From 253e67c8b3a72b3a4757fdbc5845297628db0a4a Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 19:55:15 -0400 Subject: docs: Added All NetBSD Manuals --- static/netbsd/man3/ADMISSIONS.3 | 238 + static/netbsd/man3/ASN1_EXTERN_FUNCS.3 | 226 + static/netbsd/man3/ASN1_INTEGER_get_int64.3 | 189 + static/netbsd/man3/ASN1_INTEGER_new.3 | 102 + static/netbsd/man3/ASN1_ITEM_lookup.3 | 98 + static/netbsd/man3/ASN1_OBJECT_new.3 | 109 + static/netbsd/man3/ASN1_STRING_TABLE_add.3 | 123 + static/netbsd/man3/ASN1_STRING_length.3 | 171 + static/netbsd/man3/ASN1_STRING_new.3 | 110 + static/netbsd/man3/ASN1_STRING_print_ex.3 | 173 + static/netbsd/man3/ASN1_TIME_set.3 | 346 + static/netbsd/man3/ASN1_TYPE_get.3 | 160 + static/netbsd/man3/ASN1_aux_cb.3 | 295 + static/netbsd/man3/ASN1_generate_nconf.3 | 309 + static/netbsd/man3/ASN1_item_d2i_bio.3 | 174 + static/netbsd/man3/ASN1_item_new.3 | 104 + static/netbsd/man3/ASN1_item_sign.3 | 284 + static/netbsd/man3/ASYNC_WAIT_CTX_new.3 | 276 + static/netbsd/man3/ASYNC_start_job.3 | 430 + static/netbsd/man3/BF_encrypt.3 | 190 + static/netbsd/man3/BIO_ADDR.3 | 198 + static/netbsd/man3/BIO_ADDRINFO.3 | 171 + static/netbsd/man3/BIO_connect.3 | 176 + static/netbsd/man3/BIO_ctrl.3 | 248 + static/netbsd/man3/BIO_f_base64.3 | 194 + static/netbsd/man3/BIO_f_buffer.3 | 161 + static/netbsd/man3/BIO_f_cipher.3 | 138 + static/netbsd/man3/BIO_f_md.3 | 222 + static/netbsd/man3/BIO_f_null.3 | 98 + static/netbsd/man3/BIO_f_prefix.3 | 128 + static/netbsd/man3/BIO_f_readbuffer.3 | 119 + static/netbsd/man3/BIO_f_ssl.3 | 373 + static/netbsd/man3/BIO_find_type.3 | 130 + static/netbsd/man3/BIO_get_data.3 | 129 + static/netbsd/man3/BIO_get_ex_new_index.3 | 193 + static/netbsd/man3/BIO_get_rpoll_descriptor.3 | 163 + static/netbsd/man3/BIO_meth_new.3 | 279 + static/netbsd/man3/BIO_new.3 | 138 + static/netbsd/man3/BIO_new_CMS.3 | 131 + static/netbsd/man3/BIO_parse_hostserv.3 | 142 + static/netbsd/man3/BIO_printf.3 | 116 + static/netbsd/man3/BIO_push.3 | 160 + static/netbsd/man3/BIO_read.3 | 188 + static/netbsd/man3/BIO_s_accept.3 | 315 + static/netbsd/man3/BIO_s_bio.3 | 259 + static/netbsd/man3/BIO_s_connect.3 | 293 + static/netbsd/man3/BIO_s_core.3 | 132 + static/netbsd/man3/BIO_s_datagram.3 | 294 + static/netbsd/man3/BIO_s_dgram_pair.3 | 285 + static/netbsd/man3/BIO_s_fd.3 | 157 + static/netbsd/man3/BIO_s_file.3 | 232 + static/netbsd/man3/BIO_s_mem.3 | 278 + static/netbsd/man3/BIO_s_null.3 | 103 + static/netbsd/man3/BIO_s_socket.3 | 113 + static/netbsd/man3/BIO_sendmmsg.3 | 277 + static/netbsd/man3/BIO_set_callback.3 | 380 + static/netbsd/man3/BIO_set_flags.3 | 238 + static/netbsd/man3/BIO_should_retry.3 | 203 + static/netbsd/man3/BIO_socket_wait.3 | 127 + static/netbsd/man3/BN_BLINDING_new.3 | 185 + static/netbsd/man3/BN_CTX_new.3 | 150 + static/netbsd/man3/BN_CTX_start.3 | 116 + static/netbsd/man3/BN_add.3 | 203 + static/netbsd/man3/BN_add_word.3 | 120 + static/netbsd/man3/BN_bn2bin.3 | 208 + static/netbsd/man3/BN_cmp.3 | 123 + static/netbsd/man3/BN_copy.3 | 118 + static/netbsd/man3/BN_generate_prime.3 | 309 + static/netbsd/man3/BN_mod_exp_mont.3 | 124 + static/netbsd/man3/BN_mod_inverse.3 | 103 + static/netbsd/man3/BN_mod_mul_montgomery.3 | 147 + static/netbsd/man3/BN_mod_mul_reciprocal.3 | 134 + static/netbsd/man3/BN_new.3 | 122 + static/netbsd/man3/BN_num_bytes.3 | 119 + static/netbsd/man3/BN_rand.3 | 179 + static/netbsd/man3/BN_security_bits.3 | 108 + static/netbsd/man3/BN_set_bit.3 | 131 + static/netbsd/man3/BN_swap.3 | 90 + static/netbsd/man3/BN_zero.3 | 125 + static/netbsd/man3/BUF_MEM_new.3 | 134 + static/netbsd/man3/CMAC_CTX.3 | 173 + static/netbsd/man3/CMS_EncryptedData_decrypt.3 | 126 + static/netbsd/man3/CMS_EncryptedData_encrypt.3 | 127 + static/netbsd/man3/CMS_EncryptedData_set1_key.3 | 98 + static/netbsd/man3/CMS_EnvelopedData_create.3 | 144 + static/netbsd/man3/CMS_add0_cert.3 | 142 + static/netbsd/man3/CMS_add1_recipient_cert.3 | 143 + static/netbsd/man3/CMS_add1_signer.3 | 168 + static/netbsd/man3/CMS_compress.3 | 135 + static/netbsd/man3/CMS_data_create.3 | 112 + static/netbsd/man3/CMS_decrypt.3 | 178 + static/netbsd/man3/CMS_digest_create.3 | 115 + static/netbsd/man3/CMS_encrypt.3 | 172 + static/netbsd/man3/CMS_final.3 | 118 + static/netbsd/man3/CMS_get0_RecipientInfos.3 | 212 + static/netbsd/man3/CMS_get0_SignerInfos.3 | 148 + static/netbsd/man3/CMS_get0_type.3 | 145 + static/netbsd/man3/CMS_get1_ReceiptRequest.3 | 149 + static/netbsd/man3/CMS_sign.3 | 202 + static/netbsd/man3/CMS_sign_receipt.3 | 110 + static/netbsd/man3/CMS_signed_get_attr.3 | 265 + static/netbsd/man3/CMS_uncompress.3 | 116 + static/netbsd/man3/CMS_verify.3 | 227 + static/netbsd/man3/CMS_verify_receipt.3 | 112 + static/netbsd/man3/COMP_CTX_new.3 | 225 + static/netbsd/man3/CONF_modules_free.3 | 118 + static/netbsd/man3/CONF_modules_load_file.3 | 229 + static/netbsd/man3/CRYPTO_THREAD_run_once.3 | 311 + static/netbsd/man3/CRYPTO_get_ex_new_index.3 | 240 + static/netbsd/man3/CRYPTO_memcmp.3 | 98 + static/netbsd/man3/CRYPTO_set_ex_data.3 | 185 + static/netbsd/man3/CTLOG_STORE_get0_log_by_id.3 | 107 + static/netbsd/man3/CTLOG_STORE_new.3 | 147 + static/netbsd/man3/CTLOG_new.3 | 148 + static/netbsd/man3/CT_POLICY_EVAL_CTX_new.3 | 174 + static/netbsd/man3/ChangeLog.3 | 23224 +++++++++++++++++++ static/netbsd/man3/DEFINE_STACK_OF.3 | 374 + static/netbsd/man3/DES_cbc_cksum.3 | 3 + static/netbsd/man3/DES_cbc_encrypt.3 | 3 + static/netbsd/man3/DES_cfb64_encrypt.3 | 3 + static/netbsd/man3/DES_check_key_parity.3 | 3 + static/netbsd/man3/DES_ecb3_encrypt.3 | 3 + static/netbsd/man3/DES_ecb_encrypt.3 | 3 + static/netbsd/man3/DES_ede3_cbc_encrypt.3 | 3 + static/netbsd/man3/DES_encrypt.3 | 3 + .../netbsd/man3/DES_init_random_number_generator.3 | 3 + static/netbsd/man3/DES_is_weak_key.3 | 3 + static/netbsd/man3/DES_key_sched.3 | 3 + static/netbsd/man3/DES_new_random_key.3 | 3 + static/netbsd/man3/DES_pcbc_encrypt.3 | 3 + static/netbsd/man3/DES_random_key.3 | 388 + static/netbsd/man3/DES_set_key.3 | 3 + static/netbsd/man3/DES_set_key_checked.3 | 3 + static/netbsd/man3/DES_set_key_unchecked.3 | 3 + static/netbsd/man3/DES_set_odd_parity.3 | 3 + static/netbsd/man3/DES_string_to_key.3 | 3 + static/netbsd/man3/DH_check_pubkey.3 | 3 + static/netbsd/man3/DH_compute_key.3 | 3 + static/netbsd/man3/DH_free.3 | 3 + static/netbsd/man3/DH_generate_key.3 | 142 + static/netbsd/man3/DH_generate_parameters.3 | 217 + static/netbsd/man3/DH_generate_parameters_ex.3 | 3 + static/netbsd/man3/DH_get0_pqg.3 | 210 + static/netbsd/man3/DH_get_1024_160.3 | 152 + static/netbsd/man3/DH_get_default_method.3 | 3 + static/netbsd/man3/DH_get_ex_data.3 | 3 + static/netbsd/man3/DH_get_ex_new_index.3 | 169 + static/netbsd/man3/DH_ltm_method.3 | 3 + static/netbsd/man3/DH_meth_new.3 | 238 + static/netbsd/man3/DH_new.3 | 117 + static/netbsd/man3/DH_new_by_nid.3 | 113 + static/netbsd/man3/DH_new_method.3 | 3 + static/netbsd/man3/DH_null_method.3 | 3 + static/netbsd/man3/DH_set_default_method.3 | 3 + static/netbsd/man3/DH_set_ex_data.3 | 3 + static/netbsd/man3/DH_set_method.3 | 159 + static/netbsd/man3/DH_size.3 | 129 + static/netbsd/man3/DH_up_ref.3 | 3 + static/netbsd/man3/DSA_SIG_new.3 | 118 + static/netbsd/man3/DSA_do_sign.3 | 124 + static/netbsd/man3/DSA_dup_DH.3 | 112 + static/netbsd/man3/DSA_generate_key.3 | 113 + static/netbsd/man3/DSA_generate_parameters.3 | 179 + static/netbsd/man3/DSA_get0_pqg.3 | 182 + static/netbsd/man3/DSA_get_ex_new_index.3 | 169 + static/netbsd/man3/DSA_meth_new.3 | 288 + static/netbsd/man3/DSA_new.3 | 120 + static/netbsd/man3/DSA_set_method.3 | 159 + static/netbsd/man3/DSA_sign.3 | 142 + static/netbsd/man3/DSA_size.3 | 128 + static/netbsd/man3/DTLS_get_data_mtu.3 | 95 + static/netbsd/man3/DTLS_set_timer_cb.3 | 110 + static/netbsd/man3/DTLSv1_get_timeout.3 | 117 + static/netbsd/man3/DTLSv1_handle_timeout.3 | 110 + static/netbsd/man3/DTLSv1_listen.3 | 213 + static/netbsd/man3/ECDSA_SIG_new.3 | 208 + static/netbsd/man3/ECDSA_sign.3 | 256 + static/netbsd/man3/ECPKParameters_print.3 | 115 + static/netbsd/man3/EC_GFp_simple_method.3 | 142 + static/netbsd/man3/EC_GROUP_copy.3 | 324 + static/netbsd/man3/EC_GROUP_new.3 | 304 + static/netbsd/man3/EC_KEY_get_enc_flags.3 | 118 + static/netbsd/man3/EC_KEY_new.3 | 305 + static/netbsd/man3/EC_POINT_add.3 | 160 + static/netbsd/man3/EC_POINT_new.3 | 338 + static/netbsd/man3/ENGINE_add.3 | 743 + static/netbsd/man3/ERR_GET_LIB.3 | 129 + static/netbsd/man3/ERR_clear_error.3 | 93 + static/netbsd/man3/ERR_error_string.3 | 143 + static/netbsd/man3/ERR_get_error.3 | 201 + static/netbsd/man3/ERR_load_crypto_strings.3 | 114 + static/netbsd/man3/ERR_load_strings.3 | 119 + static/netbsd/man3/ERR_new.3 | 136 + static/netbsd/man3/ERR_print_errors.3 | 120 + static/netbsd/man3/ERR_put_error.3 | 226 + static/netbsd/man3/ERR_remove_state.3 | 111 + static/netbsd/man3/ERR_set_mark.3 | 120 + static/netbsd/man3/EVP_ASYM_CIPHER_free.3 | 170 + static/netbsd/man3/EVP_BytesToKey.3 | 137 + static/netbsd/man3/EVP_CIPHER_CTX_block_size.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_cipher.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_cleanup.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_ctrl.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_flags.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_get_app_data.3 | 98 + .../netbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 | 110 + .../netbsd/man3/EVP_CIPHER_CTX_get_original_iv.3 | 135 + static/netbsd/man3/EVP_CIPHER_CTX_init.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_iv_length.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_key_length.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_mode.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_rand_key.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_set_app_data.3 | 3 + static/netbsd/man3/EVP_CIPHER_CTX_set_key_length.3 | 3 + static/netbsd/man3/EVP_CIPHER_block_size.3 | 3 + static/netbsd/man3/EVP_CIPHER_iv_length.3 | 3 + static/netbsd/man3/EVP_CIPHER_key_length.3 | 3 + static/netbsd/man3/EVP_CIPHER_meth_new.3 | 298 + static/netbsd/man3/EVP_CipherFinal_ex.3 | 3 + static/netbsd/man3/EVP_CipherInit_ex.3 | 3 + static/netbsd/man3/EVP_CipherUpdate.3 | 3 + static/netbsd/man3/EVP_Digest.3 | 3 + static/netbsd/man3/EVP_DigestFinal_ex.3 | 3 + static/netbsd/man3/EVP_DigestInit.3 | 807 + static/netbsd/man3/EVP_DigestInit_ex.3 | 3 + static/netbsd/man3/EVP_DigestSignInit.3 | 266 + static/netbsd/man3/EVP_DigestUpdate.3 | 3 + static/netbsd/man3/EVP_DigestVerifyInit.3 | 251 + static/netbsd/man3/EVP_EncodeInit.3 | 252 + static/netbsd/man3/EVP_EncryptInit.3 | 1827 ++ static/netbsd/man3/EVP_KDF.3 | 353 + static/netbsd/man3/EVP_KEM_free.3 | 164 + static/netbsd/man3/EVP_KEYEXCH_free.3 | 169 + static/netbsd/man3/EVP_KEYMGMT.3 | 212 + static/netbsd/man3/EVP_MAC.3 | 551 + static/netbsd/man3/EVP_MD_CTX_block_size.3 | 3 + static/netbsd/man3/EVP_MD_CTX_cleanup.3 | 3 + static/netbsd/man3/EVP_MD_CTX_create.3 | 3 + static/netbsd/man3/EVP_MD_CTX_destroy.3 | 3 + static/netbsd/man3/EVP_MD_CTX_init.3 | 3 + static/netbsd/man3/EVP_MD_CTX_md.3 | 3 + static/netbsd/man3/EVP_MD_CTX_size.3 | 3 + static/netbsd/man3/EVP_MD_block_size.3 | 3 + static/netbsd/man3/EVP_MD_meth_new.3 | 255 + static/netbsd/man3/EVP_MD_size.3 | 3 + static/netbsd/man3/EVP_OpenInit.3 | 127 + static/netbsd/man3/EVP_PBE_CipherInit.3 | 156 + static/netbsd/man3/EVP_PKEY2PKCS8.3 | 106 + static/netbsd/man3/EVP_PKEY_ASN1_METHOD.3 | 519 + static/netbsd/man3/EVP_PKEY_CTX_ctrl.3 | 747 + static/netbsd/man3/EVP_PKEY_CTX_get0_libctx.3 | 112 + static/netbsd/man3/EVP_PKEY_CTX_get0_pkey.3 | 115 + static/netbsd/man3/EVP_PKEY_CTX_get_algor.3 | 125 + static/netbsd/man3/EVP_PKEY_CTX_new.3 | 185 + static/netbsd/man3/EVP_PKEY_CTX_set1_pbe_pass.3 | 112 + static/netbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 | 220 + static/netbsd/man3/EVP_PKEY_CTX_set_params.3 | 157 + .../man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.3 | 163 + static/netbsd/man3/EVP_PKEY_CTX_set_scrypt_N.3 | 148 + static/netbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 | 171 + static/netbsd/man3/EVP_PKEY_asn1_get_count.3 | 139 + static/netbsd/man3/EVP_PKEY_check.3 | 158 + static/netbsd/man3/EVP_PKEY_cmp.3 | 208 + static/netbsd/man3/EVP_PKEY_copy_parameters.3 | 163 + static/netbsd/man3/EVP_PKEY_decapsulate.3 | 193 + static/netbsd/man3/EVP_PKEY_decrypt.3 | 193 + static/netbsd/man3/EVP_PKEY_derive.3 | 182 + .../man3/EVP_PKEY_digestsign_supports_digest.3 | 102 + static/netbsd/man3/EVP_PKEY_encapsulate.3 | 202 + static/netbsd/man3/EVP_PKEY_encrypt.3 | 176 + static/netbsd/man3/EVP_PKEY_fromdata.3 | 336 + static/netbsd/man3/EVP_PKEY_get_attr.3 | 171 + static/netbsd/man3/EVP_PKEY_get_default_digest.3 | 172 + .../netbsd/man3/EVP_PKEY_get_default_digest_nid.3 | 124 + static/netbsd/man3/EVP_PKEY_get_field_type.3 | 112 + static/netbsd/man3/EVP_PKEY_get_group_name.3 | 104 + static/netbsd/man3/EVP_PKEY_get_size.3 | 152 + static/netbsd/man3/EVP_PKEY_gettable_params.3 | 193 + static/netbsd/man3/EVP_PKEY_is_a.3 | 174 + static/netbsd/man3/EVP_PKEY_keygen.3 | 313 + static/netbsd/man3/EVP_PKEY_meth_get_count.3 | 121 + static/netbsd/man3/EVP_PKEY_meth_new.3 | 557 + static/netbsd/man3/EVP_PKEY_new.3 | 352 + static/netbsd/man3/EVP_PKEY_print_private.3 | 134 + static/netbsd/man3/EVP_PKEY_set1_RSA.3 | 296 + .../netbsd/man3/EVP_PKEY_set1_encoded_public_key.3 | 217 + static/netbsd/man3/EVP_PKEY_set_type.3 | 127 + static/netbsd/man3/EVP_PKEY_settable_params.3 | 138 + static/netbsd/man3/EVP_PKEY_sign.3 | 411 + static/netbsd/man3/EVP_PKEY_todata.3 | 131 + static/netbsd/man3/EVP_PKEY_verify.3 | 400 + static/netbsd/man3/EVP_PKEY_verify_recover.3 | 200 + static/netbsd/man3/EVP_RAND.3 | 454 + static/netbsd/man3/EVP_SIGNATURE.3 | 174 + static/netbsd/man3/EVP_SKEY.3 | 212 + static/netbsd/man3/EVP_SKEYMGMT.3 | 208 + static/netbsd/man3/EVP_SealInit.3 | 150 + static/netbsd/man3/EVP_SignInit.3 | 175 + static/netbsd/man3/EVP_VerifyInit.3 | 170 + static/netbsd/man3/EVP_aes.3 | 272 + static/netbsd/man3/EVP_aes_128_cbc.3 | 3 + static/netbsd/man3/EVP_aes_128_cfb8.3 | 3 + static/netbsd/man3/EVP_aes_128_gcm.3 | 201 + static/netbsd/man3/EVP_aes_192_cbc.3 | 3 + static/netbsd/man3/EVP_aes_192_cfb8.3 | 3 + static/netbsd/man3/EVP_aes_256_cbc.3 | 3 + static/netbsd/man3/EVP_aes_256_cfb8.3 | 3 + static/netbsd/man3/EVP_aria.3 | 216 + static/netbsd/man3/EVP_aria_128_gcm.3 | 145 + static/netbsd/man3/EVP_bf_cbc.3 | 117 + static/netbsd/man3/EVP_blake2b512.3 | 119 + static/netbsd/man3/EVP_camellia.3 | 205 + static/netbsd/man3/EVP_camellia_128_cbc.3 | 3 + static/netbsd/man3/EVP_camellia_128_ecb.3 | 134 + static/netbsd/man3/EVP_camellia_192_cbc.3 | 3 + static/netbsd/man3/EVP_camellia_256_cbc.3 | 3 + static/netbsd/man3/EVP_cast5_cbc.3 | 117 + static/netbsd/man3/EVP_chacha20.3 | 126 + static/netbsd/man3/EVP_des.3 | 213 + static/netbsd/man3/EVP_des_cbc.3 | 146 + static/netbsd/man3/EVP_des_ede3_cbc.3 | 3 + static/netbsd/man3/EVP_desx_cbc.3 | 112 + static/netbsd/man3/EVP_enc_null.3 | 3 + static/netbsd/man3/EVP_get_cipherbyname.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_128_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_128_cfb8.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_192_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_192_cfb8.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_256_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_aes_256_cfb8.3 | 3 + static/netbsd/man3/EVP_hcrypto_camellia_128_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_camellia_192_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_camellia_256_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_des_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_des_ede3_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_md4.3 | 3 + static/netbsd/man3/EVP_hcrypto_md5.3 | 3 + static/netbsd/man3/EVP_hcrypto_rc2_40_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_rc2_64_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_rc2_cbc.3 | 3 + static/netbsd/man3/EVP_hcrypto_sha1.3 | 3 + static/netbsd/man3/EVP_hcrypto_sha256.3 | 3 + static/netbsd/man3/EVP_hcrypto_sha384.3 | 3 + static/netbsd/man3/EVP_hcrypto_sha512.3 | 3 + static/netbsd/man3/EVP_idea_cbc.3 | 115 + static/netbsd/man3/EVP_md2.3 | 111 + static/netbsd/man3/EVP_md4.3 | 112 + static/netbsd/man3/EVP_md5.3 | 121 + static/netbsd/man3/EVP_md_null.3 | 3 + static/netbsd/man3/EVP_mdc2.3 | 113 + static/netbsd/man3/EVP_rc2_40_cbc.3 | 3 + static/netbsd/man3/EVP_rc2_64_cbc.3 | 3 + static/netbsd/man3/EVP_rc2_cbc.3 | 129 + static/netbsd/man3/EVP_rc4.3 | 125 + static/netbsd/man3/EVP_rc4_40.3 | 3 + static/netbsd/man3/EVP_rc5_32_12_16_cbc.3 | 134 + static/netbsd/man3/EVP_ripemd160.3 | 112 + static/netbsd/man3/EVP_seed_cbc.3 | 117 + static/netbsd/man3/EVP_set_default_properties.3 | 143 + static/netbsd/man3/EVP_sha.3 | 3 + static/netbsd/man3/EVP_sha1.3 | 111 + static/netbsd/man3/EVP_sha224.3 | 126 + static/netbsd/man3/EVP_sha256.3 | 3 + static/netbsd/man3/EVP_sha384.3 | 3 + static/netbsd/man3/EVP_sha3_224.3 | 131 + static/netbsd/man3/EVP_sha512.3 | 3 + static/netbsd/man3/EVP_sm3.3 | 111 + static/netbsd/man3/EVP_sm4_cbc.3 | 121 + static/netbsd/man3/EVP_whirlpool.3 | 113 + static/netbsd/man3/EVP_wincrypt_des_ede3_cbc.3 | 3 + static/netbsd/man3/GENERAL_NAME.3 | 100 + static/netbsd/man3/HDB.3 | 176 + static/netbsd/man3/HMAC.3 | 93 + static/netbsd/man3/MD5.3 | 170 + static/netbsd/man3/MDC2_Init.3 | 139 + static/netbsd/man3/NCONF_new_ex.3 | 142 + static/netbsd/man3/OBJ_nid2obj.3 | 272 + static/netbsd/man3/OCSP_REQUEST_new.3 | 178 + static/netbsd/man3/OCSP_cert_to_id.3 | 147 + static/netbsd/man3/OCSP_request_add1_nonce.3 | 142 + static/netbsd/man3/OCSP_resp_find_status.3 | 278 + static/netbsd/man3/OCSP_response_status.3 | 191 + static/netbsd/man3/OCSP_sendreq_new.3 | 189 + static/netbsd/man3/OPENSSL_Applink.3 | 95 + static/netbsd/man3/OPENSSL_FILE.3 | 114 + static/netbsd/man3/OPENSSL_LH_COMPFUNC.3 | 405 + static/netbsd/man3/OPENSSL_LH_stats.3 | 139 + static/netbsd/man3/OPENSSL_VERSION_NUMBER.3 | 247 + static/netbsd/man3/OPENSSL_config.3 | 141 + static/netbsd/man3/OPENSSL_fork_prepare.3 | 130 + static/netbsd/man3/OPENSSL_gmtime.3 | 120 + static/netbsd/man3/OPENSSL_hexchar2int.3 | 141 + static/netbsd/man3/OPENSSL_ia32cap.3 | 273 + static/netbsd/man3/OPENSSL_init_crypto.3 | 336 + static/netbsd/man3/OPENSSL_init_ssl.3 | 136 + static/netbsd/man3/OPENSSL_instrument_bus.3 | 113 + static/netbsd/man3/OPENSSL_load_builtin_modules.3 | 117 + static/netbsd/man3/OPENSSL_load_u16_le.3 | 143 + static/netbsd/man3/OPENSSL_malloc.3 | 323 + static/netbsd/man3/OPENSSL_ppccap.3 | 208 + static/netbsd/man3/OPENSSL_riscvcap.3 | 256 + static/netbsd/man3/OPENSSL_s390xcap.3 | 271 + static/netbsd/man3/OPENSSL_secure_malloc.3 | 208 + static/netbsd/man3/OPENSSL_strcasecmp.3 | 109 + static/netbsd/man3/OSSL_ALGORITHM.3 | 187 + static/netbsd/man3/OSSL_CALLBACK.3 | 124 + static/netbsd/man3/OSSL_CIPHER_ALGORITHM.3 | 3 + static/netbsd/man3/OSSL_CMP_ATAV_set0.3 | 175 + static/netbsd/man3/OSSL_CMP_CTX_new.3 | 947 + .../netbsd/man3/OSSL_CMP_HDR_get0_transactionID.3 | 113 + static/netbsd/man3/OSSL_CMP_ITAV_new_caCerts.3 | 272 + static/netbsd/man3/OSSL_CMP_ITAV_set0.3 | 191 + static/netbsd/man3/OSSL_CMP_MSG_get0_header.3 | 214 + static/netbsd/man3/OSSL_CMP_MSG_http_perform.3 | 130 + static/netbsd/man3/OSSL_CMP_SRV_CTX_new.3 | 256 + static/netbsd/man3/OSSL_CMP_STATUSINFO_new.3 | 124 + static/netbsd/man3/OSSL_CMP_exec_certreq.3 | 320 + static/netbsd/man3/OSSL_CMP_log_open.3 | 185 + static/netbsd/man3/OSSL_CMP_validate_msg.3 | 146 + static/netbsd/man3/OSSL_CORE_MAKE_FUNC.3 | 102 + static/netbsd/man3/OSSL_CRMF_MSG_get0_tmpl.3 | 226 + static/netbsd/man3/OSSL_CRMF_MSG_set0_validity.3 | 174 + .../man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.3 | 188 + .../man3/OSSL_CRMF_MSG_set1_regInfo_certReq.3 | 125 + static/netbsd/man3/OSSL_CRMF_pbmp_new.3 | 151 + static/netbsd/man3/OSSL_DECODER.3 | 249 + static/netbsd/man3/OSSL_DECODER_CTX.3 | 316 + static/netbsd/man3/OSSL_DECODER_CTX_new_for_pkey.3 | 204 + static/netbsd/man3/OSSL_DECODER_from_bio.3 | 176 + static/netbsd/man3/OSSL_DISPATCH.3 | 125 + static/netbsd/man3/OSSL_ENCODER.3 | 203 + static/netbsd/man3/OSSL_ENCODER_CTX.3 | 284 + static/netbsd/man3/OSSL_ENCODER_CTX_new_for_pkey.3 | 202 + static/netbsd/man3/OSSL_ENCODER_to_bio.3 | 187 + static/netbsd/man3/OSSL_ERR_STATE_save.3 | 144 + static/netbsd/man3/OSSL_ESS_check_signing_certs.3 | 145 + static/netbsd/man3/OSSL_GENERAL_NAMES_print.3 | 95 + static/netbsd/man3/OSSL_HPKE_CTX_new.3 | 599 + static/netbsd/man3/OSSL_HTTP_REQ_CTX.3 | 357 + static/netbsd/man3/OSSL_HTTP_parse_url.3 | 172 + static/netbsd/man3/OSSL_HTTP_transfer.3 | 346 + static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX.3 | 149 + static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX_print.3 | 99 + static/netbsd/man3/OSSL_INDICATOR_set_callback.3 | 141 + static/netbsd/man3/OSSL_ITEM.3 | 105 + static/netbsd/man3/OSSL_LIB_CTX.3 | 211 + .../man3/OSSL_LIB_CTX_set_conf_diagnostics.3 | 111 + static/netbsd/man3/OSSL_PARAM.3 | 393 + static/netbsd/man3/OSSL_PARAM_BLD.3 | 266 + static/netbsd/man3/OSSL_PARAM_allocate_from_text.3 | 257 + static/netbsd/man3/OSSL_PARAM_dup.3 | 118 + static/netbsd/man3/OSSL_PARAM_int.3 | 470 + static/netbsd/man3/OSSL_PARAM_print_to_bio.3 | 101 + static/netbsd/man3/OSSL_PROVIDER.3 | 349 + static/netbsd/man3/OSSL_QUIC_client_method.3 | 115 + static/netbsd/man3/OSSL_SELF_TEST_new.3 | 214 + static/netbsd/man3/OSSL_SELF_TEST_set_callback.3 | 110 + static/netbsd/man3/OSSL_STORE_INFO.3 | 277 + static/netbsd/man3/OSSL_STORE_LOADER.3 | 434 + static/netbsd/man3/OSSL_STORE_SEARCH.3 | 240 + static/netbsd/man3/OSSL_STORE_attach.3 | 105 + static/netbsd/man3/OSSL_STORE_expect.3 | 138 + static/netbsd/man3/OSSL_STORE_open.3 | 244 + static/netbsd/man3/OSSL_sleep.3 | 101 + static/netbsd/man3/OSSL_trace_enabled.3 | 393 + static/netbsd/man3/OSSL_trace_get_category_num.3 | 103 + static/netbsd/man3/OSSL_trace_set_channel.3 | 376 + static/netbsd/man3/OpenSSL_add_all_algorithms.3 | 123 + .../netbsd/man3/OpenSSL_add_all_algorithms_conf.3 | 3 + .../man3/OpenSSL_add_all_algorithms_noconf.3 | 3 + static/netbsd/man3/OpenSSL_version.3 | 297 + static/netbsd/man3/PBMAC1_get1_pbkdf2_param.3 | 103 + static/netbsd/man3/PEM_X509_INFO_read_bio_ex.3 | 141 + static/netbsd/man3/PEM_bytes_read_bio.3 | 143 + static/netbsd/man3/PEM_read.3 | 214 + static/netbsd/man3/PEM_read_CMS.3 | 209 + static/netbsd/man3/PEM_read_bio_PrivateKey.3 | 684 + static/netbsd/man3/PEM_read_bio_ex.3 | 127 + static/netbsd/man3/PEM_write_bio_CMS_stream.3 | 107 + static/netbsd/man3/PEM_write_bio_PKCS7_stream.3 | 106 + static/netbsd/man3/PKCS12_PBE_keyivgen.3 | 164 + static/netbsd/man3/PKCS12_SAFEBAG_create_cert.3 | 156 + static/netbsd/man3/PKCS12_SAFEBAG_get0_attrs.3 | 109 + static/netbsd/man3/PKCS12_SAFEBAG_get1_cert.3 | 147 + static/netbsd/man3/PKCS12_SAFEBAG_set0_attrs.3 | 95 + static/netbsd/man3/PKCS12_add1_attr_by_NID.3 | 110 + static/netbsd/man3/PKCS12_add_CSPName_asc.3 | 95 + static/netbsd/man3/PKCS12_add_cert.3 | 137 + static/netbsd/man3/PKCS12_add_friendlyname_asc.3 | 111 + static/netbsd/man3/PKCS12_add_localkeyid.3 | 97 + static/netbsd/man3/PKCS12_add_safe.3 | 139 + static/netbsd/man3/PKCS12_create.3 | 193 + static/netbsd/man3/PKCS12_decrypt_skey.3 | 112 + static/netbsd/man3/PKCS12_gen_mac.3 | 151 + static/netbsd/man3/PKCS12_get_friendlyname.3 | 98 + static/netbsd/man3/PKCS12_init.3 | 106 + static/netbsd/man3/PKCS12_item_decrypt_d2i.3 | 131 + static/netbsd/man3/PKCS12_key_gen_utf8_ex.3 | 174 + static/netbsd/man3/PKCS12_newpass.3 | 171 + static/netbsd/man3/PKCS12_pack_p7encdata.3 | 116 + static/netbsd/man3/PKCS12_parse.3 | 134 + static/netbsd/man3/PKCS5_PBE_keyivgen.3 | 251 + static/netbsd/man3/PKCS5_PBKDF2_HMAC.3 | 135 + static/netbsd/man3/PKCS5_PBKDF2_HMAC_SHA1.3 | 3 + static/netbsd/man3/PKCS7_decrypt.3 | 114 + static/netbsd/man3/PKCS7_encrypt.3 | 154 + static/netbsd/man3/PKCS7_get_octet_string.3 | 98 + static/netbsd/man3/PKCS7_sign.3 | 189 + static/netbsd/man3/PKCS7_sign_add_signer.3 | 166 + static/netbsd/man3/PKCS7_type_is_other.3 | 101 + static/netbsd/man3/PKCS7_verify.3 | 199 + static/netbsd/man3/PKCS8_encrypt.3 | 135 + static/netbsd/man3/PKCS8_pkey_add1_attr.3 | 112 + static/netbsd/man3/RAND_DRBG_generate.3 | 220 + static/netbsd/man3/RAND_DRBG_get0_master.3 | 211 + static/netbsd/man3/RAND_DRBG_new.3 | 258 + static/netbsd/man3/RAND_DRBG_reseed.3 | 247 + static/netbsd/man3/RAND_DRBG_set_callbacks.3 | 277 + static/netbsd/man3/RAND_DRBG_set_ex_data.3 | 200 + static/netbsd/man3/RAND_add.3 | 171 + static/netbsd/man3/RAND_bytes.3 | 173 + static/netbsd/man3/RAND_cleanup.3 | 106 + static/netbsd/man3/RAND_egd.3 | 120 + static/netbsd/man3/RAND_file_name.3 | 3 + static/netbsd/man3/RAND_get0_primary.3 | 152 + static/netbsd/man3/RAND_get_rand_method.3 | 3 + static/netbsd/man3/RAND_load_file.3 | 149 + static/netbsd/man3/RAND_pseudo_bytes.3 | 3 + static/netbsd/man3/RAND_seed.3 | 3 + static/netbsd/man3/RAND_set_DRBG_type.3 | 130 + static/netbsd/man3/RAND_set_rand_engine.3 | 3 + static/netbsd/man3/RAND_set_rand_method.3 | 147 + static/netbsd/man3/RAND_status.3 | 3 + static/netbsd/man3/RAND_write_file.3 | 3 + static/netbsd/man3/RC4_set_key.3 | 137 + static/netbsd/man3/RELEASE_NOTES-2.3 | 761 + static/netbsd/man3/RELEASE_NOTES-3.3 | 124 + static/netbsd/man3/RIPEMD160_Init.3 | 141 + static/netbsd/man3/RSA_blinding_on.3 | 114 + static/netbsd/man3/RSA_check_key.3 | 152 + static/netbsd/man3/RSA_free.3 | 3 + static/netbsd/man3/RSA_generate_key.3 | 178 + static/netbsd/man3/RSA_get0_key.3 | 253 + static/netbsd/man3/RSA_get_app_data.3 | 3 + static/netbsd/man3/RSA_get_ex_new_index.3 | 251 + static/netbsd/man3/RSA_get_method.3 | 3 + static/netbsd/man3/RSA_meth_new.3 | 331 + static/netbsd/man3/RSA_new.3 | 116 + static/netbsd/man3/RSA_new_method.3 | 3 + static/netbsd/man3/RSA_padding_add_PKCS1_type_1.3 | 214 + static/netbsd/man3/RSA_print.3 | 143 + static/netbsd/man3/RSA_private_encrypt.3 | 142 + static/netbsd/man3/RSA_public_encrypt.3 | 182 + static/netbsd/man3/RSA_set_app_data.3 | 3 + static/netbsd/man3/RSA_set_method.3 | 249 + static/netbsd/man3/RSA_sign.3 | 136 + static/netbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 | 137 + static/netbsd/man3/RSA_size.3 | 125 + static/netbsd/man3/RSA_up_ref.3 | 3 + static/netbsd/man3/SCT_new.3 | 249 + static/netbsd/man3/SCT_print.3 | 115 + static/netbsd/man3/SCT_validate.3 | 151 + static/netbsd/man3/SHA256_Init.3 | 176 + static/netbsd/man3/SHA3_Selftest.3 | 73 + static/netbsd/man3/SHAKE.3 | 114 + static/netbsd/man3/SMIME_read_ASN1.3 | 142 + static/netbsd/man3/SMIME_read_CMS.3 | 150 + static/netbsd/man3/SMIME_read_PKCS7.3 | 146 + static/netbsd/man3/SMIME_write_ASN1.3 | 140 + static/netbsd/man3/SMIME_write_CMS.3 | 126 + static/netbsd/man3/SMIME_write_PKCS7.3 | 127 + static/netbsd/man3/SQLITE_ACCESS_EXISTS.3 | 40 + .../man3/SQLITE_CHANGESETAPPLY_NOSAVEPOINT.3 | 65 + static/netbsd/man3/SQLITE_CHANGESETSTART_INVERT.3 | 26 + static/netbsd/man3/SQLITE_CHANGESET_DATA.3 | 74 + static/netbsd/man3/SQLITE_CHANGESET_OMIT.3 | 49 + static/netbsd/man3/SQLITE_CHECKPOINT_PASSIVE.3 | 35 + static/netbsd/man3/SQLITE_CONFIG_SINGLETHREAD.3 | 513 + static/netbsd/man3/SQLITE_CREATE_INDEX.3 | 136 + static/netbsd/man3/SQLITE_DBCONFIG_LOOKASIDE.3 | 115 + static/netbsd/man3/SQLITE_DBCONFIG_MAINDBNAME.3 | 405 + .../netbsd/man3/SQLITE_DBSTATUS_LOOKASIDE_USED.3 | 158 + static/netbsd/man3/SQLITE_DENY.3 | 34 + .../netbsd/man3/SQLITE_DESERIALIZE_FREEONCLOSE.3 | 46 + static/netbsd/man3/SQLITE_DETERMINISTIC.3 | 129 + static/netbsd/man3/SQLITE_ERROR_MISSING_COLLSEQ.3 | 262 + static/netbsd/man3/SQLITE_FCNTL_LOCKSTATE.3 | 519 + static/netbsd/man3/SQLITE_INDEX_CONSTRAINT_EQ.3 | 105 + static/netbsd/man3/SQLITE_INDEX_SCAN_UNIQUE.3 | 20 + static/netbsd/man3/SQLITE_INTEGER.3 | 55 + static/netbsd/man3/SQLITE_IOCAP_ATOMIC.3 | 89 + static/netbsd/man3/SQLITE_IOERR_READ.3 | 136 + static/netbsd/man3/SQLITE_LIMIT_LENGTH.3 | 94 + static/netbsd/man3/SQLITE_LOCK_NONE.3 | 37 + static/netbsd/man3/SQLITE_MUTEX_FAST.3 | 71 + static/netbsd/man3/SQLITE_OK.3 | 115 + static/netbsd/man3/SQLITE_OPEN_READONLY.3 | 102 + static/netbsd/man3/SQLITE_PREPARE_PERSISTENT.3 | 66 + static/netbsd/man3/SQLITE_ROLLBACK.3 | 38 + static/netbsd/man3/SQLITE_SCANSTAT_COMPLEX.3 | 16 + static/netbsd/man3/SQLITE_SCANSTAT_NLOOP.3 | 95 + static/netbsd/man3/SQLITE_SERIALIZE_NOCOPY.3 | 33 + .../netbsd/man3/SQLITE_SESSION_CONFIG_STRMSIZE.3 | 16 + static/netbsd/man3/SQLITE_SESSION_OBJCONFIG_SIZE.3 | 49 + static/netbsd/man3/SQLITE_SHM_NLOCK.3 | 22 + static/netbsd/man3/SQLITE_SHM_UNLOCK.3 | 48 + static/netbsd/man3/SQLITE_STATUS_MEMORY_USED.3 | 111 + .../netbsd/man3/SQLITE_STMTSTATUS_FULLSCAN_STEP.3 | 99 + static/netbsd/man3/SQLITE_SYNC_NORMAL.3 | 47 + static/netbsd/man3/SQLITE_TESTCTRL_FIRST.3 | 131 + static/netbsd/man3/SQLITE_TRACE_STMT.3 | 81 + static/netbsd/man3/SQLITE_TXN_NONE.3 | 47 + static/netbsd/man3/SQLITE_UTF8.3 | 33 + static/netbsd/man3/SQLITE_VERSION.3 | 46 + .../netbsd/man3/SQLITE_VTAB_CONSTRAINT_SUPPORT.3 | 90 + .../netbsd/man3/SQLITE_WIN32_DATA_DIRECTORY_TYPE.3 | 24 + static/netbsd/man3/SRP_Calc_B.3 | 160 + static/netbsd/man3/SRP_VBASE_new.3 | 168 + static/netbsd/man3/SRP_create_verifier.3 | 200 + static/netbsd/man3/SRP_user_pwd_new.3 | 137 + static/netbsd/man3/SSL_CIPHER_get_name.3 | 267 + .../netbsd/man3/SSL_COMP_add_compression_method.3 | 170 + static/netbsd/man3/SSL_CONF_CTX_new.3 | 109 + static/netbsd/man3/SSL_CONF_CTX_set1_prefix.3 | 116 + static/netbsd/man3/SSL_CONF_CTX_set_flags.3 | 133 + static/netbsd/man3/SSL_CONF_CTX_set_ssl_ctx.3 | 122 + static/netbsd/man3/SSL_CONF_cmd.3 | 898 + static/netbsd/man3/SSL_CONF_cmd_argv.3 | 110 + static/netbsd/man3/SSL_CTX_add1_chain_cert.3 | 219 + static/netbsd/man3/SSL_CTX_add_extra_chain_cert.3 | 151 + static/netbsd/man3/SSL_CTX_add_session.3 | 127 + static/netbsd/man3/SSL_CTX_config.3 | 151 + static/netbsd/man3/SSL_CTX_ctrl.3 | 102 + static/netbsd/man3/SSL_CTX_dane_enable.3 | 444 + static/netbsd/man3/SSL_CTX_flush_sessions.3 | 129 + static/netbsd/man3/SSL_CTX_free.3 | 109 + static/netbsd/man3/SSL_CTX_get0_param.3 | 139 + static/netbsd/man3/SSL_CTX_get_ex_new_index.3 | 187 + static/netbsd/man3/SSL_CTX_get_verify_mode.3 | 118 + static/netbsd/man3/SSL_CTX_has_client_custom_ext.3 | 96 + static/netbsd/man3/SSL_CTX_load_verify_locations.3 | 237 + static/netbsd/man3/SSL_CTX_new.3 | 299 + static/netbsd/man3/SSL_CTX_sess_number.3 | 144 + static/netbsd/man3/SSL_CTX_sess_set_cache_size.3 | 120 + static/netbsd/man3/SSL_CTX_sess_set_get_cb.3 | 181 + static/netbsd/man3/SSL_CTX_sessions.3 | 105 + static/netbsd/man3/SSL_CTX_set0_CA_list.3 | 247 + .../man3/SSL_CTX_set1_cert_comp_preference.3 | 208 + static/netbsd/man3/SSL_CTX_set1_curves.3 | 470 + static/netbsd/man3/SSL_CTX_set1_sigalgs.3 | 189 + .../netbsd/man3/SSL_CTX_set1_verify_cert_store.3 | 172 + static/netbsd/man3/SSL_CTX_set_alpn_select_cb.3 | 259 + static/netbsd/man3/SSL_CTX_set_cert_cb.3 | 138 + static/netbsd/man3/SSL_CTX_set_cert_store.3 | 148 + .../netbsd/man3/SSL_CTX_set_cert_verify_callback.3 | 167 + static/netbsd/man3/SSL_CTX_set_cipher_list.3 | 188 + static/netbsd/man3/SSL_CTX_set_client_CA_list.3 | 228 + static/netbsd/man3/SSL_CTX_set_client_cert_cb.3 | 167 + static/netbsd/man3/SSL_CTX_set_client_hello_cb.3 | 215 + .../man3/SSL_CTX_set_ct_validation_callback.3 | 202 + static/netbsd/man3/SSL_CTX_set_ctlog_list_file.3 | 111 + static/netbsd/man3/SSL_CTX_set_custom_cli_ext.3 | 264 + static/netbsd/man3/SSL_CTX_set_default_passwd_cb.3 | 171 + static/netbsd/man3/SSL_CTX_set_domain_flags.3 | 169 + static/netbsd/man3/SSL_CTX_set_ex_data.3 | 188 + .../netbsd/man3/SSL_CTX_set_generate_session_id.3 | 196 + static/netbsd/man3/SSL_CTX_set_info_callback.3 | 220 + static/netbsd/man3/SSL_CTX_set_keylog_callback.3 | 111 + static/netbsd/man3/SSL_CTX_set_max_cert_list.3 | 140 + static/netbsd/man3/SSL_CTX_set_min_proto_version.3 | 135 + static/netbsd/man3/SSL_CTX_set_mode.3 | 196 + static/netbsd/man3/SSL_CTX_set_msg_callback.3 | 227 + .../netbsd/man3/SSL_CTX_set_new_pending_conn_cb.3 | 128 + static/netbsd/man3/SSL_CTX_set_num_tickets.3 | 154 + static/netbsd/man3/SSL_CTX_set_options.3 | 555 + .../netbsd/man3/SSL_CTX_set_psk_client_callback.3 | 236 + static/netbsd/man3/SSL_CTX_set_quiet_shutdown.3 | 134 + static/netbsd/man3/SSL_CTX_set_read_ahead.3 | 135 + .../man3/SSL_CTX_set_record_padding_callback.3 | 176 + static/netbsd/man3/SSL_CTX_set_security_level.3 | 234 + .../netbsd/man3/SSL_CTX_set_session_cache_mode.3 | 190 + .../netbsd/man3/SSL_CTX_set_session_id_context.3 | 142 + static/netbsd/man3/SSL_CTX_set_session_ticket_cb.3 | 232 + .../netbsd/man3/SSL_CTX_set_split_send_fragment.3 | 245 + static/netbsd/man3/SSL_CTX_set_srp_password.3 | 287 + static/netbsd/man3/SSL_CTX_set_ssl_version.3 | 143 + .../SSL_CTX_set_stateless_cookie_generate_cb.3 | 154 + static/netbsd/man3/SSL_CTX_set_timeout.3 | 136 + .../man3/SSL_CTX_set_tlsext_servername_callback.3 | 214 + static/netbsd/man3/SSL_CTX_set_tlsext_status_cb.3 | 185 + .../netbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 | 302 + static/netbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 | 191 + static/netbsd/man3/SSL_CTX_set_tmp_dh_callback.3 | 185 + static/netbsd/man3/SSL_CTX_set_tmp_ecdh.3 | 109 + static/netbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 | 292 + static/netbsd/man3/SSL_CTX_set_verify.3 | 427 + static/netbsd/man3/SSL_CTX_use_certificate.3 | 264 + static/netbsd/man3/SSL_CTX_use_psk_identity_hint.3 | 206 + static/netbsd/man3/SSL_CTX_use_serverinfo.3 | 148 + static/netbsd/man3/SSL_SESSION_free.3 | 146 + static/netbsd/man3/SSL_SESSION_get0_cipher.3 | 116 + static/netbsd/man3/SSL_SESSION_get0_hostname.3 | 133 + static/netbsd/man3/SSL_SESSION_get0_id_context.3 | 114 + static/netbsd/man3/SSL_SESSION_get0_peer.3 | 97 + static/netbsd/man3/SSL_SESSION_get_compress_id.3 | 98 + static/netbsd/man3/SSL_SESSION_get_ex_data.3 | 183 + static/netbsd/man3/SSL_SESSION_get_ex_new_index.3 | 194 + .../netbsd/man3/SSL_SESSION_get_protocol_version.3 | 114 + static/netbsd/man3/SSL_SESSION_get_time.3 | 160 + static/netbsd/man3/SSL_SESSION_has_ticket.3 | 117 + static/netbsd/man3/SSL_SESSION_is_resumable.3 | 102 + static/netbsd/man3/SSL_SESSION_print.3 | 106 + static/netbsd/man3/SSL_SESSION_set1_id.3 | 108 + static/netbsd/man3/SSL_accept.3 | 132 + static/netbsd/man3/SSL_accept_stream.3 | 139 + static/netbsd/man3/SSL_alert_type_string.3 | 267 + static/netbsd/man3/SSL_alloc_buffers.3 | 124 + static/netbsd/man3/SSL_check_chain.3 | 152 + static/netbsd/man3/SSL_clear.3 | 138 + static/netbsd/man3/SSL_connect.3 | 147 + static/netbsd/man3/SSL_do_handshake.3 | 131 + static/netbsd/man3/SSL_export_keying_material.3 | 149 + static/netbsd/man3/SSL_extension_supported.3 | 336 + static/netbsd/man3/SSL_free.3 | 137 + static/netbsd/man3/SSL_get0_connection.3 | 112 + static/netbsd/man3/SSL_get0_group_name.3 | 105 + static/netbsd/man3/SSL_get0_peer_rpk.3 | 154 + static/netbsd/man3/SSL_get0_peer_scts.3 | 103 + static/netbsd/man3/SSL_get1_builtin_sigalgs.3 | 100 + static/netbsd/man3/SSL_get_SSL_CTX.3 | 94 + static/netbsd/man3/SSL_get_all_async_fds.3 | 144 + static/netbsd/man3/SSL_get_certificate.3 | 123 + static/netbsd/man3/SSL_get_ciphers.3 | 177 + static/netbsd/man3/SSL_get_client_CA_list.3 | 188 + static/netbsd/man3/SSL_get_client_random.3 | 160 + static/netbsd/man3/SSL_get_conn_close_info.3 | 220 + static/netbsd/man3/SSL_get_current_cipher.3 | 129 + static/netbsd/man3/SSL_get_default_timeout.3 | 108 + static/netbsd/man3/SSL_get_error.3 | 250 + static/netbsd/man3/SSL_get_event_timeout.3 | 136 + .../man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 187 + static/netbsd/man3/SSL_get_ex_new_index.3 | 192 + static/netbsd/man3/SSL_get_extms_support.3 | 99 + static/netbsd/man3/SSL_get_fd.3 | 106 + static/netbsd/man3/SSL_get_handshake_rtt.3 | 119 + static/netbsd/man3/SSL_get_peer_cert_chain.3 | 129 + static/netbsd/man3/SSL_get_peer_certificate.3 | 137 + static/netbsd/man3/SSL_get_peer_signature_nid.3 | 129 + static/netbsd/man3/SSL_get_peer_tmp_key.3 | 111 + static/netbsd/man3/SSL_get_psk_identity.3 | 103 + static/netbsd/man3/SSL_get_rbio.3 | 102 + static/netbsd/man3/SSL_get_rpoll_descriptor.3 | 148 + static/netbsd/man3/SSL_get_server_tmp_key.3 | 174 + static/netbsd/man3/SSL_get_session.3 | 165 + static/netbsd/man3/SSL_get_shared_sigalgs.3 | 146 + static/netbsd/man3/SSL_get_stream_id.3 | 159 + static/netbsd/man3/SSL_get_stream_read_state.3 | 208 + static/netbsd/man3/SSL_get_value_uint.3 | 376 + static/netbsd/man3/SSL_get_verify_result.3 | 124 + static/netbsd/man3/SSL_get_version.3 | 182 + static/netbsd/man3/SSL_group_to_name.3 | 102 + static/netbsd/man3/SSL_handle_events.3 | 152 + static/netbsd/man3/SSL_in_init.3 | 162 + static/netbsd/man3/SSL_inject_net_dgram.3 | 113 + static/netbsd/man3/SSL_key_update.3 | 187 + static/netbsd/man3/SSL_library_init.3 | 113 + static/netbsd/man3/SSL_load_client_CA_file.3 | 168 + static/netbsd/man3/SSL_new.3 | 182 + static/netbsd/man3/SSL_new_domain.3 | 158 + static/netbsd/man3/SSL_new_listener.3 | 270 + static/netbsd/man3/SSL_new_stream.3 | 158 + static/netbsd/man3/SSL_pending.3 | 127 + static/netbsd/man3/SSL_poll.3 | 430 + static/netbsd/man3/SSL_read.3 | 211 + static/netbsd/man3/SSL_read_early_data.3 | 429 + static/netbsd/man3/SSL_rstate_string.3 | 118 + static/netbsd/man3/SSL_session_reused.3 | 105 + static/netbsd/man3/SSL_set1_host.3 | 186 + static/netbsd/man3/SSL_set1_initial_peer_addr.3 | 119 + static/netbsd/man3/SSL_set1_server_cert_type.3 | 250 + static/netbsd/man3/SSL_set_async_callback.3 | 165 + static/netbsd/man3/SSL_set_bio.3 | 167 + static/netbsd/man3/SSL_set_blocking_mode.3 | 133 + static/netbsd/man3/SSL_set_connect_state.3 | 135 + static/netbsd/man3/SSL_set_default_stream_mode.3 | 178 + static/netbsd/man3/SSL_set_fd.3 | 128 + .../netbsd/man3/SSL_set_incoming_stream_policy.3 | 146 + static/netbsd/man3/SSL_set_quic_tls_cbs.3 | 248 + static/netbsd/man3/SSL_set_retry_verify.3 | 128 + static/netbsd/man3/SSL_set_session.3 | 122 + static/netbsd/man3/SSL_set_session_secret_cb.3 | 128 + static/netbsd/man3/SSL_set_shutdown.3 | 141 + static/netbsd/man3/SSL_set_verify_result.3 | 105 + static/netbsd/man3/SSL_shutdown.3 | 455 + static/netbsd/man3/SSL_state_string.3 | 112 + static/netbsd/man3/SSL_stream_conclude.3 | 118 + static/netbsd/man3/SSL_stream_reset.3 | 136 + static/netbsd/man3/SSL_want.3 | 168 + static/netbsd/man3/SSL_write.3 | 248 + static/netbsd/man3/SSLeay_version.3 | 192 + static/netbsd/man3/TS_RESP_CTX_new.3 | 109 + static/netbsd/man3/TS_VERIFY_CTX.3 | 216 + static/netbsd/man3/TS_VERIFY_CTX_set_certs.3 | 116 + static/netbsd/man3/Tspi_ChangeAuth.3 | 75 + static/netbsd/man3/Tspi_ChangeAuthAsym.3 | 76 + static/netbsd/man3/Tspi_Context_Close.3 | 68 + static/netbsd/man3/Tspi_Context_CloseObject.3 | 69 + static/netbsd/man3/Tspi_Context_Connect.3 | 69 + static/netbsd/man3/Tspi_Context_Create.3 | 66 + static/netbsd/man3/Tspi_Context_CreateObject.3 | 125 + static/netbsd/man3/Tspi_Context_FreeMemory.3 | 81 + static/netbsd/man3/Tspi_Context_GetCapability.3 | 83 + static/netbsd/man3/Tspi_Context_GetDefaultPolicy.3 | 82 + .../netbsd/man3/Tspi_Context_GetKeyByPublicInfo.3 | 81 + static/netbsd/man3/Tspi_Context_GetKeyByUUID.3 | 98 + .../man3/Tspi_Context_GetRegisteredKeysByUUID.3 | 81 + .../man3/Tspi_Context_GetRegisteredKeysByUUID2.3 | 82 + static/netbsd/man3/Tspi_Context_GetTpmObject.3 | 86 + static/netbsd/man3/Tspi_Context_LoadKeyByBlob.3 | 98 + static/netbsd/man3/Tspi_Context_LoadKeyByUUID.3 | 78 + static/netbsd/man3/Tspi_Context_RegisterKey.3 | 170 + static/netbsd/man3/Tspi_Context_UnregisterKey.3 | 150 + static/netbsd/man3/Tspi_DAA_IssueCredential.3 | 103 + static/netbsd/man3/Tspi_DAA_IssueInit.3 | 113 + static/netbsd/man3/Tspi_DAA_IssueSetup.3 | 100 + .../netbsd/man3/Tspi_DAA_IssuerKeyVerification.3 | 87 + static/netbsd/man3/Tspi_DAA_VerifyInit.3 | 85 + static/netbsd/man3/Tspi_DAA_VerifySignature.3 | 106 + static/netbsd/man3/Tspi_Data_Bind.3 | 116 + static/netbsd/man3/Tspi_Data_Seal.3 | 83 + static/netbsd/man3/Tspi_Data_Unbind.3 | 109 + static/netbsd/man3/Tspi_Data_Unseal.3 | 81 + static/netbsd/man3/Tspi_DecodeBER_TssBlob.3 | 77 + static/netbsd/man3/Tspi_EncodeDER_TssBlob.3 | 77 + static/netbsd/man3/Tspi_GetAttribData.3 | 89 + static/netbsd/man3/Tspi_GetAttribUint32.3 | 105 + static/netbsd/man3/Tspi_GetPolicyObject.3 | 90 + static/netbsd/man3/Tspi_Hash_GetHashValue.3 | 98 + static/netbsd/man3/Tspi_Hash_SetHashValue.3 | 98 + static/netbsd/man3/Tspi_Hash_Sign.3 | 108 + static/netbsd/man3/Tspi_Hash_UpdateHashValue.3 | 99 + static/netbsd/man3/Tspi_Hash_VerifySignature.3 | 105 + static/netbsd/man3/Tspi_Key_CertifyKey.3 | 76 + static/netbsd/man3/Tspi_Key_ConvertMigrationBlob.3 | 100 + static/netbsd/man3/Tspi_Key_CreateKey.3 | 71 + static/netbsd/man3/Tspi_Key_CreateMigrationBlob.3 | 97 + static/netbsd/man3/Tspi_Key_GetPubKey.3 | 89 + static/netbsd/man3/Tspi_Key_LoadKey.3 | 83 + static/netbsd/man3/Tspi_Key_UnloadKey.3 | 83 + static/netbsd/man3/Tspi_Key_WrapKey.3 | 72 + static/netbsd/man3/Tspi_PcrComposite_GetPcrValue.3 | 77 + .../netbsd/man3/Tspi_PcrComposite_SelectPcrIndex.3 | 69 + static/netbsd/man3/Tspi_PcrComposite_SetPcrValue.3 | 77 + static/netbsd/man3/Tspi_Policy_AssignToObject.3 | 86 + static/netbsd/man3/Tspi_Policy_FlushSecret.3 | 77 + static/netbsd/man3/Tspi_Policy_SetSecret.3 | 80 + static/netbsd/man3/Tspi_SetAttribData.3 | 87 + static/netbsd/man3/Tspi_SetAttribUint32.3 | 106 + .../man3/Tspi_TPM_AuthorizeMigrationTicket.3 | 84 + static/netbsd/man3/Tspi_TPM_CMKSetRestrictions.3 | 93 + static/netbsd/man3/Tspi_TPM_CertifySelfTest.3 | 80 + .../netbsd/man3/Tspi_TPM_CheckMaintenancePubKey.3 | 100 + static/netbsd/man3/Tspi_TPM_ClearOwner.3 | 85 + .../netbsd/man3/Tspi_TPM_CollateIdentityRequest.3 | 102 + static/netbsd/man3/Tspi_TPM_CreateEndorsementKey.3 | 94 + .../man3/Tspi_TPM_CreateMaintenanceArchive.3 | 107 + .../netbsd/man3/Tspi_TPM_DAA_JoinCreateDaaPubKey.3 | 112 + static/netbsd/man3/Tspi_TPM_DAA_JoinInit.3 | 119 + .../netbsd/man3/Tspi_TPM_DAA_JoinStoreCredential.3 | 89 + static/netbsd/man3/Tspi_TPM_DAA_Sign.3 | 109 + static/netbsd/man3/Tspi_TPM_DirRead.3 | 89 + static/netbsd/man3/Tspi_TPM_DirWrite.3 | 91 + static/netbsd/man3/Tspi_TPM_GetAuditDigest.3 | 87 + static/netbsd/man3/Tspi_TPM_GetCapability.3 | 125 + static/netbsd/man3/Tspi_TPM_GetEvent.3 | 80 + static/netbsd/man3/Tspi_TPM_GetEventLog.3 | 78 + static/netbsd/man3/Tspi_TPM_GetEvents.3 | 86 + static/netbsd/man3/Tspi_TPM_GetPubEndorsementKey.3 | 101 + static/netbsd/man3/Tspi_TPM_GetRandom.3 | 88 + static/netbsd/man3/Tspi_TPM_GetStatus.3 | 86 + static/netbsd/man3/Tspi_TPM_GetTestResult.3 | 76 + .../netbsd/man3/Tspi_TPM_KillMaintenanceFeature.3 | 85 + .../netbsd/man3/Tspi_TPM_LoadMaintenancePubKey.3 | 102 + static/netbsd/man3/Tspi_TPM_OwnerGetSRKPubKey.3 | 87 + static/netbsd/man3/Tspi_TPM_PcrExtend.3 | 100 + static/netbsd/man3/Tspi_TPM_PcrRead.3 | 91 + static/netbsd/man3/Tspi_TPM_Quote.3 | 83 + static/netbsd/man3/Tspi_TPM_Quote2.3 | 100 + static/netbsd/man3/Tspi_TPM_SelfTestFull.3 | 82 + static/netbsd/man3/Tspi_TPM_SetStatus.3 | 90 + static/netbsd/man3/Tspi_TPM_StirRandom.3 | 89 + static/netbsd/man3/Tspi_TPM_TakeOwnership.3 | 83 + static/netbsd/man3/UI_STRING.3 | 206 + static/netbsd/man3/UI_UTIL_read_pw.3 | 130 + static/netbsd/man3/UI_create_method.3 | 255 + static/netbsd/man3/UI_new.3 | 319 + static/netbsd/man3/WINCNG_CIPHER_ALGORITHM.3 | 3 + .../man3/WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3 | 3 + static/netbsd/man3/X509V3_get_d2i.3 | 327 + static/netbsd/man3/X509V3_set_ctx.3 | 127 + static/netbsd/man3/X509_ACERT_add1_attr.3 | 125 + static/netbsd/man3/X509_ACERT_add_attr_nconf.3 | 125 + .../man3/X509_ACERT_get0_holder_baseCertId.3 | 173 + static/netbsd/man3/X509_ACERT_get_attr.3 | 118 + static/netbsd/man3/X509_ACERT_print_ex.3 | 164 + static/netbsd/man3/X509_ALGOR_dup.3 | 131 + static/netbsd/man3/X509_ATTRIBUTE.3 | 326 + static/netbsd/man3/X509_CRL_get0_by_serial.3 | 173 + static/netbsd/man3/X509_EXTENSION_set_object.3 | 154 + static/netbsd/man3/X509_LOOKUP.3 | 298 + static/netbsd/man3/X509_LOOKUP_hash_dir.3 | 218 + static/netbsd/man3/X509_LOOKUP_meth_new.3 | 255 + static/netbsd/man3/X509_NAME_ENTRY_get_object.3 | 154 + static/netbsd/man3/X509_NAME_add_entry_by_txt.3 | 185 + static/netbsd/man3/X509_NAME_get0_der.3 | 98 + static/netbsd/man3/X509_NAME_get_index_by_NID.3 | 187 + static/netbsd/man3/X509_NAME_print_ex.3 | 189 + static/netbsd/man3/X509_PUBKEY_new.3 | 237 + static/netbsd/man3/X509_REQ_get_attr.3 | 169 + static/netbsd/man3/X509_REQ_get_extensions.3 | 112 + static/netbsd/man3/X509_SIG_get0.3 | 99 + static/netbsd/man3/X509_STORE_CTX_get_by_subject.3 | 110 + static/netbsd/man3/X509_STORE_CTX_get_error.3 | 460 + .../netbsd/man3/X509_STORE_CTX_get_ex_new_index.3 | 173 + static/netbsd/man3/X509_STORE_CTX_new.3 | 387 + static/netbsd/man3/X509_STORE_CTX_set_verify_cb.3 | 304 + static/netbsd/man3/X509_STORE_add_cert.3 | 230 + static/netbsd/man3/X509_STORE_get0_param.3 | 136 + static/netbsd/man3/X509_STORE_new.3 | 118 + static/netbsd/man3/X509_STORE_set_verify_cb_func.3 | 343 + static/netbsd/man3/X509_VERIFY_PARAM_set_flags.3 | 481 + static/netbsd/man3/X509_add_cert.3 | 134 + static/netbsd/man3/X509_check_ca.3 | 107 + static/netbsd/man3/X509_check_host.3 | 219 + static/netbsd/man3/X509_check_issued.3 | 104 + static/netbsd/man3/X509_check_private_key.3 | 112 + static/netbsd/man3/X509_check_purpose.3 | 236 + static/netbsd/man3/X509_cmp.3 | 144 + static/netbsd/man3/X509_cmp_time.3 | 146 + static/netbsd/man3/X509_digest.3 | 149 + static/netbsd/man3/X509_dup.3 | 673 + static/netbsd/man3/X509_get0_distinguishing_id.3 | 127 + static/netbsd/man3/X509_get0_notBefore.3 | 189 + static/netbsd/man3/X509_get0_signature.3 | 217 + static/netbsd/man3/X509_get0_uids.3 | 131 + static/netbsd/man3/X509_get_default_cert_file.3 | 144 + static/netbsd/man3/X509_get_extension_flags.3 | 249 + static/netbsd/man3/X509_get_pubkey.3 | 145 + static/netbsd/man3/X509_get_serialNumber.3 | 146 + static/netbsd/man3/X509_get_subject_name.3 | 201 + static/netbsd/man3/X509_get_version.3 | 153 + static/netbsd/man3/X509_load_http.3 | 131 + static/netbsd/man3/X509_new.3 | 165 + static/netbsd/man3/X509_sign.3 | 147 + static/netbsd/man3/X509_verify.3 | 147 + static/netbsd/man3/X509_verify_cert.3 | 170 + static/netbsd/man3/X509v3_get_ext_by_NID.3 | 225 + static/netbsd/man3/__builtin_object_size.3 | 101 + static/netbsd/man3/_lwp_makecontext.3 | 74 + static/netbsd/man3/a64l.3 | 133 + static/netbsd/man3/abort.3 | 73 + static/netbsd/man3/abs.3 | 73 + static/netbsd/man3/acl.3 | 307 + static/netbsd/man3/acl_add_flag_np.3 | 99 + static/netbsd/man3/acl_add_perm.3 | 130 + static/netbsd/man3/acl_calc_mask.3 | 99 + static/netbsd/man3/acl_clear_flags_np.3 | 80 + static/netbsd/man3/acl_clear_perms.3 | 80 + static/netbsd/man3/acl_copy_entry.3 | 86 + static/netbsd/man3/acl_create_entry.3 | 99 + static/netbsd/man3/acl_delete.3 | 141 + static/netbsd/man3/acl_delete_entry.3 | 102 + static/netbsd/man3/acl_delete_flag_np.3 | 85 + static/netbsd/man3/acl_delete_perm.3 | 85 + static/netbsd/man3/acl_dup.3 | 111 + static/netbsd/man3/acl_free.3 | 90 + static/netbsd/man3/acl_from_text.3 | 131 + static/netbsd/man3/acl_get.3 | 169 + static/netbsd/man3/acl_get_brand_np.3 | 87 + static/netbsd/man3/acl_get_entry.3 | 146 + static/netbsd/man3/acl_get_entry_type_np.3 | 81 + static/netbsd/man3/acl_get_flag_np.3 | 95 + static/netbsd/man3/acl_get_flagset_np.3 | 84 + static/netbsd/man3/acl_get_perm_np.3 | 95 + static/netbsd/man3/acl_get_permset.3 | 84 + static/netbsd/man3/acl_get_qualifier.3 | 141 + static/netbsd/man3/acl_get_tag_type.3 | 86 + static/netbsd/man3/acl_init.3 | 112 + static/netbsd/man3/acl_is_trivial_np.3 | 86 + static/netbsd/man3/acl_set.3 | 158 + static/netbsd/man3/acl_set_entry_type_np.3 | 95 + static/netbsd/man3/acl_set_flagset_np.3 | 86 + static/netbsd/man3/acl_set_permset.3 | 82 + static/netbsd/man3/acl_set_qualifier.3 | 92 + static/netbsd/man3/acl_set_tag_type.3 | 103 + static/netbsd/man3/acl_strip_np.3 | 110 + static/netbsd/man3/acl_to_text.3 | 160 + static/netbsd/man3/acl_valid.3 | 171 + static/netbsd/man3/acos.3 | 89 + static/netbsd/man3/acosh.3 | 88 + static/netbsd/man3/affinity.3 | 141 + static/netbsd/man3/aio.3 | 348 + static/netbsd/man3/aio_cancel.3 | 90 + static/netbsd/man3/aio_error.3 | 92 + static/netbsd/man3/aio_fsync.3 | 140 + static/netbsd/man3/aio_read.3 | 199 + static/netbsd/man3/aio_return.3 | 95 + static/netbsd/man3/aio_suspend.3 | 117 + static/netbsd/man3/aio_write.3 | 196 + static/netbsd/man3/alarm.3 | 98 + static/netbsd/man3/alloca.3 | 120 + static/netbsd/man3/apropos-utils.3 | 61 + static/netbsd/man3/arc4random.3 | 332 + static/netbsd/man3/archive_entry.3 | 147 + static/netbsd/man3/archive_entry_acl.3 | 458 + static/netbsd/man3/archive_entry_linkify.3 | 224 + static/netbsd/man3/archive_entry_misc.3 | 63 + static/netbsd/man3/archive_entry_paths.3 | 153 + static/netbsd/man3/archive_entry_perms.3 | 210 + static/netbsd/man3/archive_entry_stat.3 | 274 + static/netbsd/man3/archive_entry_time.3 | 127 + static/netbsd/man3/archive_read.3 | 250 + static/netbsd/man3/archive_read_add_passphrase.3 | 72 + static/netbsd/man3/archive_read_data.3 | 128 + static/netbsd/man3/archive_read_disk.3 | 422 + static/netbsd/man3/archive_read_extract.3 | 135 + static/netbsd/man3/archive_read_filter.3 | 162 + static/netbsd/man3/archive_read_format.3 | 190 + static/netbsd/man3/archive_read_free.3 | 91 + static/netbsd/man3/archive_read_header.3 | 89 + static/netbsd/man3/archive_read_new.3 | 57 + static/netbsd/man3/archive_read_open.3 | 231 + static/netbsd/man3/archive_read_set_options.3 | 290 + static/netbsd/man3/archive_util.3 | 222 + static/netbsd/man3/archive_write.3 | 266 + static/netbsd/man3/archive_write_blocksize.3 | 112 + static/netbsd/man3/archive_write_data.3 | 88 + static/netbsd/man3/archive_write_disk.3 | 360 + static/netbsd/man3/archive_write_filter.3 | 132 + static/netbsd/man3/archive_write_finish_entry.3 | 77 + static/netbsd/man3/archive_write_format.3 | 185 + static/netbsd/man3/archive_write_free.3 | 94 + static/netbsd/man3/archive_write_header.3 | 71 + static/netbsd/man3/archive_write_new.3 | 56 + static/netbsd/man3/archive_write_open.3 | 270 + static/netbsd/man3/archive_write_set_options.3 | 761 + static/netbsd/man3/archive_write_set_passphrase.3 | 72 + static/netbsd/man3/asin.3 | 90 + static/netbsd/man3/asinh.3 | 85 + static/netbsd/man3/at_quick_exit.3 | 63 + static/netbsd/man3/atan.3 | 81 + static/netbsd/man3/atan2.3 | 196 + static/netbsd/man3/atanh.3 | 88 + static/netbsd/man3/atexit.3 | 79 + static/netbsd/man3/atf-c++-api.3 | 635 + static/netbsd/man3/atf-c-api.3 | 775 + static/netbsd/man3/atf-sh-api.3 | 393 + static/netbsd/man3/atof.3 | 73 + static/netbsd/man3/atoi.3 | 85 + static/netbsd/man3/atol.3 | 74 + static/netbsd/man3/atoll.3 | 77 + static/netbsd/man3/atomic_add.3 | 95 + static/netbsd/man3/atomic_and.3 | 95 + static/netbsd/man3/atomic_cas.3 | 129 + static/netbsd/man3/atomic_dec.3 | 95 + static/netbsd/man3/atomic_inc.3 | 95 + static/netbsd/man3/atomic_ops.3 | 130 + static/netbsd/man3/atomic_or.3 | 95 + static/netbsd/man3/atomic_swap.3 | 77 + static/netbsd/man3/b2i_PVK_bio_ex.3 | 127 + static/netbsd/man3/backtrace.3 | 181 + static/netbsd/man3/bad.include-toplevel.3 | 6 + static/netbsd/man3/basename.3 | 95 + static/netbsd/man3/bcmp.3 | 90 + static/netbsd/man3/bcopy.3 | 94 + static/netbsd/man3/bind_textdomain_codeset.3 | 72 + static/netbsd/man3/bindresvport.3 | 106 + static/netbsd/man3/bindtextdomain.3 | 69 + static/netbsd/man3/bluetooth.3 | 300 + static/netbsd/man3/bm.3 | 114 + static/netbsd/man3/bsd_signal.3 | 68 + static/netbsd/man3/bsdmalloc.3 | 86 + static/netbsd/man3/bsearch.3 | 90 + static/netbsd/man3/bstring.3 | 93 + static/netbsd/man3/bswap.3 | 54 + static/netbsd/man3/bt_dev.3 | 373 + static/netbsd/man3/btowc.3 | 87 + static/netbsd/man3/btree.3 | 254 + static/netbsd/man3/buffer.h.3 | 1361 ++ static/netbsd/man3/buffer_compat.h.3 | 144 + static/netbsd/man3/bufferevent.3 | 27 + static/netbsd/man3/bufferevent.h.3 | 1253 + static/netbsd/man3/bufferevent_ssl.h.3 | 135 + static/netbsd/man3/byteorder.3 | 80 + static/netbsd/man3/bzero.3 | 82 + static/netbsd/man3/c16rtomb.3 | 222 + static/netbsd/man3/c32rtomb.3 | 200 + static/netbsd/man3/c8rtomb.3 | 220 + static/netbsd/man3/cabs.3 | 44 + static/netbsd/man3/cacos.3 | 45 + static/netbsd/man3/cacosh.3 | 45 + static/netbsd/man3/call_once.3 | 113 + static/netbsd/man3/carg.3 | 46 + static/netbsd/man3/casin.3 | 46 + static/netbsd/man3/casinh.3 | 46 + static/netbsd/man3/catan.3 | 46 + static/netbsd/man3/catanh.3 | 46 + static/netbsd/man3/catclose.3 | 32 + static/netbsd/man3/catgets.3 | 73 + static/netbsd/man3/catopen.3 | 61 + static/netbsd/man3/ccos.3 | 41 + static/netbsd/man3/ccosh.3 | 41 + static/netbsd/man3/cdbr.3 | 147 + static/netbsd/man3/cdbw.3 | 141 + static/netbsd/man3/ceil.3 | 83 + static/netbsd/man3/cexp.3 | 43 + static/netbsd/man3/cgetcap.3 | 373 + static/netbsd/man3/cimag.3 | 51 + static/netbsd/man3/clock.3 | 66 + static/netbsd/man3/clog.3 | 46 + static/netbsd/man3/close_db.3 | 60 + static/netbsd/man3/closefrom.3 | 64 + static/netbsd/man3/cnd.3 | 182 + static/netbsd/man3/com_err.3 | 248 + static/netbsd/man3/confstr.3 | 134 + static/netbsd/man3/conj.3 | 45 + static/netbsd/man3/consttime_memequal.3 | 95 + static/netbsd/man3/copysign.3 | 93 + static/netbsd/man3/cos.3 | 86 + static/netbsd/man3/cosh.3 | 86 + static/netbsd/man3/cpow.3 | 43 + static/netbsd/man3/cproj.3 | 62 + static/netbsd/man3/cpuset.3 | 119 + static/netbsd/man3/creal.3 | 55 + static/netbsd/man3/creat.3 | 65 + static/netbsd/man3/crypt.3 | 529 + static/netbsd/man3/crypto.3 | 207 + static/netbsd/man3/csh.3 | 648 + static/netbsd/man3/csin.3 | 41 + static/netbsd/man3/csinh.3 | 41 + static/netbsd/man3/csqrt.3 | 44 + static/netbsd/man3/ctan.3 | 41 + static/netbsd/man3/ctanh.3 | 41 + static/netbsd/man3/ctermid.3 | 90 + static/netbsd/man3/ctime.3 | 650 + static/netbsd/man3/ctype.3 | 229 + static/netbsd/man3/curses.3 | 379 + static/netbsd/man3/curses_addch.3 | 187 + static/netbsd/man3/curses_addchstr.3 | 155 + static/netbsd/man3/curses_addstr.3 | 183 + static/netbsd/man3/curses_attributes.3 | 347 + static/netbsd/man3/curses_background.3 | 124 + static/netbsd/man3/curses_border.3 | 159 + static/netbsd/man3/curses_cchar.3 | 154 + static/netbsd/man3/curses_chgat.3 | 119 + static/netbsd/man3/curses_clear.3 | 148 + static/netbsd/man3/curses_color.3 | 237 + static/netbsd/man3/curses_cursor.3 | 261 + static/netbsd/man3/curses_default_colors.3 | 73 + static/netbsd/man3/curses_delch.3 | 90 + static/netbsd/man3/curses_deleteln.3 | 110 + static/netbsd/man3/curses_echochar.3 | 123 + static/netbsd/man3/curses_fileio.3 | 93 + static/netbsd/man3/curses_inch.3 | 264 + static/netbsd/man3/curses_input.3 | 624 + static/netbsd/man3/curses_insch.3 | 113 + static/netbsd/man3/curses_insdelln.3 | 115 + static/netbsd/man3/curses_insertln.3 | 109 + static/netbsd/man3/curses_keyname.3 | 72 + static/netbsd/man3/curses_line.3 | 171 + static/netbsd/man3/curses_mouse.3 | 162 + static/netbsd/man3/curses_pad.3 | 156 + static/netbsd/man3/curses_print.3 | 125 + static/netbsd/man3/curses_refresh.3 | 179 + static/netbsd/man3/curses_scanw.3 | 114 + static/netbsd/man3/curses_screen.3 | 317 + static/netbsd/man3/curses_scroll.3 | 189 + static/netbsd/man3/curses_slk.3 | 244 + static/netbsd/man3/curses_standout.3 | 112 + static/netbsd/man3/curses_termcap.3 | 81 + static/netbsd/man3/curses_touch.3 | 209 + static/netbsd/man3/curses_tty.3 | 389 + static/netbsd/man3/curses_underscore.3 | 100 + static/netbsd/man3/curses_version.3 | 60 + static/netbsd/man3/curses_window.3 | 274 + static/netbsd/man3/cuserid.3 | 120 + static/netbsd/man3/d2i_ASN1_OBJECT.3 | 162 + static/netbsd/man3/d2i_CMS_ContentInfo.3 | 162 + static/netbsd/man3/d2i_DHparams.3 | 178 + static/netbsd/man3/d2i_DSAPublicKey.3 | 215 + static/netbsd/man3/d2i_ECPKParameters.3 | 216 + static/netbsd/man3/d2i_ECPrivateKey.3 | 200 + static/netbsd/man3/d2i_PKCS8PrivateKey.3 | 189 + static/netbsd/man3/d2i_PKCS8PrivateKey_bio.3 | 132 + static/netbsd/man3/d2i_PrivateKey.3 | 192 + static/netbsd/man3/d2i_RSAPrivateKey.3 | 353 + static/netbsd/man3/d2i_RSAPublicKey.3 | 199 + static/netbsd/man3/d2i_SSL_SESSION.3 | 116 + static/netbsd/man3/d2i_X509.3 | 816 + static/netbsd/man3/d2i_X509_ALGOR.3 | 163 + static/netbsd/man3/d2i_X509_CRL.3 | 170 + static/netbsd/man3/d2i_X509_NAME.3 | 164 + static/netbsd/man3/d2i_X509_REQ.3 | 169 + static/netbsd/man3/d2i_X509_SIG.3 | 163 + static/netbsd/man3/daemon.3 | 114 + static/netbsd/man3/data.3 | 3 + static/netbsd/man3/dbm_clearerr.3 | 306 + static/netbsd/man3/dbopen.3 | 538 + static/netbsd/man3/dcgettext.3 | 1 + static/netbsd/man3/dcngettext.3 | 1 + static/netbsd/man3/deprecated.3 | 82 + static/netbsd/man3/des.3 | 496 + static/netbsd/man3/devname.3 | 127 + static/netbsd/man3/dgettext.3 | 1 + static/netbsd/man3/dhcpctl.3 | 607 + static/netbsd/man3/directory.3 | 462 + static/netbsd/man3/dirname.3 | 98 + static/netbsd/man3/disklabel_dkcksum.3 | 56 + static/netbsd/man3/disklabel_scan.3 | 59 + static/netbsd/man3/div.3 | 87 + static/netbsd/man3/dm.3 | 396 + static/netbsd/man3/dngettext.3 | 1 + static/netbsd/man3/dns.h.3 | 961 + static/netbsd/man3/dns_compat.h.3 | 513 + static/netbsd/man3/do_add.3 | 18 + static/netbsd/man3/duplocale.3 | 61 + static/netbsd/man3/dwarf.3 | 755 + static/netbsd/man3/dwarf_add_AT_comp_dir.3 | 103 + .../netbsd/man3/dwarf_add_AT_const_value_string.3 | 131 + static/netbsd/man3/dwarf_add_AT_dataref.3 | 127 + static/netbsd/man3/dwarf_add_AT_flag.3 | 119 + static/netbsd/man3/dwarf_add_AT_location_expr.3 | 124 + static/netbsd/man3/dwarf_add_AT_name.3 | 103 + static/netbsd/man3/dwarf_add_AT_producer.3 | 103 + static/netbsd/man3/dwarf_add_AT_ref_address.3 | 121 + static/netbsd/man3/dwarf_add_AT_reference.3 | 121 + static/netbsd/man3/dwarf_add_AT_signed_const.3 | 136 + static/netbsd/man3/dwarf_add_AT_string.3 | 118 + static/netbsd/man3/dwarf_add_AT_targ_address.3 | 141 + static/netbsd/man3/dwarf_add_arange.3 | 155 + static/netbsd/man3/dwarf_add_die_to_debug.3 | 99 + static/netbsd/man3/dwarf_add_directory_decl.3 | 101 + static/netbsd/man3/dwarf_add_expr_addr.3 | 115 + static/netbsd/man3/dwarf_add_expr_gen.3 | 122 + static/netbsd/man3/dwarf_add_fde_inst.3 | 117 + static/netbsd/man3/dwarf_add_file_decl.3 | 126 + static/netbsd/man3/dwarf_add_frame_cie.3 | 128 + static/netbsd/man3/dwarf_add_frame_fde.3 | 205 + static/netbsd/man3/dwarf_add_funcname.3 | 107 + static/netbsd/man3/dwarf_add_line_entry.3 | 168 + static/netbsd/man3/dwarf_add_pubname.3 | 107 + static/netbsd/man3/dwarf_add_typename.3 | 107 + static/netbsd/man3/dwarf_add_varname.3 | 107 + static/netbsd/man3/dwarf_add_weakname.3 | 107 + static/netbsd/man3/dwarf_attr.3 | 125 + static/netbsd/man3/dwarf_attrlist.3 | 151 + static/netbsd/man3/dwarf_attroffset.3 | 90 + static/netbsd/man3/dwarf_attrval_signed.3 | 229 + static/netbsd/man3/dwarf_child.3 | 284 + static/netbsd/man3/dwarf_dealloc.3 | 205 + static/netbsd/man3/dwarf_def_macro.3 | 134 + static/netbsd/man3/dwarf_die_abbrev_code.3 | 57 + static/netbsd/man3/dwarf_die_link.3 | 124 + static/netbsd/man3/dwarf_diename.3 | 94 + static/netbsd/man3/dwarf_dieoffset.3 | 214 + static/netbsd/man3/dwarf_end_macro_file.3 | 93 + static/netbsd/man3/dwarf_errmsg.3 | 69 + static/netbsd/man3/dwarf_errno.3 | 60 + .../netbsd/man3/dwarf_expand_frame_instructions.3 | 186 + static/netbsd/man3/dwarf_expr_current_offset.3 | 88 + static/netbsd/man3/dwarf_expr_into_block.3 | 98 + static/netbsd/man3/dwarf_fde_cfa_offset.3 | 103 + static/netbsd/man3/dwarf_find_macro_value_start.3 | 73 + static/netbsd/man3/dwarf_finish.3 | 142 + static/netbsd/man3/dwarf_formaddr.3 | 101 + static/netbsd/man3/dwarf_formblock.3 | 113 + static/netbsd/man3/dwarf_formexprloc.3 | 113 + static/netbsd/man3/dwarf_formflag.3 | 101 + static/netbsd/man3/dwarf_formref.3 | 140 + static/netbsd/man3/dwarf_formsig8.3 | 100 + static/netbsd/man3/dwarf_formstring.3 | 105 + static/netbsd/man3/dwarf_formudata.3 | 126 + static/netbsd/man3/dwarf_get_AT_name.3 | 262 + static/netbsd/man3/dwarf_get_abbrev.3 | 183 + .../netbsd/man3/dwarf_get_abbrev_children_flag.3 | 103 + static/netbsd/man3/dwarf_get_abbrev_code.3 | 90 + static/netbsd/man3/dwarf_get_abbrev_entry.3 | 163 + static/netbsd/man3/dwarf_get_abbrev_tag.3 | 90 + static/netbsd/man3/dwarf_get_address_size.3 | 87 + static/netbsd/man3/dwarf_get_arange.3 | 125 + static/netbsd/man3/dwarf_get_arange_info.3 | 139 + static/netbsd/man3/dwarf_get_aranges.3 | 152 + static/netbsd/man3/dwarf_get_cie_index.3 | 89 + static/netbsd/man3/dwarf_get_cie_info.3 | 154 + static/netbsd/man3/dwarf_get_cie_of_fde.3 | 92 + static/netbsd/man3/dwarf_get_cu_die_offset.3 | 108 + static/netbsd/man3/dwarf_get_die_infotypes_flag.3 | 75 + static/netbsd/man3/dwarf_get_elf.3 | 105 + static/netbsd/man3/dwarf_get_fde_at_pc.3 | 129 + .../netbsd/man3/dwarf_get_fde_info_for_all_regs.3 | 160 + .../netbsd/man3/dwarf_get_fde_info_for_all_regs3.3 | 187 + .../netbsd/man3/dwarf_get_fde_info_for_cfa_reg3.3 | 175 + static/netbsd/man3/dwarf_get_fde_info_for_reg.3 | 160 + static/netbsd/man3/dwarf_get_fde_info_for_reg3.3 | 218 + static/netbsd/man3/dwarf_get_fde_instr_bytes.3 | 117 + static/netbsd/man3/dwarf_get_fde_list.3 | 222 + static/netbsd/man3/dwarf_get_fde_n.3 | 115 + static/netbsd/man3/dwarf_get_fde_range.3 | 153 + static/netbsd/man3/dwarf_get_form_class.3 | 89 + static/netbsd/man3/dwarf_get_funcs.3 | 219 + static/netbsd/man3/dwarf_get_globals.3 | 216 + static/netbsd/man3/dwarf_get_loclist_entry.3 | 160 + static/netbsd/man3/dwarf_get_macro_details.3 | 198 + static/netbsd/man3/dwarf_get_pubtypes.3 | 248 + static/netbsd/man3/dwarf_get_ranges.3 | 264 + static/netbsd/man3/dwarf_get_relocation_info.3 | 232 + .../netbsd/man3/dwarf_get_relocation_info_count.3 | 120 + static/netbsd/man3/dwarf_get_section_bytes.3 | 163 + static/netbsd/man3/dwarf_get_section_max_offsets.3 | 122 + static/netbsd/man3/dwarf_get_str.3 | 153 + static/netbsd/man3/dwarf_get_types.3 | 237 + static/netbsd/man3/dwarf_get_vars.3 | 215 + static/netbsd/man3/dwarf_get_weaks.3 | 220 + static/netbsd/man3/dwarf_hasattr.3 | 96 + static/netbsd/man3/dwarf_hasform.3 | 133 + static/netbsd/man3/dwarf_highpc.3 | 199 + static/netbsd/man3/dwarf_init.3 | 180 + static/netbsd/man3/dwarf_lineno.3 | 206 + static/netbsd/man3/dwarf_lne_end_sequence.3 | 104 + static/netbsd/man3/dwarf_lne_set_address.3 | 109 + static/netbsd/man3/dwarf_loclist.3 | 235 + static/netbsd/man3/dwarf_loclist_from_expr.3 | 205 + static/netbsd/man3/dwarf_new_die.3 | 170 + static/netbsd/man3/dwarf_new_expr.3 | 139 + static/netbsd/man3/dwarf_new_fde.3 | 91 + static/netbsd/man3/dwarf_next_cu_header.3 | 324 + static/netbsd/man3/dwarf_next_types_section.3 | 137 + static/netbsd/man3/dwarf_object_init.3 | 229 + static/netbsd/man3/dwarf_producer_init.3 | 299 + static/netbsd/man3/dwarf_producer_set_isa.3 | 102 + static/netbsd/man3/dwarf_reset_section_bytes.3 | 71 + static/netbsd/man3/dwarf_set_frame_cfa_value.3 | 142 + static/netbsd/man3/dwarf_set_reloc_application.3 | 84 + static/netbsd/man3/dwarf_seterrarg.3 | 113 + static/netbsd/man3/dwarf_srcfiles.3 | 109 + static/netbsd/man3/dwarf_srclines.3 | 167 + static/netbsd/man3/dwarf_start_macro_file.3 | 109 + static/netbsd/man3/dwarf_tag.3 | 81 + static/netbsd/man3/dwarf_transform_to_disk_form.3 | 103 + static/netbsd/man3/dwarf_undef_macro.3 | 123 + static/netbsd/man3/dwarf_vendor_ext.3 | 114 + static/netbsd/man3/dwarf_whatattr.3 | 83 + static/netbsd/man3/ec.3 | 333 + static/netbsd/man3/ecalloc.3 | 86 + static/netbsd/man3/eddsa_pk_new.3 | 146 + static/netbsd/man3/editline.3 | 1054 + static/netbsd/man3/efun.3 | 140 + static/netbsd/man3/elf.3 | 630 + static/netbsd/man3/elf_begin.3 | 329 + static/netbsd/man3/elf_cntl.3 | 114 + static/netbsd/man3/elf_end.3 | 81 + static/netbsd/man3/elf_errmsg.3 | 113 + static/netbsd/man3/elf_fill.3 | 54 + static/netbsd/man3/elf_flagdata.3 | 230 + static/netbsd/man3/elf_getarhdr.3 | 106 + static/netbsd/man3/elf_getarsym.3 | 136 + static/netbsd/man3/elf_getbase.3 | 74 + static/netbsd/man3/elf_getdata.3 | 254 + static/netbsd/man3/elf_getident.3 | 90 + static/netbsd/man3/elf_getphdrnum.3 | 89 + static/netbsd/man3/elf_getphnum.3 | 96 + static/netbsd/man3/elf_getscn.3 | 163 + static/netbsd/man3/elf_getshdrnum.3 | 81 + static/netbsd/man3/elf_getshdrstrndx.3 | 82 + static/netbsd/man3/elf_getshnum.3 | 87 + static/netbsd/man3/elf_getshstrndx.3 | 98 + static/netbsd/man3/elf_getversion.3 | 71 + static/netbsd/man3/elf_hash.3 | 59 + static/netbsd/man3/elf_kind.3 | 76 + static/netbsd/man3/elf_memory.3 | 129 + static/netbsd/man3/elf_next.3 | 101 + static/netbsd/man3/elf_open.3 | 119 + static/netbsd/man3/elf_rand.3 | 120 + static/netbsd/man3/elf_rawfile.3 | 81 + static/netbsd/man3/elf_strptr.3 | 120 + static/netbsd/man3/elf_update.3 | 384 + static/netbsd/man3/elf_version.3 | 97 + static/netbsd/man3/endutent.3 | 122 + static/netbsd/man3/endutxent.3 | 202 + static/netbsd/man3/erf.3 | 93 + static/netbsd/man3/err.3 | 213 + static/netbsd/man3/es256_pk_new.3 | 164 + static/netbsd/man3/es384_pk_new.3 | 164 + static/netbsd/man3/ethers.3 | 121 + static/netbsd/man3/evbuffer.3 | 27 + static/netbsd/man3/evbuffer_cb_info.3 | 57 + static/netbsd/man3/evbuffer_iovec.3 | 49 + static/netbsd/man3/evbuffer_ptr.3 | 48 + static/netbsd/man3/event.3 | 43 + static/netbsd/man3/event.h.3 | 1778 ++ static/netbsd/man3/event_base.3 | 29 + static/netbsd/man3/event_compat.h.3 | 298 + static/netbsd/man3/event_config.3 | 27 + static/netbsd/man3/evthread_condition_callbacks.3 | 68 + static/netbsd/man3/evthread_lock_callbacks.3 | 74 + static/netbsd/man3/evutil_addrinfo.3 | 48 + static/netbsd/man3/evutil_monotonic_timer.3 | 29 + static/netbsd/man3/example.3 | 41 + static/netbsd/man3/exec.3 | 292 + static/netbsd/man3/exit.3 | 116 + static/netbsd/man3/exp.3 | 136 + static/netbsd/man3/explicit_memset.3 | 96 + static/netbsd/man3/extattr.3 | 101 + static/netbsd/man3/extattr_copy_file.3 | 105 + static/netbsd/man3/fabs.3 | 78 + static/netbsd/man3/fclose.3 | 93 + static/netbsd/man3/fdim.3 | 89 + static/netbsd/man3/feclearexcept.3 | 139 + static/netbsd/man3/feenableexcept.3 | 97 + static/netbsd/man3/fegetenv.3 | 114 + static/netbsd/man3/fegetround.3 | 84 + static/netbsd/man3/fenv.3 | 283 + static/netbsd/man3/ferror.3 | 121 + static/netbsd/man3/fetch.3 | 668 + static/netbsd/man3/fflush.3 | 134 + static/netbsd/man3/ffs.3 | 88 + static/netbsd/man3/fgetln.3 | 149 + static/netbsd/man3/fgets.3 | 201 + static/netbsd/man3/fgetwln.3 | 121 + static/netbsd/man3/fgetws.3 | 122 + static/netbsd/man3/fido_assert_allow_cred.3 | 80 + static/netbsd/man3/fido_assert_new.3 | 293 + static/netbsd/man3/fido_assert_set_authdata.3 | 314 + static/netbsd/man3/fido_assert_verify.3 | 104 + static/netbsd/man3/fido_bio_dev_get_info.3 | 145 + static/netbsd/man3/fido_bio_enroll_new.3 | 118 + static/netbsd/man3/fido_bio_info_new.3 | 104 + static/netbsd/man3/fido_bio_template.3 | 202 + static/netbsd/man3/fido_cbor_info_new.3 | 389 + static/netbsd/man3/fido_cred_exclude.3 | 93 + static/netbsd/man3/fido_cred_new.3 | 366 + static/netbsd/man3/fido_cred_set_authdata.3 | 424 + static/netbsd/man3/fido_cred_verify.3 | 114 + static/netbsd/man3/fido_credman_metadata_new.3 | 349 + static/netbsd/man3/fido_dev_enable_entattest.3 | 149 + static/netbsd/man3/fido_dev_get_assert.3 | 99 + static/netbsd/man3/fido_dev_get_touch_begin.3 | 96 + static/netbsd/man3/fido_dev_info_manifest.3 | 211 + static/netbsd/man3/fido_dev_largeblob_get.3 | 216 + static/netbsd/man3/fido_dev_make_cred.3 | 100 + static/netbsd/man3/fido_dev_open.3 | 316 + static/netbsd/man3/fido_dev_set_io_functions.3 | 261 + static/netbsd/man3/fido_dev_set_pin.3 | 128 + static/netbsd/man3/fido_init.3 | 95 + static/netbsd/man3/fido_strerr.3 | 50 + static/netbsd/man3/finite.3 | 82 + static/netbsd/man3/flockfile.3 | 127 + static/netbsd/man3/fma.3 | 126 + static/netbsd/man3/fmax.3 | 100 + static/netbsd/man3/fmemopen.3 | 194 + static/netbsd/man3/fmod.3 | 83 + static/netbsd/man3/fmtcheck.3 | 99 + static/netbsd/man3/fmtmsg.3 | 220 + static/netbsd/man3/fnmatch.3 | 140 + static/netbsd/man3/fopen.3 | 326 + static/netbsd/man3/form_cursor.3 | 71 + static/netbsd/man3/form_data.3 | 76 + static/netbsd/man3/form_driver.3 | 226 + static/netbsd/man3/form_field.3 | 111 + static/netbsd/man3/form_field_attributes.3 | 100 + static/netbsd/man3/form_field_buffer.3 | 134 + static/netbsd/man3/form_field_info.3 | 89 + static/netbsd/man3/form_field_just.3 | 97 + static/netbsd/man3/form_field_new.3 | 117 + static/netbsd/man3/form_field_opts.3 | 157 + static/netbsd/man3/form_field_userptr.3 | 74 + static/netbsd/man3/form_field_validation.3 | 82 + static/netbsd/man3/form_fieldtype.3 | 150 + static/netbsd/man3/form_hook.3 | 116 + static/netbsd/man3/form_new.3 | 85 + static/netbsd/man3/form_new_page.3 | 75 + static/netbsd/man3/form_opts.3 | 104 + static/netbsd/man3/form_page.3 | 119 + static/netbsd/man3/form_post.3 | 85 + static/netbsd/man3/form_userptr.3 | 74 + static/netbsd/man3/form_win.3 | 109 + static/netbsd/man3/forms.3 | 235 + static/netbsd/man3/fparseln.3 | 148 + static/netbsd/man3/fpclassify.3 | 94 + static/netbsd/man3/fpgetmask.3 | 172 + static/netbsd/man3/fputs.3 | 105 + static/netbsd/man3/fputws.3 | 89 + static/netbsd/man3/fread.3 | 133 + static/netbsd/man3/freelocale.3 | 58 + static/netbsd/man3/frexp.3 | 87 + static/netbsd/man3/fseek.3 | 247 + static/netbsd/man3/fstab.nfs.3 | 16 + static/netbsd/man3/fstab.wd0.3 | 18 + static/netbsd/man3/ftime.3 | 90 + static/netbsd/man3/ftok.3 | 93 + static/netbsd/man3/fts.3 | 793 + static/netbsd/man3/ftw.3 | 214 + static/netbsd/man3/funopen.3 | 202 + static/netbsd/man3/fwide.3 | 94 + static/netbsd/man3/gai_strerror.3 | 96 + static/netbsd/man3/gelf.3 | 205 + static/netbsd/man3/gelf_checksum.3 | 118 + static/netbsd/man3/gelf_fsize.3 | 100 + static/netbsd/man3/gelf_getcap.3 | 132 + static/netbsd/man3/gelf_getclass.3 | 63 + static/netbsd/man3/gelf_getdyn.3 | 135 + static/netbsd/man3/gelf_getehdr.3 | 127 + static/netbsd/man3/gelf_getmove.3 | 131 + static/netbsd/man3/gelf_getphdr.3 | 146 + static/netbsd/man3/gelf_getrel.3 | 132 + static/netbsd/man3/gelf_getrela.3 | 132 + static/netbsd/man3/gelf_getshdr.3 | 122 + static/netbsd/man3/gelf_getsym.3 | 136 + static/netbsd/man3/gelf_getsyminfo.3 | 126 + static/netbsd/man3/gelf_getsymshndx.3 | 194 + static/netbsd/man3/gelf_newehdr.3 | 201 + static/netbsd/man3/gelf_newphdr.3 | 148 + static/netbsd/man3/gelf_update_ehdr.3 | 126 + static/netbsd/man3/gelf_xlatetof.3 | 285 + static/netbsd/man3/getaddrinfo.3 | 343 + static/netbsd/man3/getarg.3 | 343 + static/netbsd/man3/getbootfile.3 | 61 + static/netbsd/man3/getbsize.3 | 90 + static/netbsd/man3/getbyteorder.3 | 61 + static/netbsd/man3/getc.3 | 177 + static/netbsd/man3/getcwd.3 | 172 + static/netbsd/man3/getdate.3 | 232 + static/netbsd/man3/getdelim.3 | 171 + static/netbsd/man3/getdevmajor.3 | 118 + static/netbsd/man3/getdirentries.3 | 164 + static/netbsd/man3/getdiskbyname.3 | 105 + static/netbsd/man3/getdiskrawname.3 | 72 + static/netbsd/man3/getdomainname.3 | 99 + static/netbsd/man3/getdtablesize.3 | 70 + static/netbsd/man3/getentropy.3 | 133 + static/netbsd/man3/getenv.3 | 231 + static/netbsd/man3/getfsent.3 | 149 + static/netbsd/man3/getfsspecname.3 | 106 + static/netbsd/man3/getfstypename.3 | 55 + static/netbsd/man3/getgrent.3 | 344 + static/netbsd/man3/getgrouplist.3 | 152 + static/netbsd/man3/gethostbyname.3 | 239 + static/netbsd/man3/gethostid.3 | 77 + static/netbsd/man3/gethostname.3 | 101 + static/netbsd/man3/getifaddrs.3 | 207 + static/netbsd/man3/getipnodebyname.3 | 212 + static/netbsd/man3/getlabelsector.3 | 83 + static/netbsd/man3/getlastlogx.3 | 173 + static/netbsd/man3/getloadavg.3 | 66 + static/netbsd/man3/getmaxpartitions.3 | 59 + static/netbsd/man3/getmntinfo.3 | 115 + static/netbsd/man3/getmntopts.3 | 280 + static/netbsd/man3/getnameinfo.3 | 103 + static/netbsd/man3/getnetconfig.3 | 183 + static/netbsd/man3/getnetent.3 | 155 + static/netbsd/man3/getnetgrent.3 | 124 + static/netbsd/man3/getnetpath.3 | 155 + static/netbsd/man3/getopt.3 | 329 + static/netbsd/man3/getopt_long.3 | 310 + static/netbsd/man3/getpagesize.3 | 66 + static/netbsd/man3/getpass.3 | 202 + static/netbsd/man3/getpeereid.3 | 142 + static/netbsd/man3/getprogname.3 | 117 + static/netbsd/man3/getprotoent.3 | 156 + static/netbsd/man3/getpwent.3 | 370 + static/netbsd/man3/getrawpartition.3 | 75 + static/netbsd/man3/getrpcent.3 | 96 + static/netbsd/man3/getrpcport.3 | 34 + static/netbsd/man3/getservent.3 | 155 + static/netbsd/man3/getsubopt.3 | 148 + static/netbsd/man3/gettext.3 | 99 + static/netbsd/man3/getttyent.3 | 219 + static/netbsd/man3/getusershell.3 | 98 + static/netbsd/man3/getwc.3 | 114 + static/netbsd/man3/glob.3 | 541 + static/netbsd/man3/grantpt.3 | 97 + static/netbsd/man3/gss_acquire_cred.3 | 690 + static/netbsd/man3/gss_add_oid_set_member.3 | 3 + static/netbsd/man3/gss_canonicalize_name.3 | 3 + static/netbsd/man3/gss_display_status.3 | 3 + static/netbsd/man3/gss_export_name.3 | 3 + static/netbsd/man3/gss_import_name.3 | 3 + static/netbsd/man3/gss_init_sec_context.3 | 3 + static/netbsd/man3/gss_inquire_attrs_for_mech.3 | 3 + static/netbsd/man3/gss_inquire_saslname_for_mech.3 | 3 + static/netbsd/man3/gss_oid_equal.3 | 3 + static/netbsd/man3/gss_release_cred.3 | 3 + static/netbsd/man3/gss_release_iov_buffer.3 | 3 + static/netbsd/man3/gss_release_name.3 | 3 + static/netbsd/man3/gss_unwrap_iov.3 | 3 + static/netbsd/man3/gss_wrap.3 | 3 + static/netbsd/man3/gss_wrap_iov.3 | 3 + static/netbsd/man3/gss_wrap_iov_length.3 | 3 + static/netbsd/man3/gssapi.3 | 436 + static/netbsd/man3/gssapi_mechs_intro.3 | 18 + static/netbsd/man3/gssapi_services_intro.3 | 68 + static/netbsd/man3/hash.3 | 172 + static/netbsd/man3/hcreate.3 | 333 + static/netbsd/man3/hcrypto_core.3 | 79 + static/netbsd/man3/hcrypto_des.3 | 381 + static/netbsd/man3/hcrypto_dh.3 | 294 + static/netbsd/man3/hcrypto_evp.3 | 1443 ++ static/netbsd/man3/hcrypto_misc.3 | 82 + static/netbsd/man3/hcrypto_rand.3 | 208 + static/netbsd/man3/hcrypto_rsa.3 | 152 + static/netbsd/man3/hdb__del.3 | 3 + static/netbsd/man3/hdb__get.3 | 3 + static/netbsd/man3/hdb__put.3 | 3 + static/netbsd/man3/hdb_auth_status.3 | 3 + .../netbsd/man3/hdb_check_constrained_delegation.3 | 3 + static/netbsd/man3/hdb_check_pkinit_ms_upn_match.3 | 3 + static/netbsd/man3/hdb_check_s4u2self.3 | 3 + static/netbsd/man3/hdb_close.3 | 3 + static/netbsd/man3/hdb_destroy.3 | 3 + static/netbsd/man3/hdb_entry_ex.3 | 19 + static/netbsd/man3/hdb_fetch_kvno.3 | 3 + static/netbsd/man3/hdb_firstkey.3 | 3 + static/netbsd/man3/hdb_free.3 | 3 + static/netbsd/man3/hdb_get_realms.3 | 3 + static/netbsd/man3/hdb_lock.3 | 3 + static/netbsd/man3/hdb_name.3 | 3 + static/netbsd/man3/hdb_nextkey.3 | 3 + static/netbsd/man3/hdb_open.3 | 3 + static/netbsd/man3/hdb_password.3 | 3 + static/netbsd/man3/hdb_remove.3 | 3 + static/netbsd/man3/hdb_rename.3 | 3 + static/netbsd/man3/hdb_set_sync.3 | 3 + static/netbsd/man3/hdb_store.3 | 3 + static/netbsd/man3/hdb_unlock.3 | 3 + static/netbsd/man3/heim_ntlm_build_ntlm1_master.3 | 3 + static/netbsd/man3/heim_ntlm_build_ntlm2_master.3 | 3 + static/netbsd/man3/heim_ntlm_calculate_lm2.3 | 3 + static/netbsd/man3/heim_ntlm_calculate_ntlm1.3 | 3 + static/netbsd/man3/heim_ntlm_calculate_ntlm2.3 | 3 + static/netbsd/man3/heim_ntlm_decode_targetinfo.3 | 3 + static/netbsd/man3/heim_ntlm_encode_targetinfo.3 | 3 + static/netbsd/man3/heim_ntlm_encode_type1.3 | 3 + static/netbsd/man3/heim_ntlm_encode_type2.3 | 3 + static/netbsd/man3/heim_ntlm_encode_type3.3 | 3 + static/netbsd/man3/heim_ntlm_free_buf.3 | 3 + static/netbsd/man3/heim_ntlm_free_targetinfo.3 | 3 + static/netbsd/man3/heim_ntlm_free_type1.3 | 3 + static/netbsd/man3/heim_ntlm_free_type2.3 | 3 + static/netbsd/man3/heim_ntlm_free_type3.3 | 3 + static/netbsd/man3/heim_ntlm_keyex_unwrap.3 | 3 + static/netbsd/man3/heim_ntlm_nt_key.3 | 3 + static/netbsd/man3/heim_ntlm_ntlmv2_key.3 | 3 + static/netbsd/man3/heim_ntlm_verify_ntlm2.3 | 3 + static/netbsd/man3/heimbase.3 | 334 + static/netbsd/man3/hesiod.3 | 130 + static/netbsd/man3/history.3 | 687 + static/netbsd/man3/hosts_access.3 | 96 + static/netbsd/man3/http.h.3 | 1668 ++ static/netbsd/man3/http_compat.h.3 | 94 + static/netbsd/man3/humanize_number.3 | 189 + static/netbsd/man3/hx509.3 | 51 + static/netbsd/man3/hx509_bitstring_print.3 | 3 + static/netbsd/man3/hx509_ca.3 | 575 + static/netbsd/man3/hx509_ca_sign.3 | 3 + static/netbsd/man3/hx509_ca_sign_self.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_crl_dp_uri.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_eku.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_san_hostname.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_san_jid.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_san_ms_upn.3 | 3 + .../netbsd/man3/hx509_ca_tbs_add_san_otherName.3 | 3 + static/netbsd/man3/hx509_ca_tbs_add_san_pkinit.3 | 3 + .../netbsd/man3/hx509_ca_tbs_add_san_rfc822name.3 | 3 + static/netbsd/man3/hx509_ca_tbs_free.3 | 3 + static/netbsd/man3/hx509_ca_tbs_init.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_ca.3 | 3 + .../man3/hx509_ca_tbs_set_domaincontroller.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_notAfter.3 | 3 + .../man3/hx509_ca_tbs_set_notAfter_lifetime.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_notBefore.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_proxy.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_serialnumber.3 | 3 + .../man3/hx509_ca_tbs_set_signature_algorithm.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_spki.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_subject.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_template.3 | 3 + static/netbsd/man3/hx509_ca_tbs_set_unique.3 | 3 + static/netbsd/man3/hx509_ca_tbs_subject_expand.3 | 3 + static/netbsd/man3/hx509_ca_tbs_template_units.3 | 3 + static/netbsd/man3/hx509_cert.3 | 675 + static/netbsd/man3/hx509_cert_binary.3 | 3 + static/netbsd/man3/hx509_cert_check_eku.3 | 3 + static/netbsd/man3/hx509_cert_cmp.3 | 3 + .../hx509_cert_find_subjectAltName_otherName.3 | 3 + static/netbsd/man3/hx509_cert_free.3 | 3 + static/netbsd/man3/hx509_cert_get_SPKI.3 | 3 + .../man3/hx509_cert_get_SPKI_AlgorithmIdentifier.3 | 3 + static/netbsd/man3/hx509_cert_get_attribute.3 | 3 + static/netbsd/man3/hx509_cert_get_base_subject.3 | 3 + static/netbsd/man3/hx509_cert_get_friendly_name.3 | 3 + static/netbsd/man3/hx509_cert_get_issuer.3 | 3 + .../netbsd/man3/hx509_cert_get_issuer_unique_id.3 | 3 + static/netbsd/man3/hx509_cert_get_notAfter.3 | 3 + static/netbsd/man3/hx509_cert_get_notBefore.3 | 3 + static/netbsd/man3/hx509_cert_get_serialnumber.3 | 3 + static/netbsd/man3/hx509_cert_get_subject.3 | 3 + .../netbsd/man3/hx509_cert_get_subject_unique_id.3 | 3 + static/netbsd/man3/hx509_cert_init.3 | 3 + static/netbsd/man3/hx509_cert_init_data.3 | 3 + static/netbsd/man3/hx509_cert_keyusage_print.3 | 3 + static/netbsd/man3/hx509_cert_ref.3 | 3 + static/netbsd/man3/hx509_cert_set_friendly_name.3 | 3 + static/netbsd/man3/hx509_certs_add.3 | 3 + static/netbsd/man3/hx509_certs_append.3 | 3 + static/netbsd/man3/hx509_certs_end_seq.3 | 3 + static/netbsd/man3/hx509_certs_filter.3 | 3 + static/netbsd/man3/hx509_certs_find.3 | 3 + static/netbsd/man3/hx509_certs_free.3 | 3 + static/netbsd/man3/hx509_certs_info.3 | 3 + static/netbsd/man3/hx509_certs_init.3 | 3 + static/netbsd/man3/hx509_certs_iter_f.3 | 3 + static/netbsd/man3/hx509_certs_merge.3 | 3 + static/netbsd/man3/hx509_certs_next_cert.3 | 3 + static/netbsd/man3/hx509_certs_start_seq.3 | 3 + static/netbsd/man3/hx509_certs_store.3 | 3 + static/netbsd/man3/hx509_ci_print_names.3 | 3 + static/netbsd/man3/hx509_clear_error_string.3 | 3 + static/netbsd/man3/hx509_cms.3 | 226 + static/netbsd/man3/hx509_cms_create_signed_1.3 | 3 + static/netbsd/man3/hx509_cms_envelope_1.3 | 3 + static/netbsd/man3/hx509_cms_unenvelope.3 | 3 + static/netbsd/man3/hx509_cms_unwrap_ContentInfo.3 | 3 + static/netbsd/man3/hx509_cms_verify_signed.3 | 3 + static/netbsd/man3/hx509_cms_wrap_ContentInfo.3 | 3 + static/netbsd/man3/hx509_context_free.3 | 3 + static/netbsd/man3/hx509_context_init.3 | 3 + .../netbsd/man3/hx509_context_set_missing_revoke.3 | 3 + static/netbsd/man3/hx509_crl_add_revoked_certs.3 | 3 + static/netbsd/man3/hx509_crl_alloc.3 | 3 + static/netbsd/man3/hx509_crl_free.3 | 3 + static/netbsd/man3/hx509_crl_lifetime.3 | 3 + static/netbsd/man3/hx509_crl_sign.3 | 3 + static/netbsd/man3/hx509_crypto.3 | 47 + static/netbsd/man3/hx509_env.3 | 145 + static/netbsd/man3/hx509_env_add.3 | 3 + static/netbsd/man3/hx509_env_add_binding.3 | 3 + static/netbsd/man3/hx509_env_find.3 | 3 + static/netbsd/man3/hx509_env_find_binding.3 | 3 + static/netbsd/man3/hx509_env_free.3 | 3 + static/netbsd/man3/hx509_env_lfind.3 | 3 + static/netbsd/man3/hx509_err.3 | 3 + static/netbsd/man3/hx509_error.3 | 131 + static/netbsd/man3/hx509_free_error_string.3 | 3 + static/netbsd/man3/hx509_free_octet_string_list.3 | 3 + static/netbsd/man3/hx509_general_name_unparse.3 | 3 + static/netbsd/man3/hx509_get_error_string.3 | 3 + static/netbsd/man3/hx509_get_one_cert.3 | 3 + static/netbsd/man3/hx509_keyset.3 | 353 + static/netbsd/man3/hx509_lock.3 | 16 + static/netbsd/man3/hx509_misc.3 | 46 + static/netbsd/man3/hx509_name.3 | 230 + static/netbsd/man3/hx509_name_binary.3 | 3 + static/netbsd/man3/hx509_name_cmp.3 | 3 + static/netbsd/man3/hx509_name_copy.3 | 3 + static/netbsd/man3/hx509_name_expand.3 | 3 + static/netbsd/man3/hx509_name_free.3 | 3 + static/netbsd/man3/hx509_name_is_null_p.3 | 3 + static/netbsd/man3/hx509_name_to_Name.3 | 3 + static/netbsd/man3/hx509_name_to_string.3 | 3 + static/netbsd/man3/hx509_ocsp_request.3 | 3 + static/netbsd/man3/hx509_ocsp_verify.3 | 3 + static/netbsd/man3/hx509_oid_print.3 | 3 + static/netbsd/man3/hx509_oid_sprint.3 | 3 + static/netbsd/man3/hx509_parse_name.3 | 3 + static/netbsd/man3/hx509_peer.3 | 116 + static/netbsd/man3/hx509_peer_info_add_cms_alg.3 | 3 + static/netbsd/man3/hx509_peer_info_alloc.3 | 3 + static/netbsd/man3/hx509_peer_info_free.3 | 3 + static/netbsd/man3/hx509_peer_info_set_cert.3 | 3 + static/netbsd/man3/hx509_peer_info_set_cms_algs.3 | 3 + static/netbsd/man3/hx509_print.3 | 209 + static/netbsd/man3/hx509_print_cert.3 | 3 + static/netbsd/man3/hx509_print_stdout.3 | 3 + static/netbsd/man3/hx509_query.3 | 16 + static/netbsd/man3/hx509_query_alloc.3 | 3 + static/netbsd/man3/hx509_query_free.3 | 3 + static/netbsd/man3/hx509_query_match_cmp_func.3 | 3 + static/netbsd/man3/hx509_query_match_eku.3 | 3 + .../netbsd/man3/hx509_query_match_friendly_name.3 | 3 + .../netbsd/man3/hx509_query_match_issuer_serial.3 | 3 + static/netbsd/man3/hx509_query_match_option.3 | 3 + static/netbsd/man3/hx509_query_statistic_file.3 | 3 + static/netbsd/man3/hx509_query_unparse_stats.3 | 3 + static/netbsd/man3/hx509_revoke.3 | 172 + static/netbsd/man3/hx509_revoke_add_crl.3 | 3 + static/netbsd/man3/hx509_revoke_add_ocsp.3 | 3 + static/netbsd/man3/hx509_revoke_free.3 | 3 + static/netbsd/man3/hx509_revoke_init.3 | 3 + static/netbsd/man3/hx509_revoke_ocsp_print.3 | 3 + static/netbsd/man3/hx509_revoke_verify.3 | 3 + static/netbsd/man3/hx509_set_error_string.3 | 3 + static/netbsd/man3/hx509_set_error_stringv.3 | 3 + static/netbsd/man3/hx509_unparse_der_name.3 | 3 + static/netbsd/man3/hx509_validate_cert.3 | 3 + static/netbsd/man3/hx509_validate_ctx_add_flags.3 | 3 + static/netbsd/man3/hx509_validate_ctx_free.3 | 3 + static/netbsd/man3/hx509_validate_ctx_init.3 | 3 + static/netbsd/man3/hx509_validate_ctx_set_print.3 | 3 + static/netbsd/man3/hx509_verify.3 | 301 + static/netbsd/man3/hx509_verify_attach_anchors.3 | 3 + static/netbsd/man3/hx509_verify_attach_revoke.3 | 3 + ...hx509_verify_ctx_f_allow_default_trustanchors.3 | 3 + static/netbsd/man3/hx509_verify_destroy_ctx.3 | 3 + static/netbsd/man3/hx509_verify_hostname.3 | 3 + static/netbsd/man3/hx509_verify_init_ctx.3 | 3 + static/netbsd/man3/hx509_verify_path.3 | 3 + static/netbsd/man3/hx509_verify_set_max_depth.3 | 3 + .../man3/hx509_verify_set_proxy_certificate.3 | 3 + .../hx509_verify_set_strict_rfc3280_verification.3 | 3 + static/netbsd/man3/hx509_verify_set_time.3 | 3 + static/netbsd/man3/hx509_verify_signature.3 | 3 + static/netbsd/man3/hx509_xfree.3 | 3 + static/netbsd/man3/hypot.3 | 118 + static/netbsd/man3/i2d_CMS_bio_stream.3 | 109 + static/netbsd/man3/i2d_PKCS7_bio_stream.3 | 109 + static/netbsd/man3/i2d_re_X509_tbs.3 | 147 + static/netbsd/man3/iconv.3 | 279 + static/netbsd/man3/ieee_test.3 | 98 + static/netbsd/man3/if_indextoname.3 | 138 + static/netbsd/man3/ilogb.3 | 104 + static/netbsd/man3/include.include.withclauses.3 | 1 + .../netbsd/man3/include.include.withoutclauses.3 | 1 + .../netbsd/man3/include.includetop.withclauses.3 | 1 + .../man3/include.includetop.withoutclauses.3 | 1 + static/netbsd/man3/include.withclauses.3 | 1 + static/netbsd/man3/include.withoutclauses.3 | 1 + static/netbsd/man3/include.withsomeclauses.3 | 1 + static/netbsd/man3/index.3 | 99 + static/netbsd/man3/inet.3 | 410 + static/netbsd/man3/inet6_getscopeid.3 | 100 + static/netbsd/man3/inet6_opt_init.3 | 337 + static/netbsd/man3/inet6_option_space.3 | 448 + static/netbsd/man3/inet6_rth_space.3 | 223 + static/netbsd/man3/inet6_rthdr_space.3 | 321 + static/netbsd/man3/inet_cidr.3 | 95 + static/netbsd/man3/inet_net.3 | 198 + static/netbsd/man3/init_db.3 | 100 + static/netbsd/man3/initgroups.3 | 91 + static/netbsd/man3/insque.3 | 80 + static/netbsd/man3/internal_v_smechname.3 | 22 + static/netbsd/man3/ipsec_set_policy.3 | 310 + static/netbsd/man3/ipsec_strerror.3 | 80 + static/netbsd/man3/ipv6.3 | 30 + static/netbsd/man3/isalnum.3 | 97 + static/netbsd/man3/isalpha.3 | 114 + static/netbsd/man3/isascii.3 | 85 + static/netbsd/man3/isblank.3 | 102 + static/netbsd/man3/iscntrl.3 | 93 + static/netbsd/man3/isdigit.3 | 93 + static/netbsd/man3/isfinite.3 | 78 + static/netbsd/man3/isgraph.3 | 93 + static/netbsd/man3/isgreater.3 | 104 + static/netbsd/man3/isinf.3 | 83 + static/netbsd/man3/isinff.3 | 76 + static/netbsd/man3/islower.3 | 107 + static/netbsd/man3/isnan.3 | 85 + static/netbsd/man3/isnormal.3 | 77 + static/netbsd/man3/isns.3 | 245 + static/netbsd/man3/isprint.3 | 93 + static/netbsd/man3/ispunct.3 | 96 + static/netbsd/man3/isspace.3 | 120 + static/netbsd/man3/isupper.3 | 105 + static/netbsd/man3/iswalnum.3 | 116 + static/netbsd/man3/iswctype.3 | 99 + static/netbsd/man3/isxdigit.3 | 93 + static/netbsd/man3/j0.3 | 153 + static/netbsd/man3/jemalloc.3 | 2688 +++ static/netbsd/man3/kadm5_pwcheck.3 | 161 + static/netbsd/man3/kafs.3 | 298 + static/netbsd/man3/keccak.3 | 74 + static/netbsd/man3/killpg.3 | 94 + static/netbsd/man3/kinfo_getvmmap.3 | 80 + static/netbsd/man3/krb5.3 | 1062 + static/netbsd/man3/krb524_convert_creds_kdc.3 | 3 + .../netbsd/man3/krb524_convert_creds_kdc_ccache.3 | 3 + static/netbsd/man3/krb5_425_conv_principal.3 | 226 + static/netbsd/man3/krb5_abort.3 | 3 + static/netbsd/man3/krb5_abortx.3 | 3 + static/netbsd/man3/krb5_acc_ops.3 | 3 + static/netbsd/man3/krb5_acl_match_file.3 | 3 + static/netbsd/man3/krb5_acl_match_string.3 | 3 + static/netbsd/man3/krb5_add_et_list.3 | 3 + static/netbsd/man3/krb5_add_extra_addresses.3 | 3 + static/netbsd/man3/krb5_add_ignore_addresses.3 | 3 + static/netbsd/man3/krb5_addr2sockaddr.3 | 3 + static/netbsd/man3/krb5_address.3 | 449 + static/netbsd/man3/krb5_address_compare.3 | 3 + static/netbsd/man3/krb5_address_order.3 | 3 + .../netbsd/man3/krb5_address_prefixlen_boundary.3 | 3 + static/netbsd/man3/krb5_address_search.3 | 3 + static/netbsd/man3/krb5_allow_weak_crypto.3 | 3 + static/netbsd/man3/krb5_aname_to_localname.3 | 3 + static/netbsd/man3/krb5_anyaddr.3 | 3 + static/netbsd/man3/krb5_appdefault.3 | 90 + static/netbsd/man3/krb5_append_addresses.3 | 3 + static/netbsd/man3/krb5_auth.3 | 140 + static/netbsd/man3/krb5_auth_context.3 | 397 + static/netbsd/man3/krb5_auth_getremoteseqnumber.3 | 3 + static/netbsd/man3/krb5_build_principal.3 | 3 + static/netbsd/man3/krb5_c_enctype_compare.3 | 3 + static/netbsd/man3/krb5_c_make_checksum.3 | 299 + static/netbsd/man3/krb5_cc_cache_end_seq_get.3 | 3 + static/netbsd/man3/krb5_cc_cache_get_first.3 | 3 + static/netbsd/man3/krb5_cc_cache_match.3 | 3 + static/netbsd/man3/krb5_cc_cache_next.3 | 3 + static/netbsd/man3/krb5_cc_clear_mcred.3 | 3 + static/netbsd/man3/krb5_cc_close.3 | 3 + static/netbsd/man3/krb5_cc_copy_cache.3 | 3 + static/netbsd/man3/krb5_cc_copy_creds.3 | 3 + static/netbsd/man3/krb5_cc_copy_match_f.3 | 3 + static/netbsd/man3/krb5_cc_default.3 | 3 + static/netbsd/man3/krb5_cc_default_name.3 | 3 + static/netbsd/man3/krb5_cc_destroy.3 | 3 + static/netbsd/man3/krb5_cc_end_seq_get.3 | 3 + static/netbsd/man3/krb5_cc_gen_new.3 | 3 + static/netbsd/man3/krb5_cc_get_config.3 | 3 + static/netbsd/man3/krb5_cc_get_flags.3 | 3 + static/netbsd/man3/krb5_cc_get_friendly_name.3 | 3 + static/netbsd/man3/krb5_cc_get_full_name.3 | 3 + static/netbsd/man3/krb5_cc_get_kdc_offset.3 | 3 + static/netbsd/man3/krb5_cc_get_lifetime.3 | 3 + static/netbsd/man3/krb5_cc_get_name.3 | 3 + static/netbsd/man3/krb5_cc_get_ops.3 | 3 + static/netbsd/man3/krb5_cc_get_prefix_ops.3 | 3 + static/netbsd/man3/krb5_cc_get_principal.3 | 3 + static/netbsd/man3/krb5_cc_get_type.3 | 3 + static/netbsd/man3/krb5_cc_get_version.3 | 3 + static/netbsd/man3/krb5_cc_initialize.3 | 3 + static/netbsd/man3/krb5_cc_last_change_time.3 | 3 + static/netbsd/man3/krb5_cc_move.3 | 3 + static/netbsd/man3/krb5_cc_new_unique.3 | 3 + static/netbsd/man3/krb5_cc_next_cred.3 | 3 + static/netbsd/man3/krb5_cc_register.3 | 3 + static/netbsd/man3/krb5_cc_remove_cred.3 | 3 + static/netbsd/man3/krb5_cc_resolve.3 | 3 + static/netbsd/man3/krb5_cc_retrieve_cred.3 | 3 + static/netbsd/man3/krb5_cc_set_config.3 | 3 + static/netbsd/man3/krb5_cc_set_default_name.3 | 3 + static/netbsd/man3/krb5_cc_set_flags.3 | 3 + static/netbsd/man3/krb5_cc_set_friendly_name.3 | 3 + static/netbsd/man3/krb5_cc_set_kdc_offset.3 | 3 + static/netbsd/man3/krb5_cc_start_seq_get.3 | 3 + static/netbsd/man3/krb5_cc_store_cred.3 | 3 + static/netbsd/man3/krb5_cc_support_switch.3 | 3 + static/netbsd/man3/krb5_cc_switch.3 | 3 + static/netbsd/man3/krb5_ccache.3 | 882 + static/netbsd/man3/krb5_ccache_intro.3 | 72 + static/netbsd/man3/krb5_cccol_cursor_free.3 | 3 + static/netbsd/man3/krb5_cccol_cursor_new.3 | 3 + static/netbsd/man3/krb5_cccol_cursor_next.3 | 3 + static/netbsd/man3/krb5_cccol_last_change_time.3 | 3 + static/netbsd/man3/krb5_change_password.3 | 3 + static/netbsd/man3/krb5_check_transited.3 | 108 + static/netbsd/man3/krb5_cksumtype_to_enctype.3 | 3 + static/netbsd/man3/krb5_clear_error_message.3 | 3 + static/netbsd/man3/krb5_clear_error_string.3 | 3 + static/netbsd/man3/krb5_compare_creds.3 | 3 + static/netbsd/man3/krb5_config_file_free.3 | 3 + static/netbsd/man3/krb5_config_free_strings.3 | 3 + static/netbsd/man3/krb5_config_get_bool.3 | 3 + static/netbsd/man3/krb5_config_get_bool_default.3 | 3 + static/netbsd/man3/krb5_config_get_list.3 | 3 + static/netbsd/man3/krb5_config_get_string.3 | 3 + .../netbsd/man3/krb5_config_get_string_default.3 | 3 + static/netbsd/man3/krb5_config_get_strings.3 | 3 + static/netbsd/man3/krb5_config_get_time.3 | 3 + static/netbsd/man3/krb5_config_get_time_default.3 | 3 + static/netbsd/man3/krb5_config_parse_file_multi.3 | 3 + .../netbsd/man3/krb5_config_parse_string_multi.3 | 3 + static/netbsd/man3/krb5_config_vget_bool.3 | 3 + static/netbsd/man3/krb5_config_vget_bool_default.3 | 3 + static/netbsd/man3/krb5_config_vget_list.3 | 3 + static/netbsd/man3/krb5_config_vget_string.3 | 3 + .../netbsd/man3/krb5_config_vget_string_default.3 | 3 + static/netbsd/man3/krb5_config_vget_strings.3 | 3 + static/netbsd/man3/krb5_config_vget_time.3 | 3 + static/netbsd/man3/krb5_config_vget_time_default.3 | 3 + static/netbsd/man3/krb5_copy_address.3 | 3 + static/netbsd/man3/krb5_copy_addresses.3 | 3 + static/netbsd/man3/krb5_copy_context.3 | 3 + static/netbsd/man3/krb5_copy_creds.3 | 3 + static/netbsd/man3/krb5_copy_creds_contents.3 | 3 + static/netbsd/man3/krb5_copy_data.3 | 3 + static/netbsd/man3/krb5_copy_host_realm.3 | 3 + static/netbsd/man3/krb5_copy_keyblock.3 | 3 + static/netbsd/man3/krb5_copy_keyblock_contents.3 | 3 + static/netbsd/man3/krb5_copy_principal.3 | 3 + static/netbsd/man3/krb5_copy_ticket.3 | 3 + static/netbsd/man3/krb5_create_checksum.3 | 228 + static/netbsd/man3/krb5_create_checksum_iov.3 | 3 + static/netbsd/man3/krb5_credential.3 | 270 + static/netbsd/man3/krb5_creds.3 | 121 + static/netbsd/man3/krb5_creds_get_ticket_flags.3 | 3 + static/netbsd/man3/krb5_crypto.3 | 651 + static/netbsd/man3/krb5_crypto_destroy.3 | 3 + static/netbsd/man3/krb5_crypto_fx_cf2.3 | 3 + static/netbsd/man3/krb5_crypto_getblocksize.3 | 3 + static/netbsd/man3/krb5_crypto_getconfoundersize.3 | 3 + static/netbsd/man3/krb5_crypto_getenctype.3 | 3 + static/netbsd/man3/krb5_crypto_getpadsize.3 | 3 + static/netbsd/man3/krb5_crypto_init.3 | 3 + static/netbsd/man3/krb5_crypto_iov.3 | 19 + static/netbsd/man3/krb5_data_alloc.3 | 3 + static/netbsd/man3/krb5_data_cmp.3 | 3 + static/netbsd/man3/krb5_data_copy.3 | 3 + static/netbsd/man3/krb5_data_ct_cmp.3 | 3 + static/netbsd/man3/krb5_data_free.3 | 3 + static/netbsd/man3/krb5_data_realloc.3 | 3 + static/netbsd/man3/krb5_data_zero.3 | 3 + static/netbsd/man3/krb5_dcc_ops.3 | 3 + static/netbsd/man3/krb5_decrypt_iov_ivec.3 | 3 + static/netbsd/man3/krb5_deprecated.3 | 251 + static/netbsd/man3/krb5_digest.3 | 45 + static/netbsd/man3/krb5_digest_probe.3 | 3 + static/netbsd/man3/krb5_eai_to_heim_errno.3 | 3 + static/netbsd/man3/krb5_encrypt.3 | 280 + static/netbsd/man3/krb5_encrypt_iov_ivec.3 | 3 + static/netbsd/man3/krb5_enctype_disable.3 | 3 + static/netbsd/man3/krb5_enctype_enable.3 | 3 + static/netbsd/man3/krb5_enctype_valid.3 | 3 + static/netbsd/man3/krb5_enctypes_compatible_keys.3 | 3 + static/netbsd/man3/krb5_err.3 | 3 + static/netbsd/man3/krb5_error.3 | 414 + static/netbsd/man3/krb5_errx.3 | 3 + static/netbsd/man3/krb5_expand_hostname.3 | 3 + static/netbsd/man3/krb5_expand_hostname_realms.3 | 3 + static/netbsd/man3/krb5_fcc_ops.3 | 3 + static/netbsd/man3/krb5_fileformats.3 | 236 + static/netbsd/man3/krb5_find_padata.3 | 89 + static/netbsd/man3/krb5_free_address.3 | 3 + static/netbsd/man3/krb5_free_addresses.3 | 3 + static/netbsd/man3/krb5_free_config_files.3 | 3 + static/netbsd/man3/krb5_free_context.3 | 3 + static/netbsd/man3/krb5_free_cred_contents.3 | 3 + static/netbsd/man3/krb5_free_creds.3 | 3 + static/netbsd/man3/krb5_free_creds_contents.3 | 3 + static/netbsd/man3/krb5_free_data.3 | 3 + static/netbsd/man3/krb5_free_data_contents.3 | 3 + static/netbsd/man3/krb5_free_error_message.3 | 3 + static/netbsd/man3/krb5_free_error_string.3 | 3 + static/netbsd/man3/krb5_free_host_realm.3 | 3 + static/netbsd/man3/krb5_free_keyblock.3 | 3 + static/netbsd/man3/krb5_free_keyblock_contents.3 | 3 + static/netbsd/man3/krb5_free_principal.3 | 3 + static/netbsd/man3/krb5_free_ticket.3 | 3 + static/netbsd/man3/krb5_free_unparsed_name.3 | 3 + static/netbsd/man3/krb5_fwd_tgt_creds.3 | 3 + static/netbsd/man3/krb5_generate_random.3 | 3 + static/netbsd/man3/krb5_generate_random_block.3 | 3 + static/netbsd/man3/krb5_generate_subkey.3 | 3 + static/netbsd/man3/krb5_generate_subkey_extended.3 | 3 + static/netbsd/man3/krb5_get_all_client_addrs.3 | 76 + static/netbsd/man3/krb5_get_cred_from_kdc.3 | 3 + static/netbsd/man3/krb5_get_cred_from_kdc_opt.3 | 3 + static/netbsd/man3/krb5_get_credentials.3 | 183 + static/netbsd/man3/krb5_get_creds.3 | 175 + static/netbsd/man3/krb5_get_default_config_files.3 | 3 + .../netbsd/man3/krb5_get_default_in_tkt_etypes.3 | 3 + .../man3/krb5_get_dns_canonicalize_hostname.3 | 3 + static/netbsd/man3/krb5_get_err_text.3 | 3 + static/netbsd/man3/krb5_get_error_message.3 | 3 + static/netbsd/man3/krb5_get_error_string.3 | 3 + static/netbsd/man3/krb5_get_extra_addresses.3 | 3 + static/netbsd/man3/krb5_get_fcache_version.3 | 3 + static/netbsd/man3/krb5_get_forwarded_creds.3 | 3 + static/netbsd/man3/krb5_get_ignore_addresses.3 | 3 + static/netbsd/man3/krb5_get_in_cred.3 | 276 + static/netbsd/man3/krb5_get_in_tkt_with_keytab.3 | 3 + static/netbsd/man3/krb5_get_in_tkt_with_password.3 | 3 + static/netbsd/man3/krb5_get_in_tkt_with_skey.3 | 3 + static/netbsd/man3/krb5_get_init_creds.3 | 405 + static/netbsd/man3/krb5_get_init_creds_keyblock.3 | 3 + static/netbsd/man3/krb5_get_init_creds_keytab.3 | 3 + static/netbsd/man3/krb5_get_init_creds_opt_alloc.3 | 3 + static/netbsd/man3/krb5_get_init_creds_opt_free.3 | 3 + .../man3/krb5_get_init_creds_opt_get_error.3 | 3 + static/netbsd/man3/krb5_get_init_creds_opt_init.3 | 3 + static/netbsd/man3/krb5_get_init_creds_password.3 | 3 + static/netbsd/man3/krb5_get_kdc_sec_offset.3 | 3 + static/netbsd/man3/krb5_get_krbhst.3 | 88 + static/netbsd/man3/krb5_get_max_time_skew.3 | 3 + static/netbsd/man3/krb5_get_use_admin_kdc.3 | 3 + static/netbsd/man3/krb5_get_validated_creds.3 | 3 + static/netbsd/man3/krb5_get_warn_dest.3 | 3 + static/netbsd/man3/krb5_getportbyname.3 | 69 + static/netbsd/man3/krb5_h_addr2addr.3 | 3 + static/netbsd/man3/krb5_h_addr2sockaddr.3 | 3 + static/netbsd/man3/krb5_h_errno_to_heim_errno.3 | 3 + static/netbsd/man3/krb5_init_context.3 | 3 + static/netbsd/man3/krb5_init_creds_free.3 | 3 + static/netbsd/man3/krb5_init_creds_get.3 | 3 + static/netbsd/man3/krb5_init_creds_get_error.3 | 3 + static/netbsd/man3/krb5_init_creds_init.3 | 3 + static/netbsd/man3/krb5_init_creds_intro.3 | 11 + static/netbsd/man3/krb5_init_creds_set_keytab.3 | 3 + static/netbsd/man3/krb5_init_creds_set_password.3 | 3 + static/netbsd/man3/krb5_init_creds_set_service.3 | 3 + static/netbsd/man3/krb5_init_creds_step.3 | 3 + static/netbsd/man3/krb5_init_ets.3 | 3 + static/netbsd/man3/krb5_introduction.3 | 262 + static/netbsd/man3/krb5_is_config_principal.3 | 3 + static/netbsd/man3/krb5_is_enctype_weak.3 | 3 + static/netbsd/man3/krb5_is_thread_safe.3 | 3 + static/netbsd/man3/krb5_kerberos_enctypes.3 | 3 + static/netbsd/man3/krb5_keyblock_get_enctype.3 | 3 + static/netbsd/man3/krb5_keyblock_init.3 | 3 + static/netbsd/man3/krb5_keyblock_zero.3 | 3 + static/netbsd/man3/krb5_keytab.3 | 473 + static/netbsd/man3/krb5_keytab_intro.3 | 73 + static/netbsd/man3/krb5_keytab_key_proc.3 | 3 + static/netbsd/man3/krb5_keytype_to_enctypes.3 | 3 + .../netbsd/man3/krb5_keytype_to_enctypes_default.3 | 3 + static/netbsd/man3/krb5_keytype_to_string.3 | 3 + static/netbsd/man3/krb5_krbhst_get_addrinfo.3 | 3 + static/netbsd/man3/krb5_krbhst_init.3 | 176 + static/netbsd/man3/krb5_kt_add_entry.3 | 3 + static/netbsd/man3/krb5_kt_close.3 | 3 + static/netbsd/man3/krb5_kt_compare.3 | 3 + static/netbsd/man3/krb5_kt_copy_entry_contents.3 | 3 + static/netbsd/man3/krb5_kt_default.3 | 3 + static/netbsd/man3/krb5_kt_default_modify_name.3 | 3 + static/netbsd/man3/krb5_kt_default_name.3 | 3 + static/netbsd/man3/krb5_kt_destroy.3 | 3 + static/netbsd/man3/krb5_kt_end_seq_get.3 | 3 + static/netbsd/man3/krb5_kt_free_entry.3 | 3 + static/netbsd/man3/krb5_kt_get_entry.3 | 3 + static/netbsd/man3/krb5_kt_get_full_name.3 | 3 + static/netbsd/man3/krb5_kt_get_name.3 | 3 + static/netbsd/man3/krb5_kt_get_type.3 | 3 + static/netbsd/man3/krb5_kt_have_content.3 | 3 + static/netbsd/man3/krb5_kt_next_entry.3 | 3 + static/netbsd/man3/krb5_kt_read_service_key.3 | 3 + static/netbsd/man3/krb5_kt_register.3 | 3 + static/netbsd/man3/krb5_kt_remove_entry.3 | 3 + static/netbsd/man3/krb5_kt_resolve.3 | 3 + static/netbsd/man3/krb5_kt_start_seq_get.3 | 3 + static/netbsd/man3/krb5_kuserok.3 | 3 + static/netbsd/man3/krb5_make_addrport.3 | 3 + static/netbsd/man3/krb5_make_principal.3 | 3 + static/netbsd/man3/krb5_max_sockaddr_size.3 | 3 + static/netbsd/man3/krb5_mcc_ops.3 | 3 + static/netbsd/man3/krb5_mk_req.3 | 189 + static/netbsd/man3/krb5_mk_safe.3 | 84 + static/netbsd/man3/krb5_openlog.3 | 244 + static/netbsd/man3/krb5_pac.3 | 72 + static/netbsd/man3/krb5_pac_get_buffer.3 | 3 + static/netbsd/man3/krb5_pac_verify.3 | 3 + static/netbsd/man3/krb5_parse_address.3 | 3 + static/netbsd/man3/krb5_parse_name.3 | 3 + static/netbsd/man3/krb5_parse_name_flags.3 | 3 + static/netbsd/man3/krb5_parse_nametype.3 | 3 + static/netbsd/man3/krb5_password_key_proc.3 | 3 + static/netbsd/man3/krb5_plugin_register.3 | 3 + .../man3/krb5_prepend_config_files_default.3 | 3 + static/netbsd/man3/krb5_prepend_error_message.3 | 3 + static/netbsd/man3/krb5_princ_realm.3 | 3 + static/netbsd/man3/krb5_princ_set_realm.3 | 3 + static/netbsd/man3/krb5_principal.3 | 540 + static/netbsd/man3/krb5_principal_compare.3 | 3 + .../netbsd/man3/krb5_principal_compare_any_realm.3 | 3 + static/netbsd/man3/krb5_principal_get_num_comp.3 | 3 + static/netbsd/man3/krb5_principal_get_realm.3 | 3 + static/netbsd/man3/krb5_principal_get_type.3 | 3 + static/netbsd/man3/krb5_principal_intro.3 | 18 + static/netbsd/man3/krb5_principal_is_anonymous.3 | 3 + .../man3/krb5_principal_is_gss_hostbased_service.3 | 3 + static/netbsd/man3/krb5_principal_is_krbtgt.3 | 3 + static/netbsd/man3/krb5_principal_is_lkdc.3 | 3 + static/netbsd/man3/krb5_principal_is_null.3 | 3 + static/netbsd/man3/krb5_principal_is_pku2u.3 | 3 + static/netbsd/man3/krb5_principal_is_root_krbtgt.3 | 3 + static/netbsd/man3/krb5_principal_match.3 | 3 + static/netbsd/man3/krb5_principal_set_realm.3 | 3 + static/netbsd/man3/krb5_principal_set_type.3 | 3 + static/netbsd/man3/krb5_print_address.3 | 3 + static/netbsd/man3/krb5_random_to_key.3 | 3 + static/netbsd/man3/krb5_rcache.3 | 165 + static/netbsd/man3/krb5_rd_error.3 | 100 + static/netbsd/man3/krb5_rd_req_ctx.3 | 3 + static/netbsd/man3/krb5_rd_req_in_ctx_alloc.3 | 3 + static/netbsd/man3/krb5_rd_req_in_set_keytab.3 | 3 + static/netbsd/man3/krb5_rd_req_in_set_pac_check.3 | 3 + static/netbsd/man3/krb5_rd_req_out_ctx_free.3 | 3 + static/netbsd/man3/krb5_rd_req_out_get_server.3 | 3 + static/netbsd/man3/krb5_rd_safe.3 | 83 + static/netbsd/man3/krb5_realm_compare.3 | 3 + static/netbsd/man3/krb5_realm_is_lkdc.3 | 3 + static/netbsd/man3/krb5_ret_address.3 | 3 + static/netbsd/man3/krb5_ret_addrs.3 | 3 + static/netbsd/man3/krb5_ret_authdata.3 | 3 + static/netbsd/man3/krb5_ret_creds.3 | 3 + static/netbsd/man3/krb5_ret_creds_tag.3 | 3 + static/netbsd/man3/krb5_ret_data.3 | 3 + static/netbsd/man3/krb5_ret_int16.3 | 3 + static/netbsd/man3/krb5_ret_int32.3 | 3 + static/netbsd/man3/krb5_ret_int64.3 | 3 + static/netbsd/man3/krb5_ret_int8.3 | 3 + static/netbsd/man3/krb5_ret_keyblock.3 | 3 + static/netbsd/man3/krb5_ret_principal.3 | 3 + static/netbsd/man3/krb5_ret_string.3 | 3 + static/netbsd/man3/krb5_ret_stringz.3 | 3 + static/netbsd/man3/krb5_ret_times.3 | 3 + static/netbsd/man3/krb5_ret_uint16.3 | 3 + static/netbsd/man3/krb5_ret_uint32.3 | 3 + static/netbsd/man3/krb5_ret_uint64.3 | 3 + static/netbsd/man3/krb5_ret_uint8.3 | 3 + static/netbsd/man3/krb5_set_config_files.3 | 3 + .../netbsd/man3/krb5_set_default_in_tkt_etypes.3 | 3 + static/netbsd/man3/krb5_set_default_realm.3 | 166 + .../man3/krb5_set_dns_canonicalize_hostname.3 | 3 + static/netbsd/man3/krb5_set_error_message.3 | 3 + static/netbsd/man3/krb5_set_error_string.3 | 3 + static/netbsd/man3/krb5_set_extra_addresses.3 | 3 + static/netbsd/man3/krb5_set_fcache_version.3 | 3 + static/netbsd/man3/krb5_set_home_dir_access.3 | 3 + static/netbsd/man3/krb5_set_ignore_addresses.3 | 3 + static/netbsd/man3/krb5_set_kdc_sec_offset.3 | 3 + static/netbsd/man3/krb5_set_max_time_skew.3 | 3 + static/netbsd/man3/krb5_set_password.3 | 3 + static/netbsd/man3/krb5_set_real_time.3 | 3 + static/netbsd/man3/krb5_set_use_admin_kdc.3 | 3 + static/netbsd/man3/krb5_set_warn_dest.3 | 3 + static/netbsd/man3/krb5_sname_to_principal.3 | 3 + static/netbsd/man3/krb5_sockaddr2address.3 | 3 + static/netbsd/man3/krb5_sockaddr2port.3 | 3 + static/netbsd/man3/krb5_sockaddr_uninteresting.3 | 3 + static/netbsd/man3/krb5_storage.3 | 1136 + static/netbsd/man3/krb5_storage_clear_flags.3 | 3 + static/netbsd/man3/krb5_storage_emem.3 | 3 + static/netbsd/man3/krb5_storage_free.3 | 3 + static/netbsd/man3/krb5_storage_from_data.3 | 3 + static/netbsd/man3/krb5_storage_from_fd.3 | 3 + static/netbsd/man3/krb5_storage_from_mem.3 | 3 + .../netbsd/man3/krb5_storage_from_readonly_mem.3 | 3 + static/netbsd/man3/krb5_storage_from_socket.3 | 3 + static/netbsd/man3/krb5_storage_fsync.3 | 3 + static/netbsd/man3/krb5_storage_get_byteorder.3 | 3 + static/netbsd/man3/krb5_storage_get_eof_code.3 | 3 + static/netbsd/man3/krb5_storage_is_flags.3 | 3 + static/netbsd/man3/krb5_storage_read.3 | 3 + static/netbsd/man3/krb5_storage_seek.3 | 3 + static/netbsd/man3/krb5_storage_set_byteorder.3 | 3 + static/netbsd/man3/krb5_storage_set_eof_code.3 | 3 + static/netbsd/man3/krb5_storage_set_flags.3 | 3 + static/netbsd/man3/krb5_storage_set_max_alloc.3 | 3 + static/netbsd/man3/krb5_storage_to_data.3 | 3 + static/netbsd/man3/krb5_storage_truncate.3 | 3 + static/netbsd/man3/krb5_storage_write.3 | 3 + static/netbsd/man3/krb5_store_address.3 | 3 + static/netbsd/man3/krb5_store_addrs.3 | 3 + static/netbsd/man3/krb5_store_authdata.3 | 3 + static/netbsd/man3/krb5_store_creds.3 | 3 + static/netbsd/man3/krb5_store_creds_tag.3 | 3 + static/netbsd/man3/krb5_store_data.3 | 3 + static/netbsd/man3/krb5_store_int16.3 | 3 + static/netbsd/man3/krb5_store_int32.3 | 3 + static/netbsd/man3/krb5_store_int64.3 | 3 + static/netbsd/man3/krb5_store_int8.3 | 3 + static/netbsd/man3/krb5_store_keyblock.3 | 3 + static/netbsd/man3/krb5_store_principal.3 | 3 + static/netbsd/man3/krb5_store_string.3 | 3 + static/netbsd/man3/krb5_store_stringz.3 | 3 + static/netbsd/man3/krb5_store_times.3 | 3 + static/netbsd/man3/krb5_store_uint16.3 | 3 + static/netbsd/man3/krb5_store_uint32.3 | 3 + static/netbsd/man3/krb5_store_uint64.3 | 3 + static/netbsd/man3/krb5_store_uint8.3 | 3 + static/netbsd/man3/krb5_string_to_key.3 | 158 + static/netbsd/man3/krb5_string_to_keytype.3 | 3 + static/netbsd/man3/krb5_support.3 | 668 + static/netbsd/man3/krb5_ticket.3 | 41 + .../man3/krb5_ticket_get_authorization_data_type.3 | 3 + static/netbsd/man3/krb5_ticket_get_client.3 | 3 + static/netbsd/man3/krb5_ticket_get_endtime.3 | 3 + static/netbsd/man3/krb5_ticket_get_flags.3 | 3 + static/netbsd/man3/krb5_ticket_get_server.3 | 3 + static/netbsd/man3/krb5_timeofday.3 | 120 + static/netbsd/man3/krb5_unparse_name.3 | 3 + static/netbsd/man3/krb5_unparse_name_fixed.3 | 3 + static/netbsd/man3/krb5_unparse_name_fixed_flags.3 | 3 + static/netbsd/man3/krb5_unparse_name_fixed_short.3 | 3 + static/netbsd/man3/krb5_unparse_name_flags.3 | 3 + static/netbsd/man3/krb5_unparse_name_short.3 | 3 + static/netbsd/man3/krb5_v4compat.3 | 66 + static/netbsd/man3/krb5_vabort.3 | 3 + static/netbsd/man3/krb5_verify_checksum_iov.3 | 3 + static/netbsd/man3/krb5_verify_init_creds.3 | 105 + static/netbsd/man3/krb5_verify_user.3 | 243 + static/netbsd/man3/krb5_verr.3 | 3 + static/netbsd/man3/krb5_verrx.3 | 3 + static/netbsd/man3/krb5_vprepend_error_message.3 | 3 + static/netbsd/man3/krb5_vset_error_message.3 | 3 + static/netbsd/man3/krb5_vset_error_string.3 | 3 + static/netbsd/man3/krb5_vwarn.3 | 3 + static/netbsd/man3/krb5_vwarnx.3 | 3 + static/netbsd/man3/krb5_warn.3 | 3 + static/netbsd/man3/krb5_warnx.3 | 3 + static/netbsd/man3/krb5plugin_an2ln_ftable_desc.3 | 54 + static/netbsd/man3/krb5plugin_db_ftable_desc.3 | 35 + .../netbsd/man3/krb5plugin_kuserok_ftable_desc.3 | 58 + static/netbsd/man3/kvm.3 | 110 + static/netbsd/man3/kvm_dump.3 | 109 + static/netbsd/man3/kvm_geterr.3 | 79 + static/netbsd/man3/kvm_getfiles.3 | 87 + static/netbsd/man3/kvm_getkernelname.3 | 67 + static/netbsd/man3/kvm_getloadavg.3 | 71 + static/netbsd/man3/kvm_getlwps.3 | 102 + static/netbsd/man3/kvm_getprocs.3 | 239 + static/netbsd/man3/kvm_nlist.3 | 93 + static/netbsd/man3/kvm_open.3 | 237 + static/netbsd/man3/kvm_read.3 | 93 + static/netbsd/man3/lber-decode.3 | 357 + static/netbsd/man3/lber-encode.3 | 288 + static/netbsd/man3/lber-memory.3 | 49 + static/netbsd/man3/lber-sockbuf.3 | 199 + static/netbsd/man3/lber-types.3 | 188 + static/netbsd/man3/ldap.3 | 278 + static/netbsd/man3/ldap_abandon.3 | 69 + static/netbsd/man3/ldap_add.3 | 81 + static/netbsd/man3/ldap_bind.3 | 337 + static/netbsd/man3/ldap_compare.3 | 79 + static/netbsd/man3/ldap_controls.3 | 84 + static/netbsd/man3/ldap_delete.3 | 89 + static/netbsd/man3/ldap_dup.3 | 125 + static/netbsd/man3/ldap_error.3 | 224 + static/netbsd/man3/ldap_extended_operation.3 | 75 + static/netbsd/man3/ldap_first_attribute.3 | 97 + static/netbsd/man3/ldap_first_entry.3 | 80 + static/netbsd/man3/ldap_first_message.3 | 82 + static/netbsd/man3/ldap_first_reference.3 | 71 + static/netbsd/man3/ldap_get_dn.3 | 246 + static/netbsd/man3/ldap_get_option.3 | 933 + static/netbsd/man3/ldap_get_values.3 | 102 + static/netbsd/man3/ldap_memory.3 | 50 + static/netbsd/man3/ldap_modify.3 | 134 + static/netbsd/man3/ldap_modrdn.3 | 81 + static/netbsd/man3/ldap_open.3 | 236 + static/netbsd/man3/ldap_parse_reference.3 | 61 + static/netbsd/man3/ldap_parse_result.3 | 114 + static/netbsd/man3/ldap_parse_sort_control.3 | 40 + static/netbsd/man3/ldap_parse_vlv_control.3 | 49 + static/netbsd/man3/ldap_rename.3 | 66 + static/netbsd/man3/ldap_result.3 | 136 + static/netbsd/man3/ldap_schema.3 | 320 + static/netbsd/man3/ldap_search.3 | 144 + static/netbsd/man3/ldap_sort.3 | 21 + static/netbsd/man3/ldap_sync.3 | 326 + static/netbsd/man3/ldap_tls.3 | 41 + static/netbsd/man3/ldap_url.3 | 83 + static/netbsd/man3/ldexp.3 | 105 + static/netbsd/man3/length.3 | 3 + static/netbsd/man3/lgamma.3 | 165 + static/netbsd/man3/lh_stats.3 | 192 + static/netbsd/man3/libarchive.3 | 297 + static/netbsd/man3/libarchive_changes.3 | 339 + static/netbsd/man3/libarchive_internals.3 | 363 + static/netbsd/man3/libblocklist.3 | 177 + static/netbsd/man3/libbozohttpd.3 | 150 + static/netbsd/man3/libiscsi.3 | 162 + static/netbsd/man3/libmagic.3 | 439 + static/netbsd/man3/libmj.3 | 283 + static/netbsd/man3/libnetpgp.3 | 394 + static/netbsd/man3/libnetpgpbn.3 | 304 + static/netbsd/man3/libnetpgprsa.3 | 113 + static/netbsd/man3/libnetpgpverify.3 | 146 + static/netbsd/man3/libnpf.3 | 506 + static/netbsd/man3/libnvmm.3 | 739 + static/netbsd/man3/libpaa.3 | 117 + static/netbsd/man3/libperfuse.3 | 139 + static/netbsd/man3/libquota.3 | 482 + static/netbsd/man3/libradius.3 | 556 + static/netbsd/man3/librtld_db.3 | 194 + static/netbsd/man3/libsaslc.3 | 820 + static/netbsd/man3/libuv.3 | 10855 +++++++++ static/netbsd/man3/linkaddr.3 | 137 + static/netbsd/man3/lio_listio.3 | 172 + static/netbsd/man3/lockf.3 | 262 + static/netbsd/man3/log.3 | 188 + static/netbsd/man3/login.3 | 107 + static/netbsd/man3/login_cap.3 | 304 + static/netbsd/man3/loginx.3 | 93 + static/netbsd/man3/lrint.3 | 115 + static/netbsd/man3/lsearch.3 | 97 + static/netbsd/man3/makecontext.3 | 169 + static/netbsd/man3/malloc.3 | 319 + static/netbsd/man3/man.cgi.3 | 310 + static/netbsd/man3/mandoc.3 | 574 + static/netbsd/man3/mandoc_escape.3 | 367 + static/netbsd/man3/mandoc_headers.3 | 746 + static/netbsd/man3/mandoc_html.3 | 552 + static/netbsd/man3/mandoc_malloc.3 | 210 + static/netbsd/man3/mansearch.3 | 120 + static/netbsd/man3/math.3 | 587 + static/netbsd/man3/mblen.3 | 181 + static/netbsd/man3/mbrlen.3 | 206 + static/netbsd/man3/mbrtoc16.3 | 312 + static/netbsd/man3/mbrtoc32.3 | 271 + static/netbsd/man3/mbrtoc8.3 | 311 + static/netbsd/man3/mbrtowc.3 | 196 + static/netbsd/man3/mbsinit.3 | 74 + static/netbsd/man3/mbsrtowcs.3 | 225 + static/netbsd/man3/mbstowcs.3 | 129 + static/netbsd/man3/mbtowc.3 | 182 + static/netbsd/man3/mchars_alloc.3 | 227 + static/netbsd/man3/md2.3 | 128 + static/netbsd/man3/mdX.3 | 146 + static/netbsd/man3/membar_ops.3 | 393 + static/netbsd/man3/memccpy.3 | 78 + static/netbsd/man3/memchr.3 | 94 + static/netbsd/man3/memcmp.3 | 91 + static/netbsd/man3/memcpy.3 | 86 + static/netbsd/man3/memmem.3 | 82 + static/netbsd/man3/memmove.3 | 74 + static/netbsd/man3/memory.3 | 68 + static/netbsd/man3/memset.3 | 80 + static/netbsd/man3/menu_attributes.3 | 135 + static/netbsd/man3/menu_cursor.3 | 91 + static/netbsd/man3/menu_driver.3 | 136 + static/netbsd/man3/menu_format.3 | 77 + static/netbsd/man3/menu_hook.3 | 103 + static/netbsd/man3/menu_item_current.3 | 101 + static/netbsd/man3/menu_item_name.3 | 71 + static/netbsd/man3/menu_item_new.3 | 79 + static/netbsd/man3/menu_item_opts.3 | 82 + static/netbsd/man3/menu_item_userptr.3 | 72 + static/netbsd/man3/menu_item_value.3 | 106 + static/netbsd/man3/menu_item_visible.3 | 67 + static/netbsd/man3/menu_items.3 | 90 + static/netbsd/man3/menu_mark.3 | 112 + static/netbsd/man3/menu_new.3 | 85 + static/netbsd/man3/menu_opts.3 | 97 + static/netbsd/man3/menu_pattern.3 | 77 + static/netbsd/man3/menu_post.3 | 98 + static/netbsd/man3/menu_userptr.3 | 73 + static/netbsd/man3/menu_win.3 | 115 + static/netbsd/man3/menus.3 | 299 + static/netbsd/man3/mi_vector_hash.3 | 65 + static/netbsd/man3/mktemp.3 | 390 + static/netbsd/man3/modf.3 | 78 + static/netbsd/man3/modrdn.out.provider.3 | 19 + static/netbsd/man3/moncontrol.3 | 115 + static/netbsd/man3/move_panel.3 | 70 + static/netbsd/man3/mpool.3 | 226 + static/netbsd/man3/mq.3 | 354 + static/netbsd/man3/mq_close.3 | 65 + static/netbsd/man3/mq_getattr.3 | 86 + static/netbsd/man3/mq_notify.3 | 90 + static/netbsd/man3/mq_open.3 | 273 + static/netbsd/man3/mq_receive.3 | 172 + static/netbsd/man3/mq_send.3 | 202 + static/netbsd/man3/mq_setattr.3 | 103 + static/netbsd/man3/mq_unlink.3 | 92 + static/netbsd/man3/mtx.3 | 219 + static/netbsd/man3/nan.3 | 95 + static/netbsd/man3/new_panel.3 | 82 + static/netbsd/man3/newlocale.3 | 126 + static/netbsd/man3/nextafter.3 | 132 + static/netbsd/man3/ngettext.3 | 60 + static/netbsd/man3/nice.3 | 93 + static/netbsd/man3/nl_langinfo.3 | 149 + static/netbsd/man3/nlist.3 | 80 + static/netbsd/man3/nsdispatch.3 | 959 + static/netbsd/man3/ntlm_buf.3 | 47 + static/netbsd/man3/ntlm_core.3 | 474 + static/netbsd/man3/ntlm_type1.3 | 23 + static/netbsd/man3/ntlm_type2.3 | 23 + static/netbsd/man3/ntlm_type3.3 | 23 + static/netbsd/man3/o2i_SCT_LIST.3 | 107 + static/netbsd/man3/offtime.3 | 81 + static/netbsd/man3/ohash_init.3 | 229 + static/netbsd/man3/ohash_interval.3 | 90 + static/netbsd/man3/omapi.3 | 249 + static/netbsd/man3/open_memstream.3 | 155 + static/netbsd/man3/opendisk.3 | 233 + static/netbsd/man3/openpam.3 | 135 + static/netbsd/man3/openpam_borrow_cred.3 | 65 + static/netbsd/man3/openpam_free_data.3 | 47 + static/netbsd/man3/openpam_free_envlist.3 | 37 + static/netbsd/man3/openpam_get_feature.3 | 72 + static/netbsd/man3/openpam_get_option.3 | 49 + static/netbsd/man3/openpam_log.3 | 92 + static/netbsd/man3/openpam_nullconv.3 | 71 + static/netbsd/man3/openpam_readline.3 | 90 + static/netbsd/man3/openpam_readlinev.3 | 124 + static/netbsd/man3/openpam_readword.3 | 117 + static/netbsd/man3/openpam_restore_cred.3 | 57 + static/netbsd/man3/openpam_set_feature.3 | 54 + static/netbsd/man3/openpam_set_option.3 | 54 + static/netbsd/man3/openpam_straddch.3 | 104 + static/netbsd/man3/openpam_subst.3 | 107 + static/netbsd/man3/openpam_ttyconv.3 | 69 + static/netbsd/man3/openpty.3 | 178 + static/netbsd/man3/openssl-DES_random_key.3 | 391 + static/netbsd/man3/openssl-HMAC.3 | 234 + static/netbsd/man3/openssl-MD5.3 | 173 + static/netbsd/man3/openssl_HMAC.3 | 284 + static/netbsd/man3/openssl_MD5.3 | 231 + static/netbsd/man3/openssl_bio.3 | 218 + static/netbsd/man3/openssl_blowfish.3 | 242 + static/netbsd/man3/openssl_bn.3 | 315 + static/netbsd/man3/openssl_bn_internal.3 | 369 + static/netbsd/man3/openssl_buffer.3 | 208 + static/netbsd/man3/openssl_des.3 | 486 + static/netbsd/man3/openssl_dh.3 | 214 + static/netbsd/man3/openssl_dsa.3 | 249 + static/netbsd/man3/openssl_ecdsa.3 | 349 + static/netbsd/man3/openssl_engine.3 | 746 + static/netbsd/man3/openssl_err.3 | 321 + static/netbsd/man3/openssl_evp.3 | 236 + static/netbsd/man3/openssl_lhash.3 | 439 + static/netbsd/man3/openssl_mdc2.3 | 195 + static/netbsd/man3/openssl_pem.3 | 661 + static/netbsd/man3/openssl_rand.3 | 290 + static/netbsd/man3/openssl_rc4.3 | 193 + static/netbsd/man3/openssl_ripemd.3 | 197 + static/netbsd/man3/openssl_rsa.3 | 257 + static/netbsd/man3/openssl_sha.3 | 235 + static/netbsd/man3/openssl_threads.3 | 330 + static/netbsd/man3/openssl_ui.3 | 326 + static/netbsd/man3/openssl_ui_compat.3 | 189 + static/netbsd/man3/openssl_x509.3 | 198 + static/netbsd/man3/ossaudio.3 | 147 + static/netbsd/man3/p.3 | 1 + static/netbsd/man3/p2k.3 | 141 + static/netbsd/man3/page_ca.3 | 8 + static/netbsd/man3/page_cert.3 | 12 + static/netbsd/man3/page_cms.3 | 20 + static/netbsd/man3/page_des.3 | 38 + static/netbsd/man3/page_dh.3 | 12 + static/netbsd/man3/page_env.3 | 8 + static/netbsd/man3/page_error.3 | 8 + static/netbsd/man3/page_evp.3 | 11 + static/netbsd/man3/page_keyset.3 | 27 + static/netbsd/man3/page_lock.3 | 8 + static/netbsd/man3/page_name.3 | 20 + static/netbsd/man3/page_peer.3 | 10 + static/netbsd/man3/page_print.3 | 8 + static/netbsd/man3/page_rand.3 | 8 + static/netbsd/man3/page_revoke.3 | 12 + static/netbsd/man3/page_rsa.3 | 15 + static/netbsd/man3/pam.3 | 268 + static/netbsd/man3/pam_acct_mgmt.3 | 85 + static/netbsd/man3/pam_authenticate.3 | 99 + static/netbsd/man3/pam_chauthtok.3 | 91 + static/netbsd/man3/pam_close_session.3 | 81 + static/netbsd/man3/pam_conv.3 | 187 + static/netbsd/man3/pam_end.3 | 57 + static/netbsd/man3/pam_error.3 | 57 + static/netbsd/man3/pam_get_authtok.3 | 165 + static/netbsd/man3/pam_get_data.3 | 70 + static/netbsd/man3/pam_get_item.3 | 113 + static/netbsd/man3/pam_get_user.3 | 109 + static/netbsd/man3/pam_getenv.3 | 53 + static/netbsd/man3/pam_getenvlist.3 | 75 + static/netbsd/man3/pam_info.3 | 57 + static/netbsd/man3/pam_open_session.3 | 82 + static/netbsd/man3/pam_prompt.3 | 69 + static/netbsd/man3/pam_putenv.3 | 60 + static/netbsd/man3/pam_set_data.3 | 72 + static/netbsd/man3/pam_set_item.3 | 63 + static/netbsd/man3/pam_setcred.3 | 94 + static/netbsd/man3/pam_setenv.3 | 59 + static/netbsd/man3/pam_sm_acct_mgmt.3 | 75 + static/netbsd/man3/pam_sm_authenticate.3 | 77 + static/netbsd/man3/pam_sm_chauthtok.3 | 87 + static/netbsd/man3/pam_sm_close_session.3 | 69 + static/netbsd/man3/pam_sm_open_session.3 | 69 + static/netbsd/man3/pam_sm_setcred.3 | 75 + static/netbsd/man3/pam_start.3 | 81 + static/netbsd/man3/pam_strerror.3 | 58 + static/netbsd/man3/pam_verror.3 | 61 + static/netbsd/man3/pam_vinfo.3 | 61 + static/netbsd/man3/pam_vprompt.3 | 98 + static/netbsd/man3/panel.3 | 75 + static/netbsd/man3/panel_above.3 | 102 + static/netbsd/man3/panel_hidden.3 | 98 + static/netbsd/man3/panel_userptr.3 | 65 + static/netbsd/man3/parse_time.3 | 175 + static/netbsd/man3/parsedate.3 | 513 + static/netbsd/man3/pause.3 | 92 + static/netbsd/man3/pci.3 | 203 + static/netbsd/man3/pidfile.3 | 173 + static/netbsd/man3/pidlock.3 | 184 + static/netbsd/man3/popcount.3 | 71 + static/netbsd/man3/popen.3 | 228 + static/netbsd/man3/posix1e.3 | 93 + static/netbsd/man3/posix_memalign.3 | 133 + static/netbsd/man3/posix_openpt.3 | 106 + static/netbsd/man3/posix_spawn.3 | 488 + .../man3/posix_spawn_file_actions_addchdir.3 | 162 + .../netbsd/man3/posix_spawn_file_actions_addopen.3 | 190 + static/netbsd/man3/posix_spawn_file_actions_init.3 | 112 + static/netbsd/man3/posix_spawnattr_getflags.3 | 115 + static/netbsd/man3/posix_spawnattr_getpgroup.3 | 100 + static/netbsd/man3/posix_spawnattr_getschedparam.3 | 104 + .../netbsd/man3/posix_spawnattr_getschedpolicy.3 | 102 + static/netbsd/man3/posix_spawnattr_getsigdefault.3 | 102 + static/netbsd/man3/posix_spawnattr_getsigmask.3 | 101 + static/netbsd/man3/posix_spawnattr_init.3 | 127 + static/netbsd/man3/pow.3 | 83 + static/netbsd/man3/ppath.3 | 440 + static/netbsd/man3/ppath_bool.3 | 235 + static/netbsd/man3/ppath_number.3 | 280 + static/netbsd/man3/ppath_object.3 | 278 + static/netbsd/man3/printf.3 | 1015 + static/netbsd/man3/printf_l.3 | 85 + static/netbsd/man3/proc_compare.3 | 107 + static/netbsd/man3/prop_array.3 | 265 + static/netbsd/man3/prop_array_util.3 | 404 + static/netbsd/man3/prop_bool.3 | 87 + static/netbsd/man3/prop_data.3 | 154 + static/netbsd/man3/prop_dictionary.3 | 308 + static/netbsd/man3/prop_dictionary_util.3 | 330 + static/netbsd/man3/prop_ingest.3 | 181 + static/netbsd/man3/prop_number.3 | 297 + static/netbsd/man3/prop_object.3 | 219 + static/netbsd/man3/prop_send_ioctl.3 | 143 + static/netbsd/man3/prop_send_syscall.3 | 128 + static/netbsd/man3/prop_string.3 | 174 + static/netbsd/man3/proplib.3 | 167 + static/netbsd/man3/pset.3 | 277 + static/netbsd/man3/psignal.3 | 105 + static/netbsd/man3/pthread.3 | 176 + static/netbsd/man3/pthread_atfork.3 | 129 + static/netbsd/man3/pthread_attr.3 | 156 + static/netbsd/man3/pthread_attr_get_np.3 | 122 + static/netbsd/man3/pthread_attr_getdetachstate.3 | 118 + static/netbsd/man3/pthread_attr_getguardsize.3 | 149 + static/netbsd/man3/pthread_attr_getinheritsched.3 | 113 + static/netbsd/man3/pthread_attr_getname_np.3 | 110 + static/netbsd/man3/pthread_attr_getschedparam.3 | 127 + static/netbsd/man3/pthread_attr_getscope.3 | 98 + static/netbsd/man3/pthread_attr_getstack.3 | 203 + .../netbsd/man3/pthread_attr_setcreatesuspend_np.3 | 66 + static/netbsd/man3/pthread_barrier.3 | 166 + static/netbsd/man3/pthread_barrierattr.3 | 114 + static/netbsd/man3/pthread_cancel.3 | 134 + static/netbsd/man3/pthread_cleanup_push.3 | 118 + static/netbsd/man3/pthread_cond.3 | 281 + static/netbsd/man3/pthread_condattr.3 | 167 + static/netbsd/man3/pthread_create.3 | 164 + static/netbsd/man3/pthread_curcpu_np.3 | 66 + static/netbsd/man3/pthread_detach.3 | 108 + static/netbsd/man3/pthread_equal.3 | 92 + static/netbsd/man3/pthread_exit.3 | 129 + static/netbsd/man3/pthread_getcpuclockid.3 | 82 + static/netbsd/man3/pthread_getname_np.3 | 108 + static/netbsd/man3/pthread_getspecific.3 | 124 + static/netbsd/man3/pthread_join.3 | 134 + static/netbsd/man3/pthread_key_create.3 | 195 + static/netbsd/man3/pthread_kill.3 | 102 + static/netbsd/man3/pthread_mutex.3 | 304 + static/netbsd/man3/pthread_mutexattr.3 | 302 + static/netbsd/man3/pthread_once.3 | 128 + static/netbsd/man3/pthread_rwlock.3 | 355 + static/netbsd/man3/pthread_rwlockattr.3 | 138 + static/netbsd/man3/pthread_schedparam.3 | 120 + static/netbsd/man3/pthread_self.3 | 83 + static/netbsd/man3/pthread_sigmask.3 | 122 + static/netbsd/man3/pthread_spin.3 | 213 + static/netbsd/man3/pthread_suspend_np.3 | 120 + static/netbsd/man3/pthread_testcancel.3 | 271 + static/netbsd/man3/ptsname.3 | 168 + static/netbsd/man3/puffs.3 | 595 + static/netbsd/man3/puffs_cc.3 | 94 + static/netbsd/man3/puffs_cred.3 | 167 + static/netbsd/man3/puffs_flush.3 | 113 + static/netbsd/man3/puffs_framebuf.3 | 620 + static/netbsd/man3/puffs_node.3 | 101 + static/netbsd/man3/puffs_ops.3 | 989 + static/netbsd/man3/puffs_path.3 | 125 + static/netbsd/man3/putc.3 | 176 + static/netbsd/man3/putwc.3 | 101 + static/netbsd/man3/pw_gensalt.3 | 184 + static/netbsd/man3/pw_getconf.3 | 111 + static/netbsd/man3/pw_init.3 | 233 + static/netbsd/man3/pw_lock.3 | 139 + static/netbsd/man3/pwcache.3 | 224 + static/netbsd/man3/qabs.3 | 63 + static/netbsd/man3/qdiv.3 | 67 + static/netbsd/man3/qsort.3 | 279 + static/netbsd/man3/quick_exit.3 | 68 + static/netbsd/man3/radixsort.3 | 167 + static/netbsd/man3/raise.3 | 80 + static/netbsd/man3/raise_default_signal.3 | 116 + static/netbsd/man3/rand.3 | 100 + static/netbsd/man3/rand48.3 | 163 + static/netbsd/man3/random.3 | 191 + static/netbsd/man3/randomid.3 | 148 + static/netbsd/man3/rcmd.3 | 311 + static/netbsd/man3/re_comp.3 | 127 + static/netbsd/man3/readline.3 | 1597 ++ static/netbsd/man3/readpassphrase.3 | 118 + static/netbsd/man3/reallocarr.3 | 177 + static/netbsd/man3/reallocarray.3 | 123 + static/netbsd/man3/realpath.3 | 163 + static/netbsd/man3/recno.3 | 214 + static/netbsd/man3/refuse.3 | 288 + static/netbsd/man3/regex.3 | 538 + static/netbsd/man3/regexp.3 | 322 + static/netbsd/man3/remainder.3 | 152 + static/netbsd/man3/remove.3 | 87 + static/netbsd/man3/resolver.3 | 669 + static/netbsd/man3/rexec.3 | 115 + static/netbsd/man3/rindex.3 | 102 + static/netbsd/man3/rint.3 | 96 + static/netbsd/man3/rmd160.3 | 225 + static/netbsd/man3/rmtops.3 | 184 + static/netbsd/man3/round.3 | 79 + static/netbsd/man3/rpc.3 | 416 + static/netbsd/man3/rpc.h.3 | 893 + static/netbsd/man3/rpc_clnt_auth.3 | 108 + static/netbsd/man3/rpc_clnt_calls.3 | 296 + static/netbsd/man3/rpc_clnt_create.3 | 443 + static/netbsd/man3/rpc_compat.h.3 | 25 + static/netbsd/man3/rpc_soc.3 | 1067 + static/netbsd/man3/rpc_svc_calls.3 | 253 + static/netbsd/man3/rpc_svc_create.3 | 315 + static/netbsd/man3/rpc_svc_err.3 | 101 + static/netbsd/man3/rpc_svc_reg.3 | 196 + static/netbsd/man3/rpc_xdr.3 | 100 + static/netbsd/man3/rpcbind.3 | 201 + static/netbsd/man3/rs256_pk_new.3 | 160 + static/netbsd/man3/rtbl.3 | 203 + static/netbsd/man3/rump.3 | 55 + static/netbsd/man3/rump_etfs.3 | 213 + static/netbsd/man3/rump_lwproc.3 | 145 + static/netbsd/man3/rumpclient.3 | 204 + static/netbsd/man3/rumphijack.3 | 243 + static/netbsd/man3/rumpuser.3 | 777 + static/netbsd/man3/run_query.3 | 208 + static/netbsd/man3/s2i_ASN1_IA5STRING.3 | 157 + static/netbsd/man3/scalbn.3 | 108 + static/netbsd/man3/scandir.3 | 122 + static/netbsd/man3/scanf.3 | 478 + static/netbsd/man3/scanf_l.3 | 74 + static/netbsd/man3/sched.3 | 335 + static/netbsd/man3/sctp_bindx.3 | 120 + static/netbsd/man3/sctp_connectx.3 | 111 + static/netbsd/man3/sctp_freepaddrs.3 | 74 + static/netbsd/man3/sctp_getaddrlen.3 | 93 + static/netbsd/man3/sctp_getassocid.3 | 79 + static/netbsd/man3/sctp_getpaddrs.3 | 106 + static/netbsd/man3/sctp_opt_info.3 | 129 + static/netbsd/man3/sctp_peeloff.3 | 85 + static/netbsd/man3/sctp_recvmsg.3 | 308 + static/netbsd/man3/sctp_send.3 | 368 + static/netbsd/man3/sctp_sendmsg.3 | 346 + static/netbsd/man3/sdp.3 | 260 + static/netbsd/man3/sdp_data.3 | 393 + static/netbsd/man3/secure_path.3 | 71 + static/netbsd/man3/sem_destroy.3 | 82 + static/netbsd/man3/sem_getvalue.3 | 76 + static/netbsd/man3/sem_init.3 | 91 + static/netbsd/man3/sem_open.3 | 227 + static/netbsd/man3/sem_post.3 | 74 + static/netbsd/man3/sem_wait.3 | 108 + static/netbsd/man3/setbuf.3 | 225 + static/netbsd/man3/setjmp.3 | 238 + static/netbsd/man3/setlocale.3 | 406 + static/netbsd/man3/setmode.3 | 149 + static/netbsd/man3/setproctitle.3 | 99 + static/netbsd/man3/setruid.3 | 78 + static/netbsd/man3/sha1.3 | 225 + static/netbsd/man3/sha2.3 | 314 + static/netbsd/man3/sha3.3 | 129 + static/netbsd/man3/shm_open.3 | 240 + static/netbsd/man3/shquote.3 | 244 + static/netbsd/man3/sigblock.3 | 119 + static/netbsd/man3/sighold.3 | 80 + static/netbsd/man3/sigignore.3 | 85 + static/netbsd/man3/siginterrupt.3 | 105 + static/netbsd/man3/signal.3 | 204 + static/netbsd/man3/signalname.3 | 150 + static/netbsd/man3/signbit.3 | 75 + static/netbsd/man3/sigpause.3 | 75 + static/netbsd/man3/sigrelse.3 | 80 + static/netbsd/man3/sigset.3 | 125 + static/netbsd/man3/sigsetmask.3 | 140 + static/netbsd/man3/sigsetops.3 | 124 + static/netbsd/man3/sigvec.3 | 313 + static/netbsd/man3/sin.3 | 81 + static/netbsd/man3/sincos.3 | 85 + static/netbsd/man3/sinh.3 | 78 + static/netbsd/man3/skey.3 | 257 + static/netbsd/man3/sleep.3 | 77 + static/netbsd/man3/smp.3 | 23 + static/netbsd/man3/snprintb.3 | 488 + static/netbsd/man3/sockaddr_snprintf.3 | 257 + static/netbsd/man3/sockatmark.3 | 103 + static/netbsd/man3/sqlite3.3 | 41 + static/netbsd/man3/sqlite3_aggregate_context.3 | 61 + static/netbsd/man3/sqlite3_aggregate_count.3 | 61 + static/netbsd/man3/sqlite3_api_routines.3 | 20 + static/netbsd/man3/sqlite3_auto_extension.3 | 64 + static/netbsd/man3/sqlite3_autovacuum_pages.3 | 82 + static/netbsd/man3/sqlite3_backup.3 | 24 + static/netbsd/man3/sqlite3_backup_init.3 | 253 + static/netbsd/man3/sqlite3_bind_blob.3 | 293 + static/netbsd/man3/sqlite3_bind_parameter_count.3 | 36 + static/netbsd/man3/sqlite3_bind_parameter_index.3 | 34 + static/netbsd/man3/sqlite3_bind_parameter_name.3 | 46 + static/netbsd/man3/sqlite3_blob.3 | 36 + static/netbsd/man3/sqlite3_blob_bytes.3 | 35 + static/netbsd/man3/sqlite3_blob_close.3 | 42 + static/netbsd/man3/sqlite3_blob_open.3 | 146 + static/netbsd/man3/sqlite3_blob_read.3 | 58 + static/netbsd/man3/sqlite3_blob_reopen.3 | 53 + static/netbsd/man3/sqlite3_blob_write.3 | 77 + static/netbsd/man3/sqlite3_busy_handler.3 | 82 + static/netbsd/man3/sqlite3_busy_timeout.3 | 43 + static/netbsd/man3/sqlite3_cancel_auto_extension.3 | 25 + static/netbsd/man3/sqlite3_changegroup.3 | 18 + static/netbsd/man3/sqlite3_changes.3 | 77 + static/netbsd/man3/sqlite3_changeset_iter.3 | 18 + static/netbsd/man3/sqlite3_clear_bindings.3 | 27 + static/netbsd/man3/sqlite3_close.3 | 73 + static/netbsd/man3/sqlite3_collation_needed.3 | 66 + static/netbsd/man3/sqlite3_column_blob.3 | 356 + static/netbsd/man3/sqlite3_column_count.3 | 31 + static/netbsd/man3/sqlite3_column_database_name.3 | 100 + static/netbsd/man3/sqlite3_column_decltype.3 | 55 + static/netbsd/man3/sqlite3_column_name.3 | 58 + static/netbsd/man3/sqlite3_commit_hook.3 | 84 + static/netbsd/man3/sqlite3_compileoption_used.3 | 48 + static/netbsd/man3/sqlite3_complete.3 | 61 + static/netbsd/man3/sqlite3_config.3 | 59 + static/netbsd/man3/sqlite3_context.3 | 34 + static/netbsd/man3/sqlite3_context_db_handle.3 | 29 + static/netbsd/man3/sqlite3_create_collation.3 | 159 + static/netbsd/man3/sqlite3_create_filename.3 | 93 + static/netbsd/man3/sqlite3_create_function.3 | 243 + static/netbsd/man3/sqlite3_create_module.3 | 75 + static/netbsd/man3/sqlite3_data_count.3 | 40 + static/netbsd/man3/sqlite3_data_directory.3 | 52 + static/netbsd/man3/sqlite3_database_file_object.3 | 36 + static/netbsd/man3/sqlite3_db_cacheflush.3 | 56 + static/netbsd/man3/sqlite3_db_config.3 | 39 + static/netbsd/man3/sqlite3_db_filename.3 | 57 + static/netbsd/man3/sqlite3_db_handle.3 | 31 + static/netbsd/man3/sqlite3_db_mutex.3 | 27 + static/netbsd/man3/sqlite3_db_name.3 | 43 + static/netbsd/man3/sqlite3_db_readonly.3 | 23 + static/netbsd/man3/sqlite3_db_release_memory.3 | 28 + static/netbsd/man3/sqlite3_db_status.3 | 44 + static/netbsd/man3/sqlite3_declare_vtab.3 | 25 + static/netbsd/man3/sqlite3_deserialize.3 | 77 + static/netbsd/man3/sqlite3_destructor_type.3 | 35 + static/netbsd/man3/sqlite3_drop_modules.3 | 31 + static/netbsd/man3/sqlite3_enable_load_extension.3 | 50 + static/netbsd/man3/sqlite3_enable_shared_cache.3 | 73 + static/netbsd/man3/sqlite3_errcode.3 | 115 + static/netbsd/man3/sqlite3_exec.3 | 106 + static/netbsd/man3/sqlite3_extended_result_codes.3 | 23 + static/netbsd/man3/sqlite3_file.3 | 30 + static/netbsd/man3/sqlite3_file_control.3 | 68 + static/netbsd/man3/sqlite3_filename.3 | 38 + static/netbsd/man3/sqlite3_filename_database.3 | 60 + static/netbsd/man3/sqlite3_finalize.3 | 46 + static/netbsd/man3/sqlite3_get_autocommit.3 | 36 + static/netbsd/man3/sqlite3_get_auxdata.3 | 105 + static/netbsd/man3/sqlite3_get_clientdata.3 | 85 + static/netbsd/man3/sqlite3_get_table.3 | 122 + static/netbsd/man3/sqlite3_index_info.3 | 153 + static/netbsd/man3/sqlite3_initialize.3 | 120 + static/netbsd/man3/sqlite3_interrupt.3 | 63 + static/netbsd/man3/sqlite3_io_methods.3 | 176 + static/netbsd/man3/sqlite3_keyword_count.3 | 84 + static/netbsd/man3/sqlite3_last_insert_rowid.3 | 79 + static/netbsd/man3/sqlite3_limit.3 | 61 + static/netbsd/man3/sqlite3_load_extension.3 | 75 + static/netbsd/man3/sqlite3_log.3 | 47 + static/netbsd/man3/sqlite3_malloc.3 | 128 + static/netbsd/man3/sqlite3_mem_methods.3 | 102 + static/netbsd/man3/sqlite3_memory_used.3 | 62 + static/netbsd/man3/sqlite3_module.3 | 72 + static/netbsd/man3/sqlite3_mprintf.3 | 86 + static/netbsd/man3/sqlite3_mutex.3 | 25 + static/netbsd/man3/sqlite3_mutex_alloc.3 | 175 + static/netbsd/man3/sqlite3_mutex_held.3 | 55 + static/netbsd/man3/sqlite3_mutex_methods.3 | 108 + static/netbsd/man3/sqlite3_next_stmt.3 | 34 + static/netbsd/man3/sqlite3_open.3 | 335 + static/netbsd/man3/sqlite3_overload_function.3 | 36 + static/netbsd/man3/sqlite3_pcache.3 | 25 + static/netbsd/man3/sqlite3_pcache_methods2.3 | 194 + static/netbsd/man3/sqlite3_pcache_page.3 | 31 + static/netbsd/man3/sqlite3_prepare.3 | 234 + static/netbsd/man3/sqlite3_preupdate_hook.3 | 188 + static/netbsd/man3/sqlite3_progress_handler.3 | 70 + static/netbsd/man3/sqlite3_randomness.3 | 40 + static/netbsd/man3/sqlite3_rebaser.3 | 111 + static/netbsd/man3/sqlite3_release_memory.3 | 31 + static/netbsd/man3/sqlite3_reset.3 | 60 + static/netbsd/man3/sqlite3_reset_auto_extension.3 | 24 + static/netbsd/man3/sqlite3_result_blob.3 | 330 + static/netbsd/man3/sqlite3_result_subtype.3 | 44 + static/netbsd/man3/sqlite3_serialize.3 | 72 + static/netbsd/man3/sqlite3_session.3 | 18 + static/netbsd/man3/sqlite3_set_authorizer.3 | 142 + static/netbsd/man3/sqlite3_set_last_insert_rowid.3 | 23 + static/netbsd/man3/sqlite3_sleep.3 | 42 + static/netbsd/man3/sqlite3_snapshot.3 | 36 + static/netbsd/man3/sqlite3_snapshot_cmp.3 | 43 + static/netbsd/man3/sqlite3_snapshot_free.3 | 30 + static/netbsd/man3/sqlite3_snapshot_get.3 | 76 + static/netbsd/man3/sqlite3_snapshot_open.3 | 74 + static/netbsd/man3/sqlite3_snapshot_recover.3 | 46 + static/netbsd/man3/sqlite3_soft_heap_limit.3 | 28 + static/netbsd/man3/sqlite3_soft_heap_limit64.3 | 89 + static/netbsd/man3/sqlite3_sql.3 | 80 + static/netbsd/man3/sqlite3_status.3 | 63 + static/netbsd/man3/sqlite3_step.3 | 142 + static/netbsd/man3/sqlite3_stmt.3 | 51 + static/netbsd/man3/sqlite3_stmt_busy.3 | 37 + static/netbsd/man3/sqlite3_stmt_explain.3 | 56 + static/netbsd/man3/sqlite3_stmt_isexplain.3 | 24 + static/netbsd/man3/sqlite3_stmt_readonly.3 | 70 + static/netbsd/man3/sqlite3_stmt_scanstatus.3 | 83 + static/netbsd/man3/sqlite3_stmt_scanstatus_reset.3 | 27 + static/netbsd/man3/sqlite3_stmt_status.3 | 43 + static/netbsd/man3/sqlite3_str.3 | 39 + static/netbsd/man3/sqlite3_str_appendf.3 | 94 + static/netbsd/man3/sqlite3_str_errcode.3 | 63 + static/netbsd/man3/sqlite3_str_finish.3 | 36 + static/netbsd/man3/sqlite3_str_new.3 | 47 + static/netbsd/man3/sqlite3_strglob.3 | 28 + static/netbsd/man3/sqlite3_stricmp.3 | 36 + static/netbsd/man3/sqlite3_strlike.3 | 32 + static/netbsd/man3/sqlite3_system_errno.3 | 30 + static/netbsd/man3/sqlite3_table_column_metadata.3 | 102 + static/netbsd/man3/sqlite3_temp_directory.3 | 76 + static/netbsd/man3/sqlite3_test_control.3 | 35 + static/netbsd/man3/sqlite3_threadsafe.3 | 59 + static/netbsd/man3/sqlite3_total_changes.3 | 59 + static/netbsd/man3/sqlite3_trace.3 | 70 + static/netbsd/man3/sqlite3_trace_v2.3 | 62 + static/netbsd/man3/sqlite3_txn_state.3 | 38 + static/netbsd/man3/sqlite3_unlock_notify.3 | 150 + static/netbsd/man3/sqlite3_update_hook.3 | 87 + static/netbsd/man3/sqlite3_uri_parameter.3 | 118 + static/netbsd/man3/sqlite3_user_data.3 | 30 + static/netbsd/man3/sqlite3_value.3 | 72 + static/netbsd/man3/sqlite3_value_blob.3 | 250 + static/netbsd/man3/sqlite3_value_dup.3 | 40 + static/netbsd/man3/sqlite3_value_encoding.3 | 41 + static/netbsd/man3/sqlite3_value_subtype.3 | 36 + static/netbsd/man3/sqlite3_version.3 | 68 + static/netbsd/man3/sqlite3_vfs.3 | 263 + static/netbsd/man3/sqlite3_vfs_find.3 | 61 + static/netbsd/man3/sqlite3_vtab.3 | 44 + static/netbsd/man3/sqlite3_vtab_collation.3 | 59 + static/netbsd/man3/sqlite3_vtab_config.3 | 38 + static/netbsd/man3/sqlite3_vtab_cursor.3 | 34 + static/netbsd/man3/sqlite3_vtab_distinct.3 | 100 + static/netbsd/man3/sqlite3_vtab_in.3 | 96 + static/netbsd/man3/sqlite3_vtab_in_first.3 | 71 + static/netbsd/man3/sqlite3_vtab_nochange.3 | 43 + static/netbsd/man3/sqlite3_vtab_on_conflict.3 | 30 + static/netbsd/man3/sqlite3_vtab_rhs_value.3 | 66 + static/netbsd/man3/sqlite3_wal_autocheckpoint.3 | 51 + static/netbsd/man3/sqlite3_wal_checkpoint.3 | 39 + static/netbsd/man3/sqlite3_wal_checkpoint_v2.3 | 128 + static/netbsd/man3/sqlite3_wal_hook.3 | 69 + static/netbsd/man3/sqlite3_win32_set_directory.3 | 62 + static/netbsd/man3/sqlite3changegroup_add.3 | 89 + static/netbsd/man3/sqlite3changegroup_delete.3 | 19 + static/netbsd/man3/sqlite3changegroup_new.3 | 52 + static/netbsd/man3/sqlite3changegroup_output.3 | 47 + static/netbsd/man3/sqlite3changegroup_schema.3 | 49 + static/netbsd/man3/sqlite3changeset_apply.3 | 233 + static/netbsd/man3/sqlite3changeset_apply_strm.3 | 281 + static/netbsd/man3/sqlite3changeset_concat.3 | 48 + static/netbsd/man3/sqlite3changeset_conflict.3 | 48 + static/netbsd/man3/sqlite3changeset_finalize.3 | 52 + static/netbsd/man3/sqlite3changeset_fk_conflicts.3 | 29 + static/netbsd/man3/sqlite3changeset_invert.3 | 55 + static/netbsd/man3/sqlite3changeset_new.3 | 60 + static/netbsd/man3/sqlite3changeset_next.3 | 43 + static/netbsd/man3/sqlite3changeset_old.3 | 58 + static/netbsd/man3/sqlite3changeset_op.3 | 70 + static/netbsd/man3/sqlite3changeset_pk.3 | 48 + static/netbsd/man3/sqlite3changeset_start.3 | 94 + static/netbsd/man3/sqlite3changeset_upgrade.3 | 29 + static/netbsd/man3/sqlite3rebaser_configure.3 | 27 + static/netbsd/man3/sqlite3rebaser_create.3 | 23 + static/netbsd/man3/sqlite3rebaser_delete.3 | 22 + static/netbsd/man3/sqlite3rebaser_rebase.3 | 39 + static/netbsd/man3/sqlite3session_attach.3 | 86 + static/netbsd/man3/sqlite3session_changeset.3 | 149 + static/netbsd/man3/sqlite3session_changeset_size.3 | 29 + static/netbsd/man3/sqlite3session_config.3 | 51 + static/netbsd/man3/sqlite3session_create.3 | 60 + static/netbsd/man3/sqlite3session_delete.3 | 31 + static/netbsd/man3/sqlite3session_diff.3 | 87 + static/netbsd/man3/sqlite3session_enable.3 | 38 + static/netbsd/man3/sqlite3session_indirect.3 | 47 + static/netbsd/man3/sqlite3session_isempty.3 | 34 + static/netbsd/man3/sqlite3session_memory_used.3 | 21 + static/netbsd/man3/sqlite3session_object_config.3 | 28 + static/netbsd/man3/sqlite3session_patchset.3 | 50 + static/netbsd/man3/sqlite3session_table_filter.3 | 34 + static/netbsd/man3/sqlite_int64.3 | 58 + static/netbsd/man3/sqrt.3 | 101 + static/netbsd/man3/ssl.3 | 878 + static/netbsd/man3/ssp.3 | 121 + static/netbsd/man3/stat_flags.3 | 172 + static/netbsd/man3/stdio.3 | 347 + static/netbsd/man3/strcasecmp.3 | 101 + static/netbsd/man3/strcat.3 | 138 + static/netbsd/man3/strchr.3 | 118 + static/netbsd/man3/strcmp.3 | 99 + static/netbsd/man3/strcoll.3 | 73 + static/netbsd/man3/strcpy.3 | 152 + static/netbsd/man3/strcspn.3 | 97 + static/netbsd/man3/strdup.3 | 115 + static/netbsd/man3/strerror.3 | 289 + static/netbsd/man3/strfmon.3 | 185 + static/netbsd/man3/strftime.3 | 545 + static/netbsd/man3/string.3 | 170 + static/netbsd/man3/stringlist.3 | 144 + static/netbsd/man3/strings.3 | 91 + static/netbsd/man3/strlcpy.3 | 359 + static/netbsd/man3/strlen.3 | 95 + static/netbsd/man3/strmode.3 | 156 + static/netbsd/man3/strncpy.3 | 302 + static/netbsd/man3/strpbrk.3 | 79 + static/netbsd/man3/strpct.3 | 237 + static/netbsd/man3/strptime.3 | 443 + static/netbsd/man3/strrchr.3 | 100 + static/netbsd/man3/strsep.3 | 120 + static/netbsd/man3/strsignal.3 | 64 + static/netbsd/man3/strspn.3 | 92 + static/netbsd/man3/strstr.3 | 134 + static/netbsd/man3/strsuftoll.3 | 150 + static/netbsd/man3/strtod.3 | 243 + static/netbsd/man3/strtoi.3 | 301 + static/netbsd/man3/strtok.3 | 177 + static/netbsd/man3/strtol.3 | 320 + static/netbsd/man3/strtonum.3 | 188 + static/netbsd/man3/strtoul.3 | 292 + static/netbsd/man3/strxfrm.3 | 79 + static/netbsd/man3/stty.3 | 94 + static/netbsd/man3/swab.3 | 92 + static/netbsd/man3/swapon.3 | 121 + static/netbsd/man3/sysconf.3 | 362 + static/netbsd/man3/sysctl.3 | 753 + static/netbsd/man3/syslog.3 | 549 + static/netbsd/man3/system.3 | 108 + static/netbsd/man3/t.3 | 1 + static/netbsd/man3/tag.h.3 | 123 + static/netbsd/man3/tag_compat.h.3 | 41 + static/netbsd/man3/tan.3 | 81 + static/netbsd/man3/tanh.3 | 101 + static/netbsd/man3/tbl.3 | 349 + static/netbsd/man3/tcgetpgrp.3 | 77 + static/netbsd/man3/tcgetsid.3 | 75 + static/netbsd/man3/tcgetwinsize.3 | 216 + static/netbsd/man3/tcsendbreak.3 | 154 + static/netbsd/man3/tcsetattr.3 | 331 + static/netbsd/man3/tcsetpgrp.3 | 98 + static/netbsd/man3/termcap.3 | 155 + static/netbsd/man3/terminfo.3 | 256 + static/netbsd/man3/test_ldnsrr.3 | 574 + static/netbsd/man3/test_packets.3 | 496 + static/netbsd/man3/test_signatures.3 | 48 + static/netbsd/man3/textdomain.3 | 57 + static/netbsd/man3/thrd.3 | 234 + static/netbsd/man3/thread.h.3 | 210 + static/netbsd/man3/threads.3 | 98 + static/netbsd/man3/tiger.3 | 218 + static/netbsd/man3/time.3 | 103 + static/netbsd/man3/time2posix.3 | 183 + static/netbsd/man3/times.3 | 151 + static/netbsd/man3/timespec_get.3 | 135 + static/netbsd/man3/timezone.3 | 75 + static/netbsd/man3/tmpnam.3 | 261 + static/netbsd/man3/toascii.3 | 83 + static/netbsd/man3/tolower.3 | 102 + static/netbsd/man3/toupper.3 | 101 + static/netbsd/man3/towctrans.3 | 87 + static/netbsd/man3/towlower.3 | 70 + static/netbsd/man3/tpmUnsealFile.3 | 57 + static/netbsd/man3/tpmUnsealShred.3 | 1 + static/netbsd/man3/tpmUnsealStrerror.3 | 1 + static/netbsd/man3/trunc.3 | 79 + static/netbsd/man3/tsearch.3 | 141 + static/netbsd/man3/tsig.3 | 241 + static/netbsd/man3/tss.3 | 157 + static/netbsd/man3/ttyaction.3 | 113 + static/netbsd/man3/ttymsg.3 | 68 + static/netbsd/man3/ttyname.3 | 204 + static/netbsd/man3/tzset.3 | 438 + static/netbsd/man3/ualarm.3 | 103 + static/netbsd/man3/ukfs.3 | 321 + static/netbsd/man3/ulimit.3 | 119 + static/netbsd/man3/uname.3 | 114 + static/netbsd/man3/ungetc.3 | 102 + static/netbsd/man3/ungetwc.3 | 95 + static/netbsd/man3/unlockpt.3 | 86 + static/netbsd/man3/unvis.3 | 268 + static/netbsd/man3/update_panels.3 | 66 + static/netbsd/man3/usbhid.3 | 223 + static/netbsd/man3/usleep.3 | 115 + static/netbsd/man3/util.3 | 132 + static/netbsd/man3/util.h.3 | 715 + static/netbsd/man3/utime.3 | 149 + static/netbsd/man3/uuid.3 | 211 + static/netbsd/man3/valloc.3 | 77 + static/netbsd/man3/virtdir.3 | 137 + static/netbsd/man3/vis.3 | 556 + static/netbsd/man3/wcrtomb.3 | 145 + static/netbsd/man3/wcscasecmp.3 | 93 + static/netbsd/man3/wcscoll.3 | 112 + static/netbsd/man3/wcsdup.3 | 87 + static/netbsd/man3/wcsftime.3 | 72 + static/netbsd/man3/wcsrtombs.3 | 223 + static/netbsd/man3/wcstod.3 | 78 + static/netbsd/man3/wcstok.3 | 135 + static/netbsd/man3/wcstol.3 | 96 + static/netbsd/man3/wcstombs.3 | 133 + static/netbsd/man3/wcswidth.3 | 64 + static/netbsd/man3/wcsxfrm.3 | 107 + static/netbsd/man3/wctob.3 | 87 + static/netbsd/man3/wctomb.3 | 130 + static/netbsd/man3/wctrans.3 | 89 + static/netbsd/man3/wctype.3 | 91 + static/netbsd/man3/wcwidth.3 | 89 + static/netbsd/man3/wind.3 | 317 + static/netbsd/man3/wind_profile.3 | 3 + static/netbsd/man3/wind_punycode_label_toascii.3 | 3 + static/netbsd/man3/wind_stringprep.3 | 3 + static/netbsd/man3/wind_ucs2read.3 | 3 + static/netbsd/man3/wind_ucs2utf8.3 | 3 + static/netbsd/man3/wind_ucs2utf8_length.3 | 3 + static/netbsd/man3/wind_ucs2write.3 | 3 + static/netbsd/man3/wind_ucs4utf8.3 | 3 + static/netbsd/man3/wind_ucs4utf8_length.3 | 3 + static/netbsd/man3/wind_utf8ucs2.3 | 3 + static/netbsd/man3/wind_utf8ucs2_length.3 | 3 + static/netbsd/man3/wind_utf8ucs4.3 | 3 + static/netbsd/man3/wind_utf8ucs4_length.3 | 3 + static/netbsd/man3/wmemchr.3 | 219 + static/netbsd/man3/wordexp.3 | 226 + static/netbsd/man3/wprintf.3 | 618 + static/netbsd/man3/wscanf.3 | 484 + static/netbsd/man3/xdr.3 | 522 + static/netbsd/man3/ypclnt.3 | 376 + static/netbsd/man3/zlib.3 | 149 + static/netbsd/man3/zopen.3 | 138 + 3160 files changed, 443862 insertions(+) create mode 100644 static/netbsd/man3/ADMISSIONS.3 create mode 100644 static/netbsd/man3/ASN1_EXTERN_FUNCS.3 create mode 100644 static/netbsd/man3/ASN1_INTEGER_get_int64.3 create mode 100644 static/netbsd/man3/ASN1_INTEGER_new.3 create mode 100644 static/netbsd/man3/ASN1_ITEM_lookup.3 create mode 100644 static/netbsd/man3/ASN1_OBJECT_new.3 create mode 100644 static/netbsd/man3/ASN1_STRING_TABLE_add.3 create mode 100644 static/netbsd/man3/ASN1_STRING_length.3 create mode 100644 static/netbsd/man3/ASN1_STRING_new.3 create mode 100644 static/netbsd/man3/ASN1_STRING_print_ex.3 create mode 100644 static/netbsd/man3/ASN1_TIME_set.3 create mode 100644 static/netbsd/man3/ASN1_TYPE_get.3 create mode 100644 static/netbsd/man3/ASN1_aux_cb.3 create mode 100644 static/netbsd/man3/ASN1_generate_nconf.3 create mode 100644 static/netbsd/man3/ASN1_item_d2i_bio.3 create mode 100644 static/netbsd/man3/ASN1_item_new.3 create mode 100644 static/netbsd/man3/ASN1_item_sign.3 create mode 100644 static/netbsd/man3/ASYNC_WAIT_CTX_new.3 create mode 100644 static/netbsd/man3/ASYNC_start_job.3 create mode 100644 static/netbsd/man3/BF_encrypt.3 create mode 100644 static/netbsd/man3/BIO_ADDR.3 create mode 100644 static/netbsd/man3/BIO_ADDRINFO.3 create mode 100644 static/netbsd/man3/BIO_connect.3 create mode 100644 static/netbsd/man3/BIO_ctrl.3 create mode 100644 static/netbsd/man3/BIO_f_base64.3 create mode 100644 static/netbsd/man3/BIO_f_buffer.3 create mode 100644 static/netbsd/man3/BIO_f_cipher.3 create mode 100644 static/netbsd/man3/BIO_f_md.3 create mode 100644 static/netbsd/man3/BIO_f_null.3 create mode 100644 static/netbsd/man3/BIO_f_prefix.3 create mode 100644 static/netbsd/man3/BIO_f_readbuffer.3 create mode 100644 static/netbsd/man3/BIO_f_ssl.3 create mode 100644 static/netbsd/man3/BIO_find_type.3 create mode 100644 static/netbsd/man3/BIO_get_data.3 create mode 100644 static/netbsd/man3/BIO_get_ex_new_index.3 create mode 100644 static/netbsd/man3/BIO_get_rpoll_descriptor.3 create mode 100644 static/netbsd/man3/BIO_meth_new.3 create mode 100644 static/netbsd/man3/BIO_new.3 create mode 100644 static/netbsd/man3/BIO_new_CMS.3 create mode 100644 static/netbsd/man3/BIO_parse_hostserv.3 create mode 100644 static/netbsd/man3/BIO_printf.3 create mode 100644 static/netbsd/man3/BIO_push.3 create mode 100644 static/netbsd/man3/BIO_read.3 create mode 100644 static/netbsd/man3/BIO_s_accept.3 create mode 100644 static/netbsd/man3/BIO_s_bio.3 create mode 100644 static/netbsd/man3/BIO_s_connect.3 create mode 100644 static/netbsd/man3/BIO_s_core.3 create mode 100644 static/netbsd/man3/BIO_s_datagram.3 create mode 100644 static/netbsd/man3/BIO_s_dgram_pair.3 create mode 100644 static/netbsd/man3/BIO_s_fd.3 create mode 100644 static/netbsd/man3/BIO_s_file.3 create mode 100644 static/netbsd/man3/BIO_s_mem.3 create mode 100644 static/netbsd/man3/BIO_s_null.3 create mode 100644 static/netbsd/man3/BIO_s_socket.3 create mode 100644 static/netbsd/man3/BIO_sendmmsg.3 create mode 100644 static/netbsd/man3/BIO_set_callback.3 create mode 100644 static/netbsd/man3/BIO_set_flags.3 create mode 100644 static/netbsd/man3/BIO_should_retry.3 create mode 100644 static/netbsd/man3/BIO_socket_wait.3 create mode 100644 static/netbsd/man3/BN_BLINDING_new.3 create mode 100644 static/netbsd/man3/BN_CTX_new.3 create mode 100644 static/netbsd/man3/BN_CTX_start.3 create mode 100644 static/netbsd/man3/BN_add.3 create mode 100644 static/netbsd/man3/BN_add_word.3 create mode 100644 static/netbsd/man3/BN_bn2bin.3 create mode 100644 static/netbsd/man3/BN_cmp.3 create mode 100644 static/netbsd/man3/BN_copy.3 create mode 100644 static/netbsd/man3/BN_generate_prime.3 create mode 100644 static/netbsd/man3/BN_mod_exp_mont.3 create mode 100644 static/netbsd/man3/BN_mod_inverse.3 create mode 100644 static/netbsd/man3/BN_mod_mul_montgomery.3 create mode 100644 static/netbsd/man3/BN_mod_mul_reciprocal.3 create mode 100644 static/netbsd/man3/BN_new.3 create mode 100644 static/netbsd/man3/BN_num_bytes.3 create mode 100644 static/netbsd/man3/BN_rand.3 create mode 100644 static/netbsd/man3/BN_security_bits.3 create mode 100644 static/netbsd/man3/BN_set_bit.3 create mode 100644 static/netbsd/man3/BN_swap.3 create mode 100644 static/netbsd/man3/BN_zero.3 create mode 100644 static/netbsd/man3/BUF_MEM_new.3 create mode 100644 static/netbsd/man3/CMAC_CTX.3 create mode 100644 static/netbsd/man3/CMS_EncryptedData_decrypt.3 create mode 100644 static/netbsd/man3/CMS_EncryptedData_encrypt.3 create mode 100644 static/netbsd/man3/CMS_EncryptedData_set1_key.3 create mode 100644 static/netbsd/man3/CMS_EnvelopedData_create.3 create mode 100644 static/netbsd/man3/CMS_add0_cert.3 create mode 100644 static/netbsd/man3/CMS_add1_recipient_cert.3 create mode 100644 static/netbsd/man3/CMS_add1_signer.3 create mode 100644 static/netbsd/man3/CMS_compress.3 create mode 100644 static/netbsd/man3/CMS_data_create.3 create mode 100644 static/netbsd/man3/CMS_decrypt.3 create mode 100644 static/netbsd/man3/CMS_digest_create.3 create mode 100644 static/netbsd/man3/CMS_encrypt.3 create mode 100644 static/netbsd/man3/CMS_final.3 create mode 100644 static/netbsd/man3/CMS_get0_RecipientInfos.3 create mode 100644 static/netbsd/man3/CMS_get0_SignerInfos.3 create mode 100644 static/netbsd/man3/CMS_get0_type.3 create mode 100644 static/netbsd/man3/CMS_get1_ReceiptRequest.3 create mode 100644 static/netbsd/man3/CMS_sign.3 create mode 100644 static/netbsd/man3/CMS_sign_receipt.3 create mode 100644 static/netbsd/man3/CMS_signed_get_attr.3 create mode 100644 static/netbsd/man3/CMS_uncompress.3 create mode 100644 static/netbsd/man3/CMS_verify.3 create mode 100644 static/netbsd/man3/CMS_verify_receipt.3 create mode 100644 static/netbsd/man3/COMP_CTX_new.3 create mode 100644 static/netbsd/man3/CONF_modules_free.3 create mode 100644 static/netbsd/man3/CONF_modules_load_file.3 create mode 100644 static/netbsd/man3/CRYPTO_THREAD_run_once.3 create mode 100644 static/netbsd/man3/CRYPTO_get_ex_new_index.3 create mode 100644 static/netbsd/man3/CRYPTO_memcmp.3 create mode 100644 static/netbsd/man3/CRYPTO_set_ex_data.3 create mode 100644 static/netbsd/man3/CTLOG_STORE_get0_log_by_id.3 create mode 100644 static/netbsd/man3/CTLOG_STORE_new.3 create mode 100644 static/netbsd/man3/CTLOG_new.3 create mode 100644 static/netbsd/man3/CT_POLICY_EVAL_CTX_new.3 create mode 100644 static/netbsd/man3/ChangeLog.3 create mode 100644 static/netbsd/man3/DEFINE_STACK_OF.3 create mode 100644 static/netbsd/man3/DES_cbc_cksum.3 create mode 100644 static/netbsd/man3/DES_cbc_encrypt.3 create mode 100644 static/netbsd/man3/DES_cfb64_encrypt.3 create mode 100644 static/netbsd/man3/DES_check_key_parity.3 create mode 100644 static/netbsd/man3/DES_ecb3_encrypt.3 create mode 100644 static/netbsd/man3/DES_ecb_encrypt.3 create mode 100644 static/netbsd/man3/DES_ede3_cbc_encrypt.3 create mode 100644 static/netbsd/man3/DES_encrypt.3 create mode 100644 static/netbsd/man3/DES_init_random_number_generator.3 create mode 100644 static/netbsd/man3/DES_is_weak_key.3 create mode 100644 static/netbsd/man3/DES_key_sched.3 create mode 100644 static/netbsd/man3/DES_new_random_key.3 create mode 100644 static/netbsd/man3/DES_pcbc_encrypt.3 create mode 100644 static/netbsd/man3/DES_random_key.3 create mode 100644 static/netbsd/man3/DES_set_key.3 create mode 100644 static/netbsd/man3/DES_set_key_checked.3 create mode 100644 static/netbsd/man3/DES_set_key_unchecked.3 create mode 100644 static/netbsd/man3/DES_set_odd_parity.3 create mode 100644 static/netbsd/man3/DES_string_to_key.3 create mode 100644 static/netbsd/man3/DH_check_pubkey.3 create mode 100644 static/netbsd/man3/DH_compute_key.3 create mode 100644 static/netbsd/man3/DH_free.3 create mode 100644 static/netbsd/man3/DH_generate_key.3 create mode 100644 static/netbsd/man3/DH_generate_parameters.3 create mode 100644 static/netbsd/man3/DH_generate_parameters_ex.3 create mode 100644 static/netbsd/man3/DH_get0_pqg.3 create mode 100644 static/netbsd/man3/DH_get_1024_160.3 create mode 100644 static/netbsd/man3/DH_get_default_method.3 create mode 100644 static/netbsd/man3/DH_get_ex_data.3 create mode 100644 static/netbsd/man3/DH_get_ex_new_index.3 create mode 100644 static/netbsd/man3/DH_ltm_method.3 create mode 100644 static/netbsd/man3/DH_meth_new.3 create mode 100644 static/netbsd/man3/DH_new.3 create mode 100644 static/netbsd/man3/DH_new_by_nid.3 create mode 100644 static/netbsd/man3/DH_new_method.3 create mode 100644 static/netbsd/man3/DH_null_method.3 create mode 100644 static/netbsd/man3/DH_set_default_method.3 create mode 100644 static/netbsd/man3/DH_set_ex_data.3 create mode 100644 static/netbsd/man3/DH_set_method.3 create mode 100644 static/netbsd/man3/DH_size.3 create mode 100644 static/netbsd/man3/DH_up_ref.3 create mode 100644 static/netbsd/man3/DSA_SIG_new.3 create mode 100644 static/netbsd/man3/DSA_do_sign.3 create mode 100644 static/netbsd/man3/DSA_dup_DH.3 create mode 100644 static/netbsd/man3/DSA_generate_key.3 create mode 100644 static/netbsd/man3/DSA_generate_parameters.3 create mode 100644 static/netbsd/man3/DSA_get0_pqg.3 create mode 100644 static/netbsd/man3/DSA_get_ex_new_index.3 create mode 100644 static/netbsd/man3/DSA_meth_new.3 create mode 100644 static/netbsd/man3/DSA_new.3 create mode 100644 static/netbsd/man3/DSA_set_method.3 create mode 100644 static/netbsd/man3/DSA_sign.3 create mode 100644 static/netbsd/man3/DSA_size.3 create mode 100644 static/netbsd/man3/DTLS_get_data_mtu.3 create mode 100644 static/netbsd/man3/DTLS_set_timer_cb.3 create mode 100644 static/netbsd/man3/DTLSv1_get_timeout.3 create mode 100644 static/netbsd/man3/DTLSv1_handle_timeout.3 create mode 100644 static/netbsd/man3/DTLSv1_listen.3 create mode 100644 static/netbsd/man3/ECDSA_SIG_new.3 create mode 100644 static/netbsd/man3/ECDSA_sign.3 create mode 100644 static/netbsd/man3/ECPKParameters_print.3 create mode 100644 static/netbsd/man3/EC_GFp_simple_method.3 create mode 100644 static/netbsd/man3/EC_GROUP_copy.3 create mode 100644 static/netbsd/man3/EC_GROUP_new.3 create mode 100644 static/netbsd/man3/EC_KEY_get_enc_flags.3 create mode 100644 static/netbsd/man3/EC_KEY_new.3 create mode 100644 static/netbsd/man3/EC_POINT_add.3 create mode 100644 static/netbsd/man3/EC_POINT_new.3 create mode 100644 static/netbsd/man3/ENGINE_add.3 create mode 100644 static/netbsd/man3/ERR_GET_LIB.3 create mode 100644 static/netbsd/man3/ERR_clear_error.3 create mode 100644 static/netbsd/man3/ERR_error_string.3 create mode 100644 static/netbsd/man3/ERR_get_error.3 create mode 100644 static/netbsd/man3/ERR_load_crypto_strings.3 create mode 100644 static/netbsd/man3/ERR_load_strings.3 create mode 100644 static/netbsd/man3/ERR_new.3 create mode 100644 static/netbsd/man3/ERR_print_errors.3 create mode 100644 static/netbsd/man3/ERR_put_error.3 create mode 100644 static/netbsd/man3/ERR_remove_state.3 create mode 100644 static/netbsd/man3/ERR_set_mark.3 create mode 100644 static/netbsd/man3/EVP_ASYM_CIPHER_free.3 create mode 100644 static/netbsd/man3/EVP_BytesToKey.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_block_size.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_cipher.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_cleanup.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_ctrl.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_flags.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_get_app_data.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_get_original_iv.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_init.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_iv_length.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_key_length.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_mode.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_rand_key.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_set_app_data.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_CTX_set_key_length.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_block_size.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_iv_length.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_key_length.3 create mode 100644 static/netbsd/man3/EVP_CIPHER_meth_new.3 create mode 100644 static/netbsd/man3/EVP_CipherFinal_ex.3 create mode 100644 static/netbsd/man3/EVP_CipherInit_ex.3 create mode 100644 static/netbsd/man3/EVP_CipherUpdate.3 create mode 100644 static/netbsd/man3/EVP_Digest.3 create mode 100644 static/netbsd/man3/EVP_DigestFinal_ex.3 create mode 100644 static/netbsd/man3/EVP_DigestInit.3 create mode 100644 static/netbsd/man3/EVP_DigestInit_ex.3 create mode 100644 static/netbsd/man3/EVP_DigestSignInit.3 create mode 100644 static/netbsd/man3/EVP_DigestUpdate.3 create mode 100644 static/netbsd/man3/EVP_DigestVerifyInit.3 create mode 100644 static/netbsd/man3/EVP_EncodeInit.3 create mode 100644 static/netbsd/man3/EVP_EncryptInit.3 create mode 100644 static/netbsd/man3/EVP_KDF.3 create mode 100644 static/netbsd/man3/EVP_KEM_free.3 create mode 100644 static/netbsd/man3/EVP_KEYEXCH_free.3 create mode 100644 static/netbsd/man3/EVP_KEYMGMT.3 create mode 100644 static/netbsd/man3/EVP_MAC.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_block_size.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_cleanup.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_create.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_destroy.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_init.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_md.3 create mode 100644 static/netbsd/man3/EVP_MD_CTX_size.3 create mode 100644 static/netbsd/man3/EVP_MD_block_size.3 create mode 100644 static/netbsd/man3/EVP_MD_meth_new.3 create mode 100644 static/netbsd/man3/EVP_MD_size.3 create mode 100644 static/netbsd/man3/EVP_OpenInit.3 create mode 100644 static/netbsd/man3/EVP_PBE_CipherInit.3 create mode 100644 static/netbsd/man3/EVP_PKEY2PKCS8.3 create mode 100644 static/netbsd/man3/EVP_PKEY_ASN1_METHOD.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_ctrl.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_get0_libctx.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_get0_pkey.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_get_algor.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_new.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set1_pbe_pass.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set_params.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set_scrypt_N.3 create mode 100644 static/netbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 create mode 100644 static/netbsd/man3/EVP_PKEY_asn1_get_count.3 create mode 100644 static/netbsd/man3/EVP_PKEY_check.3 create mode 100644 static/netbsd/man3/EVP_PKEY_cmp.3 create mode 100644 static/netbsd/man3/EVP_PKEY_copy_parameters.3 create mode 100644 static/netbsd/man3/EVP_PKEY_decapsulate.3 create mode 100644 static/netbsd/man3/EVP_PKEY_decrypt.3 create mode 100644 static/netbsd/man3/EVP_PKEY_derive.3 create mode 100644 static/netbsd/man3/EVP_PKEY_digestsign_supports_digest.3 create mode 100644 static/netbsd/man3/EVP_PKEY_encapsulate.3 create mode 100644 static/netbsd/man3/EVP_PKEY_encrypt.3 create mode 100644 static/netbsd/man3/EVP_PKEY_fromdata.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_attr.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_default_digest.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_default_digest_nid.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_field_type.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_group_name.3 create mode 100644 static/netbsd/man3/EVP_PKEY_get_size.3 create mode 100644 static/netbsd/man3/EVP_PKEY_gettable_params.3 create mode 100644 static/netbsd/man3/EVP_PKEY_is_a.3 create mode 100644 static/netbsd/man3/EVP_PKEY_keygen.3 create mode 100644 static/netbsd/man3/EVP_PKEY_meth_get_count.3 create mode 100644 static/netbsd/man3/EVP_PKEY_meth_new.3 create mode 100644 static/netbsd/man3/EVP_PKEY_new.3 create mode 100644 static/netbsd/man3/EVP_PKEY_print_private.3 create mode 100644 static/netbsd/man3/EVP_PKEY_set1_RSA.3 create mode 100644 static/netbsd/man3/EVP_PKEY_set1_encoded_public_key.3 create mode 100644 static/netbsd/man3/EVP_PKEY_set_type.3 create mode 100644 static/netbsd/man3/EVP_PKEY_settable_params.3 create mode 100644 static/netbsd/man3/EVP_PKEY_sign.3 create mode 100644 static/netbsd/man3/EVP_PKEY_todata.3 create mode 100644 static/netbsd/man3/EVP_PKEY_verify.3 create mode 100644 static/netbsd/man3/EVP_PKEY_verify_recover.3 create mode 100644 static/netbsd/man3/EVP_RAND.3 create mode 100644 static/netbsd/man3/EVP_SIGNATURE.3 create mode 100644 static/netbsd/man3/EVP_SKEY.3 create mode 100644 static/netbsd/man3/EVP_SKEYMGMT.3 create mode 100644 static/netbsd/man3/EVP_SealInit.3 create mode 100644 static/netbsd/man3/EVP_SignInit.3 create mode 100644 static/netbsd/man3/EVP_VerifyInit.3 create mode 100644 static/netbsd/man3/EVP_aes.3 create mode 100644 static/netbsd/man3/EVP_aes_128_cbc.3 create mode 100644 static/netbsd/man3/EVP_aes_128_cfb8.3 create mode 100644 static/netbsd/man3/EVP_aes_128_gcm.3 create mode 100644 static/netbsd/man3/EVP_aes_192_cbc.3 create mode 100644 static/netbsd/man3/EVP_aes_192_cfb8.3 create mode 100644 static/netbsd/man3/EVP_aes_256_cbc.3 create mode 100644 static/netbsd/man3/EVP_aes_256_cfb8.3 create mode 100644 static/netbsd/man3/EVP_aria.3 create mode 100644 static/netbsd/man3/EVP_aria_128_gcm.3 create mode 100644 static/netbsd/man3/EVP_bf_cbc.3 create mode 100644 static/netbsd/man3/EVP_blake2b512.3 create mode 100644 static/netbsd/man3/EVP_camellia.3 create mode 100644 static/netbsd/man3/EVP_camellia_128_cbc.3 create mode 100644 static/netbsd/man3/EVP_camellia_128_ecb.3 create mode 100644 static/netbsd/man3/EVP_camellia_192_cbc.3 create mode 100644 static/netbsd/man3/EVP_camellia_256_cbc.3 create mode 100644 static/netbsd/man3/EVP_cast5_cbc.3 create mode 100644 static/netbsd/man3/EVP_chacha20.3 create mode 100644 static/netbsd/man3/EVP_des.3 create mode 100644 static/netbsd/man3/EVP_des_cbc.3 create mode 100644 static/netbsd/man3/EVP_des_ede3_cbc.3 create mode 100644 static/netbsd/man3/EVP_desx_cbc.3 create mode 100644 static/netbsd/man3/EVP_enc_null.3 create mode 100644 static/netbsd/man3/EVP_get_cipherbyname.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_128_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_128_cfb8.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_192_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_192_cfb8.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_256_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_aes_256_cfb8.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_camellia_128_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_camellia_192_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_camellia_256_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_des_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_des_ede3_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_md4.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_md5.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_rc2_40_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_rc2_64_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_rc2_cbc.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_sha1.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_sha256.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_sha384.3 create mode 100644 static/netbsd/man3/EVP_hcrypto_sha512.3 create mode 100644 static/netbsd/man3/EVP_idea_cbc.3 create mode 100644 static/netbsd/man3/EVP_md2.3 create mode 100644 static/netbsd/man3/EVP_md4.3 create mode 100644 static/netbsd/man3/EVP_md5.3 create mode 100644 static/netbsd/man3/EVP_md_null.3 create mode 100644 static/netbsd/man3/EVP_mdc2.3 create mode 100644 static/netbsd/man3/EVP_rc2_40_cbc.3 create mode 100644 static/netbsd/man3/EVP_rc2_64_cbc.3 create mode 100644 static/netbsd/man3/EVP_rc2_cbc.3 create mode 100644 static/netbsd/man3/EVP_rc4.3 create mode 100644 static/netbsd/man3/EVP_rc4_40.3 create mode 100644 static/netbsd/man3/EVP_rc5_32_12_16_cbc.3 create mode 100644 static/netbsd/man3/EVP_ripemd160.3 create mode 100644 static/netbsd/man3/EVP_seed_cbc.3 create mode 100644 static/netbsd/man3/EVP_set_default_properties.3 create mode 100644 static/netbsd/man3/EVP_sha.3 create mode 100644 static/netbsd/man3/EVP_sha1.3 create mode 100644 static/netbsd/man3/EVP_sha224.3 create mode 100644 static/netbsd/man3/EVP_sha256.3 create mode 100644 static/netbsd/man3/EVP_sha384.3 create mode 100644 static/netbsd/man3/EVP_sha3_224.3 create mode 100644 static/netbsd/man3/EVP_sha512.3 create mode 100644 static/netbsd/man3/EVP_sm3.3 create mode 100644 static/netbsd/man3/EVP_sm4_cbc.3 create mode 100644 static/netbsd/man3/EVP_whirlpool.3 create mode 100644 static/netbsd/man3/EVP_wincrypt_des_ede3_cbc.3 create mode 100644 static/netbsd/man3/GENERAL_NAME.3 create mode 100644 static/netbsd/man3/HDB.3 create mode 100644 static/netbsd/man3/HMAC.3 create mode 100644 static/netbsd/man3/MD5.3 create mode 100644 static/netbsd/man3/MDC2_Init.3 create mode 100644 static/netbsd/man3/NCONF_new_ex.3 create mode 100644 static/netbsd/man3/OBJ_nid2obj.3 create mode 100644 static/netbsd/man3/OCSP_REQUEST_new.3 create mode 100644 static/netbsd/man3/OCSP_cert_to_id.3 create mode 100644 static/netbsd/man3/OCSP_request_add1_nonce.3 create mode 100644 static/netbsd/man3/OCSP_resp_find_status.3 create mode 100644 static/netbsd/man3/OCSP_response_status.3 create mode 100644 static/netbsd/man3/OCSP_sendreq_new.3 create mode 100644 static/netbsd/man3/OPENSSL_Applink.3 create mode 100644 static/netbsd/man3/OPENSSL_FILE.3 create mode 100644 static/netbsd/man3/OPENSSL_LH_COMPFUNC.3 create mode 100644 static/netbsd/man3/OPENSSL_LH_stats.3 create mode 100644 static/netbsd/man3/OPENSSL_VERSION_NUMBER.3 create mode 100644 static/netbsd/man3/OPENSSL_config.3 create mode 100644 static/netbsd/man3/OPENSSL_fork_prepare.3 create mode 100644 static/netbsd/man3/OPENSSL_gmtime.3 create mode 100644 static/netbsd/man3/OPENSSL_hexchar2int.3 create mode 100644 static/netbsd/man3/OPENSSL_ia32cap.3 create mode 100644 static/netbsd/man3/OPENSSL_init_crypto.3 create mode 100644 static/netbsd/man3/OPENSSL_init_ssl.3 create mode 100644 static/netbsd/man3/OPENSSL_instrument_bus.3 create mode 100644 static/netbsd/man3/OPENSSL_load_builtin_modules.3 create mode 100644 static/netbsd/man3/OPENSSL_load_u16_le.3 create mode 100644 static/netbsd/man3/OPENSSL_malloc.3 create mode 100644 static/netbsd/man3/OPENSSL_ppccap.3 create mode 100644 static/netbsd/man3/OPENSSL_riscvcap.3 create mode 100644 static/netbsd/man3/OPENSSL_s390xcap.3 create mode 100644 static/netbsd/man3/OPENSSL_secure_malloc.3 create mode 100644 static/netbsd/man3/OPENSSL_strcasecmp.3 create mode 100644 static/netbsd/man3/OSSL_ALGORITHM.3 create mode 100644 static/netbsd/man3/OSSL_CALLBACK.3 create mode 100644 static/netbsd/man3/OSSL_CIPHER_ALGORITHM.3 create mode 100644 static/netbsd/man3/OSSL_CMP_ATAV_set0.3 create mode 100644 static/netbsd/man3/OSSL_CMP_CTX_new.3 create mode 100644 static/netbsd/man3/OSSL_CMP_HDR_get0_transactionID.3 create mode 100644 static/netbsd/man3/OSSL_CMP_ITAV_new_caCerts.3 create mode 100644 static/netbsd/man3/OSSL_CMP_ITAV_set0.3 create mode 100644 static/netbsd/man3/OSSL_CMP_MSG_get0_header.3 create mode 100644 static/netbsd/man3/OSSL_CMP_MSG_http_perform.3 create mode 100644 static/netbsd/man3/OSSL_CMP_SRV_CTX_new.3 create mode 100644 static/netbsd/man3/OSSL_CMP_STATUSINFO_new.3 create mode 100644 static/netbsd/man3/OSSL_CMP_exec_certreq.3 create mode 100644 static/netbsd/man3/OSSL_CMP_log_open.3 create mode 100644 static/netbsd/man3/OSSL_CMP_validate_msg.3 create mode 100644 static/netbsd/man3/OSSL_CORE_MAKE_FUNC.3 create mode 100644 static/netbsd/man3/OSSL_CRMF_MSG_get0_tmpl.3 create mode 100644 static/netbsd/man3/OSSL_CRMF_MSG_set0_validity.3 create mode 100644 static/netbsd/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.3 create mode 100644 static/netbsd/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.3 create mode 100644 static/netbsd/man3/OSSL_CRMF_pbmp_new.3 create mode 100644 static/netbsd/man3/OSSL_DECODER.3 create mode 100644 static/netbsd/man3/OSSL_DECODER_CTX.3 create mode 100644 static/netbsd/man3/OSSL_DECODER_CTX_new_for_pkey.3 create mode 100644 static/netbsd/man3/OSSL_DECODER_from_bio.3 create mode 100644 static/netbsd/man3/OSSL_DISPATCH.3 create mode 100644 static/netbsd/man3/OSSL_ENCODER.3 create mode 100644 static/netbsd/man3/OSSL_ENCODER_CTX.3 create mode 100644 static/netbsd/man3/OSSL_ENCODER_CTX_new_for_pkey.3 create mode 100644 static/netbsd/man3/OSSL_ENCODER_to_bio.3 create mode 100644 static/netbsd/man3/OSSL_ERR_STATE_save.3 create mode 100644 static/netbsd/man3/OSSL_ESS_check_signing_certs.3 create mode 100644 static/netbsd/man3/OSSL_GENERAL_NAMES_print.3 create mode 100644 static/netbsd/man3/OSSL_HPKE_CTX_new.3 create mode 100644 static/netbsd/man3/OSSL_HTTP_REQ_CTX.3 create mode 100644 static/netbsd/man3/OSSL_HTTP_parse_url.3 create mode 100644 static/netbsd/man3/OSSL_HTTP_transfer.3 create mode 100644 static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX.3 create mode 100644 static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX_print.3 create mode 100644 static/netbsd/man3/OSSL_INDICATOR_set_callback.3 create mode 100644 static/netbsd/man3/OSSL_ITEM.3 create mode 100644 static/netbsd/man3/OSSL_LIB_CTX.3 create mode 100644 static/netbsd/man3/OSSL_LIB_CTX_set_conf_diagnostics.3 create mode 100644 static/netbsd/man3/OSSL_PARAM.3 create mode 100644 static/netbsd/man3/OSSL_PARAM_BLD.3 create mode 100644 static/netbsd/man3/OSSL_PARAM_allocate_from_text.3 create mode 100644 static/netbsd/man3/OSSL_PARAM_dup.3 create mode 100644 static/netbsd/man3/OSSL_PARAM_int.3 create mode 100644 static/netbsd/man3/OSSL_PARAM_print_to_bio.3 create mode 100644 static/netbsd/man3/OSSL_PROVIDER.3 create mode 100644 static/netbsd/man3/OSSL_QUIC_client_method.3 create mode 100644 static/netbsd/man3/OSSL_SELF_TEST_new.3 create mode 100644 static/netbsd/man3/OSSL_SELF_TEST_set_callback.3 create mode 100644 static/netbsd/man3/OSSL_STORE_INFO.3 create mode 100644 static/netbsd/man3/OSSL_STORE_LOADER.3 create mode 100644 static/netbsd/man3/OSSL_STORE_SEARCH.3 create mode 100644 static/netbsd/man3/OSSL_STORE_attach.3 create mode 100644 static/netbsd/man3/OSSL_STORE_expect.3 create mode 100644 static/netbsd/man3/OSSL_STORE_open.3 create mode 100644 static/netbsd/man3/OSSL_sleep.3 create mode 100644 static/netbsd/man3/OSSL_trace_enabled.3 create mode 100644 static/netbsd/man3/OSSL_trace_get_category_num.3 create mode 100644 static/netbsd/man3/OSSL_trace_set_channel.3 create mode 100644 static/netbsd/man3/OpenSSL_add_all_algorithms.3 create mode 100644 static/netbsd/man3/OpenSSL_add_all_algorithms_conf.3 create mode 100644 static/netbsd/man3/OpenSSL_add_all_algorithms_noconf.3 create mode 100644 static/netbsd/man3/OpenSSL_version.3 create mode 100644 static/netbsd/man3/PBMAC1_get1_pbkdf2_param.3 create mode 100644 static/netbsd/man3/PEM_X509_INFO_read_bio_ex.3 create mode 100644 static/netbsd/man3/PEM_bytes_read_bio.3 create mode 100644 static/netbsd/man3/PEM_read.3 create mode 100644 static/netbsd/man3/PEM_read_CMS.3 create mode 100644 static/netbsd/man3/PEM_read_bio_PrivateKey.3 create mode 100644 static/netbsd/man3/PEM_read_bio_ex.3 create mode 100644 static/netbsd/man3/PEM_write_bio_CMS_stream.3 create mode 100644 static/netbsd/man3/PEM_write_bio_PKCS7_stream.3 create mode 100644 static/netbsd/man3/PKCS12_PBE_keyivgen.3 create mode 100644 static/netbsd/man3/PKCS12_SAFEBAG_create_cert.3 create mode 100644 static/netbsd/man3/PKCS12_SAFEBAG_get0_attrs.3 create mode 100644 static/netbsd/man3/PKCS12_SAFEBAG_get1_cert.3 create mode 100644 static/netbsd/man3/PKCS12_SAFEBAG_set0_attrs.3 create mode 100644 static/netbsd/man3/PKCS12_add1_attr_by_NID.3 create mode 100644 static/netbsd/man3/PKCS12_add_CSPName_asc.3 create mode 100644 static/netbsd/man3/PKCS12_add_cert.3 create mode 100644 static/netbsd/man3/PKCS12_add_friendlyname_asc.3 create mode 100644 static/netbsd/man3/PKCS12_add_localkeyid.3 create mode 100644 static/netbsd/man3/PKCS12_add_safe.3 create mode 100644 static/netbsd/man3/PKCS12_create.3 create mode 100644 static/netbsd/man3/PKCS12_decrypt_skey.3 create mode 100644 static/netbsd/man3/PKCS12_gen_mac.3 create mode 100644 static/netbsd/man3/PKCS12_get_friendlyname.3 create mode 100644 static/netbsd/man3/PKCS12_init.3 create mode 100644 static/netbsd/man3/PKCS12_item_decrypt_d2i.3 create mode 100644 static/netbsd/man3/PKCS12_key_gen_utf8_ex.3 create mode 100644 static/netbsd/man3/PKCS12_newpass.3 create mode 100644 static/netbsd/man3/PKCS12_pack_p7encdata.3 create mode 100644 static/netbsd/man3/PKCS12_parse.3 create mode 100644 static/netbsd/man3/PKCS5_PBE_keyivgen.3 create mode 100644 static/netbsd/man3/PKCS5_PBKDF2_HMAC.3 create mode 100644 static/netbsd/man3/PKCS5_PBKDF2_HMAC_SHA1.3 create mode 100644 static/netbsd/man3/PKCS7_decrypt.3 create mode 100644 static/netbsd/man3/PKCS7_encrypt.3 create mode 100644 static/netbsd/man3/PKCS7_get_octet_string.3 create mode 100644 static/netbsd/man3/PKCS7_sign.3 create mode 100644 static/netbsd/man3/PKCS7_sign_add_signer.3 create mode 100644 static/netbsd/man3/PKCS7_type_is_other.3 create mode 100644 static/netbsd/man3/PKCS7_verify.3 create mode 100644 static/netbsd/man3/PKCS8_encrypt.3 create mode 100644 static/netbsd/man3/PKCS8_pkey_add1_attr.3 create mode 100644 static/netbsd/man3/RAND_DRBG_generate.3 create mode 100644 static/netbsd/man3/RAND_DRBG_get0_master.3 create mode 100644 static/netbsd/man3/RAND_DRBG_new.3 create mode 100644 static/netbsd/man3/RAND_DRBG_reseed.3 create mode 100644 static/netbsd/man3/RAND_DRBG_set_callbacks.3 create mode 100644 static/netbsd/man3/RAND_DRBG_set_ex_data.3 create mode 100644 static/netbsd/man3/RAND_add.3 create mode 100644 static/netbsd/man3/RAND_bytes.3 create mode 100644 static/netbsd/man3/RAND_cleanup.3 create mode 100644 static/netbsd/man3/RAND_egd.3 create mode 100644 static/netbsd/man3/RAND_file_name.3 create mode 100644 static/netbsd/man3/RAND_get0_primary.3 create mode 100644 static/netbsd/man3/RAND_get_rand_method.3 create mode 100644 static/netbsd/man3/RAND_load_file.3 create mode 100644 static/netbsd/man3/RAND_pseudo_bytes.3 create mode 100644 static/netbsd/man3/RAND_seed.3 create mode 100644 static/netbsd/man3/RAND_set_DRBG_type.3 create mode 100644 static/netbsd/man3/RAND_set_rand_engine.3 create mode 100644 static/netbsd/man3/RAND_set_rand_method.3 create mode 100644 static/netbsd/man3/RAND_status.3 create mode 100644 static/netbsd/man3/RAND_write_file.3 create mode 100644 static/netbsd/man3/RC4_set_key.3 create mode 100644 static/netbsd/man3/RELEASE_NOTES-2.3 create mode 100644 static/netbsd/man3/RELEASE_NOTES-3.3 create mode 100644 static/netbsd/man3/RIPEMD160_Init.3 create mode 100644 static/netbsd/man3/RSA_blinding_on.3 create mode 100644 static/netbsd/man3/RSA_check_key.3 create mode 100644 static/netbsd/man3/RSA_free.3 create mode 100644 static/netbsd/man3/RSA_generate_key.3 create mode 100644 static/netbsd/man3/RSA_get0_key.3 create mode 100644 static/netbsd/man3/RSA_get_app_data.3 create mode 100644 static/netbsd/man3/RSA_get_ex_new_index.3 create mode 100644 static/netbsd/man3/RSA_get_method.3 create mode 100644 static/netbsd/man3/RSA_meth_new.3 create mode 100644 static/netbsd/man3/RSA_new.3 create mode 100644 static/netbsd/man3/RSA_new_method.3 create mode 100644 static/netbsd/man3/RSA_padding_add_PKCS1_type_1.3 create mode 100644 static/netbsd/man3/RSA_print.3 create mode 100644 static/netbsd/man3/RSA_private_encrypt.3 create mode 100644 static/netbsd/man3/RSA_public_encrypt.3 create mode 100644 static/netbsd/man3/RSA_set_app_data.3 create mode 100644 static/netbsd/man3/RSA_set_method.3 create mode 100644 static/netbsd/man3/RSA_sign.3 create mode 100644 static/netbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 create mode 100644 static/netbsd/man3/RSA_size.3 create mode 100644 static/netbsd/man3/RSA_up_ref.3 create mode 100644 static/netbsd/man3/SCT_new.3 create mode 100644 static/netbsd/man3/SCT_print.3 create mode 100644 static/netbsd/man3/SCT_validate.3 create mode 100644 static/netbsd/man3/SHA256_Init.3 create mode 100644 static/netbsd/man3/SHA3_Selftest.3 create mode 100644 static/netbsd/man3/SHAKE.3 create mode 100644 static/netbsd/man3/SMIME_read_ASN1.3 create mode 100644 static/netbsd/man3/SMIME_read_CMS.3 create mode 100644 static/netbsd/man3/SMIME_read_PKCS7.3 create mode 100644 static/netbsd/man3/SMIME_write_ASN1.3 create mode 100644 static/netbsd/man3/SMIME_write_CMS.3 create mode 100644 static/netbsd/man3/SMIME_write_PKCS7.3 create mode 100644 static/netbsd/man3/SQLITE_ACCESS_EXISTS.3 create mode 100644 static/netbsd/man3/SQLITE_CHANGESETAPPLY_NOSAVEPOINT.3 create mode 100644 static/netbsd/man3/SQLITE_CHANGESETSTART_INVERT.3 create mode 100644 static/netbsd/man3/SQLITE_CHANGESET_DATA.3 create mode 100644 static/netbsd/man3/SQLITE_CHANGESET_OMIT.3 create mode 100644 static/netbsd/man3/SQLITE_CHECKPOINT_PASSIVE.3 create mode 100644 static/netbsd/man3/SQLITE_CONFIG_SINGLETHREAD.3 create mode 100644 static/netbsd/man3/SQLITE_CREATE_INDEX.3 create mode 100644 static/netbsd/man3/SQLITE_DBCONFIG_LOOKASIDE.3 create mode 100644 static/netbsd/man3/SQLITE_DBCONFIG_MAINDBNAME.3 create mode 100644 static/netbsd/man3/SQLITE_DBSTATUS_LOOKASIDE_USED.3 create mode 100644 static/netbsd/man3/SQLITE_DENY.3 create mode 100644 static/netbsd/man3/SQLITE_DESERIALIZE_FREEONCLOSE.3 create mode 100644 static/netbsd/man3/SQLITE_DETERMINISTIC.3 create mode 100644 static/netbsd/man3/SQLITE_ERROR_MISSING_COLLSEQ.3 create mode 100644 static/netbsd/man3/SQLITE_FCNTL_LOCKSTATE.3 create mode 100644 static/netbsd/man3/SQLITE_INDEX_CONSTRAINT_EQ.3 create mode 100644 static/netbsd/man3/SQLITE_INDEX_SCAN_UNIQUE.3 create mode 100644 static/netbsd/man3/SQLITE_INTEGER.3 create mode 100644 static/netbsd/man3/SQLITE_IOCAP_ATOMIC.3 create mode 100644 static/netbsd/man3/SQLITE_IOERR_READ.3 create mode 100644 static/netbsd/man3/SQLITE_LIMIT_LENGTH.3 create mode 100644 static/netbsd/man3/SQLITE_LOCK_NONE.3 create mode 100644 static/netbsd/man3/SQLITE_MUTEX_FAST.3 create mode 100644 static/netbsd/man3/SQLITE_OK.3 create mode 100644 static/netbsd/man3/SQLITE_OPEN_READONLY.3 create mode 100644 static/netbsd/man3/SQLITE_PREPARE_PERSISTENT.3 create mode 100644 static/netbsd/man3/SQLITE_ROLLBACK.3 create mode 100644 static/netbsd/man3/SQLITE_SCANSTAT_COMPLEX.3 create mode 100644 static/netbsd/man3/SQLITE_SCANSTAT_NLOOP.3 create mode 100644 static/netbsd/man3/SQLITE_SERIALIZE_NOCOPY.3 create mode 100644 static/netbsd/man3/SQLITE_SESSION_CONFIG_STRMSIZE.3 create mode 100644 static/netbsd/man3/SQLITE_SESSION_OBJCONFIG_SIZE.3 create mode 100644 static/netbsd/man3/SQLITE_SHM_NLOCK.3 create mode 100644 static/netbsd/man3/SQLITE_SHM_UNLOCK.3 create mode 100644 static/netbsd/man3/SQLITE_STATUS_MEMORY_USED.3 create mode 100644 static/netbsd/man3/SQLITE_STMTSTATUS_FULLSCAN_STEP.3 create mode 100644 static/netbsd/man3/SQLITE_SYNC_NORMAL.3 create mode 100644 static/netbsd/man3/SQLITE_TESTCTRL_FIRST.3 create mode 100644 static/netbsd/man3/SQLITE_TRACE_STMT.3 create mode 100644 static/netbsd/man3/SQLITE_TXN_NONE.3 create mode 100644 static/netbsd/man3/SQLITE_UTF8.3 create mode 100644 static/netbsd/man3/SQLITE_VERSION.3 create mode 100644 static/netbsd/man3/SQLITE_VTAB_CONSTRAINT_SUPPORT.3 create mode 100644 static/netbsd/man3/SQLITE_WIN32_DATA_DIRECTORY_TYPE.3 create mode 100644 static/netbsd/man3/SRP_Calc_B.3 create mode 100644 static/netbsd/man3/SRP_VBASE_new.3 create mode 100644 static/netbsd/man3/SRP_create_verifier.3 create mode 100644 static/netbsd/man3/SRP_user_pwd_new.3 create mode 100644 static/netbsd/man3/SSL_CIPHER_get_name.3 create mode 100644 static/netbsd/man3/SSL_COMP_add_compression_method.3 create mode 100644 static/netbsd/man3/SSL_CONF_CTX_new.3 create mode 100644 static/netbsd/man3/SSL_CONF_CTX_set1_prefix.3 create mode 100644 static/netbsd/man3/SSL_CONF_CTX_set_flags.3 create mode 100644 static/netbsd/man3/SSL_CONF_CTX_set_ssl_ctx.3 create mode 100644 static/netbsd/man3/SSL_CONF_cmd.3 create mode 100644 static/netbsd/man3/SSL_CONF_cmd_argv.3 create mode 100644 static/netbsd/man3/SSL_CTX_add1_chain_cert.3 create mode 100644 static/netbsd/man3/SSL_CTX_add_extra_chain_cert.3 create mode 100644 static/netbsd/man3/SSL_CTX_add_session.3 create mode 100644 static/netbsd/man3/SSL_CTX_config.3 create mode 100644 static/netbsd/man3/SSL_CTX_ctrl.3 create mode 100644 static/netbsd/man3/SSL_CTX_dane_enable.3 create mode 100644 static/netbsd/man3/SSL_CTX_flush_sessions.3 create mode 100644 static/netbsd/man3/SSL_CTX_free.3 create mode 100644 static/netbsd/man3/SSL_CTX_get0_param.3 create mode 100644 static/netbsd/man3/SSL_CTX_get_ex_new_index.3 create mode 100644 static/netbsd/man3/SSL_CTX_get_verify_mode.3 create mode 100644 static/netbsd/man3/SSL_CTX_has_client_custom_ext.3 create mode 100644 static/netbsd/man3/SSL_CTX_load_verify_locations.3 create mode 100644 static/netbsd/man3/SSL_CTX_new.3 create mode 100644 static/netbsd/man3/SSL_CTX_sess_number.3 create mode 100644 static/netbsd/man3/SSL_CTX_sess_set_cache_size.3 create mode 100644 static/netbsd/man3/SSL_CTX_sess_set_get_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_sessions.3 create mode 100644 static/netbsd/man3/SSL_CTX_set0_CA_list.3 create mode 100644 static/netbsd/man3/SSL_CTX_set1_cert_comp_preference.3 create mode 100644 static/netbsd/man3/SSL_CTX_set1_curves.3 create mode 100644 static/netbsd/man3/SSL_CTX_set1_sigalgs.3 create mode 100644 static/netbsd/man3/SSL_CTX_set1_verify_cert_store.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_alpn_select_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_cert_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_cert_store.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_cert_verify_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_cipher_list.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_client_CA_list.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_client_cert_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_client_hello_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_ct_validation_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_ctlog_list_file.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_custom_cli_ext.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_default_passwd_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_domain_flags.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_ex_data.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_generate_session_id.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_info_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_keylog_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_max_cert_list.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_min_proto_version.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_mode.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_msg_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_new_pending_conn_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_num_tickets.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_options.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_psk_client_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_quiet_shutdown.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_read_ahead.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_record_padding_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_security_level.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_session_cache_mode.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_session_id_context.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_session_ticket_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_split_send_fragment.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_srp_password.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_ssl_version.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_stateless_cookie_generate_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_timeout.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tlsext_status_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tmp_dh_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tmp_ecdh.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 create mode 100644 static/netbsd/man3/SSL_CTX_set_verify.3 create mode 100644 static/netbsd/man3/SSL_CTX_use_certificate.3 create mode 100644 static/netbsd/man3/SSL_CTX_use_psk_identity_hint.3 create mode 100644 static/netbsd/man3/SSL_CTX_use_serverinfo.3 create mode 100644 static/netbsd/man3/SSL_SESSION_free.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get0_cipher.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get0_hostname.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get0_id_context.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get0_peer.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get_compress_id.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get_ex_data.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get_ex_new_index.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get_protocol_version.3 create mode 100644 static/netbsd/man3/SSL_SESSION_get_time.3 create mode 100644 static/netbsd/man3/SSL_SESSION_has_ticket.3 create mode 100644 static/netbsd/man3/SSL_SESSION_is_resumable.3 create mode 100644 static/netbsd/man3/SSL_SESSION_print.3 create mode 100644 static/netbsd/man3/SSL_SESSION_set1_id.3 create mode 100644 static/netbsd/man3/SSL_accept.3 create mode 100644 static/netbsd/man3/SSL_accept_stream.3 create mode 100644 static/netbsd/man3/SSL_alert_type_string.3 create mode 100644 static/netbsd/man3/SSL_alloc_buffers.3 create mode 100644 static/netbsd/man3/SSL_check_chain.3 create mode 100644 static/netbsd/man3/SSL_clear.3 create mode 100644 static/netbsd/man3/SSL_connect.3 create mode 100644 static/netbsd/man3/SSL_do_handshake.3 create mode 100644 static/netbsd/man3/SSL_export_keying_material.3 create mode 100644 static/netbsd/man3/SSL_extension_supported.3 create mode 100644 static/netbsd/man3/SSL_free.3 create mode 100644 static/netbsd/man3/SSL_get0_connection.3 create mode 100644 static/netbsd/man3/SSL_get0_group_name.3 create mode 100644 static/netbsd/man3/SSL_get0_peer_rpk.3 create mode 100644 static/netbsd/man3/SSL_get0_peer_scts.3 create mode 100644 static/netbsd/man3/SSL_get1_builtin_sigalgs.3 create mode 100644 static/netbsd/man3/SSL_get_SSL_CTX.3 create mode 100644 static/netbsd/man3/SSL_get_all_async_fds.3 create mode 100644 static/netbsd/man3/SSL_get_certificate.3 create mode 100644 static/netbsd/man3/SSL_get_ciphers.3 create mode 100644 static/netbsd/man3/SSL_get_client_CA_list.3 create mode 100644 static/netbsd/man3/SSL_get_client_random.3 create mode 100644 static/netbsd/man3/SSL_get_conn_close_info.3 create mode 100644 static/netbsd/man3/SSL_get_current_cipher.3 create mode 100644 static/netbsd/man3/SSL_get_default_timeout.3 create mode 100644 static/netbsd/man3/SSL_get_error.3 create mode 100644 static/netbsd/man3/SSL_get_event_timeout.3 create mode 100644 static/netbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 create mode 100644 static/netbsd/man3/SSL_get_ex_new_index.3 create mode 100644 static/netbsd/man3/SSL_get_extms_support.3 create mode 100644 static/netbsd/man3/SSL_get_fd.3 create mode 100644 static/netbsd/man3/SSL_get_handshake_rtt.3 create mode 100644 static/netbsd/man3/SSL_get_peer_cert_chain.3 create mode 100644 static/netbsd/man3/SSL_get_peer_certificate.3 create mode 100644 static/netbsd/man3/SSL_get_peer_signature_nid.3 create mode 100644 static/netbsd/man3/SSL_get_peer_tmp_key.3 create mode 100644 static/netbsd/man3/SSL_get_psk_identity.3 create mode 100644 static/netbsd/man3/SSL_get_rbio.3 create mode 100644 static/netbsd/man3/SSL_get_rpoll_descriptor.3 create mode 100644 static/netbsd/man3/SSL_get_server_tmp_key.3 create mode 100644 static/netbsd/man3/SSL_get_session.3 create mode 100644 static/netbsd/man3/SSL_get_shared_sigalgs.3 create mode 100644 static/netbsd/man3/SSL_get_stream_id.3 create mode 100644 static/netbsd/man3/SSL_get_stream_read_state.3 create mode 100644 static/netbsd/man3/SSL_get_value_uint.3 create mode 100644 static/netbsd/man3/SSL_get_verify_result.3 create mode 100644 static/netbsd/man3/SSL_get_version.3 create mode 100644 static/netbsd/man3/SSL_group_to_name.3 create mode 100644 static/netbsd/man3/SSL_handle_events.3 create mode 100644 static/netbsd/man3/SSL_in_init.3 create mode 100644 static/netbsd/man3/SSL_inject_net_dgram.3 create mode 100644 static/netbsd/man3/SSL_key_update.3 create mode 100644 static/netbsd/man3/SSL_library_init.3 create mode 100644 static/netbsd/man3/SSL_load_client_CA_file.3 create mode 100644 static/netbsd/man3/SSL_new.3 create mode 100644 static/netbsd/man3/SSL_new_domain.3 create mode 100644 static/netbsd/man3/SSL_new_listener.3 create mode 100644 static/netbsd/man3/SSL_new_stream.3 create mode 100644 static/netbsd/man3/SSL_pending.3 create mode 100644 static/netbsd/man3/SSL_poll.3 create mode 100644 static/netbsd/man3/SSL_read.3 create mode 100644 static/netbsd/man3/SSL_read_early_data.3 create mode 100644 static/netbsd/man3/SSL_rstate_string.3 create mode 100644 static/netbsd/man3/SSL_session_reused.3 create mode 100644 static/netbsd/man3/SSL_set1_host.3 create mode 100644 static/netbsd/man3/SSL_set1_initial_peer_addr.3 create mode 100644 static/netbsd/man3/SSL_set1_server_cert_type.3 create mode 100644 static/netbsd/man3/SSL_set_async_callback.3 create mode 100644 static/netbsd/man3/SSL_set_bio.3 create mode 100644 static/netbsd/man3/SSL_set_blocking_mode.3 create mode 100644 static/netbsd/man3/SSL_set_connect_state.3 create mode 100644 static/netbsd/man3/SSL_set_default_stream_mode.3 create mode 100644 static/netbsd/man3/SSL_set_fd.3 create mode 100644 static/netbsd/man3/SSL_set_incoming_stream_policy.3 create mode 100644 static/netbsd/man3/SSL_set_quic_tls_cbs.3 create mode 100644 static/netbsd/man3/SSL_set_retry_verify.3 create mode 100644 static/netbsd/man3/SSL_set_session.3 create mode 100644 static/netbsd/man3/SSL_set_session_secret_cb.3 create mode 100644 static/netbsd/man3/SSL_set_shutdown.3 create mode 100644 static/netbsd/man3/SSL_set_verify_result.3 create mode 100644 static/netbsd/man3/SSL_shutdown.3 create mode 100644 static/netbsd/man3/SSL_state_string.3 create mode 100644 static/netbsd/man3/SSL_stream_conclude.3 create mode 100644 static/netbsd/man3/SSL_stream_reset.3 create mode 100644 static/netbsd/man3/SSL_want.3 create mode 100644 static/netbsd/man3/SSL_write.3 create mode 100644 static/netbsd/man3/SSLeay_version.3 create mode 100644 static/netbsd/man3/TS_RESP_CTX_new.3 create mode 100644 static/netbsd/man3/TS_VERIFY_CTX.3 create mode 100644 static/netbsd/man3/TS_VERIFY_CTX_set_certs.3 create mode 100644 static/netbsd/man3/Tspi_ChangeAuth.3 create mode 100644 static/netbsd/man3/Tspi_ChangeAuthAsym.3 create mode 100644 static/netbsd/man3/Tspi_Context_Close.3 create mode 100644 static/netbsd/man3/Tspi_Context_CloseObject.3 create mode 100644 static/netbsd/man3/Tspi_Context_Connect.3 create mode 100644 static/netbsd/man3/Tspi_Context_Create.3 create mode 100644 static/netbsd/man3/Tspi_Context_CreateObject.3 create mode 100644 static/netbsd/man3/Tspi_Context_FreeMemory.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetCapability.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetDefaultPolicy.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetKeyByPublicInfo.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetKeyByUUID.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID2.3 create mode 100644 static/netbsd/man3/Tspi_Context_GetTpmObject.3 create mode 100644 static/netbsd/man3/Tspi_Context_LoadKeyByBlob.3 create mode 100644 static/netbsd/man3/Tspi_Context_LoadKeyByUUID.3 create mode 100644 static/netbsd/man3/Tspi_Context_RegisterKey.3 create mode 100644 static/netbsd/man3/Tspi_Context_UnregisterKey.3 create mode 100644 static/netbsd/man3/Tspi_DAA_IssueCredential.3 create mode 100644 static/netbsd/man3/Tspi_DAA_IssueInit.3 create mode 100644 static/netbsd/man3/Tspi_DAA_IssueSetup.3 create mode 100644 static/netbsd/man3/Tspi_DAA_IssuerKeyVerification.3 create mode 100644 static/netbsd/man3/Tspi_DAA_VerifyInit.3 create mode 100644 static/netbsd/man3/Tspi_DAA_VerifySignature.3 create mode 100644 static/netbsd/man3/Tspi_Data_Bind.3 create mode 100644 static/netbsd/man3/Tspi_Data_Seal.3 create mode 100644 static/netbsd/man3/Tspi_Data_Unbind.3 create mode 100644 static/netbsd/man3/Tspi_Data_Unseal.3 create mode 100644 static/netbsd/man3/Tspi_DecodeBER_TssBlob.3 create mode 100644 static/netbsd/man3/Tspi_EncodeDER_TssBlob.3 create mode 100644 static/netbsd/man3/Tspi_GetAttribData.3 create mode 100644 static/netbsd/man3/Tspi_GetAttribUint32.3 create mode 100644 static/netbsd/man3/Tspi_GetPolicyObject.3 create mode 100644 static/netbsd/man3/Tspi_Hash_GetHashValue.3 create mode 100644 static/netbsd/man3/Tspi_Hash_SetHashValue.3 create mode 100644 static/netbsd/man3/Tspi_Hash_Sign.3 create mode 100644 static/netbsd/man3/Tspi_Hash_UpdateHashValue.3 create mode 100644 static/netbsd/man3/Tspi_Hash_VerifySignature.3 create mode 100644 static/netbsd/man3/Tspi_Key_CertifyKey.3 create mode 100644 static/netbsd/man3/Tspi_Key_ConvertMigrationBlob.3 create mode 100644 static/netbsd/man3/Tspi_Key_CreateKey.3 create mode 100644 static/netbsd/man3/Tspi_Key_CreateMigrationBlob.3 create mode 100644 static/netbsd/man3/Tspi_Key_GetPubKey.3 create mode 100644 static/netbsd/man3/Tspi_Key_LoadKey.3 create mode 100644 static/netbsd/man3/Tspi_Key_UnloadKey.3 create mode 100644 static/netbsd/man3/Tspi_Key_WrapKey.3 create mode 100644 static/netbsd/man3/Tspi_PcrComposite_GetPcrValue.3 create mode 100644 static/netbsd/man3/Tspi_PcrComposite_SelectPcrIndex.3 create mode 100644 static/netbsd/man3/Tspi_PcrComposite_SetPcrValue.3 create mode 100644 static/netbsd/man3/Tspi_Policy_AssignToObject.3 create mode 100644 static/netbsd/man3/Tspi_Policy_FlushSecret.3 create mode 100644 static/netbsd/man3/Tspi_Policy_SetSecret.3 create mode 100644 static/netbsd/man3/Tspi_SetAttribData.3 create mode 100644 static/netbsd/man3/Tspi_SetAttribUint32.3 create mode 100644 static/netbsd/man3/Tspi_TPM_AuthorizeMigrationTicket.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CMKSetRestrictions.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CertifySelfTest.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CheckMaintenancePubKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_ClearOwner.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CollateIdentityRequest.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CreateEndorsementKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_CreateMaintenanceArchive.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DAA_JoinCreateDaaPubKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DAA_JoinInit.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DAA_JoinStoreCredential.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DAA_Sign.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DirRead.3 create mode 100644 static/netbsd/man3/Tspi_TPM_DirWrite.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetAuditDigest.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetCapability.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetEvent.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetEventLog.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetEvents.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetPubEndorsementKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetRandom.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetStatus.3 create mode 100644 static/netbsd/man3/Tspi_TPM_GetTestResult.3 create mode 100644 static/netbsd/man3/Tspi_TPM_KillMaintenanceFeature.3 create mode 100644 static/netbsd/man3/Tspi_TPM_LoadMaintenancePubKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_OwnerGetSRKPubKey.3 create mode 100644 static/netbsd/man3/Tspi_TPM_PcrExtend.3 create mode 100644 static/netbsd/man3/Tspi_TPM_PcrRead.3 create mode 100644 static/netbsd/man3/Tspi_TPM_Quote.3 create mode 100644 static/netbsd/man3/Tspi_TPM_Quote2.3 create mode 100644 static/netbsd/man3/Tspi_TPM_SelfTestFull.3 create mode 100644 static/netbsd/man3/Tspi_TPM_SetStatus.3 create mode 100644 static/netbsd/man3/Tspi_TPM_StirRandom.3 create mode 100644 static/netbsd/man3/Tspi_TPM_TakeOwnership.3 create mode 100644 static/netbsd/man3/UI_STRING.3 create mode 100644 static/netbsd/man3/UI_UTIL_read_pw.3 create mode 100644 static/netbsd/man3/UI_create_method.3 create mode 100644 static/netbsd/man3/UI_new.3 create mode 100644 static/netbsd/man3/WINCNG_CIPHER_ALGORITHM.3 create mode 100644 static/netbsd/man3/WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3 create mode 100644 static/netbsd/man3/X509V3_get_d2i.3 create mode 100644 static/netbsd/man3/X509V3_set_ctx.3 create mode 100644 static/netbsd/man3/X509_ACERT_add1_attr.3 create mode 100644 static/netbsd/man3/X509_ACERT_add_attr_nconf.3 create mode 100644 static/netbsd/man3/X509_ACERT_get0_holder_baseCertId.3 create mode 100644 static/netbsd/man3/X509_ACERT_get_attr.3 create mode 100644 static/netbsd/man3/X509_ACERT_print_ex.3 create mode 100644 static/netbsd/man3/X509_ALGOR_dup.3 create mode 100644 static/netbsd/man3/X509_ATTRIBUTE.3 create mode 100644 static/netbsd/man3/X509_CRL_get0_by_serial.3 create mode 100644 static/netbsd/man3/X509_EXTENSION_set_object.3 create mode 100644 static/netbsd/man3/X509_LOOKUP.3 create mode 100644 static/netbsd/man3/X509_LOOKUP_hash_dir.3 create mode 100644 static/netbsd/man3/X509_LOOKUP_meth_new.3 create mode 100644 static/netbsd/man3/X509_NAME_ENTRY_get_object.3 create mode 100644 static/netbsd/man3/X509_NAME_add_entry_by_txt.3 create mode 100644 static/netbsd/man3/X509_NAME_get0_der.3 create mode 100644 static/netbsd/man3/X509_NAME_get_index_by_NID.3 create mode 100644 static/netbsd/man3/X509_NAME_print_ex.3 create mode 100644 static/netbsd/man3/X509_PUBKEY_new.3 create mode 100644 static/netbsd/man3/X509_REQ_get_attr.3 create mode 100644 static/netbsd/man3/X509_REQ_get_extensions.3 create mode 100644 static/netbsd/man3/X509_SIG_get0.3 create mode 100644 static/netbsd/man3/X509_STORE_CTX_get_by_subject.3 create mode 100644 static/netbsd/man3/X509_STORE_CTX_get_error.3 create mode 100644 static/netbsd/man3/X509_STORE_CTX_get_ex_new_index.3 create mode 100644 static/netbsd/man3/X509_STORE_CTX_new.3 create mode 100644 static/netbsd/man3/X509_STORE_CTX_set_verify_cb.3 create mode 100644 static/netbsd/man3/X509_STORE_add_cert.3 create mode 100644 static/netbsd/man3/X509_STORE_get0_param.3 create mode 100644 static/netbsd/man3/X509_STORE_new.3 create mode 100644 static/netbsd/man3/X509_STORE_set_verify_cb_func.3 create mode 100644 static/netbsd/man3/X509_VERIFY_PARAM_set_flags.3 create mode 100644 static/netbsd/man3/X509_add_cert.3 create mode 100644 static/netbsd/man3/X509_check_ca.3 create mode 100644 static/netbsd/man3/X509_check_host.3 create mode 100644 static/netbsd/man3/X509_check_issued.3 create mode 100644 static/netbsd/man3/X509_check_private_key.3 create mode 100644 static/netbsd/man3/X509_check_purpose.3 create mode 100644 static/netbsd/man3/X509_cmp.3 create mode 100644 static/netbsd/man3/X509_cmp_time.3 create mode 100644 static/netbsd/man3/X509_digest.3 create mode 100644 static/netbsd/man3/X509_dup.3 create mode 100644 static/netbsd/man3/X509_get0_distinguishing_id.3 create mode 100644 static/netbsd/man3/X509_get0_notBefore.3 create mode 100644 static/netbsd/man3/X509_get0_signature.3 create mode 100644 static/netbsd/man3/X509_get0_uids.3 create mode 100644 static/netbsd/man3/X509_get_default_cert_file.3 create mode 100644 static/netbsd/man3/X509_get_extension_flags.3 create mode 100644 static/netbsd/man3/X509_get_pubkey.3 create mode 100644 static/netbsd/man3/X509_get_serialNumber.3 create mode 100644 static/netbsd/man3/X509_get_subject_name.3 create mode 100644 static/netbsd/man3/X509_get_version.3 create mode 100644 static/netbsd/man3/X509_load_http.3 create mode 100644 static/netbsd/man3/X509_new.3 create mode 100644 static/netbsd/man3/X509_sign.3 create mode 100644 static/netbsd/man3/X509_verify.3 create mode 100644 static/netbsd/man3/X509_verify_cert.3 create mode 100644 static/netbsd/man3/X509v3_get_ext_by_NID.3 create mode 100644 static/netbsd/man3/__builtin_object_size.3 create mode 100644 static/netbsd/man3/_lwp_makecontext.3 create mode 100644 static/netbsd/man3/a64l.3 create mode 100644 static/netbsd/man3/abort.3 create mode 100644 static/netbsd/man3/abs.3 create mode 100644 static/netbsd/man3/acl.3 create mode 100644 static/netbsd/man3/acl_add_flag_np.3 create mode 100644 static/netbsd/man3/acl_add_perm.3 create mode 100644 static/netbsd/man3/acl_calc_mask.3 create mode 100644 static/netbsd/man3/acl_clear_flags_np.3 create mode 100644 static/netbsd/man3/acl_clear_perms.3 create mode 100644 static/netbsd/man3/acl_copy_entry.3 create mode 100644 static/netbsd/man3/acl_create_entry.3 create mode 100644 static/netbsd/man3/acl_delete.3 create mode 100644 static/netbsd/man3/acl_delete_entry.3 create mode 100644 static/netbsd/man3/acl_delete_flag_np.3 create mode 100644 static/netbsd/man3/acl_delete_perm.3 create mode 100644 static/netbsd/man3/acl_dup.3 create mode 100644 static/netbsd/man3/acl_free.3 create mode 100644 static/netbsd/man3/acl_from_text.3 create mode 100644 static/netbsd/man3/acl_get.3 create mode 100644 static/netbsd/man3/acl_get_brand_np.3 create mode 100644 static/netbsd/man3/acl_get_entry.3 create mode 100644 static/netbsd/man3/acl_get_entry_type_np.3 create mode 100644 static/netbsd/man3/acl_get_flag_np.3 create mode 100644 static/netbsd/man3/acl_get_flagset_np.3 create mode 100644 static/netbsd/man3/acl_get_perm_np.3 create mode 100644 static/netbsd/man3/acl_get_permset.3 create mode 100644 static/netbsd/man3/acl_get_qualifier.3 create mode 100644 static/netbsd/man3/acl_get_tag_type.3 create mode 100644 static/netbsd/man3/acl_init.3 create mode 100644 static/netbsd/man3/acl_is_trivial_np.3 create mode 100644 static/netbsd/man3/acl_set.3 create mode 100644 static/netbsd/man3/acl_set_entry_type_np.3 create mode 100644 static/netbsd/man3/acl_set_flagset_np.3 create mode 100644 static/netbsd/man3/acl_set_permset.3 create mode 100644 static/netbsd/man3/acl_set_qualifier.3 create mode 100644 static/netbsd/man3/acl_set_tag_type.3 create mode 100644 static/netbsd/man3/acl_strip_np.3 create mode 100644 static/netbsd/man3/acl_to_text.3 create mode 100644 static/netbsd/man3/acl_valid.3 create mode 100644 static/netbsd/man3/acos.3 create mode 100644 static/netbsd/man3/acosh.3 create mode 100644 static/netbsd/man3/affinity.3 create mode 100644 static/netbsd/man3/aio.3 create mode 100644 static/netbsd/man3/aio_cancel.3 create mode 100644 static/netbsd/man3/aio_error.3 create mode 100644 static/netbsd/man3/aio_fsync.3 create mode 100644 static/netbsd/man3/aio_read.3 create mode 100644 static/netbsd/man3/aio_return.3 create mode 100644 static/netbsd/man3/aio_suspend.3 create mode 100644 static/netbsd/man3/aio_write.3 create mode 100644 static/netbsd/man3/alarm.3 create mode 100644 static/netbsd/man3/alloca.3 create mode 100644 static/netbsd/man3/apropos-utils.3 create mode 100644 static/netbsd/man3/arc4random.3 create mode 100644 static/netbsd/man3/archive_entry.3 create mode 100644 static/netbsd/man3/archive_entry_acl.3 create mode 100644 static/netbsd/man3/archive_entry_linkify.3 create mode 100644 static/netbsd/man3/archive_entry_misc.3 create mode 100644 static/netbsd/man3/archive_entry_paths.3 create mode 100644 static/netbsd/man3/archive_entry_perms.3 create mode 100644 static/netbsd/man3/archive_entry_stat.3 create mode 100644 static/netbsd/man3/archive_entry_time.3 create mode 100644 static/netbsd/man3/archive_read.3 create mode 100644 static/netbsd/man3/archive_read_add_passphrase.3 create mode 100644 static/netbsd/man3/archive_read_data.3 create mode 100644 static/netbsd/man3/archive_read_disk.3 create mode 100644 static/netbsd/man3/archive_read_extract.3 create mode 100644 static/netbsd/man3/archive_read_filter.3 create mode 100644 static/netbsd/man3/archive_read_format.3 create mode 100644 static/netbsd/man3/archive_read_free.3 create mode 100644 static/netbsd/man3/archive_read_header.3 create mode 100644 static/netbsd/man3/archive_read_new.3 create mode 100644 static/netbsd/man3/archive_read_open.3 create mode 100644 static/netbsd/man3/archive_read_set_options.3 create mode 100644 static/netbsd/man3/archive_util.3 create mode 100644 static/netbsd/man3/archive_write.3 create mode 100644 static/netbsd/man3/archive_write_blocksize.3 create mode 100644 static/netbsd/man3/archive_write_data.3 create mode 100644 static/netbsd/man3/archive_write_disk.3 create mode 100644 static/netbsd/man3/archive_write_filter.3 create mode 100644 static/netbsd/man3/archive_write_finish_entry.3 create mode 100644 static/netbsd/man3/archive_write_format.3 create mode 100644 static/netbsd/man3/archive_write_free.3 create mode 100644 static/netbsd/man3/archive_write_header.3 create mode 100644 static/netbsd/man3/archive_write_new.3 create mode 100644 static/netbsd/man3/archive_write_open.3 create mode 100644 static/netbsd/man3/archive_write_set_options.3 create mode 100644 static/netbsd/man3/archive_write_set_passphrase.3 create mode 100644 static/netbsd/man3/asin.3 create mode 100644 static/netbsd/man3/asinh.3 create mode 100644 static/netbsd/man3/at_quick_exit.3 create mode 100644 static/netbsd/man3/atan.3 create mode 100644 static/netbsd/man3/atan2.3 create mode 100644 static/netbsd/man3/atanh.3 create mode 100644 static/netbsd/man3/atexit.3 create mode 100644 static/netbsd/man3/atf-c++-api.3 create mode 100644 static/netbsd/man3/atf-c-api.3 create mode 100644 static/netbsd/man3/atf-sh-api.3 create mode 100644 static/netbsd/man3/atof.3 create mode 100644 static/netbsd/man3/atoi.3 create mode 100644 static/netbsd/man3/atol.3 create mode 100644 static/netbsd/man3/atoll.3 create mode 100644 static/netbsd/man3/atomic_add.3 create mode 100644 static/netbsd/man3/atomic_and.3 create mode 100644 static/netbsd/man3/atomic_cas.3 create mode 100644 static/netbsd/man3/atomic_dec.3 create mode 100644 static/netbsd/man3/atomic_inc.3 create mode 100644 static/netbsd/man3/atomic_ops.3 create mode 100644 static/netbsd/man3/atomic_or.3 create mode 100644 static/netbsd/man3/atomic_swap.3 create mode 100644 static/netbsd/man3/b2i_PVK_bio_ex.3 create mode 100644 static/netbsd/man3/backtrace.3 create mode 100644 static/netbsd/man3/bad.include-toplevel.3 create mode 100644 static/netbsd/man3/basename.3 create mode 100644 static/netbsd/man3/bcmp.3 create mode 100644 static/netbsd/man3/bcopy.3 create mode 100644 static/netbsd/man3/bind_textdomain_codeset.3 create mode 100644 static/netbsd/man3/bindresvport.3 create mode 100644 static/netbsd/man3/bindtextdomain.3 create mode 100644 static/netbsd/man3/bluetooth.3 create mode 100644 static/netbsd/man3/bm.3 create mode 100644 static/netbsd/man3/bsd_signal.3 create mode 100644 static/netbsd/man3/bsdmalloc.3 create mode 100644 static/netbsd/man3/bsearch.3 create mode 100644 static/netbsd/man3/bstring.3 create mode 100644 static/netbsd/man3/bswap.3 create mode 100644 static/netbsd/man3/bt_dev.3 create mode 100644 static/netbsd/man3/btowc.3 create mode 100644 static/netbsd/man3/btree.3 create mode 100644 static/netbsd/man3/buffer.h.3 create mode 100644 static/netbsd/man3/buffer_compat.h.3 create mode 100644 static/netbsd/man3/bufferevent.3 create mode 100644 static/netbsd/man3/bufferevent.h.3 create mode 100644 static/netbsd/man3/bufferevent_ssl.h.3 create mode 100644 static/netbsd/man3/byteorder.3 create mode 100644 static/netbsd/man3/bzero.3 create mode 100644 static/netbsd/man3/c16rtomb.3 create mode 100644 static/netbsd/man3/c32rtomb.3 create mode 100644 static/netbsd/man3/c8rtomb.3 create mode 100644 static/netbsd/man3/cabs.3 create mode 100644 static/netbsd/man3/cacos.3 create mode 100644 static/netbsd/man3/cacosh.3 create mode 100644 static/netbsd/man3/call_once.3 create mode 100644 static/netbsd/man3/carg.3 create mode 100644 static/netbsd/man3/casin.3 create mode 100644 static/netbsd/man3/casinh.3 create mode 100644 static/netbsd/man3/catan.3 create mode 100644 static/netbsd/man3/catanh.3 create mode 100644 static/netbsd/man3/catclose.3 create mode 100644 static/netbsd/man3/catgets.3 create mode 100644 static/netbsd/man3/catopen.3 create mode 100644 static/netbsd/man3/ccos.3 create mode 100644 static/netbsd/man3/ccosh.3 create mode 100644 static/netbsd/man3/cdbr.3 create mode 100644 static/netbsd/man3/cdbw.3 create mode 100644 static/netbsd/man3/ceil.3 create mode 100644 static/netbsd/man3/cexp.3 create mode 100644 static/netbsd/man3/cgetcap.3 create mode 100644 static/netbsd/man3/cimag.3 create mode 100644 static/netbsd/man3/clock.3 create mode 100644 static/netbsd/man3/clog.3 create mode 100644 static/netbsd/man3/close_db.3 create mode 100644 static/netbsd/man3/closefrom.3 create mode 100644 static/netbsd/man3/cnd.3 create mode 100644 static/netbsd/man3/com_err.3 create mode 100644 static/netbsd/man3/confstr.3 create mode 100644 static/netbsd/man3/conj.3 create mode 100644 static/netbsd/man3/consttime_memequal.3 create mode 100644 static/netbsd/man3/copysign.3 create mode 100644 static/netbsd/man3/cos.3 create mode 100644 static/netbsd/man3/cosh.3 create mode 100644 static/netbsd/man3/cpow.3 create mode 100644 static/netbsd/man3/cproj.3 create mode 100644 static/netbsd/man3/cpuset.3 create mode 100644 static/netbsd/man3/creal.3 create mode 100644 static/netbsd/man3/creat.3 create mode 100644 static/netbsd/man3/crypt.3 create mode 100644 static/netbsd/man3/crypto.3 create mode 100644 static/netbsd/man3/csh.3 create mode 100644 static/netbsd/man3/csin.3 create mode 100644 static/netbsd/man3/csinh.3 create mode 100644 static/netbsd/man3/csqrt.3 create mode 100644 static/netbsd/man3/ctan.3 create mode 100644 static/netbsd/man3/ctanh.3 create mode 100644 static/netbsd/man3/ctermid.3 create mode 100644 static/netbsd/man3/ctime.3 create mode 100644 static/netbsd/man3/ctype.3 create mode 100644 static/netbsd/man3/curses.3 create mode 100644 static/netbsd/man3/curses_addch.3 create mode 100644 static/netbsd/man3/curses_addchstr.3 create mode 100644 static/netbsd/man3/curses_addstr.3 create mode 100644 static/netbsd/man3/curses_attributes.3 create mode 100644 static/netbsd/man3/curses_background.3 create mode 100644 static/netbsd/man3/curses_border.3 create mode 100644 static/netbsd/man3/curses_cchar.3 create mode 100644 static/netbsd/man3/curses_chgat.3 create mode 100644 static/netbsd/man3/curses_clear.3 create mode 100644 static/netbsd/man3/curses_color.3 create mode 100644 static/netbsd/man3/curses_cursor.3 create mode 100644 static/netbsd/man3/curses_default_colors.3 create mode 100644 static/netbsd/man3/curses_delch.3 create mode 100644 static/netbsd/man3/curses_deleteln.3 create mode 100644 static/netbsd/man3/curses_echochar.3 create mode 100644 static/netbsd/man3/curses_fileio.3 create mode 100644 static/netbsd/man3/curses_inch.3 create mode 100644 static/netbsd/man3/curses_input.3 create mode 100644 static/netbsd/man3/curses_insch.3 create mode 100644 static/netbsd/man3/curses_insdelln.3 create mode 100644 static/netbsd/man3/curses_insertln.3 create mode 100644 static/netbsd/man3/curses_keyname.3 create mode 100644 static/netbsd/man3/curses_line.3 create mode 100644 static/netbsd/man3/curses_mouse.3 create mode 100644 static/netbsd/man3/curses_pad.3 create mode 100644 static/netbsd/man3/curses_print.3 create mode 100644 static/netbsd/man3/curses_refresh.3 create mode 100644 static/netbsd/man3/curses_scanw.3 create mode 100644 static/netbsd/man3/curses_screen.3 create mode 100644 static/netbsd/man3/curses_scroll.3 create mode 100644 static/netbsd/man3/curses_slk.3 create mode 100644 static/netbsd/man3/curses_standout.3 create mode 100644 static/netbsd/man3/curses_termcap.3 create mode 100644 static/netbsd/man3/curses_touch.3 create mode 100644 static/netbsd/man3/curses_tty.3 create mode 100644 static/netbsd/man3/curses_underscore.3 create mode 100644 static/netbsd/man3/curses_version.3 create mode 100644 static/netbsd/man3/curses_window.3 create mode 100644 static/netbsd/man3/cuserid.3 create mode 100644 static/netbsd/man3/d2i_ASN1_OBJECT.3 create mode 100644 static/netbsd/man3/d2i_CMS_ContentInfo.3 create mode 100644 static/netbsd/man3/d2i_DHparams.3 create mode 100644 static/netbsd/man3/d2i_DSAPublicKey.3 create mode 100644 static/netbsd/man3/d2i_ECPKParameters.3 create mode 100644 static/netbsd/man3/d2i_ECPrivateKey.3 create mode 100644 static/netbsd/man3/d2i_PKCS8PrivateKey.3 create mode 100644 static/netbsd/man3/d2i_PKCS8PrivateKey_bio.3 create mode 100644 static/netbsd/man3/d2i_PrivateKey.3 create mode 100644 static/netbsd/man3/d2i_RSAPrivateKey.3 create mode 100644 static/netbsd/man3/d2i_RSAPublicKey.3 create mode 100644 static/netbsd/man3/d2i_SSL_SESSION.3 create mode 100644 static/netbsd/man3/d2i_X509.3 create mode 100644 static/netbsd/man3/d2i_X509_ALGOR.3 create mode 100644 static/netbsd/man3/d2i_X509_CRL.3 create mode 100644 static/netbsd/man3/d2i_X509_NAME.3 create mode 100644 static/netbsd/man3/d2i_X509_REQ.3 create mode 100644 static/netbsd/man3/d2i_X509_SIG.3 create mode 100644 static/netbsd/man3/daemon.3 create mode 100644 static/netbsd/man3/data.3 create mode 100644 static/netbsd/man3/dbm_clearerr.3 create mode 100644 static/netbsd/man3/dbopen.3 create mode 100644 static/netbsd/man3/dcgettext.3 create mode 100644 static/netbsd/man3/dcngettext.3 create mode 100644 static/netbsd/man3/deprecated.3 create mode 100644 static/netbsd/man3/des.3 create mode 100644 static/netbsd/man3/devname.3 create mode 100644 static/netbsd/man3/dgettext.3 create mode 100644 static/netbsd/man3/dhcpctl.3 create mode 100644 static/netbsd/man3/directory.3 create mode 100644 static/netbsd/man3/dirname.3 create mode 100644 static/netbsd/man3/disklabel_dkcksum.3 create mode 100644 static/netbsd/man3/disklabel_scan.3 create mode 100644 static/netbsd/man3/div.3 create mode 100644 static/netbsd/man3/dm.3 create mode 100644 static/netbsd/man3/dngettext.3 create mode 100644 static/netbsd/man3/dns.h.3 create mode 100644 static/netbsd/man3/dns_compat.h.3 create mode 100644 static/netbsd/man3/do_add.3 create mode 100644 static/netbsd/man3/duplocale.3 create mode 100644 static/netbsd/man3/dwarf.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_comp_dir.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_const_value_string.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_dataref.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_flag.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_location_expr.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_name.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_producer.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_ref_address.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_reference.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_signed_const.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_string.3 create mode 100644 static/netbsd/man3/dwarf_add_AT_targ_address.3 create mode 100644 static/netbsd/man3/dwarf_add_arange.3 create mode 100644 static/netbsd/man3/dwarf_add_die_to_debug.3 create mode 100644 static/netbsd/man3/dwarf_add_directory_decl.3 create mode 100644 static/netbsd/man3/dwarf_add_expr_addr.3 create mode 100644 static/netbsd/man3/dwarf_add_expr_gen.3 create mode 100644 static/netbsd/man3/dwarf_add_fde_inst.3 create mode 100644 static/netbsd/man3/dwarf_add_file_decl.3 create mode 100644 static/netbsd/man3/dwarf_add_frame_cie.3 create mode 100644 static/netbsd/man3/dwarf_add_frame_fde.3 create mode 100644 static/netbsd/man3/dwarf_add_funcname.3 create mode 100644 static/netbsd/man3/dwarf_add_line_entry.3 create mode 100644 static/netbsd/man3/dwarf_add_pubname.3 create mode 100644 static/netbsd/man3/dwarf_add_typename.3 create mode 100644 static/netbsd/man3/dwarf_add_varname.3 create mode 100644 static/netbsd/man3/dwarf_add_weakname.3 create mode 100644 static/netbsd/man3/dwarf_attr.3 create mode 100644 static/netbsd/man3/dwarf_attrlist.3 create mode 100644 static/netbsd/man3/dwarf_attroffset.3 create mode 100644 static/netbsd/man3/dwarf_attrval_signed.3 create mode 100644 static/netbsd/man3/dwarf_child.3 create mode 100644 static/netbsd/man3/dwarf_dealloc.3 create mode 100644 static/netbsd/man3/dwarf_def_macro.3 create mode 100644 static/netbsd/man3/dwarf_die_abbrev_code.3 create mode 100644 static/netbsd/man3/dwarf_die_link.3 create mode 100644 static/netbsd/man3/dwarf_diename.3 create mode 100644 static/netbsd/man3/dwarf_dieoffset.3 create mode 100644 static/netbsd/man3/dwarf_end_macro_file.3 create mode 100644 static/netbsd/man3/dwarf_errmsg.3 create mode 100644 static/netbsd/man3/dwarf_errno.3 create mode 100644 static/netbsd/man3/dwarf_expand_frame_instructions.3 create mode 100644 static/netbsd/man3/dwarf_expr_current_offset.3 create mode 100644 static/netbsd/man3/dwarf_expr_into_block.3 create mode 100644 static/netbsd/man3/dwarf_fde_cfa_offset.3 create mode 100644 static/netbsd/man3/dwarf_find_macro_value_start.3 create mode 100644 static/netbsd/man3/dwarf_finish.3 create mode 100644 static/netbsd/man3/dwarf_formaddr.3 create mode 100644 static/netbsd/man3/dwarf_formblock.3 create mode 100644 static/netbsd/man3/dwarf_formexprloc.3 create mode 100644 static/netbsd/man3/dwarf_formflag.3 create mode 100644 static/netbsd/man3/dwarf_formref.3 create mode 100644 static/netbsd/man3/dwarf_formsig8.3 create mode 100644 static/netbsd/man3/dwarf_formstring.3 create mode 100644 static/netbsd/man3/dwarf_formudata.3 create mode 100644 static/netbsd/man3/dwarf_get_AT_name.3 create mode 100644 static/netbsd/man3/dwarf_get_abbrev.3 create mode 100644 static/netbsd/man3/dwarf_get_abbrev_children_flag.3 create mode 100644 static/netbsd/man3/dwarf_get_abbrev_code.3 create mode 100644 static/netbsd/man3/dwarf_get_abbrev_entry.3 create mode 100644 static/netbsd/man3/dwarf_get_abbrev_tag.3 create mode 100644 static/netbsd/man3/dwarf_get_address_size.3 create mode 100644 static/netbsd/man3/dwarf_get_arange.3 create mode 100644 static/netbsd/man3/dwarf_get_arange_info.3 create mode 100644 static/netbsd/man3/dwarf_get_aranges.3 create mode 100644 static/netbsd/man3/dwarf_get_cie_index.3 create mode 100644 static/netbsd/man3/dwarf_get_cie_info.3 create mode 100644 static/netbsd/man3/dwarf_get_cie_of_fde.3 create mode 100644 static/netbsd/man3/dwarf_get_cu_die_offset.3 create mode 100644 static/netbsd/man3/dwarf_get_die_infotypes_flag.3 create mode 100644 static/netbsd/man3/dwarf_get_elf.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_at_pc.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_info_for_all_regs.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_info_for_all_regs3.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_info_for_cfa_reg3.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_info_for_reg.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_info_for_reg3.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_instr_bytes.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_list.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_n.3 create mode 100644 static/netbsd/man3/dwarf_get_fde_range.3 create mode 100644 static/netbsd/man3/dwarf_get_form_class.3 create mode 100644 static/netbsd/man3/dwarf_get_funcs.3 create mode 100644 static/netbsd/man3/dwarf_get_globals.3 create mode 100644 static/netbsd/man3/dwarf_get_loclist_entry.3 create mode 100644 static/netbsd/man3/dwarf_get_macro_details.3 create mode 100644 static/netbsd/man3/dwarf_get_pubtypes.3 create mode 100644 static/netbsd/man3/dwarf_get_ranges.3 create mode 100644 static/netbsd/man3/dwarf_get_relocation_info.3 create mode 100644 static/netbsd/man3/dwarf_get_relocation_info_count.3 create mode 100644 static/netbsd/man3/dwarf_get_section_bytes.3 create mode 100644 static/netbsd/man3/dwarf_get_section_max_offsets.3 create mode 100644 static/netbsd/man3/dwarf_get_str.3 create mode 100644 static/netbsd/man3/dwarf_get_types.3 create mode 100644 static/netbsd/man3/dwarf_get_vars.3 create mode 100644 static/netbsd/man3/dwarf_get_weaks.3 create mode 100644 static/netbsd/man3/dwarf_hasattr.3 create mode 100644 static/netbsd/man3/dwarf_hasform.3 create mode 100644 static/netbsd/man3/dwarf_highpc.3 create mode 100644 static/netbsd/man3/dwarf_init.3 create mode 100644 static/netbsd/man3/dwarf_lineno.3 create mode 100644 static/netbsd/man3/dwarf_lne_end_sequence.3 create mode 100644 static/netbsd/man3/dwarf_lne_set_address.3 create mode 100644 static/netbsd/man3/dwarf_loclist.3 create mode 100644 static/netbsd/man3/dwarf_loclist_from_expr.3 create mode 100644 static/netbsd/man3/dwarf_new_die.3 create mode 100644 static/netbsd/man3/dwarf_new_expr.3 create mode 100644 static/netbsd/man3/dwarf_new_fde.3 create mode 100644 static/netbsd/man3/dwarf_next_cu_header.3 create mode 100644 static/netbsd/man3/dwarf_next_types_section.3 create mode 100644 static/netbsd/man3/dwarf_object_init.3 create mode 100644 static/netbsd/man3/dwarf_producer_init.3 create mode 100644 static/netbsd/man3/dwarf_producer_set_isa.3 create mode 100644 static/netbsd/man3/dwarf_reset_section_bytes.3 create mode 100644 static/netbsd/man3/dwarf_set_frame_cfa_value.3 create mode 100644 static/netbsd/man3/dwarf_set_reloc_application.3 create mode 100644 static/netbsd/man3/dwarf_seterrarg.3 create mode 100644 static/netbsd/man3/dwarf_srcfiles.3 create mode 100644 static/netbsd/man3/dwarf_srclines.3 create mode 100644 static/netbsd/man3/dwarf_start_macro_file.3 create mode 100644 static/netbsd/man3/dwarf_tag.3 create mode 100644 static/netbsd/man3/dwarf_transform_to_disk_form.3 create mode 100644 static/netbsd/man3/dwarf_undef_macro.3 create mode 100644 static/netbsd/man3/dwarf_vendor_ext.3 create mode 100644 static/netbsd/man3/dwarf_whatattr.3 create mode 100644 static/netbsd/man3/ec.3 create mode 100644 static/netbsd/man3/ecalloc.3 create mode 100644 static/netbsd/man3/eddsa_pk_new.3 create mode 100644 static/netbsd/man3/editline.3 create mode 100644 static/netbsd/man3/efun.3 create mode 100644 static/netbsd/man3/elf.3 create mode 100644 static/netbsd/man3/elf_begin.3 create mode 100644 static/netbsd/man3/elf_cntl.3 create mode 100644 static/netbsd/man3/elf_end.3 create mode 100644 static/netbsd/man3/elf_errmsg.3 create mode 100644 static/netbsd/man3/elf_fill.3 create mode 100644 static/netbsd/man3/elf_flagdata.3 create mode 100644 static/netbsd/man3/elf_getarhdr.3 create mode 100644 static/netbsd/man3/elf_getarsym.3 create mode 100644 static/netbsd/man3/elf_getbase.3 create mode 100644 static/netbsd/man3/elf_getdata.3 create mode 100644 static/netbsd/man3/elf_getident.3 create mode 100644 static/netbsd/man3/elf_getphdrnum.3 create mode 100644 static/netbsd/man3/elf_getphnum.3 create mode 100644 static/netbsd/man3/elf_getscn.3 create mode 100644 static/netbsd/man3/elf_getshdrnum.3 create mode 100644 static/netbsd/man3/elf_getshdrstrndx.3 create mode 100644 static/netbsd/man3/elf_getshnum.3 create mode 100644 static/netbsd/man3/elf_getshstrndx.3 create mode 100644 static/netbsd/man3/elf_getversion.3 create mode 100644 static/netbsd/man3/elf_hash.3 create mode 100644 static/netbsd/man3/elf_kind.3 create mode 100644 static/netbsd/man3/elf_memory.3 create mode 100644 static/netbsd/man3/elf_next.3 create mode 100644 static/netbsd/man3/elf_open.3 create mode 100644 static/netbsd/man3/elf_rand.3 create mode 100644 static/netbsd/man3/elf_rawfile.3 create mode 100644 static/netbsd/man3/elf_strptr.3 create mode 100644 static/netbsd/man3/elf_update.3 create mode 100644 static/netbsd/man3/elf_version.3 create mode 100644 static/netbsd/man3/endutent.3 create mode 100644 static/netbsd/man3/endutxent.3 create mode 100644 static/netbsd/man3/erf.3 create mode 100644 static/netbsd/man3/err.3 create mode 100644 static/netbsd/man3/es256_pk_new.3 create mode 100644 static/netbsd/man3/es384_pk_new.3 create mode 100644 static/netbsd/man3/ethers.3 create mode 100644 static/netbsd/man3/evbuffer.3 create mode 100644 static/netbsd/man3/evbuffer_cb_info.3 create mode 100644 static/netbsd/man3/evbuffer_iovec.3 create mode 100644 static/netbsd/man3/evbuffer_ptr.3 create mode 100644 static/netbsd/man3/event.3 create mode 100644 static/netbsd/man3/event.h.3 create mode 100644 static/netbsd/man3/event_base.3 create mode 100644 static/netbsd/man3/event_compat.h.3 create mode 100644 static/netbsd/man3/event_config.3 create mode 100644 static/netbsd/man3/evthread_condition_callbacks.3 create mode 100644 static/netbsd/man3/evthread_lock_callbacks.3 create mode 100644 static/netbsd/man3/evutil_addrinfo.3 create mode 100644 static/netbsd/man3/evutil_monotonic_timer.3 create mode 100644 static/netbsd/man3/example.3 create mode 100644 static/netbsd/man3/exec.3 create mode 100644 static/netbsd/man3/exit.3 create mode 100644 static/netbsd/man3/exp.3 create mode 100644 static/netbsd/man3/explicit_memset.3 create mode 100644 static/netbsd/man3/extattr.3 create mode 100644 static/netbsd/man3/extattr_copy_file.3 create mode 100644 static/netbsd/man3/fabs.3 create mode 100644 static/netbsd/man3/fclose.3 create mode 100644 static/netbsd/man3/fdim.3 create mode 100644 static/netbsd/man3/feclearexcept.3 create mode 100644 static/netbsd/man3/feenableexcept.3 create mode 100644 static/netbsd/man3/fegetenv.3 create mode 100644 static/netbsd/man3/fegetround.3 create mode 100644 static/netbsd/man3/fenv.3 create mode 100644 static/netbsd/man3/ferror.3 create mode 100644 static/netbsd/man3/fetch.3 create mode 100644 static/netbsd/man3/fflush.3 create mode 100644 static/netbsd/man3/ffs.3 create mode 100644 static/netbsd/man3/fgetln.3 create mode 100644 static/netbsd/man3/fgets.3 create mode 100644 static/netbsd/man3/fgetwln.3 create mode 100644 static/netbsd/man3/fgetws.3 create mode 100644 static/netbsd/man3/fido_assert_allow_cred.3 create mode 100644 static/netbsd/man3/fido_assert_new.3 create mode 100644 static/netbsd/man3/fido_assert_set_authdata.3 create mode 100644 static/netbsd/man3/fido_assert_verify.3 create mode 100644 static/netbsd/man3/fido_bio_dev_get_info.3 create mode 100644 static/netbsd/man3/fido_bio_enroll_new.3 create mode 100644 static/netbsd/man3/fido_bio_info_new.3 create mode 100644 static/netbsd/man3/fido_bio_template.3 create mode 100644 static/netbsd/man3/fido_cbor_info_new.3 create mode 100644 static/netbsd/man3/fido_cred_exclude.3 create mode 100644 static/netbsd/man3/fido_cred_new.3 create mode 100644 static/netbsd/man3/fido_cred_set_authdata.3 create mode 100644 static/netbsd/man3/fido_cred_verify.3 create mode 100644 static/netbsd/man3/fido_credman_metadata_new.3 create mode 100644 static/netbsd/man3/fido_dev_enable_entattest.3 create mode 100644 static/netbsd/man3/fido_dev_get_assert.3 create mode 100644 static/netbsd/man3/fido_dev_get_touch_begin.3 create mode 100644 static/netbsd/man3/fido_dev_info_manifest.3 create mode 100644 static/netbsd/man3/fido_dev_largeblob_get.3 create mode 100644 static/netbsd/man3/fido_dev_make_cred.3 create mode 100644 static/netbsd/man3/fido_dev_open.3 create mode 100644 static/netbsd/man3/fido_dev_set_io_functions.3 create mode 100644 static/netbsd/man3/fido_dev_set_pin.3 create mode 100644 static/netbsd/man3/fido_init.3 create mode 100644 static/netbsd/man3/fido_strerr.3 create mode 100644 static/netbsd/man3/finite.3 create mode 100644 static/netbsd/man3/flockfile.3 create mode 100644 static/netbsd/man3/fma.3 create mode 100644 static/netbsd/man3/fmax.3 create mode 100644 static/netbsd/man3/fmemopen.3 create mode 100644 static/netbsd/man3/fmod.3 create mode 100644 static/netbsd/man3/fmtcheck.3 create mode 100644 static/netbsd/man3/fmtmsg.3 create mode 100644 static/netbsd/man3/fnmatch.3 create mode 100644 static/netbsd/man3/fopen.3 create mode 100644 static/netbsd/man3/form_cursor.3 create mode 100644 static/netbsd/man3/form_data.3 create mode 100644 static/netbsd/man3/form_driver.3 create mode 100644 static/netbsd/man3/form_field.3 create mode 100644 static/netbsd/man3/form_field_attributes.3 create mode 100644 static/netbsd/man3/form_field_buffer.3 create mode 100644 static/netbsd/man3/form_field_info.3 create mode 100644 static/netbsd/man3/form_field_just.3 create mode 100644 static/netbsd/man3/form_field_new.3 create mode 100644 static/netbsd/man3/form_field_opts.3 create mode 100644 static/netbsd/man3/form_field_userptr.3 create mode 100644 static/netbsd/man3/form_field_validation.3 create mode 100644 static/netbsd/man3/form_fieldtype.3 create mode 100644 static/netbsd/man3/form_hook.3 create mode 100644 static/netbsd/man3/form_new.3 create mode 100644 static/netbsd/man3/form_new_page.3 create mode 100644 static/netbsd/man3/form_opts.3 create mode 100644 static/netbsd/man3/form_page.3 create mode 100644 static/netbsd/man3/form_post.3 create mode 100644 static/netbsd/man3/form_userptr.3 create mode 100644 static/netbsd/man3/form_win.3 create mode 100644 static/netbsd/man3/forms.3 create mode 100644 static/netbsd/man3/fparseln.3 create mode 100644 static/netbsd/man3/fpclassify.3 create mode 100644 static/netbsd/man3/fpgetmask.3 create mode 100644 static/netbsd/man3/fputs.3 create mode 100644 static/netbsd/man3/fputws.3 create mode 100644 static/netbsd/man3/fread.3 create mode 100644 static/netbsd/man3/freelocale.3 create mode 100644 static/netbsd/man3/frexp.3 create mode 100644 static/netbsd/man3/fseek.3 create mode 100644 static/netbsd/man3/fstab.nfs.3 create mode 100644 static/netbsd/man3/fstab.wd0.3 create mode 100644 static/netbsd/man3/ftime.3 create mode 100644 static/netbsd/man3/ftok.3 create mode 100644 static/netbsd/man3/fts.3 create mode 100644 static/netbsd/man3/ftw.3 create mode 100644 static/netbsd/man3/funopen.3 create mode 100644 static/netbsd/man3/fwide.3 create mode 100644 static/netbsd/man3/gai_strerror.3 create mode 100644 static/netbsd/man3/gelf.3 create mode 100644 static/netbsd/man3/gelf_checksum.3 create mode 100644 static/netbsd/man3/gelf_fsize.3 create mode 100644 static/netbsd/man3/gelf_getcap.3 create mode 100644 static/netbsd/man3/gelf_getclass.3 create mode 100644 static/netbsd/man3/gelf_getdyn.3 create mode 100644 static/netbsd/man3/gelf_getehdr.3 create mode 100644 static/netbsd/man3/gelf_getmove.3 create mode 100644 static/netbsd/man3/gelf_getphdr.3 create mode 100644 static/netbsd/man3/gelf_getrel.3 create mode 100644 static/netbsd/man3/gelf_getrela.3 create mode 100644 static/netbsd/man3/gelf_getshdr.3 create mode 100644 static/netbsd/man3/gelf_getsym.3 create mode 100644 static/netbsd/man3/gelf_getsyminfo.3 create mode 100644 static/netbsd/man3/gelf_getsymshndx.3 create mode 100644 static/netbsd/man3/gelf_newehdr.3 create mode 100644 static/netbsd/man3/gelf_newphdr.3 create mode 100644 static/netbsd/man3/gelf_update_ehdr.3 create mode 100644 static/netbsd/man3/gelf_xlatetof.3 create mode 100644 static/netbsd/man3/getaddrinfo.3 create mode 100644 static/netbsd/man3/getarg.3 create mode 100644 static/netbsd/man3/getbootfile.3 create mode 100644 static/netbsd/man3/getbsize.3 create mode 100644 static/netbsd/man3/getbyteorder.3 create mode 100644 static/netbsd/man3/getc.3 create mode 100644 static/netbsd/man3/getcwd.3 create mode 100644 static/netbsd/man3/getdate.3 create mode 100644 static/netbsd/man3/getdelim.3 create mode 100644 static/netbsd/man3/getdevmajor.3 create mode 100644 static/netbsd/man3/getdirentries.3 create mode 100644 static/netbsd/man3/getdiskbyname.3 create mode 100644 static/netbsd/man3/getdiskrawname.3 create mode 100644 static/netbsd/man3/getdomainname.3 create mode 100644 static/netbsd/man3/getdtablesize.3 create mode 100644 static/netbsd/man3/getentropy.3 create mode 100644 static/netbsd/man3/getenv.3 create mode 100644 static/netbsd/man3/getfsent.3 create mode 100644 static/netbsd/man3/getfsspecname.3 create mode 100644 static/netbsd/man3/getfstypename.3 create mode 100644 static/netbsd/man3/getgrent.3 create mode 100644 static/netbsd/man3/getgrouplist.3 create mode 100644 static/netbsd/man3/gethostbyname.3 create mode 100644 static/netbsd/man3/gethostid.3 create mode 100644 static/netbsd/man3/gethostname.3 create mode 100644 static/netbsd/man3/getifaddrs.3 create mode 100644 static/netbsd/man3/getipnodebyname.3 create mode 100644 static/netbsd/man3/getlabelsector.3 create mode 100644 static/netbsd/man3/getlastlogx.3 create mode 100644 static/netbsd/man3/getloadavg.3 create mode 100644 static/netbsd/man3/getmaxpartitions.3 create mode 100644 static/netbsd/man3/getmntinfo.3 create mode 100644 static/netbsd/man3/getmntopts.3 create mode 100644 static/netbsd/man3/getnameinfo.3 create mode 100644 static/netbsd/man3/getnetconfig.3 create mode 100644 static/netbsd/man3/getnetent.3 create mode 100644 static/netbsd/man3/getnetgrent.3 create mode 100644 static/netbsd/man3/getnetpath.3 create mode 100644 static/netbsd/man3/getopt.3 create mode 100644 static/netbsd/man3/getopt_long.3 create mode 100644 static/netbsd/man3/getpagesize.3 create mode 100644 static/netbsd/man3/getpass.3 create mode 100644 static/netbsd/man3/getpeereid.3 create mode 100644 static/netbsd/man3/getprogname.3 create mode 100644 static/netbsd/man3/getprotoent.3 create mode 100644 static/netbsd/man3/getpwent.3 create mode 100644 static/netbsd/man3/getrawpartition.3 create mode 100644 static/netbsd/man3/getrpcent.3 create mode 100644 static/netbsd/man3/getrpcport.3 create mode 100644 static/netbsd/man3/getservent.3 create mode 100644 static/netbsd/man3/getsubopt.3 create mode 100644 static/netbsd/man3/gettext.3 create mode 100644 static/netbsd/man3/getttyent.3 create mode 100644 static/netbsd/man3/getusershell.3 create mode 100644 static/netbsd/man3/getwc.3 create mode 100644 static/netbsd/man3/glob.3 create mode 100644 static/netbsd/man3/grantpt.3 create mode 100644 static/netbsd/man3/gss_acquire_cred.3 create mode 100644 static/netbsd/man3/gss_add_oid_set_member.3 create mode 100644 static/netbsd/man3/gss_canonicalize_name.3 create mode 100644 static/netbsd/man3/gss_display_status.3 create mode 100644 static/netbsd/man3/gss_export_name.3 create mode 100644 static/netbsd/man3/gss_import_name.3 create mode 100644 static/netbsd/man3/gss_init_sec_context.3 create mode 100644 static/netbsd/man3/gss_inquire_attrs_for_mech.3 create mode 100644 static/netbsd/man3/gss_inquire_saslname_for_mech.3 create mode 100644 static/netbsd/man3/gss_oid_equal.3 create mode 100644 static/netbsd/man3/gss_release_cred.3 create mode 100644 static/netbsd/man3/gss_release_iov_buffer.3 create mode 100644 static/netbsd/man3/gss_release_name.3 create mode 100644 static/netbsd/man3/gss_unwrap_iov.3 create mode 100644 static/netbsd/man3/gss_wrap.3 create mode 100644 static/netbsd/man3/gss_wrap_iov.3 create mode 100644 static/netbsd/man3/gss_wrap_iov_length.3 create mode 100644 static/netbsd/man3/gssapi.3 create mode 100644 static/netbsd/man3/gssapi_mechs_intro.3 create mode 100644 static/netbsd/man3/gssapi_services_intro.3 create mode 100644 static/netbsd/man3/hash.3 create mode 100644 static/netbsd/man3/hcreate.3 create mode 100644 static/netbsd/man3/hcrypto_core.3 create mode 100644 static/netbsd/man3/hcrypto_des.3 create mode 100644 static/netbsd/man3/hcrypto_dh.3 create mode 100644 static/netbsd/man3/hcrypto_evp.3 create mode 100644 static/netbsd/man3/hcrypto_misc.3 create mode 100644 static/netbsd/man3/hcrypto_rand.3 create mode 100644 static/netbsd/man3/hcrypto_rsa.3 create mode 100644 static/netbsd/man3/hdb__del.3 create mode 100644 static/netbsd/man3/hdb__get.3 create mode 100644 static/netbsd/man3/hdb__put.3 create mode 100644 static/netbsd/man3/hdb_auth_status.3 create mode 100644 static/netbsd/man3/hdb_check_constrained_delegation.3 create mode 100644 static/netbsd/man3/hdb_check_pkinit_ms_upn_match.3 create mode 100644 static/netbsd/man3/hdb_check_s4u2self.3 create mode 100644 static/netbsd/man3/hdb_close.3 create mode 100644 static/netbsd/man3/hdb_destroy.3 create mode 100644 static/netbsd/man3/hdb_entry_ex.3 create mode 100644 static/netbsd/man3/hdb_fetch_kvno.3 create mode 100644 static/netbsd/man3/hdb_firstkey.3 create mode 100644 static/netbsd/man3/hdb_free.3 create mode 100644 static/netbsd/man3/hdb_get_realms.3 create mode 100644 static/netbsd/man3/hdb_lock.3 create mode 100644 static/netbsd/man3/hdb_name.3 create mode 100644 static/netbsd/man3/hdb_nextkey.3 create mode 100644 static/netbsd/man3/hdb_open.3 create mode 100644 static/netbsd/man3/hdb_password.3 create mode 100644 static/netbsd/man3/hdb_remove.3 create mode 100644 static/netbsd/man3/hdb_rename.3 create mode 100644 static/netbsd/man3/hdb_set_sync.3 create mode 100644 static/netbsd/man3/hdb_store.3 create mode 100644 static/netbsd/man3/hdb_unlock.3 create mode 100644 static/netbsd/man3/heim_ntlm_build_ntlm1_master.3 create mode 100644 static/netbsd/man3/heim_ntlm_build_ntlm2_master.3 create mode 100644 static/netbsd/man3/heim_ntlm_calculate_lm2.3 create mode 100644 static/netbsd/man3/heim_ntlm_calculate_ntlm1.3 create mode 100644 static/netbsd/man3/heim_ntlm_calculate_ntlm2.3 create mode 100644 static/netbsd/man3/heim_ntlm_decode_targetinfo.3 create mode 100644 static/netbsd/man3/heim_ntlm_encode_targetinfo.3 create mode 100644 static/netbsd/man3/heim_ntlm_encode_type1.3 create mode 100644 static/netbsd/man3/heim_ntlm_encode_type2.3 create mode 100644 static/netbsd/man3/heim_ntlm_encode_type3.3 create mode 100644 static/netbsd/man3/heim_ntlm_free_buf.3 create mode 100644 static/netbsd/man3/heim_ntlm_free_targetinfo.3 create mode 100644 static/netbsd/man3/heim_ntlm_free_type1.3 create mode 100644 static/netbsd/man3/heim_ntlm_free_type2.3 create mode 100644 static/netbsd/man3/heim_ntlm_free_type3.3 create mode 100644 static/netbsd/man3/heim_ntlm_keyex_unwrap.3 create mode 100644 static/netbsd/man3/heim_ntlm_nt_key.3 create mode 100644 static/netbsd/man3/heim_ntlm_ntlmv2_key.3 create mode 100644 static/netbsd/man3/heim_ntlm_verify_ntlm2.3 create mode 100644 static/netbsd/man3/heimbase.3 create mode 100644 static/netbsd/man3/hesiod.3 create mode 100644 static/netbsd/man3/history.3 create mode 100644 static/netbsd/man3/hosts_access.3 create mode 100644 static/netbsd/man3/http.h.3 create mode 100644 static/netbsd/man3/http_compat.h.3 create mode 100644 static/netbsd/man3/humanize_number.3 create mode 100644 static/netbsd/man3/hx509.3 create mode 100644 static/netbsd/man3/hx509_bitstring_print.3 create mode 100644 static/netbsd/man3/hx509_ca.3 create mode 100644 static/netbsd/man3/hx509_ca_sign.3 create mode 100644 static/netbsd/man3/hx509_ca_sign_self.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_crl_dp_uri.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_eku.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_hostname.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_jid.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_ms_upn.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_otherName.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_pkinit.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_add_san_rfc822name.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_free.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_init.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_ca.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_domaincontroller.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_notAfter.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_notAfter_lifetime.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_notBefore.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_proxy.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_serialnumber.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_signature_algorithm.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_spki.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_subject.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_template.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_set_unique.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_subject_expand.3 create mode 100644 static/netbsd/man3/hx509_ca_tbs_template_units.3 create mode 100644 static/netbsd/man3/hx509_cert.3 create mode 100644 static/netbsd/man3/hx509_cert_binary.3 create mode 100644 static/netbsd/man3/hx509_cert_check_eku.3 create mode 100644 static/netbsd/man3/hx509_cert_cmp.3 create mode 100644 static/netbsd/man3/hx509_cert_find_subjectAltName_otherName.3 create mode 100644 static/netbsd/man3/hx509_cert_free.3 create mode 100644 static/netbsd/man3/hx509_cert_get_SPKI.3 create mode 100644 static/netbsd/man3/hx509_cert_get_SPKI_AlgorithmIdentifier.3 create mode 100644 static/netbsd/man3/hx509_cert_get_attribute.3 create mode 100644 static/netbsd/man3/hx509_cert_get_base_subject.3 create mode 100644 static/netbsd/man3/hx509_cert_get_friendly_name.3 create mode 100644 static/netbsd/man3/hx509_cert_get_issuer.3 create mode 100644 static/netbsd/man3/hx509_cert_get_issuer_unique_id.3 create mode 100644 static/netbsd/man3/hx509_cert_get_notAfter.3 create mode 100644 static/netbsd/man3/hx509_cert_get_notBefore.3 create mode 100644 static/netbsd/man3/hx509_cert_get_serialnumber.3 create mode 100644 static/netbsd/man3/hx509_cert_get_subject.3 create mode 100644 static/netbsd/man3/hx509_cert_get_subject_unique_id.3 create mode 100644 static/netbsd/man3/hx509_cert_init.3 create mode 100644 static/netbsd/man3/hx509_cert_init_data.3 create mode 100644 static/netbsd/man3/hx509_cert_keyusage_print.3 create mode 100644 static/netbsd/man3/hx509_cert_ref.3 create mode 100644 static/netbsd/man3/hx509_cert_set_friendly_name.3 create mode 100644 static/netbsd/man3/hx509_certs_add.3 create mode 100644 static/netbsd/man3/hx509_certs_append.3 create mode 100644 static/netbsd/man3/hx509_certs_end_seq.3 create mode 100644 static/netbsd/man3/hx509_certs_filter.3 create mode 100644 static/netbsd/man3/hx509_certs_find.3 create mode 100644 static/netbsd/man3/hx509_certs_free.3 create mode 100644 static/netbsd/man3/hx509_certs_info.3 create mode 100644 static/netbsd/man3/hx509_certs_init.3 create mode 100644 static/netbsd/man3/hx509_certs_iter_f.3 create mode 100644 static/netbsd/man3/hx509_certs_merge.3 create mode 100644 static/netbsd/man3/hx509_certs_next_cert.3 create mode 100644 static/netbsd/man3/hx509_certs_start_seq.3 create mode 100644 static/netbsd/man3/hx509_certs_store.3 create mode 100644 static/netbsd/man3/hx509_ci_print_names.3 create mode 100644 static/netbsd/man3/hx509_clear_error_string.3 create mode 100644 static/netbsd/man3/hx509_cms.3 create mode 100644 static/netbsd/man3/hx509_cms_create_signed_1.3 create mode 100644 static/netbsd/man3/hx509_cms_envelope_1.3 create mode 100644 static/netbsd/man3/hx509_cms_unenvelope.3 create mode 100644 static/netbsd/man3/hx509_cms_unwrap_ContentInfo.3 create mode 100644 static/netbsd/man3/hx509_cms_verify_signed.3 create mode 100644 static/netbsd/man3/hx509_cms_wrap_ContentInfo.3 create mode 100644 static/netbsd/man3/hx509_context_free.3 create mode 100644 static/netbsd/man3/hx509_context_init.3 create mode 100644 static/netbsd/man3/hx509_context_set_missing_revoke.3 create mode 100644 static/netbsd/man3/hx509_crl_add_revoked_certs.3 create mode 100644 static/netbsd/man3/hx509_crl_alloc.3 create mode 100644 static/netbsd/man3/hx509_crl_free.3 create mode 100644 static/netbsd/man3/hx509_crl_lifetime.3 create mode 100644 static/netbsd/man3/hx509_crl_sign.3 create mode 100644 static/netbsd/man3/hx509_crypto.3 create mode 100644 static/netbsd/man3/hx509_env.3 create mode 100644 static/netbsd/man3/hx509_env_add.3 create mode 100644 static/netbsd/man3/hx509_env_add_binding.3 create mode 100644 static/netbsd/man3/hx509_env_find.3 create mode 100644 static/netbsd/man3/hx509_env_find_binding.3 create mode 100644 static/netbsd/man3/hx509_env_free.3 create mode 100644 static/netbsd/man3/hx509_env_lfind.3 create mode 100644 static/netbsd/man3/hx509_err.3 create mode 100644 static/netbsd/man3/hx509_error.3 create mode 100644 static/netbsd/man3/hx509_free_error_string.3 create mode 100644 static/netbsd/man3/hx509_free_octet_string_list.3 create mode 100644 static/netbsd/man3/hx509_general_name_unparse.3 create mode 100644 static/netbsd/man3/hx509_get_error_string.3 create mode 100644 static/netbsd/man3/hx509_get_one_cert.3 create mode 100644 static/netbsd/man3/hx509_keyset.3 create mode 100644 static/netbsd/man3/hx509_lock.3 create mode 100644 static/netbsd/man3/hx509_misc.3 create mode 100644 static/netbsd/man3/hx509_name.3 create mode 100644 static/netbsd/man3/hx509_name_binary.3 create mode 100644 static/netbsd/man3/hx509_name_cmp.3 create mode 100644 static/netbsd/man3/hx509_name_copy.3 create mode 100644 static/netbsd/man3/hx509_name_expand.3 create mode 100644 static/netbsd/man3/hx509_name_free.3 create mode 100644 static/netbsd/man3/hx509_name_is_null_p.3 create mode 100644 static/netbsd/man3/hx509_name_to_Name.3 create mode 100644 static/netbsd/man3/hx509_name_to_string.3 create mode 100644 static/netbsd/man3/hx509_ocsp_request.3 create mode 100644 static/netbsd/man3/hx509_ocsp_verify.3 create mode 100644 static/netbsd/man3/hx509_oid_print.3 create mode 100644 static/netbsd/man3/hx509_oid_sprint.3 create mode 100644 static/netbsd/man3/hx509_parse_name.3 create mode 100644 static/netbsd/man3/hx509_peer.3 create mode 100644 static/netbsd/man3/hx509_peer_info_add_cms_alg.3 create mode 100644 static/netbsd/man3/hx509_peer_info_alloc.3 create mode 100644 static/netbsd/man3/hx509_peer_info_free.3 create mode 100644 static/netbsd/man3/hx509_peer_info_set_cert.3 create mode 100644 static/netbsd/man3/hx509_peer_info_set_cms_algs.3 create mode 100644 static/netbsd/man3/hx509_print.3 create mode 100644 static/netbsd/man3/hx509_print_cert.3 create mode 100644 static/netbsd/man3/hx509_print_stdout.3 create mode 100644 static/netbsd/man3/hx509_query.3 create mode 100644 static/netbsd/man3/hx509_query_alloc.3 create mode 100644 static/netbsd/man3/hx509_query_free.3 create mode 100644 static/netbsd/man3/hx509_query_match_cmp_func.3 create mode 100644 static/netbsd/man3/hx509_query_match_eku.3 create mode 100644 static/netbsd/man3/hx509_query_match_friendly_name.3 create mode 100644 static/netbsd/man3/hx509_query_match_issuer_serial.3 create mode 100644 static/netbsd/man3/hx509_query_match_option.3 create mode 100644 static/netbsd/man3/hx509_query_statistic_file.3 create mode 100644 static/netbsd/man3/hx509_query_unparse_stats.3 create mode 100644 static/netbsd/man3/hx509_revoke.3 create mode 100644 static/netbsd/man3/hx509_revoke_add_crl.3 create mode 100644 static/netbsd/man3/hx509_revoke_add_ocsp.3 create mode 100644 static/netbsd/man3/hx509_revoke_free.3 create mode 100644 static/netbsd/man3/hx509_revoke_init.3 create mode 100644 static/netbsd/man3/hx509_revoke_ocsp_print.3 create mode 100644 static/netbsd/man3/hx509_revoke_verify.3 create mode 100644 static/netbsd/man3/hx509_set_error_string.3 create mode 100644 static/netbsd/man3/hx509_set_error_stringv.3 create mode 100644 static/netbsd/man3/hx509_unparse_der_name.3 create mode 100644 static/netbsd/man3/hx509_validate_cert.3 create mode 100644 static/netbsd/man3/hx509_validate_ctx_add_flags.3 create mode 100644 static/netbsd/man3/hx509_validate_ctx_free.3 create mode 100644 static/netbsd/man3/hx509_validate_ctx_init.3 create mode 100644 static/netbsd/man3/hx509_validate_ctx_set_print.3 create mode 100644 static/netbsd/man3/hx509_verify.3 create mode 100644 static/netbsd/man3/hx509_verify_attach_anchors.3 create mode 100644 static/netbsd/man3/hx509_verify_attach_revoke.3 create mode 100644 static/netbsd/man3/hx509_verify_ctx_f_allow_default_trustanchors.3 create mode 100644 static/netbsd/man3/hx509_verify_destroy_ctx.3 create mode 100644 static/netbsd/man3/hx509_verify_hostname.3 create mode 100644 static/netbsd/man3/hx509_verify_init_ctx.3 create mode 100644 static/netbsd/man3/hx509_verify_path.3 create mode 100644 static/netbsd/man3/hx509_verify_set_max_depth.3 create mode 100644 static/netbsd/man3/hx509_verify_set_proxy_certificate.3 create mode 100644 static/netbsd/man3/hx509_verify_set_strict_rfc3280_verification.3 create mode 100644 static/netbsd/man3/hx509_verify_set_time.3 create mode 100644 static/netbsd/man3/hx509_verify_signature.3 create mode 100644 static/netbsd/man3/hx509_xfree.3 create mode 100644 static/netbsd/man3/hypot.3 create mode 100644 static/netbsd/man3/i2d_CMS_bio_stream.3 create mode 100644 static/netbsd/man3/i2d_PKCS7_bio_stream.3 create mode 100644 static/netbsd/man3/i2d_re_X509_tbs.3 create mode 100644 static/netbsd/man3/iconv.3 create mode 100644 static/netbsd/man3/ieee_test.3 create mode 100644 static/netbsd/man3/if_indextoname.3 create mode 100644 static/netbsd/man3/ilogb.3 create mode 100644 static/netbsd/man3/include.include.withclauses.3 create mode 100644 static/netbsd/man3/include.include.withoutclauses.3 create mode 100644 static/netbsd/man3/include.includetop.withclauses.3 create mode 100644 static/netbsd/man3/include.includetop.withoutclauses.3 create mode 100644 static/netbsd/man3/include.withclauses.3 create mode 100644 static/netbsd/man3/include.withoutclauses.3 create mode 100644 static/netbsd/man3/include.withsomeclauses.3 create mode 100644 static/netbsd/man3/index.3 create mode 100644 static/netbsd/man3/inet.3 create mode 100644 static/netbsd/man3/inet6_getscopeid.3 create mode 100644 static/netbsd/man3/inet6_opt_init.3 create mode 100644 static/netbsd/man3/inet6_option_space.3 create mode 100644 static/netbsd/man3/inet6_rth_space.3 create mode 100644 static/netbsd/man3/inet6_rthdr_space.3 create mode 100644 static/netbsd/man3/inet_cidr.3 create mode 100644 static/netbsd/man3/inet_net.3 create mode 100644 static/netbsd/man3/init_db.3 create mode 100644 static/netbsd/man3/initgroups.3 create mode 100644 static/netbsd/man3/insque.3 create mode 100644 static/netbsd/man3/internal_v_smechname.3 create mode 100644 static/netbsd/man3/ipsec_set_policy.3 create mode 100644 static/netbsd/man3/ipsec_strerror.3 create mode 100644 static/netbsd/man3/ipv6.3 create mode 100644 static/netbsd/man3/isalnum.3 create mode 100644 static/netbsd/man3/isalpha.3 create mode 100644 static/netbsd/man3/isascii.3 create mode 100644 static/netbsd/man3/isblank.3 create mode 100644 static/netbsd/man3/iscntrl.3 create mode 100644 static/netbsd/man3/isdigit.3 create mode 100644 static/netbsd/man3/isfinite.3 create mode 100644 static/netbsd/man3/isgraph.3 create mode 100644 static/netbsd/man3/isgreater.3 create mode 100644 static/netbsd/man3/isinf.3 create mode 100644 static/netbsd/man3/isinff.3 create mode 100644 static/netbsd/man3/islower.3 create mode 100644 static/netbsd/man3/isnan.3 create mode 100644 static/netbsd/man3/isnormal.3 create mode 100644 static/netbsd/man3/isns.3 create mode 100644 static/netbsd/man3/isprint.3 create mode 100644 static/netbsd/man3/ispunct.3 create mode 100644 static/netbsd/man3/isspace.3 create mode 100644 static/netbsd/man3/isupper.3 create mode 100644 static/netbsd/man3/iswalnum.3 create mode 100644 static/netbsd/man3/iswctype.3 create mode 100644 static/netbsd/man3/isxdigit.3 create mode 100644 static/netbsd/man3/j0.3 create mode 100644 static/netbsd/man3/jemalloc.3 create mode 100644 static/netbsd/man3/kadm5_pwcheck.3 create mode 100644 static/netbsd/man3/kafs.3 create mode 100644 static/netbsd/man3/keccak.3 create mode 100644 static/netbsd/man3/killpg.3 create mode 100644 static/netbsd/man3/kinfo_getvmmap.3 create mode 100644 static/netbsd/man3/krb5.3 create mode 100644 static/netbsd/man3/krb524_convert_creds_kdc.3 create mode 100644 static/netbsd/man3/krb524_convert_creds_kdc_ccache.3 create mode 100644 static/netbsd/man3/krb5_425_conv_principal.3 create mode 100644 static/netbsd/man3/krb5_abort.3 create mode 100644 static/netbsd/man3/krb5_abortx.3 create mode 100644 static/netbsd/man3/krb5_acc_ops.3 create mode 100644 static/netbsd/man3/krb5_acl_match_file.3 create mode 100644 static/netbsd/man3/krb5_acl_match_string.3 create mode 100644 static/netbsd/man3/krb5_add_et_list.3 create mode 100644 static/netbsd/man3/krb5_add_extra_addresses.3 create mode 100644 static/netbsd/man3/krb5_add_ignore_addresses.3 create mode 100644 static/netbsd/man3/krb5_addr2sockaddr.3 create mode 100644 static/netbsd/man3/krb5_address.3 create mode 100644 static/netbsd/man3/krb5_address_compare.3 create mode 100644 static/netbsd/man3/krb5_address_order.3 create mode 100644 static/netbsd/man3/krb5_address_prefixlen_boundary.3 create mode 100644 static/netbsd/man3/krb5_address_search.3 create mode 100644 static/netbsd/man3/krb5_allow_weak_crypto.3 create mode 100644 static/netbsd/man3/krb5_aname_to_localname.3 create mode 100644 static/netbsd/man3/krb5_anyaddr.3 create mode 100644 static/netbsd/man3/krb5_appdefault.3 create mode 100644 static/netbsd/man3/krb5_append_addresses.3 create mode 100644 static/netbsd/man3/krb5_auth.3 create mode 100644 static/netbsd/man3/krb5_auth_context.3 create mode 100644 static/netbsd/man3/krb5_auth_getremoteseqnumber.3 create mode 100644 static/netbsd/man3/krb5_build_principal.3 create mode 100644 static/netbsd/man3/krb5_c_enctype_compare.3 create mode 100644 static/netbsd/man3/krb5_c_make_checksum.3 create mode 100644 static/netbsd/man3/krb5_cc_cache_end_seq_get.3 create mode 100644 static/netbsd/man3/krb5_cc_cache_get_first.3 create mode 100644 static/netbsd/man3/krb5_cc_cache_match.3 create mode 100644 static/netbsd/man3/krb5_cc_cache_next.3 create mode 100644 static/netbsd/man3/krb5_cc_clear_mcred.3 create mode 100644 static/netbsd/man3/krb5_cc_close.3 create mode 100644 static/netbsd/man3/krb5_cc_copy_cache.3 create mode 100644 static/netbsd/man3/krb5_cc_copy_creds.3 create mode 100644 static/netbsd/man3/krb5_cc_copy_match_f.3 create mode 100644 static/netbsd/man3/krb5_cc_default.3 create mode 100644 static/netbsd/man3/krb5_cc_default_name.3 create mode 100644 static/netbsd/man3/krb5_cc_destroy.3 create mode 100644 static/netbsd/man3/krb5_cc_end_seq_get.3 create mode 100644 static/netbsd/man3/krb5_cc_gen_new.3 create mode 100644 static/netbsd/man3/krb5_cc_get_config.3 create mode 100644 static/netbsd/man3/krb5_cc_get_flags.3 create mode 100644 static/netbsd/man3/krb5_cc_get_friendly_name.3 create mode 100644 static/netbsd/man3/krb5_cc_get_full_name.3 create mode 100644 static/netbsd/man3/krb5_cc_get_kdc_offset.3 create mode 100644 static/netbsd/man3/krb5_cc_get_lifetime.3 create mode 100644 static/netbsd/man3/krb5_cc_get_name.3 create mode 100644 static/netbsd/man3/krb5_cc_get_ops.3 create mode 100644 static/netbsd/man3/krb5_cc_get_prefix_ops.3 create mode 100644 static/netbsd/man3/krb5_cc_get_principal.3 create mode 100644 static/netbsd/man3/krb5_cc_get_type.3 create mode 100644 static/netbsd/man3/krb5_cc_get_version.3 create mode 100644 static/netbsd/man3/krb5_cc_initialize.3 create mode 100644 static/netbsd/man3/krb5_cc_last_change_time.3 create mode 100644 static/netbsd/man3/krb5_cc_move.3 create mode 100644 static/netbsd/man3/krb5_cc_new_unique.3 create mode 100644 static/netbsd/man3/krb5_cc_next_cred.3 create mode 100644 static/netbsd/man3/krb5_cc_register.3 create mode 100644 static/netbsd/man3/krb5_cc_remove_cred.3 create mode 100644 static/netbsd/man3/krb5_cc_resolve.3 create mode 100644 static/netbsd/man3/krb5_cc_retrieve_cred.3 create mode 100644 static/netbsd/man3/krb5_cc_set_config.3 create mode 100644 static/netbsd/man3/krb5_cc_set_default_name.3 create mode 100644 static/netbsd/man3/krb5_cc_set_flags.3 create mode 100644 static/netbsd/man3/krb5_cc_set_friendly_name.3 create mode 100644 static/netbsd/man3/krb5_cc_set_kdc_offset.3 create mode 100644 static/netbsd/man3/krb5_cc_start_seq_get.3 create mode 100644 static/netbsd/man3/krb5_cc_store_cred.3 create mode 100644 static/netbsd/man3/krb5_cc_support_switch.3 create mode 100644 static/netbsd/man3/krb5_cc_switch.3 create mode 100644 static/netbsd/man3/krb5_ccache.3 create mode 100644 static/netbsd/man3/krb5_ccache_intro.3 create mode 100644 static/netbsd/man3/krb5_cccol_cursor_free.3 create mode 100644 static/netbsd/man3/krb5_cccol_cursor_new.3 create mode 100644 static/netbsd/man3/krb5_cccol_cursor_next.3 create mode 100644 static/netbsd/man3/krb5_cccol_last_change_time.3 create mode 100644 static/netbsd/man3/krb5_change_password.3 create mode 100644 static/netbsd/man3/krb5_check_transited.3 create mode 100644 static/netbsd/man3/krb5_cksumtype_to_enctype.3 create mode 100644 static/netbsd/man3/krb5_clear_error_message.3 create mode 100644 static/netbsd/man3/krb5_clear_error_string.3 create mode 100644 static/netbsd/man3/krb5_compare_creds.3 create mode 100644 static/netbsd/man3/krb5_config_file_free.3 create mode 100644 static/netbsd/man3/krb5_config_free_strings.3 create mode 100644 static/netbsd/man3/krb5_config_get_bool.3 create mode 100644 static/netbsd/man3/krb5_config_get_bool_default.3 create mode 100644 static/netbsd/man3/krb5_config_get_list.3 create mode 100644 static/netbsd/man3/krb5_config_get_string.3 create mode 100644 static/netbsd/man3/krb5_config_get_string_default.3 create mode 100644 static/netbsd/man3/krb5_config_get_strings.3 create mode 100644 static/netbsd/man3/krb5_config_get_time.3 create mode 100644 static/netbsd/man3/krb5_config_get_time_default.3 create mode 100644 static/netbsd/man3/krb5_config_parse_file_multi.3 create mode 100644 static/netbsd/man3/krb5_config_parse_string_multi.3 create mode 100644 static/netbsd/man3/krb5_config_vget_bool.3 create mode 100644 static/netbsd/man3/krb5_config_vget_bool_default.3 create mode 100644 static/netbsd/man3/krb5_config_vget_list.3 create mode 100644 static/netbsd/man3/krb5_config_vget_string.3 create mode 100644 static/netbsd/man3/krb5_config_vget_string_default.3 create mode 100644 static/netbsd/man3/krb5_config_vget_strings.3 create mode 100644 static/netbsd/man3/krb5_config_vget_time.3 create mode 100644 static/netbsd/man3/krb5_config_vget_time_default.3 create mode 100644 static/netbsd/man3/krb5_copy_address.3 create mode 100644 static/netbsd/man3/krb5_copy_addresses.3 create mode 100644 static/netbsd/man3/krb5_copy_context.3 create mode 100644 static/netbsd/man3/krb5_copy_creds.3 create mode 100644 static/netbsd/man3/krb5_copy_creds_contents.3 create mode 100644 static/netbsd/man3/krb5_copy_data.3 create mode 100644 static/netbsd/man3/krb5_copy_host_realm.3 create mode 100644 static/netbsd/man3/krb5_copy_keyblock.3 create mode 100644 static/netbsd/man3/krb5_copy_keyblock_contents.3 create mode 100644 static/netbsd/man3/krb5_copy_principal.3 create mode 100644 static/netbsd/man3/krb5_copy_ticket.3 create mode 100644 static/netbsd/man3/krb5_create_checksum.3 create mode 100644 static/netbsd/man3/krb5_create_checksum_iov.3 create mode 100644 static/netbsd/man3/krb5_credential.3 create mode 100644 static/netbsd/man3/krb5_creds.3 create mode 100644 static/netbsd/man3/krb5_creds_get_ticket_flags.3 create mode 100644 static/netbsd/man3/krb5_crypto.3 create mode 100644 static/netbsd/man3/krb5_crypto_destroy.3 create mode 100644 static/netbsd/man3/krb5_crypto_fx_cf2.3 create mode 100644 static/netbsd/man3/krb5_crypto_getblocksize.3 create mode 100644 static/netbsd/man3/krb5_crypto_getconfoundersize.3 create mode 100644 static/netbsd/man3/krb5_crypto_getenctype.3 create mode 100644 static/netbsd/man3/krb5_crypto_getpadsize.3 create mode 100644 static/netbsd/man3/krb5_crypto_init.3 create mode 100644 static/netbsd/man3/krb5_crypto_iov.3 create mode 100644 static/netbsd/man3/krb5_data_alloc.3 create mode 100644 static/netbsd/man3/krb5_data_cmp.3 create mode 100644 static/netbsd/man3/krb5_data_copy.3 create mode 100644 static/netbsd/man3/krb5_data_ct_cmp.3 create mode 100644 static/netbsd/man3/krb5_data_free.3 create mode 100644 static/netbsd/man3/krb5_data_realloc.3 create mode 100644 static/netbsd/man3/krb5_data_zero.3 create mode 100644 static/netbsd/man3/krb5_dcc_ops.3 create mode 100644 static/netbsd/man3/krb5_decrypt_iov_ivec.3 create mode 100644 static/netbsd/man3/krb5_deprecated.3 create mode 100644 static/netbsd/man3/krb5_digest.3 create mode 100644 static/netbsd/man3/krb5_digest_probe.3 create mode 100644 static/netbsd/man3/krb5_eai_to_heim_errno.3 create mode 100644 static/netbsd/man3/krb5_encrypt.3 create mode 100644 static/netbsd/man3/krb5_encrypt_iov_ivec.3 create mode 100644 static/netbsd/man3/krb5_enctype_disable.3 create mode 100644 static/netbsd/man3/krb5_enctype_enable.3 create mode 100644 static/netbsd/man3/krb5_enctype_valid.3 create mode 100644 static/netbsd/man3/krb5_enctypes_compatible_keys.3 create mode 100644 static/netbsd/man3/krb5_err.3 create mode 100644 static/netbsd/man3/krb5_error.3 create mode 100644 static/netbsd/man3/krb5_errx.3 create mode 100644 static/netbsd/man3/krb5_expand_hostname.3 create mode 100644 static/netbsd/man3/krb5_expand_hostname_realms.3 create mode 100644 static/netbsd/man3/krb5_fcc_ops.3 create mode 100644 static/netbsd/man3/krb5_fileformats.3 create mode 100644 static/netbsd/man3/krb5_find_padata.3 create mode 100644 static/netbsd/man3/krb5_free_address.3 create mode 100644 static/netbsd/man3/krb5_free_addresses.3 create mode 100644 static/netbsd/man3/krb5_free_config_files.3 create mode 100644 static/netbsd/man3/krb5_free_context.3 create mode 100644 static/netbsd/man3/krb5_free_cred_contents.3 create mode 100644 static/netbsd/man3/krb5_free_creds.3 create mode 100644 static/netbsd/man3/krb5_free_creds_contents.3 create mode 100644 static/netbsd/man3/krb5_free_data.3 create mode 100644 static/netbsd/man3/krb5_free_data_contents.3 create mode 100644 static/netbsd/man3/krb5_free_error_message.3 create mode 100644 static/netbsd/man3/krb5_free_error_string.3 create mode 100644 static/netbsd/man3/krb5_free_host_realm.3 create mode 100644 static/netbsd/man3/krb5_free_keyblock.3 create mode 100644 static/netbsd/man3/krb5_free_keyblock_contents.3 create mode 100644 static/netbsd/man3/krb5_free_principal.3 create mode 100644 static/netbsd/man3/krb5_free_ticket.3 create mode 100644 static/netbsd/man3/krb5_free_unparsed_name.3 create mode 100644 static/netbsd/man3/krb5_fwd_tgt_creds.3 create mode 100644 static/netbsd/man3/krb5_generate_random.3 create mode 100644 static/netbsd/man3/krb5_generate_random_block.3 create mode 100644 static/netbsd/man3/krb5_generate_subkey.3 create mode 100644 static/netbsd/man3/krb5_generate_subkey_extended.3 create mode 100644 static/netbsd/man3/krb5_get_all_client_addrs.3 create mode 100644 static/netbsd/man3/krb5_get_cred_from_kdc.3 create mode 100644 static/netbsd/man3/krb5_get_cred_from_kdc_opt.3 create mode 100644 static/netbsd/man3/krb5_get_credentials.3 create mode 100644 static/netbsd/man3/krb5_get_creds.3 create mode 100644 static/netbsd/man3/krb5_get_default_config_files.3 create mode 100644 static/netbsd/man3/krb5_get_default_in_tkt_etypes.3 create mode 100644 static/netbsd/man3/krb5_get_dns_canonicalize_hostname.3 create mode 100644 static/netbsd/man3/krb5_get_err_text.3 create mode 100644 static/netbsd/man3/krb5_get_error_message.3 create mode 100644 static/netbsd/man3/krb5_get_error_string.3 create mode 100644 static/netbsd/man3/krb5_get_extra_addresses.3 create mode 100644 static/netbsd/man3/krb5_get_fcache_version.3 create mode 100644 static/netbsd/man3/krb5_get_forwarded_creds.3 create mode 100644 static/netbsd/man3/krb5_get_ignore_addresses.3 create mode 100644 static/netbsd/man3/krb5_get_in_cred.3 create mode 100644 static/netbsd/man3/krb5_get_in_tkt_with_keytab.3 create mode 100644 static/netbsd/man3/krb5_get_in_tkt_with_password.3 create mode 100644 static/netbsd/man3/krb5_get_in_tkt_with_skey.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_keyblock.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_keytab.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_opt_alloc.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_opt_free.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_opt_get_error.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_opt_init.3 create mode 100644 static/netbsd/man3/krb5_get_init_creds_password.3 create mode 100644 static/netbsd/man3/krb5_get_kdc_sec_offset.3 create mode 100644 static/netbsd/man3/krb5_get_krbhst.3 create mode 100644 static/netbsd/man3/krb5_get_max_time_skew.3 create mode 100644 static/netbsd/man3/krb5_get_use_admin_kdc.3 create mode 100644 static/netbsd/man3/krb5_get_validated_creds.3 create mode 100644 static/netbsd/man3/krb5_get_warn_dest.3 create mode 100644 static/netbsd/man3/krb5_getportbyname.3 create mode 100644 static/netbsd/man3/krb5_h_addr2addr.3 create mode 100644 static/netbsd/man3/krb5_h_addr2sockaddr.3 create mode 100644 static/netbsd/man3/krb5_h_errno_to_heim_errno.3 create mode 100644 static/netbsd/man3/krb5_init_context.3 create mode 100644 static/netbsd/man3/krb5_init_creds_free.3 create mode 100644 static/netbsd/man3/krb5_init_creds_get.3 create mode 100644 static/netbsd/man3/krb5_init_creds_get_error.3 create mode 100644 static/netbsd/man3/krb5_init_creds_init.3 create mode 100644 static/netbsd/man3/krb5_init_creds_intro.3 create mode 100644 static/netbsd/man3/krb5_init_creds_set_keytab.3 create mode 100644 static/netbsd/man3/krb5_init_creds_set_password.3 create mode 100644 static/netbsd/man3/krb5_init_creds_set_service.3 create mode 100644 static/netbsd/man3/krb5_init_creds_step.3 create mode 100644 static/netbsd/man3/krb5_init_ets.3 create mode 100644 static/netbsd/man3/krb5_introduction.3 create mode 100644 static/netbsd/man3/krb5_is_config_principal.3 create mode 100644 static/netbsd/man3/krb5_is_enctype_weak.3 create mode 100644 static/netbsd/man3/krb5_is_thread_safe.3 create mode 100644 static/netbsd/man3/krb5_kerberos_enctypes.3 create mode 100644 static/netbsd/man3/krb5_keyblock_get_enctype.3 create mode 100644 static/netbsd/man3/krb5_keyblock_init.3 create mode 100644 static/netbsd/man3/krb5_keyblock_zero.3 create mode 100644 static/netbsd/man3/krb5_keytab.3 create mode 100644 static/netbsd/man3/krb5_keytab_intro.3 create mode 100644 static/netbsd/man3/krb5_keytab_key_proc.3 create mode 100644 static/netbsd/man3/krb5_keytype_to_enctypes.3 create mode 100644 static/netbsd/man3/krb5_keytype_to_enctypes_default.3 create mode 100644 static/netbsd/man3/krb5_keytype_to_string.3 create mode 100644 static/netbsd/man3/krb5_krbhst_get_addrinfo.3 create mode 100644 static/netbsd/man3/krb5_krbhst_init.3 create mode 100644 static/netbsd/man3/krb5_kt_add_entry.3 create mode 100644 static/netbsd/man3/krb5_kt_close.3 create mode 100644 static/netbsd/man3/krb5_kt_compare.3 create mode 100644 static/netbsd/man3/krb5_kt_copy_entry_contents.3 create mode 100644 static/netbsd/man3/krb5_kt_default.3 create mode 100644 static/netbsd/man3/krb5_kt_default_modify_name.3 create mode 100644 static/netbsd/man3/krb5_kt_default_name.3 create mode 100644 static/netbsd/man3/krb5_kt_destroy.3 create mode 100644 static/netbsd/man3/krb5_kt_end_seq_get.3 create mode 100644 static/netbsd/man3/krb5_kt_free_entry.3 create mode 100644 static/netbsd/man3/krb5_kt_get_entry.3 create mode 100644 static/netbsd/man3/krb5_kt_get_full_name.3 create mode 100644 static/netbsd/man3/krb5_kt_get_name.3 create mode 100644 static/netbsd/man3/krb5_kt_get_type.3 create mode 100644 static/netbsd/man3/krb5_kt_have_content.3 create mode 100644 static/netbsd/man3/krb5_kt_next_entry.3 create mode 100644 static/netbsd/man3/krb5_kt_read_service_key.3 create mode 100644 static/netbsd/man3/krb5_kt_register.3 create mode 100644 static/netbsd/man3/krb5_kt_remove_entry.3 create mode 100644 static/netbsd/man3/krb5_kt_resolve.3 create mode 100644 static/netbsd/man3/krb5_kt_start_seq_get.3 create mode 100644 static/netbsd/man3/krb5_kuserok.3 create mode 100644 static/netbsd/man3/krb5_make_addrport.3 create mode 100644 static/netbsd/man3/krb5_make_principal.3 create mode 100644 static/netbsd/man3/krb5_max_sockaddr_size.3 create mode 100644 static/netbsd/man3/krb5_mcc_ops.3 create mode 100644 static/netbsd/man3/krb5_mk_req.3 create mode 100644 static/netbsd/man3/krb5_mk_safe.3 create mode 100644 static/netbsd/man3/krb5_openlog.3 create mode 100644 static/netbsd/man3/krb5_pac.3 create mode 100644 static/netbsd/man3/krb5_pac_get_buffer.3 create mode 100644 static/netbsd/man3/krb5_pac_verify.3 create mode 100644 static/netbsd/man3/krb5_parse_address.3 create mode 100644 static/netbsd/man3/krb5_parse_name.3 create mode 100644 static/netbsd/man3/krb5_parse_name_flags.3 create mode 100644 static/netbsd/man3/krb5_parse_nametype.3 create mode 100644 static/netbsd/man3/krb5_password_key_proc.3 create mode 100644 static/netbsd/man3/krb5_plugin_register.3 create mode 100644 static/netbsd/man3/krb5_prepend_config_files_default.3 create mode 100644 static/netbsd/man3/krb5_prepend_error_message.3 create mode 100644 static/netbsd/man3/krb5_princ_realm.3 create mode 100644 static/netbsd/man3/krb5_princ_set_realm.3 create mode 100644 static/netbsd/man3/krb5_principal.3 create mode 100644 static/netbsd/man3/krb5_principal_compare.3 create mode 100644 static/netbsd/man3/krb5_principal_compare_any_realm.3 create mode 100644 static/netbsd/man3/krb5_principal_get_num_comp.3 create mode 100644 static/netbsd/man3/krb5_principal_get_realm.3 create mode 100644 static/netbsd/man3/krb5_principal_get_type.3 create mode 100644 static/netbsd/man3/krb5_principal_intro.3 create mode 100644 static/netbsd/man3/krb5_principal_is_anonymous.3 create mode 100644 static/netbsd/man3/krb5_principal_is_gss_hostbased_service.3 create mode 100644 static/netbsd/man3/krb5_principal_is_krbtgt.3 create mode 100644 static/netbsd/man3/krb5_principal_is_lkdc.3 create mode 100644 static/netbsd/man3/krb5_principal_is_null.3 create mode 100644 static/netbsd/man3/krb5_principal_is_pku2u.3 create mode 100644 static/netbsd/man3/krb5_principal_is_root_krbtgt.3 create mode 100644 static/netbsd/man3/krb5_principal_match.3 create mode 100644 static/netbsd/man3/krb5_principal_set_realm.3 create mode 100644 static/netbsd/man3/krb5_principal_set_type.3 create mode 100644 static/netbsd/man3/krb5_print_address.3 create mode 100644 static/netbsd/man3/krb5_random_to_key.3 create mode 100644 static/netbsd/man3/krb5_rcache.3 create mode 100644 static/netbsd/man3/krb5_rd_error.3 create mode 100644 static/netbsd/man3/krb5_rd_req_ctx.3 create mode 100644 static/netbsd/man3/krb5_rd_req_in_ctx_alloc.3 create mode 100644 static/netbsd/man3/krb5_rd_req_in_set_keytab.3 create mode 100644 static/netbsd/man3/krb5_rd_req_in_set_pac_check.3 create mode 100644 static/netbsd/man3/krb5_rd_req_out_ctx_free.3 create mode 100644 static/netbsd/man3/krb5_rd_req_out_get_server.3 create mode 100644 static/netbsd/man3/krb5_rd_safe.3 create mode 100644 static/netbsd/man3/krb5_realm_compare.3 create mode 100644 static/netbsd/man3/krb5_realm_is_lkdc.3 create mode 100644 static/netbsd/man3/krb5_ret_address.3 create mode 100644 static/netbsd/man3/krb5_ret_addrs.3 create mode 100644 static/netbsd/man3/krb5_ret_authdata.3 create mode 100644 static/netbsd/man3/krb5_ret_creds.3 create mode 100644 static/netbsd/man3/krb5_ret_creds_tag.3 create mode 100644 static/netbsd/man3/krb5_ret_data.3 create mode 100644 static/netbsd/man3/krb5_ret_int16.3 create mode 100644 static/netbsd/man3/krb5_ret_int32.3 create mode 100644 static/netbsd/man3/krb5_ret_int64.3 create mode 100644 static/netbsd/man3/krb5_ret_int8.3 create mode 100644 static/netbsd/man3/krb5_ret_keyblock.3 create mode 100644 static/netbsd/man3/krb5_ret_principal.3 create mode 100644 static/netbsd/man3/krb5_ret_string.3 create mode 100644 static/netbsd/man3/krb5_ret_stringz.3 create mode 100644 static/netbsd/man3/krb5_ret_times.3 create mode 100644 static/netbsd/man3/krb5_ret_uint16.3 create mode 100644 static/netbsd/man3/krb5_ret_uint32.3 create mode 100644 static/netbsd/man3/krb5_ret_uint64.3 create mode 100644 static/netbsd/man3/krb5_ret_uint8.3 create mode 100644 static/netbsd/man3/krb5_set_config_files.3 create mode 100644 static/netbsd/man3/krb5_set_default_in_tkt_etypes.3 create mode 100644 static/netbsd/man3/krb5_set_default_realm.3 create mode 100644 static/netbsd/man3/krb5_set_dns_canonicalize_hostname.3 create mode 100644 static/netbsd/man3/krb5_set_error_message.3 create mode 100644 static/netbsd/man3/krb5_set_error_string.3 create mode 100644 static/netbsd/man3/krb5_set_extra_addresses.3 create mode 100644 static/netbsd/man3/krb5_set_fcache_version.3 create mode 100644 static/netbsd/man3/krb5_set_home_dir_access.3 create mode 100644 static/netbsd/man3/krb5_set_ignore_addresses.3 create mode 100644 static/netbsd/man3/krb5_set_kdc_sec_offset.3 create mode 100644 static/netbsd/man3/krb5_set_max_time_skew.3 create mode 100644 static/netbsd/man3/krb5_set_password.3 create mode 100644 static/netbsd/man3/krb5_set_real_time.3 create mode 100644 static/netbsd/man3/krb5_set_use_admin_kdc.3 create mode 100644 static/netbsd/man3/krb5_set_warn_dest.3 create mode 100644 static/netbsd/man3/krb5_sname_to_principal.3 create mode 100644 static/netbsd/man3/krb5_sockaddr2address.3 create mode 100644 static/netbsd/man3/krb5_sockaddr2port.3 create mode 100644 static/netbsd/man3/krb5_sockaddr_uninteresting.3 create mode 100644 static/netbsd/man3/krb5_storage.3 create mode 100644 static/netbsd/man3/krb5_storage_clear_flags.3 create mode 100644 static/netbsd/man3/krb5_storage_emem.3 create mode 100644 static/netbsd/man3/krb5_storage_free.3 create mode 100644 static/netbsd/man3/krb5_storage_from_data.3 create mode 100644 static/netbsd/man3/krb5_storage_from_fd.3 create mode 100644 static/netbsd/man3/krb5_storage_from_mem.3 create mode 100644 static/netbsd/man3/krb5_storage_from_readonly_mem.3 create mode 100644 static/netbsd/man3/krb5_storage_from_socket.3 create mode 100644 static/netbsd/man3/krb5_storage_fsync.3 create mode 100644 static/netbsd/man3/krb5_storage_get_byteorder.3 create mode 100644 static/netbsd/man3/krb5_storage_get_eof_code.3 create mode 100644 static/netbsd/man3/krb5_storage_is_flags.3 create mode 100644 static/netbsd/man3/krb5_storage_read.3 create mode 100644 static/netbsd/man3/krb5_storage_seek.3 create mode 100644 static/netbsd/man3/krb5_storage_set_byteorder.3 create mode 100644 static/netbsd/man3/krb5_storage_set_eof_code.3 create mode 100644 static/netbsd/man3/krb5_storage_set_flags.3 create mode 100644 static/netbsd/man3/krb5_storage_set_max_alloc.3 create mode 100644 static/netbsd/man3/krb5_storage_to_data.3 create mode 100644 static/netbsd/man3/krb5_storage_truncate.3 create mode 100644 static/netbsd/man3/krb5_storage_write.3 create mode 100644 static/netbsd/man3/krb5_store_address.3 create mode 100644 static/netbsd/man3/krb5_store_addrs.3 create mode 100644 static/netbsd/man3/krb5_store_authdata.3 create mode 100644 static/netbsd/man3/krb5_store_creds.3 create mode 100644 static/netbsd/man3/krb5_store_creds_tag.3 create mode 100644 static/netbsd/man3/krb5_store_data.3 create mode 100644 static/netbsd/man3/krb5_store_int16.3 create mode 100644 static/netbsd/man3/krb5_store_int32.3 create mode 100644 static/netbsd/man3/krb5_store_int64.3 create mode 100644 static/netbsd/man3/krb5_store_int8.3 create mode 100644 static/netbsd/man3/krb5_store_keyblock.3 create mode 100644 static/netbsd/man3/krb5_store_principal.3 create mode 100644 static/netbsd/man3/krb5_store_string.3 create mode 100644 static/netbsd/man3/krb5_store_stringz.3 create mode 100644 static/netbsd/man3/krb5_store_times.3 create mode 100644 static/netbsd/man3/krb5_store_uint16.3 create mode 100644 static/netbsd/man3/krb5_store_uint32.3 create mode 100644 static/netbsd/man3/krb5_store_uint64.3 create mode 100644 static/netbsd/man3/krb5_store_uint8.3 create mode 100644 static/netbsd/man3/krb5_string_to_key.3 create mode 100644 static/netbsd/man3/krb5_string_to_keytype.3 create mode 100644 static/netbsd/man3/krb5_support.3 create mode 100644 static/netbsd/man3/krb5_ticket.3 create mode 100644 static/netbsd/man3/krb5_ticket_get_authorization_data_type.3 create mode 100644 static/netbsd/man3/krb5_ticket_get_client.3 create mode 100644 static/netbsd/man3/krb5_ticket_get_endtime.3 create mode 100644 static/netbsd/man3/krb5_ticket_get_flags.3 create mode 100644 static/netbsd/man3/krb5_ticket_get_server.3 create mode 100644 static/netbsd/man3/krb5_timeofday.3 create mode 100644 static/netbsd/man3/krb5_unparse_name.3 create mode 100644 static/netbsd/man3/krb5_unparse_name_fixed.3 create mode 100644 static/netbsd/man3/krb5_unparse_name_fixed_flags.3 create mode 100644 static/netbsd/man3/krb5_unparse_name_fixed_short.3 create mode 100644 static/netbsd/man3/krb5_unparse_name_flags.3 create mode 100644 static/netbsd/man3/krb5_unparse_name_short.3 create mode 100644 static/netbsd/man3/krb5_v4compat.3 create mode 100644 static/netbsd/man3/krb5_vabort.3 create mode 100644 static/netbsd/man3/krb5_verify_checksum_iov.3 create mode 100644 static/netbsd/man3/krb5_verify_init_creds.3 create mode 100644 static/netbsd/man3/krb5_verify_user.3 create mode 100644 static/netbsd/man3/krb5_verr.3 create mode 100644 static/netbsd/man3/krb5_verrx.3 create mode 100644 static/netbsd/man3/krb5_vprepend_error_message.3 create mode 100644 static/netbsd/man3/krb5_vset_error_message.3 create mode 100644 static/netbsd/man3/krb5_vset_error_string.3 create mode 100644 static/netbsd/man3/krb5_vwarn.3 create mode 100644 static/netbsd/man3/krb5_vwarnx.3 create mode 100644 static/netbsd/man3/krb5_warn.3 create mode 100644 static/netbsd/man3/krb5_warnx.3 create mode 100644 static/netbsd/man3/krb5plugin_an2ln_ftable_desc.3 create mode 100644 static/netbsd/man3/krb5plugin_db_ftable_desc.3 create mode 100644 static/netbsd/man3/krb5plugin_kuserok_ftable_desc.3 create mode 100644 static/netbsd/man3/kvm.3 create mode 100644 static/netbsd/man3/kvm_dump.3 create mode 100644 static/netbsd/man3/kvm_geterr.3 create mode 100644 static/netbsd/man3/kvm_getfiles.3 create mode 100644 static/netbsd/man3/kvm_getkernelname.3 create mode 100644 static/netbsd/man3/kvm_getloadavg.3 create mode 100644 static/netbsd/man3/kvm_getlwps.3 create mode 100644 static/netbsd/man3/kvm_getprocs.3 create mode 100644 static/netbsd/man3/kvm_nlist.3 create mode 100644 static/netbsd/man3/kvm_open.3 create mode 100644 static/netbsd/man3/kvm_read.3 create mode 100644 static/netbsd/man3/lber-decode.3 create mode 100644 static/netbsd/man3/lber-encode.3 create mode 100644 static/netbsd/man3/lber-memory.3 create mode 100644 static/netbsd/man3/lber-sockbuf.3 create mode 100644 static/netbsd/man3/lber-types.3 create mode 100644 static/netbsd/man3/ldap.3 create mode 100644 static/netbsd/man3/ldap_abandon.3 create mode 100644 static/netbsd/man3/ldap_add.3 create mode 100644 static/netbsd/man3/ldap_bind.3 create mode 100644 static/netbsd/man3/ldap_compare.3 create mode 100644 static/netbsd/man3/ldap_controls.3 create mode 100644 static/netbsd/man3/ldap_delete.3 create mode 100644 static/netbsd/man3/ldap_dup.3 create mode 100644 static/netbsd/man3/ldap_error.3 create mode 100644 static/netbsd/man3/ldap_extended_operation.3 create mode 100644 static/netbsd/man3/ldap_first_attribute.3 create mode 100644 static/netbsd/man3/ldap_first_entry.3 create mode 100644 static/netbsd/man3/ldap_first_message.3 create mode 100644 static/netbsd/man3/ldap_first_reference.3 create mode 100644 static/netbsd/man3/ldap_get_dn.3 create mode 100644 static/netbsd/man3/ldap_get_option.3 create mode 100644 static/netbsd/man3/ldap_get_values.3 create mode 100644 static/netbsd/man3/ldap_memory.3 create mode 100644 static/netbsd/man3/ldap_modify.3 create mode 100644 static/netbsd/man3/ldap_modrdn.3 create mode 100644 static/netbsd/man3/ldap_open.3 create mode 100644 static/netbsd/man3/ldap_parse_reference.3 create mode 100644 static/netbsd/man3/ldap_parse_result.3 create mode 100644 static/netbsd/man3/ldap_parse_sort_control.3 create mode 100644 static/netbsd/man3/ldap_parse_vlv_control.3 create mode 100644 static/netbsd/man3/ldap_rename.3 create mode 100644 static/netbsd/man3/ldap_result.3 create mode 100644 static/netbsd/man3/ldap_schema.3 create mode 100644 static/netbsd/man3/ldap_search.3 create mode 100644 static/netbsd/man3/ldap_sort.3 create mode 100644 static/netbsd/man3/ldap_sync.3 create mode 100644 static/netbsd/man3/ldap_tls.3 create mode 100644 static/netbsd/man3/ldap_url.3 create mode 100644 static/netbsd/man3/ldexp.3 create mode 100644 static/netbsd/man3/length.3 create mode 100644 static/netbsd/man3/lgamma.3 create mode 100644 static/netbsd/man3/lh_stats.3 create mode 100644 static/netbsd/man3/libarchive.3 create mode 100644 static/netbsd/man3/libarchive_changes.3 create mode 100644 static/netbsd/man3/libarchive_internals.3 create mode 100644 static/netbsd/man3/libblocklist.3 create mode 100644 static/netbsd/man3/libbozohttpd.3 create mode 100644 static/netbsd/man3/libiscsi.3 create mode 100644 static/netbsd/man3/libmagic.3 create mode 100644 static/netbsd/man3/libmj.3 create mode 100644 static/netbsd/man3/libnetpgp.3 create mode 100644 static/netbsd/man3/libnetpgpbn.3 create mode 100644 static/netbsd/man3/libnetpgprsa.3 create mode 100644 static/netbsd/man3/libnetpgpverify.3 create mode 100644 static/netbsd/man3/libnpf.3 create mode 100644 static/netbsd/man3/libnvmm.3 create mode 100644 static/netbsd/man3/libpaa.3 create mode 100644 static/netbsd/man3/libperfuse.3 create mode 100644 static/netbsd/man3/libquota.3 create mode 100644 static/netbsd/man3/libradius.3 create mode 100644 static/netbsd/man3/librtld_db.3 create mode 100644 static/netbsd/man3/libsaslc.3 create mode 100644 static/netbsd/man3/libuv.3 create mode 100644 static/netbsd/man3/linkaddr.3 create mode 100644 static/netbsd/man3/lio_listio.3 create mode 100644 static/netbsd/man3/lockf.3 create mode 100644 static/netbsd/man3/log.3 create mode 100644 static/netbsd/man3/login.3 create mode 100644 static/netbsd/man3/login_cap.3 create mode 100644 static/netbsd/man3/loginx.3 create mode 100644 static/netbsd/man3/lrint.3 create mode 100644 static/netbsd/man3/lsearch.3 create mode 100644 static/netbsd/man3/makecontext.3 create mode 100644 static/netbsd/man3/malloc.3 create mode 100644 static/netbsd/man3/man.cgi.3 create mode 100644 static/netbsd/man3/mandoc.3 create mode 100644 static/netbsd/man3/mandoc_escape.3 create mode 100644 static/netbsd/man3/mandoc_headers.3 create mode 100644 static/netbsd/man3/mandoc_html.3 create mode 100644 static/netbsd/man3/mandoc_malloc.3 create mode 100644 static/netbsd/man3/mansearch.3 create mode 100644 static/netbsd/man3/math.3 create mode 100644 static/netbsd/man3/mblen.3 create mode 100644 static/netbsd/man3/mbrlen.3 create mode 100644 static/netbsd/man3/mbrtoc16.3 create mode 100644 static/netbsd/man3/mbrtoc32.3 create mode 100644 static/netbsd/man3/mbrtoc8.3 create mode 100644 static/netbsd/man3/mbrtowc.3 create mode 100644 static/netbsd/man3/mbsinit.3 create mode 100644 static/netbsd/man3/mbsrtowcs.3 create mode 100644 static/netbsd/man3/mbstowcs.3 create mode 100644 static/netbsd/man3/mbtowc.3 create mode 100644 static/netbsd/man3/mchars_alloc.3 create mode 100644 static/netbsd/man3/md2.3 create mode 100644 static/netbsd/man3/mdX.3 create mode 100644 static/netbsd/man3/membar_ops.3 create mode 100644 static/netbsd/man3/memccpy.3 create mode 100644 static/netbsd/man3/memchr.3 create mode 100644 static/netbsd/man3/memcmp.3 create mode 100644 static/netbsd/man3/memcpy.3 create mode 100644 static/netbsd/man3/memmem.3 create mode 100644 static/netbsd/man3/memmove.3 create mode 100644 static/netbsd/man3/memory.3 create mode 100644 static/netbsd/man3/memset.3 create mode 100644 static/netbsd/man3/menu_attributes.3 create mode 100644 static/netbsd/man3/menu_cursor.3 create mode 100644 static/netbsd/man3/menu_driver.3 create mode 100644 static/netbsd/man3/menu_format.3 create mode 100644 static/netbsd/man3/menu_hook.3 create mode 100644 static/netbsd/man3/menu_item_current.3 create mode 100644 static/netbsd/man3/menu_item_name.3 create mode 100644 static/netbsd/man3/menu_item_new.3 create mode 100644 static/netbsd/man3/menu_item_opts.3 create mode 100644 static/netbsd/man3/menu_item_userptr.3 create mode 100644 static/netbsd/man3/menu_item_value.3 create mode 100644 static/netbsd/man3/menu_item_visible.3 create mode 100644 static/netbsd/man3/menu_items.3 create mode 100644 static/netbsd/man3/menu_mark.3 create mode 100644 static/netbsd/man3/menu_new.3 create mode 100644 static/netbsd/man3/menu_opts.3 create mode 100644 static/netbsd/man3/menu_pattern.3 create mode 100644 static/netbsd/man3/menu_post.3 create mode 100644 static/netbsd/man3/menu_userptr.3 create mode 100644 static/netbsd/man3/menu_win.3 create mode 100644 static/netbsd/man3/menus.3 create mode 100644 static/netbsd/man3/mi_vector_hash.3 create mode 100644 static/netbsd/man3/mktemp.3 create mode 100644 static/netbsd/man3/modf.3 create mode 100644 static/netbsd/man3/modrdn.out.provider.3 create mode 100644 static/netbsd/man3/moncontrol.3 create mode 100644 static/netbsd/man3/move_panel.3 create mode 100644 static/netbsd/man3/mpool.3 create mode 100644 static/netbsd/man3/mq.3 create mode 100644 static/netbsd/man3/mq_close.3 create mode 100644 static/netbsd/man3/mq_getattr.3 create mode 100644 static/netbsd/man3/mq_notify.3 create mode 100644 static/netbsd/man3/mq_open.3 create mode 100644 static/netbsd/man3/mq_receive.3 create mode 100644 static/netbsd/man3/mq_send.3 create mode 100644 static/netbsd/man3/mq_setattr.3 create mode 100644 static/netbsd/man3/mq_unlink.3 create mode 100644 static/netbsd/man3/mtx.3 create mode 100644 static/netbsd/man3/nan.3 create mode 100644 static/netbsd/man3/new_panel.3 create mode 100644 static/netbsd/man3/newlocale.3 create mode 100644 static/netbsd/man3/nextafter.3 create mode 100644 static/netbsd/man3/ngettext.3 create mode 100644 static/netbsd/man3/nice.3 create mode 100644 static/netbsd/man3/nl_langinfo.3 create mode 100644 static/netbsd/man3/nlist.3 create mode 100644 static/netbsd/man3/nsdispatch.3 create mode 100644 static/netbsd/man3/ntlm_buf.3 create mode 100644 static/netbsd/man3/ntlm_core.3 create mode 100644 static/netbsd/man3/ntlm_type1.3 create mode 100644 static/netbsd/man3/ntlm_type2.3 create mode 100644 static/netbsd/man3/ntlm_type3.3 create mode 100644 static/netbsd/man3/o2i_SCT_LIST.3 create mode 100644 static/netbsd/man3/offtime.3 create mode 100644 static/netbsd/man3/ohash_init.3 create mode 100644 static/netbsd/man3/ohash_interval.3 create mode 100644 static/netbsd/man3/omapi.3 create mode 100644 static/netbsd/man3/open_memstream.3 create mode 100644 static/netbsd/man3/opendisk.3 create mode 100644 static/netbsd/man3/openpam.3 create mode 100644 static/netbsd/man3/openpam_borrow_cred.3 create mode 100644 static/netbsd/man3/openpam_free_data.3 create mode 100644 static/netbsd/man3/openpam_free_envlist.3 create mode 100644 static/netbsd/man3/openpam_get_feature.3 create mode 100644 static/netbsd/man3/openpam_get_option.3 create mode 100644 static/netbsd/man3/openpam_log.3 create mode 100644 static/netbsd/man3/openpam_nullconv.3 create mode 100644 static/netbsd/man3/openpam_readline.3 create mode 100644 static/netbsd/man3/openpam_readlinev.3 create mode 100644 static/netbsd/man3/openpam_readword.3 create mode 100644 static/netbsd/man3/openpam_restore_cred.3 create mode 100644 static/netbsd/man3/openpam_set_feature.3 create mode 100644 static/netbsd/man3/openpam_set_option.3 create mode 100644 static/netbsd/man3/openpam_straddch.3 create mode 100644 static/netbsd/man3/openpam_subst.3 create mode 100644 static/netbsd/man3/openpam_ttyconv.3 create mode 100644 static/netbsd/man3/openpty.3 create mode 100644 static/netbsd/man3/openssl-DES_random_key.3 create mode 100644 static/netbsd/man3/openssl-HMAC.3 create mode 100644 static/netbsd/man3/openssl-MD5.3 create mode 100644 static/netbsd/man3/openssl_HMAC.3 create mode 100644 static/netbsd/man3/openssl_MD5.3 create mode 100644 static/netbsd/man3/openssl_bio.3 create mode 100644 static/netbsd/man3/openssl_blowfish.3 create mode 100644 static/netbsd/man3/openssl_bn.3 create mode 100644 static/netbsd/man3/openssl_bn_internal.3 create mode 100644 static/netbsd/man3/openssl_buffer.3 create mode 100644 static/netbsd/man3/openssl_des.3 create mode 100644 static/netbsd/man3/openssl_dh.3 create mode 100644 static/netbsd/man3/openssl_dsa.3 create mode 100644 static/netbsd/man3/openssl_ecdsa.3 create mode 100644 static/netbsd/man3/openssl_engine.3 create mode 100644 static/netbsd/man3/openssl_err.3 create mode 100644 static/netbsd/man3/openssl_evp.3 create mode 100644 static/netbsd/man3/openssl_lhash.3 create mode 100644 static/netbsd/man3/openssl_mdc2.3 create mode 100644 static/netbsd/man3/openssl_pem.3 create mode 100644 static/netbsd/man3/openssl_rand.3 create mode 100644 static/netbsd/man3/openssl_rc4.3 create mode 100644 static/netbsd/man3/openssl_ripemd.3 create mode 100644 static/netbsd/man3/openssl_rsa.3 create mode 100644 static/netbsd/man3/openssl_sha.3 create mode 100644 static/netbsd/man3/openssl_threads.3 create mode 100644 static/netbsd/man3/openssl_ui.3 create mode 100644 static/netbsd/man3/openssl_ui_compat.3 create mode 100644 static/netbsd/man3/openssl_x509.3 create mode 100644 static/netbsd/man3/ossaudio.3 create mode 100644 static/netbsd/man3/p.3 create mode 100644 static/netbsd/man3/p2k.3 create mode 100644 static/netbsd/man3/page_ca.3 create mode 100644 static/netbsd/man3/page_cert.3 create mode 100644 static/netbsd/man3/page_cms.3 create mode 100644 static/netbsd/man3/page_des.3 create mode 100644 static/netbsd/man3/page_dh.3 create mode 100644 static/netbsd/man3/page_env.3 create mode 100644 static/netbsd/man3/page_error.3 create mode 100644 static/netbsd/man3/page_evp.3 create mode 100644 static/netbsd/man3/page_keyset.3 create mode 100644 static/netbsd/man3/page_lock.3 create mode 100644 static/netbsd/man3/page_name.3 create mode 100644 static/netbsd/man3/page_peer.3 create mode 100644 static/netbsd/man3/page_print.3 create mode 100644 static/netbsd/man3/page_rand.3 create mode 100644 static/netbsd/man3/page_revoke.3 create mode 100644 static/netbsd/man3/page_rsa.3 create mode 100644 static/netbsd/man3/pam.3 create mode 100644 static/netbsd/man3/pam_acct_mgmt.3 create mode 100644 static/netbsd/man3/pam_authenticate.3 create mode 100644 static/netbsd/man3/pam_chauthtok.3 create mode 100644 static/netbsd/man3/pam_close_session.3 create mode 100644 static/netbsd/man3/pam_conv.3 create mode 100644 static/netbsd/man3/pam_end.3 create mode 100644 static/netbsd/man3/pam_error.3 create mode 100644 static/netbsd/man3/pam_get_authtok.3 create mode 100644 static/netbsd/man3/pam_get_data.3 create mode 100644 static/netbsd/man3/pam_get_item.3 create mode 100644 static/netbsd/man3/pam_get_user.3 create mode 100644 static/netbsd/man3/pam_getenv.3 create mode 100644 static/netbsd/man3/pam_getenvlist.3 create mode 100644 static/netbsd/man3/pam_info.3 create mode 100644 static/netbsd/man3/pam_open_session.3 create mode 100644 static/netbsd/man3/pam_prompt.3 create mode 100644 static/netbsd/man3/pam_putenv.3 create mode 100644 static/netbsd/man3/pam_set_data.3 create mode 100644 static/netbsd/man3/pam_set_item.3 create mode 100644 static/netbsd/man3/pam_setcred.3 create mode 100644 static/netbsd/man3/pam_setenv.3 create mode 100644 static/netbsd/man3/pam_sm_acct_mgmt.3 create mode 100644 static/netbsd/man3/pam_sm_authenticate.3 create mode 100644 static/netbsd/man3/pam_sm_chauthtok.3 create mode 100644 static/netbsd/man3/pam_sm_close_session.3 create mode 100644 static/netbsd/man3/pam_sm_open_session.3 create mode 100644 static/netbsd/man3/pam_sm_setcred.3 create mode 100644 static/netbsd/man3/pam_start.3 create mode 100644 static/netbsd/man3/pam_strerror.3 create mode 100644 static/netbsd/man3/pam_verror.3 create mode 100644 static/netbsd/man3/pam_vinfo.3 create mode 100644 static/netbsd/man3/pam_vprompt.3 create mode 100644 static/netbsd/man3/panel.3 create mode 100644 static/netbsd/man3/panel_above.3 create mode 100644 static/netbsd/man3/panel_hidden.3 create mode 100644 static/netbsd/man3/panel_userptr.3 create mode 100644 static/netbsd/man3/parse_time.3 create mode 100644 static/netbsd/man3/parsedate.3 create mode 100644 static/netbsd/man3/pause.3 create mode 100644 static/netbsd/man3/pci.3 create mode 100644 static/netbsd/man3/pidfile.3 create mode 100644 static/netbsd/man3/pidlock.3 create mode 100644 static/netbsd/man3/popcount.3 create mode 100644 static/netbsd/man3/popen.3 create mode 100644 static/netbsd/man3/posix1e.3 create mode 100644 static/netbsd/man3/posix_memalign.3 create mode 100644 static/netbsd/man3/posix_openpt.3 create mode 100644 static/netbsd/man3/posix_spawn.3 create mode 100644 static/netbsd/man3/posix_spawn_file_actions_addchdir.3 create mode 100644 static/netbsd/man3/posix_spawn_file_actions_addopen.3 create mode 100644 static/netbsd/man3/posix_spawn_file_actions_init.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getflags.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getpgroup.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getschedparam.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getschedpolicy.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getsigdefault.3 create mode 100644 static/netbsd/man3/posix_spawnattr_getsigmask.3 create mode 100644 static/netbsd/man3/posix_spawnattr_init.3 create mode 100644 static/netbsd/man3/pow.3 create mode 100644 static/netbsd/man3/ppath.3 create mode 100644 static/netbsd/man3/ppath_bool.3 create mode 100644 static/netbsd/man3/ppath_number.3 create mode 100644 static/netbsd/man3/ppath_object.3 create mode 100644 static/netbsd/man3/printf.3 create mode 100644 static/netbsd/man3/printf_l.3 create mode 100644 static/netbsd/man3/proc_compare.3 create mode 100644 static/netbsd/man3/prop_array.3 create mode 100644 static/netbsd/man3/prop_array_util.3 create mode 100644 static/netbsd/man3/prop_bool.3 create mode 100644 static/netbsd/man3/prop_data.3 create mode 100644 static/netbsd/man3/prop_dictionary.3 create mode 100644 static/netbsd/man3/prop_dictionary_util.3 create mode 100644 static/netbsd/man3/prop_ingest.3 create mode 100644 static/netbsd/man3/prop_number.3 create mode 100644 static/netbsd/man3/prop_object.3 create mode 100644 static/netbsd/man3/prop_send_ioctl.3 create mode 100644 static/netbsd/man3/prop_send_syscall.3 create mode 100644 static/netbsd/man3/prop_string.3 create mode 100644 static/netbsd/man3/proplib.3 create mode 100644 static/netbsd/man3/pset.3 create mode 100644 static/netbsd/man3/psignal.3 create mode 100644 static/netbsd/man3/pthread.3 create mode 100644 static/netbsd/man3/pthread_atfork.3 create mode 100644 static/netbsd/man3/pthread_attr.3 create mode 100644 static/netbsd/man3/pthread_attr_get_np.3 create mode 100644 static/netbsd/man3/pthread_attr_getdetachstate.3 create mode 100644 static/netbsd/man3/pthread_attr_getguardsize.3 create mode 100644 static/netbsd/man3/pthread_attr_getinheritsched.3 create mode 100644 static/netbsd/man3/pthread_attr_getname_np.3 create mode 100644 static/netbsd/man3/pthread_attr_getschedparam.3 create mode 100644 static/netbsd/man3/pthread_attr_getscope.3 create mode 100644 static/netbsd/man3/pthread_attr_getstack.3 create mode 100644 static/netbsd/man3/pthread_attr_setcreatesuspend_np.3 create mode 100644 static/netbsd/man3/pthread_barrier.3 create mode 100644 static/netbsd/man3/pthread_barrierattr.3 create mode 100644 static/netbsd/man3/pthread_cancel.3 create mode 100644 static/netbsd/man3/pthread_cleanup_push.3 create mode 100644 static/netbsd/man3/pthread_cond.3 create mode 100644 static/netbsd/man3/pthread_condattr.3 create mode 100644 static/netbsd/man3/pthread_create.3 create mode 100644 static/netbsd/man3/pthread_curcpu_np.3 create mode 100644 static/netbsd/man3/pthread_detach.3 create mode 100644 static/netbsd/man3/pthread_equal.3 create mode 100644 static/netbsd/man3/pthread_exit.3 create mode 100644 static/netbsd/man3/pthread_getcpuclockid.3 create mode 100644 static/netbsd/man3/pthread_getname_np.3 create mode 100644 static/netbsd/man3/pthread_getspecific.3 create mode 100644 static/netbsd/man3/pthread_join.3 create mode 100644 static/netbsd/man3/pthread_key_create.3 create mode 100644 static/netbsd/man3/pthread_kill.3 create mode 100644 static/netbsd/man3/pthread_mutex.3 create mode 100644 static/netbsd/man3/pthread_mutexattr.3 create mode 100644 static/netbsd/man3/pthread_once.3 create mode 100644 static/netbsd/man3/pthread_rwlock.3 create mode 100644 static/netbsd/man3/pthread_rwlockattr.3 create mode 100644 static/netbsd/man3/pthread_schedparam.3 create mode 100644 static/netbsd/man3/pthread_self.3 create mode 100644 static/netbsd/man3/pthread_sigmask.3 create mode 100644 static/netbsd/man3/pthread_spin.3 create mode 100644 static/netbsd/man3/pthread_suspend_np.3 create mode 100644 static/netbsd/man3/pthread_testcancel.3 create mode 100644 static/netbsd/man3/ptsname.3 create mode 100644 static/netbsd/man3/puffs.3 create mode 100644 static/netbsd/man3/puffs_cc.3 create mode 100644 static/netbsd/man3/puffs_cred.3 create mode 100644 static/netbsd/man3/puffs_flush.3 create mode 100644 static/netbsd/man3/puffs_framebuf.3 create mode 100644 static/netbsd/man3/puffs_node.3 create mode 100644 static/netbsd/man3/puffs_ops.3 create mode 100644 static/netbsd/man3/puffs_path.3 create mode 100644 static/netbsd/man3/putc.3 create mode 100644 static/netbsd/man3/putwc.3 create mode 100644 static/netbsd/man3/pw_gensalt.3 create mode 100644 static/netbsd/man3/pw_getconf.3 create mode 100644 static/netbsd/man3/pw_init.3 create mode 100644 static/netbsd/man3/pw_lock.3 create mode 100644 static/netbsd/man3/pwcache.3 create mode 100644 static/netbsd/man3/qabs.3 create mode 100644 static/netbsd/man3/qdiv.3 create mode 100644 static/netbsd/man3/qsort.3 create mode 100644 static/netbsd/man3/quick_exit.3 create mode 100644 static/netbsd/man3/radixsort.3 create mode 100644 static/netbsd/man3/raise.3 create mode 100644 static/netbsd/man3/raise_default_signal.3 create mode 100644 static/netbsd/man3/rand.3 create mode 100644 static/netbsd/man3/rand48.3 create mode 100644 static/netbsd/man3/random.3 create mode 100644 static/netbsd/man3/randomid.3 create mode 100644 static/netbsd/man3/rcmd.3 create mode 100644 static/netbsd/man3/re_comp.3 create mode 100644 static/netbsd/man3/readline.3 create mode 100644 static/netbsd/man3/readpassphrase.3 create mode 100644 static/netbsd/man3/reallocarr.3 create mode 100644 static/netbsd/man3/reallocarray.3 create mode 100644 static/netbsd/man3/realpath.3 create mode 100644 static/netbsd/man3/recno.3 create mode 100644 static/netbsd/man3/refuse.3 create mode 100644 static/netbsd/man3/regex.3 create mode 100644 static/netbsd/man3/regexp.3 create mode 100644 static/netbsd/man3/remainder.3 create mode 100644 static/netbsd/man3/remove.3 create mode 100644 static/netbsd/man3/resolver.3 create mode 100644 static/netbsd/man3/rexec.3 create mode 100644 static/netbsd/man3/rindex.3 create mode 100644 static/netbsd/man3/rint.3 create mode 100644 static/netbsd/man3/rmd160.3 create mode 100644 static/netbsd/man3/rmtops.3 create mode 100644 static/netbsd/man3/round.3 create mode 100644 static/netbsd/man3/rpc.3 create mode 100644 static/netbsd/man3/rpc.h.3 create mode 100644 static/netbsd/man3/rpc_clnt_auth.3 create mode 100644 static/netbsd/man3/rpc_clnt_calls.3 create mode 100644 static/netbsd/man3/rpc_clnt_create.3 create mode 100644 static/netbsd/man3/rpc_compat.h.3 create mode 100644 static/netbsd/man3/rpc_soc.3 create mode 100644 static/netbsd/man3/rpc_svc_calls.3 create mode 100644 static/netbsd/man3/rpc_svc_create.3 create mode 100644 static/netbsd/man3/rpc_svc_err.3 create mode 100644 static/netbsd/man3/rpc_svc_reg.3 create mode 100644 static/netbsd/man3/rpc_xdr.3 create mode 100644 static/netbsd/man3/rpcbind.3 create mode 100644 static/netbsd/man3/rs256_pk_new.3 create mode 100644 static/netbsd/man3/rtbl.3 create mode 100644 static/netbsd/man3/rump.3 create mode 100644 static/netbsd/man3/rump_etfs.3 create mode 100644 static/netbsd/man3/rump_lwproc.3 create mode 100644 static/netbsd/man3/rumpclient.3 create mode 100644 static/netbsd/man3/rumphijack.3 create mode 100644 static/netbsd/man3/rumpuser.3 create mode 100644 static/netbsd/man3/run_query.3 create mode 100644 static/netbsd/man3/s2i_ASN1_IA5STRING.3 create mode 100644 static/netbsd/man3/scalbn.3 create mode 100644 static/netbsd/man3/scandir.3 create mode 100644 static/netbsd/man3/scanf.3 create mode 100644 static/netbsd/man3/scanf_l.3 create mode 100644 static/netbsd/man3/sched.3 create mode 100644 static/netbsd/man3/sctp_bindx.3 create mode 100644 static/netbsd/man3/sctp_connectx.3 create mode 100644 static/netbsd/man3/sctp_freepaddrs.3 create mode 100644 static/netbsd/man3/sctp_getaddrlen.3 create mode 100644 static/netbsd/man3/sctp_getassocid.3 create mode 100644 static/netbsd/man3/sctp_getpaddrs.3 create mode 100644 static/netbsd/man3/sctp_opt_info.3 create mode 100644 static/netbsd/man3/sctp_peeloff.3 create mode 100644 static/netbsd/man3/sctp_recvmsg.3 create mode 100644 static/netbsd/man3/sctp_send.3 create mode 100644 static/netbsd/man3/sctp_sendmsg.3 create mode 100644 static/netbsd/man3/sdp.3 create mode 100644 static/netbsd/man3/sdp_data.3 create mode 100644 static/netbsd/man3/secure_path.3 create mode 100644 static/netbsd/man3/sem_destroy.3 create mode 100644 static/netbsd/man3/sem_getvalue.3 create mode 100644 static/netbsd/man3/sem_init.3 create mode 100644 static/netbsd/man3/sem_open.3 create mode 100644 static/netbsd/man3/sem_post.3 create mode 100644 static/netbsd/man3/sem_wait.3 create mode 100644 static/netbsd/man3/setbuf.3 create mode 100644 static/netbsd/man3/setjmp.3 create mode 100644 static/netbsd/man3/setlocale.3 create mode 100644 static/netbsd/man3/setmode.3 create mode 100644 static/netbsd/man3/setproctitle.3 create mode 100644 static/netbsd/man3/setruid.3 create mode 100644 static/netbsd/man3/sha1.3 create mode 100644 static/netbsd/man3/sha2.3 create mode 100644 static/netbsd/man3/sha3.3 create mode 100644 static/netbsd/man3/shm_open.3 create mode 100644 static/netbsd/man3/shquote.3 create mode 100644 static/netbsd/man3/sigblock.3 create mode 100644 static/netbsd/man3/sighold.3 create mode 100644 static/netbsd/man3/sigignore.3 create mode 100644 static/netbsd/man3/siginterrupt.3 create mode 100644 static/netbsd/man3/signal.3 create mode 100644 static/netbsd/man3/signalname.3 create mode 100644 static/netbsd/man3/signbit.3 create mode 100644 static/netbsd/man3/sigpause.3 create mode 100644 static/netbsd/man3/sigrelse.3 create mode 100644 static/netbsd/man3/sigset.3 create mode 100644 static/netbsd/man3/sigsetmask.3 create mode 100644 static/netbsd/man3/sigsetops.3 create mode 100644 static/netbsd/man3/sigvec.3 create mode 100644 static/netbsd/man3/sin.3 create mode 100644 static/netbsd/man3/sincos.3 create mode 100644 static/netbsd/man3/sinh.3 create mode 100644 static/netbsd/man3/skey.3 create mode 100644 static/netbsd/man3/sleep.3 create mode 100644 static/netbsd/man3/smp.3 create mode 100644 static/netbsd/man3/snprintb.3 create mode 100644 static/netbsd/man3/sockaddr_snprintf.3 create mode 100644 static/netbsd/man3/sockatmark.3 create mode 100644 static/netbsd/man3/sqlite3.3 create mode 100644 static/netbsd/man3/sqlite3_aggregate_context.3 create mode 100644 static/netbsd/man3/sqlite3_aggregate_count.3 create mode 100644 static/netbsd/man3/sqlite3_api_routines.3 create mode 100644 static/netbsd/man3/sqlite3_auto_extension.3 create mode 100644 static/netbsd/man3/sqlite3_autovacuum_pages.3 create mode 100644 static/netbsd/man3/sqlite3_backup.3 create mode 100644 static/netbsd/man3/sqlite3_backup_init.3 create mode 100644 static/netbsd/man3/sqlite3_bind_blob.3 create mode 100644 static/netbsd/man3/sqlite3_bind_parameter_count.3 create mode 100644 static/netbsd/man3/sqlite3_bind_parameter_index.3 create mode 100644 static/netbsd/man3/sqlite3_bind_parameter_name.3 create mode 100644 static/netbsd/man3/sqlite3_blob.3 create mode 100644 static/netbsd/man3/sqlite3_blob_bytes.3 create mode 100644 static/netbsd/man3/sqlite3_blob_close.3 create mode 100644 static/netbsd/man3/sqlite3_blob_open.3 create mode 100644 static/netbsd/man3/sqlite3_blob_read.3 create mode 100644 static/netbsd/man3/sqlite3_blob_reopen.3 create mode 100644 static/netbsd/man3/sqlite3_blob_write.3 create mode 100644 static/netbsd/man3/sqlite3_busy_handler.3 create mode 100644 static/netbsd/man3/sqlite3_busy_timeout.3 create mode 100644 static/netbsd/man3/sqlite3_cancel_auto_extension.3 create mode 100644 static/netbsd/man3/sqlite3_changegroup.3 create mode 100644 static/netbsd/man3/sqlite3_changes.3 create mode 100644 static/netbsd/man3/sqlite3_changeset_iter.3 create mode 100644 static/netbsd/man3/sqlite3_clear_bindings.3 create mode 100644 static/netbsd/man3/sqlite3_close.3 create mode 100644 static/netbsd/man3/sqlite3_collation_needed.3 create mode 100644 static/netbsd/man3/sqlite3_column_blob.3 create mode 100644 static/netbsd/man3/sqlite3_column_count.3 create mode 100644 static/netbsd/man3/sqlite3_column_database_name.3 create mode 100644 static/netbsd/man3/sqlite3_column_decltype.3 create mode 100644 static/netbsd/man3/sqlite3_column_name.3 create mode 100644 static/netbsd/man3/sqlite3_commit_hook.3 create mode 100644 static/netbsd/man3/sqlite3_compileoption_used.3 create mode 100644 static/netbsd/man3/sqlite3_complete.3 create mode 100644 static/netbsd/man3/sqlite3_config.3 create mode 100644 static/netbsd/man3/sqlite3_context.3 create mode 100644 static/netbsd/man3/sqlite3_context_db_handle.3 create mode 100644 static/netbsd/man3/sqlite3_create_collation.3 create mode 100644 static/netbsd/man3/sqlite3_create_filename.3 create mode 100644 static/netbsd/man3/sqlite3_create_function.3 create mode 100644 static/netbsd/man3/sqlite3_create_module.3 create mode 100644 static/netbsd/man3/sqlite3_data_count.3 create mode 100644 static/netbsd/man3/sqlite3_data_directory.3 create mode 100644 static/netbsd/man3/sqlite3_database_file_object.3 create mode 100644 static/netbsd/man3/sqlite3_db_cacheflush.3 create mode 100644 static/netbsd/man3/sqlite3_db_config.3 create mode 100644 static/netbsd/man3/sqlite3_db_filename.3 create mode 100644 static/netbsd/man3/sqlite3_db_handle.3 create mode 100644 static/netbsd/man3/sqlite3_db_mutex.3 create mode 100644 static/netbsd/man3/sqlite3_db_name.3 create mode 100644 static/netbsd/man3/sqlite3_db_readonly.3 create mode 100644 static/netbsd/man3/sqlite3_db_release_memory.3 create mode 100644 static/netbsd/man3/sqlite3_db_status.3 create mode 100644 static/netbsd/man3/sqlite3_declare_vtab.3 create mode 100644 static/netbsd/man3/sqlite3_deserialize.3 create mode 100644 static/netbsd/man3/sqlite3_destructor_type.3 create mode 100644 static/netbsd/man3/sqlite3_drop_modules.3 create mode 100644 static/netbsd/man3/sqlite3_enable_load_extension.3 create mode 100644 static/netbsd/man3/sqlite3_enable_shared_cache.3 create mode 100644 static/netbsd/man3/sqlite3_errcode.3 create mode 100644 static/netbsd/man3/sqlite3_exec.3 create mode 100644 static/netbsd/man3/sqlite3_extended_result_codes.3 create mode 100644 static/netbsd/man3/sqlite3_file.3 create mode 100644 static/netbsd/man3/sqlite3_file_control.3 create mode 100644 static/netbsd/man3/sqlite3_filename.3 create mode 100644 static/netbsd/man3/sqlite3_filename_database.3 create mode 100644 static/netbsd/man3/sqlite3_finalize.3 create mode 100644 static/netbsd/man3/sqlite3_get_autocommit.3 create mode 100644 static/netbsd/man3/sqlite3_get_auxdata.3 create mode 100644 static/netbsd/man3/sqlite3_get_clientdata.3 create mode 100644 static/netbsd/man3/sqlite3_get_table.3 create mode 100644 static/netbsd/man3/sqlite3_index_info.3 create mode 100644 static/netbsd/man3/sqlite3_initialize.3 create mode 100644 static/netbsd/man3/sqlite3_interrupt.3 create mode 100644 static/netbsd/man3/sqlite3_io_methods.3 create mode 100644 static/netbsd/man3/sqlite3_keyword_count.3 create mode 100644 static/netbsd/man3/sqlite3_last_insert_rowid.3 create mode 100644 static/netbsd/man3/sqlite3_limit.3 create mode 100644 static/netbsd/man3/sqlite3_load_extension.3 create mode 100644 static/netbsd/man3/sqlite3_log.3 create mode 100644 static/netbsd/man3/sqlite3_malloc.3 create mode 100644 static/netbsd/man3/sqlite3_mem_methods.3 create mode 100644 static/netbsd/man3/sqlite3_memory_used.3 create mode 100644 static/netbsd/man3/sqlite3_module.3 create mode 100644 static/netbsd/man3/sqlite3_mprintf.3 create mode 100644 static/netbsd/man3/sqlite3_mutex.3 create mode 100644 static/netbsd/man3/sqlite3_mutex_alloc.3 create mode 100644 static/netbsd/man3/sqlite3_mutex_held.3 create mode 100644 static/netbsd/man3/sqlite3_mutex_methods.3 create mode 100644 static/netbsd/man3/sqlite3_next_stmt.3 create mode 100644 static/netbsd/man3/sqlite3_open.3 create mode 100644 static/netbsd/man3/sqlite3_overload_function.3 create mode 100644 static/netbsd/man3/sqlite3_pcache.3 create mode 100644 static/netbsd/man3/sqlite3_pcache_methods2.3 create mode 100644 static/netbsd/man3/sqlite3_pcache_page.3 create mode 100644 static/netbsd/man3/sqlite3_prepare.3 create mode 100644 static/netbsd/man3/sqlite3_preupdate_hook.3 create mode 100644 static/netbsd/man3/sqlite3_progress_handler.3 create mode 100644 static/netbsd/man3/sqlite3_randomness.3 create mode 100644 static/netbsd/man3/sqlite3_rebaser.3 create mode 100644 static/netbsd/man3/sqlite3_release_memory.3 create mode 100644 static/netbsd/man3/sqlite3_reset.3 create mode 100644 static/netbsd/man3/sqlite3_reset_auto_extension.3 create mode 100644 static/netbsd/man3/sqlite3_result_blob.3 create mode 100644 static/netbsd/man3/sqlite3_result_subtype.3 create mode 100644 static/netbsd/man3/sqlite3_serialize.3 create mode 100644 static/netbsd/man3/sqlite3_session.3 create mode 100644 static/netbsd/man3/sqlite3_set_authorizer.3 create mode 100644 static/netbsd/man3/sqlite3_set_last_insert_rowid.3 create mode 100644 static/netbsd/man3/sqlite3_sleep.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot_cmp.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot_free.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot_get.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot_open.3 create mode 100644 static/netbsd/man3/sqlite3_snapshot_recover.3 create mode 100644 static/netbsd/man3/sqlite3_soft_heap_limit.3 create mode 100644 static/netbsd/man3/sqlite3_soft_heap_limit64.3 create mode 100644 static/netbsd/man3/sqlite3_sql.3 create mode 100644 static/netbsd/man3/sqlite3_status.3 create mode 100644 static/netbsd/man3/sqlite3_step.3 create mode 100644 static/netbsd/man3/sqlite3_stmt.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_busy.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_explain.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_isexplain.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_readonly.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_scanstatus.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_scanstatus_reset.3 create mode 100644 static/netbsd/man3/sqlite3_stmt_status.3 create mode 100644 static/netbsd/man3/sqlite3_str.3 create mode 100644 static/netbsd/man3/sqlite3_str_appendf.3 create mode 100644 static/netbsd/man3/sqlite3_str_errcode.3 create mode 100644 static/netbsd/man3/sqlite3_str_finish.3 create mode 100644 static/netbsd/man3/sqlite3_str_new.3 create mode 100644 static/netbsd/man3/sqlite3_strglob.3 create mode 100644 static/netbsd/man3/sqlite3_stricmp.3 create mode 100644 static/netbsd/man3/sqlite3_strlike.3 create mode 100644 static/netbsd/man3/sqlite3_system_errno.3 create mode 100644 static/netbsd/man3/sqlite3_table_column_metadata.3 create mode 100644 static/netbsd/man3/sqlite3_temp_directory.3 create mode 100644 static/netbsd/man3/sqlite3_test_control.3 create mode 100644 static/netbsd/man3/sqlite3_threadsafe.3 create mode 100644 static/netbsd/man3/sqlite3_total_changes.3 create mode 100644 static/netbsd/man3/sqlite3_trace.3 create mode 100644 static/netbsd/man3/sqlite3_trace_v2.3 create mode 100644 static/netbsd/man3/sqlite3_txn_state.3 create mode 100644 static/netbsd/man3/sqlite3_unlock_notify.3 create mode 100644 static/netbsd/man3/sqlite3_update_hook.3 create mode 100644 static/netbsd/man3/sqlite3_uri_parameter.3 create mode 100644 static/netbsd/man3/sqlite3_user_data.3 create mode 100644 static/netbsd/man3/sqlite3_value.3 create mode 100644 static/netbsd/man3/sqlite3_value_blob.3 create mode 100644 static/netbsd/man3/sqlite3_value_dup.3 create mode 100644 static/netbsd/man3/sqlite3_value_encoding.3 create mode 100644 static/netbsd/man3/sqlite3_value_subtype.3 create mode 100644 static/netbsd/man3/sqlite3_version.3 create mode 100644 static/netbsd/man3/sqlite3_vfs.3 create mode 100644 static/netbsd/man3/sqlite3_vfs_find.3 create mode 100644 static/netbsd/man3/sqlite3_vtab.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_collation.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_config.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_cursor.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_distinct.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_in.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_in_first.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_nochange.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_on_conflict.3 create mode 100644 static/netbsd/man3/sqlite3_vtab_rhs_value.3 create mode 100644 static/netbsd/man3/sqlite3_wal_autocheckpoint.3 create mode 100644 static/netbsd/man3/sqlite3_wal_checkpoint.3 create mode 100644 static/netbsd/man3/sqlite3_wal_checkpoint_v2.3 create mode 100644 static/netbsd/man3/sqlite3_wal_hook.3 create mode 100644 static/netbsd/man3/sqlite3_win32_set_directory.3 create mode 100644 static/netbsd/man3/sqlite3changegroup_add.3 create mode 100644 static/netbsd/man3/sqlite3changegroup_delete.3 create mode 100644 static/netbsd/man3/sqlite3changegroup_new.3 create mode 100644 static/netbsd/man3/sqlite3changegroup_output.3 create mode 100644 static/netbsd/man3/sqlite3changegroup_schema.3 create mode 100644 static/netbsd/man3/sqlite3changeset_apply.3 create mode 100644 static/netbsd/man3/sqlite3changeset_apply_strm.3 create mode 100644 static/netbsd/man3/sqlite3changeset_concat.3 create mode 100644 static/netbsd/man3/sqlite3changeset_conflict.3 create mode 100644 static/netbsd/man3/sqlite3changeset_finalize.3 create mode 100644 static/netbsd/man3/sqlite3changeset_fk_conflicts.3 create mode 100644 static/netbsd/man3/sqlite3changeset_invert.3 create mode 100644 static/netbsd/man3/sqlite3changeset_new.3 create mode 100644 static/netbsd/man3/sqlite3changeset_next.3 create mode 100644 static/netbsd/man3/sqlite3changeset_old.3 create mode 100644 static/netbsd/man3/sqlite3changeset_op.3 create mode 100644 static/netbsd/man3/sqlite3changeset_pk.3 create mode 100644 static/netbsd/man3/sqlite3changeset_start.3 create mode 100644 static/netbsd/man3/sqlite3changeset_upgrade.3 create mode 100644 static/netbsd/man3/sqlite3rebaser_configure.3 create mode 100644 static/netbsd/man3/sqlite3rebaser_create.3 create mode 100644 static/netbsd/man3/sqlite3rebaser_delete.3 create mode 100644 static/netbsd/man3/sqlite3rebaser_rebase.3 create mode 100644 static/netbsd/man3/sqlite3session_attach.3 create mode 100644 static/netbsd/man3/sqlite3session_changeset.3 create mode 100644 static/netbsd/man3/sqlite3session_changeset_size.3 create mode 100644 static/netbsd/man3/sqlite3session_config.3 create mode 100644 static/netbsd/man3/sqlite3session_create.3 create mode 100644 static/netbsd/man3/sqlite3session_delete.3 create mode 100644 static/netbsd/man3/sqlite3session_diff.3 create mode 100644 static/netbsd/man3/sqlite3session_enable.3 create mode 100644 static/netbsd/man3/sqlite3session_indirect.3 create mode 100644 static/netbsd/man3/sqlite3session_isempty.3 create mode 100644 static/netbsd/man3/sqlite3session_memory_used.3 create mode 100644 static/netbsd/man3/sqlite3session_object_config.3 create mode 100644 static/netbsd/man3/sqlite3session_patchset.3 create mode 100644 static/netbsd/man3/sqlite3session_table_filter.3 create mode 100644 static/netbsd/man3/sqlite_int64.3 create mode 100644 static/netbsd/man3/sqrt.3 create mode 100644 static/netbsd/man3/ssl.3 create mode 100644 static/netbsd/man3/ssp.3 create mode 100644 static/netbsd/man3/stat_flags.3 create mode 100644 static/netbsd/man3/stdio.3 create mode 100644 static/netbsd/man3/strcasecmp.3 create mode 100644 static/netbsd/man3/strcat.3 create mode 100644 static/netbsd/man3/strchr.3 create mode 100644 static/netbsd/man3/strcmp.3 create mode 100644 static/netbsd/man3/strcoll.3 create mode 100644 static/netbsd/man3/strcpy.3 create mode 100644 static/netbsd/man3/strcspn.3 create mode 100644 static/netbsd/man3/strdup.3 create mode 100644 static/netbsd/man3/strerror.3 create mode 100644 static/netbsd/man3/strfmon.3 create mode 100644 static/netbsd/man3/strftime.3 create mode 100644 static/netbsd/man3/string.3 create mode 100644 static/netbsd/man3/stringlist.3 create mode 100644 static/netbsd/man3/strings.3 create mode 100644 static/netbsd/man3/strlcpy.3 create mode 100644 static/netbsd/man3/strlen.3 create mode 100644 static/netbsd/man3/strmode.3 create mode 100644 static/netbsd/man3/strncpy.3 create mode 100644 static/netbsd/man3/strpbrk.3 create mode 100644 static/netbsd/man3/strpct.3 create mode 100644 static/netbsd/man3/strptime.3 create mode 100644 static/netbsd/man3/strrchr.3 create mode 100644 static/netbsd/man3/strsep.3 create mode 100644 static/netbsd/man3/strsignal.3 create mode 100644 static/netbsd/man3/strspn.3 create mode 100644 static/netbsd/man3/strstr.3 create mode 100644 static/netbsd/man3/strsuftoll.3 create mode 100644 static/netbsd/man3/strtod.3 create mode 100644 static/netbsd/man3/strtoi.3 create mode 100644 static/netbsd/man3/strtok.3 create mode 100644 static/netbsd/man3/strtol.3 create mode 100644 static/netbsd/man3/strtonum.3 create mode 100644 static/netbsd/man3/strtoul.3 create mode 100644 static/netbsd/man3/strxfrm.3 create mode 100644 static/netbsd/man3/stty.3 create mode 100644 static/netbsd/man3/swab.3 create mode 100644 static/netbsd/man3/swapon.3 create mode 100644 static/netbsd/man3/sysconf.3 create mode 100644 static/netbsd/man3/sysctl.3 create mode 100644 static/netbsd/man3/syslog.3 create mode 100644 static/netbsd/man3/system.3 create mode 100644 static/netbsd/man3/t.3 create mode 100644 static/netbsd/man3/tag.h.3 create mode 100644 static/netbsd/man3/tag_compat.h.3 create mode 100644 static/netbsd/man3/tan.3 create mode 100644 static/netbsd/man3/tanh.3 create mode 100644 static/netbsd/man3/tbl.3 create mode 100644 static/netbsd/man3/tcgetpgrp.3 create mode 100644 static/netbsd/man3/tcgetsid.3 create mode 100644 static/netbsd/man3/tcgetwinsize.3 create mode 100644 static/netbsd/man3/tcsendbreak.3 create mode 100644 static/netbsd/man3/tcsetattr.3 create mode 100644 static/netbsd/man3/tcsetpgrp.3 create mode 100644 static/netbsd/man3/termcap.3 create mode 100644 static/netbsd/man3/terminfo.3 create mode 100644 static/netbsd/man3/test_ldnsrr.3 create mode 100644 static/netbsd/man3/test_packets.3 create mode 100644 static/netbsd/man3/test_signatures.3 create mode 100644 static/netbsd/man3/textdomain.3 create mode 100644 static/netbsd/man3/thrd.3 create mode 100644 static/netbsd/man3/thread.h.3 create mode 100644 static/netbsd/man3/threads.3 create mode 100644 static/netbsd/man3/tiger.3 create mode 100644 static/netbsd/man3/time.3 create mode 100644 static/netbsd/man3/time2posix.3 create mode 100644 static/netbsd/man3/times.3 create mode 100644 static/netbsd/man3/timespec_get.3 create mode 100644 static/netbsd/man3/timezone.3 create mode 100644 static/netbsd/man3/tmpnam.3 create mode 100644 static/netbsd/man3/toascii.3 create mode 100644 static/netbsd/man3/tolower.3 create mode 100644 static/netbsd/man3/toupper.3 create mode 100644 static/netbsd/man3/towctrans.3 create mode 100644 static/netbsd/man3/towlower.3 create mode 100644 static/netbsd/man3/tpmUnsealFile.3 create mode 100644 static/netbsd/man3/tpmUnsealShred.3 create mode 100644 static/netbsd/man3/tpmUnsealStrerror.3 create mode 100644 static/netbsd/man3/trunc.3 create mode 100644 static/netbsd/man3/tsearch.3 create mode 100644 static/netbsd/man3/tsig.3 create mode 100644 static/netbsd/man3/tss.3 create mode 100644 static/netbsd/man3/ttyaction.3 create mode 100644 static/netbsd/man3/ttymsg.3 create mode 100644 static/netbsd/man3/ttyname.3 create mode 100644 static/netbsd/man3/tzset.3 create mode 100644 static/netbsd/man3/ualarm.3 create mode 100644 static/netbsd/man3/ukfs.3 create mode 100644 static/netbsd/man3/ulimit.3 create mode 100644 static/netbsd/man3/uname.3 create mode 100644 static/netbsd/man3/ungetc.3 create mode 100644 static/netbsd/man3/ungetwc.3 create mode 100644 static/netbsd/man3/unlockpt.3 create mode 100644 static/netbsd/man3/unvis.3 create mode 100644 static/netbsd/man3/update_panels.3 create mode 100644 static/netbsd/man3/usbhid.3 create mode 100644 static/netbsd/man3/usleep.3 create mode 100644 static/netbsd/man3/util.3 create mode 100644 static/netbsd/man3/util.h.3 create mode 100644 static/netbsd/man3/utime.3 create mode 100644 static/netbsd/man3/uuid.3 create mode 100644 static/netbsd/man3/valloc.3 create mode 100644 static/netbsd/man3/virtdir.3 create mode 100644 static/netbsd/man3/vis.3 create mode 100644 static/netbsd/man3/wcrtomb.3 create mode 100644 static/netbsd/man3/wcscasecmp.3 create mode 100644 static/netbsd/man3/wcscoll.3 create mode 100644 static/netbsd/man3/wcsdup.3 create mode 100644 static/netbsd/man3/wcsftime.3 create mode 100644 static/netbsd/man3/wcsrtombs.3 create mode 100644 static/netbsd/man3/wcstod.3 create mode 100644 static/netbsd/man3/wcstok.3 create mode 100644 static/netbsd/man3/wcstol.3 create mode 100644 static/netbsd/man3/wcstombs.3 create mode 100644 static/netbsd/man3/wcswidth.3 create mode 100644 static/netbsd/man3/wcsxfrm.3 create mode 100644 static/netbsd/man3/wctob.3 create mode 100644 static/netbsd/man3/wctomb.3 create mode 100644 static/netbsd/man3/wctrans.3 create mode 100644 static/netbsd/man3/wctype.3 create mode 100644 static/netbsd/man3/wcwidth.3 create mode 100644 static/netbsd/man3/wind.3 create mode 100644 static/netbsd/man3/wind_profile.3 create mode 100644 static/netbsd/man3/wind_punycode_label_toascii.3 create mode 100644 static/netbsd/man3/wind_stringprep.3 create mode 100644 static/netbsd/man3/wind_ucs2read.3 create mode 100644 static/netbsd/man3/wind_ucs2utf8.3 create mode 100644 static/netbsd/man3/wind_ucs2utf8_length.3 create mode 100644 static/netbsd/man3/wind_ucs2write.3 create mode 100644 static/netbsd/man3/wind_ucs4utf8.3 create mode 100644 static/netbsd/man3/wind_ucs4utf8_length.3 create mode 100644 static/netbsd/man3/wind_utf8ucs2.3 create mode 100644 static/netbsd/man3/wind_utf8ucs2_length.3 create mode 100644 static/netbsd/man3/wind_utf8ucs4.3 create mode 100644 static/netbsd/man3/wind_utf8ucs4_length.3 create mode 100644 static/netbsd/man3/wmemchr.3 create mode 100644 static/netbsd/man3/wordexp.3 create mode 100644 static/netbsd/man3/wprintf.3 create mode 100644 static/netbsd/man3/wscanf.3 create mode 100644 static/netbsd/man3/xdr.3 create mode 100644 static/netbsd/man3/ypclnt.3 create mode 100644 static/netbsd/man3/zlib.3 create mode 100644 static/netbsd/man3/zopen.3 (limited to 'static/netbsd/man3') diff --git a/static/netbsd/man3/ADMISSIONS.3 b/static/netbsd/man3/ADMISSIONS.3 new file mode 100644 index 00000000..69c396f6 --- /dev/null +++ b/static/netbsd/man3/ADMISSIONS.3 @@ -0,0 +1,238 @@ +.\" $NetBSD: ADMISSIONS.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ADMISSIONS 3" +.TH ADMISSIONS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ADMISSIONS, +ADMISSIONS_get0_admissionAuthority, +ADMISSIONS_get0_namingAuthority, +ADMISSIONS_get0_professionInfos, +ADMISSIONS_set0_admissionAuthority, +ADMISSIONS_set0_namingAuthority, +ADMISSIONS_set0_professionInfos, +ADMISSION_SYNTAX, +ADMISSION_SYNTAX_get0_admissionAuthority, +ADMISSION_SYNTAX_get0_contentsOfAdmissions, +ADMISSION_SYNTAX_set0_admissionAuthority, +ADMISSION_SYNTAX_set0_contentsOfAdmissions, +NAMING_AUTHORITY, +NAMING_AUTHORITY_get0_authorityId, +NAMING_AUTHORITY_get0_authorityURL, +NAMING_AUTHORITY_get0_authorityText, +NAMING_AUTHORITY_set0_authorityId, +NAMING_AUTHORITY_set0_authorityURL, +NAMING_AUTHORITY_set0_authorityText, +PROFESSION_INFO, +PROFESSION_INFOS, +PROFESSION_INFO_get0_addProfessionInfo, +PROFESSION_INFO_get0_namingAuthority, +PROFESSION_INFO_get0_professionItems, +PROFESSION_INFO_get0_professionOIDs, +PROFESSION_INFO_get0_registrationNumber, +PROFESSION_INFO_set0_addProfessionInfo, +PROFESSION_INFO_set0_namingAuthority, +PROFESSION_INFO_set0_professionItems, +PROFESSION_INFO_set0_professionOIDs, +PROFESSION_INFO_set0_registrationNumber +\&\- Accessors and settors for ADMISSION_SYNTAX +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 5 +\& typedef struct NamingAuthority_st NAMING_AUTHORITY; +\& typedef struct ProfessionInfo_st PROFESSION_INFO; +\& typedef STACK_OF(PROFESSION_INFO) PROFESSION_INFOS; +\& typedef struct Admissions_st ADMISSIONS; +\& typedef struct AdmissionSyntax_st ADMISSION_SYNTAX; +\& +\& const ASN1_OBJECT *NAMING_AUTHORITY_get0_authorityId( +\& const NAMING_AUTHORITY *n); +\& void NAMING_AUTHORITY_set0_authorityId(NAMING_AUTHORITY *n, +\& ASN1_OBJECT* namingAuthorityId); +\& const ASN1_IA5STRING *NAMING_AUTHORITY_get0_authorityURL( +\& const NAMING_AUTHORITY *n); +\& void NAMING_AUTHORITY_set0_authorityURL(NAMING_AUTHORITY *n, +\& ASN1_IA5STRING* namingAuthorityUrl); +\& const ASN1_STRING *NAMING_AUTHORITY_get0_authorityText( +\& const NAMING_AUTHORITY *n); +\& void NAMING_AUTHORITY_set0_authorityText(NAMING_AUTHORITY *n, +\& ASN1_STRING* namingAuthorityText); +\& +\& const GENERAL_NAME *ADMISSION_SYNTAX_get0_admissionAuthority( +\& const ADMISSION_SYNTAX *as); +\& void ADMISSION_SYNTAX_set0_admissionAuthority( +\& ADMISSION_SYNTAX *as, GENERAL_NAME *aa); +\& const STACK_OF(ADMISSIONS) *ADMISSION_SYNTAX_get0_contentsOfAdmissions( +\& const ADMISSION_SYNTAX *as); +\& void ADMISSION_SYNTAX_set0_contentsOfAdmissions( +\& ADMISSION_SYNTAX *as, STACK_OF(ADMISSIONS) *a); +\& +\& const GENERAL_NAME *ADMISSIONS_get0_admissionAuthority(const ADMISSIONS *a); +\& void ADMISSIONS_set0_admissionAuthority(ADMISSIONS *a, GENERAL_NAME *aa); +\& const NAMING_AUTHORITY *ADMISSIONS_get0_namingAuthority(const ADMISSIONS *a); +\& void ADMISSIONS_set0_namingAuthority(ADMISSIONS *a, NAMING_AUTHORITY *na); +\& const PROFESSION_INFOS *ADMISSIONS_get0_professionInfos(const ADMISSIONS *a); +\& void ADMISSIONS_set0_professionInfos(ADMISSIONS *a, PROFESSION_INFOS *pi); +\& +\& const ASN1_OCTET_STRING *PROFESSION_INFO_get0_addProfessionInfo( +\& const PROFESSION_INFO *pi); +\& void PROFESSION_INFO_set0_addProfessionInfo( +\& PROFESSION_INFO *pi, ASN1_OCTET_STRING *aos); +\& const NAMING_AUTHORITY *PROFESSION_INFO_get0_namingAuthority( +\& const PROFESSION_INFO *pi); +\& void PROFESSION_INFO_set0_namingAuthority( +\& PROFESSION_INFO *pi, NAMING_AUTHORITY *na); +\& const STACK_OF(ASN1_STRING) *PROFESSION_INFO_get0_professionItems( +\& const PROFESSION_INFO *pi); +\& void PROFESSION_INFO_set0_professionItems( +\& PROFESSION_INFO *pi, STACK_OF(ASN1_STRING) *as); +\& const STACK_OF(ASN1_OBJECT) *PROFESSION_INFO_get0_professionOIDs( +\& const PROFESSION_INFO *pi); +\& void PROFESSION_INFO_set0_professionOIDs( +\& PROFESSION_INFO *pi, STACK_OF(ASN1_OBJECT) *po); +\& const ASN1_PRINTABLESTRING *PROFESSION_INFO_get0_registrationNumber( +\& const PROFESSION_INFO *pi); +\& void PROFESSION_INFO_set0_registrationNumber( +\& PROFESSION_INFO *pi, ASN1_PRINTABLESTRING *rn); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBPROFESSION_INFOS\fR, \fBADMISSION_SYNTAX\fR, \fBADMISSIONS\fR, and +\&\fBPROFESSION_INFO\fR types are opaque structures representing the +analogous types defined in the Common PKI Specification published +by T7 & TELETRUST . +Knowledge of those structures and their semantics is assumed. +.PP +The conventional routines to convert between DER and the local format +are described in \fBd2i_X509\fR\|(3). +The conventional routines to allocate and free the types are defined +in \fBX509_dup\fR\|(3). +.PP +The \fBPROFESSION_INFOS\fR type is a stack of \fBPROFESSION_INFO\fR; see +\&\fBDEFINE_STACK_OF\fR\|(3) for details. +.PP +The \fBNAMING_AUTHORITY\fR type has an authority ID and URL, and text fields. +The \fBNAMING_AUTHORITY_get0_authorityId()\fR, +\&\fBNAMING_AUTHORITY_get0_get0_authorityURL()\fR, and +\&\fBNAMING_AUTHORITY_get0_get0_authorityText()\fR, functions return pointers +to those values within the object. +The \fBNAMING_AUTHORITY_set0_authorityId()\fR, +\&\fBNAMING_AUTHORITY_set0_get0_authorityURL()\fR, and +\&\fBNAMING_AUTHORITY_set0_get0_authorityText()\fR, +functions free any existing value and set the pointer to the specified value. +.PP +The \fBADMISSION_SYNTAX\fR type has an authority name and a stack of +\&\fBADMISSION\fR objects. +The \fBADMISSION_SYNTAX_get0_admissionAuthority()\fR +and \fBADMISSION_SYNTAX_get0_contentsOfAdmissions()\fR functions return pointers +to those values within the object. +The +\&\fBADMISSION_SYNTAX_set0_admissionAuthority()\fR and +\&\fBADMISSION_SYNTAX_set0_contentsOfAdmissions()\fR +functions free any existing value and set the pointer to the specified value. +.PP +The \fBADMISSION\fR type has an authority name, authority object, and a +stack of \fBPROFESSION_INFO\fR items. +The \fBADMISSIONS_get0_admissionAuthority()\fR, \fBADMISSIONS_get0_namingAuthority()\fR, +and \fBADMISSIONS_get0_professionInfos()\fR +functions return pointers to those values within the object. +The +\&\fBADMISSIONS_set0_admissionAuthority()\fR, +\&\fBADMISSIONS_set0_namingAuthority()\fR, and +\&\fBADMISSIONS_set0_professionInfos()\fR +functions free any existing value and set the pointer to the specified value. +.PP +The \fBPROFESSION_INFO\fR type has a name authority, stacks of +profession Items and OIDs, a registration number, and additional +profession info. +The functions \fBPROFESSION_INFO_get0_addProfessionInfo()\fR, +\&\fBPROFESSION_INFO_get0_namingAuthority()\fR, \fBPROFESSION_INFO_get0_professionItems()\fR, +\&\fBPROFESSION_INFO_get0_professionOIDs()\fR, and +\&\fBPROFESSION_INFO_get0_registrationNumber()\fR +functions return pointers to those values within the object. +The +\&\fBPROFESSION_INFO_set0_addProfessionInfo()\fR, +\&\fBPROFESSION_INFO_set0_namingAuthority()\fR, +\&\fBPROFESSION_INFO_set0_professionItems()\fR, +\&\fBPROFESSION_INFO_set0_professionOIDs()\fR, and +\&\fBPROFESSION_INFO_set0_registrationNumber()\fR +functions free any existing value and set the pointer to the specified value. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Described above. +Note that all of the \fIget0\fR functions return a pointer to the internal data +structure and must not be freed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_dup\fR\|(3), +\&\fBd2i_X509\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_EXTERN_FUNCS.3 b/static/netbsd/man3/ASN1_EXTERN_FUNCS.3 new file mode 100644 index 00000000..260c4605 --- /dev/null +++ b/static/netbsd/man3/ASN1_EXTERN_FUNCS.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: ASN1_EXTERN_FUNCS.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_EXTERN_FUNCS 3" +.TH ASN1_EXTERN_FUNCS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func, +ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func, +IMPLEMENT_EXTERN_ASN1 +\&\- ASN.1 external function support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len, +\& const ASN1_ITEM *it, int tag, int aclass, char opt, +\& ASN1_TLC *ctx); +\& typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len, +\& const ASN1_ITEM *it, int tag, int aclass, char opt, +\& ASN1_TLC *ctx, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out, +\& const ASN1_ITEM *it, int tag, int aclass); +\& typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it); +\& typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it); +\& typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval, +\& int indent, const char *fname, +\& const ASN1_PCTX *pctx); +\& +\& struct ASN1_EXTERN_FUNCS_st { +\& void *app_data; +\& ASN1_ex_new_func *asn1_ex_new; +\& ASN1_ex_free_func *asn1_ex_free; +\& ASN1_ex_free_func *asn1_ex_clear; +\& ASN1_ex_d2i *asn1_ex_d2i; +\& ASN1_ex_i2d *asn1_ex_i2d; +\& ASN1_ex_print_func *asn1_ex_print; +\& ASN1_ex_new_ex_func *asn1_ex_new_ex; +\& ASN1_ex_d2i_ex *asn1_ex_d2i_ex; +\& }; +\& typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS; +\& +\& #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ASN.1 data structures templates are typically defined in OpenSSL using a series +of macros such as \fBASN1_SEQUENCE()\fR, \fBASN1_SEQUENCE_END()\fR and so on. Instead +templates can also be defined based entirely on external functions. These +external functions are called to perform operations such as creating a new +\&\fBASN1_VALUE\fR or converting an \fBASN1_VALUE\fR to or from DER encoding. +.PP +The macro \fBIMPLEMENT_EXTERN_ASN1()\fR can be used to create such an externally +defined structure. The name of the structure should be supplied in the \fIsname\fR +parameter. The tag for the structure (e.g. typically \fBV_ASN1_SEQUENCE\fR) should +be supplied in the \fItag\fR parameter. Finally a pointer to an +\&\fBASN1_EXTERN_FUNCS\fR structure should be supplied in the \fIfptrs\fR parameter. +.PP +The \fBASN1_EXTERN_FUNCS\fR structure has the following entries. +.IP \fIapp_data\fR 4 +.IX Item "app_data" +A pointer to arbitrary application specific data. +.IP \fIasn1_ex_new\fR 4 +.IX Item "asn1_ex_new" +A "new" function responsible for constructing a new \fBASN1_VALUE\fR object. The +newly constructed value should be stored in \fI*pval\fR. The \fIit\fR parameter is a +pointer to the \fBASN1_ITEM\fR template object created via the +\&\fBIMPLEMENT_EXTERN_ASN1()\fR macro. +.Sp +Returns a positive value on success or 0 on error. +.IP \fIasn1_ex_free\fR 4 +.IX Item "asn1_ex_free" +A "free" function responsible for freeing the \fBASN1_VALUE\fR passed in \fI*pval\fR +that was previously allocated via a "new" function. The \fIit\fR parameter is a +pointer to the \fBASN1_ITEM\fR template object created via the +\&\fBIMPLEMENT_EXTERN_ASN1()\fR macro. +.IP \fIasn1_ex_clear\fR 4 +.IX Item "asn1_ex_clear" +A "clear" function responsible for clearing any data in the \fBASN1_VALUE\fR passed +in \fI*pval\fR and making it suitable for reuse. The \fIit\fR parameter is a pointer +to the \fBASN1_ITEM\fR template object created via the \fBIMPLEMENT_EXTERN_ASN1()\fR +macro. +.IP \fIasn1_ex_d2i\fR 4 +.IX Item "asn1_ex_d2i" +A "d2i" function responsible for converting DER data with the tag \fItag\fR and +class \fIclass\fR into an \fBASN1_VALUE\fR. If \fI*pval\fR is non\-NULL then the +\&\fBASN_VALUE\fR it points to should be reused. Otherwise a new \fBASN1_VALUE\fR +should be allocated and stored in \fI*pval\fR. \fI*in\fR points to the DER data to be +decoded and \fIlen\fR is the length of that data. After decoding \fI*in\fR should be +updated to point at the next byte after the decoded data. If the \fBASN1_VALUE\fR +is considered optional in this context then \fIopt\fR will be nonzero. Otherwise +it will be zero. The \fIit\fR parameter is a pointer to the \fBASN1_ITEM\fR template +object created via the \fBIMPLEMENT_EXTERN_ASN1()\fR macro. A pointer to the current +\&\fBASN1_TLC\fR context (which may be required for other ASN1 function calls) is +passed in the \fIctx\fR parameter. +.Sp +The \fIasn1_ex_d2i\fR entry may be NULL if \fIasn1_ex_d2i_ex\fR has been specified +instead. +.Sp +Returns <= 0 on error or a positive value on success. +.IP \fIasn1_ex_i2d\fR 4 +.IX Item "asn1_ex_i2d" +An "i2d" function responsible for converting an \fBASN1_VALUE\fR into DER encoding. +On entry \fI*pval\fR will contain the \fBASN1_VALUE\fR to be encoded. If default +tagging is to be used then \fItag\fR will be \-1 on entry. Otherwise if implicit +tagging should be used then \fItag\fR and \fIaclass\fR will be the tag and associated +class. +.Sp +If \fIout\fR is not NULL then this function should write the DER encoded data to +the buffer in \fI*out\fR, and then increment \fI*out\fR to point to immediately after +the data just written. +.Sp +If \fIout\fR is NULL then no data should be written but the length calculated and +returned as if it were. +.Sp +The \fIasn1_ex_i2d\fR entry may be NULL if \fIasn1_ex_i2d_ex\fR has been specified +instead. +.Sp +The return value should be negative if a fatal error occurred, or 0 if a +non\-fatal error occurred. Otherwise it should return the length of the encoded +data. +.IP \fIasn1_ex_print\fR 4 +.IX Item "asn1_ex_print" +A "print" function. \fIout\fR is the BIO to print the output to. \fI*pval\fR is the +\&\fBASN1_VALUE\fR to be printed. \fIindent\fR is the number of spaces of indenting to +be printed before any data is printed. \fIfname\fR is currently unused and is +always "". \fIpctx\fR is a pointer to the \fBASN1_PCTX\fR for the print operation. +.Sp +Returns 0 on error or a positive value on success. If the return value is 2 then +an additional newline will be printed after the data printed by this function. +.IP \fIasn1_ex_new_ex\fR 4 +.IX Item "asn1_ex_new_ex" +This is the same as \fIasn1_ex_new\fR except that it is additionally passed the +OSSL_LIB_CTX to be used in \fIlibctx\fR and any property query string to be used +for algorithm fetching in the \fIpropq\fR parameter. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_new_ex\fR is +non NULL, then it will always be called in preference to \fIasn1_ex_new\fR. +.IP \fIasn1_ex_d2i_ex\fR 4 +.IX Item "asn1_ex_d2i_ex" +This is the same as \fIasn1_ex_d2i\fR except that it is additionally passed the +OSSL_LIB_CTX to be used in \fIlibctx\fR and any property query string to be used +for algorithm fetching in the \fIpropq\fR parameter. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further details. If \fIasn1_ex_d2i_ex\fR is +non NULL, then it will always be called in preference to \fIasn1_ex_d2i\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Return values for the various callbacks are as described above. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_item_new_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fIasn1_ex_new_ex\fR and \fIasn1_ex_d2i_ex\fR callbacks were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_INTEGER_get_int64.3 b/static/netbsd/man3/ASN1_INTEGER_get_int64.3 new file mode 100644 index 00000000..314af840 --- /dev/null +++ b/static/netbsd/man3/ASN1_INTEGER_get_int64.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: ASN1_INTEGER_get_int64.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_INTEGER_get_int64 3" +.TH ASN1_INTEGER_get_int64 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, +ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN +\&\- ASN.1 INTEGER and ENUMERATED utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a); +\& long ASN1_INTEGER_get(const ASN1_INTEGER *a); +\& +\& int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r); +\& int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); +\& +\& int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a); +\& int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r); +\& +\& ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai); +\& BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn); +\& +\& int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a); +\& long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a); +\& +\& int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r); +\& int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v); +\& +\& ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai); +\& BIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions convert to and from \fBASN1_INTEGER\fR and \fBASN1_ENUMERATED\fR +structures. +.PP +\&\fBASN1_INTEGER_get_int64()\fR converts an \fBASN1_INTEGER\fR into an \fBint64_t\fR type +If successful it returns 1 and sets \fI*pr\fR to the value of \fIa\fR. If it fails +(due to invalid type or the value being too big to fit into an \fBint64_t\fR type) +it returns 0. +.PP +\&\fBASN1_INTEGER_get_uint64()\fR is similar to \fBASN1_INTEGER_get_int64_t()\fR except it +converts to a \fBuint64_t\fR type and an error is returned if the passed integer +is negative. +.PP +\&\fBASN1_INTEGER_get()\fR also returns the value of \fIa\fR but it returns 0 if \fIa\fR is +NULL and \-1 on error (which is ambiguous because \-1 is a legitimate value for +an \fBASN1_INTEGER\fR). New applications should use \fBASN1_INTEGER_get_int64()\fR +instead. +.PP +\&\fBASN1_INTEGER_set_int64()\fR sets the value of \fBASN1_INTEGER\fR \fIa\fR to the +\&\fBint64_t\fR value \fIr\fR. +.PP +\&\fBASN1_INTEGER_set_uint64()\fR sets the value of \fBASN1_INTEGER\fR \fIa\fR to the +\&\fBuint64_t\fR value \fIr\fR. +.PP +\&\fBASN1_INTEGER_set()\fR sets the value of \fBASN1_INTEGER\fR \fIa\fR to the \fIlong\fR value +\&\fIv\fR. +.PP +\&\fBBN_to_ASN1_INTEGER()\fR converts \fBBIGNUM\fR \fIbn\fR to an \fBASN1_INTEGER\fR. If \fIai\fR +is NULL a new \fBASN1_INTEGER\fR structure is returned. If \fIai\fR is not NULL then +the existing structure will be used instead. +.PP +\&\fBASN1_INTEGER_to_BN()\fR converts ASN1_INTEGER \fIai\fR into a \fBBIGNUM\fR. If \fIbn\fR is +NULL a new \fBBIGNUM\fR structure is returned. If \fIbn\fR is not NULL then the +existing structure will be used instead. +.PP +\&\fBASN1_ENUMERATED_get_int64()\fR, \fBASN1_ENUMERATED_set_int64()\fR, +\&\fBASN1_ENUMERATED_set()\fR, \fBBN_to_ASN1_ENUMERATED()\fR and \fBASN1_ENUMERATED_to_BN()\fR +behave in an identical way to their ASN1_INTEGER counterparts except they +operate on an \fBASN1_ENUMERATED\fR value. +.PP +\&\fBASN1_ENUMERATED_get()\fR returns the value of \fIa\fR in a similar way to +\&\fBASN1_INTEGER_get()\fR but it returns \fB0xffffffffL\fR if the value of \fIa\fR will not +fit in a long type. New applications should use \fBASN1_ENUMERATED_get_int64()\fR +instead. +.SH NOTES +.IX Header "NOTES" +In general an \fBASN1_INTEGER\fR or \fBASN1_ENUMERATED\fR type can contain an +integer of almost arbitrary size and so cannot always be represented by a C +\&\fBint64_t\fR type. However, in many cases (for example version numbers) they +represent small integers which can be more easily manipulated if converted to +an appropriate C integer type. +.SH BUGS +.IX Header "BUGS" +The ambiguous return values of \fBASN1_INTEGER_get()\fR and \fBASN1_ENUMERATED_get()\fR +mean these functions should be avoided if possible. They are retained for +compatibility. Normally the ambiguous return values are not legitimate +values for the fields they represent. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_INTEGER_set_int64()\fR, \fBASN1_INTEGER_set()\fR, \fBASN1_ENUMERATED_set_int64()\fR and +\&\fBASN1_ENUMERATED_set()\fR return 1 for success and 0 for failure. They will only +fail if a memory allocation error occurs. +.PP +\&\fBASN1_INTEGER_get_int64()\fR and \fBASN1_ENUMERATED_get_int64()\fR return 1 for success +and 0 for failure. They will fail if the passed type is incorrect (this will +only happen if there is a programming error) or if the value exceeds the range +of an \fBint64_t\fR type. +.PP +\&\fBBN_to_ASN1_INTEGER()\fR and \fBBN_to_ASN1_ENUMERATED()\fR return an \fBASN1_INTEGER\fR or +\&\fBASN1_ENUMERATED\fR structure respectively or NULL if an error occurs. They will +only fail due to a memory allocation error. +.PP +\&\fBASN1_INTEGER_to_BN()\fR and \fBASN1_ENUMERATED_to_BN()\fR return a \fBBIGNUM\fR structure +of NULL if an error occurs. They can fail if the passed type is incorrect +(due to programming error) or due to a memory allocation failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBASN1_INTEGER_set_int64()\fR, \fBASN1_INTEGER_get_int64()\fR, +\&\fBASN1_ENUMERATED_set_int64()\fR and \fBASN1_ENUMERATED_get_int64()\fR +were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_INTEGER_new.3 b/static/netbsd/man3/ASN1_INTEGER_new.3 new file mode 100644 index 00000000..6fd0e1b5 --- /dev/null +++ b/static/netbsd/man3/ASN1_INTEGER_new.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: ASN1_INTEGER_new.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_INTEGER_new 3" +.TH ASN1_INTEGER_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_INTEGER_new, ASN1_INTEGER_free \- ASN1_INTEGER allocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_INTEGER *ASN1_INTEGER_new(void); +\& void ASN1_INTEGER_free(ASN1_INTEGER *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_INTEGER_new()\fR returns an allocated \fBASN1_INTEGER\fR structure. +.PP +\&\fBASN1_INTEGER_free()\fR frees up a single \fBASN1_INTEGER\fR object. +If the argument is NULL, nothing is done. +.PP +\&\fBASN1_INTEGER\fR structure representing the ASN.1 INTEGER type +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_INTEGER_new()\fR return a valid \fBASN1_INTEGER\fR structure or NULL +if an error occurred. +.PP +\&\fBASN1_INTEGER_free()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_ITEM_lookup.3 b/static/netbsd/man3/ASN1_ITEM_lookup.3 new file mode 100644 index 00000000..43db86e5 --- /dev/null +++ b/static/netbsd/man3/ASN1_ITEM_lookup.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: ASN1_ITEM_lookup.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_ITEM_lookup 3" +.TH ASN1_ITEM_lookup 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_ITEM_lookup, ASN1_ITEM_get \- lookup ASN.1 structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const ASN1_ITEM *ASN1_ITEM_lookup(const char *name); +\& const ASN1_ITEM *ASN1_ITEM_get(size_t i); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_ITEM_lookup()\fR returns the \fBASN1_ITEM\fR named \fIname\fR. +.PP +\&\fBASN1_ITEM_get()\fR returns the \fBASN1_ITEM\fR with index \fIi\fR. This function +returns NULL if the index \fIi\fR is out of range. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_ITEM_lookup()\fR and \fBASN1_ITEM_get()\fR return a valid \fBASN1_ITEM\fR structure +or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_OBJECT_new.3 b/static/netbsd/man3/ASN1_OBJECT_new.3 new file mode 100644 index 00000000..355a00a5 --- /dev/null +++ b/static/netbsd/man3/ASN1_OBJECT_new.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: ASN1_OBJECT_new.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_OBJECT_new 3" +.TH ASN1_OBJECT_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_OBJECT_new, ASN1_OBJECT_free \- object allocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OBJECT *ASN1_OBJECT_new(void); +\& void ASN1_OBJECT_free(ASN1_OBJECT *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBASN1_OBJECT\fR allocation routines, allocate and free an +\&\fBASN1_OBJECT\fR structure, which represents an ASN1 OBJECT IDENTIFIER. +.PP +\&\fBASN1_OBJECT_new()\fR allocates and initializes an \fBASN1_OBJECT\fR structure. +.PP +\&\fBASN1_OBJECT_free()\fR frees up the \fBASN1_OBJECT\fR structure \fIa\fR. +If \fIa\fR is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +Although \fBASN1_OBJECT_new()\fR allocates a new \fBASN1_OBJECT\fR structure it +is almost never used in applications. The ASN1 object utility functions +such as \fBOBJ_nid2obj()\fR are used instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBASN1_OBJECT_new()\fR returns NULL and sets an error +code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise it returns a pointer to the newly allocated structure. +.PP +\&\fBASN1_OBJECT_free()\fR returns no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBd2i_ASN1_OBJECT\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_STRING_TABLE_add.3 b/static/netbsd/man3/ASN1_STRING_TABLE_add.3 new file mode 100644 index 00000000..dc865ae1 --- /dev/null +++ b/static/netbsd/man3/ASN1_STRING_TABLE_add.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: ASN1_STRING_TABLE_add.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_STRING_TABLE_add 3" +.TH ASN1_STRING_TABLE_add 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get, +ASN1_STRING_TABLE_cleanup \- ASN1_STRING_TABLE manipulation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct asn1_string_table_st ASN1_STRING_TABLE; +\& +\& int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize, +\& unsigned long mask, unsigned long flags); +\& ASN1_STRING_TABLE *ASN1_STRING_TABLE_get(int nid); +\& void ASN1_STRING_TABLE_cleanup(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS Types +.IX Subsection "Types" +\&\fBASN1_STRING_TABLE\fR is a table which holds string information +(basically minimum size, maximum size, type and etc) for a NID object. +.SS Functions +.IX Subsection "Functions" +\&\fBASN1_STRING_TABLE_add()\fR adds a new \fBASN1_STRING_TABLE\fR item into the +local ASN1 string table based on the \fInid\fR along with other parameters. +.PP +If the item is already in the table, fields of \fBASN1_STRING_TABLE\fR are +updated (depending on the values of those parameters, e.g., \fIminsize\fR +and \fImaxsize\fR >= 0, \fImask\fR and \fIflags\fR != 0). If the \fInid\fR is standard, +a copy of the standard \fBASN1_STRING_TABLE\fR is created and updated with +other parameters. +.PP +\&\fBASN1_STRING_TABLE_get()\fR searches for an \fBASN1_STRING_TABLE\fR item based +on \fInid\fR. It will search the local table first, then the standard one. +.PP +\&\fBASN1_STRING_TABLE_cleanup()\fR frees all \fBASN1_STRING_TABLE\fR items added +by \fBASN1_STRING_TABLE_add()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_STRING_TABLE_add()\fR returns 1 on success, 0 if an error occurred. +.PP +\&\fBASN1_STRING_TABLE_get()\fR returns a valid \fBASN1_STRING_TABLE\fR structure +or NULL if nothing is found. +.PP +\&\fBASN1_STRING_TABLE_cleanup()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_STRING_length.3 b/static/netbsd/man3/ASN1_STRING_length.3 new file mode 100644 index 00000000..4853328f --- /dev/null +++ b/static/netbsd/man3/ASN1_STRING_length.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: ASN1_STRING_length.3,v 1.5 2026/04/08 17:06:40 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_STRING_length 3" +.TH ASN1_STRING_length 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, +ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, +ASN1_STRING_to_UTF8 \- ASN1_STRING utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASN1_STRING_length(ASN1_STRING *x); +\& const unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x); +\& unsigned char *ASN1_STRING_data(ASN1_STRING *x); +\& +\& ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a); +\& +\& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); +\& +\& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); +\& +\& int ASN1_STRING_type(const ASN1_STRING *x); +\& +\& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions allow an \fBASN1_STRING\fR structure to be manipulated. +.PP +\&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR. \fIx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fIx\fR. +Since this is an internal pointer it should \fBnot\fR be freed or +modified in any way. \fIx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBASN1_STRING_data()\fR is similar to \fBASN1_STRING_get0_data()\fR except the +returned value is not constant. This function is deprecated: +applications should use \fBASN1_STRING_get0_data()\fR instead. +.PP +\&\fBASN1_STRING_dup()\fR returns a copy of the structure \fIa\fR. +.PP +\&\fBASN1_STRING_cmp()\fR compares \fIa\fR and \fIb\fR returning 0 if the two +are identical. The string types and content are compared. +.PP +\&\fBASN1_STRING_set()\fR sets the data of string \fIstr\fR to the buffer +\&\fIdata\fR or length \fIlen\fR. The supplied data is copied. If \fIlen\fR +is \-1 then the length is determined by strlen(data). +.PP +\&\fBASN1_STRING_type()\fR returns the type of \fIx\fR, using standard constants +such as \fBV_ASN1_OCTET_STRING\fR. +.PP +\&\fBASN1_STRING_to_UTF8()\fR converts the string \fIin\fR to UTF8 format, the +converted data is allocated in a buffer in \fI*out\fR. The length of +\&\fIout\fR is returned or a negative error code. The buffer \fI*out\fR +should be freed using \fBOPENSSL_free()\fR. +.SH NOTES +.IX Header "NOTES" +Almost all ASN1 types in OpenSSL are represented as an \fBASN1_STRING\fR +structure. Other types such as \fBASN1_OCTET_STRING\fR are simply typedef\*(Aqed +to \fBASN1_STRING\fR and the functions call the \fBASN1_STRING\fR equivalents. +\&\fBASN1_STRING\fR is also used for some \fBCHOICE\fR types which consist +entirely of primitive string types such as \fBDirectoryString\fR and +\&\fBTime\fR. +.PP +These functions should \fBnot\fR be used to examine or modify \fBASN1_INTEGER\fR +or \fBASN1_ENUMERATED\fR types: the relevant \fBINTEGER\fR or \fBENUMERATED\fR +utility functions should be used instead. +.PP +In general it cannot be assumed that the data returned by \fBASN1_STRING_data()\fR +is null terminated or does not contain embedded nulls. The actual format +of the data will depend on the actual string type itself: for example +for an IA5String the data will be ASCII, for a BMPString two bytes per +character in big endian format, and for a UTF8String it will be in UTF8 format. +.PP +Similar care should be take to ensure the data is in the correct format +when calling \fBASN1_STRING_set()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_STRING_length()\fR returns the length of the content of \fIx\fR. +.PP +\&\fBASN1_STRING_get0_data()\fR and \fBASN1_STRING_data()\fR return an internal pointer to +the data of \fIx\fR. +.PP +\&\fBASN1_STRING_dup()\fR returns a valid \fBASN1_STRING\fR structure or NULL if an +error occurred. +.PP +\&\fBASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0, +according to whether \fIa\fR is greater than, equal to, or less than \fIb\fR. +.PP +\&\fBASN1_STRING_set()\fR returns 1 on success or 0 on error. +.PP +\&\fBASN1_STRING_type()\fR returns the type of \fIx\fR. +.PP +\&\fBASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fIout\fR or a +negative value if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_STRING_new.3 b/static/netbsd/man3/ASN1_STRING_new.3 new file mode 100644 index 00000000..6b5a4ef6 --- /dev/null +++ b/static/netbsd/man3/ASN1_STRING_new.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: ASN1_STRING_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_STRING_new 3" +.TH ASN1_STRING_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free \- +ASN1_STRING allocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_STRING *ASN1_STRING_new(void); +\& ASN1_STRING *ASN1_STRING_type_new(int type); +\& void ASN1_STRING_free(ASN1_STRING *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_STRING_new()\fR returns an allocated \fBASN1_STRING\fR structure. Its type +is undefined. +.PP +\&\fBASN1_STRING_type_new()\fR returns an allocated \fBASN1_STRING\fR structure of +type \fItype\fR. +.PP +\&\fBASN1_STRING_free()\fR frees up \fIa\fR. +If \fIa\fR is NULL nothing is done. +.SH NOTES +.IX Header "NOTES" +Other string types call the \fBASN1_STRING\fR functions. For example +\&\fBASN1_OCTET_STRING_new()\fR calls ASN1_STRING_type_new(V_ASN1_OCTET_STRING). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_STRING_new()\fR and \fBASN1_STRING_type_new()\fR return a valid +\&\fBASN1_STRING\fR structure or NULL if an error occurred. +.PP +\&\fBASN1_STRING_free()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_STRING_print_ex.3 b/static/netbsd/man3/ASN1_STRING_print_ex.3 new file mode 100644 index 00000000..44fb1818 --- /dev/null +++ b/static/netbsd/man3/ASN1_STRING_print_ex.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: ASN1_STRING_print_ex.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_STRING_print_ex 3" +.TH ASN1_STRING_print_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print +\&\- ASN1_STRING output routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags); +\& int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags); +\& int ASN1_STRING_print(BIO *out, const ASN1_STRING *str); +\& +\& const char *ASN1_tag2str(int tag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions output an \fBASN1_STRING\fR structure. \fBASN1_STRING\fR is used to +represent all the ASN1 string types. +.PP +\&\fBASN1_STRING_print_ex()\fR outputs \fIstr\fR to \fIout\fR, the format is determined by +the options \fIflags\fR. \fBASN1_STRING_print_ex_fp()\fR is identical except it outputs +to \fIfp\fR instead. +.PP +\&\fBASN1_STRING_print()\fR prints \fIstr\fR to \fIout\fR but using a different format to +\&\fBASN1_STRING_print_ex()\fR. It replaces unprintable characters (other than CR, LF) +with \*(Aq.\*(Aq. +.PP +\&\fBASN1_tag2str()\fR returns a human\-readable name of the specified ASN.1 \fItag\fR. +.SH NOTES +.IX Header "NOTES" +\&\fBASN1_STRING_print()\fR is a deprecated function which should be avoided; use +\&\fBASN1_STRING_print_ex()\fR instead. +.PP +Although there are a large number of options frequently \fBASN1_STRFLGS_RFC2253\fR is +suitable, or on UTF8 terminals \fBASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB\fR. +.PP +The complete set of supported options for \fIflags\fR is listed below. +.PP +Various characters can be escaped. If \fBASN1_STRFLGS_ESC_2253\fR is set the characters +determined by RFC2253 are escaped. If \fBASN1_STRFLGS_ESC_CTRL\fR is set control +characters are escaped. If \fBASN1_STRFLGS_ESC_MSB\fR is set characters with the +MSB set are escaped: this option should \fBnot\fR be used if the terminal correctly +interprets UTF8 sequences. +.PP +Escaping takes several forms. +.PP +If the character being escaped is a 16 bit character then the form "\eUXXXX" is used +using exactly four characters for the hex representation. If it is 32 bits then +"\eWXXXXXXXX" is used using eight characters of its hex representation. These forms +will only be used if UTF8 conversion is not set (see below). +.PP +Printable characters are normally escaped using the backslash \*(Aq\e\*(Aq character. If +\&\fBASN1_STRFLGS_ESC_QUOTE\fR is set then the whole string is instead surrounded by +double quote characters: this is arguably more readable than the backslash +notation. Other characters use the "\eXX" using exactly two characters of the hex +representation. +.PP +If \fBASN1_STRFLGS_UTF8_CONVERT\fR is set then characters are converted to UTF8 +format first. If the terminal supports the display of UTF8 sequences then this +option will correctly display multi byte characters. +.PP +If \fBASN1_STRFLGS_IGNORE_TYPE\fR is set then the string type is not interpreted at +all: everything is assumed to be one byte per character. This is primarily for +debugging purposes and can result in confusing output in multi character strings. +.PP +If \fBASN1_STRFLGS_SHOW_TYPE\fR is set then the string type itself is printed out +before its value (for example "BMPSTRING"), this actually uses \fBASN1_tag2str()\fR. +.PP +The content of a string instead of being interpreted can be "dumped": this just +outputs the value of the string using the form #XXXX using hex format for each +octet. +.PP +If \fBASN1_STRFLGS_DUMP_ALL\fR is set then any type is dumped. +.PP +Normally non character string types (such as OCTET STRING) are assumed to be +one byte per character, if \fBASN1_STRFLGS_DUMP_UNKNOWN\fR is set then they will +be dumped instead. +.PP +When a type is dumped normally just the content octets are printed, if +\&\fBASN1_STRFLGS_DUMP_DER\fR is set then the complete encoding is dumped +instead (including tag and length octets). +.PP +\&\fBASN1_STRFLGS_RFC2253\fR includes all the flags required by RFC2253. It is +equivalent to: + ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | + ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_STRING_print_ex()\fR and \fBASN1_STRING_print_ex_fp()\fR return the number of +characters written or \-1 if an error occurred. +.PP +\&\fBASN1_STRING_print()\fR returns 1 on success or 0 on error. +.PP +\&\fBASN1_tag2str()\fR returns a human\-readable name of the specified ASN.1 \fItag\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBASN1_tag2str\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_TIME_set.3 b/static/netbsd/man3/ASN1_TIME_set.3 new file mode 100644 index 00000000..8e38b6a4 --- /dev/null +++ b/static/netbsd/man3/ASN1_TIME_set.3 @@ -0,0 +1,346 @@ +.\" $NetBSD: ASN1_TIME_set.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_TIME_set 3" +.TH ASN1_TIME_set 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, +ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, +ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, +ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, +ASN1_TIME_set_string_X509, +ASN1_TIME_normalize, +ASN1_TIME_to_tm, +ASN1_TIME_print, ASN1_TIME_print_ex, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, +ASN1_TIME_diff, +ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, +ASN1_TIME_compare, +ASN1_TIME_to_generalizedtime, +ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup \- ASN.1 Time functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 4 +\& ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); +\& ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t); +\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s, +\& time_t t); +\& +\& ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day, +\& long offset_sec); +\& ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t, +\& int offset_day, long offset_sec); +\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s, +\& time_t t, int offset_day, +\& long offset_sec); +\& +\& int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); +\& int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str); +\& int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str); +\& int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s, +\& const char *str); +\& +\& int ASN1_TIME_normalize(ASN1_TIME *s); +\& +\& int ASN1_TIME_check(const ASN1_TIME *t); +\& int ASN1_UTCTIME_check(const ASN1_UTCTIME *t); +\& int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t); +\& +\& int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); +\& int ASN1_TIME_print_ex(BIO *bp, const ASN1_TIME *tm, unsigned long flags); +\& int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s); +\& int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s); +\& +\& int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm); +\& int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from, +\& const ASN1_TIME *to); +\& +\& int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t); +\& int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t); +\& +\& int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b); +\& +\& ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t, +\& ASN1_GENERALIZEDTIME **out); +\& +\& ASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t); +\& ASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t); +\& ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBASN1_TIME_set()\fR, \fBASN1_UTCTIME_set()\fR and \fBASN1_GENERALIZEDTIME_set()\fR +functions set the structure \fIs\fR to the time represented by the time_t +value \fIt\fR. If \fIs\fR is NULL a new time structure is allocated and returned. +.PP +The \fBASN1_TIME_adj()\fR, \fBASN1_UTCTIME_adj()\fR and \fBASN1_GENERALIZEDTIME_adj()\fR +functions set the time structure \fIs\fR to the time represented +by the time \fIoffset_day\fR and \fIoffset_sec\fR after the time_t value \fIt\fR. +The values of \fIoffset_day\fR or \fIoffset_sec\fR can be negative to set a +time before \fIt\fR. The \fIoffset_sec\fR value can also exceed the number of +seconds in a day. If \fIs\fR is NULL a new structure is allocated +and returned. +.PP +The \fBASN1_TIME_set_string()\fR, \fBASN1_UTCTIME_set_string()\fR and +\&\fBASN1_GENERALIZEDTIME_set_string()\fR functions set the time structure \fIs\fR +to the time represented by string \fIstr\fR which must be in appropriate ASN.1 +time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If \fIs\fR is NULL +this function performs a format check on \fIstr\fR only. The string \fIstr\fR +is copied into \fIs\fR. +.PP +\&\fBASN1_TIME_set_string_X509()\fR sets \fBASN1_TIME\fR structure \fIs\fR to the time +represented by string \fIstr\fR which must be in appropriate time format +that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and +YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format +are not allowed. If \fIs\fR is NULL this function performs a format check +on \fIstr\fR only. +.PP +The \fBASN1_TIME_normalize()\fR function converts an \fBASN1_GENERALIZEDTIME\fR or +\&\fBASN1_UTCTIME\fR into a time value that can be used in a certificate. It +should be used after the \fBASN1_TIME_set_string()\fR functions and before +\&\fBASN1_TIME_print()\fR functions to get consistent (i.e. GMT) results. +.PP +The \fBASN1_TIME_check()\fR, \fBASN1_UTCTIME_check()\fR and \fBASN1_GENERALIZEDTIME_check()\fR +functions check the syntax of the time structure \fIs\fR. +.PP +The \fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR +functions print the time structure \fIs\fR to BIO \fIb\fR in human readable +format. It will be of the format MMM DD HH:MM:SS[.s*] YYYY GMT, for example +"Feb 3 00:55:52 2015 GMT", which does not include a newline. +If the time structure has invalid format it prints out "Bad time value" and +returns an error. The output for generalized time may include a fractional part +following the second. +.PP +\&\fBASN1_TIME_print_ex()\fR provides \fIflags\fR to specify the output format of the +datetime. This can be either \fBASN1_DTFLGS_RFC822\fR or \fBASN1_DTFLGS_ISO8601\fR. +.PP +\&\fBASN1_TIME_to_tm()\fR converts the time \fIs\fR to the standard \fItm\fR structure. +If \fIs\fR is NULL, then the current time is converted. The output time is GMT. +The \fItm_sec\fR, \fItm_min\fR, \fItm_hour\fR, \fItm_mday\fR, \fItm_wday\fR, \fItm_yday\fR, +\&\fItm_mon\fR and \fItm_year\fR fields of \fItm\fR structure are set to proper values, +whereas all other fields are set to 0. If \fItm\fR is NULL this function performs +a format check on \fIs\fR only. If \fIs\fR is in Generalized format with fractional +seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while +converting \fIs\fR to \fItm\fR structure. +.PP +\&\fBASN1_TIME_diff()\fR sets \fI*pday\fR and \fI*psec\fR to the time difference between +\&\fIfrom\fR and \fIto\fR. If \fIto\fR represents a time later than \fIfrom\fR then +one or both (depending on the time difference) of \fI*pday\fR and \fI*psec\fR +will be positive. If \fIto\fR represents a time earlier than \fIfrom\fR then +one or both of \fI*pday\fR and \fI*psec\fR will be negative. If \fIto\fR and \fIfrom\fR +represent the same time then \fI*pday\fR and \fI*psec\fR will both be zero. +If both \fI*pday\fR and \fI*psec\fR are nonzero they will always have the same +sign. The value of \fI*psec\fR will always be less than the number of seconds +in a day. If \fIfrom\fR or \fIto\fR is NULL the current time is used. +.PP +The \fBASN1_TIME_cmp_time_t()\fR and \fBASN1_UTCTIME_cmp_time_t()\fR functions compare +the two times represented by the time structure \fIs\fR and the time_t \fIt\fR. +.PP +The \fBASN1_TIME_compare()\fR function compares the two times represented by the +time structures \fIa\fR and \fIb\fR. +.PP +The \fBASN1_TIME_to_generalizedtime()\fR function converts an \fBASN1_TIME\fR to an +\&\fBASN1_GENERALIZEDTIME\fR, regardless of year. If either \fIout\fR or +\&\fI*out\fR are NULL, then a new object is allocated and must be freed after use. +.PP +The \fBASN1_TIME_dup()\fR, \fBASN1_UTCTIME_dup()\fR and \fBASN1_GENERALIZEDTIME_dup()\fR functions +duplicate the time structure \fIt\fR and return the duplicated result +correspondingly. +.SH NOTES +.IX Header "NOTES" +The \fBASN1_TIME\fR structure corresponds to the ASN.1 structure \fBTime\fR +defined in RFC5280 et al. The time setting functions obey the rules outlined +in RFC5280: if the date can be represented by UTCTime it is used, else +GeneralizedTime is used. +.PP +The \fBASN1_TIME\fR, \fBASN1_UTCTIME\fR and \fBASN1_GENERALIZEDTIME\fR structures are +represented as an \fBASN1_STRING\fR internally and can be freed up using +\&\fBASN1_STRING_free()\fR. +.PP +The \fBASN1_TIME\fR structure can represent years from 0000 to 9999 but no attempt +is made to correct ancient calendar changes (for example from Julian to +Gregorian calendars). +.PP +\&\fBASN1_UTCTIME\fR is limited to a year range of 1950 through 2049. +.PP +Some applications add offset times directly to a time_t value and pass the +results to \fBASN1_TIME_set()\fR (or equivalent). This can cause problems as the +time_t value can overflow on some systems resulting in unexpected results. +New applications should use \fBASN1_TIME_adj()\fR instead and pass the offset value +in the \fIoffset_sec\fR and \fIoffset_day\fR parameters instead of directly +manipulating a time_t value. +.PP +\&\fBASN1_TIME_adj()\fR may change the type from \fBASN1_GENERALIZEDTIME\fR to +\&\fBASN1_UTCTIME\fR, or vice versa, based on the resulting year. +\&\fBASN1_GENERALIZEDTIME_adj()\fR and \fBASN1_UTCTIME_adj()\fR will not modify the type +of the return structure. +.PP +It is recommended that functions starting with \fBASN1_TIME\fR be used instead of +those starting with \fBASN1_UTCTIME\fR or \fBASN1_GENERALIZEDTIME\fR. The functions +starting with \fBASN1_UTCTIME\fR and \fBASN1_GENERALIZEDTIME\fR act only on that +specific time format. The functions starting with \fBASN1_TIME\fR will operate on +either format. +.PP +Users familiar with RFC822 should note that when specifying the flag +\&\fBASN1_DTFLGS_RFC822\fR the year will be formatted as documented above, +i.e., using 4 digits, not 2 as specified in RFC822. +.SH BUGS +.IX Header "BUGS" +\&\fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR do +not print out the timezone: it either prints out "GMT" or nothing. But all +certificates complying with RFC5280 et al use GMT anyway. +.PP +\&\fBASN1_TIME_print()\fR, \fBASN1_TIME_print_ex()\fR, \fBASN1_UTCTIME_print()\fR and +\&\fBASN1_GENERALIZEDTIME_print()\fR do not distinguish if they fail because +of an I/O error or invalid time format. +.PP +Use the \fBASN1_TIME_normalize()\fR function to normalize the time value before +printing to get GMT results. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_TIME_set()\fR, \fBASN1_UTCTIME_set()\fR, \fBASN1_GENERALIZEDTIME_set()\fR, +\&\fBASN1_TIME_adj()\fR, \fBASN1_UTCTIME_adj()\fR and \fBASN1_GENERALIZEDTIME_set()\fR return +a pointer to a time structure or NULL if an error occurred. +.PP +\&\fBASN1_TIME_set_string()\fR, \fBASN1_UTCTIME_set_string()\fR, +\&\fBASN1_GENERALIZEDTIME_set_string()\fR and \fBASN1_TIME_set_string_X509()\fR return +1 if the time value is successfully set and 0 otherwise. +.PP +\&\fBASN1_TIME_normalize()\fR returns 1 on success, and 0 on error. +.PP +\&\fBASN1_TIME_check()\fR, ASN1_UTCTIME_check and \fBASN1_GENERALIZEDTIME_check()\fR return 1 +if the structure is syntactically correct and 0 otherwise. +.PP +\&\fBASN1_TIME_print()\fR, \fBASN1_UTCTIME_print()\fR and \fBASN1_GENERALIZEDTIME_print()\fR +return 1 if the time is successfully printed out and +0 if an I/O error occurred an error occurred (I/O error or invalid time format). +.PP +\&\fBASN1_TIME_to_tm()\fR returns 1 if the time is successfully parsed and 0 if an +error occurred (invalid time format). +.PP +\&\fBASN1_TIME_diff()\fR returns 1 for success and 0 for failure. It can fail if the +passed\-in time structure has invalid syntax, for example. +.PP +\&\fBASN1_TIME_cmp_time_t()\fR and \fBASN1_UTCTIME_cmp_time_t()\fR return \-1 if \fIs\fR is +before \fIt\fR, 0 if \fIs\fR equals \fIt\fR, or 1 if \fIs\fR is after \fIt\fR. \-2 is returned +on error. +.PP +\&\fBASN1_TIME_compare()\fR returns \-1 if \fIa\fR is before \fIb\fR, 0 if \fIa\fR equals \fIb\fR, +or 1 if \fIa\fR is after \fIb\fR. \-2 is returned on error. +.PP +\&\fBASN1_TIME_to_generalizedtime()\fR returns a pointer to the appropriate time +structure on success or NULL if an error occurred. +.PP +\&\fBASN1_TIME_dup()\fR, \fBASN1_UTCTIME_dup()\fR and \fBASN1_GENERALIZEDTIME_dup()\fR return a +pointer to a time structure or NULL if an error occurred. +.SH EXAMPLES +.IX Header "EXAMPLES" +Set a time structure to one hour after the current time and print it out: +.PP +.Vb 2 +\& #include +\& #include +\& +\& ASN1_TIME *tm; +\& time_t t; +\& BIO *b; +\& +\& t = time(NULL); +\& tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); +\& b = BIO_new_fp(stdout, BIO_NOCLOSE); +\& ASN1_TIME_print(b, tm); +\& ASN1_STRING_free(tm); +\& BIO_free(b); +.Ve +.PP +Determine if one time is later or sooner than the current time: +.PP +.Vb 1 +\& int day, sec; +\& +\& if (!ASN1_TIME_diff(&day, &sec, NULL, to)) +\& /* Invalid time format */ +\& +\& if (day > 0 || sec > 0) +\& printf("Later\en"); +\& else if (day < 0 || sec < 0) +\& printf("Sooner\en"); +\& else +\& printf("Same\en"); +.Ve +.SH HISTORY +.IX Header "HISTORY" +The \fBASN1_TIME_to_tm()\fR function was added in OpenSSL 1.1.1. +The \fBASN1_TIME_set_string_X509()\fR function was added in OpenSSL 1.1.1. +The \fBASN1_TIME_normalize()\fR function was added in OpenSSL 1.1.1. +The \fBASN1_TIME_cmp_time_t()\fR function was added in OpenSSL 1.1.1. +The \fBASN1_TIME_compare()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_TYPE_get.3 b/static/netbsd/man3/ASN1_TYPE_get.3 new file mode 100644 index 00000000..87d4ca03 --- /dev/null +++ b/static/netbsd/man3/ASN1_TYPE_get.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: ASN1_TYPE_get.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_TYPE_get 3" +.TH ASN1_TYPE_get 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence \- ASN1_TYPE utility +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASN1_TYPE_get(const ASN1_TYPE *a); +\& void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value); +\& int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value); +\& int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b); +\& +\& void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t); +\& ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s, +\& ASN1_TYPE **t); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions allow an \fBASN1_TYPE\fR structure to be manipulated. The +\&\fBASN1_TYPE\fR structure can contain any ASN.1 type or constructed type +such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. +.PP +\&\fBASN1_TYPE_get()\fR returns the type of \fIa\fR or 0 if it fails. +.PP +\&\fBASN1_TYPE_set()\fR sets the value of \fIa\fR to \fItype\fR and \fIvalue\fR. This +function uses the pointer \fIvalue\fR internally so it must \fBnot\fR be freed +up after the call. +.PP +\&\fBASN1_TYPE_set1()\fR sets the value of \fIa\fR to \fItype\fR a copy of \fIvalue\fR. +.PP +\&\fBASN1_TYPE_cmp()\fR compares ASN.1 types \fIa\fR and \fIb\fR and returns 0 if +they are identical and nonzero otherwise. +.PP +\&\fBASN1_TYPE_unpack_sequence()\fR attempts to parse the SEQUENCE present in +\&\fIt\fR using the ASN.1 structure \fIit\fR. If successful it returns a pointer +to the ASN.1 structure corresponding to \fIit\fR which must be freed by the +caller. If it fails it return NULL. +.PP +\&\fBASN1_TYPE_pack_sequence()\fR attempts to encode the ASN.1 structure \fIs\fR +corresponding to \fIit\fR into an \fBASN1_TYPE\fR. If successful the encoded +\&\fBASN1_TYPE\fR is returned. If \fIt\fR and \fI*t\fR are not NULL the encoded type +is written to \fIt\fR overwriting any existing data. If \fIt\fR is not NULL +but \fI*t\fR is NULL the returned \fBASN1_TYPE\fR is written to \fI*t\fR. +.SH NOTES +.IX Header "NOTES" +The type and meaning of the \fIvalue\fR parameter for \fBASN1_TYPE_set()\fR and +\&\fBASN1_TYPE_set1()\fR is determined by the \fItype\fR parameter. +If \fItype\fR is \fBV_ASN1_NULL\fR \fIvalue\fR is ignored. If \fItype\fR is +\&\fBV_ASN1_BOOLEAN\fR +then the boolean is set to TRUE if \fIvalue\fR is not NULL. If \fItype\fR is +\&\fBV_ASN1_OBJECT\fR then value is an \fBASN1_OBJECT\fR structure. Otherwise \fItype\fR +is and \fBASN1_STRING\fR structure. If \fItype\fR corresponds to a primitive type +(or a string type) then the contents of the \fBASN1_STRING\fR contain the content +octets of the type. If \fItype\fR corresponds to a constructed type or +a tagged type (\fBV_ASN1_SEQUENCE\fR, \fBV_ASN1_SET\fR or \fBV_ASN1_OTHER\fR) then the +\&\fBASN1_STRING\fR contains the entire ASN.1 encoding verbatim (including tag and +length octets). +.PP +\&\fBASN1_TYPE_cmp()\fR may not return zero if two types are equivalent but have +different encodings. For example the single content octet of the boolean TRUE +value under BER can have any nonzero encoding but \fBASN1_TYPE_cmp()\fR will +only return zero if the values are the same. +.PP +If either or both of the parameters passed to \fBASN1_TYPE_cmp()\fR is NULL the +return value is nonzero. Technically if both parameters are NULL the two +types could be absent OPTIONAL fields and so should match, however, passing +NULL values could also indicate a programming error (for example an +unparsable type which returns NULL) for types which do \fBnot\fR match. So +applications should handle the case of two absent values separately. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_TYPE_get()\fR returns the type of the \fBASN1_TYPE\fR argument. +.PP +\&\fBASN1_TYPE_set()\fR does not return a value. +.PP +\&\fBASN1_TYPE_set1()\fR returns 1 for success and 0 for failure. +.PP +\&\fBASN1_TYPE_cmp()\fR returns 0 if the types are identical and nonzero otherwise. +.PP +\&\fBASN1_TYPE_unpack_sequence()\fR returns a pointer to an ASN.1 structure or +NULL on failure. +.PP +\&\fBASN1_TYPE_pack_sequence()\fR return an \fBASN1_TYPE\fR structure if it succeeds or +NULL on failure. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_aux_cb.3 b/static/netbsd/man3/ASN1_aux_cb.3 new file mode 100644 index 00000000..04608075 --- /dev/null +++ b/static/netbsd/man3/ASN1_aux_cb.3 @@ -0,0 +1,295 @@ +.\" $NetBSD: ASN1_aux_cb.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_aux_cb 3" +.TH ASN1_aux_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb +\&\- ASN.1 auxiliary data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& struct ASN1_AUX_st { +\& void *app_data; +\& int flags; +\& int ref_offset; /* Offset of reference value */ +\& int ref_lock; /* Offset to an CRYPTO_RWLOCK */ +\& ASN1_aux_cb *asn1_cb; +\& int enc_offset; /* Offset of ASN1_ENCODING structure */ +\& ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */ +\& }; +\& typedef struct ASN1_AUX_st ASN1_AUX; +\& +\& struct ASN1_PRINT_ARG_st { +\& BIO *out; +\& int indent; +\& const ASN1_PCTX *pctx; +\& }; +\& typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG; +\& +\& struct ASN1_STREAM_ARG_st { +\& BIO *out; +\& BIO *ndef_bio; +\& unsigned char **boundary; +\& }; +\& typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG; +\& +\& typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it, +\& void *exarg); +\& typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in, +\& const ASN1_ITEM *it, void *exarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ASN.1 data structures can be associated with an \fBASN1_AUX\fR object to supply +additional information about the ASN.1 structure. An \fBASN1_AUX\fR structure is +associated with the structure during the definition of the ASN.1 template. For +example an \fBASN1_AUX\fR structure will be associated by using one of the various +ASN.1 template definition macros that supply auxiliary information such as +\&\fBASN1_SEQUENCE_enc()\fR, \fBASN1_SEQUENCE_ref()\fR, \fBASN1_SEQUENCE_cb_const_cb()\fR, +\&\fBASN1_SEQUENCE_const_cb()\fR, \fBASN1_SEQUENCE_cb()\fR or \fBASN1_NDEF_SEQUENCE_cb()\fR. +.PP +An \fBASN1_AUX\fR structure contains the following information. +.IP \fIapp_data\fR 4 +.IX Item "app_data" +Arbitrary application data +.IP \fIflags\fR 4 +.IX Item "flags" +Flags which indicate the auxiliarly functionality supported. +.Sp +The \fBASN1_AFLG_REFCOUNT\fR flag indicates that objects support reference counting. +.Sp +The \fBASN1_AFLG_ENCODING\fR flag indicates that the original encoding of the +object will be saved. +.Sp +The \fBASN1_AFLG_BROKEN\fR flag is a work around for broken encoders where the +sequence length value may not be correct. This should generally not be used. +.Sp +The \fBASN1_AFLG_CONST_CB\fR flag indicates that the "const" form of the +\&\fBASN1_AUX\fR callback should be used in preference to the non\-const form. +.IP \fIref_offset\fR 4 +.IX Item "ref_offset" +If the \fBASN1_AFLG_REFCOUNT\fR flag is set then this value is assumed to be an +offset into the \fBASN1_VALUE\fR structure where a \fBCRYPTO_REF_COUNT\fR may be +found for the purposes of reference counting. +.IP \fIref_lock\fR 4 +.IX Item "ref_lock" +If the \fBASN1_AFLG_REFCOUNT\fR flag is set then this value is assumed to be an +offset into the \fBASN1_VALUE\fR structure where a \fBCRYPTO_RWLOCK\fR may be +found for the purposes of reference counting. +.IP \fIasn1_cb\fR 4 +.IX Item "asn1_cb" +A callback that will be invoked at various points during the processing of +the \fBASN1_VALUE\fR. See below for further details. +.IP \fIenc_offset\fR 4 +.IX Item "enc_offset" +Offset into the \fBASN1_VALUE\fR object where the original encoding of the object +will be saved if the \fBASN1_AFLG_ENCODING\fR flag has been set. +.IP \fIasn1_const_cb\fR 4 +.IX Item "asn1_const_cb" +A callback that will be invoked at various points during the processing of +the \fBASN1_VALUE\fR. This is used in preference to the \fIasn1_cb\fR callback if +the \fBASN1_AFLG_CONST_CB\fR flag is set. See below for further details. +.PP +During the processing of an \fBASN1_VALUE\fR object the callbacks set via +\&\fIasn1_cb\fR or \fIasn1_const_cb\fR will be invoked as a result of various events +indicated via the \fIoperation\fR parameter. The value of \fI*in\fR will be the +\&\fBASN1_VALUE\fR object being processed based on the template in \fIit\fR. An +additional operation specific parameter may be passed in \fIexarg\fR. The currently +supported operations are as follows. The callbacks should return a positive +value on success or zero on error, unless otherwise noted below. +.IP \fBASN1_OP_NEW_PRE\fR 4 +.IX Item "ASN1_OP_NEW_PRE" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +prior to an \fBASN1_VALUE\fR object being allocated. The callback may allocate the +\&\fBASN1_VALUE\fR itself and store it in \fI*pval\fR. If it does so it should return 2 +from the callback. On error it should return 0. +.IP \fBASN1_OP_NEW_POST\fR 4 +.IX Item "ASN1_OP_NEW_POST" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +after an \fBASN1_VALUE\fR object has been allocated. The allocated object is in +\&\fI*pval\fR. +.IP \fBASN1_OP_FREE_PRE\fR 4 +.IX Item "ASN1_OP_FREE_PRE" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately before an \fBASN1_VALUE\fR is freed. If the callback originally +constructed the \fBASN1_VALUE\fR via \fBASN1_OP_NEW_PRE\fR then it should free it at +this point and return 2 from the callback. Otherwise it should return 1 for +success or 0 on error. +.IP \fBASN1_OP_FREE_POST\fR 4 +.IX Item "ASN1_OP_FREE_POST" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately after \fBASN1_VALUE\fR sub\-structures are freed. +.IP \fBASN1_OP_D2I_PRE\fR 4 +.IX Item "ASN1_OP_D2I_PRE" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately before a "d2i" operation for the \fBASN1_VALUE\fR. +.IP \fBASN1_OP_D2I_POST\fR 4 +.IX Item "ASN1_OP_D2I_POST" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately after a "d2i" operation for the \fBASN1_VALUE\fR. +.IP \fBASN1_OP_I2D_PRE\fR 4 +.IX Item "ASN1_OP_I2D_PRE" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately before a "i2d" operation for the \fBASN1_VALUE\fR. +.IP \fBASN1_OP_I2D_POST\fR 4 +.IX Item "ASN1_OP_I2D_POST" +Invoked when processing a \fBCHOICE\fR, \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure +immediately after a "i2d" operation for the \fBASN1_VALUE\fR. +.IP \fBASN1_OP_PRINT_PRE\fR 4 +.IX Item "ASN1_OP_PRINT_PRE" +Invoked when processing a \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure immediately +before printing the \fBASN1_VALUE\fR. The \fIexarg\fR argument will be a pointer to an +\&\fBASN1_PRINT_ARG\fR structure (see below). +.IP \fBASN1_OP_PRINT_POST\fR 4 +.IX Item "ASN1_OP_PRINT_POST" +Invoked when processing a \fBSEQUENCE\fR or \fBNDEF_SEQUENCE\fR structure immediately +after printing the \fBASN1_VALUE\fR. The \fIexarg\fR argument will be a pointer to an +\&\fBASN1_PRINT_ARG\fR structure (see below). +.IP \fBASN1_OP_STREAM_PRE\fR 4 +.IX Item "ASN1_OP_STREAM_PRE" +Invoked immediately prior to streaming the \fBASN1_VALUE\fR data using indefinite +length encoding. The \fIexarg\fR argument will be a pointer to a \fBASN1_STREAM_ARG\fR +structure (see below). +.IP \fBASN1_OP_STREAM_POST\fR 4 +.IX Item "ASN1_OP_STREAM_POST" +Invoked immediately after streaming the \fBASN1_VALUE\fR data using indefinite +length encoding. The \fIexarg\fR argument will be a pointer to a \fBASN1_STREAM_ARG\fR +structure (see below). +.IP \fBASN1_OP_DETACHED_PRE\fR 4 +.IX Item "ASN1_OP_DETACHED_PRE" +Invoked immediately prior to processing the \fBASN1_VALUE\fR data as a "detached" +value (as used in CMS and PKCS7). The \fIexarg\fR argument will be a pointer to a +\&\fBASN1_STREAM_ARG\fR structure (see below). +.IP \fBASN1_OP_DETACHED_POST\fR 4 +.IX Item "ASN1_OP_DETACHED_POST" +Invoked immediately after processing the \fBASN1_VALUE\fR data as a "detached" +value (as used in CMS and PKCS7). The \fIexarg\fR argument will be a pointer to a +\&\fBASN1_STREAM_ARG\fR structure (see below). +.IP \fBASN1_OP_DUP_PRE\fR 4 +.IX Item "ASN1_OP_DUP_PRE" +Invoked immediate prior to an ASN1_VALUE being duplicated via a call to +\&\fBASN1_item_dup()\fR. +.IP \fBASN1_OP_DUP_POST\fR 4 +.IX Item "ASN1_OP_DUP_POST" +Invoked immediate after to an ASN1_VALUE has been duplicated via a call to +\&\fBASN1_item_dup()\fR. +.IP \fBASN1_OP_GET0_LIBCTX\fR 4 +.IX Item "ASN1_OP_GET0_LIBCTX" +Invoked in order to obtain the \fBOSSL_LIB_CTX\fR associated with an \fBASN1_VALUE\fR +if any. A pointer to an \fBOSSL_LIB_CTX\fR should be stored in \fI*exarg\fR if such +a value exists. +.IP \fBASN1_OP_GET0_PROPQ\fR 4 +.IX Item "ASN1_OP_GET0_PROPQ" +Invoked in order to obtain the property query string associated with an +\&\fBASN1_VALUE\fR if any. A pointer to the property query string should be stored in +\&\fI*exarg\fR if such a value exists. +.PP +An \fBASN1_PRINT_ARG\fR object is used during processing of \fBASN1_OP_PRINT_PRE\fR +and \fBASN1_OP_PRINT_POST\fR callback operations. It contains the following +information. +.IP \fIout\fR 4 +.IX Item "out" +The \fBBIO\fR being used to print the data out. +.IP \fIndef_bio\fR 4 +.IX Item "ndef_bio" +The current number of indent spaces that should be used for printing this data. +.IP \fIpctx\fR 4 +.IX Item "pctx" +The context for the \fBASN1_PCTX\fR operation. +.PP +An \fBASN1_STREAM_ARG\fR object is used during processing of \fBASN1_OP_STREAM_PRE\fR, +\&\fBASN1_OP_STREAM_POST\fR, \fBASN1_OP_DETACHED_PRE\fR and \fBASN1_OP_DETACHED_POST\fR +callback operations. It contains the following information. +.IP \fIout\fR 4 +.IX Item "out" +The \fBBIO\fR to stream through +.IP \fIndef_bio\fR 4 +.IX Item "ndef_bio" +The \fBBIO\fR with filters appended +.IP \fIboundary\fR 4 +.IX Item "boundary" +The streaming I/O boundary. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The callbacks return 0 on error and a positive value on success. Some operations +require specific positive success values as noted above. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_item_new_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBASN1_aux_const_cb()\fR callback and the \fBASN1_OP_GET0_LIBCTX\fR and +\&\fBASN1_OP_GET0_PROPQ\fR operation types were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_generate_nconf.3 b/static/netbsd/man3/ASN1_generate_nconf.3 new file mode 100644 index 00000000..55585b5c --- /dev/null +++ b/static/netbsd/man3/ASN1_generate_nconf.3 @@ -0,0 +1,309 @@ +.\" $NetBSD: ASN1_generate_nconf.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_generate_nconf 3" +.TH ASN1_generate_nconf 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 string generation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf); +\& ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions generate the ASN1 encoding of a string +in an \fBASN1_TYPE\fR structure. +.PP +\&\fIstr\fR contains the string to encode. \fInconf\fR or \fIcnf\fR contains +the optional configuration information where additional strings +will be read from. \fInconf\fR will typically come from a config +file whereas \fIcnf\fR is obtained from an \fBX509V3_CTX\fR structure, +which will typically be used by X509 v3 certificate extension +functions. \fIcnf\fR or \fInconf\fR can be set to NULL if no additional +configuration will be used. +.SH "GENERATION STRING FORMAT" +.IX Header "GENERATION STRING FORMAT" +The actual data encoded is determined by the string \fIstr\fR and +the configuration information. The general format of the string +is: +.IP [\fImodifier\fR,]\fItype\fR[:\fIvalue\fR] 4 +.IX Item "[modifier,]type[:value]" +.PP +That is zero or more comma separated modifiers followed by a type +followed by an optional colon and a value. The formats of \fItype\fR, +\&\fIvalue\fR and \fImodifier\fR are explained below. +.SS "Supported Types" +.IX Subsection "Supported Types" +The supported types are listed below. +Case is not significant in the type names. +Unless otherwise specified only the \fBASCII\fR format is permissible. +.IP "\fBBOOLEAN\fR, \fBBOOL\fR" 4 +.IX Item "BOOLEAN, BOOL" +This encodes a boolean type. The \fIvalue\fR string is mandatory and +should be \fBTRUE\fR or \fBFALSE\fR. Additionally \fBTRUE\fR, \fBtrue\fR, \fBY\fR, +\&\fBy\fR, \fBYES\fR, \fByes\fR, \fBFALSE\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fBNO\fR and \fBno\fR +are acceptable. +.IP \fBNULL\fR 4 +.IX Item "NULL" +Encode the \fBNULL\fR type, the \fIvalue\fR string must not be present. +.IP "\fBINTEGER\fR, \fBINT\fR" 4 +.IX Item "INTEGER, INT" +Encodes an ASN1 \fBINTEGER\fR type. The \fIvalue\fR string represents +the value of the integer, it can be prefaced by a minus sign and +is normally interpreted as a decimal value unless the prefix \fB0x\fR +is included. +.IP "\fBENUMERATED\fR, \fBENUM\fR" 4 +.IX Item "ENUMERATED, ENUM" +Encodes the ASN1 \fBENUMERATED\fR type, it is otherwise identical to +\&\fBINTEGER\fR. +.IP "\fBOBJECT\fR, \fBOID\fR" 4 +.IX Item "OBJECT, OID" +Encodes an ASN1 \fBOBJECT IDENTIFIER\fR, the \fIvalue\fR string can be +a short name, a long name or numerical format. +.IP "\fBUTCTIME\fR, \fBUTC\fR" 4 +.IX Item "UTCTIME, UTC" +Encodes an ASN1 \fBUTCTime\fR structure, the value should be in +the format \fBYYMMDDHHMMSSZ\fR. +.IP "\fBGENERALIZEDTIME\fR, \fBGENTIME\fR" 4 +.IX Item "GENERALIZEDTIME, GENTIME" +Encodes an ASN1 \fBGeneralizedTime\fR structure, the value should be in +the format \fBYYYYMMDDHHMMSSZ\fR. +.IP "\fBOCTETSTRING\fR, \fBOCT\fR" 4 +.IX Item "OCTETSTRING, OCT" +Encodes an ASN1 \fBOCTET STRING\fR. \fIvalue\fR represents the contents +of this structure, the format strings \fBASCII\fR and \fBHEX\fR can be +used to specify the format of \fIvalue\fR. +.IP "\fBBITSTRING\fR, \fBBITSTR\fR" 4 +.IX Item "BITSTRING, BITSTR" +Encodes an ASN1 \fBBIT STRING\fR. \fIvalue\fR represents the contents +of this structure, the format strings \fBASCII\fR, \fBHEX\fR and \fBBITLIST\fR +can be used to specify the format of \fIvalue\fR. +.Sp +If the format is anything other than \fBBITLIST\fR the number of unused +bits is set to zero. +.IP "\fBUNIVERSALSTRING\fR, \fBUNIV\fR, \fBIA5\fR, \fBIA5STRING\fR, \fBUTF8\fR, \fBUTF8String\fR, \fBBMP\fR, \fBBMPSTRING\fR, \fBVISIBLESTRING\fR, \fBVISIBLE\fR, \fBPRINTABLESTRING\fR, \fBPRINTABLE\fR, \fBT61\fR, \fBT61STRING\fR, \fBTELETEXSTRING\fR, \fBGeneralString\fR, \fBNUMERICSTRING\fR, \fBNUMERIC\fR" 4 +.IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC" +These encode the corresponding string types. \fIvalue\fR represents the +contents of this structure. The format can be \fBASCII\fR or \fBUTF8\fR. +.IP "\fBSEQUENCE\fR, \fBSEQ\fR, \fBSET\fR" 4 +.IX Item "SEQUENCE, SEQ, SET" +Formats the result as an ASN1 \fBSEQUENCE\fR or \fBSET\fR type. \fIvalue\fR +should be a section name which will contain the contents. The +field names in the section are ignored and the values are in the +generated string format. If \fIvalue\fR is absent then an empty SEQUENCE +will be encoded. +.SS Modifiers +.IX Subsection "Modifiers" +Modifiers affect the following structure, they can be used to +add EXPLICIT or IMPLICIT tagging, add wrappers or to change +the string format of the final type and value. The supported +formats are documented below. +.IP "\fBEXPLICIT\fR, \fBEXP\fR" 4 +.IX Item "EXPLICIT, EXP" +Add an explicit tag to the following structure. This string +should be followed by a colon and the tag value to use as a +decimal value. +.Sp +By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR UNIVERSAL, +APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, +the default is CONTEXT SPECIFIC. +.IP "\fBIMPLICIT\fR, \fBIMP\fR" 4 +.IX Item "IMPLICIT, IMP" +This is the same as \fBEXPLICIT\fR except IMPLICIT tagging is used +instead. +.IP "\fBOCTWRAP\fR, \fBSEQWRAP\fR, \fBSETWRAP\fR, \fBBITWRAP\fR" 4 +.IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP" +The following structure is surrounded by an OCTET STRING, a SEQUENCE, +a SET or a BIT STRING respectively. For a BIT STRING the number of unused +bits is set to zero. +.IP \fBFORMAT\fR 4 +.IX Item "FORMAT" +This specifies the format of the ultimate value. It should be followed +by a colon and one of the strings \fBASCII\fR, \fBUTF8\fR, \fBHEX\fR or \fBBITLIST\fR. +.Sp +If no format specifier is included then \fBASCII\fR is used. If \fBUTF8\fR is +specified then the value string must be a valid \fBUTF8\fR string. For \fBHEX\fR the +output must be a set of hex digits. \fBBITLIST\fR (which is only valid for a BIT +STRING) is a comma separated list of the indices of the set bits, all other +bits are zero. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_generate_nconf()\fR and \fBASN1_generate_v3()\fR return the encoded +data as an \fBASN1_TYPE\fR structure or NULL if an error occurred. +.PP +The error codes that can be obtained by \fBERR_get_error\fR\|(3). +.SH EXAMPLES +.IX Header "EXAMPLES" +A simple IA5String: +.PP +.Vb 1 +\& IA5STRING:Hello World +.Ve +.PP +An IA5String explicitly tagged: +.PP +.Vb 1 +\& EXPLICIT:0,IA5STRING:Hello World +.Ve +.PP +An IA5String explicitly tagged using APPLICATION tagging: +.PP +.Vb 1 +\& EXPLICIT:0A,IA5STRING:Hello World +.Ve +.PP +A BITSTRING with bits 1 and 5 set and all others zero: +.PP +.Vb 1 +\& FORMAT:BITLIST,BITSTRING:1,5 +.Ve +.PP +A more complex example using a config file to produce a +SEQUENCE consisting of a BOOL an OID and a UTF8String: +.PP +.Vb 1 +\& asn1 = SEQUENCE:seq_section +\& +\& [seq_section] +\& +\& field1 = BOOLEAN:TRUE +\& field2 = OID:commonName +\& field3 = UTF8:Third field +.Ve +.PP +This example produces an RSAPrivateKey structure, this is the +key contained in the file client.pem in all OpenSSL distributions +(note: the field names such as \*(Aqcoeff\*(Aq are ignored and are present just +for clarity): +.PP +.Vb 3 +\& asn1=SEQUENCE:private_key +\& [private_key] +\& version=INTEGER:0 +\& +\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e +\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 +\& +\& e=INTEGER:0x010001 +\& +\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e +\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D +\& +\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e +\& D4BD57 +\& +\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e +\& 46EC4F +\& +\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e +\& 9C0A39B9 +\& +\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e +\& E7B2458F +\& +\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e +\& 628657053A +.Ve +.PP +This example is the corresponding public key in a SubjectPublicKeyInfo +structure: +.PP +.Vb 2 +\& # Start with a SEQUENCE +\& asn1=SEQUENCE:pubkeyinfo +\& +\& # pubkeyinfo contains an algorithm identifier and the public key wrapped +\& # in a BIT STRING +\& [pubkeyinfo] +\& algorithm=SEQUENCE:rsa_alg +\& pubkey=BITWRAP,SEQUENCE:rsapubkey +\& +\& # algorithm ID for RSA is just an OID and a NULL +\& [rsa_alg] +\& algorithm=OID:rsaEncryption +\& parameter=NULL +\& +\& # Actual public key: modulus and exponent +\& [rsapubkey] +\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e +\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 +\& +\& e=INTEGER:0x010001 +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_item_d2i_bio.3 b/static/netbsd/man3/ASN1_item_d2i_bio.3 new file mode 100644 index 00000000..727469c0 --- /dev/null +++ b/static/netbsd/man3/ASN1_item_d2i_bio.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: ASN1_item_d2i_bio.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_item_d2i_bio 3" +.TH ASN1_item_d2i_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, +ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio, +ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack +\&\- decode and encode DER\-encoded ASN.1 structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, +\& long len, const ASN1_ITEM *it, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in, +\& long len, const ASN1_ITEM *it); +\& +\& void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x); +\& +\& void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x); +\& +\& BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val); +\& +\& ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct); +\& +\& void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it); +\& +\& void *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it, +\& OSSL_LIB_CTX *libctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_item_d2i_ex()\fR decodes the contents of the data stored in \fI*in\fR of length +\&\fIlen\fR which must be a DER\-encoded ASN.1 structure, using the ASN.1 template +\&\fIit\fR. It places the result in \fI*pval\fR unless \fIpval\fR is NULL. If \fI*pval\fR is +non\-NULL on entry then the \fBASN1_VALUE\fR present there will be reused. Otherwise +a new \fBASN1_VALUE\fR will be allocated. If any algorithm fetches are required +during the process then they will use the \fBOSSL_LIB_CTX\fRprovided in the +\&\fIlibctx\fR parameter and the property query string in \fIpropq\fR. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about algorithm fetching. +On exit \fI*in\fR will be updated to point to the next byte in the buffer after the +decoded structure. +.PP +\&\fBASN1_item_d2i()\fR is the same as \fBASN1_item_d2i_ex()\fR except that the default +OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string. +.PP +\&\fBASN1_item_d2i_bio_ex()\fR decodes the contents of its input BIO \fIin\fR, +which must be a DER\-encoded ASN.1 structure, using the ASN.1 template \fIit\fR +and places the result in \fI*pval\fR unless \fIpval\fR is NULL. +If \fIin\fR is NULL it returns NULL, else a pointer to the parsed structure. If any +algorithm fetches are required during the process then they will use the +\&\fBOSSL_LIB_CTX\fR provided in the \fIlibctx\fR parameter and the property query +string in \fIpropq\fR. See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information +about algorithm fetching. +.PP +\&\fBASN1_item_d2i_bio()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that the +default \fBOSSL_LIB_CTX\fR is used (i.e. NULL) and with a NULL property query +string. +.PP +\&\fBASN1_item_d2i_fp_ex()\fR is the same as \fBASN1_item_d2i_bio_ex()\fR except that a FILE +pointer is provided instead of a BIO. +.PP +\&\fBASN1_item_d2i_fp()\fR is the same as \fBASN1_item_d2i_fp_ex()\fR except that the +default \fBOSSL_LIB_CTX\fR is used (i.e. NULL) and with a NULL property query +string. +.PP +\&\fBASN1_item_i2d_mem_bio()\fR encodes the given ASN.1 value \fIval\fR +using the ASN.1 template \fIit\fR and returns the result in a memory BIO. +.PP +\&\fBASN1_item_pack()\fR encodes the given ASN.1 value in \fIobj\fR using the +ASN.1 template \fIit\fR and returns an \fBASN1_STRING\fR object. If the passed in +\&\fI*oct\fR is not NULL then this is used to store the returned result, otherwise +a new \fBASN1_STRING\fR object is created. If \fIoct\fR is not NULL and \fI*oct\fR is NULL +then the returned return is also set into \fI*oct\fR. If there is an error the optional +passed in \fBASN1_STRING\fR will not be freed, but the previous value may be cleared when +ASN1_STRING_set0(*oct, NULL, 0) is called internally. +.PP +\&\fBASN1_item_unpack()\fR uses \fBASN1_item_d2i()\fR to decode the DER\-encoded \fBASN1_STRING\fR +\&\fIoct\fR using the ASN.1 template \fIit\fR. +.PP +\&\fBASN1_item_unpack_ex()\fR is similar to \fBASN1_item_unpack()\fR, but uses \fBASN1_item_d2i_ex()\fR so +that the \fIlibctx\fR and \fIpropq\fR can be used when doing algorithm fetching. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_item_d2i_bio()\fR, \fBASN1_item_unpack_ex()\fR and \fBASN1_item_unpack()\fR return a pointer to +an \fBASN1_VALUE\fR or NULL on error. +.PP +\&\fBASN1_item_i2d_mem_bio()\fR returns a pointer to a memory BIO or NULL on error. +.PP +\&\fBASN1_item_pack()\fR returns a pointer to an \fBASN1_STRING\fR or NULL on error. +.SH HISTORY +.IX Header "HISTORY" +The functions \fBASN1_item_d2i_ex()\fR, \fBASN1_item_d2i_bio_ex()\fR, \fBASN1_item_d2i_fp_ex()\fR +and \fBASN1_item_i2d_mem_bio()\fR were added in OpenSSL 3.0. +.PP +The function \fBASN1_item_unpack_ex()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_item_new.3 b/static/netbsd/man3/ASN1_item_new.3 new file mode 100644 index 00000000..ac67093d --- /dev/null +++ b/static/netbsd/man3/ASN1_item_new.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: ASN1_item_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_item_new 3" +.TH ASN1_item_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_item_new_ex, ASN1_item_new +\&\- create new ASN.1 values +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_item_new_ex()\fR creates a new \fBASN1_VALUE\fR structure based on the +\&\fBASN1_ITEM\fR template given in the \fIit\fR parameter. If any algorithm fetches are +required during the process then they will use the \fBOSSL_LIB_CTX\fR provided in +the \fIlibctx\fR parameter and the property query string in \fIpropq\fR. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about algorithm fetching. +.PP +\&\fBASN1_item_new()\fR is the same as \fBASN1_item_new_ex()\fR except that the default +\&\fBOSSL_LIB_CTX\fR is used (i.e. NULL) and with a NULL property query string. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASN1_item_new_ex()\fR and \fBASN1_item_new()\fR return a pointer to the newly created +\&\fBASN1_VALUE\fR or NULL on error. +.SH HISTORY +.IX Header "HISTORY" +The function \fBASN1_item_new_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASN1_item_sign.3 b/static/netbsd/man3/ASN1_item_sign.3 new file mode 100644 index 00000000..4f2d33a1 --- /dev/null +++ b/static/netbsd/man3/ASN1_item_sign.3 @@ -0,0 +1,284 @@ +.\" $NetBSD: ASN1_item_sign.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASN1_item_sign 3" +.TH ASN1_item_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASN1_item_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx, +ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx \- +ASN1 sign and verify +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASN1_item_sign_ex(const ASN1_ITEM *it, X509_ALGOR *algor1, +\& X509_ALGOR *algor2, ASN1_BIT_STRING *signature, +\& const void *data, const ASN1_OCTET_STRING *id, +\& EVP_PKEY *pkey, const EVP_MD *md, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& +\& int ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2, +\& ASN1_BIT_STRING *signature, const void *data, +\& EVP_PKEY *pkey, const EVP_MD *md); +\& +\& int ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1, +\& X509_ALGOR *algor2, ASN1_BIT_STRING *signature, +\& const void *data, EVP_MD_CTX *ctx); +\& +\& int ASN1_item_verify_ex(const ASN1_ITEM *it, const X509_ALGOR *alg, +\& const ASN1_BIT_STRING *signature, const void *data, +\& const ASN1_OCTET_STRING *id, EVP_PKEY *pkey, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& int ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *alg, +\& const ASN1_BIT_STRING *signature, const void *data, +\& EVP_PKEY *pkey); +\& +\& int ASN1_item_verify_ctx(const ASN1_ITEM *it, const X509_ALGOR *alg, +\& const ASN1_BIT_STRING *signature, const void *data, +\& EVP_MD_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBASN1_item_sign_ex()\fR is used to sign arbitrary ASN1 data using a data object +\&\fIdata\fR, the ASN.1 structure \fIit\fR, private key \fIpkey\fR and message digest \fImd\fR. +The data that is signed is formed by taking the data object in \fIdata\fR and +converting it to der format using the ASN.1 structure \fIit\fR. +The \fIdata\fR that will be signed, and a structure containing the signature may +both have a copy of the \fBX509_ALGOR\fR. The \fBASN1_item_sign_ex()\fR function will +write the correct \fBX509_ALGOR\fR to the structs based on the algorithms and +parameters that have been set up. If one of \fIalgor1\fR or \fIalgor2\fR points to the +\&\fBX509_ALGOR\fR of the \fIdata\fR to be signed, then that \fBX509_ALGOR\fR will first be +written before the signature is generated. +Examples of valid values that can be used by the ASN.1 structure \fIit\fR are +ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and +ASN1_ITEM_rptr(X509_CRL_INFO). +The \fBOSSL_LIB_CTX\fR specified in \fIlibctx\fR and the property query string +specified in \fIprops\fR are used when searching for algorithms in providers. +The generated signature is set into \fIsignature\fR. +The optional parameter \fIid\fR can be NULL, but can be set for special key types. +See \fBEVP_PKEY_CTX_set1_id()\fR for further info. The output parameters and +\&\fIalgor2\fR are ignored if they are NULL. +.PP +\&\fBASN1_item_sign()\fR is similar to \fBASN1_item_sign_ex()\fR but uses default values of +NULL for the \fIid\fR, \fIlibctx\fR and \fIpropq\fR. +.PP +\&\fBASN1_item_sign_ctx()\fR is similar to \fBASN1_item_sign()\fR but uses the parameters +contained in digest context \fIctx\fR. +.PP +\&\fBASN1_item_verify_ex()\fR is used to verify the signature \fIsignature\fR of internal +data \fIdata\fR using the public key \fIpkey\fR and algorithm identifier \fIalg\fR. +The data that is verified is formed by taking the data object in \fIdata\fR and +converting it to der format using the ASN.1 structure \fIit\fR. +The \fBOSSL_LIB_CTX\fR specified in \fIlibctx\fR and the property query string +specified in \fIprops\fR are used when searching for algorithms in providers. +The optional parameter \fIid\fR can be NULL, but can be set for special key types. +See \fBEVP_PKEY_CTX_set1_id()\fR for further info. +.PP +\&\fBASN1_item_verify()\fR is similar to \fBASN1_item_verify_ex()\fR but uses default values of +NULL for the \fIid\fR, \fIlibctx\fR and \fIpropq\fR. +.PP +\&\fBASN1_item_verify_ctx()\fR is similar to \fBASN1_item_verify()\fR but uses the parameters +contained in digest context \fIctx\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All sign functions return the size of the signature in bytes for success and +zero for failure. +.PP +All verify functions return 1 if the signature is valid and 0 if the signature +check fails. If the signature could not be checked at all because it was +ill\-formed or some other error occurred then \-1 is returned. +.SH EXAMPLES +.IX Header "EXAMPLES" +In the following example a \*(AqMyObject\*(Aq object is signed using the key contained +in an EVP_MD_CTX. The signature is written to MyObject.signature. The object is +then output in DER format and then loaded back in and verified. +.PP +.Vb 2 +\& #include +\& #include +\& +\& /* An object used to store the ASN1 data fields that will be signed */ +\& typedef struct MySignInfoObject_st +\& { +\& ASN1_INTEGER *version; +\& X509_ALGOR sig_alg; +\& } MySignInfoObject; +\& +\& DECLARE_ASN1_FUNCTIONS(MySignInfoObject) +\& /* +\& * A higher level object containing the ASN1 fields, signature alg and +\& * output signature. +\& */ +\& typedef struct MyObject_st +\& { +\& MySignInfoObject info; +\& X509_ALGOR sig_alg; +\& ASN1_BIT_STRING *signature; +\& } MyObject; +\& +\& DECLARE_ASN1_FUNCTIONS(MyObject) +\& +\& /* The ASN1 definition of MySignInfoObject */ +\& ASN1_SEQUENCE_cb(MySignInfoObject, NULL) = { +\& ASN1_SIMPLE(MySignInfoObject, version, ASN1_INTEGER) +\& ASN1_EMBED(MySignInfoObject, sig_alg, X509_ALGOR), +\& } ASN1_SEQUENCE_END_cb(MySignInfoObject, MySignInfoObject) +\& +\& /* new, free, d2i & i2d functions for MySignInfoObject */ +\& IMPLEMENT_ASN1_FUNCTIONS(MySignInfoObject) +\& +\& /* The ASN1 definition of MyObject */ +\& ASN1_SEQUENCE_cb(MyObject, NULL) = { +\& ASN1_EMBED(MyObject, info, MySignInfoObject), +\& ASN1_EMBED(MyObject, sig_alg, X509_ALGOR), +\& ASN1_SIMPLE(MyObject, signature, ASN1_BIT_STRING) +\& } ASN1_SEQUENCE_END_cb(MyObject, MyObject) +\& +\& /* new, free, d2i & i2d functions for MyObject */ +\& IMPLEMENT_ASN1_FUNCTIONS(MyObject) +\& +\& int test_asn1_item_sign_verify(const char *mdname, EVP_PKEY *pkey, long version) +\& { +\& int ret = 0; +\& unsigned char *obj_der = NULL; +\& const unsigned char *p = NULL; +\& MyObject *obj = NULL, *loaded_obj = NULL; +\& const ASN1_ITEM *it = ASN1_ITEM_rptr(MySignInfoObject); +\& EVP_MD_CTX *sctx = NULL, *vctx = NULL; +\& int len; +\& +\& /* Create MyObject and set its version */ +\& obj = MyObject_new(); +\& if (obj == NULL) +\& goto err; +\& if (!ASN1_INTEGER_set(obj\->info.version, version)) +\& goto err; +\& +\& /* Set the key and digest used for signing */ +\& sctx = EVP_MD_CTX_new(); +\& if (sctx == NULL +\& || !EVP_DigestSignInit_ex(sctx, NULL, mdname, NULL, NULL, pkey)) +\& goto err; +\& +\& /* +\& * it contains the mapping between ASN.1 data and an object MySignInfoObject +\& * obj\->info is the \*(AqMySignInfoObject\*(Aq object that will be +\& * converted into DER data and then signed. +\& * obj\->signature will contain the output signature. +\& * obj\->sig_alg is filled with the private key\*(Aqs signing algorithm id. +\& * obj\->info.sig_alg is another copy of the signing algorithm id that sits +\& * within MyObject. +\& */ +\& len = ASN1_item_sign_ctx(it, &obj\->sig_alg, &obj\->info.sig_alg, +\& obj\->signature, &obj\->info, sctx); +\& if (len <= 0 +\& || X509_ALGOR_cmp(&obj\->sig_alg, &obj\->info.sig_alg) != 0) +\& goto err; +\& +\& /* Output MyObject in der form */ +\& len = i2d_MyObject(obj, &obj_der); +\& if (len <= 0) +\& goto err; +\& +\& /* Set the key and digest used for verifying */ +\& vctx = EVP_MD_CTX_new(); +\& if (vctx == NULL +\& || !EVP_DigestVerifyInit_ex(vctx, NULL, mdname, NULL, NULL, pkey)) +\& goto err; +\& +\& /* Load the der data back into an object */ +\& p = obj_der; +\& loaded_obj = d2i_MyObject(NULL, &p, len); +\& if (loaded_obj == NULL) +\& goto err; +\& /* Verify the loaded object */ +\& ret = ASN1_item_verify_ctx(it, &loaded_obj\->sig_alg, loaded_obj\->signature, +\& &loaded_obj\->info, vctx); +\&err: +\& OPENSSL_free(obj_der); +\& MyObject_free(loaded_obj); +\& MyObject_free(obj); +\& EVP_MD_CTX_free(sctx); +\& EVP_MD_CTX_free(vctx); +\& return ret; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_sign\fR\|(3), +\&\fBX509_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBASN1_item_sign_ex()\fR and \fBASN1_item_verify_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASYNC_WAIT_CTX_new.3 b/static/netbsd/man3/ASYNC_WAIT_CTX_new.3 new file mode 100644 index 00000000..9538eb64 --- /dev/null +++ b/static/netbsd/man3/ASYNC_WAIT_CTX_new.3 @@ -0,0 +1,276 @@ +.\" $NetBSD: ASYNC_WAIT_CTX_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASYNC_WAIT_CTX_new 3" +.TH ASYNC_WAIT_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, +ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback, +ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn, +ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK, +ASYNC_STATUS_EAGAIN +\&\- functions to manage waiting for asynchronous jobs to complete +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define ASYNC_STATUS_UNSUPPORTED 0 +\& #define ASYNC_STATUS_ERR 1 +\& #define ASYNC_STATUS_OK 2 +\& #define ASYNC_STATUS_EAGAIN 3 +\& typedef int (*ASYNC_callback_fn)(void *arg); +\& ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); +\& void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); +\& int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, +\& OSSL_ASYNC_FD fd, +\& void *custom_data, +\& void (*cleanup)(ASYNC_WAIT_CTX *, const void *, +\& OSSL_ASYNC_FD, void *)); +\& int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key, +\& OSSL_ASYNC_FD *fd, void **custom_data); +\& int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd, +\& size_t *numfds); +\& int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd, +\& size_t *numaddfds, OSSL_ASYNC_FD *delfd, +\& size_t *numdelfds); +\& int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); +\& int ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx, +\& ASYNC_callback_fn callback, +\& void *callback_arg); +\& int ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx, +\& ASYNC_callback_fn *callback, +\& void **callback_arg); +\& int ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status); +\& int ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For an overview of how asynchronous operations are implemented in OpenSSL see +\&\fBASYNC_start_job\fR\|(3). An \fBASYNC_WAIT_CTX\fR object represents an asynchronous +"session", i.e. a related set of crypto operations. For example in SSL terms +this would have a one\-to\-one correspondence with an SSL connection. +.PP +Application code must create an \fBASYNC_WAIT_CTX\fR using the \fBASYNC_WAIT_CTX_new()\fR +function prior to calling \fBASYNC_start_job()\fR (see \fBASYNC_start_job\fR\|(3)). When +the job is started it is associated with the \fBASYNC_WAIT_CTX\fR for the duration +of that job. An \fBASYNC_WAIT_CTX\fR should only be used for one \fBASYNC_JOB\fR at +any one time, but can be reused after an \fBASYNC_JOB\fR has finished for a +subsequent \fBASYNC_JOB\fR. When the session is complete (e.g. the SSL connection +is closed), application code cleans up with \fBASYNC_WAIT_CTX_free()\fR. +.PP +\&\fBASYNC_WAIT_CTX\fRs can have "wait" file descriptors associated with them. +Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an +\&\fBASYNC_WAIT_CTX\fR in the \fIctx\fR parameter will return the wait file descriptors +associated with that job in \fI*fd\fR. The number of file descriptors returned will +be stored in \fI*numfds\fR. It is the caller\*(Aqs responsibility to ensure that +sufficient memory has been allocated in \fI*fd\fR to receive all the file +descriptors. Calling \fBASYNC_WAIT_CTX_get_all_fds()\fR with a NULL \fIfd\fR value will +return no file descriptors but will still populate \fI*numfds\fR. Therefore, +application code is typically expected to call this function twice: once to get +the number of fds, and then again when sufficient memory has been allocated. If +only one asynchronous engine is being used then normally this call will only +ever return one fd. If multiple asynchronous engines are being used then more +could be returned. +.PP +The function \fBASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds +have changed since the last call time \fBASYNC_start_job()\fR returned \fBASYNC_PAUSE\fR +(or since the \fBASYNC_WAIT_CTX\fR was created if no \fBASYNC_PAUSE\fR result has +been received). The \fInumaddfds\fR and \fInumdelfds\fR parameters will be populated +with the number of fds added or deleted respectively. \fI*addfd\fR and \fI*delfd\fR +will be populated with the list of added and deleted fds respectively. Similarly +to \fBASYNC_WAIT_CTX_get_all_fds()\fR either of these can be NULL, but if they are not +NULL then the caller is responsible for ensuring sufficient memory is allocated. +.PP +Implementers of async aware code (e.g. engines) are encouraged to return a +stable fd for the lifetime of the \fBASYNC_WAIT_CTX\fR in order to reduce the +"churn" of regularly changing fds \- although no guarantees of this are provided +to applications. +.PP +Applications can wait for the file descriptor to be ready for "read" using a +system function call such as select or poll (being ready for "read" indicates +that the job should be resumed). If no file descriptor is made available then an +application will have to periodically "poll" the job by attempting to restart it +to see if it is ready to continue. +.PP +Async aware code (e.g. engines) can get the current \fBASYNC_WAIT_CTX\fR from the +job via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for +waiting on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done +by an engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user +code. An existing association with a file descriptor can be obtained using +\&\fBASYNC_WAIT_CTX_get_fd()\fR and cleared using \fBASYNC_WAIT_CTX_clear_fd()\fR. Both of +these functions requires a \fIkey\fR value which is unique to the async aware +code. This could be any unique value but a good candidate might be the +\&\fBENGINE *\fR for the engine. The \fIcustom_data\fR parameter can be any value, and +will be returned in a subsequent call to \fBASYNC_WAIT_CTX_get_fd()\fR. The +\&\fBASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a "cleanup" +routine. This can be NULL but if provided will automatically get called when +the \fBASYNC_WAIT_CTX\fR is freed, and gives the engine the opportunity to close +the fd or any other resources. Note: The "cleanup" routine does not get called +if the fd is cleared directly via a call to \fBASYNC_WAIT_CTX_clear_fd()\fR. +.PP +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call \fBASYNC_WAIT_CTX_set_wait_fd()\fR followed by +\&\fBASYNC_pause_job()\fR to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. +.PP +As well as a file descriptor, user code may also be notified via a callback. The +callback and data pointers are stored within the \fBASYNC_WAIT_CTX\fR along with an +additional status field that can be used for the notification of retries from an +engine. This additional method can be used when the user thinks that a file +descriptor is too costly in terms of CPU cycles or in some context where a file +descriptor is not appropriate. +.PP +\&\fBASYNC_WAIT_CTX_set_callback()\fR sets the callback and the callback argument. The +callback will be called to notify user code when an engine completes a +cryptography operation. It is a requirement that the callback function is small +and nonblocking as it will be run in the context of a polling mechanism or an +interrupt. +.PP +\&\fBASYNC_WAIT_CTX_get_callback()\fR returns the callback set in the \fBASYNC_WAIT_CTX\fR +structure. +.PP +\&\fBASYNC_WAIT_CTX_set_status()\fR allows an engine to set the current engine status. +The possible status values are the following: +.IP \fBASYNC_STATUS_UNSUPPORTED\fR 4 +.IX Item "ASYNC_STATUS_UNSUPPORTED" +The engine does not support the callback mechanism. This is the default value. +The engine must call \fBASYNC_WAIT_CTX_set_status()\fR to set the status to some value +other than \fBASYNC_STATUS_UNSUPPORTED\fR if it intends to enable the callback +mechanism. +.IP \fBASYNC_STATUS_ERR\fR 4 +.IX Item "ASYNC_STATUS_ERR" +The engine has a fatal problem with this request. The user code should clean up +this session. +.IP \fBASYNC_STATUS_OK\fR 4 +.IX Item "ASYNC_STATUS_OK" +The request has been successfully submitted. +.IP \fBASYNC_STATUS_EAGAIN\fR 4 +.IX Item "ASYNC_STATUS_EAGAIN" +The engine has some problem which will be recovered soon, such as a buffer is +full, so user code should resume the job. +.PP +\&\fBASYNC_WAIT_CTX_get_status()\fR allows user code to obtain the current status value. +If the status is any value other than \fBASYNC_STATUS_OK\fR then the user code +should not expect to receive a callback from the engine even if one has been +set. +.PP +An example of the usage of the callback method might be the following. User +code would initiate cryptographic operations, and the engine code would dispatch +this operation to hardware, and if the dispatch is successful, then the engine +code would call \fBASYNC_pause_job()\fR to return control to the user code. After +that, user code can perform other tasks. When the hardware completes the +operation, normally it is detected by a polling function or an interrupt, as the +user code set a callback by calling \fBASYNC_WAIT_CTX_set_callback()\fR previously, +then the registered callback will be called. +.PP +\&\fBASYNC_WAIT_CTX_free()\fR frees up a single \fBASYNC_WAIT_CTX\fR object. +If the argument is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \fBASYNC_WAIT_CTX\fR +or NULL on error. +.PP +ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, +ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and +ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. +\&\fBASYNC_WAIT_CTX_get_status()\fR returns the engine status. +.SH NOTES +.IX Header "NOTES" +On Windows platforms the \fI\fR header is dependent on some +of the types customarily made available by including \fI\fR. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore, +it is defined as an application developer\*(Aqs responsibility to include +\&\fI\fR prior to \fI\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBASYNC_start_job\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBASYNC_WAIT_CTX_new()\fR, \fBASYNC_WAIT_CTX_free()\fR, \fBASYNC_WAIT_CTX_set_wait_fd()\fR, +\&\fBASYNC_WAIT_CTX_get_fd()\fR, \fBASYNC_WAIT_CTX_get_all_fds()\fR, +\&\fBASYNC_WAIT_CTX_get_changed_fds()\fR and \fBASYNC_WAIT_CTX_clear_fd()\fR +were added in OpenSSL 1.1.0. +.PP +\&\fBASYNC_WAIT_CTX_set_callback()\fR, \fBASYNC_WAIT_CTX_get_callback()\fR, +\&\fBASYNC_WAIT_CTX_set_status()\fR, and \fBASYNC_WAIT_CTX_get_status()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ASYNC_start_job.3 b/static/netbsd/man3/ASYNC_start_job.3 new file mode 100644 index 00000000..b26beae0 --- /dev/null +++ b/static/netbsd/man3/ASYNC_start_job.3 @@ -0,0 +1,430 @@ +.\" $NetBSD: ASYNC_start_job.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ASYNC_start_job 3" +.TH ASYNC_start_job 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ASYNC_get_wait_ctx, +ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, +ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable, +ASYNC_stack_alloc_fn, ASYNC_stack_free_fn, ASYNC_set_mem_functions, ASYNC_get_mem_functions +\&\- asynchronous job management functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ASYNC_init_thread(size_t max_size, size_t init_size); +\& void ASYNC_cleanup_thread(void); +\& +\& int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret, +\& int (*func)(void *), void *args, size_t size); +\& int ASYNC_pause_job(void); +\& +\& ASYNC_JOB *ASYNC_get_current_job(void); +\& ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job); +\& void ASYNC_block_pause(void); +\& void ASYNC_unblock_pause(void); +\& +\& int ASYNC_is_capable(void); +\& +\& typedef void *(*ASYNC_stack_alloc_fn)(size_t *num); +\& typedef void (*ASYNC_stack_free_fn)(void *addr); +\& int ASYNC_set_mem_functions(ASYNC_stack_alloc_fn alloc_fn, +\& ASYNC_stack_free_fn free_fn); +\& void ASYNC_get_mem_functions(ASYNC_stack_alloc_fn *alloc_fn, +\& ASYNC_stack_free_fn *free_fn); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL implements asynchronous capabilities through an \fBASYNC_JOB\fR. This +represents code that can be started and executes until some event occurs. At +that point the code can be paused and control returns to user code until some +subsequent event indicates that the job can be resumed. It\*(Aqs OpenSSL +specific implementation of cooperative multitasking. +.PP +The creation of an \fBASYNC_JOB\fR is a relatively expensive operation. Therefore, +for efficiency reasons, jobs can be created up front and reused many times. They +are held in a pool until they are needed, at which point they are removed from +the pool, used, and then returned to the pool when the job completes. If the +user application is multi\-threaded, then \fBASYNC_init_thread()\fR may be called for +each thread that will initiate asynchronous jobs. Before +user code exits per\-thread resources need to be cleaned up. This will normally +occur automatically (see \fBOPENSSL_init_crypto\fR\|(3)) but may be explicitly +initiated by using \fBASYNC_cleanup_thread()\fR. No asynchronous jobs must be +outstanding for the thread when \fBASYNC_cleanup_thread()\fR is called. Failing to +ensure this will result in memory leaks. +.PP +The \fImax_size\fR argument limits the number of \fBASYNC_JOB\fRs that will be held in +the pool. If \fImax_size\fR is set to 0 then no upper limit is set. When an +\&\fBASYNC_JOB\fR is needed but there are none available in the pool already then one +will be automatically created, as long as the total of \fBASYNC_JOB\fRs managed by +the pool does not exceed \fImax_size\fR. When the pool is first initialised +\&\fIinit_size\fR \fBASYNC_JOB\fRs will be created immediately. If \fBASYNC_init_thread()\fR +is not called before the pool is first used then it will be called automatically +with a \fImax_size\fR of 0 (no upper limit) and an \fIinit_size\fR of 0 (no +\&\fBASYNC_JOB\fRs created up front). +.PP +An asynchronous job is started by calling the \fBASYNC_start_job()\fR function. +Initially \fI*job\fR should be NULL. \fIctx\fR should point to an \fBASYNC_WAIT_CTX\fR +object created through the \fBASYNC_WAIT_CTX_new\fR\|(3) function. \fIret\fR should +point to a location where the return value of the asynchronous function should +be stored on completion of the job. \fIfunc\fR represents the function that should +be started asynchronously. The data pointed to by \fIargs\fR and of size \fIsize\fR +will be copied and then passed as an argument to \fIfunc\fR when the job starts. +ASYNC_start_job will return one of the following values: +.IP \fBASYNC_ERR\fR 4 +.IX Item "ASYNC_ERR" +An error occurred trying to start the job. Check the OpenSSL error queue (e.g. +see \fBERR_print_errors\fR\|(3)) for more details. +.IP \fBASYNC_NO_JOBS\fR 4 +.IX Item "ASYNC_NO_JOBS" +There are no jobs currently available in the pool. This call can be retried +again at a later time. +.IP \fBASYNC_PAUSE\fR 4 +.IX Item "ASYNC_PAUSE" +The job was successfully started but was "paused" before it completed (see +\&\fBASYNC_pause_job()\fR below). A handle to the job is placed in \fI*job\fR. Other work +can be performed (if desired) and the job restarted at a later time. To restart +a job call \fBASYNC_start_job()\fR again passing the job handle in \fI*job\fR. The +\&\fIfunc\fR, \fIargs\fR and \fIsize\fR parameters will be ignored when restarting a job. +When restarting a job \fBASYNC_start_job()\fR \fBmust\fR be called from the same thread +that the job was originally started from. \fBASYNC_WAIT_CTX\fR is used to +know when a job is ready to be restarted. +.IP \fBASYNC_FINISH\fR 4 +.IX Item "ASYNC_FINISH" +The job completed. \fI*job\fR will be NULL and the return value from \fIfunc\fR will +be placed in \fI*ret\fR. +.PP +At any one time there can be a maximum of one job actively running per thread +(you can have many that are paused). \fBASYNC_get_current_job()\fR can be used to get +a pointer to the currently executing \fBASYNC_JOB\fR. If no job is currently +executing then this will return NULL. +.PP +If executing within the context of a job (i.e. having been called directly or +indirectly by the function "func" passed as an argument to \fBASYNC_start_job()\fR) +then \fBASYNC_pause_job()\fR will immediately return control to the calling +application with \fBASYNC_PAUSE\fR returned from the \fBASYNC_start_job()\fR call. A +subsequent call to ASYNC_start_job passing in the relevant \fBASYNC_JOB\fR in the +\&\fI*job\fR parameter will resume execution from the \fBASYNC_pause_job()\fR call. If +\&\fBASYNC_pause_job()\fR is called whilst not within the context of a job then no +action is taken and \fBASYNC_pause_job()\fR returns immediately. +.PP +\&\fBASYNC_get_wait_ctx()\fR can be used to get a pointer to the \fBASYNC_WAIT_CTX\fR +for the \fIjob\fR (see \fBASYNC_WAIT_CTX_new\fR\|(3)). +\&\fBASYNC_WAIT_CTX\fRs contain two different ways to notify +applications that a job is ready to be resumed. One is a "wait" file +descriptor, and the other is a "callback" mechanism. +.PP +The "wait" file descriptor associated with \fBASYNC_WAIT_CTX\fR is used for +applications to wait for the file descriptor to be ready for "read" using a +system function call such as \fBselect\fR\|(2) or \fBpoll\fR\|(2) (being ready for "read" +indicates +that the job should be resumed). If no file descriptor is made available then +an application will have to periodically "poll" the job by attempting to restart +it to see if it is ready to continue. +.PP +\&\fBASYNC_WAIT_CTX\fRs also have a "callback" mechanism to notify applications. The +callback is set by an application, and it will be automatically called when an +engine completes a cryptography operation, so that the application can resume +the paused work flow without polling. An engine could be written to look whether +the callback has been set. If it has then it would use the callback mechanism +in preference to the file descriptor notifications. If a callback is not set +then the engine may use file descriptor based notifications. Please note that +not all engines may support the callback mechanism, so the callback may not be +used even if it has been set. See \fBASYNC_WAIT_CTX_new()\fR for more details. +.PP +The \fBASYNC_block_pause()\fR function will prevent the currently active job from +pausing. The block will remain in place until a subsequent call to +\&\fBASYNC_unblock_pause()\fR. These functions can be nested, e.g. if you call +\&\fBASYNC_block_pause()\fR twice then you must call \fBASYNC_unblock_pause()\fR twice in +order to re\-enable pausing. If these functions are called while there is no +currently active job then they have no effect. This functionality can be useful +to avoid deadlock scenarios. For example during the execution of an \fBASYNC_JOB\fR +an application acquires a lock. It then calls some cryptographic function which +invokes \fBASYNC_pause_job()\fR. This returns control back to the code that created +the \fBASYNC_JOB\fR. If that code then attempts to acquire the same lock before +resuming the original job then a deadlock can occur. By calling +\&\fBASYNC_block_pause()\fR immediately after acquiring the lock and +\&\fBASYNC_unblock_pause()\fR immediately before releasing it then this situation cannot +occur. +.PP +Some platforms cannot support async operations. The \fBASYNC_is_capable()\fR function +can be used to detect whether the current platform is async capable or not. +.PP +Custom memory allocation functions are supported for the POSIX platform. +Custom memory allocation functions allow alternative methods of allocating +stack memory such as mmap, or using stack memory from the current thread. +Using an ASYNC_stack_alloc_fn callback also allows manipulation of the stack +size, which defaults to 32k. +The stack size can be altered by allocating a stack of a size different to +the requested size, and passing back the new stack size in the callback\*(Aqs \fI*num\fR +parameter. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +ASYNC_init_thread returns 1 on success or 0 otherwise. +.PP +ASYNC_start_job returns one of \fBASYNC_ERR\fR, \fBASYNC_NO_JOBS\fR, \fBASYNC_PAUSE\fR or +\&\fBASYNC_FINISH\fR as described above. +.PP +ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when +not within the context of an \fBASYNC_JOB\fR then this is counted as success so 1 +is returned. +.PP +ASYNC_get_current_job returns a pointer to the currently executing \fBASYNC_JOB\fR +or NULL if not within the context of a job. +.PP +\&\fBASYNC_get_wait_ctx()\fR returns a pointer to the \fBASYNC_WAIT_CTX\fR for the job. +.PP +\&\fBASYNC_is_capable()\fR returns 1 if the current platform is async capable or 0 +otherwise. +.PP +ASYNC_set_mem_functions returns 1 if custom stack allocators are supported by +the current platform and no allocations have already occurred or 0 otherwise. +.SH NOTES +.IX Header "NOTES" +On Windows platforms the \fI\fR header is dependent on some +of the types customarily made available by including \fI\fR. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore, +it is defined as an application developer\*(Aqs responsibility to include +\&\fI\fR prior to \fI\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following example demonstrates how to use most of the core async APIs: +.PP +.Vb 7 +\& #ifdef _WIN32 +\& # include +\& #endif +\& #include +\& #include +\& #include +\& #include +\& +\& int unique = 0; +\& +\& void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw) +\& { +\& OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw; +\& +\& close(r); +\& close(*w); +\& OPENSSL_free(w); +\& } +\& +\& int jobfunc(void *arg) +\& { +\& ASYNC_JOB *currjob; +\& unsigned char *msg; +\& int pipefds[2] = {0, 0}; +\& OSSL_ASYNC_FD *wptr; +\& char buf = \*(AqX\*(Aq; +\& +\& currjob = ASYNC_get_current_job(); +\& if (currjob != NULL) { +\& printf("Executing within a job\en"); +\& } else { +\& printf("Not executing within a job \- should not happen\en"); +\& return 0; +\& } +\& +\& msg = (unsigned char *)arg; +\& printf("Passed in message is: %s\en", msg); +\& +\& /* +\& * Create a way to inform the calling thread when this job is ready +\& * to resume, in this example we\*(Aqre using file descriptors. +\& * For offloading the task to an asynchronous ENGINE it\*(Aqs not necessary, +\& * the ENGINE should handle that internally. +\& */ +\& +\& if (pipe(pipefds) != 0) { +\& printf("Failed to create pipe\en"); +\& return 0; +\& } +\& wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD)); +\& if (wptr == NULL) { +\& printf("Failed to malloc\en"); +\& return 0; +\& } +\& *wptr = pipefds[1]; +\& ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique, +\& pipefds[0], wptr, cleanup); +\& +\& /* +\& * Normally some external event (like a network read being ready, +\& * disk access being finished, or some hardware offload operation +\& * completing) would cause this to happen at some +\& * later point \- but we do it here for demo purposes, i.e. +\& * immediately signalling that the job is ready to be woken up after +\& * we return to main via ASYNC_pause_job(). +\& */ +\& write(pipefds[1], &buf, 1); +\& +\& /* +\& * Return control back to main just before calling a blocking +\& * method. The main thread will wait until pipefds[0] is ready +\& * for reading before returning control to this thread. +\& */ +\& ASYNC_pause_job(); +\& +\& /* Perform the blocking call (it won\*(Aqt block with this example code) */ +\& read(pipefds[0], &buf, 1); +\& +\& printf ("Resumed the job after a pause\en"); +\& +\& return 1; +\& } +\& +\& int main(void) +\& { +\& ASYNC_JOB *job = NULL; +\& ASYNC_WAIT_CTX *ctx = NULL; +\& int ret; +\& OSSL_ASYNC_FD waitfd; +\& fd_set waitfdset; +\& size_t numfds; +\& unsigned char msg[13] = "Hello world!"; +\& +\& printf("Starting...\en"); +\& +\& ctx = ASYNC_WAIT_CTX_new(); +\& if (ctx == NULL) { +\& printf("Failed to create ASYNC_WAIT_CTX\en"); +\& abort(); +\& } +\& +\& for (;;) { +\& switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) { +\& case ASYNC_ERR: +\& case ASYNC_NO_JOBS: +\& printf("An error occurred\en"); +\& goto end; +\& case ASYNC_PAUSE: +\& printf("Job was paused\en"); +\& break; +\& case ASYNC_FINISH: +\& printf("Job finished with return value %d\en", ret); +\& goto end; +\& } +\& +\& /* Get the file descriptor we can use to wait for the job +\& * to be ready to be woken up +\& */ +\& printf("Waiting for the job to be woken up\en"); +\& +\& if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds) +\& || numfds > 1) { +\& printf("Unexpected number of fds\en"); +\& abort(); +\& } +\& ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds); +\& FD_ZERO(&waitfdset); +\& FD_SET(waitfd, &waitfdset); +\& +\& /* Wait for the job to be ready for wakeup */ +\& select(waitfd + 1, &waitfdset, NULL, NULL, NULL); +\& } +\& +\& end: +\& ASYNC_WAIT_CTX_free(ctx); +\& printf("Finishing\en"); +\& +\& return 0; +\& } +.Ve +.PP +The expected output from executing the above example program is: +.PP +.Vb 8 +\& Starting... +\& Executing within a job +\& Passed in message is: Hello world! +\& Job was paused +\& Waiting for the job to be woken up +\& Resumed the job after a pause +\& Job finished with return value 1 +\& Finishing +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBERR_print_errors\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +ASYNC_init_thread, ASYNC_cleanup_thread, +ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, \fBASYNC_get_wait_ctx()\fR, +\&\fBASYNC_block_pause()\fR, \fBASYNC_unblock_pause()\fR and \fBASYNC_is_capable()\fR were first +added in OpenSSL 1.1.0. +\&\fBASYNC_set_mem_functions()\fR, \fBASYNC_get_mem_functions()\fR were added +in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BF_encrypt.3 b/static/netbsd/man3/BF_encrypt.3 new file mode 100644 index 00000000..41416077 --- /dev/null +++ b/static/netbsd/man3/BF_encrypt.3 @@ -0,0 +1,190 @@ +.\" $NetBSD: BF_encrypt.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BF_encrypt 3" +.TH BF_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options \- Blowfish encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void BF_set_key(BF_KEY *key, int len, const unsigned char *data); +\& +\& void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, +\& BF_KEY *key, int enc); +\& void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, +\& unsigned char *ivec, int enc); +\& void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, +\& unsigned char *ivec, int *num, int enc); +\& void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, +\& unsigned char *ivec, int *num); +\& const char *BF_options(void); +\& +\& void BF_encrypt(BF_LONG *data, const BF_KEY *key); +\& void BF_decrypt(BF_LONG *data, const BF_KEY *key); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. Applications should +instead use \fBEVP_EncryptInit_ex\fR\|(3), \fBEVP_EncryptUpdate\fR\|(3) and +\&\fBEVP_EncryptFinal_ex\fR\|(3) or the equivalently named decrypt functions. +.PP +This library implements the Blowfish cipher, which was invented and described +by Counterpane (see http://www.counterpane.com/blowfish.html ). +.PP +Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. +It uses a variable size key, but typically, 128 bit (16 byte) keys are +considered good for strong encryption. Blowfish can be used in the same +modes as DES (see \fBdes_modes\fR\|(7)). Blowfish is currently one +of the faster block ciphers. It is quite a bit faster than DES, and much +faster than IDEA or RC2. +.PP +Blowfish consists of a key setup phase and the actual encryption or decryption +phase. +.PP +\&\fBBF_set_key()\fR sets up the \fBBF_KEY\fR \fBkey\fR using the \fBlen\fR bytes long key +at \fBdata\fR. +.PP +\&\fBBF_ecb_encrypt()\fR is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of \fBin\fR using the key \fBkey\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fBBF_ENCRYPT\fR) +or decryption (\fBBF_DECRYPT\fR) shall be performed. The vector pointed at by +\&\fBin\fR and \fBout\fR must be 64 bits in length, no less. If they are larger, +everything after the first 64 bits is ignored. +.PP +The mode functions \fBBF_cbc_encrypt()\fR, \fBBF_cfb64_encrypt()\fR and \fBBF_ofb64_encrypt()\fR +all operate on variable length data. They all take an initialization vector +\&\fBivec\fR which needs to be passed along into the next call of the same function +for the same message. \fBivec\fR may be initialized with anything, but the +recipient needs to know what it was initialized with, or it won\*(Aqt be able +to decrypt. Some programs and protocols simplify this, like SSH, where +\&\fBivec\fR is simply initialized to zero. +\&\fBBF_cbc_encrypt()\fR operates on data that is a multiple of 8 bytes long, while +\&\fBBF_cfb64_encrypt()\fR and \fBBF_ofb64_encrypt()\fR are used to encrypt a variable +number of bytes (the amount does not have to be an exact multiple of 8). The +purpose of the latter two is to simulate stream ciphers, and therefore, they +need the parameter \fBnum\fR, which is a pointer to an integer where the current +offset in \fBivec\fR is stored between calls. This integer must be initialized +to zero when \fBivec\fR is initialized. +.PP +\&\fBBF_cbc_encrypt()\fR is the Cipher Block Chaining function for Blowfish. It +encrypts or decrypts the 64 bits chunks of \fBin\fR using the key \fBschedule\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (BF_ENCRYPT) or +decryption (BF_DECRYPT) shall be performed. \fBivec\fR must point at an 8 byte +long initialization vector. +.PP +\&\fBBF_cfb64_encrypt()\fR is the CFB mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in \fBin\fR using the key \fBschedule\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fBBF_ENCRYPT\fR) +or decryption (\fBBF_DECRYPT\fR) shall be performed. \fBivec\fR must point at an +8 byte long initialization vector. \fBnum\fR must point at an integer which must +be initially zero. +.PP +\&\fBBF_ofb64_encrypt()\fR is the OFB mode for Blowfish with 64 bit feedback. +It uses the same parameters as \fBBF_cfb64_encrypt()\fR, which must be initialized +the same way. +.PP +\&\fBBF_encrypt()\fR and \fBBF_decrypt()\fR are the lowest level functions for Blowfish +encryption. They encrypt/decrypt the first 64 bits of the vector pointed by +\&\fBdata\fR, using the key \fBkey\fR. These functions should not be used unless you +implement \*(Aqmodes\*(Aq of Blowfish. The alternative is to use \fBBF_ecb_encrypt()\fR. +If you still want to use these functions, you should be aware that they take +each 32\-bit chunk in host\-byte order, which is little\-endian on little\-endian +platforms and big\-endian on big\-endian ones. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +None of the functions presented here return any value. +.SH NOTE +.IX Header "NOTE" +Applications should use the higher level functions +\&\fBEVP_EncryptInit\fR\|(3) etc. instead of calling these +functions directly. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBdes_modes\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_ADDR.3 b/static/netbsd/man3/BIO_ADDR.3 new file mode 100644 index 00000000..aa2d8ebc --- /dev/null +++ b/static/netbsd/man3/BIO_ADDR.3 @@ -0,0 +1,198 @@ +.\" $NetBSD: BIO_ADDR.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_ADDR 3" +.TH BIO_ADDR 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear, +BIO_ADDR_free, BIO_ADDR_rawmake, +BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, +BIO_ADDR_hostname_string, BIO_ADDR_service_string, +BIO_ADDR_path_string \- BIO_ADDR routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& typedef union bio_addr_st BIO_ADDR; +\& +\& BIO_ADDR *BIO_ADDR_new(void); +\& int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src); +\& BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap); +\& void BIO_ADDR_free(BIO_ADDR *ap); +\& void BIO_ADDR_clear(BIO_ADDR *ap); +\& int BIO_ADDR_rawmake(BIO_ADDR *ap, int family, +\& const void *where, size_t wherelen, unsigned short port); +\& int BIO_ADDR_family(const BIO_ADDR *ap); +\& int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l); +\& unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap); +\& char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric); +\& char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric); +\& char *BIO_ADDR_path_string(const BIO_ADDR *ap); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_ADDR\fR type is a wrapper around all types of socket +addresses that OpenSSL deals with, currently transparently +supporting AF_INET, AF_INET6 and AF_UNIX according to what\*(Aqs +available on the platform at hand. +.PP +\&\fBBIO_ADDR_new()\fR creates a new unfilled \fBBIO_ADDR\fR, to be used +with routines that will fill it with information, such as +\&\fBBIO_accept_ex()\fR. +.PP +\&\fBBIO_ADDR_copy()\fR copies the contents of \fBsrc\fR into \fBdst\fR. Neither \fBsrc\fR or +\&\fBdst\fR can be NULL. +.PP +\&\fBBIO_ADDR_dup()\fR creates a new \fBBIO_ADDR\fR, with a copy of the +address data in \fBap\fR. +.PP +\&\fBBIO_ADDR_free()\fR frees a \fBBIO_ADDR\fR created with \fBBIO_ADDR_new()\fR +or \fBBIO_ADDR_dup()\fR. If the argument is NULL, nothing is done. +.PP +\&\fBBIO_ADDR_clear()\fR clears any data held within the provided \fBBIO_ADDR\fR and sets +it back to an uninitialised state. +.PP +\&\fBBIO_ADDR_rawmake()\fR takes a protocol \fBfamily\fR, a byte array of +size \fBwherelen\fR with an address in network byte order pointed at +by \fBwhere\fR and a port number in network byte order in \fBport\fR (except +for the \fBAF_UNIX\fR protocol family, where \fBport\fR is meaningless and +therefore ignored) and populates the given \fBBIO_ADDR\fR with them. +In case this creates a \fBAF_UNIX\fR \fBBIO_ADDR\fR, \fBwherelen\fR is expected +to be the length of the path string (not including the terminating +NUL, such as the result of a call to \fBstrlen()\fR). +Read on about the addresses in "RAW ADDRESSES" below. +.PP +\&\fBBIO_ADDR_family()\fR returns the protocol family of the given +\&\fBBIO_ADDR\fR. The possible non\-error results are one of the +constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the +BIO_ADDR has not been initialised. +.PP +\&\fBBIO_ADDR_rawaddress()\fR will write the raw address of the given +\&\fBBIO_ADDR\fR in the area pointed at by \fBp\fR if \fBp\fR is non\-NULL, +and will set \fB*l\fR to be the amount of bytes the raw address +takes up if \fBl\fR is non\-NULL. +A technique to only find out the size of the address is a call +with \fBp\fR set to \fBNULL\fR. The raw address will be in network byte +order, most significant byte first. +In case this is a \fBAF_UNIX\fR \fBBIO_ADDR\fR, \fBl\fR gets the length of the +path string (not including the terminating NUL, such as the result of +a call to \fBstrlen()\fR). +Read on about the addresses in "RAW ADDRESSES" below. +.PP +\&\fBBIO_ADDR_rawport()\fR returns the raw port of the given \fBBIO_ADDR\fR. +The raw port will be in network byte order. +.PP +\&\fBBIO_ADDR_hostname_string()\fR returns a character string with the +hostname of the given \fBBIO_ADDR\fR. If \fBnumeric\fR is 1, the string +will contain the numerical form of the address. This only works for +\&\fBBIO_ADDR\fR of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with \fBOPENSSL_free()\fR. +.PP +\&\fBBIO_ADDR_service_string()\fR returns a character string with the +service name of the port of the given \fBBIO_ADDR\fR. If \fBnumeric\fR +is 1, the string will contain the port number. This only works +for \fBBIO_ADDR\fR of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with \fBOPENSSL_free()\fR. +.PP +\&\fBBIO_ADDR_path_string()\fR returns a character string with the path +of the given \fBBIO_ADDR\fR. This only works for \fBBIO_ADDR\fR of the +protocol family AF_UNIX. The returned string has been allocated +on the heap and must be freed with \fBOPENSSL_free()\fR. +.SH "RAW ADDRESSES" +.IX Header "RAW ADDRESSES" +Both \fBBIO_ADDR_rawmake()\fR and \fBBIO_ADDR_rawaddress()\fR take a pointer to a +network byte order address of a specific site. Internally, those are +treated as a pointer to \fBstruct in_addr\fR (for \fBAF_INET\fR), \fBstruct +in6_addr\fR (for \fBAF_INET6\fR) or \fBchar *\fR (for \fBAF_UNIX\fR), all +depending on the protocol family the address is for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The string producing functions \fBBIO_ADDR_hostname_string()\fR, +\&\fBBIO_ADDR_service_string()\fR and \fBBIO_ADDR_path_string()\fR will +return \fBNULL\fR on error and leave an error indication on the +OpenSSL error stack. +.PP +\&\fBBIO_ADDR_copy()\fR returns 1 on success or 0 on error. +.PP +All other functions described here return 0 or \fBNULL\fR when the +information they should return isn\*(Aqt available. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_connect\fR\|(3), \fBBIO_s_connect\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_ADDR_copy()\fR and \fBBIO_ADDR_dup()\fR were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_ADDRINFO.3 b/static/netbsd/man3/BIO_ADDRINFO.3 new file mode 100644 index 00000000..abf72806 --- /dev/null +++ b/static/netbsd/man3/BIO_ADDRINFO.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: BIO_ADDRINFO.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_ADDRINFO 3" +.TH BIO_ADDRINFO 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_lookup_type, +BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, +BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, +BIO_ADDRINFO_address, +BIO_lookup_ex, +BIO_lookup +\&\- BIO_ADDRINFO type and routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& typedef union bio_addrinfo_st BIO_ADDRINFO; +\& +\& enum BIO_lookup_type { +\& BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER +\& }; +\& +\& int BIO_lookup_ex(const char *host, const char *service, int lookup_type, +\& int family, int socktype, int protocol, BIO_ADDRINFO **res); +\& int BIO_lookup(const char *host, const char *service, +\& enum BIO_lookup_type lookup_type, +\& int family, int socktype, BIO_ADDRINFO **res); +\& +\& const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai); +\& int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai); +\& int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai); +\& int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai); +\& const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai); +\& void BIO_ADDRINFO_free(BIO_ADDRINFO *bai); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_ADDRINFO\fR type is a wrapper for address information +types provided on your platform. +.PP +\&\fBBIO_ADDRINFO\fR normally forms a chain of several that can be +picked at one by one. +.PP +\&\fBBIO_lookup_ex()\fR looks up a specified \fBhost\fR and \fBservice\fR, and +uses \fBlookup_type\fR to determine what the default address should +be if \fBhost\fR is \fBNULL\fR. \fBfamily\fR, \fBsocktype\fR and \fBprotocol\fR are used to +determine what protocol family, socket type and protocol should be used for +the lookup. \fBfamily\fR can be any of AF_INET, AF_INET6, AF_UNIX and +AF_UNSPEC. \fBsocktype\fR can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0 +indicates that any type can be used. \fBprotocol\fR specifies a protocol such as +IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be +used. \fBres\fR points at a pointer to hold the start of a \fBBIO_ADDRINFO\fR +chain. +.PP +For the family \fBAF_UNIX\fR, \fBBIO_lookup_ex()\fR will ignore the \fBservice\fR +parameter and expects the \fBhost\fR parameter to hold the path to the socket file. +.PP +\&\fBBIO_lookup()\fR does the same as \fBBIO_lookup_ex()\fR but does not provide the ability +to select based on the protocol (any protocol may be returned). +.PP +\&\fBBIO_ADDRINFO_family()\fR returns the family of the given +\&\fBBIO_ADDRINFO\fR. The result will be one of the constants +AF_INET, AF_INET6 and AF_UNIX. +.PP +\&\fBBIO_ADDRINFO_socktype()\fR returns the socket type of the given +\&\fBBIO_ADDRINFO\fR. The result will be one of the constants +SOCK_STREAM and SOCK_DGRAM. +.PP +\&\fBBIO_ADDRINFO_protocol()\fR returns the protocol id of the given +\&\fBBIO_ADDRINFO\fR. The result will be one of the constants +IPPROTO_TCP and IPPROTO_UDP. +.PP +\&\fBBIO_ADDRINFO_address()\fR returns the underlying \fBBIO_ADDR\fR +of the given \fBBIO_ADDRINFO\fR. +.PP +\&\fBBIO_ADDRINFO_next()\fR returns the next \fBBIO_ADDRINFO\fR in the chain +from the given one. +.PP +\&\fBBIO_ADDRINFO_free()\fR frees the chain of \fBBIO_ADDRINFO\fR starting +with the given one. If the argument is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_lookup_ex()\fR and \fBBIO_lookup()\fR return 1 on success and 0 when an error +occurred, and will leave an error indication on the OpenSSL error stack in that +case. +.PP +All other functions described here return 0 or \fBNULL\fR when the +information they should return isn\*(Aqt available. +.SH NOTES +.IX Header "NOTES" +The \fBBIO_lookup_ex()\fR implementation uses the platform provided \fBgetaddrinfo()\fR +function. On Linux it is known that specifying 0 for the protocol will not +return any SCTP based addresses when calling \fBgetaddrinfo()\fR. Therefore, if an SCTP +address is required then the \fBprotocol\fR parameter to \fBBIO_lookup_ex()\fR should be +explicitly set to IPPROTO_SCTP. The same may be true on other platforms. +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_lookup_ex()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_connect.3 b/static/netbsd/man3/BIO_connect.3 new file mode 100644 index 00000000..d7c44298 --- /dev/null +++ b/static/netbsd/man3/BIO_connect.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: BIO_connect.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_connect 3" +.TH BIO_connect 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket \- BIO +socket communication setup routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BIO_socket(int domain, int socktype, int protocol, int options); +\& int BIO_bind(int sock, const BIO_ADDR *addr, int options); +\& int BIO_connect(int sock, const BIO_ADDR *addr, int options); +\& int BIO_listen(int sock, const BIO_ADDR *addr, int options); +\& int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); +\& int BIO_closesocket(int sock); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_socket()\fR creates a socket in the domain \fBdomain\fR, of type +\&\fBsocktype\fR and \fBprotocol\fR. Socket \fBoptions\fR are currently unused, +but is present for future use. +.PP +\&\fBBIO_bind()\fR binds the source address and service to a socket and +may be useful before calling \fBBIO_connect()\fR. The options may include +\&\fBBIO_SOCK_REUSEADDR\fR, which is described in "FLAGS" below. +.PP +\&\fBBIO_connect()\fR connects \fBsock\fR to the address and service given by +\&\fBaddr\fR. Connection \fBoptions\fR may be zero or any combination of +\&\fBBIO_SOCK_KEEPALIVE\fR, \fBBIO_SOCK_NONBLOCK\fR and \fBBIO_SOCK_NODELAY\fR. +The flags are described in "FLAGS" below. +.PP +\&\fBBIO_listen()\fR has \fBsock\fR start listening on the address and service +given by \fBaddr\fR. Connection \fBoptions\fR may be zero or any +combination of \fBBIO_SOCK_KEEPALIVE\fR, \fBBIO_SOCK_NONBLOCK\fR, +\&\fBBIO_SOCK_NODELAY\fR, \fBBIO_SOCK_REUSEADDR\fR and \fBBIO_SOCK_V6_ONLY\fR. +The flags are described in "FLAGS" below. +.PP +\&\fBBIO_accept_ex()\fR waits for an incoming connections on the given +socket \fBaccept_sock\fR. When it gets a connection, the address and +port of the peer gets stored in \fBpeer\fR if that one is non\-NULL. +Accept \fBoptions\fR may be zero or \fBBIO_SOCK_NONBLOCK\fR, and is applied +on the accepted socket. The flags are described in "FLAGS" below. +.PP +\&\fBBIO_closesocket()\fR closes \fBsock\fR. +.SH FLAGS +.IX Header "FLAGS" +.IP BIO_SOCK_KEEPALIVE 4 +.IX Item "BIO_SOCK_KEEPALIVE" +Enables regular sending of keep\-alive messages. +.IP BIO_SOCK_NONBLOCK 4 +.IX Item "BIO_SOCK_NONBLOCK" +Sets the socket to nonblocking mode. +.IP BIO_SOCK_NODELAY 4 +.IX Item "BIO_SOCK_NODELAY" +Corresponds to \fBTCP_NODELAY\fR, and disables the Nagle algorithm. With +this set, any data will be sent as soon as possible instead of being +buffered until there\*(Aqs enough for the socket to send out in one go. +.IP BIO_SOCK_REUSEADDR 4 +.IX Item "BIO_SOCK_REUSEADDR" +Try to reuse the address and port combination for a recently closed +port. +.IP BIO_SOCK_V6_ONLY 4 +.IX Item "BIO_SOCK_V6_ONLY" +When creating an IPv6 socket, make it only listen for IPv6 addresses +and not IPv4 addresses mapped to IPv6. +.IP BIO_SOCK_TFO 4 +.IX Item "BIO_SOCK_TFO" +Enables TCP Fast Open on the socket. Uses appropriate APIs on +supported operating systems, including Linux, macOS and FreeBSD. Can +be used with \fBBIO_connect()\fR, \fBBIO_set_conn_mode()\fR, \fBBIO_set_bind_mode()\fR, +and \fBBIO_listen()\fR. +On Linux kernels before 4.14, use \fBBIO_set_conn_address()\fR to specify +the peer address before starting the TLS handshake. +.PP +These flags are bit flags, so they are to be combined with the +\&\f(CW\*(C`|\*(C'\fR operator, for example: +.PP +.Vb 1 +\& BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_socket()\fR returns the socket number on success or \fBINVALID_SOCKET\fR +(\-1) on error. When an error has occurred, the OpenSSL error stack +will hold the error data and errno has the system error. +.PP +\&\fBBIO_bind()\fR, \fBBIO_connect()\fR and \fBBIO_listen()\fR return 1 on success or 0 on error. +When an error has occurred, the OpenSSL error stack will hold the error +data and errno has the system error. +.PP +\&\fBBIO_accept_ex()\fR returns the accepted socket on success or +\&\fBINVALID_SOCKET\fR (\-1) on error. When an error has occurred, the +OpenSSL error stack will hold the error data and errno has the system +error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_ADDR\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_gethostname()\fR, \fBBIO_get_port()\fR, \fBBIO_get_host_ip()\fR, +\&\fBBIO_get_accept_socket()\fR and \fBBIO_accept()\fR were deprecated in OpenSSL 1.1.0. +Use the functions described above instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_ctrl.3 b/static/netbsd/man3/BIO_ctrl.3 new file mode 100644 index 00000000..377369fb --- /dev/null +++ b/static/netbsd/man3/BIO_ctrl.3 @@ -0,0 +1,248 @@ +.\" $NetBSD: BIO_ctrl.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_ctrl 3" +.TH BIO_ctrl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, +BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, +BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, +BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, +BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo +\&\- BIO control operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int BIO_info_cb(BIO *b, int state, int res); +\& +\& long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); +\& long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb); +\& void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); +\& long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); +\& +\& int BIO_reset(BIO *b); +\& int BIO_seek(BIO *b, int ofs); +\& int BIO_tell(BIO *b); +\& int BIO_flush(BIO *b); +\& int BIO_eof(BIO *b); +\& int BIO_set_close(BIO *b, long flag); +\& int BIO_get_close(BIO *b); +\& int BIO_pending(BIO *b); +\& int BIO_wpending(BIO *b); +\& size_t BIO_ctrl_pending(BIO *b); +\& size_t BIO_ctrl_wpending(BIO *b); +\& +\& int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp); +\& int BIO_set_info_callback(BIO *b, BIO_info_cb *cb); +\& +\& int BIO_get_ktls_send(BIO *b); +\& int BIO_get_ktls_recv(BIO *b); +\& +\& int BIO_set_conn_mode(BIO *b, int mode); +\& int BIO_get_conn_mode(BIO *b); +\& +\& int BIO_set_tfo(BIO *b, int onoff); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_ctrl()\fR, \fBBIO_callback_ctrl()\fR, \fBBIO_ptr_ctrl()\fR and \fBBIO_int_ctrl()\fR +are BIO "control" operations taking arguments of various types. +These functions are not normally called directly, various macros +are used instead. The standard macros are described below, macros +specific to a particular type of BIO are described in the specific +BIOs manual page as well as any special features of the standard +calls. +.PP +\&\fBBIO_reset()\fR typically resets a BIO to some initial state, in the case +of file related BIOs for example it rewinds the file pointer to the +start of the file. +.PP +\&\fBBIO_seek()\fR resets a file related BIO\*(Aqs (that is file descriptor and +FILE BIOs) file position pointer to \fBofs\fR bytes from start of file. +.PP +\&\fBBIO_tell()\fR returns the current file position of a file related BIO. +.PP +\&\fBBIO_flush()\fR normally writes out any internally buffered data, in some +cases it is used to signal EOF and that no more data will be written. +.PP +\&\fBBIO_eof()\fR returns 1 if the BIO has read EOF, the precise meaning of +"EOF" varies according to the BIO type. +.PP +\&\fBBIO_set_close()\fR sets the BIO \fBb\fR close flag to \fBflag\fR. \fBflag\fR can +take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used +in a source/sink BIO to indicate that the underlying I/O stream should +be closed when the BIO is freed. +.PP +\&\fBBIO_get_close()\fR returns the BIOs close flag. +.PP +\&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR +return the number of pending characters in the BIOs read and write buffers. +Not all BIOs support these calls. \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR +return a size_t type and are functions, \fBBIO_pending()\fR and \fBBIO_wpending()\fR are +macros which call \fBBIO_ctrl()\fR. +.PP +\&\fBBIO_get_ktls_send()\fR returns 1 if the BIO is using the Kernel TLS data\-path for +sending. Otherwise, it returns zero. +\&\fBBIO_get_ktls_recv()\fR returns 1 if the BIO is using the Kernel TLS data\-path for +receiving. Otherwise, it returns zero. +.PP +\&\fBBIO_get_conn_mode()\fR returns the BIO connection mode. \fBBIO_set_conn_mode()\fR sets +the BIO connection mode. +.PP +\&\fBBIO_set_tfo()\fR disables TCP Fast Open when \fBonoff\fR is 0, and enables TCP Fast +Open when \fBonoff\fR is nonzero. Setting the value to 1 is equivalent to setting +\&\fBBIO_SOCK_TFO\fR in \fBBIO_set_conn_mode()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_reset()\fR normally returns 1 for success and <=0 for failure. File +BIOs are an exception, they return 0 for success and \-1 for failure. +.PP +\&\fBBIO_seek()\fR and \fBBIO_tell()\fR both return the current file position on success +and \-1 for failure, except file BIOs which for \fBBIO_seek()\fR always return 0 +for success and \-1 for failure. +.PP +\&\fBBIO_flush()\fR returns 1 for success and <=0 for failure. +.PP +\&\fBBIO_eof()\fR returns 1 if EOF has been reached, 0 if not, or negative values for failure. +.PP +\&\fBBIO_set_close()\fR returns 1 on success or <=0 for failure. +.PP +\&\fBBIO_get_close()\fR returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also +returns other negative values if an error occurs. +.PP +\&\fBBIO_pending()\fR, \fBBIO_ctrl_pending()\fR, \fBBIO_wpending()\fR and \fBBIO_ctrl_wpending()\fR +return the amount of pending data. \fBBIO_pending()\fR and \fBBIO_wpending()\fR return +negative value or 0 on error. \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR return +0 on error. +.PP +\&\fBBIO_get_ktls_send()\fR returns 1 if the BIO is using the Kernel TLS data\-path for +sending. Otherwise, it returns zero. +\&\fBBIO_get_ktls_recv()\fR returns 1 if the BIO is using the Kernel TLS data\-path for +receiving. Otherwise, it returns zero. +.PP +\&\fBBIO_set_conn_mode()\fR returns 1 for success and 0 for failure. \fBBIO_get_conn_mode()\fR +returns the current connection mode. Which may contain the bitwise\-or of the +following flags: +.PP +.Vb 6 +\& BIO_SOCK_REUSEADDR +\& BIO_SOCK_V6_ONLY +\& BIO_SOCK_KEEPALIVE +\& BIO_SOCK_NONBLOCK +\& BIO_SOCK_NODELAY +\& BIO_SOCK_TFO +.Ve +.PP +\&\fBBIO_set_tfo()\fR returns 1 for success, and 0 for failure. +.SH NOTES +.IX Header "NOTES" +\&\fBBIO_flush()\fR, because it can write data may return 0 or \-1 indicating +that the call should be retried later in a similar manner to \fBBIO_write_ex()\fR. +The \fBBIO_should_retry()\fR call should be used and appropriate action taken +is the call fails. +.PP +The return values of \fBBIO_pending()\fR and \fBBIO_wpending()\fR may not reliably +determine the amount of pending data in all cases. For example in the +case of a file BIO some data may be available in the FILE structures +internal buffers but it is not possible to determine this in a +portably way. For other types of BIO they may not be supported. +.PP +Filter BIOs if they do not internally handle a particular \fBBIO_ctrl()\fR +operation usually pass the operation to the next BIO in the chain. +This often means there is no need to locate the required BIO for +a particular operation, it can be called on a chain and it will +be automatically passed to the relevant BIO. However, this can cause +unexpected results: for example no current filter BIOs implement +\&\fBBIO_seek()\fR, but this may still succeed if the chain ends in a FILE +or file descriptor BIO. +.PP +Source/sink BIOs return an 0 if they do not recognize the \fBBIO_ctrl()\fR +operation. +.SH BUGS +.IX Header "BUGS" +Some of the return values are ambiguous and care should be taken. In +particular a return value of 0 can be returned if an operation is not +supported, if an error occurred, if EOF has not been reached and in +the case of \fBBIO_seek()\fR on a file BIO for a successful operation. +.PP +In older versions of OpenSSL the \fBBIO_ctrl_pending()\fR and +\&\fBBIO_ctrl_wpending()\fR could return values greater than INT_MAX on error. +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_get_ktls_send()\fR and \fBBIO_get_ktls_recv()\fR macros were added in +OpenSSL 3.0. They were modified to never return \-1 in OpenSSL 3.0.4. +.PP +The \fBBIO_get_conn_mode()\fR, \fBBIO_set_conn_mode()\fR and \fBBIO_set_tfo()\fR functions +were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_base64.3 b/static/netbsd/man3/BIO_f_base64.3 new file mode 100644 index 00000000..e101d01c --- /dev/null +++ b/static/netbsd/man3/BIO_f_base64.3 @@ -0,0 +1,194 @@ +.\" $NetBSD: BIO_f_base64.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_base64 3" +.TH BIO_f_base64 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_base64 \- base64 BIO filter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& const BIO_METHOD *BIO_f_base64(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_base64()\fR returns the base64 BIO method. This is a filter +BIO that base64 encodes any data written through it and decodes +any data read through it. +.PP +Base64 BIOs do not support \fBBIO_gets()\fR or \fBBIO_puts()\fR. +.PP +For writing, by default output is divided to lines of length 64 +characters and there is a newline at the end of output. +This behavior can be changed with \fBBIO_FLAGS_BASE64_NO_NL\fR flag. +.PP +For reading, the first line of base64 content should be at most 1024 bytes long +including newline unless the flag \fBBIO_FLAGS_BASE64_NO_NL\fR is set. +Subsequent input lines can be of any length (i.e., newlines may appear anywhere +in the input) and a newline at the end of input is not needed. +.PP +Also when reading, unless the flag \fBBIO_FLAGS_BASE64_NO_NL\fR is set, initial +lines that contain non\-base64 content (whitespace is tolerated and ignored) are +skipped, as are lines longer than 1024 bytes. +Decoding starts with the first line that is shorter than 1024 bytes (including +the newline) and consists of only (at least one) valid base64 characters plus +optional whitespace. +Decoding stops when base64 padding is encountered, a soft end\-of\-input +character (\fB\-\fR, see \fBEVP_DecodeUpdate\fR\|(3)) occurs as the first byte after a +complete group of 4 valid base64 characters is decoded, or when an error occurs +(e.g. due to input characters other than valid base64 or whitespace). +.PP +If decoding stops as a result of an error, the first \fBBIO_read\fR\|(3) that +returns no decoded data will typically return a negative result, rather +than 0 (which indicates normal end of input). +However, a negative return value can also occur if the underlying BIO +supports retries, see \fBBIO_should_read\fR\|(3) and \fBBIO_set_mem_eof_return\fR\|(3). +.PP +\&\fBBIO_flush()\fR on a base64 BIO that is being written through is +used to signal that no more data is to be encoded: this is used +to flush the final block through the BIO. +.PP +The flag \fBBIO_FLAGS_BASE64_NO_NL\fR can be set with \fBBIO_set_flags()\fR. +For writing, it causes all data to be written on one line without +newline at the end. +For reading, it removes all expectations on newlines in the input data. +.SH NOTES +.IX Header "NOTES" +Because of the format of base64 encoding the end of the encoded +block cannot always be reliably determined. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_base64()\fR returns the base64 BIO method. +.SH EXAMPLES +.IX Header "EXAMPLES" +Base64 encode the string "Hello World\en" and write the result +to standard output: +.PP +.Vb 2 +\& BIO *bio, *b64; +\& char message[] = "Hello World \en"; +\& +\& b64 = BIO_new(BIO_f_base64()); +\& bio = BIO_new_fp(stdout, BIO_NOCLOSE); +\& BIO_push(b64, bio); +\& BIO_write(b64, message, strlen(message)); +\& BIO_flush(b64); +\& +\& BIO_free_all(b64); +.Ve +.PP +Read base64 encoded data from standard input and write the decoded +data to standard output: +.PP +.Vb 3 +\& BIO *bio, *b64, *bio_out; +\& char inbuf[512]; +\& int inlen; +\& +\& b64 = BIO_new(BIO_f_base64()); +\& bio = BIO_new_fp(stdin, BIO_NOCLOSE); +\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); +\& BIO_push(b64, bio); +\& while ((inlen = BIO_read(b64, inbuf, 512)) > 0) +\& BIO_write(bio_out, inbuf, inlen); +\& +\& BIO_flush(bio_out); +\& BIO_free_all(b64); +.Ve +.SH BUGS +.IX Header "BUGS" +The hyphen character (\fB\-\fR) is treated as an ad hoc soft end\-of\-input +character when it occurs at the start of a base64 group of 4 encoded +characters. +.PP +This heuristic works to detect the ends of base64 blocks in PEM or +multi\-part MIME, provided there are no stray hyphens in the middle +input. +But it is just a heuristic, and sufficiently unusual input could produce +unexpected results. +.PP +There should perhaps be some way of specifying a test that the BIO can perform +to reliably determine EOF (for example a MIME boundary). +.PP +It may be possible for \fBBIO_read\fR\|(3) to return zero, rather than \-1, even if +an error has been detected, more tests are needed to cover all the potential +error paths. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_read\fR\|(3), +\&\fBBIO_should_read\fR\|(3), +\&\fBBIO_set_mem_eof_return\fR\|(3), +\&\fBEVP_DecodeUpdate\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_buffer.3 b/static/netbsd/man3/BIO_f_buffer.3 new file mode 100644 index 00000000..31a6400c --- /dev/null +++ b/static/netbsd/man3/BIO_f_buffer.3 @@ -0,0 +1,161 @@ +.\" $NetBSD: BIO_f_buffer.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_buffer 3" +.TH BIO_f_buffer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_get_buffer_num_lines, +BIO_set_read_buffer_size, +BIO_set_write_buffer_size, +BIO_set_buffer_size, +BIO_set_buffer_read_data, +BIO_f_buffer +\&\- buffering BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_f_buffer(void); +\& +\& long BIO_get_buffer_num_lines(BIO *b); +\& long BIO_set_read_buffer_size(BIO *b, long size); +\& long BIO_set_write_buffer_size(BIO *b, long size); +\& long BIO_set_buffer_size(BIO *b, long size); +\& long BIO_set_buffer_read_data(BIO *b, void *buf, long num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_buffer()\fR returns the buffering BIO method. +.PP +Data written to a buffering BIO is buffered and periodically written +to the next BIO in the chain. Data read from a buffering BIO comes from +an internal buffer which is filled from the next BIO in the chain. +Both \fBBIO_gets()\fR and \fBBIO_puts()\fR are supported. +.PP +Calling \fBBIO_reset()\fR on a buffering BIO clears any buffered data. +.PP +\&\fBBIO_get_buffer_num_lines()\fR returns the number of lines currently buffered. +.PP +\&\fBBIO_set_read_buffer_size()\fR, \fBBIO_set_write_buffer_size()\fR and \fBBIO_set_buffer_size()\fR +set the read, write or both read and write buffer sizes to \fBsize\fR. The initial +buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the +buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared +when the buffer is resized. +.PP +\&\fBBIO_set_buffer_read_data()\fR clears the read buffer and fills it with \fBnum\fR +bytes of \fBbuf\fR. If \fBnum\fR is larger than the current buffer size the buffer +is expanded. +.SH NOTES +.IX Header "NOTES" +These functions, other than \fBBIO_f_buffer()\fR, are implemented as macros. +.PP +Buffering BIOs implement \fBBIO_read_ex()\fR and \fBBIO_gets()\fR by using +\&\fBBIO_read_ex()\fR operations on the next BIO in the chain and storing the +result in an internal buffer, from which bytes are given back to the +caller as appropriate for the call; a \fBBIO_gets()\fR is guaranteed to give +the caller a whole line, and \fBBIO_read_ex()\fR is guaranteed to give the +caller the number of bytes it asks for, unless there\*(Aqs an error or end +of communication is reached in the next BIO. By prepending a +buffering BIO to a chain it is therefore possible to provide +\&\fBBIO_gets()\fR or exact size \fBBIO_read_ex()\fR functionality if the following +BIOs do not support it. +.PP +Do not add more than one \fBBIO_f_buffer()\fR to a BIO chain. The result of +doing so will force a full read of the size of the internal buffer of +the top \fBBIO_f_buffer()\fR, which is 4 KiB at a minimum. +.PP +Data is only written to the next BIO in the chain when the write buffer fills +or when \fBBIO_flush()\fR is called. It is therefore important to call \fBBIO_flush()\fR +whenever any pending data should be written such as when removing a buffering +BIO using \fBBIO_pop()\fR. \fBBIO_flush()\fR may need to be retried if the ultimate +source/sink BIO is non blocking. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_buffer()\fR returns the buffering BIO method. +.PP +\&\fBBIO_get_buffer_num_lines()\fR returns the number of lines buffered (may be 0) or +a negative value in case of errors. +.PP +\&\fBBIO_set_read_buffer_size()\fR, \fBBIO_set_write_buffer_size()\fR and \fBBIO_set_buffer_size()\fR +return 1 if the buffer was successfully resized or <=0 for failure. +.PP +\&\fBBIO_set_buffer_read_data()\fR returns 1 if the data was set correctly or <=0 if +there was an error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), +\&\fBBIO_reset\fR\|(3), +\&\fBBIO_flush\fR\|(3), +\&\fBBIO_pop\fR\|(3), +\&\fBBIO_ctrl\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_cipher.3 b/static/netbsd/man3/BIO_f_cipher.3 new file mode 100644 index 00000000..d5c611b2 --- /dev/null +++ b/static/netbsd/man3/BIO_f_cipher.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: BIO_f_cipher.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_cipher 3" +.TH BIO_f_cipher 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx \- cipher BIO filter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& const BIO_METHOD *BIO_f_cipher(void); +\& int BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, +\& const unsigned char *key, const unsigned char *iv, int enc); +\& int BIO_get_cipher_status(BIO *b); +\& int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_cipher()\fR returns the cipher BIO method. This is a filter +BIO that encrypts any data written through it, and decrypts any data +read from it. It is a BIO wrapper for the cipher routines +\&\fBEVP_CipherInit()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal()\fR. +.PP +Cipher BIOs do not support \fBBIO_gets()\fR or \fBBIO_puts()\fR. +.PP +\&\fBBIO_flush()\fR on an encryption BIO that is being written through is +used to signal that no more data is to be encrypted: this is used +to flush and possibly pad the final block through the BIO. +.PP +\&\fBBIO_set_cipher()\fR sets the cipher of BIO \fBb\fR to \fBcipher\fR using key \fBkey\fR +and IV \fBiv\fR. \fBenc\fR should be set to 1 for encryption and zero for +decryption. +.PP +When reading from an encryption BIO the final block is automatically +decrypted and checked when EOF is detected. \fBBIO_get_cipher_status()\fR +is a \fBBIO_ctrl()\fR macro which can be called to determine whether the +decryption operation was successful. +.PP +\&\fBBIO_get_cipher_ctx()\fR is a \fBBIO_ctrl()\fR macro which retrieves the internal +BIO cipher context. The retrieved context can be used in conjunction +with the standard cipher routines to set it up. This is useful when +\&\fBBIO_set_cipher()\fR is not flexible enough for the applications needs. +.SH NOTES +.IX Header "NOTES" +When encrypting \fBBIO_flush()\fR \fBmust\fR be called to flush the final block +through the BIO. If it is not then the final block will fail a subsequent +decrypt. +.PP +When decrypting an error on the final block is signaled by a zero +return value from the read operation. A successful decrypt followed +by EOF will also return zero for the final read. \fBBIO_get_cipher_status()\fR +should be called to determine if the decrypt was successful. +.PP +As always, if \fBBIO_gets()\fR or \fBBIO_puts()\fR support is needed then it can +be achieved by preceding the cipher BIO with a buffering BIO. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_cipher()\fR returns the cipher BIO method. +.PP +\&\fBBIO_set_cipher()\fR returns 1 for success and 0 for failure. +.PP +\&\fBBIO_get_cipher_status()\fR returns 1 for a successful decrypt and <=0 +for failure. +.PP +\&\fBBIO_get_cipher_ctx()\fR returns 1 for success and <=0 for failure. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_md.3 b/static/netbsd/man3/BIO_f_md.3 new file mode 100644 index 00000000..6a08fefa --- /dev/null +++ b/static/netbsd/man3/BIO_f_md.3 @@ -0,0 +1,222 @@ +.\" $NetBSD: BIO_f_md.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_md 3" +.TH BIO_f_md 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& const BIO_METHOD *BIO_f_md(void); +\& int BIO_set_md(BIO *b, EVP_MD *md); +\& int BIO_get_md(BIO *b, EVP_MD **mdp); +\& int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_md()\fR returns the message digest BIO method. This is a filter +BIO that digests any data passed through it. It is a BIO wrapper +for the digest routines \fBEVP_DigestInit()\fR, \fBEVP_DigestUpdate()\fR +and \fBEVP_DigestFinal()\fR. +.PP +Any data written or read through a digest BIO using \fBBIO_read_ex()\fR and +\&\fBBIO_write_ex()\fR is digested. +.PP +\&\fBBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the +digest calculation and returns the digest value. \fBBIO_puts()\fR is +not supported. +.PP +\&\fBBIO_reset()\fR reinitialises a digest BIO. +.PP +\&\fBBIO_set_md()\fR sets the message digest of BIO \fBb\fR to \fBmd\fR: this +must be called to initialize a digest BIO before any data is +passed through it. It is a \fBBIO_ctrl()\fR macro. +.PP +\&\fBBIO_get_md()\fR places a pointer to the digest BIOs digest method +in \fBmdp\fR. It is a \fBBIO_ctrl()\fR macro. +.PP +\&\fBBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR. +.SH NOTES +.IX Header "NOTES" +The context returned by \fBBIO_get_md_ctx()\fR can be used in calls +to \fBEVP_DigestFinal()\fR and also the signature routines \fBEVP_SignFinal()\fR +and \fBEVP_VerifyFinal()\fR. +.PP +The context returned by \fBBIO_get_md_ctx()\fR is an internal context +structure. Changes made to this context will affect the digest +BIO itself and the context pointer will become invalid when the digest +BIO is freed. +.PP +After the digest has been retrieved from a digest BIO it must be +reinitialized by calling \fBBIO_reset()\fR, or \fBBIO_set_md()\fR before any more +data is passed through it. +.PP +If an application needs to call \fBBIO_gets()\fR or \fBBIO_puts()\fR through +a chain containing digest BIOs then this can be done by prepending +a buffering BIO. +.PP +Calling \fBBIO_get_md_ctx()\fR will return the context and initialize the BIO +state. This allows applications to initialize the context externally +if the standard calls such as \fBBIO_set_md()\fR are not sufficiently flexible. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_md()\fR returns the digest BIO method. +.PP +\&\fBBIO_set_md()\fR, \fBBIO_get_md()\fR and \fBBIO_md_ctx()\fR return 1 for success and +<=0 for failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following example creates a BIO chain containing an SHA1 and MD5 +digest BIO and passes the string "Hello World" through it. Error +checking has been omitted for clarity. +.PP +.Vb 2 +\& BIO *bio, *mdtmp; +\& char message[] = "Hello World"; +\& +\& bio = BIO_new(BIO_s_null()); +\& mdtmp = BIO_new(BIO_f_md()); +\& BIO_set_md(mdtmp, EVP_sha1()); +\& /* +\& * For BIO_push() we want to append the sink BIO and keep a note of +\& * the start of the chain. +\& */ +\& bio = BIO_push(mdtmp, bio); +\& mdtmp = BIO_new(BIO_f_md()); +\& BIO_set_md(mdtmp, EVP_md5()); +\& bio = BIO_push(mdtmp, bio); +\& /* Note: mdtmp can now be discarded */ +\& BIO_write(bio, message, strlen(message)); +.Ve +.PP +The next example digests data by reading through a chain instead: +.PP +.Vb 3 +\& BIO *bio, *mdtmp; +\& char buf[1024]; +\& int rdlen; +\& +\& bio = BIO_new_file(file, "rb"); +\& mdtmp = BIO_new(BIO_f_md()); +\& BIO_set_md(mdtmp, EVP_sha1()); +\& bio = BIO_push(mdtmp, bio); +\& mdtmp = BIO_new(BIO_f_md()); +\& BIO_set_md(mdtmp, EVP_md5()); +\& bio = BIO_push(mdtmp, bio); +\& do { +\& rdlen = BIO_read(bio, buf, sizeof(buf)); +\& /* Might want to do something with the data here */ +\& } while (rdlen > 0); +.Ve +.PP +This next example retrieves the message digests from a BIO chain and +outputs them. This could be used with the examples above. +.PP +.Vb 4 +\& BIO *mdtmp; +\& unsigned char mdbuf[EVP_MAX_MD_SIZE]; +\& int mdlen; +\& int i; +\& +\& mdtmp = bio; /* Assume bio has previously been set up */ +\& do { +\& EVP_MD *md; +\& +\& mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); +\& if (!mdtmp) +\& break; +\& BIO_get_md(mdtmp, &md); +\& printf("%s digest", OBJ_nid2sn(EVP_MD_get_type(md))); +\& mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); +\& for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); +\& printf("\en"); +\& mdtmp = BIO_next(mdtmp); +\& } while (mdtmp); +\& +\& BIO_free_all(bio); +.Ve +.SH BUGS +.IX Header "BUGS" +The lack of support for \fBBIO_puts()\fR and the non standard behaviour of +\&\fBBIO_gets()\fR could be regarded as anomalous. It could be argued that \fBBIO_gets()\fR +and \fBBIO_puts()\fR should be passed to the next BIO in the chain and digest +the data passed through and that digests should be retrieved using a +separate \fBBIO_ctrl()\fR call. +.SH HISTORY +.IX Header "HISTORY" +Before OpenSSL 1.0.0., the call to \fBBIO_get_md_ctx()\fR would only work if the +BIO was initialized first. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_null.3 b/static/netbsd/man3/BIO_f_null.3 new file mode 100644 index 00000000..9e7f7a9c --- /dev/null +++ b/static/netbsd/man3/BIO_f_null.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: BIO_f_null.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_null 3" +.TH BIO_f_null 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_null \- null filter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_f_null(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_null()\fR returns the null filter BIO method. This is a filter BIO +that does nothing. +.PP +All requests to a null filter BIO are passed through to the next BIO in +the chain: this means that a BIO chain containing a null filter BIO +behaves just as though the BIO was not there. +.SH NOTES +.IX Header "NOTES" +As may be apparent a null filter BIO is not particularly useful. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_null()\fR returns the null filter BIO method. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_prefix.3 b/static/netbsd/man3/BIO_f_prefix.3 new file mode 100644 index 00000000..91028ddb --- /dev/null +++ b/static/netbsd/man3/BIO_f_prefix.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: BIO_f_prefix.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_prefix 3" +.TH BIO_f_prefix 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_prefix, BIO_set_prefix, BIO_set_indent, BIO_get_indent +\&\- prefix BIO filter +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_f_prefix(void); +\& long BIO_set_prefix(BIO *b, const char *prefix); +\& long BIO_set_indent(BIO *b, long indent); +\& long BIO_get_indent(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_cipher()\fR returns the prefix BIO method. This is a filter for +text output, where each line gets automatically prefixed and indented +according to user input. +.PP +The prefix and the indentation are combined. For each line of output +going through this filter, the prefix is output first, then the amount +of additional spaces indicated by the indentation, and then the line +itself. +.PP +By default, there is no prefix, and indentation is set to 0. +.PP +\&\fBBIO_set_prefix()\fR sets the prefix to be used for future lines of +text, using \fIprefix\fR. \fIprefix\fR may be NULL, signifying that there +should be no prefix. If \fIprefix\fR isn\*(Aqt NULL, this function makes a +copy of it. +.PP +\&\fBBIO_set_indent()\fR sets the indentation to be used for future lines of +text, using \fIindent\fR. Negative values are not allowed. +.PP +\&\fBBIO_get_indent()\fR gets the current indentation. +.SH NOTES +.IX Header "NOTES" +\&\fBBIO_set_prefix()\fR, \fBBIO_set_indent()\fR and \fBBIO_get_indent()\fR are +implemented as macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_prefix()\fR returns the prefix BIO method. +.PP +\&\fBBIO_set_prefix()\fR returns 1 if the prefix was correctly set, or <=0 on +failure. +.PP +\&\fBBIO_set_indent()\fR returns 1 if the prefix was correctly set, or <=0 on +failure. +.PP +\&\fBBIO_get_indent()\fR returns the current indentation, or a negative value for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_readbuffer.3 b/static/netbsd/man3/BIO_f_readbuffer.3 new file mode 100644 index 00000000..e06caa98 --- /dev/null +++ b/static/netbsd/man3/BIO_f_readbuffer.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: BIO_f_readbuffer.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_readbuffer 3" +.TH BIO_f_readbuffer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_f_readbuffer +\&\- read only buffering BIO that supports BIO_tell() and BIO_seek() +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_f_readbuffer(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_readbuffer()\fR returns the read buffering BIO method. +.PP +This BIO filter can be inserted on top of BIO\*(Aqs that do not support \fBBIO_tell()\fR +or \fBBIO_seek()\fR (e.g. A file BIO that uses stdin). +.PP +Data read from a read buffering BIO comes from an internal buffer which is +filled from the next BIO in the chain. +.PP +\&\fBBIO_gets()\fR is supported for read buffering BIOs. +Writing data to a read buffering BIO is not supported. +.PP +Calling \fBBIO_reset()\fR on a read buffering BIO does not clear any buffered data. +.SH NOTES +.IX Header "NOTES" +Read buffering BIOs implement \fBBIO_read_ex()\fR by using \fBBIO_read_ex()\fR operations +on the next BIO (e.g. a file BIO) in the chain and storing the result in an +internal buffer, from which bytes are given back to the caller as appropriate +for the call. \fBBIO_read_ex()\fR is guaranteed to give the caller the number of bytes +it asks for, unless there\*(Aqs an error or end of communication is reached in the +next BIO. The internal buffer can grow to cache the entire contents of the next +BIO in the chain. \fBBIO_seek()\fR uses the internal buffer, so that it can only seek +into data that is already read. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_readbuffer()\fR returns the read buffering BIO method. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), +\&\fBBIO_read\fR\|(3), +\&\fBBIO_gets\fR\|(3), +\&\fBBIO_reset\fR\|(3), +\&\fBBIO_ctrl\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_f_ssl.3 b/static/netbsd/man3/BIO_f_ssl.3 new file mode 100644 index 00000000..cfbd9b26 --- /dev/null +++ b/static/netbsd/man3/BIO_f_ssl.3 @@ -0,0 +1,373 @@ +.\" $NetBSD: BIO_f_ssl.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_f_ssl 3" +.TH BIO_f_ssl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_do_handshake, +BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, +BIO_set_ssl_renegotiate_bytes, +BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, +BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, +BIO_ssl_shutdown \- SSL BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& const BIO_METHOD *BIO_f_ssl(void); +\& +\& long BIO_set_ssl(BIO *b, SSL *ssl, long c); +\& long BIO_get_ssl(BIO *b, SSL **sslp); +\& long BIO_set_ssl_mode(BIO *b, long client); +\& long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); +\& long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); +\& long BIO_get_num_renegotiates(BIO *b); +\& +\& BIO *BIO_new_ssl(SSL_CTX *ctx, int client); +\& BIO *BIO_new_ssl_connect(SSL_CTX *ctx); +\& BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); +\& int BIO_ssl_copy_session_id(BIO *to, BIO *from); +\& void BIO_ssl_shutdown(BIO *bio); +\& +\& long BIO_do_handshake(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_f_ssl()\fR returns the SSL BIO method. This is a filter BIO which +is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to +SSL I/O. +.PP +I/O performed on an SSL BIO communicates using the SSL protocol with +the SSLs read and write BIOs. If an SSL connection is not established +then an attempt is made to establish one on the first I/O call. +.PP +If a BIO is appended to an SSL BIO using \fBBIO_push()\fR it is automatically +used as the SSL BIOs read and write BIOs. +.PP +Calling \fBBIO_reset()\fR on an SSL BIO closes down any current SSL connection +by calling \fBSSL_shutdown()\fR. \fBBIO_reset()\fR is then sent to the next BIO in +the chain: this will typically disconnect the underlying transport. +The SSL BIO is then reset to the initial accept or connect state. +.PP +If the close flag is set when an SSL BIO is freed then the internal +SSL structure is also freed using \fBSSL_free()\fR. +.PP +\&\fBBIO_set_ssl()\fR sets the internal SSL pointer of SSL BIO \fBb\fR to \fBssl\fR using +the close flag \fBc\fR. +.PP +\&\fBBIO_get_ssl()\fR retrieves the SSL pointer of SSL BIO \fBb\fR, it can then be +manipulated using the standard SSL library functions. +.PP +\&\fBBIO_set_ssl_mode()\fR sets the SSL BIO mode to \fBclient\fR. If \fBclient\fR +is 1 client mode is set. If \fBclient\fR is 0 server mode is set. +.PP +\&\fBBIO_set_ssl_renegotiate_bytes()\fR sets the renegotiate byte count of SSL BIO \fBb\fR +to \fBnum\fR. When set after every \fBnum\fR bytes of I/O (read and write) +the SSL session is automatically renegotiated. \fBnum\fR must be at +least 512 bytes. +.PP +\&\fBBIO_set_ssl_renegotiate_timeout()\fR sets the renegotiate timeout of SSL BIO \fBb\fR +to \fBseconds\fR. +When the renegotiate timeout elapses the session is automatically renegotiated. +.PP +\&\fBBIO_get_num_renegotiates()\fR returns the total number of session +renegotiations due to I/O or timeout of SSL BIO \fBb\fR. +.PP +\&\fBBIO_new_ssl()\fR allocates an SSL BIO using SSL_CTX \fBctx\fR and using +client mode if \fBclient\fR is non zero. +.PP +\&\fBBIO_new_ssl_connect()\fR creates a new BIO chain consisting of an +SSL BIO (using \fBctx\fR) followed by a connect BIO. +.PP +\&\fBBIO_new_buffer_ssl_connect()\fR creates a new BIO chain consisting +of a buffering BIO, an SSL BIO (using \fBctx\fR), and a connect BIO. +.PP +\&\fBBIO_ssl_copy_session_id()\fR copies an SSL session id between +BIO chains \fBfrom\fR and \fBto\fR. It does this by locating the +SSL BIOs in each chain and calling \fBSSL_copy_session_id()\fR on +the internal SSL pointer. +.PP +\&\fBBIO_ssl_shutdown()\fR closes down an SSL connection on BIO +chain \fBbio\fR. It does this by locating the SSL BIO in the +chain and calling \fBSSL_shutdown()\fR on its internal SSL +pointer. +.PP +\&\fBBIO_do_handshake()\fR attempts to complete an SSL handshake on the +supplied BIO and establish the SSL connection. +For non\-SSL BIOs the connection is done typically at TCP level. +If domain name resolution yields multiple IP addresses all of them are tried +after \fBconnect()\fR failures. +The function returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection could not be established. +The call \fBBIO_should_retry()\fR should be used for nonblocking connect BIOs +to determine if the call should be retried. +If a connection has already been established this call has no effect. +.SH NOTES +.IX Header "NOTES" +SSL BIOs are exceptional in that if the underlying transport +is non blocking they can still request a retry in exceptional +circumstances. Specifically this will happen if a session +renegotiation takes place during a \fBBIO_read_ex()\fR operation, one +case where this happens is when step up occurs. +.PP +The SSL flag SSL_AUTO_RETRY can be +set to disable this behaviour. That is when this flag is set +an SSL BIO using a blocking transport will never request a +retry. +.PP +Since unknown \fBBIO_ctrl()\fR operations are sent through filter +BIOs the servers name and port can be set using \fBBIO_set_host()\fR +on the BIO returned by \fBBIO_new_ssl_connect()\fR without having +to locate the connect BIO first. +.PP +Applications do not have to call \fBBIO_do_handshake()\fR but may wish +to do so to separate the handshake process from other I/O +processing. +.PP +\&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR, +\&\fBBIO_set_ssl_renegotiate_bytes()\fR, \fBBIO_set_ssl_renegotiate_timeout()\fR, +\&\fBBIO_get_num_renegotiates()\fR, and \fBBIO_do_handshake()\fR are implemented as macros. +.PP +\&\fBBIO_ssl_copy_session_id()\fR is not currently supported on QUIC SSL objects and +fails if called on such an object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_f_ssl()\fR returns the SSL \fBBIO_METHOD\fR structure. +.PP +\&\fBBIO_set_ssl()\fR, \fBBIO_get_ssl()\fR, \fBBIO_set_ssl_mode()\fR, \fBBIO_set_ssl_renegotiate_bytes()\fR, +\&\fBBIO_set_ssl_renegotiate_timeout()\fR and \fBBIO_get_num_renegotiates()\fR return 1 on +success or a value which is less than or equal to 0 if an error occurred. +.PP +\&\fBBIO_new_ssl()\fR, \fBBIO_new_ssl_connect()\fR and \fBBIO_new_buffer_ssl_connect()\fR return +a valid \fBBIO\fR structure on success or \fBNULL\fR if an error occurred. +.PP +\&\fBBIO_ssl_copy_session_id()\fR returns 1 on success or 0 on error, or if called +on a QUIC SSL object. +.PP +\&\fBBIO_do_handshake()\fR returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection could not be established. +.SH EXAMPLES +.IX Header "EXAMPLES" +This SSL/TLS client example attempts to retrieve a page from an +SSL/TLS web server. The I/O routines are identical to those of the +unencrypted example in \fBBIO_s_connect\fR\|(3). +.PP +.Vb 5 +\& BIO *sbio, *out; +\& int len; +\& char tmpbuf[1024]; +\& SSL_CTX *ctx; +\& SSL *ssl; +\& +\& /* XXX Seed the PRNG if needed. */ +\& +\& ctx = SSL_CTX_new(TLS_client_method()); +\& +\& /* XXX Set verify paths and mode here. */ +\& +\& sbio = BIO_new_ssl_connect(ctx); +\& BIO_get_ssl(sbio, &ssl); +\& if (ssl == NULL) { +\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& /* XXX We might want to do other things with ssl here */ +\& +\& /* An empty host part means the loopback address */ +\& BIO_set_conn_hostname(sbio, ":https"); +\& +\& out = BIO_new_fp(stdout, BIO_NOCLOSE); +\& if (BIO_do_connect(sbio) <= 0) { +\& fprintf(stderr, "Error connecting to server\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& /* XXX Could examine ssl here to get connection info */ +\& +\& BIO_puts(sbio, "GET / HTTP/1.0\en\en"); +\& for (;;) { +\& len = BIO_read(sbio, tmpbuf, 1024); +\& if (len <= 0) +\& break; +\& BIO_write(out, tmpbuf, len); +\& } +\& BIO_free_all(sbio); +\& BIO_free(out); +.Ve +.PP +Here is a simple server example. It makes use of a buffering +BIO to allow lines to be read from the SSL BIO using BIO_gets. +It creates a pseudo web page containing the actual request from +a client and also echoes the request to standard output. +.PP +.Vb 5 +\& BIO *sbio, *bbio, *acpt, *out; +\& int len; +\& char tmpbuf[1024]; +\& SSL_CTX *ctx; +\& SSL *ssl; +\& +\& /* XXX Seed the PRNG if needed. */ +\& +\& ctx = SSL_CTX_new(TLS_server_method()); +\& if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) +\& || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) +\& || !SSL_CTX_check_private_key(ctx)) { +\& fprintf(stderr, "Error setting up SSL_CTX\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& /* XXX Other things like set verify locations, EDH temp callbacks. */ +\& +\& /* New SSL BIO setup as server */ +\& sbio = BIO_new_ssl(ctx, 0); +\& BIO_get_ssl(sbio, &ssl); +\& if (ssl == NULL) { +\& fprintf(stderr, "Can\*(Aqt locate SSL pointer\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& bbio = BIO_new(BIO_f_buffer()); +\& sbio = BIO_push(bbio, sbio); +\& acpt = BIO_new_accept("4433"); +\& +\& /* +\& * By doing this when a new connection is established +\& * we automatically have sbio inserted into it. The +\& * BIO chain is now \*(Aqswallowed\*(Aq by the accept BIO and +\& * will be freed when the accept BIO is freed. +\& */ +\& BIO_set_accept_bios(acpt, sbio); +\& out = BIO_new_fp(stdout, BIO_NOCLOSE); +\& +\& /* First call to BIO_do_accept() sets up accept BIO */ +\& if (BIO_do_accept(acpt) <= 0) { +\& fprintf(stderr, "Error setting up accept BIO\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +.Ve +.PP +/* Second call to \fBBIO_do_accept()\fR waits for incoming connection */ + if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error accepting connection\en"); + ERR_print_errors_fp(stderr); + \fBexit\fR\|(1); + } +.PP +.Vb 3 +\& /* We only want one connection so remove and free accept BIO */ +\& sbio = BIO_pop(acpt); +\& BIO_free_all(acpt); +\& +\& if (BIO_do_handshake(sbio) <= 0) { +\& fprintf(stderr, "Error in SSL handshake\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent\-type: text/plain\er\en\er\en"); +\& BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); +\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en"); +\& +\& for (;;) { +\& len = BIO_gets(sbio, tmpbuf, 1024); +\& if (len <= 0) +\& break; +\& BIO_write(sbio, tmpbuf, len); +\& BIO_write(out, tmpbuf, len); +\& /* Look for blank line signifying end of headers*/ +\& if (tmpbuf[0] == \*(Aq\er\*(Aq || tmpbuf[0] == \*(Aq\en\*(Aq) +\& break; +\& } +\& +\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en"); +\& BIO_puts(sbio, "\er\en"); +\& BIO_flush(sbio); +\& BIO_free_all(sbio); +.Ve +.SH HISTORY +.IX Header "HISTORY" +In OpenSSL before 1.0.0 the \fBBIO_pop()\fR call was handled incorrectly, +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the SSL BIO even if the SSL BIO was not +explicitly being popped (e.g. a pop higher up the chain). Applications which +included workarounds for this bug (e.g. freeing BIOs more than once) should +be modified to handle this fix or they may free up an already freed BIO. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_find_type.3 b/static/netbsd/man3/BIO_find_type.3 new file mode 100644 index 00000000..598ba950 --- /dev/null +++ b/static/netbsd/man3/BIO_find_type.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: BIO_find_type.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_find_type 3" +.TH BIO_find_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_find_type, BIO_next, BIO_method_type \- BIO chain traversal +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO *BIO_find_type(BIO *b, int bio_type); +\& BIO *BIO_next(BIO *b); +\& int BIO_method_type(const BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_find_type()\fR searches for a \fBBIO\fR of a given type in a chain, starting +at \fBBIO\fR \fIb\fR. If \fItype\fR is a specific type (such as \fBBIO_TYPE_MEM\fR) then a +search is made for a \fBBIO\fR of that type. If \fItype\fR is a general type (such as +\&\fBBIO_TYPE_SOURCE_SINK\fR) then the next matching \fBBIO\fR of the given general type is +searched for. \fBBIO_find_type()\fR returns the next matching \fBBIO\fR or NULL if none is +found. If \fItype\fR is \fBBIO_TYPE_NONE\fR it will not find a match. +.PP +The following general types are defined: +\&\fBBIO_TYPE_DESCRIPTOR\fR, \fBBIO_TYPE_FILTER\fR, and \fBBIO_TYPE_SOURCE_SINK\fR. +.PP +For a list of the specific types, see the \fI\fR header file. +.PP +\&\fBBIO_next()\fR returns the next BIO in a chain. It can be used to traverse all BIOs +in a chain or used in conjunction with \fBBIO_find_type()\fR to find all BIOs of a +certain type. +.PP +\&\fBBIO_method_type()\fR returns the type of a BIO. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_find_type()\fR returns a matching BIO or NULL for no match. +.PP +\&\fBBIO_next()\fR returns the next BIO in a chain. +.PP +\&\fBBIO_method_type()\fR returns the type of the BIO \fIb\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +Traverse a chain looking for digest BIOs: +.PP +.Vb 1 +\& BIO *btmp; +\& +\& btmp = in_bio; /* in_bio is chain to search through */ +\& do { +\& btmp = BIO_find_type(btmp, BIO_TYPE_MD); +\& if (btmp == NULL) +\& break; /* Not found */ +\& /* btmp is a digest BIO, do something with it ...*/ +\& ... +\& +\& btmp = BIO_next(btmp); +\& } while (btmp); +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_get_data.3 b/static/netbsd/man3/BIO_get_data.3 new file mode 100644 index 00000000..0e4e2e32 --- /dev/null +++ b/static/netbsd/man3/BIO_get_data.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: BIO_get_data.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_get_data 3" +.TH BIO_get_data 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown, +BIO_get_shutdown \- functions for managing BIO state information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void BIO_set_data(BIO *a, void *ptr); +\& void *BIO_get_data(BIO *a); +\& void BIO_set_init(BIO *a, int init); +\& int BIO_get_init(BIO *a); +\& void BIO_set_shutdown(BIO *a, int shut); +\& int BIO_get_shutdown(BIO *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions can be used when implementing a custom BIO. +.PP +The \fBBIO_set_data()\fR function associates the custom data pointed to by \fBptr\fR with +the BIO. This data can subsequently be retrieved via a call to \fBBIO_get_data()\fR. +This can be used by custom BIOs for storing implementation specific information. +.PP +The \fBBIO_set_init()\fR function sets the value of the BIO\*(Aqs "init" flag to indicate +whether initialisation has been completed for this BIO or not. A nonzero value +indicates that initialisation is complete, whilst zero indicates that it is not. +Often initialisation will complete during initial construction of the BIO. For +some BIOs however, initialisation may not complete until after additional steps +have occurred (for example through calling custom ctrls). The \fBBIO_get_init()\fR +function returns the value of the "init" flag. +.PP +The \fBBIO_set_shutdown()\fR and \fBBIO_get_shutdown()\fR functions set and get the state of +this BIO\*(Aqs shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource +is also closed when the BIO is freed. +.SH WARNINGS +.IX Header "WARNINGS" +Do not use \fBBIO_set_data()\fR, \fBBIO_get_data()\fR, \fBBIO_set_init()\fR, \fBBIO_get_init()\fR, outside +the implementation of a custom BIO. +Calling \fBBIO_set_data()\fR on an existing BIO implementation with data that it does +not expect will lead to unexpected results. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_get_data()\fR returns a pointer to the implementation specific custom data +associated with this BIO, or NULL if none has been set. +.PP +\&\fBBIO_get_init()\fR returns the state of the BIO\*(Aqs init flag. +.PP +\&\fBBIO_get_shutdown()\fR returns the stat of the BIO\*(Aqs shutdown (i.e. BIO_CLOSE) flag. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), \fBBIO_meth_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_get_ex_new_index.3 b/static/netbsd/man3/BIO_get_ex_new_index.3 new file mode 100644 index 00000000..a8eee4af --- /dev/null +++ b/static/netbsd/man3/BIO_get_ex_new_index.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: BIO_get_ex_new_index.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_get_ex_new_index 3" +.TH BIO_get_ex_new_index 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, +BIO_set_app_data, BIO_get_app_data, +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, +EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, +ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, +EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data, +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, +RSA_set_app_data, RSA_get_app_data, +SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, +SSL_set_app_data, SSL_get_app_data, +SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data, +SSL_CTX_set_app_data, SSL_CTX_get_app_data, +SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data, +SSL_SESSION_set_app_data, SSL_SESSION_get_app_data, +UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, +UI_set_app_data, UI_get_app_data, +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, +X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data, +X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, +X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data +\&\- application\-specific data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int TYPE_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int TYPE_set_ex_data(TYPE *d, int idx, void *arg); +\& +\& void *TYPE_get_ex_data(const TYPE *d, int idx); +\& +\& #define TYPE_set_app_data(TYPE *d, void *arg) +\& #define TYPE_get_app_data(TYPE *d) +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& int DH_set_ex_data(DH *type, int idx, void *arg); +\& void *DH_get_ex_data(DH *type, int idx); +\& int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& int DSA_set_ex_data(DSA *type, int idx, void *arg); +\& void *DSA_get_ex_data(DSA *type, int idx); +\& int EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& int EC_KEY_set_ex_data(EC_KEY *type, int idx, void *arg); +\& void *EC_KEY_get_ex_data(EC_KEY *type, int idx); +\& int RSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& int RSA_set_ex_data(RSA *type, int idx, void *arg); +\& void *RSA_get_ex_data(RSA *type, int idx); +\& int RSA_set_app_data(RSA *type, void *arg); +\& void *RSA_get_app_data(RSA *type); +\& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& int ENGINE_set_ex_data(ENGINE *type, int idx, void *arg); +\& void *ENGINE_get_ex_data(ENGINE *type, int idx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In the description here, \fITYPE\fR is used a placeholder +for any of the OpenSSL datatypes listed in \fBCRYPTO_get_ex_new_index\fR\|(3). +.PP +All functions with a \fITYPE\fR of \fBDH\fR, \fBDSA\fR, \fBRSA\fR and \fBEC_KEY\fR are deprecated. +Applications should instead use \fBEVP_PKEY_set_ex_data()\fR, +\&\fBEVP_PKEY_get_ex_data()\fR and \fBEVP_PKEY_get_ex_new_index()\fR. +.PP +All functions with a \fITYPE\fR of \fBENGINE\fR are deprecated. +Applications using engines should be replaced by providers. +.PP +These functions handle application\-specific data for OpenSSL data +structures. +.PP +\&\fBTYPE_get_ex_new_index()\fR is a macro that calls \fBCRYPTO_get_ex_new_index()\fR +with the correct \fBindex\fR value. +.PP +\&\fBTYPE_set_ex_data()\fR is a function that calls \fBCRYPTO_set_ex_data()\fR with +an offset into the opaque exdata part of the TYPE object. \fId\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBTYPE_get_ex_data()\fR is a function that calls \fBCRYPTO_get_ex_data()\fR with +an offset into the opaque exdata part of the TYPE object. \fId\fR \fBMUST NOT\fR be NULL. +.PP +For compatibility with previous releases, the exdata index of zero is +reserved for "application data." There are two convenience functions for +this. +\&\fBTYPE_set_app_data()\fR is a macro that invokes \fBTYPE_set_ex_data()\fR with +\&\fBidx\fR set to zero. +\&\fBTYPE_get_app_data()\fR is a macro that invokes \fBTYPE_get_ex_data()\fR with +\&\fBidx\fR set to zero. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBTYPE_get_ex_new_index()\fR returns a new index on success or \-1 on error. +.PP +\&\fBTYPE_set_ex_data()\fR returns 1 on success or 0 on error. +.PP +\&\fBTYPE_get_ex_data()\fR returns the application data or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCRYPTO_get_ex_new_index\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The functions \fBDH_get_ex_new_index()\fR, \fBDH_set_ex_data()\fR, \fBDH_get_ex_data()\fR, +\&\fBDSA_get_ex_new_index()\fR, \fBDSA_set_ex_data()\fR, \fBDSA_get_ex_data()\fR, +\&\fBEC_KEY_get_ex_new_index()\fR, \fBEC_KEY_set_ex_data()\fR, \fBEC_KEY_get_ex_data()\fR, +\&\fBENGINE_get_ex_new_index()\fR, \fBENGINE_set_ex_data()\fR, \fBENGINE_get_ex_data()\fR, +\&\fBRSA_get_ex_new_index()\fR, \fBRSA_set_ex_data()\fR, \fBRSA_get_ex_data()\fR, +\&\fBRSA_set_app_data()\fR and \fBRSA_get_app_data()\fR were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_get_rpoll_descriptor.3 b/static/netbsd/man3/BIO_get_rpoll_descriptor.3 new file mode 100644 index 00000000..d9e6f146 --- /dev/null +++ b/static/netbsd/man3/BIO_get_rpoll_descriptor.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: BIO_get_rpoll_descriptor.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_get_rpoll_descriptor 3" +.TH BIO_get_rpoll_descriptor 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor \- obtain a structure which +can be used to determine when a BIO object can next be read or written +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct bio_poll_descriptor_st { +\& uint32_t type; +\& union { +\& int fd; +\& void *custom; +\& uintptr_t custom_ui; +\& } value; +\& } BIO_POLL_DESCRIPTOR; +\& +\& int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc); +\& int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR, on success, fill +\&\fI*desc\fR with a poll descriptor. A poll descriptor is a tagged union structure +which represents some kind of OS or non\-OS resource which can be used to +synchronise on I/O availability events. +.PP +\&\fBBIO_get_rpoll_descriptor()\fR outputs a descriptor which can be used to determine +when the BIO can (potentially) next be read, and \fBBIO_get_wpoll_descriptor()\fR +outputs a descriptor which can be used to determine when the BIO can +(potentially) next be written. +.PP +It is permissible for \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR +to output the same descriptor. +.PP +Poll descriptors can represent different kinds of information. A typical kind of +resource which might be represented by a poll descriptor is an OS file +descriptor which can be used with APIs such as \fBselect()\fR. +.PP +The kinds of poll descriptor defined by OpenSSL are: +.IP BIO_POLL_DESCRIPTOR_TYPE_NONE 4 +.IX Item "BIO_POLL_DESCRIPTOR_TYPE_NONE" +Represents the absence of a valid poll descriptor. It may be used by +\&\fBBIO_get_rpoll_descriptor()\fR or \fBBIO_get_wpoll_descriptor()\fR to indicate that the +BIO is not pollable for readability or writeability respectively. +.Sp +For this type, no field within the \fIvalue\fR field of the \fBBIO_POLL_DESCRIPTOR\fR +is valid. +.IP BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD 4 +.IX Item "BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD" +The poll descriptor represents an OS socket resource. The field \fIvalue.fd\fR +in the \fBBIO_POLL_DESCRIPTOR\fR is valid if it is not set to \-1. +.Sp +The resource is whatever kind of handle is used by a given OS to represent +sockets, which may vary by OS. For example, on Windows, the value is a \fBSOCKET\fR +for use with the Winsock API. On POSIX\-like platforms, it is a file descriptor. +.Sp +Where a poll descriptor of this type is output by \fBBIO_get_rpoll_descriptor()\fR, it +should be polled for readability to determine when the BIO might next be able to +successfully complete a \fBBIO_read()\fR operation; likewise, where a poll descriptor +of this type is output by \fBBIO_get_wpoll_descriptor()\fR, it should be polled for +writeability to determine when the BIO might next be able to successfully +complete a \fBBIO_write()\fR operation. +.IP BIO_POLL_DESCRIPTOR_CUSTOM_START 4 +.IX Item "BIO_POLL_DESCRIPTOR_CUSTOM_START" +Type values beginning with this value (inclusive) are reserved for application +allocation for custom poll descriptor types. Any of the definitions in the union +field \fIvalue\fR can be used by the application arbitrarily as opaque values. +.PP +Because poll descriptors are a tagged union structure, they can represent +different kinds of information. New types of poll descriptor may be defined, +including by applications, according to their needs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR return 1 +on success and 0 on failure. +.PP +These functions are permitted to succeed and initialise \fI*desc\fR with a poll +descriptor of type \fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR to indicate that the BIO is +not pollable for readability or writeability respectively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3), +\&\fBSSL_get_wpoll_descriptor\fR\|(3), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR functions were +added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_meth_new.3 b/static/netbsd/man3/BIO_meth_new.3 new file mode 100644 index 00000000..880b07b9 --- /dev/null +++ b/static/netbsd/man3/BIO_meth_new.3 @@ -0,0 +1,279 @@ +.\" $NetBSD: BIO_meth_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_meth_new 3" +.TH BIO_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_get_new_index, +BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, +BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, +BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, +BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, +BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, +BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, +BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, +BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg \- Routines to build up BIO methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BIO_get_new_index(void); +\& +\& BIO_METHOD *BIO_meth_new(int type, const char *name); +\& +\& void BIO_meth_free(BIO_METHOD *biom); +\& +\& int BIO_meth_set_write_ex(BIO_METHOD *biom, +\& int (*bwrite)(BIO *, const char *, size_t, size_t *)); +\& int BIO_meth_set_write(BIO_METHOD *biom, +\& int (*write)(BIO *, const char *, int)); +\& +\& int BIO_meth_set_read_ex(BIO_METHOD *biom, +\& int (*bread)(BIO *, char *, size_t, size_t *)); +\& int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int)); +\& +\& int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *)); +\& int BIO_meth_set_gets(BIO_METHOD *biom, +\& int (*gets)(BIO *, char *, int)); +\& +\& int BIO_meth_set_ctrl(BIO_METHOD *biom, +\& long (*ctrl)(BIO *, int, long, void *)); +\& +\& int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *)); +\& int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *)); +\& +\& int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, +\& long (*callback_ctrl)(BIO *, int, BIO_info_cb *)); +\& +\& int BIO_meth_set_sendmmsg(BIO_METHOD *biom, +\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, +\& size_t, uint64_t)); +\& int BIO_meth_set_recvmmsg(BIO_METHOD *biom, +\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, +\& size_t, uint64_t)); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.5: +.PP +.Vb 3 +\& int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t, +\& size_t *); +\& int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int); +\& +\& int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *); +\& int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int); +\& +\& int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *); +\& int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int); +\& +\& long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *); +\& +\& int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *); +\& int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *); +\& +\& long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *); +\& +\& ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *, +\& BIO_MSG *, +\& size_t, +\& size_t, +\& uint64_t); +\& ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *, +\& BIO_MSG *, +\& size_t, +\& size_t, +\& uint64_t); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_METHOD\fR type is a structure used for the implementation of new BIO +types. It provides a set of functions used by OpenSSL for the implementation +of the various BIO capabilities. See the \fBbio\fR\|(7) page for more information. +.PP +\&\fBBIO_meth_new()\fR creates a new \fBBIO_METHOD\fR structure that contains a type +identifier \fItype\fR and a string that represents its \fBname\fR. +\&\fBtype\fR can be set to either \fBBIO_TYPE_NONE\fR or via \fBBIO_get_new_index()\fR if +a unique type is required for searching (See \fBBIO_find_type\fR\|(3)) +.PP +Note that \fBBIO_get_new_index()\fR can only be used 127 times before it returns an +error. +.PP +The set of +standard OpenSSL provided BIO types is provided in \fI\fR. +Some examples include \fBBIO_TYPE_BUFFER\fR and \fBBIO_TYPE_CIPHER\fR. Filter BIOs +should have a type which have the "filter" bit set (\fBBIO_TYPE_FILTER\fR). +Source/sink BIOs should have the "source/sink" bit set (\fBBIO_TYPE_SOURCE_SINK\fR). +File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should +additionally have the "descriptor" bit set (\fBBIO_TYPE_DESCRIPTOR\fR). See the +\&\fBBIO_find_type\fR\|(3) page for more information. +.PP +\&\fBBIO_meth_free()\fR destroys a \fBBIO_METHOD\fR structure and frees up any memory +associated with it. If the argument is NULL, nothing is done. +.PP +\&\fBBIO_meth_get_write_ex()\fR and \fBBIO_meth_set_write_ex()\fR get and set the function +used for writing arbitrary length data to the BIO respectively. This function +will be called in response to the application calling \fBBIO_write_ex()\fR or +\&\fBBIO_write()\fR. The parameters for the function have the same meaning as for +\&\fBBIO_write_ex()\fR. Older code may call \fBBIO_meth_get_write()\fR and +\&\fBBIO_meth_set_write()\fR instead. Applications should not call both +\&\fBBIO_meth_set_write_ex()\fR and \fBBIO_meth_set_write()\fR or call \fBBIO_meth_get_write()\fR +when the function was set with \fBBIO_meth_set_write_ex()\fR. +.PP +\&\fBBIO_meth_get_read_ex()\fR and \fBBIO_meth_set_read_ex()\fR get and set the function used +for reading arbitrary length data from the BIO respectively. This function will +be called in response to the application calling \fBBIO_read_ex()\fR or \fBBIO_read()\fR. +The parameters for the function have the same meaning as for \fBBIO_read_ex()\fR. +Older code may call \fBBIO_meth_get_read()\fR and \fBBIO_meth_set_read()\fR instead. +Applications should not call both \fBBIO_meth_set_read_ex()\fR and \fBBIO_meth_set_read()\fR +or call \fBBIO_meth_get_read()\fR when the function was set with +\&\fBBIO_meth_set_read_ex()\fR. +.PP +\&\fBBIO_meth_get_puts()\fR and \fBBIO_meth_set_puts()\fR get and set the function used for +writing a NULL terminated string to the BIO respectively. This function will be +called in response to the application calling \fBBIO_puts()\fR. The parameters for +the function have the same meaning as for \fBBIO_puts()\fR. +.PP +\&\fBBIO_meth_get_gets()\fR and \fBBIO_meth_set_gets()\fR get and set the function typically +used for reading a line of data from the BIO respectively (see the \fBBIO_gets\fR\|(3) +page for more information). This function will be called in response to the +application calling \fBBIO_gets()\fR. The parameters for the function have the same +meaning as for \fBBIO_gets()\fR. +.PP +\&\fBBIO_meth_get_ctrl()\fR and \fBBIO_meth_set_ctrl()\fR get and set the function used for +processing ctrl messages in the BIO respectively. See the \fBBIO_ctrl\fR\|(3) page for +more information. This function will be called in response to the application +calling \fBBIO_ctrl()\fR. The parameters for the function have the same meaning as for +\&\fBBIO_ctrl()\fR. +.PP +\&\fBBIO_meth_get_create()\fR and \fBBIO_meth_set_create()\fR get and set the function used +for creating a new instance of the BIO respectively. This function will be +called in response to the application calling \fBBIO_new()\fR and passing +in a pointer to the current BIO_METHOD. The \fBBIO_new()\fR function will allocate the +memory for the new BIO, and a pointer to this newly allocated structure will +be passed as a parameter to the function. If a create function is set, +\&\fBBIO_new()\fR will not mark the BIO as initialised on allocation. +\&\fBBIO_set_init\fR\|(3) must then be called either by the create function, or later, +by a BIO ctrl function, once BIO initialisation is complete. +.PP +\&\fBBIO_meth_get_destroy()\fR and \fBBIO_meth_set_destroy()\fR get and set the function used +for destroying an instance of a BIO respectively. This function will be +called in response to the application calling \fBBIO_free()\fR. A pointer to the BIO +to be destroyed is passed as a parameter. The destroy function should be used +for BIO specific clean up. The memory for the BIO itself should not be freed by +this function. +.PP +\&\fBBIO_meth_get_callback_ctrl()\fR and \fBBIO_meth_set_callback_ctrl()\fR get and set the +function used for processing callback ctrl messages in the BIO respectively. See +the \fBBIO_callback_ctrl\fR\|(3) page for more information. This function will be called +in response to the application calling \fBBIO_callback_ctrl()\fR. The parameters for +the function have the same meaning as for \fBBIO_callback_ctrl()\fR. +.PP +\&\fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, \fBBIO_meth_get_recvmmsg()\fR and +\&\fBBIO_meth_set_recvmmsg()\fR get and set the functions used for handling +\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR calls respectively. See \fBBIO_sendmmsg\fR\|(3) for +more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_get_new_index()\fR returns the new BIO type value or \-1 if an error occurred. +.PP +BIO_meth_new(int type, const char *name) returns a valid \fBBIO_METHOD\fR or NULL +if an error occurred. +.PP +The \fBBIO_meth_set\fR functions return 1 on success or 0 on error. +.PP +The \fBBIO_meth_get\fR functions return the corresponding function pointers. +.SH BUGS +.IX Header "BUGS" +It is not safe to use \f(CW\*(C`BIO_meth_get_\*(C'\fR functions to reuse the \fBBIO\fR +implementation of \fBBIO\fRs implemented by OpenSSL itself with +application\-implemented \fBBIO\fRs. Instead either the applications ought to +implement these functions themselves or they should implement a filter BIO. +.PP +For more details please see . +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), \fBBIO_find_type\fR\|(3), \fBBIO_ctrl\fR\|(3), \fBBIO_read_ex\fR\|(3), \fBBIO_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, +\&\fBBIO_meth_get_recvmmsg()\fR and \fBBIO_meth_set_recvmmsg()\fR were added in OpenSSL 3.2. +.PP +All the other functions described here were added in OpenSSL 1.1.0. +.PP +The functions \fBBIO_meth_get_read_ex()\fR, \fBBIO_meth_get_write_ex()\fR, +\&\fBBIO_meth_get_write()\fR, \fBBIO_meth_get_read()\fR, \fBBIO_meth_get_puts()\fR, +\&\fBBIO_meth_get_gets()\fR, \fBBIO_meth_get_ctrl()\fR, \fBBIO_meth_get_create()\fR, +\&\fBBIO_meth_get_destroy()\fR, \fBBIO_meth_get_callback_ctrl()\fR, +\&\fBBIO_meth_get_sendmmsg()\fR and \fBBIO_meth_get_recvmmsg()\fR are deprecated since +OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_new.3 b/static/netbsd/man3/BIO_new.3 new file mode 100644 index 00000000..505fc6bb --- /dev/null +++ b/static/netbsd/man3/BIO_new.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: BIO_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_new 3" +.TH BIO_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all +\&\- BIO allocation and freeing functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type); +\& BIO *BIO_new(const BIO_METHOD *type); +\& int BIO_up_ref(BIO *a); +\& int BIO_free(BIO *a); +\& void BIO_vfree(BIO *a); +\& void BIO_free_all(BIO *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_new_ex()\fR function returns a new BIO using method \fBtype\fR associated with +the library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)). The library context may be +NULL to indicate the default library context. \fItype\fR \fBMUST NOT\fR be NULL. +.PP +The \fBBIO_new()\fR is the same as \fBBIO_new_ex()\fR except the default library context is +always used. +.PP +\&\fBBIO_up_ref()\fR increments the reference count associated with the BIO object. +.PP +\&\fBBIO_free()\fR frees up a single BIO, \fBBIO_vfree()\fR also frees up a single BIO +but it does not return a value. +If \fBa\fR is NULL nothing is done. +Calling \fBBIO_free()\fR may also have some effect +on the underlying I/O structure, for example it may close the file being +referred to under certain circumstances. For more details see the individual +BIO_METHOD descriptions. +.PP +\&\fBBIO_free_all()\fR frees up an entire BIO chain, it does not halt if an error +occurs freeing up an individual BIO in the chain. +If \fBa\fR is NULL nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_new_ex()\fR and \fBBIO_new()\fR return a newly created BIO or NULL if the call fails. +.PP +\&\fBBIO_up_ref()\fR and \fBBIO_free()\fR return 1 for success and 0 for failure. +.PP +\&\fBBIO_free_all()\fR and \fBBIO_vfree()\fR do not return values. +.SH NOTES +.IX Header "NOTES" +If \fBBIO_free()\fR is called on a BIO chain it will only free one BIO resulting +in a memory leak. +.PP +Calling \fBBIO_free_all()\fR on a single BIO has the same effect as calling \fBBIO_free()\fR +on it other than the discarded return value. +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_set()\fR was removed in OpenSSL 1.1.0 as BIO type is now opaque. +.PP +\&\fBBIO_new_ex()\fR was added in OpenSSL 3.0. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create a memory BIO: +.PP +.Vb 1 +\& BIO *mem = BIO_new(BIO_s_mem()); +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_new_CMS.3 b/static/netbsd/man3/BIO_new_CMS.3 new file mode 100644 index 00000000..fec922a6 --- /dev/null +++ b/static/netbsd/man3/BIO_new_CMS.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: BIO_new_CMS.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_new_CMS 3" +.TH BIO_new_CMS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_new_CMS \- CMS streaming filter BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_new_CMS()\fR returns a streaming filter BIO chain based on \fBcms\fR. The output +of the filter is written to \fBout\fR. Any data written to the chain is +automatically translated to a BER format CMS structure of the appropriate type. +.SH NOTES +.IX Header "NOTES" +The chain returned by this function behaves like a standard filter BIO. It +supports non blocking I/O. Content is processed and streamed on the fly and not +all held in memory at once: so it is possible to encode very large structures. +After all content has been written through the chain \fBBIO_flush()\fR must be called +to finalise the structure. +.PP +The \fBCMS_STREAM\fR flag must be included in the corresponding \fBflags\fR +parameter of the \fBcms\fR creation function. +.PP +If an application wishes to write additional data to \fBout\fR BIOs should be +removed from the chain using \fBBIO_pop()\fR and freed with \fBBIO_free()\fR until \fBout\fR +is reached. If no additional data needs to be written \fBBIO_free_all()\fR can be +called to free up the whole chain. +.PP +Any content written through the filter is used verbatim: no canonical +translation is performed. +.PP +It is possible to chain multiple BIOs to, for example, create a triple wrapped +signed, enveloped, signed structure. In this case it is the applications +responsibility to set the inner content type of any outer CMS_ContentInfo +structures. +.PP +Large numbers of small writes through the chain should be avoided as this will +produce an output consisting of lots of OCTET STRING structures. Prepending +a \fBBIO_f_buffer()\fR buffering BIO will prevent this. +.SH BUGS +.IX Header "BUGS" +There is currently no corresponding inverse BIO: i.e. one which can decode +a CMS structure on the fly. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_new_CMS()\fR returns a BIO chain when successful or NULL if an error +occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_encrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_new_CMS()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_parse_hostserv.3 b/static/netbsd/man3/BIO_parse_hostserv.3 new file mode 100644 index 00000000..a46dbce4 --- /dev/null +++ b/static/netbsd/man3/BIO_parse_hostserv.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: BIO_parse_hostserv.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_parse_hostserv 3" +.TH BIO_parse_hostserv 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_hostserv_priorities, +BIO_parse_hostserv +\&\- utility routines to parse a standard host and service string +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& enum BIO_hostserv_priorities { +\& BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV +\& }; +\& int BIO_parse_hostserv(const char *hostserv, char **host, char **service, +\& enum BIO_hostserv_priorities hostserv_prio); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_parse_hostserv()\fR will parse the information given in \fBhostserv\fR, +create strings with the hostname and service name and give those +back via \fBhost\fR and \fBservice\fR. Those will need to be freed after +they are used. \fBhostserv_prio\fR helps determine if \fBhostserv\fR shall +be interpreted primarily as a hostname or a service name in ambiguous +cases. +.PP +The syntax the \fBBIO_parse_hostserv()\fR recognises is: +.PP +.Vb 7 +\& host + \*(Aq:\*(Aq + service +\& host + \*(Aq:\*(Aq + \*(Aq*\*(Aq +\& host + \*(Aq:\*(Aq +\& \*(Aq:\*(Aq + service +\& \*(Aq*\*(Aq + \*(Aq:\*(Aq + service +\& host +\& service +.Ve +.PP +The host part can be a name or an IP address. If it\*(Aqs a IPv6 +address, it MUST be enclosed in brackets, such as \*(Aq[::1]\*(Aq. +.PP +The service part can be a service name or its port number. A service name +will be mapped to a port number using the system function \fBgetservbyname()\fR. +.PP +The returned values will depend on the given \fBhostserv\fR string +and \fBhostserv_prio\fR, as follows: +.PP +.Vb 5 +\& host + \*(Aq:\*(Aq + service => *host = "host", *service = "service" +\& host + \*(Aq:\*(Aq + \*(Aq*\*(Aq => *host = "host", *service = NULL +\& host + \*(Aq:\*(Aq => *host = "host", *service = NULL +\& \*(Aq:\*(Aq + service => *host = NULL, *service = "service" +\& \*(Aq*\*(Aq + \*(Aq:\*(Aq + service => *host = NULL, *service = "service" +\& +\& in case no \*(Aq:\*(Aq is present in the string, the result depends on +\& hostserv_prio, as follows: +\& +\& when hostserv_prio == BIO_PARSE_PRIO_HOST +\& host => *host = "host", *service untouched +\& +\& when hostserv_prio == BIO_PARSE_PRIO_SERV +\& service => *host untouched, *service = "service" +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_parse_hostserv()\fR returns 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_ADDRINFO\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_printf.3 b/static/netbsd/man3/BIO_printf.3 new file mode 100644 index 00000000..f99b1d4f --- /dev/null +++ b/static/netbsd/man3/BIO_printf.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: BIO_printf.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_printf 3" +.TH BIO_printf 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf +\&\- formatted output to a BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BIO_printf(BIO *bio, const char *format, ...); +\& int BIO_vprintf(BIO *bio, const char *format, va_list args); +\& +\& int BIO_snprintf(char *buf, size_t n, const char *format, ...); +\& int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_printf()\fR is similar to the standard C \fBprintf()\fR function, except that +the output is sent to the specified BIO, \fIbio\fR, rather than standard +output. All common format specifiers are supported. +.PP +\&\fBBIO_vprintf()\fR is similar to the \fBvprintf()\fR function found on many platforms, +the output is sent to the specified BIO, \fIbio\fR, rather than standard +output. All common format specifiers are supported. The argument +list \fIargs\fR is a stdarg argument list. +.PP +\&\fBBIO_snprintf()\fR is for platforms that do not have the common \fBsnprintf()\fR +function. It is like \fBsprintf()\fR except that the size parameter, \fIn\fR, +specifies the size of the output buffer. +.PP +\&\fBBIO_vsnprintf()\fR is to \fBBIO_snprintf()\fR as \fBBIO_vprintf()\fR is to \fBBIO_printf()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return the number of bytes written, or \-1 on error. +For \fBBIO_snprintf()\fR and \fBBIO_vsnprintf()\fR this includes when the output +buffer is too small. +.SH NOTES +.IX Header "NOTES" +Except when \fIn\fR is 0, both \fBBIO_snprintf()\fR and \fBBIO_vsnprintf()\fR always +terminate their output with \f(CW\*(Aq\e0\*(Aq\fR. This includes cases where \-1 is +returned, such as when there is insufficient space to output the whole +string. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_push.3 b/static/netbsd/man3/BIO_push.3 new file mode 100644 index 00000000..31ec2caf --- /dev/null +++ b/static/netbsd/man3/BIO_push.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: BIO_push.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_push 3" +.TH BIO_push 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_push, BIO_pop, BIO_set_next \- add and remove BIOs from a chain +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO *BIO_push(BIO *b, BIO *next); +\& BIO *BIO_pop(BIO *b); +\& void BIO_set_next(BIO *b, BIO *next); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_push()\fR pushes \fIb\fR on \fInext\fR. +If \fIb\fR is NULL the function does nothing and returns \fInext\fR. +Otherwise it prepends \fIb\fR, which may be a single BIO or a chain of BIOs, +to \fInext\fR (unless \fInext\fR is NULL). +It then makes a control call on \fIb\fR and returns \fIb\fR. +.PP +\&\fBBIO_pop()\fR removes the BIO \fIb\fR from any chain it is part of. +If \fIb\fR is NULL the function does nothing and returns NULL. +Otherwise it makes a control call on \fIb\fR and +returns the next BIO in the chain, or NULL if there is no next BIO. +The removed BIO becomes a single BIO with no association with +the original chain, it can thus be freed or be made part of a different chain. +.PP +\&\fBBIO_set_next()\fR replaces the existing next BIO in a chain with the BIO pointed to +by \fInext\fR. The new chain may include some of the same BIOs from the old chain +or it may be completely different. +.SH NOTES +.IX Header "NOTES" +The names of these functions are perhaps a little misleading. \fBBIO_push()\fR +joins two BIO chains whereas \fBBIO_pop()\fR deletes a single BIO from a chain, +the deleted BIO does not need to be at the end of a chain. +.PP +The process of calling \fBBIO_push()\fR and \fBBIO_pop()\fR on a BIO may have additional +consequences (a control call is made to the affected BIOs). +Any effects will be noted in the descriptions of individual BIOs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_push()\fR returns the head of the chain, +which usually is \fIb\fR, or \fInext\fR if \fIb\fR is NULL. +.PP +\&\fBBIO_pop()\fR returns the next BIO in the chain, +or NULL if there is no next BIO. +.SH EXAMPLES +.IX Header "EXAMPLES" +For these examples suppose \fImd1\fR and \fImd2\fR are digest BIOs, +\&\fIb64\fR is a base64 BIO and \fIf\fR is a file BIO. +.PP +If the call: +.PP +.Vb 1 +\& BIO_push(b64, f); +.Ve +.PP +is made then the new chain will be \fIb64\-f\fR. After making the calls +.PP +.Vb 2 +\& BIO_push(md2, b64); +\& BIO_push(md1, md2); +.Ve +.PP +the new chain is \fImd1\-md2\-b64\-f\fR. Data written to \fImd1\fR will be digested +by \fImd1\fR and \fImd2\fR, base64 encoded, and finally written to \fIf\fR. +.PP +It should be noted that reading causes data to pass in the reverse +direction, that is data is read from \fIf\fR, base64 decoded, +and digested by \fImd2\fR and then \fImd1\fR. +.PP +The call: +.PP +.Vb 1 +\& BIO_pop(md2); +.Ve +.PP +will return \fIb64\fR and the new chain will be \fImd1\-b64\-f\fR. +Data can be written to and read from \fImd1\fR as before, +except that \fImd2\fR will no more be applied. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_set_next()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_read.3 b/static/netbsd/man3/BIO_read.3 new file mode 100644 index 00000000..1b8cc4c1 --- /dev/null +++ b/static/netbsd/man3/BIO_read.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: BIO_read.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_read 3" +.TH BIO_read 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, +BIO_gets, BIO_get_line, BIO_puts +\&\- BIO I/O functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes); +\& int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written); +\& +\& int BIO_read(BIO *b, void *data, int dlen); +\& int BIO_gets(BIO *b, char *buf, int size); +\& int BIO_get_line(BIO *b, char *buf, int size); +\& int BIO_write(BIO *b, const void *data, int dlen); +\& int BIO_puts(BIO *b, const char *buf); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_read_ex()\fR attempts to read \fIdlen\fR bytes from BIO \fIb\fR and places the data +in \fIdata\fR. If any bytes were successfully read then the number of bytes read is +stored in \fI*readbytes\fR. +.PP +\&\fBBIO_write_ex()\fR attempts to write \fIdlen\fR bytes from \fIdata\fR to BIO \fIb\fR. +If successful then the number of bytes written is stored in \fI*written\fR +unless \fIwritten\fR is NULL. +.PP +\&\fBBIO_read()\fR attempts to read \fIlen\fR bytes from BIO \fIb\fR and places +the data in \fIbuf\fR. +.PP +\&\fBBIO_gets()\fR performs the BIOs "gets" operation and places the data +in \fIbuf\fR. Usually this operation will attempt to read a line of data +from the BIO of maximum length \fIsize\-1\fR. There are exceptions to this, +however; for example, \fBBIO_gets()\fR on a digest BIO will calculate and +return the digest and other BIOs may not support \fBBIO_gets()\fR at all. +The returned string is always NUL\-terminated and the \*(Aq\en\*(Aq is preserved +if present in the input data. +On binary input there may be NUL characters within the string; +in this case the return value (if nonnegative) may give an incorrect length. +.PP +\&\fBBIO_get_line()\fR attempts to read from BIO \fIb\fR a line of data up to the next \*(Aq\en\*(Aq +or the maximum length \fIsize\-1\fR is reached and places the data in \fIbuf\fR. +The returned string is always NUL\-terminated and the \*(Aq\en\*(Aq is preserved +if present in the input data. +On binary input there may be NUL characters within the string; +in this case the return value (if nonnegative) gives the actual length read. +For implementing this, unfortunately the data needs to be read byte\-by\-byte. +.PP +\&\fBBIO_write()\fR attempts to write \fIlen\fR bytes from \fIbuf\fR to BIO \fIb\fR. +.PP +\&\fBBIO_puts()\fR attempts to write a NUL\-terminated string \fIbuf\fR to BIO \fIb\fR, +without the terminating NUL byte and without appending \*(Aq\en\*(Aq +(so, similar to \fBfputs\fR\|(3), and not \fBputs\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_read_ex()\fR returns 1 if data was successfully read, and 0 otherwise. +.PP +\&\fBBIO_write_ex()\fR returns 1 if no error was encountered writing data, 0 otherwise. +Requesting to write 0 bytes is not considered an error. +.PP +\&\fBBIO_write()\fR returns \-2 if the "write" operation is not implemented by the BIO +or \-1 on other errors. +Otherwise it returns the number of bytes written. +This may be 0 if the BIO \fIb\fR is NULL or \fIdlen <= 0\fR. +.PP +\&\fBBIO_gets()\fR returns \-2 if the "gets" operation is not implemented by the BIO +or \-1 on other errors. +Otherwise it typically returns the amount of data read, +but depending on the implementation it may return only the length up to +the first NUL character contained in the data read. +In any case the trailing NUL that is added after the data read +is not included in the length returned. +.PP +All other functions return either the amount of data successfully read or +written (if the return value is positive) or that no data was successfully +read or written if the result is 0 or \-1. If the return value is \-2 then +the operation is not implemented in the specific BIO type. +.SH NOTES +.IX Header "NOTES" +A 0 or \-1 return is not necessarily an indication of an error. In +particular when the source/sink is nonblocking or of a certain type +it may merely be an indication that no data is currently available and that +the application should retry the operation later. +.PP +One technique sometimes used with blocking sockets is to use a system call +(such as \fBselect()\fR, \fBpoll()\fR or equivalent) to determine when data is available +and then call \fBread()\fR to read the data. The equivalent with BIOs (that is call +\&\fBselect()\fR on the underlying I/O structure and then call \fBBIO_read()\fR to +read the data) should \fBnot\fR be used because a single call to \fBBIO_read()\fR +can cause several reads (and writes in the case of SSL BIOs) on the underlying +I/O structure and may block as a result. Instead \fBselect()\fR (or equivalent) +should be combined with non blocking I/O so successive reads will request +a retry instead of blocking. +.PP +See \fBBIO_should_retry\fR\|(3) for details of how to +determine the cause of a retry and other I/O issues. +.PP +If the "gets" method is not supported by a BIO then \fBBIO_get_line()\fR can be used. +It is also possible to make \fBBIO_gets()\fR usable even if the "gets" method is not +supported by adding a buffering BIO \fBBIO_f_buffer\fR\|(3) to the chain. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_should_retry\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_gets()\fR on 1.1.0 and older when called on \fBBIO_fd()\fR based BIO did not +keep the \*(Aq\en\*(Aq at the end of the line in the buffer. +.PP +\&\fBBIO_get_line()\fR was added in OpenSSL 3.0. +.PP +\&\fBBIO_write_ex()\fR returns 1 if the size of the data to write is 0 and the +\&\fIwritten\fR parameter of the function can be NULL since OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_accept.3 b/static/netbsd/man3/BIO_s_accept.3 new file mode 100644 index 00000000..0a6e426e --- /dev/null +++ b/static/netbsd/man3/BIO_s_accept.3 @@ -0,0 +1,315 @@ +.\" $NetBSD: BIO_s_accept.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_accept 3" +.TH BIO_s_accept 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, +BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios, +BIO_get_peer_name, BIO_get_peer_port, +BIO_get_accept_ip_family, BIO_set_accept_ip_family, +BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept \- accept BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_accept(void); +\& +\& long BIO_set_accept_name(BIO *b, char *name); +\& char *BIO_get_accept_name(BIO *b); +\& +\& long BIO_set_accept_port(BIO *b, char *port); +\& char *BIO_get_accept_port(BIO *b); +\& +\& BIO *BIO_new_accept(char *host_port); +\& +\& long BIO_set_nbio_accept(BIO *b, int n); +\& long BIO_set_tfo_accept(BIO *b, int n); +\& long BIO_set_accept_bios(BIO *b, char *bio); +\& +\& char *BIO_get_peer_name(BIO *b); +\& char *BIO_get_peer_port(BIO *b); +\& long BIO_get_accept_ip_family(BIO *b); +\& long BIO_set_accept_ip_family(BIO *b, long family); +\& +\& long BIO_set_bind_mode(BIO *b, long mode); +\& long BIO_get_bind_mode(BIO *b); +\& +\& int BIO_do_accept(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_accept()\fR returns the accept BIO method. This is a wrapper +round the platform\*(Aqs TCP/IP socket accept routines. +.PP +Using accept BIOs, TCP/IP connections can be accepted and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. +.PP +Read and write operations on an accept BIO will perform I/O +on the underlying connection. If no connection is established +and the port (see below) is set up properly then the BIO +waits for an incoming connection. +.PP +Accept BIOs support \fBBIO_puts()\fR but not \fBBIO_gets()\fR. +.PP +If the close flag is set on an accept BIO then any active +connection on that chain is shutdown and the socket closed when +the BIO is freed. +.PP +Calling \fBBIO_reset()\fR on an accept BIO will close any active +connection and reset the BIO into a state where it awaits another +incoming connection. +.PP +\&\fBBIO_get_fd()\fR and \fBBIO_set_fd()\fR can be called to retrieve or set +the accept socket. See \fBBIO_s_fd\fR\|(3) +.PP +\&\fBBIO_set_accept_name()\fR uses the string \fBname\fR to set the accept +name. The name is represented as a string of the form "host:port", +where "host" is the interface to use and "port" is the port. +The host can be "*" or empty which is interpreted as meaning +any interface. If the host is an IPv6 address, it has to be +enclosed in brackets, for example "[::1]:https". "port" has the +same syntax as the port specified in \fBBIO_set_conn_port()\fR for +connect BIOs, that is it can be a numerical port string or a +string to lookup using \fBgetservbyname()\fR and a string table. +.PP +\&\fBBIO_set_accept_port()\fR uses the string \fBport\fR to set the accept +port of BIO \fIb\fR. "port" has the same syntax as the port specified in +\&\fBBIO_set_conn_port()\fR for connect BIOs, that is it can be a numerical +port string or a string to lookup using \fBgetservbyname()\fR and a string +table. +If the given port is \f(CW0\fR then a random available port is chosen. +It may be queried using \fBBIO_sock_info()\fR and \fBBIO_ADDR_service_string\fR\|(3). +.PP +\&\fBBIO_new_accept()\fR combines \fBBIO_new()\fR and \fBBIO_set_accept_name()\fR into +a single call: that is it creates a new accept BIO with port +\&\fBhost_port\fR. +.PP +\&\fBBIO_set_nbio_accept()\fR sets the accept socket to blocking mode +(the default) if \fBn\fR is 0 or non blocking mode if \fBn\fR is 1. +.PP +\&\fBBIO_set_tfo_accept()\fR enables TCP Fast Open on the accept socket +if \fBn\fR is 1 or disables TCP Fast Open if \fBn\fR is 0 (the default). +Setting the value to 1 is equivalent to setting \fBBIO_SOCK_TFO\fR +in \fBBIO_set_bind_mode()\fR. +.PP +\&\fBBIO_set_accept_bios()\fR can be used to set a chain of BIOs which +will be duplicated and prepended to the chain when an incoming +connection is received. This is useful if, for example, a +buffering or SSL BIO is required for each connection. The +chain of BIOs must not be freed after this call, they will +be automatically freed when the accept BIO is freed. +.PP +\&\fBBIO_get_accept_ip_family()\fR returns the IP family accepted by the BIO \fIb\fR, +which may be \fBBIO_FAMILY_IPV4\fR, \fBBIO_FAMILY_IPV6\fR, or \fBBIO_FAMILY_IPANY\fR. +.PP +\&\fBBIO_set_accept_ip_family()\fR sets the IP family \fIfamily\fR accepted by BIO \fIb\fR. +The default is \fBBIO_FAMILY_IPANY\fR. +.PP +\&\fBBIO_set_bind_mode()\fR and \fBBIO_get_bind_mode()\fR set and retrieve +the current bind mode. If \fBBIO_BIND_NORMAL\fR (the default) is set +then another socket cannot be bound to the same port. If +\&\fBBIO_BIND_REUSEADDR\fR is set then other sockets can bind to the +same port. If \fBBIO_BIND_REUSEADDR_IF_UNUSED\fR is set then and +attempt is first made to use BIO_BIN_NORMAL, if this fails +and the port is not in use then a second attempt is made +using \fBBIO_BIND_REUSEADDR\fR. If \fBBIO_SOCK_TFO\fR is set, then +the socket will be configured to accept TCP Fast Open +connections. +.PP +\&\fBBIO_do_accept()\fR serves two functions. When it is first +called, after the accept BIO has been setup, it will attempt +to create the accept socket and bind an address to it. Second +and subsequent calls to \fBBIO_do_accept()\fR will await an incoming +connection, or request a retry in non blocking mode. +.SH NOTES +.IX Header "NOTES" +When an accept BIO is at the end of a chain it will await an +incoming connection before processing I/O calls. When an accept +BIO is not at then end of a chain it passes I/O calls to the next +BIO in the chain. +.PP +When a connection is established a new socket BIO is created for +the connection and appended to the chain. That is the chain is now +accept\->socket. This effectively means that attempting I/O on +an initial accept socket will await an incoming connection then +perform I/O on it. +.PP +If any additional BIOs have been set using \fBBIO_set_accept_bios()\fR +then they are placed between the socket and the accept BIO, +that is the chain will be accept\->otherbios\->socket. +.PP +If a server wishes to process multiple connections (as is normally +the case) then the accept BIO must be made available for further +incoming connections. This can be done by waiting for a connection and +then calling: +.PP +.Vb 1 +\& connection = BIO_pop(accept); +.Ve +.PP +After this call \fBconnection\fR will contain a BIO for the recently +established connection and \fBaccept\fR will now be a single BIO +again which can be used to await further incoming connections. +If no further connections will be accepted the \fBaccept\fR can +be freed using \fBBIO_free()\fR. +.PP +If only a single connection will be processed it is possible to +perform I/O using the accept BIO itself. This is often undesirable +however because the accept BIO will still accept additional incoming +connections. This can be resolved by using \fBBIO_pop()\fR (see above) +and freeing up the accept BIO after the initial connection. +.PP +If the underlying accept socket is nonblocking and \fBBIO_do_accept()\fR is +called to await an incoming connection it is possible for +\&\fBBIO_should_io_special()\fR with the reason BIO_RR_ACCEPT. If this happens +then it is an indication that an accept attempt would block: the application +should take appropriate action to wait until the underlying socket has +accepted a connection and retry the call. +.PP +\&\fBBIO_set_accept_name()\fR, \fBBIO_get_accept_name()\fR, \fBBIO_set_accept_port()\fR, +\&\fBBIO_get_accept_port()\fR, \fBBIO_set_nbio_accept()\fR, \fBBIO_set_accept_bios()\fR, +\&\fBBIO_get_peer_name()\fR, \fBBIO_get_peer_port()\fR, +\&\fBBIO_get_accept_ip_family()\fR, \fBBIO_set_accept_ip_family()\fR, +\&\fBBIO_set_bind_mode()\fR, \fBBIO_get_bind_mode()\fR and \fBBIO_do_accept()\fR are macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_do_accept()\fR, +\&\fBBIO_set_accept_name()\fR, \fBBIO_set_accept_port()\fR, \fBBIO_set_nbio_accept()\fR, +\&\fBBIO_set_accept_bios()\fR, \fBBIO_set_accept_ip_family()\fR, and \fBBIO_set_bind_mode()\fR +return 1 for success and <= 0 for failure. +.PP +\&\fBBIO_get_accept_name()\fR returns the accept name or NULL on error. +\&\fBBIO_get_peer_name()\fR returns the peer name or NULL on error. +.PP +\&\fBBIO_get_accept_port()\fR returns the accept port as a string or NULL on error. +\&\fBBIO_get_peer_port()\fR returns the peer port as a string or NULL on error. +\&\fBBIO_get_accept_ip_family()\fR returns the IP family or <= 0 on error. +.PP +\&\fBBIO_get_bind_mode()\fR returns the set of \fBBIO_BIND\fR flags, or <= 0 on failure. +.PP +\&\fBBIO_new_accept()\fR returns a BIO or NULL on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example accepts two connections on port 4444, sends messages +down each and finally closes both down. +.PP +.Vb 1 +\& BIO *abio, *cbio, *cbio2; +\& +\& /* First call to BIO_do_accept() sets up accept BIO */ +\& abio = BIO_new_accept("4444"); +\& if (BIO_do_accept(abio) <= 0) { +\& fprintf(stderr, "Error setting up accept\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& +\& /* Wait for incoming connection */ +\& if (BIO_do_accept(abio) <= 0) { +\& fprintf(stderr, "Error accepting connection\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& fprintf(stderr, "Connection 1 established\en"); +\& +\& /* Retrieve BIO for connection */ +\& cbio = BIO_pop(abio); +\& BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en"); +\& fprintf(stderr, "Sent out data on connection 1\en"); +\& +\& /* Wait for another connection */ +\& if (BIO_do_accept(abio) <= 0) { +\& fprintf(stderr, "Error accepting connection\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& fprintf(stderr, "Connection 2 established\en"); +\& +\& /* Close accept BIO to refuse further connections */ +\& cbio2 = BIO_pop(abio); +\& BIO_free(abio); +\& BIO_puts(cbio2, "Connection 2: Sending out Data on second\en"); +\& fprintf(stderr, "Sent out data on connection 2\en"); +\& +\& BIO_puts(cbio, "Connection 1: Second connection established\en"); +\& +\& /* Close the two established connections */ +\& BIO_free(cbio); +\& BIO_free(cbio2); +.Ve +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_set_tfo_accept()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_bio.3 b/static/netbsd/man3/BIO_s_bio.3 new file mode 100644 index 00000000..7d6ad3be --- /dev/null +++ b/static/netbsd/man3/BIO_s_bio.3 @@ -0,0 +1,259 @@ +.\" $NetBSD: BIO_s_bio.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_bio 3" +.TH BIO_s_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request \- BIO pair BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_bio(void); +\& +\& int BIO_make_bio_pair(BIO *b1, BIO *b2); +\& int BIO_destroy_bio_pair(BIO *b); +\& int BIO_shutdown_wr(BIO *b); +\& +\& int BIO_set_write_buf_size(BIO *b, long size); +\& size_t BIO_get_write_buf_size(BIO *b, long size); +\& +\& int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); +\& +\& int BIO_get_write_guarantee(BIO *b); +\& size_t BIO_ctrl_get_write_guarantee(BIO *b); +\& int BIO_get_read_request(BIO *b); +\& size_t BIO_ctrl_get_read_request(BIO *b); +\& int BIO_ctrl_reset_read_request(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_bio()\fR returns the method for a BIO pair. A BIO pair is a pair of source/sink +BIOs where data written to either half of the pair is buffered and can be read from +the other half. Both halves must usually by handled by the same application thread +since no locking is done on the internal data structures. +.PP +Since BIO chains typically end in a source/sink BIO it is possible to make this +one half of a BIO pair and have all the data processed by the chain under application +control. +.PP +One typical use of BIO pairs is to place TLS/SSL I/O under application control, this +can be used when the application wishes to use a non standard transport for +TLS/SSL or the normal socket routines are inappropriate. +.PP +Calls to \fBBIO_read_ex()\fR will read data from the buffer or request a retry if no +data is available. +.PP +Calls to \fBBIO_write_ex()\fR will place data in the buffer or request a retry if the +buffer is full. +.PP +The standard calls \fBBIO_ctrl_pending()\fR and \fBBIO_ctrl_wpending()\fR can be used to +determine the amount of pending data in the read or write buffer. +.PP +\&\fBBIO_reset()\fR clears any data in the write buffer. +.PP +\&\fBBIO_make_bio_pair()\fR joins two separate BIOs into a connected pair. +.PP +\&\fBBIO_destroy_pair()\fR destroys the association between two connected BIOs. Freeing +up any half of the pair will automatically destroy the association. +.PP +\&\fBBIO_shutdown_wr()\fR is used to close down a BIO \fBb\fR. After this call no further +writes on BIO \fBb\fR are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. +.PP +\&\fBBIO_set_write_buf_size()\fR sets the write buffer size of BIO \fBb\fR to \fBsize\fR. +If the size is not initialized a default value is used. This is currently +17K, sufficient for a maximum size TLS record. +.PP +\&\fBBIO_get_write_buf_size()\fR returns the size of the write buffer. +.PP +\&\fBBIO_new_bio_pair()\fR combines the calls to \fBBIO_new()\fR, \fBBIO_make_bio_pair()\fR and +\&\fBBIO_set_write_buf_size()\fR to create a connected pair of BIOs \fBbio1\fR, \fBbio2\fR +with write buffer sizes \fBwritebuf1\fR and \fBwritebuf2\fR. If either size is +zero then the default size is used. \fBBIO_new_bio_pair()\fR does not check whether +\&\fBbio1\fR or \fBbio2\fR do point to some other BIO, the values are overwritten, +\&\fBBIO_free()\fR is not called. +.PP +\&\fBBIO_get_write_guarantee()\fR and \fBBIO_ctrl_get_write_guarantee()\fR return the maximum +length of data that can be currently written to the BIO. Writes larger than this +value will return a value from \fBBIO_write_ex()\fR less than the amount requested or +if the buffer is full request a retry. \fBBIO_ctrl_get_write_guarantee()\fR is a +function whereas \fBBIO_get_write_guarantee()\fR is a macro. +.PP +\&\fBBIO_get_read_request()\fR and \fBBIO_ctrl_get_read_request()\fR return the +amount of data requested, or the buffer size if it is less, if the +last read attempt at the other half of the BIO pair failed due to an +empty buffer. This can be used to determine how much data should be +written to the BIO so the next read will succeed: this is most useful +in TLS/SSL applications where the amount of data read is usually +meaningful rather than just a buffer size. After a successful read +this call will return zero. It also will return zero once new data +has been written satisfying the read request or part of it. +Note that \fBBIO_get_read_request()\fR never returns an amount larger +than that returned by \fBBIO_get_write_guarantee()\fR. +.PP +\&\fBBIO_ctrl_reset_read_request()\fR can also be used to reset the value returned by +\&\fBBIO_get_read_request()\fR to zero. +.SH NOTES +.IX Header "NOTES" +Both halves of a BIO pair should be freed. That is even if one half is implicit +freed due to a \fBBIO_free_all()\fR or \fBSSL_free()\fR call the other half needs to be freed. +.PP +When used in bidirectional applications (such as TLS/SSL) care should be taken to +flush any data in the write buffer. This can be done by calling \fBBIO_pending()\fR +on the other half of the pair and, if any data is pending, reading it and sending +it to the underlying transport. This must be done before any normal processing +(such as calling \fBselect()\fR ) due to a request and \fBBIO_should_read()\fR being true. +.PP +To see why this is important consider a case where a request is sent using +\&\fBBIO_write_ex()\fR and a response read with \fBBIO_read_ex()\fR, this can occur during an +TLS/SSL handshake for example. \fBBIO_write_ex()\fR will succeed and place data in the +write buffer. \fBBIO_read_ex()\fR will initially fail and \fBBIO_should_read()\fR will be +true. If the application then waits for data to be available on the underlying +transport before flushing the write buffer it will never succeed because the +request was never sent! +.PP +\&\fBBIO_eof()\fR is true if no data is in the peer BIO and the peer BIO has been +shutdown. +.PP +\&\fBBIO_make_bio_pair()\fR, \fBBIO_destroy_bio_pair()\fR, \fBBIO_shutdown_wr()\fR, +\&\fBBIO_set_write_buf_size()\fR, \fBBIO_get_write_buf_size()\fR, +\&\fBBIO_get_write_guarantee()\fR, and \fBBIO_get_read_request()\fR are implemented +as macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in +\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with NULL pointers stored into the +locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information. +.PP +[XXXXX: More return values need to be added here] +.SH EXAMPLES +.IX Header "EXAMPLES" +The BIO pair can be used to have full control over the network access of an +application. The application can call \fBselect()\fR on the socket as required +without having to go through the SSL\-interface. +.PP +.Vb 1 +\& BIO *internal_bio, *network_bio; +\& +\& ... +\& BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); +\& SSL_set_bio(ssl, internal_bio, internal_bio); +\& SSL_operations(); /* e.g. SSL_read and SSL_write */ +\& ... +\& +\& application | TLS\-engine +\& | | +\& +\-\-\-\-\-\-\-\-\-\-> SSL_operations() +\& | /\e || +\& | || \e/ +\& | BIO\-pair (internal_bio) +\& | BIO\-pair (network_bio) +\& | || /\e +\& | \e/ || +\& +\-\-\-\-\-\-\-\-\-\-\-< BIO_operations() +\& | | +\& | | +\& socket +\& +\& ... +\& SSL_free(ssl); /* implicitly frees internal_bio */ +\& BIO_free(network_bio); +\& ... +.Ve +.PP +As the BIO pair will only buffer the data and never directly access the +connection, it behaves nonblocking and will return as soon as the write +buffer is full or the read buffer is drained. Then the application has to +flush the write buffer and/or fill the read buffer. +.PP +Use the \fBBIO_ctrl_pending()\fR, to find out whether data is buffered in the BIO +and must be transferred to the network. Use \fBBIO_ctrl_get_read_request()\fR to +find out, how many bytes must be written into the buffer before the +\&\fBSSL_operation()\fR can successfully be continued. +.SH WARNINGS +.IX Header "WARNINGS" +As the data is buffered, \fBSSL_operation()\fR may return with an ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. An application must +not rely on the error value of \fBSSL_operation()\fR but must assure that the +write buffer is always flushed first. Otherwise a deadlock may occur as +the peer might be waiting for the data before being able to continue. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_set_bio\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7), +\&\fBBIO_should_retry\fR\|(3), \fBBIO_read_ex\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_connect.3 b/static/netbsd/man3/BIO_s_connect.3 new file mode 100644 index 00000000..a7ed4790 --- /dev/null +++ b/static/netbsd/man3/BIO_s_connect.3 @@ -0,0 +1,293 @@ +.\" $NetBSD: BIO_s_connect.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_connect 3" +.TH BIO_s_connect 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_connect, BIO_new_connect, +BIO_set_conn_hostname, BIO_set_conn_port, +BIO_set_conn_address, BIO_set_conn_ip_family, +BIO_get_conn_hostname, BIO_get_conn_port, +BIO_get_conn_address, BIO_get_conn_ip_family, +BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio, +BIO_do_connect \- connect BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_connect(void); +\& +\& BIO *BIO_new_connect(const char *name); +\& +\& long BIO_set_conn_hostname(BIO *b, char *name); +\& long BIO_set_conn_port(BIO *b, char *port); +\& long BIO_set_conn_address(BIO *b, BIO_ADDR *addr); +\& long BIO_set_conn_ip_family(BIO *b, long family); +\& const char *BIO_get_conn_hostname(BIO *b); +\& const char *BIO_get_conn_port(BIO *b); +\& const BIO_ADDR *BIO_get_conn_address(BIO *b); +\& const long BIO_get_conn_ip_family(BIO *b); +\& +\& long BIO_set_nbio(BIO *b, long n); +\& +\& int BIO_set_sock_type(BIO *b, int sock_type); +\& int BIO_get_sock_type(BIO *b); +\& int BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio); +\& +\& long BIO_do_connect(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_connect()\fR returns the connect BIO method. This is a wrapper +round the platform\*(Aqs TCP/IP socket connection routines. +.PP +Using connect BIOs, TCP/IP connections can be made and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. +.PP +Read and write operations on a connect BIO will perform I/O +on the underlying connection. If no connection is established +and the port and hostname (see below) is set up properly then +a connection is established first. +.PP +Connect BIOs support \fBBIO_puts()\fR and \fBBIO_gets()\fR. +.PP +If the close flag is set on a connect BIO then any active +connection is shutdown and the socket closed when the BIO +is freed. +.PP +Calling \fBBIO_reset()\fR on a connect BIO will close any active +connection and reset the BIO into a state where it can connect +to the same host again. +.PP +\&\fBBIO_new_connect()\fR combines \fBBIO_new()\fR and \fBBIO_set_conn_hostname()\fR into +a single call: that is it creates a new connect BIO with hostname \fBname\fR. +.PP +\&\fBBIO_set_conn_hostname()\fR uses the string \fBname\fR to set the hostname. +The hostname can be an IP address; if the address is an IPv6 one, it +must be enclosed in brackets \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +The hostname can also include the port in the form hostname:port; +see \fBBIO_parse_hostserv\fR\|(3) and \fBBIO_set_conn_port()\fR for details. +.PP +\&\fBBIO_set_conn_port()\fR sets the port to \fBport\fR. \fBport\fR can be the +numerical form or a service string such as "http", which +will be mapped to a port number using the system function \fBgetservbyname()\fR. +.PP +\&\fBBIO_set_conn_address()\fR sets the address and port information using +a \fBBIO_ADDR\fR\|(3ssl). +.PP +\&\fBBIO_set_conn_ip_family()\fR sets the IP family. +.PP +\&\fBBIO_get_conn_hostname()\fR returns the hostname of the connect BIO or +NULL if the BIO is initialized but no hostname is set. +This return value is an internal pointer which should not be modified. +.PP +\&\fBBIO_get_conn_port()\fR returns the port as a string. +This return value is an internal pointer which should not be modified. +.PP +\&\fBBIO_get_conn_address()\fR returns the address information as a BIO_ADDR. +This return value is an internal pointer which should not be modified. +.PP +\&\fBBIO_get_conn_ip_family()\fR returns the IP family of the connect BIO. +.PP +\&\fBBIO_set_nbio()\fR sets the non blocking I/O flag to \fBn\fR. If \fBn\fR is +zero then blocking I/O is set. If \fBn\fR is 1 then non blocking I/O +is set. Blocking I/O is the default. The call to \fBBIO_set_nbio()\fR +should be made before the connection is established because +non blocking I/O is set during the connect process. +.PP +\&\fBBIO_do_connect()\fR attempts to connect the supplied BIO. +This performs an SSL/TLS handshake as far as supported by the BIO. +For non\-SSL BIOs the connection is done typically at TCP level. +If domain name resolution yields multiple IP addresses all of them are tried +after \fBconnect()\fR failures. +The function returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection could not be established. +The call \fBBIO_should_retry()\fR should be used for non blocking connect BIOs +to determine if the call should be retried. +If a connection has already been established this call has no effect. +.PP +\&\fBBIO_set_sock_type()\fR can be used to set a socket type value as would be passed in +a call to \fBsocket\fR\|(2). The only currently supported values are \fBSOCK_STREAM\fR (the +default) and \fBSOCK_DGRAM\fR. If \fBSOCK_DGRAM\fR is configured, the connection +created is a UDP datagram socket handled via \fBBIO_s_datagram\fR\|(3). +I/O calls such as \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3) are forwarded transparently +to an internal \fBBIO_s_datagram\fR\|(3) instance. The created \fBBIO_s_datagram\fR\|(3) +instance can be retrieved using \fBBIO_get0_dgram_bio()\fR if desired, which writes +a pointer to the \fBBIO_s_datagram\fR\|(3) instance to \fI*dgram_bio\fR. The lifetime +of the internal \fBBIO_s_datagram\fR\|(3) is managed by \fBBIO_s_connect()\fR and does not +need to be freed by the caller. +.PP +\&\fBBIO_get_sock_type()\fR retrieves the value set using \fBBIO_set_sock_type()\fR. +.SH NOTES +.IX Header "NOTES" +If blocking I/O is set then a non positive return value from any +I/O call is caused by an error condition, although a zero return +will normally mean that the connection was closed. +.PP +If the port name is supplied as part of the hostname then this will +override any value set with \fBBIO_set_conn_port()\fR. This may be undesirable +if the application does not wish to allow connection to arbitrary +ports. This can be avoided by checking for the presence of the \*(Aq:\*(Aq +character in the passed hostname and either indicating an error or +truncating the string at that point. +.PP +The values returned by \fBBIO_get_conn_hostname()\fR, \fBBIO_get_conn_address()\fR, +and \fBBIO_get_conn_port()\fR are updated when a connection attempt is made. +Before any connection attempt the values returned are those set by the +application itself. +.PP +Applications do not have to call \fBBIO_do_connect()\fR but may wish to do +so to separate the connection process from other I/O processing. +.PP +If non blocking I/O is set then retries will be requested as appropriate. +.PP +It addition to \fBBIO_should_read()\fR and \fBBIO_should_write()\fR it is also +possible for \fBBIO_should_io_special()\fR to be true during the initial +connection process with the reason BIO_RR_CONNECT. If this is returned +then this is an indication that a connection attempt would block, +the application should then take appropriate action to wait until +the underlying socket has connected and retry the call. +.PP +\&\fBBIO_set_conn_hostname()\fR, \fBBIO_set_conn_port()\fR, \fBBIO_get_conn_hostname()\fR, +\&\fBBIO_set_conn_address()\fR, \fBBIO_get_conn_port()\fR, \fBBIO_get_conn_address()\fR, +\&\fBBIO_set_conn_ip_family()\fR, \fBBIO_get_conn_ip_family()\fR, +\&\fBBIO_set_nbio()\fR, and \fBBIO_do_connect()\fR are macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_connect()\fR returns the connect BIO method. +.PP +\&\fBBIO_set_conn_address()\fR, \fBBIO_set_conn_port()\fR, and \fBBIO_set_conn_ip_family()\fR +return 1 or <=0 if an error occurs. +.PP +\&\fBBIO_set_conn_hostname()\fR returns 1 on success and <=0 on failure. +.PP +\&\fBBIO_get_conn_address()\fR returns the address information or NULL if none +was set. +.PP +\&\fBBIO_get_conn_hostname()\fR returns the connected hostname or NULL if +none was set. +.PP +\&\fBBIO_get_conn_ip_family()\fR returns the address family or \-1 if none was set. +.PP +\&\fBBIO_get_conn_port()\fR returns a string representing the connected +port or NULL if not set. +.PP +\&\fBBIO_set_nbio()\fR returns 1 or <=0 if an error occurs. +.PP +\&\fBBIO_do_connect()\fR returns 1 if the connection was successfully +established and <=0 if the connection failed. +.PP +\&\fBBIO_set_sock_type()\fR returns 1 on success or 0 on failure. +.PP +\&\fBBIO_get_sock_type()\fR returns a socket type or 0 if the call is not supported. +.PP +\&\fBBIO_get0_dgram_bio()\fR returns 1 on success or 0 on failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +This is example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. +.PP +.Vb 3 +\& BIO *cbio, *out; +\& int len; +\& char tmpbuf[1024]; +\& +\& cbio = BIO_new_connect("localhost:http"); +\& out = BIO_new_fp(stdout, BIO_NOCLOSE); +\& if (BIO_do_connect(cbio) <= 0) { +\& fprintf(stderr, "Error connecting to server\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +\& BIO_puts(cbio, "GET / HTTP/1.0\en\en"); +\& for (;;) { +\& len = BIO_read(cbio, tmpbuf, 1024); +\& if (len <= 0) +\& break; +\& BIO_write(out, tmpbuf, len); +\& } +\& BIO_free(cbio); +\& BIO_free(out); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_ADDR\fR\|(3), \fBBIO_parse_hostserv\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_set_conn_int_port()\fR, \fBBIO_get_conn_int_port()\fR, \fBBIO_set_conn_ip()\fR, and \fBBIO_get_conn_ip()\fR +were removed in OpenSSL 1.1.0. +Use \fBBIO_set_conn_address()\fR and \fBBIO_get_conn_address()\fR instead. +.PP +Connect BIOs support \fBBIO_gets()\fR since OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_core.3 b/static/netbsd/man3/BIO_s_core.3 new file mode 100644 index 00000000..71119230 --- /dev/null +++ b/static/netbsd/man3/BIO_s_core.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: BIO_s_core.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_core 3" +.TH BIO_s_core 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_core, BIO_new_from_core_bio \- OSSL_CORE_BIO functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_core(void); +\& +\& BIO *BIO_new_from_core_bio(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_core()\fR returns the core BIO method function. +.PP +A core BIO is treated as source/sink BIO which communicates to some external +BIO. This is primarily useful to provider authors. A number of calls from +libcrypto into a provider supply an OSSL_CORE_BIO parameter. This represents +a BIO within libcrypto, but cannot be used directly by a provider. Instead it +should be wrapped using a \fBBIO_s_core()\fR. +.PP +Once a BIO is constructed based on \fBBIO_s_core()\fR, the associated OSSL_CORE_BIO +object should be set on it using \fBBIO_set_data\fR\|(3). Note that the BIO will only +operate correctly if it is associated with a library context constructed using +\&\fBOSSL_LIB_CTX_new_from_dispatch\fR\|(3). To associate the BIO with a library context +construct it using \fBBIO_new_ex\fR\|(3). +.PP +\&\fBBIO_new_from_core_bio()\fR is a convenience function that constructs a new BIO +based on \fBBIO_s_core()\fR and that is associated with the given library context. It +then also sets the OSSL_CORE_BIO object on the BIO using \fBBIO_set_data\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_core()\fR return a core BIO \fBBIO_METHOD\fR structure. +.PP +\&\fBBIO_new_from_core_bio()\fR returns a BIO structure on success or NULL on failure. +A failure will most commonly be because the library context was not constructed +using \fBOSSL_LIB_CTX_new_from_dispatch\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_s_core()\fR and \fBBIO_new_from_core_bio()\fR were added in OpenSSL 3.0. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create a core BIO and write some data to it: +.PP +.Vb 2 +\& int some_function(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio) { +\& BIO *cbio = BIO_new_from_core_bio(libctx, corebio); +\& +\& if (cbio == NULL) +\& return 0; +\& +\& BIO_puts(cbio, "Hello World\en"); +\& +\& BIO_free(cbio); +\& return 1; +\& } +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_datagram.3 b/static/netbsd/man3/BIO_s_datagram.3 new file mode 100644 index 00000000..7560b53d --- /dev/null +++ b/static/netbsd/man3/BIO_s_datagram.3 @@ -0,0 +1,294 @@ +.\" $NetBSD: BIO_s_datagram.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_datagram 3" +.TH BIO_s_datagram 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_datagram, BIO_new_dgram, +BIO_ctrl_dgram_connect, +BIO_ctrl_set_connected, +BIO_dgram_recv_timedout, +BIO_dgram_send_timedout, +BIO_dgram_get_peer, +BIO_dgram_set_peer, +BIO_dgram_detect_peer_addr, +BIO_dgram_get_mtu_overhead \- Network BIO with datagram semantics +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO_METHOD *BIO_s_datagram(void); +\& BIO *BIO_new_dgram(int fd, int close_flag); +\& +\& int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer); +\& int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer); +\& int BIO_dgram_recv_timedout(BIO *bio); +\& int BIO_dgram_send_timedout(BIO *bio); +\& int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer); +\& int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer); +\& int BIO_dgram_get_mtu_overhead(BIO *bio); +\& int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_datagram()\fR is a BIO implementation designed for use with network sockets +which provide datagram semantics, such as UDP sockets. It is suitable for use +with DTLSv1 or QUIC. +.PP +Because \fBBIO_s_datagram()\fR has datagram semantics, a single \fBBIO_write()\fR call sends +a single datagram and a single \fBBIO_read()\fR call receives a single datagram. If +the size of the buffer passed to \fBBIO_read()\fR is inadequate, the datagram is +silently truncated. +.PP +For a memory\-based BIO which provides datagram semantics identical to those of +\&\fBBIO_s_datagram()\fR, see \fBBIO_s_dgram_pair\fR\|(3). +.PP +This BIO supports the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) functions. +.PP +When using \fBBIO_s_datagram()\fR, it is important to note that: +.IP \(bu 4 +This BIO can be used with either a connected or unconnected network socket. A +connected socket is a network socket which has had \fBBIO_connect\fR\|(3) or a +similar OS\-specific function called on it. Such a socket can only receive +datagrams from the specified peer. Any other socket is an unconnected socket and +can receive datagrams from any host. +.IP \(bu 4 +Despite their naming, +neither \fBBIO_ctrl_dgram_connect()\fR nor \fBBIO_ctrl_set_connected()\fR cause a socket +to become connected. These controls are provided to indicate to the BIO how +the underlying socket is configured and how it is to be used; see below. +.IP \(bu 4 +Use of \fBBIO_s_datagram()\fR with an unconnected network socket is hazardous hecause +any successful call to \fBBIO_read()\fR results in the peer address used for any +subsequent call to \fBBIO_write()\fR being set to the source address of the datagram +received by that call to \fBBIO_read()\fR. Thus, unless the caller calls +\&\fBBIO_dgram_set_peer()\fR immediately prior to every call to \fBBIO_write()\fR, or never +calls \fBBIO_read()\fR, any host on the network may cause future datagrams written to +be redirected to that host. Therefore, it is recommended that users either use +\&\fBBIO_s_dgram()\fR only with a connected socket, or, if using \fBBIO_s_dgram()\fR with an +unconnected socket, to use the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) methods +only and forego use of \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3). An exception is where +\&\fBDTLSv1_listen\fR\|(3) must be used; see \fBDTLSv1_listen\fR\|(3) for further +discussion. +.IP \(bu 4 +Unlike \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3), the \fBBIO_sendmmsg\fR\|(3) and +\&\fBBIO_recvmmsg\fR\|(3) methods are stateless and do not cause the internal state of +the \fBBIO_s_datagram()\fR to change. +.PP +Various controls are available for configuring the \fBBIO_s_datagram()\fR using +\&\fBBIO_ctrl\fR\|(3): +.IP "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)" 4 +.IX Item "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)" +This is equivalent to calling \fBBIO_dgram_set_peer\fR\|(3). +.Sp +Despite its name, this function does not cause the underlying socket to become +connected. +.IP "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)" 4 +.IX Item "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)" +This informs the \fBBIO_s_datagram()\fR whether the underlying socket has been +connected, and therefore how the \fBBIO_s_datagram()\fR should attempt to use the +socket. +.Sp +If the \fIpeer\fR argument is non\-NULL, \fBBIO_s_datagram()\fR assumes that the +underlying socket has been connected and will attempt to use the socket using OS +APIs which do not specify peer addresses (for example, \fBsend\fR\|(3) and \fBrecv\fR\|(3) or +similar). The \fIpeer\fR argument should specify the peer address to which the socket +is connected. +.Sp +If the \fIpeer\fR argument is NULL, \fBBIO_s_datagram()\fR assumes that the underlying +socket is not connected and will attempt to use the socket using an OS APIs +which specify peer addresses (for example, \fBsendto\fR\|(3) and \fBrecvfrom\fR\|(3)). +.Sp +This control does not affect the operation of \fBBIO_sendmmsg\fR\|(3) or +\&\fBBIO_recvmmsg\fR\|(3). +.IP "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)" 4 +.IX Item "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)" +This outputs a \fBBIO_ADDR\fR which specifies one of the following values, +whichever happened most recently: +.RS 4 +.IP \(bu 4 +The peer address last passed to \fBBIO_dgram_set_peer()\fR, \fBBIO_ctrl_dgram_connect()\fR +or \fBBIO_ctrl_set_connected()\fR. +.IP \(bu 4 +The peer address of the datagram last received by a call to \fBBIO_read()\fR. +.RE +.RS 4 +.RE +.IP "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)" 4 +.IX Item "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)" +Sets the peer address to be used for subsequent writes to this BIO. +.Sp +Warning: When used with an unconnected network socket, the value set may be +modified by future calls to \fBBIO_read\fR\|(3), making use of \fBBIO_s_datagram()\fR +hazardous when used with unconnected network sockets; see above. +.Sp +This does not affect the operation of \fBBIO_sendmmsg\fR\|(3). +\&\fBBIO_recvmmsg\fR\|(3) does not affect the value set by \fBBIO_dgram_set_peer()\fR. +.IP "BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)" 4 +.IX Item "BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)" +This is similar to \fBBIO_dgram_get_peer()\fR except that if the peer address has not +been set on the BIO object, an OS call such as \fBgetpeername\fR\|(2) will be attempted +to try and autodetect the peer address to which the underlying socket is +connected. Other BIOs may also implement this control if they are capable of +sensing a peer address, without necessarily also implementing +\&\fBBIO_dgram_set_peer()\fR and \fBBIO_dgram_get_peer()\fR. +.IP "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)" 4 +.IX Item "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)" +Returns 1 if the last I/O operation performed on the BIO (for example, via a +call to \fBBIO_read\fR\|(3)) may have been caused by a receive timeout. +.IP "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)" 4 +.IX Item "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)" +Returns 1 if the last I/O operation performed on the BIO (for example, via a +call to \fBBIO_write\fR\|(3)) may have been caused by a send timeout. +.IP "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)" 4 +.IX Item "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)" +Returns a quantity in bytes which is a rough estimate of the number of bytes of +overhead which should typically be added to a datagram payload size in order to +estimate the final size of the Layer 3 (e.g. IP) packet which will contain the +datagram. In most cases, the maximum datagram payload size which can be +transmitted can be determined by determining the link MTU in bytes and +subtracting the value returned by this call. +.Sp +The value returned by this call depends on the network layer protocol being +used. +.Sp +The value returned is not fully reliable because datagram overheads can be +higher in atypical network configurations, for example where IPv6 extension +headers or IPv4 options are used. +.IP BIO_CTRL_DGRAM_SET_DONT_FRAG 4 +.IX Item "BIO_CTRL_DGRAM_SET_DONT_FRAG" +If \fInum\fR is nonzero, configures the underlying network socket to enable Don\*(Aqt +Fragment mode, in which datagrams will be set with the IP Don\*(Aqt Fragment (DF) +bit set. If \fInum\fR is zero, Don\*(Aqt Fragment mode is disabled. +.IP BIO_CTRL_DGRAM_QUERY_MTU 4 +.IX Item "BIO_CTRL_DGRAM_QUERY_MTU" +Queries the OS for its assessment of the Path MTU for the destination to which +the underlying network socket, and returns that Path MTU in bytes. This control +can only be used with a connected socket. +.Sp +This is not supported on all platforms and depends on OS support being +available. Returns 0 on failure. +.IP BIO_CTRL_DGRAM_MTU_DISCOVER 4 +.IX Item "BIO_CTRL_DGRAM_MTU_DISCOVER" +This control requests that Path MTU discovery be enabled on the underlying +network socket. +.IP BIO_CTRL_DGRAM_GET_FALLBACK_MTU 4 +.IX Item "BIO_CTRL_DGRAM_GET_FALLBACK_MTU" +Returns the estimated minimum size of datagram payload which should always be +supported on the BIO. This size is determined by the minimum MTU required to be +supported by the applicable underlying network layer. Use of datagrams of this +size may lead to suboptimal performance, but should be routable in all +circumstances. The value returned is the datagram payload size in bytes and does +not include the size of layer 3 or layer 4 protocol headers. +.IP BIO_CTRL_DGRAM_MTU_EXCEEDED 4 +.IX Item "BIO_CTRL_DGRAM_MTU_EXCEEDED" +Returns 1 if the last attempted write to the BIO failed due to the size of the +attempted write exceeding the applicable MTU. +.IP BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT 4 +.IX Item "BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT" +Accepts a pointer to a \fBstruct timeval\fR. If the time specified is zero, +disables receive timeouts. Otherwise, configures the specified time interval as +the receive timeout for the socket for the purposes of future \fBBIO_read\fR\|(3) +calls. +.IP BIO_CTRL_DGRAM_SET_PEEK_MODE 4 +.IX Item "BIO_CTRL_DGRAM_SET_PEEK_MODE" +If \fBnum\fR is nonzero, enables peek mode; otherwise, disables peek mode. Where +peek mode is enabled, calls to \fBBIO_read\fR\|(3) read datagrams from the underlying +network socket in peek mode, meaning that a future call to \fBBIO_read\fR\|(3) will +yield the same datagram until peek mode is disabled. +.Sp +\&\fBBIO_recvmmsg\fR\|(3) is not affected by this control. +.PP +\&\fBBIO_new_dgram()\fR is a helper function which instantiates a \fBBIO_s_datagram()\fR and +sets the BIO to use the socket given in \fIfd\fR by calling \fBBIO_set_fd()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_datagram()\fR returns a BIO method. +.PP +\&\fBBIO_new_dgram()\fR returns a BIO on success and NULL on failure. +.PP +\&\fBBIO_ctrl_dgram_connect()\fR, \fBBIO_ctrl_set_connected()\fR and \fBBIO_dgram_set_peer()\fR +return 1 on success and 0 on failure. +.PP +\&\fBBIO_dgram_get_peer()\fR and \fBBIO_dgram_detect_peer_addr()\fR return 0 on failure and +the number of bytes for the outputted address representation (a positive value) +on success. +.PP +\&\fBBIO_dgram_recv_timedout()\fR and \fBBIO_dgram_send_timedout()\fR return 0 or 1 depending +on the circumstance; see discussion above. +.PP +\&\fBBIO_dgram_get_mtu_overhead()\fR returns a value in bytes. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_sendmmsg\fR\|(3), \fBBIO_s_dgram_pair\fR\|(3), \fBDTLSv1_listen\fR\|(3), \fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_dgram_pair.3 b/static/netbsd/man3/BIO_s_dgram_pair.3 new file mode 100644 index 00000000..acf288f5 --- /dev/null +++ b/static/netbsd/man3/BIO_s_dgram_pair.3 @@ -0,0 +1,285 @@ +.\" $NetBSD: BIO_s_dgram_pair.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_dgram_pair 3" +.TH BIO_s_dgram_pair 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc, +BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps, +BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu, +BIO_dgram_set0_local_addr \- datagram pair BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_dgram_pair(void); +\& +\& int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1, +\& BIO **bio2, size_t writebuf2); +\& int BIO_dgram_set_no_trunc(BIO *bio, int enable); +\& int BIO_dgram_get_no_trunc(BIO *bio); +\& uint32_t BIO_dgram_get_effective_caps(BIO *bio); +\& uint32_t BIO_dgram_get_caps(BIO *bio); +\& int BIO_dgram_set_caps(BIO *bio, uint32_t caps); +\& int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu); +\& unsigned int BIO_dgram_get_mtu(BIO *bio); +\& int BIO_dgram_set0_local_addr(BIO *bio, BIO_ADDR *addr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_dgram_pair()\fR returns the method for a BIO datagram pair. A BIO datagram +pair is similar to a BIO pair (see \fBBIO_s_bio\fR\|(3)) but has datagram semantics. +Broadly, this means that the length of the buffer passed to a write call will +match that retrieved by a read call. If the buffer passed to a read call is too +short, the datagram is truncated or the read fails, depending on how the BIO is +configured. +.PP +The BIO datagram pair attaches certain metadata to each write, such as source +and destination addresses. This information may be retrieved on read. +.PP +A typical application of a BIO datagram pair is to allow an application to keep +all datagram network I/O requested by libssl under application control. +.PP +The BIO datagram pair is designed to support multithreaded use where certain +restrictions are observed; see THREADING. +.PP +The BIO datagram pair allows each half of a pair to signal to the other half +whether they support certain capabilities; see CAPABILITY INDICATION. +.PP +\&\fBBIO_new_bio_dgram_pair()\fR combines the calls to \fBBIO_new\fR\|(3), +\&\fBBIO_make_bio_pair\fR\|(3) and \fBBIO_set_write_buf_size\fR\|(3) to create a connected +pair of BIOs \fBbio1\fR, \fBbio2\fR with write buffer sizes \fBwritebuf1\fR and +\&\fBwritebuf2\fR. If either size is zero then the default size is used. +.PP +\&\fBBIO_make_bio_pair\fR\|(3) may be used to join two datagram pair BIOs into a pair. +The two BIOs must both use the method returned by \fBBIO_s_dgram_pair()\fR and neither +of the BIOs may currently be associated in a pair. +.PP +\&\fBBIO_destroy_bio_pair\fR\|(3) destroys the association between two connected BIOs. +Freeing either half of the pair will automatically destroy the association. +.PP +\&\fBBIO_reset\fR\|(3) clears any data in the write buffer of the given BIO. This means +that the opposite BIO in the pair will no longer have any data waiting to be +read. +.PP +The BIO maintains a fixed size internal write buffer. When the buffer is full, +further writes will fail until the buffer is drained via calls to +\&\fBBIO_read\fR\|(3). The size of the buffer can be changed using +\&\fBBIO_set_write_buf_size\fR\|(3) and queried using \fBBIO_get_write_buf_size\fR\|(3). +.PP +Note that the write buffer is partially consumed by metadata stored internally +which is attached to each datagram, such as source and destination addresses. +The size of this overhead is undefined and may change between releases. +.PP +The standard \fBBIO_ctrl_pending\fR\|(3) call has modified behaviour and returns the +size of the next datagram waiting to be read in bytes. An application can use +this function to ensure it provides an adequate buffer to a subsequent read +call. If no datagram is waiting to be read, zero is returned. +.PP +This BIO does not support sending or receiving zero\-length datagrams. Passing a +zero\-length buffer to BIO_write is treated as a no\-op. +.PP +\&\fBBIO_eof\fR\|(3) returns 1 only if the given BIO datagram pair BIO is not currently +connected to a peer BIO. +.PP +\&\fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_ctrl_get_write_guarantee\fR\|(3) return how +large a datagram the next call to \fBBIO_write\fR\|(3) can accept. If there is not +enough space in the write buffer to accept another datagram equal in size to the +configured MTU, zero is returned (see below). This is intended to avoid a +situation where an application attempts to read a datagram from a network +intending to write it to a BIO datagram pair, but where the received datagram +ends up being too large to write to the BIO datagram pair. +.PP +\&\fBBIO_dgram_set_no_trunc()\fR and \fBBIO_ctrl_get_no_trunc()\fR set and retrieve the +truncation mode for the given half of a BIO datagram pair. When no\-truncate mode +is enabled, \fBBIO_read()\fR will fail if the buffer provided is inadequate to hold +the next datagram to be read. If no\-truncate mode is disabled (the default), the +datagram will be silently truncated. This default behaviour maintains +compatibility with the semantics of the Berkeley sockets API. +.PP +\&\fBBIO_dgram_set_mtu()\fR and \fBBIO_dgram_get_mtu()\fR may be used to set an informational +MTU value on the BIO datagram pair. If \fBBIO_dgram_set_mtu()\fR is used on a BIO +which is currently part of a BIO datagram pair, the MTU value is set on both +halves of the pair. The value does not affect the operation of the BIO datagram +pair (except for \fBBIO_get_write_guarantee()\fR; see above) but may be used by other +code to determine a requested MTU. When a BIO datagram pair BIO is created, the +MTU is set to an unspecified but valid value. +.PP +\&\fBBIO_dgram_set0_local_addr()\fR can be used to set the local BIO_ADDR to be used +when sending a datagram via a BIO datagram pair. This becomes the peer address +when receiving on the other half of the pair. If the BIO is used in a call to +\&\fBBIO_sendmmsg\fR\|(3) and a local address is explicitly specified, then the +explicitly specified local address takes precedence. The reference to the +BIO_ADDR is passed to the BIO by this call and will be freed automatically when +the BIO is freed. +.PP +\&\fBBIO_flush\fR\|(3) is a no\-op. +.SH NOTES +.IX Header "NOTES" +The halves of a BIO datagram pair have independent lifetimes and must be +separately freed. +.SH THREADING +.IX Header "THREADING" +\&\fBBIO_recvmmsg\fR\|(3), \fBBIO_sendmmsg\fR\|(3), \fBBIO_read\fR\|(3), \fBBIO_write\fR\|(3), +\&\fBBIO_pending\fR\|(3), \fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_flush\fR\|(3) may be used +by multiple threads simultaneously on the same BIO datagram pair. Specific +\&\fBBIO_ctrl\fR\|(3) operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and +BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any +other \fBBIO_ctrl\fR\|(3) operation, on either half of a BIO datagram pair while any +other BIO call is also in progress to either half of the same BIO datagram pair +results in undefined behaviour. +.SH "CAPABILITY INDICATION" +.IX Header "CAPABILITY INDICATION" +The BIO datagram pair can be used to enqueue datagrams which have source and +destination addresses attached. It is important that the component consuming one +side of a BIO datagram pair understand whether the other side of the pair will +honour any source and destination addresses it attaches to each datagram. For +example, if datagrams are queued with destination addresses set but simply read +by simple calls to \fBBIO_read\fR\|(3), the destination addresses will be discarded. +.PP +Each half of a BIO datagram pair can have capability flags set on it which +indicate whether source and destination addresses will be honoured by the reader +and whether they will be provided by the writer. These capability flags should +be set via a call to \fBBIO_dgram_set_caps()\fR, and these capabilities will be +reflected in the value returned by \fBBIO_dgram_get_effective_caps()\fR on the +opposite BIO. If necessary, the capability value previously set can be retrieved +using \fBBIO_dgram_get_caps()\fR. Note that \fBBIO_dgram_set_caps()\fR on a given BIO +controls the capabilities advertised to the peer, and +\&\fBBIO_dgram_get_effective_caps()\fR on a given BIO determines the capabilities +advertised by the peer of that BIO. +.PP +The following capabilities are available: +.IP \fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR 4 +.IX Item "BIO_DGRAM_CAP_HANDLES_SRC_ADDR" +The user of the datagram pair BIO promises to honour source addresses provided +with datagrams written to the BIO pair. +.IP \fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR 4 +.IX Item "BIO_DGRAM_CAP_HANDLES_DST_ADDR" +The user of the datagram pair BIO promises to honour destination addresses provided +with datagrams written to the BIO pair. +.IP \fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR 4 +.IX Item "BIO_DGRAM_CAP_PROVIDES_SRC_ADDR" +The user of the datagram pair BIO advertises the fact that it will provide source +addressing information with future writes to the BIO pair, where available. +.IP \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR 4 +.IX Item "BIO_DGRAM_CAP_PROVIDES_DST_ADDR" +The user of the datagram pair BIO advertises the fact that it will provide +destination addressing information with future writes to the BIO pair, where +available. +.PP +If a caller attempts to specify a destination address (for example, using +\&\fBBIO_sendmmsg\fR\|(3)) and the peer has not advertised the +\&\fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR capability, the operation fails. Thus, +capability negotiation is mandatory. +.PP +If a caller attempts to specify a source address when writing, or requests a +destination address when receiving, and local address support has not been +enabled, the operation fails; see \fBBIO_dgram_set_local_addr_enable\fR\|(3). +.PP +If a caller attempts to enable local address support using +\&\fBBIO_dgram_set_local_addr_enable\fR\|(3) and \fBBIO_dgram_get_local_addr_cap\fR\|(3) +does not return 1 (meaning that the peer has not advertised both the +\&\fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR and the \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR +capability), the operation fails. +.PP +\&\fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR and \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR +indicate that the application using that half of a BIO datagram pair promises to +provide source and destination addresses respectively when writing datagrams to +that half of the BIO datagram pair. However, these capability flags do not +affect the behaviour of the BIO datagram pair. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_new_bio_dgram_pair()\fR returns 1 on success, with the new BIOs available in +\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with NULL pointers stored into the +locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information. +.PP +\&\fBBIO_dgram_set_no_trunc()\fR, \fBBIO_dgram_set_caps()\fR and \fBBIO_dgram_set_mtu()\fR return 1 +on success and 0 on failure. +.PP +\&\fBBIO_dgram_get_no_trunc()\fR returns 1 if no\-truncate mode is enabled on a BIO, or 0 +if no\-truncate mode is not enabled or not supported on a given BIO. +.PP +\&\fBBIO_dgram_get_effective_caps()\fR and \fBBIO_dgram_get_caps()\fR return zero if no +capabilities are supported. +.PP +\&\fBBIO_dgram_get_mtu()\fR returns the MTU value configured on the BIO, or zero if the +operation is not supported. +.PP +\&\fBBIO_dgram_set0_local_addr()\fR returns 1 on success and <= 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_s_bio\fR\|(3), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_s_dgram_pair()\fR, \fBBIO_new_bio_dgram_pair()\fR were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_fd.3 b/static/netbsd/man3/BIO_s_fd.3 new file mode 100644 index 00000000..8df85359 --- /dev/null +++ b/static/netbsd/man3/BIO_s_fd.3 @@ -0,0 +1,157 @@ +.\" $NetBSD: BIO_s_fd.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_fd 3" +.TH BIO_s_fd 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd \- file descriptor BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_fd(void); +\& +\& int BIO_set_fd(BIO *b, int fd, int c); +\& int BIO_get_fd(BIO *b, int *c); +\& +\& BIO *BIO_new_fd(int fd, int close_flag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_fd()\fR returns the file descriptor BIO method. This is a wrapper +round the platforms file descriptor routines such as \fBread()\fR and \fBwrite()\fR. +.PP +\&\fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read or write the underlying descriptor. +\&\fBBIO_puts()\fR is supported but \fBBIO_gets()\fR is not. +.PP +If the close flag is set then \fBclose()\fR is called on the underlying +file descriptor when the BIO is freed. +.PP +\&\fBBIO_reset()\fR attempts to change the file pointer to the start of file +such as by using \fBlseek(fd, 0, 0)\fR. +.PP +\&\fBBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file +such as by using \fBlseek(fd, ofs, 0)\fR. +.PP +\&\fBBIO_tell()\fR returns the current file position such as by calling +\&\fBlseek(fd, 0, 1)\fR. +.PP +\&\fBBIO_set_fd()\fR sets the file descriptor of BIO \fBb\fR to \fBfd\fR and the close +flag to \fBc\fR. +.PP +\&\fBBIO_get_fd()\fR places the file descriptor of BIO \fBb\fR in \fBc\fR if it is not NULL. +It also returns the file descriptor. +.PP +\&\fBBIO_new_fd()\fR returns a file descriptor BIO using \fBfd\fR and \fBclose_flag\fR. +.SH NOTES +.IX Header "NOTES" +The behaviour of \fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR depends on the behavior of the +platforms \fBread()\fR and \fBwrite()\fR calls on the descriptor. If the underlying +file descriptor is in a non blocking mode then the BIO will behave in the +manner described in the \fBBIO_read_ex\fR\|(3) and \fBBIO_should_retry\fR\|(3) +manual pages. +.PP +File descriptor BIOs should not be used for socket I/O. Use socket BIOs +instead. +.PP +\&\fBBIO_set_fd()\fR and \fBBIO_get_fd()\fR are implemented as macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_fd()\fR returns the file descriptor BIO method. +.PP +\&\fBBIO_set_fd()\fR returns 1 on success or <=0 for failure. +.PP +\&\fBBIO_get_fd()\fR returns the file descriptor or \-1 if the BIO has not +been initialized. It also returns zero and negative values if other error occurs. +.PP +\&\fBBIO_new_fd()\fR returns the newly allocated BIO or NULL is an error +occurred. +.SH EXAMPLES +.IX Header "EXAMPLES" +This is a file descriptor BIO version of "Hello World": +.PP +.Vb 1 +\& BIO *out; +\& +\& out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); +\& BIO_printf(out, "Hello World\en"); +\& BIO_free(out); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_seek\fR\|(3), \fBBIO_tell\fR\|(3), +\&\fBBIO_reset\fR\|(3), \fBBIO_read_ex\fR\|(3), +\&\fBBIO_write_ex\fR\|(3), \fBBIO_puts\fR\|(3), +\&\fBBIO_gets\fR\|(3), \fBBIO_printf\fR\|(3), +\&\fBBIO_set_close\fR\|(3), \fBBIO_get_close\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_file.3 b/static/netbsd/man3/BIO_s_file.3 new file mode 100644 index 00000000..06ba128a --- /dev/null +++ b/static/netbsd/man3/BIO_s_file.3 @@ -0,0 +1,232 @@ +.\" $NetBSD: BIO_s_file.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_file 3" +.TH BIO_s_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, +BIO_read_filename, BIO_write_filename, BIO_append_filename, +BIO_rw_filename \- FILE bio +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_file(void); +\& BIO *BIO_new_file(const char *filename, const char *mode); +\& BIO *BIO_new_fp(FILE *stream, int flags); +\& +\& BIO_set_fp(BIO *b, FILE *fp, int flags); +\& BIO_get_fp(BIO *b, FILE **fpp); +\& +\& int BIO_read_filename(BIO *b, char *name); +\& int BIO_write_filename(BIO *b, char *name); +\& int BIO_append_filename(BIO *b, char *name); +\& int BIO_rw_filename(BIO *b, char *name); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_file()\fR returns the BIO file method. As its name implies it +is a wrapper round the stdio FILE structure and it is a +source/sink BIO. +.PP +Calls to \fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read and write data to the +underlying stream. \fBBIO_gets()\fR and \fBBIO_puts()\fR are supported on file BIOs. +.PP +\&\fBBIO_flush()\fR on a file BIO calls the \fBfflush()\fR function on the wrapped +stream. +.PP +\&\fBBIO_reset()\fR attempts to change the file pointer to the start of file +using fseek(stream, 0, 0). +.PP +\&\fBBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file +using fseek(stream, ofs, 0). +.PP +\&\fBBIO_eof()\fR calls \fBfeof()\fR. +.PP +Setting the BIO_CLOSE flag calls \fBfclose()\fR on the stream when the BIO +is freed. +.PP +\&\fBBIO_new_file()\fR creates a new file BIO with mode \fBmode\fR the meaning +of \fBmode\fR is the same as the stdio function \fBfopen()\fR. The BIO_CLOSE +flag is set on the returned BIO. +.PP +\&\fBBIO_new_fp()\fR creates a file BIO wrapping \fBstream\fR. Flags can be: +BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying +stream to text mode, default is binary: this only has any effect under +Win32). +.PP +\&\fBBIO_set_fp()\fR sets the fp of a file BIO to \fBfp\fR. \fBflags\fR has the same +meaning as in \fBBIO_new_fp()\fR, it is a macro. +.PP +\&\fBBIO_get_fp()\fR retrieves the fp of a file BIO, it is a macro. +.PP +\&\fBBIO_seek()\fR is a macro that sets the position pointer to \fBoffset\fR bytes +from the start of file. +.PP +\&\fBBIO_tell()\fR returns the value of the position pointer. +.PP +\&\fBBIO_read_filename()\fR, \fBBIO_write_filename()\fR, \fBBIO_append_filename()\fR and +\&\fBBIO_rw_filename()\fR set the file BIO \fBb\fR to use file \fBname\fR for +reading, writing, append or read write respectively. +.SH NOTES +.IX Header "NOTES" +When wrapping stdout, stdin or stderr the underlying stream should not +normally be closed so the BIO_NOCLOSE flag should be set. +.PP +Because the file BIO calls the underlying stdio functions any quirks +in stdio behaviour will be mirrored by the corresponding BIO. +.PP +On Windows BIO_new_files reserves for the filename argument to be +UTF\-8 encoded. In other words if you have to make it work in multi\- +lingual environment, encode filenames in UTF\-8. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_file()\fR returns the file BIO method. +.PP +\&\fBBIO_new_file()\fR and \fBBIO_new_fp()\fR return a file BIO or NULL if an error +occurred. +.PP +\&\fBBIO_set_fp()\fR and \fBBIO_get_fp()\fR return 1 for success or <=0 for failure +(although the current implementation never return 0). +.PP +\&\fBBIO_seek()\fR returns 0 for success or negative values for failure. +.PP +\&\fBBIO_tell()\fR returns the current file position or negative values for failure. +.PP +\&\fBBIO_read_filename()\fR, \fBBIO_write_filename()\fR, \fBBIO_append_filename()\fR and +\&\fBBIO_rw_filename()\fR return 1 for success or <=0 for failure. An error is also +returned if the file does not exist. +.SH EXAMPLES +.IX Header "EXAMPLES" +File BIO "hello world": +.PP +.Vb 1 +\& BIO *bio_out; +\& +\& bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); +\& BIO_printf(bio_out, "Hello World\en"); +.Ve +.PP +Alternative technique: +.PP +.Vb 1 +\& BIO *bio_out; +\& +\& bio_out = BIO_new(BIO_s_file()); +\& if (bio_out == NULL) +\& /* Error */ +\& if (BIO_set_fp(bio_out, stdout, BIO_NOCLOSE) <= 0) +\& /* Error */ +\& BIO_printf(bio_out, "Hello World\en"); +.Ve +.PP +Write to a file: +.PP +.Vb 1 +\& BIO *out; +\& +\& out = BIO_new_file("filename.txt", "w"); +\& if (!out) +\& /* Error */ +\& BIO_printf(out, "Hello World\en"); +\& BIO_free(out); +.Ve +.PP +Alternative technique: +.PP +.Vb 1 +\& BIO *out; +\& +\& out = BIO_new(BIO_s_file()); +\& if (out == NULL) +\& /* Error */ +\& if (BIO_write_filename(out, "filename.txt") <= 0) +\& /* Error */ +\& BIO_printf(out, "Hello World\en"); +\& BIO_free(out); +.Ve +.SH BUGS +.IX Header "BUGS" +\&\fBBIO_reset()\fR and \fBBIO_seek()\fR are implemented using \fBfseek()\fR on the underlying +stream. The return value for \fBfseek()\fR is 0 for success or \-1 if an error +occurred this differs from other types of BIO which will typically return +1 for success and a non positive value if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_seek\fR\|(3), \fBBIO_tell\fR\|(3), +\&\fBBIO_reset\fR\|(3), \fBBIO_flush\fR\|(3), +\&\fBBIO_read_ex\fR\|(3), +\&\fBBIO_write_ex\fR\|(3), \fBBIO_puts\fR\|(3), +\&\fBBIO_gets\fR\|(3), \fBBIO_printf\fR\|(3), +\&\fBBIO_set_close\fR\|(3), \fBBIO_get_close\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_mem.3 b/static/netbsd/man3/BIO_s_mem.3 new file mode 100644 index 00000000..47150fb9 --- /dev/null +++ b/static/netbsd/man3/BIO_s_mem.3 @@ -0,0 +1,278 @@ +.\" $NetBSD: BIO_s_mem.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_mem 3" +.TH BIO_s_mem 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_secmem, BIO_s_dgram_mem, +BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, +BIO_get_mem_ptr, BIO_new_mem_buf \- memory BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_mem(void); +\& const BIO_METHOD *BIO_s_dgram_mem(void); +\& const BIO_METHOD *BIO_s_secmem(void); +\& +\& BIO_set_mem_eof_return(BIO *b, int v); +\& long BIO_get_mem_data(BIO *b, char **pp); +\& BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c); +\& BIO_get_mem_ptr(BIO *b, BUF_MEM **pp); +\& +\& BIO *BIO_new_mem_buf(const void *buf, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_mem()\fR returns the memory BIO method function. +.PP +A memory BIO is a source/sink BIO which uses memory for its I/O. Data +written to a memory BIO is stored in a BUF_MEM structure which is extended +as appropriate to accommodate the stored data. +.PP +\&\fBBIO_s_secmem()\fR is like \fBBIO_s_mem()\fR except that the secure heap is used +for buffer storage. +.PP +\&\fBBIO_s_dgram_mem()\fR is a memory BIO that respects datagram semantics. A single +call to \fBBIO_write\fR\|(3) will write a single datagram to the memory BIO. A +subsequent call to \fBBIO_read\fR\|(3) will read the data in that datagram. The +\&\fBBIO_read\fR\|(3) call will never return more data than was written in the original +\&\fBBIO_write\fR\|(3) call even if there were subsequent \fBBIO_write\fR\|(3) calls that +wrote more datagrams. Each successive call to \fBBIO_read\fR\|(3) will read the next +datagram. If a \fBBIO_read\fR\|(3) call supplies a read buffer that is smaller than +the size of the datagram, then the read buffer will be completely filled and the +remaining data from the datagram will be discarded. +.PP +It is not possible to write a zero length datagram. Calling \fBBIO_write\fR\|(3) in +this case will return 0 and no datagrams will be written. Calling \fBBIO_read\fR\|(3) +when there are no datagrams in the BIO to read will return a negative result and +the "retry" flags will be set (i.e. calling \fBBIO_should_retry\fR\|(3) will return +true). A datagram mem BIO will never return true from \fBBIO_eof\fR\|(3). +.PP +Any data written to a memory BIO can be recalled by reading from it. +Unless the memory BIO is read only any data read from it is deleted from +the BIO. +.PP +Memory BIOs except \fBBIO_s_dgram_mem()\fR support \fBBIO_gets()\fR and \fBBIO_puts()\fR. +.PP +\&\fBBIO_s_dgram_mem()\fR supports \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) calls +and calls related to \fBBIO_ADDR\fR and MTU handling similarly to the +\&\fBBIO_s_dgram_pair\fR\|(3). +.PP +If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying +BUF_MEM structure is also freed. +.PP +Calling \fBBIO_reset()\fR on a read write memory BIO clears any data in it if the +flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read +pointer to the state it was just after the last write was performed and the +data can be read again. On a read only BIO it similarly restores the BIO to +its original state and the read only data can be read again. +.PP +\&\fBBIO_eof()\fR is true if no data is in the BIO. +.PP +\&\fBBIO_ctrl_pending()\fR returns the number of bytes currently stored. +.PP +\&\fBBIO_set_mem_eof_return()\fR sets the behaviour of memory BIO \fBb\fR when it is +empty. If the \fBv\fR is zero then an empty memory BIO will return EOF (that is +it will return zero and BIO_should_retry(b) will be false. If \fBv\fR is non +zero then it will return \fBv\fR when it is empty and it will set the read retry +flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal +positive return value \fBv\fR should be set to a negative value, typically \-1. +Calling this macro will fail for datagram mem BIOs. +.PP +\&\fBBIO_get_mem_data()\fR sets *\fBpp\fR to a pointer to the start of the memory BIOs data +and returns the total amount of data available. It is implemented as a macro. +Note the pointer returned by this call is informative, no transfer of ownership +of this memory is implied. See notes on \fBBIO_set_close()\fR. +.PP +\&\fBBIO_set_mem_buf()\fR sets the internal BUF_MEM structure to \fBbm\fR and sets the +close flag to \fBc\fR, that is \fBc\fR should be either BIO_CLOSE or BIO_NOCLOSE. +It is a macro. +.PP +\&\fBBIO_get_mem_ptr()\fR places the underlying BUF_MEM structure in *\fBpp\fR. It is +a macro. +.PP +\&\fBBIO_new_mem_buf()\fR creates a memory BIO using \fBlen\fR bytes of data at \fBbuf\fR, +if \fBlen\fR is \-1 then the \fBbuf\fR is assumed to be nul terminated and its +length is determined by \fBstrlen\fR. The BIO is set to a read only state and +as a result cannot be written to. This is useful when some data needs to be +made available from a static area of memory in the form of a BIO. The +supplied data is read directly from the supplied buffer: it is \fBnot\fR copied +first, so the supplied area of memory must be unchanged until the BIO is freed. +.PP +All of the five functions described above return an error with +\&\fBBIO_s_dgram_mem()\fR. +.SH NOTES +.IX Header "NOTES" +Writes to memory BIOs will always succeed if memory is available: that is +their size can grow indefinitely. An exception is \fBBIO_s_dgram_mem()\fR when +\&\fBBIO_set_write_buf_size\fR\|(3) is called on it. In such case the write buffer +size will be fixed and any writes that would overflow the buffer will return +an error. +.PP +Every write after partial read (not all data in the memory buffer was read) +to a read write memory BIO will have to move the unread data with an internal +copy operation, if a BIO contains a lot of data and it is read in small +chunks intertwined with writes the operation can be very slow. Adding +a buffering BIO to the chain can speed up the process. +.PP +Calling \fBBIO_set_mem_buf()\fR on a secmem or dgram BIO will give undefined results, +including perhaps a program crash. +.PP +Switching a memory BIO from read write to read only is not supported and +can give undefined results including a program crash. There are two notable +exceptions to the rule. The first one is to assign a static memory buffer +immediately after BIO creation and set the BIO as read only. +.PP +The other supported sequence is to start with a read write BIO then temporarily +switch it to read only and call \fBBIO_reset()\fR on the read only BIO immediately +before switching it back to read write. Before the BIO is freed it must be +switched back to the read write mode. +.PP +Calling \fBBIO_get_mem_ptr()\fR on read only BIO will return a BUF_MEM that +contains only the remaining data to be read. If the close status of the +BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer +in it must be set to NULL as the data pointer does not point to an +allocated memory. +.PP +Calling \fBBIO_reset()\fR on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST +flag set can have unexpected outcome when the reads and writes to the +BIO are intertwined. As documented above the BIO will be reset to the +state after the last completed write operation. The effects of reads +preceding that write operation cannot be undone. +.PP +Calling \fBBIO_get_mem_ptr()\fR prior to a \fBBIO_reset()\fR call with +BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation. +.PP +Calling \fBBIO_set_close()\fR with BIO_NOCLOSE orphans the BUF_MEM internal to the +BIO, _not_ its actual data buffer. See the examples section for the proper +method for claiming ownership of the data pointer for a deferred free operation. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_mem()\fR, \fBBIO_s_dgram_mem()\fR and \fBBIO_s_secmem()\fR return a valid memory +\&\fBBIO_METHOD\fR structure. +.PP +\&\fBBIO_set_mem_eof_return()\fR, \fBBIO_set_mem_buf()\fR and \fBBIO_get_mem_ptr()\fR +return 1 on success or a value which is less than or equal to 0 if an error occurred. +.PP +\&\fBBIO_get_mem_data()\fR returns the total number of bytes available on success, +0 if b is NULL, or a negative value in case of other errors. +.PP +\&\fBBIO_new_mem_buf()\fR returns a valid \fBBIO\fR structure on success or NULL on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create a memory BIO and write some data to it: +.PP +.Vb 1 +\& BIO *mem = BIO_new(BIO_s_mem()); +\& +\& BIO_puts(mem, "Hello World\en"); +.Ve +.PP +Create a read only memory BIO: +.PP +.Vb 2 +\& char data[] = "Hello World"; +\& BIO *mem = BIO_new_mem_buf(data, \-1); +.Ve +.PP +Extract the BUF_MEM structure from a memory BIO and then free up the BIO: +.PP +.Vb 1 +\& BUF_MEM *bptr; +\& +\& BIO_get_mem_ptr(mem, &bptr); +\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ +\& BIO_free(mem); +.Ve +.PP +Extract the BUF_MEM ptr, claim ownership of the internal data and free the BIO +and BUF_MEM structure: +.PP +.Vb 2 +\& BUF_MEM *bptr; +\& char *data; +\& +\& BIO_get_mem_data(bio, &data); +\& BIO_get_mem_ptr(bio, &bptr); +\& BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */ +\& BIO_free(bio); +\& bptr\->data = NULL; /* Tell BUF_MEM to orphan data */ +\& BUF_MEM_free(bptr); +\& ... +\& free(data); +.Ve +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_s_dgram_mem()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_null.3 b/static/netbsd/man3/BIO_s_null.3 new file mode 100644 index 00000000..0ccf083f --- /dev/null +++ b/static/netbsd/man3/BIO_s_null.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: BIO_s_null.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_null 3" +.TH BIO_s_null 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_null \- null data sink +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_null(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_null()\fR returns the null sink BIO method. Data written to +the null sink is discarded, reads return EOF. +.SH NOTES +.IX Header "NOTES" +A null sink BIO behaves in a similar manner to the Unix /dev/null +device. +.PP +A null bio can be placed on the end of a chain to discard any data +passed through it. +.PP +A null sink is useful if, for example, an application wishes to digest some +data by writing through a digest bio but not send the digested data anywhere. +Since a BIO chain must normally include a source/sink BIO this can be achieved +by adding a null sink BIO to the end of the chain +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_null()\fR returns the null sink BIO method. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_s_socket.3 b/static/netbsd/man3/BIO_s_socket.3 new file mode 100644 index 00000000..bee154aa --- /dev/null +++ b/static/netbsd/man3/BIO_s_socket.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: BIO_s_socket.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_s_socket 3" +.TH BIO_s_socket 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_s_socket, BIO_new_socket \- socket BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIO_METHOD *BIO_s_socket(void); +\& +\& BIO *BIO_new_socket(int sock, int close_flag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_s_socket()\fR returns the socket BIO method. This is a wrapper +round the platform\*(Aqs socket routines. +.PP +\&\fBBIO_read_ex()\fR and \fBBIO_write_ex()\fR read or write the underlying socket. +\&\fBBIO_puts()\fR is supported but \fBBIO_gets()\fR is not. +.PP +If the close flag is set then the socket is shut down and closed +when the BIO is freed. +.PP +\&\fBBIO_new_socket()\fR returns a socket BIO using \fBsock\fR and \fBclose_flag\fR. +.SH NOTES +.IX Header "NOTES" +Socket BIOs also support any relevant functionality of file descriptor +BIOs. +.PP +The reason for having separate file descriptor and socket BIOs is that on some +platforms sockets are not file descriptors and use distinct I/O routines, +Windows is one such platform. Any code mixing the two will not work on +all platforms. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_s_socket()\fR returns the socket BIO method. +.PP +\&\fBBIO_new_socket()\fR returns the newly allocated BIO or NULL is an error +occurred. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_sendmmsg.3 b/static/netbsd/man3/BIO_sendmmsg.3 new file mode 100644 index 00000000..27f3be4d --- /dev/null +++ b/static/netbsd/man3/BIO_sendmmsg.3 @@ -0,0 +1,277 @@ +.\" $NetBSD: BIO_sendmmsg.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_sendmmsg 3" +.TH BIO_sendmmsg 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable, +BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap, +BIO_err_is_non_fatal \- send and receive multiple datagrams in a single call +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct bio_msg_st { +\& void *data; +\& size_t data_len; +\& BIO_ADDR *peer, *local; +\& uint64_t flags; +\& } BIO_MSG; +\& +\& int BIO_sendmmsg(BIO *b, BIO_MSG *msg, +\& size_t stride, size_t num_msg, uint64_t flags, +\& size_t *msgs_processed); +\& int BIO_recvmmsg(BIO *b, BIO_MSG *msg, +\& size_t stride, size_t num_msg, uint64_t flags, +\& size_t *msgs_processed); +\& +\& int BIO_dgram_set_local_addr_enable(BIO *b, int enable); +\& int BIO_dgram_get_local_addr_enable(BIO *b, int *enable); +\& int BIO_dgram_get_local_addr_cap(BIO *b); +\& int BIO_err_is_non_fatal(unsigned int errcode); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR functions can be used to send and receive +multiple messages in a single call to a BIO. They are analogous to \fBsendmmsg\fR\|(2) +and \fBrecvmmsg\fR\|(2) on operating systems which provide those functions. +.PP +The \fBBIO_MSG\fR structure provides a subset of the functionality of the \fBstruct +msghdr\fR structure defined by POSIX. These functions accept an array of +\&\fBBIO_MSG\fR structures. On any particular invocation, these functions may process +all of the passed structures, some of them, or none of them. This is indicated +by the value stored in \fI*msgs_processed\fR, which expresses the number of +messages processed. +.PP +The caller should set the \fIdata\fR member of a \fBBIO_MSG\fR to a buffer containing +the data to send, or to be filled with a received message. \fIdata_len\fR should be +set to the size of the buffer in bytes. If the given \fBBIO_MSG\fR is processed (in +other words, if the integer returned by the function is greater than or equal to +that \fBBIO_MSG\fR\*(Aqs array index), \fIdata_len\fR will be modified to specify the +actual amount of data sent or received. +.PP +The \fIflags\fR field of a \fBBIO_MSG\fR provides input per\-message flags to the +invocation. If the invocation processes that \fBBIO_MSG\fR, the \fIflags\fR field is +written with output per\-message flags, or zero if no such flags are applicable. +.PP +Currently, no input or output per\-message flags are defined and this field +should be set to zero before calling \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR. +.PP +The \fIflags\fR argument to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR provides global +flags which affect the entire invocation. No global flags are currently +defined and this argument should be set to zero. +.PP +When these functions are used to send and receive datagrams, the \fIpeer\fR field +of a \fBBIO_MSG\fR allows the destination address of sent datagrams to be specified +on a per\-datagram basis, and the source address of received datagrams to be +determined. The \fIpeer\fR field should be set to point to a \fBBIO_ADDR\fR, which +will be read by \fBBIO_sendmmsg()\fR and used as the destination address for sent +datagrams, and written by \fBBIO_recvmmsg()\fR with the source address of received +datagrams. +.PP +Similarly, the \fIlocal\fR field of a \fBBIO_MSG\fR allows the source address of sent +datagrams to be specified on a per\-datagram basis, and the destination address +of received datagrams to be determined. Unlike \fIpeer\fR, support for \fIlocal\fR +must be explicitly enabled on a \fBBIO\fR before it can be used; see +\&\fBBIO_dgram_set_local_addr_enable()\fR. If \fIlocal\fR is non\-NULL in a \fBBIO_MSG\fR and +support for \fIlocal\fR has not been enabled, processing of that \fBBIO_MSG\fR fails. +.PP +\&\fIpeer\fR and \fIlocal\fR should be set to NULL if they are not required. Support for +\&\fIlocal\fR may not be available on all platforms; on these platforms, these +functions always fail if \fIlocal\fR is non\-NULL. +.PP +If \fIlocal\fR is specified and local address support is enabled, but the operating +system does not report a local address for a specific received message, the +\&\fBBIO_ADDR\fR it points to will be cleared (address family set to \f(CW\*(C`AF_UNSPEC\*(C'\fR). +This is known to happen on Windows when a packet is received which was sent by +the local system, regardless of whether the packet\*(Aqs destination address was the +loopback address or the IP address of a local non\-loopback interface. This is +also known to happen on macOS in some circumstances, such as for packets sent +before local address support was enabled for a receiving socket. These are +OS\-specific limitations. As such, users of this API using local address support +should expect to sometimes receive a cleared local \fBBIO_ADDR\fR instead of the +correct value. +.PP +The \fIstride\fR argument must be set to \f(CWsizeof(BIO_MSG)\fR. This argument +facilitates backwards compatibility if fields are added to \fBBIO_MSG\fR. Callers +must zero\-initialize \fBBIO_MSG\fR. +.PP +\&\fInum_msg\fR should be sent to the maximum number of messages to send or receive, +which is also the length of the array pointed to by \fImsg\fR. +.PP +\&\fImsgs_processed\fR must be non\-NULL and points to an integer written with the +number of messages successfully processed; see the RETURN VALUES section for +further discussion. +.PP +Unlike most BIO functions, these functions explicitly support multi\-threaded +use. Multiple concurrent writers and multiple concurrent readers of the same BIO +are permitted in any combination. As such, these functions do not clear, set, or +otherwise modify BIO retry flags. The return value must be used to determine +whether an operation should be retried; see below. +.PP +The support for concurrent use extends to \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR +only, and no other function may be called on a given BIO while any call to +\&\fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR is in progress, or vice versa. +.PP +\&\fBBIO_dgram_set_local_addr_enable()\fR and \fBBIO_dgram_get_local_addr_enable()\fR control +whether local address support is enabled. To enable local address support, call +\&\fBBIO_dgram_set_local_addr_enable()\fR with an argument of 1. The call will fail if +local address support is not available for the platform. +\&\fBBIO_dgram_get_local_addr_enable()\fR retrieves the value set by +\&\fBBIO_dgram_set_local_addr_enable()\fR. +.PP +\&\fBBIO_dgram_get_local_addr_cap()\fR determines if the \fBBIO\fR is capable of supporting +local addresses. +.PP +\&\fBBIO_err_is_non_fatal()\fR determines if a packed error code represents an error +which is transient in nature. +.SH NOTES +.IX Header "NOTES" +Some implementations of the \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR BIO methods might +always process at most one message at a time, for example when OS\-level +functionality to transmit or receive multiple messages at a time is not +available. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +On success, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 1 and write +the number of messages successfully processed (which need not be nonzero) to +\&\fImsgs_processed\fR. Where a positive value n is written to \fImsgs_processed\fR, all +entries in the \fBBIO_MSG\fR array from 0 through n\-1 inclusive have their +\&\fIdata_len\fR and \fIflags\fR fields updated with the results of the operation on +that message. If the call was to \fBBIO_recvmmsg()\fR and the \fIpeer\fR or \fIlocal\fR +fields of that message are non\-NULL, the \fBBIO_ADDR\fR structures they point to +are written with the relevant address. +.PP +On failure, the functions \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR return 0 and write +zero to \fImsgs_processed\fR. Thus \fImsgs_processed\fR is always written regardless +of the outcome of the function call. +.PP +If \fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR fail, they always raise an \fBERR_LIB_BIO\fR +error using \fBERR_raise\fR\|(3). Any error may be raised, but the following in +particular may be noted: +.IP \fBBIO_R_LOCAL_ADDR_NOT_AVAILABLE\fR 2 +.IX Item "BIO_R_LOCAL_ADDR_NOT_AVAILABLE" +The \fIlocal\fR field was set to a non\-NULL value, but local address support is not +available or not enabled on the BIO. +.IP \fBBIO_R_PEER_ADDR_NOT_AVAILABLE\fR 2 +.IX Item "BIO_R_PEER_ADDR_NOT_AVAILABLE" +The \fIpeer\fR field was set to a non\-NULL value, but peer address support is not +available on the BIO. +.IP \fBBIO_R_UNSUPPORTED_METHOD\fR 2 +.IX Item "BIO_R_UNSUPPORTED_METHOD" +The \fBBIO_sendmmsg()\fR or \fBBIO_recvmmsg()\fR method is not supported on the BIO. +.IP \fBBIO_R_NON_FATAL\fR 2 +.IX Item "BIO_R_NON_FATAL" +The call failed due to a transient, non\-fatal error (for example, because the +BIO is in nonblocking mode and the call would otherwise have blocked). +.Sp +Implementations of this interface which do not make system calls and thereby +pass through system error codes using \fBERR_LIB_SYS\fR (for example, memory\-based +implementations) should issue this reason code to indicate a transient failure. +However, users of this interface should not test for this reason code directly, +as there are multiple possible packed error codes representing a transient +failure; use \fBBIO_err_is_non_fatal()\fR instead (discussed below). +.IP "Socket errors" 2 +.IX Item "Socket errors" +OS\-level socket errors are reported using an error with library code +\&\fBERR_LIB_SYS\fR; for a packed error code \fBerrcode\fR where +\&\f(CW\*(C`ERR_SYSTEM_ERROR(errcode) == 1\*(C'\fR, the OS\-level socket error code can be +retrieved using \f(CWERR_GET_REASON(errcode)\fR. The packed error code can be +retrieved by calling \fBERR_peek_last_error\fR\|(3) after the call to \fBBIO_sendmmsg()\fR +or \fBBIO_recvmmsg()\fR returns 0. +.IP "Non\-fatal errors" 2 +.IX Item "Non-fatal errors" +Whether an error is transient can be determined by passing the packed error code +to \fBBIO_err_is_non_fatal()\fR. Callers should do this instead of testing the reason +code directly, as there are many possible error codes which can indicate a +transient error, many of which are system specific. +.PP +Third parties implementing custom BIOs supporting the \fBBIO_sendmmsg()\fR or +\&\fBBIO_recvmmsg()\fR methods should note that it is a required part of the API +contract that an error is always raised when either of these functions return 0. +.PP +\&\fBBIO_dgram_set_local_addr_enable()\fR returns 1 if local address support was +successfully enabled or disabled and 0 otherwise. +.PP +\&\fBBIO_dgram_get_local_addr_enable()\fR returns 1 if the local address support enable +flag was successfully retrieved. +.PP +\&\fBBIO_dgram_get_local_addr_cap()\fR returns 1 if the \fBBIO\fR can support local +addresses. +.PP +\&\fBBIO_err_is_non_fatal()\fR returns 1 if the passed packed error code represents an +error which is transient in nature. +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_set_callback.3 b/static/netbsd/man3/BIO_set_callback.3 new file mode 100644 index 00000000..2733334a --- /dev/null +++ b/static/netbsd/man3/BIO_set_callback.3 @@ -0,0 +1,380 @@ +.\" $NetBSD: BIO_set_callback.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_set_callback 3" +.TH BIO_set_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, +BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, +BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn +\&\- BIO callback functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, +\& size_t len, int argi, +\& long argl, int ret, size_t *processed); +\& +\& void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback); +\& BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b); +\& +\& void BIO_set_callback_arg(BIO *b, char *arg); +\& char *BIO_get_callback_arg(const BIO *b); +\& +\& long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len, +\& int argi, long argl, int ret, size_t *processed); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 6 +\& typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, +\& long argl, long ret); +\& void BIO_set_callback(BIO *b, BIO_callback_fn cb); +\& BIO_callback_fn BIO_get_callback(const BIO *b); +\& long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi, +\& long argl, long ret); +\& +\& typedef struct bio_mmsg_cb_args_st { +\& BIO_MSG *msg; +\& size_t stride, num_msg; +\& uint64_t flags; +\& size_t *msgs_processed; +\& } BIO_MMSG_CB_ARGS; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_set_callback_ex()\fR and \fBBIO_get_callback_ex()\fR set and retrieve the BIO +callback. The callback is called during most high\-level BIO operations. It can +be used for debugging purposes to trace operations on a BIO or to modify its +operation. +.PP +\&\fBBIO_set_callback()\fR and \fBBIO_get_callback()\fR set and retrieve the old format BIO +callback. New code should not use these functions, but they are retained for +backwards compatibility. Any callback set via \fBBIO_set_callback_ex()\fR will get +called in preference to any set by \fBBIO_set_callback()\fR. +.PP +\&\fBBIO_set_callback_arg()\fR and \fBBIO_get_callback_arg()\fR are macros which can be +used to set and retrieve an argument for use in the callback. +.PP +\&\fBBIO_debug_callback_ex()\fR is a standard debugging callback which prints +out information relating to each BIO operation. If the callback +argument is set it is interpreted as a BIO to send the information +to, otherwise stderr is used. The \fBBIO_debug_callback()\fR function is the +deprecated version of the same callback for use with the old callback +format \fBBIO_set_callback()\fR function. +.PP +BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn +is the type of the old format callback function. The meaning of each argument +is described below: +.IP \fBb\fR 4 +.IX Item "b" +The BIO the callback is attached to is passed in \fBb\fR. +.IP \fBoper\fR 4 +.IX Item "oper" +\&\fBoper\fR is set to the operation being performed. For some operations +the callback is called twice, once before and once after the actual +operation, the latter case has \fBoper\fR or\*(Aqed with BIO_CB_RETURN. +.IP \fBlen\fR 4 +.IX Item "len" +The length of the data requested to be read or written. This is only useful if +\&\fBoper\fR is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS. +.IP "\fBargp\fR \fBargi\fR \fBargl\fR" 4 +.IX Item "argp argi argl" +The meaning of the arguments \fBargp\fR, \fBargi\fR and \fBargl\fR depends on +the value of \fBoper\fR, that is the operation being performed. +.IP \fBprocessed\fR 4 +.IX Item "processed" +\&\fBprocessed\fR is a pointer to a location which will be updated with the amount of +data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, +BIO_CB_GETS and BIO_CB_PUTS. +.IP \fBret\fR 4 +.IX Item "ret" +\&\fBret\fR is the return value that would be returned to the +application if no callback were present. The actual value returned +is the return value of the callback itself. In the case of callbacks +called before the actual BIO operation 1 is placed in \fBret\fR, if +the return value is not positive it will be immediately returned to +the application and the BIO operation will not be performed. +.PP +The callback should normally simply return \fBret\fR when it has +finished processing, unless it specifically wishes to modify the +value returned to the application. +.SH "CALLBACK OPERATIONS" +.IX Header "CALLBACK OPERATIONS" +In the notes below, \fBcallback\fR defers to the actual callback +function that is called. +.IP \fBBIO_free(b)\fR 4 +.IX Item "BIO_free(b)" +.Vb 1 +\& callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) +.Ve +.Sp +is called before the free operation. +.IP "\fBBIO_read_ex(b, data, dlen, readbytes)\fR" 4 +.IX Item "BIO_read_ex(b, data, dlen, readbytes)" +.Vb 1 +\& callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_READ, data, dlen, 0L, 1L) +.Ve +.Sp +is called before the read and +.Sp +.Vb 2 +\& callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, +\& &readbytes) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue) +.Ve +.Sp +after. +.IP "\fBBIO_write(b, data, dlen, written)\fR" 4 +.IX Item "BIO_write(b, data, dlen, written)" +.Vb 1 +\& callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L) +.Ve +.Sp +is called before the write and +.Sp +.Vb 2 +\& callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, +\& &written) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue) +.Ve +.Sp +after. +.IP "\fBBIO_gets(b, buf, size)\fR" 4 +.IX Item "BIO_gets(b, buf, size)" +.Vb 1 +\& callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_GETS, buf, size, 0L, 1L) +.Ve +.Sp +is called before the operation and +.Sp +.Vb 2 +\& callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, +\& &readbytes) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue) +.Ve +.Sp +after. +.IP "\fBBIO_puts(b, buf)\fR" 4 +.IX Item "BIO_puts(b, buf)" +.Vb 1 +\& callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL); +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L) +.Ve +.Sp +is called before the operation and +.Sp +.Vb 1 +\& callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue) +.Ve +.Sp +after. +.IP "\fBBIO_ctrl(BIO *b, int cmd, long larg, void *parg)\fR" 4 +.IX Item "BIO_ctrl(BIO *b, int cmd, long larg, void *parg)" +.Vb 1 +\& callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) +.Ve +.Sp +is called before the call and +.Sp +.Vb 1 +\& callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) +.Ve +.Sp +after. +.Sp +Note: \fBcmd\fR == \fBBIO_CTRL_SET_CALLBACK\fR is special, because \fBparg\fR is not the +argument of type \fBBIO_info_cb\fR itself. In this case \fBparg\fR is a pointer to +the actual call parameter, see \fBBIO_callback_ctrl\fR. +.IP "\fBBIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)\fR" 4 +.IX Item "BIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)" +.Vb 1 +\& callback_ex(b, BIO_CB_SENDMMSG, args, 0, 0, 0, 1, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_SENDMMSG, args, 0, 0, 1) +.Ve +.Sp +is called before the call and +.Sp +.Vb 1 +\& callback_ex(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret, NULL) +.Ve +.Sp +or +.Sp +.Vb 1 +\& callback(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret) +.Ve +.Sp +after. +.Sp +\&\fBargs\fR is a pointer to a \fBBIO_MMSG_CB_ARGS\fR structure containing the arguments +passed to \fBBIO_sendmmsg()\fR. \fBret\fR is the return value of the \fBBIO_sendmmsg()\fR call. +The return value of \fBBIO_sendmmsg()\fR is altered to the value returned by the +\&\fBBIO_CB_SENDMMSG | BIO_CB_RETURN\fR call. +.IP "\fBBIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)\fR" 4 +.IX Item "BIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)" +See the documentation for \fBBIO_sendmmsg()\fR. \fBBIO_recvmmsg()\fR works identically +except that \fBBIO_CB_RECVMMSG\fR is used instead of \fBBIO_CB_SENDMMSG\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_get_callback_ex()\fR and \fBBIO_get_callback()\fR return the callback function +previously set by a call to \fBBIO_set_callback_ex()\fR and \fBBIO_set_callback()\fR +respectively. +.PP +\&\fBBIO_get_callback_arg()\fR returns a \fBchar\fR pointer to the value previously set +via a call to \fBBIO_set_callback_arg()\fR. +.PP +\&\fBBIO_debug_callback()\fR returns 1 or \fBret\fR if it\*(Aqs called after specific BIO +operations. +.SH EXAMPLES +.IX Header "EXAMPLES" +The \fBBIO_debug_callback_ex()\fR function is an example, its source is +in crypto/bio/bio_cb.c +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_debug_callback_ex()\fR function was added in OpenSSL 3.0. +.PP +\&\fBBIO_set_callback()\fR, \fBBIO_get_callback()\fR, and \fBBIO_debug_callback()\fR were +deprecated in OpenSSL 3.0. Use the non\-deprecated _ex functions instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_set_flags.3 b/static/netbsd/man3/BIO_set_flags.3 new file mode 100644 index 00000000..eb46d9c9 --- /dev/null +++ b/static/netbsd/man3/BIO_set_flags.3 @@ -0,0 +1,238 @@ +.\" $NetBSD: BIO_set_flags.3,v 1.2 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_set_flags 3" +.TH BIO_set_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_set_flags, BIO_clear_flags, BIO_test_flags, BIO_get_flags, +BIO_set_retry_read, BIO_set_retry_write, BIO_set_retry_special, +BIO_clear_retry_flags, BIO_get_retry_flags +\&\- manipulate and interpret BIO flags +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void BIO_set_flags(BIO *b, int flags); +\& void BIO_clear_flags(BIO *b, int flags); +\& int BIO_test_flags(const BIO *b, int flags); +\& int BIO_get_flags(const BIO *b); +\& +\& void BIO_set_retry_read(BIO *b); +\& void BIO_set_retry_write(BIO *b); +\& void BIO_set_retry_special(BIO *b); +\& void BIO_clear_retry_flags(BIO *b); +\& int BIO_get_retry_flags(BIO *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A \fBBIO\fR has an internal set of bit flags that describe its state. These +functions and macros are used primarily by \fBBIO\fR implementations and by code +that builds \fBBIO\fR chains to manipulate those flags. +.PP +\&\fBBIO_set_flags()\fR sets the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR. Any bits +already set in the \fBBIO\fR\*(Aqs flag word remain set. +.PP +\&\fBBIO_clear_flags()\fR clears the bits given in \fIflags\fR from the \fBBIO\fR \fIb\fR. Any +other bits in the flag word are left unchanged. +.PP +\&\fBBIO_test_flags()\fR tests the bits given in \fIflags\fR in the \fBBIO\fR \fIb\fR and +returns a nonzero value if any of them are currently set and zero +otherwise. +.PP +\&\fBBIO_get_flags()\fR returns the current flag word from the \fBBIO\fR \fIb\fR. This is +equivalent to testing for all bits and returning the result. +.PP +The following convenience macros are built on top of these primitives and are +used to maintain the retry state of a BIO: +.PP +\&\fBBIO_set_retry_read()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state +by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the +\&\fBBIO_FLAGS_READ\fR flag to indicate that the retry condition is +associated with a read operation. +.PP +\&\fBBIO_set_retry_write()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state +by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the +\&\fBBIO_FLAGS_WRITE\fR flag to indicate that the retry condition is +associated with a write operation. +.PP +\&\fBBIO_set_retry_special()\fR marks the \fBBIO\fR \fIb\fR as being in a retryable state +by setting the \fBBIO_FLAGS_SHOULD_RETRY\fR flag. In addition, it sets the +\&\fBBIO_FLAGS_IO_SPECIAL\fR flag to indicate that the retry condition is +associated with a read operation some "special" condition. +The precise meaning of this condition depends on the \fBBIO\fR type. +.PP +\&\fBBIO_clear_retry_flags()\fR clears all retry\-related bits from \fIb\fR, i.e. +\&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and +\&\fBBIO_FLAGS_SHOULD_RETRY\fR. +.PP +\&\fBBIO_get_retry_flags()\fR returns retry\-related bits that are +currently set in \fIb\fR. The result is a subset of +\&\fBBIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY\fR. +.PP +The retry bits are interpreted by the higher level macros +\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR, +\&\fBBIO_retry_type()\fR and \fBBIO_should_retry()\fR, as documented in +\&\fBBIO_should_retry\fR\|(3). Application code will typically use those macros +rather than manipulate the underlying flags directly. +.PP +The following flag bits are currently defined for use with \fBBIO_set_flags()\fR, +\&\fBBIO_clear_flags()\fR and \fBBIO_test_flags()\fR: +.IP \fBBIO_FLAGS_READ\fR 4 +.IX Item "BIO_FLAGS_READ" +The last I/O operation should be retried when the \fBBIO\fR becomes readable. +This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_read()\fR +after a failed read operation. +.IP \fBBIO_FLAGS_WRITE\fR 4 +.IX Item "BIO_FLAGS_WRITE" +The last I/O operation should be retried when the \fBBIO\fR becomes writable. +This flag is normally set by the \fBBIO\fR implementation via \fBBIO_set_retry_write()\fR +after a failed write operation. +.IP \fBBIO_FLAGS_IO_SPECIAL\fR 4 +.IX Item "BIO_FLAGS_IO_SPECIAL" +The last I/O operation should be retried when some "special" condition +becomes true. The precise meaning of this condition depends on the \fBBIO\fR +type and is usually obtained via \fBBIO_get_retry_BIO()\fR and +\&\fBBIO_get_retry_reason()\fR as described in \fBBIO_should_retry\fR\|(3). +This flag is normally set by the \fBBIO\fR implementation via +\&\fBBIO_set_retry_special()\fR. +.IP \fBBIO_FLAGS_RWS\fR 4 +.IX Item "BIO_FLAGS_RWS" +The bitwise OR of \fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR and +\&\fBBIO_FLAGS_IO_SPECIAL\fR. This mask is used when clearing or extracting +the retry\-direction bits. +.IP \fBBIO_FLAGS_SHOULD_RETRY\fR 4 +.IX Item "BIO_FLAGS_SHOULD_RETRY" +Set if the last I/O operation on the \fBBIO\fR should be retried at a later time. +If this bit is not set then the condition is treated as an error. +This flag is normally set by the \fBBIO\fR implementation. +.IP \fBBIO_FLAGS_BASE64_NO_NL\fR 4 +.IX Item "BIO_FLAGS_BASE64_NO_NL" +When set on a base64 filter \fBBIO\fR this flag disables the generation of +newline characters in the encoded output and causes newlines to be ignored +in the input. See also \fBBIO_f_base64\fR\|(3). +The flag has no effect on any other built\-in \fBBIO\fR types. +.IP \fBBIO_FLAGS_MEM_RDONLY\fR 4 +.IX Item "BIO_FLAGS_MEM_RDONLY" +When set on a memory \fBBIO\fR this flag indicates that the underlying buffer is +read only. Attempts to write to such a \fBBIO\fR will fail. +The flag has no effect on any other built\-in \fBBIO\fR types. +.IP \fBBIO_FLAGS_NONCLEAR_RST\fR 4 +.IX Item "BIO_FLAGS_NONCLEAR_RST" +On a memory \fBBIO\fR this flag modifies the behaviour of \fBBIO_reset()\fR. When it +is set, resetting the \fBBIO\fR does not clear the underlying buffer but only +resets the current read position. +The flag has no effect on any other built\-in \fBBIO\fR types. +.IP \fBBIO_FLAGS_IN_EOF\fR 4 +.IX Item "BIO_FLAGS_IN_EOF" +This flag may be used by a \fBBIO\fR implementation to indicate that the end +of the input stream has been reached. However, \fBBIO\fR types are not +required to use this flag to signal end\-of\-file conditions; they may rely +on other mechanisms such as system calls or by querying the next \fBBIO\fR in a +chain. Applications must therefore not test this flag directly to +determine whether EOF has been reached, and must use \fBBIO_eof()\fR instead. +.PP +A range of additional flag values is reserved for internal use by OpenSSL +to track kernel TLS (KTLS) state. This range and the corresponding flag +macros are not part of the public API and must not be used by applications. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_get_flags()\fR returns a bit mask of the flags currently set on the \fBBIO\fR. +.PP +\&\fBBIO_test_flags()\fR returns a bit mask consisting of those flags from the +argument that are currently set in the \fBBIO\fR. Consequently, it returns a +nonzero value if and only if at least one of the requested flags is set. +.PP +\&\fBBIO_get_retry_flags()\fR returns a bit mask consisting of those flags from +\&\fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, \fBBIO_FLAGS_IO_SPECIAL\fR, and +\&\fBBIO_FLAGS_SHOULD_RETRY\fR that are currently set in the \fIBIO\fR. +.SH NOTES +.IX Header "NOTES" +Ordinary application code will rarely need to call \fBBIO_set_flags()\fR, +\&\fBBIO_clear_flags()\fR or \fBBIO_test_flags()\fR directly. They are intended for \fBBIO\fR +implementations and for code that forwards retry state from one \fBBIO\fR in a +chain to another. +After a failed I/O operation, applications should normally use +\&\fBBIO_should_retry()\fR and related macros as described in +\&\fBBIO_should_retry\fR\|(3) instead of inspecting the flags directly. +.PP +These functions and macros are not thread\-safe. If a single \fBBIO\fR +is accessed from multiple threads, the caller must provide appropriate +external synchronisation. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_should_retry\fR\|(3), \fBBIO_f_base64\fR\|(3), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions and macros described here have been available in OpenSSL since +at least 1.1.0 (\fBBIO_FLAGS_IN_EOF\fR since 1.1.1). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_should_retry.3 b/static/netbsd/man3/BIO_should_retry.3 new file mode 100644 index 00000000..f2970cf4 --- /dev/null +++ b/static/netbsd/man3/BIO_should_retry.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: BIO_should_retry.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_should_retry 3" +.TH BIO_should_retry 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_should_read, BIO_should_write, +BIO_should_io_special, BIO_retry_type, BIO_should_retry, +BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason \- BIO retry +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BIO_should_read(BIO *b); +\& int BIO_should_write(BIO *b); +\& int BIO_should_io_special(iBIO *b); +\& int BIO_retry_type(BIO *b); +\& int BIO_should_retry(BIO *b); +\& +\& BIO *BIO_get_retry_BIO(BIO *bio, int *reason); +\& int BIO_get_retry_reason(BIO *bio); +\& void BIO_set_retry_reason(BIO *bio, int reason); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions determine why a BIO is not able to read or write data. +They will typically be called after a failed \fBBIO_read_ex()\fR or \fBBIO_write_ex()\fR +call. +.PP +\&\fBBIO_should_retry()\fR is true if the call that produced this condition +should then be retried at a later time. +.PP +If \fBBIO_should_retry()\fR is false then the cause is an error condition. +.PP +\&\fBBIO_should_read()\fR is true if the cause of the condition is that the BIO +has insufficient data to return. Check for readability and/or retry the +last operation. +.PP +\&\fBBIO_should_write()\fR is true if the cause of the condition is that the BIO +has pending data to write. Check for writability and/or retry the +last operation. +.PP +\&\fBBIO_should_io_special()\fR is true if some "special" condition, that is a +reason other than reading or writing is the cause of the condition. +.PP +\&\fBBIO_retry_type()\fR returns a mask of the cause of a retry condition +consisting of the values \fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR, +\&\fBBIO_FLAGS_IO_SPECIAL\fR though current BIO types will only set one of +these. +.PP +\&\fBBIO_get_retry_BIO()\fR determines the precise reason for the special +condition, it returns the BIO that caused this condition and if +\&\fBreason\fR is not NULL it contains the reason code. The meaning of +the reason code and the action that should be taken depends on +the type of BIO that resulted in this condition. +.PP +\&\fBBIO_get_retry_reason()\fR returns the reason for a special condition if +passed the relevant BIO, for example as returned by \fBBIO_get_retry_BIO()\fR. +.PP +\&\fBBIO_set_retry_reason()\fR sets the retry reason for a special condition for a given +BIO. This would usually only be called by BIO implementations. +.SH NOTES +.IX Header "NOTES" +\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR, +\&\fBBIO_retry_type()\fR, and \fBBIO_should_retry()\fR, are implemented as macros. +.PP +If \fBBIO_should_retry()\fR returns false then the precise "error condition" +depends on the BIO type that caused it and the return code of the BIO +operation. For example if a call to \fBBIO_read_ex()\fR on a socket BIO returns +0 and \fBBIO_should_retry()\fR is false then the cause will be that the +connection closed. A similar condition on a file BIO will mean that it +has reached EOF. Some BIO types may place additional information on +the error queue. For more details see the individual BIO type manual +pages. +.PP +If the underlying I/O structure is in a blocking mode almost all current +BIO types will not request a retry, because the underlying I/O +calls will not. If the application knows that the BIO type will never +signal a retry then it need not call \fBBIO_should_retry()\fR after a failed +BIO I/O call. This is typically done with file BIOs. +.PP +SSL BIOs are the only current exception to this rule: they can request a +retry even if the underlying I/O structure is blocking, if a handshake +occurs during a call to \fBBIO_read()\fR. An application can retry the failed +call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY +on the underlying SSL structure. +.PP +While an application may retry a failed non blocking call immediately +this is likely to be very inefficient because the call will fail +repeatedly until data can be processed or is available. An application +will normally wait until the necessary condition is satisfied. How +this is done depends on the underlying I/O structure. +.PP +For example if the cause is ultimately a socket and \fBBIO_should_read()\fR +is true then a call to \fBselect()\fR may be made to wait until data is +available and then retry the BIO operation. By combining the retry +conditions of several non blocking BIOs in a single \fBselect()\fR call +it is possible to service several BIOs in a single thread, though +the performance may be poor if SSL BIOs are present because long delays +can occur during the initial handshake process. +.PP +It is possible for a BIO to block indefinitely if the underlying I/O +structure cannot process or return any data. This depends on the behaviour of +the platforms I/O functions. This is often not desirable: one solution +is to use non blocking I/O and use a timeout on the \fBselect()\fR (or +equivalent) call. +.SH BUGS +.IX Header "BUGS" +The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: +that is they cannot retry after a partial read or write. This is usually +worked around by only passing the relevant data to ASN1 functions when +the entire structure can be read or written. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_should_read()\fR, \fBBIO_should_write()\fR, \fBBIO_should_io_special()\fR, and +\&\fBBIO_should_retry()\fR return either 1 or 0 based on the actual conditions +of the \fBBIO\fR. +.PP +\&\fBBIO_retry_type()\fR returns a flag combination presenting the cause of a retry +condition or false if there is no retry condition. +.PP +\&\fBBIO_get_retry_BIO()\fR returns a valid \fBBIO\fR structure. +.PP +\&\fBBIO_get_retry_reason()\fR returns the reason for a special condition. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBBIO_get_retry_reason()\fR and \fBBIO_set_retry_reason()\fR functions were added in +OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BIO_socket_wait.3 b/static/netbsd/man3/BIO_socket_wait.3 new file mode 100644 index 00000000..f553c879 --- /dev/null +++ b/static/netbsd/man3/BIO_socket_wait.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: BIO_socket_wait.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_socket_wait 3" +.TH BIO_socket_wait 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_socket_wait, +BIO_wait, +BIO_do_connect_retry +\&\- BIO connection utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #ifndef OPENSSL_NO_SOCK +\& int BIO_socket_wait(int fd, int for_read, time_t max_time); +\& #endif +\& int BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds); +\& int BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBIO_socket_wait()\fR waits on the socket \fBfd\fR for reading if \fBfor_read\fR is not 0, +else for writing, at most until \fBmax_time\fR. +It succeeds immediately if \fBmax_time\fR == 0 (which means no timeout given). +.PP +\&\fBBIO_wait()\fR waits at most until \fBmax_time\fR on the given (typically socket\-based) +\&\fBbio\fR, for reading if \fBbio\fR is supposed to read, else for writing. +It is used by \fBBIO_do_connect_retry()\fR and can be used together \fBBIO_read\fR\|(3). +It succeeds immediately if \fBmax_time\fR == 0 (which means no timeout given). +If sockets are not available it supports polling by succeeding after sleeping +at most the given \fBnap_milliseconds\fR in order to avoid a tight busy loop. +Via \fBnap_milliseconds\fR the caller determines the polling granularity. +.PP +\&\fBBIO_do_connect_retry()\fR connects via the given \fBbio\fR. +It retries \fBBIO_do_connect()\fR as far as needed to reach a definite outcome, +i.e., connection succeeded, timeout has been reached, or an error occurred. +For nonblocking and potentially even non\-socket BIOs it polls +every \fBnap_milliseconds\fR and sleeps in between using \fBBIO_wait()\fR. +If \fBnap_milliseconds\fR is < 0 then a default value of 100 ms is used. +If the \fBtimeout\fR parameter is > 0 this indicates the maximum number of seconds +to wait until the connection is established or a definite error occurred. +A value of 0 enables waiting indefinitely (i.e, no timeout), +while a value < 0 means that \fBBIO_do_connect()\fR is tried only once. +The function may, directly or indirectly, invoke \fBERR_clear_error()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_socket_wait()\fR, \fBBIO_wait()\fR, and \fBBIO_do_connect_retry()\fR +return \-1 on error, 0 on timeout, and 1 on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_do_connect\fR\|(3), \fBBIO_read\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBIO_socket_wait()\fR, \fBBIO_wait()\fR, and \fBBIO_do_connect_retry()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_BLINDING_new.3 b/static/netbsd/man3/BN_BLINDING_new.3 new file mode 100644 index 00000000..a318f4b5 --- /dev/null +++ b/static/netbsd/man3/BN_BLINDING_new.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: BN_BLINDING_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_BLINDING_new 3" +.TH BN_BLINDING_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, +BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, +BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, +BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, +BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, +\& BIGNUM *mod); +\& void BN_BLINDING_free(BN_BLINDING *b); +\& int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx); +\& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); +\& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); +\& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, +\& BN_CTX *ctx); +\& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b, +\& BN_CTX *ctx); +\& int BN_BLINDING_is_current_thread(BN_BLINDING *b); +\& void BN_BLINDING_set_current_thread(BN_BLINDING *b); +\& int BN_BLINDING_lock(BN_BLINDING *b); +\& int BN_BLINDING_unlock(BN_BLINDING *b); +\& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *b); +\& void BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags); +\& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, +\& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, +\& int (*bn_mod_exp)(BIGNUM *r, +\& const BIGNUM *a, +\& const BIGNUM *p, +\& const BIGNUM *m, +\& BN_CTX *ctx, +\& BN_MONT_CTX *m_ctx), +\& BN_MONT_CTX *m_ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_BLINDING_new()\fR allocates a new \fBBN_BLINDING\fR structure and copies +the \fBA\fR and \fBAi\fR values into the newly created \fBBN_BLINDING\fR object. +.PP +\&\fBBN_BLINDING_free()\fR frees the \fBBN_BLINDING\fR structure. +If \fBb\fR is NULL, nothing is done. +.PP +\&\fBBN_BLINDING_update()\fR updates the \fBBN_BLINDING\fR parameters by squaring +the \fBA\fR and \fBAi\fR or, after specific number of uses and if the +necessary parameters are set, by re\-creating the blinding parameters. +.PP +\&\fBBN_BLINDING_convert_ex()\fR multiplies \fBn\fR with the blinding factor \fBA\fR. +If \fBr\fR is not NULL a copy the inverse blinding factor \fBAi\fR will be +returned in \fBr\fR (this is useful if a \fBRSA\fR object is shared among +several threads). \fBBN_BLINDING_invert_ex()\fR multiplies \fBn\fR with the +inverse blinding factor \fBAi\fR. If \fBr\fR is not NULL it will be used as +the inverse blinding. +.PP +\&\fBBN_BLINDING_convert()\fR and \fBBN_BLINDING_invert()\fR are wrapper +functions for \fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR +with \fBr\fR set to NULL. +.PP +\&\fBBN_BLINDING_is_current_thread()\fR returns whether the \fBBN_BLINDING\fR +structure is owned by the current thread. This is to help users +provide proper locking if needed for multi\-threaded use. +.PP +\&\fBBN_BLINDING_set_current_thread()\fR sets the current thread as the +owner of the \fBBN_BLINDING\fR structure. +.PP +\&\fBBN_BLINDING_lock()\fR locks the \fBBN_BLINDING\fR structure. +.PP +\&\fBBN_BLINDING_unlock()\fR unlocks the \fBBN_BLINDING\fR structure. +.PP +\&\fBBN_BLINDING_get_flags()\fR returns the BN_BLINDING flags. Currently +there are two supported flags: \fBBN_BLINDING_NO_UPDATE\fR and +\&\fBBN_BLINDING_NO_RECREATE\fR. \fBBN_BLINDING_NO_UPDATE\fR inhibits the +automatic update of the \fBBN_BLINDING\fR parameters after each use +and \fBBN_BLINDING_NO_RECREATE\fR inhibits the automatic re\-creation +of the \fBBN_BLINDING\fR parameters after a fixed number of uses (currently +32). In newly allocated \fBBN_BLINDING\fR objects no flags are set. +\&\fBBN_BLINDING_set_flags()\fR sets the \fBBN_BLINDING\fR parameters flags. +.PP +\&\fBBN_BLINDING_create_param()\fR creates new \fBBN_BLINDING\fR parameters +using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and +\&\fBm_ctx\fR can be used to pass special functions for exponentiation +(normally \fBBN_mod_exp_mont()\fR and \fBBN_MONT_CTX\fR). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_BLINDING_new()\fR returns the newly allocated \fBBN_BLINDING\fR structure +or NULL in case of an error. +.PP +\&\fBBN_BLINDING_update()\fR, \fBBN_BLINDING_convert()\fR, \fBBN_BLINDING_invert()\fR, +\&\fBBN_BLINDING_convert_ex()\fR and \fBBN_BLINDING_invert_ex()\fR return 1 on +success and 0 if an error occurred. +.PP +\&\fBBN_BLINDING_is_current_thread()\fR returns 1 if the current thread owns +the \fBBN_BLINDING\fR object, 0 otherwise. +.PP +\&\fBBN_BLINDING_set_current_thread()\fR doesn\*(Aqt return anything. +.PP +\&\fBBN_BLINDING_lock()\fR, \fBBN_BLINDING_unlock()\fR return 1 if the operation +succeeded or 0 on error. +.PP +\&\fBBN_BLINDING_get_flags()\fR returns the currently set \fBBN_BLINDING\fR flags +(a \fBunsigned long\fR value). +.PP +\&\fBBN_BLINDING_create_param()\fR returns the newly created \fBBN_BLINDING\fR +parameters or NULL on error. +.SH HISTORY +.IX Header "HISTORY" +\&\fBBN_BLINDING_thread_id()\fR was first introduced in OpenSSL 1.0.0, and it +deprecates \fBBN_BLINDING_set_thread_id()\fR and \fBBN_BLINDING_get_thread_id()\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2005\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_CTX_new.3 b/static/netbsd/man3/BN_CTX_new.3 new file mode 100644 index 00000000..259894d7 --- /dev/null +++ b/static/netbsd/man3/BN_CTX_new.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: BN_CTX_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_CTX_new 3" +.TH BN_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_CTX_new_ex, BN_CTX_new, BN_CTX_secure_new_ex, BN_CTX_secure_new, BN_CTX_free +\&\- allocate and free BN_CTX structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BN_CTX *BN_CTX_new_ex(OSSL_LIB_CTX *ctx); +\& BN_CTX *BN_CTX_new(void); +\& +\& BN_CTX *BN_CTX_secure_new_ex(OSSL_LIB_CTX *ctx); +\& BN_CTX *BN_CTX_secure_new(void); +\& +\& void BN_CTX_free(BN_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A \fBBN_CTX\fR is a structure that holds \fBBIGNUM\fR temporary variables used by +library functions. Since dynamic memory allocation to create \fBBIGNUM\fRs +is rather expensive when used in conjunction with repeated subroutine +calls, the \fBBN_CTX\fR structure is used. +.PP +\&\fBBN_CTX_new_ex()\fR allocates and initializes a \fBBN_CTX\fR structure for the given +library context \fBctx\fR. The value may be NULL in which case the default +library context will be used. \fBBN_CTX_new()\fR is the same as \fBBN_CTX_new_ex()\fR except +that the default library context is always used. +.PP +\&\fBBN_CTX_secure_new_ex()\fR allocates and initializes a \fBBN_CTX\fR structure +but uses the secure heap (see \fBCRYPTO_secure_malloc\fR\|(3)) to hold the +\&\fBBIGNUM\fRs for the given library context \fBctx\fR. The value may be NULL in +which case the default library context will be used. \fBBN_CTX_secure_new()\fR is the +same as \fBBN_CTX_secure_new_ex()\fR except that the default library context is always +used. +.PP +\&\fBBN_CTX_free()\fR frees the components of the \fBBN_CTX\fR and the structure itself. +Since \fBBN_CTX_start()\fR is required in order to obtain \fBBIGNUM\fRs from the +\&\fBBN_CTX\fR, in most cases \fBBN_CTX_end()\fR must be called before the \fBBN_CTX\fR may +be freed by \fBBN_CTX_free()\fR. If \fBc\fR is NULL, nothing is done. +.PP +A given \fBBN_CTX\fR must only be used by a single thread of execution. No +locking is performed, and the internal pool allocator will not properly handle +multiple threads of execution. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_CTX_new()\fR and \fBBN_CTX_secure_new()\fR return a pointer to the \fBBN_CTX\fR. +If the allocation fails, +they return \fBNULL\fR and sets an error code that can be obtained by +\&\fBERR_get_error\fR\|(3). +.PP +\&\fBBN_CTX_free()\fR has no return values. +.SH "REMOVED FUNCTIONALITY" +.IX Header "REMOVED FUNCTIONALITY" +.Vb 1 +\& void BN_CTX_init(BN_CTX *c); +.Ve +.PP +\&\fBBN_CTX_init()\fR is no longer available as of OpenSSL 1.1.0. Applications should +replace use of BN_CTX_init with BN_CTX_new instead: +.PP +.Vb 6 +\& BN_CTX *ctx; +\& ctx = BN_CTX_new(); +\& if (!ctx) +\& /* error */ +\& ... +\& BN_CTX_free(ctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3), +\&\fBBN_CTX_start\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBN_CTX_init()\fR was removed in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_CTX_start.3 b/static/netbsd/man3/BN_CTX_start.3 new file mode 100644 index 00000000..6ea449eb --- /dev/null +++ b/static/netbsd/man3/BN_CTX_start.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: BN_CTX_start.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_CTX_start 3" +.TH BN_CTX_start 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_CTX_start, BN_CTX_get, BN_CTX_end \- use temporary BIGNUM variables +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void BN_CTX_start(BN_CTX *ctx); +\& +\& BIGNUM *BN_CTX_get(BN_CTX *ctx); +\& +\& void BN_CTX_end(BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are used to obtain temporary \fBBIGNUM\fR variables from +a \fBBN_CTX\fR (which can been created by using \fBBN_CTX_new\fR\|(3)) +in order to save the overhead of repeatedly creating and +freeing \fBBIGNUM\fRs in functions that are called from inside a loop. +.PP +A function must call \fBBN_CTX_start()\fR first. Then, \fBBN_CTX_get()\fR may be +called repeatedly to obtain temporary \fBBIGNUM\fRs. All \fBBN_CTX_get()\fR +calls must be made before calling any other functions that use the +\&\fBctx\fR as an argument. +.PP +Finally, \fBBN_CTX_end()\fR must be called before returning from the function. +If \fBctx\fR is NULL, nothing is done. +When \fBBN_CTX_end()\fR is called, the \fBBIGNUM\fR pointers obtained from +\&\fBBN_CTX_get()\fR become invalid. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_CTX_start()\fR and \fBBN_CTX_end()\fR return no values. +.PP +\&\fBBN_CTX_get()\fR returns a pointer to the \fBBIGNUM\fR, or \fBNULL\fR on error. +Once \fBBN_CTX_get()\fR has failed, the subsequent calls will return \fBNULL\fR +as well, so it is sufficient to check the return value of the last +\&\fBBN_CTX_get()\fR call. In case of an error, an error code is set, which +can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBN_CTX_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_add.3 b/static/netbsd/man3/BN_add.3 new file mode 100644 index 00000000..50480057 --- /dev/null +++ b/static/netbsd/man3/BN_add.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: BN_add.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_add 3" +.TH BN_add 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, +BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd \- +arithmetic operations on BIGNUMs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); +\& +\& int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); +\& +\& int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& +\& int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx); +\& +\& int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, +\& BN_CTX *ctx); +\& +\& int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& +\& int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& +\& int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& +\& int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& +\& int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& +\& int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& +\& BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); +\& +\& int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); +\& +\& int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx); +\& +\& int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_add()\fR adds \fIa\fR and \fIb\fR and places the result in \fIr\fR (\f(CW\*(C`r=a+b\*(C'\fR). +\&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR. +.PP +\&\fBBN_sub()\fR subtracts \fIb\fR from \fIa\fR and places the result in \fIr\fR (\f(CW\*(C`r=a\-b\*(C'\fR). +\&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR. +.PP +\&\fBBN_mul()\fR multiplies \fIa\fR and \fIb\fR and places the result in \fIr\fR (\f(CW\*(C`r=a*b\*(C'\fR). +\&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR. +For multiplication by powers of 2, use \fBBN_lshift\fR\|(3). +.PP +\&\fBBN_sqr()\fR takes the square of \fIa\fR and places the result in \fIr\fR +(\f(CW\*(C`r=a^2\*(C'\fR). \fIr\fR and \fIa\fR may be the same \fBBIGNUM\fR. +This function is faster than BN_mul(r,a,a). +.PP +\&\fBBN_div()\fR divides \fIa\fR by \fId\fR and places the result in \fIdv\fR and the +remainder in \fIrem\fR (\f(CW\*(C`dv=a/d, rem=a%d\*(C'\fR). Either of \fIdv\fR and \fIrem\fR may +be \fBNULL\fR, in which case the respective value is not returned. +The result is rounded towards zero; thus if \fIa\fR is negative, the +remainder will be zero or negative. +For division by powers of 2, use \fBBN_rshift\fR\|(3). +.PP +\&\fBBN_mod()\fR corresponds to \fBBN_div()\fR with \fIdv\fR set to \fBNULL\fR. +.PP +\&\fBBN_nnmod()\fR reduces \fIa\fR modulo \fIm\fR and places the nonnegative +remainder in \fIr\fR. +.PP +\&\fBBN_mod_add()\fR adds \fIa\fR to \fIb\fR modulo \fIm\fR and places the nonnegative +result in \fIr\fR. +.PP +\&\fBBN_mod_sub()\fR subtracts \fIb\fR from \fIa\fR modulo \fIm\fR and places the +nonnegative result in \fIr\fR. +.PP +\&\fBBN_mod_mul()\fR multiplies \fIa\fR by \fIb\fR and finds the nonnegative +remainder respective to modulus \fIm\fR (\f(CW\*(C`r=(a*b) mod m\*(C'\fR). \fIr\fR may be +the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR. For more efficient algorithms for +repeated computations using the same modulus, see +\&\fBBN_mod_mul_montgomery\fR\|(3) and +\&\fBBN_mod_mul_reciprocal\fR\|(3). +.PP +\&\fBBN_mod_sqr()\fR takes the square of \fIa\fR modulo \fBm\fR and places the +result in \fIr\fR. +.PP +\&\fBBN_mod_sqrt()\fR returns the modular square root of \fIa\fR such that +\&\f(CW\*(C`in^2 = a (mod p)\*(C'\fR. The modulus \fIp\fR must be a +prime, otherwise an error or an incorrect "result" will be returned. +The result is stored into \fIin\fR which can be NULL. The result will be +newly allocated in that case. +.PP +\&\fBBN_exp()\fR raises \fIa\fR to the \fIp\fR\-th power and places the result in \fIr\fR +(\f(CW\*(C`r=a^p\*(C'\fR). This function is faster than repeated applications of +\&\fBBN_mul()\fR. +.PP +\&\fBBN_mod_exp()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR (\f(CW\*(C`r=a^p % +m\*(C'\fR). This function uses less time and space than \fBBN_exp()\fR. Do not call this +function when \fBm\fR is even and any of the parameters have the +\&\fBBN_FLG_CONSTTIME\fR flag set. +.PP +\&\fBBN_gcd()\fR computes the greatest common divisor of \fIa\fR and \fIb\fR and +places the result in \fIr\fR. \fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or +\&\fIb\fR. +.PP +For all functions, \fIctx\fR is a previously allocated \fBBN_CTX\fR used for +temporary variables; see \fBBN_CTX_new\fR\|(3). +.PP +Unless noted otherwise, the result \fBBIGNUM\fR must be different from +the arguments. +.SH NOTES +.IX Header "NOTES" +For modular operations such as \fBBN_nnmod()\fR or \fBBN_mod_exp()\fR it is an error +to use the same \fBBIGNUM\fR object for the modulus as for the output. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBBN_mod_sqrt()\fR returns the result (possibly incorrect if \fIp\fR is +not a prime), or NULL. +.PP +For all remaining functions, 1 is returned for success, 0 on error. The return +value should always be checked (e.g., \f(CW\*(C`if (!BN_add(r,a,b)) goto err;\*(C'\fR). +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_CTX_new\fR\|(3), +\&\fBBN_add_word\fR\|(3), \fBBN_set_bit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_add_word.3 b/static/netbsd/man3/BN_add_word.3 new file mode 100644 index 00000000..ce3b2bfa --- /dev/null +++ b/static/netbsd/man3/BN_add_word.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: BN_add_word.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_add_word 3" +.TH BN_add_word 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word \- arithmetic +functions on BIGNUMs with integers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_add_word(BIGNUM *a, BN_ULONG w); +\& +\& int BN_sub_word(BIGNUM *a, BN_ULONG w); +\& +\& int BN_mul_word(BIGNUM *a, BN_ULONG w); +\& +\& BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); +\& +\& BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions perform arithmetic operations on BIGNUMs with unsigned +integers. They are much more efficient than the normal BIGNUM +arithmetic operations. +.PP +\&\fBBN_add_word()\fR adds \fBw\fR to \fBa\fR (\f(CW\*(C`a+=w\*(C'\fR). +.PP +\&\fBBN_sub_word()\fR subtracts \fBw\fR from \fBa\fR (\f(CW\*(C`a\-=w\*(C'\fR). +.PP +\&\fBBN_mul_word()\fR multiplies \fBa\fR and \fBw\fR (\f(CW\*(C`a*=w\*(C'\fR). +.PP +\&\fBBN_div_word()\fR divides \fBa\fR by \fBw\fR (\f(CW\*(C`a/=w\*(C'\fR) and returns the remainder. +.PP +\&\fBBN_mod_word()\fR returns the remainder of \fBa\fR divided by \fBw\fR (\f(CW\*(C`a%w\*(C'\fR). +.PP +For \fBBN_div_word()\fR and \fBBN_mod_word()\fR, \fBw\fR must not be 0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_add_word()\fR, \fBBN_sub_word()\fR and \fBBN_mul_word()\fR return 1 for success, 0 +on error. The error codes can be obtained by \fBERR_get_error\fR\|(3). +.PP +\&\fBBN_mod_word()\fR and \fBBN_div_word()\fR return \fBa\fR%\fBw\fR on success and +\&\fB(BN_ULONG)\-1\fR if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_bn2bin.3 b/static/netbsd/man3/BN_bn2bin.3 new file mode 100644 index 00000000..322adaa1 --- /dev/null +++ b/static/netbsd/man3/BN_bn2bin.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: BN_bn2bin.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_bn2bin 3" +.TH BN_bn2bin 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_bn2binpad, BN_signed_bn2bin, BN_bn2bin, BN_bin2bn, BN_signed_bin2bn, +BN_bn2lebinpad, BN_signed_bn2lebin, BN_lebin2bn, BN_signed_lebin2bn, +BN_bn2nativepad, BN_signed_bn2native, BN_native2bn, BN_signed_native2bn, +BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, +BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn \- format conversions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_bn2bin(const BIGNUM *a, unsigned char *to); +\& int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen); +\& int BN_signed_bn2bin(const BIGNUM *a, unsigned char *to, int tolen); +\& BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); +\& BIGNUM *BN_signed_bin2bn(const unsigned char *s, int len, BIGNUM *ret); +\& +\& int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen); +\& int BN_signed_bn2lebin(const BIGNUM *a, unsigned char *to, int tolen); +\& BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret); +\& BIGNUM *BN_signed_lebin2bn(const unsigned char *s, int len, BIGNUM *ret); +\& +\& int BN_bn2nativepad(const BIGNUM *a, unsigned char *to, int tolen); +\& int BN_signed_bn2native(const BIGNUM *a, unsigned char *to, int tolen); +\& BIGNUM *BN_native2bn(const unsigned char *s, int len, BIGNUM *ret); +\& BIGNUM *BN_signed_native2bn(const unsigned char *s, int len, BIGNUM *ret); +\& +\& char *BN_bn2hex(const BIGNUM *a); +\& char *BN_bn2dec(const BIGNUM *a); +\& int BN_hex2bn(BIGNUM **a, const char *str); +\& int BN_dec2bn(BIGNUM **a, const char *str); +\& +\& int BN_print(BIO *fp, const BIGNUM *a); +\& int BN_print_fp(FILE *fp, const BIGNUM *a); +\& +\& int BN_bn2mpi(const BIGNUM *a, unsigned char *to); +\& BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_bn2bin()\fR converts the absolute value of \fBa\fR into big\-endian form +and stores it at \fBto\fR. \fBto\fR must point to BN_num_bytes(\fBa\fR) bytes of +memory. \fBa\fR and \fBto\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBBN_bn2binpad()\fR also converts the absolute value of \fBa\fR into big\-endian form +and stores it at \fBto\fR. \fBtolen\fR indicates the length of the output buffer +\&\fBto\fR. The result is padded with zeros if necessary. If \fBtolen\fR is less than +BN_num_bytes(\fBa\fR) an error is returned. +.PP +\&\fBBN_signed_bn2bin()\fR converts the value of \fBa\fR into big\-endian signed 2\*(Aqs +complements form and stores it at \fBto\fR. \fBtolen\fR indicates the length of +the output buffer \fBto\fR. The result is signed extended (padded with 0x00 +for positive numbers or with 0xff for negative numbers) if necessary. +If \fBtolen\fR is smaller than the necessary size (which may be +\&\f(CW\*(C`), an error is returned. +.PP +\&\fBBN_bin2bn()\fR converts the positive integer in big\-endian form of length +\&\fBlen\fR at \fBs\fR into a \fBBIGNUM\fR and places it in \fBret\fR. If \fBret\fR is +NULL, a new \fBBIGNUM\fR is created. \fBs\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBBN_signed_bin2bn()\fR converts the integer in big\-endian signed 2\*(Aqs complement +form of length \fBlen\fR at \fBs\fR into a \fBBIGNUM\fR and places it in \fBret\fR. If +\&\fBret\fR is NULL, a new \fBBIGNUM\fR is created. +.PP +\&\fBBN_bn2lebinpad()\fR, \fBBN_signed_bn2lebin()\fR and \fBBN_lebin2bn()\fR are identical to +\&\fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR and \fBBN_bin2bn()\fR except the buffer is in +little\-endian format. +.PP +\&\fBBN_bn2nativepad()\fR, \fBBN_signed_bn2native()\fR and \fBBN_native2bn()\fR are identical +to \fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR and \fBBN_bin2bn()\fR except the buffer is +in native format, i.e. most significant byte first on big\-endian platforms, +and least significant byte first on little\-endian platforms. +.PP +\&\fBBN_bn2hex()\fR and \fBBN_bn2dec()\fR return printable strings containing the +hexadecimal and decimal encoding of \fBa\fR respectively. For negative +numbers, the string is prefaced with a leading \*(Aq\-\*(Aq. The string must be +freed later using \fBOPENSSL_free()\fR. +.PP +\&\fBBN_hex2bn()\fR takes as many characters as possible from the string \fBstr\fR, +including the leading character \*(Aq\-\*(Aq which means negative, to form a valid +hexadecimal number representation and converts them to a \fBBIGNUM\fR and +stores it in **\fBa\fR. If *\fBa\fR is NULL, a new \fBBIGNUM\fR is created. If +\&\fBa\fR is NULL, it only computes the length of valid representation. +A "negative zero" is converted to zero. +\&\fBBN_dec2bn()\fR is the same using the decimal system. +.PP +\&\fBBN_print()\fR and \fBBN_print_fp()\fR write the hexadecimal encoding of \fBa\fR, +with a leading \*(Aq\-\*(Aq for negative numbers, to the \fBBIO\fR or \fBFILE\fR +\&\fBfp\fR. +.PP +\&\fBBN_bn2mpi()\fR and \fBBN_mpi2bn()\fR convert \fBBIGNUM\fRs from and to a format +that consists of the number\*(Aqs length in bytes represented as a 4\-byte +big\-endian number, and the number itself in big\-endian format, where +the most significant bit signals a negative number (the representation +of numbers with the MSB set is prefixed with null byte). +.PP +\&\fBBN_bn2mpi()\fR stores the representation of \fBa\fR at \fBto\fR, where \fBto\fR +must be large enough to hold the result. The size can be determined by +calling BN_bn2mpi(\fBa\fR, NULL). +.PP +\&\fBBN_mpi2bn()\fR converts the \fBlen\fR bytes long representation at \fBs\fR to +a \fBBIGNUM\fR and stores it at \fBret\fR, or in a newly allocated \fBBIGNUM\fR +if \fBret\fR is NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_bn2bin()\fR returns the length of the big\-endian number placed at \fBto\fR. +\&\fBBN_bin2bn()\fR returns the \fBBIGNUM\fR, NULL on error. +.PP +\&\fBBN_bn2binpad()\fR, \fBBN_signed_bn2bin()\fR, \fBBN_bn2lebinpad()\fR, \fBBN_signed_bn2lebin()\fR, +\&\fBBN_bn2nativepad()\fR, and_signed \fBBN_bn2native()\fR return the number of bytes +written or \-1 if the supplied buffer is too small. +.PP +\&\fBBN_bn2hex()\fR and \fBBN_bn2dec()\fR return a NUL\-terminated string, or NULL +on error. \fBBN_hex2bn()\fR and \fBBN_dec2bn()\fR return the number of characters +used in parsing, or 0 on error, in which +case no new \fBBIGNUM\fR will be created. +.PP +\&\fBBN_print_fp()\fR and \fBBN_print()\fR return 1 on success, 0 on write errors. +.PP +\&\fBBN_bn2mpi()\fR returns the length of the representation. \fBBN_mpi2bn()\fR +returns the \fBBIGNUM\fR, and NULL on error. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_zero\fR\|(3), +\&\fBASN1_INTEGER_to_BN\fR\|(3), +\&\fBBN_num_bytes\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBBN_signed_bin2bn()\fR, \fBBN_signed_bn2bin()\fR, \fBBN_signed_lebin2bn()\fR, +\&\fBBN_signed_bn2lebin()\fR, \fBBN_signed_native2bn()\fR, \fBBN_signed_bn2native()\fR +were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_cmp.3 b/static/netbsd/man3/BN_cmp.3 new file mode 100644 index 00000000..0bb929f6 --- /dev/null +++ b/static/netbsd/man3/BN_cmp.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: BN_cmp.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_cmp 3" +.TH BN_cmp 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_abs_is_word, BN_is_odd, BN_are_coprime +\&\- BIGNUM comparison and test functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_cmp(const BIGNUM *a, const BIGNUM *b); +\& int BN_ucmp(const BIGNUM *a, const BIGNUM *b); +\& +\& int BN_is_zero(const BIGNUM *a); +\& int BN_is_one(const BIGNUM *a); +\& int BN_is_word(const BIGNUM *a, const BN_ULONG w); +\& int BN_abs_is_word(const BIGNUM *a, const BN_ULONG w); +\& int BN_is_odd(const BIGNUM *a); +\& +\& int BN_are_coprime(BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_cmp()\fR compares the numbers \fIa\fR and \fIb\fR. \fBBN_ucmp()\fR compares their +absolute values. +.PP +\&\fBBN_is_zero()\fR, \fBBN_is_one()\fR, \fBBN_is_word()\fR and \fBBN_abs_is_word()\fR test if +\&\fIa\fR equals 0, 1, \fIw\fR, or |\fIw\fR| respectively. +\&\fBBN_is_odd()\fR tests if \fIa\fR is odd. +.PP +\&\fBBN_are_coprime()\fR determines if \fBa\fR and \fBb\fR are coprime. +\&\fBctx\fR is used internally for storing temporary variables. +The values of \fBa\fR and \fBb\fR and \fBctx\fR must not be NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_cmp()\fR returns \-1 if \fIa\fR < \fIb\fR, 0 if \fIa\fR == \fIb\fR and 1 if +\&\fIa\fR > \fIb\fR. \fBBN_ucmp()\fR is the same using the absolute values +of \fIa\fR and \fIb\fR. +.PP +\&\fBBN_is_zero()\fR, \fBBN_is_one()\fR \fBBN_is_word()\fR, \fBBN_abs_is_word()\fR and +\&\fBBN_is_odd()\fR return 1 if the condition is true, 0 otherwise. +.PP +\&\fBBN_are_coprime()\fR returns 1 if the \fBBIGNUM\fR\*(Aqs are coprime, otherwise it +returns 0. +.SH HISTORY +.IX Header "HISTORY" +Prior to OpenSSL 1.1.0, \fBBN_is_zero()\fR, \fBBN_is_one()\fR, \fBBN_is_word()\fR, +\&\fBBN_abs_is_word()\fR and \fBBN_is_odd()\fR were macros. +.PP +The function \fBBN_are_coprime()\fR was added in OpenSSL 3.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_copy.3 b/static/netbsd/man3/BN_copy.3 new file mode 100644 index 00000000..539ffd2c --- /dev/null +++ b/static/netbsd/man3/BN_copy.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: BN_copy.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_copy 3" +.TH BN_copy 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_copy, BN_dup, BN_with_flags \- copy BIGNUMs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); +\& +\& BIGNUM *BN_dup(const BIGNUM *from); +\& +\& void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_copy()\fR copies \fBfrom\fR to \fBto\fR. \fBBN_dup()\fR creates a new \fBBIGNUM\fR +containing the value \fBfrom\fR. +.PP +BN_with_flags creates a \fBtemporary\fR shallow copy of \fBb\fR in \fBdest\fR. It places +significant restrictions on the copied data. Applications that do no adhere to +these restrictions may encounter unexpected side effects or crashes. For that +reason use of this function is discouraged. Any flags provided in \fBflags\fR will +be set in \fBdest\fR in addition to any flags already set in \fBb\fR. For example this +might commonly be used to create a temporary copy of a BIGNUM with the +\&\fBBN_FLG_CONSTTIME\fR flag set for constant time operations. The temporary copy in +\&\fBdest\fR will share some internal state with \fBb\fR. For this reason the following +restrictions apply to the use of \fBdest\fR: +.IP \(bu 2 +\&\fBdest\fR should be a newly allocated BIGNUM obtained via a call to \fBBN_new()\fR. It +should not have been used for other purposes or initialised in any way. +.IP \(bu 2 +\&\fBdest\fR must only be used in "read\-only" operations, i.e. typically those +functions where the relevant parameter is declared "const". +.IP \(bu 2 +\&\fBdest\fR must be used and freed before any further subsequent use of \fBb\fR +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_copy()\fR returns \fBto\fR on success, NULL on error. \fBBN_dup()\fR returns +the new \fBBIGNUM\fR, and NULL on error. The error codes can be obtained +by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_generate_prime.3 b/static/netbsd/man3/BN_generate_prime.3 new file mode 100644 index 00000000..9e59f9b7 --- /dev/null +++ b/static/netbsd/man3/BN_generate_prime.3 @@ -0,0 +1,309 @@ +.\" $NetBSD: BN_generate_prime.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_generate_prime 3" +.TH BN_generate_prime 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime, +BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, +BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime, +BN_is_prime, BN_is_prime_fasttest \- generate primes and test for primality +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe, +\& const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb, +\& BN_CTX *ctx); +\& +\& int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, +\& const BIGNUM *rem, BN_GENCB *cb); +\& +\& int BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb); +\& +\& int BN_GENCB_call(BN_GENCB *cb, int a, int b); +\& +\& BN_GENCB *BN_GENCB_new(void); +\& +\& void BN_GENCB_free(BN_GENCB *cb); +\& +\& void BN_GENCB_set_old(BN_GENCB *gencb, +\& void (*callback)(int, int, void *), void *cb_arg); +\& +\& void BN_GENCB_set(BN_GENCB *gencb, +\& int (*callback)(int, int, BN_GENCB *), void *cb_arg); +\& +\& void *BN_GENCB_get_arg(BN_GENCB *cb); +.Ve +.PP +The following functions have been deprecated since OpenSSL 0.9.8, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, +\& BIGNUM *rem, void (*callback)(int, int, void *), +\& void *cb_arg); +\& +\& int BN_is_prime(const BIGNUM *p, int nchecks, +\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); +\& +\& int BN_is_prime_fasttest(const BIGNUM *p, int nchecks, +\& void (*callback)(int, int, void *), BN_CTX *ctx, +\& void *cb_arg, int do_trial_division); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); +\& +\& int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, +\& int do_trial_division, BN_GENCB *cb); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_generate_prime_ex2()\fR generates a pseudo\-random prime number of +at least bit length \fBbits\fR using the BN_CTX provided in \fBctx\fR. The value of +\&\fBctx\fR must not be NULL. +.PP +The returned number is probably prime with a negligible error. +The maximum error rate is 2^\-128. +It\*(Aqs 2^\-287 for a 512 bit prime, 2^\-435 for a 1024 bit prime, +2^\-648 for a 2048 bit prime, and lower than 2^\-882 for primes larger +than 2048 bit. +.PP +If \fBadd\fR is \fBNULL\fR the returned prime number will have exact bit +length \fBbits\fR with the top most two bits set. +.PP +If \fBret\fR is not \fBNULL\fR, it will be used to store the number. +.PP +If \fBcb\fR is not \fBNULL\fR, it is used as follows: +.IP \(bu 2 +\&\fBBN_GENCB_call(cb, 0, i)\fR is called after generating the i\-th +potential prime number. +.IP \(bu 2 +While the number is being tested for primality, +\&\fBBN_GENCB_call(cb, 1, j)\fR is called as described below. +.IP \(bu 2 +When a prime has been found, \fBBN_GENCB_call(cb, 2, i)\fR is called. +.IP \(bu 2 +The callers of \fBBN_generate_prime_ex()\fR may call \fBBN_GENCB_call(cb, i, j)\fR with +other values as described in their respective man pages; see "SEE ALSO". +.PP +The prime may have to fulfill additional requirements for use in +Diffie\-Hellman key exchange: +.PP +If \fBadd\fR is not \fBNULL\fR, the prime will fulfill the condition p % \fBadd\fR +== \fBrem\fR (p % \fBadd\fR == 1 if \fBrem\fR == \fBNULL\fR) in order to suit a given +generator. +.PP +If \fBsafe\fR is true, it will be a safe prime (i.e. a prime p so +that (p\-1)/2 is also prime). If \fBsafe\fR is true, and \fBrem\fR == \fBNULL\fR +the condition will be p % \fBadd\fR == 3. +It is recommended that \fBadd\fR is a multiple of 4. +.PP +The random generator must be seeded prior to calling \fBBN_generate_prime_ex()\fR. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +The random number generator configured for the OSSL_LIB_CTX associated with +\&\fBctx\fR will be used. +.PP +\&\fBBN_generate_prime_ex()\fR is the same as \fBBN_generate_prime_ex2()\fR except that no +\&\fBctx\fR parameter is passed. +In this case the random number generator associated with the default OSSL_LIB_CTX +will be used. +.PP +\&\fBBN_check_prime()\fR, \fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR +and \fBBN_is_prime_fasttest()\fR test if the number \fBp\fR is prime. +The functions tests until one of the tests shows that \fBp\fR is composite, +or all the tests passed. +If \fBp\fR passes all these tests, it is considered a probable prime. +.PP +The test performed on \fBp\fR are trial division by a number of small primes +and rounds of the Miller\-Rabin probabilistic primality test. +.PP +The functions do at least 64 rounds of the Miller\-Rabin test giving a maximum +false positive rate of 2^\-128. +If the size of \fBp\fR is more than 2048 bits, they do at least 128 rounds +giving a maximum false positive rate of 2^\-256. +.PP +If \fBnchecks\fR is larger than the minimum above (64 or 128), \fBnchecks\fR +rounds of the Miller\-Rabin test will be done. +.PP +If \fBdo_trial_division\fR set to \fB0\fR, the trial division will be skipped. +\&\fBBN_is_prime_ex()\fR and \fBBN_is_prime()\fR always skip the trial division. +.PP +\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR +and \fBBN_is_prime_fasttest()\fR are deprecated. +.PP +\&\fBBN_is_prime_fasttest()\fR and \fBBN_is_prime()\fR behave just like +\&\fBBN_is_prime_fasttest_ex()\fR and \fBBN_is_prime_ex()\fR respectively, but with the old +style callback. +.PP +\&\fBctx\fR is a preallocated \fBBN_CTX\fR (to save the overhead of allocating and +freeing the structure in a loop), or \fBNULL\fR. +.PP +If the trial division is done, and no divisors are found and \fBcb\fR +is not \fBNULL\fR, \fBBN_GENCB_call(cb, 1, \-1)\fR is called. +.PP +After each round of the Miller\-Rabin probabilistic primality test, +if \fBcb\fR is not \fBNULL\fR, \fBBN_GENCB_call(cb, 1, j)\fR is called +with \fBj\fR the iteration (j = 0, 1, ...). +.PP +\&\fBBN_GENCB_call()\fR calls the callback function held in the \fBBN_GENCB\fR structure +and passes the ints \fBa\fR and \fBb\fR as arguments. There are two types of +\&\fBBN_GENCB\fR structure that are supported: "new" style and "old" style. New +programs should prefer the "new" style, whilst the "old" style is provided +for backwards compatibility purposes. +.PP +A \fBBN_GENCB\fR structure should be created through a call to \fBBN_GENCB_new()\fR, +and freed through a call to \fBBN_GENCB_free()\fR. If the argument is NULL, +nothing is done. +.PP +For "new" style callbacks a BN_GENCB structure should be initialised with a +call to \fBBN_GENCB_set()\fR, where \fBgencb\fR is a \fBBN_GENCB *\fR, \fBcallback\fR is of +type \fBint (*callback)(int, int, BN_GENCB *)\fR and \fBcb_arg\fR is a \fBvoid *\fR. +"Old" style callbacks are the same except they are initialised with a call +to \fBBN_GENCB_set_old()\fR and \fBcallback\fR is of type +\&\fBvoid (*callback)(int, int, void *)\fR. +.PP +A callback is invoked through a call to \fBBN_GENCB_call\fR. This will check +the type of the callback and will invoke \fBcallback(a, b, gencb)\fR for new +style callbacks or \fBcallback(a, b, cb_arg)\fR for old style. +.PP +It is possible to obtain the argument associated with a BN_GENCB structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. +.PP +\&\fBBN_generate_prime()\fR (deprecated) works in the same way as +\&\fBBN_generate_prime_ex()\fR but expects an old\-style callback function +directly in the \fBcallback\fR parameter, and an argument to pass to it in +the \fBcb_arg\fR. \fBBN_is_prime()\fR and \fBBN_is_prime_fasttest()\fR +can similarly be compared to \fBBN_is_prime_ex()\fR and +\&\fBBN_is_prime_fasttest_ex()\fR, respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_generate_prime_ex()\fR return 1 on success or 0 on error. +.PP +\&\fBBN_is_prime_ex()\fR, \fBBN_is_prime_fasttest_ex()\fR, \fBBN_is_prime()\fR, +\&\fBBN_is_prime_fasttest()\fR and BN_check_prime return 0 if the number is composite, +1 if it is prime with an error probability of less than 0.25^\fBnchecks\fR, and +\&\-1 on error. +.PP +\&\fBBN_generate_prime()\fR returns the prime number on success, \fBNULL\fR otherwise. +.PP +BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or \fBNULL\fR +otherwise. +.PP +BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB +structure. +.PP +Callback functions should return 1 on success or 0 on error. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "REMOVED FUNCTIONALITY" +.IX Header "REMOVED FUNCTIONALITY" +As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure +directly, as in: +.PP +.Vb 1 +\& BN_GENCB callback; +.Ve +.PP +Instead applications should create a BN_GENCB structure using BN_GENCB_new: +.PP +.Vb 6 +\& BN_GENCB *callback; +\& callback = BN_GENCB_new(); +\& if (!callback) +\& /* error */ +\& ... +\& BN_GENCB_free(callback); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_generate_parameters\fR\|(3), \fBDSA_generate_parameters\fR\|(3), +\&\fBRSA_generate_key\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBBN_is_prime_ex()\fR and \fBBN_is_prime_fasttest_ex()\fR functions were +deprecated in OpenSSL 3.0. +.PP +The \fBBN_GENCB_new()\fR, \fBBN_GENCB_free()\fR, +and \fBBN_GENCB_get_arg()\fR functions were added in OpenSSL 1.1.0. +.PP +\&\fBBN_check_prime()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_mod_exp_mont.3 b/static/netbsd/man3/BN_mod_exp_mont.3 new file mode 100644 index 00000000..5c28d362 --- /dev/null +++ b/static/netbsd/man3/BN_mod_exp_mont.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: BN_mod_exp_mont.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_mod_exp_mont 3" +.TH BN_mod_exp_mont 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_mod_exp_mont, BN_mod_exp_mont_consttime, BN_mod_exp_mont_consttime_x2 \- +Montgomery exponentiation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_mod_exp_mont(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont); +\& +\& int BN_mod_exp_mont_consttime(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx, +\& BN_MONT_CTX *in_mont); +\& +\& int BN_mod_exp_mont_consttime_x2(BIGNUM *rr1, const BIGNUM *a1, +\& const BIGNUM *p1, const BIGNUM *m1, +\& BN_MONT_CTX *in_mont1, BIGNUM *rr2, +\& const BIGNUM *a2, const BIGNUM *p2, +\& const BIGNUM *m2, BN_MONT_CTX *in_mont2, +\& BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_mod_exp_mont()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR (\f(CW\*(C`rr=a^p % m\*(C'\fR) +using Montgomery multiplication. \fIin_mont\fR is a Montgomery context and can be +NULL. In the case \fIin_mont\fR is NULL, it will be initialized within the +function, so you can save time on initialization if you provide it in advance. +.PP +\&\fBBN_mod_exp_mont_consttime()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR +(\f(CW\*(C`rr=a^p % m\*(C'\fR) using Montgomery multiplication. It is a variant of +\&\fBBN_mod_exp_mont\fR\|(3) that uses fixed windows and the special precomputation +memory layout to limit data\-dependency to a minimum to protect secret exponents. +It is called automatically when \fBBN_mod_exp_mont\fR\|(3) is called with parameters +\&\fIa\fR, \fIp\fR, \fIm\fR, any of which have \fBBN_FLG_CONSTTIME\fR flag. +.PP +\&\fBBN_mod_exp_mont_consttime_x2()\fR computes two independent exponentiations \fIa1\fR to +the \fIp1\fR\-th power modulo \fIm1\fR (\f(CW\*(C`rr1=a1^p1 % m1\*(C'\fR) and \fIa2\fR to the \fIp2\fR\-th +power modulo \fIm2\fR (\f(CW\*(C`rr2=a2^p2 % m2\*(C'\fR) using Montgomery multiplication. For some +fixed and equal modulus sizes \fIm1\fR and \fIm2\fR it uses optimizations that allow +to speedup two exponentiations. In all other cases the function reduces to two +calls of \fBBN_mod_exp_mont_consttime\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +For all functions 1 is returned for success, 0 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_mod_exp_mont\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_mod_inverse.3 b/static/netbsd/man3/BN_mod_inverse.3 new file mode 100644 index 00000000..42515116 --- /dev/null +++ b/static/netbsd/man3/BN_mod_inverse.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: BN_mod_inverse.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_mod_inverse 3" +.TH BN_mod_inverse 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_mod_inverse \- compute inverse modulo n +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, +\& BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_mod_inverse()\fR computes the inverse of \fBa\fR modulo \fBn\fR +places the result in \fBr\fR (\f(CW\*(C`(a*r)%n==1\*(C'\fR). If \fBr\fR is NULL, +a new \fBBIGNUM\fR is created. +.PP +\&\fBctx\fR is a previously allocated \fBBN_CTX\fR used for temporary +variables. \fBr\fR may be the same \fBBIGNUM\fR as \fBa\fR. +.SH NOTES +.IX Header "NOTES" +It is an error to use the same \fBBIGNUM\fR as \fBn\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_mod_inverse()\fR returns the \fBBIGNUM\fR containing the inverse, and +NULL on error. The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_mod_mul_montgomery.3 b/static/netbsd/man3/BN_mod_mul_montgomery.3 new file mode 100644 index 00000000..5b6dd86a --- /dev/null +++ b/static/netbsd/man3/BN_mod_mul_montgomery.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: BN_mod_mul_montgomery.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_mod_mul_montgomery 3" +.TH BN_mod_mul_montgomery 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_mod_mul_montgomery, BN_MONT_CTX_new, +BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, +BN_from_montgomery, BN_to_montgomery \- Montgomery multiplication +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BN_MONT_CTX *BN_MONT_CTX_new(void); +\& void BN_MONT_CTX_free(BN_MONT_CTX *mont); +\& +\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); +\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); +\& +\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, +\& BN_MONT_CTX *mont, BN_CTX *ctx); +\& +\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, +\& BN_CTX *ctx); +\& +\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, +\& BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions implement Montgomery multiplication. They are used +automatically when \fBBN_mod_exp\fR\|(3) is called with suitable input, +but they may be useful when several operations are to be performed +using the same modulus. +.PP +\&\fBBN_MONT_CTX_new()\fR allocates and initializes a \fBBN_MONT_CTX\fR structure. +.PP +\&\fBBN_MONT_CTX_set()\fR sets up the \fImont\fR structure from the modulus \fIm\fR +by precomputing its inverse and a value R. +.PP +\&\fBBN_MONT_CTX_copy()\fR copies the \fBBN_MONT_CTX\fR \fIfrom\fR to \fIto\fR. +.PP +\&\fBBN_MONT_CTX_free()\fR frees the components of the \fBBN_MONT_CTX\fR, and, if +it was created by \fBBN_MONT_CTX_new()\fR, also the structure itself. +If \fBmont\fR is NULL, nothing is done. +.PP +\&\fBBN_mod_mul_montgomery()\fR computes Mont(\fIa\fR,\fIb\fR):=\fIa\fR*\fIb\fR*R^\-1 and places +the result in \fIr\fR. +.PP +\&\fBBN_from_montgomery()\fR performs the Montgomery reduction \fIr\fR = \fIa\fR*R^\-1. +.PP +\&\fBBN_to_montgomery()\fR computes Mont(\fIa\fR,R^2), i.e. \fIa\fR*R. +Note that \fIa\fR must be nonnegative and smaller than the modulus. +.PP +For all functions, \fIctx\fR is a previously allocated \fBBN_CTX\fR used for +temporary variables. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_MONT_CTX_new()\fR returns the newly allocated \fBBN_MONT_CTX\fR, and NULL +on error. +.PP +\&\fBBN_MONT_CTX_free()\fR has no return value. +.PP +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH WARNINGS +.IX Header "WARNINGS" +The inputs must be reduced modulo \fBm\fR, otherwise the result will be +outside the expected range. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3), +\&\fBBN_CTX_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBN_MONT_CTX_init()\fR was removed in OpenSSL 1.1.0 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_mod_mul_reciprocal.3 b/static/netbsd/man3/BN_mod_mul_reciprocal.3 new file mode 100644 index 00000000..e893aff3 --- /dev/null +++ b/static/netbsd/man3/BN_mod_mul_reciprocal.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: BN_mod_mul_reciprocal.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_mod_mul_reciprocal 3" +.TH BN_mod_mul_reciprocal 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, +BN_RECP_CTX_free, BN_RECP_CTX_set \- modular multiplication using +reciprocal +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BN_RECP_CTX *BN_RECP_CTX_new(void); +\& void BN_RECP_CTX_free(BN_RECP_CTX *recp); +\& +\& int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); +\& +\& int BN_div_recp(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, BN_RECP_CTX *recp, +\& BN_CTX *ctx); +\& +\& int BN_mod_mul_reciprocal(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, +\& BN_RECP_CTX *recp, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_mod_mul_reciprocal()\fR can be used to perform an efficient +\&\fBBN_mod_mul\fR\|(3) operation when the operation will be performed +repeatedly with the same modulus. It computes \fBr\fR=(\fBa\fR*\fBb\fR)%\fBm\fR +using \fBrecp\fR=1/\fBm\fR, which is set as described below. \fBctx\fR is a +previously allocated \fBBN_CTX\fR used for temporary variables. +.PP +\&\fBBN_RECP_CTX_new()\fR allocates and initializes a \fBBN_RECP\fR structure. +.PP +\&\fBBN_RECP_CTX_free()\fR frees the components of the \fBBN_RECP\fR, and, if it +was created by \fBBN_RECP_CTX_new()\fR, also the structure itself. +If \fBrecp\fR is NULL, nothing is done. +.PP +\&\fBBN_RECP_CTX_set()\fR stores \fBm\fR in \fBrecp\fR and sets it up for computing +1/\fBm\fR and shifting it left by BN_num_bits(\fBm\fR)+1 to make it an +integer. The result and the number of bits it was shifted left will +later be stored in \fBrecp\fR. +.PP +\&\fBBN_div_recp()\fR divides \fBa\fR by \fBm\fR using \fBrecp\fR. It places the quotient +in \fBdv\fR and the remainder in \fBrem\fR. +.PP +The \fBBN_RECP_CTX\fR structure cannot be shared between threads. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_RECP_CTX_new()\fR returns the newly allocated \fBBN_RECP_CTX\fR, and NULL +on error. +.PP +\&\fBBN_RECP_CTX_free()\fR has no return value. +.PP +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBBN_add\fR\|(3), +\&\fBBN_CTX_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBN_RECP_CTX_init()\fR was removed in OpenSSL 1.1.0 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_new.3 b/static/netbsd/man3/BN_new.3 new file mode 100644 index 00000000..c9b36fac --- /dev/null +++ b/static/netbsd/man3/BN_new.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: BN_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_new 3" +.TH BN_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free \- allocate and free BIGNUMs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIGNUM *BN_new(void); +\& +\& BIGNUM *BN_secure_new(void); +\& +\& void BN_clear(BIGNUM *a); +\& +\& void BN_free(BIGNUM *a); +\& +\& void BN_clear_free(BIGNUM *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_new()\fR allocates and initializes a \fBBIGNUM\fR structure. +\&\fBBN_secure_new()\fR does the same except that the secure heap +\&\fBOPENSSL_secure_malloc\fR\|(3) is used to store the value. +.PP +\&\fBBN_clear()\fR is used to destroy sensitive data such as keys when they +are no longer needed. It erases the memory used by \fBa\fR and sets it +to the value 0. +If \fBa\fR is NULL, nothing is done. +.PP +\&\fBBN_free()\fR frees the components of the \fBBIGNUM\fR, and if it was created +by \fBBN_new()\fR, also the structure itself. \fBBN_clear_free()\fR additionally +overwrites the data before the memory is returned to the system. +If \fBa\fR is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_new()\fR and \fBBN_secure_new()\fR +return a pointer to the \fBBIGNUM\fR initialised to the value 0. +If the allocation fails, +they return \fBNULL\fR and set an error code that can be obtained +by \fBERR_get_error\fR\|(3). +.PP +\&\fBBN_clear()\fR, \fBBN_free()\fR and \fBBN_clear_free()\fR have no return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBOPENSSL_secure_malloc\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBBN_init()\fR was removed in OpenSSL 1.1.0; use \fBBN_new()\fR instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_num_bytes.3 b/static/netbsd/man3/BN_num_bytes.3 new file mode 100644 index 00000000..d5ebb34f --- /dev/null +++ b/static/netbsd/man3/BN_num_bytes.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: BN_num_bytes.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_num_bytes 3" +.TH BN_num_bytes 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_num_bits, BN_num_bytes, BN_num_bits_word \- get BIGNUM size +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_num_bytes(const BIGNUM *a); +\& +\& int BN_num_bits(const BIGNUM *a); +\& +\& int BN_num_bits_word(BN_ULONG w); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_num_bytes()\fR returns the size of a \fBBIGNUM\fR in bytes. +.PP +\&\fBBN_num_bits_word()\fR returns the number of significant bits in a word. +If we take 0x00000432 as an example, it returns 11, not 16, not 32. +Basically, except for a zero, it returns \fIfloor(log2(w))+1\fR. +.PP +\&\fBBN_num_bits()\fR returns the number of significant bits in a \fBBIGNUM\fR, +following the same principle as \fBBN_num_bits_word()\fR. +.PP +\&\fBBN_num_bytes()\fR is a macro. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The size. +.SH NOTES +.IX Header "NOTES" +Some have tried using \fBBN_num_bits()\fR on individual numbers in RSA keys, +DH keys and DSA keys, and found that they don\*(Aqt always come up with +the number of bits they expected (something like 512, 1024, 2048, +\&...). This is because generating a number with some specific number +of bits doesn\*(Aqt always set the highest bits, thereby making the number +of \fIsignificant\fR bits a little lower. If you want to know the "key +size" of such a key, either use functions like \fBRSA_size()\fR, \fBDH_size()\fR +and \fBDSA_size()\fR, or use \fBBN_num_bytes()\fR and multiply with 8 (although +there\*(Aqs no real guarantee that will match the "key size", just a lot +more probability). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_size\fR\|(3), \fBDSA_size\fR\|(3), +\&\fBRSA_size\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_rand.3 b/static/netbsd/man3/BN_rand.3 new file mode 100644 index 00000000..870114f0 --- /dev/null +++ b/static/netbsd/man3/BN_rand.3 @@ -0,0 +1,179 @@ +.\" $NetBSD: BN_rand.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_rand 3" +.TH BN_rand 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand, +BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range, +BN_pseudo_rand_range +\&\- generate pseudo\-random number +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, +\& unsigned int strength, BN_CTX *ctx); +\& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& +\& int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, +\& unsigned int strength, BN_CTX *ctx); +\& int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& +\& int BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength, +\& BN_CTX *ctx); +\& int BN_rand_range(BIGNUM *rnd, const BIGNUM *range); +\& +\& int BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength, +\& BN_CTX *ctx); +\& int BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& int BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_rand_ex()\fR generates a cryptographically strong pseudo\-random +number of \fIbits\fR in length and security strength at least \fIstrength\fR bits +using the random number generator for the library context associated with +\&\fIctx\fR. The function stores the generated data in \fIrnd\fR. The parameter \fIctx\fR +may be NULL in which case the default library context is used. +If \fIbits\fR is less than zero, or too small to +accommodate the requirements specified by the \fItop\fR and \fIbottom\fR +parameters, an error is returned. +The \fItop\fR parameters specifies +requirements on the most significant bit of the generated number. +If it is \fBBN_RAND_TOP_ANY\fR, there is no constraint. +If it is \fBBN_RAND_TOP_ONE\fR, the top bit must be one. +If it is \fBBN_RAND_TOP_TWO\fR, the two most significant bits of +the number will be set to 1, so that the product of two such random +numbers will always have 2*\fIbits\fR length. +If \fIbottom\fR is \fBBN_RAND_BOTTOM_ODD\fR, the number will be odd; if it +is \fBBN_RAND_BOTTOM_ANY\fR it can be odd or even. +If \fIbits\fR is 1 then \fItop\fR cannot also be \fBBN_RAND_TOP_TWO\fR. +.PP +\&\fBBN_rand()\fR is the same as \fBBN_rand_ex()\fR except that the default library context +is always used. +.PP +\&\fBBN_rand_range_ex()\fR generates a cryptographically strong pseudo\-random +number \fIrnd\fR, of security strength at least \fIstrength\fR bits, +in the range 0 <= \fIrnd\fR < \fIrange\fR using the random number +generator for the library context associated with \fIctx\fR. The parameter \fIctx\fR +may be NULL in which case the default library context is used. +.PP +\&\fBBN_rand_range()\fR is the same as \fBBN_rand_range_ex()\fR except that the default +library context is always used. +.PP +\&\fBBN_priv_rand_ex()\fR, \fBBN_priv_rand()\fR, \fBBN_priv_rand_rand_ex()\fR and +\&\fBBN_priv_rand_range()\fR have the same semantics as \fBBN_rand_ex()\fR, \fBBN_rand()\fR, +\&\fBBN_rand_range_ex()\fR and \fBBN_rand_range()\fR respectively. They are intended to be +used for generating values that should remain private, and mirror the +same difference between \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3). +.SH NOTES +.IX Header "NOTES" +Always check the error return value of these functions and do not take +randomness for granted: an error occurs if the CSPRNG has not been +seeded with enough randomness to ensure an unpredictable byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions return 1 on success, 0 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBRAND_add\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_priv_bytes\fR\|(3), +\&\fBRAND\fR\|(7), +\&\fBEVP_RAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +.IP \(bu 2 +Starting with OpenSSL release 1.1.0, \fBBN_pseudo_rand()\fR has been identical +to \fBBN_rand()\fR and \fBBN_pseudo_rand_range()\fR has been identical to +\&\fBBN_rand_range()\fR. +The \fBBN_pseudo_rand()\fR and \fBBN_pseudo_rand_range()\fR functions were +deprecated in OpenSSL 3.0. +.IP \(bu 2 +The \fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR functions were added in +OpenSSL 1.1.1. +.IP \(bu 2 +The \fBBN_rand_ex()\fR, \fBBN_priv_rand_ex()\fR, \fBBN_rand_range_ex()\fR and +\&\fBBN_priv_rand_range_ex()\fR functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_security_bits.3 b/static/netbsd/man3/BN_security_bits.3 new file mode 100644 index 00000000..490834ba --- /dev/null +++ b/static/netbsd/man3/BN_security_bits.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: BN_security_bits.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_security_bits 3" +.TH BN_security_bits 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_security_bits \- returns bits of security based on given numbers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_security_bits(int L, int N); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_security_bits()\fR returns the number of bits of security provided by a +specific algorithm and a particular key size. The bits of security is +defined in NIST SP800\-57. Currently, \fBBN_security_bits()\fR support two types +of asymmetric algorithms: the FFC (Finite Field Cryptography) and IFC +(Integer Factorization Cryptography). For FFC, e.g., DSA and DH, both +parameters \fBL\fR and \fBN\fR are used to decide the bits of security, where +\&\fBL\fR is the size of the public key and \fBN\fR is the size of the private +key. For IFC, e.g., RSA, only \fBL\fR is used and it\*(Aqs commonly considered +to be the key size (modulus). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Number of security bits. +.SH NOTES +.IX Header "NOTES" +ECC (Elliptic Curve Cryptography) is not covered by the \fBBN_security_bits()\fR +function. The symmetric algorithms are not covered neither. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_security_bits\fR\|(3), \fBDSA_security_bits\fR\|(3), \fBRSA_security_bits\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBBN_security_bits()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_set_bit.3 b/static/netbsd/man3/BN_set_bit.3 new file mode 100644 index 00000000..c7761bfe --- /dev/null +++ b/static/netbsd/man3/BN_set_bit.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: BN_set_bit.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_set_bit 3" +.TH BN_set_bit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, +BN_lshift1, BN_rshift, BN_rshift1 \- bit operations on BIGNUMs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int BN_set_bit(BIGNUM *a, int n); +\& int BN_clear_bit(BIGNUM *a, int n); +\& +\& int BN_is_bit_set(const BIGNUM *a, int n); +\& +\& int BN_mask_bits(BIGNUM *a, int n); +\& +\& int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); +\& int BN_lshift1(BIGNUM *r, BIGNUM *a); +\& +\& int BN_rshift(BIGNUM *r, BIGNUM *a, int n); +\& int BN_rshift1(BIGNUM *r, BIGNUM *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_set_bit()\fR sets bit \fBn\fR in \fBa\fR to 1 (\f(CW\*(C`a|=(1<. diff --git a/static/netbsd/man3/BN_swap.3 b/static/netbsd/man3/BN_swap.3 new file mode 100644 index 00000000..4fcfcc9b --- /dev/null +++ b/static/netbsd/man3/BN_swap.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: BN_swap.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_swap 3" +.TH BN_swap 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_swap \- exchange BIGNUMs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void BN_swap(BIGNUM *a, BIGNUM *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_swap()\fR exchanges the values of \fIa\fR and \fIb\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_swap()\fR does not return a value. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BN_zero.3 b/static/netbsd/man3/BN_zero.3 new file mode 100644 index 00000000..0da7b1a3 --- /dev/null +++ b/static/netbsd/man3/BN_zero.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: BN_zero.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BN_zero 3" +.TH BN_zero 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word \- BIGNUM assignment +operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void BN_zero(BIGNUM *a); +\& int BN_one(BIGNUM *a); +\& +\& const BIGNUM *BN_value_one(void); +\& +\& int BN_set_word(BIGNUM *a, BN_ULONG w); +\& unsigned BN_ULONG BN_get_word(BIGNUM *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBBN_ULONG\fR is a macro that will be an unsigned integral type optimized +for the most efficient implementation on the local platform. +.PP +\&\fBBN_zero()\fR, \fBBN_one()\fR and \fBBN_set_word()\fR set \fBa\fR to the values 0, 1 and +\&\fBw\fR respectively. \fBBN_zero()\fR and \fBBN_one()\fR are macros. +.PP +\&\fBBN_value_one()\fR returns a \fBBIGNUM\fR constant of value 1. This constant +is useful for use in comparisons and assignment. +.PP +\&\fBBN_get_word()\fR returns \fBa\fR, if it can be represented as a \fBBN_ULONG\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBN_get_word()\fR returns the value \fBa\fR, or all\-bits\-set if \fBa\fR cannot +be represented as a single integer. +.PP +\&\fBBN_one()\fR and \fBBN_set_word()\fR return 1 on success, 0 otherwise. +\&\fBBN_value_one()\fR returns the constant. +\&\fBBN_zero()\fR never fails and returns no value. +.SH BUGS +.IX Header "BUGS" +If a \fBBIGNUM\fR is equal to the value of all\-bits\-set, it will collide +with the error condition returned by \fBBN_get_word()\fR which uses that +as an error value. +.PP +\&\fBBN_ULONG\fR should probably be a typedef. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBN_bn2bin\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +In OpenSSL 0.9.8, \fBBN_zero()\fR was changed to not return a value; previous +versions returned an int. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/BUF_MEM_new.3 b/static/netbsd/man3/BUF_MEM_new.3 new file mode 100644 index 00000000..6d88cbca --- /dev/null +++ b/static/netbsd/man3/BUF_MEM_new.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: BUF_MEM_new.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BUF_MEM_new 3" +.TH BUF_MEM_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, +BUF_MEM_grow_clean, BUF_reverse +\&\- simple character array structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BUF_MEM *BUF_MEM_new(void); +\& +\& BUF_MEM *BUF_MEM_new_ex(unsigned long flags); +\& +\& void BUF_MEM_free(BUF_MEM *a); +\& +\& int BUF_MEM_grow(BUF_MEM *str, int len); +\& size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len); +\& +\& void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. +.PP +\&\fBBUF_MEM_new()\fR allocates a new buffer of zero size. +.PP +\&\fBBUF_MEM_new_ex()\fR allocates a buffer with the specified flags. +The flag \fBBUF_MEM_FLAG_SECURE\fR specifies that the \fBdata\fR pointer +should be allocated on the secure heap; see \fBCRYPTO_secure_malloc\fR\|(3). +.PP +\&\fBBUF_MEM_free()\fR frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. +If the argument is NULL, nothing is done. +.PP +\&\fBBUF_MEM_grow()\fR changes the size of an already existing buffer to +\&\fBlen\fR. Any data already in the buffer is preserved if it increases in +size. +.PP +\&\fBBUF_MEM_grow_clean()\fR is similar to \fBBUF_MEM_grow()\fR but it sets any free\*(Aqd +or additionally\-allocated memory to zero. +.PP +\&\fBBUF_reverse()\fR reverses \fBsize\fR bytes at \fBin\fR into \fBout\fR. If \fBin\fR +is NULL, the array is reversed in\-place. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBUF_MEM_new()\fR returns the buffer or NULL on error. +.PP +\&\fBBUF_MEM_free()\fR has no return value. +.PP +\&\fBBUF_MEM_grow()\fR and \fBBUF_MEM_grow_clean()\fR return +zero on error or the new size (i.e., \fBlen\fR). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), +\&\fBCRYPTO_secure_malloc\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The \fBBUF_MEM_new_ex()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMAC_CTX.3 b/static/netbsd/man3/CMAC_CTX.3 new file mode 100644 index 00000000..2d1f9ff7 --- /dev/null +++ b/static/netbsd/man3/CMAC_CTX.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: CMAC_CTX.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMAC_CTX 3" +.TH CMAC_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, +CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final, +CMAC_resume +\&\- create cipher\-based message authentication codes +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +disabled entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version +value, see \fBopenssl_user_macros\fR\|(7). +.PP +.Vb 1 +\& typedef struct CMAC_CTX_st CMAC_CTX; +\& +\& CMAC_CTX *CMAC_CTX_new(void); +\& void CMAC_CTX_cleanup(CMAC_CTX *ctx); +\& void CMAC_CTX_free(CMAC_CTX *ctx); +\& EVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx); +\& int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in); +\& int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen, +\& const EVP_CIPHER *cipher, ENGINE *impl); +\& int CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen); +\& int CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen); +\& int CMAC_resume(CMAC_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The low\-level MAC functions documented on this page are deprecated. +Applications should use the new \fBEVP_MAC\fR\|(3) interface. +Specifically, utilize the following functions for MAC operations: +.IP "\fBEVP_MAC_CTX_new\fR\|(3) to create a new MAC context." 4 +.IX Item "EVP_MAC_CTX_new to create a new MAC context." +.PD 0 +.IP "\fBEVP_MAC_CTX_free\fR\|(3) to free the MAC context." 4 +.IX Item "EVP_MAC_CTX_free to free the MAC context." +.IP "\fBEVP_MAC_init\fR\|(3) to initialize the MAC context." 4 +.IX Item "EVP_MAC_init to initialize the MAC context." +.IP "\fBEVP_MAC_update\fR\|(3) to update the MAC with data." 4 +.IX Item "EVP_MAC_update to update the MAC with data." +.IP "\fBEVP_MAC_final\fR\|(3) to finalize the MAC and retrieve the output." 4 +.IX Item "EVP_MAC_final to finalize the MAC and retrieve the output." +.PD +.PP +Alternatively, for a single\-step MAC computation, use the \fBEVP_Q_mac\fR\|(3) +function. +.PP +The \fBCMAC_CTX\fR type is a structure used for the provision of CMAC +(Cipher\-based Message Authentication Code) operations. +.PP +\&\fBCMAC_CTX_new()\fR creates a new \fBCMAC_CTX\fR structure and returns a pointer to it. +.PP +\&\fBCMAC_CTX_cleanup()\fR resets the \fBCMAC_CTX\fR structure, clearing any internal data +but not freeing the structure itself. +.PP +\&\fBCMAC_CTX_free()\fR frees the \fBCMAC_CTX\fR structure and any associated resources. +If the argument is NULL, no action is taken. +.PP +\&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal \fBEVP_CIPHER_CTX\fR +structure within the \fBCMAC_CTX\fR. +.PP +\&\fBCMAC_CTX_copy()\fR copies the state from one \fBCMAC_CTX\fR structure to another. +.PP +\&\fBCMAC_Init()\fR initializes the \fBCMAC_CTX\fR structure for a new CMAC calculation +with the specified key, key length, and cipher type. +Optionally, an \fBENGINE\fR can be provided. +.PP +\&\fBCMAC_Update()\fR processes data to be included in the CMAC calculation. +This function can be called multiple times to update the context with +additional data. +.PP +\&\fBCMAC_Final()\fR finalizes the CMAC calculation and retrieves the resulting +MAC value. The output is stored in the provided buffer, and the length is +stored in the variable pointed to by \fIpoutlen\fR. To determine the required +buffer size, call with \fIout\fR set to NULL, which stores only the length in +\&\fIpoutlen\fR. Allocate a buffer of this size and call \fBCMAC_Final()\fR again with +the allocated buffer to retrieve the MAC. +.PP +\&\fBCMAC_resume()\fR resumes a previously finalized CMAC calculation, allowing +additional data to be processed and a new MAC to be generated. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMAC_CTX_new()\fR returns a pointer to a new \fBCMAC_CTX\fR structure or NULL if +an error occurs. +.PP +\&\fBCMAC_CTX_get0_cipher_ctx()\fR returns a pointer to the internal +\&\fBEVP_CIPHER_CTX\fR structure, or NULL if an error occurs. +.PP +\&\fBCMAC_CTX_copy()\fR, \fBCMAC_Init()\fR, \fBCMAC_Update()\fR, \fBCMAC_Final()\fR and \fBCMAC_resume()\fR +return 1 for success or 0 if an error occurs. +.SH HISTORY +.IX Header "HISTORY" +All functions described here were deprecated in OpenSSL 3.0. For replacements, +see \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), \fBEVP_MAC_init\fR\|(3), +\&\fBEVP_MAC_update\fR\|(3), and \fBEVP_MAC_final\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_EncryptedData_decrypt.3 b/static/netbsd/man3/CMS_EncryptedData_decrypt.3 new file mode 100644 index 00000000..bc7b788c --- /dev/null +++ b/static/netbsd/man3/CMS_EncryptedData_decrypt.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: CMS_EncryptedData_decrypt.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_EncryptedData_decrypt 3" +.TH CMS_EncryptedData_decrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_EncryptedData_decrypt, CMS_EnvelopedData_decrypt +\&\- Decrypt CMS EncryptedData or EnvelopedData +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_EncryptedData_decrypt(CMS_ContentInfo *cms, +\& const unsigned char *key, size_t keylen, +\& BIO *dcont, BIO *out, unsigned int flags); +\& +\& BIO *CMS_EnvelopedData_decrypt(CMS_EnvelopedData *env, BIO *detached_data, +\& EVP_PKEY *pkey, X509 *cert, +\& ASN1_OCTET_STRING *secret, unsigned int flags, +\& OSSL_LIB_CTX *libctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_EncryptedData_decrypt()\fR decrypts a \fIcms\fR EncryptedData object using the +symmetric \fIkey\fR of size \fIkeylen\fR bytes. AEAD cipher algorithms are not +supported. \fIout\fR is a BIO to write the content to and \fIflags\fR is an optional +set of flags. \fIdcont\fR is used in the rare case where the encrypted content is +detached. It will normally be set to NULL. +.PP +The following flags can be passed in the \fIflags\fR parameter. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted +from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is +returned. +.PP +\&\fBCMS_EnvelopedData_decrypt()\fR decrypts, similarly to \fBCMS_decrypt\fR\|(3), +a CMS EnvelopedData object \fIenv\fR using the symmetric key \fIsecret\fR if it +is not NULL, otherwise the private key of the recipient \fIpkey\fR. +If \fIpkey\fR is given, it is recommended to provide also the associated +certificate in \fIcert\fR \- see \fBCMS_decrypt\fR\|(3) and the NOTES on \fIcert\fR there. +The optional parameters \fIflags\fR and \fIdcont\fR are used as described above. +The optional parameters library context \fIlibctx\fR and property query \fIpropq\fR +are used when retrieving algorithms from providers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_EncryptedData_decrypt()\fR returns 0 if an error occurred otherwise returns 1. +.PP +\&\fBCMS_EnvelopedData_decrypt()\fR returns NULL if an error occurred, +otherwise a BIO containing the decypted content. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_EnvelopedData_decrypt()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_EncryptedData_encrypt.3 b/static/netbsd/man3/CMS_EncryptedData_encrypt.3 new file mode 100644 index 00000000..6418bbf9 --- /dev/null +++ b/static/netbsd/man3/CMS_EncryptedData_encrypt.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: CMS_EncryptedData_encrypt.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_EncryptedData_encrypt 3" +.TH CMS_EncryptedData_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_EncryptedData_encrypt_ex, CMS_EncryptedData_encrypt +\&\- Create CMS EncryptedData +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_EncryptedData_encrypt_ex(BIO *in, +\& const EVP_CIPHER *cipher, +\& const unsigned char *key, +\& size_t keylen, +\& unsigned int flags, +\& OSSL_LIB_CTX *ctx, +\& const char *propq); +\& +\& CMS_ContentInfo *CMS_EncryptedData_encrypt(BIO *in, +\& const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen, +\& unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_EncryptedData_encrypt_ex()\fR creates a \fBCMS_ContentInfo\fR structure +with a type \fBNID_pkcs7_encrypted\fR. \fIin\fR is a BIO containing the data to +encrypt using \fIcipher\fR and the encryption key \fIkey\fR of size \fIkeylen\fR bytes. +The library context \fIlibctx\fR and the property query \fIpropq\fR are used when +retrieving algorithms from providers. \fIflags\fR is a set of optional flags. +.PP +The \fIflags\fR field supports the options \fBCMS_DETACHED\fR, \fBCMS_STREAM\fR and +\&\fBCMS_PARTIAL\fR. Internally \fBCMS_final()\fR is called unless \fBCMS_STREAM\fR and/or +\&\fBCMS_PARTIAL\fR is specified. +.PP +The algorithm passed in the \fIcipher\fR parameter must support ASN1 encoding of +its parameters. AEAD cipher algorithms are not supported. +.PP +The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3). +.PP +\&\fBCMS_EncryptedData_encrypt()\fR is similar to \fBCMS_EncryptedData_encrypt_ex()\fR +but uses default values of NULL for the library context \fIlibctx\fR and the +property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBCMS_EncryptedData_encrypt_ex()\fR and +\&\fBCMS_EncryptedData_encrypt()\fR return NULL and set an error code that can be +obtained by \fBERR_get_error\fR\|(3). Otherwise they return a pointer to the newly +allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3), \fBCMS_EncryptedData_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_EncryptedData_encrypt_ex()\fR method was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_EncryptedData_set1_key.3 b/static/netbsd/man3/CMS_EncryptedData_set1_key.3 new file mode 100644 index 00000000..79842261 --- /dev/null +++ b/static/netbsd/man3/CMS_EncryptedData_set1_key.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: CMS_EncryptedData_set1_key.3,v 1.2 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_EncryptedData_set1_key 3" +.TH CMS_EncryptedData_set1_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_EncryptedData_set1_key \- Sets the cipher and key for +CMS EncryptedData +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_EncryptedData_set1_key(CMS_ContentInfo *cms, const EVP_CIPHER *ciph, +\& const unsigned char *key, size_t keylen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_EncryptedData_set1_key()\fR takes in a \fIcms\fR EncryptedData object and sets +the appropriate attributes to \fIciph\fR, it makes a copy of the symmetric \fIkey\fR +of size \fIkeylen\fR. AEAD cipher algorithms are not supported. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_EncryptedData_set1_key()\fR returns 0 if an error occurred otherwise +returns 1. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCMS_EncryptedData_encrypt\fR\|(3), \fBCMS_EncryptedData_decrypt\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_EnvelopedData_create.3 b/static/netbsd/man3/CMS_EnvelopedData_create.3 new file mode 100644 index 00000000..45a8757b --- /dev/null +++ b/static/netbsd/man3/CMS_EnvelopedData_create.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: CMS_EnvelopedData_create.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_EnvelopedData_create 3" +.TH CMS_EnvelopedData_create 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_EnvelopedData_create_ex, CMS_EnvelopedData_create, +CMS_AuthEnvelopedData_create, CMS_AuthEnvelopedData_create_ex +\&\- Create CMS envelope +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo * +\& CMS_EnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& CMS_ContentInfo *CMS_EnvelopedData_create(const EVP_CIPHER *cipher); +\& +\& CMS_ContentInfo * +\& CMS_AuthEnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& CMS_ContentInfo *CMS_AuthEnvelopedData_create(const EVP_CIPHER *cipher); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_EnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure +with a type \fBNID_pkcs7_enveloped\fR. \fIcipher\fR is the symmetric cipher to use. +The library context \fIlibctx\fR and the property query \fIpropq\fR are used when +retrieving algorithms from providers. +.PP +\&\fBCMS_AuthEnvelopedData_create_ex()\fR creates a \fBCMS_ContentInfo\fR +structure with a type \fBNID_id_smime_ct_authEnvelopedData\fR. \fBcipher\fR is the +symmetric AEAD cipher to use. Currently only AES variants with GCM mode are +supported. The library context \fIlibctx\fR and the property query \fIpropq\fR are +used when retrieving algorithms from providers. +.PP +The algorithm passed in the \fIcipher\fR parameter must support ASN1 encoding of +its parameters. +.PP +The recipients can be added later using \fBCMS_add1_recipient_cert\fR\|(3) or +\&\fBCMS_add0_recipient_key\fR\|(3). +.PP +The \fBCMS_ContentInfo\fR structure needs to be finalized using \fBCMS_final\fR\|(3) +and then freed using \fBCMS_ContentInfo_free\fR\|(3). +.PP +\&\fBCMS_EnvelopedData_create()\fR and \fBCMS_AuthEnvelopedData_create()\fR are similar to +\&\fBCMS_EnvelopedData_create_ex()\fR and \fBCMS_AuthEnvelopedData_create_ex()\fR +but use default values of NULL for +the library context \fIlibctx\fR and the property query \fIpropq\fR. +.SH NOTES +.IX Header "NOTES" +Although \fBCMS_EnvelopedData_create_ex()\fR, and \fBCMS_EnvelopedData_create()\fR, +\&\fBCMS_AuthEnvelopedData_create_ex()\fR, and \fBCMS_AuthEnvelopedData_create()\fR allocate +a new \fBCMS_ContentInfo\fR structure, they are not usually used in applications. +The wrappers \fBCMS_encrypt\fR\|(3) and \fBCMS_decrypt\fR\|(3) are often used instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBCMS_EnvelopedData_create_ex()\fR, +\&\fBCMS_EnvelopedData_create()\fR, \fBCMS_AuthEnvelopedData_create_ex()\fR, +\&\fBCMS_AuthEnvelopedData_create()\fR, \fBCMS_AuthEnvelopedData_create()\fR, +and \fBCMS_AuthEnvelopedData_create_ex()\fR return NULL and set an +error code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise, they return a pointer to the newly allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_encrypt\fR\|(3), \fBCMS_decrypt\fR\|(3), \fBCMS_final\fR\|(3), +\&\fBCMS_sign_ex\fR\|(3), \fBCMS_encrypt_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_EnvelopedData_create_ex()\fR method was added in OpenSSL 3.0. +.PP +\&\fBCMS_AuthEnvelopedData_create()\fR and \fBCMS_AuthEnvelopedData_create_ex()\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_add0_cert.3 b/static/netbsd/man3/CMS_add0_cert.3 new file mode 100644 index 00000000..d69dfded --- /dev/null +++ b/static/netbsd/man3/CMS_add0_cert.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: CMS_add0_cert.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_add0_cert 3" +.TH CMS_add0_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, +CMS_add0_crl, CMS_add1_crl, CMS_get1_crls +\&\- CMS certificate and CRL utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); +\& int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); +\& STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); +\& +\& int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); +\& int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); +\& STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_add0_cert()\fR and \fBCMS_add1_cert()\fR add certificate \fIcert\fR to \fIcms\fR +unless it is already present. +This is used by \fBCMS_sign_ex\fR\|(3) and \fBCMS_sign\fR\|(3) and may be used before +calling \fBCMS_verify\fR\|(3) to help chain building in certificate validation. +As the 0 implies, \fBCMS_add0_cert()\fR adds \fIcert\fR internally to \fIcms\fR +and on success it must not be freed up by the caller. +In contrast, the caller of \fBCMS_add1_cert()\fR must free \fIcert\fR. +\&\fIcms\fR must be of type signed data or (authenticated) enveloped data. +For signed data, such a certificate can be used when signing or verifying +to fill in the signer certificate or to provide an extra CA certificate +that may be needed for chain building in certificate validation. +.PP +\&\fBCMS_get1_certs()\fR returns all certificates in \fIcms\fR. +.PP +\&\fBCMS_add0_crl()\fR and \fBCMS_add1_crl()\fR add CRL \fIcrl\fR to \fIcms\fR. +\&\fIcms\fR must be of type signed data or (authenticated) enveloped data. +For signed data, such a CRL may be used in certificate validation +with \fBCMS_verify\fR\|(3). +It may be given both for inclusion when signing a CMS message +and when verifying a signed CMS message. +.PP +\&\fBCMS_get1_crls()\fR returns all CRLs in \fIcms\fR. +.SH NOTES +.IX Header "NOTES" +The CMS_ContentInfo structure \fIcms\fR must be of type signed data or enveloped +data or authenticated enveloped data or an error will be returned. +.PP +For signed data, certificates and CRLs are added to the \fIcertificates\fR and +\&\fIcrls\fR fields of SignedData structure. +For enveloped data they are added to \fBOriginatorInfo\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_add0_cert()\fR, \fBCMS_add1_cert()\fR and \fBCMS_add0_crl()\fR and \fBCMS_add1_crl()\fR return +1 for success and 0 for failure. +.PP +\&\fBCMS_get1_certs()\fR and \fBCMS_get1_crls()\fR return the STACK of certificates or CRLs +or NULL if there are none or an error occurs. +Besides out\-of\-memory, the only error which will occur +in practice is if the \fIcms\fR type is invalid. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBCMS_sign\fR\|(3), \fBCMS_sign_ex\fR\|(3), \fBCMS_verify\fR\|(3), +\&\fBCMS_encrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_add0_cert()\fR and \fBCMS_add1_cert()\fR have been changed in OpenSSL 3.2 +not to throw an error if a certificate to be added is already present. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_add1_recipient_cert.3 b/static/netbsd/man3/CMS_add1_recipient_cert.3 new file mode 100644 index 00000000..bb0564a8 --- /dev/null +++ b/static/netbsd/man3/CMS_add1_recipient_cert.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: CMS_add1_recipient_cert.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_add1_recipient_cert 3" +.TH CMS_add1_recipient_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key \- add recipients to a CMS enveloped data structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip, +\& EVP_PKEY *originatorPrivKey, +\& X509 *originator, unsigned int flags); +\& +\& CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, +\& X509 *recip, unsigned int flags); +\& +\& CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, +\& unsigned char *key, size_t keylen, +\& unsigned char *id, size_t idlen, +\& ASN1_GENERALIZEDTIME *date, +\& ASN1_OBJECT *otherTypeId, +\& ASN1_TYPE *otherType); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_add1_recipient()\fR adds recipient \fBrecip\fR and provides the originator pkey +\&\fBoriginatorPrivKey\fR and originator certificate \fBoriginator\fR to CMS_ContentInfo. +The originator\-related fields are relevant only in case when the keyAgreement +method of providing of the shared key is in use. +.PP +\&\fBCMS_add1_recipient_cert()\fR adds recipient \fBrecip\fR to CMS_ContentInfo enveloped +data structure \fBcms\fR as a KeyTransRecipientInfo structure. +.PP +\&\fBCMS_add0_recipient_key()\fR adds symmetric key \fBkey\fR of length \fBkeylen\fR using +wrapping algorithm \fBnid\fR, identifier \fBid\fR of length \fBidlen\fR and optional +values \fBdate\fR, \fBotherTypeId\fR and \fBotherType\fR to CMS_ContentInfo enveloped +data structure \fBcms\fR as a KEKRecipientInfo structure. +.PP +The CMS_ContentInfo structure should be obtained from an initial call to +\&\fBCMS_encrypt()\fR with the flag \fBCMS_PARTIAL\fR set. +.SH NOTES +.IX Header "NOTES" +The main purpose of this function is to provide finer control over a CMS +enveloped data structure where the simpler \fBCMS_encrypt()\fR function defaults are +not appropriate. For example if one or more KEKRecipientInfo structures +need to be added. New attributes can also be added using the returned +CMS_RecipientInfo structure and the CMS attribute utility functions. +.PP +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If \fBCMS_USE_KEYID\fR is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. +.PP +Currently only AES based key wrapping algorithms are supported for \fBnid\fR, +specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. +If \fBnid\fR is set to \fBNID_undef\fR then an AES wrap algorithm will be used +consistent with \fBkeylen\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_add1_recipient_cert()\fR and \fBCMS_add0_recipient_key()\fR return an internal +pointer to the CMS_RecipientInfo structure just added or NULL if an error +occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3), +\&\fBCMS_final\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_add1_recipient_cert\fR and \fBCMS_add0_recipient_key\fR were added in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_add1_signer.3 b/static/netbsd/man3/CMS_add1_signer.3 new file mode 100644 index 00000000..3d8dfcb4 --- /dev/null +++ b/static/netbsd/man3/CMS_add1_signer.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: CMS_add1_signer.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_add1_signer 3" +.TH CMS_add1_signer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_add1_signer, CMS_SignerInfo_sign \- add a signer to a CMS_ContentInfo signed data structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, +\& EVP_PKEY *pkey, const EVP_MD *md, +\& unsigned int flags); +\& +\& int CMS_SignerInfo_sign(CMS_SignerInfo *si); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_add1_signer()\fR adds a signer with certificate \fBsigncert\fR and private +key \fBpkey\fR using message digest \fBmd\fR to CMS_ContentInfo SignedData +structure \fBcms\fR. +.PP +The CMS_ContentInfo structure should be obtained from an initial call to +\&\fBCMS_sign()\fR with the flag \fBCMS_PARTIAL\fR set or in the case or re\-signing a +valid CMS_ContentInfo SignedData structure. +.PP +If the \fBmd\fR parameter is \fBNULL\fR then the default digest for the public +key algorithm will be used. +.PP +Unless the \fBCMS_REUSE_DIGEST\fR flag is set the returned CMS_ContentInfo +structure is not complete and must be finalized either by streaming (if +applicable) or a call to \fBCMS_final()\fR. +.PP +The \fBCMS_SignerInfo_sign()\fR function explicitly signs a CMS_SignerInfo +structure, its main use is when the \fBCMS_REUSE_DIGEST\fR and \fBCMS_PARTIAL\fR flags +are both set. +.SH NOTES +.IX Header "NOTES" +The main purpose of \fBCMS_add1_signer()\fR is to provide finer control +over a CMS signed data structure where the simpler \fBCMS_sign()\fR function defaults +are not appropriate. For example if multiple signers or non default digest +algorithms are needed. New attributes can also be added using the returned +CMS_SignerInfo structure and the CMS attribute utility functions or the +CMS signed receipt request functions. +.PP +Any of the following flags (ored together) can be passed in the \fBflags\fR +parameter. +.PP +If \fBCMS_REUSE_DIGEST\fR is set then an attempt is made to copy the content +digest value from the CMS_ContentInfo structure: to add a signer to an existing +structure. An error occurs if a matching digest value cannot be found to copy. +The returned CMS_ContentInfo structure will be valid and finalized when this +flag is set. +.PP +If \fBCMS_PARTIAL\fR is set in addition to \fBCMS_REUSE_DIGEST\fR then the +CMS_SignerInfo structure will not be finalized so additional attributes +can be added. In this case an explicit call to \fBCMS_SignerInfo_sign()\fR is +needed to finalize it. +.PP +If \fBCMS_NOCERTS\fR is set the signer\*(Aqs certificate will not be included in the +CMS_ContentInfo structure, the signer\*(Aqs certificate must still be supplied in +the \fBsigncert\fR parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. +.PP +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If \fBCMS_NOATTR\fR is set then no signedAttributes +will be used at all. If \fBCMS_NOSMIMECAP\fR is set then the SMIMECapabilities +will be omitted. If \fBCMS_NO_SIGNING_TIME\fR is set then the signing time will be +omitted. +.PP +OpenSSL will by default identify signing certificates using issuer name +and serial number. If \fBCMS_USE_KEYID\fR is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. +.PP +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411\-94, Gost 28147\-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. +.PP +\&\fBCMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo +structure just added, this can be used to set additional attributes +before it is finalized. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_add1_signer()\fR returns an internal pointer to the CMS_SignerInfo +structure just added or NULL if an error occurs. +.PP +\&\fBCMS_SignerInfo_sign()\fR returns 1 on success, 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_final\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_compress.3 b/static/netbsd/man3/CMS_compress.3 new file mode 100644 index 00000000..08fc7bd2 --- /dev/null +++ b/static/netbsd/man3/CMS_compress.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: CMS_compress.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_compress 3" +.TH CMS_compress 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_compress \- create a CMS CompressedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_compress()\fR creates and returns a CMS CompressedData structure. \fBcomp_nid\fR +is the compression algorithm to use or \fBNID_undef\fR to use the default +algorithm (zlib compression). \fBin\fR is the content to be compressed. +\&\fBflags\fR is an optional set of flags. +.PP +The only currently supported compression algorithm is zlib using the NID +NID_zlib_compression. +.PP +If zlib support is not compiled into OpenSSL then \fBCMS_compress()\fR will return +an error. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are +prepended to the data. +.PP +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if \fBCMS_BINARY\fR is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If \fBCMS_BINARY\fR is set then +\&\fBCMS_TEXT\fR is ignored. +.PP +If the \fBCMS_STREAM\fR flag is set a partial \fBCMS_ContentInfo\fR structure is +returned suitable for streaming I/O: no data is read from the BIO \fBin\fR. +.PP +The compressed data is included in the CMS_ContentInfo structure, unless +\&\fBCMS_DETACHED\fR is set in which case it is omitted. This is rarely used in +practice and is not supported by \fBSMIME_write_CMS()\fR. +.PP +If the flag \fBCMS_STREAM\fR is set the returned \fBCMS_ContentInfo\fR structure is +\&\fBnot\fR complete and outputting its contents via a function that does not +properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable +results. +.PP +Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR, +\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 \fBBIO\fR directly using +\&\fBBIO_new_CMS()\fR. +.PP +Additional compression parameters such as the zlib compression level cannot +currently be set. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_compress()\fR returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_uncompress\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_STREAM\fR flag was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_data_create.3 b/static/netbsd/man3/CMS_data_create.3 new file mode 100644 index 00000000..5dd568ff --- /dev/null +++ b/static/netbsd/man3/CMS_data_create.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: CMS_data_create.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_data_create 3" +.TH CMS_data_create 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_data_create_ex, CMS_data_create +\&\- Create CMS Data object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_data_create_ex(BIO *in, unsigned int flags, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& CMS_ContentInfo *CMS_data_create(BIO *in, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_data_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure +with a type \fBNID_pkcs7_data\fR. The data is supplied via the \fIin\fR BIO. +The library context \fIlibctx\fR and the property query \fIpropq\fR are used when +retrieving algorithms from providers. The \fIflags\fR field supports the +\&\fBCMS_STREAM\fR flag. Internally \fBCMS_final()\fR is called unless \fBCMS_STREAM\fR is +specified. +.PP +The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3). +.PP +\&\fBCMS_data_create()\fR is similar to \fBCMS_data_create_ex()\fR +but uses default values of NULL for the library context \fIlibctx\fR and the +property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBCMS_data_create_ex()\fR and \fBCMS_data_create()\fR +return NULL and set an error code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise they return a pointer to the newly allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_data_create_ex()\fR method was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_decrypt.3 b/static/netbsd/man3/CMS_decrypt.3 new file mode 100644 index 00000000..82050229 --- /dev/null +++ b/static/netbsd/man3/CMS_decrypt.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: CMS_decrypt.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_decrypt 3" +.TH CMS_decrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_decrypt, CMS_decrypt_set1_pkey_and_peer, +CMS_decrypt_set1_pkey, CMS_decrypt_set1_password +\&\- decrypt content from a CMS envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, +\& BIO *dcont, BIO *out, unsigned int flags); +\& int CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms, +\& EVP_PKEY *pk, X509 *cert, X509 *peer); +\& int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert); +\& int CMS_decrypt_set1_password(CMS_ContentInfo *cms, +\& unsigned char *pass, ossl_ssize_t passlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_decrypt()\fR extracts the decrypted content from a CMS EnvelopedData +or AuthEnvelopedData structure. +It uses \fBCMS_decrypt_set1_pkey()\fR to decrypt the content +with the recipient private key \fIpkey\fR if \fIpkey\fR is not NULL. +In this case, the associated certificate is recommended to provide in \fIcert\fR \- +see the NOTES below. +\&\fIout\fR is a BIO to write the content to and +\&\fIflags\fR is an optional set of flags. +If \fIpkey\fR is NULL the function assumes that decryption was already done +(e.g., using \fBCMS_decrypt_set1_pkey()\fR or \fBCMS_decrypt_set1_password()\fR) and just +provides the content unless \fIcert\fR, \fIdcont\fR, and \fIout\fR are NULL as well. +The \fIdcont\fR parameter is used in the rare case where the encrypted content +is detached. It will normally be set to NULL. +.PP +\&\fBCMS_decrypt_set1_pkey_and_peer()\fR decrypts the CMS_ContentInfo structure \fIcms\fR +using the private key \fIpkey\fR, the corresponding certificate \fIcert\fR, which is +recommended but may be NULL, and the (optional) originator certificate \fIpeer\fR. +On success, it also records in \fIcms\fR the decryption key \fIpkey\fR, and then +should be followed by \f(CW\*(C`CMS_decrypt(cms, NULL, NULL, dcont, out, flags)\*(C'\fR. +This call deallocates any decryption key stored in \fIcms\fR. +.PP +\&\fBCMS_decrypt_set1_pkey()\fR is the same as +\&\fBCMS_decrypt_set1_pkey_and_peer()\fR with \fIpeer\fR being NULL. +.PP +\&\fBCMS_decrypt_set1_password()\fR decrypts the CMS_ContentInfo structure \fIcms\fR +using the secret \fIpass\fR of length \fIpasslen\fR. +On success, it also records in \fIcms\fR the decryption key used, and then +should be followed by \f(CW\*(C`CMS_decrypt(cms, NULL, NULL, dcont, out, flags)\*(C'\fR. +This call deallocates any decryption key stored in \fIcms\fR. +.SH NOTES +.IX Header "NOTES" +Although the recipients certificate is not needed to decrypt the data it is +needed to locate the appropriate (of possible several) recipients in the CMS +structure. +.PP +If \fIcert\fR is set to NULL all possible recipients are tried. This case however +is problematic. To thwart the MMA attack (Bleichenbacher\*(Aqs attack on +PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or +not. If no recipient succeeds then a random symmetric key is used to decrypt +the content: this will typically output garbage and may (but is not guaranteed +to) ultimately return a padding error only. If \fBCMS_decrypt()\fR just returned an +error when all recipient encrypted keys failed to decrypt an attacker could +use this in a timing attack. If the special flag \fBCMS_DEBUG_DECRYPT\fR is set +then the above behaviour is modified and an error \fBis\fR returned if no +recipient encrypted key can be decrypted \fBwithout\fR generating a random +content encryption key. Applications should use this flag with +\&\fBextreme caution\fR especially in automated gateways as it can leave them +open to attack. +.PP +It is possible to determine the correct recipient key by other means (for +example looking them up in a database) and setting them in the CMS structure +in advance using the CMS utility functions such as \fBCMS_set1_pkey()\fR, +or use \fBCMS_decrypt_set1_password()\fR if the recipient has a symmetric key. +In these cases both \fIcert\fR and \fIpkey\fR should be set to NULL. +.PP +To process KEKRecipientInfo types \fBCMS_set1_key()\fR or \fBCMS_RecipientInfo_set0_key()\fR +and \fBCMS_RecipientInfo_decrypt()\fR should be called before \fBCMS_decrypt()\fR and +\&\fIcert\fR and \fIpkey\fR set to NULL. +.PP +The following flags can be passed in the \fIflags\fR parameter. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted +from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is +returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_decrypt()\fR, \fBCMS_decrypt_set1_pkey_and_peer()\fR, +\&\fBCMS_decrypt_set1_pkey()\fR, and \fBCMS_decrypt_set1_password()\fR +return either 1 for success or 0 for failure. +The error can be obtained from \fBERR_get_error\fR\|(3). +.SH BUGS +.IX Header "BUGS" +The \fBset1_\fR part of these function names is misleading +and should better read: \fBwith_\fR. +.PP +The lack of single pass processing and the need to hold all data in memory as +mentioned in \fBCMS_verify()\fR also applies to \fBCMS_decrypt()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_encrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_decrypt_set1_pkey_and_peer()\fR and \fBCMS_decrypt_set1_password()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_digest_create.3 b/static/netbsd/man3/CMS_digest_create.3 new file mode 100644 index 00000000..4a2e6b2e --- /dev/null +++ b/static/netbsd/man3/CMS_digest_create.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: CMS_digest_create.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_digest_create 3" +.TH CMS_digest_create 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_digest_create_ex, CMS_digest_create +\&\- Create CMS DigestedData object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_digest_create_ex(BIO *in, const EVP_MD *md, +\& unsigned int flags, OSSL_LIB_CTX *ctx, +\& const char *propq); +\& +\& CMS_ContentInfo *CMS_digest_create(BIO *in, const EVP_MD *md, +\& unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_digest_create_ex()\fR creates a \fBCMS_ContentInfo\fR structure +with a type \fBNID_pkcs7_digest\fR. The data supplied via the \fIin\fR BIO is digested +using \fImd\fR. The library context \fIlibctx\fR and the property query \fIpropq\fR are +used when retrieving algorithms from providers. +The \fIflags\fR field supports the \fBCMS_DETACHED\fR and \fBCMS_STREAM\fR flags, +Internally \fBCMS_final()\fR is called unless \fBCMS_STREAM\fR is specified. +.PP +The \fBCMS_ContentInfo\fR structure can be freed using \fBCMS_ContentInfo_free\fR\|(3). +.PP +\&\fBCMS_digest_create()\fR is similar to \fBCMS_digest_create_ex()\fR +but uses default values of NULL for the library context \fIlibctx\fR and the +property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBCMS_digest_create_ex()\fR and \fBCMS_digest_create()\fR +return NULL and set an error code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise they return a pointer to the newly allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_final\fR\|(3)> +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_digest_create_ex()\fR method was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_encrypt.3 b/static/netbsd/man3/CMS_encrypt.3 new file mode 100644 index 00000000..263ec00d --- /dev/null +++ b/static/netbsd/man3/CMS_encrypt.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: CMS_encrypt.3,v 1.5 2026/04/08 17:06:41 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_encrypt 3" +.TH CMS_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_encrypt_ex, CMS_encrypt \- create a CMS envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_encrypt_ex(STACK_OF(X509) *certs, BIO *in, +\& const EVP_CIPHER *cipher, unsigned int flags, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, +\& const EVP_CIPHER *cipher, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_encrypt_ex()\fR creates and returns a CMS EnvelopedData or +AuthEnvelopedData structure. \fIcerts\fR is a list of recipient certificates. +\&\fIin\fR is the content to be encrypted. \fIcipher\fR is the symmetric cipher to use. +\&\fIflags\fR is an optional set of flags. The library context \fIlibctx\fR and the +property query \fIpropq\fR are used internally when retrieving algorithms from +providers. +.PP +Only certificates carrying RSA, Diffie\-Hellman or EC keys are supported by this +function. +.PP +\&\fBEVP_des_ede3_cbc()\fR (triple DES) is the algorithm of choice for S/MIME use +because most clients will support it. +.PP +The algorithm passed in the \fBcipher\fR parameter must support ASN1 encoding of +its parameters. If the cipher mode is GCM, then an AuthEnvelopedData structure +containing MAC is used. Otherwise an EnvelopedData structure is used. Currently +the AES variants with GCM mode are the only supported AEAD algorithms. +.PP +Many browsers implement a "sign and encrypt" option which is simply an S/MIME +envelopedData containing an S/MIME signed message. This can be readily produced +by storing the S/MIME signed message in a memory BIO and passing it to +\&\fBCMS_encrypt()\fR. +.PP +The following flags can be passed in the \fBflags\fR parameter. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are +prepended to the data. +.PP +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if \fBCMS_BINARY\fR is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If \fBCMS_BINARY\fR is set then +\&\fBCMS_TEXT\fR is ignored. +.PP +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If \fBCMS_USE_KEYID\fR is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. +.PP +If the \fBCMS_STREAM\fR flag is set a partial \fBCMS_ContentInfo\fR structure is +returned suitable for streaming I/O: no data is read from the BIO \fBin\fR. +.PP +If the \fBCMS_PARTIAL\fR flag is set a partial \fBCMS_ContentInfo\fR structure is +returned to which additional recipients and attributes can be added before +finalization. +.PP +The data being encrypted is included in the CMS_ContentInfo structure, unless +\&\fBCMS_DETACHED\fR is set in which case it is omitted. This is rarely used in +practice and is not supported by \fBSMIME_write_CMS()\fR. +.PP +If the flag \fBCMS_STREAM\fR is set the returned \fBCMS_ContentInfo\fR structure is +\&\fBnot\fR complete and outputting its contents via a function that does not +properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable +results. +.PP +Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR, +\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 \fBBIO\fR directly using +\&\fBBIO_new_CMS()\fR. +.PP +The recipients specified in \fBcerts\fR use a CMS KeyTransRecipientInfo info +structure. KEKRecipientInfo is also supported using the flag \fBCMS_PARTIAL\fR +and \fBCMS_add0_recipient_key()\fR. +.PP +The parameter \fBcerts\fR may be NULL if \fBCMS_PARTIAL\fR is set and recipients +added later using \fBCMS_add1_recipient_cert()\fR or \fBCMS_add0_recipient_key()\fR. +.PP +\&\fBCMS_encrypt()\fR is similar to \fBCMS_encrypt_ex()\fR but uses default values +of NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_encrypt_ex()\fR and \fBCMS_encrypt()\fR return either a CMS_ContentInfo +structure or NULL if an error occurred. The error can be obtained from +\&\fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBCMS_encrypt_ex()\fR was added in OpenSSL 3.0. +.PP +The \fBCMS_STREAM\fR flag was first supported in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_final.3 b/static/netbsd/man3/CMS_final.3 new file mode 100644 index 00000000..5fe64932 --- /dev/null +++ b/static/netbsd/man3/CMS_final.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: CMS_final.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_final 3" +.TH CMS_final 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_final, CMS_final_digest \- finalise a CMS_ContentInfo structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); +\& int CMS_final_digest(CMS_ContentInfo *cms, const unsigned char *md, +\& unsigned int mdlen, BIO *dcont, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_final()\fR finalises the structure \fBcms\fR. Its purpose is to perform any +operations necessary on \fBcms\fR (digest computation for example) and set the +appropriate fields. The parameter \fBdata\fR contains the content to be +processed. The \fBdcont\fR parameter contains a BIO to write content to after +processing: this is only used with detached data and will usually be set to +NULL. +.PP +\&\fBCMS_final_digest()\fR finalises the structure \fBcms\fR using a pre\-computed digest, +rather than computing the digest from the original data. +.SH NOTES +.IX Header "NOTES" +These functions will normally be called when the \fBCMS_PARTIAL\fR flag is used. It +should only be used when streaming is not performed because the streaming +I/O functions perform finalisation operations internally. +.PP +To sign a pre\-computed digest, \fBCMS_sign\fR\|(3) or \fBCMS_sign_ex()\fR is called +with the \fBdata\fR parameter set to NULL before the CMS structure is finalised +with the digest provided to \fBCMS_final_digest()\fR in binary form. +When signing a pre\-computed digest, the security relies on the digest and its +computation from the original message being trusted. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_final()\fR and \fBCMS_final_digest()\fR return 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_encrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_final_digest()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_get0_RecipientInfos.3 b/static/netbsd/man3/CMS_get0_RecipientInfos.3 new file mode 100644 index 00000000..a7ea5a30 --- /dev/null +++ b/static/netbsd/man3/CMS_get0_RecipientInfos.3 @@ -0,0 +1,212 @@ +.\" $NetBSD: CMS_get0_RecipientInfos.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_get0_RecipientInfos 3" +.TH CMS_get0_RecipientInfos 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_get0_RecipientInfos, CMS_RecipientInfo_type, +CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, +CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, +CMS_RecipientInfo_kari_set0_pkey_and_peer, +CMS_RecipientInfo_kari_set0_pkey, +CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, +CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt +\&\- CMS envelopedData RecipientInfo routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); +\& int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); +\& +\& int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, +\& ASN1_OCTET_STRING **keyid, +\& X509_NAME **issuer, +\& ASN1_INTEGER **sno); +\& int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); +\& int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); +\& int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri, +\& EVP_PKEY *pk, X509 *peer); +\& int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk); +\& int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, +\& ASN1_OCTET_STRING **pid, +\& ASN1_GENERALIZEDTIME **pdate, +\& ASN1_OBJECT **potherid, +\& ASN1_TYPE **pothertype); +\& int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, +\& const unsigned char *id, size_t idlen); +\& int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, +\& unsigned char *key, size_t keylen); +\& +\& int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); +\& int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBCMS_get0_RecipientInfos()\fR returns all the CMS_RecipientInfo +structures associated with a CMS EnvelopedData structure. +.PP +\&\fBCMS_RecipientInfo_type()\fR returns the type of CMS_RecipientInfo structure \fBri\fR. +It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, +CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. +.PP +\&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR retrieves the certificate recipient +identifier associated with a specific CMS_RecipientInfo structure \fBri\fR, which +must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in +\&\fBkeyid\fR or \fBboth\fR issuer name and serial number in \fBissuer\fR and \fBsno\fR. +.PP +\&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR compares the certificate \fBcert\fR against the +CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_TRANS. +It returns zero if the comparison is successful and non zero if not. +.PP +\&\fBCMS_RecipientInfo_set0_pkey()\fR associates the private key \fBpkey\fR with +the CMS_RecipientInfo structure \fBri\fR, which must be of type +CMS_RECIPINFO_TRANS. +.PP +\&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer()\fR associates the private key \fBpkey\fR +and peer certificate \fBpeer\fR with the CMS_RecipientInfo structure \fBri\fR, which +must be of type CMS_RECIPINFO_AGREE. +.PP +\&\fBCMS_RecipientInfo_kari_set0_pkey()\fR associates the private key \fBpkey\fR with the +CMS_RecipientInfo structure \fBri\fR, which must be of type CMS_RECIPINFO_AGREE. +.PP +\&\fBCMS_RecipientInfo_kekri_get0_id()\fR retrieves the key information from the +CMS_RecipientInfo structure \fBri\fR which must be of type CMS_RECIPINFO_KEK. Any +of the remaining parameters can be NULL if the application is not interested in +the value of a field. Where a field is optional and absent NULL will be written +to the corresponding parameter. The keyEncryptionAlgorithm field is written to +\&\fBpalg\fR, the \fBkeyIdentifier\fR field is written to \fBpid\fR, the \fBdate\fR field if +present is written to \fBpdate\fR, if the \fBother\fR field is present the components +\&\fBkeyAttrId\fR and \fBkeyAttr\fR are written to parameters \fBpotherid\fR and +\&\fBpothertype\fR. +.PP +\&\fBCMS_RecipientInfo_kekri_id_cmp()\fR compares the ID in the \fBid\fR and \fBidlen\fR +parameters against the \fBkeyIdentifier\fR CMS_RecipientInfo structure \fBri\fR, +which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is +successful and non zero if not. +.PP +\&\fBCMS_RecipientInfo_set0_key()\fR associates the symmetric key \fBkey\fR of length +\&\fBkeylen\fR with the CMS_RecipientInfo structure \fBri\fR, which must be of type +CMS_RECIPINFO_KEK. +.PP +\&\fBCMS_RecipientInfo_decrypt()\fR attempts to decrypt CMS_RecipientInfo structure +\&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure +first. +.PP +\&\fBCMS_RecipientInfo_encrypt()\fR attempts to encrypt CMS_RecipientInfo structure +\&\fBri\fR in structure \fBcms\fR. A key must have been associated with the structure +first and the content encryption key must be available: for example by a +previous call to \fBCMS_RecipientInfo_decrypt()\fR. +.SH NOTES +.IX Header "NOTES" +The main purpose of these functions is to enable an application to lookup +recipient keys using any appropriate technique when the simpler method +of \fBCMS_decrypt()\fR is not appropriate. +.PP +In typical usage and application will retrieve all CMS_RecipientInfo structures +using \fBCMS_get0_RecipientInfos()\fR and check the type of each using +\&\fBCMS_RecipientInfo_type()\fR. Depending on the type the CMS_RecipientInfo structure +can be ignored or its key identifier data retrieved using an appropriate +function. Then if the corresponding secret or private key can be obtained by +any appropriate means it can then associated with the structure and +\&\fBCMS_RecipientInfo_decrypt()\fR called. If successful \fBCMS_decrypt()\fR can be called +with a NULL key to decrypt the enveloped content. +.PP +The \fBCMS_RecipientInfo_encrypt()\fR can be used to add a new recipient to an +existing enveloped data structure. Typically an application will first decrypt +an appropriate CMS_RecipientInfo structure to make the content encrypt key +available, it will then add a new recipient using a function such as +\&\fBCMS_add1_recipient_cert()\fR and finally encrypt the content encryption key +using \fBCMS_RecipientInfo_encrypt()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_get0_RecipientInfos()\fR returns all CMS_RecipientInfo structures, or NULL if +an error occurs. +.PP +\&\fBCMS_RecipientInfo_ktri_get0_signer_id()\fR, \fBCMS_RecipientInfo_set0_pkey()\fR, +\&\fBCMS_RecipientInfo_kekri_get0_id()\fR, \fBCMS_RecipientInfo_set0_key()\fR and +\&\fBCMS_RecipientInfo_decrypt()\fR return 1 for success or 0 if an error occurs. +\&\fBCMS_RecipientInfo_encrypt()\fR return 1 for success or 0 if an error occurs. +.PP +\&\fBCMS_RecipientInfo_ktri_cert_cmp()\fR and \fBCMS_RecipientInfo_kekri_cmp()\fR return 0 +for a successful comparison and non zero otherwise. +.PP +Any error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_RecipientInfo_kari_set0_pkey_and_peer\fR and \fBCMS_RecipientInfo_kari_set0_pkey\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_get0_SignerInfos.3 b/static/netbsd/man3/CMS_get0_SignerInfos.3 new file mode 100644 index 00000000..836e2d91 --- /dev/null +++ b/static/netbsd/man3/CMS_get0_SignerInfos.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: CMS_get0_SignerInfos.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_get0_SignerInfos 3" +.TH CMS_get0_SignerInfos 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_SignerInfo_set1_signer_cert, +CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, +CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp +\&\- CMS signedData signer functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); +\& +\& int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, +\& X509_NAME **issuer, ASN1_INTEGER **sno); +\& ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si); +\& int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); +\& void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBCMS_get0_SignerInfos()\fR returns all the CMS_SignerInfo structures +associated with a CMS signedData structure. +.PP +\&\fBCMS_SignerInfo_get0_signer_id()\fR retrieves the certificate signer identifier +associated with a specific CMS_SignerInfo structure \fBsi\fR. Either the +keyidentifier will be set in \fBkeyid\fR or \fBboth\fR issuer name and serial number +in \fBissuer\fR and \fBsno\fR. +.PP +\&\fBCMS_SignerInfo_get0_signature()\fR retrieves the signature associated with +\&\fBsi\fR in a pointer to an ASN1_OCTET_STRING structure. This pointer returned +corresponds to the internal signature value if \fBsi\fR so it may be read or +modified. +.PP +\&\fBCMS_SignerInfo_cert_cmp()\fR compares the certificate \fBcert\fR against the signer +identifier \fBsi\fR. It returns zero if the comparison is successful and non zero +if not. +.PP +\&\fBCMS_SignerInfo_set1_signer_cert()\fR sets the signer\*(Aqs certificate of \fBsi\fR to +\&\fBsigner\fR. +.SH NOTES +.IX Header "NOTES" +The main purpose of these functions is to enable an application to lookup +signers certificates using any appropriate technique when the simpler method +of \fBCMS_verify()\fR is not appropriate. +.PP +In typical usage and application will retrieve all CMS_SignerInfo structures +using \fBCMS_get0_SignerInfo()\fR and retrieve the identifier information using +CMS. It will then obtain the signer certificate by some unspecified means +(or return and error if it cannot be found) and set it using +\&\fBCMS_SignerInfo_set1_signer_cert()\fR. +.PP +Once all signer certificates have been set \fBCMS_verify()\fR can be used. +.PP +Although \fBCMS_get0_SignerInfos()\fR can return NULL if an error occurs \fBor\fR if +there are no signers this is not a problem in practice because the only +error which can occur is if the \fBcms\fR structure is not of type signedData +due to application error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_get0_SignerInfos()\fR returns all CMS_SignerInfo structures, or NULL there +are no signers or an error occurs. +.PP +\&\fBCMS_SignerInfo_get0_signer_id()\fR returns 1 for success and 0 for failure. +.PP +\&\fBCMS_SignerInfo_cert_cmp()\fR returns 0 for a successful comparison and non +zero otherwise. +.PP +\&\fBCMS_SignerInfo_set1_signer_cert()\fR does not return a value. +.PP +Any error can be obtained from \fBERR_get_error\fR\|(3) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_verify\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_get0_type.3 b/static/netbsd/man3/CMS_get0_type.3 new file mode 100644 index 00000000..2544d447 --- /dev/null +++ b/static/netbsd/man3/CMS_get0_type.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: CMS_get0_type.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_get0_type 3" +.TH CMS_get0_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content \- get and set CMS content types and content +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms); +\& int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); +\& const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); +\& ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_get0_type()\fR returns the content type of a CMS_ContentInfo structure as +an ASN1_OBJECT pointer. An application can then decide how to process the +CMS_ContentInfo structure based on this value. +.PP +\&\fBCMS_set1_eContentType()\fR sets the embedded content type of a CMS_ContentInfo +structure. It should be called with CMS functions (such as \fBCMS_sign\fR\|(3), +\&\fBCMS_encrypt\fR\|(3)) +with the \fBCMS_PARTIAL\fR +flag and \fBbefore\fR the structure is finalised, otherwise the results are +undefined. +.PP +ASN1_OBJECT *\fBCMS_get0_eContentType()\fR returns a pointer to the embedded +content type. +.PP +\&\fBCMS_get0_content()\fR returns a pointer to the \fBASN1_OCTET_STRING\fR pointer +containing the embedded content. +.SH NOTES +.IX Header "NOTES" +As the \fB0\fR implies \fBCMS_get0_type()\fR, \fBCMS_get0_eContentType()\fR and +\&\fBCMS_get0_content()\fR return internal pointers which should \fBnot\fR be freed up. +\&\fBCMS_set1_eContentType()\fR copies the supplied OID and it \fBshould\fR be freed up +after use. +.PP +The \fBASN1_OBJECT\fR values returned can be converted to an integer \fBNID\fR value +using \fBOBJ_obj2nid()\fR. For the currently supported content types the following +values are returned: +.PP +.Vb 6 +\& NID_pkcs7_data +\& NID_pkcs7_signed +\& NID_pkcs7_digest +\& NID_id_smime_ct_compressedData: +\& NID_pkcs7_encrypted +\& NID_pkcs7_enveloped +.Ve +.PP +The return value of \fBCMS_get0_content()\fR is a pointer to the \fBASN1_OCTET_STRING\fR +content pointer. That means that for example: +.PP +.Vb 1 +\& ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); +.Ve +.PP +\&\fB*pconf\fR could be NULL if there is no embedded content. Applications can +access, modify or create the embedded content in a \fBCMS_ContentInfo\fR structure +using this function. Applications usually will not need to modify the +embedded content as it is normally set by higher level functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_get0_type()\fR and \fBCMS_get0_eContentType()\fR return an ASN1_OBJECT structure. +.PP +\&\fBCMS_set1_eContentType()\fR returns 1 for success or 0 if an error occurred. The +error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_get1_ReceiptRequest.3 b/static/netbsd/man3/CMS_get1_ReceiptRequest.3 new file mode 100644 index 00000000..faf841cb --- /dev/null +++ b/static/netbsd/man3/CMS_get1_ReceiptRequest.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: CMS_get1_ReceiptRequest.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_get1_ReceiptRequest 3" +.TH CMS_get1_ReceiptRequest 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_ReceiptRequest_create0_ex, CMS_ReceiptRequest_create0, +CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values +\&\- CMS signed receipt request functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ReceiptRequest *CMS_ReceiptRequest_create0_ex( +\& unsigned char *id, int idlen, int allorfirst, +\& STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo, +\& OSSL_LIB_CTX *libctx); +\& CMS_ReceiptRequest *CMS_ReceiptRequest_create0( +\& unsigned char *id, int idlen, int allorfirst, +\& STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); +\& int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); +\& int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); +\& void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, +\& int *pallorfirst, +\& STACK_OF(GENERAL_NAMES) **plist, +\& STACK_OF(GENERAL_NAMES) **prto); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_ReceiptRequest_create0_ex()\fR creates a signed receipt request +structure. The \fBsignedContentIdentifier\fR field is set using \fIid\fR and \fIidlen\fR, +or it is set to 32 bytes of pseudo random data if \fIid\fR is NULL. +If \fIreceiptList\fR is NULL the allOrFirstTier option in \fIreceiptsFrom\fR is used +and set to the value of the \fIallorfirst\fR parameter. If \fIreceiptList\fR is not +NULL the \fIreceiptList\fR option in \fIreceiptsFrom\fR is used. The \fIreceiptsTo\fR +parameter specifies the \fIreceiptsTo\fR field value. The library context \fIlibctx\fR +is used to find the public random generator. +.PP +\&\fBCMS_ReceiptRequest_create0()\fR is similar to +\&\fBCMS_ReceiptRequest_create0_ex()\fR but uses default values of NULL for the +library context \fIlibctx\fR. +.PP +The \fBCMS_add1_ReceiptRequest()\fR function adds a signed receipt request \fBrr\fR +to SignerInfo structure \fBsi\fR. +.PP +int \fBCMS_get1_ReceiptRequest()\fR looks for a signed receipt request in \fBsi\fR, if +any is found it is decoded and written to \fBprr\fR. +.PP +\&\fBCMS_ReceiptRequest_get0_values()\fR retrieves the values of a receipt request. +The signedContentIdentifier is copied to \fBpcid\fR. If the \fBallOrFirstTier\fR +option of \fBreceiptsFrom\fR is used its value is copied to \fBpallorfirst\fR +otherwise the \fBreceiptList\fR field is copied to \fBplist\fR. The \fBreceiptsTo\fR +parameter is copied to \fBprto\fR. +.SH NOTES +.IX Header "NOTES" +For more details of the meaning of the fields see RFC2634. +.PP +The contents of a signed receipt should only be considered meaningful if the +corresponding CMS_ContentInfo structure can be successfully verified using +\&\fBCMS_verify()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_ReceiptRequest_create0_ex()\fR and \fBCMS_ReceiptRequest_create0()\fR return +a signed receipt request structure or NULL if an error occurred. +.PP +\&\fBCMS_add1_ReceiptRequest()\fR returns 1 for success or 0 if an error occurred. +.PP +\&\fBCMS_get1_ReceiptRequest()\fR returns 1 is a signed receipt request is found and +decoded. It returns 0 if a signed receipt request is not present and \-1 if +it is present but malformed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_sign_receipt\fR\|(3), \fBCMS_verify\fR\|(3) +\&\fBCMS_verify_receipt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBCMS_ReceiptRequest_create0_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_sign.3 b/static/netbsd/man3/CMS_sign.3 new file mode 100644 index 00000000..cd21d8c4 --- /dev/null +++ b/static/netbsd/man3/CMS_sign.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: CMS_sign.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_sign 3" +.TH CMS_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_sign, CMS_sign_ex \- create a CMS SignedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey, +\& STACK_OF(X509) *certs, BIO *data, +\& unsigned int flags, OSSL_LIB_CTX *ctx, +\& const char *propq); +\& CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, +\& BIO *data, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_sign_ex()\fR creates and returns a CMS SignedData structure. +\&\fIsigncert\fR is the certificate to sign with, \fIpkey\fR is the corresponding +private key. \fIcerts\fR is an optional additional set of certificates to include +in the CMS structure (for example any intermediate CAs in the chain). The +library context \fIlibctx\fR and the property query \fIpropq\fR are used when +retrieving algorithms from providers. Any or all of these parameters can be +\&\fBNULL\fR, see \fBNOTES\fR below. +.PP +The data to be signed is read from BIO \fBdata\fR. +.PP +\&\fBflags\fR is an optional set of flags. +.PP +\&\fBCMS_sign()\fR is similar to \fBCMS_sign_ex()\fR but uses default values of NULL +for the library context \fIlibctx\fR and the property query \fIpropq\fR. +.SH NOTES +.IX Header "NOTES" +Any of the following flags (ored together) can be passed in the \fBflags\fR +parameter. +.PP +Many S/MIME clients expect the signed content to include valid MIME headers. If +the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are prepended +to the data. +.PP +If \fBCMS_NOCERTS\fR is set the signer\*(Aqs certificate will not be included in the +CMS_ContentInfo structure, the signer\*(Aqs certificate must still be supplied in +the \fBsigncert\fR parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. +.PP +The data being signed is included in the CMS_ContentInfo structure, unless +\&\fBCMS_DETACHED\fR is set in which case it is omitted. This is used for +CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed +messages for example. +.PP +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if \fBCMS_BINARY\fR is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. +.PP +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If \fBCMS_NOATTR\fR is set then no signedAttributes +will be used at all. If \fBCMS_NOSMIMECAP\fR is set then the SMIMECapabilities +will be omitted. If \fBCMS_NO_SIGNING_TIME\fR is set then the signing time will be +omitted. +.PP +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411\-94, Gost 28147\-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: +for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. +.PP +OpenSSL will by default identify signing certificates using issuer name +and serial number. If \fBCMS_USE_KEYID\fR is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. +.PP +If the flags \fBCMS_STREAM\fR is set then the returned \fBCMS_ContentInfo\fR +structure is just initialized ready to perform the signing operation. The +signing is however \fBnot\fR performed and the data to be signed is not read from +the \fBdata\fR parameter. Signing is deferred until after the data has been +written. In this way data can be signed in a single pass. +.PP +If the \fBCMS_PARTIAL\fR flag is set a partial \fBCMS_ContentInfo\fR structure is +output to which additional signers and capabilities can be added before +finalization. +.PP +If the flag \fBCMS_STREAM\fR is set the returned \fBCMS_ContentInfo\fR structure is +\&\fBnot\fR complete and outputting its contents via a function that does not +properly finalize the \fBCMS_ContentInfo\fR structure will give unpredictable +results. +.PP +Several functions including \fBSMIME_write_CMS()\fR, \fBi2d_CMS_bio_stream()\fR, +\&\fBPEM_write_bio_CMS_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 \fBBIO\fR directly using +\&\fBBIO_new_CMS()\fR. +.PP +If a signer is specified it will use the default digest for the signing +algorithm. This is \fBSHA256\fR for both RSA and DSA keys. +.PP +If \fBsigncert\fR and \fBpkey\fR are NULL then a certificates only CMS structure is +output. +.PP +The function \fBCMS_sign()\fR is a basic CMS signing function whose output will be +suitable for many purposes. For finer control of the output format the +\&\fBcerts\fR, \fBsigncert\fR and \fBpkey\fR parameters can all be \fBNULL\fR and the +\&\fBCMS_PARTIAL\fR flag set. Then one or more signers can be added using the +function \fBCMS_add1_signer()\fR, non default digests can be used and custom +attributes added. \fBCMS_final()\fR must then be called to finalize the +structure if streaming is not enabled. +.SH BUGS +.IX Header "BUGS" +Some attributes such as counter signatures are not supported. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_sign_ex()\fR and \fBCMS_sign()\fR return either a valid CMS_ContentInfo +structure or NULL if an error occurred. The error can be obtained from +\&\fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCMS_STREAM\fR flag is only supported for detached data in OpenSSL 0.9.8, +it is supported for embedded data in OpenSSL 1.0.0 and later. +.PP +The \fBCMS_sign_ex()\fR method was added in OpenSSL 3.0. +.PP +Since OpenSSL 3.2, \fBCMS_sign_ex()\fR and \fBCMS_sign()\fR ignore any duplicate +certificates in their \fIcerts\fR argument and no longer throw an error for them. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_sign_receipt.3 b/static/netbsd/man3/CMS_sign_receipt.3 new file mode 100644 index 00000000..fceb216b --- /dev/null +++ b/static/netbsd/man3/CMS_sign_receipt.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: CMS_sign_receipt.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_sign_receipt 3" +.TH CMS_sign_receipt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_sign_receipt \- create a CMS signed receipt +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, +\& EVP_PKEY *pkey, STACK_OF(X509) *certs, +\& unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_sign_receipt()\fR creates and returns a CMS signed receipt structure. \fBsi\fR is +the \fBCMS_SignerInfo\fR structure containing the signed receipt request. +\&\fBsigncert\fR is the certificate to sign with, \fBpkey\fR is the corresponding +private key. \fBcerts\fR is an optional additional set of certificates to include +in the CMS structure (for example any intermediate CAs in the chain). +.PP +\&\fBflags\fR is an optional set of flags. +.SH NOTES +.IX Header "NOTES" +This functions behaves in a similar way to \fBCMS_sign()\fR except the flag values +\&\fBCMS_DETACHED\fR, \fBCMS_BINARY\fR, \fBCMS_NOATTR\fR, \fBCMS_TEXT\fR and \fBCMS_STREAM\fR +are not supported since they do not make sense in the context of signed +receipts. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_sign_receipt()\fR returns either a valid CMS_ContentInfo structure or NULL if +an error occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBCMS_verify_receipt\fR\|(3), +\&\fBCMS_sign\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_signed_get_attr.3 b/static/netbsd/man3/CMS_signed_get_attr.3 new file mode 100644 index 00000000..13e7b5a9 --- /dev/null +++ b/static/netbsd/man3/CMS_signed_get_attr.3 @@ -0,0 +1,265 @@ +.\" $NetBSD: CMS_signed_get_attr.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_signed_get_attr 3" +.TH CMS_signed_get_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_signed_get_attr_count, +CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr, +CMS_signed_delete_attr, +CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ, +CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt, +CMS_signed_get0_data_by_OBJ, +CMS_unsigned_get_attr_count, +CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, +CMS_unsigned_get_attr, CMS_unsigned_delete_attr, +CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ, +CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt, +CMS_unsigned_get0_data_by_OBJ +\&\- CMS signed and unsigned attribute functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_signed_get_attr_count(const CMS_SignerInfo *si); +\& int CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid, +\& int lastpos); +\& int CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj, +\& int lastpos); +\& X509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc); +\& X509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc); +\& int CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); +\& int CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si, +\& const ASN1_OBJECT *obj, int type, +\& const void *bytes, int len); +\& int CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si, +\& int nid, int type, +\& const void *bytes, int len); +\& int CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si, +\& const char *attrname, int type, +\& const void *bytes, int len); +\& void *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si, +\& const ASN1_OBJECT *oid, +\& int lastpos, int type); +\& +\& int CMS_unsigned_get_attr_count(const CMS_SignerInfo *si); +\& int CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid, +\& int lastpos); +\& int CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si, +\& const ASN1_OBJECT *obj, int lastpos); +\& X509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc); +\& X509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc); +\& int CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr); +\& int CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si, +\& const ASN1_OBJECT *obj, int type, +\& const void *bytes, int len); +\& int CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si, +\& int nid, int type, +\& const void *bytes, int len); +\& int CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si, +\& const char *attrname, int type, +\& const void *bytes, int len); +\& void *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid, +\& int lastpos, int type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +CMS_signerInfo contains separate attribute lists for signed and unsigned +attributes. Each \fBCMS_signed_XXX()\fR function is used for signed attributes, and +each \fBCMS_unsigned_XXX()\fR function is used for unsigned attributes. +Since the \fBCMS_unsigned_XXX()\fR functions work in the same way as the +\&\fBCMS_signed_XXX()\fR equivalents, only the \fBCMS_signed_XXX()\fR functions are +described below. +.PP +\&\fBCMS_signed_get_attr_by_OBJ()\fR finds the location of the first matching object +\&\fIobj\fR in the SignerInfo\*(Aqs \fIsi\fR signed attribute list. The search starts at the +position after \fIlastpos\fR. If the returned value is positive then it can be used +on the next call to \fBCMS_signed_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in +order to iterate through the remaining attributes. \fIlastpos\fR can be set to any +negative value on the first call, in order to start searching from the start of +the signed attribute list. +.PP +\&\fBCMS_signed_get_attr_by_NID()\fR is similar to \fBCMS_signed_get_attr_by_OBJ()\fR except +that it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBCMS_signed_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the +\&\fIsi\fR signed attribute list. \fIloc\fR should be in the range from 0 to +\&\fBCMS_signed_get_attr_count()\fR \- 1. +.PP +\&\fBCMS_signed_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in +the \fIsi\fR signed attribute list. An error occurs if the \fIsi\fR attribute list +is NULL. +.PP +\&\fBCMS_signed_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR object +to the \fIsi\fR signed attribute list. A new signed attribute list is created if +required. An error occurs if \fIattr\fR is NULL. +.PP +\&\fBCMS_signed_add1_attr_by_OBJ()\fR creates a new signed \fBX509_ATTRIBUTE\fR using +\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new +\&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it +to the \fIkey\fR object\*(Aqs attribute list. +.PP +\&\fBCMS_signed_add1_attr_by_NID()\fR is similar to \fBCMS_signed_add1_attr_by_OBJ()\fR except +that it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBCMS_signed_add1_attr_by_txt()\fR is similar to \fBCMS_signed_add1_attr_by_OBJ()\fR +except that it passes a name \fIattrname\fR associated with the object. +See for a list of SN_* names. +.PP +\&\fBCMS_signed_get0_data_by_OBJ()\fR finds the first attribute in a \fIsi\fR signed +attributes list that matches the \fIobj\fR starting at index \fIlastpos\fR +and returns the data retrieved from the found attributes first \fBASN1_TYPE\fR +object. An error will occur if the attribute type \fItype\fR does not match the +type of the \fBASN1_TYPE\fR object OR if \fItype\fR is either \fBV_ASN1_BOOLEAN\fR or +\&\fBV_ASN1_NULL\fR OR the attribute is not found. +If \fIlastpos\fR is less than \-1 then an error will occur if there are multiple +objects in the signed attribute list that match \fIobj\fR. +If \fIlastpos\fR is less than \-2 then an error will occur if there is more than +one \fBASN1_TYPE\fR object in the found signed attribute. +.PP +Refer to \fBX509_ATTRIBUTE\fR\|(3) for information related to attributes. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBCMS_unsigned_XXX()\fR functions return values are similar to those of the +equivalent \fBCMS_signed_XXX()\fR functions. +.PP +\&\fBCMS_signed_get_attr_count()\fR returns the number of signed attributes in the +SignerInfo \fIsi\fR, or \-1 if the signed attribute list is NULL. +.PP +\&\fBCMS_signed_get_attr_by_OBJ()\fR returns \-1 if either the signed attribute list of +\&\fIsi\fR is empty OR if \fIobj\fR is not found, otherwise it returns the location of +the \fIobj\fR in the SignerInfo\*(Aqs \fIsi\fR signed attribute list. +.PP +\&\fBCMS_signed_get_attr_by_NID()\fR is similar to \fBCMS_signed_get_attr_by_OBJ()\fR except +that it returns \-2 if the \fInid\fR is not known by OpenSSL. +.PP +\&\fBCMS_signed_get_attr()\fR returns either a signed \fBX509_ATTRIBUTE\fR or NULL on error. +.PP +\&\fBCMS_signed_delete_attr()\fR returns either the removed signed \fBX509_ATTRIBUTE\fR or +NULL if there is a error. +.PP +\&\fBCMS_signed_add1_attr()\fR, \fBCMS_signed_add1_attr_by_OBJ()\fR, +\&\fBCMS_signed_add1_attr_by_NID()\fR, \fBCMS_signed_add1_attr_by_txt()\fR, +return 1 on success or 0 on error. +.PP +\&\fBCMS_signed_get0_data_by_OBJ()\fR returns the data retrieved from the found +signed attributes first \fBASN1_TYPE\fR object, or NULL if an error occurs. +.SH NOTES +.IX Header "NOTES" +Some attributes are added automatically during the signing process. +.PP +Calling \fBCMS_SignerInfo_sign()\fR adds the NID_pkcs9_signingTime signed +attribute. +.PP +Calling \fBCMS_final()\fR, \fBCMS_final_digest()\fR or \fBCMS_dataFinal()\fR adds the +NID_pkcs9_messageDigest signed attribute. +.PP +The NID_pkcs9_contentType signed attribute is always added if the +NID_pkcs9_signingTime attribute is added. +.PP +Calling \fBCMS_sign_ex()\fR, \fBCMS_sign_receipt()\fR or \fBCMS_add1_signer()\fR may add +attributes depending on the flags parameter. See \fBCMS_add1_signer\fR\|(3) for +more information. +.PP +OpenSSL applies special rules for the following attribute NIDs: +.IP "CMS Signed Attributes" 4 +.IX Item "CMS Signed Attributes" +NID_pkcs9_contentType +NID_pkcs9_messageDigest +NID_pkcs9_signingTime +.IP "ESS Signed Attributes" 4 +.IX Item "ESS Signed Attributes" +NID_id_smime_aa_signingCertificate +NID_id_smime_aa_signingCertificateV2 +NID_id_smime_aa_receiptRequest +.IP "CMS Unsigned Attributes" 4 +.IX Item "CMS Unsigned Attributes" +NID_pkcs9_countersignature +.PP +\&\fBCMS_signed_add1_attr()\fR, \fBCMS_signed_add1_attr_by_OBJ()\fR, +\&\fBCMS_signed_add1_attr_by_NID()\fR, \fBCMS_signed_add1_attr_by_txt()\fR +and the equivalent \fBCMS_unsigned_add1_attrXXX()\fR functions allow +duplicate attributes to be added. The attribute rules are not checked +during these function calls, and are deferred until the sign or verify process +(i.e. during calls to any of \fBCMS_sign_ex()\fR, \fBCMS_sign()\fR, \fBCMS_sign_receipt()\fR, +\&\fBCMS_add1_signer()\fR, \fBCMS_Final()\fR, \fBCMS_dataFinal()\fR, \fBCMS_final_digest()\fR, +\&\fBCMS_verify()\fR, \fBCMS_verify_receipt()\fR or \fBCMS_SignedData_verify()\fR). +.PP +For CMS attribute rules see RFC 5652 Section 11. +For ESS attribute rules see RFC 2634 Section 1.3.4 and RFC 5035 Section 5.4. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_ATTRIBUTE\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_uncompress.3 b/static/netbsd/man3/CMS_uncompress.3 new file mode 100644 index 00000000..90bd2a43 --- /dev/null +++ b/static/netbsd/man3/CMS_uncompress.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: CMS_uncompress.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_uncompress 3" +.TH CMS_uncompress 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_uncompress \- uncompress a CMS CompressedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_uncompress()\fR extracts and uncompresses the content from a CMS +CompressedData structure \fBcms\fR. \fBdata\fR is a BIO to write the content to and +\&\fBflags\fR is an optional set of flags. +.PP +The \fBdcont\fR parameter is used in the rare case where the compressed content +is detached. It will normally be set to NULL. +.SH NOTES +.IX Header "NOTES" +The only currently supported compression algorithm is zlib: if the structure +indicates the use of any other algorithm an error is returned. +.PP +If zlib support is not compiled into OpenSSL then \fBCMS_uncompress()\fR will always +return an error. +.PP +The following flags can be passed in the \fBflags\fR parameter. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are deleted +from the content. If the content is not of type \fBtext/plain\fR then an error is +returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_uncompress()\fR returns either 1 for success or 0 for failure. The error can +be obtained from \fBERR_get_error\fR\|(3) +.SH BUGS +.IX Header "BUGS" +The lack of single pass processing and the need to hold all data in memory as +mentioned in \fBCMS_verify()\fR also applies to \fBCMS_decompress()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_compress\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_verify.3 b/static/netbsd/man3/CMS_verify.3 new file mode 100644 index 00000000..65c4981a --- /dev/null +++ b/static/netbsd/man3/CMS_verify.3 @@ -0,0 +1,227 @@ +.\" $NetBSD: CMS_verify.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_verify 3" +.TH CMS_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_verify, CMS_SignedData_verify, +CMS_get0_signers \- verify a CMS SignedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, +\& BIO *detached_data, BIO *out, unsigned int flags); +\& BIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data, +\& STACK_OF(X509) *scerts, X509_STORE *store, +\& STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls, +\& unsigned int flags, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_verify()\fR is very similar to \fBPKCS7_verify\fR\|(3). It verifies a +\&\fBCMS SignedData\fR structure contained in a structure of type \fBCMS_ContentInfo\fR. +\&\fIcms\fR points to the \fBCMS_ContentInfo\fR structure to verify. +The optional \fIcerts\fR parameter refers to a set of certificates +in which to search for signing certificates. +It is also used +as a source of untrusted intermediate CA certificates for chain building. +\&\fIcms\fR may contain extra untrusted CA certificates that may be used for +chain building as well as CRLs that may be used for certificate validation. +\&\fIstore\fR may be NULL or point to +the trusted certificate store to use for chain verification. +\&\fIdetached_data\fR refers to the signed data if the content is detached from \fIcms\fR. +Otherwise \fIdetached_data\fR should be NULL and the signed data must be in \fIcms\fR. +The content is written to the BIO \fIout\fR unless it is NULL. +\&\fIflags\fR is an optional set of flags, which can be used to modify the operation. +.PP +\&\fBCMS_SignedData_verify()\fR is like \fBCMS_verify()\fR except that +it operates on \fBCMS SignedData\fR input in the \fIsd\fR argument, +it has some additional parameters described next, +and on success it returns the verified content as a memory BIO. +The optional \fIextra\fR parameter may be used to provide untrusted CA +certificates that may be helpful for chain building in certificate validation. +This list of certificates must not contain duplicates. +The optional \fIcrls\fR parameter may be used to provide extra CRLs. +Also the list of CRLs must not contain duplicates. +The optional parameters library context \fIlibctx\fR and property query \fIpropq\fR +are used when retrieving algorithms from providers. +.PP +\&\fBCMS_get0_signers()\fR retrieves the signing certificate(s) from \fIcms\fR; it may only +be called after a successful \fBCMS_verify()\fR or \fBCMS_SignedData_verify()\fR operation. +.SH "VERIFY PROCESS" +.IX Header "VERIFY PROCESS" +Normally the verify process proceeds as follows. +.PP +Initially some sanity checks are performed on \fIcms\fR. The type of \fIcms\fR must +be SignedData. There must be at least one signature on the data and if +the content is detached \fIdetached_data\fR cannot be NULL. +.PP +An attempt is made to locate all the signing certificate(s), first looking in +the \fIcerts\fR parameter (if it is not NULL) and then looking in any +certificates contained in the \fIcms\fR structure unless \fBCMS_NOINTERN\fR is set. +If any signing certificate cannot be located the operation fails. +.PP +Each signing certificate is chain verified using the \fIsmimesign\fR purpose and +using the trusted certificate store \fIstore\fR if supplied. +Any internal certificates in the message, which may have been added using +\&\fBCMS_add1_cert\fR\|(3), are used as untrusted CAs. +If CRL checking is enabled in \fIstore\fR and \fBCMS_NOCRL\fR is not set, +any internal CRLs, which may have been added using \fBCMS_add1_crl\fR\|(3), +are used in addition to attempting to look them up in \fIstore\fR. +If \fIstore\fR is not NULL and any chain verify fails an error code is returned. +.PP +Finally the signed content is read (and written to \fIout\fR unless it is NULL) +and the signature is checked. +.PP +If all signatures verify correctly then the function is successful. +.PP +Any of the following flags (ored together) can be passed in the \fIflags\fR +parameter to change the default verify behaviour. +.PP +If \fBCMS_NOINTERN\fR is set the certificates in the message itself are not +searched when locating the signing certificate(s). +This means that all the signing certificates must be in the \fIcerts\fR parameter. +.PP +If \fBCMS_NOCRL\fR is set and CRL checking is enabled in \fIstore\fR then any +CRLs in the message itself and provided via the \fIcrls\fR parameter are ignored. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted +from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is +returned. +.PP +If \fBCMS_NO_SIGNER_CERT_VERIFY\fR is set the signing certificates are not +chain verified, unless \fBCMS_CADES\fR flag is also set. +.PP +If \fBCMS_NO_ATTR_VERIFY\fR is set the signed attributes signature is not +verified, unless CMS_CADES flag is also set. +.PP +If \fBCMS_CADES\fR is set, each signer certificate is checked against the +ESS signingCertificate or ESS signingCertificateV2 extension +that is required in the signed attributes of the signature. +.PP +If \fBCMS_NO_CONTENT_VERIFY\fR is set then the content digest is not checked. +.SH NOTES +.IX Header "NOTES" +One application of \fBCMS_NOINTERN\fR is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the \fIcerts\fR parameter. In this case if the signer certificate is not one +of the certificates supplied in \fIcerts\fR then the verify will fail because the +signer cannot be found. +.PP +In some cases the standard techniques for looking up and validating +certificates are not appropriate: for example an application may wish to +lookup certificates in a database or perform customised verification. This +can be achieved by setting and verifying the signer certificates manually +using the signed data utility functions. +.PP +Care should be taken when modifying the default verify behaviour, for example +setting \fBCMS_NO_CONTENT_VERIFY\fR will totally disable all content verification +and any modified content will be considered valid. This combination is however +useful if one merely wishes to write the content to \fIout\fR and its validity +is not considered important. +.PP +Chain verification should arguably be performed using the signing time rather +than the current time. However, since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_verify()\fR returns 1 for a successful verification and 0 if an error occurred. +.PP +\&\fBCMS_SignedData_verify()\fR returns a memory BIO containing the verified content, +or NULL on error. +.PP +\&\fBCMS_get0_signers()\fR returns all signers or NULL if an error occurred. +.PP +The error can be obtained from \fBERR_get_error\fR\|(3). +.SH BUGS +.IX Header "BUGS" +The trusted certificate store is not searched for the signing certificate. +This is primarily due to the inadequacies of the current \fBX509_STORE\fR +functionality. +.PP +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS7_verify\fR\|(3), \fBCMS_add1_cert\fR\|(3), \fBCMS_add1_crl\fR\|(3), +\&\fBOSSL_ESS_check_signing_certs\fR\|(3), +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCMS_SignedData_verify()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CMS_verify_receipt.3 b/static/netbsd/man3/CMS_verify_receipt.3 new file mode 100644 index 00000000..673bf7fb --- /dev/null +++ b/static/netbsd/man3/CMS_verify_receipt.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: CMS_verify_receipt.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CMS_verify_receipt 3" +.TH CMS_verify_receipt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CMS_verify_receipt \- verify a CMS signed receipt +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, +\& STACK_OF(X509) *certs, X509_STORE *store, +\& unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCMS_verify_receipt()\fR verifies a CMS signed receipt. \fBrcms\fR is the signed +receipt to verify. \fBocms\fR is the original SignedData structure containing the +receipt request. \fBcerts\fR is a set of certificates in which to search for the +signing certificate. \fBstore\fR is a trusted certificate store (used for chain +verification). +.PP +\&\fBflags\fR is an optional set of flags, which can be used to modify the verify +operation. +.SH NOTES +.IX Header "NOTES" +This functions behaves in a similar way to \fBCMS_verify()\fR except the flag values +\&\fBCMS_DETACHED\fR, \fBCMS_BINARY\fR, \fBCMS_TEXT\fR and \fBCMS_STREAM\fR are not +supported since they do not make sense in the context of signed receipts. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCMS_verify_receipt()\fR returns 1 for a successful verification and zero if an +error occurred. +.PP +The error can be obtained from \fBERR_get_error\fR\|(3) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBCMS_sign_receipt\fR\|(3), +\&\fBCMS_verify\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/COMP_CTX_new.3 b/static/netbsd/man3/COMP_CTX_new.3 new file mode 100644 index 00000000..558adde9 --- /dev/null +++ b/static/netbsd/man3/COMP_CTX_new.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: COMP_CTX_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "COMP_CTX_new 3" +.TH COMP_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +COMP_CTX_new, +COMP_CTX_get_method, +COMP_CTX_get_type, +COMP_get_type, +COMP_get_name, +COMP_CTX_free, +COMP_compress_block, +COMP_expand_block, +COMP_zlib, +COMP_zlib_oneshot, +COMP_brotli, +COMP_brotli_oneshot, +COMP_zstd, +COMP_zstd_oneshot, +BIO_f_zlib, +BIO_f_brotli, +BIO_f_zstd +\&\- Compression support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& COMP_CTX *COMP_CTX_new(COMP_METHOD *meth); +\& void COMP_CTX_free(COMP_CTX *ctx); +\& const COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx); +\& int COMP_CTX_get_type(const COMP_CTX* comp); +\& int COMP_get_type(const COMP_METHOD *meth); +\& const char *COMP_get_name(const COMP_METHOD *meth); +\& +\& int COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen, +\& unsigned char *in, int ilen); +\& int COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen, +\& unsigned char *in, int ilen); +\& +\& COMP_METHOD *COMP_zlib(void); +\& COMP_METHOD *COMP_zlib_oneshot(void); +\& COMP_METHOD *COMP_brotli(void); +\& COMP_METHOD *COMP_brotli_oneshot(void); +\& COMP_METHOD *COMP_zstd(void); +\& COMP_METHOD *COMP_zstd_oneshot(void); +\& +\& const BIO_METHOD *BIO_f_zlib(void); +\& const BIO_METHOD *BIO_f_brotli(void); +\& const BIO_METHOD *BIO_f_zstd(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions provide compression support for OpenSSL. Compression is used within +the OpenSSL library to support TLS record and certificate compression. +.PP +\&\fBCOMP_CTX_new()\fR is used to create a new \fBCOMP_CTX\fR structure used to compress data. +.PP +\&\fBCOMP_CTX_free()\fR is used to free the returned \fBCOMP_CTX\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBCOMP_CTX_get_method()\fR returns the \fBCOMP_METHOD\fR of the given \fIctx\fR. +.PP +\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return the NID for the \fBCOMP_CTX\fR and +\&\fBCOMP_METHOD\fR, respectively. \fBCOMP_get_name()\fR returns the name of the algorithm +of the given \fBCOMP_METHOD\fR. +.PP +\&\fBCOMP_compress_block()\fR compresses b bytes from the buffer \fIin\fR into the +buffer b of size \fIolen\fR using the algorithm specified by \fIctx\fR. +.PP +\&\fBCOMP_expand_block()\fR expands \fIilen\fR bytes from the buffer \fIin\fR into the +buffer \fIout\fR of size \fIolen\fR using the algorithm specified by \fIctx\fR. +.PP +Methods (\fBCOMP_METHOD\fR) may be specified by one of these functions. These functions +will be available even if their corresponding compression algorithm is not configured +into the OpenSSL library. In such a case, NULL will be returned. +.IP \(bu 4 +\&\fBCOMP_zlib()\fR returns a \fBCOMP_METHOD\fR for stream\-based ZLIB compression. +.IP \(bu 4 +\&\fBCOMP_zlib_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot ZLIB compression. +.IP \(bu 4 +\&\fBCOMP_brotli()\fR returns a \fBCOMP_METHOD\fR for stream\-based Brotli compression. +.IP \(bu 4 +\&\fBCOMP_brotli_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot Brotli compression. +.IP \(bu 4 +\&\fBCOMP_zstd()\fR returns a \fBCOMP_METHOD\fR for stream\-based Zstandard compression. +.IP \(bu 4 +\&\fBCOMP_zstd_oneshot()\fR returns a \fBCOMP_METHOD\fR for one\-shot Zstandard compression. +.PP +\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR \fBBIO_f_zstd()\fR each return a \fBBIO_METHOD\fR that may be used to +create a \fBBIO\fR via \fBBIO_new\|(3)\fR to read and write compressed files or streams. +The functions are only available if the corresponding algorithm is compiled into +the OpenSSL library. NULL may be returned if the algorithm fails to load dynamically. +.SH NOTES +.IX Header "NOTES" +While compressing non\-compressible data, the output may be larger than the +input. Care should be taken to size output buffers appropriate for both +compression and expansion. +.PP +Compression support and compression algorithms must be enabled and built into +the library before use. Refer to the INSTALL.md file when configuring OpenSSL. +.PP +ZLIB may be found at +.PP +Brotli may be found at . +.PP +Zstandard may be found at . +.PP +Compression of SSL/TLS records is not recommended, as it has been +shown to lead to the CRIME attack . +It is disabled by default, and may be enabled by clearing the +SSL_OP_NO_COMPRESSION option and setting the security level as appropriate. +See the documentation for the \fBSSL_CTX_set_options\fR\|(3) and +\&\fBSSL_set_options\fR\|(3) functions. +.PP +Compression is also used to support certificate compression as described +in RFC8879 . +It may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and +SSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the +\&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions. +.PP +\&\fBCOMP_zlib()\fR, \fBCOMP_brotli()\fR and \fBCOMP_zstd()\fR are stream\-based compression methods. +Internal state (including compression dictionary) is maintained between calls. +If an error is returned, the stream is corrupted, and should be closed. +.PP +\&\fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli_oneshot()\fR and \fBCOMP_zstd_oneshot()\fR are not stream\-based. These +methods do not maintain state between calls. An error in one call does not affect +future calls. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCOMP_CTX_new()\fR returns a \fBCOMP_CTX\fR on success, or NULL on failure. +.PP +\&\fBCOMP_CTX_get_method()\fR, \fBCOMP_zlib()\fR, \fBCOMP_zlib_oneshot()\fR, \fBCOMP_brotli()\fR, \fBCOMP_brotli_oneshot()\fR, +\&\fBCOMP_zstd()\fR, and \fBCOMP_zstd_oneshot()\fR return a \fBCOMP_METHOD\fR on success, +or NULL on failure. +.PP +\&\fBCOMP_CTX_get_type()\fR and \fBCOMP_get_type()\fR return a NID value. On failure, +NID_undef is returned. +.PP +\&\fBCOMP_compress_block()\fR and \fBCOMP_expand_block()\fR return the number of +bytes stored in the output buffer \fIout\fR. This may be 0. On failure, +\&\-1 is returned. +.PP +\&\fBCOMP_get_name()\fR returns a \fBconst char *\fR that must not be freed +on success, or NULL on failure. +.PP +\&\fBBIO_f_zlib()\fR, \fBBIO_f_brotli()\fR and \fBBIO_f_zstd()\fR return NULL on error, and +a \fBBIO_METHOD\fR on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_new\fR\|(3), \fBSSL_CTX_set_options\fR\|(3), \fBSSL_set_options\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Brotli and Zstandard functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CONF_modules_free.3 b/static/netbsd/man3/CONF_modules_free.3 new file mode 100644 index 00000000..04130c3d --- /dev/null +++ b/static/netbsd/man3/CONF_modules_free.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: CONF_modules_free.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CONF_modules_free 3" +.TH CONF_modules_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CONF_modules_free, CONF_modules_finish, CONF_modules_unload \- +OpenSSL configuration cleanup functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void CONF_modules_finish(void); +\& void CONF_modules_unload(int all); +.Ve +.PP +The following functions have been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void CONF_modules_free(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCONF_modules_free()\fR closes down and frees up all memory allocated by all +configuration modules. Normally, in versions of OpenSSL prior to 1.1.0, +applications called +\&\fBCONF_modules_free()\fR at exit to tidy up any configuration performed. +.PP +\&\fBCONF_modules_finish()\fR calls each configuration modules \fBfinish\fR handler +to free up any configuration that module may have performed. +.PP +\&\fBCONF_modules_unload()\fR finishes and unloads configuration modules. If +\&\fBall\fR is set to \fB0\fR only modules loaded from DSOs will be unloads. If +\&\fBall\fR is \fB1\fR all modules, including built\-in modules will be unloaded. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +None of the functions return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBconfig\fR\|(5), \fBOPENSSL_config\fR\|(3), +\&\fBCONF_modules_load_file_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBCONF_modules_free()\fR was deprecated in OpenSSL 1.1.0; do not use it. +For more information see \fBOPENSSL_init_crypto\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CONF_modules_load_file.3 b/static/netbsd/man3/CONF_modules_load_file.3 new file mode 100644 index 00000000..31b382ad --- /dev/null +++ b/static/netbsd/man3/CONF_modules_load_file.3 @@ -0,0 +1,229 @@ +.\" $NetBSD: CONF_modules_load_file.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CONF_modules_load_file 3" +.TH CONF_modules_load_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CONF_get1_default_config_file, +CONF_modules_load_file_ex, CONF_modules_load_file, CONF_modules_load +\&\- OpenSSL configuration functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& char *CONF_get1_default_config_file(void); +\& int CONF_modules_load_file_ex(OSSL_LIB_CTX *libctx, const char *filename, +\& const char *appname, unsigned long flags); +\& int CONF_modules_load_file(const char *filename, const char *appname, +\& unsigned long flags); +\& int CONF_modules_load(const CONF *cnf, const char *appname, +\& unsigned long flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBCONF_get1_default_config_file()\fR determines the default +configuration file pathname as follows. +If the \fBOPENSSL_CONF\fR environment variable is set its value is returned. +Else the function returns the path obtained using +\&\fBX509_get_default_cert_area\fR\|(3) with the filename \f(CW"openssl.cnf"\fR appended. +The caller is responsible for freeing any string returned. +.PP +The function \fBCONF_modules_load_file_ex()\fR configures OpenSSL using +library context \fBlibctx\fR file \fBfilename\fR and application name \fBappname\fR. +If \fBfilename\fR is NULL the standard OpenSSL configuration file is used +as determined by calling \fBCONF_get1_default_config_file()\fR. +If \fBappname\fR is NULL the standard OpenSSL application name \fBopenssl_conf\fR is +used. +The behaviour can be customized using \fBflags\fR. Note that, the error suppressing +can be overridden by \fBconfig_diagnostics\fR as described in \fBconfig\fR\|(5). +.PP +\&\fBCONF_modules_load_file()\fR is the same as \fBCONF_modules_load_file_ex()\fR but +has a NULL library context. +.PP +\&\fBCONF_modules_load()\fR is identical to \fBCONF_modules_load_file()\fR except it +reads configuration information from \fBcnf\fR. +.SH NOTES +.IX Header "NOTES" +The following \fBflags\fR are currently recognized: +.PP +If \fBCONF_MFLAGS_IGNORE_ERRORS\fR is set errors returned by individual +configuration modules are ignored. If not set the first module error is +considered fatal and no further modules are loaded. +.PP +Normally any modules errors will add error information to the error queue. If +\&\fBCONF_MFLAGS_SILENT\fR is set no error information is added. +.PP +If \fBCONF_MFLAGS_IGNORE_RETURN_CODES\fR is set the function unconditionally +returns success. +This is used by default in \fBOPENSSL_init_crypto\fR\|(3) to ignore any errors in +the default system\-wide configuration file, as having all OpenSSL applications +fail to start when there are potentially minor issues in the file is too risky. +Applications calling \fBCONF_modules_load_file_ex\fR explicitly should not +generally set this flag. +.PP +If \fBCONF_MFLAGS_NO_DSO\fR is set configuration module loading from DSOs is +disabled. +.PP +\&\fBCONF_MFLAGS_IGNORE_MISSING_FILE\fR if set will make \fBCONF_load_modules_file()\fR +ignore missing configuration files. Normally a missing configuration file +return an error. +.PP +\&\fBCONF_MFLAGS_DEFAULT_SECTION\fR if set and \fBappname\fR is not NULL will use the +default section pointed to by \fBopenssl_conf\fR if \fBappname\fR does not exist. +.PP +By using \fBCONF_modules_load_file_ex()\fR with appropriate flags an +application can customise application configuration to best suit its needs. +In some cases the use of a configuration file is optional and its absence is not +an error: in this case \fBCONF_MFLAGS_IGNORE_MISSING_FILE\fR would be set. +.PP +Errors during configuration may also be handled differently by different +applications. For example in some cases an error may simply print out a warning +message and the application continue. In other cases an application might +consider a configuration file error as fatal and exit immediately. +.PP +Applications can use the \fBCONF_modules_load()\fR function if they wish to load a +configuration file themselves and have finer control over how errors are +treated. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return 1 for success and a zero or negative value for +failure. If module errors are not ignored the return code will reflect the +return value of the failing module (this will always be zero or negative). +.SH EXAMPLES +.IX Header "EXAMPLES" +Load a configuration file and print out any errors and exit (missing file +considered fatal): +.PP +.Vb 5 +\& if (CONF_modules_load_file_ex(libctx, NULL, NULL, 0) <= 0) { +\& fprintf(stderr, "FATAL: error loading configuration file\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +.Ve +.PP +Load default configuration file using the section indicated by "myapp", +tolerate missing files, but exit on other errors: +.PP +.Vb 6 +\& if (CONF_modules_load_file_ex(NULL, NULL, "myapp", +\& CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { +\& fprintf(stderr, "FATAL: error loading configuration file\en"); +\& ERR_print_errors_fp(stderr); +\& exit(1); +\& } +.Ve +.PP +Load custom configuration file and section, only print warnings on error, +missing configuration file ignored: +.PP +.Vb 5 +\& if (CONF_modules_load_file_ex(NULL, "/something/app.cnf", "myapp", +\& CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { +\& fprintf(stderr, "WARNING: error loading configuration file\en"); +\& ERR_print_errors_fp(stderr); +\& } +.Ve +.PP +Load and parse configuration file manually, custom error handling: +.PP +.Vb 3 +\& FILE *fp; +\& CONF *cnf = NULL; +\& long eline; +\& +\& fp = fopen("/somepath/app.cnf", "r"); +\& if (fp == NULL) { +\& fprintf(stderr, "Error opening configuration file\en"); +\& /* Other missing configuration file behaviour */ +\& } else { +\& cnf = NCONF_new_ex(libctx, NULL); +\& if (NCONF_load_fp(cnf, fp, &eline) == 0) { +\& fprintf(stderr, "Error on line %ld of configuration file\en", eline); +\& ERR_print_errors_fp(stderr); +\& /* Other malformed configuration file behaviour */ +\& } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { +\& fprintf(stderr, "Error configuring application\en"); +\& ERR_print_errors_fp(stderr); +\& /* Other configuration error behaviour */ +\& } +\& fclose(fp); +\& NCONF_free(cnf); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBconfig\fR\|(5), +\&\fBOPENSSL_config\fR\|(3), +\&\fBNCONF_new_ex\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CRYPTO_THREAD_run_once.3 b/static/netbsd/man3/CRYPTO_THREAD_run_once.3 new file mode 100644 index 00000000..1405038f --- /dev/null +++ b/static/netbsd/man3/CRYPTO_THREAD_run_once.3 @@ -0,0 +1,311 @@ +.\" $NetBSD: CRYPTO_THREAD_run_once.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CRYPTO_THREAD_run_once 3" +.TH CRYPTO_THREAD_run_once 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CRYPTO_THREAD_run_once, +CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, +CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, +CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or, +CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int, +OSSL_set_max_threads, OSSL_get_max_threads, +OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL, +OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN \- OpenSSL thread support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT; +\& int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void)); +\& +\& CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void); +\& int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock); +\& int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock); +\& int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock); +\& void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock); +\& +\& int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_add64(uint64_t *val, uint64_t op, uint64_t *ret, +\& CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_and(uint64_t *val, uint64_t op, uint64_t *ret, +\& CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret, +\& CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock); +\& int CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock); +\& +\& int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads); +\& uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx); +\& uint32_t OSSL_get_thread_support_flags(void); +\& +\& #define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL +\& #define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL can be safely used in multi\-threaded applications provided that +support for the underlying OS threading API is built\-in. Currently, OpenSSL +supports the pthread and Windows APIs. OpenSSL can also be built without +any multi\-threading support, for example on platforms that don\*(Aqt provide +any threading support or that provide a threading API that is not yet +supported by OpenSSL. +.PP +The following multi\-threading function are provided: +.IP \(bu 2 +\&\fBCRYPTO_THREAD_run_once()\fR can be used to perform one\-time initialization. +The \fIonce\fR argument must be a pointer to a static object of type +\&\fBCRYPTO_ONCE\fR that was statically initialized to the value +\&\fBCRYPTO_ONCE_STATIC_INIT\fR. +The \fIinit\fR argument is a pointer to a function that performs the desired +exactly once initialization. +In particular, this can be used to allocate locks in a thread\-safe manner, +which can then be used with the locking functions below. +.IP \(bu 2 +\&\fBCRYPTO_THREAD_lock_new()\fR allocates, initializes and returns a new read/write +lock. +.IP \(bu 2 +\&\fBCRYPTO_THREAD_read_lock()\fR locks the provided \fIlock\fR for reading. +.IP \(bu 2 +\&\fBCRYPTO_THREAD_write_lock()\fR locks the provided \fIlock\fR for writing. +.IP \(bu 2 +\&\fBCRYPTO_THREAD_unlock()\fR unlocks the previously locked \fIlock\fR. +.IP \(bu 2 +\&\fBCRYPTO_THREAD_lock_free()\fR frees the provided \fIlock\fR. +If the argument is NULL, nothing is done. +.IP \(bu 2 +\&\fBCRYPTO_atomic_add()\fR atomically adds \fIamount\fR to \fI*val\fR and returns the +result of the operation in \fI*ret\fR. \fIlock\fR will be locked, unless atomic +operations are supported on the specific platform. Because of this, if a +variable is modified by \fBCRYPTO_atomic_add()\fR then \fBCRYPTO_atomic_add()\fR must +be the only way that the variable is modified. If atomic operations are not +supported and \fIlock\fR is NULL, then the function will fail. +.IP \(bu 2 +\&\fBCRYPTO_atomic_add64()\fR atomically adds \fIop\fR to \fI*val\fR and returns the +result of the operation in \fI*ret\fR. \fIlock\fR will be locked, unless atomic +operations are supported on the specific platform. Because of this, if a +variable is modified by \fBCRYPTO_atomic_add64()\fR then \fBCRYPTO_atomic_add64()\fR must +be the only way that the variable is modified. If atomic operations are not +supported and \fIlock\fR is NULL, then the function will fail. +.IP \(bu 2 +\&\fBCRYPTO_atomic_and()\fR performs an atomic bitwise and of \fIop\fR and \fI*val\fR and stores +the result back in \fI*val\fR. It also returns the result of the operation in +\&\fI*ret\fR. \fIlock\fR will be locked, unless atomic operations are supported on the +specific platform. Because of this, if a variable is modified by +\&\fBCRYPTO_atomic_and()\fR or read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_and()\fR must +be the only way that the variable is modified. If atomic operations are not +supported and \fIlock\fR is NULL, then the function will fail. +.IP \(bu 2 +\&\fBCRYPTO_atomic_or()\fR performs an atomic bitwise or of \fIop\fR and \fI*val\fR and stores +the result back in \fI*val\fR. It also returns the result of the operation in +\&\fI*ret\fR. \fIlock\fR will be locked, unless atomic operations are supported on the +specific platform. Because of this, if a variable is modified by +\&\fBCRYPTO_atomic_or()\fR or read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_or()\fR must +be the only way that the variable is modified. If atomic operations are not +supported and \fIlock\fR is NULL, then the function will fail. +.IP \(bu 2 +\&\fBCRYPTO_atomic_load()\fR atomically loads the contents of \fI*val\fR into \fI*ret\fR. +\&\fIlock\fR will be locked, unless atomic operations are supported on the specific +platform. Because of this, if a variable is modified by \fBCRYPTO_atomic_or()\fR or +read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_load()\fR must be the only way that +the variable is read. If atomic operations are not supported and \fIlock\fR is +NULL, then the function will fail. +.IP \(bu 2 +\&\fBCRYPTO_atomic_store()\fR atomically stores the contents of \fIval\fR into \fI*dst\fR. +\&\fIlock\fR will be locked, unless atomic operations are supported on the specific +platform. +.IP \(bu 2 +\&\fBCRYPTO_atomic_load_int()\fR works identically to \fBCRYPTO_atomic_load()\fR but operates +on an \fIint\fR value instead of a \fIuint64_t\fR value. +.IP \(bu 2 +\&\fBOSSL_set_max_threads()\fR sets the maximum number of threads to be used by the +thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will +not create any threads and existing threads in the thread pool will be torn +down. The maximum thread count is a limit, not a target. Threads will not be +spawned unless (and until) there is demand. Thread polling is disabled by +default. To enable threading you must call \fBOSSL_set_max_threads()\fR explicitly. +Under no circumstances is this done for you. +.IP \(bu 2 +\&\fBOSSL_get_thread_support_flags()\fR determines what thread pool functionality +OpenSSL is compiled with and is able to support in the current run time +environment. \fBOSSL_THREAD_SUPPORT_FLAG_THREAD_POOL\fR indicates that the base +thread pool functionality is available, and +\&\fBOSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN\fR indicates that the default thread pool +model is available. The default thread pool model is currently the only model +available, therefore both of these flags must be set for thread pool +functionality to be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCRYPTO_THREAD_run_once()\fR returns 1 on success, or 0 on error. +.PP +\&\fBCRYPTO_THREAD_lock_new()\fR returns the allocated lock, or NULL on error. +.PP +\&\fBCRYPTO_THREAD_lock_free()\fR returns no value. +.PP +\&\fBOSSL_set_max_threads()\fR returns 1 on success and 0 on failure. Returns failure +if OpenSSL\-managed thread pooling is not supported (for example, if it is not +supported on the current platform, or because OpenSSL is not built with the +necessary support). +.PP +\&\fBOSSL_get_max_threads()\fR returns the maximum number of threads currently allowed +to be used by the thread pool. If thread pooling is disabled or not available, +returns 0. +.PP +\&\fBOSSL_get_thread_support_flags()\fR returns zero or more \fBOSSL_THREAD_SUPPORT_FLAG\fR +values. +.PP +The other functions return 1 on success, or 0 on error. +.SH NOTES +.IX Header "NOTES" +On Windows platforms the CRYPTO_THREAD_* types and functions in the +\&\fI\fR header are dependent on some of the types +customarily made available by including \fI\fR. The application +developer is likely to require control over when the latter is included, +commonly as one of the first included headers. Therefore, it is defined as an +application developer\*(Aqs responsibility to include \fI\fR prior to +\&\fI\fR where use of CRYPTO_THREAD_* types and functions is +required. +.SH EXAMPLES +.IX Header "EXAMPLES" +You can find out if OpenSSL was configured with thread support: +.PP +.Vb 6 +\& #include +\& #if defined(OPENSSL_THREADS) +\& /* thread support enabled */ +\& #else +\& /* no thread support */ +\& #endif +.Ve +.PP +This example safely initializes and uses a lock. +.PP +.Vb 4 +\& #ifdef _WIN32 +\& # include +\& #endif +\& #include +\& +\& static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; +\& static CRYPTO_RWLOCK *lock; +\& +\& static void myinit(void) +\& { +\& lock = CRYPTO_THREAD_lock_new(); +\& } +\& +\& static int mylock(void) +\& { +\& if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL) +\& return 0; +\& return CRYPTO_THREAD_write_lock(lock); +\& } +\& +\& static int myunlock(void) +\& { +\& return CRYPTO_THREAD_unlock(lock); +\& } +\& +\& int serialized(void) +\& { +\& int ret = 0; +\& +\& if (!mylock()) { +\& /* Do not unlock unless the lock was successfully acquired. */ +\& return 0; +\& } +\& +\& /* Your code here, do not return without releasing the lock! */ +\& ret = ... ; +\& myunlock(); +\& return ret; +\& } +.Ve +.PP +Finalization of locks is an advanced topic, not covered in this example. +This can only be done at process exit or when a dynamically loaded library is +no longer in use and is unloaded. +The simplest solution is to just "leak" the lock in applications and not +repeatedly load/unload shared libraries that allocate locks. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBopenssl\-threads\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +\&\fBCRYPTO_atomic_load_int()\fR, \fBOSSL_set_max_threads()\fR, \fBOSSL_get_max_threads()\fR, +\&\fBOSSL_get_thread_support_flags()\fR were added in OpenSSL 3.2. +.PP +\&\fBCRYPTO_atomic_store()\fR, \fBCRYPTO_atomic_add64()\fR, \fBCRYPTO_atomic_and()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CRYPTO_get_ex_new_index.3 b/static/netbsd/man3/CRYPTO_get_ex_new_index.3 new file mode 100644 index 00000000..dcbbc846 --- /dev/null +++ b/static/netbsd/man3/CRYPTO_get_ex_new_index.3 @@ -0,0 +1,240 @@ +.\" $NetBSD: CRYPTO_get_ex_new_index.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CRYPTO_get_ex_new_index 3" +.TH CRYPTO_get_ex_new_index 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, +CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, +CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data, +CRYPTO_free_ex_data, CRYPTO_new_ex_data +\&\- functions supporting application\-specific data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CRYPTO_get_ex_new_index(int class_index, +\& long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, +\& void **from_d, int idx, long argl, void *argp); +\& +\& int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad); +\& +\& int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad, +\& int idx); +\& +\& int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); +\& +\& void *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *r, int idx); +\& +\& void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r); +\& +\& int CRYPTO_free_ex_index(int class_index, int idx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application\-specific data attached to them, +known as "exdata." +The specific structures are: +.PP +.Vb 10 +\& BIO +\& DH +\& DSA +\& EC_KEY +\& ENGINE +\& EVP_PKEY +\& RSA +\& SSL +\& SSL_CTX +\& SSL_SESSION +\& UI +\& UI_METHOD +\& X509 +\& X509_STORE +\& X509_STORE_CTX +.Ve +.PP +In addition, the \fBAPP\fR name is reserved for use by application code. +.PP +Each is identified by an \fBCRYPTO_EX_INDEX_xxx\fR define in the header file +\&\fI\fR. In addition, \fBCRYPTO_EX_INDEX_APP\fR is reserved for +applications to use this facility for their own structures. +.PP +The API described here is used by OpenSSL to manipulate exdata for specific +structures. Since the application data can be anything at all it is passed +and retrieved as a \fBvoid *\fR type. +.PP +The \fBCRYPTO_EX_DATA\fR type is opaque. To initialize the exdata part of +a structure, call \fBCRYPTO_new_ex_data()\fR. This is only necessary for +\&\fBCRYPTO_EX_INDEX_APP\fR objects. +.PP +Exdata types are identified by an \fBindex\fR, an integer guaranteed to be +unique within structures for the lifetime of the program. Applications +using exdata typically call \fBCRYPTO_get_ex_new_index\fR at startup, and +store the result in a global variable, or write a wrapper function to +provide lazy evaluation. The \fBclass_index\fR should be one of the +\&\fBCRYPTO_EX_INDEX_xxx\fR values. The \fBargl\fR and \fBargp\fR parameters are saved +to be passed to the callbacks but are otherwise not used. In order to +transparently manipulate exdata, three callbacks must be provided. The +semantics of those callbacks are described below. +.PP +When copying or releasing objects with exdata, the callback functions +are called in increasing order of their \fBindex\fR value. +.PP +If a dynamic library can be unloaded, it should call \fBCRYPTO_free_ex_index()\fR +when this is done. +This will replace the callbacks with no\-ops +so that applications don\*(Aqt crash. Any existing exdata will be leaked. +.PP +To set or get the exdata on an object, the appropriate type\-specific +routine must be used. This is because the containing structure is opaque +and the \fBCRYPTO_EX_DATA\fR field is not accessible. In both API\*(Aqs, the +\&\fBidx\fR parameter should be an already\-created index value. +.PP +When setting exdata, the pointer specified with a particular index is saved, +and returned on a subsequent "get" call. If the application is going to +release the data, it must make sure to set a \fBNULL\fR value at the index, +to avoid likely double\-free crashes. +.PP +The function \fBCRYPTO_free_ex_data\fR is used to free all exdata attached +to a structure. The appropriate type\-specific routine must be used. +The \fBclass_index\fR identifies the structure type, the \fBobj\fR is +a pointer to the actual structure, and \fBr\fR is a pointer to the +structure\*(Aqs exdata field. +.SS "Callback Functions" +.IX Subsection "Callback Functions" +This section describes how the callback functions are used. Applications +that are defining their own exdata using \fBCYPRTO_EX_INDEX_APP\fR must +call them as described here. +.PP +When a structure is initially allocated (such as \fBRSA_new()\fR) then the +\&\fBnew_func()\fR is called for every defined index. There is no requirement +that the entire parent, or containing, structure has been set up. +The \fBnew_func()\fR is typically used only to allocate memory to store the +exdata, and perhaps an "initialized" flag within that memory. +The exdata value may be allocated later on with \fBCRYPTO_alloc_ex_data()\fR, +or may be set by calling \fBCRYPTO_set_ex_data()\fR. +.PP +When a structure is free\*(Aqd (such as \fBSSL_CTX_free()\fR) then the +\&\fBfree_func()\fR is called for every defined index. Again, the state of the +parent structure is not guaranteed. The \fBfree_func()\fR may be called with a +NULL pointer. +.PP +Both \fBnew_func()\fR and \fBfree_func()\fR take the same parameters. +The \fBparent\fR is the pointer to the structure that contains the exdata. +The \fBptr\fR is the current exdata item; for \fBnew_func()\fR this will typically +be NULL. The \fBr\fR parameter is a pointer to the exdata field of the object. +The \fBidx\fR is the index and is the value returned when the callbacks were +initially registered via \fBCRYPTO_get_ex_new_index()\fR and can be used if +the same callback handles different types of exdata. +.PP +\&\fBdup_func()\fR is called when a structure is being copied. This is only done +for \fBSSL\fR, \fBSSL_SESSION\fR, \fBEC_KEY\fR objects and \fBBIO\fR chains via +\&\fBBIO_dup_chain()\fR. The \fBto\fR and \fBfrom\fR parameters +are pointers to the destination and source \fBCRYPTO_EX_DATA\fR structures, +respectively. The \fB*from_d\fR parameter is a pointer to the source exdata. +When the \fBdup_func()\fR returns, the value in \fB*from_d\fR is copied to the +destination ex_data. If the pointer contained in \fB*pptr\fR is not modified +by the \fBdup_func()\fR, then both \fBto\fR and \fBfrom\fR will point to the same data. +The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are as described for the other +two callbacks. If the \fBdup_func()\fR returns \fB0\fR the whole \fBCRYPTO_dup_ex_data()\fR +will fail. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCRYPTO_get_ex_new_index()\fR returns a new index or \-1 on failure. +.PP +\&\fBCRYPTO_free_ex_index()\fR, \fBCRYPTO_alloc_ex_data()\fR and \fBCRYPTO_set_ex_data()\fR +return 1 on success or 0 on failure. +.PP +\&\fBCRYPTO_get_ex_data()\fR returns the application data or NULL on failure; +note that NULL may be a valid value. +.PP +\&\fBdup_func()\fR should return 0 for failure and 1 for success. +.SH HISTORY +.IX Header "HISTORY" +\&\fBCRYPTO_alloc_ex_data()\fR was added in OpenSSL 3.0. +.PP +The signature of the \fBdup_func()\fR callback was changed in OpenSSL 3.0 to use the +type \fBvoid **\fR for \fBfrom_d\fR. Previously this parameter was of type \fBvoid *\fR. +.PP +Support for ENGINE "exdata" was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CRYPTO_memcmp.3 b/static/netbsd/man3/CRYPTO_memcmp.3 new file mode 100644 index 00000000..6110c3c1 --- /dev/null +++ b/static/netbsd/man3/CRYPTO_memcmp.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: CRYPTO_memcmp.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CRYPTO_memcmp 3" +.TH CRYPTO_memcmp 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CRYPTO_memcmp \- Constant time memory comparison +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CRYPTO_memcmp(const void *a, const void *b, size_t len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The CRYPTO_memcmp function compares the \fBlen\fR bytes pointed to by \fBa\fR and \fBb\fR +for equality. +It takes an amount of time dependent on \fBlen\fR, but independent of the +contents of the memory regions pointed to by \fBa\fR and \fBb\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCRYPTO_memcmp()\fR returns 0 if the memory regions are equal and nonzero +otherwise. +.SH NOTES +.IX Header "NOTES" +Unlike \fBmemcmp\fR\|(2), this function cannot be used to order the two memory regions +as the return value when they differ is undefined, other than being nonzero. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CRYPTO_set_ex_data.3 b/static/netbsd/man3/CRYPTO_set_ex_data.3 new file mode 100644 index 00000000..49059ce8 --- /dev/null +++ b/static/netbsd/man3/CRYPTO_set_ex_data.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: CRYPTO_set_ex_data.3,v 1.1.1.1 2018/02/03 22:43:38 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "CRYPTO_set_ex_data 3" +.TH CRYPTO_set_ex_data 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +CRYPTO_set_ex_data, CRYPTO_get_ex_data \- internal application specific data functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); +\& +\& void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.PP +These functions should only be used by applications to manipulate +\&\fB\s-1CRYPTO_EX_DATA\s0\fR structures passed to the \fB\f(BInew_func()\fB\fR, \fB\f(BIfree_func()\fB\fR and +\&\fB\f(BIdup_func()\fB\fR callbacks: as passed to \fB\f(BIRSA_get_ex_new_index()\fB\fR for example. +.PP +\&\fB\f(BICRYPTO_set_ex_data()\fB\fR is used to set application specific data, the data is +supplied in the \fBarg\fR parameter and its precise meaning is up to the +application. +.PP +\&\fB\f(BICRYPTO_get_ex_data()\fB\fR is used to retrieve application specific data. The data +is returned to the application, this will be the same value as supplied to +a previous \fB\f(BICRYPTO_set_ex_data()\fB\fR call. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fB\f(BICRYPTO_set_ex_data()\fB\fR returns 1 on success or 0 on failure. +.PP +\&\fB\f(BICRYPTO_get_ex_data()\fB\fR returns the application data or 0 on failure. 0 may also +be valid application data but currently it can only fail if given an invalid \fBidx\fR +parameter. +.PP +On failure an error code can be obtained from \fIERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIRSA_get_ex_new_index\fR\|(3), +\&\fIDSA_get_ex_new_index\fR\|(3), +\&\fIDH_get_ex_new_index\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fICRYPTO_set_ex_data()\fR and \fICRYPTO_get_ex_data()\fR have been available since SSLeay 0.9.0. diff --git a/static/netbsd/man3/CTLOG_STORE_get0_log_by_id.3 b/static/netbsd/man3/CTLOG_STORE_get0_log_by_id.3 new file mode 100644 index 00000000..1c713168 --- /dev/null +++ b/static/netbsd/man3/CTLOG_STORE_get0_log_by_id.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: CTLOG_STORE_get0_log_by_id.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CTLOG_STORE_get0_log_by_id 3" +.TH CTLOG_STORE_get0_log_by_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CTLOG_STORE_get0_log_by_id \- +Get a Certificate Transparency log from a CTLOG_STORE +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store, +\& const uint8_t *log_id, +\& size_t log_id_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency +(CT) log that issued it using the log\*(Aqs LogID (see RFC 6962, Section 3.2). +Therefore, it is useful to be able to look up more information about a log +(e.g. its public key) using this LogID. +.PP +\&\fBCTLOG_STORE_get0_log_by_id()\fR provides a way to do this. It will find a CTLOG +in a CTLOG_STORE that has a given LogID. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCTLOG_STORE_get0_log_by_id\fR returns a CTLOG with the given LogID, if it +exists in the given CTLOG_STORE, otherwise it returns NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7), +\&\fBCTLOG_STORE_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBCTLOG_STORE_get0_log_by_id()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CTLOG_STORE_new.3 b/static/netbsd/man3/CTLOG_STORE_new.3 new file mode 100644 index 00000000..2d20c333 --- /dev/null +++ b/static/netbsd/man3/CTLOG_STORE_new.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: CTLOG_STORE_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CTLOG_STORE_new 3" +.TH CTLOG_STORE_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CTLOG_STORE_new_ex, +CTLOG_STORE_new, CTLOG_STORE_free, +CTLOG_STORE_load_default_file, CTLOG_STORE_load_file \- +Create and populate a Certificate Transparency log list +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CTLOG_STORE *CTLOG_STORE_new_ex(OSSL_LIB_CTX *libctx, const char *propq); +\& CTLOG_STORE *CTLOG_STORE_new(void); +\& void CTLOG_STORE_free(CTLOG_STORE *store); +\& +\& int CTLOG_STORE_load_default_file(CTLOG_STORE *store); +\& int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency +logs). The list can be loaded from one or more files and then searched by LogID +(see RFC 6962, Section 3.2, for the definition of a LogID). +.PP +\&\fBCTLOG_STORE_new_ex()\fR creates an empty list of CT logs associated with +the library context \fIlibctx\fR and the property query string \fIpropq\fR. +.PP +\&\fBCTLOG_STORE_new()\fR does the same thing as \fBCTLOG_STORE_new_ex()\fR but with +the default library context and property query string. +.PP +The CTLOG_STORE is then populated by \fBCTLOG_STORE_load_default_file()\fR or +\&\fBCTLOG_STORE_load_file()\fR. \fBCTLOG_STORE_load_default_file()\fR loads from the default +file, which is named \fIct_log_list.cnf\fR in OPENSSLDIR (see the output of +\&\fBopenssl\-version\fR\|(1)). This can be overridden using an environment variable +named \fBCTLOG_FILE\fR. \fBCTLOG_STORE_load_file()\fR loads from a caller\-specified file +path instead. Both of these functions append any loaded CT logs to the +CTLOG_STORE. +.PP +The expected format of the file is: +.PP +.Vb 1 +\& enabled_logs=foo,bar +\& +\& [foo] +\& description = Log 1 +\& key = +\& +\& [bar] +\& description = Log 2 +\& key = +.Ve +.PP +Once a CTLOG_STORE is no longer required, it should be passed to +\&\fBCTLOG_STORE_free()\fR. This will delete all of the CTLOGs stored within, along +with the CTLOG_STORE itself. If the argument is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +If there are any invalid CT logs in a file, they are skipped and the remaining +valid logs will still be added to the CTLOG_STORE. A CT log will be considered +invalid if it is missing a "key" or "description" field. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Both \fBCTLOG_STORE_load_default_file\fR and \fBCTLOG_STORE_load_file\fR return 1 if +all CT logs in the file are successfully parsed and loaded, 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7), +\&\fBCTLOG_STORE_get0_log_by_id\fR\|(3), +\&\fBSSL_CTX_set_ctlog_list_file\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +CTLOG_STORE_new_ex was added in OpenSSL 3.0. All other functions were +added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CTLOG_new.3 b/static/netbsd/man3/CTLOG_new.3 new file mode 100644 index 00000000..d5951c30 --- /dev/null +++ b/static/netbsd/man3/CTLOG_new.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: CTLOG_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CTLOG_new 3" +.TH CTLOG_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CTLOG_new_ex, CTLOG_new, CTLOG_new_from_base64, +CTLOG_new_from_base64_ex, CTLOG_free, +CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key \- +encapsulates information about a Certificate Transparency log +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CTLOG *CTLOG_new_ex(EVP_PKEY *public_key, const char *name, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name); +\& +\& int CTLOG_new_from_base64_ex(CTLOG **ct_log, const char *pkey_base64, +\& const char *name, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int CTLOG_new_from_base64(CTLOG ** ct_log, +\& const char *pkey_base64, const char *name); +\& void CTLOG_free(CTLOG *log); +\& const char *CTLOG_get0_name(const CTLOG *log); +\& void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id, +\& size_t *log_id_len); +\& EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBCTLOG_new_ex()\fR returns a new CTLOG that represents the Certificate +Transparency (CT) log with the given public key and associates it with the +library context \fIlibctx\fR and property query string \fIpropq\fR. A name must also +be provided that can be used to help users identify this log. Ownership of the +public key is transferred. +.PP +\&\fBCTLOG_new()\fR does the same thing as \fBCTLOG_new_ex()\fR but with the default +library context and the default property query string. +.PP +\&\fBCTLOG_new_from_base64_ex()\fR also creates a new CTLOG, but takes the +public key in base64\-encoded DER form and sets the ct_log pointer to point to +the new CTLOG. The base64 will be decoded and the public key parsed. The CTLOG +will be associated with the given library context \fIlibctx\fR and property query +string \fIpropq\fR. +.PP +\&\fBCTLOG_new_from_base64()\fR does the same thing as +\&\fBCTLOG_new_from_base64_ex()\fR except that the default library context and +property query string are used. +.PP +Regardless of whether \fBCTLOG_new()\fR or \fBCTLOG_new_from_base64()\fR is used, it is the +caller\*(Aqs responsibility to pass the CTLOG to \fBCTLOG_free()\fR once it is no longer +needed. This will delete it and, if created by \fBCTLOG_new()\fR, the EVP_PKEY that +was passed to it. If the argument to \fBCTLOG_free()\fR is NULL, nothing is done. +.PP +\&\fBCTLOG_get0_name()\fR returns the name of the log, as provided when the CTLOG was +created. Ownership of the string remains with the CTLOG. +.PP +\&\fBCTLOG_get0_log_id()\fR sets *log_id to point to a string containing that log\*(Aqs +LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a +v1 CT log, the LogID will be a SHA\-256 hash (i.e. 32 bytes long). Ownership of +the string remains with the CTLOG. +.PP +\&\fBCTLOG_get0_public_key()\fR returns the public key of the CT log. Ownership of the +EVP_PKEY remains with the CTLOG. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCTLOG_new()\fR will return NULL if an error occurs. +.PP +\&\fBCTLOG_new_from_base64()\fR will return 1 on success, 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBCTLOG_new_ex()\fR and \fBCTLOG_new_from_base64_ex()\fR +were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/CT_POLICY_EVAL_CTX_new.3 b/static/netbsd/man3/CT_POLICY_EVAL_CTX_new.3 new file mode 100644 index 00000000..a201321c --- /dev/null +++ b/static/netbsd/man3/CT_POLICY_EVAL_CTX_new.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: CT_POLICY_EVAL_CTX_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "CT_POLICY_EVAL_CTX_new 3" +.TH CT_POLICY_EVAL_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CT_POLICY_EVAL_CTX_new_ex, +CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, +CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, +CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, +CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, +CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time \- +Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_ex(OSSL_LIB_CTX *libctx, +\& const char *propq); +\& CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); +\& void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); +\& X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); +\& int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); +\& X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); +\& int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); +\& const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); +\& void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, +\& CTLOG_STORE *log_store); +\& uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); +\& void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A \fBCT_POLICY_EVAL_CTX\fR is used by functions that evaluate whether Signed +Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. +This policy may be, for example, that at least one valid SCT is available. To +determine this, an SCT\*(Aqs timestamp and signature must be verified. +This requires: +.IP \(bu 2 +the public key of the log that issued the SCT +.IP \(bu 2 +the certificate that the SCT was issued for +.IP \(bu 2 +the issuer certificate (if the SCT was issued for a pre\-certificate) +.IP \(bu 2 +the current time +.PP +The above requirements are met using the setters described below. +.PP +\&\fBCT_POLICY_EVAL_CTX_new_ex()\fR creates an empty policy evaluation context +and associates it with the given library context \fIlibctx\fR and property query +string \fIpropq\fR. +.PP +\&\fBCT_POLICY_EVAL_CTX_new()\fR does the same thing as +\&\fBCT_POLICY_EVAL_CTX_new_ex()\fR except that it uses the default library +context and property query string. +.PP +The CT_POLICY_EVAL_CTX should then be populated using: +.IP \(bu 2 +\&\fBCT_POLICY_EVAL_CTX_set1_cert()\fR to provide the certificate the SCTs were issued for +.Sp +Increments the reference count of the certificate. +.IP \(bu 2 +\&\fBCT_POLICY_EVAL_CTX_set1_issuer()\fR to provide the issuer certificate +.Sp +Increments the reference count of the certificate. +.IP \(bu 2 +\&\fBCT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE()\fR to provide a list of logs that are trusted as sources of SCTs +.Sp +Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the +CT_POLICY_EVAL_CTX. +.IP \(bu 2 +\&\fBCT_POLICY_EVAL_CTX_set_time()\fR to set the time SCTs should be compared with to determine if they are valid +.Sp +The SCT timestamp will be compared to this time to check whether the SCT was +issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose +timestamp is in the future". By default, this will be set to 5 minutes in the +future (e.g. (\fBtime()\fR + 300) * 1000), to allow for clock drift. +.Sp +The time should be in milliseconds since the Unix Epoch. +.PP +Each setter has a matching getter for accessing the current value. +.PP +When no longer required, the \fBCT_POLICY_EVAL_CTX\fR should be passed to +\&\fBCT_POLICY_EVAL_CTX_free()\fR to delete it. If the argument to +\&\fBCT_POLICY_EVAL_CTX_free()\fR is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +The issuer certificate only needs to be provided if at least one of the SCTs +was issued for a pre\-certificate. This will be the case for SCTs embedded in a +certificate (i.e. those in an X.509 extension), but may not be the case for SCTs +found in the TLS SCT extension or OCSP response. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCT_POLICY_EVAL_CTX_new_ex()\fR and \fBCT_POLICY_EVAL_CTX_new()\fR will return +NULL if malloc fails. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +CT_POLICY_EVAL_CTX_new_ex was added in OpenSSL 3.0. All other +functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ChangeLog.3 b/static/netbsd/man3/ChangeLog.3 new file mode 100644 index 00000000..bedcba38 --- /dev/null +++ b/static/netbsd/man3/ChangeLog.3 @@ -0,0 +1,23224 @@ +2012-01-15 Jim Meyering + + getopt: refine syntax of previous change + * lib/Autom4te/General.pm (getopt): Use a more concise test. + +2011-01-15 Stefano Lattarini + + getopt: remove hack for special handling of "-" argument + + Older versions of Getopt::Long acted bogusly and died when they + where configured with the 'bundling' flag and an argument '-' was + seen on the command line they were parsing. That is no longer + the case though, and has not been for quite a long time: the bug + is no longer present in the 5.6.2 version of perl and the 2.25 + version of Getopt::Long (and today, the latest versions of perl + and Getopt::Long are respectively 5.14.2 and 2.38). The obsolete + workaround for that Getopt::Long bug can thus be removed from our + 'getopt' function. + + It is also worth noting that such a workaround was quite buggy + and brittle itself; for example, a command like this: + "autom4te --output -" + would have caused the incorrect diagnostic: + "autom4te: option `--output' requires an argument" + Much worse, a command like this: + "autom4te --language=autoconf --output - configure.ac" + would have caused the standard input of autom4te to be processed + and copied into the 'configure.ac' file, deleting its pre-existing + content! Surely not what a user would have expected. + + After this change, a command like this: + autom4te --language=autoconf --output - - out + works as expected, processing the input from 'configure.ac' and + writing it to the 'out' file. + + * lib/Autom4te/General.pm (use): Require perl version 5.6.2. + (getopt): Remove the old workaround. + +2012-01-15 Jim Meyering + + avoid new warning about undefined $ARGV[0] + * lib/Autom4te/General.pm (getopt): Avoid warning induced by + yesterday's change: $ARGV[0] may not be defined, e.g., when + invoked via autoreconf. + +2011-01-14 Stefano Lattarini + + getopt: fix diagnostic for missing mandatory option argument + Before this change, an incorrect command line usage: + "autom4te --output" + triggered broken diagnostic like: + "autom4te: unrecognized option `--output'" + instead of the expected and correct: + "autom4te: option `--output' requires an argument" + * lib/Autom4te/General.pm (getopt): Give correct diagnostic in + case of usage errors due to missing arguments for options for + which they are mandatory. Code basically copied from automake's + 'parse_arguments' private subroutine. + +2012-01-05 Paul Eggert + + doc: mention Bash 2.03 bug with backslash-newline + * doc/autoconf.texi (Invoking the Shell): New section. + (Backslash-Newline-Empty): Rename from Backslash-Newline-Newline. + Mention problem with Bash 2.03. + + doc: clarify sed buffer limit + * doc/autoconf.texi (Limitations of Usual Tools): + That 4000-byte limit applies to output and internal buffers, too. + +2012-01-03 Paul Eggert + + maint: update copyright year + All files changed to add 2012, via 'make update-copyright'. + + maint: resync upstream files + * ChangeLog, GNUmakefile, build-aux/announce-gen: + * build-aux/config.guess, build-aux/config.sub, build-aux/gendocs.sh: + * build-aux/git-version-gen, build-aux/move-if-change: + * build-aux/texinfo.tex, build-aux/update-copyright: + * build-aux/vc-list-files, doc/fdl.texi, doc/gendocs_template: + * doc/standards.texi, lib/Autom4te/XFile.pm, m4/autobuild.m4: + Regenerated by 'make fetch'. + +2012-01-02 Paul Eggert + + autoconf: remove " -link" and ")" from xlf output + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): + Also remove " -link" and trailing ")" from xlf output. + Problem and fix reported by Thomas Jahns in + . + +2011-12-26 Stefano Lattarini + + configure: will re-execute with $CONFIG_SHELL, if it's set + * lib/m4sugar/general.m4 (_AS_DETECT_BETTER_SHELL): Define the macro + `_AS_FORCE_REEXEC_WITH_CONFIG_SHELL' to `yes', so that the code in + `_AS_DETECT_BETTER_SHELL' will cause autoconf-generated configure + scripts to always re-execute themselves with $CONFIG_SHELL, if it's + set in the environment. + * doc/autoconf.texi (config.status Invocation): Update. + * doc/install.texi (Defining Variables): Likewise. + * NEWS: Likewise. + * tests/m4sh.at: Add tests for the new semantics in ... + (Configure re-execs self with CONFIG_SHELL): ... this new + test group. + +2011-12-26 Stefano Lattarini + + m4sh: allow forced re-execution with $CONFIG_SHELL, if it's set + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): If the m4sh client + has defined the macro `_AS_FORCE_REEXEC_WITH_CONFIG_SHELL' to + "yes", emit code to always re-execute the current script with + $CONFIG_SHELL, if that's set. + * tests/m4sh.at: Add tests for the new and old semantics, in ... + (Re-exec with CONFIG_SHELL, Forced re-exec with CONFIG_SHELL): ... + these new test groups. + +2011-12-26 Stefano Lattarini + + m4sh: refactor _AS_DETECT_BETTER_SHELL, for future changes + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Move code to + handle the re-execution of the shell ... + (_AS_REEXEC_WITH_SHELL): ... in this new macro. + +2011-12-24 Stefano Lattarini + + docs: issue with shell functions and here-documents on Solaris + * doc/autoconf.texi (Here-Documents): Using a command substitution + in a here-documents being fed to a shell function is unportable. + Problem revealed by the automake testsuite: + + +2011-12-26 Paul Eggert + + AS_LN_S: fall back on 'cp -pR' (not 'cp -p') if 'ln -s' fails + This works better for symlinks to directories. + Problem reported by Eli Zaretskii via Werner Lemberg in + . + * NEWS: + * doc/autoconf.texi (Particular Programs): Document this. + * lib/m4sugar/m4sh.m4 (_AS_LN_S_PREPARE): Implement this. + +2011-12-07 Paul Eggert + + AC_LANG_BOOL_COMPILE_TRY(C): port to g++ with warnings + * lib/autoconf/c.m4 (AC_LANG_BOOL_COMPILE_TRY(C)): Use the + array as well as setting it, to pacify g++. Reported by + Werner Lemberg in + . + +2011-12-05 Paul Eggert + + doc: document GNU make's \# + * doc/autoconf.texi (Comments in Make Macros): Also mention \# + in the right hand side of a macro, as an unportable usage. + +2011-11-11 Eric Blake + + doc: tweak previous commit + * doc/autoconf.texi (Limitations of Builtins) : Give + concrete example of offender, and drop redundant text. + Reported by Stefano Lattarini. + + doc: mention export portability hint + * doc/autoconf.texi (Limitations of Builtins) : Document + export limitation. + Suggested by Bruno Haible. + +2011-10-21 Stefano Lattarini + + fortran: define $GFC to "yes" if $FC is a GNU compiler + * lib/autoconf/fortran.m4 (AC_PROG_FC): Define `$GFC' to "yes" if + the detected fortran compiler is a GNU compiler, define it to the + empty string otherwise. + This is mostly for consistency for what is done for the C, C++ + and Fortran 77 compilers. + * doc/automake.texi: Update. + +2011-10-13 Eric Blake + + admin: mention recent copyright assignments + * AUTHORS: Update list. + +2011-10-06 Stefano Lattarini + + docs: we prefer US English spelling over British one + * doc/autoconf.texi (Parallel Make): Prefer `behavior' over + `behaviour' in a couple of places. + +2011-10-06 Stefano Lattarini + + docs: some fixlets in section about shell signal handling + * doc/autoconf.texi (Signal handling): Rename ... + (Signal Handling): ... to this, for consistency with other node + names. Fix some typos and grammaros. Add more URL references + in comments. + +2011-10-06 Stefano Lattarini + + docs: korn shells can have $? > 256 for signal-terminated children + Some Korn shells, when a child process dies due to signal number + n, can leave in $? an exit status of 256+n, instead of the more + common 128+n. See also Austin Group issue 0000051: + + * doc/autoconf.texi (Signal handling): Document the described Korn + Shell behaviour, and some of its possible shortcomings. + Suggestion by Eric Blake. + +2011-09-26 Eric Blake + + docs: relax documentation license by dropping cover text + * doc/autoconf.texi (copying): Drop front- and back-cover texts. + * NEWS: Document this. + Reported by Brian Gough. + +2011-09-13 Stefano Lattarini + + docs: signal-related bugs and incompatibilities for the shells + Motivated by recent discussion on the bug-autoconf list, as well + as work in the automake testsuite: + + + + * doc/autoconf.texi (Signal handling): New paragraph. + (@menu at "Portable Shell", @detailmenu): Update. + +2011-09-19 Eric Blake + + docs: refer to correct AC_RUN_IFELSE parameter name + * doc/autoconf.texi (Runtime) : Fix wording. + Reported by Reuben Thomas. + +2011-09-16 Eric Blake + + docs: fix typo in shell example + * doc/autoconf.texi (Shell Substitutions): Fix typo. + * THANKS: Update. + Reported by Nick Bowler. + +2011-09-14 Stefano Lattarini + + docs: more details about make VPATH rewriting woes + * doc/autoconf.texi (Automatic Rule Rewriting): Solaris make + VPATH rewriting applies to any whitespace-separated word in a + rule, so it might apply also to shell variables, functions + and keywords (and automake has already tripped on this once); + document this, with an example. Since we are at it, do some + minor reformatting of existing text. + +2011-09-13 Stefano Lattarini + + docs: document Solaris 10 /bin/ksh and XPG4 sh 'unset' bug + * doc/autoconf.texi (Limitations of Builtins): Solaris 10 ksh + and XPG4 sh also fails upon `unset' of a variable that is not + set. + +2011-07-24 Jim Meyering + + docs: improve the prose describing _AC_CHECK_TYPE_NEW_BODY + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW_BODY): Improve prose. + +2011-08-31 Paul Eggert + + AC_C_CONST: don't reject gcc -Werror -Wall + * lib/autoconf/c.m4 (AC_C_CONST): Don't reject gcc when it is used + with -Werror -Wall during configuring. It's unwise to use GCC + that way, but apparently enough people do it nowadays that it's an + issue. These days nobody uses the old compilers that the old + tests reject, so we can't test this fix against them, but it's + more important to work with modern GCC (even when misused) than to + work with no-longer-used compilers. Problem reported by Shevek in + + and raised again by Dan Kegel in + . + +2011-08-16 Stefano Lattarini + + docs: other issues with parallel BSD make + Motivated by automake bug#9245: + + and FreeBSD PR bin/159730: + + * doc/autoconf.texi (Parallel Make): Document other BSD make + incompatibilities. Reorganize the existing related documentation + accordingly. + +2011-08-08 Stefano Lattarini + + docs: fix minor typos + * doc/autoconf.texi (Shell Functions): Fix a couple of minor typos. + +2011-08-04 Stefano Lattarini + + docs: another Solaris sh bug with redirected `:' + * doc/autoconf.texi (File Descriptors): Solaris 10 /bin/sh + "optimizes" away redirected `:' commands in a shell function + after the first call. + +2011-07-31 Paul Eggert + + docs: modernize treatment of ns-resolution timestamps + * doc/autoconf.texi (Limitations of Usual Tools): ns-resolution time + stamps are now routinely supported by coreutils 'cp' etc. + +2011-07-30 Paul Eggert + + * lib/autoconf/specific.m4 (AC_SYS_LARGEFILE): Port to Mac OS X 10.5 + by defining _DARWIN_USE_64_BIT_INODE. Imported from gnulib. + +2011-07-22 Paul Eggert + + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Quote cleanly. + This is imported from gnulib. gnulib also has an HP-UX 11.11 fix, but + let's see if we can do that another way, as it's pretty heavyweight. + +2011-07-22 Eric Blake + + docs: fix minor doc problems + * doc/autoconf.texi (Why Not Imake): Fix grammar. + (autoreconf Invocation): Fix short option for --version. + * THANKS: Update. + Reported by Christophe Jarry and Russ Allbery. + +2011-07-12 Benoit Sigoure (tiny change) + + docs: fix typo in AC_PATH_PROG + * doc/autoconf.texi (Erlang Compiler and Interpreter): + s/AC_PROG_PATH/AC_PATH_PROG/. + * THANKS: Update. + +2011-06-30 Paul Eggert + + * tests/semantics.at (AC_REPLACE_FUNCS): Test for just-fixed bug. + +2011-06-30 Timo Kamph (trivial change) + + * lib/autoconf/functions.m4 (_AC_REPLACE_FUNCS): Fix tr-cpp problem. + See http://lists.gnu.org/archive/html/bug-autoconf/2011-06/msg00058.html + +2011-06-19 Paul Eggert + + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA): Be even smarter. + GCC was too smart for the previous patch. See + . + +2011-06-18 Paul Eggert + + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA): Try to outsmart GCC. + Problem with stack-detection code reported by Andy Wingo in + . + This fix is imported from gnulib's c-stack module. + + * doc/autoconf.texi (File Descriptors): Fix texinfo typo. + +2011-06-14 Eric Blake + + doc: mention more about ksh cloexec behavior + * doc/autoconf.texi (File Descriptors): Clarify that only the exec + builtin suffers from cloexec issues. + + doc: update quoting example + * doc/autoconf.texi (Autoconf Language): Add AC_LANG_SOURCE use. + * THANKS: Update. + Reported by KÅ™iÅ¡tof Želechovski. + +2011-05-05 Eric Blake + + doc: document dash bug with positional parameters + * doc/autoconf.texi (Shell Substitutions) <${10}>: Document + a pitfall with $10. + +2011-04-27 Eric Blake + + docs: document NetBSD join bug + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + bug in -a parsing. + Reported by J.T. Conklin. + +2011-04-13 Eric Blake + + maint: reflect recent copyright assignments + * AUTHORS: Update. + +2011-04-05 Eric Blake + + maint: reflect recent copyright assignments + * AUTHORS: Update. + +2011-04-02 Ralf Wildenhues + + New macro AC_FC_PP_DEFINE for the preprocessor define flag. + * lib/autoconf/fortran.m4 (AC_FC_PP_DEFINE): New macro. + * lib/autom4te.in (Automake-preselections): Preselect it. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/local.at (_AT_CHECK_ENV): Do not complain about + FCFLAGS_F nor FC_DEFINE. + * NEWS: Update. + + New macro AC_FC_PP_SRCEXT for preprocessed file extensions. + * lib/autoconf/fortran.m4 (AC_FC_PP_SRCEXT): New macro. + * lib/autom4te.in (Automake-preselections): Preselect it. + * doc/autoconf.texi (Fortran Compiler): Document it, rewriting + the documentation for AC_FC_SRCEXT along the way. + * tests/fortran.at (AC_FC_PP_SRCEXT usage): New test. + * tests/mktests.sh: Exclude the macro from default testing. + * NEWS: Update. + + New macro AC_FC_MODULE_OUTPUT_FLAG: module output directory. + * lib/autoconf/fortran.m4 (AC_FC_MODULE_OUTPUT_FLAG): New macro. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/local.at (_AT_CHECK_ENV): Do not complain about + FC_MODOUT. + * NEWS: Update. + +2011-04-02 Luc Maisonobe + Julian C. Cummings + Alexander Pletzer + Ralf Wildenhues + + New macro AC_FC_MODULE_FLAG: Fortran 90 module include path. + * lib/autoconf/fortran.m4 (AC_FC_MODULE_FLAG): New macro, + adjusted and rewritten from the AX_F90_MODULE_FLAG macro from + the Autoconf Macro Archive by Luc Maisonobe, Julian C. Cummings, + and Alexander Pletzer. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/fortran.at (AC_FC_MODULE_FLAG): New test. + * tests/local.at (AT_CHECK_ENV): Do not complain about FC_MODINC + setting. + * NEWS, THANKS: Update. + +2011-04-02 Luc Maisonobe + Alexander Pletzer + Ralf Wildenhues + + New macro AC_FC_MODULE_EXTENSION: Fortran 90 module extension. + * lib/autoconf/fortran.m4 (AC_FC_MODULE_EXTENSION): New macro, + rewritten from the AX_F90_MODULE_EXTENSION macro from the + Autoconf Macro Archive by Luc Maisonobe and Alexander Pletzer. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/local.at (_AT_CHECK_ENV): Do not complain about + FC_MODEXT setting. + * NEWS, THANKS: Update. + +2011-03-26 Jim Meyering + + README-hacking: fix typo + * README-hacking: s/just build/just built/. + +2011-03-08 Colin Watson (tiny change) + Ralf Wildenhues + + * doc/autoconf.texi (Particular Functions): Document AC_FUNC_FORK + cache variables. + * THANKS: Update. + +2011-03-08 Ralf Wildenhues + + docs: BSD and Solaris make trailing space macro issue. + * doc/autoconf.texi (Trailing whitespace in Make Macros): + Document issue with trailing whitespace in macro settings. + +2011-03-05 Ralf Wildenhues + + Fix Cray Fortran flag for AC_FC_IMPLICIT_NONE. + * lib/autoconf/fortran.m4 (_AC_FC_IMPLICIT_NONE): Use -e I + not -d i, for Cray ftn. + * THANKS: Update. + Thanks to Tobias Burnus for feedback and testing. + + docs: document several Fortran and OpenMP cache variables. + * doc/autoconf.texi (Generic Compiler Characteristics) + [AC_OPENMP]: Document associated cache variables. + (Fortran Compiler) [AC_PROG_F77, AC_PROG_FC, AC_PROG_F77_C_O] + [AC_PROG_FC_C_O, AC_F77_LIBRARY_LDFLAGS, AC_FC_LIBRARY_LDFLAGS] + [AC_F77_DUMMY_MAIN, AC_FC_DUMMY_MAIN, AC_F77_MAIN, AC_FC_MAIN] + [AC_F77_WRAPPERS, AC_FC_WRAPPERS, AC_FC_FREEFORM] + [AC_FC_FIXEDFORM, AC_FC_LINE_LENGTH, AC_FC_CHECK_BOUNDS] + [AC_F77_IMPLICIT_NONE, AC_FC_IMPLICIT_NONE]: Document and/or + index the cache variables used by these macros. + +2011-03-05 Ralf Wildenhues + and Eric Blake + + build: exclude M4 with buggy strstr + * m4/m4.m4 (AC_PROG_GNU_M4): When searching PATH, do not accept + an m4 that has either the gnulib strstr bug, or the glibc/gnulib + strstr bug. + +2011-03-05 Ralf Wildenhues + + docs: fix description of AC_F77_IMPLICIT_NONE. + * doc/autoconf.texi (Fortran Compiler) [AC_F77_IMPLICIT_NONE]: + This macro modifies FFLAGS, not FCFLAGS. + + AC_FC_SRCEXT: allow gfortran to compile .f77 files. + * lib/autoconf/fortran.m4 (AC_FC_SRCEXT): Try '-x f77' for .f77 + files, '-x f95' for others, for gfortran. + + New macros AC_{F77,FC}_IMPLICIT_NONE to disable Fortran implicit int. + * lib/autoconf/fortran.m4 (_AC_FC_IMPLICIT_NONE): New internal + macro. + (AC_F77_IMPLICIT_NONE, AC_FC_IMPLICIT_NONE): New macros. + * doc/autoconf.texi (Fortran Compiler): Document them. + * NEWS: Update. + + New macro AC_FC_CHECK_BOUNDS to enable Fortran array bounds checking. + * lib/autoconf/fortran.m4 (AC_FC_CHECK_BOUNDS): New macro. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/fortran.at (AC_FC_CHECK_BOUNDS): New test. + * NEWS: Update. + Prompted by report from Eve-Marie Devaliere. + +2011-03-04 Ralf Wildenhues + + Update known compiler switches for Fortran and OpenMP macros. + * lib/autoconf/c.m4 (AC_OPENMP): Update for Lahey on GNU/Linux. + * lib/autoconf/fortran.m4 (_AC_F95_FC): Also try nagfor. + (_AC_PROG_FC_V): Update documentation for Lahey switches. + (AC_FC_FREEFORM, AC_FC_FIXEDFORM): Add flags for Absoft, Lahey + on GNU/Linux, document NAGWare, g95, and f2c switches. + (AC_FC_LINE_LENGTH): Document NAGware switch. Update Absoft, + Lahey, NAGWare, Open Watcom, g95, and f2c switches. + + tests: accept f2c/fort77 as GNU Fortran 77. + * tests/fortran.at (GNU Fortran 77): Try to detect f2c wrapper + fort77 as GNU as well: it defines __GNUC__ too. Fixes testsuite + failure when f77 is fort77. + Report from Giulio Paci. + + docs: macro synopses document default failure cases. + * doc/autoconf.texi (Fortran Compiler, Obsolete Macros): + Document failure case for AC_F77_DUMMY_MAIN, AC_FC_DUMMY_MAIN, + AC_FC_SRCEXT, AC_FC_FREEFORM, AC_FC_FIXEDFORM, + AC_FC_LINE_LENGTH, and AC_TRY_RUN macros. + + Reword Fortran macro documentation. + * doc/autoconf.texi (Fortran Compiler): Improve wording for + AC_FC_FREEFORM, AC_FC_FIXEDFORM, and AC_FC_LINE_LENGTH macros. + +2011-02-27 Ralf Wildenhues + + config.status: do not quote $SHELL when rerunning configure. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Allow + $SHELL to contain more than one word, when rerunning configure, + for debugging purposes like CONFIG_SHELL='/bin/sh -x'. + +2011-02-21 Ian Lance Taylor + + * lib/autoconf/go.m4: New file. + * lib/autoconf/autoconf.m4: Include autoconf/go.m4. + * lib/autoconf/Makefile.am (dist_autoconflib_DATA): Add go.m4. + * lib/freeze.mk (autoconf_m4f_dependencies): Add + $(src_libdir)/autoconf/go.m4. + * doc/autoconf.texi: Rebuild menus. + (Preset Output Variables): Mention Go. Document GOFLAGS. + (Libraries): Mention Go. + (Go Compiler): New subsection. + (Language Choice): Mention Go. + (Generating Sources): Likewise. + (Running the Preprocessor): Likewise. + * tests/go.at: New file. + * tests/suite.at: Include go.at and acgo.at. + * tests/local.at (_AT_CHECK_ENV): Add GOC and GOFLAGS. + * tests/Makefile.am (TESTSUITE_GENERATED_AT): Add + $(srcdir)/acgo.at. + (TESTSUITE_HAND_AT): Add go.at. + (AUTOCONF_FILES): Add $(autoconfdir)/go.m4. + * NEWS: Update. + +2011-02-20 Christian Rössel (tiny change) + Markus Geimer (tiny change) + + Fix OpenMP flag detection for various Fortran compilers. + * lib/autoconf/c.m4 (_AC_LANG_OPENMP(Fortran 77)): Use '!$' + OpenMP-conditional compilation construct, to force compile + failure with missing OpenMP flag. + (AC_OPENMP): Add flags for Cray CCE and NEC SX compilers. + * THANKS: Update. + +2011-02-18 Eric Blake + + docs: document fourth argument of AC_RUN_IFELSE better + * doc/autoconf.texi (Runtime) : Make synopsis show + that the default is configure failure. Rework the text about + proper use of the fourth argument. + + long long: don't abort configure when cross-compiling + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): Provide no-op + cross-compiling fallback; fixing regression from 2011-02-16. + +2011-02-16 Patrick Welche (tiny change) + + docs: fix a typo + * doc/autoconf.texi (Generic Structures): Fix typo. + +2011-02-16 Matt Kraai (tiny change) + + docs: fix some typos + * doc/autoconf.texi (testsuite Scripts): Fix typos. + * THANKS: Update. + +2011-02-16 Paul Eggert + + autoconf: tune long long tests, particularly for c99 + + This change is imported from gnulib. + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): Don't bother compiling + or running anything if c99, or if unsigned long long int does not + work. In either case, we know the answer without further tests. + Do not compile _AC_TYPE_LONG_LONG_SNIPPET twice. Instead, compile + it at most once, and use its results for both long long int and + unsigned long long int. This is more likely to be efficient in + the common case where the program wants to check for both long + long int and unsigned long long int. + (AC_TYPE_UNSIGNED_LONG_LONG_INT): Don't bother compiling if c99, + since the answer is already known. + +2011-02-15 Eric Blake + + doc: fix debug advice typo + * doc/autoconf.texi (Debugging): Put shell option in right place. + Reported by Reuben Thomas. + +2011-02-12 Giulio Paci (tiny change) + Ralf Wildenhues + + Fix detection of link flags for fort77 on GNU/Linux. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Properly detect + the fort77 (f2c wrapper) compiler verbose linking output flag. + Fixes also AC_F77_LIBRARY_LDFLAGS and AC_F77_DUMMY_MAIN. + * THANKS: Update. + +2011-02-07 Ralf Wildenhues + + * doc/autoconf.texi: Rebuild menus using emacs ^C ^U ^A. + +2011-02-04 Paul Eggert + + autoconf: new macro AC_HEADER_CHECK_STDBOOL + * NEWS: Document this. + * doc/autoconf.texi (Particular Headers): Likewise. + In example, don't assume a 'system.h' exists. + * lib/autoconf/headers.m4 (AC_CHECK_HEADER_STDBOOL): New macro. + Use it with AN_IDENTIFIER, since it's less heavyweight. + Reindent to match gnulib, since that's a bit nicer. + (AC_HEADER_STDBOOL): Reimplement in terms of it. + +2011-01-29 Jim Warhol (tiny change) + + * doc/autoconf.texi (Introduction): Fix typo. + * THANKS: Update. + +2011-01-27 Stefano Lattarini + + docs: another parallel make issue + * doc/autoconf.texi (Parallel Make): Document that some make + implementations, when run in parallel mode, connect stdout and + stderr of child processes to pipes or temporary files, and might + re-route stderr of spawned processes to stout. Also document + that FreeBSD make in parallel mode reuses the same shell for + multiple commands within one recipe (like NetBSD make does). + +2011-01-25 Ralf Wildenhues + Eric Blake + + docs: advise against HP-UX make due to time stamp semantics. + * doc/autoconf.texi (Timestamps and Make): Document HP-UX 11.31 + make issue with targets having the same time stamps as their + prerequisites. + * doc/install.texi (Particular Systems): Warn against using + HP-UX make. + +2011-01-25 Eric Blake + + maint: reflect recent copyright assignments + * AUTHORS: Update. + +2011-01-23 Ralf Wildenhues + + docs: new section about whitespace trimmed from make command-lines. + * doc/autoconf.texi (Command-line Macros and whitespace): New + section, document trimming of whitespace from macros set on the + command line and from the environment. + +2011-01-22 Ralf Wildenhues + + docs: document how to use comment characters in rules. + * doc/autoconf.texi (Comments in Make Rules): Explain how to + produce a `#' in a rule. + (Comments in Make Macros): Add cross reference. + Suggestion from Eric Blake. + + docs: new sections about comments and whitespace in make macros. + * doc/autoconf.texi (Top, Portable Make): Adjust menus. + (Comments in Make Macros, Trailing whitespace in Make Macros): + New sections. + Suggestion by Stefano Lattarini. + + docs: do not use AIX 5.3 cp -R. + * doc/autoconf.texi (Limitations of Usual Tools): Document one + instance of the cp -R bug on AIX 5.3. This seems to have been + fixed in 6.1 and newer releases. + + docs: update entry about unset. + * doc/autoconf.texi (Limitations of Builtins): NetBSD sh unset + also fails upon `unset' of a variable that is not set. Bash 2.01 + could also dump core over `unset MAILPATH'. + Suggestion by Eric Blake. + +2011-01-21 Ralf Wildenhues + + Fix LEXLIB and YYTEXT_POINTER with IRIX 6.5 flex 2.5.4. + * lib/autoconf/programs.m4 (_AC_PROG_LEX_YYTEXT_DECL): + Overquote nontrivial yyless argument, to compensate for + underquoted macro definition in IRIX 6.5 flex 2.5.4 + leading to compile failure due to incompatible operands. + Fixes Automake silent-lex-generic.test failure. + +2011-01-17 Ralf Wildenhues + + docs: Tru64/OSF sh treats read as special builtin + * doc/autoconf.texi (Limitations of Builtins): read may exit + upon unreadable or non-existent file with Tru64/OSF 5.1 sh. + +2011-01-12 Eric Blake + + docs: fix description of m4_ifval + * doc/autoconf.texi (Conditional constructs) : Use + correct argument order. + * THANKS: Update. + Reported by Mostafa. + +2011-01-10 Ralf Wildenhues + + Avoid reference to $CYGWIN in Fortran macros. + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Require + AC_CANONICAL_HOST. Replace test for $CYGWIN with $host_s test. + * tests/fortran.at (AC_F77_DUMMY_MAIN usage) + (AC_FC_DUMMY_MAIN usage, AC_F77_MAIN usage, AC_FC_MAIN usage): + Use AT_CONFIGURE_AC and simplify accordingly, so auxiliary + scripts are copied into the test directories. + (AC_F77_FUNC usage, AC_FC_FUNC usage): Likewise. Adjust to + autoheader being used now. + + docs: link to Gnulib configmake documentation. + * doc/autoconf.texi (Defining Directories): Use proper crossref, + now that the Gnulib manual has a configmake section. + Thanks to Karl Berry. + +2011-01-09 Ralf Wildenhues + + docs: link to 'set -e' shell behavior overview. + * doc/autoconf.texi (Limitations of Builtins): Add link to + Sven Mascheck's 'set -e' page. Replace broken Opengroup link. + Suggestion by Eric Blake. + + docs: mention configmake module for defining directories. + * doc/autoconf.texi (Defining Directories): Mention configmake + gnulib module. + Suggestion by Karl Berry and Eric Blake. + +2011-01-04 Eric Blake + + doc: improve install.texi texinfo markup + * doc/install.texi: Don't force @firstparagraphindent on all + clients; instead, add it only when building INSTALL. Compress + copyright. + * Makefile.am (INSTALL): Match gnulib's formatting. + Reported by Karl Berry. + + maint: update copyright year + All files changed to add 2011, via 'make update-copyright'. + + maint: resync upstream files + * GNUmakefile: Regenerated by 'make fetch'. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gendocs.sh: Likewise. + * build-aux/git-version-gen: Likewise. + * build-aux/texinfo.tex: Likewise. + * doc/make-stds.texi: Likewise. + * lib/Autom4te/Channels.pm: Likewise. + * lib/Autom4te/Configure_ac.pm: Likewise. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/Struct.pm: Likewise. + * lib/Autom4te/XFile.pm: Likewise. + + maint: document use of copyright ranges + * README: Copy coreutils wording for allowing copyright year + ranges. + * cfg.mk (UPDATE_COPYRIGHT_USE_INTERVALS): Now that GNU Coding + Standards permit it, prefer shorthand copyright. + * .x-update-copyright: Exempt an imported file. + +2011-01-03 Karl Berry + + Avoid using @acronym in install.texi. + * doc/install.texi (Basic Installation, Multiple Architectures) + (Installation Names): Write `GNU' instead of `@acronym{GNU}'. + +2010-12-27 Paul Eggert + + autoconf: Use -D_STDC_C99=, not -xc99=all, with Solaris cc + * lib/autoconf/c.m4 (_AC_PROG_CC_C99): Use -D_STDC_C99= rather than + -xc99=all to convince Solaris Studio cc to compile c99 programs. + +2010-11-26 Paul Eggert + + autotest: fix file descriptor leak + * lib/autotest/general.m4 (_AT_CHECK): Close AS_MESSAGE_LOG_FD + when running the test. Problem reported by Luke Mewburn in + . + +2010-11-20 Paul Eggert + + autoconf: don't assume sys/stat.h and sys/types.h when testing C89 + Problem reported by Patrick Pelissier in + . + * lib/autoconf/c.m4 (_AC_PROG_CC_C89): Don't include sys/types.h + and sys/stat.h. Instead, define a dummy struct stat. C89 doesn't + guarantee sys/types.h and sys/stat.h. + +2010-11-10 Reuben Thomas (tiny change) + + docs: avoid first person, and credit history to David MacKenzie + * doc/autoconf.texi (History): Add credit. + +2010-10-26 Paul Eggert + + docs: Posix now says "((cat))" isn't portable + * doc/autoconf.texi (Parenthesis): Update documentation to reflect + what Posix 1003.1-2008 says about "((". + +2010-10-20 Eric Blake + + docs: document dash bug in <> + * doc/autoconf.texi (File Descriptors): Dash 0.5.5 truncates on + <>; at least this was fixed in dash 0.5.6. + +2010-10-12 Ralf Wildenhues + + tests: avoid AC_CACHE_CHECK test failure with dash. + * tests/base.at (AC_CACHE_CHECK): Normalize configure exit + status in presence of syntax error in sourced site file. + Do not error out if configure is aborted at this point. + Fixes testsuite failure with dash 0.5.5.1. + +2010-10-08 Eric Blake + + AS_LITERAL_IF: Treat raw = as literal again. + * lib/m4sugar/m4sh.m4 (_AS_LITERAL_IF): Treat = like +. + * tests/m4sh.at (AS@&t@_TR_SH and AS@&t@_TR_CPP) + (AS@&t@_LITERAL_IF): Expand tests. + * NEWS: Document the fix. + Reported via Ben Pfaff; originally http://bugs.debian.org/593838 + +2010-09-24 Joshua G. Hale (tiny change) + + docs: fix typo in AC_CONFIG_FILES example code. + * doc/autoconf.texi (Configuration Actions): Fix typo. + * THANKS: Update. + +2010-10-05 Eric Blake + + doc: suggest a few more workarounds + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + that 'redundant' brackets can work around Solaris bug. + (File Descriptors): Mention that {} works as well as () for + silencing file-not-found warnings. + * THANKS: Update. + Suggested by Pádraig Brady. + +2010-09-24 Ralf Wildenhues + + tests: normalize trailing spaces in gcc -E -dD output. + * tests/compile.at (AC_LANG_SOURCE example) + (AC_LANG_PROGRAM example): Remove trailing spaces before + comparing with expected output. Fixes testsuite failure + with GCC 2.95.3 on Haiku. + Report by Scott McCreary. + +2010-09-22 Eric Blake + + Release Version 2.68. + * NEWS: Mention the release. + +2010-09-22 Ralf Wildenhues + + autom4te: add traces for likely future Automake macros + * lib/autom4te.in (Automake-preselections): Trace + AM_MAKEFILE_INCLUDE, AM_NLS, AM_POT_TOOLS, AM_PATH_GUILE, + AM_PROG_MOC, AM_XGETTEXT_OPTION, _AM_MAKEFILE_INCLUDE. + +2010-09-22 Eric Blake + + AC_REPLACE_FUNCS: allow split lines again + * lib/autoconf/functions.m4 (AC_REPLACE_FUNCS): Flatten newlines + and move guts... + (_AC_REPLACE_FUNCS): ...to new helper. + * tests/semantics.at (AC_REPLACE_FUNCS): Enhance test. + Reported by Ralf Wildenhues. + +2010-09-21 Eric Blake + + AC_LIBOBJ: optimize internal use + * lib/autoconf/general.m4 (_AC_LIBOBJ): Move literal check... + (AC_LIBOBJ): ...into callers. + * lib/autoconf/functions.m4 (_AC_REPLACE_FUNC): Likewise, thus + avoiding a second call to AS_LITERAL_IF. + + AC_REPLACE_FUNCS: restore shell loop for non-literal + * lib/autoconf/functions.m4 (AC_REPLACE_FUNCS): Handle + non-literals, which was lost in 2010-02-26 optimization. + * tests/semantics.at (AC_REPLACE_FUNCS): Enhance test. + * NEWS: Document the fix. + * THANKS: Update. + Reported by Wiseman Jun. + + maint: resync upstream files + * build-aux/gendocs.sh: Resync via 'make fetch'. + + tests: XFAIL in the face of a MacOS X bug + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + the issue. + * tests/torture.at (Substitute and define special characters): + Detect if sed cannot process 8-bit bytes in the C locale. + * THANKS: Update. + Reported by Rochan. + +2010-09-20 Eric Blake + + autom4te: don't filter out portions of location traces + * bin/autom4te.in (_m4_warn): Pass warnings through the channels + machinery as a single chunk, to avoid partial filtering. + * lib/m4sugar/m4sugar.m4 (_m4_warn): Document the conventions. + * tests/m4sugar.at (m4@&t@_warn): Enhance test to catch this. + Reported by Bruno Haible. + +2010-09-17 Eric Blake + + build: support autobuild + * cfg.mk (gnulib-update): Add autobuild.m4. + * configure.ac (AB_INIT): Output autobuild header. + * m4/autobuild.m4: New file, from gnulib. + * build-aux/config.guess: Resync from upstream. + * build-aux/config.sub: Likewise. + * build-aux/texinfo.tex: Likewise. + * doc/fdl.texi: Likewise. + * doc/gnu-oids.texi: Likewise. + * doc/make-stds.texi: Likewise. + * doc/standards.texi: Likewise. + * build-aux/gendocs.sh: Likewise. + + config.status: avoid corrupting $ac_t + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS_PREPARE): Use a + different name, so as not to clash with pre-2.50 usage of "$ac_t" + as a tab character. + Reported by Sam Steingold. + +2010-09-17 Bruno Haible + + docs: mark several macros obsolete + * doc/autoconf.texi (Particular Functions): Mark AC_FUNC_ERROR_AT_LINE, + AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK, AC_FUNC_MKTIME, AC_FUNC_STRTOD + as obsolete and refer to Gnulib. + * NEWS: Mention the change. + + AC_FUNC_STRNLEN: more realistic cross-compilation guess + * lib/autoconf/functions.m4 (AC_FUNC_STRNLEN): Require + AC_CANONICAL_HOST. When cross-compiling, guess it works everywhere + except on AIX. + +2010-09-16 Eric Blake + + m4sh: fix today's AS_BOX regression + * lib/m4sugar/m4sh.m4 (_AS_BOX_LITERAL): Fix underquotation. + Reported by Stefano Lattarini. + + fortran: avoid misparsed FCLIBS from Fortran compiler + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Also skip + 'Configured by:' lines from gfortran. + * NEWS: Mention it. + Reported by Stefano Lattarini. + +2010-09-16 Ralf Wildenhues + + Add autom4te trace for AM_PROG_AR. + * lib/autom4te.in (Automake-preselections): Trace + AM_PROG_AR. + +2010-09-16 Eric Blake + + m4sugar: fix regression in AC_MSG_ERROR expansion + * lib/m4sugar/m4sugar.m4 (m4_defun_init): Avoid macro + concatenation on subsequent expansions + * tests/m4sh.at (AS_WARN and AS_ERROR): New test. + * tests/m4sugar.at (m4@&t@_require: one-shot initialization): + Enhance test. + * NEWS: Document the fix. + * THANKS: Update. + Reported by Adrian Bunk and and Nishio Futoshi. + +2010-09-13 Stefano Lattarini + + tests: simplify grepping of 'automake --version'. + * tests/tools.at (autom4te preselections): Remove minor + redundancies in regular expressions used to grep the output + 'automake --version' for test skipping. + * tests/torture.at (Configuring subdirectories) + (Unusual Automake input files): Likewise. + +2010-09-13 Eric Blake + + autotest: work around zsh bug + * lib/autotest/general.m4 (AT_DATA): Special case an empty data + file, since zsh botches empty here-docs. + * doc/autoconf.texi (Writing Testsuites) : Document that + this allows empty contents. + * tests/autotest.at (AT_DATA): New test. + Reported by Ralf Wildenhues. + + docs: mention gnulib portability docs + * doc/autoconf.texi (Function Portability, Header Portability): + Add external links to gnulib. + +2010-09-13 Ralf Wildenhues + Gary V. Vaughan + + docs: document zsh specialty with empty here-documents. + * doc/autoconf.texi (Here-Documents): zsh 4.3.10 adds a newline + to empty here-docs. + +2010-09-13 Ralf Wildenhues + + docs: document zsh special array $options. + * doc/autoconf.texi (Special Shell Variables): Add entry for + `options'. + + doc: minor updates. + * doc/autoconf.texi (Generic Compiler Characteristics): Use + second argument of @uref consistently, for nicer OpenMP link. + (Polymorphic Variables): Restore font-lock. + (Debugging): Add item for bashdb. + + Document and test AT_CHECK args shell execution environment. + * doc/autoconf.texi (Writing Testsuites): Document that COMMANDS + is run in a subshell, but RUN-IF-FAIL and RUN-IF-PASS are not. + * tests/autotest.at (AT@&t@_CHECK execution environment): New + test. + * NEWS: Update. + + autotest: document and test at_status semantics. + * doc/autoconf.texi (Writing Testsuites): Document $at_status. + * tests/autotest.at (at_status): New test. + * NEWS: Update. + + doc: index entries for non-environment, non-output variables. + * doc/autoconf.texi: Clarify the meaning of the various variable + indices. Merge variable index `vr' into concept index using + syncodeindex. + (Configuration Actions, Generic Programs, Generic Functions) + (Writing Testsuites): Add index entries for documented shell + variables used during in configure and testsuite scripts. + +2010-09-12 Fernando Carrijo (tiny change) + + docs: fix minor typo and 'See See foo' instances + * doc/autoconf.texi (Buffer Overruns and Subscript Errors): Fix + usage of TeX superscript notation to correctly represent number + exponent. + (Shell Functions): s/[Ss]ee @xref/@xref/ + (Limitations of Shell Builtins, Canonicalizing): Likewise. + * THANKS: Update. + +2010-09-13 Eric Blake + + tests: skip broken automake wrapper on MirBSD + * tests/tools.at (autom4te preselections): Skip, rather than fail, + if 'automake --version' succeeds without printing a version when + an environment variable is not set. + * tests/torture.at (Configuring subdirectories) + (Unusual Automake input files): Likewise. + +2010-09-12 Ralf Wildenhues + + doc: minor indexing update. + (Shell Substitutions, Site Defaults): Fix markup for indexed + entried, using @code and @file as appropriate. + (M4 Macro Index): Clarify which of the indexed macros have m4_ + and which have AS_ prefix. + +2010-09-08 Eric Blake + + m4sh: preserve set -vx over re-exec + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Trace through + re-exec, to make it easier to debug script startup issues. + Idea from recent bug-gnulib change to init.sh. + + docs: update alloca recommendations + * doc/autoconf.texi (Particular Functions): Don't redeclare alloca + on FreeBSD. + * THANKS: Update. + Reported by Giorgos Keramidas. + + docs: link to GNU Coding Standards in intro + * doc/autoconf.texi (Introduction): Actually link to the + standards. Make other references consistent. + + docs: mention traditional awk limitation + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + that traditional awk lacks ENVIRON. Add reference to awk manual. + (Particular Programs) : Add reference to awk section. + Reported by Ralf Wildenhues. + +2010-09-07 Eric Blake + + docs: mention bash vs. POSIXLY_CORRECT + * doc/autoconf.texi (Special Shell Variables) : + Document bash behavior. + * THANKS: Update. + Reported by Dustin J. Mitchell, via bug-gnulib list. + + docs: enhance recommendations on test usage + * doc/autoconf.texi (Limitations of Builtins) : + Mention yet another Solaris issue. + Reported by Stefano Lattarini. + +2010-08-30 Eric Blake + + tests: avoid trashing / + * tests/torture.at (AC_CONFIG_COMMANDS with temporary directory): + Use a relative path, rather than risking issues with /. + Reported by Ralf Wildenhues. + + docs: mention Solaris here-docs vs. ${a-"b c"} + * doc/autoconf.texi (Shell Substitutions) <${var:=value}>: + Document problem of "" within here-docs. + Reported by Ralf Wildenhues. + + fortran: always avoid AC_LANG_CONFTEST warning + * lib/autoconf/lang.m4 (AC_LANG_CONFTEST()): Make the default + match the fact that the default AC_LANG_SOURCE does not inline + confdefs.h in the first place. + * lib/autoconf/fortran.m4 (AC_FC_FREEFORM, AC_FC_FIXEDFORM) + (AC_FC_LINE_LENGTH, __AC_FC_NAME_MANGLING): Revert previous use of + AC_LANG_DEFINES_PROVIDED. + Suggested by Ralf Wildenhues. + + config.status: minimize use of $tmp + * lib/autoconf/status.m4 (_AC_OUTPUT_MAIN_LOOP) + (_AC_OUTPUT_FILES_PREPARE, _AC_OUTPUT_FILE) + (_AC_OUTPUT_HEADERS_PREPARE, _AC_OUTPUT_HEADER): Use $ac_tmp + internally, while preserving $tmp for existing users. + * tests/torture.at (AC_CONFIG_COMMANDS with temporary directory): + New test, that $tmp is available but not essential. + + docs: avoid use of $tmp outside of config.status use + * doc/autoconf.texi (Polymorphic Variables, Shell Substitutions): + Use $var or $t instead. + (Limitations of Usual Tools): Use $dir instead. + (Initialization Macros) : Make good on the NEWS + regarding AS_TMPDIR being documented as consuming $tmp. + Suggested by Ralf Wildenhues. + +2010-08-29 Paul Eggert + + AC_PROG_YACC: fix comment re what "yacc" stands for + * lib/autoconf/programs.m4 (AC_PROG_YACC): YACC stands for + "Yet Another Compiler Compiler", not "Yet Another C Compiler". + Problem reported by Chris Long in + . + +2010-08-27 Ralf Wildenhues + + Avoid long lines in testsuite script. + * lib/autotest/general.m4 (AT_INIT): Remove definition of + AT_groups_all. Initialize at_groups from at_help_all, with + newlines instead of spaces separating test groups numbers. + Adjust all code to newlines. + * NEWS: Update. + * tests/autotest.at (Huge testsuite): New test. + + Try to update config.cache atomically; respect symlinks. + * lib/autoconf/general.m4 (AC_CACHE_SAVE): Use `mv -f' to update + the cache file if it is a regular file and not a symlink. Move + first to temporary name in the target directory if not in the + current directory for atomicity across mount points. + * tests/base.at (AC_CACHE_CHECK): Try symlinked cache file. + * doc/autoconf.texi (Cache Files): Leftover temporary cache + files may be deleted by the user. + * NEWS: Update. + +2010-08-27 Eric Blake + + m4sh: protect LINENO against stray macro + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Double quote entire + sed script, to avoid issue uncovered by automake testsuite where + 'b' was an m4 macro that broke execution on dash. + Reported by Stefano Lattarini. + + m4sh: assume ${a:-b} support + * tests/m4sh.at (Null variable substitution): New test. + * doc/autoconf.texi (Shell Substitutions) <${var:-value}>: Mention + that m4sh guarantees support. + (Limitations of Usual Tools) : Use it. + * lib/m4sugar/m4sh.m4 (AS_LINENO_POP, AS_VAR_IF, AS_TMPDIR): + Exploit use of colon for smaller files. + +2010-08-26 Eric Blake + + docs: document m4_define_default + * doc/autoconf.texi (Conditional constructs) : + Document it, since gnulib wants to use it. + * NEWS: Mention this. + + autoconf: warn if AC_*_IFELSE lacks complete program + * lib/autoconf/lang.m4 (AC_LANG_DEFINES_PROVIDED): New macro. + (AC_LANG_SOURCE): Call it. + (AC_LANG_CONFTEST): Add warning if new macro is not called. + * lib/autoconf/c.m4 (_AC_LANG_OPENMP): Add missing AC_LANG_SOURCE. + * lib/autoconf/fortran.m4 (AC_FC_FREEFORM, AC_FC_FIXEDFORM) + (AC_FC_LINE_LENGTH, __AC_FC_NAME_MANGLING): Intentionally bypass + AC_LANG_SOURCE. + * lib/autoconf/programs.m4 (_AC_PROG_LEX_YYTEXT_DECL): Likewise. + * tests/compile.at (AC_COMPILE_IFELSE): New test. + * doc/autoconf.texi (Generating Sources) : + Document new warning. + : Document new macro. + : Document use of new macro. + * NEWS: Document the improvement. + Suggested by Bruno Haible. + + autoconf: fix regression in AC_FUNC_SELECT_ARGTYPES + * lib/autoconf/functions.m4 (AC_FUNC_SELECT_ARGTYPES): Fix + quoting; regression from yesterday leaked '' into default value. + Reported by Ralf Wildenhues. + + docs: mention another issue with variable expansion + In particular, see http://austingroupbugs.net/view.php?id=221 + and http://austingroupbugs.net/view.php?id=255. + * doc/autoconf.texi (Shell Substitutions) <${var+value}>: New + subsection. + <${var=literal}>: Tweak wording. Add mention of an ambiguity + allowed by POSIX. + * tests/torture.at (Substitute and define special characters): + Make test more robust; here, the outer "" is in a here-doc, and + does not violate the quoting rules of thumb just documented. + +2010-08-25 Eric Blake + + m4sh: revert incorrect mix of "${a='b'}" + * bin/autoconf.as: Revert leak of literal '' into assignment. + * tests/tools.at (autom4te preselections): Likewise. + + m4sh: revert regression in AS_TMPDIR + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): The previous patch trying to + rename $tmp to $as_tmp was wrong; config.status relies on it. + + m4sh: reduce size of AS_VAR_TEST_SET + * lib/m4sugar/m4sh.m4 (AS_VAR_TEST_SET): Make more compact. + + tests: improve some shell assumption testing + * tests/m4sh.at (Functions Support, Functions and return Support) + (Negated classes in globbing): Update comments. + (AS@&t@_VAR basics): Test comparison to empty string. + + docs: mention cost of globbing during variable expansion + * doc/autoconf.texi (Shell Substitutions) <${var=literal}>: + Recommend quoting substitutions that might trigger globbing. + (Limitations of Builtins) <:>: Likewise. + * bin/autoconf.as: Follow our own advice. + * lib/autoconf/functions.m4 (AC_FUNC_SELECT_ARGTYPES): Likewise. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Likewise. + * lib/autoconf/status.m4 (AC_OUTPUT): Likewise. + * lib/autotest/general.m4 (_AT_FINISH): Likewise. + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Likewise. + * tests/autotest.at (parallel autotest and signal handling): + Likewise. + * tests/c.at (AC_OPENMP and C, AC_OPENMP and C++): Likewise. + * tests/foreign.at (shtool): Likewise. + * tests/fortran.at: Likewise. + * tests/tools.at (autom4te preselections): Likewise. + * tests/torture.at (VPATH): Likewise. + + m4sh: fix some namespace safety issues + * lib/m4sugar/m4sh.m4 (_AS_SHELL_SANITIZE): Avoid problems if + as_myself is inherited from environment. + (AS_TMPDIR): Be namespace clean. + +2010-08-24 Ralf Wildenhues + + tests: fix AC_CACHE_CHECK to skip with bad shells. + * tests/base.at (AC_CACHE_CHECK): Skip test with malformed + config.site file if the shell does not report syntax errors + from a sourced file. Fixes test failure on AIX and FreeBSD. + Report from Rainer Tammer. + +2010-08-24 Paul Eggert + + AC_HEADER_STDBOOL: avoid spurious failure with modern xlc + * lib/autoconf/headers.m4 (AC_HEADER_STDBOOL): Move the "bool e = + &s;" test into the main program, as C99 might plausibly be + interpreted as not requiring support for this construction in + static initializers. Remove the "#if defined __xlc__" stuff, as + the bug is not present in recent xlc implementations, and they + reject the test for other (valid) reasons. People using ancient + xlc versions, if any, are suggested to update to fixed versions. + Reported by Ralf Wildenhues in the thread starting at: + http://lists.gnu.org/archive/html/bug-autoconf/2010-08/msg00103.html + +2010-08-24 Eric Blake + + AC_FUNC_GETLOADAVG: don't define SVR4 on cygwin + * lib/autoconf/functions.m4 (_AC_LIBOBJ_GETLOADAVG): Only define + SVR4 when -lkvm is required. + * THANKS: Update. + Reported by Yaakov Selkowitz. + +2010-08-23 Eric Blake + + AC_HEADER_STDBOOL: avoid spurious clang failure + * lib/autoconf/headers.m4 (AC_HEADER_STDBOOL): Drop gcc (and by + extension clang) check in favor of a gnulib test. Force failure, + rather than merely testing for a compiler extension. + * THANKS: Update. + Reported by Anders Kaseorg. + +2010-08-22 Ralf Wildenhues + + doc: AIX sed dislikes indented comments. + * doc/autoconf.texi (Limitations of Usual Tools) : Update. + +2010-08-19 Stefano Lattarini + + Fix autoreconf docs w.r.t. AUTOM4TE environment variable. + * doc/autoconf.texi (Using autoreconf to Update configure + Scripts): List `AUTOM4TE' among the environment variables + honored by autoreconf. + * bin/autoreconf.in ($help): Likewise. + +2010-08-17 Eric Blake + + doc: improve AS_VAR_IF details + * doc/autoconf.texi (Polymorphic Variables) : Make it + clear that user must supply quotes as needed. + * THANKS: Update. + Suggested by Randall Cotton. + +2010-08-16 Ralf Wildenhues + + Fix Autotest --errexit to exit after XPASSing tests. + * lib/autotest/general.m4 (AT_INIT) : + Exit after an unexpected passing test if $at_errexit. + * tests/autotest.at (errexit): Also try tests that xpass, skip, + xfail, or fail hard. + +2010-08-14 Eric Blake + + AC_INIT: allow bugreport to contain '?' + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Relax check. + * tests/base.at (AC_INIT with unusual version strings): Enhance + test. + * doc/autoconf.texi (Initializing configure): Document this. + * NEWS: Likewise. + * THANKS: Update. + Reported by Yavor Doganov and others. + +2010-08-10 Peter Rosin + + Keep testsuite files on unexpected pass. + * lib/autotest/general.m4 (AT_INIT) : + Don't cleanup the group directory when a test unexpectedly passes. + * tests/autotest.at (Cleanup): Check that an unexpected pass leaves + the test group directory intact. + +2010-08-10 Ralf Wildenhues + + Skip AC_FC_SRCEXT([f90]) tests with a Fortran 77 compiler in $FC. + * tests/fortran.at (AC_FC_FREEFORM with AC_FC_SRCEXT) + (AC_FC_FIXEDFORM with AC_FC_SRCEXT): Skip if the compiler cannot + handle files with .f90 extension. + Report by Luke Dalessandro. + + Fix testsuite failures with typical m4-x.y.z program suffix. + * tests/local.at (AT_CHECK_M4): Normalize hyphens and digits + after the `m4' program name. + * THANKS: Update. + Report by Luke Dalessandro. + +2010-08-06 Ralf Wildenhues + + Fix description of AC_CONFIG_TESTDIR to not mention atconfig.in. + * doc/autoconf.texi (Making testsuite Scripts): atconfig is not + created from an input template. + +2010-08-05 Bruno Haible + and Eric Blake + + AC_FUNC_ALLOCA: modernize + * lib/autoconf/functions.m4 (AC_FUNC_ALLOCA): Assume that alloca's + return type is 'void *', not 'char *'. Supply C89 prototype. + Reported by Thomas Klausner. + +2010-08-04 Ralf Wildenhues + + Fix testsuite failure due to bugs in third-party aclocal macros. + * tests/torture.at (Non-literal AC_CONFIG_SUBDIRS): Create a + hand-written aclocal.m4 file, so the -Werror test doesn't fail + over aclocal warnings about errors in third-party macro files. + Simplify test accordingly, calling autoreconf throughout. + Report by Bob Friesenhahn. + + Fix AC_LANG_SOURCE and AC_LANG_PROGRAM tests. + * tests/compile.at (AC_LANG_SOURCE example) + (AC_LANG_PROGRAM example): Fix broken sed script for + extracting the interesting part of the conftest.c file. + Fixes test failure on Haiku. + * THANKS: Update. + Report by Scott McCreary. + +2010-08-03 Eric Blake + + docs: mention bash bug with word splitting + * doc/autoconf.texi (Shell Substitutions): Document bash bug, and + zsh default behavior difference. + Reported by Ralf Wildenhues. + + docs: mention ksh bug with function syntax + * doc/autoconf.texi (Shell Functions): Document ksh93 limitation. + +2010-08-03 Ralf Wildenhues + + Fix typo in Autotest color test, for dash testsuite failure. + * tests/autotest.at (colored test results): Use exit not + Exit. Fixes test failure with dash 0.5.4. + +2010-08-02 Eric Blake + + docs: track recent copyright assignment + * AUTHORS: Add Peter Rosin. + +2010-08-02 Ralf Wildenhues + + Add testsuite exposure for last-minute fix in 2.67. + * tests/autotest.at (parallel args but non-working mkfifo): + New test, to expose the failure v2.66-23-g991183c avoided. + + Ensure unnamed test group categories are separated from previous. + * doc/autoconf.texi (Writing Testsuites) : Update + description. + * lib/autotest/general.m4 (AT_INIT) : Set banner + to single space, not empty line, once printed. For empty + banners, print a single empty line to separate them from a + previous test group category. + * tests/autotest.at (Banners): Insert another test group; adjust + tests accordingly. Extend test to cover semantic change. + * NEWS: Update. + +2010-07-31 Ralf Wildenhues + + Fix typos in perlpod docs. + * lib/Autom4te/ChannelDefs.pm, lib/Autom4te/Channels.pm, + lib/Autom4te/General.pm: Fix typos and spacing in perlpod + documentation and in comments. + +2010-07-29 Eric Blake + + docs: mention ksh file descriptor limitation + * doc/autoconf.texi (File Descriptors): Document issue with fd 10 + and above. + Reported by Ralf Wildenhues. + + docs: mention cd limitation + * doc/autoconf.texi (Limitations of Builtins) : Document + issues with empty argument. + +2010-07-29 Ralf Wildenhues + + Add missing index entries to manual. + * doc/autoconf.texi (Fortran Compiler, Language Choice): Add + index entries for AC_FC_DUMMY_MAIN, AC_LANG; reformat entry for + AC_LANG_ASSERT. + +2010-07-21 Eric Blake + + Release Version 2.67. + * NEWS: Mention the release. + + Prepare for release. + * maint.mk (PREV_VERSION_REGEXP): New macro, missed when + backporting update-NEWS_hash from gnulib. + * cfg.mk (old_NEWS_hash): Correctly generate. + * build-aux/gendocs.sh: Temporarily break sync from upstream, to + avoid including spurious directories in info source tarball. + + Avoid spurious testsuite failures. + * doc/autoconf.texi (Generating Sources): Don't mix gcc '-E' and + '-o -', since the former already implies stdout, while the latter + creates -.exe on cygwin. + * tests/compile.at (AC_LANG_SOURCE example) + (AC_LANG_PROGRAM example): Likewise. Also prevent any config.site + interference. + + Partially revert previous patch. + * lib/autotest/general.m4 (AT_INIT) : Changing + at_jobs here breaks output if -j2 was requested but shell is + insufficient to support parallel testing. + Reported by Ralf Wildenhues. + + Minor testsuite size reduction. + * lib/autotest/general.m4 (AT_INIT) : Ensure + at_jobs is 1. + (AT_SETUP, AT_CLEANUP): Factor initialization code... + (AT_INIT) : ...into new function. + Based in part on suggestion by Ralf Wildenhues. + +2010-07-20 Eric Blake + + Close job control fd before running tests. + * doc/autoconf.texi (File Descriptors): Clarify limitations. + * lib/autotest/general.m4 (AT_CLEANUP): Avoid leaking job control + fifo fd to user tests. + (AT_INIT): Delete comment, now that close is done elsewhere. + Suggested by Ralf Wildenhues. + +2010-07-20 Paul Eggert + and Eric Blake + + Plug race in parallel autotest. + * lib/autotest/general.m4 (AT_INIT) : Track + two fds to fifo in parent, to avoid race where parent can see EOF + before child opens fifo. Avoid any atomicity problems with tokens + larger than one byte. + * NEWS: Document the bug fix. + +2010-07-20 Eric Blake + + Another empty argument through expr workaround. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Detect empty + arguments. Reject empty file argument. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Check for missing argument. + + Also reject ' and newline from AC_INIT strings. + * lib/autoconf/general.m4 (_AC_INIT_LITERAL): Reject a couple more + problematic characters. + * tests/base.at (AC_INIT with unusual version strings): Enhance + test. + * doc/autoconf.texi (Initializing configure) : Further + clarifications, and clean up wording about use of m4_esyscmd. + * NEWS: Update previous news entry. + Suggested by Paolo Bonzini. + +2010-07-20 Ralf Wildenhues + + Let autoreconf pass warning flags to new-enough aclocal. + * bin/autoreconf.in ($aclocal_supports_warnings) + ($automake_supports_warnings): New globals. + (parse_args): Set and use them. Be sure to invoke `aclocal + --help' and `automake --help' just once each. + * NEWS: Update. + Prompted by report from Bruno Haible. + + Fix parsing of empty variable settings on the command line. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Work around + expr bug returning 0 instead of the empty string. + * lib/autotest/general.m4 (AT_INIT): Likewise. + + Fix typo in the manual. + * doc/autoconf.texi (AC_ACT_IFELSE vs AC_TRY_ACT): Fix typo. + +2010-07-19 Eric Blake + + Fix up AC_INIT vs. " issues, and document it. + * doc/autoconf.texi (Initializing configure): Improve + documentation on argument restrictions. + * NEWS: Tweak information. + * lib/autoconf/general.m4 (_AC_INIT_GENERAL): New macro, that also + rejects literal ". + (_AC_INIT_PACKAGE): Use it to plug hole in last patch. + * tests/base.at (AC_INIT with unusual version strings): Enhance + test. + +2010-07-19 Eric Blake + and Ralf Wildenhues + + Relax AC_INIT requirements for PACKAGE and VERSION strings again. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_HEREDOC_IF): New macro. + (_AS_LITERAL_HEREDOC_IF, _AS_LITERAL_HEREDOC_IF_YES) + (_AS_LITERAL_HEREDOC_IF_NO): New helper macros. + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Use + AS_LITERAL_HEREDOC_IF for PACKAGE and VERSION strings. + * tests/base.at (AC_INIT with unusual version strings): New test. + * tests/m4sh.at (AS@&t@_LITERAL_IF): Extend test. + * NEWS: Update. + +2010-07-19 Eric Blake + + Fix testsuite failures from previous patch. + * lib/autoconf/c.m4 (_AC_PROG_PREPROC_WORKS_IFELSE): Also remove + conftest.i when preprocessor tests break out of a loop. + +2010-07-19 Ralf Wildenhues + + Allow inspecting AC_PREPROC_IFELSE output in true branch. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE_BODY): Redirect + preprocessor output to conftest.i rather than /dev/null. + (_AC_PREPROC_IFELSE): Remove conftest.i in the postprocessing. + * tests/compile.at (Order of user actions and cleanup): Extend + test in the ACTION-IF-TRUE branch. + * doc/autoconf.texi (Running the Preprocessor): Document new + feature. + * NEWS: Update. + + Fix AC_FC_LIBRARY_LDFLAGS detection for BlueGene xlf -qipa. + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Ignore + '-link', added spuriously when -qipa is used with the XL + Fortran compilers on BlueGene. + + manual: compiler flags -D and -L should not be followed by space + * doc/autoconf.texi (Preset Output Variables): Remove space + between -D and -L flags and their arguments, traditional cpp + implementations like Solaris 10, IRIX 6.5, OSF Tru64 5.1D, + AIX 5.3 do not accept it. + +2010-07-10 Ralf Wildenhues + + Fix comment typo in the manual. + * doc/autoconf.texi (Generic Compiler Characteristics): Refer + to the right test in the example marker comment. + Spotted by Eric Blake. + +2010-07-10 Ralf Wildenhues + + New Fortran macro AC_FC_LINE_LENGTH. + * lib/autoconf/fortran.m4 (AC_FC_LINE_LENGTH): New macro. + * doc/autoconf.texi (Fortran Compiler): Document it. + * tests/fortran.at (AC_FC_LINE_LENGTH): New test. + * NEWS: Update. + + Fix wording about AC_CONFIG_SUBDIRS warning. + * doc/autoconf.texi (Subdirectories): We warn, not error, about + nonexistent config subdirs, but only at configure run time. + +2010-07-10 Eric Blake + and Ralf Wildenhues + + Fix regression of AC_CHECK_SIZEOF on pointer types. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): Translate `*' to `p' + when checking literal-ness of the type, for pointer types. + * lib/m4sugar/m4sh.m4 (_AS_TR_SH): Also consider `*' as literal. + (_AS_TR_CPP): Likewise. + * tests/semantics.at (AC_CHECK_ALIGNOF struct): When checking + for numeric answer, be sure to not allow variable references. + (AC_CHECK_SIZEOF struct): Likewise. Also, test the + `AC_CHECK_SIZEOF([int *])' example from the manual. + * doc/autoconf.texi (Generic Compiler Characteristics): Add + example marker. + * NEWS: Update. + Reports by Nishio Futoshi and Roberto Bagnara. + +2010-07-08 Eric Blake + and Ralf Wildenhues + + Fix regression of AC_CONFIG_SUBDIRS with multiple arguments. + * lib/autoconf/status.m4 (AC_CONFIG_SUBDIRS): Do not assume the + argument is a single word. + * tests/torture.at (Deep Package): Extend test to cover this. + (Non-literal AC_CONFIG_SUBDIRS): New test. + * doc/autoconf.texi (Subdirectories): Add example marker. + * NEWS: Update. + Report by Bruno Haible. + +2010-07-04 Stefano Lattarini + + Fix minor copy&paste leftover in m4sh tests. + * tests/m4sh.at (AS@&t@_TR_SH and AS@&t@_TR_CPP): Remove + useless variables assignements ($var, $vAr, $VAR). + +2010-07-04 Ralf Wildenhues + + Fix testsuite to not trigger Solaris sh for bug. + * tests/torture.at (Torturing config.status) + (Substitute a 2000-byte string) + (Substitute and define special characters) + (Substitute a newline): Quote first argument in for list so + that it does not look like an assignment. + +2010-07-02 Eric Blake + + Post-release administrivia. + * maint.mk (NEWS_hash): Define. + * NEWS: Add header line for next release. + * .prev-version: Record previous version. + * cfg.mk (old_NEWS_hash): Auto-update. + + Release Version 2.66. + * NEWS: Mention the release. + +2010-07-02 Eric Blake + + Pick up some maint.mk improvements from gnulib. + * configure.ac (AM_INIT_AUTOMAKE): Require 1.11, and build xz + archives by default now. + * maint.mk (gzip_rsyncable): Avoid non-portable echo. + (VC-tag): Depend on gpg_key_ID. + (PREV_VERSION): Don't parse error as version. + (announcement): Populate email addresses with defaults. + (emit_upload_commands, web-manual): Reflect changes in scripts. + (update-NEWS-hash, emit-commit-log, release-prep): New macros. + * cfg.mk (announcement_Cc_, announcement_mail_headers_): Override + defaults. + * HACKING: Modernize a bit. + + Resync upstream files. + * GNUmakefile: Run 'make fetch'. + * build-aux/announce-gen: Likewise. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gendocs.sh: Likewise. + * build-aux/git-version-gen: Likewise. + * build-aux/gnupload: Likewise. + * build-aux/texinfo.tex: Likewise. + * build-aux/vc-list-files: Likewise. + * doc/gendocs_template: Likewise. + * doc/gnu-oids.texi: Likewise. + * doc/make-stds.texi: Likewise. + * doc/standards.texi: Likewise. + * lib/Autom4te/Channels.pm: Likewise. + * lib/Autom4te/Configure_ac.pm: Likewise. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/XFile.pm: Likewise. + + Make AS_TR_SH and AS_TR_CPP similar. + * lib/m4sugar/m4sh.m4 (_AS_TR_CPP_LITERAL): Avoid underquoting. + (_AS_TR_CPP_INDIR): Handle all polymorphic variables. + * tests/m4sh.at (AS@&t@_TR_SH and AS@&t@_TR_CPP): New test. + * NEWS: Document the fix. + Reported by Bruno Haible. + + Reduce startup cost of autotest. + * lib/autotest/general.m4 (_AT_FINISH) : Rather than + doing a recursive find, limit ourselves to top ChangeLog only. + Reported by Ralf Wildenhues. + +2010-07-02 Ralf Wildenhues + + New macro AC_FC_FIXEDFORM, improved AC_FC_FREEFORM, coverage. + * lib/autoconf/fortran.m4 (_AC_FC_DIALECT_YEAR): Fix typo in + comment. + (AC_FC_FREEFORM): Update list of known options for Sun, HP, + Lahey/Fujitsu Fortran compilers. Use M4 quoting consistently. + (AC_FC_FIXEDFORM): New macro. + * tests/fortran.at (AC_FC_DUMMY_MAIN usage, AC_FC_MAIN usage): + Use AC_FC_FIXEDFORM, to avoid testsuite failure with FC=xlf95. + (AC_FC_FREEFORM with AC_FC_SRCEXT, AC_FC_FIXEDFORM) + (AC_FC_FIXEDFORM with AC_FC_SRCEXT): New tests. + * tests/mktests.sh: No need to exclude AC_FC_FREEFORM, it uses + AC_LANG_PUSH/AC_LANG_POP. + * doc/autoconf.texi (Fortran Compiler): Document it. + * NEWS: Update. + +2010-07-02 Eric Blake + + Optimize AS_BOX. + * lib/m4sugar/m4sh.m4 (AS_BOX): Use less m4 time. + (_AS_BOX_LITERAL): Use fewer forks in the common case. + * doc/autoconf.texi (Common Shell Constructs) : Document + the macro. + * NEWS: Mention it. + + Use new AS_LITERAL_IF argument when appropriate. + * lib/m4sugar/m4sh.m4 (AS_VAR_SET): Reduce m4 overhead. + (AS_VAR_IF, AS_VAR_TEST_SET): Provide shorter variant for simple + references. + Suggested by Bruno Haible. + + Add tests for AS_BOX. + * tests/m4sugar.at (m4@&t@_text_box): New test. + * tests/m4sh.at (AS@&t@_BOX): Likewise. + * lib/m4sugar/m4sugar.m4 (m4_text_box): Support comma. + * doc/autoconf.texi (Text processing Macros) : + Document further limitations. + + Add optional argument to AS_LITERAL_IF. + * lib/m4sugar/m4sh.m4 (_AS_LITERAL_IF): Rewrite to generate macro + name, without using m4_cond. + (_AS_LITERAL_IF_, _AS_LITERAL_IF_YES, _AS_LITERAL_IF_NO): New + helpers. + (AS_LITERAL_IF, AS_LITERAL_WORD_IF, _AS_TR_SH, _AS_TR_CPP) + (_AS_VAR_PUSHDEF): Adjust callers. + * lib/autoconf/types.m4 (AC_CHECK_ALIGNOF): Relax restrictions on + invalid bytes, since this allows inline struct layouts. + (_AC_CHECK_ALIGNOF): New helper macro. + * tests/m4sh.at (AS@&t@_LITERAL_IF): Update test. + * doc/autoconf.texi (Polymorphic Variables) : + Update documentation. + + Use AS_LITERAL_WORD_IF as appropriate. + * lib/autoconf/autoheader.m4 (AH_VERBATIM): Use new macro. + * lib/autoconf/general.m4 (AC_REQUIRE_AUX_FILE, AC_CACHE_VAL) + (AS_CACHE_CHECK, AC_DEFINE_TRACE, _AC_LIBOBJ): Likewise. + * lib/autoconf/libs.m4 (AC_CHECK_LIB): Likewise. + * lib/autoconf/status.m4 (AC_CONFIG_SUBDIRS): Likewise. + * lib/m4sugar/m4sh.m4 (AS_UNSET, AS_VAR_COPY, AS_VAR_GET) + (AS_VAR_IF, AS_VAR_SET, AS_VAR_TEST_SET): Likewise. + + Add AS_LITERAL_WORD_IF. + * lib/m4sugar/m4sh.m4 (_AS_LITERAL_IF): Also reject shell quoting + characters as non-literal, and provide way to reject space. + (AS_LITERAL_WORD_IF): New macro. + * doc/autoconf.texi (Polymorphic Variables) : + Document new macro. Fix example to match reality. + * NEWS: Document change and new macro. + * tests/m4sh.at (AS@&t@_LITERAL_IF): Update test. + + Optimize AC_DEFINE. + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Avoid overhead of + AS_LITERAL_IF. + +2010-07-02 Stefano Lattarini + and Eric Blake + + Describe a Solaris /bin/sh bug w.r.t. for loops. + * doc/autoconf.texi (Limitations of Shell Builtins) : + Document a bug of the 'for' builtin in Solaris /bin/sh, w.r.t. + tokens seeming variable assignment in the list of arguments. + +2010-06-23 Ralf Wildenhues + + Improve VPATH handling in config.status for non-Automake projects. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Be sure not + to remove references to a subdir of srcdir. Fix treatment of + multiple colon-separated VPATH entries. + * tests/torture.at (VPATH): New test. + Report by Keith Marshall. + + Further improve docs about nested double-quotes and backquotes. + * doc/autoconf.texi (Shellology): Remove anchor for pdksh. + Move quoting bug example to ... + (Shell Substitutions): ... here. Document which behavior is + specified by Posix. + + Coverage for Fortran compiler macros. + * tests/fortran.at (AC_OPENMP and Fortran 77) + (AC_OPENMP and Fortran): Simplify, using AT_CHECK_CONFIGURE. + (AC_F77_DUMMY_MAIN usage, AC_FC_DUMMY_MAIN usage) + (AC_F77_MAIN usage, AC_FC_MAIN usage, AC_F77_FUNC usage) + (AC_FC_FUNC usage, AC_FC_SRCEXT usage, AC_FC_FREEFORM): New + tests. + * doc/autoconf.texi (Fortran Compiler): Use GNU coding style + on C code snippets. Add markers for tested examples. + Suggest AC_FC_FREEFORM for source file extensions which the + compiler might not natively support but which are accepted + with help from AC_FC_SRCEXT. Suggest AC_CONFIG_HEADERS for + setups using one of the AC_*MAIN macros. + + Accept any nonzero exit status upon config.status write failure. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Normalize nonzero status to 1 for writing to /dev/full, for HP-UX + 11.31 cat which exits 2. + + Fix testsuite failure with Tru64 preprocessor. + * tests/compile.at (Order of user actions and cleanup): Add + incomplete comment to provoke failure with Tru64/OSF 5.1 cc + preprocessor. + +2010-06-22 Ralf Wildenhues + and Eric Blake + + Further clarification on sed -e portability. + * doc/autoconf.texi (Limitations of Usual Tools) : Clarify + more about sed -e and Posix limitations. + +2010-06-22 Bruno Haible + + Document how to use literal newlines in makefile rules. + * doc/autoconf.texi (Newlines in Make Rules): New section. + + Document how to write comments in makefile rules. + * doc/autoconf.texi (Comments in Make Rules): Mention a workaround + syntax. + +2010-06-22 Ben Pfaff + + Document how to propagate variables to submakes. + * doc/autoconf.texi: Describe technique used by Automake to + propagate variables to submakes in more detail. + +2010-06-22 Peter Johansson (tiny change) + + Be consistent in doc example. + * doc/autoconf.texi: (Polymorphic Variables) be consistent in code + example and output + +2010-06-22 Ralf Wildenhues + + Add comments for vim syntax highlighting. + * doc/autoconf.texi: Restore font-lock in some examples using + $$, for vim. + + Formatting cleanups for optional arguments. + * doc/autoconf.texi (Configuration Actions, Help Formatting) + (External Software): Use @r{} for brackets denoting optional + arguments, where @ovar is not safe to use. + + Clarify nested double-quotes and backquotes shell issues. + * doc/autoconf.texi (Shellology): New anchor for pdksh. + (Shell Substitutions): Link to it for escaped double-quotes + within double-quoted backquotes; add ksh example for unescaped + inner double-quotes problem. + + Mention Tru64 5.1 fgrep limitation with empty patterns. + * doc/autoconf.texi (Limitations of Usual Tools): Update. + + Overhaul the manual, esp. the Autotest chapter. + * doc/autoconf.texi (Installation Directory Variables): + Replace some uses of @var with @code. + (Special Shell Variables): Fix misordered paragraph about IFS. + (Writing Testsuites): Include paragraph following AT_TESTED in + the macro definition. + (testsuite Invocation): Failed tests are not rerun. + (testsuite Scripts, Autotest Logs, testsuite Invocation) + (Making testsuite Scripts): Minor edits for consistency and + language. + +2010-06-18 Bruno Haible + + Document sed -e limitation. + * doc/autoconf.texi (Limitations of Usual Tools): Mention portability + problem of sed -e option with script fragments. + +2010-06-17 Ralf Wildenhues + + Document, test, and fix AT_ARG_OPTION, AT_ARG_OPTION_ARG. + * lib/autotest/general.m4 (_AT_ARG_OPTION): Fix translation of + hyphens to underscores when turning option names to variables. + Avoid macro name concatenation garbage with trailing `dnl'. + (AT_ARG_OPTION, AT_ARG_OPTION_ARG): Overhaul macro description. + The OPTIONS are space-separated, not comma-separated. The + negative form of AT_ARG_OPTION is prefixed with `--no-'. + * tests/autotest.at (AT@&t@_ARG_OPTION, AT@&t@_ARG_OPTION_ARG): + New tests. + * NEWS: Update. + * doc/autoconf.texi (Writing Testsuites): Document AT_ARG_OPTION + and AT_ARG_OPTION_ARG. + (testsuite Invocation): Call the thingies passed to the + testsuite options, not arguments. Note that the testsuite + author may add further package-specific options. + + Autotest: enable colored test results. + * lib/autotest/general.m4 (HELP_TUNING_BEGIN): New diversion. + (HELP_TUNING, HELP_OTHER, HELP_END): Bump diversion numbers. + (AT_INIT): Accept + --color and --color=never|auto|always. If desired, colorize + test results and testsuite summary on standard output. + [HELP_TUNING]: Divert content instead to ... + [HELP_TUNING_BEGIN]: ... this diversion, m4_wrapped until the + end, when we know whether AT_COLOR_TESTS has been specified. + (AT_COLOR_TESTS): New macro, set the default for color to auto. + * doc/autoconf.texi (Writing Testsuites): Document it. + (testsuite Invocation): Document --color* options. + * tests/local.at: Call AT_COLOR_TESTS for Autoconf's testsuite. + * tests/autotest.at (color test results): New test, mirroring + color.test from Automake. + * NEWS: Update. + +2010-06-15 Ralf Wildenhues + + Avoid texinfo bug with backslashes in macro arguments. + * doc/autoconf.texi (Text processing Macros) + (Common Shell Constructs): Do not use @dvar with backslashes. + +2010-06-14 Eric Blake + + Make CONFIG_SITE handling more robust. + * lib/autoconf/general.m4 (AC_SITE_LOAD): Avoid leading - and path + search, and check for failure to load. + * tests/base.at (AC_CACHE_CHECK): Enhance test. + * doc/autoconf.texi (Site Defaults): Mention that CONFIG_SITE + works best as an absolute path. + * NEWS: Document the semantic change. + +2010-03-13 Bruno Haible + and Ralf Wildenhues + + Allow plus signs in AC_ARG_ENABLE and AC_ARG_WITH. + * doc/autoconf.texi (External Software): Mention that AC_ARG_WITH + accepts packages with a + sign in it. + (Package Options): Likewise for AC_ARG_ENABLE. + * lib/autoconf/general.m4 (_AC_ENABLE_IF): Also replace '+' with '_'. + * tests/base.at (AC_ARG_ENABLE and AC_ARG_WITH): New test. + * NEWS: Update. + +2010-06-14 Ralf Wildenhues + + Autotest: simplify logic to compute test group result. + * lib/autotest/general.m4 (AT_INIT): Compactify result + computation logic. + + New Autotest testsuite option --recheck. + * lib/autotest/general.m4 (AT_INIT): New variable $at_recheck. + Escape hyphen in $at_dir early. Accept command line switch + --recheck. Set $at_suite_log early, based on --directory + switch; with --recheck, include the list of FAILed and XPASSed + tests from old testsuite.log file in $at_groups. Document + --recheck in --help output. + * tests/autotest.at (recheck): New test. + * doc/autoconf.texi (testsuite Invocation): Document --recheck. + * NEWS: Update. + +2010-06-14 Karl Berry (tiny change) + + Clarify comment about old system. + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Prefer GNU/Linux, + and note that bug has long since been fixed. + +2010-06-08 Eric Blake + + Run libtool test with modern libtool. + * tests/foreign.at (Libtool): Request that libtoolize install + auxiliary files. Assume libtool 2.x is modern. + +2010-06-08 Ralf Wildenhues + + Coverage and doc fixes for AC_LANG_SOURCE and AC_LANG_PROGRAM. + * tests/compile.at (AC_LANG_SOURCE, AC_LANG_SOURCE(C++)) + (AC_LANG_SOURCE example, AC_LANG_PROGRAM example): New tests. + * doc/autoconf.texi (Generating Sources): Add markers for tested + examples; update quoting, and update AC_INIT usage to also set + optional URL arguments. Mention that the examples require gcc. + Prompted by report from Brian J. Murrell. + + Make AS_SET_CATFILE polymorphic, and add testsuite coverage. + * lib/m4sugar/m4sh.m4 (AS_SET_CATFILE): Use AS_VAR_SET to set + the variable. + * tests/m4sh.at (AS@&t@_SET_CATFILE): New test. + * doc/autoconf.texi (Common Shell Constructs): Document that + AS_SET_CATFILE is polymorphic in its VAR argument now. + * NEWS: Update. + + Testsuite coverage for AC_COPYRIGHT and AT_COPYRIGHT. + * tests/autotest.at (AT@&t@_COPYRIGHT): New test. + * tests/base.at (AC@&t@_COPYRIGHT): Likewise. + + Testsuite coverage for __file__ and __line__. + * tests/m4sugar.at (__file__ and __line__): New test. + + Testsuite coverage for AC_CACHE_VAL and caching semantics. + * tests/base.at (AC_CACHE_CHECK): Extend test. + (AC_CACHE_LOAD): New test. + * tests/torture.at (Configuring subdirectories): Also test + --config-cache with AC_CONFIG_SUBDIRS. + * doc/autoconf.texi (Caching Results): Annotate code snippets + which are tested in the test suite. + (Cache Files): Documented cache variables may be used on the + configure command line to override individual entries in the + cache file. + + Clarify OpenBSD sh errexit issue with compound commands. + * doc/autoconf.texi (Limitations of Builtins): Only the last + command in a compound list is problematic. + Tested on OpenBSD 4.4. + +2010-06-07 Eric Blake + + Properly quote AC_PREREQ during autoupdate. + * lib/autoconf/general.m4 (AC_PREREQ): Follow consistent quoting + style for AC_PREREQ. + * tests/tools.at (autoupdating AC_PREREQ): Update expected + results. + Reported by NightStrike. + +2010-06-01 Ralf Wildenhues + + Documentation and tests for the AC_CHECK_DECL change. + * lib/autoconf/general.m4 (_AC_CHECK_DECL_BODY): Squash trailing + spaces in as_decl_name. + (_AC_CHECK_DECLS): Likewise for the define. + * tests/semantics.at (AC_CHECK_DECLS): Extend test. + * doc/autoconf.texi (Generic Declarations): Update. + * NEWS: Update. + +2010-06-01 Joern Rennecke (tiny change) + + Generalize AC_CHECK_DECL for C++: allow optional arguments. + * general.m4 (_AC_CHECK_DECL_BODY): Process trailing function + argument types as arguments to use for C++. + (_AC_CHECK_DECLS): Filter out trailing function argument types + when generating the HAVE_DECL_* macro. + +2010-05-25 Stefano Lattarini + Eric Blake + + Don't expose AC_{COMPILE,LINK}_IFELSE internals in documentation. + * doc/autoconf.texi (Runtime) : Suggest to use + `conftest$EXEEXT' rather than `conftest$ac_exeext' to acces the + just-linked program file. + (Runtime) : Suggest to use `conftest.$OBJEXT' + rather than `conftest.$ac_object' to access the just-compiled + object file. Also, refer to the object file as "just-compiled" + rather than "just-linked". + +2010-05-20 Eric Blake + + Mention another line-counting alternative. + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + how to use sed to count lines. + Suggested by Paolo Bonzini. + +2010-05-12 Eric Blake + + Document the grep workaround. + * doc/autoconf.texi (Limitations of Usual Tools) : Document + the bug. + +2010-05-12 Mark Hessling (tiny change) + + Work around QNX4 grep bug. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Count ^ + rather than $ to avoid QNX4 grep bug. + * THANKS: Update. + +2010-05-11 David Reiss (tiny change) + + Improve Erlang documentation. + * doc/autoconf.texi (Erlang Libraries): Document actual default + values. + * THANKS: Update. + +2010-05-11 Eric Blake + + Fix typo in previous patch. + * doc/autoconf.texi (File Descriptors): Add end '. + Reported by Ralf Wildenhues. + + Mention how to silence program probes. + * doc/autoconf.texi (File Descriptors): Document how to silence a + program probe. + +2010-04-26 Ralf Wildenhues + + Error and warning message formatting cleanups. + * doc/autoconf.texi (Autoconf Language, Generic Structures): + Do not capitalize the first word in error messages, do not end + them with a period. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS, AC_MSG_FAILURE): + Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Likewise. + * lib/autotest/general.m4 (AT_INIT, at_fn_group_prepare): + Likewise. + * m4/m4.m4 (AC_PROG_GNU_M4): Likewise. + * tests/base.at (AC_TRY_COMMAND): Likewise. + * tests/torture.at (datarootdir workaround): Adjust expected + message. + + Fix placing of ellipses in English text. + * lib/autoconf/general.m4 (_AC_INIT_HELP): Be sure to add a + space before `...' in natural language text. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL_BODY): + Likewise. + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): Likewise. + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Likewise. + * tests/suite.at: Likewise. + * tests/torture.at (@%:@define header templates): Likewise. + + Ensure autotest tests have an atconfig file, for testsuite -v. + * tests/autotest.at (AT_CHECK_AT_PREP): Create a default + atconfig file in the directory of the testsuite. + (AT_CHECK_AT_TITLE): Also check that `./micro-suite -v' output + does not contain empty $at_srcdir expansion. + (srcdir propagation): Remove the atconfig file generated by + AT_CHECK_AT_PREP. Check each suite invocation for $at_srcdir + expansion. + + Fix autotest testsuite -v output to print test group title. + * lib/autotest/general.m4 (AT_CLEANUP): Actually print test + title in verbose output. Fixes AUTOCONF-2.57-101-gc102ed8 + regression. + * tests/autotest.at (AT_CHECK_AT_TITLE): Amend macro to check + for test title in -v output. + +2010-04-26 Eric Blake + + Clarify octal escapes with tr. + * doc/autoconf.texi (Limitations of Usual Tools): Carriage return + is portable in octal, but not newline. + +2010-04-22 Joel James Adamson (tiny change) + + Add a paragraph to FAQ on Debugging configure scripts. + * doc/autoconf.texi (Debugging): Mention inspecting config.log. + * THANKS: Update. + +2010-04-21 Mike Frysinger (tiny change) + + Fix typo in doc example. + * doc/autoconf.texi (Subdirectories): Fix typo. + +2010-04-05 Eric Blake + + Fix m4_cr_all for EBCDIC. + * lib/m4sugar/m4sugar.m4 (m4_cr_all): Swap * and $, so that we + don't end up with $* in EBCDIC. + * NEWS: Document the fix. + * THANKS: Update. + Reported by Steve Goetze. + +2010-03-28 Ralf Wildenhues + + Do not use @acronym in the manual. + * doc/autoconf.texi: Remove all usage of @acronym. + Suggested by Karl Berry. + + Do not use @sc in the manual. + * doc/autoconf.texi: Remove all usage of @sc in the manual. + Suggested by Karl Berry. + +2010-03-12 Ralf Wildenhues + + Fix wrong comment in testsuite. + * tests/m4sugar.at (m4@&t@_warn): Remove copy&pasted comment. + + Formatting cleanups in macro comments. + * lib/autoconf/c.m4, lib/autoconf/erlang.m4, + lib/autoconf/fortran.m4, lib/autoconf/functions.m4, + lib/autoconf/general.m4, lib/autoconf/lang.m4, + lib/autoconf/programs.m4, lib/autoconf/specific.m4, + lib/autoconf/status.m4, lib/autoconf/types.m4, + lib/autotest/general.m4, lib/autotest/specific.m4, + lib/m4sugar/m4sh.m4, lib/m4sugar/m4sugar.m4, + tests/autotest.at, tests/local.at, tests/m4sh.at, + tests/semantics.at, tests/tools.at, tests/torture.at: Fix macro + comment format. + +2010-03-05 Ralf Wildenhues + + manual: index strings containing colon in non-info outputs. + * doc/autoconf.texi (Quadrigraphs, Shell Substitutions): Produce + index entries for concepts containing a colon in output formats + other than info. + + Update copyright years for files generated by mktests.sh. + * tests/mktests.sh: Update copyright years for generated files. + +2010-03-04 Eric Blake + + Document AC_LANG_CONFTEST semantic change. + * doc/autoconf.texi (Generating Sources) : + Enhance documentation, to show that semantic change in 2.63b was + intentional. + * THANKS: Update. + Reported by Brian J. Murrell, analyzed by Ralf Wildenhues. + +2010-03-04 Peter Johansson (tiny change) + + Autoconf Macro Archive URL has changed. + * doc/autoconf.texi (Introduction, Coding Style, Defining + Directories): The Autoconf Macro Archive is officially `GNU'. + Update URL. + +2010-03-02 Eric Blake + + Fix shell code in AS_TR_SH documentation. + * doc/autoconf.texi (Common Shell Constructs) : Fix + example to expand to valid shell code. + Reported by Ralf Wildenhues. + + Improve documentation on AC_{COMPILE,LINK}_IFELSE. + * doc/autoconf.texi (Running the Compiler): Mention that the + object file is available after a successful compile. + (Running the Linker): Likewise for the linker output. + Suggested by Paolo Bonzini. + + Fix typo in docs. + * doc/autoconf.texi (Conditional constructs) : Fix + typo. + +2010-03-02 Ralf Wildenhues + + Fix AS_ERROR for FreeBSD sh. + * lib/m4sugar/m4sh.m4 (_AS_ERROR_PREPARE): Rewrite as_fn_error + to take additional first argument STATUS instead of transporting + $? across shell function entry, which does not work with FreeBSD + sh. Shift all other arguments by one, adjust. + (AS_ERROR): Pass EXIT-STATUS, defaulting to $?, to as_fn_error. + Report by Václav Haisman. + + Fix `autom4te cache creation' testsuite failure on FreeBSD. + * tests/tools.at (autom4te cache creation): Normalize exit + status of failed redirection to 1, may be 2 with FreeBSD sh. + * THANKS: Update. + Report by Václav Haisman. + + Fix Autotest tracing of shell pipelines for FreeBSD sh. + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): Do not trace + commands that contain [^|]|[^|], a likely shell pipeline. + * tests/local.at (_AT_CHECK_ENV): Turn off tracing for egrep | + grep pipeline. + * doc/autoconf.texi (File Descriptors): Document limitation. + * tests/autotest.at (Trace output): New test. + +2010-03-01 Eric Blake + + Update file flow diagram to mention Automake. + * doc/autoconf.texi (Making configure Scripts): Avoid confusion + with listing Makefile.in twice on one line. Add a diagram showing + how automake fits into the picture. + Reported by santilín. + +2010-02-26 Eric Blake + + Optimize AC_REPLACE_FUNCS. + * lib/autoconf/functions.m4 (_AC_REPLACE_FUNC): New helper macro. + (AC_REPLACE_FUNCS): Use it to reduce forks when checking for + replacements, by using literal rather than shell variable. + + Document how to safely override CFLAGS default. + * doc/autoconf.texi (C Compiler) : Document a way to + change the default CFLAGS. + (C++ Compiler) : Likewise, for CXXFLAGS. + Reported by Monty Taylor; wording suggested by Paolo Bonzini. + + Document that Autoconf relies on IFS. + * doc/autoconf.texi (Special Shell Variables) : Add details + about use of IFS within configure script. + * THANKS: Update. + Reported by Arkadiusz Miskiewicz. + + Recommend latest m4 release. + * README: Bump recommendation to m4 1.4.14 (minimum remains + 1.4.6). + * doc/autoconf.texi (Introduction): Likewise. + * m4/m4.m4 (AC_PROG_GNU_M4): Likewise. + +2010-02-23 Ralf Wildenhues + + Fix testsuite failures due to setting of $U. + * tests/local.at (_AT_CHECK_ENV): Ignore setting of $U. + +2010-02-10 Eric Blake + + Avoid $U if it is not initialized. + * lib/autoconf/general.m4 (_AC_LIBOBJS_NORMALIZE): Ensure $U is + set if automake did not define it. + * THANKS: Update. + Reported by Heiko Schlichting, via Julien Élie. + +2010-01-24 Ralf Wildenhues + + Fix substitution of carriage return on Darwin. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Set + ac_cs_awk_cr to '\\r', so that sed portably expands this to '\r' + rather than a literal carriage return, to fix substitution on + Darwin. Regression introduced in 2.63b. + Report by Peter O'Gorman. + +2010-01-21 Dmitry V. Levin + + Fix test failure when a shell uses $TMPDIR for here-documents. + * tests/tools.at (autotools and whitespace in file names): Create + $TMPDIR before potential use like in other whitespace tests. + +2010-01-20 Paolo Bonzini + + Add recommendation on (not) unsetting IFS. + * doc/autoconf.texi (Special shell variables): Explain why it's + better not to unset IFS. + +2010-01-19 Ralf Wildenhues + + config.status: consistent exit status with nonexistent config file input. + * lib/autoconf/status.m4 (_AC_OUTPUT_MAIN_LOOP): Ensure we + exit with status 1 rather than with that of 'false', for + reproducibility. + (AC_OUTPUT): Ensure to exit 1 in case of config.status failure. + * tests/torture.at (Missing templates): Also test code path + for $srcdir != '.'. + Report by Tim Rice. + +2010-01-13 Eric Blake + + Fix previous example. + * doc/autoconf.texi (Here-Documents): Touch up the example to + match output to sample command line. + + Document here-doc pitfall. + * doc/autoconf.texi (Here-Documents): Mention problem with <<- + operator. + Reported by Jim Meyering. + +2010-01-12 Eric Blake + + Typo fix in earlier commit. + * doc/autoconf.texi (Autoconf Language): Fix typo. + +2010-01-12 Ralf Wildenhues + + Allow AC_FUNC_MKTIME to work with C++. + * lib/autoconf/functions.m4 (AC_FUNC_MKTIME): ANSIfy KnR function + definitions. Use `const char*' for character literals; cast them + to `char*' for putenv. + +2010-01-11 Ralf Wildenhues + + Export AUTOM4TE in tests/atlocal.in, for aclocal. + * tests/atlocal.in: Set and export $AUTOM4TE, for aclocal. + Report by Tim Rice. + +2010-01-08 Eric Blake + + Make autotest example act better with automake. + * doc/autoconf.texi (Making testsuite Scripts): Rely on automake + feature for recommended autotest snippet, following our own use. + + Clarify language on handling of opening parenthesis. + * doc/autoconf.texi (Autoconf Language): Give an example of + improper argument passing. + * THANKS: Update. + Reported by Juan Carlos Hurtado. + +2010-01-06 Ralf Wildenhues + + Don't fail autom4te preselection test due to different Automake. + * tests/tools.at (autom4te preselections): If the cache test + fails, extract the Automake version from the toplevel + Makefile.in file of the source tree; skip, rather than fail + the test group if the automake program has a different version. + * THANKS: Update. + Report by Dieter Jurzitza, fix suggested by Eric Blake. + +2010-01-06 Peter Breitenlohner + Ralf Wildenhues + + Fix AC_CONFIG_LINKS to generated files when srcdir is absolute. + * lib/autoconf/status.m4 (_AC_OUTPUT_LINK): Check $ac_source, + not $srcdir, for being relative or absolute. + * tests/torture.at (AC_CONFIG_LINKS): New test. + (AC_CONFIG_LINKS and identical files): Extend test, avoid some + forks. + Report, patch and testcase example by Peter Breitenlohner. + +2010-01-05 Eric Blake + + Improve release automation. + * maint.mk (gnulib_dir, gnulib-version, bootstrap-tools) + (announcement): Copy from latest gnulib maint.mk. + * cfg.mk (announce_gen, gpg_key_ID): Delete. + (bootstrap-tools): Override the default. + + Update upstream files. + * GNUmakefile: Update via 'make fetch'. + * build-aux/announce-gen: Likewise. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gendocs.sh: Likewise. + * build-aux/gnupload: Likewise. + * build-aux/move-if-change: Likewise. + * build-aux/update-copyright: Likewise. + * build-aux/vc-list-files: Likewise. + * doc/standards.texi: Likewise. + * cfg.mk (update-copyright-env): Enforce wrap column. + + Update copyright year. + All files changed to add 2010, via 'make update-copyright'. + +2009-12-31 Bruno Haible + + Improve documentation on Solaris tr bugs. + * doc/autoconf.texi (Limitations of Usual Tools) : Refine + description of NUL handling by Solaris tr. + +2009-12-31 Eric Blake + + Another tr tweak. + * doc/autoconf.texi (Limitations of Usual Tools) : Clarify + previous commit. + Reported by Ralf Wildenhues. + +2009-12-29 Eric Blake + + Improve documentation on tr portability. + * doc/autoconf.texi (Limitations of Usual Tools) : Refine + description of NUL handling. Document set size issue. + Reported by Bruno Haible. + + Fix comment in AC_CHECK_DECLS. + * lib/autoconf/general.m4 (AC_CHECK_DECL): Document the includes + argument to the shell function. + +2009-12-15 Ralf Wildenhues + + Add testsuite exposure for shtool usage. + * tests/foreign.at (shtool): New test. + Report by Dmitry Grebeniuk. + +2009-12-12 Eric Blake + + Improve wording about m4 quote characters. + * doc/autoconf.texi (Autoconf Language): Autoconf quote characters + come from m4sugar, not raw m4. + (Active Characters): Mention that it is m4sugar which changes + quotes from `' to []. + * THANKS: Update. + Suggested by Josef Vukovic. + +2009-12-12 Ralf Wildenhues + + Revert "Improve AC_CONFIG_AUX_DIRS a bit." to fix shtool usage. + * lib/autoconf/general.m4 (AC_CONFIG_AUX_DIRS): Revert test for + shtool as install script. Regression introduced in 2.64. + * NEWS, THANKS: Update. + Report by Dmitry Grebeniuk. + This reverts commit 93d9386de9c1320afed43f1337ac5ddb2d2dcbb4. + +2009-12-09 Ralf Wildenhues + + Fix NEWS description for AC_FUNC_MMAP entry. + * NEWS: Update. + + Fix 2.65 AC_TYPE_INT*_T macro body text regression. + * lib/autoconf/types.m4 (_AC_TYPE_INT_BODY): Move helper enum + definition to prologue section, to avoid syntax error. + * NEWS, THANKS: Update. + Report by Pierre Ynard. + +2009-12-09 Paolo Bonzini + + Fix `recursion' test failure. + * tests/m4sugar.at (recursion): Use empty diversion, not 0. + +2009-12-05 Stefano Lattarini + Ralf Wildenhues + + Document Solaris/Heirloom sh set -e issue with command substitutions. + * doc/autoconf.texi (Limitations of Builtins): Fix typos `set -d' + in previous example. Document failure to honor && lists with set -e + and a command substitution in the failing command. + Report and initial patch by Stefano Lattarini against Automake. + +2009-12-04 Eric Blake + + Warn if using unnamed diversion. + * lib/m4sugar/m4sugar.m4 (_m4_divert, m4_divert_push): Add + optional parameter, which controls warning. + (m4_divert_pop, m4_cleardivert, m4_divert_require) + (_m4_require_call): Adjust callers. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Likewise. + * tests/m4sh.at (AT_DATA_LINENO): Avoid triggering the warning. + * tests/m4sugar.at (AT_CHECK_M4SUGAR_TEXT, m4@&t@_append) + (m4@&t@_text_wrap, recursion): Likewise. + (m4@&t@_warn, m4@&t@_divert_stack): Adjust expected output. + * tests/tools.at (autom4te and whitespace in file names) + (autoconf: the empty token): Avoid triggering the warning. + (autoconf: AC_PRESERVE_HELP_ORDER): New test. + * tests/mktests.sh (ac_exclude_list): Retire prior test. + * NEWS: Document the warning. + * doc/autoconf.texi (Redefined M4 Macros) , + : Make even more explicit that using these directly + is discouraged. + (Diversion support): Further warn against improper diversion + changes. + : Give an example of proper use. + Reported by Mike Frysinger. + +2009-11-30 Ralf Wildenhues + + manual: AC_SEARCH_LIBS also prepends to LIBS. + * doc/autoconf.texi (Libraries): Document that AC_SEARCH_LIBS + prepends to LIBS, just like AC_CHECK_LIB. + +2009-11-27 Paolo Bonzini + + Bump m4.m4 serial number. + * m4/m4: Bump serial number to 10. + +2009-11-27 Harald van Dijk + + Fix m4 detection test on dash. + * m4/m4 (AC_PROG_GNU_M4): Use AS_ECHO. + +2009-11-24 Ralf Wildenhues + + Fix AC_FUNC_MMAP regression with C++ compiler in 2.65. + * lib/autoconf/functions.m4 (AC_FUNC_MMAP): Use const char* + for the constant string. Cast void* to char* for assignment. + * NEWS, THANKS: Update. + Report by Michal ÄŒihaÅ™. + + Add pgfortran to list of Fortran 95+ compilers. + * lib/autoconf/fortran.m4 (_AC_F95_FC): Add pgfortran before + pgf95. + Based on report by Jeff Squyres. + +2009-11-22 Bruno Haible + + Fix failure of test 35 when the user has a .autom4te.cfg file. + * tests/tools.at (autom4te cache creation): Skip the test if the + user has a .autom4te.cfg file. + +2009-11-21 Eric Blake + + Release Version 2.65. + * NEWS: Mention the release. + + Prepare for release. + * build-aux/announce-gen: Sync from upstream. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * cfg.mk (gnu_rel_host, url_dir_list): Move... + * maint.mk: ...here, copying ideas from gnulib. + (major): Rename... + (stable): ...to this, copying gnulib. + * HACKING (release): Document changes in process. + + Avoid spurious newline in traced macros. + * bin/autoreconf.in (tracing): Drop newline before parsing traced + arguments; regression from 2009-11-14. + +2009-11-20 Eric Blake + + Allow absolute names in AT_TESTED. + * lib/autotest/general.m4 (AT_INIT) : Check for + absolute names before path walk. + * THANKS: Update. + Suggested by Allan Clark. + +2009-11-14 Ralf Wildenhues + + Fix AC_CONFIG_SUBDIRS tracing in autoreconf. + * bin/autoreconf.in (autoreconf_current_directory): Collapse + newlines in the autoconf trace output, similar to how automake + invokes autoconf, so that newlines do not matter in the argument + to AC_CONFIG_SUBDIRS. + * tests/torture.at (Deep Package): Expose this issue in the + test. + * THANKS: Update. + Report by Nathan Schulte. + +2009-11-09 Eric Blake + + Fix AC_FUNC_MMAP for cygwin. + * lib/autoconf/functions.m4 (AC_FUNC_MMAP): Make the test more + portable: Actually check for , and only use MAP_FIXED + on an address previously returned from mmap. + * THANKS: Update. + Reported by Corinna Vinschen. + +2009-11-04 Eric Blake + + Redocument AS_DIRNAME, even with its flaws. + * doc/autoconf.texi (Common Shell Constructs) : + Restore documentation, since dirname mentions it. + Reported by Peter Johansson. + + Update upstream files. + * build-aux/announce-gen: Synchronize from upstream. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gendocs.sh: Likewise. + * build-aux/git-version-gen: Likewise. + * build-aux/texinfo.tex: Likewise. + * build-aux/update-copyright: Likewise. + * doc/standards.texi: Likewise. + * lib/Autom4te/Channels.pm: Likewise. + * lib/Autom4te/Configure_ac.pm: Likewise. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/Struct.pm: Likewise. + * lib/Autom4te/XFile.pm: Likewise. + +2009-11-04 Ralf Wildenhues + + Coverage for autom4te cache creation issues. + * tests/tools.at (autom4te cache creation): New test. + +2009-11-03 Ralf Wildenhues + + Fix testsuite failures with SHELL=zsh. + * tests/statesave.m4 (AC_STATE_SAVE): Ignore argv and ARGC when + comparing configure variables. + +2009-11-03 Eric Blake + and Ralf Wildenhues + + Update NEWS for recent fixes. + * NEWS: Add some entries. + +2009-10-31 Ralf Wildenhues + + Micro-optimization of config.status substitution. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): No need to + concatenate an empty second string, when we have exactly 148 + characters to substitute. + * tests/torture.at (Substitute a 2000-byte string): Add test + exposure for runs of backslashes near the 148 character limit. + + Fix testsuite failure on AIX 4.3.3. + * lib/autoconf/general.m4 (_AC_RUN_LOG_LIMIT): Remove conftest.err + also if it is empty. + + Fix testsuite failure on IRIX and AIX. + * tests/torture.at (Substitute and define special characters): + Double the backslash before the double-quote in + AC_DEFINE_UNQUOTED, as documented for here-documents. + +2009-10-31 Eric Blake + + Fix cross-manual link to gcc. + * doc/autoconf.texi (Portable C and C++): Provide uref rather than + xref when building for html. + Reported via Karl Berry. + + Update authors. + * AUTHORS: Document recent copyright assignments. + +2009-10-31 Ralf Wildenhues + + Fix AC_OPENMP configure message for non-C compilers. + * lib/autoconf/lang.m4 (AC_LANG_DEFINE): Accept as additional + fourth arg the compiler variable name, defined in _AC_CC($1). + (_AC_CC): New language dispatch macro. + * lib/autoconf/erlang.m4 (AC_LANG(Erlang)): Adjust. + * lib/autoconf/fortran.m4 (AC_LANG(Fortran 77), AC_LANG(Fortran)): + Likewise. + * lib/autoconf/c.m4 (AC_LANG(C), AC_LANG(C++)) + (AC_LANG(Objective C), AC_LANG(Objective C++)): Likewise. + (AC_OPENMP): Use _AC_CC instead of $CC. + + Do not fail OpenMP tests on systems without aclocal. + * tests/c.at (AC_OPENMP and C, AC_OPENMP and C++): Override + `ACLOCAL=true' for autoreconf, the tests don't need aclocal. + * tests/fortran.at (AC_OPENMP and Fortran 77) + (AC_OPENMP and Fortran): Likewise. + +2009-10-31 Bruno Haible + Ralf Wildenhues + + Improve cache variable documentation. + * doc/autoconf.texi (AC_PROG_AWK, AC_PROG_GREP, AC_PROG_EGREP, + AC_PROG_FGREP, AC_PROG_INSTALL, AC_PROG_MKDIR_P, AC_PROG_LEX, + AC_PROG_YACC, AC_CHECK_PROG, AC_CHECK_PROGS, AC_PATH_PROG, + AC_PATH_PROGS): Don't suggest to use the cache variable, only to + override it, or preferably, a non-cache variable associated with + the test. + (AC_PROG_SED): Likewise. Fix name of cache variable. + (AC_FUNC_GETMNTENT): Fix name cache variable. + (AC_FUNC_LSTAT): Fix typo. + +2009-10-31 Ralf Wildenhues + + Fix AC_OPENMP for Fortran (F77 and FC). + * lib/autoconf/fortran.m4 (AC_LANG_FUNC_LINK_TRY(Fortran): New. + * tests/c.at (AC_C_RESTRICT and C++, AC_OPENMP and C) + (AC_OPENMP and C++): New tests. + * tests/fortran.at (AC_OPENMP and Fortran 77) + (AC_OPENMP and Fortran): New tests. + * THANKS: Update. + Report by Bart Oldeman. + + Perl coverage convenience targets. + * Makefile.am (PERL_COVERAGE_DB, PERL_COVERAGE_FLAGS) + (PERL_COVER): New variables. + (check-coverage, check-coverage-run, check-coverage-report) + (clean-coverage): New phony targets. + (clean-local): Depend on clean-coverage. + +2009-10-28 Eric Blake + + Fix corner cases in AS_LITERAL_IF and AS_TR_SH. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Fix bug with unbalanced + parens. Move guts... + (_AS_LITERAL_IF): into new helper. + (AS_TR_SH, AS_TR_CPP): Fix bugs with expansion of wrong macro. + Move guts... + (_AS_TR_SH, _AS_TR_SH_LITERAL, _AS_TR_SH_INDIR, _AS_TR_CPP) + (_AS_TR_CPP_LITERAL, _AS_TR_CPP_INDIR): ...into new helpers. + (AS_VAR_PUSHDEF): Hoist m4_require, by moving guts... + (_AS_VAR_PUSHDEF): ...into new helper. + * tests/m4sh.at (AS@&t@_LITERAL_IF): Enhance test. + + Minor optimizations to m4sh. + * lib/m4sugar/m4sh.m4 (AS_VAR_IF, AS_IDENTIFIER_IF) + (AS_LITERAL_IF): Parse fewer bytes during expansion, by visiting + if-true and if-false arguments only once. + + Optimize m4_escape for common case. + * lib/m4sugar/m4sugar.m4 (m4_escape): Don't use regex if string is + already sane, by copying from AS_LITERAL_IF. Move guts... + (_m4_escape): ...into new helper. + + Fix m4_text_wrap handling of quoted whitespace. + * lib/m4sugar/m4sugar.m4 (m4_escape): New macro. + (m4_text_wrap): Use it to avoid issues with embedded [ and ]. + * tests/m4sugar.at (m4@&t@_text_wrap): Test it. + * NEWS: Document this. + * doc/autoconf.texi (Text processing Macros) : + Likewise. + Reported by Mike Frysinger. + +2009-10-27 Eric Blake + + Mention another feature of AC_RUN_IFELSE. + * doc/autoconf.texi (Runtime) : Mention that + compiled test program still exists during if-true branch. + * THANKS: Update. + Reported by Stefano Lattarini, suggestion by Ralf Wildenhues. + +2009-10-26 Paolo Bonzini + + Pass Autom4te path down to programs that autoreconf invokes. + * bin/autoreconf.in (autom4te): New variable. Export its value + as $ENV{'AUTOM4TE'}. Suggested by Peter Johansson. + * THANKS: Update. + +2009-10-20 Eric Blake + + Fix AC_TYPE_UINT64_T on Tru64 with gcc 3.4.4. + * lib/autoconf/types.m4 (_AC_TYPE_UNSIGNED_INT_BODY) + (_AC_TYPE_INT_BODY): Avoid undefined behavior of attempting shift + wider than type. + * NEWS: Document this. + Reported by Rainer Orth. + +2009-10-17 Ralf Wildenhues + + Fix a couple of index entries in the manual. + * doc/autoconf.texi (Polymorphic Variables): Fix index entries + for AS_VAR_APPEND, AS_VAR_ARITH. + +2009-10-15 Eric Blake + + Fix typos in INSTALL. + * doc/install.texi (Basic Installation, Installation Names): Fix + typos in last patch. + Reported by Ralf Wildenhues. + + Improve INSTALL wording. + * doc/install.texi (Basic Installation): Clarify installcheck + behavior. + (Installation Names): Mention that --prefix only overrides + directory locations not specified on the command line. Prefer + /alternate/directory over /path/to. Remove a sentence targeted to + the developer, not the user. + * THANKS: Update. + Suggested by Alfred M. Szmidt. + +2009-10-15 Peter Breitenlohner + + Fix typos in documentation. + * doc/autoconf.texi (Cache Variable Index): Fix typo. + (Libraries) : Mention 'none required' result. + +2009-10-09 Bruno Haible + Ralf Wildenhues + + Recommend `sh -n' debugging, and public result variables for macros. + * doc/autoconf.texi (Debugging): Recommend to use "bash -n + configure". Recommend the use of result variables as an + alternative to run-if-true/run-if-false parameters. + +2009-10-05 Bruno Haible + + * doc/autoconf.texi (Particular Functions): Swap sections about + AC_FUNC_MBRTOWC and AC_FUNC_MEMCMP. + +2009-10-01 Paolo Bonzini + + Unconditionally check for junk ./--version after mkdir search loop. + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Always check for + presence of ./--version. Reported by Eric Blake. + +2009-09-22 Ralf Wildenhues + + Clarify documentation about Solaris sed quantifier restriction. + * doc/autoconf.texi (Limitations of Usual Tools) : '*' does + not work after subexpressions, \{M,N\} only after one-character + expressions. From GCC PR 38923. + +2009-09-21 Eric Blake + + Fit configure output in 80 columns. + * lib/autoconf/functions.m4 + (AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK): Shorten message. + +2009-09-18 Ralf Wildenhues + + Use consistent notation for cache variables. + * doc/autoconf.texi (Generic Programs): Remove `$' before + variable name. + + Documentation of specific and general cache variables. + * doc/autoconf.texi (Default Includes, Alternative Programs) + (Particular Programs, Generic Programs, Files, Libraries) + (Function Portability, Particular Functions, Generic Functions) + (Particular Headers, Generic Headers, Declarations) + (Generic Declarations, Particular Structures, Particular Types) + (Specific Compiler Characteristics) + (Generic Compiler Characteristics, C Compiler, System Services): + Document lots of cache variables. + * NEWS: Update. + Suggested by Bruno Haible. + + New cache variable index in the manual. + * doc/autoconf.texi: Define new index `CA' for cache variables. + (caindex): New macro. + (Cache Variable Index): New appendix node. + (Top, Indices): Adjust menus. + (Cache Variable Names, Site Defaults): Adjust text. + * doc/Makefile.am (CLEANFILES): Add files generated for CA index. + + New FAQ node: Debugging. + * doc/autoconf.texi (Debugging): New node. + (Top, FAQ): Adjust menus. + Report by Bruno Haible. + + Document AM_MAKEFLAGS workaround to the macro override problem. + * doc/autoconf.texi (Macros and Submakes): Automake makefiles + provide AM_MAKEFLAGS to help with overriding macros in submake + invocations. + Prompted by bug report from Bruno Haible. + +2009-09-15 Peter Breitenlohner + + Implement and document Objective C++ support. + * lib/autoconf/c.m4 (AC_LANG(Objective C++), AC_LANG_OBJCXX) + (AC_LANG_PREPROC(Objective C++), AC_PROG_OBJCXXCPP) + (AC_LANG_COMPILER(Objective C++), AC_PROG_OBJCXX) + (_AC_PROG_OBJCXX_G): New macros. + (_AC_ARG_VAR_CPPFLAGS, _AC_ARG_VAR_LDFLAGS) + (_AC_ARG_VAR_LIBS): Adjusted. + * doc/autoconf.texi (Objective C++ Compiler): New node. + (Preset Output Variables): Document OBJCXXFLAGS. + (Language Choice): Document `Objective C++' language. + * NEWS: Updated. + * tests/local.at (AT_CHECK_ENV): Ignore AC_SUBSTed Objective C++ + related variables. + +2009-09-15 Ralf Wildenhues + + Work around DJGPP shell function return bug with command substitutions. + DJGPP bash 2.04 has a bug in that `return $ac_retval' done in a + shell function which also contains a command substitution causes + the shell to barf. For more details and a fix see: + + Possible workaround include putting the `return' in a subshell + or calling another function to set the status. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE_BODY) + (_AC_COMPILE_IFELSE_BODY, _AC_LINK_IFELSE_BODY) + (_AC_RUN_IFELSE_BODY, _AC_COMPUTE_INT_BODY): Use AS_SET_STATUS + instead of `return'. + * doc/autoconf.texi (Common Shell Constructs, Shell Functions): + Document the issue. + * THANKS: Update. + Report by Rugxulo and Reuben Thomas. + + DJGPP fix: Do not redirect standard input in configure scripts. + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): If $DJGPP is + nonempty, do not dup fd 0 to AS_ORIGINAL_STDIN_FD, do not close + fd 0. + +2009-09-14 Eric Blake + + Quote result of m4_toupper and m4_tolower. + * lib/m4sugar/m4sugar.m4 (m4_tolower, m4_toupper): Quote result. + * lib/autotest/general.m4 (AT_KEYWORDS): Adjust caller. + * tests/m4sugar.at (m4@&t@_toupper and m4@&t@_tolower): New test. + * NEWS: Document this. + * THANKS: Update. + Reported by Sam Steingold. + +2009-09-14 Ralf Wildenhues + + DJGPP fix: remove both conftest and conftest.exe. + The DJGPP compiler may create both `a.out' and `a.exe' without -o, + and both `conftest' and `conftest.exe' with `-o conftest', but not + with `-o conftest.exe'. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_O): Also remove + `conftest' without $ac_exeext suffix. + + DJGPP fix: do not try to source /dev/null as cache or site file. + * lib/autoconf/general.m4 (AC_SITE_LOAD, AC_CACHE_LOAD): Do not + load the cache or site file if it is `/dev/null', as DJGPP treats + it as a regular file, but the shell then warns about it later. + Fixes several test suite failures on DJGPP. + + testsuite: pass $configure_options to configure invocations. + * tests/local.at (AT_CHECK_CONFIGURE): Add $configure_options + to configure command line. + * tests/autotest.at, tests/base.at, tests/c.at, tests/torture.at: + Likewise for each configure invocation. + * README-hacking: Document configure_options. + + testsuite: improve Erlang tests portability, overridability. + * tests/autotest.at (Erlang Eunit unit tests): Use "no" as + value-if-not-found for Erlang tools. + * tests/erlang.at: Likewise. Also, use AS_EXIT instead of plain + exit. + +2009-09-13 Ralf Wildenhues + + * bin/autoupdate.in: Fix typos in comments. + + Improve autotest testsuite summary message. + * lib/autotest/general.m4 (AT_INIT): Hint at the toplevel log + only if not $at_debug_p. Always hint at the per-test output. + + Four new autoupdate tests, expected failures. + * tests/tools.at (autoupdating macros recursively) + (autoupdating with m4@&t@_pushdef, autoupdating with AC_REQUIRE) + (autoupdating with complex quoting): New tests. + + Fix description of AC_CHECK_LIB regarding other deplibs. + * doc/autoconf.texi (Libraries): Library linking may not fail + even without missing additional libs. + +2009-09-12 Eric Blake + + Track recent copyright assignments. + * AUTHORS: Update. + + Improve documentation on quoting. + * doc/autoconf.texi (Autoconf Language): Clarify quoting example. + * THANKS: Update. + Reported by santilín. + +2009-09-11 Ralf Wildenhues + + New config.status option --config. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Implement + --config. + * doc/autoconf.texi (config.status Invocation): Document it. + * NEWS: Update. + * tests/torture.at (configure invocation): Test it. + Suggested several times, by several people, in the past. + +2009-09-10 Eric Blake + + Document that AS_INIT is automatically used. + * doc/autoconf.texi (Initialization Macros) : Add words + to clarify that only bare-bones scripts need a direct AS_INIT. + Suggested by Reuben Thomas. + + Clarify portability pitfall of test. + * doc/autoconf.texi (Limitations of Builtins) : Give more + reasons why -a and -o are not portable. + Reported by Reuben Thomas. + +2009-09-10 Ralf Wildenhues + + Document sed limitation with escaped metacharacters. + * doc/autoconf.texi (Limitations of Usual Tools) : Use `%' + rather than `/' as delimiter in an example `s' command. + Document inconsistent treatment of escaped metacharacters. + * THANKS: Update. + Report by Dave Korn, with additional input from Paolo Bonzini + and Eric Blake. + + Document temporary directory `$tmp' for use in config.status. + * doc/autoconf.texi (Configuration Actions): Document `$tmp'. + * NEWS: Update. + +2009-09-09 Ralf Wildenhues + + Update License to GPLv3+ including new Autoconf Exception. + * NEWS, README: Update licensing information. + * COPYING.EXCEPTION: New file. + * Makefile.am (EXTRA_DIST): Distribute it. + * cfg.mk (autom4te-update): Remove copyright change warning. + * lib/autoconf/autoconf.m4, lib/autoconf/autoheader.m4, + lib/autoconf/autoscan.m4, lib/autoconf/autotest.m4, + lib/autoconf/autoupdate.m4, lib/autoconf/c.m4, + lib/autoconf/erlang.m4, lib/autoconf/fortran.m4, + lib/autoconf/functions.m4, lib/autoconf/general.m4, + lib/autoconf/headers.m4, lib/autoconf/lang.m4, + lib/autoconf/libs.m4, lib/autoconf/oldnames.m4, + lib/autoconf/programs.m4, lib/autoconf/specific.m4, + lib/autoconf/status.m4, lib/autoconf/types.m4, + lib/autotest/autotest.m4, lib/autotest/general.m4, + lib/autotest/specific.m4, lib/m4sugar/foreach.m4, + lib/m4sugar/m4sh.m4, lib/m4sugar/m4sugar.m4: Update exception + statement, bump to GPLv3. + * bin/autoconf.as, bin/autoheader.in, bin/autom4te.in, + bin/autoreconf.in, bin/autoscan.in, bin/autoupdate.in, + bin/ifnames.in: Bump to GPLv3+, adjust --version output + to reflect the GPLv3+ and the Autoconf Exception. + * lib/Autom4te/C4che.pm, lib/Autom4te/ChannelDefs.pm, + lib/Autom4te/General.pm, lib/Autom4te/Request.pm, + lib/autom4te.in, lib/autoscan/autoscan.pre, + lib/emacs/autoconf-mode.el, lib/emacs/autotest-mode.el, + lib/freeze.mk, tests/atlocal.in, tests/autoscan.at, + tests/autotest.at, tests/base.at, tests/c.at, + tests/compile.at, tests/erlang.at, tests/foreign.at, + tests/fortran.at, tests/local.at, tests/m4sh.at, + tests/m4sugar.at, tests/mktests.sh, tests/semantics.at, + tests/statesave.m4, tests/suite.at, tests/tools.at, + tests/torture.at, tests/wrapper.as: Bump to GPLv3+. + + Allow to work on systems without Fcntl::flock implementation. + * configure.ac (PERL_FLOCK): New substitution variable with test + whether Fcntl::flock is implemented by the system. + * bin/Makefile.am (edit): Substitute @PERL_FLOCK@. + * bin/autom4te.in: Call XFile::lock only if flock is + implemented. + +2009-09-04 Reuben Thomas (tiny change) + + Mention the Autoconf archive. + * doc/autoconf.texi (Coding Style): Add a link. + +2009-08-30 Bruno Haible + + Document another Solaris tr pitfall. + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + that Solaris /usr/bin/tr does not only have problems with + replacing NUL bytes but discards all NUL bytes from the input. + +2009-09-04 Eric Blake + + Improve wording about what goes before AC_INIT. + * doc/autoconf.texi (Initializing configure): Update wording. + (Versioning) : Remove misleading text, to match + autoscan's behavior. + * THANKS: Update. + Reported by NightStrike, with input from Ralf Wildenhues. + +2009-09-04 Thomas Jahns (tiny change) + + Fix illegal tab character in Fortran source. + * lib/autoconf/fortran.m4 (AC_FC_SRCEXT): Change TAB back to + multiple spaces; regression introduced 2008-10-23. + * NEWS: Mention this. + * THANKS: Update. + +2009-08-22 Romain Lenglet + + Fix AT_CHECK_EUNIT for versions of Erlang/OTP without init:stop/1. + * lib/autotest/specific.m4 (AT_CHECK_EUNIT): Support older + versions of Erlang/OTP with an erlang:stop() function that doesn't + take arguments. + +2009-08-22 Ralf Wildenhues + + Drop unneeded line in Eunit test. + * tests/autotest.at (Erlang Eunit unit tests): Do not copy + install-sh. + + Fix build dependencies for Erlang macro files. + * lib/freeze.mk (autotest_m4f_dependencies): Add + $(src_libdir)/autotest/specific.m4. + * tests/Makefile.am (AUTOCONF_FILES): Add erlang.m4. + +2009-09-19 Paolo Bonzini + + Use a separate program to test whether the compiler works. + * lib/autoconf/erlang.m4 (_AC_LANG_NULL_PROGRAM(Erlang)): New. + * lib/autoconf/lang.m4 (AC_LANG_DEFINE): Copy _AC_LANG_NULL_PROGRAM. + (_AC_LANG_NULL_PROGRAM(), _AC_LANG_NULL_PROGRAM): New. + (_AC_COMPILER_EXEEXT_DEFAULT): Print here "whether the xyz compiler + works", before exiting. + (_AC_COMPILER_EXEEXT_WORKS): Merge into _AC_COMPILER_EXEEXT_CROSS, + remove the "whether the xyz compiler works" message, use + conftest$ac_cv_exeext instead of $ac_file. + (_AC_COMPILER_EXEEXT): Try _AC_COMPILER_EXEEXT_DEFAULT using + the null program, and clean conftest.out only after + _AC_COMPILER_EXEEXT_CROSS. + (AC_NO_EXECUTABLES): Use _AC_LANG_NULL_PROGRAM. + (_AC_COMPILER_OBJEXT): Use _AC_LANG_NULL_PROGRAM. + +2009-08-18 Bruno Haible + + Document Solaris tr range and NUL limitations. + * doc/autoconf.texi (Limitations of Usual Tools): Mention that + Solaris /usr/bin/tr does not support ranges, nor the '\0' octal + escape. + +2009-08-14 Eric Blake + + Simplify version control metadata. + * .cvsignore: Delete. + * bin/.cvsignore: Likewise. + * config/.cvsignore: Likewise. + * doc/.cvsignore: Likewise. + * lib/.cvsignore: Likewise. + * lib/autoconf/.cvsignore: Likewise. + * lib/Autom4te/.cvsignore: Likewise. + * lib/autoscan/.cvsignore: Likewise. + * lib/autotest/.cvsignore: Likewise. + * lib/emacs/.cvsignore: Likewise. + * lib/m4sugar/.cvsignore: Likewise. + * man/.cvsignore: Likewise. + * tests/.cvsignore: Likewise. + * bin/.gitignore: Likewise. + * build-aux/.gitignore: Likewise. + * config/.gitignore: Likewise. + * doc/.gitignore: Likewise. + * lib/.gitignore: Likewise. + * lib/autoconf/.gitignore: Likewise. + * lib/Autom4te/.gitignore: Likewise. + * lib/autoscan/.gitignore: Likewise. + * lib/autotest/.gitignore: Likewise. + * lib/emacs/.gitignore: Likewise. + * lib/m4sugar/.gitignore: Likewise. + * man/.gitignore: Likewise. + * tests/.gitignore: Likewise. + * .gitignore: Consolidate all rules into one file. + + Normalize remaining copyright lines. + * BUGS: Reformat copyright line, using UPDATE_COPYRIGHT_FORCE. + * NEWS: Likewise. + * README-hacking: Likewise. + * TODO: Likewise. + * lib/Autom4te/ChannelDefs.pm: Likewise. + * lib/autoconf/fortran.m4: Likewise. + * lib/autoconf/general.m4: Likewise. + * lib/autoconf/lang.m4: Likewise. + * lib/autotest/general.m4: Likewise. + * maint.mk: Likewise. + * tests/compile.at: Likewise. + + Improve copyright updating. + * build-aux/update-copyright: Resynchronize from upstream. + * maint.mk (update-copyright): Simplify based on gnulib. + (update-copyright-env): New variable. + * cfg.mk (update-copyright-exclude-regexp): Delete. + (update-copyright-env): New override. + * .x-update-copyright: New file. + * lib/Autom4te/Makefile.am: Add copyright. + * lib/Autom4te/Channels.pm: Revert copyright update to upstream + file. + * lib/Autom4te/Configure_ac.pm: Likewise. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/Struct.pm: Likewise. + * lib/Autom4te/XFile.pm: Likewise. + + Update copyright. + * AUTHORS: Include 2009 in copyright. + * lib/Autom4te/C4che.pm: Likewise. + * lib/Autom4te/Channels.pm: Likewise. + * lib/Autom4te/Configure_ac.pm: Likewise. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/General.pm: Likewise. + * lib/Autom4te/Request.pm: Likewise. + * lib/Autom4te/Struct.pm: Likewise. + * lib/autoconf/Makefile.am: Likewise. + * lib/autoconf/autoconf.m4: Likewise. + * lib/autoconf/autoscan.m4: Likewise. + * lib/autoconf/autoupdate.m4: Likewise. + * lib/autoconf/functions.m4: Likewise. + * lib/autoconf/libs.m4: Likewise. + * lib/autoconf/oldnames.m4: Likewise. + * lib/autoconf/types.m4: Likewise. + * lib/autoscan/Makefile.am: Likewise. + * lib/autoscan/autoscan.pre: Likewise. + * lib/autotest/Makefile.am: Likewise. + * lib/autotest/autotest.m4: Likewise. + * lib/emacs/autoconf-mode.el: Likewise. + * lib/emacs/autotest-mode.el: Likewise. + * lib/freeze.mk: Likewise. + * lib/m4sugar/foreach.m4: Likewise. + * man/Makefile.am: Likewise. + * tests/atlocal.in: Likewise. + * tests/autoscan.at: Likewise. + * tests/foreign.at: Likewise. + * tests/fortran.at: Likewise. + * tests/mktests.sh: Likewise. + * tests/semantics.at: Likewise. + * tests/suite.at: Likewise. + * tests/wrapper.as: Likewise. + + Prepare to bulk update copyright years. + * build-aux/update-copyright: New file. + * cfg.mk (gnulib-update): Sync it from gnulib. + (update-copyright-exclude-regexp): New variable. + (web-manual): Move... + * maint.mk (web-manual): ...here, to match gnulib. + (update-copyright): New target, copied from gnulib's + maint.mk (it would be nice to sync this file...). + (build_aux): New macro. + (VC_LIST, emit_upload_commands): Use it. + * build-aux/texinfo.tex: Resynchronize from upstream. + * lib/autoconf/general.m4 (_AC_COPYRIGHT_YEARS): Reformat to meet + expected pattern. + * lib/autotest/general.m4 (_AT_COPYRIGHT_YEARS): Likewise. + +2009-08-12 Paolo Bonzini + + Fix testsuite log capturing for tests 183 and 186. + * tests/autotest.at (AT_CHECK_AT_PREP): Prepend AT_dir to + testsuite log file for AT_CAPTURE_FILE. + +2009-08-10 Ralf Wildenhues + + Ensure we do not regress with AC_CHECK_MEMBERS. + * tests/semantics.at (AC_CHECK_MEMBERS): Expose the recent + AC_CHECK_MEMBERS fix. + (AC_CHECK_MEMBER): New test group. + +2009-08-10 Jeff Squyres (tiny change) + + Fix typo in AC_REQUIRE description. + * doc/autoconf.texi (Prerequisite macros): Fix typo. + +2009-08-10 Paolo Bonzini + + Fix description of the macro generated by AC_CHECK_MEMBERS. + * lib/autoconf/types.m4 (_AC_CHECK_MEMBERS): Fix regex + replacement. Reported by Bruno Haible. + +2009-08-07 Romain Lenglet + + * lib/autoconf/erlang.m4 (AC_LANG(Erlang)): Make AC_RUN_IFELSE + fail if the test module doesn't compile. + +2009-08-02 Paolo Bonzini + + Use exit code to detect no occurrences with grep. + * tests/autotest.at (Erlang Eunit unit tests): Fix grep invocation. + +2009-08-01 Romain Lenglet + Paolo Bonzini + + * lib/autotest/specific.m4 (AT_CHECK_EUNIT): New file. + * lib/autotest/Makefile.am (dist_autotestlib_DATA): Add specific.m4. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Add definitions of + variables used by AT_CHECK_EUNIT macro: ERL, ERLC, ERLCFLAGS. + * tests/autotest.at (Erlang Eunit unit tests): Add test for macro + AT_CHECK_EUNIT. + * doc/autoconf.texi (Writing Testsuites): Document macro + AT_CHECK_EUNIT. + * NEWS: Mention macro AT_CHECK_EUNIT. + +2009-07-30 Paolo Bonzini + Joel E. Denny + + Clarify comparison of echo, printf, and AS_ECHO*. + * doc/autoconf.texi (Limitations of Builtins): In echo's entry, + give a reason why printf is better than echo. In printf's + entry, cross-reference echo's entry. + +2009-07-30 Paolo Bonzini + + Add back AH_CHECK_HEADERS. + * lib/autoconf/general.m4 (AH_CHECK_HEADERS): New. + * NEWS: Create new section. + +2009-07-29 Ralf Wildenhues + + testsuite: avoid bogus hostname match from inner test logs. + * tests/autotest.at (Hard fail): Check more restrictively for + passed tests, so that hostnames recorded in the log file do not + wrongly match. + Report by Ludovic Courtès. + +2009-07-26 Eric Blake + + Release Version 2.64. + * NEWS: Mention the release. + * README: This release is stable. + * HACKING (release): Use dist-xz, not dist-lzma. + + Document some optional features in INSTALL. + * doc/install.texi (Basic Installation): Mention that INSTALL is + generic, and that not all packages implement all features. + Mention 'make distcheck' for maintainers, and 'make installcheck' + for users. Mention the GNU Coding Standards. + (Installation Names): Mention DESTDIR vs. 'make prefix= install' + as ways to alter the configuration, with caveats of each. Move + --program-prefix discussion... + (Optional Features): ...here. Mention --enable-silent-rules and + use of make V=0. + + Basic improvements to INSTALL. + * doc/install.texi (Basic Installation): Use better markup. + (Multiple Architectures): Introduce the term VPATH. + (Installation Names): Mention that --prefix must be absolute. + * doc/autoconf.texi (Preset Output Variables) + (Installation Directory Variables): Consistently refer to GNU + Coding Standards. + + Update some upstream files. + * build-aux/config.guess: Resynchronize from upstream. + * build-aux/config.sub: Likewise. + * build-aux/texinfo.tex: Likewise. + * build-aux/vc-list-files: Likewise. + * doc/standards.texi: Likewise. + +2009-07-25 Eric Blake + + Recognize new m4sugar keywords. + * lib/emacs/autoconf-mode.el (autoconf-current-defun): Recognize + m4_define_default, m4_defun_init, m4_defun_once. + (autoconf-font-lock-keywords): Likewise. + + Require m4 1.4.6, and fix testsuite to support this version. + * m4/m4.m4 (AC_PROG_GNU_M4): Reject m4 1.4.5, now that we use + regexp it can't handle. + * NEWS: Mention minimum version bump. + * README: Likewise. + * README-hacking: Likewise. + * doc/autoconf.texi (Introduction, Why GNU M4): Likewise. + * tests/tools.at (autom4te --trace and whitespace): Update test so + still work with older m4 line numbers. + * tests/m4sugar.at (m4@&t@_require: nested): Likewise. + Reported by Ralf Wildenhues. + +2009-07-25 Bruno Haible + + Clarify autom4te debugging tips. + * doc/autoconf.texi (Debugging via autom4te): Fix example from + previous commit, and add clarification. + +2009-07-25 Eric Blake + + Document some autom4te debugging tips. + * doc/autoconf.texi (Debugging via autom4te): New node. + Suggested by Bruno Haible. + + Fix font-lock. + * configure.ac (ac_cv_unsupported_fs_chars): Make editing easier. + + Let autoheader see through m4 macros in AC_DEFINE. + * lib/autoconf/general.m4 (AC_DEFINE_TRACE): Expand macro before + tracing its name. + * lib/autoconf/autoheader.m4 (AH_VERBATIM, AH_TEMPLATE): Likewise, + for using the macro in a template file. + * tests/tools.at (autoheader and macros): New test. + * NEWS: Mention this. + Reported by Bruno Haible. + + Improve NEWS wording. + * NEWS: Use more accurate statement. + Suggestedy by Ralf Wildenhues. + +2009-07-24 Eric Blake + + Fix AS_EXIT for FreeBSD sh. + * lib/m4sugar/m4sh.m4 (AS_EXIT): Always supply an argument to the + shell function, since $? is not reliable on function entry. + (_AS_EXIT_PREPARE): Simplify to assume argument. + Reported by Ralf Wildenhues. + +2009-07-23 Eric Blake + + Run more tests under Solaris. + * tests/local.at (AT_CHECK_AUTOCONF): Don't skip entire test + group when passing over syntax checks. + +2009-07-23 Romain Lenglet + + Clean up temporary files generated by Erlang macros. + * lib/autoconf/erlang.m4 (AC_ERLANG_CHECK_LIB) + (AC_ERLANG_SUBST_ROOT_DIR, AC_ERLANG_SUBST_LIB_DIR) + (AC_ERLANG_SUBST_ERTS_VER): Delete conftest.out; renamed + erlang_cv_* cache variables into ac_cv_erlang_*. + * lib/autoconf/general.m4 (AC_RUN_IFELSE): Delete conftest.beam + files generated by Erlang compiler. + * tests/local.at (AT_CHECK_ENV): Ignore variables defined by + Erlang macros. + * tests/erlang.at (AT_SETUP_ERLANG): Delete; replace all uses by + AT_CHECK_MACRO. + * tests/Makefile.am (AUTOCONF_FILES): Revert previous addition of + generated Erlang tests; they are all hand-tested. + + Add autotests for Erlang macros. + * tests/erlang.at: Added tests for all macros in erlang.m4. + * tests/Makefile.am (TESTSUITE_HAND_AT, AUTOCONF_FILES): Added + erlang.at. + * tests/suite.at: Likewise. + * tests/compile.at (AC_LANG, AC_LANG_PUSH & AC_LANG_POP): Added + test for extension of Erlang files. + (Multiple languages): Use correct m4 quoting. + * NEWS: Mention this. + +2009-07-22 Eric Blake + + Fix test of autom4te from stdin. + * tests/tools.at (autom4te cache locking): Make stdin request + explicit, so that --force is properly used. + +2009-07-16 Eric Blake + + Don't hide leading space in autom4te --trace output. + * bin/autom4te.in (handle_traces): Don't flatten leading and + trailing space, since tracing spacing bugs can be useful. + * tests/tools.at (autom4te --trace and whitespace): New test. + +2009-07-13 Eric Blake + + Document that $srcdir can be used during configure. + * doc/autoconf.texi (Preset Output Variables): Add a paragraph. + * THANKS: Update. + Reported by Monty Taylor. + +2009-07-13 Eric Blake + + Disable asynchronous job notification for parallel tests. + * lib/autotest/general.m4 (AT_INIT) : Turn off notify + mode, since zsh leaves it on after 'emulate sh'. + * doc/autoconf.texi (Limitations of Builtins) : Document that + job control options are not portable. + + Guarantee that exit status trumps output matching. + * doc/autoconf.texi (Writing Testsuites) : Document this + better. + * tests/autotest.at (Skip, parallel skip): Enhance tests. + + Fix nits in recent patches. + * configure.ac (ac_cv_dir_trailing_space): Avoid $status, for + zsh. + * doc/autoconf.texi (Writing Testsuites) : + Tweak wording. + (Introduction): Recommend m4 1.4.13. + * README: Likewise. + * m4/m4.m4 (AC_PROG_GNU_M4): Likewise. Use long option --gnu + rather than -g. + +2009-07-13 Paolo Bonzini + + Introduce AT_SKIP_IF and AT_FAIL_IF + * NEWS: Mention AT_SKIP_IF and AT_FAIL_IF. + * doc/autoconf.texi (Autotest): Document them. + * lib/autotest/general.m4 (_AT_LINE_ESCAPED, AT_SKIP_IF, + AT_FAIL_IF, _AT_CHECK_EXIT): New. + (AT_CHECK): Use _AT_LINE_ESCAPED. + * tests/autotest.at: Add tests for AT_SKIP_IF and AT_FAIL_IF. + Use AT_SKIP_IF. + * tests/local.at: Use AT_SKIP_IF. + +2009-07-13 Paolo Bonzini + + Use m4 -g when available. + * m4/m4.m4: Unset POSIXLY_CORRECT during first test. Test for -g. + Warn user if he has POSIXLY_CORRECT set but -g is not supported. + * bin/Makefile.am: Substitute @M4_GNU@ into generated files. + * bin/autom4te.in: Pass @M4_GNU@ to m4. + +2009-07-13 Eric Blake + + Fix previous patch. + * lib/autotest/general.m4 (at_fn_check_prepare_notrace): Use + proper m4 quoting. + (_AT_DECIDE_TRACEABLE): Likewise. + +2009-07-13 Paolo Bonzini + + * lib/autotest/general.m4 (at_fn_check_prepare_notrace): Use + $at_trace_echo. Add new REASON argument. + (at_fn_check_prepare_trace): Do not call at_fn_check_prepare_notrace. + Use $at_check_filter_trace. + (at_fn_check_prepare_dynamic): Use at_fn_check_prepare_notrace. + (at_traceon): Initialize to ':'. + (at_traceoff): Remove, use 'set +x' instead throughout. + (at_check_filter_trace, at_trace_echo): New shell variables. + Initialize them if tracing is requested. + (_AT_DECIDE_TRACEABLE): Adjust call to at_fn_check_prepare_notrace. + +2009-07-12 Paolo Bonzini + + Move atlocal feature tests to configure + * configure.ac: Test for unsupported characters in files and + directories here... + * tests/atlocal.in: ... and not here. + +2009-07-09 Eric Blake + + Fix test typo. + * tests/m4sh.at (AS@&t@_INIT_GENERATED): Close fd, rather than + creating file named -. + + Fix testsuite under dash. + * tests/m4sh.at (LINENO stack, AS@&t@_BASENAME, AS@&t@_DIRNAME) + (AS@&t@_ECHO and AS@&t@_ECHO_N, AS@&t@_EXIT, AS@&t@_MKDIR_P) + (AS@&t@_VERSION_COMPARE, as_me, Negated classes in globbing) + (Functions Support, Functions and return Support) + (Nested AS@&t@_REQUIRE_SHELL_FN, Nested AS@&t@_REQUIRE) + (AS@&t@_REQUIRE_SHELL_FN and m4@&t@_require, AS@&t@_HELP_STRING) + (AS@&t@_IF and AS@&t@_CASE, AS@&t@_FOR, AS@&t@_LITERAL_IF) + (AS@&t@_VAR basics, AS@&t@_VAR_APPEND, AS@&t@_VAR_ARITH) + (AS@&t@_INIT cleanup, AS@&t@_INIT_GENERATED, AS@&t@_MESSAGE_FD) + (_AS@&t@_CLEAN_DIR, ECHO_C): Allow testing different CONFIG_SHELL + options during the testsuite run. + Reported by Ralf Wildenhues. + +2009-07-09 Ralf Wildenhues + + Ignore messages on stderr when testing for the zsh issue. + * tests/autotest.at (AT_SKIP_PARALLEL_TESTS): Ignore stderr. + +2009-07-07 Eric Blake + + Skip parallel tests when zsh 'set -m' fails. + * tests/autotest.at (AT_SKIP_PARALLEL_TESTS): Skip test if set -m + is not supported. + Reported by Ralf Wildenhues. + + Make parallel testsuite more portable. + * lib/autotest/general.m4 (AT_INIT) : Avoid <>; + instead open write descriptor in each group and read descriptor in + main driver. + * tests/autotest.at (AT_SKIP_PARALLEL_TESTS): Relax condition. + +2009-07-03 Eric Blake + + Avoid syntax error in ash. + * lib/autotest/general.m4 (AT_INIT) : Avoid syntax + errors on shells that don't recognize <>. + * tests/autotest.at (AT_SKIP_PARALLEL_TESTS): Also skip parallel + tests for this reason. Skip based on the shell to be tested, + not the shell driving the testsuite. + (parallel syntax error): Rearrange similar to previous patch. + (parallel test execution): Defer skip until after serial tests. + +2009-07-02 Eric Blake + + Skip test on shells that can't catch syntax failure. + * tests/autotest.at (Syntax error): Skip test if shell aborts on + syntax error (AIX ksh88) or doesn't detect it (zsh). + * doc/autoconf.texi (Limitations of Builtins) <.>: Mention these + limitations. + Reported by Ralf Wildenhues. + +2009-06-30 Jan Madzik (tiny change) + Ralf Wildenhues + + Avoid AIX 6.1 ksh88 ECHO_C command substitution bug. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_N_PREPARE): Ensure more than + one character is output with `\c'; reset echo output state + if buggy ksh was detected, and set ECHO_T instead of ECHO_C. + * doc/autoconf.texi (Limitations of Builtins): Document it. + * tests/m4sh.at (ECHO_C): New test. + * THANKS: Update. + +2009-06-27 William Pursell (tiny change) + + Fix grammaro in documenation. + * doc/autoconf.texi (Guidelines): Fix grammaro. + +2009-06-17 Eric Blake + + Fix AC_CHECK_HEADER infloop for gcc. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_NEW) + (_AC_CHECK_HEADER_OLD): Give up on AU_DEFUN, and manually warn + about obsoletion, to avoid infinite loop in gcc. + Reported by Ralf Wildenhues. + +2009-06-15 Eric Blake + + Add m4_copy_force, m4_rename_force. + * lib/m4sugar/m4sugar.m4 (m4_copy_force, m4_rename_force): New + macros. + * tests/m4sugar.at (m4@&t@_defn): Test them. + * doc/autoconf.texi (Redefined M4 Macros) : Document + them. + * NEWS: Likewise. + Suggested by Ralf Wildenhues. + + Reinstate _AC_CHECK_HEADER_OLD for gcc. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_NEW) + (_AC_CHECK_HEADER_OLD): Provide autoupdate versions, since gcc and + others used these undocumented macros. + Reported by Ralf Wildenhues. + +2009-06-12 Ralf Wildenhues + + Fix concurrent autom4te.cache directory creation race. + * bin/autom4te.in: Do not error out if another `autom4te' + instance created the cache directory before we could. + +2009-06-11 Steven G. Johnson + and Eric Blake + + Create a file in test program when detecting cross-compilation. + * lib/autoconf/lang.m4 (_AC_LANG_IO_PROGRAM): New macro, returns + program that creates a file. + (_AC_COMPILER_EXEEXT,_AC_COMPILER_EXEEXT_WORKS): Call new macro + and document why it's needed to robustly detect cross-compiling. + (AC_LANG_DEFINE): Copy implementation across similar languages. + * lib/autoconf/c.m4 (_AC_LANG_IO_PROGRAM(C)): Implement new macro. + * lib/autoconf/fortran.m4 (_AC_LANG_IO_PROGRAM(Fortran 77)): + Likewise. + * lib/autoconf/erlang.m4 (_AC_LANG_IO_PROGRAM(Erlang)): Likewise. + +2009-06-11 Eric Blake + + Simplify AC_LANG(Fortran). + * lib/autoconf/fortran.m4 (AC_LANG(Fortran)): Borrow from Fortran + 77, which requires reordering portions of the file. + (AC_LANG_PROGRAM(Fortran), AC_LANG_CALL(Fortran)): Now defined + automatically. + + Clarify m4_copy semantics. + * doc/autoconf.texi (Redefined M4 Macros) : Update + documentation. + * tests/m4sugar.at (m4@&t@_defn): Enhance test. + +2009-06-06 Eric Blake + + Improve documentation on trap pitfalls. + * doc/autoconf.texi (Limitations of Builtins) : Mention new + Posix 2008 requirement on trap, and dash bug in implementing it. + Mention various shell bugs with traps defined inside subshells. + Mention older bash limitation with single-command exit trap. + : Mention another 'set -e' limitation. + Reported by Jens Schmidt. + +2009-06-06 Jim Meyering + + Improve testsuite --help + * lib/autotest/general.m4: Correct the example in ./testsuite --help. + Improve wording. + +2009-06-06 Eric Blake + + Document fallback behavior of AC_PROG_LEX. + * doc/autoconf.texi (Particular Programs) : Mention + why fallback is :, and that a --version check must be used to + determine whether flex was found. + Reported by Patrick Welche. + +2009-05-28 Jim Meyering + + Fix syntax errors in autoconf.texi. + * doc/autoconf.texi (Erlang Libraries): @-escape curly braces + in example code. + +2009-05-28 Romain Lenglet + + New AC_ERLANG_SUBST_ERTS_VER macro. + * lib/autoconf/erlang.m4: Add macro AC_ERLANG_SUBST_ERTS_VER. + * doc/autoconf.texi (Erlang Libraries): Document + AC_ERLANG_SUBST_ERTS_VER. + * NEWS: Likewise. + * AUTHORS: Update Romain Lenglet's email address. + * THANKS: Update. + Suggested by Ruslan Babayev. + +2009-05-26 Eric Blake + + Sanitize more problematic environment variables. + * doc/autoconf.texi (Environment Variable Index): Add more + entries, particularly for precious variables and known culprit + variables. Needed to avoid overfull vbox. + (Special Shell Variables) : Add + variables known to cause misbehavior. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Unset variables + known to cause problems. + * THANKS: Update. + Based on reports from Ilya Bobir and Joey Mingrone. + +2009-05-21 Ralf Wildenhues + + Document VPATH = $(variable) issue in VPATH chapter. + * doc/autoconf.texi (Variables listed in VPATH): New node. + (Top, VPATH and Make): Adjust menus. + (Build Directories): Refer to it. + Prompted by report from Bruno Haible. + +2009-05-19 Eric Blake + + Update uses of all-permissive license. + * ChangeLog: Relicense under GPL. + * ChangeLog.0: Likewise. + * ChangeLog.1: Likewise. + * ChangeLog.2: Likewise. + * THANKS: Likewise. + * m4/m4.m4: Use latest wording of FSF all-permissive license. + * m4/make-case.m4: Likewise. + * doc/install.texi: Likewise. + * tests/statesave.m4: Relicense to match rest of testsuite; this + file does not need all-permissive license since it is not designed + for reuse by other packages. + * BUGS: Relicense under all-permissive license. + * HACKING: Likewise. + * NEWS: Likewise. + * README: Likewise. + * README-alpha: Likewise. + * README-hacking: Likewise. + * TODO: Likewise. + + Update some upstream files. + * build-aux/config.guess: Resynchronize from upstream. + * build-aux/gnupload: Likewise. + * build-aux/vc-list-files: Likewise. + * build-aux/texinfo.tex: Likewise. + * doc/gendocs_template: Likewise. + + Don't mention undocumented interface in NEWS. + * NEWS: Correct earlier entry about AS_FOR. + +2009-05-17 Ralf Wildenhues + + New manual section `Parallel Make'. + * doc/autoconf.texi (Parallel Make): New node, document NetBSD + `make -jN' quirks. + (Top, Portable Make): Adjust menus. + +2009-05-14 Ralf Wildenhues + + testsuite: skip `Multiple languages' test without C++ compiler. + * tests/compile.at (Multiple languages): Skip test on systems + without a C++ compiler. + Report by Jim Meyering. + +2009-05-13 Eric Blake + + Document zsh bug with empty commands. + * doc/autoconf.texi (Special Shell Variables) : Add mention of + more problems with $?. + +2009-05-11 Patrick Welche (tiny change) + + Also try X11R7 when looking for X11 files, for NetBSD. + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Also try directories + with X11R7 in the name. + +2009-05-01 Ralf Wildenhues + + Limit stderr logging for C compiler version. + * lib/autoconf/general.m4 (_AC_RUN_LOG_LIMIT, _AC_DO_LIMIT): New + internal macros, equivalent to _AC_RUN_LOG and _AC_DO, but with + an optional additional argument to limit the number of lines of + stderr output logged, defaulting to 10. + * lib/autoconf/c.m4 (AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC): Use + _AC_DO_LIMIT for capturing compiler version output. Also test + -qversion, for the IBM xlc compiler. + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Likewise. + * THANKS: Update. + Report by Christian Rössel and John R. Cary against Libtool. + +2009-04-24 Eric Blake + + Fix quoting of m4 macros in AT_CHECK. + * lib/autotest/general.m4 (AT_CHECK): Expand prior to adding + escapes, to avoid shell syntax errors caused by late macro + expansion. + * NEWS: Document this change. + * tests/autotest.at (Metacharacters in command from M4 expansion): + New test. + + manual: Use consistent spelling of here-document. + * doc/autoconf.texi (Defining Symbols, Programming in M4sh) + (Common Shell Constructs, Macro Names, Writing Testsuites): Fix + spelling. + Reported by Ralf Wildenhues. + + Make AT_CHECK_UNQUOTED more like AC_DEFINE_UNQUOTED. + * lib/autotest/general.m4 (AT_CHECK_NOESCAPE): Keep older, + undocumented semantics, where unbalanced " cannot be used in the + stdout/stderr argument. + (AT_CHECK_UNQUOTED): Treat " in stdout/stderr as a literal, since + the text is used in double-quoted context. + * tests/autotest.at (unquoted output): New test. + * doc/autoconf.texi (Writing Testsuites) : Mention which + shell expansions are handled. + + Rename AT_CHECK_NOESCAPE to AT_CHECK_UNQUOTED. + * lib/autotest/general.m4 (AT_CHECK_NOESCAPE): Deprecate, in favor + of new spelling... + (AT_CHECK_UNQUOTED): ...for consistency with AC_DEFINE_UNQUOTED. + * doc/autoconf.texi (Writing Testsuites) : Document the + rename. + * NEWS: Likewise. + * tests/autotest.at (Binary output, Cleanup): Adjust tests. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Likewise. + Reported by Ralf Wildenhues. + +2009-04-22 Ralf Wildenhues + + New test to ensure autom4te cache file locking works. + * tests/tools.at (autom4te cache locking): New test. + Report by Eric Blake. + +2009-04-22 Paolo Bonzini + + manual: another grammar improvement. + * doc/autoconf.texi (Fortran Compiler): Avoid dependency on + pronunciation of `FCFLAGS_f90'. + +2009-04-23 Eric Blake + + Change FOO placeholder to use @var{text} instead. + * doc/autoconf.texi (Configuration Actions): Rename AC_CONFIG_FOOS + to AC_CONFIG_@var{ITEMS}. + * doc/autoconf.texi (config.status Invocation): Likewise. + (AC_FOO_IFELSE vs AC_TRY_FOO): Rename node... + (AC_ACT_IFELSE vs AC_TRY_ACT): ...to this. + +2009-04-22 Eric Blake + + Add m4_argn. + * lib/m4sugar/m4sugar.m4 (m4_argn): New macro. + * NEWS: Document it. + * doc/autoconf.texi (Looping constructs) : Likewise. + : Improve documentation. + * tests/m4sugar.at (m4 lists): New test. + +2009-04-22 Ralf Wildenhues + + Improve description of AC_PROG_CC_C89 and AC_PROG_CC_C99. + * doc/autoconf.texi (C Compiler): Document that AC_PROG_CC_C89 + and AC_PROG_CC_C99 prefer extended over strict conformance modes. + Report by Vincent Lefèvre. + +2009-04-21 Ralf Wildenhues + + Revert bogus change in last commit. + * doc/autoconf.texi (Initialization Macros): Revert change. + Spotted by Eric Blake. + + manual: fix trivial grammar errors. + * doc/autoconf.texi (Fortran Compiler, Initialization Macros) + (Limitations of Usual Tools, Pretty Help Strings) + (config.status Invocation): Fix `a' vs. `an' errors. + Report by Eric Blake. + +2009-04-21 Eric Blake + + Shuffle maintainer-specific rules. + * Makefile.am (maintainer-check-tests): Delete. + (autom4te-update): Move... + * cfg.mk (autom4te-update): ...here. + (fetch): Depend on autom4te-update. Split... + (gnulib-update): ...into new rule. Import move-if-change from + gnulib. + * maint.mk (maintainer-distcheck): Absorb former maintainer-check + rule. + * build-aux/move-if-change: New file, undistributed. + * .gitattributes: Handle new upstream file. + * .gitignore: Ignore maintainer cruft. + * HACKING: Update maintainer instructions. + * build-aux/config.guess: Update from upstream. + * build-aux/config.sub: Likewise. + * build-aux/gendocs.sh: Likewise. + * build-aux/texinfo.tex: Likewise. + * doc/gendocs_template: Likewise. + * doc/standards.texi: Likewise. + +2009-04-19 Ralf Wildenhues + + Sync autom4te perl modules from Automake. + * lib/Autom4te/Channels.pm: Sync from Automake. + * lib/Autom4te/FileUtils.pm: Likewise. + * lib/Autom4te/XFile.pm: Likewise. + + Adjust channel definitions for new Automake `ordered' flag. + * lib/Autom4te/ChannelDefs.pm (Autom4te::ChannelDefs): Set + `ordered' flag to zero for channels `fatal', `automake', and + `verb'. This has currently no effect on actual semantics but + avoids a consistency check needed for Automake's usage of the + Channels.pm code. + + manual: clarify m4_if synopsis. + * doc/autoconf.texi (Redefined M4 Macros): Rewrite synopsis of + m4_if in the presence of more than three arguments. + + Improve and clarify `config.status' usage documentation. + * doc/autoconf.texi (config.status Invocation): Fix markup in + synopsis. Use `tag' instead of `file' notation for the + non-option arguments, to be consistent with the documentation + of the AC_CONFIG_* macros. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Likewise, + use `tag' notation for non-option arguments. + Report by John Calcote. + +2009-04-15 Eric Blake + + Test that autotest handles binary output. + * tests/autotest.at (Binary output): New test. + Suggested by Ralf Wildenhues. + + Add stdout-nolog and ignore-nolog to AT_CHECK. + * lib/autotest/general.m4 (AT_DIFF_STDERR(stderr-nolog)) + (AT_DIFF_STDERR(ignore-nolog), AT_DIFF_STDOUT(stdout-nolog)) + (AT_DIFF_STDOUT(ignore-nolog)): New macros. + * tests/autotest.at (Logging): New test. + * doc/autoconf.texi (Writing Testsuites) : Document the + new logging actions. + * NEWS: Likewise. + Reported by Ralf Wildenhues. + + Teach AT_CHECK about hard failures. + * lib/autotest/general.m4 (AT_INIT) + : Handle hard + failures. + * doc/autoconf.texi (Writing Testsuites) : Document + AT_CHECK_NOESCAPE and exit status 99. + * NEWS: Likewise. + * tests/autotest.at (Hard fail, Cleanup): New tests. + +2009-04-14 Eric Blake + + Fix yesterday's regression in AS_IF. + * lib/m4sugar/m4sh.m4 (_AS_IF_ELSE): Don't corrupt $? in else + branch; it is up to the user to avoid syntax errors. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Adjust test. + +2009-04-14 Ralf Wildenhues + + Add traces for AM_SILENT_RULES. + * lib/autom4te.in (Automake-preselections): Trace + AM_SILENT_RULES. + +2009-04-13 Eric Blake + + Improve documentation related to expanded-before-required. + * doc/autoconf.texi (Expanded Before Required): Add a case study. + (Running the Compiler) : Remind users that + running a compile test will AC_REQUIRE the compiler check. + (Macro Definitions) : Contrast AC_DEFUN and m4_define. + (C Compiler) : Mention the fact that only first + invocation of this macro checks for $EXEEXT, and that many other + macros use it via AC_REQUIRE. + Reported by Andreas Schwab. + + Mention latest rules about make and set -e. + * doc/autoconf.texi (Failure in Make Rules): Posix is now clear + that make must use set -e. + (Limitations of Builtins) : Clarify more about set -e + behavior. + + Improve documentation about if exit status. + * doc/autoconf.texi (Limitations of Builtins) : Mention that + exit status bugs don't affect modern targets. + Reported by Andreas Schwab. + + Add cross-reference to new macros. + * doc/autoconf.texi (Text processing Macros) + : Reference the new m4_ifblank. + Suggested by Mike Frysinger. + + Make AS_IF, AS_CASE, and AS_FOR more robust to blank arguments. + * lib/m4sugar/m4sh.m4 (_AS_CASE, _AS_CASE_DEFAULT, AS_FOR, _AS_IF) + (_AS_IF_ELSE, AS_IF): Avoid syntax error on blank argument, + including a macro with an empty expansion. + * NEWS: Mention this. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE, AS@&t@_FOR): Update + tests. + Reported by Mike Frysinger. + + Add m4_blank and friends. + * lib/m4sugar/m4sugar.m4 (m4_blank, m4_nblank, m4_default_nblank) + (m4_default_nblank_quoted): New macros. + * NEWS: Document them. + * doc/autoconf.texi (Conditional constructs): Likewise. + * tests/m4sugar.at (m4sugar shorthand conditionals): New test. + Suggested by Mike Frysinger. + +2009-04-13 Eric Blake + + Finish upgrade to GFDL 1.3. + * doc/autoconf.texi (copying): Use correct license; comment change + was missed on 2008-11-04. + +2009-04-10 Eric Blake + + Test parallel handling of syntax error. + * tests/autotest.at (parallel syntax error): New test. + Suggested by Ralf Wildenhues. + +2009-04-10 Ralf Wildenhues + + Document awk and config.status line length limitations. + * doc/autoconf.texi (Configuration Actions): The input to + config.status should have reasonable line length. + (Limitations of Usual Tools): Document IRIX, HP-UX awk input + line length limit. + Report by Bruno Haible. + + Skip `Multiple languages' test if CC is a C++ compiler. + * tests/compile.at (Multiple languages): Before starting the + test proper, build and run a configure script that tests the + C compiler only, and skips the test if this is found to be a + C++ compiler. + Report by Eric Blake. + + Note that AC_DEFUN is needed for aclocal. + * doc/autoconf.texi (Coding Style): Public third-party macros + should be AC_DEFUN'ed. + Report by John Calcote. + +2009-04-10 Eric Blake + + Add undocumented _AS_CLEAN_DIR. + * lib/m4sugar/m4sh.m4 (_AS_CLEAN_DIR): New macro; fixes m4 quoting + in previous patch. + * lib/autotest/general.m4 (AT_INIT) : Use new + macro. + * tests/m4sh.at (_AS@&t@_CLEAN_DIR): New test. + Reported by Ralf Wildenhues. + +2009-04-09 Eric Blake + + Avoid problems caused by deleting in-use directory. + * lib/autotest/general.m4 (AT_INIT) : Only + remove the contents of $at_group_dir, not the directory itself. + + Fix regression in empty test. + * lib/autotest/general.m4 (AT_SETUP): Prep AT_ingroup for fallback + use in empty test. Fixes regression introduced 2009-04-06. + (_AT_CHECK): Undo fallback when a test is not empty. + (AT_CLEANUP): Expand AT_ingroup before deleting. + +2009-04-09 Paolo Bonzini + + Make a less conservative cross-compilation guess for AC_FUNC_UTIME_NULL. + * lib/autoconf/functions.m4 (AC_FUNC_UTIME_NULL): Assume + not crosscompiling to an obsolete system. + +2009-04-08 Ralf Wildenhues + + Automake relies on the undocumented `_AC_COMPILER_EXEEXT' macro. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT): Document that + Automake relies on this macro. + +2009-04-06 Eric Blake + + Reduce testsuite size. + * tests/statesave.m4: New file. + * tests/Makefile.am (EXTRA_DIST): Distribute it. + * tests/local.at (AT_CONFIGURE_AC): Reuse file, rather than + repeating inline definition of AC_STATE_SAVE. + (AT_CHECK_ENV): Factor code... + (_AT_CHECK_ENV): ...into shell function. + * tests/m4sh.at (AT_DATA_LINENO): Avoid churn in testsuite. + + Handle shell comments in AT_CHECK. + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): Handle # in + test correctly. Latent bug in handling shell comment was first + fixed 2008-11-20, but regressed two patches later. + * tests/autotest.at (Shell comment in command): New test. + * NEWS: Document the fix. + + Hard fail any test with syntax errors. + * lib/autotest/general.m4 (AT_INIT) : + Guarantee test failure on syntax error, rather than inheriting + status from previous test. + * tests/autotest.at (Syntax error): New test. + +2009-03-31 Eric Blake + + Beta Release Version 2.63b. + * NEWS: Mention the release. + * README: Clarify that this is a beta release. + * build-aux/texinfo.tex: Synchronize from upstream. + * .x-sc_trailing_blank: Exempt more upstream files. + +2009-03-30 Eric Blake + + Fix testsuite failures under zsh. + * tests/local.at (AT_CHECK_ENV): Exempt $argv and $ARGC, which are + set by zsh -c 'emulate sh'. + Reported by Ralf Wildenhues. + + For now, skip parallel tests under less-tested shells. + * tests/autotest.at (AT_CHECK_AT): Add pre-test argument. + (Tested programs, Startup error messages, AT_CHECK_AT_TITLE) + (Fallacy, Skip, errexit, Long test source lines) + (Debugging a successful test, Debugging script and environment) + (Debugging a failed test, Using atlocal) + (Choosing where testsuite is run): Adjust callers. + (AT_SKIP_PARALLEL_TESTS): New macro, to skip parallel tests except + under zsh, bash, or when TEST_PARALLEL_AUTOTEST is defined. Makes + it easier to avoid testsuite hangs for users with dash or other + less-tested shell. + (parallel test execution, parallel truth, parallel fallacy) + (parallel skip, parallel errexit) + (parallel autotest and signal handling): Use it. + * BUGS: Mention this. + +2009-03-24 Andris Pavenis (tiny change) + + Fix awk substitution of carriage returns on DJGPP. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fix typo in + generation of ac_cs_awk_cr. + * THANKS: Update. + +2009-03-24 Aaron W. LaFramboise (tiny change) + + Work around cygwin bash igncr mode. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fall back to + bash carriage returns if ac_cr lost \r from ``. + * THANKS: Update. + Suggested by Eric Blake. + +2009-03-24 Eric Blake + + Fix underquoted example in manual. + * doc/autoconf.texi (Common Shell Constructs) : + Properly m4-quote #. + * THANKS: Update spelling. + Reported by MatÄ›j TýÄ. + +2009-03-18 Eric Blake + + Manual: mention more expr pitfalls. + * doc/autoconf.texi (Limitations of Usual Tools) : + Mention HP-UX limitation, and $ ambiguity. + * THANKS: Update. + Reported by Jens Schmidt, in http://bugs.debian.org/466990. + +2009-03-17 Jim Meyering + + Manual: fix a typo. + * lib/m4sugar/m4sh.m4: s/are/is/ => "there is no indirection" + +2009-03-17 Eric Blake + + Use test consistently in examples. + * doc/autoconf.texi (Subdirectories, Caching Results) + (Common Shell Constructs, Prerequisite Macros, Coding Style) + (Changed Results, Particular Programs, Defining Symbols): + Protect against arbitrary user strings. + (Multiple Cases): Mention why $fstype does not need protection. + Reported by Reuben Thomas. + + Improve confusing section names. + * doc/autoconf.texi (Specifying Names): Rename node... + (Specifying Target Triplets): ...to this. + (Generic Programs): Adjust references. + * doc/install.texi (System Type): Touch up formatting. + * THANKS: Update. + Reported by Tim Freeman, in http://bugs.debian.org/312873. + + Remove historical inaccuracy. + * doc/autoconf.texi (Portable Shell): Don't perpetuate myth about + #!/bin/sh needing a space. + Reported by Reuben Thomas. + + Recommend AS_HELP_STRING more prominently. + * doc/autoconf.texi (External Software): Reduce mention of + hand-written help strings. + Reported by Reuben Thomas. + +2009-03-16 Eric Blake + + Fix 'make pdf'. + * doc/autoconf.texi (Balancing Parentheses): Fix usage of + @itemize. + Reported by Ralf Wildenhues, fix suggested by Karl Berry. + +2009-03-14 Eric Blake + + Resync upstream files. + * GNUmakefile: Run 'make fetch'. + * build-aux/announce-gen: Likewise. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gnupload: Likewise. + * build-aux/texinfo.tex: Likewise. + * build-aux/vc-list-files: Likewise. + * doc/gnu-oids.texi: Likewise. + * doc/standards.texi: Likewise. + +2009-03-09 Ralf Wildenhues + + New test for SunStudio `restrict' handling. + * tests/c.at (AC_C_RESTRICT and C++): New test. + Prompted by bug report from Rolf Vandevaart. + +2009-03-08 Ralf Wildenhues + + Manual: testsuite depends on package.m4. + * doc/autoconf.texi (Making testsuite Scripts): In the example + makefile snippet, $(TESTSUITE) depends on $(srcdir)/package.m4. + +2009-03-02 Allan Caffee (tiny change) + + Fix a typo in comment for AS_LITERAL_IF. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Update a comment that fell + out of date when this function was moved/renamed in 59ecd766. + * THANKS: Update. + +2009-03-02 Eric Blake + + Improve wording for AS_ESCAPE. + * doc/autoconf.texi (Common Shell Constructs) : Touch + up documentation. + * lib/m4sugar/m4sh.m4 (_AS_ESCAPE): Fix comment typos. + Reported by Ralf Wildenhues. + +2009-02-24 Eric Blake + + Use pkgdatadir consistently. + * bin/Makefile.am (edit): Substitute pkgdatadir, not datadir. + * lib/Makefile.am (edit): Likewise. + * lib/autom4te.in (Autoconf-without-aclocal-m4, Autotest, M4sh) + (M4sugar): Use @pkgdatadir@, not @datadir@. + * bin/autoheader.in ($datadir): Likewise. + * bin/autom4te.in ($datadir): Likewise. + * bin/autoreconf.in ($datadir): Likewise. + * bin/autoscan.in ($datadir): Likewise. + * bin/autoupdate.in ($datadir): Likewise. + * bin/ifnames.in ($datadir): Likewise. + * doc/autoconf.texi (Installation Directory Variables): Update + example to be consistent; focus on $(bindir) as an autoconf + variable, and mention that $(pkgdatadir) comes from automake. + Reported by Reuben Thomas. + +2009-02-19 Eric Blake + + Use m4_translit more efficiently in AS_ESCAPE. + * lib/m4sugar/m4sh.m4 (_AS_ESCAPE): Alter API to take first byte + of set separately from rest. + (AS_ESCAPE, _AS_QUOTE_MODERN, AS_TR_SH, AS_VAR_GET): Adjust + callers. + * lib/autoconf/autoheader.m4 (AH_VERBATIM): Avoid duplicate + characters in translit request. + * doc/autoconf.texi (Common Shell Constructs) : + Document the macro. + * NEWS: Likewise. + + Mention recently documented macros. + * NEWS: Update list of new documentation. + +2009-02-14 Ralf Wildenhues + + Add index for config.site. + * doc/autoconf.texi (Site Defaults): Add index for config.site. + * THANKS: Update. + Report by Stephen P. Schaefer. + +2009-02-12 Eric Blake + + Fix m4_set speed regression introduced 2008-12-18. + * lib/m4sugar/m4sugar.m4 (_m4_stack_reverse): Alter API to avoid + creating larger argument on each iteration. + (m4_stack_foreach_sep, m4_stack_foreach_sep_lifo) + (_m4_set_contents_2): Adjust all four-argument callers. + +2009-02-05 Eric Blake + + Mention new AC_DEFUN_ONCE clients. + * NEWS: Mention recent semantic changes. + Reported by Ralf Wildenhues. + +2009-02-03 Eric Blake + + Use AC_DEFUN_ONCE for some one-shot AC_PROG macros. + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Switch to + AC_DEFUN_ONCE, since this is a one-shot macro. + (AC_PROG_INSTALL): Likewise. + +2009-02-03 Eric Blake + + Mention that packagers should not pre-set CFLAGS. + * doc/autoconf.texi (Preset Output Variables) : Copy + advice given by automake on handling variables reserved by GNU + Coding Standards. + Reported by Karl Berry. + + Document lib64 in config.site. + * doc/autoconf.texi (Site Defaults): Fix typo in FHS sample file. + Mention use of lib64. + * THANKS: Update. + Reported by Tom Browder, with help from Peter Breitenlohner. + +2009-01-28 Eric Blake + + Use AC_DEFUN_ONCE for uncontroversial one-shot macros. + * lib/autoconf/headers.m4 (AC_HEADER_ASSERT): Switch to + AC_DEFUN_ONCE, since this is a one-shot macro. + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Likewise. + * lib/autoconf/general.m4 (AC_CANONICAL_BUILD) + (AC_CANONICAL_HOST, AC_CANONICAL_TARGET): Likewise. + +2009-01-28 Eric Blake + + Reduce blank lines in AC_DEFUN_ONCE macros. + * lib/m4sugar/m4sugar.m4 (m4_defun_once): Avoid redundant blank + line when a defun_once macro is required. + (_m4_defun_once): New helper macro, for less memory use. + * tests/m4sugar.at (m4@&t@_require: nested): Adjust test. + + Silence another false positive expand-before-require. + * lib/m4sugar/m4sugar.m4 (_m4_defun_pro_outer) + (_m4_defun_epi_outer, _m4_require_call, m4_provide): Track name + that caused a diversion change, not just diversion number. + (m4_require): Factor... + (_m4_require_check): ...into new macro, which also checks whether + diversion that performed the expansion has been collected. + * tests/m4sugar.at (m4@&t@_require: nested): Enhance test. + Reported by Ralf Wildenhues. + +2009-01-28 Eric Blake + + Fix AC_C_RESTRICT for Sun Studio 12 C++. + * lib/autoconf/c.m4 (AC_C_RESTRICT): Newer Sun Studio C provides + __restrict__ rather than _Restrict, which still trips up Sun + Studio 12 C++. + * THANKS: Update. + Reported by Rolf Vandevaart. + +2009-01-28 Eric Blake + + Fix years in copyright notices. + * lib/m4sugar/m4sugar.m4 (m4_copyright_condense): New macro, + undocumented for now. + * lib/m4sugar/Makefile.am (version.m4): Add m4_PACKAGE_YEAR, + m4_PACKAGE_URL. + (RELEASE_YEAR): New macro, copied from bin/Makefile.am. + * lib/autoconf/general.m4 (_AC_COPYRIGHT_YEARS): New macro. + (AC_COPYRIGHT): Add undocumented third parameter. + (_AC_INIT_COPYRIGHT): Avoid need to bump copyright years. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Likewise. + (AT_COPYRIGHT): Add undocumented third parameter. + * tests/local.at (AT_COPYRIGHT): Don't add an extra copyright + parameter; the generic copyright given by autotest is sufficient + since we are the package that owns autotest. + +2009-01-27 Eric Blake + + Use URLs in --help output, part 3: testsuite. + * doc/autoconf.texi (Writing Testsuites): Mention autotest + namespace. + (Writing Testsuites) : Mention mandatory macros. + (Making testsuite Scripts): Document AT_PACKAGE_URL. + * tests/Makefile.am (package.m4): Follow our own advice. + * lib/autotest/general.m4 (AT_INIT): Give the user a hint about + package.m4. Enhance --help output. + (_AT_COPYRIGHT_YEARS): New macro, to make copyright bump easier. + + Use URLs in --help output, part 2: configure. + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Bump copyright + date. + (_AC_INIT_PACKAGE): Support optional URL parameter, mapped to + AC_PACKAGE_URL. + (_AC_INIT_DEFAULTS, _AC_INIT_PREPARE): Substitute it. + (_AC_INIT_HELP): Use it in './configure --help' output. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Likewise, for + './config.status --help'. Bump copyright date. + * doc/autoconf.texi (Initializing configure) : Document + new parameter. + * NEWS: Likewise. + * tests/tools.at (autoheader): Adjust test. + * tests/torture.at (@%:@define header templates) + (Torturing config.status): Likewise. + + Use URLs in --help output, part 1: autoconf executables. + * bin/autoconf.as (usage): Make output consistent with recent + change in gnulib version-etc module. + * bin/autoheader.in ($help): Likewise. + * bin/autom4te.in ($help): Likewise. + * bin/autoreconf.in ($help): Likewise. + * bin/autoscan.in ($help): Likewise. + * bin/autoupdate.in ($help): Likewise. + * bin/ifnames.in ($help): Likewise. + +2009-01-27 Peter Breitenlohner (tiny change) + + Quote traced macros passed from autom4te to M4. + * bin/autom4te (handle_m4): Apply shell_quote to macro names. + * tests/tools.at (autom4te --trace and unusual macro names): New + test. + * THANKS: Update. + +2009-01-26 Eric Blake + + Improve AC_DEFUN_ONCE semantics. + * lib/m4sugar/m4sugar.m4 (m4_defun_once): Rewrite to be no-op, + rather than warning, on second use, and make sure first use never + occurs out of order. + * tests/m4sugar.at (m4@&t@_require: one-shot initialization): + Enhance test. + * tests/base.at (AC_REQUIRE & AC_DEFUN_ONCE: [Require, expand], + (AC_REQUIRE & AC_DEFUN_ONCE: [Expand, require]): Adjust tests. + * NEWS: Document this. + * doc/autoconf.texi (Macro Definitions) : Mention + AC_DEFUN_ONCE. + (Prerequisite Macros) : Likewise. + (Expanded Before Required): Likewise. + (One-Shot Macros) : Document new semantics. + Reported by Bruno Haible, with suggestion by Paolo Bonzini. + +2009-01-24 Eric Blake + + Fix typos in recent patches. + * lib/m4sugar/m4sugar.m4: Improve m4_defun comments. + * doc/autoconf.texi (Expanded Before Required): Fix typos. + Reported by Ralf Wildenhues. + + Revert change to AC_DIR_HEADER. + * lib/autoconf/headers.m4 (AC_DIR_HEADER): Explicitly expanding + AC_HEADER_DIRENT no longer triggers a warning, and helps the user + who decides they don't need the obsolete AC_FUNC_CLOSEDIR_VOID. + Reported by Paolo Bonzini. + +2009-01-22 Eric Blake + + Silence a false positive expand-before-require case. + * lib/m4sugar/m4sugar.m4 (m4_provide): Track the diversion in + which a macro was provided. + (m4_require): Compare diversion numbers, rather than m4_require + nesting, when determining direct requires. + * tests/m4sugar.at (m4@&t@_require: nested): Test it. + Reported by Ralf Wildenhues, affecting Libtool. + +2009-01-21 Eric Blake + + Fix out-of-order expansion with expand-before-require. + * lib/m4sugar/m4sugar.m4 (m4_require): Redundantly expand a + required macro when issuing expand-before-require warning. + * doc/autoconf.texi (Prerequisite Macros): Adjust documentation. + (Expanded Before Required): New node. + * tests/m4sugar.at (m4@&t@_require: nested): Adjust test. + * NEWS: Mention this fix. + Suggested by Bruno Haible. + + Warn if macro is provided before indirectly required. + * lib/m4sugar/m4sugar.m4 (m4_provide): Track the set of all macros + provided since last outermost defun. + (_m4_defun_pro_outer): Empty the set. + (_m4_require_call): Distinguish between direct and indirect + requires, and remove required macros from the set. + (m4_require): Check the set, in order to warn. + * tests/m4sugar.at (m4@&t@_require: nested): Remove xfail, and add + test case for direct requires. + +2009-01-20 Eric Blake + + Clean up some bugs caught by preliminary dependency validation. + * lib/autoconf/headers.m4 (AC_DIR_HEADER): Don't invoke + AC_HEADER_DIRENT, since AC_FUNC_CLOSEDIR_VOID requires it. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL) + (_AS_SHELL_SANITIZE): Fix quoting bugs. + +2009-01-19 Eric Blake + + Improve AC_REQUIRE documentation. + * doc/autoconf.texi (Macro Definitions) : Add @defmac, + and mention interaction with AC_REQUIRE. + (Prerequisite Macros) : Give more detail on user + ordering constraint bug, and how to fix it. + * tests/m4sugar.at (m4@&t@_require: nested): New test. + + Speed up m4_require. + * lib/m4sugar/m4sugar.m4 (_m4_divert_dump): Change semantics to + always be defined, as either empty or a number. + (_m4_defun_pro_outer, _m4_defun_epi_outer): Treat _m4_divert_dump + as a stack, rather than a one-shot macro. + (_m4_require_call): Expect third argument to be pre-expanded. + (m4_divert_require, m4_require): Adjust clients accordingly. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Likewise. + +2009-01-17 Eric Blake + + Avoid underfull hbox. + * doc/autoconf.texi (Installation Directory Variables): Reword to + fit on line. + +2009-01-14 Ralf Wildenhues + + Ignore `set -e'-related failure of NetBSD sh. + * tests/m4sh.at (AS@&t@_EXIT): Skip test if (NetBSD) shell + fails to finish EXIT trap after set -e. + +2009-01-06 Eric Blake + + Maintainer cleanups. + * cfg.mk (web-manual): Use new feature of gendocs. + (fetch): Fetch gendocs. + * Makefile.am (EXTRA_DIST): Distribute new file. + * doc/Makefile.am (EXTRA_DIST): Likewise. + * .gitattributes: Ignore whitespace in upstream files. + * HACKING (Other web updates): Update Free Software Directory + instructions. + (Upload): No longer mention xdelta. + * maint.mk (xd-delta): Likewise. + * build-aux/gendocs.sh: New upstream file. + * doc/gendocs_template: Likewise. + * build-aux/announce-gen: Resync from upstream. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/gnupload: Likewise. + * build-aux/texinfo.tex: Likewise. + +2008-12-30 Eric Blake + + Make it easier to track diversion bugs. + * lib/m4sugar/m4sugar.m4 (_m4_divert_raw, _m4_undivert): New + internal macros, which are easier to trace than m4_builtin. + (m4_cleardivert, m4_divert, m4_divert_push, m4_divert_pop) + (m4_undivert): Use them. + (_m4_require_call): Likewise. Use fewer macros. + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): Fix typo. + +2008-12-26 Bruno Haible + + Improve multiarch detection. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Make detection of options + indicating a universal build more reliable. + +2008-12-28 William Pursell (tiny change) + + Use AS_CASE in documented example. + * doc/autoconf.texi (Using the System Type): Use AS_CASE in + example instead of raw case. + +2008-12-23 Eric Blake + + Make m4_dumpdef more useful with M4 1.6. + * lib/m4sugar/m4sugar.m4 (_m4_dumpdef): New macro. + (m4_init): Install it for new enough m4. + * tests/m4sugar.at (m4@&t@_dumpdef): Enhance test. + * doc/autoconf.texi (Redefined M4 Macros) : Mention + lack of sorting. + +2008-12-24 Bruno Haible + + Improve INSTALL for HP-UX. + * doc/install.texi (Particular Systems): For HP-UX, also recommend + -D_XOPEN_SOURCE=500. Needed for the declaration of mbstate_t on + HP-UX 11.11. + +2008-12-22 Bruno Haible + + Improve INSTALL for Haiku. + * doc/install.texi (Particular Systems): Add a recommendation + which prefix to use on Haiku. + +2008-12-19 Eric Blake + + Fix typo in previous commit. + * doc/autoconf.texi (Set manipulation Macros) : + Fix typo. + + Document some recently added macros. + * lib/m4sugar/m4sugar.m4 (m4_map_args_w): Add optional sep + parameter. + * doc/autoconf.texi (Looping constructs) + : Document + new macros. + (Set manipulation Macros) : Likewise. + * tests/m4sugar.at (m4@&t@_stack, M4 loops): Enhance tests. + * NEWS: Document new macros. + +2008-12-18 Eric Blake + + Fix separator in m4_stack_foreach_sep. + * lib/m4sugar/m4sugar.m4 (_m4_stack_reverse): Separate separator + from prefix. + * tests/m4sugar.at (m4@&t@_stack): Enhance test. + +2008-12-18 Eric Blake + + Mention limitation of M4 1.4.x on builtin tokens. + * doc/autoconf.texi (Redefined M4 Macros) : Document + ramification of M4 1.4.x's inability to pass builtin tokens + through text macros. + (Evaluation Macros) : Likewise. + * tests/m4sugar.at (m4@&t@_defn): Enhance test. + * NEWS: Mention subtle change in m4_dumpdef semantics. + + Document m4_version_prereq. + * doc/autoconf.texi (Number processing Macros) + : Add documentation. + * NEWS: Mention it. + Reported by Bruno Haible. + +2008-12-10 Jim Meyering + + AC_HEADER_ASSERT: don't say assertions are disabled when they're not + * lib/autoconf/headers.m4 (AC_HEADER_ASSERT): Do not make configure + report "checking whether to enable assertions... no", when they are + in fact enabled. This is solely a bug in the output of configure. + In spite of saying "no", NDEBUG was not defined in that case. + Also, as noted by Eric Blake, leave assertions enabled upon + --enable-assert=INVALID. + +2008-12-09 Eric Blake + + Fix m4_location inside m4_wrap with m4 1.4.5. + * lib/m4sugar/m4sugar.m4 (m4_undefine): Redefine m4_location + inside wrapped text if older m4 is detected. + Reported by William Pursell. + +2008-12-08 William Pursell (tiny change) + and Eric Blake + + Fix AC_HEADER_ASSERT w.r.t. --enable-assert. + * lib/autoconf/headers.m4 (AC_HEADER_ASSERT): Honor --enable-assert, + rather than treating it as a synonym for --disable-assert. + * NEWS: Document the fix. + +2008-12-06 William Pursell (tiny change) + + Fix AC_HEADER_ASSERT to honor --enable-assert, rather than + treat --enable-assert and --disable-assert equivalently. + * lib/autoconf/headers.m4 (AC_HEADER_ASSERT): Check value of $enableval. + +2008-12-05 William Pursell (tiny change) + + Fix some typos and grammatical errors in documentation. + * doc/autoconf.texi: Clean up some bad use of English. + +2008-12-03 Eric Blake + + Improve AC_STATE_SAVE. + * tests/local.at (AC_STATE_SAVE): Avoid ls -1, and use one less + process by hoisting the uniqueness check into sed. + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + MacOS bug. + +2008-12-02 Eric Blake + + Avoid MacOS readdir bug in testsuite. + * tests/local.at (AC_STATE_SAVE): Avoid spurious failures due to + duplicated ls entries. + * THANKS: Update. + Reported by Bruce Dugan and others. + +2008-11-29 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_JOB_FIFO_FD): Hide zsh 4.3.4 + error messages about `set -m'. + +2008-11-27 Ralf Wildenhues + + Fix a couple of test failures with dash. + * tests/autotest.at (AT_CHECK_AT_TITLE_CHAR): Normalize + exit status of `cd'. + * tests/m4sh.at (AS_MESSAGE_LOG_FD): Remove script before + regeneration, to avoid timing effects. + +2008-11-25 Eric Blake + + Add m4_cleardivert. + * lib/m4sugar/m4sugar.m4 (m4_cleardivert): New macro. + * lib/autotest/general.m4 (AT_INIT): Use it. + * lib/autoconf/general.m4 (_AC_INIT_NOTICE): Likewise. + * tests/m4sugar.at (m4@&t@_divert_stack): Test it. + * doc/autoconf.texi (Diversion support) : Document + it. + * NEWS: Likewise. + Suggested by Paolo Bonzini. + + Add safety check for m4_expand vs. diversions. + * lib/m4sugar/m4sugar.m4 (m4_expand): Make more robust against + diverted text. + * doc/autoconf.texi (Evaluation Macros) : Document new + safety check. + +2008-11-24 Eric Blake + + Fix typo in AS_MESSAGE_LOG_FD patch. + * lib/m4sugar/m4sh.m4 (AS_ERROR): Check correct condition. + +2008-11-23 Ralf Wildenhues + + More reliable signal handling in Autotest. + * lib/autotest/general.m4 (Driver loop): Rewrite signal handler. + Start parallel jobs in their own process group, enabling job + control in the shell if possible, for better signal handling. + Deal with INT, TERM, and HUP in the testsuite driver. In the + parallel driver, propagate TSTP to jobs either as TSTP or as + STOP (to avoid fork bombs with ksh). + Inside the job processes, add PIPE handler to write back the + job token, so the master process does not hang. + Disable the parallel driver if job control is not provided or if + trap does not understand signal names. + * tests/autotest.at (parallel autotest and signals): New test, + exercises INT, TERM, and PIPE, serial and parallel, with and + without `make' in the loop. + Kudos to Richard Stevens for writing APUE. + +2008-11-22 Eric Blake + + Fix testsuite failure on Solaris. + * tests/torture.at (AT_CHECK_CONFIG_CREATION_NOWRITE): Normalize + failure status to 1. + +2008-11-21 Eric Blake + + Clean up AS_MESSAGE_LOG_FD usage. + * lib/m4sugar/m4sh.m4 (AS_MESSAGE_FD, AS_MESSAGE_LOG_FD) + (AS_ORIGINAL_STDIN_FD): Provide default M4sh values. + (_AS_ECHO_LOG, AS_MESSAGE, _AS_ERROR_PREPARE, AS_ERROR): Simplify + usage. + (AS_INIT_GENERATED): Don't shuffle an unchanged AS_MESSAGE_FD. + * tests/m4sh.at (AS@&t@_INIT_GENERATED): Update test. + (AS@&t@_MESSAGE_FD): New test. + * doc/autoconf.texi (Initialization Macros) : + Give more details about fd manipulation. + (File Descriptor Macros): Describe M4sh defaults for the fds. + +2008-11-21 Eric Blake + + Use shell function for AS_ERROR. + * lib/m4sugar/m4sh.m4 (_AS_ERROR_PREPARE): New macro, defining a + new shell function. + (AS_ERROR): Use it. + (_AS_LINENO_PREPARE): Break circular dependency. + (AS_PREPARE, _AS_PREPARE): Initialize for child scripts. + +2008-11-21 Eric Blake + + Fix typos in recent testsuite improvements. + * lib/autotest/general.m4 (AT_INIT) : + Fix typo. + * NEWS: Clarify the potential impact to users. + * tests/autotest.at (AT_DATA_AUTOTEST): New macro, patterned after + AT_DATA_M4SUGAR. + (AT_CHECK_AT_PREP, AT_CHECK_AT_TITLE): Use it. + (unusual file names): Test that the recent echo fix does not + regress. Fix quoting bug that made the test a no-op. + Reported by Paolo Bonzini and Ralf Wildenhues. + +2008-11-21 Eric Blake + + Use modern m4sh constructs in autoconf. + * bin/autoconf.as (exit_missing_arg, getopt): Use AS_ERROR, rather + than AS_EXIT. + + Change the semantics of AS_EXIT without argument. + * lib/m4sugar/m4sh.m4 (_AS_EXIT_PREPARE): When defaulting, use $? + even if it is 0. + (AS_ERROR): Guarantee non-zero status. + * bin/autoconf.as (exit_missing_arg, getopt): Revert prior change; + we want non-zero status. + * tests/m4sh.at (AS@&t@_EXIT): Update test accordingly. + * doc/autoconf.texi (Common Shell Constructs) : Update + the documentation. + : Don't overly restrict implementation. + (Printing Messages) : Describe better default. + Suggestions by Paolo Bonzini and Ralf Wildenhues. + +2008-11-21 Eric Blake + + Add @anchors within Builtins and Usual Tools lists. + * doc/autoconf.texi (Limitations of Builtins) + (Limitatations of Usual Tools): Add anchors for tools called out + by name. Adjust callers to narrow in on tool of interest. + + Move case statement style discussion to m4 quoting section. + * doc/autoconf.texi (Limitations of Builtins): Move comparison of + quoting styles... + (Balancing Parentheses): ...to this new node. + Suggested by Ralf Wildenhues. + +2008-11-20 Eric Blake + + Factor more common code out of AT_CHECK into shell function. + * lib/autotest/general.m4 (_AT_CHECK): Avoid echo bug if AT_LINE + starts with -. Move preparations... + (AT_INIT) + : + ...into these new shell functions. + : Inline into only caller. + (_AT_DECIDE_TRACEABLE): Use them to condense testsuite size. + +2008-11-20 Eric Blake + + Handle version numbers as decimal, even if they start with 0. + * lib/m4sugar/m4sugar.m4 (_m4_version_unletter): Avoid + interpreting leading zeros as octal. + +2008-11-20 Eric Blake + + Speed up AT_CHECK. + * lib/autotest/general.m4 (AT_CHECK, AT_CHECK_UNQUOTED): Expand + third and fourth arguments once. + (_AT_CHECK): Don't re-expand expected output. Rearrange code for + fewer scans of arguments. + (AT_CHECK): Update caller. + (AT_INIT) : Drop parameter. + * tests/m4sugar.at (m4@&t@_split): Protect test with + quadrigraphs. + + Fix XFAIL related to AT_CHECK. + * lib/autotest/general.m4 (AT_CHECK, AT_CHECK_UNQUOTED): Expand + first argument once. + (_AT_CHECK): Don't re-expand commands. + * tests/autotest.at (Multiline command from M4 expansion): Remove + XFAIL. + * tests/tools.at (autoupdating AU_ALIAS): Quote unbalanced paren. + * NEWS: Document the fallout. + +2008-11-20 Eric Blake + + Reduce forks in AC_DEFINE. + * lib/autoconf/general.m4 (_AC_DEFINE_Q_PRINT): New macro. + (_AC_DEFINE_Q): Use it to avoid forks for all AC_DEFINE and most + AC_DEFINE_UNQUOTED. + * lib/autoconf/fortran.m4 (_AC_FC_WRAPPERS): Properly quote #. + * tests/torture.at (Substitute and define special characters): + (Define to a 2000-byte string): Enhance tests to cover + AC_DEFINE_UNQUOTED. + (@%:@define header templates): Enhance test to cover #. + +2008-11-20 Eric Blake + + Improve m4_expand robustness, part 2. + * lib/m4sugar/m4sugar.m4 (m4_expand): Support unterminated + comments, by wrapping old implementation... + (_m4_expand): ...as this, and renaming old core... + (_m4_expand_): ...to this. + (m4_text_box): Use lighter-weight _m4_expand. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_EXPAND) + (_AS_DETECT_BETTER_SHELL, AS_FUNCTION_DESCRIBE): Likewise. + * lib/autotest/general.m4 (AT_KEYWORDS): Likewise. + * tests/m4sugar.at (m4@&t@_expand): Enhance test. + * tests/autotest.at (AT_CHECK_AT_TITLE_CHAR): Likewise. + * doc/autoconf.texi (Evaluation Macros) : Mention new + functionality. + + Improve m4_expand robustness, part 1. + * lib/m4sugar/m4sugar.m4 (_m4_expand): Tolerate unquoted + unbalanced `)'. + * tests/m4sugar.at (m4@&t@_expand): New test. + +2008-11-20 Eric Blake + + Add m4_chomp, m4_esyscmd_s. + * lib/m4sugar/m4sugar.m4 (m4_esyscmd_e, m4_chomp, m4_chomp_all): + New macros. + * doc/autoconf.texi (Redefined M4 Macros) : Document + them. + (Text processing Macros) : Likewise. + * NEWS: Likewise. + * tests/m4sugar.at (m4@&t@_esyscmd_s): New test. + + Remove _m4_index. + * lib/m4sugar/m4sugar.m4 (_m4_index): Delete; it is more efficient + to make callers guarantee a match. + (m4_init): Adjust caller. + * lib/autoconf/status.m4 (_AC_CONFIG_COMPUTE_DEST): Likewise. + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Likewise. + + Describe different hacks for balancing ')' in case statements. + * doc/autoconf.texi (Limitations of Builtins) : Add an + exposition on various quoting styles. + +2008-11-20 Eric Blake + + Speed up _AS_QUOTE. + * lib/m4sugar/m4sh.m4 (_AS_QUOTE_IFELSE): Inline into... + (_AS_QUOTE): ...here, delete unused second parameter, and factor + choice into... + (_AS_QUOTE_MODERN, _AS_QUOTE_OLD): ...new helpers. + +2008-11-20 Alfred G. de Wijn (tiny change) + + For consistency, make temporary variable match language name. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_G, _AC_PROG_FC_V_OUTPUT): + Match the save/test variables' names to the FFLAGS/FCFLAGS being + saved. + * THANKS: Update. + +2008-11-19 Eric Blake + + Improve testsuite generation. + * tests/local.at (AT_DATA_M4SUGAR, AT_DATA_M4SH) + (AT_DATA_AUTOCONF): Escape all quadrigraphs, not just @&t@. Use + fewer macros. + +2008-11-18 Eric Blake + + Use fn for shell functions, func for autoconf CHECK_FUNCS. + * lib/autoconf/functions.m4 (AC_CHECK_FUNC): Abbreviate shell + function names. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE) + (_AC_COMPILE_IFELSE, _AC_LINK_IFELSE, _AC_RUN_IFELSE) + (AC_CHECK_DECL, AC_COMPUTE_INT): Likewise. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL) + (_AC_CHECK_HEADER_COMPILE, _AC_CHECK_HEADER_PREPROC): Likewise. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW, _AC_TYPE_INT) + (_AC_TYPE_UNSIGNED_INT, AC_CHECK_MEMBER): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_WORK, _AS_EXIT_PREPARE) + (AS_EXIT, AS_SET_STATUS, _AS_UNSET_PREPARE, _AS_MKDIR_P) + (_AS_MKDIR_P_PREPARE, _AS_VAR_APPEND_PREPARE, AS_VAR_APPEND) + (_AS_VAR_ARITH_PREPARE, AS_VAR_ARITH): Likewise. + * doc/autoconf.texi (Shell Functions): Likewise. + +2008-11-18 Eric Blake + + Alter default value of AS_EXIT. + * lib/m4sugar/m4sh.m4 (_AS_EXIT_PREPARE): Let as_func_exit + parameter be optional. + (AS_EXIT): Use it to make better default. + (_AS_DETECT_BETTER_SHELL): Use new default. + * bin/autoconf.as (exit_missing_arg, getopt): Likewise. + * lib/autoconf/status.m4 (AC_OUTPUT): Likewise. + * tests/m4sh.at (AS@&t@_EXIT): Update test. + * doc/autoconf.texi (Common Shell Constructs) : Mention + new default behavior. + (Limitations of Builtins) : Adjust to use new default. + * NEWS: Mention the semantic change. + Suggested by Ralf Wildenhues. + + Update example to match actual Tru64 behavior. + * doc/autoconf.texi (Limitations of Builtins) : Correct + the example. + Reported by Ralf Wildenhues. + + Add AS_SET_STATUS, make AS_EXIT more efficient. + * lib/m4sugar/m4sh.m4 (_AS_EXIT_PREPARE, AS_SET_STATUS): New + macros. + (AS_EXIT): Rewrite to avoid forks. + (_AS_SHELL_SANITIZE): Avoid AS_EXIT prior to shell functions. + (AS_PREPARE, _AS_PREPARE): Add new preparation. + * doc/autoconf.texi (Common Shell Constructs) : + Document. + * NEWS: Mention new macro. + * tests/m4sh.at (AS@&t@_EXIT): New test. + (BASENAME_TEST): Sort. + + Document Tru64 bug with 'set -e'. + * doc/autoconf.texi (Limitations of Builtins) : Mention a + bug in mixing 'set -e' with 'trap .. 0'. + Reported by Ralf Wildenhues. + + Document a Solaris /bin/sh bug with 'set -e'. + * doc/autoconf.texi (Shell Functions): Mention the bug. + +2008-11-17 Eric Blake + + Detect empty list in AS_FOR. + * lib/m4sugar/m4sh.m4 (AS_FOR): Handle iteration over $@ + properly. + * tests/m4sh.at (AS@&t@_FOR): Enhance test to catch it. + Reported by Paolo Bonzini. + +2008-11-16 Ralf Wildenhues + + Use a different workaround for an automake quirk. + * tests/Makefile.am (AUTOMAKE_OPTIONS): Remove. + (distclean_generic): New helper variable, to fool automake. + ($(distclean_generic)): Depend on clean-local, to prevent + the race in the two rules with accessing and removing + $(TESTSUITE). + Report by Eric Blake. + + * lib/m4sugar/m4sh.m4 (_AS_VAR_ARITH_PREPARE): Simplify, avoid + unbalanced parentheses from last change. + Spotted by Eric Blake, fix suggested by Paolo Bonzini. + + Fix exit status of expr version of as_func_arith. + * lib/m4sugar/m4sh.m4 (_AS_VAR_ARITH_PREPARE): Count an exit + status of 1 of expr also as success, to avoid failure if the + computation result is zero. Fixes test failures with IRIX sh, + where the expr variant of as_func_arith is used. + + Do not use read-only variable $status. + * tests/compile.at (AC_RUN_IFELSE): Use $estatus instead of + $status, for zsh. + +2008-11-15 Eric Blake + + Use the new AS_FOR function. + * lib/autoconf/functions.m4 (AC_CHECK_FUNCS): Use new + abstraction for cleaner code. + * lib/autoconf/headers.m4 (AC_CHECK_HEADERS): Likewise. + + Add AS_FOR, undocumented for now. + * lib/m4sugar/m4sh.m4 (AS_FOR): New macro. + * tests/m4sh.at (AS@&t@_FOR): New test. + Suggested by Paolo Bonzini. + +2008-11-13 Eric Blake + + Optimize single-argument loop. + * lib/autoconf/functions.m4 (AC_CHECK_FUNCS): Avoid forks when + loop only has one argument. + * lib/autoconf/headers.m4 (AC_CHECK_HEADERS): Likewise. + +2008-11-13 Eric Blake + + Fix AS_ESCAPE usage bugs. + * lib/m4sugar/m4sh.m4 (_AS_VAR_APPEND_PREPARE) + (_AS_VAR_ARITH_PREPARE): Expand macros prior to adding shell + escapes. + (AS_TR_SH, AS_VAR_GET): Use _AS_ESCAPE for speed. + * doc/autoconf.texi (Polymorphic Variables) : Document + caveat due to conditional AS_ESCAPE. + * tests/m4sh.at (AS@&t@_VAR basics): Enhance test. + +2008-11-12 Eric Blake + + Whitespace reduction in configure. + * lib/autoconf/autoheader.m4 (AH_VERBATIM): Avoid empty lines. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE, AC_CHECK_FILES): + Likewise. + (_AC_DEFINE_Q): Restore empty line, since some clients in the wild + depend on it. + +2008-11-12 Eric Blake + + Make M4sh, not autoconf, guarantee sane $SHELL. + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Move setting of + SHELL... + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): ...to here. + * doc/autoconf.texi (Initialization Macros): Document the effect + on SHELL. + * tests/m4sh.at (AS@&t@_INIT_GENERATED): New test. + Reported by Ralf Wildenhues. + +2008-11-12 Ralf Wildenhues + + Wrap keywords in `testsuite --list' output. + * lib/autotest/general.m4 (AT_INIT): Rewrite --list awk script, + avoid lint warnings from gawk, wrap keyword lists to stay below + 80 characters per line if possible. + * tests/autotest.at (Keyword wrapping): New test. + + * tests/local.at (AT_COPYRIGHT): Bump copyright years. + + * doc/autoconf.texi (Conditional constructs, Macro Names): Fix + typos. + +2008-11-10 Eric Blake + + Work around <=m4-1.4.9 bug in m4_format. + * lib/m4sugar/m4sugar.m4 (_m4_index): New internal macro. + (m4_init): Only use it in older m4. + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Use it to avoid + m4_format bug in older m4. + * lib/autoconf/status.m4 (_AC_CONFIG_COMPUTE_DEST): Likewise. + Reported by Bob Proulx. + +2008-11-10 Eric Blake + + Match upstream standards.texi. + * doc/standards.texi: Resync from upstream. + * doc/fdl-1.3.texi: Rename... + * doc/fdl.texi: ...to this. + * doc/Makefile.am (autoconf_TEXINFOS, standards_TEXINFOS): Update + users. + * doc/autoconf.texi (GNU Free Documentation License): Likewise. + * cfg.mk (fetch): Likewise. + + Yet more FDL 1.3 fallout. + * NEWS: Mention manual license change. + +2008-11-10 Eric Blake + + Avoid some regex uses. + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Use m4_format rather + than m4_bpatsubst to grab string prefix. + * lib/autoconf/status.m4 (_AC_CONFIG_REGISTER) + (_AC_CONFIG_REGISTER_DEST, AC_CONFIG_SUBDIRS): Likewise. + (_AC_FILE_DEPENDENCY_TRACE_COLON): Use m4_translit instead of + m4_bpatsubst to change bytes. + (_AC_CONFIG_DEPENDENCY_DEFAULT): Use m4_index rather than + m4_bmatch to find byte. + (_AC_CONFIG_COMPUTE_DEST): New helper macro. + + Use more efficient macros in AC_CONFIG_SUBDIRS. + * lib/autoconf/status.m4 (_AC_CONFIG_FOOS, AC_CONFIG_SUBDIRS): Use + m4_map_args_w. + (_AC_OUTPUT_FILE): Use m4_map_args_sep and m4_map_args. + (_AC_OUTPUT_FILE_ADJUST_DIR): New helper macro. + + Use more efficient macros in AC_CHECK_FILES and AC_CHECK_DECLS. + * lib/autoconf/general.m4 (AC_CHECK_FILES): Use m4_map_args_w, + and avoid typo. + (AC_CHECK_DECLS, AC_CHECK_DECLS_ONCE): Use m4_map_args_sep. + (_AC_CHECK_FILES, _AC_CHECK_DECLS, _AC_CHECK_DECL_ONCE): New + helper macros. + (AC_LIBSOURCES): Use m4_map_args. + + Use more efficient macros in AC_CHECK_TYPES. + * lib/autoconf/types.m4 (AC_CHECK_TYPES, AC_CHECK_MEMBERS): Use + m4_map_args_sep. + (_AC_CHECK_TYPES, _AC_CHECK_MEMBERS): New helper macros. + + Use more efficient macros in AC_CHECK_HEADERS. + * lib/autoconf/headers.m4 (AH_CHECK_HEADERS) + (AH_CHECK_HEADERS_DIRENT): Rename... + (_AH_CHECK_HEADER, _AH_CHECK_HEADER_DIRENT): ...and take only one + argument, rather than a list. + (AC_CHECK_HEADERS, AC_CHECK_HEADERS_ONCE): + Adjust callers to use m4_map_args_w. + (AC_HEADER_DIRENT): Adjust caller to use m4_map_args. + (_AC_CHECK_HEADER_ONCE): New helper macro. + + Use more efficient macros in AC_CHECK_FUNCS. + * lib/autoconf/functions.m4 (_AH_CHECK_FUNCS): Rename... + (_AH_CHECK_FUNC): ...and take only one argument, rather than a + list. + (AC_CHECK_FUNCS, AC_CHECK_FUNCS_ONCE): Adjust callers to use + m4_map_args_w. + (_AC_CHECK_FUNC_ONCE): New helper macro. + (AC_REPLACE_FUNCS): Use m4_map_args_w. + + Use more efficient macro in AT_INIT. + * lib/autotest/general.m4 (AT_INIT): Use m4_map_args. + +2008-11-10 Eric Blake + + More FDL 1.3 fallout. + * cfg.mk (fetch): Add gnu-oids.texi, drop fdl.texi. + * doc/Makefile.am (standards_TEXINFOS): Reflect upstream + dependency changes. + * doc/fdl.texi: Delete. + * doc/gnu-oids.texi: New upstream file. + * doc/standards.texi: Resync from upstream. + * doc/make-stds.texi: Likewise. + * build-aux/announce-gen: Likewise. + * build-aux/texinfo.tex: Likewise. + +2008-11-10 Clinton Roy (tiny change) + + Pass autoreconf -I to aclocal -I + * bin/autoreconf.in (parse_args): Pass --include to aclocal. + * doc/autoconf.texi (autoreconf Invocation): Updates for above. + * NEWS: Document it. + * THANKS: Update. + +2008-11-10 Eric Blake + + Try 'print -r --' as a non-forking variant of 'printf %s\\n'. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_PREPARE): Cater to Solaris ksh. + * doc/autoconf.texi (Limitations of Builtins) : Document + the print workaround. + Idea by Paolo Bonzini. + +2008-11-10 Eric Blake + + Provide a section on all tools allowed in GNU Coding Standards. + * doc/autoconf.texi (Limitations of Builtins) : Sort. + : Add section. + (Limitations of Usual Tools) : Make table entry consistent. + Add sections. + +2008-11-09 Paolo Bonzini + + Balance parentheses in _AC_CACHE_DUMP. + * lib/autoconf/general.m4 (_AC_CACHE_DUMP): Balance parentheses + without introducing \). + +2008-11-07 Eric Blake + + Further doc updates for AC_CHECK_HEADER change. + * doc/autoconf.texi (Generic Headers) : Mention + new default, and make it more obvious that using [-] is generally + broken. + +2008-11-07 Eric Blake + + * ChangeLog: Enforce UTF-8 encoding. + +2008-11-06 Eric Blake + + Skip preprocessor check in AC_CHECK_HEADERS_ONCE. + * lib/autoconf/headers.m4 (_AC_HEADERS_EXPANSION): Provide fourth + argument to speed up check. + +2008-11-06 Eric Blake + + Speed up AC_CHECK_TYPE. + * lib/autoconf/types.m4 (AC_CHECK_TYPE): Factor out $@, and avoid + regex when enough arguments are present. + +2008-11-06 Paolo Bonzini + + Remove three forks per _AC_RUN_LOG_STDERR in the common case. + * lib/autoconf/general.m4 (_AC_RUN_LOG_STDERR): Avoid grep/rm/cat + sequence when the program's stderr was empty, while providing a + conftest.err file even in that case. + (_AC_CACHE_DUMP): Fix mismatched parenthesis. + +2008-11-06 Paolo Bonzini + + Change `present but cannot be compiled' behavior to use compiler result. + * NEWS: Document it. + * doc/autoconf.texi (Present But Cannot Be Compiled): Document it. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Implement it + and adjust warning. + * tests/semantics.at (AC_CHECK_HEADERS): Test new semantics. + +2008-11-05 Eric Blake + + Add m4_map_args_w. + * lib/m4sugar/m4sugar.m4 (m4_map_args_w): New macro, undocumented + for now. + (_m4_split): Allow user control over separator. + (m4_split): Adjust caller. + (m4_foreach_w, m4_append_uniq_w, _m4_text_wrap): Rewrite to use + m4_map_args_w. + * tests/m4sugar.at (m4@&t@_append): Augment test keywords. + (M4 loops): Test new interface. + + Use m4_set_map_sep in more places. + * lib/m4sugar/m4sugar.m4 (m4_set_difference, m4_set_intersection) + (m4_set_union): Use m4_set_map_sep rather than m4_set_foreach. + * doc/autoconf.texi (Set manipulation Macros) : + Enhance documentation. + : Mention faster alternative. + (Looping constructs) : Likewise. + + Unify m4_set_foreach and m4_set_map. + * lib/m4sugar/m4sugar.m4 (m4_set_map_sep): New macro, undocumented + for now. + (m4_set_contents, m4_set_foreach, m4_set_list, m4_set_listc) + (m4_set_map): Adjust callers. + + Use _m4_foreach in more places. + * lib/m4sugar/foreach.m4 (m4_dquote_elt, m4_join, m4_joinall) + (_m4_minmax, m4_set_add_all): Use _m4_foreach instead of + m4_foreach. + * lib/m4sugar/m4sugar.m4 (_m4_joinall): Use m4_map_args_sep + instead of m4_foreach or m4_map_args. + + Unify _m4_foreach and _m4_map. + * lib/m4sugar/m4sugar.m4 (_m4_map): Delete, merged with... + (_m4_foreach): ...this. + (m4_foreach, m4_map, m4_mapall, m4_map_sep, _m4_mapall_sep) + (m4_map_args, m4_map_args_sep): Adjust callers. + * lib/m4sugar/foreach.m4 (_m4_map): Rename... + (_m4_foreach): ...to this, overwriting old definition. + +2008-11-04 Eric Blake + + Add m4_map_args_sep, undocumented for now. + * lib/m4sugar/m4sugar.m4 (m4_map_args_sep): New macro. + (_m4_map): Change API to cover more of m4_map*. + * lib/m4sugar/foreach.m4 (_m4_map): Adjust to new API. + (m4_map_args): Delete. + * tests/m4sugar.at (m4@&t@_map_args and m4@&t@_curry): Enhance + test. + + Improve m4_for performance. + * lib/m4sugar/m4sugar.m4 (_m4_for): Alter API to make it easier to + avoid m4_define by some clients. + (m4_for): Adjust caller. + * lib/m4sugar/foreach.m4 (_m4_foreach, m4_case, m4_bmatch) + (_m4_cond, _m4_bpatsubsts, _m4_shiftn, m4_do, m4_reverse) + (_m4_map, m4_map_args, m4_map_args_pair, _m4_list_pad) + (_m4_list_cmp): Likewise. + +2008-11-04 Eric Blake + + Adjust expected output. + * tests/torture.at (Missing templates): Reflect added quoting. + Detected by Bob Proulx's buildbot. + + Reject arguments with leading =. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Detect case of + missing variable name, with fewer forks. Quote invalid arguments + in message, in case they include spaces. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS) + (_AC_OUTPUT_MAIN_LOOP): Quote invalid arguments. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * tests/base.at (configure arguments): Test this. + Reported by Jeff Squyres. + +2008-11-04 Eric Blake + + Upgrade to FDL 1.3. + * cfg.mk (fetch): Add fdl-1.3.texi. + * .gitattributes: Likewise. + * doc/autoconf.texi (GNU Free Documentation License): Point to new + upstream version. + * doc/Makefile.am (autoconf_TEXINFOS): Likewise. + (standards_TEXINFOS): Mention current dependence on older license. + * doc/fdl-1.3.texi: New upstream file. + * GNUmakefile: Resync from upstream. + * build-aux/announce-gen: Likewise. + * build-aux/texinfo.tex: Likewise. + +2008-11-03 Ralf Wildenhues + + Point at AM_SUBST_NOTMAKE. + * doc/autoconf.texi (Setting Output Variables): Add cross + reference to new Automake macro AM_SUBST_NOTMAKE. + +2008-11-03 Paolo Bonzini + + Eliminate a fork per invocation of AC_LANG_CONFTEST. + * lib/autoconf/c.m4 (AC_LANG_CONFTEST(C)): Define instead of + AC_LANG_SOURCE(C). + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Add a comment at the + top of confdefs.h, which also works around cpp deficiencies. + * lib/autoconf/lang.m4 (AC_LANG_DEFINE): Define AC_LANG_CONFTEST(xyz) + (AC_LANG_CONFTEST): Dispatch based on _AC_LANG. + (AC_LANG_CONFTEST()): New. + +2008-11-03 Paolo Bonzini + + Reorganize definition of languages. + * lib/autoconf/c.m4 (AC_LANG(C), AC_LANG(C++), AC_LANG(Objective C), + _AC_LANG_ABBREV(C), _AC_LANG_ABBREV(C++), _AC_LANG_ABBREV(Objective C), + _AC_LANG_PREFIX(C), _AC_LANG_PREFIX(C++), _AC_LANG_PREFIX(Objective C)): + Replace definitions with usage of AC_LANG_DEFINE. + (Sections 2b, 2c): Delete. + (Sections 1b, 1c): Move after section 2a. + * lib/autoconf/erlang.m4 (AC_LANG(Erlang), _AC_LANG_ABBREV(Erlang), + _AC_LANG_PREFIX(Erlang), AC_LANG_SOURCE(Erlang)): Replace definitions + with usage of AC_LANG_DEFINE. + (AC_LANG_ERLANG): Define using AU_DEFUN. + * lib/autoconf/fortran.m4 (AC_LANG(Fortran), AC_LANG(Fortran 77), + _AC_LANG_ABBREV(Fortran), _AC_LANG_ABBREV(Fortran 77), + _AC_LANG_PREFIX(Fortran), _AC_LANG_PREFIX(Fortran 77), + _AC_LANG_SOURCE(Fortran), AC_LANG_SOURCE(Fortran 77)): Replace + definitions with usage of AC_LANG_DEFINE. + * lib/autoconf/lang.m4 (AC_LANG_DEFINE, AC_LANG_SOURCE()): New. + +2008-11-03 Paolo Bonzini + + Use preprocessor in cpp tests. + * tests/c.at (CPP tests): Use AC_CHECK_HEADERS(..., [-]). + +2008-10-31 Paolo Bonzini + + Rename _AC_CHECK_HEADER_OLD and _AC_CHECK_HEADER_NEW. + * lib/autoconf/headers.m4 (AC_CHECK_HEADER): Adjust naming. + (_AC_CHECK_HEADER_PREPROC_BODY): New name of _AC_CHECK_HEADER_OLD_BODY. + (_AC_CHECK_HEADER_COMPILE_BODY): New name of _AC_CHECK_HEADER_NEW_BODY. + (_AC_CHECK_HEADER_PREPROC): New name of _AC_CHECK_HEADER_OLD. + (_AC_CHECK_HEADER_COMPILE): New name of _AC_CHECK_HEADER_NEW. + * tests/semantics.at (AC_CHECK_HEADERS_OLD, AC_CHECK_HEADER_NEW): + Give better name. + +2008-10-31 Eric Blake + + Support multiple undiverts and dumpdefs at once. + * lib/m4sugar/m4sugar.m4 (m4_dumpdefs, m4_undivert): Allow extra + arguments. + * doc/autoconf.texi (Redefined M4 Macros) , + : Document argument list change. + * tests/m4sugar.at (m4@&t@_divert_stack, m4@&t@_dumpdef): Test + them. + + Simplify diversion stack handling. + * lib/m4sugar/m4sugar.m4 (m4_divert_stack): Use fewer macros, and + avoid extra newlines. + (m4_divert_stack_push): Compute location here, rather than caller. + (m4_divert_push): Update caller. + (m4_divert): Likewise, and also adjust current diversion name. + (m4_divert_pop): Simplify rule that diversion stack must never go + empty. + (_m4_require_call): Bypass diversion stack when collecting + required macro text. + (m4_init): Set current diversion without requiring m4_init. + * lib/m4sugar/m4sh.m4 (AS_INIT): Avoid too many pops. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Schedule wrapped + text to run prior to m4sugar cleanup. + * doc/autoconf.texi (Text processing Macros) : Mention + optional argument. + (Conditional constructs) : Mention use of dnl. + * NEWS: Undo blurb about m4_divert. + * tests/m4sugar.at (m4@&t@_divert_stack): New test. + + Simplify expansion stack handling. + * lib/m4sugar/m4sugar.m4 (m4_expansion_stack): Use fewer macros; + always output 'top level'. + (_m4_expansion_stack_entry): New macro, to format the string only + when needed. + (m4_expansion_stack_push): Only push a macro name. + (m4_warn, _m4_defun_pro): Update callers. + (m4_expansion_stack_pop, m4_expansion_stack_dump): Delete. + (_m4_defun_epi, m4_fatal): Inline the calls. + * tests/m4sugar.at (m4@&t@_expansion_stack): New test. + +2008-10-30 Eric Blake + + Better documentation of AC_CHECK_HEADER's fourth argument. + * doc/autoconf.texi (Generic Headers) : Mention + how to suppress compiler or preprocessor header check. + Reported by Jeff Squyres. + +2008-10-30 Eric Blake + + Fix LINENO testsuite failure. + * tests/m4sh.at (AT_DATA_LINENO): Use AS_LINENO_PREPARE, not + undocumented _AS_PREPARE, and move unset earlier in script. + + Update LINENO documentation. + * doc/autoconf.texi (Initialization Macros) : + (Special Shell Variables) : Mention that LINENO support in + child scripts may be broken. Modernize example. + +2008-10-30 Paolo Bonzini + + Do not check for $LINENO in generated scripts. + * lib/m4sugar/m4sh.m4 (_AS_PREPARE): Do not call _AS_LINENO_PREPARE, + and explain why. + +2008-10-30 Eric Blake + + Don't check for non-POSIX extensions in suggested tests. + * lib/m4sugar/m4sh.m4 (_AS_VAR_APPEND_WORKS): Remove suggestion; + we still use += if available, but should not reject shells (like + dash) that don't provide it. + (_AS_DETECT_SUGGESTED): Document a policy for m4sh. + Reported by Paolo Bonzini. + +2008-10-30 Paolo Bonzini + + Pass CONFIG_SHELL down to generated scripts, and re-export SHELL. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): If proceeding + with a given CONFIG_SHELL, move it to SHELL. + (AS_INIT_GENERATED): Re-export SHELL. + +2008-10-30 Eric Blake + + Work around Solaris /bin/sh case bug. + * lib/m4sugar/m4sh.m4 (_AS_CASE, _AS_CASE_DEFAULT): Always provide + a non-empty command list. + (AS_CASE): Always guarantee that a case will match. + * doc/autoconf.texi (Limitations of Builtins) : Document the + Solaris bug, and mention AS_CASE. + +2008-10-30 Paolo Bonzini + + Require _AS_CR_PREPARE where appropriate. + * lib/m4sugar/m4sh.m4 (_AS_PREPARE): Call _AS_CR_PREPARE. + (AS_PREPARE): Require _AS_CR_PREPARE. + + Avoid walking the entire PATH when looking for a better shell. + * lib/m4sugar/m4sh.m4 (_AS_SHELL_SANITIZE): Test shell characteristics + as the PATH is walked. + + Add third argument to _AS_PATH_WALK + * lib/m4sugar/m4sh.m4 (_AS_SHELL_SANITIZE): Do not call _AS_CR_PREPARE. + (_AS_PATH_WALK): Add third optional argument. + + Trim down the length of the shell function test. + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_WORK): Condense. + +2008-10-29 Eric Blake + + Fix LINENO detection to work around bash and pdksh limitations. + * lib/m4sugar/m4sh.m4 (_AS_LINENO_WORKS): Enhance the test, so + that we can choose which of two tests to trust. + (_AS_RUN): Set flag when alternate shell is running. + (_AS_DETECT_EXPAND): New macro. + (_AS_DETECT_BETTER_SHELL): Use it to massage LINENO tests. + +2008-10-29 Eric Blake + + Mention proper fix for zsh users. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Recommend zsh + version known to work. + Suggested by Paolo Bonzini. + + Document current beta-quality status. + * configure.ac: Reflect fact that change to git-version-gen + produces -, but not always a letter, on non-release builds. + * BUGS: Mention known issues. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Ask for help in + debugging platforms with deficient shells. + +2008-10-29 Eric Blake + + Alter signature of AS_INIT_GENERATED. + * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): Add parameters, and + manage here-doc and chmod in place. This also allows future + changes for optimizing the child via diversion/m4_wrap magic. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Update + caller. + * doc/autoconf.texi (Initialization Macros) : + Update the documentation. + +2008-10-29 Eric Blake + + Use _m4_stack_reverse in m4_set. + * lib/m4sugar/m4sugar.m4 (_m4_set_contents_1) + (_m4_set_contents_2): Rewrite to share _m4_stack_reverse + implementation. + (m4_set_contents, m4_set_foreach, m4_set_list, m4_set_listc) + (m4_set_map): Adjust callers to new API. + + Add m4_stack_foreach_sep. + * lib/m4sugar/m4sugar.m4 (m4_stack_foreach_sep) + (m4_stack_foreach_sep_lifo): New macros. + (_m4_stack_reverse): Adjust prototype, to support it. + (m4_copy): Use fewer macros. + * tests/m4sugar.at (m4@&t@_stack_foreach): Rename... + (m4@&t@_stack): ...and add m4_stack_foreach_sep tests. + +2008-10-29 Bruno Haible + + Mention Sun WorkShop 6.2 OpenMP bug. + * doc/autoconf.texi (AC_OPENMP): Document portability pitfall. + +2008-10-29 Paolo Bonzini + + Rewrite handling of diversion and expansion stack. + * NEWS: Document stricter requirement on m4_init. + * lib/m4sugar/m4sugar.m4 (m4_divert_stack): New, replacing + _m4_divert_n_stack. + (_m4_divert_stack_push): New. + (m4_divert): Use _m4_divert_stack_push and replace m4_define with + m4_popdef. + (m4_divert_push): Use _m4_divert_stack_push. + (m4_divert_pop): Use m4_divert_stack instead of _m4_divert_n_stack, + pop _m4_divert_stack instead of m4_divert_stack. + (m4_expansion_stack): New. Update comment above it. + (m4_expansion_stack_push, m4_expansion_stack_pop): Work on + _m4_expansion_stack instead of m4_expansion_stack. + (m4_expansion_stack_dump): Check presence of _m4_expansion_stack + instead of m4_expansion_stack. Use m4_expansion_stack's expansion + instead of the definition, and compensate for the trailing newline + in the expansion. + (m4_warn, _m4_defun_pro, _m4_defun_epi): Check presence of + _m4_expansion_stack instead of m4_expansion_stack. + (m4_newline): Expand first argument after the newline. + (m4_init): Use m4_divert_stack instead of _m4_divert_n_stack, + * tests/m4sugar.at (m4_append, m4_text_wrap): Invoke m4_init. + * tests/tools.at (whitespace in file names, the empty token): Likewise. + +2008-10-28 Eric Blake + + Reduce forks while searching for better shell. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_REQUIRED) + (_AS_DETECT_SUGGESTED): No need to provide extra subshell; _AS_RUN + already does the job. + (_AS_DETECT_BETTER_SHELL): Simplify AS_EXIT when not run in a trap + 0 context. + + Undo needless efforts to protect $2 in $2_t. + * lib/autoconf/types.m4 (_AC_TYPE_INT_BODY) + (_AC_TYPE_UNSIGNED_INT_BODY): Reduce extra quoting. + +2008-10-28 Ralf Wildenhues + + Fix parallel test execution output lossage. + * lib/autotest/general.m4 (_AT_CHECK): Truncate files to hold + standard output and standard error before the test, use append + mode for writing. + * THANKS: Update. + Caught by Bob Proulx' build daemons, analysis and suggested fix + by Stéphane Chazelas. + +2008-10-28 Eric Blake + + Use m4_map_args in more places. + * lib/m4sugar/m4sugar.m4 (m4_defn, m4_dumpdef, m4_popdef) + (m4_undefine, m4_combine): Use m4_map_args, rather than + m4_foreach. + +2008-10-28 Eric Blake + + Override m4 1.4.x dumpdef, as it breaks autom4te. + * lib/m4sugar/m4sugar.m4 (m4_dumpdef): New implementation. + (m4_copy): Formatting touchup. + * doc/autoconf.texi (Redefined M4 Macros) : Mention + semantic differences as well as m4_dumpdefs. + * NEWS: Likewise. + * tests/m4sugar.at (m4@&t@_dumpdef): New test. + +2008-10-28 Eric Blake + + Allow m4sugar to be used without autom4te, such as in bison. + * lib/m4sugar/m4sugar.m4 (m4_text_wrap, m4_qlen): Document that + alternate escape sequences can be used. + (m4_text_box): Likewise. Don't output quadrigraphs. + (m4_qdelta): Delete unused macro. + +2008-10-28 Paolo Bonzini + + Add m4_stack_foreach and m4_stack_foreach_lifo. + * lib/m4sugar/m4sugar.m4 (_m4_stack_reverse): New from _m4_copy. + (m4_stack_foreach, m4_stack_foreach_lifo): New. + (m4_copy): Use m4_stack_foreach and m4_curry. + (_m4_dumpdefs_down, _m4_dumpdefs_up): Remove. + (m4_dumpdefs): Rewrite using m4_stack_foreach_lifo. + * tests/m4sugar.at (m4_stack_foreach): New test. + +2008-10-28 Paolo Bonzini + + use a shell function for AC_TYPE_INTx_T + * lib/autoconf/types.m4 (_AC_TYPE_INT_BODY, _AC_TYPE_UNSIGNED_INT_BODY): + New. + (_AC_TYPE_INT, _AC_TYPE_UNSIGNED_INT): Define and use a shell function. + +2008-10-28 Paolo Bonzini + + * lib/autoconf/general.m4 (AC_CHECK_DECL): Fix AS_ESCAPE usage. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL, + _AC_CHECK_HEADER_NEW): Likewise. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW, AC_CHECK_MEMBER): Likewise. + +2008-10-28 Paolo Bonzini + + * lib/autoconf/types.m4 (_AC_CHECK_MEMBER_BODY): New. + (AC_CHECK_MEMBER): Define and use a shell function. + +2008-10-27 Eric Blake + + Prefer m4_fatal over AC_FATAL. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF, AC_CHECK_ALIGNOF) + (AC_CHECK_MEMBER): Use non-obsolete macro name. + * lib/autoconf/fortran.m4 (_AC_LIST_MEMBER_IF): Likewise. + * lib/autoconf/general.m4 (AC_REQUIRE_AUX_FILE, AC_SUBST): + Likewise. + * lib/autoconf/lang.m4 (_AC_LANG_DISPATCH): Likewise. + * lib/autoconf/status.m4 (_AC_CONFIG_DEPENDENCY_DEFAULT) + (_AC_CONFIG_UNIQUE, _AC_CONFIG_REGISTER_DEST): Likewise. + +2008-10-27 Eric Blake + + Avoid raw carriage return in scripts. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Generate CR + via tr, rather than with literal byte. + * THANKS: Update. + Reported by Steven R. Loomis; patch suggested by Thomas Dickey. + +2008-10-27 Eric Blake + + Use AS_VAR_ARITH. + * lib/autotest/general.m4 (at_func_arith): Delete; replace all + clients with AS_VAR_ARITH instead. + * lib/autoconf/general.m4 (_AC_COMPUTE_INT_COMPILE): Use new + macro. + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Likewise. + * tests/torture.at (Torturing config.status): Likewise. + * tests/tools.at (autom4te --force): Likewise. + + Add AS_VAR_ARITH. + * lib/m4sugar/m4sh.m4 (_AS_VAR_ARITH_PREPARE, _AS_VAR_ARITH_WORKS) + (AS_VAR_ARITH): New macros. + (_AS_PREPARE, AS_PREPARE): Emit preparation. + * tests/m4sh.at (AS@&t@_VAR_ARITH): New test. + * doc/autoconf.texi (Polymorphic Variables) : + Document new macro. + (Limitations of Usual Tools) : Mention portability problem + if first argument starts with -. + (Shell Substitutions) <$((expression))>: Mention it. + * NEWS: Likewise. + +2008-10-27 Eric Blake + + Use read, rather than `cat`, for safe one-line files. + * lib/autotest/general.m4 (AT_CLEANUP): Avoid a fork, since it is + known that the file has only one line and no \. + * lib/autoconf/general.m4 (_AC_COMPUTE_INT_RUN): Likewise. + +2008-10-27 Paolo Bonzini + + * lib/autoconf/general.m4 (_AC_COMPUTE_INT_COMPILE, + _AC_COMPUTE_INT_RUN): Add IF-SUCCESS argument. + (_AC_COMPUTE_INT_BODY): New. + (AC_COMPUTE_INT): Define and use a shell function. + +2008-10-27 Paolo Bonzini + + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW_BODY): Extract + test body here. Move head comment of _AC_CHECK_TYPE_NEW here. + (_AC_CHECK_TYPE_NEW): Define a shell function and call it. + +2008-10-27 Paolo Bonzini + + * lib/autoconf/general.m4 (_AC_CHECK_DECL_BODY): New. + (AC_CHECK_DECL): Use a shell function. + +2008-10-27 Paolo Bonzini + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_OLD, + _AC_CHECK_HEADER_NEW): Use a shell function. + +2008-10-25 Eric Blake + + Track recent copyright assignments. + * AUTHORS: Update. + +2008-10-25 Paolo Bonzini + and Eric Blake + + Use a shell function for _AC_CHECK_HEADER_MONGREL. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL_BODY): New + macro. + (_AC_CHECK_HEADER_MONGREL): Use a shell function. + +2008-10-25 Eric Blake + + Simplify _AS_PREPARE handling of functions. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE_SHELL_FN): Factor... + (_AS_REQUIRE_SHELL_FN): ...into new helper macro. + (_AS_PREPARE): Temporarily redefine AS_REQUIRE_SHELL_FN to make + this task easier. + (_AS_LINENO_PREPARE): Make more efficient. + (_AS_MKDIR_P_PREPARE): Simplify use in _AS_PREPARE. + (_AS_UNSET_PREPARE): Avoid blank newline. + (AS_INIT): Emit as_func_unset alongside other functions. + +2008-10-25 Eric Blake + + Document AS_EXIT. + * doc/autoconf.texi (Common Shell Constructs) : Document + this macro. + (Limitations of Builtins): Mention AS_EXIT. + * NEWS: Mention it. + + Use AS_EXIT in autoconf.as. + * bin/autoconf.as: Consistently use AS_EXIT. + +2008-10-24 Eric Blake + + Fix m4 underquoting in AC_PROG_INSTALL. + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Produce accurate + character ranges. + + Speed up AC_CHECK_HEADER. + * lib/autoconf/headers.m4 (AC_CHECK_HEADER): Factor out $@. + +2008-10-24 Paolo Bonzini + and Eric Blake + + Use a shell function for AC_CHECK_FUNC. + * lib/autoconf/functions.m4 (_AC_CHECK_FUNC_BODY): New macro. + (AC_CHECK_FUNC): Use a shell function. + * lib/autoconf/c.m4 (AC_LANG_SOURCE(C)): Reduce number of forks. + +2008-10-24 Eric Blake + + Work around fact that gnulib-tool doesn't use m4_copy. + * lib/autoconf/general.m4 (AC_LIBOBJ, AC_LIBSOURCES): Defun, not + define, so that an initial location is present, to account for + fact that gnulib-tool pushes another AC_DEFUN'd macro on top. + + Make m4_defun_init more robust. + * lib/m4sugar/m4sugar.m4 (m4_defun_init): Handle indirect macro + names, and correct number of arguments. + (m4_copy): Also set up location of the copy. + (m4_defun): When copied, use current macro name, not original. + * tests/m4sugar.at (m4@&t@_require: one-shot initialization): + Update test. + + Optimize clients of AS_REQUIRE. + * lib/m4sugar/m4sugar.m4 (m4_defun): Add undocumented third + argument. + (m4_defun_init): New undocumented macro. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_LOG, AS_MESSAGE, AS_BASENAME) + (_AS_DIRNAME_EXPR, AS_DIRNAME, AS_ECHO, AS_ECHO_N, AS_TEST_X) + (AS_LN_S, AS_MKDIR_P, _AS_PATH_WALK, AS_VERSION_COMPARE) + (AS_TR_SH, AS_TR_CPP, AS_VAR_APPEND, AS_VAR_PUSHDEF): Use it to + simplify these macros once the one-shot initialization is + complete. + * tests/m4sugar.at (m4@&t@_require: one-shot initialization): New + test. + + Improve m4_copy. + * lib/m4sugar/m4sugar.m4 (m4_copy): Add second implementation for + public use. + (_m4_copy): New macro, which preserves pushdef stacks. + (_m4_defun_pro_outer): Bypass it, for speed. + (m4_init): Bypass new implementation, since it breaks on m4_defn. + * bin/autoupdate.in (handle_autoconf_macros): Likewise. + * lib/autoconf/general.m4 (AC_PREREQ): Undefine before redefining, + now that m4_copy checks this. + * doc/autoconf.texi (Redefined M4 Macros) : Document + this, as well as m4_rename. + * lib/autoconf/autoconf.m4 (m4_copy): Temporarily redefine when + renaming builtins, since it breaks on m4_ifdef. + * NEWS: Likewise. + * tests/m4sugar.at (m4@&t@_defn): Enhance test. + +2008-10-24 Eric Blake + + AC_FUNC_GETGROUPS: Revert regression. + * lib/autoconf/functions.m4 (AC_FUNC_GETGROUPS): Only set + ac_cv_func_getgroups_works=no when it is not available. + +2008-10-23 Eric Blake + + Whitespace cleanup. + * lib/autoconf/fortran.m4: Consistently use tabs. + +2008-10-23 Chikama Masaki (tiny change) + + For gfortran on sh, ignore -little. + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Add -little to + list of ignored arguments. + * THANKS: Update. + +2008-10-23 Paolo Bonzini + + Eliminate empty lines after AC_*_IFELSE. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, + _AC_LINK_IFELSE, _AC_RUN_IFELSE): Add a dnl at end. + +2008-10-23 Paolo Bonzini + + Avoid a fork in _AC_RUN_LOG and _AC_RUN_LOG_STDERR + * lib/autoconf/general.m4 (_AC_RUN_LOG, _AC_RUN_LOG_STDERR): + Return a boolean status code based on $ac_status. + +2008-10-23 Paolo Bonzini + + Ensure actions can look at conftest* files. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE_BODY, + _AC_COMPILE_IFELSE_BODY, _AC_LINK_IFELSE_BODY, _AC_RUN_IFELSE_BODY): + Move rm commands, except IPA files and Apple debug symbols... + (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, _AC_LINK_IFELSE, + _AC_RUN_IFELSE): ...in here. + * tests/compile.at: Add regression test. + +2008-10-23 Eric Blake + + Remove excess dnl from m4sh. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL, _AS_PREPARE) + (_AS_SHELL_FN_WORK, _AS_SHELL_SANITIZE, AS_IF, _AS_ECHO_LOG) + (AS_MESSAGE, AS_ERROR, AS_BASENAME, _AS_BASENAME_PREPARE) + (_AS_DIRNAME_EXPR, AS_DIRNAME, _AS_DIRNAME_PREPARE, AS_ECHO) + (AS_ECHO_N, AS_TEST_X, AS_EXECUTABLE_P, _AS_ME_PREPARE) + (_AS_LINENO_PREPARE, AS_LN_S, AS_MKDIR_P, _AS_PATH_WALK) + (AS_SET_CATFILE, AS_HELP_STRING, AS_TMPDIR, AS_VERSION_COMPARE) + (_AS_TR_SH_PREPARE, AS_TR_SH, _AS_TR_CPP_PREPARE, AS_TR_CPP) + (_AS_TR_PREPARE, AS_VAR_APPEND, AS_VAR_PUSHDEF) + (AS_INIT_GENERATED): Use fewer dnl in m4sh macro bodies. + +2008-10-23 Paolo Bonzini + and Eric Blake + + Use a shell function for _AC_RUN_IFELSE. + * lib/autoconf/general.m4 (_AC_RUN_IFELSE_BODY): New macro. + (_AC_RUN_IFELSE): Use a shell function. + (_AC_RUN_LOG): Avoid subshell for logging. + +2008-10-23 Eric Blake + + Formatting tweak: balance () with m4sh case statements. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL) + (_AS_SHELL_SANITIZE, _AS_ECHO_N_PREPARE, _AS_ECHO_PREPARE) + (AS_SET_CATFILE, _AS_TEST_PREPARE): Add strategic shell comments. + (_AS_CASE, _AS_CASE_DEFAULT, AS_CASE): Rearrange newlines, to + allow output of strategic shell comments. + (AS_VERSION_COMPARE): Use AS_CASE. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Enhance test. + +2008-10-22 Jim Meyering + + AC_FUNC_GETGROUPS: always define $ac_cv_func_getgroups_works + * lib/autoconf/functions.m4 (AC_FUNC_GETGROUPS): Always define + the shell variable, $ac_cv_func_getgroups_works. Otherwise, if + it is set to "yes" in the environment and configure is run on + a system like mingw that lacks the getgroups function, it would + mistakenly define HAVE_GETGROUPS. Reported by Simon Josefsson in + . + +2008-10-22 Paolo Bonzini + and Eric Blake + + Use a shell function for _AC_LINK_IFELSE. + * lib/autoconf/general.m4 (_AC_LINK_IFELSE_BODY): New macro. + (_AC_LINK_IFELSE): Use a shell function. + +2008-10-22 Eric Blake + + Fix autoconf logging commands. + * lib/autoconf/general.m4 (AC_MSG_RESULT_UNQUOTED, _AC_EVAL) + (_AC_EVAL_STDERR, AC_RUN_LOG): Respect as_lineno. + (_AC_DO_ECHO): Likewise, and use fewer dnl. + (_AC_RUN_LOG_STDERR): Avoid subshell for logging. + +2008-10-22 Eric Blake + + Fix testsuite failure. + * tests/mktests.sh (ac_exclude_list): Don't generate test for + AC_REQUIRE_SHELL_FN. + +2008-10-21 Eric Blake + + Improve wording related to automake and autotest. + * doc/autoconf.texi (Making testsuite Scripts): Clarify wording in + relation to automake. Mention dependency on package.m4. + Consolidate examples. Define AUTOM4TE. + * THANKS: Update. + Reported by William Pursell. + +2008-10-21 Eric Blake + + Allow AS_VAR_SET_IF in shell lists. + * lib/m4sugar/m4sh.m4 (AS_VAR_SET_IF): Allow continuation of + line. + * lib/autoconf/general.m4 (AC_CACHE_VAL): Supply newline no longer + provided by AS_VAR_SET_IF. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Adjust + clients. + * lib/autoconf/libs.m4 (AC_SEARCH_LIBS): Likewise. + * tests/m4sh.at (AS@&t@_VAR basics): Enhance test. + + Allow AS_VAR_IF in shell lists. + * lib/m4sugar/m4sh.m4 (AS_VAR_IF): Allow continuation of line. + * lib/autoconf/functions.m4 (AC_CHECK_FUNC): Adjust clients. + * lib/autoconf/general.m4 (AC_CHECK_FILE, AC_CHECK_DECL): + Likewise. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL) + (_AC_CHECK_HEADER_NEW, _AC_CHECK_HEADER_OLD) + (_AC_CHECK_HEADER_DIRENT): Likewise. + * lib/autoconf/libs.m4 (AC_CHECK_LIB): Likewise. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW, AC_CHECK_MEMBER): + Likewise. + * tests/m4sh.at (AS@&t@_VAR basics): Enhance test. + + Allow AS_CASE in shell lists. + * lib/m4sugar/m4sh.m4 (AS_CASE): Always execute test, in case of + side effects. Allow continuation of script on same line as esac. + * lib/autoconf/c.m4 (AC_PROG_CC_STDC): Adjust client. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Enhance test. + * NEWS: Document the subtle change. + + Allow AS_IF in shell lists. + * lib/m4sugar/m4sh.m4 (AS_IF): Always execute test, in case of + side effects. Allow continuation of script on same line as fi. + (_AS_DETECT_BETTER_SHELL): Adjust clients. + (AS_VAR_IF, AS_VAR_SET_IF): For now, supply newline no longer + given by AS_IF. + * lib/autoconf/c.m4 (_AC_PROG_PREPROC_WORKS_IFELSE): Likewise. + * lib/autoconf/general.m4 (_AC_ENABLE_IF): Likewise. + (AC_EGREP_CPP, _AC_RUN_IFELSE): Adjust client. + * lib/autoconf/libs.m4 (AC_SEARCH_LIBS): Likewise. + * doc/autoconf.texi (Common Shell Constructs) : Fix typo. + (Polymorphic Variables): Move mention of dnl to the only two + AS_VAR functions that need it. + +2008-10-21 Paolo Bonzini + and Eric Blake + + Use a shell function for _AC_COMPILE_IFELSE. + * lib/autoconf/general.m4 (_AC_COMPILE_IFELSE_BODY): New macro. + (_AC_COMPILE_IFELSE): Use a shell function. + +2008-10-21 Eric Blake + + Use AS_VAR_APPEND. + * lib/autoconf/functions.m4 (AC_CHECK_FUNCS_ONCE): Use new macro. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE) + (_AC_LIBOBJS_NORMALIZE): Likewise. + * lib/autoconf/headers.m4 (AC_CHECK_HEADERS_ONCE): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS) + (_AC_OUTPUT_CONFIG_STATUS, _AC_OUTPUT_MAIN_LOOP): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + + Add AS_VAR_APPEND. + * lib/m4sugar/m4sh.m4 (_AS_VAR_APPEND_PREPARE) + (_AS_VAR_APPEND_WORKS, AS_VAR_APPEND): New macros. + (AS_PREPARE, _AS_PREPARE): Emit preparation. + * tests/m4sh.at (AS@&t@_VAR_APPEND): New test. + * doc/autoconf.texi (Polymorphic Variables) : + Document new macro. + : Mention ramification of `""` rules. + * NEWS: Mention new macro. + +2008-10-21 Paolo Bonzini + and Eric Blake + + Use a shell function for _AC_PREPROC_IFELSE. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE_BODY): New macro. + (_AC_PREPROC_IFELSE): Use a shell function. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Factor for faster execution. + (AS_REQUIRE_SHELL_FN): Bypass AS_REQUIRE if function has already + been provided. + +2008-10-21 Eric Blake + + Add banners to generated files. + * lib/m4sugar/m4sh.m4 (_AS_SHELL_SANITIZE): Use m4_text_box for + existing banner. + (AS_INIT): Add new banners at strategic points. + * lib/autoconf/general.m4 (AC_INIT): Alter banner location, and + make consistent with other banners. + * lib/autotest/general.m4 (AT_INIT): Make banners consistent. + +2008-10-20 Paolo Bonzini + + Add AC_REQUIRE_SHELL_FN and the SHELL_FN diversion. + * lib/autoconf/general.m4 (AC_REQUIRE_SHELL_FN): New. + (m4_divert(SHELL_FN)): New. + +2008-10-20 Eric Blake + + Avoid unportable use of echo in testsuite. + * tests/m4sh.at (AS@&t@_VAR basics): Use AS_ECHO, since string + contains backslash. + +2008-10-18 Paolo Bonzini + + Make sure that nested AS_REQUIRE do not lose the desired diversion. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Expand _m4_divert_desired before + passing it to m4_divert_require, so that its content is not used + anymore. + * tests/m4sh.at (Nested AS_REQUIRE): New testcase. + +2008-10-18 Eric Blake + + Document bugs in { } handling. + * doc/autoconf.texi (Limitations of Builtins): Mention bug on + empty list. + + Fix some testsuite failures introduced two days ago. + * tests/m4sh.at (Nested AS@&t@_REQUIRE_SHELL_FN) + (AS@&t@_REQUIRE_SHELL_FN and m4@&t@_require): Adjust to changed + API. + Reported by Ralf Wildenhues. + +2008-10-18 Ralf Wildenhues + + Show how to extract single substitutions from config.status. + * doc/autoconf.texi (config.status Invocation): Show example + using `--file=-'. + +2008-10-17 Eric Blake + + Add m4_curry. + * lib/m4sugar/m4sugar.m4 (m4_curry, _m4_curry): New macros. + * tests/m4sugar.at (m4@&t@_map_args): Rename... + (m4@&t@_map_args and m4@&t@_curry): ...and add currying tests. + * doc/autoconf.texi (Looping constructs) : Document + currying as a way to add parameters. + (Evaluation Macros) : Document the new macro. + * NEWS: Likewise. + + Improve suggested test filtering. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_SUGGESTED_PRUNE): New macro, + extracted from... + (_AS_DETECT_BETTER_SHELL): ...here, to use faster API. No need to + check for an empty required set. + + Add m4_set_map. + * lib/m4sugar/m4sugar.m4 (m4_set_foreach): New macro. + * tests/m4sugar.at (m4@&t@_set): Enhance test. + * doc/autoconf.texi (Set manipulation Macros) : + Document it. + * NEWS: Likewise. + + Document m4_map_args. + * lib/m4sugar/m4sugar.m4 (m4_transform, m4_transform_pair): + Rename... + (m4_map_args, m4_map_args_pair): ...to these names, and document. + (m4_version_unletter): Use the interface. + * lib/m4sugar/foreach.m4 (m4_map_args, m4_map_args_pair) + (_m4_map_args_, _m4_map_args_pair_, _m4_map_args_pair_end): + Perform same renames. + * lib/m4sugar/m4sh.m4 (AS_CASE, AS_IF): Adjust callers. + * tests/m4sugar.at (m4@&t@_map_args): New test. + (recursion): Adjust caller. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Likewise. + * doc/autoconf.texi (Looping constructs) : Document + this interface. + * NEWS: Mention the new macros. + +2008-10-17 Eric Blake + + Reduce vertical whitespace in configure. + * lib/autoconf/general.m4 (AC_INIT): Silence newline output during + m4 side effect initializations. + * lib/m4sugar/m4sh.m4 (AS_PREPARE): Likewise. + +2008-10-17 Eric Blake + + Document AS_VAR interfaces. + * doc/autoconf.texi (Programming in M4sh): M4sh is now prime-time. + (Polymorphic Variables): New node. + * NEWS: Update accordingly. + + Test AS_VAR interfaces. + * tests/m4sh.at (AS@&t@_VAR): New test. + * lib/m4sugar/m4sh.m4 (AS_VAR_PUSHDEF): Force expansion of + _AS_TR_SH_PREPARE at top level, rather than argument collection. + (AS_TR_SH): Support command substitution. + + Add AS_VAR_COPY. + * lib/m4sugar/m4sh.m4 (AS_VAR_COPY): New macro. + (AS_VAR_IF): Use it, instead of the broken AS_VAR_GET. + * lib/autoconf/general.m4 (AC_CACHE_CHECK): Likewise. + * lib/autoconf/libs.m4 (AC_SEARCH_LIBS): Likewise. + * lib/autotest/general.m4 (_AT_FINISH): Likewise. + + Sort AS_VAR_* interfaces. + * lib/m4sugar/m4sh.m4 (AS_VAR_GET): Reduce output to one line. + (AS_VAR_TEST_SET, AS_VAR_SET, AS_VAR_SET_IF, AS_VAR_POPDEF): Sort, + no code changes. + +2008-10-16 Eric Blake + + Allow comments before functions emitted by m4sh. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE_SHELL_FN): Add comment + argument. Supply closing comment, to ease readability. + (_AS_MKDIR_P_PREPARE): Adjust caller. + (_AS_UNSET_PREPARE): Add comment. + + Add AS_FUNCTION_DESCRIBE. + * lib/m4sugar/m4sh.m4 (AS_FUNCTION_DESCRIBE): New macro. + * lib/autotest/general.m4 (AT_INIT): Use it. + +2008-10-16 Eric Blake + + Speed up m4_qlen with caching. + * lib/m4sugar/m4sugar.m4 (_m4_qlen): Renamed from old m4_qlen. + (m4_qlen): Cache results for speed. + +2008-10-16 Paolo Bonzini + + Add a testcase using more then one language. + * tests/compile.at (Multiple languages): New test. + +2008-10-16 Paolo Bonzini + + Fix Libtool's config.lt test. + * lib/m4sugar/m4sh.m4 (_AS_PREPARE): Disable AS_REQUIRE while + expanding it. + +2008-10-15 Eric Blake + + Break circular require chain in _AS_LINENO_PREPARE. + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Ensure that logging is + disabled when reporting LINENO failure, since logging requires + LINENO. + * doc/autoconf.texi (Initialization Macros): Recommend m4_pushdef, + not m4_rename, since the latter is undocumented. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Avoid + m4_rename, as it does not yet handle pushdef stacks. + Reported by Ralf Wildenhues. + +2008-10-15 Eric Blake + + Cleanups to previous patches. + * doc/autoconf.texi (Portable Shell): Minor edits. + (Limitations of Builtins): Touch up wording. + * lib/m4sugar/m4sh.m4 (AS_LINENO_PUSH): Nuke trailing whitespace. + (_AS_SHELL_SANITIZE): Wrap comments less than 80 columns. + +2008-10-15 Paolo Bonzini + + Updates to shell portability documentation. + * doc/autoconf.texi: Updates all references to "Portable Shell" and + "Limitations of Builtins" to use three-argument commands. + (Programming in M4sh): Document AS_ECHO, AS_ECHO_N, AS_UNSET. + (Portable Shell): Move here discussion about "Where is the POSIX + shell?" Mention that M4sh provides a SVR2 shell and takes care + of unsetting variables if necessary. Talk about M4sh and not only + Autoconf-generated scripts. + (Special Shell Variables): Talk about M4sh and not only + Autoconf-generated scripts. Don't talk about things that Autoconf + does not do. Mention problems of $LINENO with shell functions. + (Limitations of Builtins). Mention AS_ECHO and AS_ECHO_N. Move + discussion of eval bugs before discussion on proper use of eval. + Mention AS_IF. Reword why not to use "shift N". Mention "foo=; + unset foo" trick. Include M4sh code that unsets MAIL for Bash 2.01. + * NEWS: Update list of documented M4sh macros. + +2008-10-15 Paolo Bonzini + + Assume a (possibly buggy) `unset' is present after a + `better shell' was found. + * lib/autoconf/general.m4 (_AC_CACHE_DUMP): Use AS_UNSET. + * lib/autoconf/programs.m4 (AC_PROG_SED): Use AS_UNSET. + * lib/m4sugar/m4sh.m4 (_AS_UNSET_PREPARE): Provide $as_unset as an + alias for AS_UNSET, for backwards compatibility. + (_AS_DETECT_BETTER_SHELL): Set BASH_ENV and ENV to /dev/null in case + the shell does not support unset. + (_AS_SHELL_SANITIZE): Work around Bash 2.01 bugs. Unset BASH_ENV. + (AS_INIT, _AS_PREPARE, AS_PREPARE): Call it. + (AS_UNSET): Assume it is there but it might fail if the variable is + not set. Use it throughout instead of $as_unset. + +2008-10-15 Paolo Bonzini + + Turn AS_SHELL_SANITIZE into a for-Libtool-only wrapper. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_REQUIRED, _AS_DETECT_SUGGESTED): Remove + m4_require of _AS_DETECT_BETTER_SHELL. + (_AS_CLEANUP): Add it here. + (_AS_DETECT_BETTER_SHELL): Just expand the test instead of appending it + to _AS_CLEANUP. + (_AS_SHELL_SANITIZE): New name of the old AS_SHELL_SANITIZE macro. + (AS_SHELL_SANITIZE): New macro hacking around Libtool misuse. + (AS_PREPARE): Use _AS_SHELL_SANITIZE. + (AS_INIT): Add m4_provide of itself. + +2008-10-15 Paolo Bonzini + + Use "test x$foo = xyes" to avoid upsetting Libtool's sh.test. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL, _AS_SHELL_FN_WORK): Use + "test x$foo = xyes". + +2008-10-15 Paolo Bonzini + + Trim down the size of the better-shell test. + * lib/m4sugar/m4sh.at (_AT_DETECT_BETTER_SHELL): Store the common + snippets into shell variables. + (_AS_RUN): Rewrite. + +2008-10-15 Paolo Bonzini + + Support a stack of LINENO values for AS_MESSAGE. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_LOG): If defined, use $as_lineno as + the line number emitted to the log file. + (AS_LINENO_PUSH, AS_LINENO_POP): New. + * tests/m4sh.at (LINENO Stack): New test. + +2008-10-14 Eric Blake + + Correct previous patch. + * doc/autoconf.texi (Shell Functions): Bash obeys Posix, after + all. + + Document shell function environment pitfall. + * doc/autoconf.texi (Shell Functions): Document bugs in bash, + Solaris /bin/sh. + +2008-10-14 Paolo Bonzini + + Use m4_require to implement AS_REQUIRE. + * lib/m4sugar/m4sugar.m4 (_m4_require_call): Accept a third argument. + (m4_require): Pass it. + (m4_divert_require): New. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Rewrite using m4_divert_require. + Remove comment about differences with m4_require. + * tests/m4sh.at (AS_REQUIRE_SHELL_FN and m4_require): Update to test + the expected behavior. + (Nested AS_REQUIRE_SHELL_FN): New test. + +2008-10-13 Paolo Bonzini + + Test AS_LINENO_PREPARE. + * tests/m4sh.at: Use documented AS_LINENO_PREPARE. + +2008-10-13 Paolo Bonzini + + Test AS_ME_PREPARE. + * tests/m4sh.at (as_me): New test. + +2008-10-13 Paolo Bonzini + + Add and document AS_INIT_GENERATED. + * lib/m4sugar/m4sh.m4 (AS_INIT_GENERATED): New. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use it. + * doc/autoconf.texi (Initialization macros): Document it. + +2008-10-13 Eric Blake + + Use consistent shell function style. + * lib/m4sugar/m4sh.m4 (_AS_PREPARE, AS_REQUIRE_SHELL_FN) + (_AS_SHELL_FN_WORK): Imitate GNU Coding Standards for C + functions. + +2008-10-13 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Place names of + contributors under m4 rather than shell comments. + +2008-10-10 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (AS_ME_PREPARE, AS_LINENO_PREPARE): New. + * doc/autoconf.texi (Initialization macros): Document them. + (Portable Shell): Refer to AS_LINENO_PREPARE. + * NEWS: Mention them. + + * bin/autoconf.as: Invoke AS_ME_PREPARE. + * lib/autotest/general.m4: Likewise. + +2008-10-10 Paolo Bonzini + + * doc/autoconf.texi (Programming in M4sh): Make its own chapter. + +2008-10-10 Eric Blake + + Fix _AS_MKDIR_P usage. + * lib/m4sugar/m4sh.m4 (_AS_MKDIR_P): Correct documentation to + match implementation. + (_AS_PREPARE, _AS_MKDIR_P_PREPARE): Adjust callers. + * doc/autoconf.texi (Programming in M4sh) : Tweak + wording to better match behavior. + +2008-10-10 Paolo Bonzini + + * doc/autoconf.texi: Be less wary of shell functions. + * NEWS: Document the increased use of shell functions. + +2008-10-10 Paolo Bonzini + + * m4sugar/m4sh.m4 (_AS_MKDIR_P): New, from AS_MKDIR_P. Adjust + meaning of as_mkdir_p to be `false' or a full `mkdir -p' command. + (AS_MKDIR_P): Just dispatch to as_func_mkdir_p. + (_AS_PREPARE): Define shell functions. + (_AS_MKDIR_P_PREPARE): Set as_mkdir_p according to the above change. + Define shell functions. + +2008-10-09 Eric Blake + + Only prepare $as_me if it will be used. + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Avoid unconditional + preparation. + (_AS_ECHO_LOG): Depend on $LINENO preparation. + (AS_MESSAGE): Depend on $as_me preparation. + (AS_TMPDIR): Use AS_ERROR, rather than a hand-rolled copy. + +2008-10-09 Paolo Bonzini + + * m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Delay setting as_me + until the M4SH-INIT diversion using _AS_ME_PREPARE. + (_AS_PREPARE): Invoke _AS_EXPR_PREPARE before _AS_BASENAME_PREPARE + and _AS_DIRNAME_PREPARE, and _AS_BASENAME_PREPARE and _AS_ME_PREPARE + before _AS_LINENO_PREPARE. + (AS_PREPARE): Include all the AS_REQUIREs manually. + (_AS_ME_PREPARE): New. + (_AS_LINENO_PREPARE): Use m4_defun. + +2008-10-09 Paolo Bonzini + + * m4sugar/m4sh.m4 (_AS_BASENAME_EXPR, _AS_DIRNAME_EXPR): Do not + require _AS_EXPR_PREPARE. + (_AS_BASENAME_PREPARE, _AS_DIRNAME_PREPARE): Do it here. + (_AS_PREPARE): Add _AS_BASENAME_PREPARE. + +2008-10-08 Eric Blake + + Resync from gnulib. + * cfg.mk (cvs_executable_files, cvs_files): Rewrite... + (fetch): ...into new target. + (executable-update): Delete, now that it is unused. + * maint.mk (update, local_updates, cvs_files, gnulib_repo) + (wget-update, cvs-update): Likewise. + * HACKING (Update the foreign files): Document new procedure. + * GNUmakefile: Resync from upstream, via new 'make fetch'. + * build-aux/config.guess: Likewise. + +2008-10-08 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_SPY): Remove. + (AS_INIT): Do not call it. + +2008-10-08 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Expand + _AS_UNSET_PREPARE in M4SH-SANITIZE. + +2008-10-08 Eric Blake + + Avoid repeating required shell tests in suggested set. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_REQUIRED, _AS_DETECT_SUGGESTED): + Use m4_set, rather than m4_expand_once/m4_append. + (_AS_DETECT_SUGGESTED): Adjust to new storage layout, and filter + required tests out of suggested tests. + Reported by Paolo Bonzini. + +2008-10-08 Paolo Bonzini + + Add m4sh keyword to all m4sh.at tests. + * tests/m4sh.at: Add m4sh keyword to all tests. Fix comment + pastos. + +2008-10-08 Ralf Wildenhues + + Document AS_VERSION_COMPARE. + * doc/autoconf.texi (Programming in M4sh): Document + AS_VERSION_COMPARE. + * NEWS: Update. + + Do not write to testsuite log fd before initialization. + * lib/autotest/general.m4 (AS_MESSAGE_LOG_FD, AT_JOB_FIFO_FD): + Define fds only when initializing the log fd so early error + messages do not try to write to it. + * tests/autotest.at (Startup error messages): New test. + * NEWS: Document this 2.63 regression. + +2008-10-07 Eric Blake + + Ensure _AS_CLEANUP is defined. + * lib/m4sugar/m4sh.m4 (_AS_CLEANUP): Give initial definition. + * tests/m4sh.at (AS@&t@_INIT cleanup): Expose the need for this. + + Improve m4sh maintainability. + * lib/m4sugar/m4sh.m4: Sort macros for sanitizing the shell; no + code change. + + Fix m4 quoting in previous patch. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE_SHELL_FN): Determine diversion + name prior to invoking AS_REQUIRE. + Reported by Ralf Wildenhues. + +2008-09-18 Paolo Bonzini + and Eric Blake + + Add a separate diversion for shell functions. + * lib/m4sugar/m4sh.m4 (M4SH-INIT-FN): New diversion. + (AS_REQUIRE): Accept diversion parameter. + (AS_REQUIRE_SHELL_FN): Use it. + +2008-10-06 Eric Blake + + Add m4_default_quoted. + * lib/m4sugar/m4sugar.m4 (m4_default_quoted): New macro. + (m4_for, m4_expand_once, m4_text_wrap, m4_text_box): Use it. + * doc/autoconf.texi (Conditional constructs): Document it. + * NEWS: Likewise. + + Fix build with case-insensitive make, again. + * Makefile.am (pkgdata_DATA): Protect by MAKE_CASE_SENSITIVE. + Reported via Keith Marshall, originally by newthinker in + . + +2008-10-06 Bruno Haible + + Warn about /usr/ucb on Solaris. + * doc/install.texi (Particular Systems): Recommend putting + /usr/ucb late in PATH, if at all. + +2008-10-03 Ralf Wildenhues + + Fix more testsuite hang corner cases. + * lib/autotest/general.m4: Use the serial code path if no test + is to be run. + * tests/autotest.at (parallel test execution): Test -j and -jN + with `-k notmatched'. + +2008-10-02 Ralf Wildenhues + + Fix hang with `testsuite -k notmatched'. + * lib/autotest/general.m4: Do not reset $at_jobs if it is equal + to one. Fixes hang with `-k notmatched'. + +2008-10-02 Eric Blake + + Document more binary file portability traps. + * doc/autoconf.texi (Limitations of Usual Tools) : Remind + reader that NUL and sed don't always mix. + : Mention Solaris /usr/ucb/tr bug with \0. + +2008-10-02 Ralf Wildenhues + + Implement parallel Autotest test execution: testsuite --jobs. + * lib/autotest/general.m4 (AT_JOB_FIFO_FD): New macro. + (AT_INIT): : New variable. + Accept -j, -jN, --jobs[=N], document them in --help output. + Implement parallel driver loop using a FIFO, enabled with --jobs + and if mkfifo works; otherwise, fall back to sequential loop. + (AT_SETUP): Store, do not output summary progress line if + parallel. + * tests/autotest.at (parallel test execution, parallel truth) + (parallel fallacy, parallel skip): New tests. + * doc/autoconf.texi (testsuite Invocation): Document -j, --jobs, + the mkfifo requirement, and that --errexit may cause concurrent + jobs to finish. + * NEWS: Update. + +2008-09-20 Eric Blake + + Fix sample isinf definition. + * doc/autoconf.texi (Function Portability) : Filter out NaN + first. + * THANKS: Update. + Reported by David Cournapeau. + +2008-09-16 Eric Blake + + Fix Erlang regression, introduced 2006-11-17. + * lib/autoconf/erlang.m4 (AC_LANG(Erlang)): Avoid M4 comment + caused by underquoting. + * NEWS: Mention this fix. + * THANKS: Update. + Reported by BJ Terry. + +2008-09-13 Ralf Wildenhues + + * lib/autoconf/general.m4 (AC_CONFIG_AUX_DIRS): Improve a bit. + + Mention Solaris sh ':' redirection bug. + * doc/autoconf.texi (File Descriptors): Redirecting ':' + in a loop causes bogus optimization with Solaris sh. + +2008-09-10 Eric Blake + + Avoid testsuite bug when autom4te cache is disabled by user. + * tests/tools.at (autoconf: forbidden tokens, basic): Enable + cache, even if user normally disabled it. + Reported by Bruno Haible. + + Avoid testsuite bug in presence of verbose config.site. + * tests/base.at (Input/Output): Nullify config.site during test. + Reported by Bob Friesenhahn. + +2008-09-09 Eric Blake + + Release Version 2.63. + * NEWS: Mention the release. + + Formatting tweaks to the manual. + * doc/autoconf.texi (Introduction, Systemology) + (File System Conventions, Portable C and C++) + (Floating Point Portability): Allow URLs to split as needed. + (Indices): Add entries, to work around texinfo bug on indices that + start too close to a page break. + (Particular Functions): Mention ftello. + (Introduction, Language Choice): Use @enddots at sentence end. + + Resync from gnulib. + * cfg.mk (cvs_executable_files, cvs_files): Update list of files, + although for now, they are still manually sync'd. + * build-aux/gnupload: Update. + * build-aux/config.sub: Likewise. + * GNUmakefile: Likewise. + +2008-09-06 Eric Blake + + Mention that Automake already supports VPATH. + * doc/autoconf.texi (Build Directories): Details in this section + only apply to users avoiding automake. + * THANKS: Update. + Reported by Matej Tyc. + + Relax tone when warning about cross-compiler names. + * lib/autoconf/programs.m4 (_AC_TOOL_WARN): Support cross-compiles + with poorly named tools; the issue has been reported too many + times in the last four years to pull support. + * doc/autoconf.texi (Specifying Names, Generic Programs): Update + documentation accordingly. + * THANKS: Update. + Reported by Josef Tran and others, wording suggested by Ralf + Wildenhues. + +2008-09-01 Eric Blake + + Improve AC_C_BIGENDIAN. + * doc/autoconf.texi (C Compiler) : Mention that + universal builds require a config header. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Enhance comments. Check + AH_HEADER at the last possible moment, so that users can use + AC_CONFIG_HEADER after this macro. + Reported by Stepan Kasal. + + Fix manual date information. + * doc/autoconf.tex: UPDATED refers to the day the manual was + built, not the release date of Autoconf. + Based on a bison patch by Akim Demaille. + +2008-08-27 Eric Blake + + Fix off-by-one bug in _m4_shiftn. + * lib/m4sugar/foreach.m4 (_m4_shiftn): Handle case when shifting + all arguments. + * tests/m4sugar.at (M4 loops): Test it. + Reported by Akim Demaille. + +2008-08-26 Eric Blake + + Improve INSTALL formatting. + * doc/install.texi [!autoconf]: Ensure first paragraphs are + indented like all others in a plain text rendering. + * Makefile.am ($(srcdir)/INSTALL): Ensure plaintext formatting. + Reported by Bruno Haible. + +2008-08-26 Stepan Kasal + + Check for case sensitive make. + * m4/make-check.m4 (AC_PROG_MAKE_CASE_SENSITIVE): New macro,... + * configure.ac: ... called here. + * Makefile.am ($(abs_srcdir)/INSTALL, INSTALL): Return to... + ($(srcdir)/INSTALL): ...this, but enclose the rule in + "if MAKE_CASE_SENSITIVE". + +2008-08-26 Eric Blake + + Update invocation documentation. + * doc/autoconf.texi (autoscan Invocation): Mention --debug. + (autoreconf Invocation): Mention -v. + (autom4te Invocation): Tie --freeze to -F, not -f. + (autoupdate Invocation): Mention --prepend-include. + * doc/install.texi (configure Invocation): Mention --help=short, + --help=recursive, -n/--no-create, --prefix. Avoid TABs. + * bin/autoscan.in ($help): Omit space before `...'. + * bin/ifnames.in ($help): Likewise. + * bin/autoconf.as (Usage): Likewise. + * bin/autoreconf.in ($help): Likewise. + * bin/autoheader.in ($help): Likewise. + * bin/autom4te.in ($help): Likewise. + * bin/autoupdate.in ($help): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use + `[OPTION]...', rather than `[OPTIONS]'. Mention --silent. Indent + --file correctly. + + Don't let frozen __m4_version__ break downgrade to m4 1.4.x. + * bin/autom4te.in: Adjust comments, now that we rely on 1.4.5+. + (files_to_options): Avoid inheriting __m4_version__ from frozen + file if current M4 does not support it. + +2008-08-25 Eric Blake + + Adjust to recent m4 1.6 change to support m4_debugmode(d). + * lib/m4sugar/m4sugar.m4 (m4_defn, m4_popdef, m4_undefine): Move + freeze-time decision of using faster 1.6 implementation... + (m4_init): ...to a runtime decision, and add use of new debugmode + flag. + +2008-08-22 Peter O'Gorman + + Limit AC_C_BIGENDIAN univeral checks to Mac OS X. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Limit the check to + __APPLE_CC__ with possible -arch flags. + * NEWS: Document it. + +2008-08-22 Ralf Wildenhues + + * NEWS: Fix typo. + +2008-08-22 Eric Blake + + * TODO: Add an item for additional m4sugar looping constructs. + Suggested by Ralf Wildenhues. + + Add reminder to keep dual implementations in sync. + * lib/m4sugar/m4sugar.m4: Add comments. + * lib/m4sugar/foreach.m4: Likewise. + Suggested by Ralf Wildenhues. + +2008-08-22 Peter Eisentraut (tiny change) + + Format warning and error messages to match GCS. + * lib/autoconf/general.m4 (_AC_INIT_DIRCHECK) + (_AC_INIT_PARSE_ARGS, _AC_CACHE_DUMP): Start warning and error + messages with a lowercase letter, end them without punctuation. + * lib/autoconf/lang.m4 (AC_NO_EXECUTABLES): Likewise. + * lib/autoconf/libs.m4 (AC_PATH_X): Likewise. + * lib/autoconf/status.m4 (AC_OUTPUT, _AC_OUTPUT_MAIN_LOOP): + Likewise. + * tests/fortran.at (GNU Fortran): Likewise. + * tests/torture.at (Deep Package): Likewise. + +2008-08-21 Eric Blake + + Avoid extra side effects in m4sugar list expansion. + * lib/m4sugar/m4sugar.m4 (m4_mapall_sep, m4_list_cmp): Wrap + around... + (_m4_mapall_sep, _m4_list_cmp_raw): ...new helpers, to avoid + duplicate side effects. + (m4_version_compare): Adjust caller. + * lib/m4sugar/foreach.m4 (m4_list_cmp): Rename... + (_m4_list_cmp_raw): ...to match m4sugar. + * doc/autoconf.texi (Looping constructs): Document the behavior of + side effects. + * tests/m4sugar.at (M4 loops, m4@&t@_map, m4@&t@_version_compare): + Ensure only one side effect. + (recursion): Fix test typo. + Reported by Ralf Wildenhues. + +2008-08-21 Ralf Wildenhues + + * TODO: Add item for compiler default flags. + Suggested by Bruno Haible. + + * tests/m4sh.at (AS_IF and AS_CASE): Set the expansion limit + back to 1000. + +2008-08-21 Eric Blake + + Formatting improvements. + * doc/autoconf.texi: Use @file and @command, rather than @code, + where appropriate. + + Document another make bug. + * doc/autoconf.texi (The Make Macro SHELL): Mention bug in BSD + make, GNU make <= 3.80. + + Tweak wording about SHELL in Makefile. + * doc/autoconf.texi (The Make Macro SHELL): Stronger wording on + the importance of proper SHELL settings. + Reported by Bruno Haible, in + http://lists.gnu.org/archive/html/bug-libtool/2008-04/msg00029.html. + +2008-08-20 Ralf Wildenhues + + Avoid timestamp races for updated input. + * tests/m4sh.at (AS_IF and AS_CASE): Use `autom4te --force' for + second script. + * tests/tools.at (autotools and whitespace in file names): Add + --force for repeated invocations. + +2008-08-20 Bruno Haible + + Add section to INSTALL about particular systems. + * doc/install.texi (Particular systems): New node. + * doc/autoconf.texi: Adjust menus. + +2008-08-19 Bruno Haible + and Peter O'Gorman + + Mention universal binaries in INSTALL. + * doc/install.texi (Compiling For Multiple Architectures): Explain + how to create universal binaries on MacOS X. + +2008-08-19 Jim Meyering + Eric Blake + Ralf Wildenhues + + Avoid shell parse errors after interrupt due to empty ``. + * doc/autoconf.texi (Shell Substitutions): Document the issue. + * lib/m4sugar/m4sh.m4 (AS_VAR_IF): New function. + * lib/autoconf/functions.m4 (AC_CHECK_FUNC): Use it in place of + "test AS_VAR_GET([...]) = yes" + * lib/autoconf/general.m4 (AC_CHECK_FILE, AC_CHECK_DECL): Likewise. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Likewise. + (_AC_CHECK_HEADER_NEW, _AC_CHECK_HEADER_OLD): Likewise. + (_AC_CHECK_HEADER_DIRENT): Likewise. + * lib/autoconf/libs.m4 (AC_CHECK_LIB): Likewise. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW, AC_CHECK_MEMBER): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Use + temporary variable to work around the issue. + * tests/foreign.at (Libtool): Quote result of command + substitution. + +2008-08-18 Eric Blake + + Test m4_transform without tickling shell bugs. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Relax test to + something more manageable. + * tests/m4sugar.at (recursion): Move stress test of + m4_transform_pair here. + Reported by Ralf Wildenhues. + + Let 'git diff' give better context for doc updates. + * .gitattributes (*.texi*): Add new entry. + * README-hacking: Mention how to use it. + Inspired by a coreutils patch by Jim Meyering. + +2008-08-15 Eric Blake + + Fix m4_map regression from 2007-10-16. + * lib/m4sugar/m4sugar.m4 (_m4_apply): New macro. + (m4_map): Ignore empty sublists. For a list consisting of only an + empty sublist, this restores 2.61 behavior of being a no-op. + (m4_map_sep): Likewise, and expand separator. + (m4_mapall, m4_mapall_sep): New macros, to regain 2.62 behavior. + (_m4_map): Rewrite, to be common base for all four variants. + * lib/m4sugar/foreach.m4 (_m4_map): Adjust to new prototype. + * tests/m4sugar.at (m4@&t@_map): Add tests. + * doc/autoconf.texi (Looping constructs) : Document new + macros, and mention ramifications of expanded separator. + * NEWS: Mention the change. + +2008-08-14 Eric Blake + + Implement m4_transform_pair, to speed up AS_IF. + * lib/m4sugar/m4sugar.m4 (m4_transform, m4_transform_pair): New + macros, undocumented for now. + * lib/m4sugar/foreach.m4 (m4_transform, m4_transform_pair): Also + the m4 1.4.x counterparts. + * lib/m4sugar/m4sh.m4 (AS_IF, AS_CASE): Use it. + * tests/m4sh.at (AS@&t@_IF and AS@&t@_CASE): Test it. + +2008-08-14 Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_PATH_TARGET_TOOL) + (AC_CHECK_TARGET_TOOL, AC_CHECK_TARGET_TOOLS): Require, do not + warn about previous AC_CANONICAL_TARGET. + (AC_CHECK_TARGET_TOOL): Add missing `$' making the macro + unusable in the non-cross-compiling case. + * NEWS, THANKS: Update. + Report by Dave Erickson. + +2008-08-12 Eric Blake + + Optimize m4_bmatch. + * lib/m4sugar/foreach.m4 (m4_bmatch): Provide linear + implementation for m4 1.4.x. + * tests/m4sugar.at (m4@&t@_bmatch): New test. + (recursion): Test the linear nature. + * NEWS: Document the fix. + + Fix m4_cond corner case. + * lib/m4sugar/foreach.m4 (_m4_cond): Ensure alternate + implementation allows concatenation with subsequent text. + * tests/m4sugar.at (m4@&t@_cond): Enhance test. + + Add test for m4_cond. + * tests/m4sugar.at (m4@&t@_cond): New test. + Reported by Ralf Wildenhues. + +2008-08-06 Eric Blake + + Fix autoheader 2.62 regression on AC_DEFINE([__EXTENSIONS__]). + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Use a + unique key for the AH_VERBATIM. + * tests/c.at (AC_USE_SYSTEM_EXTENSIONS): New test. + * NEWS: Mention the fix. + Reported by Andreas Schwab, analyzed by Stepan Kasal. + + Add linear m4_cond for m4 1.4.x. + * lib/m4sugar/m4sugar.m4 (m4_cond): Split into... + (_m4_cond): ...this, for fewer macros per iteration. + * lib/m4sugar/foreach.m4 (_m4_cond): New implementation. + * tests/m4sugar.at (recursion): Test it. + * NEWS: Document the linear guarantee. + + Speed up diversion handling. + * lib/m4sugar/m4sugar.m4 (m4_divert, m4_divert_push) + (m4_divert_pop, m4_divert_text): Avoid dnl for fewer macro + expansions. + + AC_C_CHAR_UNSIGNED is not strictly necessary. + * doc/autoconf.texi (C Compiler) : Mention a + portable alternative to this macro. + * THANKS: Update. + Reported by Hallvard B Furuseth. + + Update some files from upstream. + * GNUmakefile: Update. + * build-aux/announce-gen: Likewise. + * build-aux/config.guess: Likewise. + * build-aux/config.sub: Likewise. + * build-aux/git-version-gen: Likewise. + * build-aux/texinfo.tex: Likewise. + * build-aux/vc-list-files: Likewise. + * doc/make-stds.texi: Likewise. + * doc/standards.texi: Likewise. + +2008-08-04 Ralf Wildenhues + + Fix AC_CONFIG_FILES([$var]) 2.62 regression. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Flatten + whitespace in $ac_config_files and $ac_config_headers. + * tests/torture.at (Parameterized AC_CONFIG_FILES): New test. + Report by Andreas Schwab and Per Øyvind Karlsen. + * THANKS: Update. + +2008-07-30 Eric Blake + + Fix bugs in previous version of m4_bpatsubsts. + * lib/m4sugar/foreach.m4 (_m4_bpatsubsts): Don't expand $1, and + allow concatenation with subsequent text. + * tests/m4sugar.at (m4@&t@_bpatsubsts): Enhance test. + +2008-07-29 Eric Blake + + Add linear m4_bpatsubsts for m4 1.4.x. + * lib/m4sugar/m4sugar.m4 (m4_bpatsubsts): Match documentation + about anchors, even for only one substitution. + * lib/m4sugar/foreach.m4 (_m4_bpatsubsts): New implementation. + * doc/autoconf.texi (Conditional constructs) : + Clarify behavior with regard to quoting. + * tests/m4sugar.at (recursion): Test scaling of m4_bpatsubsts. + (m4@&t@_bpatsubsts): New test. + * NEWS: Document the linear guarantee. + + Tweak m4_do semantics. + * lib/m4sugar/m4sugar.m4 (m4_do): Don't concat final argument with + subsequent text. + * lib/m4sugar/foreach.m4 (m4_do): Don't concat intermediate + arguments, and avoid infinite loop. + * doc/autoconf.texi (Evaluation Macros) : Document the + behavior. + * tests/m4sugar.at (m4@&t@_do): New test. + + Optimize m4_for. + * lib/m4sugar/m4sugar.m4 (m4_for): Use fewer macros. + (_m4_for): Take additional parameter, for fewer m4_indir calls. + * lib/m4sugar/foreach.m4 (_m4_foreach, _m4_shiftn, m4_do) + (m4_reverse, _m4_list_pad, _m4_list_cmp): Adjust all callers. + * doc/autoconf.texi (Looping constructs) : Document subtle + semantic change caused by the optimization. + * tests/m4sugar.at (M4 loops): Test the new semantics. + + One more m4_list_cmp tweak. + * lib/m4sugar/m4sugar.m4 (_m4_list_cmp_1): Don't defer shift. + * lib/m4sugar/foreach.m4 (m4_list_cmp): Fix comment. + * tests/m4sugar.at (recursion): Test both directions of list + disparity. + + Add m4_reverse, and improve m4_list_cmp. + * lib/m4sugar/m4sugar.m4 (m4_reverse): New macro. + (m4_list_cmp): Rewrite to give linear behavior with M4 1.6 on an + m4_reverse'd list. + * lib/m4sugar/foreach.m4 (m4_reverse): Add the M4 1.4.x + counterpart. + * tests/m4sugar.at (recursion): Test it. + * doc/autoconf.texi (Evaluation Macros) : Document + it. + (Text processing Macros) : Cross-reference to m4_set. + * NEWS: Mention new macro. + +2008-07-28 Eric Blake + + Avoid _m4_shiftn for m4 1.6 speedup. + * lib/m4sugar/m4sugar.m4 (m4_foreach, _m4_foreach, m4_map) + (_m4_map, m4_map_sep): Rewrite recursion to use one less m4_if. + * lib/m4sugar/foreach.m4 (_m4_map): Accomodate changed signature. + + Implement O(n) unique element set creation. + * lib/m4sugar/m4sugar.m4 (m4_set_add, m4_set_add_all) + (m4_set_contains, m4_set_contents, m4_set_delete) + (m4_set_difference, m4_set_dump, m4_set_empty, m4_set_foreach) + (m4_set_intersection, m4_set_list, m4_set_listc, m4_set_remove) + (m4_set_size, m4_set_union): New macros. + * lib/m4sugar/foreach.m4 (m4_set_add_all): Add O(n) fallback for + m4 1.4.x. + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS, AC_SUBST): Use + new m4_set API for the set most likely to be large. + * doc/autoconf.texi (Set manipulation Macros): New node. + * NEWS: Mention new macros. + * tests/m4sugar.at (m4@&t@_set): New test. + +2008-07-25 Eric Blake + + Avoid infinite aclocal loop. + * lib/m4sugar/m4sugar.m4 (m4_init): Bypass m4_include tracing, so + that aclocal doesn't insist on finding m4sugar/foreach.m4. + + Provide O(n) replacement macros for M4 1.4.x. + * lib/m4sugar/foreach.m4: New file. + (m4_foreach, m4_case, _m4_shiftn, m4_do, m4_dquote_elt, _m4_map) + (m4_join, m4_joinall, m4_list_cmp, _m4_minmax): Replace m4sugar + macros based on $@ recursion [fast on M4 1.6, but quadratic on M4 + 1.4.x] with versions based on m4_for/m4_foreach [slow on 1.6, but + linear on 1.4.x]. + * lib/m4sugar/m4sugar.m4 (m4_init): Dynamically load new file if + older M4 is assumed. + (m4_map_sep): Optimize. + (m4_max, m4_min): Refactor, by adding... + (_m4_max, _m4_min, _m4_minmax): ...more efficient helpers. + (m4_defn, m4_popdef, m4_undefine): Use foreach recursion. + * lib/m4sugar/Makefile.am (dist_m4sugarlib_DATA): Distribute new + file. + * tests/m4sugar.at (M4 loops): Add a stress test that takes + forever if m4_foreach and friends are quadratic. + * NEWS: Mention this. + +2008-07-21 Eric Blake + + Ignore undefined macros, necessary with m4 1.6. + * bin/autoupdate.in (_au___undefine): New macro,... + (_au__undefine): ...wrapped by ifdef to silence m4 warnings. + Reported by Ralf Wildenhues. + + Resync with gnulib. + * GNUmakefile: Grab from upstream, to fix issue where 'make + install' would allow installation of stale version string. + +2008-07-19 Eric Blake + + Support multiple arguments to m4_defn, m4_popdef, and m4_undefine. + * lib/m4sugar/m4sugar.m4 (m4_defn, m4_popdef, m4_undefine): Loop + through all variables, per POSIX and newer m4. + (_m4_text_wrap): Exploit the looping capabilities. + * tests/m4sugar.at (m4@&t@_defn): Test this. + * NEWS: Document it. + * doc/autoconf.texi (Redefined M4 Macros) + : Likewise. + + Reduce overhead of m4_builtin([defn]). + * lib/m4sugar/m4sugar.m4 (_m4_defn, _m4_popdef, _m4_undefine): New + internal macros, which are slightly more efficient than + m4_builtin([defn]) and company. + (m4_defn, m4_popdef, m4_undefine, m4_warn, m4_ifset) + (_m4_dumpdefs_up, _m4_dumpdefs_down, _m4_wrap, m4_for) + (_m4_divert_n_stack, m4_divert_pop, m4_expansion_stack_push) + (m4_expansion_stack_dump, _m4_defun_pro, _m4_defun_epi) + (_m4_defun_epi_outer, _m4_require_call, m4_combine, m4_append) + (_m4_append_uniq, m4_append_uniq_w, _m4_text_wrap, m4_text_box) + (m4_version_prereq): Use them. + + Use warnings from m4 when available. + * lib/m4sugar/m4sugar.m4 (m4_defn, m4_popdef, m4_undefine): Don't + define slower wrapper if m4 will warn on our behalf; key off of + __m4_version__, added alongside the new warnings in m4 1.6. + * tests/m4sugar.at (m4@&t@_defn): New test. + +2008-07-18 Eric Blake + + Add m4_joinall. + * lib/m4sugar/m4sugar.m4 (m4_joinall, _m4_joinall): New macros. + * tests/m4sugar.at (m4@&t@_join): Test them. + * doc/autoconf.texi (Text processing Macros) : Document + m4_joinall. + * NEWS: Likewise. + +2008-07-17 Stepan Kasal + and Eric Blake + + Improve documentation of config.h.in template rules. + * doc/autoconf.texi (Header Templates): Mention rules on comments + and whitespace, and that the user cannot rely on #undef to survive + through config.status. + +2008-07-16 Eric Blake + + Revert m4_prepend; it is less efficient, and unused by bison. + * lib/m4sugar/m4sugar.m4 (m4_prepend, m4_prepend_uniq) + (m4_prepend_uniq_w): Delete addition from 2008-07-11. + (_m4_grow_uniq_1): Rename back... + (_m4_append_uniq): ...to this. + * NEWS: Revert NEWS blurb. + * doc/autoconf.texi (Text processing Macros) : Delete. + * tests/m4sugar.at (m4@&t@_prepend): Delete. + +2008-07-15 Eric Blake + + Avoid failure if version.m4 is omitted but m4_PACKAGE_* unused. + * lib/m4sugar/m4sugar.m4 (m4_version_compare): Provide alternate + definition for non-Autoconf clients of m4sugar. + +2008-07-14 Eric Blake + + Tighten bound of potential speed of m4_append. + * doc/autoconf.texi (Text processing Macros) + : If m4 is fixed, m4_append can be linear rather than + O(n log n). + * lib/m4sugar/m4sugar.m4 (m4_append, m4_append_uniq): Fix comments. + Analysis by Bruno Haible. + +2008-07-11 Eric Blake + + Inherit improvements from bison's fork of m4sugar. + * lib/m4sugar/m4sugar.m4 (m4_PACKAGE_VERSION): Ignore failure to + find version.texi, since bison does not provide it. + (m4_prepend): Add new macro, from bison. + (m4_prepend_uniq, m4_prepend_uniq_w): Add new macros, for + completeness. + (_m4_append_uniq): Rename... + (_m4_grow_uniq_1): ...to this to share implementation, and + optimize initial assignment. + (m4_append_uniq_w): Adjust caller. + * NEWS: Document new macros. + * doc/autoconf.texi (Text processing Macros) : Mention + speed consideration. + : Document the new prepend variants. + * tests/m4sugar.at (m4@&t@_prepend): New test. + + Work around M4 1.6 warning on undefined macros. + * lib/m4sugar/m4sugar.m4 (changeword, symbols): Don't rename if + not already available as builtins. + +2008-07-06 Ralf Wildenhues + + * doc/autoconf.texi (@dvar): Remove trailing newline. + (@ovar): Likewise. Fix macro documentation. + +2008-07-02 Stepan Kasal + + Add quotes to the header of autoscan-generated source. + * bin/autoscan.in: Add quotes to AC_PREREQ and AC_INIT. + +2008-06-28 Andreas Schwab + + * doc/autoconf.texi (autoscan Invocation): Fix spacing. + (autoconf Invocation): Likewise. + (autoreconf Invocation): Likewise. + (autoheader Invocation): Likewise. + (autom4te Invocation): Likewise. + +2008-06-19 Eric Blake + + Add comment explaining recent patch. + * lib/autotest/general.m4 (AT_INIT) : Explain choice + of * vs. ? globbing. + +2008-06-19 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_LINK): Do not warn when not + linking a file to itself. + Report by Bruno Haible. + +2008-06-19 Eric Blake + + Resync with gnulib. + * GNUmakefile: Grab from upstream, to fix VPATH 'make dist' bug. + Reported by Stepan Kasal. + +2008-06-18 Ralf Wildenhues + + Reorganize autotest files, factorize for parallel execution. + * lib/autotest/general.m4 (AS_MESSAGE_LOG_FD): Move definition + earlier in the file. + (AT_INIT): Create line number cache in + $at_suite_dir/at-source-lines. + : New directory at-groups below $at_suite_dir. + Add comment explaining the new directory structure. + (at_func_group_prepare, at_func_group_postprocess): New shell + functions to factorize per-test group work. Keep the actual + test execution outside of a shell function in order to avoid + zsh 4.x exit status bugs. + + : Turn these into per-group files + below $at_helper_dir. Also store test results there in files + named pass, fail, xpass, xfail, skip. Let the parent collect + results from $at_helper_dir. Adjust summary statistics + computation and result output. + +2008-06-17 Ralf Wildenhues + + Fix '#undef variable /* comment */' transform in config headers. + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS_PREPARE): For + undefined preprocessor macros that are followed by a comment + in the header template, do not create nested comments in the + output. + * tests/torture.at (@%:@define header templates): Extend test. + * NEWS: Update. + Report by Karsten Hopp . + +2008-06-09 Eric Blake + + Mark AC_TYPE_SIGNAL as obsolete. + * lib/autoconf/types.m4 (AC_TYPE_SIGNAL): Switch to AU_DEFUN. + * doc/autoconf.texi (Function Portability): Update documentation. + (Particular Types): Move AC_TYPE_SIGNAL... + (Obsolete Macros): ...here, and mention why. + * NEWS: Mention the change. + + Allow lib64 as a default X library location. + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): Add lib64. + * NEWS: Mention the change. + * THANKS: Update. + Reported by Brad Walker. + +2008-06-05 Eric Blake + + Fix regression in AT_KEYWORDS([Macro]), from 2007-10-18. + * lib/autotest/general.m4 (AT_KEYWORDS): Expand argument prior to + converting it to lower case. + * tests/autotest.at (Keywords and ranges): Test this. + * NEWS: Document the fix. + * THANKS: Update. + Reported via Karsten Hopp, by Jochen Schmitt in + https://bugzilla.redhat.com/show_bug.cgi?id=449973 + +2008-06-03 Eric Blake + + Fix 'make dist' regression from 2008-05-08. + * Makefile.am (INSTALL): Add rule, to accomodate 'make dist' after + GNUmakefile's _autoconf rule removes INSTALL. + +2008-05-27 Eric Blake + + Document Solaris /bin/sh redirection pitfall. + * doc/autoconf.texi (File Descriptors): Mention redirection bug. + +2008-05-14 Eric Blake + + Improve documentation of ! issues. + * doc/autoconf.texi (Limitations of Builtins) : Touch up. + Reported by Noah Misch. + + Document some FreeBSD shell bugs. + * doc/autoconf.texi (Limitations of Builtins) : Mention ! issue + in compound pipe commands. + : Mention difference of exporting an undefined variable. + (Shell Functions): Mention loss of $? in entry to shell functions. + Extracted from the git mailing list. + +2008-05-13 Stepan Kasal + + Work around MSYS and Cygwin bugs when dealing with trailing space. + * tests/atlocal.in (func_sanitize_dir_name): Let atlocal succeed, + even when platform bugs are tickled. + Reported by Keith Marshall and Eric Blake. + +2008-05-12 Ralf Wildenhues + + Let AC_MSG_FAILURE report pwd. + * lib/autoconf/general.m4 (_AC_ARG_VAR_VALIDATE, AC_MSG_FAILURE): + Output $ac_pwd along with fatal failure. + * tests/torture.at (Deep Package): Extend test. + Reported numerous times against GCC, and probably other packages. + +2008-05-12 Eric Blake + + Enforce --help and --version compliance. + * configure.ac (AM_INIT_AUTOMAKE): Add std-options option. + +2008-05-08 Keith Marshall (tiny change) + + Avoid case-insensitive `make install' vs. `INSTALL' conflict. + * Makefile.am ($(srcdir)/INSTALL): Replace all references... + ($(abs_srcdir)/INSTALL): ...with this. + +2008-05-06 Eric Blake + + Fix typo. + * doc/autoconf.texi (Shell Substitutions): Drop at_ prefix. + + Avoid overfull \hbox. + * doc/autoconf.texi (Versioning): Reword to fit line size. + + Document $(( )) pitfalls. + * doc/autoconf.texi (Shell Substitutions): Mention octal + vs. decimal. Mention autotest's at_func_arith. + + Improve behavior of './testsuite 01'. + * lib/autotest/general.m4 (AT_INIT) : + Alter usage to eval its arguments, in order to normalize away + leading zero. All callers updated. + * tests/autotest.at (Keywords and ranges): Test range + normalization with leading 0. + +2008-04-26 Eric Blake + + Mention Solaris /usr/ucb/tr pitfall. + * doc/autoconf.texi (Limitations of Usual Tools) : Add section. + Reported by Bruno Haible and Jim Meyering. + +2008-04-24 Eric Blake + + Mention m4sugar's internal quote strings. + * doc/autoconf.texi (Quadrigraphs): Mention alternate quote used + in m4sugar, and how to still output it literally. + * tests/m4sugar.at (m4@&t@_split): And test it. + Reported by Joel E. Denny. + +2008-04-23 Eric Blake + + Allow unbalanced () in m4_expand. + * lib/m4sugar/m4sugar.m4 (m4_expand, _m4_expand): Use more complex + quotes. + (m4_noquote, _m4_split): Use consistent complex quote. + * tests/autotest.at (Left paren, Right paren): Test this. + (Parentheses): Ensure new quadrigraphs still work. + (AT_CHECK_AT_TITLE_CHAR): All title char tests exercise m4_expand. + * NEWS: Mention the fix. + * doc/autoconf.texi (Quadrigraphs): Revert mention of macros that + require quadrigraphs for (). + (Evaluation Macros) : Relax the restriction against + unbalanced (). + (Pretty Help Strings) : Likewise. + (Writing Testsuites) : Likewise. + Reported by Joel E. Denny, fix suggested by Noah Misch. + +2008-04-22 Eric Blake + + Support unbalanced () in AT_SETUP by adding two new quadrigraphs. + * bin/autom4te.in (handle_output): Substitute @{:@ and @:}@. + (handle_traces): Likewise. + * lib/m4sugar/m4sugar.m4 (m4_qlen): Account for new quadrigraphs. + * tests/autotest.at (AT_CHECK_AT_TITLE_CHAR): Add new tests. + * doc/autoconf.texi (Quadrigraphs): Document them. + (Evaluation Macros) : Enhance documentation. + (Text processing Macros) : Document cases where + quadrigraphs can help for problemetic unbalanced parentheses. + (Pretty Help Strings) : Likewise. + (Writing Testsuites) : Likewise. + (Limitations of Builtins) : Consolidate text on unbalanced + parentheses, and add an example of creative comments. + * NEWS: Document the addition. + Reported by Joel E. Denny. + +2008-04-16 Eric Blake + + Document pdksh exec behavior. + * doc/autoconf.texi (Limitations of Builtins) : New + subsection. + Discovered by Jim Meyering. + +2008-04-14 Ralf Wildenhues + + * tests/autotest.at (AT_CHECK_AT): Allow to pass additional + arguments to the inner suite. + (errexit, input from stdin): New tests. + +2008-04-13 Ralf Wildenhues + + * NEWS: Post-release update. + +2008-04-10 Eric Blake + + AC_AUTOCONF_VERSION might contain arbitrary macro names. + * doc/autoconf.texi (Versioning): Mention problem with expansion. + * tests/tools.at (autoconf: AC_AUTOCONF_VERSION): Adjust test. + +2008-04-09 Slava Sysoltsev (tiny change) + + Flush buffered output before exit. + * bin/autom4te.in (handle_output): Explicitly close file. + * THANKS: Update. + See http://lists.gnu.org/archive/html/autoconf/2008-04/msg00026.html. + +2008-04-08 Eric Blake + + Generate web docs for 2.62. + * doc/autoconf.texi (Evaluation Macros): Fix typo. + (Notices): Use recommended means to escape RCS keyword. + * cfg.mk (gnulib_dir): New macro. + (web-manual): New target. + +2008-04-05 Eric Blake + + Release Version 2.62. + * NEWS: Mention the release. + +2008-04-04 Stepan Kasal + and Eric Blake + + Return back to GPLv2+, until the text of the exceptions is + finalized, reverting the change from 2007-07-03 and the first + part of the change from 2007-07-20. + * COPYING: Revert to GPLv2. + * COPYINGv3: New file, since some auxiliary build tools, used for + building autoconf and not installed, are GPLv3. + * Makefile.am (EXTRA_DIST): Distribute COPYINGv3. + * NEWS: Remove mention of GPLv3. + * README: Clarify situation regarding GPLv3. + +2008-04-05 Eric Blake + + Prepare for release. + * maint.mk (announcement): Avoid deleted option. + * cfg.mk (release_archive_dir): Use default. + * build-aux/gnupload: New file, from automake/gnulib. + * Makefile.am (EXTRA_DIST): Distribute it. + * .x-sc_two_space_separator_in_usage: New file, to exempt gnupload + from syntax check. + +2008-04-05 Jim Meyering + and Ralf Wildenhues + + Work around CR EOL markers on OS/2 (www.ecomstation.com Ecs v2 rc4) + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): When CR + is the EOL marker, skip a step that would remove and translate + carriage return bytes. + * THANKS: Update. + Reported by Elbert Pol. + +2008-04-05 Eric Blake + + Avoid some autoreconf -Wall warnings. + * configure.ac: Use proper quoting, to be a good example. + (PACKAGE_NAME): Remove setting covered by autoconf. + (AM_INIT_AUTOMAKE): Bump automake requirement, for html rules. + * doc/Makefile.am (TEXI2DVI): Remove settings covered by + automake. + (html, autoconf_1.html, standards_1.html): Likewise. + (TEXI2HTML, TEXI2HTML_FLAGS): Remove unused macros. + * Makefile.am (html): Likewise. + * doc/autoconf.texi (Quoting and Parameters): Add missing section + name. + * tests/Makefile.am (AUTOMAKE_OPTIONS): Intentionally ignore + warning about our override, until Automake is fixed. + * README-hacking: Document minimum requirements for bootstrap. + +2008-04-03 Eric Blake + + Fix version number generation in man pages. + * Makefile.am (EXTRA_DIST): Distribute .version. + (.version): New rule. + * man/Makefile.am (common_dep): Depend on .version, not + configure.ac. + (.x.1): Use package name for version string. + * GNUmakefile [!_have-Makefile]: Sync from upstream, again. + * build-aux/git-version-gen: Sync from upstream. + + More maintainer tweaks: pass 'make maintainer-distcheck'. + * GNUmakefile (_is-dist-target): Sync from upstream. + * build-aux/vc-list-files: Sync from upstream, yet again. + * tests/atlocal.in (unsupported_fs_chars): Always remove tdir. + * tests/Makefile.am (EXTRA_DIST): Don't distribute the built + package.m4. + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Bump year. + + Fix VPATH 'make syntax-check'. + * maint.mk (VC_LIST, VC_LIST_EXCEPT, sc_changelog) + (sc_prohibit_jm_in_m4, makefile-check): Support VPATH. + (author_mark_check): Avoid error message. + * build-aux/vc-list-files: Sync from upstream again. + * build-aux/texinfo.tex: Likewise. + + Sync files from upstream, and pass 'make syntax-check'. + * config/announce-gen: Move... + * build-aux/announce-gen: ...here, and sync from gnulib. + * Makefile.am (EXTRA_DIST): Adjust accordingly. + * cfg.mk (announce_gen): Likewise. + (prev_version_file): Delete, relying on default in maint.mk. + (gpg_key_ID): New macro. + (url_dir_list): Rewrite to match coreutils. + * config/prev-version.txt: Move... + * .prev-version: ...here, and adjust to 2.61. + * build-aux/vc-list-files: Sync from coreutils. + * maint.mk: Resynchronize with coreutils, where possible. + (ME): Remove $(srcdir) from definition. + (CVS): Delete. + (GIT, VC, VC-tag): New macros. + (CVS_LIST, CVS_LIST_EXCEPT): Rename... + (VC_LIST, VC_LIST_EXCEPT): ...to this. + (cvs-tag-check): Delete. + (cvs-diff-check): Rename... + (vc-diff-check): ...to this. + (sc_file_system): Allow FHS acronym. + * doc/autoconf.texi (Particular Functions): Recommend + unconditional . + * build-aux/config.guess: Sync from upstream (manually). + * build-aux/config.sub: Likewise. + * build-aux/texinfo.tex: Likewise. + * doc/make-stds.texi: Likewise. + * doc/standards.texi: Likewise. + * .gitattributes: Ignore whitespace problems in upstream files. + +2008-04-03 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Usual Tools): Mention awk %u + bug on HP-UX/IA. + Report by Peter O'Gorman. + +2008-04-02 Eric Blake + + Recommend the just-released M4 1.4.11. + * NEWS: Update recommendation. + * README: Likewise. + * doc/autoconf.texi (Introduction): Likewise. + * m4/m4.m4 (AC_PROG_GNU_M4): Likewise. + +2008-04-01 Eric Blake + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Bump + copyright year. + +2008-03-28 Peter O'Gorman + + Find X11 on Mac OS X too. + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT,_AC_PATH_X_XMKMF): + Check for libX11 with extensions dylib la and dll too. + * THANKS: Update. + Reported by Martin Costabel. + +2008-03-28 Eric Blake + + Update TODO based on completed tasks. + * TODO (AC_PROG_INSTALL takes multiple files): Done. + (AC_GNU_SOURCE deprecation): Done, see AC_USE_SYSTEM_EXTENSIONS. + (AC_COMPILE_IFELSE documentation): Done. + (Tracing builtins): Done, now that we require M4 1.4.5. + (AC_PROG_CC_POSIX suggestion, providing header files) + (AC_TYPE_SIGNAL): Not needed; gnulib's approach is better. + (cache consistency): Done with precious variables. + +2008-03-26 Eric Blake + + Document --trace=macro:format in --help output. + * bin/autom4te.in (help): Mention optional trace format. + * bin/autoconf.as (usage): Likewise. + + * doc/autoconf.texi (Limitations of Usual Tools) : Fix + typos in last patch. + Reported by Ralf Wildenhues. + +2008-03-26 Jim Meyering + + Fix texinfo syntax error. + * doc/autoconf.texi (Limitations of Usual Tools): s/@kbd {/@kbd{/ + +2008-03-26 Ralf Wildenhues + + Warn, not fail on whitespace-only precious variable differences. + * lib/autoconf/general.m4 (_AC_ARG_VAR_VALIDATE): Output + precious variable differences less ambiguous with `ugly-quotes'. + If their settings differ only in whitespace, do not fail, but + reuse the old value. + * tests/torture.at (AT_CHECK_AC_ARG_VAR): Extend macro to allow + an optional status and expected-warning argument. Fix m4 + quotation for initial value. + (AC_ARG_VAR): Also test for whitespace-only differences, and + that the old value is retained in this case. + * doc/autoconf.texi (Setting Output Variables): Document this. + * NEWS: Update. + Report and initial patch by Paolo Bonzini. + +2008-03-26 Eric Blake + + Document busybox sed bug. + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + restrictions when using back-references. + Reported by Vincent Lefevre: + . + + Document Automake interaction with AC_CONFIG_MACRO_DIR. + * doc/autoconf.texi (Input): Mention ACLOCAL_AMFLAGS for automake + users. + * THANKS: Update. + Reported by Chris Pickett. + +2008-03-25 Ralf Wildenhues + + * tests/autotest.at (Using atlocal): Quote instances of `pwd`. + + * tests/local.at (AT_CHECK_M4): Factorize warning output + normalization. + Suggested by Eric Blake. + +2008-03-24 Ralf Wildenhues + + Fix .exe-related test failure on MinGW. + * tests/local.at (AT_CHECK_M4): Normalize `/bin/m4.exe' correctly + for comparing warning output. + + Fix Fortran testsuite failures with gfortran 4.3. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): When scanning + verbose compiler output, skip lines that set variables; gfortran + 4.3 sets LIBRARY_PATH, COMPILER_PATH, COLLECT_GCC_OPTIONS. + * THANKS: Update. + Report by Vincent Lefèvre. + +2008-03-21 Eric Blake + + * GNUmakefile: Resynchronize with gnulib. + + Document more uses of $cross_compiling. + * doc/autoconf.texi (Runtime): Document that a temporary override + is permissible. + * THANKS: Update. + Reported by Ineiev, example by Ralf Wildenhues. + + Don't swallow $1 in textual local variables. + * lib/m4sugar/m4sugar.m4 (m4_combine): Don't use overquoting and + expansion of text arguments, as that swallows $1. + (m4_text_wrap): Likewise, by splitting out... + (_m4_text_wrap): ...new helper macro. Also, allow arbitrary + expression for width. + * tests/m4sugar.at (m4@&t@_text_wrap): Test this. + (m4@&t@_combine): Likewise. + +2008-03-21 Ralf Wildenhues + + Avoid leftover files on Leopard. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT): Remove a.out.dSYM + directory created on darwin. + (AC_NO_EXECUTABLES): Likewise; also remove objects which may be + left over from a broken link. + * tests/c.at (AC_NO_EXECUTABLES (working linker)) + (AC_NO_EXECUTABLES (broken linker)): New tests. + Report by Gary V. Vaughan. + + * lib/autom4te.in (Automake-preselections): Trace + _AM_COND_IF, _AM_COND_ELSE, _AM_COND_ENDIF. + +2008-03-20 Eric Blake + + Kill more CVS references. + * README-cvs: Delete. See README-hacking instead. + * README-hacking: Update wording, based on older file. + * BUGS: Remove CVS mention. + +2008-03-20 Ralf Wildenhues + + * tests/tools.at (autotools and whitespace in file names): Skip + if aclocal is not present. + +2008-03-20 Eric Blake + + Sync GNUmakefile with gnulib. + * GNUmakefile (Makefile.cfg): Rename... + (cfg.mk): ...to this, and make optional. + (GNUmakefile.cfg): Delete, redundant with cfg.mk. + (Makefile.maint): Rename... + (maint.mk): ...to this. + (all) [!_have-Makefile]: Rename... + (abort-due-to-no-makefile): ...to this, and invoke via + .DEFAULT_GOAL to pick up all targets. + * Makefile.cfg: Rename... + * cfg.mk: ...to this. + * Makefile.maint: Rename... + * maint.mk ...to this. + (ME): Reflect name change. + (makefile-check, m4-check, author_mark_check, msg): Use $(ME) + rather than hard-coded name. + * GNUmakefile.cfg: Delete; move rules into cfg.mk. + * Makefile.am (EXTRA_DIST): Reflect file name changes. + * .x-sc_prohibit_atoi_atof: Likewise. + * lib/freeze.mk: Likewise. + +2008-03-19 Stepan Kasal + + * doc/autoconf.texi (Introduction): Improve the paraphrase of + Henry Spencer's quotation. + +2008-03-19 Eric Blake + + AC_CONFIG_HEADERS replaced AC_CONFIG_HEADER. + * bin/autoscan.in (output): Avoid obsolete spelling. + * tests/local.at (AC_STATE_SAVE): Update usage. + * THANKS: Update. + Reported by John Calcote. + + Emphasize that ease of configure triumphs over ease of autoconf. + * doc/autoconf.texi (Introduction): Expand on primary + vs. secondary goal of autoconf. + * THANKS: Update. + Inspired by Paul Smith. + +2008-03-17 Ralf Wildenhues + + * lib/Autom4te/FileUtils.pm (handle_exec_errors): New argument + $hint, show if the executing program does not exist. + (xsystem_hint): New function, like xsystem but allows to pass + a hint. + * bin/autoreconf.in: Use xsystem_hint for spawning autopoint and + libtoolize. + Report by Bruce Korb. + +2008-03-14 Stepan Kasal + + * lib/Autom4te/ChannelDefs.pm, tests/fortran.at, + tests/mktests.sh, tests/wrapper.as: Fix typos. + +2008-03-12 Eric Blake + + Fix yesterday's regression in m4_wrap([$1]). + * lib/m4sugar/m4sugar.m4 (_m4_wrap): Don't directly invoke wrapped + text, since it may contain text that looks like parameters. + * tests/m4sh.at (AS@&t@_INIT cleanup): Enhance test. + +2008-03-11 Eric Blake + + Improve error messages for common testsuite bugs. + * lib/autotest/general.m4 (_AT_DEFINE_INIT, _AT_DEFINE_SETUP): New + macros for defining order-enforced macros. + (AT_INIT, AT_SETUP, AT_CLEANUP, AT_BANNER, AT_XFAIL_IF) + (AT_CAPTURE_FILE, AT_DATA, AT_CHECK, AT_CHECK_NOESCAPE): Add error + messages when order violations are detected. + * tests/autotest.at (AT_CHECK_AT_SYNTAX): New helper macro. + (AT_SETUP without AT_INIT, AT_BANNER without AT_INIT) + (AT_CLEANUP without AT_INIT, Missing AT_CLEANUP) + (AT_CHECK without AT_SETUP, AT_DATA without AT_SETUP) + (AT_XFAIL_IF without AT_DATA, AT_KEYWORDS without AT_SETUP, + (AT_CLEANUP without AT_SETUP, AT_BANNER inside AT_SETUP) + (AT_SETUP inside AT_SETUP, Multiple AT_INIT) + (Banner-only test suite): New tests. + Reported by Christopher Hulbert. + + Tweak m4_wrap to force FIFO or LIFO semantics. + * lib/m4sugar/m4sugar.m4 (m4_wrap): Override M4 implementation. + (m4_wrap_lifo, _m4_wrap): New macros. + * lib/m4sugar/m4sh.m4 (AS_INIT): Combine all cleanup into known + order, prior to m4sugar's. + (_AS_DETECT_BETTER_SHELL): Use cleanup parameter, rather than + m4_wrap. + * lib/autotest/general.m4 (AT_INIT): Combine all cleanup into + known order, prior to m4sh's. + * doc/autoconf.texi (Diagnostic Macros) : Document + argument. + (Redefined M4 Macros) : Rewrite documentation to match + new behavior. + * tests/m4sh.at (AS_INIT cleanup): New test. + * NEWS: Document the change. + +2008-03-10 Eric Blake + + Encode nested autotest data. + * tests/autotest.at (AT_CHECK_AT_PREP): Avoid raw AT_ in output. + (unusual file names): Likewise. + (m4_pattern_allow): Remove loophole, to make it easier to catch + poorly written tests. + + Factor some autotest tests. + * tests/autotest.at (AT_CHECK_AT_PREP): New macro, to factor out + common initialization. + (AT_CHECK_AT, Banners, Keywords and ranges, srcdir propagation) + (whitespace in absolute testdir, unusual file names): Use it. + +2008-03-06 Eric Blake + + Minor documentation fix. + * doc/autoconf.texi (Evaluation Macros): Fix typo. + +2008-03-04 Eric Blake + + Make AT_CHECK act like a simple command. + * lib/autotest/general.m4 (_AT_CHECK): Wrap commands in {;}. + * tests/torture.at (AT_CHECK_CONFIG_CREATION_NOWRITE): Test it. + +2008-03-04 Ralf Wildenhues + + On MinGW, substitution of CR and 0xFF fails. + * tests/torture.at (Substitute and define special characters): + MinGW awk cannot handle 0xFF, and on MinGW, the test does the + wrong thing for CR. + +2008-03-04 Eric Blake + + Pull in recent maintainer improvements from coreutils. + * GNUmakefile (_is-dist-target): 'make distclean' should not + trigger autoreconf. + (_dummy): Change directories before removing autom4te.cache. + (check dist distcheck install) [!_have-Makefile]: Provide nicer + diagnostics. + * configure.ac (AC_CONFIG_LINKS): Copy GNUmakefile into VPATH + builds, after initial bootstrap. + * Makefile.am (distclean-local): Work around current automake bug. + * Makefile.maint (ME): Allow VPATH usage. + + Use git-merge-changelog when available. + * .gitattributes: New file. + * README-hacking: Document use of git-merge-changelog. + + Work around cygwin bug. + * tests/atlocal.in (unsupported_fs_chars): Avoid cygwin bug where + "touch 't\'" creates regular file 't'. + + Ignore tests that require read-only directories under root. + * tests/torture.at (AT_CHECK_CONFIG_CREATION_NOWRITE): Skip + no-write portion if user has root-like privileges. + +2008-03-04 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): Fix detection of '-C -'. + +2008-03-03 Ralf Wildenhues + + autoreconf -m now honors $MAKE. + * bin/autoreconf.in ($run_make): Renamed from ... + ($make): ... this. Use now as command to run `make', + overridden by $MAKE. Document this in --help output. + * doc/autoconf.texi (autoreconf Invocation): Document + all environment variables honored by autoreconf. + * NEWS: Update. + Report by Paul Eggert. + +2008-03-03 Eric Blake + + Documentation improvements. + * doc/autoconf.texi (Looping constructs): s/recurses/repeats/. + (Evaluation Macros): Drop `1' suffix from metasyntax variable name + that preceeds @dots. Improve wording. + (Text processing Macros): Drop `1' suffix from metasyntax variable + name that preceeds @dots. + (Number processing Macros): Drop `1' suffix from metasyntax + variable name that preceeds @dots. Improve wording. + * lib/m4sugar/m4sugar.m4 (m4_cmp): Comment wording fix. + Suggested by Ralf Wildenhues. + +2008-03-02 Jim Meyering + + Don't infloop upon "make dist". + * GNUmakefile: Merge from coreutils. + * Makefile.am (dist-hook): Inject .tarball-version into tarball, + not .version. + * configure.ac (AC_INIT): Use .tarball-version, not .version. + * build-aux/git-version-gen: Update from gnulib. + +2008-03-02 Ralf Wildenhues + + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Before using /dev/full, check that it is a writable character + special device. + Report by Benoit Sigoure and Eric Blake. + + Actually test that @configure_input@ is expanded correctly. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Actually check generated file contents for the name of the + generated file, using AC_PROG_FGREP and $FGREP. + +2008-03-01 Benoit Sigoure + + Be nice with file systems that don't handle unusual characters. + * tests/atlocal.in (func_sanitize_file_name) + (func_sanitize_dir_name): New shell functions. + * tests/tools.at (autom4te and whitespace in file names) + (autotools and whitespace in file names): Use them. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Cover more potentially problemtic file names. Use the new + functions. + + Properly handle funny file names for headers in config.status. + The test suite did not cover this bug because the code was not + quoting properly the arguments of `rm -f' (which "fails" silently) + as well as the arguments of `diff' (whose output was redirected to + /dev/null so we couldn't see its error message). + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADER): Properly quote the + file names passed to `rm' and `diff'. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Add a regression test. + +2008-03-01 Benoit Sigoure + and Ralf Wildenhues + + Properly expand @configure_input@ in config.status. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE, _AC_OUTPUT_MAIN_LOOP): + Escape the backslashes and ampersands in $configure_input before + using it in the sed replacement string to expand @configure_input@. + Report by Eric Blake and Patrick Welche. + +2008-03-01 Ralf Wildenhues + + Ignore errors from ./run on w32. + * tests/autotest.at (whitespace in absolute testdir): + Ignore stderr for `./run' which fails to remove the + busy test directory on w32. + +2008-02-22 Eric Blake + + Improve documentation for writing autotest suites. + * doc/autoconf.texi (Writing Testsuites) : Mention that + checks must live inside a test group. + Reported by Christopher Hulbert. + +2008-02-21 Eric Blake + + Sync git-version-gen from upstream. + * build-aux/git-version-gen: Pull from gnulib. + * configure.ac (AC_INIT): Adjust to new calling convention. + +2008-02-12 Eric Blake + + Avoid trailing space in config.h with AC_DEFINE([var], []). + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Explicitly mark empty + defines with a comment. + +2008-02-08 Eric Blake + + Fix texinfo typos in previous patch. + * doc/autoconf.texi (Site Defaults): s/[{}]/@&/g. + Reported by Ralf Wildenhues. + + Describe a config.site that can be used for FHS compliance. + * doc/autoconf.texi (Site Defaults): Fix typo. Add new example + for FHS. + * THANKS: Update. + Reported by Jules Colding and Ralf Wildenhues. + +2008-02-02 Eric Blake + + * doc/autoconf.texi (Limitations of Usual Tools) : Fix typo. + +2008-02-02 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): Fix --clean to work + again, broken since introduction of `-C dir'. + * tests/autotest.at (Choosing where testsuite is run): Test it. + +2008-01-30 Paul Eggert + + * doc/autoconf.texi: Update Back-Cover text to reflect new GNU wording. + +2008-01-29 Eric Blake + + Fix more autotest regressions. + * lib/autotest/general.m4 (AT_LINE): Fix regression from + 2007-10-04 when file name is `dnl'. + (AT_INIT) : Move command-line assignments... + : ...to this new diversion, to fix regression from + yesterday in libtool's testsuite. + (_AT_ARG_OPTION): Detect write failure. + * doc/autoconf.texi (Diversion support): Document PREPARE_TESTS to + make libtool's use kosher. Document m4_init. + (Programming in M4sh): Document AS_INIT. + (Writing Testsuites): Document limitation of AT_DATA file name. + * tests/autotest.at (unusual file names): New test. + (Banners, Keywords and ranges): Use correct shell. + + More corner cases in testsuite VAR=VALUE handling. + * lib/autotest/general.m4 (AT_INIT) : Also detect leading digits in assignments. + * tests/autotest.at (Using atlocal): Enhance test to catch last + bug. + + * doc/autoconf.texi (Limitations of Builtins) <.>: Mention bash + bug. + +2008-01-28 Eric Blake + + Fix regression in handling VAR=VALUE arguments to testsuite. + * lib/autotest/general.m4 (AT_INIT) : Detect + leading = as invalid. Defer use of command-line variable + assignments... + : ...here, after atconfig has been sourced. Fix + regression in sourcing files. + * tests/autotest.at (Using atlocal): New test to catch this. + (Debugging a successful test, Choosing where testsuite is run): + Use correct shell. + Reported by Ralf Wildenhues. + + Document grep peculiarity. + * doc/autoconf.texi (Limitations of Usual Tools) : Document + BSD behavior on binary input. + + Minor testsuite improvements. + * lib/autotest/general.m4 (AT_INIT) : Use fewer + forks when sanitizing PATH. Always output machine information, + not just when atconfig was located. + + Add 'testsuite -C dir'. + * lib/autotest/general.m4 (_AT_ARG_OPTION): Move missing argument + detection... + (AT_INIT) : ...here, since -k always takes + argument. + : Delay computation of variables based on $at_dir... + : ...to here, since -C can change $at_dir. + : Re-invoke via absolute name, since -C may be in effect. + : Parse new option. + : Document it. + * tests/autotest.at (Choosing where testsuite is run): New test + for this feature. + (Keywords and ranges): Add test for missing -k argument. + * NEWS: Document this. + * doc/autoconf.texi (testsuite Invocation): Likewise. + +2008-01-24 Ralf Wildenhues + + * build-aux/config.guess, build-aux/config.sub, + build-aux/texinfo.tex: Sync from gnulib. + * doc/fdl.texi, doc/make-stds.texi, doc/standards.texi: + Likewise. + +2008-01-23 Ralf Wildenhues + + * doc/autoconf.texi (Particular Programs): Do not mention the + Autoconf version in which the AC_PROG_INSTALL change was done. + Suggested by Paul Eggert. + +2008-01-22 Ralf Wildenhues + + Fix --help=recursive with multiple AC_CONFIG_SUBDIRS. + * lib/autoconf/general.m4 (_AC_INIT_HELP): If, for recursive help + mode, we change to the source directory, also set $ac_pwd so we + do not go back to the build tree for the next config subdir. + * tests/torture.at (Deep Package): Extend test to contain two + config subdirs on the top level. + + Fix parallel `maintainer-check'. + * Makefile.am (maintainer-check-tests): Depend on `all'. + Use `$(MAKE) $(AM_MAKEFLAGS)' instead of plain `make'. + * tests/Makefile.am (maintainer-check-c++, maintainer-check-posix): + Likewise. + (maintainer-check): Serialize the testsuite runs. + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ENABLE2): Accept `+' + in feature string for --enable/--with. Convert to underscore + for variable name. + + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Require that + `install -c file1 file2 dir' works. + * doc/autoconf.texi (Particular Programs): Document this. + * NEWS: Update. + +2008-01-21 Eric Blake + + Improve documentation about default include directives. + * doc/autoconf.texi (Generic Headers, Generic Declarations) + (Generic Structures, Generic Types) + (Generic Compiler Characteristics): Add links to + AC_INCLUDES_DEFAULT. + Reported by Reuben Thomas. + +2008-01-15 Eric Blake + + * lib/m4sugar/m4sugar.m4 (m4_qlen): Use fewer macros. + +2008-01-08 Ralf Wildenhues + + * tests/Makefile.am (noinst_SCRIPTS): Renamed from + check_SCRIPTS. Building the wrappers for `all' allows help2man + to use them for the manpages. + Report by Benoit Sigoure. + + * bin/autoreconf.in: Discard stderr for $autoconf/$aclocal --help. + +2007-12-16 Ralf Wildenhues + + Fix some write failure cases in Autotest. + * lib/autotest/general.m4 (AT_INIT): Do not exit successfully + upon write failures for --help, --version, --list. + Guard against write failures for intermediate created scripts. + : Do not make the debugging + script executable if it is not complete. + +2007-12-12 Eric Blake + + Fix thinko in earlier patch - m4_join isn't defined yet. + * lib/m4sugar/m4sugar.m4 (m4_expansion_stack_push, _m4_defun_pro) + (_m4_defun_pro_outer, _m4_defun_epi, _m4_defun_epi_outer) + (m4_require): Use m4_do, not m4_join. + + Fix some whitespace tests on cygwin. + * tests/tools.at (autom4te and whitespace in file names): Restore + font-lock. Create $TMPDIR before it might be used. + + Fix spurious testsuite failure with M4 1.4.11. + * tests/local.at (AT_CHECK_M4): Cater to new m4 error message. + + Optimize AC_REQUIRE. + * lib/m4sugar/m4sugar.m4 (m4_expansion_stack_push, _m4_defun_pro) + (_m4_defun_pro_outer, _m4_defun_epi, _m4_defun_epi_outer) + (m4_require): Avoid extra macro calls. + +2007-12-08 Ralf Wildenhues + + * tests/torture.at (srcdir): Fix quoting. + + Do not pass top_srcdir to configure scripts in testsuite. + * tests/autotest.at (srcdir propagation): Copy install-sh to + source tree. + (my only test): Drop setting of `top_srcdir'. + * tests/base.at (Input/Output): Likewise. + * tests/local.at (AT_CONFIGURE_AC): Copy install-sh, + config.guess, and config.sub to test source tree. + Drop AC_CONFIG_AUX_DIR setting. + (AT_CHECK_CONFIGURE): Drop setting of `top_srcdir'. + * tests/torture.at (Substitute a 2000-byte string): Drop + AC_CONFIG_AUX_DIR setting, copy install-sh to test source tree. + (Substitute a newline, datarootdir workaround): Likewise. + (Define a newline): Adjust for linenumber changes in configure.ac. + * tests/foreign.at (Libtool): Adjust comment to reflect changes. + + * tests/semantics.at (AC_PATH_PROGS_FEATURE_CHECK): Skip test + if `pwd` contains whitespace. + + Quote $abs_top_srcdir in tests. + * tests/local.at (AT_CHECK_PERL_SYNTAX): Likewise. + * tests/tools.at (Syntax of the shell scripts): Likewise. + + * tests/m4sh.at (LINENO): Quote $0. + + Fix testsuite program wrapper for whitespace in `pwd`. + The problem here is that the usual mantra is that command + variables can contain arguments, thus we cannot just escape + $AUTOCONF, $AUTOM4TE etc. The compromise is to put the + $top_builddir/tests directory early in $PATH, so that the + wrappers are found by their plain name. + * tests/wrapper.as: Put $testdir early in $PATH. + (AUTOCONF, AUTOHEADER, AUTOM4TE): Set to plain command names. + + Proper config.status --file/--header and $srcdir escaping. + * lib/autoconf/status.m4 (_AC_OUTPUT_MAIN_LOOP): Quote special + characters in $ac_file_inputs. + (_AC_OUTPUT_FILE, _AC_OUTPUT_HEADER): eval $ac_file_inputs + accordingly. + * tests/torture.at (datarootdir workaround): Adjust. + (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): Extend test. + + Fix Autotest for whitespace in `pwd`. + * lib/autotest/general.m4 (AT_INIT) + : + Quote $at_group_dir. + * tests/autotest.at (whitespace in absolute testdir): New test. + + * lib/autom4te.in: Quote @datadir@. + + Proper file name escaping in Autoconf programs and Perl modules. + This includes escaping of characters special to the shell + as well as special to Perl, e.g., leading `<' or `>'. + For example, when $file starts with `>', `open ">$file"' + wrongly tries to append to a different file. + * bin/autoconf.as: Fix quoting for autom4te options. + * lib/Autom4te/General.pm (shell_quote): New function, taken + from coreutils, written by Jim Meyering. + (mktmpdir): Use it. + * bin/autom4te.in (files_to_options, handle_m4): Use shell_quote + and open_quote. + * bin/autoreconf.in (parse_args): Likewise. + * bin/autoscan.in (main): Likewise. + * bin/autoupdate.in (main): Likewise. + * bin/autoheader.in: Likewise, fixing old insufficient escaping. + * bin/ifnames.in: Likewise, XFile usage fixes. + * tests/tools.at (autom4te and whitespace in file names): Extend + test. Test twice, with special characters allowed on w32, and the + rest. Test leading and trailing whitespace, for `open_quote'. + (autotools and whitespace in file names): New, analogous test. + Reported by Paul Eggert and Benoit Sigoure, additional suggestions + by Russ Allbery and Eric Blake. + + Sync from Automake. + * lib/Autom4te/Channels.pm, lib/Autom4te/Configure_ac.pm, + lib/Autom4te/Struct.pm, lib/Autom4te/XFile.pm: Likewise. + * lib/Autom4te/FileUtils.pm (open_quote): New function. + (update_file, contents): Use it. + + * Makefile.am (autom4te-update): Rewrite for git. + +2007-12-04 Ralf Wildenhues + + * doc/autoconf.texi (autom4te Invocation, Autom4te Cache): Fix typos. + + Fix copyright years. + * Makefile.am, doc/install.texi, lib/autoconf/fortran.m4, + lib/autoconf/lang.m4, lib/freeze.mk: Likewise. + +2007-12-04 Eric Blake + + Manually resync with gnulib, since 'make cvs-update' no longer works. + * build-aux/config.guess: New upstream version. + * build-aux/config.sub: Likewise. + + When using older automake, don't downgrade build-aux/texinfo.tex. + * configure.ac (AM_INIT_AUTOMAKE): Add no-texinfo.tex option. + * doc/Makefile.am (TEXINFO_TEX): Add. + +2007-11-27 Paul Eggert + + Fix AC_C_BIGENDIAN bug caused by new awk method of substitution. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Don't comment out the + #undef as this runs afoul of our new way of creating config.h. + Problem reported by Jim Meyering in + . + +2007-11-26 Ralf Wildenhues + + Fix autom4te for unusual characters in input file names. + * bin/autom4te.in (files_to_options): Quote active characters + for the shell. + * tests/tools.at (autom4te and white space in file names): + New test. + + * doc/autoconf.texi (Limitations of Usual Tools) : + Document that Tru64 awk always splits $0. + +2007-11-24 Stepan Kasal + + * lib/autotest/general.m4 (AT_INIT): Do not extract the + `#AT_STOP_...' line at the end of each test. + +2007-11-23 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): For awk line number + extraction script, ensure `$at_group' has a defined value + even for the empty set, and properly quote its usage inside + the awk script. + +2007-11-22 Ralf Wildenhues + + * doc/autoconf.texi (Shell Functions): New chapter. Document + IRIX sh $0 issue in functions, move content from ... + (Portable Shell): ... here. + (Shell Script Compiler): Note that shell functions are not + totally unportable any more. + +2007-11-22 Stepan Kasal + and Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): Exit awk script after + extracting the line numbers of the last needed test. + +2007-11-20 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT) : + Fix quoting. + +2007-11-19 Ralf Wildenhues + + Fix IRIX testsuite debugging failures: $0 in functions. + * lib/autotest/general.m4 (AT_INIT) : + Do not use $0 inside a function, as IRIX sh will set that to the + function name rather than the script invocation name. + +2007-11-19 Paolo Bonzini + and Ralf Wildenhues + + * lib/autotest/general.m4 (at_func_test): Use cached line numbers + to extract test scripts. + (AT_INIT): Extract and cache test script line numbers. + +2007-11-19 Ralf Wildenhues + + * lib/autotest/general.m4: Revert 2007-11-15 patch and + subsequent fixups; the awk -> here-document conversion trashes + performance too much with AIX sh. + +2007-11-18 Ralf Wildenhues + + * tests/local.at: Do not test m4, perl with AT_TESTED. + + Diagnose and guard against write errors dealing with config.status. + The general idea is this: all write failures from `configure' + writing `config.status' are indicated by $ac_write_error, which + is only checked at the end. This is safe because config.status + code is not executed before the file is complete. Other write + failures, be they inside config.status, or in sub shell/awk + scripts spawned from configure or config.status, typically need + earlier checking, as their results are used right afterwards. + * lib/autoconf/status.m4 (AC_OUTPUT): Initialize `ac_write_fail' + before writing config.status, check afterwards. + (_AC_OUTPUT_FILES_PREPARE, _AC_OUTPUT_FILE) + (_AC_OUTPUT_HEADERS_PREPARE,_AC_OUTPUT_CONFIG_STATUS): + Set `ac_write_error' for write failures to config.status. Barf + upon write failures to temporary files. + Adjust note about closing and reopening the here-document. + (_AC_OUTPUT_HEADER, _AC_OUTPUT_LINK, _AC_OUTPUT_COMMAND) + (_AC_OUTPUT_MAIN_LOOP): Likewise, adjust note about closing and + reopening the here-document. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Ensure `ac_write_error' does not escape into config.status. + Also, add a couple of code paths not yet exercised in the test + suite: a config file with input from stdin, and a config header + output to stdout. + Suggestion for catching write errors by Bruno Haible. + +2007-11-17 Ralf Wildenhues + + Avoid error with Tru64 awk and testsuite lines with many words. + * lib/autotest/general.m4 (AT_INIT): In the awk script that + reads the testsuite, set the field separator to an unusual value, + in order to not run over the limit of 199 fields. Tru64 4.0D awk + even splits the input if $i, i>0, was never accessed in the script. + + Revert 2007-10-17 change. + * TODO: Multiline args in config files and headers mean something + different and are not fixed, see + + Report by Stepan Kasal. + + * doc/autoconf.texi (Generic Programs): Fix typo. + +2007-11-16 Stepan Kasal + + AC_*_TOOL does not canonicalize the prefix + * doc/autoconf.texi (Generic Programs): Do not say that + the *_TOOL macros canonicalize, they simply use the `host_alias'. + +2007-11-16 Ralf Wildenhues + + Diagnose write errors in config.status instantiations. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE) + (_AC_OUTPUT_HEADER, _AC_OUTPUT_MAIN_LOOP): Bail out + on write errors. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Extend test to also check for some write error failures, using... + : ...this new macro. + Report by Bruno Haible. + + Indentation fixups. + * lib/autotest/general.m4 (AT_INIT) : Fix + indentation. + (_AT_CHECK): Use less indentation, to save space. + +2007-11-15 Ralf Wildenhues + + Add witness macro for @top_build_prefix@ substitution. + * lib/autoconf/status.m4 (_AC_HAVE_TOP_BUILD_PREFIX): New macro. + (_AC_OUTPUT_FILE): Mention it here. + +2007-11-15 Paolo Bonzini + and Ralf Wildenhues + + * lib/autotest/general.m4 (at_func_test): Remove. + (AT_INIT): Pre-extract test groups into separate files. + (AT_CLEANUP): Source pre-extracted file instead of calling at_func_test. + Remove at-test-source files together with the $at_group_dir. + * tests/autotest.at (Long test source lines): New test. + +2007-11-15 Ralf Wildenhues + + Shell functions and variables may share a namespace. + * doc/autoconf.texi (Portable Shell): Mention Solaris sh + limitation. + +2007-11-14 Paul Eggert + + * lib/autoconf/types.m4 (_AC_TYPE_LONG_LONG_SNIPPET): Make comment match + gnulib. + +2007-11-14 Ralf Wildenhues + + * lib/autoconf/status.m4: Fix a couple of comment typos. + + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Use $as_me, not $me. + +2007-11-13 Jim Meyering + + Clean up the rule to create "expr". + * tests/Makefile.am (expr): Don't redirect directly to target. + Redirect just once, not for each echo statement. + Use $@, not literal "expr". + +2007-11-13 Paul Eggert + + Don't worry about preprocessor when testing long long. + See: http://lists.gnu.org/archive/html/bug-gnulib/2007-11/msg00075.html + * doc/autoconf.texi (Preprocessor Arithmetic): New section. + (AC_TYPE_LONG_LONG_INT, AC_TYPE_UNSIGNED_LONG_LONG_INT): + These no longer check for preprocessor flaws. + * lib/autoconf/types.m4 (_AC_TYPE_LONG_LONG_SNIPPET): + Do not check for preprocessor flaws. + +2007-11-13 Jim Meyering + + Adapt dependencies, now that a version change doesn't modify configure.ac + * GNUmakefile: Remove "make clean" kludge. + * lib/m4sugar/Makefile.am (version.m4): Depend on Makefile, not + configure.ac. + Don't redirect directly to target. + Use $@, not literal "version.m4". + +2007-11-12 Ralf Wildenhues + + * doc/autoconf.texi (Making testsuite Scripts): Document + ":;{" shorthand as in previous patch. + +2007-11-12 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Document problem + with { ... } a bit more clearly. Suggest ":;{" as a shorthand + for the workaround. + * lib/m4sugar/Makefile.am (version.m4): Detect 'echo' failure. + Use ":;{" shorthand. + * tests/Makefile.am ($(srcdir)/package.m4): Likewise. + +2007-11-12 Jim Meyering + + Add more non-srcdir build support. + * GNUmakefile (dummy): Split a long line. + Add -v option to autoreconf invocation. + + Remove the autoreconf-provided INSTALL, so that we regenerate it. + * GNUmakefile (dummy): Remove INSTALL. + + Remove racy commands to build scripts in bin/ and tests/. + * man/Makefile.am (.x.1): Now that scripts in bin/ and tests/ + are guaranteed to be built, remove the rules that tried to build + them. Before, with a parallel build, these rules could lead to + two processes writing tests/wrapper.in concurrently. + + Build in man/ only *after* building in bin/ and tests/. + * Makefile.am (SUBDIRS): The man-page-creation process runs $(MAKE) + in both bin/ and tests/. + + Accommodate non-srcdir build-from-checkout. + * build-aux/git-version-gen: Require an additional parameter: $srcdir. + Use git's --git-dir=$srcdir/.git option. + Add quotes, in case tarball_version_file contains shell meta-characters. + * GNUmakefile (_curr-ver): Pass $(srcdir) to git-version-gen. + * configure.ac: Pass "." to git-version-gen. + + Avoid spurious test failures due to version skew. + * GNUmakefile (dummy): Run $(MAKE) clean after autoreconf -i. + +2007-11-12 Ralf Wildenhues + + Avoid warnings about conftest.dSYM directories on Mac OS X Leopard. + * lib/autoconf/general.m4 (_AC_LINK_IFELSE, _AC_RUN_IFELSE): + Remove conftest.dSYM directory. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT) + (_AC_LANG_PROGRAM_C_, _AC_FC_MAIN, __AC_FC_NAME_MANGLING): + Remove `conftest.*' recursively. + * lib/autoconf/lang.m4 (AC_LINK_IFELSE): Likewise. + * lib/autoconf/specific.m4 (_AC_SYS_LARGEFILE_MACRO_VALUE): + Likewise. + (_AC_COMPILER_OBJEXT_REJECT): Reject *.dSYM. + * THANKS: Update. + Report and analysis by Jeff Squyres and Peter O'Gorman. + +2007-11-12 Benoit Sigoure + + Fix typos in variable names. + * tests/semantics.at (test for AC_CHECK_LIB): s/at_m/ac_m/. + +2007-11-11 Benoit Sigoure + + Document that $((expression)) is not portable. + * doc/autoconf.texi (Shell Substitutions): Here. + +2007-11-10 Ralf Wildenhues + + Ignore configure --help* errors due to LINENO-impaired shells. + * tests/torture.at (Configuring subdirectories, Deep Package): + In the --help* tests in read-only trees, make `.' temporarily + writable again for the `stderr' file, and ignore errors due to + the attempt to write configure.lineno. + Report by Patrick Welche. + +2007-11-10 Jim Meyering + + Generate package.m4 in build-dir, not srcdir. + * tests/Makefile.am (package.m4): Adjust target. + Don't redirect directly to $@. + (CLEANFILES): Add package.m4. + ($(TESTSUITE)): Depend on just-built package.m4, not the one + in $(srcdir). + When running $(AUTOTEST), search "." before searching $(srcdir). + + Avoid a race condition that would make parallel "distclean" fail. + * tests/Makefile.am (distclean-generic): Replace the default, + automake-provided rule with an identical one, but with an additional + dependency on distclean-local. Simply adding the dependency would + cause automake not to emit the rule at all. + * BUGS: Building with -jN works, now. + + Distribute git-version-gen. + * Makefile.am (EXTRA_DIST): Add build-aux/git-version-gen, + since GNUmakefile is distributed, and requires it for dist* rules. + + Remove two more generated files from version control. + * INSTALL: Remove generated file. + * lib/autoscan/autoscan.list: Remove generated file. + +2007-11-09 Paul Eggert + + * GNUmakefile (PATH): Remove stray apostrophes; they become + part of PATH, which isn't wanted here. + +2007-11-09 Ralf Wildenhues + + New config files output variable `top_build_prefix'. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Substitute + `top_build_prefix'. + * doc/autoconf.texi (Preset Output Variables): Document it. + * NEWS: Update. + Report by Bob Friesenhahn. + + Avoid expr for arithmetic evaluation if the shell accepts $((...)). + * lib/autotest/general.m4 (AT_INIT) : New + function, to parametrize arithmetic with expr vs. the shell. + Use it where possible. + Suggestion by Benoit Sigoure. + +2007-11-03 Benoit Sigoure + + Adjust the documentation of autotest WRT atlocal. + * doc/autoconf.texi (Making testsuite Scripts): It is not necessary, + when using Automake, to write a rule to produce atlocal, since it's + an AC_CONFIG_FILES. Mention that atlocal.in needs to be + distributed, not atconfig.in. + +2007-11-04 Eric Blake + + Update list information. + * README: Mention new autoconf-commit list. + * doc/autoconf.texi (Introduction): Mention autoconf-commit list. + +2007-11-04 Ralf Wildenhues + + * lib/autoconf/functions.m4 (_AC_FUNC_MALLOC_IF): Fix comment typo. + + * lib/m4sugar/Makefile.am (version.m4): Another bash bug workaround. + + * build-aux/.gitignore: Ignore mkinstalldirs. + + * doc/autoconf.texi (autoreconf Invocation): Fix an underfull line. + +2007-11-03 Jim Meyering + + s/-/./ in snapshot version string: 2.61a-256-8b556 -> 2.61a.256-8b556 + * build-aux/git-version-gen: This syncs from coreutils. + + Adjust the build procedure so "make check" works reliably. + * README-hacking: Include an extra step between "make" and + "make check" to ensure that the latter passes. + + Use just-built tools, when possible. + * GNUmakefile (PATH): Set and export here, ... + (dummy): ... rather than here. + +2007-11-03 Ralf Wildenhues + and Andreas Schwab + + * tests/Makefile.am ($(srcdir)/package.m4): Work around bash + exit status bug. + +2007-11-03 Ralf Wildenhues + + * configure.ac (AC_PREREQ): Require version 2.60, for + AC_PROG_SED, AC_PROG_GREP. + +2007-11-02 Benoit Sigoure + and Jim Meyering + and Andreas Schwab + and Eric Blake + + Document a bug in GNU Bash with compound commands and redirections. + * doc/autoconf.texi (Limitations of Builtins): Mention that GNU + Bash doesn't properly set $? when `{ ... } >/bad' fails, and give + workaround. + +2007-11-03 Eric Blake + + Support m4 1.4.5 in testsuite. + * tests/torture.at (Define a newline): Exclude line numbers in + error message. + Reported by Ralf Wildenhues. + +2007-11-03 Jim Meyering + + Remove automake-provided files from version control. + * build-aux/elisp-comp: Remove file. + * build-aux/install-sh: Remove file. + * build-aux/missing: Remove file. + * build-aux/mdate-sh: Remove file. + * build-aux/.gitignore: New file. + Suggestion from Ralf Wildenhues. + +2007-11-03 Eric Blake + + Adjust version comparison to account for git snapshot numbers. + * lib/m4sugar/m4sugar.m4 (_m4_version_unletter): Also treat - as a + component separator. + * doc/autoconf.texi (Number processing Macros) + : Document this change. + * tests/m4sugar.at (m4@&t@_version_compare): Test it. + +2007-10-30 Bruno Haible + + * lib/autoconf/types.m4 (_AC_TYPE_LONG_LONG_SNIPPET): New macro, + extracted from AC_TYPE_LONG_LONG_INT and AC_TYPE_UNSIGNED_LONG_LONG_INT. + (AC_TYPE_LONG_LONG_INT, AC_TYPE_UNSIGNED_LONG_LONG_INT): Use it. + Fixes problem with Sun C 5.[0-8] in 32-bit mode, reported in + + Suggested by Paul Eggert. + +2007-10-28 Jim Meyering + + * README-hacking: Autoconf, Automake, and Perl are required to build. + List Gzip and Tar separately. Suggested by Ralf Wildenhues. + +2007-10-28 Jim Meyering + + README-hacking: Recommend running autoreconf -vi. + * GNUmakefile (dummy): Use autoreconf -i, with appropriate PATH, + so that we use just-built tools when they're available. + Suggestions from Ralf Wildenhues. + +2007-10-28 Jim Meyering + + Make inter-release --version output more useful. + + Now, each unofficial build has a version "number" like 2.61a-19-58dd, + which indicates that it is built using the 19th change set + (in _some_ repository) following the "v2.61a" tag, and that 58dd + is a prefix of the commit SHA1. + * build-aux/git-version-gen: New file. + * configure.ac: Run it to set the version. + (AM_INIT_AUTOMAKE): Don't check NEWS here. + * Makefile.am (dist-hook): Arrange so that .version appears only + in distribution tarballs, never in a checked-out repository. + * .gitignore: Add .version here, too. Just in case. + * tests/Makefile.am ($(srcdir)/package.m4): Depend on Makefile, + not configure.ac, now that the version number changes automatically. + + Ensure that $(VERSION) is up to date for dist-related targets. + * GNUmakefile: Arrange to rerun autoconf, if the version reported by + git-version-gen doesn't match $(VERSION), but only for dist targets. + +2007-10-27 Ralf Wildenhues + + Fix `Deep Package' failure with a configure script early in PATH + * tests/torture.at (Deep Package): Add `.' early in PATH. + Report by Jim Meyering. + +2007-10-27 Jim Meyering + + Remove all generated files from version control. + * aclocal.m4: Remove. + * configure: Remove. + * Makefile.in: Remove, along with all other Makefile.in in subdirs. + * .gitignore: Add aclocal.m4, configure and Makefile.in. Sort. + * README-hacking: New file: how to build from just-checked-out sources. + +2007-10-23 Eric Blake + + Improve corner case of m4_expand. + * lib/m4sugar/m4sugar.m4 (m4_expand, _m4_expand): Rewrite more + efficiently. + * tests/m4sh.at (AS@&t@_HELP_STRING): Test overquoted comma. + * doc/autoconf.texi (Evaluation Macros) : Update + documentation. + +2007-10-23 Paul Eggert + + * doc/make-stds.texi: Update from gnulib. + +2007-10-22 Paul Eggert + and Eric Blake + + * lib/autoconf/c.m4 (AC_C_RESTRICT): Work around Sun C++ compatibility + problem reported by Bruno Haible in + . + +2007-10-22 Eric Blake + + * doc/autoconf.texi (Particular Types): Mention bug in HP-UX 11.00 + preprocessor. + +2007-10-22 Paul Eggert + + Don't check for bug in HP-UX 11.00 cpp. + * lib/autoconf/types.m4 (AC_TYPE_UNSIGNED_LONG_LONG_INT): + Use -1ull rather than -1u, since that causes problems with gnulib; see + . + +2007-10-22 Ralf Wildenhues + + * tests/autotest.at (Backquote command substitution) + (Multiline backquote command substitution) + (Parenthetical command substitution) + (Multiline parenthetical command substitution): Fix typos in + test names. + +2007-10-21 Eric Blake + + * configure: Regenerate. + +2007-10-21 Ralf Wildenhues + + Fix config status generation with Tru64 ksh. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fix + escaping of backslash in here-documents. + + Fix `Deep Package' test failure on FreeBSD. + * tests/torture.at (Deep Package): Do not add `.' to $PATH + unnecessarily. Do not try running `/bin/sh configure' with a + configure script to be found in $PATH, if the shell does not do + this resolution. Fixes test failure on FreeBSD. + + Fix config header generation with AIX awk. + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS_PREPARE): In awk + script, use helper array D_is_set, as `" 0"' does not evaluate + to true for AIX awk. + +2007-10-21 Eric Blake + + * tests/autotest.at (Banners): Reinstate test, with typo + corrected. + +2007-10-20 Ralf Wildenhues + + * lib/autotest/general.m4 (Defaults): Validate input ranges ... + : ... using this new function. + * tests/autotest.at (Keywords and ranges): Test invalid ranges. + Test --list with ranges and keywords. + (Banners): Remove one now-failing test. + +2007-10-20 Eric Blake + + Fix testsuite --list subset. + * lib/autotest/general.m4 (AT_INIT) : Swap newlines + back to spaces, before listing subset of tests. + Reported by Ralf Wildenhues. + +2007-10-19 Eric Blake + + s/parenthesis/parentheses/ where appropriate. + * doc/autoconf.texi: Fix typos. + * lib/m4sugar/m4sugar.m4: Likewise. + Reported by Ralf Wildenhues. + + Document m4_expand limitation. + * lib/m4sugar/m4sugar.m4 (m4_expand): Mention problem with + unbalanced parse. + * doc/autoconf.texi (Pretty Help Strings, Evaluation Macros) + (Writing Testsuites): Mention limitations inherited from + m4_expand. + + Improve AT_BANNER handling. + * lib/autotest/general.m4 (BANNERS): New named diversion. + (TESTS_END): Diversion no longer used. + (AT_INIT) : Factor all banners into a + shell function, which prints only as needed, using an associative + array of banner text from a special diversion. + : No longer need awk to find banners. + : Banners are no longer processed by main driver loop, so + we no longer need case statement. + (AT_BANNER): Rewrite to populate new diversion. + (AT_SETUP): Each test invokes its own banner. No output is needed + to the TESTS diversion. + * doc/autoconf.texi (Writing Testsuites): Document slight + semantics change. + * tests/autotest.at (AT_BANNERS): Enhance test. + * NEWS: Document AT_BANNER. + + Document and test AT_BANNER. + * doc/autoconf.texi (Writing Testsuites): Document AT_BANNER. + * tests/autotest.at (AT_CHECK_EGREP): Share between tests. + (AT_CHECK_BANNERS): New test. + + Doc touchups. + * doc/autoconf.texi (Text processing Macros) + : Clarify and fix typos. + +2007-10-18 Eric Blake + + Ignore `make dist' changelogs in testsuite.log. + * lib/autotest/general.m4 (AT_INIT) : Prune + directories matching AT_PACKAGE_TARNAME-*. + + Fix AT_TESTED, AT_KEYWORDS. + * lib/m4sugar/m4sugar.m4 (m4_append_uniq): Warn if separator + occurs in string, as duplicates may be added. + (_m4_append_uniq): New helper macro. + (m4_append_uniq_w): New macro. + * lib/autotest/general.m4 (AT_TESTED, AT_KEYWORDS): Fix + duplication bug by using new macro. + (AT_INIT) : Restore newline separators. Invoke tested + programs with stdin redirected, so programs that don't + understand --version won't try to behave interactively. + * tests/autotest.at (Tested programs): Catch this bug. + * tests/m4sugar.at (m4@&t@_append): Test new macro. + * tests/local.at (AT_TESTED): Add m4, perl. + * doc/autoconf.texi (Text processing Macros): Document + m4_append_uniq_w, and update text on m4_append. + * NEWS: Document the addition. + +2007-10-17 Eric Blake + + Function cleanup. + * lib/autotest/general.m4 (_AT_CREATE_DEBUGGING_SCRIPT): Convert + from m4 macro... + (AT_INIT) : ...to shell + function. + (AT_INIT): Defer function declarations until after --help, + --version. Format functions consistently, trying to fit in 80 + columns. + (TEST_FUNCTIONS): Based on recent changes, rename... + (TEST_GROUPS): ...to this. + + Reject FreeBSD m4. + * m4/m4.m4 (AC_PROG_GNU_M4): Also check for frozen file support. + * configure: Regenerate. + Reported by Bob Friesenhahn. + + Test recent additions. + * tests/m4sugar.at (m4@&t@_map, m4@&t@_combine) + (m4@&t_max and m4@&t_min): New tests. + * doc/autoconf.texi (Evaluation Macros) : Enhance + description. + +2007-10-17 Ralf Wildenhues + + * TODO: multiline args in config files and headers work now. + + Autotest: do not use shell functions for individual tests. + * lib/autotest/general.m4 (AT_INIT) : Merely + extract the source test source, do not invoke it. + (AT_SETUP, AT_CLEANUP): Source test code outside shell function. + * tests/autotest.at (Fallacy): Actually let the inner suite fail, + expect exit status of 1. + * tests/autotest.at (Skip): New test, for bogus zsh exit status. + + * lib/autotest/general.m4 (at_func_test): Fix test extraction + script. + +2007-10-17 Eric Blake + + Fix m4_combine for empty suffix list. + * lib/m4sugar/m4sugar.m4 (m4_combine): Check for suffix list. + * doc/autoconf.texi (Text processing Macros): Document this. + + Add m4_combine, based on Libtool's lt_combine. + * lib/m4sugar/m4sugar.m4 (m4_combine): New macro. + * doc/autoconf.texi (Text processing Macros): Document it. + * NEWS: Likewise. + +2007-10-16 Ralf Wildenhues + + Fix `configure --help=recursive' in unconfigured/read-only trees. + * lib/m4sugar/m4sh.m4 (_AS_LN_S_PREPARE): Avoid errors when `.' + is not writable, use 'cp -p' in this case, in the hope that it + will not actually be needed. Still try removing files, in case + of other write errors. + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): For ac_confdir, + use $as_myself, not $0. + (_AC_INIT_HELP): For --help=recursive, if the subdir does not + exist, try again in the the source tree. This change assumes + that the subpackage configure script is capable of running + --help=recursive in the source tree. + * tests/torture.at (Configuring subdirectories, Deep Package): + Adjust tests to expose both issues, also try invocation as + `sh configure ...' and plain `configure ...' with PATH adjusted. + * NEWS, THANKS: Update. + Report by Hans Ulrich Niedermann. + +2007-10-16 Paul Eggert + + Check for 64-bit int errors in HP-UX 10.20 preprocessor. + Problem reported by H.Merijn Brand in + . + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): + (AC_TYPE_UNSIGNED_LONG_LONG_INT): + Check that preprocessor handles 64-bit ints, too. + +2007-10-16 Eric Blake + + m4_map is a looping construct. + * lib/m4sugar/m4sugar.m4 (m4_map, _m4_map, m4_map_sep): Move. + + Fix m4_map, and add some more utility macros. + * lib/m4sugar/m4sugar.m4 (m4_apply, m4_count, m4_dquote_elt) + (m4_echo, m4_make_list): New documented macros. + (_m4_quote, _m4_shift2): New helper macros. + (m4_map): Change semantics to allow calling macro without + arguments. + (m4_map_sep): Likewise. Also change semantics to quote separator, + to match m4_join and m4_append. + (m4_version_unletter): Fix use of m4_map. + * doc/autoconf.texi (Evaluation Macros): Document m4_apply, + m4_count, m4_dquote_elt, m4_echo, m4_make_list. + (Text processing Macros): Mention m4_dquote as a faster + alternative to joining with commas. + (Looping constructs): Document m4_map, m4_map_sep. + * NEWS: Mention new macros. + + A few more m4sugar improvements, to benefit libtool. + * lib/m4sugar/m4sugar.m4 (m4_bpatsubsts, _m4_shiftn): Reduce size + of expansion by avoiding extra uses of $@. + (m4_shiftn): Avoid extra dnl, and forbid shifting by 0. + (_m4_cdr): New helper macro. + (_m4_map, m4_map_sep): Use it to reduce size of expansion. + (_m4_shift3): New helper macro. + (_m4_foreach): Swap argument order, and use new macro to reduce + size of expansion. + * doc/autoconf.texi (Looping constructs) : Mention that + count must be positive. + + * doc/autoconf.texi (Evaluation Macros) : Fix typo. + Reported by Ralf Wildenhues. + +2007-10-15 Ralf Wildenhues + + * doc/autoconf.texi (Portable Shell): Improve description of zsh + 4.x function subshell bug with exit and trap. + +2007-10-15 Eric Blake + + Enhance AS_HELP_STRING. + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Don't expand arguments, + and reduce number of expansions. + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): Rework to use m4_expand, + and to take indent and wrap column numbers. + * tests/m4sh.at (AS@&t@_HELP_STRING): Update the test. + * doc/autoconf.texi (Pretty Help Strings): Document details about + arguments. + (Text processing Macros): Minor tweaks. + * NEWS: Document this change. + + Fix 2007-10-03 regression with AT_SETUP([a, b]). + * lib/m4sugar/m4sugar.m4 (m4_expand): New macro. + (m4_text_box): Use it. + * lib/autotest/general.m4 (AT_SETUP): Use it. + * lib/m4sugar/m4sh.m4 (_AS_RUN): Use it. + * tests/autotest.at (AT_CHECK_AT_TITLE_CHAR): Test this. + * NEWS: Revert caveat about semantics change on comma. + * doc/autoconf.texi (Evaluation Macros): Document m4_expand. + +2007-10-13 Eric Blake + + Change m4_join to match libtool's ltsugar semantics. + * lib/m4sugar/m4sugar.m4 (m4_join): Just define this, not defun. + Ignore empty arguments, using... + (_m4_join): ...this new helper. + * tests/m4sugar.at (m4@&t@_join): New test. + * doc/autoconf.texi (Text processing Macros): Document new + semantics of m4_join. + + Make AC_PREREQ faster and more robust. + * lib/m4sugar/m4sugar.m4 (m4_ignore, m4_unquote): New macros. + (m4_version_prereq): Inline constant expansions. + (m4_list_cmp): Reduce number of expansions, by avoiding m4_case. + Rewrite in terms of [] list, not () list. + (_m4_list_cmp, _m4_version_unletter): New helper macros. + (m4_version_unletter): Write wrapper around new implementation to + preserve old semantics. + (m4_version_compare): Pass correct type of list, and avoid + overhead of flattening expressions too early. + (m4_do): Move to be near other quoting macros. + (m4_max, m4_min): Always result in decimal output. + * doc/autoconf.texi (Looping constructs): Add m4_car, m4_cdr. + Move m4_do... + (Evaluation Macros): ...here. Add m4_ignore, m4_unquote. + (Text processing Macros): Move m4_version_compare... + (Number processing Macros): ...to this new node; document m4_cmp, + m4_list_cmp, m4_sign, m4_max, m4_min. + * tests/m4sugar.at (m4@&t@_version_compare): Enhance test, to pick + up on bugs fixed by this patch. + * NEWS: Document new macros. + +2007-10-12 Eric Blake + + * doc/autoconf.texi (Text processing Macros): Fix bad merge. + (Reporting Messages): Fix underfull hbox. + + Some more m4sugar documentation. + * lib/m4sugar/m4sugar.m4: Clean up macro order. + * doc/autoconf.texi (Programming in M4): Lighten the warning on + using m4sugar; it is stabilizing and useful. + (Redefined M4 Macros): Touch up wording on M4 builtins; sort. Add + m4_divert, m4_undivert, __file__, __line__, __oline__. + (Diagnostics): New node, documenting m4_assert, m4_errprintn, + m4_fatal, m4_location, m4_warn. + (Diversion support): New node, documenting m4_divert_push, + m4_divert_pop, m4_divert_text, m4_divert_once. + (Text processing Macros): Sort. Add m4_flatten, m4_join, + m4_newline, m4_strip, m4_text_box, m4_text_wrap. + (Reporting Messages): Mark AC_DIAGNOSE, AC_WARNING, and AC_FATAL + as obsolescent. + (Printing Messages): Change cross-reference. + + Document interaction of recent m4_append change with Libtool HEAD. + * lib/m4sugar/m4sugar.m4 (m4_append): Document semantics change. + (m4_append_uniq): Add new parameters, based on lt_append_uniq. + * tests/m4sugar.at (m4@&t@_append): New test. + * NEWS: Document semantics change. + * doc/autoconf.texi (Text processing Macros): Likewise. + + s/AC_VERSION/AC_AUTOCONF_VERSION/. + * doc/autoconf.texi (Versioning): Change the name. + * NEWS: Likewise. + * lib/autoconf/general.m4 (AC_AUTOCONF_VERSION): Likewise. + * tests/tools.at (autoconf: AC_AUTOCONF_VERSION): Likewise. + Suggested by Ralf Wildenhues. + + Namespace cleanup. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE) + (_AC_OUTPUT_HEADERS_PREPARE): Convert here-doc delimiters into + autoconf namespace. + * doc/autoconf.texi (Programming in M4sugar, Forbidden Patterns) + (Programming in M4sh, Macro Names): Beef up description of + namespaces reserved for autoconf. + * configure: Regenerate. + +2007-10-12 Eric Blake + and Paolo Bonzini + + Speed up execution of subset of testsuite. + * lib/autotest/general.m4 (TEST_FUNCTIONS): New diversion. + (AT_INIT) : New shell function. + (AT_INIT) : New variable, set to absolute $as_myself. + (AT_INIT) New variable, names file that holds + current test function definition. + (AT_SETUP): Start the shell function at_func_test_#, into the + TEST_FUNCTIONS diversion. + (AT_CLEANUP): End the shell function. Simplify the TESTS + diversion to invoke the function. + +2007-10-11 Ralf Wildenhues + + * .gitignore: Ignore tags and TAGS files. + +2007-10-11 Eric Blake + + Config header generation followup. + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Check for raw newlines, + which won't work with the preprocessor nor with the awk + implementation. + * tests/torture.at (Define a newline): Test raw newline detection, + removing the XFAIL. + * doc/autoconf.texi (Defining Symbols): Document recent change to + allow backslash-newline. + * THANKS: Update. + +2007-10-11 Ralf Wildenhues + + * lib/autotest/general.m4: Put function braces in separate line. + +2007-10-10 Eric Blake + + Avoid some overhead from m4_defn and m4_popdef. + * lib/m4sugar/m4sugar.m4 (m4_defn, m4_popdef, m4_undefine): Only + pass on first argument, since we are documented that way. + (m4_for, m4_append_uniq, m4_text_wrap): Optimize out defined-ness + check where it is safe to do so. + (m4_append): Likewise, and quote the separator. + (m4_text_box): Likewise, and avoid regex, also be robust to + expansion and quadrigraphs. + + Another AC_DEFINE speedup. + * lib/autoconf/general.m4 (AC_DEFINE_TRACE): Move parameter + elision... + (_AC_DEFINE_Q): ...here, and only do it once. + * lib/autoconf/functions.m4 (AC_CHECK_FUNCS): Avoid overquoting. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Fix m4_defn overquoting + introduced 2007-10-05. + + Whitespace cleanup. + * lib/autoconf/general.m4: Use consistent indentation. + * configure: Regenerate. + + * NEWS: Announce recent round of speed optimizations. + +2007-10-10 Ralf Wildenhues + + * NEWS: Announce shell function usage in Autotest. + +2007-10-10 Eric Blake + and Paul Eggert + + Reduce number of forks at startup. + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Speed up NLS + sanitization. + * configure: Regenerate. + +2007-10-10 Ralf Wildenhues + and Paul Eggert + + Use awk for config header generation. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fix comments. + (_AC_OUTPUT_HEADERS_PREPARE): New macro. Rewrite of the config + header machinery for use with awk and placement outside the main + config.status instantiation loop. Retain multi-line defines + through backslash-newline combinations, do not split the script + any more. + (_AC_OUTPUT_HEADER): Simplify accordingly, use $AWK. + (_AC_OUTPUT_MAIN_LOOP): Call _AC_OUTPUT_HEADERS_PREPARE if + needed. + (AC_OUTPUT_MAKE_DEFS): Remove backslash-newline combinations + from define values. + * NEWS: Update. + * tests/torture.at (#define header templates): Extend test by + several more cases: white space before and after `#', macros + with parameters in config.hin and as defines, multi-line macro + values. + (Torturing config.status): Use a define value twice the length + in order to exercise the awk literal string limit. + (Substitute and define special characters): Also try special + delimiter, to exercise the special-case code. + Suggestion by Eric Lemings. + +2007-10-10 Ralf Wildenhues + + * tests/local.at (AT_COPYRIGHT): Bump copyright years. + +2007-10-09 Eric Blake + + Improve header of bin/autoconf. + * lib/m4sugar/m4sh.m4 (AS_INIT): Add a 'generated from' notice. + * lib/autoconf/general.m4 (_AC_INIT_NOTICE): Override new notice + from M4sh. + * bin/autoconf.as: Put copyright up front in generated file. + + * bin/autoconf.as (exit_missing_arg): Font-lock tweak. + +2007-10-09 Ralf Wildenhues + + * doc/install.texi (Basic Installation): Document `uninstall'. + * INSTALL: Regenerate. + Suggestion by Roberto Bagnara. + +2007-10-08 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): V7 awk had 'index'. + + Adjust doc. to match latest gnulib. + * build-aux/texinfo.tex: Sync from gnulib. + * doc/standards.texi: Likewise. + * doc/autoconf.texi (Copying This Manual): Rename to "GNU Free + Documentation License" and remove the subsection. This simplifies + the manual a bit and is more like what other GNU projects do + nowadays. + +2007-10-08 Eric Blake + + Use recent changes. + * configure: Regenerate. + + Fix regression in m4_text_wrap from 2007-10-05. + * lib/m4sugar/m4sugar.m4 (m4_max, m4_min): New macros. + (m4_sign): Sort. + (m4_text_wrap): Fix off-by-one error in rewrite from m4_for to + m4_format. + * lib/autotest/general.m4 (AT_SETUP): Avoid negative width. + * tests/autotest.at (Long test title, Longer test title): Test + this fix, beyond what AS_HELP_STRING already tests. + + Avoid m4 warnings on bad m4_format usage. + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Use %*s, in case width + evaulates to 0. + * lib/autotest/general.m4 (AT_SETUP): Likewise; also ensure that + enough arguments are provided. + +2007-10-06 Paolo Bonzini + + * doc/autoconf.texi (Shell portability): Document shell function + portability. + +2007-10-06 Paolo Bonzini + + * lib/autotest/general.m4 (AT_INIT): Add at_func_diff_devnull, + at_func_check_skip, at_func_check_status, at_func_filter_trace, + at_func_log_failure shell functions. Use test -s to avoid + useless diff invocations. + (at_func_check_newline): Renamed from at_check_newline. + (AT_SETUP): Define AT_captured_files to empty. + (AT_DIFF_STDERR(*), AT_DIFF_STDOUT(*)): New, extracted from _AT_CHECK. + (_AT_CHECK): Replace m4_case with m4_ifdef/m4_indir. Use all + the shell functions. + +2007-10-05 Paul Eggert + + Don't assume "." is writeable, for commands like "autoconf --version". + * lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): Use a + different heuristic instead, one that doesn't rely on creating + files. + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Handle "///" + correctly. + +2007-10-05 Jim Meyering + + Avoid makeinfo warnings. + * doc/autoconf.texi (Redefined M4 Macros): Add a `,' after @xref. + (Looping constructs): Add ` ' after @defmac'd name, m4_do. + +2007-10-05 Eric Blake + + Resolve Python issue 1676135 regarding configure directory args. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Strip trailing + slashes from directory arguments. + * tests/base.at (configure directories): New test. + * doc/autoconf.texi (Installation Directory Variables): Document + the change. + * NEWS: Likewise. + * THANKS: Update. + Reported by Björn Lindqvist. + + Provide better short-circuiting operation. + * lib/m4sugar/m4sugar.m4 (m4_cond, m4_newline): New macros. + (m4_text_wrap): Use it. Also avoid useless m4_for. + * lib/m4sugar/m4sh.m4 (_AS_QUOTE_IFELSE, AS_LITERAL_IF): Use + new macro. + (_AS_IDENTIFIER_IF): Likewise, and fix bug when $1 is [,]. + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): Use new macros + to avoid regexps. + * doc/autoconf.texi (Redefined M4 Macros): Expand m4_if + documentation. Sort m4_mkstemp, m4_undefine. Move m4_ifndef... + (Conditional constructs): ...here, to new section. Also document + m4_cond, m4_ifval, m4_n, m4_ifvaln, m4_ifset, m4_case, m4_bmatch, + m4_bpatsubsts, and m4_default. + (Looping constructs): Document m4_shiftn, m4_shift2, m4_shift3, + m4_do. + +2007-10-04 Eric Blake + + Fix recent testsuite failures. + * lib/autotest/general.m4 (AT_INIT, AT_SETUP): Double-quote text + that must not be re-expanded after AS_ESCAPE. + * lib/m4sugar/m4sh.m4 (_AS_IDENTIFIER_IF): Don't expand $1 when + checking if it is an identifier. + + Whitespace cleanup. + * lib/autotest/general.m4 (_AT_CREATE_DEBUGGING_SCRIPT): Avoid + leading whitespace, as it caused space-tab in testsuite. + (AT_INIT): Avoid trailing newlines in testsuite. + + One more round of m4_foreach_w speedups. + * lib/m4sugar/m4sugar.m4 (m4_flatten): Only use regex if newline + is present. + (_m4_split): Avoid useless expansions inside definition. Move + argument defaulting... + (m4_split): ...here. Change alternate quote to something less + likely to appear in $1. Also, special case space as regexp... + (m4_foreach_w): ...to avoid regexp on single-term list. + (m4_default, m4_defn, m4_popdef, m4_undefine, _m4_foreach): Avoid + useless expansions inside definition. + * tests/m4sugar.at (m4@&t@_split): Add tests. + +2007-10-04 Paolo Bonzini + + * general.m4 (AT_INIT): Add at_check_newline function. + (_AT_DECIDE_TRACEABLE): Include at_traceon test, use shell function. + (_AT_CHECK): Don't use at_trace_this. + +2007-10-04 Paolo Bonzini + + Fix previous commit. + * lib/autotest/general.m4 (AT_LINE): Fix regex. + +2007-10-04 Eric Blake + + Speed up building testsuites. + * lib/autotest/general.m4 (AT_LINE): Only use regex when file + changed since last time. Use simpler regex. + +2007-10-03 Eric Blake + + Optimize checking for identifiers. + * lib/m4sugar/m4sh.m4 (AS_IDENTIFIER_IF, _AS_IDENTIFIER_IF): New + macros, more efficient than regex on m4_re_word. + * lib/autoconf/general.m4 (AC_SUBST, AC_DEFINE_TRACE_LITERAL): + Rewrite in terms of new macro. As a side-effect, AC_DEFINE can + now use @&t@. + * configure: Regenerate. + + Remove some XFAILs, and make AT_SETUP output line up. + * lib/autotest/general.m4 (AT_SETUP): Only expand description + once; thereafter, use its expansion, properly quoted. + * tests/autotest.at (AT_CHECK_AT_TITLE): Also check macro + expansion with arguments, and check for aligned output. + (AT_CHECK_AT_TITLE_CHAR): Remove XFAILs for tests that now pass. + Add a test for macros with parameters. + * NEWS: Document the semantics change. + * tests/base.at: Fix test titles containing commas. + * tests/compile.at: Likewise. + * tests/tools.at: Likewise. + * tests/torture.at: Likewise. + + Another round of regex avoidance. + * lib/m4sugar/m4sugar.m4 (m4_cr_alnum, m4_cr_all) + (_m4_define_cr_not, m4_cr_not_letters, m4_cr_not_LETTERS) + (m4_cr_not_Letters, m4_cr_not_digits, m4_cr_not_alnum) + (m4_cr_not_symbols1, m4_cr_not_symbols2): New macros, implementing + character ranges useful in m4_translit. + (m4_toupper, m4_tolower): Optimize the constant portion of + definition. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Also reject @S|@ because it + creates $, and reject [] thanks to AS_TR_SH rewrite. + (AS_TR_SH, AS_TR_CPP): Use just translit, not bpatsubst. + (AS_ESCAPE): Factor... + (_AS_ESCAPE): ...into new macro, with second argument required. + Avoid regex in common case. + (_AS_QUOTE): Use new macro. + + Whitespace cleanup. + * lib/autoconf/types.m4: Avoid space-tab. + * lib/m4sugar/m4sh.m4: Use tab consistently. + +2007-10-03 Paul Eggert + + * lib/m4sugar/m4sugar.m4 (m4_shift2, m4_shift3): New macros. + (m4_shiftn): Remove no-longer-needed optimization. Perhaps we + should remove m4_shiftn entirely? + (m4_case, b4_bmatch, m4_map_sep, m4_bpatsubsts, m4_join): + Prefer m4_shift2 and m4_shift3 to m4_shiftn. + * lib/autoconf/lang.m4 (_AC_LANG_DISPATCH): Likewise. + * lib/m4sugar/m4sh.m4 (AS_CASE, AS_IF): Likewise. + * tests/autotest.at (AT_CHECK_AT_TEST): Likewise. + +2007-10-03 Eric Blake + + Comment touchups. + * lib/m4sugar/m4sugar.m4: Grammar fixes in comments. + +2007-10-02 Eric Blake + + Optimize appending text. + * lib/m4sugar/m4sugar.m4 (m4_append_uniq): Use index, not regular + expressions. + + Optimize recursion. + * lib/m4sugar/m4sugar.m4 (m4_shiftn): This macro is called in a + lot of hot spots; optimize it for 2 and 3 shifts. + + Optimize AC_PREREQ and other m4sugar numerics. + * lib/m4sugar/m4sugar.m4 (m4_sign): Write with m4_eval. + (m4_cmp): Compare arbitrary expressions, without overflow. + (m4_version_unletter): Also recognize capital letters. + (m4_version_compare): Avoid regex when splitting version number + string. + +2007-10-01 Eric Blake + + Once again, reject IRIX m4. + * m4/m4.m4 (AC_PROG_GNU_M4): Use indir builtin to root out non-GNU + implementations that ignore --trace. + * configure: Regenerate. + Reported by Ralf Wildenhues. + + Fix regression in AC_DEFINE([macro(with_arg)]). + * lib/autoconf/general.m4 (AC_DEFINE_TRACE): Don't chop off close + quotes with a careless m4_substr. + +2007-09-30 Eric Blake + + Allow nameless iteration. + * lib/m4sugar/m4sugar.m4 (m4_for, _m4_for): Access variable + indirectly. + * tests/m4sugar.at (myvar): Test this. + +2007-09-29 Eric Blake + + Speed optimization: avoid m4 regex when other algorithms work. + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Rewrite without regex. + (_AS_QUOTE_IFELSE): Likewise. + * lib/m4sugar/m4sugar.m4 (m4_strip): Reduce from 3 to 2 regex. + (m4_bpatsubsts): Split... + (_m4_bpatsubsts): ...so that recursion can avoid patsubst on empty + regex. + (_m4_divert()): Define, to avoid m4 warning on `m4_divert'. + (m4_qlen): Optimize on short strings, to avoid regex. + (m4_sign): Avoid regex, and fix bug with `01' and `-0'. + * lib/autoconf/general.m4 (AC_CACHE_VAL): Rewrite without regex. + (AC_DEFINE_TRACE): Likewise. + +2007-09-28 Eric Blake + + Oops - my earlier 'optimization' caused a regression. + * tests/local.at (AT_CHECK_M4): Fix typo. + +2007-09-27 Eric Blake + and Ralf Wildenhues + + Catch even more common AC_CACHE_VAL mistakes. + * lib/autoconf/general.m4 (AC_CACHE_VAL): Warn if cache variable + lacks '_cv_', or if AC_SUBST appears in body. + * tests/base.at (AC_CACHE_CHECK): Test this change. + +2007-09-27 Stepan Kasal + and Eric Blake + + Autotest no longer caters to Ultrix redirection limitation. + * doc/autoconf.texi (Writing testsuite.at): Remove the + limitation that the first parameter of AT_CHECK cannot + contain redirection. + (File Descriptors): Mention that Ultrix limitation is no longer a + show-stopper in modern code. + * tests/local.at (AT_CHECK_M4): Fix for cases when the fourth + parameter is `stderr' or `experr'. Optimize if it was `ignore'. + * lib/autotest/general.m4 (AT_CHECK): Update comment. + +2007-09-27 Eric Blake + + Squelch changeword in m4sugar. + * lib/m4sugar/m4sugar.m4 (changeword): Disable this experimental + feature of m4 1.4.x. + + Configure whitespace touchups. + * lib/autoconf/general.m4 (_AC_INIT_HELP): Fix alignment of + installation directories, and avoid TAB, in configure --help + output. + * configure.ac: Avoid extra trailing newline. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Avoid space-tab. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Avoid TAB in + config.status --help output. + * configure: Regenerate. + + Fix underquotation in AS_HELP_STRING. + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): Don't underquote lhs + argument. + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Don't underquote + first-prefix argument. + * tests/m4sh.at (AS@&t@_HELP_STRING): Test this fix. + * NEWS: Document AS_HELP_STRING fix. + + Autotest formatting touchups. + * lib/autotest/general.m4 (HELP_TUNING): Avoid TAB in terminal + output. + (PATH): Simplify computation of new PATH. + +2007-09-26 Eric Blake + + Fix testsuite breakage in last patch. + * tests/autotest.at (AT_CHECK_AT_TITLE): Properly quote the + font-lock fix. + * tests/torture.at (@%:@define header templates): Rename, so that + output lines up correctly. + + More font-lock happiness. + * tests/autotest.at (AT_CHECK_AT_TITLE_CHAR): Clean up font + confusion. + +2007-09-25 Eric Blake + + Typo fixes. + * lib/autoconf/general.m4 (AC_SUBST): Fix typo in comment. + * lib/m4sugar/m4sh.m4 (AS_VAR_PUSHDEF): Likewise. + + Improve documentation of M4 parameter expansion. + * doc/autoconf.texi (Quoting and Parameters): New section. + (Quotation and Nested Macros): Improve wording. + + Improve C99 detection. + * lib/autoconf/c.m4 (_AC_PROG_CC_C99): Add support for HP cc, and + avoid deprecation warning with icc. + * THANKS: Update. + Reported by Ted Bullock. + +2007-09-24 Jim Meyering + + Whenever possible, use the vertical bar as sed delimiter. + * lib/autoconf/functions.m4 (GETLOADAVG_LIBS) [AC_FUNC_GETLOADAVG]: + Use "|", not "!". + * lib/autoconf/status.m4 (_AC_SRCDIRS) [ac_top_builddir_sub]: + [ac_dir_suffix]: Use "|", not "," as sed delimiter. + * tests/mktests.sh (as_me): Likewise. + * lib/freeze.mk (check-forbidden-patterns): Likewise. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Likewise. + * configure: Regenerate. + * doc/autoconf.texi (Shell Substitutions): Use "|", not "," in examples. + * lib/autotest/general.m4 (AT_INIT): Use "|", not "&" as sed delimiter + in the : -> $PATH_SEPARATOR transformation of $AUTOTEST_PATH. + This is fine, as long as $PATH_SEPARATOR doesn't contain "|". + +2007-09-22 Jim Meyering + + Add a comment. + * lib/autoconf/headers.m4 (HAVE_STDBOOL_H): Document the + 2004-05-31 change also with a comment in the code. + +2007-09-20 Eric Blake + + More contribution housekeeping. + * THANKS: Sort. + * AUTHORS: Sort, reflect recent assignment from Helge Deller. + + Ignore additional files, when copying cross-repository. + * .gitignore: Ignore CVS directories, emacs edits. + * .cvsignore: Ignore .git directory, emacs edits. + +2007-09-15 Eric Blake + + Provide AC_VERSION, not m4_AUTOCONF_VERSION. + * doc/autoconf.texi (Text processing Macros): Remove mention of + m4_AUTOCONF_VERSION, and leave m4_PACKAGE_VERSION undocumented + once again. + (Notices): Move AC_PREREQ... + (Versioning): ...to this new section, alongside the new AC_VERSION + alias for the undocumented m4_PACKAGE_VERSION. + * lib/m4sugar/m4sugar.m4 (m4_AUTOCONF_VERSION): Revert change. + * lib/autoconf/general.m4 (AC_VERSION): New macro. + * NEWS: Update to match this rename. + * tests/m4sugar.at (m4@&t@_version_compare): Remove tests of + m4_PACKAGE_VERSION. + * tests/tools.at (autoconf: AC_VERSION): New test. + Suggested by Paolo Bonzini and Benoit Sigoure. + +2007-09-14 Eric Blake + + Prepare for conversion to git. + * doc/.cvsignore: Avoid multiple listings on one line. + * bin/.cvsignore: Likewise. + * .gitignore, bin/.gitignore, config/.gitignore, doc/.gitignore, + lib/.gitignore, lib/Autom4te/.gitignore, lib/autoconf/.gitignore, + lib/autoscan/.gitignore, lib/autotest/.gitignore, + lib/emacs/.gitignore, lib/m4sugar/.gitignore, man/.gitignore, + tests/.gitignore: New files, identical to .cvsignore counterpart. + +2007-09-13 Eric Blake + + Editing eye-candy. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Restore + font-lock balance. + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): Likewise. + * lib/autoconf/general.m4 (_AC_DO_ECHO): Likewise. + * configure: Regenerate. + + Clean up 'make dist' of previous patch. + * tests/Makefile.am (EXTRA_DIST): Distribute mktests.stamp. + (CLEANFILES): Don't clean the stamp, since we distribute the + generated files pre-built. + (MAINTAINERCLEANFILES): Clean it here instead. + * tests/Makefile.in: Regenerate. + + Avoid parallel 'make check' issue. + * tests/Makefile.am (mktests.stamp): New witness. + (TESTSUITE_GENERATED_AT): Use it. + (CLEANFILES): Clean the witness. + * tests/.cvsignore (mktests.stamp): Ignore the witness. + + Document another awk pitfall. + * doc/autoconf.texi (Limitations of Usual Tools) : Document + limitation of field variables in END. + Reported by Gary V. Vaughan. + + * AUTHORS: Add missing entries. + +2007-09-12 Eric Blake + + Publish m4_ifndef, m4_version_compare, m4_AUTOCONF_VERSION. + * doc/autoconf.texi (Text processing Macros): Document + m4_version_compare, m4_AUTOCONF_VERSION, m4_PACKAGE_VERSION. + (Redefined M4 Macros): Document m4_ifndef. + * lib/m4sugar/m4sugar.m4 (m4_AUTOCONF_VERSION): New macro; we + can't obsolete m4_PACKAGE_VERSION at this time since Autoconf 1.10 + used it while it was undocumented. + * NEWS: Document this change. + * lib/m4sugar/Makefile.am (version.m4): Update copyright dates. + * lib/m4sugar/Makefile.in: Regenerate. + * tests/m4sugar.at (m4@&t@_version_compare): New test. + Reported by Bruno Haible. + + * doc/autoconf.texi (Generic Compiler Characteristics): Add + missing index entries. + +2007-09-11 Eric Blake + + Centralize all system extensions checks. + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Inline code + from AC_AIX, AC_GNU_SOURCE, AC_MINIX. Add Interix support. + (AC_AIX, AC_GNU_SOURCE, AC_MINIX): Obsolete, and point to + AC_USE_SYSTEM_EXTENSIONS. + (AC_ISC_POSIX): Obsolete, and point to AC_SEARCH_LIBS. + (AC_XENIX_DIR, AC_IRIX_SUN): Promote proper quoting in AU_DEFUN. + * doc/autoconf.texi (Posix Variants): Reword this section, + emphasizing that AC_USE_SYSTEM_EXTENSIONS is the preferred method, + rather than a series of system-specific checks. + (Obsolete Macros): Add AC_AIX, AC_GNU_SOURCE, AC_ISC_POSIX, + AC_MINIX. + * NEWS: Document this change. + * THANKS: Update. + Reported by Martin Koeppe. + +2007-09-08 Eric Blake + + Clean up obsolete macros references. + * doc/autoconf.texi: Add anchors to support better + cross-referencing. + (Particular Structures): Move obsolete macros descriptions... + (External Software): Likewise. + (Package Options): Likewise. + (Obsolete Macros): ...to here. Add cross-references to + documentation on replacements. + * NEWS: Mention that these macros have been obsolete for a while + now: AC_STRUCT_ST_BLKSIZE AC_STRUCT_ST_RDEV AC_WITH AC_ENABLE. + + Improve M4 path searching during configure. + * lib/autoconf/programs.m4 (AC_PATH_PROGS_FEATURE_CHECK): New + macro. + (_AC_PATH_PROG_FEATURE_CHECK): Rename... + (_AC_PATH_PROGS_FEATURE_CHECK): ...to this, add defaulted action + parameter, and kill side effects. + (_AC_PROG_GREP, AC_PROG_SED): Adjust callers. + (_AC_FEATURE_CHECK_LENGTH): Kill extra whitespace. + * m4/m4.m4 (AC_PROG_GNU_M4): Don't stop searching until working m4 + is found. + (AC_PATH_PROGS_FEATURE_CHECK): Add backwards compatibility hack to + allow bootstrapping with autoconf 2.61. + * configure.ac (M4): AC_PROG_GNU_M4 now exits on failure. + * configure: Regenerate. + * doc/autoconf.texi (Generic Programs): Document new macro. + * tests/mktests.sh (au_exclude_script): Exclude auto-testing new + macro. + * tests/semantics.at (AC_PATH_PROGS_FEATURE_CHECK): New test. + * NEWS: Document the change. + * THANKS: Update. + Reported by Hans Aberg. + + * doc/autoconf.texi (Generic Programs): Fix typo. + +2007-09-06 Eric Blake + + * doc/autoconf.texi (Generic Programs): Use $PATH_SEPARATOR, not + :, and make it clear that optional @var{path} defaults to $PATH. + (Erlang Compiler and Interpreter): Likewise. + + Texinfo cleanup. + * doc/autoconf.texi: Avoid lines > 80 columns when possible. + Reword some paragraphs to avoid overfull, underfull hbox + warnings. Add index entries to avoid overfull vbox warnings. + +2007-09-05 Eric Blake + + * NEWS: Adjust wording for AC_CONFIG_LINKS. + Reported by Ralf Wildenhues. + +2007-09-03 Eric Blake + + * NEWS: Document fixes that have been applied since 2.61a. + + Housekeeping. + * THANKS: Update, and convert to UTF-8 encoding. + * AUTHORS: Likewise. + +2007-08-23 Ralf Wildenhues + + * lib/autoconf/general.m4 (AC_SITE_LOAD): Guard against file + names beginning with `-' again. + +2007-08-22 Stepan Kasal + Ralf Wildenhues + + * doc/autoconf.texi (Defining Directories): Mention + AM_CPPFLAGS, as the way to modify CPPFLAGS when using Automake. + +2007-08-21 Ralf Wildenhues + + * lib/autoconf/general.m4 (AC_SITE_LOAD): Do not overwrite "$@" + here, this macro is expanded by AC_INIT. Fixes 2.60 regression. + * tests/base.at (configure arguments): New test. + * THANKS: Update. + Report by Olaf Lenz. + + * lib/autoconf/general.m4 (_AC_ENABLE_IF): Expand macro + arguments in comment. + Report by Vincent Torri . + +2007-08-20 Benoit Sigoure + + * doc/autoconf.texi (File System Conventions): Index the proper + way of detecting absolute file names. + +2007-08-20 Ralf Wildenhues + + * build-aux/config.guess, build-aux/config.sub, + build-aux/elisp-comp, build-aux/install-sh, build-aux/mdate-sh, + build-aux/missing, build-aux/texinfo.tex, doc/fdl.texi, + doc/make-stds.texi, doc/standards.texi: Sync from gnulib. + * doc/autoconf.texi (GNU Free Documentation License): Adjust for + sectioning change in fdl.texi. + + * bin/autoconf.as: Update --version output to match current GCS. + * bin/autoheader.in: Likewise. + * bin/autom4te.in: Likewise. + * bin/autoreconf.in: Likewise. + * bin/autoscan.in: Likewise. + * bin/autoupdate.in: Likewise. + * bin/ifnames.in: Likewise. + +2007-08-18 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_LINK): Do not try to link a + file to itself if source and build trees coincide. + * tests/torture.at (AC_CONFIG_LINKS and identical files): New + test. + Report by Sebastian Freundt . + +2007-07-20 Paul Eggert + + Reword the copyright notices to match what's suggested in GPLv3. + In ChangeLog files, use more-permissive notice rather than GPL, as + per usual GNU standards these days. + +2007-07-13 Paul Eggert + + * doc/autoconf.texi (autoreconf Invocation): Document ACLOCAL_AMFLAGS + limitation reported by Leo Moisio in + . + +2007-07-03 Paul Eggert + + * COPYING: Update to GPLv3. All uses changed. + +2007-06-26 Ralf Wildenhues + and Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): sed -e '' + fails on AIX 5.3. + +2007-06-17 Noah Misch + + * lib/autotest/general.m4 (AT_INIT): Handle absolute `srcdir'. + * tests/autotest.at (srcdir propagation): Test absolute `srcdir' and + `srcdir' as subdirectory of `builddir'. + +2007-06-13 Noah Misch + + * lib/autotest/general.m4 (AT_INIT): Compute $srcdir correctly. + * tests/autotest.at (srcdir propagation): New test. + * THANKS: Update. + Reported by Mike Frysinger. + +2007-06-13 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): Set FPATH too. + Problem reported by Fred Kreek in + . + * doc/autoconf.texi (Special Shell Variables): Warn about FPATH. + (Macro Names, Defining Directories): Don't mention PATH as a name + for a fully qualified file name, as this usage violates the GNU + coding standards and we shouldn't recommend it. + + * lib/autotest/general.m4 (AT_INIT): Don't set PATH to the empty + string and then assume shell builtins like "test" will work. + +2007-06-12 Noah Misch + + * lib/autoconf/general.m4 (AC_SUBST): Raise a fatal error if VARIABLE is + not a valid shell variable name. + * tests/mktests.sh (ac_exclude_list): Add AC_ARG_VAR. + * tests/torture.at (AC_SUBST: variable name validation): New test. + Reported by Andreas Schwab. + +2007-06-04 Noah Misch + + * doc/autoconf.texi (AC_F77_MAIN): Give a specific usage example that + works with both C and C++. + +2007-06-03 Noah Misch , + Bruno Haible + + * lib/autoconf/c.m4 (AC_OPENMP): Use a simple loop instead of compiler + brand tests. + +2007-05-31 Paul Eggert + + * doc/autoconf.texi (Particular Types): Give example of use for + AC_TYPE_INT8_T etc. + +2007-05-29 Stepan Kasal + + * lib/autoconf/types.m4 (_AC_TYPE_UNSIGNED_INT): Fix a typo. + +2007-05-28 Paul Eggert + + * doc/autoconf.texi (Particular Types): AC_TYPE_INT8_T does not + define HAVE_INT8_T, and likewise for similar macros. + Problem reported by Patrick Welche in + . + +2007-05-25 Noah Misch + + * bin/Makefile.am ($(top_builddir)/bin/autom4te): New dependency. + +2007-05-21 Paul Eggert + + * lib/autoconf/c.m4 (AC_OPENMP): Don't echo --enable-openmp + choice, since that's what we do with --enable-largefile etc. + Redo indenting and assignments to simplify things a bit, and make + the parens work with Emacs. + + * doc/autoconf.texi (Generic Compiler Characteristics): Fix typo + in my previous change: AC_C_OPENMP -> AC_OPENMP. Reported by Bruno + Haible. + +2007-05-21 Noah Misch + + * lib/autoconf/c.m4 (AC_OPENMP): Simplify use of AC_ARG_ENABLE. + * tests/local.at (AT_CHECK_ENV): Exempt OPENMP_CFLAGS. + +2007-05-21 Bruno Haible + + * NEWS: Rename AC_C_OPENMP to AC_OPENMP. + * lib/autoconf/c.m4 (AC_OPENMP): Renamed from AC_C_OPENMP. + * doc/autoconf.texi (Generic Compiler Characteristics): Move + renamed AC_OPENMP documentation here, from "C compiler". + Mention C++ and Fortran. + +2007-05-21 Paul Eggert + + * doc/autoconf.texi (C Compiler): Tweak OpenMP documentation a bit. + +2007-05-21 Bruno Haible + + * NEWS: Mention AC_C_OPENMP. + * lib/autoconf/c.m4 (AC_C_OPENMP): New macro. + * doc/autoconf.texi (C Compiler): Document AC_C_OPENMP. + Based in part on Steven G. Johnson's investigations for the AX_OPENMP + macro in the Autoconf macro archive. + +2007-05-17 Ralf Wildenhues + + * bin/autom4te.in: Fix typos. + +2007-05-16 Noah Misch + + * bin/autoconf.as: Handle `-' just like other input files. + * bin/autom4te.in (parse_args): Pass `-' through. + (handle_output): Skip the forbidden token search if we read from stdin. + (up_to_date): Always treat stdin as out of date. + * tests/tools.at (autoconf: input from stdin): New test. + (autoconf: forbidden tokens, basic): Check a second `autoconf' run. + +2007-05-16 Stepan Kasal + + * tests/foreign.at tests/semantics.at, tests/tools.at: Remove + parameters for AT_CLEANUP. + * tests/local.at (AT_CHECK_AU_MACRO): Likewise. + +2007-05-14 Paul Eggert + + * NEWS: Document that AC_C_RESTRICT checks 'restrict' last. + * doc/autoconf.texi (C Compiler): Likewise. + +2007-05-14 Noah Misch + + * lib/autoconf/c.m4 (AC_C_RESTRICT): Check `restrict' last. + +2007-05-09 Stepan Kasal + + * doc/autoconf.texi: Direntry for "autoconf Invocation" + renamed to "autoconf-invocation" + + * doc/autoconf.texi (Caching Results): The CACHE-ID variable + in the examples should not use the internal "ac_" prefix. + +2007-05-05 Noah Misch + + * lib/autotest/general.m4 (_AT_NORMALIZE_TEST_GROUP_NUMBER): Use `eval'. + * doc/autoconf.texi ($@, case): Document Zsh limitations. + +2007-05-03 Stepan Kasal + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Put a.out first. + Reorganize the comments before and in the macro. + +2007-05-02 Stepan Kasal + + * lib/autoconf/lang.m4, lib/autoconf/c.m4, + lib/autoconf/fortran.m4, lib/autoconf/erlang.m4: Cleanup of + section titles and other comments; no code change. + +2007-05-01 Kevin Ryde + + * doc/autoconf.texi (Particular Programs): Typo + @acindex{AC_PROG_MKDIR_P} shouldn't have "AC" in that call. + +2007-04-30 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_SPY): Don't imply that + 'configure' will fail if the shell lacks proper support for shell + functions. Suggested by RMS. + +2007-04-29 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Correct the warning + about Solaris /bin/printf '%010000x' 123. Problem reported by + Bruno Haible. + +2007-04-28 Paul Eggert + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Don't look + for a.* when searching for executables, as this prevents users + from having files like a.c. Problem reported by Ralf Wildenhues in: + http://lists.gnu.org/archive/html/autoconf-patches/2007-04/msg00029.html + This fixes a problem introduced on 2000-12-19. + +2007-04-26 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Warn about Solaris + /bin/printf '%010000x' 123. Problem reported by Arto C. Nirkko + via Bruno Haible. + +2007-04-12 Paul Eggert + + * NEWS: Document recent changes to AC_CHECK_ALIGNOF, AC_CHECK_SIZEOF, + AC_CHECK_TYPE, AC_CHECK_TYPES. + * doc/autoconf.texi (Generic types): C types must be type-names + (the C terminology), not type-ids (the C++ term). C++ types + must not be anonymous. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW): Remove special case + for C++; this drops support for anonymous struct and union types, + which were problematic anyway. + * tests/semantics.at (AC_CHECK_HEADERS_NEW): Adjust test to work even + for C++. + +2007-04-12 Jim Meyering + + * doc/autoconf.texi (Libraries): Typo fix: insert missing "in". + +2007-04-12 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_LINK): Fix AC_CONFIG_LINKS + to prefer a link source from the build tree, if it exists. + Report by Pallav Gupta . + +2007-04-11 Paul Eggert + + * doc/autoconf.texi (Generic Types): Document the restrictions + on types imposed by AC_CHECK_TYPE, AC_CHECK_TYPES. + (Generic Compiler Characteristics): AC_CHECK_SIZEOF now works + with objects too. Document the restrictions on its use. + Document the restrictions on AC_CHECK_ALIGNOF's type argument. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW): + For C, just try sizeof (TYPE) and sizeof ((TYPE)); if the former + works but the latter doesn't, then it's a valid type. + This lets people use function types and so forth. + For C++ there doesn't seem to be a simple solution, so leave it alone. + (AC_CHECK_SIZEOF): Allow argument to be a variable. + (AC_CHECK_SIZEOF, AC_CHECK_ALIGNOF): Don't bother to invoke + AC_CHECK_TYPE; that wasn't documented or necessary. + +2007-04-11 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_LINK_IFELSE): Skip AS_TEST_X + when cross-compiling. + +2007-04-11 Stepan Kasal + + * doc/autoconf.texi (External Software): Fix a typo in the + previous change. + +2007-04-11 Ralf Wildenhues + + * doc/autoconf.texi (External Software, Package Options): + Fix ambiguous wording. Report by Reuben Thomas . + +2007-04-06 Paul Eggert + + * doc/autoconf.texi (Particular Types): AC_C_LONG_DOUBLE is now + obsolescent. Suggested by Bruno Haible. + * NEWS: Document this. + +2007-03-29 Paul Eggert + + * doc/autoconf.texi (Here-Documents, Limitations of Builtins): + (Limitations of Usual Tools): Don't say "older" if Solaris 10 by + default still has the problem. Problem reported by Bruce Korb. + +2007-03-28 Stepan Kasal + and Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Fix a + comment in the generated config.status. + +2007-03-27 Stepan Kasal + + * lib/autoconf/status.m4 (AC_CONFIG_SUBDIRS): Update comment. + +2007-03-26 Paul Eggert + + * doc/autoconf.texi (Shellology): Rework treatment of the 'test' + command and case statements to make it a bit clearer and describe + more pitfalls. + +2007-03-23 Paul Eggert + + * doc/autoconf.texi (C Compiler): Mention that AC_PROG_CC_C99 also + checks for unsigned long long int. + +2007-03-19 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Warn about other + nonstandard grep R.E. escape sequences. + +2007-03-17 Jim Meyering + + * doc/autoconf.texi: Adjust grammar around use of "heuristics". + (Limitations of Usual Tools): Also list \< and \>, and mention that + HP-UX's grep, like the one from Solaris, does not support that syntax. + +2007-03-09 Stepan Kasal + + * doc/autoconf.texi (Specifying Names): `--host' does not + change the build type. + +2007-03-05 Paul Eggert + + * doc/autoconf.texi (C Compiler): Warn that AC_C_BIGENDIAN + suggests AC_CONFIG_HEADERS. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Warn if not using + AC_CONFIG_HEADERS. Problem reported by + Peter O'Gorman. + +2007-02-28 Paul Eggert + + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Fix typo "__LITLE_ENDIAN__". + Problem reported by Paolo Bonzini in: + http://lists.gnu.org/archive/html/autoconf-patches/2007-02/msg00024.html + * tests/semantics.at (AC_C_BIGENDIAN): Don't reject hosts that have + universal binaries. Problem reported by Elias Pipping. + +2007-02-27 Paul Eggert + + * NEWS: AC_C_BIGENDIAN now supports universal binaries a la Mac OS X. + * doc/autoconf.texi (C Compiler): Document this. There is a new + extra argument ACTION-IF-UNIVERSAL. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Implement this. + Add support for Solaris-style _LITTLE_ENDIAN and _BIG_ENDIAN. + Reindent for sanity's sake. + +2007-02-24 Eric Blake + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Update + copyright. + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + (_AT_DECIDE_TRACEABLE): Fix syntax highlighting. + +2007-02-13 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): With --clean, return exit + status of rm so we know when it failed. + If cleaning of test dir failed before running the test, warn. + Output the line separator in verbose mode before the warning + to make clear the warning belongs to the following test. + +2007-02-08 Paul Eggert + + * doc/autoconf.texi (Parentheses): Mention problem with (( in + shells. + +2007-02-07 Ralf Wildenhues + and Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fix quoting + errors introduced in last change. + +2007-02-07 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Prefer \r to + an actual carriage return. Use "ac_cr" to contain the actual + carriage return. + * doc/autoconf.texi (Limitations of Usual Tools): Document problem + with traditional Awk and begin. + * tests/torture.at (Limitations of Builtins): Document the problem + with Bash 2.03 printf. + (Substitute and define special characters): + Remove trailing white space. Work around a bug in Solaris 8 /bin/bash. + +2007-02-06 Ralf Menzel (tiny change) + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Redirect + input from /dev/null in awk test, so even Solaris /usr/bin/awk + will not wait for input with a script containing only a BEGIN + rule. + +2007-02-03 Paul Eggert + + * doc/autoconf.texi (Introduction, Why GNU M4): Clarify M4 version + requirements. + * README: Likewise. + +2007-02-02 Eric Blake + + * NEWS: Update copyright. + + * m4/m4.m4 (AC_PROG_GNU_M4): Reject M4 1.4 through 1.4.4 as + broken. + * configure.ac: Update error message. + * NEWS: Note that M4 1.4.5 or later is now a hard dependency. + Reported by Gary Vaughan and Jim Meyering, and problem analyzed + by Stepan Kasal: + http://lists.gnu.org/archive/html/bug-autoconf/2006-11/msg00025.html + +2007-01-31 Eric Blake + + * THANKS (people): Update. + +2007-01-28 Paul Eggert + + * doc/autoconf.texi (Shellology): pdksh 5.2.14 is still the + latest version. + (Shell Substitutions): Note problems with @{var:=value} etc. + Add a new section for problems with @{#var} etc. Problem noted + by Ralf Wildenhues. See: + http://lists.gnu.org/archive/html/libtool-patches/2005-01/msg00157.html + +2007-01-23 Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Also + AC_SUBST([MKDIR_P]), so that Automake < 1.10 will pick up its + trace, if a package uses AC_PROG_MKDIR_P explicitly. The actual + substitution will still be done by the special code. + Report by Jim Meyering. + + * doc/autoconf.texi (File System Conventions): Mention that + $PATH_SEPARATOR is for the build system only. + Report by Keith Marshall. + +2007-01-19 Ralf Wildenhues + + * doc/autoconf.texi (Setting Output Variables): Mention that + all non-NUL characters are ok in substituted values. + * lib/autoconf/status.m4 (_AC_SED_CMD_LIMIT): Fix comment typo. + (_AC_OUTPUT_FILES_PREPARE): Test and use backslash escaping of + carriage return for $AWK, needed for BSD awk. + * tests/torture.at (Substitute and define special characters): + Test all 8 bit non-NUL characters. + Report against Automake by Patrick Welche. + +2007-01-15 Stepan Kasal + + * doc/autoconf.texi: Direntry for "autoconf Invocation" renamed. + +2007-01-11 Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_PROG_SED): When closing a pipe + early on the reader side, drop stderr of the input to avoid + `broken pipe' error output; this may happen even with shell + builtin `echo' of some bash versions. Reports by Ian Macdonald + and Sam Sexton . + +2007-01-10 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Use newlines to + separate items of `ac_user_opts', to avoid long lines. + (_AC_INIT_PARSE_ENABLE2, _AC_ENABLE_IF_ACTION): Adjust. + +2007-01-08 Ralf Wildenhues + + * doc/autoconf.texi: Fix some typos. + +2007-01-05 Paul Eggert + + Fix some wording problems noted by Paolo Bonzini in: + http://lists.gnu.org/archive/html/autoconf-patches/2007-01/msg00077.html + * doc/autoconf.texi (Signed Overflow Examples): Give more + discussion about the allow_superuser_privileges example, + and change it a bit to make things clearer. + (Optimization and Wraparound): Clarify whether the compiler + will generate an infinite loop for the example derived from + Autoconf's mktime test. + (Signed Overflow Advice): Say that -ftrapv is meant for debugging. + Also, clarify unsigned multiplication overflow. + +2007-01-04 Eric Blake + + * bin/Makefile.am (RELEASE_YEAR): New macro. + (edit): Use it to supply correct copyright year to scripts. + * bin/autoconf.as (version): Use it. + * bin/autoheader.in ($version): Likewise. + * bin/autom4te.in ($version): Likewise. + * bin/autoreconf.in ($version): Likewise. + * bin/autoscan.in ($version): Likewise. + * bin/autoupdate.in ($version): Likewise. + * bin/ifnames.in ($version): Likewise. + +2007-01-02 Paul Eggert + + * doc/autoconf.texi (Integer Overflow): Revised based on today's + feedback. The most important changes document what happens when + you convert an out-of-range value to a signed integer type, and + say that (sum < a) != (b < 0) reliably detects overflow when sum = + a + b. + + * doc/autoconf.texi (Integer Overflow): Greatly expand and + rewrite, taking notions from the recent discussion on the gcc and + autoconf mailing lists; please see + http://lists.gnu.org/archive/html/autoconf-patches/2006-12/msg00091.html + and follow the many links. + (Integer Overflow Basics, Signed Overflow Examples): + (Optimization and Wraparound, Signed Overflow Advice): + (Signed Integer Division): New sections. + +2006-12-28 Steven G. Johnson + + * lib/autoconf/general.m4 (AC_DEFINE_TRACE): Don't include + preprocessor macro arguments in traced name. + * doc/autoconf.texi (Defining symbols): Document longstanding + support for AC_DEFINE-ing macros with arguments, and document + behavior when the same variable has multiple AC_DEFINEs. + * lib/autoconf/fortran.m4 (_AC_FC_WRAPPERS): Revert to the + old implementation which AC_DEFINEs the FC_FUNC and FC_FUNC_ + macros directly, giving much shorter and simpler code. + +2006-12-28 Malcolm Purvis (trivial change) + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Insert a + space before "$ac_configure_args" to prevent a 'config.status + --recheck' failure if ac_configure_args doesn't contain a leading + space. This works around a problem with the XEmacs configure.ac, + which uses the (undocumented) ac_configure_args variable + inconsistently with Autoconf. + +2006-12-22 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_MKTIME): + Include , and use its INT_MAX to rewrite the + j loop so that it does not overflow 'int'. Problem reported by + Ralf Wildenhues in + . + Play it safe by shifting left by 1 rather than multiplying by 2, + as GCC is less likely to optimize this away when the value + is signed (when it assumes overflow leads to undefined behavior). + Also, don't assume time_t uses two's complement. + +2006-12-20 Ralf Wildenhues + + * tests/torture.at (Substitute a 2000-byte string): Avoid using + a 10kB long (multi-line) string literal, OpenServer 5.0.7 ksh + dumps core on it. Report by Tim Rice. + +2006-12-18 Steven G. Johnson + + * lib/autoconf/general.m4 (AC_ARG_ENABLE): Print help about + --disable-option-checking to --help output even when + AC_PRESERVE_HELP_ORDER is not used. + (_AC_INIT_PARSE_ENABLE2): Print warnings using actual --enable or + --with argument, rather than argument with [-.] replaced by + underscores. + * NEWS: Fix typo in previous change; the news was in the + wrong section. + +2006-12-18 Paul Eggert + + * NEWS: Warnings are now generated by default for unknown + --enable-* and --with-* options. + * doc/autoconf.texi (Option Checking): Renamed from + (Configure Option Checking). Tighten up the wording a bit. + (External Software, Package Options): Cross-reference to Option + Checking, and use this to shorten our section. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Prefer test -n + "$x" to test "x$foo" != x. + * lib/autoconf/status.m4 (AC_OUTPUT): Likewise. + Don't warn if $enable_option_checking is "no". + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Initialize + ac_unrecognized_opts to the empty string. + Don't echo the unrecognized opts, as this might mishandle + backslashes or leading -. + (AC_PRESERVE_HELP_ORDER): Put the --disable-option-checking + usage next to the other --disable-FEATURE options in the + help string. + +2006-12-18 Steven G. Johnson + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS, _AC_INIT_PARSE_ARGS): + (_AC_INIT_PARSE_ENABLE2, _AC_INIT_HELP, _AC_ENABLE_IF): + Print warning for unrecognized --with and --enable options + (AC_DISABLE_OPTION_CHECKING): New macro to disable warnings. + * lib/autoconf/status.m4 (AC_CONFIG_SUBDIRS, _AC_OUTPUT_SUBDIRS): + Disable option checking when subdirs are configured. + (AC_OUTPUT): If warnings are enabled, print warning about + unrecognized --with and --enable options at the end of + the configure output (as well as at the beginning). + * doc/autoconf.texi (Option Checking): New node. + Document new option warning functionality. + +2006-12-16 Eric Blake + + * configure.ac (AC_INIT): Bump version, since 2.61a is released. + * NEWS: Start news for current version. + +2006-12-15 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): + Define HAVE_GETMNTENT to 1, not to the empty string. + Problem originally reported by Jochen Friedrich in + . + + This change prompted by a problem report by Andrey Simonenko in + . + * doc/autoconf.texi (Defining Symbols): AC_DEFINE works for + object-like macros only, in the traditional portable character + set. + * lib/autoconf/general.m4 (AC_DEFINE_TRACE_LITERAL): + Warn about attempts to define things that are not identifiers. + * lib/autoconf/fortran.m4 (_AC_FC_WRAPPERS): Rewrite to avoid + awful hack that AC_DEFINEd macro names containing parentheses. + +2006-12-12 Paul Eggert + + * doc/autoconf.texi: Undo some of the 2006-12-10 change. It was + too drastic, even if Texinfo in theory requires it for info mode. + + (config.status Invocation): Renamed back from Recreating a + Configuration). + (Obsolete config.status Use): Renamed back from Obsolete Recreation. + (Autoconf 2.13): Renamed back from 20th-century Autoconf 2. + +2006-12-11 Paul Eggert + + * NEWS: Version 2.61a. + +2006-12-11 Paul Eggert + and Ralf Wildenhues + + * NEWS: Document changes with echo and printf, and the lack + of limits on the total size of multi-line values of substituted + variables, and the AC_FUNC_FSEEKO fix. + +2006-12-10 Paul Eggert + + * doc/autoconf.texi (Writing Autoconf Input): Renamed from + Writing configure.ac. + (Autoconf Input Layout): Renamed from configure.ac Layout. + (Recreating a Configuration): Renamed from config.status Invocation. + (Obsolete Recreation): Renamed from Obsolete config.status Use. + (acconfig Header): Renamed from acconfig.h. + (20th-century Autoconf 2): Renamed from Autoconf 2.13. + (Writing Testsuites): Renamed from Writing testsuite.at. + (Autom4te Cache): Renamed from autom4te.cache. + + * BUGS: Remove mention of VPATH problem, since it's now documented + not to be a bug in the Autoconf build procedure itself, but rather + a problem with the proprietary `make' programs. + + * doc/autoconf.texi (Build Directories): Add a cross reference + to VPATH and Make. + + * build-aux/config.guess, build-aux/config.sub, build-aux/texinfo.tex: + * doc/standards.texi: Sync from gnulib. + + * man/autoconf.1, man/autoheader.1, man/autom4te.1, man/autoreconf.1: + * man/autoscan.1, man/autoupdate.1, man/config.guess.1: + * man/config.sub.1, man/ifnames.1: Remove from CVS, since they're + generated automatically. + +2006-12-06 Paul Eggert + + * lib/autoconf/c.m4 (_AC_PROG_CC_C89): Also try -xc99=all, for Sun + C 5.8 on Solaris 10. Using -xc99=all rather than -xc99 bypasses + the buggy -xc99 option of Forte Developer 7 C on Solaris 9. + +2006-12-07 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Drop the + `CEOF$ac_eof' special marker, the awk script cannot contain a + line matching `^CEOF', so this is not needed any more. + * tests/torture.at (Substitute a newline): Expose the `%!_!# ' + special marker in the test. + +2006-12-06 Stepan Kasal + + * tests/tools.at (autom4te preselections): Use `find -newer'; + remove one of the sleeps. + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ENABLE): Make it + more readable, using ... + (_AC_INIT_PARSE_ENABLE2): ... this new helper macro. + + * doc/autoconf.texi (autoheader Invocation): Do not double- + quote the parameter of `AH_BOTTOM' in the example. + +2006-12-05 Stepan Kasal + + * doc/autoconf.texi (Configuration Headers): Remove the + example with multiple input files. + (autoheader Invocation): Encourage `AH_BOTTOM', discouraging + multiple input files. + +2006-12-05 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): When + creating the awk substitution script, handle one input line at a + time, so that the maximum length of a substituted (multi-line) + value is not limited by the size of the sed pattern space. + The trade-off is a slightly repetitive sed script. + * doc/autoconf.texi (Limitations of Usual Tools): Branch labels + can only have up to 7 characters, due to Solaris 10 /bin/sed. + * tests/torture.at (Substitute a 2000-byte string): Increase the + test with several long lines, they should not be caught by sed + limits any more. + + * tests/tools.at (autom4te preselections): New test, to flag + entries missing from autom4te.cfg. + Report by David Byron . + + * tests/torture.at (Substitute a 2000-byte string): Actually use + AC_PROG_AWK, so the last change works as intended. + (Substitute and define special characters): Likewise. + (Substitute a newline): Likewise. + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Use `$AWK' + instead of `awk' consistently. + (_AC_OUTPUT_CONFIG_STATUS): Initialize $AWK. + * tests/torture.at (Torturing config.status): Test both the + result of AC_PROG_AWK and plain awk. + (Substitute a 2000-byte string): Likewise. + (Substitute and define special characters): Likewise. + (Substitute a newline): Likewise. + +2006-12-04 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_FSEEKO): Check that fseeko + can be assigned to a function pointer. Problem reported by + Peter Palfrader in . Based on + part of a patch by Ralf Wildenhues in that same bug report. + +2006-12-01 Paul Eggert + + * tests/mktests.sh (ac_exclude_list): Exclude AC_FUNC_SETVBUF_REVERSED. + * tests/semantics.at (AC_FUNC_SETVBUF_REVERSED): New test. + +2006-12-01 Eric Blake + + * lib/autoconf/c.m4 (AC_LANG_INT_SAVE): Avoid newline, to aid in + cross-compiling from cygwin to mingw. + Reported by Bob Rossi. This resurrects the 2000-11-30 patch to + aclang.m4, which was mistakenly removed in the 2001-09-17 patch + to lib/autoconf/c.m4. + +2006-12-01 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_ECHO_PREPARE): Use a longer test + string for more reliable failure. Wrap the entire test that + causes the broken Solaris printf to dump core, in a subshell, + so the segmentation fault message is reliably suppressed. + Fix shell expansion errors by using /usr/ucb/echo always; + avoid an error on systems without it by another subshell. + Avoid m4 expansion of `$1'. Set the zeroth argument of the + subshell-$as_echo to `as_echo', for better error message. + +2006-11-28 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_CACHE_DUMP): If `BASH_ARGV' or + `BASH_SOURCE' contain a newline, set them to empty, as they may + not be unset. + +2006-11-27 Paul Eggert + + Turn AC_FUNC_SETVBUF_REVERSED into a noop. It's been obsolete for + years and is too hard to maintain now. The last straw was + reported by Jerker Baeck in + . + * NEWS: AC_FUNC_SETVBUF_REVERSED is now obsolete. + * doc/autoconf.texi (Particular Functions): Move + AC_FUNC_SETVBUF_REVERSED from here... + (Obsolete Macros): ... to here. Say that it does nothing now. + * lib/autoconf/functions.m4 (AC_FUNC_SETVBUF_REVERSED): + Turn into (almost) a no-op. + + * lib/autoconf/c.m4 (AC_PROG_GCC_TRADITIONAL, AC_C_CONST): + (AC_C_VOLATILE): + Do not recommend via AN_FUNCTION, AN_IDENTIFIER, or AN_HEADER. + These macros are obsolescent and new applications shouldn't need them. + * lib/autoconf/functions.m4 (AC_FUNC_CLOSEDIR_VOID, AC_REPLACE_FNMATCH): + (AC_FUNC_GETLOADAVG, AC_FUNC_GETPGRP, AC_FUNC_MEMCMP): + (AC_FUNC_SELECT_ARGTYPES, AC_FUNC_SETPGRP, AC_FUNC_STAT, AC_FUNC_LSTAT): + (AC_FUNC_STRFTIME, AC_FUNC_SETVBUF_REVERSED, AC_FUNC_UTIME_NULL): + (AC_FUNC_VPRINTF): Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_DIRENT, AC_HEADER_STAT): + (AC_HEADER_STDC, AC_HEADER_SYS_WAIT, AC_HEADER_TIME): Likewise. + * lib/autoconf/types.m4 (AC_STRUCT_TM): Likewise. + + * doc/autoconf.texi (Setting Output Variables): Mention that + @VAR1@VAR2 has unspecified behavior. Problem reported by + Ralf Wildenhues. + * NEWS: Mention this. + + * Makefile.am: Put only a single '#' into the copyright notice, + so that it's also present in the output file. Standardize wording + in makefile copyright notices to match GNU coding standards. + * bin/Makefile.am: Likewise. + * doc/Makefile.am: Likewise. + * lib/Makefile.am: Likewise. + * lib/freeze.mk: Likewise. + * lib/autoconf/Makefile.am: Likewise. + * lib/autoscan/Makefile.am: Likewise. + * lib/autotest/Makefile.am: Likewise. + * lib/m4sugar/Makefile.am: Likewise. + * man/Makefile.am: Likewise. + * tests/Makefile.am: Likewise. + * lib/emacs/Makefile.am: Remove copyright notice; it's just a + one-line file. + +2006-11-27 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Fix error + in the sed script that mangles the awk script: delete up to the + first exclamation mark only. + * tests/torture.at (Substitute and define special characters): + Test '!' too. + +2006-11-26 Ralf Wildenhues + + Rewrite config files generation: avoid quadratic growth in + the number of substituted variables by using awk instead of sed + for the bulk of the substitutions. + * NEWS: Mention this. + * doc/autoconf.texi (Setting Output Variables): `|#_!!_#|' is also + forbidden in the output (and thus input) file. + * lib/autoconf/status.m4 (_AC_AWK_LITERAL_LIMIT): New macro. + (_AC_OUTPUT_FILES_PREPARE): Instead of several sed scripts, + generate just one large awk script for substitutions, + eliminating much of the earlier complexity, while adding some + new complexity. Only expand the substitution templates at + configure time, for smaller configure script size. If + _AC_SUBST_FILES are used, test 'awk' for working getline support + at config.status time. If absent, interpolate through the + shell. The awk script was written with much help + from Paolo Bonzini and Paul Eggert. + (_AC_SED_CMD_NUM, _AC_SED_DELIM_NUM, _AC_SED_FRAG): Removed. + (_AC_SED_FRAG_NUM): Likewise. + (_AC_SUBST_CMDS): Renamed from... + (_AC_SED_CMDS): ...this. + (_AC_OUTPUT_FILE): Use _AC_SUBST_CMDS. + * tests/torture.at (Substitute a 2000-byte string): Also + substitute a line with 1000 words, and a variable with several + long lines. + (Substitute and define special characters): Test awk special + characters, and put substitution input strings `@foo@' in the + output, to test that no recursion happens; test several other + combinations from Paolo Bonzini. + +2006-11-25 Paul Eggert + + * lib/autotest/general.m4 (AT_INIT): Undo recent changes + that replaced echo with AS_ECHO where this wasn't necessary. + Problem reportd by Ralf Wildenhues. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_PREPARE): Port to Solaris 7, + where "/usr/bin/printf '%s\n' S" dumps core if S is long. + This is Sun bug 4206210. Problem reportd by Ralf Wildenhues. + +2006-11-24 Ralf Wildenhues + + * lib/freeze.mk (GREP): Removed, no need to initialize this. + +2006-11-21 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Don't claim + that traditional Awk lacks 3-arg "split". It has it. + Mention that FS must be a single character, and a few other + 99-byte limits of traditional Awk. + Mention that if (i in a) doesn't work with traditional Awk. + +2006-11-18 Paul Eggert + + * tests/autotest.at (BSx641-newline in command): + (BS-BS-newline in command, BSx640-newline in command): + (Newline-CODE-BS-newline in command): + (Single-quote-BS-newline in command): + (Single-quote-newline-BS-newline in command): + Use printf '%s\n' instead of echo, for portability to hosts + where echo interprets backslashes. This will break on hosts + that lack printf, but for now let's assume all such hosts + are dead (if not, we should get reports of test failures). + +2006-11-17 Paul Eggert + + 'echo' has some portability problems, when given a first argument + with a leading '-', or when given any argument containing '\'. + Avoid using 'echo' in these cases. + * bin/Makefile.am $(bin_SCRIPTS): Rewrite to avoid 'echo' entirely. + * lib/autoconf/c.m4 (AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC): Likewise. + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * bin/autoconf.as: Use AS_ECHO rather than plain echo, when the + argument might be unportable. + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): Likewise. + * lib/autoconf/erlang.m4 (AC_LANG(Erlang)): Likewise. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): + (_AC_FC_LIBRARY_LDFLAGS): Likewise. + * lib/autoconf/functions.m4 (AC_FUNC_GETLOADAVG): Likewise. + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ENABLE, _AC_INIT_PREPARE): + (_AC_ARG_VAR_VALIDATE, AC_ARG_PROGRAM, _AC_MSG_LOG_CONFTEST): + (AC_RUN_LOG, _AC_RUN_IFELSE, _AC_LIBOBJS_NORMALIZE): Likewise. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Likewise. + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Likewise. + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): + (AC_PROG_MAKE_SET): Likewise. + * lib/autoconf/status.m4 (_AC_SRCDIRS, _AC_OUTPUT_HEADER): + (_AC_OUTPUT_SUBDIRS, _AC_OUTPUT_CONFIG_STATUS): Likewise. + * lib/autotest/general.m4 (_AT_CREATE_DEBUGGING_SCRIPT, AT_INIT): + (AT_CLEANUP, _AT_DECIDE_TRACEABLE, _AT_CHECK): Likewise. + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE, _AS_ECHO_UNQUOTED): + (_AS_BASENAME_SED, _AS_DIRNAME_SED, AS_MKDIR_P, AS_TMPDIR, AS_UNAME): + (AS_TR_SH, AS_TR_CPP, AS_VAR_GET): Likewise. + * bin/autoconf.as: Redo verbose flag implementation, as the old + scheme wouldn't work with AS_ECHO. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/autoconf/general.m4 (AC_MSG_RESULT, AC_MSG_RESULT_UNQUOTED): + Don't use ECHO_T, since ECHO_N is now reliable. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/autoconf/general.m4 (AC_ARG_PROGRAM): Use sed "$script" + rather than using a here-document to put the script into a file. + (_AC_DO_ECHO): Hoist the eval out of the echo, so that we can + use AS_ECHO. + * lib/m4sugar/m4sh.m4 (AS_VAR_GET): Likewise. + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Use + AS_ECHO_N rather than ECHO_N and ECHO_C. This doesn't fix any + bug, but we might as well stop using ECHO_N and ECHO_C internally. + * lib/autotest/general.m4 (AT_SETUP): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_ECHO_N): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): + (_AC_OUTPUT_MAIN_LOOP): Rework echo so that it has just one + operand, as AS_ECHO requires. Avoid double file name expansion. + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Invoke _AS_ECHO_PREPARE. + Don't set as_nl, since _AS_ECHO_PREPARE does that now. + (_AS_PREPARE): Comment that _AS_ECHO_N_PREPARE is just for user code. + (AS_ECHO, AS_ECHO_N, _AS_ECHO_PREPARE): New macros. + * tests/c.at (AC_PROG_CPP without warnings, AC_PROG_CPP via CC): + Double-quote strings that would otherwise contain M4 comments. + * tests/m4sh.at (AS_ECHO and AS_ECHO_N): New test. + + * configure.ac (AC_INIT): Bump to 2.61a. + * NEWS: Likewise. + +2006-11-17 Paul Eggert + + Version 2.61. + + * configure.ac (AC_INIT): Bump to 2.61. + * NEWS: Likewise. + + * tests/autotest.at (Macro with backslash in a test title): + Comment out for now, as this tests neither fails nor passes + reliably. Problem reported by Ralf Wildenhues. + +2006-11-16 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ENABLE): Fix some typos + in previous change, which caused test failures. + +2006-11-16 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Factor out + code for --enable, --disable, --with, and --without to... + (_AC_INIT_PARSE_ENABLE): ... a new macro. + * doc/autoconf.texi (Package Options): + * NEWS: Document that AC_ARG_ENABLE allows dots, too. + +2006-11-16 Paul Eggert + + Import these changes from config via gnulib: + + 2006-11-15 Ben Elliston + + From Josselin Mouette : + * build-aux/config.guess (SX-8:SUPER-UX:*:*): New. + + 2006-11-08 Ben Elliston + + * build-aux/config.guess (authenticamd:Interix*:[3456]*): Another AMD64. + + 2006-11-07 Steve Woodford + Ben Elliston + + * build-aux/config.guess (*:NetBSD:*:*): Handle sh5el arch. + * build-aux/config.sub (sh5el): New basic_machine. + + + Import this change from coreutils: + + 2006-02-13 Jim Meyering + + * GNUmakefile (all): Emit diagnostics to stderr, not stdout. + + + Import this change from gnustandards via gnulib: + + 2006-11-15 Karl Berry + + * standards.texi: core -> memory, throughout. + (CPU Portability): show correct example of calling write + on a char value; thanks to Paul Eggert for the code. + Both of these suggestions from Eugene Y. Vasserman. + + + Import these changes from texinfo via gnulib: + + 2006-11-08 Karl Berry + + * build-aux/texinfo.tex (\dopdfimage): look for png, jpg/jpeg/JPG, and + as well as pdf images, since they are supported in pdftex with + no further ado. + + 2006-11-05 Karl Berry + + * doc/texinfo.tex (Image Syntax): don't mention GIF any more. + +2006-11-13 Paul Eggert + + * NEWS: Document the AC_ARG_WITH change. + +2006-11-13 Bruno Haible + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): For --with, --without + options, transliterate also dots to underscores. + (_AC_ENABLE_IF): Transliterate also dots to underscores. + * doc/autoconf.texi (External Software): Document that AC_ARG_WITH's + first argument may also contain dots. + +2006-11-09 Paul Eggert + + * tests/mktests.sh (ac_exclude_list): Exclude AC_PROG_CXX_C_O, for + benefit of platforms like Solaris+GCC where it is common to have a + non-working g++ installation. + +2006-11-08 Ralf Wildenhues + and Joel E. Denny + and Paul Eggert + + * tests/autotest.at (AT_CHECK_AT_TITLE): Fix shell quoting bugs + and non-portable sed scripts, and use $CONFIG_SHELL when invoking + ./micro-suite. + +2006-11-08 Paul Eggert + + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): Set + ac_cv_type_long_long_int to 'yes' instead of 'cross-compiling'. + Imported from a similar patch to gnulib by Bruno Haible. + +2006-11-08 Paul Eggert + + * NEWS: New macros AC_C_FLEXIBLE_ARRAY_MEMBER, AC_C_VARARRAYS. + * doc/autoconf.texi (C Compiler): Document them. + * lib/autoconf/c.m4 (AC_C_FLEXIBLE_ARRAY_MEMBER, AC_C_VARARRAYS): + New macros, taken from gnulib. + +2006-11-07 Paul Eggert + + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): Detect bug in + Tandem NonStop Kernel (OSS) cc -O circa 2004, reported by + Matthew Woehlke. + +2006-10-28 Ralf Wildenhues + + * tests/torture.at (Configuring subdirectories): Do not skip + Automake 1.10 nor future Automake 11.1 (sic). + +2006-10-26 Joel E. Denny + and Stepan Kasal + + Handle special characters in test case titles correctly. + * lib/autotest/general.m4 (AT_INIT): M4-quote and AS_ESCAPE AT_help_all + properly. + (AT_SETUP): M4-quote and AS_ESCAPE the title properly everywhere. + * tests/autotest.at (AT_CHECK_AT_TITLE): Add EXPANDED-TITLE-TO-TEST + argument. Extend to check titles printed by ./micro-suite and + ./micro-suite -l and the title in micro-suite.log. + (Backquote in a test title, + Single-quote in a test title, + Double-quote in a test title): Don't expect failure anymore. + (Backslash in a test title): Put a non-whitespace character after the + backslash so that Bourne shells might actually see it as an escape + sequence. + (Brackets in a test title, + Pound in a test title, + Comma in a test title, + Quoted Macro in a test title, + Macro in a test title, + Macro with single-quote in a test title): New tests. + (Macro with backquote in a test title, + Macro with double-quote in a test title, + Macro with backslash in a test title): New tests expected to fail. + * tests/torture.at (#define header templates): M4-quote this title in + AT_SETUP call so that no M4 code is commented inadvertently somewhere. + The visible effect was a stray [] in the testsuite output. + +2006-10-27 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Builtins): Do not invoke + `trap ... 0' inside a function, for AIX sh. + +2006-10-26 Paul Eggert + + * tests/base.at (AC_COMPUTE_INT): Test **0** rather than 1 / 0, + since powerpc-apple-darwin8-gcc-4.0.1 (Apple Computer, Inc. build + 5363) simply issues a warning when dividing by zero at compile + time. Problem reported by Elias Pipping. + +2006-10-26 Eric Blake + + * THANKS: Update. + * doc/autoconf.texi (Evaluation Macros): Improve the example to + show effect on macros that expand with commas. + Reported by Joel E. Denny. + + * tests/m4sugar.at (m4_warn, m4_require: circular dependencies): + Also work with M4 1.4.8. + +2006-10-25 Paul Eggert + + * doc/autoconf.texi (Slashes): Document Tru64 4.0 bug reported by + Jim Meyering. + +2006-10-25 Stepan Kasal + + * tests/tools.at (autom4te --force): New test, verifies that + `--force' always rewrites the output file. + +2006-10-24 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Document that rm + needs operands on NetBSD 2.0.2. Problem reported by Bruno Haible. + +2006-10-24 Stepan Kasal + + * tools/trace.at (autoconf --trace: user macros): Test `$%'. + +2006-10-24 Paul Eggert + + * lib/autoconf/specific.m4 (_AC_SYS_LARGEFILE_MACRO_VALUE): + If FUNCTION-BODY is nonempty, use AC_LINK_IFELSE rather than + AC_COMPILE_IFELSE, to work around problem with OSF/1 4.0F fseeko + reported by Nelson H. F. Beebe for Coreutils 6.4. + + * tests/tools.at (autoconf --trace: user macros): Remove test + for tracing multiline macros, since m4 1.4.7a uses a different + way to number lines. Problem reported by Ralf Wildenhues. + +2006-10-24 Stepan Kasal + + * bin/autom4te.in (handle_m4): Do not redirect stdin to + /dev/null since the heuristics for interactive behaviour was + fixed in CVS m4. + + * bin/autom4te.in: With --force, always refresh the output + file. Problem reported by Greg Schafer . + + * bin/autoconf.as: Fix the verbose message at the end. + +2006-10-23 Paul Eggert + + * configure.ac (AC_INIT): Bump to 2.60c. + * NEWS: Likewise. + +2006-10-22 Paul Eggert + + * NEWS: Version 2.60b. + + Import this change from Texinfo: + 2006-10-15 Karl Berry + * build-aux/texinfo.tex: automake 1.10 + + * NEWS: Remove AC_CACHE_CHECK_INT. + * doc/autoconf.texi (Caching Results): Likewise. + * lib/autoconf/general.m4 (_AC_CACHE_CHECK_INT): Renamed from + AC_CACHE_CHECK_INT, since it's no longer public. + * lib/autoconf/types.m4: All uses of AC_CACHE_CHECK_INT changed. + * tests/base.at (AC_COMPUTE_INT): Test this, not AC_CACHE_CHECK_INT. + +2006-10-20 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Usual Tools): Fix two typos. + +2006-10-19 Eric Blake + + * lib/m4sugar/m4sugar.m4 (m4_mkstemp): New macro. + (m4_maketemp): Avoid warnings with M4 1.9a. + * lib/emacs/autoconf-mode.el (autoconf-font-lock-keywords): Color + m4_mkstemp. + * doc/autoconf.texi (Redefined M4 Macros): Document m4_mkstemp. + * NEWS: Likewise. + +2006-10-16 Eric Blake + + * doc/autoconf.texi (Setting Output Variables): Fix typo. + + * bin/autoconf.as (version): Reword to match GNU Coding + Standards. + * bin/autoheader.in (version): Likewise. + * bin/autom4te.in (version): Likewise. + * bin/autoreconf.in (version): Likewise. + * bin/autoscan.in (version): Likewise. + * bin/autoupdate.in (version): Likewise. + * bin/ifnames.in (version): Likewise. + +2006-10-14 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_LITERAL_IF): Expand $1 before + looking for special shell characters. + * lib/autoconf/functions.m4 (AC_CHECK_FUNC): Do not expand the + macro defined by AS_VAR_PUSHDEF before passing it as a + parameter. + * lib/autoconf/general.m4 (AC_CHECK_FILE, AC_CHECK_DECL): + * lib/autoconf/libs.m4 (AC_SEARCH_LIBS, AC_CHECK_LIB): + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW, AC_CHECK_MEMBER): + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): + (_AC_CHECK_HEADER_NEW, _AC_CHECK_HEADER_OLD, _AC_CHECK_HEADER_DIRENT): + Likewise. + * lib/autotest/general.m4 (AT_INIT): Quote parameters of + AS_VAR_* properly. + * tests/m4sh.at (AS_LITERAL_IF): New test. + +2006-10-14 Paul Eggert + + (Imported from Automake.) + * build-aux/install-sh (posix_mkdir): Reject FreeBSD 6.1 mkdir -p -m, + which incorrectly sets the mode of an existing destination + directory. In some cases the unpatched install-sh could do the + equivalent of "chmod 777 /" or "chmod 0 /" on a buggy FreeBSD + system. We hope this is rare in practice, but it's clearly worth + fixing. Problem reported by Alex Unleashed in + . + Also, don't bother to check for -m bugs unless we're using -m; + suggested by Stepan Kasal. + +2006-10-14 Paul Eggert + + Import this change from Automake: + + 2006-08-23 Alexandre Duret-Lutz + * lib/Autom4te/ChannelDefs.pm (usage): Mention that -Wportability + is enabled by default with gnu and gnits strictness. + Report from Bruno Haible. + + 2006-03-10 Alexandre Duret-Lutz + * lib/Autom4te/ChannelDefs.pm: Make -Wportability the default in + gnu and gnits modes. + + Import this change from Config: + + 2006-09-20 Ben Elliston + * build-aux/config.sub (score, score-*): New. + + Import this change from Gnulib: + + 2006-09-16 Karl Berry + * doc/fdl.texi (ADDENDUM): switch to @heading from @appendixsubsec, + to avoid sectioning errors. + + Import these changes from Texinfo: + + 2006-10-04 Karl Berry + * build-aux/texinfo.tex (\singlequotechar): rename to \codequoteright. + (\quoteexpand): rename to \rquoteexpand. + (\codequoteleft): new def, to look for @set codequotebacktick. + (\lquoteexpand, \quoteexpand): new defs. + (\lquoteChar, \rquoteChar, \dashChar, \underChar: new \chardef's. + (\code): must use new \...Char values, since now ` is active. + + 2006-08-26 Karl Berry + * build-aux/texinfo.tex (\textdegree): New command. + + 2006-08-12 Karl Berry + * build-aux/texinfo.tex (error \box0): smaller font. + +2006-10-14 Ralf Wildenhues + + * doc/autoconf.texi (Autoheader Macros): Fix syntax error. + +2006-10-13 Stepan Kasal + + * doc/autoconf.texi (Autoheader Macros): Warn that the text + added to the template can get mangled. + +2006-10-13 Ralf Wildenhues + + * lib/autoconf/functions.m4 (AC_FUNC_OBSTACK): In the test, + include the default headers, and redefine obstack_chunk_alloc + and obstack_chunk_free. Fixes false failure with glibc. + +2006-10-12 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_TEST_PREPARE): Set as_executable_p, + for backward compatibility with Libtool 1.5.22. Problem reported + by Ralf Wildenhues. + +2006-10-12 Ralf Wildenhues + + * lib/autoconf/c.m4 (AC_PROG_GCC_TRADITIONAL): Require + AC_PROG_CC. + Report by IOhannes m zmoelnig . + +2006-10-11 Paul Eggert + + * NEWS: AC_USE_SYSTEM_EXTENSIONS now defines _TANDEM_SOURCE for + the NonStop platform. + * doc/autoconf.texi (Posix Variants): Likewise. + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): Likewise. + + * lib/m4sugar/m4sh.m4 (AS_TEST_X): New macro. + (AS_EXECUTABLE_P): Use as_test_x rather than as_executable_p. + (_AS_TEST_PREPARE): Set as_test_x rather than as_executable_p. + Use a better substitute, by inspecting the output of "ls" + rather than just using ":". + * lib/autoconf/general.m4 (_AC_LINK_IFELSE): Use AS_TEST_X + rather than AS_EXECUTABLE_P, since we needn't worry about + non-regular files here. + + * NEWS: Autoconf-generated shell scripts no longer export BIN_SH, + due to configuration hassles with this. See Tonya Underwood's report + . + * doc/autoconf.texi (Special Shell Variables): Likewise. + +2006-10-11 Paul Eggert + Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_BOURNE_COMPATIBLE): Don't set BIN_SH. + (_AS_DETECT_BETTER_SHELL): Don't look in /usr/bin/posix. + +2006-10-11 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_BOURNE_COMPATIBLE): Move the + initialization which is not inherited through the environment + (_AS_BOURNE_COMPATIBLE): ... to this new macro. + (_AS_RUN): Call _AS_BOURNE_COMPATIBLE, not AS_BOURNE_COMPATIBLE. + +2006-10-09 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Describe + problems with mkdir -p -m. + +2006-10-06 Paul Eggert + + * lib/autoconf/c.m4 (_AC_PROG_PREPROC_WORKS_IFELSE): Remove + comment about ac_cpp_err; it was incorrect, and anyway + ac_cpp_err is being removed below. + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE): Don't + set ac_cpp_err to 'yesyes' if preproc_warn_flag and werror_flag + are both 'yes'. In fact, don't bother setting ac_cpp_err at all; + nobody uses it. + (_AC_COMPILE_IFELSE, _AC_LINK_IFELSE): Don't log our funky tests + with werror_flag and conftest.err and so forth. This is more + compatible with how _AC_PROG_PREPROC_WORKS_IFELSE behaves, + and anyway the user shouldn't normally want to see this gorp logged. + Problem reported by Ralf Wildenhues. + * lib/autoconf/lang.m4 (AC_LANG_WERROR): werror_flag's default is + empty, not 'no', since the rest of the code uses 'test -z'. + +2006-10-04 Paul Eggert + + * lib/autoconf/general.m4 (_AC_COMPILE_IFELSE, _AC_LINK_IFELSE): + Use a single call to AC_DO_TOKENS rather than multiple, for + efficiency. + (_AC_LINK_IFELSE): Test that resulting file is executable. + Problem reported by mwoehlke in + . + + * lib/m4sugar/m4sh.m4 (_AS_TEST_PREPARE): Use "test -x /" rather + than creating a file to use with test -x; this is much faster. + +2006-10-02 Bruno Haible + + * lib/autom4te.in (Automake-preselections): Add + AM_GNU_GETTEXT_INTL_SUBDIR, for automake 1.10. + +2006-09-27 Stepan Kasal + + * doc/autoconf.texi (Writing testsuite.at): Fix a typo: for + standard error, `experr' should be used, not `expout'. + +2006-09-26 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_FSEEKO): Don't compile the + fseeko testing program twice; just use the earlier result. + * lib/autoconf/specific.m4 (_AC_SYS_LARGEFILE_MACRO_VALUE): + Set cache var to 'unknown' (not 'no') if leaving the macro unset + still doesn't let the program compile. + (AC_SYS_LARGEFILE): Test for _LARGE_FILES only if earlier tests + failed. + + * lib/autoconf/functions.m4: Fix problems reported by Ralf Wildenhues. + (AC_FUNC_ERROR_AT_LINE): Don't bother to check for error.h. Just + include it, without including anything else. + (AC_FUNC_FSEEKO): Avoid gcc -Wall warnings about constant + expressions. + (AC_FUNC_STRNLEN): Require AC_USE_SYSTEM_EXTENSIONS. + +2006-09-26 Ralf Wildenhues + + * lib/autoconf/functions.m4 (AC_FUNC_ERROR_AT_LINE): Check for + `error.h', and include it, for a `error_at_line' prototype. + Use a nonempty format string in the link test. + * lib/autoconf/functions.m4 (AC_FUNC_WAIT3): Include , + for a declaration of wait3. + +2006-09-26 Paul Eggert + + * NEWS: AC_CHECK_DECL now also works with aggregate objects. + * doc/autoconf.texi (Generic Declarations): Clarify that AC_CHECK_DECL + can apply to constants too, and that it checks for macro defns. + * lib/autoconf/general.m4 (AC_CHECK_DECL): Assume C89 or better, + and simply cast the identifier to void. This handles structure + values. Problem reported by Ralf Wildenhues. + * tests/semantics.at (AC_CHECK_DECLS): Also check enums. + +2006-09-26 Ralf Wildenhues + + * tests/semantics.at (AC_CHECK_DECLS): Also check macros, + structure, and function symbols. + +2006-09-26 Ralf Wildenhues + + * tests/semantics.at (AC_CHECK_MEMBERS): Also test with a struct + member. + +2006-09-25 Paul Eggert + + * NEWS: Recommend M4 1.4.7 instead of 1.4.6. + * README: Likewise. + * doc/autoconf.texi (Introduction, Why GNU M4): Likewise. + +2006-09-25 Paul Eggert + and Ralf Wildenhues + + * lib/autoconf/functions.m4 (AC_FUNC_OBSTACK): Avoid `gcc -Wall' + warnings (uninitialized value). + (AC_FUNC_UTIME_NULL): Likewise, test for and include if + present. + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): Likewise, add + parentheses. + (AC_STRUCT_TM): Likewise, avoid unused variables. + +2006-09-20 Ralf Wildenhues + + * lib/autoconf/c.m4 (_AC_ARG_VAR_LDFLAGS): Update comment. + (_AC_ARG_VAR_LIBS): New macro: let LIBS be precious. + (AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC): Call _AC_ARG_VAR_LIBS. + * lib/autoconf/fortran.m4 (AC_PROG_F77, AC_PROG_FC): Likewise. + Report by Olly Betts. + +2006-09-19 Eric Blake + + * m4/m4.m4: Change copyright. + * configure: Regenerate. + * Makefile.in: Likewise. + * bin/Makefile.in: Likewise. + * doc/Makefile.in: Likewise. + * lib/Makefile.in: Likewise. + * lib/Autom4te/Makefile.in: Likewise. + * lib/autoconf/Makefile.in: Likewise. + * lib/autoscan/Makefile.in: Likewise. + * lib/autotest/Makefile.in: Likewise. + * lib/emacs/Makefile.in: Likewise. + * lib/m4sugar/Makefile.in: Likewise. + * man/Makefile.in: Likewise. + * tests/Makefile.in: Likewise. + + * m4/m4.m4 (AC_PROG_GNU_M4): Check for m4 --debugfile support. + * bin/Makefile.am (edit): Substitute M4_DEBUGFILE. + * bin/autom4te.in (handle_m4): Favor --debugfile over misnamed + --error-output, to avoid warnings with M4 2.0. + +2006-09-19 Stepan Kasal + + * lib/autoconf/libs.m4 (AH_CHECK_LIB): Fix quoting, to be + consistent with _AH_CHECK_FUNCS and _AH_CHECK_HEADERS. + * lib/autoconf/headers.m4 (AH_CHECK_HEADERS_DIRENT): Likewise. + +2006-09-15 Stepan Kasal + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): Eliminate the + expansion of AC_CHECK_FUNCS. + +2006-09-14 Stepan Kasal + + * lib/autoconf/general.m4 (AC_CONFIG_MACRO_DIR): Remove a + mistaken comment: the path has to be relative; do not use + the path at runtime. + +2006-09-13 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Quote the + argument to `--prefix' for sub-configure scripts. + Pass `--silent' to sub-configure scripts. + * tests/torture.at (Configuring subdirectories): Add tests + for both changes. + * doc/autoconf.texi (Setting Output Variables): Fix example to + not show `--silent' being passed to a `configure' re-run. + +2006-09-12 Paul Eggert + + * doc/autoconf.texi (Input): Clarify role of AC_CONFIG_MACRO_DIR. + * lib/autoconf/general.m4 (AC_CONFIG_MACRO_DIR): Do not check + for the existence of the directory at configure-time. That's + too late, anyway. Problem reported by Stefan Seefeld. + + * lib/m4sugar/m4sh.m4 (_AS_TEST_PREPARE): Avoid bug in UnixWare + 7.1.4 /usr/bin/posix/sh described by Tim Rice in + . + +2006-09-11 Stepan Kasal + + * tests/local.at (AT_CHECK_M4): Fix this so that the testsuite + works with GNU M4 1.4.3 again; make the normalized form + match the current m4 message; fix the description. + * test/tools.at (autom4te cache): Adapt to the change. + +2006-09-08 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_MKTIME): Add year_2050_test + to catch glibc bug 2821 + . + + Merge from gnulib as follows: Use AC_CHECK_HEADERS_ONCE instead of + AC_CHECK_HEADERS, and likewise for AC_CHECK_FUNCS_ONCE and + AC_CHECK_FUNCS. Don't check for stdlib.h, since we now + assume C89. + +2006-09-08 Stepan Kasal + + * lib/autom4te.in (Autoconf-without-aclocal-m4): Move the + preselections ... + (Autoconf): ... here. + (Autoscan-preselections): Delete. + +2006-09-07 Stepan Kasal + + * lib/autom4te.in (Automake-preselections): Preselect + AM_ENABLE_MULTILIB. + +2006-09-05 Paul Eggert + + * doc/autoconf.texi (Preset Output Variables): srcdir and + top_srcdir are not necessarily relative. Problem reported + by Dries Kimpe. + +2006-09-05 Ralf Wildenhues + + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Prefer xlf90/xlf95 over + f90/f95 because the latter drivers of AIX Fortran 9.1 do not + accept files with extension `.f'. For consistency, also prefer + xlf over f77. + * doc/autoconf.texi (Fortran Compiler): Remove mention of bug + from last patch. + +2006-09-05 Romain Lenglet + + * lib/autoconf/erlang.m4 (AC_ERLANG_CHECK_LIB): Added substitution + of ERLANG_LIB_VER_* variables. + * doc/autoconf.texi (Erlang Libraries): Document ERLANG_LIB_VER_* + variables. + +2006-09-03 Paul Eggert + and Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Builtins): Document 'unset' + bugs of Bash 2.01 and 2.05a. + (Fortran Compiler): Document that AC_PROG_CC should be called + before AC_PROG_FC, due to a bug in Autoconf. + +2006-09-01 Paul Eggert + + * NEWS: New macro AC_CACHE_CHECK_INT. It replaces the + old AC_COMPUTE_INT, which now behaves like _AC_COMPUTE_INT + except the first two arguments are reversed. + * doc/autoconf.texi (Caching Results): New macro AC_CACHE_CHECK_INT. + (Generic Compiler Characteristics): AC_COMPUTE_INT no longer + caches nor outputs a diagnostic. Suggested by Bruno Haible. + * lib/autoconf/general.m4 (AC_CACHE_CHECK_INT): New macro, + equivalent to the old AC_COMPUTE_INT. + (AC_COMPUTE_INT): No longer caches or reports. New signature. + All uses changed to AC_CACHE_CHECK_INT. + * tests/base.at (AC_CACHE_CHECK_INT): New test. + * tests/mktests.sh (ac_exclude_list): Add AC_CACHE_CHECK_INT. + +2006-08-31 Paul Eggert + + * NEWS: AC_FUNC_FNMATCH, AC_FUNC_FNMATCH_GNU, AC_FUNC_GETLOADVG, + and AC_REPLACE_FNMATCH are now obsolescent in Autoconf. New + programs should use their Gnulib counterparts. + * doc/autoconf.texi (Particular Functions): Likewise. + (Macro Names, testsuite Invocation): Replace uses of these + obsolete macros with uses of non-obsolete macros. + +2006-08-29 Eric Blake + + * configure.ac (AC_INIT): Bump to 2.60b. + * NEWS: Update. + +2006-08-28 Eric Blake + + * lib/autoconf/headers.m4 (AC_HEADER_STAT): Fix logic that was + mistakenly swapped on 2006-08-15. + +2006-08-25 Paul Eggert + + * NEWS: Version 2.60a. + +2006-08-25 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_LINK_IFELSE): Remove the IPA/IPO + file created by the PGI compiler. + +2006-08-25 Noah Misch + + * lib/Autom4te/General.pm (END): Use `File::Path::rmtree' to + simplify the code. + +2006-08-25 Paul Eggert + + Fix Lex library problem reported to us by Julio Garvia. + * doc/autoconf.texi (Particular Programs): YYTEXT_POINTER is + for the default, which the user can override. + * lib/autoconf/programs.m4 (AC_PROG_LEX): Let _AC_PROG_LEX_YYTEXT_DECL + deal with LEXLIB. + (_AC_PROG_LEX_YYTEXT_DECL): Handle caching correctly; the old code + didn't work if some values were cached but not others. Test for + broken lex libraries like native ia64-hp-hpux11.22; see + , and + work around the problem by preferring an empty LEXLIB to -lfl or + -ll. Let the user set LEXLIB='' to indicate no library needed. + + * NEWS: Recommend M4 1.4.6 instead of 1.4.5. + * README: Likewise. + * doc/autoconf.texi (Introduction, Why GNU M4): Likewise. + +2006-08-24 Paul Eggert + + Rework to use more-modern build style. + Many files are renamed; all uses of their names were changed. + * .x-sc_trailing_blank: Renamed from .x-sc_trailing_space. + * .x-sc_useless_cpp_parens: New file. + * build-aux/config.guess: Renamed from config/config.guess. Update. + * build-aux/config.sub: Renamed from config/config.sub. Update. + * build-aux/elisp-comp: Renamed from config/elisp-comp. + * build-aux/install-sh: Renamed from config/install-sh. Update. + * build-aux/mdate-sh: Renamed from config/mdate-sh. + * build-aux/missing: Renamed from config/missing. + * build-aux/texinfo.tex: Renamed from config/texinfo.tex. Update. + * build-aux/vc-list-files: Renamed from config/vc-list-files. + * config/Makefile.am: Removed. + * config/mkinstalldirs: Removed. + * config/move-if-change: Removed. + * m4/m4.m4: Renamed from config/m4.m4. Add (C) to copyright notice. + * Makefile.am (SUBDIRS): Remove config. + (ACLOCAL_AMFLAGS): Include from m4, not config. + (EXTRA_DIST): Add config/announce-gen, config/prev-version.txt. + (WGET, WGETFLAGS): New macros, since Makefile.maint no longer does this. + (autom4te-update): Rewrite with a loop. Get from gnulib, not automake. + Fail if there's an error. + * Makefile.cfg (move_if_change): Remove. + (wget_files): Remove. + (cvs_executable_files): New macro. + (cvs_files): Use it. Remove mkinstalldirs. Add fdl.texi. + (executable-update): Use $(cvs_executable_files). + (local-checks-to-skip): Remove. + * Makefile.maint: Merge from coreutils, plus add our own changes + (gzip_rsyncable): New macro. + (GZIP_ENV): Use it. + (CVS_LIST): Use build-aux/vc-list-files. + (VERSION_REGEXP): New macro. + (local-checks-available): Add patch-check, $(syntax-check-rules), + check-AUTHORS. + (syntax-check-rules): Compute dynamically. + (sc_cast_of_x_alloc_return_value): Work even if no source files. + (sc_cast_of_alloca_return_value): Likewise. + (sc_prohibit_atoi_atof): Simplify regexp. + (sc_no_if_have_config_h, sc_require_config_h): + (sc_prohibit_assert_without_use, + (sc_obsolete_symbols): Check for O_NDELAY. + (sc_texi_notab): Remove. + (sc-changelog): Don't make an exception for '----' lines. + (.re-list): Remove, so we don't have a junk file behind. + (sc_system_h_headers): Remove the need for .re-list. + (sc_the_the): New rule. + (sc_tight_scope): Simplify. + (sc_trailing_blank): Renamed from sc_trailing_space. + (longopt_re): New macro. + (sc_two_space_separator_in_usage): New rule. + (sc_unmarked_diagnostics): Look at all files under CVS. + (sc_useless_cpp_parens, patch-check, check-AUTHORS): New rules. + (news-date-check, changelog-check): Version is OK. + (po-check): Look for lib files even if not in CVS. + (copyright-check): Use $() not ``. + (maintainer-distcheck): Do not depend on changelog-check. + (my-distcheck): Depend on $(release_archive_dir)/$(prev-tgz). + Also check for -Wpointer-arith. + (WGET, WGETFLAGS, tgz-md5, tgz-sha1, bz2-md5, bz2-sha1): + (xdelta-md5, xdelta-sha1, tgz-size, bz2-size, xd-size, rel-check): + Remove. + (announcement): Add --gpg-key-id arg. + (cvs-sv): Remove. + (move_if_change): Just use mv. + (local_updates: Remove wget-update, po-update. + (po_repo, do-po-update, po-update, wget_files, get-targets): Remove. + (config.guess-url_prefix, config.sub-url_prefix): Remove. + (ansi2knr.c-url_prefix, texinfo.tex-url_prefix): + (standards.texi-url_prefix, make-stds.texi-url_prefix, target, url): + ($(get-targets)): Remove. + (cvs_files): Remove missing, mkinstalldirs, ansi2knr.c. + (gnulib_repo): Renamed from automake_repo. Get from gnulib now. + (cvs-update): Get from gnulib. + (emut_upload_commands): gnupload is in build-aux now. + (alpha beta major): Add changelog-check. Check version. + * configure.ac (AC_CONFIG_AUX_DIR): Renamed from config to build-aux. + (AC_CONFIG_FILES): Remove. + * bin/autoconf.as: Add spaces to avoid distcheck warning. + * config/announce-gen: Sync from coreutils. + * doc/make-stds.texi: Sync from gnulib. + * doc/standards.texi: Likewise. + * man/Makefile.am: Adjust for config -> build-aux renaming. + * tests/Makefile.am: Prefer $(FOO) to @FOO@. + * tests/local.at: Adjust from config -> build-aux renaming. + * tests/tools.at: Likewise. + * tests/torture.at: Likewise. + + * NEWS: The C99 check now tests for vararg macros and 64-bit + preprocessor ints. + * doc/autoconf.texi (C Compiler): Document // comments, va_copy. + * lib/autoconf/c.m4 (_AC_PROG_CC_C99): Test varargs macros and + 64-bit preprocessor ints. Check for static initialization of + long long. Remove unnecessary casts. + +2006-08-24 Ralf Wildenhues + + * doc/autoconf.texi (Particular Programs): Mention that + @INSTALL@ and @MKDIR_P@ may vary for different output files. + Reported by Alexandre Duret-Lutz. + +2006-08-24 Paul Eggert + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Also ignore + -lgcc?* and -lSystem, for Darwin/MacOS X. Problem reported by + Bill Northcott in + . + +2006-08-22 Paul Eggert + + * lib/autoconf/c.m4 (AC_C_CONST): Don't used shadowed vars, to + pacify insanely picky compilers. Problem reported by Eric Blake. + + * doc/autoconf.texi (Posix Variants): INTERACTIVE Unix is no + longer supported by Sun. + +2006-08-15 Paul Eggert + + * NEWS: Autoconf now uses constructs like "#ifdef HAVE_STDLIB_H" + rather than "#if HAVE_STDLIB_H", so that it now works with "gcc + -Wundef -Werror". Problem reported by David Fang in + . + * doc/autoconf.texi (Header Templates, Default Includes): + (Particular Functions, Generic Functions, Header Portability): + (Particular Headers, Generic Headers, Generic Declarations, Guidelines): + (Obsolete Macros, AC_FOO_IFELSE vs AC_TRY_FOO): + (Present But Cannot Be Compiled, Preprocessor Symbol Index): + Prefer #ifdef to #if. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Prefer #ifdef to #if. + * lib/autoconf/functions.m4 (AC_FUNC_ALLOCA, _AC_FUNC_MALLOC_IF): + (AC_FUNC_MKTIME, AC_FUNC_MMAP, _AC_FUNC_REALLOC_IF): + (AC_FUNC_SELECT_ARGTYPES, AC_FUNC_SETVBUF_REVERSED, _AC_FUNC_VFORK): + Likewise. + * lib/autoconf/headers.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): + (AC_HEADER_RESOLV, AC_HEADER_STAT): Likewise. + * lib/autoconf/specific.m4 (AC_DECL_SYS_SYGLIST): + (AC_SYS_RESTARTABLE_SYSCALLS): Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_STAT): Don't assume that + S_ISDIR etc. are valid for use in #if; POSIX doesn't guarantee + this. + +2006-08-14 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Document sed + problems with arg script text that doesn't end in newline, and + with '-e a...'. Problems reported by Ralf Wildenhues. + +2006-08-12 Alexandre Julliard (tiny change) + + * lib/autoconf/libs.m4 (AC_PATH_X_DIRECT): Replace another + check for libXt by a check for libX11. + +2006-08-10 Ralf Wildenhues + + * doc/autoconf.texi (config.status Invocation): Adjust according + to last change. + +2006-08-08 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): `config.status + --help' should mention that `--version' outputs configuration + settings. Report by Bruno Haible. + +2006-08-06 Paul Eggert + + Fix test suite failures reported by Pierre in + . + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Don't claim + the compiler created a file "b.out" when it didn't create anything + at all. + * lib/autoconf/specific.m4 (AC_SYS_INTERPRETER): + Discard stderr too, when invoking the test script. + +2006-08-05 Alexandre Julliard (tiny change) + + * lib/autoconf/libs.m4 (AC_PATH_XTRA): Fixed a typo + in the restoring of the werror flag. + +2006-07-24 Paul Eggert + + * doc/autoconf.texi (Volatile Objects): Be even a little + less skeptical about "volatile", after discussion with + Bruno Haible on bug-gnulib. + (Limitations of Usual Tools): Warn about sed stripping + leading white space from text. From Bruno Haible. + +2006-07-20 Paul Eggert + + * lib/autoconf/libs.m4 (AC_PATH_XTRA): Don't use -R if the + compiler complains about it, even if things works after the + complaint. Problem reported by Peter O'Gorman. + + * doc/autoconf.texi (Preset Output Variables): Document CFLAGS, + CPPFLAGS, and LDFLAGS better. Problem reported by Bruno Haible. + Similarly for CXXFLAGS, OBJCFLAGS, ERLCFLAGS. + +2006-07-17 Paul Eggert + + * lib/autoconf/libs.m4 (AC_PATH_XTRA): Do the check for space + after -R regardless of host. Patrick Welche reports that this + fixes things on NetBSD 3.99. + + * NEWS: Recommend M4 1.4.5. + * README: Likewise. + * doc/autoconf.texi (Introduction, Why GNU M4): Likewise. + * tests/tools.at (autom4te cache): Update wording of diagnostic + to match M4 1.4.5. + +2006-07-07 Paul Eggert + + * doc/autoconf.texi (C Compiler): Add a ref to Volatile Objects + under AC_C_VOLATILE. + (Volatile Objects): Be a little less skeptical about what + "volatile" means. Derived from thoughts by Ben Pfaff in + . + +2006-07-07 Ralf Wildenhues + + * doc/autoconf.texi: Fix some typos. + +2006-07-07 Paul Eggert + + * tests/torture.at (Configuring subdirectories): Set CONFIG_SITE + more globally, since the 2006-06-30 patch didn't suffice. Problem + reported by Keith Marshall. Also, don't bother with builddir2, + since it shouldn't be needed any more. + +2006-07-07 Paolo Bonzini + + * doc/autoconf.texi (Generic compiler characteristics): + Document AC_COMPUTE_INT. Fix wrong statements on Default + Includes for AC_CHECK_SIZEOF and AC_CHECK_ALIGNOF. + + * lib/autoconf/general.m4 (AC_COMPUTE_INT): New. + (_AC_COMPUTE_INT): Add obsoletion warnings. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF, AC_CHECK_ALIGNOF): Use + AC_COMPUTE_INT. + + * NEWS: Document change. + +2006-07-05 Paul Eggert + + * doc/autoconf.texi (Volatile Objects): New section. + + * NEWS: Document previous change. + +2006-07-02 Paul Eggert + + * lib/autoconf/types.m4 (AC_TYPE_LONG_LONG_INT): + Require that long long int be at least 64 bits wide. C99 requires + this and enough programs depend on it so we should check for it. + Bruno Haible reports in + + that long long int is 32 bits wide with some nonstandard compilers. + (AC_TYPE_UNSIGNED_LONG_LONG_INT): Likewise. + +2006-06-30 Paul Eggert + + * tests/torture.at (Configuring subdirectories): Set CONFIG_SITE + to a nonexistent file, so that we don't have to worry about + a local site configuration that doesn't use /usr/local. + Problem reported by Keith Marshall in + . + +2006-06-28 Paul Eggert + + * doc/autoconf.texi: Be more consistent about using @acronym with + "HP" and "HP-UX". Remove mention of OSF; the old version wasn't + quite right (it talked about "OSF/Tru64", even though the + operating systems were called OSF/1, Digital UNIX, and Tru64 UNIX, + and it even mentioned "OSF 4"!) and at this point there's little + reason to talk about OSF any more, since it died in 1994. + (Specific Compiler Characteristics): Simplify example of + negative-size array. + (File Descriptors): Reorder to make the text flow better. + Remove joke about "appreciate the various levels"; I didn't get it. + Add remark about HP-UX sh -x bug with stderr noted by Bob Proulx in + . + (File Descriptors, Limitations of Usual Tools): + Tone down the advice against renaming or removing open files. + (Limitations of Usual Tools): Add a new section, on 'rm'. + +2006-06-26 Stepan Kasal + + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Use -lX11, not + -lXt in LIBS, idea from Karsten Hopp; this was due since + this change: + + 2005-09-18 Paul Eggert + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Look for X11/Xlib.h + and XrmInitialize rather than X11/Intrinsic.h and XtMalloc + (which belong to Xt, not X itself). See Debian bug 327655. + +2006-06-23 Ralf Wildenhues + + * configure.ac (AC_INIT): Bump to 2.60a. + * NEWS: Update. + +2006-06-23 Ralf Wildenhues + + Version 2.60. + + * configure.ac, NEWS: Update. + +2006-06-23 Ralf Wildenhues + + * config/texinfo.tex: Sync from upstream. + + * bin/autom4te.in (handle_traces): Transform the `@S|@' + quadrigraph correctly in traces. + + * NEWS, lib/Autom4te/C4che.pm, lib/autoconf/functions.m4: + Fix typos. + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Expand tests for + datarootdir-related errors only if AC_DATAROOTDIR_CHECKED is + not defined. + * doc/autoconf.texi (Changed Directory Variables): New node, + to document the whole `datarootdir' business a bit better. + * NEWS: Update. + * tests/torture.at (datarootdir workaround): Extend test. + Prompted by report by Alexandre Julliard. + +2006-06-22 Paul Eggert + + * lib/autoconf/c.m4 (_AC_PROG_CC_C89): Check for C89 incompatibility + when using default mode of IBM C 6 for AIX. Problem and two-line + fix reported by Larry Jones. + +2006-06-22 Alexandre Julliard + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Avoid warning + about literal '${datarootdir}' if a definition is found in the + output file. + +2006-06-20 Paul Eggert + + * NEWS: Use "M4" rather than "m4" when appropriate. + Problem reported by Eric Blake. + * doc/autoconf.texi: Likewise. + Use @acronym around BSD, GCC, and GNU when appropriate. + (Why GNU M4): Renamed from "Why GNU m4". + (Redefined M4 Macros): Mention that Posix + m4wrap takes only 1 argument, but GNU M4 1.4.x takes more. + (Buffer Overruns): Mention size_t and ptrdiff_t as alternatives + to int. + +2006-06-20 Ralf Wildenhues + + * bin/autom4te.in (handle_output): Do not forbid the empty + pattern. + * tests/tools.at (autoconf: the empty token): New test. + +2006-06-20 Stepan Kasal + + * lib/m4sugar/m4sugar.m4 (m4_init): Merge the two m4_wrap + calls, so that we do not care whether they are LIFO or FIFO; + in the m4_wrap, do not check which diversion is the topmost + one, just check that the stack is balanced at the end. + * lib/m4sugar/m4sh.m4 (AS_INIT): We are going to change the + base diversion forever--pop the previous diversion before + opening the new one; consequently, remove the m4_wrap call. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * tests/m4sugar.at: Do not use + m4_wrap([m4_diversion_pop([..])]), for educational purposes. + +2006-06-19 Paul Eggert + and Ralf Wildenhues + + * NEWS: Document that m4wrap/m4_wrap might not be LIFO. + * doc/autoconf.texi (Redefined M4 Macros): Likewise. + Rework example of m4wrap token-pasting trouble so that it doesn't + care whether it's LIFO or FIFO. + Fix some "contrary to"s that are awkward in English. + +2006-06-19 Ralf Wildenhues + + * lib/autoconf/types.m4 (_AC_TYPE_INT): Set `$ac_cv_c_int$1_t' + to `yes' instead of `int$1_t' if the type is found, for more + consistent configure output (where $1 is the number of bits). + (_AC_TYPE_UINT): Likewise for `uint$1_t'. + Suggested by Bruno Haible. + + * lib/autoconf/types.m4 (_AC_TYPE_UNSIGNED_INT): Solaris 2.5.1 + needs _UINT8_T and _UINT64_T defines as well, to avoid clashes + with system headers. Report by Bruno Haible. + +2006-06-17 Ralf Wildenhues + + * config/config.guess, config/config.sub: Sync from upstream. + + * bin/Makefile.am (autoconf.in): Use `--melt' for autom4te, + in order to avoid picking up an older installed frozen m4sh.m4f. + Besides an outdated shell startup, this could have been created + by an earlier M4 version with incompatible frozen file format. + +2006-06-16 Paul Eggert + + * README: Recommend m4 1.4.4 instead of 1.4.3.. + * doc/autoconf.texi: Likewise. + (Special Chars in Names): Say that $(.FOO) is portable, as + suggested by Stepan Kasal. + (Installation Directory Variables, Build Directories): + (Automatic Remaking, Subdirectories, Fortran Compiler): + (Making testsuite Scripts, Defining Directories): + Quote variable usages better. + (Making testsuite Scripts): Add clean-local rule to makefile + snippet, by Eric Blake. + (Installation Directory Variables): Fix table item font. + Reword slightly to clarify. Generalize advice about + not using special characters to include all file-related + vars, not just VPATH. + (Special Chars in Variables): Warn about special characters in + $(srcdir) too. + (Assignments): Clarify default-value example as suggested by + Ralf Wildenhues in + . + (Special Shell Variables): Note leading ./ or ../, as suggested + by Eric Blake. + (Limitations of Builtins): Under cd, warn about CDPATH. + (The Make Macro MAKEFLAGS): Untabify. Problem reported by + Ralf Wildenhues. + +2006-06-15 Ralf Wildenhues + + * doc/autoconf.texi (Configuration Actions): Remove duplicate + `@var', for texi2html. + (Systemology): Some more word wrapping, for DVI output. + (autom4te Invocation): The short option for `--melt' is `-M', + not `-m'. + +2006-06-15 Paul Eggert + + * doc/autoconf.texi: More formatting and English tweaks, + many suggested by Ralf Wildenhues. + Reword to avoid "@code{...}'s" and the like, since it's ugly + with Emacs info mode. discontents -> woes. + Put a few "will"s back. time stamp -> timestamp. + side-effect -> side effect. + +2006-06-14 Paul Eggert + + * doc/autoconf.texi (Initializing configure, Shell Substitutions): + Warn about $@ not persisting. Problem reported by Julien Danjou in + . + (Special Chars in Names): Renamed from Leading _ in Macro Names. + Mention other special chars, too. + +2006-06-14 Eric Blake + + * doc/autoconf.texi (The Make Macro MAKEFLAGS): New node. + +2006-06-13 Paul Eggert + + * doc/autoconf.texi: Some systematic minor improvements, as + follows. Use "makefile" when talking about makefiles + generally (which might be named "makefile" or "Makefile" or even + "foo.mk"), "Makefile" when talking about a specific makefile + called "Makefile". This unclutters the text from weird quotes + (e.g., "`Makefile's" in info mode). Similarly, use "@var{foo} + values" rather than "@var{foo}s" and similar constructs containing + "}s". Use "Make rules" rather than "Makefile rules". Minor + English-language improvements. Change the prefix "sub-" to "sub" + and "re-" to "re". + Put blank lines around examples more consistently. + Avoid "rather" and "very" as intensifiers. + Avoid "will" as an auxiliary. + (Limitations of Make): Split this node into.... + (Portable Make, $< in Ordinary Make Rules, Failure in Make Rules): + (Leading _ in Macro Names, Backslash-Newline-Newline): + (Backslash-Newline Comments, Long Lines in Makefiles): + (Macros and Submakes, The Make Macro SHELL, Comments in Make Rules): + (obj/ and Make, make -k Status, VPATH and Make): + (VPATH and Double-colon, $< in Explicit Rules): + (Automatic Rule Rewriting, OSF/Tru64 Directory Magic): + (Make Target Lookup, Single Suffix Rules, Timestamps and Make): + New nodes, resulting from splitup of Limitations of Make. + All cross-references changed. Raise the top node from + a section to a chapter, and all subnodes accordingly. + Redo the introductory wording to match the new organization. + (Installation Directory Variables): Use an example that is + closer to what Autoconf actually does. Mention that VPATH's + value should not contain metacharacters or white space. + (Fortran Compiler): Fix a VPATH bug in an example. + (Leading _ in Macro Names): Mention that this problem is no longer + of practical concern. + (VPATH and Make): Reword the advice to make it clearer + that Autoconf and Automake support VPATH in non-GNU make, but + many packages have bugs in this area. + ($< in Explicit Rules): Refer to Build Directories rather + than using a (non-VPATH-safe) example. + (Automatic Rule Rewriting): Mention the sort of disaster that + can ensue with Solaris-style rule rewriting with VPATH. + +2006-06-13 Ralf Wildenhues + + * doc/install.texi (Compilers and Options): Weaken the + suggestion to use GNU make for VPATH builds. + + * lib/autom4te.in (Automake-preselections): Add AM_PROG_CXX_C_O, + AM_PROG_F77_C_O, AM_PROG_FC_C_O, AC_FC_SRCEXT, AC_FC_FREEFORM. + + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Fix M4 quotation + in regular expression. + +2006-06-08 Ralf Wildenhues + + * doc/autoconf.texi (Installation Directory Variables): + Drop extra @samp from `@table @samp' item. + (Limitations of Usual Tools): Comment fix. + Do not nest @samp just to point to other table items. + (Writing testsuite.at) : The second argument to + `@dvar' is already @samp'ed. + (Making testsuite Scripts) : Likewise, + do not use @var in the second argument. + +2006-06-07 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Look for + $as_shell.exe too. Problem reported by Andreas Buening in + . + +2006-06-07 Ralf Wildenhues + + * lib/autoconf/functions.m4 (AC_FUNC_ALLOCA): Work around + `unused variable' compiler warning, for `-Wall -Werror'. + Reported by Jaap Haitsma in + . + +2006-06-06 Paul Eggert + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): Remove core file, in + case the compiler dumps core. Problem reported for + OpenServer 5.0.7 by Tim Rice in + . + * lib/autoconf/general.m4 (_AC_COMPILE_IFELSE, _AC_LINK_IFELSE): + Likewise. + +2006-06-06 Tim Rice . + + * lib/freeze.mk: Quiet check-forbidden-patterns so the string + "ERROR" only shows up in "make check" output if there is an + error. + +2006-06-06 Eric Blake + + * tests/tools.at (automatically allowed tokens): Fix typo. + +2006-06-05 Paul Eggert + + * NEWS: Don't blame non-GNU VPATH compatibility issues on Automake. + + * doc/autoconf.texi (Integer Overflow): Mention that INT_MIN % -1 + typically overflows on x86 CPUs, even though the C standard + requires otherwise. + +2006-06-05 Ralf Wildenhues + + * configure.ac (AC_INIT): Bump to 2.59e. + * NEWS: Update. + +2006-06-05 Ralf Wildenhues + + Version 2.59d. + + * config/texinfo.tex: Sync from upstream. + + * bin/autoreconf.in: Trace `LT_CONFIG_LTDL_DIR'; if it has been + seen, invoke libtoolize with `--ltdl' argument. + * lib/autom4te.in (Autoreconf-preselections): Adjust. + * NEWS: Update. + Suggested by Eric Blake. + +2006-06-05 Paul Eggert + + * NEWS: Whoops! AC_FUNC_STRNLEN isn't obsolescent. Problem + reported by Ralf Wildenhues. + * doc/autoconf.texi (AC_FUNC_STRNLEN): Likewise. + +2006-06-05 Ralf Wildenhues + + * THANKS: Update. + +2006-06-05 Paul Eggert + + * doc/autoconf.texi: Modernize some of the references to Solaris. + +2006-06-05 Stepan Kasal + + * lib/m4sugar/m4sugar.m4 (m4_require): Modify the error + message issued by AC_REQUIRE. + * tests/m4sugar.at: Check m4_require's error message. + * tests/base.at: Check AC_REQUIRE's error message. + * tests/local.at (AT_CHECK_M4): New macro, almost identical + to... + (AT_CHECK_AUTOM4TE): ... which is now a thin wrapper around + AT_CHECK_M4. + (AT_CHECK_AUTOCONF): Use AT_CHECK_M4; no longer support + `expout' as the last parameter. + * tests/tools.at: Adapt to the above change. + +2006-06-04 Stepan Kasal + + * doc/autoconf.texi (Limitations of Usual Tools): Correct + information about race-free implementations of mkdir. + +2006-06-04 Eric Blake + + * bin/autoreconf.in (help): Document M4 environment variable. + * bin/autoconf.as (Usage): Likewise. + * bin/autom4te.in (help): Likewise. + * doc/autoconf.texi (autom4te Invocation): Likewise. + +2006-06-04 Paul Eggert + + * NEWS: GNU make now recommended for VPATH builds. + Mention that some macros are now documented to be obsolescent. + * doc/autoconf.texi: + Prefer "current" to "modern" to describe + currently-used (albeit perhaps old-fashioned) hosts. + Mention which ancient features no longer need to be worried about. + setgid -> set-group-ID + setuid -> set-user-ID (these are the Posix terms) + Fix some misuses of "only". + (AC_C_BACKSLASH_A, AC_C_CONST, AC_C_PROTOTYPES): + (AC_C_STRINGIZE, AC_C_VOLATILE, AC_FUNC_CLOSEDIR_VOID): + (AC_FUNC_GETPGRP, AC_FUNC_LSTAT, AC_FUNC_MEMCMP): + (AC_FUNC_SELECT_ARGTYPES, AC_FUNC_SETPGRP): + (AC_FUNC_SETVBUF_REVERSED, AC_FUNC_STAT, AC_FUNC_STRFTIME): + (AC_FUNC_STRNLEN, AC_FUNC_UTIME_NULL, AC_FUNC_VPRINTF): + (AC_HEADER_DIRENT, AC_HEADER_STAT, AC_HEADER_STDC): + (AC_HEADER_SYS_WAIT, AC_HEADER_TIME, AC_ISC_POSIX): + (AC_PROG_GCC_TRADITIONAL, AC_STRUCT_TM): + Mention that these macros are obsolescent. + (Installation Directory Variables): shall -> should + (File Descriptors): Mention that 0, 1, 2 might get reopened. + Mention that it's now safe to use 3 and 4. + (Limitations of Usual Tools): cp -r is now specified by Posix. + Omit longwinded and obsolescent discussion of cp -f. + Modernize discussion of expr, ls. + (Limitations of Make): Modernize discussion of VPATH builds. + Mention $? as a workaround in some cases. + * doc/install.texi (Basic Installation): + Mention "./configure; make; make install" first. Be more + specific about why this file is generic. Remove unnecessary + parens. Remove misleading "only". Remove obsolete advice + about csh. Don't say "configure" takes awhile; say it + might take a while. Suggest CFLAGS=-g rather than CFLAGS=-O2, + and CC=c99 rather than CC=c89, as these are blessed by current + Posix. Recommend GNU make if doing a VPATH build. + +2006-06-03 Paul Eggert + + * doc/autoconf.texi: Use a consistent style "$ @kbd{...}" for + examples involving shell prompts. + +2006-06-02 Stepan Kasal + and Paul Eggert + + * doc/autoconf.texi (Here-Documents): Add details about the + pre-ksh93g bug. Reword slightly to make it clearer. Consistently + use "here-documents" instead of "here documents". + +2006-06-01 Ralf Wildenhues + + * config/texinfo.tex, doc/standards.texi: Sync from upstream. + +2006-06-01 Paul Eggert + + * doc/autoconf.texi (File System Conventions): Warn about ":" + anywhere in directory names. + +2006-05-31 Paul Eggert + + * lib/autoconf/general.m4 (_AC_DO_ECHO): Be even more conservative + about quoting the case statement, just in case. + * doc/autoconf.texi (Here-Documents): Mention that the ksh bug + was fixed in ksh93g; reported by Ralf Wildenhues. + +2006-05-31 Stepan Kasal + + * doc/autoconf.texi (System Services): Do not document + overriding EXEEXT via ac_cv_exeext=ext. + (Particular Programs) : + Document that ${MKDIR_P} understands --. + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Improve the + comment. + +2006-05-31 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_DIRNAME_PREPARE): Guard against test + argument with leading hyphen. Problem reported by Paul Eggert. + +2006-05-30 Paul Eggert + + * lib/autoconf/general.m4 (_AC_DO_ECHO): Be more conservative + about quoting ac_try: quote all of it, if any of it seems suspicious. + This means we don't have to worry about ${ or sed any more. + Also, double-quote the case statement, to work around misuses via + underquoting as reported by Ralf Wildenhues in + . + (_AC_EVAL_STDERR): Revert, since evidently some packages rely on this + undocumented and dangerous macro. + Problem reported by Ralf Wildenhues in + . + +2006-05-31 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_DIRNAME_PREPARE): Check whether + `dirname -- /' returns `/', for SunOS dirname scripts that escaped. + Report by Sam Sirlin . + +2006-05-30 Paul Eggert + + * lib/autoconf/general.m4: Revert AC_TRY_EVAL and AC_TRY_COMMAND, + since evidently some packages rely on the old, broken behavior. + Problem reported by Ralf Wildenhues in + . + (AC_TRY_EVAL, AC_TRY_COMMAND, _AC_EVAL): Go back to the + pre-2006-05-26 definitions, but leave in the comments that + these macros are dangerous and should not be used. + (_AC_DO_ECHO): Renamed from _AC_EVAL_ECHO. All callers changed. + (_AC_DO): Renamed from _AC_EVAL. All callers changed. + (_AC_DO_STDERR): Renamed from _AC_EVAL_STDERR. All callers changed. + (_AC_DO_VAR): Renamed from AC_TRY_EVAL. + (_AC_DO_TOKENS): Renamed from AC_TRY_COMMAND. + +2006-05-29 Paul Eggert + + * lib/autoconf/status.m4 (AC_OUTPUT_MAKE_DEFS): Rewrite to avoid + the use of 'tr', since this is our only use of 'tr'. + +2006-05-29 Ralf Wildenhues + and Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): + Don't assume 'grep' works on long lines, since AIX grep doesn't. + +2005-05-28 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Do not use `grep' on + the output file in the `${datarootdir}' test. + +2005-05-28 Stepan Kasal + and Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): If we have not seen + mention of `datarootdir' in the input file(s), but literal + `${datarootdir}' in the output file, and we haven't warned yet, + then warn as well: the user may have (erroneously) used + `AC_SUBST([mydatadir], [$datadir/my])' instead of the correct + `AC_SUBST([mydatadir], ['${datadir}/my'])'. + * tests/torture.at (datarootdir workaround): Extend this test. + * NEWS: Update. + +2006-05-27 Ralf Wildenhues + and Paul Eggert + + * doc/autoconf.texi (autoheader Invocation): The first argument to + `AC_DEFINE_UNQUOTED' need not be a literal. Mention the + alternatives and clear up the language a bit. + +2006-05-27 Paul Eggert + + * NEWS: Reword notice for AC_TRY_COMMAND, AC_TRY_EVAL, + ac_config_guess, ac_config_sub, ac_configure. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): + Fix typo that prevented an unnecessary space from being removed. + Problems reported by Ralf Wildenhues in: + http://lists.gnu.org/archive/html/autoconf-patches/2006-05/msg00143.html + +2006-05-26 Paul Eggert + + * doc/autoconf.texi (Particular Programs, Limitations of Usual Tools): + Use better wording to talk about AC_PROG_MKDIR_P's thread-safety. + Don't use the term "thread-safe" to talk about mkdir race + conditions, since the problem is more a process than a thread + issue. Problem reported by Stepan Kasal in: + http://lists.gnu.org/archive/html/autoconf-patches/2006-05/msg00088.html + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Use code that mimics + the test for 'install' more closely. Look at MKDIR_P first. + Look in the PATH, and at /opt/sfw/bin. + Look for a 'gmkdir' program as well (Solaris 10 /opt/sfw/bin/gmkdir). + Don't bother to try mkdir -p, since we already check mkdir --version; + just look at the version number. (There's no easy way to check + for race-free implementations.) + * tests/tools.at (autoconf: subdirectories): Adjust to above + changes, since MKDIR_P now might end in "/mkdir -p". + + * doc/autoconf.texi (autoheader Invocation): Mention that the + first arg of AC_DEFINE_UNQUOTED must be a literal. + Problem reported by Ben Pfaff in + . + + * NEWS: Mention that AC_TRY_COMMAND and AC_TRY_EVAL may be removed. + * doc/autoconf.texi (Special Chars in Variables): New section. + (Preset Output Variables): Warn about special chars in CPPFLAGS. + (Installation Directory Variables): Quote $(datadir) better. + (Limitations of Builtins): Describe some of eval's trickiness. + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): Simplify quoting. + * lib/autoconf/fortram.m4 (_AC_PROG_FC_V_OUTPUT): Likewise. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Put leading space + in front of every arg, not just trailing args. Quote apostrophes. + (_AC_EVAL_ECHO): New macro. + (_AC_EVAL, AC_EVAL_STDERR): Use it. Quote arg of eval. + (AC_TRY_EVAL, AC_TRY_COMMAND): Mention that these macros might get + removed. + (_AC_LINK_IFELSE): Use proper rule for shell continuation lines, + exposed by quoting of eval argument. Put the command on line line + so it logs better. + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): Use eval more safely. + (_AC_PATH_X, AC_PATH_X): Quote more safely. + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Use eval more safely. + * lib/autoconf/specific.m4 (AC_SYS_LONG_FILE_NAMES): Don't use eval. + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Minor style change. + Handle special chars in prefix, ac_srcdir, ac_aux_dir. + Use eval more safely. + (_AC_OUTPUT_CONFIG_STATUS): Adjust to above changes. + * lib/m4sugar/m4sh.m4 (AS_VAR_GET): Note that this API needs + to be replaced. + * tests/base.at (AC_TRY_COMMAND): Use proper rule for shell continuation + lines, exposed by quoting of eval argument. + +2006-05-26 Stepan Kasal + and Ralf Wildenhues + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Drop the + initialization of `ac_cv_exeext', do not override it if it was + already set, unless it was set to `no', for compatibility with + Autoconf-2.13, and comment this. + Do not export `ac_cv_exeext', Libtool hasn't needed this for years. + (_AC_COMPILER_EXEEXT_DEFAULT): Likewise, do not export it. + (_AC_COMPILER_EXEEXT_WORKS, _AC_COMPILER_EXEEXT_CROSS): Typos. + * doc/autoconf.texi (Compilers and Preprocessors) : + Document that this test may be overridden by setting + `ac_cv_exeext'. + +2006-05-26 Ralf Wildenhues + + Revert these two patches: + + 2006-04-06 Eric Blake + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_O): Inside cache + check, s/ac_exeext/ac_cv_exeext/. Fixes regression introduced + 2006-04-01. + + 2006-04-01 Stepan Kasal + Clean up _AC_COMPILER_EXEEXT* macros. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Don't try to + detect exeext, it will be done by _AC_COMPILER_EXEEXT_O; just set + ac_file to the name of the default output file and call + _AC_COMPILER_EXEEXT_WORKS. Move the definition of ac_files and the + initial `rm' of the candidate files... + (_AC_COMPILER_EXEEXT): ... here and simplify them. Moreover, use + the same list in subsequent `rm' calls, and for the temporary + redefinition of ac_clean_files; call _AC_COMPILER_OBJEXT at the end, + and don't call the other _AC_COMPILER_EXEEXT_* macros directly, use... + (_AC_COMPILER_EXEEXT_TESTS): ... this new macro. + (_AC_COMPILER_EXEEXT_O): Don't export ac_cv_exeext, it's not needed (or + no longer needed) by libtool. Make it a cache check. + (_AC_COMPILER_EXEEXT_CROSS): Remove the comment, it was obviously + copied here by mistake. + (AC_NO_EXECUTABLES): Redefine _AC_COMPILER_EXEEXT_TESTS, not + _AC_COMPILER_EXEEXT. + * lib/autoconf/c.m4 (AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC): Do not call + _AC_COMPILER_OBJEXT directly. + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Likewise. + +2006-05-25 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Usual Tools) < sed (`t')>: + Fix description of how the buggy `sed' works. + +2006-05-25 Noah Misch + + Sync from Automake: + + * lib/Autom4te/XFile.pm (lock): Allow EOPNOTSUPP, besides + ENOLCK. Only mention `make -j' when applicable. Only raise + fatal errors when `make -j' is involved. Improve error message. + +2006-05-25 Ralf Wildenhues + + * doc/autoconf.texi (Here-Documents): We now know more about + the variable expansion in here documents bug. + Thanks to Tim Rice and Stepan Kasal. + + * doc/autoconf.texi (Making testsuite Scripts): Add an example + how to use TESTSUITEFLAGS. Suggested by Eric Blake. + +2006-05-24 Ralf Wildenhues + + * tests/autotest.at (Multiline command from M4 expansion): + No failure to be expected if the shell quotes newlines in + commands in the `set -x' output. Report by Tim Rice. + * THANKS: Update. + +2006-05-23 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADER): Don't use shell + expansion in the here-documents used by config.status, as that + runs afoul of the Korn shell version M-12/28/93d bug described in + the Autoconf manual, and this in turn causes a Coreutils 5.95 build to + fail as described by Tim Rice and diagnosed by Ralf Wildenhues in + . + +2006-05-23 Jim Meyering + + * lib/autoconf/functions.m4 (AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK): + Fix typo introduced with 2006-04-02 change. It reversed the sense + of the test. + +2006-05-23 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADER): Simplify ac_dA and + ac_dB slightly, to save bytes in the script. + Max out at 50 lines, rather than 96; this is more likely + (though not guaranteed) to avoid obscure 'sed' failures. + +2006-05-23 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): UnixWare `tr' may interpret + `tr -d -' as bad option argument. Work around this by deleting + an unrelated character. + Report by Tim Rice . + +2006-05-22 Paul Eggert , + Ralf Wildenhues , + Stepan Kasal + + * doc/autoconf.texi (Particular Programs): Do not promise that + we always prefer the GNU version of the program, and that we + search according to PATH; both rules can have exceptions. + Update description of AC_PROG_GREP, AC_PROG_EGREP, AC_PROG_FGREP, + AC_PROG_SED. Move descriptions of limitations + to the Limitations of Usual Tools section. + (Limitations of Usual Tools) : Mention script length + limitations with Solaris /usr/ucb/sed. + : Fix wording for empty alternative. Mention that -c and + -l should not be combined, and that -E and -F should not be + combined. + +2006-05-21 Paul Eggert + and Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_PROG_SED): Catch script length + limits in Solaris 8 /usr/ucb/sed by testing a long script. + +2006-05-22 Stepan Kasal + + * doc/autoconf.texi (Defining Symbols): Literal parameter of + AC_DEFINE is now passed to m4_pattern_allow. + * NEWS: Mention that; likewise for AC_SUBST. + * lib/autoconf/general.m4 (AC_DEFINE_TRACE_LITERAL): Pass + the parameter to m4_pattern_allow. + * tests/tools.at: Add a check for that. + +2006-05-22 Stepan Kasal + + * lib/autoconf/status.m4: Fix typos. + +2006-05-21 Ralf Wildenhues + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Remove + only the files that this macro generates. + +2006-05-21 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools) : For + the HP-UX sed limitation of 99 commands, labels do not count. + * lib/autoconf/status.m4 (_AC_SED_CMD_LIMIT): Mention that + in the comment. + (_AC_OUTPUT_HEADER): Revert the change from 2006-05-19. + +2006-05-21 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): + Import the following fix from coreutils: + + 2006-01-13 Jim Meyering + + Invoke AC_CHECK_FUNCS(getmntent) unconditionally so that tests of + $ac_cv_func_getmntent (e.g., in gl_LIST_MOUNTED_FILE_SYSTEMS) need + not double-quote uses of that variable, to accommodate the rare + case in which getmntent is available in none of the libraries + checked. This happens at least on FreeBSD 5.0. + +2006-05-20 Paul Eggert + + * lib/autoconf/general.m4 (AC_CONFIG_AUX_DIRS): Bring back + ac_config_guess, ac_config_sub, and ac_configure, since evidently + some other programs unwisely rely on these undocumented vars. + But put in warning comments about them. + Problem reported by Ralf Wildenhues in + . + * NEWS: Document that these variables are intended to go away. + +2006-05-20 Ralf Wildenhues + + * lib/autoconf/c.m4 (AC_PROG_CXX_C_O): Require AC_PROG_CXX, + and set the language to C++ (analogous to the equivalent Fortran + tests). + + * lib/autoconf/c.m4 (AC_PROG_CXX_C_O): New macro. + * doc/autoconf.texi (C++ Compiler): Document it. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_C_O): Adjust comment. + * NEWS: Update. + +2006-05-19 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADER): Fix off-by-one bug + that caused config.status to generate 100-command sed scripts; the + portable limit is 99. + +2006-05-19 Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): Name temporary + variable `ac_d' instead of `d' to avoid infringing namespace. + Report by Ralf Menzel. + +2006-05-18 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): Don't prepend + $ac_top_build_prefix to $MKDIR_P if it's just 'mkdir -p'. + * tests/tools.at (autoconf: subdirectories): New test, taken from + the corresponding problem report by Ralf Wildenhues in: + http://lists.gnu.org/archive/html/autoconf-patches/2006-05/msg00053.html + + * lib/autoconf/functions.m4 (AC_REPLACE_FNMATCH, AC_FUNC_FNMATCH_GNU): + Quote some uses of shell variables if they might suffer unexpected + globbing. This doesn't fix all instances of quoting problems that + I found, just the easy ones that look safe. + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR, _AC_INIT_HELP): + (AC_CONFIG_AUX_DIR, AC_CONFIG_AUX_DIR_DEFAULT, AC_CONFIG_AUX_DIRS): + (AC_CANONICAL_BUILD, AC_CANONICAL_HOST, AC_CANONICAL_TARGET): + (AC_CACHE_LOAD, AC_CACHE_SAVE): Likewise. + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF, _AC_PATH_X_DIRECT): Likewise. + * lib/autoconf/specific.m4 (AC_SYS_LONG_FILE_NAMES): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_LINK, _AC_OUTPUT_SUBDIRS): + Likewise. + * lib/autotest/general.m4 (_AC_INIT_PARSE_ARGS): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Likewise. + +2006-05-18 Ralf Wildenhues + + * bin/autoreconf.in ($help): Reword according to the manual. + Suggested by Olly Betts. + +2006-05-17 Olly Betts (tiny change) + and Ralf Wildenhues + + * bin/autoreconf.in: Pass the directory argument to + `require_configure_ac'. Fix comment. + * tests/torture.at (Configuring subdirectories): Expose this. + Reported by Olly Betts. + +2006-05-17 Ralf Wildenhues + + * lib/Automake/Configure_ac.pm, lib/Automake/Channels.pm, + lib/Automake/FileUtils.pm, lib/Automake/Struct.pm: Sync from + Automake as follows: + + * lib/Autom4te/Configure_ac.pm (find_configure_ac): Use + `$configure_in' instead of `configure.in', to preserve + directory component. + +2006-05-17 Ralf Wildenhues + + * config/config.guess, config/config.sub, config/texinfo.tex, + doc/make-stds.texi, doc/standards.texi: Sync from upstream. + +2006-05-14 Paul Eggert + + * lib/autoconf/headers.m4 (AC_HEADER_STDBOOL): Fix overly-picky + test for C99 conformance; (bool) 0.5 is an integer constant + expression, but (bool) -0.5 is not. Problem reported by Fedor + Sergeev in . + +2006-05-13 Paul Eggert + + * doc/autoconf.texi (Particular Programs): AC_PROG_MKDIR_P now + sets MKDIR_P, not mkdir_p, to avoid collisions with Automake. + Warn about obsolete install-sh files. Remove stray sentence + fragment and fix cross reference. + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Don't insist on + install -d; this undoes the 2006-05-10 change. + (MKDIR_P): Mark with AN_MAKEVAR. + (AC_PROG_MKDIR_P): Fall back on $ac_install_sh, not $INSTALL, so + that we don't require $INSTALL to be thread-safe. Move comments + out of generated code. Require AC_CONFIG_AUX_DIR_DEFAULT instead + of AC_PROG_INSTALL. Output a message saying that we're checking + mkdir -p. Set MKDIR_P rather than mkdir_p. Do special magic for + MKDIR_P instead of AC_SUBST. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE, _AC_OUTPUT_CONFIG_STATUS): + Special magic for MKDIR_P, too. + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): Remove comment that defeated + a dnl. + * tests/local.at (AT_CHECK_ENV): mkdir_p -> MKDIR_P. + +2006-05-11 Paul Eggert + + Sync from Automake, as follows: + + 2006-05-11 Ralf Wildenhues + * config/install-sh: Initialize IFS, so field splitting isn't + turned off later. + * config/mkinstalldirs: Likewise. + * config/missing: Remove superfluous quotes. Replace all uses of + `[' by `test', for consistency, and for.. + * config/missing (sed_minuso, sed_output): New variables. + (autom4te, help2man, makeinfo): Use them. Unifies detection of + `-o FILE', `--output FILE', `--output=FILE', stricter regex. + Fixes `missing' to detect `--output' for help2man. Fixes + PR automake/483. Report by Dennis J. Linse. + (autom4te): Document in `missing --help'. + +2006-05-10 Paul Eggert + + * NEWS: New macro AC_PROG_MKDIR_P. AS_MKDIR_P is now more robust. + * config/install-sh: Don't use 'path' to talk about file names, + as per GNU coding standards. Close a race condition reported by Ralf + Wildenhues and Stepan Kasal. There is still a race condition + on hosts that predate Posix 1003.1-1992, but we can't help this. + Don't mishandle weird characters like space on pre-Posix hosts. + Invoke mkdir at most once per dir arg on pre-Posix hosts. + * doc/autoconf.texi (Programming in M4sh): Cross-reference to + AC_PROG_MKDIR_P from AS_MKDIR_P. + (Limitations of Usual Tools): Cross-reference to AC_PROG_MKDIR_P + from mkdir. Mention that Autoconf 2.60 install-sh is safe but + earlier editions are not (including Automake 1.8.3). + Do not suggest mkinstalldirs for thread-safety. + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Insist on an 'install' + that understands -d, so that AC_PROG_MKDIR_P can fall back on $INSTALL. + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): Make it more robust in the + presence of special characters and race conditions. + * tests/local.at (AT_CHECK_ENV): Add mkdir_p to the list of variables + in Autoconf's name space. + +2006-05-10 Bruno Haible + and Paul Eggert + + * lib/autoconf/programs.m4 (AC_PROG_MKDIR_P): New macro, taken + from Automake with minor changes. + * doc/autoconf.texi (Particular Programs): Document AC_PROG_MKDIR_P. + +2006-05-10 Paul Eggert + + * config/install-sh: Update to Automake CVS version, as follows: + 2006-04-25 Stepan Kasal + * lib/install-sh: Simplify the expr implementation of dirname. + 2006-04-24 Paul Eggert + * lib/install-sh: Handle --, and diagnose unknown options. + +2006-05-09 Ralf Wildenhues + + * tests/Makefile.am (AUTOTEST): Use `$(MY_AUTOM4TE)' instead of + `./autom4te' to create `./testsuite', since the `all' target + will ensure its presence, but `installcheck' should not create + the uninstalled wrappers. + + * tests/torture.at (Unusual Automake input files): Skip if we + detect automake < 1.8. + +2006-05-07 Ralf Wildenhues + + * lib/autoconf/c.m4 (AC_PROG_CC_STDC): If ac_cv_prog_cc_stdc + is set to `no', then that overrides and sets ac_cv_prog_cc_c89 + and ac_cv_prog_cc_c99 to `no', for backward compatibility. + * NEWS: Update. + +2006-05-06 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Take care not to + munge (multiple) white space and other oddities. + * tests/torture.at (AT_CHECK_AC_ARG_VAR): Make sure to M4-escape + single quotes in variable assignment. + (AC_ARG_VAR, configure invocation): Adjust tests to expose this + and similar failures by adding multiple spaces, tabs, and other + special characters. + Report and different test suggested by Francesco Romani + and Andrew Church . + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): When we escape + single quotes, we only need to search for single quotes; this + both simplifies the search pattern, and makes us less + susceptible to `echo' variations for arguments not containing + single quotes. + (_AC_ARG_VAR_VALIDATE): Likewise. + +2006-05-04 Ralf Wildenhues + + * doc/autoconf.texi (Special Shell Variables) : Document + `$*' and IFS concatenation issue with traditional shells and + bash-2.04. Report by Seanster@Seanster.com. + +2006-05-03 Bruno Haible + + * doc/autoconf.texi (Limitations of Usual Tools): Identify more + precisely which Mac OS X versions have the od problem. + +2006-05-02 Paul Eggert + + * doc/autoconf.texi: Use @option systematically. + +2006-05-02 Paul Eggert + and Bruno Haible + + * doc/autoconf.texi (Limitations of Usual Tools): Add a paragraph + about 'od'. + (Integer Overflow): Mention the special case of integer division + overflow. + +2006-05-02 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): Cater for + traditional shells like the Solaris one that do not use the + first IFS character for assembling `$*'. + Prompted by a related report from autoconf_bug@nro.ca. + +2006-05-01 Paul Eggert + and Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Builtins, Limitations of Make): + Mention more problems with the -e option. + +2006-04-30 Ralf Wildenhues + + * NEWS: Typo. + * doc/autoconf.texi (Systemology): Mention the Heirloom Project. + + * doc/autoconf.texi (Introduction, Pointers): Use `@/' liberally + in URLs to improve DVI formatted output (requires texinfo 4.6). + (System Services, Systemology, Shellology): Likewise. + (Limitations of Usual Tools): Rewrite Mac OS X example for nicer + output. + + * doc/autoconf.texi (Fortran Compiler): Do not use `@ovar' in + continuous text. + (Runtime): Fix macro argument names to match description: + `action-if-found' -> `action-if-true' and similarly. + (Obsolete Macros): Likewise. + * lib/autoconf/general.m4 (_AC_COMPILE_IFELSE): Likewise. + (AC_COMPILE_IFELSE, AC_TRY_COMPILE, _AC_LINK_IFELSE) + (AC_LINK_IFELSE, AC_TRY_LINK, AC_COMPILE_CHECK): Likewise. + +2006-04-29 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Make): Clean up markup. + + * ChangeLog: Typo. + * doc/autoconf.texi (Portable Shell): Allow wrapped URLs, for + DVI output. + +2006-04-28 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Builtins): Document FreeBSD + /bin/sh set unsorted output. + * lib/autoconf/general.m4 (_AC_CACHE_DUMP): Adjust. + * tests/local.at: Likewise. + +2006-04-26 Paul Eggert + + * doc/autoconf.texi (Portable C and C++, Varieties of Unportability): + (Integer Overflow, Null Pointers, Buffer Overruns): + (Floating Point Portability, Exiting Portably): New sections. + (Writing Test Programs): Fix some langauge. Recommend exiting + with status 1, not merely nonzero. Clarify exit declaration. + (Run Time): Move C exit status stuff to new Exiting Portably section. + (Systemology): Mention Posix and levenez. Update v7 reference. + (Portable Shell): Mention the Posix shell. + +2006-04-25 Stepan Kasal + + * bin/autoconf.as (me): Replace by as_me. + +2006-04-25 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Don't use AS_ERROR, + since as_me isn't set yet. + +2006-04-23 Paul Eggert + + Prepare for deprecation of AS_BASENAME and AS_DIRNAME, and fix + a few minor bugs in this area. + + * doc/autoconf.texi (Programming in M4sh): Comment out the + documentation of AS_BASENAME, for now. + (Shell Substitutions): Do not use AS_DIRNAME in an example. + (Limitations of Builtins) : Do not refer to + AS_BASENAME. + * bin/autoconf.as (me): Don't use AS_BASENAME. + (dir): Remove the unused variable. + * lib/m4sugar/m4sh.m4 (_AS_DETECT_REQUIRED): Renamed from + AS_DETECT_REQUIRED. All uses changed. + (_AS_DETECT_SUGGESTED): Renamed from AS_DETECT_SUGGESTED. + All uses changed. + (_AS_DETECT_BETTER_SHELL): Put ;; at the end of a case. + (AS_BASENAME): Use "basename --" to protect against leading "-". + (_AS_BASENAME_EXPR): Renamed from AS_BASENAME_EXPR. All uses changed. + (_AS_BASENAME_SED): Renamed from AS_BASENAME_SED. All uses changed. + (_AS_BASENAME_PREPARE): Reject implementations that cannot handle "--". + (_AS_DIRNAME_PREPARE): Likewise. + (_AS_DIRNAME_EXPR): Renamed from AS_DIRNAME_EXPR. All uses changed. + (_AS_DIRNAME_SED): Renamed from AS_DIRNAME_SED. All uses changed. + (AS_DIRNAME): Use "dirname --". + +2006-04-23 Paul Eggert + + * doc/autoconf.texi (Runtime): Renamed from "Run Time". All uses + of "run time" and "run-time" changed to "runtime", for consistency. + * lib/autoconf/fortran.m4: Likewise (in comment). + * lib/autoconf/functions.m4: Likewise. + * lib/autoconf/general.m4: Likewise. + * lib/autoconf/headers.m4: Likewise. + + * doc/autoconf.texi (Run Time): Document the exit status situation + with more accuracy and detail. + +2006-04-23 Ralf Wildenhues + + * doc/autoconf.texi (Introduction): The GNU Autoconf Macro + Archive is not officially `GNU' any more. Update URL. + (Defining Directories): Likewise + * lib/autoconf/c.m4 (AC_C_RESTRICT): Update URL. + +2006-04-19 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Remove the leading + newline from the `trap' code to finish `config.log'; the NetBSD + /bin/sh resets the exit status after an empty command, as + documented in doc/autoconf.texi. + Reported by Dalibor Topic . + +2006-04-19 Paul Eggert + + * doc/autoconf.texi (C Compiler): Clarify AC_C_TYPEOF. + Suggested by Bruno Haible. + +2006-04-18 Paul Eggert + + * configure.ac (ac_cv_sh_n_works): Don't try to test for it, since + some shells (e.g., Solaris 8 /bin/sh) implement it verrrry slowly. + Instead, just list the shells that we know work. + * tests/local.at (AT_CHECK_SHELL_SYNTAX): Remove 2nd arg. All uses + changed. Be more cautious about the _cv_ variable. + * tests/tools.at (Syntax of the shell scripts): Check the + _cv_ variable once, at first, to avoid an internal autoconf error + when sh -n does not work. + +2006-04-17 Ralf Wildenhues + + * lib/Autom4te/FileUtils.pm: Sync from Automake. + +2006-04-16 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_CONFIG_LOG): Don't + use ">&-" since we're only 99.999% sure that this is portable, + and since the MinGW bug is fixed in a different way. + * lib/autotest/general.m4 (AT_INIT): Likewise. + +2006-04-16 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Handle --recheck + before opening config.log, to avoid hitting a bug on MinGW. + +2006-04-14 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_CONFIG_LOG): Close + AS_MESSAGE_LOG_FD before reopening it onto the log file. + This works around a MinGW bug reported by Eric Paire. + Make sure that all writes to the log file append to it, + rather than possibly losing data. + * lib/autotest/general.m4 (AT_INIT): Likewise. + +2006-04-14 Stepan Kasal + + * lib/Autom4te/FileUtils.pm (find_file): Fix a typo in the + description. + +2006-04-13 Ralf Wildenhues + + * NEWS: Update. + + * configure.ac (AC_INIT): Bump to 2.59d. + +2006-04-12 Ralf Wildenhues + + Version 2.59c. + + * Makefile.maint (news-date-check): Do not require a leading `*' + before the release date in NEWS. + +2006-04-12 Stepan Kasal + and Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILE): If the templates for + the instantiated file do not contain the string 'datarootdir' + but contain @datadir@, @docdir@, @infodir@, @localedir@, or + @mandir@, replace the reference '${datarootdir}' by the value. + * tests/torture.at (datarootdir workaround): New test. + * NEWS: Advertise this temporary fixup. + Based on a patch by Bruno Haible, reported and analyzed by + Paul Eggert and Noah Misch. + +2006-04-12 Eric Blake + + * tests/autotest.at (Debugging a failed test): Fix comment. + +2006-04-12 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (_AS_LN_S_PREPARE): Simplify the summary of + all the changes since 2006-04-07. + +2006-04-11 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_LN_S_PREPARE): If `ln -s file1 file2' + succeeded, but `ln -s file dir' failed, take care to remove the + leftover target before the next test, to prevent its spurious + failure; also make sure `ln file dir' works before selecting it. + Thanks to Keith Marshall for pointing this out. + * THANKS: Update. + + * lib/autotest/general.m4 (AT_INIT): Store quoted variable + assignments in `at_debug_args', so that we put them correctly + in the `run' script. + * tests/autotest.at (Debugging a failed test): Unmark XFAIL. + Reported by Eric Blake. + +2006-04-11 Eric Blake + + * tests/autotest.at (AT_CHECK_AT): Add new argument, to allow + top-level tests after micro-suite has been run. Used in... + (Debugging a successful test, Debugging script and environment), + (Debugging a failed test): ...these new tests. The first of these + is fixed by... + * lib/autotest/general.m4 (_AT_CREATE_DEBUGGING_SCRIPT): New + macro, split out from... + (AT_INIT): ...here, so that using -d also generates a run script. + Document that -d inhibits top-level logging. + * doc/autoconf.texi (testsuite Invocation): Document that -d only + inhibits top-level logging; debug scripts are created. + + * lib/autotest/general.m4 (_AT_CHECK): Avoid syntax error on empty + check. + * tests/autotest.at (Empty test, Empty check): New test to check it. + + * lib/autoconf/c.m4 (AC_C_CONST, AC_C_VOLATILE): Avoid warnings + from gcc. + +2006-04-10 Stepan Kasal + + * tests/mktests.sh: Use "trap '' 0", not "trap 0". Do not touch + the files if a problem appears. Make the empty *.at files + read-only, too. Proposed by Ralf Wildenhues. + +2006-04-10 Ralf Wildenhues + + * config/Makefile.am: Add comment to force updated Makefile.in. + + * lib/freeze.mk: Fix typo in comment. Unlike the last, white + space only patch to this file, this patch causes the Makefile.in + files that include freeze.mk to be updated, and thus have a + newer time stamp again, which in turn makes a pristine CVS + checkout have correct time stamps. + + * Makefile.maint (cvs-sv): New macro, to be used.. + (config.guess-url_prefix, config.sub-url_prefix) + (texinfo.tex-url_prefix, standards.texi-url_prefix): ..here; + point to CVS text checkout of Gnulib files. + (copyright-check): Bump current year. + (announcement): Do not hard-wire `./announce-gen'. + (cvs-update): Propagate failures of `cvs' and `move-if-change' + correctly. + * Makefile.cfg (executable-update): Use `chmod a+x' instead of + `chmod +x'. + (wget_files): Update config.guess, config.sub, texinfo.tex by + `wget-update', now that their URLs work again. + +2006-04-10 Paul Eggert + + * doc/autoconf.texi (Particular Types): Don't use AC_CHECK_TYPE. + Problem noted by Paul D. Smith. + +2006-04-10 Ralf Wildenhues + + * doc/autoconf.texi: Remove unused words from word list. + * .x-sc_prohibit_atoi_atof, .x-sc_space_tab, .x-sc_sun_os_names, + .x-sc_trailing_space: New files. + + * doc/standards.texi: Sync from gnulib. + + * NEWS, doc/autoconf.texi (AC_LIBOBJ vs LIBOBJS): Mark + `LIBOBJDIR' as experimental. + + * lib/m4sugar/m4sh.m4 (_AS_LN_S_PREPARE): MSYS `ln -s' fails + with a target directory; it's internally implemented as `cp' + anyway, but since Autoconf advertises the possibility to use + a target directory when LN_S is `ln -s', we need to find out. + Reported by Rolf Ebert against MSYS, + analyzed by Keith Marshall . + + * THANKS: Update. + +2006-04-10 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Just output + confdefs.h as-is. In general, if it has backslash-newline or the + like, then it doesn't work either to sort or to remove empty + lines. + +2006-04-09 Stepan Kasal + + * tests/Makefile.am (AUTOCONF_FILES): Fix typo in the comment. + +2006-04-09 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect + _AM_SUBST_NOTMAKE. + +2006-04-08 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Use '\'' for an + apostrophe within a single-quoted string, as this is the usual + tradition and is easier to read than '"'"'. Don't rely on the + shell treating "$/" like '$/'. Use a more-consistent indenting + style for the trap. + +2006-04-09 Eric Blake + + * tests/autotest.at (Backquote command substitution), + (Multiline backquote command substitution): Remove mistaken + AT_NO_CMDSUBST from the 2006-03-14 patch, which was meant to be + applied... + (Parenthetical command substitution, Multiline parenthetical + command substitution): here. + +2006-04-08 Paul Eggert + + Import macros from gnulib (often changing their name). + + * NEWS: AC_C_TYPE_LONG_DOUBLE is now obsolete. + New macros AC_CHECK_DECLS_ONCE, AC_CHECK_FUNCS_ONCE, + AC_CHECK_HEADERS_ONCE, AC_FUNC_STRTOLD, AC_HEADER_ASSERT, + AC_STRUCT_DIRENT_D_INO, AC_STRUCT_DIRENT_D_TYPE, + AC_TYPE_LONG_DOUBLE, AC_TYPE_LONG_DOUBLE_WIDER, AC_TYPE_INT8_T, + AC_TYPE_INT16_T, AC_TYPE_INT32_T, AC_TYPE_INT64_T, + AC_TYPE_INTMAX_T, AC_TYPE_INTPTR_T, AC_TYPE_LONG_LONG_INT, + AC_TYPE_UINT8_T, AC_TYPE_UINT16_T, AC_TYPE_UINT32_T, + AC_TYPE_UINT64_T, AC_TYPE_UINTMAX_T, AC_TYPE_UINTPTR_T, + AC_TYPE_UNSIGNED_LONG_LONG_INT, AC_USE_SYSTEM_EXTENSIONS. + The manual mentions Gnulib more prominently. + * doc/autoconf.texi (Gnulib): New node. + (Pointers): Add Gnulib URL. + (Particular Functions): Alphabetize. Add AC_FUNC_STRTOLD. + (Generic Functions): Add AC_CHECK_FUNCS_ONCE. Refer to new + Gnulib section. + (Particular Headers): Add AC_HEADER_ASSERT. For stdbool.h, + suggest a #define rather than a typedef for _Bool, and mention + Gnulib rather than trying to substitute stdbool code. + (Generic Headers): Add AC_CHECK_HEADERS_ONCE. + (Generic Declarations): Add AC_CHECK_DECLS_ONCE. + (Particular Structures): Add AC_STRUCT_DIRENT_D_INO, + AC_STRUCT_DIRENT_D_TYPE. + (Particular Types): Mention stdint.h and inttypes.h as standard + headers too. + Add AC_TYPE_INT8_T, AC_TYPE_INT16_T, AC_TYPE_INT32_T, AC_TYPE_INT64_T, + AC_TYPE_INTMAX_T, AC_TYPE_INTPTR_T, AC_TYPE_LONG_DOUBLE, + AC_TYPE_LONG_DOUBLE_WIDER, AC_TYPE_LONG_LONG_INT, AC_TYPE_UINT8_T, + AC_TYPE_UINT16_T, AC_TYPE_UINT32_T, AC_TYPE_UINT64_T, + AC_TYPE_UINTMAX_T, AC_TYPE_UINTPTR_T, AC_TYPE_UNSIGNED_LONG_LONG_INT. + (C Compiler): Move AC_C_LONG_DOUBLE to ... + (Obsolete Macros): here. Under AC_LONG_DOUBLE, mention + AC_TYPE_LONG_DOUBLE or AC_TYPE_LONG_DOUBLE_WIDER instead. + (Posix Variants): Add AC_USE_SYSTEM_EXTENSIONS. + (Coding Style). Don't mention m4_expand_once. + * lib/autoconf/c.m4 (AC_C_LONG_DOUBLE): Implement via + AC_TYPE_LONG_DOUBLE_WIDER. Now obsolete. + * lib/autoconf/functions.m4 (_AH_CHECK_FUNCS): New macro. + (AC_CHECK_FUNCS): Use it. + (AC_CHECK_FUNCS_ONCE, AC_FUNC_STRTOLD): New macros. + (AC_FUNC_WAIT3): "the Open Group standards" -> "POSIX". + * lib/autoconf/general.m4 (AC_CHECK_DECLS_ONCE): New macro. + * lib/autoconf/headers.m4 (AC_CHECK_HEADERS_ONCE): New macro. + (AC_HEADER_ASSERT): New macro. + (AC_HEADER_STDBOOL): Don't assume "#error" works. + Catch a bug in IBM AIX xlc compiler version 6.0.0.0. + Catch a bug in an HP-UX C compiler. + * lib/autoconf/specific.m4 (AC_USE_SYSTEM_EXTENSIONS): New macro. + * lib/autoconf/types.m4 (AC_TYPE_INTMAX_T. AC_TYPE_UINTMAX_T): + (AC_TYPE_INTPTR_T, AC_TYPE_UINTPTR_T. AC_TYPE_LONG_DOUBLE): + (AC_TYPE_LONG_DOUBLE_WIDER, AC_C_LONG_DOUBLE, AC_TYPE_LONG_LONG_INT): + (AC_TYPE_UNSIGNED_LONG_LONG_INT, _AC_TYPE_INT, _AC_TYPE_UNSIGNED_INT): + (_AC_STRUCT_DIRENT, AC_STRUCT_DIRENT_D_INO, AC_STRUCT_DIRENT_D_TYPE): + New macros. + + * tests/mktests.sh (ac_exclude_list, au_exclude_list): Do not + use /^foo|bar$/, it does not mean /^(foo|bar)$/. + +2006-04-08 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Fix the wording + of the warning introduced by the 2001-08-28 change. + +2006-04-08 Stepan Kasal , + Ralf Wildenhues + + * lib/autoconf/general.m4 (AC_CACHE_SAVE): All `ac_cv_env_foo' + variables shall be overriden by the cache. + * tests/torture.at (AC_ARG_VAR): Test also with a first value + that contains braces. + +2006-04-07 Stepan Kasal + + Revert the patch from 2006-04-01 and only improve + _AS_DETECT_BETTER_SHELL: + + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Do not optimize; do not + skip nonexistent directories. + (_AS_DETECT_BETTER_SHELL): The optimization is moved here--try + only shell candidates which exist. + (AS_UNAME): No need to give three parameters to _AS_PATH_WALK. + * lib/autotest/general.m4 (AT_INIT): No need to give three + parameters to _AS_PATH_WALK. + +2006-04-07 Stepan Kasal , + Ralf Wildenhues + + * bin/autoupdate.in (handle_autoconf_patches): Change the way we + distinguish m4sugar macros. + * tests/tools.at (autoupdating with aclocal and m4_include): + New test. Bug reported by Gary V. Vaughan , + test case by Noah Misch . + +2006-04-07 Stepan Kasal + + Revert my change from 2006-03-17, in other words: + * lib/m4sugar/m4sh.m4 (AS_BOURNE_COMPATIBLE): Insert BIN_SH=xpg4 + and DUALCASE=1. + (AS_SHELL_SANITIZE): Remove DUALCASE=1. + * doc/autoconf.texi (Special Shell Variables) : Say that + it is set. + +2006-04-07 Eric Blake + + * doc/autoconf.texi (Programming in M4sh): Document that + AS_MKDIR_P exits the script on failure. + * lib/autotest/general.m4: Remove redundant AS_ERROR. + +2006-04-07 Ralf Wildenhues + + * config/elisp-comp, config/install-sh, config/mdate-sh, + config/missing, config/mkinstalldirs: Sync from Automake. + + * lib/Autom4te/FileUtils.pm, lib/Autom4te/Struct.pm: Sync + from Automake. + + * doc/make-stds.texi: Sync from gnulib. + +2006-04-06 Eric Blake + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_O): Inside cache + check, s/ac_exeext/ac_cv_exeext/. Fixes regression introduced + 2006-04-01. + +2006-04-06 Stepan Kasal , + Eric Blake , + Paul Eggert , + Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_CACHE_DUMP): Fix the detection of + whether `set' quotes correctly: redirect stderr of the tested + `set', and use a subshell, for Ultrix; use `sed' instead of + `grep' for zsh `set' which may write binary output; match only + at the beginning of a line, to avoid false positives. + In order to avoid false positives by unrelated variables with + multiline content, put the dump algorithm in a subshell and + unset all variables containing newlines (except some which are + special to the shell). Warn about cache variables that are + unset. + +2006-04-06 Ralf Wildenhues + + * config/config.guess, config/config.sub, config/texinfo.tex: + Sync from upstream. + + * tests/mktests.sh: Reword comments. + + * tests/mktests.sh: Only skip internal macros starting with + `_AC_' or `__AC_'. Noted by Stepan Kasal. + Update exclusion lists for the test suite to this end: + (AC_ARG_VAR): Do test this now. + (AC_SEARCH_LIBS, AC_REPLACE_FUNCS): Need an argument. + (AC_LINKER_OPTION): Remove (renamed to _AC_LINKER_OPTION). + (AC_LIST_MEMBER_OF): Likewise (renamed to _AC_LIST_MEMBER_IF). + (AC_LINK_FILES): Obsoleted since (and thus AU_DEFUN'ed). + + * doc/autoconf.texi (Shell Substitutions): Mention the MSYS + shell issue with double-quoted command substitutions of native + commands. + Reported to MSYS by Mark Cave-Ayland, to Autoconf by Keith + Marshall. + + * Makefile.maint (sc_cast_of_argument_to_free): Do not fail when + no file matches the glob, discard the warning, set `nullglob'. + (syntax-check): Likewise. + (sc_cast_of_x_alloc_return_value): Likewise. + (sc_cast_of_alloca_return_value, sc_error_exit_success) + (sc_prohibit_jm_in_m4, .re-list, sc_unmarked_diagnostics) + (m4-check): Likewise. + (sc_system_h_headers): Do not print rule on execution. + (sc_tight_scope): Do not fail for non-existing `src' directory. + (sc_changelog): Skip the Copyright footer. + * lib/autoconf/lang.m4: Remove trailing space. + + * lib/autoconf/status.m4: More replacements to + where this makes sense. + +2006-04-06 Stepan Kasal + + * tests/Makefile.am (maintainer-check-posix): + s/POSIXLY_CORRECTLY/POSIXLY_CORRECT/ + + * lib/autoconf/status.m4 (_AC_CONFIG_FOOS): Append TAGS to + ac_config_s again, sometimes normalized, sometimes not. + (AC_CONFIG_FILES, AC_CONFIG_HEADERS, AC_CONFIG_LINKS): + (AC_CONFIG_COMMANDS): Do not do so here. + (_AC_CONFIG_REGISTER_DEST): Double quote the tags in macros _AC_LIST_TAGS + and_AC_LIST_TAG_COMMANDS; fixes another regression introduced by the + 2005-07-25 rewrite. Noticed by Noah Misch. + + * lib/autoconf/general.m4 (AC_PRESERVE_HELP_ORDER): Do not define + _AC_PRESERVE_HELP_ORDER, ... + (AC_ARG_ENABLE, AC_ARG_WITH): ... use AC_PROVIDE_IFELSE insetad. + + * lib/autoconf/general.m4 (AC_ARG_VAR): Do not use m4_divert_once + inside m4_expand_once; it is redundant. + + * lib/autoconf/general.m4 (_AC_INIT_HELP): Remove the broken support + for --help from Cygnus `configure.' + +2006-04-06 Paul Eggert + + * doc/autoconf.texi (C Compiler): Warn about #error. Follows up + on a patch proposed by Ralf Wildenhues. + +2006-04-05 Paul Eggert + + * lib/autoconf/status.m4: Replace '' with + where this makes sense. + +2006-04-05 Howard Chu (trivial change) + Noah Misch + + * lib/autoconf/general.m4 (AC_PRESERVE_HELP_ORDER): New macro. + (AC_ARG_ENABLE, AC_ARG_WITH): Adjust. + * doc/autoconf.texi (Help Formatting): New node. + * NEWS: Announce AC_PRESERVE_HELP_ORDER. + +2006-04-05 Ralf Wildenhues + + * TODO, config/Makefile.am, lib/freeze.mk, lib/autoconf/c.m4, + lib/autoconf/specific.m4, lib/autoconf/status.m4, + lib/autoconf/types.m4, lib/autotest/general.m4, + tests/mktests.sh, tests/torture.at: White space cleanup: + remove some SPACE before TAB, or add quoting ('' or @&t@). + + * NEWS, TODO, bin/autoreconf.in: `filesystem' -> `file system'. + + * doc/autoconf.texi (Shell Substitutions): Document `^' vs. `|'. + +2006-04-05 Eric Blake + + * lib/autotest/general.m4 (AT_INIT): Prep AT_*_all, so that an + empty test suite works. + * tests/autotest.at (Empty test suite): Remove xfail. + +2006-04-05 Noah Misch + + * lib/autoconf/status.m4 (_AC_CONFIG_FOOS): Do not append normalized + TAGS to ac_config_s. + (AC_CONFIG_FILES, AC_CONFIG_HEADERS, AC_CONFIG_LINKS): Do so here. + (AC_CONFIG_COMMANDS): Append NAME to ac_config_commands without + normalizing it, consistent it with previous releases. + * tests/torture.at (Macro calls in AC_CONFIG_COMMANDS tags): New test. + +2006-04-05 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_BASENAME_EXPR, AS_DIRNAME_EXPR): + Use simplified args that Eric Blake originally suggested. + +2006-04-04 Paul Eggert + + * tests/mktests.sh: Don't use 'cat'; just read the files directly. + Prefer 'sort -u' to 'sort | uniq'. Filter data before sorting it. + Use 'comm' rather than N instances of grep; this also fixes a bug + whereby substrings were incorrectly matched, causing us to not + generate tests for AC_F77_NAME_MANGLING and AC_FUNC_LSTAT. + (exclude_list): Exclude empty macros. + (ac_exclude_list): Exclude AC_INCLUDES_DEFAULT. + + Use awk rather than grep -E or egrep, to avoid + portability problems with regular expressions containing newlines. + (exclude_list, ac_exclude_list, au_exclude_list, ac_exclude_script): + Switch from grep to awk syntax. + (ac_exclude_script): Renamed from ac_exclude_egrep. + (au_exclude_script): Renamed from au_exclude_egrep. + +2006-04-04 Noah Misch + + * lib/autoconf/general.m4 (_AC_INIT_HELP): Only `configure.in' evidences + a subdirectory subject to Cygnus `configure'. + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Likewise. + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Omit the bug + report request when we have no AC_PACKAGE_BUGREPORT. + +2006-04-03 Ralf Wildenhues + + * THANKS: Update. + + * tests/mktests.sh: Update copyright year in the header of the + generated files. + + * lib/autoconf/c.m4 (AC_C_INLINE): Do not skip cleanup code. + (AC_C_RESTRICT): Likewise. Furthermore, add a function with a + typedef'ed restricted pointer, to catch a compiler bug on + HP-UX 11.x, and fix warnings so it passes with -Werror. + (_AC_PROG_CC_C99): Likewise. + Reported by Albert Chin . + * tests/mktests.sh: Do not skip AC_C_INLINE, AC_C_RESTRICT. + +2006-04-03 Noah Misch + + * bin/autoscan.in (subdirs): New global. + (scan_file): Prune directories with configure{,.{ac,in,gnu}}. + (output): Emit AC_CONFIG_SUBDIRS as needed. + * tests/autoscan.at (autoscan): Remove XFAIL. + +2006-04-03 Noah Misch + + * lib/autoconf/general.m4 (AC_CACHE_SAVE): Use AC_MSG_NOTICE. + +2006-04-03 Eric Blake + + * THANKS: Add myself. + +2006-04-03 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT): Add `at_testdir' to pointer + to log, point to testsuite output tree. + +2006-04-02 Paul Eggert + + * NEWS: AC_PROG_CC and AC_PROG_CXX no longer declare 'exit'. + * doc/autoconf.texi (Function Portability): Mention that C++ + has trouble with 'exit'. + (Guidelines): Test programs shouldn't use 'exit'. + * lib/autoconf/c.m4 (_AC_PROG_CXX_EXIT_DECLARATION): + Remove; all uses removed. + (AC_LANG_INT_SAVE(C), AC_C_BIGENDIAN): + Return from 'main' instead of calling 'exit'. + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA, AC_FUNC_CLOSEDIR_VOID): + (_AC_FUNC_FNMATCH_IF, AC_FUNC_GETGROUPS): + (AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK, _AC_FUNC_MALLOC_IF): + (AC_FUNC_MEMCMP, AC_FUNC_MKTIME, AC_FUNC_MMAP, _AC_FUNC_REALLOC_IF): + (AC_FUNC_SETPGRP, _AC_FUNC_STAT, AC_FUNC_STRTOD, AC_FUNC_STRERROR_R): + (AC_FUNC_STRNLEN, AC_FUNC_SETVBUF_REVERSED, AC_FUNC_UTIME_NULL): + (_AC_FUNC_FORK, _AC_FUNC_VFORK, AC_FUNC_WAIT3): Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_STDC): Likewise. + * lib/autoconf/specific.m4 (AC_SYS_RESTARTABLE_SYSCALLS): Likewise. + * lib/autoconf/types.m4 (AC_TYPE_GETGROUPS): Likewise. + * tests/compile.at: Likewise. + +2006-04-02 Pavel Roskin + + * doc/autoconf.texi (AC_PATH_X): Update per 2005-08-26 change. + +2006-04-01 Stepan Kasal + + Clean up _AC_COMPILER_EXEEXT* macros. + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Don't try to + detect exeext, it will be done by _AC_COMPILER_EXEEXT_O; just set + ac_file to the name of the default output file and call + _AC_COMPILER_EXEEXT_WORKS. Move the definition of ac_files and the + initial `rm' of the candidate files... + (_AC_COMPILER_EXEEXT): ... here and simplify them. Moreover, use + the same list in subsequent `rm' calls, and for the temporary + redefinition of ac_clean_files; call _AC_COMPILER_OBJEXT at the end, + and don't call the other _AC_COMPILER_EXEEXT_* macros directly, use... + (_AC_COMPILER_EXEEXT_TESTS): ... this new macro. + (_AC_COMPILER_EXEEXT_O): Don't export ac_cv_exeext, it's not needed (or + no longer needed) by libtool. Make it a cache check. + (_AC_COMPILER_EXEEXT_CROSS): Remove the comment, it was obviously + copied here by mistake. + (AC_NO_EXECUTABLES): Redefine _AC_COMPILER_EXEEXT_TESTS, not + _AC_COMPILER_EXEEXT. + * lib/autoconf/c.m4 (AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC): Do not call + _AC_COMPILER_OBJEXT directly. + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Likewise. + +2006-04-01 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (_AS_DIRNAME_PREPARE): New macro. + (AS_DIRNAME): Use it. + (_AS_PREPARE): Add _AS_DIRNAME_PREPARE. + + * tests/*.at: Remove the generated ones. + +2006-04-01 Stepan Kasal + + * lib/autotest/general.m4 (AT_INIT): Don't optimize the first PATH walk. + +2006-04-01 Eric Blake + + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Optimize nonexistent + directories, unless optional third argument supplied. + (AS_UNAME): Don't optimize PATH walk. + + * lib/Autom4te/Struct.pm, lib/autoconf/c.m4: s/non-existent/nonexistent/ + +2006-04-01 Eric Blake + and Stepan Kasal + + * lib/m4sugar/m4sh.m4: Sort sections as implied by the comments, + and fix some typos. + +2006-04-01 Noah Misch + + * lib/autoconf/general.m4 (_AC_INIT_VERSION): Emit script name and + Autoconf version number despite a zero- or one-argument AC_INIT. + + * bin/autoreconf.in (parse_args): Multiple -v send --verbose to + subordinate tools. + * lib/Autom4te/General.pm (getopt): Make -v and -d incremental. + * doc/autoconf.texi (autoreconf Invocation): Document it. + + * doc/autoconf.texi: Use `Cygwin', `MinGW', and `license' consistently. + Append LocalWords so ispell-buffer passes cleanly. Spelling fixes. + +2006-04-01 Eric Blake + + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): Allow use in shell lists. + * lib/autotest/general.m4: Be tolerant of existing directory when + rm failed to remove it. + +2006-04-01 Ralf Wildenhues + + * bin/autoupdate.in: Redefine m4_location so that warnings print + the correct lines of the input file by subtracting.. + (_au__first_line): ..this new definition. + + * lib/autoconf/general.m4 (AC_COMPILE_CHECK): Prefer + AC_MSG_CHECKING over obsolete AC_CHECKING in autoupdated code. + Remove stray newline in output. + (AC_FOREACH): AU_DEFUN this as literal for autoupdate, and also + AC_DEFUN this for autoconf, including the obsoletion diagnose. + Fixes autoupdating of code where the replacement output contains + m4sugar macros. + * lib/autoconf/lang.m4 (AC_LANG_SAVE): Likewise. + * tests/mktests.sh (ac_exclude_list): Add AC_FOREACH. + (au_exclude_list): Add AC_LANG_SAVE. + * tests/tools.at: Several new tests for all of this. + * doc/autoconf.texi (Obsoleting Macros): Give a hint about the + hairy details. + The AC_LANG_SAVE issue was reported against Libtool by + Dalibor Topic , and against Autoconf 2.57 by + Kristian Kvilekval . + +2006-04-01 Stepan Kasal + + * bin/autoupdate.in: Handle m4 builtins and m4sugar macros together-- + switch all of them on and of when necessary. Fixes the bug when + m4sugar macros (e.g., m4_define) were expanded after the first + automatic update (e.g., after AC_PREREQ or AC_INIT). + +2006-03-31 Paul Eggert + + * doc/autoconf.texi (Programming in M4sh): Sharpen the descriptions + of AS_BASENAME and AS_DIRNAME. Reported by Stepan Kasal. + + * lib/m4sugar/m4sh.m4 (AS_BASENAME_EXPR): Handle ///, ////, etc. + correctly. Problem reported by Eric Blake. + (_AS_EXPR_PREPARE): Detect Tru64 expr bug. Problem reported by + Ralf Wildenhues. + +2006-03-30 Paul Eggert + + * doc/autoconf.texi (Programming in M4sh, Limitations of Usual Tools): + Tighten up the basename/dirname wording. + +2006-03-30 Ralf Wildenhues + + * Makefile.maint (sc_texi_notab): New check: do not use TABs + in texinfo files outside of verbatim environments. + (syntax-check-rules): Update. + * doc/autoconf.texi (Configuration Headers): Conform to it. + +2006-03-30 Chris Pickett (tiny change) + + * doc/autoconf.texi (autoreconf Invocation): Mention that -I for + aclocal cannot be given on the command line. + +2006-03-29 Paul Eggert + + * doc/autoconf.texi (Programming in M4sh): Mention AS_BASENAME. + Give an example for AS_DIRNAME instead of referring to Posix.. + (File System Conventions): Put discussion of // versus / here, and + modernize it a bit. + (Limitations of Usual Tools): Add basename. Remove verbiage + after dirname, since it got moved to the above sections. + All this was inspired by a patch proposed earlier by Eric Blake. + +2006-03-27 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Quote + `$0' to protect against spaces. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Likewise, for + `$0', $as_me. + +2006-03-26 Ralf Wildenhues + + * bin/autoscan.in: The value of find_configure_ac should be + checked for existence, so we don't barf over a nonexisting + configure.ac. Reported by Laurence Darby . + +2006-03-22 Ralf Wildenhues + + * bin/autoupdate.in: Fix some typos. + +2006-03-21 Stepan Kasal + + * doc/autoconf.texi (Installation Directory Variables): Fix typo. + + * lib/autoscan/autoscan.list: Refreshed. + +2006-03-20 Ralf Wildenhues + + * tests/local.at (AT_CHECK_ENV): Ignore AC_SUBSTed Objective C + and Erlang related variables. + + * lib/autoconf/c.m4 (AC_LANG(Objective C), AC_LANG_OBJC) + (_AC_LANG_ABBREV(Objective C), _AC_LANG_PREFIX(Objective C)) + (AC_LANG_SOURCE(Objective C), AC_LANG_PROGRAM(Objective C)) + (AC_LANG_CALL(Objective C), AC_LANG_FUNC_LINK_TRY(Objective C)) + (AC_LANG_BOOL_COMPILE_TRY(Objective C)) + (AC_LANG_INT_SAVE(Objective C), AC_LANG_PREPROC(Objective C)) + (AC_PROG_OBJCPP, AC_LANG_COMPILER(Objective C), AC_PROG_OBJC) + (_AC_PROG_OBJC_G): New macros. + (_AC_ARG_VAR_CPPFLAGS): Adjusted. + * doc/autoconf.texi (Objective C Compiler): New node. + (Preset Output Variables): Document OBJCFLAGS. + (Language Choice): Document `Objective C' language. + (Fortran Compiler): Fix typo. + * NEWS: Updated. + Inspired by a patch from David M. Lloyd . + +2006-03-20 Stepan Kasal + + * doc/autoconf.texi (Default Includes): Fix typo + s/AC_HEADERS_STDC/AC_HEADER_STDC/ + (Limitations of Usual Tools): s/unwriteable/unwritable/ + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT, _AC_COMPILER_EXEEXT): + Fix typos in the comments. + +2006-03-17 Stepan Kasal + + * lib/autoconf/programs.m4 (AC_PATH_TOOL, AC_CHECK_TOOL, AC_CHECK_TOOLS): + Factor out the warning to... + (_AC_TOOL_WARN): ... this new macro; use `cross_compiling'. + * tests/local.at (AT_CHECK_MACRO_CROSS): Avoid this warning. + * tests/semantics.at (AC_C_BIGENDIAN): Likewise. + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Do not special + case `ac_delim' when writing the sed script. + + * lib/m4sugar/m4sh.m4 (AS_BOURNE_COMPATIBLE): Removed BIN_SH=xpg4, + moved DUALCASE=1 ... + (AS_SHELL_SANITIZE): ... here. + * doc/autoconf.texi (Special Shell Variables) : Do not say + that it is set. + + * lib/autoconf/programs.m4 (AC_CHECK_PROG): Quote the parameter of + AC_SUBST. + (_AC_PATH_PROG): Store the result to VARIABLE. + (AC_PATH_PROG): No need to set VARIABLE again. + + * tests/local.at (AT_CHECK_MACRO_CROSS): New macro, creates two tests: + the first one is usual AT_CHECK_MACRO test, the second one checks + that the same works when cross-compiling. + * tests/semantics.at (AC_CHECK_ALIGNOF, AC_CHECK_ALIGNOF struct): + (AC_CHECK_SIZEOF, AC_CHECK_SIZEOF struct): Use it. + +2006-03-17 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Prepend + the directory `/usr/bin/posix' in the shell search, to prefer + the Posix shell not only in subsequent spawns as with `$BIN_SH' + on Tru64. + + * doc/autoconf.texi (contents): To fix texi2html output, hide + `@setcontentsaftertitlepage' for HTML. + (Writing Autoconf Macros): Likewise, insert space after `@c'. + (Leviticus, Numbers, Deuteronomy): Likewise, change `@,c' to + `@,{c}'. + +2006-03-16 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (_AS_PREPARE): Move the IFS setup and CDPATH + sanitizing... + (AS_SHELL_SANITIZE): ...here; mention _AS_PATH_WALK needs IFS set. + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): Add an explanation + why IFS is restored so late; thank you, Ralf, for reminding us. + +2006-03-15 Stepan Kasal + + * doc/autoconf.texi (Pretty Help Strings): No need to use cached + variables in the examples. + +2006-03-14 Romain Lenglet + + * doc/autoconf.texi (several sections): Cleaned up documentation for + macros in erlang.m4. + +2006-03-14 Ralf Wildenhues + + * tests/autotest.at (AT_NO_CMDSUBST): New macro to determine + failure condition for `$(cmd)' style command substitutions. + (Parenthetical command substitution, Multiline parenthetical + command substitution): Use it. + + * doc/autoconf.texi (Special Shell Variables): Missing word. + Reported by Keith Marshall . + + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Do not forget to reset + IFS even in case of empty `$PATH'. + +2006-03-12 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_INIT) : Optimize + `expr' away if there is nothing to do. + < --keywords >: Simplify and robustify argument handling. + Revert erroneous comment from 2005-08-23. Extend to allow + keyword negation with `!'. + Update help message. Remove broken code to prevent running + tests multiple times. + * doc/autoconf.texi (testsuite Invocation) < --keywords >: + Update and fix the documentation accordingly. + * tests/autotest.at (Keywords): Renamed to.. + (Keywords and ranges): .. this. Extended to make sure negated + keywords, keywords taken from AT_SETUP arguments, and numeric + test ranges work, and that matching is case-insensitive. + +2006-03-11 Ralf Wildenhues + + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_NEW): Use a typedef to + allow to pass unnamed structs even in C++. + (AC_CHECK_SIZEOF): Likewise. + Also fix quoting error in `AC_MSG_FAILURE' arguments. + * tests/semantics.at (AC_CHECK_ALIGNOF struct, AC_CHECK_SIZEOF + struct): New tests for unnamed structs, each both native and + cross-compiling. + + * lib/autoconf/c.m4 (AC_C_TYPEOF): Use typedef to avoid defining + a structure inside a cast, for C++ conformance. + * lib/autoconf/types.m4 (AC_CHECK_ALIGNOF): Likewise. + Also fix quoting error in `AC_MSG_FAILURE' arguments. + + * lib/autoconf/c.m4 (AC_PROG_CC_STDC): If we cannot enable C99 + nor C89 mode, set `$ac_cv_prog_cc_stdc' to `no' instead of + trying to execute the command `no'. + + * lib/autoconf/lang.m4 (AC_LANG_CONFTEST): AC_DEFUN this, not + m4_define, so that the requirements of `AC_INCLUDES_DEFAULT' are + expanded outside. + + * doc/autoconf.texi (autoconf Invocation): Fix typos in trace + example. Do not emphasize `$%', it is hardly new and special. + Reported by Edouard Bechetoille . + + * doc/autoconf.texi (Limitations of Usual Tools): Document + OpenBSD and traditional `grep' failure to handle multiple + patterns separated by newlines. + +2006-03-10 Romain Lenglet + + * doc/autoconf.texi (several sections): Add documentation for macros + in erlang.m4. + +2006-03-10 Eric Blake + + * doc/autoconf.texi (Obsolete Macros): Fix wording of + AC_TRY_LINK_FUNC. + +2006-03-10 Paul Eggert + + * doc/autoconf.texi: Use @acronym more consistently for acronyms + like BSD, GPL, LGPL. Fix minor English typos. + (AC_STDC_HEADERS, AC_PROG_GCC_TRADITIONAL): + Mention that these macros are becoming obsolete. + (AC_STDC_HEADERS, AC_PROG_CC, AC_C_CONST, AC_C_VOLATILE): + Use more modern terminology for which standard is what. + (AC_PROG_CC): Mention gcc first, and remove obsolete references to egcs + and to ansi2knr. + (AC_PROG_CXX): Likewise. + (AC_C_PROTOTYPES, Test Functions, AC_LIBOBJ vs LIBOBJS): + Remove obsolete discussion about how to port to K&R. + (Guidelines for Test Programs): Suggest AC_HEADER_STDBOOL rather than + the obsolescent AC_HEADER_STDC. + (AC_FOO_IFELSE vs AC_TRY_FOO): Don't use #error; test programs + can't rely on it. + +2006-03-08 Ralf Wildenhues + + * tests/c.at (AC_PROG_CPP without warnings, AC_PROG_CPP via CC): + Remove stdin redirection from /dev/null to allow pipe to work. + +2006-03-08 Paul Eggert + + * tests/c.at (AC_PROG_CPP without warnings, AC_PROG_CPP via CC): + Require that /lib/cpp include stdio.h correctly. Solaris 10's + doesn't. Problem reported by D'Arcy A MacIsaac and diagnosed by + Ralf Wildenhues. + +2006-03-06 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_SED_CMD_LIMIT): The limit for + HP-UX sed is 99 commands, not 100. + (_AC_OUTPUT_FILES_PREPARE): Do not count the `}' of an + _AC_SUBST_FILES fragment. Separate `{' and `r' commands by + newline for portability. + * tests/torture.at (Torturing config.status): Also test 100 + AC_SUBST_FILE invocations. Fix test to actually verify the + AC_CONFIG_FILES output. + * doc/autoconf.texi (Limitations of Usual Tools): Document HP-UX + command, label, and read-file `r' limits. Unify HP-UX spelling. + + * tests/Makefile.am (edit, $(wrappers)): Do not use `$<' in + non-suffix rule. + ($(TESTSUITE_GENERATED_AT)): Use `$(srcdir)` for the benefit of + non-GNU make. + (autoconfdir, $(AUTOCONF_FILES)): Likewise. + * tests/mktests.sh: Small shell portability fixes. + +2006-03-05 Ralf Wildenhues + + * doc/autoconf.texi (Caching Results): Fix the examples to use a + recommended quoting style and discard unwanted output. + +2006-03-05 Paul Eggert + + * lib/autotest/general.m4 (_AT_NORMALIZE_TEST_GROUP_NUMBER): New macro. + (AT_INIT): Use it, to remove arbitrary limit of 999,999 test + cases, and to work around Tru64 expr bug. + +2006-03-05 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Usual Tools): Mention Tru64 + expr bug that turns the result of a regex match into a number if + possible. + +2006-03-04 Ralf Wildenhues + + * lib/autoconf/types.m4 (AC_CHECK_ALIGNOF): Work around + HPUX compiler bug, similarly to AC_CHECK_SIZEOF, as documented + in section `Specific Compiler Characteristics'. + +2006-03-04 Eric Blake + + * lib/autoconf/functions.m4 (AC_FUNC_STRERROR_R): Avoid unused + variable warning. + +2006-03-01 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADER): Force correct + order of variable initialization, so even the Solaris 2.6 shell + can create a config header correctly. Fixes lots of test suite + failures. + +2006-02-22 Ralf Wildenhues + + * doc/autoconf.texi (Text processing Macros): New node to + document the m4sugar macros m4_re_escape, m4_tolower, + m4_toupper, m4_split, m4_normalize, m4_append, m4_append_uniq. + +2006-02-22 Paul Eggert + + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Fix typo: + XrmInitialize (0) -> XrmInitialize (). + Reported by Toshio Kuratomi. + +2006-02-21 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (AS_IF): Extend to allow more than one + test, as in `if tests; then cmd1; elif ...; else ...; fi'. + * doc/autoconf.texi (Programming in M4sh): Adjusted. + * tests/m4sh.at (AS_IF and AS_CASE): Test this. Also make sure + both macros are defun'ed so that required macros are evaluated + outside. + + * doc/autoconf.texi (Prerequisite Macros): State more precisely + where a required macro will be expanded. + (Coding Style): Another reason not to use `m4_define'. + +2006-02-21 Eric Blake + + * lib/autoconf/general.m4 (_AC_LIBOBJ): Minor optimization. + +2006-02-20 Ralf Wildenhues + + * doc/autoconf.texi (Looping constructs): New node, to + document m4_for, m4_foreach, m4_foreach_w, and mention + obsolete AC_FOREACH. + (Obsolete Macros): Document AC_FOREACH. + * lib/m4sugar/m4sugar.m4 (_m4_for): Fix declaration comment. + (m4_for): Fix to never loop (almost) endlessly, work correctly + with arithmetic expressions in arguments, a step of zero or + non-integer multiple of the interval, and avoid integer + overflow. + * tests/m4sugar.at: New test for m4_for, m4_foreach, and + m4_foreach_w. + +2006-02-20 Romain Lenglet + + Add basic support for Erlang, both for configuring Erlang/OTP + tools, and Erlang as a conf test language. + * lib/autoconf/erlang.m4: New file. + * lib/autoconf/autoconf.m4: Add erlang.m4. + * lib/autoconf/Makefile.am (dist_autoconflib_DATA): Likewise. + * lib/freeze.mk (autoconf_m4f_dependencies): Likewise. + * NEWS: Add short description of new macros. + * THANKS: Add Romain Lenglet. + +2006-02-20 Ralf Wildenhues + + * doc/autoconf.texi (Shellology) : Document that pdksh as + native /bin/sh may not set KSH_VERSION (seen on OpenBSD). + +2006-02-15 Eric Blake + + * lib/autoconf/general.m4 (AC_CHECK_DECL): Avoid unused variable + warning. + +2006-02-15 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (AS_CASE): New macro. + (_AS_CASE): Private helper macro. + * tests/m4sh.at: Basic tests for AS_IF and AS_CASE. + * doc/autoconf.texi (Programming in M4sh): Document AS_CASE. + Fix syntax of AS_IF description + (Prerequisite Macros): Mention AS_IF and AS_CASE as workarounds + for the AC_REQUIRE mess. + * NEWS: Mention AS_CASE, AS_BOURNE_COMPATIBLE, and + AS_SHELL_SANITIZE. + +2006-02-14 Paul Eggert + + * doc/autoconf.texi: Minor style cleanup. + Be consistent about spaces after commas. + Insert [] where empty args look a bit funny. + Fix some "i.e." and "e.g." usages. + Try to avoid "X/Y" usages. + Don't be pedantic about "ISO C99"; just say C99. + Prefer GNU style for spaces in front of parens. + (Function Portability): Comment about C89 versus C99 + signed integer division. + (Particular Headers): Use current gnulib style for dirent + includes. + +2006-02-14 Stepan Kasal + and Ralf Wildenhues + + * bin/autoupdate.in (handle_autoconf_macros): Fix updating of + macros without parameters. + * lib/autoconf/autoupdate.m4 (AU_ALIAS): Likewise. + * doc/autoconf.texi (Obsoleting Macros): Document AU_ALIAS. + * tests/tools.at (autoupdating AU_ALIAS): New test for AU_ALIAS + `$#' bug. + (autoupdate): Updated to match AU_ALIAS fix. + +2006-02-13 Ralf Wildenhues + and Paul Eggert + + * doc/autoconf.texi (Programming in M4sh): Document + AS_BOURNE_COMPATIBLE and AS_SHELL_SANITIZE. + +2006-02-13 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Renamed to.. + (AS_BOURNE_COMPATIBLE): ..this. + (_AS_RUN, AS_SHELL_SANITIZE): Adjusted all callers. + +2006-02-12 Paul Eggert + + * doc/install.texi (Defining Variables): Tighten up the + CONFIG_SHELL wording. + +2006-02-12 Paul Eggert + and Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Look at the output + of (set -o) rather than testing whether (set -o posix) succeeds, + to work around a bug in the AIX 5.3 shell. Problem originally + reportd by Howard Chu for libtool. + +2006-02-10 J.T. Conklin + + * doc/autoconf.texi (Running the Compiler, Running the Linker): + Changes the macro arguments in summaries to match the + descriptions. + +2006-02-04 Stepan Kasal + + * doc/install.texi (Defining Variables): Classify the `CONFIG_SHELL' + hint as ``a workaround for a bug.'' + +2006-01-31 Ralf Wildenhues + + * bin/autoreconf.in: New option `--no-recursive'. + Improve wording for subpackages a bit. + * doc/autoconf.texi (autoreconf Invocation): Updated. + * NEWS: Updated. + + * doc/install.texi (Defining Variables): Put `CONFIG_SHELL' + in environment of `configure', not the command line. + Reported by Howard Chu . + +2006-01-25 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Document the + problem with "trap -". + +2006-01-23 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS, _AC_FC_DUMMY_MAIN): + (_AC_FC_MAIN, __AC_FC_NAME_MANGLING): Use _AC_LANG in check + messages to differentiate Fortran and Fortran 77 tests. + (AC_FC_SRCEXT, AC_FC_FREEFORM): Use AC_LANG_PUSH/POP instead of + AC_LANG_ASSERT, to allow use in mixed-language projects. + +2006-01-23 Paul Eggert + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY(C)): Prefer "defined + FOO" to "defined (FOO)". + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA): Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_STAT): Likewise. + * lib/autoconf/specific.m4 (AC_XENIX_DIR): Likewise. + * tests/tools.at (ifnames): Likewise. + +2006-01-21 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Do not pass `-q' to mktemp. + * lib/Autom4te/General.pm (mktmpdir): Likewise. + (END): Improve error message a bit. + Reported by Bruce Korb . + +2006-01-12 Ralf Wildenhues + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Ignore + `-LIST:' and `-LNO:', for PathScale 2.3 compilers. + +2006-01-11 Stepan Kasal + + * doc/autoconf.texi (Header Portability): On Solaris 8, sys/ptem.h + requires sys/stream.h. Reported by Oliver Kiddle. + +2006-01-11 Ralf Wildenhues + Stepan Kasal + + * lib/autotest/general.m4 (AT_INIT): When ensuring writability + before the removals of test dirs, use `find' to avoid modification + of symlinked directories. + +2006-01-11 Steven G. Johnson + + * lib/autoconf/fortran.m4 (AC_F77_DUMMY_MAIN, AC_FC_DUMMY_MAIN): + Don't ignore the macro arguments. + +2006-01-11 David Thompson + + * lib/autoconf/c.m4 (_AC_PROG_CXX_EXIT_DECLARATION): Add `exit' + declaration that works for MSVC. + +2006-01-11 Ralf Wildenhues + + * lib/autoconf/lang.m4 (_AC_COMPILER_OBJEXT_REJECT): + Add `*.map' and `.inf' for Green Hills compiler. + Reported by Stefan Seefeld . + + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Handle quadrigraphs + correctly: pad with spaces after FIRST_PREFIX if necessary, + and compute string lenghts with `m4_qlen' instead of `m4_len'. + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): Comments updated. + * tests/m4sh.at (AS_HELP_STRING): Test extended. + * NEWS: Updated. + Reported by numerous people, numerous times. + +2006-01-05 Paul Eggert + + * bin/autoconf.as, bin/autoheader.in, bin/autom4te.in + * bin/autoreconf.in, bin/autoscan.in, bin/autoupdate.in, bin/ifnames.in: + * lib/autoconf/general.m4, lib/autoconf/status.m4: + * lib/autotest/general.m4, tests/local.at: + Update copyright year to 2006. + + * Makefile.maint (sc_root_tests): Use the recommended style s/a/b/ for + sed substitutions. + * doc/autoconf.texi (Installation Directory Variables): Use s|a|b| + for file names, again. Reported by Noah Misch. + (Coding Style): Explain that s|a|b| is preferred for file names. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): Prefer s/a/b/. + (AC_OUTPUT_MAKE_DEFS): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Likewise. + * tests/local.at (AT_CHECK_AUTOM4TE): Likewise. + + Fix Posix-conformance bugs re use of { command in sed scripts, + and improve the sed-related documentation a bit. + * doc/autoconf.texi (Installation Directory Variables): Use + our own style advice re 's,a,b,' versus 's|a|b|'. Use "Sed" + rather than "sed" when talking about Sed in general. + (Particular Programs): Likewise. + (Coding Style): y is like s with respect to / and ,. + (Limitations of Usual Tools): Document the weird restrictions + that Posix has about { }. Use better quoting. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE, _AC_OUTPUT_HEADER): + Rewrite to conform to Posix rules about { } in sed scripts. + * lib/m4sugar/m4sh.m4 (AS_DIRNAME_SED, AS_BASENAME_SED): Likewise. + * tests/foreign.at (Libtool): Likewise. + * tests/semantics.at (AC_CHECK_PROG & AC_CHECK_PROGS): + Use our own style advice re 's,a,b,' versus 's|a|b|'. + +2006-01-05 Ralf Wildenhues + + * lib/autoconf/status.m4: Fix typo. + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Ignore + singly- or doubly-quoted arguments to `-cmdline', `-ignore', + `-def', for the benefit of Portland `pgf90 -Mipa'. + Reported by Christopher Hulbert . + +2006-01-04 Paul Eggert + + * doc/autoconf.texi: Update copyright (and other) dates to 2006. + * doc/autoconf.texi (Shellology): Mac OS X 10.2 changed the default + shell from zsh to bash. + +2005-12-31 Stepan Kasal + + * lib/autoconf/programs.m4 (_AC_PROG_GREP): Use $PATH_SEPARATOR; + ":" caused problems on OS/2-EMX. Suggested by Andrew Belov. + +2005-12-29 Paul Eggert + + * doc/autoconf.texi (Shell Substitutions): Warn about unbalanced + parentheses in $(...). Problem reported by Eric Blake. + +2005-12-12 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): + Mention which characters can be escaped with \ in portable regular + expressions used in grep, sed, expr. Mention the leading ^ problem + with expr. Clean up some confusing wording. Mention which + grep options are portable. + +2005-12-09 Stepan Kasal + + * tests/local.at (AT_CHECK_AUTOM4TE): Fix typo in the comment. + +2005-12-02 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Fix typos in previous + patch, noted by Ralf Wildenhues. + +2005-12-02 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Try `set -o + posix' unconditionally, for pdksh in `native sh' emulation. + +2005-12-01 Paul Eggert + + * doc/autoconf.texi (Shellology): Document eval $? problem + with ash. + (Limitations of Builtins): Likewise. + +2005-11-10 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Pass + CONFIG_SHELL in the environment of the configure rerun. + * doc/autoconf.texi (Here-Documents, config.status Invocation): + Suggest passing CONFIG_SHELL absolute, and in the environment + rather than as option. + +2005-11-09 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): + Fix quoting of output line (triggered for many AC_SUBST_FILEs). + Fix macro quoting. Fix output for n * 98 substituted variables. + +2005-11-08 Ralf Wildenhues + + * lib/autoconf/status.m4 (_AC_OUTPUT_MAIN_LOOP): Initialize + `tmp' to avoid file removal race. + +2005-11-07 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Initialize + ac_clean_files and LIBOBJS. + +2005-11-06 Ralf Wildenhues + + * lib/autoconf/programs.m4 (AC_CHECK_PROG, AC_PATH_PROG): + Factor functionality to.. + (_AC_CHECK_PROG, _AC_PATH_PROG): these new macros, but only + `AC_SUBST($1)' in the public version. + (AC_CHECK_TOOL, AC_PATH_TOOL, AC_PATH_TARGET_TOOL) + (AC_CHECK_TARGET_TOOL): Use internal versions for ac_ct_* and + ac_pt_* variables. + +2005-11-01 Stepan Kasal + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): Remove the comment about 8+3 + filesystems. + +2005-11-01 Ralf Wildenhues + + * NEWS: Move AH_HEADER mention to right place. + +2005-10-27 Stepan Kasal + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): "conftst2" -> "conftest2" + * lib/autoconf/fortran.m4 (_AC_PROG_FC_C_O): Likewise. + +2005-10-25 Stepan Kasal + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): rm -f conftst2.*, not only + conftst2.$ac_objext. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_C_O): Likewise. + +2005-10-24 Stepan Kasal + + * lib/autoconf/c.m4 (AC_PROG_CC_C_O): Use conftst2.o instead of + conftest.o, to see whether the compiler really obeys; rm the object + file before and after the test and register it with ac_clean_files. + * lib/autoconf/fortran.m4 (_AC_PROG_FC_C_O): Likewise. + +2005-10-21 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES_PREPARE): When determining, + the delimiter CEOF$ac_eof: fix quoting of CEOF[0-9]* and modify the + code so that the most common case requires less forks. + +2005-10-20 Stepan Kasal + + * doc/autoconf.texi (Shell Substitutions}: Document that ${10} is + not portable; thanks to Paul Eggert and Alexandre. + + * NEWS: Fix an old typo. + +2005-10-20 Jim Meyering + + * doc/autoconf.texi: Typo: s/feature/features/ in ``the features of + the latter'', in two places. + +2005-10-19 Paul Eggert + + * doc/autoconf.texi (Generating Sources): AC_LANG_PROGRAMS -> + AC_LANG_PROGRAM, fixing a typo. Don't give details about + the inner workings of AC_LANG_FUNC_LINK_TRY. + * lib/autoconf/c.m4 (AC_LANG_CALL(C)): Reformat to match + AC_LANG_FUNC_LINK_TRY. This involves returning the value returned + by the function rather than ignoring it. + (AC_LANG_FUNC_LINK_TRY(C)): Call the function rather than simply + comparing its address. Intel's interprocedural optimization was + outsmarting the old heuristic. Problem reported by + Mikulas Patocka. + +2005-10-19 Stepan Kasal + + * lib/autoconf/general.m4 (AC_SUBST): Remove an obsolete comment. + +2005-10-05 Paul Eggert + + * lib/m4sugar/m4sugar.m4 (_m4_map): New macro. + (m4_map, m4_map_sep): Use it. Handle the empty list correctly. + +2005-10-04 Stepan Kasal + + * lib/autotest/general.m4 (AT_INIT): Really make the subtree writable + before removing it (chmod -R u+rwx); there are three instances of this. + +2005-10-02 Ralf Wildenhues + Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Balance parentheses. + * lib/autotest/general.m4 (AT_INIT): If the test dir already exists, + make its content writable before removing it. Remove an errorneous + comment from the end, where the logs of the failed tests are copied + to the main log file. + +2005-09-27 Stepan Kasal + + * tests/semantics.at (AC_C_BIGENDIAN): Pass --force to autoheader, + in case the computer is too quick. Double quote the configure.ac + snippets. + + * tests/local.at (AT_CHECK_AUTOCONF): Always pass --force to prevent + problems if the testsuite were running too fast. + +2005-09-18 Paul Eggert + + * lib/autoconf/libs.m4 (_AC_PATH_X_DIRECT): Look for X11/Xlib.h + and XrmInitialize rather than X11/Intrinsic.h and XtMalloc + (which belong to Xt, not X itself). See Debian bug 327655. + * NEWS: Mention this. + +2005-09-07 Stepan Kasal + + * lib/autoconf/c.m4 (AC_LANG_SOURCE(C)): Remove an incorrect comment. + +2005-09-06 Paul Eggert + + * config/move-if-change: Don't output "$2 is unchanged"; + suggested by Ben Elliston. Handle weird characters correctly. + +2005-09-06 Stepan Kasal + + * lib/autoconf/libs.m4 (AC_SEARCH_LIBS): Merge the two AC_LINK_IFELSE + calls, so that the final expansion of this macro is shorter. + Create the conftest.$ac_ext outside the `for' loop, to speed the run. + Do not use `break' in the argument to AC_LINK_IFELSE, it would skip + the cleanup there. Use AS_VAR_* macros, to be more general. + * tests/semantics.at (AC_SEARCH_LIBS): Check for the cleanup. + + * lib/autoconf/general.m4: Use AS_IF where appropriate. + + * lib/m4sugar/m4sh.m4 (AS_IF): Use m4_default. + +2005-09-01 Stepan Kasal + + * doc/autoconf.texi (Configuration Headers): Add an index entry + for AH_HEADER. + +2005-08-26 Pavel Roskin + + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): Use shell variable + XMKMF to locate xmkmf. Make XMKMF precious. Export CC when + running xmkmf. + +2005-08-26 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_VERSION_COMPARE_PREPARE): + The previous patch didn't work, so try a better one. + +2005-08-26 Stepan Kasal + + * doc/autoconf.texi (Programming in M4sh) : Fix m4 quoting + in the example. Reported by Bruno Haible. + : Likewise. Also modify the example to be more convincing: + "if $undefined_var;" succeeds with my shell. + + * lib/autoconf/general.m4 (AC_CANONICAL_BUILD, AC_CANONICAL_HOST, + AC_CANONICAL_TARGET): Define by AC_DEFUN, no need to use AC_DEFUN_ONCE; + but change the m4_divert_text to m4_divert_once. + +2005-08-25 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_VERSION_COMPARE_PREPARE): + Work around bug in Solaris /usr/xpg4/bin/awk. + The bug is present in at least Solaris 8 through 10. + +2005-08-24 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): Simplify; rejecting + some evil values and relying on the fact that $* concatenates the + parameters by the first character from IFS. + +2005-08-23 Ralf Wildenhues , + Stepan Kasal + + * lib/autoconf/status.m4 (_AC_CONFIG_REGISTER_DEST): When the + first header appears, define AH_HEADER. + * doc/autoconf.texi (Configuration Headers): Document AH_HEADER. + Update limitations about when to call AC_CONFIG_HEADERS. + (Configuration Commands): Document that AC_CONFIG_COMMANDS_PRE + parameter can call AC_SUBST, AC_DEFINE, or AC_CONFIG_FOOS; explain + that AC_CONFIG_COMMANDS_PRE and AC_CONFIG_COMMANDS_POST are not + ``Configuration Actions''; fix their index entries. + + * lib/autotest/general.m4 (AT_INIT): Process multiple keywords + options correctly. Process N-M as M-N if M is smaller than N. + Process ranges correctly so that N-N will run only N. + Sort and uniquify the tests that will be run. If there is more + than one test, reinsert the banners for the tests. + * tests/autotest.at (Keywords): Unmark XFAIL. + +2005-08-23 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_DEFINE_Q): Strip the parameter list + before passing the macro name to AH_TEMPLATE. + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): config.status + now opens log after option processing; in particular, --version + and --help do not touch config.log. + + * Makefile.maint: Revert the change from 2005-08-12. + +2005-08-22 Stepan Kasal + + * lib/autoconf/general.m4 (AC_ARG_ENABLE, AC_ARG_WITH): Factor out + common code to... + (_AC_ENABLE_IF, _AC_ENABLE_IF_ACTION): ... these new macros. + +2005-08-21 Ralf Wildenhues + + * doc/autoconf.texi (Using Autotest, testsuite Scripts) + (Autotest Logs, Writing testsuite.at, testsuite Invocation): + Language cleanup. + + * doc/autoconf.texi (Defining Symbols, Changed Results): + Prepend to LIBS, not append, in examples. + +2005-08-16 Stepan Kasal + + When building in place, set srcdir="."; suggested by Tim Van Holder. + + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): Do this; to recognize + build in place, we need ac_pwd, and thus have to AC_REQUIRE ... + (_AC_INIT_DIRCHECK): ... this macro and AC_DEFUN both of them. + * lib/autoconf/status.m4 (_AC_SRCDIRS): Fix a comment: srcdir="." + does not mean "no --srcdir option". + +2005-08-15 Ralf Wildenhues + + * tests/autoscan.at (autoscan): New file. + * tests/suite.at: Use it. + * tests/Makefile.am (TESTSUITE_HAND_AT): Add it. + Reported against Libtool by Gideon Go . + + * tests/autotest.at (Keywords): Test keywords combinations. + +2005-08-12 Stepan Kasal + + * Makefile.maint (GZIP_ENV): When checking the help text of gzip, + add "2>&1"; gzip 1.2.4 prints help on stderr. + +2005-07-27 Stepan Kasal + + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): The symbol at_reason + was pushdef'ed twice while popped only once. Push it only once. + (_AT_CHECK): Cosmetic changes to the "case $at_status" command. + +2005-07-26 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): The message is now + prefixed by mere "===", not "configure: === ". + +2005-07-25 Paul Eggert + + * Makefile.maint: Update from Bison. + + * lib/m4sugar/m4sugar.m4 (m4_strip): Comment fix---change tab to + "" in comment, so that the point is understandable. + +2005-07-25 Stepan Kasal + + Rewrite substantial part of lib/autoconf/status.m4. + The main change is that CONFIG_FILES, CONFIG_HEADERS, CONFIG_LINKS, + and CONFIG_COMMANDS are not processed in four separate loops. + Instead, there is one main loop. This allows that the common code + is expanded only once, thus config.status (and configure) is smaller. + + The registration mechanism in AC_CONFIG_FILES and cousins also + changed; the AC_LIST_FILES and cousins macros are no longer used. + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES, _AC_OUTPUT_HEADERS, + _AC_OUTPUT_LINKS, _AC_OUTPUT_COMMANDS): Renamed to ... + (_AC_OUTPUT_FILE, _AC_OUTPUT_HEADER, _AC_OUTPUT_LINK, + _AC_OUTPUT_COMMAND): ..., respectively. These macros no longer + contain the initialization, nor the for loop, nor the associated + commands; all these go to ... + (_AC_OUTPUT_MAIN_LOOP): ... this new macro, called from + _AC_OUTPUT_CONFIG_STATUS. + (_AC_CONFIG_SPLIT, _AC_CONFIG_SPLIT_SOURCE_DEST, _AC_CONFIG_SPLIT_FILE_IN): + Nuked; the code was merged into _AC_OUTPUT_MAIN_LOOP. + (_AC_OUTPUT_FILE): The creation of the sed script ... + (AC_OUTPUT): ... and the setup of ac_vpsub goes to ... + (_AC_OUTPUT_FILES_PREPARE): ... a new macro, also called from + _AC_OUTPUT_MAIN_LOOP. + (_AC_CONFIG_FILES, _AC_CONFIG_HEADERS, _AC_CONFIG_LINKS, + _AC_CONFIG_COMMANDS): Use ... + (_AC_CONFIG_FOOS): ... this new macro, which uses these ... + (_AC_CONFIG_REGISTER, _AC_CONFIG_REGISTER_DEST): ... new macros. + (_AC_CONFIG_FILE, _AC_CONFIG_HEADER, _AC_CONFIG_LINK, + _AC_CONFIG_COMMAND, _AC_CONFIG_DEPENDENCIES): No longer needed. + (_AC_CONFIG_DEPENDENCY): Update, it uses these ... + (_AC_CONFIG_DEPENDENCY_DEFAULT, _AC_FILE_DEPENDENCY_TRACE_COLON): + ... new macros. + (_AC_CONFIG_UNIQUE): Update. + (AC_LIST_FILES, AC_LIST_HEADERS, AC_LIST_LINKS, AC_LIST_COMMANDS): + Replaced by this ... + (_AC_LIST_TAGS): ... new common macro. + (AC_LIST_FILE_COMMANDS, AC_LIST_HEADER_COMMANDS, AC_LIST_LINK_COMMANDS, + AC_LIST_COMMAND_COMMANDS): Replaced by this ... + (_AC_LIST_TAG_COMMANDS): ... new common macro. + (_AC_CONFIG_COMMANDS_INIT): Moved top to the `registration' section; + this didn't belong to the `config commands' section. + (_AC_OUTPUT_COMMANDS_INIT): Don't initialize, m4_ifdef is our friend. + (AC_CONFIG_COMMANDS_PRE, AC_OUTPUT_COMMANDS_PRE, + AC_CONFIG_COMMANDS_POST): Moved to a new section, these didn't belong + to the `config commands' section either. + (AC_CONFIG_SUBDIRS): Don't touch diversion DEFAULTS. + (_AC_LIST_SUBDIRS): Don't initialize, m4_ifdef is our friend. + + ... and many changes to the comments nearby. + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): At the end of the day, + set ac_subdirs_all='_AC_LIST_SUBDIRS'. + * tests/torture.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS): + AC_CONFIG_COMMANDS(command:input,...) is no longer allowed. + (#define header templates): The comment at the top of the generated + header now includes the name(s) of the source file(s). + + Several unrelated small changes: + + * lib/autoconf/general.m4 (AC_CACHE_VAL): Be didactic, quote the first + parameter to AC_DIAGNOSE. + * lib/autoconf/status.m4 (AC_CONFIG_SUBDIRS): Likewise. + (_AC_LINK_FILES_CNT): Don't AU_DEFUN this; it causes confusing messages + with autoupdate; use m4_define_default inside AU_DEFUNed AC_LINK_FILES. + (AC_OUTPUT): In the compatibility code, use m4_ifvaln, to be consistent + with AU::AC_OUTPUT. + (AU::AC_OUTPUT): Don't double-quote $2 and $3, the compatibility code + in AC_OUTPUT doesn't double-quote it either. + * tests/tools.at (autoupdate): AU::AC_OUTPUT no longer double-quotes the + parameters. + +2005-07-10 Stepan Kasal + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Document which + versions of Portland Group compiler produce single- and double-quoted + -cmdline argument. Reported by Steven G. Johnson + and Ole Holm Nielsen . + +2005-07-07 Paul Eggert + + * tests/local.at (AT_CONFIG_CMP): Ignore lines like "LIBS=''" too. + This is a corrected version of yesterday's patch. + +2005-07-07 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Report the full + path, too; insert a "===" to emphasize the line. + + * lib/autoconf/general.m4 (AC_CANONICAL_BUILD): Rename + ac_cv_build_alias to ac_build_alias. + (AC_CANONICAL_HOST, AC_CANONICAL_TARGET): Simplify. + + On 2005-02-24, an unintentional AC_SUBST([CC]) was introduced; this + change eliminates it. Problem reported by Alexandre Duret-Lutz. + * lib/autoconf/general.m4 (_AC_ARG_VAR_PRECIOUS): Move the AC_SUBST ... + (AC_ARG_VAR): ... here. + (_AC_INIT_PREPARE): Call AC_SUBST for build_alias, host_alias and + target_alias. + + Keep a list of all precious variables and process them with one simple + for loop, instead of expanding all commands, or, OTOH, complicated + processing of output of "set". + * lib/autoconf/general.m4 (_AC_ARG_VAR_PRECIOUS): Accumulate the + variable names in new macro... + (_AC_PRECIOUS_VARS): ... which will be assigned to ac_precious_vars. + (_AC_ARG_VAR_STORE): New macro which writes to diversion PARSE_ARGS + a loop to assign all ac_env_* and ac_cv_env_* variables. + (_AC_ARG_VAR_VALIDATE): Use shell variable ac_precious_vars, divert + to INIT_PREPARE. + (_AC_INIT_DEFAULTS): At the end, if _AC_PRECIOUS_VARS is set, assign + its value to shell variable ac_precious_vars and call + _AC_ARG_VAR_STORE and _AC_ARG_VAR_VALIDATE. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Don't call + _AC_ARG_VAR_VALIDATE. + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Move AC_LANG_PUSH(C) + and the AC_SUBSTs ... + (AC_INIT): ... here. + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Changed the title of + the ac_subst_files section in config.log. + + * tests/local.at (AT_CONFIG_CMP): Revert Paul's previous change. + +2005-07-06 Paul Eggert + + * NEWS: New macro AC_C_TYPEOF. + * doc/autoconf.texi (C Compiler): Document AC_C_TYPEOF. + * lib/autoconf/c.m4 (AC_C_TYPEOF): New macro. + * tests/c.at (C keywords): Test AC_C_TYPEOF. + + Fix problems reported by Nicolas Joly. + * tests/base.at (Input/Output): Ignore 'loading site script' chatter. + * tests/local.at (AT_CONFIG_CMP): Ignore lines like "LIBS=''" too. + They are generated by the Tru64 v5.1B shell. + +2005-07-05 Stepan Kasal + + Fix my changes from 2005-07-01; reported by Noah Misch. + * lib/autoconf/status.m4 (_AC_CONFIG_DEPENDENCIES): Fix the + description, the macro now accepts only a single tag. + (_AC_CONFIG_UNIQUE): Likewise; s/AC_File/[$1]/ + + Fix cases when the varsions of Autoconf and Autotest don't match. + Reported by Noah Misch. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Set also + at_top_builddir, for compatibility with older autotest. + * lib/autotest/general.m4 (AT_INIT): If at_top_build_prefix + is not set, use at_top_builddir, for compatibility with older + versions of autoconf. + +2005-07-04 Paul Eggert + + * bin/autom4te.in ($m4): Catch usages like --nesting-limit=2048. + Problem reported by Patrick Welche. + +2005-07-03 Paul Eggert + + * lib/autoconf/general.m4 (AC_ARG_PROGRAM): Use &, not |, in + sed substitution command, so that we allow | in program prefixes + and program suffixes. (& is a problem anyway; we're not fixing + that here.) + * lib/autoconf/status.m4 (AC_CONFIG_FILES): Likewise, for + configure_input, top_builddir, srcdir, etc. + * lib/autotest/general.m4 (AT_INIT): Likewise, for + PATH_SEPARATOR in AUTOTEST_PATH. + +2005-07-02 Alexandre Duret-Lutz + + * lib/autoconf/general.m4 (AC_SITE_LOAD): Rewrite the + for loop over config.site files using `set', to allow + directory names containing IFS characters. + +2005-07-01 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_DIRCHECK): Remove the tests for + directories with weird names. Apparently some people like living + on the edge. However, improve the test that "pwd" actually does + report a name for the working directory. + * NEWS: Remove the claim that we test for funny chars in dir names. + +2005-07-01 Stepan Kasal + + * lib/autoconf/general.m4 (AC_FOREACH): Make obsolete; it's + replaced ... + * lib/m4sugar/m4sugar.m4 (m4_foreach_w): ... by this new macro. + * lib/autoconf/status.m4 (_AC_CONFIG_DEPENDENCIES, _AC_CONFIG_UNIQUE): + Now accept a single tag, not whitespace separated list. + (AC_CONFIG_SUBDIRS): Call _AC_CONFIG_UNIQUE in a m4_foreach_w loop. + +2005-06-30 Stepan Kasal + + * doc/autoconf.texi (Configuration Headers): Change the explanation + about #include . + (Generic Functions): Mention the Gnulib project. + (Limitations of Usual Tools) : Another minor rephrasing. + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Use a here + document to output the default config_* lists to config.status. + Don't recognize option --file, if the functionality is not there. + Likewise for --header; moreover, recognize --he and --h as shortcuts + for --help in that case. + + * lib/autoconf/status.m4: Fix the order of the "sections", so that it + matches the order of execution. No code changed. + +2005-06-30 Ralf Wildenhues + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Fix also for + single-quoted -cmdline argument in Portland Group compiler. + Reported against LAM by Ole Holm Nielsen . + +2005-06-30 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect AC_SUBST_TRACE. + +2005-06-29 Stepan Kasal + + * doc/autoconf.texi (File Descriptors): ksh doesn't pass open file + descriptors to child processes; reported by Norman Gray. + +2005-06-29 Stepan Kasal + + * lib/autoconf/general.m4 (AC_ARG_VAR): Move next to _AC_ARG_PRECIOUS. + + * lib/autoconf/general.m4 (AC_SUBST_TRACE): New macro, to be traced + instead of AC_SUBST; proposed by Alexandre Duret-Lutz. + (AC_SUBST): Call it. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES): Call AC_SUBST_TRACE for + the directory specific variables; but don't call it for configure_input. + +2005-06-28 Derek Price + + * doc/autoconf.texi (Limitations of Usual Tools) : Reword recent + addition. + +2005-06-23 Paul Eggert + + * NEWS: Don't worry about spaces in bindir etc. Only srcdir and working + directory have inherent problems with special characters like spaces, + due to limitations in Make syntax. Problem reported by Alexandre + Duret-Lutz. + * lib/autoconf/general.m4 (_AC_INIT_DIRCHECK): Implement the above. + Also, fix Tru64 porting problem with shell patterns, + reported by Ralf Wildenhues. + +2005-06-23 Ralf Wildenhues + + * doc/autoconf.texi (Subdirectories): Fix markup typos. + +2005-06-23 Paul Eggert + + * tests/local.at (AT_CHECK_ENV): Simplify regexp slightly. + + Fix some more shell quoting problems. Prompted by a bug report + from Justace Clutter. + * lib/autoconf/general.m4 (_AC_INIT_DIRCHECK): Put name of invalid + variable into diagnostic. Make the diagnostic an error, not a warning, + because we really don't support spaces and suchlike in dir names. + (_AC_INIT_SRCDIR): Allow special characters in $ac_unique_file. + Don't worry about backslashes in srcdir; it can't happen now. + (_AC_INIT_PARSE_ARGS): Allow weird characters in ac_optarg. + Simplify ac_optarg handling. + (_AC_ARG_VAR_VALIDATE): Remove unnecessary and inconsistent quotes. + +2005-06-22 Stepan Kasal + + Fix AT_CONFIG_CMP for Solaris hosts; idea from Ralf Menzel. + * configure.ac: Call AC_PROG_EGREP and AC_PROG_SED. + * tests/atlocal.in: Propagate $EGREP and $SED. + * tests/local.at (AT_CHECK_ENV): Use $EGREP, not $GREP -E. + (AT_CONFIG_CMP): Use sed instead of grep plumbing. + + * doc/autoconf.texi (Limitations of Usual Tools) : Mention + that '\|' is not allowed in BREs; recommend using newline separated + list of patterns instead of multiple -e options. + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Remove an old comment. + + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): Use AC_SUBST/2. + +2005-06-22 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): Fix typo. + +2005-06-21 Stepan Kasal + + * doc/autoconf.texi (Limitations of Usual Tools) : Document that + b, t, r, w commands require single space, while : cannot have any. + (Special Shell Variables): Fix sed code this in the example. + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS): Likewise; and fix a typo. + * lib/autotest/general.m4 (AT_ARG_OPTION): Fix typo in the description. + + * lib/m4sugar/m4sugar.m4 (m4_split): If the parameter is empty, + expand to the empty list. Don't use two pairs of m4_changequote, + it's not necessary. + +2005-06-20 Derek Price + + * lib/m4/programs.m4 (AC_PROG_YACC): Declare YACC & YFLAGS precious. + +2005-06-17 Paul Eggert + + * lib/m4sugar/m4sh.m4 (as_awk_strverscmp): Port to Solaris /bin/awk. + * doc/autoconf.texi: + Don't mention Solaris versions so much, if a + problem is common to all extant versions of Solaris. Say "SunOS + 4" instead of "SunOS" for SunOS 4. + (awk): Mention more of the limitations of traditional Awk. + (cat): Don't talk about cat -v. + +2005-06-16 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_VERSION_COMPARE_PREPARE): New macro. + (AS_VERSION_COMPARE): New macro. The API is taken from CVS, + but the implementation is entirely different and is designed + to be compatible with glibc strverscmp. + * tests/m4sh.at (AS_VERSION_COMPARE): New test. + + * doc/autoconf.texi (Limitations of Usual Tools): Mention expr bug + on Mac OS X 10.4 reported by Peter O'Gorman in: + http://lists.gnu.org/archive/html/autoconf-patches/2005-06/msg00041.html + * lib/autoconf/general.m4 (_AC_CANONICAL_SPLIT): + Use shell builtins rather than 'expr', to work around expr bug. + +2005-06-10 Paul Eggert + + * doc/autoconf.texi: "filesystem" -> "file system". + "behaviour" -> "behavior". + Warn about \(...\)* in Solaris sed (written by Ralf Menzel). + * lib/autoconf/general.m4: Omit blank after ":" sed command, + as per POSIX. + * lib/m4sugar/m4sh.m4: Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS): Work around problem + with Solaris sed. Fix by Ralf Menzel and Stepan Kasal. + + * man/Makefile.am (MOSTLYCLEANFILES): Add $(srcdir)/*.t. + (.x.1): Ignore the time stamp in the .TH line when deciding whether + to update the man page. That way, we don't have to check in new + man pages every month. + + * lib/m4sugar/m4sh.m4 (AS_VAR_TEST_SET): Work even if $1 contains + quotes and backslashes. Patch from Derek Price. + +2005-06-10 Derek Price + + * doc/autoconf.texi (Programming in M4sh): Document AS_TR_CPP & + AS_TR_SH. + +2005-06-08 Paul Eggert + + * lib/autotest/general.m4 (AT_INIT): Don't accept Solaris 9's diff + -u, since it outputs chatter if the input files are the same. + Problem reported by Ralf Menzel. + +2005-06-08 Derek Price + + * lib/m4sugar/m4sugar.m4: Undefine include & sinclude rather than + renaming them since they are about to be redefined anyhow. + +2005-06-08 Derek Price + + * doc/autoconf.texi (Redefined M4 Macros): Add index entries for most + redefined M4 macros to this node. Document m4_include & m4_sinclude. + Move m4_undefine to alphabetical order. + +2005-06-07 Paul Eggert + + * README: Recommend GNU M4 1.4.3 or later. + * doc/autoconf.texi (Introduction): Likewise. + Reword to avoid some formatting glitches. + Use "#!/bin/sh", not "#! /bin/sh"; the space isn't needed these days. + Clarify explanation of HP compiler bug. + Redo example output tp match current CVS snapshot. + Use @example.org in email addresses when the examples + might get inadvertently cut-and-pasted into user code. + Remove example of autom4te usage that doesn't seem to work now. + Use modern AC_INIT (except when the example is meant to be + shown with Autoconf 2.13). + Update ksh info for Solaris 9 and later. + KB -> kB. + Modernize description of Automake versions a bit. + Don't claim a future version of Autoconf is near. + * doc/install.texi: Reword to avoid some formatting glitches. + +2005-06-07 Ralf Wildenhues + + * doc/autoconf.texi: Add [] to examples, so that the manual + follows its own advice about quoting better. + Reword to avoid some formatting glitches. + * doc/installt.exi: Reword to avoid some formatting glitches. + + * doc/autoconf.texi (Limitations of Builtins) : Mention + Tru64 ksh pattern matching bug. Reported against Libtool by + Albert Chin and + Nicolas Joly . + +2005-06-06 Stepan Kasal + + m4_cdr of one-member list was [[]] (one-member list containing an + empty string) instead of [] (an empty list. Callers were skewed to + match this misbehaviour. As a consequence of this: + - m4_foreach([x], [], [foo]) expanded to `foo', while + - the expansion of m4_foreach([x], [[]], [foo]) was empty. + This bug has been fixed: + + * lib/m4sugar/m4sugar.m4 (m4_cdr): If only one argument is given, + expand to an empty string; print error msg if called without + an argument list. + (m4_foreach, m4_map, m4_map_sep): Don't expect the previous + misbehaviour; handle [] and [[]] correctly. + +2005-06-06 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Nuke ac_max_here_lines. + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS): Simplify the sed + scripts created and the loop applying them, use _AC_SED_CMD_LIMIT. + +2005-06-06 Ralf Menzel (trivial change) + + * doc/autoconf.texi (Limitations of Usual Tools): Solaris' awk cannot + swallow records with more than 99 fields. + * lib/autotest/general.m4 (AT_INIT): Use the awk builtin `split' to + parse the long line. + +2005-06-04 Stepan Kasal + + * doc/autoconf.texi (Limitations of Usual Tools): AIX awk cannot + swallow literals longer than 399. Reported by Ralf Wildenhues. + * lib/autotest/general.m4 (AT_INIT): Pass $at_groups though stdin, + to workaround this limitation. + +2005-06-03 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Find g95 in addition + to gfortran, and make these the first two compiler names + checked (following the general autoconf preference for gcc). + +2005-06-03 Stepan Kasal + + * tests/Makefile.am (check_SCRIPTS): Set to $(wrappers). + (DISTCLEANFILES): Remove $(check_SCRIPTS). + (testsuite): Make sure autotest.m4f is up-to-date before using it. + +2005-06-02 Paul Eggert + + * lib/autotest/general.m4 (AT_INIT): Don't create a regular + expression of unbounded size when processing the --list + option. This runs afoul of a limit of 399 bytes per regular + expression on AIX. Problem reported by Ralf Wildenhues. + +2005-06-01 Paul Eggert + + * NEWS: Note yesterday's changes to AC_SUBST and AC_SUBST_FILE. + * doc/autoconf.texi (Particular Headers): Reword example + for multiline stdbool replacement. + (Setting Output Variables): Reword text a bit. Don't + give all the details about |#_!!_#|. + Reword description of line replacement. + +2005-05-31 Dan Manthey + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES): Output variables may + now contain newlines, and substituted files must be referenced on + a line alone; the sed scripts to substitute them are now very + different. + (_AC_SED_CMD_LIMIT): Added; single place to store limit on how many + commands can be put in a sed script portably. + * doc/autoconf.texi (Setting Output Variables): Document above + changes. (Particular Header Checks) : Give exaple + use of multiline substitution. + * tests/torture.at: No longer expect substitution of newline to fail. + +2005-05-27 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_WORK): Fix diagnostics. + From Ralf Menzel (trivial change). + +2005-05-25 Paul Eggert + + * tests/local.at: Don't attempt to check for negated character + classes in shell scripts. The test was too brittle. + +2005-05-25 Stepan Kasal + + * bin/autoconf.as: Don't use "shift 2"; it's not portable enough. + * doc/autoconf.texi (Limitations of Builtins): Document this + limitation. + +2005-05-24 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (_AS_ECHO_LOG): New macro to factor out + common code; used in many places in the tree. + (AS_ESCAPE): Make the pattern a bit simpler; use \& insetad of \1. + (_AS_ECHO_UNQUOTED): Move the macro lower; no code change. + + * lib/m4sugar/m4sugar.m4 (m4_ifset): Use m4_ifval. + + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): Merge the two error + messages when ac_unique_file is not found. + (AC_CONFIG_MACRO_DIR): Simplify the `if' at the end. + (AC_MSG_CHECKING, AC_MSG_RESULT): Put braces around the two echo + commands, for consistency with AC_MSG_ERROR and such. + + * bin/autoconf.as: Make more use of "shift 2" in option processing. + + * bin/Makefile.am: Merge the two rules for creating scripts. + +2005-05-23 Stepan Kasal + + * lib/autoconf/general.m4 (AC_MSG_RESULT_UNQUOTED): Make + obsolete; it was never documented. + (AC_CACHE_CHECK): Use AC_MSG_RESULT instead. + +2005-05-20 Stepan Kasal + + * NEWS: @top_builddir@ is now a dirname, ac_top_builddir will follow. + * lib/autoconf/status.m4 (_AC_SRCDIRS): Rename ... + (ac_top_builddir): ... this ... + (ac_top_build_prefix): ... to this; the old name is also kept, for + backward compatibility. + (ac_top_builddir_sub): New variable, without the trailing slash, + always nonempty. + (_AC_OUTPUT_FILES): s/@top_builddir@/$ac_top_builddir_sub/ + * doc/autoconf.texi (Configuration Actions): Rename + ac_top_builddir to ac_top_build_prefix. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Rename + at_top_builddir to at_top_build_prefix. + * lib/autotest/general.m4 (AT_INIT): Likewise. + +2005-05-20 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Simplify the init + of confdefs.h . + +2005-05-17 Stepan Kasal + + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Don't m4_quote the second + argument to m4_foreach. I guess it was necessary in the past, + but I think it's a no-op now. + +2005-05-17 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_HELP): Merge two consecutive + ``cat <<_ACEOF'' commands to one. + (_AC_CANONICAL_SPLIT): Use expr, not ``echo|sed.'' + * lib/autoconf/status.m4: On various places, use expr instead of + ``echo|sed.'' + (_AC_CONFIG_SPLIT, _AC_CONFIG_SPLIT_SOURCE_DEST): + (_AC_CONFIG_SPLIT_FILE_IN): New macros, to factor out common code. + * lib/autotest/general.m4 (AT_INIT): Use expr to get the numbers from + a range. + * tests/local.at (AT_CHECK_SHELL_SYNTAX): Use awk to search for + the wrong patterns between ``case'' and ``esac.'' The previous + code had false positives. + +2005-05-14 Alexandre Duret-Lutz + + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA): Prepend ${LIBOBJDIR}, + as on 2005-05-02. + * doc/autoconf.texi (Particular Functions) : + Mention LIBOBJDIR. + +2005-05-13 Paul Eggert + + * AUTHORS, BUGS, COPYING, ChangeLog, ChangeLog.0, ChangeLog.1, + ChangeLog.2, GNUmakefile, Makefile.am, Makefile.cfg, + Makefile.maint, NEWS, README, README-alpha, TODO, configure.ac, + bin/Makefile.am, bin/autoconf.as, bin/autoheader.in, + bin/autom4te.in, bin/autoreconf.in, bin/autoscan.in, + bin/autoupdate.in, bin/ifnames.in, config/Makefile.am, + config/config.guess, config/config.sub, config/elisp-comp, + config/m4.m4, config/mdate-sh, config/missing, config/texinfo.tex, + doc/Makefile.am, doc/fdl.texi, lib/Makefile.am, lib/autom4te.in, + lib/freeze.mk, lib/Autom4te/C4che.pm, lib/Autom4te/ChannelDefs.pm, + lib/Autom4te/Channels.pm, lib/Autom4te/Configure_ac.pm, + lib/Autom4te/FileUtils.pm, lib/Autom4te/General.pm, + lib/Autom4te/Request.pm, lib/Autom4te/Struct.pm, + lib/Autom4te/XFile.pm, lib/autoconf/Makefile.am, + lib/autoconf/autoconf.m4, lib/autoconf/autoheader.m4, + lib/autoconf/autoscan.m4, lib/autoconf/autotest.m4, + lib/autoconf/autoupdate.m4, lib/autoconf/c.m4, + lib/autoconf/fortran.m4, lib/autoconf/functions.m4, + lib/autoconf/general.m4, lib/autoconf/headers.m4, + lib/autoconf/lang.m4, lib/autoconf/libs.m4, + lib/autoconf/oldnames.m4, lib/autoconf/programs.m4, + lib/autoconf/specific.m4, lib/autoconf/status.m4, + lib/autoconf/types.m4, lib/autoscan/Makefile.am, + lib/autoscan/autoscan.list, lib/autoscan/autoscan.pre, + lib/autotest/Makefile.am, lib/autotest/autotest.m4, + lib/autotest/general.m4, lib/emacs/Makefile.am, + lib/emacs/autoconf-mode.el, lib/emacs/autotest-mode.el, + lib/m4sugar/Makefile.am, lib/m4sugar/m4sh.m4, + lib/m4sugar/m4sugar.m4, man/Makefile.am, tests/Makefile.am, + tests/atlocal.in, tests/autotest.at, tests/base.at, tests/c.at, + tests/compile.at, tests/foreign.at, tests/fortran.at, + tests/local.at, tests/m4sh.at, tests/m4sugar.at, tests/mktests.sh, + tests/semantics.at, tests/suite.at, tests/tools.at, + tests/torture.at, tests/wrapper.as: + Update FSF postal mail address. + +2005-05-13 Stepan Kasal + + * lib/autoconf/general.m4 (AC_CONFIG_LIBOBJ_DIR): Remove the broken + check. + * lib/m4sugar/m4sugar.m4 (m4_bmatch): Halt with error if we don't get + enough arguments, similarly as in m4_bpatsubsts. + +2005-05-12 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_SRCDIRS): Simplify the computation + of absolute paths. + +2005-05-11 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Make the check + for absolute directory names in one loop. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Handle + abbreviations of --version and --debug. + +2005-05-10 Paul Eggert + + * doc/autoconf.texi (Autoconf Language): Be more precise about + quoting rules. Problems noted by Stepan Kasal. + Also, throughout this document, be more careful about white space. + "blank", "white space", and "space" all have different meanings + and we should be careful to say what we mean. + +2005-05-05 Paul Eggert + + Fix C++ related problems reported by Werner Lemberg. + * doc/autoconf.texi (C++ Compiler): Mention .cpp extension. + * lib/autoconf/c.m4 (AC_LANG(C++)): Set ac_ext to .cpp, not .cc. + * lib/autoconf/types.m4 (AC_TYPE_SIGNAL): Simplify test, to + avoid problems with C++ and throw. + * tests/compile.at: .cpp, not .cc. + + * tests/semantics.at: Prepend LIBOBJDIR, as per 2005-05-02 change. + +2005-05-05 Ralf Wildenhues + + * doc/autoconf.texi (Generic Functions): Typos. + +2005-05-02 Gary V. Vaughan + + * lib/autoconf/general.m4 (_AC_LIBOBJS_NORMALIZE): Prepend each + object named in LIBOBJS and LTLIBOBJS with the ${LIBOBJDIR}, as + set by latest automake. + +2005-05-01 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): "expr '' \| ''" + outputs 0 on GNU/Linux these days. + +2005-04-29 Paul Eggert + + * doc/autoconf.texi (Autoconf Language): Add more description + about quoting heuristics. + (Limitations of Builtins): Describe "set -" problems. + +2005-04-29 Ralf Wildenhues + + * lib/autotest/general.m4 (AT_KEYWORDS): Separate by space, + not newline. + + * doc/autoconf.texi (External Software): Replace AC_DEFINE_UNQUOTED + by AC_DEFINE; it was a mistake. + From bug reported against libtool by Dalibor Topic . + +2005-04-25 Stepan Kasal + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS): A tiny optimization. + +2005-04-22 Stepan Kasal + + * doc/autoconf.texi (External Software): Quadrigraphs are not + processed correctly in AS_HELP_STRING; avoid this in the examples. + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): Add a FIXME about quadrigraphs. + * lib/m4sugar/m4sugar.m4 (m4_text_wrap): Likewise; and rephrase the + comment and reduce m4_default([foo], []) to [foo]. + (m4_strip): Update the explanation. + +2005-04-19 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE, _AC_RUN_IFELSE): + Remove core.conftest.* too; it's generated by Tru64 5.1. + Problem reported by Jennis Pruett. + * lib/autoconf/functions.m4 + (AC_FUNC_SETVBUF_REVERSED, AC_FUNC_UTIME_NULL): + Don't bother to remove core files; AC_RUN_IFELSE should do that + for you. + +2005-04-19 Stepan Kasal + + * lib/m4sugar/m4sugar.m4 (m4_bpatsubsts): Add the b- to comment, too. + +2005-04-19 Alexandre Duret-Lutz + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Handle --docdir. + Report from Horst Wente. + +2005-04-15 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_ARG_VAR_VALIDATE): Fixed a typo in + the comment. + +2005-04-14 Gregorio Guidi + + * doc/autoconf.texi (External Software, Package Options): Add + examples showing how to implement --with-* and --enable-* options. + +2005-04-13 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Look for configure.ac + as well as configure.in. Problem reported by Gregorio Guidi. + +2005-04-10 Paul Eggert + + * doc/autoconf.texi (Particular Functions): Use gnulib's current + pattern for alloca snippet. + +2005-04-04 Stepan Kasal + + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): Fix a typo. + +2005-04-01 Stepan Kasal + + * doc/autoconf.texi (Generic Programs): Fix a typo. + +2005-04-01 Paul Eggert + + * lib/autotest/general.m4 (AT_INIT): Don't assume that "date +%s" + fails if %s isn't supported. Problem reported by Ralf Wildenhues. + +2005-03-22 Ralf Wildenhues + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): + Merge `-z option' as well for the benefit of Solaris link flags. Pass + whole-archive (-zallextract, -zdefaultextract) options in the hope of + unique libraries, for the Sun Fortran 95 8.0 compiler. Bug reported + against Libtool by Yury Puhalsky . + +2005-03-22 Paul Eggert + + * NEWS: The configure command now warns you if you attempt to use + a directory whose name contains a special character like space, + newline, or "\". + * doc/autoconf.texi (Installation Directory Variables): Allow + "," in file names. Do not use \@; it's not a portable regexp. + * bin/Makefile.am (edit): Likewise. + * lib/Makefile.am (edit): Likewise. + * tests/Makefile.am (edit): Likewise. + * tests/semantics.at: Likewise. + * tests/torture.at: Likewise. + * lib/autoconf/general.m4 (AC_ARG_PROGRAM): Likewise. + * lib/autoconf/status.m4 (_AC_SRCDIRS): Likewise. + * doc/autoconf.texi (File System Conventions): Warn about + unportable file names. + * lib/autoconf/general.m4 (_AC_INIT_DIRCHECK): New macro. + (AC_INIT): Use it. + (_AC_INIT_SRCDIR): Use ac_pwd rather than invoking pwd. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Propagate + ac_pwd, and quote srcdir. + * lib/autotest/general.m4 (AT_INIT): Quote file name args. + + * doc/autoconf.texi: Fix some systematic formatting problems. + ".)" needs a following @: if not at the end of a sentence, and + similarly for "!)". "etc." should be preceded by a comma. + "n-th" -> "@var{n}th". pdksh is still buggy, so update its date. + +2005-03-22 Bruno Haible + + * doc/autoconf.texi (Input): Mention that AC_CONFIG_AUX_DIR's + argument is often called 'build-aux'. + +2005-03-07 Stepan Kasal + + * doc/autoconf.texi (Quotation Rule Of Thumb): Mention that the + macro AC_TRY_LINK is obsolete. + (Installation Directory Variables): Change `AC_OUTPUT_FILES' to + `AC_CONFIG_FILES'. + +2005-02-24 Stepan Kasal + + * lib/autoconf/c.m4 (AC_PROG_CC): Be more careful to skip + `/usr/ucb/cc'; use `cl.exe' to distinguish the MS compiler + from a Common Lisp's `cl'. + (AC_PROG_CXX): Behave according to the documentation: don't + search for $ac_tool_prefix$CCC and $CCC, just set CXX=$CCC; + make the variable CCC precious; use `cl.exe', not `cl'. + +2005-02-23 Paul Eggert + Alexandre Duret-Lutz + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Redirect stdin from + /dev/null, as "configure" shouldn't read stdin, and this insulates + us from problems (e.g., when testing for "cl"). Also, do this + redirection before invoking "hostname" or "uname", and keep the + original input stream available via... + (AS_ORIGINAL_STDIN_FD): ... this new macro. + (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, _AC_LINK_IFELSE): Don't + bother with " + + * lib/m4sugar/m4sh.m4 (_AS_ECHO_N_PREPARE): Don't set ECHO_C to + newline if neither \c nor -n work, as that would output two + newlines. Prefer -n to \c. Reported by Stepan Kasal. + +2005-02-12 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_IF): Define by m4_defun, not m4_define. + This causes that any required macros inside will get before the if. + * doc/autoconf.texi (autom4te.cache): A typo. + +2005-02-12 Paul Eggert + + Undo previous change, except keep the change to + lib/autoconf/programs.m4 that replaced grep with shell + pattern-matching. This is because net-snmp configure reads stdin. + Reported by Noah Misch. + +2005-02-11 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Redirect stdin + from /dev/null, as "configure" shouldn't read stdin, and this + insulates us from problems (e.g., when testing for "cl"). + Suggested by Alexandre Duret-Lutz. Also, do this redirection + before invoking "hostname" or "uname". + (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, + _AC_LINK_IFELSE): Undo previous change, as it's no longer needed. + * lib/autoconf/c.m4 (AC_PROG_CC, AC_PROG_CXX): Don't bother with + " + + * lib/autoconf/general.m4 (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, + _AC_LINK_IFELSE): Redirect stdin to /dev/null, in an attempt to + avoid thinking that Allegro Common Lisp's "cl" command is a C++ + compiler. + +2005-02-09 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Document that + grep -q isn't portable. Improve grep -s explanation. + Problem reported by Dan Manthey. + +2005-02-08 Paul Eggert + + * doc/autoconf.texi (Special Shell Variables): Clarify + PATH_SEPARATOR wording; fix typo in IFS. Reported by Gary V. Vaughan. + +2005-02-07 Paul Eggert + + * doc/autoconf.texi: Use @acronym for DJGPP. + Fix some @code's that should have been @env's, and vice versa. + Sort environment variable names. + Mention that shells no longer inherit IFS. + Don't recommend PATH_SEPARATOR=';' so strongly. + Mention that $RANDOM might expand to the empty string. + "symlink" and "soft link" -> "symbolic link". + Improve mktemp description (reported by Bruno Haible). + +2005-02-05 Paul Eggert + + * tests/foreign.at (Libtool): Don't overquote AT_SETUP arg. + * tests/m4sh.at (AS_DIRNAME, AS_BASENAME, AS_MKDIR_P, AS_HELP_STRING): + Likewise. + * tests/semantics.at (AC_C_BIGENDIAN, AC_PATH_PROG & AC_PATH_PROGS): + Likewise. + +2005-02-04 Paul Eggert + + * NEWS: Mention AT_COPYRIGHT. + + * tests/local.at (AT_CMP): Use diff directly on input files rather + than copying them. + + * lib/autoconf/programs.m4 (AC_PROG_SED): Don't look in + /usr/xpg4/bin since that sed dumps core (at least on Solaris 8). + +2005-02-04 Noah Misch + and Paul Eggert + + * tests/autotest.at (Empty test suite): New test. + * tests/torture.at (Substitute and define special characters) + (Substitute a 2000-byte string, Define to a 2000-byte string) + (Substitute a newline, Define a newline): New tests. + +2005-02-04 Noah Misch + + * lib/m4sugar/m4sugar.m4 (m4_re_string, m4_re_word): Revert 2002-03-04. + * tests/local.at (AT_CHECK_M4SUGAR): Add `m4sugar' to keywords. + (AT_CHECK_ENV): Ignore LTLIBOBJS, FC variables, EGREP, FGREP, and SED. + * tests/m4sugar.at (AT_CHECK_M4SUGAR_TEXT, AT_CHECK_M4RE): New macros. + (Standard regular expressions): New test. + (m4_warn, m4_require: circular dependencies, m4_text_wrap): Strip + excess test name quoting. + * tests/semantics.at (AC_CHECK_HEADERS_OLD, AC_CHECK_HEADERS_NEW): Pass + CPPFLAGS to `configure' instead of setting it in `configure'. + + * lib/m4sugar/m4sh.m4 (AS_UNAME): Try only /usr/bin/hostinfo, not + any `hostinfo' in $PATH, since hostinfo.exe is a popular file name + on some platforms. + + * lib/autoconf/fortran.m4 (AC_LANG(Fortran), AC_FC_SRCEXT): + s/FC_SRCEXT/ac_fc_srcext/; s/FCFLAGS_SRCEXT/ac_fcflags_srcext/. + + * tests/local.at (AT_CMP): New macro. + (AT_DATA_AUTOCONF): Do not call AC_PROG_GREP. + (AC_SAVE_STATE): Move environment grep... + (AT_CHECK_ENV): to here. Filter out `'$''. Use AT_CMP. + (AT_CONFIG_CMP): New macro. + (AT_CHECK_MACRO): Run `configure' twice with cache and compare results. + * tests/c.at (Extensions): Do not exit early. + * tests/atlocal.in: Inherit $GREP. + + * lib/autoconf/c.m4 (_AC_C_STD_TRY): New macro. + (_AC_PROG_CC_C89, _AC_PROG_CC_C99): Use it. + + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Update for 2005. + (AC_COPYRIGHT): Factor header comment portion out and move into... + * lib/m4sugar/m4sh.m4 (AS_COPYRIGHT): This. + * lib/autotest/general.at (AT_COPYRIGHT): New macro. + (AT_INIT): Add Autotest copyright notice. Display copyright notices in + --version output. + * tests/local.at: Add Autoconf test suite copyright notice. + * doc/autoconf.texi (Writing testsuite.at): Document AT_COPYRIGHT. + +2005-02-04 Bruno Haible + and Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): New mkstemp entry. + +2005-02-03 Paul Eggert + + * lib/m4sugar/m4sugar.m4 (m4_re_escape): Escape ?, ^, \, $ too; + this fixes a bug tickled by the AT_CAPTURE_FILE change noted below. + + Try not to generated lines of unlimited length, as POSIX places a + 2047-byte limit on line length of portable text files. + * lib/autoconf/general.m4 (AC_SUBST, AC_SUBST_FILE): + Use newline as a separator, not space. + * lib/autotest/general.m4 (AT_TESTED, AT_KEYWORDS): Likewise. + (AT_CAPTURE_FILE): Use space-backslash-newline as a separator, not + space. + +2005-02-03 Ralf Wildenhues + + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_WORK): Move func_* to + as_func_*. Add test to check whether positional parameters + are restored after function return. + +2005-02-02 Paul Eggert + + * doc/autoconf.texi (Special Shell Variables): Mention _, + BIN_SH, DUALCASE. Say that variables other than "status" are safe + if they contain a lower-case letter. The DUALCASE problem was + reported by Ralf Wildenhues. + + * bin/autoconf.as: Don't exit with status 0 after write failure + with --help or --version. + * lib/autoconf/general.m4 (_AC_INIT_HELP, _AC_INIT_VERSION): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Likewise. + +2005-02-02 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Usual Tools): + Unicos 9 sed limitations. + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Try cf77 before fort77 + to get the option-enhanced interface on older Crays. Try ftn for + Fortran 95 (newer Crays). + +2005-02-01 Paul Eggert + + * man/Makefile.am (.x.1): Go back to the simple solution, but take + care to echo the commands, so the user knows what's going on. + Modified from a suggestion by Stepan Kasal. + + * doc/autoconf.texi (autoreconf Invocation): Mention autopoint, + with a cross reference. Derived from a suggestion by Bruce Korb. + +2005-01-31 Paul Eggert + + * doc/autoconf.texi (config.status Invocation): Warn about + discrepancy between CONFIG_SHELL and shell used to invoke 'configure'. + * doc/install.texi (Defining Variables): Likewise. + Based on a proposed patch by Ralf Wildenhues. + + * man/Makefile.am (.x.1): Make sure the required generated files + are up to date. Problem and original solution proposed by Stepan Kasal. + $(dist_man_MANS:.1=-bin-prereq), $(dist_man_MANS:.1=-tests-prereq), + implicit-man-prerequisites): New rules, used by the above. + + * doc/make-stds.texi, doc/standards.texi: Sync from gnulib. + * config/config.guess, config/config.sub, config/install-sh: Likewise. + * config/missing, config/texinfo.tex: Likewise. + +2005-01-29 Stepan Kasal + + Simplify the implementation of m4_require (a.k.a. AC_REQUIRE). + Update the long comment explaining it. + + m4_require no longer writes an ``is required by'' line to the + execution stack. It contains only one bit of non-redundant + information: that the macro was required, not called. And even + this bit is useless in most situations: have you ever met a macro + which both calls and requires the same macro? + + * lib/m4sugar/m4sugar.m4 (_m4_defun_pro): Don't push a diversion... + (_m4_defun_pro_outer): ... only via this macro, for the outermost + macro. + (_m4_defun_epi, _m4_defun_epi_outer): Complementarily. + (m4_expansion_stack_pop): Remove the misplaced comment. + (m4_require): Don't put the ``is required by'' line to the + execution stack; slightly improve the out-of-a-defun error message. + (_m4_divert_grow): New macro, counter for the temporary diversions. + (_m4_require_call): Use it. + * tests/m4sugar.at (m4_require): Expect output without the + ``is required by'' messages. + +2005-01-28 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Recommend X + rather than x for expr. + + * lib/autoconf/lang.m4 (_AC_COMPILER_OBJEXT): Avoid subshells when + this is safe. + * lib/autoconf/programs.m4 (AC_PROG_EGREP, AC_PROG_FGREP): Likewise. + * lib/autoconf/specific.m4 (AC_SYS_LONG_FILE_NAMES): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/m4sugar/m4sh.m4 (_AS_LINENO_WORKS): Likewise. + * tests/mktests.sh: Likewise. + +2005-01-27 Akim Demaille + + Have autoheader honor --force. + + * doc/make-stds.texi, doc/standards.texi: Update from masters. + * lib/Autom4te/Channels.pm, lib/Autom4te/Configure_ac.pm + * lib/Autom4te/FileUtils.pm, lib/Autom4te/XFile.pm: Update + from masters, so that FileUtils.pm's update_file provide --force + support. + * bin/autoheader.in: Pass $force to update_file so that + config.h.in is always recreated when --force. + +2005-01-24 Stepan Kasal + + * doc/autoconf.texi (Introduction): Update Peter Simons' address. + +2005-01-21 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Clarify that + "if test ! -d foo; ..." is portable. Suggested by Stepan Kasal. + +2005-01-20 Paul Eggert + + * doc/autoconf.texi (Shell Substitutions): Fix typo in case statement. + Warn about newline stripping in `` and $(). Update Solaris + version to 9. + (Limitations of Builtins): Use expr "X...", not expr "x...", as + X insulates us from future changes to Posix. + (Limitations of Usual Tools): For AS_DIRNAME, warn about newline + stripping. + +2005-01-19 Stepan Kasal + + * doc/autoconf.texi (Defining Symbols): Delete the false comment that + you cannot use AC_DEFINE to define macros containing `[' or `]'. + +2005-01-13 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Document bug + in Solaris 8 join. Problem reported by Tomohiro Suzuki on + bug-tar mailing list. + +2005-01-05 Stepan Kasal + + * lib/m4sugar/m4sugar.m4 (m4_copy): Fix the explanation. + +2005-01-05 Paul Eggert + + * lib/autoconf/c.m4 (AC_LANG_INT_SAVE(C)): Declare longval and + ulongval to be static, to avoid unwanted GCC warning. Problem + reported by Michael Jennings via Daniel Reed; see + . + +2005-01-05 Alexandre Duret-Lutz + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Define datarootdir, + docdir, htmldir, dvidir, pdfdir, psdir, and localdir. Update + datadir, infodir, and mandir. Adjust argument parsing code. + (_AC_INIT_HELP): Update help text. + * doc/autoconf.texi (Installation Directory Variables): Document + new variables. + +2005-01-04 Noah Misch + + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): If the Make program does + not seem to work, assume it does set $(MAKE). + * doc/autoconf.texi (AC_PROG_MAKE_SET): Update. + +2005-01-03 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Add a comment about nesting. + +2005-01-03 Stepan Kasal + + A cleanup of the diversion support in m4sugar. + + * lib/m4sugar/m4sugar.m4 (_m4_divert): A typo in description. + (_m4_divert_n_stack): New macro; the expansion is + m4_divert_stack, if m4_divert_stack is defined, and void + otherwise. + (m4_divert, m4_divert_push, m4_divert_pop, m4_init): Use it. + (m4_divert_push, m4_divert_pop, _m4_defun_epi): Don't expand the word + stored in _m4_divert_diversion or _m4_divert_dump. + (m4_divert_pop): When the parameter is given, compare the symbolic + name with the last diversion pushed on the stack. Previously, the + current diversion was compared with the numeric value of the + diversion given as the parameter. + (m4_require): If the macro hasn't been expanded yet, call ... + (_m4_require_call): this new macro. + +2005-01-03 Ralf Wildenhues + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE, _AC_ARG_VAR_VALIDATE): + Workarounds for documented `case' limitations. + +2005-01-03 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Warn about + sed 'command1;command2'. Problem reported by Ralf Wildenhues. + +2005-01-02 Paul Eggert + + * bin/autoconf.as, bin/autoheader.in, bin/autom4te.in, + bin/autoreconf.in, bin/autoscan.in, bin/autoupdate.in, + bin/ifnames.in, tests/mktests.sh: Update copyright date to 2005. + + Patch from Roger Leigh (with some minor changes) as follows: + * NEWS: New macros AC_PROG_CC_C89, AC_PROG_CC_C99. + Resurrect AC_PROG_CC_STDC. + * doc/autoconf.texi (C Compiler): Add AC_PROG_CC_STDC, + AC_PROG_CC_C89, AC_PROG_CC_C99. + (Obsolete Macros): Remove AC_PROG_CC_STDC; it's no longer obsolete. + * lib/autoconf/c.m4 (_AC_PROG_CC_C89, _AC_PROG_CC_C99, AC_PROG_CC_C89, + AC_PROG_CC_C99): New macros. + (AC_PROG_CC_STDC): Use them. + (_AC_PROG_CC_STDC): Remove. + (AC_C_PROTOTYPES): Use ac_cv_prog_cc_c89, not ac_cv_prog_cc_stdc. + * THANKS: Add Roger Leigh. + +2004-12-30 Noah Misch + + * bin/autoreconf.in (autoreconf_current_directory): AM_INIT_AUTOMAKE + signals that the package uses Automake; a `Makefile.am' is typical but + not essential. Reported by Magnus Therning. + * tests/torture.at (autoreconf.): New banner. + (autoreconf and non-AC configure): Rename to `Non-Autoconf + AC_CONFIG_SUBDIRS'. + (autoreconf an empty directory): Rename to `Empty directory'. + (Unusual Automake input files): New test. + +2004-12-30 Noah Misch + + * lib/autotest/general.m4 (AT_CAPTURE_FILE): New macro. + (AT_SETUP): Clear AT_capture_files. + (_AT_CHECK): On failure, log each of AT_capture_files. Fix comment. + (AT_KEYWORDS): Fix comment typo. + * tests/autotest.at (AT_CHECK_AT): Use AT_CAPTURE_FILE. + * tests/local.at (AT_CHECK_CONFIGURE): Use AT_CAPTURE_FILE. + * doc/autoconf.texi (Writing testsuite.at): Document AT_CAPTURE_FILE. + +2004-12-29 Albert Chin-A-Young + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): + If the variable to set is already set, set ac_cv_path_$1 + to the preset value so caller can assume ac_cv_path_$1 + is available. (trivial change) + +2004-12-27 Noah Misch + + * BUGS (Minor Problems): Warn about makefile limitations. + * Makefile.am: Find and update `INSTALL' in $(srcdir). + * man/Makefile.am: Find and update manual pages in $(srcdir). + +2004-12-24 Eric Blake + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Test candidate + shells in subshell, to avoid noise from ash. (trivial change) + +2004-12-22 Ralf Wildenhues + + * doc/autoconf.texi (Limitations of Builtins) : Mention + problems with SunOS ksh and backslash escaping, Bourne shells and + closing brackets (both within character classes). Bug reported + against Libtool by Alexander Kurz . + : New entry. Mention non-availability of -r. + +2004-12-21 Akim Demaille + + * lib/autotest/general.m4 (AT_LINE): Don't add srcdir here, to + avoid cluttering displayed messages. Rather, prepend srcdir where + AT_LINE is used for log files. + +2004-12-21 Stepan Kasal + + * lib/autoconf/status.m4: Quote ``$tmp'' in many places. + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Fix the comment, as traps are + no longer part of the macro, quote the occurrence of ``$tmp''. + * doc/autoconf.texi (Forbidden Patterns): Typo. + +2004-12-21 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Make sure the "ok" etc. are + separated from the test title by forcing a white space. + +2004-12-21 Akim Demaille + + Enable Emacs navigation within testsuite.log files. + + * lib/autotest/general.m4 (AT_CLEANUP): Add an hint for Emacs to + use the compilation mode. + (AT_LINE): Point to the srcdir. + +2004-12-19 Noah Misch + + * tests/Makefile.am (installcheck-local): Use $(bindir). + (check-local, installcheck-local): Pass TESTSUITEFLAGS. + * doc/autoconf.texi (Making testsuite Scripts): Recommend the same + Makefile.am scheme Autoconf now uses. + +2004-12-18 Noah Misch + + * lib/m4sugar/m4sugar.m4 (m4_qlen, m4_qdelta): New macros. + * lib/autotest/general.m4 (AT_SETUP): Use m4_qdelta. + +2004-12-18 Noah Misch + + * lib/autotest/general.m4 (_AT_DECIDE_TRACEABLE): New macro. + (_AT_CHECK): Use it. + * lib/m4sugar/m4sh.m4 (AS_ESCAPE_FOR_EXPAND): Remove. + (AS_ESCAPE): Fix comment. + * tests/autotest.at: Adjust section banner comments. + (AT_CHECK_AT): Accept STATUS and STDERR. + (AT_CHECK_AT_TEST): Likewise. + (Invalid brace-enclosed parameter expansion) + (Multiline command from M4 expansion) + (Double-M4-quoted command): New tests. + +2004-12-17 Paul Eggert + + * doc/autoconf.texi: Update GNU FDL version from 1.1 to 1.2. + +2004-12-17 Akim Demaille + + * lib/autoconf/general.m4 (AC_SUBST, AC_SUBST_FILES): Pass $1 to + m4_pattern_allow. + Suggested by Alexandre Duret-Lutz. + * doc/autoconf.texi (Setting Output Variables): Catch up. + +2004-12-17 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (_AS_TEST_PREPARE): Fix comment. + +2004-12-17 Stepan Kasal + + * lib/autoconf/general.m4 (_AC_LIBOBJ): We can use AC_SUBST/2, + remove the comment which said we cannot. + +2004-12-17 Stepan Kasal + + Add a specialized check for resolv.h. Thanks to Gerrit P. Haase, + Reini Urban and Paul Eggert for reporting the dependencies. + + * lib/autoconf/headers.m4 (AC_HEADER_RESOLV): New macro. + * doc/autoconf.texi (AC_HEADER_RESOLV): Document it. + (AC_HEADER_STAT): @cvindex{STAT_MACROS_BROKEN}, not @acindex. + +2004-12-17 Stepan Kasal + + * bin/autoscan.in: Open autoscan.log only after ``parse_args''; + so that eg. ``autoscan --help'' doesn't truncate it. + +2004-12-15 Nicolas Joly + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Remove + generated conftest files. + +2004-12-13 Noah Misch + + * lib/autotest/general.m4 (_AT_CHECK) [--trace]: Do not enable shell + tracing on commands with possibly-escaped newlines. + * doc/autoconf.texi (Writing testsuite.at): Delete documentation of the + discontinued behavior and its implications. + * tests/autotest.at (BS-newline in command, ^BS-newline in command) + (BSx641-newline in command, BS-BS-newline in command) + (BSx640-newline in command, Newline-CODE-BS-newline in command) + (Single-quote-BS-newline in command) + (Single-quote-newline-BS-newline in command): New tests. + +2004-12-13 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_EXECUTABLE_P): Use test -f && test -x + on platforms where it works. + (_AS_TEST_PREPARE): Test for ``test -x''. + (_AS_BROKEN_TEST_PREPARE): Nuke. + +2004-12-13 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Move the trap commands ... + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): ... here; + give only 4-letter prefix to AS_TMPDIR, comment fixed. + * lib/autoconf/programs.m4 (_AC_PATH_PROG_FEATURE_CHECK): Don't + create the temporary directory. + (_AC_FEATURE_CHECK_LENGTH): Work in current directory. + +2004-12-12 Kelley Cook + + * bin/autoheader.in: Exit if no AC_CONFIG_HEADERS was found. + (trivial change) + +2004-12-12 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Usual Tools) : Typo. + +2004-12-11 Noah Misch + + * lib/autotest/general.m4 (_AT_CHECK) [--trace]: Rework a shell pattern + to avoid using a negated character class. Reported by Nicolas Joly. + * tests/local.at (AT_CHECK_SHELL_SYNTAX): Check for similar constructs. + +2004-12-10 Paul Eggert + + * man/Makefile.am (autoconf.1, autoheader.1, autom4te.1, autoreconf.1, + autoscan.1, autoupdate.1, ifnames.1, config.guess.1, config.sub.1): + Don't depend on .x file explicitly, since "make" does that for us. + Suggested by Stepan Kasal. + + * bin/Makefile.am (MOSTLYCLEANFILES): Renamed from CLEANFILES. + Add *.tmp. + (autoconf, autoheader, autom4te, autoreconf, autoscan, autoupdate, + ifnames): Factor common code. And they said it couldn't be done! + +2004-12-09 Paul Eggert + + * bin/.cvsignore: Add autoconf.in. + * tests/.cvsignore: Add wrapper.in. + * lib/autotest/general.m4: Escape '$' in case pattern. + +2004-12-09 Noah Misch + + * man/Makefile.am (autoconf.1): Regenerate when `autoconf.as' changes. + + * lib/autotest/general.m4 [--trace] (AT_INIT): Do not `set -v'. + + * tests/autotest.at: New file. + * tests/suite.at: Include it. + * tests/Makefile.am: Distribute it. + + * lib/autotest/general.m4 [--trace] (_AT_CHECK): Do not enable + shell tracing on a command that could contain multiple lines. + * doc/autoconf.text: Document that fact and its implications. + * lib/m4sugar/m4sh.m4 (AS_ESCAPE_FOR_EXPAND): New macro. + * tests/autotest.at (Multiline backquote command substitution, + Multiline parameter expansion, Literal multiline command, + Multiline parenthetical command substitution): Remove XFAIL. + +2004-12-09 Paul Eggert + + * doc/autoconf.texi (Libraries): Clarify problems with AC_CHECK_LIB + and suggest AC_SEARCH_LIBS. Suggested by Noah Misch and Stepan Kasal. + +2004-12-08 Noah Misch + + * configure.ac (test suite): Cease to generate wrapper scripts. + * configure: Regenerate. + * lib/freeze.mk (MY_AUTOM4TE): Wrap the uninstalled autom4te directly. + (m4f_dependencies): Adjust accordingly. + * tests/Makefile.am (Wrappers): Generate wrapper scripts. + (wrapper.in): Generate it in the build directory. + (MAINTAINERCLEANFILES): Delete wrapper.in. + (CLEANFILES): Add wrapper.in. + * tests/wrapper.as: Move AS_INIT to very top, preserving copyright in + the output. Replace each $as_me with a @wrap_program@. + * tests/wrapper.in: Delete it; we always build it. + + * bin/Makefile.am (autoconf.in): Generate it in the build directory. + (EXTRA_DIST): Remove autoconf.in. + (CLEANFILES): Add autoconf.in. + (autoconf): Find autoconf.in in the build directory. + * bin/autoconf.in: Delete it; we always build it. + +2004-12-08 Noah Misch + + * lib/autotest/general.m4 (AT_INIT): Replace a `tr' with a `sed'. Join + PATH members so as to not prepend an empty element. Move a comment. + * Makefile.am (SUBDIRS): Build in `tests' last. + * tests/Makefile.am (installcheck-local): Add check-local dependencies. + +2004-12-08 Paul Eggert + + * lib/mdate-sh: Don't use "set - x`$ls_command /`", as zsh mishandles + the spaces inside $ls_command. Problem reported by Loulou Pouchet in + . + Don't use "set - x"; plain "set x" is enough, and simplifies debugging. + +2004-12-07 Stepan Kasal + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): Fix typo in previous + patch: extra "-l"s. + +2004-12-06 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): Check libc before + looking elsewhere for getmntent. Problem reported by Mark D. Baushke. + * doc/autoconf.texi (Particular Functions): Mention new behavior. + +2004-12-03 Stepan Kasal + + * lib/autoconf/general.m4 (AC_DEFINE, AC_DEFINE_UNQUOTED): Factor + out the common code to ... + (_AC_DEFINE_Q): ... a new macro; simplify the condition about the + value of the #define--default to 1, iff the macro was called + with exactly one parameter. + +2004-12-02 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_MEMCMP): Use + "char c = '\200';" rather than "char c = 0x80;" as the + latter doesn't conform to the strict C standard due to + overflow on signed char hosts. + + * lib/autoconf/c.m4 (_AC_PROG_CC_STDC): Prefer -qlanglvl=extc89 + to -qlanglvl=ansi. We don't want to disable extensions. + +2004-11-29 Paul Eggert + + * doc/autoconf.texi (Particular Programs): @code{$PATH} -> @env{PATH}. + (Using Autotest, testsuite Scripts, Writing testsuite.at): + Reword slightly to avoid some English-language problems noted + by Ralf Wildenhues in: + http://lists.gnu.org/archive/html/autoconf-patches/2004-11/msg00027.html + +2004-11-29 Stepan Kasal + + * NEWS: Add ^L above each release. + +2004-11-28 Paul Eggert + + Fix documentation problems reported by Russ Boylan in + , + along with some nearby cruft. + * doc/autoconf.texi (Libtool): Libtool can be used without + Automake (not without Autoconf). + (Introduction): Mention lists.gnu.org. + * BUGS: Don't mention bugs.gnu.org. + Remove mention of ancient libtool compatibility problem. + * NEWS: Mention that bugs.gnu.org is kaput. + * README: Likewise. Mention where mailing list archives can be found. + +2004-11-28 Stepan Kasal + + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): A typo in the comment. + +2004-11-26 Paul Eggert + + * doc/autoconf.texi (Pretty Help Strings): Go back to + single-quoting assignments to cache variables. + +2004-11-23 Stepan Kasal + + * doc/autoconf.texi (Pretty Help Strings): Fix quoting issues + with the examples; fix the bug in MY_ARG_WITH example reported + by Alexandre Duret-Lutz. + * lib/autoconf/general.m4 (AC_ARG_ENABLE, AC_ARG_ENABLE): Enable + expansion of $1 in the comment emitted to configure. + +2004-11-23 Paul Eggert + + * doc/autoconf.texi (Pretty Help Strings): Fix typo + in my editing of the previous patch. Problem reported + by Alexandre Duret-Lutz. + +2004-11-22 Stepan Kasal + + * doc/autoconf.texi (Autoconf Language): Explain that + ``descriptions'' may not be double quotes. + (Quotation Rule Of Thumb): Likewise. + (Pretty Help Strings): Likewise; remove the wrong comment; + simplify the examples and improve their quoting. + +2004-11-13 Stepan Kasal + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Don't check + the $1_found variable, don't test whether the file is executable; + Both things are checked ... + (_AC_PATH_PROG_FEATURE_CHECK): ... here; AS_EXECUTABLE_P replaces + the former ``test -f''. + * lib/m4sugar/m4sh.m4 (_AS_TEST_PREPARE): Fix a typo. + +2004-11-10 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Avoid cp -r; + use cp -R instead. + +2004-11-10 Derek R. Price + + * doc/autoconf.texi (Limitations of Usual Tools): Note `cp -r' + limitations. Reorder paragraphs for clarity. + +2004-10-11 Paul Eggert + + * doc/autoconf.texi: Standardize spelling of "Posix" (as opposed + to "POSIX" or "@acronym{POSIX}"), and similarly for "DOS + variants", "Unix", and some related minor wording fixups. + + (Shellology, Special Shell Variables): Document that the Zsh + problem with NULLCMD was fixed in zsh 3.1.6-dev-18. Thanks + to Alexandre Duret-Lutz for this info. + +2004-10-10 Alexandre Duret-Lutz + + * doc/autoconf.texi (One-Shot Macros): New node. + +2004-09-28 Paul Eggert + + * doc/autoconf.texi (Function Portability): Fix misdescription + of putenv. Problem reported by Michael Wardle. + +2004-09-22 Paul Eggert + + * doc/autoconf.texi (auindex): New macro. + (AU_DEFUN): Use it to fix the bug when the index contained AC_AU_DEFUN. + Problem reported by Stepan Kasal. + +2004-09-05 Paul Eggert + + Fix problems reported by Andreas Buening in: + http://lists.gnu.org/archive/html/autoconf-patches/2004-04/msg00004.html + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Set SHELL=/bin/sh + in test makefile. + * lib/autotest/general.m4 (AT_INIT): Don't assume /dev/null is + readable; it's not true in OS/2-emx. + +2004-09-04 Paul Eggert + + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): If xmkmf returns + "/usr/include", clear ac_x_includes instead of leaving it as "no" + (trivial change). Problem and patch reported by Andrew Church in: + http://lists.gnu.org/archive/html/bug-autoconf/2004-04/msg00016.html + +2004-09-03 Paul Eggert + + * doc/autoconf.texi: Give AC_DEFINE and AC_DEFINE_UNQUOTED + three args in examples. Problem reported by Frederik Fouvry in: + http://lists.gnu.org/archive/html/bug-autoconf/2004-09/msg00017.html + Also, fix some minor spacing and punctuation bugs. + +2004-09-02 Akim Demaille + + * doc/autoconf.texi (Limitations of Builtins): Swap "cd" and + "case" to restore ordering. + Reported by Stepan Kasal. + +2004-08-26 Akim Demaille + + * doc/autoconf.texi: Minor typos and stylos. + +2004-08-20 Paul Eggert + + * configure.ac (AC_INIT): Bump to 2.59c. + +2004-08-20 Paul Eggert + + Version 2.59b. + + * README: Add advice about m4 1.4.2. + + * Makefile.cfg (wget_files): Remove config.guess, config.sub, + texinfo.tex for now (done by hand now). + * Makefile.maint (wget_files, cvs_files): + Remove ansi2knr.c; nobody uses it. + (ansi2knr.c-url_prefix): Remove. + (cvs-update): Fix test for failure. I don't know why it ever + worked... + + * doc/autoconf.texi: Update URLs, some of which went stale. + Use @uref rather than @href. + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Have configure + handle "--" as per POSIX. Suggested by Paul Pogonyshev. + + * config/config.guess, config/config.sub, config/elisp-comp, + config/install-sh, config/mkinstalldirs, config/texinfo.tex, + doc/fdl.texi, doc/standards.texi: Sync with master copy. + + * NEWS, TODO, configure.ac, bin/autoscan.in, + bin/autoupdate.in, bin/ifnames.in, doc/autoconf.texi, + doc/install.texi, lib/Autom4te/Configure_ac.pm, + lib/Autom4te/FileUtils.pm, lib/autoconf/general.m4, + lib/autoconf/programs.m4, lib/autoconf/status.m4, + lib/autotest/general.m4, lib/m4sugar/m4sh.m4, + lib/m4sugar/m4sugar.m4, tests/local.at, tests/m4sh.at, + tests/tools.at, tests/torture.at: + Use "file name" rather than "filename" or "path", + to be consistent with the terminology of the GNU coding standards. + +2004-08-19 Paul Eggert + + * lib/autoconf/c.m4 (AC_LANG_BOOL_COMPILE_TRY(C), + AC_C_LONG_DOUBLE): Undo 2004-06-04 change, as it didn't work with + HP-UX 11.23 cc/aCC or Tru64 4.0 cc. Problem reported by Noah Misch in + . + + More fixes to support spaces in the name of the build directory. + This isn't a complete fix but it's an improvement. + + * bin/autoconf.as (autom4te_options): New var. + Use it instead of appending to AUTOM4TE, so that we can allow + spaces in the build directory's absolute name. + * bin/autoheader.in ($autoconf): Allow spaces in file names. + * lib/autotest/general.m4 (AT_INIT, AT_CLEANUP, _AT_CHECK, + AT_CHECK_NOESCAPE): Likewise. + * tests/wrapper.as (testdir, AUTOM4TE_CFG, autom4te_perllibdir, + main program): Likewise. + +2004-08-18 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_HELP): Quote $ac_popdir uses. + From Ralf Corsepius in: + http://lists.gnu.org/archive/html/autoconf-patches/2004-08/msg00014.html + +2004-08-12 Paul Eggert + + * doc/autoconf.texi (Function Portability): Document isinf and + and isnan. From a suggestion by Kevin Ryde. + + * lib/Autom4te/General.pm (END): Return correct exit status even + if unlink succeeds and sets $?. Needed with Solaris 8's perl 5.00503. + +2004-08-09 Paul Eggert + + * tests/torture.at (Deep Package): Use configure.in, not configure.ac, + for compatibility with Automake 1.4. Reported by J C Fitzgerald in + . + +2004-08-04 Alexandre Duret-Lutz + + * lib/autoconf/general.m4 (AC_REQUIRE_AUX_FILE): New empty macro. + (AC_CANONICAL_BUILD): Call it to require config.sub and config.guess. + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Likewise for install-sh. + * doc/autoconf.texi (Input): Document AC_REQUIRE_AUX_FILE. + * lib/autom4te.in (Automake-preselections): Preselect + AC_REQUIRE_AUX_FILE. Automake 1.10 will trace it. + +2004-08-02 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect + AC_CANONICAL_BUILD and AC_CANONICAL_TARGET. Automake 1.9.1 will + trace them. + +2004-07-29 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Set BIN_SH, for + Tru64. + * doc/autoconf.texi (Shellology): Mention BIN_SH. + Document problem with "`""`" in pdksh POSIX mode. + +2004-07-27 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Use "set -o posix" + with pdksh, too. Problem reported by Patrick Welche via + Gary V. Vaughan. + * doc/autoconf.texi (Shellology): Note that set -o posix is + useful for pkdsh, too. + +2004-06-24 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Require + _AS_UNSET_PREPARE, so that we can use $as_unset directly. + Don't fail if ENV or BASH_ENV is readonly. + (AS_SHELL_SANITIZE): Don't fail if ENV, MAIL, MAILPATH, LC_ALL, + etc. are read only. Problem reported by Ludovic Courtes. + +2004-06-23 Noah Misch + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): If the shell is + zsh, disable GLOB_SUBST to avoid backslash handling problems. + (trivial change) + +2004-06-04 Paul Eggert + + * doc/autoconf.texi (File System Conventions): Warn about + names like "aux". Problem reported by Eric Blake. + + * lib/autoconf/c.m4 (AC_LANG_BOOL_COMPILE_TRY (C)): Use division + by zero instead of array size, so that we can use any arithmetic + constant expression (instead of requiring an integer constant + expression). This allows us to test expressions like DBL_MAX < + LDBL_MAX, which didn't conform to the C standard using the old + method. + (AC_C_LONG_DOUBLE): Put back in the tests for LDBL_MAX and LDBL_EPSILON, + now that we can do floating-point tests at compile time. + +2004-06-02 Paul Eggert + + * lib/autoconf/c.m4 (AC_C_LONG_DOUBLE): Don't check LDBL_MAX + and LDBL_EPSILON, as the resulting expression isn't an + integer constant expression and violates the C standard. + Problem reported by Nelson H. F. Beebe. Also, check + for "L" suffix, and check that long double doesn't have + worse range or precision than double, that mixed-mode + arithmetic doesn't generate a diagnostic, that double + constants fit in long double. + +2004-06-03 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Add notes on free(NULL), + malloc(0) and realloc(NULL,size). + + * doc/autoconf.texi (Shell Substitutions): Spelling error reported by + Bob Proulx. + +2004-05-31 Paul Eggert + + * lib/autoconf/headers.m4 (HAVE_STDBOOL_H): Detect _Bool bug + in HP aC++/ANSI C B3910B A.05.55 [Dec 04 2003]. Problem reported + by Jim Meyering. + +2004-05-26 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Mention that ! COMMAND + can be rewritten using if-then-else. Suggested by Bruno Haible. + +2004-05-25 Paul Eggert + + * doc/autoconf.texi (testsuite Scripts): Fix typo. + Problem reported by Stepan Kasal. + +2004-05-24 Paul Eggert + + * tests/Makefile.am (autoconfdir): Fix to match comment (trivial + change). Patch reported by Ralf Wildenhues in + . + + * lib/autoconf/functions.m4 (AC_FUNC_MBRTOWC): Don't assume that a + function F exists if the compiler and linker let you compile an + expression like (F != 0). Recent versions of GCC optimize away + the reference to F in that case, since every function address must + be nonzero, so the link succeeds even if F does not exist. + Problem reported by Manu in + . + + * doc/autoconf.texi (Systemology): Standardize on the spelling of + "Unix". Many uses changed. + (Limitations of Builtins): Explain better why the ! command isn't + portable. + +2004-05-22 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect + LT_SUPPORTED_TAG in lieu of AC_LIBTOOL_TAGS. + +2004-05-19 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Add strerror_r, cross + referencing AC_FUNC_STRERROR_R. + + * doc/autoconf.texi (Particular Functions): In AC_FUNC_CLOSEDIR_VOID, + note pessimistic assumption when cross compiling. + +2004-05-16 Paul Eggert + + * doc/autoconf.texi (Limitations of Make): Note that BSD make + (until 2004) invoked subcommands with sh -e, contra POSIX. + Reported by Kevin Ryde. + +2004-05-10 Eric Sunshine + + * programs.m4 (_AC_PROG_GREP): Fixed bug where PATH argument handed to + _AC_PATH_PROG_FEATURE_CHECK contained leading whitespace (i.e. + " $PATH:/usr/xpg4/bin"). This resulted in bogus tests, such as + `test -f " /usr/bin/grep"', which _always_ failed. + (AC_PROG_SED): Ditto bogus PATH fix. + * autoconf.texi (AC_PROG_GREP): Properly document that this macro + requires that grep correctly supports _multiple_ `-e' options, rather + than stating only that grep should accept `-e'. + +2004-05-03 Paul Eggert + + Port to C99, which requires that 'exit' be declared. + + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Use AC_INCLUDES_DEFAULT + to ensure that stdlib.h is included. + * lib/autoconf/functions.m4 (_AC_LIBOBJ_ALLOCA, AC_FUNC_SETPGRP, + AC_FUNC_STRTOD, AC_FUNC_SETVBUF_REVERSED, AC_FUNC_FORK, _AC_FUNC_FORK, + _AC_FUNC_VFORK, AC_FUNC_WAIT3): Likewise. + * lib/autoconf/specific.m4 (AC_SYS_RESTARTABLE_SYSCALLS): Likewise. + * lib/autoconf/types.m4 (AC_TYPE_GETGROUPS): Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_STDC): Include + when using 'exit' in a test; C99 requires that 'exit' be declared. + +2004-05-02 Paul Eggert + + * doc/autoconf.texi (Particular Programs): AC_PROG_GREP + now prefers 'grep' implementations that accept -e. + (Limitations of Usual Tools): Describe problems of traditional + egrep and fgrep with long input lines, and of traditional grep + with -e. + * lib/autoconf/programs.m4 (AC_PROG_GREP): Check for -e, too. + (_AC_PROG_GREP): Assume 3rd arg is properly quoted for the shell. + All callers changed. Append /usr/xpg4/bin to the PATH, for + Solaris. + (_AC_FEATURE_CHECK_LENGTH): Discard stderr, so we don't bother + the user with complaints about multiple -e options. + * tests/local.at (AC_STATE_SAVE): Use $GREP, not grep. + Define it with AC_PROG_GREP. + * configure.ac (AC_PROG_GREP): Add. + * lib/freeze.mk (GREP): New macro. + +2004-05-02 Eric Sunshine + + * lib/m4sugar/m4sh.m4 (_AS_DETECT_BETTER_SHELL): Consult $SHELL as + a possible candidate only after all others fail, rather than + consulting it first. This improves backward compatibility by + better reflecting the way shell selection occurred in previous + versions of Autoconf, and should help to avoid triggering latent + problems in other packages, such as the one in Automake where zsh + is not handled robustly: + http://mail.gnu.org/archive/html/automake/2004-04/msg00095.html + Although it is not Autoconf's responsibility to work around + problems in Automake, it nevertheless makes sense to avoid + introducing unnecessary incompatibilites. + +2004-04-22 Albert Chin-A-Young , + Gary V. Vaughan + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Don't guess + how deeply nested we are when a suitable tool is found, set the + ac_path_TOOL_found flag. + (_AC_PATH_PROG_FEATURE_CHECK): Encapsulate knowledge of how deeply + nested we are in this macro. Break out of all 3 nested loops if + ac_path_TOOL_found is set. + +2004-04-21 Gary V. Vaughan + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Break out + of the _AS_PATH_WALK loop too if GNU flavor is found. + +2004-04-21 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Update documentation + for `$<'. New entry `Long lines', based on a report from Simon + Josefsson. Augment the documentation for SHELL = @SHELL@ with a + paragraph about DJGPP, based on a mail from Richard Dawe. + +2004-04-20 Paul Eggert + + * tests/c.at (C keywords): Don't assume that GCC supports + "restrict" and "inline", as sufficiently-old GCC versions do not + (also, GCC configured to be in pedantic C89 mode does not). + Problem reported by Sumit Pandya in: + http://mail.gnu.org/archive/html/autoconf/2004-04/msg00092.html + + * lib/autoconf/c.m4 (_AC_PROG_CC_G, _AC_PROG_CXX_G): Don't + consider -g to work if it generates warnings when plain compiles + don't. Problem reported by Braden McDaniel in: + http://mail.gnu.org/archive/html/autoconf-patches/2003-07/msg00014.html + + * doc/autoconf.texi (Slashes): New section, to document a problem + reported by Jim Meyering in: + http://mail.gnu.org/archive/html/bug-coreutils/2004-02/msg00060.html + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Remove potential + linker output files before linking, to work around IRIX 6 linker bug. + Problem reported by Rainer Orth in: + http://mail.gnu.org/archive/html/autoconf-patches/2004-02/msg00007.html + +2004-04-20 Gary V. Vaughan + + * lib/autoconf/programs.m4 (_AC_FEATURE_CHECK_LENGTH): Make the + best tool so far counter rely on the tool path variable name to + avoid checks for one tool being affected by the results of running + the length check on a previous tool. + + * lib/autoconf/programs.m4 (_AC_PROG_GREP): Take an additional + match expression argument, as different greps have different + regular expression flavours. + (AC_PROG_FGREP): Pass 'FGREP'. fgrep treats all match chars as + literals. + (AC_PROG_EGREP): Pass 'EGREP$'. + (AC_PROG_GREP): Pass 'GREP$'. + +2004-04-20 Albert Chin-A-Young + + * lib/autoconf/programs.m4 (AC_PROG_GREP): Cache variable + is `ac_cv_path_GREP', not `oc_cv_path_GREP'. + +2004-03-29 Paul Eggert + + * doc/autoconf.texi (Particular Headers, Particular Types, Generic + Types, Specific Compiler Characteristics, System Services, + Obsolete Macros): Use 'long int', 'short int', 'unsigned int' + etc. consistently instead of 'long', 'short', 'unsigned' etc. + * lib/autoconf/c.m4 (AC_LANG_INT_SAVE(C), AC_C_BIGENDIAN): Likewise. + * lib/autoconf/functions.m4 (AC_FUNC_MMAP, AC_FUNC_SELECT_ARGTYPES): + Likewise. + * lib/autoconf/headers.m4 (AC_HEADER_SYS_WAIT): Likewise. + * lib/autoconf/types.m4 (AC_TYPE_GETGROUPS, AC_TYPE_SIZE_T, + AC_TYPE_OFF_T): Likewise. + * tests/semantics.at (AC_CHECK_TYPES: backward compatibility): + Likewise. + + * tests/foreign.at (Libtool): Create an empty aclocal.m4, to + pacify libtool 1.5.2. Fix quoting problems in sed command. + +2004-03-28 Paul Eggert + + * doc/autoconf.texi (Particular Structures): AC_STRUCT_TIMEZONE + now defines HAVE_DECL_TZNAME if it is declared, when + HAVE_STRUCT_TM_TM_ZONE is not defined. + * lib/autoconf/types.m4 (AC_STRUCT_TIMEZONE): Implement this. + Do not assume atoi. Rely on HAVE_DECL_TZNAME when testing + for HAVE_TZNAME. + +2004-03-28 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Corrected + superfluous backslashing of quotes (") in sed expressions; + thanks to Paul Eggert. + +2004-03-26 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC): new name of Intel + Fortran compiler is ifort, also added pghpf; thanks to Nelson + H. F. Beebe for the bug report. + +2004-03-26 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): fix for + quoted -cmdline argument in Portland Group compiler (bug + reported by Jeffrey J. Barteet). + +2004-03-25 Kevin Ryde + + * doc/autoconf.texi (Specifying Names): Move cross_compiling ovindex to + (Run Time): ... here, where it's now mentioned. + +2004-03-19 Alexandre Duret-Lutz + + * doc/autoconf.texi (autom4te Invocation): Language Autoconf + inherits from language Autoconf-without-aclocal-m4. + (Customizing autom4te): Adjust example; the cache must now be + disabled for language Autoconf-without-aclocal-m4. + +2004-03-16 Paolo Bonzini + Nathanael Nerode + + * lib/autoconf/programs.m4 (AC_PATH_TOOL, AC_CHECK_TOOL, + AC_CHECK_TOOLS): Warn if a cross-tool is found without + a prefix. + (AC_PATH_TARGET_TOOL, AC_CHECK_TARGET_TOOL, + AC_CHECK_TARGET_TOOLS): New macros. + * doc/autoconf.texi (Generic Programs): Document + (AC_PATH_TARGET_TOOL, AC_CHECK_TARGET_TOOL, + AC_CHECK_TARGET_TOOLS, and warn for future changes + in the behavior of AC_PATH_TOOL, AC_CHECK_TOOL and + AC_CHECK_TOOLS. + (Specifying Names): Document the reason for these future + behavioral changes. + * tests/mktests.sh: Do not generate tests for the + new macros. + * NEWS: Document these changes. + + * doc/autoconf.texi: Avoid macros with unbraced arguments, + they make TeX hang up. + +2004-03-15 Paul Eggert + + * NEWS: New macro AC_CHECK_ALIGNOF. + * doc/autoconf.texi (Generic Compiler Characteristics): Document it. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): Use long int rather than + int; avoid "a `$1'" since this isn't grammatical if $1 begins with a + vowel. + (AC_CHECK_ALIGNOF): New macro. + * tests/mktests.sh (ac_exclude_list): Exclude AC_CHECK_ALIGNOF. + * tests/semantics.at (AC_CHECK_ALIGNOF): Add tests similar to + those for sizeof. + +2004-03-03 Paul Eggert + + * bin/Makefile.am (edit): Don't use $< in a context where + POSIX doesn't require support for it. Use $@.in instead. + Problem reported by Anthony N. Frasso in + . + * bin/autoscan.in, bin/autoupdate.in: Add @configure_input@ comment. + +2004-02-23 Gary V. Vaughan + + * bin/autoreconf.in (autoreconf_current_directory): Recognize LT_INIT + from the next generation of Libtool. + * lib/autom4te.in (Autoreconf-preselections): Ditto. + +2004-02-20 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Usual Tools) : `mkdir -p' + is not always thread-safe. Report from Nathanael Nerode. + +2004-02-18 Paul Eggert + + Fix a dependencies problem, stemming from a Autoconf 2.59 build + problem on QNX reported by Stephen Rasku in + . + + * bin/Makefile.am ($(srcdir)/autoconf.in): Depend on + $(m4sh_m4f_dependencies); this removes a FIXME. + * tests/Makefile.am ($(srcdir)/wrapper.in): Likewise. + (MAINTAINERCLEANFILES): Split into pieces, + one per related section. Add $(srcdir)/wrapper.in. + +2004-02-09 Paul Eggert + + * doc/autoconf.texi (Setting Output Variables): Emphasize that + AC_SUBST provides no portable way to escape literal newlines. + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Ignore all + flags of the form -lcrt*.o, not just -lcrt[01].o and -lcrtbegin.o. + Darwin uses -lcrt2.o and there's little point to cataloging all + the system variants. Partial fix reported by Andreas Waechter in: + http://mail.gnu.org/archive/html/autoconf-patches/2004-02/msg00006.html + for bug reported by Nelson H. F. Beebe in: + http://mail.gnu.org/archive/html/bug-autoconf/2003-12/msg00090.html + +2004-02-04 Paolo Bonzini + + * doc/autoconf.texi (AU_DEFUN): Fix English, + suggested by Paul Eggert. + * lib/autoconf/autoupdate.m4: Correct reference to + acobsolete.m4, suggested by Alexandre Duret-Lutz. + +2004-02-02 Paolo Bonzini + + * bin/autoupdate.in: Define __file__ so that warnings + refer to the correct file. + * doc/autoconf.texi (AU_DEFUN): Describe more correctly + the behavior of the third argument. + * lib/autoconf/autoupdate.m4 (AU_DEFUN): Describe more + correctly the behavior of the third argument. Document + what the three macros that AU_DEFUN defines do. Fix + warning message when the third argument includes $0 + (reported by Alexandre Duret-Lutz). + +2004-01-30 Paolo Bonzini + Eric Sunshine + Paul Eggert + + * lib/m4sugar/m4sh.m4 (M4SH-SANITIZE): New diversion. + (AS_INIT): Output shell initialization there. Removed optional + parameter. Expand _AS_SHELL_FN_SPY. + (AS_INIT_WITH_SHELL_FN): Removed. + (_AS_SHELL_FN_SPY): New macro. + (AS_DETECT_REQUIRED, AS_DETECT_SUGGESTED): New + macros. + (AS_SHELL_SANITIZE): Remove loop to find better shell + and documentation for the parameter. + (_AS_DETECT_BETTER_SHELL): Move it here. + (_AS_SHELL_FN_WORK): Remove shell invocation, reformat. + (_AS_RUN): Move it here, support testing with eval. + (AS_REQUIRE_SHELL_FN): Require shell functions when + it is used. + (_AS_LINENO_WORKS): Put around braces, we do not + trigger the bash bug anymore. + * lib/autotest/general.m4: Document M4SH-SANITIZE, do not + use AS_INIT_WITH_SHELL_FN. + * bin/autoconf.in, tests/wrapper.in: Regenerated. + +2004-01-30 Paolo Bonzini + + * bin/autoupdate.in: Trace AU_DEFINE instead of AU_DEFUN. + * doc/autoconf.texi: Don't say that the third parameter + is broken. + * lib/autoconf/autoupdate.m4 (AU_DEFINE): New dummy macro. + (AU_DEFUN): Honor the third parameter, create autoupdate + macros with AU_DEFINE. + * lib/autoconf/headers.m4 (AC_USG, AC_MEMORY_H, + AC_DIR_HEADER): Use AU_DEFUN's third parameter. + * lib/autoconf/lang.m4 (AC_LANG_SAVE): Likewise. + * lib/autoconf/programs.m4 (AC_RSH): Likewise. + * lib/autoconf/specific.m4 (AC_HAVE_POUNDBANG, + AC_ARG_ARRAY, AC_CYGWIN, AC_EMXOS2, AC_MINGW32, + AC_XENIX_DIR): Likewise. + * lib/autoconf/types.m4 (AC_INT_16_BITS, AC_LONG_64_BITS, + AC_STRUCT_ST_BLKSIZE, AC_STRUCT_ST_RDEV): Likewise. + * lib/autoconf/status.m4: Remove FIXME. + * tests/local.at (AT_CHECK_AU_MACRO): Ignore stderr, check + that the macro is not present anymore in the updated + configure.ac. + * tests/tools.at (autoupdate AC_LINK_FILES): Ignore stderr + of autoupdate. + +2004-01-28 Paul Eggert + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Add 2004 to + copyright years. + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Add 1992 thorugh + 2003 (except 1997) to the list of copyright years. This undoes + the 2003-05-22 change, which removed the older years from the list. + * lib/autoconf/status.m4 (AC_OUTPUT): Update copyright date to 2004. + +2004-01-27 Gary V. Vaughan + Albert Chin-A-Young + + * lib/autoconf/programs.m4 (AC_PROG_GREP): New macro to test for a + grep or ggrep program in PATH that accepts as long lines as + possible. + * lib/autoconf/programs.m4 (_AC_PROG_GREP): Factor out the core of + AC_PROG_GREP. + (AC_PROG_EGREP, AC_PROG_FGREP): Use it to find best available + egrep and fgrep respectively if $GREP -E/-F don't work. + (_AC_PATH_PROG_FEATURE_CHECK): Factor out the common core of + _AC_PROG_GREP, and AC_PROG_SED. + (_AC_FEATURE_CHECK_LENGTH): New helper macro for finding the + longest input length accepted by a command. + (AC_PROG_SED): Use it. + * doc/autoconf.texi (Particular Programs): Document the changes. + * NEWS: Updated. + +2004-01-27 Paul Eggert + + * bin/autoconf.as ($version): Update copyright from 2003 to 2004. + * bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in, + bin/autoscan.in, bin/autoupdate.in, bin/ifnames.in: Likewise. + * lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Likewise. + + * Makefile.in, aclocal.m4, configure, bin/Makefile.in, + bin/autoconf.in, config/Makefile.in, config/config.guess, + config/config.sub, config/install-sh, config/mdate-sh, + config/mkinstalldirs, config/texinfo.tex, doc/Makefile.in, + lib/Makefile.in, lib/Autom4te/Makefile.in, + lib/autoconf/Makefile.in, lib/autoscan/Makefile.in, + lib/autotest/Makefile.in, lib/emacs/Makefile.in, + lib/m4sugar/Makefile.in, man/Makefile.in, man/autoconf.1, + man/autoheader.1, man/autom4te.1, man/autoreconf.1, + man/autoscan.1, man/autoupdate.1, man/config.guess.1, + man/config.sub.1, man/ifnames.1, tests/Makefile.in, + tests/acc.at, tests/acfortran.at, tests/acfunctions.at, + tests/acgeneral.at, tests/acheaders.at, tests/aclang.at, + tests/aclibs.at, tests/acspecific.at, tests/acstatus.at, + tests/actypes.at: Regenerate and/or sync with original + sources. + +2004-01-26 Paul Eggert + + * doc/autoconf.texi (Default Includes): Include even if + HAVE_INTTYPES_H is defined. This is needed on Tru64 5.1b with + Compac C V6.5-207 (dtk), which defines uintmax_t in but + not . Problem reported by Tim Mooney in + . + * lib/autoconf/headers.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): + Likewise. + + * lib/autoconf/programs.m4 (AC_PROG_SED): Use diff, not sed; + otherwise "make check" fails because it forbids cmp (I guess + because cmp treats files as binary on DOS-like systems). + + * tests/mktests.sh: Update copyright date to 2004, since some tests + have changed in 2004. + +2004-01-23 Gary V. Vaughan + + * lib/autoconf/programs.m4 (AC_PROG_SED): New macro to test for a + non-truncating sed or gsed program in PATH. + * tests/acprograms.at: Add it. + * doc/autoconf.texi (Particular Programs): Document it. + * NEWS: Updated. + +2004-01-15 Paul Eggert + + * lib/autoconf/c.m4 (_AC_PROG_CC_STDC): Try -std, not -std1, since + -std1 disables some useful extensions on Tru64. Problem reported + by N. Lichtmaier in + . + +2004-01-14 Paul Eggert + + * doc/autoconf.texi (Programming in M4sh): Document that + AS_MKDIR_P succeeds if the destination is a symbolic link + to an existing directory. + (Limitations of Usual Tools): Note that mkdir -p might not + succeed on symlinks to directories. + +2004-01-13 Paul Hilfinger + + * lib/autoconf/autoupdate.m4 (AU_DEFUN): Grammar fix in comment. + * bin/autoheader.in: Grammar fix in message. + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): + Test for dir before calling mkdir -p. (trivial changes) + +2004-01-13 Eric Blake + + * doc/autoconf.texi (Obsolete Macros): In AC_TRY_COMPILE and + AC_TRY_LINK, s/AC_LANG_SOURCE/AC_LANG_PROGRAM/. (trivial change) + +2004-01-10 Jim Meyering + + * doc/autoconf.texi (Running the Preprocessor): Correct grammar. + +2004-01-09 Paul Eggert + + * lib/autoconf/general.m4: Fix bug: AC_CHECK_SIZEOF evokes a warning + with `autoconf -Wall,error'. Bug reported by Eric Blake in: + http://mail.gnu.org/archive/html/autoconf-patches/2004-01/msg00000.html + (_AC_COMPUTE_INT_COMPILE): Invoke _AC_COMPILE_IFELSE, not + AC_COMPILE_IFELSE, since we now assume our caller invokes + AC_LANG_COMPILER_REQUIRE, for symmetry with _AC_COMPUTE_INT_RUN. + (_AC_COMPUTE_INT_RUN): Likewise, for _AC_RUN_IFELSE instead + of AC_RUN_IFELSE; this avoids the warning mentioned above. + (_AC_COMPUTE_INT): Invoke AC_LANG_COMPILER_REQUIRE. + +2004-01-07 Paul Eggert + + * lib/autoconf/general.m4 (_AC_LIBOBJS_NORMALIZE): Avoid \$ inside + `"'...'"`, as it's confusing (and I suspect it may not work on + some platforms). The code was incorrect anyway, as it assumed + that \$ evaluated to itself in that context. Reported by + Alexandre Duret-Lutz. + +2004-01-07 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect AC_LIBTOOL_TAGS + and _LT_AC_TAGCONFIG. + +2004-01-06 Paul Eggert + + * doc/autoconf.texi (One Macro Call): Fix an incorrect + example, and add more examples. Reported by Eric Sunshine. + +2004-01-05 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): + Remove warning against "rm -fr" introduced yesterday; it + was a false alarm. + + * bin/Makefile.am (autoconf, autoheader, autom4te, autoreconf, + autoscan, autoupdate, ifnames): Don't use chmod -w. + * lib/Makefile.am (autom4te.cfg): Likewise. + * doc/autoconf.texi (Limitations of Usual Tools): Warn against + "chmod -w". + +2004-01-04 Paul Eggert + Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Speed up sed scripts + by doing lineno substitution only on lines containing "$LINENO". + +2004-01-04 Paul Eggert + + * lib/autoconf/general.m4 (AC_ARG_PROGRAM): + Use "rm -f" to remove conftest.sed, not plain "rm". + Bug reported by David Relson in + . + + * Makefile.am (autom4te-update): + Replace "rm -rf" and "rm -fr" with "rm -f -r", as POSIX requires. + * Makefile.maint (my-distcheck, do-po-update): Likewise. + * doc/autoconf.texi (Guidelines): Likewise. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Likewise. + * lib/autoconf/libs.m4 (_AC_PATH_X_XMKMF): Likewise. + * lib/autoconf/specific.m4 (AC_SYS_LONG_FILE_NAMES): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): Likewise. + * tests/Makefile.am (clean-local): Likewise. + * tests/tortue.at (AC_CONFIG_FILES, HEADERS, LINKS and COMMANDS, + srcdir): Likewise. + * doc/autoconf.texi (Limitations of Usual Tools): + Warn against "rm -fr". + +2004-01-03 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools): Mention that cc + -c -o might not work. From a suggestion by Kevin Ryde. + (C Compiler, Generating Sources, Limitations + of Usual Tools, Limitations of Make, Making testsuite Scripts): + Don't put '-o' after non-options, as POSIX doesn't allow this. + Mention that cc's name might be gcc or c89 or whatever. + +2004-01-04 Kevin Ryde + + * doc/autoconf.texi: Add various further index entries. + +2003-12-29 Paul Eggert + + * bin/autoreconf.in (autoreconf_current_directory): + Fix typo: mkdir without umask arg. + +2003-12-27 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make) : + Documents OSF1/Tru64 make behavior. Replace `VPATH = ../src' by + `VPATH = ../pkg/src' in examples to make the OSF1/Tru64 make + explanation clearer. + +2003-12-24 Andreas Schwab + + * doc/autoconf.texi (Default Includes): Fix misspelling of + AC_INCLUDES_DEFAULT. + +2003-12-03 Paolo Bonzini + + * configure.ac: Test if sh -n works. + * configure: Regenerate. + * tests/atlocal.in: Store the result here. + * tests/local.at (AT_CHECK_SHELL_SYNTAX): Extracted from + tools.at, looking in atlocal's ac_cv_sh_n_works instead + of explicitly testing. + (AT_CHECK_PERL_SYNTAX): Moved from tools.at. + (AT_CHECK_AUTOCONF): Test for the configure script syntax. + * tests/tools.at (Syntax of the shell scripts): Simplify + using AT_CHECK_SHELL_SYNTAX. + (Syntax of the Perl scripts): Remove definition of + AT_CHECK_PERL_SYNTAX. + +2003-12-03 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_SHELL_FN_WORK): Redirect + stderr to /dev/null. + * bin/autoconf.in: Regenerate. + * bin/wrapper.in: Regenerate. + +2003-11-26 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): + Extracted from AS_SHELL_SANITIZE. + (_AS_SHELL_FN_WORK, AS_INIT_WITH_SHELL_FN): New + macros. + (AS_SHELL_SANITIZE): Move reinvocation code from + _AS_LINENO_WORKS, use it to find out if shell + functions work. + (_AS_LINENO_WORKS): Don't find another shell if $LINENO + does not work. + (AS_INIT): Pass parameter down to AS_SHELL_SANITIZE. + (AS_REQUIRE_SHELL_FN): Test that AS_INIT_WITH_SHELL_FN + was called. + * lib/autotest/general.m4: Use AS_INIT_WITH_SHELL_FN. + * bin/autoconf.in: Regenerate. + * tests/wrapper.in: Regenerate. + * tests/tools.at: Test the syntax of tests/autoconf + and tests/testsuite. + +2003-11-24 Akim Demaille + + * config/announce-gen (&print_locations, &print_signatures) + (&sizes): New. + Use them. + No longer rely on Gnus to inline the list of signatures: compute + them on the fly. + +2003-11-24 Akim Demaille + + * doc/autoconf.texi (Particular Programs): AC_PROG_LEX can + override some files. + (Input): AC_CONFIG_AUX_DIR(aux) is a bad idea on DOS. + From Debian Autoconf 2.58. + +2003-11-24 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): Quote $ac_popdir + uses. + From Debian Autoconf 2.58. + +2003-11-24 Paolo Bonzini + + * TODO: Remove already done things. Update the part about finding + tools for the target. + +2003-11-24 Paolo Bonzini + + * lib/autoconf/headers.m4 (AC_USG, AC_MEMORY_H, AC_DIR_HEADER): + Make wording more consistent. + * lib/autoconf/specific.m4 (AC_CYGWIN, AC_EMXOS2, AC_MINGW32): + Explain the transition better. + * lib/autoconf/types.m4 (AC_INT_16_BITS, AC_LONG_64_BITS): Explain + the transition better. + +2003-11-24 Paolo Bonzini + + * doc/autoconf.texi (Obsoleting Macros): Don't document the third + parameter of AU_DEFUN. + * lib/autoconf/autoupdate.m4 (AU_DEFINE): Remove. + (AU_DEFUN): Remove the third parameter, it was not used. + Use AC_DEFUN directly, not AU_DEFINE. + * lib/autoconf/status.m4 (AC_LINK_FILES): Move the message into + the expanded body, consistently with other macros such as AC_USG. + +2003-11-17 Paul Eggert + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Put at least 14 bytes + into the initial confdefs.h, to work around a bug in NextStep 3.3 + patch 3 reported by Eric Sunshine. + +2003-11-15 Kevin Ryde + + * doc/autoconf.texi (Using System Type): Revise, showing $host rather + than $target since the latter is not usual, add guidelines on when to + use or not use the system type. + +2003-11-12 Derek Price + + * doc/autoconf.texi (Limitations of Usual Tools): Fix what looks like a + typo misrepaired by an auto-spellcheck. + +2003-11-12 Akim Demaille + + * bin/autoreconf.in (&parse_args): Don't call automake with + --force-missing unless it actually supports it. + From Debian #219336. + +2003-11-12 Akim Demaille + + * configure.ac: Bump to 2.59a. + Require 2.59. + +2003-11-06 Akim Demaille + + Version 2.59. + +2003-11-05 Alexandre Duret-Lutz + + * lib/autoconf/status.m4 (_AC_SRCPATHS): Fix use of AS_SET_CATFILE + so that ac_abs_builddir, ac_abs_top_builddir, ac_abs_srcdir, + and ac_abs_top_srcdir are absolute paths. + * lib/m4sugar/m4sh.m4 (AS_SET_CATFILE): Remove misleading comment. + +2003-11-05 Akim Demaille + + * configure.ac: Bump to 2.58a. + +2003-11-05 Kevin Ryde + + * doc/autoconf.texi (Using Autotest): Avoid @strong{Note: ...}, since + it provokes a warning from makeinfo about looking like a cross + reference in info output. + + * doc/autoconf.texi (Function Portability): Add notes on signal + handler return type, as per AC_TYPE_SIGNAL. + +2003-11-04 Akim Demaille + + Version 2.58. + * doc/standards.texi: Update from master. + + * tests/mktests.sh (ac_exclude_list): Add AC_FC_FREEFORM. + +2003-11-04 Akim Demaille + + AC_CONFIG_FILE([d1/foo:d2/foo]) triggers error messages when + computing the absolute path to d1 in the source hierarchy: it may + not exist at all. So don't cd into it. + From Alexandre Duret-Lutz. + http://mail.gnu.org/archive/html/bug-autoconf/2003-10/msg00205.html + + * lib/m4sugar/m4sh.m4 (AS_SET_CATFILE): New. + From Paul Eggert, but named after Perl's IO::Spec->catfile. + * doc/autoconf.texi (Programming in M4sh): Document. + * lib/autoconf/status.m4 (_AC_SRCPATHS): Use it. + +2003-11-03 Pavel Roskin + + * doc/autoconf.texi (Generic Structure Checks): Describe + action-if-found and action-if-not-found in AC_CHECK_MEMBERS. + +2003-10-31 Akim Demaille + + * tests/fortran.at (GNU Fortran 77): Don't run FC macros. + (GNU Fortran): New. + * doc/autoconf.texi (Language Choice): Document. + * lib/autoconf/fortran.m4 (AC_FC_SRCEXT, AC_FC_FREEFORM): Assert + the current language is Fortran. + +2003-10-31 Akim Demaille + + * bin/autom4te.in (&freeze): Use a less likely warning separator + than `\n\n', so that `\n\n\n' is valid in warnings. + Reported by Steve Huston. + +2003-10-28 Akim Demaille + + * Makefile.cfg (local_updates, executable-update): Tweak to be + robust to parallel makes. + Suggested by Alexandre Duret-Lutz. + +2003-10-27 Akim Demaille + + * Makefile.cfg (executable-update): New. + (local_updates): Call it. + +2003-10-27 Akim Demaille + + * lib/autoconf/general.m4 (_AC_RUN_IFELSE, _AC_INIT_PREPARE): + Don't remove core.* as it may remove valid user files. + * lib/autoconf/functions.m4 (AC_FUNC_SETVBUF_REVERSED) + (AC_FUNC_UTIME_NULL): Likewise. + +2003-10-23 Akim Demaille + + Version 2.57g. + * config/config.guess, config/config.sub: Upgrade from masters. + +2003-10-23 Akim Demaille + + * lib/autoconf/fortran.m4 (AC_FC_SRCEXT): Functions using + AC_COMPILE_IFELSE that use break skip the clean up. So do it by + hand... + +2003-10-23 Akim Demaille + + * lib/autoconf/general.m4 (_AC_LINK_IFELSE, _AC_COMPILE_IFELSE): + Don't forget to remove conftest.err. + +2003-10-23 Akim Demaille + + * lib/autoconf/general.m4 (_AC_LIBOBJ): Don't insert twice the + same object file in $LIBOBJS. + Reported by Alexandre Duret-Lutz & Derek Robert Price. + * doc/autoconf.texi (Generic Functions): Adjust. + +2003-10-20 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_TR_SH_PREPARE, _AS_TR_CPP_PREPARE): + Use 'eval', so that the resulting configure scripts work even if + the current directory has a weird file name like 'y%s+%pp%;s%@%_%g'. + +2003-10-20 Daniel Jacobowitz + + * lib/autoconf/lang.m4 (AC_LANG_WERROR): New macro. + * lib/autoconf/general.m4 (_AC_COMPILE_IFELSE, _AC_PREPROC_IFELSE) + (_AC_LINK_IFELSE): Check the werror flag. + * doc/autoconf.texi (Generic Compiler Characteristics): Document + AC_LANG_WERROR. + * NEWS: Mention it. + +2003-10-20 Daniel Jacobowitz + + * lib/autoconf/lang.m4 (AC_NO_EXECUTABLES): Override + _AC_COMPILER_EXEEXT to attempt a link. If linking fails, + override AC_LINK_IFELSE. + +2003-10-15 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_UNSET_PREPARE): Work around a bug in + pdksh 5.2.14. Bug reported by Ralf Corsepius. + * doc/autoconf.texi (Shellology): Mention the Korn shell and pdksh. + Mention /usr/dt/bin/dtksh on Solaris. + (Shell Substitutions): Warn about $((...)). + (Parentheses): New section. + +2003-10-15 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Add @prindex for exit. + Add putenv and unsetenv. Add sysconf _SC_PAGE_SIZE. + +2003-10-13 Nathanael Nerode + + * lib/autoconf/functions.m4 (AC_FUNC_FORK): Trivial fix for vfork + cross test. + +2003-10-11 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Use the new official + name for the GNU Fortran 95+ compiler, 'gfortran', not 'g95'. + +2003-10-10 Andreas Schwab + + * bin/autoheader.in: Avoid empty first line in --version and + --help output. + * bin/ifnames.in: Likewise. + +2003-10-09 Paul Eggert + + * lib/Autom4te/XFile.pm: Don't assume -j is solo. + Issue a more-informative diagnostic. + Problems reported by Eric Sunshine. + +2003-10-08 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_V_OUTPUT): Omit quoted + -mGLOB_options_string stuff for Intel ifc, which can cause + _AC_FC_LIBRARY_LDFLAGS to fail. Use (faster) case for + pattern-matching instead of grep. + +2003-10-08 Steven G. Johnson + + * doc/autoconf.texi: Document new FC Fortran macros. + +2003-10-08 Gary V. Vaughan + + * lib/autoconf/general.m4 (AC_CONFIG_MACRO_DIR): Stub out a macro + that future autopoint/aclocal/automake/autoreconf will be able + to trace to find where to install local m4 macros. + * doc/autoconf.texi (Input): Document it. + * NEWS: Updated. + +2003-10-06 Gary V. Vaughan + + * lib/autoconf/fortran.m4 (_AC_FC_LIBRARY_LDFLAGS): Add + -lcrtbegin.o to list of ignored flags and fix underquoting of + -lcrt[01].o. + +2003-10-04 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_FC_G): Use language-specific + cache variable instead of $G77 to decide whether to include -O2, + since $G77 is specific to Fortran 77. + +2003-10-03 Steven G. Johnson + + * lib/autoconf/fortran.m4 (AC_FC_FREEFORM): Support Absoft "-f + free" flag. Re-order flags tested into rough order of popularity. + +2003-10-03 Steven G. Johnson + + * lib/autoconf/fortran.m4 (AC_PROG_FC): Reverse the order of the + arguments so that it can be used with syntax identical to + AC_PROG_F77, and so that we can more easily decide to + remove/deprecate the DIALECT optional argument in the future if it + proves troublesome. + (AC_FC_FREEFORM): Exit 77 upon failure to fix test suite for + non-freeform-supporting compilers. Document freeform flags. + +2003-10-03 Akim Demaille + + * configure.ac: Look for emacs, not macs. + Reported by Eric Sunshine. + +2003-10-03 Akim Demaille + + * lib/autom4te.in (Autoreconf-preselections): Trace AC_CONFIG_AUX_DIR. + * bin/autoreconf.in (autoreconf_current_directory): Create the + AUX_DIR if needed, for sake of automake --add-missing etc. + Suggested by Alexandre Duret-Lutz. + +2003-10-03 Akim Demaille + + * configure.ac: Quotation and formatting changes. + (EMACS): Don't set it if it is not recent enough to support + autoconf-mode.el. + From Eric Sunshine. + +2003-10-02 Akim Demaille + + * bin/ifnames.in (&scan_file): Skip C++ comments. + From Jeremy Yallop. + +2003-10-01 Pavel Roskin + + * doc/autoconf.texi (Particular Structure Checks): + Fix misspelling of HAVE_STRUCT_STAT_ST_BLOCKS. + +2003-10-01 Akim Demaille + + Version 2.57f. + +2003-09-30 Paul Eggert + + * lib/Autom4te/XFile.pm: Use Errno. + (lock): Ignore ENOLCK errors. Problem reported Andreas Schwab in + . + +2003-09-30 Akim Demaille + + * config/announce-gen (&print_news_deltas): Extracted from... + (&print_changelog_deltas): here. + (&news_file): Rename as... + (@news_file): this. + +2003-09-30 Nicolas Joly + + * lib/autoconf/fortran.m4 (_AC_PROG_FC): Remove files which might + have been created when invoking the compiler. + * tests/fortran.at (GNU Fortran 77): Quote $G77. + +2003-09-29 Akim Demaille + + Version 2.57e. + + * config/mkinstalldirs: Upgrade. + +2003-09-28 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Set DUALCASE=1, for MKS sh. + Problem reported by Lars J. Aas in + . + (_AS_MKDIR_P_PREPARE): Change "rm -fr ./-p" to the more-conservative + "test -d ./-p && rmdir ./-p". Suggested by Andreas Schwab in: + http://mail.gnu.org/archive/html/autoconf-patches/2003-09/msg00039.html + +2003-09-26 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_COMMANDS): Make sure the + directory for AC_CONFIG_COMMANDS' first argument exists. + This makes valid the invocation of _AC_SRCPATH that follows. + Reported by Eric Sunshine. + * doc/autoconf.texi (Configuration Commands): Adjust. + +2003-09-26 Akim Demaille + + * bin/autoscan.in (Autom4te::FileUtils): Use it for find_file. + Reported by Ralf Corsepius. + +2003-09-26 Akim Demaille + + * lib/autoconf/general.m4 (AC_HELP_STRING): Don't overquote the + arguments. + Actually, use AU_ALIAS. + From Bruno Haible. + +2003-09-26 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_MKDIR_P_PREPARE): If mkdir -p . fails, + rm -fr ./-p to remove junk left behind on NextStep and OpenStep. + Problem reported by Eric Sunshine in: + http://mail.gnu.org/archive/html/autoconf-patches/2002-12/msg00014.html + +2003-09-26 Akim Demaille + + The test suite are sometimes assigning timings incorrectly. + Reported by Henk Krus. + Diagnosed by Nicolas Joly. + + * lib/autotest/general.m4 (AT_CLEANUP): Rename AT_help as + AT_help_all. + Instead of making AT_help a sequence of assignments to grow + $at_help_all, just make AT_help_all be the growing contents of + $at_help_all, and make a single assignment in... + (AT_INIT): here. + (at_times_skip): Flip the meaning and rename as... + (at_times_p): this. + (AT_INIT): When summarizing the test that ran, remove + $at_times_file after use, and check it is present before trying to + use it. + +2003-09-25 Akim Demaille + + Version 2.57d. + + * bin/Makefile.am (edit): Handle '@configure_input@'. + (autoconf, autoheader, autom4te, autoreconf, autoscan, autoupdate) + (ifnames): chmod -w. + * tests/wrapper.as (AUTOCONF, AUTOM4TE, ): Point to tests/ + executables, not bin/ executables! Otherwise all the magic needed + to find non installed files is turned off. This caused a failure + of test 40 and 41 that ran aclocal 1.8 which in turn ran autom4te + as found in its environment (sent by tests/autoreconf): pointing + to bin/autom4te that could not find its files. + * tests/mktests.sh: Force the replacement of generated files, for + the sake of "mv" program that are interactive when overwriting a + -w file. + * config/install-sh: Upgrade from CVS Automake. + +2003-09-23 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Document test -h + versus test -L issues. + +2003-09-23 Daniel Jacobowitz and + Paul Eggert + + Trivial change to support GCC's configuration procedure. + * lib/autoconf/c.m4 (AC_PROG_CPP_WERROR): New macro. + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Don't warn + about inconsistency if the preprocessor is set to give errors for + any warning. + * doc/autoconf.texi (C Compiler Characteristics): Document this. + +2003-09-13 Alexandre Duret-Lutz + + * Makefile.am (autom4te-update, autom4te_files): Fetch Struct.pm + and XFile.pm from Automake. + * lib/Autom4te/XFile.pm: Update from Automake. + +2003-09-12 Akim Demaille + + Version 2.57c. + +2003-09-12 Akim Demaille + + * config/config.guess, config/config.sub, config/missing, + * lib/Autom4te/Channels.pm, lib/Autom4te/Configure_ac.pm: Update + from masters. + +2003-09-12 Akim Demaille + + * doc/autoconf.texi (Header Portability): Promote linux/types.h, + not asm/types.h. + +2003-09-11 Akim Demaille + + * doc/autoconf.texi (Header Portability): linux/random.h. + From Peter Hendrickson. + +2003-09-10 Akim Demaille + + * tests/mktests.sh (au_exclude_egrep): Make it harder to be + willing to edit the output files. + +2003-09-10 Akim Demaille + + * tests/fortran.at (GNU Fortran 77): Also exercise AC_FC_SRCEXT + and AC_FC_FREEFORM. + * tests/mktests.sh: Skip AC_FC_SRCEXT. + * lib/autoconf/fortran.m4 (AC_FC_SRCEXT, AC_FC_FREEFORM): Likewise. + +2003-09-09 Akim Demaille + + * lib/Autom4te/FileUtils.pm (&update_file): s/cannot not/cannot/g. + Reported by Gary Vaughan. + * bin/autom4te.in (handle_m4): Likewise. + +2003-09-09 Akim Demaille + + * lib/Autom4te/FileUtils.pm (&update_file): Be sure not to leave + trailing files. + +2003-09-07 Paul Eggert + + * lib/autoconf/specific.m4 (AC_SYS_RESTARTABLE_SYSCALLS): + Improve the accuracy of the wording about obsolescence. + From a suggestion by Ian Lance Taylor in + . + +2003-09-05 Paul Eggert + + * lib/autoconf/fortran.m4 (AC_FC_FREEFORM): Try -ffree-form too, + for the benefit of g77 3.2. Fix suggested by Steven G. Johnson. + +2003-09-04 Akim Demaille + + * tests/mktests.sh (ac_exclude_list): Fix the filtering of + AC_FUNC_WAIT3. + +2003-09-04 Akim Demaille + + * bin/autom4te.in: Use &fatal where more appropriate than &error. + (freeze): When exiting, use $exit_code. + * lib/autoconf/fortran.m4: Comment changes. + +2003-09-04 Akim Demaille + + * tests/mktests.sh (ac_exclude_list): Add AC_FC_FUNC. + +2003-09-02 Steven G. Johnson + + Add support for newer Fortran dialects. The F77 interface is + unchanged, and continues to support Fortran 77. New FC macros + correspond to all the old F77 macros, with output variables FC, + FCFLAGS, and FCLIBS. AC_PROG_FC defaults to picking the newest + available dialect, but older dialects can be specified. There are + new macros AC_FC_SRCEXT to set the source extension, and + AC_FC_FREEFORM to accept free-form source files. + + * lib/autoconf/c.m4 (_AC_LANG_PREFIX(C), _AC_LANG_PREFIX(C++)): + New macros. + (AC_LANG_PROGRAM(C)): Invoke _AC_LANG_PROGRAM_C_FC_HOOKS if defined. + * lib/autoconf/fortran.m4 (AC_LANG(Fortran), _AC_FORTRAN_ASSERT, + _AC_LANG_ABBREV(Fortran), _AC_LANG_PREFIX(Fortran 77), + _AC_LANG_PREFIX(Fortran), _AC_FC, AC_LANG_SOURCE(Fortran), + AC_LANG_PROGRAM(Fortran), AC_LANG_CALL(Fortran), + AC_LANG_PREPROC(Fortran), AC_LANG_COMPILER(Fortran), + _AC_FC_DIALECT_YEAR, _AC_F95_FC, _AC_F90_FC, _AC_F77_FC, + _AC_PROG_FC, AC_PROG_FC, _AC_PROG_FC_G, _AC_PROG_FC_C_O, + AC_PROG_FC_C_O, _AC_PROG_FC_V_OUTPUT, _AC_PROG_FC_V, + _AC_FC_LIBRARY_LDFLAGS, AC_FC_LIBRARY_LDFLAGS, _AC_FC_DUMMY_MAIN, + AC_FC_DUMMY_MAIN, _AC_FC_MAIN, AC_FC_MAIN, __AC_FC_NAME_MANGLING, + _AC_FC_WRAPPERS, AC_FC_WRAPPERS, _AC_FC_FUNC, AC_FC_FUNC, + AC_FC_SRCEXT, AC_FC_FREEFORM): + New macros. + (AC_PROG_F77, AC_PROG_F77_C_O, AC_F77_LIBRARY_LDFLAGS, + AC_F77_DUMMY_MAIN, AC_F77_MAIN, _AC_F77_NAME_MANGLING, + AC_F77_NAME_MANGLING, AC_F77_WRAPPERS, AC_F77_FUNC): + Rewrite in terms of the above. + (_AC_PROG_F77_G, _AC_PROG_F77_V_OUTPUT, _AC_PROG_F77_V): Remove. + * lib/autoconf/lang.m4 (_AC_LANG_PREFIX): New macro. + * tests/acfortran.at: Test AC_FC_FREEFORM, AC_FC_FUNC, + AC_FC_MAIN, AC_FC_SRCEXT, AC_FC_WRAPPERS, AC_PROG_FC_C_O. + +2003-09-02 Paul Eggert + + * doc/autoconf.texi (Limitations of Usual Tools, Limitations of Make): + Document problems with timestamp resolution that 'make', 'cp -p', and + 'touch -r' have. + +2003-08-27 Akim Demaille + + * tests/m4sugar.at (cross_warning): Make sure to enable the + output, so that we can track spurious m4sugar output. + * tests/local.at: Require 2.57. + (AT_CHECK_M4SUGAR, AT_CHECK_M4SH): Don't m4_default the arguments that + are defaulted by AT_CHECK anyway. + Use AT_CHECK_AUTOM4TE. + * lib/m4sugar/m4sugar.m4: There should be no output at all: add a + missing dnl. + +2003-08-27 Akim Demaille + + * bin/autoheader.in: Issue the "Using auxiliary..." message only + when -Wobsolete is set. + Set it on by default. + Suggested by Klee Dienes. + +2003-08-27 Akim Demaille + + * doc/autoconf.texi (AC_FUNC_FSEEKO, AC_SYS_LARGEFILE): More + documentation. + From Guido Draheim. + +2003-08-26 Akim Demaille + + * doc/autoconf.texi (Output): Make clear that one can run code + after AC_OUTPUT. + +2003-08-25 Akim Demaille + + * config/announce-gen, GNUmakefile, Makefile.maint: Update from + CVS Bison. + +2003-08-25 Alexandre Duret-Lutz + + * bin/autoreconf.in (parse_args): Do not pass --no-force to + Automake versions prior to 1.8. + +2003-08-25 Akim Demaille + + * doc/autoconf.texi (Header Portability): netinet/if_ether.h. + From Ville Karaila. + +2003-08-24 Akim Demaille + + * configure.ac: Bump to 2.57c. + +2003-08-22 Akim Demaille + + Version 2.57b. + + * Makefile.cfg (local-checks-to-skip): New. + * Makefile.maint (local-check): Rename as... + (local-checks-available): this. + (local-check): New. + + * Makefile.am (EXTRA_DIST): Add Makefile.cfg. + * configure.ac: Require Automake 1.7.6. + +2003-08-22 Akim Demaille + + Output stack traces in warnings. + + * lib/m4sugar/m4sugar.m4 (_m4_warn): New. + Replace the former... + (m4_warn): Pass the call stack to _m4_warn. + * bin/autom4te.in: Adjust to output the call stack. + * tests/m4sugar.at (m4@&t@_warn): Adjust. + +2003-08-22 Akim Demaille + + * lib/Autom4te/Request.pm, lib/Autom4te/C4che.pm: New. + * bin/autom4te.in: Adjust. + +2003-08-21 Akim Demaille + + * lib/Autom4te/General.pm (&file_name_is_absolute): Remove. + (&verbose): Remove. + (&getopt): Adjust the note and verb channels, depending upon + --verbose. + * bin/autoheader.in, bin/autom4te.in, bin/autoscan.in, + * bin/autoupdate.in: Adjust. + Use &verb, not &verbose. + +2003-08-21 Akim Demaille + + * bin/autoheader.in (&parse_args): Use &parse_warnings and + &parse_WARNINGS. + ($help): Use Autom4te::ChannelDefs::usage. + * bin/autoscan.in: Use Autom4te::ChannelDefs. + * lib/Autom4te/General.pm: Don't export error: you don't own it. + +2003-08-21 Akim Demaille + + First stab at preserving warnings between calls to autom4te, + including when the cache is used. + + There are still several issues: (i) there are too many runs of m4 + (one for include, one for warnings, and some more), (ii) warnings + spreading on several lines are not handled gracefully, (iii) the + code meant to have the call stack display for errors does not work + (its handling should move from m4 to autom4te). + + * bin/autom4te.in Autom4te::Channels, Autom4te::ChannelDefs): + Use them. + (@preselect): Add m4_warn. + ($exit_status): Remove, use $exit_code. + ($help): Use Autom4te::ChannelDefs::usage. + (&handle_m4): No longer define the m4_warnings. + At each run, extract and report the warnings. + Always cache the result, including if the exit status is on + failure, since if nothing changes, we should result in the same + failure, hence we can use the cache. + * lib/m4sugar/m4sugar.m4 (m4_warning_ifelse, _m4_warning_ifelse) + (_m4_warning_error_ifelse, __m4_warning_error_ifelse, _m4_warn): + Remove. + (m4_warn): Redefine as a do-nothing: it is its invocation that + matters, as warnings are now reported via traces. + * lib/autoconf/general.m4 (AC_DIAGNOSE): Don't make it a copy of + the contents of m4_warn: make it _call_ m4_warn, so that tracing + the latter reveals calls to the former. + + Adjust the tests. + + * tests/m4sugar.at (m4@&t@_warn): Use existing warning categories. + +2003-08-21 Akim Demaille + + * bin/autoreconf.pm (Autom4te::Channels, Autom4te::ChannelDefs): + Use them. + +2003-08-21 Akim Demaille + + * lib/Autom4te/FileUtils.pm (&find_file): Walk the @include in + forward order. + * lib/Autom4te/ChannelDefs.pm: Doc typos. + (&parse_warnings): Accept a list of warning requests. + (&usage): Return a string, not a side effect. + (cross): New warning category. + +2003-08-21 Akim Demaille + + * lib/Autom4te/Configure_ac.pm (&find_configure_ac) + (&require_configure_ac): Accept an optional directory argument. + ($configure_ac): Remove. + * lib/Autom4te/General.pm (&find_configure_ac, &canonfile) + (&catfile): Remove. + * bin/autoheader.in, bin/autoreconf.in, bin/autoupdate.in, + * bin/autoscan.in: Adjust. + +2003-08-20 Akim Demaille + + * bin/autoheader.in: Remove duplicate 'use Autom4te::FileUtils'. + Reported by Alexandre Duret-Lutz. + +2003-08-20 Akim Demaille + + * bin/autoupdate.in, bin/autoheader.in, bin/autoreconf.in, + * bin/autom4te: Adjust. + In particular, be Autoconf tools are really silent when properly + working, bind the verbosity of the 'note' channel to $verbose. + * lib/Autom4te/General.pm (&find_file, &mtime, &update_file) + (&xsystem, &contents): Remove, since they are exported by... + * lib/Autom4te/FileUtils.pm: this. + More perldoc. + * lib/Autom4te/General.pm (&up_to_date_p): Move to... + * lib/Autom4te/FileUtils.pm: here. + +2003-08-20 Akim Demaille + + * lib/Autom4te/Channels.pm, lib/Autom4te/ChannelDefs.pm + * lib/Autom4te/Configure_ac.pm, lib/Autom4te/FileUtils.pm: New, + from CVS Automake. + +2003-08-20 Akim Demaille + + * Makefile.am (automake_cvsweb, automake_cvsargs, autom4te_files) + (autom4te-update): New. + * Makefile.cfg (update): Bind autom4te-update. + +2003-08-19 Derek Price + + * lib/autotest/general.m4: Comment various HELP_* diversions. + (PARSE_ARGS_BEGIN): New section for option parsing related + initialization. + (AT_ARG_OPTION,AT_ARG_OPTION_ARG,_AT_ARG_OPTION): New macros to define + package specific options and associated help. + +2003-08-19 Akim Demaille + + * config/announce-gen, Makefile.cfg: New. + * Makefile.am: Adjust. + * GNUmakefile, Makefile.maint: Update from CVS Coreutils. + +2003-08-19 Alexandre Duret-Lutz + + * lib/autom4te.in (Automake-preselections): Preselect + AC_CONFIG_LIBOBJ_DIR, AC_CONFIG_LINKS, m4_include, + and m4_sinclude. + +2003-08-19 Alexandre Duret-Lutz + + * lib/autom4te.in (Autoconf): Move all args except aclocal.m4? into ... + (Autoconf-without-aclocal-m4): ... this new language. + * doc/autoconf.texi (autom4te Invocation): Mention + Autoconf-without-aclocal-m4. + +2003-08-18 Derek Price + + * doc/autoconf.texi (Writing testsuite.at): Document RUN-IF-FAIL & + RUN-IF-PASS optional arguments. + +2003-08-18 Derek Price + + * doc/autoconf.texi (Programming in M4sh): Add doc for AS_IF. + +2003-08-16 Derek Price + + * doc/autoconf.texi (Writing testsuite.at): Document defaults for + STDOUT & STDERR arguments. + +2003-08-14 Derek Price + + * lib/autotestgeneral.m4 (AT_INIT): Reformat test summary line to print + DESCRIPTION rather than FILE and LINE. Shorten result to fit in new, + shorter column three. Add DESCRIPTION to log file content. + +2003-08-13 Derek Price + + * lib/autotest/general.m4 (AT_INIT): Correct typo in final status + output. + +2003-08-12 Derek Price + + * lib/autotest/general.m4 (AT_CHECK): Use new _AT_CHECK API. + (AT_CHECK_NOESCAPE): Move core functionality to... + (_AT_CHECK): ...this new macro. + +2003-08-07 Derek Price + + * lib/autotest/general.m4 (AT_CHECK): Move core functionality... + (AT_CHECK_NOESCAPE): ...to this new macro. + +2003-07-31 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_UNSET_PREPARE): Work around a bug + in Bash 2.01. Problem reported by Brian Gough in + . + +2003-07-25 John W. Eaton + + * lib/autoconf/fortran.m4 (AC_F77_LIBRARY_LDFLAGS): Also ignore + -lcrt1.o, for OS X. (trivial change) + +2003-07-07 Paul Eggert + + * lib/autoconf/c.m4 (AC_C_INLINE): Wrap the '#define inline ...' + inside '#ifndef __cplusplus'. Problem reported by + Bob Friesenhahn. + +2003-07-06 Bill Clarke + + * lib/autoconf/functions.m4 (AC_FUNC_MMAP): Cast pointer to + 'long', not 'int', for benefit of Sun's recent C++ compilers + (trivial change). See: + http://mail.gnu.org/archive/html/autoconf-patches/2003-07/msg00007.html + (This really should be 'intptr_t', not 'long', but that would + take more work.) + +2003-06-25 Akim Demaille + + * lib/Makefile.am (autom4te.cfg): Make it read only. + Depend on Makefile since it contains substitutions. + From Paolo Bonzini. + * lib/autom4te.in (args): Add local.at? for Autotest args. + This change was made on autom4te.cfg which is generated. + Reported by Raja R. Harinath. + +2003-06-25 Akim Demaille + + * doc/autoconf.texi (Header Portability): sys/mount.h. + From Gareth McCaughan. + +2003-06-23 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Report a single config.log, + not all of them. This fixes 1. the fact that when testing + Autoconf there are many many config.log, 2. the incorrect use of + top_srcdir to find config.log. + Don't mix the detailed output of failed test with the summary of + failures. Rather, append detailed log afterwards. + +2003-06-23 Akim Demaille + + * tests/local.at (AT_CHECK_CONFIGURE): Adjust to the verbose being + always run: output config.log on $at_group_log. + +2003-06-23 Akim Demaille + + * tests/torture.at (#define header templates): Don't use quotes in + C++ comments as it puzzles Emacs' sh font-lock-mode. + +2003-06-23 Akim Demaille + + * tests/mktests.sh (au_exclude_egrep): Fix output copyright notice. + * lib/autom4te.cfg (args): Add local.at? for Autotest args. + * tests/atspecific.m4: Rename as... + * tests/local.at: This. + * tests/suite.at: Move the globals into... + * tests/local.at: here. + * tests/Makefile.am: Adjust. + * doc/autoconf.texi (testsuite Scripts): Adjust. + +2003-06-21 Kevin Ryde + + * lib/autoconf/c.m4 (_AC_PROG_CC_STDC): Extend test program to get an + error from OSF 4.0 Compaq cc in its default almost-ANSI mode, thereby + ensuring we add -std1 for full-ANSI. + + * doc/autoconf.texi (hdrindex): New macro. + Add index entries for portability of various standard header files. + +2003-06-20 Akim Demaille + + * configure.ac: Bump to 2.57b. + +2003-06-20 Akim Demaille + + Version 2.57a. + +2003-06-20 Akim Demaille + + * bin/autom4te.in: Don't rely on $HOME being defined. + Reported by Marc Espie as PR/233. + +2003-06-20 Akim Demaille + + * lib/autotest/general.m4: Use at_times_file only if used. + From Nicolas Joly. + +2003-06-20 Akim Demaille + + * config/config.guess, config/config.sub, config/elisp-comp, + * config/install-sh, config/mkinstalldirs, doc/standards.texi: + Update from masters. + +2003-06-11 Paolo Bonzini + + * doc/autoconf.texi (Writing testsuite.at): Document AT_XFAIL_IF + * lib/autotest/general.m4 (AT_XFAIL_IF): New macro. + (TEST_SCRIPT): New diversion. + (AT_SETUP): Divert output to TEST_SCRIPT and move some code... + (AT_CLEANUP): ...to here. Undivert TEST_SCRIPT. + (AT_INIT): Support for expected failures. + +2003-06-02 Akim Demaille + + * bin/autom4te.in, bin/autoscan.in, bin/autoheader.in: White space + changes. + * lib/Autom4te/General.pm (&backname): Remove, no longer used by + Autoconf nor Automake. + (&contents): New, from Automake. + PODify. + +2003-05-28 Paul Eggert + + * NEWS, doc/autoconf.texi (Particular Functions), + lib/autoconf/functions.m4 (AC_FUNC_MKTIME): Check that mktime + is the inverse of localtime. + +2003-05-25 Alexandre Duret-Lutz + + * lib/Autom4te/General.pm (END): Print diagnostics to STDERR. + (handle_exec_errors): New function. Work around $! being + altered by WEXITSTATUS. + (xqx, xsystem): Use handle_exec_errors. + +2003-05-23 Alexandre Duret-Lutz + + * lib/Autom4te/General.pm (END): Rewrite exit code processing. + Do not call `_exit()', simply modify `$?'. + (xsystem): Reset $! before running system, and check it afterward. + * tests/tools.at (autoupdating AC_PREREQ): Expect exit status + 63 for version mismatches. + +2003-05-23 Akim Demaille + + * lib/autoconf/status.m4: Prefer "TAB-SP" to "SP-TAB", because of + Emacs' dangerous whitespace.el behavior (smashing "useless" spaces in + the middle of a line). + * lib/m4sugar/m4sugar.m4: Likewise. + Remove useless spaces in comments. + +2003-05-23 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_version_prereq): Failure causes an + exit 63, so that we (or Automake's "missing") can tell the + difference with a plain failure. + * doc/autoconf.texi (Notices): Adjust. + +2003-05-23 Akim Demaille + + * Makefile.am, bin/Makefile.am, config/Makefile.am, + * doc/Makefile.am, lib/autoconf/Makefile.am, tests/Makefile.am: + White spaces cleanup. + +2003-05-22 Jim Meyering + Paul Eggert + + * lib/autoconf/c.m4 (_AC_PROG_CXX_EXIT_DECLARATION): + Remove `#include ' from the list; we should never + make confdefs.h include or , because the + resulting namespace pollution would cause other tests to fail. + Configure scripts run with some older versions of g++ and HP's + aCC would fail due to such an #include. Problems reported by + Matthew Mueller in and by + Keith Bostic in + . + In the test, use the test declaration before including , + as that's closer to how it'll be used. + +2003-05-23 Akim Demaille + + * doc/autoconf.texi (Header Portability): ucred.h. + From Ian Redfern. + +2003-05-22 Paolo Bonzini + + Overhaul Autotest's logging: generate separate log files + in testsuite.dir/NNN/testsuite.log, and append them to + testsuite.log instead of re-running the test verbosely. + + * lib/autotest/general.m4 (AT_INIT): Use a single redirected + file descriptor, write 0 to at_status_file instead of setting + at_status=0, initialize some new variables (at_status_file, + at_group_log, at_suite_log, at_tee_pipe). Remove the cruft + to rerun the tests, instead append the at_group_log to the + at_suite_log when a test fails. + (AT_SETUP): pipe the test case's output into at_tee_pipe, + with the AS_MESSAGE_LOG_FD redirected to stdout. + (AT_CLEANUP): save the output status in $at_status_file + and restore it, redirect the AS_MESSAGE_LOG_FD back to + its original place. + (AT_CHECK): since tests are run with a redirected stdout, + and used to be re-run in verbose mode, turn some $at_verbose + into echo, and don't redirect the output of testing stdout + and stderr. + + * lib/autotest/autoconf.texi (testsuite Scripts): Update + the name of the debugging directory and information about + its contents. + +2003-05-22 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): Actually use the 2nd + parameter. + +2003-05-22 Akim Demaille + + * lib/autoconf/autotest.m4, lib/autoconf/autoupdate.m4 + * lib/autoconf/fortran.m4 lib/autoconf/general.m4 + * lib/autoconf/headers.m4 lib/autoconf/oldnames.m4 + * lib/autoconf/status.m4: Fix and adjust copyright notices. + +2003-05-22 Akim Demaille + + * aclocal.m4, bin/autoconf.as, lib/autoconf/autoconf.m4, + * lib/autoconf/autoheader.m4, lib/autoconf/autoupdate.m4, + * lib/autoconf/c.m4, lib/autoconf/fortran.m4, + * lib/autoconf/general.m4, lib/autoconf/headers.m4, + * lib/autoconf/lang.m4, lib/autoconf/libs.m4, + * lib/autoconf/programs.m4, lib/autoconf/specific.m4, + * lib/autoconf/status.m4, lib/autoconf/types.m4, + * lib/autotest/general.m4, lib/m4sugar/m4sugar.m4, + * tests/atspecific.m4, tests/base.at, tests/compile.at, + * tests/foreign.at, tests/m4sh.at, tests/semantics.at, + * tests/tools.at, tests/torture.at: + Whitespace clean up. + Suggested by Jim Meyering. + +2003-05-22 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_GETLOADAVG): Restore smashed + ' \t' as '\t ' so that Emacs' whitespace.el keep it. + Reported by Jim Meyering. + +2003-05-22 Akim Demaille + + * doc/autoconf.texi: Replace AC_HELP_STRING AS_HELP_STRING. + Add AC_HELP_STRING to the obsolete macros section. + Typos. + Use '@.' for sentences that ended in a capital letter. + From Art Haas. + +2003-05-22 Akim Demaille + + * config/config.guess, config/config.sub, config/elisp-comp, + * config/install-sh, config/mdate-sh, config/mkinstalldirs, + * config/texinfo.tex, doc/standards.texi: Update from masters. + +2003-05-21 Paolo Bonzini + + * lib/m4sugar/m4sh.m4 (AS_VAR_SET): Escape the RHS before passing + it to eval. + +2003-05-21 Akim Demaille + + * bin/autoupdate.in ($m4): Fix quotation. + Reported by Martin Mokrejs. + +2003-05-19 Paul Eggert + + * ChangeLog, ChangeLog.2, THANKS, lib/m4sugar/m4sugar.m4: + Remove non-ASCII characters. + +2003-05-18 Paolo Bonzini + + * tests/semantics.at (AC_SEARCH_LIBS): New test. + * tests/semantics.at (AC_CHECK_HEADERS_OLD, + AC_CHECK_HEADERS_NEW): New tests. + +2003-05-17 Akim Demaille + + * lib/autoconf/functions.m4: Use the default includes so that + memcmp be declared before being tested. + Reported by Sander Niemeijer. + (AC_FUNC_ERROR_AT_LINE, AC_FUNC_GETGROUPS, AC_FUNC_STRNLEN): Likewise. + * doc/autoconf.texi (Default Includes): Document + AC_INCLUDES_DEFAULT. + +2003-05-17 Akim Demaille + + * lib/autoconf/specific.m4: Include signal.h and unistd.h. + * doc/autoconf.texi (Obsolete Macros): Adjust. + Reported by Werner LEMBERG and Debian Bug 190886. + +2003-05-16 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_UNSET_PREPARE): s/FOO/as_foo/ to avoid + user name space clashes. + Reported by Bruno Haible. + +2003-05-16 Akim Demaille + + * bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in, + * bin/autoscan.in, bin/autoupdate.in, bin/ifnames.in (BEGIN): Make + them uniform, and more robust to Perl special characters. + Reported by Martin Mokrejs. + +2003-05-14 Akim Demaille + + * tests/foreign.at (Libtool): Skip all Libtools pre 1.4. + +2003-05-14 Akim Demaille + + * doc/autoconf.texi (Header Portability): X11/extensions/scrnsaver.h, + linux/irda.h. + +2003-05-12 Akim Demaille + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Improve the + message. + From Matthias Andree. + +2003-05-07 Alexandre Duret-Lutz + + * lib/Autom4te/XFile.pm (lock, truncate): Do not pass @_ to flock + and truncate. + +2003-05-06 Akim Demaille + + Don't try to be smart with aclocal 1.8+ because (i) aclocal no + longer updates aclocal.m4 if useless, (ii) if a file m4_included + by aclocal.m4 is changed it might require the importing of another + m4 extension file, i.e., aclocal must be run. + + * bin/autoreconf.in (&run_aclocal, $aclocal_supports_force): New. + (&parse_args): Use --force with aclocal if required and supported. + (&autoreconf_current_directory): Use &run_aclocal. + +2003-05-06 Akim Demaille + + Lock autom4te's cache. + + * lib/Autom4te/XFile.pm ($me, &name, &lock, &truncate, &seek): New. + * bin/autom4te.in (&Request::save, &Request::load): Use an IO::File + argument instead of a file name, so that the request file remains + open during the whole autom4te run. + ($icache_file): New. + (&freeze): Lock the $icache_file. + +2003-04-29 Derek Price + + * lib/autotest/general.m4 (AT_KEYWORDS): Don't use a comma as the + seperator with m4_append_uniq(). It doesn't work. + (AT_CLEANUP): Add `;' to end of at_help_all. + (AT_INIT): Allow --keywords to be specified more than once. When + grepping $at_help_all for keywords, use the field and keyword + seperators to ensure a complete keyword match. Alter at_prev handling + to support the new --keywords behavior. + +2003-04-27 Karl Berry + + * doc/autoconf.texi: Make the dir entries in the autoconf manual + align better with others. I also made some of the individual + entries on one line, for brevity and to make it easier for me to + sort my dir-example file in the Texinfo distribution :). + +2003-04-12 Jim Meyering + + * NEWS: Mention the new macro. + * lib/autoconf/c.m4 (AC_C_RESTRICT): New macro. + * doc/autoconf.texi (C Compiler): Describe AC_C_RESTRICT. + * tests/c.at: Test AC_C_RESTRICT. + * tests/mktests.sh (ac_exclude_list): Add exclusion for AC_C_RESTRICT. + +2003-04-08 Akim Demaille + + * bin/ifnames.in: Skip C++ comments. + From Jeremy Yallop. + +2003-04-08 Akim Demaille + + * GNUmakefile (SHELL): Don't assume sh is in /bin/. + From Ilya Zakharevich. + +2003-04-08 Akim Demaille + + * doc/autoconf.texi (Particular Headers): Some about sys/socket.h, + net/if.h, stdlib.h. + +2003-04-01 Derek Price + + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Correct syntax error + from Akim's checkin of 2003-03-29. + +2003-04-01 Derek Price + + * tests/torture.at (Configuring subdirectories): Add missing + close-quote for Akim's change from 2003-03-28. + +2003-04-01 Akim Demaille + + * doc/autoconf.texi (ac, at, ms): Rename these indexes as... + (AC, AT, MS): these. + (shortindexflag, @acindex, @ahindex, @asindex, @atindex, @msindex): + New. + Use them. + * doc/Makefile.am (CLEANFILES): Adjust. + (TEXI2DVI): Make it --batch. + +2003-03-31 Derek Price + + * lib/autotest/general.m4: Revert the checkin from 2003-03-27 + which removed the main loop. + Thanks to Akim Demaille. + +2003-03-29 Akim Demaille + + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Skip OS/2's install, + that starts a GUI. + From Ilya Zakharevich. + +2003-03-29 Akim Demaille + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): The + documentation to read is Autoconf's. + Suggested by Paul Eggert. + +2003-03-28 Akim Demaille + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): Suggest + reading the section "Present But Cannot Be Compiled" when the + header causes problems. + +2003-03-28 Akim Demaille + + * tests/torture.at (Configuring subdirectories): Require aclocal + 1.4, otherwise the test fails, as it does support configure.ac. + This fixes the "test 40 failed" bug reports. + +2003-03-28 Akim Demaille + + * doc/autoconf.texi (C Compiler): `#line' portability. + From Paul Eggert and Nelson H. F. Beebe. + +2003-03-27 Derek Price + + * lib/autotest/general.m4: Eliminate main loop and reorganize test + layout in order to allow scripting around test groups. + +2003-03-27 Derek Price + + * lib/autotest/general.m4 (PARSE_ARGS,PARSE_ARGS_END,HELP,HELP_MODES, + HELP_TUNING,HELP_OTHER,HELP_END,PREPARE_TESTS,TESTS_END): Define and + use new diversions in preparation for accepting new arguments and + allowing scripting around tests. + (OPTIONS,TAIL): Remove these diversions to make way for the ones above. + +2003-03-26 Derek Price + + * lib/autoconf/general.m4 (AC_ARG_VAR): Use AS_HELP_STRING instead of + obsolete AC_HELP_STRING. + (AC_HELP_STRING): AU_DEFUN to... + * lib/m4sugar/m4sh.m4 (AS_HELP_STRING): ...here. + * tests/m4sh.at (AS_HELP_STRING): New test. + + * tests/acgeneral.at: Regenerated. + +2003-03-26 Derek Price + + * lib/autotest/general.m4: s/DEFAULT/DEFAULTS/ since it makes more + sense. Verbosify the diversion definitions comment. + +2003-03-26 Derek Price + + * lib/autotest/general.m4 (AT_INIT): Remove redundant call to + AS_PREPARE. + +2003-03-21 Eric Siegerman + + * doc/autoconf.texi (Present But Cannot Be Compiled): + Grammar fixes and minor rewording. (trivial change) + +2003-03-06 Paul Eggert + + Work around a problem noted by Nelson H. F. Beebe with coreutils + 4.5.9: Sun c89 (Sun WorkShop 6 update 2 C 5.3 Patch 111679-08 + 2002/05/09) rejects '#line 32768 "configure"' because the line + number overflows. + * lib/autoconf/c.m4 (AC_LANG_SOURCE(C)): Do not generate + #line directives. + * lib/autoconf/lang.m4 (AC_LANG_SOURCE): Fix comment to match this. + * doc/autoconf.texi (Generating Sources): Document this. + +2003-03-01 Richard Dawe + + * tests/atspecific.m4 (AT_CHECK_AUTOM4TE): Normalize + file name for the m4 program, when it has an "exe" file extension. + DJGPP's error messages include the error code in brackets - + remove the error code during normalization. + +2003-02-28 Akim Demaille + + * doc/autoconf.texi (Present But Cannot Be Compiled): New. + +2003-02-28 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Remove the section + about `$<' in inference rules, it was a bogus interpretation of + an old Automake change. Discuss NetBSD, FreeBSD, OpenBSD, and + Tru64 make in the "target lookup" section. + (Automake): Automake 1.5+ no longer requires special tools to be + present on the developer's host. + +2003-02-26 Richard Dawe + + * bin/autoheader.in (BEGIN): For DJGPP SHELL may not be set + to a shell that can handle redirection or quoting correctly. + Override SHELL with the shell detected by configure. + Use of $^O suggested by Tim van Holder. + * bin/autom4te.in (BEGIN): Likewise. + * bin/autoreconf.in (BEGIN): Likewise. + * bin/autoscan.in (BEGIN): Likewise. + * bin/autoupdate.in (BEGIN): Likewise. + * bin/ifnames.in (BEGIN): Likewise. + + * bin/ifnames.in: Add final newline to help and version messages. + + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Translate colons, + to cope with DOS-style absolute paths, when constructing + ${ac_make}. + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS, _AC_OUTPUT_FILES): + When constructing paths with IFS=:, quote the path. If we're + constructing a DOS-style absolute path, we don't want to split it + on the colon. + + * tests/atspecific.m4 (AT_CHECK_CONFIGURE): Fix typo + in description. + +2003-02-25 Pavel Roskin + + * bin/autoheader.in: Add missing newline when printing + suggestion how change AC_DEFINE call. + +2003-02-24 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Fix typo in + 2002-09-01 patch by replacing "test -n" with "test -z". + This fixes a bug found by Jeff Painter and reported by Tom Epperly in + . + + * doc/autoconf.texi (Shell Substitutions): test -n -> test -z, + to fix a mismatch between example and discussion. + +2003-02-24 Kevin Ryde + + * doc/autoconf.texi (Limitations of Builtins): Add notes on printf + format starting with "-". + +2003-02-20 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): `foo=bar make -e' + is not portable inside Makefile. + +2003-02-20 Akim Demaille + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL): When + compiler says yeah, but preproc says nope, compiler is right. + Conversely, prompt the reader to send a bug report to the + maintainers of the package, not of Autoconf. + +2003-02-20 Klee Dienes + + * bin/autoreconf.in (autoreconf_current_directory): Properly + handle an empty aclocal.m4. + +2003-02-20 Akim Demaille + + * lib/autoconf/general.m4 (AC_PREFIX_PROGRAM): Quote + $ac_prefix_program. + From Larry Jones. + +2002-12-23 Paul Eggert + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY(C)): Define $1 to an + innocuous variant befor including or . This + works around a bug reported by Albert Chin: HP-UX 11i + (and earlier versions) have a that declares + gettimeofday and many other functions. + +2002-12-03 Paul Eggert + + Version 2.57. + + * NEWS, configure.ac: Update version. + + * doc/fdl.texi: Upgrade to FDL version 1.2. + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY(C)): Use the function f + nontrivially in main's body, so that f's external declaration is + not optimized away in AIX. This should fix the bug reported by + Martin Frydl in + . + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY(C), + _AC_PROG_PREPROC_WORKS_IFELSE): Use if __STDC__ is + defined, to support freestanding compilers. This should fix the + bug reported by Momchil Velkov in + . + + * doc/autoconf.texi (Obsolete Macros): Fix typos (insert empty + arg, AC_DEFINE -> AC_DEFINE_UNQUOTED) in documentation for + obsolete AC_CHECK_TYPE. The missing empty arg was reported + by Simon Josefsson in + . + + * Makefile.maint (www-gnu): New macro. + (standards.texi-url_prefix, make-stds.texi-url_prefix): Use it, as + the location has moved. + +2002-12-02 Martin Frydl + + * bin/autom4te.in (at_flatten): rewritten to avoid M4 problem when + \(.*\) match is too long and there is something more to be checked. + + +2002-11-15 Akim Demaille + + Version 2.56. + + * config/install-sh: chmod +x. + From Paul Eggert. + * config/move-if-change: Indenting changes. + * Makefile.am (AUTOMAKE_OPTIONS): Move to... + * configure.ac (AM_INIT_AUTOMAKE): here. + Require 1.7.1. + +2002-11-14 Akim Demaille + + Version 2.55. + + * config/config.guess, config/config.sub, config/install-sh: + Update from masters. + +2002-11-14 Akim Demaille + + * Makefile.maint: Sync with Bison, i.e.: + (po-check): Scan .l and .y files instead of the + .c and the .h files that they generate. This fixes the bug + reported by Tim Van Holder in: + + Look for N_ as well as for _. Try to avoid matching #define for + N_ and _. + From Paul Eggert. + +2002-11-14 Akim Demaille + + * doc/autoconf.texi (C Compiler): Compiling several files at once. + From Paul Eggert and Albert Chin-A-Young. + +2002-11-14 Akim Demaille + + * doc/autoconf.texi (C Compiler): Solitary backslashes. + From Paul Eggert and Albert Chin-A-Young. + +2002-11-14 Kevin Ryde + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY(C)): Initialize f=$1 rather + than assigning in main, to avoid HP cc +O3 optimizing it away. + +2002-11-12 Peter Eisentraut + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Add -q + option. Process --recheck after parsing all options. Pass -q + option to configure on --recheck. + (AC_OUTPUT): Pass -q from configure to config.status. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Strip -q from + arguments to record. + * doc/autoconf.texi (config.status Invocation): Document + config.status -q option. + +2002-11-07 Alexandre Duret-Lutz + + * bin/autoscan.in (scan_file): Scan Makefile.am too. Ignore + Makefile.in if Makefile.am exists. + (output): Strip `.am' from Makefiles. Don't + output AC_CONFIG_FILES if no Makefiles were found. + +2002-11-07 Akim Demaille + + * Makefile.am (cvs_files): Add elisp-comp, mdate-sh. + (local_updates): New. + * Makefile.maint: Update, from CVS Bison. + (local_updates): New. + +2002-11-06 Akim Demaille + + * lib/autoconf/c.m4 (AC_LANG_FUNC_LINK_TRY): Wrap the `f' + declaration in extern "C" too. + Reported by Roberto Bagnara. + +2002-11-06 Akim Demaille + + * tests/torture.at (Configuring subdirectories): Don't use grep + -w. + * doc/autoconf.texi (Limitations of Usual Tools): Grep -w. + Reported by Ezra Peisach. + +2002-11-05 Akim Demaille + + * lib/autoconf/autoheader.m4 (_AH_TEMPLATE_OLD, _AH_VERBATIM_OLD): + Remove. + We _have_ to stop using the old compatibility scheme that tried to + avoid useless backslashes because Libtool 1.4.3 contains a + AC_DEFINE([error_t], [int], + [Define to a type to use for \`error_t' if it is not + otherwise available.]) + We _have_ to quote the single quote and backslashes with \. The + old compatibility scheme saw that ` was backslashed, and therefore + did not quote the single quote. Hence before this patch, Autoconf + was not compatible with Libtool. + +2002-11-04 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Set the following variables, + too: LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_MONETARY, + LC_NAME, LC_PAPER, LC_TELEPHONE. + * doc/autoconf.texi (Special Shell Variables): Mention those vars. + +2002-11-04 Akim Demaille + + Version 2.54c. + + * Makefile.maint (update, cvs-update, po-update, do-po-update): + New. + * config/texinfo.tex: Update. + +2002-11-03 Akim Demaille + + * bin/autoreconf.in (&autoreconf_current_directory): New, extracted + from... + (&autoreconf): here. + ($help, $make, &parse_args, &autoreconf_current_directory): + Support -m/--make. + * doc/autoconf.texi (autoreconf Invocation): Adjust. + +2002-10-31 Bruno Haible + + * lib/autoconf/functions.m4 (_AC_FUNC_MALLOC_IF): Change message. + Change name of cache variable to ac_cv_func_malloc_0_nonnull. + (AC_FUNC_MALLOC): Change description of HAVE_MALLOC macro. + (_AC_FUNC_REALLOC_IF): Change message. Change name of cache variable + to ac_cv_func_realloc_0_nonnull. + (AC_FUNC_REALLOC): Change description of HAVE_REALLOC macro. + +2002-10-31 Akim Demaille + + The test suite was no longer checking for trailing envvars and files. + + * tests/atspecific.m4 (AC_STATE_SAVE): Don't use quadrigraphs here. + (AT_CHECK_ENV): Make sure the `state-ls.before file exists. + +2002-10-31 Akim Demaille + + * lib/autoconf/programs.m4 (AC_PROG_MAKE_SET): Use and display + `$(MAKE)' instead of '${MAKE}' to emphasize that we refer to the + Make variable, not a shell variable. + Suggested by Bruno Haible. + +2002-10-31 Akim Demaille + + * bin/autom4te.in (load_configuration): Reject #args out of any + language. + +2002-10-31 Akim Demaille + + * lib/autoconf/general.m4 (_AC_MSG_LOG_CONFTEST): New. + (_AC_PREPROC_IFELSE, _AC_COMPILE_IFELSE, _AC_LINK_IFELSE) + (_AC_RUN_IFELSE): Use it. + * lib/autoconf/lang.m4 (_AC_COMPILER_OBJEXT): + (_AC_COMPILER_EXEEXT_DEFAULT): Likewise. + * lib/autoconf/c.m4 (AC_LANG_SOURCE): Don't include confdefs.h, + inline it. + +2002-10-30 Akim Demaille + + * bin/autom4te.in (&parse_args, $help): Support --no-cache. + * doc/autoconf.texi (autom4te Invocation): Adjust. + Suggested by Tim van Holder. + +2002-10-29 Paul Eggert + + * doc/autoconf.texi (Particular Functions): AC_FUNC_MALLOC and + AC_FUNC_REALLOC check for compatibility with glibc, not POSIX. + Problem reported by Bruno Haible. + +2002-10-29 Akim Demaille + + * doc/autoconf.texi (Header Templates): Put also in words what the + pictures says to assist free style readers. + (Customizing autom4te): s/--cache=/--cache /. + +2002-10-29 Akim Demaille + + * lib/autoconf/functions.m4 (_AC_FUNC_VFORK): Include stdlib.h and + sys/wait.h. + sparc_address_test returns void. + Use it with an argument, as prototyped. + From Bruno Haible. + +2002-10-29 Akim Demaille + + * doc/autoconf.texi (Subdirectories): Cygnus dirs have + configure.in, not configure.ac. + Reported by Bruno Haible. + +2002-10-29 Akim Demaille + + * tests/torture.at (Deep Package): New test. + (Configuring subdirectories): Don't use a testSubDir as Autotest + now does it itself. + +2002-10-29 Akim Demaille + + * bin/autoreconf.in (&parse_args, $help): Support --warnings. + * doc/autoconf.texi (Invoking autom4te): Rename as... + (autom4te Invocation): this, for consistency with the other nodes. + +2002-10-29 Akim Demaille + + * lib/autom4te.in (Autoconf): s/automate/autom4te/. + Reported by Ralf Corsepius. + +2002-10-29 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_QUOTE): The warning about quoted + characters is a back as an `obsolete' warning now. + Reported by Ralf Corsepius. + +2002-10-28 Akim Demaille + + * configure.ac: Bump to 2.54c. + +2002-10-28 Akim Demaille + + Version 2.54b. + + * tests/foreign.at (Libtool): Adjust to broken libtoolize. + +2002-10-28 Akim Demaille + + * tests/atspecific.m4 (AT_CHECK_AUTOM4TE): Be robust to different + m4 executable names, and different GNU M4 version. + Reported by Ezra Peisach and Paul Jarc. + +2002-10-27 Akim Demaille + + * lib/autoconf/functions.m4 (_AC_FUNC_VFORK): Really use + AC_RUN_IFELSE. + +2002-10-27 Akim Demaille + + * doc/autoconf.texi: More AC_MSG_FAILURE promotion. + * lib/autoconf/fortran.m4 (_AC_F77_NAME_MANGLING): + Die when a simple Fortran program cannot be compiled. + * lib/autoconf/lang.m4 (AC_LANG_CALL, AC_LANG_FUNC_LINK_TRY): + Issue a warning if no function is given. + +2002-10-27 Akim Demaille + + * doc/autoconf.texi (Run Time): Document AC_RUN_IFELSE. + Move the documentation of AC_TRY_RUN to... + (Obsolete Macros): here. + Adjust all the old samples still using AC_TRY_RUN to AC_RUN_IFELSE. + (autoconf Invocation): Remove the duplicates with `invoking + autom4te'. + * lib/autoconf/headers.m4 (AC_HEADER_STDC): Don't use AC_TRY_RUN. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Likewise. + +2002-10-27 Akim Demaille + + * doc/autoconf.texi (Generating Sources): Document AC_LANG_CALL + and AC_LANG_FUNC_LINK_TRY. + (Examining Libraries): Rename as... + (Running the Linker): this. + Document AC_LINK_IFELSE. + Move the documentation of AC_TRY_LINK and AC_TRY_LINK_FUNC to... + (Obsolete Macros): here. + * lib/autoconf/fortran.m4 (_AC_F77_NAME_MANGLING): Don't use + AC_TRY_LINK_FUNC nor AC_TRY_LINK. + * lib/autoconf/libs.m4 (AC_CHECK_LIB, AC_PATH_XTRA): Likewise. + * lib/autoconf/headers.m4 (AC_USG): Likewise. + +2002-10-27 Akim Demaille + + * lib/autoconf/headers.m4 (AC_HEADER_STDC): Don't use AC_TRY_CPP. + + More `check config.log' messages. + + * lib/autoconf/general.m4 (AC_MSG_FAILURE): New. + * doc/autoconf.texi (Printing Messages): Document it. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): Use it when + appropriate. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT) + (_AC_COMPILER_EXEEXT_WORKS, _AC_COMPILER_EXEEXT_O) + (_AC_COMPILER_OBJEXT): Likewise. + * lib/autoconf/general.m4 (AC_RUN_IFELSE): Likewise. + * lib/autoconf/fortran.m4 (_AC_LANG_PROGRAM_C_F77_HOOKS): + Likewise. + * lib/autoconf/c.m4 (AC_PROG_CPP, AC_PROG_CC, AC_PROG_CXXCPP): + Likewise. + + Deprecate macros with unusual interfaces. + + * lib/autoconf/general.m4 (AC_TRY_CPP, AC_TRY_LINK) + (AC_TRY_COMPILE, AC_TRY_RUN): AU_DEFUN'ed. + + Document the new ones, and proper style. + + * doc/autoconf.texi (Generating Sources): New. + Document AC_LANG_CONFTEST, AC_LANG_SOURCE, AC_LANG_PROGRAM. + (Examining Declarations): Rename as... + (Running the Preprocessor): this. + Document AC_PREPROC_IFELSE. + (Examining Syntax): Rename as... + (Running the Compiler): this. + (AC_FOO_IFELSE vs AC_TRY_FOO): New section. + (Obsolete Macros): Move the definition of AC_TRY_CPP and + AC_TRY_COMPILE here. + +2002-10-27 Akim Demaille + + Move sections around. + + * doc/autoconf.texi (Customizing autom4te): Remove a lost + sentence. + Reported by Burno Haible. + (Language Choice): Now the first section of... + (Writing Tests): this section. + Make the introduction less C-centric. + (Guidelines, Test Functions): Move to... + (Writing Test Programs): this new section. + (Test Programs): Merge into... + (Run Time): this. + +2002-10-27 Akim Demaille + + * lib/freeze.mk ($(AUTOM4TE_CFG)): Add a missing dependency on + autom4te.in that resulted in the need for two `make' runs. + +2002-10-27 Akim Demaille + + * configure.ac: Bump to 2.54b. + +2002-10-25 Akim Demaille + + Version 2.54a. + + * Makefile.maint: Update from the Coreutils. + (AMTAR): Remove, obsolete. + (automake_repo): Update to redhat.com. + (cvs_file): New. + Adjust to the fact that ansi2knr is now hosted by Automake. + * Makefile.am (cvs_files): Add install-sh and mkinstalldirs. + * config/config.guess, config/mkinstalldirs, config/texinfo.tex: + Update from masters. + * lib/autoscan/Makefile.am (EXTRA_DIST, nodist_autoscanlib_DATA): + autoscan.pre is not to be installed, and autoscan.list is not to + be shipped. + (CLEANFILES): Add autoscan.list. + (autoscan.list): Disable the cache. + * bin/Makefile.am: Include freeze.mk. + +2002-10-25 Akim Demaille + + * bin/autom4te.in (&load_configuration): Take the file as + argument. + (&parse_args): Handle -C, --cache. + ($help): Adjust. + (MAIN): Load ~/.autom4te.cfg and ./.autom4te.cfg. + * lib/autom4te.in (Autoconf): Pass --cache=autom4te.cache. + * doc/autoconf.texi (Invoking autom4te): Document --cache. + Now a subsection of... + (Using autom4te): This new section. + (Customizing autom4te): New. + (autom4te.cache): Adjust. + +2002-10-25 Akim Demaille + + * doc/autoconf.texi (Generic Headers): More information on how to + use AC_CHECK_HEADERS. + +2002-10-25 Akim Demaille + + * bin/autoconf.as, bin/autoconf.in, bin/autoupdate.in ($help): + Space changes. + +2002-10-25 Akim Demaille + + * bin/autoscan.in (output): Output AC_PREREQ. + (%needed_macros): Add AC_PREREQ so that configure.ac without one + be reported. + +2002-10-23 Akim Demaille + + * doc/autoconf.texi (Particular Headers): In AC_HEADER_STDBOOL, + document _Bool. + +2002-10-23 Akim Demaille + + * bin/autom4te.in (handle_traces): Handle @&t@ in traces. + Reported by Peter Eisentraut. + +2002-10-23 Akim Demaille + + * lib/autoconf/headers.m4 (AC_HEADER_STDBOOL): Also look for the + type _Bool. + Fix a typo. + * doc/autoconf.texi (Particular Headers): Adjust according to Paul + Eggert's recommandations. + +2002-10-22 Akim Demaille + + * lib/autoconf/headers.m4 (AC_HEADER_STDBOOL): New, based on CVS + Bison, by Paul Eggert. + * doc/autoconf.texi (Particular Headers): Document it. + +2002-10-22 Aaron M. Ucko + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Avoid duplicates in + `$ac_configure_args'. + +2002-10-22 Akim Demaille + + * doc/autoconf.texi: Use AC_CONFIG_HEADERS in examples. + (AC_ST_BLKSIZE, AC_ST_RDEV): Directly point to AC_CHECK_MEMBERS. + From Art Haas. + +2002-10-22 Akim Demaille + + Restore the 2002-10-11 Akim Demaille patch: + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL) + (AC_CHECK_HEADER, _AC_CHECK_HEADER_NEW,_AC_CHECK_HEADER_OLD): Restore. + (_AC_CHECK_HEADER_NEW): Rename as... + (AC_CHECK_HEADER): this. + +2002-10-22 Akim Demaille + + * doc/autoconf.texi (Limitations of Usual Tools): Remove incorrect + words about HP-UX cmp: it was actually a user-written cmp. + +2002-10-22 Akim Demaille + + * tests/foreign.at (Libtool): Don't check autoconf's stderr: there + are a few warnings. + * lib/autoconf/autoheader.m4 (AH_VERBATIM, _AH_VERBATIM_OLD): + Quote for Perl '' strings, not "". + * bin/autoheader.in: Invoke autoconf to get '' strings, not "" + strings. + +2002-10-22 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_QUOTE): The warning about quoted + characters is a syntax warning now. + (_AS_QUOTE): Accept $2 as list of characters to quote. + * lib/autoconf/autoheader.m4 (AH_VERBATIM, _AH_VERBATIM_OLD): + Quote for Perl, not sh. + * bin/autoheader.in: When $debug, report the file which is + `do'ne. + * tests/tools.at (autom4te, autoheader): Exercise @bar, not merely + `@', to tickle Perl's lists. + Reported by Carlos Velasco. + +2002-10-18 Akim Demaille + + * bin/autom4te.in (handle_m4): Pass --fatal-warning to m4, so that + missing included files _are_ errors. + Thanks to Alexandre Duret-Lutz. + * tests/tools.at (autom4te cache): Adjust. + * tests/atspecific.m4 (AT_CHECK_AUTOM4TE): New. + (AT_CHECK_M4SUGAR): Use it. + * tests/m4sugar.at (m4_warn, m4_require: circular dependencies): + Adjust. + * tests/tools.at (autom4te): Now it does exit 1. + +2002-10-17 Akim Demaille + + * lib/autoconf/general.m4 (AC_CACHE_SAVE): Don't use cmp. + Fixes the `AC_ARG_VAR' test failures. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES): Don't use cmp. + * lib/freeze.mk (check-forbidden-patterns): New. + * lib/autoconf/Makefile.am, lib/autotest/Makefile.am + * lib/m4sugar/Makefile.am (check-local): Use it to catch `cmp'. + * doc/autoconf.texi (Limitations of Usual Tools): HP-UX' cmp and + /dev/null. + Reported months ago by H. Merijn Brand. + +2002-10-17 Akim Demaille + + * tests/tools.at (autoheader): Put randoms `@' to stress Perl. + +2002-10-16 Paul Eggert + + * Makefile.maint (wget_files): Remove ansi2knr.c. + (ansi2knr.c-url_prefix): Remove. + +2002-10-16 Akim Demaille + + Because of caching, some files that no longer exist and are no + longer required can still cause errors. + Reported by Alexandre Duret-Lutz. + + * bin/autom4te.in (&parse_args): Do not prepend `--reload-state' + to frozen files in @ARGV, as @ARGV must remain being a list of + files. Rather, at M4 call sites, use this... + (&files_to_options): New function. + (&freeze): Use &error. + (&up_to_date): If a file that was included according to the cache + is no longer there, then the output is out dated. + (&main): Don't even check whether a file is up to date is anyway + --force is given. + * tests/tools.at (autom4te cache): New. + +2002-10-16 Akim Demaille + + * bin/autoconf.as: Kill dead options. + * bin/autoupdate.in (&parse_args): Kill old options. + * bin/autoreconf.in (&parse_args): Remove dead options. + Factor some code. + (&autoreconf): Report the directories we enter *and leave*, so + that error messages can be easily located, and use GNU Make + format, so that Emacs' compile mode understands us. + * lib/Autom4te/General.pm (&update_file): Use `verbose' to report + if some file was changed instead of `print'. + * bin/autoheader.in: Suggest AC_DEFINE with 3 args when needed. + (&parse_args): Remove the dead options. + * tests/atspecific.m4 (AT_CHECK_AUTOHEADER): Adjust to the new + autoheader's quiet mode. + (AT_CHECK_AUTOUPDATE): Likewise. + * tests/tools.at (autoupdate): Adjust. + * tests/semantics.at (AC_C_BIGENDIAN): Likewise. + +2002-10-11 Akim Demaille + + No longer use CPP to check for the existing of headers: use CC to + check for compilability. + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_MONGREL) + (AC_CHECK_HEADER, _AC_CHECK_HEADER_OLD): Remove. + (_AC_CHECK_HEADER_NEW): Rename as... + (AC_CHECK_HEADER): this. + + * lib/autotest/general.m4 (AT_INIT): Include the failed test + numbers in the Subject suggestion. + +2002-10-11 Akim Demaille + + * lib/autoconf/specific.m4 (AC_DECL_SYS_SIGLIST): Obsolete. + Suggest using AC_CHECK_DECLS instead. + +2002-10-11 Akim Demaille + + * tests/torture.at (AC_ARG_VAR): Have configure report the value + of `precious'. + +2002-10-11 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): Use $$ in the + file name to enable parallel executions. + From Sam Varshavchik. + +2002-10-08 Akim Demaille + + * bin/autoreconf.in (&autoreconf): Run autopoint before the first + aclocal invocation, as Gettext macros might not be visible to + aclocal. + Instead of blindly running autopoint, scan configure.ac (not the + traces) for AM_GNU_GETTEXT_VERSION uses, as autopoint does. + Reported by Paul D. Smith. + +2002-10-08 Paul Eggert + + Work around problems found when POSIXLY_CORRECT=1 is set. + None of this seems to have anything to do with POSIX, really, + but it's how Perl getopt works. + * bin/autom4te.in (parse_args): Configure GetOpt with + "permute", too. + * doc/autoconf.texi (Invoking autom4te): + --warning -> --warnings. + * lib/autom4te.in: --warning -> --warnings. + +2002-09-28 Akim Demaille + + * doc/autoconf.texi (autom4te.cache): New section. + +2002-09-28 Akim Demaille + + * lib/autom4te.in (Autoscan-preselections, Autoreconf-preselections) + (Automake-preselections): Update. + * bin/autoreconf.in, bin/autoheader.in: Comment changes. + +2002-09-28 Akim Demaille + + * lib/autoscan/autoscan.pre: Move all the remaining rules to... + * lib/autoconf/c.m4, lib/autoconf/functions.m4, + * lib/autoconf/headers.m4, lib/autoconf/libs.m4, + * lib/autoconf/specific.m4, lib/autoconf/types.m4: here. + +2002-09-28 Akim Demaille + + * tests/torture.at (Configuring subdirectories): Be robust to + users who use config.site to require for a cache: in this case, + the two last configure runs, using two different sets of + arguments, trigger a legitimate error. + +2002-09-28 Akim Demaille + + * tests/m4sh.at (Functions Support, Functions and return Support): + New. + +2002-09-28 Akim Demaille + + * bin/Makefile.am (ETAGS_SH, ETAGS_PERL): Update: ifnames and + autoheader are Perl programs. + (autoconf, autoheader, autoreconf, autoupdate, ifnames, autoscan) + (autom4te): Specify that the sources are in the $srcdir. + * doc/autoconf.texi (Installation Directory Variables): Adjust. + +2002-09-28 Akim Demaille + + * lib/autoscan/autoscan.pre (st_blksize, st_blocks, st_rdev) + (tm_zone): Move their rules to... + * lib/autoconf/types.m4: here, using AN_ macros. + * lib/autoscan/autoscan.pre (AWK, BISON, INSTALL, LEX, LN, MAKE) + (RANLIB, YACC, awk, bison, byacc, flex, gawk, install, lex, ln) + (make, mawk, nawk, ranlib, yacc): Similarly, move to... + * lib/autoconf/programs.m4: here. + * lib/freeze.mk (ETAGS_FOR_M4, ETAGS_FOR_M4SUGAR) + (ETAGS_FOR_AUTOCONF): New. + Use it. + +2002-09-28 Akim Demaille + + * lib/autoconf/autoscan.m4: New file. + * lib/autoconf/autoconf.m4: Include it. + * lib/autoconf/functions.m4: Use AN_FUNCTION for all the functions + that were listed in the original autoscan.list. + * lib/autoconf/headers.m4: Similarly with headers. + * lib/freeze.mk (autoconf_m4f_dependencies): Add autoscan.m4. + (.m4.m4f): Don't pass --prepend-include, since that's done by + tests/autom4te itself. + * lib/autoscan/Makefile.am: Include freeze.mk. + (autoscan.list): New target --this file is no longer a source. + (autoscan.pre): New file. + +2002-09-28 Akim Demaille + + * bin/autoscan.in (@kinds): Make them singular. + Adjust all uses. + (&init_tables): When --debug, report the list of rules to ease + tracking changes in autoscan.list. + * lib/autoscan/autoscan.list (function): Strip comments, sort. + +2002-09-28 Akim Demaille + + * lib/autoscan/functions, lib/autoscan/headers, + * lib/autoscan/identifiers, lib/autoscan/makevars, + * lib/autoscan/programs: Merge into... + * lib/autoscan/autoscan.list: this. + * bin/autoscan.in (&init_tables): Adjust. + +2002-09-28 Akim Demaille + + * lib/autoscan/functions, lib/autoscan/headers, + * lib/autoscan/identifiers, lib/autoscan/makevars, + * lib/autoscan/programs: Make the `kind' explicit, i.e., each + `functions' line is now prefixed with `function:'. + * bin/autoscan.in (&init_tables): Adjust. + +2002-09-28 Akim Demaille + + From now on, autoscan files must always map a macro name to a + word: there is no `default' macro for autoscan. + + * bin/autoscan.in (&init_tables): Reject entries with no macro at + all. + * lib/autoscan/functions, lib/autoscan/headers: Make the macro + explicit. + +2002-09-28 Akim Demaille + + * bin/autoscan.in (%c_keywords): Remove. + (&used): Keep only track of the words we might be interested in. + (&output_kind): It is no longer needed to look for non active + checks. + +2002-09-27 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_MBRTOWC): New, stolen from + jm_FUNC_MBRTOWC, by Paul Eggert, from the Coreutils 4.5.1. + * lib/autoscan/functions: Adjust. + * doc/autoconf.texi (Particular Functions): Adjust. + +2002-09-27 Akim Demaille + + * doc/autoconf.texi (Limitations of Usual Tools): Some about mv + from /tmp. + Thanks to Bill Moseley and Paul Eggert. + * lib/m4sugar/m4sh.m4 (AS_TMPDIR): $2 is the directory into which + the tmpdir must be created. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Have the tmp + dir be in the build tree, instead of $TMPDIR. + +2002-09-27 Akim Demaille + + * bin/autoscan.in: Improve the comments. + (&parse_args): Drop obsolete undocumented options. + (&output_kind): Output warnings. + * lib/autoscan/functions: (dcgettext): Now trigger AM_GNU_GETTEXT. + (getwd): Trigger a warning. + +2002-09-26 Akim Demaille + + * bin/autoreconf.in: Clarify that -s is meaningless without -i. + Reported by Ralf Corsepius. + * doc/autoconf.texi (autoreconf Invocation): Likewise. + +2002-09-26 Akim Demaille + + Single suffix rules and seperated dependencies are not portable. + + * doc/autoconf.texi (Installation Directory Variables): Update. + (Limitations of Make): Some about `Single Suffix Rules and + Separated Dependencies'. + * bin/Makefile.am (autoconf, autoheader, autoreconf, autoupdate) + (ifnames, autoscan, autom4te): Un-factor into several rules. + +2002-09-25 Paul Eggert + + * BUGS (Interoperability bugs): New section. Mention libtool + 1.4.2, configure.ac, and AC_CONFIG_AUX_DIR interoperability bug. + +2002-09-24 Paul Eggert + + Fix a portability bug reported by Alexandre Duret-Lutz: Solaris 8 + make handles suffix-rules differently from GNU make. + + * bin/Makefile.am (SUFFIXES, .in): Remove. + (autoconf autoheader autoreconf autoupdate ifnames autoscan autom4te): + Move the body of the old .in rule here. + +2002-09-16 Akim Demaille + + i960 compilers create `b.out' files by default. + Reported by Ralf Corsepius. + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT): Remove b.out files. + (_AC_COMPILER_EXEEXT_DEFAULT): Adjust to b.out. + +2002-09-13 Paul Eggert + + * doc/autoconf.texi (Particular Headers): Remove obsolete + reference to `struct timezone' in the description of + AC_HEADER_TIME. + +2002-09-13 Akim Demaille + + Version 2.54. + + * config/config.sub, config/config.guess: Update. + * Makefile.maint: Update from bits of the Coreutils 4.5.1. + * Makefile.am: Adjust. + +2002-09-13 Akim Demaille + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Suggest + reading config.log when the compiler is rejected. + Suggested by Guido Draheim. + +2002-09-13 Akim Demaille + + * bin/autoreconf.in: Don't use Cwd::chdir, since in its internals + (chdir_init) might hang when stat'ing mounted directories. + Reported by Vance Shipley. + +2002-09-12 Akim Demaille + + * bin/autoscan.in (&parse_args): Pass a reference to the lists, not + the lists. + +2002-09-12 Akim Demaille + + * doc/autoconf.texi (Defining Symbols): Present two different + prototypes for AC_DEFINE and AC_DEFINE_UNQUOTED to emphasize the + difference between 1 argument calls, and 2-3 argument calls. + +2002-09-12 Peter Eisentraut + + * doc/autoconf.texi: Review grammar and punctuation. + +2002-09-11 Paul Eggert + + * doc/autoconf.texi: Fix minor formatting, spelling, and + grammatical typos. + (Defining Symbols): Explain that AC_DEFINE(var) defaults to 1, but + AC_DEFINE(var,,description) does not; and the AC_DEFINE(var) case + is obsolescent. + +2002-09-11 Akim Demaille + + * doc/autoconf.texi (Questions): Rename as... + (FAQ): this. + (Defining Directories): New. + +2002-09-09 Akim Demaille + + * doc/autoconf.texi (Making testsuite Scripts): Update. + Suggested by Nishio Futoshi. + +2002-09-09 Koji Arai + + * doc/autoconf.texi (Making testsuite Scripts): Use `@@' where a + plain `@' is wanted. + +2002-09-09 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Keep the + `duplicates', since the algorithm was too naive and could keep + `--prefix=1 --prefix=2 --prefix=1' as `--prefix=1 --prefix=2', and + keep `--prefix foo --prefix bar' as `--prefix foo bar'. + Reported by Ralf Corsepius. + * tests/torture.at (Configuring subdirectories): Exercise these + cases. + +2002-09-09 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_GETLOADAVG): Use $srcdir when + looking for a replacement file. + * lib/autoconf/general.m4 (AC_CHECK_DECLS): Check that the + directory is relative. + * doc/autoconf.texi (Generic Functions): Clarify the replacement + directory definition. + Reported by Andreas Schwab and Jim Meyering. + +2002-09-06 Akim Demaille + + * doc/autoconf.texi (Setting Output Variables): Clarify what + precious variables are. + Suggested by Pontus Skoeld. + +2002-09-05 Akim Demaille + + * bin/Makefile.am (autoconf, autoheader, autoreconf, autoupdate) + (ifnames, autoscan, autom4te): Since we don't only depend on + configure.ac variables (such as VERSION etc.), but also on prefix + and so forth, depend on Makefile, not configure.ac. + Reported by Alexandre Duret-Lutz. + * doc/autoconf.texi (Installation Directory Variables): Adjust. + +2002-09-05 Kevin Ryde + + * doc/autoconf.texi (Limitations of Make): HP-UX trailing backslashes + doesn't seem to be confined to ia64, just say "some versions". + +2002-09-04 Akim Demaille + + * Makefile.am, doc/Makefile.am: Remove pdf targets, handled by + Automake 1.6c. + * Makefile.am (maintainer-clean-local): Remove. + (MAINTAINERCLEANFILES): Remove COPYING. + +2002-09-03 Paul Eggert + + * doc/autoconf.texi (Configuration Commands): Remove obsolete + example for AC_CONFIG_COMMANDS_PRE. Problem reported by Marcus + Brinkmann. + +2002-09-03 Akim Demaille + + * configure.ac: Bump to 2.53d. + * Makefile.am (AUTOMAKE_OPTIONS): Require 1.6c, i.e., CVS Automake + as of today, on Automake's team suggestion. + +2002-09-03 Akim Demaille + + Version 2.53c. + +2002-09-02 Akim Demaille + + * bin/autom4te.in (parse_args): Don't honor AUTOM4TE_PATH and + SITE_MACRO_DIR. + * configure.ac: Disable SITE_MACRO_DIR. + +2002-09-02 Jim Meyering + + * doc/autoconf.texi (AC_SYS_POSIX_TERMIOS): Reflect renaming: s/am/ac/, + i.e., change am_cv_sys_posix_termios to ac_cv_sys_posix_termios. + Also, tweak grammar: s/make sure to/be sure to/. + +2002-09-02 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): Explain why logical + directory names are generally preferable to physical names. + +2002-09-02 Akim Demaille + + * lib/Autom4te/General.pm (&update_file): s/die/error/. + Reported by Raja R. Harinath. + * bin/autoheader.in, bin/autoreconf.in, bin/autoscan.in, + * bin/autoupdate.in: Use error instead of die. + +2002-09-01 Paul Eggert + + * tests/mktests.sh (ac_exclude_egrep, au_exclude_egrep): Use + ordinary shell concatenation rather than echo+tr+sed command that + runs afoul of a long-line-related sed bug in Solaris 8. + + * bin/autoheader.in (parse_args): --warning -> --warnings. + + * bin/autoconf.as: Work even if "ls" outputs "FOO not found" to + stdout, as traditional "ls" does. + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT, + _AC_COMPILER_EXEEXT_O): Likewise. + * doc/autoconf.texi (Limitations of Usual Tools): Add "ls". + + * bin/autoconf.as: Add --prepend-include option. This patch was + applied to bin/autoconf.in in the 2002-07-17 patch by Mark D. Roth, + but bin/autoconf.in is generated automatically from bin/autoconf.as. + + * bin/autoconf.in, configure: Regenerate. + + * doc/autoconf.texi (Special Shell Variables): Mention + ENV, MAIL, MAILPATH, PS1, PS2, PS4. Index PWD. + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Unset ENV, MAIL, + MAILPATH and set PS1, PS2, PS4 to default values, to work + around bug in pre-3.0 UWIN ksh reported by Bruce Lilly. + For LC_ALL etc, first try to set to "C" as POSIX requires and as + the Autoconf documentation specifies; fall back to "unset" only if + this fails. Use a shell for-loop for this rather than an m4 loop, + to shorten the output script. + +2002-08-30 Paul Eggert + + * doc/autoconf.texi (Special Shell Variables): Mention POSIX + 1003.1-2001's requirements for CDPATH. Give a simpler workaround + for the CDPATH problem. Document PWD. + (Limitations of Builtins): Document the problem that "cd $foo" and + "ls $foo" may refer to different directories in shells conforming + to POSIX 1003.1-2001. Use PS1 rather than CDPATH for "unset" + example, since the old example is now out of date. + + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): Reject FOO if "cd + FOO" and "ls FOO" talk about different directories; this catches + problems when POSIX 1003.1-2001 "cd" fails due to symlink + spaghetti. + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Use AS_UNSET instead + of rolling our own unset. + (_AS_PREPARE): $as_unset CDPATH instead of AS_UNSETting it, since + in practice we needn't worry about CDPATH if unset doesn't work. + + * Makefile.in, aclocal.m4, bin/Makefile.in, + config/Makefile.in, doc/Makefile.in, lib/Makefile.in, + lib/Autom4te/Makefile.in, lib/autoconf/Makefile.in, + lib/autoscan/Makefile.in, lib/autotest/Makefile.in, + lib/emacs/Makefile.in, lib/m4sugar/Makefile.in, man/Makefile.in, + tests/Makefile.in: Regenerate with Automake 1.6.3. + + * config/config.guess, config/config.sub, config/mkinstalldirs: + Update. + + * configure: Regenerate with self. + +2002-08-30 Kevin Ryde + + * doc/autoconf.texi (Limitations of Usual Tools): Notes on "cc" + default output. + +2002-08-29 Rainer Orth + + * bin/autom4te.in (Request::load): Correctly test for "do" read + failure. + +2002-08-29 Akim Demaille + + * lib/Autom4te/General.pm (&xqx): New. + (&xsystem): Use WIFEXITED and WEXITSTATUS instead of decoding $? by + hand, which is not portable. + (&error): New. + * bin/autom4te.in: Use them. + Use &error instead of die. + * tests/m4sugar.at (m4_warn, m4_require: circular dependencies): + Adjust. + +2002-08-17 Paul Eggert + + * lib/autoconf/fortran.m4 (AC_PROG_F77): Remove fc from the + default list of compilers to try, since it was long ago superseded + by the ksh fc builtin. Suggested by Steven G. Johnson. + +2002-07-31 Alexandre Duret-Lutz + + * doc/autoconf.texi (Invoking autom4te): End the option table, + fixing a bug introduced by the previous patch. + (Limitations of Make): Add a 'target lookup' subentry in the + 'VPATH' entry. Rewrite all `make' occurences as `@command{make}'. + +2002-07-29 Mark D. Roth + + * bin/autom4te.in: Remove --include-envvar and --site-macro-subdir + options and use $AUTOM4TE_PATH. + * doc/autoconf.texi: Remove documentation of autom4te + --include-envvar and --site-macro-subdir options and document + use of $AUTOM4TE_PATH. + * lib/autom4te.in: Remove --include-envvar and --site-macro-subdir + arguments from each language section. + +2002-07-29 Paul Eggert + + * doc/install.texi: Include copyright symbol in copyright notice. + + * Makefile.am (MAKEINFO): Remove; it's a user-specified macro. + Replace with: + (AM_MAKEINFOFLAGS): New macro. + * doc/Makefile.am (MAKEINFO, AM_MAKEINFOFLAGS): Likewise. + * Makefile.am (INSTALL): Use the new macros. + Use -o rather than --output, since "missing" does not grok --output. + +2002-07-25 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Escaped newlines in + comments do not always work. Never trust the exit status of + `make -k'. + +2002-07-24 Kevin Ryde + + * doc/autoconf.texi (Limitations of Make, Making testsuite Scripts): + Untabify, since tabs are not enjoyed by texi2dvi and makeinfo. + +2002-07-23 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): + Use PATH="/nonexistent;.", not PATH=".;.", as FreeBSD ksh2002 + apparently treats PATH="nonexistent" as if it contained ".". + Bug reported by Stefan `Sec' Zehl. + +2002-07-22 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Mention the special + handling of the obj/ directory by BSD make. + +2002-07-20 Kevin Ryde + + * doc/autoconf.texi (Limitations of Make): Add HP-UX IA-64 trailing + backslashes. + +2002-07-19 Akim Demaille + + * doc/autoconf.texi (Function Portability): `exit'. + (Programming in M4sh): Ethymology of M4sh. + +2002-07-19 Akim Demaille + + * doc/autoconf.texi (AC_LIBOBJ vs LIBOBJS): More about $U. + +2002-07-18 Akim Demaille + + Version 2.53b. + +2002-07-18 Akim Demaille + + * config/config.guess, config/config.sub: Update. + +2002-07-18 Akim Demaille + + Handle LIBOBJS and LTLIBOBJS once for all, including Libtool's and + Automake's parts. + + * lib/autoconf/general.m4 (_AC_LIBOBJS_NORMALIZE): New. + * lib/autoconf/status.m4 (AC_OUTPUT_COMMANDS_PRE): Call it. + * tests/semantics.at (AC_REPLACE_FUNCS): Adjust. + +2002-07-18 Akim Demaille , + Alexandre Duret-Lutz + + * lib/autoconf/status.m4 (_AC_OUTPUT_HEADERS): Install + _AC_AM_CONFIG_HEADER_HOOK for Automake 1.7. + +2002-07-17 Russ Allbery + + * doc/autoconf.texi (Initializing configure): Clarify the + description of the tarname default. + +2002-07-17 Andreas Buening + + * lib/autoconf/functions.m4 (AC_FUNC_FORK): Don't set + ac_cv_func_fork_works before running _AC_FUNC_FORK, do it if the + latter was not run. + +2002-07-17 Akim Demaille + + * lib/Autom4te/General.pm (find_file): Browse the directories in + the order they are given. + +2002-07-17 Akim Demaille + + * tests/wrapsh.as, tests/wrappl.as: Merge into... + * tests/wrapper.as: this. + * tests/Makefile.am, configure.ac: Adjust. + +2002-07-17 Mark D. Roth + + * configure.ac: Add --enable-site-macro-dir option. + * bin/Makefile.am: Expand @SITE_MACRO_DIR@. + * bin/autom4te.in: Add --prepend-include, --include-envvar, and + --site-macro-subdir options. + * bin/autoconf.in: Add --prepend-include option. + * bin/autoheader.in: Add --prepend-include option. + * bin/autoreconf.in: Add --prepend-include option. + * bin/autoscan.in: Add --prepend-include option. + * bin/autoupdate.in: Add --prepend-include option. + * doc/autoconf.texi: Document use of $AC_MACRO_PATH and site + macro directory, remove note that include path directories are + used in reverse order, and document --prepend-include option. + * lib/autom4te.in: Use --prepend-include instead of --include. + * tests/wrapsh.in: Use --prepend-include instead of --include. + +2002-07-17 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): `_' is allowed in + tarnames. + * doc/autoconf.texi (Initializing configure): Adjust. + +2002-07-17 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_REALLOC, _AC_FUNC_REALLOC) + (_AC_FUNC_MALLOC): New. + (AC_FUNC_MALLOC): Use the latter. + Define HAVE_MALLOC to 0 if broken. + * doc/autoconf.texi (Particular Functions): Adjust. + +2002-07-16 Akim Demaille + + * lib/autoconf/c.m4 (AC_C_BACKSLASH_A): New. + * doc/autoconf.texi (C Compiler): Adjust. + +2002-07-09 Akim Demaille + + * doc/autoconf.texi: Properly set the ``header'' part. + +2002-07-09 Akim Demaille + + * doc/autoconf.texi (Systemology): Some about Darwin. + +2002-07-09 Alexandre Duret-Lutz + + * lib/autoconf/specific.m4 (AC_CYGWIN, AC_EMXOS2, AC_MINGW32): + Don't use AC_REQUIRE in AU_DEFUN. + +2002-07-09 Art Haas + + * doc/autoconf.texi: Use @enddots{} or @dots{} where appropriate. + +2002-07-02 Alexandre Duret-Lutz + + * bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in, + bin/autoupdate.in, bin/ifnames.in, lib/Autom4te/General.pm, + lib/Autom4te/Struct.pm, lib/Autom4te/XFile.pm: Add local variables + so that Emacs setups GNU style for perl-mode and cperl-mode. + +2002-06-27 Paul Eggert + + * config/install-sh: Quote $src. Prefer || to test's -o option, + as per "Limitations of Builtins". + * tests/atspecific.m4 (AT_CHECK_ENV): Likewise, for && vs test -a. + * tests/semantics.at (AC_C_BIGENDIAN): Likewise. + + * tests/mktests.sh: Use grep instead of fgrep, as per + "Limitations of Builtins". + +2002-06-15 Paul Eggert + + * tests/wrapsh.as (AUTOCONF, AUTOHEADER, AUTOM4TE, AUTOM4TE_CFG, + autom4te_perllibdir): Set to top build dir or src dir as appropriate, + so that we consistently test the just-built programs. + * tests/wrappl.as: Likewise. + +2002-06-12 Paul Eggert + + * bin/autoconf.as (AUTOM4TE): Default to a fully qualified path + name, so that symlinks to 'autoconf' work properly. Bug reported + by Bruno Haible. + * bin/autoheader.in (AUTOM4TE): Likewise. + * bin/autoreconf.in (autoconf, autoheader): Likewise. + * bin/autoscan.in (autom4te): Likewise. + * bin/autoupdate.in (autom4te): Likewise. + + * lib/autoconf/functions.m4 (_AC_LIBOBJ_FNMATCH): Also check for + btowc, to fix a portability bug with diffutils-2.8.2/lib/fnmatch.c + on Solaris 2.5.1. + +2002-06-11 Andreas Schwab + + * doc/autoconf.texi: Add more dir entries. + +2002-06-10 Alexandre Duret-Lutz + + * bin/autom4te.in ($cache): Don't define using `$me', the name + of the cache should not depend on the name under which autom4te + was installed. + +2002-06-07 Akim Demaille + + * tests/tools.at (autoconf: forbidden tokens, basic) + (autoconf: forbidden tokens, exceptions): Adjust to the change of + words in autom4te.in. + +2002-06-07 Peter Eisentraut + + * lib/autoconf/c.m4 (AC_LANG_PROGRAM(C)): Use + _AC_LANG_PROGRAM_C_F77_HOOKS. + +2002-06-07 Akim Demaille + + * lib/autoconf/functions.m4 (AC_REPLACE_FUNC_FNMATCH): Typo, + rename as... + (AC_REPLACE_FNMATCH): this. + * tests/mktests.sh (exclude_list): Exclude AC_REPLACE_FNMATCH, + AC_FUNC_FNMATCH_GNU. + +2002-06-07 Akim Demaille + + * doc/autoconf.texi (Systemology): Point to Tru64 docs, and the + Rosetta Stone for Unix. + +2002-06-07 Akim Demaille + + * bin/autom4te.in (warn_forbidden): When rejecting a token, + suggest m4_pattern_allow. + Suggested by Adam J. Richter. + +2002-06-07 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Initialize + ac_config_libobj_dir. + (AC_CONFIG_LIBOBJ_DIR): New. + * lib/autoconf/functions.m4 (_AC_FUNC_FNMATCH): Split into... + (_AC_FUNC_FNMATCH_IF, _AC_LIBOBJ_FNMATCH): these. + Use ac_config_libobj_dir to find the replacement files. + (AC_FUNC_FNMATCH, AC_FUNC_FNMATCH_GNU): Split into... + (AC_FUNC_FNMATCH, AC_FUNC_FNMATCH_GNU, AC_REPLACE_FNMATCH) + (AC_REPLACE_FNMATCH_GNU): these. + (AC_FUNC_GETLOADAVG): Use ac_config_libobj_dir. + * doc/autoconf.texi (Particular Functions, Generic Functions): Adjust. + * tests/mktests.sh (ac_exclude_list): Don't check + AC_FUNC_GETLOADAVG as it requires getloadavg.c which is not shipped. + +2002-06-06 Paul Eggert + + * lib/autoconf/status.m4 (_AC_OUTPUT_LINKS): Fall back on cp + if ln doesn't work. + * NEWS: Likewise. + * doc/autoconf.texi (Configuration Links): Likewise. + (Limitations of Usual Tools): Prefer $(LN_S) to ln -s || ln. + +2002-06-05 Paul Eggert + + * config/config.guess, config/config.sub, config/texinfo.tex: + Update from masters. + +2002-05-29 Paul Eggert + + * bin/autom4te.in ($m4): Do not assume that egrep and fgrep exist. + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Likewise. + * lib/autoconf/general.m4 (_AC_RUN_LOG_STDERR, AC_EGREP_CPP): + Likewise. + * lib/autoconf/Makefile.am (check-local): Likewise. + * lib/autoconf/status.m4 (AC_CONFIG_HEADER): Likewise. + * lib/autoconf/types.m4 (commentary only): Likewise. + * lib/autotest/general.m4 (AT_INIT, AT_CHECK): Likewise. + * lib/autotest/Makefile.am (check-local): Likewise. + * lib/m4sugar/Makefile.am (check-local): Likewise. + * tests/atspecific.m4 (AT_CONFIGURE_AC, AT_CHECK_DEFINES): Likewise. + * tests/mktests.sh (egrep): New var; use it instead of plain egrep. + + * lib/autoconf/programs.m4 (AC_PROG_EGREP, AC_PROG_FGREP): New macros. + * doc/autoconf.texi (Particular Programs): Document them. + (Limitations of Usual Tools): Warn that egrep and fgrep may not exist. + * NEWS: Likewise. + +2002-05-27 Paul Eggert + + * lib/autoconf/types.m4 (AC_TYPE_MBSTATE_T): New macro. + * NEWS, doc/autoconf.texi (Particular Types): Document it. + * lib/autoconf/functions.m4 (_AC_FUNC_FNMATCH): Require it + instead of AC_MBSTATE_T, which never existed. + +2002-05-23 Akim Demaille + + * doc/autoconf.texi (Hosts and Cross-Compilation): Specify the + version of Autoconf that is discussed. + +2002-05-22 Paul Eggert + + * lib/autoconf/fortran.m4 (AC_PROG_F77): Remove cf77 and cft77 + from the default list of compilers to try. Suggested by + Kate Hedstrom. + * NEWS: Document the above. + * doc/autoconf.texi (Fortran 77 Compiler): Don't suggest cf77. + +2002-05-17 Paul Eggert + + * lib/autoconf/types.m4 (AC_CHECK_MEMBER): Work correctly even if + the member is itself an aggregate. Bug reported by Sergey Poznyakoff. + This improves on an earlier suggestion by H. Peter Anvin. + +2002-05-16 Paul Eggert + + AC_FUNC_FNMATCH now tests only for POSIX compatibility. + AC_FUNC_FNMATCH_GNU also tests for GNU extensions. + Both macros now accept an optional source-dir arg. + New macro AC_GNU_SOURCE to define _GNU_SOURCE. + + * NEWS: Document this. + * doc/autoconf.texi (Particular Functions, UNIX Variants): Likewise. + + * lib/autoconf/functions.m4 (_AC_FUNC_FNMATCH): New macro. + (AC_FUNC_FNMATCH): Use it. Test only for POSIX conformance, + not for GNU extensions; this undoes part of the 2000-11-03 change, + reverting to 2.13-compatible behavior. + Add new optional argument DIR. + (AC_FUNC_FNMATCH_GNU): New macro. + + * lib/autoconf/specific.m4 (AC_GNU_SOURCE): New macro. + +2002-05-08 Paul Eggert + + * lib/autoconf/headers.m4 (AC_HEADER_TIOCGWINSZ): + Don't require AC_SYS_POSIX_TERMIOS. The test is unnecessary, + and it causes a 'test' syntax error if it fails. + Bug reported by Stephen Gildea. + + * lib/autoconf/functions.m4 (AC_FUNC_SETVBUF_REVERSED): + If prototypes are supported, use them to check this at compile-time, + instead of trying to check it at run-time. If we must do a run-time + check, assume that setvbuf is standard when cross-compiling, as + nonstandard setvbuf occurs only on ancient and unlikely hosts. + Bug reported by Paul D. Smith. + + * lib/autoconf/functions.m4 (AC_FUNC_GETLOADAVG): Add optional + argument specifying location of getloadavg.c. This removes a + FIXME. This idea was taken from Jim Meyering's implementation in + textutils. + * doc/autoconf.texi (Particular Functions): Document this. + Also, mention HAVE_NLIST_H rather than NLIST_STRUCT, since + that's what the code does; this fixes a bug reported by + Paul D. Smith. + +2002-05-03 Akim Demaille + + * bin/autoreconf.in (autoreconf): Rewrite to use Gettext's + autopoint instead of gettextize. + ($uses_alocal): Rename as... + ($uses_aclocal): this. + * doc/autoconf.texi (autoreconf Invocation): Adjust. + Suggested by Bruno Haible. + +2002-05-03 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_map_sep): New. + +2002-04-29 Paul Eggert + + * bin/autoreconf.in (autoreconf): Don't age aclocal.m4's input + files to be 1 second older; just set them to be the same time. + Also, sleep 1 second after the first aclocal, to work around + problems with sub-second time stamps on the input files. + +2002-04-29 Thien-Thi Nguyen + + * doc/autoconf.texi: Mention "set -e -x" lossage + under node "Limitations of Builtins". + +2002-04-29 Akim Demaille + + * doc/install.texi: Better wording for setting variables when + running configure. + From Christian Cornelssen. + +2002-04-29 Akim Demaille + + * tests/m4sh.at (LINENO): If testsuite itself is rewritten because + of lack of $LINENO support, then the test will compare the $LINENO + in testsuite vs. the lineno in the test file. This is wrong, of + course. + Be sure to protect it. + Reported by Patrick Welche. + +2002-04-25 Akim Demaille + + * doc/autoconf.texi (Obsolete Macros): Typo. + Reported by Vladimir Volovich. + +2002-04-25 Akim Demaille + + * bin/autoreconf.in (autoreconf): Don't let aclocal.m4 be older + than some of the input files, hence, on the second run of aclocal, + if some of its input are younger, make them older. + Suggested by Paul Eggert. + +2002-04-25 Akim Demaille + + * doc/autoconf.texi (Limitations of Usual Tools): sed and `!'. + Thanks to Paul Eggert. + +2002-04-25 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Let ac_subst_files + and ac_subst_vars be sh variables containing the list of + AC_SUBST_FILES'ed and AC_SUBST'ed identifiers. Output them in the + DEFAULT diversion. + (_AC_INIT_PREPARE): Use them to log them. + (_AC_SUBST, _AC_SUBST_SED_PROGRAM): Remove. + (AC_SUBST, AC_SUBST_FILE): Instead of buliding the + _AC_SUBST_SED_PROGRAM, store the list of output files/variables in + _AC_SUBST_FILES and _AC_SUBST_VARS. + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES): Adjust. + +2002-04-24 Akim Demaille + + * bin/autoreconf.in (autoreconf): Run automake after autoconf and + autoheader, so that automake does not complain about a missing + config.h.in that was to be created. + +2002-04-23 Akim Demaille + + * bin/autoheader.in (parse_args): --warning takes an argument. + Fixes PR/220. + +2002-04-22 Peter Eisentraut + + * lib/autoconf/general.m4 (_AC_RUN_IFELSE): Remove gmon.out + and bb.out when cleaning up. + +2002-04-22 Akim Demaille + + Version 2.53a. + +2002-04-22 Akim Demaille + + * tests/m4sh.at (LINENO): Fix the Zsh skip pattern. + +2002-04-22 Akim Demaille + + * doc/autoconf.texi (Pretty Help Strings): Remove a spurious + comma. + Reported by Gregory Giannoni. + +2002-04-22 Akim Demaille + + * tests/m4sh.at (LINENO): Skip the test if LINENO cannot be unset. + Fixes false failures on Darwin. + +2002-04-21 Paul Eggert + + * TODO, bin/autoupdate.in, doc/autoconf.texi, + lib/autoconf/general.m4, lib/autoconf/libs.m4, + lib/autoconf/status.m4, lib/m4sugar/m4sugar.m4, tests/m4sh.at, + tests/tools.at: Minor spelling and grammar fixes. + +2002-04-20 Paul Eggert + + * doc/autoconf.texi (Shell Substitutions): Fix typos in yesterday's + ZSH_VERSION fixes. Bug reported by Raja R Harinath. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * tests/atgeneral.m4 (AT_INIT): Likewise. + +2002-04-19 Paul Eggert + + * NEWS, TODO, bin/autom4te.in, bin/autoreconf.in, bin/autoupdate.in, + doc/autoconf.texi, lib/freeze.mk, lib/Autom4te/Struct.pm, + lib/autoconf/autoheader.m4, lib/autoconf/c.m4, + lib/autoconf/functions.m4, lib/autoconf/general.m4, + lib/autoconf/lang.m4, lib/autoconf/libs.m4, lib/autoscan/identifiers, + lib/autotest/general.m4, lib/m4sugar/m4sh.m4, tests/atgeneral.m4, + tests/atspecific.m4, tests/semantics.at, tests/torture.at: + Minor spelling and grammar fixes. + + * doc/autoconf.texi: Follow the outline suggested in the GNU + Sample Texts sections of the Texinfo 4.2 manual. Most + importantly, this makes sure that the copyright notices appear in + all output formats. You probably need Texinfo 4.2 to generate + the manual now. + + Fix some bugs when using "$@" when there might be zero positional + arguments in cases where this matters. + + * bin/autoconf.as: Rewrite so that the problem does not come up. + * lib/autoconf/programs.m4 (AC_CHECK_PROG): Likewise. + * lib/autoconf/status.m4 (AC_OUTPUT): Likewise. + * lib/autotest/general.m4 (AT_INIT): Likewise. + + * bin/autoheader.in: Use 'case' statement to work around problem. + * bin/auto4mte.in: Likewise. + * bin/autoreconf.in: Likewise. + * bin/autoscan.in: Likewise. + * bin/autoupdate.in: Likewise. + * bin/ifnames.in: Likewise. + + * doc/autoconf.texi (Shell Substitutions): Document the problem. + + * lib/autotest/general.m4 (AT_INIT): + Use Zsh alias to work around problem. + * tests/atgeneral.m4 (AT_INIT): Likewise. + + * tests/c.at: We can't have zero arguments, so remove workaround + that is not portable to Zsh. + +2002-04-19 Alexandre Duret-Lutz + + * bin/autoupdate.in (handle_autoconf_macros): Honor AU_DEFUNs + from aclocal.m4 too. + +2002-04-12 Akim Demaille + + * tests/wrappl.as: New, M4sh precursor of wrappl.in. + +2002-04-10 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Install the Zsh + workaround for ${1+"$@"}. + * doc/autoconf.texi (Shell Substitutions): Explain it. + From Oliver Kiddle and Peter Stephenson. + + Have M4sh perform minimal shell sanitizing. + + * lib/m4sugar/m4sh.at (AS_SHELL_SANITIZE): Split the `_AS_PREPARE_*' + part into... + (_AS_PREPARE): this new macro. + (AS_PREPARE): New. + (AS_INIT): Invoke AS_SHELL_SANITIZE. + * tests/m4sh.at (AT_DATA_LINENO): Use _AS_PREPARE. + + Adjust Autoconf and Autotest. + + * lib/autoconf/general.m4 (_AC_INIT_DEFAULTS): Don't invoke + AS_SHELL_SANITIZE, AS_INIT did it, but invoke AS_PREPARE. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): + Invoke _AS_PREPARE (not AS_PREPARE) in addition to + AS_SHELL_SANITIZE. + + Use this M4sh to generate Autoconf's shell scripts. + + * tests/wrapsh.as: New, precursor of wrapsh.in. + * tests/Makefile.am: Include lib/freeze.mk to get the dependencies + on Autotest and M4sh. + ($(TESTSUITE)): Use $(autotest_m4f_dependencies). + (wrapsh.in): New target. + * bin/autoconf.as: New, precursor of autoconf.in. + (autoconf.in): New target. + +2002-04-09 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Mention the issue + with indented comments in rules. + +2002-04-09 Andreas Schwab + + * lib/autoconf/status.m4 (_AC_SRCPATHS): Handle empty + ac_top_builddir when setting ac_abs_top_builddir. + +2002-04-06 Kevin Ryde + + * doc/autoconf.texi (Systemology): Add link to Unix V7 online docs. + (Portable Shell): Cross reference to Systemology. + +2002-04-05 Akim Demaille + + * bin/autoreconf.in (autoreconf): Be sure to accumulate the + directories when descending in a SUBDIRS. + Reported by Ezra Peisach. + +2002-04-04 Andreas Schwab + + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Only simplify if path + contains no literal separators. + +2002-04-03 Akim Demaille + + * lib/autoconf/status.m4 (_AC_CONFIG_FILE, _AC_CONFIG_HEADER) + (_AC_CONFIG_COMMAND, _AC_CONFIG_LINK): New. + Use dnl, not the KILL diversion. + Extracted from... + (AC_CONFIG_FILES, AC_CONFIG_HEADERS, AC_CONFIG_COMMANDS) + (AC_CONFIG_LINKS): here. + Adjust. + Don't use the KILL diversion, as it kills spurious output, which + results in failures being hidden. + Use m4_defn where appropriate. + (AC_CONFIG_IF_MEMBER): Kill the real bug: a spurious parenthesis + after the second argument. + Use m4_defn. + * lib/autom4te.in (Autoconf, Autotest, M4sh): Don't pass --warning + syntax, as it is provided by M4sugar. + * tests/torture.at (Multiple AC_CONFIG_FILES): New. + +2002-04-03 Andreas Schwab + + * lib/m4sugar/m4sugar.m4 (m4_bmatch): Make sure m4_bregexp is not + expanded if $# <= 2. + + * bin/autoreconf.in (autoreconf): Run automake after rerunning + aclocal. + +2002-04-03 Akim Demaille + + * lib/autoconf/lang.m4 (_AC_COMPILER_OBJEXT_REJECT) + (_AC_COMPILER_EXEEXT_REJECT): New. + Also recognize *.bb and *.bbg as compilation byproducts. + (_AC_COMPILER_EXEEXT_DEFAULT, _AC_COMPILER_EXEEXT_O) + (_AC_COMPILER_OBJEXT): Use them. + Fixes Debian #138666. + +2002-04-02 Peter Eisentraut + + Integrate AC_PROG_CC_STDC into AC_PROG_CC. + + * lib/autoconf/c.m4 (AC_PROG_CC_STDC): Rename to _AC_PROG_CC_STDC. + AU_DEFUN old name. Use _AC_COMPILE_IFELSE. + (AC_PROG_CC): Call _AC_PROG_CC_STDC. + (AC_C_INLINE): Do not require AC_PROG_CC_STDC. + (AC_C_CONST): Same. + (AC_C_INLINE): Same. + (AC_C_PROTOTYPES): Same. Require AC_PROG_CC instead. + * doc/autoconf.texi, NEWS: Document. + * tests/mktests.sh (au_exclude_list): Add AC_PROG_CC_STDC and + AC_C_CROSS. + +2002-04-02 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Invoke + _AS_MKDIR_P_PREPARE. + +2002-03-28 Kevin Ryde + + * lib/autoconf/c.m4 (AC_C_INLINE): Test with a typedef return value, + to avoid versions of HP C which don't allow that. + +2002-03-27 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_BASENAME_PREPARE): New macro. + (AS_SHELL_SANITIZE): Invoke it. + (AS_BASENAME): AS_REQUIRE it, and use $as_basename. + +2002-03-26 Akim Demaille + + * doc/autoconf.texi (Portable Shell): Add pointers to FAQs. + +2002-03-26 Akim Demaille + + * doc/autoconf.texi (Introduction): The GNATS base moved. + +2002-03-25 Paul Eggert + + * tests/m4sh.at: Don't rely on "PATH=test:$PATH test-1" working + as POSIX requires, as it doesn't work with Zsh. + * doc/autoconf.texi (Assignments): Document the problem. + +2002-03-25 Alexandre Duret-Lutz + + * doc/autoconf.texi (Limitations of Make): Mention more issue + about VPATH, overriding of macros in sub-makes, and handling of + SHELL. + +2002-03-21 Paul Eggert + + * doc/autoconf.texi (Here-Documents): Mention Solaris 8 dtksh + problem with here-document buffer boundaries. + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Unset ENV and BASH_ENV + when reinvoking the shell, to work around problems with installers + who put strange things like "cd" commands in their environments. + +2002-03-19 Akim Demaille + + * tests/semantics.at (AC_C_BIGENDIAN): s/unknow/unknown/. + From Aaron Ucko. + +2002-03-19 Akim Demaille + + * bin/autoscan.in (scan_file): Specify the location in `&used' + invocations. + From Nicolas Joly. + +2002-03-19 Akim Demaille + + * doc/autoconf.texi: Adjust @code/@command, @xref/@ref usage. + From Nishio Futoshi. + +2002-03-19 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_define_default, m4_fst, m4_map): New. + +2002-03-18 Paul Eggert + + * doc/autoconf.texi (Programming in M4sh): Add AS_MKDIR_P. + (Limitations of Usual Tools): Add mkdir section. + + * lib/m4sugar/m4sh.m4 (_AS_MKDIR_P_PREPARE): New macro. + (AS_MKDIR_P): Require it. Use mkdir -p if available, falling + back on AS_DIRNAME to compute prefixes otherwise; this is + roughly what mkinstalldirs does. That way, we need not have + our own filename disassembler. The old disassembler did not + work with Solaris 8 dtksh, which is ksh Version M-12/28/93d. + + * lib/autotest/general.m4 (AT_INIT, AT_CLEANUP): + Create at_test_all by a series of assignments, + not by a single assignment of a long string. The latter causes ksh + version 11/16/88g to silently misbehave on OpenServer 5.0.6a, + presumably because of a buffer overrun. + +2002-03-14 Paul Eggert + + * lib/autotest/general.m4 (at_times_skip): + Renamed from at_times. Now a boolean. + ksh93 Version M-12/28/93d doesn't like 'x=times; $x'; it + says 'times: not found'. + +2002-03-14 Akim Demaille + + * bin/autoreconf.in (&study_gettextize): New. + (&autoreconf): Handle newest gettextize. + Rerun aclocal if needed. + Suggested by Andreas Schwab. + +2002-03-13 Akim Demaille + + * doc/autoconf.texi (Special Shell Variables): More about IFS. + +2002-03-13 Akim Demaille + + * doc/autoconf.texi (Header Portability): New. + Add information about stdint.h and inttypes.h from Paul Eggert. + +2002-03-13 Akim Demaille + + * doc/autoconf.texi (Limitations of Usual Tools): Some about `cp + -p'. + From Bob Proulx. + +2002-03-12 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_BASENAME_EXPR): AS_REQUIRE, not + m4_require. + +2002-03-11 Andreas Schwab + + * configure.ac: Explicitly check for EMACS since AM_PATH_LISPDIR + does not do it if --with-lispdir is given. + +2002-03-08 Akim Demaille + + Version 2.53. + +2002-03-08 Akim Demaille + + * doc/autoconf.texi (Subdirectories): Clarify that the + subdirectory should exist. + +2002-03-08 Akim Demaille + + * Makefile.am (AUTOMAKE_OPTIONS): 1.6. + +2002-03-08 Akim Demaille + + * bin/autom4te.in (&handle_m4): Do not foreach with `$_' as it + aliases the actual variables, and modifications of the former + affect the latter. + +2002-03-08 Akim Demaille + + * bin/autom4te.in (&handle_m4): Protect us from corrupted file + because of C-c: have m4 output in tmp files, then mv them. + +2002-03-08 Akim Demaille + + * bin/autoconf.in, bin/autoheader.in, bin/autom4te.in, + * bin/autoreconf.in, bin/autoscan.in, bin/autoupdate.in, + * bin/ifnames.in: Copyright update. + +2002-03-08 Akim Demaille + + * doc/autoconf.texi (Invoking autom4te): New. + +2002-03-05 Akim Demaille + + * doc/autoconf.texi (Specifying Names): Clarification suggested by + Kevin Ryde. + +2002-03-05 Akim Demaille + + Version 2.52i. + +2002-03-04 Akim Demaille + + * doc/autoconf.texi (AC_LIBOBJ vs. LIBOBJS): New. + * lib/autoconf/general.m4 (AC_INIT): More informative error + message for LIBOBJ. + +2002-03-04 Akim Demaille + + * lib/freeze.mk ($(build_libdir)/m4sugar/version.m4): New, for + parallel builds. + +2002-03-04 Akim Demaille + + * doc/autoconf.texi (Transforming Names): Equality between target + and host is irrelevant. + (Specifying Names, Canonicalizing): Remove all references to the + backward compatibility hooks. Rather, collect them all into... + (Hosts and Cross-Compilation): this new section. + * doc/install.texi (System Type): Ditto. + * lib/autoconf/general.m4 (AC_CANONICAL_HOST): Explicitly state + that `--host' implies cross-compilation. + +2002-03-04 Akim Demaille + + * doc/autoconf.texi (Evaluation Macros): New. + * lib/m4sugar/m4sugar.m4 (m4_lquote): Remove, it is totally + useless. + (_m4_foreach): Define the variant with immediate evaluation so + that it contains exactly the items, not an expression which + evaluation is the current item. + (m4_re_string, m4_re_word): Don't over quote them. + +2002-03-04 Akim Demaille + + Instead of having stacking `shift's evaluated at the end, let + `foreach' loops immediately evaluate them. + + * lib/m4sugar/m4sugar.m4 (m4_quote, m4_dquote): Use $@ rather than + $*. This is the n-th time I change my mind, but hopefully this is + the last... + (m4_lquote): New. + (m4_text_wrap): Use m4_foreach, which is finally correct _and_ + efficient. + (m4_foreach_quoted, m4_car_quoted, _m4_foreach_quoted): Remove, as + it was only a hack for m4_text_wrap. + (m4_car2): Remove, replaced by... + (m4_cdr): New. + (_m4_foreach): Adjust. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Adjust, and use + m4_bpatsubst for clarification. + +2002-03-04 Akim Demaille + + * doc/autoconf.texi (Changequote is Evil): New. + +2002-03-03 Kevin Ryde + + * doc/autoconf.texi (Portable Shell): Mention 32-byte #! length limit + on old systems like SunOS. + +2002-03-01 Peter Eisentraut + + * lib/autoconf/c.m4, lib/autoconf/fortran.m4, + lib/autoconf/functions.m4, lib/autoconf/general.m4, + lib/autoconf/headers.m4, lib/autoconf/lang.m4, + lib/autoconf/programs.m4, lib/autoconf/status.m4: Improve spelling + of messages. + +2002-02-28 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Suggest a title to the + message to be sent. + +2002-02-28 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Add va_copy and va_list. + +2002-02-25 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_SETPGRP): Fix the test. + From Akinori Musha. + +2002-02-13 Alexandre Duret-Lutz + + * lib/Autom4te/XFile.pm (getline, getlines): New functions, + translate \r\n to \n. + +2002-02-07 Akim Demaille + + Version 2.52h. + +2002-02-07 Akim Demaille + + Fix Autoconf PR/209. + Also reported by Frank Denis. + + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Don't over quote. + +2002-02-07 Akim Demaille + + Fix Autoconf PR/207: + AC_PREFIX_PROGRAM fails with dashed program names + + * lib/autoconf/general.m4 (AC_PREFIX_PROGRAM): Just use a fresh + variable when looking for the prefix program. + Now it also works for shell variables. + +2002-02-07 Akim Demaille + + * doc/autoconf.texi (Limitations of Builtins): More about + case/esac. + +2002-02-06 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_COMMANDS): Don't output empty + case/esac, some shells don't support it. + Reported by Zack Weinberg. + * tests/torture.at (AC_CONFIG_COMMANDS with empty commands): New. + +2002-02-06 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): When handling --keywords, be + sure not to introduce newlines in at_groups. + * lib/autotest/Makefile.am (autotest.m4f): Typo. + +2002-02-06 Akim Demaille + + * tests/torture.at (Configuring subdirectories): Skip if aclocal + is not available. + +2002-02-05 Paul Eggert + + * doc/autoconf.texi (Specific Compiler Characteristics): + Describe HP-UX cc bug workaround more accurately. + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): Cast to long, + not unsigned long. + * tests/semantics.at (AC_CHECK_SIZEOF): Check non-GCC + cross-compilers, too. This undoes some of the most recent change + to this file. + +2002-02-05 Akim Demaille + + * tests/Makefile.am (check_SCRIPTS): Use it, instead of WRAPPERS, + to make sure they are up to date when `check' is run. + +2002-02-05 Akim Demaille + + * doc/autoconf.texi (Making testsuite Scripts): Document + package.m4. + +2002-02-05 Akim Demaille + + * lib/freeze.mk: New. + +2002-02-05 Akim Demaille + + Implement `autom4te --freeze'. + + * bin/autom4te.in (&freeze): New. + * lib/autoconf/autoconf.m4, lib/autotest/general.m4, + * lib/m4sugar/m4sh.m4: Don't include files given by autom4te. + +2002-02-05 Akim Demaille + + * bin/autom4te.in (&parse_args): Implement `frozen files are + optional are the sum of the previous files on the command line'. + Also, pass `--reload-state=' on them, so... + (handle_m4): don't. + * lib/autom4te.in (Autotest, Autoconf): Rely on M4sh. + (M4sh): Rely on M4sugar. + (Autotest, M4sh, M4sugar): Use frozen files. + +2002-01-31 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Accept $4. + * doc/autoconf.texi (Initializing configure): Adjust. + +2002-01-30 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Map non + alphanumeric to `-' instead of `_'. + +2002-01-30 Akim Demaille + + * tests/semantics.at (AC_CHECK_SIZEOF): Split into two tests: one + for plain code, the other for cross-compilation code. The latter + is now run with GCC only. + * doc/autoconf.texi (Compilers and Preprocessors): New. + +2002-01-30 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Support pre-defined + values. + * doc/autoconf.texi (Initializing configure): Explain how to + change AC_INIT default values. + +2002-01-29 Akim Demaille + + * tests/torture.at (Configuring subdirectories): Use configure.in, + so that aclocal 1.4 works. + Reported by Alexandre Duret-Lutz and Larry Schmitt. + +2002-01-28 Akim Demaille + + * doc/autoconf.texi (Writing testsuite.at): AT_CLEANUP no longer + needs an argument. + +2002-01-28 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Don't be ridiculous: adjust + AUTOTEST_PATH *after* it was set. + Don't put `.' in the PATH: the user should be precise and `./' if + needed. In addition, given that the test suite does some `cd', if + `.' is in the path, the `tested programs' sections will report + programs found in the test suite's directory, while during the + tests (performed in their own directory), these programs are no + longer visible. In other words, the results is confusing and + useless. + * tests/m4sh.at: Adjust: don't rely on `.' being in the PATH. + +2002-01-24 Akim Demaille + + Version 2.52g. + +2002-01-24 Akim Demaille + + * bin/autoheader.in, bin/autoconf.in, bin/autoscan.in, + * doc/autoconf.texi: Finally add Akim as an author. + +2002-01-24 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Use PATH_SEPARATOR. + (_AS_PATH_SEPARATOR_PREPARE): Don't expect $SHELL to be + Bourne. Use /bin/sh. + From Andreas Buening. + +2002-01-24 Akim Demaille + + * config/config.guess, config/config.sub, config/texinfo.tex: + Update from masters. + +2002-01-24 Akim Demaille + + * Makefile.am (AUTOMAKE_OPTIONS): 1.5b. + * config/auxdir.m4, config/cond.m4, config/depend.m4, + * config/init.m4, config/install-sh.m4, config/lispdir.m4, + * config/missing.m4, config/sanity.m4, config/select.m4, + * config/strip.m4: Remove, to ease sync'ing with any version of + Automake. + +2002-01-24 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS) + (_AC_INIT_PREPARE): Support -n as --no-create, as documented. + Reported by Geir Ove Myhr. + +2002-01-21 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_MMAP): #Undef malloc. + +2002-01-21 Akim Demaille + + * lib/Autom4te/General.pm (getopt): Use a more GNUish error + message on invalid options. + * bin/autom4te.in (parse_args): Don't use + Autoconf::General::getopt with non valid options. + +2002-01-17 Jim Meyering + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Initialize + $ac_cv_exeext so we don't use an old, invalid, cached value. + +2002-01-11 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_STRNLEN): New, from Jim + Meyering. + * doc/autoconf.texi (Function Portability): Document the strnlen + limitation. + (Particular Functions): Document AC_FUNC_STRNLEN. + * lib/autoscan/functions: Adjust. + +2002-01-06 Akim Demaille + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Don't create + package.m4, since is really depends upon configure.ac, not + configure. + * doc/autoconf.texi (testsuite Scripts): Adjust. + * tests/Makefile.am (package.m4): New. + EXTRA_DIST it since its a source. + +2002-01-06 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PARSE_ARGS): Move the AC_SUBST + of PACKAGE_NAME, PACKAGE_TARNAME, PACKAGE_VERSION, PACKAGE_STRING, + and PACKAGE_BUGREPORT from here... + (_AC_INIT_DEFAULTS): to here, since it is unrelated to the + arguments. + (_AC_INIT_PREPARE): AC_DEFINE these symbols. + * lib/autotest/general.m4: Use AT_PACKAGE_*, not PACKAGE_*. + (AT_INIT): No longer catch `^PACKAGE_(BUGREPORT|STRING)$'. + * tests/tools.at (autoheader): Adjust. + * tests/atspecific.m4 (AT_CHECK_DEFINES): Adjust. + +2002-01-06 Akim Demaille + + * bin/autoscan.in (scan_file): Use `&used'. + +2002-01-03 Akim Demaille + + * doc/autoconf.texi (Output): Improved wording regarding use of + AC_OUTPUT. + From Olly Betts. + +2001-12-18 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Add notes on sscanf + sometimes needing writable input. + +2001-12-17 Jim Meyering + + * doc/autoconf.texi (New Macros): Tweak wording. + +2001-12-14 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): We cleaning up the + trailing files, don't apply `-rf' to files which might not be + created by configure (core, core.*, and *.core), but just `rm -f'. + Suggested by Jonathan Kamens. + +2001-12-14 Aaron M. Ucko + + * lib/autoconf/general.m4: Avoid duplicates in `$ac_configure_args'. + +2001-12-14 Akim Demaille + + * Makefile.am (MAINTAINERCLEANFILES): Remove configure. + +2001-12-13 Peter Eisentraut + + * lib/autoconf/status.m4 (_AC_SRCPATHS): Rename buildpath to + abs_builddir, top_buildpath to abs_top_builddir, srcpath to + abs_srcdir, top_srcpath to abs_top_srcdir. + (_AC_OUTPUT_FILES): Adjust. + * NEWS, doc/autoconf.texi, lib/autoconf/autotest.m4, + * tests/atspecific.m4, tests/autoreconf.in, tests/tools.at, + * tests/wrappl.in, tests/wrapsh.in: Adjust. + +2001-12-12 Steven G. Johnson + + * lib/autoconf/fortran.m4 (_AC_PROG_F77_V_OUTPUT): Fix failed + C/Fortran linking on HP/UX, by extracting the Fortran library + search path from the LPATH line in the $F77 -v output. + +2001-12-12 Kevin Ryde + + * doc/autoconf.texi (File Descriptors): Use a clearer layout for the + forbidden file descriptors table. + +2001-11-26 Akim Demaille + + * bin/autoscan.in (%c_keywords): Build it at top level. + Map to 1 in order to simplify its uses. + +2001-11-26 Akim Demaille + + * bin/autoscan.in (&scan_c_file, &scan_sh_file, &scan_makefile): + Remove $filepath, useless. + (&scan_makefile): Don't remove the $(FOO), ${FOO} and @FOO@ + variables, they are really part of the tokens. + Split the input line on spaces and then look for tokens. + Now autoscan ceases to ask for AC_PROG_LEX for the package Bison + because of `lex$U.$(OBJEXT)'. + (&scan_files): Use "@list" instead of join. + * doc/Makefile.am (CLEANFILES): Add *.fns. + +2001-11-26 Akim Demaille + + * tests/autoreconf.in, tests/autom4te.in, tests/autoupdate.in: + Remove, replaced by... + * tests/wrappl.in: Be common for all the Perl executables. + In particular autoscan and autoheader want -I. + * configure.ac: Adjust. + * lib/autoscan/headers: errno.h is portable. + +2001-11-26 Akim Demaille + + * bin/autoscan.in (used): New. + Use it. + +2001-11-26 Akim Demaille + + * bin/autoscan.in (&scan_c_file): Better parsing of CPP + directives. + (&scan_sh_file): Remove a duplicate pattern. + (&check_configure_ac): Use long options. + * lib/autoscan/headers (alloca.h): Check with AC_FUNC_ALLOCA. + +2001-11-26 Akim Demaille + + * bin/autoscan.in (scan_c_file): Fix the handling of C comments. + Before, having a line containing the opening of a multi line + comment made the whole line be ignored. + +2001-11-26 Akim Demaille + + * doc/autoconf.texi (Using an Autotest Test Suite): New. + (testsuite Scripts): Be one of its subsection. + (Autotest Logs): New. + +2001-11-26 Akim Demaille + + Test groups are now run two directories deeper. + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Replace srcdir, + top_srcdir and top_builddir with at_srcdir, at_top_srcdir and + at_top_builddir. + * lib/autotest/general.m4 (AT_INIT): Compute srcdir, + top_srcdir, builddir and top_builddir. + Use `at_*dir' relatively to the directory containing the + suite, use `*dir' when relatively to the current group dir. + +2001-11-25 Joseph S. Myers + + * doc/autoconf.texi, TODO, lib/autoconf/fortran.m4, + lib/autoconf/functions.m4, lib/autoconf/headers.m4, + tests/atgeneral.m4, tests/tools.at, tests/atspecific.m4: Fix + spelling errors. + +2001-11-22 Alexandre Duret-Lutz + + * doc/autoconf.texi (Using System Type): Add an example of `case + $host' usage so people quit using `case $target' everywhere. + +2001-11-22 Akim Demaille + + * doc/autoconf.texi (Installation Directory Variables): Englishoes + spotted by Jim Meyering. + +2001-11-16 Paul Eggert + + This patch implements a `long double' suggestion by Oliver Kiddle. + + * lib/autoconf/c.m4 (AC_LANG_BOOL_COMPILE_TRY(C)): Make the array + static, to catch errors if the value isn't known at compile-time + and the compiler supports dynamic arrays. Change its name from + `_array_' to `test_array' to avoid potential name clashes. + (AC_C_LONG_DOUBLE): Make it a compile-time test, not a run-time + test. Do not define HAVE_LONG_DOUBLE if `long double' is no + better than double. Catch a bug in GCC 2.95.2 x86. + * doc/autoconf.texi (C Compiler): Document the above. + * NEWS: Likewise. + +2001-11-13 Akim Demaille + + * tests/m4sh.at (LINENO): Protect from autom4te's substitution by + hand. + * tests/tools.at: Don't protect dnl, AT_DATA_M4SH does. + +2001-11-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): After having run the test + group, go back to the initial directory, not to at_suite_dir. + +2001-11-13 Akim Demaille + + * tests/atspecific.m4 (AT_DATA_M4SUGAR, AT_DATA_M4SH) + (AT_DATA_AUTOCONF): Also protect @&t@ from autom4te. + (AT_CHECK_AUTOCONF, AT_CHECK_AUTOHEADER): Pass no --include + option. + (AT_CHECK_CONFIGURE): Use absolute paths. + (_AT_CHECK_AC_MACRO): Create aclocal.m4 with AC_STATE_SAVE in it. + The problem is still the old one: there is no means in M4 (that I + know about) to create a defining macro, because there is no means + to create `$1' etc., therefore, the defining macro ``swallows'' + all the arguments meant to the defined macro. + +2001-11-13 Akim Demaille + + * tests/atspecific.m4 (AT_DATA_AUTOCONF): New. + (AT_CONFIGURE_AC): Output the definition of AC_STATE_SAVE in + configure.ac. + * tests/aclocal.m4: Remove, as it is no longer used. + +2001-11-13 Akim Demaille + + * lib/autotest/general.m4: Change `tests?' into `groups?' in + variable names when referring to a single test group, or to + `suite' when referring to the whole test suite. + `at_last_test' is removed: m4 compute at_format itself. + (at_stdout, at_stder1, at_stderr): New variables. + (AT_CHECK): Use them. + +2001-11-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Be sure to put `.', relative, + in PATH. + Create `testsuite.dir/003/run' instead of `testsuite.003'. + Do it as soon as a test fails, don't wait till the end of the test + suite. + Don't remove $as_me.[0-9]*, since these files no longer exist. + +2001-11-13 Akim Demaille + + * tests/tools.at: Use absolute paths, since we are no longer run + in place. + +2001-11-13 Akim Demaille + + Now that tests are running in their own private dir, there is no + need to list the files to remove at the end of tests groups. + + * lib/autotest/general.m4 (_AT_CLEANUP_FILE, AT_CLEANUP_FILES): + (AT_data_files, at_data_files): Remove. + (AT_CLEANUP, AT_DATA): Simplify. + (AT_INIT): Adjust. + Remove the group dir if !debug && !failed. + * tests/atspecific.m4: Adjust. + +2001-11-13 Akim Demaille + + Start a new layout for Autotest: `testsuite' creates + `testsuite.dir' in which the at-check-line etc. files are to be + found, and `testsuite.dir/003' where the test group 3 is run. + + * lib/autotest/general.m4 (AT_INIT): at_tests_dir, + at_check_line_file, at_format, at_test_normalized, at_group_dir + are new variables. + Create the directories. + Use absolute paths for at- files. + (AT_CHECK): Adjust. + +2001-11-11 Michael Matz + + * m4sugar.m4 (_m4_foreach): Make it linear instead quadratic. + (m4_car2): New. + (m4_car): Properly quote arguments. + +2001-11-13 Akim Demaille + + * tests/aclocal.m4 (AC_STATE_SAVE): s/LIBOBJS/LIB@&t@OBJS/ to cope + with stricter rules on LIBOBJS. + +2001-11-12 Paul Eggert + + * lib/autoconf/c.m4 (AC_C_PROTOTYPES): Define __PROTOTYPES too. + * doc/autoconf.texi (C Compiler): AC_C_PROTOTYPES now defines + __PROTOTYPES too. + +2001-11-12 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_GETMNTENT): Use AC_CHECK_FUNCS. + +2001-11-12 Akim Demaille + + * lib/autoconf/c.m4, lib/autoconf/fortran.m4, + * lib/autoconf/functions.m4, lib/autoconf/general.m4, + * lib/autoconf/headers.m4, lib/autoconf/libs.m4, + * lib/autoconf/programs.m4, lib/autoconf/specific.m4, + * lib/autoconf/types.m4: When invoking AC_DEFINE and friends, + specify to what the macro should be defined (typically to 1). + +2001-11-12 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_STRTOD): AC_SUBST POW_LIB. + From Jim Meyering. + +2001-11-12 Akim Demaille + + * lib/autoconf/programs.m4 (_AC_PROG_LEX_YYTEXT_DECL): Use + AC_TRY_EVAL to run $LEX, not AC_TRY_COMMAND. This validates the + definition used by Automake where LEX is +/- "${missing} lex" and + `missing' itself contains variables. + +2001-11-12 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Push KILL at the end. + Now that M4sh pushes BODY, the comments were output at the end of + the test suites. + +2001-11-08 Akim Demaille + + * bin/autoreconf.in (&autoreconf): Run aclocal before tracing, so + that we can trace macros from aclocal.m4. + Trace AC_PROG_LIBTOOL, not AM_PROG_LIBTOOL, since the latter is + obsoleted, and redirect to the former anyway. + Reported by Ralf Corsepius. + +2001-11-08 Akim Demaille + + * bin/autoreconf.in (&autoreconf): AC_CONFIG_SUBIDRS are to be + processed only if present. + * tests/torture.at (Configuring subdirectories): Use autoreconf + instead of successive calls to autoconf. + Add a nonexistent subdirectory to exercise the patch above. + Reported by Ralf Corsepius. + +2001-11-08 Kevin Ryde + + * doc/autoconf.texi (Limitations of Usual Tools): Note HP-UX cc + doesn't accept .S files. + +2001-11-07 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_pattern_forbid): Accepts $2. + * lib/autoconf/general.m4 (AC_INTI): Forbid LIBOBJS. + (_AC_LIBOBJ): s/LIBOBJS/LIB@&t@OBJS/. + * bin/autom4te.in (warn_forbidden): New. + (handle_output): Use it. + Read m4_pattern_forbid with messages. + +2001-11-05 Akim Demaille + + * bin/autom4te.in (--normalize): Remove. + * lib/autom4te.in: Adjust. + +2001-11-05 Akim Demaille + + * tests/Makefile.am (testsuite): Rename this target as... + ($(TESTSUITE)): this. + From Nicolas Joly. + +2001-11-05 Alexandre Duret-Lutz + + * lib/autoconf/status.m4 (_AC_OUTPUT_SUBDIRS): When removing + the --prefix option, also remove it's argument. + +2001-11-05 Akim Demaille + + * doc/autoconf.texi (testsuite Invocation): Update. + (Writing testsuite.at): Update. + +2001-11-03 Akim Demaille + + * doc/autoconf.texi: s/@code/@command/ where appropriate. + +2001-11-03 Akim Demaille + + * lib/Autom4te/General.pm: (&catfile, &canonfile) + (&file_name_is_absolute): New, wrappers around routines from + File::Spec. + Use and export them. + (&find_configure_ac): Optionally take a directory where to look at. + * bin/autoreconf.in (&parse_args): Trim the configure.ac part of + the arguments. + Default @ARGV to `.', not find_configure_ac. + (&autoreconf): Argument is a directory. + Trace AC_CONFIG_SUBDIRS and schedule the subdirs for autoreconf'ing. + * doc/autoconf.texi (autoreconf Invocation): Update. + +2001-11-03 Akim Demaille + + * lib/Autom4te/General.pm (@export_vars, @export_subs) + (@export_forward_subs): New. + Add basename, dirname, and fileparse. + (@EXPORT): Adjust. + * bin/autoreconf.in (&autoreconf): Fix call to fileparse. + Don't look for aclocal flags if we already know aclocal is not + used. + Move aclocal.m4t only if it exists. + Reported by Ezra Peisach. + +2001-11-03 Akim Demaille + + * bin/autoreconf.in (&parse_args): Work only on the configure.ac + passed on command line, defaulting to ./configure.ac if present. + (&maybe_autoreconf, File::Find): Remove, unused. + (&autoreconf): If autoconf is not used, don't try to trace. + +2001-11-02 Akim Demaille + + * configure.ac: Bump to 2.52g. + +2001-11-02 Akim Demaille + + Version 2.52f. + +2001-11-02 Akim Demaille + + * config/config.guess, config/config.sub, doc/standards.texi: + * config/lispdir.m4: Update from masters. + * configure.ac: Bump to 2.52f. + +2001-11-02 Akim Demaille + + * bin/autoreconf.in (&autoreconf): Set `$aclocal_flags' to ''. + Don't run aclocal when aclocal.m4 is not from aclocal. + From Ezra Peisach. + Don't run libtoolize and gettextize if --install is not given. + +2001-11-01 Paul Eggert + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): _AS_CR_PREPARE needs to + be invoked before _AS_LINENO_PREPARE. + (_AS_LINENO_PREPARE): Use as_cr_digits and as_cr_alnum rather + than character ranges. + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Fix NLS before + invoking AS_BASENAME. Set the locale variables to 'C' if + possible, as POSIX requires this to get the traditional + behavior. + * doc/autoconf.texi (Special Shell Variables): Describe the above. + +2001-10-31 Paul Eggert + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_WORKS): Do not surround body + with {}, as that triggers a bug in Bash 2.05. + + (_AS_LINENO_PREPARE): Use Sed rather than + Awk. Fix the sed prepass to work even if there are multiple + instances of $LINENO on the same line. Do not substitute for + other variables like $LINENOT. Do not check file dates; such a + check is unreliable on sufficiently fast machines, and removing + the check makes the code simpler and more reliable. Check for + output and chmod failures. + + * doc/autoconf.texi (Special Shell Variables): Document + the above. + +2001-10-31 Akim Demaille + + * tests/Makefile.am (atconfig): Remove this target, Automake + handles it now. + +2001-10-31 Akim Demaille + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Do not + AC_CONFIG_FILES(atlocal) as it means a file atlocal.in *must* be + provided, while it is optional. + * configure.ac: Adjust. + +2001-10-26 Paul Eggert + + * NEWS, README, configure.ac, lib/Autom4te/General.pm, + lib/Autom4te/Struct.pm: + Require Perl 5.005_03 instead of just 5.005, as some tests fail + with 5.005_02. + + * doc/autoconf.texi (Special Shell Variables): Document some + more LINENO gotchas, particularly with respect to the Awk+Sed hack. + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_WORKS): New macro. + (_AS_LINENO_PREPARE): Use it instead of shell eval, since + eval $LINENO is not portable in practice. + +2001-10-24 Akim Demaille + + * lib/Autom4te/General.pm (backname): New. + +2001-10-24 Akim Demaille + + * m4/: Remove, merged into... + * config/: here. + +2001-10-23 Tim Van Holder + + * doc/autoconf.texi (Shellology): Mention the problems with bash + 2.05's use of ANSI quoting in its `set' builtin. + +2001-10-22 Paul Eggert + + * lib/autoconf/functions.m4 (AC_FUNC_STRERROR_R): + Rename ac_cv_func_strerror_r_works to ac_cv_func_strerror_r_char_p, + and rename HAVE_WORKING_STRERROR_R to STRERROR_R_CHAR_P, since + POSIX decided to standardize on the int flavor of strerror_r. + Always do char* test, as there's no reason not to. + Assign to a char* var, to catch strerror_r that returns int*. + + * doc/autoconf.texi (Particular Functions): + Document the above changes. Also, document the fact that + AC_FUNC_STRERROR_R defines HAVE_DECL_STRERROR_R. + + * NEWS: Mention HAVE_WORKING_STRERROR_R -> STRERROR_R_CHAR_P. + +2001-10-20 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): The name of + the executable was missing from the log. + +2001-10-20 Akim Demaille + + * lib/Autom4te/General.pm (&update_file): If destination is + unchanged, remove the source. + (&up_to_date_p): Don't be verbose, be debug. + * bin/autoreconf.in: No longer support --m4dir. + (&autoreconf): Display the full path of the configure.ac we are + studying. + Trace it only once. + Be sure to honor --force with gettextize. + Always run aclocal. + * doc/autoconf.texi: Adjust. + +2001-10-20 Akim Demaille + + * bin/autoheader.in ($localdir, $m4, $SIMPLE_BACKUP_SUFFIX): + Remove, dead. + * bin/autoreconf.in (&autoreconf): Do not run gettextize when + `intl' is already present, as it refuses unless --force. + (&parse_args): Use -I, --include instead of the old Autoconf + options. + ($localdir, $autoconf_dir): Remove. + (@include): New. + (&maybe_autoreconf): New, to preserve $_ for File::Find. + +2001-10-19 Jens Petersen + + * lib/autoconf/programs.m4 (AC_PROG_AWK): Prefer gawk to mawk. + * doc/autoconf.texi (Particular Programs): Likewise. + +2001-10-19 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_FILES): Name the generated + file in @configure_input@. + Don't mention `automatically' in addition to `generated'. + * tests/torture.at (#define header templates): Adjust. + +2001-10-19 Akim Demaille + + * lib/emacs/autoconf-mode.el, lib/emacs/autotest-mode.el: In a + comment, explain how to install automatic mode selection. + From Russ Allbery. + +2001-10-19 Ezra Peisach + + * bin/autoreconf.in (autoreconf): Display the path to the + configure.ac being studied. + +2001-10-18 Paul Eggert + + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): Cast sizeof to unsigned + long, to work around a bug in the HP C compiler version HP92453-01 + B.11.11.23709.GP. + + * lib/m4sugar/m4sh.m4 (AS_DIRNAME): Use 'dirname' if that works. + (AS_BASENAME_EXPR): New macro. + (AS_BASENAME_SED): Do not assume GNU sed semantics. + (AS_BASENAME): Use 'basename' if that works; then try 'expr'; + and fall back on 'sed' only if the other two fail. This makes + AS_BASENAME act more like AS_DIRNAME. + (as_me): Shell-quote the argument of AS_BASENAME, in case $0 + contains white space. + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): + Use AS_DIRNAME, since I think it's now DOS-friendly. + * tests/m4sh.at (DIRNAME_TEST): New arg $3. + Allow "dirname //FOO" to return either / or //, as POSIX allows + either behavior. + +2001-10-10 Akim Demaille + + * lib/autoconf/lang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Recognize + `a_out.exe' for OpenVMS 7.1, DEC C 5.5 compiler, via GNV. + From Eric Sharkey. + +2001-10-10 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_ECHO_N_PREPARE): m4_defun, not + m4_define, since... + (_AS_ECHO_N): AS_REQUIREs it. + +2001-10-10 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS) + (AC_INCLUDES_DEFAULT): Move to... + * lib/autoconf/headers.m4: here. + * lib/autoconf/types.m4: Comment changes. + * doc/autoconf.texi: Specify where the default includes are used + in the macro prototypes. + +2001-10-09 Akim Demaille + + * lib/autoconf/autoconf.m4 (m4_patsubst, m4_regexp): New + transition code. + +2001-10-08 Akim Demaille + + * bin/autoreconf.in (&autoreconf): Remove debugging code. + (&parse_args): Pass verbosity/debugging options to subtools when + --debug, not when --verbose. + * lib/autom4te.in (Autoreconf-preselections): New. + (Autoconf): Use it. + +2001-10-08 Akim Demaille + + * bin/autoreconf.in (autoreconf): Run libtoolize when appropriate. + +2001-10-08 Akim Demaille + + * doc/autoconf.texi (autoreconf Invocation): Adjust. + * bin/autoreconf.in (autoreconf): Run gettextize when appropriate. + +2001-10-08 Akim Demaille + + * tests/tools.at (AT_CHECK_PERL_SYNTAX): Check autoreconf. + (Syntax of the shell scripts): Don't. + * bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in: Don't + bother with $force since... + * lib/Autom4te/General.pm: does. + +2001-10-08 Akim Demaille + + * bin/autoreconf.in: Rewrite in Perl. + * configure.ac: Adjust. + * lib/Autom4te/General.pm (&up_to_date_p): New. + * bin/autom4te.in (&up_to_date_p): Use it. + Rename as... + (&up_to_date): this. + +2001-10-08 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_case, m4_bmatch, m4_normalize) + (m4_list_cmp): Use $0 to reinvoke yourself. + (m4_patsubsts): New. + (m4_strip, m4_version_unletter): Use it. + * tests/atspecific.m4 (AT_DATA_M4SUGAR, AT_DATA_M4SH): Likewise. + +2001-10-08 Akim Demaille + + * lib/autoconf/autoconf.m4, lib/autoconf/general.m4, + * lib/autoconf/libs.m4, lib/autoconf/status.m4, + * lib/autoconf/types.m4, lib/autotest/general.m4, + * lib/m4sugar/m4sh.m4, lib/m4sugar/m4sugar.m4, tests/atspecific.m4, + * tests/torture.at: Rename m4_regexp, m4_patsubst, and m4_match to + m4_bregexp, m4_bpatsubst, and m4_bmatch. + * doc/autoconf.texi (Redefined M4 Macros): Adjust. + +2001-10-08 Akim Demaille + + * lib/m4sugar/m4sh.m4: Use AS_REQUIRE. + +2001-10-08 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_DIRNAME_EXPR): Use AS_REQUIRE. + * tests/tools.at (AT_DATA_FORBIDDEN): Rename/move/duplicate to... + * tests/atspecific.m4 (AT_DATA_M4SUGAR, AT_DATA_M4SH): here. + * tests/tools.at, tests/m4sh.at: Use it. + * tests/m4sh.at: Don't rely on Autoconf macros. + (DIRNAME_TEST): Also exercise the expr variant. + * tests/m4sugar.at, tests/atspecific.m4 (AT_CHECK_M4SUGAR): The + preferred M4sugar extension is now `.4s'. + * tests/README: Remove. + +2001-10-08 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_provide_ifelse): Rename as... + (m4_provide_if): this. + * lib/m4sugar/m4sh.m4 (AS_REQUIRE): New. + * lib/autoconf/general.m4 (AS_DEFUN, AC_DEFUN_ONCE, AC_BEFORE) + (AC_REQUIRE, AC_PROVIDE, AC_PROVIDE_IFELSE): Be exact copy of the + M4sugar peer, i.e., drop the `AC_PROVIDE_$1' broken marker. + +2001-10-08 Akim Demaille + + Use `add-log-current-defun-function' for ChangeLog creation. + Suggested by Tom Tromey. + + * lib/emacs/autotest-mode.el (autotest-mode-map): New. + (autotest-mode): Adjust. + * lib/emacs/autoconf-mode.el (autoconf-mode-map): Modernize, map + 'comment-region onto `C-c ;'. + Comments are `#', not `dnl'. + (autoconf-current-defun): New. + (autoconf-font-lock-keywords): Recognize `m4_defun'. + +2001-10-08 Akim Demaille + + * lib/autoconf/general.m4 (_m4_divert(BODY)): Move to... + * lib/m4sugar/m4sh.m4: here. + (AS_INIT): Push the BODY diversion, set the #! /bin/sh line. + * lib/autoconf/general.m4 (AC_PLAIN_SCRIPT) : Remove. + (AT_INIT): Replace AC_PLAIN_SCRIPT with AS_INIT invocation, + include handle the m4_pattern_*, no longer push the + BODY diversion nor set the /bin/sh line, AS_INIT does it. + * lib/autotest/general.m4 (AT_INIT): Likewise. + * tests/base.at: Adjust the tests to use AS_INIT. + * tests/tools.at (AT_DATA_FORBIDDEN): New. + (autoconf: forbidden tokens): Adjust to work on M4sh instead of + Autoconf. + +2001-10-07 Paul Eggert + + * doc/autoconf.texi (config.status Invocation): + CONFIG_SHELL defaults to a shell that supports LINENO if available. + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): If the current + shell does not support LINENO, and if CONFIG_SHELL is unset or + empty, and if we can find a shell that does support LINENO, + then set CONFIG_SHELL to that shell and then re-execute + ourselves with CONFIG_SHELL. + +2001-10-05 Paul Eggert + + * tests/Makefile.am (clean-local): Don't invoke $(TESTSUITE) if it + doesn't exist. Remove *.tmp, as a .tmp file is created during the + build of $(TESTSUITE). + +2001-10-05 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): Look in the path + iff we are a bareword. + Reported by Raja R Harinath. + +2001-10-05 Akim Demaille + + * tests/m4sh.at (LINENO): New. + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Be sure to set + PATH_SEPARATOR before using it. + Fix the absolute path case/esac pattern. + Provide $0 as fallback for as_myself. + Reported by Raja R Harinath. + +2001-10-05 Akim Demaille + + * Makefile.am, config/Makefile.am, lib/emacs/Makefile.am, + * m4/Makefile.am, man/Makefile.am: Add/adjust MAINTAINERCLEANFILES. + +2001-10-05 Akim Demaille + + * lib/m4sugar/m4sh.m4 (_AS_LINENO_PREPARE): New, extracted from... + (AS_SHELL_SANITIZE): here. Use it. + (_AS_LINENO_PREPARE): Preserve the exit status of $0.lineno. + From Paul Eggert. + +2001-10-04 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Use a portable + combination of Awk and sed to replace $LINENO. + +2001-10-02 Paul Eggert + + * doc/autoconf.texi (Limitations of Builtins): You can't use + "source"; it's not portable. Remove confusing and + somewhat-incorrect example involving "." and "/". + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): "source" -> ".", for + compatibility with POSIX shells. + +2001-10-02 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Just source 40.lineno + instead of exec'ing to preserve $0 and $@. + +2001-10-01 Akim Demaille + + * tests/testsuite (AT_INIT) : New. + Don't run twice the same test. + +2001-10-01 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT) <--help>: Catch up with reality. + No longer output the list of tests. + <--list>: New option. + <--full-help>: Remove. + Complete the short/long options duality. + Various small adjustments. + +2001-10-01 Akim Demaille + + * doc/autoconf.texi: Use @kbd for user input. + Always use `$' as shell prompt. + +2001-09-30 Paul Eggert + + * lib/autoconf/status.m4 (AC_OUTPUT_MAKE_DEFS): + Don't use nested parenthesization. This patch was originally + suggested to bug-autoconf by Philippe De Muyter on 2000-05-28, + but somehow it didn't get incorporated then. + * doc/autoconf.texi (Limitations of Usual Tools): + Clarify remark about sed and nested parenthesization. + + * lib/autoconf/types.m4 (AC_CHECK_SIZEOF): + Report an error if the size cannot be determined even though + the type exists. + * lib/autoconf/general.m4 (_AC_COMPUTE_INT_COMPILE): + Check for `expr' arithmetic overflow, and for compilation failure, + and invoke a new argument $4 if either is discovered. + This makes _AC_COMPUTE_INT_COMPILE more like _AC_COMPUTE_INT_RUN. + (_AC_COMPUTE_INT): Pass IF-FAILS arg to _AC_COMPUTE_INT_COMPILE. + +2001-09-28 Akim Demaille + + * lib/emacs/autoconf-mode.el, lib/emacs/autotest-mode.el: New. + * m4/lispdir.m4: New. + * aclocal.m4, configure.ac: Adjust. + +2001-09-28 Akim Demaille + + * lib/autotest/general.m4 (AT_VICTIMS): Rename as... + (AT_TESTED): this. + (AT_INIT): More the wrapped section to where it will be expanded. + Output `AT_tested' only when existing. + Catch unexpanded PACKAGE_STRING and PACKAGE_BUGREPORT. + +2001-09-27 Akim Demaille + + Fix the passing of $? to ACTION-IF-FAILED in AC_TRY_RUN, that + generates too many bug reports. + + * lib/autoconf/general.m4 (_AC_RUN_IFELSE): Pass the right exit + status when executing the ACTION-IF-FALSE. + * tests/base.at (AC_TRY_*): Rename as... + (AC_TRY_COMMAND): this. + (AC_RUN_IFELSE): New. + * tests/compile.at (Extensions, C keywords) + (AC_PROG_CPP requires AC_PROG_CC, GNU Fortran 77) + (Broken/missing compilers, AC_PROG_CPP with warnings) + (AC_PROG_CPP without warnings, AC_PROG_CPP via CC): Move to... + * tests/c.at (Extensions, C keywords) + (Broken/missing compilers, AC_PROG_CPP with warnings) + (AC_PROG_CPP without warnings, AC_PROG_CPP via CC) + (AC_PROG_CPP requires AC_PROG_CC): here and... + * tests/fortran.at (GNU Fortran 77): there. + * doc/autoconf.texi (autoconf Invocation): Fix the example: + AC_TRY_RUN is about compilation, not shell commands. + (Test Programs): AC_TRY_RUN works as used to be advertised. + +2001-09-27 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Fix bugs spotted by + Raja R Harinath: + Be sure to detect when $LINENO always returns the same value. + Look for the original script, basename($0) is certainly not + enough. + Pass the CLI arguments to `$as_me.lineno'. + +2001-09-25 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Dump the whole config.log. + Be sure the close and reopen the LOG fd before and after using tee + to extend the log. + : Adjust to the new format of at_help_all. + +2001-09-23 Akim Demaille + + * bin/autom4te.in (parse_args): There can be several invocations + of --language now. + +2001-09-23 Akim Demaille + + * doc/autoconf.texi (Top): Wrap in @ifnottex. + +2001-09-23 Akim Demaille + + * lib/autoconf/status.m4 (_AC_SRCPATHS): Compute and provide + ac_buildpath, ac_top_buildpath, ac_srcpath, and ac_top_srcpath. + (_AC_OUTPUT_FILES): Also substitute srcpath, top_srcpath, + builddir, buildpath, top_builddir, and top_buildpath. + (_AC_OUTPUT_SUBDIRS): Compute the dir variables *before* changing + the current directory. + * lib/autoconf/general.m4 (_AC_INIT_HELP): Compute the dir + variables *before* changing the current directory. + Skip nonexistent dirs. + * doc/autoconf.texi (Preset Output Variables): Document these + variables. + + * lib/autotest/general.m4: Do not reset AT_victims. + Don't compute at_srcdir nor at_top_srcdir. + + * tests/tools.at: Hence use top_srcdir. + + * tests/Makefile.am, tests/autoconf, tests/autoheader, + * tests/autom4te, tests/autoreconf, tests/autoupdate, tests/ifnames: + Remove. + * tests/autoreconf.in, tests/wrappl.in, tests/autom4te.in, + * tests/wrapsh.in, tests/autoupdate.in: New. + * tests/Makefile.am (DISTCLEANFILES, EXTRA_DIST): Adjust. + * configure.ac: Build the position independent wrappers. + + * man/Makefile.am: Now that test wrappers are position + independent, use them and drop dark envvar magic. + +2001-09-23 Akim Demaille + + * doc/autoconf.texi (Common Shell Constructs): Rename as... + (Programming in M4sh): this. + Promote to @section. + +2001-09-23 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Dump config.log last. + Pass $at_debug_args to the rerun test suite. + * lib/m4sugar/Makefile.am (DISTCLEANFILES): New. + * bin/Makefile.am (ETAGS_SH): Don't use characters ranges. + From Paul Eggert. + +2001-09-23 Akim Demaille + + * bin/autom4te.in (@my_warning): Remove, handled by `autom4te.cfg'. + +2001-09-23 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Fix shell + over-escaping. + +2001-09-23 Akim Demaille + + * lib/Autom4te/General.pm (&debug): New. + * bin/autom4te.in ($language): Move to... + (parse_args): here. + Handle --language in languages. + * lib/autom4te.in (Automake-selections, Autoheader-selections) + (Autoscan-selections): New. + (Autoconf): Adjust. + +2001-09-23 Tim Van Holder + + * m4/auxdir.m4, m4/cond.m4, m4/depend.m4, m4/init.m4, + * m4/install-sh.m4, m4/missing.m4, m4/sanity.m4, m4/strip.m4: Updated + to match current versions from CVS Automake. + +2001-09-23 Alexandre Duret-Lutz + + * doc/autoconf.texi (Special Shell Variables): Add pdksh output + for $LINENO. + +2001-09-22 Akim Demaille + + * lib/autoconf/autotest.m4: Create `package.m4'. + * tests/Makefile.am (package.m4): Remove. + +2001-09-22 Akim Demaille + + Rely on `$LINENO' when possible instead of `__oline__'. + + * lib/m4sugar/m4sh.m4 (AS_SHELL_SANITIZE): Provide some form of + `$LINENO' support replacement when not supported. + (_AS_CR_PREPARE, _AS_TR_CPP_PREPARE, _AS_TR_SH_PREPARE): Invoke + them explicitly to be sure they are not output before this section + (via m4_require). Cosmetic only. + * lib/autoconf/c.m4, lib/autoconf/general.m4, + * lib/autoconf/programs.m4: Replace all the occurrences of + `__oline__' with `$LINENO'. + * doc/autoconf.texi (Special Shell Variables): Document LINENO. + +2001-09-21 Tim Van Holder + + * lib/autoconf/functions.m4 (_AC_FUNC_FORK): Replaceded an 8-bit + character (u: -> ue) in a code comment. + (AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK): Only run 'ln -s' if we know + it works. + +2001-09-21 Akim Demaille + + * Makefile.maint (AUTOM4TE): Neutralize autom4te. + Suggested by Jim Meyering. + +2001-09-20 Tim Van Holder + + * lib/autoconf/programs.m4: Use extensions listed in + $ac_executable_extensions when looking for programs. + +2001-09-20 Tim Van Holder + + * lib/autoconf/general.m4: Fix a small Englisho. + * lib/autoconf/status.m4: Fix a small typo. Handle DOS paths when + setting up ac_dir_suffix and ac_top_builddir. + * lib/m4sugar/m4sh.m4: Default CDPATH to $PATH_SEPARATOR, not ':'. + +2001-09-20 Tim Van Holder + + * doc/autoconf.texi (File System Conventions): Clarify the use of + PATH_SEPARATOR. + (Special Shell Variables[PATH_SEPARATOR]): Ditto. + (Special Shell Variables[CDPATH]): Mention that $PATH_SEPRATOR should + be used instead of ':'. + * lib/autotest/general.m4: Replace occurrences of ':' in + AUTOTEST_PATH with $PATH_SEPARATOR at test suite startup. + +2001-09-20 Tim Van Holder + + * tests/atgeneral.m4: Add basic support for test ranges (e.g. 7-34) as + arguments. Fixed a typo. + +2001-09-20 Tim Van Holder + + * man/Makefile.am (.x.1): Use @PATH_SEPARATOR@, not ':' to set up + $PATH. Also set AUTOM4TE_CFG, so we can process autom4te properly. + +2001-09-20 Tim Van Holder + + * bin/autoscan.in: Add 'exec-perl-if-not-run-by-perl'. + * bin/autoupdate.in: Ditto. + * bin/autoheader.in: Reworded a few comments. + * bin/autoconf.in: Reworded help text for a few options. + * bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in, + * bin/autoscan.in, bin/autoupdate.in: Ditto. + +2001-09-20 Tim Van Holder + + * lib/Autom4te/XFile.pm (open): Simplified the error message (we + already have $file). Set output files to binary mode (helps avoid + CR issues on DOSish systems). + +2001-09-19 Akim Demaille + + * lib/autotest/general.m4: Englishoes. + From Tim Van Holder and Alexey Mahotkin. + +2001-09-18 Paul Eggert + + * doc/autoconf.texi (Common Shell Constructs): New node, + documenting AS_DIRNAME. + (Limitations of Usual Tools): Refer to it when discussing dirname. + Also, update discussion of POSIX standard to reflect latest draft. + + * lib/autoconf/c.m4: + (AC_LANG_INT_SAVE(C)): Also support negative values, down to LONG_MIN. + + * lib/autoconf/general.m4 (_AC_COMPUTE_INT_COMPILE): + Do not pass a first argument with leading '-' + to expr, by parenthesizing initial integers that might be negative. + + * doc/autoconf.texi (Particular Functions): AC_FUNC_GETPGRP + now merely checks whether it is an error to pass an argument + to getpgrp. + + * lib/autoconf/functions.m4 (_AC_FUNC_GETPGRP_TEST): Remove. + (AC_FUNC_GETPGRP): Don't bother with a runtime test. Just check + whether it is a (compile-time) error to pass an argument to + getpgrp. This simpler test supports the revised documentation, + and is all that AC_FUNC_GETPGRP's users really need. + +2001-09-18 Akim Demaille + + * doc/autoconf.texi (Limitations of Make) <$<>: New. + +2001-09-18 Akim Demaille + + * doc/autoconf.texi (Limitations of Usual Tools) : More about + `{}'. + * lib/autotest/general.m4 (AT_INIT): Adjust. + +2001-09-18 Paul Wagland + + * tests/m4sh.at: Ensure that AS_DIRNAME handles '/', '//' and '///' + correctly. + Add test for AS_BASENAME. + * lib/m4sugar/m4sh.m4: Fix AS_BASENAME so that it passes the previous + added test. It now correctly handles /1/2/3/, returning '3' not ''. + Added AS_BASENAME_SED to make the interface the same as AS_DIRNAME. + * tests/base.at: Fixed the expected responses. The old ones were + one line out... + * lib/autoconf/general.m4: Fixed AC_PREFIX_PROGRAM, it now behaves as + the documentation claims it should (and how it behaved in 2.13). + +2001-09-18 Akim Demaille + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): No INIT-CMDS in + the AC_CONFIG_COMMANDS invocation. + This also solves the name clash problems. + Don't set the package's ID. + * lib/m4sugar/Makefile.am (version.m4): Revamp. + No longer to be shipped. + (version.in): Remove. + * lib/m4sugar/m4sugar.m4, lib/autoconf/general.m4, + * lib/autoconf/status.m4: Adjust. + Use `m4_PACKAGE_STRING'. + * lib/autotest/general.m4 (AT_INIT): N-th signature change: now + the only optional argument is the name of the test suite. + Expect `package.m4' to define the package signature. + * lib/autom4te.in (Autotest): Add `package.m4?'. + * tests/Makefile.am (package.m4): New. + * tests/suite.at: ifnames is a victim. + +2001-09-18 Akim Demaille + + * lib/autom4te.in (Autoconf): Preselect AM_CONDITIONAL, + AC_LIBSOURCE, AC_CONFIG_FILES. + * lib/autotest/general.m4 (AT_INIT): Don't abort when a tested + program version string doesn't match the package's. + * lib/autoconf/general.m4 (AC_CACHE_VAL): Reestablish the space + after `(cached)'. + +2001-09-17 Paul Eggert + + * lib/autoconf/c.m4: (AC_LANG_INT_SAVE(C)): + Allow expression to return any value that can fit into unsigned long + (not int, as before). Check for output errors. + +2001-09-17 Bruno Haible + + * lib/autoconf/c.m4: (AC_LANG_INT_SAVE(C)): + Always include and . Evaluate + the expression in an extra function before these includes. Call + fprintf "%d" only after ensuring the argument is of type 'int'. + Reported by Wayne Chapeskie . + +2001-09-17 Paul Eggert + + Fix bug reported by Paul Townsend on AIX 4.3.3.0 with CFLAGS=-O4 + or CFLAGS=-O5. In that case, the linker has a relaxed view of + fatal errors, and AC_CHECK_LIB causes it to include libraries even + when they don't exist. + + * lib/autoconf/headers.m4 (AC_HEADER_DIRENT): Use AC_SEARCH_LIBS, + not AC_CHECK_LIB, so that we don't use -ldir or -lx if we don't + need it. + + * lib/autoconf/specific.m4 (AC_ISC_POSIX): Replace the old, crufty + version with the version used by fileutils 4.1, except use + AC_SEARCH_LIBS, not AC_CHECK_LIB, so that we don't use -lcposix if + we don't need it. + + * doc/autoconf.texi (AC_ISC_POSIX): Describe new behavior. + +2001-09-13 Akim Demaille + + * tests/base.at, tests/m4sh.at: Be sure to issue the bangshe line + _first_. + Reported by Gerrit P. Haase. + +2001-09-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Reset `AT_victims' so that + m4_defn'ing is valid. + +2001-09-13 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_append_uniq): New. + * lib/autotest/general.m4 (AT_VICTIMS, AT_KEYWORDS, _AT_CLEANUP_FILE): + Use it. + +2001-09-13 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (_AS_QUOTE_IFELSE, _AS_BOX_INDIR): Use + m4_match. + (m4_re_escape): New. + * lib/autoconf/status.m4 (AC_CONFIG_IF_MEMBER): Use it. + * lib/autoconf/general.m4 (AC_CACHE_SAVE): Use m4_match. + * lib/autoconf/status.m4 (AC_CONFIG_IF_MEMBER, AC_CONFIG_LINKS): + Likewise. + * lib/autoconf/types.m4 (_AC_CHECK_TYPE_REPLACEMENT_TYPE_P) + (_AC_CHECK_TYPE_MAYBE_TYPE_P, AC_CHECK_MEMBER): Likewise. + * lib/autotest/general.m4 (AT_INIT): Rename AT_TESTS_ALL as + AT_tests_all for consistency. + Set at_victims. + (AT_VICTIMS): Similar to AT_KEYWORDS. + (_AT_CLEANUP_FILE_IF): Use m4_match and m4_re_escape. + +2001-09-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Fix stupid bugs. + +2001-09-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Create and remove + `$as_me.[0-9]+' instead of `debug-[0-9]+.sh', so that multiple + test suites can cohabit. + +2001-09-13 Akim Demaille + + * tests/mktests.sh: Don't output banners for empty test files. + +2001-09-13 Akim Demaille + + Test suites can be run independently of configure. + + * lib/m4sugar/m4sh.m4 (_AS_ECHO, _AS_ECHO_N_PREPARE): New. + * lib/autoconf/programs.m4 (_AC_PROG_ECHO): Remove. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Adjust: AC_SUBST + ECHO_N etc. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Don't ask for at_n + and at_c. + * lib/autotest/general.m4: Use ECHO_*. + +2001-09-13 Akim Demaille + + * bin/ifnames.in: Rewrite in Perl. + * configure.ac: Don't look for AWK. + * tests/tools.at (AWK portability): Remove. + (Syntax of the shell scripts): Don't check ifnames. + (AT_CHECK_PERL_SYNTAX): New. + (Syntax of the Perl scripts): Check ifnames. + * tests/ifnames: New. + +2001-09-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Let --keywords also match + test group titles. + * tests/atspecific.m4 (AT_CHECK_AU_MACRO): AT_KEYWORDS(autoupdate). + Remove all the other keywords. + +2001-09-10 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Remove the diversion HELP and + SETUP: no longer used. + Support -k, --keywords. + : Be `no', `short', or `long'. + : New variable. + (AT_KEYWORDS): New. + (AT_CLEANUP_FILE_IFELSE, AT_CLEANUP_FILE): Rename as... + (_AT_CLEANUP_FILE_IF, _AT_CLEANUP_FILE): these. + (_AT_CLEANUP_FILE_IF): Simplify the regexp. + (AT_SETUP): Reset AT_line, AT_keywords, AT_description. + No longer fill the HELP diversion. + (AT_CLEANUP): Use them. + * lib/m4sugar/m4sugar.m4 (m4_append): Support a separator. + (m4_list_append): Remove. + + Spread a few keywords in the Autoconf test suite. + +2001-09-10 Akim Demaille + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Don't pass + PATH_SEPARATOR, let M4sh compute it. + * lib/m4sugar/m4sh.m4 (_AS_PATH_SEPARATOR_PREPARE): New. + * lib/autoconf/programs.m4 (AC_SHELL_PATH_WALK): Use PATH_SEPARATOR. + Move to... + * lib/m4sugar/m4sh.m4 (_AS_PATH_WALK): Here. + Simplify when the path is not a literal. + (AS_UNAME): Use it to report PATH. + * lib/autoconf/general.m4 (_AC_INIT_PREPARE_FS_SEPARATORS): Remove. + (_AC_INIT_DEFAULTS): AC_SUBST PATH_SEPARATOR. + * lib/autoconf/programs.m4 (AC_PROG_INSTALL): Use _AS_PATH_WALK. + * lib/autotest/general.m4 (AT_INIT): Use _AS_PATH_WALK to + normalize the path, and to look for victims. + * tests/semantics.at (AC_PATH_PROG & AC_PATH_PROGS) + (AC_CHECK_PROG & AC_CHECK_PROGS): Use PATH_SEPARATOR. + +2001-09-07 Akim Demaille + + * bin/autom4te.in (&handle_m4): `< /dev/null' so that GNU M4 1.5 + doesn't neutralize SIGINT, making autoconf etc. non interruptible. + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): Move the package + related variables into `at_package_*'. + * lib/autotest/general.m4 (AT_VICTIMS): New. + (AT_INIT): Adjust for stand-alone/embedded test suites. + (AS_MESSAGE_LOG_FD): Define and use it. + * tests/suite.at (AT_VICTIMS): Use it. + * tests/tools.at (autoupdating AC_PREREQ): Don't depend upon + at_version. + +2001-09-07 Akim Demaille + + Move toward possibly stand-alone test suites. + + * lib/autotest/general.m4: Stop displaying srcdir everywhere as, + in addition, it introduces useless differences in logs. + (AT_INIT): Let atconfig and atlocal be both optional. + Adjust PATH computation. + * lib/m4sugar/m4sh.m4 (AS_UNAME): More readable display of PATH. + +2001-09-07 Akim Demaille + + * lib/autoconf/Makefile.am (autoconf.m4f): Depends upon + m4sugar/version.m4. + +2001-09-05 Akim Demaille + + * lib/autoconf/c.m4 (AC_LANG_BOOL_COMPILE_TRY(C)): Use `_array_' + to avoid GCC warnings. + From Uwe Seimet. + +2001-09-05 Akim Demaille + + * bin/autom4te.in: --language is -l, not -s. + +2001-09-05 Akim Demaille + + Be ready to handle filenames as stupid as `dnl.at', for if even + the maintainer is dumb enough to do that... + + * lib/autotest/general.m4 (AT_SETUP, AT_LINE): Demonstrates your + excellence in M4 quotation: consider `__file__' is active. + + And BTW, when invoking m4, pass the --include in the right order: + the wrong one. + + * bin/autom4te.in, bin/autoupdate.in: Use reverse when kingtal to + 4m. + +2001-09-05 Akim Demaille + + * lib/Autom4te/XFile.pm: New lib file. + * bin/autoupdate.in, bin/autoscan.pl, bin/autom4te.in, + * bin/autoheader.in: Use it. + +2001-09-05 Akim Demaille + + * bin/autoupdate.in (&handle_m4_macros) : Undefine iff + defined. + +2001-09-05 Akim Demaille + + * lib/Autom4te/General.pm (&getopt): Work around the `-' Getopt bug. + * bin/autoheader.in, bin/autoupdate.in (&parse_args): Adjust. + + * bin/autoscan.in: Use `getopt' and `find_files' etc. + Add -I, --include support. + * doc/autoconf.texi (autoscan Invocation): Adjust. + +2001-09-05 Akim Demaille + + CVS GNU M4 doesn't like `undefine(undefined)'. + + * bin/autoupdate.in (&handle_m4_macros, &handle_autoconf_macros): + New, extracted from main. + Use IO::File wherever possible. + (input.m4): Be constant, use -I instead of hard coding $tmp. + Therefore be a quoted heredoc. + Don't invoke `_au_disable', since ac was not loaded, but just + `unm4.m4'. + +2001-08-31 Akim Demaille + + Version 2.52d. + +2001-08-31 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): Fix the + previous patch. + * tests/atspecific.m4 (AT_CHECK_AUTOHEADER): Can create `config.hin~'. + +2001-08-31 Akim Demaille + + * lib/autoconf/status.m4 (_AC_OUTPUT_CONFIG_STATUS): DU 5.0 has + serious problems handling heredocs in heredocs. + Reported by Nicolas Joly. + +2001-08-31 Akim Demaille + + * doc/autoconf.texi: Don't promote non `m4_*' M4 macros. + (Making testsuite Scripts): Update. + +2001-08-31 Akim Demaille + + * lib/Makefile.am (CLEANFILES): Add autom4te.cfg. + +2001-08-31 Akim Demaille + + * doc/autoconf.texi (Quadrigraphs): Document `@&t@'. + (testsuite Scripts): There is no such thing as `atconfig.in'. + And actually one diagram is missing: test suite runtime. + +2001-08-31 Akim Demaille + + * lib/Autom4te/General.pm (&find_file): Browse the includes in the + inverse order. + +2001-08-31 Akim Demaille + + * bin/autoupdate.in (@include): `installcheck' revealed the path + to m4sugar was lacking! + +2001-08-31 Akim Demaille + + * man/Makefile.am (.x.1): We really have to pass + autom4te_perllibdir. + +2001-08-31 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Don't pass all the args to + debug scripts, in particular passing explicitly listed tests to + run is stupid. + +2001-08-31 Akim Demaille + + * bin/autom4te.in (&parse_args): Strip `.' from `@include'. + * bin/autoupdate.in: Use --include, -I, and --force, -f, too. + Use directly autom4te, not autoconf. + * tests/autoupdate: $top_srcdir/lib is needed too for melt files. + +2001-08-31 Akim Demaille + + * tests/semantics.at (AC_C_BIGENDIAN): Missing eol. + * bin/autoheader.in (%symbol): Strip arguments of macros. + +2001-08-31 Akim Demaille + + * doc/autoconf.texi: Catch up -I, --include changes. + +2001-08-31 Akim Demaille + + * bin/autom4te.in (&parse_args): Die on unknown languages. + * bin/autoheader.in: Run directly autom4te --mode=autoconf, no + need for autoconf. + Promote --include over --macrodir and other obsolete options. + +2001-08-31 Akim Demaille + + * lib/Autom4te/General.pm ($version, $help, &getopt): New. + * bin/autoupdate.in, bin/autoheader.in, bin/autom4te.in: Use them. + * bin/autom4te.in ($autoconf): Pass --force. + `print $out' doesn't print `$_' but `$out'. + * tests/tools.at (Syntax of the Perl scripts): Pass the lib dir. + (autoheader): Pass --force since the test suite goes too fast for + the time stamps. + Adjust to the new autoheader messages. + +2001-08-31 Akim Demaille + + * bin/autoheader.in: Handle the acconfig.h etc. junk files. + Check the completeness of the #template. + * lib/Autom4te/General.pm (&update_file): s/remove/unlink/. + * tests/semantics.at (AC_C_BIGENDIAN): Adjust AT_CHECK_AUTOHEADER + invocation. + +2001-08-31 Akim Demaille + + * lib/Autom4te/General.pm (&find_file, &update_file): New. + * bin/autoupdate.in, bin/autoheader.in: Adjust. + Drop AC_MACRODIR dead for real. + * tests/atspecific.m4 (AT_CHECK_AUTOHEADER): Now autoheader says + `autoheader: `config.hin' is created'. + * tests/tools.at (Syntax of the Perl scripts): Check autoheader. + +2001-08-31 Akim Demaille + + * bin/autoheader.in: Rewrite in Perl. + * tests/autoheader: Adjust. + +2001-08-31 Akim Demaille + + * bin/autoconf.in (--include, -I): New option. + Map --localdir, --autoconf-dir onto it. + Forward autom4te's options instead of interpreting them. + * bin/autoconf.in, bin/autoheader.in (AC_MACRODIR, autoconf_dir): + There is no such envvar since the inception of autom4te.cfg. + * bin/autom4te.in (&parse_args): Uniquify `@include'. + * bin/autoupdate.in: Adjust, and perform more control. + * tests/atspecific.m4 (AT_CHECK_AUTOCONF): Adjust. + * tests/autoconf: Dittowise. + +2001-08-31 Akim Demaille + + * bin/autoconf.in: Don't bother with `acsite.m4' and `aclocal.m4'. + * bin/autom4te.in (&find_file): Support `FILE?' standing for + optionally `FILE'. + Use -e, not -f, since /dev/null for instance is OK. + (&parse_args): Adjust. + * lib/autom4te.in (Autoconf): Add `acsite.m4?' and `aclocal.m4?'. + +2001-08-31 Akim Demaille + + * configure.ac: Also find tested executables in bin. + * bin/autoconf.in, bin/autoheader.in, bin/autoreconf.in, + * bin/autoscan.in, autoupdate.in: Use exclusively the name of the + installed peer executables, only PATH is allowed to resolve it. + Pass `autoconf_dir' via options, not via invisible envvars. + * lib/Autom4te/General.pm (&find_peer): Remove. + * lib/autotest/general.m4 (AT_INIT): `AUTOTEST_PATH=a:b' gives + `abuild:asrc:bbuild:bsrc', not `abuild:bbuild:asrc:bsrc'. + * man/Makefile.am: Let help2man rely on PATH instead of trying to + find the executables for it. + * tests/Makefile.am: Major cleanup. Too lazy to document... + * tests/atlocal.in: Remove all the obscure envvar manipulations. + We only need PERL. + * tests/atspecific.m4, tests/tools.at: Passing --localdir is + indeed related to running the test suite, while passing + --autoconf-dir and others is related to running non installed + Autoconf executables. So don't do that, leave it to... + * tests/autoconf, tests/autoheader, tests/autom4te, tests/autoupdate, + * tests/autoscan: New. + * tests/atspecific.m4 (AT_CHECK_M4SUGAR, AT_CHECK_M4SH): Don't + refer to library files: rely on --language. + +2001-08-29 Akim Demaille + + * bin/autom4te.in, lib/autom4te.in, bin/autoconf.in: + s/--set/--language/. + +2001-08-29 Akim Demaille + + * doc/autoconf.texi: Strip the @nodes. + Suggested by Paul Eggert. + (Initializing configure): Typo. + +2001-08-29 Akim Demaille + + * bin/autom4te.in (&handle_output): s/@__@/@&t@/. + Suggested by Paul Eggert. + +2001-08-29 Akim Demaille + + * Makefile.maint (do-po-update): Wget refuses to overwrite files: + download in a tmp dir. + +2001-08-29 Akim Demaille + + * lib/autotest/general.m4: s/AT-devnull/devnull/ since there are + case insensitive OSes out there :( + From Tim Van Holder. + +2001-08-29 Akim Demaille + + * lib/autom4te.in: New. + * lib/Makefile.am (edit, autom4te.cfg): New. + * bin/autom4te.in (BEGIN): Simplify. + Rely on `AC_MACRODIR' in addition of `autom4te_perllibdir'. + (&load_configuration): New. Use it. + (&parse_args): Support --mode, --set, and --melt. + * bin/autoconf.in: Simplify and adjust. + * tests/Makefile.am (AUTOMAKE): Use --set. + * tests/atlocal.in: Adjust. + * BUGS: distcheck and check are weak. + +2001-08-29 Akim Demaille + + * lib/autotest/general.m4: Use + foo=`(command) 2>/dev/null` + not + foo=`command` 2>/dev/null + (at-devnull): Rename as... + (AT-devnull): this. + (--clean): Remove AT-* files too. + * doc/autoconf.texi (Limitations of Usual Tools): Document `date'. + Reported by Nicolas Joly. + +2001-08-28 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PREPARE): Don't use single + quotes inside single quotes. + Reported by Nicolas Joly. + +2001-08-28 Kevin Ryde + + * doc/autoconf.texi (Function Portability): Mention C right shifts. + +2001-08-27 Tim Van Holder + + * lib/autotest/general.m4: Reword some messages. + (AT_INIT): Check for the `times' builtin before using it. + Support test ranges as arguments to the testsuite. + Have -e imply -d as the help text suggested. + +2001-08-27 Akim Demaille + + * Makefile.maint: Formatting changes. + (do-po-update, po-update, cvs-update, update): New targets. + (AMTAR): Remove. + +2001-08-27 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT) : Remove. + : New. + Pass it to debug-*.sh scripts. + : May contain absolute dir names. + +2001-08-27 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Log the command line. + Support `VAR=VAL' as arguments. + Compute PATH _after_ the options processing, so that AUTOTEST_PATH + may be set via the command line. + +2001-08-27 Akim Demaille + + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): $2 defaults to $1. + * lib/autotest/autotest.m4 (AT_INIT): Expand AUTOTEST_PATH into + first the build dirs, then the src dirs. + * configure.ac (AC_CONFIG_TESTDIR): Adjust. + +2001-08-27 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Output the definition of + at_data_files earlier. + (--clean, -c): New option. + * tests/Makefile.am: Use this option. + +2001-08-27 Akim Demaille + + * lib/autoconf/status.m4 (_AC_SRCPATHS): Rename `ac_dots' as + `ac_top_builddir' to mimic Automake's vocabulary, which much more + readable. + Adjust callers. + * doc/autoconf.texi (Configuration Actions): Document the vars + available in commands. + Emphasize the risks of collisions in init-cmds. + +2001-08-27 Akim Demaille + + * doc/autoconf.texi (Input) : Move to.. + (Initializing configure): this new node. + +2001-08-27 Akim Demaille + + * Makefile.am (EXTRA_DIST): INSTALL.txt is a dead hack. + +2001-08-27 Akim Demaille + + * m4/atconfig.m4 (AT_CONFIG): Remove, replaced by... + * lib/autoconf/autotest.m4 (AC_CONFIG_TESTDIR): this. + New file. + * m4/Makefile.am (EXTRA_DIST): Oops, adjust... + +2001-08-27 Akim Demaille + + * lib/autoconf/general.m4 (AU_DEFINE, AU_DEFUN, AU_ALIAS): Move + to... + * lib/autoconf/autoheader.m4: this new file. + * lib/autoconf/general.m4 (AH_OUTPUT, AH_VERBATIM) + (_AH_VERBATIM_OLD, AH_TEMPLATE, _AH_TEMPLATE_OLD, AH_TOP, AH_BOTTOM): + Move to... + * lib/autoconf/autoupdate.m4: this new file. + +2001-08-27 Akim Demaille + + * lib/autoconf/status.m4 (_AC_SRCPATHS): New. + (_AC_OUTPUT_LINKS, _AC_OUTPUT_FILES, _AC_OUTPUT_SUBDIRS): Use it. + Standardize the var names (ac_sub_srcdir -> ac_srcdir, ac_subdir + -> ac_dir). + (_AC_OUTPUT_HEADERS): AS_DIRNAME always return a dir name. + * lib/autoconf/general.m4 (_AC_INIT_HELP): Ditto. + +2001-08-27 Akim Demaille + + * lib/autoconf/autoconf.m4 (AC_CONFIG_COMMANDS) + (AC_CONFIG_COMMANDS_POST, AC_CONFIG_COMMANDS_PRE, AC_CONFIG_FILES) + (AC_CONFIG_HEADER, AC_CONFIG_HEADERS, AC_CONFIG_IF_MEMBER) + (AC_CONFIG_LINKS, AC_CONFIG_SUBDIRS, AC_FILE_DEPENDENCY_TRACE) + (AC_LINK_FILES, AC_LIST_COMMANDS, AC_LIST_COMMANDS_COMMANDS) + (AC_LIST_FILES, AC_LIST_FILES_COMMANDS, AC_LIST_HEADERS) + (AC_LIST_HEADERS_COMMANDS, AC_LIST_LINKS, AC_LIST_LINKS_COMMANDS) + (AC_OUTPUT, AC_OUTPUT_COMMANDS, AC_OUTPUT_COMMANDS_POST) + (AC_OUTPUT_COMMANDS_PRE, AC_OUTPUT_MAKE_DEFS) + (_AC_CONFIG_COMMANDS_INIT, _AC_CONFIG_DEPENDENCIES) + (_AC_CONFIG_DEPENDENCY, _AC_CONFIG_UNIQUE, _AC_LINK_FILES_CNT) + (_AC_LIST_SUBDIRS, _AC_OUTPUT_COMMANDS, _AC_OUTPUT_COMMANDS_CNT) + (_AC_OUTPUT_COMMANDS_INIT, _AC_OUTPUT_CONFIG_STATUS) + (_AC_OUTPUT_FILES, _AC_OUTPUT_HEADERS, _AC_OUTPUT_LINKS) + (_AC_OUTPUT_SUBDIRS): Move to... + * lib/autoconf/status.m4: this new file. + * lib/autoconf/general.m4, lib/autoconf/Makefile.am: Adjust. + * tests/Makefile.am, tests/suite.at: Adjust. + +2001-08-27 Akim Demaille + + Automake 1.5. + + * Makefile.am (AUTOMAKE_OPTIONS): Add 1.5 and dist-bzip2. + (AMTAR): Help automake define it. + (INSTALL, install-data-hook): The INSTALL.txt trick is no longer + needed, 1.5 can have a macro and a target with the same name. + * m4/auxdir.m4, m4/cond.m4, m4/depend.m4, m4/install-sh.m4, + * m4/strip.m4: New. + * m4/init.m4, m4/sanity.m4: Update. + * doc/Makefile.am (CLEANFILES): 1.5 knows the texi2dvi files. + * lib/autoconf/Makefile.am, lib/autotest/Makefile.am, + * lib/m4sugar/Makefile.am, lib/autoscan/Makefile.am, + * lib/Autom4te/Makefile.am, man/Makefile.am: Use dist/nodist. + +2001-08-27 Akim Demaille + + Provide a mean to ``AC_PREREQ'' for M4sugar, M4sh and Autotest. + + * lib/autoconf/version.in: Remove. + * lib/m4sugar/version.in: New. + * lib/m4sugar/m4sugar.m4 (m4_acversion, m4_version_prereq): New. + Adjust callers. + * bin/autoupdate.in: Distinguish M4sugar vs. Autoconf macros by + the name of the directory they're in, instead of the filename, + since version.m4 is now in m4sugar, but m4_acversion must not be + classified as an Autoconf macro. + ($input_m4): Don't qualify the path to m4sugar. + Rather, pass autoconf_dir to m4. + * tests/Makefile.am (testsuite): Remove -I top_srcdir, unneeded. + * tests/suite.at: Require 2.52c. + +2001-08-27 Akim Demaille + + testsuite.log should include config.log. + + * lib/autotest/autotest.m4: New. + * lib/autotest/general.m4, tests/atspecific.m4: Adjust. + * tests/suite.at : Adjust. + (AT_INIT): Log config.log. + * lib/m4sugar/m4sugar.m4 (m4_text_box): New. + * lib/m4sugar/m4sh.m4 (_AS_BOX_LITERAL): Adjust. + * lib/autoconf/general.m4 (_AC_INIT_CONFIG_LOG): Use them. + (_AC_INIT_PREPARE): Fix the incredibly messy and buggy completion + of config.log on traps. + (_AC_OUTPUT_CONFIG_STATUS): Use AS_BOX. + Use consistently `_ACEOF' for configure's here docs, and `_CSEOF' + for config.status'. + Open the log as soon as possible. + Use the same log introduction as configure's. + +2001-08-22 Paul Eggert + + * doc/autoconf.texi (Indices): New node. + Move indices out of the top level menu and into this submenu. + +2001-08-22 Akim Demaille + + * lib/autoconf/programs.m4 (_AC_PROG_LEX_YYTEXT_DECL): Use + AC_TRY_COMMAND. + (AC_DECL_YYTEXT): Fix the previous patch: it points to AC_PROG_LEX. + +2001-08-22 Akim Demaille + + * lib/autoconf/general.m4 (AC_SHELL_PATH_WALK, AC_CHECK_PROG) + (AC_CHECK_PROGS, AC_PATH_PROG, AC_PATH_PROGS, AC_CHECK_TOOL_PREFIX) + (AC_PATH_TOOL, AC_CHECK_TOOL, AC_CHECK_TOOLS): Move to... + * lib/autoconf/programs.m4: here. + * lib/autoconf/specific.m4 (_AC_PROG_ECHO, AC_PROG_MAKE_SET) + (AC_PROG_RANLIB, AC_PROG_YACC, AC_PROG_LEX, _AC_DECL_YYTEXT) + (AC_PROG_INSTALL, AC_PROG_LN_S, AC_RSH): Move to... + * lib/autoconf/programs.m4: here. + (_AC_DECL_YYTEXT): Rename as... + (_AC_PROG_LEX_YYTEXT_DECL): this. + * lib/autoconf/autoconf.m4, lib/autoconf/Makefile.am + * tests/Makefile.am, tests/suite.am: Adjust. + +2001-08-22 Akim Demaille + + * lib/autoconf/general.m4 (AC_LIST_MEMBER_OF, AC_LINKER_OPTION): + Move to... + * lib/autoconf/fortran.m4 (_AC_LIST_MEMBER_IF, _AC_LINKER_OPTION): + here. + * lib/autoconf/general.m4 (AC_TRY_LINK_FUNC): Move to... + * lib/autoconf/functions.m4: here. + * lib/autoconf/general.m4 (AC_SEARCH_LIBS, AC_CHECK_LIB) + (AH_CHECK_LIB): Move to... + * lib/autoconf/libs: this new file. + * lib/autoconf/specific.m4 (_AC_PATH_X_XMKMF, _AC_PATH_X_DIRECT) + (_AC_PATH_X, AC_PATH_X, AC_PATH_XTRA): Move to... + * lib/autoconf/libs.m4: here. + * lib/autoconf/autoconf.m4, lib/autoconf/Makefile.am: Adjust. + +2001-08-22 Akim Demaille + + * lib/m4sugar/m4sh.m4 (AS_MKDIR_P): Fail if fails. + * lib/autoconf/general.m4 (_AC_OUTPUT_SUBDIRS): Adjust. + (AC_SITE_LOAD): Better logging of config.site. + +2001-08-20 Akim Demaille + + * configure.ac (AT_CONFIG): Fix the path. + * m4/atconfig.m4 (AT_CONFIG): Don't use EOF but ATEOF so that 2.52 + can be used. + +2001-08-20 Alexandre Duret-Lutz + + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Prepare the cross-compile + program with AC_LANG_PROGRAM before feeding it to + AC_COMPILE_IFELSE. Cleanup grep usage. + +2001-08-20 Akim Demaille + + * ChangeLog, ChangeLog.0, ChangeLog.1, ChangeLog.2, AUTHORS, BUGS, + * NEWS, README, README-alpha, TODO, tests/README: This package is + `Autoconf', not `autoconf' (the executable). + +2001-08-20 Akim Demaille + + Info readers seem to need `Index' in the index node title :( + + * doc/autoconf.texi: Reverse the 2001-08-15 change which + simplified index node names. + +2001-08-20 Akim Demaille + + * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Warn if the + arguments are not literals. + * doc/autoconf.texi (Input) : Arguments must be literals. + Specify the output variables, and macros defined. + +2001-08-20 Akim Demaille + + * doc/autoconf.texi (Examining Declarations) : + (Examining Syntax) + (Examining Libraries) + (Test Programs) : These macros double quote some of + their arguments. + Reported by Werner Lemberg. + +2001-08-20 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Compute top_builddir, + top_srcdir and srcdir from at_topbuild_2_topsrc and at_testdir. + Load atlocal late enough to dump it in the log. + * m4/atconfig.m4 (AT_CONFIG): Pass them to atconfig. + +2001-08-20 Akim Demaille + + * tests/torture.at (Configuring subdirectories): New test. + * lib/autoconf/general.m4 (_AC_INIT_SRCDIR): Say what you are + looking for. + * m4/atconfig.m4: Be sure the let $[0] be expandable. + (top_srcdir): Fix its computation. + +2001-08-20 Akim Demaille + + * lib/autoconf/general.m4 (_AC_OUTPUT_COMMANDS): Say what you do. + * m4/atconfig.m4 (AT_CONFIG): $1 is now the directory where the + test suite lives. + Create `atconfig' automagically. + Configure atlocal.in if present. + * tests/atconfig.in: Remove. + * tests/atlocal.in: New. + * tests/Makefile.am: Adjust. + +2001-08-20 Akim Demaille + + Huh!?!?! There are still some user EOF tags used, which prevents + their use in AC_CONFIG_COMMANDS for instance... + + * lib/autoconf/general.m4, lib/autoconf/specific.m4, + * lib/autotest/general.m4: Rename the EOF tags as `_ACEOF', + `_CSEOF', or `_ATEOF', as appropriate. + * lib/m4sugar/Makefile.am, lib/autoconf/Makefile.am, + * lib/autotest/Makefile.am (check-local): Enforce this constraint. + +2001-08-20 Akim Demaille + + * tests/base.at, tests/m4sh.at, tests/m4sugar.at, + * tests/semantics.at, tests/tools.at, tests/torture.at: + s/^AT_DATA\(([^][]+),/AT_DATA([$1],/. + +2001-08-20 Akim Demaille + + Autotest invokes M4sh's initialization. + + * lib/autotest/general.m4: Adjust the diversion names. + (AT_INIT): Run AS_INIT. + Use the BINSH diversion to invoke /bin/sh. + * tests/base.at, tests/m4sh.at, tests/m4sugar.at, tests/tools.at: + * tests/torture.at: Respect M4sugar and M4sh macro name spaces. + +2001-08-20 Akim Demaille + + Let M4sh have its own diversions. + + * lib/autoconf/general.m4 (_m4_divert(BINSH), _m4_divert(REVISION)) + (_m4_divert(NOTICE)): Rename as... + * lib/m4sugar/m4msh.m4 (_m4_divert(BINSH), _m4_divert(HEADER-REVISION)) + (_m4_divert(HEADER-COMMENT)): these. + (_m4_divert(HEADER-COPYRIGHT), _m4_divert(HEADER-COPYRIGHT)): New. + (_m4_divert(NOTICE)): New, for Libtool. + * lib/autoconf/general.m4 (_m4_divert(PREPARE)): Remove, replaced + long ago with `_m4_divert(GROW)'. + (AC_COPYRIGHT, AC_REVISION, _AC_INIT_NOTICE): Adjust. + +2001-08-20 Akim Demaille + + * tests/base.at, tests/compile.at, tests/foreign.at, + * tests/m4sh.at, tests/m4sugar.at, tests/mktests.sh, + * tests/semantics.at, tests/suite.at, tests/tools.at, + * tests/torture.at: Ask Autotest mode, not Autoconf mode. + +2001-08-20 Akim Demaille + + * bin/autom4te.in (handle_output): Handle @__@. + +2001-08-20 Akim Demaille + + * lib/autoconf/autoconf.m4, lib/autoconf/oldnames.m4, + * lib/autotest/general.m4: Adjust the license. + +2001-08-17 Paul Eggert + + * doc/autoconf.texi (Function Portability): Mention snprintf, + following up on a suggestion by Kevin Ryde. + +2001-08-17 Akim Demaille + + * doc/install.texi, doc/autoconf.texi: Use `autoconf', not + `autoconf_manual', as texinfo.tex 2001-06-21.10 chokes on it. + +2001-08-17 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Refer to `$as_me.log', not + `$0.log' as for projects where testsuite is in src, we'd have + testsuite.log created in src. + +2001-08-17 Akim Demaille + + * bin/autom4te.in (&parse_args): Recognize --normalize. + +2001-08-17 Akim Demaille + + Start implementing the AC_CHECK_HEADER transition scheme. + + * lib/autoconf/headers.m4 (_AC_CHECK_HEADER_NEW) + (_AC_CHECK_HEADER_OLD, _AC_CHECK_HEADER_MONGREL): New. + (AC_CHECK_HEADER): Use them. + +2001-08-17 Akim Demaille + + * doc/autoconf.texi: Work around Texinfo buglets. + (Transformation Rules): One example is enough, users are expected + to have their brains on. And BTW, use DESTDIR. + (dvar): New macro. Use it. + +2001-08-17 Akim Demaille + + * doc/autoconf.texi (Writing testsuite.at) : Complete. + * lib/autotest/general.m4 (AT_INIT): Use the relative dir when + looking for ChangeLogs. + +2001-08-17 Akim Demaille + + * bin/autom4te.in: --normalize is a new option. + * bin/autoconf.in: Use it. + +2001-08-17 Akim Demaille + + * bin/Makefile.am, lib/Autom4te/Makefile.am, lib/autoconf/Makefile.am + * lib/autotest/Makefile.am, lib/m4sugar/Makefile.am: Add TAGS support. + +2001-08-16 Paul Eggert + + * doc/autoconf.texi, doc/install.texi: Put copyright notice at + start, not at end. + +2001-08-15 Akim Demaille + + * doc/Makefile.am (fu): New index, can't use fn because of defmac. + Use it. + +2001-08-15 Akim Demaille + + * doc/autoconf.texi (pr): New index. + (prindex, findex): Use, merge, and output them. + (Environment Variable Index, Output Variable Index) + (Preprocessor Symbol Index, Autoconf Macro Index, M4 Macro Index) + (Autotest Macro Index): Rename as... + (Environment Variables, Output Variables,Preprocessor Symbols) + (Autoconf Macros, M4 Macros, Autotest Macros): these. + * doc/install.texi: Use @command. + (Environment Variables): Rename as... + (Defining Variables): this. + +2001-08-15 Akim Demaille + + * doc/autoconf.texi (Function Portability): sprintf's return + value. + From Kevin Ryde. + +2001-08-15 Akim Demaille + + * Makefile.maint (CVS): New. + (local-check): Run changelog-check. last. + (alpha): Don't depend upon local-check, since... + (cvs-dist): depends upon it. + +2001-08-15 Tim Van Holder + + * tests/Makefile.am: Use a clean-local rule to remove + autom4te.cache (it's a directory, not a file. + * Makefile.am: Ditto (but maintainer-clean-local). + +2001-08-15 Akim Demaille + + * bin/autom4te.in (@m4_warning): New. + (&handle_m4): Use it. + * tests/m4sugar.at (m4_warn): Pass `-f' to autom4te to ensure the + warnings are issued at each run. + * tests/atspecific.m4 (AT_CHECK_M4SUGAR, AT_CHECK_M4SH): M4sugar + is in the src tree. + +2001-08-15 Akim Demaille + + * tests/atspecific.m4 (AT_CHECK_AUTOUPDATE): Perl is now required: + don't waste time running `autoupdate --version' works. + * tests/tools.at (autoupdating AC_PREREQ): Likewise. + +2001-08-13 Akim Demaille + + * doc/autoconf.texi (ma): Rename this index as... + (ac): this. + +2001-08-13 Akim Demaille + + * Makefile.am: Remove dead code and dead comments. + (pdf, html): New targets. + * doc/autoconf.texi (Using Autotest): New chapter. + * doc/Makefile.am (pdf): New targets. + (CLEANFILES): Adjust. + +2001-08-13 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): Log the start/stop dates and + duration of the test suite. + +2001-08-12 Alexandre Duret-Lutz + + * tests/semantics.at (AC_C_BIGENDIAN): Explicitelly save and load + endianness for comparison instead of relying on AT_CHECK_ENV. + +2001-08-11 Paul Eggert + + * doc/autoconf.texi, doc/install.texi: Add a copyright notice + to the INSTALL file. + +2001-08-11 Paul Eggert + + * NEWS: The autoconf manual now is distributed under the terms + of the GNU Free Documentation License. + + * doc/autoconf.texi: Switch from old style copyright notice to FDL. + Add an appendix "Copying This Manual" for the FDL. + + * doc/fdl.texi: New file, from + . + + * doc/Makefile.am (autoconf_TEXINFOS): Add fdl.texi. + +2001-08-10 Paul Eggert + + * AUTHORS, BUGS, ChangeLog, ChangeLog.0, ChangeLog.1, + ChangeLog.2, GNUmakefile, Makefile.maint, NEWS, README, + README-alpha, TODO, configure.ac, lib/autoconf/Makefile.am, + m4/atconfig.m4, m4/init.m4, m4/m4.m4, m4/missing.m4, + m4/sanity.m4, tests/README, tests/aclocal.m4, + tests/atspecific.m4, tests/base.at, tests/compile.at, + tests/foreign.at, tests/m4sh.at, tests/m4sugar.at, + tests/semantics.at, tests/suite.at, tests/tools.at, + tests/torture.at: Add copyright notice. + + * tests/mktests.sh: Update year in copyright notice. + +2001-08-12 Alexandre Duret-Lutz + + * tests/semantics.at (AC_C_BIGENDIAN): New test. + +2001-08-11 Alexandre Duret-Lutz + + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Handle ACTION-IF-TRUE, + ACTION-IF-FALSE, and ACTION-IF-UNKNOWN. + * doc/autoconf.texi (C Compiler Characteristics): Update + documentation for AC_C_BIGENDIAN. + +2001-08-11 Alexandre Duret-Lutz + + * lib/autoconf/c.m4 (AC_C_BIGENDIAN): Guess endianness by grep'ing + magic values from an object file when cross-compiling. + Based on code by Guido Draheim . + +2001-08-10 Akim Demaille + + * bin/autom4te.in (&handle_output): Don't use `grep' with side + effects. + Suggested by Russ Allbery. + +2001-08-10 Ralf Corsepius + + * lib/autoconf/general.m4 (_AC_OUTPUT_SUBDIRS): Propagate the + current $prefix to the sub-configures. + +2001-08-09 Tim Van Holder + + * lib/autoconf/lang.m4: Ignore *.xSYM when looking for an executable + extension (needed on BeOS). Reported by Guido van Rossum. + +2001-08-09 Akim Demaille + + * bin/autom4te.in ($icache): Load it only if older than autom4te. + +2001-08-07 Akim Demaille + + * lib/autotest/general.m4 (AT_INIT): All the `at-*' are to be + removed. + (at-setup-line): Huh? Be a variable `at_setup_line', not a file. + No need to remove the files before and after the each test, before + each test and at the end of the suite is enough. + Display only the children `times', not the shell's. + If the test failed or was skipped, at-times is not available. + +2001-08-07 Akim Demaille + + Always produce testsuite.log, including when there are no + failures. This helps getting information on skipped tests, and + duration of the tests. Err, implement the latter btw. + + * lib/autotest/general.m4 (AT_INIT): Set up fd 6 for the log. + Dump information on the first run of each test. + (AT_CLEANUP): Create `at-times' containing the duration of the + test group. + +2001-08-07 Akim Demaille + + The use of `dumpstat' revealed that `len' was used although it + should not. m4_text_wrap was using it, but in the Autoconf world + where it is legal. Hence (i) test M4sh in its own world, not + Autoconf's, and (ii), ahem, fix the bug :) + + * lib/autotest/general.m4: Be sure the set good quotes, as tracing + does not like `' instead of []. + (AT_INIT): Forbid `^_?AT_'. + And don't output such tokens. + * tests/Makefile.am (CLEANFILES): Add `script', `script.s4g', + `script.as', and `autom4te.cache'. + Remove `empty' and `macro' which are no longer used. + * tests/atspecific.m4 (AT_CHECK_M4SUGAR, AT_CHECK_M4SH): New. + * tests/m4sugar.at: Use it. + * lib/m4sugar/m4sugar.m4: Use `m4_len' not `len'. + +2001-08-07 Akim Demaille + + * bin/autoconf.in, bin/autoheader.in: --force, -f is a new option. + +2001-08-07 Alexandre Duret-Lutz + + * bin/autom4te.in (handle_output): Typo in quadrigraph substitution. + +2001-08-04 Akim Demaille + + * lib/autoconf/functions.m4 (AC_FUNC_ALLOCA, AC_FUNC_ERROR_AT_LINE) + (AC_FUNC_FSEEKO, AC_FUNC_OBSTACK): Use AC_LANG_IFELSE, not + AC_TRY_LINK. + * lib/autoconf/headers.m4 (AC_HEADER_MAJOR): Likewise. + * lib/autoconf/fortran.m4 (_AC_LANG_PROGRAM_C_F77_HOOKS) + (AC_F77_MAIN): Likewise. + +2001-08-04 Akim Demaille + + Don't rely on M4sugar outputting the patterns in files, since we + might process the output _without_ running m4, hence without these + files. + + * lib/m4sugar/m4sugar.m4 (m4_init): No need for `m4_tmpdir'. + * bin/autom4te.in (@Request::includes): Remove, unused. + (@Request::source): Rename as... + (@Request::input): this. + (@preselect): Add `m4_pattern_forbid' and `m4_pattern_allow'. + (&handle_output): Fetch the patterns from the traces. + `$forbidden' and `$allowed' are constant: use m//o. + (&handle_m4): M4sugar no longer wants `m4_tmpdir'. + (m4_pattern_forbid, m4_pattern_allow): Adjust for tracing only. + +2001-08-04 Akim Demaille + + `autoconf && autoheader' is sped up. Now, speed up `autoheader && + autoconf', i.e., in addition to caching traces, cache the output. + + * bin/autom4te.in (Request::cache): Rename as... + (Request::id): this. + ($cache, $icache, $tcache, $ocache): New. + (&handle_m4): Save M4 output in the cache instead of $tmp. + (&handle_output): Adjust. + (&up_to_date_p): Check that the output cache is up to date too. + (top level): Run `&handle_m4' iff force or the cache is invalid. + Run `&handle_output' if the output cache is more recent. + +2001-08-04 Akim Demaille + + * bin/autom4te.in ($force): New. + (&parse_args, &print_usage): -f, --force is a new option. + (&handle_output): CPP directives might have spaces after `#'. + (&parse_args): The first file only can be frozen. + +2001-08-04 Akim Demaille + + Don't let autom4te compute the `include' traces several times: + first check that the trace cache file is up to date, and then + compare its timestamp with that of the output. + + * bin/autom4te.in, bin/autoupdate.in, bin/autoscan.in: Normalize + the preamble. Don't require 5.005 as Autom4te::General does it, + and better yet (use `use', not `require'!). + * lib/Autom4te/Struct.pm: Rename the last occurrences of + Class::Struct as Autom4te::Struct. + * lib/Autom4te/General.pm (File::stat): Use it. + (&mtime): New, export it. + * bin/autom4te.in: Use it. + Declare `$req' is invalid if it is outdated. + Don't declare it valid before saving it if something went wrong. + +2001-08-04 Akim Demaille + + Autom4te shall not encode Autoconf data, and preselecting traces + must be proposed to the users. + + * bin/autom4te.in (@required_trace): Remove. + (@preselect): New. + (&parse_args, &print_usage): -p, --preselect is a new option. + (&up_to_date_p): Adjust. + * bin/autoconf.in: Preselect some Autoconf macros. + +2001-08-04 Akim Demaille + + * tests/tools.at (autoconf --trace: user macros): Check traces on + macros invoked without arguments, and macros invoked with multiple + lines arguments. + +2001-08-03 Alexandre Duret-Lutz + + * bin/autom4te.in (handle_traces): Fix rewriting of traces without + arguments. + +2001-08-03 Akim Demaille + + * bin/autoconf.in ($@): Work around the usual sh bug. + From Nicolas Joly. + +2001-08-03 Akim Demaille + + Clean up the handling of the M4 builtins tracing exception. + + * bin/autom4te.in (Request::request): Don't complete M4 builtins + trace requests. + (@m4_builtins): Rename as... + (@m4_builtin): this. + (%m4_builtin_alternate_name): New. + (&parse_args): Complete the trace requests with alternate names. + (&handle_traces): Hence no longer do it here. + (&trace_requests): Remove, unused. + +2001-08-03 Akim Demaille + + * doc/autoconf.texi (Redefined M4 Macros): Document m4_exit, + m4_if, and m4_wrap. + +2001-08-03 Akim Demaille + + * lib/m4sugar/m4sugar.m4 (m4_init): Also forbid `_m4_*' tokens. + (m4_divert_pop): Dump the whole diversion stack when a diversion + mismatch happens. + * bin/autom4te.in (&handle_output): Remember of the first + occurrence of a possibly undefined macro, not the last. + Complain about the possibly undefined macros in the same order as + the appear in the output. + * lib/autoconf/Makefile.am (autoconf.m4f): List its dependencies. + * tests/tools.at (autoconf: forbidden tokens, basic) + (autoconf: forbidden tokens, exceptions): No longer sort + autoconf's stderr, as it is now deterministic. + Check that `dnl' is caught. + +2001-08-01 Akim Demaille + + * configure.ac: Bump to 2.52c. + +2001-08-01 Akim Demaille + + Version 2.52b. + + * lib/Autom4te/Makefile.am (perllibdir): s/Autoconf/Autom4te/. + +2001-08-01 Akim Demaille + + Version 2.52a. + +2001-08-01 Akim Demaille + + * lib/Autom4te/General.pm: Use `carp' and `croak', not `warn' and + `die'. + (&END): New. + * bin/autoconf.in, bin/autom4te.in, bin/autoupdate.in: Remove your + `END', as `Autom4te::General::END' will be triggered. + * bin/autoupdate.in, bin/autoscan.in: Improve error messages accuracy. + * bin/autoupdate.in (File::Compare, File::Copy): Use them instead of + system to run `mv', `rm', and `cmp'. + +2001-08-01 Akim Demaille + + * lib/Autom4te/General.pm (&unique): New. + * bin/autoscan.in (&output): Use it to issue trace requests once. + +2001-08-01 Akim Demaille + + * lib/Autom4te/General.pm: New. + * bin/autom4te.in (Autom4te::General): Use it. + ($me, $tmp, $verbose, $debug, &mktmpdir, &verbose, &xsystem) + (&find_configure_ac, &find_slave): Remove. + * bin/autoscan.in: Likewise. + * bin/autoupdate.in: Likewise. + +2001-08-01 Akim Demaille + + * autoconf.in, autom4te.in, autoscan.in, ifnames.in, + * autoheader.in, autoreconf.in, autoupdate.in: Move to... + * bin: here, new directory. + * lib/Autoconf: Rename as... + * lib/Autom4te: this, to please case insensitive junkie OSes. + +2001-08-01 Akim Demaille + + * autom4te.in ($m4): Handle the --nesting-limit. + * autoconf.in (M4): Remove. + +2001-08-01 Akim Demaille + + * autoconf.in ($AWK): Remove, no longer used. + * test/tools.at: Use AT_CHECK_AUTOCONF. + (AWK portability): Remove, for autoconf no longer uses AWK. + (Syntax of the Perl scripts): New. + * configure.ac: autoconf no longer needs an AWK with a good + regexp engine. + Use a static test on AC_PACKAGE_VERSION. + * autom4te.in (&up_to_date_p): Output depends on the arguments. + * lib/autoconf/Makefile.am: Ship version.m4, maintainer file. + * tests/atconfig.in (PERL): New. + +2001-08-01 Akim Demaille + + * lib/autoconf/lang.m4 (AC_LANG(C), AC_LANG_C, _AC_LANG_ABBREV(C)) + (AC_LANG(C++), AC_LANG_CPLUSPLUS, _AC_LANG_ABBREV(C++)) + (AC_LANG_SOURCE(C), AC_LANG_PROGRAM(C), AC_LANG_CALL(C)) + (AC_LANG_FUNC_LINK_TRY(C), AC_LANG_BOOL_COMPILE_TRY(C)) + (AC_LANG_INT_SAVE(C), _AC_ARG_VAR_CPPFLAGS, _AC_ARG_VAR_LDFLAGS) + (AC_LANG_PREPROC(C), _AC_PROG_PREPROC_WORKS_IFELSE, AC_PROG_CPP) + (AC_LANG_COMPILER(C), ac_cv_prog_gcc, AC_PROG_CC, _AC_PROG_CC_G) + (AC_PROG_GCC_TRADITIONAL, AC_PROG_CC_C_O, AC_LANG_PREPROC(C++)) + (AC_PROG_CXXCPP, AC_LANG_COMPILER(C++), ac_cv_prog_gxx) + (AC_PROG_CXX, _AC_PROG_CXX_G, _AC_PROG_CXX_EXIT_DECLARATION) + (AC_PROG_CC_STDC, AC_C_CROSS, AC_C_CHAR_UNSIGNED, AC_C_LONG_DOUBLE) + (AC_C_BIGENDIAN, AC_C_INLINE, AC_C_CONST, AC_C_VOLATILE) + (AC_C_STRINGIZE, AC_C_PROTOTYPES): Move to... + * lib/autoconf/c.m4: here, new file. + + * lib/autoconf/lang.m4 (AC_LANG(Fortran 77), AC_LANG_FORTRAN77) + (_AC_LANG_ABBREV(Fortran 77), AC_LANG_SOURCE(Fortran 77)) + (AC_LANG_PROGRAM(Fortran 77), AC_LANG_CALL(Fortran 77)) + (AC_LANG_PREPROC(Fortran 77), AC_LANG_COMPILER(Fortran 77)) + (ac_cv_prog_g77, AC_PROG_F77, _AC_PROG_F77_G, AC_PROG_F77_C_O) + (_AC_PROG_F77_V_OUTPUT, _AC_PROG_F77_V, AC_F77_LIBRARY_LDFLAGS) + (AC_F77_DUMMY_MAIN, _AC_LANG_PROGRAM_C_F77_HOOKS, AC_F77_MAIN) + (_AC_F77_NAME_MANGLING, AC_F77_NAME_MANGLING, AC_F77_WRAPPERS) + (AC_F77_FUNC): Move to... + * lib/autoconf/fortran.m4: here, new file. + +2001-08-01 Akim Demaille + + * acfunctions.m4: Rename as... + * lib/autoconf/functions.m4: this. + * acgeneral.m4: Rename as... + * lib/autoconf/general.m4: this. + * acheaders.m4: Rename as... + * lib/autoconf/headers.m4: this. + * aclang.m4: Rename as... + * lib/autoconf/lang.m4: this. + * acoldnames.m4: Rename as... + * lib/autoconf/oldnames.m4: this. + * acspecific.m4: Rename as... + * lib/autoconf/specific.m4: this. + * actypes.m4: Rename as... + * lib/autoconf/types.m4: this. + * autoconf.m4: Rename as... + * lib/autoconf/autoconf.m4: this. + + * m4sugar.m4: Rename as... + * lib/m4sugar/m4sugar.m4: this. + * m4sh.m4: Rename as... + * lib/m4sugar/m4sh.m4: this. + + * tests/atgeneral.m4: Rename as... + * lib/autotest/general.m4: this. + + * acfunctions: Rename as... + * lib/autoscan/functions: this. + * acheaders: Rename as... + * lib/autoscan/headers: this. + * acidentifiers: Rename as... + * lib/autoscan/identifiers: this. + * aclibraries: Rename as... + * lib/autoscan/libraries: this. + * acmakevars: Rename as... + * lib/autoscan/makevars: this. + * acprograms: Rename as... + * lib/autoscan/programs: this. + +2001-08-01 Akim Demaille + + * doc/autoconf.texi: Moving/deleting open files is not portable. + Portability issues for `.' (source), and more information about sed. + +2001-07-25 Steven G. Johnson + + * aclang.m4 (AC_F77_LIBRARY_LDFLAGS): Ignore -libmil (on Solaris), + which has a special meaning and is not a reference to libibmil.a. + Reported by Matteo Frigo. + +2001-07-25 Pavel Roskin + + * autom4te.in (mktmpdir): Strip trailing newline from mktemp + output. + +2001-07-25 Akim Demaille + + * autoconf.in: Try to define the variables before using them. + * autom4te.in ($perllibdir): Use `$autom4te_perllibdir' as envvar + instead of `$perllibdir'. + * tests/atconfig.in ($autom4te_perllibdir): Export it. + +2001-07-25 Akim Demaille + + * autoconf.in (ac_LF_and_DOT): Remove, unused. + +2001-07-24 Akim Demaille + + Let autoconf use autom4te for traces. + + * autoconf.in ($task, task trace): Remove, merely pass --trace to + autom4te. + * autoheader.in: Don't pass `-' to autoconf, rather, a tmp file. + (Because I found no way for autom4te to accept `-'). + * autom4te.in (&Request::request): Beware of M4 builtins. + (END): Don't try to remove the content of an empty dir. + (&parse_args): Default is `$f:$l:$n:$%', not `$f:$l:$n:$*'. + (&handle_output): Set a default value to `$forbidden'. + * autoupdate.in (&verbose, &xsystem): New, from autom4te.in. + ($autoconf): Pass --debug and --verbose. + * tests/atspecific.m4 (AT_CHECK_AUTOCONF): Clean up autom4te's + cache. + +2001-07-24 Akim Demaille + + Let autoconf use autom4te to create configure. + + * autoconf.in ($automate): New var. + (task script): Use autom4te. + * autom4te.in (File::Spec): Use it. + (&find_file): New. + (&parse_args): --warning is -W, not -w. + Find the top level files. + (&handle_m4): Pass the warnings flags. + Don't report verbosely m4's failures, unless requested. + (&handle_output): Don't complain for forbidden tokens in comments. + Be sure to report all the forbidden tokens within a single line. + (&trace_format_to_m4): Preserve `$_'. + (&handle_traces): Sort the output macros. + (&up_to_date_p): Find the files before trying to get its time stamp. + +2001-07-24 Akim Demaille + + * Makefile.am: Ship, build and install Autom4te. + (SUBDIRS): Add lib. + * lib/Autoconf/Struct.pm: New, from Automake 1.5. + * configure.in: Require Perl. + * man/autom4te.in: New. + +2001-07-19 Paul Eggert + + * doc/autoconf.texi (Cache Checkpointing): Use AC_MSG_ERROR in + example, rather than (exit 1); exit (which isn't portable). + +2001-07-18 Akim Demaille + + Version 2.52. + +2001-07-18 Akim Demaille + + The C-Fortran 77 hooks are available only once AC_F77_DUMMY_MAIN + was run, while they are needed also when it is expanded. + Reported by Nicolas Joly. + + * aclang.m4 (AC_F77_DUMMY_MAIN): Define _AC_LANG_PROGRAM_C_F77_HOOKS. + (AC_LANG_PROGRAM(C)): Use it instead of depending upon + AC_F77_DUMMY_MAIN being expanded. + +2001-07-18 Akim Demaille + + * configure.in: Bump to 2.51a. + +2001-07-17 Akim Demaille + + Version 2.51. + +2001-07-17 Akim Demaille + + * aclang.m4 (AC_F77_DUMMY_MAIN): Let the interface be more + Autoconfy: $1 = action-if-found, $2 = action-if-not-found. + +2001-07-17 Akim Demaille + + The runtime test for AC_FUNC_GETPGRP fails when prototypes are + used. Well, then use the prototypes when you can, and runtime as + a last resort. + Reported by Artur Frysiak + + * acfunctions.m4 (_AC_FUNC_GETPGRP_TEST): New. + (AC_FUNC_GETPGRP): Use it. + First try to compile with 0-ary or 1-ary calls. + +2001-07-17 Akim Demaille + + * actypes.m4 (_AC_CHECK_TYPE_REPLACEMENT_TYPE_P): `foo_t' is a + replacement type. + From Paul Eggert. + +2001-07-17 Akim Demaille + + * Makefile.maint: Sync. with cppi 1.10. + +2001-07-17 Akim Demaille + + * aclang.m4 (AC_LANG_PROGRAM(C)): Output F77_DUMMY_MAIN only when + AC_F77_DUMMY_MAIN has been run. + From Pavel Roskin and Steven G. Johnson. + +2001-07-17 Akim Demaille + + * configure.in: Rename as... + * configure.ac: this. + +2001-07-17 Akim Demaille + + * Makefile.am (INSTALL.txt): Don't use $@ and $< in non suffix + rules. + From Marc Espie. + * Makefile.maint (release-archive-dir): Rename as... + (release_archive_dir): this, so that it can be specialized in + Makefile. + +2001-07-14 Akim Demaille + + * configure.in: Bump to 2.50d. + +2001-07-14 Akim Demaille + + Version 2.50c. + * Makefile.maint (alpha): Typo. + +2001-07-14 Akim Demaille + + * doc/autoconf.texi (Limitations of Make): Macro names and underscore. + +2001-07-14 Akim Demaille + + * config/config.guess, config/config.sub, config/texinfo.tex + * doc/standards.texi, doc/make-stds.texi: Update. + +2001-07-14 Akim Demaille + + * Makefile.maint (cvs-check, cvs-tag-check, cvs-diff-check): New. + +2001-07-14 Akim Demaille + + * Makefile.maint (maintainer-check): Rename as... + (maintainer-distcheck): this. + (changelog-check, static-check): New. + Use them. + +2001-07-14 Kevin Ryde + + * doc/autoconf.texi (C++ Compilers Characteristics): Last resort + for CXX is g++, not gcc. + +2001-07-14 Akim Demaille + + * doc/autoconf.texi (Files): New subsection. + +2001-07-14 Akim Demaille + + * doc/autoconf.texi (C Compiler, Fortran 77 Compiler): Be subsections + of... + (Generic Compiler Characteristics): this. + (C++ Compiler): New subsection. + +2001-07-14 Akim Demaille + + * autoscan.in: Use IO::File. + Adjust all the routines to use it. + ($log): New file (autoscan.log). + (output): Dump detailed logs into $log, and a shortened version to + stderr. + (&scan_makefile): Refine the regexp catching tokens in the code. + * doc/autoconf.texi (autoscan Invocation): Document `autoscan.log' + and the `configure.ac' checking feature. + +2001-07-12 Akim Demaille + + For some AWK, such as on HPUX 11, `xfoo' does not match `foo|^bar'. + Reported by Michael Elizabeth Chastain. + + * autoconf.in: Refuse such AWK. + * configure.in: Likewise. + * Makefile.am (acversion.m4): Do not use move-if-change this file + has dependencies. + * doc/autoconf.texi (Fortran 77 Compiler): Some typos. + +2001-07-10 Jens Petersen + + * autoscan.in (&scan_makefile): Improve programs regexp to parse + things like "g++", "file.c" and "some-conf" as tokens. + (&scan_file): Match C++ files extensions. + If the filename extension is C++ then ask for c++. + +2001-07-05 Steven G. Johnson + + * aclang.m4 (AC_F77_DUMMY_MAIN): Use AC_TRY_LINK, not + AC_TRY_LINK_FUNC, to check whether defining a dummy + main-like routine is needed for linking with F77 libs. + +2001-07-05 Pavel Roskin + + * aclocal.m4 (_AC_PROG_CXX_EXIT_DECLARATION): Remove conftest* + after using break. + (_AC_PROG_F77_V_OUTPUT): Remove conftest*, not conftest.* after + linking. + +2001-07-05 Akim Demaille + + * Makefile.am (move_if_change): New. Use it instead of `mv'. + (acversion.m4): Name it `$(srcdir)/acversion.m4' to ease broken + Makes' lives. + Reported by Nicolas Joly. + +2001-07-04 Akim Demaille + + * acgeneral.m4 (_AC_RUN_IFELSE): Remove conftest.o when cleaning + up. + * acfunctions.m4 (AC_FUNC_WAIT3): Use `break' to silent some + warnings from compilers. + * aclang.m4 (_AC_LANG_COMPILER_GNU): Log the version information + for all the compilers, not only GNU. Hence move from here... + (AC_PROG_CC, AC_PROG_CXX, AC_PROG_F77): to here. + +2001-07-04 Akim Demaille + + * acfunctions.m4 (AC_FUNC_STRTOD, AC_FUNC_STRERROR_R) + (AC_FUNC_STRCOLL, AC_FUNC_WAIT3): Use AC_RUN_IFELSE and + AC_COMPILE_IFELSE. + +2001-07-04 Akim Demaille + + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): Actually apply + the ``strings.h'' change claimed below. + +2001-07-04 Akim Demaille + + * aclang.m4 (_AC_LANG_COMPILER_GNU): s/-dumpspecs/-v/. + +2001-07-04 Akim Demaille + + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): Include + strings.h if usable with string.h. + Suggested by Paul Eggert. + +2001-07-04 Akim Demaille + + * autoscan.in (&scan_file): Skip FILE if there is FILE.in. + From Jens Petersen. + +2001-07-03 Akim Demaille + + * acgeneral.m4 (_AC_OUTPUT_CONFIG_STATUS): Specify CONFIG_FILES + etc. in the log. + +2001-07-03 Akim Demaille + + * acheaders.m4 (AC_CHECK_HEADER): When INCLUDES are set, use the + compiler, not the preprocessor. + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): No longer use + dedicated code to check for inttypes.h, as AC_CHECK_HEADERS does + the right thing. + * Makefile.am (.m4.m4f): Emphasize M4 error messages and fail + earlier if there are. + +2001-07-03 Akim Demaille + + * autoscan.in ($initfile): Remove. + (&find_file): Rename as... + (&scan_file): this. + Immediately scan the current file, instead of gathering them, and + later having them handled by &scan_files. + (&scan_files): Merely invoke Find::File. + Adjust. + +2001-07-02 Akim Demaille + + * autoscan.in: Formatting changes, matching the invocation order. + (File::Find): Use it instead of Perl 4's `find.pl'. + (&wanted): Rename as... + (&find_file): this. + +2001-07-01 Pavel Roskin + + * aclang.m4 (AC_F77_DUMMY_MAIN): Remove conftest* after using + break in the argument to AC_TRY_LINK_FUNC. + (AC_F77_MAIN): Remove conftest* after using break in the + argument to AC_TRY_LINK. + +2001-07-01 Steven G. Johnson + + Add alternate 'main' routine detection for linking C/C++ with Fortran, + fixing link failures for e.g. AC_F77_WRAPPERS on NetBSD. + + * aclang.m4 (AC_F77_DUMMY_MAIN): New macro to detect whether a + dummy alternate main is required even if the user provides her own + 'main'. + (AC_F77_MAIN): New macro to detect whether it is possible to + provide an alternate 'main' function name, using the 'main' from + the Fortran libraries. + (AC_LANG_PROGRAM(C)): Use F77_DUMMY_MAIN, if it is defined, so that + cross-language link tests can be performed successfully. + (_AC_F77_NAME_MANGLING): Require AC_F77_DUMMY_MAIN. Also put $FLIBS + after $LIBS, for consistency; this should be the general rule since + the user may want to link to Fortran libraries that require $FLIBS. + * doc/autoconf.texi: Document AC_F77_DUMMY_MAIN and AC_F77_MAIN. + +2001-06-29 Pavel Roskin + + * atgeneral.m4 (AT_CHECK): Add a newline to the end of + at-stdout and at-stderr instead of removing the newline + from the echo output, which is not guaranteed to work. + +2001-06-28 Jens Petersen + + * aclang.m4 (_AC_PROG_CXX_EXIT_DECLARATION): Only add declaration to + confdefs.h when non-zero. + +2001-06-28 Akim Demaille + + * configure.in: Bump to 2.50c. + +2001-06-26 Akim Demaille + + Version 2.50b. + +2001-06-26 Akim Demaille + + Version 2.50a. + +2001-06-25 Pavel Roskin + + * tests/atspecific.m4 (AT_CHECK_MACRO): Accept one more + argument, AUTOCONF-FLAGS. + * tests/mktests.sh (update_exclude_list): Add + AC_SYS_RESTARTABLE_SYSCALLS and AC_FUNC_WAIT3. + * tests/semantics.at: Test AC_SYS_RESTARTABLE_SYSCALLS and + AC_FUNC_WAIT3 with "-W no-obsolete". + +2001-06-25 Akim Demaille + + * tests/foreign.at (libtool): Fix the `libtoolize --version' decoding. + +2001-06-25 Akim Demaille + + * autoscan.in (%macro): Now maps from word to list of macros. + (&init_tables): Die when a word which is already handled by + explicit macros is mapped to the default macro. + (&print_unique): Remove, inlined in... + (&output_kind): here. + (File::Basename): Use it. + (&output): Sort the CONFIG_FILES. + * acheaders: Normalize. + * acfunctions: Likewise. + +2001-06-25 Akim Demaille + + * aclang.m4 (_AC_LANG_COMPILER_GNU): If GNU, dump the compiler + characteristics in the logs. + Suggested by Mo DeJong. + +2001-06-24 Akim Demaille + + * acfunctions.m4 (AM_FUNC_ERROR_AT_LINE, AM_FUNC_FNMATCH) + (AM_FUNC_MKTIME, AM_FUNC_OBSTACK, AM_FUNC_STRTOD): Reactivated. + * doc/autoconf.texi (Autoconf 2.13): New section. + +2001-06-24 Akim Demaille + + * autoconf.in (Task traces): Separate the error messages from the + traces to improve robustness. + +2001-06-23 Akim Demaille + + * tests/torture.at (AC_ARG_VAR): Make it a single test instead of + three as failures are unlikely, and speed matters. + +2001-06-23 Akim Demaille + + * doc/autoconf.texi (Redefined M4 Macros): New. + +2001-06-23 Akim Demaille + + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): Consider + inttypes.h is missing if it conflicts with sys/types.h, as on IRIX + 5.3. + +2001-06-23 Paolo Bonzini + + * acgeneral.m4 (_AC_OUTPUT_CONFIG_STATUS): Defer parsing of + config.status targets to after the evaluation of the INIT-CMDS. + Double quote config.status targets (used to be single quoted). + +2001-06-23 Akim Demaille + + * tests/torture.at (CONFIG_FILES, HEADERS, LINKS and COMMANDS): + Check the content of the created file. + Check the ./config.status command line invocation. + +2001-06-23 Akim Demaille + + * tests/foreign.at (Libtool): Reject prehistoric versions. + +2001-06-23 Akim Demaille + + * aclang.m4 (_AC_COMPILER_EXEEXT_DEFAULT): Try to be robust to + preexisting files matching a.*. + +2001-06-23 Akim Demaille + + * acgeneral.m4 (_AC_ARG_VAR_VALIDATE): Output error messages on + stderr. + * doc/autoconf.texi (AC_ARG_VAR): Update. + +2001-06-21 Akim Demaille + + * acgeneral.m4 (_AC_ARG_VAR_VALIDATE): Die instead of warning when + precious variables have changed. + * tests/torture.at (AC_ARG_VAR): Adjust. + +2001-06-21 Akim Demaille + + ./configure --program-suffix=foo produces `transform=s,$$,foo,;', + but some sed choke on multiple `;', and other tools (e.g., + Automake), include the separator themselves. + + * acgeneral.m4 (AC_ARG_VAR): Be sure not to leave extra `;'. + +2001-06-19 Tim Van Holder + + * doc/autoconf.texi (Functions Portability): Rename as... + (Function Portability): this. + (Function Portability): Document potential problems with unlink(). + +2001-06-19 Paul Eggert + + * NEWS, doc/autoconf.texi: Document quadrigraphs. + +2001-06-18 Akim Demaille + + * acfunctions.m4 (AC_FUNC_FORK): Fix typos. + +2001-06-18 Ruediger Kuhlmann + + * acfunctions.m4: (AC_FUNC_VFORK) rename as... + (_AC_FUNC_VFORK): this. + Remove AC_DEFINEs and don't guess cross-compilation values. + (_AC_FUNC_FORK): New, check whether fork() isn't just a stub. + (AC_FUNC_FORK): New, use _AC_FUNC_VFORK and _AC_FUNC_FORK to + define HAVE_WORKING_FORK, HAVE_WORKING_VFORK; and vfork to fork if + vfork doesn't work. + Guess values if cross-compiling, but warn. + * acfunctions: Add AC_FUNC_FORK. + * doc/autoconf.texi: Document AC_FUNC_FORK. Give example to define + and vfork appropriately. + +2001-06-18 Akim Demaille + + * doc/autoconf.texi (Functions Portability): New section. + +2001-06-18 Akim Demaille + + * autoconf.in (M4): Pass --nesting-limit=1024, unless already set + in $M4. + Suggested by Andreas Schwab. + +2001-06-18 Akim Demaille + + * acfunctions.m4 (AC_FUNC_CHOWN, AC_FUNC_CLOSEDIR_VOID) + (AC_FUNC_GETPGRP, AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK) + (AC_FUNC_MMAP, AC_FUNC_SELECT_ARGTYPES, _AC_FUNC_STAT) + (AC_FUNC_UTIME_NULL): Use AC_INCLUDES_DEFAULT. + Don't use AC_TRY_RUN, which double quotes, prefer AC_RUN_IFELSE, + and either AC_LANG_SOURCE or AC_LANG_PROGRAM. + (AC_FUNC_CLOSEDIR_VOID): Protect C++ from `int closedir ();' (or + the converse). + +2001-06-18 Akim Demaille + + * doc/autoconf.texi (ms): New index. + (Macro Index): Rename as... + (Autoconf Macro Index): this. + (M4 Macro Index): New appendix. + (Programming in M4): New chapter. + Define M4sugar, M4sh, m4_pattern_forbid, and m4_pattern_allow. + (Quoting): Rename as... + (M$ Quotation): this. + Be part of `Programming in M4). + +2001-06-18 Nicolas Joly + + * tests/torture.at (AC_ARG_VAR): Set variables and export them + in separate statements for compatibility with Tru64 v5.1. + +2001-06-17 Akim Demaille + + * acgeneral.m4 (_AC_ARG_VAR_VALIDATE): Be sure to cache the + current values of the precious variables, not the previously + cached values. + Pass precious variables which are set to config.status. + * doc/autoconf.texi (Setting Output Variables): Document AC_ARG_VAR. + * tests/torture.at (AC_ARG_VAR): New. + +2001-06-15 Paul Eggert + + * doc/autoconf.texi: Move AC_FUNC_WAIT3 and + AC_SYS_RESTARTABLE_SYSCALLS to the obsolete section, + and explain why and how to replace them. + * acfunctions.m4 (AC_FUNC_WAIT3): Warn as obsolete. + * acspecific.m4 (AC_SYS_RESTARTABLE_SYSCALLS): Likewise. + +2001-06-15 Akim Demaille + + `build_alias', `host_alias', and `target_alias' are not AC_SUBST'd. + Reported by Bruno Haible. + + * acgeneral.m4 (AC_ARG_VAR): Move the AC_SUBST, from here... + (_AC_ARG_VAR_PRECIOUS): to here. + +2001-06-15 Pavel Roskin + + * acheaders.m4 (_AC_CHECK_HEADER_DIRENT): Instead of defining + an unused pointer use cast to this type and `if' statement to + avoid warnings from the compiler. + (AC_HEADER_TIME): Likewise. + * actypes.m4 (AC_CHECK_MEMBER): s/foo/ac_aggr/. Use the member + in `if' statement to avoid warnings from the compiler. Declare + ac_aggr static to avoid the need to initialize it. + +2001-06-14 Akim Demaille + + * doc/autoconf.texi (Portable Shell): Move to follow `Writing + Macros'. + +2001-06-13 Akim Demaille + + * m4/missing.m4, config/missing: Updated to Automake 1.4g's. + Suggested by Alexander Mai. + +2001-06-13 Akim Demaille + + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): Guard + sys/types.h and sys/stat.h, and check for them. + +2001-06-13 Akim Demaille + + * acheaders.m4 (AC_CHECK_HEADER, AC_CHECK_HEADERS): Support $4 = + INCLUDES. + +2001-06-12 Maciej W. Rozycki + + * acspecific.m4 (AC_PATH_XTRA): Check if linking against libX11 + succeeds and only try adding libdnet upon a failure. + +2001-06-12 Akim Demaille + + * autoscan.in (&output_kind): Output the comment only if it exists. + (%kind_comment): Add entry for `programs'. + (&output_programs): Use &output_kind. + (&output_functions, &output_identifiers, &output_headers) + (&output_programs): Inline, and remove. + +2001-06-12 Akim Demaille + + * autoscan.in (%kind_comment): New. + (output_kind): New. + (output_functions, output_identifiers, output_headers): Use it. + +2001-06-12 Akim Demaille + + * autoscan.in (&print_unique): Take `$kind' and `$word' as + arguments, to factor indirections into `%macro' and `%used'. + (%generic_macro): Fix a typo. + +2001-06-12 Akim Demaille + + * aclibraries: New. + * autoscan.in (@kinds): Add `libraries'. + Use `@kinds' instead of hard coded lists. + (%programs, %headers, %identifiers, %makevars, %libraries, %functions): + Remove, replaced by... + (%used): this. + +2001-06-12 Akim Demaille + + * autoscan.in (%functions_macros %headers_macros) + (%identifiers_macros %programs_macros %makevars_macros): Remove, + replaced by... + (%macro): New. + +2001-06-11 Raja R Harinath + + * aclang.m4 (AC_NO_EXECUTABLES): Override + _AC_COMPILER_EXEEXT_WORKS, not _AC_LANG_COMPILER_WORKS. + +2001-06-11 Akim Demaille + + * aclang.m4 (AC_NO_EXECUTABLES): Define the macros with their + trailing new line. + Reported by Andreas Schwab. + +2001-06-11 Akim Demaille + + * Makefile.am, Makefile.maint: Typos. + +2001-06-09 Akim Demaille + + * doc/autoconf.texi (Here-Documents): New section, gathering + documentation about here-documents. + Use `href', not `uref', and other changes. + +2001-06-09 Akim Demaille + + * doc/autoconf.texi (Portable Shell Programming): Promoted as a + chapter. + +2001-06-09 Akim Demaille + + * doc/autoconf.texi (Limitations of Builtins): Complete the + description of the here-docs penalties with Alexandre Oliva's + explanations. + +2001-06-01 Paul Eggert + + * doc/autoconf.texi: Talk about here documents and speedups. + Do not use "echo" on arbitrary strings. + Spell "here-documents" consistently with the standard. + +2001-06-09 Akim Demaille + + * doc/autoconf.texi (Concept Index): Introduce it. + Regenerate the menus. + +2001-06-09 Akim Demaille + + * Makefile.maint, GNUmakefile: New, from Jim Meyering. + * config/prev-version.txt: New. + * config/move-if-change: New, for GNU libc. + +2001-06-06 Pavel Roskin + + * tests/atgeneral.m4 (AT_INIT): Remove "/bin/sh" after $SHELL. + +2001-06-06 Akim Demaille + + * acgeneral.m4 (AC_CHECK_LIB): Fix the cache var name to work + properly when $1 is not a literal. + Fixes PR Autoconf/187, reported by Bram Moolenaar. + +2001-06-06 Akim Demaille + + Invoking AC_COPYRIGHT before AC_INIT fails. + + * Makefile.am (.m4.m4f): Pass --fatal-warnings to m4. + * acgeneral.m4 (_m4_divert(VERSION_FSF)) + (_m4_divert(VERSION_USER)): New. + (AC_COPYRIGHT): $2 is the diversion to use. + (_AC_INIT_COPYRIGHT): Use the FSF diversion. + (AC_INIT): Remove dead comments as now it's commutative. + +2001-06-06 Akim Demaille + + * tests/semantics.at (AC_CHECK_LIB): Strengthen to reflect + PR autoconf/187. + +2001-06-05 Akim Demaille + + * acgeneral.m4 (_AC_INIT_PARSE_ARGS): `prefix' and `exec_prefix' + can be empty. + `*dir' variables cannot be NONE. + Reported by Mark Kettenis. + +2001-06-05 Paul Eggert + + * doc/autoconf.texi: Fix references to Solaris and SunOS versions. + +2001-06-04 Akim Demaille + + * acgeneral.m4 (AC_VAR_SET, AC_VAR_GET, AC_VAR_TEST_SET) + (AC_VAR_SET_IFELSE, AC_VAR_PUSHDEF and AC_VAR_POPDEF, AC_TR_CPP) + (AC_TR_SH): Move as... + * m4sh.m4 (AS_VAR_SET, AS_VAR_GET, AS_VAR_TEST_SET) + (AS_VAR_SET_IF, AC_VAR_PUSHDEF, AS_VAR_POPDEF, AS_TR_CPP) + (AS_TR_SH): these. + (_AS_TR_PREPARE, _AS_CR_PREPARE, _AS_TR_CPP_PREPARE) + (_AS_TR_SH_PREPARE): New. + (AS_SHELL_SANITIZE): Invoke _AS_TR_PREPARE. + * tests/aclocal.m4 (AC_STATE_SAVE): `as_' vars can be modified. + +2001-06-02 Akim Demaille + + * Makefile.am (.m4.m4f): Pass the options first. + Fixes PR autoconf/182. + +2001-06-02 Nathan Sidwell + + GNU getopt, when POSIXLY_CORRECT does not permute options and + arguments. So pass the options first. + Fixes PR autoconf/184. + + * autoconf.sh (m4_prefiles, m4f_prefiles): New variables. + (run_m4): Remove files. + (run_m4f): Remove. + Update remainder of script to use them. + (for warning in): Do not use a literal comma as it will not be + split by IFS. + +2001-06-02 Christian Marquardt + + * aclang.m4 (AC_PROG_F77): Add Fujitsu's "frt" to the list of + Fortran compilers to check. + (_AC_PROG_F77_V): Add '-###' as a possible option to print + information on library and object files. + (AC_PROG_CXX): Add Fujitsu's "FCC" to the list of C++ compilers + to check. + +2001-06-02 Akim Demaille + + * autom4te.in (Request::@request): Declare with `vars', not `my', + as it prevents updates via `do FILENAME'. + +2001-06-02 Akim Demaille + + * configure.in (standards_texi): Remove, dead code. + +2001-06-02 Akim Demaille + + * autom4te.in: New. + +2001-06-02 Pavel Roskin + + * acgeneral.m4 (_AC_INIT_PREPARE): Don't rely on $? in the traps + for signals other than 0 - exit with code 1. + * m4sh.m4 (AS_TMPDIR): Likewise. + * autoconf.in: Likewise. Also don't rely on exit == exit $?. + * autoheader.in: Likewise. + * autoreconf.in: Likewise. + * tests/torture.at (Signal handling): New test for the above. + +2001-06-01 Akim Demaille + + * m4sugar.m4 (m4_defn, m4_undefine, m4_popdef): Clarify the error + message. + +2001-05-31 Akim Demaille + + * acfunctions, acheaders, acidentifiers, acmakevars, acprograms: + Add copyright and comments. + * acheaders: Add stdint.h. + Suggested by Paul Eggert. + +2001-05-31 Akim Demaille + + * atgeneral.m4 (AT_INIT): Use $SHELL. + * atspecific.m4 (AT_CHECK_DEFINES): Skip HAVE_STDINT_H. + +2001-05-31 Akim Demaille + + * acgeneral.m4 (_AC_INCLUDES_DEFAULT_REQUIREMENTS): Include + stdint.h. + From Paul Eggert and Lars Hecking. + +2001-05-31 Akim Demaille + + * tests/base.at: Adjust line numbers in error messages. + +2001-05-31 Akim Demaille + + * tests/base.at, tests/m4sh.at: When using AC_PLAIN_SCRIPT be sure + to emit the bangshe line. + Reported by David Carter. + +2001-05-30 Steven G. Johnson + + * aclang.m4 (AC_PROG_F77): Add Compaq's "fort" to the list of + Fortran (95) compilers to check. + +2001-05-29 Alexandre Duret-Lutz + + * doc/autoconf.texi (Introduction, Pointers): Update the Autoconf + Macro Archive URL. + +2001-05-23 Pavel Roskin + + * aclang.m4 (AC_PROG_CPP): Use `break' instead of `break 2' since + _AC_PROG_PREPROC_WORKS_IFELSE expands arguments outside the loop. + (AC_PROG_CXXCPP): Likewise. + +2001-05-22 Akim Demaille + + * config: New directory. + * configure.in: AC_CONFIG_AUX_DIR it. + * tests/atspecific.m4 (AT_CONFIGURE_AC): Adjust. + +2001-05-22 Akim Demaille + + * autoconf.in, autoreconf.in, autoheader.in, autoscan.in, ifnames.in, + * autoupdate.in: Specify the Emacs mode. + * acversion.m4.in: Rename as... + * acversion.m4: this. + * tests/Makefile.am (CLEANFILES): More garbage. + +2001-05-22 Akim Demaille + + * autoconf.sh, autoreconf.sh, autoheader.sh, autoscan.pl, ifnames.sh: + Rename as... + * autoconf.in, autoreconf.in, autoheader.in, autoscan.in, ifnames.in: + these. + +2001-05-21 Akim Demaille + + * configure.in: Bump to 2.50a. + + + ----- + + Local Variables: + coding: utf-8 + End: + + Copyright (C) 2001-2012 Free Software Foundation, Inc. + + 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 + . diff --git a/static/netbsd/man3/DEFINE_STACK_OF.3 b/static/netbsd/man3/DEFINE_STACK_OF.3 new file mode 100644 index 00000000..94e72025 --- /dev/null +++ b/static/netbsd/man3/DEFINE_STACK_OF.3 @@ -0,0 +1,374 @@ +.\" $NetBSD: DEFINE_STACK_OF.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DEFINE_STACK_OF 3" +.TH DEFINE_STACK_OF 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, +DEFINE_SPECIAL_STACK_OF_CONST, +sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, +sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete, +sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop, +sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set, +sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort, +sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, +sk_TYPE_new_reserve, +OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, +OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all, +OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, +OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, OPENSSL_sk_num, OPENSSL_sk_pop, +OPENSSL_sk_pop_free, OPENSSL_sk_push, OPENSSL_sk_reserve, OPENSSL_sk_set, +OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort, +OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero +\&\- stack container +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(TYPE) +\& DEFINE_STACK_OF(TYPE) +\& DEFINE_STACK_OF_CONST(TYPE) +\& DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE) +\& DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE) +\& +\& typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b); +\& typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a); +\& typedef void (*sk_TYPE_freefunc)(TYPE *a); +\& +\& int sk_TYPE_num(const STACK_OF(TYPE) *sk); +\& TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx); +\& STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare); +\& STACK_OF(TYPE) *sk_TYPE_new_null(void); +\& int sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n); +\& void sk_TYPE_free(STACK_OF(TYPE) *sk); +\& void sk_TYPE_zero(STACK_OF(TYPE) *sk); +\& TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i); +\& TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr); +\& int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr); +\& int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr); +\& TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk); +\& TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk); +\& void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc); +\& int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx); +\& TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr); +\& int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr); +\& int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr); +\& int sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum); +\& void sk_TYPE_sort(const STACK_OF(TYPE) *sk); +\& int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk); +\& STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk); +\& STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk, +\& sk_TYPE_copyfunc copyfunc, +\& sk_TYPE_freefunc freefunc); +\& sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, +\& sk_TYPE_compfunc compare)); +\& STACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Applications can create and use their own stacks by placing any of the macros +described below in a header file. These macros define typesafe inline +functions that wrap around the utility \fBOPENSSL_sk_\fR API. +In the description here, \fR\f(BITYPE\fR\fB\fR is used +as a placeholder for any of the OpenSSL datatypes, such as \fBX509\fR. +.PP +The \fBSTACK_OF()\fR macro returns the name for a stack of the specified \fR\f(BITYPE\fR\fB\fR. +This is an opaque pointer to a structure declaration. +This can be used in every header file that references the stack. +There are several \fBDEFINE...\fR macros that create static inline functions +for all of the functions described on this page. +This should normally be used in one source file, and the stack manipulation +is wrapped with application\-specific functions. +.PP +\&\fBDEFINE_STACK_OF()\fR creates set of functions for a stack of \fR\f(BITYPE\fR\fB\fR elements. +The type is referenced by +\&\fBSTACK_OF\fR(\fB\fR\f(BITYPE\fR\fB\fR) and each function name begins with \fBsk_\fR\f(BITYPE\fR\fB_\fR. +\&\fBDEFINE_STACK_OF_CONST()\fR is identical to \fBDEFINE_STACK_OF()\fR except +each element is constant. +.PP +.Vb 4 +\& /* DEFINE_STACK_OF(TYPE) */ +\& TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); +\& /* DEFINE_STACK_OF_CONST(TYPE) */ +\& const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); +.Ve +.PP +\&\fBDEFINE_SPECIAL_STACK_OF()\fR and \fBDEFINE_SPECIAL_STACK_OF_CONST()\fR are similar +except \fBFUNCNAME\fR is used in the function names: +.PP +.Vb 4 +\& /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */ +\& TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); +\& /* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */ +\& const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); +.Ve +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_num\fR() returns the number of elements in \fIsk\fR or \-1 if \fIsk\fR is +NULL. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_value\fR() returns element \fIidx\fR in \fIsk\fR, where \fIidx\fR starts at +zero. If \fIidx\fR is out of range then NULL is returned. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_new\fR() allocates a new empty stack using comparison function +\&\fIcompare\fR. If \fIcompare\fR is NULL then no comparison function is used. This +function is equivalent to \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR(\fIcompare\fR, 0). +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_new_null\fR() allocates a new empty stack with no comparison +function. This function is equivalent to \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR(NULL, 0). +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() allocates additional memory in the \fIsk\fR structure +such that the next \fIn\fR calls to \fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR() +or \fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() will not fail or cause memory to be allocated +or reallocated. If \fIn\fR is zero, any excess space allocated in the +\&\fIsk\fR structure is freed. On error \fIsk\fR is unchanged. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() allocates a new stack. The new stack will have +additional memory allocated to hold \fIn\fR elements if \fIn\fR is positive. +The next \fIn\fR calls to \fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR() or +\&\fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() will not fail or cause memory to be allocated or +reallocated. If \fIn\fR is zero or less than zero, no memory is allocated. +\&\fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() also sets the comparison function \fIcompare\fR +to the newly created stack. If \fIcompare\fR is NULL then no comparison +function is used. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_set_cmp_func\fR() sets the comparison function of \fIsk\fR to +\&\fIcompare\fR. The previous comparison function is returned or NULL if there +was no previous comparison function. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_free\fR() frees up the \fIsk\fR structure. It does \fInot\fR free up any +elements of \fIsk\fR. After this call \fIsk\fR is no longer valid. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_zero\fR() sets the number of elements in \fIsk\fR to zero. It does not +free \fIsk\fR so after this call \fIsk\fR is still valid. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR() frees up all elements of \fIsk\fR and \fIsk\fR itself. The +free function \fBfreefunc()\fR is called on each element to free it. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_delete\fR() deletes element \fIi\fR from \fIsk\fR. It returns the deleted +element or NULL if \fIi\fR is out of range. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR() deletes element matching \fIptr\fR from \fIsk\fR. It +returns the deleted element or NULL if no element matching \fIptr\fR was found. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_insert\fR() inserts \fIptr\fR into \fIsk\fR at position \fIidx\fR. Any +existing elements at or after \fIidx\fR are moved downwards. If \fIidx\fR is out +of range the new element is appended to \fIsk\fR. \fBsk_\fR\f(BITYPE\fR\fB_insert\fR() either +returns the number of elements in \fIsk\fR after the new element is inserted or +zero if an error (such as memory allocation failure) occurred. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_push\fR() appends \fIptr\fR to \fIsk\fR it is equivalent to: +.PP +.Vb 1 +\& sk_TYPE_insert(sk, ptr, \-1); +.Ve +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() inserts \fIptr\fR at the start of \fIsk\fR it is equivalent +to: +.PP +.Vb 1 +\& sk_TYPE_insert(sk, ptr, 0); +.Ve +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_pop\fR() returns and removes the last element from \fIsk\fR. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_shift\fR() returns and removes the first element from \fIsk\fR. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_set\fR() sets element \fIidx\fR of \fIsk\fR to \fIptr\fR replacing the current +element. The new element value is returned or NULL if an error occurred: +this will only happen if \fIsk\fR is NULL or \fIidx\fR is out of range. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() searches \fIsk\fR for the element \fIptr\fR. In the +case where no comparison function has been specified, the function +performs a linear search for a pointer equal to \fIptr\fR. In the case +where a comparison function has been specified, the function performs +a search for a element that the comparison function indicates is a +match. If the stack is sorted, a binary search is used, otherwise, a +linear search is used. \fBsk_\fR\f(BITYPE\fR\fB_find\fR() returns the index of a +matching element or \fB\-1\fR if there is no match. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() operates like \fBsk_\fR\f(BITYPE\fR\fB_find\fR() except when a +comparison function has been specified and no matching element is found. +Instead of returning \fB\-1\fR, \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() returns the index of the +element either before or after the location where \fIptr\fR would be if it were +present in \fIsk\fR. The function also does not guarantee that the first matching +element in the sorted stack is returned. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() operates like \fBsk_\fR\f(BITYPE\fR\fB_find\fR() but it also +sets the \fI*pnum\fR to number of matching elements in the stack. In case +no comparison function has been specified the \fI*pnum\fR will be always set +to 1 if matching element was found, 0 otherwise. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() sorts \fIsk\fR using the supplied comparison function. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_is_sorted\fR() returns \fB1\fR if \fIsk\fR is sorted and \fB0\fR otherwise. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_dup\fR() returns a shallow copy of \fIsk\fR +or an empty stack if the passed stack is NULL. +Note the pointers in the copy are identical to the original. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_deep_copy\fR() returns a new stack where each element has been +copied or an empty stack if the passed stack is NULL. +Copying is performed by the supplied \fBcopyfunc()\fR and freeing by \fBfreefunc()\fR. +The function \fBfreefunc()\fR is only called if an error occurs. +.SH NOTES +.IX Header "NOTES" +Care should be taken when accessing stacks in multi\-threaded environments. +Any operation which increases the size of a stack such as \fBsk_\fR\f(BITYPE\fR\fB_insert\fR() +or \fBsk_\fR\f(BITYPE\fR\fB_push\fR() can "grow" the size of an internal array and cause race +conditions if the same stack is accessed in a different thread. Operations such +as \fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_sort\fR() can also reorder the stack. +.PP +Any comparison function supplied should use a metric suitable +for use in a binary search operation. That is it should return zero, a +positive or negative value if \fIa\fR is equal to, greater than +or less than \fIb\fR respectively. +.PP +Care should be taken when checking the return values of the functions +\&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR(). They return an index to the +matching element. In particular \fB0\fR indicates a matching first element. +A failed search is indicated by a \fB\-1\fR return value. +.PP +\&\fBSTACK_OF()\fR, \fBDEFINE_STACK_OF()\fR, \fBDEFINE_STACK_OF_CONST()\fR, and +\&\fBDEFINE_SPECIAL_STACK_OF()\fR are implemented as macros. +.PP +It is not an error to call \fBsk_\fR\f(BITYPE\fR\fB_num\fR(), \fBsk_\fR\f(BITYPE\fR\fB_value\fR(), +\&\fBsk_\fR\f(BITYPE\fR\fB_free\fR(), \fBsk_\fR\f(BITYPE\fR\fB_zero\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR(), +\&\fBsk_\fR\f(BITYPE\fR\fB_delete\fR(), \fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop\fR(), +\&\fBsk_\fR\f(BITYPE\fR\fB_shift\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR(), +and \fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() on a NULL stack, empty stack, or with +an invalid index. An error is not raised in these conditions. +.PP +The underlying utility \fBOPENSSL_sk_\fR API should not be used directly. +It defines these functions: \fBOPENSSL_sk_deep_copy()\fR, +\&\fBOPENSSL_sk_delete()\fR, \fBOPENSSL_sk_delete_ptr()\fR, \fBOPENSSL_sk_dup()\fR, +\&\fBOPENSSL_sk_find()\fR, \fBOPENSSL_sk_find_ex()\fR, \fBOPENSSL_sk_find_all()\fR, +\&\fBOPENSSL_sk_free()\fR, \fBOPENSSL_sk_insert()\fR, \fBOPENSSL_sk_is_sorted()\fR, +\&\fBOPENSSL_sk_new()\fR, \fBOPENSSL_sk_new_null()\fR, \fBOPENSSL_sk_new_reserve()\fR, +\&\fBOPENSSL_sk_num()\fR, \fBOPENSSL_sk_pop()\fR, \fBOPENSSL_sk_pop_free()\fR, \fBOPENSSL_sk_push()\fR, +\&\fBOPENSSL_sk_reserve()\fR, \fBOPENSSL_sk_set()\fR, \fBOPENSSL_sk_set_cmp_func()\fR, +\&\fBOPENSSL_sk_shift()\fR, \fBOPENSSL_sk_sort()\fR, \fBOPENSSL_sk_unshift()\fR, +\&\fBOPENSSL_sk_value()\fR, \fBOPENSSL_sk_zero()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBsk_\fR\f(BITYPE\fR\fB_num\fR() returns the number of elements in the stack or \fB\-1\fR if the +passed stack is NULL. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_value\fR() returns a pointer to a stack element or NULL if the +index is out of range. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_new\fR(), \fBsk_\fR\f(BITYPE\fR\fB_new_null\fR() and \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() +return an empty stack or NULL if an error occurs. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() returns \fB1\fR on successful allocation of the required +memory or \fB0\fR on error. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_set_cmp_func\fR() returns the old comparison function or NULL if +there was no old comparison function. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_free\fR(), \fBsk_\fR\f(BITYPE\fR\fB_zero\fR(), \fBsk_\fR\f(BITYPE\fR\fB_pop_free\fR() and +\&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() do not return values. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_pop\fR(), \fBsk_\fR\f(BITYPE\fR\fB_shift\fR(), \fBsk_\fR\f(BITYPE\fR\fB_delete\fR() and +\&\fBsk_\fR\f(BITYPE\fR\fB_delete_ptr\fR() return a pointer to the deleted element or NULL +on error. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_insert\fR(), \fBsk_\fR\f(BITYPE\fR\fB_push\fR() and \fBsk_\fR\f(BITYPE\fR\fB_unshift\fR() return +the total number of elements in the stack and 0 if an error occurred. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_set\fR() returns a pointer to the replacement element or NULL on +error. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_find\fR() and \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() return an index to the found +element or \fB\-1\fR on error. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_is_sorted\fR() returns \fB1\fR if the stack is sorted and \fB0\fR if it is +not. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_dup\fR() and \fBsk_\fR\f(BITYPE\fR\fB_deep_copy\fR() return a pointer to the copy +of the stack or NULL on error. +.SH HISTORY +.IX Header "HISTORY" +Before OpenSSL 1.1.0, this was implemented via macros and not inline functions +and was not a public API. +.PP +\&\fBsk_\fR\f(BITYPE\fR\fB_reserve\fR() and \fBsk_\fR\f(BITYPE\fR\fB_new_reserve\fR() were added in OpenSSL +1.1.1. +.PP +From OpenSSL 3.2.0, the \fBsk_\fR\f(BITYPE\fR\fB_find\fR(), \fBsk_\fR\f(BITYPE\fR\fB_find_ex\fR() +and \fBsk_\fR\f(BITYPE\fR\fB_find_all\fR() calls are read\-only and do not sort the +stack. To avoid any performance implications this change introduces, +\&\fBsk_\fR\f(BITYPE\fR\fB_sort\fR() should be called before these find operations. +.PP +Before OpenSSL 3.3.0 \fBsk_\fR\f(BITYPE\fR\fB_push\fR() returned \-1 if \fIsk\fR was NULL. It +was changed to return 0 in this condition as for other errors. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DES_cbc_cksum.3 b/static/netbsd/man3/DES_cbc_cksum.3 new file mode 100644 index 00000000..d10255b0 --- /dev/null +++ b/static/netbsd/man3/DES_cbc_cksum.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_cbc_cksum.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_cbc_encrypt.3 b/static/netbsd/man3/DES_cbc_encrypt.3 new file mode 100644 index 00000000..f56a4858 --- /dev/null +++ b/static/netbsd/man3/DES_cbc_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_cbc_encrypt.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_cfb64_encrypt.3 b/static/netbsd/man3/DES_cfb64_encrypt.3 new file mode 100644 index 00000000..26d28d93 --- /dev/null +++ b/static/netbsd/man3/DES_cfb64_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_cfb64_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_check_key_parity.3 b/static/netbsd/man3/DES_check_key_parity.3 new file mode 100644 index 00000000..b363f13f --- /dev/null +++ b/static/netbsd/man3/DES_check_key_parity.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_check_key_parity.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_ecb3_encrypt.3 b/static/netbsd/man3/DES_ecb3_encrypt.3 new file mode 100644 index 00000000..619b1c91 --- /dev/null +++ b/static/netbsd/man3/DES_ecb3_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_ecb3_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_ecb_encrypt.3 b/static/netbsd/man3/DES_ecb_encrypt.3 new file mode 100644 index 00000000..df1af54b --- /dev/null +++ b/static/netbsd/man3/DES_ecb_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_ecb_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_ede3_cbc_encrypt.3 b/static/netbsd/man3/DES_ede3_cbc_encrypt.3 new file mode 100644 index 00000000..2a834d56 --- /dev/null +++ b/static/netbsd/man3/DES_ede3_cbc_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_ede3_cbc_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_encrypt.3 b/static/netbsd/man3/DES_encrypt.3 new file mode 100644 index 00000000..e7c2b419 --- /dev/null +++ b/static/netbsd/man3/DES_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_init_random_number_generator.3 b/static/netbsd/man3/DES_init_random_number_generator.3 new file mode 100644 index 00000000..f1f88bc0 --- /dev/null +++ b/static/netbsd/man3/DES_init_random_number_generator.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_init_random_number_generator.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_is_weak_key.3 b/static/netbsd/man3/DES_is_weak_key.3 new file mode 100644 index 00000000..ebe6570f --- /dev/null +++ b/static/netbsd/man3/DES_is_weak_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_is_weak_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_key_sched.3 b/static/netbsd/man3/DES_key_sched.3 new file mode 100644 index 00000000..6a96c1e3 --- /dev/null +++ b/static/netbsd/man3/DES_key_sched.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_key_sched.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_new_random_key.3 b/static/netbsd/man3/DES_new_random_key.3 new file mode 100644 index 00000000..77815361 --- /dev/null +++ b/static/netbsd/man3/DES_new_random_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_new_random_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_pcbc_encrypt.3 b/static/netbsd/man3/DES_pcbc_encrypt.3 new file mode 100644 index 00000000..d3cce2e7 --- /dev/null +++ b/static/netbsd/man3/DES_pcbc_encrypt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_pcbc_encrypt.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_random_key.3 b/static/netbsd/man3/DES_random_key.3 new file mode 100644 index 00000000..08eedf71 --- /dev/null +++ b/static/netbsd/man3/DES_random_key.3 @@ -0,0 +1,388 @@ +.\" $NetBSD: DES_random_key.3,v 1.10 2025/04/16 15:23:15 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "DES_random_key 3" +.TH DES_random_key 3 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, +DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, +DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, +DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, +DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, +DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, +DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, +DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, +DES_fcrypt, DES_crypt \- DES encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void DES_random_key(DES_cblock *ret); +\& +\& int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_set_key_checked(const_DES_cblock *key, DES_key_schedule *schedule); +\& void DES_set_key_unchecked(const_DES_cblock *key, DES_key_schedule *schedule); +\& +\& void DES_set_odd_parity(DES_cblock *key); +\& int DES_is_weak_key(const_DES_cblock *key); +\& +\& void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks, int enc); +\& void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); +\& void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, +\& DES_key_schedule *ks3, int enc); +\& +\& void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec, int enc); +\& void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec); +\& void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num, int enc); +\& void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num); +\& +\& void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& const_DES_cblock *inw, const_DES_cblock *outw, int enc); +\& +\& void DES_ede2_cbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int enc); +\& void DES_ede2_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, +\& int *num, int enc); +\& void DES_ede2_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int *num); +\& +\& void DES_ede3_cbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int enc); +\& void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int *num, int enc); +\& void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int *num); +\& +\& DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, +\& long length, DES_key_schedule *schedule, +\& const_DES_cblock *ivec); +\& DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], +\& long length, int out_count, DES_cblock *seed); +\& void DES_string_to_key(const char *str, DES_cblock *key); +\& void DES_string_to_2keys(const char *str, DES_cblock *key1, DES_cblock *key2); +\& +\& char *DES_fcrypt(const char *buf, const char *salt, char *ret); +\& char *DES_crypt(const char *buf, const char *salt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. Applications should +instead use \fBEVP_EncryptInit_ex\fR\|(3), \fBEVP_EncryptUpdate\fR\|(3) and +\&\fBEVP_EncryptFinal_ex\fR\|(3) or the equivalently named decrypt functions. +.PP +This library contains a fast implementation of the DES encryption +algorithm. +.PP +There are two phases to the use of DES encryption. The first is the +generation of a \fIDES_key_schedule\fR from a key, the second is the +actual encryption. A DES key is of type \fIDES_cblock\fR. This type +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. +.PP +\&\fBDES_random_key()\fR generates a random key. The random generator must be +seeded when calling this function. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +If the function fails, 0 is returned. +.PP +Before a DES key can be used, it must be converted into the +architecture dependent \fIDES_key_schedule\fR via the +\&\fBDES_set_key_checked()\fR or \fBDES_set_key_unchecked()\fR function. +.PP +\&\fBDES_set_key_checked()\fR will check that the key passed is of odd parity +and is not a weak or semi-weak key. If the parity is wrong, then \-1 +is returned. If the key is a weak key, then \-2 is returned. If an +error is returned, the key schedule is not generated. +.PP +\&\fBDES_set_key()\fR works like \fBDES_set_key_checked()\fR and remains for +backward compatibility. +.PP +\&\fBDES_set_odd_parity()\fR sets the parity of the passed \fIkey\fR to odd. +.PP +\&\fBDES_is_weak_key()\fR returns 1 if the passed key is a weak key, 0 if it +is ok. +.PP +The following routines mostly operate on an input and output stream of +\&\fIDES_cblock\fRs. +.PP +\&\fBDES_ecb_encrypt()\fR is the basic DES encryption routine that encrypts or +decrypts a single 8\-byte \fIDES_cblock\fR in \fIelectronic code book\fR +(ECB) mode. It always transforms the input data, pointed to by +\&\fIinput\fR, into the output data, pointed to by the \fIoutput\fR argument. +If the \fIencrypt\fR argument is nonzero (DES_ENCRYPT), the \fIinput\fR +(cleartext) is encrypted in to the \fIoutput\fR (ciphertext) using the +key_schedule specified by the \fIschedule\fR argument, previously set via +\&\fIDES_set_key\fR. If \fIencrypt\fR is zero (DES_DECRYPT), the \fIinput\fR (now +ciphertext) is decrypted into the \fIoutput\fR (now cleartext). Input +and output may overlap. \fBDES_ecb_encrypt()\fR does not return a value. +.PP +\&\fBDES_ecb3_encrypt()\fR encrypts/decrypts the \fIinput\fR block by using +three-key Triple-DES encryption in ECB mode. This involves encrypting +the input with \fIks1\fR, decrypting with the key schedule \fIks2\fR, and +then encrypting with \fIks3\fR. This routine greatly reduces the chances +of brute force breaking of DES and has the advantage of if \fIks1\fR, +\&\fIks2\fR and \fIks3\fR are the same, it is equivalent to just encryption +using ECB mode and \fIks1\fR as the key. +.PP +The macro \fBDES_ecb2_encrypt()\fR is provided to perform two-key Triple-DES +encryption by using \fIks1\fR for the final encryption. +.PP +\&\fBDES_ncbc_encrypt()\fR encrypts/decrypts using the \fIcipher-block-chaining\fR +(CBC) mode of DES. If the \fIencrypt\fR argument is nonzero, the +routine cipher-block-chain encrypts the cleartext data pointed to by +the \fIinput\fR argument into the ciphertext pointed to by the \fIoutput\fR +argument, using the key schedule provided by the \fIschedule\fR argument, +and initialization vector provided by the \fIivec\fR argument. If the +\&\fIlength\fR argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. +.PP +\&\fBDES_xcbc_encrypt()\fR is RSA's DESX mode of DES. It uses \fIinw\fR and +\&\fIoutw\fR to 'whiten' the encryption. \fIinw\fR and \fIoutw\fR are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than CBC DES. +.PP +\&\fBDES_ede3_cbc_encrypt()\fR implements outer triple CBC DES encryption with +three keys. This means that each DES operation inside the CBC mode is +\&\f(CW\*(C`C=E(ks3,D(ks2,E(ks1,M)))\*(C'\fR. This mode is used by SSL. +.PP +The \fBDES_ede2_cbc_encrypt()\fR macro implements two-key Triple-DES by +reusing \fIks1\fR for the final encryption. \f(CW\*(C`C=E(ks1,D(ks2,E(ks1,M)))\*(C'\fR. +This form of Triple-DES is used by the RSAREF library. +.PP +\&\fBDES_pcbc_encrypt()\fR encrypts/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +\&\fBDES_ncbc_encrypt()\fR. +.PP +\&\fBDES_cfb_encrypt()\fR encrypts/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs an array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per \fInumbits\fR, this function is only +suggested for use when sending a small number of characters. +.PP +\&\fBDES_cfb64_encrypt()\fR +implements CFB mode of DES with 64\-bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, without 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains 'how far' we are though ivec. If this does +not make much sense, read more about CFB mode of DES. +.PP +\&\fBDES_ede3_cfb64_encrypt()\fR and \fBDES_ede2_cfb64_encrypt()\fR is the same as +\&\fBDES_cfb64_encrypt()\fR except that Triple-DES is used. +.PP +\&\fBDES_ofb_encrypt()\fR encrypts using output feedback mode. This method +takes an array of characters as input and outputs an array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per \fInumbits\fR, this function is only +suggested for use when sending a small number of characters. +.PP +\&\fBDES_ofb64_encrypt()\fR is the same as \fBDES_cfb64_encrypt()\fR using Output +Feed Back mode. +.PP +\&\fBDES_ede3_ofb64_encrypt()\fR and \fBDES_ede2_ofb64_encrypt()\fR is the same as +\&\fBDES_ofb64_encrypt()\fR, using Triple-DES. +.PP +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. +.PP +\&\fBDES_cbc_cksum()\fR produces an 8 byte checksum based on the input stream +(via CBC encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in \fIoutput\fR. This function is +used by Kerberos v4. Other applications should use +\&\fBEVP_DigestInit\fR\|(3) etc. instead. +.PP +\&\fBDES_quad_cksum()\fR is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on \fIout_count\fR, 1, 2, 3 or 4 times. If \fIoutput\fR is +non-NULL, the 8 bytes generated by each pass are written into +\&\fIoutput\fR. +.PP +The following are DES-based transformations: +.PP +\&\fBDES_fcrypt()\fR is a fast version of the Unix \fBcrypt\fR\|(3) function. This +version takes only a small amount of space relative to other fast +\&\fBcrypt()\fR implementations. This is different to the normal \fBcrypt()\fR in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal \fBcrypt()\fR. +.PP +\&\fBDES_crypt()\fR is a faster replacement for the normal system \fBcrypt()\fR. +This function calls \fBDES_fcrypt()\fR with a static array passed as the +third parameter. This mostly emulates the normal non-thread-safe semantics +of \fBcrypt\fR\|(3). +The \fBsalt\fR must be two ASCII characters. +.PP +The values returned by \fBDES_fcrypt()\fR and \fBDES_crypt()\fR are terminated by NUL +character. +.PP +\&\fBDES_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from +buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default) +using \fIsched\fR for the key and \fIiv\fR as a starting vector. The actual +data send down \fIfd\fR consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. +.SH BUGS +.IX Header "BUGS" +\&\fBDES_cbc_encrypt()\fR does not modify \fBivec\fR; use \fBDES_ncbc_encrypt()\fR +instead. +.PP +\&\fBDES_cfb_encrypt()\fR and \fBDES_ofb_encrypt()\fR operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! +.PP +\&\fBDES_string_to_key()\fR is available for backward compatibility with the +MIT library. New applications should use a cryptographic hash function. +The same applies for \fBDES_string_to_2key()\fR. +.SH NOTES +.IX Header "NOTES" +The \fBdes\fR library was written to be source code compatible with +the MIT Kerberos library. +.PP +Applications should use the higher level functions +\&\fBEVP_EncryptInit\fR\|(3) etc. instead of calling these +functions directly. +.PP +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see \fBdes_modes\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDES_set_key()\fR, \fBDES_key_sched()\fR, and \fBDES_set_key_checked()\fR +return 0 on success or negative values on error. +.PP +\&\fBDES_is_weak_key()\fR returns 1 if the passed key is a weak key, 0 if it +is ok. +.PP +\&\fBDES_cbc_cksum()\fR and \fBDES_quad_cksum()\fR return 4\-byte integer representing the +last 4 bytes of the checksum of the input. +.PP +\&\fBDES_fcrypt()\fR returns a pointer to the caller-provided buffer and \fBDES_crypt()\fR \- +to a static buffer on success; otherwise they return NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBdes_modes\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The requirement that the \fBsalt\fR parameter to \fBDES_crypt()\fR and \fBDES_fcrypt()\fR +be two ASCII characters was first enforced in +OpenSSL 1.1.0. Previous versions tried to use the letter uppercase \fBA\fR +if both character were not present, and could crash when given non-ASCII +on some platforms. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DES_set_key.3 b/static/netbsd/man3/DES_set_key.3 new file mode 100644 index 00000000..6a0a5b32 --- /dev/null +++ b/static/netbsd/man3/DES_set_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_set_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_set_key_checked.3 b/static/netbsd/man3/DES_set_key_checked.3 new file mode 100644 index 00000000..5f1130e2 --- /dev/null +++ b/static/netbsd/man3/DES_set_key_checked.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_set_key_checked.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_set_key_unchecked.3 b/static/netbsd/man3/DES_set_key_unchecked.3 new file mode 100644 index 00000000..6f67510d --- /dev/null +++ b/static/netbsd/man3/DES_set_key_unchecked.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_set_key_unchecked.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_set_odd_parity.3 b/static/netbsd/man3/DES_set_odd_parity.3 new file mode 100644 index 00000000..4ff86038 --- /dev/null +++ b/static/netbsd/man3/DES_set_odd_parity.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_set_odd_parity.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DES_string_to_key.3 b/static/netbsd/man3/DES_string_to_key.3 new file mode 100644 index 00000000..17346421 --- /dev/null +++ b/static/netbsd/man3/DES_string_to_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DES_string_to_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_des.3 diff --git a/static/netbsd/man3/DH_check_pubkey.3 b/static/netbsd/man3/DH_check_pubkey.3 new file mode 100644 index 00000000..24892f6c --- /dev/null +++ b/static/netbsd/man3/DH_check_pubkey.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_check_pubkey.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_compute_key.3 b/static/netbsd/man3/DH_compute_key.3 new file mode 100644 index 00000000..814ed388 --- /dev/null +++ b/static/netbsd/man3/DH_compute_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_compute_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_free.3 b/static/netbsd/man3/DH_free.3 new file mode 100644 index 00000000..5be02aaf --- /dev/null +++ b/static/netbsd/man3/DH_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_generate_key.3 b/static/netbsd/man3/DH_generate_key.3 new file mode 100644 index 00000000..af527aae --- /dev/null +++ b/static/netbsd/man3/DH_generate_key.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: DH_generate_key.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_generate_key 3" +.TH DH_generate_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_generate_key, DH_compute_key, DH_compute_key_padded \- perform +Diffie\-Hellman key exchange +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int DH_generate_key(DH *dh); +\& +\& int DH_compute_key(unsigned char *key, const BIGNUM *pub_key, DH *dh); +\& +\& int DH_compute_key_padded(unsigned char *key, const BIGNUM *pub_key, DH *dh); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_derive_init\fR\|(3) +and \fBEVP_PKEY_derive\fR\|(3). +.PP +\&\fBDH_generate_key()\fR performs the first step of a Diffie\-Hellman key +exchange by generating private and public DH values. By calling +\&\fBDH_compute_key()\fR or \fBDH_compute_key_padded()\fR, these are combined with +the other party\*(Aqs public value to compute the shared key. +.PP +\&\fBDH_generate_key()\fR expects \fBdh\fR to contain the shared parameters +\&\fBdh\->p\fR and \fBdh\->g\fR. It generates a random private DH value +unless \fBdh\->priv_key\fR is already set, and computes the +corresponding public value \fBdh\->pub_key\fR, which can then be +published. +.PP +\&\fBDH_compute_key()\fR computes the shared secret from the private DH value +in \fBdh\fR and the other party\*(Aqs public value in \fBpub_key\fR and stores +it in \fBkey\fR. \fBkey\fR must point to \fBDH_size(dh)\fR bytes of memory. +The padding style is RFC 5246 (8.1.2) that strips leading zero bytes. +It is not constant time due to the leading zero bytes being stripped. +The return value should be considered public. +.PP +\&\fBDH_compute_key_padded()\fR is similar but stores a fixed number of bytes. +The padding style is NIST SP 800\-56A (C.1) that retains leading zero bytes. +It is constant time due to the leading zero bytes being retained. +The return value should be considered public. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_generate_key()\fR returns 1 on success, 0 otherwise. +.PP +\&\fBDH_compute_key()\fR returns the size of the shared secret on success, \-1 +on error. +.PP +\&\fBDH_compute_key_padded()\fR returns \fBDH_size(dh)\fR on success, \-1 on error. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBDH_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), \fBDH_size\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBDH_compute_key_padded()\fR was added in OpenSSL 1.0.2. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_generate_parameters.3 b/static/netbsd/man3/DH_generate_parameters.3 new file mode 100644 index 00000000..682284d8 --- /dev/null +++ b/static/netbsd/man3/DH_generate_parameters.3 @@ -0,0 +1,217 @@ +.\" $NetBSD: DH_generate_parameters.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_generate_parameters 3" +.TH DH_generate_parameters 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_generate_parameters_ex, DH_generate_parameters, +DH_check, DH_check_params, +DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex +\&\- generate and check Diffie\-Hellman +parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb); +\& +\& int DH_check(DH *dh, int *codes); +\& int DH_check_params(DH *dh, int *codes); +\& +\& int DH_check_ex(const DH *dh); +\& int DH_check_params_ex(const DH *dh); +\& int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key); +.Ve +.PP +The following functions have been deprecated since OpenSSL 0.9.8, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& DH *DH_generate_parameters(int prime_len, int generator, +\& void (*callback)(int, int, void *), void *cb_arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_check\fR\|(3), +\&\fBEVP_PKEY_public_check\fR\|(3), \fBEVP_PKEY_private_check\fR\|(3) and +\&\fBEVP_PKEY_param_check\fR\|(3). +.PP +\&\fBDH_generate_parameters_ex()\fR generates Diffie\-Hellman parameters that can +be shared among a group of users, and stores them in the provided \fBDH\fR +structure. The pseudo\-random number generator must be +seeded before calling it. +The parameters generated by \fBDH_generate_parameters_ex()\fR should not be used in +signature schemes. +.PP +\&\fBprime_len\fR is the length in bits of the safe prime to be generated. +\&\fBgenerator\fR is a small number > 1, typically 2 or 5. +.PP +A callback function may be used to provide feedback about the progress +of the key generation. If \fBcb\fR is not \fBNULL\fR, it will be +called as described in \fBBN_generate_prime\fR\|(3) while a random prime +number is generated, and when a prime has been found, \fBBN_GENCB_call(cb, 3, 0)\fR +is called. See \fBBN_generate_prime_ex\fR\|(3) for information on +the \fBBN_GENCB_call()\fR function. +.PP +\&\fBDH_generate_parameters()\fR is similar to \fBDH_generate_prime_ex()\fR but +expects an old\-style callback function; see +\&\fBBN_generate_prime\fR\|(3) for information on the old\-style callback. +.PP +\&\fBDH_check_params()\fR confirms that the \fBp\fR and \fBg\fR are likely enough to +be valid. +This is a lightweight check, if a more thorough check is needed, use +\&\fBDH_check()\fR. +The value of \fB*codes\fR is updated with any problems found. +If \fB*codes\fR is zero then no problems were found, otherwise the +following bits may be set: +.IP DH_CHECK_P_NOT_PRIME 4 +.IX Item "DH_CHECK_P_NOT_PRIME" +The parameter \fBp\fR has been determined to not being an odd prime. +Note that the lack of this bit doesn\*(Aqt guarantee that \fBp\fR is a +prime. +.IP DH_NOT_SUITABLE_GENERATOR 4 +.IX Item "DH_NOT_SUITABLE_GENERATOR" +The generator \fBg\fR is not suitable. +Note that the lack of this bit doesn\*(Aqt guarantee that \fBg\fR is +suitable, unless \fBp\fR is known to be a strong prime. +.IP DH_MODULUS_TOO_SMALL 4 +.IX Item "DH_MODULUS_TOO_SMALL" +The modulus is too small. +.IP DH_MODULUS_TOO_LARGE 4 +.IX Item "DH_MODULUS_TOO_LARGE" +The modulus is too large. +.PP +\&\fBDH_check()\fR confirms that the Diffie\-Hellman parameters \fBdh\fR are valid. The +value of \fB*codes\fR is updated with any problems found. If \fB*codes\fR is zero then +no problems were found, otherwise the following bits may be set: +.IP DH_CHECK_P_NOT_PRIME 4 +.IX Item "DH_CHECK_P_NOT_PRIME" +The parameter \fBp\fR is not prime. +.IP DH_CHECK_P_NOT_SAFE_PRIME 4 +.IX Item "DH_CHECK_P_NOT_SAFE_PRIME" +The parameter \fBp\fR is not a safe prime and no \fBq\fR value is present. +.IP DH_UNABLE_TO_CHECK_GENERATOR 4 +.IX Item "DH_UNABLE_TO_CHECK_GENERATOR" +The generator \fBg\fR cannot be checked for suitability. +.IP DH_NOT_SUITABLE_GENERATOR 4 +.IX Item "DH_NOT_SUITABLE_GENERATOR" +The generator \fBg\fR is not suitable. +.IP DH_CHECK_Q_NOT_PRIME 4 +.IX Item "DH_CHECK_Q_NOT_PRIME" +The parameter \fBq\fR is not prime. +.IP DH_CHECK_INVALID_Q_VALUE 4 +.IX Item "DH_CHECK_INVALID_Q_VALUE" +The parameter \fBq\fR is invalid. +.IP DH_CHECK_INVALID_J_VALUE 4 +.IX Item "DH_CHECK_INVALID_J_VALUE" +The parameter \fBj\fR is invalid. +.PP +If 0 is returned or \fB*codes\fR is set to a nonzero value the supplied +parameters should not be used for Diffie\-Hellman operations otherwise +the security properties of the key exchange are not guaranteed. +.PP +\&\fBDH_check_ex()\fR, \fBDH_check_params()\fR and \fBDH_check_pub_key_ex()\fR are similar to +\&\fBDH_check()\fR and \fBDH_check_params()\fR respectively, but the error reasons are added +to the thread\*(Aqs error queue instead of provided as return values from the +function. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_generate_parameters_ex()\fR, \fBDH_check()\fR and \fBDH_check_params()\fR return 1 +if the check could be performed, 0 otherwise. +.PP +\&\fBDH_generate_parameters()\fR returns a pointer to the DH structure or NULL if +the parameter generation fails. +.PP +\&\fBDH_check_ex()\fR, \fBDH_check_params()\fR and \fBDH_check_pub_key_ex()\fR return 1 if the +check is successful, 0 for failed. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBDH_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +\&\fBDH_generate_parameters()\fR was deprecated in OpenSSL 0.9.8; use +\&\fBDH_generate_parameters_ex()\fR instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_generate_parameters_ex.3 b/static/netbsd/man3/DH_generate_parameters_ex.3 new file mode 100644 index 00000000..8022afe9 --- /dev/null +++ b/static/netbsd/man3/DH_generate_parameters_ex.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_generate_parameters_ex.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_get0_pqg.3 b/static/netbsd/man3/DH_get0_pqg.3 new file mode 100644 index 00000000..f6774b25 --- /dev/null +++ b/static/netbsd/man3/DH_get0_pqg.3 @@ -0,0 +1,210 @@ +.\" $NetBSD: DH_get0_pqg.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_get0_pqg 3" +.TH DH_get0_pqg 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, +DH_get0_p, DH_get0_q, DH_get0_g, +DH_get0_priv_key, DH_get0_pub_key, +DH_clear_flags, DH_test_flags, DH_set_flags, DH_get0_engine, +DH_get_length, DH_set_length \- Routines for getting and setting data in a DH object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& void DH_get0_pqg(const DH *dh, +\& const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); +\& int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g); +\& void DH_get0_key(const DH *dh, +\& const BIGNUM **pub_key, const BIGNUM **priv_key); +\& int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key); +\& const BIGNUM *DH_get0_p(const DH *dh); +\& const BIGNUM *DH_get0_q(const DH *dh); +\& const BIGNUM *DH_get0_g(const DH *dh); +\& const BIGNUM *DH_get0_priv_key(const DH *dh); +\& const BIGNUM *DH_get0_pub_key(const DH *dh); +\& void DH_clear_flags(DH *dh, int flags); +\& int DH_test_flags(const DH *dh, int flags); +\& void DH_set_flags(DH *dh, int flags); +\& +\& long DH_get_length(const DH *dh); +\& int DH_set_length(DH *dh, long length); +\& +\& ENGINE *DH_get0_engine(DH *d); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_bn_param\fR\|(3) for any methods that +return a \fBBIGNUM\fR. Refer to \fBEVP_PKEY\-DH\fR\|(7) for more information. +.PP +A DH object contains the parameters \fIp\fR, \fIq\fR and \fIg\fR. Note that the \fIq\fR +parameter is optional. It also contains a public key (\fIpub_key\fR) and +(optionally) a private key (\fIpriv_key\fR). +.PP +The \fIp\fR, \fIq\fR and \fIg\fR parameters can be obtained by calling \fBDH_get0_pqg()\fR. +If the parameters have not yet been set then \fI*p\fR, \fI*q\fR and \fI*g\fR will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. +Any of the out parameters \fIp\fR, \fIq\fR, and \fIg\fR can be NULL, in which case no +value will be returned for that parameter. +.PP +The \fIp\fR, \fIq\fR and \fIg\fR values can be set by calling \fBDH_set0_pqg()\fR and passing +the new values for \fIp\fR, \fIq\fR and \fIg\fR as parameters to the function. Calling +this function transfers the memory management of the values to the DH object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. The \fIq\fR parameter may be NULL. +\&\fBDH_set0_pqg()\fR also checks if the parameters associated with \fIp\fR and \fIg\fR and +optionally \fIq\fR are associated with known safe prime groups. If it is a safe +prime group then the value of \fIq\fR will be set to q = (p \- 1) / 2 if \fIq\fR is +NULL. The optional length parameter will be set to BN_num_bits(\fIq\fR) if \fIq\fR +is not NULL. +.PP +To get the public and private key values use the \fBDH_get0_key()\fR function. A +pointer to the public key will be stored in \fI*pub_key\fR, and a pointer to the +private key will be stored in \fI*priv_key\fR. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. +Any of the out parameters \fIpub_key\fR and \fIpriv_key\fR can be NULL, in which case +no value will be returned for that parameter. +.PP +The public and private key values can be set using \fBDH_set0_key()\fR. Either +parameter may be NULL, which means the corresponding DH field is left +untouched. As with \fBDH_set0_pqg()\fR this function transfers the memory management +of the key values to the DH object, and therefore they should not be freed +directly after this function has been called. +.PP +Any of the values \fIp\fR, \fIq\fR, \fIg\fR, \fIpriv_key\fR, and \fIpub_key\fR can also be +retrieved separately by the corresponding function \fBDH_get0_p()\fR, \fBDH_get0_q()\fR, +\&\fBDH_get0_g()\fR, \fBDH_get0_priv_key()\fR, and \fBDH_get0_pub_key()\fR, respectively. +.PP +\&\fBDH_set_flags()\fR sets the flags in the \fIflags\fR parameter on the DH object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. \fBDH_test_flags()\fR tests to see whether the flags +passed in the \fIflags\fR parameter are currently set in the DH object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. \fBDH_clear_flags()\fR clears the specified flags +within the DH object. +.PP +\&\fBDH_get0_engine()\fR returns a handle to the ENGINE that has been set for this DH +object, or NULL if no such ENGINE has been set. This function is deprecated. All +engines should be replaced by providers. +.PP +The \fBDH_get_length()\fR and \fBDH_set_length()\fR functions get and set the optional +length parameter associated with this DH object. If the length is nonzero then +it is used, otherwise it is ignored. The \fIlength\fR parameter indicates the +length of the secret exponent (private key) in bits. For safe prime groups the optional length parameter \fIlength\fR can be +set to a value greater or equal to 2 * maximum_target_security_strength(BN_num_bits(\fIp\fR)) +as listed in SP800\-56Ar3 Table(s) 25 & 26. +These functions are deprecated and should be replaced with +\&\fBEVP_PKEY_CTX_set_params()\fR and \fBEVP_PKEY_get_int_param()\fR using the parameter key +\&\fBOSSL_PKEY_PARAM_DH_PRIV_LEN\fR as described in \fBEVP_PKEY\-DH\fR\|(7). +.SH NOTES +.IX Header "NOTES" +Values retrieved with \fBDH_get0_key()\fR are owned by the DH object used +in the call and may therefore \fInot\fR be passed to \fBDH_set0_key()\fR. If +needed, duplicate the received value using \fBBN_dup()\fR and pass the +duplicate. The same applies to \fBDH_get0_pqg()\fR and \fBDH_set0_pqg()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_set0_pqg()\fR and \fBDH_set0_key()\fR return 1 on success or 0 on failure. +.PP +\&\fBDH_get0_p()\fR, \fBDH_get0_q()\fR, \fBDH_get0_g()\fR, \fBDH_get0_priv_key()\fR, and \fBDH_get0_pub_key()\fR +return the respective value, or NULL if it is unset. +.PP +\&\fBDH_test_flags()\fR returns the current state of the flags in the DH object. +.PP +\&\fBDH_get0_engine()\fR returns the ENGINE set for the DH object or NULL if no ENGINE +has been set. +.PP +\&\fBDH_get_length()\fR returns the length of the secret exponent (private key) in bits, +or zero if no such length has been explicitly set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBDH_new\fR\|(3), \fBDH_generate_parameters\fR\|(3), \fBDH_generate_key\fR\|(3), +\&\fBDH_set_method\fR\|(3), \fBDH_size\fR\|(3), \fBDH_meth_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 1.1.0. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_get_1024_160.3 b/static/netbsd/man3/DH_get_1024_160.3 new file mode 100644 index 00000000..e4a665d1 --- /dev/null +++ b/static/netbsd/man3/DH_get_1024_160.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: DH_get_1024_160.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_get_1024_160 3" +.TH DH_get_1024_160 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_get_1024_160, +DH_get_2048_224, +DH_get_2048_256, +BN_get0_nist_prime_192, +BN_get0_nist_prime_224, +BN_get0_nist_prime_256, +BN_get0_nist_prime_384, +BN_get0_nist_prime_521, +BN_get_rfc2409_prime_768, +BN_get_rfc2409_prime_1024, +BN_get_rfc3526_prime_1536, +BN_get_rfc3526_prime_2048, +BN_get_rfc3526_prime_3072, +BN_get_rfc3526_prime_4096, +BN_get_rfc3526_prime_6144, +BN_get_rfc3526_prime_8192 +\&\- Create standardized public primes or DH pairs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const BIGNUM *BN_get0_nist_prime_192(void); +\& const BIGNUM *BN_get0_nist_prime_224(void); +\& const BIGNUM *BN_get0_nist_prime_256(void); +\& const BIGNUM *BN_get0_nist_prime_384(void); +\& const BIGNUM *BN_get0_nist_prime_521(void); +\& +\& BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn); +\& BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn); +\& BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& DH *DH_get_1024_160(void); +\& DH *DH_get_2048_224(void); +\& DH *DH_get_2048_256(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR, and \fBDH_get_2048_256()\fR each return +a DH object for the IETF RFC 5114 value. These functions are deprecated. +Applications should instead use \fBEVP_PKEY_CTX_set_dh_rfc5114()\fR and +\&\fBEVP_PKEY_CTX_set_dhx_rfc5114()\fR as described in \fBEVP_PKEY_CTX_ctrl\fR\|(3) or +by setting the \fBOSSL_PKEY_PARAM_GROUP_NAME\fR as specified in +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7)) to one of "dh_1024_160", "dh_2048_224" or +"dh_2048_256". +.PP +\&\fBBN_get0_nist_prime_192()\fR, \fBBN_get0_nist_prime_224()\fR, \fBBN_get0_nist_prime_256()\fR, +\&\fBBN_get0_nist_prime_384()\fR, and \fBBN_get0_nist_prime_521()\fR functions return +a BIGNUM for the specific NIST prime curve (e.g., P\-256). +.PP +\&\fBBN_get_rfc2409_prime_768()\fR, \fBBN_get_rfc2409_prime_1024()\fR, +\&\fBBN_get_rfc3526_prime_1536()\fR, \fBBN_get_rfc3526_prime_2048()\fR, +\&\fBBN_get_rfc3526_prime_3072()\fR, \fBBN_get_rfc3526_prime_4096()\fR, +\&\fBBN_get_rfc3526_prime_6144()\fR, and \fBBN_get_rfc3526_prime_8192()\fR functions +return a BIGNUM for the specified size from IETF RFC 2409. If \fBbn\fR +is not NULL, the BIGNUM will be set into that location as well. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Defined above. +.SH HISTORY +.IX Header "HISTORY" +The functions \fBDH_get_1024_160()\fR, \fBDH_get_2048_224()\fR and \fBDH_get_2048_256()\fR were +deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_get_default_method.3 b/static/netbsd/man3/DH_get_default_method.3 new file mode 100644 index 00000000..39c17713 --- /dev/null +++ b/static/netbsd/man3/DH_get_default_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_get_default_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_get_ex_data.3 b/static/netbsd/man3/DH_get_ex_data.3 new file mode 100644 index 00000000..854c8aaa --- /dev/null +++ b/static/netbsd/man3/DH_get_ex_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_get_ex_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_get_ex_new_index.3 b/static/netbsd/man3/DH_get_ex_new_index.3 new file mode 100644 index 00000000..7c0dcaea --- /dev/null +++ b/static/netbsd/man3/DH_get_ex_new_index.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: DH_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:38 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "DH_get_ex_new_index 3" +.TH DH_get_ex_new_index 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data \- add application specific data to DH structures +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int DH_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int DH_set_ex_data(DH *d, int idx, void *arg); +\& +\& char *DH_get_ex_data(DH *d, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions handle application specific data in \s-1DH\s0 +structures. Their usage is identical to that of +\&\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR +as described in \fIRSA_get_ex_new_index\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIRSA_get_ex_new_index\fR\|(3), \fIopenssl_dh\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIDH_get_ex_new_index()\fR, \fIDH_set_ex_data()\fR and \fIDH_get_ex_data()\fR are +available since OpenSSL 0.9.5. diff --git a/static/netbsd/man3/DH_ltm_method.3 b/static/netbsd/man3/DH_ltm_method.3 new file mode 100644 index 00000000..0a06f5fb --- /dev/null +++ b/static/netbsd/man3/DH_ltm_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_ltm_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_meth_new.3 b/static/netbsd/man3/DH_meth_new.3 new file mode 100644 index 00000000..f082c312 --- /dev/null +++ b/static/netbsd/man3/DH_meth_new.3 @@ -0,0 +1,238 @@ +.\" $NetBSD: DH_meth_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_meth_new 3" +.TH DH_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, +DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, +DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, +DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, +DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, +DH_meth_set_finish, DH_meth_get_generate_params, +DH_meth_set_generate_params \- Routines to build up DH methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DH_METHOD *DH_meth_new(const char *name, int flags); +\& +\& void DH_meth_free(DH_METHOD *dhm); +\& +\& DH_METHOD *DH_meth_dup(const DH_METHOD *dhm); +\& +\& const char *DH_meth_get0_name(const DH_METHOD *dhm); +\& int DH_meth_set1_name(DH_METHOD *dhm, const char *name); +\& +\& int DH_meth_get_flags(const DH_METHOD *dhm); +\& int DH_meth_set_flags(DH_METHOD *dhm, int flags); +\& +\& void *DH_meth_get0_app_data(const DH_METHOD *dhm); +\& int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data); +\& +\& int (*DH_meth_get_generate_key(const DH_METHOD *dhm))(DH *); +\& int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key)(DH *)); +\& +\& int (*DH_meth_get_compute_key(const DH_METHOD *dhm)) +\& (unsigned char *key, const BIGNUM *pub_key, DH *dh); +\& int DH_meth_set_compute_key(DH_METHOD *dhm, +\& int (*compute_key)(unsigned char *key, const BIGNUM *pub_key, DH *dh)); +\& +\& int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm)) +\& (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); +\& int DH_meth_set_bn_mod_exp(DH_METHOD *dhm, +\& int (*bn_mod_exp)(const DH *dh, BIGNUM *r, const BIGNUM *a, +\& const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, +\& BN_MONT_CTX *m_ctx)); +\& +\& int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *); +\& int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *)); +\& +\& int (*DH_meth_get_finish(const DH_METHOD *dhm))(DH *); +\& int DH_meth_set_finish(DH_METHOD *dhm, int (*finish)(DH *)); +\& +\& int (*DH_meth_get_generate_params(const DH_METHOD *dhm)) +\& (DH *, int, int, BN_GENCB *); +\& int DH_meth_set_generate_params(DH_METHOD *dhm, +\& int (*generate_params)(DH *, int, int, BN_GENCB *)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the provider APIs. +.PP +The \fBDH_METHOD\fR type is a structure used for the provision of custom DH +implementations. It provides a set of functions used by OpenSSL for the +implementation of the various DH capabilities. +.PP +\&\fBDH_meth_new()\fR creates a new \fBDH_METHOD\fR structure. It should be given a +unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a NULL terminated +string, which will be duplicated and stored in the \fBDH_METHOD\fR object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new \fBDH\fR object based on this \fBDH_METHOD\fR. Any +new \fBDH\fR object will have those flags set by default. +.PP +\&\fBDH_meth_dup()\fR creates a duplicate copy of the \fBDH_METHOD\fR object passed as a +parameter. This might be useful for creating a new \fBDH_METHOD\fR based on an +existing one, but with some differences. +.PP +\&\fBDH_meth_free()\fR destroys a \fBDH_METHOD\fR structure and frees up any memory +associated with it. If the argument is NULL, nothing is done. +.PP +\&\fBDH_meth_get0_name()\fR will return a pointer to the name of this DH_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. \fBDH_meth_set1_name()\fR sets the name of the DH_METHOD to \fBname\fR. The +string is duplicated and the copy is stored in the DH_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. +.PP +\&\fBDH_meth_get_flags()\fR returns the current value of the flags associated with this +DH_METHOD. \fBDH_meth_set_flags()\fR provides the ability to set these flags. +.PP +The functions \fBDH_meth_get0_app_data()\fR and \fBDH_meth_set0_app_data()\fR provide the +ability to associate implementation specific data with the DH_METHOD. It is +the application\*(Aqs responsibility to free this data before the DH_METHOD is +freed via a call to \fBDH_meth_free()\fR. +.PP +\&\fBDH_meth_get_generate_key()\fR and \fBDH_meth_set_generate_key()\fR get and set the +function used for generating a new DH key pair respectively. This function will +be called in response to the application calling \fBDH_generate_key()\fR. The +parameter for the function has the same meaning as for \fBDH_generate_key()\fR. +.PP +\&\fBDH_meth_get_compute_key()\fR and \fBDH_meth_set_compute_key()\fR get and set the +function used for computing a new DH shared secret respectively. This function +will be called in response to the application calling \fBDH_compute_key()\fR. The +parameters for the function have the same meaning as for \fBDH_compute_key()\fR. +.PP +\&\fBDH_meth_get_bn_mod_exp()\fR and \fBDH_meth_set_bn_mod_exp()\fR get and set the function +used for computing the following value: +.PP +.Vb 1 +\& r = a ^ p mod m +.Ve +.PP +This function will be called by the default OpenSSL function for +\&\fBDH_generate_key()\fR. The result is stored in the \fBr\fR parameter. This function +may be NULL unless using the default generate key function, in which case it +must be present. +.PP +\&\fBDH_meth_get_init()\fR and \fBDH_meth_set_init()\fR get and set the function used +for creating a new DH instance respectively. This function will be +called in response to the application calling \fBDH_new()\fR (if the current default +DH_METHOD is this one) or \fBDH_new_method()\fR. The \fBDH_new()\fR and \fBDH_new_method()\fR +functions will allocate the memory for the new DH object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. +.PP +\&\fBDH_meth_get_finish()\fR and \fBDH_meth_set_finish()\fR get and set the function used +for destroying an instance of a DH object respectively. This function will be +called in response to the application calling \fBDH_free()\fR. A pointer to the DH +to be destroyed is passed as a parameter. The destroy function should be used +for DH implementation specific clean up. The memory for the DH itself should +not be freed by this function. This function may be NULL. +.PP +\&\fBDH_meth_get_generate_params()\fR and \fBDH_meth_set_generate_params()\fR get and set the +function used for generating DH parameters respectively. This function will be +called in response to the application calling \fBDH_generate_parameters_ex()\fR (or +\&\fBDH_generate_parameters()\fR). The parameters for the function have the same +meaning as for \fBDH_generate_parameters_ex()\fR. This function may be NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_meth_new()\fR and \fBDH_meth_dup()\fR return the newly allocated DH_METHOD object +or NULL on failure. +.PP +\&\fBDH_meth_get0_name()\fR and \fBDH_meth_get_flags()\fR return the name and flags +associated with the DH_METHOD respectively. +.PP +All other DH_meth_get_*() functions return the appropriate function pointer +that has been set in the DH_METHOD, or NULL if no such pointer has yet been +set. +.PP +\&\fBDH_meth_set1_name()\fR and all DH_meth_set_*() functions return 1 on success or +0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBDH_new\fR\|(3), \fBDH_generate_parameters\fR\|(3), \fBDH_generate_key\fR\|(3), +\&\fBDH_set_method\fR\|(3), \fBDH_size\fR\|(3), \fBDH_get0_pqg\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The functions described here were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_new.3 b/static/netbsd/man3/DH_new.3 new file mode 100644 index 00000000..6ab0a771 --- /dev/null +++ b/static/netbsd/man3/DH_new.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: DH_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_new 3" +.TH DH_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_new, DH_free \- allocate and free DH objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DH* DH_new(void); +\& +\& void DH_free(DH *dh); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDH_new()\fR allocates and initializes a \fBDH\fR structure. +.PP +\&\fBDH_free()\fR frees the \fBDH\fR structure and its components. The values are +erased before the memory is returned to the system. +If \fBdh\fR is NULL nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBDH_new()\fR returns \fBNULL\fR and sets an error +code that can be obtained by \fBERR_get_error\fR\|(3). Otherwise it returns +a pointer to the newly allocated structure. +.PP +\&\fBDH_free()\fR returns no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBERR_get_error\fR\|(3), +\&\fBDH_generate_parameters\fR\|(3), +\&\fBDH_generate_key\fR\|(3), +\&\fBEVP_PKEY\-DH\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +For replacement see \fBEVP_PKEY\-DH\fR\|(7). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_new_by_nid.3 b/static/netbsd/man3/DH_new_by_nid.3 new file mode 100644 index 00000000..6954707d --- /dev/null +++ b/static/netbsd/man3/DH_new_by_nid.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: DH_new_by_nid.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_new_by_nid 3" +.TH DH_new_by_nid 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_new_by_nid, DH_get_nid \- create or get DH named parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DH *DH_new_by_nid(int nid); +\& +\& int DH_get_nid(const DH *dh); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDH_new_by_nid()\fR creates and returns a DH structure containing named parameters +\&\fBnid\fR. Currently \fBnid\fR must be \fBNID_ffdhe2048\fR, \fBNID_ffdhe3072\fR, +\&\fBNID_ffdhe4096\fR, \fBNID_ffdhe6144\fR, \fBNID_ffdhe8192\fR, +\&\fBNID_modp_1536\fR, \fBNID_modp_2048\fR, \fBNID_modp_3072\fR, +\&\fBNID_modp_4096\fR, \fBNID_modp_6144\fR or \fBNID_modp_8192\fR. +.PP +\&\fBDH_get_nid()\fR determines if the parameters contained in \fBdh\fR match +any named safe prime group. It returns the NID corresponding to the matching +parameters or \fBNID_undef\fR if there is no match. +This function is deprecated. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_new_by_nid()\fR returns a set of DH parameters or \fBNULL\fR if an error occurred. +.PP +\&\fBDH_get_nid()\fR returns the NID of the matching set of parameters for p and g +and optionally q, otherwise it returns \fBNID_undef\fR if there is no match. +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_new_method.3 b/static/netbsd/man3/DH_new_method.3 new file mode 100644 index 00000000..5ca8f16f --- /dev/null +++ b/static/netbsd/man3/DH_new_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_new_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_null_method.3 b/static/netbsd/man3/DH_null_method.3 new file mode 100644 index 00000000..9a88e81e --- /dev/null +++ b/static/netbsd/man3/DH_null_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_null_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_set_default_method.3 b/static/netbsd/man3/DH_set_default_method.3 new file mode 100644 index 00000000..f685bead --- /dev/null +++ b/static/netbsd/man3/DH_set_default_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_set_default_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_set_ex_data.3 b/static/netbsd/man3/DH_set_ex_data.3 new file mode 100644 index 00000000..7a623767 --- /dev/null +++ b/static/netbsd/man3/DH_set_ex_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_set_ex_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DH_set_method.3 b/static/netbsd/man3/DH_set_method.3 new file mode 100644 index 00000000..07dce8dc --- /dev/null +++ b/static/netbsd/man3/DH_set_method.3 @@ -0,0 +1,159 @@ +.\" $NetBSD: DH_set_method.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_set_method 3" +.TH DH_set_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_set_default_method, DH_get_default_method, +DH_set_method, DH_new_method, DH_OpenSSL \- select DH method +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void DH_set_default_method(const DH_METHOD *meth); +\& +\& const DH_METHOD *DH_get_default_method(void); +\& +\& int DH_set_method(DH *dh, const DH_METHOD *meth); +\& +\& DH *DH_new_method(ENGINE *engine); +\& +\& const DH_METHOD *DH_OpenSSL(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the provider APIs. +.PP +A \fBDH_METHOD\fR specifies the functions that OpenSSL uses for Diffie\-Hellman +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these DH API functions are affected by the use +of \fBENGINE\fR API calls. +.PP +Initially, the default DH_METHOD is the OpenSSL internal implementation, as +returned by \fBDH_OpenSSL()\fR. +.PP +\&\fBDH_set_default_method()\fR makes \fBmeth\fR the default method for all DH +structures created later. +\&\fBNB\fR: This is true only whilst no ENGINE has been set +as a default for DH, so this function is no longer recommended. +This function is not thread\-safe and should not be called at the same time +as other OpenSSL functions. +.PP +\&\fBDH_get_default_method()\fR returns a pointer to the current default DH_METHOD. +However, the meaningfulness of this result is dependent on whether the ENGINE +API is being used, so this function is no longer recommended. +.PP +\&\fBDH_set_method()\fR selects \fBmeth\fR to perform all operations using the key \fBdh\fR. +This will replace the DH_METHOD used by the DH key and if the previous method +was supplied by an ENGINE, the handle to that ENGINE will be released during the +change. It is possible to have DH keys that only work with certain DH_METHOD +implementations (e.g. from an ENGINE module that supports embedded +hardware\-protected keys), and in such cases attempting to change the DH_METHOD +for the key can have unexpected results. +.PP +\&\fBDH_new_method()\fR allocates and initializes a DH structure so that \fBengine\fR will +be used for the DH operations. If \fBengine\fR is NULL, the default ENGINE for DH +operations is used, and if no default ENGINE is set, the DH_METHOD controlled by +\&\fBDH_set_default_method()\fR is used. +.PP +A new DH_METHOD object may be constructed using \fBDH_meth_new()\fR (see +\&\fBDH_meth_new\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_OpenSSL()\fR and \fBDH_get_default_method()\fR return pointers to the respective +\&\fBDH_METHOD\fRs. +.PP +\&\fBDH_set_default_method()\fR returns no value. +.PP +\&\fBDH_set_method()\fR returns nonzero if the provided \fBmeth\fR was successfully set as +the method for \fBdh\fR (including unloading the ENGINE handle if the previous +method was supplied by an ENGINE). +.PP +\&\fBDH_new_method()\fR returns NULL and sets an error code that can be obtained by +\&\fBERR_get_error\fR\|(3) if the allocation fails. Otherwise it +returns a pointer to the newly allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBDH_new\fR\|(3), \fBDH_meth_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_size.3 b/static/netbsd/man3/DH_size.3 new file mode 100644 index 00000000..fdbda176 --- /dev/null +++ b/static/netbsd/man3/DH_size.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: DH_size.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DH_size 3" +.TH DH_size 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DH_size, DH_bits, DH_security_bits \- get Diffie\-Hellman prime size and +security bits +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int DH_bits(const DH *dh); +\& +\& int DH_size(const DH *dh); +\& +\& int DH_security_bits(const DH *dh); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3) and \fBEVP_PKEY_get_size\fR\|(3). +.PP +\&\fBDH_bits()\fR returns the number of significant bits. +.PP +\&\fBdh\fR and \fBdh\->p\fR must not be \fBNULL\fR. +.PP +\&\fBDH_size()\fR returns the Diffie\-Hellman prime size in bytes. It can be used +to determine how much memory must be allocated for the shared secret +computed by \fBDH_compute_key\fR\|(3). +.PP +\&\fBDH_security_bits()\fR returns the number of security bits of the given \fBdh\fR +key. See \fBBN_security_bits\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDH_bits()\fR returns the number of bits in the key, or \-1 if +\&\fBdh\fR doesn\*(Aqt hold any key parameters. +.PP +\&\fBDH_size()\fR returns the prime size of Diffie\-Hellman in bytes, or \-1 if +\&\fBdh\fR doesn\*(Aqt hold any key parameters. +.PP +\&\fBDH_security_bits()\fR returns the number of security bits, or \-1 if +\&\fBdh\fR doesn\*(Aqt hold any key parameters. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_bits\fR\|(3), +\&\fBDH_new\fR\|(3), \fBDH_generate_key\fR\|(3), +\&\fBBN_num_bits\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DH_up_ref.3 b/static/netbsd/man3/DH_up_ref.3 new file mode 100644 index 00000000..1ed505e8 --- /dev/null +++ b/static/netbsd/man3/DH_up_ref.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: DH_up_ref.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_dh.3 diff --git a/static/netbsd/man3/DSA_SIG_new.3 b/static/netbsd/man3/DSA_SIG_new.3 new file mode 100644 index 00000000..64b15d81 --- /dev/null +++ b/static/netbsd/man3/DSA_SIG_new.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: DSA_SIG_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_SIG_new 3" +.TH DSA_SIG_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_SIG_get0, DSA_SIG_set0, +DSA_SIG_new, DSA_SIG_free \- allocate and free DSA signature objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& DSA_SIG *DSA_SIG_new(void); +\& void DSA_SIG_free(DSA_SIG *a); +\& void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); +\& int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDSA_SIG_new()\fR allocates an empty \fBDSA_SIG\fR structure. +.PP +\&\fBDSA_SIG_free()\fR frees the \fBDSA_SIG\fR structure and its components. The +values are erased before the memory is returned to the system. +If the argument is NULL, nothing is done. +.PP +\&\fBDSA_SIG_get0()\fR returns internal pointers to the \fBr\fR and \fBs\fR values contained +in \fBsig\fR. +.PP +The \fBr\fR and \fBs\fR values can be set by calling \fBDSA_SIG_set0()\fR and passing the +new values for \fBr\fR and \fBs\fR as parameters to the function. Calling this +function transfers the memory management of the values to the DSA_SIG object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBDSA_SIG_new()\fR returns \fBNULL\fR and sets an +error code that can be obtained by +\&\fBERR_get_error\fR\|(3). Otherwise it returns a pointer +to the newly allocated structure. +.PP +\&\fBDSA_SIG_free()\fR returns no value. +.PP +\&\fBDSA_SIG_set0()\fR returns 1 on success or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_free\fR\|(3), \fBEVP_PKEY_get_bn_param\fR\|(3), +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_do_sign.3 b/static/netbsd/man3/DSA_do_sign.3 new file mode 100644 index 00000000..17193b26 --- /dev/null +++ b/static/netbsd/man3/DSA_do_sign.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: DSA_do_sign.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_do_sign 3" +.TH DSA_do_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_do_sign, DSA_do_verify \- raw DSA signature operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); +\& +\& int DSA_do_verify(const unsigned char *dgst, int dgst_len, +\& DSA_SIG *sig, DSA *dsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_sign_init\fR\|(3), \fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3). +.PP +\&\fBDSA_do_sign()\fR computes a digital signature on the \fBlen\fR byte message +digest \fBdgst\fR using the private key \fBdsa\fR and returns it in a +newly allocated \fBDSA_SIG\fR structure. +.PP +\&\fBDSA_sign_setup\fR\|(3) may be used to precompute part +of the signing operation in case signature generation is +time\-critical. +.PP +\&\fBDSA_do_verify()\fR verifies that the signature \fBsig\fR matches a given +message digest \fBdgst\fR of size \fBlen\fR. \fBdsa\fR is the signer\*(Aqs public +key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_do_sign()\fR returns the signature, NULL on error. \fBDSA_do_verify()\fR +returns 1 for a valid signature, 0 for an incorrect signature and \-1 +on error. The error codes can be obtained by +\&\fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBDSA_SIG_new\fR\|(3), +\&\fBDSA_sign\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_dup_DH.3 b/static/netbsd/man3/DSA_dup_DH.3 new file mode 100644 index 00000000..0ee9d8f8 --- /dev/null +++ b/static/netbsd/man3/DSA_dup_DH.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: DSA_dup_DH.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_dup_DH 3" +.TH DSA_dup_DH 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_dup_DH \- create a DH structure out of DSA structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DH *DSA_dup_DH(const DSA *r); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function described on this page is deprecated. There is no direct +replacement, applications should use the EVP_PKEY APIs for Diffie\-Hellman +operations. +.PP +\&\fBDSA_dup_DH()\fR duplicates DSA parameters/keys as DH parameters/keys. q +is lost during that conversion, but the resulting DH parameters +contain its length. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_dup_DH()\fR returns the new \fBDH\fR structure, and NULL on error. The +error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH NOTE +.IX Header "NOTE" +Be careful to avoid small subgroup attacks when using this. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDH_new\fR\|(3), \fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This function was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_generate_key.3 b/static/netbsd/man3/DSA_generate_key.3 new file mode 100644 index 00000000..7a96eed3 --- /dev/null +++ b/static/netbsd/man3/DSA_generate_key.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: DSA_generate_key.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_generate_key 3" +.TH DSA_generate_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_generate_key \- generate DSA key pair +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int DSA_generate_key(DSA *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_keygen_init\fR\|(3) and +\&\fBEVP_PKEY_keygen\fR\|(3) as described in \fBEVP_PKEY\-DSA\fR\|(7). +.PP +\&\fBDSA_generate_key()\fR expects \fBa\fR to contain DSA parameters. It generates +a new key pair and stores it in \fBa\->pub_key\fR and \fBa\->priv_key\fR. +.PP +The random generator must be seeded prior to calling \fBDSA_generate_key()\fR. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_generate_key()\fR returns 1 on success, 0 otherwise. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBDSA_generate_parameters_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This function was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_generate_parameters.3 b/static/netbsd/man3/DSA_generate_parameters.3 new file mode 100644 index 00000000..f6540ca0 --- /dev/null +++ b/static/netbsd/man3/DSA_generate_parameters.3 @@ -0,0 +1,179 @@ +.\" $NetBSD: DSA_generate_parameters.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_generate_parameters 3" +.TH DSA_generate_parameters 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_generate_parameters_ex, DSA_generate_parameters \- generate DSA parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& int DSA_generate_parameters_ex(DSA *dsa, int bits, +\& const unsigned char *seed, int seed_len, +\& int *counter_ret, unsigned long *h_ret, +\& BN_GENCB *cb); +.Ve +.PP +The following functions have been deprecated since OpenSSL 0.9.8, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, +\& int *counter_ret, unsigned long *h_ret, +\& void (*callback)(int, int, void *), void *cb_arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_paramgen_init\fR\|(3) and +\&\fBEVP_PKEY_keygen\fR\|(3) as described in \fBEVP_PKEY\-DSA\fR\|(7). +.PP +\&\fBDSA_generate_parameters_ex()\fR generates primes p and q and a generator g +for use in the DSA and stores the result in \fBdsa\fR. +.PP +\&\fBbits\fR is the length of the prime p to be generated. +For lengths under 2048 bits, the length of q is 160 bits; for lengths +greater than or equal to 2048 bits, the length of q is set to 256 bits. +.PP +If \fBseed\fR is NULL, the primes will be generated at random. +If \fBseed_len\fR is less than the length of q, an error is returned. +.PP +\&\fBDSA_generate_parameters_ex()\fR places the iteration count in +*\fBcounter_ret\fR and a counter used for finding a generator in +*\fBh_ret\fR, unless these are \fBNULL\fR. +.PP +A callback function may be used to provide feedback about the progress +of the key generation. If \fBcb\fR is not \fBNULL\fR, it will be +called as shown below. For information on the BN_GENCB structure and the +BN_GENCB_call function discussed below, refer to +\&\fBBN_generate_prime\fR\|(3). +.PP +\&\fBDSA_generate_parameters()\fR is similar to \fBDSA_generate_parameters_ex()\fR but +expects an old\-style callback function; see +\&\fBBN_generate_prime\fR\|(3) for information on the old\-style callback. +.IP \(bu 2 +When a candidate for q is generated, \fBBN_GENCB_call(cb, 0, m++)\fR is called +(m is 0 for the first candidate). +.IP \(bu 2 +When a candidate for q has passed a test by trial division, +\&\fBBN_GENCB_call(cb, 1, \-1)\fR is called. +While a candidate for q is tested by Miller\-Rabin primality tests, +\&\fBBN_GENCB_call(cb, 1, i)\fR is called in the outer loop +(once for each witness that confirms that the candidate may be prime); +i is the loop counter (starting at 0). +.IP \(bu 2 +When a prime q has been found, \fBBN_GENCB_call(cb, 2, 0)\fR and +\&\fBBN_GENCB_call(cb, 3, 0)\fR are called. +.IP \(bu 2 +Before a candidate for p (other than the first) is generated and tested, +\&\fBBN_GENCB_call(cb, 0, counter)\fR is called. +.IP \(bu 2 +When a candidate for p has passed the test by trial division, +\&\fBBN_GENCB_call(cb, 1, \-1)\fR is called. +While it is tested by the Miller\-Rabin primality test, +\&\fBBN_GENCB_call(cb, 1, i)\fR is called in the outer loop +(once for each witness that confirms that the candidate may be prime). +i is the loop counter (starting at 0). +.IP \(bu 2 +When p has been found, \fBBN_GENCB_call(cb, 2, 1)\fR is called. +.IP \(bu 2 +When the generator has been found, \fBBN_GENCB_call(cb, 3, 1)\fR is called. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_generate_parameters_ex()\fR returns a 1 on success, or 0 otherwise. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.PP +\&\fBDSA_generate_parameters()\fR returns a pointer to the DSA structure or +\&\fBNULL\fR if the parameter generation fails. +.SH BUGS +.IX Header "BUGS" +Seed lengths greater than 20 are not supported. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBDSA_free\fR\|(3), \fBBN_generate_prime\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBDSA_generate_parameters_ex()\fR was deprecated in OpenSSL 3.0. +.PP +\&\fBDSA_generate_parameters()\fR was deprecated in OpenSSL 0.9.8; use +\&\fBDSA_generate_parameters_ex()\fR instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_get0_pqg.3 b/static/netbsd/man3/DSA_get0_pqg.3 new file mode 100644 index 00000000..18d05d92 --- /dev/null +++ b/static/netbsd/man3/DSA_get0_pqg.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: DSA_get0_pqg.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_get0_pqg 3" +.TH DSA_get0_pqg 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, +DSA_get0_p, DSA_get0_q, DSA_get0_g, +DSA_get0_pub_key, DSA_get0_priv_key, +DSA_clear_flags, DSA_test_flags, DSA_set_flags, +DSA_get0_engine \- Routines for getting and +setting data in a DSA object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& void DSA_get0_pqg(const DSA *d, +\& const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); +\& int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g); +\& void DSA_get0_key(const DSA *d, +\& const BIGNUM **pub_key, const BIGNUM **priv_key); +\& int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key); +\& const BIGNUM *DSA_get0_p(const DSA *d); +\& const BIGNUM *DSA_get0_q(const DSA *d); +\& const BIGNUM *DSA_get0_g(const DSA *d); +\& const BIGNUM *DSA_get0_pub_key(const DSA *d); +\& const BIGNUM *DSA_get0_priv_key(const DSA *d); +\& void DSA_clear_flags(DSA *d, int flags); +\& int DSA_test_flags(const DSA *d, int flags); +\& void DSA_set_flags(DSA *d, int flags); +\& ENGINE *DSA_get0_engine(DSA *d); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_bn_param\fR\|(3). +.PP +A DSA object contains the parameters \fBp\fR, \fBq\fR and \fBg\fR. It also contains a +public key (\fBpub_key\fR) and (optionally) a private key (\fBpriv_key\fR). +.PP +The \fBp\fR, \fBq\fR and \fBg\fR parameters can be obtained by calling \fBDSA_get0_pqg()\fR. +If the parameters have not yet been set then \fB*p\fR, \fB*q\fR and \fB*g\fR will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. +.PP +The \fBp\fR, \fBq\fR and \fBg\fR values can be set by calling \fBDSA_set0_pqg()\fR and passing +the new values for \fBp\fR, \fBq\fR and \fBg\fR as parameters to the function. Calling +this function transfers the memory management of the values to the DSA object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. +.PP +To get the public and private key values use the \fBDSA_get0_key()\fR function. A +pointer to the public key will be stored in \fB*pub_key\fR, and a pointer to the +private key will be stored in \fB*priv_key\fR. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. +.PP +The public and private key values can be set using \fBDSA_set0_key()\fR. The public +key must be non\-NULL the first time this function is called on a given DSA +object. The private key may be NULL. On subsequent calls, either may be NULL, +which means the corresponding DSA field is left untouched. As for \fBDSA_set0_pqg()\fR +this function transfers the memory management of the key values to the DSA +object, and therefore they should not be freed directly after this function has +been called. +.PP +Any of the values \fBp\fR, \fBq\fR, \fBg\fR, \fBpriv_key\fR, and \fBpub_key\fR can also be +retrieved separately by the corresponding function \fBDSA_get0_p()\fR, \fBDSA_get0_q()\fR, +\&\fBDSA_get0_g()\fR, \fBDSA_get0_priv_key()\fR, and \fBDSA_get0_pub_key()\fR, respectively. +.PP +\&\fBDSA_set_flags()\fR sets the flags in the \fBflags\fR parameter on the DSA object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. \fBDSA_test_flags()\fR tests to see whether the flags +passed in the \fBflags\fR parameter are currently set in the DSA object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. \fBDSA_clear_flags()\fR clears the specified flags +within the DSA object. +.PP +\&\fBDSA_get0_engine()\fR returns a handle to the ENGINE that has been set for this DSA +object, or NULL if no such ENGINE has been set. +.SH NOTES +.IX Header "NOTES" +Values retrieved with \fBDSA_get0_key()\fR are owned by the DSA object used +in the call and may therefore \fInot\fR be passed to \fBDSA_set0_key()\fR. If +needed, duplicate the received value using \fBBN_dup()\fR and pass the +duplicate. The same applies to \fBDSA_get0_pqg()\fR and \fBDSA_set0_pqg()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_set0_pqg()\fR and \fBDSA_set0_key()\fR return 1 on success or 0 on failure. +.PP +\&\fBDSA_test_flags()\fR returns the current state of the flags in the DSA object. +.PP +\&\fBDSA_get0_engine()\fR returns the ENGINE set for the DSA object or NULL if no ENGINE +has been set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_bn_param\fR\|(3), +\&\fBDSA_new\fR\|(3), \fBDSA_new\fR\|(3), \fBDSA_generate_parameters\fR\|(3), \fBDSA_generate_key\fR\|(3), +\&\fBDSA_dup_DH\fR\|(3), \fBDSA_do_sign\fR\|(3), \fBDSA_set_method\fR\|(3), \fBDSA_SIG_new\fR\|(3), +\&\fBDSA_sign\fR\|(3), \fBDSA_size\fR\|(3), \fBDSA_meth_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 1.1.0 and deprecated in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_get_ex_new_index.3 b/static/netbsd/man3/DSA_get_ex_new_index.3 new file mode 100644 index 00000000..e4fb0aed --- /dev/null +++ b/static/netbsd/man3/DSA_get_ex_new_index.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: DSA_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "DSA_get_ex_new_index 3" +.TH DSA_get_ex_new_index 3 "2009-12-26" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data \- add application specific data to DSA structures +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int DSA_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int DSA_set_ex_data(DSA *d, int idx, void *arg); +\& +\& char *DSA_get_ex_data(DSA *d, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions handle application specific data in \s-1DSA\s0 +structures. Their usage is identical to that of +\&\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR +as described in \fIRSA_get_ex_new_index\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIRSA_get_ex_new_index\fR\|(3), \fIopenssl_dsa\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIDSA_get_ex_new_index()\fR, \fIDSA_set_ex_data()\fR and \fIDSA_get_ex_data()\fR are +available since OpenSSL 0.9.5. diff --git a/static/netbsd/man3/DSA_meth_new.3 b/static/netbsd/man3/DSA_meth_new.3 new file mode 100644 index 00000000..36d4fd39 --- /dev/null +++ b/static/netbsd/man3/DSA_meth_new.3 @@ -0,0 +1,288 @@ +.\" $NetBSD: DSA_meth_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_meth_new 3" +.TH DSA_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, +DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, +DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, +DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, +DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, +DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, +DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, +DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, +DSA_meth_set_keygen \- Routines to build up DSA methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DSA_METHOD *DSA_meth_new(const char *name, int flags); +\& +\& void DSA_meth_free(DSA_METHOD *dsam); +\& +\& DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth); +\& +\& const char *DSA_meth_get0_name(const DSA_METHOD *dsam); +\& int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name); +\& +\& int DSA_meth_get_flags(const DSA_METHOD *dsam); +\& int DSA_meth_set_flags(DSA_METHOD *dsam, int flags); +\& +\& void *DSA_meth_get0_app_data(const DSA_METHOD *dsam); +\& int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data); +\& +\& DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))(const unsigned char *, +\& int, DSA *); +\& int DSA_meth_set_sign(DSA_METHOD *dsam, DSA_SIG *(*sign)(const unsigned char *, +\& int, DSA *)); +\& +\& int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))(DSA *, BN_CTX *,$ +\& BIGNUM **, BIGNUM **); +\& int DSA_meth_set_sign_setup(DSA_METHOD *dsam, int (*sign_setup)(DSA *, BN_CTX *, +\& BIGNUM **, BIGNUM **)); +\& +\& int (*DSA_meth_get_verify(const DSA_METHOD *dsam))(const unsigned char *, +\& int, DSA_SIG *, DSA *); +\& int DSA_meth_set_verify(DSA_METHOD *dsam, int (*verify)(const unsigned char *, +\& int, DSA_SIG *, DSA *)); +\& +\& int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *rr, BIGNUM *a1, +\& BIGNUM *p1, BIGNUM *a2, BIGNUM *p2, +\& BIGNUM *m, BN_CTX *ctx, +\& BN_MONT_CTX *in_mont); +\& int DSA_meth_set_mod_exp(DSA_METHOD *dsam, int (*mod_exp)(DSA *dsa, BIGNUM *rr, +\& BIGNUM *a1, BIGNUM *p1, +\& BIGNUM *a2, BIGNUM *p2, +\& BIGNUM *m, BN_CTX *ctx, +\& BN_MONT_CTX *mont)); +\& +\& int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *r, BIGNUM *a, +\& const BIGNUM *p, const BIGNUM *m, +\& BN_CTX *ctx, BN_MONT_CTX *mont); +\& int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, int (*bn_mod_exp)(DSA *dsa, +\& BIGNUM *r, +\& BIGNUM *a, +\& const BIGNUM *p, +\& const BIGNUM *m, +\& BN_CTX *ctx, +\& BN_MONT_CTX *mont)); +\& +\& int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *); +\& int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *)); +\& +\& int (*DSA_meth_get_finish(const DSA_METHOD *dsam))(DSA *); +\& int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish)(DSA *)); +\& +\& int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))(DSA *, int, +\& const unsigned char *, +\& int, int *, unsigned long *, +\& BN_GENCB *); +\& int DSA_meth_set_paramgen(DSA_METHOD *dsam, +\& int (*paramgen)(DSA *, int, const unsigned char *, +\& int, int *, unsigned long *, BN_GENCB *)); +\& +\& int (*DSA_meth_get_keygen(const DSA_METHOD *dsam))(DSA *); +\& int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen)(DSA *)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications and extension implementations should instead use the +OSSL_PROVIDER APIs. +.PP +The \fBDSA_METHOD\fR type is a structure used for the provision of custom DSA +implementations. It provides a set of functions used by OpenSSL for the +implementation of the various DSA capabilities. +.PP +\&\fBDSA_meth_new()\fR creates a new \fBDSA_METHOD\fR structure. It should be given a +unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a NULL terminated +string, which will be duplicated and stored in the \fBDSA_METHOD\fR object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new \fBDSA\fR object based on this \fBDSA_METHOD\fR. Any +new \fBDSA\fR object will have those flags set by default. +.PP +\&\fBDSA_meth_dup()\fR creates a duplicate copy of the \fBDSA_METHOD\fR object passed as a +parameter. This might be useful for creating a new \fBDSA_METHOD\fR based on an +existing one, but with some differences. +.PP +\&\fBDSA_meth_free()\fR destroys a \fBDSA_METHOD\fR structure and frees up any memory +associated with it. If the argument is NULL, nothing is done. +.PP +\&\fBDSA_meth_get0_name()\fR will return a pointer to the name of this DSA_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. \fBDSA_meth_set1_name()\fR sets the name of the DSA_METHOD to \fBname\fR. The +string is duplicated and the copy is stored in the DSA_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. +.PP +\&\fBDSA_meth_get_flags()\fR returns the current value of the flags associated with this +DSA_METHOD. \fBDSA_meth_set_flags()\fR provides the ability to set these flags. +.PP +The functions \fBDSA_meth_get0_app_data()\fR and \fBDSA_meth_set0_app_data()\fR provide the +ability to associate implementation specific data with the DSA_METHOD. It is +the application\*(Aqs responsibility to free this data before the DSA_METHOD is +freed via a call to \fBDSA_meth_free()\fR. +.PP +\&\fBDSA_meth_get_sign()\fR and \fBDSA_meth_set_sign()\fR get and set the function used for +creating a DSA signature respectively. This function will be +called in response to the application calling \fBDSA_do_sign()\fR (or \fBDSA_sign()\fR). The +parameters for the function have the same meaning as for \fBDSA_do_sign()\fR. +.PP +\&\fBDSA_meth_get_sign_setup()\fR and \fBDSA_meth_set_sign_setup()\fR get and set the function +used for precalculating the DSA signature values \fBk^\-1\fR and \fBr\fR. This function +will be called in response to the application calling \fBDSA_sign_setup()\fR. The +parameters for the function have the same meaning as for \fBDSA_sign_setup()\fR. +.PP +\&\fBDSA_meth_get_verify()\fR and \fBDSA_meth_set_verify()\fR get and set the function used +for verifying a DSA signature respectively. This function will be called in +response to the application calling \fBDSA_do_verify()\fR (or \fBDSA_verify()\fR). The +parameters for the function have the same meaning as for \fBDSA_do_verify()\fR. +.PP +\&\fBDSA_meth_get_mod_exp()\fR and \fBDSA_meth_set_mod_exp()\fR get and set the function used +for computing the following value: +.PP +.Vb 1 +\& rr = a1^p1 * a2^p2 mod m +.Ve +.PP +This function will be called by the default OpenSSL method during verification +of a DSA signature. The result is stored in the \fBrr\fR parameter. This function +may be NULL. +.PP +\&\fBDSA_meth_get_bn_mod_exp()\fR and \fBDSA_meth_set_bn_mod_exp()\fR get and set the function +used for computing the following value: +.PP +.Vb 1 +\& r = a ^ p mod m +.Ve +.PP +This function will be called by the default OpenSSL function for +\&\fBDSA_sign_setup()\fR. The result is stored in the \fBr\fR parameter. This function +may be NULL. +.PP +\&\fBDSA_meth_get_init()\fR and \fBDSA_meth_set_init()\fR get and set the function used +for creating a new DSA instance respectively. This function will be +called in response to the application calling \fBDSA_new()\fR (if the current default +DSA_METHOD is this one) or \fBDSA_new_method()\fR. The \fBDSA_new()\fR and \fBDSA_new_method()\fR +functions will allocate the memory for the new DSA object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. +.PP +\&\fBDSA_meth_get_finish()\fR and \fBDSA_meth_set_finish()\fR get and set the function used +for destroying an instance of a DSA object respectively. This function will be +called in response to the application calling \fBDSA_free()\fR. A pointer to the DSA +to be destroyed is passed as a parameter. The destroy function should be used +for DSA implementation specific clean up. The memory for the DSA itself should +not be freed by this function. This function may be NULL. +.PP +\&\fBDSA_meth_get_paramgen()\fR and \fBDSA_meth_set_paramgen()\fR get and set the function +used for generating DSA parameters respectively. This function will be called in +response to the application calling \fBDSA_generate_parameters_ex()\fR (or +\&\fBDSA_generate_parameters()\fR). The parameters for the function have the same +meaning as for \fBDSA_generate_parameters_ex()\fR. +.PP +\&\fBDSA_meth_get_keygen()\fR and \fBDSA_meth_set_keygen()\fR get and set the function +used for generating a new DSA key pair respectively. This function will be +called in response to the application calling \fBDSA_generate_key()\fR. The parameter +for the function has the same meaning as for \fBDSA_generate_key()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_meth_new()\fR and \fBDSA_meth_dup()\fR return the newly allocated DSA_METHOD object +or NULL on failure. +.PP +\&\fBDSA_meth_get0_name()\fR and \fBDSA_meth_get_flags()\fR return the name and flags +associated with the DSA_METHOD respectively. +.PP +All other DSA_meth_get_*() functions return the appropriate function pointer +that has been set in the DSA_METHOD, or NULL if no such pointer has yet been +set. +.PP +\&\fBDSA_meth_set1_name()\fR and all DSA_meth_set_*() functions return 1 on success or +0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBDSA_new\fR\|(3), \fBDSA_generate_parameters\fR\|(3), \fBDSA_generate_key\fR\|(3), +\&\fBDSA_dup_DH\fR\|(3), \fBDSA_do_sign\fR\|(3), \fBDSA_set_method\fR\|(3), \fBDSA_SIG_new\fR\|(3), +\&\fBDSA_sign\fR\|(3), \fBDSA_size\fR\|(3), \fBDSA_get0_pqg\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were deprecated in OpenSSL 3.0. +.PP +The functions described here were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_new.3 b/static/netbsd/man3/DSA_new.3 new file mode 100644 index 00000000..698dc5fc --- /dev/null +++ b/static/netbsd/man3/DSA_new.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: DSA_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_new 3" +.TH DSA_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_new, DSA_free \- allocate and free DSA objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& DSA* DSA_new(void); +\& +\& void DSA_free(DSA *dsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_new\fR\|(3) and \fBEVP_PKEY_free\fR\|(3). +.PP +\&\fBDSA_new()\fR allocates and initializes a \fBDSA\fR structure. It is equivalent to +calling DSA_new_method(NULL). +.PP +\&\fBDSA_free()\fR frees the \fBDSA\fR structure and its components. The values are +erased before the memory is returned to the system. +If \fBdsa\fR is NULL nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBDSA_new()\fR returns \fBNULL\fR and sets an error +code that can be obtained by +\&\fBERR_get_error\fR\|(3). Otherwise it returns a pointer +to the newly allocated structure. +.PP +\&\fBDSA_free()\fR returns no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), \fBEVP_PKEY_free\fR\|(3), +\&\fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3), +\&\fBDSA_generate_parameters\fR\|(3), +\&\fBDSA_generate_key\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_set_method.3 b/static/netbsd/man3/DSA_set_method.3 new file mode 100644 index 00000000..97922bc5 --- /dev/null +++ b/static/netbsd/man3/DSA_set_method.3 @@ -0,0 +1,159 @@ +.\" $NetBSD: DSA_set_method.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_set_method 3" +.TH DSA_set_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_set_default_method, DSA_get_default_method, +DSA_set_method, DSA_new_method, DSA_OpenSSL \- select DSA method +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void DSA_set_default_method(const DSA_METHOD *meth); +\& +\& const DSA_METHOD *DSA_get_default_method(void); +\& +\& int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); +\& +\& DSA *DSA_new_method(ENGINE *engine); +\& +\& const DSA_METHOD *DSA_OpenSSL(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should providers instead of method overrides. +.PP +A \fBDSA_METHOD\fR specifies the functions that OpenSSL uses for DSA +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these DSA API functions are affected by the use +of \fBENGINE\fR API calls. +.PP +Initially, the default DSA_METHOD is the OpenSSL internal implementation, +as returned by \fBDSA_OpenSSL()\fR. +.PP +\&\fBDSA_set_default_method()\fR makes \fBmeth\fR the default method for all DSA +structures created later. +\&\fBNB\fR: This is true only whilst no ENGINE has +been set as a default for DSA, so this function is no longer recommended. +This function is not thread\-safe and should not be called at the same time +as other OpenSSL functions. +.PP +\&\fBDSA_get_default_method()\fR returns a pointer to the current default +DSA_METHOD. However, the meaningfulness of this result is dependent on +whether the ENGINE API is being used, so this function is no longer +recommended. +.PP +\&\fBDSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key +\&\fBrsa\fR. This will replace the DSA_METHOD used by the DSA key and if the +previous method was supplied by an ENGINE, the handle to that ENGINE will +be released during the change. It is possible to have DSA keys that only +work with certain DSA_METHOD implementations (e.g. from an ENGINE module +that supports embedded hardware\-protected keys), and in such cases +attempting to change the DSA_METHOD for the key can have unexpected +results. See \fBDSA_meth_new\fR\|(3) for information on constructing custom DSA_METHOD +objects; +.PP +\&\fBDSA_new_method()\fR allocates and initializes a DSA structure so that \fBengine\fR +will be used for the DSA operations. If \fBengine\fR is NULL, the default engine +for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD +controlled by \fBDSA_set_default_method()\fR is used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_OpenSSL()\fR and \fBDSA_get_default_method()\fR return pointers to the respective +\&\fBDSA_METHOD\fRs. +.PP +\&\fBDSA_set_default_method()\fR returns no value. +.PP +\&\fBDSA_set_method()\fR returns nonzero if the provided \fBmeth\fR was successfully set as +the method for \fBdsa\fR (including unloading the ENGINE handle if the previous +method was supplied by an ENGINE). +.PP +\&\fBDSA_new_method()\fR returns NULL and sets an error code that can be +obtained by \fBERR_get_error\fR\|(3) if the allocation +fails. Otherwise it returns a pointer to the newly allocated structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBDSA_new\fR\|(3), \fBDSA_meth_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_sign.3 b/static/netbsd/man3/DSA_sign.3 new file mode 100644 index 00000000..d579989c --- /dev/null +++ b/static/netbsd/man3/DSA_sign.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: DSA_sign.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_sign 3" +.TH DSA_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_sign, DSA_sign_setup, DSA_verify \- DSA signatures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int DSA_sign(int type, const unsigned char *dgst, int len, +\& unsigned char *sigret, unsigned int *siglen, DSA *dsa); +\& +\& int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, BIGNUM **rp); +\& +\& int DSA_verify(int type, const unsigned char *dgst, int len, +\& unsigned char *sigbuf, int siglen, DSA *dsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_sign_init\fR\|(3), \fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3). +.PP +\&\fBDSA_sign()\fR computes a digital signature on the \fBlen\fR byte message +digest \fBdgst\fR using the private key \fBdsa\fR and places its ASN.1 DER +encoding at \fBsigret\fR. The length of the signature is places in +*\fBsiglen\fR. \fBsigret\fR must point to DSA_size(\fBdsa\fR) bytes of memory. +.PP +\&\fBDSA_sign_setup()\fR is defined only for backward binary compatibility and +should not be used. +Since OpenSSL 1.1.0 the DSA type is opaque and the output of +\&\fBDSA_sign_setup()\fR cannot be used anyway: calling this function will only +cause overhead, and does not affect the actual signature +(pre\-)computation. +.PP +\&\fBDSA_verify()\fR verifies that the signature \fBsigbuf\fR of size \fBsiglen\fR +matches a given message digest \fBdgst\fR of size \fBlen\fR. +\&\fBdsa\fR is the signer\*(Aqs public key. +.PP +The \fBtype\fR parameter is ignored. +.PP +The random generator must be seeded when \fBDSA_sign()\fR (or \fBDSA_sign_setup()\fR) +is called. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_sign()\fR and \fBDSA_sign_setup()\fR return 1 on success, 0 on error. +\&\fBDSA_verify()\fR returns 1 for a valid signature, 0 for an incorrect +signature and \-1 on error. The error codes can be obtained by +\&\fBERR_get_error\fR\|(3). +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +US Federal Information Processing Standard FIPS186\-4 (Digital Signature +Standard, DSS), ANSI X9.30 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDSA_new\fR\|(3), \fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBDSA_do_sign\fR\|(3), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DSA_size.3 b/static/netbsd/man3/DSA_size.3 new file mode 100644 index 00000000..bd5d3ce8 --- /dev/null +++ b/static/netbsd/man3/DSA_size.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: DSA_size.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DSA_size 3" +.TH DSA_size 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DSA_size, DSA_bits, DSA_security_bits \- get DSA signature size, key bits or security bits +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int DSA_bits(const DSA *dsa); +\& +\& int DSA_size(const DSA *dsa); +\& +\& int DSA_security_bits(const DSA *dsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3) and \fBEVP_PKEY_get_size\fR\|(3). +.PP +\&\fBDSA_bits()\fR returns the number of bits in key \fIdsa\fR: this is the number +of bits in the \fIp\fR parameter. +.PP +\&\fBDSA_size()\fR returns the maximum size of an ASN.1 encoded DSA signature +for key \fIdsa\fR in bytes. It can be used to determine how much memory must +be allocated for a DSA signature. +.PP +\&\fBDSA_security_bits()\fR returns the number of security bits of the given \fIdsa\fR +key. See \fBBN_security_bits\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSA_security_bits()\fR returns the number of security bits in the key, or \-1 if +\&\fIdsa\fR doesn\*(Aqt hold any key parameters. +.PP +\&\fBDSA_bits()\fR returns the number of bits in the key, or \-1 if \fIdsa\fR doesn\*(Aqt +hold any key parameters. +.PP +\&\fBDSA_size()\fR returns the signature size in bytes, or \-1 if \fIdsa\fR doesn\*(Aqt +hold any key parameters. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3), +\&\fBEVP_PKEY_get_size\fR\|(3), +\&\fBDSA_new\fR\|(3), \fBDSA_sign\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DTLS_get_data_mtu.3 b/static/netbsd/man3/DTLS_get_data_mtu.3 new file mode 100644 index 00000000..3840d604 --- /dev/null +++ b/static/netbsd/man3/DTLS_get_data_mtu.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: DTLS_get_data_mtu.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DTLS_get_data_mtu 3" +.TH DTLS_get_data_mtu 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DTLS_get_data_mtu \- Get maximum data payload size +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& size_t DTLS_get_data_mtu(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This function obtains the maximum data payload size for the established +DTLS connection \fBssl\fR, based on the DTLS record MTU and the overhead +of the DTLS record header, encryption and authentication currently in use. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns the maximum data payload size on success, or 0 on failure. +.SH HISTORY +.IX Header "HISTORY" +The \fBDTLS_get_data_mtu()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DTLS_set_timer_cb.3 b/static/netbsd/man3/DTLS_set_timer_cb.3 new file mode 100644 index 00000000..d7fe48f0 --- /dev/null +++ b/static/netbsd/man3/DTLS_set_timer_cb.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: DTLS_set_timer_cb.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DTLS_set_timer_cb 3" +.TH DTLS_set_timer_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DTLS_timer_cb, +DTLS_set_timer_cb +\&\- Set callback for controlling DTLS timer duration +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef unsigned int (*DTLS_timer_cb)(SSL *s, unsigned int timer_us); +\& +\& void DTLS_set_timer_cb(SSL *s, DTLS_timer_cb cb); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This function sets an optional callback function for controlling the +timeout interval on the DTLS protocol. The callback function will be +called by DTLS for every new DTLS packet that is sent. +.PP +The callback should return the timeout interval in micro seconds. +.PP +The \fItimer_us\fR parameter of the callback is the last set timeout +interval returned. On the first invocation of the callback, +this value will be 0. +.PP +At the beginning of the connection, if no timeout callback has been +set via \fBDTLS_set_timer_cb()\fR, the default timeout value is 1 second. +For all subsequent timeouts, the default behavior is to double the +duration up to a maximum of 1 minute. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns void. +.SH HISTORY +.IX Header "HISTORY" +The \fBDTLS_set_timer_cb()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DTLSv1_get_timeout.3 b/static/netbsd/man3/DTLSv1_get_timeout.3 new file mode 100644 index 00000000..438130df --- /dev/null +++ b/static/netbsd/man3/DTLSv1_get_timeout.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: DTLSv1_get_timeout.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DTLSv1_get_timeout 3" +.TH DTLSv1_get_timeout 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DTLSv1_get_timeout \- determine when a DTLS or QUIC SSL object next needs a +timeout event to be handled +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int DTLSv1_get_timeout(SSL *s, struct timeval *tv); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDTLSv1_get_timeout()\fR can be used on a DTLS or QUIC SSL object to determine when +the SSL object next needs to perform internal processing due to the passage of +time. +.PP +Calling \fBDTLSv1_get_timeout()\fR results in \fI*tv\fR being written with an amount of +time left before the SSL object needs have \fBDTLSv1_handle_timeout()\fR called on it. +If the SSL object needs to be ticked immediately, \fI*tv\fR is zeroed and the +function succeeds, returning 1. If no timeout is currently active, this function +returns 0. +.PP +This function is only applicable to DTLS and QUIC objects. It fails if called on +any other kind of SSL object. +.PP +Note that the value output by a call to \fBDTLSv1_get_timeout()\fR may change as a +result of other calls to the SSL object. +.PP +Once the timeout expires, \fBDTLSv1_handle_timeout()\fR should be called to handle any +internal processing which is due; for more information, see +\&\fBDTLSv1_handle_timeout\fR\|(3). +.PP +\&\fBSSL_get_event_timeout\fR\|(3) supersedes all use cases for this this function and +may be used instead of it. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +On success, writes a duration to \fI*tv\fR and returns 1. +.PP +Returns 0 on failure, or if no timeout is currently active. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDTLSv1_handle_timeout\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DTLSv1_handle_timeout.3 b/static/netbsd/man3/DTLSv1_handle_timeout.3 new file mode 100644 index 00000000..faa97174 --- /dev/null +++ b/static/netbsd/man3/DTLSv1_handle_timeout.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: DTLSv1_handle_timeout.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DTLSv1_handle_timeout 3" +.TH DTLSv1_handle_timeout 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DTLSv1_handle_timeout \- handle a pending timeout event for a DTLS or QUIC SSL +object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int DTLSv1_handle_timeout(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBDTLSv1_handle_timeout()\fR handles any timeout events which have become pending +on a DTLS or QUIC SSL object. +.PP +Use \fBDTLSv1_get_timeout\fR\|(3) or \fBSSL_get_event_timeout\fR\|(3) to determine +when to call \fBDTLSv1_handle_timeout()\fR. +.PP +This function is only applicable to DTLS or QUIC SSL objects. It returns 0 if +called on any other kind of SSL object. +.PP +\&\fBSSL_handle_events\fR\|(3) supersedes all use cases for this function and may +be used instead of it. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 if there was a pending timeout event and it was handled successfully. +.PP +Returns 0 if there was no pending timeout event, or if the SSL object is not a +DTLS or QUIC object. +.PP +Returns \-1 if there was a pending timeout event but it could not be handled +successfully. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDTLSv1_get_timeout\fR\|(3), \fBSSL_handle_events\fR\|(3), \fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/DTLSv1_listen.3 b/static/netbsd/man3/DTLSv1_listen.3 new file mode 100644 index 00000000..ffb02284 --- /dev/null +++ b/static/netbsd/man3/DTLSv1_listen.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: DTLSv1_listen.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DTLSv1_listen 3" +.TH DTLSv1_listen 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_stateless, +DTLSv1_listen +\&\- Statelessly listen for incoming connections +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_stateless(SSL *s); +\& int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_stateless()\fR statelessly listens for new incoming TLSv1.3 connections. +\&\fBDTLSv1_listen()\fR statelessly listens for new incoming DTLS connections. If a +ClientHello is received that does not contain a cookie, then they respond with a +request for a new ClientHello that does contain a cookie. If a ClientHello is +received with a cookie that is verified then the function returns in order to +enable the handshake to be completed (for example by using \fBSSL_accept()\fR). +.SH NOTES +.IX Header "NOTES" +Some transport protocols (such as UDP) can be susceptible to amplification +attacks. Unlike TCP there is no initial connection setup in UDP that +validates that the client can actually receive messages on its advertised source +address. An attacker could forge its source IP address and then send handshake +initiation messages to the server. The server would then send its response to +the forged source IP. If the response messages are larger than the original +message then the amplification attack has succeeded. +.PP +If DTLS is used over UDP (or any datagram based protocol that does not validate +the source IP) then it is susceptible to this type of attack. TLSv1.3 is +designed to operate over a stream\-based transport protocol (such as TCP). +If TCP is being used then there is no need to use \fBSSL_stateless()\fR. However, some +stream\-based transport protocols (e.g. QUIC) may not validate the source +address. In this case a TLSv1.3 application would be susceptible to this attack. +.PP +As a countermeasure to this issue TLSv1.3 and DTLS include a stateless cookie +mechanism. The idea is that when a client attempts to connect to a server it +sends a ClientHello message. The server responds with a HelloRetryRequest (in +TLSv1.3) or a HelloVerifyRequest (in DTLS) which contains a unique cookie. The +client then resends the ClientHello, but this time includes the cookie in the +message thus proving that the client is capable of receiving messages sent to +that address. All of this can be done by the server without allocating any +state, and thus without consuming expensive resources. +.PP +OpenSSL implements this capability via the \fBSSL_stateless()\fR and \fBDTLSv1_listen()\fR +functions. The \fBssl\fR parameter should be a newly allocated SSL object with its +read and write BIOs set, in the same way as might be done for a call to +\&\fBSSL_accept()\fR. Typically, for DTLS, the read BIO will be in an "unconnected" +state and thus capable of receiving messages from any peer. +.PP +When a ClientHello is received that contains a cookie that has been verified, +then these functions will return with the \fBssl\fR parameter updated into a state +where the handshake can be continued by a call to (for example) \fBSSL_accept()\fR. +Additionally, for \fBDTLSv1_listen()\fR, the \fBBIO_ADDR\fR pointed to by \fBpeer\fR will be +filled in with details of the peer that sent the ClientHello. If the underlying +BIO is unable to obtain the \fBBIO_ADDR\fR of the peer (for example because the BIO +does not support this), then \fB*peer\fR will be cleared and the family set to +AF_UNSPEC. Typically user code is expected to "connect" the underlying socket to +the peer and continue the handshake in a connected state. +.PP +Warning: It is essential that the calling code connects the underlying socket to +the peer after making use of \fBDTLSv1_listen()\fR. In the typical case where +\&\fBBIO_s_datagram\fR\|(3) is used, the peer address is updated when receiving a +datagram on an unconnected socket. If the socket is not connected, it can +receive datagrams from any host on the network, which will cause subsequent +outgoing datagrams transmitted by DTLS to be transmitted to that host. In other +words, failing to call \fBBIO_connect()\fR or a similar OS\-specific function on a +socket means that any host on the network can cause outgoing DTLS traffic to be +redirected to it by sending a datagram to the socket in question. This does not +break the cryptographic protections of DTLS but may facilitate a +denial\-of\-service attack or allow unencrypted information in the DTLS handshake +to be learned by an attacker. This is due to the historical design of +\&\fBBIO_s_datagram\fR\|(3); see \fBBIO_s_datagram\fR\|(3) for details on this issue. +.PP +Once a socket has been connected, \fBBIO_ctrl_set_connected\fR\|(3) should be used to +inform the BIO that the socket is to be used in connected mode. +.PP +Prior to calling \fBDTLSv1_listen()\fR user code must ensure that cookie generation +and verification callbacks have been set up using +\&\fBSSL_CTX_set_cookie_generate_cb\fR\|(3) and \fBSSL_CTX_set_cookie_verify_cb\fR\|(3) +respectively. For \fBSSL_stateless()\fR, \fBSSL_CTX_set_stateless_cookie_generate_cb\fR\|(3) +and \fBSSL_CTX_set_stateless_cookie_verify_cb\fR\|(3) must be used instead. +.PP +Since \fBDTLSv1_listen()\fR operates entirely statelessly whilst processing incoming +ClientHellos it is unable to process fragmented messages (since this would +require the allocation of state). An implication of this is that \fBDTLSv1_listen()\fR +\&\fBonly\fR supports ClientHellos that fit inside a single datagram. +.PP +For \fBSSL_stateless()\fR if an entire ClientHello message cannot be read without the +"read" BIO becoming empty then the \fBSSL_stateless()\fR call will fail. It is the +application\*(Aqs responsibility to ensure that data read from the "read" BIO during +a single \fBSSL_stateless()\fR call is all from the same peer. +.PP +\&\fBSSL_stateless()\fR will fail (with a 0 return value) if some TLS version less than +TLSv1.3 is used. +.PP +Both \fBSSL_stateless()\fR and \fBDTLSv1_listen()\fR will clear the error queue when they +start. +.PP +\&\fBSSL_stateless()\fR cannot be used with QUIC SSL objects and returns an error if +called on such an object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +For \fBSSL_stateless()\fR a return value of 1 indicates success and the \fBssl\fR object +will be set up ready to continue the handshake. A return value of 0 or \-1 +indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value +of \-1 indicates any other error. User code may retry the \fBSSL_stateless()\fR call. +.PP +For \fBDTLSv1_listen()\fR a return value of >= 1 indicates success. The \fBssl\fR object +will be set up ready to continue the handshake. the \fBpeer\fR value will also be +filled in. +.PP +A return value of 0 indicates a non\-fatal error. This could (for +example) be because of nonblocking IO, or some invalid message having been +received from a peer. Errors may be placed on the OpenSSL error queue with +further information if appropriate. Typically user code is expected to retry the +call to \fBDTLSv1_listen()\fR in the event of a non\-fatal error. +.PP +A return value of <0 indicates a fatal error. This could (for example) be +because of a failure to allocate sufficient memory for the operation. +.PP +For \fBDTLSv1_listen()\fR, prior to OpenSSL 1.1.0, fatal and non\-fatal errors both +produce return codes <= 0 (in typical implementations user code treats all +errors as non\-fatal), whilst return codes >0 indicate success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_set_cookie_generate_cb\fR\|(3), \fBSSL_CTX_set_cookie_verify_cb\fR\|(3), +\&\fBSSL_CTX_set_stateless_cookie_generate_cb\fR\|(3), +\&\fBSSL_CTX_set_stateless_cookie_verify_cb\fR\|(3), \fBSSL_get_error\fR\|(3), +\&\fBSSL_accept\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_stateless()\fR function was added in OpenSSL 1.1.1. +.PP +The \fBDTLSv1_listen()\fR return codes were clarified in OpenSSL 1.1.0. +The type of "peer" also changed in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ECDSA_SIG_new.3 b/static/netbsd/man3/ECDSA_SIG_new.3 new file mode 100644 index 00000000..de2a71a2 --- /dev/null +++ b/static/netbsd/man3/ECDSA_SIG_new.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: ECDSA_SIG_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ECDSA_SIG_new 3" +.TH ECDSA_SIG_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ECDSA_SIG_new, ECDSA_SIG_free, +ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0 +\&\- Functions for creating, destroying and manipulating ECDSA_SIG objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ECDSA_SIG *ECDSA_SIG_new(void); +\& void ECDSA_SIG_free(ECDSA_SIG *sig); +\& void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); +\& const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig); +\& const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig); +\& int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBECDSA_SIG\fR is an opaque structure consisting of two BIGNUMs for the +\&\fIr\fR and \fIs\fR value of an Elliptic Curve Digital Signature Algorithm (ECDSA) signature +(see FIPS186\-4 or X9.62). +The \fBECDSA_SIG\fR object was mainly used by the deprecated low level functions described in +\&\fBECDSA_sign\fR\|(3), it is still required in order to be able to set or get the values of +\&\fIr\fR and \fIs\fR into or from a signature. This is mainly used for testing purposes as shown +in the "EXAMPLES". +.PP +\&\fBECDSA_SIG_new()\fR allocates an empty \fBECDSA_SIG\fR structure. +Note: before OpenSSL 1.1.0, the \fIr\fR and \fIs\fR components were initialised. +.PP +\&\fBECDSA_SIG_free()\fR frees the \fBECDSA_SIG\fR structure \fIsig\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBECDSA_SIG_get0()\fR returns internal pointers the \fIr\fR and \fIs\fR values contained +in \fIsig\fR and stores them in \fI*pr\fR and \fI*ps\fR, respectively. +The pointer \fIpr\fR or \fIps\fR can be NULL, in which case the corresponding value +is not returned. +.PP +The values \fIr\fR, \fIs\fR can also be retrieved separately by the corresponding +function \fBECDSA_SIG_get0_r()\fR and \fBECDSA_SIG_get0_s()\fR, respectively. +.PP +Non\-NULL \fIr\fR and \fIs\fR values can be set on the \fIsig\fR by calling +\&\fBECDSA_SIG_set0()\fR. Calling this function transfers the memory management of the +values to the \fBECDSA_SIG\fR object, and therefore the values that have been +passed in should not be freed by the caller. +.PP +See \fBi2d_ECDSA_SIG\fR\|(3) and \fBd2i_ECDSA_SIG\fR\|(3) for information about encoding +and decoding ECDSA signatures to/from DER. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBECDSA_SIG_new()\fR returns NULL if the allocation fails. +.PP +\&\fBECDSA_SIG_set0()\fR returns 1 on success or 0 on failure. +.PP +\&\fBECDSA_SIG_get0_r()\fR and \fBECDSA_SIG_get0_s()\fR return the corresponding value, +or NULL if it is unset. +.SH EXAMPLES +.IX Header "EXAMPLES" +Extract signature \fIr\fR and \fIs\fR values from a ECDSA \fIsignature\fR +of size \fIsignaturelen\fR: +.PP +.Vb 2 +\& ECDSA_SIG *obj; +\& const BIGNUM *r, *s; +\& +\& /* Load a signature into the ECDSA_SIG object */ +\& obj = d2i_ECDSA_SIG(NULL, &signature, signaturelen); +\& if (obj == NULL) +\& /* error */ +\& +\& r = ECDSA_SIG_get0_r(obj); +\& s = ECDSA_SIG_get0_s(obj); +\& if (r == NULL || s == NULL) +\& /* error */ +\& +\& /* Use BN_bn2binpad() here to convert to r and s into byte arrays */ +\& +\& /* +\& * Do not try to access I or I after calling ECDSA_SIG_free(), +\& * as they are both freed by this call. +\& */ +\& ECDSA_SIG_free(obj); +.Ve +.PP +Convert \fIr\fR and \fIs\fR byte arrays into an ECDSA_SIG \fIsignature\fR of +size \fIsignaturelen\fR: +.PP +.Vb 4 +\& ECDSA_SIG *obj = NULL; +\& unsigned char *signature = NULL; +\& size_t signaturelen; +\& BIGNUM *rbn = NULL, *sbn = NULL; +\& +\& obj = ECDSA_SIG_new(); +\& if (obj == NULL) +\& /* error */ +\& rbn = BN_bin2bn(r, rlen, NULL); +\& sbn = BN_bin2bn(s, slen, NULL); +\& if (rbn == NULL || sbn == NULL) +\& /* error */ +\& +\& if (!ECDSA_SIG_set0(obj, rbn, sbn)) +\& /* error */ +\& /* Set these to NULL since they are now owned by obj */ +\& rbn = sbn = NULL; +\& +\& signaturelen = i2d_ECDSA_SIG(obj, &signature); +\& if (signaturelen <= 0) +\& /* error */ +\& +\& /* +\& * This signature could now be passed to L +\& * or L +\& */ +\& +\& BN_free(rbn); +\& BN_free(sbn); +\& OPENSSL_free(signature); +\& ECDSA_SIG_free(obj); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ANSI X9.62, +US Federal Information Processing Standard FIPS186\-4 +(Digital Signature Standard, DSS) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEC_KEY_new\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3) +\&\fBi2d_ECDSA_SIG\fR\|(3), +\&\fBd2i_ECDSA_SIG\fR\|(3), +\&\fBECDSA_sign\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ECDSA_sign.3 b/static/netbsd/man3/ECDSA_sign.3 new file mode 100644 index 00000000..8a2e58de --- /dev/null +++ b/static/netbsd/man3/ECDSA_sign.3 @@ -0,0 +1,256 @@ +.\" $NetBSD: ECDSA_sign.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ECDSA_sign 3" +.TH ECDSA_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ECDSA_size, ECDSA_sign, ECDSA_do_sign, +ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex, +ECDSA_do_sign_ex \- deprecated low\-level elliptic curve digital signature algorithm +(ECDSA) functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int ECDSA_size(const EC_KEY *eckey); +\& +\& int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, +\& unsigned char *sig, unsigned int *siglen, EC_KEY *eckey); +\& ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len, +\& EC_KEY *eckey); +\& +\& int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, +\& const unsigned char *sig, int siglen, EC_KEY *eckey); +\& int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, +\& const ECDSA_SIG *sig, EC_KEY* eckey); +\& +\& ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, +\& const BIGNUM *kinv, const BIGNUM *rp, +\& EC_KEY *eckey); +\& int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp); +\& int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen, +\& unsigned char *sig, unsigned int *siglen, +\& const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +See \fBECDSA_SIG_new\fR\|(3) for a description of the \fBECDSA_SIG\fR object. +.PP +See \fBi2d_ECDSA_SIG\fR\|(3) and \fBd2i_ECDSA_SIG\fR\|(3) for information about encoding +and decoding ECDSA signatures to/from DER. +.PP +All of the functions described below are deprecated. Applications should +use the higher level \fBEVP\fR interface such as \fBEVP_DigestSignInit\fR\|(3) +or \fBEVP_DigestVerifyInit\fR\|(3) instead. +.PP +\&\fBECDSA_size()\fR returns the maximum length of a DER encoded ECDSA signature +created with the private EC key \fIeckey\fR. To obtain the actual signature +size use \fBEVP_PKEY_sign\fR\|(3) with a NULL \fIsig\fR parameter. +.PP +\&\fBECDSA_sign()\fR computes a digital signature of the \fIdgstlen\fR bytes hash value +\&\fIdgst\fR using the private EC key \fIeckey\fR. The DER encoded signatures is +stored in \fIsig\fR and its length is returned in \fIsiglen\fR. Note: \fIsig\fR must +point to ECDSA_size(eckey) bytes of memory. The parameter \fItype\fR is currently +ignored. \fBECDSA_sign()\fR is wrapper function for \fBECDSA_sign_ex()\fR with \fIkinv\fR +and \fIrp\fR set to NULL. +.PP +\&\fBECDSA_do_sign()\fR is similar to \fBECDSA_sign()\fR except the signature is returned +as a newly allocated \fBECDSA_SIG\fR structure (or NULL on error). \fBECDSA_do_sign()\fR +is a wrapper function for \fBECDSA_do_sign_ex()\fR with \fIkinv\fR and \fIrp\fR set to +NULL. +.PP +\&\fBECDSA_verify()\fR verifies that the signature in \fIsig\fR of size \fIsiglen\fR is a +valid ECDSA signature of the hash value \fIdgst\fR of size \fIdgstlen\fR using the +public key \fIeckey\fR. The parameter \fItype\fR is ignored. +.PP +\&\fBECDSA_do_verify()\fR is similar to \fBECDSA_verify()\fR except the signature is +presented in the form of a pointer to an \fBECDSA_SIG\fR structure. +.PP +The remaining functions utilise the internal \fIkinv\fR and \fIr\fR values used +during signature computation. Most applications will never need to call these +and some external ECDSA ENGINE implementations may not support them at all if +either \fIkinv\fR or \fIr\fR is not NULL. +.PP +\&\fBECDSA_sign_setup()\fR may be used to precompute parts of the signing operation. +\&\fIeckey\fR is the private EC key and \fIctx\fR is a pointer to \fBBN_CTX\fR structure +(or NULL). The precomputed values or returned in \fIkinv\fR and \fIrp\fR and can be +used in a later call to \fBECDSA_sign_ex()\fR or \fBECDSA_do_sign_ex()\fR. +.PP +\&\fBECDSA_sign_ex()\fR computes a digital signature of the \fIdgstlen\fR bytes hash value +\&\fIdgst\fR using the private EC key \fIeckey\fR and the optional pre\-computed values +\&\fIkinv\fR and \fIrp\fR. The DER encoded signature is stored in \fIsig\fR and its +length is returned in \fIsiglen\fR. Note: \fIsig\fR must point to ECDSA_size(eckey) +bytes of memory. The parameter \fItype\fR is ignored. +.PP +\&\fBECDSA_do_sign_ex()\fR is similar to \fBECDSA_sign_ex()\fR except the signature is +returned as a newly allocated \fBECDSA_SIG\fR structure (or NULL on error). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBECDSA_size()\fR returns the maximum length signature or 0 on error. +.PP +\&\fBECDSA_sign()\fR, \fBECDSA_sign_ex()\fR and \fBECDSA_sign_setup()\fR return 1 if successful +or 0 on error. +.PP +\&\fBECDSA_do_sign()\fR and \fBECDSA_do_sign_ex()\fR return a pointer to an allocated +\&\fBECDSA_SIG\fR structure or NULL on error. +.PP +\&\fBECDSA_verify()\fR and \fBECDSA_do_verify()\fR return 1 for a valid +signature, 0 for an invalid signature and \-1 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH EXAMPLES +.IX Header "EXAMPLES" +Creating an ECDSA signature of a given SHA\-256 hash value using the +named curve prime256v1 (aka P\-256). +This example uses deprecated functionality. See "DESCRIPTION". +.PP +First step: create an EC_KEY object (note: this part is \fBnot\fR ECDSA +specific) +.PP +.Vb 3 +\& int ret; +\& ECDSA_SIG *sig; +\& EC_KEY *eckey; +\& +\& eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); +\& if (eckey == NULL) +\& /* error */ +\& if (EC_KEY_generate_key(eckey) == 0) +\& /* error */ +.Ve +.PP +Second step: compute the ECDSA signature of a SHA\-256 hash value +using \fBECDSA_do_sign()\fR: +.PP +.Vb 3 +\& sig = ECDSA_do_sign(digest, 32, eckey); +\& if (sig == NULL) +\& /* error */ +.Ve +.PP +or using \fBECDSA_sign()\fR: +.PP +.Vb 2 +\& unsigned char *buffer, *pp; +\& int buf_len; +\& +\& buf_len = ECDSA_size(eckey); +\& buffer = OPENSSL_malloc(buf_len); +\& pp = buffer; +\& if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) +\& /* error */ +.Ve +.PP +Third step: verify the created ECDSA signature using \fBECDSA_do_verify()\fR: +.PP +.Vb 1 +\& ret = ECDSA_do_verify(digest, 32, sig, eckey); +.Ve +.PP +or using \fBECDSA_verify()\fR: +.PP +.Vb 1 +\& ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey); +.Ve +.PP +and finally evaluate the return value: +.PP +.Vb 6 +\& if (ret == 1) +\& /* signature ok */ +\& else if (ret == 0) +\& /* incorrect signature */ +\& else +\& /* error */ +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ANSI X9.62, US Federal Information Processing Standard FIPS186\-2 +(Digital Signature Standard, DSS) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEC_KEY_new\fR\|(3), +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3) +\&\fBi2d_ECDSA_SIG\fR\|(3), +\&\fBd2i_ECDSA_SIG\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All functionality described here was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ECPKParameters_print.3 b/static/netbsd/man3/ECPKParameters_print.3 new file mode 100644 index 00000000..4021d49a --- /dev/null +++ b/static/netbsd/man3/ECPKParameters_print.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: ECPKParameters_print.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ECPKParameters_print 3" +.TH ECPKParameters_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ECPKParameters_print, ECPKParameters_print_fp \- Functions for decoding and +encoding ASN1 representations of elliptic curve entities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); +\& int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_print_params\fR\|(3) +.PP +The ECPKParameters represent the public parameters for an +\&\fBEC_GROUP\fR structure, which represents a curve. +.PP +The \fBECPKParameters_print()\fR and \fBECPKParameters_print_fp()\fR functions print +a human\-readable output of the public parameters of the EC_GROUP to \fBbp\fR +or \fBfp\fR. The output lines are indented by \fBoff\fR spaces. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBECPKParameters_print()\fR and \fBECPKParameters_print_fp()\fR +return 1 for success and 0 if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3), +\&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_GFp_simple_method.3 b/static/netbsd/man3/EC_GFp_simple_method.3 new file mode 100644 index 00000000..5eee4b10 --- /dev/null +++ b/static/netbsd/man3/EC_GFp_simple_method.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: EC_GFp_simple_method.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_GFp_simple_method 3" +.TH EC_GFp_simple_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type \- Functions for obtaining EC_METHOD objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 6 +\& const EC_METHOD *EC_GFp_simple_method(void); +\& const EC_METHOD *EC_GFp_mont_method(void); +\& const EC_METHOD *EC_GFp_nist_method(void); +\& const EC_METHOD *EC_GFp_nistp224_method(void); +\& const EC_METHOD *EC_GFp_nistp256_method(void); +\& const EC_METHOD *EC_GFp_nistp521_method(void); +\& +\& const EC_METHOD *EC_GF2m_simple_method(void); +\& +\& int EC_METHOD_get_field_type(const EC_METHOD *meth); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All const EC_METHOD *EC_GF* functions were deprecated in OpenSSL 3.0, since +EC_METHOD is no longer a public concept. +.PP +The Elliptic Curve library provides a number of different implementations through a single common interface. +When constructing a curve using EC_GROUP_new (see \fBEC_GROUP_new\fR\|(3)) an +implementation method must be provided. The functions described here all return a const pointer to an +\&\fBEC_METHOD\fR structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation +type for the form of curve selected is used. +.PP +For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. +.PP +For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All +other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the +use of montgomery multiplication (see \fBBN_mod_mul_montgomery\fR\|(3)). EC_GFp_nist_method +offers an implementation optimised for use with NIST recommended curves (NIST curves are available through +EC_GROUP_new_by_curve_name as described in \fBEC_GROUP_new\fR\|(3)). +.PP +The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit +optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these +implementations are not available on all platforms. +.PP +\&\fBEC_METHOD_get_field_type()\fR was deprecated in OpenSSL 3.0. +Applications should use \fBEC_GROUP_get_field_type()\fR as a replacement (see \fBEC_GROUP_copy\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. +.PP +EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3), +\&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBd2i_ECPKParameters\fR\|(3), +\&\fBBN_mod_mul_montgomery\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEC_GFp_simple_method()\fR, EC_GFp_mont_method(void), +\&\fBEC_GFp_nist_method()\fR, \fBEC_GFp_nistp224_method()\fR, +\&\fBEC_GFp_nistp256_method()\fR, \fBEC_GFp_nistp521_method()\fR, +\&\fBEC_GF2m_simple_method()\fR, and \fBEC_METHOD_get_field_type()\fR +were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_GROUP_copy.3 b/static/netbsd/man3/EC_GROUP_copy.3 new file mode 100644 index 00000000..ddb7c870 --- /dev/null +++ b/static/netbsd/man3/EC_GROUP_copy.3 @@ -0,0 +1,324 @@ +.\" $NetBSD: EC_GROUP_copy.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_GROUP_copy 3" +.TH EC_GROUP_copy 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, +EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, +EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, +EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, +EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, +EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, +EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, +EC_GROUP_check, EC_GROUP_check_named_curve, +EC_GROUP_check_discriminant, EC_GROUP_cmp, +EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, +EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field, +EC_GROUP_get_field_type +\&\- Functions for manipulating EC_GROUP objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); +\& EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); +\& +\& int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, +\& const BIGNUM *order, const BIGNUM *cofactor); +\& const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); +\& +\& int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); +\& const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group); +\& int EC_GROUP_order_bits(const EC_GROUP *group); +\& int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); +\& const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group); +\& const BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group); +\& +\& void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); +\& int EC_GROUP_get_curve_name(const EC_GROUP *group); +\& +\& void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); +\& int EC_GROUP_get_asn1_flag(const EC_GROUP *group); +\& +\& void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); +\& point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group); +\& +\& unsigned char *EC_GROUP_get0_seed(const EC_GROUP *group); +\& size_t EC_GROUP_get_seed_len(const EC_GROUP *group); +\& size_t EC_GROUP_set_seed(EC_GROUP *group, const unsigned char *, size_t len); +\& +\& int EC_GROUP_get_degree(const EC_GROUP *group); +\& +\& int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); +\& int EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only, +\& BN_CTX *ctx); +\& +\& int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); +\& +\& int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); +\& +\& int EC_GROUP_get_basis_type(const EC_GROUP *group); +\& int EC_GROUP_get_trinomial_basis(const EC_GROUP *group, unsigned int *k); +\& int EC_GROUP_get_pentanomial_basis(const EC_GROUP *group, unsigned int *k1, +\& unsigned int *k2, unsigned int *k3); +\& +\& int EC_GROUP_get_field_type(const EC_GROUP *group); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEC_GROUP_copy()\fR copies the curve \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR must use the same EC_METHOD. +.PP +\&\fBEC_GROUP_dup()\fR creates a new EC_GROUP object and copies the content from \fBsrc\fR to the newly created +EC_GROUP object. +.PP +\&\fBEC_GROUP_method_of()\fR obtains the EC_METHOD of \fBgroup\fR. +This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept. +.PP +\&\fBEC_GROUP_set_generator()\fR sets curve parameters that must be agreed by all participants using the curve. These +parameters include the \fBgenerator\fR, the \fBorder\fR and the \fBcofactor\fR. The \fBgenerator\fR is a well defined point on the +curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and +n\-1 where n is the \fBorder\fR. The \fBorder\fR multiplied by the \fBcofactor\fR gives the number of points on the curve. +.PP +\&\fBEC_GROUP_get0_generator()\fR returns the generator for the identified \fBgroup\fR. +.PP +\&\fBEC_GROUP_get_order()\fR retrieves the order of \fBgroup\fR and copies its value into +\&\fBorder\fR. It fails in case \fBgroup\fR is not fully initialized (i.e., its order +is not set or set to zero). +.PP +\&\fBEC_GROUP_get_cofactor()\fR retrieves the cofactor of \fBgroup\fR and copies its value +into \fBcofactor\fR. It fails in case \fBgroup\fR is not fully initialized or if the +cofactor is not set (or set to zero). +.PP +The functions \fBEC_GROUP_set_curve_name()\fR and \fBEC_GROUP_get_curve_name()\fR, set and get the NID for the curve respectively +(see \fBEC_GROUP_new\fR\|(3)). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name +will return NID_undef. +.PP +The asn1_flag value is used to determine whether the curve encoding uses +explicit parameters or a named curve using an ASN1 OID: many applications only +support the latter form. If asn1_flag is \fBOPENSSL_EC_NAMED_CURVE\fR then the +named curve form is used and the parameters must have a corresponding +named curve NID set. If asn1_flags is \fBOPENSSL_EC_EXPLICIT_CURVE\fR the +parameters are explicitly encoded. The functions \fBEC_GROUP_get_asn1_flag()\fR and +\&\fBEC_GROUP_set_asn1_flag()\fR get and set the status of the asn1_flag for the curve. +Note: \fBOPENSSL_EC_EXPLICIT_CURVE\fR was added in OpenSSL 1.1.0, for +previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL +1.1.0 the default form was to use explicit parameters (meaning that +applications would have to explicitly set the named curve form) in OpenSSL +1.1.0 and later the named curve form is the default. +.PP +The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). +point_conversion_form_t is an enum defined as follows: +.PP +.Vb 10 +\& typedef enum { +\& /** the point is encoded as z||x, where the octet z specifies +\& * which solution of the quadratic equation y is */ +\& POINT_CONVERSION_COMPRESSED = 2, +\& /** the point is encoded as z||x||y, where z is the octet 0x04 */ +\& POINT_CONVERSION_UNCOMPRESSED = 4, +\& /** the point is encoded as z||x||y, where the octet z specifies +\& * which solution of the quadratic equation y is */ +\& POINT_CONVERSION_HYBRID = 6 +\& } point_conversion_form_t; +.Ve +.PP +For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by +the octets for x, followed by the octets for y. +.PP +For any given x coordinate for a point on a curve it is possible to derive two possible y values. For +POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of +the two possible solutions for y has been used, followed by the octets for x. +.PP +For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two +possible solutions for y has been used, followed by the octets for x, followed by the octets for y. +.PP +The functions \fBEC_GROUP_set_point_conversion_form()\fR and \fBEC_GROUP_get_point_conversion_form()\fR, set and get the point_conversion_form +for the curve respectively. +.PP +ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages +in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. +If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library +does not use this seed value but does enable you to inspect it using \fBEC_GROUP_get0_seed()\fR. This returns a pointer to a memory block +containing the seed that was used. The length of the memory block can be obtained using \fBEC_GROUP_get_seed_len()\fR. A number of the +built\-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using +\&\fBEC_GROUP_set_seed()\fR and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use +this seed value, although it will be preserved in any ASN1 based communications. +.PP +\&\fBEC_GROUP_get_degree()\fR gets the degree of the field. +For Fp fields this will be the number of bits in p. +For F2^m fields this will be the value m. +.PP +\&\fBEC_GROUP_get_field_type()\fR identifies what type of field the EC_GROUP structure supports, +which will be either F2^m or Fp. +.PP +The function \fBEC_GROUP_check_discriminant()\fR calculates the discriminant for the curve and verifies that it is valid. +For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is +simply b. In either case for the curve to be valid the discriminant must be non zero. +.PP +The function \fBEC_GROUP_check()\fR behaves in the following way: +For the OpenSSL default provider it performs a number of checks on a curve to verify that it is valid. Checks performed include +verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has +the correct order. For the OpenSSL FIPS provider it uses \fBEC_GROUP_check_named_curve()\fR to conform to SP800\-56Ar3. +.PP +The function \fBEC_GROUP_check_named_curve()\fR determines if the group\*(Aqs domain parameters match one of the built\-in curves supported by the library. +The curve name is returned as a \fBNID\fR if it matches. If the group\*(Aqs domain parameters have been modified then no match will be found. +If the curve name of the given group is \fBNID_undef\fR (e.g. it has been created by using explicit parameters with no curve name), +then this method can be used to lookup the name of the curve that matches the group domain parameters. The built\-in curves contain +aliases, so that multiple NID\*(Aqs can map to the same domain parameters. For such curves it is unspecified which of the aliases will be +returned if the curve name of the given group is NID_undef. +If \fBnist_only\fR is 1 it will only look for NIST approved curves, otherwise it searches all built\-in curves. +This function may be passed a BN_CTX object in the \fBctx\fR parameter. +The \fBctx\fR parameter may be NULL. +.PP +\&\fBEC_GROUP_cmp()\fR compares \fBa\fR and \fBb\fR to determine whether they represent the same curve or not. +.PP +The functions \fBEC_GROUP_get_basis_type()\fR, \fBEC_GROUP_get_trinomial_basis()\fR and \fBEC_GROUP_get_pentanomial_basis()\fR should only be called for curves +defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial +function f(x). This function is either a trinomial of the form: +.PP +f(x) = x^m + x^k + 1 with m > k >= 1 +.PP +or a pentanomial of the form: +.PP +f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 +.PP +The function \fBEC_GROUP_get_basis_type()\fR returns a NID identifying whether a trinomial or pentanomial is in use for the field. The +function \fBEC_GROUP_get_trinomial_basis()\fR must only be called where f(x) is of the trinomial form, and returns the value of \fBk\fR. Similarly +the function \fBEC_GROUP_get_pentanomial_basis()\fR must only be called where f(x) is of the pentanomial form, and returns the values of \fBk1\fR, +\&\fBk2\fR and \fBk3\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following functions return 1 on success or 0 on error: \fBEC_GROUP_copy()\fR, \fBEC_GROUP_set_generator()\fR, \fBEC_GROUP_check()\fR, +\&\fBEC_GROUP_check_discriminant()\fR, \fBEC_GROUP_get_trinomial_basis()\fR and \fBEC_GROUP_get_pentanomial_basis()\fR. +.PP +\&\fBEC_GROUP_dup()\fR returns a pointer to the duplicated curve, or NULL on error. +.PP +\&\fBEC_GROUP_method_of()\fR returns the EC_METHOD implementation in use for the given curve or NULL on error. +.PP +\&\fBEC_GROUP_get0_generator()\fR returns the generator for the given curve or NULL on error. +.PP +\&\fBEC_GROUP_get_order()\fR returns 0 if the order is not set (or set to zero) for +\&\fBgroup\fR or if copying into \fBorder\fR fails, 1 otherwise. +.PP +\&\fBEC_GROUP_get_cofactor()\fR returns 0 if the cofactor is not set (or is set to zero) for \fBgroup\fR or if copying into \fBcofactor\fR fails, 1 otherwise. +.PP +\&\fBEC_GROUP_get_curve_name()\fR returns the curve name (NID) for \fBgroup\fR or will return NID_undef if no curve name is associated. +.PP +\&\fBEC_GROUP_get_asn1_flag()\fR returns the ASN1 flag for the specified \fBgroup\fR . +.PP +\&\fBEC_GROUP_get_point_conversion_form()\fR returns the point_conversion_form for \fBgroup\fR. +.PP +\&\fBEC_GROUP_get_degree()\fR returns the degree for \fBgroup\fR or 0 if the operation is not supported by the underlying group implementation. +.PP +\&\fBEC_GROUP_get_field_type()\fR returns either \fBNID_X9_62_prime_field\fR for prime curves +or \fBNID_X9_62_characteristic_two_field\fR for binary curves; +these values are defined in the \fI\fR header file. +.PP +\&\fBEC_GROUP_check_named_curve()\fR returns the nid of the matching named curve, otherwise it returns 0 for no match, or \-1 on error. +.PP +\&\fBEC_GROUP_get0_order()\fR returns an internal pointer to the group order. +\&\fBEC_GROUP_order_bits()\fR returns the number of bits in the group order. +\&\fBEC_GROUP_get0_cofactor()\fR returns an internal pointer to the group cofactor. +\&\fBEC_GROUP_get0_field()\fR returns an internal pointer to the group field. For curves over GF(p), this is the modulus; for curves +over GF(2^m), this is the irreducible polynomial defining the field. +.PP +\&\fBEC_GROUP_get0_seed()\fR returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not +specified. \fBEC_GROUP_get_seed_len()\fR returns the length of the seed or 0 if the seed is not specified. +.PP +\&\fBEC_GROUP_set_seed()\fR returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is +0, the return value will be 1. On error 0 is returned. +.PP +\&\fBEC_GROUP_cmp()\fR returns 0 if the curves are equal, 1 if they are not equal, or \-1 on error. +.PP +\&\fBEC_GROUP_get_basis_type()\fR returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in \fI\fR) for a +trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), +\&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEC_GROUP_method_of()\fR was deprecated in OpenSSL 3.0. +\&\fBEC_GROUP_get0_field()\fR, \fBEC_GROUP_check_named_curve()\fR and \fBEC_GROUP_get_field_type()\fR were added in OpenSSL 3.0. +\&\fBEC_GROUP_get0_order()\fR, \fBEC_GROUP_order_bits()\fR and \fBEC_GROUP_get0_cofactor()\fR were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_GROUP_new.3 b/static/netbsd/man3/EC_GROUP_new.3 new file mode 100644 index 00000000..0b223840 --- /dev/null +++ b/static/netbsd/man3/EC_GROUP_new.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: EC_GROUP_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_GROUP_new 3" +.TH EC_GROUP_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_GROUP_get_ecparameters, +EC_GROUP_get_ecpkparameters, +EC_GROUP_new_from_params, +EC_GROUP_to_params, +EC_GROUP_new_from_ecparameters, +EC_GROUP_new_from_ecpkparameters, +EC_GROUP_new, +EC_GROUP_free, +EC_GROUP_clear_free, +EC_GROUP_new_curve_GFp, +EC_GROUP_new_curve_GF2m, +EC_GROUP_new_by_curve_name_ex, +EC_GROUP_new_by_curve_name, +EC_GROUP_set_curve, +EC_GROUP_get_curve, +EC_GROUP_set_curve_GFp, +EC_GROUP_get_curve_GFp, +EC_GROUP_set_curve_GF2m, +EC_GROUP_get_curve_GF2m, +EC_get_builtin_curves, +OSSL_EC_curve_nid2name \- +Functions for creating and destroying EC_GROUP objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[], +\& OSSL_LIB_CTX *libctx, const char *propq); +\& OSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx, +\& const char *propq, BN_CTX *bnctx); +\& EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params); +\& EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params); +\& void EC_GROUP_free(EC_GROUP *group); +\& +\& EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, +\& const BIGNUM *b, BN_CTX *ctx); +\& EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, +\& const BIGNUM *b, BN_CTX *ctx); +\& EC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq, +\& int nid); +\& EC_GROUP *EC_GROUP_new_by_curve_name(int nid); +\& +\& int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, +\& const BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, +\& BN_CTX *ctx); +\& +\& ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, +\& ECPARAMETERS *params); +\& ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, +\& ECPKPARAMETERS *params); +\& +\& size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); +\& const char *OSSL_EC_curve_nid2name(int nid); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); +\& void EC_GROUP_clear_free(EC_GROUP *group); +\& +\& int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, +\& const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, +\& BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, +\& const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, +\& BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Within the library there are two forms of elliptic curve that are of interest. +The first form is those defined over the prime field Fp. The elements of Fp are +the integers 0 to p\-1, where p is a prime number. This gives us a revised +elliptic curve equation as follows: +.PP +y^2 mod p = x^3 +ax + b mod p +.PP +The second form is those defined over a binary field F2^m where the elements of +the field are integers of length at most m bits. For this form the elliptic +curve equation is modified to: +.PP +y^2 + xy = x^3 + ax^2 + b (where b != 0) +.PP +Operations in a binary field are performed relative to an +\&\fBirreducible polynomial\fR. All such curves with OpenSSL use a trinomial or a +pentanomial for this parameter. +.PP +Although deprecated since OpenSSL 3.0 and should no longer be used, +a new curve can be constructed by calling \fBEC_GROUP_new()\fR, using the +implementation provided by \fImeth\fR (see \fBEC_GFp_simple_method\fR\|(3)) and +associated with the library context \fIctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)). +The \fIctx\fR parameter may be NULL in which case the default library context is +used. +It is then necessary to call \fBEC_GROUP_set_curve()\fR to set the curve parameters. +Applications should instead use one of the other EC_GROUP_new_* constructors. +.PP +\&\fBEC_GROUP_new_from_params()\fR creates a group with parameters specified by \fIparams\fR. +The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and property query string +\&\fIpropq\fR are used to fetch algorithms from providers. +\&\fIparams\fR may be either a list of explicit params or a named group, +The values for \fIctx\fR and \fIpropq\fR may be NULL. +The \fIparams\fR that can be used are described in +\&\fBEVP_PKEY\-EC\fR(7). +.PP +EC_GROUP_to_params creates an OSSL_PARAM array with the corresponding parameters +describing the given EC_GROUP. The resulting parameters may contain parameters +describing a named or explicit curve depending on the EC_GROUP. +The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and property query string +\&\fIpropq\fR are used to fetch algorithms from providers. +\&\fIbnctx\fR is an optional preallocated BN_CTX (to save the overhead of allocating +and freeing the structure in a loop). +The values for \fIlibctx\fR, \fIpropq\fR and \fIbnctx\fR may be NULL. +The caller is responsible for freeing the OSSL_PARAM pointer returned. +.PP +\&\fBEC_GROUP_new_from_ecparameters()\fR will create a group from the +specified \fIparams\fR and +\&\fBEC_GROUP_new_from_ecpkparameters()\fR will create a group from the specific PK +\&\fIparams\fR. +.PP +\&\fBEC_GROUP_set_curve()\fR sets the curve parameters \fIp\fR, \fIa\fR and \fIb\fR. For a curve +over Fp \fIp\fR is the prime for the field. For a curve over F2^m \fIp\fR represents +the irreducible polynomial \- each bit represents a term in the polynomial. +Therefore, there will either be three or five bits set dependent on whether the +polynomial is a trinomial or a pentanomial. +In either case, \fIa\fR and \fIb\fR represents the coefficients a and b from the +relevant equation introduced above. +.PP +\&\fBEC_group_get_curve()\fR obtains the previously set curve parameters. +.PP +\&\fBEC_GROUP_set_curve_GFp()\fR and \fBEC_GROUP_set_curve_GF2m()\fR are synonyms for +\&\fBEC_GROUP_set_curve()\fR. They are defined for backwards compatibility only and +should not be used. +.PP +\&\fBEC_GROUP_get_curve_GFp()\fR and \fBEC_GROUP_get_curve_GF2m()\fR are synonyms for +\&\fBEC_GROUP_get_curve()\fR. They are defined for backwards compatibility only and +should not be used. +.PP +The functions \fBEC_GROUP_new_curve_GFp()\fR and \fBEC_GROUP_new_curve_GF2m()\fR are +shortcuts for calling \fBEC_GROUP_new()\fR and then the \fBEC_GROUP_set_curve()\fR function. +An appropriate default implementation method will be used. +.PP +Whilst the library can be used to create any curve using the functions described +above, there are also a number of predefined curves that are available. In order +to obtain a list of all of the predefined curves, call the function +\&\fBEC_get_builtin_curves()\fR. The parameter \fIr\fR should be an array of +EC_builtin_curve structures of size \fInitems\fR. The function will populate the +\&\fIr\fR array with information about the built\-in curves. If \fInitems\fR is less than +the total number of curves available, then the first \fInitems\fR curves will be +returned. Otherwise the total number of curves will be provided. The return +value is the total number of curves available (whether that number has been +populated in \fIr\fR or not). Passing a NULL \fIr\fR, or setting \fInitems\fR to 0 will +do nothing other than return the total number of curves available. +The EC_builtin_curve structure is defined as follows: +.PP +.Vb 4 +\& typedef struct { +\& int nid; +\& const char *comment; +\& } EC_builtin_curve; +.Ve +.PP +Each EC_builtin_curve item has a unique integer id (\fInid\fR), and a human +readable comment string describing the curve. +.PP +In order to construct a built\-in curve use the function +\&\fBEC_GROUP_new_by_curve_name_ex()\fR and provide the \fInid\fR of the curve to +be constructed, the associated library context to be used in \fIctx\fR (see +\&\fBOSSL_LIB_CTX\fR\|(3)) and any property query string in \fIpropq\fR. The \fIctx\fR value +may be NULL in which case the default library context is used. The \fIpropq\fR +value may also be NULL. +.PP +\&\fBEC_GROUP_new_by_curve_name()\fR is the same as +\&\fBEC_GROUP_new_by_curve_name_ex()\fR except that the default library context +is always used along with a NULL property query string. +.PP +\&\fBEC_GROUP_free()\fR frees the memory associated with the EC_GROUP. +If \fIgroup\fR is NULL nothing is done. +.PP +\&\fBEC_GROUP_clear_free()\fR is deprecated: it was meant to destroy any sensitive data +held within the EC_GROUP and then free its memory, but since all the data stored +in the EC_GROUP is public anyway, this function is unnecessary. +Its use can be safely replaced with \fBEC_GROUP_free()\fR. +If \fIgroup\fR is NULL nothing is done. +.PP +\&\fBOSSL_EC_curve_nid2name()\fR converts a curve \fInid\fR into the corresponding name. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All EC_GROUP_new* functions return a pointer to the newly constructed group, or +NULL on error. +.PP +\&\fBEC_get_builtin_curves()\fR returns the number of built\-in curves that are +available. +.PP +\&\fBEC_GROUP_set_curve_GFp()\fR, \fBEC_GROUP_get_curve_GFp()\fR, \fBEC_GROUP_set_curve_GF2m()\fR, +\&\fBEC_GROUP_get_curve_GF2m()\fR return 1 on success or 0 on error. +.PP +\&\fBOSSL_EC_curve_nid2name()\fR returns a character string constant, or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_copy\fR\|(3), +\&\fBEC_POINT_new\fR\|(3), \fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3), +\&\fBOSSL_LIB_CTX\fR\|(3), \fBEVP_PKEY\-EC\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEC_GROUP_to_params()\fR was added in OpenSSL 3.2. +.IP \(bu 2 +\&\fBEC_GROUP_new()\fR was deprecated in OpenSSL 3.0. +.Sp +\&\fBEC_GROUP_new_by_curve_name_ex()\fR and \fBEC_GROUP_new_from_params()\fR were +added in OpenSSL 3.0. +.IP \(bu 2 +\&\fBEC_GROUP_clear_free()\fR was deprecated in OpenSSL 3.0; use \fBEC_GROUP_free()\fR +instead. +.IP \(bu 2 + +.Sp +.Vb 3 +\& EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), +\& EC_GROUP_set_curve_GF2m() and EC_GROUP_get_curve_GF2m() were deprecated in +\& OpenSSL 3.0; use EC_GROUP_set_curve() and EC_GROUP_get_curve() instead. +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_KEY_get_enc_flags.3 b/static/netbsd/man3/EC_KEY_get_enc_flags.3 new file mode 100644 index 00000000..76e8245c --- /dev/null +++ b/static/netbsd/man3/EC_KEY_get_enc_flags.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: EC_KEY_get_enc_flags.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_KEY_get_enc_flags 3" +.TH EC_KEY_get_enc_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_KEY_get_enc_flags, EC_KEY_set_enc_flags +\&\- Get and set flags for encoding EC_KEY structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); +\& void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The format of the external representation of the public key written by +\&\fBi2d_ECPrivateKey()\fR (such as whether it is stored in a compressed form or not) is +described by the point_conversion_form. See \fBEC_GROUP_copy\fR\|(3) +for a description of point_conversion_form. +.PP +When reading a private key encoded without an associated public key (e.g. if +EC_PKEY_NO_PUBKEY has been used \- see below), then \fBd2i_ECPrivateKey()\fR generates +the missing public key automatically. Private keys encoded without parameters +(e.g. if EC_PKEY_NO_PARAMETERS has been used \- see below) cannot be loaded using +\&\fBd2i_ECPrivateKey()\fR. +.PP +The functions \fBEC_KEY_get_enc_flags()\fR and \fBEC_KEY_set_enc_flags()\fR get and set the +value of the encoding flags for the \fBkey\fR. There are two encoding flags +currently defined \- EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags +define the behaviour of how the \fBkey\fR is converted into ASN1 in a call to +\&\fBi2d_ECPrivateKey()\fR. If EC_PKEY_NO_PARAMETERS is set then the public parameters for +the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is +set then the public key is not encoded along with the private key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEC_KEY_get_enc_flags()\fR returns the value of the current encoding flags for the +EC_KEY. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), +\&\fBEC_GROUP_copy\fR\|(3), \fBEC_POINT_new\fR\|(3), +\&\fBEC_POINT_add\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), +\&\fBd2i_ECPKParameters\fR\|(3), +\&\fBd2i_ECPrivateKey\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_KEY_new.3 b/static/netbsd/man3/EC_KEY_new.3 new file mode 100644 index 00000000..1d88ea6c --- /dev/null +++ b/static/netbsd/man3/EC_KEY_new.3 @@ -0,0 +1,305 @@ +.\" $NetBSD: EC_KEY_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_KEY_new 3" +.TH EC_KEY_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_EC_gen, +EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex, +EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, +EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, +EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine, +EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, +EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, +EC_KEY_get_conv_form, +EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, +EC_KEY_decoded_from_explicit_params, EC_KEY_precompute_mult, +EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, +EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, +EC_KEY_priv2buf \- Functions for creating, destroying and manipulating +EC_KEY objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *EVP_EC_gen(const char *curve); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& EC_KEY *EC_KEY_new_ex(OSSL_LIB_CTX *ctx, const char *propq); +\& EC_KEY *EC_KEY_new(void); +\& int EC_KEY_get_flags(const EC_KEY *key); +\& void EC_KEY_set_flags(EC_KEY *key, int flags); +\& void EC_KEY_clear_flags(EC_KEY *key, int flags); +\& EC_KEY *EC_KEY_new_by_curve_name_ex(OSSL_LIB_CTX *ctx, const char *propq, +\& int nid); +\& EC_KEY *EC_KEY_new_by_curve_name(int nid); +\& void EC_KEY_free(EC_KEY *key); +\& EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); +\& EC_KEY *EC_KEY_dup(const EC_KEY *src); +\& int EC_KEY_up_ref(EC_KEY *key); +\& ENGINE *EC_KEY_get0_engine(const EC_KEY *eckey); +\& const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); +\& int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); +\& const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); +\& int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv_key); +\& const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); +\& int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); +\& point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); +\& void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); +\& void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); +\& int EC_KEY_decoded_from_explicit_params(const EC_KEY *key); +\& int EC_KEY_generate_key(EC_KEY *key); +\& int EC_KEY_check_key(const EC_KEY *key); +\& int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); +\& const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key); +\& int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth); +\& +\& int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, BN_CTX *ctx); +\& size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form, +\& unsigned char **pbuf, BN_CTX *ctx); +\& +\& int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len); +\& size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len); +\& +\& size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf); +\& int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_EC_gen()\fR generates a new EC key pair on the given \fIcurve\fR. +.PP +All of the functions described below are deprecated. +Applications should instead use \fBEVP_EC_gen()\fR, \fBEVP_PKEY_Q_keygen\fR\|(3), or +\&\fBEVP_PKEY_keygen_init\fR\|(3) and \fBEVP_PKEY_keygen\fR\|(3). +.PP +An EC_KEY represents a public key and, optionally, the associated private +key. +A new EC_KEY with no associated curve can be constructed by calling +\&\fBEC_KEY_new_ex()\fR and specifying the associated library context in \fIctx\fR +(see \fBOSSL_LIB_CTX\fR\|(3)) and property query string \fIpropq\fR. +The \fIctx\fR parameter may be NULL in which case the default library context is +used. +The reference count for the newly created EC_KEY is initially +set to 1. +A curve can be associated with the EC_KEY by calling +\&\fBEC_KEY_set_group()\fR. +.PP +\&\fBEC_KEY_new()\fR is the same as \fBEC_KEY_new_ex()\fR except that the default library +context is always used. +.PP +Alternatively a new EC_KEY can be constructed by calling +\&\fBEC_KEY_new_by_curve_name_ex()\fR and supplying the nid of the associated +curve, the library context to be used \fIctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and any +property query string \fIpropq\fR. +The \fIctx\fR parameter may be NULL in which case the default library context is +used. The \fIpropq\fR value may also be NULL. +See \fBEC_GROUP_new\fR\|(3) for a description of curve names. +This function simply wraps calls to \fBEC_KEY_new_ex()\fR and +\&\fBEC_GROUP_new_by_curve_name_ex()\fR. +.PP +\&\fBEC_KEY_new_by_curve_name()\fR is the same as \fBEC_KEY_new_by_curve_name_ex()\fR +except that the default library context is always used and a NULL property query +string. +.PP +Calling \fBEC_KEY_free()\fR decrements the reference count for the EC_KEY object, +and if it has dropped to zero then frees the memory associated with it. If +\&\fIkey\fR is NULL nothing is done. +.PP +\&\fBEC_KEY_copy()\fR copies the contents of the EC_KEY in \fIsrc\fR into \fIdest\fR. +.PP +\&\fBEC_KEY_dup()\fR creates a new EC_KEY object and copies \fIec_key\fR into it. +.PP +\&\fBEC_KEY_up_ref()\fR increments the reference count associated with the EC_KEY +object. +.PP +\&\fBEC_KEY_get0_engine()\fR returns a handle to the ENGINE that has been set for +this EC_KEY object. +.PP +\&\fBEC_KEY_generate_key()\fR generates a new public and private key for the supplied +\&\fIeckey\fR object. \fIeckey\fR must have an EC_GROUP object associated with it +before calling this function. The private key is a random integer (0 < priv_key +< order, where \fIorder\fR is the order of the EC_GROUP object). The public key is +an EC_POINT on the curve calculated by multiplying the generator for the +curve by the private key. +.PP +\&\fBEC_KEY_check_key()\fR performs various sanity checks on the EC_KEY object to +confirm that it is valid. +.PP +\&\fBEC_KEY_set_public_key_affine_coordinates()\fR sets the public key for \fIkey\fR based +on its affine coordinates; i.e., it constructs an EC_POINT object based on +the supplied \fIx\fR and \fIy\fR values and sets the public key to be this +EC_POINT. It also performs certain sanity checks on the key to confirm +that it is valid. +.PP +The functions \fBEC_KEY_get0_group()\fR, \fBEC_KEY_set_group()\fR, +\&\fBEC_KEY_get0_private_key()\fR, \fBEC_KEY_set_private_key()\fR, \fBEC_KEY_get0_public_key()\fR, +and \fBEC_KEY_set_public_key()\fR get and set the EC_GROUP object, the private key, +and the EC_POINT public key for the \fBkey\fR respectively. The function +\&\fBEC_KEY_set_private_key()\fR accepts NULL as the priv_key argument to securely clear +the private key component from the EC_KEY. +.PP +The functions \fBEC_KEY_get_conv_form()\fR and \fBEC_KEY_set_conv_form()\fR get and set the +point_conversion_form for the \fIkey\fR. For a description of +point_conversion_forms please see \fBEC_POINT_new\fR\|(3). +.PP +\&\fBEC_KEY_set_flags()\fR sets the flags in the \fIflags\fR parameter on the EC_KEY +object. Any flags that are already set are left set. The flags currently +defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In +addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH. +\&\fBEC_KEY_get_flags()\fR returns the current flags that are set for this EC_KEY. +\&\fBEC_KEY_clear_flags()\fR clears the flags indicated by the \fIflags\fR parameter; all +other flags are left in their existing state. +.PP +\&\fBEC_KEY_set_asn1_flag()\fR sets the asn1_flag on the underlying EC_GROUP object +(if set). Refer to \fBEC_GROUP_copy\fR\|(3) for further information on the +asn1_flag. +.PP +\&\fBEC_KEY_decoded_from_explicit_params()\fR returns 1 if the group of the \fIkey\fR was +decoded from data with explicitly encoded group parameters, \-1 if the \fIkey\fR +is NULL or the group parameters are missing, and 0 otherwise. +.PP +\&\fBEC_KEY_precompute_mult()\fR stores multiples of the underlying EC_GROUP generator +for faster point multiplication. See also \fBEC_POINT_add\fR\|(3). +Modern versions should instead switch to named curves which OpenSSL has +hardcoded lookup tables for. +.PP +\&\fBEC_KEY_oct2key()\fR and \fBEC_KEY_key2buf()\fR are identical to the functions +\&\fBEC_POINT_oct2point()\fR and \fBEC_POINT_point2buf()\fR except they use the public key +EC_POINT in \fIeckey\fR. +.PP +\&\fBEC_KEY_oct2priv()\fR and \fBEC_KEY_priv2oct()\fR convert between the private key +component of \fIeckey\fR and octet form. The octet form consists of the content +octets of the \fIprivateKey\fR OCTET STRING in an \fIECPrivateKey\fR ASN.1 structure. +.PP +The function \fBEC_KEY_priv2oct()\fR must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will just return the required buffer length. +.PP +The function \fBEC_KEY_priv2buf()\fR allocates a buffer of suitable length and writes +an EC_KEY to it in octet format. The allocated buffer is written to \fI*pbuf\fR +and its length is returned. The caller must free up the allocated buffer with a +call to \fBOPENSSL_free()\fR. Since the allocated buffer value is written to \fI*pbuf\fR +the \fIpbuf\fR parameter \fBMUST NOT\fR be \fBNULL\fR. +.PP +\&\fBEC_KEY_priv2buf()\fR converts an EC_KEY private key into an allocated buffer. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEC_KEY_new_ex()\fR, \fBEC_KEY_new()\fR, \fBEC_KEY_new_by_curve_name_ex()\fR, +\&\fBEC_KEY_new_by_curve_name()\fR and \fBEC_KEY_dup()\fR return a pointer to the newly +created EC_KEY object, or NULL on error. +.PP +\&\fBEC_KEY_get_flags()\fR returns the flags associated with the EC_KEY object as an +integer. +.PP +\&\fBEC_KEY_copy()\fR returns a pointer to the destination key, or NULL on error. +.PP +\&\fBEC_KEY_get0_engine()\fR returns a pointer to an ENGINE, or NULL if it wasn\*(Aqt set. +.PP +\&\fBEC_KEY_up_ref()\fR, \fBEC_KEY_set_group()\fR, \fBEC_KEY_set_public_key()\fR, +\&\fBEC_KEY_precompute_mult()\fR, \fBEC_KEY_generate_key()\fR, \fBEC_KEY_check_key()\fR, +\&\fBEC_KEY_set_public_key_affine_coordinates()\fR, \fBEC_KEY_oct2key()\fR and +\&\fBEC_KEY_oct2priv()\fR return 1 on success or 0 on error. +.PP +\&\fBEC_KEY_set_private_key()\fR returns 1 on success or 0 on error except when the +priv_key argument is NULL, in that case it returns 0, for legacy compatibility, +and should not be treated as an error. +.PP +\&\fBEC_KEY_get0_group()\fR returns the EC_GROUP associated with the EC_KEY. +.PP +\&\fBEC_KEY_get0_private_key()\fR returns the private key associated with the EC_KEY. +.PP +\&\fBEC_KEY_get_conv_form()\fR return the point_conversion_form for the EC_KEY. +.PP +\&\fBEC_KEY_key2buf()\fR, \fBEC_KEY_priv2oct()\fR and \fBEC_KEY_priv2buf()\fR return the length +of the buffer or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_Q_keygen\fR\|(3) +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), +\&\fBEC_GROUP_copy\fR\|(3), \fBEC_POINT_new\fR\|(3), +\&\fBEC_POINT_add\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), +\&\fBd2i_ECPKParameters\fR\|(3), +\&\fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_EC_gen()\fR was added in OpenSSL 3.0. +All other functions described here were deprecated in OpenSSL 3.0. +For replacement see \fBEVP_PKEY\-EC\fR\|(7). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_POINT_add.3 b/static/netbsd/man3/EC_POINT_add.3 new file mode 100644 index 00000000..36b5ce5a --- /dev/null +++ b/static/netbsd/man3/EC_POINT_add.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: EC_POINT_add.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_POINT_add 3" +.TH EC_POINT_add 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult \- Functions for performing mathematical operations and tests on EC_POINT objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, +\& const EC_POINT *b, BN_CTX *ctx); +\& int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); +\& int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); +\& int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); +\& int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); +\& int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); +\& int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, +\& const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 7 +\& int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); +\& int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, +\& EC_POINT *points[], BN_CTX *ctx); +\& int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, +\& const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); +\& int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); +\& int EC_GROUP_have_precompute_mult(const EC_GROUP *group); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +EC_POINT_add adds the two points \fBa\fR and \fBb\fR and places the result in \fBr\fR. Similarly EC_POINT_dbl doubles the point \fBa\fR and places the +result in \fBr\fR. In both cases it is valid for \fBr\fR to be one of \fBa\fR or \fBb\fR. +.PP +EC_POINT_invert calculates the inverse of the supplied point \fBa\fR. The result is placed back in \fBa\fR. +.PP +The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. +.PP +EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. +.PP +EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. +.PP +The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine +coordinate system. In the case of EC_POINTs_make_affine the value \fBnum\fR provides the number of points in the array \fBpoints\fR to be +forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used. +Modern versions automatically perform this conversion when needed. +.PP +EC_POINT_mul calculates the value generator * \fBn\fR + \fBq\fR * \fBm\fR and stores the result in \fBr\fR. +The value \fBn\fR may be NULL in which case the result is just \fBq\fR * \fBm\fR (variable point multiplication). Alternatively, both \fBq\fR and \fBm\fR may be NULL, and \fBn\fR non\-NULL, in which case the result is just generator * \fBn\fR (fixed point multiplication). +When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either \fBn\fR or \fBm\fR) is in the range [0, ec_group_order). +.PP +Although deprecated in OpenSSL 3.0 and should no longer be used, +EC_POINTs_mul calculates the value generator * \fBn\fR + \fBq[0]\fR * \fBm[0]\fR + ... + \fBq[num\-1]\fR * \fBm[num\-1]\fR. As for EC_POINT_mul the value \fBn\fR may be NULL or \fBnum\fR may be zero. +When performing a fixed point multiplication (\fBn\fR is non\-NULL and \fBnum\fR is 0) or a variable point multiplication (\fBn\fR is NULL and \fBnum\fR is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either \fBn\fR or \fBm[0]\fR) is in the range [0, ec_group_order). +Modern versions should instead use \fBEC_POINT_mul()\fR, combined (if needed) with \fBEC_POINT_add()\fR in such rare circumstances. +.PP +The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst +EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See \fBEC_GROUP_copy\fR\|(3) for information +about the generator. Precomputation functionality was deprecated in OpenSSL 3.0. +Users of \fBEC_GROUP_precompute_mult()\fR and \fBEC_GROUP_have_precompute_mult()\fR should +switch to named curves which OpenSSL has hardcoded lookup tables for. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, +EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. +.PP +EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. +.PP +EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or \-1 on error. +.PP +EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or \-1 on error. +.PP +EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3), +\&\fBEC_POINT_new\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEC_POINT_make_affine()\fR, \fBEC_POINTs_make_affine()\fR, \fBEC_POINTs_mul()\fR, +\&\fBEC_GROUP_precompute_mult()\fR, and \fBEC_GROUP_have_precompute_mult()\fR +were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EC_POINT_new.3 b/static/netbsd/man3/EC_POINT_new.3 new file mode 100644 index 00000000..0edf402f --- /dev/null +++ b/static/netbsd/man3/EC_POINT_new.3 @@ -0,0 +1,338 @@ +.\" $NetBSD: EC_POINT_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EC_POINT_new 3" +.TH EC_POINT_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EC_POINT_set_Jprojective_coordinates_GFp, +EC_POINT_point2buf, +EC_POINT_new, +EC_POINT_free, +EC_POINT_clear_free, +EC_POINT_copy, +EC_POINT_dup, +EC_POINT_method_of, +EC_POINT_set_to_infinity, +EC_POINT_get_Jprojective_coordinates_GFp, +EC_POINT_set_affine_coordinates, +EC_POINT_get_affine_coordinates, +EC_POINT_set_compressed_coordinates, +EC_POINT_set_affine_coordinates_GFp, +EC_POINT_get_affine_coordinates_GFp, +EC_POINT_set_compressed_coordinates_GFp, +EC_POINT_set_affine_coordinates_GF2m, +EC_POINT_get_affine_coordinates_GF2m, +EC_POINT_set_compressed_coordinates_GF2m, +EC_POINT_point2oct, +EC_POINT_oct2point, +EC_POINT_point2bn, +EC_POINT_bn2point, +EC_POINT_point2hex, +EC_POINT_hex2point +\&\- Functions for creating, destroying and manipulating EC_POINT objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EC_POINT *EC_POINT_new(const EC_GROUP *group); +\& void EC_POINT_free(EC_POINT *point); +\& void EC_POINT_clear_free(EC_POINT *point); +\& int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); +\& EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); +\& int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); +\& int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, +\& BN_CTX *ctx); +\& int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, int y_bit, +\& BN_CTX *ctx); +\& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, +\& unsigned char *buf, size_t len, BN_CTX *ctx); +\& size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, +\& point_conversion_form_t form, +\& unsigned char **pbuf, BN_CTX *ctx); +\& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, +\& const unsigned char *buf, size_t len, BN_CTX *ctx); +\& char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, BN_CTX *ctx); +\& EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, +\& EC_POINT *p, BN_CTX *ctx); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); +\& int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, +\& EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, +\& const BIGNUM *z, BN_CTX *ctx); +\& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BIGNUM *z, +\& BN_CTX *ctx); +\& int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, +\& BN_CTX *ctx); +\& int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, +\& EC_POINT *p, +\& const BIGNUM *x, int y_bit, +\& BN_CTX *ctx); +\& int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, +\& BN_CTX *ctx); +\& int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, +\& EC_POINT *p, +\& const BIGNUM *x, int y_bit, +\& BN_CTX *ctx); +\& BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, BIGNUM *bn, +\& BN_CTX *ctx); +\& EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, +\& EC_POINT *p, BN_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +An \fBEC_POINT\fR structure represents a point on a curve. A new point is +constructed by calling the function \fBEC_POINT_new()\fR and providing the +\&\fBgroup\fR object that the point relates to. +.PP +\&\fBEC_POINT_free()\fR frees the memory associated with the \fBEC_POINT\fR. +if \fBpoint\fR is NULL nothing is done. +.PP +\&\fBEC_POINT_clear_free()\fR destroys any sensitive data held within the EC_POINT and +then frees its memory. If \fBpoint\fR is NULL nothing is done. +.PP +\&\fBEC_POINT_copy()\fR copies the point \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR +must use the same \fBEC_METHOD\fR. +.PP +\&\fBEC_POINT_dup()\fR creates a new \fBEC_POINT\fR object and copies the content from +\&\fBsrc\fR to the newly created \fBEC_POINT\fR object. +.PP +\&\fBEC_POINT_method_of()\fR obtains the \fBEC_METHOD\fR associated with \fBpoint\fR. +This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a +public concept. +.PP +A valid point on a curve is the special point at infinity. A point is set to +be at infinity by calling \fBEC_POINT_set_to_infinity()\fR. +.PP +The affine coordinates for a point describe a point in terms of its x and y +position. The function \fBEC_POINT_set_affine_coordinates()\fR sets the \fBx\fR and \fBy\fR +coordinates for the point \fBp\fR defined over the curve given in \fBgroup\fR. The +function \fBEC_POINT_get_affine_coordinates()\fR sets \fBx\fR and \fBy\fR, either of which +may be NULL, to the corresponding coordinates of \fBp\fR. +.PP +The functions \fBEC_POINT_set_affine_coordinates_GFp()\fR and +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR are synonyms for +\&\fBEC_POINT_set_affine_coordinates()\fR. They are defined for backwards compatibility +only and should not be used. +.PP +The functions \fBEC_POINT_get_affine_coordinates_GFp()\fR and +\&\fBEC_POINT_get_affine_coordinates_GF2m()\fR are synonyms for +\&\fBEC_POINT_get_affine_coordinates()\fR. They are defined for backwards compatibility +only and should not be used. +.PP +As well as the affine coordinates, a point can alternatively be described in +terms of its Jacobian projective coordinates (for Fp curves only). Jacobian +projective coordinates are expressed as three values x, y and z. Working in +this coordinate system provides more efficient point multiplication +operations. A mapping exists between Jacobian projective coordinates and +affine coordinates. A Jacobian projective coordinate (x, y, z) can be written +as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian +projective from affine coordinates is simple. The coordinate (x, y) is mapped +to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used, +to set or get the projective coordinates in older versions use +\&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR and +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR respectively. +Modern versions should instead use \fBEC_POINT_set_affine_coordinates()\fR and +\&\fBEC_POINT_get_affine_coordinates()\fR, performing the conversion manually using the +above maps in such rare circumstances. +.PP +Points can also be described in terms of their compressed coordinates. For a +point (x, y), for any given value for x such that the point is on the curve +there will only ever be two possible values for y. Therefore, a point can be set +using the \fBEC_POINT_set_compressed_coordinates()\fR function where \fBx\fR is the x +coordinate and \fBy_bit\fR is a value 0 or 1 to identify which of the two +possible values for y should be used. +.PP +The functions \fBEC_POINT_set_compressed_coordinates_GFp()\fR and +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR are synonyms for +\&\fBEC_POINT_set_compressed_coordinates()\fR. They are defined for backwards +compatibility only and should not be used. +.PP +In addition \fBEC_POINT\fR can be converted to and from various external +representations. The octet form is the binary encoding of the \fBECPoint\fR +structure (as defined in RFC5480 and used in certificates and TLS records): +only the content octets are present, the \fBOCTET STRING\fR tag and length are +not included. \fBBIGNUM\fR form is the octet form interpreted as a big endian +integer converted to a \fBBIGNUM\fR structure. Hexadecimal form is the octet +form converted to a NULL terminated character string where each character +is one of the printable values 0\-9 or A\-F (or a\-f). +.PP +The functions \fBEC_POINT_point2oct()\fR, \fBEC_POINT_oct2point()\fR, \fBEC_POINT_point2bn()\fR, +\&\fBEC_POINT_bn2point()\fR, \fBEC_POINT_point2hex()\fR and \fBEC_POINT_hex2point()\fR convert from +and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively. +.PP +The function \fBEC_POINT_point2oct()\fR encodes the given curve point \fBp\fR as an +octet string into the buffer \fBbuf\fR of size \fBlen\fR, using the specified +conversion form \fBform\fR. +The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve +Cryptography") standard. +Similarly the function \fBEC_POINT_oct2point()\fR decodes a curve point into \fBp\fR from +the octet string contained in the given buffer \fBbuf\fR of size \fBlen\fR, conforming +to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. +.PP +The functions \fBEC_POINT_point2hex()\fR and \fBEC_POINT_point2bn()\fR convert a point \fBp\fR, +respectively, to the hexadecimal or BIGNUM representation of the same +encoding of the function \fBEC_POINT_point2oct()\fR. +Vice versa, similarly to the function \fBEC_POINT_oct2point()\fR, the functions +\&\fBEC_POINT_hex2point()\fR and \fBEC_POINT_point2bn()\fR decode the hexadecimal or +BIGNUM representation into the EC_POINT \fBp\fR. +.PP +Notice that, according to the standard, the octet string encoding of the point +at infinity for a given curve is fixed to a single octet of value zero and that, +vice versa, a single octet of size zero is decoded as the point at infinity. +.PP +The function \fBEC_POINT_point2oct()\fR must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will still return the required buffer length. +.PP +The function \fBEC_POINT_point2buf()\fR allocates a buffer of suitable length and +writes an EC_POINT to it in octet format. The allocated buffer is written to +\&\fB*pbuf\fR and its length is returned. The caller must free up the allocated +buffer with a call to \fBOPENSSL_free()\fR. Since the allocated buffer value is +written to \fB*pbuf\fR the \fBpbuf\fR parameter \fBMUST NOT\fR be \fBNULL\fR. +.PP +The function \fBEC_POINT_point2hex()\fR will allocate sufficient memory to store the +hexadecimal string. It is the caller\*(Aqs responsibility to free this memory with +a subsequent call to \fBOPENSSL_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEC_POINT_new()\fR and \fBEC_POINT_dup()\fR return the newly allocated EC_POINT or NULL +on error. +.PP +The following functions return 1 on success or 0 on error: \fBEC_POINT_copy()\fR, +\&\fBEC_POINT_set_to_infinity()\fR, \fBEC_POINT_set_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR and \fBEC_POINT_oct2point()\fR. +.PP +EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. +.PP +\&\fBEC_POINT_point2oct()\fR and \fBEC_POINT_point2buf()\fR return the length of the required +buffer or 0 on error. +.PP +\&\fBEC_POINT_point2bn()\fR returns the pointer to the BIGNUM supplied, or NULL on +error. +.PP +\&\fBEC_POINT_bn2point()\fR returns the pointer to the EC_POINT supplied, or NULL on +error. +.PP +\&\fBEC_POINT_point2hex()\fR returns a pointer to the hex string, or NULL on error. +.PP +\&\fBEC_POINT_hex2point()\fR returns the pointer to the EC_POINT supplied, or NULL on +error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3), +\&\fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), +\&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEC_POINT_method_of()\fR, +\&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, +\&\fBEC_POINT_point2bn()\fR, and \fBEC_POINT_bn2point()\fR were deprecated in OpenSSL 3.0. +.PP +\&\fBEC_POINT_set_affine_coordinates\fR, \fBEC_POINT_get_affine_coordinates\fR, +and \fBEC_POINT_set_compressed_coordinates\fR were +added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ENGINE_add.3 b/static/netbsd/man3/ENGINE_add.3 new file mode 100644 index 00000000..7ce666f9 --- /dev/null +++ b/static/netbsd/man3/ENGINE_add.3 @@ -0,0 +1,743 @@ +.\" $NetBSD: ENGINE_add.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ENGINE_add 3" +.TH ENGINE_add 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ENGINE_get_DH, ENGINE_get_DSA, +ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, +ENGINE_get_default_DSA, +ENGINE_get_default_RAND, +ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, +ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, +ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, +ENGINE_get_destroy_function, ENGINE_get_finish_function, +ENGINE_get_init_function, ENGINE_get_load_privkey_function, +ENGINE_get_load_pubkey_function, ENGINE_load_private_key, +ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, +ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, +ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, +ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, +ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, +ENGINE_register_DH, ENGINE_register_DSA, +ENGINE_register_RAND, ENGINE_register_RSA, +ENGINE_register_all_complete, ENGINE_register_ciphers, +ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, +ENGINE_set_DH, ENGINE_set_DSA, +ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, +ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, +ENGINE_set_default_DH, ENGINE_set_default_DSA, +ENGINE_set_default_RAND, ENGINE_set_default_RSA, +ENGINE_set_default_ciphers, ENGINE_set_default_digests, +ENGINE_set_default_string, ENGINE_set_destroy_function, +ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, +ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, +ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, +ENGINE_get_table_flags, ENGINE_cleanup, +ENGINE_load_builtin_engines, ENGINE_register_all_DH, +ENGINE_register_all_DSA, +ENGINE_register_all_RAND, +ENGINE_register_all_RSA, ENGINE_register_all_ciphers, +ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, +ENGINE_unregister_DSA, +ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, +ENGINE_unregister_digests +\&\- ENGINE cryptographic module support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& ENGINE *ENGINE_get_first(void); +\& ENGINE *ENGINE_get_last(void); +\& ENGINE *ENGINE_get_next(ENGINE *e); +\& ENGINE *ENGINE_get_prev(ENGINE *e); +\& +\& int ENGINE_add(ENGINE *e); +\& int ENGINE_remove(ENGINE *e); +\& +\& ENGINE *ENGINE_by_id(const char *id); +\& +\& int ENGINE_init(ENGINE *e); +\& int ENGINE_finish(ENGINE *e); +\& +\& void ENGINE_load_builtin_engines(void); +\& +\& ENGINE *ENGINE_get_default_RSA(void); +\& ENGINE *ENGINE_get_default_DSA(void); +\& ENGINE *ENGINE_get_default_DH(void); +\& ENGINE *ENGINE_get_default_RAND(void); +\& ENGINE *ENGINE_get_cipher_engine(int nid); +\& ENGINE *ENGINE_get_digest_engine(int nid); +\& +\& int ENGINE_set_default_RSA(ENGINE *e); +\& int ENGINE_set_default_DSA(ENGINE *e); +\& int ENGINE_set_default_DH(ENGINE *e); +\& int ENGINE_set_default_RAND(ENGINE *e); +\& int ENGINE_set_default_ciphers(ENGINE *e); +\& int ENGINE_set_default_digests(ENGINE *e); +\& int ENGINE_set_default_string(ENGINE *e, const char *list); +\& +\& int ENGINE_set_default(ENGINE *e, unsigned int flags); +\& +\& unsigned int ENGINE_get_table_flags(void); +\& void ENGINE_set_table_flags(unsigned int flags); +\& +\& int ENGINE_register_RSA(ENGINE *e); +\& void ENGINE_unregister_RSA(ENGINE *e); +\& void ENGINE_register_all_RSA(void); +\& int ENGINE_register_DSA(ENGINE *e); +\& void ENGINE_unregister_DSA(ENGINE *e); +\& void ENGINE_register_all_DSA(void); +\& int ENGINE_register_DH(ENGINE *e); +\& void ENGINE_unregister_DH(ENGINE *e); +\& void ENGINE_register_all_DH(void); +\& int ENGINE_register_RAND(ENGINE *e); +\& void ENGINE_unregister_RAND(ENGINE *e); +\& void ENGINE_register_all_RAND(void); +\& int ENGINE_register_ciphers(ENGINE *e); +\& void ENGINE_unregister_ciphers(ENGINE *e); +\& void ENGINE_register_all_ciphers(void); +\& int ENGINE_register_digests(ENGINE *e); +\& void ENGINE_unregister_digests(ENGINE *e); +\& void ENGINE_register_all_digests(void); +\& int ENGINE_register_complete(ENGINE *e); +\& int ENGINE_register_all_complete(void); +\& +\& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); +\& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); +\& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, +\& long i, void *p, void (*f)(void), int cmd_optional); +\& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, +\& int cmd_optional); +\& +\& ENGINE *ENGINE_new(void); +\& int ENGINE_free(ENGINE *e); +\& int ENGINE_up_ref(ENGINE *e); +\& +\& int ENGINE_set_id(ENGINE *e, const char *id); +\& int ENGINE_set_name(ENGINE *e, const char *name); +\& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); +\& int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); +\& int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); +\& int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); +\& int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); +\& int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); +\& int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); +\& int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); +\& int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); +\& int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); +\& int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); +\& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); +\& int ENGINE_set_flags(ENGINE *e, int flags); +\& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); +\& +\& const char *ENGINE_get_id(const ENGINE *e); +\& const char *ENGINE_get_name(const ENGINE *e); +\& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); +\& const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); +\& const DH_METHOD *ENGINE_get_DH(const ENGINE *e); +\& const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); +\& ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); +\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); +\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); +\& ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); +\& ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); +\& const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); +\& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); +\& int ENGINE_get_flags(const ENGINE *e); +\& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); +\& +\& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, +\& UI_METHOD *ui_method, void *callback_data); +\& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, +\& UI_METHOD *ui_method, void *callback_data); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void ENGINE_cleanup(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the provider APIs. +.PP +These functions create, manipulate, and use cryptographic modules in the +form of \fBENGINE\fR objects. These objects act as containers for +implementations of cryptographic algorithms, and support a +reference\-counted mechanism to allow them to be dynamically loaded in and +out of the running application. +.PP +The cryptographic functionality that can be provided by an \fBENGINE\fR +implementation includes the following abstractions; +.PP +.Vb 6 +\& RSA_METHOD \- for providing alternative RSA implementations +\& DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, +\& \- similarly for other OpenSSL APIs +\& EVP_CIPHER \- potentially multiple cipher algorithms (indexed by \*(Aqnid\*(Aq) +\& EVP_DIGEST \- potentially multiple hash algorithms (indexed by \*(Aqnid\*(Aq) +\& key\-loading \- loading public and/or private EVP_PKEY keys +.Ve +.SS "Reference counting and handles" +.IX Subsection "Reference counting and handles" +Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be +treated as handles \- i.e. not only as pointers, but also as references to +the underlying ENGINE object. Ie. one should obtain a new reference when +making copies of an ENGINE pointer if the copies will be used (and +released) independently. +.PP +ENGINE objects have two levels of reference\-counting to match the way in +which the objects are used. At the most basic level, each ENGINE pointer is +inherently a \fBstructural\fR reference \- a structural reference is required +to use the pointer value at all, as this kind of reference is a guarantee +that the structure can not be deallocated until the reference is released. +.PP +However, a structural reference provides no guarantee that the ENGINE is +initialised and able to use any of its cryptographic +implementations. Indeed it\*(Aqs quite possible that most ENGINEs will not +initialise at all in typical environments, as ENGINEs are typically used to +support specialised hardware. To use an ENGINE\*(Aqs functionality, you need a +\&\fBfunctional\fR reference. This kind of reference can be considered a +specialised form of structural reference, because each functional reference +implicitly contains a structural reference as well \- however to avoid +difficult\-to\-find programming bugs, it is recommended to treat the two +kinds of reference independently. If you have a functional reference to an +ENGINE, you have a guarantee that the ENGINE has been initialised and +is ready to perform cryptographic operations, and will remain initialised +until after you have released your reference. +.PP +\&\fIStructural references\fR +.PP +This basic type of reference is used for instantiating new ENGINEs, +iterating across OpenSSL\*(Aqs internal linked\-list of loaded +ENGINEs, reading information about an ENGINE, etc. Essentially a structural +reference is sufficient if you only need to query or manipulate the data of +an ENGINE implementation rather than use its functionality. +.PP +The \fBENGINE_new()\fR function returns a structural reference to a new (empty) +ENGINE object. There are other ENGINE API functions that return structural +references such as; \fBENGINE_by_id()\fR, \fBENGINE_get_first()\fR, \fBENGINE_get_last()\fR, +\&\fBENGINE_get_next()\fR, \fBENGINE_get_prev()\fR. All structural references should be +released by a corresponding to call to the \fBENGINE_free()\fR function \- the +ENGINE object itself will only actually be cleaned up and deallocated when +the last structural reference is released. If the argument to \fBENGINE_free()\fR +is NULL, nothing is done. +.PP +It should also be noted that many ENGINE API function calls that accept a +structural reference will internally obtain another reference \- typically +this happens whenever the supplied ENGINE will be needed by OpenSSL after +the function has returned. Eg. the function to add a new ENGINE to +OpenSSL\*(Aqs internal list is \fBENGINE_add()\fR \- if this function returns success, +then OpenSSL will have stored a new structural reference internally so the +caller is still responsible for freeing their own reference with +\&\fBENGINE_free()\fR when they are finished with it. In a similar way, some +functions will automatically release the structural reference passed to it +if part of the function\*(Aqs job is to do so. Eg. the \fBENGINE_get_next()\fR and +\&\fBENGINE_get_prev()\fR functions are used for iterating across the internal +ENGINE list \- they will return a new structural reference to the next (or +previous) ENGINE in the list or NULL if at the end (or beginning) of the +list, but in either case the structural reference passed to the function is +released on behalf of the caller. +.PP +To clarify a particular function\*(Aqs handling of references, one should +always consult that function\*(Aqs documentation "man" page, or failing that +the \fI\fR header file includes some hints. +.PP +\&\fIFunctional references\fR +.PP +As mentioned, functional references exist when the cryptographic +functionality of an ENGINE is required to be available. A functional +reference can be obtained in one of two ways; from an existing structural +reference to the required ENGINE, or by asking OpenSSL for the default +operational ENGINE for a given cryptographic purpose. +.PP +To obtain a functional reference from an existing structural reference, +call the \fBENGINE_init()\fR function. This returns zero if the ENGINE was not +already operational and couldn\*(Aqt be successfully initialised (e.g. lack of +system drivers, no special hardware attached, etc), otherwise it will +return nonzero to indicate that the ENGINE is now operational and will +have allocated a new \fBfunctional\fR reference to the ENGINE. All functional +references are released by calling \fBENGINE_finish()\fR (which removes the +implicit structural reference as well). +.PP +The second way to get a functional reference is by asking OpenSSL for a +default implementation for a given task, e.g. by \fBENGINE_get_default_RSA()\fR, +\&\fBENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next +section, though they are not usually required by application programmers as +they are used automatically when creating and using the relevant +algorithm\-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. +.SS "Default implementations" +.IX Subsection "Default implementations" +For each supported abstraction, the ENGINE code maintains an internal table +of state to control which implementations are available for a given +abstraction and which should be used by default. These implementations are +registered in the tables and indexed by an \*(Aqnid\*(Aq value, because +abstractions like EVP_CIPHER and EVP_DIGEST support many distinct +algorithms and modes, and ENGINEs can support arbitrarily many of them. +In the case of other abstractions like RSA, DSA, etc, there is only one +"algorithm" so all implementations implicitly register using the same \*(Aqnid\*(Aq +index. +.PP +When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g. +when calling RSA_new_method(NULL)), a "get_default" call will be made to the +ENGINE subsystem to process the corresponding state table and return a +functional reference to an initialised ENGINE whose implementation should be +used. If no ENGINE should (or can) be used, it will return NULL and the caller +will operate with a NULL ENGINE handle \- this usually equates to using the +conventional software implementation. In the latter case, OpenSSL will from +then on behave the way it used to before the ENGINE API existed. +.PP +Each state table has a flag to note whether it has processed this +"get_default" query since the table was last modified, because to process +this question it must iterate across all the registered ENGINEs in the +table trying to initialise each of them in turn, in case one of them is +operational. If it returns a functional reference to an ENGINE, it will +also cache another reference to speed up processing future queries (without +needing to iterate across the table). Likewise, it will cache a NULL +response if no ENGINE was available so that future queries won\*(Aqt repeat the +same iteration unless the state table changes. This behaviour can also be +changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using +\&\fBENGINE_set_table_flags()\fR), no attempted initialisations will take place, +instead the only way for the state table to return a non\-NULL ENGINE to the +"get_default" query will be if one is expressly set in the table. Eg. +\&\fBENGINE_set_default_RSA()\fR does the same job as \fBENGINE_register_RSA()\fR except +that it also sets the state table\*(Aqs cached response for the "get_default" +query. In the case of abstractions like EVP_CIPHER, where implementations are +indexed by \*(Aqnid\*(Aq, these flags and cached\-responses are distinct for each \*(Aqnid\*(Aq +value. +.SS "Application requirements" +.IX Subsection "Application requirements" +This section will explain the basic things an application programmer should +support to make the most useful elements of the ENGINE functionality +available to the user. The first thing to consider is whether the +programmer wishes to make alternative ENGINE modules available to the +application and user. OpenSSL maintains an internal linked list of +"visible" ENGINEs from which it has to operate \- at start\-up, this list is +empty and in fact if an application does not call any ENGINE API calls and +it uses static linking against openssl, then the resulting application +binary will not contain any alternative ENGINE code at all. So the first +consideration is whether any/all available ENGINE implementations should be +made visible to OpenSSL \- this is controlled by calling the various "load" +functions. +.PP +The fact that ENGINEs are made visible to OpenSSL (and thus are linked into +the program and loaded into memory at run\-time) does not mean they are +"registered" or called into use by OpenSSL automatically \- that behaviour +is something for the application to control. Some applications +will want to allow the user to specify exactly which ENGINE they want used +if any is to be used at all. Others may prefer to load all support and have +OpenSSL automatically use at run\-time any ENGINE that is able to +successfully initialise \- i.e. to assume that this corresponds to +acceleration hardware attached to the machine or some such thing. There are +probably numerous other ways in which applications may prefer to handle +things, so we will simply illustrate the consequences as they apply to a +couple of simple cases and leave developers to consider these and the +source code to openssl\*(Aqs built\-in utilities as guides. +.PP +If no ENGINE API functions are called within an application, then OpenSSL +will not allocate any internal resources. Prior to OpenSSL 1.1.0, however, +if any ENGINEs are loaded, even if not registered or used, it was necessary to +call \fBENGINE_cleanup()\fR before the program exits. +.PP +\&\fIUsing a specific ENGINE implementation\fR +.PP +Here we\*(Aqll assume an application has been configured by its user or admin +to want to use the "ACME" ENGINE if it is available in the version of +OpenSSL the application was compiled with. If it is available, it should be +used by default for all RSA, DSA, and symmetric cipher operations, otherwise +OpenSSL should use its built\-in software as per usual. The following code +illustrates how to approach this; +.PP +.Vb 10 +\& ENGINE *e; +\& const char *engine_id = "ACME"; +\& ENGINE_load_builtin_engines(); +\& e = ENGINE_by_id(engine_id); +\& if (!e) +\& /* the engine isn\*(Aqt available */ +\& return; +\& if (!ENGINE_init(e)) { +\& /* the engine couldn\*(Aqt initialise, release \*(Aqe\*(Aq */ +\& ENGINE_free(e); +\& return; +\& } +\& if (!ENGINE_set_default_RSA(e)) +\& /* +\& * This should only happen when \*(Aqe\*(Aq can\*(Aqt initialise, but the previous +\& * statement suggests it did. +\& */ +\& abort(); +\& ENGINE_set_default_DSA(e); +\& ENGINE_set_default_ciphers(e); +\& /* Release the functional reference from ENGINE_init() */ +\& ENGINE_finish(e); +\& /* Release the structural reference from ENGINE_by_id() */ +\& ENGINE_free(e); +.Ve +.PP +\&\fIAutomatically using built\-in ENGINE implementations\fR +.PP +Here we\*(Aqll assume we want to load and register all ENGINE implementations +bundled with OpenSSL, such that for any cryptographic algorithm required by +OpenSSL \- if there is an ENGINE that implements it and can be initialised, +it should be used. The following code illustrates how this can work; +.PP +.Vb 4 +\& /* Load all bundled ENGINEs into memory and make them visible */ +\& ENGINE_load_builtin_engines(); +\& /* Register all of them for every algorithm they collectively implement */ +\& ENGINE_register_all_complete(); +.Ve +.PP +That\*(Aqs all that\*(Aqs required. Eg. the next time OpenSSL tries to set up an +RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to +\&\fBENGINE_init()\fR and if any of those succeed, that ENGINE will be set as the +default for RSA use from then on. +.SS "Advanced configuration support" +.IX Subsection "Advanced configuration support" +There is a mechanism supported by the ENGINE framework that allows each +ENGINE implementation to define an arbitrary set of configuration +"commands" and expose them to OpenSSL and any applications based on +OpenSSL. This mechanism is entirely based on the use of name\-value pairs +and assumes ASCII input (no unicode or UTF for now!), so it is ideal if +applications want to provide a transparent way for users to provide +arbitrary configuration "directives" directly to such ENGINEs. It is also +possible for the application to dynamically interrogate the loaded ENGINE +implementations for the names, descriptions, and input flags of their +available "control commands", providing a more flexible configuration +scheme. However, if the user is expected to know which ENGINE device he/she +is using (in the case of specialised hardware, this goes without saying) +then applications may not need to concern themselves with discovering the +supported control commands and simply prefer to pass settings into ENGINEs +exactly as they are provided by the user. +.PP +Before illustrating how control commands work, it is worth mentioning what +they are typically used for. Broadly speaking there are two uses for +control commands; the first is to provide the necessary details to the +implementation (which may know nothing at all specific to the host system) +so that it can be initialised for use. This could include the path to any +driver or config files it needs to load, required network addresses, +smart\-card identifiers, passwords to initialise protected devices, +logging information, etc etc. This class of commands typically needs to be +passed to an ENGINE \fBbefore\fR attempting to initialise it, i.e. before +calling \fBENGINE_init()\fR. The other class of commands consist of settings or +operations that tweak certain behaviour or cause certain operations to take +place, and these commands may work either before or after \fBENGINE_init()\fR, or +in some cases both. ENGINE implementations should provide indications of +this in the descriptions attached to built\-in control commands and/or in +external product documentation. +.PP +\&\fIIssuing control commands to an ENGINE\fR +.PP +Let\*(Aqs illustrate by example; a function for which the caller supplies the +name of the ENGINE it wishes to use, a table of string\-pairs for use before +initialisation, and another table for use after initialisation. Note that +the string\-pairs used for control commands consist of a command "name" +followed by the command "parameter" \- the parameter could be NULL in some +cases but the name can not. This function should initialise the ENGINE +(issuing the "pre" commands beforehand and the "post" commands afterwards) +and set it as the default for everything except RAND and then return a +boolean success or failure. +.PP +.Vb 10 +\& int generic_load_engine_fn(const char *engine_id, +\& const char **pre_cmds, int pre_num, +\& const char **post_cmds, int post_num) +\& { +\& ENGINE *e = ENGINE_by_id(engine_id); +\& if (!e) return 0; +\& while (pre_num\-\-) { +\& if (!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, +\& pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); +\& ENGINE_free(e); +\& return 0; +\& } +\& pre_cmds += 2; +\& } +\& if (!ENGINE_init(e)) { +\& fprintf(stderr, "Failed initialisation\en"); +\& ENGINE_free(e); +\& return 0; +\& } +\& /* +\& * ENGINE_init() returned a functional reference, so free the structural +\& * reference from ENGINE_by_id(). +\& */ +\& ENGINE_free(e); +\& while (post_num\-\-) { +\& if (!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, +\& post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); +\& ENGINE_finish(e); +\& return 0; +\& } +\& post_cmds += 2; +\& } +\& ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); +\& /* Success */ +\& return 1; +\& } +.Ve +.PP +Note that \fBENGINE_ctrl_cmd_string()\fR accepts a boolean argument that can +relax the semantics of the function \- if set nonzero it will only return +failure if the ENGINE supported the given command name but failed while +executing it, if the ENGINE doesn\*(Aqt support the command name it will simply +return success without doing anything. In this case we assume the user is +only supplying commands specific to the given ENGINE so we set this to +FALSE. +.PP +\&\fIDiscovering supported control commands\fR +.PP +It is possible to discover at run\-time the names, numerical\-ids, descriptions +and input parameters of the control commands supported by an ENGINE using a +structural reference. Note that some control commands are defined by OpenSSL +itself and it will intercept and handle these control commands on behalf of the +ENGINE, i.e. the ENGINE\*(Aqs \fBctrl()\fR handler is not used for the control command. +\&\fI\fR defines an index, ENGINE_CMD_BASE, that all control +commands implemented by ENGINEs should be numbered from. Any command value +lower than this symbol is considered a "generic" command is handled directly +by the OpenSSL core routines. +.PP +It is using these "core" control commands that one can discover the control +commands implemented by a given ENGINE, specifically the commands: +.PP +.Vb 9 +\& ENGINE_HAS_CTRL_FUNCTION +\& ENGINE_CTRL_GET_FIRST_CMD_TYPE +\& ENGINE_CTRL_GET_NEXT_CMD_TYPE +\& ENGINE_CTRL_GET_CMD_FROM_NAME +\& ENGINE_CTRL_GET_NAME_LEN_FROM_CMD +\& ENGINE_CTRL_GET_NAME_FROM_CMD +\& ENGINE_CTRL_GET_DESC_LEN_FROM_CMD +\& ENGINE_CTRL_GET_DESC_FROM_CMD +\& ENGINE_CTRL_GET_CMD_FLAGS +.Ve +.PP +Whilst these commands are automatically processed by the OpenSSL framework code, +they use various properties exposed by each ENGINE to process these +queries. An ENGINE has 3 properties it exposes that can affect how this behaves; +it can supply a \fBctrl()\fR handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in +the ENGINE\*(Aqs flags, and it can expose an array of control command descriptions. +If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will +simply pass all these "core" control commands directly to the ENGINE\*(Aqs \fBctrl()\fR +handler (and thus, it must have supplied one), so it is up to the ENGINE to +reply to these "discovery" commands itself. If that flag is not set, then the +OpenSSL framework code will work with the following rules: +.PP +.Vb 9 +\& if no ctrl() handler supplied; +\& ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), +\& all other commands fail. +\& if a ctrl() handler was supplied but no array of control commands; +\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, +\& all other commands fail. +\& if a ctrl() handler and array of control commands was supplied; +\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, +\& all other commands proceed processing ... +.Ve +.PP +If the ENGINE\*(Aqs array of control commands is empty then all other commands will +fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of +the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the +identifier of a command supported by the ENGINE and returns the next command +identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string +name for a command and returns the corresponding identifier or fails if no such +command name exists, and the remaining commands take a command identifier and +return properties of the corresponding commands. All except +ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, +or populate a supplied character buffer with a copy of the command name or +description. ENGINE_CTRL_GET_FLAGS returns a bitwise\-OR\*(Aqd mask of the following +possible values: +.PP +.Vb 4 +\& ENGINE_CMD_FLAG_NUMERIC +\& ENGINE_CMD_FLAG_STRING +\& ENGINE_CMD_FLAG_NO_INPUT +\& ENGINE_CMD_FLAG_INTERNAL +.Ve +.PP +If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely +informational to the caller \- this flag will prevent the command being usable +for any higher\-level ENGINE functions such as \fBENGINE_ctrl_cmd_string()\fR. +"INTERNAL" commands are not intended to be exposed to text\-based configuration +by applications, administrations, users, etc. These can support arbitrary +operations via \fBENGINE_ctrl()\fR, including passing to and/or from the control +commands data of any arbitrary type. These commands are supported in the +discovery mechanisms simply to allow applications to determine if an ENGINE +supports certain specific commands it might want to use (e.g. application "foo" +might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" \- +and ENGINE could therefore decide whether or not to support this "foo"\-specific +extension). +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +.IP \fBOPENSSL_ENGINES\fR 4 +.IX Item "OPENSSL_ENGINES" +The path to the engines directory. +Ignored in set\-user\-ID and set\-group\-ID programs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBENGINE_get_first()\fR, \fBENGINE_get_last()\fR, \fBENGINE_get_next()\fR and \fBENGINE_get_prev()\fR +return a valid \fBENGINE\fR structure or NULL if an error occurred. +.PP +\&\fBENGINE_add()\fR and \fBENGINE_remove()\fR return 1 on success or 0 on error. +.PP +\&\fBENGINE_by_id()\fR returns a valid \fBENGINE\fR structure or NULL if an error occurred. +.PP +\&\fBENGINE_init()\fR and \fBENGINE_finish()\fR return 1 on success or 0 on error. +.PP +All \fBENGINE_get_default_TYPE()\fR functions, \fBENGINE_get_cipher_engine()\fR and +\&\fBENGINE_get_digest_engine()\fR return a valid \fBENGINE\fR structure on success or NULL +if an error occurred. +.PP +All \fBENGINE_set_default_TYPE()\fR functions return 1 on success or 0 on error. +.PP +\&\fBENGINE_set_default()\fR returns 1 on success or 0 on error. +.PP +\&\fBENGINE_get_table_flags()\fR returns an unsigned integer value representing the +global table flags which are used to control the registration behaviour of +\&\fBENGINE\fR implementations. +.PP +All \fBENGINE_register_TYPE()\fR functions return 1 on success or 0 on error. +.PP +\&\fBENGINE_register_complete()\fR and \fBENGINE_register_all_complete()\fR always return 1. +.PP +\&\fBENGINE_ctrl()\fR returns a positive value on success or others on error. +.PP +\&\fBENGINE_cmd_is_executable()\fR returns 1 if \fBcmd\fR is executable or 0 otherwise. +.PP +\&\fBENGINE_ctrl_cmd()\fR and \fBENGINE_ctrl_cmd_string()\fR return 1 on success or 0 on error. +.PP +\&\fBENGINE_new()\fR returns a valid \fBENGINE\fR structure on success or NULL if an error +occurred. +.PP +\&\fBENGINE_free()\fR always returns 1. +.PP +\&\fBENGINE_up_ref()\fR returns 1 on success or 0 on error. +.PP +\&\fBENGINE_set_id()\fR and \fBENGINE_set_name()\fR return 1 on success or 0 on error. +.PP +All other \fBENGINE_set_*\fR functions return 1 on success or 0 on error. +.PP +\&\fBENGINE_get_id()\fR and \fBENGINE_get_name()\fR return a string representing the identifier +and the name of the ENGINE \fBe\fR respectively. +.PP +\&\fBENGINE_get_RSA()\fR, \fBENGINE_get_DSA()\fR, \fBENGINE_get_DH()\fR and \fBENGINE_get_RAND()\fR +return corresponding method structures for each algorithms. +.PP +\&\fBENGINE_get_destroy_function()\fR, \fBENGINE_get_init_function()\fR, +\&\fBENGINE_get_finish_function()\fR, \fBENGINE_get_ctrl_function()\fR, +\&\fBENGINE_get_load_privkey_function()\fR, \fBENGINE_get_load_pubkey_function()\fR, +\&\fBENGINE_get_ciphers()\fR and \fBENGINE_get_digests()\fR return corresponding function +pointers of the callbacks. +.PP +\&\fBENGINE_get_cipher()\fR returns a valid \fBEVP_CIPHER\fR structure on success or NULL +if an error occurred. +.PP +\&\fBENGINE_get_digest()\fR returns a valid \fBEVP_MD\fR structure on success or NULL if an +error occurred. +.PP +\&\fBENGINE_get_flags()\fR returns an integer representing the ENGINE flags which are +used to control various behaviours of an ENGINE. +.PP +\&\fBENGINE_get_cmd_defns()\fR returns an \fBENGINE_CMD_DEFN\fR structure or NULL if it\*(Aqs +not set. +.PP +\&\fBENGINE_load_private_key()\fR and \fBENGINE_load_public_key()\fR return a valid \fBEVP_PKEY\fR +structure on success or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_init_crypto\fR\|(3), \fBRSA_new_method\fR\|(3), \fBDSA_new\fR\|(3), \fBDH_new\fR\|(3), +\&\fBRAND_bytes\fR\|(3), \fBconfig\fR\|(5) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +\&\fBENGINE_cleanup()\fR was deprecated in OpenSSL 1.1.0 by the automatic cleanup +done by \fBOPENSSL_cleanup()\fR +and should not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_GET_LIB.3 b/static/netbsd/man3/ERR_GET_LIB.3 new file mode 100644 index 00000000..2cc71f56 --- /dev/null +++ b/static/netbsd/man3/ERR_GET_LIB.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: ERR_GET_LIB.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_GET_LIB 3" +.TH ERR_GET_LIB 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_GET_LIB, ERR_GET_REASON, ERR_FATAL_ERROR +\&\- get information from error codes +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ERR_GET_LIB(unsigned long e); +\& +\& int ERR_GET_REASON(unsigned long e); +\& +\& int ERR_FATAL_ERROR(unsigned long e); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The error code returned by \fBERR_get_error()\fR consists of a library +number and reason code. \fBERR_GET_LIB()\fR +and \fBERR_GET_REASON()\fR can be used to extract these. +.PP +\&\fBERR_FATAL_ERROR()\fR indicates whether a given error code is a fatal error. +.PP +The library number describes where the error +occurred, the reason code is the information about what went wrong. +.PP +Each sub\-library of OpenSSL has a unique library number; the +reason code is unique within each sub\-library. Note that different +libraries may use the same value to signal different reasons. +.PP +\&\fBERR_R_...\fR reason codes such as \fBERR_R_MALLOC_FAILURE\fR are globally +unique. However, when checking for sub\-library specific reason codes, +be sure to also compare the library number. +.PP +\&\fBERR_GET_LIB()\fR, \fBERR_GET_REASON()\fR, and \fBERR_FATAL_ERROR()\fR are macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The library number, reason code, and whether the error +is fatal, respectively. +Starting with OpenSSL 3.0.0, the function code is always set to zero. +.SH NOTES +.IX Header "NOTES" +Applications should not make control flow decisions based on specific error +codes. Error codes are subject to change at any time (even in patch releases of +OpenSSL). A particular error code can only be considered meaningful for control +flow decisions if it is explicitly documented as such. New failure codes may +still appear at any time. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBERR_GET_LIB()\fR and \fBERR_GET_REASON()\fR are available in all versions of OpenSSL. +.PP +\&\fBERR_GET_FUNC()\fR was removed in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_clear_error.3 b/static/netbsd/man3/ERR_clear_error.3 new file mode 100644 index 00000000..059bcf57 --- /dev/null +++ b/static/netbsd/man3/ERR_clear_error.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: ERR_clear_error.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_clear_error 3" +.TH ERR_clear_error 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_clear_error \- clear the error queue +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void ERR_clear_error(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_clear_error()\fR empties the current thread\*(Aqs error queue. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_clear_error()\fR has no return value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_error_string.3 b/static/netbsd/man3/ERR_error_string.3 new file mode 100644 index 00000000..9fd007d6 --- /dev/null +++ b/static/netbsd/man3/ERR_error_string.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: ERR_error_string.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_error_string 3" +.TH ERR_error_string 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_error_string, ERR_error_string_n, ERR_lib_error_string, +ERR_func_error_string, ERR_reason_error_string \- obtain human\-readable +error message +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& char *ERR_error_string(unsigned long e, char *buf); +\& void ERR_error_string_n(unsigned long e, char *buf, size_t len); +\& +\& const char *ERR_lib_error_string(unsigned long e); +\& const char *ERR_reason_error_string(unsigned long e); +.Ve +.PP +Deprecated in OpenSSL 3.0: +.PP +.Vb 1 +\& const char *ERR_func_error_string(unsigned long e); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_error_string()\fR generates a human\-readable string representing the +error code \fIe\fR, and places it at \fIbuf\fR. \fIbuf\fR must be at least 256 +bytes long. If \fIbuf\fR is \fBNULL\fR, the error string is placed in a +static buffer. +Note that this function is not thread\-safe and does no checks on the size +of the buffer; use \fBERR_error_string_n()\fR instead. +.PP +\&\fBERR_error_string_n()\fR is a variant of \fBERR_error_string()\fR that writes +at most \fIlen\fR characters (including the terminating 0) +and truncates the string if necessary. +For \fBERR_error_string_n()\fR, \fIbuf\fR \fBMUST NOT\fR be NULL. +.PP +The string will have the following format: +.PP +.Vb 1 +\& error:[error code]:[library name]::[reason string] +.Ve +.PP +\&\fIerror code\fR is an 8 digit hexadecimal number, \fIlibrary name\fR and +\&\fIreason string\fR are ASCII text. +.PP +\&\fBERR_lib_error_string()\fR and \fBERR_reason_error_string()\fR return the library +name and reason string respectively. +.PP +If there is no text string registered for the given error code, +the error string will contain the numeric code. +.PP +\&\fBERR_print_errors\fR\|(3) can be used to print +all error codes currently in the queue. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_error_string()\fR returns a pointer to a static buffer containing the +string if \fIbuf\fR \fB== NULL\fR, \fIbuf\fR otherwise. +.PP +\&\fBERR_lib_error_string()\fR and \fBERR_reason_error_string()\fR return the strings, +and \fBNULL\fR if none is registered for the error code. +.PP +\&\fBERR_func_error_string()\fR returns NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBERR_print_errors\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBERR_func_error_string()\fR became deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_get_error.3 b/static/netbsd/man3/ERR_get_error.3 new file mode 100644 index 00000000..041ae0bc --- /dev/null +++ b/static/netbsd/man3/ERR_get_error.3 @@ -0,0 +1,201 @@ +.\" $NetBSD: ERR_get_error.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_get_error 3" +.TH ERR_get_error 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_get_error, ERR_peek_error, ERR_peek_last_error, +ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, +ERR_peek_error_func, ERR_peek_last_error_func, +ERR_peek_error_data, ERR_peek_last_error_data, +ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all, +ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data +\&\- obtain error code and data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned long ERR_get_error(void); +\& unsigned long ERR_peek_error(void); +\& unsigned long ERR_peek_last_error(void); +\& +\& unsigned long ERR_peek_error_line(const char **file, int *line); +\& unsigned long ERR_peek_last_error_line(const char **file, int *line); +\& +\& unsigned long ERR_peek_error_func(const char **func); +\& unsigned long ERR_peek_last_error_func(const char **func); +\& +\& unsigned long ERR_peek_error_data(const char **data, int *flags); +\& unsigned long ERR_peek_last_error_data(const char **data, int *flags); +\& +\& unsigned long ERR_get_error_all(const char **file, int *line, +\& const char **func, +\& const char **data, int *flags); +\& unsigned long ERR_peek_error_all(const char **file, int *line, +\& const char **func, +\& const char **data, int *flags); +\& unsigned long ERR_peek_last_error_all(const char **file, int *line, +\& const char *func, +\& const char **data, int *flags); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 7 +\& unsigned long ERR_get_error_line(const char **file, int *line); +\& unsigned long ERR_get_error_line_data(const char **file, int *line, +\& const char **data, int *flags); +\& unsigned long ERR_peek_error_line_data(const char **file, int *line, +\& const char **data, int *flags); +\& unsigned long ERR_peek_last_error_line_data(const char **file, int *line, +\& const char **data, int *flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_get_error()\fR returns the earliest error code from the thread\*(Aqs error +queue and removes the entry. This function can be called repeatedly +until there are no more error codes to return. +.PP +\&\fBERR_peek_error()\fR returns the earliest error code from the thread\*(Aqs +error queue without modifying it. +.PP +\&\fBERR_peek_last_error()\fR returns the latest error code from the thread\*(Aqs +error queue without modifying it. +.PP +See \fBERR_GET_LIB\fR\|(3) for obtaining further specific information +such as the reason of the error, +and \fBERR_error_string\fR\|(3) for human\-readable error messages. +.PP +\&\fBERR_get_error_all()\fR is the same as \fBERR_get_error()\fR, but on success it +additionally stores the filename, line number and function where the error +occurred in *\fIfile\fR, *\fIline\fR and *\fIfunc\fR, and also extra text and flags +in *\fIdata\fR, *\fIflags\fR. If any of those parameters are NULL, it will not +be changed. +An unset filename is indicated as "", i.e. an empty string. +An unset line number is indicated as 0. +An unset function name is indicated as "", i.e. an empty string. +.PP +A pointer returned this way by these functions and the ones below +is valid until the respective entry is overwritten in the error queue. +.PP +\&\fBERR_peek_error_line()\fR and \fBERR_peek_last_error_line()\fR are the same as +\&\fBERR_peek_error()\fR and \fBERR_peek_last_error()\fR, but on success they additionally +store the filename and line number where the error occurred in *\fIfile\fR and +*\fIline\fR, as far as they are not NULL. +An unset filename is indicated as "", i.e., an empty string. +An unset line number is indicated as 0. +.PP +\&\fBERR_peek_error_func()\fR and \fBERR_peek_last_error_func()\fR are the same as +\&\fBERR_peek_error()\fR and \fBERR_peek_last_error()\fR, but on success they additionally +store the name of the function where the error occurred in *\fIfunc\fR, unless +it is NULL. +An unset function name is indicated as "". +.PP +\&\fBERR_peek_error_data()\fR and \fBERR_peek_last_error_data()\fR are the same as +\&\fBERR_peek_error()\fR and \fBERR_peek_last_error()\fR, but on success they additionally +store additional data and flags associated with the error code in *\fIdata\fR +and *\fIflags\fR, as far as they are not NULL. +Unset data is indicated as "". +In this case the value given for the flag is irrelevant (and equals 0). +*\fIdata\fR contains a string if *\fIflags\fR&\fBERR_TXT_STRING\fR is true. +.PP +\&\fBERR_peek_error_all()\fR and \fBERR_peek_last_error_all()\fR are combinations of all +of the above. +.PP +\&\fBERR_get_error_line()\fR, \fBERR_get_error_line_data()\fR, \fBERR_peek_error_line_data()\fR +and \fBERR_peek_last_error_line_data()\fR are older variants of \fBERR_get_error_all()\fR, +\&\fBERR_peek_error_all()\fR and \fBERR_peek_last_error_all()\fR, and may give confusing +results. They should no longer be used and are therefore deprecated. +.PP +An application \fBMUST NOT\fR free the *\fIdata\fR pointer (or any other pointers +returned by these functions) with \fBOPENSSL_free()\fR as freeing is handled +automatically by the error library. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The error code, or 0 if there is no error in the queue. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_error_string\fR\|(3), +\&\fBERR_GET_LIB\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBERR_peek_error_func()\fR, \fBERR_peek_last_error_func()\fR, +\&\fBERR_peek_error_data()\fR, \fBERR_peek_last_error_data()\fR, +\&\fBERR_peek_error_all()\fR and \fBERR_peek_last_error_all()\fR +were added in OpenSSL 3.0. +.PP +\&\fBERR_get_error_line()\fR, \fBERR_get_error_line_data()\fR, \fBERR_peek_error_line_data()\fR +and \fBERR_peek_last_error_line_data()\fR became deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_load_crypto_strings.3 b/static/netbsd/man3/ERR_load_crypto_strings.3 new file mode 100644 index 00000000..02fc6013 --- /dev/null +++ b/static/netbsd/man3/ERR_load_crypto_strings.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: ERR_load_crypto_strings.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_load_crypto_strings 3" +.TH ERR_load_crypto_strings 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings \- +load and free error strings +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The following functions have been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& void ERR_load_crypto_strings(void); +\& void ERR_free_strings(void); +\& +\& #include +\& +\& void SSL_load_error_strings(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_load_crypto_strings()\fR registers the error strings for all +\&\fBlibcrypto\fR functions. \fBSSL_load_error_strings()\fR does the same, +but also registers the \fBlibssl\fR error strings. +.PP +In versions prior to OpenSSL 1.1.0, +\&\fBERR_free_strings()\fR releases any resources created by the above functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_load_crypto_strings()\fR, \fBSSL_load_error_strings()\fR and +\&\fBERR_free_strings()\fR return no values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_error_string\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBERR_load_crypto_strings()\fR, \fBSSL_load_error_strings()\fR, and +\&\fBERR_free_strings()\fR functions were deprecated in OpenSSL 1.1.0 by +\&\fBOPENSSL_init_crypto()\fR and \fBOPENSSL_init_ssl()\fR and should not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_load_strings.3 b/static/netbsd/man3/ERR_load_strings.3 new file mode 100644 index 00000000..8f389f0c --- /dev/null +++ b/static/netbsd/man3/ERR_load_strings.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: ERR_load_strings.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_load_strings 3" +.TH ERR_load_strings 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_load_strings, ERR_PACK, ERR_get_next_error_library \- load +arbitrary error strings +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ERR_load_strings(int lib, ERR_STRING_DATA *str); +\& +\& int ERR_get_next_error_library(void); +\& +\& unsigned long ERR_PACK(int lib, int func, int reason); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_load_strings()\fR registers error strings for library number \fBlib\fR. +.PP +\&\fBstr\fR is an array of error string data: +.PP +.Vb 5 +\& typedef struct ERR_string_data_st +\& { +\& unsigned long error; +\& char *string; +\& } ERR_STRING_DATA; +.Ve +.PP +The error code is generated from the library number and a function and +reason code: \fBerror\fR = ERR_PACK(\fBlib\fR, \fBfunc\fR, \fBreason\fR). +\&\fBERR_PACK()\fR is a macro. +.PP +The last entry in the array is {0,0}. +.PP +\&\fBERR_get_next_error_library()\fR can be used to assign library numbers +to user libraries at run time. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_load_strings()\fR returns 1 for success and 0 for failure. \fBERR_PACK()\fR returns the error code. +\&\fBERR_get_next_error_library()\fR returns zero on failure, otherwise a new +library number. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_load_strings\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_new.3 b/static/netbsd/man3/ERR_new.3 new file mode 100644 index 00000000..8d08d825 --- /dev/null +++ b/static/netbsd/man3/ERR_new.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: ERR_new.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_new 3" +.TH ERR_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error +\&\- Error recording building blocks +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void ERR_new(void); +\& void ERR_set_debug(const char *file, int line, const char *func); +\& void ERR_set_error(int lib, int reason, const char *fmt, ...); +\& void ERR_vset_error(int lib, int reason, const char *fmt, va_list args); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described here are generally not used directly, but +rather through macros such as \fBERR_raise\fR\|(3). +They can still be useful for anyone that wants to make their own +macros. +.PP +\&\fBERR_new()\fR allocates a new slot in the thread\*(Aqs error queue. +.PP +\&\fBERR_set_debug()\fR sets the debug information related to the current +error in the thread\*(Aqs error queue. +The values that can be given are the filename \fIfile\fR, line in the +file \fIline\fR and the name of the function \fIfunc\fR where the error +occurred. +The names must be constant, this function will only save away the +pointers, not copy the strings. +.PP +\&\fBERR_set_error()\fR sets the error information, which are the library +number \fIlib\fR and the reason code \fIreason\fR, and additional data as a +format string \fIfmt\fR and an arbitrary number of arguments. +The additional data is processed with \fBBIO_snprintf\fR\|(3) to form the +additional data string, which is allocated and store in the error +record. +.PP +\&\fBERR_vset_error()\fR works like \fBERR_set_error()\fR, but takes a \fBva_list\fR +argument instead of a variable number of arguments. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +ERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error +do not return any values. +.SH NOTES +.IX Header "NOTES" +The library number is unique to each unit that records errors. +OpenSSL has a number of preallocated ones for its own uses, but +others may allocate their own library number dynamically with +\&\fBERR_get_next_error_library\fR\|(3). +.PP +Reason codes are unique within each library, and may have an +associated set of strings as a short description of the reason. +For dynamically allocated library numbers, reason strings are recorded +with \fBERR_load_strings\fR\|(3). +.PP +Provider authors are supplied with core versions of these functions, +see \fBprovider\-base\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_raise\fR\|(3), \fBERR_get_next_error_library\fR\|(3), +\&\fBERR_load_strings\fR\|(3), \fBBIO_snprintf\fR\|(3), \fBprovider\-base\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_print_errors.3 b/static/netbsd/man3/ERR_print_errors.3 new file mode 100644 index 00000000..3812bfff --- /dev/null +++ b/static/netbsd/man3/ERR_print_errors.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: ERR_print_errors.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_print_errors 3" +.TH ERR_print_errors 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb +\&\- print error messages +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void ERR_print_errors(BIO *bp); +\& void ERR_print_errors_fp(FILE *fp); +\& void ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u), +\& void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_print_errors()\fR is a convenience function that prints the error +strings for all errors that OpenSSL has recorded to \fBbp\fR, thus +emptying the error queue. +.PP +\&\fBERR_print_errors_fp()\fR is the same, except that the output goes to a +\&\fBFILE\fR. +.PP +\&\fBERR_print_errors_cb()\fR is the same, except that the callback function, +\&\fBcb\fR, is called for each error line with the string, length, and userdata +\&\fBu\fR as the callback parameters. +.PP +The error strings will have the following format: +.PP +.Vb 1 +\& [pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message] +.Ve +.PP +\&\fIerror code\fR is an 8 digit hexadecimal number. \fIlibrary name\fR, +\&\fIfunction name\fR and \fIreason string\fR are ASCII text, as is \fIoptional +text message\fR if one was set for the respective error code. +.PP +If there is no text string registered for the given error code, +the error string will contain the numeric code. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_print_errors()\fR and \fBERR_print_errors_fp()\fR return no values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_error_string\fR\|(3), +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_put_error.3 b/static/netbsd/man3/ERR_put_error.3 new file mode 100644 index 00000000..39d8af2c --- /dev/null +++ b/static/netbsd/man3/ERR_put_error.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: ERR_put_error.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_put_error 3" +.TH ERR_put_error 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_raise, ERR_raise_data, +ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, +ERR_add_error_txt, ERR_add_error_mem_bio +\&\- record an error +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void ERR_raise(int lib, int reason); +\& void ERR_raise_data(int lib, int reason, const char *fmt, ...); +\& +\& void ERR_add_error_data(int num, ...); +\& void ERR_add_error_vdata(int num, va_list arg); +\& void ERR_add_error_txt(const char *sep, const char *txt); +\& void ERR_add_error_mem_bio(const char *sep, BIO *bio); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void ERR_put_error(int lib, int func, int reason, const char *file, int line); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_raise()\fR adds a new error to the thread\*(Aqs error queue. The +error occurred in the library \fBlib\fR for the reason given by the +\&\fBreason\fR code. Furthermore, the name of the file, the line, and name +of the function where the error occurred is saved with the error +record. +.PP +\&\fBERR_raise_data()\fR does the same thing as \fBERR_raise()\fR, but also lets the +caller specify additional information as a format string \fBfmt\fR and an +arbitrary number of values, which are processed with \fBBIO_snprintf\fR\|(3). +.PP +\&\fBERR_put_error()\fR adds an error code to the thread\*(Aqs error queue. It +signals that the error of reason code \fBreason\fR occurred in function +\&\fBfunc\fR of library \fBlib\fR, in line number \fBline\fR of \fBfile\fR. +This function is usually called by a macro. +.PP +\&\fBERR_add_error_data()\fR associates the concatenation of its \fBnum\fR string +arguments as additional data with the error code added last. +\&\fBERR_add_error_vdata()\fR is similar except the argument is a \fBva_list\fR. +Multiple calls to these functions append to the current top of the error queue. +The total length of the string data per error is limited to 4096 characters. +.PP +\&\fBERR_add_error_txt()\fR appends the given text string as additional data to the +last error queue entry, after inserting the optional separator string if it is +not NULL and the top error entry does not yet have additional data. +In case the separator is at the end of the text it is not appended to the data. +The \fBsep\fR argument may be for instance "\en" to insert a line break when needed. +If the associated data would become more than 4096 characters long +(which is the limit given above) +it is split over sufficiently many new copies of the last error queue entry. +.PP +\&\fBERR_add_error_mem_bio()\fR is the same as \fBERR_add_error_txt()\fR except that +the text string is taken from the given memory BIO. +It appends \*(Aq\e0\*(Aq to the BIO contents if not already NUL\-terminated. +.PP +\&\fBERR_load_strings\fR\|(3) can be used to register +error strings so that the application can a generate human\-readable +error messages for the error code. +.SS "Reporting errors" +.IX Subsection "Reporting errors" +\fIOpenSSL library reports\fR +.IX Subsection "OpenSSL library reports" +.PP +Each OpenSSL sub\-library has library code \fBERR_LIB_XXX\fR and has its own set +of reason codes \fBXXX_R_...\fR. These are both passed in combination to +\&\fBERR_raise()\fR and \fBERR_raise_data()\fR, and the combination ultimately produces +the correct error text for the reported error. +.PP +All these macros and the numbers they have as values are specific to +OpenSSL\*(Aqs libraries. OpenSSL reason codes normally consist of textual error +descriptions. For example, the function \fBssl3_read_bytes()\fR reports a +"handshake failure" as follows: +.PP +.Vb 1 +\& ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE); +.Ve +.PP +There are two exceptions: +.IP \fBERR_LIB_SYS\fR 4 +.IX Item "ERR_LIB_SYS" +This "library code" indicates that a system error is being reported. In +this case, the reason code given to \fBERR_raise()\fR and \fBERR_raise_data()\fR \fImust\fR +be \fBerrno\fR\|(3). +.Sp +.Vb 1 +\& ERR_raise(ERR_LIB_SYS, errno); +.Ve +.IP \fBERR_R_XXX\fR 4 +.IX Item "ERR_R_XXX" +This set of error codes is considered global, and may be used in combination +with any sub\-library code. +.Sp +.Vb 1 +\& ERR_raise(ERR_LIB_RSA, ERR_R_PASSED_INVALID_ARGUMENT); +.Ve +.PP +\fIOther pieces of software\fR +.IX Subsection "Other pieces of software" +.PP +Other pieces of software that may want to use OpenSSL\*(Aqs error reporting +system, such as engines or applications, must normally get their own +numbers. +.IP \(bu 4 +To get a "library" code, call \fBERR_get_next_error_library\fR\|(3); this gives +the calling code a dynamic number, usable for the duration of the process. +.IP \(bu 4 +Reason codes for each such "library" are determined or generated by the +authors of that code. They must be numbers in the range 1 to 524287 (in +other words, they must be nonzero unsigned 18 bit integers). +.PP +The exceptions mentioned in "OpenSSL library reports" above are valid for +other pieces of software, i.e. they may use \fBERR_LIB_SYS\fR to report system +errors: +.PP +.Vb 1 +\& ERR_raise(ERR_LIB_SYS, errno); +.Ve +.PP +\&... and they may use \fBERR_R_XXX\fR macros together with their own "library" +code. +.PP +.Vb 1 +\& int app_lib_code = ERR_get_next_error_library(); +\& +\& /* ... */ +\& +\& ERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT); +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_raise()\fR, \fBERR_raise_data()\fR, \fBERR_put_error()\fR, +\&\fBERR_add_error_data()\fR, \fBERR_add_error_vdata()\fR +\&\fBERR_add_error_txt()\fR, and \fBERR_add_error_mem_bio()\fR +return no values. +.SH NOTES +.IX Header "NOTES" +\&\fBERR_raise()\fR, \fBERR_raise()\fR and \fBERR_put_error()\fR are implemented as macros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_load_strings\fR\|(3), \fBERR_get_next_error_library\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +ERR_raise, ERR_raise_data, \fBERR_add_error_txt()\fR and \fBERR_add_error_mem_bio()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_remove_state.3 b/static/netbsd/man3/ERR_remove_state.3 new file mode 100644 index 00000000..73710fba --- /dev/null +++ b/static/netbsd/man3/ERR_remove_state.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: ERR_remove_state.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_remove_state 3" +.TH ERR_remove_state 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_remove_thread_state, ERR_remove_state \- DEPRECATED +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The following function has been deprecated since OpenSSL 1.0.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void ERR_remove_state(unsigned long tid); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void ERR_remove_thread_state(void *tid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_remove_state()\fR frees the error queue associated with the specified +thread, identified by \fBtid\fR. +\&\fBERR_remove_thread_state()\fR does the same thing, except the identifier is +an opaque pointer. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_remove_state()\fR and \fBERR_remove_thread_state()\fR return no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +L\fBOPENSSL_init_crypto\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBERR_remove_state()\fR was deprecated in OpenSSL 1.0.0 and +\&\fBERR_remove_thread_state()\fR was deprecated in OpenSSL 1.1.0; these functions +and should not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/ERR_set_mark.3 b/static/netbsd/man3/ERR_set_mark.3 new file mode 100644 index 00000000..814a23b5 --- /dev/null +++ b/static/netbsd/man3/ERR_set_mark.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: ERR_set_mark.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "ERR_set_mark 3" +.TH ERR_set_mark 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ERR_set_mark, ERR_clear_last_mark, ERR_pop_to_mark, ERR_count_to_mark, ERR_pop \- +set mark, clear mark, pop errors until mark and pop last error +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int ERR_set_mark(void); +\& int ERR_pop_to_mark(void); +\& int ERR_clear_last_mark(void); +\& int ERR_count_to_mark(void); +\& int ERR_pop(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBERR_set_mark()\fR sets a mark on the current topmost error record if there +is one. +.PP +\&\fBERR_pop_to_mark()\fR will pop the top of the error stack until a mark is found. +The mark is then removed. If there is no mark, the whole stack is removed. +.PP +\&\fBERR_clear_last_mark()\fR removes the last mark added if there is one. +.PP +\&\fBERR_count_to_mark()\fR returns the number of entries on the error stack above the +most recently marked entry, not including that entry. If there is no mark in the +error stack, the number of entries in the error stack is returned. +.PP +\&\fBERR_pop()\fR unconditionally pops a single error entry from the top of the error +stack (which is the entry obtainable via \fBERR_peek_last_error\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBERR_set_mark()\fR returns 0 if the error stack is empty, otherwise 1. +.PP +\&\fBERR_clear_last_mark()\fR and \fBERR_pop_to_mark()\fR return 0 if there was no mark in the +error stack, which implies that the stack became empty, otherwise 1. +.PP +\&\fBERR_count_to_mark()\fR returns the number of error stack entries found above the +most recent mark, if any, or the total number of error stack entries. +.PP +\&\fBERR_pop()\fR returns 1 if an error was popped or 0 if the error stack was empty. +.SH HISTORY +.IX Header "HISTORY" +\&\fBERR_count_to_mark()\fR was added in OpenSSL 3.2. +\&\fBERR_pop()\fR was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2003\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_ASYM_CIPHER_free.3 b/static/netbsd/man3/EVP_ASYM_CIPHER_free.3 new file mode 100644 index 00000000..019a0466 --- /dev/null +++ b/static/netbsd/man3/EVP_ASYM_CIPHER_free.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: EVP_ASYM_CIPHER_free.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_ASYM_CIPHER_free 3" +.TH EVP_ASYM_CIPHER_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref, +EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_get0_provider, +EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all, +EVP_ASYM_CIPHER_get0_name, EVP_ASYM_CIPHER_get0_description, +EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params +\&\- Functions to manage EVP_ASYM_CIPHER algorithm objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& void EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher); +\& int EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher); +\& const char *EVP_ASYM_CIPHER_get0_name(const EVP_ASYM_CIPHER *cipher); +\& int EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name); +\& OSSL_PROVIDER *EVP_ASYM_CIPHER_get0_provider(const EVP_ASYM_CIPHER *cipher); +\& void EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_ASYM_CIPHER *cipher, +\& void *arg), +\& void *arg); +\& int EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_ASYM_CIPHER_get0_description(const EVP_ASYM_CIPHER *cipher); +\& const OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip); +\& const OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_ASYM_CIPHER_fetch()\fR fetches the implementation for the given +\&\fBalgorithm\fR from any provider offering it, within the criteria given +by the \fBproperties\fR and in the scope of the given library context \fBctx\fR (see +\&\fBOSSL_LIB_CTX\fR\|(3)). The algorithm will be one offering functions for performing +asymmetric cipher related tasks such as asymmetric encryption and decryption. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +The returned value must eventually be freed with \fBEVP_ASYM_CIPHER_free()\fR. +.PP +\&\fBEVP_ASYM_CIPHER_free()\fR decrements the reference count for the \fBEVP_ASYM_CIPHER\fR +structure. Typically this structure will have been obtained from an earlier call +to \fBEVP_ASYM_CIPHER_fetch()\fR. If the reference count drops to 0 then the +structure is freed. If the argument is NULL, nothing is done. +.PP +\&\fBEVP_ASYM_CIPHER_up_ref()\fR increments the reference count for an +\&\fBEVP_ASYM_CIPHER\fR structure. +.PP +\&\fBEVP_ASYM_CIPHER_is_a()\fR returns 1 if \fIcipher\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR, otherwise 0. +.PP +\&\fBEVP_ASYM_CIPHER_get0_provider()\fR returns the provider that \fIcipher\fR was +fetched from. +.PP +\&\fBEVP_ASYM_CIPHER_do_all_provided()\fR traverses all EVP_ASYM_CIPHERs implemented by +all activated providers in the given library context \fIlibctx\fR, and for each of +the implementations, calls the given function \fIfn\fR with the implementation +method and the given \fIarg\fR as argument. +.PP +\&\fBEVP_ASYM_CIPHER_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIcipher\fR. Note that the \fIcipher\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIcipher\fR object and should not be freed by the caller. +.PP +\&\fBEVP_ASYM_CIPHER_names_do_all()\fR traverses all names for \fIcipher\fR, and calls +\&\fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_ASYM_CIPHER_get0_description()\fR returns a description of the \fIcipher\fR, +meant for display and human consumption. The description is at the +discretion of the \fIcipher\fR implementation. +.PP +\&\fBEVP_ASYM_CIPHER_gettable_ctx_params()\fR and \fBEVP_ASYM_CIPHER_settable_ctx_params()\fR +return a constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +parameters that can be retrieved or set by a key encryption algorithm using +\&\fBEVP_PKEY_CTX_get_params\fR\|(3) and \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_ASYM_CIPHER_fetch()\fR returns a pointer to an \fBEVP_ASYM_CIPHER\fR for success +or \fBNULL\fR for failure. +.PP +\&\fBEVP_ASYM_CIPHER_up_ref()\fR returns 1 for success or 0 otherwise. +.PP +\&\fBEVP_ASYM_CIPHER_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_ASYM_CIPHER_gettable_ctx_params()\fR and \fBEVP_ASYM_CIPHER_settable_ctx_params()\fR +return a constant \fBOSSL_PARAM\fR\|(3) array or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), \fBOSSL_PROVIDER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_BytesToKey.3 b/static/netbsd/man3/EVP_BytesToKey.3 new file mode 100644 index 00000000..373e403d --- /dev/null +++ b/static/netbsd/man3/EVP_BytesToKey.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: EVP_BytesToKey.3,v 1.5 2026/04/08 17:06:42 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_BytesToKey 3" +.TH EVP_BytesToKey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_BytesToKey \- password based encryption routine +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, +\& const unsigned char *salt, +\& const unsigned char *data, int datal, int count, +\& unsigned char *key, unsigned char *iv); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_BytesToKey()\fR derives a key and IV from various parameters. \fBtype\fR is +the cipher to derive the key and IV for. \fBmd\fR is the message digest to use. +The \fBsalt\fR parameter is used as a salt in the derivation: it should point to +an 8 byte buffer or NULL if no salt is used. \fBdata\fR is a buffer containing +\&\fBdatal\fR bytes which is used to derive the keying data. \fBcount\fR is the +iteration count to use. The derived key and IV will be written to \fBkey\fR +and \fBiv\fR respectively. +.SH NOTES +.IX Header "NOTES" +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the \fBdata\fR parameter. +.PP +Increasing the \fBcount\fR parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +If the total key and IV length is less than the digest length and +\&\fBMD5\fR is used then the derivation algorithm is compatible with PKCS#5 v1.5 +otherwise a non standard extension is used to derive the extra data. +.PP +Newer applications should use a more modern algorithm such as PBKDF2 as +defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. +.SH "KEY DERIVATION ALGORITHM" +.IX Header "KEY DERIVATION ALGORITHM" +The key and IV is derived by concatenating D_1, D_2, etc until +enough data is available for the key and IV. D_i is defined as: +.PP +.Vb 1 +\& D_i = HASH^count(D_(i\-1) || data || salt) +.Ve +.PP +where || denotes concatenation, D_0 is empty, HASH is the digest +algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) +is HASH(HASH(data)) and so on. +.PP +The initial bytes are used for the key and the subsequent bytes for +the IV. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If \fBdata\fR is NULL, then \fBEVP_BytesToKey()\fR returns the number of bytes +needed to store the derived key. +Otherwise, \fBEVP_BytesToKey()\fR returns the size of the derived key in bytes, +or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), \fBRAND_bytes\fR\|(3), +\&\fBPKCS5_PBKDF2_HMAC\fR\|(3), +\&\fBEVP_EncryptInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_block_size.3 b/static/netbsd/man3/EVP_CIPHER_CTX_block_size.3 new file mode 100644 index 00000000..0da9c7a0 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_block_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_block_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_cipher.3 b/static/netbsd/man3/EVP_CIPHER_CTX_cipher.3 new file mode 100644 index 00000000..81aea71e --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_cipher.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_cipher.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_cleanup.3 b/static/netbsd/man3/EVP_CIPHER_CTX_cleanup.3 new file mode 100644 index 00000000..c4d5761a --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_cleanup.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_cleanup.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_ctrl.3 b/static/netbsd/man3/EVP_CIPHER_CTX_ctrl.3 new file mode 100644 index 00000000..b49a7f23 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_ctrl.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_ctrl.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_core.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_flags.3 b/static/netbsd/man3/EVP_CIPHER_CTX_flags.3 new file mode 100644 index 00000000..ea016649 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_flags.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_get_app_data.3 b/static/netbsd/man3/EVP_CIPHER_CTX_get_app_data.3 new file mode 100644 index 00000000..b07f47f8 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_get_app_data.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: EVP_CIPHER_CTX_get_app_data.3,v 1.2 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER_CTX_get_app_data 3" +.TH EVP_CIPHER_CTX_get_app_data 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data \- Routines to +inspect and modify application data related to EVP_CIPHER_CTX +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); +\& void EVP_CIPHER_CTX_set_app_data(EVP_CIPHER_CTX *ctx, void *data); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions \fBEVP_CIPHER_CTX_set_app_data()\fR and \fBEVP_CIPHER_CTX_get_app_data()\fR +associate an opaque, application\-defined pointer with an EVP_CIPHER_CTX object. +.PP +This pointer is not interpreted by the library and is reserved entirely for use +by the application. It may be used to store arbitrary context or state that +needs to be accessible wherever the corresponding EVP_CIPHER_CTX is available. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBEVP_CIPHER_CTX_get_app_data()\fR function returns a opaque pointer to the +current application data for the EVP_CIPHER_CTX. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 b/static/netbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 new file mode 100644 index 00000000..baf51602 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_get_cipher_data.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: EVP_CIPHER_CTX_get_cipher_data.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER_CTX_get_cipher_data 3" +.TH EVP_CIPHER_CTX_get_cipher_data 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data \- Routines to +inspect and modify EVP_CIPHER_CTX objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx); +\& void *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_CIPHER_CTX_get_cipher_data()\fR function returns a pointer to the cipher +data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the +particular implementation of the cipher. For example this data can be used by +engines to store engine specific information. The data is automatically +allocated and freed by OpenSSL, so applications and engines should not normally +free this directly (but see below). +.PP +The \fBEVP_CIPHER_CTX_set_cipher_data()\fR function allows an application or engine to +replace the cipher data with new data. A pointer to any existing cipher data is +returned from this function. If the old data is no longer required then it +should be freed through a call to \fBOPENSSL_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBEVP_CIPHER_CTX_get_cipher_data()\fR function returns a pointer to the current +cipher data for the EVP_CIPHER_CTX. +.PP +The \fBEVP_CIPHER_CTX_set_cipher_data()\fR function returns a pointer to the old +cipher data for the EVP_CIPHER_CTX. +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_CIPHER_CTX_get_cipher_data()\fR and \fBEVP_CIPHER_CTX_set_cipher_data()\fR +functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_get_original_iv.3 b/static/netbsd/man3/EVP_CIPHER_CTX_get_original_iv.3 new file mode 100644 index 00000000..cea7a8c1 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_get_original_iv.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: EVP_CIPHER_CTX_get_original_iv.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER_CTX_get_original_iv 3" +.TH EVP_CIPHER_CTX_get_original_iv 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv, +EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv, +EVP_CIPHER_CTX_iv_noconst \- Routines to inspect EVP_CIPHER_CTX IV data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len); +\& int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx); +\& const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx); +\& unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_CIPHER_CTX_get_original_iv()\fR and \fBEVP_CIPHER_CTX_get_updated_iv()\fR copy +initialization vector (IV) information from the \fBEVP_CIPHER_CTX\fR into the +caller\-supplied buffer. \fBEVP_CIPHER_CTX_get_iv_length\fR\|(3) can be used to +determine an appropriate buffer size, and if the supplied buffer is too small, +an error will be returned (and no data copied). +\&\fBEVP_CIPHER_CTX_get_original_iv()\fR accesses the ("original") IV that was +supplied when the \fBEVP_CIPHER_CTX\fR was initialized, and +\&\fBEVP_CIPHER_CTX_get_updated_iv()\fR accesses the current "IV state" +of the cipher, which is updated during cipher operation for certain cipher modes +(e.g., CBC and OFB). +.PP +The functions \fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR, and +\&\fBEVP_CIPHER_CTX_iv_noconst()\fR are deprecated functions that provide similar (at +a conceptual level) functionality. \fBEVP_CIPHER_CTX_iv()\fR returns a pointer to +the beginning of the "IV state" as maintained internally in the +\&\fBEVP_CIPHER_CTX\fR; \fBEVP_CIPHER_CTX_original_iv()\fR returns a pointer to the +beginning of the ("original") IV, as maintained by the \fBEVP_CIPHER_CTX\fR, that +was provided when the \fBEVP_CIPHER_CTX\fR was initialized; and +\&\fBEVP_CIPHER_CTX_get_iv_noconst()\fR is the same as \fBEVP_CIPHER_CTX_iv()\fR but has a +different return type for the pointer. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_CIPHER_CTX_get_original_iv()\fR and \fBEVP_CIPHER_CTX_get_updated_iv()\fR return 1 +on success and 0 on failure. +.PP +The functions \fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR, and +\&\fBEVP_CIPHER_CTX_iv_noconst()\fR return a pointer to an IV as an array of bytes on +success, and NULL on failure. +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_CIPHER_CTX_get_original_iv()\fR and \fBEVP_CIPHER_CTX_get_updated_iv()\fR were added +in OpenSSL 3.0.0. +.PP +\&\fBEVP_CIPHER_CTX_iv()\fR, \fBEVP_CIPHER_CTX_original_iv()\fR, and +\&\fBEVP_CIPHER_CTX_iv_noconst()\fR were added in OpenSSL 1.1.0, and were deprecated +in OpenSSL 3.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_init.3 b/static/netbsd/man3/EVP_CIPHER_CTX_init.3 new file mode 100644 index 00000000..faeaebd5 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_iv_length.3 b/static/netbsd/man3/EVP_CIPHER_CTX_iv_length.3 new file mode 100644 index 00000000..9804f5a8 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_iv_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_iv_length.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_key_length.3 b/static/netbsd/man3/EVP_CIPHER_CTX_key_length.3 new file mode 100644 index 00000000..659cad9e --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_key_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_key_length.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_mode.3 b/static/netbsd/man3/EVP_CIPHER_CTX_mode.3 new file mode 100644 index 00000000..31f0e986 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_mode.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_mode.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_rand_key.3 b/static/netbsd/man3/EVP_CIPHER_CTX_rand_key.3 new file mode 100644 index 00000000..a1a55ec0 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_rand_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_rand_key.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_core.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_set_app_data.3 b/static/netbsd/man3/EVP_CIPHER_CTX_set_app_data.3 new file mode 100644 index 00000000..af1ffead --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_set_app_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_set_app_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_CTX_set_key_length.3 b/static/netbsd/man3/EVP_CIPHER_CTX_set_key_length.3 new file mode 100644 index 00000000..1e2b0d4c --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_CTX_set_key_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_CTX_set_key_length.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_block_size.3 b/static/netbsd/man3/EVP_CIPHER_block_size.3 new file mode 100644 index 00000000..1887f8b7 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_block_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_block_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_iv_length.3 b/static/netbsd/man3/EVP_CIPHER_iv_length.3 new file mode 100644 index 00000000..bc9c385c --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_iv_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_iv_length.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_key_length.3 b/static/netbsd/man3/EVP_CIPHER_key_length.3 new file mode 100644 index 00000000..4ac93b55 --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_key_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CIPHER_key_length.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CIPHER_meth_new.3 b/static/netbsd/man3/EVP_CIPHER_meth_new.3 new file mode 100644 index 00000000..525367ae --- /dev/null +++ b/static/netbsd/man3/EVP_CIPHER_meth_new.3 @@ -0,0 +1,298 @@ +.\" $NetBSD: EVP_CIPHER_meth_new.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_CIPHER_meth_new 3" +.TH EVP_CIPHER_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, +EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, +EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, +EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, +EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, +EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, +EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, +EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, +EVP_CIPHER_meth_get_ctrl +\&\- Routines to build up EVP_CIPHER methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); +\& EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); +\& void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); +\& +\& int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); +\& int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); +\& int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); +\& int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, +\& int (*init)(EVP_CIPHER_CTX *ctx, +\& const unsigned char *key, +\& const unsigned char *iv, +\& int enc)); +\& int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, +\& int (*do_cipher)(EVP_CIPHER_CTX *ctx, +\& unsigned char *out, +\& const unsigned char *in, +\& size_t inl)); +\& int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, +\& int (*cleanup)(EVP_CIPHER_CTX *)); +\& int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, +\& int (*set_asn1_parameters)(EVP_CIPHER_CTX *, +\& ASN1_TYPE *)); +\& int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, +\& int (*get_asn1_parameters)(EVP_CIPHER_CTX *, +\& ASN1_TYPE *)); +\& int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, +\& int (*ctrl)(EVP_CIPHER_CTX *, int type, +\& int arg, void *ptr)); +\& +\& int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, +\& const unsigned char *key, +\& const unsigned char *iv, +\& int enc); +\& int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, +\& unsigned char *out, +\& const unsigned char *in, +\& size_t inl); +\& int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); +\& int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, +\& ASN1_TYPE *); +\& int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, +\& ASN1_TYPE *); +\& int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, +\& int type, int arg, +\& void *ptr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +The \fBEVP_CIPHER\fR type is a structure for symmetric cipher method +implementation. +.PP +\&\fBEVP_CIPHER_meth_new()\fR creates a new \fBEVP_CIPHER\fR structure. +.PP +\&\fBEVP_CIPHER_meth_dup()\fR creates a copy of \fBcipher\fR. +.PP +\&\fBEVP_CIPHER_meth_free()\fR destroys a \fBEVP_CIPHER\fR structure. +If the argument is NULL, nothing is done. +.PP +\&\fBEVP_CIPHER_meth_set_iv_length()\fR sets the length of the IV. +This is only needed when the implemented cipher mode requires it. +.PP +\&\fBEVP_CIPHER_meth_set_flags()\fR sets the flags to describe optional +behaviours in the particular \fBcipher\fR. +With the exception of cipher modes, of which only one may be present, +several flags can be or\*(Aqd together. +The available flags are: +.IP "EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE, EVP_CIPH_SIV_MODE" 4 +.IX Item "EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE, EVP_CIPH_SIV_MODE" +The cipher mode. +.IP EVP_CIPH_VARIABLE_LENGTH 4 +.IX Item "EVP_CIPH_VARIABLE_LENGTH" +This cipher is of variable length. +.IP EVP_CIPH_CUSTOM_IV 4 +.IX Item "EVP_CIPH_CUSTOM_IV" +Storing and initialising the IV is left entirely to the +implementation. +.IP EVP_CIPH_ALWAYS_CALL_INIT 4 +.IX Item "EVP_CIPH_ALWAYS_CALL_INIT" +Set this if the implementation\*(Aqs \fBinit()\fR function should be called even +if \fBkey\fR is \fBNULL\fR. +.IP EVP_CIPH_CTRL_INIT 4 +.IX Item "EVP_CIPH_CTRL_INIT" +Set this to have the implementation\*(Aqs \fBctrl()\fR function called with +command code \fBEVP_CTRL_INIT\fR early in its setup. +.IP EVP_CIPH_CUSTOM_KEY_LENGTH 4 +.IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH" +Checking and setting the key length after creating the \fBEVP_CIPHER\fR +is left to the implementation. +Whenever someone uses \fBEVP_CIPHER_CTX_set_key_length()\fR on a +\&\fBEVP_CIPHER\fR with this flag set, the implementation\*(Aqs \fBctrl()\fR function +will be called with the control code \fBEVP_CTRL_SET_KEY_LENGTH\fR and +the key length in \fBarg\fR. +.IP EVP_CIPH_NO_PADDING 4 +.IX Item "EVP_CIPH_NO_PADDING" +Don\*(Aqt use standard block padding. +.IP EVP_CIPH_RAND_KEY 4 +.IX Item "EVP_CIPH_RAND_KEY" +Making a key with random content is left to the implementation. +This is done by calling the implementation\*(Aqs \fBctrl()\fR function with the +control code \fBEVP_CTRL_RAND_KEY\fR and the pointer to the key memory +storage in \fBptr\fR. +.IP EVP_CIPH_CUSTOM_COPY 4 +.IX Item "EVP_CIPH_CUSTOM_COPY" +Set this to have the implementation\*(Aqs \fBctrl()\fR function called with +command code \fBEVP_CTRL_COPY\fR at the end of \fBEVP_CIPHER_CTX_copy()\fR. +The intended use is for further things to deal with after the +implementation specific data block has been copied. +The destination \fBEVP_CIPHER_CTX\fR is passed to the control with the +\&\fBptr\fR parameter. +The implementation specific data block is reached with +\&\fBEVP_CIPHER_CTX_get_cipher_data()\fR. +.IP EVP_CIPH_FLAG_DEFAULT_ASN1 4 +.IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1" +Use the default EVP routines to pass IV to and from ASN.1. +.IP EVP_CIPH_FLAG_LENGTH_BITS 4 +.IX Item "EVP_CIPH_FLAG_LENGTH_BITS" +Signals that the length of the input buffer for encryption / +decryption is to be understood as the number of bits instead of +bytes for this implementation. +This is only useful for CFB1 ciphers. +.IP EVP_CIPH_FLAG_CTS 4 +.IX Item "EVP_CIPH_FLAG_CTS" +Indicates that the cipher uses ciphertext stealing. This is currently +used to indicate that the cipher is a one shot that only allows a single call to +\&\fBEVP_CipherUpdate()\fR. +.IP EVP_CIPH_FLAG_CUSTOM_CIPHER 4 +.IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER" +This indicates that the implementation takes care of everything, +including padding, buffering and finalization. +The EVP routines will simply give them control and do nothing more. +.IP EVP_CIPH_FLAG_AEAD_CIPHER 4 +.IX Item "EVP_CIPH_FLAG_AEAD_CIPHER" +This indicates that this is an AEAD cipher implementation. +.IP EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK 4 +.IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK" +Allow interleaving of crypto blocks, a particular optimization only applicable +to certain TLS ciphers. +.PP +\&\fBEVP_CIPHER_meth_set_impl_ctx_size()\fR sets the size of the EVP_CIPHER\*(Aqs +implementation context so that it can be automatically allocated. +.PP +\&\fBEVP_CIPHER_meth_set_init()\fR sets the cipher init function for +\&\fBcipher\fR. +The cipher init function is called by \fBEVP_CipherInit()\fR, +\&\fBEVP_CipherInit_ex()\fR, \fBEVP_EncryptInit()\fR, \fBEVP_EncryptInit_ex()\fR, +\&\fBEVP_DecryptInit()\fR, \fBEVP_DecryptInit_ex()\fR. +.PP +\&\fBEVP_CIPHER_meth_set_do_cipher()\fR sets the cipher function for +\&\fBcipher\fR. +The cipher function is called by \fBEVP_CipherUpdate()\fR, +\&\fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR, \fBEVP_CipherFinal()\fR, +\&\fBEVP_EncryptFinal()\fR, \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal()\fR and +\&\fBEVP_DecryptFinal_ex()\fR. +.PP +\&\fBEVP_CIPHER_meth_set_cleanup()\fR sets the function for \fBcipher\fR to do +extra cleanup before the method\*(Aqs private data structure is cleaned +out and freed. +Note that the cleanup function is passed a \fBEVP_CIPHER_CTX *\fR, the +private data structure is then available with +\&\fBEVP_CIPHER_CTX_get_cipher_data()\fR. +This cleanup function is called by \fBEVP_CIPHER_CTX_reset()\fR and +\&\fBEVP_CIPHER_CTX_free()\fR. +.PP +\&\fBEVP_CIPHER_meth_set_set_asn1_params()\fR sets the function for \fBcipher\fR +to set the AlgorithmIdentifier "parameter" based on the passed cipher. +This function is called by \fBEVP_CIPHER_param_to_asn1()\fR. +\&\fBEVP_CIPHER_meth_set_get_asn1_params()\fR sets the function for \fBcipher\fR +that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier +"parameter". +Both these functions are needed when there is a need for custom data +(more or other than the cipher IV). +They are called by \fBEVP_CIPHER_param_to_asn1()\fR and +\&\fBEVP_CIPHER_asn1_to_param()\fR respectively if defined. +.PP +\&\fBEVP_CIPHER_meth_set_ctrl()\fR sets the control function for \fBcipher\fR. +.PP +\&\fBEVP_CIPHER_meth_get_init()\fR, \fBEVP_CIPHER_meth_get_do_cipher()\fR, +\&\fBEVP_CIPHER_meth_get_cleanup()\fR, \fBEVP_CIPHER_meth_get_set_asn1_params()\fR, +\&\fBEVP_CIPHER_meth_get_get_asn1_params()\fR and \fBEVP_CIPHER_meth_get_ctrl()\fR +are all used to retrieve the method data given with the +EVP_CIPHER_meth_set_*() functions above. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_CIPHER_meth_new()\fR and \fBEVP_CIPHER_meth_dup()\fR return a pointer to a +newly created \fBEVP_CIPHER\fR, or NULL on failure. +All EVP_CIPHER_meth_set_*() functions return 1. +All EVP_CIPHER_meth_get_*() functions return pointers to their +respective \fBcipher\fR function. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The functions described here were added in OpenSSL 1.1.0. +The \fBEVP_CIPHER\fR structure created with these functions became reference +counted in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_CipherFinal_ex.3 b/static/netbsd/man3/EVP_CipherFinal_ex.3 new file mode 100644 index 00000000..b3724c53 --- /dev/null +++ b/static/netbsd/man3/EVP_CipherFinal_ex.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CipherFinal_ex.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CipherInit_ex.3 b/static/netbsd/man3/EVP_CipherInit_ex.3 new file mode 100644 index 00000000..51f4adfd --- /dev/null +++ b/static/netbsd/man3/EVP_CipherInit_ex.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CipherInit_ex.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_CipherUpdate.3 b/static/netbsd/man3/EVP_CipherUpdate.3 new file mode 100644 index 00000000..b933f45a --- /dev/null +++ b/static/netbsd/man3/EVP_CipherUpdate.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_CipherUpdate.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_Digest.3 b/static/netbsd/man3/EVP_Digest.3 new file mode 100644 index 00000000..808c0509 --- /dev/null +++ b/static/netbsd/man3/EVP_Digest.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_Digest.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_DigestFinal_ex.3 b/static/netbsd/man3/EVP_DigestFinal_ex.3 new file mode 100644 index 00000000..9040eb06 --- /dev/null +++ b/static/netbsd/man3/EVP_DigestFinal_ex.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_DigestFinal_ex.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_DigestInit.3 b/static/netbsd/man3/EVP_DigestInit.3 new file mode 100644 index 00000000..4e78e7fc --- /dev/null +++ b/static/netbsd/man3/EVP_DigestInit.3 @@ -0,0 +1,807 @@ +.\" $NetBSD: EVP_DigestInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_DigestInit 3" +.TH EVP_DigestInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, +EVP_MD_get_params, EVP_MD_gettable_params, +EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, +EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, +EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, +EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, +EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, +EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, +EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, +EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, +EVP_DigestSqueeze, +EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, +EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, +EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, +EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, +EVP_MD_CTX_get_type, EVP_MD_CTX_get_size_ex, EVP_MD_CTX_get_block_size, +EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, +EVP_md_null, +EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, +EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, +EVP_MD_do_all_provided, +EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, +EVP_MD_block_size, EVP_MD_flags, EVP_MD_xof, +EVP_MD_CTX_size, EVP_MD_CTX_get_size, EVP_MD_CTX_block_size, +EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data +\&\- EVP digest routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& int EVP_MD_up_ref(EVP_MD *md); +\& void EVP_MD_free(EVP_MD *md); +\& int EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest); +\& EVP_MD_CTX *EVP_MD_CTX_new(void); +\& int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); +\& void EVP_MD_CTX_free(EVP_MD_CTX *ctx); +\& void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2); +\& int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]); +\& int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md); +\& const OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md); +\& const OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx); +\& const OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx); +\& void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags); +\& void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); +\& int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); +\& +\& int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq, +\& const void *data, size_t datalen, +\& unsigned char *md, size_t *mdlen); +\& int EVP_Digest(const void *data, size_t count, unsigned char *md, +\& unsigned int *size, const EVP_MD *type, ENGINE *impl); +\& int EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type, +\& const OSSL_PARAM params[]); +\& int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); +\& int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); +\& int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); +\& int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); +\& int EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); +\& +\& EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in); +\& int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); +\& +\& int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); +\& int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); +\& +\& int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); +\& +\& const char *EVP_MD_get0_name(const EVP_MD *md); +\& const char *EVP_MD_get0_description(const EVP_MD *md); +\& int EVP_MD_is_a(const EVP_MD *md, const char *name); +\& int EVP_MD_names_do_all(const EVP_MD *md, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const OSSL_PROVIDER *EVP_MD_get0_provider(const EVP_MD *md); +\& int EVP_MD_get_type(const EVP_MD *md); +\& int EVP_MD_get_pkey_type(const EVP_MD *md); +\& int EVP_MD_get_size(const EVP_MD *md); +\& int EVP_MD_get_block_size(const EVP_MD *md); +\& unsigned long EVP_MD_get_flags(const EVP_MD *md); +\& int EVP_MD_xof(const EVP_MD *md); +\& +\& const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx); +\& EVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx); +\& const char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx); +\& int EVP_MD_CTX_get_size_ex(const EVP_MD_CTX *ctx); +\& int EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx); +\& int EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx); +\& void *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx); +\& +\& const EVP_MD *EVP_md_null(void); +\& +\& const EVP_MD *EVP_get_digestbyname(const char *name); +\& const EVP_MD *EVP_get_digestbynid(int type); +\& const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); +\& +\& EVP_PKEY_CTX *EVP_MD_CTX_get_pkey_ctx(const EVP_MD_CTX *ctx); +\& void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); +\& +\& void EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_MD *mac, void *arg), +\& void *arg); +\& +\& #define EVP_MD_type EVP_MD_get_type +\& #define EVP_MD_nid EVP_MD_get_type +\& #define EVP_MD_name EVP_MD_get0_name +\& #define EVP_MD_pkey_type EVP_MD_get_pkey_type +\& #define EVP_MD_size EVP_MD_get_size +\& #define EVP_MD_block_size EVP_MD_get_block_size +\& #define EVP_MD_flags EVP_MD_get_flags +\& #define EVP_MD_CTX_get_size EVP_MD_CTX_get_size_ex +\& #define EVP_MD_CTX_size EVP_MD_CTX_get_size_ex +\& #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size +\& #define EVP_MD_CTX_type EVP_MD_CTX_get_type +\& #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx +\& #define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); +\& +\& int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx, +\& const void *data, size_t count); +\& +\& void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx, +\& int (*update)(EVP_MD_CTX *ctx, +\& const void *data, size_t count)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP digest routines are a high\-level interface to message digests, and +Extendable Output Functions (XOF). +.PP +The \fBEVP_MD\fR type is a structure for digest method implementation. +.PP +Each Message digest algorithm (such as SHA256) produces a fixed size output +length which is returned when \fBEVP_DigestFinal_ex()\fR is called. +Extendable Output Functions (XOF) such as SHAKE256 have a variable sized output +length \fIoutlen\fR which can be used with either \fBEVP_DigestFinalXOF()\fR or +\&\fBEVP_DigestSqueeze()\fR. \fBEVP_DigestFinal_ex()\fR may also be used for an XOF, but the +"xoflen" must be set beforehand (See "PARAMETERS"). +Note that \fBEVP_MD_get_size()\fR and \fBEVP_MD_CTX_get_size_ex()\fR behave differently for +an XOF. +.IP \fBEVP_MD_fetch()\fR 4 +.IX Item "EVP_MD_fetch()" +Fetches the digest implementation for the given \fIalgorithm\fR from any +provider offering it, within the criteria given by the \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.Sp +The returned value must eventually be freed with \fBEVP_MD_free()\fR. +.Sp +Fetched \fBEVP_MD\fR structures are reference counted. +.IP \fBEVP_MD_up_ref()\fR 4 +.IX Item "EVP_MD_up_ref()" +Increments the reference count for an \fBEVP_MD\fR structure. +.IP \fBEVP_MD_free()\fR 4 +.IX Item "EVP_MD_free()" +Decrements the reference count for the fetched \fBEVP_MD\fR structure. +If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. +.IP \fBEVP_MD_CTX_new()\fR 4 +.IX Item "EVP_MD_CTX_new()" +Allocates and returns a digest context. +.IP \fBEVP_MD_CTX_reset()\fR 4 +.IX Item "EVP_MD_CTX_reset()" +Resets the digest context \fIctx\fR. This can be used to reuse an already +existing context. +.IP \fBEVP_MD_CTX_free()\fR 4 +.IX Item "EVP_MD_CTX_free()" +Cleans up digest context \fIctx\fR and frees up the space allocated to it. +If the argument is NULL, nothing is done. +.IP \fBEVP_MD_CTX_ctrl()\fR 4 +.IX Item "EVP_MD_CTX_ctrl()" +\&\fIThis is a legacy method. \fR\f(BIEVP_MD_CTX_set_params()\fR\fI and \fR\f(BIEVP_MD_CTX_get_params()\fR\fI +is the mechanism that should be used to set and get parameters that are used by +providers.\fR +.Sp +Performs digest\-specific control actions on context \fIctx\fR. The control command +is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR. +\&\fBEVP_MD_CTX_ctrl()\fR must be called after \fBEVP_DigestInit_ex2()\fR. Other restrictions +may apply depending on the control type and digest implementation. +.Sp +If this function happens to be used with a fetched \fBEVP_MD\fR, it will +translate the controls that are known to OpenSSL into \fBOSSL_PARAM\fR\|(3) +parameters with keys defined by OpenSSL and call \fBEVP_MD_CTX_get_params()\fR or +\&\fBEVP_MD_CTX_set_params()\fR as is appropriate for each control command. +.Sp +See "CONTROLS" below for more information, including what translations are +being done. +.IP \fBEVP_MD_get_params()\fR 4 +.IX Item "EVP_MD_get_params()" +Retrieves the requested list of \fIparams\fR from a MD \fImd\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_CTX_get_params()\fR 4 +.IX Item "EVP_MD_CTX_get_params()" +Retrieves the requested list of \fIparams\fR from a MD context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_CTX_set_params()\fR 4 +.IX Item "EVP_MD_CTX_set_params()" +Sets the list of \fIparams\fR into a MD context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_gettable_params()\fR 4 +.IX Item "EVP_MD_gettable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_MD_get_params()\fR. +.IP "\fBEVP_MD_gettable_ctx_params()\fR, \fBEVP_MD_CTX_gettable_params()\fR" 4 +.IX Item "EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_MD_CTX_get_params()\fR. \fBEVP_MD_gettable_ctx_params()\fR +returns the parameters that can be retrieved from the algorithm, whereas +\&\fBEVP_MD_CTX_gettable_params()\fR returns the parameters that can be retrieved +in the context\*(Aqs current state. +.IP "\fBEVP_MD_settable_ctx_params()\fR, \fBEVP_MD_CTX_settable_params()\fR" 4 +.IX Item "EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the settable parameters +that can be used with \fBEVP_MD_CTX_set_params()\fR. \fBEVP_MD_settable_ctx_params()\fR +returns the parameters that can be set from the algorithm, whereas +\&\fBEVP_MD_CTX_settable_params()\fR returns the parameters that can be set in the +context\*(Aqs current state. +.IP "\fBEVP_MD_CTX_set_flags()\fR, \fBEVP_MD_CTX_clear_flags()\fR, \fBEVP_MD_CTX_test_flags()\fR" 4 +.IX Item "EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()" +Sets, clears and tests \fIctx\fR flags. See "FLAGS" below for more information. +.IP "\fBEVP_Q_digest()\fR is a quick one\-shot digest function." 4 +.IX Item "EVP_Q_digest() is a quick one-shot digest function." +It hashes \fIdatalen\fR bytes of data at \fIdata\fR using the digest algorithm +\&\fIname\fR, which is fetched using the optional \fIlibctx\fR and \fIpropq\fR parameters. +The digest value is placed in \fImd\fR and its length is written at \fImdlen\fR +if the pointer is not NULL. At most \fBEVP_MAX_MD_SIZE\fR bytes will be written. +.IP \fBEVP_Digest()\fR 4 +.IX Item "EVP_Digest()" +A wrapper around the Digest Init_ex, Update and Final_ex functions. +Hashes \fIcount\fR bytes of data at \fIdata\fR using a digest \fItype\fR from ENGINE +\&\fIimpl\fR. The digest value is placed in \fImd\fR and its length is written at \fIsize\fR +if the pointer is not NULL. At most \fBEVP_MAX_MD_SIZE\fR bytes will be written. +If \fIimpl\fR is NULL the default implementation of digest \fItype\fR is used. +.IP \fBEVP_DigestInit_ex2()\fR 4 +.IX Item "EVP_DigestInit_ex2()" +Sets up digest context \fIctx\fR to use a digest \fItype\fR. +\&\fItype\fR is typically supplied by a function such as \fBEVP_sha1()\fR, or a +value explicitly fetched with \fBEVP_MD_fetch()\fR. \fIctx\fR \fBMUST NOT\fR be NULL. +.Sp +The parameters \fBparams\fR are set on the context after initialisation. +.Sp +The \fItype\fR parameter can be NULL if \fIctx\fR has been already initialized +with another \fBEVP_DigestInit_ex()\fR call and has not been reset with +\&\fBEVP_MD_CTX_reset()\fR. +.IP \fBEVP_DigestInit_ex()\fR 4 +.IX Item "EVP_DigestInit_ex()" +Sets up digest context \fIctx\fR to use a digest \fItype\fR. +\&\fItype\fR is typically supplied by a function such as \fBEVP_sha1()\fR, or a +value explicitly fetched with \fBEVP_MD_fetch()\fR. +.Sp +If \fIimpl\fR is non\-NULL, its implementation of the digest \fItype\fR is used if +there is one, and if not, the default implementation is used. +.Sp +The \fItype\fR parameter can be NULL if \fIctx\fR has been already initialized +with another \fBEVP_DigestInit_ex()\fR call and has not been reset with +\&\fBEVP_MD_CTX_reset()\fR. +.IP \fBEVP_DigestUpdate()\fR 4 +.IX Item "EVP_DigestUpdate()" +Hashes \fIcnt\fR bytes of data at \fId\fR into the digest context \fIctx\fR. This +function can be called several times on the same \fIctx\fR to hash additional +data. +.IP \fBEVP_DigestFinal_ex()\fR 4 +.IX Item "EVP_DigestFinal_ex()" +Retrieves the digest value from \fIctx\fR and places it in \fImd\fR. If the \fIs\fR +parameter is not NULL then the number of bytes of data written (i.e. the +length of the digest) will be written to the integer at \fIs\fR, at most +\&\fBEVP_MAX_MD_SIZE\fR bytes will be written unless the digest implementation +allows changing the digest size and it is set to a larger value by the +application. After calling \fBEVP_DigestFinal_ex()\fR no additional calls to +\&\fBEVP_DigestUpdate()\fR can be made, but \fBEVP_DigestInit_ex2()\fR can be called to +initialize a new digest operation. \fIctx\fR \fBMUST NOT\fR be NULL. +.IP \fBEVP_DigestFinalXOF()\fR 4 +.IX Item "EVP_DigestFinalXOF()" +Interfaces to extendable\-output functions, XOFs, such as SHAKE128 and SHAKE256. +It retrieves the digest value from \fIctx\fR and places it in \fIoutlen\fR\-sized \fIout\fR. +After calling this function no additional calls to \fBEVP_DigestUpdate()\fR can be +made, but \fBEVP_DigestInit_ex2()\fR can be called to initialize a new operation. +\&\fBEVP_DigestFinalXOF()\fR may only be called once +.IP \fBEVP_DigestSqueeze()\fR 4 +.IX Item "EVP_DigestSqueeze()" +Similar to \fBEVP_DigestFinalXOF()\fR but allows multiple calls to be made to +squeeze variable length output data. +\&\fBEVP_DigestFinalXOF()\fR should not be called after this. +.IP \fBEVP_MD_CTX_dup()\fR 4 +.IX Item "EVP_MD_CTX_dup()" +Can be used to duplicate the message digest state from \fIin\fR. This is useful +to avoid multiple \fBEVP_MD_fetch()\fR calls or if large amounts of data are to be +hashed which only differ in the last few bytes. +.IP \fBEVP_MD_CTX_copy_ex()\fR 4 +.IX Item "EVP_MD_CTX_copy_ex()" +Can be used to copy the message digest state from \fIin\fR to \fIout\fR. This is +useful if large amounts of data are to be hashed which only differ in the last +few bytes. +.IP \fBEVP_DigestInit()\fR 4 +.IX Item "EVP_DigestInit()" +Behaves in the same way as \fBEVP_DigestInit_ex2()\fR except it doesn\*(Aqt set any +parameters and calls \fBEVP_MD_CTX_reset()\fR so it cannot be used with an \fItype\fR +of NULL. +.IP \fBEVP_DigestFinal()\fR 4 +.IX Item "EVP_DigestFinal()" +Similar to \fBEVP_DigestFinal_ex()\fR except after computing the digest +the digest context \fIctx\fR is automatically cleaned up with \fBEVP_MD_CTX_reset()\fR. +.IP \fBEVP_MD_CTX_copy()\fR 4 +.IX Item "EVP_MD_CTX_copy()" +Similar to \fBEVP_MD_CTX_copy_ex()\fR except the destination \fIout\fR does not have to +be initialized. +.IP \fBEVP_MD_is_a()\fR 4 +.IX Item "EVP_MD_is_a()" +Returns 1 if \fImd\fR is an implementation of an algorithm that\*(Aqs +identifiable with \fIname\fR, otherwise 0. +.Sp +If \fImd\fR is a legacy digest (it\*(Aqs the return value from the likes of +\&\fBEVP_sha256()\fR rather than the result of an \fBEVP_MD_fetch()\fR), only cipher +names registered with the default library context (see +\&\fBOSSL_LIB_CTX\fR\|(3)) will be considered. +.IP \fBEVP_MD_xof()\fR 4 +.IX Item "EVP_MD_xof()" +Returns 1 if \fImd\fR is an Extendable\-output Function (XOF) otherwise it returns +0. SHAKE128 and SHAKE256 are XOF functions. +It returns 0 for BLAKE2B algorithms. +.IP "\fBEVP_MD_get0_name()\fR, \fBEVP_MD_CTX_get0_name()\fR" 4 +.IX Item "EVP_MD_get0_name(), EVP_MD_CTX_get0_name()" +Return the name of the given message digest. For fetched message +digests with multiple names, only one of them is returned; it\*(Aqs +recommended to use \fBEVP_MD_names_do_all()\fR instead. +.IP \fBEVP_MD_names_do_all()\fR 4 +.IX Item "EVP_MD_names_do_all()" +Traverses all names for the \fImd\fR, and calls \fIfn\fR with each name and +\&\fIdata\fR. This is only useful with fetched \fBEVP_MD\fRs. +.IP \fBEVP_MD_get0_description()\fR 4 +.IX Item "EVP_MD_get0_description()" +Returns a description of the digest, meant for display and human consumption. +The description is at the discretion of the digest implementation. +.IP \fBEVP_MD_get0_provider()\fR 4 +.IX Item "EVP_MD_get0_provider()" +Returns an \fBOSSL_PROVIDER\fR pointer to the provider that implements the given +\&\fBEVP_MD\fR. +.IP \fBEVP_MD_get_size()\fR 4 +.IX Item "EVP_MD_get_size()" +Return the size of the message digest when passed an \fBEVP_MD\fR, i.e. the size of +the hash. A negative value or 0 can occur for invalid size. +For an XOF with no default size this returns 0. +.IP "\fBEVP_MD_CTX_get_size_ex()\fR, \fBEVP_MD_CTX_get_size()\fR" 4 +.IX Item "EVP_MD_CTX_get_size_ex(), EVP_MD_CTX_get_size()" +For a normal digest this is the same as \fBEVP_MD_get_size()\fR. +For an XOF this returns the "xoflen" if it has been set, otherwise it returns 0. +.IP "\fBEVP_MD_get_block_size()\fR, \fBEVP_MD_CTX_get_block_size()\fR" 4 +.IX Item "EVP_MD_get_block_size(), EVP_MD_CTX_get_block_size()" +Return the block size of the message digest when passed an \fBEVP_MD\fR or an +\&\fBEVP_MD_CTX\fR structure. +.IP "\fBEVP_MD_get_type()\fR, \fBEVP_MD_CTX_get_type()\fR" 4 +.IX Item "EVP_MD_get_type(), EVP_MD_CTX_get_type()" +Return the NID of the OBJECT IDENTIFIER representing the given message digest +when passed an \fBEVP_MD\fR structure. For example, \f(CW\*(C`EVP_MD_get_type(EVP_sha1())\*(C'\fR +returns \fBNID_sha1\fR. This function is normally used when setting ASN1 OIDs. +.IP \fBEVP_MD_CTX_get0_md_data()\fR 4 +.IX Item "EVP_MD_CTX_get0_md_data()" +Return the digest method private data for the passed \fBEVP_MD_CTX\fR. +The space is allocated by OpenSSL and has the size originally set with +\&\fBEVP_MD_meth_set_app_datasize()\fR. +.IP "\fBEVP_MD_CTX_get0_md()\fR, \fBEVP_MD_CTX_get1_md()\fR" 4 +.IX Item "EVP_MD_CTX_get0_md(), EVP_MD_CTX_get1_md()" +\&\fBEVP_MD_CTX_get0_md()\fR returns +the \fBEVP_MD\fR structure corresponding to the passed \fBEVP_MD_CTX\fR. This +will be the same \fBEVP_MD\fR object originally passed to \fBEVP_DigestInit_ex2()\fR (or +other similar function) when the EVP_MD_CTX was first initialised. Note that +where explicit fetch is in use (see \fBEVP_MD_fetch\fR\|(3)) the value returned from +this function will not have its reference count incremented and therefore it +should not be used after the EVP_MD_CTX is freed. +\&\fBEVP_MD_CTX_get1_md()\fR is the same except the ownership is passed to the +caller and is from the passed \fBEVP_MD_CTX\fR. +.IP \fBEVP_MD_CTX_set_update_fn()\fR 4 +.IX Item "EVP_MD_CTX_set_update_fn()" +Sets the update function for \fIctx\fR to \fIupdate\fR. +This is the function that is called by \fBEVP_DigestUpdate()\fR. If not set, the +update function from the \fBEVP_MD\fR type specified at initialization is used. +.IP \fBEVP_MD_CTX_update_fn()\fR 4 +.IX Item "EVP_MD_CTX_update_fn()" +Returns the update function for \fIctx\fR. +.IP \fBEVP_MD_get_flags()\fR 4 +.IX Item "EVP_MD_get_flags()" +Returns the \fImd\fR flags. Note that these are different from the \fBEVP_MD_CTX\fR +ones. See \fBEVP_MD_meth_set_flags\fR\|(3) for more information. +.IP \fBEVP_MD_get_pkey_type()\fR 4 +.IX Item "EVP_MD_get_pkey_type()" +Returns the NID of the public key signing algorithm associated with this +digest. For example \fBEVP_sha1()\fR is associated with RSA so this will return +\&\fBNID_sha1WithRSAEncryption\fR. Since digests and signature algorithms are no +longer linked this function is only retained for compatibility reasons. +.IP \fBEVP_md_null()\fR 4 +.IX Item "EVP_md_null()" +A "null" message digest that does nothing: i.e. the hash it returns is of zero +length. +.IP "\fBEVP_get_digestbyname()\fR, \fBEVP_get_digestbynid()\fR, \fBEVP_get_digestbyobj()\fR" 4 +.IX Item "EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()" +Returns an \fBEVP_MD\fR structure when passed a digest name, a digest \fBNID\fR or an +\&\fBASN1_OBJECT\fR structure respectively. +.Sp +The \fBEVP_get_digestbyname()\fR function is present for backwards compatibility with +OpenSSL prior to version 3 and is different to the \fBEVP_MD_fetch()\fR function +since it does not attempt to "fetch" an implementation of the cipher. +Additionally, it only knows about digests that are built\-in to OpenSSL and have +an associated NID. Similarly \fBEVP_get_digestbynid()\fR and \fBEVP_get_digestbyobj()\fR +also return objects without an associated implementation. +.Sp +When the digest objects returned by these functions are used (such as in a call +to \fBEVP_DigestInit_ex()\fR) an implementation of the digest will be implicitly +fetched from the loaded providers. This fetch could fail if no suitable +implementation is available. Use \fBEVP_MD_fetch()\fR instead to explicitly fetch +the algorithm and an associated implementation from a provider. +.Sp +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about fetching. +.Sp +The digest objects returned from these functions do not need to be freed with +\&\fBEVP_MD_free()\fR. +.IP \fBEVP_MD_CTX_get_pkey_ctx()\fR 4 +.IX Item "EVP_MD_CTX_get_pkey_ctx()" +Returns the \fBEVP_PKEY_CTX\fR assigned to \fIctx\fR. The returned pointer should not +be freed by the caller. +.IP \fBEVP_MD_CTX_set_pkey_ctx()\fR 4 +.IX Item "EVP_MD_CTX_set_pkey_ctx()" +Assigns an \fBEVP_PKEY_CTX\fR to \fBEVP_MD_CTX\fR. This is usually used to provide +a customized \fBEVP_PKEY_CTX\fR to \fBEVP_DigestSignInit\fR\|(3) or +\&\fBEVP_DigestVerifyInit\fR\|(3). The \fIpctx\fR passed to this function should be freed +by the caller. A NULL \fIpctx\fR pointer is also allowed to clear the \fBEVP_PKEY_CTX\fR +assigned to \fIctx\fR. In such case, freeing the cleared \fBEVP_PKEY_CTX\fR or not +depends on how the \fBEVP_PKEY_CTX\fR is created. +.IP \fBEVP_MD_do_all_provided()\fR 4 +.IX Item "EVP_MD_do_all_provided()" +Traverses all messages digests implemented by all activated providers +in the given library context \fIlibctx\fR, and for each of the implementations, +calls the given function \fIfn\fR with the implementation method and the given +\&\fIarg\fR as argument. +.SH PARAMETERS +.IX Header "PARAMETERS" +See \fBOSSL_PARAM\fR\|(3) for information about passing parameters. +.PP +\&\fBEVP_MD_CTX_set_params()\fR and \fBEVP_MD_CTX_get_params()\fR can be used with the +following OSSL_PARAM keys: +.IP """xoflen"" (\fBOSSL_DIGEST_PARAM_XOFLEN\fR) " 4 +.IX Item """xoflen"" (OSSL_DIGEST_PARAM_XOFLEN) " +Sets or gets the digest length for extendable output functions. +The value should not exceed what can be given using a \fBsize_t\fR. +It may be used by SHAKE\-128 and SHAKE\-256 to set the +output length used by \fBEVP_DigestFinal_ex()\fR and \fBEVP_DigestFinal()\fR. +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) " +Sets or gets a fixed digest length. +The value should not exceed what can be given using a \fBsize_t\fR. +It may be used by BLAKE2B\-512 to set the output length used by +\&\fBEVP_DigestFinal_ex()\fR and \fBEVP_DigestFinal()\fR. +.PP +\&\fBEVP_MD_CTX_set_params()\fR can be used with the following OSSL_PARAM keys: +.IP """pad\-type"" (\fBOSSL_DIGEST_PARAM_PAD_TYPE\fR) " 4 +.IX Item """pad-type"" (OSSL_DIGEST_PARAM_PAD_TYPE) " +Sets the padding type. +It is used by the MDC2 algorithm. +.PP +\&\fBEVP_MD_CTX_get_params()\fR can be used with the following OSSL_PARAM keys: +.IP """micalg"" (\fBOSSL_DIGEST_PARAM_MICALG\fR) ." 4 +.IX Item """micalg"" (OSSL_DIGEST_PARAM_MICALG) ." +Gets the digest Message Integrity Check algorithm string. This is used when +creating S/MIME multipart/signed messages, as specified in RFC 3851. +It may be used by external engines or providers. +.SH CONTROLS +.IX Header "CONTROLS" +\&\fBEVP_MD_CTX_ctrl()\fR can be used to send the following standard controls: +.IP EVP_MD_CTRL_MICALG 4 +.IX Item "EVP_MD_CTRL_MICALG" +Gets the digest Message Integrity Check algorithm string. This is used when +creating S/MIME multipart/signed messages, as specified in RFC 3851. +The string value is written to \fIp2\fR. +.Sp +When used with a fetched \fBEVP_MD\fR, \fBEVP_MD_CTX_get_params()\fR gets called with +an \fBOSSL_PARAM\fR\|(3) item with the key "micalg" (\fBOSSL_DIGEST_PARAM_MICALG\fR). +.IP EVP_MD_CTRL_XOF_LEN 4 +.IX Item "EVP_MD_CTRL_XOF_LEN" +This control sets the digest length for extendable output functions to \fIp1\fR. +Sending this control directly should not be necessary, the use of +\&\fBEVP_DigestFinalXOF()\fR is preferred. +Currently used by SHAKE algorithms. +.Sp +When used with a fetched \fBEVP_MD\fR, \fBEVP_MD_CTX_get_params()\fR gets called with +an \fBOSSL_PARAM\fR\|(3) item with the key "xoflen" (\fBOSSL_DIGEST_PARAM_XOFLEN\fR). +.SH FLAGS +.IX Header "FLAGS" +\&\fBEVP_MD_CTX_set_flags()\fR, \fBEVP_MD_CTX_clear_flags()\fR and \fBEVP_MD_CTX_test_flags()\fR +can be used the manipulate and test these \fBEVP_MD_CTX\fR flags: +.IP EVP_MD_CTX_FLAG_ONESHOT 4 +.IX Item "EVP_MD_CTX_FLAG_ONESHOT" +This flag instructs the digest to optimize for one update only, if possible. +.IP EVP_MD_CTX_FLAG_CLEANED 4 +.IX Item "EVP_MD_CTX_FLAG_CLEANED" +This flag is for internal use only and \fImust not\fR be used in user code. +.IP EVP_MD_CTX_FLAG_REUSE 4 +.IX Item "EVP_MD_CTX_FLAG_REUSE" +This flag is for internal use only and \fImust not\fR be used in user code. +.IP EVP_MD_CTX_FLAG_NO_INIT 4 +.IX Item "EVP_MD_CTX_FLAG_NO_INIT" +This flag instructs \fBEVP_DigestInit()\fR and similar not to initialise the +implementation specific data. +.IP EVP_MD_CTX_FLAG_FINALISE 4 +.IX Item "EVP_MD_CTX_FLAG_FINALISE" +Some functions such as EVP_DigestSign only finalise copies of internal +contexts so additional data can be included after the finalisation call. +This is inefficient if this functionality is not required, and can be +disabled with this flag. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +.IP \fBEVP_MD_fetch()\fR 4 +.IX Item "EVP_MD_fetch()" +Returns a pointer to a \fBEVP_MD\fR for success or NULL for failure. +.IP \fBEVP_MD_up_ref()\fR 4 +.IX Item "EVP_MD_up_ref()" +Returns 1 for success or 0 for failure. +.IP "\fBEVP_Q_digest()\fR, \fBEVP_Digest()\fR, \fBEVP_DigestInit_ex2()\fR, \fBEVP_DigestInit_ex()\fR, \fBEVP_DigestInit()\fR, \fBEVP_DigestUpdate()\fR, \fBEVP_DigestFinal_ex()\fR, \fBEVP_DigestFinalXOF()\fR, and \fBEVP_DigestFinal()\fR" 4 +.IX Item "EVP_Q_digest(), EVP_Digest(), EVP_DigestInit_ex2(), EVP_DigestInit_ex(), EVP_DigestInit(), EVP_DigestUpdate(), EVP_DigestFinal_ex(), EVP_DigestFinalXOF(), and EVP_DigestFinal()" +return 1 for +success and 0 for failure. +.IP \fBEVP_MD_CTX_ctrl()\fR 4 +.IX Item "EVP_MD_CTX_ctrl()" +Returns 1 if successful or 0 for failure. +.IP "\fBEVP_MD_CTX_set_params()\fR, \fBEVP_MD_CTX_get_params()\fR" 4 +.IX Item "EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params()" +Returns 1 if successful or 0 for failure. +.IP "\fBEVP_MD_CTX_settable_params()\fR, \fBEVP_MD_CTX_gettable_params()\fR" 4 +.IX Item "EVP_MD_CTX_settable_params(), EVP_MD_CTX_gettable_params()" +Return an array of constant \fBOSSL_PARAM\fR\|(3)s, or NULL if there is none +to get. +.IP \fBEVP_MD_CTX_dup()\fR 4 +.IX Item "EVP_MD_CTX_dup()" +Returns a new EVP_MD_CTX if successful or NULL on failure. +.IP \fBEVP_MD_CTX_copy_ex()\fR 4 +.IX Item "EVP_MD_CTX_copy_ex()" +Returns 1 if successful or 0 for failure. +.IP "\fBEVP_MD_get_type()\fR, \fBEVP_MD_get_pkey_type()\fR" 4 +.IX Item "EVP_MD_get_type(), EVP_MD_get_pkey_type()" +Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none +exists. +.IP "\fBEVP_MD_get_size()\fR, \fBEVP_MD_get_block_size()\fR, \fBEVP_MD_CTX_get_size()\fR, \fBEVP_MD_CTX_get_block_size()\fR" 4 +.IX Item "EVP_MD_get_size(), EVP_MD_get_block_size(), EVP_MD_CTX_get_size(), EVP_MD_CTX_get_block_size()" +Returns the digest or block size in bytes or \-1 for failure. +.IP \fBEVP_md_null()\fR 4 +.IX Item "EVP_md_null()" +Returns a pointer to the \fBEVP_MD\fR structure of the "null" message digest. +.IP "\fBEVP_get_digestbyname()\fR, \fBEVP_get_digestbynid()\fR, \fBEVP_get_digestbyobj()\fR" 4 +.IX Item "EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()" +Returns either an \fBEVP_MD\fR structure or NULL if an error occurs. +.IP \fBEVP_MD_CTX_set_pkey_ctx()\fR 4 +.IX Item "EVP_MD_CTX_set_pkey_ctx()" +This function has no return value. +.IP \fBEVP_MD_names_do_all()\fR 4 +.IX Item "EVP_MD_names_do_all()" +Returns 1 if the callback was called for all names. A return value of 0 means +that the callback was not called for any names. +.SH NOTES +.IX Header "NOTES" +The \fBEVP\fR interface to message digests should almost always be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the digest used and much more flexible. +.PP +New applications should use the SHA\-2 (such as \fBEVP_sha256\fR\|(3)) or the SHA\-3 +digest algorithms (such as \fBEVP_sha3_512\fR\|(3)). The other digest algorithms +are still in common use. +.PP +For most applications the \fIimpl\fR parameter to \fBEVP_DigestInit_ex()\fR will be +set to NULL to use the default digest implementation. +.PP +Ignoring failure returns of \fBEVP_DigestInit_ex()\fR, \fBEVP_DigestInit_ex2()\fR, or +\&\fBEVP_DigestInit()\fR can lead to undefined behavior on subsequent calls +updating or finalizing the \fBEVP_MD_CTX\fR such as the \fBEVP_DigestUpdate()\fR or +\&\fBEVP_DigestFinal()\fR functions. The only valid calls on the \fBEVP_MD_CTX\fR +when initialization fails are calls that attempt another initialization of +the context or release the context. +.PP +The functions \fBEVP_DigestInit()\fR, \fBEVP_DigestFinal()\fR and \fBEVP_MD_CTX_copy()\fR are +obsolete but are retained to maintain compatibility with existing code. New +applications should use \fBEVP_DigestInit_ex()\fR, \fBEVP_DigestFinal_ex()\fR and +\&\fBEVP_MD_CTX_copy_ex()\fR because they can efficiently reuse a digest context +instead of initializing and cleaning it up on each call and allow non default +implementations of digests to be specified. +.PP +If digest contexts are not cleaned up after use, +memory leaks will occur. +.PP +\&\fBEVP_MD_CTX_get0_name()\fR, \fBEVP_MD_CTX_get_size()\fR, \fBEVP_MD_CTX_get_block_size()\fR, +\&\fBEVP_MD_CTX_get_type()\fR, \fBEVP_get_digestbynid()\fR and \fBEVP_get_digestbyobj()\fR are +defined as macros. +.PP +\&\fBEVP_MD_CTX_ctrl()\fR sends commands to message digests for additional configuration +or control. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example digests the data "Test Message\en" and "Hello World\en", using the +digest name passed on the command line. +.PP +.Vb 3 +\& #include +\& #include +\& #include +\& +\& int main(int argc, char *argv[]) +\& { +\& EVP_MD_CTX *mdctx; +\& const EVP_MD *md; +\& char mess1[] = "Test Message\en"; +\& char mess2[] = "Hello World\en"; +\& unsigned char md_value[EVP_MAX_MD_SIZE]; +\& unsigned int md_len, i; +\& +\& if (argv[1] == NULL) { +\& printf("Usage: mdtest digestname\en"); +\& exit(1); +\& } +\& +\& md = EVP_get_digestbyname(argv[1]); +\& if (md == NULL) { +\& printf("Unknown message digest %s\en", argv[1]); +\& exit(1); +\& } +\& +\& mdctx = EVP_MD_CTX_new(); +\& if (mdctx == NULL) { +\& printf("Message digest create failed.\en"); +\& exit(1); +\& } +\& if (!EVP_DigestInit_ex2(mdctx, md, NULL)) { +\& printf("Message digest initialization failed.\en"); +\& EVP_MD_CTX_free(mdctx); +\& exit(1); +\& } +\& if (!EVP_DigestUpdate(mdctx, mess1, strlen(mess1))) { +\& printf("Message digest update failed.\en"); +\& EVP_MD_CTX_free(mdctx); +\& exit(1); +\& } +\& if (!EVP_DigestUpdate(mdctx, mess2, strlen(mess2))) { +\& printf("Message digest update failed.\en"); +\& EVP_MD_CTX_free(mdctx); +\& exit(1); +\& } +\& if (!EVP_DigestFinal_ex(mdctx, md_value, &md_len)) { +\& printf("Message digest finalization failed.\en"); +\& EVP_MD_CTX_free(mdctx); +\& exit(1); +\& } +\& EVP_MD_CTX_free(mdctx); +\& +\& printf("Digest is: "); +\& for (i = 0; i < md_len; i++) +\& printf("%02x", md_value[i]); +\& printf("\en"); +\& +\& exit(0); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_meth_new\fR\|(3), +\&\fBopenssl\-dgst\fR\|(1), +\&\fBevp\fR\|(7), +\&\fBOSSL_PROVIDER\fR\|(3), +\&\fBOSSL_PARAM\fR\|(3), +\&\fBproperty\fR\|(7), +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), +\&\fBprovider\-digest\fR\|(7), +\&\fBlife_cycle\-digest\fR\|(7) +.PP +The full list of digest algorithms are provided below. +.PP +\&\fBEVP_blake2b512\fR\|(3), +\&\fBEVP_md2\fR\|(3), +\&\fBEVP_md4\fR\|(3), +\&\fBEVP_md5\fR\|(3), +\&\fBEVP_mdc2\fR\|(3), +\&\fBEVP_ripemd160\fR\|(3), +\&\fBEVP_sha1\fR\|(3), +\&\fBEVP_sha224\fR\|(3), +\&\fBEVP_sha3_224\fR\|(3), +\&\fBEVP_sm3\fR\|(3), +\&\fBEVP_whirlpool\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_MD_CTX_create()\fR and \fBEVP_MD_CTX_destroy()\fR functions were renamed to +\&\fBEVP_MD_CTX_new()\fR and \fBEVP_MD_CTX_free()\fR in OpenSSL 1.1.0, respectively. +.PP +The link between digests and signing algorithms was fixed in OpenSSL 1.0 and +later, so now \fBEVP_sha1()\fR can be used with RSA and DSA. +.PP +The \fBEVP_dss1()\fR function was removed in OpenSSL 1.1.0. +.PP +The \fBEVP_MD_CTX_set_pkey_ctx()\fR function was added in OpenSSL 1.1.1. +.PP +The \fBEVP_Q_digest()\fR, \fBEVP_DigestInit_ex2()\fR, +\&\fBEVP_MD_fetch()\fR, \fBEVP_MD_free()\fR, \fBEVP_MD_up_ref()\fR, +\&\fBEVP_MD_get_params()\fR, \fBEVP_MD_CTX_set_params()\fR, \fBEVP_MD_CTX_get_params()\fR, +\&\fBEVP_MD_gettable_params()\fR, \fBEVP_MD_gettable_ctx_params()\fR, +\&\fBEVP_MD_settable_ctx_params()\fR, \fBEVP_MD_CTX_settable_params()\fR and +\&\fBEVP_MD_CTX_gettable_params()\fR functions were added in OpenSSL 3.0. +.PP +The \fBEVP_MD_type()\fR, \fBEVP_MD_nid()\fR, \fBEVP_MD_name()\fR, \fBEVP_MD_pkey_type()\fR, +\&\fBEVP_MD_size()\fR, \fBEVP_MD_block_size()\fR, \fBEVP_MD_flags()\fR, \fBEVP_MD_CTX_size()\fR, +\&\fBEVP_MD_CTX_block_size()\fR, \fBEVP_MD_CTX_type()\fR, and \fBEVP_MD_CTX_md_data()\fR +functions were renamed to include \f(CW\*(C`get\*(C'\fR or \f(CW\*(C`get0\*(C'\fR in their names in +OpenSSL 3.0, respectively. The old names are kept as non\-deprecated +alias macros. +.PP +The \fBEVP_MD_CTX_md()\fR function was deprecated in OpenSSL 3.0; use +\&\fBEVP_MD_CTX_get0_md()\fR instead. +\&\fBEVP_MD_CTX_update_fn()\fR and \fBEVP_MD_CTX_set_update_fn()\fR were deprecated +in OpenSSL 3.0. +.PP +The \fBEVP_MD_CTX_dup()\fR function was added in OpenSSL 3.1. +.PP +The \fBEVP_DigestSqueeze()\fR function was added in OpenSSL 3.3. +.PP +The \fBEVP_MD_CTX_get_size_ex()\fR and \fBEVP_xof()\fR functions were added in OpenSSL 3.4. +The macros \fBEVP_MD_CTX_get_size()\fR and EVP_MD_CTX_size were changed in OpenSSL 3.4 +to be aliases for \fBEVP_MD_CTX_get_size_ex()\fR, previously they were aliases for +EVP_MD_get_size which returned a constant value. This is required for XOF +digests since they do not have a fixed size. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_DigestInit_ex.3 b/static/netbsd/man3/EVP_DigestInit_ex.3 new file mode 100644 index 00000000..325a823d --- /dev/null +++ b/static/netbsd/man3/EVP_DigestInit_ex.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_DigestInit_ex.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_DigestSignInit.3 b/static/netbsd/man3/EVP_DigestSignInit.3 new file mode 100644 index 00000000..9673fa67 --- /dev/null +++ b/static/netbsd/man3/EVP_DigestSignInit.3 @@ -0,0 +1,266 @@ +.\" $NetBSD: EVP_DigestSignInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_DigestSignInit 3" +.TH EVP_DigestSignInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate, +EVP_DigestSignFinal, EVP_DigestSign \- EVP signing functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, +\& const char *mdname, OSSL_LIB_CTX *libctx, +\& const char *props, EVP_PKEY *pkey, +\& const OSSL_PARAM params[]); +\& int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, +\& const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); +\& int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); +\& int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); +\& +\& int EVP_DigestSign(EVP_MD_CTX *ctx, unsigned char *sig, +\& size_t *siglen, const unsigned char *tbs, +\& size_t tbslen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP signature routines are a high\-level interface to digital signatures. +Input data is digested first before the signing takes place. +.PP +\&\fBEVP_DigestSignInit_ex()\fR sets up signing context \fIctx\fR to use a digest +with the name \fImdname\fR and private key \fIpkey\fR. The name of the digest to be +used is passed to the provider of the signature algorithm in use. How that +provider interprets the digest name is provider specific. The provider may +implement that digest directly itself or it may (optionally) choose to fetch it +(which could result in a digest from a different provider being selected). If the +provider supports fetching the digest then it may use the \fIprops\fR argument for +the properties to be used during the fetch. Finally, the passed parameters +\&\fIparams\fR, if not NULL, are set on the context before returning. +.PP +The \fIpkey\fR algorithm is used to fetch a \fBEVP_SIGNATURE\fR method implicitly, to +be used for the actual signing. See "Implicit fetch" in \fBprovider\fR\|(7) for +more information about implicit fetches. +.PP +The OpenSSL default and legacy providers support fetching digests and can fetch +those digests from any available provider. The OpenSSL FIPS provider also +supports fetching digests but will only fetch digests that are themselves +implemented inside the FIPS provider. +.PP +\&\fIctx\fR must be created with \fBEVP_MD_CTX_new()\fR before calling this function. If +\&\fIpctx\fR is not NULL, the EVP_PKEY_CTX of the signing operation will be written +to \fI*pctx\fR: this can be used to set alternative signing options. Note that any +existing value in \fI*pctx\fR is overwritten. The EVP_PKEY_CTX value returned must +not be freed directly by the application if \fIctx\fR is not assigned an +EVP_PKEY_CTX value before being passed to \fBEVP_DigestSignInit_ex()\fR +(which means the EVP_PKEY_CTX is created inside \fBEVP_DigestSignInit_ex()\fR +and it will be freed automatically when the EVP_MD_CTX is freed). If the +EVP_PKEY_CTX to be used is created by EVP_DigestSignInit_ex then it +will use the \fBOSSL_LIB_CTX\fR specified in \fIlibctx\fR and the property query string +specified in \fIprops\fR. +.PP +The digest \fImdname\fR may be NULL if the signing algorithm supports it. The +\&\fIprops\fR argument can always be NULL. +.PP +No \fBEVP_PKEY_CTX\fR will be created by \fBEVP_DigestSignInit_ex()\fR if the +passed \fIctx\fR has already been assigned one via \fBEVP_MD_CTX_set_pkey_ctx\fR\|(3). +See also \fBSM2\fR\|(7). +.PP +Only EVP_PKEY types that support signing can be used with these functions. This +includes MAC algorithms where the MAC generation is considered as a form of +"signing". Built\-in EVP_PKEY types supported by these functions are CMAC, +Poly1305, DSA, ECDSA, HMAC, RSA, SipHash, Ed25519 and Ed448. +.PP +Not all digests can be used for all key types. The following combinations apply. +.IP DSA 4 +.IX Item "DSA" +Supports SHA1, SHA224, SHA256, SHA384 and SHA512 +.IP ECDSA 4 +.IX Item "ECDSA" +Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 +.IP "RSA with no padding" 4 +.IX Item "RSA with no padding" +Supports no digests (the digest \fItype\fR must be NULL) +.IP "RSA with X931 padding" 4 +.IX Item "RSA with X931 padding" +Supports SHA1, SHA256, SHA384 and SHA512 +.IP "All other RSA padding types" 4 +.IX Item "All other RSA padding types" +Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, +SHA3\-224, SHA3\-256, SHA3\-384, SHA3\-512 +.IP "Ed25519 and Ed448" 4 +.IX Item "Ed25519 and Ed448" +Support no digests (the digest \fItype\fR must be NULL) +.IP HMAC 4 +.IX Item "HMAC" +Supports any digest +.IP "CMAC, Poly1305 and SipHash" 4 +.IX Item "CMAC, Poly1305 and SipHash" +Will ignore any digest provided. +.PP +If RSA\-PSS is used and restrictions apply then the digest must match. +.PP +\&\fBEVP_DigestSignInit()\fR works in the same way as \fBEVP_DigestSignInit_ex()\fR +except that the \fImdname\fR parameter will be inferred from the supplied +digest \fItype\fR, and \fIprops\fR will be NULL. Where supplied the ENGINE \fIe\fR will +be used for the signing and digest algorithm implementations. \fIe\fR may be NULL. +.PP +\&\fBEVP_DigestSignUpdate()\fR hashes \fIcnt\fR bytes of data at \fId\fR into the +signature context \fIctx\fR. This function can be called several times on the +same \fIctx\fR to include additional data. \fIctx\fR \fBMUST NOT\fR be NULL. +.PP +Unless \fIsig\fR is NULL \fBEVP_DigestSignFinal()\fR signs the data in \fIctx\fR +and places the signature in \fIsig\fR. +Otherwise the maximum necessary size of the output buffer is written to +the \fIsiglen\fR parameter. If \fIsig\fR is not NULL then before the call the +\&\fIsiglen\fR parameter should contain the length of the \fIsig\fR buffer. If the +call is successful the signature is written to \fIsig\fR and the amount of data +written to \fIsiglen\fR. +.PP +\&\fBEVP_DigestSign()\fR is similar to a single call to \fBEVP_DigestSignUpdate()\fR and +\&\fBEVP_DigestSignFinal()\fR. +Unless \fIsig\fR is NULL, \fBEVP_DigestSign()\fR signs the data \fItbs\fR of length \fItbslen\fR +bytes and places the signature in a buffer \fIsig\fR of size \fIsiglen\fR. +If \fIsig\fR is NULL, the maximum necessary size of the signature buffer is written +to the \fIsiglen\fR parameter. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR, \fBEVP_DigestSignFinal()\fR and +\&\fBEVP_DigestSign()\fR return 1 for success and 0 for failure. +.PP +The error codes can be obtained from \fBERR_get_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The \fBEVP\fR interface to digital signatures should almost always be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. +.PP +\&\fBEVP_DigestSign()\fR is a one shot operation which signs a single block of data +in one function. For algorithms that support streaming it is equivalent to +calling \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR. For algorithms which +do not support streaming (e.g. PureEdDSA) it is the only way to sign data. +.PP +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as \fBEVP_dss1()\fR +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. +.PP +For some key types and parameters the random number generator must be seeded. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +The call to \fBEVP_DigestSignFinal()\fR internally finalizes a copy of the digest +context. This means that calls to \fBEVP_DigestSignUpdate()\fR and +\&\fBEVP_DigestSignFinal()\fR can be called later to digest and sign additional data. +Applications may disable this behavior by setting the EVP_MD_CTX_FLAG_FINALISE +context flag via \fBEVP_MD_CTX_set_flags\fR\|(3). +.PP +Note that not all providers support continuation, in case the selected +provider does not allow to duplicate contexts \fBEVP_DigestSignFinal()\fR will +finalize the digest context and attempting to process additional data via +\&\fBEVP_DigestSignUpdate()\fR will result in an error. +.PP +\&\fBEVP_DigestSignInit()\fR and \fBEVP_DigestSignInit_ex()\fR functions can be called +multiple times on a context and the parameters set by previous calls should be +preserved if the \fIpkey\fR parameter is NULL. The call then just resets the state +of the \fIctx\fR. +.PP +\&\fBEVP_DigestSign()\fR can not be called again, once a signature is generated (by +passing \fIsig\fR as non NULL), unless the \fBEVP_MD_CTX\fR is reinitialised by +calling \fBEVP_DigestSignInit_ex()\fR. +.PP +Ignoring failure returns of \fBEVP_DigestSignInit()\fR and \fBEVP_DigestSignInit_ex()\fR +functions can lead to subsequent undefined behavior when calling +\&\fBEVP_DigestSignUpdate()\fR, \fBEVP_DigestSignFinal()\fR, or \fBEVP_DigestSign()\fR. +.PP +The use of \fBEVP_PKEY_get_size()\fR with these functions is discouraged because some +signature operations may have a signature length which depends on the +parameters set. As a result \fBEVP_PKEY_get_size()\fR would have to return a value +which indicates the maximum possible signature for any set of parameters. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestVerifyInit\fR\|(3), +\&\fBEVP_DigestInit\fR\|(3), +\&\fBevp\fR\|(7), \fBHMAC\fR\|(3), \fBMD2\fR\|(3), +\&\fBMD5\fR\|(3), \fBMDC2\fR\|(3), \fBRIPEMD160\fR\|(3), +\&\fBSHA1\fR\|(3), \fBopenssl\-dgst\fR\|(1), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR +were added in OpenSSL 1.0.0. +.PP +\&\fBEVP_DigestSignInit_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBEVP_DigestSignUpdate()\fR was converted from a macro to a function in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_DigestUpdate.3 b/static/netbsd/man3/EVP_DigestUpdate.3 new file mode 100644 index 00000000..7df7b685 --- /dev/null +++ b/static/netbsd/man3/EVP_DigestUpdate.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_DigestUpdate.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_DigestVerifyInit.3 b/static/netbsd/man3/EVP_DigestVerifyInit.3 new file mode 100644 index 00000000..328cf662 --- /dev/null +++ b/static/netbsd/man3/EVP_DigestVerifyInit.3 @@ -0,0 +1,251 @@ +.\" $NetBSD: EVP_DigestVerifyInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_DigestVerifyInit 3" +.TH EVP_DigestVerifyInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_DigestVerifyInit_ex, EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, +EVP_DigestVerifyFinal, EVP_DigestVerify \- EVP signature verification functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, +\& const char *mdname, OSSL_LIB_CTX *libctx, +\& const char *props, EVP_PKEY *pkey, +\& const OSSL_PARAM params[]); +\& int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, +\& const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); +\& int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); +\& int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, +\& size_t siglen); +\& int EVP_DigestVerify(EVP_MD_CTX *ctx, const unsigned char *sig, +\& size_t siglen, const unsigned char *tbs, size_t tbslen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP signature routines are a high\-level interface to digital signatures. +Input data is digested first before the signature verification takes place. +.PP +\&\fBEVP_DigestVerifyInit_ex()\fR sets up verification context \fBctx\fR to use a +digest with the name \fBmdname\fR and public key \fBpkey\fR. The name of the digest to +be used is passed to the provider of the signature algorithm in use. How that +provider interprets the digest name is provider specific. The provider may +implement that digest directly itself or it may (optionally) choose to fetch it +(which could result in a digest from a different provider being selected). If +the provider supports fetching the digest then it may use the \fBprops\fR argument +for the properties to be used during the fetch. Finally, the passed parameters +\&\fIparams\fR, if not NULL, are set on the context before returning. +.PP +The \fIpkey\fR algorithm is used to fetch a \fBEVP_SIGNATURE\fR method implicitly, to +be used for the actual signing. See "Implicit fetch" in \fBprovider\fR\|(7) for +more information about implicit fetches. +.PP +The OpenSSL default and legacy providers support fetching digests and can fetch +those digests from any available provider. The OpenSSL FIPS provider also +supports fetching digests but will only fetch digests that are themselves +implemented inside the FIPS provider. +.PP +\&\fBctx\fR must be created with \fBEVP_MD_CTX_new()\fR before calling this function. If +\&\fBpctx\fR is not NULL, the EVP_PKEY_CTX of the verification operation will be +written to \fB*pctx\fR: this can be used to set alternative verification options. +Note that any existing value in \fB*pctx\fR is overwritten. The EVP_PKEY_CTX value +returned must not be freed directly by the application if \fBctx\fR is not assigned +an EVP_PKEY_CTX value before being passed to \fBEVP_DigestVerifyInit_ex()\fR +(which means the EVP_PKEY_CTX is created inside +\&\fBEVP_DigestVerifyInit_ex()\fR and it will be freed automatically when the +EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be used is created by +EVP_DigestVerifyInit_ex then it will use the \fBOSSL_LIB_CTX\fR specified +in \fIlibctx\fR and the property query string specified in \fIprops\fR. +.PP +No \fBEVP_PKEY_CTX\fR will be created by \fBEVP_DigestVerifyInit_ex()\fR if the +passed \fBctx\fR has already been assigned one via \fBEVP_MD_CTX_set_pkey_ctx\fR\|(3). +See also \fBSM2\fR\|(7). +.PP +Not all digests can be used for all key types. The following combinations apply. +.IP DSA 4 +.IX Item "DSA" +Supports SHA1, SHA224, SHA256, SHA384 and SHA512 +.IP ECDSA 4 +.IX Item "ECDSA" +Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 +.IP "RSA with no padding" 4 +.IX Item "RSA with no padding" +Supports no digests (the digest \fBtype\fR must be NULL) +.IP "RSA with X931 padding" 4 +.IX Item "RSA with X931 padding" +Supports SHA1, SHA256, SHA384 and SHA512 +.IP "All other RSA padding types" 4 +.IX Item "All other RSA padding types" +Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, +SHA3\-224, SHA3\-256, SHA3\-384, SHA3\-512 +.IP "Ed25519 and Ed448" 4 +.IX Item "Ed25519 and Ed448" +Support no digests (the digest \fBtype\fR must be NULL) +.IP HMAC 4 +.IX Item "HMAC" +Supports any digest +.IP "CMAC, Poly1305 and Siphash" 4 +.IX Item "CMAC, Poly1305 and Siphash" +Will ignore any digest provided. +.PP +If RSA\-PSS is used and restrictions apply then the digest must match. +.PP +\&\fBEVP_DigestVerifyInit()\fR works in the same way as +\&\fBEVP_DigestVerifyInit_ex()\fR except that the \fBmdname\fR parameter will be +inferred from the supplied digest \fBtype\fR, and \fBprops\fR will be NULL. Where +supplied the ENGINE \fBe\fR will be used for the signature verification and digest +algorithm implementations. \fBe\fR may be NULL. +.PP +\&\fBEVP_DigestVerifyUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the +verification context \fBctx\fR. This function can be called several times on the +same \fBctx\fR to include additional data. +.PP +\&\fBEVP_DigestVerifyFinal()\fR verifies the data in \fBctx\fR against the signature in +\&\fBsig\fR of length \fBsiglen\fR. +.PP +\&\fBEVP_DigestVerify()\fR verifies \fBtbslen\fR bytes at \fBtbs\fR against the signature +in \fBsig\fR of length \fBsiglen\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_DigestVerifyInit()\fR and \fBEVP_DigestVerifyUpdate()\fR return 1 for success and 0 +for failure. +.PP +\&\fBEVP_DigestVerifyFinal()\fR and \fBEVP_DigestVerify()\fR return 1 for success; any other +value indicates failure. A return value of zero indicates that the signature +did not verify successfully (that is, \fBtbs\fR did not match the original data or +the signature had an invalid form), while other values indicate a more serious +error (and sometimes also indicate an invalid signature form). +.PP +The error codes can be obtained from \fBERR_get_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The \fBEVP\fR interface to digital signatures should almost always be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. +.PP +\&\fBEVP_DigestVerify()\fR is a one shot operation which verifies a single block of +data in one function. For algorithms that support streaming it is equivalent +to calling \fBEVP_DigestVerifyUpdate()\fR and \fBEVP_DigestVerifyFinal()\fR. For +algorithms which do not support streaming (e.g. PureEdDSA) it is the only way +to verify data. +.PP +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as \fBEVP_dss1()\fR +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. +.PP +For some key types and parameters the random number generator must be seeded. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +The call to \fBEVP_DigestVerifyFinal()\fR internally finalizes a copy of the digest +context. This means that \fBEVP_VerifyUpdate()\fR and \fBEVP_VerifyFinal()\fR can +be called later to digest and verify additional data. Applications may disable +this behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via +\&\fBEVP_MD_CTX_set_flags\fR\|(3). +.PP +Note that not all providers support continuation, in case the selected +provider does not allow to duplicate contexts \fBEVP_DigestVerifyFinal()\fR will +finalize the digest context and attempting to process additional data via +\&\fBEVP_DigestVerifyUpdate()\fR will result in an error. +.PP +\&\fBEVP_DigestVerifyInit()\fR and \fBEVP_DigestVerifyInit_ex()\fR functions can be called +multiple times on a context and the parameters set by previous calls should be +preserved if the \fIpkey\fR parameter is NULL. The call then just resets the state +of the \fIctx\fR. +.PP +\&\fBEVP_DigestVerify()\fR can only be called once, and cannot be used again without +reinitialising the \fBEVP_MD_CTX\fR by calling \fBEVP_DigestVerifyInit_ex()\fR. +.PP +Ignoring failure returns of \fBEVP_DigestVerifyInit()\fR and \fBEVP_DigestVerifyInit_ex()\fR +functions can lead to subsequent undefined behavior when calling +\&\fBEVP_DigestVerifyUpdate()\fR, \fBEVP_DigestVerifyFinal()\fR, or \fBEVP_DigestVerify()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestSignInit\fR\|(3), +\&\fBEVP_DigestInit\fR\|(3), +\&\fBevp\fR\|(7), \fBHMAC\fR\|(3), \fBMD2\fR\|(3), +\&\fBMD5\fR\|(3), \fBMDC2\fR\|(3), \fBRIPEMD160\fR\|(3), +\&\fBSHA1\fR\|(3), \fBopenssl\-dgst\fR\|(1), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_DigestVerifyInit()\fR, \fBEVP_DigestVerifyUpdate()\fR and \fBEVP_DigestVerifyFinal()\fR +were added in OpenSSL 1.0.0. +.PP +\&\fBEVP_DigestVerifyInit_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBEVP_DigestVerifyUpdate()\fR was converted from a macro to a function in OpenSSL +3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_EncodeInit.3 b/static/netbsd/man3/EVP_EncodeInit.3 new file mode 100644 index 00000000..0fa32e21 --- /dev/null +++ b/static/netbsd/man3/EVP_EncodeInit.3 @@ -0,0 +1,252 @@ +.\" $NetBSD: EVP_EncodeInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_EncodeInit 3" +.TH EVP_EncodeInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, +EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, +EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, +EVP_DecodeBlock \- EVP base64 encode/decode routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); +\& void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); +\& int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); +\& int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); +\& void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); +\& int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, +\& const unsigned char *in, int inl); +\& void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); +\& int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); +\& +\& void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); +\& int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, +\& const unsigned char *in, int inl); +\& int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); +\& int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP encode routines provide a high\-level interface to base64 encoding and +decoding. +Base64 encoding converts binary data into a printable form that uses +the characters A\-Z, a\-z, 0\-9, "+" and "/" to represent the data. For every 3 +bytes of binary data provided 4 bytes of base64 encoded data will be produced +plus some occasional newlines (see below). If the input data length is not a +multiple of 3 then the output data will be padded at the end using the "=" +character. +.PP +\&\fBEVP_ENCODE_CTX_new()\fR allocates, initializes and returns a context to be used for +the encode/decode functions. +.PP +\&\fBEVP_ENCODE_CTX_free()\fR cleans up an encode/decode context \fBctx\fR and frees up the +space allocated to it. If the argument is NULL, nothing is done. +.PP +Encoding of binary data is performed in blocks of 48 input bytes (or less for +the final block). +For each 48 byte input block encoded 64 bytes of base64 data +is output plus an additional newline character (i.e. 65 bytes in total). The +final block (which may be less than 48 bytes) will output 4 bytes for every 3 +bytes of input. If the data length is not divisible by 3 then a full 4 bytes is +still output for the final 1 or 2 bytes of input. Similarly a newline character +will also be output. +.PP +\&\fBEVP_EncodeInit()\fR initialises \fBctx\fR for the start of a new encoding operation. +.PP +\&\fBEVP_EncodeUpdate()\fR encode \fBinl\fR bytes of data found in the buffer pointed to by +\&\fBin\fR. The output is stored in the buffer \fBout\fR and the number of bytes output +is stored in \fB*outl\fR. It is the caller\*(Aqs responsibility to ensure that the +buffer at \fBout\fR is sufficiently large to accommodate the output data. Only full +blocks of data (48 bytes) will be immediately processed and output by this +function. Any remainder is held in the \fBctx\fR object and will be processed by a +subsequent call to \fBEVP_EncodeUpdate()\fR or \fBEVP_EncodeFinal()\fR. To calculate the +required size of the output buffer add together the value of \fBinl\fR with the +amount of unprocessed data held in \fBctx\fR and divide the result by 48 (ignore +any remainder). This gives the number of blocks of data that will be processed. +Ensure the output buffer contains 65 bytes of storage for each block, plus an +additional byte for a NUL terminator. \fBEVP_EncodeUpdate()\fR may be called +repeatedly to process large amounts of input data. In the event of an error +\&\fBEVP_EncodeUpdate()\fR will set \fB*outl\fR to 0 and return 0. On success 1 will be +returned. +.PP +\&\fBEVP_EncodeFinal()\fR must be called at the end of an encoding operation. It will +process any partial block of data remaining in the \fBctx\fR object. The output +data will be stored in \fBout\fR and the length of the data written will be stored +in \fB*outl\fR. It is the caller\*(Aqs responsibility to ensure that \fBout\fR is +sufficiently large to accommodate the output data which will never be more than +65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). +.PP +\&\fBEVP_ENCODE_CTX_copy()\fR can be used to copy a context \fBsctx\fR to a context +\&\fBdctx\fR. \fBdctx\fR must be initialized before calling this function. +.PP +\&\fBEVP_ENCODE_CTX_num()\fR will return the number of as yet unprocessed bytes still to +be encoded or decoded that are pending in the \fBctx\fR object. +.PP +\&\fBEVP_EncodeBlock()\fR encodes a full block of input data in \fBf\fR and of length +\&\fBn\fR and stores it in \fBt\fR. For every 3 bytes of input provided 4 bytes of +output data will be produced. If \fBn\fR is not divisible by 3 then the block is +encoded as a final block of data and the output is padded such that it is always +divisible by 4. Additionally a NUL terminator character will be added. For +example if 16 bytes of input data is provided then 24 bytes of encoded data is +created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of +the data generated \fIwithout\fR the NUL terminator is returned from the function. +.PP +\&\fBEVP_DecodeInit()\fR initialises \fBctx\fR for the start of a new decoding operation. +.PP +\&\fBEVP_DecodeUpdate()\fR decodes \fBinl\fR characters of data found in the buffer +pointed to by \fBin\fR. +The output is stored in the buffer \fBout\fR and the number of bytes output is +stored in \fB*outl\fR. +It is the caller\*(Aqs responsibility to ensure that the buffer at \fBout\fR is +sufficiently large to accommodate the output data. +This function will attempt to decode as much data as possible in chunks of up +to 80 base64 characters at a time. +Residual input shorter than the internal chunk size will be buffered in \fBctx\fR +if its length is not a multiple of 4 (including any padding), to be processed +in future calls to \fBEVP_DecodeUpdate()\fR or \fBEVP_DecodeFinal()\fR. +If the final chunk length is a multiple of 4, it is decoded immediately and +not buffered. +.PP +Any whitespace, newline or carriage return characters are ignored. +For compatibility with \fBPEM\fR, the \fB\-\fR (hyphen) character is treated as a soft +end\-of\-input, subsequent bytes are not buffered, and the return value will be +0 to indicate that the end of the base64 input has been detected. +The soft end\-of\-input, if present, MUST occur after a multiple of 4 valid base64 +input bytes. +The soft end\-of\-input condition is not remembered in \fBctx\fR, it is up to the +caller to avoid further calls to \fBEVP_DecodeUpdate()\fR after a 0 or negative +(error) return. +.PP +If any invalid base64 characters are encountered or if the base64 padding +character (\fB=\fR) is encountered in the middle of the data then +\&\fBEVP_DecodeUpdate()\fR returns \-1 to indicate an error. +A return value of 0 or 1 indicates successful processing of the data. +A return value of 0 additionally indicates that the last 4 bytes processed +ended with base64 padding (\fB=\fR), or that the next 4 byte group starts with the +soft end\-of\-input (\fB\-\fR) character, and therefore no more input data is +expected to be processed. +.PP +For every 4 valid base64 bytes processed (ignoring whitespace, carriage returns +and line feeds), 3 bytes of binary output data will be produced (except at the +end of data terminated with one or two padding characters). +.PP +\&\fBEVP_DecodeFinal()\fR should be called at the end of a decoding operation, +but it will never decode additional data. If there is no residual data +it will return 1 to indicate success. If there is residual data, its +length is not a multiple of 4, i.e. it was not properly padded, \-1 is +is returned in that case to indicate an error. +.PP +\&\fBEVP_DecodeBlock()\fR will decode the block of \fBn\fR characters of base64 data +contained in \fBf\fR and store the result in \fBt\fR. +Any leading whitespace will be trimmed as will any trailing whitespace, +newlines, carriage returns or EOF characters. +Internal whitespace MUST NOT be present. +After trimming the data in \fBf\fR MUST consist entirely of valid base64 +characters or padding (only at the tail of the input) and its length MUST be +divisible by 4. +For every 4 input bytes exactly 3 output bytes will be produced. +Padding bytes (\fB=\fR) (even if internal) are decoded to 6 zero bits, the caller +is responsible for taking trailing padding into account, by ignoring as many +bytes at the tail of the returned output. +\&\fBEVP_DecodeBlock()\fR will return the length of the data decoded or \-1 on error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_ENCODE_CTX_new()\fR returns a pointer to the newly allocated EVP_ENCODE_CTX +object or NULL on error. +.PP +\&\fBEVP_ENCODE_CTX_num()\fR returns the number of bytes pending encoding or decoding in +\&\fBctx\fR. +.PP +\&\fBEVP_EncodeUpdate()\fR returns 0 on error or 1 on success. +.PP +\&\fBEVP_EncodeBlock()\fR returns the number of bytes encoded excluding the NUL +terminator. +.PP +\&\fBEVP_DecodeUpdate()\fR returns \-1 on error and 0 or 1 on success. If 0 is returned +then no more non\-padding base64 characters are expected. +.PP +\&\fBEVP_DecodeFinal()\fR returns \-1 on error or 1 on success. +.PP +\&\fBEVP_DecodeBlock()\fR returns the length of the data decoded or \-1 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_DecodeUpdate()\fR function was fixed in OpenSSL 3.5, +so now it produces the number of bytes specified in \fBoutl*\fR +and does not decode padding bytes (\fB=\fR) to 6 zero bits. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_EncryptInit.3 b/static/netbsd/man3/EVP_EncryptInit.3 new file mode 100644 index 00000000..1651eb5f --- /dev/null +++ b/static/netbsd/man3/EVP_EncryptInit.3 @@ -0,0 +1,1827 @@ +.\" $NetBSD: EVP_EncryptInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_EncryptInit 3" +.TH EVP_EncryptInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_fetch, +EVP_CIPHER_up_ref, +EVP_CIPHER_free, +EVP_CIPHER_CTX_new, +EVP_CIPHER_CTX_reset, +EVP_CIPHER_CTX_free, +EVP_CIPHER_CTX_dup, +EVP_CIPHER_CTX_copy, +EVP_EncryptInit_ex, +EVP_EncryptInit_ex2, +EVP_EncryptUpdate, +EVP_EncryptFinal_ex, +EVP_DecryptInit_ex, +EVP_DecryptInit_ex2, +EVP_DecryptUpdate, +EVP_DecryptFinal_ex, +EVP_CipherInit_ex, +EVP_CipherInit_ex2, +EVP_CipherInit_SKEY, +EVP_CipherUpdate, +EVP_CipherFinal_ex, +EVP_CIPHER_CTX_set_key_length, +EVP_CIPHER_CTX_ctrl, +EVP_EncryptInit, +EVP_EncryptFinal, +EVP_DecryptInit, +EVP_DecryptFinal, +EVP_CipherInit, +EVP_CipherFinal, +EVP_Cipher, +EVP_CIPHER_can_pipeline, +EVP_CipherPipelineEncryptInit, +EVP_CipherPipelineDecryptInit, +EVP_CipherPipelineUpdate, +EVP_CipherPipelineFinal, +EVP_get_cipherbyname, +EVP_get_cipherbynid, +EVP_get_cipherbyobj, +EVP_CIPHER_is_a, +EVP_CIPHER_get0_name, +EVP_CIPHER_get0_description, +EVP_CIPHER_names_do_all, +EVP_CIPHER_get0_provider, +EVP_CIPHER_get_nid, +EVP_CIPHER_get_params, +EVP_CIPHER_gettable_params, +EVP_CIPHER_get_block_size, +EVP_CIPHER_get_key_length, +EVP_CIPHER_get_iv_length, +EVP_CIPHER_get_flags, +EVP_CIPHER_get_mode, +EVP_CIPHER_get_type, +EVP_CIPHER_CTX_cipher, +EVP_CIPHER_CTX_get0_cipher, +EVP_CIPHER_CTX_get1_cipher, +EVP_CIPHER_CTX_get0_name, +EVP_CIPHER_CTX_get_nid, +EVP_CIPHER_CTX_get_params, +EVP_CIPHER_gettable_ctx_params, +EVP_CIPHER_CTX_gettable_params, +EVP_CIPHER_CTX_set_params, +EVP_CIPHER_settable_ctx_params, +EVP_CIPHER_CTX_settable_params, +EVP_CIPHER_CTX_get_block_size, +EVP_CIPHER_CTX_get_key_length, +EVP_CIPHER_CTX_get_iv_length, +EVP_CIPHER_CTX_get_tag_length, +EVP_CIPHER_CTX_flags, +EVP_CIPHER_CTX_set_flags, +EVP_CIPHER_CTX_clear_flags, +EVP_CIPHER_CTX_test_flags, +EVP_CIPHER_CTX_get_type, +EVP_CIPHER_CTX_get_mode, +EVP_CIPHER_CTX_get_num, +EVP_CIPHER_CTX_set_num, +EVP_CIPHER_CTX_is_encrypting, +EVP_CIPHER_param_to_asn1, +EVP_CIPHER_asn1_to_param, +EVP_CIPHER_CTX_set_padding, +EVP_enc_null, +EVP_CIPHER_do_all_provided, +EVP_CIPHER_nid, +EVP_CIPHER_name, +EVP_CIPHER_block_size, +EVP_CIPHER_key_length, +EVP_CIPHER_iv_length, +EVP_CIPHER_flags, +EVP_CIPHER_mode, +EVP_CIPHER_type, +EVP_CIPHER_CTX_encrypting, +EVP_CIPHER_CTX_nid, +EVP_CIPHER_CTX_block_size, +EVP_CIPHER_CTX_key_length, +EVP_CIPHER_CTX_iv_length, +EVP_CIPHER_CTX_tag_length, +EVP_CIPHER_CTX_num, +EVP_CIPHER_CTX_type, +EVP_CIPHER_CTX_mode +\&\- EVP cipher routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); +\& void EVP_CIPHER_free(EVP_CIPHER *cipher); +\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); +\& int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); +\& void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); +\& EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in); +\& int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in); +\& +\& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& ENGINE *impl, const unsigned char *key, const unsigned char *iv); +\& int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& const OSSL_PARAM params[]); +\& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, const unsigned char *in, int inl); +\& int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); +\& +\& int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& ENGINE *impl, const unsigned char *key, const unsigned char *iv); +\& int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& const OSSL_PARAM params[]); +\& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, const unsigned char *in, int inl); +\& int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); +\& +\& int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); +\& int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& int enc, const OSSL_PARAM params[]); +\& int EVP_CipherInit_SKEY(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, +\& EVP_SKEY *skey, const unsigned char *iv, size_t iv_len, +\& int enc, const OSSL_PARAM params[]); +\& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, const unsigned char *in, int inl); +\& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); +\& +\& int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv); +\& int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); +\& +\& int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv); +\& int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); +\& +\& int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, int enc); +\& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); +\& +\& int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& const unsigned char *in, unsigned int inl); +\& +\& int EVP_CIPHER_can_pipeline(const EVP_CIPHER *cipher, int enc); +\& int EVP_CipherPipelineEncryptInit(EVP_CIPHER_CTX *ctx, +\& const EVP_CIPHER *cipher, +\& const unsigned char *key, size_t keylen, +\& size_t numpipes, +\& const unsigned char **iv, size_t ivlen); +\& int EVP_CipherPipelineDecryptInit(EVP_CIPHER_CTX *ctx, +\& const EVP_CIPHER *cipher, +\& const unsigned char *key, size_t keylen, +\& size_t numpipes, +\& const unsigned char **iv, size_t ivlen); +\& int EVP_CipherPipelineUpdate(EVP_CIPHER_CTX *ctx, +\& unsigned char **out, size_t *outl, +\& const size_t *outsize, +\& const unsigned char **in, const size_t *inl); +\& int EVP_CipherPipelineFinal(EVP_CIPHER_CTX *ctx, +\& unsigned char **outm, size_t *outl, +\& const size_t *outsize); +\& +\& int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); +\& int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); +\& int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2); +\& int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key); +\& void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags); +\& void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags); +\& int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags); +\& +\& const EVP_CIPHER *EVP_get_cipherbyname(const char *name); +\& const EVP_CIPHER *EVP_get_cipherbynid(int nid); +\& const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); +\& +\& int EVP_CIPHER_get_nid(const EVP_CIPHER *e); +\& int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); +\& int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher); +\& const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher); +\& const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher); +\& int EVP_CIPHER_get_block_size(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_key_length(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e); +\& unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e); +\& unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_type(const EVP_CIPHER *cipher); +\& +\& const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx); +\& EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx); +\& const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx); +\& +\& int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); +\& int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx); +\& const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num); +\& int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx); +\& +\& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); +\& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); +\& +\& void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_CIPHER *cipher, void *arg), +\& void *arg); +\& +\& #define EVP_CIPHER_nid EVP_CIPHER_get_nid +\& #define EVP_CIPHER_name EVP_CIPHER_get0_name +\& #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size +\& #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length +\& #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length +\& #define EVP_CIPHER_flags EVP_CIPHER_get_flags +\& #define EVP_CIPHER_mode EVP_CIPHER_get_mode +\& #define EVP_CIPHER_type EVP_CIPHER_get_type +\& #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting +\& #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid +\& #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size +\& #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length +\& #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length +\& #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length +\& #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num +\& #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type +\& #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP cipher routines are a high\-level interface to certain +symmetric ciphers. +.PP +The \fBEVP_CIPHER\fR type is a structure for cipher method implementation. +.IP \fBEVP_CIPHER_fetch()\fR 4 +.IX Item "EVP_CIPHER_fetch()" +Fetches the cipher implementation for the given \fIalgorithm\fR from any provider +offering it, within the criteria given by the \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.Sp +The returned value must eventually be freed with \fBEVP_CIPHER_free()\fR. +.Sp +Fetched \fBEVP_CIPHER\fR structures are reference counted. +.IP \fBEVP_CIPHER_up_ref()\fR 4 +.IX Item "EVP_CIPHER_up_ref()" +Increments the reference count for an \fBEVP_CIPHER\fR structure. +.IP \fBEVP_CIPHER_free()\fR 4 +.IX Item "EVP_CIPHER_free()" +Decrements the reference count for the fetched \fBEVP_CIPHER\fR structure. +If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. +.IP \fBEVP_CIPHER_CTX_new()\fR 4 +.IX Item "EVP_CIPHER_CTX_new()" +Allocates and returns a cipher context. +.IP \fBEVP_CIPHER_CTX_free()\fR 4 +.IX Item "EVP_CIPHER_CTX_free()" +Clears all information from a cipher context and frees any allocated memory +associated with it, including \fIctx\fR itself. This function should be called +after all operations using a cipher are complete so sensitive information does +not remain in memory. If the argument is NULL, nothing is done. +.IP \fBEVP_CIPHER_CTX_dup()\fR 4 +.IX Item "EVP_CIPHER_CTX_dup()" +Can be used to duplicate the cipher state from \fIin\fR. This is useful +to avoid multiple \fBEVP_CIPHER_fetch()\fR calls or if large amounts of data are to be +fed which only differ in the last few bytes. +.IP \fBEVP_CIPHER_CTX_copy()\fR 4 +.IX Item "EVP_CIPHER_CTX_copy()" +Can be used to copy the cipher state from \fIin\fR to \fIout\fR. +.IP \fBEVP_CIPHER_CTX_ctrl()\fR 4 +.IX Item "EVP_CIPHER_CTX_ctrl()" +\&\fIThis is a legacy method.\fR \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR is the mechanism that should be used to set and get +parameters that are used by providers. +.Sp +Performs cipher\-specific control actions on context \fIctx\fR. The control command +is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR. +\&\fBEVP_CIPHER_CTX_ctrl()\fR must be called after \fBEVP_CipherInit_ex2()\fR. Other restrictions +may apply depending on the control type and cipher implementation. +.Sp +If this function happens to be used with a fetched \fBEVP_CIPHER\fR, it will +translate the controls that are known to OpenSSL into \fBOSSL_PARAM\fR\|(3) +parameters with keys defined by OpenSSL and call \fBEVP_CIPHER_CTX_get_params()\fR or +\&\fBEVP_CIPHER_CTX_set_params()\fR as is appropriate for each control command. +.Sp +See "CONTROLS" below for more information, including what translations are +being done. +.IP \fBEVP_CIPHER_get_params()\fR 4 +.IX Item "EVP_CIPHER_get_params()" +Retrieves the requested list of algorithm \fIparams\fR from a CIPHER \fIcipher\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_CIPHER_CTX_get_params()\fR 4 +.IX Item "EVP_CIPHER_CTX_get_params()" +Retrieves the requested list of \fIparams\fR from CIPHER context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_CIPHER_CTX_set_params()\fR 4 +.IX Item "EVP_CIPHER_CTX_set_params()" +Sets the list of \fIparams\fR into a CIPHER context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_CIPHER_gettable_params()\fR 4 +.IX Item "EVP_CIPHER_gettable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_CIPHER_get_params()\fR. +.IP "\fBEVP_CIPHER_gettable_ctx_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR" 4 +.IX Item "EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_CIPHER_CTX_get_params()\fR. +\&\fBEVP_CIPHER_gettable_ctx_params()\fR returns the parameters that can be retrieved +from the algorithm, whereas \fBEVP_CIPHER_CTX_gettable_params()\fR returns the +parameters that can be retrieved in the context\*(Aqs current state. +.IP "\fBEVP_CIPHER_settable_ctx_params()\fR and \fBEVP_CIPHER_CTX_settable_params()\fR" 4 +.IX Item "EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()" +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the settable parameters +that can be used with \fBEVP_CIPHER_CTX_set_params()\fR. +\&\fBEVP_CIPHER_settable_ctx_params()\fR returns the parameters that can be set from the +algorithm, whereas \fBEVP_CIPHER_CTX_settable_params()\fR returns the parameters that +can be set in the context\*(Aqs current state. +.IP \fBEVP_EncryptInit_ex2()\fR 4 +.IX Item "EVP_EncryptInit_ex2()" +Sets up cipher context \fIctx\fR for encryption with cipher \fItype\fR. \fIctx\fR \fBMUST NOT\fR be NULL. +\&\fItype\fR is typically supplied by calling \fBEVP_CIPHER_fetch()\fR. \fItype\fR may also be set +using legacy functions such as \fBEVP_aes_256_cbc()\fR, but this is not recommended +for new applications. \fIkey\fR is the symmetric key to use and \fIiv\fR is the IV to +use (if necessary), the actual number of bytes used for the key and IV depends +on the cipher. The parameters \fIparams\fR will be set on the context after +initialisation. It is possible to set all parameters to NULL except \fItype\fR in +an initial call and supply the remaining parameters in subsequent calls, all of +which have \fItype\fR set to NULL. This is done when the default cipher parameters +are not appropriate. +For \fBEVP_CIPH_GCM_MODE\fR the IV will be generated internally if it is not +specified. +.IP \fBEVP_EncryptInit_ex()\fR 4 +.IX Item "EVP_EncryptInit_ex()" +This legacy function is similar to \fBEVP_EncryptInit_ex2()\fR when \fIimpl\fR is NULL. +The implementation of the \fItype\fR from the \fIimpl\fR engine will be used if it +exists. +.IP \fBEVP_EncryptUpdate()\fR 4 +.IX Item "EVP_EncryptUpdate()" +Encrypts \fIinl\fR bytes from the buffer \fIin\fR and writes the encrypted version to +\&\fIout\fR. The pointers \fIout\fR and \fIin\fR may point to the same location, in which +case the encryption will be done in\-place. However, in\-place encryption is +guaranteed to work only if the encryption context (\fIctx\fR) has processed data in +multiples of the block size. If the context contains an incomplete data block +from previous operations, in\-place encryption will fail. \fIctx\fR \fBMUST NOT\fR be NULL. +.Sp +If \fIout\fR and \fIin\fR point to different locations, the two buffers must be +disjoint, otherwise the operation might fail or the outcome might be undefined. +.Sp +This function can be called multiple times to encrypt successive blocks +of data. The amount of data written depends on the block alignment of the +encrypted data. +For most ciphers and modes, the amount of data written can be anything +from zero bytes to (inl + cipher_block_size \- 1) bytes. +For wrap cipher modes, the amount of data written can be anything +from zero bytes to (inl + cipher_block_size) bytes. +For stream ciphers, the amount of data written can be anything from zero +bytes to inl bytes. +Thus, the buffer pointed to by \fIout\fR must contain sufficient room for the +operation being performed. +The actual number of bytes written is placed in \fIoutl\fR. +.Sp +If padding is enabled (the default) then \fBEVP_EncryptFinal_ex()\fR encrypts +the "final" data, that is any data that remains in a partial block. +It uses standard block padding (aka PKCS padding) as described in +the NOTES section, below. The encrypted +final data is written to \fIout\fR which should have sufficient space for +one cipher block. The number of bytes written is placed in \fIoutl\fR. After +this function is called the encryption operation is finished and no further +calls to \fBEVP_EncryptUpdate()\fR should be made. +.Sp +If padding is disabled then \fBEVP_EncryptFinal_ex()\fR will not encrypt any more +data and it will return an error if any data remains in a partial block: +that is if the total data length is not a multiple of the block size. +.IP "\fBEVP_DecryptInit_ex2()\fR, \fBEVP_DecryptInit_ex()\fR, \fBEVP_DecryptUpdate()\fR and \fBEVP_DecryptFinal_ex()\fR" 4 +.IX Item "EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex()" +These functions are the corresponding decryption operations. +\&\fBEVP_DecryptFinal()\fR will return an error code if padding is enabled and the +final block is not correctly formatted. The parameters and restrictions are +identical to the encryption operations. \fIctx\fR \fBMUST NOT\fR be NULL. +.IP "\fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherInit_ex()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal_ex()\fR" 4 +.IX Item "EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex()" +These functions can be used for decryption or encryption. The operation +performed depends on the value of the \fIenc\fR parameter. It should be set to 1 +for encryption, 0 for decryption and \-1 to leave the value unchanged +(the actual value of \*(Aqenc\*(Aq being supplied in a previous call). +.IP \fBEVP_CipherInit_SKEY()\fR 4 +.IX Item "EVP_CipherInit_SKEY()" +This function is similar to \fBEVP_CipherInit_ex2()\fR but accepts a +symmetric key object of type \fIEVP_SKEY\fR as a key. +.IP \fBEVP_CIPHER_CTX_reset()\fR 4 +.IX Item "EVP_CIPHER_CTX_reset()" +Clears all information from a cipher context and free up any allocated memory +associated with it, except the \fIctx\fR itself. This function should be called +anytime \fIctx\fR is reused by another +\&\fBEVP_CipherInit()\fR / \fBEVP_CipherUpdate()\fR / \fBEVP_CipherFinal()\fR series of calls. +.IP "\fBEVP_EncryptInit()\fR, \fBEVP_DecryptInit()\fR and \fBEVP_CipherInit()\fR" 4 +.IX Item "EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()" +Behave in a similar way to \fBEVP_EncryptInit_ex()\fR, \fBEVP_DecryptInit_ex()\fR and +\&\fBEVP_CipherInit_ex()\fR except if the \fItype\fR is not a fetched cipher they use the +default implementation of the \fItype\fR. +.IP "\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptFinal()\fR and \fBEVP_CipherFinal()\fR" 4 +.IX Item "EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()" +Identical to \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal_ex()\fR and +\&\fBEVP_CipherFinal_ex()\fR. In previous releases they also cleaned up +the \fIctx\fR, but this is no longer done and \fBEVP_CIPHER_CTX_cleanup()\fR +must be called to free any context resources. +.IP \fBEVP_Cipher()\fR 4 +.IX Item "EVP_Cipher()" +Encrypts or decrypts a maximum \fIinl\fR amount of bytes from \fIin\fR and leaves the +result in \fIout\fR. +.Sp +For legacy ciphers \- If the cipher doesn\*(Aqt have the flag +\&\fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR set, then \fIinl\fR must be a multiple of +\&\fBEVP_CIPHER_get_block_size()\fR. If it isn\*(Aqt, the result is undefined. If the cipher +has that flag set, then \fIinl\fR can be any size. +.Sp +Due to the constraints of the API contract of this function it shouldn\*(Aqt be used +in applications, please consider using \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal_ex()\fR instead. +.IP \fBEVP_CIPHER_can_pipeline()\fR 4 +.IX Item "EVP_CIPHER_can_pipeline()" +This function checks if a \fBEVP_CIPHER\fR fetched using \fBEVP_CIPHER_fetch()\fR supports +cipher pipelining. If the cipher supports pipelining, it returns 1, otherwise 0. +This function will return 0 for non\-fetched ciphers such as \fBEVP_aes_128_gcm()\fR. +There are currently no built\-in ciphers that support pipelining. +.Sp +Cipher pipelining support allows an application to submit multiple chunks of +data in one set of \fBEVP_CipherUpdate()\fR/EVP_CipherFinal calls, thereby allowing +the provided implementation to take advantage of parallel computing. This is +beneficial for hardware accelerators as pipeline amortizes the latency over +multiple chunks. +.Sp +For non\-fetched ciphers, \fBEVP_CipherPipelineEncryptInit()\fR or +\&\fBEVP_CipherPipelineDecryptInit()\fR may be directly called, which will perform a +fetch and return an error if a pipeline supported implementation is not found. +.IP "\fBEVP_CipherPipelineEncryptInit()\fR, \fBEVP_CipherPipelineDecryptInit()\fR, \fBEVP_CipherPipelineUpdate()\fR and \fBEVP_CipherPipelineFinal()\fR" 4 +.IX Item "EVP_CipherPipelineEncryptInit(), EVP_CipherPipelineDecryptInit(), EVP_CipherPipelineUpdate() and EVP_CipherPipelineFinal()" +These functions can be used to perform multiple encryption or decryption +operations in parallel. \fBEVP_CIPHER_can_pipeline()\fR may be called to check if the +cipher supports pipelining. These functions are analogous to +\&\fBEVP_EncryptInit_ex2()\fR, \fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal()\fR but take an array of pointers for iv, input and output buffers. +.Sp +The \fIkey\fR, of length \fIkeylen\fR, is the symmetric key to use. The \fInumpipes\fR +parameter specifies the number of parallel operations to perform. The +\&\fInumpipes\fR cannot exceed \fBEVP_MAX_PIPES\fR. The \fIiv\fR parameter is an array of +buffer pointers, containing IVs. The array size must be equal to \fInumpipes\fR. +The size of each IV buffer must be equal to \fIivlen\fR. When IV is not provided, +\&\fIiv\fR must be NULL, rather than an array of NULL pointers. The \fIin\fR +parameters takes an array of buffer pointers, each pointing to a buffer +containing the input data. The buffers can be of different sizes. The \fIinl\fR +parameter is an array of size_t, each specifying the size of the corresponding +input buffer. The \fIout\fR and \fIoutm\fR parameters are arrays of buffer pointers, +each pointing to a buffer where the output data will be written. The \fIoutsize\fR +parameter is an array of size_t, each specifying the size of the corresponding +output buffer. The \fIoutl\fR parameter is an array of size_t which will be updated +with the size of the output data written to the corresponding output buffer. +For size requirement of the output buffers, see the description of \fBEVP_CipherUpdate()\fR. +.Sp +The \fBEVP_CipherPipelineUpdate()\fR function can be called multiple times to encrypt +successive blocks of data. For AAD data, the \fIout\fR, and \fIoutsize\fR parameter +should be NULL, rather than an array of NULL pointers. +.IP "\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR" 4 +.IX Item "EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()" +Returns an \fBEVP_CIPHER\fR structure when passed a cipher name, a cipher \fBNID\fR or +an \fBASN1_OBJECT\fR structure respectively. +.Sp +\&\fBEVP_get_cipherbyname()\fR will return NULL for algorithms such as "AES\-128\-SIV", +"AES\-128\-CBC\-CTS" and "CAMELLIA\-128\-CBC\-CTS" which were previously only +accessible via low level interfaces. +.Sp +The \fBEVP_get_cipherbyname()\fR function is present for backwards compatibility with +OpenSSL prior to version 3 and is different to the \fBEVP_CIPHER_fetch()\fR function +since it does not attempt to "fetch" an implementation of the cipher. +Additionally, it only knows about ciphers that are built\-in to OpenSSL and have +an associated NID. Similarly \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR +also return objects without an associated implementation. +.Sp +When the cipher objects returned by these functions are used (such as in a call +to \fBEVP_EncryptInit_ex()\fR) an implementation of the cipher will be implicitly +fetched from the loaded providers. This fetch could fail if no suitable +implementation is available. Use \fBEVP_CIPHER_fetch()\fR instead to explicitly fetch +the algorithm and an associated implementation from a provider. +.Sp +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about fetching. +.Sp +The cipher objects returned from these functions do not need to be freed with +\&\fBEVP_CIPHER_free()\fR. +.IP "\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR" 4 +.IX Item "EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()" +Return the NID of a cipher when passed an \fBEVP_CIPHER\fR or \fBEVP_CIPHER_CTX\fR +structure. The actual NID value is an internal value which may not have a +corresponding OBJECT IDENTIFIER. NID_undef is returned in the event that the +nid is unknown or if the cipher has not been properly initialized via a call to +\&\fBEVP_CipherInit\fR. +.IP "\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR" 4 +.IX Item "EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags()" +Sets, clears and tests \fIctx\fR flags. See "FLAGS" below for more information. +.Sp +For provided ciphers \fBEVP_CIPHER_CTX_set_flags()\fR should be called only after the +fetched cipher has been assigned to the \fIctx\fR. It is recommended to use +"PARAMETERS" instead. +.IP \fBEVP_CIPHER_CTX_set_padding()\fR 4 +.IX Item "EVP_CIPHER_CTX_set_padding()" +Enables or disables padding. This function should be called after the context +is set up for encryption or decryption with \fBEVP_EncryptInit_ex2()\fR, +\&\fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherInit_ex2()\fR, or \fBEVP_CipherInit_SKEY()\fR. By +default encryption operations are padded using standard block padding and the +padding is checked and removed when decrypting. If the \fIpad\fR parameter is zero +then no padding is performed, the total amount of data encrypted or decrypted +must then be a multiple of the block size or an error will occur. \fIx\fR \fBMUST +NOT\fR be NULL. +.IP "\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR" 4 +.IX Item "EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()" +Return the key length of a cipher when passed an \fBEVP_CIPHER\fR or +\&\fBEVP_CIPHER_CTX\fR structure. The constant \fBEVP_MAX_KEY_LENGTH\fR is the maximum +key length for all ciphers. Note: although \fBEVP_CIPHER_get_key_length()\fR is fixed for +a given cipher, the value of \fBEVP_CIPHER_CTX_get_key_length()\fR may be different for +variable key length ciphers. +.IP \fBEVP_CIPHER_CTX_set_key_length()\fR 4 +.IX Item "EVP_CIPHER_CTX_set_key_length()" +Sets the key length of the cipher context. +If the cipher is a fixed length cipher then attempting to set the key +length to any value other than the fixed value is an error. +.IP "\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR" 4 +.IX Item "EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()" +Return the IV length of a cipher when passed an \fBEVP_CIPHER\fR or +\&\fBEVP_CIPHER_CTX\fR. It will return zero if the cipher does not use an IV, if +the cipher has not yet been initialized within the \fBEVP_CIPHER_CTX\fR, or if the +passed cipher is NULL. The constant \fBEVP_MAX_IV_LENGTH\fR is the maximum IV +length for all ciphers. +.IP \fBEVP_CIPHER_CTX_get_tag_length()\fR 4 +.IX Item "EVP_CIPHER_CTX_get_tag_length()" +Returns the tag length of an AEAD cipher when passed a \fBEVP_CIPHER_CTX\fR. It will +return zero if the cipher does not support a tag. It returns a default value if +the tag length has not been set. +.IP "\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR" 4 +.IX Item "EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size()" +Return the block size of a cipher when passed an \fBEVP_CIPHER\fR or +\&\fBEVP_CIPHER_CTX\fR structure. The constant \fBEVP_MAX_BLOCK_LENGTH\fR is also the +maximum block length for all ciphers. +A value of 0 is returned if, with \fBEVP_CIPHER_get_block_size()\fR, the cipher +\&\fIe\fR is NULL, or, with \fBEVP_CIPHER_CTX_get_block_size()\fR, the context +\&\fIctx\fR is NULL or has not been properly initialized with a call to +\&\fBEVP_CipherInit\fR. +.IP "\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR" 4 +.IX Item "EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()" +Return the type of the passed cipher or context. This "type" is the actual NID +of the cipher OBJECT IDENTIFIER and as such it ignores the cipher parameters +(40 bit RC2 and 128 bit RC2 have the same NID). If the cipher does not have an +object identifier or does not have ASN1 support this function will return +\&\fBNID_undef\fR. +.IP \fBEVP_CIPHER_is_a()\fR 4 +.IX Item "EVP_CIPHER_is_a()" +Returns 1 if \fIcipher\fR is an implementation of an algorithm that\*(Aqs identifiable +with \fIname\fR, otherwise 0. If \fIcipher\fR is a legacy cipher (it\*(Aqs the return +value from the likes of \fBEVP_aes128()\fR rather than the result of an +\&\fBEVP_CIPHER_fetch()\fR), only cipher names registered with the default library +context (see \fBOSSL_LIB_CTX\fR\|(3)) will be considered. +.IP "\fBEVP_CIPHER_get0_name()\fR and \fBEVP_CIPHER_CTX_get0_name()\fR" 4 +.IX Item "EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name()" +Return the name of the passed cipher or context. For fetched ciphers with +multiple names, only one of them is returned. See also \fBEVP_CIPHER_names_do_all()\fR. +\&\fIcipher\fR \fBMUST NOT\fR be NULL. +.IP \fBEVP_CIPHER_names_do_all()\fR 4 +.IX Item "EVP_CIPHER_names_do_all()" +Traverses all names for the \fIcipher\fR, and calls \fIfn\fR with each name and +\&\fIdata\fR. This is only useful with fetched \fBEVP_CIPHER\fRs. +.IP \fBEVP_CIPHER_get0_description()\fR 4 +.IX Item "EVP_CIPHER_get0_description()" +Returns a description of the cipher, meant for display and human consumption. +The description is at the discretion of the cipher implementation. +.IP \fBEVP_CIPHER_get0_provider()\fR 4 +.IX Item "EVP_CIPHER_get0_provider()" +Returns an \fBOSSL_PROVIDER\fR pointer to the provider that implements the given +\&\fBEVP_CIPHER\fR. +.IP \fBEVP_CIPHER_CTX_get0_cipher()\fR 4 +.IX Item "EVP_CIPHER_CTX_get0_cipher()" +Returns the \fBEVP_CIPHER\fR structure when passed an \fBEVP_CIPHER_CTX\fR structure. +\&\fBEVP_CIPHER_CTX_get1_cipher()\fR is the same except the ownership is passed to +the caller. Both functions return NULL on error. +.IP "\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR" 4 +.IX Item "EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()" +Return the block cipher mode: +EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, +EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, +EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. +If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned. +.IP \fBEVP_CIPHER_get_flags()\fR 4 +.IX Item "EVP_CIPHER_get_flags()" +Returns any flags associated with the cipher. See "FLAGS" +for a list of currently defined flags. +.IP "\fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR" 4 +.IX Item "EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()" +Gets or sets the cipher specific "num" parameter for the associated \fIctx\fR. +Built\-in ciphers typically use this to track how much of the current underlying block +has been "used" already. +.IP \fBEVP_CIPHER_CTX_is_encrypting()\fR 4 +.IX Item "EVP_CIPHER_CTX_is_encrypting()" +Reports whether the \fIctx\fR is being used for encryption or decryption. +.IP \fBEVP_CIPHER_CTX_flags()\fR 4 +.IX Item "EVP_CIPHER_CTX_flags()" +A deprecated macro calling \f(CW\*(C`EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))\*(C'\fR. +Do not use. +.IP \fBEVP_CIPHER_param_to_asn1()\fR 4 +.IX Item "EVP_CIPHER_param_to_asn1()" +Sets the AlgorithmIdentifier "parameter" based on the passed cipher. This will +typically include any parameters and an IV. The cipher IV (if any) must be set +when this call is made. This call should be made before the cipher is actually +"used" (before any \fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR calls for example). +This function may fail if the cipher does not have any ASN1 support, or if an +uninitialized cipher is passed to it. +.IP \fBEVP_CIPHER_asn1_to_param()\fR 4 +.IX Item "EVP_CIPHER_asn1_to_param()" +Sets the cipher parameters based on an ASN1 AlgorithmIdentifier "parameter". +The precise effect depends on the cipher. In the case of \fBRC2\fR, for example, +it will set the IV and effective key length. +This function should be called after the base cipher type is set but before +the key is set. For example \fBEVP_CipherInit()\fR will be called with the IV and +key set to NULL, \fBEVP_CIPHER_asn1_to_param()\fR will be called and finally +\&\fBEVP_CipherInit()\fR again with all parameters except the key set to NULL. It is +possible for this function to fail if the cipher does not have any ASN1 support +or the parameters cannot be set (for example the RC2 effective key length +is not supported. +.IP \fBEVP_CIPHER_CTX_rand_key()\fR 4 +.IX Item "EVP_CIPHER_CTX_rand_key()" +Generates a random key of the appropriate length based on the cipher context. +The \fBEVP_CIPHER\fR can provide its own random key generation routine to support +keys of a specific form. \fIkey\fR must point to a buffer at least as big as the +value returned by \fBEVP_CIPHER_CTX_get_key_length()\fR. +.IP \fBEVP_CIPHER_do_all_provided()\fR 4 +.IX Item "EVP_CIPHER_do_all_provided()" +Traverses all ciphers implemented by all activated providers in the given +library context \fIlibctx\fR, and for each of the implementations, calls the given +function \fIfn\fR with the implementation method and the given \fIarg\fR as argument. +.SH PARAMETERS +.IX Header "PARAMETERS" +See \fBOSSL_PARAM\fR\|(3) for information about passing parameters. +.SS "Gettable EVP_CIPHER parameters" +.IX Subsection "Gettable EVP_CIPHER parameters" +When \fBEVP_CIPHER_fetch()\fR is called it internally calls \fBEVP_CIPHER_get_params()\fR +and caches the results. +.PP +\&\fBEVP_CIPHER_get_params()\fR can be used with the following \fBOSSL_PARAM\fR\|(3) keys: +.IP """mode"" (\fBOSSL_CIPHER_PARAM_MODE\fR) " 4 +.IX Item """mode"" (OSSL_CIPHER_PARAM_MODE) " +Gets the mode for the associated cipher algorithm \fIcipher\fR. +See "\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR" for a list of valid modes. +Use \fBEVP_CIPHER_get_mode()\fR to retrieve the cached value. +.IP """keylen"" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR) " 4 +.IX Item """keylen"" (OSSL_CIPHER_PARAM_KEYLEN) " +Gets the key length for the associated cipher algorithm \fIcipher\fR. +Use \fBEVP_CIPHER_get_key_length()\fR to retrieve the cached value. +.IP """ivlen"" (\fBOSSL_CIPHER_PARAM_IVLEN\fR) " 4 +.IX Item """ivlen"" (OSSL_CIPHER_PARAM_IVLEN) " +Gets the IV length for the associated cipher algorithm \fIcipher\fR. +Use \fBEVP_CIPHER_get_iv_length()\fR to retrieve the cached value. +.IP """blocksize"" (\fBOSSL_CIPHER_PARAM_BLOCK_SIZE\fR) " 4 +.IX Item """blocksize"" (OSSL_CIPHER_PARAM_BLOCK_SIZE) " +Gets the block size for the associated cipher algorithm \fIcipher\fR. +The block size should be 1 for stream ciphers. +Note that the block size for a cipher may be different to the block size for +the underlying encryption/decryption primitive. +For example AES in CTR mode has a block size of 1 (because it operates like a +stream cipher), even though AES has a block size of 16. +Use \fBEVP_CIPHER_get_block_size()\fR to retrieve the cached value. +.IP """aead"" (\fBOSSL_CIPHER_PARAM_AEAD\fR) " 4 +.IX Item """aead"" (OSSL_CIPHER_PARAM_AEAD) " +Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0. +Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to retrieve the +cached value. +.IP """custom\-iv"" (\fBOSSL_CIPHER_PARAM_CUSTOM_IV\fR) " 4 +.IX Item """custom-iv"" (OSSL_CIPHER_PARAM_CUSTOM_IV) " +Gets 1 if the cipher algorithm \fIcipher\fR has a custom IV, otherwise it gets 0. +Storing and initializing the IV is left entirely to the implementation, if a +custom IV is used. +Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the +cached value. +.IP """cts"" (\fBOSSL_CIPHER_PARAM_CTS\fR) " 4 +.IX Item """cts"" (OSSL_CIPHER_PARAM_CTS) " +Gets 1 if the cipher algorithm \fIcipher\fR uses ciphertext stealing, +otherwise it gets 0. +This is currently used to indicate that the cipher is a one shot that only +allows a single call to \fBEVP_CipherUpdate()\fR. +Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_CTS) to retrieve the +cached value. +.IP """tls\-multi"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\fR) " 4 +.IX Item """tls-multi"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) " +Gets 1 if the cipher algorithm \fIcipher\fR supports interleaving of crypto blocks, +otherwise it gets 0. The interleaving is an optimization only applicable to certain +TLS ciphers. +Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to retrieve the +cached value. +.IP """has\-randkey"" (\fBOSSL_CIPHER_PARAM_HAS_RANDKEY\fR) " 4 +.IX Item """has-randkey"" (OSSL_CIPHER_PARAM_HAS_RANDKEY) " +Gets 1 if the cipher algorithm \fIcipher\fR supports the gettable EVP_CIPHER_CTX +parameter \fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR. Only DES and 3DES set this to 1, +all other OpenSSL ciphers return 0. +.IP """decrypt\-only"" (\fBOSSL_CIPHER_PARAM_DECRYPT_ONLY) " 4 +.IX Item """padding"" (OSSL_CIPHER_PARAM_PADDING) " +Gets or sets the padding mode for the cipher context \fIctx\fR. +Padding is enabled if the value is 1, and disabled if the value is 0. +See also \fBEVP_CIPHER_CTX_set_padding()\fR. +.IP """num"" (\fBOSSL_CIPHER_PARAM_NUM\fR) " 4 +.IX Item """num"" (OSSL_CIPHER_PARAM_NUM) " +Gets or sets the cipher specific "num" parameter for the cipher context \fIctx\fR. +Built\-in ciphers typically use this to track how much of the current underlying +block has been "used" already. +See also \fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR. +.IP """keylen"" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR) " 4 +.IX Item """keylen"" (OSSL_CIPHER_PARAM_KEYLEN) " +Gets or sets the key length for the cipher context \fIctx\fR. +The length of the "keylen" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_key_length()\fR and \fBEVP_CIPHER_CTX_set_key_length()\fR. +.IP """tag"" (\fBOSSL_CIPHER_PARAM_AEAD_TAG\fR) " 4 +.IX Item """tag"" (OSSL_CIPHER_PARAM_AEAD_TAG) " +Gets or sets the AEAD tag for the associated cipher context \fIctx\fR. +See "AEAD INTERFACE" in \fBEVP_EncryptInit\fR\|(3). +.IP """pipeline\-tag"" (\fBOSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG\fR) " 4 +.IX Item """pipeline-tag"" (OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG) " +Gets or sets the AEAD tag when using cipher pipelining. The pointer must +point to an array of buffers, where the aead tag will be read from or written to. +The array size must be equal to \fInumpipes\fR used in +\&\fBEVP_CipherPipelineEncryptInit()\fR or \fBEVP_CipherPipelineDecryptInit()\fR. +.IP """keybits"" (\fBOSSL_CIPHER_PARAM_RC2_KEYBITS\fR) " 4 +.IX Item """keybits"" (OSSL_CIPHER_PARAM_RC2_KEYBITS) " +Gets or sets the effective keybits used for a RC2 cipher. +The length of the "keybits" parameter should not exceed that of a \fBsize_t\fR. +.IP """rounds"" (\fBOSSL_CIPHER_PARAM_ROUNDS\fR) " 4 +.IX Item """rounds"" (OSSL_CIPHER_PARAM_ROUNDS) " +Gets or sets the number of rounds to be used for a cipher. +This is used by the RC5 cipher. +.IP """algorithm\-id"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID\fR) " 4 +.IX Item """algorithm-id"" (OSSL_CIPHER_PARAM_ALGORITHM_ID) " +Used to get the DER encoded AlgorithmIdentifier from the cipher +implementation. Functions like \fBEVP_PKEY_CTX_get_algor\fR\|(3) use this +parameter. +.IP """algorithm\-id\-params"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\fR) " 4 +.IX Item """algorithm-id-params"" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) " +Used to pass the DER encoded AlgorithmIdentifier parameter to or from +the cipher implementation. +Functions like \fBEVP_CIPHER_CTX_set_algor_params\fR\|(3) and +\&\fBEVP_CIPHER_CTX_get_algor_params\fR\|(3) use this parameter. +.IP """alg_id_params"" (\fBOSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD\fR) " 4 +.IX Item """alg_id_params"" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD) " +An deprecated alias for "algorithm\-id\-params", only used by +\&\fBEVP_CIPHER_param_to_asn1\fR\|(3) and \fBEVP_CIPHER_asn1_to_param\fR\|(3). +.IP """cts_mode"" (\fBOSSL_CIPHER_PARAM_CTS_MODE\fR) " 4 +.IX Item """cts_mode"" (OSSL_CIPHER_PARAM_CTS_MODE) " +Gets or sets the cipher text stealing mode. For all modes the output size is the +same as the input size. The input length must be greater than or equal to the +block size. (The block size for AES and CAMELLIA is 16 bytes). +.Sp +Valid values for the mode are: +.RS 4 +.IP """CS1""" 4 +.IX Item """CS1""" +The NIST variant of cipher text stealing. +For input lengths that are multiples of the block size it is equivalent to +using a "AES\-XXX\-CBC" or "CAMELLIA\-XXX\-CBC" cipher otherwise the second last +cipher text block is a partial block. +.IP """CS2""" 4 +.IX Item """CS2""" +For input lengths that are multiples of the block size it is equivalent to +using a "AES\-XXX\-CBC" or "CAMELLIA\-XXX\-CBC" cipher, otherwise it is the same as +"CS3" mode. +.IP """CS3""" 4 +.IX Item """CS3""" +The Kerberos5 variant of cipher text stealing which always swaps the last +cipher text block with the previous block (which may be a partial or full block +depending on the input length). If the input length is exactly one full block +then this is equivalent to using a "AES\-XXX\-CBC" or "CAMELLIA\-XXX\-CBC" cipher. +.RE +.RS 4 +.Sp +The default is "CS1". +This is only supported for "AES\-128\-CBC\-CTS", "AES\-192\-CBC\-CTS", "AES\-256\-CBC\-CTS", +"CAMELLIA\-128\-CBC\-CTS", "CAMELLIA\-192\-CBC\-CTS" and "CAMELLIA\-256\-CBC\-CTS". +.RE +.IP """tls1multi_interleave"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR) " 4 +.IX Item """tls1multi_interleave"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) " +Sets or gets the number of records being sent in one go for a tls1 multiblock +cipher operation (either 4 or 8 records). +.SS "Gettable EVP_CIPHER_CTX parameters" +.IX Subsection "Gettable EVP_CIPHER_CTX parameters" +The following \fBOSSL_PARAM\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_get_params()\fR: +.IP """ivlen"" (\fBOSSL_CIPHER_PARAM_IVLEN\fR and <\fBOSSL_CIPHER_PARAM_AEAD_IVLEN\fR) " 4 +.IX Item """ivlen"" (OSSL_CIPHER_PARAM_IVLEN and " +Gets the IV length for the cipher context \fIctx\fR. +The length of the "ivlen" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_iv_length()\fR. +.IP """iv"" (\fBOSSL_CIPHER_PARAM_IV\fR) " 4 +.IX Item """iv"" (OSSL_CIPHER_PARAM_IV) " +Gets the IV used to initialize the associated cipher context \fIctx\fR. +See also \fBEVP_CIPHER_CTX_get_original_iv()\fR. +.IP """updated\-iv"" (\fBOSSL_CIPHER_PARAM_UPDATED_IV\fR) " 4 +.IX Item """updated-iv"" (OSSL_CIPHER_PARAM_UPDATED_IV) " +Gets the updated pseudo\-IV state for the associated cipher context, e.g., +the previous ciphertext block for CBC mode or the iteratively encrypted IV +value for OFB mode. Note that octet pointer access is deprecated and is +provided only for backwards compatibility with historical libcrypto APIs. +See also \fBEVP_CIPHER_CTX_get_updated_iv()\fR. +.IP """randkey"" (\fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR) " 4 +.IX Item """randkey"" (OSSL_CIPHER_PARAM_RANDOM_KEY) " +Gets an implementation specific randomly generated key for the associated +cipher context \fIctx\fR. This is currently only supported by DES and 3DES (which set +the key to odd parity). +.IP """taglen"" (\fBOSSL_CIPHER_PARAM_AEAD_TAGLEN\fR) " 4 +.IX Item """taglen"" (OSSL_CIPHER_PARAM_AEAD_TAGLEN) " +Gets the tag length to be used for an AEAD cipher for the associated cipher +context \fIctx\fR. It gets a default value if it has not been set. +The length of the "taglen" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_tag_length()\fR. +.IP """tlsaadpad"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\fR) " 4 +.IX Item """tlsaadpad"" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) " +Gets the length of the tag that will be added to a TLS record for the AEAD +tag for the associated cipher context \fIctx\fR. +The length of the "tlsaadpad" parameter should not exceed that of a \fBsize_t\fR. +.IP """tlsivgen"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\fR) " 4 +.IX Item """tlsivgen"" (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) " +Gets the invocation field generated for encryption. +Can only be called after "tlsivfixed" is set. +This is only used for GCM mode. +.IP """tls1multi_enclen"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\fR) " 4 +.IX Item """tls1multi_enclen"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) " +Get the total length of the record returned from the "tls1multi_enc" operation. +.IP """tls1multi_maxbufsz"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\fR) " 4 +.IX Item """tls1multi_maxbufsz"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) " +Gets the maximum record length for a TLS1 multiblock cipher operation. +The length of the "tls1multi_maxbufsz" parameter should not exceed that of a \fBsize_t\fR. +.IP """tls1multi_aadpacklen"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\fR) " 4 +.IX Item """tls1multi_aadpacklen"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) " +Gets the result of running the "tls1multi_aad" operation. +.IP """tls\-mac"" (\fBOSSL_CIPHER_PARAM_TLS_MAC\fR) " 4 +.IX Item """tls-mac"" (OSSL_CIPHER_PARAM_TLS_MAC) " +Used to pass the TLS MAC data. +.IP """fips\-indicator"" (\fBOSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) " +This option is used by the OpenSSL FIPS provider. +.Sp +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling a cipher final operation such as +\&\fBEVP_EncryptFinal_ex()\fR. It may return 0 if the "encrypt\-check" option is set to 0. +.IP """iv\-generated"" (\fBOSSL_CIPHER_PARAM_AEAD_IV_GENERATED\fR) " 4 +.IX Item """iv-generated"" (OSSL_CIPHER_PARAM_AEAD_IV_GENERATED) " +An indicator that returns 1 if an IV was generated internally during encryption, +or O otherwise. +This may be used by GCM ciphers after calling a cipher final operation such +as \fBEVP_EncryptFinal_ex()\fR. +GCM should generate an IV internally if the IV is not specified during a +cipher initialisation call such as \fBEVP_CipherInit_ex()\fR. +See FIPS 140\-3 IG C.H for information related to IV requirements. +.SS "Settable EVP_CIPHER_CTX parameters" +.IX Subsection "Settable EVP_CIPHER_CTX parameters" +The following \fBOSSL_PARAM\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_set_params()\fR: +.IP """mackey"" (\fBOSSL_CIPHER_PARAM_AEAD_MAC_KEY\fR) " 4 +.IX Item """mackey"" (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) " +Sets the MAC key used by composite AEAD ciphers such as AES\-CBC\-HMAC\-SHA256. +.IP """speed"" (\fBOSSL_CIPHER_PARAM_SPEED\fR) " 4 +.IX Item """speed"" (OSSL_CIPHER_PARAM_SPEED) " +Sets the speed option for the associated cipher context. This is only supported +by AES SIV ciphers which disallow multiple operations by default. +Setting "speed" to 1 allows another encrypt or decrypt operation to be +performed. This is used for performance testing. +.IP """use\-bits"" (\fBOSSL_CIPHER_PARAM_USE_BITS\fR) " 4 +.IX Item """use-bits"" (OSSL_CIPHER_PARAM_USE_BITS) " +Determines if the input length \fIinl\fR passed to \fBEVP_EncryptUpdate()\fR, +\&\fBEVP_DecryptUpdate()\fR and \fBEVP_CipherUpdate()\fR is the number of bits or number of bytes. +Setting "use\-bits" to 1 uses bits. The default is in bytes. +This is only used for \fBCFB1\fR ciphers. +.Sp +This can be set using EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPH_FLAG_LENGTH_BITS). +.IP """tls\-version"" (\fBOSSL_CIPHER_PARAM_TLS_VERSION\fR) " 4 +.IX Item """tls-version"" (OSSL_CIPHER_PARAM_TLS_VERSION) " +Sets the TLS version. +.IP """tls\-mac\-size"" (\fBOSSL_CIPHER_PARAM_TLS_MAC_SIZE\fR) " 4 +.IX Item """tls-mac-size"" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) " +Set the TLS MAC size. +.IP """tlsaad"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD\fR) " 4 +.IX Item """tlsaad"" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) " +Sets TLSv1.2 AAD information for the associated cipher context \fIctx\fR. +TLSv1.2 AAD information is always 13 bytes in length and is as defined for the +"additional_data" field described in section 6.2.3.3 of RFC5246. +.IP """tlsivfixed"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\fR) " 4 +.IX Item """tlsivfixed"" (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) " +Sets the fixed portion of an IV for an AEAD cipher used in a TLS record +encryption/ decryption for the associated cipher context. +TLS record encryption/decryption always occurs "in place" so that the input and +output buffers are always the same memory location. +AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part +that varies with every record. +Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records. +TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per +record. +For a record decryption the first bytes of the input buffer will be the explicit +part of the IV and the final bytes of the input buffer will be the AEAD tag. +The length of the explicit part of the IV and the tag length will depend on the +cipher in use and will be defined in the RFC for the relevant ciphersuite. +In order to allow for "in place" decryption the plaintext output should be +written to the same location in the output buffer that the ciphertext payload +was read from, i.e. immediately after the explicit IV. +.Sp +When encrypting a record the first bytes of the input buffer should be empty to +allow space for the explicit IV, as will the final bytes where the tag will +be written. +The length of the input buffer will include the length of the explicit IV, the +payload, and the tag bytes. +The cipher implementation should generate the explicit IV and write it to the +beginning of the output buffer, do "in place" encryption of the payload and +write that to the output buffer, and finally add the tag onto the end of the +output buffer. +.Sp +Whether encrypting or decrypting the value written to \fI*outl\fR in the +OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit +IV length and the tag length. +.IP """tlsivinv"" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\fR) " 4 +.IX Item """tlsivinv"" (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) " +Sets the invocation field used for decryption. +Can only be called after "tlsivfixed" is set. +This is only used for GCM mode. +.IP """tls1multi_enc"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\fR) " 4 +.IX Item """tls1multi_enc"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) " +Triggers a multiblock TLS1 encrypt operation for a TLS1 aware cipher that +supports sending 4 or 8 records in one go. +The cipher performs both the MAC and encrypt stages and constructs the record +headers itself. +"tls1multi_enc" supplies the output buffer for the encrypt operation, +"tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply +values to the encrypt operation. +.IP """tls1multi_encin"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\fR) " 4 +.IX Item """tls1multi_encin"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) " +Supplies the data to encrypt for a TLS1 multiblock cipher operation. +.IP """tls1multi_maxsndfrag"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\fR) " 4 +.IX Item """tls1multi_maxsndfrag"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) " +Sets the maximum send fragment size for a TLS1 multiblock cipher operation. +It must be set before using "tls1multi_maxbufsz". +The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a \fBsize_t\fR. +.IP """tls1multi_aad"" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\fR) " 4 +.IX Item """tls1multi_aad"" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) " +Sets the authenticated additional data used by a TLS1 multiblock cipher operation. +The supplied data consists of 13 bytes of record data containing: +Bytes 0\-7: The sequence number of the first record +Byte 8: The record type +Byte 9\-10: The protocol version +Byte 11\-12: Input length (Always 0) +.Sp +"tls1multi_interleave" must also be set for this operation. +.IP """xts_standard"" (\fBOSSL_CIPHER_PARAM_XTS_STANDARD\fR) " 4 +.IX Item """xts_standard"" (OSSL_CIPHER_PARAM_XTS_STANDARD) " +Sets the XTS standard to use with SM4\-XTS algorithm. XTS mode has two +implementations, one is standardized in IEEE Std. 1619\-2007 and has +been widely used (e.g., XTS AES), the other is proposed recently +(GB/T 17964\-2021 implemented in May 2022) and is currently only used +in SM4. +.Sp +The main difference between them is the multiplication by the +primitive element α to calculate the tweak values. The IEEE +Std 1619\-2007 noted that the multiplication "is a left shift of each +byte by one bit with carry propagating from one byte to the next +one", which means that in each byte, the leftmost bit is the most +significant bit. But in GB/T 17964\-2021, the rightmost bit is the +most significant bit, thus the multiplication becomes a right shift +of each byte by one bit with carry propagating from one byte to the +next one. +.Sp +Valid values for the mode are: +.RS 4 +.IP """GB""" 4 +.IX Item """GB""" +The GB/T 17964\-2021 variant of SM4\-XTS algorithm. +.IP """IEEE""" 4 +.IX Item """IEEE""" +The IEEE Std. 1619\-2007 variant of SM4\-XTS algorithm. +.RE +.RS 4 +.Sp +The default value is "GB". +.RE +.IP """encrypt\-check"" (\fBOSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK\fR) " 4 +.IX Item """encrypt-check"" (OSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK) " +This option is used by the OpenSSL FIPS provider. +.Sp +If required this parameter should be set early via an cipher encrypt init +function such as \fBEVP_EncryptInit_ex2()\fR. +The default value of 1 causes an error when an encryption operation is triggered. +Setting this to 0 will ignore the error and set the approved "fips\-indicator" to +0. +This option breaks FIPS compliance if it causes the approved "fips\-indicator" +to return 0. +.SH CONTROLS +.IX Header "CONTROLS" +The Mappings from \fBEVP_CIPHER_CTX_ctrl()\fR identifiers to PARAMETERS are listed +in the following section. See the "PARAMETERS" section for more details. +.PP +\&\fBEVP_CIPHER_CTX_ctrl()\fR can be used to send the following standard controls: +.IP "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN" 4 +.IX Item "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the +key "ivlen" (\fBOSSL_CIPHER_PARAM_IVLEN\fR). +.IP EVP_CTRL_AEAD_SET_IV_FIXED 4 +.IX Item "EVP_CTRL_AEAD_SET_IV_FIXED" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "tlsivfixed" +(\fBOSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\fR). +.IP EVP_CTRL_AEAD_SET_MAC_KEY 4 +.IX Item "EVP_CTRL_AEAD_SET_MAC_KEY" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "mackey" +(\fBOSSL_CIPHER_PARAM_AEAD_MAC_KEY\fR). +.IP "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG" 4 +.IX Item "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the +key "tag" (\fBOSSL_CIPHER_PARAM_AEAD_TAG\fR). +.IP EVP_CTRL_CCM_SET_L 4 +.IX Item "EVP_CTRL_CCM_SET_L" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "ivlen" (\fBOSSL_CIPHER_PARAM_IVLEN\fR) +with a value of (15 \- L) +.IP EVP_CTRL_COPY 4 +.IX Item "EVP_CTRL_COPY" +There is no OSSL_PARAM mapping for this. Use \fBEVP_CIPHER_CTX_copy()\fR instead. +.IP EVP_CTRL_GCM_SET_IV_INV 4 +.IX Item "EVP_CTRL_GCM_SET_IV_INV" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "tlsivinv" +(\fBOSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\fR). +.IP EVP_CTRL_RAND_KEY 4 +.IX Item "EVP_CTRL_RAND_KEY" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "randkey" +(\fBOSSL_CIPHER_PARAM_RANDOM_KEY\fR). +.IP EVP_CTRL_SET_KEY_LENGTH 4 +.IX Item "EVP_CTRL_SET_KEY_LENGTH" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "keylen" (\fBOSSL_CIPHER_PARAM_KEYLEN\fR). +.IP "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS" 4 +.IX Item "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the +key "keybits" (\fBOSSL_CIPHER_PARAM_RC2_KEYBITS\fR). +.IP "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS" 4 +.IX Item "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \fBOSSL_PARAM\fR\|(3) item with the +key "rounds" (\fBOSSL_CIPHER_PARAM_ROUNDS\fR). +.IP EVP_CTRL_SET_SPEED 4 +.IX Item "EVP_CTRL_SET_SPEED" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key "speed" (\fBOSSL_CIPHER_PARAM_SPEED\fR). +.IP EVP_CTRL_GCM_IV_GEN 4 +.IX Item "EVP_CTRL_GCM_IV_GEN" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_get_params()\fR gets called +with an \fBOSSL_PARAM\fR\|(3) item with the key +"tlsivgen" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\fR). +.IP EVP_CTRL_AEAD_TLS1_AAD 4 +.IX Item "EVP_CTRL_AEAD_TLS1_AAD" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR get called +with an \fBOSSL_PARAM\fR\|(3) item with the key +"tlsaad" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD\fR) +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +"tlsaadpad" (\fBOSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\fR). +.IP EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE" +When used with a fetched \fBEVP_CIPHER\fR, +\&\fBEVP_CIPHER_CTX_set_params()\fR gets called with an \fBOSSL_PARAM\fR\|(3) item with the +key OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +"tls1multi_maxbufsz" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\fR). +.IP EVP_CTRL_TLS1_1_MULTIBLOCK_AAD 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_AAD" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with \fBOSSL_PARAM\fR\|(3) items with the keys +"tls1multi_aad" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\fR) and +"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR) +followed by \fBEVP_CIPHER_CTX_get_params()\fR with keys of +"tls1multi_aadpacklen" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\fR) and +"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR). +.IP EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT" +When used with a fetched \fBEVP_CIPHER\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with \fBOSSL_PARAM\fR\|(3) items with the keys +"tls1multi_enc" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\fR), +"tls1multi_encin" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\fR) and +"tls1multi_interleave" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\fR), +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +"tls1multi_enclen" (\fBOSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\fR). +.SH FLAGS +.IX Header "FLAGS" +\&\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR. +can be used to manipulate and test these \fBEVP_CIPHER_CTX\fR flags: +.IP EVP_CIPH_NO_PADDING 4 +.IX Item "EVP_CIPH_NO_PADDING" +Used by \fBEVP_CIPHER_CTX_set_padding()\fR. +.Sp +See also "Gettable and Settable EVP_CIPHER_CTX parameters" "padding" +.IP EVP_CIPH_FLAG_LENGTH_BITS 4 +.IX Item "EVP_CIPH_FLAG_LENGTH_BITS" +See "Settable EVP_CIPHER_CTX parameters" "use\-bits". +.IP EVP_CIPHER_CTX_FLAG_WRAP_ALLOW 4 +.IX Item "EVP_CIPHER_CTX_FLAG_WRAP_ALLOW" +Used for Legacy purposes only. This flag needed to be set to indicate the +cipher handled wrapping. +.PP +\&\fBEVP_CIPHER_flags()\fR uses the following flags that +have mappings to "Gettable EVP_CIPHER parameters": +.IP EVP_CIPH_FLAG_AEAD_CIPHER 4 +.IX Item "EVP_CIPH_FLAG_AEAD_CIPHER" +See "Gettable EVP_CIPHER parameters" "aead". +.IP EVP_CIPH_CUSTOM_IV 4 +.IX Item "EVP_CIPH_CUSTOM_IV" +See "Gettable EVP_CIPHER parameters" "custom\-iv". +.IP EVP_CIPH_FLAG_CTS 4 +.IX Item "EVP_CIPH_FLAG_CTS" +See "Gettable EVP_CIPHER parameters" "cts". +.IP EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK; 4 +.IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;" +See "Gettable EVP_CIPHER parameters" "tls\-multi". +.IP EVP_CIPH_RAND_KEY 4 +.IX Item "EVP_CIPH_RAND_KEY" +See "Gettable EVP_CIPHER parameters" "has\-randkey". +.PP +\&\fBEVP_CIPHER_flags()\fR uses the following flags for legacy purposes only: +.IP EVP_CIPH_VARIABLE_LENGTH 4 +.IX Item "EVP_CIPH_VARIABLE_LENGTH" +.PD 0 +.IP EVP_CIPH_FLAG_CUSTOM_CIPHER 4 +.IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER" +.IP EVP_CIPH_ALWAYS_CALL_INIT 4 +.IX Item "EVP_CIPH_ALWAYS_CALL_INIT" +.IP EVP_CIPH_CTRL_INIT 4 +.IX Item "EVP_CIPH_CTRL_INIT" +.IP EVP_CIPH_CUSTOM_KEY_LENGTH 4 +.IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH" +.IP EVP_CIPH_CUSTOM_COPY 4 +.IX Item "EVP_CIPH_CUSTOM_COPY" +.IP EVP_CIPH_FLAG_DEFAULT_ASN1 4 +.IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1" +.PD +See \fBEVP_CIPHER_meth_set_flags\fR\|(3) for further information related to the above +flags. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_CIPHER_fetch()\fR returns a pointer to a \fBEVP_CIPHER\fR for success +and NULL for failure. +.PP +\&\fBEVP_CIPHER_up_ref()\fR returns 1 for success or 0 otherwise. +.PP +\&\fBEVP_CIPHER_CTX_new()\fR returns a pointer to a newly created +\&\fBEVP_CIPHER_CTX\fR for success and NULL for failure. +.PP +\&\fBEVP_CIPHER_CTX_dup()\fR returns a new EVP_CIPHER_CTX if successful or NULL on failure. +.PP +\&\fBEVP_CIPHER_CTX_copy()\fR returns 1 if successful or 0 for failure. +.PP +\&\fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal_ex()\fR +return 1 for success and 0 for failure. +.PP +\&\fBEVP_DecryptInit_ex2()\fR and \fBEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. +\&\fBEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success. +.PP +\&\fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherInit_SKEY()\fR and \fBEVP_CipherUpdate()\fR return 1 for +success and 0 for failure. +\&\fBEVP_CipherFinal_ex()\fR returns 0 for an encryption/decryption failure or 1 for +success. +.PP +\&\fBEVP_Cipher()\fR returns 1 on success and <= 0 on failure, if the flag +\&\fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR is not set for the cipher, or if the cipher has +not been initialized via a call to \fBEVP_CipherInit_ex2\fR. +\&\fBEVP_Cipher()\fR returns the number of bytes written to \fIout\fR for +encryption/decryption, or the number of bytes authenticated in a call specifying +AAD for an AEAD cipher, if the flag \fBEVP_CIPH_FLAG_CUSTOM_CIPHER\fR is set for +the cipher. +.PP +\&\fBEVP_CIPHER_can_pipeline()\fR returns 1 if the cipher can be used in a pipeline, 0 otherwise. +.PP +\&\fBEVP_CipherPipelineEncryptInit()\fR and \fBEVP_CipherPipelineDecryptInit()\fR +return 1 for success and 0 for failure. +.PP +\&\fBEVP_CipherPipelineUpdate()\fR and \fBEVP_CipherPipelineFinal()\fR +return 1 for success and 0 for failure. +.PP +\&\fBEVP_CIPHER_CTX_reset()\fR returns 1 for success and 0 for failure. +.PP +\&\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR +return an \fBEVP_CIPHER\fR structure or NULL on error. +.PP +\&\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR return a NID. +.PP +\&\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR return the +block size, or 0 on error. +.PP +\&\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR return the key +length. +.PP +\&\fBEVP_CIPHER_CTX_set_padding()\fR always returns 1. +.PP +\&\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR return the IV +length, zero if the cipher does not use an IV and a negative value on error. +.PP +\&\fBEVP_CIPHER_CTX_get_tag_length()\fR return the tag length or zero if the cipher +does not use a tag. +.PP +\&\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR return the NID of the +cipher\*(Aqs OBJECT IDENTIFIER or NID_undef if it has no defined +OBJECT IDENTIFIER. +.PP +\&\fBEVP_CIPHER_CTX_cipher()\fR returns an \fBEVP_CIPHER\fR structure. +.PP +\&\fBEVP_CIPHER_CTX_get_num()\fR returns a nonnegative num value or +\&\fBEVP_CTRL_RET_UNSUPPORTED\fR if the implementation does not support the call +or on any other error. +.PP +\&\fBEVP_CIPHER_CTX_set_num()\fR returns 1 on success and 0 if the implementation +does not support the call or on any other error. +.PP +\&\fBEVP_CIPHER_CTX_is_encrypting()\fR returns 1 if the \fIctx\fR is set up for encryption +0 otherwise. +.PP +\&\fBEVP_CIPHER_param_to_asn1()\fR and \fBEVP_CIPHER_asn1_to_param()\fR return greater +than zero for success and zero or a negative number on failure. +.PP +\&\fBEVP_CIPHER_CTX_rand_key()\fR returns 1 for success and zero or a negative number +for failure. +.PP +\&\fBEVP_CIPHER_names_do_all()\fR returns 1 if the callback was called for all names. +A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_CIPHER_get_params()\fR, \fBEVP_CIPHER_CTX_get_params()\fR and +\&\fBEVP_CIPHER_CTX_set_params()\fR return 1 for success and 0 for failure. +.SH "CIPHER LISTING" +.IX Header "CIPHER LISTING" +All algorithms have a fixed key length unless otherwise stated. +.PP +Refer to "SEE ALSO" for the full list of ciphers available through the EVP +interface. +.IP \fBEVP_enc_null()\fR 4 +.IX Item "EVP_enc_null()" +Null cipher: does nothing. +.SH "AEAD INTERFACE" +.IX Header "AEAD INTERFACE" +The EVP interface for Authenticated Encryption with Associated Data (AEAD) +modes are subtly altered and several additional \fIctrl\fR operations are supported +depending on the mode specified. +.PP +To specify additional authenticated data (AAD), a call to \fBEVP_CipherUpdate()\fR, +\&\fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made with the output +parameter \fIout\fR set to NULL. In this case, on success, the parameter +\&\fIoutl\fR is set to the number of AAD bytes processed in that call +(that is, the value of \fIinl\fR), and does not include any plaintext +or ciphertext bytes processed by other calls. +.PP +If no AAD is used, this call can be omitted. See the mode\-specific notes +below for any exceptions. +.PP +When decrypting, the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR +indicates whether the operation was successful. If it does not indicate success, +the authentication operation has failed and any output data \fBMUST NOT\fR be used +as it is corrupted. +.PP +Please note that the number of authenticated bytes returned by +\&\fBEVP_CipherUpdate()\fR depends on the cipher used. Stream ciphers, such as ChaCha20 +or ciphers in GCM mode, can handle 1 byte at a time, resulting in an effective +"block" size of 1. Conversely, ciphers in OCB mode must process data one block +at a time, and the block size is returned. +.PP +Regardless of the returned size, it is safe to pass unpadded data to an +\&\fBEVP_CipherUpdate()\fR call in a single operation. +.SS "GCM and OCB Modes" +.IX Subsection "GCM and OCB Modes" +The following \fIctrl\fRs are supported in GCM and OCB modes. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" +Sets the IV length. This call can only be made before specifying an IV. If +not called a default IV length is used. +.Sp +For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the +maximum is 15. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" +Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR. +This call can only be made when encrypting data and \fBafter\fR all data has been +processed (e.g. after an \fBEVP_EncryptFinal()\fR call). +.Sp +For OCB, \f(CW\*(C`taglen\*(C'\fR must either be 16 or the value previously set via +\&\fBEVP_CTRL_AEAD_SET_TAG\fR. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" +When decrypting, this call sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR. +\&\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 inclusive. +The tag must be set prior to any call to \fBEVP_DecryptFinal()\fR or +\&\fBEVP_DecryptFinal_ex()\fR. +.Sp +For GCM, this call is only valid when decrypting data. +.Sp +For OCB, this call is valid when decrypting data to set the expected tag, +and when encrypting to set the desired tag length. +.Sp +In OCB mode, calling this with \f(CW\*(C`tag\*(C'\fR set to \f(CW\*(C`NULL\*(C'\fR sets the tag length. +The tag length can only be set before specifying an IV. If this is not called +prior to setting the IV, then a default tag length is used. +.Sp +For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the +maximum tag length for OCB. +.SS "CCM Mode" +.IX Subsection "CCM Mode" +The EVP interface for CCM mode is similar to that of the GCM mode but with a +few additional requirements and different \fIctrl\fR values. +.PP +For CCM mode, the total plaintext or ciphertext length \fBMUST\fR be passed to +\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR with the output +and input parameters (\fIin\fR and \fIout\fR) set to NULL and the length passed in +the \fIinl\fR parameter. +.PP +The following \fIctrl\fRs are supported in CCM mode. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" +This call is made to set the expected \fBCCM\fR tag value when decrypting or +the length of the tag (with the \f(CW\*(C`tag\*(C'\fR parameter set to NULL) when encrypting. +The tag length is often referred to as \fBM\fR. If not set a default value is +used (12 for AES). When decrypting, the tag needs to be set before passing +in data to be decrypted, but as in GCM and OCB mode, it can be set after +passing additional authenticated data (see "AEAD INTERFACE"). +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)" +Sets the CCM \fBL\fR value. If not set a default is used (8 for AES). +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" +Sets the CCM nonce (IV) length. This call can only be made before specifying a +nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default for +AES. +.SS "SIV Mode" +.IX Subsection "SIV Mode" +Both the AES\-SIV and AES\-GCM\-SIV ciphers fall under this mode. +.PP +For SIV mode ciphers the behaviour of the EVP interface is subtly +altered and several additional ctrl operations are supported. +.PP +To specify any additional authenticated data (AAD) and/or a Nonce, a call to +\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made +with the output parameter \fIout\fR set to NULL. +.PP +RFC5297 states that the Nonce is the last piece of AAD before the actual +encrypt/decrypt takes place. The API does not differentiate the Nonce from +other AAD. +.PP +When decrypting the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR +indicates if the operation was successful. If it does not indicate success +the authentication operation has failed and any output data \fBMUST NOT\fR +be used as it is corrupted. +.PP +The API does not store the SIV (Synthetic Initialization Vector) in +the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX. +The SIV must be retrieved from the context after encryption, and set into +the context before decryption. +.PP +This differs from RFC5297 in that the cipher output from encryption, and +the cipher input to decryption, does not contain the SIV. This also means +that the plain text and cipher text lengths are identical. +.PP +The following ctrls are supported in SIV mode, and are used to get and set +the Synthetic Initialization Vector: +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);" +Writes \fItaglen\fR bytes of the tag value (the Synthetic Initialization Vector) +to the buffer indicated by \fItag\fR. This call can only be made when encrypting +data and \fBafter\fR all data has been processed (e.g. after an \fBEVP_EncryptFinal()\fR +call). For SIV mode the taglen must be 16. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);" +Sets the expected tag (the Synthetic Initialization Vector) to \fItaglen\fR +bytes from \fItag\fR. This call is only legal when decrypting data and must be +made \fBbefore\fR any data is processed (e.g. before any \fBEVP_DecryptUpdate()\fR +calls). For SIV mode the taglen must be 16. +.PP +SIV mode makes two passes over the input data, thus, only one call to +\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made +with \fIout\fR set to a non\-NULL value. A call to \fBEVP_DecryptFinal()\fR or +\&\fBEVP_CipherFinal()\fR is not required, but will indicate if the update +operation succeeded. +.SS ChaCha20\-Poly1305 +.IX Subsection "ChaCha20-Poly1305" +The following \fIctrl\fRs are supported for the ChaCha20\-Poly1305 AEAD algorithm. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" +Sets the nonce length. This call is now redundant since the only valid value +is the default length of 12 (i.e. 96 bits). +Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically +pad the iv with leading 0 bytes to make it 12 bytes in length. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" +Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR. +This call can only be made when encrypting data and \fBafter\fR all data has been +processed (e.g. after an \fBEVP_EncryptFinal()\fR call). +.Sp +\&\f(CW\*(C`taglen\*(C'\fR specified here must be 16 (\fBPOLY1305_BLOCK_SIZE\fR, i.e. 128\-bits) or +less. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)" +Sets the expected tag to \f(CW\*(C`taglen\*(C'\fR bytes from \f(CW\*(C`tag\*(C'\fR. +The tag length can only be set before specifying an IV. +\&\f(CW\*(C`taglen\*(C'\fR must be between 1 and 16 (\fBPOLY1305_BLOCK_SIZE\fR) inclusive. +This call is only valid when decrypting data. +.SH NOTES +.IX Header "NOTES" +Where possible the \fBEVP\fR interface to symmetric ciphers should be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the cipher used and much more flexible. Additionally, the +\&\fBEVP\fR interface will ensure the use of platform specific cryptographic +acceleration such as AES\-NI (the low\-level interfaces do not provide the +guarantee). +.PP +PKCS padding works by adding \fBn\fR padding bytes of value \fBn\fR to make the total +length of the encrypted data a multiple of the block size. Padding is always +added so if the data is already a multiple of the block size \fBn\fR will equal +the block size. For example if the block size is 8 and 11 bytes are to be +encrypted then 5 padding bytes of value 5 will be added. +.PP +When decrypting the final block is checked to see if it has the correct form. +.PP +Although the decryption operation can produce an error if padding is enabled, +it is not a strong test that the input data or key is correct. A random block +has better than 1 in 256 chance of being of the correct format and problems with +the input data earlier on will not produce a final decrypt error. +.PP +If padding is disabled then the decryption operation will always succeed if +the total amount of data decrypted is a multiple of the block size. +.PP +The functions \fBEVP_EncryptInit()\fR, \fBEVP_EncryptInit_ex()\fR, +\&\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptInit()\fR, \fBEVP_DecryptInit_ex()\fR, +\&\fBEVP_CipherInit()\fR, \fBEVP_CipherInit_ex()\fR and \fBEVP_CipherFinal()\fR are obsolete +but are retained for compatibility with existing code. New code should +use \fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptInit_ex2()\fR, +\&\fBEVP_DecryptFinal_ex()\fR, \fBEVP_CipherInit_ex2()\fR and \fBEVP_CipherFinal_ex()\fR +because they can reuse an existing context without allocating and freeing +it up on each call. +.PP +There are some differences between functions \fBEVP_CipherInit()\fR and +\&\fBEVP_CipherInit_ex()\fR, significant in some circumstances. \fBEVP_CipherInit()\fR fills +the passed context object with zeros. As a consequence, \fBEVP_CipherInit()\fR does +not allow step\-by\-step initialization of the ctx when the \fIkey\fR and \fIiv\fR are +passed in separate calls. It also means that the flags set for the CTX are +removed, and it is especially important for the +\&\fBEVP_CIPHER_CTX_FLAG_WRAP_ALLOW\fR flag treated specially in +\&\fBEVP_CipherInit_ex()\fR. +.PP +Ignoring failure returns of the \fBEVP_CIPHER_CTX\fR initialization functions can +lead to subsequent undefined behavior when calling the functions that update or +finalize the context. The only valid calls on the \fBEVP_CIPHER_CTX\fR when +initialization fails are calls that attempt another initialization of the +context or release the context. +.PP +\&\fBEVP_get_cipherbynid()\fR, and \fBEVP_get_cipherbyobj()\fR are implemented as macros. +.SH BUGS +.IX Header "BUGS" +\&\fBEVP_MAX_KEY_LENGTH\fR and \fBEVP_MAX_IV_LENGTH\fR only refer to the internal +ciphers with default key lengths. If custom ciphers exceed these values the +results are unpredictable. This is because it has become standard practice to +define a generic key as a fixed unsigned char array containing +\&\fBEVP_MAX_KEY_LENGTH\fR bytes. +.PP +The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested +for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. +.SH EXAMPLES +.IX Header "EXAMPLES" +Encrypt a string using IDEA: +.PP +.Vb 10 +\& int do_crypt(char *outfile) +\& { +\& unsigned char outbuf[1024]; +\& int outlen, tmplen; +\& /* +\& * Bogus key and IV: we\*(Aqd normally set these from +\& * another source. +\& */ +\& unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; +\& unsigned char iv[] = {1,2,3,4,5,6,7,8}; +\& char intext[] = "Some Crypto Text"; +\& EVP_CIPHER_CTX *ctx; +\& FILE *out; +\& +\& ctx = EVP_CIPHER_CTX_new(); +\& if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } +\& +\& if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } +\& /* +\& * Buffer passed to EVP_EncryptFinal() must be after data just +\& * encrypted to avoid overwriting it. +\& */ +\& if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } +\& outlen += tmplen; +\& EVP_CIPHER_CTX_free(ctx); +\& /* +\& * Need binary mode for fopen because encrypted data is +\& * binary data. Also cannot use strlen() on it because +\& * it won\*(Aqt be NUL terminated and may contain embedded +\& * NULs. +\& */ +\& out = fopen(outfile, "wb"); +\& if (out == NULL) { +\& /* Error */ +\& return 0; +\& } +\& fwrite(outbuf, 1, outlen, out); +\& fclose(out); +\& return 1; +\& } +.Ve +.PP +The ciphertext from the above example can be decrypted using the \fBopenssl\fR +utility with the command line (shown on two lines for clarity): +.PP +.Vb 2 +\& openssl idea \-d \e +\& \-K 000102030405060708090A0B0C0D0E0F \-iv 0102030405060708 = 16. +\& */ +\& int ret = 0, encrypt = 1, outlen, len; +\& EVP_CIPHER_CTX *ctx = NULL; +\& EVP_CIPHER *cipher = NULL; +\& OSSL_PARAM params[2]; +\& +\& ctx = EVP_CIPHER_CTX_new(); +\& cipher = EVP_CIPHER_fetch(NULL, "AES\-256\-CBC\-CTS", NULL); +\& if (ctx == NULL || cipher == NULL) +\& goto err; +\& +\& /* +\& * The default is "CS1" so this is not really needed, +\& * but would be needed to set either "CS2" or "CS3". +\& */ +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, +\& "CS1", 0); +\& params[1] = OSSL_PARAM_construct_end(); +\& +\& if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params)) +\& goto err; +\& +\& /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ +\& if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len)) +\& goto err; +\& if (!EVP_CipherFinal_ex(ctx, out + outlen, &len)) +\& goto err; +\& ret = 1; +\& err: +\& EVP_CIPHER_free(cipher); +\& EVP_CIPHER_CTX_free(ctx); +\& return ret; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBproperty\fR\|(7), +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), +\&\fBprovider\-cipher\fR\|(7), +\&\fBlife_cycle\-cipher\fR\|(7) +.PP +Supported ciphers are listed in: +.PP +\&\fBEVP_aes_128_gcm\fR\|(3), +\&\fBEVP_aria_128_gcm\fR\|(3), +\&\fBEVP_bf_cbc\fR\|(3), +\&\fBEVP_camellia_128_ecb\fR\|(3), +\&\fBEVP_cast5_cbc\fR\|(3), +\&\fBEVP_chacha20\fR\|(3), +\&\fBEVP_des_cbc\fR\|(3), +\&\fBEVP_desx_cbc\fR\|(3), +\&\fBEVP_idea_cbc\fR\|(3), +\&\fBEVP_rc2_cbc\fR\|(3), +\&\fBEVP_rc4\fR\|(3), +\&\fBEVP_rc5_32_12_16_cbc\fR\|(3), +\&\fBEVP_seed_cbc\fR\|(3), +\&\fBEVP_sm4_cbc\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +Support for OCB mode was added in OpenSSL 1.1.0. +.PP +\&\fBEVP_CIPHER_CTX\fR was made opaque in OpenSSL 1.1.0. As a result, +\&\fBEVP_CIPHER_CTX_reset()\fR appeared and \fBEVP_CIPHER_CTX_cleanup()\fR +disappeared. \fBEVP_CIPHER_CTX_init()\fR remains as an alias for +\&\fBEVP_CIPHER_CTX_reset()\fR. +.PP +The \fBEVP_CIPHER_CTX_cipher()\fR function was deprecated in OpenSSL 3.0; use +\&\fBEVP_CIPHER_CTX_get0_cipher()\fR instead. +.PP +The \fBEVP_EncryptInit_ex2()\fR, \fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherInit_ex2()\fR, +\&\fBEVP_CIPHER_fetch()\fR, \fBEVP_CIPHER_free()\fR, \fBEVP_CIPHER_up_ref()\fR, +\&\fBEVP_CIPHER_CTX_get0_cipher()\fR, \fBEVP_CIPHER_CTX_get1_cipher()\fR, +\&\fBEVP_CIPHER_get_params()\fR, \fBEVP_CIPHER_CTX_set_params()\fR, +\&\fBEVP_CIPHER_CTX_get_params()\fR, \fBEVP_CIPHER_gettable_params()\fR, +\&\fBEVP_CIPHER_settable_ctx_params()\fR, \fBEVP_CIPHER_gettable_ctx_params()\fR, +\&\fBEVP_CIPHER_CTX_settable_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR +functions were added in 3.0. +.PP +The \fBEVP_CIPHER_nid()\fR, \fBEVP_CIPHER_name()\fR, \fBEVP_CIPHER_block_size()\fR, +\&\fBEVP_CIPHER_key_length()\fR, \fBEVP_CIPHER_iv_length()\fR, \fBEVP_CIPHER_flags()\fR, +\&\fBEVP_CIPHER_mode()\fR, \fBEVP_CIPHER_type()\fR, \fBEVP_CIPHER_CTX_nid()\fR, +\&\fBEVP_CIPHER_CTX_block_size()\fR, \fBEVP_CIPHER_CTX_key_length()\fR, +\&\fBEVP_CIPHER_CTX_iv_length()\fR, \fBEVP_CIPHER_CTX_tag_length()\fR, +\&\fBEVP_CIPHER_CTX_num()\fR, \fBEVP_CIPHER_CTX_type()\fR, and \fBEVP_CIPHER_CTX_mode()\fR +functions were renamed to include \f(CW\*(C`get\*(C'\fR or \f(CW\*(C`get0\*(C'\fR in their names in +OpenSSL 3.0, respectively. The old names are kept as non\-deprecated +alias macros. +.PP +The \fBEVP_CIPHER_CTX_encrypting()\fR function was renamed to +\&\fBEVP_CIPHER_CTX_is_encrypting()\fR in OpenSSL 3.0. The old name is kept as +non\-deprecated alias macro. +.PP +The \fBEVP_CIPHER_CTX_flags()\fR macro was deprecated in OpenSSL 1.1.0. +.PP +\&\fBEVP_CIPHER_CTX_dup()\fR was added in OpenSSL 3.2. +.PP +\&\fBEVP_CipherInit_SKEY()\fR was added in OpenSSL 3.5. +.PP +Prior to OpenSSL 3.5, passing a NULL \fIctx\fR to +\&\fBEVP_CIPHER_CTX_get_block_size()\fR would result in a NULL pointer dereference, +rather than a 0 return value indicating an error. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_KDF.3 b/static/netbsd/man3/EVP_KDF.3 new file mode 100644 index 00000000..e8e0fe4b --- /dev/null +++ b/static/netbsd/man3/EVP_KDF.3 @@ -0,0 +1,353 @@ +.\" $NetBSD: EVP_KDF.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KDF 3" +.TH EVP_KDF 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref, +EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup, +EVP_KDF_CTX_reset, EVP_KDF_derive, +EVP_KDF_CTX_get_kdf_size, +EVP_KDF_get0_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a, +EVP_KDF_get0_name, EVP_KDF_names_do_all, EVP_KDF_get0_description, +EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided, +EVP_KDF_get_params, EVP_KDF_gettable_params, +EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params, +EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params \- EVP KDF routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_kdf_st EVP_KDF; +\& typedef struct evp_kdf_ctx_st EVP_KDF_CTX; +\& +\& EVP_KDF_CTX *EVP_KDF_CTX_new(EVP_KDF *kdf); +\& const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx); +\& void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx); +\& EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src); +\& void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx); +\& size_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx); +\& int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& int EVP_KDF_up_ref(EVP_KDF *kdf); +\& void EVP_KDF_free(EVP_KDF *kdf); +\& EVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, +\& const char *properties); +\& int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name); +\& const char *EVP_KDF_get0_name(const EVP_KDF *kdf); +\& const char *EVP_KDF_get0_description(const EVP_KDF *kdf); +\& const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf); +\& void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_KDF *kdf, void *arg), +\& void *arg); +\& int EVP_KDF_names_do_all(const EVP_KDF *kdf, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]); +\& int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]); +\& int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf); +\& const OSSL_PARAM *EVP_KDF_gettable_ctx_params(const EVP_KDF *kdf); +\& const OSSL_PARAM *EVP_KDF_settable_ctx_params(const EVP_KDF *kdf); +\& const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf); +\& const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf); +\& const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP KDF routines are a high\-level interface to Key Derivation Function +algorithms and should be used instead of algorithm\-specific functions. +.PP +After creating a \fBEVP_KDF_CTX\fR for the required algorithm using +\&\fBEVP_KDF_CTX_new()\fR, inputs to the algorithm are supplied either by +passing them as part of the \fBEVP_KDF_derive()\fR call or using calls +to \fBEVP_KDF_CTX_set_params()\fR before calling \fBEVP_KDF_derive()\fR to derive +the key. +.SS Types +.IX Subsection "Types" +\&\fBEVP_KDF\fR is a type that holds the implementation of a KDF. +.PP +\&\fBEVP_KDF_CTX\fR is a context type that holds the algorithm inputs. +.SS "Algorithm implementation fetching" +.IX Subsection "Algorithm implementation fetching" +\&\fBEVP_KDF_fetch()\fR fetches an implementation of a KDF \fIalgorithm\fR, given +a library context \fIlibctx\fR and a set of \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +See "Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-default\fR\|(7) for the lists of +algorithms supported by the default provider. +.PP +The returned value must eventually be freed with +\&\fBEVP_KDF_free\fR\|(3). +.PP +\&\fBEVP_KDF_up_ref()\fR increments the reference count of an already fetched +KDF. +.PP +\&\fBEVP_KDF_free()\fR frees a fetched algorithm. +NULL is a valid parameter, for which this function is a no\-op. +.SS "Context manipulation functions" +.IX Subsection "Context manipulation functions" +\&\fBEVP_KDF_CTX_new()\fR creates a new context for the KDF implementation \fIkdf\fR. +.PP +\&\fBEVP_KDF_CTX_free()\fR frees up the context \fIctx\fR. If \fIctx\fR is NULL, nothing +is done. +.PP +\&\fBEVP_KDF_CTX_kdf()\fR returns the \fBEVP_KDF\fR associated with the context +\&\fIctx\fR. +.SS "Computing functions" +.IX Subsection "Computing functions" +\&\fBEVP_KDF_CTX_reset()\fR resets the context to the default state as if the context +had just been created. +.PP +\&\fBEVP_KDF_derive()\fR processes any parameters in \fIParams\fR and then derives +\&\fIkeylen\fR bytes of key material and places it in the \fIkey\fR buffer. +If the algorithm produces a fixed amount of output then an error will +occur unless the \fIkeylen\fR parameter is equal to that output size, +as returned by \fBEVP_KDF_CTX_get_kdf_size()\fR. +.PP +\&\fBEVP_KDF_get_params()\fR retrieves details about the implementation +\&\fIkdf\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_KDF_CTX_get_params()\fR retrieves chosen parameters, given the +context \fIctx\fR and its underlying context. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_KDF_CTX_set_params()\fR passes chosen parameters to the underlying +context, given a context \fIctx\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters are passed down. +Note that a parameter that is unknown in the underlying context is +simply ignored. +Also, what happens when a needed parameter isn\*(Aqt passed down is +defined by the implementation. +.PP +\&\fBEVP_KDF_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array that describes +the retrievable and settable parameters. \fBEVP_KDF_gettable_params()\fR +returns parameters that can be used with \fBEVP_KDF_get_params()\fR. +.PP +\&\fBEVP_KDF_gettable_ctx_params()\fR and \fBEVP_KDF_CTX_gettable_params()\fR +return constant \fBOSSL_PARAM\fR\|(3) arrays that describe the retrievable +parameters that can be used with \fBEVP_KDF_CTX_get_params()\fR. +\&\fBEVP_KDF_gettable_ctx_params()\fR returns the parameters that can be retrieved +from the algorithm, whereas \fBEVP_KDF_CTX_gettable_params()\fR returns +the parameters that can be retrieved in the context\*(Aqs current state. +.PP +\&\fBEVP_KDF_settable_ctx_params()\fR and \fBEVP_KDF_CTX_settable_params()\fR return +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the settable parameters that +can be used with \fBEVP_KDF_CTX_set_params()\fR. \fBEVP_KDF_settable_ctx_params()\fR +returns the parameters that can be retrieved from the algorithm, +whereas \fBEVP_KDF_CTX_settable_params()\fR returns the parameters that can +be retrieved in the context\*(Aqs current state. +.SS "Information functions" +.IX Subsection "Information functions" +\&\fBEVP_KDF_CTX_get_kdf_size()\fR returns the output size if the algorithm produces a fixed amount +of output and \fBSIZE_MAX\fR otherwise. If an error occurs then 0 is returned. +For some algorithms an error may result if input parameters necessary to +calculate a fixed output size have not yet been supplied. +.PP +\&\fBEVP_KDF_is_a()\fR returns 1 if \fIkdf\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR, otherwise 0. +.PP +\&\fBEVP_KDF_get0_provider()\fR returns the provider that holds the implementation +of the given \fIkdf\fR. +.PP +\&\fBEVP_KDF_do_all_provided()\fR traverses all KDF implemented by all activated +providers in the given library context \fIlibctx\fR, and for each of the +implementations, calls the given function \fIfn\fR with the implementation method +and the given \fIarg\fR as argument. +.PP +\&\fBEVP_KDF_get0_name()\fR return the name of the given KDF. For fetched KDFs +with multiple names, only one of them is returned; it\*(Aqs +recommended to use \fBEVP_KDF_names_do_all()\fR instead. +.PP +\&\fBEVP_KDF_names_do_all()\fR traverses all names for \fIkdf\fR, and calls +\&\fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_KDF_get0_description()\fR returns a description of the \fIkdf\fR, meant for +display and human consumption. The description is at the discretion of +the \fIkdf\fR implementation. +.SH PARAMETERS +.IX Header "PARAMETERS" +The standard parameter names are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) " 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) " +Some KDF implementations require a password. +For those KDF implementations that support it, this parameter sets the password. +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) " +Some KDF implementations can take a non\-secret unique cryptographic salt. +For those KDF implementations that support it, this parameter sets the salt. +.Sp +The default value, if any, is implementation dependent. +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) " 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) " +Some KDF implementations require an iteration count. +For those KDF implementations that support it, this parameter sets the +iteration count. +.Sp +The default value, if any, is implementation dependent. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) " +.PD 0 +.IP """mac"" (\fBOSSL_KDF_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_KDF_PARAM_MAC) " +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) " +.IP """cipher"" (\fBOSSL_KDF_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_KDF_PARAM_CIPHER) " +.PD +For KDF implementations that use an underlying computation MAC, digest or +cipher, these parameters set what the algorithm should be. +.Sp +The value is always the name of the intended algorithm, +or the properties. +.Sp +Note that not all algorithms may support all possible underlying +implementations. +.IP """key"" (\fBOSSL_KDF_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_KDF_PARAM_KEY) " +Some KDF implementations require a key. +For those KDF implementations that support it, this octet string parameter +sets the key. +.IP """info"" (\fBOSSL_KDF_PARAM_INFO\fR) " 4 +.IX Item """info"" (OSSL_KDF_PARAM_INFO) " +Some KDF implementations, such as \fBEVP_KDF\-HKDF\fR\|(7), take an \*(Aqinfo\*(Aq parameter +for binding the derived key material +to application\- and context\-specific information. +This parameter sets the info, fixed info, other info or shared info argument. +You can specify this parameter multiple times, and each instance will +be concatenated to form the final value. +.IP """maclen"" (\fBOSSL_KDF_PARAM_MAC_SIZE\fR) " 4 +.IX Item """maclen"" (OSSL_KDF_PARAM_MAC_SIZE) " +Used by implementations that use a MAC with a variable output size (KMAC). +For those KDF implementations that support it, this parameter +sets the MAC output size. +.Sp +The default value, if any, is implementation dependent. +The length must never exceed what can be given with a \fBsize_t\fR. +.IP """maxmem_bytes"" (\fBOSSL_KDF_PARAM_SCRYPT_MAXMEM\fR) " 4 +.IX Item """maxmem_bytes"" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) " +Memory\-hard password\-based KDF algorithms, such as scrypt, use an amount of +memory that depends on the load factors provided as input. +For those KDF implementations that support it, this \fBuint64_t\fR parameter sets +an upper limit on the amount of memory that may be consumed while performing +a key derivation. +If this memory usage limit is exceeded because the load factors are chosen +too high, the key derivation will fail. +.Sp +The default value is implementation dependent. +The memory size must never exceed what can be given with a \fBsize_t\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_KDF_fetch()\fR returns a pointer to a newly fetched \fBEVP_KDF\fR, or +NULL if allocation failed. +.PP +\&\fBEVP_KDF_get0_provider()\fR returns a pointer to the provider for the KDF, or +NULL on error. +.PP +\&\fBEVP_KDF_up_ref()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_KDF_CTX_new()\fR returns either the newly allocated +\&\fBEVP_KDF_CTX\fR structure or NULL if an error occurred. +.PP +\&\fBEVP_KDF_CTX_free()\fR and \fBEVP_KDF_CTX_reset()\fR do not return a value. +.PP +\&\fBEVP_KDF_CTX_get_kdf_size()\fR returns the output size. \fBSIZE_MAX\fR is returned to indicate +that the algorithm produces a variable amount of output; 0 to indicate failure. +.PP +\&\fBEVP_KDF_get0_name()\fR returns the name of the KDF, or NULL on error. +.PP +\&\fBEVP_KDF_names_do_all()\fR returns 1 if the callback was called for all names. A +return value of 0 means that the callback was not called for any names. +.PP +The remaining functions return 1 for success and 0 for failure. +.SH NOTES +.IX Header "NOTES" +The KDF life\-cycle is described in \fBlife_cycle\-kdf\fR\|(7). In the future, +the transitions described there will be enforced. When this is done, it will +not be considered a breaking change to the API. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"Key Derivation Function (KDF)" in \fBOSSL_PROVIDER\-default\fR\|(7), +\&\fBlife_cycle\-kdf\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_KEM_free.3 b/static/netbsd/man3/EVP_KEM_free.3 new file mode 100644 index 00000000..7937674e --- /dev/null +++ b/static/netbsd/man3/EVP_KEM_free.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: EVP_KEM_free.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEM_free 3" +.TH EVP_KEM_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEM_fetch, EVP_KEM_free, EVP_KEM_up_ref, +EVP_KEM_get0_name, EVP_KEM_is_a, EVP_KEM_get0_provider, +EVP_KEM_do_all_provided, EVP_KEM_names_do_all, EVP_KEM_get0_description, +EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params +\&\- Functions to manage EVP_KEM algorithm objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_KEM *EVP_KEM_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& void EVP_KEM_free(EVP_KEM *kem); +\& int EVP_KEM_up_ref(EVP_KEM *kem); +\& const char *EVP_KEM_get0_name(const EVP_KEM *kem); +\& int EVP_KEM_is_a(const EVP_KEM *kem, const char *name); +\& OSSL_PROVIDER *EVP_KEM_get0_provider(const EVP_KEM *kem); +\& void EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_KEM *kem, void *arg), void *arg); +\& int EVP_KEM_names_do_all(const EVP_KEM *kem, +\& void (*fn)(const char *name, void *data), void *data); +\& const char *EVP_KEM_get0_description(const EVP_KEM *kem); +\& const OSSL_PARAM *EVP_KEM_gettable_ctx_params(const EVP_KEM *kem); +\& const OSSL_PARAM *EVP_KEM_settable_ctx_params(const EVP_KEM *kem); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_KEM_fetch()\fR fetches the implementation for the given \fBalgorithm\fR from any +provider offering it, within the criteria given by the \fBproperties\fR and in the +scope of the given library context \fBctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)). The algorithm +will be one offering functions for performing asymmetric kem related tasks such +as key encapsulation and decapsulation. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +The returned value must eventually be freed with \fBEVP_KEM_free()\fR. +.PP +\&\fBEVP_KEM_free()\fR decrements the reference count for the \fBEVP_KEM\fR structure. +Typically this structure will have been obtained from an earlier call to +\&\fBEVP_KEM_fetch()\fR. If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. +.PP +\&\fBEVP_KEM_up_ref()\fR increments the reference count for an \fBEVP_KEM\fR structure. +.PP +\&\fBEVP_KEM_is_a()\fR returns 1 if \fIkem\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR, otherwise 0. +.PP +\&\fBEVP_KEM_get0_provider()\fR returns the provider that \fIkem\fR was fetched from. +.PP +\&\fBEVP_KEM_do_all_provided()\fR traverses all EVP_KEMs implemented by all activated +providers in the given library context \fIlibctx\fR, and for each of the +implementations, calls the given function \fIfn\fR with the implementation method +and the given \fIarg\fR as argument. +.PP +\&\fBEVP_KEM_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIkem\fR. Note that the \fIkem\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIkem\fR object and should not be freed by the caller. +.PP +\&\fBEVP_KEM_names_do_all()\fR traverses all names for \fIkem\fR, and calls \fIfn\fR with +each name and \fIdata\fR. +.PP +\&\fBEVP_KEM_get0_description()\fR returns a description of the \fIkem\fR, meant for +display and human consumption. The description is at the discretion of +the \fIkem\fR implementation. +.PP +\&\fBEVP_KEM_gettable_ctx_params()\fR and \fBEVP_KEM_settable_ctx_params()\fR return +a constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +parameters that can be retrieved or set by a key encapsulation algorithm using +\&\fBEVP_PKEY_CTX_get_params\fR\|(3) and \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_KEM_fetch()\fR returns a pointer to an \fBEVP_KEM\fR for success or \fBNULL\fR for +failure. +.PP +\&\fBEVP_KEM_up_ref()\fR returns 1 for success or 0 otherwise. +.PP +\&\fBEVP_KEM_names_do_all()\fR returns 1 if the callback was called for all names. A +return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_KEM_gettable_ctx_params()\fR and \fBEVP_KEM_settable_ctx_params()\fR return +a constant \fBOSSL_PARAM\fR\|(3) array or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), \fBOSSL_PROVIDER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_KEYEXCH_free.3 b/static/netbsd/man3/EVP_KEYEXCH_free.3 new file mode 100644 index 00000000..37ea6fe1 --- /dev/null +++ b/static/netbsd/man3/EVP_KEYEXCH_free.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: EVP_KEYEXCH_free.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEYEXCH_free 3" +.TH EVP_KEYEXCH_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, +EVP_KEYEXCH_get0_provider, EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided, +EVP_KEYEXCH_names_do_all, EVP_KEYEXCH_get0_name, EVP_KEYEXCH_get0_description, +EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params +\&\- Functions to manage EVP_KEYEXCH algorithm objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_KEYEXCH *EVP_KEYEXCH_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange); +\& int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange); +\& OSSL_PROVIDER *EVP_KEYEXCH_get0_provider(const EVP_KEYEXCH *exchange); +\& int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *exchange, const char *name); +\& const char *EVP_KEYEXCH_get0_name(const EVP_KEYEXCH *exchange); +\& void EVP_KEYEXCH_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_KEYEXCH *exchange, void *arg), +\& void *arg); +\& int EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_KEYEXCH_get0_description(const EVP_KEYEXCH *keyexch); +\& const OSSL_PARAM *EVP_KEYEXCH_gettable_ctx_params(const EVP_KEYEXCH *keyexch); +\& const OSSL_PARAM *EVP_KEYEXCH_settable_ctx_params(const EVP_KEYEXCH *keyexch); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_KEYEXCH_fetch()\fR fetches the key exchange implementation for the given +\&\fIalgorithm\fR from any provider offering it, within the criteria given +by the \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +The returned value must eventually be freed with \fBEVP_KEYEXCH_free()\fR. +.PP +\&\fBEVP_KEYEXCH_free()\fR decrements the reference count for the \fBEVP_KEYEXCH\fR +structure. Typically this structure will have been obtained from an earlier call +to \fBEVP_KEYEXCH_fetch()\fR. If the reference count drops to 0 then the +structure is freed. If the argument is NULL, nothing is done. +.PP +\&\fBEVP_KEYEXCH_up_ref()\fR increments the reference count for an \fBEVP_KEYEXCH\fR +structure. +.PP +\&\fBEVP_KEYEXCH_get0_provider()\fR returns the provider that \fIexchange\fR was +fetched from. +.PP +\&\fBEVP_KEYEXCH_is_a()\fR checks if \fIexchange\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR. +.PP +\&\fBEVP_KEYEXCH_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIexchange\fR. Note that the \fIexchange\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIexchange\fR object and should not be freed by the caller. +.PP +\&\fBEVP_KEYEXCH_names_do_all()\fR traverses all names for the \fIexchange\fR, and +calls \fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_KEYEXCH_get0_description()\fR returns a description of the \fIkeyexch\fR, meant +for display and human consumption. The description is at the discretion of +the \fIkeyexch\fR implementation. +.PP +\&\fBEVP_KEYEXCH_do_all_provided()\fR traverses all key exchange implementations by +all activated providers in the library context \fIlibctx\fR, and for each +of the implementations, calls \fIfn\fR with the implementation method and +\&\fIdata\fR as arguments. +.PP +\&\fBEVP_KEYEXCH_gettable_ctx_params()\fR and \fBEVP_KEYEXCH_settable_ctx_params()\fR return +a constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +parameters that can be retrieved or set by a key exchange algorithm using +\&\fBEVP_PKEY_CTX_get_params\fR\|(3) and \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_KEYEXCH_fetch()\fR returns a pointer to a \fBEVP_KEYEXCH\fR for success +or NULL for failure. +.PP +\&\fBEVP_KEYEXCH_up_ref()\fR returns 1 for success or 0 otherwise. +.PP +\&\fBEVP_KEYEXCH_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_KEYEXCH_is_a()\fR returns 1 of \fIexchange\fR was identifiable, +otherwise 0. +.PP +\&\fBEVP_KEYEXCH_gettable_ctx_params()\fR and \fBEVP_KEYEXCH_settable_ctx_params()\fR return +a constant \fBOSSL_PARAM\fR\|(3) array or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), \fBOSSL_PROVIDER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_KEYMGMT.3 b/static/netbsd/man3/EVP_KEYMGMT.3 new file mode 100644 index 00000000..b6be5129 --- /dev/null +++ b/static/netbsd/man3/EVP_KEYMGMT.3 @@ -0,0 +1,212 @@ +.\" $NetBSD: EVP_KEYMGMT.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_KEYMGMT 3" +.TH EVP_KEYMGMT 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KEYMGMT, +EVP_KEYMGMT_fetch, +EVP_KEYMGMT_up_ref, +EVP_KEYMGMT_free, +EVP_KEYMGMT_get0_provider, +EVP_KEYMGMT_is_a, +EVP_KEYMGMT_get0_description, +EVP_KEYMGMT_get0_name, +EVP_KEYMGMT_do_all_provided, +EVP_KEYMGMT_names_do_all, +EVP_KEYMGMT_gettable_params, +EVP_KEYMGMT_settable_params, +EVP_KEYMGMT_gen_gettable_params, +EVP_KEYMGMT_gen_settable_params +\&\- EVP key management routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_keymgmt_st EVP_KEYMGMT; +\& +\& EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt); +\& void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt); +\& const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt); +\& int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name); +\& const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt); +\& const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt); +\& +\& void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_KEYMGMT *keymgmt, void *arg), +\& void *arg); +\& int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt); +\& const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt); +\& const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt); +\& const OSSL_PARAM *EVP_KEYMGMT_gen_gettable_params(const EVP_KEYMGMT *keymgmt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_KEYMGMT\fR is a method object that represents key management +implementations for different cryptographic algorithms. +This method object provides functionality to have providers import key +material from the outside, as well as export key material to the +outside. +Most of the functionality can only be used internally and has no +public interface, this object is simply passed into other functions +when needed. +.PP +\&\fBEVP_KEYMGMT_fetch()\fR looks for an algorithm within the provider that +has been loaded into the \fBOSSL_LIB_CTX\fR given by \fIctx\fR, having the +name given by \fIalgorithm\fR and the properties given by \fIproperties\fR. +.PP +\&\fBEVP_KEYMGMT_up_ref()\fR increments the reference count for the given +\&\fBEVP_KEYMGMT\fR \fIkeymgmt\fR. +.PP +\&\fBEVP_KEYMGMT_free()\fR decrements the reference count for the given +\&\fBEVP_KEYMGMT\fR \fIkeymgmt\fR, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. +.PP +\&\fBEVP_KEYMGMT_get0_provider()\fR returns the provider that has this particular +implementation. +.PP +\&\fBEVP_KEYMGMT_is_a()\fR checks if \fIkeymgmt\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR. +.PP +\&\fBEVP_KEYMGMT_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIkeymgmt\fR. Note that the \fIkeymgmt\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is +retained by the \fIkeymgmt\fR object and should not be freed by the caller. +.PP +\&\fBEVP_KEYMGMT_names_do_all()\fR traverses all names for the \fIkeymgmt\fR, and +calls \fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_KEYMGMT_get0_description()\fR returns a description of the \fIkeymgmt\fR, meant +for display and human consumption. The description is at the discretion +of the \fIkeymgmt\fR implementation. +.PP +\&\fBEVP_KEYMGMT_do_all_provided()\fR traverses all key keymgmt implementations by +all activated providers in the library context \fIlibctx\fR, and for each +of the implementations, calls \fIfn\fR with the implementation method and +\&\fIdata\fR as arguments. +.PP +\&\fBEVP_KEYMGMT_gettable_params()\fR and \fBEVP_KEYMGMT_settable_params()\fR return a +constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +parameters that can be retrieved or set. +\&\fBEVP_KEYMGMT_gettable_params()\fR is used by \fBEVP_PKEY_gettable_params\fR\|(3). +.PP +\&\fBEVP_KEYMGMT_gen_gettable_params()\fR and \fBEVP_KEYMGMT_gen_settable_params()\fR return a +constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +generation parameters that can be retrieved or set via +\&\fBEVP_PKEY_CTX_get_params\fR\|(3) or \fBEVP_PKEY_CTX_set_params\fR\|(3) respectively. +.SH NOTES +.IX Header "NOTES" +\&\fBEVP_KEYMGMT_fetch()\fR may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_KEYMGMT_fetch()\fR returns a pointer to the key management +implementation represented by an EVP_KEYMGMT object, or NULL on +error. +.PP +\&\fBEVP_KEYMGMT_up_ref()\fR returns 1 on success, or 0 on error. +.PP +\&\fBEVP_KEYMGMT_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_KEYMGMT_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBEVP_KEYMGMT_get0_provider()\fR returns a pointer to a provider object, or NULL +on error. +.PP +\&\fBEVP_KEYMGMT_is_a()\fR returns 1 of \fIkeymgmt\fR was identifiable, +otherwise 0. +.PP +\&\fBEVP_KEYMGMT_get0_name()\fR returns the algorithm name, or NULL on error. +.PP +\&\fBEVP_KEYMGMT_get0_description()\fR returns a pointer to a description, or NULL if +there isn\*(Aqt one. +.PP +\&\fBEVP_KEYMGMT_gettable_params()\fR, \fBEVP_KEYMGMT_settable_params()\fR, +\&\fBEVP_KEYMGMT_gen_gettable_params()\fR and \fBEVP_KEYMGMT_gen_settable_params()\fR +return a constant \fBOSSL_PARAM\fR\|(3) array or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_fetch\fR\|(3), \fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBEVP_KEYMGMT_gen_gettable_params()\fR was added in OpenSSL 3.4.0 +All other functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_MAC.3 b/static/netbsd/man3/EVP_MAC.3 new file mode 100644 index 00000000..2f9320ac --- /dev/null +++ b/static/netbsd/man3/EVP_MAC.3 @@ -0,0 +1,551 @@ +.\" $NetBSD: EVP_MAC.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MAC 3" +.TH EVP_MAC 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free, EVP_MAC_is_a, +EVP_MAC_get0_name, EVP_MAC_names_do_all, EVP_MAC_get0_description, +EVP_MAC_get0_provider, EVP_MAC_get_params, EVP_MAC_gettable_params, +EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup, +EVP_MAC_CTX_get0_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params, +EVP_MAC_CTX_get_mac_size, EVP_MAC_CTX_get_block_size, EVP_Q_mac, +EVP_MAC_init, EVP_MAC_init_SKEY, EVP_MAC_update, EVP_MAC_final, EVP_MAC_finalXOF, +EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params, +EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params, +EVP_MAC_do_all_provided \- EVP MAC routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_mac_st EVP_MAC; +\& typedef struct evp_mac_ctx_st EVP_MAC_CTX; +\& +\& EVP_MAC *EVP_MAC_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, +\& const char *properties); +\& int EVP_MAC_up_ref(EVP_MAC *mac); +\& void EVP_MAC_free(EVP_MAC *mac); +\& int EVP_MAC_is_a(const EVP_MAC *mac, const char *name); +\& const char *EVP_MAC_get0_name(const EVP_MAC *mac); +\& int EVP_MAC_names_do_all(const EVP_MAC *mac, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_MAC_get0_description(const EVP_MAC *mac); +\& const OSSL_PROVIDER *EVP_MAC_get0_provider(const EVP_MAC *mac); +\& int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]); +\& +\& EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac); +\& void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx); +\& EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src); +\& EVP_MAC *EVP_MAC_CTX_get0_mac(EVP_MAC_CTX *ctx); +\& int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]); +\& int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]); +\& +\& size_t EVP_MAC_CTX_get_mac_size(EVP_MAC_CTX *ctx); +\& size_t EVP_MAC_CTX_get_block_size(EVP_MAC_CTX *ctx); +\& unsigned char *EVP_Q_mac(OSSL_LIB_CTX *libctx, const char *name, const char *propq, +\& const char *subalg, const OSSL_PARAM *params, +\& const void *key, size_t keylen, +\& const unsigned char *data, size_t datalen, +\& unsigned char *out, size_t outsize, size_t *outlen); +\& int EVP_MAC_init(EVP_MAC_CTX *ctx, const unsigned char *key, size_t keylen, +\& const OSSL_PARAM params[]); +\& int EVP_MAC_init_SKEY(EVP_MAC_CTX *ctx, EVP_SKEY *skey, const OSSL_PARAM params[]); +\& int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen); +\& int EVP_MAC_final(EVP_MAC_CTX *ctx, +\& unsigned char *out, size_t *outl, size_t outsize); +\& int EVP_MAC_finalXOF(EVP_MAC_CTX *ctx, unsigned char *out, size_t outsize); +\& +\& const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac); +\& const OSSL_PARAM *EVP_MAC_gettable_ctx_params(const EVP_MAC *mac); +\& const OSSL_PARAM *EVP_MAC_settable_ctx_params(const EVP_MAC *mac); +\& const OSSL_PARAM *EVP_MAC_CTX_gettable_params(EVP_MAC_CTX *ctx); +\& const OSSL_PARAM *EVP_MAC_CTX_settable_params(EVP_MAC_CTX *ctx); +\& +\& void EVP_MAC_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_MAC *mac, void *arg), +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These types and functions help the application to calculate MACs of +different types and with different underlying algorithms if there are +any. +.PP +MACs are a bit complex insofar that some of them use other algorithms +for actual computation. HMAC uses a digest, and CMAC uses a cipher. +Therefore, there are sometimes two contexts to keep track of, one for +the MAC algorithm itself and one for the underlying computation +algorithm if there is one. +.PP +To make things less ambiguous, this manual talks about a "context" or +"MAC context", which is to denote the MAC level context, and about a +"underlying context", or "computation context", which is to denote the +context for the underlying computation algorithm if there is one. +.SS Types +.IX Subsection "Types" +\&\fBEVP_MAC\fR is a type that holds the implementation of a MAC. +.PP +\&\fBEVP_MAC_CTX\fR is a context type that holds internal MAC information +as well as a reference to a computation context, for those MACs that +rely on an underlying computation algorithm. +.SS "Algorithm implementation fetching" +.IX Subsection "Algorithm implementation fetching" +\&\fBEVP_MAC_fetch()\fR fetches an implementation of a MAC \fIalgorithm\fR, given +a library context \fIlibctx\fR and a set of \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +See "Message Authentication Code (MAC)" in \fBOSSL_PROVIDER\-default\fR\|(7) for the list +of algorithms supported by the default provider. +.PP +The returned value must eventually be freed with +\&\fBEVP_MAC_free\fR\|(3). +.PP +\&\fBEVP_MAC_up_ref()\fR increments the reference count of an already fetched +MAC. +.PP +\&\fBEVP_MAC_free()\fR frees a fetched algorithm. +NULL is a valid parameter, for which this function is a no\-op. +.SS "Context manipulation functions" +.IX Subsection "Context manipulation functions" +\&\fBEVP_MAC_CTX_new()\fR creates a new context for the MAC type \fImac\fR. +The created context can then be used with most other functions +described here. +.PP +\&\fBEVP_MAC_CTX_free()\fR frees the contents of the context, including an +underlying context if there is one, as well as the context itself. +NULL is a valid parameter, for which this function is a no\-op. +.PP +\&\fBEVP_MAC_CTX_dup()\fR duplicates the \fIsrc\fR context and returns a newly allocated +context. +.PP +\&\fBEVP_MAC_CTX_get0_mac()\fR returns the \fBEVP_MAC\fR associated with the context +\&\fIctx\fR. +.SS "Computing functions" +.IX Subsection "Computing functions" +\&\fBEVP_Q_mac()\fR computes the message authentication code +of \fIdata\fR with length \fIdatalen\fR +using the MAC algorithm \fIname\fR and the key \fIkey\fR with length \fIkeylen\fR. +The MAC algorithm is fetched using any given \fIlibctx\fR and property query +string \fIpropq\fR. It takes parameters \fIsubalg\fR and further \fIparams\fR, +both of which may be NULL if not needed. +If \fIout\fR is not NULL, it places the result in the memory pointed at by \fIout\fR, +but only if \fIoutsize\fR is sufficient (otherwise no computation is made). +If \fIout\fR is NULL, it allocates and uses a buffer of suitable length, +which will be returned on success and must be freed by the caller. +In either case, also on error, +it assigns the number of bytes written to \fI*outlen\fR unless \fIoutlen\fR is NULL. +.PP +\&\fBEVP_MAC_init()\fR sets up the underlying context \fIctx\fR with information given +via the \fIkey\fR and \fIparams\fR arguments. The MAC \fIkey\fR has a length of +\&\fIkeylen\fR and the parameters in \fIparams\fR are processed before setting +the key. If \fIkey\fR is NULL, the key must be set via \fIparams\fR either +as part of this call or separately using \fBEVP_MAC_CTX_set_params()\fR. +Providing non\-NULL \fIparams\fR to this function is equivalent to calling +\&\fBEVP_MAC_CTX_set_params()\fR with those \fIparams\fR for the same \fIctx\fR beforehand. +Note: There are additional requirements for some MAC algorithms during +re\-initalization (i.e. calling \fBEVP_MAC_init()\fR on an EVP_MAC after \fBEVP_MAC_final()\fR +has been called on the same object). See the NOTES section below. +.PP +\&\fBEVP_MAC_init()\fR should be called before \fBEVP_MAC_update()\fR and \fBEVP_MAC_final()\fR. +.PP +\&\fBEVP_MAC_init_SKEY()\fR is similar to \fBEVP_MAC_init()\fR but it accepts an opaque +\&\fBEVP_SKEY\fR object as a key. +.PP +\&\fBEVP_MAC_update()\fR adds \fIdatalen\fR bytes from \fIdata\fR to the MAC input. +.PP +\&\fBEVP_MAC_final()\fR does the final computation and stores the result in +the memory pointed at by \fIout\fR of size \fIoutsize\fR, and sets the number +of bytes written in \fI*outl\fR at. +If \fIout\fR is NULL or \fIoutsize\fR is too small, then no computation +is made. +To figure out what the output length will be and allocate space for it +dynamically, simply call with \fIout\fR being NULL and \fIoutl\fR +pointing at a valid location, then allocate space and make a second +call with \fIout\fR pointing at the allocated space. +.PP +\&\fBEVP_MAC_finalXOF()\fR does the final computation for an XOF based MAC and stores +the result in the memory pointed at by \fIout\fR of size \fIoutsize\fR. +.PP +\&\fBEVP_MAC_get_params()\fR retrieves details about the implementation +\&\fImac\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_MAC_CTX_get_params()\fR retrieves chosen parameters, given the +context \fIctx\fR and its underlying context. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_MAC_CTX_set_params()\fR passes chosen parameters to the underlying +context, given a context \fIctx\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters are passed down. +If \fIparams\fR are NULL, the underlying context should do nothing and return 1. +Note that a parameter that is unknown in the underlying context is +simply ignored. +Also, what happens when a needed parameter isn\*(Aqt passed down is +defined by the implementation. +.PP +\&\fBEVP_MAC_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array that describes +the retrievable and settable parameters. \fBEVP_MAC_gettable_params()\fR +returns parameters that can be used with \fBEVP_MAC_get_params()\fR. +.PP +\&\fBEVP_MAC_gettable_ctx_params()\fR and \fBEVP_MAC_CTX_gettable_params()\fR +return constant \fBOSSL_PARAM\fR\|(3) arrays that describe the retrievable +parameters that can be used with \fBEVP_MAC_CTX_get_params()\fR. +\&\fBEVP_MAC_gettable_ctx_params()\fR returns the parameters that can be retrieved +from the algorithm, whereas \fBEVP_MAC_CTX_gettable_params()\fR returns +the parameters that can be retrieved in the context\*(Aqs current state. +.PP +\&\fBEVP_MAC_settable_ctx_params()\fR and \fBEVP_MAC_CTX_settable_params()\fR return +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the settable parameters that +can be used with \fBEVP_MAC_CTX_set_params()\fR. \fBEVP_MAC_settable_ctx_params()\fR +returns the parameters that can be retrieved from the algorithm, +whereas \fBEVP_MAC_CTX_settable_params()\fR returns the parameters that can +be retrieved in the context\*(Aqs current state. +.SS "Information functions" +.IX Subsection "Information functions" +\&\fBEVP_MAC_CTX_get_mac_size()\fR returns the MAC output size for the given context. +.PP +\&\fBEVP_MAC_CTX_get_block_size()\fR returns the MAC block size for the given context. +Not all MAC algorithms support this. +.PP +\&\fBEVP_MAC_is_a()\fR checks if the given \fImac\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR. +.PP +\&\fBEVP_MAC_get0_provider()\fR returns the provider that holds the implementation +of the given \fImac\fR. +.PP +\&\fBEVP_MAC_do_all_provided()\fR traverses all MAC implemented by all activated +providers in the given library context \fIlibctx\fR, and for each of the +implementations, calls the given function \fIfn\fR with the implementation method +and the given \fIarg\fR as argument. +.PP +\&\fBEVP_MAC_get0_name()\fR return the name of the given MAC. For fetched MACs +with multiple names, only one of them is returned; it\*(Aqs +recommended to use \fBEVP_MAC_names_do_all()\fR instead. +.PP +\&\fBEVP_MAC_names_do_all()\fR traverses all names for \fImac\fR, and calls +\&\fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_MAC_get0_description()\fR returns a description of the \fImac\fR, meant +for display and human consumption. The description is at the discretion +of the mac implementation. +.SH PARAMETERS +.IX Header "PARAMETERS" +Parameters are identified by name as strings, and have an expected +data type and maximum size. +OpenSSL has a set of macros for parameter names it expects to see in +its own MAC implementations. +Here, we show all three, the OpenSSL macro for the parameter name, the +name in string form, and a type description. +.PP +The standard parameter names are: +.IP """key"" (\fBOSSL_MAC_PARAM_KEY\fR) " 4 +.IX Item """key"" (OSSL_MAC_PARAM_KEY) " +Its value is the MAC key as an array of bytes. +.Sp +For MACs that use an underlying computation algorithm, the algorithm +must be set first, see parameter names "algorithm" below. +.IP """iv"" (\fBOSSL_MAC_PARAM_IV\fR) " 4 +.IX Item """iv"" (OSSL_MAC_PARAM_IV) " +Some MAC implementations (GMAC) require an IV, this parameter sets the IV. +.IP """custom"" (\fBOSSL_MAC_PARAM_CUSTOM\fR) " 4 +.IX Item """custom"" (OSSL_MAC_PARAM_CUSTOM) " +Some MAC implementations (KMAC, BLAKE2) accept a Customization String, +this parameter sets the Customization String. The default value is the +empty string. +.IP """salt"" (\fBOSSL_MAC_PARAM_SALT\fR) " 4 +.IX Item """salt"" (OSSL_MAC_PARAM_SALT) " +This option is used by BLAKE2 MAC. +.IP """xof"" (\fBOSSL_MAC_PARAM_XOF\fR) " 4 +.IX Item """xof"" (OSSL_MAC_PARAM_XOF) " +It\*(Aqs a simple flag, the value 0 or 1 are expected. +.Sp +This option is used by KMAC. +.IP """digest\-noinit"" (\fBOSSL_MAC_PARAM_DIGEST_NOINIT\fR) " 4 +.IX Item """digest-noinit"" (OSSL_MAC_PARAM_DIGEST_NOINIT) " +A simple flag to set the MAC digest to not initialise the +implementation specific data. The value 0 or 1 is expected. +.Sp +This option is deprecated and will be removed in a future release. +The option may be set, but is ignored. +.IP """digest\-oneshot"" (\fBOSSL_MAC_PARAM_DIGEST_ONESHOT\fR) " 4 +.IX Item """digest-oneshot"" (OSSL_MAC_PARAM_DIGEST_ONESHOT) " +A simple flag to set the MAC digest to be a oneshot operation. +The value 0 or 1 is expected. +.Sp +This option is deprecated and will be removed in a future release. +The option may be set, but is ignored. +.IP """properties"" (\fBOSSL_MAC_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_MAC_PARAM_PROPERTIES) " +.PD 0 +.IP """digest"" (\fBOSSL_MAC_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_MAC_PARAM_DIGEST) " +.IP """cipher"" (\fBOSSL_MAC_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_MAC_PARAM_CIPHER) " +.PD +For MAC implementations that use an underlying computation cipher or +digest, these parameters set what the algorithm should be. +.Sp +The value is always the name of the intended algorithm, +or the properties. +.Sp +Note that not all algorithms may support all digests. +HMAC does not support variable output length digests such as SHAKE128 +or SHAKE256. +.IP """size"" (\fBOSSL_MAC_PARAM_SIZE\fR) " 4 +.IX Item """size"" (OSSL_MAC_PARAM_SIZE) " +For MAC implementations that support it, set the output size that +\&\fBEVP_MAC_final()\fR should produce. +The allowed sizes vary between MAC implementations, but must never exceed +what can be given with a \fBsize_t\fR. +.IP """tls\-data\-size"" (\fBOSSL_MAC_PARAM_TLS_DATA_SIZE\fR) " 4 +.IX Item """tls-data-size"" (OSSL_MAC_PARAM_TLS_DATA_SIZE) " +This parameter is only supported by HMAC. If set then special handling is +activated for calculating the MAC of a received mac\-then\-encrypt TLS record +where variable length record padding has been used (as in the case of CBC mode +ciphersuites). The value represents the total length of the record that is +having the MAC calculated including the received MAC and the record padding. +.Sp +When used EVP_MAC_update must be called precisely twice. The first time with +the 13 bytes of TLS "header" data, and the second time with the entire record +including the MAC itself and any padding. The entire record length must equal +the value passed in the "tls\-data\-size" parameter. The length passed in the +\&\fBdatalen\fR parameter to \fBEVP_MAC_update()\fR should be equal to the length of the +record after the MAC and any padding has been removed. +.PP +All these parameters should be used before the calls to any of +\&\fBEVP_MAC_init()\fR, \fBEVP_MAC_update()\fR and \fBEVP_MAC_final()\fR for a full +computation. +Anything else may give undefined results. +.SH NOTES +.IX Header "NOTES" +The MAC life\-cycle is described in \fBlife_cycle\-mac\fR\|(7). In the future, +the transitions described there will be enforced. When this is done, it will +not be considered a breaking change to the API. +.PP +The usage of the parameter names "custom", "iv" and "salt" correspond to +the names used in the standard where the algorithm was defined. +.PP +Some MAC algorithms store internal state that cannot be extracted during +re\-initalization. For example GMAC cannot extract an \fBIV\fR from the +underlying CIPHER context, and so calling \fBEVP_MAC_init()\fR on an EVP_MAC object +after \fBEVP_MAC_final()\fR has been called cannot reset its cipher state to what it +was when the \fBIV\fR was initially generated. For such instances, an +\&\fBOSSL_MAC_PARAM_IV\fR parameter must be passed with each call to \fBEVP_MAC_init()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_MAC_fetch()\fR returns a pointer to a newly fetched \fBEVP_MAC\fR, or +NULL if allocation failed. +.PP +\&\fBEVP_MAC_up_ref()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_MAC_names_do_all()\fR returns 1 if the callback was called for all names. A +return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_MAC_free()\fR returns nothing at all. +.PP +\&\fBEVP_MAC_is_a()\fR returns 1 if the given method can be identified with +the given name, otherwise 0. +.PP +\&\fBEVP_MAC_get0_name()\fR returns a name of the MAC, or NULL on error. +.PP +\&\fBEVP_MAC_get0_provider()\fR returns a pointer to the provider for the MAC, or +NULL on error. +.PP +\&\fBEVP_MAC_CTX_new()\fR and \fBEVP_MAC_CTX_dup()\fR return a pointer to a newly +created EVP_MAC_CTX, or NULL if allocation failed. +.PP +\&\fBEVP_MAC_CTX_free()\fR returns nothing at all. +.PP +\&\fBEVP_MAC_CTX_get_params()\fR and \fBEVP_MAC_CTX_set_params()\fR return 1 on +success, 0 on error. +.PP +\&\fBEVP_Q_mac()\fR returns a pointer to the computed MAC value, or NULL on error. +.PP +\&\fBEVP_MAC_init()\fR, \fBEVP_MAC_init_SKEY()\fR, \fBEVP_MAC_update()\fR, \fBEVP_MAC_final()\fR, and +\&\fBEVP_MAC_finalXOF()\fR return 1 on success, 0 on error. +.PP +\&\fBEVP_MAC_CTX_get_mac_size()\fR returns the expected output size, or 0 if it isn\*(Aqt +set. If it isn\*(Aqt set, a call to \fBEVP_MAC_init()\fR will set it. +.PP +\&\fBEVP_MAC_CTX_get_block_size()\fR returns the block size, or 0 if it isn\*(Aqt set. +If it isn\*(Aqt set, a call to \fBEVP_MAC_init()\fR will set it. +.PP +\&\fBEVP_MAC_do_all_provided()\fR returns nothing at all. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& #include +\& #include +\& #include +\& #include +\& #include +\& +\& #include +\& #include +\& #include +\& +\& int main() { +\& EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL); +\& const char *cipher = getenv("MY_MAC_CIPHER"); +\& const char *digest = getenv("MY_MAC_DIGEST"); +\& const char *key = getenv("MY_KEY"); +\& EVP_MAC_CTX *ctx = NULL; +\& +\& unsigned char buf[4096]; +\& size_t read_l; +\& size_t final_l; +\& +\& size_t i; +\& +\& OSSL_PARAM params[3]; +\& size_t params_n = 0; +\& +\& if (cipher != NULL) +\& params[params_n++] = +\& OSSL_PARAM_construct_utf8_string("cipher", (char*)cipher, 0); +\& if (digest != NULL) +\& params[params_n++] = +\& OSSL_PARAM_construct_utf8_string("digest", (char*)digest, 0); +\& params[params_n] = OSSL_PARAM_construct_end(); +\& +\& if (mac == NULL +\& || key == NULL +\& || (ctx = EVP_MAC_CTX_new(mac)) == NULL +\& || !EVP_MAC_init(ctx, (const unsigned char *)key, strlen(key), +\& params)) +\& goto err; +\& +\& while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) { +\& if (!EVP_MAC_update(ctx, buf, read_l)) +\& goto err; +\& } +\& +\& if (!EVP_MAC_final(ctx, buf, &final_l, sizeof(buf))) +\& goto err; +\& +\& printf("Result: "); +\& for (i = 0; i < final_l; i++) +\& printf("%02X", buf[i]); +\& printf("\en"); +\& +\& EVP_MAC_CTX_free(ctx); +\& EVP_MAC_free(mac); +\& exit(0); +\& +\& err: +\& EVP_MAC_CTX_free(ctx); +\& EVP_MAC_free(mac); +\& fprintf(stderr, "Something went wrong\en"); +\& ERR_print_errors_fp(stderr); +\& exit (1); +\& } +.Ve +.PP +A run of this program, called with correct environment variables, can +look like this: +.PP +.Vb 3 +\& $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes\-128\-cbc \e +\& LD_LIBRARY_PATH=. ./foo < foo.c +\& Result: C5C06683CD9DDEF904D754505C560A4E +.Ve +.PP +(in this example, that program was stored in \fIfoo.c\fR and compiled to +\&\fI./foo\fR) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBproperty\fR\|(7) +\&\fBOSSL_PARAM\fR\|(3), +\&\fBEVP_MAC\-BLAKE2\fR\|(7), +\&\fBEVP_MAC\-CMAC\fR\|(7), +\&\fBEVP_MAC\-GMAC\fR\|(7), +\&\fBEVP_MAC\-HMAC\fR\|(7), +\&\fBEVP_MAC\-KMAC\fR\|(7), +\&\fBEVP_MAC\-Siphash\fR\|(7), +\&\fBEVP_MAC\-Poly1305\fR\|(7), +\&\fBprovider\-mac\fR\|(7), +\&\fBlife_cycle\-mac\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.PP +The \fBEVP_MAC_init_SKEY()\fR function was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_MD_CTX_block_size.3 b/static/netbsd/man3/EVP_MD_CTX_block_size.3 new file mode 100644 index 00000000..e86c79df --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_block_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_block_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_cleanup.3 b/static/netbsd/man3/EVP_MD_CTX_cleanup.3 new file mode 100644 index 00000000..67f8c101 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_cleanup.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_cleanup.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_create.3 b/static/netbsd/man3/EVP_MD_CTX_create.3 new file mode 100644 index 00000000..9031d483 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_create.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_create.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_destroy.3 b/static/netbsd/man3/EVP_MD_CTX_destroy.3 new file mode 100644 index 00000000..995fa0c5 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_destroy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_destroy.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_init.3 b/static/netbsd/man3/EVP_MD_CTX_init.3 new file mode 100644 index 00000000..3994ff71 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_md.3 b/static/netbsd/man3/EVP_MD_CTX_md.3 new file mode 100644 index 00000000..4aaf6210 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_md.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_md.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_CTX_size.3 b/static/netbsd/man3/EVP_MD_CTX_size.3 new file mode 100644 index 00000000..fa4fda36 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_CTX_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_CTX_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_block_size.3 b/static/netbsd/man3/EVP_MD_block_size.3 new file mode 100644 index 00000000..620d352c --- /dev/null +++ b/static/netbsd/man3/EVP_MD_block_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_block_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_MD_meth_new.3 b/static/netbsd/man3/EVP_MD_meth_new.3 new file mode 100644 index 00000000..9b52ea7a --- /dev/null +++ b/static/netbsd/man3/EVP_MD_meth_new.3 @@ -0,0 +1,255 @@ +.\" $NetBSD: EVP_MD_meth_new.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_MD_meth_new 3" +.TH EVP_MD_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free, +EVP_MD_meth_set_input_blocksize, +EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize, +EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update, +EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup, +EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize, +EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize, +EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update, +EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup, +EVP_MD_meth_get_ctrl +\&\- Routines to build up legacy EVP_MD methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type); +\& void EVP_MD_meth_free(EVP_MD *md); +\& EVP_MD *EVP_MD_meth_dup(const EVP_MD *md); +\& +\& int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize); +\& int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize); +\& int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize); +\& int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags); +\& int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx)); +\& int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx, +\& const void *data, +\& size_t count)); +\& int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx, +\& unsigned char *md)); +\& int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to, +\& const EVP_MD_CTX *from)); +\& int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx)); +\& int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd, +\& int p1, void *p2)); +\& +\& int EVP_MD_meth_get_input_blocksize(const EVP_MD *md); +\& int EVP_MD_meth_get_result_size(const EVP_MD *md); +\& int EVP_MD_meth_get_app_datasize(const EVP_MD *md); +\& unsigned long EVP_MD_meth_get_flags(const EVP_MD *md); +\& int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx); +\& int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx, +\& const void *data, +\& size_t count); +\& int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx, +\& unsigned char *md); +\& int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to, +\& const EVP_MD_CTX *from); +\& int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx); +\& int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd, +\& int p1, void *p2); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +The \fBEVP_MD\fR type is a structure for digest method implementation. +It can also have associated public/private key signing and verifying +routines. +.PP +\&\fBEVP_MD_meth_new()\fR creates a new \fBEVP_MD\fR structure. +These \fBEVP_MD\fR structures are reference counted. +.PP +\&\fBEVP_MD_meth_dup()\fR creates a copy of \fBmd\fR. +.PP +\&\fBEVP_MD_meth_free()\fR decrements the reference count for the \fBEVP_MD\fR structure. +If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. +.PP +\&\fBEVP_MD_meth_set_input_blocksize()\fR sets the internal input block size +for the method \fBmd\fR to \fBblocksize\fR bytes. +.PP +\&\fBEVP_MD_meth_set_result_size()\fR sets the size of the result that the +digest method in \fBmd\fR is expected to produce to \fBresultsize\fR bytes. +.PP +The digest method may have its own private data, which OpenSSL will +allocate for it. \fBEVP_MD_meth_set_app_datasize()\fR should be used to +set the size for it to \fBdatasize\fR. +.PP +\&\fBEVP_MD_meth_set_flags()\fR sets the flags to describe optional +behaviours in the particular \fBmd\fR. Several flags can be or\*(Aqd +together. The available flags are: +.IP EVP_MD_FLAG_ONESHOT 4 +.IX Item "EVP_MD_FLAG_ONESHOT" +This digest method can only handle one block of input. +.IP EVP_MD_FLAG_XOF 4 +.IX Item "EVP_MD_FLAG_XOF" +This digest method is an extensible\-output function (XOF) and supports +the \fBEVP_MD_CTRL_XOF_LEN\fR control. +.IP EVP_MD_FLAG_DIGALGID_NULL 4 +.IX Item "EVP_MD_FLAG_DIGALGID_NULL" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to NULL by default. Use this for PKCS#1. \fINote: if +combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.\fR +.IP EVP_MD_FLAG_DIGALGID_ABSENT 4 +.IX Item "EVP_MD_FLAG_DIGALGID_ABSENT" +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. \fINote: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR +.IP EVP_MD_FLAG_DIGALGID_CUSTOM 4 +.IX Item "EVP_MD_FLAG_DIGALGID_CUSTOM" +Custom DigestAlgorithmIdentifier handling via ctrl, with +\&\fBEVP_MD_FLAG_DIGALGID_ABSENT\fR as default. \fINote: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR +Currently unused. +.IP EVP_MD_FLAG_FIPS 4 +.IX Item "EVP_MD_FLAG_FIPS" +This digest method is suitable for use in FIPS mode. +Currently unused. +.PP +\&\fBEVP_MD_meth_set_init()\fR sets the digest init function for \fBmd\fR. +The digest init function is called by \fBEVP_Digest()\fR, \fBEVP_DigestInit()\fR, +\&\fBEVP_DigestInit_ex()\fR, EVP_SignInit, \fBEVP_SignInit_ex()\fR, \fBEVP_VerifyInit()\fR +and \fBEVP_VerifyInit_ex()\fR. +.PP +\&\fBEVP_MD_meth_set_update()\fR sets the digest update function for \fBmd\fR. +The digest update function is called by \fBEVP_Digest()\fR, \fBEVP_DigestUpdate()\fR and +\&\fBEVP_SignUpdate()\fR. +.PP +\&\fBEVP_MD_meth_set_final()\fR sets the digest final function for \fBmd\fR. +The digest final function is called by \fBEVP_Digest()\fR, \fBEVP_DigestFinal()\fR, +\&\fBEVP_DigestFinal_ex()\fR, \fBEVP_SignFinal()\fR and \fBEVP_VerifyFinal()\fR. +.PP +\&\fBEVP_MD_meth_set_copy()\fR sets the function for \fBmd\fR to do extra +computations after the method\*(Aqs private data structure has been copied +from one \fBEVP_MD_CTX\fR to another. If all that\*(Aqs needed is to copy +the data, there is no need for this copy function. +Note that the copy function is passed two \fBEVP_MD_CTX *\fR, the private +data structure is then available with \fBEVP_MD_CTX_get0_md_data()\fR. +This copy function is called by \fBEVP_MD_CTX_copy()\fR and +\&\fBEVP_MD_CTX_copy_ex()\fR. +.PP +\&\fBEVP_MD_meth_set_cleanup()\fR sets the function for \fBmd\fR to do extra +cleanup before the method\*(Aqs private data structure is cleaned out and +freed. +Note that the cleanup function is passed a \fBEVP_MD_CTX *\fR, the +private data structure is then available with \fBEVP_MD_CTX_get0_md_data()\fR. +This cleanup function is called by \fBEVP_MD_CTX_reset()\fR and +\&\fBEVP_MD_CTX_free()\fR. +.PP +\&\fBEVP_MD_meth_set_ctrl()\fR sets the control function for \fBmd\fR. +See \fBEVP_MD_CTX_ctrl\fR\|(3) for the available controls. +.PP +\&\fBEVP_MD_meth_get_input_blocksize()\fR, \fBEVP_MD_meth_get_result_size()\fR, +\&\fBEVP_MD_meth_get_app_datasize()\fR, \fBEVP_MD_meth_get_flags()\fR, +\&\fBEVP_MD_meth_get_init()\fR, \fBEVP_MD_meth_get_update()\fR, +\&\fBEVP_MD_meth_get_final()\fR, \fBEVP_MD_meth_get_copy()\fR, +\&\fBEVP_MD_meth_get_cleanup()\fR and \fBEVP_MD_meth_get_ctrl()\fR are all used +to retrieve the method data given with the EVP_MD_meth_set_*() +functions above. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_MD_meth_new()\fR and \fBEVP_MD_meth_dup()\fR return a pointer to a newly +created \fBEVP_MD\fR, or NULL on failure. +All EVP_MD_meth_set_*() functions return 1. +\&\fBEVP_MD_get_input_blocksize()\fR, \fBEVP_MD_meth_get_result_size()\fR, +\&\fBEVP_MD_meth_get_app_datasize()\fR and \fBEVP_MD_meth_get_flags()\fR return the +indicated sizes or flags. +All other EVP_CIPHER_meth_get_*() functions return pointers to their +respective \fBmd\fR function. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3), \fBEVP_SignInit\fR\|(3), \fBEVP_VerifyInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The \fBEVP_MD\fR structure was openly available in OpenSSL before version +1.1. +The functions described here were added in OpenSSL 1.1. +The \fBEVP_MD\fR structure created with these functions became reference +counted in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_MD_size.3 b/static/netbsd/man3/EVP_MD_size.3 new file mode 100644 index 00000000..6a5723a4 --- /dev/null +++ b/static/netbsd/man3/EVP_MD_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_MD_size.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_OpenInit.3 b/static/netbsd/man3/EVP_OpenInit.3 new file mode 100644 index 00000000..da8a0150 --- /dev/null +++ b/static/netbsd/man3/EVP_OpenInit.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: EVP_OpenInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_OpenInit 3" +.TH EVP_OpenInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal \- EVP envelope decryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek, +\& int ekl, unsigned char *iv, EVP_PKEY *priv); +\& int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, unsigned char *in, int inl); +\& int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP envelope routines are a high\-level interface to envelope +decryption. They decrypt a public key encrypted symmetric key and +then decrypt data using it. +.PP +\&\fBEVP_OpenInit()\fR initializes a cipher context \fBctx\fR for decryption +with cipher \fBtype\fR. It decrypts the encrypted symmetric key of length +\&\fBekl\fR bytes passed in the \fBek\fR parameter using the private key \fBpriv\fR. +The IV is supplied in the \fBiv\fR parameter. +.PP +\&\fBEVP_OpenUpdate()\fR and \fBEVP_OpenFinal()\fR have exactly the same properties +as the \fBEVP_DecryptUpdate()\fR and \fBEVP_DecryptFinal()\fR routines, as +documented on the \fBEVP_EncryptInit\fR\|(3) manual +page. +.SH NOTES +.IX Header "NOTES" +It is possible to call \fBEVP_OpenInit()\fR twice in the same way as +\&\fBEVP_DecryptInit()\fR. The first call should have \fBpriv\fR set to NULL +and (after setting any cipher parameters) it should be called again +with \fBtype\fR set to NULL. +.PP +If the cipher passed in the \fBtype\fR parameter is a variable length +cipher then the key length will be set to the value of the recovered +key length. If the cipher is a fixed length cipher then the recovered +key length must match the fixed cipher length. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_OpenInit()\fR returns 0 on error or a non zero integer (actually the +recovered secret key size) if successful. +.PP +\&\fBEVP_OpenUpdate()\fR returns 1 for success or 0 for failure. +.PP +\&\fBEVP_OpenFinal()\fR returns 0 if the decrypt failed or 1 for success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), \fBRAND_bytes\fR\|(3), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_SealInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PBE_CipherInit.3 b/static/netbsd/man3/EVP_PBE_CipherInit.3 new file mode 100644 index 00000000..611ad782 --- /dev/null +++ b/static/netbsd/man3/EVP_PBE_CipherInit.3 @@ -0,0 +1,156 @@ +.\" $NetBSD: EVP_PBE_CipherInit.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PBE_CipherInit 3" +.TH EVP_PBE_CipherInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PBE_CipherInit, EVP_PBE_CipherInit_ex, +EVP_PBE_find, EVP_PBE_find_ex, +EVP_PBE_alg_add_type, EVP_PBE_alg_add \- Password based encryption routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PBE_CipherInit(ASN1_OBJECT *pbe_obj, const char *pass, int passlen, +\& ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de); +\& int EVP_PBE_CipherInit_ex(ASN1_OBJECT *pbe_obj, const char *pass, int passlen, +\& ASN1_TYPE *param, EVP_CIPHER_CTX *ctx, int en_de, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& int EVP_PBE_find(int type, int pbe_nid, int *pcnid, int *pmnid, +\& EVP_PBE_KEYGEN **pkeygen); +\& int EVP_PBE_find_ex(int type, int pbe_nid, int *pcnid, int *pmnid, +\& EVP_PBE_KEYGEN **pkeygen, EVP_PBE_KEYGEN_EX **keygen_ex); +\& +\& int EVP_PBE_alg_add_type(int pbe_type, int pbe_nid, int cipher_nid, +\& int md_nid, EVP_PBE_KEYGEN *keygen); +\& int EVP_PBE_alg_add(int nid, const EVP_CIPHER *cipher, const EVP_MD *md, +\& EVP_PBE_KEYGEN *keygen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS "PBE operations" +.IX Subsection "PBE operations" +\&\fBEVP_PBE_CipherInit()\fR and \fBEVP_PBE_CipherInit_ex()\fR initialise an \fBEVP_CIPHER_CTX\fR +\&\fIctx\fR for encryption (\fIen_de\fR=1) or decryption (\fIen_de\fR=0) using the password +\&\fIpass\fR of length \fIpasslen\fR. The PBE algorithm type and parameters are extracted +from an OID \fIpbe_obj\fR and parameters \fIparam\fR. +.PP +\&\fBEVP_PBE_CipherInit_ex()\fR also allows the application to specify a library context +\&\fIlibctx\fR and property query \fIpropq\fR to select appropriate algorithm +implementations. +.SS "PBE algorithm search" +.IX Subsection "PBE algorithm search" +\&\fBEVP_PBE_find()\fR and \fBEVP_PBE_find_ex()\fR search for a matching algorithm using two parameters: +.PP +1. An algorithm type \fItype\fR which can be: +.IP \(bu 4 +EVP_PBE_TYPE_OUTER \- A PBE algorithm +.IP \(bu 4 +EVP_PBE_TYPE_PRF \- A pseudo\-random function +.IP \(bu 4 +EVP_PBE_TYPE_KDF \- A key derivation function +.PP +2. A \fIpbe_nid\fR which can represent the algorithm identifier with parameters e.g. +\&\fBNID_pbeWithSHA1AndRC2_CBC\fR or an algorithm class e.g. \fBNID_pbes2\fR. +.PP +They return the algorithm\*(Aqs cipher ID \fIpcnid\fR, digest ID \fIpmnid\fR and a key +generation function for the algorithm \fIpkeygen\fR. \fBEVP_PBE_CipherInit_ex()\fR also +returns an extended key generation function \fIkeygen_ex\fR which takes a library +context and property query. +.PP +If a NULL is supplied for any of \fIpcnid\fR, \fIpmnid\fR, \fIpkeygen\fR or \fIpkeygen_ex\fR +then this parameter is not returned. +.SS "PBE algorithm add" +.IX Subsection "PBE algorithm add" +\&\fBEVP_PBE_alg_add_type()\fR and \fBEVP_PBE_alg_add()\fR add an algorithm to the list +of known algorithms. Their parameters have the same meaning as for +\&\fBEVP_PBE_find()\fR and \fBEVP_PBE_find_ex()\fR functions. +.SH NOTES +.IX Header "NOTES" +The arguments \fIpbe_obj\fR and \fIparam\fR to \fBEVP_PBE_CipherInit()\fR and \fBEVP_PBE_CipherInit_ex()\fR +together form an \fBX509_ALGOR\fR and can often be extracted directly from this structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Return value is 1 for success and 0 if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS5_PBE_keyivgen\fR\|(3), +\&\fBPKCS12_PBE_keyivgen_ex\fR\|(3), +\&\fBPKCS5_v2_PBE_keyivgen_ex\fR\|(3), +\&\fBPKCS12_pbe_crypt_ex\fR\|(3), +\&\fBPKCS12_create_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PBE_CipherInit_ex()\fR and \fBEVP_PBE_find_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY2PKCS8.3 b/static/netbsd/man3/EVP_PKEY2PKCS8.3 new file mode 100644 index 00000000..64042977 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY2PKCS8.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: EVP_PKEY2PKCS8.3,v 1.5 2026/04/08 17:06:43 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY2PKCS8 3" +.TH EVP_PKEY2PKCS8 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY2PKCS8, EVP_PKCS82PKEY_ex, EVP_PKCS82PKEY +\&\- Convert a private key to/from PKCS8 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey); +\& EVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8); +\& EVP_PKEY *EVP_PKCS82PKEY_ex(const PKCS8_PRIV_KEY_INFO *p8, OSSL_LIB_CTX *libctx, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY2PKCS8()\fR converts a private key \fIpkey\fR into a returned PKCS8 object. +.PP +\&\fBEVP_PKCS82PKEY_ex()\fR converts a PKCS8 object \fIp8\fR into a returned private key. +It uses \fIlibctx\fR and \fIpropq\fR when fetching algorithms. +.PP +\&\fBEVP_PKCS82PKEY()\fR is similar to \fBEVP_PKCS82PKEY_ex()\fR but uses default values of +NULL for the \fIlibctx\fR and \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY2PKCS8()\fR returns a PKCS8 object on success. +\&\fBEVP_PKCS82PKEY()\fR and \fBEVP_PKCS82PKEY_ex()\fR return a private key on success. +.PP +All functions return NULL if the operation fails. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS8_pkey_add1_attr\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_ASN1_METHOD.3 b/static/netbsd/man3/EVP_PKEY_ASN1_METHOD.3 new file mode 100644 index 00000000..d03d7b06 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_ASN1_METHOD.3 @@ -0,0 +1,519 @@ +.\" $NetBSD: EVP_PKEY_ASN1_METHOD.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_ASN1_METHOD 3" +.TH EVP_PKEY_ASN1_METHOD 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_ASN1_METHOD, +EVP_PKEY_asn1_new, +EVP_PKEY_asn1_copy, +EVP_PKEY_asn1_free, +EVP_PKEY_asn1_add0, +EVP_PKEY_asn1_add_alias, +EVP_PKEY_asn1_set_public, +EVP_PKEY_asn1_set_private, +EVP_PKEY_asn1_set_param, +EVP_PKEY_asn1_set_free, +EVP_PKEY_asn1_set_ctrl, +EVP_PKEY_asn1_set_item, +EVP_PKEY_asn1_set_siginf, +EVP_PKEY_asn1_set_check, +EVP_PKEY_asn1_set_public_check, +EVP_PKEY_asn1_set_param_check, +EVP_PKEY_asn1_set_security_bits, +EVP_PKEY_asn1_set_set_priv_key, +EVP_PKEY_asn1_set_set_pub_key, +EVP_PKEY_asn1_set_get_priv_key, +EVP_PKEY_asn1_set_get_pub_key, +EVP_PKEY_get0_asn1 +\&\- manipulating and registering EVP_PKEY_ASN1_METHOD structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD; +\& +\& EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags, +\& const char *pem_str, +\& const char *info); +\& void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst, +\& const EVP_PKEY_ASN1_METHOD *src); +\& void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth); +\& int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth); +\& int EVP_PKEY_asn1_add_alias(int to, int from); +\& +\& void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pub_decode) (EVP_PKEY *pk, +\& const X509_PUBKEY *pub), +\& int (*pub_encode) (X509_PUBKEY *pub, +\& const EVP_PKEY *pk), +\& int (*pub_cmp) (const EVP_PKEY *a, +\& const EVP_PKEY *b), +\& int (*pub_print) (BIO *out, +\& const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx), +\& int (*pkey_size) (const EVP_PKEY *pk), +\& int (*pkey_bits) (const EVP_PKEY *pk)); +\& void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*priv_decode) (EVP_PKEY *pk, +\& const PKCS8_PRIV_KEY_INFO +\& *p8inf), +\& int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, +\& const EVP_PKEY *pk), +\& int (*priv_print) (BIO *out, +\& const EVP_PKEY *pkey, +\& int indent, +\& ASN1_PCTX *pctx)); +\& void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*param_decode) (EVP_PKEY *pkey, +\& const unsigned char **pder, +\& int derlen), +\& int (*param_encode) (const EVP_PKEY *pkey, +\& unsigned char **pder), +\& int (*param_missing) (const EVP_PKEY *pk), +\& int (*param_copy) (EVP_PKEY *to, +\& const EVP_PKEY *from), +\& int (*param_cmp) (const EVP_PKEY *a, +\& const EVP_PKEY *b), +\& int (*param_print) (BIO *out, +\& const EVP_PKEY *pkey, +\& int indent, +\& ASN1_PCTX *pctx)); +\& +\& void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth, +\& void (*pkey_free) (EVP_PKEY *pkey)); +\& void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pkey_ctrl) (EVP_PKEY *pkey, int op, +\& long arg1, void *arg2)); +\& void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*item_verify) (EVP_MD_CTX *ctx, +\& const ASN1_ITEM *it, +\& void *asn, +\& X509_ALGOR *a, +\& ASN1_BIT_STRING *sig, +\& EVP_PKEY *pkey), +\& int (*item_sign) (EVP_MD_CTX *ctx, +\& const ASN1_ITEM *it, +\& void *asn, +\& X509_ALGOR *alg1, +\& X509_ALGOR *alg2, +\& ASN1_BIT_STRING *sig)); +\& +\& void EVP_PKEY_asn1_set_siginf(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*siginf_set) (X509_SIG_INFO *siginf, +\& const X509_ALGOR *alg, +\& const ASN1_STRING *sig)); +\& +\& void EVP_PKEY_asn1_set_check(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pkey_check) (const EVP_PKEY *pk)); +\& +\& void EVP_PKEY_asn1_set_public_check(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pkey_pub_check) (const EVP_PKEY *pk)); +\& +\& void EVP_PKEY_asn1_set_param_check(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pkey_param_check) (const EVP_PKEY *pk)); +\& +\& void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*pkey_security_bits) (const EVP_PKEY +\& *pk)); +\& +\& void EVP_PKEY_asn1_set_set_priv_key(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*set_priv_key) (EVP_PKEY *pk, +\& const unsigned char +\& *priv, +\& size_t len)); +\& +\& void EVP_PKEY_asn1_set_set_pub_key(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*set_pub_key) (EVP_PKEY *pk, +\& const unsigned char *pub, +\& size_t len)); +\& +\& void EVP_PKEY_asn1_set_get_priv_key(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*get_priv_key) (const EVP_PKEY *pk, +\& unsigned char *priv, +\& size_t *len)); +\& +\& void EVP_PKEY_asn1_set_get_pub_key(EVP_PKEY_ASN1_METHOD *ameth, +\& int (*get_pub_key) (const EVP_PKEY *pk, +\& unsigned char *pub, +\& size_t *len)); +\& +\& const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_ASN1_METHOD\fR is a structure which holds a set of ASN.1 +conversion, printing and information methods for a specific public key +algorithm. +.PP +There are two places where the \fBEVP_PKEY_ASN1_METHOD\fR objects are +stored: one is a built\-in array representing the standard methods for +different algorithms, and the other one is a stack of user\-defined +application\-specific methods, which can be manipulated by using +\&\fBEVP_PKEY_asn1_add0\fR\|(3). +.SS Methods +.IX Subsection "Methods" +The methods are the underlying implementations of a particular public +key algorithm present by the \fBEVP_PKEY\fR object. +.PP +.Vb 5 +\& int (*pub_decode) (EVP_PKEY *pk, const X509_PUBKEY *pub); +\& int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk); +\& int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); +\& int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent, +\& ASN1_PCTX *pctx); +.Ve +.PP +The \fBpub_decode()\fR and \fBpub_encode()\fR methods are called to decode / +encode \fBX509_PUBKEY\fR ASN.1 parameters to / from \fBpk\fR. +They MUST return 0 on error, 1 on success. +They\*(Aqre called by \fBX509_PUBKEY_get0\fR\|(3) and \fBX509_PUBKEY_set\fR\|(3). +.PP +The \fBpub_cmp()\fR method is called when two public keys are to be +compared. +It MUST return 1 when the keys are equal, 0 otherwise. +It\*(Aqs called by \fBEVP_PKEY_eq\fR\|(3). +.PP +The \fBpub_print()\fR method is called to print a public key in humanly +readable text to \fBout\fR, indented \fBindent\fR spaces. +It MUST return 0 on error, 1 on success. +It\*(Aqs called by \fBEVP_PKEY_print_public\fR\|(3). +.PP +.Vb 4 +\& int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf); +\& int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk); +\& int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent, +\& ASN1_PCTX *pctx); +.Ve +.PP +The \fBpriv_decode()\fR and \fBpriv_encode()\fR methods are called to decode / +encode \fBPKCS8_PRIV_KEY_INFO\fR form private key to / from \fBpk\fR. +They MUST return 0 on error, 1 on success. +They\*(Aqre called by \fBEVP_PKCS82PKEY\fR\|(3) and \fBEVP_PKEY2PKCS8\fR\|(3). +.PP +The \fBpriv_print()\fR method is called to print a private key in humanly +readable text to \fBout\fR, indented \fBindent\fR spaces. +It MUST return 0 on error, 1 on success. +It\*(Aqs called by \fBEVP_PKEY_print_private\fR\|(3). +.PP +.Vb 3 +\& int (*pkey_size) (const EVP_PKEY *pk); +\& int (*pkey_bits) (const EVP_PKEY *pk); +\& int (*pkey_security_bits) (const EVP_PKEY *pk); +.Ve +.PP +The \fBpkey_size()\fR method returns the key size in bytes. +It\*(Aqs called by \fBEVP_PKEY_get_size\fR\|(3). +.PP +The \fBpkey_bits()\fR method returns the key size in bits. +It\*(Aqs called by \fBEVP_PKEY_get_bits\fR\|(3). +.PP +.Vb 8 +\& int (*param_decode) (EVP_PKEY *pkey, +\& const unsigned char **pder, int derlen); +\& int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder); +\& int (*param_missing) (const EVP_PKEY *pk); +\& int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from); +\& int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); +\& int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent, +\& ASN1_PCTX *pctx); +.Ve +.PP +The \fBparam_decode()\fR and \fBparam_encode()\fR methods are called to decode / +encode DER formatted parameters to / from \fBpk\fR. +They MUST return 0 on error, 1 on success. +They\*(Aqre called by \fBPEM_read_bio_Parameters\fR\|(3) and the \fBfile:\fR +\&\fBOSSL_STORE_LOADER\fR\|(3). +.PP +The \fBparam_missing()\fR method returns 0 if a key parameter is missing, +otherwise 1. +It\*(Aqs called by \fBEVP_PKEY_missing_parameters\fR\|(3). +.PP +The \fBparam_copy()\fR method copies key parameters from \fBfrom\fR to \fBto\fR. +It MUST return 0 on error, 1 on success. +It\*(Aqs called by \fBEVP_PKEY_copy_parameters\fR\|(3). +.PP +The \fBparam_cmp()\fR method compares the parameters of keys \fBa\fR and \fBb\fR. +It MUST return 1 when the keys are equal, 0 when not equal, or a +negative number on error. +It\*(Aqs called by \fBEVP_PKEY_parameters_eq\fR\|(3). +.PP +The \fBparam_print()\fR method prints the private key parameters in humanly +readable text to \fBout\fR, indented \fBindent\fR spaces. +It MUST return 0 on error, 1 on success. +It\*(Aqs called by \fBEVP_PKEY_print_params\fR\|(3). +.PP +.Vb 3 +\& int (*sig_print) (BIO *out, +\& const X509_ALGOR *sigalg, const ASN1_STRING *sig, +\& int indent, ASN1_PCTX *pctx); +.Ve +.PP +The \fBsig_print()\fR method prints a signature in humanly readable text to +\&\fBout\fR, indented \fBindent\fR spaces. +\&\fBsigalg\fR contains the exact signature algorithm. +If the signature in \fBsig\fR doesn\*(Aqt correspond to what this method +expects, \fBX509_signature_dump()\fR must be used as a last resort. +It MUST return 0 on error, 1 on success. +It\*(Aqs called by \fBX509_signature_print\fR\|(3). +.PP +.Vb 1 +\& void (*pkey_free) (EVP_PKEY *pkey); +.Ve +.PP +The \fBpkey_free()\fR method helps freeing the internals of \fBpkey\fR. +It\*(Aqs called by \fBEVP_PKEY_free\fR\|(3), \fBEVP_PKEY_set_type\fR\|(3), +\&\fBEVP_PKEY_set_type_str\fR\|(3), and \fBEVP_PKEY_assign\fR\|(3). +.PP +.Vb 1 +\& int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2); +.Ve +.PP +The \fBpkey_ctrl()\fR method adds extra algorithm specific control. +It\*(Aqs called by \fBEVP_PKEY_get_default_digest_nid\fR\|(3), +\&\fBEVP_PKEY_set1_encoded_public_key\fR\|(3), +\&\fBEVP_PKEY_get1_encoded_public_key\fR\|(3), \fBPKCS7_SIGNER_INFO_set\fR\|(3), +\&\fBPKCS7_RECIP_INFO_set\fR\|(3), ... +.PP +.Vb 3 +\& int (*old_priv_decode) (EVP_PKEY *pkey, +\& const unsigned char **pder, int derlen); +\& int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder); +.Ve +.PP +The \fBold_priv_decode()\fR and \fBold_priv_encode()\fR methods decode / encode +they private key \fBpkey\fR from / to a DER formatted array. +These are exclusively used to help decoding / encoding older (pre +PKCS#8) PEM formatted encrypted private keys. +\&\fBold_priv_decode()\fR MUST return 0 on error, 1 on success. +\&\fBold_priv_encode()\fR MUST the return same kind of values as +\&\fBi2d_PrivateKey()\fR. +They\*(Aqre called by \fBd2i_PrivateKey\fR\|(3) and \fBi2d_PrivateKey\fR\|(3). +.PP +.Vb 5 +\& int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, +\& X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey); +\& int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, +\& X509_ALGOR *alg1, X509_ALGOR *alg2, +\& ASN1_BIT_STRING *sig); +.Ve +.PP +The \fBitem_sign()\fR and \fBitem_verify()\fR methods make it possible to have +algorithm specific signatures and verification of them. +.PP +\&\fBitem_sign()\fR MUST return one of: +.IP <=0 4 +.IX Item "<=0" +error +.IP 1 4 +.IX Item "1" +\&\fBitem_sign()\fR did everything, OpenSSL internals just needs to pass the +signature length back. +.IP 2 4 +.IX Item "2" +\&\fBitem_sign()\fR did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. +.IP 3 4 +.IX Item "3" +\&\fBitem_sign()\fR set the algorithm identifier \fBalgor1\fR and \fBalgor2\fR, +OpenSSL internals should just sign using those algorithms. +.PP +\&\fBitem_verify()\fR MUST return one of: +.IP <=0 4 +.IX Item "<=0" +error +.IP 1 4 +.IX Item "1" +\&\fBitem_sign()\fR did everything, OpenSSL internals just needs to pass the +signature length back. +.IP 2 4 +.IX Item "2" +\&\fBitem_sign()\fR did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. +.PP +\&\fBitem_verify()\fR and \fBitem_sign()\fR are called by \fBASN1_item_verify\fR\|(3) and +\&\fBASN1_item_sign\fR\|(3), and by extension, \fBX509_verify\fR\|(3), +\&\fBX509_REQ_verify\fR\|(3), \fBX509_sign\fR\|(3), \fBX509_REQ_sign\fR\|(3), ... +.PP +.Vb 2 +\& int (*siginf_set) (X509_SIG_INFO *siginf, const X509_ALGOR *alg, +\& const ASN1_STRING *sig); +.Ve +.PP +The \fBsiginf_set()\fR method is used to set custom \fBX509_SIG_INFO\fR +parameters. +It MUST return 0 on error, or 1 on success. +It\*(Aqs called as part of \fBX509_check_purpose\fR\|(3), \fBX509_check_ca\fR\|(3) +and \fBX509_check_issued\fR\|(3). +.PP +.Vb 3 +\& int (*pkey_check) (const EVP_PKEY *pk); +\& int (*pkey_public_check) (const EVP_PKEY *pk); +\& int (*pkey_param_check) (const EVP_PKEY *pk); +.Ve +.PP +The \fBpkey_check()\fR, \fBpkey_public_check()\fR and \fBpkey_param_check()\fR methods are used +to check the validity of \fBpk\fR for key\-pair, public component and parameters, +respectively. +They MUST return 0 for an invalid key, or 1 for a valid key. +They are called by \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3) and +\&\fBEVP_PKEY_param_check\fR\|(3) respectively. +.PP +.Vb 2 +\& int (*set_priv_key) (EVP_PKEY *pk, const unsigned char *priv, size_t len); +\& int (*set_pub_key) (EVP_PKEY *pk, const unsigned char *pub, size_t len); +.Ve +.PP +The \fBset_priv_key()\fR and \fBset_pub_key()\fR methods are used to set the raw private and +public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success. +They are called by \fBEVP_PKEY_new_raw_private_key\fR\|(3), and +\&\fBEVP_PKEY_new_raw_public_key\fR\|(3) respectively. +.PP +.Vb 2 +\& size_t (*dirty) (const EVP_PKEY *pk); +\& void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt); +.Ve +.PP +\&\fBdirty_cnt()\fR returns the internal key\*(Aqs dirty count. +This can be used to synchronise different copies of the same keys. +.PP +The \fBexport_to()\fR method exports the key material from the given key to +a provider, through the \fBEVP_KEYMGMT\fR\|(3) interface, if that provider +supports importing key material. +.SS Functions +.IX Subsection "Functions" +\&\fBEVP_PKEY_asn1_new()\fR creates and returns a new \fBEVP_PKEY_ASN1_METHOD\fR +object, and associates the given \fBid\fR, \fBflags\fR, \fBpem_str\fR and +\&\fBinfo\fR. +\&\fBid\fR is a NID, \fBpem_str\fR is the PEM type string, \fBinfo\fR is a +descriptive string. +The following \fBflags\fR are supported: +.PP +.Vb 1 +\& ASN1_PKEY_SIGPARAM_NULL +.Ve +.PP +If \fBASN1_PKEY_SIGPARAM_NULL\fR is set, then the signature algorithm +parameters are given the type \fBV_ASN1_NULL\fR by default, otherwise +they will be given the type \fBV_ASN1_UNDEF\fR (i.e. the parameter is +omitted). +See \fBX509_ALGOR_set0\fR\|(3) for more information. +.PP +\&\fBEVP_PKEY_asn1_copy()\fR copies an \fBEVP_PKEY_ASN1_METHOD\fR object from +\&\fBsrc\fR to \fBdst\fR. +This function is not thread safe, it\*(Aqs recommended to only use this +when initializing the application. +.PP +\&\fBEVP_PKEY_asn1_free()\fR frees an existing \fBEVP_PKEY_ASN1_METHOD\fR pointed +by \fBameth\fR. If the argument is NULL, nothing is done. +.PP +\&\fBEVP_PKEY_asn1_add0()\fR adds \fBameth\fR to the user defined stack of +methods unless another \fBEVP_PKEY_ASN1_METHOD\fR with the same NID is +already there. +This function is not thread safe, it\*(Aqs recommended to only use this +when initializing the application. +.PP +\&\fBEVP_PKEY_asn1_add_alias()\fR creates an alias with the NID \fBto\fR for the +\&\fBEVP_PKEY_ASN1_METHOD\fR with NID \fBfrom\fR unless another +\&\fBEVP_PKEY_ASN1_METHOD\fR with the same NID is already added. +This function is not thread safe, it\*(Aqs recommended to only use this +when initializing the application. +.PP +\&\fBEVP_PKEY_asn1_set_public()\fR, \fBEVP_PKEY_asn1_set_private()\fR, +\&\fBEVP_PKEY_asn1_set_param()\fR, \fBEVP_PKEY_asn1_set_free()\fR, +\&\fBEVP_PKEY_asn1_set_ctrl()\fR, \fBEVP_PKEY_asn1_set_item()\fR, +\&\fBEVP_PKEY_asn1_set_siginf()\fR, \fBEVP_PKEY_asn1_set_check()\fR, +\&\fBEVP_PKEY_asn1_set_public_check()\fR, \fBEVP_PKEY_asn1_set_param_check()\fR, +\&\fBEVP_PKEY_asn1_set_security_bits()\fR, \fBEVP_PKEY_asn1_set_set_priv_key()\fR, +\&\fBEVP_PKEY_asn1_set_set_pub_key()\fR, \fBEVP_PKEY_asn1_set_get_priv_key()\fR and +\&\fBEVP_PKEY_asn1_set_get_pub_key()\fR set the diverse methods of the given +\&\fBEVP_PKEY_ASN1_METHOD\fR object. +.PP +\&\fBEVP_PKEY_get0_asn1()\fR finds the \fBEVP_PKEY_ASN1_METHOD\fR associated +with the key \fBpkey\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_asn1_new()\fR returns NULL on error, or a pointer to an +\&\fBEVP_PKEY_ASN1_METHOD\fR object otherwise. +.PP +\&\fBEVP_PKEY_asn1_add0()\fR and \fBEVP_PKEY_asn1_add_alias()\fR return 0 on error, +or 1 on success. +.PP +\&\fBEVP_PKEY_get0_asn1()\fR returns NULL on error, or a pointer to a constant +\&\fBEVP_PKEY_ASN1_METHOD\fR object otherwise. +.SH HISTORY +.IX Header "HISTORY" +The signature of the \fIpub_decode\fR functional argument of +\&\fBEVP_PKEY_asn1_set_public()\fR has changed in OpenSSL 3.0 so its \fIpub\fR +parameter is now constified. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_ctrl.3 b/static/netbsd/man3/EVP_PKEY_CTX_ctrl.3 new file mode 100644 index 00000000..850a0b62 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_ctrl.3 @@ -0,0 +1,747 @@ +.\" $NetBSD: EVP_PKEY_CTX_ctrl.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_ctrl 3" +.TH EVP_PKEY_CTX_ctrl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_ctrl, +EVP_PKEY_CTX_ctrl_str, +EVP_PKEY_CTX_ctrl_uint64, +EVP_PKEY_CTX_md, +EVP_PKEY_CTX_set_signature_md, +EVP_PKEY_CTX_get_signature_md, +EVP_PKEY_CTX_set_mac_key, +EVP_PKEY_CTX_set_group_name, +EVP_PKEY_CTX_get_group_name, +EVP_PKEY_CTX_set_rsa_padding, +EVP_PKEY_CTX_get_rsa_padding, +EVP_PKEY_CTX_set_rsa_pss_saltlen, +EVP_PKEY_CTX_get_rsa_pss_saltlen, +EVP_PKEY_CTX_set_rsa_keygen_bits, +EVP_PKEY_CTX_set_rsa_keygen_pubexp, +EVP_PKEY_CTX_set1_rsa_keygen_pubexp, +EVP_PKEY_CTX_set_rsa_keygen_primes, +EVP_PKEY_CTX_set_rsa_mgf1_md_name, +EVP_PKEY_CTX_set_rsa_mgf1_md, +EVP_PKEY_CTX_get_rsa_mgf1_md, +EVP_PKEY_CTX_get_rsa_mgf1_md_name, +EVP_PKEY_CTX_set_rsa_oaep_md_name, +EVP_PKEY_CTX_set_rsa_oaep_md, +EVP_PKEY_CTX_get_rsa_oaep_md, +EVP_PKEY_CTX_get_rsa_oaep_md_name, +EVP_PKEY_CTX_set0_rsa_oaep_label, +EVP_PKEY_CTX_get0_rsa_oaep_label, +EVP_PKEY_CTX_set_dsa_paramgen_bits, +EVP_PKEY_CTX_set_dsa_paramgen_q_bits, +EVP_PKEY_CTX_set_dsa_paramgen_md, +EVP_PKEY_CTX_set_dsa_paramgen_md_props, +EVP_PKEY_CTX_set_dsa_paramgen_gindex, +EVP_PKEY_CTX_set_dsa_paramgen_type, +EVP_PKEY_CTX_set_dsa_paramgen_seed, +EVP_PKEY_CTX_set_dh_paramgen_prime_len, +EVP_PKEY_CTX_set_dh_paramgen_subprime_len, +EVP_PKEY_CTX_set_dh_paramgen_generator, +EVP_PKEY_CTX_set_dh_paramgen_type, +EVP_PKEY_CTX_set_dh_paramgen_gindex, +EVP_PKEY_CTX_set_dh_paramgen_seed, +EVP_PKEY_CTX_set_dh_rfc5114, +EVP_PKEY_CTX_set_dhx_rfc5114, +EVP_PKEY_CTX_set_dh_pad, +EVP_PKEY_CTX_set_dh_nid, +EVP_PKEY_CTX_set_dh_kdf_type, +EVP_PKEY_CTX_get_dh_kdf_type, +EVP_PKEY_CTX_set0_dh_kdf_oid, +EVP_PKEY_CTX_get0_dh_kdf_oid, +EVP_PKEY_CTX_set_dh_kdf_md, +EVP_PKEY_CTX_get_dh_kdf_md, +EVP_PKEY_CTX_set_dh_kdf_outlen, +EVP_PKEY_CTX_get_dh_kdf_outlen, +EVP_PKEY_CTX_set0_dh_kdf_ukm, +EVP_PKEY_CTX_get0_dh_kdf_ukm, +EVP_PKEY_CTX_set_ec_paramgen_curve_nid, +EVP_PKEY_CTX_set_ec_param_enc, +EVP_PKEY_CTX_set_ecdh_cofactor_mode, +EVP_PKEY_CTX_get_ecdh_cofactor_mode, +EVP_PKEY_CTX_set_ecdh_kdf_type, +EVP_PKEY_CTX_get_ecdh_kdf_type, +EVP_PKEY_CTX_set_ecdh_kdf_md, +EVP_PKEY_CTX_get_ecdh_kdf_md, +EVP_PKEY_CTX_set_ecdh_kdf_outlen, +EVP_PKEY_CTX_get_ecdh_kdf_outlen, +EVP_PKEY_CTX_set0_ecdh_kdf_ukm, +EVP_PKEY_CTX_get0_ecdh_kdf_ukm, +EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len, +EVP_PKEY_CTX_set_kem_op +\&\- algorithm specific control operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, +\& int cmd, int p1, void *p2); +\& int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, +\& int cmd, uint64_t value); +\& int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, +\& const char *value); +\& +\& int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md); +\& +\& int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); +\& +\& int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key, +\& int len); +\& int EVP_PKEY_CTX_set_group_name(EVP_PKEY_CTX *ctx, const char *name); +\& int EVP_PKEY_CTX_get_group_name(EVP_PKEY_CTX *ctx, char *name, size_t namelen); +\& +\& int EVP_PKEY_CTX_set_kem_op(EVP_PKEY_CTX *ctx, const char *op); +\& +\& #include +\& +\& int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); +\& int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad); +\& int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int saltlen); +\& int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *saltlen); +\& int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); +\& int EVP_PKEY_CTX_set1_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); +\& int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes); +\& int EVP_PKEY_CTX_set_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, const char *mdname, +\& const char *mdprops); +\& int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); +\& int EVP_PKEY_CTX_get_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, char *name, +\& size_t namelen); +\& int EVP_PKEY_CTX_set_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, const char *mdname, +\& const char *mdprops); +\& int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); +\& int EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name, +\& size_t namelen); +\& int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, void *label, +\& int len); +\& int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label); +\& +\& #include +\& +\& int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); +\& int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits); +\& int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_set_dsa_paramgen_md_props(EVP_PKEY_CTX *ctx, +\& const char *md_name, +\& const char *md_properties); +\& int EVP_PKEY_CTX_set_dsa_paramgen_type(EVP_PKEY_CTX *ctx, const char *name); +\& int EVP_PKEY_CTX_set_dsa_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); +\& int EVP_PKEY_CTX_set_dsa_paramgen_seed(EVP_PKEY_CTX *ctx, +\& const unsigned char *seed, +\& size_t seedlen); +\& +\& #include +\& +\& int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); +\& int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len); +\& int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); +\& int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type); +\& int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); +\& int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); +\& int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); +\& int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); +\& int EVP_PKEY_CTX_set_dh_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); +\& int EVP_PKEY_CTX_set_dh_paramgen_seed(EVP_PKEY_CTX *ctx, +\& const unsigned char *seed, +\& size_t seedlen); +\& int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); +\& int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid); +\& int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid); +\& int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); +\& int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); +\& int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); +\& int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); +\& +\& #include +\& +\& int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); +\& int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); +\& int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode); +\& int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); +\& int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); +\& int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); +\& int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); +\& int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); +\& +\& int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); +\& int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); +\& int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); +\& +\& #include +\& +\& int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); +\& +\& #include +\& +\& int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_CTX_ctrl()\fR sends a control operation to the context \fIctx\fR. The key +type used must match \fIkeytype\fR if it is not \-1. The parameter \fIoptype\fR is a +mask indicating which operations the control can be applied to. +The control command is indicated in \fIcmd\fR and any additional arguments in +\&\fIp1\fR and \fIp2\fR. +.PP +For \fIcmd\fR = \fBEVP_PKEY_CTRL_SET_MAC_KEY\fR, \fIp1\fR is the length of the MAC key, +and \fIp2\fR is the MAC key. This is used by Poly1305, SipHash, HMAC and CMAC. +.PP +Applications will not normally call \fBEVP_PKEY_CTX_ctrl()\fR directly but will +instead call one of the algorithm specific functions below. +.PP +\&\fBEVP_PKEY_CTX_ctrl_uint64()\fR is a wrapper that directly passes a +uint64 value as \fIp2\fR to \fBEVP_PKEY_CTX_ctrl()\fR. +.PP +\&\fBEVP_PKEY_CTX_ctrl_str()\fR allows an application to send an algorithm +specific control operation to a context \fIctx\fR in string form. This is +intended to be used for options specified on the command line or in text +files. The commands supported are documented in the openssl utility +command line pages for the option \fI\-pkeyopt\fR which is supported by the +\&\fIpkeyutl\fR, \fIgenpkey\fR and \fIreq\fR commands. +.PP +\&\fBEVP_PKEY_CTX_md()\fR sends a message digest control operation to the context +\&\fIctx\fR. The message digest is specified by its name \fImd\fR. +.PP +\&\fBEVP_PKEY_CTX_set_signature_md()\fR sets the message digest type used +in a signature. It can be used in the RSA, DSA and ECDSA algorithms. +.PP +\&\fBEVP_PKEY_CTX_get_signature_md()\fRgets the message digest type used +in a signature. It can be used in the RSA, DSA and ECDSA algorithms. +.PP +Key generation typically involves setting up parameters to be used and +generating the private and public key data. Some algorithm implementations +allow private key data to be set explicitly using \fBEVP_PKEY_CTX_set_mac_key()\fR. +In this case key generation is simply the process of setting up the +parameters for the key and then setting the raw key data to the value explicitly. +Normally applications would call \fBEVP_PKEY_new_raw_private_key\fR\|(3) or similar +functions instead. +.PP +\&\fBEVP_PKEY_CTX_set_mac_key()\fR can be used with any of the algorithms supported by +the \fBEVP_PKEY_new_raw_private_key\fR\|(3) function. +.PP +\&\fBEVP_PKEY_CTX_set_group_name()\fR sets the group name to \fIname\fR for parameter and +key generation. For example for EC keys this will set the curve name and for +DH keys it will set the name of the finite field group. +.PP +\&\fBEVP_PKEY_CTX_get_group_name()\fR finds the group name that\*(Aqs currently +set with \fIctx\fR, and writes it to the location that \fIname\fR points at, as long +as its size \fInamelen\fR is large enough to store that name, including a +terminating NUL byte. +.SS "RSA parameters" +.IX Subsection "RSA parameters" +\&\fBEVP_PKEY_CTX_set_rsa_padding()\fR sets the RSA padding mode for \fIctx\fR. +The \fIpad\fR parameter can take the value \fBRSA_PKCS1_PADDING\fR for PKCS#1 +padding, \fBRSA_NO_PADDING\fR for +no padding, \fBRSA_PKCS1_OAEP_PADDING\fR for OAEP padding (encrypt and +decrypt only), \fBRSA_X931_PADDING\fR for X9.31 padding (signature operations +only), \fBRSA_PKCS1_PSS_PADDING\fR (sign and verify only) and +\&\fBRSA_PKCS1_WITH_TLS_PADDING\fR for TLS RSA ClientKeyExchange message padding +(decryption only). +.PP +Two RSA padding modes behave differently if \fBEVP_PKEY_CTX_set_signature_md()\fR +is used. If this function is called for PKCS#1 padding the plaintext buffer is +an actual digest value and is encapsulated in a DigestInfo structure according +to PKCS#1 when signing and this structure is expected (and stripped off) when +verifying. If this control is not used with RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. In the case of X9.31 +padding for RSA the algorithm identifier byte is added or checked and removed +if this control is called. If it is not called then the first byte of the plaintext +buffer is expected to be the algorithm identifier byte. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_padding()\fR gets the RSA padding mode for \fIctx\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_pss_saltlen()\fR sets the RSA PSS salt length to \fIsaltlen\fR. +As its name implies it is only supported for PSS padding. If this function is +not called then the salt length is maximized up to the digest length when +signing and auto detection when verifying. Four special values are supported: +.IP \fBRSA_PSS_SALTLEN_DIGEST\fR 4 +.IX Item "RSA_PSS_SALTLEN_DIGEST" +sets the salt length to the digest length. +.IP \fBRSA_PSS_SALTLEN_MAX\fR 4 +.IX Item "RSA_PSS_SALTLEN_MAX" +sets the salt length to the maximum permissible value. +.IP \fBRSA_PSS_SALTLEN_AUTO\fR 4 +.IX Item "RSA_PSS_SALTLEN_AUTO" +causes the salt length to be automatically determined based on the +\&\fBPSS\fR block structure when verifying. When signing, it has the same +meaning as \fBRSA_PSS_SALTLEN_MAX\fR. +.IP \fBRSA_PSS_SALTLEN_AUTO_DIGEST_MAX\fR 4 +.IX Item "RSA_PSS_SALTLEN_AUTO_DIGEST_MAX" +causes the salt length to be automatically determined based on the \fBPSS\fR block +structure when verifying, like \fBRSA_PSS_SALTLEN_AUTO\fR. When signing, the salt +length is maximized up to a maximum of the digest length to comply with FIPS +186\-4 section 5.5. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_pss_saltlen()\fR gets the RSA PSS salt length for \fIctx\fR. +The padding mode must already have been set to \fBRSA_PKCS1_PSS_PADDING\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_keygen_bits()\fR sets the RSA key length for +RSA key generation to \fIbits\fR. If not specified 2048 bits is used. +.PP +\&\fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp()\fR sets the public exponent value for RSA key +generation to the value stored in \fIpubexp\fR. Currently it should be an odd +integer. In accordance with the OpenSSL naming convention, the \fIpubexp\fR pointer +must be freed independently of the EVP_PKEY_CTX (ie, it is internally copied). +If not specified 65537 is used. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR does the same as +\&\fBEVP_PKEY_CTX_set1_rsa_keygen_pubexp()\fR except that there is no internal copy and +therefore \fIpubexp\fR should not be modified or freed after the call. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_keygen_primes()\fR sets the number of primes for +RSA key generation to \fIprimes\fR. If not specified 2 is used. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_mgf1_md_name()\fR sets the MGF1 digest for RSA +padding schemes to the digest named \fImdname\fR. If the RSA algorithm +implementation for the selected provider supports it then the digest will be +fetched using the properties \fImdprops\fR. If not explicitly set the signing +digest is used. The padding mode must have been set to \fBRSA_PKCS1_OAEP_PADDING\fR +or \fBRSA_PKCS1_PSS_PADDING\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_mgf1_md()\fR does the same as +\&\fBEVP_PKEY_CTX_set_rsa_mgf1_md_name()\fR except that the name of the digest is +inferred from the supplied \fImd\fR and it is not possible to specify any +properties. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_mgf1_md_name()\fR gets the name of the MGF1 +digest algorithm for \fIctx\fR. If not explicitly set the signing digest is used. +The padding mode must have been set to \fBRSA_PKCS1_OAEP_PADDING\fR or +\&\fBRSA_PKCS1_PSS_PADDING\fR. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_mgf1_md()\fR does the same as +\&\fBEVP_PKEY_CTX_get_rsa_mgf1_md_name()\fR except that it returns a pointer to an +EVP_MD object instead. Note that only known, built\-in EVP_MD objects will be +returned. The EVP_MD object may be NULL if the digest is not one of these (such +as a digest only implemented in a third party provider). +.PP +\&\fBEVP_PKEY_CTX_set_rsa_oaep_md_name()\fR sets the message digest type +used in RSA OAEP to the digest named \fImdname\fR. If the RSA algorithm +implementation for the selected provider supports it then the digest will be +fetched using the properties \fImdprops\fR. The padding mode must have been set to +\&\fBRSA_PKCS1_OAEP_PADDING\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_oaep_md()\fR does the same as +\&\fBEVP_PKEY_CTX_set_rsa_oaep_md_name()\fR except that the name of the digest is +inferred from the supplied \fImd\fR and it is not possible to specify any +properties. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_oaep_md_name()\fR gets the message digest +algorithm name used in RSA OAEP and stores it in the buffer \fIname\fR which is of +size \fInamelen\fR. The padding mode must have been set to +\&\fBRSA_PKCS1_OAEP_PADDING\fR. The buffer should be sufficiently large for any +expected digest algorithm names or the function will fail. +.PP +\&\fBEVP_PKEY_CTX_get_rsa_oaep_md()\fR does the same as +\&\fBEVP_PKEY_CTX_get_rsa_oaep_md_name()\fR except that it returns a pointer to an +EVP_MD object instead. Note that only known, built\-in EVP_MD objects will be +returned. The EVP_MD object may be NULL if the digest is not one of these (such +as a digest only implemented in a third party provider). +.PP +\&\fBEVP_PKEY_CTX_set0_rsa_oaep_label()\fR sets the RSA OAEP label to binary data +\&\fIlabel\fR and its length in bytes to \fIlen\fR. If \fIlabel\fR is NULL or \fIlen\fR is 0, +the label is cleared. The library takes ownership of the label so the +caller should not free the original memory pointed to by \fIlabel\fR. +The padding mode must have been set to \fBRSA_PKCS1_OAEP_PADDING\fR. +.PP +\&\fBEVP_PKEY_CTX_get0_rsa_oaep_label()\fR gets the RSA OAEP label to +\&\fIlabel\fR. The return value is the label length. The padding mode +must have been set to \fBRSA_PKCS1_OAEP_PADDING\fR. The resulting pointer is owned +by the library and should not be freed by the caller. +.PP +\&\fBRSA_PKCS1_WITH_TLS_PADDING\fR is used when decrypting an RSA encrypted TLS +pre\-master secret in a TLS ClientKeyExchange message. It is the same as +RSA_PKCS1_PADDING except that it additionally verifies that the result is the +correct length and the first two bytes are the protocol version initially +requested by the client. If the encrypted content is publicly invalid then the +decryption will fail. However, if the padding checks fail then decryption will +still appear to succeed but a random TLS premaster secret will be returned +instead. This padding mode accepts two parameters which can be set using the +\&\fBEVP_PKEY_CTX_set_params\fR\|(3) function. These are +OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and +OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be +unsigned integers. Normally only the first of these will be set and represents +the TLS protocol version that was first requested by the client (e.g. 0x0303 for +TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the +negotiated protocol version instead of the protocol version first requested. If +this behaviour should be tolerated then +OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual +negotiated protocol version. Otherwise it should be left unset. +.PP +Similarly to the \fBRSA_PKCS1_WITH_TLS_PADDING\fR above, since OpenSSL version +3.2.0, the use of \fBRSA_PKCS1_PADDING\fR will return a randomly generated message +instead of padding errors in case padding checks fail. Applications that +want to remain secure while using earlier versions of OpenSSL, or a provider +that doesn\*(Aqt implement the implicit rejection mechanism, still need to +handle both the error code from the RSA decryption operation and the +returned message in a side channel secure manner. +This protection against Bleichenbacher attacks can be disabled by setting +\&\fBOSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION\fR (an unsigned integer) to 0. +.SS "DSA parameters" +.IX Subsection "DSA parameters" +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_bits()\fR sets the number of bits used for DSA +parameter generation to \fBnbits\fR. If not specified, 2048 is used. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_q_bits()\fR sets the number of bits in the subprime +parameter \fIq\fR for DSA parameter generation to \fIqbits\fR. If not specified, 224 +is used. If a digest function is specified below, this parameter is ignored and +instead, the number of bits in \fIq\fR matches the size of the digest. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_md()\fR sets the digest function used for DSA +parameter generation to \fImd\fR. If not specified, one of SHA\-1, SHA\-224, or +SHA\-256 is selected to match the bit length of \fIq\fR above. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_md_props()\fR sets the digest function used for DSA +parameter generation using \fImd_name\fR and \fImd_properties\fR to retrieve the +digest from a provider. +If not specified, \fImd_name\fR will be set to one of SHA\-1, SHA\-224, or +SHA\-256 depending on the bit length of \fIq\fR above. \fImd_properties\fR is a +property query string that has a default value of \*(Aq\*(Aq if not specified. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_gindex()\fR sets the \fIgindex\fR used by the generator +G. The default value is \-1 which uses unverifiable g, otherwise a positive value +uses verifiable g. This value must be saved if key validation of g is required, +since it is not part of a persisted key. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_seed()\fR sets the \fIseed\fR to use for generation +rather than using a randomly generated value for the seed. This is useful for +testing purposes only and can fail if the seed does not produce primes for both +p & q on its first iteration. This value must be saved if key validation of +p, q, and verifiable g are required, since it is not part of a persisted key. +.PP +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_type()\fR sets the generation type to use FIPS186\-4 +generation if \fIname\fR is "fips186_4", or FIPS186\-2 generation if \fIname\fR is +"fips186_2". The default value for the default provider is "fips186_2". The +default value for the FIPS provider is "fips186_4". +.SS "DH parameters" +.IX Subsection "DH parameters" +\&\fBEVP_PKEY_CTX_set_dh_paramgen_prime_len()\fR sets the length of the DH prime +parameter \fIp\fR for DH parameter generation. If this function is not called then +2048 is used. Only accepts lengths greater than or equal to 256. +.PP +\&\fBEVP_PKEY_CTX_set_dh_paramgen_subprime_len()\fR sets the length of the DH +optional subprime parameter \fIq\fR for DH parameter generation. The default is +256 if the prime is at least 2048 bits long or 160 otherwise. The DH paramgen +type must have been set to "fips186_4". +.PP +\&\fBEVP_PKEY_CTX_set_dh_paramgen_generator()\fR sets DH generator to \fIgen\fR for DH +parameter generation. If not specified 2 is used. +.PP +\&\fBEVP_PKEY_CTX_set_dh_paramgen_type()\fR sets the key type for DH parameter +generation. The supported parameters are: +.IP \fBDH_PARAMGEN_TYPE_GROUP\fR 4 +.IX Item "DH_PARAMGEN_TYPE_GROUP" +Use a named group. If only the safe prime parameter \fIp\fR is set this can be +used to select a ffdhe safe prime group of the correct size. +.IP \fBDH_PARAMGEN_TYPE_FIPS_186_4\fR 4 +.IX Item "DH_PARAMGEN_TYPE_FIPS_186_4" +FIPS186\-4 FFC parameter generator. +.IP \fBDH_PARAMGEN_TYPE_FIPS_186_2\fR 4 +.IX Item "DH_PARAMGEN_TYPE_FIPS_186_2" +FIPS186\-2 FFC parameter generator (X9.42 DH). +.IP \fBDH_PARAMGEN_TYPE_GENERATOR\fR 4 +.IX Item "DH_PARAMGEN_TYPE_GENERATOR" +Uses a safe prime generator g (PKCS#3 format). +.PP +The default in the default provider is \fBDH_PARAMGEN_TYPE_GENERATOR\fR for the +"DH" keytype, and \fBDH_PARAMGEN_TYPE_FIPS_186_2\fR for the "DHX" keytype. In the +FIPS provider the default value is \fBDH_PARAMGEN_TYPE_GROUP\fR for the "DH" +keytype and <\fBDH_PARAMGEN_TYPE_FIPS_186_4\fR for the "DHX" keytype. +.PP +\&\fBEVP_PKEY_CTX_set_dh_paramgen_gindex()\fR sets the \fIgindex\fR used by the generator G. +The default value is \-1 which uses unverifiable g, otherwise a positive value +uses verifiable g. This value must be saved if key validation of g is required, +since it is not part of a persisted key. +.PP +\&\fBEVP_PKEY_CTX_set_dh_paramgen_seed()\fR sets the \fIseed\fR to use for generation +rather than using a randomly generated value for the seed. This is useful for +testing purposes only and can fail if the seed does not produce primes for both +p & q on its first iteration. This value must be saved if key validation of p, q, +and verifiable g are required, since it is not part of a persisted key. +.PP +\&\fBEVP_PKEY_CTX_set_dh_pad()\fR sets the DH padding mode. +If \fIpad\fR is 1 the shared secret is padded with zeros up to the size of the DH +prime \fIp\fR. +If \fIpad\fR is zero (the default) then no padding is performed. +.PP +\&\fBEVP_PKEY_CTX_set_dh_nid()\fR sets the DH parameters to values corresponding to +\&\fInid\fR as defined in RFC7919 or RFC3526. The \fInid\fR parameter must be +\&\fBNID_ffdhe2048\fR, \fBNID_ffdhe3072\fR, \fBNID_ffdhe4096\fR, \fBNID_ffdhe6144\fR, +\&\fBNID_ffdhe8192\fR, \fBNID_modp_1536\fR, \fBNID_modp_2048\fR, \fBNID_modp_3072\fR, +\&\fBNID_modp_4096\fR, \fBNID_modp_6144\fR, \fBNID_modp_8192\fR or \fBNID_undef\fR to clear +the stored value. This function can be called during parameter or key generation. +The nid parameter and the rfc5114 parameter are mutually exclusive. +.PP +\&\fBEVP_PKEY_CTX_set_dh_rfc5114()\fR and \fBEVP_PKEY_CTX_set_dhx_rfc5114()\fR both set the +DH parameters to the values defined in RFC5114. The \fIrfc5114\fR parameter must +be 1, 2 or 3 corresponding to RFC5114 sections 2.1, 2.2 and 2.3. or 0 to clear +the stored value. This macro can be called during parameter generation. The +\&\fIctx\fR must have a key type of \fBEVP_PKEY_DHX\fR. +The rfc5114 parameter and the nid parameter are mutually exclusive. +.SS "DH key derivation function parameters" +.IX Subsection "DH key derivation function parameters" +Note that all of the following functions require that the \fIctx\fR parameter has +a private key type of \fBEVP_PKEY_DHX\fR. When using key derivation, the output of +\&\fBEVP_PKEY_derive()\fR is the output of the KDF instead of the DH shared secret. +The KDF output is typically used as a Key Encryption Key (KEK) that in turn +encrypts a Content Encryption Key (CEK). +.PP +\&\fBEVP_PKEY_CTX_set_dh_kdf_type()\fR sets the key derivation function type to \fIkdf\fR +for DH key derivation. Possible values are \fBEVP_PKEY_DH_KDF_NONE\fR and +\&\fBEVP_PKEY_DH_KDF_X9_42\fR which uses the key derivation specified in RFC2631 +(based on the keying algorithm described in X9.42). When using key derivation, +the \fIkdf_oid\fR, \fIkdf_md\fR and \fIkdf_outlen\fR parameters must also be specified. +.PP +\&\fBEVP_PKEY_CTX_get_dh_kdf_type()\fR gets the key derivation function type for \fIctx\fR +used for DH key derivation. Possible values are \fBEVP_PKEY_DH_KDF_NONE\fR and +\&\fBEVP_PKEY_DH_KDF_X9_42\fR. +.PP +\&\fBEVP_PKEY_CTX_set0_dh_kdf_oid()\fR sets the key derivation function object +identifier to \fIoid\fR for DH key derivation. This OID should identify the +algorithm to be used with the Content Encryption Key. +The library takes ownership of the object identifier so the caller should not +free the original memory pointed to by \fIoid\fR. +.PP +\&\fBEVP_PKEY_CTX_get0_dh_kdf_oid()\fR gets the key derivation function oid for \fIctx\fR +used for DH key derivation. The resulting pointer is owned by the library and +should not be freed by the caller. +.PP +\&\fBEVP_PKEY_CTX_set_dh_kdf_md()\fR sets the key derivation function message digest to +\&\fImd\fR for DH key derivation. Note that RFC2631 specifies that this digest should +be SHA1 but OpenSSL tolerates other digests. +.PP +\&\fBEVP_PKEY_CTX_get_dh_kdf_md()\fR gets the key derivation function message digest for +\&\fIctx\fR used for DH key derivation. +.PP +\&\fBEVP_PKEY_CTX_set_dh_kdf_outlen()\fR sets the key derivation function output length +to \fIlen\fR for DH key derivation. +.PP +\&\fBEVP_PKEY_CTX_get_dh_kdf_outlen()\fR gets the key derivation function output length +for \fIctx\fR used for DH key derivation. +.PP +\&\fBEVP_PKEY_CTX_set0_dh_kdf_ukm()\fR sets the user key material to \fIukm\fR and its +length to \fIlen\fR for DH key derivation. This parameter is optional and +corresponds to the partyAInfo field in RFC2631 terms. The specification +requires that it is 512 bits long but this is not enforced by OpenSSL. +The library takes ownership of the user key material so the caller should not +free the original memory pointed to by \fIukm\fR. +.PP +\&\fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR gets the user key material for \fIctx\fR. +The return value is the user key material length. The resulting pointer is owned +by the library and should not be freed by the caller. +.SS "EC parameters" +.IX Subsection "EC parameters" +Use \fBEVP_PKEY_CTX_set_group_name()\fR (described above) to set the curve name to +\&\fIname\fR for parameter and key generation. +.PP +\&\fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR does the same as +\&\fBEVP_PKEY_CTX_set_group_name()\fR, but is specific to EC and uses a \fInid\fR rather +than a name string. +.PP +For EC parameter generation, one of \fBEVP_PKEY_CTX_set_group_name()\fR +or \fBEVP_PKEY_CTX_set_ec_paramgen_curve_nid()\fR must be called or an error occurs +because there is no default curve. +These function can also be called to set the curve explicitly when +generating an EC key. +.PP +\&\fBEVP_PKEY_CTX_get_group_name()\fR (described above) can be used to obtain the curve +name that\*(Aqs currently set with \fIctx\fR. +.PP +\&\fBEVP_PKEY_CTX_set_ec_param_enc()\fR sets the EC parameter encoding to \fIparam_enc\fR +when generating EC parameters or an EC key. The encoding can be +\&\fBOPENSSL_EC_EXPLICIT_CURVE\fR for explicit parameters (the default in versions +of OpenSSL before 1.1.0) or \fBOPENSSL_EC_NAMED_CURVE\fR to use named curve form. +For maximum compatibility the named curve form should be used. Note: the +\&\fBOPENSSL_EC_NAMED_CURVE\fR value was added in OpenSSL 1.1.0; previous +versions should use 0 instead. +.SS "ECDH parameters" +.IX Subsection "ECDH parameters" +\&\fBEVP_PKEY_CTX_set_ecdh_cofactor_mode()\fR sets the cofactor mode to \fIcofactor_mode\fR +for ECDH key derivation. Possible values are 1 to enable cofactor +key derivation, 0 to disable it and \-1 to clear the stored cofactor mode and +fallback to the private key cofactor mode. +.PP +\&\fBEVP_PKEY_CTX_get_ecdh_cofactor_mode()\fR returns the cofactor mode for \fIctx\fR used +for ECDH key derivation. Possible values are 1 when cofactor key derivation is +enabled and 0 otherwise. +.SS "ECDH key derivation function parameters" +.IX Subsection "ECDH key derivation function parameters" +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_type()\fR sets the key derivation function type to +\&\fIkdf\fR for ECDH key derivation. Possible values are \fBEVP_PKEY_ECDH_KDF_NONE\fR +and \fBEVP_PKEY_ECDH_KDF_X9_63\fR which uses the key derivation specified in X9.63. +When using key derivation, the \fIkdf_md\fR and \fIkdf_outlen\fR parameters must +also be specified. +.PP +\&\fBEVP_PKEY_CTX_get_ecdh_kdf_type()\fR returns the key derivation function type for +\&\fIctx\fR used for ECDH key derivation. Possible values are +\&\fBEVP_PKEY_ECDH_KDF_NONE\fR and \fBEVP_PKEY_ECDH_KDF_X9_63\fR. +.PP +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_md()\fR sets the key derivation function message digest +to \fImd\fR for ECDH key derivation. Note that X9.63 specifies that this digest +should be SHA1 but OpenSSL tolerates other digests. +.PP +\&\fBEVP_PKEY_CTX_get_ecdh_kdf_md()\fR gets the key derivation function message digest +for \fIctx\fR used for ECDH key derivation. +.PP +\&\fBEVP_PKEY_CTX_set_ecdh_kdf_outlen()\fR sets the key derivation function output +length to \fIlen\fR for ECDH key derivation. +.PP +\&\fBEVP_PKEY_CTX_get_ecdh_kdf_outlen()\fR gets the key derivation function output +length for \fIctx\fR used for ECDH key derivation. +.PP +\&\fBEVP_PKEY_CTX_set0_ecdh_kdf_ukm()\fR sets the user key material to \fIukm\fR for ECDH +key derivation. This parameter is optional and corresponds to the shared info in +X9.63 terms. The library takes ownership of the user key material so the caller +should not free the original memory pointed to by \fIukm\fR. +.PP +\&\fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR gets the user key material for \fIctx\fR. +The return value is the user key material length. The resulting pointer is owned +by the library and should not be freed by the caller. +.SS "Other parameters" +.IX Subsection "Other parameters" +\&\fBEVP_PKEY_CTX_set1_id()\fR, \fBEVP_PKEY_CTX_get1_id()\fR and \fBEVP_PKEY_CTX_get1_id_len()\fR +are used to manipulate the special identifier field for specific signature +algorithms such as SM2. The \fBEVP_PKEY_CTX_set1_id()\fR sets an ID pointed by \fIid\fR with +the length \fIid_len\fR to the library. The library takes a copy of the id so that +the caller can safely free the original memory pointed to by \fIid\fR. +\&\fBEVP_PKEY_CTX_get1_id_len()\fR returns the length of the ID set via a previous call +to \fBEVP_PKEY_CTX_set1_id()\fR. The length is usually used to allocate adequate +memory for further calls to \fBEVP_PKEY_CTX_get1_id()\fR. \fBEVP_PKEY_CTX_get1_id()\fR +returns the previously set ID value to caller in \fIid\fR. The caller should +allocate adequate memory space for the \fIid\fR before calling \fBEVP_PKEY_CTX_get1_id()\fR. +.PP +\&\fBEVP_PKEY_CTX_set_kem_op()\fR sets the KEM operation to run. This can be set after +\&\fBEVP_PKEY_encapsulate_init()\fR or \fBEVP_PKEY_decapsulate_init()\fR to select the kem +operation. For the key types that support encapsulation and don\*(Aqt have the +default operation, e.g. RSA, this function must be called before +\&\fBEVP_PKEY_encapsulate()\fR or \fBEVP_PKEY_decapsulate()\fR. +.PP +The supported parameters for the built\-in algorithms are documented in +\&\fBEVP_KEM\-RSA\fR\|(7), \fBEVP_KEM\-EC\fR\|(7), \fBEVP_KEM\-X25519\fR\|(7), +\&\fBEVP_KEM\-X448\fR\|(7), and \fBEVP_KEM\-ML\-KEM\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All other functions described on this page return a positive value for success +and 0 or a negative value for failure. In particular a return value of \-2 +indicates the operation is not supported by the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_params\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3) +\&\fBEVP_PKEY_encapsulate\fR\|(3) +\&\fBEVP_PKEY_decapsulate\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PKEY_CTX_get_rsa_oaep_md_name()\fR, \fBEVP_PKEY_CTX_get_rsa_mgf1_md_name()\fR, +\&\fBEVP_PKEY_CTX_set_rsa_mgf1_md_name()\fR, \fBEVP_PKEY_CTX_set_rsa_oaep_md_name()\fR, +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_md_props()\fR, \fBEVP_PKEY_CTX_set_dsa_paramgen_gindex()\fR, +\&\fBEVP_PKEY_CTX_set_dsa_paramgen_type()\fR, \fBEVP_PKEY_CTX_set_dsa_paramgen_seed()\fR, +\&\fBEVP_PKEY_CTX_set_group_name()\fR and \fBEVP_PKEY_CTX_get_group_name()\fR +were added in OpenSSL 3.0. +.PP +The \fBEVP_PKEY_CTX_set1_id()\fR, \fBEVP_PKEY_CTX_get1_id()\fR and +\&\fBEVP_PKEY_CTX_get1_id_len()\fR macros were added in 1.1.1, other functions were +added in OpenSSL 1.0.0. +.PP +In OpenSSL 1.1.1 and below the functions were mostly macros. +From OpenSSL 3.0 they are all functions. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR, \fBEVP_PKEY_CTX_get0_dh_kdf_ukm()\fR, +and \fBEVP_PKEY_CTX_get0_ecdh_kdf_ukm()\fR were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_get0_libctx.3 b/static/netbsd/man3/EVP_PKEY_CTX_get0_libctx.3 new file mode 100644 index 00000000..524c5d41 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_get0_libctx.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_PKEY_CTX_get0_libctx.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_get0_libctx 3" +.TH EVP_PKEY_CTX_get0_libctx 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_get0_libctx, +EVP_PKEY_CTX_get0_propq, +EVP_PKEY_CTX_get0_provider +\&\- functions for getting diverse information from an EVP_PKEY_CTX +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_LIB_CTX *EVP_PKEY_CTX_get0_libctx(EVP_PKEY_CTX *ctx); +\& const char *EVP_PKEY_CTX_get0_propq(const EVP_PKEY_CTX *ctx); +\& const OSSL_PROVIDER *EVP_PKEY_CTX_get0_provider(const EVP_PKEY_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_CTX_get0_libctx()\fR and \fBEVP_PKEY_CTX_get0_propq()\fR obtain the +OSSL_LIB_CTX and property query string values respectively that were +associated with the EVP_PKEY_CTX when it was constructed. +.PP +\&\fBEVP_PKEY_CTX_get0_provider()\fR returns the provider associated with the +ongoing \fBEVP_PKEY_CTX\fR operation. If the operation is performed by +en \fBENGINE\fR, this function returns NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_CTX_get0_libctx()\fR and \fBEVP_PKEY_CTX_get0_propq()\fR functions return the +OSSL_LIB_CTX and property query string associated with the EVP_PKEY_CTX or NULL +if they are not set. The returned values should not be freed by the caller. +.PP +\&\fBEVP_PKEY_CTX_get0_provider()\fR returns a provider if an operation performed by +a provider is ongoing, otherwise NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_get0_pkey.3 b/static/netbsd/man3/EVP_PKEY_CTX_get0_pkey.3 new file mode 100644 index 00000000..9c5856d8 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_get0_pkey.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: EVP_PKEY_CTX_get0_pkey.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_get0_pkey 3" +.TH EVP_PKEY_CTX_get0_pkey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_get0_pkey, +EVP_PKEY_CTX_get0_peerkey +\&\- functions for accessing the EVP_PKEY associated with an EVP_PKEY_CTX +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx); +\& EVP_PKEY *EVP_PKEY_CTX_get0_peerkey(EVP_PKEY_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_CTX_get0_pkey()\fR is used to access the \fBEVP_PKEY\fR +associated with the given \fBEVP_PKEY_CTX\fR \fIctx\fR. +The \fBEVP_PKEY\fR obtained is the one used for creating the \fBEVP_PKEY_CTX\fR +using either \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +.PP +\&\fBEVP_PKEY_CTX_get0_peerkey()\fR is used to access the peer \fBEVP_PKEY\fR +associated with the given \fBEVP_PKEY_CTX\fR \fIctx\fR. +The peer \fBEVP_PKEY\fR obtained is the one set using +either \fBEVP_PKEY_derive_set_peer\fR\|(3) or \fBEVP_PKEY_derive_set_peer_ex\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_CTX_get0_pkey()\fR returns the \fBEVP_PKEY\fR associated with the +EVP_PKEY_CTX or NULL if it is not set. +.PP +\&\fBEVP_PKEY_CTX_get0_peerkey()\fR returns the peer \fBEVP_PKEY\fR associated with the +EVP_PKEY_CTX or NULL if it is not set. +.PP +The returned EVP_PKEY objects are owned by the EVP_PKEY_CTX, +and therefore should not explicitly be freed by the caller. +.PP +These functions do not affect the EVP_PKEY reference count. +They merely act as getter functions, and should be treated as such. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3), +\&\fBEVP_PKEY_derive_set_peer\fR\|(3), \fBEVP_PKEY_derive_set_peer_ex\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). +You may not use this file except in compliance with the License. +You can obtain a copy in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_get_algor.3 b/static/netbsd/man3/EVP_PKEY_CTX_get_algor.3 new file mode 100644 index 00000000..b8b2bd6a --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_get_algor.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: EVP_PKEY_CTX_get_algor.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_get_algor 3" +.TH EVP_PKEY_CTX_get_algor 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_CIPHER_CTX_get_algor, +EVP_CIPHER_CTX_get_algor_params, +EVP_CIPHER_CTX_set_algor_params, +EVP_PKEY_CTX_get_algor, +EVP_PKEY_CTX_get_algor_params, +EVP_PKEY_CTX_set_algor_params +\&\- pass AlgorithmIdentifier and its params to/from algorithm implementations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& int EVP_TYPE_CTX_get_algor(EVP_TYPE_CTX *ctx, X509_ALGOR **alg); +\& int EVP_TYPE_CTX_get_algor_params(EVP_TYPE_CTX *ctx, X509_ALGOR *alg); +\& int EVP_TYPE_CTX_set_algor_params(EVP_TYPE_CTX *ctx, const X509_ALGOR *alg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In the description here and the "SYNOPSIS" above, \fR\f(BITYPE\fR\fB\fR is used as a +placeholder for any EVP operation type. +.PP +\&\fBEVP_\fR\f(BITYPE\fR\fB_CTX_get_algor\fR() attempts to retrieve a complete +AlgorithmIdentifier from the \fBEVP_\fR\f(BITYPE\fR implementation, and populates +\&\fI*alg\fR with it. +If \fIalg\fR is NULL, calling this function will serve to see if calling this +function is supported at all by the \fBEVP_\fR\f(BITYPE\fR\fB\fR implementation. +If \fI*alg\fR is NULL, space will be allocated automatically, and assigned to +\&\fI*alg\fR. +.PP +\&\fBEVP_\fR\f(BITYPE\fR\fB_CTX_get_algor_params\fR() attempts to retrieve the \fIparameters\fR +part of an AlgorithmIdentifier from the \fBEVP_\fR\f(BITYPE\fR implementation, and +populates \fIalg\-\fRparameters> with it. +If \fIalg\fR is NULL, calling this function will serve to see if calling this +function is supported at all by the \fBEVP_\fR\f(BITYPE\fR\fB\fR implementation. +If \fIalg\->parameters\fR is NULL, space will be allocated automatically, and +assigned to \fIalg\->parameters\fR. +If \fIalg\->parameters\fR is not NULL, its previous contents will be overwritten +with the retrieved AlgorithmIdentifier parameters. Beware! +.PP +\&\fBEVP_\fR\f(BITYPE\fR\fB_CTX_set_algor_params\fR() attempts to pass \fIalg\->parameters\fR +to the \fBEVP_\fR\f(BITYPE\fR implementation. +If \fIalg\fR is NULL, calling this function will serve to see if calling this +function is supported at all by the \fBEVP_\fR\f(BITYPE\fR\fB\fR implementation. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 for success, and 0 or a negative number if an error +occurs. In particular, \-2 is returned when the function isn\*(Aqt supported by +the \fBEVP_\fR\f(BITYPE\fR implementation. +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_new.3 b/static/netbsd/man3/EVP_PKEY_CTX_new.3 new file mode 100644 index 00000000..22c80498 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_new.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: EVP_PKEY_CTX_new.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_new 3" +.TH EVP_PKEY_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_from_name, +EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free, +EVP_PKEY_CTX_is_a +\&\- public key algorithm context functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); +\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); +\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OSSL_LIB_CTX *libctx, +\& const char *name, +\& const char *propquery); +\& EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx, +\& EVP_PKEY *pkey, +\& const char *propquery); +\& EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx); +\& void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_CTX_is_a(EVP_PKEY_CTX *ctx, const char *keytype); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_CTX_new()\fR function allocates public key algorithm context using +the \fIpkey\fR key type and ENGINE \fIe\fR. +.PP +The \fBEVP_PKEY_CTX_new_id()\fR function allocates public key algorithm context +using the key type specified by \fIid\fR and ENGINE \fIe\fR. +.PP +The \fBEVP_PKEY_CTX_new_from_name()\fR function allocates a public key algorithm +context using the library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)), the +key type specified by \fIname\fR and the property query \fIpropquery\fR. None +of the arguments are duplicated, so they must remain unchanged for the +lifetime of the returned \fBEVP_PKEY_CTX\fR or of any of its duplicates. Read +further about the possible names in "NOTES" below. +.PP +The \fBEVP_PKEY_CTX_new_from_pkey()\fR function allocates a public key algorithm +context using the library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) and the +algorithm specified by \fIpkey\fR and the property query \fIpropquery\fR. None of the +arguments are duplicated, so they must remain unchanged for the lifetime of the +returned \fBEVP_PKEY_CTX\fR or any of its duplicates. +.PP +\&\fBEVP_PKEY_CTX_new_id()\fR and \fBEVP_PKEY_CTX_new_from_name()\fR are normally +used when no \fBEVP_PKEY\fR structure is associated with the operations, +for example during parameter generation or key generation for some +algorithms. +.PP +\&\fBEVP_PKEY_CTX_dup()\fR duplicates the context \fIctx\fR. +It is not supported for a keygen operation. +It is however possible to duplicate a context freshly created via any of the +above \f(CW\*(C`new\*(C'\fR functions, provided \fBEVP_PKEY_keygen_init\fR\|(3) has not yet been +called on the source context, and then use the copy for key generation. +.PP +\&\fBEVP_PKEY_CTX_free()\fR frees up the context \fIctx\fR. +If \fIctx\fR is NULL, nothing is done. +.PP +\&\fBEVP_PKEY_is_a()\fR checks if the key type associated with \fIctx\fR is \fIkeytype\fR. +.SH NOTES +.IX Header "NOTES" +.SS "On \fBEVP_PKEY_CTX\fP" +.IX Subsection "On EVP_PKEY_CTX" +The \fBEVP_PKEY_CTX\fR structure is an opaque public key algorithm context used +by the OpenSSL high\-level public key API. Contexts \fBMUST NOT\fR be shared between +threads: that is it is not permissible to use the same context simultaneously +in two threads. +.SS "On Key Types" +.IX Subsection "On Key Types" +We mention "key type" in this manual, which is the same +as "algorithm" in most cases, allowing either term to be used +interchangeably. There are algorithms where the \fIkey type\fR and the +\&\fIalgorithm\fR of the operations that use the keys are not the same, +such as EC keys being used for ECDSA and ECDH operations. +.PP +Key types are given in two different manners: +.IP "Legacy NID or EVP_PKEY type" 4 +.IX Item "Legacy NID or EVP_PKEY type" +This is the \fIid\fR used with \fBEVP_PKEY_CTX_new_id()\fR. +.Sp +These are \fBEVP_PKEY_RSA\fR, \fBEVP_PKEY_RSA_PSS\fR, \fBEVP_PKEY_DSA\fR, +\&\fBEVP_PKEY_DH\fR, \fBEVP_PKEY_EC\fR, \fBEVP_PKEY_SM2\fR, \fBEVP_PKEY_X25519\fR, +\&\fBEVP_PKEY_X448\fR, and are used by legacy methods. +.IP "Name strings" 4 +.IX Item "Name strings" +This is the \fIname\fR used with \fBEVP_PKEY_CTX_new_from_name()\fR. +.Sp +These are names like "RSA", "DSA", and what\*(Aqs available depends on what +providers are currently accessible. +.Sp +The OpenSSL providers offer a set of key types available this way, please +see \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBOSSL_PROVIDER\-default\fR\|(7) and related +documentation for more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_CTX_new()\fR, \fBEVP_PKEY_CTX_new_id()\fR and \fBEVP_PKEY_CTX_dup()\fR return either +the newly allocated \fBEVP_PKEY_CTX\fR structure or \fBNULL\fR if an error occurred. +.PP +\&\fBEVP_PKEY_CTX_free()\fR does not return a value. +.PP +\&\fBEVP_PKEY_CTX_is_a()\fR returns 1 for true and 0 for false. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_CTX_new()\fR, \fBEVP_PKEY_CTX_new_id()\fR, \fBEVP_PKEY_CTX_dup()\fR and +\&\fBEVP_PKEY_CTX_free()\fR functions were added in OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_CTX_new_from_name()\fR and \fBEVP_PKEY_CTX_new_from_pkey()\fR functions were +added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set1_pbe_pass.3 b/static/netbsd/man3/EVP_PKEY_CTX_set1_pbe_pass.3 new file mode 100644 index 00000000..e253f715 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set1_pbe_pass.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_PKEY_CTX_set1_pbe_pass.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set1_pbe_pass 3" +.TH EVP_PKEY_CTX_set1_pbe_pass 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set1_pbe_pass +\&\- generic KDF support functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass, +\& int passlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are generic support functions for all KDF algorithms. +.PP +\&\fBEVP_PKEY_CTX_set1_pbe_pass()\fR sets the password to the \fBpasslen\fR first +bytes from \fBpass\fR. +.SH "STRING CTRLS" +.IX Header "STRING CTRLS" +There is also support for string based control operations via +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3). +The \fBpassword\fR can be directly specified using the \fBtype\fR parameter +"pass" or given in hex encoding using the "hexpass" parameter. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PKEY_CTX_set1_pbe_pass()\fR was converted from a macro to a function in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 b/static/netbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 new file mode 100644 index 00000000..87d1f8da --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set_hkdf_md.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: EVP_PKEY_CTX_set_hkdf_md.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set_hkdf_md 3" +.TH EVP_PKEY_CTX_set_hkdf_md 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, +EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info, +EVP_PKEY_CTX_set_hkdf_mode \- +HMAC\-based Extract\-and\-Expand key derivation algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set_hkdf_mode(EVP_PKEY_CTX *pctx, int mode); +\& +\& int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); +\& +\& int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, +\& int saltlen); +\& +\& int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key, +\& int keylen); +\& +\& int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info, +\& int infolen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. +HKDF follows the "extract\-then\-expand" paradigm, where the KDF logically +consists of two modules. The first stage takes the input keying material +and "extracts" from it a fixed\-length pseudorandom key K. The second stage +"expands" the key K into several additional pseudorandom keys (the output +of the KDF). +.PP +\&\fBEVP_PKEY_CTX_set_hkdf_mode()\fR sets the mode for the HKDF operation. There +are three modes that are currently defined: +.IP EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND 4 +.IX Item "EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND" +This is the default mode. Calling \fBEVP_PKEY_derive\fR\|(3) on an EVP_PKEY_CTX set +up for HKDF will perform an extract followed by an expand operation in one go. +The derived key returned will be the result after the expand operation. The +intermediate fixed\-length pseudorandom key K is not returned. +.Sp +In this mode the digest, key, salt and info values must be set before a key is +derived or an error occurs. +.IP EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY 4 +.IX Item "EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY" +In this mode calling \fBEVP_PKEY_derive\fR\|(3) will just perform the extract +operation. The value returned will be the intermediate fixed\-length pseudorandom +key K. +.Sp +The digest, key and salt values must be set before a key is derived or an +error occurs. +.IP EVP_PKEY_HKDEF_MODE_EXPAND_ONLY 4 +.IX Item "EVP_PKEY_HKDEF_MODE_EXPAND_ONLY" +In this mode calling \fBEVP_PKEY_derive\fR\|(3) will just perform the expand +operation. The input key should be set to the intermediate fixed\-length +pseudorandom key K returned from a previous extract operation. +.Sp +The digest, key and info values must be set before a key is derived or an +error occurs. +.PP +\&\fBEVP_PKEY_CTX_set_hkdf_md()\fR sets the message digest associated with the HKDF. +.PP +\&\fBEVP_PKEY_CTX_set1_hkdf_salt()\fR sets the salt to \fBsaltlen\fR bytes of the +buffer \fBsalt\fR. Any existing value is replaced. +.PP +\&\fBEVP_PKEY_CTX_set1_hkdf_key()\fR sets the key to \fBkeylen\fR bytes of the buffer +\&\fBkey\fR. Any existing value is replaced. +.PP +\&\fBEVP_PKEY_CTX_add1_hkdf_info()\fR sets the info value to \fBinfolen\fR bytes of the +buffer \fBinfo\fR. If a value is already set, it is appended to the existing +value. +.SH "STRING CTRLS" +.IX Header "STRING CTRLS" +HKDF also supports string based control operations via +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3). +The \fBtype\fR parameter "md" uses the supplied \fBvalue\fR as the name of the digest +algorithm to use. +The \fBtype\fR parameter "mode" uses the values "EXTRACT_AND_EXPAND", +"EXTRACT_ONLY" and "EXPAND_ONLY" to determine the mode to use. +The \fBtype\fR parameters "salt", "key" and "info" use the supplied \fBvalue\fR +parameter as a \fBseed\fR, \fBkey\fR or \fBinfo\fR value. +The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex +string which is converted to binary. +.SH NOTES +.IX Header "NOTES" +A context for HKDF can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); +.Ve +.PP +The total length of the info buffer cannot exceed 2048 bytes in length: this +should be more than enough for any normal use of HKDF. +.PP +The output length of an HKDF expand operation is specified via the length +parameter to the \fBEVP_PKEY_derive\fR\|(3) function. +Since the HKDF output length is variable, passing a \fBNULL\fR buffer as a means +to obtain the requisite length is not meaningful with HKDF in any mode that +performs an expand operation. Instead, the caller must allocate a buffer of the +desired length, and pass that buffer to \fBEVP_PKEY_derive\fR\|(3) along with (a +pointer initialized to) the desired length. Passing a \fBNULL\fR buffer to obtain +the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY. +.PP +Optimised versions of HKDF can be implemented in an ENGINE. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using SHA\-256 with the secret key "secret", +salt value "salt" and info value "label": +.PP +.Vb 4 +\& EVP_PKEY_CTX *pctx; +\& unsigned char out[10]; +\& size_t outlen = sizeof(out); +\& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); +\& +\& if (EVP_PKEY_derive_init(pctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, "salt", 4) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set1_hkdf_key(pctx, "secret", 6) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 5) <= 0) +\& /* Error */ +\& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) +\& /* Error */ +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 5869 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of the functions described here were converted from macros to functions in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set_params.3 b/static/netbsd/man3/EVP_PKEY_CTX_set_params.3 new file mode 100644 index 00000000..effc1354 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set_params.3 @@ -0,0 +1,157 @@ +.\" $NetBSD: EVP_PKEY_CTX_set_params.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set_params 3" +.TH EVP_PKEY_CTX_set_params 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set_params, +EVP_PKEY_CTX_settable_params, +EVP_PKEY_CTX_get_params, +EVP_PKEY_CTX_gettable_params +\&\- provider parameter passing operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, const OSSL_PARAM *params); +\& const OSSL_PARAM *EVP_PKEY_CTX_settable_params(const EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); +\& const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(const EVP_PKEY_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_CTX_get_params()\fR and \fBEVP_PKEY_CTX_set_params()\fR functions allow +transfer of arbitrary key parameters to and from providers. +Not all parameters may be supported by all providers. +See \fBOSSL_PROVIDER\fR\|(3) for more information on providers. +The \fIparams\fR field is a pointer to a list of \fBOSSL_PARAM\fR structures, +terminated with a \fBOSSL_PARAM_END\fR\|(3) struct. +See \fBOSSL_PARAM\fR\|(3) for information about passing parameters. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation. +These methods replace the \fBEVP_PKEY_CTX_ctrl()\fR mechanism. (EVP_PKEY_CTX_ctrl now +calls these methods internally to interact with providers). +.PP +\&\fBEVP_PKEY_CTX_gettable_params()\fR and \fBEVP_PKEY_CTX_settable_params()\fR get a +constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and +settable parameters for the current algorithm implementation, i.e. parameters +that can be used with \fBEVP_PKEY_CTX_get_params()\fR and \fBEVP_PKEY_CTX_set_params()\fR +respectively. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation. +.SS Parameters +.IX Subsection "Parameters" +Examples of EVP_PKEY parameters include the following: +.PP +"Common parameters" in \fBprovider\-keymgmt\fR\|(7) +"Key Exchange parameters" in \fBprovider\-keyexch\fR\|(7) +"Signature parameters" in \fBprovider\-signature\fR\|(7) +.PP +"Common RSA parameters" in \fBEVP_PKEY\-RSA\fR\|(7) +"RSA key generation parameters" in \fBEVP_PKEY\-RSA\fR\|(7) +"FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7) +"FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7) +"DSA parameters" in \fBEVP_PKEY\-DSA\fR\|(7) +"DSA key generation parameters" in \fBEVP_PKEY\-DSA\fR\|(7) +"DH parameters" in \fBEVP_PKEY\-DH\fR\|(7) +"DH key generation parameters" in \fBEVP_PKEY\-DH\fR\|(7) +"Common EC parameters" in \fBEVP_PKEY\-EC\fR\|(7) +"Common X25519, X448, ED25519 and ED448 parameters" in \fBEVP_PKEY\-X25519\fR\|(7) +"Common parameters" in \fBEVP_PKEY\-ML\-DSA\fR\|(7) +"Common parameters" in \fBEVP_PKEY\-ML\-KEM\fR\|(7) +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_CTX_set_params()\fR returns 1 for success or 0 otherwise. +\&\fBEVP_PKEY_CTX_settable_params()\fR returns an OSSL_PARAM array on success or NULL on +error. +It may also return NULL if there are no settable parameters available. +.PP +All other functions and macros described on this page return a positive value +for success and 0 or a negative value for failure. In particular a return value +of \-2 indicates the operation is not supported by the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All functions were added in OpenSSL 3.0. +.PP +Support for \fBML\-DSA\fR> and \fBML\-KEM\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.3 b/static/netbsd/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.3 new file mode 100644 index 00000000..234593d2 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: EVP_PKEY_CTX_set_rsa_pss_keygen_md.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set_rsa_pss_keygen_md 3" +.TH EVP_PKEY_CTX_set_rsa_pss_keygen_md 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set_rsa_pss_keygen_md, +EVP_PKEY_CTX_set_rsa_pss_keygen_md_name, +EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md, +EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name, +EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen +\&\- EVP_PKEY RSA\-PSS algorithm support functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx, +\& const EVP_MD *md); +\& int EVP_PKEY_CTX_set_rsa_pss_keygen_md_name(EVP_PKEY_CTX *ctx, +\& const char *mdname, +\& const char *mdprops); +\& int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx, +\& const EVP_MD *md); +\& int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name(EVP_PKEY_CTX *pctx, +\& const char *mdname); +\& int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx, +\& int saltlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These are the functions that implement \fBRSA\-PSS\fR\|(7). +.SS "Signing and Verification" +.IX Subsection "Signing and Verification" +The macro \fBEVP_PKEY_CTX_set_rsa_padding()\fR is supported but an error is +returned if an attempt is made to set the padding mode to anything other +than \fBPSS\fR. It is otherwise similar to the \fBRSA\fR version. +.PP +The \fBEVP_PKEY_CTX_set_rsa_pss_saltlen()\fR macro is used to set the salt length. +If the key has usage restrictions then an error is returned if an attempt is +made to set the salt length below the minimum value. It is otherwise similar +to the \fBRSA\fR operation except detection of the salt length (using +RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has +usage restrictions. +.PP +The \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and \fBEVP_PKEY_CTX_set_rsa_mgf1_md\fR\|(3) +functions are used to set the digest and MGF1 algorithms respectively. If the +key has usage restrictions then an error is returned if an attempt is made to +set the digest to anything other than the restricted value. Otherwise these are +similar to the \fBRSA\fR versions. +.SS "Key Generation" +.IX Subsection "Key Generation" +As with RSA key generation the \fBEVP_PKEY_CTX_set_rsa_keygen_bits()\fR +and \fBEVP_PKEY_CTX_set_rsa_keygen_pubexp()\fR macros are supported for RSA\-PSS: +they have exactly the same meaning as for the RSA algorithm. +.PP +Optional parameter restrictions can be specified when generating a PSS key. +If any restrictions are set (using the macros described below) then \fBall\fR +parameters are restricted. For example, setting a minimum salt length also +restricts the digest and MGF1 algorithms. If any restrictions are in place +then they are reflected in the corresponding parameters of the public key +when (for example) a certificate request is signed. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_md()\fR restricts the digest algorithm the +generated key can use to \fImd\fR. +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_md_name()\fR does the same thing, but +passes the algorithm by name rather than by \fBEVP_MD\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md()\fR restricts the MGF1 algorithm the +generated key can use to \fImd\fR. +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md_name()\fR does the same thing, but +passes the algorithm by name rather than by \fBEVP_MD\fR. +.PP +\&\fBEVP_PKEY_CTX_set_rsa_pss_keygen_saltlen()\fR restricts the minimum salt length +to \fIsaltlen\fR. +.SH NOTES +.IX Header "NOTES" +A context for the \fBRSA\-PSS\fR algorithm can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL); +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRSA\-PSS\fR\|(7), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set_scrypt_N.3 b/static/netbsd/man3/EVP_PKEY_CTX_set_scrypt_N.3 new file mode 100644 index 00000000..0c406e6c --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set_scrypt_N.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: EVP_PKEY_CTX_set_scrypt_N.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set_scrypt_N 3" +.TH EVP_PKEY_CTX_set_scrypt_N 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set1_scrypt_salt, +EVP_PKEY_CTX_set_scrypt_N, +EVP_PKEY_CTX_set_scrypt_r, +EVP_PKEY_CTX_set_scrypt_p, +EVP_PKEY_CTX_set_scrypt_maxmem_bytes +\&\- EVP_PKEY scrypt KDF support functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, +\& int saltlen); +\& +\& int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N); +\& +\& int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r); +\& +\& int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p); +\& +\& int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, +\& uint64_t maxmem); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are used to set up the necessary data to use the +scrypt KDF. +For more information on scrypt, see \fBEVP_KDF\-SCRYPT\fR\|(7). +.PP +\&\fBEVP_PKEY_CTX_set1_scrypt_salt()\fR sets the \fBsaltlen\fR bytes long salt +value. +.PP +\&\fBEVP_PKEY_CTX_set_scrypt_N()\fR, \fBEVP_PKEY_CTX_set_scrypt_r()\fR and +\&\fBEVP_PKEY_CTX_set_scrypt_p()\fR configure the work factors N, r and p. +.PP +\&\fBEVP_PKEY_CTX_set_scrypt_maxmem_bytes()\fR sets how much RAM key +derivation may maximally use, given in bytes. +If RAM is exceeded because the load factors are chosen too high, the +key derivation will fail. +.SH "STRING CTRLS" +.IX Header "STRING CTRLS" +scrypt also supports string based control operations via +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3). +Similarly, the \fBsalt\fR can either be specified using the \fBtype\fR +parameter "salt" or in hex encoding by using the "hexsalt" parameter. +The work factors \fBN\fR, \fBr\fR and \fBp\fR as well as \fBmaxmem_bytes\fR can be +set by using the parameters "N", "r", "p" and "maxmem_bytes", +respectively. +.SH NOTES +.IX Header "NOTES" +There is a newer generic API for KDFs, \fBEVP_KDF\fR\|(3), which is +preferred over the EVP_PKEY method. +.PP +The scrypt KDF also uses \fBEVP_PKEY_CTX_set1_pbe_pass()\fR as well as +the value from the string controls "pass" and "hexpass". +See \fBEVP_PKEY_CTX_set1_pbe_pass\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 or a negative value for +failure. +In particular a return value of \-2 indicates the operation is not +supported by the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3) +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of the functions described here were converted from macros to functions in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 b/static/netbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 new file mode 100644 index 00000000..1f49341e --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_CTX_set_tls1_prf_md.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: EVP_PKEY_CTX_set_tls1_prf_md.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_CTX_set_tls1_prf_md 3" +.TH EVP_PKEY_CTX_set_tls1_prf_md 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_CTX_set_tls1_prf_md, +EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed \- +TLS PRF key derivation algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); +\& int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx, +\& unsigned char *sec, int seclen); +\& int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, +\& unsigned char *seed, int seedlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_TLS1_PRF\fR algorithm implements the PRF key derivation function for +TLS. It has no associated private key and only implements key derivation +using \fBEVP_PKEY_derive\fR\|(3). +.PP +\&\fBEVP_PKEY_set_tls1_prf_md()\fR sets the message digest associated with the +TLS PRF. \fBEVP_md5_sha1()\fR is treated as a special case which uses the PRF +algorithm using both \fBMD5\fR and \fBSHA1\fR as used in TLS 1.0 and 1.1. +.PP +\&\fBEVP_PKEY_CTX_set_tls1_prf_secret()\fR sets the secret value of the TLS PRF +to \fBseclen\fR bytes of the buffer \fBsec\fR. Any existing secret value is replaced +and any seed is reset. +.PP +\&\fBEVP_PKEY_CTX_add1_tls1_prf_seed()\fR sets the seed to \fBseedlen\fR bytes of \fBseed\fR. +If a seed is already set it is appended to the existing value. +.SH "STRING CTRLS" +.IX Header "STRING CTRLS" +The TLS PRF also supports string based control operations using +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3). +The \fBtype\fR parameter "md" uses the supplied \fBvalue\fR as the name of the digest +algorithm to use. +The \fBtype\fR parameters "secret" and "seed" use the supplied \fBvalue\fR parameter +as a secret or seed value. +The names "hexsecret" and "hexseed" are similar except they take a hex string +which is converted to binary. +.SH NOTES +.IX Header "NOTES" +A context for the TLS PRF can be obtained by calling: +.PP +.Vb 1 +\& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); +.Ve +.PP +The digest, secret value and seed must be set before a key is derived or an +error occurs. +.PP +The total length of all seeds cannot exceed 1024 bytes in length: this should +be more than enough for any normal use of the TLS PRF. +.PP +The output length of the PRF is specified by the length parameter in the +\&\fBEVP_PKEY_derive()\fR function. Since the output length is variable, setting +the buffer to \fBNULL\fR is not meaningful for the TLS PRF. +.PP +Optimised versions of the TLS PRF can be implemented in an ENGINE. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives 10 bytes using SHA\-256 with the secret key "secret" +and seed value "seed": +.PP +.Vb 3 +\& EVP_PKEY_CTX *pctx; +\& unsigned char out[10]; +\& size_t outlen = sizeof(out); +\& +\& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); +\& if (EVP_PKEY_derive_init(pctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0) +\& /* Error */ +\& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) +\& /* Error */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of the functions described here were converted from macros to functions in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_asn1_get_count.3 b/static/netbsd/man3/EVP_PKEY_asn1_get_count.3 new file mode 100644 index 00000000..de4cc3a6 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_asn1_get_count.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: EVP_PKEY_asn1_get_count.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_asn1_get_count 3" +.TH EVP_PKEY_asn1_get_count 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_asn1_find, +EVP_PKEY_asn1_find_str, +EVP_PKEY_asn1_get_count, +EVP_PKEY_asn1_get0, +EVP_PKEY_asn1_get0_info +\&\- enumerate public key ASN.1 methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_asn1_get_count(void); +\& const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_get0(int idx); +\& const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pe, int type); +\& const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str(ENGINE **pe, +\& const char *str, int len); +\& int EVP_PKEY_asn1_get0_info(int *ppkey_id, int *pkey_base_id, +\& int *ppkey_flags, const char **pinfo, +\& const char **ppem_str, +\& const EVP_PKEY_ASN1_METHOD *ameth); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_asn1_count()\fR returns a count of the number of public key +ASN.1 methods available: it includes standard methods and any methods +added by the application. +.PP +\&\fBEVP_PKEY_asn1_get0()\fR returns the public key ASN.1 method \fBidx\fR. +The value of \fBidx\fR must be between zero and \fBEVP_PKEY_asn1_get_count()\fR +\&\- 1. +.PP +\&\fBEVP_PKEY_asn1_find()\fR looks up the \fBEVP_PKEY_ASN1_METHOD\fR with NID +\&\fBtype\fR. +If \fBpe\fR isn\*(Aqt \fBNULL\fR, then it will look up an engine implementing a +\&\fBEVP_PKEY_ASN1_METHOD\fR for the NID \fBtype\fR and return that instead, +and also set \fB*pe\fR to point at the engine that implements it. +.PP +\&\fBEVP_PKEY_asn1_find_str()\fR looks up the \fBEVP_PKEY_ASN1_METHOD\fR with PEM +type string \fBstr\fR. +Just like \fBEVP_PKEY_asn1_find()\fR, if \fBpe\fR isn\*(Aqt \fBNULL\fR, then it will +look up an engine implementing a \fBEVP_PKEY_ASN1_METHOD\fR for the NID +\&\fBtype\fR and return that instead, and also set \fB*pe\fR to point at the +engine that implements it. +.PP +\&\fBEVP_PKEY_asn1_get0_info()\fR returns the public key ID, base public key +ID (both NIDs), any flags, the method description and PEM type string +associated with the public key ASN.1 method \fB*ameth\fR. +.PP +\&\fBEVP_PKEY_asn1_count()\fR, \fBEVP_PKEY_asn1_get0()\fR, \fBEVP_PKEY_asn1_find()\fR and +\&\fBEVP_PKEY_asn1_find_str()\fR are not thread safe, but as long as all +\&\fBEVP_PKEY_ASN1_METHOD\fR objects are added before the application gets +threaded, using them is safe. See \fBEVP_PKEY_asn1_add0\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_asn1_count()\fR returns the number of available public key methods. +.PP +\&\fBEVP_PKEY_asn1_get0()\fR return a public key method or \fBNULL\fR if \fBidx\fR is +out of range. +.PP +\&\fBEVP_PKEY_asn1_get0_info()\fR returns 0 on failure, 1 on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_asn1_new\fR\|(3), \fBEVP_PKEY_asn1_add0\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_check.3 b/static/netbsd/man3/EVP_PKEY_check.3 new file mode 100644 index 00000000..c29fa45e --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_check.3 @@ -0,0 +1,158 @@ +.\" $NetBSD: EVP_PKEY_check.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_check 3" +.TH EVP_PKEY_check 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_check, EVP_PKEY_param_check, EVP_PKEY_param_check_quick, +EVP_PKEY_public_check, EVP_PKEY_public_check_quick, EVP_PKEY_private_check, +EVP_PKEY_pairwise_check +\&\- key and parameter validation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_check(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_param_check(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_param_check_quick(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_public_check(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_public_check_quick(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_private_check(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_pairwise_check(EVP_PKEY_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_param_check()\fR validates the parameters component of the key +given by \fBctx\fR. This check will always succeed for key types that do not have +parameters. +.PP +\&\fBEVP_PKEY_param_check_quick()\fR validates the parameters component of the key +given by \fBctx\fR like \fBEVP_PKEY_param_check()\fR does. However some algorithm +implementations may offer a quicker form of validation that omits some checks in +order to perform a lightweight sanity check of the key. If a quicker form is not +provided then this function call does the same thing as \fBEVP_PKEY_param_check()\fR. +.PP +\&\fBEVP_PKEY_public_check()\fR validates the public component of the key given by \fBctx\fR. +.PP +\&\fBEVP_PKEY_public_check_quick()\fR validates the public component of the key +given by \fBctx\fR like \fBEVP_PKEY_public_check()\fR does. However some algorithm +implementations may offer a quicker form of validation that omits some checks in +order to perform a lightweight sanity check of the key. If a quicker form is not +provided then this function call does the same thing as \fBEVP_PKEY_public_check()\fR. +.PP +\&\fBEVP_PKEY_private_check()\fR validates the private component of the key given by \fBctx\fR. +.PP +\&\fBEVP_PKEY_pairwise_check()\fR validates that the public and private components have +the correct mathematical relationship to each other for the key given by \fBctx\fR. +.PP +\&\fBEVP_PKEY_check()\fR is an alias for the \fBEVP_PKEY_pairwise_check()\fR function. +.SH NOTES +.IX Header "NOTES" +Key validation used by the OpenSSL FIPS provider complies with the rules +within SP800\-56A and SP800\-56B. For backwards compatibility reasons the OpenSSL +default provider may use checks that are not as restrictive for certain key types. +For further information see "DSA key validation" in \fBEVP_PKEY\-DSA\fR\|(7), +"DH key validation" in \fBEVP_PKEY\-DH\fR\|(7), "EC key validation" in \fBEVP_PKEY\-EC\fR\|(7) and +"RSA key validation" in \fBEVP_PKEY\-RSA\fR\|(7). +.PP +Refer to SP800\-56A and SP800\-56B for rules relating to when these functions +should be called during key establishment. +It is not necessary to call these functions after locally calling an approved key +generation method, but may be required for assurance purposes when receiving +keys from a third party. +.PP +The \fBEVP_PKEY_pairwise_check()\fR and \fBEVP_PKEY_private_check()\fR might not be bounded +by any key size limits as private keys are not expected to be supplied by +attackers. For that reason they might take an unbounded time if run on +arbitrarily large keys. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 for success or others for failure. +They return \-2 if the operation is not supported for the specific algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_fromdata\fR\|(3), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-FFC\fR\|(7), +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-EC\fR\|(7), +\&\fBEVP_PKEY\-RSA\fR\|(7), +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PKEY_check()\fR, \fBEVP_PKEY_public_check()\fR and \fBEVP_PKEY_param_check()\fR were added +in OpenSSL 1.1.1. +.PP +\&\fBEVP_PKEY_param_check_quick()\fR, \fBEVP_PKEY_public_check_quick()\fR, +\&\fBEVP_PKEY_private_check()\fR and \fBEVP_PKEY_pairwise_check()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_cmp.3 b/static/netbsd/man3/EVP_PKEY_cmp.3 new file mode 100644 index 00000000..f71ae745 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_cmp.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: EVP_PKEY_cmp.3,v 1.20 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_cmp 3" +.TH EVP_PKEY_cmp 3 "2018-09-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, +EVP_PKEY_cmp \- public key parameter and comparison functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); +\& int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); +\& +\& int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); +\& int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The function \fBEVP_PKEY_missing_parameters()\fR returns 1 if the public key +parameters of \fBpkey\fR are missing and 0 if they are present or the algorithm +doesn't use parameters. +.PP +The function \fBEVP_PKEY_copy_parameters()\fR copies the parameters from key +\&\fBfrom\fR to key \fBto\fR. An error is returned if the parameters are missing in +\&\fBfrom\fR or present in both \fBfrom\fR and \fBto\fR and mismatch. If the parameters +in \fBfrom\fR and \fBto\fR are both present and match this function has no effect. +.PP +The function \fBEVP_PKEY_cmp_parameters()\fR compares the parameters of keys +\&\fBa\fR and \fBb\fR. +.PP +The function \fBEVP_PKEY_cmp()\fR compares the public key components and parameters +(if present) of keys \fBa\fR and \fBb\fR. +.SH "NOTES" +.IX Header "NOTES" +The main purpose of the functions \fBEVP_PKEY_missing_parameters()\fR and +\&\fBEVP_PKEY_copy_parameters()\fR is to handle public keys in certificates where the +parameters are sometimes omitted from a public key if they are inherited from +the \s-1CA\s0 that signed it. +.PP +Since OpenSSL private keys contain public key components too the function +\&\fBEVP_PKEY_cmp()\fR can also be used to determine if a private key matches +a public key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The function \fBEVP_PKEY_missing_parameters()\fR returns 1 if the public key +parameters of \fBpkey\fR are missing and 0 if they are present or the algorithm +doesn't use parameters. +.PP +These functions \fBEVP_PKEY_copy_parameters()\fR returns 1 for success and 0 for +failure. +.PP +The function \fBEVP_PKEY_cmp_parameters()\fR and \fBEVP_PKEY_cmp()\fR return 1 if the +keys match, 0 if they don't match, \-1 if the key types are different and +\&\-2 if the operation is not supported. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2006\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_copy_parameters.3 b/static/netbsd/man3/EVP_PKEY_copy_parameters.3 new file mode 100644 index 00000000..0e0ba9b6 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_copy_parameters.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: EVP_PKEY_copy_parameters.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_copy_parameters 3" +.TH EVP_PKEY_copy_parameters 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_missing_parameters, EVP_PKEY_copy_parameters, EVP_PKEY_parameters_eq, +EVP_PKEY_cmp_parameters, EVP_PKEY_eq, +EVP_PKEY_cmp \- public key parameter and comparison functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); +\& int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); +\& +\& int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b); +\& int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); +\& int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBEVP_PKEY_missing_parameters()\fR returns 1 if the public key +parameters of \fBpkey\fR are missing and 0 if they are present or the algorithm +doesn\*(Aqt use parameters. +.PP +The function \fBEVP_PKEY_copy_parameters()\fR copies the parameters from key +\&\fBfrom\fR to key \fBto\fR. An error is returned if the parameters are missing in +\&\fBfrom\fR or present in both \fBfrom\fR and \fBto\fR and mismatch. If the parameters +in \fBfrom\fR and \fBto\fR are both present and match this function has no effect. +.PP +The function \fBEVP_PKEY_parameters_eq()\fR checks the parameters of keys +\&\fBa\fR and \fBb\fR for equality. +.PP +The function \fBEVP_PKEY_eq()\fR checks the keys \fBa\fR and \fBb\fR for equality, +including their parameters if they are available. +.SH NOTES +.IX Header "NOTES" +The main purpose of the functions \fBEVP_PKEY_missing_parameters()\fR and +\&\fBEVP_PKEY_copy_parameters()\fR is to handle public keys in certificates where the +parameters are sometimes omitted from a public key if they are inherited from +the CA that signed it. +.PP +The deprecated functions \fBEVP_PKEY_cmp()\fR and \fBEVP_PKEY_cmp_parameters()\fR differ in +their return values compared to other \fB_cmp()\fR functions. They are aliases for +\&\fBEVP_PKEY_eq()\fR and \fBEVP_PKEY_parameters_eq()\fR. +.PP +The function \fBEVP_PKEY_cmp()\fR previously only checked the key parameters +(if there are any) and the public key, assuming that there always was +a public key and that private key equality could be derived from that. +Because it\*(Aqs no longer assumed that the private key in an \fBEVP_PKEY\fR\|(3) is +always accompanied by a public key, the comparison can not rely on public +key comparison alone. +.PP +Instead, \fBEVP_PKEY_eq()\fR (and therefore also \fBEVP_PKEY_cmp()\fR) now compares: +.IP 1. 4 +the key parameters (if there are any) +.IP 2. 4 +the public keys or the private keys of the two \fBEVP_PKEY\fRs, depending on +what they both contain. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The function \fBEVP_PKEY_missing_parameters()\fR returns 1 if the public key +parameters of \fBpkey\fR are missing and 0 if they are present or the algorithm +doesn\*(Aqt use parameters. +.PP +These functions \fBEVP_PKEY_copy_parameters()\fR returns 1 for success and 0 for +failure. +.PP +The functions \fBEVP_PKEY_cmp_parameters()\fR, \fBEVP_PKEY_parameters_eq()\fR, +\&\fBEVP_PKEY_cmp()\fR and \fBEVP_PKEY_eq()\fR return 1 if their +inputs match, 0 if they don\*(Aqt match, \-1 if the key types are different and +\&\-2 if the operation is not supported. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_cmp()\fR and \fBEVP_PKEY_cmp_parameters()\fR functions were deprecated in +OpenSSL 3.0. +.PP +The \fBEVP_PKEY_eq()\fR and \fBEVP_PKEY_parameters_eq()\fR were added in OpenSSL 3.0 to +replace \fBEVP_PKEY_cmp()\fR and \fBEVP_PKEY_cmp_parameters()\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_decapsulate.3 b/static/netbsd/man3/EVP_PKEY_decapsulate.3 new file mode 100644 index 00000000..020fc8b3 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_decapsulate.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: EVP_PKEY_decapsulate.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_decapsulate 3" +.TH EVP_PKEY_decapsulate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_decapsulate_init, EVP_PKEY_auth_decapsulate_init, EVP_PKEY_decapsulate +\&\- Key decapsulation using a KEM algorithm with a private key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_auth_decapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpub, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx, +\& unsigned char *unwrapped, size_t *unwrappedlen, +\& const unsigned char *wrapped, size_t wrappedlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_decapsulate_init()\fR function initializes a private key algorithm +context \fIctx\fR for a decapsulation operation and then sets the \fIparams\fR +on the context in the same way as calling \fBEVP_PKEY_CTX_set_params\fR\|(3). +Note that \fIctx\fR usually is produced using \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3), +specifying the private key to use. +.PP +The \fBEVP_PKEY_auth_decapsulate_init()\fR function is similar to +\&\fBEVP_PKEY_decapsulate_init()\fR but also passes an \fIauthpub\fR authentication public +key that is used during decapsulation. +.PP +The \fBEVP_PKEY_decapsulate()\fR function performs a private key decapsulation +operation using \fIctx\fR. The data to be decapsulated is specified using the +\&\fIwrapped\fR and \fIwrappedlen\fR parameters (which must both non\-NULL). +.PP +The \fIwrapped\fR parameter is an output argument, to which the decapsulated +shared secret is written. +The shared secret may not match the peer\*(Aqs value even when decapsulation +returns success. +Instead, the shared secret must be used to derive a key that is used to +authenticate data subsequently received from the peer. +If \fIunwrapped\fR is NULL then the size of the output shared secret buffer is +written to \fI*unwrappedlen\fR and no decapsulation is performed, this makes it +possible to determine the required buffer size at run time. Otherwise, the +decapsulated secret data is written to \fIunwrapped\fR and the length of shared +secret is written to \fI*unwrappedlen\fR. +.PP +Note that the value pointed to by \fIunwrappedlen\fR (which must NOT be \fBNULL\fR) +must be initialised to the length of \fIunwrapped\fR, so that the call can +validate it is of sufficient size to hold the result of the operation. +.PP +Absent detailed prior knowledge of the internals of the specific KEM +algorithm, callers SHOULD NOT assume that the returned shared secret +is necessarily of the maximum possible length. +The length returned via \fI*unwrappedlen\fR SHOULD be used to determine the actual +length of the output. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_decapsulate_init()\fR algorithm\-specific parameters +for the operation may be set or modified using \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_decapsulate_init()\fR, \fBEVP_PKEY_auth_decapsulate_init()\fR and +\&\fBEVP_PKEY_decapsulate()\fR return 1 for success and 0 or a negative value for +failure. In particular a return value of \-2 indicates the operation is not +supported by the private key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +Decapsulate data using RSA: +.PP +.Vb 1 +\& #include +\& +\& /* +\& * NB: assumes rsa_priv_key is an RSA private key, +\& * and that in, inlen are already set up to contain encapsulated data. +\& */ +\& +\& EVP_PKEY_CTX *ctx = NULL; +\& size_t secretlen = 0; +\& unsigned char *secret = NULL;; +\& +\& ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL); +\& if (ctx == NULL) +\& /* Error */ +\& if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0) +\& /* Error */ +\& +\& /* Set the mode \- only \*(AqRSASVE\*(Aq is currently supported */ +\& if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_decapsulate(ctx, NULL, &secretlen, in, inlen) <= 0) +\& /* Error */ +\& +\& secret = OPENSSL_malloc(secretlen); +\& if (secret == NULL) +\& /* malloc failure */ +\& +\& /* Decapsulated secret data is secretlen bytes long */ +\& if (EVP_PKEY_decapsulate(ctx, secret, &secretlen, in, inlen) <= 0) +\& /* Error */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_KEM\-RSA\fR\|(7), +\&\fBEVP_KEM\-X25519\fR\|(7), +\&\fBEVP_KEM\-EC\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-512\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-768\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-1024\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBEVP_PKEY_decapsulate_init()\fR and \fBEVP_PKEY_decapsulate()\fR were added +in OpenSSL 3.0. +.PP +The function \fBEVP_PKEY_auth_decapsulate_init()\fR was added in OpenSSL 3.2. +.PP +Support for \fBML\-KEM\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_decrypt.3 b/static/netbsd/man3/EVP_PKEY_decrypt.3 new file mode 100644 index 00000000..62d6d35a --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_decrypt.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: EVP_PKEY_decrypt.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_decrypt 3" +.TH EVP_PKEY_decrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_decrypt_init, EVP_PKEY_decrypt_init_ex, +EVP_PKEY_decrypt \- decrypt using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_decrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, +\& unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_decrypt_init()\fR function initializes a public key algorithm +context using key \fIpkey\fR for a decryption operation. +.PP +The \fBEVP_PKEY_decrypt_init_ex()\fR function initializes a public key algorithm +context using key \fIpkey\fR for a decryption operation and sets the +algorithm specific \fIparams\fR. +.PP +The \fBEVP_PKEY_decrypt()\fR function performs a public key decryption operation +using \fIctx\fR. The data to be decrypted is specified using the \fIin\fR and +\&\fIinlen\fR parameters. If \fIout\fR is NULL then the minimum required size of +the output buffer is written to the \fI*outlen\fR parameter. +.PP +If \fIout\fR is not NULL then before the call the \fI*outlen\fR parameter must +contain the length of the \fIout\fR buffer. If the call is successful the +decrypted data is written to \fIout\fR and the amount of the decrypted data +written to \fI*outlen\fR, otherwise an error is returned. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_decrypt_init()\fR algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. These operations can be included in the \fBEVP_PKEY_decrypt_init_ex()\fR +call. +.PP +The function \fBEVP_PKEY_decrypt()\fR can be called more than once on the same +context if several operations are performed using the same parameters. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_decrypt_init()\fR, \fBEVP_PKEY_decrypt_init_ex()\fR and \fBEVP_PKEY_decrypt()\fR +return 1 for success and 0 or a negative value for failure. In particular a +return value of \-2 indicates the operation is not supported by the public key +algorithm. +.SH WARNINGS +.IX Header "WARNINGS" +In OpenSSL versions before 3.2.0, when used in PKCS#1 v1.5 padding, +both the return value from the \fBEVP_PKEY_decrypt()\fR and the \fBoutlen\fR provided +information useful in mounting a Bleichenbacher attack against the +used private key. They had to be processed in a side\-channel free way. +.PP +Since version 3.2.0, the \fBEVP_PKEY_decrypt()\fR method when used with PKCS#1 +v1.5 padding as implemented in the \fBdefault\fR provider implements +the implicit rejection mechanism (see +\&\fBOSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION\fR in \fBprovider\-asym_cipher\fR\|(7)). +That means it doesn\*(Aqt return an error when it detects an error in padding, +instead it returns a pseudo\-randomly generated message, removing the need +of side\-channel secure code from applications using OpenSSL. +If OpenSSL is configured to use a provider that doesn\*(Aqt implement implicit +rejection, the code still needs to handle the returned values +using side\-channel free code. +Side\-channel free handling of the error stack can be performed using +either a pair of unconditional \fBERR_set_mark\fR\|(3) and \fBERR_pop_to_mark\fR\|(3) +calls or by using the \fBERR_clear_error\fR\|(3) call. +.SH EXAMPLES +.IX Header "EXAMPLES" +Decrypt data using OAEP (for RSA keys): +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& ENGINE *eng; +\& unsigned char *out, *in; +\& size_t outlen, inlen; +\& EVP_PKEY *key; +\& +\& /* +\& * NB: assumes key, eng, in, inlen are already set up +\& * and that key is an RSA private key +\& */ +\& ctx = EVP_PKEY_CTX_new(key, eng); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_decrypt_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) +\& /* Error */ +\& +\& out = OPENSSL_malloc(outlen); +\& +\& if (!out) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) +\& /* Error */ +\& +\& /* Decrypted data is outlen bytes written to buffer out */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_derive.3 b/static/netbsd/man3/EVP_PKEY_derive.3 new file mode 100644 index 00000000..0f9d44a6 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_derive.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: EVP_PKEY_derive.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_derive 3" +.TH EVP_PKEY_derive 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, +EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive +\&\- derive public key algorithm shared secret +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer, +\& int validate_peer); +\& int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); +\& int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_derive_init()\fR initializes a public key algorithm context \fIctx\fR for +shared secret derivation using the algorithm given when the context was created +using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to +fetch a \fBEVP_KEYEXCH\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) for +more information about implicit fetches. +.PP +\&\fBEVP_PKEY_derive_init_ex()\fR is the same as \fBEVP_PKEY_derive_init()\fR but additionally +sets the passed parameters \fIparams\fR on the context before returning. +.PP +\&\fBEVP_PKEY_derive_set_peer_ex()\fR sets the peer key: this will normally +be a public key. The \fIvalidate_peer\fR will validate the public key if this value +is non zero. +.PP +\&\fBEVP_PKEY_derive_set_peer()\fR is similar to \fBEVP_PKEY_derive_set_peer_ex()\fR with +\&\fIvalidate_peer\fR set to 1. +.PP +\&\fBEVP_PKEY_derive()\fR derives a shared secret using \fIctx\fR. +If \fIkey\fR is NULL then the maximum size of the output buffer is written to the +\&\fIkeylen\fR parameter. If \fIkey\fR is not NULL then before the call the \fIkeylen\fR +parameter should contain the length of the \fIkey\fR buffer, if the call is +successful the shared secret is written to \fIkey\fR and the amount of data +written to \fIkeylen\fR. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_derive_init()\fR, algorithm +specific control operations can be performed to set any appropriate parameters +for the operation. +.PP +The function \fBEVP_PKEY_derive()\fR can be called more than once on the same +context if several operations are performed using the same parameters. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_derive_init()\fR and \fBEVP_PKEY_derive()\fR return 1 +for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +Derive shared secret (for example DH or EC keys): +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& ENGINE *eng; +\& unsigned char *skey; +\& size_t skeylen; +\& EVP_PKEY *pkey, *peerkey; +\& /* NB: assumes pkey, eng, peerkey have been already set up */ +\& +\& ctx = EVP_PKEY_CTX_new(pkey, eng); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_derive_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) +\& /* Error */ +\& +\& skey = OPENSSL_malloc(skeylen); +\& +\& if (!skey) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) +\& /* Error */ +\& +\& /* Shared secret is skey bytes written to buffer skey */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_KEYEXCH_fetch\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_derive_init()\fR, \fBEVP_PKEY_derive_set_peer()\fR and \fBEVP_PKEY_derive()\fR +functions were originally added in OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_derive_init_ex()\fR and \fBEVP_PKEY_derive_set_peer_ex()\fR functions were +added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_digestsign_supports_digest.3 b/static/netbsd/man3/EVP_PKEY_digestsign_supports_digest.3 new file mode 100644 index 00000000..325a0e25 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_digestsign_supports_digest.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: EVP_PKEY_digestsign_supports_digest.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_digestsign_supports_digest 3" +.TH EVP_PKEY_digestsign_supports_digest 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_digestsign_supports_digest \- indicate support for signature digest +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& #include +\& int EVP_PKEY_digestsign_supports_digest(EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, +\& const char *name, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_digestsign_supports_digest()\fR function queries whether the message +digest \fIname\fR is supported for public key signature operations associated with +key \fIpkey\fR. The query is done within an optional library context \fIlibctx\fR and +with an optional property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBEVP_PKEY_digestsign_supports_digest()\fR function returns 1 if the message +digest algorithm identified by \fIname\fR can be used for public key signature +operations associated with key \fIpkey\fR and 0 if it cannot be used. It returns +a negative value for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestSignInit_ex\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_digestsign_supports_digest()\fR function was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_encapsulate.3 b/static/netbsd/man3/EVP_PKEY_encapsulate.3 new file mode 100644 index 00000000..8f836c8d --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_encapsulate.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: EVP_PKEY_encapsulate.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_encapsulate 3" +.TH EVP_PKEY_encapsulate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_encapsulate_init, EVP_PKEY_auth_encapsulate_init, EVP_PKEY_encapsulate +\&\- Key encapsulation using a KEM algorithm with a public key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_auth_encapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpriv, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx, +\& unsigned char *wrappedkey, size_t *wrappedkeylen, +\& unsigned char *genkey, size_t *genkeylen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_encapsulate_init()\fR function initializes a public key algorithm +context \fIctx\fR for an encapsulation operation and then sets the \fIparams\fR +on the context in the same way as calling \fBEVP_PKEY_CTX_set_params\fR\|(3). +Note that \fIctx\fR is usually is produced using \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3), +specifying the public key to use. +.PP +The \fBEVP_PKEY_auth_encapsulate_init()\fR function is similar to +\&\fBEVP_PKEY_encapsulate_init()\fR but also passes an \fIauthpriv\fR authentication private +key that is used during encapsulation. +.PP +The \fBEVP_PKEY_encapsulate()\fR function performs a public key encapsulation +operation using \fIctx\fR. +The shared secret written to \fIgenkey\fR can be used as an input for key +derivation, typically for various symmetric algorithms. +Its size is written to \fIgenkeylen\fR, which must be initialised to the +size of the provided buffer. +.PP +The ciphertext written to \fIwrappedkey\fR is an encapsulated form, which +is expected to be only usable by the holder of the private key corresponding +to the public key associated with \fIctx\fR. +This ciphertext is then communicated to the private\-key holder, who can use +\&\fBEVP_PKEY_decapsulate\fR\|(3) to securely recover the same shared secret. +.PP +If \fIwrappedkey\fR is NULL then the maximum size of the output buffer is written +to the \fI*wrappedkeylen\fR parameter unless \fIwrappedkeylen\fR is NULL and the +maximum size of the generated key buffer is written to \fI*genkeylen\fR unless +\&\fIgenkeylen\fR is NULL. +.PP +If \fIwrappedkey\fR is not NULL and the call is successful then the generated +shared secret is written to \fIgenkey\fR and its size is written to +\&\fI*genkeylen\fR (which must be non\-NULL). +The encapsulated ciphertext is written to \fIwrappedkey\fR and +its size is written to \fI*wrappedkeylen\fR (must also be non\-NULL), +The value pointed to by \fIwrappedlen\fR initially hold the size of the +\&\fIunwrapped\fR buffer so that its size can be validated by the call, ensuring it +is large enough to hold the result written to \fIwrapped\fR. +.PP +Absent detailed prior knowledge of the internals of the specific KEM +algorithm, callers SHOULD NOT assume that the returned shared secret and +ciphertext are necessarily of the maximum possible length. +The lengths returned via \fI*wrappedkeylen\fR and \fI*genkeylen\fR SHOULD +be used to determine the actual lengths of the outputs. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_encapsulate_init()\fR, algorithm\-specific parameters +for the operation may be set or modified using \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_encapsulate_init()\fR, \fBEVP_PKEY_auth_encapsulate_init()\fR and +\&\fBEVP_PKEY_encapsulate()\fR return 1 for success and 0 or a negative value for +failure. In particular a return value of \-2 indicates the operation is not +supported by the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +Encapsulate an RSASVE key (for RSA keys). +.PP +.Vb 1 +\& #include +\& +\& /* +\& * NB: assumes rsa_pub_key is an public key of another party. +\& */ +\& +\& EVP_PKEY_CTX *ctx = NULL; +\& size_t secretlen = 0, outlen = 0; +\& unsigned char *out = NULL, *secret = NULL; +\& +\& ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL); +\& if (ctx == NULL) +\& /* Error */ +\& if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0) +\& /* Error */ +\& +\& /* Set the mode \- only \*(AqRSASVE\*(Aq is currently supported */ +\& if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0) +\& /* Error */ +\& /* Determine buffer length */ +\& if (EVP_PKEY_encapsulate(ctx, NULL, &outlen, NULL, &secretlen) <= 0) +\& /* Error */ +\& +\& out = OPENSSL_malloc(outlen); +\& secret = OPENSSL_malloc(secretlen); +\& if (out == NULL || secret == NULL) +\& /* malloc failure */ +\& +\& /* +\& * The generated \*(Aqsecret\*(Aq can be used as key material. +\& * The encapsulated \*(Aqout\*(Aq can be sent to another party who can +\& * decapsulate it using their private key to retrieve the \*(Aqsecret\*(Aq. +\& */ +\& if (EVP_PKEY_encapsulate(ctx, out, &outlen, secret, &secretlen) <= 0) +\& /* Error */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3), +\&\fBEVP_KEM\-RSA\fR\|(7), +\&\fBEVP_KEM\-X25519\fR\|(7), +\&\fBEVP_KEM\-EC\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-512\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-768\fR\|(7), +\&\fBEVP_KEM\-ML\-KEM\-1024\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBEVP_PKEY_encapsulate_init()\fR and \fBEVP_PKEY_encapsulate()\fR were +added in OpenSSL 3.0. +The function \fBEVP_PKEY_auth_encapsulate_init()\fR was added in OpenSSL 3.2. +.PP +Support for \fBML\-KEM\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_encrypt.3 b/static/netbsd/man3/EVP_PKEY_encrypt.3 new file mode 100644 index 00000000..bd7e8cbc --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_encrypt.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: EVP_PKEY_encrypt.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_encrypt 3" +.TH EVP_PKEY_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_encrypt_init_ex, +EVP_PKEY_encrypt_init, EVP_PKEY_encrypt \- encrypt using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_encrypt_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, +\& unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEVP_PKEY_encrypt_init()\fR function initializes a public key algorithm +context using key \fBpkey\fR for an encryption operation. +.PP +The \fBEVP_PKEY_encrypt_init_ex()\fR function initializes a public key algorithm +context using key \fBpkey\fR for an encryption operation and sets the +algorithm specific \fBparams\fR. +.PP +The \fBEVP_PKEY_encrypt()\fR function performs a public key encryption operation +using \fBctx\fR. The data to be encrypted is specified using the \fBin\fR and +\&\fBinlen\fR parameters. If \fBout\fR is \fBNULL\fR then the maximum size of the output +buffer is written to the \fBoutlen\fR parameter. If \fBout\fR is not \fBNULL\fR then +before the call the \fBoutlen\fR parameter should contain the length of the +\&\fBout\fR buffer, if the call is successful the encrypted data is written to +\&\fBout\fR and the amount of data written to \fBoutlen\fR. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_encrypt_init()\fR algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. These operations can be included in the \fBEVP_PKEY_encrypt_init_ex()\fR +call. +.PP +The function \fBEVP_PKEY_encrypt()\fR can be called more than once on the same +context if several operations are performed using the same parameters. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_encrypt_init()\fR, \fBEVP_PKEY_encrypt_init_ex()\fR and \fBEVP_PKEY_encrypt()\fR +return 1 for success and 0 or a negative value for failure. In particular a +return value of \-2 indicates the operation is not supported by the public key +algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +Encrypt data using OAEP (for RSA keys). See also \fBPEM_read_PUBKEY\fR\|(3) or +\&\fBd2i_X509\fR\|(3) for means to load a public key. You may also simply +set \*(Aqeng = NULL;\*(Aq to start with the default OpenSSL RSA implementation: +.PP +.Vb 3 +\& #include +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& ENGINE *eng; +\& unsigned char *out, *in; +\& size_t outlen, inlen; +\& EVP_PKEY *key; +\& +\& /* +\& * NB: assumes eng, key, in, inlen are already set up, +\& * and that key is an RSA public key +\& */ +\& ctx = EVP_PKEY_CTX_new(key, eng); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_encrypt_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) +\& /* Error */ +\& +\& out = OPENSSL_malloc(outlen); +\& +\& if (!out) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) +\& /* Error */ +\& +\& /* Encrypted data is outlen bytes written to buffer out */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBENGINE_by_id\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_fromdata.3 b/static/netbsd/man3/EVP_PKEY_fromdata.3 new file mode 100644 index 00000000..4a9fef62 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_fromdata.3 @@ -0,0 +1,336 @@ +.\" $NetBSD: EVP_PKEY_fromdata.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_fromdata 3" +.TH EVP_PKEY_fromdata 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable +\&\- functions to create keys and key parameters from user data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection, +\& OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described here are used to create new keys from user +provided key data, such as \fIn\fR, \fIe\fR and \fId\fR for a minimal RSA +keypair. +.PP +These functions use an \fBEVP_PKEY_CTX\fR context, which should primarily +be created with \fBEVP_PKEY_CTX_new_from_name\fR\|(3) or +\&\fBEVP_PKEY_CTX_new_id\fR\|(3). +.PP +The exact key data that the user can pass depends on the key type. +These are passed as an \fBOSSL_PARAM\fR\|(3) array. +.PP +\&\fBEVP_PKEY_fromdata_init()\fR initializes a public key algorithm context +for creating a key or key parameters from user data. +.PP +\&\fBEVP_PKEY_fromdata()\fR creates the structure to store a key or key parameters, +given data from \fIparams\fR, \fIselection\fR and a context that\*(Aqs been initialized +with \fBEVP_PKEY_fromdata_init()\fR. The result is written to \fI*ppkey\fR. +\&\fIselection\fR is described in "Selections". +The parameters that can be used for various types of key are as described by +the various "Common parameters" sections of the +\&\fBEVP_PKEY\-RSA\fR(7), +\&\fBEVP_PKEY\-DSA\fR(7), +\&\fBEVP_PKEY\-DH\fR(7), +\&\fBEVP_PKEY\-EC\fR(7), +\&\fBEVP_PKEY\-ED448\fR(7), +\&\fBEVP_PKEY\-X25519\fR(7), +\&\fBEVP_PKEY\-X448\fR(7), +\&\fBEVP_PKEY\-ED25519\fR(7), +\&\fBEVP_PKEY\-ML\-DSA\|(7)\fR +and +\&\fBEVP_PKEY\-ML\-KEM\|(7)\fR +pages. +.PP +\&\fBEVP_PKEY_fromdata_settable()\fR gets a constant \fBOSSL_PARAM\fR\|(3) array that describes +the settable parameters that can be used with \fBEVP_PKEY_fromdata()\fR. +\&\fIselection\fR is described in "Selections". +.PP +Parameters in the \fIparams\fR array that are not among the settable parameters +for the given \fIselection\fR are ignored. +.SS Selections +.IX Subsection "Selections" +The following constants can be used for \fIselection\fR: +.IP \fBEVP_PKEY_KEY_PARAMETERS\fR 4 +.IX Item "EVP_PKEY_KEY_PARAMETERS" +Only key parameters will be selected. +.IP \fBEVP_PKEY_PUBLIC_KEY\fR 4 +.IX Item "EVP_PKEY_PUBLIC_KEY" +Only public key components will be selected. This includes optional key +parameters. +.IP \fBEVP_PKEY_KEYPAIR\fR 4 +.IX Item "EVP_PKEY_KEYPAIR" +Any keypair components will be selected. This includes the private key, +public key and key parameters. +.SH NOTES +.IX Header "NOTES" +These functions only work with key management methods coming from a provider. +This is the mirror function to \fBEVP_PKEY_todata\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_fromdata_init()\fR and \fBEVP_PKEY_fromdata()\fR return 1 for success and 0 or +a negative value for failure. In particular a return value of \-2 indicates the +operation is not supported by the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +These examples are very terse for the sake of staying on topic, which +is the \fBEVP_PKEY_fromdata()\fR set of functions. In real applications, +BIGNUMs would be handled and converted to byte arrays with +\&\fBBN_bn2nativepad()\fR, but that\*(Aqs off topic here. +.SS "Creating an RSA keypair using raw key data" +.IX Subsection "Creating an RSA keypair using raw key data" +.Vb 1 +\& #include +\& +\& /* +\& * These are extremely small to make this example simple. A real +\& * and secure application will not use such small numbers. A real +\& * and secure application is expected to use BIGNUMs, and to build +\& * this array dynamically. +\& */ +\& unsigned long rsa_n = 0xbc747fc5; +\& unsigned long rsa_e = 0x10001; +\& unsigned long rsa_d = 0x7b133399; +\& OSSL_PARAM params[] = { +\& OSSL_PARAM_ulong("n", &rsa_n), +\& OSSL_PARAM_ulong("e", &rsa_e), +\& OSSL_PARAM_ulong("d", &rsa_d), +\& OSSL_PARAM_END +\& }; +\& +\& int main() +\& { +\& EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); +\& EVP_PKEY *pkey = NULL; +\& +\& if (ctx == NULL +\& || EVP_PKEY_fromdata_init(ctx) <= 0 +\& || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) +\& exit(1); +\& +\& /* Do what you want with |pkey| */ +\& } +.Ve +.SS "Creating an ECC keypair using raw key data" +.IX Subsection "Creating an ECC keypair using raw key data" +.Vb 3 +\& #include +\& #include +\& #include +\& +\& /* +\& * Fixed data to represent the private and public key. +\& */ +\& const unsigned char priv_data[] = { +\& 0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68, +\& 0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2, +\& 0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54, +\& 0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d +\& }; +\& /* UNCOMPRESSED FORMAT */ +\& const unsigned char pub_data[] = { +\& POINT_CONVERSION_UNCOMPRESSED, +\& 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e, +\& 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58, +\& 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb, +\& 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5, +\& 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff, +\& 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25, +\& 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f, +\& 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47 +\& }; +\& +\& int main() +\& { +\& EVP_PKEY_CTX *ctx; +\& EVP_PKEY *pkey = NULL; +\& BIGNUM *priv; +\& OSSL_PARAM_BLD *param_bld; +\& OSSL_PARAM *params = NULL; +\& int exitcode = 0; +\& +\& priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL); +\& +\& param_bld = OSSL_PARAM_BLD_new(); +\& if (priv != NULL && param_bld != NULL +\& && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group", +\& "prime256v1", 0) +\& && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv) +\& && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub", +\& pub_data, sizeof(pub_data))) +\& params = OSSL_PARAM_BLD_to_param(param_bld); +\& +\& ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +\& if (ctx == NULL +\& || params == NULL +\& || EVP_PKEY_fromdata_init(ctx) <= 0 +\& || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) { +\& exitcode = 1; +\& } else { +\& /* Do what you want with |pkey| */ +\& } +\& +\& EVP_PKEY_free(pkey); +\& EVP_PKEY_CTX_free(ctx); +\& OSSL_PARAM_free(params); +\& OSSL_PARAM_BLD_free(param_bld); +\& BN_free(priv); +\& +\& exit(exitcode); +\& } +.Ve +.SS "Finding out params for an unknown key type" +.IX Subsection "Finding out params for an unknown key type" +.Vb 2 +\& #include +\& #include +\& +\& /* Program expects a key type as first argument */ +\& int main(int argc, char *argv[]) +\& { +\& EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL); +\& const OSSL_PARAM *settable_params = NULL; +\& +\& if (ctx == NULL) +\& exit(1); +\& settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR); +\& if (settable_params == NULL) +\& exit(1); +\& +\& for (; settable_params\->key != NULL; settable_params++) { +\& const char *datatype = NULL; +\& +\& switch (settable_params\->data_type) { +\& case OSSL_PARAM_INTEGER: +\& datatype = "integer"; +\& break; +\& case OSSL_PARAM_UNSIGNED_INTEGER: +\& datatype = "unsigned integer"; +\& break; +\& case OSSL_PARAM_UTF8_STRING: +\& datatype = "printable string (utf\-8 encoding expected)"; +\& break; +\& case OSSL_PARAM_UTF8_PTR: +\& datatype = "printable string pointer (utf\-8 encoding expected)"; +\& break; +\& case OSSL_PARAM_OCTET_STRING: +\& datatype = "octet string"; +\& break; +\& case OSSL_PARAM_OCTET_PTR: +\& datatype = "octet string pointer"; +\& break; +\& } +\& printf("%s : %s ", settable_params\->key, datatype); +\& if (settable_params\->data_size == 0) +\& printf("(unlimited size)\en"); +\& else +\& printf("(maximum size %zu)\en", settable_params\->data_size); +\& } +\& } +.Ve +.PP +The descriptor \fBOSSL_PARAM\fR\|(3) returned by +\&\fBEVP_PKEY_fromdata_settable()\fR may also be used programmatically, for +example with \fBOSSL_PARAM_allocate_from_text\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_todata\fR\|(3), +\&\fBEVP_PKEY_gettable_params\fR\|(3), +\&\fBOSSL_PARAM\fR\|(3), +\&\fBprovider\fR\|(7), +\&\fBEVP_PKEY\-RSA\fR\|(7), +\&\fBEVP_PKEY\-EC\fR\|(7), +\&\fBEVP_PKEY\-ED25519\fR\|(7), +\&\fBEVP_PKEY\-ED448\fR\|(7), +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-X25519\fR\|(7), +\&\fBEVP_PKEY\-X448\fR\|(7), +\&\fBEVP_PKEY\-ML\-DSA\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\fR\|(7), +\&\fBEVP_PKEY\-SLH\-DSA\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.PP +Support for \fBML\-DSA\fR, \fBML\-KEM\fR and \fBSLH\-DSA\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_get_attr.3 b/static/netbsd/man3/EVP_PKEY_get_attr.3 new file mode 100644 index 00000000..40a16fa4 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_attr.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: EVP_PKEY_get_attr.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_attr 3" +.TH EVP_PKEY_get_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_get_attr, +EVP_PKEY_get_attr_count, +EVP_PKEY_get_attr_by_NID, EVP_PKEY_get_attr_by_OBJ, +EVP_PKEY_delete_attr, +EVP_PKEY_add1_attr, +EVP_PKEY_add1_attr_by_OBJ, EVP_PKEY_add1_attr_by_NID, EVP_PKEY_add1_attr_by_txt +\&\- EVP_PKEY X509_ATTRIBUTE functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_attr_count(const EVP_PKEY *key); +\& int EVP_PKEY_get_attr_by_NID(const EVP_PKEY *key, int nid, int lastpos); +\& int EVP_PKEY_get_attr_by_OBJ(const EVP_PKEY *key, const ASN1_OBJECT *obj, +\& int lastpos); +\& X509_ATTRIBUTE *EVP_PKEY_get_attr(const EVP_PKEY *key, int loc); +\& X509_ATTRIBUTE *EVP_PKEY_delete_attr(EVP_PKEY *key, int loc); +\& int EVP_PKEY_add1_attr(EVP_PKEY *key, X509_ATTRIBUTE *attr); +\& int EVP_PKEY_add1_attr_by_OBJ(EVP_PKEY *key, +\& const ASN1_OBJECT *obj, int type, +\& const unsigned char *bytes, int len); +\& int EVP_PKEY_add1_attr_by_NID(EVP_PKEY *key, +\& int nid, int type, +\& const unsigned char *bytes, int len); +\& int EVP_PKEY_add1_attr_by_txt(EVP_PKEY *key, +\& const char *attrname, int type, +\& const unsigned char *bytes, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are used by \fBPKCS12\fR. +.PP +\&\fBEVP_PKEY_get_attr_by_OBJ()\fR finds the location of the first matching object \fIobj\fR +in the \fIkey\fR attribute list. The search starts at the position after \fIlastpos\fR. +If the returned value is positive then it can be used on the next call to +\&\fBEVP_PKEY_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in order to iterate through +the remaining attributes. \fIlastpos\fR can be set to any negative value on the +first call, in order to start searching from the start of the attribute list. +.PP +\&\fBEVP_PKEY_get_attr_by_NID()\fR is similar to \fBEVP_PKEY_get_attr_by_OBJ()\fR except that +it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBEVP_PKEY_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the +\&\fIkey\fR attribute list. \fIloc\fR should be in the range from 0 to +\&\fBEVP_PKEY_get_attr_count()\fR \- 1. +.PP +\&\fBEVP_PKEY_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in +the \fIkey\fR attribute list. +.PP +\&\fBEVP_PKEY_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR object +to the \fIkey\fR attribute list. A new \fIkey\fR attribute list is created if required. +An error occurs if either \fIattr\fR is NULL, or the attribute already exists. +.PP +\&\fBEVP_PKEY_add1_attr_by_OBJ()\fR creates a new \fBX509_ATTRIBUTE\fR using +\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new +\&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it +to the \fIkey\fR object\*(Aqs attribute list. If \fIobj\fR already exists in the attribute +list then an error occurs. +.PP +\&\fBEVP_PKEY_add1_attr_by_NID()\fR is similar to \fBEVP_PKEY_add1_attr_by_OBJ()\fR except +that it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBEVP_PKEY_add1_attr_by_txt()\fR is similar to \fBEVP_PKEY_add1_attr_by_OBJ()\fR except +that it passes a name \fIattrname\fR associated with the object. +See for a list of SN_* names. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_get_attr_count()\fR returns the number of attributes in the \fIkey\fR object +attribute list or \-1 if the attribute list is NULL. +.PP +\&\fBEVP_PKEY_get_attr_by_OBJ()\fR returns \-1 if either the list is empty OR the object +is not found, otherwise it returns the location of the object in the list. +.PP +\&\fBEVP_PKEY_get_attr_by_NID()\fR is similar to \fBEVP_PKEY_get_attr_by_OBJ()\fR, except that +it returns \-2 if the \fInid\fR is not known by OpenSSL. +.PP +\&\fBEVP_PKEY_get_attr()\fR returns either a \fBX509_ATTRIBUTE\fR or NULL if there is a +error. +.PP +\&\fBEVP_PKEY_delete_attr()\fR returns either the removed \fBX509_ATTRIBUTE\fR or NULL if +there is a error. +.PP +\&\fBEVP_PKEY_add1_attr()\fR, \fBEVP_PKEY_add1_attr_by_OBJ()\fR, \fBEVP_PKEY_add1_attr_by_NID()\fR +and \fBEVP_PKEY_add1_attr_by_txt()\fR return 1 on success or 0 otherwise. +.SH NOTES +.IX Header "NOTES" +A \fBEVP_PKEY\fR object\*(Aqs attribute list is initially NULL. All the above functions +listed will return an error unless \fBEVP_PKEY_add1_attr()\fR is called. +All functions listed assume that the \fIkey\fR is not NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_ATTRIBUTE\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_get_default_digest.3 b/static/netbsd/man3/EVP_PKEY_get_default_digest.3 new file mode 100644 index 00000000..273c9470 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_default_digest.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: EVP_PKEY_get_default_digest.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_default_digest 3" +.TH EVP_PKEY_get_default_digest 3 "2013-02-05" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_PKEY_get_default_digest_nid \- get default signature digest +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fIEVP_PKEY_get_default_digest_nid()\fR function sets \fBpnid\fR to the default +message digest \s-1NID\s0 for the public key signature operations associated with key +\&\fBpkey\fR. +.SH "NOTES" +.IX Header "NOTES" +For all current standard OpenSSL public key algorithms \s-1SHA1\s0 is returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fIEVP_PKEY_get_default_digest_nid()\fR function returns 1 if the message digest +is advisory (that is other digests can be used) and 2 if it is mandatory (other +digests can not be used). It returns 0 or a negative value for failure. In +particular a return value of \-2 indicates the operation is not supported by the +public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIEVP_PKEY_CTX_new\fR\|(3), +\&\fIEVP_PKEY_sign\fR\|(3), +\&\fIEVP_PKEY_verify\fR\|(3), +\&\fIEVP_PKEY_verify_recover\fR\|(3), +.SH "HISTORY" +.IX Header "HISTORY" +This function was first added to OpenSSL 1.0.0. diff --git a/static/netbsd/man3/EVP_PKEY_get_default_digest_nid.3 b/static/netbsd/man3/EVP_PKEY_get_default_digest_nid.3 new file mode 100644 index 00000000..92f24d2a --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_default_digest_nid.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: EVP_PKEY_get_default_digest_nid.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_default_digest_nid 3" +.TH EVP_PKEY_get_default_digest_nid 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_get_default_digest_nid, EVP_PKEY_get_default_digest_name +\&\- get default signature digest +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_default_digest_name(EVP_PKEY *pkey, +\& char *mdname, size_t mdname_sz); +\& int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_get_default_digest_name()\fR fills in the default message digest +name for the public key signature operations associated with key +\&\fIpkey\fR into \fImdname\fR, up to at most \fImdname_sz\fR bytes including the +ending NUL byte. The name could be \f(CW"UNDEF"\fR, signifying that a digest +must (for return value 2) or may (for return value 1) be left unspecified. +.PP +\&\fBEVP_PKEY_get_default_digest_nid()\fR sets \fIpnid\fR to the default message +digest NID for the public key signature operations associated with key +\&\fIpkey\fR. Note that some signature algorithms (i.e. Ed25519 and Ed448) +do not use a digest during signing. In this case \fIpnid\fR will be set +to NID_undef. This function is only reliable for legacy keys, which +are keys with a \fBEVP_PKEY_ASN1_METHOD\fR; these keys have typically +been loaded from engines, or created with \fBEVP_PKEY_assign_RSA\fR\|(3) or +similar. +.SH NOTES +.IX Header "NOTES" +For all current standard OpenSSL public key algorithms SHA256 is returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_get_default_digest_name()\fR and \fBEVP_PKEY_get_default_digest_nid()\fR +both return 1 if the message digest is advisory (that is other digests +can be used) and 2 if it is mandatory (other digests can not be used). +They return 0 or a negative value for failure. In particular a return +value of \-2 indicates the operation is not supported by the public key +algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_digestsign_supports_digest\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_get_field_type.3 b/static/netbsd/man3/EVP_PKEY_get_field_type.3 new file mode 100644 index 00000000..ba573308 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_field_type.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_PKEY_get_field_type.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_field_type 3" +.TH EVP_PKEY_get_field_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_get_field_type, EVP_PKEY_get_ec_point_conv_form \- get field type +or point conversion form of a key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_field_type(const EVP_PKEY *pkey); +\& int EVP_PKEY_get_ec_point_conv_form(const EVP_PKEY *pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_get_field_type()\fR returns the field type NID of the \fIpkey\fR, if +\&\fIpkey\fR\*(Aqs key type supports it. The types currently supported +by the built\-in OpenSSL providers are either \fBNID_X9_62_prime_field\fR +for prime curves or \fBNID_X9_62_characteristic_two_field\fR for binary curves; +these values are defined in the \fI\fR header file. +.PP +\&\fBEVP_PKEY_get_ec_point_conv_form()\fR returns the point conversion format +of the \fIpkey\fR, if \fIpkey\fR\*(Aqs key type supports it. +.SH NOTES +.IX Header "NOTES" +Among the standard OpenSSL key types, this is only supported for EC and +SM2 keys. Other providers may support this for additional key types. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_get_field_type()\fR returns the field type NID or 0 on error. +.PP +\&\fBEVP_PKEY_get_ec_point_conv_form()\fR returns the point conversion format number +(see \fBEC_GROUP_copy\fR\|(3)) or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEC_GROUP_copy\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_get_group_name.3 b/static/netbsd/man3/EVP_PKEY_get_group_name.3 new file mode 100644 index 00000000..71ce5daa --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_group_name.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: EVP_PKEY_get_group_name.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_group_name 3" +.TH EVP_PKEY_get_group_name 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_get_group_name \- get group name of a key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_group_name(EVP_PKEY *pkey, char *gname, size_t gname_sz, +\& size_t *gname_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_get_group_name()\fR fills in the group name of the \fIpkey\fR into +\&\fIgname\fR, up to at most \fIgname_sz\fR bytes including the ending NUL byte +and assigns \fI*gname_len\fR the actual length of the name not including +the NUL byte, if \fIpkey\fR\*(Aqs key type supports it. +\&\fIgname\fR as well as \fIgname_len\fR may individually be NULL, and won\*(Aqt be +filled in or assigned in that case. +.SH NOTES +.IX Header "NOTES" +Among the standard OpenSSL key types, this is only supported for DH, EC and +SM2 keys. Other providers may support this for additional key types. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_get_group_name()\fR returns 1 if the group name could be filled in, +otherwise 0. +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_get_size.3 b/static/netbsd/man3/EVP_PKEY_get_size.3 new file mode 100644 index 00000000..81b51e80 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_get_size.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: EVP_PKEY_get_size.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_get_size 3" +.TH EVP_PKEY_get_size 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits, +EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size +\&\- EVP_PKEY information functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_size(const EVP_PKEY *pkey); +\& int EVP_PKEY_get_bits(const EVP_PKEY *pkey); +\& int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey); +\& +\& #define EVP_PKEY_bits EVP_PKEY_get_bits +\& #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits +\& #define EVP_PKEY_size EVP_PKEY_get_size +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_get_size()\fR returns the maximum suitable size for the output +buffers for almost all operations that can be done with \fIpkey\fR. +This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_MAX_SIZE\fR. +The primary documented use is with \fBEVP_SignFinal\fR\|(3) and +\&\fBEVP_SealInit\fR\|(3), but it isn\*(Aqt limited there. The returned size is +also large enough for the output buffer of \fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_derive\fR\|(3). +.PP +It must be stressed that, unless the documentation for the operation +that\*(Aqs being performed says otherwise, the size returned by +\&\fBEVP_PKEY_get_size()\fR is only preliminary and not exact, so the final +contents of the target buffer may be smaller. It is therefore crucial +to take note of the size given back by the function that performs the +operation, such as \fBEVP_PKEY_sign\fR\|(3) (the \fIsiglen\fR argument will +receive that length), to avoid bugs. +.PP +\&\fBEVP_PKEY_get_bits()\fR returns the cryptographic length of the cryptosystem +to which the key in \fIpkey\fR belongs, in bits. Note that the definition +of cryptographic length is specific to the key cryptosystem. +This length corresponds to the provider parameter \fBOSSL_PKEY_PARAM_BITS\fR. +.PP +\&\fBEVP_PKEY_get_security_bits()\fR returns the number of security bits of the given +\&\fIpkey\fR, bits of security is defined in NIST SP800\-57. +This corresponds to the provider parameter \fBOSSL_PKEY_PARAM_SECURITY_BITS\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_get_size()\fR, \fBEVP_PKEY_get_bits()\fR and \fBEVP_PKEY_get_security_bits()\fR +return a positive number, or 0 if this size isn\*(Aqt available. +.SH NOTES +.IX Header "NOTES" +Most functions that have an output buffer and are mentioned with +\&\fBEVP_PKEY_get_size()\fR have a functionality where you can pass NULL for the +buffer and still pass a pointer to an integer and get the exact size +that this function call delivers in the context that it\*(Aqs called in. +This allows those functions to be called twice, once to find out the +exact buffer size, then allocate the buffer in between, and call that +function again actually output the data. For those functions, it +isn\*(Aqt strictly necessary to call \fBEVP_PKEY_get_size()\fR to find out the +buffer size, but may be useful in cases where it\*(Aqs desirable to know +the upper limit in advance. +.PP +It should also be especially noted that \fBEVP_PKEY_get_size()\fR shouldn\*(Aqt be +used to get the output size for \fBEVP_DigestSignFinal()\fR, according to +"NOTES" in \fBEVP_DigestSignFinal\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-keymgmt\fR\|(7), +\&\fBEVP_SignFinal\fR\|(3), +\&\fBEVP_SealInit\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_bits()\fR, \fBEVP_PKEY_security_bits()\fR, and \fBEVP_PKEY_size()\fR functions +were renamed to include \f(CW\*(C`get\*(C'\fR in their names in OpenSSL 3.0, respectively. +The old names are kept as non\-deprecated alias macros. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_gettable_params.3 b/static/netbsd/man3/EVP_PKEY_gettable_params.3 new file mode 100644 index 00000000..8484c5c5 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_gettable_params.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: EVP_PKEY_gettable_params.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_gettable_params 3" +.TH EVP_PKEY_gettable_params 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_gettable_params, EVP_PKEY_get_params, +EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param, +EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param, +EVP_PKEY_get_octet_string_param +\&\- retrieve key parameters from a key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey); +\& int EVP_PKEY_get_params(const EVP_PKEY *pkey, OSSL_PARAM params[]); +\& int EVP_PKEY_get_int_param(const EVP_PKEY *pkey, const char *key_name, +\& int *out); +\& int EVP_PKEY_get_size_t_param(const EVP_PKEY *pkey, const char *key_name, +\& size_t *out); +\& int EVP_PKEY_get_bn_param(const EVP_PKEY *pkey, const char *key_name, +\& BIGNUM **bn); +\& int EVP_PKEY_get_utf8_string_param(const EVP_PKEY *pkey, const char *key_name, +\& char *str, size_t max_buf_sz, +\& size_t *out_len); +\& int EVP_PKEY_get_octet_string_param(const EVP_PKEY *pkey, const char *key_name, +\& unsigned char *buf, size_t max_buf_sz, +\& size_t *out_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +See \fBOSSL_PARAM\fR\|(3) for information about parameters. +.PP +\&\fBEVP_PKEY_get_params()\fR retrieves parameters from the key \fIpkey\fR, according to +the contents of \fIparams\fR. +.PP +\&\fBEVP_PKEY_gettable_params()\fR returns a constant list of \fIparams\fR indicating +the names and types of key parameters that can be retrieved. +.PP +An \fBOSSL_PARAM\fR\|(3) of type \fBOSSL_PARAM_INTEGER\fR or +\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR is of arbitrary length. Such a parameter can be +obtained using any of the functions \fBEVP_PKEY_get_int_param()\fR, +\&\fBEVP_PKEY_get_size_t_param()\fR or \fBEVP_PKEY_get_bn_param()\fR. Attempting to +obtain an integer value that does not fit into a native C \fBint\fR type will cause +\&\fBEVP_PKEY_get_int_param()\fR to fail. Similarly attempting to obtain an integer +value that is negative or does not fit into a native C \fBsize_t\fR type using +\&\fBEVP_PKEY_get_size_t_param()\fR will also fail. +.PP +\&\fBEVP_PKEY_get_int_param()\fR retrieves a key \fIpkey\fR integer value \fI*out\fR +associated with a name of \fIkey_name\fR if it fits into \f(CW\*(C`int\*(C'\fR type. For +parameters that do not fit into \f(CW\*(C`int\*(C'\fR use \fBEVP_PKEY_get_bn_param()\fR. +.PP +\&\fBEVP_PKEY_get_size_t_param()\fR retrieves a key \fIpkey\fR size_t value \fI*out\fR +associated with a name of \fIkey_name\fR if it fits into \f(CW\*(C`size_t\*(C'\fR type. For +parameters that do not fit into \f(CW\*(C`size_t\*(C'\fR use \fBEVP_PKEY_get_bn_param()\fR. +.PP +\&\fBEVP_PKEY_get_bn_param()\fR retrieves a key \fIpkey\fR BIGNUM value \fI**bn\fR +associated with a name of \fIkey_name\fR. If \fI*bn\fR is NULL then the BIGNUM +is allocated by the method. +.PP +\&\fBEVP_PKEY_get_utf8_string_param()\fR get a key \fIpkey\fR UTF8 string value into a +buffer \fIstr\fR of maximum size \fImax_buf_sz\fR associated with a name of +\&\fIkey_name\fR. The maximum size must be large enough to accommodate the string +value including a terminating NUL byte, or this function will fail. +If \fIout_len\fR is not NULL, \fI*out_len\fR is set to the length of the string +not including the terminating NUL byte. The required buffer size not including +the terminating NUL byte can be obtained from \fI*out_len\fR by calling the +function with \fIstr\fR set to NULL. +.PP +\&\fBEVP_PKEY_get_octet_string_param()\fR get a key \fIpkey\fR\*(Aqs octet string value into a +buffer \fIbuf\fR of maximum size \fImax_buf_sz\fR associated with a name of \fIkey_name\fR. +If \fIout_len\fR is not NULL, \fI*out_len\fR is set to the length of the contents. +The required buffer size can be obtained from \fI*out_len\fR by calling the +function with \fIbuf\fR set to NULL. +.SH NOTES +.IX Header "NOTES" +These functions only work for \fBEVP_PKEY\fRs that contain a provider side key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_gettable_params()\fR returns NULL on error or if it is not supported. +.PP +All other methods return 1 if a value associated with the key\*(Aqs \fIkey_name\fR was +successfully returned, or 0 if there was an error. +An error may be returned by methods \fBEVP_PKEY_get_utf8_string_param()\fR and +\&\fBEVP_PKEY_get_octet_string_param()\fR if \fImax_buf_sz\fR is not big enough to hold the +value. If \fIout_len\fR is not NULL, \fI*out_len\fR will be assigned the required +buffer size to hold the value. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 1 +\& #include +\& +\& char curve_name[64]; +\& unsigned char pub[256]; +\& BIGNUM *bn_priv = NULL; +\& +\& /* +\& * NB: assumes \*(Aqkey\*(Aq is set up before the next step. In this example the key +\& * is an EC key. +\& */ +\& +\& if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_GROUP_NAME, +\& curve_name, sizeof(curve_name), &len)) { +\& /* Error */ +\& } +\& if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY, +\& pub, sizeof(pub), &len)) { +\& /* Error */ +\& } +\& if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) { +\& /* Error */ +\& } +\& +\& BN_clear_free(bn_priv); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), \fBprovider\-keymgmt\fR\|(7), \fBOSSL_PARAM\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_is_a.3 b/static/netbsd/man3/EVP_PKEY_is_a.3 new file mode 100644 index 00000000..736fcba7 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_is_a.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: EVP_PKEY_is_a.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_is_a 3" +.TH EVP_PKEY_is_a 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_is_a, EVP_PKEY_can_sign, EVP_PKEY_type_names_do_all, +EVP_PKEY_get0_type_name, EVP_PKEY_get0_description, EVP_PKEY_get0_provider +\&\- key type and capabilities functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name); +\& int EVP_PKEY_can_sign(const EVP_PKEY *pkey); +\& int EVP_PKEY_type_names_do_all(const EVP_PKEY *pkey, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_PKEY_get0_type_name(const EVP_PKEY *key); +\& const char *EVP_PKEY_get0_description(const EVP_PKEY *key); +\& const OSSL_PROVIDER *EVP_PKEY_get0_provider(const EVP_PKEY *key); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_is_a()\fR checks if the key type of \fIpkey\fR is \fIname\fR. +.PP +\&\fBEVP_PKEY_can_sign()\fR checks if the functionality for the key type of +\&\fIpkey\fR supports signing. No other check is done, such as whether +\&\fIpkey\fR contains a private key. +.PP +\&\fBEVP_PKEY_type_names_do_all()\fR traverses all names for \fIpkey\fR\*(Aqs key type, and +calls \fIfn\fR with each name and \fIdata\fR. For example, an RSA \fBEVP_PKEY\fR may +be named both \f(CW\*(C`RSA\*(C'\fR and \f(CW\*(C`rsaEncryption\*(C'\fR. +The order of the names depends on the provider implementation that holds +the key. +.PP +\&\fBEVP_PKEY_get0_type_name()\fR returns the first key type name that is found +for the given \fIpkey\fR. Note that the \fIpkey\fR may have multiple synonyms +associated with it. In this case it depends on the provider implementation +that holds the key which one will be returned. +Ownership of the returned string is retained by the \fIpkey\fR object and should +not be freed by the caller. +.PP +\&\fBEVP_PKEY_get0_description()\fR returns a description of the type of \fBEVP_PKEY\fR, +meant for display and human consumption. The description is at the +discretion of the key type implementation. +.PP +\&\fBEVP_PKEY_get0_provider()\fR returns the provider of the \fBEVP_PKEY\fR\*(Aqs +\&\fBEVP_KEYMGMT\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_is_a()\fR returns 1 if \fIpkey\fR has the key type \fIname\fR, +otherwise 0. +.PP +\&\fBEVP_PKEY_can_sign()\fR returns 1 if the \fIpkey\fR key type functionality +supports signing, otherwise 0. +.PP +\&\fBEVP_PKEY_get0_type_name()\fR returns the name that is found or NULL on error. +.PP +\&\fBEVP_PKEY_get0_description()\fR returns the description if found or NULL if not. +.PP +\&\fBEVP_PKEY_get0_provider()\fR returns the provider if found or NULL if not. +.PP +\&\fBEVP_PKEY_type_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any +names. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS \fBEVP_PKEY_is_a()\fP +.IX Subsection "EVP_PKEY_is_a()" +The loaded providers and what key types they support will ultimately +determine what \fIname\fR is possible to use with \fBEVP_PKEY_is_a()\fR. We do know +that the default provider supports RSA, DH, DSA and EC keys, so we can use +this as an crude example: +.PP +.Vb 1 +\& #include +\& +\& ... +\& /* |pkey| is an EVP_PKEY* */ +\& if (EVP_PKEY_is_a(pkey, "RSA")) { +\& BIGNUM *modulus = NULL; +\& if (EVP_PKEY_get_bn_param(pkey, "n", &modulus)) +\& /* do whatever with the modulus */ +\& BN_free(modulus); +\& } +.Ve +.SS \fBEVP_PKEY_can_sign()\fP +.IX Subsection "EVP_PKEY_can_sign()" +.Vb 1 +\& #include +\& +\& ... +\& /* |pkey| is an EVP_PKEY* */ +\& if (!EVP_PKEY_can_sign(pkey)) { +\& fprintf(stderr, "Not a signing key!"); +\& exit(1); +\& } +\& /* Sign something... */ +.Ve +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_keygen.3 b/static/netbsd/man3/EVP_PKEY_keygen.3 new file mode 100644 index 00000000..57032863 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_keygen.3 @@ -0,0 +1,313 @@ +.\" $NetBSD: EVP_PKEY_keygen.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_keygen 3" +.TH EVP_PKEY_keygen 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_Q_keygen, +EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_generate, +EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, +EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, +EVP_PKEY_CTX_get_app_data, +EVP_PKEY_gen_cb, +EVP_PKEY_paramgen, EVP_PKEY_keygen +\&\- key and parameter generation and check functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *EVP_PKEY_Q_keygen(OSSL_LIB_CTX *libctx, const char *propq, +\& const char *type, ...); +\& +\& int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_generate(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); +\& int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); +\& int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); +\& +\& typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); +\& +\& void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); +\& EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); +\& +\& int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); +\& +\& void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); +\& void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Generating keys is sometimes straight forward, just generate the key\*(Aqs +numbers and be done with it. However, there are certain key types that need +key parameters, often called domain parameters but not necessarily limited +to that, that also need to be generated. In addition to this, the caller +may want to set user provided generation parameters that further affect key +parameter or key generation, such as the desired key size. +.PP +To flexibly allow all that\*(Aqs just been described, key parameter and key +generation is divided into an initialization of a key algorithm context, +functions to set user provided parameters, and finally the key parameter or +key generation function itself. +.PP +The key algorithm context must be created using \fBEVP_PKEY_CTX_new\fR\|(3) or +variants thereof, see that manual for details. +.PP +\&\fBEVP_PKEY_keygen_init()\fR initializes a public key algorithm context \fIctx\fR +for a key generation operation. +.PP +\&\fBEVP_PKEY_paramgen_init()\fR is similar to \fBEVP_PKEY_keygen_init()\fR except key +parameters are generated. +.PP +After initialization, generation parameters may be provided with +\&\fBEVP_PKEY_CTX_ctrl\fR\|(3) or \fBEVP_PKEY_CTX_set_params\fR\|(3), or any other +function described in those manuals. +.PP +\&\fBEVP_PKEY_generate()\fR performs the generation operation, the resulting key +parameters or key are written to \fI*ppkey\fR. If \fI*ppkey\fR is NULL when this +function is called, it will be allocated, and should be freed by the caller +when no longer useful, using \fBEVP_PKEY_free\fR\|(3). +.PP +\&\fBEVP_PKEY_paramgen()\fR and \fBEVP_PKEY_keygen()\fR do exactly the same thing as +\&\fBEVP_PKEY_generate()\fR, after checking that the corresponding \fBEVP_PKEY_paramgen_init()\fR +or \fBEVP_PKEY_keygen_init()\fR was used to initialize \fIctx\fR. +These are older functions that are kept for backward compatibility. +It is safe to use \fBEVP_PKEY_generate()\fR instead. +.PP +The function \fBEVP_PKEY_set_cb()\fR sets the key or parameter generation callback +to \fIcb\fR. The function \fBEVP_PKEY_CTX_get_cb()\fR returns the key or parameter +generation callback. +.PP +The function \fBEVP_PKEY_CTX_get_keygen_info()\fR returns parameters associated +with the generation operation. If \fIidx\fR is \-1 the total number of +parameters available is returned. Any non negative value returns the value of +that parameter. \fBEVP_PKEY_CTX_gen_keygen_info()\fR with a nonnegative value for +\&\fIidx\fR should only be called within the generation callback. +.PP +If the callback returns 0 then the key generation operation is aborted and an +error occurs. This might occur during a time consuming operation where +a user clicks on a "cancel" button. +.PP +The functions \fBEVP_PKEY_CTX_set_app_data()\fR and \fBEVP_PKEY_CTX_get_app_data()\fR +associate an opaque, application\-defined pointer with an EVP_PKEY_CTX object. +.PP +This pointer is not interpreted by the library and is reserved entirely for use +by the application. It may be used to store arbitrary context or state that +needs to be accessible wherever the corresponding EVP_PKEY_CTX is available. +.PP +\&\fBEVP_PKEY_Q_keygen()\fR abstracts from the explicit use of \fBEVP_PKEY_CTX\fR while +providing a \*(Aqquick\*(Aq but limited way of generating a new asymmetric key pair. +It provides shorthands for simple and common cases of key generation. +As usual, the library context \fIlibctx\fR and property query \fIpropq\fR +can be given for fetching algorithms from providers. +If \fItype\fR is \f(CW\*(C`RSA\*(C'\fR, +a \fBsize_t\fR parameter must be given to specify the size of the RSA key. +If \fItype\fR is \f(CW\*(C`EC\*(C'\fR, +a string parameter must be given to specify the name of the EC curve. +If \fItype\fR is: +\&\f(CW\*(C`ED25519\*(C'\fR, +\&\f(CW\*(C`ED448\*(C'\fR, +\&\f(CW\*(C`SM2\*(C'\fR, +\&\f(CW\*(C`X25519\*(C'\fR, +\&\f(CW\*(C`X448\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-44\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-65\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-87\*(C'\fR, +\&\f(CW\*(C`ML\-KEM\-512\*(C'\fR, +\&\f(CW\*(C`ML\-KEM\-768\*(C'\fR, or +\&\f(CW\*(C`ML\-KEM\-1024\*(C'\fR +no further parameters are needed. Other key types may be possible if they are +supplied by the loaded providers. \fBEVP_PKEY_Q_keygen()\fR may be usable with such +key types as long as they do not require further parameters. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_keygen_init()\fR, \fBEVP_PKEY_paramgen_init()\fR, \fBEVP_PKEY_keygen()\fR and +\&\fBEVP_PKEY_paramgen()\fR return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.PP +\&\fBEVP_PKEY_Q_keygen()\fR returns an \fBEVP_PKEY\fR, or NULL on failure. +.SH NOTES +.IX Header "NOTES" +After the call to \fBEVP_PKEY_keygen_init()\fR or \fBEVP_PKEY_paramgen_init()\fR algorithm +specific control operations can be performed to set any appropriate parameters +for the operation. +.PP +The functions \fBEVP_PKEY_keygen()\fR and \fBEVP_PKEY_paramgen()\fR can be called more than +once on the same context if several operations are performed using the same +parameters. +.PP +The meaning of the parameters passed to the callback will depend on the +algorithm and the specific implementation of the algorithm. Some might not +give any useful information at all during key or parameter generation. Others +might not even call the callback. +.PP +The operation performed by key or parameter generation depends on the algorithm +used. In some cases (e.g. EC with a supplied named curve) the "generation" +option merely sets the appropriate fields in an EVP_PKEY structure. +.PP +In OpenSSL an EVP_PKEY structure containing a private key also contains the +public key components and parameters (if any). An OpenSSL private key is +equivalent to what some libraries call a "key pair". A private key can be used +in functions which require the use of a public key or parameters. +.SH EXAMPLES +.IX Header "EXAMPLES" +Generate a 2048 bit RSA key: +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& EVP_PKEY *pkey = NULL; +\& +\& ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_keygen_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) +\& /* Error */ +\& +\& /* Generate key */ +\& if (EVP_PKEY_keygen(ctx, &pkey) <= 0) +\& /* Error */ +.Ve +.PP +Generate a key from a set of parameters: +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& ENGINE *eng; +\& EVP_PKEY *pkey = NULL, *param; +\& +\& /* Assumed param, eng are set up already */ +\& ctx = EVP_PKEY_CTX_new(param, eng); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_keygen_init(ctx) <= 0) +\& /* Error */ +\& +\& /* Generate key */ +\& if (EVP_PKEY_keygen(ctx, &pkey) <= 0) +\& /* Error */ +.Ve +.PP +Example of generation callback for OpenSSL public key implementations: +.PP +.Vb 1 +\& /* Application data is a BIO to output status to */ +\& +\& EVP_PKEY_CTX_set_app_data(ctx, status_bio); +\& +\& static int genpkey_cb(EVP_PKEY_CTX *ctx) +\& { +\& char c = \*(Aq*\*(Aq; +\& BIO *b = EVP_PKEY_CTX_get_app_data(ctx); +\& int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); +\& +\& if (p == 0) +\& c = \*(Aq.\*(Aq; +\& if (p == 1) +\& c = \*(Aq+\*(Aq; +\& if (p == 2) +\& c = \*(Aq*\*(Aq; +\& if (p == 3) +\& c = \*(Aq\en\*(Aq; +\& BIO_write(b, &c, 1); +\& (void)BIO_flush(b); +\& return 1; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RSA_gen\fR\|(3), \fBEVP_EC_gen\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PKEY_keygen_init()\fR, int \fBEVP_PKEY_paramgen_init()\fR, \fBEVP_PKEY_keygen()\fR, +\&\fBEVP_PKEY_paramgen()\fR, \fBEVP_PKEY_gen_cb()\fR, \fBEVP_PKEY_CTX_set_cb()\fR, +\&\fBEVP_PKEY_CTX_get_cb()\fR, \fBEVP_PKEY_CTX_get_keygen_info()\fR, +\&\fBEVP_PKEY_CTX_set_app_data()\fR and \fBEVP_PKEY_CTX_get_app_data()\fR were added in +OpenSSL 1.0.0. +.PP +\&\fBEVP_PKEY_Q_keygen()\fR and \fBEVP_PKEY_generate()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_meth_get_count.3 b/static/netbsd/man3/EVP_PKEY_meth_get_count.3 new file mode 100644 index 00000000..33d40015 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_meth_get_count.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: EVP_PKEY_meth_get_count.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_meth_get_count 3" +.TH EVP_PKEY_meth_get_count 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_meth_get_count, EVP_PKEY_meth_get0, EVP_PKEY_meth_get0_info \- enumerate public key methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& size_t EVP_PKEY_meth_get_count(void); +\& const EVP_PKEY_METHOD *EVP_PKEY_meth_get0(size_t idx); +\& void EVP_PKEY_meth_get0_info(int *ppkey_id, int *pflags, +\& const EVP_PKEY_METHOD *meth); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +\&\fBEVP_PKEY_meth_count()\fR returns a count of the number of public key methods +available: it includes standard methods and any methods added by the +application. +.PP +\&\fBEVP_PKEY_meth_get0()\fR returns the public key method \fBidx\fR. The value of \fBidx\fR +must be between zero and \fBEVP_PKEY_meth_get_count()\fR \- 1. +.PP +\&\fBEVP_PKEY_meth_get0_info()\fR returns the public key ID (a NID) and any flags +associated with the public key method \fB*meth\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_meth_count()\fR returns the number of available public key methods. +.PP +\&\fBEVP_PKEY_meth_get0()\fR return a public key method or \fBNULL\fR if \fBidx\fR is +out of range. +.PP +\&\fBEVP_PKEY_meth_get0_info()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_meth_new.3 b/static/netbsd/man3/EVP_PKEY_meth_new.3 new file mode 100644 index 00000000..e3a1344a --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_meth_new.3 @@ -0,0 +1,557 @@ +.\" $NetBSD: EVP_PKEY_meth_new.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_meth_new 3" +.TH EVP_PKEY_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, +EVP_PKEY_meth_add0, EVP_PKEY_METHOD, +EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, +EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, +EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, +EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, +EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, +EVP_PKEY_meth_set_digestsign, EVP_PKEY_meth_set_digestverify, +EVP_PKEY_meth_set_check, +EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check, +EVP_PKEY_meth_set_digest_custom, +EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, +EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, +EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, +EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, +EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, +EVP_PKEY_meth_get_digestsign, EVP_PKEY_meth_get_digestverify, +EVP_PKEY_meth_get_check, +EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check, +EVP_PKEY_meth_get_digest_custom, +EVP_PKEY_meth_remove +\&\- manipulating EVP_PKEY_METHOD structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& typedef struct evp_pkey_method_st EVP_PKEY_METHOD; +\& +\& EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags); +\& void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth); +\& void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src); +\& const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type); +\& int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth); +\& int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth); +\& +\& void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth, +\& int (*init) (EVP_PKEY_CTX *ctx)); +\& void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth, +\& int (*copy) (EVP_PKEY_CTX *dst, +\& const EVP_PKEY_CTX *src)); +\& void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth, +\& void (*cleanup) (EVP_PKEY_CTX *ctx)); +\& void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth, +\& int (*paramgen_init) (EVP_PKEY_CTX *ctx), +\& int (*paramgen) (EVP_PKEY_CTX *ctx, +\& EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth, +\& int (*keygen_init) (EVP_PKEY_CTX *ctx), +\& int (*keygen) (EVP_PKEY_CTX *ctx, +\& EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth, +\& int (*sign_init) (EVP_PKEY_CTX *ctx), +\& int (*sign) (EVP_PKEY_CTX *ctx, +\& unsigned char *sig, size_t *siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth, +\& int (*verify_init) (EVP_PKEY_CTX *ctx), +\& int (*verify) (EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, +\& size_t siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth, +\& int (*verify_recover_init) (EVP_PKEY_CTX +\& *ctx), +\& int (*verify_recover) (EVP_PKEY_CTX +\& *ctx, +\& unsigned char +\& *sig, +\& size_t *siglen, +\& const unsigned +\& char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth, +\& int (*signctx_init) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx), +\& int (*signctx) (EVP_PKEY_CTX *ctx, +\& unsigned char *sig, +\& size_t *siglen, +\& EVP_MD_CTX *mctx)); +\& void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth, +\& int (*verifyctx_init) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx), +\& int (*verifyctx) (EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, +\& int siglen, +\& EVP_MD_CTX *mctx)); +\& void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth, +\& int (*encrypt_init) (EVP_PKEY_CTX *ctx), +\& int (*encryptfn) (EVP_PKEY_CTX *ctx, +\& unsigned char *out, +\& size_t *outlen, +\& const unsigned char *in, +\& size_t inlen)); +\& void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth, +\& int (*decrypt_init) (EVP_PKEY_CTX *ctx), +\& int (*decrypt) (EVP_PKEY_CTX *ctx, +\& unsigned char *out, +\& size_t *outlen, +\& const unsigned char *in, +\& size_t inlen)); +\& void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth, +\& int (*derive_init) (EVP_PKEY_CTX *ctx), +\& int (*derive) (EVP_PKEY_CTX *ctx, +\& unsigned char *key, +\& size_t *keylen)); +\& void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth, +\& int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, +\& void *p2), +\& int (*ctrl_str) (EVP_PKEY_CTX *ctx, +\& const char *type, +\& const char *value)); +\& void EVP_PKEY_meth_set_digestsign(EVP_PKEY_METHOD *pmeth, +\& int (*digestsign) (EVP_MD_CTX *ctx, +\& unsigned char *sig, +\& size_t *siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_set_digestverify(EVP_PKEY_METHOD *pmeth, +\& int (*digestverify) (EVP_MD_CTX *ctx, +\& const unsigned char *sig, +\& size_t siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth, +\& int (*check) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth, +\& int (*check) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth, +\& int (*check) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_set_digest_custom(EVP_PKEY_METHOD *pmeth, +\& int (*digest_custom) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx)); +\& +\& void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth, +\& int (**pinit) (EVP_PKEY_CTX *ctx)); +\& void EVP_PKEY_meth_get_copy(const EVP_PKEY_METHOD *pmeth, +\& int (**pcopy) (EVP_PKEY_CTX *dst, +\& EVP_PKEY_CTX *src)); +\& void EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth, +\& void (**pcleanup) (EVP_PKEY_CTX *ctx)); +\& void EVP_PKEY_meth_get_paramgen(const EVP_PKEY_METHOD *pmeth, +\& int (**pparamgen_init) (EVP_PKEY_CTX *ctx), +\& int (**pparamgen) (EVP_PKEY_CTX *ctx, +\& EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_get_keygen(const EVP_PKEY_METHOD *pmeth, +\& int (**pkeygen_init) (EVP_PKEY_CTX *ctx), +\& int (**pkeygen) (EVP_PKEY_CTX *ctx, +\& EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_get_sign(const EVP_PKEY_METHOD *pmeth, +\& int (**psign_init) (EVP_PKEY_CTX *ctx), +\& int (**psign) (EVP_PKEY_CTX *ctx, +\& unsigned char *sig, size_t *siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_get_verify(const EVP_PKEY_METHOD *pmeth, +\& int (**pverify_init) (EVP_PKEY_CTX *ctx), +\& int (**pverify) (EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, +\& size_t siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth, +\& int (**pverify_recover_init) (EVP_PKEY_CTX +\& *ctx), +\& int (**pverify_recover) (EVP_PKEY_CTX +\& *ctx, +\& unsigned char +\& *sig, +\& size_t *siglen, +\& const unsigned +\& char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_get_signctx(const EVP_PKEY_METHOD *pmeth, +\& int (**psignctx_init) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx), +\& int (**psignctx) (EVP_PKEY_CTX *ctx, +\& unsigned char *sig, +\& size_t *siglen, +\& EVP_MD_CTX *mctx)); +\& void EVP_PKEY_meth_get_verifyctx(const EVP_PKEY_METHOD *pmeth, +\& int (**pverifyctx_init) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx), +\& int (**pverifyctx) (EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, +\& int siglen, +\& EVP_MD_CTX *mctx)); +\& void EVP_PKEY_meth_get_encrypt(const EVP_PKEY_METHOD *pmeth, +\& int (**pencrypt_init) (EVP_PKEY_CTX *ctx), +\& int (**pencryptfn) (EVP_PKEY_CTX *ctx, +\& unsigned char *out, +\& size_t *outlen, +\& const unsigned char *in, +\& size_t inlen)); +\& void EVP_PKEY_meth_get_decrypt(const EVP_PKEY_METHOD *pmeth, +\& int (**pdecrypt_init) (EVP_PKEY_CTX *ctx), +\& int (**pdecrypt) (EVP_PKEY_CTX *ctx, +\& unsigned char *out, +\& size_t *outlen, +\& const unsigned char *in, +\& size_t inlen)); +\& void EVP_PKEY_meth_get_derive(const EVP_PKEY_METHOD *pmeth, +\& int (**pderive_init) (EVP_PKEY_CTX *ctx), +\& int (**pderive) (EVP_PKEY_CTX *ctx, +\& unsigned char *key, +\& size_t *keylen)); +\& void EVP_PKEY_meth_get_ctrl(const EVP_PKEY_METHOD *pmeth, +\& int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1, +\& void *p2), +\& int (**pctrl_str) (EVP_PKEY_CTX *ctx, +\& const char *type, +\& const char *value)); +\& void EVP_PKEY_meth_get_digestsign(const EVP_PKEY_METHOD *pmeth, +\& int (**digestsign) (EVP_MD_CTX *ctx, +\& unsigned char *sig, +\& size_t *siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_get_digestverify(const EVP_PKEY_METHOD *pmeth, +\& int (**digestverify) (EVP_MD_CTX *ctx, +\& const unsigned char *sig, +\& size_t siglen, +\& const unsigned char *tbs, +\& size_t tbslen)); +\& void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth, +\& int (**pcheck) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth, +\& int (**pcheck) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth, +\& int (**pcheck) (EVP_PKEY *pkey)); +\& void EVP_PKEY_meth_get_digest_custom(const EVP_PKEY_METHOD *pmeth, +\& int (**pdigest_custom) (EVP_PKEY_CTX *ctx, +\& EVP_MD_CTX *mctx)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +\&\fBEVP_PKEY_METHOD\fR is a structure which holds a set of methods for a +specific public key cryptographic algorithm. Those methods are usually +used to perform different jobs, such as generating a key, signing or +verifying, encrypting or decrypting, etc. +.PP +There are two places where the \fBEVP_PKEY_METHOD\fR objects are stored: one +is a built\-in static array representing the standard methods for different +algorithms, and the other one is a stack of user\-defined application\-specific +methods, which can be manipulated by using \fBEVP_PKEY_meth_add0\fR\|(3). +.PP +The \fBEVP_PKEY_METHOD\fR objects are usually referenced by \fBEVP_PKEY_CTX\fR +objects. +.SS Methods +.IX Subsection "Methods" +The methods are the underlying implementations of a particular public key +algorithm present by the \fBEVP_PKEY_CTX\fR object. +.PP +.Vb 3 +\& int (*init) (EVP_PKEY_CTX *ctx); +\& int (*copy) (EVP_PKEY_CTX *dst, const EVP_PKEY_CTX *src); +\& void (*cleanup) (EVP_PKEY_CTX *ctx); +.Ve +.PP +The \fBinit()\fR method is called to initialize algorithm\-specific data when a new +\&\fBEVP_PKEY_CTX\fR is created. As opposed to \fBinit()\fR, the \fBcleanup()\fR method is called +when an \fBEVP_PKEY_CTX\fR is freed. The \fBcopy()\fR method is called when an \fBEVP_PKEY_CTX\fR +is being duplicated. Refer to \fBEVP_PKEY_CTX_new\fR\|(3), \fBEVP_PKEY_CTX_new_id\fR\|(3), +\&\fBEVP_PKEY_CTX_free\fR\|(3) and \fBEVP_PKEY_CTX_dup\fR\|(3). +.PP +.Vb 2 +\& int (*paramgen_init) (EVP_PKEY_CTX *ctx); +\& int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); +.Ve +.PP +The \fBparamgen_init()\fR and \fBparamgen()\fR methods deal with key parameter generation. +They are called by \fBEVP_PKEY_paramgen_init\fR\|(3) and \fBEVP_PKEY_paramgen\fR\|(3) to +handle the parameter generation process. +.PP +.Vb 2 +\& int (*keygen_init) (EVP_PKEY_CTX *ctx); +\& int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); +.Ve +.PP +The \fBkeygen_init()\fR and \fBkeygen()\fR methods are used to generate the actual key for +the specified algorithm. They are called by \fBEVP_PKEY_keygen_init\fR\|(3) and +\&\fBEVP_PKEY_keygen\fR\|(3). +.PP +.Vb 3 +\& int (*sign_init) (EVP_PKEY_CTX *ctx); +\& int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, +\& const unsigned char *tbs, size_t tbslen); +.Ve +.PP +The \fBsign_init()\fR and \fBsign()\fR methods are used to generate the signature of a +piece of data using a private key. They are called by \fBEVP_PKEY_sign_init\fR\|(3) +and \fBEVP_PKEY_sign\fR\|(3). +.PP +.Vb 4 +\& int (*verify_init) (EVP_PKEY_CTX *ctx); +\& int (*verify) (EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, size_t siglen, +\& const unsigned char *tbs, size_t tbslen); +.Ve +.PP +The \fBverify_init()\fR and \fBverify()\fR methods are used to verify whether a signature is +valid. They are called by \fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3). +.PP +.Vb 4 +\& int (*verify_recover_init) (EVP_PKEY_CTX *ctx); +\& int (*verify_recover) (EVP_PKEY_CTX *ctx, +\& unsigned char *rout, size_t *routlen, +\& const unsigned char *sig, size_t siglen); +.Ve +.PP +The \fBverify_recover_init()\fR and \fBverify_recover()\fR methods are used to verify a +signature and then recover the digest from the signature (for instance, a +signature that was generated by RSA signing algorithm). They are called by +\&\fBEVP_PKEY_verify_recover_init\fR\|(3) and \fBEVP_PKEY_verify_recover\fR\|(3). +.PP +.Vb 3 +\& int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); +\& int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, +\& EVP_MD_CTX *mctx); +.Ve +.PP +The \fBsignctx_init()\fR and \fBsignctx()\fR methods are used to sign a digest present by +a \fBEVP_MD_CTX\fR object. They are called by the EVP_DigestSign functions. See +\&\fBEVP_DigestSignInit\fR\|(3) for details. +.PP +.Vb 3 +\& int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); +\& int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen, +\& EVP_MD_CTX *mctx); +.Ve +.PP +The \fBverifyctx_init()\fR and \fBverifyctx()\fR methods are used to verify a signature +against the data in a \fBEVP_MD_CTX\fR object. They are called by the various +EVP_DigestVerify functions. See \fBEVP_DigestVerifyInit\fR\|(3) for details. +.PP +.Vb 3 +\& int (*encrypt_init) (EVP_PKEY_CTX *ctx); +\& int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +.Ve +.PP +The \fBencrypt_init()\fR and \fBencrypt()\fR methods are used to encrypt a piece of data. +They are called by \fBEVP_PKEY_encrypt_init\fR\|(3) and \fBEVP_PKEY_encrypt\fR\|(3). +.PP +.Vb 3 +\& int (*decrypt_init) (EVP_PKEY_CTX *ctx); +\& int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, +\& const unsigned char *in, size_t inlen); +.Ve +.PP +The \fBdecrypt_init()\fR and \fBdecrypt()\fR methods are used to decrypt a piece of data. +They are called by \fBEVP_PKEY_decrypt_init\fR\|(3) and \fBEVP_PKEY_decrypt\fR\|(3). +.PP +.Vb 2 +\& int (*derive_init) (EVP_PKEY_CTX *ctx); +\& int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); +.Ve +.PP +The \fBderive_init()\fR and \fBderive()\fR methods are used to derive the shared secret +from a public key algorithm (for instance, the DH algorithm). They are called by +\&\fBEVP_PKEY_derive_init\fR\|(3) and \fBEVP_PKEY_derive\fR\|(3). +.PP +.Vb 2 +\& int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2); +\& int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value); +.Ve +.PP +The \fBctrl()\fR and \fBctrl_str()\fR methods are used to adjust algorithm\-specific +settings. See \fBEVP_PKEY_CTX_ctrl\fR\|(3) and related functions for details. +.PP +.Vb 5 +\& int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen, +\& const unsigned char *tbs, size_t tbslen); +\& int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig, +\& size_t siglen, const unsigned char *tbs, +\& size_t tbslen); +.Ve +.PP +The \fBdigestsign()\fR and \fBdigestverify()\fR methods are used to generate or verify +a signature in a one\-shot mode. They could be called by \fBEVP_DigestSign\fR\|(3) +and \fBEVP_DigestVerify\fR\|(3). +.PP +.Vb 3 +\& int (*check) (EVP_PKEY *pkey); +\& int (*public_check) (EVP_PKEY *pkey); +\& int (*param_check) (EVP_PKEY *pkey); +.Ve +.PP +The \fBcheck()\fR, \fBpublic_check()\fR and \fBparam_check()\fR methods are used to validate a +key\-pair, the public component and parameters respectively for a given \fBpkey\fR. +They could be called by \fBEVP_PKEY_check\fR\|(3), \fBEVP_PKEY_public_check\fR\|(3) and +\&\fBEVP_PKEY_param_check\fR\|(3) respectively. +.PP +.Vb 1 +\& int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); +.Ve +.PP +The \fBdigest_custom()\fR method is used to generate customized digest content before +the real message is passed to functions like \fBEVP_DigestSignUpdate\fR\|(3) or +\&\fBEVP_DigestVerifyInit\fR\|(3). This is usually required by some public key +signature algorithms like SM2 which requires a hashed prefix to the message to +be signed. The \fBdigest_custom()\fR function will be called by \fBEVP_DigestSignInit\fR\|(3) +and \fBEVP_DigestVerifyInit\fR\|(3). +.SS Functions +.IX Subsection "Functions" +\&\fBEVP_PKEY_meth_new()\fR creates and returns a new \fBEVP_PKEY_METHOD\fR object, +and associates the given \fBid\fR and \fBflags\fR. The following flags are +supported: +.PP +.Vb 2 +\& EVP_PKEY_FLAG_AUTOARGLEN +\& EVP_PKEY_FLAG_SIGCTX_CUSTOM +.Ve +.PP +If an \fBEVP_PKEY_METHOD\fR is set with the \fBEVP_PKEY_FLAG_AUTOARGLEN\fR flag, the +maximum size of the output buffer will be automatically calculated or checked +in corresponding EVP methods by the EVP framework. Thus the implementations of +these methods don\*(Aqt need to care about handling the case of returning output +buffer size by themselves. For details on the output buffer size, refer to +\&\fBEVP_PKEY_sign\fR\|(3). +.PP +The \fBEVP_PKEY_FLAG_SIGCTX_CUSTOM\fR is used to indicate the \fBsignctx()\fR method +of an \fBEVP_PKEY_METHOD\fR is always called by the EVP framework while doing a +digest signing operation by calling \fBEVP_DigestSignFinal\fR\|(3). +.PP +\&\fBEVP_PKEY_meth_free()\fR frees an existing \fBEVP_PKEY_METHOD\fR pointed by +\&\fBpmeth\fR. If the argument is NULL, nothing is done. +.PP +\&\fBEVP_PKEY_meth_copy()\fR copies an \fBEVP_PKEY_METHOD\fR object from \fBsrc\fR +to \fBdst\fR. +.PP +\&\fBEVP_PKEY_meth_find()\fR finds an \fBEVP_PKEY_METHOD\fR object with the \fBid\fR. +This function first searches through the user\-defined method objects and +then the built\-in objects. +.PP +\&\fBEVP_PKEY_meth_add0()\fR adds \fBpmeth\fR to the user defined stack of methods. +.PP +\&\fBEVP_PKEY_meth_remove()\fR removes an \fBEVP_PKEY_METHOD\fR object added by +\&\fBEVP_PKEY_meth_add0()\fR. +.PP +The EVP_PKEY_meth_set functions set the corresponding fields of +\&\fBEVP_PKEY_METHOD\fR structure with the arguments passed. +.PP +The EVP_PKEY_meth_get functions get the corresponding fields of +\&\fBEVP_PKEY_METHOD\fR structure to the arguments provided. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_meth_new()\fR returns a pointer to a new \fBEVP_PKEY_METHOD\fR +object or returns NULL on error. +.PP +\&\fBEVP_PKEY_meth_free()\fR and \fBEVP_PKEY_meth_copy()\fR do not return values. +.PP +\&\fBEVP_PKEY_meth_find()\fR returns a pointer to the found \fBEVP_PKEY_METHOD\fR +object or returns NULL if not found. +.PP +\&\fBEVP_PKEY_meth_add0()\fR returns 1 if method is added successfully or 0 +if an error occurred. +.PP +\&\fBEVP_PKEY_meth_remove()\fR returns 1 if method is removed successfully or +0 if an error occurred. +.PP +All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return +values. For the \*(Aqget\*(Aq functions, function pointers are returned by +arguments. +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The signature of the \fIcopy\fR functional argument of \fBEVP_PKEY_meth_set_copy()\fR +has changed in OpenSSL 3.0 so its \fIsrc\fR parameter is now constified. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_new.3 b/static/netbsd/man3/EVP_PKEY_new.3 new file mode 100644 index 00000000..d0df79b5 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_new.3 @@ -0,0 +1,352 @@ +.\" $NetBSD: EVP_PKEY_new.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_new 3" +.TH EVP_PKEY_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY, +EVP_PKEY_new, +EVP_PKEY_up_ref, +EVP_PKEY_dup, +EVP_PKEY_free, +EVP_PKEY_new_raw_private_key_ex, +EVP_PKEY_new_raw_private_key, +EVP_PKEY_new_raw_public_key_ex, +EVP_PKEY_new_raw_public_key, +EVP_PKEY_new_CMAC_key, +EVP_PKEY_new_mac_key, +EVP_PKEY_get_raw_private_key, +EVP_PKEY_get_raw_public_key +\&\- public/private key allocation and raw key handling functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef evp_pkey_st EVP_PKEY; +\& +\& EVP_PKEY *EVP_PKEY_new(void); +\& int EVP_PKEY_up_ref(EVP_PKEY *key); +\& EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key); +\& void EVP_PKEY_free(EVP_PKEY *key); +\& +\& EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx, +\& const char *keytype, +\& const char *propq, +\& const unsigned char *key, +\& size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e, +\& const unsigned char *key, size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx, +\& const char *keytype, +\& const char *propq, +\& const unsigned char *key, +\& size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e, +\& const unsigned char *key, size_t keylen); +\& EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key, +\& int keylen); +\& +\& int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv, +\& size_t *len); +\& int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub, +\& size_t *len); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv, +\& size_t len, const EVP_CIPHER *cipher); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY\fR is a generic structure to hold diverse types of asymmetric keys +(also known as "key pairs"), and can be used for diverse operations, like +signing, verifying signatures, key derivation, etc. The asymmetric keys +themselves are often referred to as the "internal key", and are handled by +backends, such as providers (through \fBEVP_KEYMGMT\fR\|(3)) or \fBENGINE\fRs. +.PP +Conceptually, an \fBEVP_PKEY\fR internal key may hold a private key, a public +key, or both (a keypair), and along with those, key parameters if the key type +requires them. The presence of these components determine what operations can +be made; for example, signing normally requires the presence of a private key, +and verifying normally requires the presence of a public key. +.PP +\&\fBEVP_PKEY\fR has also been used for MAC algorithm that were conceived as +producing signatures, although not being public key algorithms; "POLY1305", +"SIPHASH", "HMAC", "CMAC". This usage is considered legacy and is discouraged +in favor of the \fBEVP_MAC\fR\|(3) API. +.PP +The \fBEVP_PKEY_new()\fR function allocates an empty \fBEVP_PKEY\fR structure which is +used by OpenSSL to store public and private keys. The reference count is set to +\&\fB1\fR. +.PP +\&\fBEVP_PKEY_up_ref()\fR increments the reference count of \fIkey\fR. +.PP +\&\fBEVP_PKEY_dup()\fR duplicates the \fIkey\fR. The \fIkey\fR must not be ENGINE based or +a raw key, otherwise the duplication will fail. +.PP +\&\fBEVP_PKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference +count is zero, frees it up. If \fIkey\fR is NULL, nothing is done. +.PP +\&\fBEVP_PKEY_new_raw_private_key_ex()\fR allocates a new \fBEVP_PKEY\fR. Unless an +engine should be used for the key type, a provider for the key is found using +the library context \fIlibctx\fR and the property query string \fIpropq\fR. The +\&\fIkeytype\fR argument indicates what kind of key this is. The value should be a +string for a public key algorithm that supports raw private keys, e.g., one of: +\&\f(CW\*(C`ED25519\*(C'\fR, +\&\f(CW\*(C`ED448\*(C'\fR, +\&\f(CW\*(C`X25519\*(C'\fR, +\&\f(CW\*(C`X448\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-44\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-65\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-87\*(C'\fR, +\&\f(CW\*(C`ML\-KEM\-512\*(C'\fR, +\&\f(CW\*(C`ML\-KEM\-768\*(C'\fR, +or +\&\f(CW\*(C`ML\-KEM\-1024\*(C'\fR. +\&\fIkey\fR points to the raw private key +data for this \fBEVP_PKEY\fR which should be of length \fIkeylen\fR. The length +should be appropriate for the type of the key. The public key data will be +automatically derived from the given private key data (if appropriate for the +algorithm type). +.PP +\&\fBEVP_PKEY_new_raw_private_key()\fR does the same as +\&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that the default library context and +default property query are used instead. If \fIe\fR is non\-NULL then the new +\&\fBEVP_PKEY\fR structure is associated with the engine \fIe\fR. The \fItype\fR argument +indicates what kind of key this is. The value should be a NID for a public key +algorithm that supports raw private keys, i.e. one of \fBEVP_PKEY_X25519\fR, +\&\fBEVP_PKEY_ED25519\fR, \fBEVP_PKEY_X448\fR or \fBEVP_PKEY_ED448\fR. +.PP +\&\fBEVP_PKEY_new_raw_private_key_ex()\fR and \fBEVP_PKEY_new_raw_private_key()\fR may also +be used with most MACs implemented as public key algorithms, so key types such +as "HMAC", "POLY1305", "SIPHASH", or their NID form \fBEVP_PKEY_POLY1305\fR, +\&\fBEVP_PKEY_SIPHASH\fR, \fBEVP_PKEY_HMAC\fR are also accepted. This usage is, +as mentioned above, discouraged in favor of the \fBEVP_MAC\fR\|(3) API. +.PP +\&\fBEVP_PKEY_new_raw_public_key_ex()\fR works in the same way as +\&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that \fIkey\fR points to the raw +public key data. The \fBEVP_PKEY\fR structure will be initialised without any +private key information. Algorithm types that support raw public keys are +\&\fBED25519\fR, +\&\fBED448\fR, +\&\fBX25519\fR, +\&\fBX448\fR, +\&\f(CW\*(C`ML\-DSA\-44\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-65\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-87\*(C'\fR, +\&\fBML\-KEM\-512\fR, +\&\fBML\-KEM\-768\fR, +and +\&\fBML\-KEM\-1024\fR. +.PP +\&\fBEVP_PKEY_new_raw_public_key()\fR works in the same way as +\&\fBEVP_PKEY_new_raw_private_key_ex()\fR except that \fIkey\fR points to the raw public +key data. +The \fBEVP_PKEY\fR structure will be initialised without any private key +information. +.PP +\&\fBEVP_PKEY_new_mac_key()\fR works in the same way as \fBEVP_PKEY_new_raw_private_key()\fR. +New applications should use \fBEVP_PKEY_new_raw_private_key()\fR instead. +.PP +\&\fBEVP_PKEY_get_raw_private_key()\fR fills the buffer provided by \fIpriv\fR with raw +private key data. The size of the \fIpriv\fR buffer should be in \fI*len\fR on entry +to the function, and on exit \fI*len\fR is updated with the number of bytes +actually written. If the buffer \fIpriv\fR is NULL then \fI*len\fR is populated with +the number of bytes required to hold the key. The calling application is +responsible for ensuring that the buffer is large enough to receive the private +key data. This function only works for algorithms that support raw private keys. +These include: +\&\fBED25519\fR, +\&\fBED448\fR, +\&\fBX25519\fR, +\&\fBX448\fR, +\&\fBHMAC\fR, +\&\fBPOLY1305\fR, +and +\&\fBSIPHASH\fR. +\&\fBEVP_PKEY_get_raw_private_key()\fR also works with +\&\f(CW\*(C`ML\-DSA\-44\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-65\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-87\*(C'\fR, +\&\fBML\-KEM\-512\fR, +\&\fBML\-KEM\-768\fR and +\&\fBML\-KEM\-1024\fR +keys, which don\*(Aqt have legacy numeric \fINID\fR assignments, but their raw form is +nevertheless available. +.PP +\&\fBEVP_PKEY_get_raw_public_key()\fR fills the buffer provided by \fIpub\fR with raw +public key data. The size of the \fIpub\fR buffer should be in \fI*len\fR on entry +to the function, and on exit \fI*len\fR is updated with the number of bytes +actually written. If the buffer \fIpub\fR is NULL then \fI*len\fR is populated with +the number of bytes required to hold the key. The calling application is +responsible for ensuring that the buffer is large enough to receive the public +key data. This function only works for algorithms that support raw public keys. +These include: +\&\fBED25519\fR, +\&\fBED448\fR, +\&\fBX25519\fR, +and +\&\fBX448\fR +\&\fBEVP_PKEY_get_raw_public_key()\fR also works with +\&\f(CW\*(C`ML\-DSA\-44\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-65\*(C'\fR, +\&\f(CW\*(C`ML\-DSA\-87\*(C'\fR, +\&\fBML\-KEM\-512\fR, +\&\fBML\-KEM\-768\fR and +\&\fBML\-KEM\-1024\fR +keys, which don\*(Aqt have legacy numeric \fINID\fR assignments, but their raw form is +nevertheless available. +.PP +\&\fBEVP_PKEY_new_CMAC_key()\fR works in the same way as \fBEVP_PKEY_new_raw_private_key()\fR +except it is only for the \fBEVP_PKEY_CMAC\fR algorithm type. In addition to the +raw private key data, it also takes a cipher algorithm to be used during +creation of a CMAC in the \fBcipher\fR argument. The cipher should be a standard +encryption\-only cipher. For example AEAD and XTS ciphers should not be used. +.PP +Applications should use the \fBEVP_MAC\fR\|(3) API instead +and set the \fBOSSL_MAC_PARAM_CIPHER\fR parameter on the \fBEVP_MAC_CTX\fR object +with the name of the cipher being used. +.SH NOTES +.IX Header "NOTES" +The \fBEVP_PKEY\fR structure is used by various OpenSSL functions which require a +general private key without reference to any particular algorithm. +.PP +The structure returned by \fBEVP_PKEY_new()\fR is empty. To add a private or public +key to this empty structure use the appropriate functions described in +\&\fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_DSA\fR\|(3), \fBEVP_PKEY_set1_DH\fR\|(3) or +\&\fBEVP_PKEY_set1_EC_KEY\fR\|(3) for legacy key types implemented in internal +OpenSSL providers. +.PP +For fully provider\-managed key types (see \fBprovider\-keymgmt\fR\|(7)), +possibly implemented in external providers, use functions such as +\&\fBEVP_PKEY_set1_encoded_public_key\fR\|(3) or \fBEVP_PKEY_fromdata\fR\|(3) +to populate key data. +.PP +Generally caution is advised for using an \fBEVP_PKEY\fR structure across +different library contexts: In order for an \fBEVP_PKEY\fR to be shared by +multiple library contexts the providers associated with the library contexts +must have key managers that support the key type and implement the +\&\fBOSSL_FUNC_keymgmt_import()\fR and \fBOSSL_FUNC_keymgmt_export()\fR functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_new()\fR, \fBEVP_PKEY_new_raw_private_key()\fR, \fBEVP_PKEY_new_raw_public_key()\fR, +\&\fBEVP_PKEY_new_CMAC_key()\fR and \fBEVP_PKEY_new_mac_key()\fR return either the newly +allocated \fBEVP_PKEY\fR structure or NULL if an error occurred. +.PP +\&\fBEVP_PKEY_dup()\fR returns the key duplicate or NULL if an error occurred. +.PP +\&\fBEVP_PKEY_up_ref()\fR, \fBEVP_PKEY_get_raw_private_key()\fR and +\&\fBEVP_PKEY_get_raw_public_key()\fR return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_set1_RSA\fR\|(3), +\&\fBEVP_PKEY_set1_DSA\fR\|(3), +\&\fBEVP_PKEY_set1_DH\fR\|(3), +\&\fBEVP_PKEY_set1_EC_KEY\fR\|(3), +\&\fBEVP_PKEY\-ED25519\fR\|(7), +\&\fBEVP_PKEY\-ED448\fR\|(7). +\&\fBEVP_PKEY\-HMAC\fR\|(7), +\&\fBEVP_PKEY\-Poly1305\fR\|(7), +\&\fBEVP_PKEY\-Siphash\fR\|(7), +\&\fBEVP_PKEY\-X25519\fR\|(7), +\&\fBEVP_PKEY\-X448\fR\|(7), +\&\fBEVP_PKEY\-ML\-DSA\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +The +\&\fBEVP_PKEY_new()\fR and \fBEVP_PKEY_free()\fR functions exist in all versions of OpenSSL. +.PP +The \fBEVP_PKEY_up_ref()\fR function was added in OpenSSL 1.1.0. +.PP +The +\&\fBEVP_PKEY_new_raw_private_key()\fR, \fBEVP_PKEY_new_raw_public_key()\fR, +\&\fBEVP_PKEY_new_CMAC_key()\fR, \fBEVP_PKEY_new_raw_private_key()\fR and +\&\fBEVP_PKEY_get_raw_public_key()\fR functions were added in OpenSSL 1.1.1. +.PP +The \fBEVP_PKEY_dup()\fR, \fBEVP_PKEY_new_raw_private_key_ex()\fR, and +\&\fBEVP_PKEY_new_raw_public_key_ex()\fR +functions were added in OpenSSL 3.0. +.PP +The \fBEVP_PKEY_new_CMAC_key()\fR was deprecated in OpenSSL 3.0. +.PP +The documentation of \fBEVP_PKEY\fR was amended in OpenSSL 3.0 to allow there to +be the private part of the keypair without the public part, where this was +previously implied to be disallowed. +.PP +Support for \fBML\-DSA\fR and \fBML\-KEM\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_print_private.3 b/static/netbsd/man3/EVP_PKEY_print_private.3 new file mode 100644 index 00000000..533a575d --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_print_private.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: EVP_PKEY_print_private.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_print_private 3" +.TH EVP_PKEY_print_private 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params, +EVP_PKEY_print_public_fp, EVP_PKEY_print_private_fp, +EVP_PKEY_print_params_fp \- public key algorithm printing routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +\& int EVP_PKEY_print_public_fp(FILE *fp, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +\& int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +\& int EVP_PKEY_print_private_fp(FILE *fp, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +\& int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +\& int EVP_PKEY_print_params_fp(FILE *fp, const EVP_PKEY *pkey, +\& int indent, ASN1_PCTX *pctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions \fBEVP_PKEY_print_public()\fR, \fBEVP_PKEY_print_private()\fR and +\&\fBEVP_PKEY_print_params()\fR print out the public, private or parameter components +of key \fIpkey\fR respectively. The key is sent to \fBBIO\fR \fIout\fR in human readable +form. The parameter \fIindent\fR indicates how far the printout should be indented. +.PP +The \fIpctx\fR parameter allows the print output to be finely tuned by using +ASN1 printing options. If \fIpctx\fR is set to NULL then default values will +be used. +.PP +The functions \fBEVP_PKEY_print_public_fp()\fR, \fBEVP_PKEY_print_private_fp()\fR and +\&\fBEVP_PKEY_print_params_fp()\fR do the same as the \fBBIO\fR based functions +but use \fBFILE\fR \fIfp\fR instead. +.SH NOTES +.IX Header "NOTES" +Currently no public key algorithms include any options in the \fIpctx\fR parameter. +.PP +If the key does not include all the components indicated by the function then +only those contained in the key will be printed. For example passing a public +key to \fBEVP_PKEY_print_private()\fR will only print the public components. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions all return 1 for success and 0 or a negative value for failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_keygen\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBEVP_PKEY_print_public()\fR, \fBEVP_PKEY_print_private()\fR, +and \fBEVP_PKEY_print_params()\fR were added in OpenSSL 1.0.0. +.PP +The functions \fBEVP_PKEY_print_public_fp()\fR, \fBEVP_PKEY_print_private_fp()\fR, +and \fBEVP_PKEY_print_params_fp()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_set1_RSA.3 b/static/netbsd/man3/EVP_PKEY_set1_RSA.3 new file mode 100644 index 00000000..0cf49685 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_set1_RSA.3 @@ -0,0 +1,296 @@ +.\" $NetBSD: EVP_PKEY_set1_RSA.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_set1_RSA 3" +.TH EVP_PKEY_set1_RSA 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, +EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, +EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, +EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, +EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, +EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, +EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id, +EVP_PKEY_set1_engine, EVP_PKEY_get0_engine, +EVP_PKEY_id, EVP_PKEY_base_id \- +EVP_PKEY assignment functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_get_id(const EVP_PKEY *pkey); +\& int EVP_PKEY_get_base_id(const EVP_PKEY *pkey); +\& int EVP_PKEY_type(int type); +\& +\& #define EVP_PKEY_id EVP_PKEY_get_id +\& #define EVP_PKEY_base_id EVP_PKEY_get_base_id +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); +\& int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); +\& int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key); +\& int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); +\& +\& RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); +\& DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); +\& DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); +\& EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); +\& +\& const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); +\& const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len); +\& const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len); +\& const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey); +\& const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey); +\& const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey); +\& const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey); +\& void *EVP_PKEY_get0(const EVP_PKEY *pkey); +\& +\& int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); +\& int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); +\& int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); +\& int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); +\& int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); +\& int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key); +\& +\& ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey); +\& int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_get_base_id()\fR returns the type of \fIpkey\fR. For example +an RSA key will return \fBEVP_PKEY_RSA\fR. +.PP +\&\fBEVP_PKEY_get_id()\fR returns the actual NID associated with \fIpkey\fR +only if the \fIpkey\fR type isn\*(Aqt implemented just in a \fBprovider\fR\|(7). +Historically keys using the same algorithm could use different NIDs. +For example an RSA key could use the NIDs corresponding to +the NIDs \fBNID_rsaEncryption\fR (equivalent to \fBEVP_PKEY_RSA\fR) or +\&\fBNID_rsa\fR (equivalent to \fBEVP_PKEY_RSA2\fR). The use of +alternative non\-standard NIDs is now rare so \fBEVP_PKEY_RSA2\fR et al are not +often seen in practice. +\&\fBEVP_PKEY_get_id()\fR returns \-1 (\fBEVP_PKEY_KEYMGMT\fR) if the \fIpkey\fR is +only implemented in a \fBprovider\fR\|(7). +.PP +\&\fBEVP_PKEY_type()\fR returns the underlying type of the NID \fItype\fR. For example +EVP_PKEY_type(EVP_PKEY_RSA2) will return \fBEVP_PKEY_RSA\fR. +.PP +\&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and +\&\fBEVP_PKEY_set1_EC_KEY()\fR set the key referenced by \fIpkey\fR to \fIkey\fR. These +functions are deprecated. Applications should instead use +\&\fBEVP_PKEY_fromdata\fR\|(3). +.PP +\&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR, +\&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR and +\&\fBEVP_PKEY_assign_SIPHASH()\fR set the referenced key to \fIkey\fR however these use +the supplied \fIkey\fR internally and so \fIkey\fR will be freed when the parent +\&\fIpkey\fR is freed. These macros are deprecated. Applications should instead read +an EVP_PKEY directly using the OSSL_DECODER APIs (see +\&\fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3)), or construct an EVP_PKEY from data using +\&\fBEVP_PKEY_fromdata\fR\|(3). +.PP +\&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and +\&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key in \fIpkey\fR or NULL if the +key is not of the correct type. The returned key must be freed after use. +These functions are deprecated. Applications should instead use the EVP_PKEY +directly where possible. If access to the low level key parameters is required +then applications should use \fBEVP_PKEY_get_params\fR\|(3) and other similar +functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see +\&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3)). +.PP +\&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR, +\&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR and +\&\fBEVP_PKEY_get0_EC_KEY()\fR return the referenced key in \fIpkey\fR or NULL if the +key is not of the correct type. The reference count of the returned key is +\&\fBnot\fR incremented and so the key must not be freed after use. These functions +are deprecated. Applications should instead use the EVP_PKEY directly where +possible. If access to the low level key parameters is required then +applications should use \fBEVP_PKEY_get_params\fR\|(3) and other similar functions. +To write an EVP_PKEY out use the OSSL_ENCODER APIs (see +\&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3)). \fBEVP_PKEY_get0()\fR returns a pointer to the +legacy key or NULL if the key is not legacy. +.PP +Note that if an EVP_PKEY was not constructed using one of the deprecated +functions such as \fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR +or \fBEVP_PKEY_set1_EC_KEY()\fR, or via the similarly named \fBEVP_PKEY_assign\fR macros +described above then the internal key will be managed by a provider (see +\&\fBprovider\fR\|(7)). In that case the key returned by \fBEVP_PKEY_get1_RSA()\fR, +\&\fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR, \fBEVP_PKEY_get1_EC_KEY()\fR, +\&\fBEVP_PKEY_get0_hmac()\fR, \fBEVP_PKEY_get0_poly1305()\fR, \fBEVP_PKEY_get0_siphash()\fR, +\&\fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, \fBEVP_PKEY_get0_DH()\fR or +\&\fBEVP_PKEY_get0_EC_KEY()\fR will be a cached copy of the provider\*(Aqs key. Subsequent +updates to the provider\*(Aqs key will not be reflected back in the cached copy, and +updates made by an application to the returned key will not be reflected back in +the provider\*(Aqs key. Subsequent calls to \fBEVP_PKEY_get1_RSA()\fR, +\&\fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and \fBEVP_PKEY_get1_EC_KEY()\fR will always +return the cached copy returned by the first call. +.PP +\&\fBEVP_PKEY_get0_engine()\fR returns a reference to the ENGINE handling \fIpkey\fR. This +function is deprecated. Applications should use providers instead of engines +(see \fBprovider\fR\|(7) for details). +.PP +\&\fBEVP_PKEY_set1_engine()\fR sets the ENGINE handling \fIpkey\fR to \fIengine\fR. It +must be called after the key algorithm and components are set up. +If \fIengine\fR does not include an \fBEVP_PKEY_METHOD\fR for \fIpkey\fR an +error occurs. This function is deprecated. Applications should use providers +instead of engines (see \fBprovider\fR\|(7) for details). +.SH WARNINGS +.IX Header "WARNINGS" +The following functions are only reliable with \fBEVP_PKEY\fRs that have +been assigned an internal key with EVP_PKEY_assign_*(): +.PP +\&\fBEVP_PKEY_get_id()\fR, \fBEVP_PKEY_get_base_id()\fR, \fBEVP_PKEY_type()\fR +.PP +For EVP_PKEY key type checking purposes, \fBEVP_PKEY_is_a\fR\|(3) is more generic. +.PP +For purposes of retrieving the name of the \fBEVP_PKEY\fR the function +\&\fBEVP_PKEY_get0_type_name\fR\|(3) is more generally useful. +.PP +The keys returned from the functions \fBEVP_PKEY_get0_RSA()\fR, \fBEVP_PKEY_get0_DSA()\fR, +\&\fBEVP_PKEY_get0_DH()\fR and \fBEVP_PKEY_get0_EC_KEY()\fR were changed to have a "const" +return type in OpenSSL 3.0. As described above the keys returned may be cached +copies of the key held in a provider. Due to this, and unlike in earlier +versions of OpenSSL, they should be considered read\-only copies of the key. +Updates to these keys will not be reflected back in the provider side key. The +\&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and +\&\fBEVP_PKEY_get1_EC_KEY()\fR functions were not changed to have a "const" return type +in order that applications can "free" the return value. However applications +should still consider them as read\-only copies. +.SH NOTES +.IX Header "NOTES" +In accordance with the OpenSSL naming convention the key obtained +from or assigned to the \fIpkey\fR using the \fB1\fR functions must be +freed as well as \fIpkey\fR. +.PP +\&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR, +\&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR +and \fBEVP_PKEY_assign_SIPHASH()\fR are implemented as macros. +.PP +\&\fBEVP_PKEY_assign_EC_KEY()\fR looks at the curve name id to determine if +the passed \fBEC_KEY\fR is an \fBSM2\fR\|(7) key, and will set the \fBEVP_PKEY\fR +type to \fBEVP_PKEY_SM2\fR in that case, instead of \fBEVP_PKEY_EC\fR. +.PP +Most applications wishing to know a key type will simply call +\&\fBEVP_PKEY_get_base_id()\fR and will not care about the actual type: +which will be identical in almost all cases. +.PP +Previous versions of this document suggested using EVP_PKEY_type(pkey\->type) +to determine the type of a key. Since \fBEVP_PKEY\fR is now opaque this +is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey). +.PP +\&\fBEVP_PKEY_set1_engine()\fR is typically used by an ENGINE returning an HSM +key as part of its routine to load a private key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_set1_RSA()\fR, \fBEVP_PKEY_set1_DSA()\fR, \fBEVP_PKEY_set1_DH()\fR and +\&\fBEVP_PKEY_set1_EC_KEY()\fR return 1 for success or 0 for failure. +.PP +\&\fBEVP_PKEY_get1_RSA()\fR, \fBEVP_PKEY_get1_DSA()\fR, \fBEVP_PKEY_get1_DH()\fR and +\&\fBEVP_PKEY_get1_EC_KEY()\fR return the referenced key or NULL if +an error occurred. +.PP +\&\fBEVP_PKEY_assign_RSA()\fR, \fBEVP_PKEY_assign_DSA()\fR, \fBEVP_PKEY_assign_DH()\fR, +\&\fBEVP_PKEY_assign_EC_KEY()\fR, \fBEVP_PKEY_assign_POLY1305()\fR +and \fBEVP_PKEY_assign_SIPHASH()\fR return 1 for success and 0 for failure. +.PP +\&\fBEVP_PKEY_get_base_id()\fR, \fBEVP_PKEY_get_id()\fR and \fBEVP_PKEY_type()\fR return a key +type or \fBNID_undef\fR (equivalently \fBEVP_PKEY_NONE\fR) on error. +.PP +\&\fBEVP_PKEY_set1_engine()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), \fBSM2\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_id()\fR and \fBEVP_PKEY_base_id()\fR functions were renamed to +include \f(CW\*(C`get\*(C'\fR in their names in OpenSSL 3.0, respectively. The old names +are kept as non\-deprecated alias macros. +.PP +EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, +EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, +EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, +EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, +EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, +EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, +EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were deprecated in OpenSSL 3.0. +.PP +The return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, +EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0. +.PP +The function \fBEVP_PKEY_set_alias_type()\fR was previously documented on this page. +It was removed in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_set1_encoded_public_key.3 b/static/netbsd/man3/EVP_PKEY_set1_encoded_public_key.3 new file mode 100644 index 00000000..3fa9184a --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_set1_encoded_public_key.3 @@ -0,0 +1,217 @@ +.\" $NetBSD: EVP_PKEY_set1_encoded_public_key.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_set1_encoded_public_key 3" +.TH EVP_PKEY_set1_encoded_public_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_set1_encoded_public_key, EVP_PKEY_get1_encoded_public_key, +EVP_PKEY_set1_tls_encodedpoint, EVP_PKEY_get1_tls_encodedpoint +\&\- functions to set and get public key data within an EVP_PKEY +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_set1_encoded_public_key(EVP_PKEY *pkey, +\& const unsigned char *pub, size_t publen); +\& +\& size_t EVP_PKEY_get1_encoded_public_key(EVP_PKEY *pkey, unsigned char **ppub); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int EVP_PKEY_set1_tls_encodedpoint(EVP_PKEY *pkey, +\& const unsigned char *pt, size_t ptlen); +\& +\& size_t EVP_PKEY_get1_tls_encodedpoint(EVP_PKEY *pkey, unsigned char **ppt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_set1_encoded_public_key()\fR can be used to set the public key value +within an existing EVP_PKEY object, which does not yet have either a public or +private key assigned. +For the built\-in OpenSSL algorithms this currently only works for those that +support key exchange or key encapsulation. +Parameters are not set as part of this operation, so typically an application +will create an EVP_PKEY first, set the parameters on it, and then call this +function. +For example setting the parameters might be done using +\&\fBEVP_PKEY_copy_parameters\fR\|(3). +.PP +The format for the encoded public key will depend on the algorithm in use. For +DH it should be encoded as a positive integer in big\-endian form. For EC is +should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic +Curve Cryptography") standard. For \fBX25519\fR and \fBX448\fR it should be encoded +in the format defined by RFC7748. +For \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR and \fBML\-KEM\-1024\fR, this is the public key +format defined in \fBFIPS 203\fR (the 12\-bit per\-coefficient encoded public \fIt\fR +vector and 32\-byte matrix seed \fIrho\fR). +.PP +The key to be updated is supplied in \fBpkey\fR. The buffer containing the encoded +key is pointed to be \fBpub\fR. The length of the buffer is supplied in \fBpublen\fR. +.PP +\&\fBEVP_PKEY_get1_encoded_public_key()\fR does the equivalent operation except that +the encoded public key is returned to the application. The key containing the +public key data is supplied in \fBpkey\fR. A buffer containing the encoded key will +be allocated and stored in \fB*ppub\fR. The length of the encoded public key is +returned by the function. The application is responsible for freeing the +allocated buffer. +.PP +The macro \fBEVP_PKEY_set1_tls_encodedpoint()\fR is deprecated and simply calls +\&\fBEVP_PKEY_set1_encoded_public_key()\fR with all the same arguments. New applications +should use \fBEVP_PKEY_set1_encoded_public_key()\fR instead. +.PP +The macro \fBEVP_PKEY_get1_tls_encodedpoint()\fR is deprecated and simply calls +\&\fBEVP_PKEY_get1_encoded_public_key()\fR with all the same arguments. New applications +should use \fBEVP_PKEY_get1_encoded_public_key()\fR instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_set1_encoded_public_key()\fR returns 1 for success and 0 or a negative +value for failure. +.PP +\&\fBEVP_PKEY_get1_encoded_public_key()\fR returns the length of the encoded key or 0 for failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +See \fBEVP_PKEY_derive_init\fR\|(3) and \fBEVP_PKEY_derive\fR\|(3) for information about +performing a key exchange operation. +.SS "Set up a peer\*(Aqs EVP_PKEY ready for a key exchange operation" +.IX Subsection "Set up a peer's EVP_PKEY ready for a key exchange operation" +.Vb 1 +\& #include +\& +\& int exchange(EVP_PKEY *ourkey, unsigned char *peer_pub, size_t peer_pub_len) +\& { +\& EVP_PKEY *peerkey = EVP_PKEY_new(); +\& +\& if (peerkey == NULL || EVP_PKEY_copy_parameters(peerkey, ourkey) <= 0) +\& return 0; +\& +\& if (EVP_PKEY_set1_encoded_public_key(peerkey, peer_pub, +\& peer_pub_len) <= 0) +\& return 0; +\& +\& /* Do the key exchange here */ +\& +\& EVP_PKEY_free(peerkey); +\& +\& return 1; +\& } +.Ve +.SS "Get an encoded public key to send to a peer" +.IX Subsection "Get an encoded public key to send to a peer" +.Vb 1 +\& #include +\& +\& int get_encoded_pub_key(EVP_PKEY *ourkey) +\& { +\& unsigned char *pubkey; +\& size_t pubkey_len; +\& +\& pubkey_len = EVP_PKEY_get1_encoded_public_key(ourkey, &pubkey); +\& if (pubkey_len == 0) +\& return 0; +\& +\& /* +\& * Send the encoded public key stored in the buffer at "pubkey" and of +\& * length pubkey_len, to the peer. +\& */ +\& +\& OPENSSL_free(pubkey); +\& return 1; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_new\fR\|(3), +\&\fBEVP_PKEY_copy_parameters\fR\|(3), +\&\fBEVP_PKEY_derive_init\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-EC\fR\|(7), +\&\fBEVP_PKEY\-X25519\fR\|(7), +\&\fBEVP_PKEY\-X448\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\-512\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\-768\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\-1024\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_PKEY_set1_encoded_public_key()\fR and \fBEVP_PKEY_get1_encoded_public_key()\fR were +added in OpenSSL 3.0. +.PP +\&\fBEVP_PKEY_set1_tls_encodedpoint()\fR and \fBEVP_PKEY_get1_tls_encodedpoint()\fR were +deprecated in OpenSSL 3.0. +.PP +Support for \fBML\-KEM\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_set_type.3 b/static/netbsd/man3/EVP_PKEY_set_type.3 new file mode 100644 index 00000000..c7448bc7 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_set_type.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: EVP_PKEY_set_type.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_set_type 3" +.TH EVP_PKEY_set_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_set_type, EVP_PKEY_set_type_str, EVP_PKEY_set_type_by_keymgmt +\&\- functions to change the EVP_PKEY type +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_set_type(EVP_PKEY *pkey, int type); +\& int EVP_PKEY_set_type_str(EVP_PKEY *pkey, const char *str, int len); +\& int EVP_PKEY_set_type_by_keymgmt(EVP_PKEY *pkey, EVP_KEYMGMT *keymgmt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All the functions described here behave the same in so far that they +clear all the previous key data and methods from \fIpkey\fR, and reset it +to be of the type of key given by the different arguments. If +\&\fIpkey\fR is NULL, these functions will still return the same return +values as if it wasn\*(Aqt. +.PP +\&\fBEVP_PKEY_set_type()\fR initialises \fIpkey\fR to contain an internal legacy +key. When doing this, it finds a \fBEVP_PKEY_ASN1_METHOD\fR\|(3) +corresponding to \fItype\fR, and associates \fIpkey\fR with the findings. +It is an error if no \fBEVP_PKEY_ASN1_METHOD\fR\|(3) could be found for +\&\fItype\fR. +.PP +\&\fBEVP_PKEY_set_type_str()\fR initialises \fIpkey\fR to contain an internal legacy +key. When doing this, it finds a \fBEVP_PKEY_ASN1_METHOD\fR\|(3) +corresponding to \fIstr\fR that has then length \fIlen\fR, and associates +\&\fIpkey\fR with the findings. +It is an error if no \fBEVP_PKEY_ASN1_METHOD\fR\|(3) could be found for +\&\fItype\fR. +.PP +For both \fBEVP_PKEY_set_type()\fR and \fBEVP_PKEY_set_type_str()\fR, \fIpkey\fR gets +a numeric type, which can be retrieved with \fBEVP_PKEY_get_id\fR\|(3). This +numeric type is taken from the \fBEVP_PKEY_ASN1_METHOD\fR\|(3) that was +found, and is equal to or closely related to \fItype\fR in the case of +\&\fBEVP_PKEY_set_type()\fR, or related to \fIstr\fR in the case of +\&\fBEVP_PKEY_set_type_str()\fR. +.PP +\&\fBEVP_PKEY_set_type_by_keymgmt()\fR initialises \fIpkey\fR to contain an +internal provider side key. When doing this, it associates \fIpkey\fR +with \fIkeymgmt\fR. For keys initialised like this, the numeric type +retrieved with \fBEVP_PKEY_get_id\fR\|(3) will always be \fBEVP_PKEY_NONE\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions described here return 1 if successful, or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_assign\fR\|(3), \fBEVP_PKEY_get_id\fR\|(3), \fBEVP_PKEY_get0_RSA\fR\|(3), +\&\fBEVP_PKEY_copy_parameters\fR\|(3), \fBEVP_PKEY_ASN1_METHOD\fR\|(3), +\&\fBEVP_KEYMGMT\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_settable_params.3 b/static/netbsd/man3/EVP_PKEY_settable_params.3 new file mode 100644 index 00000000..0d4feb48 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_settable_params.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: EVP_PKEY_settable_params.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_settable_params 3" +.TH EVP_PKEY_settable_params 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_settable_params, EVP_PKEY_set_params, +EVP_PKEY_set_int_param, EVP_PKEY_set_size_t_param, EVP_PKEY_set_bn_param, +EVP_PKEY_set_utf8_string_param, EVP_PKEY_set_octet_string_param +\&\- set key parameters into a key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const OSSL_PARAM *EVP_PKEY_settable_params(const EVP_PKEY *pkey); +\& int EVP_PKEY_set_params(EVP_PKEY *pkey, OSSL_PARAM params[]); +\& int EVP_PKEY_set_int_param(EVP_PKEY *pkey, const char *key_name, int in); +\& int EVP_PKEY_set_size_t_param(EVP_PKEY *pkey, const char *key_name, size_t in); +\& int EVP_PKEY_set_bn_param(EVP_PKEY *pkey, const char *key_name, +\& const BIGNUM *bn); +\& int EVP_PKEY_set_utf8_string_param(EVP_PKEY *pkey, const char *key_name, +\& const char *str); +\& int EVP_PKEY_set_octet_string_param(EVP_PKEY *pkey, const char *key_name, +\& const unsigned char *buf, size_t bsize); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions can be used to set additional parameters into an existing +\&\fBEVP_PKEY\fR. +.PP +\&\fBEVP_PKEY_set_params()\fR sets one or more \fIparams\fR into a \fIpkey\fR. +See \fBOSSL_PARAM\fR\|(3) for information about parameters. +.PP +\&\fBEVP_PKEY_settable_params()\fR returns a constant list of \fIparams\fR indicating +the names and types of key parameters that can be set. +See \fBOSSL_PARAM\fR\|(3) for information about parameters. +.PP +\&\fBEVP_PKEY_set_int_param()\fR sets an integer value \fIin\fR into a key \fIpkey\fR for the +associated field \fIkey_name\fR. +.PP +\&\fBEVP_PKEY_set_size_t_param()\fR sets an size_t value \fIin\fR into a key \fIpkey\fR for +the associated field \fIkey_name\fR. +.PP +\&\fBEVP_PKEY_set_bn_param()\fR sets the BIGNUM value \fIbn\fR into a key \fIpkey\fR for the +associated field \fIkey_name\fR. +.PP +\&\fBEVP_PKEY_set_utf8_string_param()\fR sets the UTF8 string \fIstr\fR into a key \fIpkey\fR +for the associated field \fIkey_name\fR. +.PP +\&\fBEVP_PKEY_set_octet_string_param()\fR sets the octet string value \fIbuf\fR with a +size \fIbsize\fR into a key \fIpkey\fR for the associated field \fIkey_name\fR. +.SH NOTES +.IX Header "NOTES" +These functions only work for \fBEVP_PKEY\fRs that contain a provider side key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_settable_params()\fR returns NULL on error or if it is not supported, +.PP +All other methods return 1 if a value was successfully set, or 0 if +there was an error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_gettable_params\fR\|(3), +\&\fBEVP_PKEY_CTX_new\fR\|(3), \fBprovider\-keymgmt\fR\|(7), \fBOSSL_PARAM\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_sign.3 b/static/netbsd/man3/EVP_PKEY_sign.3 new file mode 100644 index 00000000..24b85237 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_sign.3 @@ -0,0 +1,411 @@ +.\" $NetBSD: EVP_PKEY_sign.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_sign 3" +.TH EVP_PKEY_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init_ex2, +EVP_PKEY_sign, EVP_PKEY_sign_message_init, EVP_PKEY_sign_message_update, +EVP_PKEY_sign_message_final \- sign using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_sign_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_sign_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_sign_message_update(EVP_PKEY_CTX *ctx, +\& unsigned char *in, size_t inlen); +\& int EVP_PKEY_sign_message_final(EVP_PKEY_CTX *ctx, unsigned char *sig, +\& size_t *siglen, size_t sigsize); +\& int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, +\& unsigned char *sig, size_t *siglen, +\& const unsigned char *tbs, size_t tbslen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_sign_init()\fR initializes a public key algorithm context \fIctx\fR for +signing using the algorithm given when the context was created +using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to +fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) +for more information about implicit fetches. +.PP +\&\fBEVP_PKEY_sign_init_ex()\fR is the same as \fBEVP_PKEY_sign_init()\fR but additionally +sets the passed parameters \fIparams\fR on the context before returning. +.PP +\&\fBEVP_PKEY_sign_init_ex2()\fR initializes a public key algorithm context \fIctx\fR for +signing a pre\-computed message digest using the algorithm given by \fIalgo\fR and +the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +A context \fIctx\fR without a pre\-loaded key cannot be used with this function. +This function provides almost the same functionality as \fBEVP_PKEY_sign_init_ex()\fR, +but is uniquely intended to be used with a pre\-computed message digest, and +allows pre\-determining the exact conditions for that message digest, if a +composite signature algorithm (such as RSA\-SHA256) was fetched. +Following a call to this function, setting parameters that modifies the digest +implementation or padding is not normally supported. +.PP +\&\fBEVP_PKEY_sign_message_init()\fR initializes a public key algorithm context \fIctx\fR +for signing an unlimited size message using the algorithm given by \fIalgo\fR and +the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +Passing the message is supported both in a one\-shot fashion using +\&\fBEVP_PKEY_sign()\fR, and through the combination of \fBEVP_PKEY_sign_message_update()\fR +and \fBEVP_PKEY_sign_message_final()\fR. +This function enables using algorithms that can process input of arbitrary +length, such as ED25519, RSA\-SHA256 and similar. +.PP +\&\fBEVP_PKEY_sign_message_update()\fR adds \fIinlen\fR bytes from \fIin\fR to the data to be +processed for signature. The signature algorithm specification and +implementation determine how the input bytes are processed and if there\*(Aqs a +limit on the total size of the input. See "NOTES" below for a deeper +explanation. +.PP +\&\fBEVP_PKEY_sign_message_final()\fR signs the processed data and places the data in +\&\fIsig\fR, and the number of signature bytes in \fI*siglen\fR, if the number of +bytes doesn\*(Aqt surpass the size given by \fIsigsize\fR. +\&\fIsig\fR may be NULL, and in that case, only \fI*siglen\fR is updated with the +number of signature bytes. +.PP +\&\fBEVP_PKEY_sign()\fR is a one\-shot function that can be used with all the init +functions above. +When initialization was done with \fBEVP_PKEY_sign_init()\fR, \fBEVP_PKEY_sign_init_ex()\fR +or \fBEVP_PKEY_sign_init_ex2()\fR, the data specified by \fItbs\fR and \fItbslen\fR is +signed after appropriate padding. +When initialization was done with \fBEVP_PKEY_sign_message_init()\fR, the data +specified by \fItbs\fR and \fItbslen\fR is digested by the implied message digest +algorithm, and the result is signed after appropriate padding. +If \fIsig\fR is NULL then the maximum size of the output buffer is written to the +\&\fIsiglen\fR parameter. +If \fIsig\fR is not NULL, then before the call the \fIsiglen\fR parameter should +contain the length of the \fIsig\fR buffer, and if the call is successful the +signature is written to \fIsig\fR and the amount of data written to \fIsiglen\fR. +.SH NOTES +.IX Header "NOTES" +.SS General +.IX Subsection "General" +Some signature implementations only accumulate the input data and do no +further processing before signing it (they expect the input to be a digest), +while others compress the data, typically by internally producing a digest, +and signing the result. +Some of them support both modes of operation at the same time. +The caller is expected to know how the chosen algorithm is supposed to behave +and under what conditions. +.PP +For example, an RSA implementation can be expected to only expect a message +digest as input, while ED25519 can be expected to process the input with a hash, +i.e. to produce the message digest internally, and while RSA\-SHA256 can be +expected to handle either mode of operation, depending on if the operation was +initialized with \fBEVP_PKEY_sign_init_ex2()\fR or with \fBEVP_PKEY_sign_message_init()\fR. +.PP +Similarly, an RSA implementation usually expects additional details to be set, +like the message digest algorithm that the input is supposed to be digested +with, as well as the padding mode (see \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and +\&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256 +implementation usually has these details pre\-set and immutable. +.PP +The functions described here can\*(Aqt be used to combine separate algorithms. In +particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR +parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) can be used to combine a +signature algorithm with a hash algorithm to process the input. In other +words, it\*(Aqs not possible to specify a \fIctx\fR pre\-loaded with an RSA pkey, or +an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the +functionality of RSA\-SHA256. If combining algorithms in that manner is +desired, please use \fBEVP_DigestSignInit\fR\|(3) and associated functions. +.SS "Performing multiple signatures" +.IX Subsection "Performing multiple signatures" +When initialized using \fBEVP_PKEY_sign_init_ex()\fR or \fBEVP_PKEY_sign_init_ex2()\fR, +\&\fBEVP_PKEY_sign()\fR can be called more than once on the same context to have +several one\-shot operations performed using the same parameters. +.PP +When initialized using \fBEVP_PKEY_sign_message_init()\fR, it\*(Aqs not possible to +call \fBEVP_PKEY_sign()\fR multiple times. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 for success and 0 or a negative value for failure. +.PP +In particular, \fBEVP_PKEY_sign_init()\fR and its other variants may return \-2 to +indicate that the operation is not supported by the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "RSA with PKCS#1 padding for SHA256" +.IX Subsection "RSA with PKCS#1 padding for SHA256" +Sign data using RSA with PKCS#1 padding and a SHA256 digest as input: +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* md is a SHA\-256 digest in this example. */ +\& unsigned char *md, *sig; +\& size_t mdlen = 32, siglen; +\& EVP_PKEY *signing_key; +\& +\& /* +\& * NB: assumes signing_key and md are set up before the next +\& * step. signing_key must be an RSA private key and md must +\& * point to the SHA\-256 digest to be signed. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& if (ctx == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_sign_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) +\& /* Error */ +\& +\& sig = OPENSSL_malloc(siglen); +\& +\& if (sig == NULL) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) +\& /* Error */ +\& +\& /* Signature is siglen bytes written to buffer sig */ +.Ve +.SS "RSA\-SHA256 with a pre\-computed digest" +.IX Subsection "RSA-SHA256 with a pre-computed digest" +Sign a digest with RSA\-SHA256 using one\-shot functions. To be noted is that +RSA\-SHA256 is assumed to be an implementation of \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, +for which the padding is pre\-determined to be \fBRSA_PKCS1_PADDING\fR, and the +input digest is assumed to have been computed using SHA256. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* md is a SHA\-256 digest in this example. */ +\& unsigned char *md, *sig; +\& size_t mdlen = 32, siglen; +\& EVP_PKEY *signing_key; +\& +\& /* +\& * NB: assumes signing_key and md are set up before the next +\& * step. signing_key must be an RSA private key and md must +\& * point to the SHA\-256 digest to be signed. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_sign_init_ex2(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) +\& /* Error */ +\& +\& sig = OPENSSL_malloc(siglen); +\& +\& if (sig == NULL) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) +\& /* Error */ +\& +\& /* Signature is siglen bytes written to buffer sig */ +.Ve +.SS "RSA\-SHA256, one\-shot" +.IX Subsection "RSA-SHA256, one-shot" +Sign a document with RSA\-SHA256 using one\-shot functions. +To be noted is that RSA\-SHA256 is assumed to be an implementation of +\&\f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, for which the padding is pre\-determined to be +\&\fBRSA_PKCS1_PADDING\fR. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* in is the input in this example. */ +\& unsigned char *in, *sig; +\& /* inlen is the length of the input in this example. */ +\& size_t inlen, siglen; +\& EVP_PKEY *signing_key; +\& EVP_SIGNATURE *alg; +\& +\& /* +\& * NB: assumes signing_key, in and inlen are set up before +\& * the next step. signing_key must be an RSA private key, +\& * in must point to data to be digested and signed, and +\& * inlen must be the size of the data in bytes. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL || alg == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& /* Determine sig buffer length */ +\& if (EVP_PKEY_sign(ctx, NULL, &siglen, in, inlen) <= 0) +\& /* Error */ +\& +\& sig = OPENSSL_malloc(siglen); +\& +\& if (sig == NULL) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_sign(ctx, sig, &siglen, in, inlen) <= 0) +\& /* Error */ +\& +\& /* Signature is siglen bytes written to buffer sig */ +.Ve +.SS "RSA\-SHA256, using update and final" +.IX Subsection "RSA-SHA256, using update and final" +This is the same as the previous example, but allowing stream\-like +functionality. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* in is the input in this example. */ +\& unsigned char *in, *sig; +\& /* inlen is the length of the input in this example. */ +\& size_t inlen, siglen; +\& EVP_PKEY *signing_key; +\& EVP_SIGNATURE *alg; +\& +\& /* +\& * NB: assumes signing_key, in and inlen are set up before +\& * the next step. signing_key must be an RSA private key, +\& * in must point to data to be digested and signed, and +\& * inlen must be the size of the data in bytes. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL || alg == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& while (inlen > 0) { +\& if (EVP_PKEY_sign_message_update(ctx, in, inlen)) <= 0) +\& /* Error */ +\& if (inlen > 256) { +\& inlen \-= 256; +\& in += 256; +\& } else { +\& inlen = 0; +\& } +\& } +\& +\& /* Determine sig buffer length */ +\& if (EVP_PKEY_sign_message_final(ctx, NULL, &siglen) <= 0) +\& /* Error */ +\& +\& sig = OPENSSL_malloc(siglen); +\& +\& if (sig == NULL) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_sign_message_final(ctx, sig, &siglen) <= 0) +\& /* Error */ +\& +\& /* Signature is siglen bytes written to buffer sig */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_CTX_ctrl\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_sign_init()\fR and \fBEVP_PKEY_sign()\fR functions were added in +OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_sign_init_ex()\fR function was added in OpenSSL 3.0. +.PP +The \fBEVP_PKEY_sign_init_ex2()\fR, \fBEVP_PKEY_sign_message_init()\fR, +\&\fBEVP_PKEY_sign_message_update()\fR and \fBEVP_PKEY_sign_message_final()\fR functions +where added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_todata.3 b/static/netbsd/man3/EVP_PKEY_todata.3 new file mode 100644 index 00000000..05164fc9 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_todata.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: EVP_PKEY_todata.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_todata 3" +.TH EVP_PKEY_todata 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_todata, EVP_PKEY_export +\&\- functions to return keys as an array of key parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_todata(const EVP_PKEY *pkey, int selection, OSSL_PARAM **params); +\& int EVP_PKEY_export(const EVP_PKEY *pkey, int selection, +\& OSSL_CALLBACK *export_cb, void *export_cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described here are used to extract \fBEVP_PKEY\fR key values as an +array of \fBOSSL_PARAM\fR\|(3). +.PP +\&\fBEVP_PKEY_todata()\fR extracts values from a key \fIpkey\fR using the \fIselection\fR. +\&\fIselection\fR is described in "Selections" in \fBEVP_PKEY_fromdata\fR\|(3). +\&\fBOSSL_PARAM_free\fR\|(3) should be used to free the returned parameters in +\&\fI*params\fR. +.PP +\&\fBEVP_PKEY_export()\fR is similar to \fBEVP_PKEY_todata()\fR but uses a callback +\&\fIexport_cb\fR that gets passed the value of \fIexport_cbarg\fR. +See \fBopenssl\-core.h\fR\|(7) for more information about the callback. Note that the +\&\fBOSSL_PARAM\fR\|(3) array that is passed to the callback is not persistent after the +callback returns. The user must preserve the items of interest, or use +\&\fBEVP_PKEY_todata()\fR if persistence is required. +.SH NOTES +.IX Header "NOTES" +These functions only work with key management methods coming from a provider. +This is the mirror function to \fBEVP_PKEY_fromdata\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_todata()\fR and \fBEVP_PKEY_export()\fR return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PARAM\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBEVP_PKEY_fromdata\fR\|(3), +\&\fBEVP_PKEY\-RSA\fR\|(7), +\&\fBEVP_PKEY\-EC\fR\|(7), +\&\fBEVP_PKEY\-DSA\fR\|(7), +\&\fBEVP_PKEY\-ED25519\fR\|(7) +\&\fBEVP_PKEY\-ED448\fR\|(7), +\&\fBEVP_PKEY\-DH\fR\|(7), +\&\fBEVP_PKEY\-X25519\fR\|(7), +\&\fBEVP_PKEY\-X448\fR\|(7), +\&\fBEVP_PKEY\-ML\-DSA\fR\|(7), +\&\fBEVP_PKEY\-ML\-KEM\fR\|(7), +\&\fBEVP_PKEY\-SLH\-DSA\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.PP +Support for \fBML\-DSA\fR, \fBML\-KEM\fR and \fBSLH\-DSA\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_verify.3 b/static/netbsd/man3/EVP_PKEY_verify.3 new file mode 100644 index 00000000..11c81136 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_verify.3 @@ -0,0 +1,400 @@ +.\" $NetBSD: EVP_PKEY_verify.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_verify 3" +.TH EVP_PKEY_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init_ex2, +EVP_PKEY_verify, EVP_PKEY_verify_message_init, EVP_PKEY_verify_message_update, +EVP_PKEY_verify_message_final, EVP_PKEY_CTX_set_signature \- signature +verification using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_verify_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_CTX_set_signature(EVP_PKEY_CTX *pctx, +\& const unsigned char *sig, size_t siglen); +\& int EVP_PKEY_verify_message_update(EVP_PKEY_CTX *ctx, +\& unsigned char *in, size_t inlen); +\& int EVP_PKEY_verify_message_final(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, +\& const unsigned char *sig, size_t siglen, +\& const unsigned char *tbs, size_t tbslen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_verify_init()\fR initializes a public key algorithm context \fIctx\fR for +verification using the algorithm given when the context was created +using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to +fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) +for more information about implicit fetches. +.PP +\&\fBEVP_PKEY_verify_init_ex()\fR is the same as \fBEVP_PKEY_verify_init()\fR but additionally +sets the passed parameters \fIparams\fR on the context before returning. +.PP +\&\fBEVP_PKEY_verify_init_ex2()\fR is the same as \fBEVP_PKEY_verify_init_ex()\fR, but works +with an explicitly fetched \fBEVP_SIGNATURE\fR \fIalgo\fR. +A context \fIctx\fR without a pre\-loaded key cannot be used with this function. +Depending on what algorithm was fetched, certain details revolving around the +treatment of the input to \fBEVP_PKEY_verify()\fR may be pre\-determined, and in that +case, those details may normally not be changed. +See "NOTES" below for a deeper explanation. +.PP +\&\fBEVP_PKEY_verify_message_init()\fR initializes a public key algorithm context +\&\fIctx\fR for verifying an unlimited size message using the algorithm given by +\&\fIalgo\fR and the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +Passing the message is supported both in a one\-shot fashion using +\&\fBEVP_PKEY_verify()\fR, and through the combination of \fBEVP_PKEY_verify_update()\fR and +\&\fBEVP_PKEY_verify_final()\fR. +This function enables using algorithms that can process input of arbitrary +length, such as ED25519, RSA\-SHA256 and similar. +.PP +\&\fBEVP_PKEY_CTX_set_signature()\fR specifies the \fIsiglen\fR bytes long signature +\&\fIsig\fR to be verified against by \fBEVP_PKEY_verify_final()\fR. +It \fImust\fR be used together with \fBEVP_PKEY_verify_update()\fR and +\&\fBEVP_PKEY_verify_final()\fR. +See "NOTES" below for a deeper explanation. +.PP +\&\fBEVP_PKEY_verify_update()\fR adds \fIinlen\fR bytes from \fIin\fR to the data to be +processed for verification. The signature algorithm specification and +implementation determine how the input bytes are processed and if there\*(Aqs a +limit on the total size of the input. See "NOTES" below for a deeper +explanation. +.PP +\&\fBEVP_PKEY_verify_final()\fR verifies the processed data, given only \fIctx\fR. +The signature to verify against must have been given with +\&\fBEVP_PKEY_CTX_set_signature()\fR. +.PP +\&\fBEVP_PKEY_verify()\fR is a one\-shot function that performs the same thing as +\&\fBEVP_PKEY_CTX_set_signature()\fR call with \fIsig\fR and \fIsiglen\fR as parameters, +followed by a single \fBEVP_PKEY_verify_update()\fR call with \fItbs\fR and \fItbslen\fR, +followed by \fBEVP_PKEY_verify_final()\fR call. +.SH NOTES +.IX Header "NOTES" +.SS General +.IX Subsection "General" +Some signature implementations only accumulate the input data and do no +further processing before verifying it (they expect the input to be a digest), +while others compress the data, typically by internally producing a digest, +and signing the result, which is then verified against a given signature. +Some of them support both modes of operation at the same time. +The caller is expected to know how the chosen algorithm is supposed to behave +and under what conditions. +.PP +For example, an RSA implementation can be expected to only expect a digest as +input, while ED25519 can be expected to process the input with a hash, i.e. +to produce the digest internally, and while RSA\-SHA256 can be expected to +handle either mode of operation, depending on if the operation was initialized +with \fBEVP_PKEY_verify_init_ex2()\fR or with \fBEVP_PKEY_verify_message_init()\fR. +.PP +Similarly, an RSA implementation usually expects additional details to be set, +like the message digest algorithm that the input is supposed to be digested +with, as well as the padding mode (see \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and +\&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256 +implementation usually has these details pre\-set and immutable. +.PP +The functions described here can\*(Aqt be used to combine separate algorithms. In +particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR +parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) can be used to combine a +signature algorithm with a hash algorithm to process the input. In other +words, it\*(Aqs not possible to specify a \fIctx\fR pre\-loaded with an RSA pkey, or +an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the +functionality of RSA\-SHA256. If combining algorithms in that manner is +desired, please use \fBEVP_DigestVerifyInit\fR\|(3) and associated functions, or +\&\fBEVP_VerifyInit\fR\|(3) and associated functions. +.SS "Performing multiple verifications" +.IX Subsection "Performing multiple verifications" +When initialized using \fBEVP_PKEY_verify_init_ex()\fR or \fBEVP_PKEY_verify_init_ex2()\fR, +\&\fBEVP_PKEY_verify()\fR can be called more than once on the same context to have +several one\-shot operations performed using the same parameters. +.PP +When initialized using \fBEVP_PKEY_verify_message_init()\fR, it\*(Aqs not possible to +call \fBEVP_PKEY_verify()\fR multiple times. +.SS "On \fBEVP_PKEY_CTX_set_signature()\fP" +.IX Subsection "On EVP_PKEY_CTX_set_signature()" +Some signature algorithms (such as LMS) require the signature verification +data be specified before verifying the message. +Other algorithms allow the signature to be specified late. +To allow either way (which may depend on the application\*(Aqs flow of input), the +signature to be verified against \fImust\fR be specified using this function when +using \fBEVP_PKEY_verify_message_update()\fR and \fBEVP_PKEY_verify_message_final()\fR to +perform the verification. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 for success and 0 or a negative value for failure. +However, unlike other functions, the return value 0 from \fBEVP_PKEY_verify()\fR, +\&\fBEVP_PKEY_verify_recover()\fR and \fBEVP_PKEY_verify_message_final()\fR only indicates +that the signature did not verify successfully (that is tbs did not match the +original data or the signature was of invalid form) it is not an indication of +a more serious error. +.PP +A negative value indicates an error other that signature verification failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "RSA with PKCS#1 padding for SHA256" +.IX Subsection "RSA with PKCS#1 padding for SHA256" +Verify signature using PKCS#1 padding and a SHA256 digest as input: +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& unsigned char *md, *sig; +\& size_t mdlen, siglen; +\& EVP_PKEY *verify_key; +\& +\& /* +\& * NB: assumes verify_key, sig, siglen md and mdlen are already set up +\& * and that verify_key is an RSA public key +\& */ +\& ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */); +\& if (ctx == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_verify_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) +\& /* Error */ +\& +\& /* Perform operation */ +\& ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); +\& +\& /* +\& * ret == 1 indicates success, 0 verify failure and < 0 for some +\& * other error. +\& */ +.Ve +.SS "RSA\-SHA256 with a pre\-computed digest" +.IX Subsection "RSA-SHA256 with a pre-computed digest" +Verify a digest with RSA\-SHA256 using one\-shot functions. To be noted is that +RSA\-SHA256 is assumed to be an implementation of \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, +for which the padding is pre\-determined to be \fBRSA_PKCS1_PADDING\fR, and the +input digest is assumed to have been computed using SHA256. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* md is a SHA\-256 digest in this example. */ +\& unsigned char *md, *sig; +\& size_t mdlen = 32, siglen; +\& EVP_PKEY *signing_key; +\& +\& /* +\& * NB: assumes verify_key, sig, siglen, md and mdlen are already set up +\& * and that verify_key is an RSA public key +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_verify_init_ex2(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_verify(ctx, sig, siglen, md, mdlen) <= 0) +\& /* Error or signature doesn\*(Aqt verify */ +\& +\& /* Perform operation */ +\& ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); +\& +\& /* +\& * ret == 1 indicates success, 0 verify failure and < 0 for some +\& * other error. +\& */ +.Ve +.SS "RSA\-SHA256, one\-shot" +.IX Subsection "RSA-SHA256, one-shot" +Verify a document with RSA\-SHA256 using one\-shot functions. +To be noted is that RSA\-SHA256 is assumed to be an implementation of +\&\f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, for which the padding is pre\-determined to be +\&\fBRSA_PKCS1_PADDING\fR. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* in the input in this example. */ +\& unsigned char *in, *sig; +\& /* inlen is the length of the input in this example. */ +\& size_t inlen, siglen; +\& EVP_PKEY *signing_key; +\& EVP_SIGNATURE *alg; +\& +\& /* +\& * NB: assumes signing_key, in and inlen are set up before +\& * the next step. signing_key must be an RSA private key, +\& * in must point to data to be digested and signed, and +\& * inlen must be the size of the data in bytes. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL || alg == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& /* Perform operation */ +\& ret = EVP_PKEY_verify(ctx, sig, siglen, in, inlen); +\& +\& /* +\& * ret == 1 indicates success, 0 verify failure and < 0 for some +\& * other error. +\& */ +.Ve +.SS "RSA\-SHA256, using update and final" +.IX Subsection "RSA-SHA256, using update and final" +This is the same as the previous example, but allowing stream\-like +functionality. +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& /* in is the input in this example. */ +\& unsigned char *in, *sig; +\& /* inlen is the length of the input in this example. */ +\& size_t inlen, siglen; +\& EVP_PKEY *signing_key; +\& EVP_SIGNATURE *alg; +\& +\& /* +\& * NB: assumes signing_key, in and inlen are set up before +\& * the next step. signing_key must be an RSA private key, +\& * in must point to data to be digested and signed, and +\& * inlen must be the size of the data in bytes. +\& */ +\& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); +\& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL); +\& +\& if (ctx == NULL || alg == NULL) +\& /* Error occurred */ +\& if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0) +\& /* Error */ +\& +\& /* We have the signature, specify it early */ +\& EVP_PKEY_CTX_set_signature(ctx, sig, siglen); +\& +\& /* Perform operation */ +\& while (inlen > 0) { +\& if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0) +\& /* Error */ +\& if (inlen > 256) { +\& inlen \-= 256; +\& in += 256; +\& } else { +\& inlen = 0; +\& } +\& } +\& ret = EVP_PKEY_verify_message_final(ctx); +\& +\& /* +\& * ret == 1 indicates success, 0 verify failure and < 0 for some +\& * other error. +\& */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_verify_init()\fR and \fBEVP_PKEY_verify()\fR functions were added in +OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_verify_init_ex()\fR function was added in OpenSSL 3.0. +.PP +The \fBEVP_PKEY_verify_init_ex2()\fR, \fBEVP_PKEY_verify_message_init()\fR, +\&\fBEVP_PKEY_verify_message_update()\fR, \fBEVP_PKEY_verify_message_final()\fR and +\&\fBEVP_PKEY_CTX_set_signature()\fR functions where added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_PKEY_verify_recover.3 b/static/netbsd/man3/EVP_PKEY_verify_recover.3 new file mode 100644 index 00000000..223d9c16 --- /dev/null +++ b/static/netbsd/man3/EVP_PKEY_verify_recover.3 @@ -0,0 +1,200 @@ +.\" $NetBSD: EVP_PKEY_verify_recover.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_verify_recover 3" +.TH EVP_PKEY_verify_recover 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover_init_ex, +EVP_PKEY_verify_recover_init_ex2, EVP_PKEY_verify_recover +\&\- recover signature using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); +\& int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_verify_recover_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo, +\& const OSSL_PARAM params[]); +\& int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, +\& unsigned char *rout, size_t *routlen, +\& const unsigned char *sig, size_t siglen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_verify_recover_init()\fR initializes a public key algorithm context +\&\fIctx\fR for signing using the algorithm given when the context was created +using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to +fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) +for more information about implicit fetches. +.PP +\&\fBEVP_PKEY_verify_recover_init_ex()\fR is the same as +\&\fBEVP_PKEY_verify_recover_init()\fR but additionally sets the passed parameters +\&\fIparams\fR on the context before returning. +.PP +\&\fBEVP_PKEY_verify_recover_init_ex2()\fR is the same as \fBEVP_PKEY_verify_recover_init_ex()\fR, +but works with an explicitly fetched \fBEVP_SIGNATURE\fR \fIalgo\fR. +A context \fIctx\fR without a pre\-loaded key cannot be used with this function. +Depending on what algorithm was fetched, certain details revolving around the +treatment of the input to \fBEVP_PKEY_verify()\fR may be pre\-determined, and in that +case, those details may normally not be changed. +See "NOTES" below for a deeper explanation. +.PP +The \fBEVP_PKEY_verify_recover()\fR function recovers signed data +using \fIctx\fR. The signature is specified using the \fIsig\fR and +\&\fIsiglen\fR parameters. If \fIrout\fR is NULL then the maximum size of the output +buffer is written to the \fIroutlen\fR parameter. If \fIrout\fR is not NULL then +before the call the \fIroutlen\fR parameter should contain the length of the +\&\fIrout\fR buffer, if the call is successful recovered data is written to +\&\fIrout\fR and the amount of data written to \fIroutlen\fR. +.SH NOTES +.IX Header "NOTES" +Normally an application is only interested in whether a signature verification +operation is successful in those cases the \fBEVP_verify()\fR function should be +used. +.PP +Sometimes however it is useful to obtain the data originally signed using a +signing operation. Only certain public key algorithms can recover a signature +in this way (for example RSA in PKCS padding mode). +.PP +After the call to \fBEVP_PKEY_verify_recover_init()\fR algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. +.PP +After the call to \fBEVP_PKEY_verify_recover_init_ex2()\fR, algorithm specific control +operations may not be needed if the chosen algorithm implies that those controls +pre\-set (and immutable). +.PP +The function \fBEVP_PKEY_verify_recover()\fR can be called more than once on the same +context if several operations are performed using the same parameters. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_PKEY_verify_recover_init()\fR and \fBEVP_PKEY_verify_recover()\fR return 1 for success +and 0 or a negative value for failure. In particular a return value of \-2 +indicates the operation is not supported by the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +Recover digest originally signed using PKCS#1 and SHA256 digest: +.PP +.Vb 2 +\& #include +\& #include +\& +\& EVP_PKEY_CTX *ctx; +\& unsigned char *rout, *sig; +\& size_t routlen, siglen; +\& EVP_PKEY *verify_key; +\& +\& /* +\& * NB: assumes verify_key, sig and siglen are already set up +\& * and that verify_key is an RSA public key +\& */ +\& ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */); +\& if (!ctx) +\& /* Error occurred */ +\& if (EVP_PKEY_verify_recover_init(ctx) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) +\& /* Error */ +\& if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) +\& /* Error */ +\& +\& /* Determine buffer length */ +\& if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) +\& /* Error */ +\& +\& rout = OPENSSL_malloc(routlen); +\& +\& if (!rout) +\& /* malloc failure */ +\& +\& if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) +\& /* Error */ +\& +\& /* Recovered data is routlen bytes written to buffer rout */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_verify_recover_init()\fR and \fBEVP_PKEY_verify_recover()\fR +functions were added in OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_verify_recover_init_ex()\fR function was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_RAND.3 b/static/netbsd/man3/EVP_RAND.3 new file mode 100644 index 00000000..33419d16 --- /dev/null +++ b/static/netbsd/man3/EVP_RAND.3 @@ -0,0 +1,454 @@ +.\" $NetBSD: EVP_RAND.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_RAND 3" +.TH EVP_RAND 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, +EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_CTX_up_ref, EVP_RAND_instantiate, +EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce, +EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_get_strength, +EVP_RAND_get_state, +EVP_RAND_get0_provider, EVP_RAND_CTX_get0_rand, EVP_RAND_is_a, +EVP_RAND_get0_name, EVP_RAND_names_do_all, +EVP_RAND_get0_description, +EVP_RAND_CTX_get_params, +EVP_RAND_CTX_set_params, EVP_RAND_do_all_provided, EVP_RAND_get_params, +EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params, +EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params, +EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY, +EVP_RAND_STATE_ERROR \- EVP RAND routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_rand_st EVP_RAND; +\& typedef struct evp_rand_ctx_st EVP_RAND_CTX; +\& +\& EVP_RAND *EVP_RAND_fetch(OSSL_LIB_CTX *libctx, const char *algorithm, +\& const char *properties); +\& int EVP_RAND_up_ref(EVP_RAND *rand); +\& void EVP_RAND_free(EVP_RAND *rand); +\& EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent); +\& void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx); +\& int EVP_RAND_CTX_up_ref(EVP_RAND_CTX *ctx); +\& EVP_RAND *EVP_RAND_CTX_get0_rand(EVP_RAND_CTX *ctx); +\& int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]); +\& int EVP_RAND_CTX_get_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]); +\& int EVP_RAND_CTX_set_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand); +\& const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand); +\& const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand); +\& const OSSL_PARAM *EVP_RAND_CTX_gettable_params(EVP_RAND_CTX *ctx); +\& const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx); +\& const char *EVP_RAND_get0_name(const EVP_RAND *rand); +\& const char *EVP_RAND_get0_description(const EVP_RAND *rand); +\& int EVP_RAND_is_a(const EVP_RAND *rand, const char *name); +\& const OSSL_PROVIDER *EVP_RAND_get0_provider(const EVP_RAND *rand); +\& void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_RAND *rand, void *arg), +\& void *arg); +\& int EVP_RAND_names_do_all(const EVP_RAND *rand, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& +\& int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength, +\& int prediction_resistance, +\& const unsigned char *pstr, size_t pstr_len, +\& const OSSL_PARAM params[]); +\& int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx); +\& int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen, +\& unsigned int strength, int prediction_resistance, +\& const unsigned char *addin, size_t addin_len); +\& int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance, +\& const unsigned char *ent, size_t ent_len, +\& const unsigned char *addin, size_t addin_len); +\& int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen); +\& int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx); +\& int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx); +\& unsigned int EVP_RAND_get_strength(EVP_RAND_CTX *ctx); +\& int EVP_RAND_get_state(EVP_RAND_CTX *ctx); +\& +\& #define EVP_RAND_STATE_UNINITIALISED 0 +\& #define EVP_RAND_STATE_READY 1 +\& #define EVP_RAND_STATE_ERROR 2 +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP RAND routines are a high\-level interface to random number generators +both deterministic and not. +If you just want to generate random bytes then you don\*(Aqt need to use +these functions: just call \fBRAND_bytes()\fR or \fBRAND_priv_bytes()\fR. +If you want to do more, these calls should be used instead of the older +RAND and RAND_DRBG functions. +.PP +After creating a \fBEVP_RAND_CTX\fR for the required algorithm using +\&\fBEVP_RAND_CTX_new()\fR, inputs to the algorithm are supplied either by +passing them as part of the \fBEVP_RAND_instantiate()\fR call or using calls to +\&\fBEVP_RAND_CTX_set_params()\fR before calling \fBEVP_RAND_instantiate()\fR. Finally, +call \fBEVP_RAND_generate()\fR to produce cryptographically secure random bytes. +.SS Types +.IX Subsection "Types" +\&\fBEVP_RAND\fR is a type that holds the implementation of a RAND. +.PP +\&\fBEVP_RAND_CTX\fR is a context type that holds the algorithm inputs. +\&\fBEVP_RAND_CTX\fR structures are reference counted. +.SS "Algorithm implementation fetching" +.IX Subsection "Algorithm implementation fetching" +\&\fBEVP_RAND_fetch()\fR fetches an implementation of a RAND \fIalgorithm\fR, given +a library context \fIlibctx\fR and a set of \fIproperties\fR. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +The returned value must eventually be freed with +\&\fBEVP_RAND_free\fR\|(3). +.PP +\&\fBEVP_RAND_up_ref()\fR increments the reference count of an already fetched +RAND. +.PP +\&\fBEVP_RAND_free()\fR frees a fetched algorithm. +NULL is a valid parameter, for which this function is a no\-op. +.SS "Context manipulation functions" +.IX Subsection "Context manipulation functions" +\&\fBEVP_RAND_CTX_new()\fR creates a new context for the RAND implementation \fIrand\fR. +If not NULL, \fIparent\fR specifies the seed source for this implementation. +Not all random number generators need to have a seed source specified. +If a parent is required, a NULL \fIparent\fR will utilise the operating +system entropy sources. +It is recommended to minimise the number of random number generators that +rely on the operating system for their randomness because this is often scarce. +.PP +\&\fBEVP_RAND_CTX_free()\fR frees up the context \fIctx\fR. If \fIctx\fR is NULL, nothing +is done. +.PP +\&\fBEVP_RAND_CTX_get0_rand()\fR returns the \fBEVP_RAND\fR associated with the context +\&\fIctx\fR. +.SS "Random Number Generator Functions" +.IX Subsection "Random Number Generator Functions" +\&\fBEVP_RAND_instantiate()\fR processes any parameters in \fIparams\fR and +then instantiates the RAND \fIctx\fR with a minimum security strength +of and personalisation string \fIpstr\fR of length . +If \fIprediction_resistance\fR is specified, fresh entropy from a live source +will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C. +.PP +\&\fBEVP_RAND_uninstantiate()\fR uninstantiates the RAND \fIctx\fR as per +NIST SP 800\-90A and SP 800\-90C. Subsequent to this call, the RAND cannot +be used to generate bytes. It can only be freed or instantiated again. +.PP +\&\fBEVP_RAND_generate()\fR produces random bytes from the RAND \fIctx\fR with the +additional input \fIaddin\fR of length \fIaddin_len\fR. The bytes +produced will meet the security \fIstrength\fR. +If \fIprediction_resistance\fR is specified, fresh entropy from a live source +will be sought. This call operates as per NIST SP 800\-90A and SP 800\-90C. +.PP +\&\fBEVP_RAND_reseed()\fR reseeds the RAND with new entropy. +Entropy \fIent\fR of length \fIent_len\fR bytes can be supplied as can additional +input \fIaddin\fR of length \fIaddin_len\fR bytes. In the FIPS provider, both are +treated as additional input as per NIST SP\-800\-90Ar1, Sections 9.1 and 9.2. +Additional seed material is also drawn from the RAND\*(Aqs parent or the +operating system. If \fIprediction_resistance\fR is specified, fresh entropy +from a live source will be sought. This call operates as per NIST SP 800\-90A +and SP 800\-90C. +.PP +\&\fBEVP_RAND_nonce()\fR creates a nonce in \fIout\fR of length \fIoutlen\fR +bytes from the RAND \fIctx\fR. +.PP +\&\fBEVP_RAND_enable_locking()\fR enables locking for the RAND \fIctx\fR and all of +its parents. After this \fIctx\fR will operate in a thread safe manner, albeit +more slowly. This function is not itself thread safe if called with the same +\&\fIctx\fR from multiple threads. Typically locking should be enabled before a +\&\fIctx\fR is shared across multiple threads. +.PP +\&\fBEVP_RAND_get_params()\fR retrieves details about the implementation +\&\fIrand\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_RAND_CTX_get_params()\fR retrieves chosen parameters, given the +context \fIctx\fR and its underlying context. +The set of parameters given with \fIparams\fR determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. +.PP +\&\fBEVP_RAND_CTX_set_params()\fR passes chosen parameters to the underlying +context, given a context \fIctx\fR. +The set of parameters given with \fIparams\fR determine exactly what +parameters are passed down. +Note that a parameter that is unknown in the underlying context is +simply ignored. +Also, what happens when a needed parameter isn\*(Aqt passed down is +defined by the implementation. +.PP +\&\fBEVP_RAND_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array that describes +the retrievable and settable parameters. \fBEVP_RAND_gettable_params()\fR returns +parameters that can be used with \fBEVP_RAND_get_params()\fR. +.PP +\&\fBEVP_RAND_gettable_ctx_params()\fR and \fBEVP_RAND_CTX_gettable_params()\fR return +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the retrievable parameters that +can be used with \fBEVP_RAND_CTX_get_params()\fR. \fBEVP_RAND_gettable_ctx_params()\fR +returns the parameters that can be retrieved from the algorithm, whereas +\&\fBEVP_RAND_CTX_gettable_params()\fR returns the parameters that can be retrieved +in the context\*(Aqs current state. +.PP +\&\fBEVP_RAND_settable_ctx_params()\fR and \fBEVP_RAND_CTX_settable_params()\fR return +constant \fBOSSL_PARAM\fR\|(3) arrays that describe the settable parameters that +can be used with \fBEVP_RAND_CTX_set_params()\fR. \fBEVP_RAND_settable_ctx_params()\fR +returns the parameters that can be retrieved from the algorithm, whereas +\&\fBEVP_RAND_CTX_settable_params()\fR returns the parameters that can be retrieved +in the context\*(Aqs current state. +.SS "Information functions" +.IX Subsection "Information functions" +\&\fBEVP_RAND_get_strength()\fR returns the security strength of the RAND \fIctx\fR. +.PP +\&\fBEVP_RAND_get_state()\fR returns the current state of the RAND \fIctx\fR. +States defined by the OpenSSL RNGs are: +.IP \(bu 4 +EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. +The instantiate call will change this to the ready state. +.IP \(bu 4 +EVP_RAND_STATE_READY: this RNG is currently ready to generate output. +.IP \(bu 4 +EVP_RAND_STATE_ERROR: this RNG is in an error state. +.PP +\&\fBEVP_RAND_is_a()\fR returns 1 if \fIrand\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR, otherwise 0. +.PP +\&\fBEVP_RAND_get0_provider()\fR returns the provider that holds the implementation +of the given \fIrand\fR. +.PP +\&\fBEVP_RAND_do_all_provided()\fR traverses all RAND implemented by all activated +providers in the given library context \fIlibctx\fR, and for each of the +implementations, calls the given function \fIfn\fR with the implementation method +and the given \fIarg\fR as argument. +.PP +\&\fBEVP_RAND_get0_name()\fR returns the canonical name of \fIrand\fR. +.PP +\&\fBEVP_RAND_names_do_all()\fR traverses all names for \fIrand\fR, and calls +\&\fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_RAND_get0_description()\fR returns a description of the rand, meant for +display and human consumption. The description is at the discretion of +the rand implementation. +.PP +\&\fBEVP_RAND_verify_zeroization()\fR confirms if the internal DRBG state is +currently zeroed. This is used by the FIPS provider to support the mandatory +self tests. +.SH PARAMETERS +.IX Header "PARAMETERS" +The standard parameter names are: +.IP """state"" (\fBOSSL_RAND_PARAM_STATE\fR) " 4 +.IX Item """state"" (OSSL_RAND_PARAM_STATE) " +Returns the state of the random number generator. +.IP """strength"" (\fBOSSL_RAND_PARAM_STRENGTH\fR) " 4 +.IX Item """strength"" (OSSL_RAND_PARAM_STRENGTH) " +Returns the bit strength of the random number generator. +.IP """fips\-indicator"" (\fBOSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR\fR) " 4 +.IX Item """fips-indicator"" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) " +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This option is used by the OpenSSL FIPS provider and is not supported +by all EVP_RAND sources. +.PP +For rands that are also deterministic random bit generators (DRBGs), these +additional parameters are recognised. Not all +parameters are relevant to, or are understood by all DRBG rands: +.IP """reseed_requests"" (\fBOSSL_DRBG_PARAM_RESEED_REQUESTS\fR) " 4 +.IX Item """reseed_requests"" (OSSL_DRBG_PARAM_RESEED_REQUESTS) " +Reads or set the number of generate requests before reseeding the +associated RAND ctx. +.IP """reseed_time_interval"" (\fBOSSL_DRBG_PARAM_RESEED_TIME_INTERVAL\fR) " 4 +.IX Item """reseed_time_interval"" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) " +Reads or set the number of elapsed seconds before reseeding the +associated RAND ctx. +.IP """max_request"" (\fBOSSL_RAND_PARAM_MAX_REQUEST\fR) " 4 +.IX Item """max_request"" (OSSL_RAND_PARAM_MAX_REQUEST) " +Specifies the maximum number of bytes that can be generated in a single +call to OSSL_FUNC_rand_generate. +.IP """min_entropylen"" (\fBOSSL_DRBG_PARAM_MIN_ENTROPYLEN\fR) " 4 +.IX Item """min_entropylen"" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) " +.PD 0 +.IP """max_entropylen"" (\fBOSSL_DRBG_PARAM_MAX_ENTROPYLEN\fR) " 4 +.IX Item """max_entropylen"" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) " +.PD +Specify the minimum and maximum number of bytes of random material that +can be used to seed the DRBG. +.IP """min_noncelen"" (\fBOSSL_DRBG_PARAM_MIN_NONCELEN\fR) " 4 +.IX Item """min_noncelen"" (OSSL_DRBG_PARAM_MIN_NONCELEN) " +.PD 0 +.IP """max_noncelen"" (\fBOSSL_DRBG_PARAM_MAX_NONCELEN\fR) " 4 +.IX Item """max_noncelen"" (OSSL_DRBG_PARAM_MAX_NONCELEN) " +.PD +Specify the minimum and maximum number of bytes of nonce that can be used to +seed the DRBG. +.IP """max_perslen"" (\fBOSSL_DRBG_PARAM_MAX_PERSLEN\fR) " 4 +.IX Item """max_perslen"" (OSSL_DRBG_PARAM_MAX_PERSLEN) " +.PD 0 +.IP """max_adinlen"" (\fBOSSL_DRBG_PARAM_MAX_ADINLEN\fR) " 4 +.IX Item """max_adinlen"" (OSSL_DRBG_PARAM_MAX_ADINLEN) " +.PD +Specify the minimum and maximum number of bytes of personalisation string +that can be used with the DRBG. +.IP """reseed_counter"" (\fBOSSL_DRBG_PARAM_RESEED_COUNTER\fR) " 4 +.IX Item """reseed_counter"" (OSSL_DRBG_PARAM_RESEED_COUNTER) " +Specifies the number of times the DRBG has been seeded or reseeded. +.IP """properties"" (\fBOSSL_RAND_PARAM_PROPERTIES\fR) " 4 +.IX Item """properties"" (OSSL_RAND_PARAM_PROPERTIES) " +.PD 0 +.IP """mac"" (\fBOSSL_RAND_PARAM_MAC\fR) " 4 +.IX Item """mac"" (OSSL_RAND_PARAM_MAC) " +.IP """digest"" (\fBOSSL_RAND_PARAM_DIGEST\fR) " 4 +.IX Item """digest"" (OSSL_RAND_PARAM_DIGEST) " +.IP """cipher"" (\fBOSSL_RAND_PARAM_CIPHER\fR) " 4 +.IX Item """cipher"" (OSSL_RAND_PARAM_CIPHER) " +.PD +For RAND implementations that use an underlying computation MAC, digest or +cipher, these parameters set what the algorithm should be. +.Sp +The value is always the name of the intended algorithm, +or the properties in the case of \fBOSSL_RAND_PARAM_PROPERTIES\fR. +.SH NOTES +.IX Header "NOTES" +The use of a nonzero value for the \fIprediction_resistance\fR argument to +\&\fBEVP_RAND_instantiate()\fR, \fBEVP_RAND_generate()\fR or \fBEVP_RAND_reseed()\fR should +be used sparingly. In the default setup, this will cause all public and +private DRBGs to be reseeded on next use. Since, by default, public and +private DRBGs are allocated on a per thread basis, this can result in +significant overhead for highly multi\-threaded applications. For normal +use\-cases, the default "reseed_requests" and "reseed_time_interval" +thresholds ensure sufficient prediction resistance over time and you +can reduce those values if you think they are too high. Explicitly +requesting prediction resistance is intended for more special use\-cases +like generating long\-term secrets. +.PP +An \fBEVP_RAND_CTX\fR needs to have locking enabled if it acts as the parent of +more than one child and the children can be accessed concurrently. This must +be done by explicitly calling \fBEVP_RAND_enable_locking()\fR. +.PP +The RAND life\-cycle is described in \fBlife_cycle\-rand\fR\|(7). In the future, +the transitions described there will be enforced. When this is done, it will +not be considered a breaking change to the API. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_RAND_fetch()\fR returns a pointer to a newly fetched \fBEVP_RAND\fR, or +NULL if allocation failed. +.PP +\&\fBEVP_RAND_get0_provider()\fR returns a pointer to the provider for the RAND, or +NULL on error. +.PP +\&\fBEVP_RAND_CTX_get0_rand()\fR returns a pointer to the \fBEVP_RAND\fR associated +with the context. +.PP +\&\fBEVP_RAND_get0_name()\fR returns the name of the random number generation +algorithm. +.PP +\&\fBEVP_RAND_up_ref()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_RAND_names_do_all()\fR returns 1 if the callback was called for all names. A +return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_RAND_CTX_new()\fR returns either the newly allocated +\&\fBEVP_RAND_CTX\fR structure or NULL if an error occurred. +.PP +\&\fBEVP_RAND_CTX_free()\fR does not return a value. +.PP +\&\fBEVP_RAND_CTX_up_ref()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_RAND_nonce()\fR returns 1 on success, 0 on error. +.PP +\&\fBEVP_RAND_get_strength()\fR returns the strength of the random number generator +in bits. +.PP +\&\fBEVP_RAND_gettable_params()\fR, \fBEVP_RAND_gettable_ctx_params()\fR and +\&\fBEVP_RAND_settable_ctx_params()\fR return an array of OSSL_PARAMs. +.PP +\&\fBEVP_RAND_verify_zeroization()\fR returns 1 if the internal DRBG state is +currently zeroed, and 0 if not. +.PP +The remaining functions return 1 for success and 0 or a negative value for +failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_bytes\fR\|(3), +\&\fBEVP_RAND\-CTR\-DRBG\fR\|(7), +\&\fBEVP_RAND\-HASH\-DRBG\fR\|(7), +\&\fBEVP_RAND\-HMAC\-DRBG\fR\|(7), +\&\fBEVP_RAND\-TEST\-RAND\fR\|(7), +\&\fBprovider\-rand\fR\|(7), +\&\fBlife_cycle\-rand\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_RAND_CTX_up_ref()\fR was added in OpenSSL 3.1. +.PP +The remaining functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_SIGNATURE.3 b/static/netbsd/man3/EVP_SIGNATURE.3 new file mode 100644 index 00000000..b42c7188 --- /dev/null +++ b/static/netbsd/man3/EVP_SIGNATURE.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: EVP_SIGNATURE.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SIGNATURE 3" +.TH EVP_SIGNATURE 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SIGNATURE, +EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref, +EVP_SIGNATURE_is_a, EVP_SIGNATURE_get0_provider, +EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all, +EVP_SIGNATURE_get0_name, EVP_SIGNATURE_get0_description, +EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params +\&\- Functions to manage EVP_SIGNATURE algorithm objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_signature_st EVP_SIGNATURE; +\& +\& EVP_SIGNATURE *EVP_SIGNATURE_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& void EVP_SIGNATURE_free(EVP_SIGNATURE *signature); +\& int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature); +\& const char *EVP_SIGNATURE_get0_name(const EVP_SIGNATURE *signature); +\& int EVP_SIGNATURE_is_a(const EVP_SIGNATURE *signature, const char *name); +\& OSSL_PROVIDER *EVP_SIGNATURE_get0_provider(const EVP_SIGNATURE *signature); +\& void EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_SIGNATURE *signature, +\& void *arg), +\& void *arg); +\& int EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_SIGNATURE_get0_name(const EVP_SIGNATURE *signature); +\& const char *EVP_SIGNATURE_get0_description(const EVP_SIGNATURE *signature); +\& const OSSL_PARAM *EVP_SIGNATURE_gettable_ctx_params(const EVP_SIGNATURE *sig); +\& const OSSL_PARAM *EVP_SIGNATURE_settable_ctx_params(const EVP_SIGNATURE *sig); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_SIGNATURE_fetch()\fR fetches the implementation for the given +\&\fBalgorithm\fR from any provider offering it, within the criteria given +by the \fBproperties\fR. +The algorithm will be one offering functions for performing signature related +tasks such as signing and verifying. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +.PP +The returned value must eventually be freed with \fBEVP_SIGNATURE_free()\fR. +.PP +\&\fBEVP_SIGNATURE_free()\fR decrements the reference count for the \fBEVP_SIGNATURE\fR +structure. Typically this structure will have been obtained from an earlier call +to \fBEVP_SIGNATURE_fetch()\fR. If the reference count drops to 0 then the +structure is freed. If the argument is NULL, nothing is done. +.PP +\&\fBEVP_SIGNATURE_up_ref()\fR increments the reference count for an \fBEVP_SIGNATURE\fR +structure. +.PP +\&\fBEVP_SIGNATURE_is_a()\fR returns 1 if \fIsignature\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR, otherwise 0. +.PP +\&\fBEVP_SIGNATURE_get0_provider()\fR returns the provider that \fIsignature\fR was +fetched from. +.PP +\&\fBEVP_SIGNATURE_do_all_provided()\fR traverses all SIGNATURE implemented by all +activated providers in the given library context \fIlibctx\fR, and for each of the +implementations, calls the given function \fIfn\fR with the implementation method +and the given \fIarg\fR as argument. +.PP +\&\fBEVP_SIGNATURE_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIsignature\fR. Note that the \fIsignature\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIsignature\fR object and should not be freed by the caller. +.PP +\&\fBEVP_SIGNATURE_names_do_all()\fR traverses all names for \fIsignature\fR, and calls +\&\fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_SIGNATURE_get0_description()\fR returns a description of the \fIsignature\fR, +meant for display and human consumption. The description is at the +discretion of the \fIsignature\fR implementation. +.PP +\&\fBEVP_SIGNATURE_gettable_ctx_params()\fR and \fBEVP_SIGNATURE_settable_ctx_params()\fR +return a constant \fBOSSL_PARAM\fR\|(3) array that describes the names and types of key +parameters that can be retrieved or set by a signature algorithm using +\&\fBEVP_PKEY_CTX_get_params\fR\|(3) and \fBEVP_PKEY_CTX_set_params\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_SIGNATURE_fetch()\fR returns a pointer to an \fBEVP_SIGNATURE\fR for success +or \fBNULL\fR for failure. +.PP +\&\fBEVP_SIGNATURE_up_ref()\fR returns 1 for success or 0 otherwise. +.PP +\&\fBEVP_SIGNATURE_names_do_all()\fR returns 1 if the callback was called for all names. +A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_SIGNATURE_gettable_ctx_params()\fR and \fBEVP_SIGNATURE_settable_ctx_params()\fR +return a constant \fBOSSL_PARAM\fR\|(3) array or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), \fBOSSL_PROVIDER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_SKEY.3 b/static/netbsd/man3/EVP_SKEY.3 new file mode 100644 index 00000000..df1ce136 --- /dev/null +++ b/static/netbsd/man3/EVP_SKEY.3 @@ -0,0 +1,212 @@ +.\" $NetBSD: EVP_SKEY.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SKEY 3" +.TH EVP_SKEY 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SKEY, EVP_SKEY_generate, +EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref, +EVP_SKEY_export, EVP_SKEY_get0_raw_key, EVP_SKEY_get0_key_id, +EVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name, +EVP_SKEY_free, EVP_SKEY_is_a, EVP_SKEY_to_provider +\&\- opaque symmetric key allocation and handling functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef evp_skey_st EVP_SKEY; +\& +\& EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname, +\& const char *propquery, const OSSL_PARAM *params); +\& EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname, +\& const char *propquery, +\& int selection, const OSSL_PARAM *params); +\& EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname, +\& unsigned char *key, size_t len, +\& const char *propquery); +\& int EVP_SKEY_export(const EVP_SKEY *skey, int selection, +\& OSSL_CALLBACK *export_cb, void *export_cbarg); +\& int EVP_SKEY_get0_raw_key(const EVP_SKEY *skey, const unsigned char **key, +\& size_t *len); +\& const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey); +\& +\& const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey); +\& const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey); +\& +\& int EVP_SKEY_up_ref(EVP_SKEY *key); +\& void EVP_SKEY_free(EVP_SKEY *key); +\& int EVP_SKEY_is_a(const EVP_SKEY *skey, const char *name); +\& EVP_SKEY *EVP_SKEY_to_provider(EVP_SKEY *skey, OSSL_LIB_CTX *libctx, +\& OSSL_PROVIDER *prov, const char *propquery); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_SKEY\fR is a generic structure to hold symmetric keys as opaque objects. +The keys themselves are often referred to as the "internal key", and are handled by +providers using \fBEVP_SKEYMGMT\fR\|(3). +.PP +Conceptually, an \fBEVP_SKEY\fR internal key may hold a symmetric key, and along +with those, key parameters if the key type requires them. +.PP +The \fBEVP_SKEY_generate()\fR functions creates a new \fBEVP_SKEY\fR object and +initializes it according to the \fBparams\fR argument. +.PP +The \fBEVP_SKEY_import()\fR function allocates an empty \fBEVP_SKEY\fR structure +which is used by OpenSSL to store symmetric keys, assigns the +\&\fBEVP_SKEYMGMT\fR object associated with the key, and initializes the object from +the \fBparams\fR argument. +.PP +The \fBEVP_SKEY_import_raw_key()\fR function is a helper that creates an \fBEVP_SKEY\fR +object containing the raw byte representation of the symmetric keys from the +buffer \fIkey\fR having length \fIlen\fR. The \fIskeymgmtname\fR defines the name of the +target \fBEVP_SKEYMGMT\fR for the newly created key. +.PP +The \fBEVP_SKEY_export()\fR function extracts values from a key \fIskey\fR using the +\&\fIselection\fR. \fIselection\fR is described below. It uses a callback \fIexport_cb\fR +that gets passed the value of \fIexport_cbarg\fR. See \fBopenssl\-core.h\fR\|(7) for +more information about the callback. Note that the \fBOSSL_PARAM\fR\|(3) array that +is passed to the callback is not persistent after the callback returns. +.PP +The \fBEVP_SKEY_get0_raw_key()\fR returns a pointer to a raw key bytes to the passed +address and sets the key len. The returned address is managed by the internal +key management and shouldn\*(Aqt be freed explicitly. The operation can fail when +the underlying key management doesn\*(Aqt support export of the secret key. +.PP +The \fBEVP_SKEY_get0_key_id()\fR returns a NUL\-terminated string providing some +human\-readable identifier of the key if provided by the underlying key +management. The pointer becomes invalid after freeing the EVP_SKEY object. +.PP +The \fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the +names of the associated EVP_SKEYMGMT object and its provider correspondingly. +.PP +\&\fBEVP_SKEY_up_ref()\fR increments the reference count of \fIkey\fR. +.PP +\&\fBEVP_SKEY_free()\fR decrements the reference count of \fIkey\fR and, if the reference +count is zero, frees it. If \fIkey\fR is NULL, nothing is done. +.PP +\&\fBEVP_SKEY_is_a()\fR checks if the key type of \fIskey\fR is \fIname\fR. +.PP +\&\fBEVP_SKEY_to_provider()\fR simplifies the task of importing a \fIskey\fR into a +different provider identified by \fIprov\fR. If \fIprov\fR is NULL, the default +provider for the key type identified via \fIskey\fR is used. +.SS Selections +.IX Subsection "Selections" +The following constants can be used for \fIselection\fR: +.IP \fBOSSL_SKEYMGMT_SELECT_SECRET_KEY\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_SECRET_KEY" +Only the raw key representation will be selected. +.IP \fBOSSL_SKEYMGMT_SELECT_PARAMETERS\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_PARAMETERS" +Only the key parameters will be selected. This includes optional key +parameters. +.IP \fBOSSL_SKEYMGMT_SELECT_ALL\fR 4 +.IX Item "OSSL_SKEYMGMT_SELECT_ALL" +All parameters will be selected. +.SH NOTES +.IX Header "NOTES" +The \fBEVP_SKEY\fR structure is used by various OpenSSL functions which require a +general symmetric key without reference to any particular algorithm. +.PP +The \fBEVP_SKEY_to_provider()\fR function will fail and return NULL if the origin +key \fIskey\fR cannot be exported from its provider. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_SKEY_generate()\fR, \fBEVP_SKEY_import()\fR and \fBEVP_SKEY_import_raw_key()\fR return +either the newly allocated \fBEVP_SKEY\fR structure or NULL if an error occurred. +.PP +\&\fBEVP_SKEY_get0_key_id()\fR returns either a valid pointer or NULL. +.PP +\&\fBEVP_SKEY_up_ref()\fR returns 1 for success and 0 on failure. +.PP +\&\fBEVP_SKEY_export()\fR and \fBEVP_SKEY_get0_raw_key()\fR return 1 for success and 0 on failure. +.PP +\&\fBEVP_SKEY_get0_skeymgmt_name()\fR and \fBEVP_SKEY_get0_provider_name()\fR return the +names of the associated EVP_SKEYMGMT object and its provider correspondingly. +.PP +\&\fBEVP_SKEY_is_a()\fR returns 1 if \fIskey\fR has the key type \fIname\fR, +otherwise 0. +.PP +\&\fBEVP_SKEY_to_provider()\fR returns a new \fBEVP_SKEY\fR suitable for operations with +the \fIprov\fR provider or NULL in case of failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_SKEYMGMT\fR\|(3), \fBprovider\fR\|(7), \fBOSSL_PARAM\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_SKEY\fR API and functions \fBEVP_SKEY_export()\fR, +\&\fBEVP_SKEY_free()\fR, \fBEVP_SKEY_get0_raw_key()\fR, \fBEVP_SKEY_import()\fR, +\&\fBEVP_SKEY_import_raw_key()\fR, \fBEVP_SKEY_up_ref()\fR, \fBEVP_SKEY_generate()\fR, +\&\fBEVP_SKEY_get0_key_id()\fR, \fBEVP_SKEY_get0_provider_name()\fR, +\&\fBEVP_SKEY_get0_skeymgmt_name()\fR, \fBEVP_SKEY_is_a()\fR, \fBEVP_SKEY_to_provider()\fR +were introduced in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_SKEYMGMT.3 b/static/netbsd/man3/EVP_SKEYMGMT.3 new file mode 100644 index 00000000..55706c38 --- /dev/null +++ b/static/netbsd/man3/EVP_SKEYMGMT.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: EVP_SKEYMGMT.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SKEYMGMT 3" +.TH EVP_SKEYMGMT 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SKEYMGMT, +EVP_SKEYMGMT_fetch, +EVP_SKEYMGMT_up_ref, +EVP_SKEYMGMT_free, +EVP_SKEYMGMT_get0_provider, +EVP_SKEYMGMT_is_a, +EVP_SKEYMGMT_get0_description, +EVP_SKEYMGMT_get0_name, +EVP_SKEYMGMT_do_all_provided, +EVP_SKEYMGMT_names_do_all, +EVP_SKEYMGMT_get0_gen_settable_params, +EVP_SKEYMGMT_get0_imp_settable_params +\&\- EVP key management routines for opaque symmetric keys +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct evp_sskeymgmt_st EVP_SKEYMGMT; +\& +\& EVP_SKEYMGMT *EVP_SKEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& int EVP_SKEYMGMT_up_ref(EVP_SKEYMGMT *skeymgmt); +\& void EVP_SKEYMGMT_free(EVP_SKEYMGMT *skeymgmt); +\& const OSSL_PROVIDER *EVP_SKEYMGMT_get0_provider(const EVP_SKEYMGMT *skeymgmt); +\& int EVP_SKEYMGMT_is_a(const EVP_SKEYMGMT *skeymgmt, const char *name); +\& const char *EVP_SKEYMGMT_get0_name(const EVP_SKEYMGMT *skeymgmt); +\& const char *EVP_SKEYMGMT_get0_description(const EVP_SKEYMGMT *skeymgmt); +\& +\& void EVP_SKEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_SKEYMGMT *skeymgmt, void *arg), +\& void *arg); +\& int EVP_SKEYMGMT_names_do_all(const EVP_SKEYMGMT *skeymgmt, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const OSSL_PARAM *EVP_SKEYMGMT_get0_gen_settable_params(const EVP_SKEYMGMT *skeymgmt); +\& const OSSL_PARAM *EVP_SKEYMGMT_get0_imp_settable_params(const EVP_SKEYMGMT *skeymgmt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_SKEYMGMT\fR is a method object that represents symmetric key management +implementations for different cryptographic algorithms. This method object +provides functionality to allow providers to import key material from the +outside, as well as export key material to the outside. +.PP +Most of the functionality can only be used internally and has no public +interface, this opaque object is simply passed into other functions when +needed. +.PP +\&\fBEVP_SKEYMGMT_fetch()\fR looks for an algorithm within a provider that +has been loaded into the \fBOSSL_LIB_CTX\fR given by \fIctx\fR, having the +name given by \fIalgorithm\fR and the properties given by \fIproperties\fR. +.PP +\&\fBEVP_SKEYMGMT_up_ref()\fR increments the reference count for the given +\&\fBEVP_SKEYMGMT\fR \fIskeymgmt\fR. +.PP +\&\fBEVP_SKEYMGMT_free()\fR decrements the reference count for the given +\&\fBEVP_SKEYMGMT\fR \fIskeymgmt\fR, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. +.PP +\&\fBEVP_SKEYMGMT_get0_provider()\fR returns the provider that has this particular +implementation. +.PP +\&\fBEVP_SKEYMGMT_is_a()\fR checks if \fIskeymgmt\fR is an implementation of an +algorithm that\*(Aqs identified by \fIname\fR. +.PP +\&\fBEVP_SKEYMGMT_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIskeymgmt\fR. Note that the \fIskeymgmt\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is +retained by the \fIskeymgmt\fR object and should not be freed by the caller. +.PP +\&\fBEVP_SKEYMGMT_names_do_all()\fR traverses all names for the \fIskeymgmt\fR, and +calls \fIfn\fR with each name and \fIdata\fR. +.PP +\&\fBEVP_SKEYMGMT_get0_description()\fR returns a description of the \fIskeymgmt\fR, meant +for display and human consumption. The description is at the discretion +of the \fIskeymgmt\fR implementation. +.PP +\&\fBEVP_SKEYMGMT_do_all_provided()\fR traverses all key \fIskeymgmt\fR implementations by +all activated providers in the library context \fIlibctx\fR, and for each +of the implementations, calls \fIfn\fR with the implementation method and +\&\fIdata\fR as arguments. +.PP +\&\fBEVP_SKEYMGMT_get0_gen_settable_params()\fR and \fBEVP_SKEYMGMT_get0_imp_settable_params()\fR +get a constant \fBOSSL_PARAM\fR\|(3) array that describes the settable parameters +that can be used with \fBEVP_SKEY_generate()\fR and \fBEVP_SKEY_import()\fR correspondingly. +.SH NOTES +.IX Header "NOTES" +\&\fBEVP_SKEYMGMT_fetch()\fR may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses symmetric keys will typically do this. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_SKEYMGMT_fetch()\fR returns a pointer to the key management +implementation represented by an EVP_SKEYMGMT object, or NULL on +error. +.PP +\&\fBEVP_SKEYMGMT_up_ref()\fR returns 1 on success, or 0 on error. +.PP +\&\fBEVP_SKEYMGMT_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.PP +\&\fBEVP_SKEYMGMT_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBEVP_SKEYMGMT_get0_provider()\fR returns a pointer to a provider object, or NULL +on error. +.PP +\&\fBEVP_SKEYMGMT_is_a()\fR returns 1 if \fIskeymgmt\fR was identifiable, otherwise 0. +.PP +\&\fBEVP_SKEYMGMT_get0_name()\fR returns the algorithm name, or NULL on error. +.PP +\&\fBEVP_SKEYMGMT_get0_description()\fR returns a pointer to a description, or NULL if +there isn\*(Aqt one. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_SKEY\fR\|(3), \fBEVP_MD_fetch\fR\|(3), \fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_SKEYMGMT\fR structure and functions +\&\fBEVP_SKEYMGMT_fetch()\fR, +\&\fBEVP_SKEYMGMT_up_ref()\fR, +\&\fBEVP_SKEYMGMT_free()\fR, +\&\fBEVP_SKEYMGMT_get0_provider()\fR, +\&\fBEVP_SKEYMGMT_is_a()\fR, +\&\fBEVP_SKEYMGMT_get0_description()\fR, +\&\fBEVP_SKEYMGMT_get0_name()\fR, +\&\fBEVP_SKEYMGMT_do_all_provided()\fR, +\&\fBEVP_SKEYMGMT_names_do_all()\fR, +\&\fBEVP_SKEYMGMT_get0_gen_settable_params()\fR, +\&\fBEVP_SKEYMGMT_get0_imp_settable_params()\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_SealInit.3 b/static/netbsd/man3/EVP_SealInit.3 new file mode 100644 index 00000000..1447c5b0 --- /dev/null +++ b/static/netbsd/man3/EVP_SealInit.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: EVP_SealInit.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SealInit 3" +.TH EVP_SealInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SealInit, EVP_SealUpdate, EVP_SealFinal \- EVP envelope encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& unsigned char **ek, int *ekl, unsigned char *iv, +\& EVP_PKEY **pubk, int npubk); +\& int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& int *outl, unsigned char *in, int inl); +\& int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP envelope routines are a high\-level interface to envelope +encryption. They generate a random key and IV (if required) then +"envelope" it by using public key encryption. Data can then be +encrypted using this key. +.PP +\&\fBEVP_SealInit()\fR initializes a cipher context \fBctx\fR for encryption +with cipher \fBtype\fR using a random secret key and IV. \fBtype\fR is normally +supplied by a function such as \fBEVP_aes_256_cbc()\fR. The secret key is encrypted +using one or more public keys, this allows the same encrypted data to be +decrypted using any of the corresponding private keys. \fBek\fR is an array of +buffers where the public key encrypted secret key will be written, each buffer +must contain enough room for the corresponding encrypted key: that is +\&\fBek[i]\fR must have room for \fBEVP_PKEY_get_size(pubk[i])\fR bytes. The actual +size of each encrypted secret key is written to the array \fBekl\fR. \fBpubk\fR is +an array of \fBnpubk\fR public keys. +.PP +The \fBiv\fR parameter is a buffer where the generated IV is written to. It must +contain enough room for the corresponding cipher\*(Aqs IV, as determined by (for +example) EVP_CIPHER_get_iv_length(type). +.PP +If the cipher does not require an IV then the \fBiv\fR parameter is ignored +and can be \fBNULL\fR. +.PP +\&\fBEVP_SealUpdate()\fR and \fBEVP_SealFinal()\fR have exactly the same properties +as the \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal()\fR routines, as +documented on the \fBEVP_EncryptInit\fR\|(3) manual +page. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_SealInit()\fR returns 0 on error or \fBnpubk\fR if successful. +.PP +\&\fBEVP_SealUpdate()\fR and \fBEVP_SealFinal()\fR return 1 for success and 0 for +failure. +.SH NOTES +.IX Header "NOTES" +Because a random secret key is generated the random number generator +must be seeded when \fBEVP_SealInit()\fR is called. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +The public key must be RSA because it is the only OpenSSL public key +algorithm that supports key transport. +.PP +Envelope encryption is the usual method of using public key encryption +on large amounts of data, this is because public key encryption is slow +but symmetric encryption is fast. So symmetric encryption is used for +bulk encryption and the small random symmetric key used is transferred +using public key encryption. +.PP +It is possible to call \fBEVP_SealInit()\fR twice in the same way as +\&\fBEVP_EncryptInit()\fR. The first call should have \fBnpubk\fR set to 0 +and (after setting any cipher parameters) it should be called again +with \fBtype\fR set to NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), \fBRAND_bytes\fR\|(3), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_OpenInit\fR\|(3), +\&\fBRAND\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_SignInit.3 b/static/netbsd/man3/EVP_SignInit.3 new file mode 100644 index 00000000..8c19014b --- /dev/null +++ b/static/netbsd/man3/EVP_SignInit.3 @@ -0,0 +1,175 @@ +.\" $NetBSD: EVP_SignInit.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_SignInit 3" +.TH EVP_SignInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, +EVP_SignFinal_ex, EVP_SignFinal +\&\- EVP signing functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); +\& int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); +\& int EVP_SignFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s, +\& EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, const char *propq); +\& int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, +\& EVP_PKEY *pkey); +\& +\& void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP signature routines are a high\-level interface to digital +signatures. +.PP +\&\fBEVP_SignInit_ex()\fR sets up signing context \fIctx\fR to use digest +\&\fItype\fR from \fBENGINE\fR \fIimpl\fR. \fIctx\fR must be created with +\&\fBEVP_MD_CTX_new()\fR before calling this function. +.PP +\&\fBEVP_SignUpdate()\fR hashes \fIcnt\fR bytes of data at \fId\fR into the +signature context \fIctx\fR. This function can be called several times on the +same \fIctx\fR to include additional data. +.PP +\&\fBEVP_SignFinal_ex()\fR signs the data in \fIctx\fR using the private key +\&\fIpkey\fR and places the signature in \fIsig\fR. The library context \fIlibctx\fR and +property query \fIpropq\fR are used when creating a context to use with the key +\&\fIpkey\fR. \fIsig\fR must be at least \f(CWEVP_PKEY_get_size(pkey)\fR bytes in size. +\&\fIs\fR is an OUT parameter, and not used as an IN parameter. +The number of bytes of data written (i.e. the length of the signature) +will be written to the integer at \fIs\fR, at most \f(CWEVP_PKEY_get_size(pkey)\fR +bytes will be written. +.PP +\&\fBEVP_SignFinal()\fR is similar to \fBEVP_SignFinal_ex()\fR but uses default +values of NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR. +.PP +\&\fBEVP_SignInit()\fR initializes a signing context \fIctx\fR to use the default +implementation of digest \fItype\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_SignInit_ex()\fR, \fBEVP_SignUpdate()\fR, \fBEVP_SignFinal_ex()\fR and +\&\fBEVP_SignFinal()\fR return 1 for success and 0 for failure. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The \fBEVP\fR interface to digital signatures should almost always be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. +.PP +When signing with some private key types the random number generator must +be seeded. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails +due to external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +The call to \fBEVP_SignFinal()\fR internally finalizes a copy of the digest context. +This means that calls to \fBEVP_SignUpdate()\fR and \fBEVP_SignFinal()\fR can be called +later to digest and sign additional data.cApplications may disable this +behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via +\&\fBEVP_MD_CTX_set_flags\fR\|(3). +.PP +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling \fBEVP_MD_CTX_free()\fR or a memory leak +will occur. +.PP +Note that not all providers support continuation, in case the selected +provider does not allow to duplicate contexts \fBEVP_SignFinal()\fR will +finalize the digest context and attempting to process additional data via +\&\fBEVP_SignUpdate()\fR will result in an error. +.SH BUGS +.IX Header "BUGS" +Older versions of this documentation wrongly stated that calls to +\&\fBEVP_SignUpdate()\fR could not be made after calling \fBEVP_SignFinal()\fR. +.PP +Since the private key is passed in the call to \fBEVP_SignFinal()\fR any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through \fBEVP_SignUpdate()\fR. +.PP +It is not possible to change the signing parameters using these function. +.PP +The previous two bugs are fixed in the newer EVP_DigestSign*() functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_size\fR\|(3), \fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3), +\&\fBEVP_VerifyInit\fR\|(3), +\&\fBEVP_DigestInit\fR\|(3), +\&\fBevp\fR\|(7), \fBHMAC\fR\|(3), \fBMD2\fR\|(3), +\&\fBMD5\fR\|(3), \fBMDC2\fR\|(3), \fBRIPEMD160\fR\|(3), +\&\fBSHA1\fR\|(3), \fBopenssl\-dgst\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The function \fBEVP_SignFinal_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_VerifyInit.3 b/static/netbsd/man3/EVP_VerifyInit.3 new file mode 100644 index 00000000..f0ac9086 --- /dev/null +++ b/static/netbsd/man3/EVP_VerifyInit.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: EVP_VerifyInit.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_VerifyInit 3" +.TH EVP_VerifyInit 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_VerifyInit_ex, +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal_ex, EVP_VerifyFinal +\&\- EVP signature verification functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); +\& int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); +\& int EVP_VerifyFinal_ex(EVP_MD_CTX *ctx, const unsigned char *sigbuf, +\& unsigned int siglen, EVP_PKEY *pkey, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, +\& EVP_PKEY *pkey); +\& +\& int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The EVP signature verification routines are a high\-level interface to digital +signatures. +.PP +\&\fBEVP_VerifyInit_ex()\fR sets up verification context \fIctx\fR to use digest +\&\fItype\fR from ENGINE \fIimpl\fR. \fIctx\fR must be created by calling +\&\fBEVP_MD_CTX_new()\fR before calling this function. +.PP +\&\fBEVP_VerifyUpdate()\fR hashes \fIcnt\fR bytes of data at \fId\fR into the +verification context \fIctx\fR. This function can be called several times on the +same \fIctx\fR to include additional data. +.PP +\&\fBEVP_VerifyFinal_ex()\fR verifies the data in \fIctx\fR using the public key +\&\fIpkey\fR and \fIsiglen\fR bytes in \fIsigbuf\fR. +The library context \fIlibctx\fR and property query \fIpropq\fR are used when creating +a context to use with the key \fIpkey\fR. +.PP +\&\fBEVP_VerifyFinal()\fR is similar to \fBEVP_VerifyFinal_ex()\fR but uses default +values of NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR. +.PP +\&\fBEVP_VerifyInit()\fR initializes verification context \fIctx\fR to use the default +implementation of digest \fItype\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_VerifyInit_ex()\fR and \fBEVP_VerifyUpdate()\fR return 1 for success and 0 for +failure. +.PP +\&\fBEVP_VerifyFinal_ex()\fR and \fBEVP_VerifyFinal()\fR return 1 for a correct +signature, 0 for failure and a negative value if some other error occurred. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The \fBEVP\fR interface to digital signatures should almost always be used in +preference to the low\-level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. +.PP +The call to \fBEVP_VerifyFinal()\fR internally finalizes a copy of the digest context. +This means that calls to \fBEVP_VerifyUpdate()\fR and \fBEVP_VerifyFinal()\fR can be called +later to digest and verify additional data. Applications may disable this +behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via +\&\fBEVP_MD_CTX_set_flags\fR\|(3). +.PP +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling \fBEVP_MD_CTX_free()\fR or a memory leak +will occur. +.PP +Note that not all providers support continuation, in case the selected +provider does not allow to duplicate contexts \fBEVP_VerifyFinal()\fR will +finalize the digest context and attempting to process additional data via +\&\fBEVP_VerifyUpdate()\fR will result in an error. +.SH BUGS +.IX Header "BUGS" +Older versions of this documentation wrongly stated that calls to +\&\fBEVP_VerifyUpdate()\fR could not be made after calling \fBEVP_VerifyFinal()\fR. +.PP +Since the public key is passed in the call to \fBEVP_SignFinal()\fR any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through \fBEVP_SignUpdate()\fR. +.PP +It is not possible to change the signing parameters using these function. +.PP +The previous two bugs are fixed in the newer EVP_DigestVerify*() function. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_SignInit\fR\|(3), +\&\fBEVP_DigestInit\fR\|(3), +\&\fBevp\fR\|(7), \fBHMAC\fR\|(3), \fBMD2\fR\|(3), +\&\fBMD5\fR\|(3), \fBMDC2\fR\|(3), \fBRIPEMD160\fR\|(3), +\&\fBSHA1\fR\|(3), \fBopenssl\-dgst\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The function \fBEVP_VerifyFinal_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_aes.3 b/static/netbsd/man3/EVP_aes.3 new file mode 100644 index 00000000..61aeb2a0 --- /dev/null +++ b/static/netbsd/man3/EVP_aes.3 @@ -0,0 +1,272 @@ +.\" $NetBSD: EVP_aes.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_aes 3" +.TH EVP_aes 3 "2020-04-24" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_aes_128_cbc, +EVP_aes_192_cbc, +EVP_aes_256_cbc, +EVP_aes_128_cfb, +EVP_aes_192_cfb, +EVP_aes_256_cfb, +EVP_aes_128_cfb1, +EVP_aes_192_cfb1, +EVP_aes_256_cfb1, +EVP_aes_128_cfb8, +EVP_aes_192_cfb8, +EVP_aes_256_cfb8, +EVP_aes_128_cfb128, +EVP_aes_192_cfb128, +EVP_aes_256_cfb128, +EVP_aes_128_ctr, +EVP_aes_192_ctr, +EVP_aes_256_ctr, +EVP_aes_128_ecb, +EVP_aes_192_ecb, +EVP_aes_256_ecb, +EVP_aes_128_ofb, +EVP_aes_192_ofb, +EVP_aes_256_ofb, +EVP_aes_128_cbc_hmac_sha1, +EVP_aes_256_cbc_hmac_sha1, +EVP_aes_128_cbc_hmac_sha256, +EVP_aes_256_cbc_hmac_sha256, +EVP_aes_128_ccm, +EVP_aes_192_ccm, +EVP_aes_256_ccm, +EVP_aes_128_gcm, +EVP_aes_192_gcm, +EVP_aes_256_gcm, +EVP_aes_128_ocb, +EVP_aes_192_ocb, +EVP_aes_256_ocb, +EVP_aes_128_wrap, +EVP_aes_192_wrap, +EVP_aes_256_wrap, +EVP_aes_128_wrap_pad, +EVP_aes_192_wrap_pad, +EVP_aes_256_wrap_pad, +EVP_aes_128_xts, +EVP_aes_256_xts +\&\- EVP AES cipher +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_aes_128_cbc\fR. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1AES\s0 encryption algorithm for \s-1EVP.\s0 +.IP "\fBEVP_aes_128_cbc()\fR, \fBEVP_aes_192_cbc()\fR, \fBEVP_aes_256_cbc()\fR, \fBEVP_aes_128_cfb()\fR, \fBEVP_aes_192_cfb()\fR, \fBEVP_aes_256_cfb()\fR, \fBEVP_aes_128_cfb1()\fR, \fBEVP_aes_192_cfb1()\fR, \fBEVP_aes_256_cfb1()\fR, \fBEVP_aes_128_cfb8()\fR, \fBEVP_aes_192_cfb8()\fR, \fBEVP_aes_256_cfb8()\fR, \fBEVP_aes_128_cfb128()\fR, \fBEVP_aes_192_cfb128()\fR, \fBEVP_aes_256_cfb128()\fR, \fBEVP_aes_128_ctr()\fR, \fBEVP_aes_192_ctr()\fR, \fBEVP_aes_256_ctr()\fR, \fBEVP_aes_128_ecb()\fR, \fBEVP_aes_192_ecb()\fR, \fBEVP_aes_256_ecb()\fR, \fBEVP_aes_128_ofb()\fR, \fBEVP_aes_192_ofb()\fR, \fBEVP_aes_256_ofb()\fR" 4 +.IX Item "EVP_aes_128_cbc(), EVP_aes_192_cbc(), EVP_aes_256_cbc(), EVP_aes_128_cfb(), EVP_aes_192_cfb(), EVP_aes_256_cfb(), EVP_aes_128_cfb1(), EVP_aes_192_cfb1(), EVP_aes_256_cfb1(), EVP_aes_128_cfb8(), EVP_aes_192_cfb8(), EVP_aes_256_cfb8(), EVP_aes_128_cfb128(), EVP_aes_192_cfb128(), EVP_aes_256_cfb128(), EVP_aes_128_ctr(), EVP_aes_192_ctr(), EVP_aes_256_ctr(), EVP_aes_128_ecb(), EVP_aes_192_ecb(), EVP_aes_256_ecb(), EVP_aes_128_ofb(), EVP_aes_192_ofb(), EVP_aes_256_ofb()" +\&\s-1AES\s0 for 128, 192 and 256 bit keys in the following modes: \s-1CBC, CFB\s0 with 128\-bit +shift, \s-1CFB\s0 with 1\-bit shift, \s-1CFB\s0 with 8\-bit shift, \s-1CTR, ECB,\s0 and \s-1OFB.\s0 +.IP "\fBEVP_aes_128_cbc_hmac_sha1()\fR, \fBEVP_aes_256_cbc_hmac_sha1()\fR" 4 +.IX Item "EVP_aes_128_cbc_hmac_sha1(), EVP_aes_256_cbc_hmac_sha1()" +Authenticated encryption with \s-1AES\s0 in \s-1CBC\s0 mode using \s-1SHA\-1\s0 as \s-1HMAC,\s0 with keys of +128 and 256 bits length respectively. The authentication tag is 160 bits long. +.Sp +\&\s-1WARNING:\s0 this is not intended for usage outside of \s-1TLS\s0 and requires calling of +some undocumented ctrl functions. These ciphers do not conform to the \s-1EVP AEAD\s0 +interface. +.IP "\fBEVP_aes_128_cbc_hmac_sha256()\fR, \fBEVP_aes_256_cbc_hmac_sha256()\fR" 4 +.IX Item "EVP_aes_128_cbc_hmac_sha256(), EVP_aes_256_cbc_hmac_sha256()" +Authenticated encryption with \s-1AES\s0 in \s-1CBC\s0 mode using \s-1SHA256\s0 (\s-1SHA\-2,\s0 256\-bits) as +\&\s-1HMAC,\s0 with keys of 128 and 256 bits length respectively. The authentication tag +is 256 bits long. +.Sp +\&\s-1WARNING:\s0 this is not intended for usage outside of \s-1TLS\s0 and requires calling of +some undocumented ctrl functions. These ciphers do not conform to the \s-1EVP AEAD\s0 +interface. +.IP "\fBEVP_aes_128_ccm()\fR, \fBEVP_aes_192_ccm()\fR, \fBEVP_aes_256_ccm()\fR, \fBEVP_aes_128_gcm()\fR, \fBEVP_aes_192_gcm()\fR, \fBEVP_aes_256_gcm()\fR, \fBEVP_aes_128_ocb()\fR, \fBEVP_aes_192_ocb()\fR, \fBEVP_aes_256_ocb()\fR" 4 +.IX Item "EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm(), EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm(), EVP_aes_128_ocb(), EVP_aes_192_ocb(), EVP_aes_256_ocb()" +\&\s-1AES\s0 for 128, 192 and 256 bit keys in CBC-MAC Mode (\s-1CCM\s0), Galois Counter Mode +(\s-1GCM\s0) and \s-1OCB\s0 Mode respectively. These ciphers require additional control +operations to function correctly, see the \*(L"\s-1AEAD\s0 Interface\*(R" in \fBEVP_EncryptInit\fR\|(3) +section for details. +.IP "\fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_128_wrap_pad()\fR, \fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_192_wrap_pad()\fR, \fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_256_wrap_pad()\fR" 4 +.IX Item "EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_128_wrap_pad(), EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_192_wrap_pad(), EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_256_wrap_pad()" +\&\s-1AES\s0 key wrap with 128, 192 and 256 bit keys, as according to \s-1RFC 3394\s0 section +2.2.1 (\*(L"wrap\*(R") and \s-1RFC 5649\s0 section 4.1 (\*(L"wrap with padding\*(R") respectively. +.IP "\fBEVP_aes_128_xts()\fR, \fBEVP_aes_256_xts()\fR" 4 +.IX Item "EVP_aes_128_xts(), EVP_aes_256_xts()" +\&\s-1AES XTS\s0 mode (XTS-AES) is standardized in \s-1IEEE\s0 Std. 1619\-2007 and described in \s-1NIST +SP 800\-38E.\s0 The \s-1XTS\s0 (XEX-based tweaked-codebook mode with ciphertext stealing) +mode was designed by Prof. Phillip Rogaway of University of California, Davis, +intended for encrypting data on a storage device. +.Sp +XTS-AES provides confidentiality but not authentication of data. It also +requires a key of double-length for protection of a certain key size. +In particular, \s-1XTS\-AES\-128\s0 (\fBEVP_aes_128_xts\fR) takes input of a 256\-bit key to +achieve \s-1AES\s0 128\-bit security, and \s-1XTS\-AES\-256\s0 (\fBEVP_aes_256_xts\fR) takes input +of a 512\-bit key to achieve \s-1AES\s0 256\-bit security. +.Sp +The \s-1XTS\s0 implementation in OpenSSL does not support streaming. That is there must +only be one \fBEVP_EncryptUpdate\fR\|(3) call per \fBEVP_EncryptInit_ex\fR\|(3) call (and +similarly with the \*(L"Decrypt\*(R" functions). +.Sp +The \fIiv\fR parameter to \fBEVP_EncryptInit_ex\fR\|(3) or \fBEVP_DecryptInit_ex\fR\|(3) is +the \s-1XTS\s0 \*(L"tweak\*(R" value. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fB\s-1EVP_CIPHER\s0\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fB\s-1EVP_CIPHER\s0\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_aes_128_cbc.3 b/static/netbsd/man3/EVP_aes_128_cbc.3 new file mode 100644 index 00000000..470bd638 --- /dev/null +++ b/static/netbsd/man3/EVP_aes_128_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_128_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aes_128_cfb8.3 b/static/netbsd/man3/EVP_aes_128_cfb8.3 new file mode 100644 index 00000000..a45e52ae --- /dev/null +++ b/static/netbsd/man3/EVP_aes_128_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_128_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aes_128_gcm.3 b/static/netbsd/man3/EVP_aes_128_gcm.3 new file mode 100644 index 00000000..2cbdc33a --- /dev/null +++ b/static/netbsd/man3/EVP_aes_128_gcm.3 @@ -0,0 +1,201 @@ +.\" $NetBSD: EVP_aes_128_gcm.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_aes_128_gcm 3" +.TH EVP_aes_128_gcm 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_aes_128_cbc, +EVP_aes_192_cbc, +EVP_aes_256_cbc, +EVP_aes_128_cfb, +EVP_aes_192_cfb, +EVP_aes_256_cfb, +EVP_aes_128_cfb1, +EVP_aes_192_cfb1, +EVP_aes_256_cfb1, +EVP_aes_128_cfb8, +EVP_aes_192_cfb8, +EVP_aes_256_cfb8, +EVP_aes_128_cfb128, +EVP_aes_192_cfb128, +EVP_aes_256_cfb128, +EVP_aes_128_ctr, +EVP_aes_192_ctr, +EVP_aes_256_ctr, +EVP_aes_128_ecb, +EVP_aes_192_ecb, +EVP_aes_256_ecb, +EVP_aes_128_ofb, +EVP_aes_192_ofb, +EVP_aes_256_ofb, +EVP_aes_128_cbc_hmac_sha1, +EVP_aes_256_cbc_hmac_sha1, +EVP_aes_128_cbc_hmac_sha256, +EVP_aes_256_cbc_hmac_sha256, +EVP_aes_128_ccm, +EVP_aes_192_ccm, +EVP_aes_256_ccm, +EVP_aes_128_gcm, +EVP_aes_192_gcm, +EVP_aes_256_gcm, +EVP_aes_128_ocb, +EVP_aes_192_ocb, +EVP_aes_256_ocb, +EVP_aes_128_wrap, +EVP_aes_192_wrap, +EVP_aes_256_wrap, +EVP_aes_128_wrap_pad, +EVP_aes_192_wrap_pad, +EVP_aes_256_wrap_pad, +EVP_aes_128_xts, +EVP_aes_256_xts +\&\- EVP AES cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_aes_128_cbc\fR. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The AES encryption algorithm for EVP. +.IP "\fBEVP_aes_128_cbc()\fR, \fBEVP_aes_192_cbc()\fR, \fBEVP_aes_256_cbc()\fR, \fBEVP_aes_128_cfb()\fR, \fBEVP_aes_192_cfb()\fR, \fBEVP_aes_256_cfb()\fR, \fBEVP_aes_128_cfb1()\fR, \fBEVP_aes_192_cfb1()\fR, \fBEVP_aes_256_cfb1()\fR, \fBEVP_aes_128_cfb8()\fR, \fBEVP_aes_192_cfb8()\fR, \fBEVP_aes_256_cfb8()\fR, \fBEVP_aes_128_cfb128()\fR, \fBEVP_aes_192_cfb128()\fR, \fBEVP_aes_256_cfb128()\fR, \fBEVP_aes_128_ctr()\fR, \fBEVP_aes_192_ctr()\fR, \fBEVP_aes_256_ctr()\fR, \fBEVP_aes_128_ecb()\fR, \fBEVP_aes_192_ecb()\fR, \fBEVP_aes_256_ecb()\fR, \fBEVP_aes_128_ofb()\fR, \fBEVP_aes_192_ofb()\fR, \fBEVP_aes_256_ofb()\fR" 4 +.IX Item "EVP_aes_128_cbc(), EVP_aes_192_cbc(), EVP_aes_256_cbc(), EVP_aes_128_cfb(), EVP_aes_192_cfb(), EVP_aes_256_cfb(), EVP_aes_128_cfb1(), EVP_aes_192_cfb1(), EVP_aes_256_cfb1(), EVP_aes_128_cfb8(), EVP_aes_192_cfb8(), EVP_aes_256_cfb8(), EVP_aes_128_cfb128(), EVP_aes_192_cfb128(), EVP_aes_256_cfb128(), EVP_aes_128_ctr(), EVP_aes_192_ctr(), EVP_aes_256_ctr(), EVP_aes_128_ecb(), EVP_aes_192_ecb(), EVP_aes_256_ecb(), EVP_aes_128_ofb(), EVP_aes_192_ofb(), EVP_aes_256_ofb()" +AES for 128, 192 and 256 bit keys in the following modes: CBC, CFB with 128\-bit +shift, CFB with 1\-bit shift, CFB with 8\-bit shift, CTR, ECB, and OFB. +.IP "\fBEVP_aes_128_cbc_hmac_sha1()\fR, \fBEVP_aes_256_cbc_hmac_sha1()\fR" 4 +.IX Item "EVP_aes_128_cbc_hmac_sha1(), EVP_aes_256_cbc_hmac_sha1()" +Authenticated encryption with AES in CBC mode using SHA\-1 as HMAC, with keys of +128 and 256 bits length respectively. The authentication tag is 160 bits long. +.Sp +WARNING: this is not intended for usage outside of TLS and requires calling of +some undocumented ctrl functions. These ciphers do not conform to the EVP AEAD +interface. +.IP "\fBEVP_aes_128_cbc_hmac_sha256()\fR, \fBEVP_aes_256_cbc_hmac_sha256()\fR" 4 +.IX Item "EVP_aes_128_cbc_hmac_sha256(), EVP_aes_256_cbc_hmac_sha256()" +Authenticated encryption with AES in CBC mode using SHA256 (SHA\-2, 256\-bits) as +HMAC, with keys of 128 and 256 bits length respectively. The authentication tag +is 256 bits long. +.Sp +WARNING: this is not intended for usage outside of TLS and requires calling of +some undocumented ctrl functions. These ciphers do not conform to the EVP AEAD +interface. +.IP "\fBEVP_aes_128_ccm()\fR, \fBEVP_aes_192_ccm()\fR, \fBEVP_aes_256_ccm()\fR, \fBEVP_aes_128_gcm()\fR, \fBEVP_aes_192_gcm()\fR, \fBEVP_aes_256_gcm()\fR, \fBEVP_aes_128_ocb()\fR, \fBEVP_aes_192_ocb()\fR, \fBEVP_aes_256_ocb()\fR" 4 +.IX Item "EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm(), EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm(), EVP_aes_128_ocb(), EVP_aes_192_ocb(), EVP_aes_256_ocb()" +AES for 128, 192 and 256 bit keys in CBC\-MAC Mode (CCM), Galois Counter Mode +(GCM) and OCB Mode respectively. These ciphers require additional control +operations to function correctly, see the "AEAD INTERFACE" in \fBEVP_EncryptInit\fR\|(3) +section for details. +.IP "\fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_128_wrap_pad()\fR, \fBEVP_aes_192_wrap_pad()\fR, \fBEVP_aes_256_wrap_pad()\fR" 4 +.IX Item "EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_128_wrap_pad(), EVP_aes_192_wrap_pad(), EVP_aes_256_wrap_pad()" +AES key wrap with 128, 192 and 256 bit keys, as according to RFC 3394 section +2.2.1 ("wrap") and RFC 5649 section 4.1 ("wrap with padding") respectively. +.IP "\fBEVP_aes_128_xts()\fR, \fBEVP_aes_256_xts()\fR" 4 +.IX Item "EVP_aes_128_xts(), EVP_aes_256_xts()" +AES XTS mode (XTS\-AES) is standardized in IEEE Std. 1619\-2007 and described in NIST +SP 800\-38E. The XTS (XEX\-based tweaked\-codebook mode with ciphertext stealing) +mode was designed by Prof. Phillip Rogaway of University of California, Davis, +intended for encrypting data on a storage device. +.Sp +XTS\-AES provides confidentiality but not authentication of data. It also +requires a key of double\-length for protection of a certain key size. +In particular, XTS\-AES\-128 (\fBEVP_aes_128_xts\fR) takes input of a 256\-bit key to +achieve AES 128\-bit security, and XTS\-AES\-256 (\fBEVP_aes_256_xts\fR) takes input +of a 512\-bit key to achieve AES 256\-bit security. +.Sp +The XTS implementation in OpenSSL does not support streaming. That is there must +only be one \fBEVP_EncryptUpdate\fR\|(3) call per \fBEVP_EncryptInit_ex\fR\|(3) call (and +similarly with the "Decrypt" functions). +.Sp +The \fIiv\fR parameter to \fBEVP_EncryptInit_ex\fR\|(3) or \fBEVP_DecryptInit_ex\fR\|(3) is +the XTS "tweak" value. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-AES\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_aes_192_cbc.3 b/static/netbsd/man3/EVP_aes_192_cbc.3 new file mode 100644 index 00000000..72ad22ee --- /dev/null +++ b/static/netbsd/man3/EVP_aes_192_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_192_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aes_192_cfb8.3 b/static/netbsd/man3/EVP_aes_192_cfb8.3 new file mode 100644 index 00000000..738547f8 --- /dev/null +++ b/static/netbsd/man3/EVP_aes_192_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_192_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aes_256_cbc.3 b/static/netbsd/man3/EVP_aes_256_cbc.3 new file mode 100644 index 00000000..fb7757c8 --- /dev/null +++ b/static/netbsd/man3/EVP_aes_256_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_256_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aes_256_cfb8.3 b/static/netbsd/man3/EVP_aes_256_cfb8.3 new file mode 100644 index 00000000..2bbba08d --- /dev/null +++ b/static/netbsd/man3/EVP_aes_256_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_aes_256_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_aria.3 b/static/netbsd/man3/EVP_aria.3 new file mode 100644 index 00000000..78c97fdf --- /dev/null +++ b/static/netbsd/man3/EVP_aria.3 @@ -0,0 +1,216 @@ +.\" $NetBSD: EVP_aria.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_aria 3" +.TH EVP_aria 3 "2020-01-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_aria_128_cbc, +EVP_aria_192_cbc, +EVP_aria_256_cbc, +EVP_aria_128_cfb, +EVP_aria_192_cfb, +EVP_aria_256_cfb, +EVP_aria_128_cfb1, +EVP_aria_192_cfb1, +EVP_aria_256_cfb1, +EVP_aria_128_cfb8, +EVP_aria_192_cfb8, +EVP_aria_256_cfb8, +EVP_aria_128_cfb128, +EVP_aria_192_cfb128, +EVP_aria_256_cfb128, +EVP_aria_128_ctr, +EVP_aria_192_ctr, +EVP_aria_256_ctr, +EVP_aria_128_ecb, +EVP_aria_192_ecb, +EVP_aria_256_ecb, +EVP_aria_128_ofb, +EVP_aria_192_ofb, +EVP_aria_256_ofb, +EVP_aria_128_ccm, +EVP_aria_192_ccm, +EVP_aria_256_ccm, +EVP_aria_128_gcm, +EVP_aria_192_gcm, +EVP_aria_256_gcm, +\&\- EVP ARIA cipher +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_aria_128_cbc\fR. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1ARIA\s0 encryption algorithm for \s-1EVP.\s0 +.IP "\fBEVP_aria_128_cbc()\fR, \fBEVP_aria_192_cbc()\fR, \fBEVP_aria_256_cbc()\fR, \fBEVP_aria_128_cfb()\fR, \fBEVP_aria_192_cfb()\fR, \fBEVP_aria_256_cfb()\fR, \fBEVP_aria_128_cfb1()\fR, \fBEVP_aria_192_cfb1()\fR, \fBEVP_aria_256_cfb1()\fR, \fBEVP_aria_128_cfb8()\fR, \fBEVP_aria_192_cfb8()\fR, \fBEVP_aria_256_cfb8()\fR, \fBEVP_aria_128_cfb128()\fR, \fBEVP_aria_192_cfb128()\fR, \fBEVP_aria_256_cfb128()\fR, \fBEVP_aria_128_ctr()\fR, \fBEVP_aria_192_ctr()\fR, \fBEVP_aria_256_ctr()\fR, \fBEVP_aria_128_ecb()\fR, \fBEVP_aria_192_ecb()\fR, \fBEVP_aria_256_ecb()\fR, \fBEVP_aria_128_ofb()\fR, \fBEVP_aria_192_ofb()\fR, \fBEVP_aria_256_ofb()\fR" 4 +.IX Item "EVP_aria_128_cbc(), EVP_aria_192_cbc(), EVP_aria_256_cbc(), EVP_aria_128_cfb(), EVP_aria_192_cfb(), EVP_aria_256_cfb(), EVP_aria_128_cfb1(), EVP_aria_192_cfb1(), EVP_aria_256_cfb1(), EVP_aria_128_cfb8(), EVP_aria_192_cfb8(), EVP_aria_256_cfb8(), EVP_aria_128_cfb128(), EVP_aria_192_cfb128(), EVP_aria_256_cfb128(), EVP_aria_128_ctr(), EVP_aria_192_ctr(), EVP_aria_256_ctr(), EVP_aria_128_ecb(), EVP_aria_192_ecb(), EVP_aria_256_ecb(), EVP_aria_128_ofb(), EVP_aria_192_ofb(), EVP_aria_256_ofb()" +\&\s-1ARIA\s0 for 128, 192 and 256 bit keys in the following modes: \s-1CBC, CFB\s0 with +128\-bit shift, \s-1CFB\s0 with 1\-bit shift, \s-1CFB\s0 with 8\-bit shift, \s-1CTR, ECB\s0 and \s-1OFB.\s0 +.IP "\fBEVP_aria_128_ccm()\fR, \fBEVP_aria_192_ccm()\fR, \fBEVP_aria_256_ccm()\fR, \fBEVP_aria_128_gcm()\fR, \fBEVP_aria_192_gcm()\fR, \fBEVP_aria_256_gcm()\fR," 4 +.IX Item "EVP_aria_128_ccm(), EVP_aria_192_ccm(), EVP_aria_256_ccm(), EVP_aria_128_gcm(), EVP_aria_192_gcm(), EVP_aria_256_gcm()," +\&\s-1ARIA\s0 for 128, 192 and 256 bit keys in CBC-MAC Mode (\s-1CCM\s0) and Galois Counter +Mode (\s-1GCM\s0). These ciphers require additional control operations to function +correctly, see the \*(L"\s-1AEAD\s0 Interface\*(R" in \fBEVP_EncryptInit\fR\|(3) section for details. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fB\s-1EVP_CIPHER\s0\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fB\s-1EVP_CIPHER\s0\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_aria_128_gcm.3 b/static/netbsd/man3/EVP_aria_128_gcm.3 new file mode 100644 index 00000000..b33249b5 --- /dev/null +++ b/static/netbsd/man3/EVP_aria_128_gcm.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: EVP_aria_128_gcm.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_aria_128_gcm 3" +.TH EVP_aria_128_gcm 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_aria_128_cbc, +EVP_aria_192_cbc, +EVP_aria_256_cbc, +EVP_aria_128_cfb, +EVP_aria_192_cfb, +EVP_aria_256_cfb, +EVP_aria_128_cfb1, +EVP_aria_192_cfb1, +EVP_aria_256_cfb1, +EVP_aria_128_cfb8, +EVP_aria_192_cfb8, +EVP_aria_256_cfb8, +EVP_aria_128_cfb128, +EVP_aria_192_cfb128, +EVP_aria_256_cfb128, +EVP_aria_128_ctr, +EVP_aria_192_ctr, +EVP_aria_256_ctr, +EVP_aria_128_ecb, +EVP_aria_192_ecb, +EVP_aria_256_ecb, +EVP_aria_128_ofb, +EVP_aria_192_ofb, +EVP_aria_256_ofb, +EVP_aria_128_ccm, +EVP_aria_192_ccm, +EVP_aria_256_ccm, +EVP_aria_128_gcm, +EVP_aria_192_gcm, +EVP_aria_256_gcm, +\&\- EVP ARIA cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_aria_128_cbc\fR. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The ARIA encryption algorithm for EVP. +.IP "\fBEVP_aria_128_cbc()\fR, \fBEVP_aria_192_cbc()\fR, \fBEVP_aria_256_cbc()\fR, \fBEVP_aria_128_cfb()\fR, \fBEVP_aria_192_cfb()\fR, \fBEVP_aria_256_cfb()\fR, \fBEVP_aria_128_cfb1()\fR, \fBEVP_aria_192_cfb1()\fR, \fBEVP_aria_256_cfb1()\fR, \fBEVP_aria_128_cfb8()\fR, \fBEVP_aria_192_cfb8()\fR, \fBEVP_aria_256_cfb8()\fR, \fBEVP_aria_128_cfb128()\fR, \fBEVP_aria_192_cfb128()\fR, \fBEVP_aria_256_cfb128()\fR, \fBEVP_aria_128_ctr()\fR, \fBEVP_aria_192_ctr()\fR, \fBEVP_aria_256_ctr()\fR, \fBEVP_aria_128_ecb()\fR, \fBEVP_aria_192_ecb()\fR, \fBEVP_aria_256_ecb()\fR, \fBEVP_aria_128_ofb()\fR, \fBEVP_aria_192_ofb()\fR, \fBEVP_aria_256_ofb()\fR" 4 +.IX Item "EVP_aria_128_cbc(), EVP_aria_192_cbc(), EVP_aria_256_cbc(), EVP_aria_128_cfb(), EVP_aria_192_cfb(), EVP_aria_256_cfb(), EVP_aria_128_cfb1(), EVP_aria_192_cfb1(), EVP_aria_256_cfb1(), EVP_aria_128_cfb8(), EVP_aria_192_cfb8(), EVP_aria_256_cfb8(), EVP_aria_128_cfb128(), EVP_aria_192_cfb128(), EVP_aria_256_cfb128(), EVP_aria_128_ctr(), EVP_aria_192_ctr(), EVP_aria_256_ctr(), EVP_aria_128_ecb(), EVP_aria_192_ecb(), EVP_aria_256_ecb(), EVP_aria_128_ofb(), EVP_aria_192_ofb(), EVP_aria_256_ofb()" +ARIA for 128, 192 and 256 bit keys in the following modes: CBC, CFB with +128\-bit shift, CFB with 1\-bit shift, CFB with 8\-bit shift, CTR, ECB and OFB. +.IP "\fBEVP_aria_128_ccm()\fR, \fBEVP_aria_192_ccm()\fR, \fBEVP_aria_256_ccm()\fR, \fBEVP_aria_128_gcm()\fR, \fBEVP_aria_192_gcm()\fR, \fBEVP_aria_256_gcm()\fR," 4 +.IX Item "EVP_aria_128_ccm(), EVP_aria_192_ccm(), EVP_aria_256_ccm(), EVP_aria_128_gcm(), EVP_aria_192_gcm(), EVP_aria_256_gcm()," +ARIA for 128, 192 and 256 bit keys in CBC\-MAC Mode (CCM) and Galois Counter +Mode (GCM). These ciphers require additional control operations to function +correctly, see the "AEAD INTERFACE" in \fBEVP_EncryptInit\fR\|(3) section for details. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-ARIA\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_bf_cbc.3 b/static/netbsd/man3/EVP_bf_cbc.3 new file mode 100644 index 00000000..cc02dca6 --- /dev/null +++ b/static/netbsd/man3/EVP_bf_cbc.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: EVP_bf_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_bf_cbc 3" +.TH EVP_bf_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_bf_cbc, +EVP_bf_cfb, +EVP_bf_cfb64, +EVP_bf_ecb, +EVP_bf_ofb +\&\- EVP Blowfish cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_bf_cbc(void); +\& const EVP_CIPHER *EVP_bf_cfb(void); +\& const EVP_CIPHER *EVP_bf_cfb64(void); +\& const EVP_CIPHER *EVP_bf_ecb(void); +\& const EVP_CIPHER *EVP_bf_ofb(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Blowfish encryption algorithm for EVP. +.PP +This is a variable key length cipher. +.IP "\fBEVP_bf_cbc()\fR, \fBEVP_bf_cfb()\fR, \fBEVP_bf_cfb64()\fR, \fBEVP_bf_ecb()\fR, \fBEVP_bf_ofb()\fR" 4 +.IX Item "EVP_bf_cbc(), EVP_bf_cfb(), EVP_bf_cfb64(), EVP_bf_ecb(), EVP_bf_ofb()" +Blowfish encryption algorithm in CBC, CFB, ECB and OFB modes respectively. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-BLOWFISH\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_blake2b512.3 b/static/netbsd/man3/EVP_blake2b512.3 new file mode 100644 index 00000000..54d53bb4 --- /dev/null +++ b/static/netbsd/man3/EVP_blake2b512.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: EVP_blake2b512.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_blake2b512 3" +.TH EVP_blake2b512 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_blake2b512, +EVP_blake2s256 +\&\- BLAKE2 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_blake2b512(void); +\& const EVP_MD *EVP_blake2s256(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +BLAKE2 is an improved version of BLAKE, which was submitted to the NIST SHA\-3 +algorithm competition. The BLAKE2s and BLAKE2b algorithms are described in +RFC 7693. +.IP \fBEVP_blake2s256()\fR 4 +.IX Item "EVP_blake2s256()" +The BLAKE2s algorithm that produces a 256\-bit output from a given input. +.IP \fBEVP_blake2b512()\fR 4 +.IX Item "EVP_blake2b512()" +The BLAKE2b algorithm that produces a 512\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-BLAKE2\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.PP +Both algorithms support a variable\-length digest, +but this is only available through \fBEVP_MD\-BLAKE2\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 7693. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_camellia.3 b/static/netbsd/man3/EVP_camellia.3 new file mode 100644 index 00000000..4b791110 --- /dev/null +++ b/static/netbsd/man3/EVP_camellia.3 @@ -0,0 +1,205 @@ +.\" $NetBSD: EVP_camellia.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_camellia 3" +.TH EVP_camellia 3 "2018-12-08" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_camellia_128_cbc, +EVP_camellia_192_cbc, +EVP_camellia_256_cbc, +EVP_camellia_128_cfb, +EVP_camellia_192_cfb, +EVP_camellia_256_cfb, +EVP_camellia_128_cfb1, +EVP_camellia_192_cfb1, +EVP_camellia_256_cfb1, +EVP_camellia_128_cfb8, +EVP_camellia_192_cfb8, +EVP_camellia_256_cfb8, +EVP_camellia_128_cfb128, +EVP_camellia_192_cfb128, +EVP_camellia_256_cfb128, +EVP_camellia_128_ctr, +EVP_camellia_192_ctr, +EVP_camellia_256_ctr, +EVP_camellia_128_ecb, +EVP_camellia_192_ecb, +EVP_camellia_256_ecb, +EVP_camellia_128_ofb, +EVP_camellia_192_ofb, +EVP_camellia_256_ofb +\&\- EVP Camellia cipher +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_camellia_128_cbc\fR. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The Camellia encryption algorithm for \s-1EVP.\s0 +.IP "\fBEVP_camellia_128_cbc()\fR, \fBEVP_camellia_192_cbc()\fR, \fBEVP_camellia_256_cbc()\fR, \fBEVP_camellia_128_cfb()\fR, \fBEVP_camellia_192_cfb()\fR, \fBEVP_camellia_256_cfb()\fR, \fBEVP_camellia_128_cfb1()\fR, \fBEVP_camellia_192_cfb1()\fR, \fBEVP_camellia_256_cfb1()\fR, \fBEVP_camellia_128_cfb8()\fR, \fBEVP_camellia_192_cfb8()\fR, \fBEVP_camellia_256_cfb8()\fR, \fBEVP_camellia_128_cfb128()\fR, \fBEVP_camellia_192_cfb128()\fR, \fBEVP_camellia_256_cfb128()\fR, \fBEVP_camellia_128_ctr()\fR, \fBEVP_camellia_192_ctr()\fR, \fBEVP_camellia_256_ctr()\fR, \fBEVP_camellia_128_ecb()\fR, \fBEVP_camellia_192_ecb()\fR, \fBEVP_camellia_256_ecb()\fR, \fBEVP_camellia_128_ofb()\fR, \fBEVP_camellia_192_ofb()\fR, \fBEVP_camellia_256_ofb()\fR" 4 +.IX Item "EVP_camellia_128_cbc(), EVP_camellia_192_cbc(), EVP_camellia_256_cbc(), EVP_camellia_128_cfb(), EVP_camellia_192_cfb(), EVP_camellia_256_cfb(), EVP_camellia_128_cfb1(), EVP_camellia_192_cfb1(), EVP_camellia_256_cfb1(), EVP_camellia_128_cfb8(), EVP_camellia_192_cfb8(), EVP_camellia_256_cfb8(), EVP_camellia_128_cfb128(), EVP_camellia_192_cfb128(), EVP_camellia_256_cfb128(), EVP_camellia_128_ctr(), EVP_camellia_192_ctr(), EVP_camellia_256_ctr(), EVP_camellia_128_ecb(), EVP_camellia_192_ecb(), EVP_camellia_256_ecb(), EVP_camellia_128_ofb(), EVP_camellia_192_ofb(), EVP_camellia_256_ofb()" +Camellia for 128, 192 and 256 bit keys in the following modes: \s-1CBC, CFB\s0 with +128\-bit shift, \s-1CFB\s0 with 1\-bit shift, \s-1CFB\s0 with 8\-bit shift, \s-1CTR, ECB\s0 and \s-1OFB.\s0 +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fB\s-1EVP_CIPHER\s0\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fB\s-1EVP_CIPHER\s0\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_camellia_128_cbc.3 b/static/netbsd/man3/EVP_camellia_128_cbc.3 new file mode 100644 index 00000000..4e68e9d7 --- /dev/null +++ b/static/netbsd/man3/EVP_camellia_128_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_camellia_128_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_camellia_128_ecb.3 b/static/netbsd/man3/EVP_camellia_128_ecb.3 new file mode 100644 index 00000000..8a551823 --- /dev/null +++ b/static/netbsd/man3/EVP_camellia_128_ecb.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: EVP_camellia_128_ecb.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_camellia_128_ecb 3" +.TH EVP_camellia_128_ecb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_camellia_128_cbc, +EVP_camellia_192_cbc, +EVP_camellia_256_cbc, +EVP_camellia_128_cfb, +EVP_camellia_192_cfb, +EVP_camellia_256_cfb, +EVP_camellia_128_cfb1, +EVP_camellia_192_cfb1, +EVP_camellia_256_cfb1, +EVP_camellia_128_cfb8, +EVP_camellia_192_cfb8, +EVP_camellia_256_cfb8, +EVP_camellia_128_cfb128, +EVP_camellia_192_cfb128, +EVP_camellia_256_cfb128, +EVP_camellia_128_ctr, +EVP_camellia_192_ctr, +EVP_camellia_256_ctr, +EVP_camellia_128_ecb, +EVP_camellia_192_ecb, +EVP_camellia_256_ecb, +EVP_camellia_128_ofb, +EVP_camellia_192_ofb, +EVP_camellia_256_ofb +\&\- EVP Camellia cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_camellia_128_cbc\fR. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Camellia encryption algorithm for EVP. +.IP "\fBEVP_camellia_128_cbc()\fR, \fBEVP_camellia_192_cbc()\fR, \fBEVP_camellia_256_cbc()\fR, \fBEVP_camellia_128_cfb()\fR, \fBEVP_camellia_192_cfb()\fR, \fBEVP_camellia_256_cfb()\fR, \fBEVP_camellia_128_cfb1()\fR, \fBEVP_camellia_192_cfb1()\fR, \fBEVP_camellia_256_cfb1()\fR, \fBEVP_camellia_128_cfb8()\fR, \fBEVP_camellia_192_cfb8()\fR, \fBEVP_camellia_256_cfb8()\fR, \fBEVP_camellia_128_cfb128()\fR, \fBEVP_camellia_192_cfb128()\fR, \fBEVP_camellia_256_cfb128()\fR, \fBEVP_camellia_128_ctr()\fR, \fBEVP_camellia_192_ctr()\fR, \fBEVP_camellia_256_ctr()\fR, \fBEVP_camellia_128_ecb()\fR, \fBEVP_camellia_192_ecb()\fR, \fBEVP_camellia_256_ecb()\fR, \fBEVP_camellia_128_ofb()\fR, \fBEVP_camellia_192_ofb()\fR, \fBEVP_camellia_256_ofb()\fR" 4 +.IX Item "EVP_camellia_128_cbc(), EVP_camellia_192_cbc(), EVP_camellia_256_cbc(), EVP_camellia_128_cfb(), EVP_camellia_192_cfb(), EVP_camellia_256_cfb(), EVP_camellia_128_cfb1(), EVP_camellia_192_cfb1(), EVP_camellia_256_cfb1(), EVP_camellia_128_cfb8(), EVP_camellia_192_cfb8(), EVP_camellia_256_cfb8(), EVP_camellia_128_cfb128(), EVP_camellia_192_cfb128(), EVP_camellia_256_cfb128(), EVP_camellia_128_ctr(), EVP_camellia_192_ctr(), EVP_camellia_256_ctr(), EVP_camellia_128_ecb(), EVP_camellia_192_ecb(), EVP_camellia_256_ecb(), EVP_camellia_128_ofb(), EVP_camellia_192_ofb(), EVP_camellia_256_ofb()" +Camellia for 128, 192 and 256 bit keys in the following modes: CBC, CFB with +128\-bit shift, CFB with 1\-bit shift, CFB with 8\-bit shift, CTR, ECB and OFB. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-CAMELLIA\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_camellia_192_cbc.3 b/static/netbsd/man3/EVP_camellia_192_cbc.3 new file mode 100644 index 00000000..e0cdbd76 --- /dev/null +++ b/static/netbsd/man3/EVP_camellia_192_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_camellia_192_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_camellia_256_cbc.3 b/static/netbsd/man3/EVP_camellia_256_cbc.3 new file mode 100644 index 00000000..67e07624 --- /dev/null +++ b/static/netbsd/man3/EVP_camellia_256_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_camellia_256_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_cast5_cbc.3 b/static/netbsd/man3/EVP_cast5_cbc.3 new file mode 100644 index 00000000..7ceedcfb --- /dev/null +++ b/static/netbsd/man3/EVP_cast5_cbc.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: EVP_cast5_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_cast5_cbc 3" +.TH EVP_cast5_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_cast5_cbc, +EVP_cast5_cfb, +EVP_cast5_cfb64, +EVP_cast5_ecb, +EVP_cast5_ofb +\&\- EVP CAST cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_cast5_cbc(void); +\& const EVP_CIPHER *EVP_cast5_cfb(void); +\& const EVP_CIPHER *EVP_cast5_cfb64(void); +\& const EVP_CIPHER *EVP_cast5_ecb(void); +\& const EVP_CIPHER *EVP_cast5_ofb(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The CAST encryption algorithm for EVP. +.PP +This is a variable key length cipher. +.IP "\fBEVP_cast5_cbc()\fR, \fBEVP_cast5_ecb()\fR, \fBEVP_cast5_cfb()\fR, \fBEVP_cast5_cfb64()\fR, \fBEVP_cast5_ofb()\fR" 4 +.IX Item "EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_cfb64(), EVP_cast5_ofb()" +CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-CAST\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_chacha20.3 b/static/netbsd/man3/EVP_chacha20.3 new file mode 100644 index 00000000..67517f40 --- /dev/null +++ b/static/netbsd/man3/EVP_chacha20.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: EVP_chacha20.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_chacha20 3" +.TH EVP_chacha20 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_chacha20, +EVP_chacha20_poly1305 +\&\- EVP ChaCha20 stream cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_chacha20(void); +\& const EVP_CIPHER *EVP_chacha20_poly1305(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The ChaCha20 stream cipher for EVP. +.IP \fBEVP_chacha20()\fR 4 +.IX Item "EVP_chacha20()" +The ChaCha20 stream cipher. The key length is 256 bits, the IV is 128 bits long. +The first 64 bits consists of a counter in little\-endian order followed by a 64 +bit nonce. For example a nonce of: +.Sp +0000000000000002 +.Sp +With an initial counter of 42 (2a in hex) would be expressed as: +.Sp +2a000000000000000000000000000002 +.IP \fBEVP_chacha20_poly1305()\fR 4 +.IX Item "EVP_chacha20_poly1305()" +Authenticated encryption with ChaCha20\-Poly1305. Like \fBEVP_chacha20()\fR, the key +is 256 bits and the IV is 96 bits. This supports additional authenticated data +(AAD) and produces a 128\-bit authentication tag. See the +"AEAD INTERFACE" in \fBEVP_EncryptInit\fR\|(3) section for more information. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-CHACHA\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.PP +RFC 7539 +uses a 32 bit counter and a 96 bit nonce for the IV. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_des.3 b/static/netbsd/man3/EVP_des.3 new file mode 100644 index 00000000..215d1c39 --- /dev/null +++ b/static/netbsd/man3/EVP_des.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: EVP_des.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EVP_des 3" +.TH EVP_des 3 "2018-12-08" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +EVP_des_cbc, +EVP_des_cfb, +EVP_des_cfb1, +EVP_des_cfb8, +EVP_des_cfb64, +EVP_des_ecb, +EVP_des_ofb, +EVP_des_ede, +EVP_des_ede_cbc, +EVP_des_ede_cfb, +EVP_des_ede_cfb64, +EVP_des_ede_ecb, +EVP_des_ede_ofb, +EVP_des_ede3, +EVP_des_ede3_cbc, +EVP_des_ede3_cfb, +EVP_des_ede3_cfb1, +EVP_des_ede3_cfb8, +EVP_des_ede3_cfb64, +EVP_des_ede3_ecb, +EVP_des_ede3_ofb, +EVP_des_ede3_wrap +\&\- EVP DES cipher +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_des_cbc\fR. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1DES\s0 encryption algorithm for \s-1EVP.\s0 +.IP "\fBEVP_des_cbc()\fR, \fBEVP_des_ecb()\fR, \fBEVP_des_cfb()\fR, \fBEVP_des_cfb1()\fR, \fBEVP_des_cfb8()\fR, \fBEVP_des_cfb64()\fR, \fBEVP_des_ofb()\fR" 4 +.IX Item "EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_cfb1(), EVP_des_cfb8(), EVP_des_cfb64(), EVP_des_ofb()" +\&\s-1DES\s0 in \s-1CBC, ECB, CFB\s0 with 64\-bit shift, \s-1CFB\s0 with 1\-bit shift, \s-1CFB\s0 with 8\-bit +shift and \s-1OFB\s0 modes. +.IP "\fBEVP_des_ede()\fR, \fBEVP_des_ede_cbc()\fR, \fBEVP_des_ede_cfb()\fR, \fBEVP_des_ede_cfb64()\fR, \fBEVP_des_ede_ecb()\fR, \fBEVP_des_ede_ofb()\fR" 4 +.IX Item "EVP_des_ede(), EVP_des_ede_cbc(), EVP_des_ede_cfb(), EVP_des_ede_cfb64(), EVP_des_ede_ecb(), EVP_des_ede_ofb()" +Two key triple \s-1DES\s0 in \s-1ECB, CBC, CFB\s0 with 64\-bit shift and \s-1OFB\s0 modes. +.IP "\fBEVP_des_ede3()\fR, \fBEVP_des_ede3_cbc()\fR, \fBEVP_des_ede3_cfb()\fR, \fBEVP_des_ede3_cfb1()\fR, \fBEVP_des_ede3_cfb8()\fR, \fBEVP_des_ede3_cfb64()\fR, \fBEVP_des_ede3_ecb()\fR, \fBEVP_des_ede3_ofb()\fR" 4 +.IX Item "EVP_des_ede3(), EVP_des_ede3_cbc(), EVP_des_ede3_cfb(), EVP_des_ede3_cfb1(), EVP_des_ede3_cfb8(), EVP_des_ede3_cfb64(), EVP_des_ede3_ecb(), EVP_des_ede3_ofb()" +Three-key triple \s-1DES\s0 in \s-1ECB, CBC, CFB\s0 with 64\-bit shift, \s-1CFB\s0 with 1\-bit shift, +\&\s-1CFB\s0 with 8\-bit shift and \s-1OFB\s0 modes. +.IP "\fBEVP_des_ede3_wrap()\fR" 4 +.IX Item "EVP_des_ede3_wrap()" +Triple-DES key wrap according to \s-1RFC 3217\s0 Section 3. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fB\s-1EVP_CIPHER\s0\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fB\s-1EVP_CIPHER\s0\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_des_cbc.3 b/static/netbsd/man3/EVP_des_cbc.3 new file mode 100644 index 00000000..65618b9f --- /dev/null +++ b/static/netbsd/man3/EVP_des_cbc.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: EVP_des_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_des_cbc 3" +.TH EVP_des_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_des_cbc, +EVP_des_cfb, +EVP_des_cfb1, +EVP_des_cfb8, +EVP_des_cfb64, +EVP_des_ecb, +EVP_des_ofb, +EVP_des_ede, +EVP_des_ede_cbc, +EVP_des_ede_cfb, +EVP_des_ede_cfb64, +EVP_des_ede_ecb, +EVP_des_ede_ofb, +EVP_des_ede3, +EVP_des_ede3_cbc, +EVP_des_ede3_cfb, +EVP_des_ede3_cfb1, +EVP_des_ede3_cfb8, +EVP_des_ede3_cfb64, +EVP_des_ede3_ecb, +EVP_des_ede3_ofb, +EVP_des_ede3_wrap +\&\- EVP DES cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_ciphername(void) +.Ve +.PP +\&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher +functions, such as \fIEVP_des_cbc\fR. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The DES encryption algorithm for EVP. +.IP "\fBEVP_des_cbc()\fR, \fBEVP_des_ecb()\fR, \fBEVP_des_cfb()\fR, \fBEVP_des_cfb1()\fR, \fBEVP_des_cfb8()\fR, \fBEVP_des_cfb64()\fR, \fBEVP_des_ofb()\fR" 4 +.IX Item "EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_cfb1(), EVP_des_cfb8(), EVP_des_cfb64(), EVP_des_ofb()" +DES in CBC, ECB, CFB with 64\-bit shift, CFB with 1\-bit shift, CFB with 8\-bit +shift and OFB modes. +.Sp +None of these algorithms are provided by the OpenSSL default provider. +To use them it is necessary to load either the OpenSSL legacy provider or another +implementation. +.IP "\fBEVP_des_ede()\fR, \fBEVP_des_ede_cbc()\fR, \fBEVP_des_ede_cfb()\fR, \fBEVP_des_ede_cfb64()\fR, \fBEVP_des_ede_ecb()\fR, \fBEVP_des_ede_ofb()\fR" 4 +.IX Item "EVP_des_ede(), EVP_des_ede_cbc(), EVP_des_ede_cfb(), EVP_des_ede_cfb64(), EVP_des_ede_ecb(), EVP_des_ede_ofb()" +Two key triple DES in ECB, CBC, CFB with 64\-bit shift and OFB modes. +.IP "\fBEVP_des_ede3()\fR, \fBEVP_des_ede3_cbc()\fR, \fBEVP_des_ede3_cfb()\fR, \fBEVP_des_ede3_cfb1()\fR, \fBEVP_des_ede3_cfb8()\fR, \fBEVP_des_ede3_cfb64()\fR, \fBEVP_des_ede3_ecb()\fR, \fBEVP_des_ede3_ofb()\fR" 4 +.IX Item "EVP_des_ede3(), EVP_des_ede3_cbc(), EVP_des_ede3_cfb(), EVP_des_ede3_cfb1(), EVP_des_ede3_cfb8(), EVP_des_ede3_cfb64(), EVP_des_ede3_ecb(), EVP_des_ede3_ofb()" +Three\-key triple DES in ECB, CBC, CFB with 64\-bit shift, CFB with 1\-bit shift, +CFB with 8\-bit shift and OFB modes. +.IP \fBEVP_des_ede3_wrap()\fR 4 +.IX Item "EVP_des_ede3_wrap()" +Triple\-DES key wrap according to RFC 3217 Section 3. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-DES\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_des_ede3_cbc.3 b/static/netbsd/man3/EVP_des_ede3_cbc.3 new file mode 100644 index 00000000..88b68618 --- /dev/null +++ b/static/netbsd/man3/EVP_des_ede3_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_des_ede3_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_desx_cbc.3 b/static/netbsd/man3/EVP_desx_cbc.3 new file mode 100644 index 00000000..77638d00 --- /dev/null +++ b/static/netbsd/man3/EVP_desx_cbc.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_desx_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_desx_cbc 3" +.TH EVP_desx_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_desx_cbc +\&\- EVP DES\-X cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_desx_cbc(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The DES\-X encryption algorithm for EVP. +.PP +All modes below use a key length of 128 bits and acts on blocks of 128\-bits. +.IP \fBEVP_desx_cbc()\fR 4 +.IX Item "EVP_desx_cbc()" +The DES\-X algorithm in CBC mode. +.Sp +This algorithm is not provided by the OpenSSL default provider. +To use it is necessary to load either the OpenSSL legacy provider or another +implementation. +.PP +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-DES\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_enc_null.3 b/static/netbsd/man3/EVP_enc_null.3 new file mode 100644 index 00000000..9cc26196 --- /dev/null +++ b/static/netbsd/man3/EVP_enc_null.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_enc_null.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_get_cipherbyname.3 b/static/netbsd/man3/EVP_get_cipherbyname.3 new file mode 100644 index 00000000..ef88e2f7 --- /dev/null +++ b/static/netbsd/man3/EVP_get_cipherbyname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_get_cipherbyname.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_128_cbc.3 b/static/netbsd/man3/EVP_hcrypto_aes_128_cbc.3 new file mode 100644 index 00000000..e0a6f4b5 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_128_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_128_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_128_cfb8.3 b/static/netbsd/man3/EVP_hcrypto_aes_128_cfb8.3 new file mode 100644 index 00000000..62a084e3 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_128_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_128_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_192_cbc.3 b/static/netbsd/man3/EVP_hcrypto_aes_192_cbc.3 new file mode 100644 index 00000000..98eaf146 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_192_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_192_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_192_cfb8.3 b/static/netbsd/man3/EVP_hcrypto_aes_192_cfb8.3 new file mode 100644 index 00000000..0f81bd27 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_192_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_192_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_256_cbc.3 b/static/netbsd/man3/EVP_hcrypto_aes_256_cbc.3 new file mode 100644 index 00000000..14e7e325 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_256_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_256_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_aes_256_cfb8.3 b/static/netbsd/man3/EVP_hcrypto_aes_256_cfb8.3 new file mode 100644 index 00000000..81d6e0ba --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_aes_256_cfb8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_aes_256_cfb8.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_camellia_128_cbc.3 b/static/netbsd/man3/EVP_hcrypto_camellia_128_cbc.3 new file mode 100644 index 00000000..318d8831 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_camellia_128_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_camellia_128_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_camellia_192_cbc.3 b/static/netbsd/man3/EVP_hcrypto_camellia_192_cbc.3 new file mode 100644 index 00000000..72bdc698 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_camellia_192_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_camellia_192_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_camellia_256_cbc.3 b/static/netbsd/man3/EVP_hcrypto_camellia_256_cbc.3 new file mode 100644 index 00000000..5b0eb163 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_camellia_256_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_camellia_256_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_des_cbc.3 b/static/netbsd/man3/EVP_hcrypto_des_cbc.3 new file mode 100644 index 00000000..58cdff7f --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_des_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_des_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_des_ede3_cbc.3 b/static/netbsd/man3/EVP_hcrypto_des_ede3_cbc.3 new file mode 100644 index 00000000..171a54f4 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_des_ede3_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_des_ede3_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_md4.3 b/static/netbsd/man3/EVP_hcrypto_md4.3 new file mode 100644 index 00000000..014fbdd5 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_md4.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_md4.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_md5.3 b/static/netbsd/man3/EVP_hcrypto_md5.3 new file mode 100644 index 00000000..8a46ea1d --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_md5.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_md5.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_rc2_40_cbc.3 b/static/netbsd/man3/EVP_hcrypto_rc2_40_cbc.3 new file mode 100644 index 00000000..1aad0e8d --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_rc2_40_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_rc2_40_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_rc2_64_cbc.3 b/static/netbsd/man3/EVP_hcrypto_rc2_64_cbc.3 new file mode 100644 index 00000000..458b1d1a --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_rc2_64_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_rc2_64_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_rc2_cbc.3 b/static/netbsd/man3/EVP_hcrypto_rc2_cbc.3 new file mode 100644 index 00000000..593e79ca --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_rc2_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_rc2_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_sha1.3 b/static/netbsd/man3/EVP_hcrypto_sha1.3 new file mode 100644 index 00000000..fea11e73 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_sha1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_sha1.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_sha256.3 b/static/netbsd/man3/EVP_hcrypto_sha256.3 new file mode 100644 index 00000000..781ba01f --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_sha256.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_sha256.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_sha384.3 b/static/netbsd/man3/EVP_hcrypto_sha384.3 new file mode 100644 index 00000000..ebac7a70 --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_sha384.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_sha384.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_hcrypto_sha512.3 b/static/netbsd/man3/EVP_hcrypto_sha512.3 new file mode 100644 index 00000000..6a674ddf --- /dev/null +++ b/static/netbsd/man3/EVP_hcrypto_sha512.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_hcrypto_sha512.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_idea_cbc.3 b/static/netbsd/man3/EVP_idea_cbc.3 new file mode 100644 index 00000000..12dab7cc --- /dev/null +++ b/static/netbsd/man3/EVP_idea_cbc.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: EVP_idea_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_idea_cbc 3" +.TH EVP_idea_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_idea_cbc, +EVP_idea_cfb, +EVP_idea_cfb64, +EVP_idea_ecb, +EVP_idea_ofb +\&\- EVP IDEA cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_idea_cbc(void); +\& const EVP_CIPHER *EVP_idea_cfb(void); +\& const EVP_CIPHER *EVP_idea_cfb64(void); +\& const EVP_CIPHER *EVP_idea_ecb(void); +\& const EVP_CIPHER *EVP_idea_ofb(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The IDEA encryption algorithm for EVP. +.IP "\fBEVP_idea_cbc()\fR, \fBEVP_idea_cfb()\fR, \fBEVP_idea_cfb64()\fR, \fBEVP_idea_ecb()\fR, \fBEVP_idea_ofb()\fR" 4 +.IX Item "EVP_idea_cbc(), EVP_idea_cfb(), EVP_idea_cfb64(), EVP_idea_ecb(), EVP_idea_ofb()" +The IDEA encryption algorithm in CBC, CFB, ECB and OFB modes respectively. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-IDEA\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_md2.3 b/static/netbsd/man3/EVP_md2.3 new file mode 100644 index 00000000..1f09f06e --- /dev/null +++ b/static/netbsd/man3/EVP_md2.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: EVP_md2.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_md2 3" +.TH EVP_md2 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_md2 +\&\- MD2 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_md2(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +MD2 is a cryptographic hash function standardized in RFC 1319 and designed by +Ronald Rivest. This implementation is only available with the legacy provider. +.IP \fBEVP_md2()\fR 4 +.IX Item "EVP_md2()" +The MD2 algorithm which produces a 128\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-MD2\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 1319. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBprovider\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_md4.3 b/static/netbsd/man3/EVP_md4.3 new file mode 100644 index 00000000..e79ad48c --- /dev/null +++ b/static/netbsd/man3/EVP_md4.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_md4.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_md4 3" +.TH EVP_md4 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_md4 +\&\- MD4 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_md4(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +MD4 is a cryptographic hash function standardized in RFC 1320 and designed by +Ronald Rivest, first published in 1990. This implementation is only available +with the legacy provider. +.IP \fBEVP_md4()\fR 4 +.IX Item "EVP_md4()" +The MD4 algorithm which produces a 128\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-MD4\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 1320. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBprovider\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_md5.3 b/static/netbsd/man3/EVP_md5.3 new file mode 100644 index 00000000..b79e2702 --- /dev/null +++ b/static/netbsd/man3/EVP_md5.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: EVP_md5.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_md5 3" +.TH EVP_md5 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_md5, +EVP_md5_sha1 +\&\- MD5 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_md5(void); +\& const EVP_MD *EVP_md5_sha1(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +MD5 is a cryptographic hash function standardized in RFC 1321 and designed by +Ronald Rivest. +.PP +The CMU Software Engineering Institute considers MD5 unsuitable for further +use since its security has been severely compromised. +.IP \fBEVP_md5()\fR 4 +.IX Item "EVP_md5()" +The MD5 algorithm which produces a 128\-bit output from a given input. +.IP \fBEVP_md5_sha1()\fR 4 +.IX Item "EVP_md5_sha1()" +A hash algorithm of SSL v3 that combines MD5 with SHA\-1 as described in RFC +6101. +.Sp +WARNING: this algorithm is not intended for non\-SSL usage. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-MD5\fR\|(7) or \fBEVP_MD\-MD5\-SHA1\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 1321. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_md_null.3 b/static/netbsd/man3/EVP_md_null.3 new file mode 100644 index 00000000..a2a3e4df --- /dev/null +++ b/static/netbsd/man3/EVP_md_null.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_md_null.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_mdc2.3 b/static/netbsd/man3/EVP_mdc2.3 new file mode 100644 index 00000000..06f03a71 --- /dev/null +++ b/static/netbsd/man3/EVP_mdc2.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: EVP_mdc2.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_mdc2 3" +.TH EVP_mdc2 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_mdc2 +\&\- MDC\-2 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_mdc2(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +MDC\-2 (Modification Detection Code 2 or Meyer\-Schilling) is a cryptographic +hash function based on a block cipher. This implementation is only available +with the legacy provider. +.IP \fBEVP_mdc2()\fR 4 +.IX Item "EVP_mdc2()" +The MDC\-2DES algorithm of using MDC\-2 with the DES block cipher. It produces a +128\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-MDC2\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ISO/IEC 10118\-2:2000 Hash\-Function 2, with DES as the underlying block cipher. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBprovider\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_rc2_40_cbc.3 b/static/netbsd/man3/EVP_rc2_40_cbc.3 new file mode 100644 index 00000000..3680be2d --- /dev/null +++ b/static/netbsd/man3/EVP_rc2_40_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_rc2_40_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_rc2_64_cbc.3 b/static/netbsd/man3/EVP_rc2_64_cbc.3 new file mode 100644 index 00000000..231e0a01 --- /dev/null +++ b/static/netbsd/man3/EVP_rc2_64_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_rc2_64_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_rc2_cbc.3 b/static/netbsd/man3/EVP_rc2_cbc.3 new file mode 100644 index 00000000..04faa1c3 --- /dev/null +++ b/static/netbsd/man3/EVP_rc2_cbc.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: EVP_rc2_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_rc2_cbc 3" +.TH EVP_rc2_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_rc2_cbc, +EVP_rc2_cfb, +EVP_rc2_cfb64, +EVP_rc2_ecb, +EVP_rc2_ofb, +EVP_rc2_40_cbc, +EVP_rc2_64_cbc +\&\- EVP RC2 cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_rc2_cbc(void); +\& const EVP_CIPHER *EVP_rc2_cfb(void); +\& const EVP_CIPHER *EVP_rc2_cfb64(void); +\& const EVP_CIPHER *EVP_rc2_ecb(void); +\& const EVP_CIPHER *EVP_rc2_ofb(void); +\& const EVP_CIPHER *EVP_rc2_40_cbc(void); +\& const EVP_CIPHER *EVP_rc2_64_cbc(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The RC2 encryption algorithm for EVP. +.IP "\fBEVP_rc2_cbc()\fR, \fBEVP_rc2_cfb()\fR, \fBEVP_rc2_cfb64()\fR, \fBEVP_rc2_ecb()\fR, \fBEVP_rc2_ofb()\fR" 4 +.IX Item "EVP_rc2_cbc(), EVP_rc2_cfb(), EVP_rc2_cfb64(), EVP_rc2_ecb(), EVP_rc2_ofb()" +RC2 encryption algorithm in CBC, CFB, ECB and OFB modes respectively. This is a +variable key length cipher with an additional parameter called "effective key +bits" or "effective key length". By default both are set to 128 bits. +.IP "\fBEVP_rc2_40_cbc()\fR, \fBEVP_rc2_64_cbc()\fR" 4 +.IX Item "EVP_rc2_40_cbc(), EVP_rc2_64_cbc()" +RC2 algorithm in CBC mode with a default key length and effective key length of +40 and 64 bits. +.Sp +WARNING: these functions are obsolete. Their usage should be replaced with the +\&\fBEVP_rc2_cbc()\fR, \fBEVP_CIPHER_CTX_set_key_length()\fR and \fBEVP_CIPHER_CTX_ctrl()\fR +functions to set the key length and effective key length. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-RC2\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_rc4.3 b/static/netbsd/man3/EVP_rc4.3 new file mode 100644 index 00000000..27b8d461 --- /dev/null +++ b/static/netbsd/man3/EVP_rc4.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: EVP_rc4.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_rc4 3" +.TH EVP_rc4 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_rc4, +EVP_rc4_40, +EVP_rc4_hmac_md5 +\&\- EVP RC4 stream cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_rc4(void); +\& const EVP_CIPHER *EVP_rc4_40(void); +\& const EVP_CIPHER *EVP_rc4_hmac_md5(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The RC4 stream cipher for EVP. +.IP \fBEVP_rc4()\fR 4 +.IX Item "EVP_rc4()" +RC4 stream cipher. This is a variable key length cipher with a default key +length of 128 bits. +.IP \fBEVP_rc4_40()\fR 4 +.IX Item "EVP_rc4_40()" +RC4 stream cipher with 40 bit key length. +.Sp +WARNING: this function is obsolete. Its usage should be replaced with the +\&\fBEVP_rc4()\fR and the \fBEVP_CIPHER_CTX_set_key_length()\fR functions. +.IP \fBEVP_rc4_hmac_md5()\fR 4 +.IX Item "EVP_rc4_hmac_md5()" +Authenticated encryption with the RC4 stream cipher with MD5 as HMAC. +.Sp +WARNING: this is not intended for usage outside of TLS and requires calling of +some undocumented ctrl functions. These ciphers do not conform to the EVP AEAD +interface. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-RC4\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_rc4_40.3 b/static/netbsd/man3/EVP_rc4_40.3 new file mode 100644 index 00000000..3ab09f2f --- /dev/null +++ b/static/netbsd/man3/EVP_rc4_40.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_rc4_40.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_rc5_32_12_16_cbc.3 b/static/netbsd/man3/EVP_rc5_32_12_16_cbc.3 new file mode 100644 index 00000000..a4888b58 --- /dev/null +++ b/static/netbsd/man3/EVP_rc5_32_12_16_cbc.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: EVP_rc5_32_12_16_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_rc5_32_12_16_cbc 3" +.TH EVP_rc5_32_12_16_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_rc5_32_12_16_cbc, +EVP_rc5_32_12_16_cfb, +EVP_rc5_32_12_16_cfb64, +EVP_rc5_32_12_16_ecb, +EVP_rc5_32_12_16_ofb +\&\- EVP RC5 cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_rc5_32_12_16_cbc(void); +\& const EVP_CIPHER *EVP_rc5_32_12_16_cfb(void); +\& const EVP_CIPHER *EVP_rc5_32_12_16_cfb64(void); +\& const EVP_CIPHER *EVP_rc5_32_12_16_ecb(void); +\& const EVP_CIPHER *EVP_rc5_32_12_16_ofb(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The RC5 encryption algorithm for EVP. +.IP "\fBEVP_rc5_32_12_16_cbc()\fR, \fBEVP_rc5_32_12_16_cfb()\fR, \fBEVP_rc5_32_12_16_cfb64()\fR, \fBEVP_rc5_32_12_16_ecb()\fR, \fBEVP_rc5_32_12_16_ofb()\fR" 4 +.IX Item "EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_cfb64(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_ofb()" +RC5 encryption algorithm in CBC, CFB, ECB and OFB modes respectively. This is a +variable key length cipher with an additional "number of rounds" parameter. By +default the key length is set to 128 bits and 12 rounds. Alternative key lengths +can be set using \fBEVP_CIPHER_CTX_set_key_length\fR\|(3). The maximum key length is +2040 bits. +.Sp +The following rc5 specific \fIctrl\fRs are supported (see +\&\fBEVP_CIPHER_CTX_ctrl\fR\|(3)). +.RS 4 +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, rounds, NULL)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, rounds, NULL)" +Sets the number of rounds to \fBrounds\fR. This must be one of RC5_8_ROUNDS, +RC5_12_ROUNDS or RC5_16_ROUNDS. +.IP "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &rounds)" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &rounds)" +Stores the number of rounds currently configured in \fB*rounds\fR where \fB*rounds\fR +is an int. +.RE +.RS 4 +.RE +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-RC5\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_ripemd160.3 b/static/netbsd/man3/EVP_ripemd160.3 new file mode 100644 index 00000000..4b6a313a --- /dev/null +++ b/static/netbsd/man3/EVP_ripemd160.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: EVP_ripemd160.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_ripemd160 3" +.TH EVP_ripemd160 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_ripemd160 +\&\- RIPEMD160 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_ripemd160(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +RIPEMD\-160 is a cryptographic hash function first published in 1996 belonging +to the RIPEMD family (RACE Integrity Primitives Evaluation Message Digest). +This implementation is only available with the legacy provider. +.IP \fBEVP_ripemd160()\fR 4 +.IX Item "EVP_ripemd160()" +The RIPEMD\-160 algorithm which produces a 160\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-RIPEMD160\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ISO/IEC 10118\-3:2016 Dedicated Hash\-Function 1 (RIPEMD\-160). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBprovider\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_seed_cbc.3 b/static/netbsd/man3/EVP_seed_cbc.3 new file mode 100644 index 00000000..5ffce68a --- /dev/null +++ b/static/netbsd/man3/EVP_seed_cbc.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: EVP_seed_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_seed_cbc 3" +.TH EVP_seed_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_seed_cbc, +EVP_seed_cfb, +EVP_seed_cfb128, +EVP_seed_ecb, +EVP_seed_ofb +\&\- EVP SEED cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_seed_cbc(void); +\& const EVP_CIPHER *EVP_seed_cfb(void); +\& const EVP_CIPHER *EVP_seed_cfb128(void); +\& const EVP_CIPHER *EVP_seed_ecb(void); +\& const EVP_CIPHER *EVP_seed_ofb(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The SEED encryption algorithm for EVP. +.PP +All modes below use a key length of 128 bits and acts on blocks of 128\-bits. +.IP "\fBEVP_seed_cbc()\fR, \fBEVP_seed_cfb()\fR, \fBEVP_seed_cfb128()\fR, \fBEVP_seed_ecb()\fR, \fBEVP_seed_ofb()\fR" 4 +.IX Item "EVP_seed_cbc(), EVP_seed_cfb(), EVP_seed_cfb128(), EVP_seed_ecb(), EVP_seed_ofb()" +The SEED encryption algorithm in CBC, CFB, ECB and OFB modes respectively. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-SEED\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return an \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_set_default_properties.3 b/static/netbsd/man3/EVP_set_default_properties.3 new file mode 100644 index 00000000..434e7473 --- /dev/null +++ b/static/netbsd/man3/EVP_set_default_properties.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: EVP_set_default_properties.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_set_default_properties 3" +.TH EVP_set_default_properties 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_set_default_properties, EVP_default_properties_enable_fips, +EVP_default_properties_is_fips_enabled, EVP_get1_default_properties +\&\- manage default properties for future algorithm fetches +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int EVP_set_default_properties(OSSL_LIB_CTX *libctx, const char *propq); +\& char *EVP_get1_default_properties(OSSL_LIB_CTX *libctx); +\& int EVP_default_properties_enable_fips(OSSL_LIB_CTX *libctx, int enable); +\& int EVP_default_properties_is_fips_enabled(OSSL_LIB_CTX *libctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_set_default_properties()\fR sets the default properties for all +future EVP algorithm fetches, implicit as well as explicit. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for information about implicit and explicit +fetching. +.PP +EVP_set_default_properties stores the properties given with the string +\&\fIpropq\fR among the EVP data that\*(Aqs been stored in the library context +given with \fIlibctx\fR (NULL signifies the default library context). +.PP +Any previous default property for the specified library context will +be dropped. +.PP +\&\fBEVP_get1_default_properties()\fR gets the default properties set for all future EVP +algorithm fetches, implicit as well as explicit, for the specific library +context. +.PP +\&\fBEVP_default_properties_enable_fips()\fR sets the \*(Aqfips=yes\*(Aq to be a default property +if \fIenable\fR is non zero, otherwise it clears \*(Aqfips\*(Aq from the default property +query for the given \fIlibctx\fR. It merges the fips default property query with any +existing query strings that have been set via \fBEVP_set_default_properties()\fR. +.PP +\&\fBEVP_default_properties_is_fips_enabled()\fR indicates if \*(Aqfips=yes\*(Aq is a default +property for the given \fIlibctx\fR. +.SH NOTES +.IX Header "NOTES" +\&\fBEVP_set_default_properties()\fR and \fBEVP_default_properties_enable_fips()\fR are not +thread safe. They are intended to be called only during the initialisation +phase of a \fIlibctx\fR. +.PP +\&\fBEVP_get1_default_properties()\fR is not thread safe. The application must ensure +that the context reference is valid and default fetching properties are not +being modified by a different thread. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_set_default_properties()\fR and \fBEVP_default_properties_enable_fips()\fR return 1 +on success, or 0 on failure. An error is placed on the error stack if a +failure occurs. +.PP +\&\fBEVP_default_properties_is_fips_enabled()\fR returns 1 if the \*(Aqfips=yes\*(Aq default +property is set for the given \fIlibctx\fR, otherwise it returns 0. +.PP +\&\fBEVP_get1_default_properties()\fR returns allocated memory that must be freed by +\&\fBOPENSSL_free\fR\|(3) on success and NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_MD_fetch\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBEVP_set_default_properties()\fR, \fBEVP_default_properties_enable_fips()\fR, +\&\fBEVP_default_properties_is_fips_enabled()\fR were added in OpenSSL 3.0. +.PP +The function \fBEVP_get1_default_properties()\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_sha.3 b/static/netbsd/man3/EVP_sha.3 new file mode 100644 index 00000000..4ed6808f --- /dev/null +++ b/static/netbsd/man3/EVP_sha.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_sha.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_sha1.3 b/static/netbsd/man3/EVP_sha1.3 new file mode 100644 index 00000000..d72f624b --- /dev/null +++ b/static/netbsd/man3/EVP_sha1.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: EVP_sha1.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_sha1 3" +.TH EVP_sha1 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_sha1 +\&\- SHA\-1 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_sha1(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +SHA\-1 (Secure Hash Algorithm 1) is a cryptographic hash function standardized +in NIST FIPS 180\-4. The algorithm was designed by the United States National +Security Agency and initially published in 1995. +.IP \fBEVP_sha1()\fR 4 +.IX Item "EVP_sha1()" +The SHA\-1 algorithm which produces a 160\-bit output from a given input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-SHA1\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST FIPS 180\-4. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_sha224.3 b/static/netbsd/man3/EVP_sha224.3 new file mode 100644 index 00000000..21701de0 --- /dev/null +++ b/static/netbsd/man3/EVP_sha224.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: EVP_sha224.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_sha224 3" +.TH EVP_sha224 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_sha224, +EVP_sha256, +EVP_sha512_224, +EVP_sha512_256, +EVP_sha384, +EVP_sha512 +\&\- SHA\-2 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_sha224(void); +\& const EVP_MD *EVP_sha256(void); +\& const EVP_MD *EVP_sha512_224(void); +\& const EVP_MD *EVP_sha512_256(void); +\& const EVP_MD *EVP_sha384(void); +\& const EVP_MD *EVP_sha512(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +SHA\-2 (Secure Hash Algorithm 2) is a family of cryptographic hash functions +standardized in NIST FIPS 180\-4, first published in 2001. +.IP "\fBEVP_sha224()\fR, \fBEVP_sha256()\fR, EVP_sha512_224, EVP_sha512_256, \fBEVP_sha384()\fR, \fBEVP_sha512()\fR" 4 +.IX Item "EVP_sha224(), EVP_sha256(), EVP_sha512_224, EVP_sha512_256, EVP_sha384(), EVP_sha512()" +The SHA\-2 SHA\-224, SHA\-256, SHA\-512/224, SHA512/256, SHA\-384 and SHA\-512 +algorithms, which generate 224, 256, 224, 256, 384 and 512 bits +respectively of output from a given input. +.Sp +The two algorithms: SHA\-512/224 and SHA512/256 are truncated forms of the +SHA\-512 algorithm. They are distinct from SHA\-224 and SHA\-256 even though +their outputs are of the same size. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-SHA2\fR\|(7)instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST FIPS 180\-4. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_sha256.3 b/static/netbsd/man3/EVP_sha256.3 new file mode 100644 index 00000000..ceb181af --- /dev/null +++ b/static/netbsd/man3/EVP_sha256.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_sha256.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_sha384.3 b/static/netbsd/man3/EVP_sha384.3 new file mode 100644 index 00000000..c61251ba --- /dev/null +++ b/static/netbsd/man3/EVP_sha384.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_sha384.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_sha3_224.3 b/static/netbsd/man3/EVP_sha3_224.3 new file mode 100644 index 00000000..6ad446c3 --- /dev/null +++ b/static/netbsd/man3/EVP_sha3_224.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: EVP_sha3_224.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_sha3_224 3" +.TH EVP_sha3_224 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_sha3_224, +EVP_sha3_256, +EVP_sha3_384, +EVP_sha3_512, +EVP_shake128, +EVP_shake256 +\&\- SHA\-3 For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_sha3_224(void); +\& const EVP_MD *EVP_sha3_256(void); +\& const EVP_MD *EVP_sha3_384(void); +\& const EVP_MD *EVP_sha3_512(void); +\& +\& const EVP_MD *EVP_shake128(void); +\& const EVP_MD *EVP_shake256(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +SHA\-3 (Secure Hash Algorithm 3) is a family of cryptographic hash functions +standardized in NIST FIPS 202, first published in 2015. It is based on the +Keccak algorithm. +.IP "\fBEVP_sha3_224()\fR, \fBEVP_sha3_256()\fR, \fBEVP_sha3_384()\fR, \fBEVP_sha3_512()\fR" 4 +.IX Item "EVP_sha3_224(), EVP_sha3_256(), EVP_sha3_384(), EVP_sha3_512()" +The SHA\-3 SHA\-3\-224, SHA\-3\-256, SHA\-3\-384, and SHA\-3\-512 algorithms +respectively. They produce 224, 256, 384 and 512 bits of output from a given +input. +.IP "\fBEVP_shake128()\fR, \fBEVP_shake256()\fR" 4 +.IX Item "EVP_shake128(), EVP_shake256()" +The SHAKE\-128 and SHAKE\-256 Extendable Output Functions (XOF) that can generate +a variable hash length. +.Sp +Specifically, \fBEVP_shake128\fR provides an overall security of 128 bits, while +\&\fBEVP_shake256\fR provides that of 256 bits. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-SHA3\fR\|(7) or \fBEVP_MD\-SHAKE\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +NIST FIPS 202. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_sha512.3 b/static/netbsd/man3/EVP_sha512.3 new file mode 100644 index 00000000..f9a6451d --- /dev/null +++ b/static/netbsd/man3/EVP_sha512.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_sha512.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/EVP_sm3.3 b/static/netbsd/man3/EVP_sm3.3 new file mode 100644 index 00000000..a92825b2 --- /dev/null +++ b/static/netbsd/man3/EVP_sm3.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: EVP_sm3.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_sm3 3" +.TH EVP_sm3 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_sm3 +\&\- SM3 for EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_sm3(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +SM3 is a cryptographic hash function with a 256\-bit output, defined in GB/T +32905\-2016. +.IP \fBEVP_sm3()\fR 4 +.IX Item "EVP_sm3()" +The SM3 hash function. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-SM3\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +GB/T 32905\-2016 and GM/T 0004\-2012. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017 Ribose Inc. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_sm4_cbc.3 b/static/netbsd/man3/EVP_sm4_cbc.3 new file mode 100644 index 00000000..2f7ff4f1 --- /dev/null +++ b/static/netbsd/man3/EVP_sm4_cbc.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: EVP_sm4_cbc.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_sm4_cbc 3" +.TH EVP_sm4_cbc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_sm4_cbc, +EVP_sm4_ecb, +EVP_sm4_cfb, +EVP_sm4_cfb128, +EVP_sm4_ofb, +EVP_sm4_ctr +\&\- EVP SM4 cipher +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_CIPHER *EVP_sm4_cbc(void); +\& const EVP_CIPHER *EVP_sm4_ecb(void); +\& const EVP_CIPHER *EVP_sm4_cfb(void); +\& const EVP_CIPHER *EVP_sm4_cfb128(void); +\& const EVP_CIPHER *EVP_sm4_ofb(void); +\& const EVP_CIPHER *EVP_sm4_ctr(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The SM4 blockcipher (GB/T 32907\-2016) for EVP. +.PP +All modes below use a key length of 128 bits and acts on blocks of 128 bits. +.IP "\fBEVP_sm4_cbc()\fR, \fBEVP_sm4_ecb()\fR, \fBEVP_sm4_cfb()\fR, \fBEVP_sm4_cfb128()\fR, \fBEVP_sm4_ofb()\fR, \fBEVP_sm4_ctr()\fR" 4 +.IX Item "EVP_sm4_cbc(), EVP_sm4_ecb(), EVP_sm4_cfb(), EVP_sm4_cfb128(), EVP_sm4_ofb(), EVP_sm4_ctr()" +The SM4 blockcipher with a 128\-bit key in CBC, ECB, CFB, OFB and CTR modes +respectively. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling these functions multiple times and should consider using +\&\fBEVP_CIPHER_fetch\fR\|(3) with \fBEVP_CIPHER\-SM4\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_CIPHER\fR structure that contains the +implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for +details of the \fBEVP_CIPHER\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3), +\&\fBEVP_CIPHER_meth_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017 Ribose Inc. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_whirlpool.3 b/static/netbsd/man3/EVP_whirlpool.3 new file mode 100644 index 00000000..95db3977 --- /dev/null +++ b/static/netbsd/man3/EVP_whirlpool.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: EVP_whirlpool.3,v 1.5 2026/04/08 17:06:44 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "EVP_whirlpool 3" +.TH EVP_whirlpool 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_whirlpool +\&\- WHIRLPOOL For EVP +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const EVP_MD *EVP_whirlpool(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +WHIRLPOOL is a cryptographic hash function standardized in ISO/IEC 10118\-3:2004 +designed by Vincent Rijmen and Paulo S. L. M. Barreto. This implementation is +only available with the legacy provider. +.IP \fBEVP_whirlpool()\fR 4 +.IX Item "EVP_whirlpool()" +The WHIRLPOOL algorithm that produces a message digest of 512\-bits from a given +input. +.SH NOTES +.IX Header "NOTES" +Developers should be aware of the negative performance implications of +calling this function multiple times and should consider using +\&\fBEVP_MD_fetch\fR\|(3) with \fBEVP_MD\-WHIRLPOOL\fR\|(7) instead. +See "Performance" in \fBcrypto\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return a \fBEVP_MD\fR structure that contains the +implementation of the message digest. See \fBEVP_MD_meth_new\fR\|(3) for +details of the \fBEVP_MD\fR structure. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ISO/IEC 10118\-3:2004. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), +\&\fBprovider\fR\|(7), +\&\fBEVP_DigestInit\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/EVP_wincrypt_des_ede3_cbc.3 b/static/netbsd/man3/EVP_wincrypt_des_ede3_cbc.3 new file mode 100644 index 00000000..58f2a8e3 --- /dev/null +++ b/static/netbsd/man3/EVP_wincrypt_des_ede3_cbc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: EVP_wincrypt_des_ede3_cbc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/GENERAL_NAME.3 b/static/netbsd/man3/GENERAL_NAME.3 new file mode 100644 index 00000000..eea694f7 --- /dev/null +++ b/static/netbsd/man3/GENERAL_NAME.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: GENERAL_NAME.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "GENERAL_NAME 3" +.TH GENERAL_NAME 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +GENERAL_NAME, +GENERAL_NAME_set1_X509_NAME +\&\- GENERAL_NAME method routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct GENERAL_NAME_st GENERAL_NAME; +\& +\& int GENERAL_NAME_set1_X509_NAME(GENERAL_NAME **tgt, const X509_NAME *src); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBGENERAL_NAME_set1_X509_NAME()\fR creates a new GENERAL_NAME of type GEN_DIRNAME +and populates it based on provided X509_NAME \fIsrc\fR which can be NULL. +\&\fItgt\fR must not be NULL. If successful, \fI*tgt\fR will be set to point +to the newly created GENERAL_NAME. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBGENERAL_NAME_set1_X509_NAME()\fR return 1 on success, 0 on error. +.SH HISTORY +.IX Header "HISTORY" +\&\fBGENERAL_NAME_set1_X509_NAME()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/HDB.3 b/static/netbsd/man3/HDB.3 new file mode 100644 index 00000000..0ce3de1b --- /dev/null +++ b/static/netbsd/man3/HDB.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: HDB.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "HDB" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal hdb library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +HDB +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "char * \fBhdb_name\fP" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_open\fP )(krb5_context, struct \fBHDB\fP *, int, mode_t)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_close\fP )(krb5_context, struct \fBHDB\fP *)" +.br +.ti -1c +.RI "void(* \fBhdb_free\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_fetch_kvno\fP )(krb5_context, struct \fBHDB\fP *, krb5_const_principal, unsigned, krb5_kvno, \fBhdb_entry_ex\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_store\fP )(krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_remove\fP )(krb5_context, struct \fBHDB\fP *, unsigned, krb5_const_principal)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_firstkey\fP )(krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_nextkey\fP )(krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_lock\fP )(krb5_context, struct \fBHDB\fP *, int)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_unlock\fP )(krb5_context, struct \fBHDB\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_rename\fP )(krb5_context, struct \fBHDB\fP *, const char *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb__get\fP )(krb5_context, struct \fBHDB\fP *, krb5_data, krb5_data *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb__put\fP )(krb5_context, struct \fBHDB\fP *, int, krb5_data, krb5_data)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb__del\fP )(krb5_context, struct \fBHDB\fP *, krb5_data)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_destroy\fP )(krb5_context, struct \fBHDB\fP *)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_get_realms\fP )(krb5_context, struct \fBHDB\fP *, krb5_realm **)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_password\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, const char *, int)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_auth_status\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, int)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_check_constrained_delegation\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_check_pkinit_ms_upn_match\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_check_s4u2self\fP )(krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +.br +.ti -1c +.RI "krb5_error_code(* \fBhdb_set_sync\fP )(krb5_context, struct \fBHDB\fP *, int)" +.br +.in -1c +.SH "Detailed Description" +.PP +\fBHDB\fP backend function pointer structure +.PP +The \fBHDB\fP structure is what the KDC and kadmind framework uses to query the backend database when talking about principals\&. +.SH "Field Documentation" +.PP +.SS "krb5_error_code(* HDB::hdb__del) (krb5_context, struct \fBHDB\fP *, krb5_data)" +Delete and hdb_entry from a classical DB backend +.PP +This function takes a principal key (krb5_data) naming the record to delete\&. +.PP +Same discussion as in \fBHDB::hdb__put\fP +.SS "krb5_error_code(* HDB::hdb__get) (krb5_context, struct \fBHDB\fP *, krb5_data, krb5_data *)" +Get an hdb_entry from a classical DB backend +.PP +This function takes a principal key (krb5_data) and returns all data related to principal in the return krb5_data\&. The returned encoded entry is of type hdb_entry or hdb_entry_alias\&. +.SS "krb5_error_code(* HDB::hdb__put) (krb5_context, struct \fBHDB\fP *, int, krb5_data, krb5_data)" +Store an hdb_entry from a classical DB backend +.PP +This function takes a principal key (krb5_data) and encoded hdb_entry or hdb_entry_alias as the data to store\&. +.PP +For a file-based DB, this must synchronize to disk when done\&. This is sub-optimal for kadm5_s_rename_principal(), and for kadm5_s_modify_principal() when using principal aliases; to improve this so that only one fsync() need be done per-transaction will require \fBHDB\fP API extensions\&. +.SS "krb5_error_code(* HDB::hdb_auth_status) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, int)" +Auth feedback +.PP +This is a feedback call that allows backends that provides lockout functionality to register failure and/or successes\&. +.PP +In case the entry is locked out, the backend should set the hdb_entry\&.flags\&.locked-out flag\&. +.SS "krb5_error_code(* HDB::hdb_check_constrained_delegation) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +Check if delegation is allowed\&. +.SS "krb5_error_code(* HDB::hdb_check_pkinit_ms_upn_match) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +Check if this name is an alias for the supplied client for PKINIT userPrinicpalName logins +.SS "krb5_error_code(* HDB::hdb_check_s4u2self) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, krb5_const_principal)" +Check if s4u2self is allowed from this client to this server +.SS "krb5_error_code(* HDB::hdb_close) (krb5_context, struct \fBHDB\fP *)" +Close the database for transaction +.PP +Closes the database for further transactions, wont release any permanant resources\&. the database can be ->hdb_open-ed again\&. +.SS "krb5_error_code(* HDB::hdb_destroy) (krb5_context, struct \fBHDB\fP *)" +Destroy the handle to the database\&. +.PP +Destroy the handle to the database, deallocate all memory and related resources\&. Does not remove any permanent data\&. Its the logical reverse of hdb_create() function that is the entry point for the module\&. +.SS "krb5_error_code(* HDB::hdb_fetch_kvno) (krb5_context, struct \fBHDB\fP *, krb5_const_principal, unsigned, krb5_kvno, \fBhdb_entry_ex\fP *)" +Fetch an entry from the backend +.PP +Fetch an entry from the backend, flags are what type of entry should be fetch: client, server, krbtgt\&. knvo (if specified and flags HDB_F_KVNO_SPECIFIED set) is the kvno to get +.SS "krb5_error_code(* HDB::hdb_firstkey) (krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +As part of iteration, fetch one entry +.SS "void(* HDB::hdb_free) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *)" +Free an entry after use\&. +.SS "krb5_error_code(* HDB::hdb_get_realms) (krb5_context, struct \fBHDB\fP *, krb5_realm **)" +Get the list of realms this backend handles\&. This call is optional to support\&. The returned realms are used for announcing the realms over bonjour\&. Free returned array with krb5_free_host_realm()\&. +.SS "krb5_error_code(* HDB::hdb_lock) (krb5_context, struct \fBHDB\fP *, int)" +Lock database +.PP +A lock can only be held by one consumers\&. Transaction can still happen on the database while the lock is held, so the entry is only useful for syncroning creation of the database and renaming of the database\&. +.SS "char* HDB::hdb_name" +don't use, only for DB3 +.SS "krb5_error_code(* HDB::hdb_nextkey) (krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +As part of iteration, fetch next entry +.SS "krb5_error_code(* HDB::hdb_open) (krb5_context, struct \fBHDB\fP *, int, mode_t)" +Open (or create) the a Kerberos database\&. +.PP +Open (or create) the a Kerberos database that was resolved with hdb_create()\&. The third and fourth flag to the function are the same as open(), thus passing O_CREAT will create the data base if it doesn't exists\&. +.PP +Then done the caller should call \fBhdb_close()\fP, and to release all resources \fBhdb_destroy()\fP\&. +.SS "krb5_error_code(* HDB::hdb_password) (krb5_context, struct \fBHDB\fP *, \fBhdb_entry_ex\fP *, const char *, int)" +Change password\&. +.PP +Will update keys for the entry when given password\&. The new keys must be written into the entry and will then later be ->\fBhdb_store()\fP into the database\&. The backend will still perform all other operations, increasing the kvno, and update modification timestamp\&. +.PP +The backend needs to call _kadm5_set_keys() and perform password quality checks\&. +.SS "krb5_error_code(* HDB::hdb_remove) (krb5_context, struct \fBHDB\fP *, unsigned, krb5_const_principal)" +Remove an entry from the database\&. +.SS "krb5_error_code(* HDB::hdb_rename) (krb5_context, struct \fBHDB\fP *, const char *)" +Rename the data base\&. +.PP +Assume that the database is not hdb_open'ed and not locked\&. +.SS "krb5_error_code(* HDB::hdb_set_sync) (krb5_context, struct \fBHDB\fP *, int)" +Enable/disable synchronous updates +.PP +Calling this with 0 disables sync\&. Calling it with non-zero enables sync and does an fsync()\&. +.SS "krb5_error_code(* HDB::hdb_store) (krb5_context, struct \fBHDB\fP *, unsigned, \fBhdb_entry_ex\fP *)" +Store an entry to database +.SS "krb5_error_code(* HDB::hdb_unlock) (krb5_context, struct \fBHDB\fP *)" +Unlock database + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal hdb library from the source code\&. diff --git a/static/netbsd/man3/HMAC.3 b/static/netbsd/man3/HMAC.3 new file mode 100644 index 00000000..47ba4342 --- /dev/null +++ b/static/netbsd/man3/HMAC.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: hmac.3,v 1.6 2018/05/23 02:08:40 christos Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\"TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 22, 2018 +.Dt HMAC 3 +.Os +.Sh NAME +.Nm hmac +.Nd compute a key-Hash Message Authentication Code +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft ssize_t +.Fn hmac "const char *hname" "const void *key" "size_t klen" "const void *text" "size_t tlen" "void *digest" "size_t dlen" +.Sh DESCRIPTION +The +.Fn hmac +function computes the key-Hash Message Authentication Code per +.Tn RFC 2104 +and places the result in +.Fa digest +writing up to +.Fa dlen +bytes. +The actual number of bytes that would be written is returned. +.Pp +The hash functions supported are: md2, md4, md5, rmd160, sha1, sha224, +sha256, sha384, and sha512. +.Sh RETURN VALUES +The +.Fn hmac +function returns +.Dv \-1 +if the +.Fa hname +is not found. +Otherwise the actual length of the digest string is returned (which could +be bigger or smaller than +.Fa dlen ) . +This length depends on the hashing function selected. +.Sh SEE ALSO +.Xr md2 3 , +.Xr md4 3 , +.Xr md5 3 , +.Xr openssl_HMAC 3 , +.Xr openssl_MD2 3 , +.Xr openssl_MD4 3 , +.Xr openssl_MD5 3 , +.Xr rmd160 3 , +.Xr sha1 3 , +.Xr sha2 3 +.Sh STANDARDS +.Rs +.%R RFC 2104 +.Re +.Sh NOTES +The maximum digest length has been extended from +.Dv 64 +to +.Dv 128 +bytes to handle SHA2. +.Sh HISTORY +The +.Fn hmac +function appeared in +.Nx 8 . diff --git a/static/netbsd/man3/MD5.3 b/static/netbsd/man3/MD5.3 new file mode 100644 index 00000000..4560554f --- /dev/null +++ b/static/netbsd/man3/MD5.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: MD5.3,v 1.11 2025/04/16 15:23:15 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "MD5 3" +.TH MD5 3 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final \- MD2, MD4, and MD5 hash functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& unsigned char *MD2(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD2_Init(MD2_CTX *c); +\& int MD2_Update(MD2_CTX *c, const unsigned char *data, unsigned long len); +\& int MD2_Final(unsigned char *md, MD2_CTX *c); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& unsigned char *MD4(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD4_Init(MD4_CTX *c); +\& int MD4_Update(MD4_CTX *c, const void *data, unsigned long len); +\& int MD4_Final(unsigned char *md, MD4_CTX *c); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& unsigned char *MD5(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD5_Init(MD5_CTX *c); +\& int MD5_Update(MD5_CTX *c, const void *data, unsigned long len); +\& int MD5_Final(unsigned char *md, MD5_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3). +.PP +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. +.PP +\&\fBMD2()\fR, \fBMD4()\fR, and \fBMD5()\fR compute the MD2, MD4, and MD5 message digest +of the \fBn\fR bytes at \fBd\fR and place it in \fBmd\fR (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If \fBmd\fR is NULL, the digest is placed in a static +array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBMD2_Init()\fR initializes a \fBMD2_CTX\fR structure. +.PP +\&\fBMD2_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fBMD2_Final()\fR places the message digest in \fBmd\fR, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the \fBMD2_CTX\fR. +.PP +\&\fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, and +\&\fBMD5_Final()\fR are analogous using an \fBMD4_CTX\fR and \fBMD5_CTX\fR structure. +.PP +Applications should use the higher level functions +\&\fBEVP_DigestInit\fR\|(3) +etc. instead of calling the hash functions directly. +.SH NOTE +.IX Header "NOTE" +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, hashes from the SHA\-2 or SHA\-3 family +should be preferred. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBMD2()\fR, \fBMD4()\fR, and \fBMD5()\fR return pointers to the hash value. +.PP +\&\fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, +\&\fBMD4_Final()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, and \fBMD5_Final()\fR return 1 for +success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 1319, RFC 1320, RFC 1321 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3), \fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/MDC2_Init.3 b/static/netbsd/man3/MDC2_Init.3 new file mode 100644 index 00000000..74454988 --- /dev/null +++ b/static/netbsd/man3/MDC2_Init.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: MDC2_Init.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "MDC2_Init 3" +.TH MDC2_Init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +MDC2, MDC2_Init, MDC2_Update, MDC2_Final \- MDC2 hash function +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& unsigned char *MDC2(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int MDC2_Init(MDC2_CTX *c); +\& int MDC2_Update(MDC2_CTX *c, const unsigned char *data, +\& unsigned long len); +\& int MDC2_Final(unsigned char *md, MDC2_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3). +.PP +MDC2 is a method to construct hash functions with 128 bit output from +block ciphers. These functions are an implementation of MDC2 with +DES. +.PP +\&\fBMDC2()\fR computes the MDC2 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +MDC2_DIGEST_LENGTH == 16 bytes of output). If \fBmd\fR is NULL, the digest +is placed in a static array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBMDC2_Init()\fR initializes a \fBMDC2_CTX\fR structure. +.PP +\&\fBMDC2_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fBMDC2_Final()\fR places the message digest in \fBmd\fR, which must have space +for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the \fBMDC2_CTX\fR. +.PP +Applications should use the higher level functions +\&\fBEVP_DigestInit\fR\|(3) etc. instead of calling the +hash functions directly. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBMDC2()\fR returns a pointer to the hash value. +.PP +\&\fBMDC2_Init()\fR, \fBMDC2_Update()\fR and \fBMDC2_Final()\fR return 1 for success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ISO/IEC 10118\-2:2000 Hash\-Function 2, with DES as the underlying block cipher. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/NCONF_new_ex.3 b/static/netbsd/man3/NCONF_new_ex.3 new file mode 100644 index 00000000..77c72aa5 --- /dev/null +++ b/static/netbsd/man3/NCONF_new_ex.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: NCONF_new_ex.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "NCONF_new_ex 3" +.TH NCONF_new_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +NCONF_new_ex, NCONF_new, NCONF_free, NCONF_default, NCONF_load, +NCONF_get0_libctx, NCONF_get_section, NCONF_get_section_names +\&\- functionality to Load and parse configuration files manually +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct { +\& char *section; +\& char *name; +\& char *value; +\& } CONF_VALUE; +\& +\& CONF *NCONF_new_ex(OSSL_LIB_CTX *libctx, CONF_METHOD *meth); +\& CONF *NCONF_new(CONF_METHOD *meth); +\& void NCONF_free(CONF *conf); +\& CONF_METHOD *NCONF_default(void); +\& int NCONF_load(CONF *conf, const char *file, long *eline); +\& OSSL_LIB_CTX *NCONF_get0_libctx(const CONF *conf); +\& +\& STACK_OF(CONF_VALUE) *NCONF_get_section(const CONF *conf, const char *name); +\& STACK_OF(OPENSSL_CSTRING) *NCONF_get_section_names(const CONF *conf); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBNCONF_new_ex()\fR creates a new CONF object in heap memory and assigns to +it a context \fIlibctx\fR that can be used during loading. If the method table +\&\fImeth\fR is set to NULL then the default value of \fBNCONF_default()\fR is used. +.PP +\&\fBNCONF_new()\fR is similar to \fBNCONF_new_ex()\fR but sets the \fIlibctx\fR to NULL. +.PP +\&\fBNCONF_free()\fR frees the data associated with \fIconf\fR and then frees the \fIconf\fR +object. If the argument is NULL, nothing is done. +.PP +\&\fBNCONF_load()\fR parses the file named \fIfilename\fR and adds the values found to +\&\fIconf\fR. If an error occurs \fIfile\fR and \fIeline\fR list the file and line that +the load failed on if they are not NULL. +.PP +\&\fBNCONF_default()\fR gets the default method table for processing a configuration file. +.PP +\&\fBNCONF_get0_libctx()\fR gets the library context associated with the \fIconf\fR +parameter. +.PP +\&\fBNCONF_get_section_names()\fR gets the names of the sections associated with +the \fIconf\fR as \fBSTACK_OF(OPENSSL_CSTRING)\fR strings. The individual strings +are associated with the \fIconf\fR and will be invalid after \fIconf\fR is +freed. The returned stack must be freed with \fBsk_OPENSSL_CSTRING_free()\fR. +.PP +\&\fBNCONF_get_section()\fR gets the config values associated with the \fIconf\fR from +the config section \fIname\fR as \fBSTACK_OF(CONF_VALUE)\fR structures. The returned +stack is associated with the \fIconf\fR and will be invalid after \fIconf\fR +is freed. It must not be freed by the caller. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBNCONF_load()\fR returns 1 on success or 0 on error. +.PP +\&\fBNCONF_new_ex()\fR and \fBNCONF_new()\fR return a newly created \fICONF\fR object +or NULL if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCONF_modules_load_file\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +\&\fBNCONF_new_ex()\fR, \fBNCONF_get0_libctx()\fR, and \fBNCONF_get_section_names()\fR were added +in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OBJ_nid2obj.3 b/static/netbsd/man3/OBJ_nid2obj.3 new file mode 100644 index 00000000..29ceec2d --- /dev/null +++ b/static/netbsd/man3/OBJ_nid2obj.3 @@ -0,0 +1,272 @@ +.\" $NetBSD: OBJ_nid2obj.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OBJ_nid2obj 3" +.TH OBJ_nid2obj 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +i2t_ASN1_OBJECT, +OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, +OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, +OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup, OBJ_add_sigid +\&\- ASN1 object utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OBJECT *OBJ_nid2obj(int n); +\& const char *OBJ_nid2ln(int n); +\& const char *OBJ_nid2sn(int n); +\& +\& int OBJ_obj2nid(const ASN1_OBJECT *o); +\& int OBJ_ln2nid(const char *ln); +\& int OBJ_sn2nid(const char *sn); +\& +\& int OBJ_txt2nid(const char *s); +\& +\& ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name); +\& int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); +\& +\& int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); +\& +\& int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); +\& ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o); +\& +\& int OBJ_create(const char *oid, const char *sn, const char *ln); +\& +\& size_t OBJ_length(const ASN1_OBJECT *obj); +\& const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); +\& +\& int OBJ_add_sigid(int signid, int dig_id, int pkey_id); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void OBJ_cleanup(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The ASN1 object utility functions process ASN1_OBJECT structures which are +a representation of the ASN1 OBJECT IDENTIFIER (OID) type. +For convenience, OIDs are usually represented in source code as numeric +identifiers, or \fBNID\fRs. OpenSSL has an internal table of OIDs that +are generated when the library is built, and their corresponding NIDs +are available as defined constants. For the functions below, application +code should treat all returned values \-\- OIDs, NIDs, or names \-\- as +constants. +.PP +\&\fBOBJ_nid2obj()\fR, \fBOBJ_nid2ln()\fR and \fBOBJ_nid2sn()\fR convert the NID \fIn\fR to +an ASN1_OBJECT structure, its long name and its short name respectively, +or \fBNULL\fR if an error occurred. +.PP +\&\fBOBJ_obj2nid()\fR, \fBOBJ_ln2nid()\fR, \fBOBJ_sn2nid()\fR return the corresponding NID +for the object \fIo\fR, the long name \fIln\fR or the short name \fIsn\fR respectively +or NID_undef if an error occurred. +.PP +\&\fBOBJ_txt2nid()\fR returns NID corresponding to text string \fIs\fR. \fIs\fR can be +a long name, a short name or the numerical representation of an object. +.PP +\&\fBOBJ_txt2obj()\fR converts the text string \fIs\fR into an ASN1_OBJECT structure. +If \fIno_name\fR is 0 then long names and short names will be interpreted +as well as numerical forms. If \fIno_name\fR is 1 only the numerical form +is acceptable. +.PP +\&\fBOBJ_obj2txt()\fR converts the \fBASN1_OBJECT\fR \fIa\fR into a textual representation. +Unless \fIbuf\fR is NULL, +the representation is written as a NUL\-terminated string to \fIbuf\fR, where +at most \fIbuf_len\fR bytes are written, truncating the result if necessary. +In any case it returns the total string length, excluding the NUL character, +required for non\-truncated representation, or \-1 on error. +If \fIno_name\fR is 0 then if the object has a long or short name +then that will be used, otherwise the numerical form will be used. +If \fIno_name\fR is 1 then the numerical form will always be used. +.PP +\&\fBi2t_ASN1_OBJECT()\fR is the same as \fBOBJ_obj2txt()\fR with the \fIno_name\fR set to zero. +.PP +\&\fBOBJ_cmp()\fR compares \fIa\fR to \fIb\fR. If the two are identical 0 is returned. +.PP +\&\fBOBJ_dup()\fR returns a copy of \fIo\fR. +.PP +\&\fBOBJ_create()\fR adds a new object to the internal table. \fIoid\fR is the +numerical form of the object, \fIsn\fR the short name and \fIln\fR the +long name. A new NID is returned for the created object in case of +success and NID_undef in case of failure. Any of \fIoid\fR, \fIsn\fR and +\&\fIln\fR may be NULL, but not all at once. +.PP +\&\fBOBJ_length()\fR returns the size of the content octets of \fIobj\fR. +.PP +\&\fBOBJ_get0_data()\fR returns a pointer to the content octets of \fIobj\fR. +The returned pointer is an internal pointer which \fBmust not\fR be freed. +.PP +\&\fBOBJ_add_sigid()\fR creates a new composite "Signature Algorithm" that associates a +given NID with two other NIDs \- one representing the underlying signature +algorithm and the other representing a digest algorithm to be used in +conjunction with it. \fIsignid\fR represents the NID for the composite "Signature +Algorithm", \fIdig_id\fR is the NID for the digest algorithm and \fIpkey_id\fR is the +NID for the underlying signature algorithm. As there are signature algorithms +that do not require a digest, NID_undef is a valid \fIdig_id\fR. +.PP +\&\fBOBJ_cleanup()\fR releases any resources allocated by creating new objects. +.SH NOTES +.IX Header "NOTES" +Objects in OpenSSL can have a short name, a long name and a numerical +identifier (NID) associated with them. A standard set of objects is +represented in an internal table. The appropriate values are defined +in the header file \fBobjects.h\fR. +.PP +For example the OID for commonName has the following definitions: +.PP +.Vb 3 +\& #define SN_commonName "CN" +\& #define LN_commonName "commonName" +\& #define NID_commonName 13 +.Ve +.PP +New objects can be added by calling \fBOBJ_create()\fR. +.PP +Table objects have certain advantages over other objects: for example +their NIDs can be used in a C language switch statement. They are +also static constant structures which are shared: that is there +is only a single constant structure for each table object. +.PP +Objects which are not in the table have the NID value NID_undef. +.PP +Objects do not need to be in the internal tables to be processed, +the functions \fBOBJ_txt2obj()\fR and \fBOBJ_obj2txt()\fR can process the numerical +form of an OID. +.PP +Some objects are used to represent algorithms which do not have a +corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently +exists for a particular algorithm). As a result they \fBcannot\fR be encoded or +decoded as part of ASN.1 structures. Applications can determine if there +is a corresponding OBJECT IDENTIFIER by checking \fBOBJ_length()\fR is not zero. +.PP +These functions cannot return \fBconst\fR because an \fBASN1_OBJECT\fR can +represent both an internal, constant, OID and a dynamically\-created one. +The latter cannot be constant because it needs to be freed after use. +.PP +These functions were not thread safe in OpenSSL 3.0 and before. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOBJ_nid2obj()\fR returns an \fBASN1_OBJECT\fR structure or \fBNULL\fR is an +error occurred. +.PP +\&\fBOBJ_nid2ln()\fR and \fBOBJ_nid2sn()\fR returns a valid string or \fBNULL\fR +on error. +.PP +\&\fBOBJ_obj2nid()\fR, \fBOBJ_ln2nid()\fR, \fBOBJ_sn2nid()\fR and \fBOBJ_txt2nid()\fR return +a NID or \fBNID_undef\fR on error. +.PP +\&\fBOBJ_add_sigid()\fR returns 1 on success or 0 on error. +.PP +\&\fBi2t_ASN1_OBJECT()\fR an \fBOBJ_obj2txt()\fR return \-1 on error. +On success, they return the length of the string written to \fIbuf\fR if \fIbuf\fR is +not NULL and \fIbuf_len\fR is big enough, otherwise the total string length. +Note that this does not count the trailing NUL character. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create an object for \fBcommonName\fR: +.PP +.Vb 1 +\& ASN1_OBJECT *o = OBJ_nid2obj(NID_commonName); +.Ve +.PP +Check if an object is \fBcommonName\fR +.PP +.Vb 2 +\& if (OBJ_obj2nid(obj) == NID_commonName) +\& /* Do something */ +.Ve +.PP +Create a new NID and initialize an object from it: +.PP +.Vb 2 +\& int new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); +\& ASN1_OBJECT *obj = OBJ_nid2obj(new_nid); +.Ve +.PP +Create a new object directly: +.PP +.Vb 1 +\& obj = OBJ_txt2obj("1.2.3.4", 1); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOBJ_cleanup()\fR was deprecated in OpenSSL 1.1.0 by \fBOPENSSL_init_crypto\fR\|(3) +and should not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_REQUEST_new.3 b/static/netbsd/man3/OCSP_REQUEST_new.3 new file mode 100644 index 00000000..dfde2a46 --- /dev/null +++ b/static/netbsd/man3/OCSP_REQUEST_new.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: OCSP_REQUEST_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_REQUEST_new 3" +.TH OCSP_REQUEST_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign, +OCSP_request_add1_cert, OCSP_request_onereq_count, +OCSP_request_onereq_get0 \- OCSP request functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OCSP_REQUEST *OCSP_REQUEST_new(void); +\& void OCSP_REQUEST_free(OCSP_REQUEST *req); +\& +\& OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid); +\& +\& int OCSP_request_sign(OCSP_REQUEST *req, +\& X509 *signer, EVP_PKEY *key, const EVP_MD *dgst, +\& STACK_OF(X509) *certs, unsigned long flags); +\& +\& int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert); +\& +\& int OCSP_request_onereq_count(OCSP_REQUEST *req); +\& OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOCSP_REQUEST_new()\fR allocates and returns an empty \fBOCSP_REQUEST\fR structure. +.PP +\&\fBOCSP_REQUEST_free()\fR frees up the request structure \fBreq\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOCSP_request_add0_id()\fR adds certificate ID \fBcid\fR to \fBreq\fR. It returns +the \fBOCSP_ONEREQ\fR structure added so an application can add additional +extensions to the request. The \fBid\fR parameter \fBMUST NOT\fR be freed up after +the operation. +.PP +\&\fBOCSP_request_sign()\fR signs OCSP request \fBreq\fR using certificate +\&\fBsigner\fR, private key \fBkey\fR, digest \fBdgst\fR and additional certificates +\&\fBcerts\fR. If the \fBflags\fR option \fBOCSP_NOCERTS\fR is set then no certificates +will be included in the request. +.PP +\&\fBOCSP_request_add1_cert()\fR adds certificate \fBcert\fR to request \fBreq\fR. The +application is responsible for freeing up \fBcert\fR after use. +.PP +\&\fBOCSP_request_onereq_count()\fR returns the total number of \fBOCSP_ONEREQ\fR +structures in \fBreq\fR. +.PP +\&\fBOCSP_request_onereq_get0()\fR returns an internal pointer to the \fBOCSP_ONEREQ\fR +contained in \fBreq\fR of index \fBi\fR. The index value \fBi\fR runs from 0 to +OCSP_request_onereq_count(req) \- 1. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_REQUEST_new()\fR returns an empty \fBOCSP_REQUEST\fR structure or \fBNULL\fR if +an error occurred. +.PP +\&\fBOCSP_request_add0_id()\fR returns the \fBOCSP_ONEREQ\fR structure containing \fBcid\fR +or \fBNULL\fR if an error occurred. +.PP +\&\fBOCSP_request_sign()\fR and \fBOCSP_request_add1_cert()\fR return 1 for success and 0 +for failure. +.PP +\&\fBOCSP_request_onereq_count()\fR returns the total number of \fBOCSP_ONEREQ\fR +structures in \fBreq\fR and \-1 on error. +.PP +\&\fBOCSP_request_onereq_get0()\fR returns a pointer to an \fBOCSP_ONEREQ\fR structure +or \fBNULL\fR if the index value is out or range. +.SH NOTES +.IX Header "NOTES" +An OCSP request structure contains one or more \fBOCSP_ONEREQ\fR structures +corresponding to each certificate. +.PP +\&\fBOCSP_request_onereq_count()\fR and \fBOCSP_request_onereq_get0()\fR are mainly used by +OCSP responders. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create an \fBOCSP_REQUEST\fR structure for certificate \fBcert\fR with issuer +\&\fBissuer\fR: +.PP +.Vb 2 +\& OCSP_REQUEST *req; +\& OCSP_ID *cid; +\& +\& req = OCSP_REQUEST_new(); +\& if (req == NULL) +\& /* error */ +\& cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer); +\& if (cid == NULL) +\& /* error */ +\& +\& if (OCSP_REQUEST_add0_id(req, cid) == NULL) +\& /* error */ +\& +\& /* Do something with req, e.g. query responder */ +\& +\& OCSP_REQUEST_free(req); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBOCSP_cert_to_id\fR\|(3), +\&\fBOCSP_request_add1_nonce\fR\|(3), +\&\fBOCSP_resp_find_status\fR\|(3), +\&\fBOCSP_response_status\fR\|(3), +\&\fBOCSP_sendreq_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_cert_to_id.3 b/static/netbsd/man3/OCSP_cert_to_id.3 new file mode 100644 index 00000000..acd9f4dd --- /dev/null +++ b/static/netbsd/man3/OCSP_cert_to_id.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: OCSP_cert_to_id.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_cert_to_id 3" +.TH OCSP_cert_to_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp, +OCSP_id_cmp, OCSP_id_get0_info \- OCSP certificate ID utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst, +\& X509 *subject, X509 *issuer); +\& +\& OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst, +\& X509_NAME *issuerName, +\& ASN1_BIT_STRING *issuerKey, +\& ASN1_INTEGER *serialNumber); +\& +\& void OCSP_CERTID_free(OCSP_CERTID *id); +\& +\& int OCSP_id_issuer_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b); +\& int OCSP_id_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b); +\& +\& int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd, +\& ASN1_OCTET_STRING **pikeyHash, +\& ASN1_INTEGER **pserial, OCSP_CERTID *cid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOCSP_cert_to_id()\fR creates and returns a new \fBOCSP_CERTID\fR structure using +message digest \fBdgst\fR for certificate \fBsubject\fR with issuer \fBissuer\fR. If +\&\fBdgst\fR is \fBNULL\fR then SHA1 is used. +.PP +\&\fBOCSP_cert_id_new()\fR creates and returns a new \fBOCSP_CERTID\fR using \fBdgst\fR and +issuer name \fBissuerName\fR, issuer key hash \fBissuerKey\fR and serial number +\&\fBserialNumber\fR. +.PP +\&\fBOCSP_CERTID_free()\fR frees up \fBid\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOCSP_id_cmp()\fR compares \fBOCSP_CERTID\fR \fBa\fR and \fBb\fR. +.PP +\&\fBOCSP_id_issuer_cmp()\fR compares only the issuer name of \fBOCSP_CERTID\fR \fBa\fR and \fBb\fR. +.PP +\&\fBOCSP_id_get0_info()\fR returns the issuer name hash, hash OID, issuer key hash and +serial number contained in \fBcid\fR. If any of the values are not required the +corresponding parameter can be set to \fBNULL\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_cert_to_id()\fR and \fBOCSP_cert_id_new()\fR return either a pointer to a valid +\&\fBOCSP_CERTID\fR structure or \fBNULL\fR if an error occurred. +.PP +\&\fBOCSP_id_cmp()\fR and \fBOCSP_id_issuer_cmp()\fR returns zero for a match and nonzero +otherwise. +.PP +\&\fBOCSP_CERTID_free()\fR does not return a value. +.PP +\&\fBOCSP_id_get0_info()\fR returns 1 for success and 0 for failure. +.SH NOTES +.IX Header "NOTES" +OCSP clients will typically only use \fBOCSP_cert_to_id()\fR or \fBOCSP_cert_id_new()\fR: +the other functions are used by responder applications. +.PP +The values returned by \fBOCSP_id_get0_info()\fR are internal pointers and \fBMUST +NOT\fR be freed up by an application: they will be freed when the corresponding +\&\fBOCSP_CERTID\fR structure is freed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBOCSP_request_add1_nonce\fR\|(3), +\&\fBOCSP_REQUEST_new\fR\|(3), +\&\fBOCSP_resp_find_status\fR\|(3), +\&\fBOCSP_response_status\fR\|(3), +\&\fBOCSP_sendreq_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_request_add1_nonce.3 b/static/netbsd/man3/OCSP_request_add1_nonce.3 new file mode 100644 index 00000000..ca20f09d --- /dev/null +++ b/static/netbsd/man3/OCSP_request_add1_nonce.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: OCSP_request_add1_nonce.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_request_add1_nonce 3" +.TH OCSP_request_add1_nonce 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce \- OCSP nonce functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len); +\& int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len); +\& int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req); +\& int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOCSP_request_add1_nonce()\fR adds a nonce of value \fBval\fR and length \fBlen\fR to +OCSP request \fBreq\fR. If \fBval\fR is \fBNULL\fR a random nonce is used. If \fBlen\fR +is zero or negative a default length will be used (currently 16 bytes). +.PP +\&\fBOCSP_basic_add1_nonce()\fR is identical to \fBOCSP_request_add1_nonce()\fR except +it adds a nonce to OCSP basic response \fBresp\fR. +.PP +\&\fBOCSP_check_nonce()\fR compares the nonce value in \fBreq\fR and \fBresp\fR. +.PP +\&\fBOCSP_copy_nonce()\fR copies any nonce value present in \fBreq\fR to \fBresp\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_request_add1_nonce()\fR and \fBOCSP_basic_add1_nonce()\fR return 1 for success +and 0 for failure. +.PP +\&\fBOCSP_copy_nonce()\fR returns 1 if a nonce was successfully copied, 2 if no nonce +was present in \fBreq\fR and 0 if an error occurred. +.PP +\&\fBOCSP_check_nonce()\fR returns the result of the nonce comparison between \fBreq\fR +and \fBresp\fR. The return value indicates the result of the comparison. If +nonces are present and equal 1 is returned. If the nonces are absent 2 is +returned. If a nonce is present in the response only 3 is returned. If nonces +are present and unequal 0 is returned. If the nonce is present in the request +only then \-1 is returned. +.SH NOTES +.IX Header "NOTES" +For most purposes the nonce value in a request is set to a random value so +the \fBval\fR parameter in \fBOCSP_request_add1_nonce()\fR is usually NULL. +.PP +An OCSP nonce is typically added to an OCSP request to thwart replay attacks +by checking the same nonce value appears in the response. +.PP +Some responders may include a nonce in all responses even if one is not +supplied. +.PP +Some responders cache OCSP responses and do not sign each response for +performance reasons. As a result they do not support nonces. +.PP +The return values of \fBOCSP_check_nonce()\fR can be checked to cover each case. A +positive return value effectively indicates success: nonces are both present +and match, both absent or present in the response only. A nonzero return +additionally covers the case where the nonce is present in the request only: +this will happen if the responder doesn\*(Aqt support nonces. A zero return value +indicates present and mismatched nonces: this should be treated as an error +condition. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBOCSP_cert_to_id\fR\|(3), +\&\fBOCSP_REQUEST_new\fR\|(3), +\&\fBOCSP_resp_find_status\fR\|(3), +\&\fBOCSP_response_status\fR\|(3), +\&\fBOCSP_sendreq_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_resp_find_status.3 b/static/netbsd/man3/OCSP_resp_find_status.3 new file mode 100644 index 00000000..19e4ddcf --- /dev/null +++ b/static/netbsd/man3/OCSP_resp_find_status.3 @@ -0,0 +1,278 @@ +.\" $NetBSD: OCSP_resp_find_status.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_resp_find_status 3" +.TH OCSP_resp_find_status 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_resp_find_status, OCSP_resp_count, +OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, +OCSP_resp_get0_produced_at, OCSP_resp_get0_signature, +OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata, +OCSP_resp_get0_certs, OCSP_resp_get0_signer, +OCSP_resp_get0_id, OCSP_resp_get1_id, +OCSP_check_validity, OCSP_basic_verify +\&\- OCSP response utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status, +\& int *reason, +\& ASN1_GENERALIZEDTIME **revtime, +\& ASN1_GENERALIZEDTIME **thisupd, +\& ASN1_GENERALIZEDTIME **nextupd); +\& +\& int OCSP_resp_count(OCSP_BASICRESP *bs); +\& OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx); +\& int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last); +\& int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason, +\& ASN1_GENERALIZEDTIME **revtime, +\& ASN1_GENERALIZEDTIME **thisupd, +\& ASN1_GENERALIZEDTIME **nextupd); +\& +\& const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at( +\& const OCSP_BASICRESP* single); +\& +\& const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs); +\& const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs); +\& const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs); +\& const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs); +\& +\& int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer, +\& STACK_OF(X509) *extra_certs); +\& +\& int OCSP_resp_get0_id(const OCSP_BASICRESP *bs, +\& const ASN1_OCTET_STRING **pid, +\& const X509_NAME **pname); +\& int OCSP_resp_get1_id(const OCSP_BASICRESP *bs, +\& ASN1_OCTET_STRING **pid, +\& X509_NAME **pname); +\& +\& int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd, +\& ASN1_GENERALIZEDTIME *nextupd, +\& long sec, long maxsec); +\& +\& int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs, +\& X509_STORE *st, unsigned long flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOCSP_resp_find_status()\fR searches \fIbs\fR for an OCSP response for \fIid\fR. If it is +successful the fields of the response are returned in \fI*status\fR, \fI*reason\fR, +\&\fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR. The \fI*status\fR value will be one of +\&\fBV_OCSP_CERTSTATUS_GOOD\fR, \fBV_OCSP_CERTSTATUS_REVOKED\fR or +\&\fBV_OCSP_CERTSTATUS_UNKNOWN\fR. The \fI*reason\fR and \fI*revtime\fR fields are only +set if the status is \fBV_OCSP_CERTSTATUS_REVOKED\fR. If set the \fI*reason\fR field +will be set to the revocation reason which will be one of +\&\fBOCSP_REVOKED_STATUS_NOSTATUS\fR, \fBOCSP_REVOKED_STATUS_UNSPECIFIED\fR, +\&\fBOCSP_REVOKED_STATUS_KEYCOMPROMISE\fR, \fBOCSP_REVOKED_STATUS_CACOMPROMISE\fR, +\&\fBOCSP_REVOKED_STATUS_AFFILIATIONCHANGED\fR, \fBOCSP_REVOKED_STATUS_SUPERSEDED\fR, +\&\fBOCSP_REVOKED_STATUS_CESSATIONOFOPERATION\fR, +\&\fBOCSP_REVOKED_STATUS_CERTIFICATEHOLD\fR or \fBOCSP_REVOKED_STATUS_REMOVEFROMCRL\fR. +.PP +\&\fBOCSP_resp_count()\fR returns the number of \fBOCSP_SINGLERESP\fR structures in \fIbs\fR. +.PP +\&\fBOCSP_resp_get0()\fR returns the \fBOCSP_SINGLERESP\fR structure in \fIbs\fR corresponding +to index \fIidx\fR, where \fIidx\fR runs from 0 to OCSP_resp_count(bs) \- 1. +.PP +\&\fBOCSP_resp_find()\fR searches \fIbs\fR for \fIid\fR and returns the index of the first +matching entry after \fIlast\fR or starting from the beginning if \fIlast\fR is \-1. +.PP +\&\fBOCSP_single_get0_status()\fR extracts the fields of \fIsingle\fR in \fI*reason\fR, +\&\fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR. +.PP +\&\fBOCSP_resp_get0_produced_at()\fR extracts the \fBproducedAt\fR field from the +single response \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_signature()\fR returns the signature from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_tbs_sigalg()\fR returns the \fBsignatureAlgorithm\fR from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_respdata()\fR returns the \fBtbsResponseData\fR from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_certs()\fR returns any certificates included in \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_signer()\fR attempts to retrieve the certificate that directly +signed \fIbs\fR. The OCSP protocol does not require that this certificate +is included in the \fBcerts\fR field of the response, so additional certificates +can be supplied via the \fIextra_certs\fR if the certificates that may have +signed the response are known via some out\-of\-band mechanism. +.PP +\&\fBOCSP_resp_get0_id()\fR gets the responder id of \fIbs\fR. If the responder ID is +a name then <*pname> is set to the name and \fI*pid\fR is set to NULL. If the +responder ID is by key ID then \fI*pid\fR is set to the key ID and \fI*pname\fR +is set to NULL. +.PP +\&\fBOCSP_resp_get1_id()\fR is the same as \fBOCSP_resp_get0_id()\fR +but leaves ownership of \fI*pid\fR and \fI*pname\fR with the caller, +who is responsible for freeing them unless the function returns 0. +.PP +\&\fBOCSP_check_validity()\fR checks the validity of its \fIthisupd\fR and \fInextupd\fR +arguments, which will be typically obtained from \fBOCSP_resp_find_status()\fR or +\&\fBOCSP_single_get0_status()\fR. If \fIsec\fR is nonzero it indicates how many seconds +leeway should be allowed in the check. If \fImaxsec\fR is positive it indicates +the maximum age of \fIthisupd\fR in seconds. +.PP +\&\fBOCSP_basic_verify()\fR checks that the basic response message \fIbs\fR is correctly +signed and that the signer certificate can be validated. It takes \fIst\fR as +the trusted store and \fIcerts\fR as a set of untrusted intermediate certificates. +The function first tries to find the signer certificate of the response +in \fIcerts\fR. It then searches the certificates the responder may have included +in \fIbs\fR unless \fIflags\fR contains \fBOCSP_NOINTERN\fR. +It fails if the signer certificate cannot be found. +Next, unless \fIflags\fR contains \fBOCSP_NOSIGS\fR, the function checks +the signature of \fIbs\fR and fails on error. Then the function already returns +success if \fIflags\fR contains \fBOCSP_NOVERIFY\fR or if the signer certificate +was found in \fIcerts\fR and \fIflags\fR contains \fBOCSP_TRUSTOTHER\fR. +Otherwise the function continues by validating the signer certificate. +If \fIflags\fR contains \fBOCSP_PARTIAL_CHAIN\fR it takes intermediate CA +certificates in \fIst\fR as trust anchors. +For more details, see the description of \fBX509_V_FLAG_PARTIAL_CHAIN\fR +in "VERIFICATION FLAGS" in \fBX509_VERIFY_PARAM_set_flags\fR\|(3). +If \fIflags\fR contains \fBOCSP_NOCHAIN\fR it ignores all certificates in \fIcerts\fR +and in \fIbs\fR, else it takes them as untrusted intermediate CA certificates +and uses them for constructing the validation path for the signer certificate. +Certificate revocation status checks using CRLs is disabled during path validation +if the signer certificate contains the \fBid\-pkix\-ocsp\-no\-check\fR extension. +After successful path +validation the function returns success if the \fBOCSP_NOCHECKS\fR flag is set. +Otherwise it verifies that the signer certificate meets the OCSP issuer +criteria including potential delegation. If this does not succeed and the +\&\fBOCSP_NOEXPLICIT\fR flag is not set the function checks for explicit +trust for OCSP signing in the root CA certificate. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_resp_find_status()\fR returns 1 if \fIid\fR is found in \fIbs\fR and 0 otherwise. +.PP +\&\fBOCSP_resp_count()\fR returns the total number of \fBOCSP_SINGLERESP\fR fields in \fIbs\fR +or \-1 on error. +.PP +\&\fBOCSP_resp_get0()\fR returns a pointer to an \fBOCSP_SINGLERESP\fR structure or +NULL on error, such as \fIidx\fR being out of range. +.PP +\&\fBOCSP_resp_find()\fR returns the index of \fIid\fR in \fIbs\fR (which may be 0) +or \-1 on error, such as when \fIid\fR was not found. +.PP +\&\fBOCSP_single_get0_status()\fR returns the status of \fIsingle\fR or \-1 if an error +occurred. +.PP +\&\fBOCSP_resp_get0_produced_at()\fR returns the \fBproducedAt\fR field from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_signature()\fR returns the signature from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_tbs_sigalg()\fR returns the \fBsignatureAlgorithm\fR field from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_respdata()\fR returns the \fBtbsResponseData\fR field from \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_certs()\fR returns any certificates included in \fIbs\fR. +.PP +\&\fBOCSP_resp_get0_signer()\fR returns 1 if the signing certificate was located, +or 0 if not found or on error. +.PP +\&\fBOCSP_resp_get0_id()\fR and \fBOCSP_resp_get1_id()\fR return 1 on success, 0 on failure. +.PP +\&\fBOCSP_check_validity()\fR returns 1 if \fIthisupd\fR and \fInextupd\fR are valid time +values and the current time + \fIsec\fR is not before \fIthisupd\fR and, +if \fImaxsec\fR >= 0, the current time \- \fImaxsec\fR is not past \fInextupd\fR. +Otherwise it returns 0 to indicate an error. +.PP +\&\fBOCSP_basic_verify()\fR returns 1 on success, 0 on verification not successful, +or \-1 on a fatal error such as malloc failure. +.SH NOTES +.IX Header "NOTES" +Applications will typically call \fBOCSP_resp_find_status()\fR using the certificate +ID of interest and then check its validity using \fBOCSP_check_validity()\fR. They +can then take appropriate action based on the status of the certificate. +.PP +An OCSP response for a certificate contains \fBthisUpdate\fR and \fBnextUpdate\fR +fields. Normally the current time should be between these two values. To +account for clock skew the \fImaxsec\fR field can be set to nonzero in +\&\fBOCSP_check_validity()\fR. Some responders do not set the \fBnextUpdate\fR field, this +would otherwise mean an ancient response would be considered valid: the +\&\fImaxsec\fR parameter to \fBOCSP_check_validity()\fR can be used to limit the permitted +age of responses. +.PP +The values written to \fI*revtime\fR, \fI*thisupd\fR and \fI*nextupd\fR by +\&\fBOCSP_resp_find_status()\fR and \fBOCSP_single_get0_status()\fR are internal pointers +which MUST NOT be freed up by the calling application. Any or all of these +parameters can be set to NULL if their value is not required. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBOCSP_cert_to_id\fR\|(3), +\&\fBOCSP_request_add1_nonce\fR\|(3), +\&\fBOCSP_REQUEST_new\fR\|(3), +\&\fBOCSP_response_status\fR\|(3), +\&\fBOCSP_sendreq_new\fR\|(3), +\&\fBX509_VERIFY_PARAM_set_flags\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_response_status.3 b/static/netbsd/man3/OCSP_response_status.3 new file mode 100644 index 00000000..6f98dfaa --- /dev/null +++ b/static/netbsd/man3/OCSP_response_status.3 @@ -0,0 +1,191 @@ +.\" $NetBSD: OCSP_response_status.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_response_status 3" +.TH OCSP_response_status 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create, +OCSP_RESPONSE_free, OCSP_RESPID_set_by_name, +OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex, +OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx +\&\- OCSP response functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OCSP_response_status(OCSP_RESPONSE *resp); +\& OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp); +\& OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs); +\& void OCSP_RESPONSE_free(OCSP_RESPONSE *resp); +\& +\& int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert); +\& int OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert); +\& int OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert); +\& +\& int OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key, +\& const EVP_MD *dgst, STACK_OF(X509) *certs, +\& unsigned long flags); +\& int OCSP_basic_sign_ctx(OCSP_BASICRESP *brsp, X509 *signer, EVP_MD_CTX *ctx, +\& STACK_OF(X509) *certs, unsigned long flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOCSP_response_status()\fR returns the OCSP response status of \fIresp\fR. It returns +one of the values: \fIOCSP_RESPONSE_STATUS_SUCCESSFUL\fR, +\&\fIOCSP_RESPONSE_STATUS_MALFORMEDREQUEST\fR, +\&\fIOCSP_RESPONSE_STATUS_INTERNALERROR\fR, \fIOCSP_RESPONSE_STATUS_TRYLATER\fR +\&\fIOCSP_RESPONSE_STATUS_SIGREQUIRED\fR, or \fIOCSP_RESPONSE_STATUS_UNAUTHORIZED\fR. +.PP +\&\fBOCSP_response_get1_basic()\fR decodes and returns the \fIOCSP_BASICRESP\fR structure +contained in \fIresp\fR. +.PP +\&\fBOCSP_response_create()\fR creates and returns an \fIOCSP_RESPONSE\fR structure for +\&\fIstatus\fR and optionally including basic response \fIbs\fR. +.PP +\&\fBOCSP_RESPONSE_free()\fR frees up OCSP response \fIresp\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOCSP_RESPID_set_by_name()\fR sets the name of the OCSP_RESPID to be the same as the +subject name in the supplied X509 certificate \fIcert\fR for the OCSP responder. +.PP +\&\fBOCSP_RESPID_set_by_key_ex()\fR sets the key of the OCSP_RESPID to be the same as the +key in the supplied X509 certificate \fIcert\fR for the OCSP responder. The key is +stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using +the library ctx \fIlibctx\fR and the property query string \fIpropq\fR (see +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information). +.PP +\&\fBOCSP_RESPID_set_by_key()\fR does the same as \fBOCSP_RESPID_set_by_key_ex()\fR except +that the default library context is used with an empty property query string. +.PP +Note that an OCSP_RESPID can only have one of the name, or the key set. Calling +\&\fBOCSP_RESPID_set_by_name()\fR or \fBOCSP_RESPID_set_by_key()\fR will clear any existing +setting. +.PP +\&\fBOCSP_RESPID_match_ex()\fR tests whether the OCSP_RESPID given in \fIrespid\fR matches +with the X509 certificate \fIcert\fR based on the SHA1 hash. To calculate the hash +the SHA1 algorithm is fetched using the library ctx \fIlibctx\fR and the property +query string \fIpropq\fR (see "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further +information). +.PP +\&\fBOCSP_RESPID_match()\fR does the same as \fBOCSP_RESPID_match_ex()\fR except that the +default library context is used with an empty property query string. +.PP +\&\fBOCSP_basic_sign()\fR signs OCSP response \fIbrsp\fR using certificate \fIsigner\fR, private key +\&\fIkey\fR, digest \fIdgst\fR and additional certificates \fIcerts\fR. If the \fIflags\fR option +\&\fIOCSP_NOCERTS\fR is set then no certificates will be included in the response. If the +\&\fIflags\fR option \fIOCSP_RESPID_KEY\fR is set then the responder is identified by key ID +rather than by name. \fBOCSP_basic_sign_ctx()\fR also signs OCSP response \fIbrsp\fR but +uses the parameters contained in digest context \fIctx\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_RESPONSE_status()\fR returns a status value. +.PP +\&\fBOCSP_response_get1_basic()\fR returns an \fIOCSP_BASICRESP\fR structure pointer or +\&\fINULL\fR if an error occurred. +.PP +\&\fBOCSP_response_create()\fR returns an \fIOCSP_RESPONSE\fR structure pointer or \fINULL\fR +if an error occurred. +.PP +\&\fBOCSP_RESPONSE_free()\fR does not return a value. +.PP +\&\fBOCSP_RESPID_set_by_name()\fR, \fBOCSP_RESPID_set_by_key()\fR, \fBOCSP_basic_sign()\fR, and +\&\fBOCSP_basic_sign_ctx()\fR return 1 on success or 0 +on failure. +.PP +\&\fBOCSP_RESPID_match()\fR returns 1 if the OCSP_RESPID and the X509 certificate match +or 0 otherwise. +.SH NOTES +.IX Header "NOTES" +\&\fBOCSP_response_get1_basic()\fR is only called if the status of a response is +\&\fIOCSP_RESPONSE_STATUS_SUCCESSFUL\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +\&\fBOCSP_cert_to_id\fR\|(3) +\&\fBOCSP_request_add1_nonce\fR\|(3) +\&\fBOCSP_REQUEST_new\fR\|(3) +\&\fBOCSP_resp_find_status\fR\|(3) +\&\fBOCSP_sendreq_new\fR\|(3) +\&\fBOCSP_RESPID_new\fR\|(3) +\&\fBOCSP_RESPID_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOCSP_RESPID_set_by_name()\fR, \fBOCSP_RESPID_set_by_key()\fR and \fBOCSP_RESPID_match()\fR +functions were added in OpenSSL 1.1.0a. +.PP +The \fBOCSP_basic_sign_ctx()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OCSP_sendreq_new.3 b/static/netbsd/man3/OCSP_sendreq_new.3 new file mode 100644 index 00000000..0673d777 --- /dev/null +++ b/static/netbsd/man3/OCSP_sendreq_new.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: OCSP_sendreq_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OCSP_sendreq_new 3" +.TH OCSP_sendreq_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OCSP_REQ_CTX, +OCSP_sendreq_new, +OCSP_sendreq_nbio, +OCSP_sendreq_bio, +OCSP_REQ_CTX_i2d, +OCSP_REQ_CTX_add1_header, +OCSP_REQ_CTX_free, +OCSP_set_max_response_length, +OCSP_REQ_CTX_set1_req +\&\- OCSP responder query functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_HTTP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, +\& const OCSP_REQUEST *req, int buf_size); +\& OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 8 +\& typedef OSSL_HTTP_REQ_CTX OCSP_REQ_CTX; +\& int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OSSL_HTTP_REQ_CTX *rctx); +\& int OCSP_REQ_CTX_i2d(OCSP_REQ_CT *rctx, const ASN1_ITEM *it, ASN1_VALUE *req); +\& int OCSP_REQ_CTX_add1_header(OCSP_REQ_CT *rctx, +\& const char *name, const char *value); +\& void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); +\& void OCSP_set_max_response_length(OCSP_REQ_CT *rctx, unsigned long len); +\& int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, const OCSP_REQUEST *req); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions perform an OCSP POST request / response transfer over HTTP, +using the HTTP request functions described in \fBOSSL_HTTP_REQ_CTX\fR\|(3). +.PP +The function \fBOCSP_sendreq_new()\fR builds a complete \fBOSSL_HTTP_REQ_CTX\fR structure +with the \fBBIO\fR \fIio\fR to be used for requests and response, the URL path \fIpath\fR, +optionally the OCSP request \fIreq\fR, and a response header maximum line length +of \fIbuf_size\fR. If \fIbuf_size\fR is zero a default value of 4KiB is used. +The \fIreq\fR may be set to NULL and provided later using \fBOCSP_REQ_CTX_set1_req()\fR +or \fBOSSL_HTTP_REQ_CTX_set1_req\fR\|(3). +The \fIio\fR and \fIpath\fR arguments to \fBOCSP_sendreq_new()\fR correspond to the +components of the URL. +For example if the responder URL is \f(CW\*(C`http://example.com/ocspreq\*(C'\fR the BIO +\&\fIio\fR should haven been connected to host \f(CW\*(C`example.com\*(C'\fR on port 80 and \fIpath\fR +should be set to \f(CW\*(C`/ocspreq\*(C'\fR. +.PP +\&\fBOCSP_sendreq_nbio()\fR attempts to send the request prepared in \fIrctx\fR +and to gather the response via HTTP, using the BIO \fIio\fR and \fIpath\fR +that were given when calling \fBOCSP_sendreq_new()\fR. +If the operation gets completed it assigns the response, +a pointer to a \fBOCSP_RESPONSE\fR structure, in \fI*presp\fR. +The function may need to be called again if its result is \-1, which indicates +\&\fBBIO_should_retry\fR\|(3). In such a case it is advisable to sleep a little in +between, using \fBBIO_wait\fR\|(3) on the read BIO to prevent a busy loop. +.PP +\&\fBOCSP_sendreq_bio()\fR combines \fBOCSP_sendreq_new()\fR with as many calls of +\&\fBOCSP_sendreq_nbio()\fR as needed and then \fBOCSP_REQ_CTX_free()\fR, with a +response header maximum line length 4k. It waits indefinitely on a response. +It does not support setting a timeout or adding headers and is retained +for compatibility; use \fBOSSL_HTTP_transfer\fR\|(3) instead. +.PP +OCSP_REQ_CTX_i2d(rctx, it, req) is equivalent to the following: +.PP +.Vb 1 +\& OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp\-request", it, req) +.Ve +.PP +OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following: +.PP +.Vb 3 +\& OSSL_HTTP_REQ_CTX_set1_req(rctx, "application/ocsp\-request", +\& ASN1_ITEM_rptr(OCSP_REQUEST), +\& (const ASN1_VALUE *)req) +.Ve +.PP +The deprecated type and the remaining deprecated functions +have been superseded by the following equivalents: +\&\fBOCSP_REQ_CTX\fR by \fBOSSL_HTTP_REQ_CTX\fR\|(3), +\&\fBOCSP_REQ_CTX_add1_header()\fR by \fBOSSL_HTTP_REQ_CTX_add1_header\fR\|(3), +\&\fBOCSP_REQ_CTX_free()\fR by \fBOSSL_HTTP_REQ_CTX_free\fR\|(3), and +\&\fBOCSP_set_max_response_length()\fR by +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_length\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOCSP_sendreq_new()\fR returns a valid \fBOSSL_HTTP_REQ_CTX\fR structure or NULL +if an error occurred. +.PP +\&\fBOCSP_sendreq_nbio()\fR returns 1 for success, 0 on error, \-1 if retry is needed. +.PP +\&\fBOCSP_sendreq_bio()\fR returns the \fBOCSP_RESPONSE\fR structure sent by the +responder or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_HTTP_REQ_CTX\fR\|(3), \fBOSSL_HTTP_transfer\fR\|(3), +\&\fBOCSP_cert_to_id\fR\|(3), +\&\fBOCSP_request_add1_nonce\fR\|(3), +\&\fBOCSP_REQUEST_new\fR\|(3), +\&\fBOCSP_resp_find_status\fR\|(3), +\&\fBOCSP_response_status\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOCSP_REQ_CTX\fR, +\&\fBOCSP_REQ_CTX_i2d()\fR, +\&\fBOCSP_REQ_CTX_add1_header()\fR, +\&\fBOCSP_REQ_CTX_free()\fR, +\&\fBOCSP_set_max_response_length()\fR, +and \fBOCSP_REQ_CTX_set1_req()\fR +were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_Applink.3 b/static/netbsd/man3/OPENSSL_Applink.3 new file mode 100644 index 00000000..d6a64b73 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_Applink.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: OPENSSL_Applink.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_Applink 3" +.TH OPENSSL_Applink 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_Applink \- glue between OpenSSL BIO and Win32 compiler run\-time +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& _\|_declspec(dllexport) void **OPENSSL_Applink(); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OPENSSL_Applink is application\-side interface which provides a glue +between OpenSSL BIO layer and Win32 compiler run\-time environment. +Even though it appears at application side, it\*(Aqs essentially OpenSSL +private interface. For this reason application developers are not +expected to implement it, but to compile provided module with +compiler of their choice and link it into the target application. +The referred module is available as \fIapplink.c\fR, located alongside +the public header files (only on the platforms where applicable). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_FILE.3 b/static/netbsd/man3/OPENSSL_FILE.3 new file mode 100644 index 00000000..17f6509c --- /dev/null +++ b/static/netbsd/man3/OPENSSL_FILE.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: OPENSSL_FILE.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_FILE 3" +.TH OPENSSL_FILE 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_FILE, OPENSSL_LINE, OPENSSL_FUNC, +OPENSSL_MSTR, OPENSSL_MSTR_HELPER +\&\- generic C programming utility macros +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define OPENSSL_FILE /* typically: _\|_FILE_\|_ */ +\& #define OPENSSL_LINE /* typically: _\|_LINE_\|_ */ +\& #define OPENSSL_FUNC /* typically: _\|_func_\|_ */ +\& +\& #define OPENSSL_MSTR_HELPER(x) #x +\& #define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The macros \fBOPENSSL_FILE\fR and \fBOPENSSL_LINE\fR +typically yield the current filename and line number during C compilation. +When \fBOPENSSL_NO_FILENAMES\fR is defined they yield \fB""\fR and \fB0\fR, respectively. +.PP +The macro \fBOPENSSL_FUNC\fR attempts to yield the name of the C function +currently being compiled, as far as language and compiler versions allow. +Otherwise, it yields "(unknown function)". +.PP +The macro \fBOPENSSL_MSTR\fR yields the expansion of the macro given as argument, +which is useful for concatenation with string constants. +The macro \fBOPENSSL_MSTR_HELPER\fR is an auxiliary macro for this purpose. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +see above +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOPENSSL_FUNC\fR, \fBOPENSSL_MSTR\fR, and \fBOPENSSL_MSTR_HELPER\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_LH_COMPFUNC.3 b/static/netbsd/man3/OPENSSL_LH_COMPFUNC.3 new file mode 100644 index 00000000..83ba8082 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_LH_COMPFUNC.3 @@ -0,0 +1,405 @@ +.\" $NetBSD: OPENSSL_LH_COMPFUNC.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_LH_COMPFUNC 3" +.TH OPENSSL_LH_COMPFUNC 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +LHASH, LHASH_OF, DEFINE_LHASH_OF_EX, DEFINE_LHASH_OF, +OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, +LHASH_DOALL_ARG_FN_TYPE, +IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, +lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush, +lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, +lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_num_items, lh_TYPE_get_down_load, +lh_TYPE_set_down_load, lh_TYPE_error, +OPENSSL_LH_new, OPENSSL_LH_free, OPENSSL_LH_flush, +OPENSSL_LH_insert, OPENSSL_LH_delete, OPENSSL_LH_retrieve, +OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_doall_arg_thunk, +OPENSSL_LH_set_thunks, OPENSSL_LH_num_items, +OPENSSL_LH_get_down_load, OPENSSL_LH_set_down_load, OPENSSL_LH_error +\&\- dynamic hash table +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& LHASH_OF(TYPE) +\& +\& DEFINE_LHASH_OF_EX(TYPE); +\& +\& LHASH_OF(TYPE) *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare); +\& void lh_TYPE_free(LHASH_OF(TYPE) *table); +\& void lh_TYPE_flush(LHASH_OF(TYPE) *table); +\& OPENSSL_LHASH *OPENSSL_LH_set_thunks(OPENSSL_LHASH *lh, +\& OPENSSL_LH_HASHFUNCTHUNK hw, +\& OPENSSL_LH_COMPFUNCTHUNK cw, +\& OPENSSL_LH_DOALL_FUNC_THUNK daw, +\& OPENSSL_LH_DOALL_FUNCARG_THUNK daaw) +\& +\& TYPE *lh_TYPE_insert(LHASH_OF(TYPE) *table, TYPE *data); +\& TYPE *lh_TYPE_delete(LHASH_OF(TYPE) *table, TYPE *data); +\& TYPE *lh_TYPE_retrieve(LHASH_OF(TYPE) *table, TYPE *data); +\& +\& void lh_TYPE_doall(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNC func); +\& void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func, +\& TYPE *arg); +\& void OPENSSL_LH_doall_arg_thunk(OPENSSL_LHASH *lh, +\& OPENSSL_LH_DOALL_FUNCARG_THUNK daaw, +\& OPENSSL_LH_DOALL_FUNCARG fn, void *arg) +\& +\& unsigned long lh_TYPE_num_items(OPENSSL_LHASH *lh); +\& unsigned long lh_TYPE_get_down_load(OPENSSL_LHASH *lh); +\& void lh_TYPE_set_down_load(OPENSSL_LHASH *lh, unsigned long dl); +\& +\& int lh_TYPE_error(LHASH_OF(TYPE) *table); +\& +\& typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *); +\& typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *); +\& typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *); +\& typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); +\& +\& OPENSSL_LHASH *OPENSSL_LH_new(OPENSSL_LH_HASHFUNC h, OPENSSL_LH_COMPFUNC c); +\& void OPENSSL_LH_free(OPENSSL_LHASH *lh); +\& void OPENSSL_LH_flush(OPENSSL_LHASH *lh); +\& +\& void *OPENSSL_LH_insert(OPENSSL_LHASH *lh, void *data); +\& void *OPENSSL_LH_delete(OPENSSL_LHASH *lh, const void *data); +\& void *OPENSSL_LH_retrieve(OPENSSL_LHASH *lh, const void *data); +\& +\& void OPENSSL_LH_doall(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNC func); +\& void OPENSSL_LH_doall_arg(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNCARG func, void *arg); +\& +\& unsigned long OPENSSL_LH_num_items(OPENSSL_LHASH *lh); +\& unsigned long OPENSSL_LH_get_down_load(OPENSSL_LHASH *lh); +\& void OPENSSL_LH_set_down_load(OPENSSL_LHASH *lh, unsigned long dl); +\& +\& int OPENSSL_LH_error(OPENSSL_LHASH *lh); +\& +\& #define LH_LOAD_MULT /* integer constant */ +.Ve +.PP +The following macro is deprecated: +.PP +.Vb 1 +\& DEFINE_LHASH_OF(TYPE); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This library implements type\-checked dynamic hash tables. The hash +table entries can be arbitrary structures. Usually they consist of key +and value fields. In the description here, \fR\f(BITYPE\fR\fB\fR is used a placeholder +for any of the OpenSSL datatypes, such as \fISSL_SESSION\fR. +.PP +To define a new type\-checked dynamic hash table, use \fBDEFINE_LHASH_OF_EX\fR(). +\&\fBDEFINE_LHASH_OF\fR() was previously used for this purpose, but is now +deprecated. The \fBDEFINE_LHASH_OF_EX\fR() macro provides all functionality of +\&\fBDEFINE_LHASH_OF\fR() except for certain deprecated statistics functions (see +\&\fBOPENSSL_LH_stats\fR\|(3)). +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_new\fR() creates a new \fBLHASH_OF\fR(\fR\f(BITYPE\fR\fB\fR) structure to store +arbitrary data entries, and specifies the \*(Aqhash\*(Aq and \*(Aqcompare\*(Aq +callbacks to be used in organising the table\*(Aqs entries. The \fIhash\fR +callback takes a pointer to a table entry as its argument and returns +an unsigned long hash value for its key field. The hash value is +normally truncated to a power of 2, so make sure that your hash +function returns well mixed low order bits. The \fIcompare\fR callback +takes two arguments (pointers to two hash table entries), and returns +0 if their keys are equal, nonzero otherwise. +.PP +If your hash table +will contain items of some particular type and the \fIhash\fR and +\&\fIcompare\fR callbacks hash/compare these types, then the +\&\fBIMPLEMENT_LHASH_HASH_FN\fR and \fBIMPLEMENT_LHASH_COMP_FN\fR macros can be +used to create callback wrappers of the prototypes required by +\&\fBlh_\fR\f(BITYPE\fR\fB_new\fR() as shown in this example: +.PP +.Vb 11 +\& /* +\& * Implement the hash and compare functions; "stuff" can be any word. +\& */ +\& static unsigned long stuff_hash(const TYPE *a) +\& { +\& ... +\& } +\& static int stuff_cmp(const TYPE *a, const TYPE *b) +\& { +\& ... +\& } +\& +\& /* +\& * Implement the wrapper functions. +\& */ +\& static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE) +\& static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE) +.Ve +.PP +If the type is going to be used in several places, the following macros +can be used in a common header file to declare the function wrappers: +.PP +.Vb 2 +\& DECLARE_LHASH_HASH_FN(stuff, TYPE) +\& DECLARE_LHASH_COMP_FN(stuff, TYPE) +.Ve +.PP +Then a hash table of \fR\f(BITYPE\fR\fB\fR objects can be created using this: +.PP +.Vb 1 +\& LHASH_OF(TYPE) *htable; +\& +\& htable = B_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff)); +.Ve +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_free\fR() frees the \fBLHASH_OF\fR(\fR\f(BITYPE\fR\fB\fR) structure +\&\fItable\fR. Allocated hash table entries will not be freed; consider +using \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() to deallocate any remaining entries in the +hash table (see below). If the argument is NULL, nothing is done. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_flush\fR() empties the \fBLHASH_OF\fR(\fR\f(BITYPE\fR\fB\fR) structure \fItable\fR. New +entries can be added to the flushed table. Allocated hash table entries +will not be freed; consider using \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() to deallocate any +remaining entries in the hash table (see below). +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_insert\fR() inserts the structure pointed to by \fIdata\fR into +\&\fItable\fR. If there already is an entry with the same key, the old +value is replaced. Note that \fBlh_\fR\f(BITYPE\fR\fB_insert\fR() stores pointers, the +data are not copied. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_delete\fR() deletes an entry from \fItable\fR. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_retrieve\fR() looks up an entry in \fItable\fR. Normally, \fIdata\fR +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_doall\fR() will, for every entry in the hash table, call +\&\fIfunc\fR with the data item as its parameter. +For example: +.PP +.Vb 2 +\& /* Cleans up resources belonging to \*(Aqa\*(Aq (this is implemented elsewhere) */ +\& void TYPE_cleanup_doall(TYPE *a); +\& +\& /* Implement a prototype\-compatible wrapper for "TYPE_cleanup" */ +\& IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE) +\& +\& /* Call "TYPE_cleanup" against all items in a hash table. */ +\& lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup)); +\& +\& /* Then the hash table itself can be deallocated */ +\& lh_TYPE_free(hashtable); +.Ve +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR() is the same as \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() except that +\&\fIfunc\fR will be called with \fIarg\fR as the second argument and \fIfunc\fR +should be of type \fBLHASH_DOALL_ARG_FN\fR(\fR\f(BITYPE\fR\fB\fR) (a callback prototype +that is passed both the table entry and an extra argument). As with +\&\fBlh_doall()\fR, you can instead choose to declare your callback with a +prototype matching the types you are dealing with and use the +declare/implement macros to create compatible wrappers that cast +variables before calling your type\-specific callbacks. An example of +this is demonstrated here (printing all hash table entries to a BIO +that is provided by the caller): +.PP +.Vb 2 +\& /* Prints item \*(Aqa\*(Aq to \*(Aqoutput_bio\*(Aq (this is implemented elsewhere) */ +\& void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio); +\& +\& /* Implement a prototype\-compatible wrapper for "TYPE_print" */ +\& static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO) +\& +\& /* Print out the entire hashtable to a particular BIO */ +\& lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO, +\& logging_bio); +.Ve +.PP +Note that it is by default \fBnot\fR safe to use \fBlh_\fR\f(BITYPE\fR\fB_delete\fR() inside a +callback passed to \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() or \fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR(). The +reason for this is that deleting an item from the hash table may result in the +hash table being contracted to a smaller size and rehashed. +\&\fBlh_\fR\f(BITYPE\fR\fB_doall\fR() and \fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR() are unsafe and will exhibit +undefined behaviour under these conditions, as these functions assume the hash +table size and bucket pointers do not change during the call. +.PP +If it is desired to use \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() or \fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR() with +\&\fBlh_\fR\f(BITYPE\fR\fB_delete\fR(), it is essential that you call +\&\fBlh_\fR\f(BITYPE\fR\fB_set_down_load\fR() with a \fIdown_load\fR argument of 0 first. This +disables hash table contraction and guarantees that it will be safe to delete +items from a hash table during a call to \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() or +\&\fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR(). +.PP +It is never safe to call \fBlh_\fR\f(BITYPE\fR\fB_insert\fR() during a call to +\&\fBlh_\fR\f(BITYPE\fR\fB_doall\fR() or \fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR(). +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_error\fR() can be used to determine if an error occurred in the last +operation. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_num_items\fR() returns the number of items in the hash table. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_get_down_load\fR() and \fBlh_\fR\f(BITYPE\fR\fB_set_down_load\fR() get and set the +factor used to determine when the hash table is contracted. The factor is the +load factor at or below which hash table contraction will occur, multiplied by +\&\fBLH_LOAD_MULT\fR, where the load factor is the number of items divided by the +number of nodes. Setting this value to 0 disables hash table contraction. +.PP +\&\fBOPENSSL_LH_new()\fR is the same as the \fBlh_\fR\f(BITYPE\fR\fB_new\fR() except that it is not +type specific. So instead of returning an \fBLHASH_OF(\fR\f(BITYPE\fR\fB)\fR value it returns +a \fBvoid *\fR. In the same way the functions \fBOPENSSL_LH_free()\fR, +\&\fBOPENSSL_LH_flush()\fR, \fBOPENSSL_LH_insert()\fR, \fBOPENSSL_LH_delete()\fR, +\&\fBOPENSSL_LH_retrieve()\fR, \fBOPENSSL_LH_doall()\fR, \fBOPENSSL_LH_doall_arg()\fR, +\&\fBOPENSSL_LH_num_items()\fR, \fBOPENSSL_LH_get_down_load()\fR, \fBOPENSSL_LH_set_down_load()\fR +and \fBOPENSSL_LH_error()\fR are equivalent to the similarly named \fBlh_\fR\f(BITYPE\fR +functions except that they return or use a \fBvoid *\fR where the equivalent +\&\fBlh_\fR\f(BITYPE\fR\fB\fR function returns or uses a \fB\fR\f(BITYPE\fR\fB *\fR or \fBLHASH_OF(\fR\f(BITYPE\fR\fB) *\fR. +\&\fBlh_\fR\f(BITYPE\fR\fB\fR functions are implemented as type checked wrappers around the +\&\fBOPENSSL_LH\fR functions. Most applications should not call the \fBOPENSSL_LH\fR +functions directly. +.PP +\&\fBOPENSSL_LH_set_thunks()\fR and \fBOPENSSL_LH_doall_arg_thunk()\fR, while public by +necessity, are actually internal functions and should not be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBlh_\fR\f(BITYPE\fR\fB_new\fR() and \fBOPENSSL_LH_new()\fR return NULL on error, otherwise a +pointer to the new \fBLHASH\fR structure. +.PP +When a hash table entry is replaced, \fBlh_\fR\f(BITYPE\fR\fB_insert\fR() or +\&\fBOPENSSL_LH_insert()\fR return the value being replaced. NULL is returned on normal +operation and on error. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_delete\fR() and \fBOPENSSL_LH_delete()\fR return the entry being deleted. +NULL is returned if there is no such value in the hash table. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_retrieve\fR() and \fBOPENSSL_LH_retrieve()\fR return the hash table entry +if it has been found, NULL otherwise. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_error\fR() and \fBOPENSSL_LH_error()\fR return 1 if an error occurred in +the last operation, 0 otherwise. It\*(Aqs meaningful only after non\-retrieve +operations. +.PP +\&\fBlh_\fR\f(BITYPE\fR\fB_free\fR(), \fBOPENSSL_LH_free()\fR, \fBlh_\fR\f(BITYPE\fR\fB_flush\fR(), +\&\fBOPENSSL_LH_flush()\fR, \fBlh_\fR\f(BITYPE\fR\fB_doall\fR() \fBOPENSSL_LH_doall()\fR, +\&\fBlh_\fR\f(BITYPE\fR\fB_doall_arg\fR() and \fBOPENSSL_LH_doall_arg()\fR return no values. +.SH NOTE +.IX Header "NOTE" +The LHASH code is not thread safe. All updating operations, as well as +\&\fBlh_\fR\f(BITYPE\fR\fB_error\fR() or \fBOPENSSL_LH_error()\fR calls must be performed under +a write lock. All retrieve operations should be performed under a read lock, +\&\fIunless\fR accurate usage statistics are desired. In which case, a write lock +should be used for retrieve operations as well. For output of the usage +statistics, using the functions from \fBOPENSSL_LH_stats\fR\|(3), a read lock +suffices. +.PP +The LHASH code regards table entries as constant data. As such, it +internally represents \fBlh_insert()\fR\*(Aqd items with a "const void *" +pointer type. This is why callbacks such as those used by \fBlh_doall()\fR +and \fBlh_doall_arg()\fR declare their prototypes with "const", even for the +parameters that pass back the table items\*(Aq data pointers \- for +consistency, user\-provided data is "const" at all times as far as the +LHASH code is concerned. However, as callers are themselves providing +these pointers, they can choose whether they too should be treating +all such parameters as constant. +.PP +As an example, a hash table may be maintained by code that, for +reasons of encapsulation, has only "const" access to the data being +indexed in the hash table (i.e. it is returned as "const" from +elsewhere in their code) \- in this case the LHASH prototypes are +appropriate as\-is. Conversely, if the caller is responsible for the +life\-time of the data in question, then they may well wish to make +modifications to table item passed back in the \fBlh_doall()\fR or +\&\fBlh_doall_arg()\fR callbacks (see the "TYPE_cleanup" example above). If +so, the caller can either cast the "const" away (if they\*(Aqre providing +the raw callbacks themselves) or use the macros to declare/implement +the wrapper functions without "const" types. +.PP +Callers that only have "const" access to data they\*(Aqre indexing in a +table, yet declare callbacks without constant types (or cast the +"const" away themselves), are therefore creating their own risks/bugs +without being encouraged to do so by the API. On a related note, +those auditing code should pay special attention to any instances of +DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types +without any "const" qualifiers. +.SH BUGS +.IX Header "BUGS" +\&\fBlh_\fR\f(BITYPE\fR\fB_insert\fR() and \fBOPENSSL_LH_insert()\fR return NULL both for success +and error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_LH_stats\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +In OpenSSL 1.0.0, the lhash interface was revamped for better +type checking. +.PP +In OpenSSL 3.1, \fBDEFINE_LHASH_OF_EX\fR() was introduced and \fBDEFINE_LHASH_OF\fR() +was deprecated. +.PP +\&\fBOPENSSL_LH_doall_arg_thunk()\fR, \fBOPENSSL_LH_set_thunks()\fR were added in +OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_LH_stats.3 b/static/netbsd/man3/OPENSSL_LH_stats.3 new file mode 100644 index 00000000..f250f06b --- /dev/null +++ b/static/netbsd/man3/OPENSSL_LH_stats.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: OPENSSL_LH_stats.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_LH_stats 3" +.TH OPENSSL_LH_stats 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats, +OPENSSL_LH_stats_bio, +OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio \- LHASH statistics +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.1, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& void OPENSSL_LH_node_stats(LHASH *table, FILE *out); +\& void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out); +\& +\& void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out); +\& void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out); +\& +\& void OPENSSL_LH_stats(LHASH *table, FILE *out); +\& void OPENSSL_LH_stats_bio(LHASH *table, BIO *out); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBLHASH\fR structure records statistics about most aspects of +accessing the hash table. +.PP +\&\fBOPENSSL_LH_stats()\fR prints out statistics on the size of the hash table and how +many entries are in it. For historical reasons, this function also outputs a +number of additional statistics, but the tracking of these statistics is no +longer supported and these statistics are always reported as zero. +.PP +\&\fBOPENSSL_LH_node_stats()\fR prints the number of entries for each \*(Aqbucket\*(Aq in the +hash table. +.PP +\&\fBOPENSSL_LH_node_usage_stats()\fR prints out a short summary of the state of the +hash table. It prints the \*(Aqload\*(Aq and the \*(Aqactual load\*(Aq. The load is +the average number of data items per \*(Aqbucket\*(Aq in the hash table. The +\&\*(Aqactual load\*(Aq is the average number of items per \*(Aqbucket\*(Aq, but only +for buckets which contain entries. So the \*(Aqactual load\*(Aq is the +average number of searches that will need to find an item in the hash +table, while the \*(Aqload\*(Aq is the average number that will be done to +record a miss. +.PP +\&\fBOPENSSL_LH_stats_bio()\fR, \fBOPENSSL_LH_node_stats_bio()\fR and \fBOPENSSL_LH_node_usage_stats_bio()\fR +are the same as the above, except that the output goes to a \fBBIO\fR. +.PP +These functions are deprecated and should no longer be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions do not return values. +.SH NOTE +.IX Header "NOTE" +These calls should be made under a read lock. Refer to +"NOTE" in \fBOPENSSL_LH_COMPFUNC\fR\|(3) for more details about the locks required +when using the LHASH data structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), \fBOPENSSL_LH_COMPFUNC\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were deprecated in version 3.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_VERSION_NUMBER.3 b/static/netbsd/man3/OPENSSL_VERSION_NUMBER.3 new file mode 100644 index 00000000..fde6a858 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_VERSION_NUMBER.3 @@ -0,0 +1,247 @@ +.\" $NetBSD: OPENSSL_VERSION_NUMBER.3,v 1.20 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "OPENSSL_VERSION_NUMBER 3" +.TH OPENSSL_VERSION_NUMBER 3 "2018-12-08" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_TEXT, OpenSSL_version, +OpenSSL_version_num \- get OpenSSL version number +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 3 +\& #include +\& #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL +\& #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx" +\& +\& #include +\& +\& unsigned long OpenSSL_version_num(); +\& const char *OpenSSL_version(int t); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1OPENSSL_VERSION_NUMBER\s0 is a numeric release version identifier: +.PP +.Vb 1 +\& MNNFFPPS: major minor fix patch status +.Ve +.PP +The status nibble has one of the values 0 for development, 1 to e for betas +1 to 14, and f for release. +.PP +for example +.PP +.Vb 3 +\& 0x000906000 == 0.9.6 dev +\& 0x000906023 == 0.9.6b beta 3 +\& 0x00090605f == 0.9.6e release +.Ve +.PP +Versions prior to 0.9.3 have identifiers < 0x0930. +Versions between 0.9.3 and 0.9.5 had a version identifier with this +interpretation: +.PP +.Vb 1 +\& MMNNFFRBB major minor fix final beta/patch +.Ve +.PP +for example +.PP +.Vb 2 +\& 0x000904100 == 0.9.4 release +\& 0x000905000 == 0.9.5 dev +.Ve +.PP +Version 0.9.5a had an interim interpretation that is like the current one, +except the patch level got the highest bit set, to keep continuity. The +number was therefore 0x0090581f. +.PP +\&\s-1OPENSSL_VERSION_TEXT\s0 is the text variant of the version number and the +release date. For example, +\&\*(L"OpenSSL 1.0.1a 15 Oct 2015\*(R". +.PP +\&\fBOpenSSL_version_num()\fR returns the version number. +.PP +\&\fBOpenSSL_version()\fR returns different strings depending on \fBt\fR: +.IP "\s-1OPENSSL_VERSION\s0" 4 +.IX Item "OPENSSL_VERSION" +The text variant of the version number and the release date. For example, +\&\*(L"OpenSSL 1.0.1a 15 Oct 2015\*(R". +.IP "\s-1OPENSSL_CFLAGS\s0" 4 +.IX Item "OPENSSL_CFLAGS" +The compiler flags set for the compilation process in the form +\&\*(L"compiler: ...\*(R" if available or \*(L"compiler: information not available\*(R" +otherwise. +.IP "\s-1OPENSSL_BUILT_ON\s0" 4 +.IX Item "OPENSSL_BUILT_ON" +The date of the build process in the form \*(L"built on: ...\*(R" if available +or \*(L"built on: date not available\*(R" otherwise. +.IP "\s-1OPENSSL_PLATFORM\s0" 4 +.IX Item "OPENSSL_PLATFORM" +The \*(L"Configure\*(R" target of the library build in the form \*(L"platform: ...\*(R" +if available or \*(L"platform: information not available\*(R" otherwise. +.IP "\s-1OPENSSL_DIR\s0" 4 +.IX Item "OPENSSL_DIR" +The \*(L"\s-1OPENSSLDIR\*(R"\s0 setting of the library build in the form \*(L"\s-1OPENSSLDIR: \*(R"..."\*(L"\s0 +if available or \*(R"\s-1OPENSSLDIR: N/A"\s0 otherwise. +.IP "\s-1OPENSSL_ENGINES_DIR\s0" 4 +.IX Item "OPENSSL_ENGINES_DIR" +The \*(L"\s-1ENGINESDIR\*(R"\s0 setting of the library build in the form \*(L"\s-1ENGINESDIR: \*(R"..."\*(L"\s0 +if available or \*(R"\s-1ENGINESDIR: N/A"\s0 otherwise. +.PP +For an unknown \fBt\fR, the text \*(L"not available\*(R" is returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOpenSSL_version_num()\fR returns the version number. +.PP +\&\fBOpenSSL_version()\fR returns requested version strings. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_config.3 b/static/netbsd/man3/OPENSSL_config.3 new file mode 100644 index 00000000..dfc37696 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_config.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: OPENSSL_config.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_config 3" +.TH OPENSSL_config 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_config, OPENSSL_no_config \- simple OpenSSL configuration functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& void OPENSSL_config(const char *appname); +\& void OPENSSL_no_config(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOPENSSL_config()\fR configures OpenSSL using the standard \fBopenssl.cnf\fR and +reads from the application section \fBappname\fR. If \fBappname\fR is NULL then +the default section, \fBopenssl_conf\fR, will be used. +Errors are silently ignored. +Multiple calls have no effect. +.PP +\&\fBOPENSSL_no_config()\fR disables configuration. If called before \fBOPENSSL_config()\fR +no configuration takes place. +.PP +If the application is built with \fBOPENSSL_LOAD_CONF\fR defined, then a +call to \fBOpenSSL_add_all_algorithms()\fR will implicitly call \fBOPENSSL_config()\fR +first. +.SH NOTES +.IX Header "NOTES" +The \fBOPENSSL_config()\fR function is designed to be a very simple "call it and +forget it" function. +It is however \fBmuch\fR better than nothing. Applications which need finer +control over their configuration functionality should use the configuration +functions such as \fBCONF_modules_load()\fR directly. This function is deprecated +and its use should be avoided. +Applications should instead call \fBCONF_modules_load()\fR during +initialization (that is before starting any threads). +.PP +There are several reasons why calling the OpenSSL configuration routines is +advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs). +However, very few applications currently support the control interface and so +very few can load and use dynamic ENGINEs. Equally in future more sophisticated +ENGINEs will require certain control operations to customize them. If an +application calls \fBOPENSSL_config()\fR it doesn\*(Aqt need to know or care about +ENGINE control operations because they can be performed by editing a +configuration file. +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +.IP \fBOPENSSL_CONF\fR 4 +.IX Item "OPENSSL_CONF" +The path to the config file. +Ignored in set\-user\-ID and set\-group\-ID programs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Neither \fBOPENSSL_config()\fR nor \fBOPENSSL_no_config()\fR return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBconfig\fR\|(5), +\&\fBCONF_modules_load_file\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOPENSSL_no_config()\fR and \fBOPENSSL_config()\fR functions were +deprecated in OpenSSL 1.1.0 by \fBOPENSSL_init_crypto()\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_fork_prepare.3 b/static/netbsd/man3/OPENSSL_fork_prepare.3 new file mode 100644 index 00000000..64bf19d8 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_fork_prepare.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: OPENSSL_fork_prepare.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_fork_prepare 3" +.TH OPENSSL_fork_prepare 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_fork_prepare, +OPENSSL_fork_parent, +OPENSSL_fork_child +\&\- OpenSSL fork handlers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& void OPENSSL_fork_prepare(void); +\& void OPENSSL_fork_parent(void); +\& void OPENSSL_fork_child(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These methods are currently unused, and as such, no replacement methods are +required or planned. +.PP +OpenSSL has state that should be reset when a process forks. For example, +the entropy pool used to generate random numbers (and therefore encryption +keys) should not be shared across multiple programs. +The \fBOPENSSL_fork_prepare()\fR, \fBOPENSSL_fork_parent()\fR, and \fBOPENSSL_fork_child()\fR +functions are used to reset this internal state. +.PP +Platforms without \fBfork\fR\|(2) will probably not need to use these functions. +Platforms with \fBfork\fR\|(2) but without \fBpthread_atfork\fR\|(3) will probably need +to call them manually, as described in the following paragraph. Platforms +such as Linux that have both functions will normally not need to call these +functions as the OpenSSL library will do so automatically. +.PP +\&\fBOPENSSL_init_crypto\fR\|(3) will register these functions with the appropriate +handler, when the \fBOPENSSL_INIT_ATFORK\fR flag is used. For other +applications, these functions can be called directly. They should be used +according to the calling sequence described by the \fBpthread_atfork\fR\|(3) +documentation, which is summarized here. \fBOPENSSL_fork_prepare()\fR should +be called before a \fBfork()\fR is done. After the \fBfork()\fR returns, the parent +process should call \fBOPENSSL_fork_parent()\fR and the child process should +call \fBOPENSSL_fork_child()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOPENSSL_fork_prepare()\fR, \fBOPENSSL_fork_parent()\fR and \fBOPENSSL_fork_child()\fR do not +return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_init_crypto\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_gmtime.3 b/static/netbsd/man3/OPENSSL_gmtime.3 new file mode 100644 index 00000000..0ead38a5 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_gmtime.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: OPENSSL_gmtime.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_gmtime 3" +.TH OPENSSL_gmtime 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_gmtime, +OPENSSL_gmtime_adj, +OPENSSL_gmtime_diff \- platform\-agnostic OpenSSL time routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& struct tm *OPENSSL_gmtime(const time_t *timer, struct tm *result); +\& int OPENSSL_gmtime_adj(struct tm *tm, int offset_day, long offset_sec); +\& int OPENSSL_gmtime_diff(int *pday, int *psec, +\& const struct tm *from, const struct tm *to); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOPENSSL_gmtime()\fR returns the UTC time specified by \fItimer\fR into the provided +\&\fIresult\fR argument. +.PP +\&\fBOPENSSL_gmtime_adj()\fR adds the offsets in \fIoffset_day\fR and \fIoffset_sec\fR to \fItm\fR. +.PP +\&\fBOPENSSL_gmtime_diff()\fR calculates the difference between \fIfrom\fR and \fIto\fR. +.SH NOTES +.IX Header "NOTES" +It is an error to call \fBOPENSSL_gmtime()\fR with \fIresult\fR equal to NULL. The +contents of the time_t given by \fItimer\fR are stored into the \fIresult\fR. Calling +with \fItimer\fR equal to NULL means use the current time. +.PP +\&\fBOPENSSL_gmtime_adj()\fR converts \fItm\fR into a days and seconds value, adds the +offsets, then converts back into a \fIstruct tm\fR specified by \fItm\fR. Leap seconds +are not considered. +.PP +\&\fBOPENSSL_gmtime_diff()\fR calculates the difference between the two \fIstruct tm\fR +structures \fIfrom\fR and \fIto\fR. The difference in days is placed into \fI*pday\fR, +the remaining seconds are placed to \fI*psec\fR. The value in \fI*psec\fR will be less +than the number of seconds per day (3600). Leap seconds are not considered. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOPENSSL_gmtime()\fR returns NULL on error, or \fIresult\fR on success. +.PP +\&\fBOPENSSL_gmtime_adj()\fR and \fBOPENSSL_gmtime_diff()\fR return 0 on error, and 1 on success. +.SH HISTORY +.IX Header "HISTORY" +\&\fBOPENSSL_gmtime()\fR, \fBOPENSSL_gmtime_adj()\fR and \fBOPENSSL_gmtime_diff()\fR have been +in OpenSSL since 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_hexchar2int.3 b/static/netbsd/man3/OPENSSL_hexchar2int.3 new file mode 100644 index 00000000..cd3562a9 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_hexchar2int.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: OPENSSL_hexchar2int.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_hexchar2int 3" +.TH OPENSSL_hexchar2int 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_hexchar2int, +OPENSSL_hexstr2buf_ex, OPENSSL_hexstr2buf, +OPENSSL_buf2hexstr_ex, OPENSSL_buf2hexstr +\&\- Hex encoding and decoding functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OPENSSL_hexchar2int(unsigned char c); +\& int OPENSSL_hexstr2buf_ex(unsigned char *buf, size_t buf_n, long *buflen, +\& const char *str, const char sep); +\& unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); +\& int OPENSSL_buf2hexstr_ex(char *str, size_t str_n, size_t *strlength, +\& const unsigned char *buf, long buflen, +\& const char sep); +\& char *OPENSSL_buf2hexstr(const unsigned char *buf, long buflen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOPENSSL_hexchar2int()\fR converts a hexadecimal character to its numeric +equivalent. +.PP +\&\fBOPENSSL_hexstr2buf_ex()\fR decodes the hex string \fBstr\fR and places the +resulting string of bytes in the given \fIbuf\fR. +The character \fIsep\fR is the separator between the bytes, setting this to \*(Aq\e0\*(Aq +means that there is no separator. +\&\fIbuf_n\fR gives the size of the buffer. +If \fIbuflen\fR is not NULL, it is filled in with the result length. +To find out how large the result will be, call this function with NULL +for \fIbuf\fR. +Colons between two\-character hex "bytes" are accepted and ignored. +An odd number of hex digits is an error. +.PP +\&\fBOPENSSL_hexstr2buf()\fR does the same thing as \fBOPENSSL_hexstr2buf_ex()\fR, +but allocates the space for the result, and returns the result. It uses a +default separator of \*(Aq:\*(Aq. +The memory is allocated by calling \fBOPENSSL_malloc()\fR and should be +released by calling \fBOPENSSL_free()\fR. +.PP +\&\fBOPENSSL_buf2hexstr_ex()\fR encodes the contents of the given \fIbuf\fR with +length \fIbuflen\fR and places the resulting hexadecimal character string +in the given \fIstr\fR. +The character \fIsep\fR is the separator between the bytes, setting this to \*(Aq\e0\*(Aq +means that there is no separator. +\&\fIstr_n\fR gives the size of the of the string buffer. +If \fIstrlength\fR is not NULL, it is filled in with the result length. +To find out how large the result will be, call this function with NULL +for \fIstr\fR. +.PP +\&\fBOPENSSL_buf2hexstr()\fR does the same thing as \fBOPENSSL_buf2hexstr_ex()\fR, +but allocates the space for the result, and returns the result. It uses a +default separator of \*(Aq:\*(Aq. +The memory is allocated by calling \fBOPENSSL_malloc()\fR and should be +released by calling \fBOPENSSL_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +OPENSSL_hexchar2int returns the value of a decoded hex character, +or \-1 on error. +.PP +\&\fBOPENSSL_buf2hexstr()\fR and \fBOPENSSL_hexstr2buf()\fR +return a pointer to allocated memory, or NULL on error. +.PP +\&\fBOPENSSL_buf2hexstr_ex()\fR and \fBOPENSSL_hexstr2buf_ex()\fR return 1 on +success, or 0 on error. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_ia32cap.3 b/static/netbsd/man3/OPENSSL_ia32cap.3 new file mode 100644 index 00000000..27b4186b --- /dev/null +++ b/static/netbsd/man3/OPENSSL_ia32cap.3 @@ -0,0 +1,273 @@ +.\" $NetBSD: OPENSSL_ia32cap.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_ia32cap 3" +.TH OPENSSL_ia32cap 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_ia32cap \- the x86[_64] processor capabilities vector +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& env OPENSSL_ia32cap=... +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL supports a range of x86[_64] instruction set extensions and +features. These extensions are denoted by individual bits or groups of bits +stored internally as ten 32\-bit capability vectors and for simplicity +represented logically below as five 64\-bit vectors. This logical +vector (LV) representation is used to streamline the definition of the +OPENSSL_ia32cap environment variable. +.PP +Upon toolkit initialization, the capability vectors are populated through +successive executions of the CPUID instruction, after which any OPENSSL_ia32cap +environment variable capability bit modifications are applied. After toolkit +initialization is complete, populated vectors are then used to choose +between different code paths to provide optimal performance across a wide +range of x86[_64] based processors. +.PP +Further CPUID information can be found in the Intel(R) Architecture +Instruction Set Extensions Programming Reference, and the AMD64 Architecture +Programmer\*(Aqs Manual (Volume 3). +.SS "Notable Capability Bits for LV0" +.IX Subsection "Notable Capability Bits for LV0" +The following are notable capability bits from logical vector 0 (LV0) +resulting from the following execution of CPUID.(EAX=01H).EDX and +CPUID.(EAX=01H).ECX: +.IP "bit #0+4 denoting presence of Time\-Stamp Counter;" 4 +.IX Item "bit #0+4 denoting presence of Time-Stamp Counter;" +.PD 0 +.IP "bit #0+19 denoting availability of CLFLUSH instruction;" 4 +.IX Item "bit #0+19 denoting availability of CLFLUSH instruction;" +.IP "bit #0+20, reserved by Intel, is used to choose among RC4 code paths;" 4 +.IX Item "bit #0+20, reserved by Intel, is used to choose among RC4 code paths;" +.IP "bit #0+23 denoting MMX support;" 4 +.IX Item "bit #0+23 denoting MMX support;" +.IP "bit #0+24, FXSR bit, denoting availability of XMM registers;" 4 +.IX Item "bit #0+24, FXSR bit, denoting availability of XMM registers;" +.IP "bit #0+25 denoting SSE support;" 4 +.IX Item "bit #0+25 denoting SSE support;" +.IP "bit #0+26 denoting SSE2 support;" 4 +.IX Item "bit #0+26 denoting SSE2 support;" +.IP "bit #0+28 denoting Hyperthreading, which is used to distinguish cores with shared cache;" 4 +.IX Item "bit #0+28 denoting Hyperthreading, which is used to distinguish cores with shared cache;" +.IP "bit #0+30, reserved by Intel, denotes specifically Intel CPUs;" 4 +.IX Item "bit #0+30, reserved by Intel, denotes specifically Intel CPUs;" +.IP "bit #0+33 denoting availability of PCLMULQDQ instruction;" 4 +.IX Item "bit #0+33 denoting availability of PCLMULQDQ instruction;" +.IP "bit #0+41 denoting SSSE3, Supplemental SSE3, support;" 4 +.IX Item "bit #0+41 denoting SSSE3, Supplemental SSE3, support;" +.IP "bit #0+43 denoting AMD XOP support (forced to zero on non\-AMD CPUs);" 4 +.IX Item "bit #0+43 denoting AMD XOP support (forced to zero on non-AMD CPUs);" +.IP "bit #0+54 denoting availability of MOVBE instruction;" 4 +.IX Item "bit #0+54 denoting availability of MOVBE instruction;" +.IP "bit #0+57 denoting AES\-NI instruction set extension;" 4 +.IX Item "bit #0+57 denoting AES-NI instruction set extension;" +.IP "bit #0+58, XSAVE bit, lack of which in combination with MOVBE is used to identify Atom Silvermont core;" 4 +.IX Item "bit #0+58, XSAVE bit, lack of which in combination with MOVBE is used to identify Atom Silvermont core;" +.IP "bit #0+59, OSXSAVE bit, denoting availability of YMM registers;" 4 +.IX Item "bit #0+59, OSXSAVE bit, denoting availability of YMM registers;" +.IP "bit #0+60 denoting AVX extension;" 4 +.IX Item "bit #0+60 denoting AVX extension;" +.IP "bit #0+62 denoting availability of RDRAND instruction;" 4 +.IX Item "bit #0+62 denoting availability of RDRAND instruction;" +.PD +.SS "Notable Capability Bits for LV1" +.IX Subsection "Notable Capability Bits for LV1" +The following are notable capability bits from logical vector 1 (LV1) +resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EBX and +CPUID.(EAX=07H,ECX=0H).ECX: +.IP "bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;" 4 +.IX Item "bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;" +.PD 0 +.IP "bit #64+5 denoting availability of AVX2 instructions;" 4 +.IX Item "bit #64+5 denoting availability of AVX2 instructions;" +.IP "bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX;" 4 +.IX Item "bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX;" +.IP "bit #64+16 denoting availability of AVX512F extension;" 4 +.IX Item "bit #64+16 denoting availability of AVX512F extension;" +.IP "bit #64+17 denoting availability of AVX512DQ extension;" 4 +.IX Item "bit #64+17 denoting availability of AVX512DQ extension;" +.IP "bit #64+18 denoting availability of RDSEED instruction;" 4 +.IX Item "bit #64+18 denoting availability of RDSEED instruction;" +.IP "bit #64+19 denoting availability of ADCX and ADOX instructions;" 4 +.IX Item "bit #64+19 denoting availability of ADCX and ADOX instructions;" +.IP "bit #64+21 denoting availability of AVX512IFMA extension;" 4 +.IX Item "bit #64+21 denoting availability of AVX512IFMA extension;" +.IP "bit #64+29 denoting availability of SHA extension;" 4 +.IX Item "bit #64+29 denoting availability of SHA extension;" +.IP "bit #64+30 denoting availability of AVX512BW extension;" 4 +.IX Item "bit #64+30 denoting availability of AVX512BW extension;" +.IP "bit #64+31 denoting availability of AVX512VL extension;" 4 +.IX Item "bit #64+31 denoting availability of AVX512VL extension;" +.IP "bit #64+41 denoting availability of VAES extension;" 4 +.IX Item "bit #64+41 denoting availability of VAES extension;" +.IP "bit #64+42 denoting availability of VPCLMULQDQ extension;" 4 +.IX Item "bit #64+42 denoting availability of VPCLMULQDQ extension;" +.PD +.SS "Notable Capability Bits for LV2" +.IX Subsection "Notable Capability Bits for LV2" +The following are notable capability bits from logical vector 2 (LV2) +resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EDX and +CPUID.(EAX=07H,ECX=1H).EAX: +.IP "bit #128+15 denoting availability of Hybrid CPU;" 4 +.IX Item "bit #128+15 denoting availability of Hybrid CPU;" +.PD 0 +.IP "bit #128+29 denoting support for IA32_ARCH_CAPABILITIES MSR;" 4 +.IX Item "bit #128+29 denoting support for IA32_ARCH_CAPABILITIES MSR;" +.IP "bit #128+32 denoting availability of SHA512 extension;" 4 +.IX Item "bit #128+32 denoting availability of SHA512 extension;" +.IP "bit #128+33 denoting availability of SM3 extension;" 4 +.IX Item "bit #128+33 denoting availability of SM3 extension;" +.IP "bit #128+34 denoting availability of SM4 extension;" 4 +.IX Item "bit #128+34 denoting availability of SM4 extension;" +.IP "bit #128+55 denoting availability of AVX\-IFMA extension;" 4 +.IX Item "bit #128+55 denoting availability of AVX-IFMA extension;" +.PD +.SS "Notable Capability Bits for LV3" +.IX Subsection "Notable Capability Bits for LV3" +The following are notable capability bits from logical vector 3 (LV3) +resulting from the following execution of CPUID.(EAX=07H,ECX=1H).EDX and +CPUID.(EAX=07H,ECX=1H).EBX: +.IP "bit #192+19 denoting availability of AVX10 Converged Vector ISA extension;" 4 +.IX Item "bit #192+19 denoting availability of AVX10 Converged Vector ISA extension;" +.PD 0 +.IP "bit #192+21 denoting availability of APX_F extension;" 4 +.IX Item "bit #192+21 denoting availability of APX_F extension;" +.PD +.SS "Notable Capability Bits for LV4" +.IX Subsection "Notable Capability Bits for LV4" +The following are notable capability bits from logical vector 4 (LV4) +resulting from the following execution of CPUID.(EAX=07H,ECX=1H).ECX and +CPUID.(EAX=24H,ECX=0H).EBX: +.IP "bits #256+32+[0:7] denoting AVX10 Converged Vector ISA Version (8 bits);" 4 +.IX Item "bits #256+32+[0:7] denoting AVX10 Converged Vector ISA Version (8 bits);" +.PD 0 +.IP "bit #256+48 denoting AVX10 XMM support;" 4 +.IX Item "bit #256+48 denoting AVX10 XMM support;" +.IP "bit #256+49 denoting AVX10 YMM support;" 4 +.IX Item "bit #256+49 denoting AVX10 YMM support;" +.IP "bit #256+50 denoting AVX10 ZMM support;" 4 +.IX Item "bit #256+50 denoting AVX10 ZMM support;" +.PD +.SS "OPENSSL_ia32cap environment variable" +.IX Subsection "OPENSSL_ia32cap environment variable" +The \fBOPENSSL_ia32cap\fR environment variable provides a mechanism to override +the default capability vector values at library initialization time. +The variable consists of a series of 64\-bit numbers representing each +of the logical vectors (LV) described above. Each value is delimited by a \*(Aq\fB:\fR\*(Aq. +Decimal/Octal/Hexadecimal values representations are supported. +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=LV0:LV1:LV2:LV3:LV4\*(C'\fR +.PP +Used in this form, each non\-null logical vector will *overwrite* the entire corresponding +capability vector pair with the provided value. To keep compatibility with the +behaviour of the original OPENSSL_ia32cap environment variable +, the next capability vector pairs will be set to zero. +.PP +To illustrate, the following will zero all capability bits in logical vectors 1 and further +(disable all post\-AVX extensions): +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=:0\*(C'\fR +.PP +The following will zero all capability bits in logical vectors 2 and further: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=::0\*(C'\fR +.PP +The following will zero all capability bits only in logical vector 1: +\&\f(CW\*(C`env OPENSSL_ia32cap=:0::::\*(C'\fR +.PP +A more likely usage scenario would be to disable specific instruction set extensions. +The \*(Aq\fB~\fR\*(Aq character is used to specify a bit mask of the extensions to be disabled for +a particular logical vector. +.PP +To illustrate, the following will disable AVX2 code paths and further extensions: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=:~0x20000000000\*(C'\fR +.PP +The following will disable AESNI (LV0 bit 57) and VAES (LV1 bit 41) +extensions and therefore any code paths using those extensions but leave +the rest of the logical vectors unchanged: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=~0x200000000000000:~0x20000000000:~0x0:~0x0:~0x0\*(C'\fR +.SH NOTES +.IX Header "NOTES" +Not all capability bits are copied from CPUID output verbatim. An example +of this is the somewhat less intuitive clearing of LV0 bit #28, or ~0x10000000 +in the "environment variable" terms. It has been adjusted to reflect whether or +not the data cache is actually shared between logical cores. This in turn affects +the decision on whether or not expensive countermeasures against cache\-timing attacks +are applied, most notably in AES assembler module. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_init_crypto.3 b/static/netbsd/man3/OPENSSL_init_crypto.3 new file mode 100644 index 00000000..90b9e6b6 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_init_crypto.3 @@ -0,0 +1,336 @@ +.\" $NetBSD: OPENSSL_init_crypto.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_init_crypto 3" +.TH OPENSSL_init_crypto 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename, +OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags, +OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit, +OPENSSL_thread_stop_ex, OPENSSL_thread_stop \- OpenSSL initialisation +and deinitialisation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void OPENSSL_cleanup(void); +\& int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); +\& int OPENSSL_atexit(void (*handler)(void)); +\& void OPENSSL_thread_stop_ex(OSSL_LIB_CTX *ctx); +\& void OPENSSL_thread_stop(void); +\& +\& OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void); +\& int OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *init, +\& const char* filename); +\& int OPENSSL_INIT_set_config_file_flags(OPENSSL_INIT_SETTINGS *init, +\& unsigned long flags); +\& int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init, +\& const char* name); +\& void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +During normal operation OpenSSL (libcrypto) will allocate various resources at +start up that must, subsequently, be freed on close down of the library. +Additionally some resources are allocated on a per thread basis (if the +application is multi\-threaded), and these resources must be freed prior to the +thread closing. +.PP +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. +.PP +However, there may be situations when explicit initialisation is desirable or +needed, for example when some nondefault initialisation is required. The +function \fBOPENSSL_init_crypto()\fR can be used for this purpose for +libcrypto (see also \fBOPENSSL_init_ssl\fR\|(3) for the libssl +equivalent). +.PP +Numerous internal OpenSSL functions call \fBOPENSSL_init_crypto()\fR. +Therefore, in order to perform nondefault initialisation, +\&\fBOPENSSL_init_crypto()\fR MUST be called by application code prior to +any other OpenSSL function calls. +.PP +The \fBopts\fR parameter specifies which aspects of libcrypto should be +initialised. Valid options are: +.IP OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS 4 +.IX Item "OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS" +Suppress automatic loading of the libcrypto error strings. This option is +not a default option. Once selected subsequent calls to +\&\fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_LOAD_CRYPTO_STRINGS\fR will be ignored. +.IP OPENSSL_INIT_LOAD_CRYPTO_STRINGS 4 +.IX Item "OPENSSL_INIT_LOAD_CRYPTO_STRINGS" +Automatic loading of the libcrypto error strings. With this option the +library will automatically load the libcrypto error strings. +This option is a default option. Once selected subsequent calls to +\&\fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS\fR will be ignored. +.IP OPENSSL_INIT_ADD_ALL_CIPHERS 4 +.IX Item "OPENSSL_INIT_ADD_ALL_CIPHERS" +With this option the library will automatically load and make available all +libcrypto ciphers. This option is a default option. Once selected subsequent +calls to \fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_NO_ADD_ALL_CIPHERS\fR will be ignored. +.IP OPENSSL_INIT_ADD_ALL_DIGESTS 4 +.IX Item "OPENSSL_INIT_ADD_ALL_DIGESTS" +With this option the library will automatically load and make available all +libcrypto digests. This option is a default option. Once selected subsequent +calls to \fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_NO_ADD_ALL_DIGESTS\fR will be ignored. +.IP OPENSSL_INIT_NO_ADD_ALL_CIPHERS 4 +.IX Item "OPENSSL_INIT_NO_ADD_ALL_CIPHERS" +With this option the library will suppress automatic loading of libcrypto +ciphers. This option is not a default option. Once selected subsequent +calls to \fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_ADD_ALL_CIPHERS\fR will be ignored. +.IP OPENSSL_INIT_NO_ADD_ALL_DIGESTS 4 +.IX Item "OPENSSL_INIT_NO_ADD_ALL_DIGESTS" +With this option the library will suppress automatic loading of libcrypto +digests. This option is not a default option. Once selected subsequent +calls to \fBOPENSSL_init_crypto()\fR with the option +\&\fBOPENSSL_INIT_ADD_ALL_DIGESTS\fR will be ignored. +.IP OPENSSL_INIT_LOAD_CONFIG 4 +.IX Item "OPENSSL_INIT_LOAD_CONFIG" +With this option an OpenSSL configuration file will be automatically loaded and +used by calling \fBOPENSSL_config()\fR. This is a default option. +Note that in OpenSSL 1.1.1 this was the default for libssl but not for +libcrypto (see \fBOPENSSL_init_ssl\fR\|(3) for further details about libssl +initialisation). +In OpenSSL 1.1.0 this was a nondefault option for both libssl and libcrypto. +See the description of \fBOPENSSL_INIT_new()\fR, below. +.IP OPENSSL_INIT_NO_LOAD_CONFIG 4 +.IX Item "OPENSSL_INIT_NO_LOAD_CONFIG" +With this option the loading of OpenSSL configuration files will be suppressed. +It is the equivalent of calling \fBOPENSSL_no_config()\fR. This is not a default +option. +.IP OPENSSL_INIT_ASYNC 4 +.IX Item "OPENSSL_INIT_ASYNC" +With this option the library with automatically initialise the libcrypto async +sub\-library (see \fBASYNC_start_job\fR\|(3)). This is a default option. +.IP OPENSSL_INIT_ENGINE_RDRAND 4 +.IX Item "OPENSSL_INIT_ENGINE_RDRAND" +With this option the library will automatically load and initialise the +RDRAND engine (if available). This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_DYNAMIC 4 +.IX Item "OPENSSL_INIT_ENGINE_DYNAMIC" +With this option the library will automatically load and initialise the +dynamic engine. This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_OPENSSL 4 +.IX Item "OPENSSL_INIT_ENGINE_OPENSSL" +With this option the library will automatically load and initialise the +openssl engine. This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_CRYPTODEV 4 +.IX Item "OPENSSL_INIT_ENGINE_CRYPTODEV" +With this option the library will automatically load and initialise the +cryptodev engine (if available). This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_CAPI 4 +.IX Item "OPENSSL_INIT_ENGINE_CAPI" +With this option the library will automatically load and initialise the +CAPI engine (if available). This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_PADLOCK 4 +.IX Item "OPENSSL_INIT_ENGINE_PADLOCK" +With this option the library will automatically load and initialise the +padlock engine (if available). This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_AFALG 4 +.IX Item "OPENSSL_INIT_ENGINE_AFALG" +With this option the library will automatically load and initialise the +AFALG engine. This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ENGINE_ALL_BUILTIN 4 +.IX Item "OPENSSL_INIT_ENGINE_ALL_BUILTIN" +With this option the library will automatically load and initialise all the +built in engines listed above with the exception of the openssl and afalg +engines. This not a default option and is deprecated +in OpenSSL 3.0. +.IP OPENSSL_INIT_ATFORK 4 +.IX Item "OPENSSL_INIT_ATFORK" +With this option the library will register its fork handlers. +See \fBOPENSSL_fork_prepare\fR\|(3) for details. +.IP OPENSSL_INIT_NO_ATEXIT 4 +.IX Item "OPENSSL_INIT_NO_ATEXIT" +By default OpenSSL will attempt to clean itself up when the process exits via an +"atexit" handler. Using this option suppresses that behaviour. This means that +the application will have to clean up OpenSSL explicitly using +\&\fBOPENSSL_cleanup()\fR. +.PP +Multiple options may be combined together in a single call to +\&\fBOPENSSL_init_crypto()\fR. For example: +.PP +.Vb 2 +\& OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS +\& | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL); +.Ve +.PP +The \fBOPENSSL_cleanup()\fR function deinitialises OpenSSL (both libcrypto +and libssl). All resources allocated by OpenSSL are freed. Typically there +should be no need to call this function directly as it is initiated +automatically on application exit. This is done via the standard C library +\&\fBatexit()\fR function. In the event that the application will close in a manner +that will not call the registered \fBatexit()\fR handlers then the application should +call \fBOPENSSL_cleanup()\fR directly. Developers of libraries using OpenSSL +are discouraged from calling this function and should instead, typically, rely +on auto\-deinitialisation. This is to avoid error conditions where both an +application and a library it depends on both use OpenSSL, and the library +deinitialises it before the application has finished using it. +.PP +Once \fBOPENSSL_cleanup()\fR has been called the library cannot be reinitialised. +Attempts to call \fBOPENSSL_init_crypto()\fR will fail and an ERR_R_INIT_FAIL error +will be added to the error stack. Note that because initialisation has failed +OpenSSL error strings will not be available, only an error code. This code can +be put through the openssl errstr command line application to produce a human +readable error (see \fBopenssl\-errstr\fR\|(1)). +.PP +The \fBOPENSSL_atexit()\fR function enables the registration of a +function to be called during \fBOPENSSL_cleanup()\fR. Stop handlers are +called after deinitialisation of resources local to a thread, but before other +process wide resources are freed. In the event that multiple stop handlers are +registered, no guarantees are made about the order of execution. +.PP +The \fBOPENSSL_thread_stop_ex()\fR function deallocates resources associated +with the current thread for the given OSSL_LIB_CTX \fBctx\fR. The \fBctx\fR parameter +can be NULL in which case the default OSSL_LIB_CTX is used. +.PP +Typically, this function will be called automatically by the library when +the thread exits as long as the OSSL_LIB_CTX has not been freed before the thread +exits. If \fBOSSL_LIB_CTX_free()\fR is called OPENSSL_thread_stop_ex will be called +automatically for the current thread (but not any other threads that may have +used this OSSL_LIB_CTX). +.PP +OPENSSL_thread_stop_ex should be called on all threads that will exit after the +OSSL_LIB_CTX is freed. +Typically this is not necessary for the default OSSL_LIB_CTX (because all +resources are cleaned up on library exit) except if thread local resources +should be freed before library exit, or under the circumstances described in +the NOTES section below. +.PP +\&\fBOPENSSL_thread_stop()\fR is the same as \fBOPENSSL_thread_stop_ex()\fR except that the +default OSSL_LIB_CTX is always used. +.PP +The \fBOPENSSL_INIT_LOAD_CONFIG\fR flag will load a configuration file, as with +\&\fBCONF_modules_load_file\fR\|(3) with NULL filename and application name and the +\&\fBCONF_MFLAGS_IGNORE_MISSING_FILE\fR, \fBCONF_MFLAGS_IGNORE_RETURN_CODES\fR and +\&\fBCONF_MFLAGS_DEFAULT_SECTION\fR flags. +The filename, application name, and flags can be customized by providing a +non\-null \fBOPENSSL_INIT_SETTINGS\fR object. +The object can be allocated via \fBOPENSSL_INIT_new()\fR. +The \fBOPENSSL_INIT_set_config_filename()\fR function can be used to specify a +nondefault filename, which is copied and need not refer to persistent storage. +Similarly, \fBOPENSSL_INIT_set_config_appname()\fR can be used to specify a +nondefault application name. +Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags. +If the \fBCONF_MFLAGS_IGNORE_RETURN_CODES\fR flag is not included, any errors in +the configuration file will cause an error return from \fBOPENSSL_init_crypto\fR +or indirectly \fBOPENSSL_init_ssl\fR\|(3). +The object can be released with \fBOPENSSL_INIT_free()\fR when done. +If the argument to \fBOPENSSL_INIT_free()\fR is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +Resources local to a thread are deallocated automatically when the thread exits +(e.g. in a pthreads environment, when \fBpthread_exit()\fR is called). On Windows +platforms this is done in response to a DLL_THREAD_DETACH message being sent to +the libcrypto32.dll entry point. Some windows functions may cause threads to exit +without sending this message (for example \fBExitProcess()\fR). If the application +uses such functions, then the application must free up OpenSSL resources +directly via a call to \fBOPENSSL_thread_stop()\fR on each thread. Similarly this +message will also not be sent if OpenSSL is linked statically, and therefore +applications using static linking should also call \fBOPENSSL_thread_stop()\fR on each +thread. Additionally if OpenSSL is loaded dynamically via \fBLoadLibrary()\fR and the +threads are not destroyed until after \fBFreeLibrary()\fR is called then each thread +should call \fBOPENSSL_thread_stop()\fR prior to the \fBFreeLibrary()\fR call. +.PP +On Linux/Unix where OpenSSL has been loaded via \fBdlopen()\fR and the application is +multi\-threaded and if \fBdlclose()\fR is subsequently called prior to the threads +being destroyed then OpenSSL will not be able to deallocate resources associated +with those threads. The application should either call \fBOPENSSL_thread_stop()\fR on +each thread prior to the \fBdlclose()\fR call, or alternatively the original \fBdlopen()\fR +call should use the RTLD_NODELETE flag (where available on the platform). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions OPENSSL_init_crypto, \fBOPENSSL_atexit()\fR and +\&\fBOPENSSL_INIT_set_config_appname()\fR return 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_init_ssl\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOPENSSL_init_crypto()\fR, \fBOPENSSL_cleanup()\fR, \fBOPENSSL_atexit()\fR, +\&\fBOPENSSL_thread_stop()\fR, \fBOPENSSL_INIT_new()\fR, \fBOPENSSL_INIT_set_config_appname()\fR +and \fBOPENSSL_INIT_free()\fR functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_init_ssl.3 b/static/netbsd/man3/OPENSSL_init_ssl.3 new file mode 100644 index 00000000..3e514ff3 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_init_ssl.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: OPENSSL_init_ssl.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_init_ssl 3" +.TH OPENSSL_init_ssl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_init_ssl \- OpenSSL (libssl and libcrypto) initialisation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +During normal operation OpenSSL (libssl and libcrypto) will allocate various +resources at start up that must, subsequently, be freed on close down of the +library. Additionally some resources are allocated on a per thread basis (if the +application is multi\-threaded), and these resources must be freed prior to the +thread closing. +.PP +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. +.PP +However, there may be situations when explicit initialisation is desirable or +needed, for example when some nondefault initialisation is required. The +function \fBOPENSSL_init_ssl()\fR can be used for this purpose. Calling +this function will explicitly initialise BOTH libcrypto and libssl. To +explicitly initialise ONLY libcrypto see the +\&\fBOPENSSL_init_crypto\fR\|(3) function. +.PP +Numerous internal OpenSSL functions call \fBOPENSSL_init_ssl()\fR. +Therefore, in order to perform nondefault initialisation, +\&\fBOPENSSL_init_ssl()\fR MUST be called by application code prior to +any other OpenSSL function calls. +.PP +The \fBopts\fR parameter specifies which aspects of libssl and libcrypto should be +initialised. Valid options for libcrypto are described on the +\&\fBOPENSSL_init_crypto\fR\|(3) page. In addition to any libcrypto +specific option the following libssl options can also be used: +.IP OPENSSL_INIT_NO_LOAD_SSL_STRINGS 4 +.IX Item "OPENSSL_INIT_NO_LOAD_SSL_STRINGS" +Suppress automatic loading of the libssl error strings. This option is +not a default option. Once selected subsequent calls to +\&\fBOPENSSL_init_ssl()\fR with the option +\&\fBOPENSSL_INIT_LOAD_SSL_STRINGS\fR will be ignored. +.IP OPENSSL_INIT_LOAD_SSL_STRINGS 4 +.IX Item "OPENSSL_INIT_LOAD_SSL_STRINGS" +Automatic loading of the libssl error strings. This option is a +default option. Once selected subsequent calls to +\&\fBOPENSSL_init_ssl()\fR with the option +\&\fBOPENSSL_INIT_LOAD_SSL_STRINGS\fR will be ignored. +.PP +\&\fBOPENSSL_init_ssl()\fR takes a \fBsettings\fR parameter which can be used to +set parameter values. See \fBOPENSSL_init_crypto\fR\|(3) for details. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The function \fBOPENSSL_init_ssl()\fR returns 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_init_crypto\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOPENSSL_init_ssl()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_instrument_bus.3 b/static/netbsd/man3/OPENSSL_instrument_bus.3 new file mode 100644 index 00000000..e22ba66f --- /dev/null +++ b/static/netbsd/man3/OPENSSL_instrument_bus.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: OPENSSL_instrument_bus.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_instrument_bus 3" +.TH OPENSSL_instrument_bus 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_instrument_bus, OPENSSL_instrument_bus2 \- instrument references to memory bus +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 4 +\& #ifdef OPENSSL_CPUID_OBJ +\& size_t OPENSSL_instrument_bus(unsigned int *vector, size_t num); +\& size_t OPENSSL_instrument_bus2(unsigned int *vector, size_t num, size_t max); +\& #endif +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +It was empirically found that timings of references to primary memory +are subject to irregular, apparently non\-deterministic variations. The +subroutines in question instrument these references for purposes of +gathering randomness for random number generator. In order to make it +bus\-bound a \*(Aqflush cache line\*(Aq instruction is used between probes. In +addition probes are added to \fBvector\fR elements in atomic or +interlocked manner, which should contribute additional noise on +multi\-processor systems. This also means that \fBvector[num]\fR should be +zeroed upon invocation (if you want to retrieve actual probe values). +.PP +\&\fBOPENSSL_instrument_bus()\fR performs \fBnum\fR probes and records the number of +oscillator cycles every probe took. +.PP +\&\fBOPENSSL_instrument_bus2()\fR on the other hand \fBaccumulates\fR consecutive +probes with the same value, i.e. in a way it records duration of +periods when probe values appeared deterministic. The subroutine +performs at most \fBmax\fR probes in attempt to fill the \fBvector[num]\fR, +with \fBmax\fR value of 0 meaning "as many as it takes." +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Return value of 0 indicates that CPU is not capable of performing the +benchmark, either because oscillator counter or \*(Aqflush cache line\*(Aq is +not available on current platform. For reference, on x86 \*(Aqflush cache +line\*(Aq was introduced with the SSE2 extensions. +.PP +Otherwise number of recorded values is returned. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2011\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_load_builtin_modules.3 b/static/netbsd/man3/OPENSSL_load_builtin_modules.3 new file mode 100644 index 00000000..71dbaba7 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_load_builtin_modules.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: OPENSSL_load_builtin_modules.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_load_builtin_modules 3" +.TH OPENSSL_load_builtin_modules 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module \- add standard configuration modules +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void OPENSSL_load_builtin_modules(void); +\& void ASN1_add_oid_module(void); +\& void ENGINE_add_conf_module(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBOPENSSL_load_builtin_modules()\fR adds all the standard OpenSSL +configuration modules to the internal list. They can then be used by the +OpenSSL configuration code. +.PP +\&\fBASN1_add_oid_module()\fR adds just the ASN1 OBJECT module. +.PP +\&\fBENGINE_add_conf_module()\fR adds just the ENGINE configuration module. +.SH NOTES +.IX Header "NOTES" +If the simple configuration function \fBOPENSSL_config()\fR is called then +\&\fBOPENSSL_load_builtin_modules()\fR is called automatically. +.PP +Applications which use the configuration functions directly will need to +call \fBOPENSSL_load_builtin_modules()\fR themselves \fIbefore\fR any other +configuration code. +.PP +Applications should call \fBOPENSSL_load_builtin_modules()\fR to load all +configuration modules instead of adding modules selectively: otherwise +functionality may be missing from the application if an when new +modules are added. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +None of the functions return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBconfig\fR\|(5), \fBOPENSSL_config\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBENGINE_add_conf_module()\fR was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_load_u16_le.3 b/static/netbsd/man3/OPENSSL_load_u16_le.3 new file mode 100644 index 00000000..426c9fcc --- /dev/null +++ b/static/netbsd/man3/OPENSSL_load_u16_le.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: OPENSSL_load_u16_le.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_load_u16_le 3" +.TH OPENSSL_load_u16_le 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_load_u16_le, OPENSSL_load_u16_be, OPENSSL_load_u32_le, +OPENSSL_load_u32_be, OPENSSL_load_u64_le, OPENSSL_load_u64_be, +OPENSSL_store_u16_le, OPENSSL_store_u16_be, +OPENSSL_store_u32_le, OPENSSL_store_u32_be, +OPENSSL_store_u64_le, OPENSSL_store_u64_be \- +Read and write unsigned 16, 32 and 64\-bit integers in a specific byte order +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& static ossl_inline unsigned char *OPENSSL_store_u16_le( +\& unsigned char *out, uint16_t val); +\& static ossl_inline unsigned char *OPENSSL_store_u16_be( +\& unsigned char *out, uint16_t val); +\& static ossl_inline unsigned char *OPENSSL_store_u32_le( +\& unsigned char *out, uint32_t val); +\& static ossl_inline unsigned char *OPENSSL_store_u32_be( +\& unsigned char *out, uint32_t val); +\& static ossl_inline unsigned char *OPENSSL_store_u64_le( +\& unsigned char *out, uint64_t val); +\& static ossl_inline unsigned char *OPENSSL_store_u64_be( +\& unsigned char *out, uint64_t val); +\& static ossl_inline const unsigned char *OPENSSL_load_u16_le( +\& uint16_t *val, const unsigned char *in); +\& static ossl_inline const unsigned char *OPENSSL_load_u16_be( +\& uint16_t *val, const unsigned char *in); +\& static ossl_inline const unsigned char *OPENSSL_load_u32_le( +\& uint32_t *val, const unsigned char *in); +\& static ossl_inline const unsigned char *OPENSSL_load_u32_be( +\& uint32_t *val, const unsigned char *in); +\& static ossl_inline const unsigned char *OPENSSL_load_u64_le( +\& uint64_t *val, const unsigned char *in); +\& static ossl_inline const unsigned char *OPENSSL_load_u64_be( +\& uint64_t *val, const unsigned char *in); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions read and write 16, 32 and 64 bit unsigned integers in a +specified byte order. +The \f(CW\*(C`_be\*(C'\fR functions use big\-endian byte order, while the \f(CW\*(C`_le\*(C'\fR functions use +little\-endian byte order. +They\*(Aqre implemented directly in the header file, and declared static. When the +compiler supports inline functions, they\*(Aqre also declared inline. +An optimising compiler will often convert these to just one or two machine +instructions: a load or store with a possible byte swap. +.PP +The \f(CW\*(C`load\*(C'\fR functions write the decoded integer value at the address pointed to +by \fIval\fR, which must be a valid (possibly suitably aligned) address of an +object of the appropriate type. +The \f(CW\*(C`store\*(C'\fR functions write the encoding of \fIval\fR at the address pointed to +by \fIout\fR. +.PP +For convenience, these functions return the updated input or output pointer, +making it easy to continue reading or writing more data at the next memory +location. +.PP +No bounds checks are performed, the caller is responsible for making sure that +the input or output buffers are sufficiently large for the requested read or +write. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return the next memory address following the last byte +written or read. +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_malloc.3 b/static/netbsd/man3/OPENSSL_malloc.3 new file mode 100644 index 00000000..92442b13 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_malloc.3 @@ -0,0 +1,323 @@ +.\" $NetBSD: OPENSSL_malloc.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_malloc 3" +.TH OPENSSL_malloc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_malloc_init, +OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc, +OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, +CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, +OPENSSL_strdup, OPENSSL_strndup, +OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul, +CRYPTO_strdup, CRYPTO_strndup, +OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, +CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, +CRYPTO_clear_realloc, CRYPTO_clear_free, +CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn, +CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, +CRYPTO_get_alloc_counts, +CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, +CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, +OPENSSL_MALLOC_FAILURES, +OPENSSL_MALLOC_FD +\&\- Memory allocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OPENSSL_malloc_init(void); +\& +\& void *OPENSSL_malloc(size_t num); +\& void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr); +\& void *OPENSSL_zalloc(size_t num); +\& void *OPENSSL_realloc(void *addr, size_t num); +\& void OPENSSL_free(void *addr); +\& char *OPENSSL_strdup(const char *str); +\& char *OPENSSL_strndup(const char *str, size_t s); +\& size_t OPENSSL_strlcat(char *dst, const char *src, size_t size); +\& size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size); +\& int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num); +\& void *OPENSSL_memdup(void *data, size_t s); +\& void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num); +\& void OPENSSL_clear_free(void *str, size_t num); +\& void OPENSSL_cleanse(void *ptr, size_t len); +\& +\& void *CRYPTO_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr, +\& const char *file, int line); +\& void *CRYPTO_zalloc(size_t num, const char *file, int line); +\& void *CRYPTO_realloc(void *p, size_t num, const char *file, int line); +\& void CRYPTO_free(void *str, const char *, int); +\& char *CRYPTO_strdup(const char *p, const char *file, int line); +\& char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line); +\& void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, +\& const char *file, int line); +\& void CRYPTO_clear_free(void *str, size_t num, const char *, int); +\& +\& typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line); +\& typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file, +\& int line); +\& typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line); +\& void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn, +\& CRYPTO_realloc_fn *realloc_fn, +\& CRYPTO_free_fn *free_fn); +\& int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn, +\& CRYPTO_realloc_fn realloc_fn, +\& CRYPTO_free_fn free_fn); +\& +\& void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount); +\& +\& env OPENSSL_MALLOC_FAILURES=... +\& env OPENSSL_MALLOC_FD=... +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& int CRYPTO_mem_leaks(BIO *b); +\& int CRYPTO_mem_leaks_fp(FILE *fp); +\& int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), +\& void *u); +\& +\& int CRYPTO_set_mem_debug(int onoff); +\& int CRYPTO_mem_ctrl(int mode); +\& int OPENSSL_mem_debug_push(const char *info); +\& int OPENSSL_mem_debug_pop(void); +\& int CRYPTO_mem_debug_push(const char *info, const char *file, int line); +\& int CRYPTO_mem_debug_pop(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL memory allocation is handled by the \fBOPENSSL_xxx\fR API. These are +generally macro\*(Aqs that add the standard C \fB_\|_FILE_\|_\fR and \fB_\|_LINE_\|_\fR +parameters and call a lower\-level \fBCRYPTO_xxx\fR API. +Some functions do not add those parameters, but exist for consistency. +.PP +\&\fBOPENSSL_malloc_init()\fR does nothing and does not need to be called. It is +included for compatibility with older versions of OpenSSL. +.PP +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR, and \fBOPENSSL_free()\fR are like the +C \fBmalloc()\fR, \fBrealloc()\fR, and \fBfree()\fR functions. +\&\fBOPENSSL_zalloc()\fR calls \fBmemset()\fR to zero the memory before returning. +.PP +\&\fBOPENSSL_aligned_alloc()\fR operates just as OPENSSL_malloc does, but it +allows for the caller to specify an alignment value, for instances in +which the default alignment of malloc is insufficient for the callers +needs. Note, the alignment value must be a power of 2, and the size +specified must be a multiple of the alignment. +NOTE: The call to \fBOPENSSL_aligned_alloc()\fR accepts a 3rd argument, \fIfreeptr\fR +which must point to a void pointer. On some platforms, there is no available +library call to obtain memory allocations greater than what malloc provides. In +this case, OPENSSL_aligned_alloc implements its own alignment routine, +allocating additional memory and offsetting the returned pointer to be on the +requested alignment boundary. In order to safely free allocations made by this +method, the caller must return the value in the \fIfreeptr\fR variable, rather than +the returned pointer. +.PP +\&\fBOPENSSL_clear_realloc()\fR and \fBOPENSSL_clear_free()\fR should be used +when the buffer at \fBaddr\fR holds sensitive information. +The old buffer is filled with zero\*(Aqs by calling \fBOPENSSL_cleanse()\fR +before ultimately calling \fBOPENSSL_free()\fR. If the argument to +\&\fBOPENSSL_clear_free()\fR is NULL, nothing is done. +.PP +\&\fBOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0\*(Aqs. +It is useful in cases when it is needed to ensure that memory (that contains +sensitive information) is overwritten (for example, before it is reclaimed, +or when it is stored on stack), and such operation is not optimised out +by compiler optimisations such as dead store elimination (as \fBmemset\fR\|(3) may be). +Use \fBOPENSSL_cleanse()\fR with care if the memory is a mapping of a file. +If the storage controller uses write compression, then it\*(Aqs possible +that sensitive tail bytes will survive zeroization because the block of +zeros will be compressed. If the storage controller uses wear leveling, +then the old sensitive data will not be overwritten; rather, a block of +0\*(Aqs will be written at a new physical location. +.PP +\&\fBOPENSSL_strdup()\fR, \fBOPENSSL_strndup()\fR and \fBOPENSSL_memdup()\fR are like the +equivalent C functions, except that memory is allocated by calling the +\&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR. +.PP +\&\fBOPENSSL_strlcpy()\fR, +\&\fBOPENSSL_strlcat()\fR and \fBOPENSSL_strnlen()\fR are equivalents of the common C +library functions and are provided for portability. +.PP +\&\fBOPENSSL_strtoul()\fR is a wrapper around the POSIX function strtoul, with the same +behaviors listed in the POSIX documentation, with the additional behavior that +it validates the input \fIstr\fR and \fInum\fR parameters for not being NULL, and confirms +that at least a single byte of input has been consumed in the translation, +returning an error in the event that no bytes were consumed. +.PP +If no allocations have been done, it is possible to "swap out" the default +implementations for \fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR and \fBOPENSSL_free()\fR +and replace them with alternate versions. +\&\fBCRYPTO_get_mem_functions()\fR function fills in the given arguments with the +function pointers for the current implementations. +With \fBCRYPTO_set_mem_functions()\fR, you can specify a different set of functions. +If any of \fBmalloc_fn\fR, \fBrealloc_fn\fR, or \fBfree_fn\fR are NULL, then +the function is not changed. +While it\*(Aqs permitted to swap out only a few and not all the functions +with \fBCRYPTO_set_mem_functions()\fR, it\*(Aqs recommended to swap them all out +at once. +.PP +If the library is built with the \f(CW\*(C`crypto\-mdebug\*(C'\fR option, then one +function, \fBCRYPTO_get_alloc_counts()\fR, and two additional environment +variables, \fBOPENSSL_MALLOC_FAILURES\fR and \fBOPENSSL_MALLOC_FD\fR, +are available. +.PP +The function \fBCRYPTO_get_alloc_counts()\fR fills in the number of times +each of \fBCRYPTO_malloc()\fR, \fBCRYPTO_realloc()\fR, and \fBCRYPTO_free()\fR have been +called, into the values pointed to by \fBmcount\fR, \fBrcount\fR, and \fBfcount\fR, +respectively. If a pointer is NULL, then the corresponding count is not stored. +.PP +The variable +\&\fBOPENSSL_MALLOC_FAILURES\fR controls how often allocations should fail. +It is a set of fields separated by semicolons, which each field is a count +(defaulting to zero) and an optional atsign and percentage (defaulting +to 100). If the count is zero, then it lasts forever. For example, +\&\f(CW\*(C`100;@25\*(C'\fR or \f(CW\*(C`100@0;0@25\*(C'\fR means the first 100 allocations pass, then all +other allocations (until the program exits or crashes) have a 25% chance of +failing. The length of the value of \fBOPENSSL_MALLOC_FAILURES\fR must be 256 or +fewer characters. +.PP +If the variable \fBOPENSSL_MALLOC_FD\fR is parsed as a positive integer, then +it is taken as an open file descriptor. This is used in conjunction with +\&\fBOPENSSL_MALLOC_FAILURES\fR described above. For every allocation it will log +details about how many allocations there have been so far, what percentage +chance there is for this allocation failing, and whether it has actually failed. +The following example in classic shell syntax shows how to use this (will not +work on all platforms): +.PP +.Vb 5 +\& OPENSSL_MALLOC_FAILURES=\*(Aq200;@10\*(Aq +\& export OPENSSL_MALLOC_FAILURES +\& OPENSSL_MALLOC_FD=3 +\& export OPENSSL_MALLOC_FD +\& ...app invocation... 3>/tmp/log$$ +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOPENSSL_malloc_init()\fR, \fBOPENSSL_free()\fR, \fBOPENSSL_clear_free()\fR +\&\fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR and \fBCRYPTO_get_mem_functions()\fR +return no value. +.PP +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_aligned_alloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_realloc()\fR, +\&\fBOPENSSL_clear_realloc()\fR, +\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_realloc()\fR, +\&\fBCRYPTO_clear_realloc()\fR, +\&\fBOPENSSL_strdup()\fR, and \fBOPENSSL_strndup()\fR +return a pointer to allocated memory or NULL on error. +.PP +\&\fBCRYPTO_set_mem_functions()\fR returns 1 on success or 0 on failure (almost +always because allocations have already happened). +.PP +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, \fBCRYPTO_mem_leaks_cb()\fR, +\&\fBCRYPTO_set_mem_debug()\fR, and \fBCRYPTO_mem_ctrl()\fR are deprecated and are no\-ops that +always return \-1. +\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_debug_push()\fR, and \fBCRYPTO_mem_debug_pop()\fR +are deprecated and are no\-ops that always return 0. +.PP +\&\fBOPENSSL_strtoul()\fR returns 1 on success and 0 in the event that an error has +occurred. Specifically, 0 is returned in the following events: +.IP \(bu 4 +If the underlying call to strtoul returned a non zero errno value +.IP \(bu 4 +If the translation did not consume the entire input string, and the passed +endptr value was NULL +.IP \(bu 4 +If no characters were consumed in the translation +.PP +Note that a success condition does not imply that the expected +translation has been performed. For instance calling +.PP +.Vb 1 +\& OPENSSL_strtoul("0x12345", &endptr, 10, &num); +.Ve +.PP +will result in a successful translation with num having the value 0, and +*endptr = \*(Aqx\*(Aq. Be sure to validate how much data was consumed when calling this +function. +.SH HISTORY +.IX Header "HISTORY" +\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, +\&\fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_set_mem_debug()\fR, \fBCRYPTO_mem_ctrl()\fR +were deprecated in OpenSSL 3.0. +The memory\-leak checking has been deprecated in OpenSSL 3.0 in favor of +clang\*(Aqs memory and leak sanitizer. +\&\fBOPENSSL_aligned_alloc()\fR, \fBCRYPTO_aligned_alloc()\fR, \fBOPENSSL_strtoul()\fR were +added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_ppccap.3 b/static/netbsd/man3/OPENSSL_ppccap.3 new file mode 100644 index 00000000..2cb2a365 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_ppccap.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: OPENSSL_ppccap.3,v 1.2 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_ppccap 3" +.TH OPENSSL_ppccap 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_ppccap \- the PowerPC processor capabilities vector +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& env OPENSSL_ppccap=... +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +libcrypto supports PowerPC instruction set extensions. These extensions are +represented by bits in the PowerPC capabilities vector. When libcrypto +initializes, it stores the results returned by PowerPC CPU capabilities detection +logic in the PowerPC capabilities vector. The CPU capabilities detection methods +are OS\-dependent and use a combination of information gathered by the kernel +during boot and probe functions that attempt to execute instructions and trap +illegal instruction signals with a signal handler. +.PP +To override the set of extensions available to an application, you can set the +\&\fBOPENSSL_ppccap\fR environment variable before you start the application. The +environment variable is assigned a numerical value that denotes the bits in +the PowerPC capabilities vector. The ppc_arch.h header file states that, "Flags\*(Aq +usage can appear ambiguous, because they are set rather to reflect OpenSSL +performance preferences than actual processor capabilities." +.PP +Multiple extensions are enabled by logically OR\-ing the values that represent the +desired extensions. +.PP +\&\fBNotes\fR: Enabling an extension on a CPU that does not support the extension +will result in a SIGILL crash. On AIX, all vector instructions can be disabled +with the schedo \-ro allow_vmx=0 command. DO NOT USE THIS COMMAND to disable +vector instructions in the OS when it is running on a CPU level that supports the +instructions without also disabling them in libcrpto via the OPENSSL_ppccap +environment variable or the application will crash with a SIGILL. +.PP +Currently, the following extensions are defined: +.IP 0x01 4 +.IX Item "0x01" +Name: \fBPPC_FPU64\fR +.Sp +This flag is obsolete. +.IP 0x02 4 +.IX Item "0x02" +Name: \fBPPC_ALTIVEC\fR +.Sp +Meaning: Use AltiVec (aka VMX) instructions. In some but not all cases, this +capability gates the use of later ISA vector instructions. The associated probe +instruction is vor (vector logical or). +.Sp +Effect: Enables use of vector instructions but does not enable extensions added +at specific ISA levels. However, disabling this capability disables a subset of +vector extensions added at specific ISA levels even if they are otherwise +enabled. +.IP 0x04 4 +.IX Item "0x04" +Name: \fBPPC_CRYPTO207\fR +.Sp +Meaning: Use instructions added in ISA level 2.07. The associated probe +instruction instruction is vcipher (vector AES cipher round). +.Sp +Effect: Enables AES, SHA\-2 sigma, and other ISA 2.07 instructions for AES, SHA\-2, +GHASH, and Poly1305. +.IP 0x08 4 +.IX Item "0x08" +Name: \fBPPC_FPU\fR +.Sp +Meaning: Use FPU instructions. The associated probe instruction is fmr (floating +move register). +.Sp +Effect: Enables Poly1305 FPU implementation. The PPC_CRYPTO207 capability +overrides this effect. +.IP 0x10 4 +.IX Item "0x10" +Name: \fBPPC_MADD300\fR +.Sp +Meaning: Use instructions added in ISA level 3.00. The associated probe +instruction is maddhdu (multiply\-add high doubleword unsigned). +.Sp +Effect: Enables use of the polynomial multiply and other ISA 3.00 instructions +for AES\-GCM, P\-384, and P\-521. +.IP 0x20 4 +.IX Item "0x20" +Name: \fBPPC_MFTB\fR +.Sp +Meaning: Use the mftb (move from time base) instruction. The associated probe +instruction is mftb. +.Sp +Effect: Enables use of the mftb instruction to sample the lower 32 bits of the +CPU time base register in order to acquire entropy. Considered obsolete. The +PPC_MFSPR268 capability overrides this capability. +.IP 0x40 4 +.IX Item "0x40" +Name: \fBPPC_MFSPR268\fR +.Sp +Meaning: Use the mfspr (move from special purpose register) instruction to +read SPR 268. The associated probe instruction is mfspr 268. +.Sp +Effect: Enables use of the mfspr instruction to sample the lower 32 bits of the +CPU time base register from SPR 268, the TBL (time base lower) register, in order +to acquire entropy. +.IP 0x80 4 +.IX Item "0x80" +Name: \fBPPC_BRD31\fR +.Sp +Meaning: Use instructions added in ISA level 3.1. The associated probe instruction +is brd (byte\-reverse doubleword). +.Sp +Effect: Enables use of ISA 3.1 instructions in ChaCha20. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH EXAMPLES +.IX Header "EXAMPLES" +Check currently detected capabilities: +.PP +.Vb 2 +\& $ openssl info \-cpusettings +\& OPENSSL_ppccap=0x2E +.Ve +.PP +The detected capabilities in the above example indicate that PPC_MFTB, PPC_FPU, +PPC_CRYPTO207, PPC_MFSPR268, and PPC_ALTIVEC are enabled. +.PP +Disable all instruction set extensions: +.PP +.Vb 1 +\& OPENSSL_ppccap=0x00 +.Ve +.PP +Enable base AltiVec extensions: +.PP +.Vb 1 +\& OPENSSL_ppccap=0x02 +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_riscvcap.3 b/static/netbsd/man3/OPENSSL_riscvcap.3 new file mode 100644 index 00000000..83dd2982 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_riscvcap.3 @@ -0,0 +1,256 @@ +.\" $NetBSD: OPENSSL_riscvcap.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_riscvcap 3" +.TH OPENSSL_riscvcap 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_riscvcap \- the RISC\-V processor capabilities vector +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& env OPENSSL_riscvcap=... +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +libcrypto supports RISC\-V instruction set extensions. These +extensions are denoted by individual extension names in the capabilities +vector. For Linux platform, when libcrypto is initialized, the results +returned by the RISC\-V Hardware Probing syscall (hwprobe) are stored +in the vector. Otherwise all capabilities are disabled. +.PP +To override the set of instructions available to an application, you can +set the \fBOPENSSL_riscvcap\fR environment variable before you start the +application. +.PP +The environment variable is similar to the RISC\-V ISA string defined in the +RISC\-V Instruction Set Manual. It is case insensitive. Though due to the limit +of the environment variable parser inside libcrypto, an extension must be +prefixed with an underscore to make it recognizable. This also applies to the +Vector extension. +.PP +.Vb 1 +\& OPENSSL_riscvcap="rv64gc_v_zba_zbb_zbs..." +.Ve +.PP +Note that extension implication is currently not implemented. +For example, when "rv64gc_b" is provided as the environment variable, +zba/zbb/zbs would not be implied in the capability vector. +.PP +Currently only these extensions are recognized: +.IP ZBA 4 +.IX Item "ZBA" +Address Generation +.Sp +Could be detected using hwprobe for Linux kernel >= 6.5 +.IP ZBB 4 +.IX Item "ZBB" +Basic bit\-manipulation +.Sp +Could be detected using hwprobe for Linux kernel >= 6.5 +.IP ZBC 4 +.IX Item "ZBC" +Carry\-less multiplication +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZBS 4 +.IX Item "ZBS" +Single\-bit instructions +.Sp +Could be detected using hwprobe for Linux kernel >= 6.5 +.IP ZBKB 4 +.IX Item "ZBKB" +Bit\-manipulation for Cryptography +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZBKC 4 +.IX Item "ZBKC" +Carry\-less multiplication for Cryptography +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZBKX 4 +.IX Item "ZBKX" +Crossbar permutations +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKND 4 +.IX Item "ZKND" +NIST Suite: AES Decryption +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKNE 4 +.IX Item "ZKNE" +NIST Suite: AES Encryption +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKNH 4 +.IX Item "ZKNH" +NIST Suite: Hash Function Instructions +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKSED 4 +.IX Item "ZKSED" +ShangMi Suite: SM4 Block Cipher Instructions +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKSH 4 +.IX Item "ZKSH" +ShangMi Suite: SM3 Hash Function Instructions +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZKR 4 +.IX Item "ZKR" +Entropy Source Extension +.IP ZKT 4 +.IX Item "ZKT" +Data Independent Execution Latency +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP V 4 +.IX Item "V" +Vector Extension for Application Processors +.Sp +Could be detected using hwprobe for Linux kernel >= 6.5 +.IP ZVBB 4 +.IX Item "ZVBB" +Vector Basic Bit\-manipulation +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVBC 4 +.IX Item "ZVBC" +Vector Carryless Multiplication +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKB 4 +.IX Item "ZVKB" +Vector Cryptography Bit\-manipulation +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKG 4 +.IX Item "ZVKG" +Vector GCM/GMAC +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKNED 4 +.IX Item "ZVKNED" +NIST Suite: Vector AES Block Cipher +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKNHA 4 +.IX Item "ZVKNHA" +NIST Suite: Vector SHA\-2 Secure Hash +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKNHB 4 +.IX Item "ZVKNHB" +NIST Suite: Vector SHA\-2 Secure Hash +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKSED 4 +.IX Item "ZVKSED" +ShangMi Suite: SM4 Block Cipher +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.IP ZVKSH 4 +.IX Item "ZVKSH" +ShangMi Suite: SM3 Secure Hash +.Sp +Could be detected using hwprobe for Linux kernel >= 6.8 +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH EXAMPLES +.IX Header "EXAMPLES" +Check currently detected capabilities +.PP +.Vb 2 +\& $ openssl info \-cpusettings +\& OPENSSL_riscvcap=RV64GC_ZBA_ZBB_ZBC_ZBS_V vlen:256 +.Ve +.PP +Note: The first word in the displayed capabilities is the RISC\-V base +architecture value, which is derived from the compiler configuration. +It is therefore not overridable by the environment variable. +When the V extension is given the riscv_vlen value is always displayed, +there is no way to override the riscv_vlen by the environment variable. +.PP +Disables all instruction set extensions: +.PP +.Vb 1 +\& export OPENSSL_riscvcap="rv64gc" +.Ve +.PP +Only enable the vector extension: +.PP +.Vb 1 +\& export OPENSSL_riscvcap="rv64gc_v" +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_s390xcap.3 b/static/netbsd/man3/OPENSSL_s390xcap.3 new file mode 100644 index 00000000..6176eabe --- /dev/null +++ b/static/netbsd/man3/OPENSSL_s390xcap.3 @@ -0,0 +1,271 @@ +.\" $NetBSD: OPENSSL_s390xcap.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_s390xcap 3" +.TH OPENSSL_s390xcap 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_s390xcap \- the IBM z processor capabilities vector +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& env OPENSSL_s390xcap=... +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +libcrypto supports z/Architecture instruction set extensions. These +extensions are denoted by individual bits in the capabilities vector. +When libcrypto is initialized, the bits returned by the STFLE instruction +and by the QUERY functions are stored in the vector. +.PP +To change the set of instructions available to an application, you can +set the \fBOPENSSL_s390xcap\fR environment variable before you start the +application. After initialization, the capability vector is ANDed bitwise +with a mask which is derived from the environment variable. +.PP +The environment variable is a semicolon\-separated list of tokens which is +processed from left to right (whitespace is ignored): +.PP +.Vb 1 +\& OPENSSL_s390xcap=";;..." +.Ve +.PP +There are four types of tokens: +.IP 4 +.IX Item "" +The name of a processor generation. A bit in the environment variable\*(Aqs +mask is set to one if and only if the specified processor generation +implements the corresponding instruction set extension. Possible values +are \fBz900\fR, \fBz990\fR, \fBz9\fR, \fBz10\fR, \fBz196\fR, \fBzEC12\fR, \fBz13\fR, \fBz14\fR, +\&\fBz15\fR, and \fBz16\fR. +.IP :: 4 +.IX Item "::" +The name of an instruction followed by two 64\-bit masks. The part of the +environment variable\*(Aqs mask corresponding to the specified instruction is +set to the specified 128\-bit mask. Possible values are \fBkimd\fR, \fBklmd\fR, +\&\fBkm\fR, \fBkmc\fR, \fBkmac\fR, \fBkmctr\fR, \fBkmo\fR, \fBkmf\fR, \fBprno\fR, \fBkma\fR, \fBpcc\fR +and \fBkdsa\fR. +.IP stfle::: 4 +.IX Item "stfle:::" +Store\-facility\-list\-extended (stfle) followed by three 64\-bit masks. The +part of the environment variable\*(Aqs mask corresponding to the stfle +instruction is set to the specified 192\-bit mask. +.IP nocex 4 +.IX Item "nocex" +Deactivate modular exponentiation and CRT operation offloading to +Crypto Express Adapters. +.PP +The 64\-bit masks are specified in hexadecimal notation. The 0x prefix is +optional. Prefix a mask with a tilde, \f(CW\*(C`~\*(C'\fR, to denote a bitwise NOT operation. +.PP +The following is a list of significant bits for each instruction. Colon +rows separate the individual 64\-bit masks. The bit numbers in the first +column are consistent with [1], that is, 0 denotes the leftmost bit and +the numbering is continuous across 64\-bit mask boundaries. +.PP +.Vb 1 +\& Bit Mask Facility/Function +\& +\& stfle: +\& # 17 1<<46 message\-security assist +\& # 25 1<<38 store\-clock\-fast facility +\& : +\& # 76 1<<51 message\-security assist extension 3 +\& # 77 1<<50 message\-security assist extension 4 +\& # 86 1<<41 message\-security\-assist extension 12 +\& : +\& #129 1<<62 vector facility +\& #134 1<<57 vector packed decimal facility +\& #135 1<<56 vector enhancements facility 1 +\& #146 1<<45 message\-security assist extension 8 +\& #155 1<<36 message\-security assist extension 9 +\& +\& kimd : +\& # 1 1<<62 KIMD\-SHA\-1 +\& # 2 1<<61 KIMD\-SHA\-256 +\& # 3 1<<60 KIMD\-SHA\-512 +\& # 32 1<<31 KIMD\-SHA3\-224 +\& # 33 1<<30 KIMD\-SHA3\-256 +\& # 34 1<<29 KIMD\-SHA3\-384 +\& # 35 1<<28 KIMD\-SHA3\-512 +\& # 36 1<<27 KIMD\-SHAKE\-128 +\& # 37 1<<26 KIMD\-SHAKE\-256 +\& : +\& # 65 1<<62 KIMD\-GHASH +\& +\& klmd : +\& # 32 1<<31 KLMD\-SHA3\-224 +\& # 33 1<<30 KLMD\-SHA3\-256 +\& # 34 1<<29 KLMD\-SHA3\-384 +\& # 35 1<<28 KLMD\-SHA3\-512 +\& # 36 1<<27 KLMD\-SHAKE\-128 +\& # 37 1<<26 KLMD\-SHAKE\-256 +\& : +\& +\& km : +\& # 18 1<<45 KM\-AES\-128 +\& # 19 1<<44 KM\-AES\-192 +\& # 20 1<<43 KM\-AES\-256 +\& # 50 1<<13 KM\-XTS\-AES\-128 +\& # 52 1<<11 KM\-XTS\-AES\-256 +\& : +\& # 82 1<<45 KM\-XTS\-AES\-128\-MSA10 +\& # 84 1<<43 KM\-XTS\-AES\-256\-MSA10 +\& +\& kmc : +\& # 18 1<<45 KMC\-AES\-128 +\& # 19 1<<44 KMC\-AES\-192 +\& # 20 1<<43 KMC\-AES\-256 +\& : +\& +\& kmac : +\& # 18 1<<45 KMAC\-AES\-128 +\& # 19 1<<44 KMAC\-AES\-192 +\& # 20 1<<43 KMAC\-AES\-256 +\& : +\& # 112 1<<15 KMAC\-SHA\-224 +\& # 113 1<<14 KMAC\-SHA\-256 +\& # 114 1<<13 KMAC\-SHA\-384 +\& # 115 1<<12 KMAC\-SHA\-512 +\& +\& kmctr: +\& : +\& +\& kmo : +\& # 18 1<<45 KMO\-AES\-128 +\& # 19 1<<44 KMO\-AES\-192 +\& # 20 1<<43 KMO\-AES\-256 +\& : +\& +\& kmf : +\& # 18 1<<45 KMF\-AES\-128 +\& # 19 1<<44 KMF\-AES\-192 +\& # 20 1<<43 KMF\-AES\-256 +\& : +\& +\& prno : +\& : +\& +\& kma : +\& # 18 1<<45 KMA\-GCM\-AES\-128 +\& # 19 1<<44 KMA\-GCM\-AES\-192 +\& # 20 1<<43 KMA\-GCM\-AES\-256 +\& : +\& +\& pcc : +\& : +\& # 64 1<<63 PCC\-Scalar\-Multiply\-P256 +\& # 65 1<<62 PCC\-Scalar\-Multiply\-P384 +\& # 66 1<<61 PCC\-Scalar\-Multiply\-P521 +\& # 72 1<<55 PCC\-Scalar\-Multiply\-Ed25519 +\& # 73 1<<54 PCC\-Scalar\-Multiply\-Ed448 +\& # 80 1<<47 PCC\-Scalar\-Multiply\-X25519 +\& # 81 1<<46 PCC\-Scalar\-Multiply\-X448 +\& +\& kdsa : +\& # 1 1<<62 KDSA\-ECDSA\-Verify\-P256 +\& # 2 1<<61 KDSA\-ECDSA\-Verify\-P384 +\& # 3 1<<60 KDSA\-ECDSA\-Verify\-P521 +\& # 9 1<<54 KDSA\-ECDSA\-Sign\-P256 +\& # 10 1<<53 KDSA\-ECDSA\-Sign\-P384 +\& # 11 1<<52 KDSA\-ECDSA\-Sign\-P521 +\& # 32 1<<31 KDSA\-EdDSA\-Verify\-Ed25519 +\& # 36 1<<27 KDSA\-EdDSA\-Verify\-Ed448 +\& # 40 1<<23 KDSA\-EdDSA\-Sign\-Ed25519 +\& # 44 1<<19 KDSA\-EdDSA\-Sign\-Ed448 +\& : +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH EXAMPLES +.IX Header "EXAMPLES" +Disables all instruction set extensions which the z196 processor does not implement: +.PP +.Vb 1 +\& OPENSSL_s390xcap="z196" +.Ve +.PP +Disables the vector facility: +.PP +.Vb 1 +\& OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000" +.Ve +.PP +Disables the KM\-XTS\-AES and the KIMD\-SHAKE function codes: +.PP +.Vb 1 +\& OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0" +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +[1] z/Architecture Principles of Operation, SA22\-7832\-12 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_secure_malloc.3 b/static/netbsd/man3/OPENSSL_secure_malloc.3 new file mode 100644 index 00000000..20d28d5b --- /dev/null +++ b/static/netbsd/man3/OPENSSL_secure_malloc.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: OPENSSL_secure_malloc.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_secure_malloc 3" +.TH OPENSSL_secure_malloc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized, +CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc, +OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free, +CRYPTO_secure_free, OPENSSL_secure_clear_free, +CRYPTO_secure_clear_free, OPENSSL_secure_actual_size, +CRYPTO_secure_allocated, +CRYPTO_secure_used \- secure heap storage +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int CRYPTO_secure_malloc_init(size_t size, size_t minsize); +\& +\& int CRYPTO_secure_malloc_initialized(); +\& +\& int CRYPTO_secure_malloc_done(); +\& +\& void *OPENSSL_secure_malloc(size_t num); +\& void *CRYPTO_secure_malloc(size_t num, const char *file, int line); +\& +\& void *OPENSSL_secure_zalloc(size_t num); +\& void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); +\& +\& void OPENSSL_secure_free(void* ptr); +\& void CRYPTO_secure_free(void *ptr, const char *, int); +\& +\& void OPENSSL_secure_clear_free(void* ptr, size_t num); +\& void CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int); +\& +\& size_t OPENSSL_secure_actual_size(const void *ptr); +\& +\& int CRYPTO_secure_allocated(const void *ptr); +\& size_t CRYPTO_secure_used(); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In order to help protect applications (particularly long\-running servers) +from pointer overruns or underruns that could return arbitrary data from +the program\*(Aqs dynamic memory area, where keys and other sensitive +information might be stored, OpenSSL supports the concept of a "secure heap." +The level and type of security guarantees depend on the operating system. +It is a good idea to review the code and see if it addresses your +threat model and concerns. It should be noted that the secure heap +uses a single read/write lock, and therefore any operations +that involve allocation or freeing of secure heap memory are serialised, +blocking other threads. With that in mind, highly concurrent applications +should enable the secure heap with caution and be aware of the performance +implications for multi\-threaded code. +.PP +If a secure heap is used, then private key \fBBIGNUM\fR values are stored there. +This protects long\-term storage of private keys, but will not necessarily +put all intermediate values and computations there. +.PP +\&\fBCRYPTO_secure_malloc_init()\fR creates the secure heap, with the specified +\&\f(CW\*(C`size\*(C'\fR in bytes. The \f(CW\*(C`minsize\*(C'\fR parameter is the minimum size to +allocate from the heap or zero to use a reasonable default value. +Both \f(CW\*(C`size\*(C'\fR and, if specified, \f(CW\*(C`minsize\*(C'\fR must be a power of two and +\&\f(CW\*(C`minsize\*(C'\fR should generally be small, for example 16 or 32. +\&\f(CW\*(C`minsize\*(C'\fR must be less than a quarter of \f(CW\*(C`size\*(C'\fR in any case. +.PP +\&\fBCRYPTO_secure_malloc_initialized()\fR indicates whether or not the secure +heap as been initialized and is available. +.PP +\&\fBCRYPTO_secure_malloc_done()\fR releases the heap and makes the memory unavailable +to the process if all secure memory has been freed. +It can take noticeably long to complete. +.PP +\&\fBOPENSSL_secure_malloc()\fR allocates \f(CW\*(C`num\*(C'\fR bytes from the heap. +If \fBCRYPTO_secure_malloc_init()\fR is not called, this is equivalent to +calling \fBOPENSSL_malloc()\fR. +It is a macro that expands to +\&\fBCRYPTO_secure_malloc()\fR and adds the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR parameters. +.PP +\&\fBOPENSSL_secure_zalloc()\fR and \fBCRYPTO_secure_zalloc()\fR are like +\&\fBOPENSSL_secure_malloc()\fR and \fBCRYPTO_secure_malloc()\fR, respectively, +except that they call \fBmemset()\fR to zero the memory before returning. +.PP +\&\fBOPENSSL_secure_free()\fR releases the memory at \f(CW\*(C`ptr\*(C'\fR back to the heap. +It must be called with a value previously obtained from +\&\fBOPENSSL_secure_malloc()\fR. +If \fBCRYPTO_secure_malloc_init()\fR is not called, this is equivalent to +calling \fBOPENSSL_free()\fR. +It exists for consistency with \fBOPENSSL_secure_malloc()\fR , and +is a macro that expands to \fBCRYPTO_secure_free()\fR and adds the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR +and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR parameters.. If the argument to \fBOPENSSL_secure_free()\fR +is NULL, nothing is done. +.PP +\&\fBOPENSSL_secure_clear_free()\fR is similar to \fBOPENSSL_secure_free()\fR except +that it has an additional \f(CW\*(C`num\*(C'\fR parameter which is used to clear +the memory if it was not allocated from the secure heap. +If \fBCRYPTO_secure_malloc_init()\fR is not called, this is equivalent to +calling \fBOPENSSL_clear_free()\fR. If the argument to \fBOPENSSL_secure_clear_free()\fR +is NULL, nothing is done. +.PP +\&\fBOPENSSL_secure_actual_size()\fR tells the actual size allocated to the +pointer; implementations may allocate more space than initially +requested, in order to "round up" and reduce secure heap fragmentation. +.PP +\&\fBOPENSSL_secure_allocated()\fR tells if a pointer is allocated in the secure heap. +.PP +\&\fBCRYPTO_secure_used()\fR returns the number of bytes allocated in the +secure heap. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBCRYPTO_secure_malloc_init()\fR returns 0 on failure, 1 if successful, +and 2 if successful but the heap could not be protected by memory +mapping. +.PP +\&\fBCRYPTO_secure_malloc_initialized()\fR returns 1 if the secure heap is +available (that is, if \fBCRYPTO_secure_malloc_init()\fR has been called, +but \fBCRYPTO_secure_malloc_done()\fR has not been called or failed) or 0 if not. +.PP +\&\fBOPENSSL_secure_malloc()\fR and \fBOPENSSL_secure_zalloc()\fR return a pointer into +the secure heap of the requested size, or \f(CW\*(C`NULL\*(C'\fR if memory could not be +allocated. +.PP +\&\fBCRYPTO_secure_allocated()\fR returns 1 if the pointer is in the secure heap, or 0 if not. +.PP +\&\fBCRYPTO_secure_malloc_done()\fR returns 1 if the secure memory area is released, or 0 if not. +.PP +\&\fBOPENSSL_secure_free()\fR and \fBOPENSSL_secure_clear_free()\fR return no values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_malloc\fR\|(3), +\&\fBBN_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOPENSSL_secure_clear_free()\fR function was added in OpenSSL 1.1.0g. +.PP +The second argument to \fBCRYPTO_secure_malloc_init()\fR was changed from an \fBint\fR to +a \fBsize_t\fR in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OPENSSL_strcasecmp.3 b/static/netbsd/man3/OPENSSL_strcasecmp.3 new file mode 100644 index 00000000..b7b9d1a8 --- /dev/null +++ b/static/netbsd/man3/OPENSSL_strcasecmp.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: OPENSSL_strcasecmp.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_strcasecmp 3" +.TH OPENSSL_strcasecmp 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_strcasecmp, OPENSSL_strncasecmp \- compare two strings ignoring case +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OPENSSL_strcasecmp(const char *s1, const char *s2); +\& int OPENSSL_strncasecmp(const char *s1, const char *s2, size_t n); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The OPENSSL_strcasecmp function performs a byte\-by\-byte comparison of the strings +\&\fBs1\fR and \fBs2\fR, ignoring the case of the characters. +.PP +The OPENSSL_strncasecmp function is similar, except that it compares no more than +\&\fBn\fR bytes of \fBs1\fR and \fBs2\fR. +.PP +In POSIX\-compatible system and on Windows these functions use "C" locale for +case insensitive. Otherwise the comparison is done in current locale. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Both functions return an integer less than, equal to, or greater than zero if +s1 is found, respectively, to be less than, to match, or be greater than s2. +.SH NOTES +.IX Header "NOTES" +OpenSSL extensively uses case insensitive comparison of ASCII strings. Though +OpenSSL itself is locale\-agnostic, the applications using OpenSSL libraries may +unpredictably suffer when they use localization (e.g. Turkish locale is +well\-known with a specific I/i cases). These functions use C locale for string +comparison. +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ALGORITHM.3 b/static/netbsd/man3/OSSL_ALGORITHM.3 new file mode 100644 index 00000000..3baee7ad --- /dev/null +++ b/static/netbsd/man3/OSSL_ALGORITHM.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: OSSL_ALGORITHM.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ALGORITHM 3" +.TH OSSL_ALGORITHM 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ALGORITHM \- OpenSSL Core type to define a fetchable algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_algorithm_st OSSL_ALGORITHM; +\& struct ossl_algorithm_st { +\& const char *algorithm_names; /* key */ +\& const char *property_definition; /* key */ +\& const OSSL_DISPATCH *implementation; +\& const char *algorithm_description; +\& }; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBOSSL_ALGORITHM\fR type is a \fIpublic structure\fR that describes an +algorithm that a \fBprovider\fR\|(7) provides. Arrays of this type are returned +by providers on demand from the OpenSSL libraries to describe what +algorithms the providers provide implementations of, and with what +properties. +.PP +Arrays of this type must be terminated with a tuple where \fIalgorithm_names\fR +is NULL. +.PP +This type of array is typically returned by the provider\*(Aqs operation querying +function, further described in "Provider Functions" in \fBprovider\-base\fR\|(7). +.SS "\fBOSSL_ALGORITHM\fP fields" +.IX Subsection "OSSL_ALGORITHM fields" +.IP \fIalgorithm_names\fR 4 +.IX Item "algorithm_names" +This string is a colon separated set of names / identities, and is used by +the appropriate fetching functionality (such as \fBEVP_CIPHER_fetch\fR\|(3), +\&\fBEVP_MD_fetch\fR\|(3), etc) to find the desired algorithm. +.Sp +Multiple names / identities allow a specific algorithm implementation to be +fetched multiple ways. For example, the RSA algorithm has the following +known identities: +.RS 4 +.IP \(bu 4 +\&\f(CW\*(C`RSA\*(C'\fR +.IP \(bu 4 +\&\f(CW\*(C`rsaEncryption\*(C'\fR +.Sp +This is the name of the algorithm\*(Aqs OBJECT IDENTIFIER (OID), as given by the +PKCS#1 RFC\*(Aqs ASN.1 module +.IP \(bu 4 +\&\f(CW1.2.840.113549.1.1.1\fR +.Sp +This is the OID itself for \f(CW\*(C`rsaEncryption\*(C'\fR, in canonical decimal text form. +.RE +.RS 4 +.Sp +The resulting \fIalgorithm_names\fR string would look like this: +.Sp +.Vb 1 +\& "RSA:rsaEncryption:1.2.840.113549.1.1.1" +.Ve +.Sp +The OpenSSL libraries use the first of the algorithm names as the main +or canonical name, on a per algorithm implementation basis. +.Sp +See the notes "On the subject of algorithm names" below for a more in +depth discussion on \fIalgorithm_names\fR and how that may interact with +applications and libraries, including OpenSSL\*(Aqs. +.RE +.IP \fIproperty_definition\fR 4 +.IX Item "property_definition" +This string defines a set of properties associated with a particular +algorithm implementation, and is used by the appropriate fetching +functionality (such as \fBEVP_CIPHER_fetch\fR\|(3), \fBEVP_MD_fetch\fR\|(3), etc) for +a finer grained lookup of an algorithm implementation, which is useful in +case multiple implementations of the same algorithm are available. +.Sp +See \fBproperty\fR\|(7) for a further description of the contents of this +string. +.IP \fIimplementation\fR 4 +.IX Item "implementation" +Pointer to an \fBOSSL_DISPATCH\fR\|(3) array, containing pointers to the +functions of a particular algorithm implementation. +.IP \fIalgorithm_description\fR 4 +.IX Item "algorithm_description" +A string with a short human\-readable description of the algorithm. +.SH NOTES +.IX Header "NOTES" +.SS "On the subject of algorithm names" +.IX Subsection "On the subject of algorithm names" +Providers may find the need to register ASN.1 OIDs for algorithms using +\&\fBOBJ_create\fR\|(3) (via the \fBcore_obj_create\fR upcall described in +\&\fBprovider\-base\fR\|(7), because some application or library \-\- possibly still +the OpenSSL libraries, even \-\- use NIDs to look up algorithms. +.PP +In that scenario, you must make sure that the corresponding \fBOSSL_ALGORITHM\fR\*(Aqs +\&\fIalgorithm_names\fR includes both the short and the long name. +.PP +Most of the time, registering ASN.1 OIDs like this shouldn\*(Aqt be necessary, +and applications and libraries are encouraged to use \fBOBJ_obj2txt\fR\|(3) to +get a text representation of the OID, which may be a long or short name for +OIDs that are registered, or the OID itself in canonical decimal text form +if not (or if \fBOBJ_obj2txt\fR\|(3) is called with \fIno_name\fR = 1). +.PP +It\*(Aqs recommended to make sure that the corresponding \fBOSSL_ALGORITHM\fR\*(Aqs +\&\fIalgorithm_names\fR include known names as well as the OID itself in +canonical decimal text form. That should cover all scenarios. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBprovider\-base\fR\|(7), \fBopenssl\-core.h\fR\|(7), +\&\fBopenssl\-core_dispatch.h\fR\|(7), \fBOSSL_DISPATCH\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_ALGORITHM\fR was added in OpenSSL 3.0 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CALLBACK.3 b/static/netbsd/man3/OSSL_CALLBACK.3 new file mode 100644 index 00000000..eed99ee0 --- /dev/null +++ b/static/netbsd/man3/OSSL_CALLBACK.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: OSSL_CALLBACK.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CALLBACK 3" +.TH OSSL_CALLBACK 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK \- OpenSSL Core type to define callbacks +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 6 +\& #include +\& typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); +\& typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, +\& size_t *pass_len, +\& const OSSL_PARAM params[], +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For certain events or activities, provider functionality may need help from +the application or the calling OpenSSL libraries themselves. For example, +user input or direct (possibly optional) user output could be implemented +this way. +.PP +Callback functions themselves are always provided by or through the calling +OpenSSL libraries, along with a generic pointer to data \fIarg\fR. As far as +the function receiving the pointer to the function pointer and \fIarg\fR is +concerned, the data that \fIarg\fR points at is opaque, and the pointer should +simply be passed back to the callback function when it\*(Aqs called. +.IP \fBOSSL_CALLBACK\fR 4 +.IX Item "OSSL_CALLBACK" +This is a generic callback function. When calling this callback function, +the caller is expected to build an \fBOSSL_PARAM\fR\|(3) array of data it wants or +is expected to pass back, and pass that as \fIparams\fR, as well as the opaque +data pointer it received, as \fIarg\fR. +.IP \fBOSSL_PASSPHRASE_CALLBACK\fR 4 +.IX Item "OSSL_PASSPHRASE_CALLBACK" +This is a specialised callback function, used specifically to prompt the +user for a passphrase. When calling this callback function, a buffer to +store the pass phrase needs to be given with \fIpass\fR, and its size with +\&\fIpass_size\fR. The length of the prompted pass phrase will be given back in +\&\fI*pass_len\fR. +.Sp +Additional parameters can be passed with the \fBOSSL_PARAM\fR\|(3) array \fIparams\fR, +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Functions of type \fBOSSL_CALLBACK\fR and \fBOSSL_PASSPHRASE_CALLBACK\fR +must return 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The types described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CIPHER_ALGORITHM.3 b/static/netbsd/man3/OSSL_CIPHER_ALGORITHM.3 new file mode 100644 index 00000000..d53f43d9 --- /dev/null +++ b/static/netbsd/man3/OSSL_CIPHER_ALGORITHM.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: OSSL_CIPHER_ALGORITHM.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/OSSL_CMP_ATAV_set0.3 b/static/netbsd/man3/OSSL_CMP_ATAV_set0.3 new file mode 100644 index 00000000..cb1a2823 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_ATAV_set0.3 @@ -0,0 +1,175 @@ +.\" $NetBSD: OSSL_CMP_ATAV_set0.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_ATAV_set0 3" +.TH OSSL_CMP_ATAV_set0 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_ATAV, +OSSL_CMP_ATAV_create, +OSSL_CMP_ATAV_set0, +OSSL_CMP_ATAV_get0_type, +OSSL_CMP_ATAV_get0_value, +OSSL_CMP_ATAV_new_algId, +OSSL_CMP_ATAV_get0_algId, +OSSL_CMP_ATAV_new_rsaKeyLen, +OSSL_CMP_ATAV_get_rsaKeyLen, +OSSL_CMP_ATAVS, +OSSL_CMP_ATAV_push1, +OSSL_CMP_ATAV_free +\&\- OSSL_CMP_ATAV utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef OSSL_CRMF_ATTRIBUTETYPEANDVALUE OSSL_CMP_ATAV; +\& OSSL_CMP_ATAV *OSSL_CMP_ATAV_create(ASN1_OBJECT *type, ASN1_TYPE *value); +\& void OSSL_CMP_ATAV_set0(OSSL_CMP_ATAV *atav, ASN1_OBJECT *type, +\& ASN1_TYPE *value); +\& ASN1_OBJECT *OSSL_CMP_ATAV_get0_type(const OSSL_CMP_ATAV *atav); +\& ASN1_TYPE *OSSL_CMP_ATAV_get0_value(const OSSL_CMP_ATAV *atav); +\& +\& OSSL_CMP_ATAV *OSSL_CMP_ATAV_new_algId(const X509_ALGOR *alg); +\& X509_ALGOR *OSSL_CMP_ATAV_get0_algId(const OSSL_CMP_ATAV *atav); +\& OSSL_CMP_ATAV *OSSL_CMP_ATAV_new_rsaKeyLen(int len); +\& int OSSL_CMP_ATAV_get_rsaKeyLen(const OSSL_CMP_ATAV *atav); +\& +\& typedef STACK_OF(OSSL_CRMF_ATTRIBUTETYPEANDVALUE) OSSL_CMP_ATAVS; +\& int OSSL_CMP_ATAV_push1(OSSL_CMP_ATAVS **sk_p, const OSSL_CMP_ATAV *atav); +\& void OSSL_CMP_ATAV_free(OSSL_CMP_ATAV *atav); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CMP_ATAV\fR is a short hand of \fBOSSL_CRMF_ATTRIBUTETYPEANDVALUE\fR, +defined in RFC 4211 Appendix B. +It is typically used in CertRequest structures, +but also in CertReqTemplateContent structures for key specifications. +.PP +\&\fBOSSL_CMP_ATAV_create()\fR creates a new \fBOSSL_CMP_ATAV\fR structure and fills it in. +It combines \fBOSSL_CMP_ATAV_new()\fR and \fBOSSL_CMP_ATAV_set0()\fR. +.PP +\&\fBOSSL_CMP_ATAV_set0()\fR sets the \fIatav\fR with an infoType of \fItype\fR and an +infoValue of \fIvalue\fR. +The pointers \fItype\fR and \fIvalue\fR may be NULL, otherwise +they must \fBnot\fR be freed up after the call because their ownership +is transferred to \fIatav\fR. The \fIitav\fR pointer must not be NULL. +.PP +\&\fBOSSL_CMP_ATAV_get0_type()\fR returns a direct pointer to the infoType +in the \fIatav\fR unless it is NULL. +.PP +\&\fBOSSL_CMP_ATAV_get0_value()\fR returns a direct pointer to the infoValue +in the \fIatav\fR as generic \fBASN1_TYPE\fR pointer unless \fIatav\fR is NULL. +.PP +\&\fBOSSL_CMP_ATAV_new_algId()\fR creates a new \fBOSSL_CMP_ATAV\fR structure of type +\&\fBalgId\fR and fills it in with a copy of the given \fIalg\fR. +.PP +\&\fBOSSL_CMP_ATAV_get0_algId()\fR returns +a direct pointer to the algId infoValue in the \fIatav\fR of type \fBX509_ALGOR\fR +or NULL if \fIatav\fR is NULL or does not contain an algId. +.PP +\&\fBOSSL_CMP_ATAV_new_rsaKeyLen()\fR creates a new \fBOSSL_CMP_ATAV\fR structure of type +\&\fBrsaKeyLen\fR and fills it in with the given \fIlen\fR, which must be positive. +.PP +\&\fBOSSL_CMP_ATAV_get_rsaKeyLen()\fR returns +the RSA key length in rsaKeyLen infoValue in the \fIatav\fR, +\&\-1 if \fIatav\fR is NULL or does not contain an rsaKeyLen or cannot be parsed, +or \-2 if the value is less than 1 or is greater than INT_MAX. +.PP +\&\fBOSSL_CMP_ATAV_push1()\fR pushes a copy of \fIatav\fR to the stack of \fBOSSL_CMP_ATAV\fR +pointed to by \fI*sk_p\fR. It creates a new stack if \fI*sk_p\fR points to NULL. +.PP +\&\fBOSSL_CMP_ATAV_free()\fR deallocates \fIatav\fR. It is defined as a macro. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. CRMF is defined in RFC 4211. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_ATAV_create()\fR, +\&\fBOSSL_CMP_ATAV_new_algId()\fR, and \fBOSSL_CMP_ATAV_new_rsaKeyLen()\fR +return a pointer to the ATAV structure on success, or NULL on error. +.PP +\&\fBOSSL_CMP_ATAV_set0()\fR and \fBOSSL_CMP_ATAV_free()\fR do not return a value. +.PP +\&\fBOSSL_CMP_ATAV_get0_type()\fR, \fBOSSL_CMP_ATAV_get0_value()\fR, and +\&\fBOSSL_CMP_ATAV_get0_algId()\fR +return the respective pointer or NULL if their input is NULL. +.PP +\&\fBOSSL_CMP_ATAV_get_rsaKeyLen()\fR return a key length in bits or < 0 on error. +.PP +\&\fBOSSL_CMP_ATAV_push1()\fR returns 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_ITAV_new0_certReqTemplate\fR\|(3), \fBASN1_TYPE_set\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOSSL_CMP_ATAV\fR type and related functions were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_CTX_new.3 b/static/netbsd/man3/OSSL_CMP_CTX_new.3 new file mode 100644 index 00000000..9bd38e9e --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_CTX_new.3 @@ -0,0 +1,947 @@ +.\" $NetBSD: OSSL_CMP_CTX_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_CTX_new 3" +.TH OSSL_CMP_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_CTX_new, +OSSL_CMP_CTX_free, +OSSL_CMP_CTX_reinit, +OSSL_CMP_CTX_get0_libctx, OSSL_CMP_CTX_get0_propq, +OSSL_CMP_CTX_set_option, +OSSL_CMP_CTX_get_option, +OSSL_CMP_CTX_set_log_cb, +OSSL_CMP_CTX_set_log_verbosity, +OSSL_CMP_CTX_print_errors, +OSSL_CMP_CTX_set1_serverPath, +OSSL_CMP_CTX_set1_server, +OSSL_CMP_CTX_set_serverPort, +OSSL_CMP_CTX_set1_proxy, +OSSL_CMP_CTX_set1_no_proxy, +OSSL_CMP_CTX_set_http_cb, +OSSL_CMP_CTX_set_http_cb_arg, +OSSL_CMP_CTX_get_http_cb_arg, +OSSL_CMP_transfer_cb_t, +OSSL_CMP_CTX_set_transfer_cb, +OSSL_CMP_CTX_set_transfer_cb_arg, +OSSL_CMP_CTX_get_transfer_cb_arg, +OSSL_CMP_CTX_set1_srvCert, +OSSL_CMP_CTX_set1_expected_sender, +OSSL_CMP_CTX_set0_trusted, +OSSL_CMP_CTX_set0_trustedStore, +OSSL_CMP_CTX_get0_trusted, +OSSL_CMP_CTX_get0_trustedStore, +OSSL_CMP_CTX_set1_untrusted, +OSSL_CMP_CTX_get0_untrusted, +OSSL_CMP_CTX_set1_cert, +OSSL_CMP_CTX_build_cert_chain, +OSSL_CMP_CTX_set1_pkey, +OSSL_CMP_CTX_set1_referenceValue, +OSSL_CMP_CTX_set1_secretValue, +OSSL_CMP_CTX_set1_recipient, +OSSL_CMP_CTX_push0_geninfo_ITAV, +OSSL_CMP_CTX_reset_geninfo_ITAVs, +OSSL_CMP_CTX_get0_geninfo_ITAVs, +OSSL_CMP_CTX_set1_extraCertsOut, +OSSL_CMP_CTX_set0_newPkey, +OSSL_CMP_CTX_get0_newPkey, +OSSL_CMP_CTX_set1_issuer, +OSSL_CMP_CTX_set1_serialNumber, +OSSL_CMP_CTX_set1_subjectName, +OSSL_CMP_CTX_push1_subjectAltName, +OSSL_CMP_CTX_set0_reqExtensions, +OSSL_CMP_CTX_reqExtensions_have_SAN, +OSSL_CMP_CTX_push0_policy, +OSSL_CMP_CTX_set1_oldCert, +OSSL_CMP_CTX_set1_p10CSR, +OSSL_CMP_CTX_push0_genm_ITAV, +OSSL_CMP_certConf_cb_t, +OSSL_CMP_certConf_cb, +OSSL_CMP_CTX_set_certConf_cb, +OSSL_CMP_CTX_set_certConf_cb_arg, +OSSL_CMP_CTX_get_certConf_cb_arg, +OSSL_CMP_CTX_get_status, +OSSL_CMP_CTX_get0_statusString, +OSSL_CMP_CTX_get_failInfoCode, +OSSL_CMP_CTX_get0_validatedSrvCert, +OSSL_CMP_CTX_get0_newCert, +OSSL_CMP_CTX_get1_newChain, +OSSL_CMP_CTX_get1_caPubs, +OSSL_CMP_CTX_get1_extraCertsIn, +OSSL_CMP_CTX_set1_transactionID, +OSSL_CMP_CTX_set1_senderNonce +\&\- functions for managing the CMP client context data structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_CTX *OSSL_CMP_CTX_new(OSSL_LIB_CTX *libctx, const char *propq); +\& void OSSL_CMP_CTX_free(OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_reinit(OSSL_CMP_CTX *ctx); +\& OSSL_LIB_CTX *OSSL_CMP_CTX_get0_libctx(const OSSL_CMP_CTX *ctx); +\& const char *OSSL_CMP_CTX_get0_propq(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set_option(OSSL_CMP_CTX *ctx, int opt, int val); +\& int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt); +\& +\& /* logging and error reporting: */ +\& int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb); +\& #define OSSL_CMP_CTX_set_log_verbosity(ctx, level) +\& void OSSL_CMP_CTX_print_errors(const OSSL_CMP_CTX *ctx); +\& +\& /* message transfer: */ +\& int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path); +\& int OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address); +\& int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port); +\& int OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name); +\& int OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names); +\& int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb); +\& int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx); +\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx, +\& const OSSL_CMP_MSG *req); +\& int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx, +\& OSSL_CMP_transfer_cb_t cb); +\& int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx); +\& +\& /* server authentication: */ +\& int OSSL_CMP_CTX_set1_srvCert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_set1_expected_sender(OSSL_CMP_CTX *ctx, +\& const X509_NAME *name); +\& #define OSSL_CMP_CTX_set0_trusted OSSL_CMP_CTX_set0_trustedStore +\& int OSSL_CMP_CTX_set0_trustedStore(OSSL_CMP_CTX *ctx, X509_STORE *store); +\& #define OSSL_CMP_CTX_get0_trusted OSSL_CMP_CTX_get0_trustedStore +\& X509_STORE *OSSL_CMP_CTX_get0_trustedStore(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set1_untrusted(OSSL_CMP_CTX *ctx, STACK_OF(X509) *certs); +\& STACK_OF(X509) *OSSL_CMP_CTX_get0_untrusted(const OSSL_CMP_CTX *ctx); +\& +\& /* client authentication: */ +\& int OSSL_CMP_CTX_set1_cert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_build_cert_chain(OSSL_CMP_CTX *ctx, X509_STORE *own_trusted, +\& STACK_OF(X509) *candidates); +\& int OSSL_CMP_CTX_set1_pkey(OSSL_CMP_CTX *ctx, EVP_PKEY *pkey); +\& int OSSL_CMP_CTX_set1_referenceValue(OSSL_CMP_CTX *ctx, +\& const unsigned char *ref, int len); +\& int OSSL_CMP_CTX_set1_secretValue(OSSL_CMP_CTX *ctx, +\& const unsigned char *sec, int len); +\& +\& /* CMP message header and extra certificates: */ +\& int OSSL_CMP_CTX_set1_recipient(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_push0_geninfo_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); +\& int OSSL_CMP_CTX_reset_geninfo_ITAVs(OSSL_CMP_CTX *ctx); +\& STACK_OF(OSSL_CMP_ITAV) +\& *OSSL_CMP_CTX_get0_geninfo_ITAVs(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_set1_extraCertsOut(OSSL_CMP_CTX *ctx, +\& STACK_OF(X509) *extraCertsOut); +\& +\& /* certificate template: */ +\& int OSSL_CMP_CTX_set0_newPkey(OSSL_CMP_CTX *ctx, int priv, EVP_PKEY *pkey); +\& EVP_PKEY *OSSL_CMP_CTX_get0_newPkey(const OSSL_CMP_CTX *ctx, int priv); +\& int OSSL_CMP_CTX_set1_issuer(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_set1_serialNumber(OSSL_CMP_CTX *ctx, const ASN1_INTEGER *sn); +\& int OSSL_CMP_CTX_set1_subjectName(OSSL_CMP_CTX *ctx, const X509_NAME *name); +\& int OSSL_CMP_CTX_push1_subjectAltName(OSSL_CMP_CTX *ctx, +\& const GENERAL_NAME *name); +\& int OSSL_CMP_CTX_set0_reqExtensions(OSSL_CMP_CTX *ctx, X509_EXTENSIONS *exts); +\& int OSSL_CMP_CTX_reqExtensions_have_SAN(OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_push0_policy(OSSL_CMP_CTX *ctx, POLICYINFO *pinfo); +\& int OSSL_CMP_CTX_set1_oldCert(OSSL_CMP_CTX *ctx, X509 *cert); +\& int OSSL_CMP_CTX_set1_p10CSR(OSSL_CMP_CTX *ctx, const X509_REQ *csr); +\& +\& /* misc body contents: */ +\& int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav); +\& +\& /* certificate confirmation: */ +\& typedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert, +\& int fail_info, const char **txt); +\& int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info, +\& const char **text); +\& int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb); +\& int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg); +\& void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx); +\& +\& /* result fetching: */ +\& int OSSL_CMP_CTX_get_status(const OSSL_CMP_CTX *ctx); +\& OSSL_CMP_PKIFREETEXT *OSSL_CMP_CTX_get0_statusString(const OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_CTX_get_failInfoCode(const OSSL_CMP_CTX *ctx); +\& +\& X509 *OSSL_CMP_CTX_get0_validatedSrvCert(const OSSL_CMP_CTX *ctx); +\& X509 *OSSL_CMP_CTX_get0_newCert(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_newChain(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx); +\& STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx); +\& +\& /* for testing and debugging purposes: */ +\& int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx, +\& const ASN1_OCTET_STRING *id); +\& int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx, +\& const ASN1_OCTET_STRING *nonce); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is the context API for using CMP (Certificate Management Protocol) with +OpenSSL. +.PP +\&\fBOSSL_CMP_CTX_new()\fR allocates an \fBOSSL_CMP_CTX\fR structure associated with +the library context \fIlibctx\fR and property query string \fIpropq\fR, +both of which may be NULL to select the defaults. +It initializes the remaining fields to their default values \- for instance, +the logging verbosity is set to OSSL_CMP_LOG_INFO, +the message timeout is set to 120 seconds, +and the proof\-of\-possession method is set to OSSL_CRMF_POPO_SIGNATURE. +.PP +\&\fBOSSL_CMP_CTX_free()\fR deallocates an OSSL_CMP_CTX structure. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_CMP_CTX_reinit()\fR prepares the given \fIctx\fR for a further transaction by +clearing the internal CMP transaction (aka session) status, PKIStatusInfo, +and any previous results (newCert, newChain, caPubs, and extraCertsIn) +from the last executed transaction. +It also clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_genm_ITAV()\fR. +All other field values (i.e., CMP options) are retained for potential reuse. +.PP +\&\fBOSSL_CMP_CTX_get0_libctx()\fR returns the \fIlibctx\fR argument that was used +when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. +.PP +\&\fBOSSL_CMP_CTX_get0_propq()\fR returns the \fIpropq\fR argument that was used +when constructing \fIctx\fR with \fBOSSL_CMP_CTX_new()\fR, which may be NULL. +.PP +\&\fBOSSL_CMP_CTX_set_option()\fR sets the given value for the given option +(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure. +.PP +The following options can be set: +.IP \fBOSSL_CMP_OPT_LOG_VERBOSITY\fR 4 +.IX Item "OSSL_CMP_OPT_LOG_VERBOSITY" +The level of severity needed for actually outputting log messages +due to errors, warnings, general info, debugging, etc. +Default is OSSL_CMP_LOG_INFO. See also \fBOSSL_CMP_log_open\fR\|(3). +.IP \fBOSSL_CMP_OPT_KEEP_ALIVE\fR 4 +.IX Item "OSSL_CMP_OPT_KEEP_ALIVE" +If the given value is 0 then HTTP connections are not kept open +after receiving a response, which is the default behavior for HTTP 1.0. +If the value is 1 or 2 then persistent connections are requested. +If the value is 2 then persistent connections are required, +i.e., in case the server does not grant them an error occurs. +The default value is 1: prefer to keep the connection open. +.IP \fBOSSL_CMP_OPT_MSG_TIMEOUT\fR 4 +.IX Item "OSSL_CMP_OPT_MSG_TIMEOUT" +Number of seconds a CMP request\-response message round trip +is allowed to take before a timeout error is returned. +A value <= 0 means no limitation (waiting indefinitely). +Default is to use the \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR setting. +.IP \fBOSSL_CMP_OPT_TOTAL_TIMEOUT\fR 4 +.IX Item "OSSL_CMP_OPT_TOTAL_TIMEOUT" +Maximum total number of seconds a transaction may take, +including polling etc. +A value <= 0 means no limitation (waiting indefinitely). +Default is 0. +.IP \fBOSSL_CMP_OPT_USE_TLS\fR 4 +.IX Item "OSSL_CMP_OPT_USE_TLS" +Use this option to indicate to the HTTP implementation +whether TLS is going to be used for the connection (resulting in HTTPS). +The value 1 indicates that TLS is used for client\-side HTTP connections, +which needs to be implemented via a callback function set by +\&\fBOSSL_CMP_CTX_set_http_cb()\fR. +The value 0 indicates that TLS is not used. +Default is \-1 for backward compatibility: TLS is used by the client side +if and only if \fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets a non\-NULL \fIarg\fR. +.IP \fBOSSL_CMP_OPT_VALIDITY_DAYS\fR 4 +.IX Item "OSSL_CMP_OPT_VALIDITY_DAYS" +Number of days new certificates are asked to be valid for. +.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR 4 +.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT" +Do not take default Subject Alternative Names +from the reference certificate. +.IP \fBOSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL\fR 4 +.IX Item "OSSL_CMP_OPT_SUBJECTALTNAME_CRITICAL" +Demand that the given Subject Alternative Names are flagged as critical. +.IP \fBOSSL_CMP_OPT_POLICIES_CRITICAL\fR 4 +.IX Item "OSSL_CMP_OPT_POLICIES_CRITICAL" +Demand that the given policies are flagged as critical. +.IP \fBOSSL_CMP_OPT_POPO_METHOD\fR 4 +.IX Item "OSSL_CMP_OPT_POPO_METHOD" +Select the proof of possession method to use. Possible values are: +.Sp +.Vb 8 +\& OSSL_CRMF_POPO_NONE \- ProofOfPossession field omitted, +\& which implies central key generation +\& OSSL_CRMF_POPO_RAVERIFIED \- assert that the RA has already +\& verified the PoPo +\& OSSL_CRMF_POPO_SIGNATURE \- sign a value with private key, +\& which is the default. +\& OSSL_CRMF_POPO_KEYENC \- decrypt the encrypted certificate +\& ("indirect method") +.Ve +.Sp +Note that a signature\-based POPO can only be produced if a private key +is provided as the newPkey or client\*(Aqs pkey component of the CMP context. +.IP \fBOSSL_CMP_OPT_DIGEST_ALGNID\fR 4 +.IX Item "OSSL_CMP_OPT_DIGEST_ALGNID" +The NID of the digest algorithm to be used in RFC 9810\*(Aqs MSG_SIG_ALG +for signature\-based message protection and Proof\-of\-Possession (POPO). +Default is SHA256. +.IP "\fBOSSL_CMP_OPT_OWF_ALGNID\fR The NID of the digest algorithm to be used as one\-way function (OWF) for MAC\-based message protection with password\-based MAC (PBM). See RFC 9810 section 5.1.3.1 for details. Default is SHA256." 4 +.IX Item "OSSL_CMP_OPT_OWF_ALGNID The NID of the digest algorithm to be used as one-way function (OWF) for MAC-based message protection with password-based MAC (PBM). See RFC 9810 section 5.1.3.1 for details. Default is SHA256." +.PD 0 +.IP "\fBOSSL_CMP_OPT_MAC_ALGNID\fR The NID of the MAC algorithm to be used for message protection with PBM. Default is HMAC\-SHA1, for backward compatibility with RFC 4210." 4 +.IX Item "OSSL_CMP_OPT_MAC_ALGNID The NID of the MAC algorithm to be used for message protection with PBM. Default is HMAC-SHA1, for backward compatibility with RFC 4210." +.IP \fBOSSL_CMP_OPT_REVOCATION_REASON\fR 4 +.IX Item "OSSL_CMP_OPT_REVOCATION_REASON" +.PD +The reason code to be included in a Revocation Request (RR); +values: 0..10 (RFC 5210, 5.3.1) or \-1 for none, which is the default. +.IP \fBOSSL_CMP_OPT_IMPLICIT_CONFIRM\fR 4 +.IX Item "OSSL_CMP_OPT_IMPLICIT_CONFIRM" +Request server to enable implicit confirm mode, where the client +does not need to send confirmation upon receiving the +certificate. If the server does not enable implicit confirmation +in the return message, then confirmation is sent anyway. +.IP \fBOSSL_CMP_OPT_DISABLE_CONFIRM\fR 4 +.IX Item "OSSL_CMP_OPT_DISABLE_CONFIRM" +Do not confirm enrolled certificates, to cope with broken servers +not supporting implicit confirmation correctly. +\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant +exclusively to allow interoperability with server implementations violating +RFC 9810. +.IP \fBOSSL_CMP_OPT_UNPROTECTED_SEND\fR 4 +.IX Item "OSSL_CMP_OPT_UNPROTECTED_SEND" +Send request or response messages without CMP\-level protection. +.IP \fBOSSL_CMP_OPT_UNPROTECTED_ERRORS\fR 4 +.IX Item "OSSL_CMP_OPT_UNPROTECTED_ERRORS" +Accept unprotected error responses which are either explicitly +unprotected or where protection verification failed. Applies to regular +error messages as well as certificate responses (IP/CP/KUP) and +revocation responses (RP) with rejection. +\&\fBWARNING:\fR This setting leads to unspecified behavior and it is meant +exclusively to allow interoperability with server implementations violating +RFC 9810. +.IP \fBOSSL_CMP_OPT_IGNORE_KEYUSAGE\fR 4 +.IX Item "OSSL_CMP_OPT_IGNORE_KEYUSAGE" +Ignore key usage restrictions in the signer\*(Aqs certificate when +validating signature\-based protection in received CMP messages. +Else, \*(AqdigitalSignature\*(Aq must be allowed by CMP signer certificates. +.IP \fBOSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR\fR 4 +.IX Item "OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR" +Allow retrieving a trust anchor from extraCerts and using that +to validate the certificate chain of an IP message. +This is a quirk option added to support 3GPP TS 33.310. +.Sp +Note that using this option is dangerous as the certificate obtained +this way has not been authenticated (at least not at CMP level). +Taking it over as a trust anchor implements trust\-on\-first\-use (TOFU). +.IP \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR 4 +.IX Item "OSSL_CMP_OPT_NO_CACHE_EXTRACERTS" +Do not cache certificates received in the extraCerts CMP message field. +Otherwise they are stored to potentially help validate further messages. +.Sp +In any case, after successfully validating an incoming message, its protection +certificate (if any) is cached for reuse with validation of subsequent messages. +This is done not only for efficiency but also +to eliminate the need for the sender to include its certificate and related chain +in the extraCerts field of subsequent messages of the same transaction. +.PP +\&\fBOSSL_CMP_CTX_get_option()\fR reads the current value of the given option +(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) from the given OSSL_CMP_CTX structure. +.PP +\&\fBOSSL_CMP_CTX_set_log_cb()\fR sets in \fIctx\fR the callback function \fIcb\fR +for handling error queue entries and logging messages. +When \fIcb\fR is NULL errors are printed to STDERR (if available, else ignored) +any log messages are ignored. +Alternatively, \fBOSSL_CMP_log_open\fR\|(3) may be used to direct logging to STDOUT. +.PP +\&\fBOSSL_CMP_CTX_set_log_verbosity()\fR is a macro setting the +OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level. +.PP +\&\fBOSSL_CMP_CTX_print_errors()\fR outputs any entries in the OpenSSL error queue. It +is similar to \fBERR_print_errors_cb\fR\|(3) but uses the CMP log callback function +if set in the \fIctx\fR for uniformity with CMP logging if given. Otherwise it uses +\&\fBERR_print_errors\fR\|(3) to print to STDERR (unless OPENSSL_NO_STDIO is defined). +.PP +\&\fBOSSL_CMP_CTX_set1_serverPath()\fR sets the HTTP path of the CMP server on the host, +also known as "CMP alias". +The default is \f(CW\*(C`/\*(C'\fR. +.PP +\&\fBOSSL_CMP_CTX_set1_server()\fR sets the given server \fIaddress\fR +(which may be a hostname or IP address or NULL) in the given \fIctx\fR. +If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non\-NULL argument, +this server address information is used for diagnostic output only. +.PP +\&\fBOSSL_CMP_CTX_set_serverPort()\fR sets the port of the CMP server to connect to. +If not used or the \fIport\fR argument is 0 +the default port applies, which is 80 for HTTP and 443 for HTTPS. +If \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR sets a non\-NULL argument, +this server port information is used for diagnostic output only. +.PP +\&\fBOSSL_CMP_CTX_set1_proxy()\fR sets the HTTP proxy to be used for connecting to +the given CMP server unless overruled by any "no_proxy" settings (see below). +If TLS is not used this defaults to the value of +the environment variable \f(CW\*(C`http_proxy\*(C'\fR if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR. +Otherwise defaults to the value of \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR. +An empty proxy string specifies not to use a proxy. +Otherwise the format is +\&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR, +where any given userinfo, path, query, and fragment is ignored. +If the host string is an IPv6 address, it must be enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +The default port number is 80, or 443 in case \f(CW\*(C`https:\*(C'\fR is given. +.PP +\&\fBOSSL_CMP_CTX_set1_no_proxy()\fR sets the list of server hostnames not to use +an HTTP proxy for. The names may be separated by commas and/or whitespace. +Defaults to the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR. +.PP +\&\fBOSSL_CMP_CTX_set_http_cb()\fR sets the optional BIO connect/disconnect callback +function, which has the prototype +.PP +.Vb 1 +\& typedef BIO *(*HTTP_bio_cb_t) (BIO *bio, void *arg, int connect, int detail); +.Ve +.PP +The callback may modify the \fIbio\fR provided by \fBOSSL_CMP_MSG_http_perform\fR\|(3) +as described for the \fIbio_update_fn\fR parameter of \fBOSSL_HTTP_open\fR\|(3). +The callback may make use of a custom defined argument \fIarg\fR, +as described for the \fIarg\fR parameter of \fBOSSL_HTTP_open\fR\|(3). +The argument is stored in the OSSL_CMP_CTX using \fBOSSL_CMP_CTX_set_http_cb_arg()\fR. +See also the \fBOSSL_CMP_OPT_USE_TLS\fR option described above. +.PP +\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR sets the argument, respectively a pointer to +a structure containing arguments such as an \fBSSL_CTX\fR structure, +optionally to be used by the http connect/disconnect callback function. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +If a non\-NULL argument is set, it is an error to use \fBOSSL_CMP_CTX_set1_proxy()\fR +or \fBOSSL_CMP_CTX_set1_no_proxy()\fR for setting non\-NULL strings. +.PP +\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR gets the argument, respectively the pointer to a +structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_http_cb_arg()\fR or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_set_transfer_cb()\fR sets the message transfer callback function, +which has the type +.PP +.Vb 2 +\& typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx, +\& const OSSL_CMP_MSG *req); +.Ve +.PP +Default is NULL, which implies the use of \fBOSSL_CMP_MSG_http_perform\fR\|(3). +The callback should send the CMP request message it obtains via the \fIreq\fR +parameter and on success return the response, else it must return NULL. +The transfer callback may make use of a custom defined argument stored in +the ctx by means of \fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR, which may be retrieved +again through \fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR. +.PP +\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR sets an argument, respectively a pointer to a +structure containing arguments, optionally to be used by the transfer callback. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR gets the argument, respectively the pointer +to a structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_transfer_cb_arg()\fR or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_srvCert()\fR sets the expected server cert in \fIctx\fR and trusts +it directly (even if it is expired) when verifying signed response messages. +This pins the accepted CMP server +and results in ignoring whatever may be set using \fBOSSL_CMP_CTX_set0_trusted()\fR. +Any previously set value is freed. +The \fIcert\fR argument may be NULL to clear the entry. +If set, the subject of the certificate is also used +as default value for the recipient of CMP requests +and as default value for the expected sender of CMP responses. +.PP +\&\fBOSSL_CMP_CTX_set1_expected_sender()\fR sets the Distinguished Name (DN) +expected in the sender field of incoming CMP messages. +Defaults to the subject of the pinned server certificate, if any. +This can be used to make sure that only a particular entity is accepted as +CMP message signer, and attackers are not able to use arbitrary certificates +of a trusted PKI hierarchy to fraudulently pose as CMP server. +Note that this gives slightly more freedom than \fBOSSL_CMP_CTX_set1_srvCert()\fR, +which pins the server to the holder of a particular certificate, while the +expected sender name will continue to match after updates of the server cert. +.PP +\&\fBOSSL_CMP_CTX_set0_trusted()\fR is an alias of the original +\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR. +It sets in the CMP context \fIctx\fR the certificate store of type X509_STORE +containing trusted certificates, typically of root CAs. +This is ignored when a certificate is pinned using \fBOSSL_CMP_CTX_set1_srvCert()\fR. +The store may also hold CRLs and a certificate verification callback function +used for signature\-based peer authentication. +Any store entry already set before is freed. +When given a NULL parameter the entry is cleared. +.PP +\&\fBOSSL_CMP_CTX_get0_trusted()\fR is an alias of the original +\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR. +It extracts from the CMP context \fIctx\fR the pointer to the currently set +certificate store containing trust anchors etc., or an empty store if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_untrusted()\fR sets up a list of non\-trusted certificates +of intermediate CAs that may be useful for path construction for the own CMP +signer certificate, for the own TLS certificate (if any), when verifying peer +CMP protection certificates, and when verifying newly enrolled certificates. +The reference counts of those certificates handled successfully are increased. +This list of untrusted certificates in \fIctx\fR will get augmented by extraCerts +in received CMP messages unless \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR is set. +.PP +\&\fBOSSL_CMP_CTX_get0_untrusted()\fR returns a pointer to the +list of untrusted certs in \fIctx\fR, which may be empty if unset. +.PP +\&\fBOSSL_CMP_CTX_set1_cert()\fR sets the CMP \fIsigner certificate\fR, +also called \fIprotection certificate\fR, +related to the private key used for signature\-based CMP message protection. +Therefore the public key of this \fIcert\fR must correspond to +the private key set before or thereafter via \fBOSSL_CMP_CTX_set1_pkey()\fR. +When using signature\-based protection of CMP request messages +this CMP signer certificate will be included first in the extraCerts field. +It serves as fallback reference certificate, see \fBOSSL_CMP_CTX_set1_oldCert()\fR. +The subject of this \fIcert\fR will be used as the sender field of outgoing +messages, while the subject of any cert set via \fBOSSL_CMP_CTX_set1_oldCert()\fR, +the subject of any PKCS#10 CSR set via \fBOSSL_CMP_CTX_set1_p10CSR()\fR, +and any value set via \fBOSSL_CMP_CTX_set1_subjectName()\fR are used as fallback. +.PP +The \fIcert\fR argument may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_build_cert_chain()\fR builds a certificate chain for the CMP signer +certificate previously set in the \fIctx\fR. It adds the optional \fIcandidates\fR, +a list of intermediate CA certs that may already constitute the targeted chain, +to the untrusted certs that may already exist in the \fIctx\fR. +Then the function uses this augmented set of certs for chain construction. +If \fIown_trusted\fR is NULL it builds the chain as far down as possible and +ignores any verification errors. Else the CMP signer certificate must be +verifiable where the chain reaches a trust anchor contained in \fIown_trusted\fR. +On success the function stores the resulting chain in \fIctx\fR +for inclusion in the extraCerts field of signature\-protected messages. +Calling this function is optional; by default a chain construction +is performed on demand that is equivalent to calling this function +with the \fIcandidates\fR and \fIown_trusted\fR arguments being NULL. +.PP +\&\fBOSSL_CMP_CTX_set1_pkey()\fR sets the client\*(Aqs private key corresponding to the +CMP signer certificate set via \fBOSSL_CMP_CTX_set1_cert()\fR. +This key is used create signature\-based protection (protectionAlg = MSG_SIG_ALG) +of outgoing messages +unless a symmetric secret has been set via \fBOSSL_CMP_CTX_set1_secretValue()\fR. +The \fIpkey\fR argument may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_set1_secretValue()\fR sets in \fIctx\fR the byte string \fIsec\fR of length +\&\fIlen\fR to use as pre\-shared secret, or clears it if the \fIsec\fR argument is NULL. +If present, this secret is used to create MAC\-based authentication and integrity +protection (rather than applying signature\-based protection) +of outgoing messages and to verify authenticity and integrity of incoming +messages that have MAC\-based protection (protectionAlg = \f(CW\*(C`MSG_MAC_ALG\*(C'\fR). +.PP +\&\fBOSSL_CMP_CTX_set1_referenceValue()\fR sets the given referenceValue \fIref\fR with +length \fIlen\fR in the given \fIctx\fR or clears it if the \fIref\fR argument is NULL. +According to RFC 9810 section 5.1.1, if no value for the sender field in +CMP message headers can be determined (i.e., no CMP signer certificate +and no subject DN is set via \fBOSSL_CMP_CTX_set1_subjectName()\fR +then the sender field will contain the NULL\-DN +and the senderKID field of the CMP message header must be set. +When signature\-based protection is used the senderKID will be set to +the subjectKeyIdentifier of the CMP signer certificate as far as present. +If not present or when MAC\-based protection is used +the \fIref\fR value is taken as the fallback value for the senderKID. +.PP +\&\fBOSSL_CMP_CTX_set1_recipient()\fR sets the recipient name that will be used in the +PKIHeader of CMP request messages, i.e. the X509 name of the (CA) server. +.PP +The recipient field in the header of a CMP message is mandatory. +If not given explicitly the recipient is determined in the following order: +the subject of the CMP server certificate set using \fBOSSL_CMP_CTX_set1_srvCert()\fR, +the value set using \fBOSSL_CMP_CTX_set1_issuer()\fR, +the issuer of the certificate set using \fBOSSL_CMP_CTX_set1_oldCert()\fR, +the issuer of the CMP signer certificate, +as far as any of those is present, else the NULL\-DN as last resort. +.PP +\&\fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR to be +added to the generalInfo field of the CMP PKIMessage header of a request +message sent with this context. +.PP +\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR +clears any ITAVs that were added by \fBOSSL_CMP_CTX_push0_geninfo_ITAV()\fR. +.PP +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR returns the list of ITAVs set in \fIctx\fR +for inclusion in the generalInfo field of the CMP PKIMessage header of requests +or NULL if not set. +.PP +\&\fBOSSL_CMP_CTX_set1_extraCertsOut()\fR sets the stack of extraCerts that will be +sent to remote. +.PP +\&\fBOSSL_CMP_CTX_set0_newPkey()\fR can be used to explicitly set the given EVP_PKEY +structure as the private or public key to be certified in the CMP context. +The \fIpriv\fR parameter must be 0 if and only if the given key is a public key. +.PP +\&\fBOSSL_CMP_CTX_get0_newPkey()\fR gives the key to use for certificate enrollment +dependent on fields of the CMP context structure: +the newPkey (which may be a private or public key) if present, +else the public key in the p10CSR if present, else the client\*(Aqs private key. +If the \fIpriv\fR parameter is not 0 and the selected key does not have a +private component then NULL is returned. +.PP +\&\fBOSSL_CMP_CTX_set1_issuer()\fR sets the name of the intended issuer that +will be set in the CertTemplate, i.e., the X509 name of the CA server. +.PP +\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR sets the serial number optionally used to +select the certificate to be revoked in Revocation Requests (RR). +.PP +\&\fBOSSL_CMP_CTX_set1_subjectName()\fR sets the subject DN that will be used in +the CertTemplate structure when requesting a new cert. For Key Update Requests +(KUR), it defaults to the subject DN of the reference certificate, +see \fBOSSL_CMP_CTX_set1_oldCert()\fR. This default is used for Initialization +Requests (IR) and Certification Requests (CR) only if no SANs are set. +The \fIsubjectName\fR is also used as fallback for the sender field +of outgoing CMP messages if no reference certificate is available. +.PP +\&\fBOSSL_CMP_CTX_push1_subjectAltName()\fR adds the given X509 name to the list of +alternate names on the certificate template request. This cannot be used if +any Subject Alternative Name extension is set via +\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR. +By default, unless \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR has been set, +the Subject Alternative Names are copied from the reference certificate, +see \fBOSSL_CMP_CTX_set1_oldCert()\fR. +If set and the subject DN is not set with \fBOSSL_CMP_CTX_set1_subjectName()\fR then +the certificate template of an IR and CR will not be filled with the default +subject DN from the reference certificate. +If a subject DN is desired it needs to be set explicitly with +\&\fBOSSL_CMP_CTX_set1_subjectName()\fR. +.PP +\&\fBOSSL_CMP_CTX_set0_reqExtensions()\fR sets the X.509v3 extensions to be used in +IR/CR/KUR. +.PP +\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR returns 1 if the context contains +a Subject Alternative Name extension, else 0 or \-1 on error. +.PP +\&\fBOSSL_CMP_CTX_push0_policy()\fR adds the certificate policy info object +to the X509_EXTENSIONS of the requested certificate template. +.PP +\&\fBOSSL_CMP_CTX_set1_oldCert()\fR sets the old certificate to be updated in +Key Update Requests (KUR) or to be revoked in Revocation Requests (RR). +For RR, this is ignored if an issuer name and a serial number are provided using +\&\fBOSSL_CMP_CTX_set1_issuer()\fR and \fBOSSL_CMP_CTX_set1_serialNumber()\fR, respectively. +For IR/CR/KUR this sets the \fIreference certificate\fR, +which otherwise defaults to the CMP signer certificate. +The \fIreference certificate\fR determined this way, if any, is used for providing +default public key, subject DN, Subject Alternative Names, and issuer DN entries +in the requested certificate template of IR/CR/KUR messages. +.PP +The subject of the reference certificate is used as the sender field value +in CMP message headers. +Its issuer is used as default recipient in CMP message headers. +.PP +\&\fBOSSL_CMP_CTX_set1_p10CSR()\fR sets the PKCS#10 CSR to use in P10CR messages. +If such a CSR is provided, its subject and public key fields are also +used as fallback values for the certificate template of IR/CR/KUR/RR messages, +and any extensions included are added to the template of IR/CR/KUR messages. +.PP +\&\fBOSSL_CMP_CTX_push0_genm_ITAV()\fR adds \fIitav\fR to the stack in the \fIctx\fR which +will be the body of a General Message sent with this context. +.PP +\&\fBOSSL_CMP_certConf_cb()\fR is the default certificate confirmation callback function. +If the callback argument is not NULL it must point to a trust store. +In this case the function checks that the newly enrolled certificate can be +verified using this trust store and untrusted certificates from the \fIctx\fR, +which have been augmented by the list of extraCerts received. +During this verification, any certificate status checking is disabled. +If the callback argument is NULL the function tries building an approximate +chain as far as possible using the same untrusted certificates from the \fIctx\fR, +and if this fails it takes the received extraCerts as fallback. +The resulting cert chain can be retrieved using \fBOSSL_CMP_CTX_get1_newChain()\fR. +This chain excludes the leaf certificate, i.e., the newly enrolled certificate. +Also the trust anchor (the root certificate) is not included. +.PP +\&\fBOSSL_CMP_CTX_set_certConf_cb()\fR sets the callback used for evaluating the newly +enrolled certificate before the library sends, depending on its result, +a positive or negative certConf message to the server. The callback has type +.PP +.Vb 2 +\& typedef int (*OSSL_CMP_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert, +\& int fail_info, const char **txt); +.Ve +.PP +and should inspect the certificate it obtains via the \fIcert\fR parameter and may +overrule the pre\-decision given in the \fIfail_info\fR and \fI*txt\fR parameters. +If it accepts the certificate it must return 0, indicating success. Else it must +return a bit field reflecting PKIFailureInfo with at least one failure bit and +may set the \fI*txt\fR output parameter to point to a string constant with more +detail. The transfer callback may make use of a custom defined argument stored +in the \fIctx\fR by means of \fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, which may be +retrieved again through \fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR. +Typically, the callback will check at least that the certificate can be verified +using a set of trusted certificates. +It also could compare the subject DN and other fields of the newly +enrolled certificate with the certificate template of the request. +.PP +\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR sets an argument, respectively a pointer to a +structure containing arguments, optionally to be used by the certConf callback. +\&\fIarg\fR is not consumed, and it must therefore explicitly be freed when not +needed any more. \fIarg\fR may be NULL to clear the entry. +.PP +\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR gets the argument, respectively the pointer +to a structure containing arguments, previously set by +\&\fBOSSL_CMP_CTX_set_certConf_cb_arg()\fR, or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_get_status()\fR returns for client contexts the PKIstatus from +the last received CertRepMessage or Revocation Response or error message: +=item \fBOSSL_CMP_PKISTATUS_accepted\fR on successful receipt of a GENP message: +.IP \fBOSSL_CMP_PKISTATUS_request\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_request" +if an IR/CR/KUR/RR/GENM request message could not be produced, +.IP \fBOSSL_CMP_PKISTATUS_trans\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_trans" +on a transmission error or transaction error for this type of request, and +.IP \fBOSSL_CMP_PKISTATUS_unspecified\fR 4 +.IX Item "OSSL_CMP_PKISTATUS_unspecified" +if no such request was attempted or \fBOSSL_CMP_CTX_reinit()\fR has been called. +.PP +For server contexts it returns +\&\fBOSSL_CMP_PKISTATUS_trans\fR if a transaction is open, +otherwise \fBOSSL_CMP_PKISTATUS_unspecified\fR. +.PP +\&\fBOSSL_CMP_CTX_get0_statusString()\fR returns the statusString from the last received +CertRepMessage or Revocation Response or error message, or NULL if unset. +.PP +\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR returns the error code from the failInfo field +of the last received CertRepMessage or Revocation Response or error message, +or \-1 if no such response was received or \fBOSSL_CMP_CTX_reinit()\fR has been called. +This is a bit field and the flags for it are specified in the header file +\&\fI\fR. +The flags start with OSSL_CMP_CTX_FAILINFO, for example: +OSSL_CMP_CTX_FAILINFO_badAlg. Returns \-1 if the failInfoCode field is unset. +.PP +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR returns +the successfully validated certificate, if any, that the CMP server used +in the current transaction for signature\-based response message protection, +or NULL if the server used MAC\-based protection. +The value is relevant only at the end of a successful transaction. +It may be used to check the authorization of the server based on its cert. +.PP +\&\fBOSSL_CMP_CTX_get0_newCert()\fR returns the pointer to the newly obtained +certificate in case it is available, else NULL. +.PP +\&\fBOSSL_CMP_CTX_get1_newChain()\fR returns a pointer to a duplicate of the stack of +X.509 certificates computed by \fBOSSL_CMP_certConf_cb()\fR (if this function has +been called) on the last received certificate response message IP/CP/KUP. +.PP +\&\fBOSSL_CMP_CTX_get1_caPubs()\fR returns a pointer to a duplicate of the list of +X.509 certificates in the caPubs field of the last received certificate +response message (of type IP, CP, or KUP), +or an empty stack if no caPubs have been received in the current transaction. +.PP +\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR returns a pointer to a duplicate of the list +of X.509 certificates contained in the extraCerts field of the last received +response message (except for pollRep and PKIConf), or +an empty stack if no extraCerts have been received in the current transaction. +.PP +\&\fBOSSL_CMP_CTX_set1_transactionID()\fR sets the given transaction ID in the given +OSSL_CMP_CTX structure. +.PP +\&\fBOSSL_CMP_CTX_set1_senderNonce()\fR stores the last sent sender \fInonce\fR in +the \fIctx\fR. This will be used to validate the recipNonce in incoming messages. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810 (and CRMF in RFC 4211). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_CTX_free()\fR and \fBOSSL_CMP_CTX_print_errors()\fR do not return anything. +.PP +\&\fBOSSL_CMP_CTX_new()\fR, +\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, +\&\fBOSSL_CMP_CTX_get_http_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get_transfer_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get0_trusted()\fR, +\&\fBOSSL_CMP_CTX_get0_untrusted()\fR, +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR, +\&\fBOSSL_CMP_CTX_get0_newPkey()\fR, +\&\fBOSSL_CMP_CTX_get_certConf_cb_arg()\fR, +\&\fBOSSL_CMP_CTX_get0_statusString()\fR, +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR, +\&\fBOSSL_CMP_CTX_get0_newCert()\fR, +\&\fBOSSL_CMP_CTX_get0_newChain()\fR, +\&\fBOSSL_CMP_CTX_get1_caPubs()\fR, and +\&\fBOSSL_CMP_CTX_get1_extraCertsIn()\fR +return the intended pointer value as described above or NULL on error. +.PP +\&\fBOSSL_CMP_CTX_get_option()\fR, +\&\fBOSSL_CMP_CTX_reqExtensions_have_SAN()\fR, +\&\fBOSSL_CMP_CTX_get_status()\fR, and +\&\fBOSSL_CMP_CTX_get_failInfoCode()\fR +return the intended value as described above or \-1 on error. +.PP +\&\fBOSSL_CMP_certConf_cb()\fR returns \fIfail_info\fR if it is not equal to 0, +else 0 on successful validation, +or else a bit field with the \fBOSSL_CMP_PKIFAILUREINFO_incorrectData\fR bit set. +.PP +All other functions, including \fBOSSL_CMP_CTX_reinit()\fR +and \fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR, +return 1 on success, 0 on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following code omits error handling. +.PP +Set up a CMP client context for sending requests and verifying responses: +.PP +.Vb 5 +\& cmp_ctx = OSSL_CMP_CTX_new(); +\& OSSL_CMP_CTX_set1_server(cmp_ctx, name_or_address); +\& OSSL_CMP_CTX_set1_serverPort(cmp_ctx, port_string); +\& OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias); +\& OSSL_CMP_CTX_set0_trusted(cmp_ctx, ts); +.Ve +.PP +Set up symmetric credentials for MAC\-based message protection such as PBM: +.PP +.Vb 2 +\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len); +\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len); +.Ve +.PP +Set up the details for certificate requests: +.PP +.Vb 2 +\& OSSL_CMP_CTX_set1_subjectName(cmp_ctx, name); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, initialKey); +.Ve +.PP +Perform an Initialization Request transaction: +.PP +.Vb 1 +\& initialCert = OSSL_CMP_exec_IR_ses(cmp_ctx); +.Ve +.PP +Reset the transaction state of the CMP context and the credentials: +.PP +.Vb 3 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, NULL, 0); +\& OSSL_CMP_CTX_set1_secretValue(cmp_ctx, NULL, 0); +.Ve +.PP +Perform a Certification Request transaction, making use of the new credentials: +.PP +.Vb 4 +\& OSSL_CMP_CTX_set1_cert(cmp_ctx, initialCert); +\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, initialKey); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, curentKey); +\& currentCert = OSSL_CMP_exec_CR_ses(cmp_ctx); +.Ve +.PP +Perform a Key Update Request, signed using the cert (and key) to be updated: +.PP +.Vb 6 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& OSSL_CMP_CTX_set1_cert(cmp_ctx, currentCert); +\& OSSL_CMP_CTX_set1_pkey(cmp_ctx, currentKey); +\& OSSL_CMP_CTX_set0_newPkey(cmp_ctx, 1, updatedKey); +\& currentCert = OSSL_CMP_exec_KUR_ses(cmp_ctx); +\& currentKey = updatedKey; +.Ve +.PP +Perform a General Message transaction including, as an example, +the id\-it\-signKeyPairTypes OID and prints info on the General Response contents: +.PP +.Vb 1 +\& OSSL_CMP_CTX_reinit(cmp_ctx); +\& +\& ASN1_OBJECT *type = OBJ_txt2obj("1.3.6.1.5.5.7.4.2", 1); +\& OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, NULL); +\& OSSL_CMP_CTX_push0_genm_ITAV(cmp_ctx, itav); +\& +\& STACK_OF(OSSL_CMP_ITAV) *itavs; +\& itavs = OSSL_CMP_exec_GENM_ses(cmp_ctx); +\& print_itavs(itavs); +\& sk_OSSL_CMP_ITAV_pop_free(itavs, OSSL_CMP_ITAV_free); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_exec_IR_ses\fR\|(3), \fBOSSL_CMP_exec_CR_ses\fR\|(3), +\&\fBOSSL_CMP_exec_KUR_ses\fR\|(3), \fBOSSL_CMP_exec_GENM_ses\fR\|(3), +\&\fBOSSL_CMP_exec_certreq\fR\|(3), \fBOSSL_CMP_MSG_http_perform\fR\|(3), +\&\fBERR_print_errors_cb\fR\|(3), \fBOSSL_HTTP_open\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_CTX_get0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_get0_trusted()\fR and +\&\fBOSSL_CMP_CTX_set0_trustedStore()\fR was renamed to \fBOSSL_CMP_CTX_set0_trusted()\fR, +using macros, while keeping the old names for backward compatibility, +in OpenSSL 3.2. +.PP +\&\fBOSSL_CMP_CTX_reset_geninfo_ITAVs()\fR was added in OpenSSL 3.0.8. +.PP +\&\fBOSSL_CMP_CTX_set1_serialNumber()\fR, +\&\fBOSSL_CMP_CTX_get0_libctx()\fR, \fBOSSL_CMP_CTX_get0_propq()\fR, and +\&\fBOSSL_CMP_CTX_get0_validatedSrvCert()\fR were added in OpenSSL 3.2. +.PP +\&\fBOSSL_CMP_CTX_get0_geninfo_ITAVs()\fR and +the \fBOSSL_CMP_OPT_NO_CACHE_EXTRACERTS\fR option were added in OpenSSL 3.3. +.PP +Support for central key generation, requested via \fBOSSL_CRMF_POPO_NONE\fR, +was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_HDR_get0_transactionID.3 b/static/netbsd/man3/OSSL_CMP_HDR_get0_transactionID.3 new file mode 100644 index 00000000..9dbe3de8 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_HDR_get0_transactionID.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: OSSL_CMP_HDR_get0_transactionID.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_HDR_get0_transactionID 3" +.TH OSSL_CMP_HDR_get0_transactionID 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_HDR_get0_transactionID, +OSSL_CMP_HDR_get0_recipNonce, +OSSL_CMP_HDR_get0_geninfo_ITAVs +\&\- functions manipulating CMP message headers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OCTET_STRING *OSSL_CMP_HDR_get0_transactionID(const +\& OSSL_CMP_PKIHEADER *hdr); +\& ASN1_OCTET_STRING *OSSL_CMP_HDR_get0_recipNonce(const +\& OSSL_CMP_PKIHEADER *hdr); +\& STACK_OF(OSSL_CMP_ITAV) +\& *OSSL_CMP_HDR_get0_geninfo_ITAVs(const OSSL_CMP_PKIHEADER *hdr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OSSL_CMP_HDR_get0_transactionID returns the transaction ID of the given +PKIHeader. +.PP +OSSL_CMP_HDR_get0_recipNonce returns the recipient nonce of the given PKIHeader. +.PP +\&\fBOSSL_CMP_HDR_get0_geninfo_ITAVs()\fR returns the list of ITAVs +in the generalInfo field of the given PKIHeader. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions return the intended pointer value as described above +or NULL if the respective entry does not exist and on error. +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_HDR_get0_geninfo_ITAVs()\fR was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_ITAV_new_caCerts.3 b/static/netbsd/man3/OSSL_CMP_ITAV_new_caCerts.3 new file mode 100644 index 00000000..02c96c79 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_ITAV_new_caCerts.3 @@ -0,0 +1,272 @@ +.\" $NetBSD: OSSL_CMP_ITAV_new_caCerts.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_ITAV_new_caCerts 3" +.TH OSSL_CMP_ITAV_new_caCerts 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_ITAV_new_caCerts, +OSSL_CMP_ITAV_get0_caCerts, +OSSL_CMP_ITAV_new_rootCaCert, +OSSL_CMP_ITAV_get0_rootCaCert, +OSSL_CMP_ITAV_new_rootCaKeyUpdate, +OSSL_CMP_ITAV_get0_rootCaKeyUpdate, +OSSL_CMP_CRLSTATUS_new1, +OSSL_CMP_CRLSTATUS_create, +OSSL_CMP_CRLSTATUS_get0, +OSSL_CMP_ITAV_new0_crlStatusList, +OSSL_CMP_ITAV_get0_crlStatusList, +OSSL_CMP_ITAV_new_crls, +OSSL_CMP_ITAV_get0_crls, +OSSL_CMP_ITAV_new0_certReqTemplate, +OSSL_CMP_ITAV_get1_certReqTemplate +\&\- CMP utility functions for handling specific genm and genp messages +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_caCerts(const STACK_OF(X509) *caCerts); +\& int OSSL_CMP_ITAV_get0_caCerts(const OSSL_CMP_ITAV *itav, STACK_OF(X509) **out); +\& +\& OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaCert(const X509 *rootCaCert); +\& int OSSL_CMP_ITAV_get0_rootCaCert(const OSSL_CMP_ITAV *itav, X509 **out); +\& OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaKeyUpdate(const X509 *newWithNew, +\& const X509 *newWithOld, +\& const X509 *oldWithNew); +\& int OSSL_CMP_ITAV_get0_rootCaKeyUpdate(const OSSL_CMP_ITAV *itav, +\& X509 **newWithNew, +\& X509 **newWithOld, +\& X509 **oldWithNew); +\& +\& OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_new1(const DIST_POINT_NAME *dpn, +\& const GENERAL_NAMES *issuer, +\& const ASN1_TIME *thisUpdate); +\& OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_create(const X509_CRL *crl, +\& const X509 *cert, int only_DN); +\& int OSSL_CMP_CRLSTATUS_get0(const OSSL_CMP_CRLSTATUS *crlstatus, +\& DIST_POINT_NAME **dpn, GENERAL_NAMES **issuer, +\& ASN1_TIME **thisUpdate); +\& OSSL_CMP_ITAV +\& *OSSL_CMP_ITAV_new0_crlStatusList(STACK_OF(OSSL_CMP_CRLSTATUS) *crlStatusList); +\& int OSSL_CMP_ITAV_get0_crlStatusList(const OSSL_CMP_ITAV *itav, +\& STACK_OF(OSSL_CMP_CRLSTATUS) **out); +\& OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_crls(const X509_CRL *crl); +\& int OSSL_CMP_ITAV_get0_crls(const OSSL_CMP_ITAV *itav, STACK_OF(X509_CRL) **out); +\& OSSL_CMP_ITAV +\& *OSSL_CMP_ITAV_new0_certReqTemplate(OSSL_CRMF_CERTTEMPLATE *certTemplate, +\& OSSL_CMP_ATAVS *keySpec); +\& int OSSL_CMP_ITAV_get1_certReqTemplate(const OSSL_CMP_ITAV *itav, +\& OSSL_CRMF_CERTTEMPLATE **certTemplate, +\& OSSL_CMP_ATAVS **keySpec); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ITAV is short for InfoTypeAndValue. +.PP +\&\fBOSSL_CMP_ITAV_new_caCerts()\fR creates an \fBOSSL_CMP_ITAV\fR structure of type +\&\fBcaCerts\fR and fills it with a copy of the provided list of certificates. +The \fIcaCerts\fR argument may be NULL or contain any number of certificates. +.PP +\&\fBOSSL_CMP_ITAV_get0_caCerts()\fR requires that \fIitav\fR has type \fBcaCerts\fR. +It assigns NULL to \fI*out\fR if there are no CA certificates in \fIitav\fR, otherwise +the internal pointer of type \fBSTACK_OF(X509)\fR with the certificates present. +.PP +\&\fBOSSL_CMP_ITAV_new_rootCaCert()\fR creates a new \fBOSSL_CMP_ITAV\fR structure +of type \fBrootCaCert\fR that includes the optionally given certificate. +.PP +\&\fBOSSL_CMP_ITAV_get0_rootCaCert()\fR requires that \fIitav\fR has type \fBrootCaCert\fR. +It assigns NULL to \fI*out\fR if no certificate is included in \fIitav\fR, otherwise +the internal pointer to the certificate contained in the infoValue field. +.PP +\&\fBOSSL_CMP_ITAV_new_rootCaKeyUpdate()\fR creates a new \fBOSSL_CMP_ITAV\fR structure +of type \fBrootCaKeyUpdate\fR that includes an RootCaKeyUpdateContent structure +with the optional \fInewWithNew\fR, \fInewWithOld\fR, and \fIoldWithNew\fR certificates. +An RootCaKeyUpdateContent structure is included only if \fInewWithNew\fR +is not NULL. +.PP +\&\fBOSSL_CMP_ITAV_get0_rootCaKeyUpdate()\fR requires that \fIitav\fR has infoType +\&\fBrootCaKeyUpdate\fR. +If an update of a root CA certificate is included, +it assigns to \fI*newWithNew\fR the internal pointer +to the certificate contained in the newWithNew infoValue sub\-field of \fIitav\fR. +If \fInewWithOld\fR is not NULL, it assigns to \fI*newWithOld\fR the internal pointer +to the certificate contained in the newWithOld infoValue sub\-field of \fIitav\fR. +If \fIoldWithNew\fR is not NULL, it assigns to \fI*oldWithNew\fR the internal pointer +to the certificate contained in the oldWithNew infoValue sub\-field of \fIitav\fR. +Each of these pointers will be set to NULL if no root CA certificate update +is present or the respective sub\-field is not included. +.PP +\&\fBOSSL_CMP_CRLSTATUS_new1()\fR allocates a new \fBOSSL_CMP_CRLSTATUS\fR structure +that contains either a copy of the distribution point name \fIdpn\fR +or a copy of the certificate issuer \fIissuer\fR, while giving both is an error. +If given, a copy of the CRL issuance time \fIthisUpdate\fR is also included. +.PP +\&\fBOSSL_CMP_CRLSTATUS_create()\fR is a high\-level variant of \fBOSSL_CMP_CRLSTATUS_new1()\fR. +It fills the thisUpdate field with a copy of the thisUpdate field of \fIcrl\fR if present. +It fills the CRLSource field with a copy of the first data item found using the \fIcrl\fR +and/or \fIcert\fR parameters as follows. +Any available distribution point name is preferred over issuer names. +Data from \fIcert\fR, if present, is preferred over data from \fIcrl\fR. +If no distribution point names are available, +candidate issuer names are taken from following sources, as far as present: +.IP "the list of distribution points in the first cRLDistributionPoints extension of \fIcert\fR," 4 +.IX Item "the list of distribution points in the first cRLDistributionPoints extension of cert," +.PD 0 +.IP "the issuer field of the authority key identifier of \fIcert\fR," 4 +.IX Item "the issuer field of the authority key identifier of cert," +.IP "the issuer DN of \fIcert\fR," 4 +.IX Item "the issuer DN of cert," +.IP "the issuer field of the authority key identifier of \fIcrl\fR, and" 4 +.IX Item "the issuer field of the authority key identifier of crl, and" +.IP "the issuer DN of \fIcrl\fR." 4 +.IX Item "the issuer DN of crl." +.PD +.PP +If is set, a candidate issuer name of type \fBGENERAL_NAMES\fR is +accepted only if it contains exactly one general name of type directoryName. +.PP +\&\fBOSSL_CMP_CRLSTATUS_get0()\fR reads the fields of \fIcrlstatus\fR +and assigns them to \fI*dpn\fR, \fI*issuer\fR, and \fI*thisUpdate\fR. +\&\fI*thisUpdate\fR is assigned only if the \fIthisUpdate\fR argument is not NULL. +Depending on the choice present, either \fI*dpn\fR or \fI*issuer\fR will be NULL. +\&\fI*thisUpdate\fR can also be NULL if the field is not present. +.PP +\&\fBOSSL_CMP_ITAV_new0_crlStatusList()\fR creates a new \fBOSSL_CMP_ITAV\fR structure of +type \fBcrlStatusList\fR that includes the optionally given list of +CRL status data, each of which is of type \fBOSSL_CMP_CRLSTATUS\fR. +.PP +\&\fBOSSL_CMP_ITAV_get0_crlStatusList()\fR on success assigns to \fI*out\fR an internal +pointer to the list of CRL status data in the infoValue field of \fIitav\fR. +The pointer may be NULL if no CRL status data is included. +It is an error if the infoType of \fIitav\fR is not \fBcrlStatusList\fR. +.PP +\&\fBOSSL_CMP_ITAV_new_crls()\fR creates a new \fBOSSL_CMP_ITAV\fR structure +of type \fBcrls\fR including an empty list of CRLs if the \fIcrl\fR argument is NULL +or including a singleton list a with copy of the provided CRL otherwise. +.PP +\&\fBOSSL_CMP_ITAV_get0_crls()\fR on success assigns to \fI*out\fR an internal pointer to +the list of CRLs contained in the infoValue field of \fIitav\fR. +The pointer may be NULL if no CRL is included. +It is an error if the infoType of \fIitav\fR is not \fBcrls\fR. +.PP +\&\fBOSSL_CMP_ITAV_new0_certReqTemplate()\fR creates an \fBOSSL_CMP_ITAV\fR structure +of type \fBcertReqTemplate\fR. +If \fIcertTemplate\fR is NULL then also \fIkeySpec\fR must be NULL, +and the resulting ITAV can be used in a \fBgenm\fR message to obtain the +requirements a PKI has on the certificate template used to request certificates, +or in a \fBgenp\fR message stating that there are no such requirements. +Otherwise the resulting ITAV includes a CertReqTemplateValue structure +with \fIcertTemplate\fR of type \fBOSSL_CRMF_CERTTEMPLATE\fR and an optional list +of key specifications \fIkeySpec\fR, each being of type \fBOSSL_CMP_ATAV\fR, and +the resulting ATAV can be used in a \fBgenp\fR message to provide requirements. +.PP +\&\fBOSSL_CMP_ITAV_get1_certReqTemplate()\fR +requires that \fIitav\fR has type \fBcertReqTemplate\fR. +If assigns NULL to \fI*certTemplate\fR if no \fBOSSL_CRMF_CERTTEMPLATE\fR structure +with a certificate template value is in \fIitav\fR, +otherwise a copy of the certTemplate field value. +If \fIkeySpec\fR is not NULL, it is assigned NULL +if the structure is not present in \fIitav\fR or the keySpec field is absent. +Otherwise, the function checks that all elements of keySpec field are of type +\&\fBalgId\fR or \fBrsaKeyLen\fR and assigns to \fI*keySpec\fR a copy of the keySpec field. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_ITAV_new_caCerts()\fR, \fBOSSL_CMP_ITAV_new_rootCaCert()\fR, +\&\fBOSSL_CMP_ITAV_new_rootCaKeyUpdate()\fR, \fBOSSL_CMP_CRLSTATUS_new1()\fR, +\&\fBOSSL_CMP_CRLSTATUS_create()\fR, \fBOSSL_CMP_ITAV_new0_crlStatusList()\fR, +\&\fBOSSL_CMP_ITAV_new_crls()\fR and \fBOSSL_CMP_ITAV_new0_certReqTemplate()\fR +return a pointer to the new ITAV structure on success, or NULL on error. +.PP +\&\fBOSSL_CMP_ITAV_get0_caCerts()\fR, \fBOSSL_CMP_ITAV_get0_rootCaCert()\fR, +\&\fBOSSL_CMP_ITAV_get0_rootCaKeyUpdate()\fR, \fBOSSL_CMP_CRLSTATUS_get0()\fR, +\&\fBOSSL_CMP_ITAV_get0_crlStatusList()\fR, \fBOSSL_CMP_ITAV_get0_crls()\fR +and \fBOSSL_CMP_ITAV_get1_certReqTemplate()\fR +return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_ITAV_create\fR\|(3) and \fBOSSL_CMP_ITAV_get0_type\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_CMP_ITAV_new_caCerts()\fR, \fBOSSL_CMP_ITAV_get0_caCerts()\fR, +\&\fBOSSL_CMP_ITAV_new_rootCaCert()\fR, \fBOSSL_CMP_ITAV_get0_rootCaCert()\fR, +\&\fBOSSL_CMP_ITAV_new_rootCaKeyUpdate()\fR, and \fBOSSL_CMP_ITAV_get0_rootCaKeyUpdate()\fR +were added in OpenSSL 3.2. +.PP +\&\fBOSSL_CMP_CRLSTATUS_new1()\fR, \fBOSSL_CMP_CRLSTATUS_create()\fR, +\&\fBOSSL_CMP_CRLSTATUS_get0()\fR, \fBOSSL_CMP_ITAV_new0_crlStatusList()\fR, +\&\fBOSSL_CMP_ITAV_get0_crlStatusList()\fR, \fBOSSL_CMP_ITAV_new_crls()\fR, +\&\fBOSSL_CMP_ITAV_get0_crls()\fR, \fBOSSL_CMP_ITAV_new0_certReqTemplate()\fR +and \fBOSSL_CMP_ITAV_get1_certReqTemplate()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_ITAV_set0.3 b/static/netbsd/man3/OSSL_CMP_ITAV_set0.3 new file mode 100644 index 00000000..dc89a099 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_ITAV_set0.3 @@ -0,0 +1,191 @@ +.\" $NetBSD: OSSL_CMP_ITAV_set0.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_ITAV_set0 3" +.TH OSSL_CMP_ITAV_set0 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_ITAV_create, +OSSL_CMP_ITAV_set0, +OSSL_CMP_ITAV_get0_type, +OSSL_CMP_ITAV_get0_value, +OSSL_CMP_ITAV_push0_stack_item, +OSSL_CMP_ITAV_new0_certProfile, +OSSL_CMP_ITAV_get0_certProfile +\&\- OSSL_CMP_ITAV utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_ITAV *OSSL_CMP_ITAV_create(ASN1_OBJECT *type, ASN1_TYPE *value); +\& void OSSL_CMP_ITAV_set0(OSSL_CMP_ITAV *itav, ASN1_OBJECT *type, +\& ASN1_TYPE *value); +\& ASN1_OBJECT *OSSL_CMP_ITAV_get0_type(const OSSL_CMP_ITAV *itav); +\& ASN1_TYPE *OSSL_CMP_ITAV_get0_value(const OSSL_CMP_ITAV *itav); +\& int OSSL_CMP_ITAV_push0_stack_item(STACK_OF(OSSL_CMP_ITAV) **itav_sk_p, +\& OSSL_CMP_ITAV *itav); +\& OSSL_CMP_ITAV +\& *OSSL_CMP_ITAV_new0_certProfile(STACK_OF(ASN1_UTF8STRING) *certProfile); +\& int OSSL_CMP_ITAV_get0_certProfile(const OSSL_CMP_ITAV *itav, +\& STACK_OF(ASN1_UTF8STRING) **out); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ITAV is short for InfoTypeAndValue. This type is defined in RFC 9810 +section 5.3.19 and Appendix F. It is used at various places in CMP messages, +e.g., in the generalInfo PKIHeader field, to hold a key\-value pair. +.PP +\&\fBOSSL_CMP_ITAV_create()\fR creates a new \fBOSSL_CMP_ITAV\fR structure and fills it in. +It combines \fBOSSL_CMP_ITAV_new()\fR and \fBOSSL_CMP_ITAV_set0()\fR. +.PP +\&\fBOSSL_CMP_ITAV_set0()\fR sets the \fIitav\fR with an infoType of \fItype\fR and an +infoValue of \fIvalue\fR. This function uses the pointers \fItype\fR and \fIvalue\fR +internally, so they must \fBnot\fR be freed up after the call. +.PP +\&\fBOSSL_CMP_ITAV_get0_type()\fR returns a direct pointer to the infoType in the +\&\fIitav\fR. +.PP +\&\fBOSSL_CMP_ITAV_get0_value()\fR returns a direct pointer to the infoValue in +the \fIitav\fR as generic \fBASN1_TYPE\fR pointer. +.PP +\&\fBOSSL_CMP_ITAV_push0_stack_item()\fR pushes \fIitav\fR to the stack pointed to +by \fI*itav_sk_p\fR. It creates a new stack if \fI*itav_sk_p\fR points to NULL. +.PP +\&\fBOSSL_CMP_ITAV_new0_certProfile()\fR creates a new \fBOSSL_CMP_ITAV\fR structure +of type \fBcertProfile\fR that includes the optionally given list of profile names. +On success, ownership of the list is with the new \fBOSSL_CMP_ITAV\fR structure. +.PP +\&\fBOSSL_CMP_ITAV_get0_certProfile()\fR on success assigns to \fI*out\fR +an internal pointer to the +list of certificate profile names contained in the infoValue field of \fIitav\fR. +The pointer may be NULL if no profile name is included. +It is an error if the infoType of \fIitav\fR is not \fBcertProfile\fR. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.PP +OIDs to use as types in \fBOSSL_CMP_ITAV\fR can be found at +. +The respective OpenSSL NIDs, such as \fBNID_id_it_certProfile\fR, +are defined in the \fI\fR header file. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_ITAV_create()\fR and \fBOSSL_CMP_ITAV_new0_certProfile()\fR +return a pointer to an ITAV structure on success, or NULL on error. +.PP +\&\fBOSSL_CMP_ITAV_set0()\fR does not return a value. +.PP +\&\fBOSSL_CMP_ITAV_get0_type()\fR and \fBOSSL_CMP_ITAV_get0_value()\fR +return the respective pointer or NULL if their input is NULL. +.PP +\&\fBOSSL_CMP_ITAV_push0_stack_item()\fR and \fBOSSL_CMP_ITAV_get0_certProfile()\fR +return 1 on success, 0 on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following code creates and sets a structure representing a generic +InfoTypeAndValue sequence, using an OID created from text as type, and an +integer as value. Afterwards, it is pushed to the \fBOSSL_CMP_CTX\fR to be later +included in the requests\*(Aq PKIHeader\*(Aqs genInfo field. +.PP +.Vb 2 +\& ASN1_OBJECT *type = OBJ_txt2obj("1.2.3.4.5", 1); +\& if (type == NULL) ... +\& +\& ASN1_INTEGER *asn1int = ASN1_INTEGER_new(); +\& if (asn1int == NULL || !ASN1_INTEGER_set(asn1int, 12345)) ... +\& +\& ASN1_TYPE *val = ASN1_TYPE_new(); +\& if (val == NULL) ... +\& ASN1_TYPE_set(val, V_ASN1_INTEGER, asn1int); +\& +\& OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, val); +\& if (itav == NULL) ... +\& +\& if (!OSSL_CMP_CTX_push0_geninfo_ITAV(ctx, itav)) { +\& OSSL_CMP_ITAV_free(itav); /* also frees type and val */ +\& ... +\& } +\& +\& ... +\& +\& OSSL_CMP_CTX_free(ctx); /* also frees itav */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_CTX_free\fR\|(3), \fBASN1_TYPE_set\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_ITAV_new0_certProfile()\fR and \fBOSSL_CMP_ITAV_get0_certProfile()\fR +were added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_MSG_get0_header.3 b/static/netbsd/man3/OSSL_CMP_MSG_get0_header.3 new file mode 100644 index 00000000..650dbcf6 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_MSG_get0_header.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: OSSL_CMP_MSG_get0_header.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_MSG_get0_header 3" +.TH OSSL_CMP_MSG_get0_header 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_MSG_get0_header, +OSSL_CMP_MSG_get_bodytype, +OSSL_CMP_MSG_get0_certreq_publickey, +OSSL_CMP_MSG_update_transactionID, +OSSL_CMP_MSG_update_recipNonce, +OSSL_CMP_CTX_setup_CRM, +OSSL_CMP_MSG_read, +OSSL_CMP_MSG_write, +d2i_OSSL_CMP_MSG_bio, +i2d_OSSL_CMP_MSG_bio +\&\- function(s) manipulating CMP messages +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_PKIHEADER *OSSL_CMP_MSG_get0_header(const OSSL_CMP_MSG *msg); +\& int OSSL_CMP_MSG_get_bodytype(const OSSL_CMP_MSG *msg); +\& X509_PUBKEY *OSSL_CMP_MSG_get0_certreq_publickey(const OSSL_CMP_MSG *msg); +\& int OSSL_CMP_MSG_update_transactionID(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); +\& int OSSL_CMP_MSG_update_recipNonce(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); +\& OSSL_CRMF_MSG *OSSL_CMP_CTX_setup_CRM(OSSL_CMP_CTX *ctx, int for_KUR, int rid); +\& OSSL_CMP_MSG *OSSL_CMP_MSG_read(const char *file, OSSL_LIB_CTX *libctx, const char *propq); +\& int OSSL_CMP_MSG_write(const char *file, const OSSL_CMP_MSG *msg); +\& OSSL_CMP_MSG *d2i_OSSL_CMP_MSG_bio(BIO *bio, OSSL_CMP_MSG **msg); +\& int i2d_OSSL_CMP_MSG_bio(BIO *bio, const OSSL_CMP_MSG *msg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CMP_MSG_get0_header()\fR returns the header of the given CMP message. +.PP +\&\fBOSSL_CMP_MSG_get_bodytype()\fR returns the body type of the given CMP message. +.PP +\&\fBOSSL_CMP_MSG_get0_certreq_publickey()\fR expects that \fImsg\fR is a certificate request +message and returns the public key in its certificate template if present. +.PP +\&\fBOSSL_CMP_MSG_update_transactionID()\fR updates the transactionID field +in the header of the given message according to the CMP_CTX. +If \fIctx\fR does not contain a transaction ID, a fresh one is created before. +The message gets re\-protected (if protecting requests is required). +.PP +\&\fBOSSL_CMP_MSG_update_recipNonce()\fR updates the recipNonce field +in the header of the given message according to the CMP_CTX. +The message gets re\-protected (if protecting requests is required). +.PP +\&\fBOSSL_CMP_CTX_setup_CRM()\fR creates a CRMF certificate request message +from various information provided in the CMP context argument \fIctx\fR +for inclusion in a CMP request message based on details contained in \fIctx\fR. +The \fIrid\fR argument defines the request identifier to use, which typically is 0. +.PP +The subject DN included in the certificate template is +the first available value of these: +.IP "any subject name in \fIctx\fR set via \fBOSSL_CMP_CTX_set1_subjectName\fR\|(3) \- if it is the NULL\-DN (i.e., any empty sequence of RDNs), no subject is included," 4 +.IX Item "any subject name in ctx set via OSSL_CMP_CTX_set1_subjectName - if it is the NULL-DN (i.e., any empty sequence of RDNs), no subject is included," +.PD 0 +.IP "the subject field of any PKCS#10 CSR set in \fIctx\fR via \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3)," 4 +.IX Item "the subject field of any PKCS#10 CSR set in ctx via OSSL_CMP_CTX_set1_p10CSR," +.IP "the subject field of any reference certificate given in \fIctx\fR (see \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3)), but only if \fIfor_KUR\fR is nonzero or the \fIctx\fR does not include a Subject Alternative Name." 4 +.IX Item "the subject field of any reference certificate given in ctx (see OSSL_CMP_CTX_set1_oldCert), but only if for_KUR is nonzero or the ctx does not include a Subject Alternative Name." +.PD +.PP +The public key included is the first available value of these: +.IP "the public key derived from any key set via \fBOSSL_CMP_CTX_set0_newPkey\fR\|(3)," 4 +.IX Item "the public key derived from any key set via OSSL_CMP_CTX_set0_newPkey," +.PD 0 +.IP "the public key of any PKCS#10 CSR given in \fIctx\fR," 4 +.IX Item "the public key of any PKCS#10 CSR given in ctx," +.IP "the public key of any reference certificate given in \fIctx\fR (see \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3))," 4 +.IX Item "the public key of any reference certificate given in ctx (see OSSL_CMP_CTX_set1_oldCert)," +.IP "the public key derived from any client\*(Aqs private key set via \fBOSSL_CMP_CTX_set1_pkey\fR\|(3)." 4 +.IX Item "the public key derived from any client's private key set via OSSL_CMP_CTX_set1_pkey." +.PD +.PP +The set of X.509 extensions to include is computed as follows. +If a PKCS#10 CSR is present in \fIctx\fR, default extensions are taken from there, +otherwise the empty set is taken as the initial value. +If there is a reference certificate in \fIctx\fR and contains Subject Alternative +Names (SANs) and \fBOSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT\fR is not set, +these override any SANs from the PKCS#10 CSR. +The extensions are further augmented or overridden by any extensions with the +same OIDs included in the \fIctx\fR via \fBOSSL_CMP_CTX_set0_reqExtensions\fR\|(3). +The SANs are further overridden by any SANs included in \fIctx\fR via +\&\fBOSSL_CMP_CTX_push1_subjectAltName\fR\|(3). +Finally, policies are overridden by any policies included in \fIctx\fR via +\&\fBOSSL_CMP_CTX_push0_policy\fR\|(3). +.PP +\&\fBOSSL_CMP_CTX_setup_CRM()\fR also sets the sets the regToken control \fBoldCertID\fR +for KUR messages using the issuer name and serial number of the reference +certificate, if present. +.PP +\&\fBOSSL_CMP_MSG_read()\fR loads a DER\-encoded OSSL_CMP_MSG from \fIfile\fR. +.PP +\&\fBOSSL_CMP_MSG_write()\fR stores the given OSSL_CMP_MSG to \fIfile\fR in DER encoding. +.PP +\&\fBd2i_OSSL_CMP_MSG_bio()\fR parses an ASN.1\-encoded OSSL_CMP_MSG from the BIO \fIbio\fR. +It assigns a pointer to the new structure to \fI*msg\fR if \fImsg\fR is not NULL. +.PP +\&\fBi2d_OSSL_CMP_MSG_bio()\fR writes the OSSL_CMP_MSG \fImsg\fR in ASN.1 encoding +to BIO \fIbio\fR. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_MSG_get0_header()\fR returns the intended pointer value as described above +or NULL if the respective entry does not exist and on error. +.PP +\&\fBOSSL_CMP_MSG_get_bodytype()\fR returns the body type or \-1 on error. +.PP +\&\fBOSSL_CMP_MSG_get0_certreq_publickey()\fR returns a public key or NULL on error. +.PP +\&\fBOSSL_CMP_CTX_setup_CRM()\fR returns a pointer to a \fBOSSL_CRMF_MSG\fR on success, +NULL on error. +.PP +\&\fBd2i_OSSL_CMP_MSG_bio()\fR returns the parsed message or NULL on error. +.PP +\&\fBOSSL_CMP_MSG_read()\fR and \fBd2i_OSSL_CMP_MSG_bio()\fR +return the parsed CMP message or NULL on error. +.PP +\&\fBOSSL_CMP_MSG_write()\fR returns the number of bytes successfully encoded or a +negative value if an error occurs. +.PP +\&\fBi2d_OSSL_CMP_MSG_bio()\fR, \fBOSSL_CMP_MSG_update_transactionID()\fR, +and \fBOSSL_CMP_MSG_update_recipNonce()\fR +return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), \fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_pkey\fR\|(3), \fBOSSL_CMP_CTX_set0_reqExtensions\fR\|(3), +\&\fBOSSL_CMP_CTX_push1_subjectAltName\fR\|(3), \fBOSSL_CMP_CTX_push0_policy\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_MSG_update_recipNonce()\fR was added in OpenSSL 3.0.9. +.PP +\&\fBOSSL_CMP_MSG_get0_certreq_publickey()\fR was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_MSG_http_perform.3 b/static/netbsd/man3/OSSL_CMP_MSG_http_perform.3 new file mode 100644 index 00000000..44eb2dee --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_MSG_http_perform.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: OSSL_CMP_MSG_http_perform.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_MSG_http_perform 3" +.TH OSSL_CMP_MSG_http_perform 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_MSG_http_perform +\&\- client\-side HTTP(S) transfer of a CMP request\-response pair +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_MSG *OSSL_CMP_MSG_http_perform(OSSL_CMP_CTX *ctx, +\& const OSSL_CMP_MSG *req); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CMP_MSG_http_perform()\fR sends the given PKIMessage \fIreq\fR to the +CMP server specified in \fIctx\fR and returns the result obtained from it. +.PP +If \fBOSSL_CMP_CTX_set_transfer_cb_arg\fR\|(3) has been used to set the transfer +callback argument then the provided pointer \fIbios\fR is taken as +a two\-element \fBBIO\fR array to use for the exchange with the server +as described for the \fIbio\fR and \fIrbio\fR parameters of \fBOSSL_HTTP_open\fR\|(3). +For instance, the two BIO pointers may be equal and refer to a TLS connection, +such as in BRSKI\-AE where a pre\-established TLS channel is reused for CMP. +.PP +Otherwise the server specified via \fBOSSL_CMP_CTX_set1_server\fR\|(3) +and optionally \fBOSSL_CMP_CTX_set_serverPort\fR\|(3) is contacted, +where the default port is 80 for HTTP and 443 for HTTPS. +The HTTP path (aka "CMP alias" in this context) to use is by default \f(CW\*(C`/\*(C'\fR, +otherwise the string specified via \fBOSSL_CMP_CTX_set1_serverPath\fR\|(3). +On success the function returns the server\*(Aqs response PKIMessage. +.PP +The function makes use of any HTTP callback function +set via \fBOSSL_CMP_CTX_set_http_cb\fR\|(3). +It respects any timeout value set via \fBOSSL_CMP_CTX_set_option\fR\|(3) +with an \fBOSSL_CMP_OPT_MSG_TIMEOUT\fR argument. +It also respects any HTTP(S) proxy options set via \fBOSSL_CMP_CTX_set1_proxy\fR\|(3) +and \fBOSSL_CMP_CTX_set1_no_proxy\fR\|(3) and the respective environment variables. +Proxying plain HTTP is supported directly, +while using a proxy for HTTPS connections requires a suitable callback function +such as \fBOSSL_HTTP_proxy_connect\fR\|(3). +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +HTTP transfer for CMP is defined in RFC 9811. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_MSG_http_perform()\fR +returns the received CMP response message on success, else NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_HTTP_open\fR\|(3), and \fBOSSL_HTTP_proxy_connect\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +The \fBOSSL_CMP_MSG_http_perform()\fR use of transfer_cb_arg was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_SRV_CTX_new.3 b/static/netbsd/man3/OSSL_CMP_SRV_CTX_new.3 new file mode 100644 index 00000000..c5092e21 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_SRV_CTX_new.3 @@ -0,0 +1,256 @@ +.\" $NetBSD: OSSL_CMP_SRV_CTX_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_SRV_CTX_new 3" +.TH OSSL_CMP_SRV_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_SRV_process_request, +OSSL_CMP_CTX_server_perform, +OSSL_CMP_SRV_CTX_new, +OSSL_CMP_SRV_CTX_free, +OSSL_CMP_SRV_cert_request_cb_t, +OSSL_CMP_SRV_rr_cb_t, +OSSL_CMP_SRV_certConf_cb_t, +OSSL_CMP_SRV_genm_cb_t, +OSSL_CMP_SRV_error_cb_t, +OSSL_CMP_SRV_pollReq_cb_t, +OSSL_CMP_SRV_CTX_init, +OSSL_CMP_SRV_delayed_delivery_cb_t, +OSSL_CMP_SRV_clean_transaction_cb_t, +OSSL_CMP_SRV_CTX_init_trans, +OSSL_CMP_SRV_CTX_get0_cmp_ctx, +OSSL_CMP_SRV_CTX_get0_custom_ctx, +OSSL_CMP_SRV_CTX_set_send_unprotected_errors, +OSSL_CMP_SRV_CTX_set_accept_unprotected, +OSSL_CMP_SRV_CTX_set_accept_raverified, +OSSL_CMP_SRV_CTX_set_grant_implicit_confirm +\&\- generic functions to set up and control a CMP server +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_MSG *OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req); +\& OSSL_CMP_MSG *OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX *client_ctx, +\& const OSSL_CMP_MSG *req); +\& OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(OSSL_LIB_CTX *libctx, const char *propq); +\& void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx); +\& +\& typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_cert_request_cb_t)( +\& OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& int certReqId, +\& const OSSL_CRMF_MSG *crm, +\& const X509_REQ *p10cr, +\& X509 **certOut, +\& STACK_OF(X509) **chainOut, +\& STACK_OF(X509) **caPubs); +\& typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& const X509_NAME *issuer, +\& const ASN1_INTEGER *serial); +\& typedef int (*OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& STACK_OF(OSSL_CMP_ITAV) *in, +\& STACK_OF(OSSL_CMP_ITAV) **out); +\& typedef void (*OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& const OSSL_CMP_PKISI *statusInfo, +\& const ASN1_INTEGER *errorCode, +\& const OSSL_CMP_PKIFREETEXT *errorDetails); +\& typedef int (*OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& int certReqId, +\& const ASN1_OCTET_STRING *certHash, +\& const OSSL_CMP_PKISI *si); +\& typedef int (*OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req, +\& int certReqId, +\& OSSL_CMP_MSG **certReq, +\& int64_t *check_after); +\& int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX *srv_ctx, void *custom_ctx, +\& OSSL_CMP_SRV_cert_request_cb_t process_cert_request, +\& OSSL_CMP_SRV_rr_cb_t process_rr, +\& OSSL_CMP_SRV_genm_cb_t process_genm, +\& OSSL_CMP_SRV_error_cb_t process_error, +\& OSSL_CMP_SRV_certConf_cb_t process_certConf, +\& OSSL_CMP_SRV_pollReq_cb_t process_pollReq); +\& typedef int (*OSSL_CMP_SRV_delayed_delivery_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const OSSL_CMP_MSG *req); +\& typedef int (*OSSL_CMP_SRV_clean_transaction_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx, +\& const ASN1_OCTET_STRING *id); +\& int OSSL_CMP_SRV_CTX_init_trans(OSSL_CMP_SRV_CTX *srv_ctx, +\& OSSL_CMP_SRV_delayed_delivery_cb_t delay, +\& OSSL_CMP_SRV_clean_transaction_cb_t clean); +\& +\& OSSL_CMP_CTX *OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX *srv_ctx); +\& void *OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX *srv_ctx); +\& +\& int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx, +\& int val); +\& int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val); +\& int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val); +\& int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx, +\& int val); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CMP_SRV_process_request()\fR implements the generic aspects of a CMP server. +Its arguments are the \fBOSSL_CMP_SRV_CTX\fR \fIsrv_ctx\fR and the CMP request message +\&\fIreq\fR. It does the typical generic checks on \fIreq\fR, calls +the respective callback function (if present) for more specific processing, +and then assembles a result message, which may be a CMP error message. +If after return of the function the expression +\&\fIOSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))\fR yields \-1 +then the function has closed the current transaction, +which may be due to normal successful end of the transaction or due to an error. +.PP +\&\fBOSSL_CMP_CTX_server_perform()\fR is an interface to +\&\fBOSSL_CMP_SRV_process_request()\fR that can be used by a CMP client +in the same way as \fBOSSL_CMP_MSG_http_perform\fR\|(3). +In particular, the first parameter \fIclient_ctx\fR is the \fBOSSL_CMP_CTX\fR of the client. +The \fBOSSL_CMP_SRV_CTX\fR must be set as \fItransfer_cb_arg\fR of \fIclient_ctx\fR. +.PP +\&\fBOSSL_CMP_SRV_CTX_new()\fR creates and initializes an \fBOSSL_CMP_SRV_CTX\fR structure +associated with the library context \fIlibctx\fR and property query string +\&\fIpropq\fR, both of which may be NULL to select the defaults. +.PP +\&\fBOSSL_CMP_SRV_CTX_free()\fR deletes the given \fIsrv_ctx\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_CMP_SRV_CTX_init()\fR sets in the given \fIsrv_ctx\fR a custom server context +pointer as well as callback functions performing the specific processing of CMP +certificate requests, revocation requests, certificate confirmation requests, +general messages, error messages, and poll requests. +All arguments except \fIsrv_ctx\fR may be NULL. +If a callback for some message type is not given this means that the respective +type of CMP message is not supported by the server. +.PP +\&\fBOSSL_CMP_SRV_CTX_init_trans()\fR sets in \fIsrv_ctx\fR the optional callback +functions for initiating delayed delivery and cleaning up a transaction. +If the function is NULL then delivery of responses is never delayed. +Otherwise \fIdelay\fR takes a custom server context and a request message as input. +It must return 1 if delivery of the respective response shall be delayed, +0 if not, and \-1 on error. +If the function is NULL then no specific cleanup is performed. +Otherwise \fIclean\fR takes a custom server context and a transaction ID pointer +as input, where the pointer is NULL in case a new transaction is being started +and otherwise provides the ID of the transaction being terminated. +The function should reset the respective portions of the state +and free related memory. +It must return 1 on success and 0 on error. +.PP +\&\fBOSSL_CMP_SRV_CTX_get0_cmp_ctx()\fR returns the \fBOSSL_CMP_CTX\fR from the \fIsrv_ctx\fR. +.PP +\&\fBOSSL_CMP_SRV_CTX_get0_custom_ctx()\fR returns the custom server context from +\&\fIsrv_ctx\fR that has been set using \fBOSSL_CMP_SRV_CTX_init()\fR. +.PP +\&\fBOSSL_CMP_SRV_CTX_set_send_unprotected_errors()\fR enables sending error messages +and other forms of negative responses unprotected. +.PP +\&\fBOSSL_CMP_SRV_CTX_set_accept_unprotected()\fR enables acceptance of requests +without protection of with invalid protection. +.PP +\&\fBOSSL_CMP_SRV_CTX_set_accept_raverified()\fR enables acceptance of ir/cr/kur +messages with POPO \*(AqRAVerified\*(Aq. +.PP +\&\fBOSSL_CMP_SRV_CTX_set_grant_implicit_confirm()\fR enables granting implicit +confirmation of newly enrolled certificates if requested. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810 (and CRMF in RFC 4211). +.PP +So far the CMP server implementation is limited to one request per CMP message +(and consequently to at most one response component per CMP message). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_SRV_CTX_new()\fR returns a \fBOSSL_CMP_SRV_CTX\fR structure on success, +NULL on error. +.PP +\&\fBOSSL_CMP_SRV_CTX_free()\fR does not return a value. +.PP +\&\fBOSSL_CMP_SRV_CTX_get0_cmp_ctx()\fR returns a \fBOSSL_CMP_CTX\fR structure on success, +NULL on error. +.PP +\&\fBOSSL_CMP_SRV_CTX_get0_custom_ctx()\fR returns the custom server context +that has been set using \fBOSSL_CMP_SRV_CTX_init()\fR. +.PP +All other functions return 1 on success, 0 on error. +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_SRV_CTX_init_trans()\fR +supporting delayed delivery of all types of response messages +was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_STATUSINFO_new.3 b/static/netbsd/man3/OSSL_CMP_STATUSINFO_new.3 new file mode 100644 index 00000000..a95e07cf --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_STATUSINFO_new.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: OSSL_CMP_STATUSINFO_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_STATUSINFO_new 3" +.TH OSSL_CMP_STATUSINFO_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_STATUSINFO_new, +OSSL_CMP_snprint_PKIStatusInfo, +OSSL_CMP_CTX_snprint_PKIStatus +\&\- function(s) for managing the CMP PKIStatus +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CMP_PKISI *OSSL_CMP_STATUSINFO_new(int status, int fail_info, +\& const char *text); +\& char *OSSL_CMP_snprint_PKIStatusInfo(const OSSL_CMP_PKISI *statusInfo, +\& char *buf, size_t bufsize); +\& char *OSSL_CMP_CTX_snprint_PKIStatus(const OSSL_CMP_CTX *ctx, char *buf, +\& size_t bufsize); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is the PKIStatus API for using CMP (Certificate Management Protocol) with +OpenSSL. +.PP +\&\fBOSSL_CMP_STATUSINFO_new()\fR creates a new PKIStatusInfo structure +and fills in the given values. +It sets the status field to \fIstatus\fR, +copies \fItext\fR (unless it is NULL) to statusString, +and interprets \fIfail_info\fR as bit pattern for the failInfo field. +.PP +\&\fBOSSL_CMP_snprint_PKIStatusInfo()\fR places a human\-readable string +representing the given statusInfo +in the given buffer, with the given maximal length. +.PP +\&\fBOSSL_CMP_CTX_snprint_PKIStatus()\fR places a human\-readable string +representing the PKIStatusInfo components of the CMP context \fIctx\fR +in the given buffer, with the given maximal length. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_STATUSINFO_new()\fR +returns a pointer to the structure on success, or NULL on error. +.PP +\&\fBOSSL_CMP_snprint_PKIStatusInfo()\fR and +\&\fBOSSL_CMP_CTX_snprint_PKIStatus()\fR +return a copy of the buffer pointer containing the string or NULL on error. +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_exec_certreq.3 b/static/netbsd/man3/OSSL_CMP_exec_certreq.3 new file mode 100644 index 00000000..9f7b4f38 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_exec_certreq.3 @@ -0,0 +1,320 @@ +.\" $NetBSD: OSSL_CMP_exec_certreq.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_exec_certreq 3" +.TH OSSL_CMP_exec_certreq 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_exec_certreq, +OSSL_CMP_exec_IR_ses, +OSSL_CMP_exec_CR_ses, +OSSL_CMP_exec_P10CR_ses, +OSSL_CMP_exec_KUR_ses, +OSSL_CMP_IR, +OSSL_CMP_CR, +OSSL_CMP_P10CR, +OSSL_CMP_KUR, +OSSL_CMP_try_certreq, +OSSL_CMP_exec_RR_ses, +OSSL_CMP_exec_GENM_ses, +OSSL_CMP_get1_caCerts, +OSSL_CMP_get1_rootCaKeyUpdate, +OSSL_CMP_get1_crlUpdate, +OSSL_CMP_get1_certReqTemplate +\&\- functions implementing CMP client transactions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type, +\& const OSSL_CRMF_MSG *crm); +\& X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx); +\& X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx); +\& X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx); +\& X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx); +\& #define OSSL_CMP_IR +\& #define OSSL_CMP_CR +\& #define OSSL_CMP_P10CR +\& #define OSSL_CMP_KUR +\& int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, +\& const OSSL_CRMF_MSG *crm, int *checkAfter); +\& int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx); +\& +\& STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx); +\& int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out); +\& int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx, +\& const X509 *oldWithOld, X509 **newWithNew, +\& X509 **newWithOld, X509 **oldWithNew); +\& int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert, +\& const X509_CRL *last_crl, +\& X509_CRL **crl); +\& int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx, +\& OSSL_CRMF_CERTTEMPLATE **certTemplate, +\& OSSL_CMP_ATAVS **keySpec); +\&=head1 DESCRIPTION +.Ve +.PP +This is the OpenSSL API for doing CMP (Certificate Management Protocol) +client\-server transactions, i.e., sequences of CMP requests and responses. +.PP +All functions take a populated OSSL_CMP_CTX structure as their first argument. +Usually the server name, port, and path ("CMP alias") need to be set, as well as +credentials the client can use for authenticating itself to the server. +In order to authenticate the server the client typically needs a trust store. +The functions return their respective main results directly, while there are +also accessor functions for retrieving various results and status information +from the \fIctx\fR. See \fBOSSL_CMP_CTX_new\fR\|(3) etc. for details. +.PP +The default conveying protocol is HTTP. +Timeout values may be given per request\-response pair and per transaction. +See \fBOSSL_CMP_MSG_http_perform\fR\|(3) for details. +.PP +\&\fBOSSL_CMP_exec_IR_ses()\fR requests an initial certificate from the given PKI. +.PP +\&\fBOSSL_CMP_exec_CR_ses()\fR requests an additional certificate. +.PP +\&\fBOSSL_CMP_exec_P10CR_ses()\fR conveys a legacy PKCS#10 CSR requesting a certificate. +.PP +\&\fBOSSL_CMP_exec_KUR_ses()\fR obtains an updated certificate. +.PP +These four types of certificate enrollment are implemented as macros +calling \fBOSSL_CMP_exec_certreq()\fR. +.PP +\&\fBOSSL_CMP_exec_certreq()\fR performs a certificate request of the type specified +by the \fIreq_type\fR parameter, which may be IR, CR, P10CR, or KUR. +For IR, CR, and KUR, the certificate template to be used in the request +may be supplied via the \fIcrm\fR parameter pointing to a CRMF structure. +Typically \fIcrm\fR is NULL, then the template ingredients are taken from \fIctx\fR +and need to be filled in using \fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), +\&\fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), etc. +For P10CR, \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3) needs to be used instead. +The enrollment session may be blocked (with polling and sleeping in between) +until the server side can fully process and ultimately answer the request. +.PP +\&\fBOSSL_CMP_try_certreq()\fR is an alternative to the above functions that is +more flexible regarding what to do after receiving a checkAfter value. +When called for the first time (with no certificate request in progress for +the given \fIctx\fR) it starts a new transaction by sending a certificate request +constructed as stated above using the \fIreq_type\fR and optional \fIcrm\fR parameter. +Otherwise (when according to \fIctx\fR a \*(Aqwaiting\*(Aq status has been received before) +it continues polling for the pending request +unless the \fIreq_type\fR argument is < 0, which aborts the request. +If the requested certificate is available the function returns 1 and the +caller can use \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) to retrieve the new certificate. +If no error occurred but no certificate is available yet then +\&\fBOSSL_CMP_try_certreq()\fR remembers in the CMP context that it should be retried +and returns \-1 after assigning the received checkAfter value +via the output pointer argument (unless it is NULL). +The checkAfter value indicates the number of seconds the caller should let pass +before trying again. The caller is free to sleep for the given number of seconds +or for some other time and/or to do anything else before retrying by calling +\&\fBOSSL_CMP_try_certreq()\fR again with the same parameter values as before. +\&\fBOSSL_CMP_try_certreq()\fR then polls +to see whether meanwhile the requested certificate is available. +If the caller decides to abort the pending certificate request and provides +a negative value as the \fIreq_type\fR argument then \fBOSSL_CMP_try_certreq()\fR +aborts the CMP transaction by sending an error message to the server. +.PP +\&\fBOSSL_CMP_exec_RR_ses()\fR requests the revocation of the certificate +specified in the \fIctx\fR using the issuer DN and serial number set by +\&\fBOSSL_CMP_CTX_set1_issuer\fR\|(3) and \fBOSSL_CMP_CTX_set1_serialNumber\fR\|(3), respectively, +otherwise the issuer DN and serial number +of the certificate set by \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), +otherwise the subject DN and public key +of the certificate signing request set by \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3). +RFC 9810 is vague in which PKIStatus should be returned by the server. +We take "accepted" and "grantedWithMods" as clear success and handle +"revocationWarning" and "revocationNotification" just as warnings because CAs +typically return them as an indication that the certificate was already revoked. +"rejection" is a clear error. The values "waiting" and "keyUpdateWarning" +make no sense for revocation and thus are treated as an error as well. +The revocation session may be blocked (with polling and sleeping in between) +until the server can fully process and ultimately answer the request. +.PP +\&\fBOSSL_CMP_exec_GENM_ses()\fR sends a genm general message containing the sequence of +infoType and infoValue pairs (InfoTypeAndValue; short: \fBITAV\fR) +optionally provided in the \fIctx\fR using \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3). +The message exchange may be blocked (with polling and sleeping in between) +until the server can fully process and ultimately answer the request. +On success the function records in \fIctx\fR status \fBOSSL_CMP_PKISTATUS_accepted\fR +and returns the list of \fBITAV\fRs received in a genp response message. +This can be used, for instance, +with infoType \f(CW\*(C`signKeyPairTypes\*(C'\fR to obtain the set of signature +algorithm identifiers that the CA will certify for subject public keys. +See RFC 9810 section 5.3.19 and appendix D.5 for details. +Functions implementing more specific genm/genp exchanges are described next. +.PP +\&\fBOSSL_CMP_get1_caCerts()\fR uses a genm/genp message exchange with infoType caCerts +to obtain a list of CA certificates from the CMP server referenced by \fIctx\fR. +On success it assigns to \fI*out\fR the list of certificates received, +which must be freed by the caller. +NULL output means that no CA certificates were provided by the server. +.PP +\&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR uses a genm request message +with infoType rootCaCert to obtain from the CMP server referenced by \fIctx\fR +in a genp response message with infoType rootCaKeyUpdate any update of the +given root CA certificate \fIoldWithOld\fR and verifies it as far as possible. +See RFC 9810 section 4.4 for details. +On success it assigns to \fI*newWithNew\fR the root certificate received. +When the \fInewWithOld\fR and \fIoldWithNew\fR output parameters are not NULL, +it assigns to them the corresponding transition certificates. +NULL means that the respective certificate was not provided by the server. +All certificates obtained this way must be freed by the caller. +.PP +\&\fBWARNING:\fR +The \fInewWithNew\fR certificate is meant to be a certificate that will be trusted. +The trust placed in it cannot be stronger than the trust placed in +the \fIoldwithold\fR certificate if present, otherwise it cannot be stronger than +the weakest trust in any of the certificates in the trust store of \fIctx\fR. +.PP +\&\fBOSSL_CMP_get1_crlUpdate()\fR uses a genm request message with infoType crlStatusList +to obtain CRL from the CMP server referenced by \fIctx\fR in a genp response message +with infoType crls. It uses \fIlast_crl\fR and \fIcrlcert\fR to create +a request with a status field as described for \fBOSSL_CMP_CRLSTATUS_create\fR\|(3). +On success it assigns to \fI*crl\fR the CRL received. +NULL means that no CRL was provided by the server. +The CRL obtained this way must be freed by the caller. +.PP +\&\fBOSSL_CMP_get1_certReqTemplate()\fR uses a genm request message with +infoType certReqTemplate to obtain a certificate request template from the +CMP server referenced by \fIctx\fR. On success it assigns to \fI*certTemplate\fR +the certificate template received. NULL output means that no certificate +request template was provided by the server. +The optional \fIkeySpec\fR output parameter is assigned the key specification +if received, otherwise it set to NULL. +Both must be freed by the caller. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810 (and CRMF in RFC 4211). +.PP +The CMP client implementation is limited to one request per CMP message +(and consequently to at most one response component per CMP message). +.PP +When a client obtains from a CMP server CA certificates that it is going to +trust, for instance via the caPubs field of a certificate response or using +functions like \fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR, +authentication of the CMP server is particularly critical. +So special care must be taken setting up server authentication in \fIctx\fR +using functions such as +\&\fBOSSL_CMP_CTX_set0_trusted\fR\|(3) (for certificate\-based authentication) or +\&\fBOSSL_CMP_CTX_set1_secretValue\fR\|(3) (for MAC\-based protection). +If authentication is certificate\-based, \fBOSSL_CMP_CTX_get0_validatedSrvCert\fR\|(3) +should be used to obtain the server validated certificate +and perform an authorization check based on it. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_exec_certreq()\fR, \fBOSSL_CMP_exec_IR_ses()\fR, \fBOSSL_CMP_exec_CR_ses()\fR, +\&\fBOSSL_CMP_exec_P10CR_ses()\fR, and \fBOSSL_CMP_exec_KUR_ses()\fR return a +pointer to the newly obtained X509 certificate on success, NULL on error. +This pointer will be freed implicitly by \fBOSSL_CMP_CTX_free()\fR or +\&\fBCSSL_CMP_CTX_reinit()\fR. +.PP +\&\fBOSSL_CMP_try_certreq()\fR returns 1 if the requested certificate is available +via \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) +or on successfully aborting a pending certificate request, 0 on error, and \-1 +in case a \*(Aqwaiting\*(Aq status has been received and checkAfter value is available. +In the latter case \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) yields NULL +and the output parameter \fIcheckAfter\fR has been used to +assign the received value unless \fIcheckAfter\fR is NULL. +.PP +\&\fBOSSL_CMP_exec_RR_ses()\fR, \fBOSSL_CMP_get1_caCerts()\fR, +\&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR, \fBOSSL_CMP_get1_crlUpdate()\fR +and \fBOSSL_CMP_get1_certReqTemplate()\fR +return 1 on success, 0 on error. +.PP +\&\fBOSSL_CMP_exec_GENM_ses()\fR returns NULL on error, +otherwise a pointer to the sequence of \fBITAV\fR received, which may be empty. +This pointer must be freed by the caller. +.SH EXAMPLES +.IX Header "EXAMPLES" +See OSSL_CMP_CTX for examples on how to prepare the context for these +functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_CTX_free\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), \fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), +\&\fBOSSL_CMP_CTX_get0_newCert\fR\|(3), \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3), +\&\fBOSSL_CMP_MSG_http_perform\fR\|(3), \fBOSSL_CMP_CRLSTATUS_create\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR +were added in OpenSSL 3.2. +.PP +Support for delayed delivery of all types of response messages +was added in OpenSSL 3.3. +.PP +\&\fBOSSL_CMP_get1_crlUpdate()\fR and \fBOSSL_CMP_get1_certReqTemplate()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_log_open.3 b/static/netbsd/man3/OSSL_CMP_log_open.3 new file mode 100644 index 00000000..154f7f7b --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_log_open.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: OSSL_CMP_log_open.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_log_open 3" +.TH OSSL_CMP_log_open 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_log_open, +OSSL_CMP_log_close, +OSSL_CMP_severity, +OSSL_CMP_LOG_EMERG, +OSSL_CMP_LOG_ALERT, +OSSL_CMP_LOG_CRIT, +OSSL_CMP_LOG_ERR, +OSSL_CMP_LOG_WARNING, +OSSL_CMP_LOG_NOTICE, +OSSL_CMP_LOG_INFO, +OSSL_CMP_LOG_DEBUG, +OSSL_CMP_LOG_TRACE, +.PP +OSSL_CMP_log_cb_t, +OSSL_CMP_print_to_bio, +OSSL_CMP_print_errors_cb +\&\- functions for logging and error reporting +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_CMP_log_open(void); +\& void OSSL_CMP_log_close(void); +\& +\& /* severity level declarations resemble those from syslog.h */ +\& typedef int OSSL_CMP_severity; +\& #define OSSL_CMP_LOG_EMERG 0 +\& #define OSSL_CMP_LOG_ALERT 1 +\& #define OSSL_CMP_LOG_CRIT 2 +\& #define OSSL_CMP_LOG_ERR 3 +\& #define OSSL_CMP_LOG_WARNING 4 +\& #define OSSL_CMP_LOG_NOTICE 5 +\& #define OSSL_CMP_LOG_INFO 6 +\& #define OSSL_CMP_LOG_DEBUG 7 +\& #define OSSL_CMP_LOG_TRACE 8 +\& +\& typedef int (*OSSL_CMP_log_cb_t)(const char *component, +\& const char *file, int line, +\& OSSL_CMP_severity level, const char *msg); +\& int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file, +\& int line, OSSL_CMP_severity level, const char *msg); +\& void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The logging and error reporting facility described here contains +convenience functions for CMP\-specific logging, +including a string prefix mirroring the severity levels of syslog.h, +and enhancements of the error queue mechanism needed for large diagnostic +messages produced by the CMP library in case of certificate validation failures. +.PP +When an interesting activity is performed or an error occurs, some detail +should be provided for user information, debugging, and auditing purposes. +A CMP application can obtain this information by providing a callback function +with the following type: +.PP +.Vb 3 +\& typedef int (*OSSL_CMP_log_cb_t)(const char *component, +\& const char *file, int line, +\& OSSL_CMP_severity level, const char *msg); +.Ve +.PP +The parameters may provide +some component info (which may be a module name and/or function name) or NULL, +a file pathname or NULL, +a line number or 0 indicating the source code location, +a severity level, and +a message string describing the nature of the event, terminated by \*(Aq\en\*(Aq. +.PP +Even when an activity is successful some warnings may be useful and some degree +of auditing may be required. Therefore, the logging facility supports a severity +level and the callback function has a \fIlevel\fR parameter indicating such a +level, such that error, warning, info, debug, etc. can be treated differently. +The callback is activated only when the severity level is sufficient according +to the current level of verbosity, which by default is \fBOSSL_CMP_LOG_INFO\fR. +.PP +The callback function may itself do non\-trivial tasks like writing to +a log file or remote stream, which in turn may fail. +Therefore, the function should return 1 on success and 0 on failure. +.PP +\&\fBOSSL_CMP_log_open()\fR initializes the CMP\-specific logging facility to output +everything to STDOUT. It fails if the integrated tracing is disabled or STDIO +is not available. It may be called during application startup. +Alternatively, \fBOSSL_CMP_CTX_set_log_cb\fR\|(3) can be used for more flexibility. +As long as neither if the two is used any logging output is ignored. +.PP +\&\fBOSSL_CMP_log_close()\fR may be called when all activities are finished to flush +any pending CMP\-specific log output and deallocate related resources. +It may be called multiple times. It does get called at OpenSSL shutdown. +.PP +\&\fBOSSL_CMP_print_to_bio()\fR prints the given component info, filename, line number, +severity level, and log message or error queue message to the given \fIbio\fR. +\&\fIcomponent\fR usually is a function or module name. +If it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback. +.PP +\&\fBOSSL_CMP_print_errors_cb()\fR outputs any entries in the OpenSSL error queue. +It is similar to \fBERR_print_errors_cb\fR\|(3) but uses the CMP log callback +function \fIlog_fn\fR for uniformity with CMP logging if not NULL. Otherwise it +prints to STDERR using \fBOSSL_CMP_print_to_bio\fR\|(3) (unless \fBOPENSSL_NO_STDIO\fR +is defined). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_log_close()\fR and \fBOSSL_CMP_print_errors_cb()\fR do not return anything. +.PP +All other functions return 1 on success, 0 on error. +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CMP_validate_msg.3 b/static/netbsd/man3/OSSL_CMP_validate_msg.3 new file mode 100644 index 00000000..f6eed714 --- /dev/null +++ b/static/netbsd/man3/OSSL_CMP_validate_msg.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: OSSL_CMP_validate_msg.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_validate_msg 3" +.TH OSSL_CMP_validate_msg 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CMP_validate_msg, +OSSL_CMP_validate_cert_path +\&\- functions for verifying CMP message protection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 4 +\& #include +\& int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); +\& int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx, +\& X509_STORE *trusted_store, X509 *cert); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This is the API for validating the protection of CMP messages, +which includes validating CMP message sender certificates and their paths +while optionally checking the revocation status of the certificates(s). +.PP +\&\fBOSSL_CMP_validate_msg()\fR validates the protection of the given \fImsg\fR, +which must be signature\-based or using password\-based MAC (PBM). +In the former case a suitable trust anchor must be given in the CMP context +\&\fIctx\fR, and in the latter case the matching secret must have been set there +using \fBOSSL_CMP_CTX_set1_secretValue\fR\|(3). +.PP +In case of signature algorithm, the certificate to use for the signature check +is preferably the one provided by a call to \fBOSSL_CMP_CTX_set1_srvCert\fR\|(3). +If no such sender cert has been pinned then candidate sender certificates are +taken from the list of certificates received in the \fImsg\fR extraCerts, then any +certificates provided before via \fBOSSL_CMP_CTX_set1_untrusted\fR\|(3), and +then all trusted certificates provided via \fBOSSL_CMP_CTX_set0_trusted\fR\|(3). +A candidate certificate is acceptable only if it is currently valid +(or the trust store contains a verification callback that overrides the verdict +that the certificate is expired or not yet valid), its subject DN matches +the \fImsg\fR sender DN (as far as present), and its subject key identifier +is present and matches the senderKID (as far as the latter is present). +Each acceptable cert is tried in the given order to see if the message +signature check succeeds and the cert and its path can be verified +using any trust store set via \fBOSSL_CMP_CTX_set0_trusted\fR\|(3). +.PP +If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling +\&\fBOSSL_CMP_CTX_set_option\fR\|(3), for an Initialization Response (IP) message +any self\-issued certificate from the \fImsg\fR extraCerts field may be used +as a trust anchor for the path verification of an \*(Aqacceptable\*(Aq cert if it can be +used also to validate the issued certificate returned in the IP message. This is +according to TS 33.310 [Network Domain Security (NDS); Authentication Framework +(AF)] document specified by The 3rd Generation Partnership Project (3GPP). +Note that using this option is dangerous as the certificate obtained this way +has not been authenticated (at least not at CMP level). +Taking it over as a trust anchor implements trust\-on\-first\-use (TOFU). +.PP +Any cert that has been found as described above is cached and tried first when +validating the signatures of subsequent messages in the same transaction. +.PP +\&\fBOSSL_CMP_validate_cert_path()\fR attempts to validate the given certificate and its +path using the given store of trusted certs (possibly including CRLs and a cert +verification callback) and non\-trusted intermediate certs from the \fIctx\fR. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CMP_validate_msg()\fR and \fBOSSL_CMP_validate_cert_path()\fR +return 1 on success, 0 on error or validation failed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_exec_certreq\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_secretValue\fR\|(3), \fBOSSL_CMP_CTX_set1_srvCert\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_untrusted\fR\|(3), \fBOSSL_CMP_CTX_set0_trusted\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CMP support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CORE_MAKE_FUNC.3 b/static/netbsd/man3/OSSL_CORE_MAKE_FUNC.3 new file mode 100644 index 00000000..61d3a617 --- /dev/null +++ b/static/netbsd/man3/OSSL_CORE_MAKE_FUNC.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: OSSL_CORE_MAKE_FUNC.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CORE_MAKE_FUNC 3" +.TH OSSL_CORE_MAKE_FUNC 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CORE_MAKE_FUNC, +SSL_OP_BIT, +EXT_UTF8STRING +\&\- OpenSSL reserved symbols +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define OSSL_CORE_MAKE_FUNC(type,name,args) +\& #define SSL_OP_BIT(n) +\& #define EXT_UTF8STRING(nid) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +There are certain macros that may appear in OpenSSL header files that are +reserved for internal use. They should not be used by applications or assumed +to exist. +.PP +All the macros listed in the synopsis above are reserved. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not applicable. +.SH HISTORY +.IX Header "HISTORY" +The macros described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CRMF_MSG_get0_tmpl.3 b/static/netbsd/man3/OSSL_CRMF_MSG_get0_tmpl.3 new file mode 100644 index 00000000..134f63f1 --- /dev/null +++ b/static/netbsd/man3/OSSL_CRMF_MSG_get0_tmpl.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: OSSL_CRMF_MSG_get0_tmpl.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CRMF_MSG_get0_tmpl 3" +.TH OSSL_CRMF_MSG_get0_tmpl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CRMF_MSG_get0_tmpl, +OSSL_CRMF_CERTTEMPLATE_get0_publicKey, +OSSL_CRMF_CERTTEMPLATE_get0_subject, +OSSL_CRMF_CERTTEMPLATE_get0_issuer, +OSSL_CRMF_CERTTEMPLATE_get0_serialNumber, +OSSL_CRMF_CERTTEMPLATE_get0_extensions, +OSSL_CRMF_CERTID_get0_serialNumber, +OSSL_CRMF_CERTID_get0_issuer, +OSSL_CRMF_ENCRYPTEDKEY_get1_encCert, +OSSL_CRMF_ENCRYPTEDKEY_get1_pkey, +OSSL_CRMF_ENCRYPTEDKEY_init_envdata, +OSSL_CRMF_ENCRYPTEDVALUE_decrypt, +OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert, +OSSL_CRMF_MSG_get_certReqId, +OSSL_CRMF_MSG_centralkeygen_requested +\&\- functions reading from CRMF CertReqMsg structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_CRMF_CERTTEMPLATE *OSSL_CRMF_MSG_get0_tmpl(const OSSL_CRMF_MSG *crm); +\& X509_PUBKEY +\& *OSSL_CRMF_CERTTEMPLATE_get0_publicKey(const OSSL_CRMF_CERTTEMPLATE *tmpl); +\& const X509_NAME +\& *OSSL_CRMF_CERTTEMPLATE_get0_subject(const OSSL_CRMF_CERTTEMPLATE *tmpl); +\& const X509_NAME +\& *OSSL_CRMF_CERTTEMPLATE_get0_issuer(const OSSL_CRMF_CERTTEMPLATE *tmpl); +\& const ASN1_INTEGER +\& *OSSL_CRMF_CERTTEMPLATE_get0_serialNumber(const OSSL_CRMF_CERTTEMPLATE *tmpl); +\& X509_EXTENSIONS +\& *OSSL_CRMF_CERTTEMPLATE_get0_extensions(const OSSL_CRMF_CERTTEMPLATE *tmpl); +\& +\& const ASN1_INTEGER +\& *OSSL_CRMF_CERTID_get0_serialNumber(const OSSL_CRMF_CERTID *cid); +\& const X509_NAME *OSSL_CRMF_CERTID_get0_issuer(const OSSL_CRMF_CERTID *cid); +\& +\& X509 *OSSL_CRMF_ENCRYPTEDKEY_get1_encCert(const OSSL_CRMF_ENCRYPTEDKEY *ecert, +\& OSSL_LIB_CTX *libctx, const char *propq, +\& EVP_PKEY *pkey, unsigned int flags); +\& EVP_PKEY +\& *OSSL_CRMF_ENCRYPTEDKEY_get1_pkey(OSSL_CRMF_ENCRYPTEDKEY *encryptedKey, +\& X509_STORE *ts, STACK_OF(X509) *extra, +\& EVP_PKEY *pkey, X509 *cert, +\& ASN1_OCTET_STRING *secret, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& OSSL_CRMF_ENCRYPTEDKEY +\& *OSSL_CRMF_ENCRYPTEDKEY_init_envdata(CMS_EnvelopedData *envdata); +\& +\& unsigned char +\& *OSSL_CRMF_ENCRYPTEDVALUE_decrypt(const OSSL_CRMF_ENCRYPTEDVALUE *enc, +\& OSSL_LIB_CTX *libctx, const char *propq, +\& EVP_PKEY *pkey, int *outlen); +\& X509 +\& *OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(const OSSL_CRMF_ENCRYPTEDVALUE *ecert, +\& OSSL_LIB_CTX *libctx, const char *propq, +\& EVP_PKEY *pkey); +\& +\& int OSSL_CRMF_MSG_get_certReqId(const OSSL_CRMF_MSG *crm); +\& int OSSL_CRMF_MSG_centralkeygen_requested(const OSSL_CRMF_MSG *crm, +\& const X509_REQ *p10cr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CRMF_MSG_get0_tmpl()\fR retrieves the certificate template of \fIcrm\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_publicKey()\fR retrieves the public key of the +given certificate template \fItmpl\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_subject()\fR retrieves the subject name of the +given certificate template \fItmpl\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_issuer()\fR retrieves the issuer name of the +given certificate template \fItmpl\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_serialNumber()\fR retrieves the serialNumber of the +given certificate template \fItmpl\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_extensions()\fR retrieves the X.509 extensions +of the given certificate template \fItmpl\fR, or NULL if not present. +.PP +OSSL_CRMF_CERTID_get0_serialNumber retrieves the serialNumber +of the given CertId \fIcid\fR. +.PP +OSSL_CRMF_CERTID_get0_issuer retrieves the issuer name +of the given CertId \fIcid\fR, which must be of ASN.1 type GEN_DIRNAME. +.PP +\&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_encCert()\fR decrypts the certificate in the given +encryptedKey \fIecert\fR, using the private key \fIpkey\fR, library context +\&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)). +This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2. +The function returns the decrypted certificate as a copy, leaving its ownership +with the caller, who is responsible for freeing it. +.PP +\&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_pkey()\fR decrypts the private key in \fIencryptedKey\fR. +If \fIencryptedKey\fR is not of type \fBOSSL_CRMF_ENCRYPTEDKEY_ENVELOPEDDATA\fR, +decryption uses the private key \fIpkey\fR. +The library context \fIlibctx\fR and property query \fIpropq\fR are taken into account as usual. +The rest of this paragraph is relevant only if CMS support not disabled for the OpenSSL build +and \fIencryptedKey\fR is of type case \fBOSSL_CRMF_ENCRYPTEDKEY_ENVELOPEDDATA\fR. +Decryption uses the \fIsecret\fR parameter if not NULL; +otherwise uses the private key and the certificate \fIcert\fR +related to \fIpkey\fR, where \fIcert\fR is recommended to be given if available. +On success, the function verifies the decrypted data as signed data, +using the trust store \fIts\fR and any untrusted certificates in \fIextra\fR. +Doing so, it checks for the purpose "CMP Key Generation Authority" (cmKGA). +.PP +\&\fBOSSL_CRMF_ENCRYPTEDKEY_init_envdata()\fR returns \fIOSSL_CRMF_ENCRYPTEDKEY\fR, initialized with +the enveloped data \fIenvdata\fR. +.PP +\&\fBOSSL_CRMF_ENCRYPTEDVALUE_decrypt()\fR decrypts the encrypted value in the given +encryptedValue \fIenc\fR, using the private key \fIpkey\fR, library context +\&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)). +.PP +\&\fBOSSL_CRMF_ENCRYPTEDVALUE_get1_encCert()\fR decrypts the certificate in the given +encryptedValue \fIecert\fR, using the private key \fIpkey\fR, library context +\&\fIlibctx\fR and property query string \fIpropq\fR (see \fBOSSL_LIB_CTX\fR\|(3)). +This is needed for the indirect POPO method as in RFC 9810 section 5.2.8.3.2. +The function returns the decrypted certificate as a copy, leaving its ownership +with the caller, who is responsible for freeing it. +.PP +\&\fBOSSL_CRMF_MSG_get_certReqId()\fR retrieves the certReqId of \fIcrm\fR. +.PP +\&\fBOSSL_CRMF_MSG_centralkeygen_requested()\fR returns 1 if central key generation +is requested i.e., the public key in the certificate request (\fIcrm\fR is taken if it is non\-NULL, +otherwise \fIp10cr\fR) is NULL or has an empty key value (with length zero). +In case \fIcrm\fR is non\-NULL, this is checked for consistency with its \fBpopo\fR field +(must be NULL if and only if central key generation is requested). +Otherwise it returns 0, and on error a negative value. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CRMF_MSG_get_certReqId()\fR returns the certificate request ID as a +nonnegative integer or \-1 on error. +.PP +\&\fBOSSL_CRMF_MSG_centralkeygen_requested()\fR returns 1 if central key generation +is requested, 0 if it is not requested, and a negative value on error. +.PP +All other functions return a pointer with the intended result or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +RFC 4211 +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CRMF support was added in OpenSSL 3.0. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_get0_publicKey()\fR was added in OpenSSL 3.2. +.PP +\&\fBOSSL_CRMF_ENCRYPTEDKEY_get1_encCert()\fR, \fBOSSL_CRMF_ENCRYPTEDKEY_get1_pkey()\fR, +\&\fBOSSL_CRMF_ENCRYPTEDKEY_init_envdata()\fR, \fBOSSL_CRMF_ENCRYPTEDVALUE_decrypt()\fR +and \fBOSSL_CRMF_MSG_centralkeygen_requested()\fR were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CRMF_MSG_set0_validity.3 b/static/netbsd/man3/OSSL_CRMF_MSG_set0_validity.3 new file mode 100644 index 00000000..7bc9afaf --- /dev/null +++ b/static/netbsd/man3/OSSL_CRMF_MSG_set0_validity.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: OSSL_CRMF_MSG_set0_validity.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CRMF_MSG_set0_validity 3" +.TH OSSL_CRMF_MSG_set0_validity 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CRMF_MSG_set0_validity, +OSSL_CRMF_MSG_set_certReqId, +OSSL_CRMF_CERTTEMPLATE_fill, +OSSL_CRMF_MSG_set0_extensions, +OSSL_CRMF_MSG_push0_extension, +OSSL_CRMF_MSG_create_popo, +OSSL_CRMF_MSGS_verify_popo +\&\- functions populating and verifying CRMF CertReqMsg structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_CRMF_MSG_set0_validity(OSSL_CRMF_MSG *crm, +\& ASN1_TIME *notBefore, ASN1_TIME *notAfter); +\& +\& int OSSL_CRMF_MSG_set_certReqId(OSSL_CRMF_MSG *crm, int rid); +\& +\& int OSSL_CRMF_CERTTEMPLATE_fill(OSSL_CRMF_CERTTEMPLATE *tmpl, +\& EVP_PKEY *pubkey, +\& const X509_NAME *subject, +\& const X509_NAME *issuer, +\& const ASN1_INTEGER *serial); +\& +\& int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm, X509_EXTENSIONS *exts); +\& +\& int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm, X509_EXTENSION *ext); +\& +\& int OSSL_CRMF_MSG_create_popo(int meth, OSSL_CRMF_MSG *crm, +\& EVP_PKEY *pkey, const EVP_MD *digest, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& int OSSL_CRMF_MSGS_verify_popo(const OSSL_CRMF_MSGS *reqs, +\& int rid, int acceptRAVerified, +\& OSSL_LIB_CTX *libctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CRMF_MSG_set0_validity()\fR sets the \fInotBefore\fR and \fInotAfter\fR fields +as validity constraints in the certTemplate of \fIcrm\fR. +Any of the \fInotBefore\fR and \fInotAfter\fR parameters may be NULL, +which means no constraint for the respective field. +On success ownership of \fInotBefore\fR and \fInotAfter\fR is transferred to \fIcrm\fR. +.PP +\&\fBOSSL_CRMF_MSG_set_certReqId()\fR sets \fIrid\fR as the certReqId of \fIcrm\fR. +.PP +\&\fBOSSL_CRMF_CERTTEMPLATE_fill()\fR sets those fields of the certTemplate \fItmpl\fR +for which non\-NULL values are provided: \fIpubkey\fR, \fIsubject\fR, \fIissuer\fR, +and/or \fIserial\fR. +X.509 extensions may be set using \fBOSSL_CRMF_MSG_set0_extensions()\fR. +On success the reference counter of the \fIpubkey\fR (if given) is incremented, +while the \fIsubject\fR, \fIissuer\fR, and \fIserial\fR structures (if given) are copied. +.PP +\&\fBOSSL_CRMF_MSG_set0_extensions()\fR sets \fIexts\fR as the extensions in the +certTemplate of \fIcrm\fR. Frees any pre\-existing ones and consumes \fIexts\fR. +.PP +\&\fBOSSL_CRMF_MSG_push0_extension()\fR pushes the X509 extension \fIext\fR to the +extensions in the certTemplate of \fIcrm\fR. Consumes \fIext\fR. +.PP +\&\fBOSSL_CRMF_MSG_create_popo()\fR creates and sets the Proof\-of\-Possession (POPO) +according to the method \fImeth\fR in \fIcrm\fR. +The library context \fIlibctx\fR and property query string \fIpropq\fR, +may be NULL to select the defaults. +In case the method is OSSL_CRMF_POPO_SIGNATURE the POPO is calculated +using the private key \fIpkey\fR and the digest method \fIdigest\fR, +where the \fIdigest\fR argument is ignored if \fIpkey\fR is of a type (such as +Ed25519 and Ed448) that is implicitly associated with a digest algorithm. +.PP +\&\fImeth\fR can be one of the following: +.IP \(bu 8 +OSSL_CRMF_POPO_NONE \- RFC 4211, section 4, POP field omitted. +CA/RA uses out\-of\-band method to verify POP. Note that servers may fail in this +case, resulting for instance in HTTP error code 500 (Internal error). +.IP \(bu 8 +OSSL_CRMF_POPO_RAVERIFIED \- RFC 4211, section 4, explicit indication +that the RA has already verified the POP. +.IP \(bu 8 +OSSL_CRMF_POPO_SIGNATURE \- RFC 4211, section 4.1, only case 3 supported +so far. +.IP \(bu 8 +OSSL_CRMF_POPO_KEYENC \- RFC 4211, section 4.2, only indirect method +(subsequentMessage/enccert) supported, +challenge\-response exchange (challengeResp) not yet supported. +.IP \(bu 8 +OSSL_CRMF_POPO_KEYAGREE \- RFC 4211, section 4.3, not yet supported. +.PP +OSSL_CRMF_MSGS_verify_popo verifies the Proof\-of\-Possession of the request with +the given \fIrid\fR in the list of \fIreqs\fR. Optionally accepts RAVerified. It can +make use of the library context \fIlibctx\fR and property query string \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +RFC 4211 +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CRMF support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.3 b/static/netbsd/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.3 new file mode 100644 index 00000000..613363bf --- /dev/null +++ b/static/netbsd/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: OSSL_CRMF_MSG_set1_regCtrl_regToken.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CRMF_MSG_set1_regCtrl_regToken 3" +.TH OSSL_CRMF_MSG_set1_regCtrl_regToken 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CRMF_MSG_get0_regCtrl_regToken, +OSSL_CRMF_MSG_set1_regCtrl_regToken, +OSSL_CRMF_MSG_get0_regCtrl_authenticator, +OSSL_CRMF_MSG_set1_regCtrl_authenticator, +OSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo, +OSSL_CRMF_MSG_set0_SinglePubInfo, +OSSL_CRMF_MSG_set_PKIPublicationInfo_action, +OSSL_CRMF_MSG_get0_regCtrl_pkiPublicationInfo, +OSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo, +OSSL_CRMF_MSG_get0_regCtrl_protocolEncrKey, +OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey, +OSSL_CRMF_MSG_get0_regCtrl_oldCertID, +OSSL_CRMF_MSG_set1_regCtrl_oldCertID, +OSSL_CRMF_CERTID_gen +\&\- functions getting or setting CRMF Registration Controls +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_UTF8STRING +\& *OSSL_CRMF_MSG_get0_regCtrl_regToken(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regCtrl_regToken(OSSL_CRMF_MSG *msg, +\& const ASN1_UTF8STRING *tok); +\& ASN1_UTF8STRING +\& *OSSL_CRMF_MSG_get0_regCtrl_authenticator(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regCtrl_authenticator(OSSL_CRMF_MSG *msg, +\& const ASN1_UTF8STRING *auth); +\& int OSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo( +\& OSSL_CRMF_PKIPUBLICATIONINFO *pi, +\& OSSL_CRMF_SINGLEPUBINFO *spi); +\& int OSSL_CRMF_MSG_set0_SinglePubInfo(OSSL_CRMF_SINGLEPUBINFO *spi, +\& int method, GENERAL_NAME *nm); +\& int OSSL_CRMF_MSG_set_PKIPublicationInfo_action( +\& OSSL_CRMF_PKIPUBLICATIONINFO *pi, int action); +\& OSSL_CRMF_PKIPUBLICATIONINFO +\& *OSSL_CRMF_MSG_get0_regCtrl_pkiPublicationInfo(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo(OSSL_CRMF_MSG *msg, +\& const OSSL_CRMF_PKIPUBLICATIONINFO *pi); +\& X509_PUBKEY +\& *OSSL_CRMF_MSG_get0_regCtrl_protocolEncrKey(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey(OSSL_CRMF_MSG *msg, +\& const X509_PUBKEY *pubkey); +\& OSSL_CRMF_CERTID +\& *OSSL_CRMF_MSG_get0_regCtrl_oldCertID(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regCtrl_oldCertID(OSSL_CRMF_MSG *msg, +\& const OSSL_CRMF_CERTID *cid); +\& OSSL_CRMF_CERTID *OSSL_CRMF_CERTID_gen(const X509_NAME *issuer, +\& const ASN1_INTEGER *serial); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Each of the \fBOSSL_CRMF_MSG_get0_regCtrl_X()\fR functions +returns the respective control X in the given \fImsg\fR, if present. +.PP +\&\fBOSSL_CRMF_MSG_set1_regCtrl_regToken()\fR sets the regToken control in the given +\&\fImsg\fR copying the given \fItok\fR as value. See RFC 4211, section 6.1. +.PP +\&\fBOSSL_CRMF_MSG_set1_regCtrl_authenticator()\fR sets the authenticator control in +the given \fImsg\fR copying the given \fIauth\fR as value. See RFC 4211, section 6.2. +.PP +\&\fBOSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo()\fR pushes the given \fIspi\fR +to \fIsi\fR. Consumes the \fIspi\fR pointer. +.PP +\&\fBOSSL_CRMF_MSG_set0_SinglePubInfo()\fR sets in the given SinglePubInfo \fIspi\fR +the \fImethod\fR and publication location, in the form of a GeneralName, \fInm\fR. +The publication location is optional, and therefore \fInm\fR may be NULL. +The function consumes the \fInm\fR pointer if present. +Available methods are: + # define OSSL_CRMF_PUB_METHOD_DONTCARE 0 + # define OSSL_CRMF_PUB_METHOD_X500 1 + # define OSSL_CRMF_PUB_METHOD_WEB 2 + # define OSSL_CRMF_PUB_METHOD_LDAP 3 +.PP +\&\fBOSSL_CRMF_MSG_set_PKIPublicationInfo_action()\fR sets the action in the given \fIpi\fR +using the given \fIaction\fR as value. See RFC 4211, section 6.3. +Available actions are: + # define OSSL_CRMF_PUB_ACTION_DONTPUBLISH 0 + # define OSSL_CRMF_PUB_ACTION_PLEASEPUBLISH 1 +.PP +\&\fBOSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo()\fR sets the pkiPublicationInfo +control in the given \fImsg\fR copying the given \fItok\fR as value. See RFC 4211, +section 6.3. +.PP +\&\fBOSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey()\fR sets the protocolEncrKey control in +the given \fImsg\fR copying the given \fIpubkey\fR as value. See RFC 4211 section 6.6. +.PP +\&\fBOSSL_CRMF_MSG_set1_regCtrl_oldCertID()\fR sets the \fBoldCertID\fR regToken control in +the given \fImsg\fR copying the given \fIcid\fR as value. See RFC 4211, section 6.5. +.PP +OSSL_CRMF_CERTID_gen produces an OSSL_CRMF_CERTID_gen structure copying the +given \fIissuer\fR name and \fIserial\fR number. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All OSSL_CRMF_MSG_get0_*() functions +return the respective pointer value or NULL if not present and on error. +.PP +All OSSL_CRMF_MSG_set1_*() functions return 1 on success, 0 on error. +.PP +\&\fBOSSL_CRMF_CERTID_gen()\fR returns a pointer to the resulting structure +or NULL on error. +.SH NOTES +.IX Header "NOTES" +A function \fBOSSL_CRMF_MSG_set1_regCtrl_pkiArchiveOptions()\fR for setting an +Archive Options Control is not yet implemented due to missing features to +create the needed OSSL_CRMF_PKIARCHIVEOPTINS content. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +RFC 4211 +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CRMF support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.3 b/static/netbsd/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.3 new file mode 100644 index 00000000..e507eeac --- /dev/null +++ b/static/netbsd/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: OSSL_CRMF_MSG_set1_regInfo_certReq.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CRMF_MSG_set1_regInfo_certReq 3" +.TH OSSL_CRMF_MSG_set1_regInfo_certReq 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CRMF_MSG_get0_regInfo_utf8Pairs, +OSSL_CRMF_MSG_set1_regInfo_utf8Pairs, +OSSL_CRMF_MSG_get0_regInfo_certReq, +OSSL_CRMF_MSG_set1_regInfo_certReq +\&\- functions getting or setting CRMF Registration Info +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_UTF8STRING +\& *OSSL_CRMF_MSG_get0_regInfo_utf8Pairs(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regInfo_utf8Pairs(OSSL_CRMF_MSG *msg, +\& const ASN1_UTF8STRING *utf8pairs); +\& OSSL_CRMF_CERTREQUEST +\& *OSSL_CRMF_MSG_get0_regInfo_certReq(const OSSL_CRMF_MSG *msg); +\& int OSSL_CRMF_MSG_set1_regInfo_certReq(OSSL_CRMF_MSG *msg, +\& const OSSL_CRMF_CERTREQUEST *cr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CRMF_MSG_get0_regInfo_utf8Pairs()\fR returns the first utf8Pairs regInfo +in the given \fImsg\fR, if present. +.PP +\&\fBOSSL_CRMF_MSG_set1_regInfo_utf8Pairs()\fR adds a copy of the given \fIutf8pairs\fR +value as utf8Pairs regInfo to the given \fImsg\fR. See RFC 4211 section 7.1. +.PP +\&\fBOSSL_CRMF_MSG_get0_regInfo_certReq()\fR returns the first certReq regInfo +in the given \fImsg\fR, if present. +.PP +\&\fBOSSL_CRMF_MSG_set1_regInfo_certReq()\fR adds a copy of the given \fIcr\fR value +as certReq regInfo to the given \fImsg\fR. See RFC 4211 section 7.2. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All get0_*() functions return the respective pointer value, NULL if not present. +.PP +All set1_*() functions return 1 on success, 0 on error. +.SH NOTES +.IX Header "NOTES" +Calling the set1_*() functions multiple times +adds multiple instances of the respective +control to the regInfo structure of the given \fImsg\fR. While RFC 4211 expects +multiple utf8Pairs in one regInfo structure, it does not allow multiple certReq. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +RFC 4211 +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CRMF support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_CRMF_pbmp_new.3 b/static/netbsd/man3/OSSL_CRMF_pbmp_new.3 new file mode 100644 index 00000000..9fcae4f4 --- /dev/null +++ b/static/netbsd/man3/OSSL_CRMF_pbmp_new.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: OSSL_CRMF_pbmp_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CRMF_pbmp_new 3" +.TH OSSL_CRMF_pbmp_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_CRMF_pbm_new, +OSSL_CRMF_pbmp_new +\&\- functions for producing Password\-Based MAC (PBM) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_CRMF_pbm_new(OSSL_LIB_CTX *libctx, const char *propq, +\& const OSSL_CRMF_PBMPARAMETER *pbmp, +\& const unsigned char *msg, size_t msglen, +\& const unsigned char *sec, size_t seclen, +\& unsigned char **mac, size_t *maclen); +\& +\& OSSL_CRMF_PBMPARAMETER *OSSL_CRMF_pbmp_new(OSSL_LIB_CTX *libctx, size_t saltlen, +\& int owfnid, size_t itercnt, +\& int macnid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_CRMF_pbm_new()\fR generates a PBM (Password\-Based MAC) based on given PBM +parameters \fIpbmp\fR, message \fImsg\fR, and secret \fIsec\fR, along with the respective +lengths \fImsglen\fR and \fIseclen\fR. +The optional library context \fIlibctx\fR and \fIpropq\fR parameters may be used +to influence the selection of the MAC algorithm referenced in the \fIpbmp\fR; +see "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. +On success writes the address of the newly +allocated MAC via the \fImac\fR reference parameter and writes the length via the +\&\fImaclen\fR reference parameter unless it its NULL. +.PP +\&\fBOSSL_CRMF_pbmp_new()\fR initializes and returns a new \fBPBMParameter\fR structure +with a new random salt of given length \fIsaltlen\fR, +OWF (one\-way function) NID \fIowfnid\fR, OWF iteration count \fIitercnt\fR, +and MAC NID \fImacnid\fR. +The library context \fIlibctx\fR parameter may be used to select the provider +for the random number generation (DRBG) and may be NULL for the default. +.SH NOTES +.IX Header "NOTES" +The algorithms for the OWF (one\-way function) and for the MAC (message +authentication code) may be any with a NID defined in \fI\fR. +For backward compatibility with RFC 4210, these should include NID_hmac_sha1. +.PP +RFC 4210 recommended that the salt SHOULD be at least 8 bytes (64 bits) long, +where 16 bytes is common. +.PP +The iteration count must be at least 100, as stipulated by RFC 4211, and is +limited to at most 100000 to avoid DoS through manipulated or otherwise +malformed input. +See RFC 9045 for currently suggested values. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_CRMF_pbm_new()\fR returns 1 on success, 0 on error. +.PP +\&\fBOSSL_CRMF_pbmp_new()\fR returns a new and initialized OSSL_CRMF_PBMPARAMETER +structure, or NULL on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 5 +\& OSSL_CRMF_PBMPARAMETER *pbm = NULL; +\& unsigned char *msg = "Hello"; +\& unsigned char *sec = "SeCrEt"; +\& unsigned char *mac = NULL; +\& size_t maclen; +\& +\& if ((pbm = OSSL_CRMF_pbmp_new(16, NID_sha256, 500, NID_hmac_sha1) == NULL)) +\& goto err; +\& if (!OSSL_CRMF_pbm_new(pbm, msg, 5, sec, 6, &mac, &maclen)) +\& goto err; +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +RFC 4211 section 4.4 +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL CRMF support was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_DECODER.3 b/static/netbsd/man3/OSSL_DECODER.3 new file mode 100644 index 00000000..4fe16ca3 --- /dev/null +++ b/static/netbsd/man3/OSSL_DECODER.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: OSSL_DECODER.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_DECODER 3" +.TH OSSL_DECODER 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_DECODER, +OSSL_DECODER_fetch, +OSSL_DECODER_up_ref, +OSSL_DECODER_free, +OSSL_DECODER_get0_provider, +OSSL_DECODER_get0_properties, +OSSL_DECODER_is_a, +OSSL_DECODER_get0_name, +OSSL_DECODER_get0_description, +OSSL_DECODER_do_all_provided, +OSSL_DECODER_names_do_all, +OSSL_DECODER_gettable_params, +OSSL_DECODER_get_params +\&\- Decoder method routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_decoder_st OSSL_DECODER; +\& +\& OSSL_DECODER *OSSL_DECODER_fetch(OSSL_LIB_CTX *ctx, const char *name, +\& const char *properties); +\& int OSSL_DECODER_up_ref(OSSL_DECODER *decoder); +\& void OSSL_DECODER_free(OSSL_DECODER *decoder); +\& const OSSL_PROVIDER *OSSL_DECODER_get0_provider(const OSSL_DECODER *decoder); +\& const char *OSSL_DECODER_get0_properties(const OSSL_DECODER *decoder); +\& int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name); +\& const char *OSSL_DECODER_get0_name(const OSSL_DECODER *decoder); +\& const char *OSSL_DECODER_get0_description(const OSSL_DECODER *decoder); +\& void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(OSSL_DECODER *decoder, void *arg), +\& void *arg); +\& int OSSL_DECODER_names_do_all(const OSSL_DECODER *decoder, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const OSSL_PARAM *OSSL_DECODER_gettable_params(OSSL_DECODER *decoder); +\& int OSSL_DECODER_get_params(OSSL_DECODER_CTX *ctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_DECODER\fR is a method for decoders, which know how to +decode encoded data into an object of some type that the rest +of OpenSSL knows how to handle. +.PP +\&\fBOSSL_DECODER_fetch()\fR looks for an algorithm within the provider that +has been loaded into the \fBOSSL_LIB_CTX\fR given by \fIctx\fR, having the +name given by \fIname\fR and the properties given by \fIproperties\fR. +The \fIname\fR determines what type of object the fetched decoder +method is expected to be able to decode, and the properties are +used to determine the expected output type. +For known properties and the values they may have, please have a look +in "Names and properties" in \fBprovider\-encoder\fR\|(7). +.PP +\&\fBOSSL_DECODER_up_ref()\fR increments the reference count for the given +\&\fIdecoder\fR. +.PP +\&\fBOSSL_DECODER_free()\fR decrements the reference count for the given +\&\fIdecoder\fR, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_DECODER_get0_provider()\fR returns the provider of the given +\&\fIdecoder\fR. +.PP +\&\fBOSSL_DECODER_get0_properties()\fR returns the property definition associated +with the given \fIdecoder\fR. +.PP +\&\fBOSSL_DECODER_is_a()\fR checks if \fIdecoder\fR is an implementation +of an algorithm that\*(Aqs identifiable with \fIname\fR. +.PP +\&\fBOSSL_DECODER_get0_name()\fR returns the name used to fetch the given \fIdecoder\fR. +.PP +\&\fBOSSL_DECODER_get0_description()\fR returns a description of the \fIdecoder\fR, meant +for display and human consumption. The description is at the discretion +of the \fIdecoder\fR implementation. +.PP +\&\fBOSSL_DECODER_names_do_all()\fR traverses all names for the given +\&\fIdecoder\fR, and calls \fIfn\fR with each name and \fIdata\fR as arguments. +.PP +\&\fBOSSL_DECODER_do_all_provided()\fR traverses all decoder +implementations by all activated providers in the library context +\&\fIlibctx\fR, and for each of the implementations, calls \fIfn\fR with the +implementation method and \fIarg\fR as arguments. +.PP +\&\fBOSSL_DECODER_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) +array of parameter descriptors. +.PP +\&\fBOSSL_DECODER_get_params()\fR attempts to get parameters specified +with an \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. Parameters that the +implementation doesn\*(Aqt recognise should be ignored. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_DECODER_fetch()\fR returns a pointer to an OSSL_DECODER object, +or NULL on error. +.PP +\&\fBOSSL_DECODER_up_ref()\fR returns 1 on success, or 0 on error. +.PP +\&\fBOSSL_DECODER_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBOSSL_DECODER_get0_provider()\fR returns a pointer to a provider object, or +NULL on error. +.PP +\&\fBOSSL_DECODER_get0_properties()\fR returns a pointer to a property +definition string, or NULL on error. +.PP +\&\fBOSSL_DECODER_is_a()\fR returns 1 if \fIdecoder\fR was identifiable, +otherwise 0. +.PP +\&\fBOSSL_DECODER_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIdecoder\fR. Note that the \fIdecoder\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIdecoder\fR object and should not be freed by the caller. +.PP +\&\fBOSSL_DECODER_get0_description()\fR returns a pointer to a description, or NULL if +there isn\*(Aqt one. +.PP +\&\fBOSSL_DECODER_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.SH NOTES +.IX Header "NOTES" +\&\fBOSSL_DECODER_fetch()\fR may be called implicitly by other fetching +functions, using the same library context and properties. +Any other API that uses keys will typically do this. +.SH EXAMPLES +.IX Header "EXAMPLES" +To list all decoders in a provider to a bio_out: +.PP +.Vb 3 +\& static void collect_decoders(OSSL_DECODER *decoder, void *stack) +\& { +\& STACK_OF(OSSL_DECODER) *decoder_stack = stack; +\& +\& sk_OSSL_DECODER_push(decoder_stack, decoder); +\& OSSL_DECODER_up_ref(decoder); +\& } +\& +\& void print_name(const char *name, void *vdata) +\& { +\& BIO *bio = vdata; +\& +\& BIO_printf(bio, "%s ", name); +\& } +\& +\& +\& STACK_OF(OSSL_DECODER) *decoders; +\& int i; +\& +\& decoders = sk_OSSL_DECODER_new_null(); +\& +\& BIO_printf(bio_out, "DECODERs provided by %s:\en", provider); +\& OSSL_DECODER_do_all_provided(NULL, collect_decoders, +\& decoders); +\& +\& for (i = 0; i < sk_OSSL_DECODER_num(decoders); i++) { +\& OSSL_DECODER *decoder = sk_OSSL_DECODER_value(decoders, i); +\& +\& if (strcmp(OSSL_PROVIDER_get0_name(OSSL_DECODER_get0_provider(decoder)), +\& provider) != 0) +\& continue; +\& +\& if (OSSL_DECODER_names_do_all(decoder, print_name, bio_out)) +\& BIO_printf(bio_out, "\en"); +\& } +\& sk_OSSL_DECODER_pop_free(decoders, OSSL_DECODER_free); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_DECODER_CTX\fR\|(3), \fBOSSL_DECODER_from_bio\fR\|(3), +\&\fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3), \fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_DECODER_CTX.3 b/static/netbsd/man3/OSSL_DECODER_CTX.3 new file mode 100644 index 00000000..d821bc6c --- /dev/null +++ b/static/netbsd/man3/OSSL_DECODER_CTX.3 @@ -0,0 +1,316 @@ +.\" $NetBSD: OSSL_DECODER_CTX.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_DECODER_CTX 3" +.TH OSSL_DECODER_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_DECODER_CTX, +OSSL_DECODER_CTX_new, +OSSL_DECODER_settable_ctx_params, +OSSL_DECODER_CTX_set_params, +OSSL_DECODER_CTX_free, +OSSL_DECODER_CTX_set_selection, +OSSL_DECODER_CTX_set_input_type, +OSSL_DECODER_CTX_set_input_structure, +OSSL_DECODER_CTX_add_decoder, +OSSL_DECODER_CTX_add_extra, +OSSL_DECODER_CTX_get_num_decoders, +OSSL_DECODER_INSTANCE, +OSSL_DECODER_CONSTRUCT, +OSSL_DECODER_CLEANUP, +OSSL_DECODER_CTX_set_construct, +OSSL_DECODER_CTX_set_construct_data, +OSSL_DECODER_CTX_set_cleanup, +OSSL_DECODER_CTX_get_construct, +OSSL_DECODER_CTX_get_construct_data, +OSSL_DECODER_CTX_get_cleanup, +OSSL_DECODER_export, +OSSL_DECODER_INSTANCE_get_decoder, +OSSL_DECODER_INSTANCE_get_decoder_ctx, +OSSL_DECODER_INSTANCE_get_input_type, +OSSL_DECODER_INSTANCE_get_input_structure +\&\- Decoder context routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX; +\& +\& OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void); +\& const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder); +\& int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx, +\& const OSSL_PARAM params[]); +\& void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx); +\& +\& int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection); +\& int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx, +\& const char *input_type); +\& int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx, +\& const char *input_structure); +\& int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder); +\& int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx, +\& OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx); +\& +\& typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE; +\& OSSL_DECODER * +\& OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst); +\& void * +\& OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst); +\& const char * +\& OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst); +\& OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst, +\& int *was_set); +\& +\& typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst, +\& const OSSL_PARAM *object, +\& void *construct_data); +\& typedef void OSSL_DECODER_CLEANUP(void *construct_data); +\& +\& int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx, +\& OSSL_DECODER_CONSTRUCT *construct); +\& int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx, +\& void *construct_data); +\& int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx, +\& OSSL_DECODER_CLEANUP *cleanup); +\& OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx); +\& void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx); +\& OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx); +\& +\& int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst, +\& void *reference, size_t reference_sz, +\& OSSL_CALLBACK *export_cb, void *export_cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBOSSL_DECODER_CTX\fR holds data about multiple decoders, as needed to +figure out what the input data is and to attempt to unpack it into one of +several possible related results. This also includes chaining decoders, so +the output from one can become the input for another. This allows having +generic format decoders such as PEM to DER, as well as more specialized +decoders like DER to RSA. +.PP +The chains may be limited by specifying an input type, which is considered a +starting point. This is both considered by \fBOSSL_DECODER_CTX_add_extra()\fR, +which will stop adding one more decoder implementations when it has already +added those that take the specified input type, and functions like +\&\fBOSSL_DECODER_from_bio\fR\|(3), which will only start the decoding process with +the decoder implementations that take that input type. For example, if the +input type is set to \f(CW\*(C`DER\*(C'\fR, a PEM to DER decoder will be ignored. +.PP +The input type can also be NULL, which means that the caller doesn\*(Aqt know +what type of input they have. In this case, \fBOSSL_DECODER_from_bio()\fR will +simply try with one decoder implementation after the other, and thereby +discover what kind of input the caller gave it. +.PP +For every decoding done, even an intermediary one, a constructor provided by +the caller is called to attempt to construct an appropriate type / structure +that the caller knows how to handle from the current decoding result. +The constructor is set with \fBOSSL_DECODER_CTX_set_construct()\fR. +.PP +\&\fBOSSL_DECODER_INSTANCE\fR is an opaque structure that contains data about the +decoder that was just used, and that may be useful for the constructor. +There are some functions to extract data from this type, described further +down. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_DECODER_CTX_new()\fR creates a new empty \fBOSSL_DECODER_CTX\fR. +.PP +\&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array of +parameter descriptors. +.PP +\&\fBOSSL_DECODER_CTX_set_params()\fR attempts to set parameters specified with an +\&\fBOSSL_PARAM\fR\|(3) array \fIparams\fR. These parameters are passed to all +decoders that have been added to the \fIctx\fR so far. Parameters that an +implementation doesn\*(Aqt recognise should be ignored by it. +.PP +\&\fBOSSL_DECODER_CTX_free()\fR frees the given context \fIctx\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_DECODER_CTX_add_decoder()\fR populates the \fBOSSL_DECODER_CTX\fR \fIctx\fR with +a decoder, to be used to attempt to decode some encoded input. +.PP +\&\fBOSSL_DECODER_CTX_add_extra()\fR finds decoders that generate input for already +added decoders, and adds them as well. This is used to build decoder +chains. +.PP +\&\fBOSSL_DECODER_CTX_set_input_type()\fR sets the starting input type. This limits +the decoder chains to be considered, as explained in the general description +above. +.PP +\&\fBOSSL_DECODER_CTX_set_input_structure()\fR sets the name of the structure that +the input is expected to have. This may be used to determines what decoder +implementations may be used. NULL is a valid input structure, when it\*(Aqs not +relevant, or when the decoder implementations are expected to figure it out. +.PP +\&\fBOSSL_DECODER_CTX_get_num_decoders()\fR gets the number of decoders currently +added to the context \fIctx\fR. +.PP +\&\fBOSSL_DECODER_CTX_set_construct()\fR sets the constructor \fIconstruct\fR. +.PP +\&\fBOSSL_DECODER_CTX_set_construct_data()\fR sets the constructor data that is +passed to the constructor every time it\*(Aqs called. +.PP +\&\fBOSSL_DECODER_CTX_set_cleanup()\fR sets the constructor data \fIcleanup\fR +function. This is called by \fBOSSL_DECODER_CTX_free\fR\|(3). +.PP +\&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and +\&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the values that have been set by +\&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and +\&\fBOSSL_DECODER_CTX_set_cleanup()\fR respectively. +.PP +\&\fBOSSL_DECODER_export()\fR is a fallback function for constructors that cannot +use the data they get directly for diverse reasons. It takes the same +decode instance \fIdecoder_inst\fR that the constructor got and an object +\&\fIreference\fR, unpacks the object which it refers to, and exports it by +creating an \fBOSSL_PARAM\fR\|(3) array that it then passes to \fIexport_cb\fR, +along with \fIexport_arg\fR. +.PP +Note that functions \fBOSSL_DECODER_CTX_set_selection()\fR, +\&\fBOSSL_DECODER_CTX_set_output_type()\fR, \fBOSSL_DECODER_CTX_set_output_structure()\fR, +\&\fBOSSL_DECODER_CTX_add_encoder()\fR, \fBOSSL_DECODER_CTX_add_extra()\fR, +\&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR, and +\&\fBOSSL_DECODER_CTX_set_cleanup()\fR shouldn\*(Aqt be used after the context is finalised, +in particular after calling the function \fBOSSL_DECODER_CTX_new_for_pkey()\fR. +.SS Constructor +.IX Subsection "Constructor" +A \fBOSSL_DECODER_CONSTRUCT\fR gets the following arguments: +.IP \fIdecoder_inst\fR 4 +.IX Item "decoder_inst" +The \fBOSSL_DECODER_INSTANCE\fR for the decoder from which the constructor gets +its data. +.IP \fIobject\fR 4 +.IX Item "object" +A provider\-native object abstraction produced by the decoder. Further +information on the provider\-native object abstraction can be found in +\&\fBprovider\-object\fR\|(7). +.IP \fIconstruct_data\fR 4 +.IX Item "construct_data" +The pointer that was set with \fBOSSL_DECODE_CTX_set_construct_data()\fR. +.PP +The constructor is expected to return 1 when the data it receives can be +constructed, otherwise 0. +.PP +These utility functions may be used by a constructor: +.PP +\&\fBOSSL_DECODER_INSTANCE_get_decoder()\fR can be used to get the decoder +implementation from a decoder instance \fIdecoder_inst\fR. +.PP +\&\fBOSSL_DECODER_INSTANCE_get_decoder_ctx()\fR can be used to get the decoder +implementation\*(Aqs provider context from a decoder instance \fIdecoder_inst\fR. +.PP +\&\fBOSSL_DECODER_INSTANCE_get_input_type()\fR can be used to get the decoder +implementation\*(Aqs input type from a decoder instance \fIdecoder_inst\fR. +.PP +\&\fBOSSL_DECODER_INSTANCE_get_input_structure()\fR can be used to get the input +structure for the decoder implementation from a decoder instance +\&\fIdecoder_inst\fR. +This may be NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_DECODER_CTX_new()\fR returns a pointer to a \fBOSSL_DECODER_CTX\fR, or NULL +if the context structure couldn\*(Aqt be allocated. +.PP +\&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array, or +NULL if none is available. +.PP +\&\fBOSSL_DECODER_CTX_set_params()\fR returns 1 if all recognised parameters were +valid, or 0 if one of them was invalid or caused some other failure in the +implementation. +.PP +\&\fBOSSL_DECODER_CTX_add_decoder()\fR, \fBOSSL_DECODER_CTX_add_extra()\fR, +\&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and +\&\fBOSSL_DECODER_CTX_set_cleanup()\fR return 1 on success, or 0 on failure. +.PP +\&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and +\&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the current pointers to the +constructor, the constructor data and the cleanup functions, respectively. +.PP +\&\fBOSSL_DECODER_CTX_num_decoders()\fR returns the current number of decoders. It +returns 0 if \fIctx\fR is NULL. +.PP +\&\fBOSSL_DECODER_export()\fR returns 1 on success, or 0 on failure. +.PP +\&\fBOSSL_DECODER_INSTANCE_decoder()\fR returns an \fBOSSL_DECODER\fR pointer on +success, or NULL on failure. +.PP +\&\fBOSSL_DECODER_INSTANCE_decoder_ctx()\fR returns a provider context pointer on +success, or NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3), \fBOSSL_DECODER_from_bio\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_DECODER_CTX_new_for_pkey.3 b/static/netbsd/man3/OSSL_DECODER_CTX_new_for_pkey.3 new file mode 100644 index 00000000..8116c4e5 --- /dev/null +++ b/static/netbsd/man3/OSSL_DECODER_CTX_new_for_pkey.3 @@ -0,0 +1,204 @@ +.\" $NetBSD: OSSL_DECODER_CTX_new_for_pkey.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_DECODER_CTX_new_for_pkey 3" +.TH OSSL_DECODER_CTX_new_for_pkey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_DECODER_CTX_new_for_pkey, +OSSL_DECODER_CTX_set_passphrase, +OSSL_DECODER_CTX_set_pem_password_cb, +OSSL_DECODER_CTX_set_passphrase_ui, +OSSL_DECODER_CTX_set_passphrase_cb +\&\- Decoder routines to decode EVP_PKEYs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_DECODER_CTX * +\& OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey, +\& const char *input_type, +\& const char *input_struct, +\& const char *keytype, int selection, +\& OSSL_LIB_CTX *libctx, const char *propquery); +\& +\& int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx, +\& const unsigned char *kstr, +\& size_t klen); +\& int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx, +\& pem_password_cb *cb, +\& void *cbarg); +\& int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx, +\& const UI_METHOD *ui_method, +\& void *ui_data); +\& int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx, +\& OSSL_PASSPHRASE_CALLBACK *cb, +\& void *cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_DECODER_CTX_new_for_pkey()\fR is a utility function that creates a +\&\fBOSSL_DECODER_CTX\fR, finds all applicable decoder implementations and sets +them up, so all the caller has to do next is call functions like +\&\fBOSSL_DECODER_from_bio\fR\|(3). The caller may use the optional \fIinput_type\fR, +\&\fIinput_struct\fR, \fIkeytype\fR and \fIselection\fR to specify what the input is +expected to contain. The \fIpkey\fR must reference an \fBEVP_PKEY *\fR variable +that will be set to the newly created \fBEVP_PKEY\fR on successful decoding. +The referenced variable must be initialized to NULL before calling the +function. +.PP +Internally \fBOSSL_DECODER_CTX_new_for_pkey()\fR searches for all available +\&\fBEVP_KEYMGMT\fR\|(3) implementations, and then builds a list of all potential +decoder implementations that may be able to process the encoded input into +data suitable for \fBEVP_PKEY\fRs. All these implementations are implicitly +fetched using \fIlibctx\fR and \fIpropquery\fR. +.PP +The search of decoder implementations can be limited with \fIinput_type\fR and +\&\fIinput_struct\fR which specifies a starting input type and input structure. +NULL is valid for both of them and signifies that the decoder implementations +will find out the input type on their own. +They are set with \fBOSSL_DECODER_CTX_set_input_type\fR\|(3) and +\&\fBOSSL_DECODER_CTX_set_input_structure\fR\|(3). +See "Input Types" and "Input Structures" below for further information. +.PP +The search of decoder implementations can also be limited with \fIkeytype\fR +and \fIselection\fR, which specifies the expected resulting keytype and contents. +NULL and zero are valid and signify that the decoder implementations will +find out the keytype and key contents on their own from the input they get. +.PP +If no suitable decoder implementation is found, +\&\fBOSSL_DECODER_CTX_new_for_pkey()\fR still creates a \fBOSSL_DECODER_CTX\fR, but +with no associated decoder (\fBOSSL_DECODER_CTX_get_num_decoders\fR\|(3) returns +zero). This helps the caller to distinguish between an error when creating +the \fBOSSL_ENCODER_CTX\fR and missing encoder implementation, and allows it to +act accordingly. +.PP +Note that \fBOSSL_DECODER_CTX_new_for_pkey()\fR finalises the OSSL_DECODER_CTX; +after that the OSSL_DECODER_CTX_set_* and OSSL_DECODER_CTX_add_* functions +described in \fBOSSL_DECODER_CTX\fR\|(3) shouldn\*(Aqt be called. +.PP +\&\fBOSSL_DECODER_CTX_set_passphrase()\fR gives the implementation a pass phrase to +use when decrypting the encoded private key. Alternatively, a pass phrase +callback may be specified with the following functions. +.PP +\&\fBOSSL_DECODER_CTX_set_pem_password_cb()\fR, \fBOSSL_DECODER_CTX_set_passphrase_ui()\fR +and \fBOSSL_DECODER_CTX_set_passphrase_cb()\fR set up a callback method that the +implementation can use to prompt for a pass phrase, giving the caller the +choice of preferred pass phrase callback form. These are called indirectly, +through an internal \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function. +.PP +The internal \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function caches the pass phrase, to +be reused in all decodings that are performed in the same decoding run (for +example, within one \fBOSSL_DECODER_from_bio\fR\|(3) call). +.SS "Input Types" +.IX Subsection "Input Types" +Available input types depend on the implementations that available providers +offer, and provider documentation should have the details. +.PP +Among the known input types that OpenSSL decoder implementations offer +for \fBEVP_PKEY\fRs are \f(CW\*(C`DER\*(C'\fR, \f(CW\*(C`PEM\*(C'\fR, \f(CW\*(C`MSBLOB\*(C'\fR and \f(CW\*(C`PVK\*(C'\fR. +See \fBopenssl\-glossary\fR\|(7) for further information on what these input +types mean. +.SS "Input Structures" +.IX Subsection "Input Structures" +Available input structures depend on the implementations that available +providers offer, and provider documentation should have the details. +.PP +Among the known input structures that OpenSSL decoder implementations +offer for \fBEVP_PKEY\fRs are \f(CW\*(C`pkcs8\*(C'\fR and \f(CW\*(C`SubjectPublicKeyInfo\*(C'\fR. +.PP +OpenSSL decoder implementations also support the input structure +\&\f(CW\*(C`type\-specific\*(C'\fR. This is the structure used for keys encoded +according to key type specific specifications. For example, RSA keys +encoded according to PKCS#1. +.SS Selections +.IX Subsection "Selections" +\&\fIselection\fR can be any one of the values described in +"Selections" in \fBEVP_PKEY_fromdata\fR\|(3). +Additionally \fIselection\fR can also be set to \fB0\fR to indicate that the code will +auto detect the selection. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_DECODER_CTX_new_for_pkey()\fR returns a pointer to a +\&\fBOSSL_DECODER_CTX\fR, or NULL if it couldn\*(Aqt be created. +.PP +\&\fBOSSL_DECODER_CTX_set_passphrase()\fR, \fBOSSL_DECODER_CTX_set_pem_password_cb()\fR, +\&\fBOSSL_DECODER_CTX_set_passphrase_ui()\fR and +\&\fBOSSL_DECODER_CTX_set_passphrase_cb()\fR all return 1 on success, or 0 on +failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_DECODER\fR\|(3), \fBOSSL_DECODER_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_DECODER_from_bio.3 b/static/netbsd/man3/OSSL_DECODER_from_bio.3 new file mode 100644 index 00000000..5f05139c --- /dev/null +++ b/static/netbsd/man3/OSSL_DECODER_from_bio.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: OSSL_DECODER_from_bio.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_DECODER_from_bio 3" +.TH OSSL_DECODER_from_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_DECODER_from_data, +OSSL_DECODER_from_bio, +OSSL_DECODER_from_fp +\&\- Routines to perform a decoding +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_DECODER_from_bio(OSSL_DECODER_CTX *ctx, BIO *in); +\& int OSSL_DECODER_from_fp(OSSL_DECODER_CTX *ctx, FILE *fp); +\& int OSSL_DECODER_from_data(OSSL_DECODER_CTX *ctx, const unsigned char **pdata, +\& size_t *pdata_len); +.Ve +.PP +Feature availability macros: +.IP "\fBOSSL_DECODER_from_fp()\fR is only available when \fBOPENSSL_NO_STDIO\fR is undefined." 4 +.IX Item "OSSL_DECODER_from_fp() is only available when OPENSSL_NO_STDIO is undefined." +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_DECODER_from_data()\fR runs the decoding process for the context \fIctx\fR, +with input coming from \fI*pdata\fR, \fI*pdata_len\fR bytes long. Both \fI*pdata\fR +and \fI*pdata_len\fR must be non\-NULL. When \fBOSSL_DECODER_from_data()\fR returns, +\&\fI*pdata\fR is updated to point at the location after what has been decoded, +and \fI*pdata_len\fR to have the number of remaining bytes. +.PP +\&\fBOSSL_DECODER_from_bio()\fR runs the decoding process for the context \fIctx\fR, +with the input coming from the \fBBIO\fR \fIin\fR. Should it make a difference, +it\*(Aqs recommended to have the BIO set in binary mode rather than text mode. +.PP +\&\fBOSSL_DECODER_from_fp()\fR does the same thing as \fBOSSL_DECODER_from_bio()\fR, +except that the input is coming from the \fBFILE\fR \fIfp\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_DECODER_from_bio()\fR, \fBOSSL_DECODER_from_data()\fR and \fBOSSL_DECODER_from_fp()\fR +return 1 on success, or 0 on failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +To decode an RSA key encoded with PEM from a bio: +.PP +.Vb 6 +\& OSSL_DECODER_CTX *dctx; +\& EVP_PKEY *pkey = NULL; +\& const char *format = "PEM"; /* NULL for any format */ +\& const char *structure = NULL; /* any structure */ +\& const char *keytype = "RSA"; /* NULL for any key */ +\& const unsigned char *pass = "my password"; +\& +\& dctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, format, structure, +\& keytype, +\& OSSL_KEYMGMT_SELECT_KEYPAIR, +\& NULL, NULL); +\& if (dctx == NULL) { +\& /* error: no suitable potential decoders found */ +\& } +\& if (pass != NULL) +\& OSSL_DECODER_CTX_set_passphrase(dctx, pass, strlen(pass)); +\& if (OSSL_DECODER_from_bio(dctx, bio)) { +\& /* pkey is created with the decoded data from the bio */ +\& } else { +\& /* decoding failure */ +\& } +\& OSSL_DECODER_CTX_free(dctx); +.Ve +.PP +To decode an EC key encoded with DER from a buffer: +.PP +.Vb 8 +\& OSSL_DECODER_CTX *dctx; +\& EVP_PKEY *pkey = NULL; +\& const char *format = "DER"; /* NULL for any format */ +\& const char *structure = NULL; /* any structure */ +\& const char *keytype = "EC"; /* NULL for any key */ +\& const unsigned char *pass = NULL +\& const unsigned char *data = buffer; +\& size_t datalen = sizeof(buffer); +\& +\& dctx = OSSL_DECODER_CTX_new_for_pkey(&pkey, format, structure, +\& keytype, +\& OSSL_KEYMGMT_SELECT_KEYPAIR +\& | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, +\& NULL, NULL); +\& if (dctx == NULL) { +\& /* error: no suitable potential decoders found */ +\& } +\& if (pass != NULL) +\& OSSL_DECODER_CTX_set_passphrase(dctx, pass, strlen(pass)); +\& if (OSSL_DECODER_from_data(dctx, &data, &datalen)) { +\& /* pkey is created with the decoded data from the buffer */ +\& } else { +\& /* decoding failure */ +\& } +\& OSSL_DECODER_CTX_free(dctx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_DECODER_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_DISPATCH.3 b/static/netbsd/man3/OSSL_DISPATCH.3 new file mode 100644 index 00000000..30fa01a9 --- /dev/null +++ b/static/netbsd/man3/OSSL_DISPATCH.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: OSSL_DISPATCH.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_DISPATCH 3" +.TH OSSL_DISPATCH 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_DISPATCH, OSSL_DISPATCH_END \- OpenSSL Core type to define a dispatchable function table +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_dispatch_st OSSL_DISPATCH; +\& struct ossl_dispatch_st { +\& int function_id; +\& void (*function)(void); +\& }; +\& +\& #define OSSL_DISPATCH_END +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This type is a tuple of function identity and function pointer. +Arrays of this type are passed between the OpenSSL libraries and the +providers to describe what functionality one side provides to the other. +.PP +Arrays of this type must be terminated with the OSSL_DISPATCH_END macro. +.SS "\fBOSSL_DISPATCH\fP fields" +.IX Subsection "OSSL_DISPATCH fields" +.IP \fIfunction_id\fR 4 +.IX Item "function_id" +OpenSSL defined function identity of the implemented function. +.IP \fIfunction\fR 4 +.IX Item "function" +Pointer to the implemented function itself. Despite the generic definition +of this field, the implemented function it points to must have a function +signature that corresponds to the \fIfunction_id\fR +.PP +Available function identities and corresponding function signatures are +defined in \fBopenssl\-core_dispatch.h\fR\|(7). +Furthermore, the chosen function identities and associated function +signature must be chosen specifically for the operation that it\*(Aqs intended +for, as determined by the intended \fBOSSL_ALGORITHM\fR\|(3) array. +.PP +Any function identity not recognised by the recipient of this type +will be ignored. +This ensures that providers built with one OpenSSL version in mind +will work together with any other OpenSSL version that supports this +mechanism. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBopenssl\-core_dispatch.h\fR\|(7), \fBOSSL_ALGORITHM\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_DISPATCH\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ENCODER.3 b/static/netbsd/man3/OSSL_ENCODER.3 new file mode 100644 index 00000000..2932f547 --- /dev/null +++ b/static/netbsd/man3/OSSL_ENCODER.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: OSSL_ENCODER.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ENCODER 3" +.TH OSSL_ENCODER 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ENCODER, +OSSL_ENCODER_fetch, +OSSL_ENCODER_up_ref, +OSSL_ENCODER_free, +OSSL_ENCODER_get0_provider, +OSSL_ENCODER_get0_properties, +OSSL_ENCODER_is_a, +OSSL_ENCODER_get0_name, +OSSL_ENCODER_get0_description, +OSSL_ENCODER_do_all_provided, +OSSL_ENCODER_names_do_all, +OSSL_ENCODER_gettable_params, +OSSL_ENCODER_get_params +\&\- Encoder method routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_encoder_st OSSL_ENCODER; +\& +\& OSSL_ENCODER *OSSL_ENCODER_fetch(OSSL_LIB_CTX *ctx, const char *name, +\& const char *properties); +\& int OSSL_ENCODER_up_ref(OSSL_ENCODER *encoder); +\& void OSSL_ENCODER_free(OSSL_ENCODER *encoder); +\& const OSSL_PROVIDER *OSSL_ENCODER_get0_provider(const OSSL_ENCODER *encoder); +\& const char *OSSL_ENCODER_get0_properties(const OSSL_ENCODER *encoder); +\& int OSSL_ENCODER_is_a(const OSSL_ENCODER *encoder, const char *name); +\& const char *OSSL_ENCODER_get0_name(const OSSL_ENCODER *encoder); +\& const char *OSSL_ENCODER_get0_description(const OSSL_ENCODER *encoder); +\& void OSSL_ENCODER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(OSSL_ENCODER *encoder, void *arg), +\& void *arg); +\& int OSSL_ENCODER_names_do_all(const OSSL_ENCODER *encoder, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const OSSL_PARAM *OSSL_ENCODER_gettable_params(OSSL_ENCODER *encoder); +\& int OSSL_ENCODER_get_params(OSSL_ENCODER_CTX *ctx, const OSSL_PARAM params[]); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_ENCODER\fR is a method for encoders, which know how to +encode an object of some kind to a encoded form, such as PEM, +DER, or even human readable text. +.PP +\&\fBOSSL_ENCODER_fetch()\fR looks for an algorithm within the provider that +has been loaded into the \fBOSSL_LIB_CTX\fR given by \fIctx\fR, having the +name given by \fIname\fR and the properties given by \fIproperties\fR. +The \fIname\fR determines what type of object the fetched encoder +method is expected to be able to encode, and the properties are +used to determine the expected output type. +For known properties and the values they may have, please have a look +in "Names and properties" in \fBprovider\-encoder\fR\|(7). +.PP +\&\fBOSSL_ENCODER_up_ref()\fR increments the reference count for the given +\&\fIencoder\fR. +.PP +\&\fBOSSL_ENCODER_free()\fR decrements the reference count for the given +\&\fIencoder\fR, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_ENCODER_get0_provider()\fR returns the provider of the given +\&\fIencoder\fR. +.PP +\&\fBOSSL_ENCODER_get0_properties()\fR returns the property definition associated +with the given \fIencoder\fR. +.PP +\&\fBOSSL_ENCODER_is_a()\fR checks if \fIencoder\fR is an implementation of an +algorithm that\*(Aqs identifiable with \fIname\fR. +.PP +\&\fBOSSL_ENCODER_get0_name()\fR returns the name used to fetch the given \fIencoder\fR. +.PP +\&\fBOSSL_ENCODER_get0_description()\fR returns a description of the \fIloader\fR, meant +for display and human consumption. The description is at the discretion of the +\&\fIloader\fR implementation. +.PP +\&\fBOSSL_ENCODER_names_do_all()\fR traverses all names for the given +\&\fIencoder\fR, and calls \fIfn\fR with each name and \fIdata\fR as arguments. +.PP +\&\fBOSSL_ENCODER_do_all_provided()\fR traverses all encoder +implementations by all activated providers in the library context +\&\fIlibctx\fR, and for each of the implementations, calls \fIfn\fR with the +implementation method and \fIarg\fR as arguments. +.PP +\&\fBOSSL_ENCODER_gettable_params()\fR returns an \fBOSSL_PARAM\fR\|(3) +array of parameter descriptors. +.PP +\&\fBOSSL_ENCODER_get_params()\fR attempts to get parameters specified +with an \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. Parameters that the +implementation doesn\*(Aqt recognise should be ignored. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ENCODER_fetch()\fR returns a pointer to the key management +implementation represented by an OSSL_ENCODER object, or NULL on +error. +.PP +\&\fBOSSL_ENCODER_up_ref()\fR returns 1 on success, or 0 on error. +.PP +\&\fBOSSL_ENCODER_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBOSSL_ENCODER_get0_provider()\fR returns a pointer to a provider object, or +NULL on error. +.PP +\&\fBOSSL_ENCODER_get0_properties()\fR returns a pointer to a property +definition string, or NULL on error. +.PP +\&\fBOSSL_ENCODER_is_a()\fR returns 1 of \fIencoder\fR was identifiable, +otherwise 0. +.PP +\&\fBOSSL_ENCODER_get0_name()\fR returns the algorithm name from the provided +implementation for the given \fIencoder\fR. Note that the \fIencoder\fR may have +multiple synonyms associated with it. In this case the first name from the +algorithm definition is returned. Ownership of the returned string is retained +by the \fIencoder\fR object and should not be freed by the caller. +.PP +\&\fBOSSL_ENCODER_get0_description()\fR returns a pointer to a description, or NULL if +there isn\*(Aqt one. +.PP +\&\fBOSSL_ENCODER_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_ENCODER_CTX\fR\|(3), \fBOSSL_ENCODER_to_bio\fR\|(3), +\&\fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3), \fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ENCODER_CTX.3 b/static/netbsd/man3/OSSL_ENCODER_CTX.3 new file mode 100644 index 00000000..a980d1b7 --- /dev/null +++ b/static/netbsd/man3/OSSL_ENCODER_CTX.3 @@ -0,0 +1,284 @@ +.\" $NetBSD: OSSL_ENCODER_CTX.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ENCODER_CTX 3" +.TH OSSL_ENCODER_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ENCODER_CTX, +OSSL_ENCODER_CTX_new, +OSSL_ENCODER_settable_ctx_params, +OSSL_ENCODER_CTX_set_params, +OSSL_ENCODER_CTX_free, +OSSL_ENCODER_CTX_set_selection, +OSSL_ENCODER_CTX_set_output_type, +OSSL_ENCODER_CTX_set_output_structure, +OSSL_ENCODER_CTX_add_encoder, +OSSL_ENCODER_CTX_add_extra, +OSSL_ENCODER_CTX_get_num_encoders, +OSSL_ENCODER_INSTANCE, +OSSL_ENCODER_INSTANCE_get_encoder, +OSSL_ENCODER_INSTANCE_get_encoder_ctx, +OSSL_ENCODER_INSTANCE_get_output_type, +OSSL_ENCODER_INSTANCE_get_output_structure, +OSSL_ENCODER_CONSTRUCT, +OSSL_ENCODER_CLEANUP, +OSSL_ENCODER_CTX_set_construct, +OSSL_ENCODER_CTX_set_construct_data, +OSSL_ENCODER_CTX_set_cleanup +\&\- Encoder context routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX; +\& +\& OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new(); +\& const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder); +\& int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx, +\& const OSSL_PARAM params[]); +\& void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx); +\& +\& int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection); +\& int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx, +\& const char *output_type); +\& int OSSL_ENCODER_CTX_set_output_structure(OSSL_ENCODER_CTX *ctx, +\& const char *output_structure); +\& +\& int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX *ctx, OSSL_ENCODER *encoder); +\& int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx); +\& +\& typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE; +\& OSSL_ENCODER * +\& OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst); +\& void * +\& OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst); +\& const char * +\& OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst); +\& const char * +\& OSSL_ENCODER_INSTANCE_get_output_structure(OSSL_ENCODER_INSTANCE *encoder_inst); +\& +\& typedef const void *OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE *encoder_inst, +\& void *construct_data); +\& typedef void OSSL_ENCODER_CLEANUP(void *construct_data); +\& +\& int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx, +\& OSSL_ENCODER_CONSTRUCT *construct); +\& int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx, +\& void *construct_data); +\& int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx, +\& OSSL_ENCODER_CLEANUP *cleanup); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Encoding an input object to the desired encoding may be done with a chain of +encoder implementations, which means that the output from one encoder may be +the input for the next in the chain. The \fBOSSL_ENCODER_CTX\fR holds all the +data about these encoders. This allows having generic format encoders such +as DER to PEM, as well as more specialized encoders like RSA to DER. +.PP +The final output type must be given, and a chain of encoders must end with +an implementation that produces that output type. +.PP +At the beginning of the encoding process, a constructor provided by the +caller is called to ensure that there is an appropriate provider\-side object +to start with. +The constructor is set with \fBOSSL_ENCODER_CTX_set_construct()\fR. +.PP +\&\fBOSSL_ENCODER_INSTANCE\fR is an opaque structure that contains data about the +encoder that is going to be used, and that may be useful for the +constructor. There are some functions to extract data from this type, +described in "Constructor" below. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_ENCODER_CTX_new()\fR creates a \fBOSSL_ENCODER_CTX\fR. +.PP +\&\fBOSSL_ENCODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) +array of parameter descriptors. +.PP +\&\fBOSSL_ENCODER_CTX_set_params()\fR attempts to set parameters specified +with an \fBOSSL_PARAM\fR\|(3) array \fIparams\fR. Parameters that the +implementation doesn\*(Aqt recognise should be ignored. +.PP +\&\fBOSSL_ENCODER_CTX_free()\fR frees the given context \fIctx\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_ENCODER_CTX_add_encoder()\fR populates the \fBOSSL_ENCODER_CTX\fR +\&\fIctx\fR with a encoder, to be used to encode an input object. +.PP +\&\fBOSSL_ENCODER_CTX_add_extra()\fR finds encoders that further encodes output +from already added encoders, and adds them as well. This is used to build +encoder chains. +.PP +\&\fBOSSL_ENCODER_CTX_set_output_type()\fR sets the ending output type. This must +be specified, and determines if a complete encoder chain is available. +.PP +\&\fBOSSL_ENCODER_CTX_set_output_structure()\fR sets the desired output structure. +This may be used to determines what encoder implementations may be used. +Depending on the type of object being encoded, the output structure may +not be relevant. +.PP +\&\fBOSSL_ENCODER_CTX_get_num_encoders()\fR gets the number of encoders currently +added to the context \fIctx\fR. +.PP +\&\fBOSSL_ENCODER_CTX_set_construct()\fR sets the constructor \fIconstruct\fR. +.PP +\&\fBOSSL_ENCODER_CTX_set_construct_data()\fR sets the constructor data that is +passed to the constructor every time it\*(Aqs called. +.PP +\&\fBOSSL_ENCODER_CTX_set_cleanup()\fR sets the constructor data \fIcleanup\fR +function. This is called by \fBOSSL_ENCODER_CTX_free\fR\|(3). +.PP +Note that functions \fBOSSL_ENCODER_CTX_set_selection()\fR, +\&\fBOSSL_ENCODER_CTX_set_output_type()\fR, \fBOSSL_ENCODER_CTX_set_output_structure()\fR, +\&\fBOSSL_ENCODER_CTX_add_encoder()\fR, \fBOSSL_ENCODER_CTX_add_extra()\fR, +\&\fBOSSL_ENCODER_CTX_set_construct()\fR, \fBOSSL_ENCODER_CTX_set_construct_data()\fR, and +\&\fBOSSL_ENCODER_CTX_set_cleanup()\fR shouldn\*(Aqt be used after the context is finalised, +in particular after calling the function \fBOSSL_ENCODER_CTX_new_for_pkey()\fR. +.SS Constructor +.IX Subsection "Constructor" +A \fBOSSL_ENCODER_CONSTRUCT\fR gets the following arguments: +.IP \fIencoder_inst\fR 4 +.IX Item "encoder_inst" +The \fBOSSL_ENCODER_INSTANCE\fR for the encoder from which the constructor gets +its data. +.IP \fIconstruct_data\fR 4 +.IX Item "construct_data" +The pointer that was set with \fBOSSL_ENCODE_CTX_set_construct_data()\fR. +.PP +The constructor is expected to return a valid (non\-NULL) pointer to a +provider\-native object that can be used as first input of an encoding chain, +or NULL to indicate that an error has occurred. +.PP +These utility functions may be used by a constructor: +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_encoder()\fR can be used to get the encoder +implementation of the encoder instance \fIencoder_inst\fR. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_encoder_ctx()\fR can be used to get the encoder +implementation\*(Aqs provider context of the encoder instance \fIencoder_inst\fR. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_output_type()\fR can be used to get the output type +for the encoder implementation of the encoder instance \fIencoder_inst\fR. +This will never be NULL. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_output_structure()\fR can be used to get the output +structure for the encoder implementation of the encoder instance +\&\fIencoder_inst\fR. +This may be NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ENCODER_CTX_new()\fR returns a pointer to a \fBOSSL_ENCODER_CTX\fR, or NULL +if the context structure couldn\*(Aqt be allocated. +.PP +\&\fBOSSL_ENCODER_settable_ctx_params()\fR returns an \fBOSSL_PARAM\fR\|(3) array, or +NULL if none is available. +.PP +\&\fBOSSL_ENCODER_CTX_set_params()\fR returns 1 if all recognised parameters were +valid, or 0 if one of them was invalid or caused some other failure in the +implementation. +.PP +\&\fBOSSL_ENCODER_CTX_add_encoder()\fR, \fBOSSL_ENCODER_CTX_add_extra()\fR, +\&\fBOSSL_ENCODER_CTX_set_construct()\fR, \fBOSSL_ENCODER_CTX_set_construct_data()\fR and +\&\fBOSSL_ENCODER_CTX_set_cleanup()\fR return 1 on success, or 0 on failure. +.PP +\&\fBOSSL_ENCODER_CTX_get_num_encoders()\fR returns the current number of encoders. +It returns 0 if \fIctx\fR is NULL. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_encoder()\fR returns an \fBOSSL_ENCODER\fR pointer on +success, or NULL on failure. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_encoder_ctx()\fR returns a provider context pointer on +success, or NULL on failure. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_output_type()\fR returns a string with the name of the +input type, if relevant. NULL is a valid returned value. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_output_type()\fR returns a string with the name of the +output type. +.PP +\&\fBOSSL_ENCODER_INSTANCE_get_output_structure()\fR returns a string with the name +of the output structure. +.SH "NOTES AND BUGS" +.IX Header "NOTES AND BUGS" +The chain mechanism in ENCODE is not yet completely implemented. +It affects functions such as OSSL_ENCODER_CTX_add_extra and the +inner processing loop. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_ENCODER\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ENCODER_CTX_new_for_pkey.3 b/static/netbsd/man3/OSSL_ENCODER_CTX_new_for_pkey.3 new file mode 100644 index 00000000..cf5c4999 --- /dev/null +++ b/static/netbsd/man3/OSSL_ENCODER_CTX_new_for_pkey.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: OSSL_ENCODER_CTX_new_for_pkey.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ENCODER_CTX_new_for_pkey 3" +.TH OSSL_ENCODER_CTX_new_for_pkey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ENCODER_CTX_new_for_pkey, +OSSL_ENCODER_CTX_set_cipher, +OSSL_ENCODER_CTX_set_passphrase, +OSSL_ENCODER_CTX_set_pem_password_cb, +OSSL_ENCODER_CTX_set_passphrase_cb, +OSSL_ENCODER_CTX_set_passphrase_ui +\&\- Encoder routines to encode EVP_PKEYs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_ENCODER_CTX * +\& OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, int selection, +\& const char *output_type, +\& const char *output_structure, +\& const char *propquery); +\& +\& int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx, +\& const char *cipher_name, +\& const char *propquery); +\& int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx, +\& const unsigned char *kstr, +\& size_t klen); +\& int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx, +\& pem_password_cb *cb, void *cbarg); +\& int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx, +\& const UI_METHOD *ui_method, +\& void *ui_data); +\& int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx, +\& OSSL_PASSPHRASE_CALLBACK *cb, +\& void *cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_ENCODER_CTX_new_for_pkey()\fR is a utility function that creates a +\&\fBOSSL_ENCODER_CTX\fR, finds all applicable encoder implementations and sets +them up, so almost all the caller has to do next is call functions like +\&\fBOSSL_ENCODER_to_bio\fR\|(3). \fIoutput_type\fR determines the final output +encoding, and \fIselection\fR can be used to select what parts of the \fIpkey\fR +should be included in the output. \fIoutput_type\fR is further discussed in +"Output types" below, and \fIselection\fR is further described in +"Selections". +.PP +Internally, \fBOSSL_ENCODER_CTX_new_for_pkey()\fR uses the names from the +\&\fBEVP_KEYMGMT\fR\|(3) implementation associated with \fIpkey\fR to build a list of +applicable encoder implementations that are used to process the \fIpkey\fR into +the encoding named by \fIoutput_type\fR, with the outermost structure named by +\&\fIoutput_structure\fR if that\*(Aqs relevant. All these implementations are +implicitly fetched, with \fIpropquery\fR for finer selection. +.PP +If no suitable encoder implementation is found, +\&\fBOSSL_ENCODER_CTX_new_for_pkey()\fR still creates a \fBOSSL_ENCODER_CTX\fR, but +with no associated encoder (\fBOSSL_ENCODER_CTX_get_num_encoders\fR\|(3) returns +zero). This helps the caller to distinguish between an error when creating +the \fBOSSL_ENCODER_CTX\fR and missing encoder implementation, and allows it to +act accordingly. +.PP +Note that \fBOSSL_ENCODER_CTX_new_for_pkey()\fR finalises the OSSL_ENCODER_CTX; +after that the OSSL_ENCODER_CTX_set_* and OSSL_ENCODER_CTX_add_* functions +described in \fBOSSL_ENCODER_CTX\fR\|(3) shouldn\*(Aqt be called. +.PP +\&\fBOSSL_ENCODER_CTX_set_cipher()\fR tells the implementation what cipher +should be used to encrypt encoded keys. The cipher is given by +name \fIcipher_name\fR. The interpretation of that \fIcipher_name\fR is +implementation dependent. The implementation may implement the cipher +directly itself or by other implementations, or it may choose to fetch +it. If the implementation supports fetching the cipher, then it may +use \fIpropquery\fR as properties to be queried for when fetching. +\&\fIcipher_name\fR may also be NULL, which will result in unencrypted +encoding. +.PP +\&\fBOSSL_ENCODER_CTX_set_passphrase()\fR gives the implementation a +pass phrase to use when encrypting the encoded private key. +Alternatively, a pass phrase callback may be specified with the +following functions. +.PP +\&\fBOSSL_ENCODER_CTX_set_pem_password_cb()\fR, \fBOSSL_ENCODER_CTX_set_passphrase_ui()\fR +and \fBOSSL_ENCODER_CTX_set_passphrase_cb()\fR sets up a callback method that the +implementation can use to prompt for a pass phrase, giving the caller the +choice of preferred pass phrase callback form. These are called indirectly, +through an internal \fBOSSL_PASSPHRASE_CALLBACK\fR\|(3) function. +.SS "Output types" +.IX Subsection "Output types" +The possible \fBEVP_PKEY\fR output types depends on the available +implementations. +.PP +OpenSSL has built in implementations for the following output types: +.ie n .IP """TEXT""" 4 +.el .IP \f(CWTEXT\fR 4 +.IX Item "TEXT" +The output is a human readable description of the key. +\&\fBEVP_PKEY_print_private\fR\|(3), \fBEVP_PKEY_print_public\fR\|(3) and +\&\fBEVP_PKEY_print_params\fR\|(3) use this for their output. +.ie n .IP """DER""" 4 +.el .IP \f(CWDER\fR 4 +.IX Item "DER" +The output is the DER encoding of the \fIselection\fR of the \fIpkey\fR. +.ie n .IP """PEM""" 4 +.el .IP \f(CWPEM\fR 4 +.IX Item "PEM" +The output is the \fIselection\fR of the \fIpkey\fR in PEM format. +.SS Selections +.IX Subsection "Selections" +\&\fIselection\fR can be any one of the values described in +"Selections" in \fBEVP_PKEY_fromdata\fR\|(3). +.PP +These are only \*(Aqhints\*(Aq since the encoder implementations are free to +determine what makes sense to include in the output, and this may depend on +the desired output. For example, an EC key in a PKCS#8 structure doesn\*(Aqt +usually include the public key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ENCODER_CTX_new_for_pkey()\fR returns a pointer to an \fBOSSL_ENCODER_CTX\fR, +or NULL if it couldn\*(Aqt be created. +.PP +\&\fBOSSL_ENCODER_CTX_set_cipher()\fR, \fBOSSL_ENCODER_CTX_set_passphrase()\fR, +\&\fBOSSL_ENCODER_CTX_set_pem_password_cb()\fR, \fBOSSL_ENCODER_CTX_set_passphrase_ui()\fR +and \fBOSSL_ENCODER_CTX_set_passphrase_cb()\fR all return 1 on success, or 0 on +failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_ENCODER\fR\|(3), \fBOSSL_ENCODER_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ENCODER_to_bio.3 b/static/netbsd/man3/OSSL_ENCODER_to_bio.3 new file mode 100644 index 00000000..43de7d9f --- /dev/null +++ b/static/netbsd/man3/OSSL_ENCODER_to_bio.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: OSSL_ENCODER_to_bio.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ENCODER_to_bio 3" +.TH OSSL_ENCODER_to_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ENCODER_to_data, +OSSL_ENCODER_to_bio, +OSSL_ENCODER_to_fp +\&\- Routines to perform an encoding +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_ENCODER_to_data(OSSL_ENCODER_CTX *ctx, unsigned char **pdata, +\& size_t *pdata_len); +\& int OSSL_ENCODER_to_bio(OSSL_ENCODER_CTX *ctx, BIO *out); +\& int OSSL_ENCODER_to_fp(OSSL_ENCODER_CTX *ctx, FILE *fp); +.Ve +.PP +Feature availability macros: +.IP "\fBOSSL_ENCODER_to_fp()\fR is only available when \fBOPENSSL_NO_STDIO\fR is undefined." 4 +.IX Item "OSSL_ENCODER_to_fp() is only available when OPENSSL_NO_STDIO is undefined." +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_ENCODER_to_data()\fR runs the encoding process for the context \fIctx\fR, +with the output going to the \fI*pdata\fR and \fI*pdata_len\fR. +If \fI*pdata\fR is NULL when \fBOSSL_ENCODER_to_data()\fR is called, a buffer will be +allocated using \fBOPENSSL_zalloc\fR\|(3), and \fI*pdata\fR will be set to point at +the start of that buffer, and \fI*pdata_len\fR will be assigned its length when +\&\fBOSSL_ENCODER_to_data()\fR returns. +If \fI*pdata\fR is non\-NULL when \fBOSSL_ENCODER_to_data()\fR is called, \fI*pdata_len\fR +is assumed to have its size. In this case, \fI*pdata\fR will be set to point +after the encoded bytes, and \fI*pdata_len\fR will be assigned the number of +remaining bytes. +.PP +\&\fBOSSL_ENCODER_to_bio()\fR runs the encoding process for the context \fIctx\fR, with +the output going to the \fBBIO\fR \fIout\fR. +.PP +\&\fBOSSL_ENCODER_to_fp()\fR does the same thing as \fBOSSL_ENCODER_to_bio()\fR, except +that the output is going to the \fBFILE\fR \fIfp\fR. +.PP +For \fBOSSL_ENCODER_to_bio()\fR and \fBOSSL_ENCODER_to_fp()\fR, the application is +required to set up the \fBBIO\fR or \fBFILE\fR properly, for example to have +it in text or binary mode as is appropriate for the encoder output type. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ENCODER_to_bio()\fR, \fBOSSL_ENCODER_to_fp()\fR and \fBOSSL_ENCODER_to_data()\fR +return 1 on success, or 0 on failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +To encode a pkey as PKCS#8 with PEM format into a bio: +.PP +.Vb 4 +\& OSSL_ENCODER_CTX *ectx; +\& const char *format = "PEM"; +\& const char *structure = "PrivateKeyInfo"; /* PKCS#8 structure */ +\& const unsigned char *pass = "my password"; +\& +\& ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, +\& OSSL_KEYMGMT_SELECT_KEYPAIR +\& | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, +\& format, structure, +\& NULL); +\& if (ectx == NULL) { +\& /* error: no suitable potential encoders found */ +\& } +\& if (pass != NULL) +\& OSSL_ENCODER_CTX_set_passphrase(ectx, pass, strlen(pass)); +\& if (OSSL_ENCODER_to_bio(ectx, bio)) { +\& /* pkey was successfully encoded into the bio */ +\& } else { +\& /* encoding failure */ +\& } +\& OSSL_ENCODER_CTX_free(ectx); +.Ve +.PP +To encode a pkey as PKCS#8 with DER format encrypted with +AES\-256\-CBC into a buffer: +.PP +.Vb 6 +\& OSSL_ENCODER_CTX *ectx; +\& const char *format = "DER"; +\& const char *structure = "PrivateKeyInfo"; /* PKCS#8 structure */ +\& const unsigned char *pass = "my password"; +\& unsigned char *data = NULL; +\& size_t datalen; +\& +\& ectx = OSSL_ENCODER_CTX_new_for_pkey(pkey, +\& OSSL_KEYMGMT_SELECT_KEYPAIR +\& | OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, +\& format, structure, +\& NULL); +\& if (ectx == NULL) { +\& /* error: no suitable potential encoders found */ +\& } +\& if (pass != NULL) { +\& OSSL_ENCODER_CTX_set_passphrase(ectx, pass, strlen(pass)); +\& OSSL_ENCODER_CTX_set_cipher(ctx, "AES\-256\-CBC", NULL); +\& } +\& if (OSSL_ENCODER_to_data(ectx, &data, &datalen)) { +\& /* +\& * pkey was successfully encoded into a newly allocated +\& * data buffer +\& */ +\& } else { +\& /* encoding failure */ +\& } +\& OSSL_ENCODER_CTX_free(ectx); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\fR\|(7), \fBOSSL_ENCODER_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ERR_STATE_save.3 b/static/netbsd/man3/OSSL_ERR_STATE_save.3 new file mode 100644 index 00000000..3af2ab11 --- /dev/null +++ b/static/netbsd/man3/OSSL_ERR_STATE_save.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: OSSL_ERR_STATE_save.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ERR_STATE_save 3" +.TH OSSL_ERR_STATE_save 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ERR_STATE_new, OSSL_ERR_STATE_save, OSSL_ERR_STATE_save_to_mark, +OSSL_ERR_STATE_restore, OSSL_ERR_STATE_free \- saving and restoring error state +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ERR_STATE *OSSL_ERR_STATE_new(void); +\& void OSSL_ERR_STATE_save(ERR_STATE *es); +\& void OSSL_ERR_STATE_save_to_mark(ERR_STATE *es); +\& void OSSL_ERR_STATE_restore(const ERR_STATE *es); +\& void OSSL_ERR_STATE_free(ERR_STATE *es); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions save and restore the error state from the thread +local error state to a preallocated error state structure. +.PP +\&\fBOSSL_ERR_STATE_new()\fR allocates an empty error state structure to +be used when saving and restoring thread error state. +.PP +\&\fBOSSL_ERR_STATE_save()\fR saves the thread error state to \fIes\fR. It +subsequently clears the thread error state. Any previously saved +state in \fIes\fR is cleared prior to saving the new state. +.PP +\&\fBOSSL_ERR_STATE_save_to_mark()\fR is similar to \fBOSSL_ERR_STATE_save()\fR but only saves +ERR entries up to the most recent mark on the ERR stack. These entries are moved +to \fIes\fR and removed from the thread error state. However, the most recent +marked ERR and any ERR state before it remains part of the thread error state +and is not moved to the ERR_STATE. The mark is not cleared and must be cleared +explicitly after a call to this function using \fBERR_pop_to_mark\fR\|(3) or +\&\fBERR_clear_last_mark\fR\|(3). (Since a call to \fBOSSL_ERR_STATE_save_to_mark()\fR leaves +the marked ERR as the top error, either of these functions will have the same +effect.) If there is no marked ERR in the thread local error state, all ERR +entries are copied and the effect is the same as for a call to +\&\fBOSSL_ERR_STATE_save()\fR. +.PP +\&\fBOSSL_ERR_STATE_restore()\fR adds all the error entries from the +saved state \fIes\fR to the thread error state. Existing entries in +the thread error state are not affected if there is enough space +for all the added entries. Any allocated data in the saved error +entries is duplicated on adding to the thread state. +.PP +\&\fBOSSL_ERR_STATE_free()\fR frees the saved error state \fIes\fR. +If the argument is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ERR_STATE_new()\fR returns a pointer to the allocated ERR_STATE +structure or NULL on error. +.PP +\&\fBOSSL_ERR_STATE_save()\fR, \fBOSSL_ERR_STATE_save_to_mark()\fR, \fBOSSL_ERR_STATE_restore()\fR, +\&\fBOSSL_ERR_STATE_free()\fR do not return any values. +.SH NOTES +.IX Header "NOTES" +\&\fBOSSL_ERR_STATE_save()\fR and \fBOSSL_ERR_STATE_save_to_mark()\fR cannot fail as it takes +over any allocated data from the thread error state. +.PP +\&\fBOSSL_ERR_STATE_restore()\fR is a best effort function. The only failure +that can happen during its operation is when memory allocation fails. +Because it manipulates the thread error state it avoids raising memory +errors on such failure. At worst the restored error entries will be +missing the auxiliary error data. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_raise\fR\|(3), \fBERR_get_error\fR\|(3), \fBERR_clear_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ESS_check_signing_certs.3 b/static/netbsd/man3/OSSL_ESS_check_signing_certs.3 new file mode 100644 index 00000000..f2162490 --- /dev/null +++ b/static/netbsd/man3/OSSL_ESS_check_signing_certs.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: OSSL_ESS_check_signing_certs.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ESS_check_signing_certs 3" +.TH OSSL_ESS_check_signing_certs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ESS_signing_cert_new_init, +OSSL_ESS_signing_cert_v2_new_init, +OSSL_ESS_check_signing_certs +\&\- Enhanced Security Services (ESS) functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ESS_SIGNING_CERT *OSSL_ESS_signing_cert_new_init(const X509 *signcert, +\& const STACK_OF(X509) *certs, +\& int set_issuer_serial); +\& ESS_SIGNING_CERT_V2 *OSSL_ESS_signing_cert_v2_new_init(const EVP_MD *hash_alg, +\& const X509 *signcert, +\& const +\& STACK_OF(X509) *certs, +\& int set_issuer_serial); +\& int OSSL_ESS_check_signing_certs(const ESS_SIGNING_CERT *ss, +\& const ESS_SIGNING_CERT_V2 *ssv2, +\& const STACK_OF(X509) *chain, +\& int require_signing_cert); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_ESS_signing_cert_new_init()\fR generates a new \fBESS_SIGNING_CERT\fR structure +referencing the given \fIsigncert\fR and any given further \fIcerts\fR +using their SHA\-1 fingerprints. +If \fIset_issuer_serial\fR is nonzero then also the issuer and serial number +of \fIsigncert\fR are included in the \fBESS_CERT_ID\fR as the \fBissuerSerial\fR field. +For all members of \fIcerts\fR the \fBissuerSerial\fR field is always included. +.PP +\&\fBOSSL_ESS_signing_cert_v2_new_init()\fR is the same as +\&\fBOSSL_ESS_signing_cert_new_init()\fR except that it uses the given \fIhash_alg\fR and +generates a \fBESS_SIGNING_CERT_V2\fR structure with \fBESS_CERT_ID_V2\fR elements. +.PP +\&\fBOSSL_ESS_check_signing_certs()\fR checks if the validation chain \fIchain\fR contains +the certificates required by the identifiers given in \fIss\fR and/or \fIssv2\fR. +If \fIrequire_signing_cert\fR is nonzero, \fIss\fR or \fIssv2\fR must not be NULL. +If both \fIss\fR and \fIssv2\fR are not NULL, they are evaluated independently. +The list of certificate identifiers in \fIss\fR is of type \fBESS_CERT_ID\fR, +while the list contained in \fIssv2\fR is of type \fBESS_CERT_ID_V2\fR. +As far as these lists are present, they must be nonempty. +The certificate identified by their first entry must be the first element of +\&\fIchain\fR, i.e. the signer certificate. +Any further certificates referenced in the list must also be found in \fIchain\fR. +The matching is done using the given certificate hash algorithm and value. +In addition to the checks required by RFCs 2624 and 5035, +if the \fBissuerSerial\fR field is included in an \fBESSCertID\fR or \fBESSCertIDv2\fR +it must match the certificate issuer and serial number attributes. +.SH NOTES +.IX Header "NOTES" +ESS has been defined in RFC 2634, which has been updated in RFC 5035 +(ESS version 2) to support hash algorithms other than SHA\-1. +This is used for TSP (RFC 3161) and CAdES\-BES (informational RFC 5126). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_ESS_signing_cert_new_init()\fR and \fBOSSL_ESS_signing_cert_v2_new_init()\fR +return a pointer to the new structure or NULL on malloc failure. +.PP +\&\fBOSSL_ESS_check_signing_certs()\fR returns 1 on success, +0 if a required certificate cannot be found, \-1 on other error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBTS_VERIFY_CTX_set_certs\fR\|(3), +\&\fBCMS_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_ESS_signing_cert_new_init()\fR, \fBOSSL_ESS_signing_cert_v2_new_init()\fR, and +\&\fBOSSL_ESS_check_signing_certs()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_GENERAL_NAMES_print.3 b/static/netbsd/man3/OSSL_GENERAL_NAMES_print.3 new file mode 100644 index 00000000..2db6a222 --- /dev/null +++ b/static/netbsd/man3/OSSL_GENERAL_NAMES_print.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: OSSL_GENERAL_NAMES_print.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_GENERAL_NAMES_print 3" +.TH OSSL_GENERAL_NAMES_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_GENERAL_NAMES_print \- print GeneralNames in a human\-friendly, multi\-line +string +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_GENERAL_NAMES_print(BIO *out, GENERAL_NAMES *gens, int indent); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_GENERAL_NAMES_print()\fR prints a human readable version of the GeneralNames +\&\fIgens\fR to BIO \fIout\fR. Each line is indented by \fIindent\fR spaces. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_GENERAL_NAMES_print()\fR always returns 1. +.SH HISTORY +.IX Header "HISTORY" +The functions described here were all added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_HPKE_CTX_new.3 b/static/netbsd/man3/OSSL_HPKE_CTX_new.3 new file mode 100644 index 00000000..601de554 --- /dev/null +++ b/static/netbsd/man3/OSSL_HPKE_CTX_new.3 @@ -0,0 +1,599 @@ +.\" $NetBSD: OSSL_HPKE_CTX_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_HPKE_CTX_new 3" +.TH OSSL_HPKE_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_HPKE_CTX_new, OSSL_HPKE_CTX_free, +OSSL_HPKE_encap, OSSL_HPKE_decap, +OSSL_HPKE_seal, OSSL_HPKE_open, OSSL_HPKE_export, +OSSL_HPKE_suite_check, OSSL_HPKE_str2suite, +OSSL_HPKE_keygen, OSSL_HPKE_get_grease_value, +OSSL_HPKE_get_ciphertext_size, OSSL_HPKE_get_public_encap_size, +OSSL_HPKE_get_recommended_ikmelen, +OSSL_HPKE_CTX_set1_psk, OSSL_HPKE_CTX_set1_ikme, +OSSL_HPKE_CTX_set1_authpriv, OSSL_HPKE_CTX_set1_authpub, +OSSL_HPKE_CTX_get_seq, OSSL_HPKE_CTX_set_seq +\&\- Hybrid Public Key Encryption (HPKE) functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct { +\& uint16_t kem_id; +\& uint16_t kdf_id; +\& uint16_t aead_id; +\& } OSSL_HPKE_SUITE; +\& +\& OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx); +\& +\& int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx, +\& unsigned char *enc, size_t *enclen, +\& const unsigned char *pub, size_t publen, +\& const unsigned char *info, size_t infolen); +\& int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx, +\& unsigned char *ct, size_t *ctlen, +\& const unsigned char *aad, size_t aadlen, +\& const unsigned char *pt, size_t ptlen); +\& +\& int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite, +\& unsigned char *pub, size_t *publen, EVP_PKEY **priv, +\& const unsigned char *ikm, size_t ikmlen, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx, +\& const unsigned char *enc, size_t enclen, +\& EVP_PKEY *recippriv, +\& const unsigned char *info, size_t infolen); +\& int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx, +\& unsigned char *pt, size_t *ptlen, +\& const unsigned char *aad, size_t aadlen, +\& const unsigned char *ct, size_t ctlen); +\& +\& int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx, +\& unsigned char *secret, size_t secretlen, +\& const unsigned char *label, size_t labellen); +\& +\& int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv); +\& int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx, +\& unsigned char *pub, size_t publen); +\& int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx, +\& const char *pskid, +\& const unsigned char *psk, size_t psklen); +\& +\& int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq); +\& int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq); +\& +\& int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx, +\& const unsigned char *ikme, size_t ikmelen); +\& +\& int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite); +\& int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in, +\& OSSL_HPKE_SUITE *suite, +\& unsigned char *enc, size_t *enclen, +\& unsigned char *ct, size_t ctlen, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite); +\& size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen); +\& size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite); +\& size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions provide an API for using the form of Hybrid Public Key +Encryption (HPKE) defined in RFC9180. Understanding the HPKE specification +is likely required before using these APIs. HPKE is used by various +other IETF specifications, including the TLS Encrypted Client +Hello (ECH) specification and others. +.PP +HPKE is a standardised, highly flexible construct for encrypting "to" a public +key that supports combinations of a key encapsulation method (KEM), a key +derivation function (KDF) and an authenticated encryption with additional data +(AEAD) algorithm, with optional sender authentication. +.PP +The sender and a receiver here will generally be using some application or +protocol making use of HPKE. For example, with ECH, +the sender will be a browser and the receiver will be a web server. +.SS "Data Structures" +.IX Subsection "Data Structures" +\&\fBOSSL_HPKE_SUITE\fR is a structure that holds identifiers for the algorithms +used for KEM, KDF and AEAD operations. +.PP +\&\fBOSSL_HPKE_CTX\fR is a context that maintains internal state as HPKE +operations are carried out. Separate \fBOSSL_HPKE_CTX\fR objects must be used for +the sender and receiver. Attempting to use a single context for both will +result in errors. +.SS "OSSL_HPKE_SUITE Identifiers" +.IX Subsection "OSSL_HPKE_SUITE Identifiers" +The identifiers used by \fBOSSL_HPKE_SUITE\fR are: +.PP +The KEM identifier \fIkem_id\fR is one of the following: +.IP "0x10 \fBOSSL_HPKE_KEM_ID_P256\fR" 4 +.IX Item "0x10 OSSL_HPKE_KEM_ID_P256" +.PD 0 +.IP "0x11 \fBOSSL_HPKE_KEM_ID_P384\fR" 4 +.IX Item "0x11 OSSL_HPKE_KEM_ID_P384" +.IP "0x12 \fBOSSL_HPKE_KEM_ID_P521\fR" 4 +.IX Item "0x12 OSSL_HPKE_KEM_ID_P521" +.IP "0x20 \fBOSSL_HPKE_KEM_ID_X25519\fR" 4 +.IX Item "0x20 OSSL_HPKE_KEM_ID_X25519" +.IP "0x21 \fBOSSL_HPKE_KEM_ID_X448\fR" 4 +.IX Item "0x21 OSSL_HPKE_KEM_ID_X448" +.PD +.PP +The KDF identifier \fIkdf_id\fR is one of the following: +.IP "0x01 \fBOSSL_HPKE_KDF_ID_HKDF_SHA256\fR" 4 +.IX Item "0x01 OSSL_HPKE_KDF_ID_HKDF_SHA256" +.PD 0 +.IP "0x02 \fBOSSL_HPKE_KDF_ID_HKDF_SHA384\fR" 4 +.IX Item "0x02 OSSL_HPKE_KDF_ID_HKDF_SHA384" +.IP "0x03 \fBOSSL_HPKE_KDF_ID_HKDF_SHA512\fR" 4 +.IX Item "0x03 OSSL_HPKE_KDF_ID_HKDF_SHA512" +.PD +.PP +The AEAD identifier \fIaead_id\fR is one of the following: +.IP "0x01 \fBOSSL_HPKE_AEAD_ID_AES_GCM_128\fR" 4 +.IX Item "0x01 OSSL_HPKE_AEAD_ID_AES_GCM_128" +.PD 0 +.IP "0x02 \fBOSSL_HPKE_AEAD_ID_AES_GCM_256\fR" 4 +.IX Item "0x02 OSSL_HPKE_AEAD_ID_AES_GCM_256" +.IP "0x03 \fBOSSL_HPKE_AEAD_ID_CHACHA_POLY1305\fR" 4 +.IX Item "0x03 OSSL_HPKE_AEAD_ID_CHACHA_POLY1305" +.IP "0xFFFF \fBOSSL_HPKE_AEAD_ID_EXPORTONLY\fR" 4 +.IX Item "0xFFFF OSSL_HPKE_AEAD_ID_EXPORTONLY" +.PD +The last identifier above indicates that AEAD operations are not needed. +\&\fBOSSL_HPKE_export()\fR can be used, but \fBOSSL_HPKE_open()\fR and \fBOSSL_HPKE_seal()\fR will +return an error if called with a context using that AEAD identifier. +.SS "HPKE Modes" +.IX Subsection "HPKE Modes" +HPKE supports the following variants of Authentication using a mode Identifier: +.IP "\fBOSSL_HPKE_MODE_BASE\fR, 0x00" 4 +.IX Item "OSSL_HPKE_MODE_BASE, 0x00" +Authentication is not used. +.IP "\fBOSSL_HPKE_MODE_PSK\fR, 0x01" 4 +.IX Item "OSSL_HPKE_MODE_PSK, 0x01" +Authenticates possession of a pre\-shared key (PSK). +.IP "\fBOSSL_HPKE_MODE_AUTH\fR, 0x02" 4 +.IX Item "OSSL_HPKE_MODE_AUTH, 0x02" +Authenticates possession of a KEM\-based sender private key. +.IP "\fBOSSL_HPKE_MODE_PSKAUTH\fR, 0x03" 4 +.IX Item "OSSL_HPKE_MODE_PSKAUTH, 0x03" +A combination of \fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_AUTH\fR. +Both the PSK and the senders authentication public/private must be +supplied before the encapsulation/decapsulation operation will work. +.PP +For further information related to authentication see "Pre\-Shared Key HPKE +modes" and "Sender\-authenticated HPKE Modes". +.SS "HPKE Roles" +.IX Subsection "HPKE Roles" +HPKE contexts have a role \- either sender or receiver. This is used +to control which functions can be called and so that senders do not +reuse a key and nonce with different plaintexts. +.PP +\&\fBOSSL_HPKE_CTX_free()\fR, \fBOSSL_HPKE_export()\fR, \fBOSSL_HPKE_CTX_set1_psk()\fR, +and \fBOSSL_HPKE_CTX_get_seq()\fR can be called regardless of role. +.IP "\fBOSSL_HPKE_ROLE_SENDER\fR, 0" 4 +.IX Item "OSSL_HPKE_ROLE_SENDER, 0" +An \fIOSSL_HPKE_CTX\fR with this role can be used with +\&\fBOSSL_HPKE_encap()\fR, \fBOSSL_HPKE_seal()\fR, \fBOSSL_HPKE_CTX_set1_ikme()\fR and +\&\fBOSSL_HPKE_CTX_set1_authpriv()\fR. +.IP "\fBOSSL_HPKE_ROLE_RECEIVER\fR, 1" 4 +.IX Item "OSSL_HPKE_ROLE_RECEIVER, 1" +An \fIOSSL_HPKE_CTX\fR with this role can be used with \fBOSSL_HPKE_decap()\fR, +\&\fBOSSL_HPKE_open()\fR, \fBOSSL_HPKE_CTX_set1_authpub()\fR and \fBOSSL_HPKE_CTX_set_seq()\fR. +.PP +Calling a function with an incorrect role set on \fIOSSL_HPKE_CTX\fR will result +in an error. +.SS "Parameter Size Limits" +.IX Subsection "Parameter Size Limits" +In order to improve interoperability, RFC9180, section 7.2.1 suggests a +RECOMMENDED maximum size of 64 octets for various input parameters. In this +implementation we apply a limit of 66 octets for the \fIikmlen\fR, \fIpsklen\fR, and +\&\fIlabellen\fR parameters, and for the length of the string \fIpskid\fR for HPKE +functions below. The constant \fIOSSL_HPKE_MAX_PARMLEN\fR is defined as the limit +of this value. (We chose 66 octets so that we can validate all the test +vectors present in RFC9180, Appendix A.) +.PP +In accordance with RFC9180, section 9.5, we define a constant +\&\fIOSSL_HPKE_MIN_PSKLEN\fR with a value of 32 for the minimum length of a +pre\-shared key, passed in \fIpsklen\fR. +.PP +While RFC9180 also RECOMMENDS a 64 octet limit for the \fIinfolen\fR parameter, +that is not sufficient for TLS Encrypted ClientHello (ECH) processing, so we +enforce a limit of \fIOSSL_HPKE_MAX_INFOLEN\fR with a value of 1024 as the limit +for the \fIinfolen\fR parameter. +.SS "Context Construct/Free" +.IX Subsection "Context Construct/Free" +\&\fBOSSL_HPKE_CTX_new()\fR creates a \fBOSSL_HPKE_CTX\fR context object used for +subsequent HPKE operations, given a \fImode\fR (See "HPKE Modes"), \fIsuite\fR (see +"OSSL_HPKE_SUITE Identifiers") and a \fIrole\fR (see "HPKE Roles"). The +\&\fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers and may +be set to NULL. +.PP +\&\fBOSSL_HPKE_CTX_free()\fR frees the \fIctx\fR \fBOSSL_HPKE_CTX\fR that was created +previously by a call to \fBOSSL_HPKE_CTX_new()\fR. If the argument to +\&\fBOSSL_HPKE_CTX_free()\fR is NULL, nothing is done. +.SS "Sender APIs" +.IX Subsection "Sender APIs" +A sender\*(Aqs goal is to use HPKE to encrypt using a public key, via use of a +KEM, then a KDF and finally an AEAD. The first step is to encapsulate (using +\&\fBOSSL_HPKE_encap()\fR) the sender\*(Aqs public value using the recipient\*(Aqs public key, +(\fIpub\fR) and to internally derive secrets. This produces the encapsulated public value +(\fIenc\fR) to be sent to the recipient in whatever protocol is using HPKE. Having done the +encapsulation step, the sender can then make one or more calls to +\&\fBOSSL_HPKE_seal()\fR to encrypt plaintexts using the secret stored within \fIctx\fR. +.PP +\&\fBOSSL_HPKE_encap()\fR uses the HPKE context \fIctx\fR, the recipient public value +\&\fIpub\fR of size \fIpublen\fR, and an optional \fIinfo\fR parameter of size \fIinfolen\fR, +to produce the encapsulated public value \fIenc\fR. +On input \fIenclen\fR should contain the maximum size of the \fIenc\fR buffer, and returns +the output size. An error will occur if the input \fIenclen\fR is +smaller than the value returned from \fBOSSL_HPKE_get_public_encap_size()\fR. +\&\fIinfo\fR may be used to bind other protocol or application artefacts such as identifiers. +Generally, the encapsulated public value \fIenc\fR corresponds to a +single\-use ephemeral private value created as part of the encapsulation +process. Only a single call to \fBOSSL_HPKE_encap()\fR is allowed for a given +\&\fBOSSL_HPKE_CTX\fR. +.PP +\&\fBOSSL_HPKE_seal()\fR takes the \fBOSSL_HPKE_CTX\fR context \fIctx\fR, the plaintext +buffer \fIpt\fR of size \fIptlen\fR and optional additional authenticated data buffer +\&\fIaad\fR of size \fIaadlen\fR, and returns the ciphertext \fIct\fR of size \fIctlen\fR. +On input \fIctlen\fR should contain the maximum size of the \fIct\fR buffer, and returns +the output size. An error will occur if the input \fIctlen\fR is +smaller than the value returned from \fBOSSL_HPKE_get_public_encap_size()\fR. +.PP +\&\fBOSSL_HPKE_encap()\fR must be called before the \fBOSSL_HPKE_seal()\fR. \fBOSSL_HPKE_seal()\fR +may be called multiple times, with an internal "nonce" being incremented by one +after each call. +.SS "Recipient APIs" +.IX Subsection "Recipient APIs" +Recipients using HPKE require a typically less ephemeral private value so that +the public value can be distributed to potential senders via whatever protocol +is using HPKE. For this reason, recipients will generally first generate a key +pair and will need to manage their private key value using standard mechanisms +outside the scope of this API. Private keys use normal \fBEVP_PKEY\fR\|(3) pointers +so normal private key management mechanisms can be used for the relevant +values. +.PP +In order to enable encapsulation, the recipient needs to make it\*(Aqs public value +available to the sender. There is no generic HPKE format defined for that \- the +relevant formatting is intended to be defined by the application/protocols that +makes use of HPKE. ECH for example defines an ECHConfig data structure that +combines the public value with other ECH data items. Normal library functions +must therefore be used to extract the public value in the required format based +on the \fBEVP_PKEY\fR\|(3) for the private value. +.PP +\&\fBOSSL_HPKE_keygen()\fR provides a way for recipients to generate a key pair based +on the HPKE \fIsuite\fR to be used. It returns a \fBEVP_PKEY\fR\|(3) pointer +for the private value \fIpriv\fR and a encoded public key \fIpub\fR of size \fIpublen\fR. +On input \fIpublen\fR should contain the maximum size of the \fIpub\fR buffer, and +returns the output size. An error will occur if the input \fIpublen\fR is too small. +The \fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers +and may be set to NULL. +The HPKE specification also defines a deterministic key generation scheme where +the private value is derived from initial keying material (IKM), so +\&\fBOSSL_HPKE_keygen()\fR also has an option to use that scheme, using the \fIikm\fR +parameter of size \fIikmlen\fR. If either \fIikm\fR is NULL or \fIikmlen\fR is zero, +then a randomly generated key for the relevant \fIsuite\fR will be produced. +If required \fIikmlen\fR should be greater than or equal to +\&\fBOSSL_HPKE_get_recommended_ikmelen()\fR. +.PP +\&\fBOSSL_HPKE_decap()\fR takes as input the sender\*(Aqs encapsulated public value +produced by \fBOSSL_HPKE_encap()\fR (\fIenc\fR) and the recipient\*(Aqs \fBEVP_PKEY\fR\|(3) +pointer (\fIprov\fR), and then re\-generates the internal secret derived by the +sender. As before, an optional \fIinfo\fR parameter allows binding that derived +secret to other application/protocol artefacts. Only a single call to +\&\fBOSSL_HPKE_decap()\fR is allowed for a given \fBOSSL_HPKE_CTX\fR. +.PP +\&\fBOSSL_HPKE_open()\fR is used by the recipient to decrypt the ciphertext \fIct\fR of +size \fIctlen\fR using the \fIctx\fR and additional authenticated data \fIaad\fR of +size \fIaadlen\fR, to produce the plaintext \fIpt\fR of size \fIptlen\fR. +On input \fIptlen\fR should contain the maximum size of the \fIpt\fR buffer, and +returns the output size. A \fIpt\fR buffer that is the same size as the +\&\fIct\fR buffer will suffice \- generally the plaintext output will be +a little smaller than the ciphertext input. +An error will occur if the input \fIptlen\fR is too small. +\&\fBOSSL_HPKE_open()\fR may be called multiple times, but as with \fBOSSL_HPKE_seal()\fR +there is an internally incrementing nonce value so ciphertexts need to be +presented in the same order as used by the \fBOSSL_HPKE_seal()\fR. +See "Re\-sequencing" if you need to process multiple ciphertexts in a +different order. +.SS "Exporting Secrets" +.IX Subsection "Exporting Secrets" +HPKE defines a way to produce exported secrets for use by the +application. +.PP +\&\fBOSSL_HPKE_export()\fR takes as input the \fBOSSL_HPKE_CTX\fR, and an application +supplied label \fIlabel\fR of size \fIlabellen\fR, to produce a secret \fIsecret\fR +of size \fIsecretlen\fR. The sender must first call \fBOSSL_HPKE_encap()\fR, and the +receiver must call \fBOSSL_HPKE_decap()\fR in order to derive the same shared secret. +.PP +Multiple calls to \fBOSSL_HPKE_export()\fR with the same inputs will produce the +same secret. +\&\fIOSSL_HPKE_AEAD_ID_EXPORTONLY\fR may be used as the \fBOSSL_HPKE_SUITE\fR \fIaead_id\fR +that is passed to \fBOSSL_HPKE_CTX_new()\fR if the user needs to produce a shared +secret, but does not wish to perform HPKE encryption. +.SS "Sender\-authenticated HPKE Modes" +.IX Subsection "Sender-authenticated HPKE Modes" +HPKE defines modes that support KEM\-based sender\-authentication +\&\fBOSSL_HPKE_MODE_AUTH\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR. This works by binding +the sender\*(Aqs authentication private/public values into the encapsulation and +decapsulation operations. The key used for such modes must also use the same +KEM as used for the overall exchange. \fBOSSL_HPKE_keygen()\fR can be used to +generate the private value required. +.PP +\&\fBOSSL_HPKE_CTX_set1_authpriv()\fR can be used by the sender to set the senders +private \fIpriv\fR \fBEVP_PKEY\fR key into the \fBOSSL_HPKE_CTX\fR \fIctx\fR before calling +\&\fBOSSL_HPKE_encap()\fR. +.PP +\&\fBOSSL_HPKE_CTX_set1_authpub()\fR can be used by the receiver to set the senders +encoded pub key \fIpub\fR of size \fIpublen\fR into the \fBOSSL_HPKE_CTX\fR \fIctx\fR before +calling \fBOSSL_HPKE_decap()\fR. +.SS "Pre\-Shared Key HPKE modes" +.IX Subsection "Pre-Shared Key HPKE modes" +HPKE also defines a symmetric equivalent to the authentication described above +using a pre\-shared key (PSK) and a PSK identifier. PSKs can be used with the +\&\fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR modes. +.PP +\&\fBOSSL_HPKE_CTX_set1_psk()\fR sets the PSK identifier \fIpskid\fR string, and PSK buffer +\&\fIpsk\fR of size \fIpsklen\fR into the \fIctx\fR. If required this must be called +before \fBOSSL_HPKE_encap()\fR or \fBOSSL_HPKE_decap()\fR. +As per RFC9180, if required, both \fIpsk\fR and \fIpskid\fR must be set to non\-NULL values. +As PSKs are symmetric the same calls must happen on both sender and receiver +sides. +.SS "Deterministic key generation for senders" +.IX Subsection "Deterministic key generation for senders" +Normally the senders ephemeral private key is generated randomly inside +\&\fBOSSL_HPKE_encap()\fR and remains secret. +\&\fBOSSL_HPKE_CTX_set1_ikme()\fR allows the user to override this behaviour by +setting a deterministic input key material \fIikm\fR of size \fIikmlen\fR into +the \fBOSSL_HPKE_CTX\fR \fIctx\fR. +If required \fBOSSL_HPKE_CTX_set1_ikme()\fR can optionally be called before +\&\fBOSSL_HPKE_encap()\fR. +\&\fIikmlen\fR should be greater than or equal to \fBOSSL_HPKE_get_recommended_ikmelen()\fR. +.PP +It is generally undesirable to use \fBOSSL_HPKE_CTX_set1_ikme()\fR, since it +exposes the relevant secret to the application rather then preserving it +within the library, and is more likely to result in use of predictable values +or values that leak. +.SS Re\-sequencing +.IX Subsection "Re-sequencing" +Some protocols may have to deal with packet loss while still being able to +decrypt arriving packets later. We provide a way to set the increment used for +the nonce to the next subsequent call to \fBOSSL_HPKE_open()\fR (but not to +\&\fBOSSL_HPKE_seal()\fR as explained below). The \fBOSSL_HPKE_CTX_set_seq()\fR API can be +used for such purposes with the \fIseq\fR parameter value resetting the internal +nonce increment to be used for the next call. +.PP +A baseline nonce value is established based on the encapsulation or +decapsulation operation and is then incremented by 1 for each call to seal or +open. (In other words, the first \fIseq\fR increment defaults to zero.) +.PP +If a caller needs to determine how many calls to seal or open have been made +the \fBOSSL_HPKE_CTX_get_seq()\fR API can be used to retrieve the increment (in the +\&\fIseq\fR output) that will be used in the next call to seal or open. That would +return 0 before the first call a sender made to \fBOSSL_HPKE_seal()\fR and 1 after +that first call. +.PP +Note that reuse of the same nonce and key with different plaintexts would +be very dangerous and could lead to loss of confidentiality and integrity. +We therefore only support application control over \fIseq\fR for decryption +(i.e. \fBOSSL_HPKE_open()\fR) operations. +.PP +For compatibility with other implementations these \fIseq\fR increments are +represented as \fIuint64_t\fR. +.SS "Protocol Convenience Functions" +.IX Subsection "Protocol Convenience Functions" +Additional convenience APIs allow the caller to access internal details of +local HPKE support and/or algorithms, such as parameter lengths. +.PP +\&\fBOSSL_HPKE_suite_check()\fR checks if a specific \fBOSSL_HPKE_SUITE\fR \fIsuite\fR +is supported locally. +.PP +To assist with memory allocation, \fBOSSL_HPKE_get_ciphertext_size()\fR provides a +way for the caller to know by how much ciphertext will be longer than a +plaintext of length \fIclearlen\fR. (AEAD algorithms add a data integrity tag, +so there is a small amount of ciphertext expansion.) +.PP +\&\fBOSSL_HPKE_get_public_encap_size()\fR provides a way for senders to know how big +the encapsulated public value will be for a given HPKE \fIsuite\fR. +.PP +\&\fBOSSL_HPKE_get_recommended_ikmelen()\fR returns the recommended Input Key Material +size (in bytes) for a given \fIsuite\fR. This is needed in cases where the same +public value needs to be regenerated by a sender before calling \fBOSSL_HPKE_seal()\fR. +\&\fIikmlen\fR should be at least this size. +.PP +\&\fBOSSL_HPKE_get_grease_value()\fR produces values of the appropriate length for a +given \fIsuite_in\fR value (or a random value if \fIsuite_in\fR is NULL) so that a +protocol using HPKE can send so\-called GREASE (see RFC8701) values that are +harder to distinguish from a real use of HPKE. The buffer sizes should +be supplied on input. The output \fIenc\fR value will have an appropriate +length for \fIsuite_out\fR and a random value, and the \fIct\fR output will be +a random value. The relevant sizes for buffers can be found using +\&\fBOSSL_HPKE_get_ciphertext_size()\fR and \fBOSSL_HPKE_get_public_encap_size()\fR. +.PP +\&\fBOSSL_HPKE_str2suite()\fR maps input \fIstr\fR strings to an \fBOSSL_HPKE_SUITE\fR object. +The input \fIstr\fR should be a comma\-separated string with a KEM, +KDF and AEAD name in that order, for example "x25519,hkdf\-sha256,aes\-128\-gcm". +This can be used by command line tools that accept string form names for HPKE +codepoints. Valid (case\-insensitive) names are: +"p\-256", "p\-384", "p\-521", "x25519" and "x448" for KEM, +"hkdf\-sha256", "hkdf\-sha384" and "hkdf\-sha512" for KDF, and +"aes\-128\-gcm", "aes\-256\-gcm", "chacha20\-poly1305" and "exporter" for AEAD. +String variants of the numbers listed in "OSSL_HPKE_SUITE Identifiers" +can also be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_HPKE_CTX_new()\fR returns an OSSL_HPKE_CTX pointer or NULL on error. +.PP +\&\fBOSSL_HPKE_get_ciphertext_size()\fR, \fBOSSL_HPKE_get_public_encap_size()\fR, +\&\fBOSSL_HPKE_get_recommended_ikmelen()\fR all return a size_t with the +relevant value or zero on error. +.PP +All other functions return 1 for success or zero for error. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example demonstrates a minimal round\-trip using HPKE. +.PP +.Vb 4 +\& #include +\& #include +\& #include +\& #include +\& +\& /* +\& * this is big enough for this example, real code would need different +\& * handling +\& */ +\& #define LBUFSIZE 48 +\& +\& /* Do a round\-trip, generating a key, encrypting and decrypting */ +\& int main(int argc, char **argv) +\& { +\& int ok = 0; +\& int hpke_mode = OSSL_HPKE_MODE_BASE; +\& OSSL_HPKE_SUITE hpke_suite = OSSL_HPKE_SUITE_DEFAULT; +\& OSSL_HPKE_CTX *sctx = NULL, *rctx = NULL; +\& EVP_PKEY *priv = NULL; +\& unsigned char pub[LBUFSIZE]; +\& size_t publen = sizeof(pub); +\& unsigned char enc[LBUFSIZE]; +\& size_t enclen = sizeof(enc); +\& unsigned char ct[LBUFSIZE]; +\& size_t ctlen = sizeof(ct); +\& unsigned char clear[LBUFSIZE]; +\& size_t clearlen = sizeof(clear); +\& const unsigned char *pt = "a message not in a bottle"; +\& size_t ptlen = strlen((char *)pt); +\& const unsigned char *info = "Some info"; +\& size_t infolen = strlen((char *)info); +\& unsigned char aad[] = { 1, 2, 3, 4, 5, 6, 7, 8 }; +\& size_t aadlen = sizeof(aad); +\& +\& /* +\& * Generate receiver\*(Aqs key pair. +\& * The receiver gives this public key to the sender. +\& */ +\& if (OSSL_HPKE_keygen(hpke_suite, pub, &publen, &priv, +\& NULL, 0, NULL, NULL) != 1) +\& goto err; +\& +\& /* sender\*(Aqs actions \- encrypt data using the receivers public key */ +\& if ((sctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite, +\& OSSL_HPKE_ROLE_SENDER, +\& NULL, NULL)) == NULL) +\& goto err; +\& if (OSSL_HPKE_encap(sctx, enc, &enclen, pub, publen, info, infolen) != 1) +\& goto err; +\& if (OSSL_HPKE_seal(sctx, ct, &ctlen, aad, aadlen, pt, ptlen) != 1) +\& goto err; +\& +\& /* receiver\*(Aqs actions \- decrypt data using the receivers private key */ +\& if ((rctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite, +\& OSSL_HPKE_ROLE_RECEIVER, +\& NULL, NULL)) == NULL) +\& goto err; +\& if (OSSL_HPKE_decap(rctx, enc, enclen, priv, info, infolen) != 1) +\& goto err; +\& if (OSSL_HPKE_open(rctx, clear, &clearlen, aad, aadlen, ct, ctlen) != 1) +\& goto err; +\& ok = 1; +\& err: +\& /* clean up */ +\& printf(ok ? "All Good!\en" : "Error!\en"); +\& OSSL_HPKE_CTX_free(rctx); +\& OSSL_HPKE_CTX_free(sctx); +\& EVP_PKEY_free(priv); +\& return 0; +\& } +.Ve +.SH WARNINGS +.IX Header "WARNINGS" +Note that the \fBOSSL_HPKE_CTX_set_seq()\fR API could be dangerous \- if used with GCM +that could lead to nonce\-reuse, which is a known danger. So avoid that +entirely, or be very very careful when using that API. +.PP +Use of an IKM value for deterministic key generation (via +\&\fBOSSL_HPKE_CTX_set1_ikme()\fR or \fBOSSL_HPKE_keygen()\fR) creates the potential for +leaking keys (or IKM values). Only use that if really needed and if you +understand how keys or IKM values could be abused. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The RFC9180 specification: https://datatracker.ietf.org/doc/rfc9180/ +.SH HISTORY +.IX Header "HISTORY" +This functionality described here was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_HTTP_REQ_CTX.3 b/static/netbsd/man3/OSSL_HTTP_REQ_CTX.3 new file mode 100644 index 00000000..57679139 --- /dev/null +++ b/static/netbsd/man3/OSSL_HTTP_REQ_CTX.3 @@ -0,0 +1,357 @@ +.\" $NetBSD: OSSL_HTTP_REQ_CTX.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_HTTP_REQ_CTX 3" +.TH OSSL_HTTP_REQ_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_HTTP_REQ_CTX, +OSSL_HTTP_REQ_CTX_new, +OSSL_HTTP_REQ_CTX_free, +OSSL_HTTP_REQ_CTX_set_request_line, +OSSL_HTTP_REQ_CTX_add1_header, +OSSL_HTTP_REQ_CTX_set_expected, +OSSL_HTTP_REQ_CTX_set1_req, +OSSL_HTTP_REQ_CTX_nbio, +OSSL_HTTP_REQ_CTX_nbio_d2i, +OSSL_HTTP_REQ_CTX_exchange, +OSSL_HTTP_REQ_CTX_get0_mem_bio, +OSSL_HTTP_REQ_CTX_get_resp_len, +OSSL_HTTP_REQ_CTX_set_max_response_length, +OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines, +OSSL_HTTP_is_alive +\&\- HTTP client low\-level functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX; +\& +\& OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size); +\& void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx); +\& +\& int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST, +\& const char *server, const char *port, +\& const char *path); +\& int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx, +\& const char *name, const char *value); +\& +\& int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx, +\& const char *expected_content_type, int expect_asn1, +\& int timeout, int keep_alive); +\& int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type, +\& const ASN1_ITEM *it, const ASN1_VALUE *req); +\& int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx); +\& int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx, +\& ASN1_VALUE **pval, const ASN1_ITEM *it); +\& BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx); +\& +\& BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx); +\& size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx); +\& void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx, +\& unsigned long len); +\& void OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines(OSSL_HTTP_REQ_CTX *rctx, +\& size_t count); +\& +\& int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_HTTP_REQ_CTX\fR is a context structure for an HTTP request and response, +used to collect all the necessary data to perform that request. +.PP +This file documents low\-level HTTP functions rarely used directly. High\-level +HTTP client functions like \fBOSSL_HTTP_get\fR\|(3) and \fBOSSL_HTTP_transfer\fR\|(3) +should be preferred. +.PP +\&\fBOSSL_HTTP_REQ_CTX_new()\fR allocates a new HTTP request context structure, +which gets populated with the \fBBIO\fR to write/send the request to (\fIwbio\fR), +the \fBBIO\fR to read/receive the response from (\fIrbio\fR, which may be equal to +\&\fIwbio\fR), and the maximum expected response header line length \fIbuf_size\fR. +A value <= 0 indicates that +the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR of 4KiB should be used. +\&\fIbuf_size\fR is also used as the number of content bytes that are read at a time. +The allocated context structure includes an internal memory \fBBIO\fR, +which collects the HTTP request header lines. +.PP +\&\fBOSSL_HTTP_REQ_CTX_free()\fR frees up the HTTP request context \fIrctx\fR. +The \fIrbio\fR is not free\*(Aqd, \fIwbio\fR will be free\*(Aqd if \fIfree_wbio\fR is set. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR adds the 1st HTTP request line to \fIrctx\fR. +The HTTP method is determined by \fImethod_POST\fR, +which should be 1 to indicate \f(CW\*(C`POST\*(C'\fR or 0 to indicate \f(CW\*(C`GET\*(C'\fR. +\&\fIserver\fR and \fIport\fR may be set to give the server and the optional port that +an HTTP proxy shall forward the request to, otherwise they must be left NULL. +\&\fIpath\fR provides the HTTP request path; if left NULL, \f(CW\*(C`/\*(C'\fR is used. +For backward compatibility, \fIpath\fR may begin with \f(CW\*(C`http://\*(C'\fR and thus convey +an absoluteURI. In this case it indicates HTTP proxy use and provides also the +server (and optionally the port) that the proxy shall forward the request to. +In this case the \fIserver\fR and \fIport\fR arguments must be NULL. +.PP +\&\fBOSSL_HTTP_REQ_CTX_add1_header()\fR adds header \fIname\fR with value \fIvalue\fR to the +context \fIrctx\fR. It can be called more than once to add multiple header lines. +For example, to add a \f(CW\*(C`Host\*(C'\fR header for \f(CW\*(C`example.com\*(C'\fR you would call: +.PP +.Vb 1 +\& OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); +.Ve +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_expected()\fR optionally sets in \fIrctx\fR some expectations +of the HTTP client on the response. +Due to the structure of an HTTP request, if the \fIkeep_alive\fR argument is +nonzero the function must be used before calling \fBOSSL_HTTP_REQ_CTX_set1_req()\fR. +.PP +If the \fIexpected_content_type\fR argument is not NULL, the client will +check in a case\-insensitive way that the specified \f(CW\*(C`Content\-Type\*(C'\fR string value +is included in the HTTP header of the response and return an error if not. +In the \f(CW\*(C`Content\-Type\*(C'\fR header line the specified string should be present either +as a whole, or in case the specified string does not include a \f(CW\*(C`;\*(C'\fR character, +it is sufficient that the specified string appears as a prefix +in the header line, followed by a \f(CW\*(C`;\*(C'\fR character and any further text. +For instance, if the \fIexpected_content_type\fR argument specifies \f(CW\*(C`text/html\*(C'\fR, +this is matched by \f(CW\*(C`Text/HTML\*(C'\fR, \f(CW\*(C`text/html; charset=UTF\-8\*(C'\fR, etc. +.PP +If the \fIexpect_asn1\fR parameter is nonzero a structure in ASN.1 encoding will be +expected as the response content and input streaming is disabled. This means +that an ASN.1 sequence header is required, its length field is checked, and +\&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR should be used to get the buffered response. +Otherwise (by default) any input format is allowed, +with body length checks being performed on error messages only. +In this case the BIO given as \fIrbio\fR argument to \fBOSSL_HTTP_REQ_CTX_new()\fR should +be used directly to read the response contents, which may support streaming. +.PP +If the \fItimeout\fR parameter is > 0 this indicates the maximum number of seconds +the subsequent HTTP transfer (sending the request and receiving a response) +is allowed to take. +\&\fItimeout\fR == 0 enables waiting indefinitely, i.e., no timeout can occur. +This is the default. +\&\fItimeout\fR < 0 takes over any value set via the \fIoverall_timeout\fR argument of +\&\fBOSSL_HTTP_open\fR\|(3) with the default being 0, which means no timeout. +.PP +If the \fIkeep_alive\fR parameter is 0, which is the default, the connection is not +kept open after receiving a response. This is the default behavior for HTTP 1.0. +If the value is 1 or 2 then a persistent connection is requested. +If the value is 2 then a persistent connection is required, +i.e., an error occurs in case the server does not grant it. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR finalizes the HTTP request context. +It is needed if the \fImethod_POST\fR parameter in the +\&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR call was 1 +and an ASN.1\-encoded request should be sent. +It must also be used when requesting "keep\-alive", +even if a GET request is going to be sent, in which case \fIreq\fR must be NULL. +Unless \fIreq\fR is NULL, the function adds the DER encoding of \fIreq\fR using +the ASN.1 template \fIit\fR to do the encoding (which does not support streaming). +The HTTP header \f(CW\*(C`Content\-Length\*(C'\fR is filled out with the length of the request. +\&\fIcontent_type\fR must be NULL if \fIreq\fR is NULL. +If \fIcontent_type\fR isn\*(Aqt NULL, +the HTTP header \f(CW\*(C`Content\-Type\*(C'\fR is also added with the given string value. +The header lines are added to the internal memory \fBBIO\fR for the request header. +.PP +\&\fBOSSL_HTTP_REQ_CTX_nbio()\fR attempts to send the request prepared in \fIrctx\fR +and to gather the response via HTTP, using the \fIwbio\fR and \fIrbio\fR +that were given when calling \fBOSSL_HTTP_REQ_CTX_new()\fR. +The function may need to be called again if its result is \-1, which indicates +\&\fBBIO_should_retry\fR\|(3). In such a case it is advisable to sleep a little in +between, using \fBBIO_wait\fR\|(3) on the read BIO to prevent a busy loop. +See \fBOSSL_HTTP_REQ_CTX_set_expected()\fR how the response content type, +the response body, the HTTP transfer timeout, and "keep\-alive" are treated. +Any error message body is consumed +if a \f(CW\*(C`Content\-Type\*(C'\fR header is not included or its value starts with \f(CW\*(C`text/\*(C'\fR. +This is used for tracing the body contents if HTTP tracing is enabled. +If the \f(CW\*(C`Content\-Length\*(C'\fR header is present in the response +and its value exceeds the maximum allowed response content length +or the response is an error message with its body length exceeding this value +or the content is an ASN.1\-encoded structure with a length exceeding this value +or both length indications are present but disagree then an error occurs. +.PP +\&\fBOSSL_HTTP_REQ_CTX_nbio_d2i()\fR is like \fBOSSL_HTTP_REQ_CTX_nbio()\fR but on success +in addition parses the response, which must be a DER\-encoded ASN.1 structure, +using the ASN.1 template \fIit\fR and places the result in \fI*pval\fR. +.PP +\&\fBOSSL_HTTP_REQ_CTX_exchange()\fR calls \fBOSSL_HTTP_REQ_CTX_nbio()\fR as often as needed +in order to exchange a request and response or until a timeout is reached. +On success it returns a pointer to the BIO that can be used to read the result. +If an ASN.1\-encoded response was expected, this is the BIO +returned by \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR when called after the exchange. +This memory BIO does not support streaming. +Otherwise the returned BIO is the \fIrbio\fR given to \fBOSSL_HTTP_REQ_CTX_new()\fR, +which may support streaming. +When this BIO is returned, it has been read past the end of the response header, +such that the actual response body can be read from it. +The returned BIO pointer MUST NOT be freed by the caller. +.PP +\&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR returns the internal memory \fBBIO\fR. +Before the HTTP request is sent, this could be used to adapt its header lines. +\&\fIUse with caution!\fR +After receiving a response via HTTP, the BIO represents the current state of +reading the response header. If the response was expected to be ASN.1 encoded, +its contents can be read via this BIO, which does not support streaming. +The returned BIO pointer must not be freed by the caller. +.PP +\&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents +in \fIrctx\fR if provided by the server as \f(CW\*(C`Content\-Length\*(C'\fR header field, else 0. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR sets the maximum allowed +response content length for \fIrctx\fR to \fIlen\fR. If not set or \fIlen\fR is 0 +then the \fBOSSL_HTTP_DEFAULT_MAX_RESP_LEN\fR is used, which currently is 100 KiB. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR changes the limit for +the number of HTTP header lines allowed to be received in a response. +The default limit is \fBOSSL_HTTP_DEFAULT_MAX_RESP_HDR_LINES\fR, currently 256. +If the limit is not 0 and the number of lines exceeds the limit, +then the HTTP_R_RESPONSE_TOO_MANY_HDRLINES error is indicated. +Setting the limit to 0 disables the check. +.PP +\&\fBOSSL_HTTP_is_alive()\fR can be used to query if the HTTP connection +given by \fIrctx\fR is still alive, i.e., has not been closed. +It returns 0 if \fIrctx\fR is NULL. +.PP +If the client application requested or required a persistent connection +and this was granted by the server, it can keep \fIrctx\fR as long as it wants +to send further requests and \fBOSSL_HTTP_is_alive()\fR returns nonzero, +else it should call \fIOSSL_HTTP_REQ_CTX_free(rctx)\fR or \fBOSSL_HTTP_close\fR\|(3). +In case the client application keeps \fIrctx\fR but the connection then dies +for any reason at the server side, it will notice this obtaining an +I/O error when trying to send the next request via \fIrctx\fR. +.SH WARNINGS +.IX Header "WARNINGS" +The server\*(Aqs response may be unexpected if the hostname that was used to +create the \fIwbio\fR, any \f(CW\*(C`Host\*(C'\fR header, and the host specified in the +request URL do not match. +.PP +Many of these functions must be called in a certain order. +.PP +First, the HTTP request context must be allocated: +\&\fBOSSL_HTTP_REQ_CTX_new()\fR. +.PP +Then, the HTTP request must be prepared with request data: +.IP 1. 4 +Calling \fBOSSL_HTTP_REQ_CTX_set_request_line()\fR. +.IP 2. 4 +Adding extra header lines with \fBOSSL_HTTP_REQ_CTX_add1_header()\fR. +This is optional and may be done multiple times with different names. +.IP 3. 4 +Finalize the request using \fBOSSL_HTTP_REQ_CTX_set1_req()\fR. +This may be omitted if the GET method is used and "keep\-alive" is not requested. +.PP +When the request context is fully prepared, the HTTP exchange may be performed +with \fBOSSL_HTTP_REQ_CTX_nbio()\fR or \fBOSSL_HTTP_REQ_CTX_exchange()\fR. +.SH NOTES +.IX Header "NOTES" +When built with tracing enabled, \fBOSSL_HTTP_REQ_CTX_nbio()\fR and all functions +using it, such as \fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_transfer\fR\|(3), +may be traced using \fBOSSL_TRACE_CATEGORY_HTTP\fR. +See also \fBOSSL_trace_enabled\fR\|(3) and \fBopenssl\-env\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_HTTP_REQ_CTX_new()\fR returns a pointer to a \fBOSSL_HTTP_REQ_CTX\fR, or NULL +on error. +.PP +\&\fBOSSL_HTTP_REQ_CTX_free()\fR, \fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR, and +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR do not return values. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR, \fBOSSL_HTTP_REQ_CTX_add1_header()\fR, +\&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR, and \fBOSSL_HTTP_REQ_CTX_set_expected()\fR +return 1 for success and 0 for failure. +.PP +\&\fBOSSL_HTTP_REQ_CTX_nbio()\fR and \fBOSSL_HTTP_REQ_CTX_nbio_d2i()\fR +return 1 for success, 0 on error or redirection, \-1 if retry is needed. +.PP +\&\fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR +return a pointer to a \fBBIO\fR on success as described above or NULL on failure. +The returned BIO must not be freed by the caller. +.PP +\&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents +or 0 if not available or an error occurred. +.PP +\&\fBOSSL_HTTP_is_alive()\fR returns 1 if its argument is non\-NULL +and the client requested a persistent connection +and the server did not disagree on keeping the connection open, else 0. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_should_retry\fR\|(3), +\&\fBBIO_wait\fR\|(3), +\&\fBASN1_item_d2i_bio\fR\|(3), +\&\fBASN1_item_i2d_mem_bio\fR\|(3), +\&\fBOSSL_HTTP_open\fR\|(3), +\&\fBOSSL_HTTP_get\fR\|(3), +\&\fBOSSL_HTTP_transfer\fR\|(3), +\&\fBOSSL_HTTP_close\fR\|(3), +\&\fBOSSL_trace_enabled\fR\|(3), and \fBopenssl\-env\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR was added in OpenSSL 3.3. +.PP +All other functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_HTTP_parse_url.3 b/static/netbsd/man3/OSSL_HTTP_parse_url.3 new file mode 100644 index 00000000..c28e3e0e --- /dev/null +++ b/static/netbsd/man3/OSSL_HTTP_parse_url.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: OSSL_HTTP_parse_url.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_HTTP_parse_url 3" +.TH OSSL_HTTP_parse_url 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_HTTP_adapt_proxy, +OSSL_parse_url, +OSSL_HTTP_parse_url, +OCSP_parse_url +\&\- http utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *OSSL_HTTP_adapt_proxy(const char *proxy, const char *no_proxy, +\& const char *server, int use_ssl); +\& +\& int OSSL_parse_url(const char *url, char **pscheme, char **puser, char **phost, +\& char **pport, int *pport_num, +\& char **ppath, char **pquery, char **pfrag); +\& int OSSL_HTTP_parse_url(const char *url, +\& int *pssl, char **puser, char **phost, +\& char **pport, int *pport_num, +\& char **ppath, char **pquery, char **pfrag); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath, +\& int *pssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_HTTP_adapt_proxy()\fR takes an optional proxy hostname \fIproxy\fR +and returns it transformed according to the optional \fIno_proxy\fR parameter, +\&\fIserver\fR, \fIuse_ssl\fR, and the applicable environment variable, as follows. +If \fIproxy\fR is NULL, take any default value from the \f(CW\*(C`http_proxy\*(C'\fR +environment variable, or from \f(CW\*(C`https_proxy\*(C'\fR if \fIuse_ssl\fR is nonzero. +If this still does not yield a proxy hostname, +take any further default value from the \f(CW\*(C`HTTP_PROXY\*(C'\fR +environment variable, or from \f(CW\*(C`HTTPS_PROXY\*(C'\fR if \fIuse_ssl\fR is nonzero. +If \fIno_proxy\fR is NULL, take any default exclusion value from the \f(CW\*(C`no_proxy\*(C'\fR +environment variable, or else from \f(CW\*(C`NO_PROXY\*(C'\fR. +Return the determined proxy host unless the exclusion value, +which is a list of proxy hosts separated by \f(CW\*(C`,\*(C'\fR and/or whitespace, +contains \fIserver\fR. +Otherwise return NULL. +When \fIserver\fR is a string delimited by \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR, which are used for IPv6 +addresses, the enclosing \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR are stripped prior to comparison. +.PP +\&\fBOSSL_parse_url()\fR parses its input string \fIurl\fR as a URL of the form +\&\f(CW\*(C`[scheme://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR and splits it up +into scheme, userinfo, host, port, path, query, and fragment components. +The host (or server) component may be a DNS name or an IP address +where IPv6 addresses must be enclosed in square brackets \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +The port component is optional and defaults to \f(CW0\fR. +If given, it must be in decimal form. If the \fIpport_num\fR argument is not NULL +the integer value of the port number is assigned to \fI*pport_num\fR on success. +The path component is also optional and defaults to \f(CW\*(C`/\*(C'\fR. +Each non\-NULL result pointer argument \fIpscheme\fR, \fIpuser\fR, \fIphost\fR, \fIpport\fR, +\&\fIppath\fR, \fIpquery\fR, and \fIpfrag\fR, is assigned the respective url component. +Any IPv6 address in \fI*phost\fR is enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +On success, they are guaranteed to contain non\-NULL string pointers, else NULL. +It is the responsibility of the caller to free them using \fBOPENSSL_free\fR\|(3). +If \fIpquery\fR is NULL, any given query component is handled as part of the path. +A string returned via \fI*ppath\fR is guaranteed to begin with a \f(CW\*(C`/\*(C'\fR character. +For absent scheme, userinfo, port, query, and fragment components +an empty string is provided. +.PP +\&\fBOSSL_HTTP_parse_url()\fR is a special form of \fBOSSL_parse_url()\fR +where the scheme, if given, must be \f(CW\*(C`http\*(C'\fR or \f(CW\*(C`https\*(C'\fR. +If \fIpssl\fR is not NULL, \fI*pssl\fR is assigned 1 in case parsing was successful +and the scheme is \f(CW\*(C`https\*(C'\fR, else 0. +The port component is optional and defaults to \f(CW443\fR if the scheme is \f(CW\*(C`https\*(C'\fR, +else \f(CW80\fR. +Note that relative paths must be given with a leading \f(CW\*(C`/\*(C'\fR, +otherwise the first path element is interpreted as the host. +.PP +Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl) +is equivalent to +OSSL_HTTP_parse_url(url, ssl, NULL, host, port, NULL, path, NULL, NULL). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_HTTP_adapt_proxy()\fR returns NULL if no proxy is to be used, +otherwise a constant proxy hostname string, +which is either the proxy name handed in or an environment variable value. +.PP +\&\fBOSSL_parse_url()\fR, \fBOSSL_HTTP_parse_url()\fR, and \fBOCSP_parse_url()\fR +return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_HTTP_transfer\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_HTTP_adapt_proxy()\fR, +\&\fBOSSL_parse_url()\fR and \fBOSSL_HTTP_parse_url()\fR were added in OpenSSL 3.0. +\&\fBOCSP_parse_url()\fR was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_HTTP_transfer.3 b/static/netbsd/man3/OSSL_HTTP_transfer.3 new file mode 100644 index 00000000..c5d286f3 --- /dev/null +++ b/static/netbsd/man3/OSSL_HTTP_transfer.3 @@ -0,0 +1,346 @@ +.\" $NetBSD: OSSL_HTTP_transfer.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_HTTP_transfer 3" +.TH OSSL_HTTP_transfer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_HTTP_open, +OSSL_HTTP_bio_cb_t, +OSSL_HTTP_proxy_connect, +OSSL_HTTP_set1_request, +OSSL_HTTP_exchange, +OSSL_HTTP_get, +OSSL_HTTP_transfer, +OSSL_HTTP_close +\&\- HTTP client high\-level functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, +\& int connect, int detail); +\& OSSL_HTTP_REQ_CTX *OSSL_HTTP_open(const char *server, const char *port, +\& const char *proxy, const char *no_proxy, +\& int use_ssl, BIO *bio, BIO *rbio, +\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, +\& int buf_size, int overall_timeout); +\& int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port, +\& const char *proxyuser, const char *proxypass, +\& int timeout, BIO *bio_err, const char *prog); +\& int OSSL_HTTP_set1_request(OSSL_HTTP_REQ_CTX *rctx, const char *path, +\& const STACK_OF(CONF_VALUE) *headers, +\& const char *content_type, BIO *req, +\& const char *expected_content_type, int expect_asn1, +\& size_t max_resp_len, int timeout, int keep_alive); +\& BIO *OSSL_HTTP_exchange(OSSL_HTTP_REQ_CTX *rctx, char **redirection_url); +\& BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy, +\& BIO *bio, BIO *rbio, +\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, +\& int buf_size, const STACK_OF(CONF_VALUE) *headers, +\& const char *expected_content_type, int expect_asn1, +\& size_t max_resp_len, int timeout); +\& BIO *OSSL_HTTP_transfer(OSSL_HTTP_REQ_CTX **prctx, +\& const char *server, const char *port, +\& const char *path, int use_ssl, +\& const char *proxy, const char *no_proxy, +\& BIO *bio, BIO *rbio, +\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, +\& int buf_size, const STACK_OF(CONF_VALUE) *headers, +\& const char *content_type, BIO *req, +\& const char *expected_content_type, int expect_asn1, +\& size_t max_resp_len, int timeout, int keep_alive); +\& int OSSL_HTTP_close(OSSL_HTTP_REQ_CTX *rctx, int ok); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_HTTP_open()\fR initiates an HTTP session using the \fIbio\fR argument if not +NULL, else by connecting to a given \fIserver\fR optionally via a \fIproxy\fR. +.PP +Typically the OpenSSL build supports sockets and the \fIbio\fR parameter is NULL. +In this case \fIrbio\fR must be NULL as well and the \fIserver\fR must be non\-NULL. +The function creates a network BIO internally using \fBBIO_new_connect\fR\|(3) +for connecting to the given server and the optionally given \fIport\fR, +defaulting to 80 for HTTP or 443 for HTTPS. +Then this internal BIO is used for setting up a connection +and for exchanging one or more request and response. +.PP +If \fIbio\fR is given and \fIrbio\fR is NULL then this \fIbio\fR is used instead. +If both \fIbio\fR and \fIrbio\fR are given (which may be memory BIOs for instance) +then no explicit connection is set up, but +\&\fIbio\fR is used for writing requests and \fIrbio\fR for reading responses. +As soon as the client has flushed \fIbio\fR the server must be ready to provide +a response or indicate a waiting condition via \fIrbio\fR. +.PP +If \fIbio\fR is given, +it is an error to provide non\-NULL \fIproxy\fR or \fIno_proxy\fR arguments, +while \fIserver\fR and \fIport\fR arguments may be given to support diagnostic output. +If \fIbio\fR is NULL the optional \fIproxy\fR parameter can be used to set an +HTTP(S) proxy to use (unless overridden by "no_proxy" settings). +If TLS is not used this defaults to the environment variable \f(CW\*(C`http_proxy\*(C'\fR +if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR. +If \fIuse_ssl\fR != 0 it defaults to \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR. +An empty proxy string \f(CW""\fR forbids using a proxy. +Otherwise, the format is +\&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR, +where any userinfo, path, query, and fragment given is ignored. +If the host string is an IPv6 address, it must be enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR. +The default proxy port number is 80, or 443 in case "https:" is given. +The HTTP client functions connect via the given proxy unless the \fIserver\fR +is found in the optional list \fIno_proxy\fR of proxy hostnames or IP addresses +separated by \f(CW\*(C`,\*(C'\fR and/or whitespace (if not NULL; +default is the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR). +Proxying plain HTTP is supported directly, +while using a proxy for HTTPS connections requires a suitable callback function +such as \fBOSSL_HTTP_proxy_connect()\fR, described below. +.PP +If \fIuse_ssl\fR is nonzero a TLS connection is requested +and the \fIbio_update_fn\fR parameter must be provided. +.PP +The parameter \fIbio_update_fn\fR, which is optional if \fIuse_ssl\fR is 0, +may be used to modify the connection BIO used by the HTTP client, +but cannot be used when both \fIbio\fR and \fIrbio\fR are given. +\&\fIbio_update_fn\fR is a BIO connect/disconnect callback function with prototype +.PP +.Vb 1 +\& BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail) +.Ve +.PP +The callback function may modify the BIO provided in the \fIbio\fR argument, +whereby it may use an optional custom defined argument \fIarg\fR, +which can for instance point to an \fBSSL_CTX\fR structure. +During connection establishment, just after calling \fBBIO_do_connect_retry()\fR, the +callback function is invoked with the \fIconnect\fR argument being 1 and +\&\fIdetail\fR being 1 if \fIuse_ssl\fR is nonzero (i.e., HTTPS is requested), else 0. +On disconnect \fIconnect\fR is 0 and \fIdetail\fR is 1 if no error occurred, else 0. +For instance, on connect the callback may push an SSL BIO to implement HTTPS; +after disconnect it may do some diagnostic output and pop and free the SSL BIO. +.PP +The callback function must return either the potentially modified BIO \fIbio\fR +or NULL to indicate failure, in which case it should not modify the BIO. +.PP +Here is a simple example that supports TLS connections (but not via a proxy): +.PP +.Vb 5 +\& BIO *http_tls_cb(BIO *bio, void *arg, int connect, int detail) +\& { +\& if (connect && detail) { /* connecting with TLS */ +\& SSL_CTX *ctx = (SSL_CTX *)arg; +\& BIO *sbio = BIO_new_ssl(ctx, 1); +\& +\& bio = sbio != NULL ? BIO_push(sbio, bio) : NULL; +\& } else if (!connect) { /* disconnecting */ +\& BIO *hbio; +\& +\& if (!detail) { /* an error has occurred */ +\& /* optionally add diagnostics here */ +\& } +\& BIO_ssl_shutdown(bio); +\& hbio = BIO_pop(bio); +\& BIO_free(bio); /* SSL BIO */ +\& bio = hbio; +\& } +\& return bio; +\& } +.Ve +.PP +After disconnect the modified BIO will be deallocated using \fBBIO_free_all()\fR. +The optional callback function argument \fIarg\fR is not consumed, +so must be freed by the caller when not needed any more. +.PP +The \fIbuf_size\fR parameter specifies the response header maximum line length. +A value <= 0 means that the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR (4KiB) is used. +\&\fIbuf_size\fR is also used as the number of content bytes that are read at a time. +.PP +If the \fIoverall_timeout\fR parameter is > 0 this indicates the maximum number of +seconds the overall HTTP transfer (i.e., connection setup if needed, +sending requests, and receiving responses) is allowed to take until completion. +A value <= 0 enables waiting indefinitely, i.e., no timeout. +.PP +\&\fBOSSL_HTTP_proxy_connect()\fR may be used by an above BIO connect callback function +to set up an SSL/TLS connection via an HTTPS proxy. +It promotes the given BIO \fIbio\fR representing a connection +pre\-established with a TLS proxy using the HTTP CONNECT method, +optionally using proxy client credentials \fIproxyuser\fR and \fIproxypass\fR, +to connect with TLS protection ultimately to \fIserver\fR and \fIport\fR. +If the \fIport\fR argument is NULL or the empty string it defaults to "443". +If the \fItimeout\fR parameter is > 0 this indicates the maximum number of +seconds the connection setup is allowed to take. +A value <= 0 enables waiting indefinitely, i.e., no timeout. +Since this function is typically called by applications such as +\&\fBopenssl\-s_client\fR\|(1) it uses the \fIbio_err\fR and \fIprog\fR parameters (unless +NULL) to print additional diagnostic information in a user\-oriented way. +.PP +\&\fBOSSL_HTTP_set1_request()\fR sets up in \fIrctx\fR the request header and content data +and expectations on the response using the following parameters. +If indicates using a proxy for HTTP (but not HTTPS), the server host +(and optionally port) needs to be placed in the header; thus it must be present +in \fIrctx\fR. +For backward compatibility, the server (and optional port) may also be given in +the \fIpath\fR argument beginning with \f(CW\*(C`http://\*(C'\fR (thus giving an absoluteURI). +If \fIpath\fR is NULL it defaults to "/". +If \fIreq\fR is NULL the HTTP GET method will be used to send the request +else HTTP POST with the contents of \fIreq\fR and optional \fIcontent_type\fR, where +the length of the data in \fIreq\fR does not need to be determined in advance: the +BIO will be read on\-the\-fly while sending the request, which supports streaming. +The optional list \fIheaders\fR may contain additional custom HTTP header lines. +The \fImax_resp_len\fR parameter specifies the maximum allowed +response content length, where the value 0 indicates no limit. +For the meaning of the \fIexpected_content_type\fR, \fIexpect_asn1\fR, \fItimeout\fR, +and \fIkeep_alive\fR parameters, see \fBOSSL_HTTP_REQ_CTX_set_expected\fR\|(3). +.PP +\&\fBOSSL_HTTP_exchange()\fR exchanges any form of HTTP request and response +as specified by \fIrctx\fR, which must include both connection and request data, +typically set up using \fBOSSL_HTTP_open()\fR and \fBOSSL_HTTP_set1_request()\fR. +It implements the core of the functions described below. +If the HTTP method is GET and \fIredirection_url\fR +is not NULL the latter pointer is used to provide any new location that +the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). +In this case the function returns NULL and the caller is +responsible for deallocating the URL with \fBOPENSSL_free\fR\|(3). +If the response header contains one or more \f(CW\*(C`Content\-Length\*(C'\fR lines and/or +an ASN.1\-encoded response is expected, which should include a total length, +the length indications received are checked for consistency +and for not exceeding any given maximum response length. +If an ASN.1\-encoded response is expected, the function returns on success +the contents buffered in a memory BIO, which does not support streaming. +Otherwise it returns directly the read BIO that holds the response contents, +which allows a response of indefinite length and may support streaming. +The caller is responsible for freeing the BIO pointer obtained. +.PP +\&\fBOSSL_HTTP_get()\fR uses HTTP GET to obtain data from \fIbio\fR if non\-NULL, +else from the server contained in the \fIurl\fR, and returns it as a BIO. +It supports redirection via HTTP status code 301 or 302. It is meant for +transfers with a single round trip, so does not support persistent connections. +If \fIbio\fR is non\-NULL, any host and port components in the \fIurl\fR are not used +for connecting but the hostname is used, as usual, for the \f(CW\*(C`Host\*(C'\fR header. +Any userinfo and fragment components in the \fIurl\fR are ignored. +Any query component is handled as part of the path component. +If the scheme component of the \fIurl\fR is \f(CW\*(C`https\*(C'\fR a TLS connection is requested +and the \fIbio_update_fn\fR, as described for \fBOSSL_HTTP_open()\fR, must be provided. +Also the remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR +and \fBOSSL_HTTP_set1_request()\fR, respectively. +The caller is responsible for freeing the BIO pointer obtained. +.PP +\&\fBOSSL_HTTP_transfer()\fR exchanges an HTTP request and response +over a connection managed via \fIprctx\fR without supporting redirection. +It combines \fBOSSL_HTTP_open()\fR, \fBOSSL_HTTP_set1_request()\fR, \fBOSSL_HTTP_exchange()\fR, +and \fBOSSL_HTTP_close()\fR. +If \fIprctx\fR is not NULL it reuses any open connection represented by a non\-NULL +\&\fI*prctx\fR. It keeps the connection open if a persistent connection is requested +or required and this was granted by the server, else it closes the connection +and assigns NULL to \fI*prctx\fR. +The remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR +and \fBOSSL_HTTP_set1_request()\fR, respectively. +The caller is responsible for freeing the BIO pointer obtained. +.PP +\&\fBOSSL_HTTP_close()\fR closes the connection and releases \fIrctx\fR. +The \fIok\fR parameter is passed to any BIO update function +given during setup as described above for \fBOSSL_HTTP_open()\fR. +It must be 1 if no error occurred during the HTTP transfer and 0 otherwise. +.SH NOTES +.IX Header "NOTES" +The names of the environment variables used by this implementation: +\&\f(CW\*(C`http_proxy\*(C'\fR, \f(CW\*(C`HTTP_PROXY\*(C'\fR, \f(CW\*(C`https_proxy\*(C'\fR, \f(CW\*(C`HTTPS_PROXY\*(C'\fR, \f(CW\*(C`no_proxy\*(C'\fR, and +\&\f(CW\*(C`NO_PROXY\*(C'\fR, have been chosen for maximal compatibility with +other HTTP client implementations such as wget, curl, and git. +.PP +When built with tracing enabled, \fBOSSL_HTTP_transfer()\fR and all functions using it +may be traced using \fBOSSL_TRACE_CATEGORY_HTTP\fR. +See also \fBOSSL_trace_enabled\fR\|(3) and \fBopenssl\-env\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_HTTP_open()\fR returns on success a \fBOSSL_HTTP_REQ_CTX\fR, else NULL. +.PP +\&\fBOSSL_HTTP_proxy_connect()\fR and \fBOSSL_HTTP_set1_request()\fR +return 1 on success, 0 on error. +.PP +On success, \fBOSSL_HTTP_exchange()\fR, \fBOSSL_HTTP_get()\fR, and \fBOSSL_HTTP_transfer()\fR +return a memory BIO that buffers all the data received if an ASN.1\-encoded +response is expected, otherwise a BIO that may support streaming. +The BIO must be freed by the caller. +On failure, they return NULL. +Failure conditions include connection/transfer timeout, parse errors, etc. +The caller is responsible for freeing the BIO pointer obtained. +.PP +\&\fBOSSL_HTTP_close()\fR returns 0 if anything went wrong while disconnecting, else 1. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_HTTP_parse_url\fR\|(3), \fBBIO_new_connect\fR\|(3), +\&\fBASN1_item_i2d_mem_bio\fR\|(3), \fBASN1_item_d2i_bio\fR\|(3), +\&\fBOSSL_HTTP_REQ_CTX_set_expected\fR\|(3), +\&\fBOSSL_HTTP_is_alive\fR\|(3), +\&\fBOSSL_trace_enabled\fR\|(3), and \fBopenssl\-env\fR\|(7). +.SH HISTORY +.IX Header "HISTORY" +All the functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX.3 b/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX.3 new file mode 100644 index 00000000..05dcb360 --- /dev/null +++ b/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: OSSL_IETF_ATTR_SYNTAX.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_IETF_ATTR_SYNTAX 3" +.TH OSSL_IETF_ATTR_SYNTAX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_IETF_ATTR_SYNTAX, +OSSL_IETF_ATTR_SYNTAX_get0_policyAuthority, +OSSL_IETF_ATTR_SYNTAX_set0_policyAuthority, +OSSL_IETF_ATTR_SYNTAX_get_value_num, +OSSL_IETF_ATTR_SYNTAX_get0_value, +OSSL_IETF_ATTR_SYNTAX_add1_value +\&\- Accessors and setters for OSSL_IETF_ATTR_SYNTAX +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct OSSL_IETF_ATTR_SYNTAX_st OSSL_IETF_ATTR_SYNTAX; +\& +\& const GENERAL_NAMES * +\& OSSL_IETF_ATTR_SYNTAX_get0_policyAuthority(const OSSL_IETF_ATTR_SYNTAX *a); +\& void OSSL_IETF_ATTR_SYNTAX_set0_policyAuthority(OSSL_IETF_ATTR_SYNTAX *a, +\& GENERAL_NAMES *names); +\& +\& int OSSL_IETF_ATTR_SYNTAX_get_value_num(const OSSL_IETF_ATTR_SYNTAX *a); +\& void *OSSL_IETF_ATTR_SYNTAX_get0_value(const OSSL_IETF_ATTR_SYNTAX *a, +\& int ind, int *type); +\& int OSSL_IETF_ATTR_SYNTAX_add1_value(OSSL_IETF_ATTR_SYNTAX *a, int type, +\& void *data); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_IETF_ATTR_SYNTAX\fR is an opaque structure that represents the +IetfAttrSyntax type defined in RFC 5755 (Section 4.4) for use +as an AttributeValue. +.PP +\&\fBOSSL_IETF_ATTR_SYNTAX_get0_policyAuthority()\fR and \fBOSSL_IETF_ATTR_SYNTAX_set0_policyAuthority()\fR +get and set the policyAuthority field of the structure. Both routines act on +internal pointers of the structure and must not be freed by the application. +.PP +An \fBOSSL_IETF_ATTR_SYNTAX\fR object also holds a sequence of values. +\&\fBOSSL_IETF_ATTR_SYNTAX_get_value_num()\fR returns the number of values in the +sequence. \fBOSSL_IETF_ATTR_SYNTAX_add1_value()\fR, adds a copy of \fIdata\fR of a specified +\&\fItype\fR to the sequence. The caller should free the \fIdata\fR after use. +.PP +\&\fBOSSL_IETF_ATTR_SYNTAX_get0_value()\fR will return the value and a specific index \fIind\fR +in the sequence or NULL on error. If \fItype\fR is not NULL, the type of the +value will be written to this location. +.PP +The \fItype\fR of the values stored in the \fBOSSL_IETF_ATTR_SYNTAX\fR value sequence is +one of the following: +.IP OSSL_IETFAS_OCTETS 4 +.IX Item "OSSL_IETFAS_OCTETS" +A pointer to an ASN1_OCTET_STRING +.IP OSSL_IETFAS_OID 4 +.IX Item "OSSL_IETFAS_OID" +A pointer to an ASN1_OBJECT +.IP OSSL_IETFAS_STRING 4 +.IX Item "OSSL_IETFAS_STRING" +A pointer to an ASN1_UTF8STRING +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_IETF_ATTR_SYNTAX_get0_policyAuthority()\fR returns an pointer to a +\&\fBGENERAL_NAMES\fR structure or \fBNULL\fR if the policy authority has not been +set. +.PP +\&\fBOSSL_IETF_ATTR_SYNTAX_get_value_num()\fR returns the number of entries in the value +sequence or \-1 on error. +.PP +\&\fBOSSL_IETF_ATTR_SYNTAX_get0_value()\fR returns a pointer to the value at the given index +or NULL if the index is out of range. +.PP +\&\fBOSSL_IETF_ATTR_SYNTAX_add1_value()\fR returns 1 on success and 0 on failure. +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_IETF_ATTR_SYNTAX_get0_policyAuthority()\fR, \fBOSSL_IETF_ATTR_SYNTAX_set0_policyAuthority()\fR, +\&\fBOSSL_IETF_ATTR_SYNTAX_get_value_num()\fR, \fBOSSL_IETF_ATTR_SYNTAX_get0_value()\fR, and +\&\fBOSSL_IETF_ATTR_SYNTAX_add1_value()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX_print.3 b/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX_print.3 new file mode 100644 index 00000000..6ad53f97 --- /dev/null +++ b/static/netbsd/man3/OSSL_IETF_ATTR_SYNTAX_print.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: OSSL_IETF_ATTR_SYNTAX_print.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_IETF_ATTR_SYNTAX_print 3" +.TH OSSL_IETF_ATTR_SYNTAX_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_IETF_ATTR_SYNTAX_print \- OSSL_IETF_ATTR_SYNTAX printing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_IETF_ATTR_SYNTAX_print(BIO *bp, OSSL_IETF_ATTR_SYNTAX *a, +\& int indent); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_IETF_ATTR_SYNTAX_print()\fR prints a human readable version of \fIa\fR to +BIO \fIbp\fR. +Each line of the output is indented by \fIindent\fR spaces. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_IETF_ATTR_SYNTAX_print()\fR return 1 on success or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_STRING_print_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_IETF_ATTR_SYNTAX_print()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_INDICATOR_set_callback.3 b/static/netbsd/man3/OSSL_INDICATOR_set_callback.3 new file mode 100644 index 00000000..deb333b6 --- /dev/null +++ b/static/netbsd/man3/OSSL_INDICATOR_set_callback.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: OSSL_INDICATOR_set_callback.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_INDICATOR_set_callback 3" +.TH OSSL_INDICATOR_set_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_INDICATOR_set_callback, +OSSL_INDICATOR_get_callback \- specify a callback for FIPS indicators +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +typedef int (OSSL_INDICATOR_CALLBACK)(const char *type, const char *desc, + const OSSL_PARAM params[]); +.PP +.Vb 4 +\& void OSSL_INDICATOR_set_callback(OSSL_LIB_CTX *libctx, +\& OSSL_INDICATOR_CALLBACK *cb); +\& void OSSL_INDICATOR_get_callback(OSSL_LIB_CTX *libctx, +\& OSSL_INDICATOR_CALLBACK **cb); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_INDICATOR_set_callback()\fR sets a user callback \fIcb\fR associated with a +\&\fIlibctx\fR that will be called when a non approved FIPS operation is detected. +.PP +The user\*(Aqs callback may be triggered multiple times during an algorithm operation +to indicate different approved mode checks have failed. +.PP +Non approved operations may only occur if the user has deliberately chosen to do +so (either by setting a global FIPS configuration option or via an option in an +algorithm\*(Aqs operation context). +.PP +The user\*(Aqs callback \fBOSSL_INDICATOR_CALLBACK\fR \fItype\fR and \fIdesc\fR +contain the algorithm type and operation that is not approved. +\&\fIparams\fR is not currently used. +.PP +If the user callback returns 0, an error will occur in the caller. This can be +used for testing purposes. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_INDICATOR_get_callback()\fR returns the callback that has been set via +\&\fBOSSL_INDICATOR_set_callback()\fR for the given library context \fIlibctx\fR, or NULL +if no callback is currently set. +.SH EXAMPLES +.IX Header "EXAMPLES" +A simple indicator callback to log non approved FIPS operations +.PP +.Vb 9 +\& static int indicator_cb(const char *type, const char *desc, +\& const OSSL_PARAM params[]) +\& { +\& if (type != NULL && desc != NULL) +\& fprintf(stdout, "%s %s is not approved\en", type, desc); +\&end: +\& /* For Testing purposes you could return 0 here to cause an error */ +\& return 1; +\& } +\& +\& OSSL_INDICATOR_set_callback(libctx, indicator_cb); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +\&\fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_ITEM.3 b/static/netbsd/man3/OSSL_ITEM.3 new file mode 100644 index 00000000..31341d6f --- /dev/null +++ b/static/netbsd/man3/OSSL_ITEM.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: OSSL_ITEM.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_ITEM 3" +.TH OSSL_ITEM 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_ITEM \- OpenSSL Core type for generic itemized data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_item_st OSSL_ITEM; +\& struct ossl_item_st { +\& unsigned int id; +\& void *ptr; +\& }; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This type is a tuple of integer and pointer. +It\*(Aqs a generic type used as a generic descriptor, its exact meaning +being defined by how it\*(Aqs used. +Arrays of this type are passed between the OpenSSL libraries and the +providers, and must be terminated with a tuple where the integer is +zero and the pointer NULL. +.PP +This is currently mainly used for the return value of the provider\*(Aqs error +reason strings array, see "Provider Functions" in \fBprovider\-base\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), \fBprovider\-base\fR\|(7), \fBopenssl\-core.h\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_ITEM\fR was added in OpenSSL 3.0 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_LIB_CTX.3 b/static/netbsd/man3/OSSL_LIB_CTX.3 new file mode 100644 index 00000000..cebc2974 --- /dev/null +++ b/static/netbsd/man3/OSSL_LIB_CTX.3 @@ -0,0 +1,211 @@ +.\" $NetBSD: OSSL_LIB_CTX.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_LIB_CTX 3" +.TH OSSL_LIB_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_LIB_CTX, OSSL_LIB_CTX_get_data, OSSL_LIB_CTX_new, +OSSL_LIB_CTX_new_from_dispatch, OSSL_LIB_CTX_new_child, +OSSL_LIB_CTX_free, OSSL_LIB_CTX_load_config, +OSSL_LIB_CTX_get0_global_default, OSSL_LIB_CTX_set0_default +\&\- OpenSSL library context +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_lib_ctx_st OSSL_LIB_CTX; +\& +\& OSSL_LIB_CTX *OSSL_LIB_CTX_new(void); +\& OSSL_LIB_CTX *OSSL_LIB_CTX_new_from_dispatch(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in); +\& OSSL_LIB_CTX *OSSL_LIB_CTX_new_child(const OSSL_CORE_HANDLE *handle, +\& const OSSL_DISPATCH *in); +\& int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file); +\& void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx); +\& OSSL_LIB_CTX *OSSL_LIB_CTX_get0_global_default(void); +\& OSSL_LIB_CTX *OSSL_LIB_CTX_set0_default(OSSL_LIB_CTX *ctx); +\& void *OSSL_LIB_CTX_get_data(OSSL_LIB_CTX *ctx, int index); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_LIB_CTX\fR is an internal OpenSSL library context type. +Applications may allocate their own, but may also use NULL to use +a default context with functions that take an \fBOSSL_LIB_CTX\fR +argument. +.PP +When a non default library context is in use care should be taken with +multi\-threaded applications to properly clean up thread local resources before +the OSSL_LIB_CTX is freed. +See \fBOPENSSL_thread_stop_ex\fR\|(3) for more information. +.PP +\&\fBOSSL_LIB_CTX_new()\fR creates a new OpenSSL library context. +.PP +\&\fBOSSL_LIB_CTX_new_from_dispatch()\fR creates a new OpenSSL library context +initialised to use callbacks from the OSSL_DISPATCH structure. This is primarily +useful for provider authors. The \fIhandle\fR and dispatch structure arguments +passed should be the same ones as passed to a provider\*(Aqs +OSSL_provider_init function. Some OpenSSL functions, such as +\&\fBBIO_new_from_core_bio\fR\|(3), require the library context to be created in this +way in order to work. +.PP +\&\fBOSSL_LIB_CTX_new_child()\fR is only useful to provider authors and does the same +thing as \fBOSSL_LIB_CTX_new_from_dispatch()\fR except that it additionally links the +new library context to the application library context. The new library context +is a full library context in its own right, but will have all the same providers +available to it that are available in the application library context (without +having to reload them). If the application loads or unloads providers from the +application library context then this will be automatically mirrored in the +child library context. +.PP +In addition providers that are not loaded in the parent library context can be +explicitly loaded into the child library context independently from the parent +library context. Providers loaded independently in this way will not be mirrored +in the parent library context and will not be affected if the parent library +context subsequently loads the same provider. +.PP +A provider may call the function \fBOSSL_PROVIDER_load\fR\|(3) with the child library +context as required. If the provider already exists due to it being mirrored +from the parent library context then it will remain available and its reference +count will be increased. If \fBOSSL_PROVIDER_load\fR\|(3) is called in this way then +\&\fBOSSL_PROVIDER_unload\fR\|(3) should be subsequently called to decrement the +reference count. \fBOSSL_PROVIDER_unload\fR\|(3) must not be called for a provider in +the child library context that did not have an earlier \fBOSSL_PROVIDER_load\fR\|(3) +call for that provider in that child library context. +.PP +In addition to providers, a child library context will also mirror the default +properties (set via \fBEVP_set_default_properties\fR\|(3)) from the parent library +context. If \fBEVP_set_default_properties\fR\|(3) is called directly on a child +library context then the new properties will override anything from the parent +library context and mirroring of the properties will stop. +.PP +When \fBOSSL_LIB_CTX_new_child()\fR is called from within the scope of a provider\*(Aqs +\&\fBOSSL_provider_init\fR function the currently initialising provider is not yet +available in the application\*(Aqs library context and therefore will similarly not +yet be available in the newly constructed child library context. As soon as the +\&\fBOSSL_provider_init\fR function returns then the new provider is available in the +application\*(Aqs library context and will be similarly mirrored in the child +library context. +.PP +\&\fBOSSL_LIB_CTX_load_config()\fR loads a configuration file using the given \fIctx\fR. +This can be used to associate a library context with providers that are loaded +from a configuration. This function must not be called concurrently from +multiple threads on a single \fIctx\fR. +.PP +\&\fBOSSL_LIB_CTX_free()\fR frees the given \fIctx\fR, unless it happens to be the +default OpenSSL library context. If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_LIB_CTX_get0_global_default()\fR returns a concrete (non NULL) reference to +the global default library context. +.PP +\&\fBOSSL_LIB_CTX_set0_default()\fR sets the default OpenSSL library context to be +\&\fIctx\fR in the current thread. The previous default library context is +returned. Care should be taken by the caller to restore the previous +default library context with a subsequent call of this function. If \fIctx\fR is +NULL then no change is made to the default library context, but a pointer to +the current library context is still returned. On a successful call of this +function the returned value will always be a concrete (non NULL) library +context. +.PP +Care should be taken when changing the default library context and starting +async jobs (see \fBASYNC_start_job\fR\|(3)), as the default library context when +the job is started will be used throughout the lifetime of an async job, no +matter how the calling thread makes further default library context changes +in the mean time. This means that the calling thread must not free the +library context that was the default at the start of the async job before +that job has finished. +.PP +\&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation depends +on the index. The index argument refers to a context member which is +to be retrieved. The values for index are all private to OpenSSL currently +and so applications should not typically call this function. +If ctx is NULL then the function operates on the default library context. +\&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation +depends on the index. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_LIB_CTX_new()\fR, \fBOSSL_LIB_CTX_get0_global_default()\fR and +\&\fBOSSL_LIB_CTX_set0_default()\fR return a library context pointer on success, or NULL +on error. +.PP +\&\fBOSSL_LIB_CTX_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBOSSL_LIB_CTX_load_config()\fR returns 1 on success, 0 on error. +.PP +\&\fBOSSL_LIB_CTX_get_data()\fR returns a memory address whose interpretation +depends on the index. +.SH HISTORY +.IX Header "HISTORY" +All of the functions described on this page were added in OpenSSL 3.0. +.PP +\&\fBOSSL_LIB_CTX_get_data()\fR was introduced in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_LIB_CTX_set_conf_diagnostics.3 b/static/netbsd/man3/OSSL_LIB_CTX_set_conf_diagnostics.3 new file mode 100644 index 00000000..694d2623 --- /dev/null +++ b/static/netbsd/man3/OSSL_LIB_CTX_set_conf_diagnostics.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: OSSL_LIB_CTX_set_conf_diagnostics.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_LIB_CTX_set_conf_diagnostics 3" +.TH OSSL_LIB_CTX_set_conf_diagnostics 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_LIB_CTX_set_conf_diagnostics, OSSL_LIB_CTX_get_conf_diagnostics +\&\- Set and get configuration diagnostics +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void OSSL_LIB_CTX_set_conf_diagnostics(OSSL_LIB_CTX *ctx, int value); +\& int OSSL_LIB_CTX_get_conf_diagnostics(OSSL_LIB_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_LIB_CTX_set_conf_diagnostics()\fR sets the value of the configuration +diagnostics flag. If \fIvalue\fR is nonzero subsequent parsing and application +of configuration data can report errors that would otherwise be ignored. In +particular any errors in the ssl configuration module will cause a failure +of \fBSSL_CTX_new\fR\|(3) and \fBSSL_CTX_new_ex\fR\|(3) calls. The configuration +diagnostics flag can be also set when a configuration file is being loaded +into \fBOSSL_LIB_CTX\fR with \fBOSSL_LIB_CTX_load_config\fR\|(3). If the configuration +sets a \fBconfig_diagnostics\fR value as described in \fBconfig\fR\|(5), it will +override the value set by \fBOSSL_LIB_CTX_set_conf_diagnostics()\fR before +loading the configuration file. +.PP +\&\fBOSSL_LIB_CTX_get_conf_diagnostics()\fR returns the current value of the +configuration diagnostics flag. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_LIB_CTX_get_conf_diagnostics()\fR returns 0 if the configuration diagnostics +should not be performed, nonzero otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_new\fR\|(3), \fBOSSL_LIB_CTX_load_config\fR\|(3), \fBconfig\fR\|(5) +.SH HISTORY +.IX Header "HISTORY" +The functions described on this page were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM.3 b/static/netbsd/man3/OSSL_PARAM.3 new file mode 100644 index 00000000..3584e3ab --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM.3 @@ -0,0 +1,393 @@ +.\" $NetBSD: OSSL_PARAM.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM 3" +.TH OSSL_PARAM 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM \- a structure to pass or request object parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_param_st OSSL_PARAM; +\& struct ossl_param_st { +\& const char *key; /* the name of the parameter */ +\& unsigned int data_type; /* declare what kind of content is in data */ +\& void *data; /* value being passed in or out */ +\& size_t data_size; /* data size */ +\& size_t return_size; /* returned size */ +\& }; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_PARAM\fR is a type that allows passing arbitrary data for some +object between two parties that have no or very little shared +knowledge about their respective internal structures for that object. +.PP +A typical usage example could be an application that wants to set some +parameters for an object, or wants to find out some parameters of an +object. +.PP +Arrays of this type can be used for the following purposes: +.IP \(bu 4 +Setting parameters for some object +.Sp +The caller sets up the \fBOSSL_PARAM\fR array and calls some function +(the \fIsetter\fR) that has intimate knowledge about the object that can +take the data from the \fBOSSL_PARAM\fR array and assign them in a +suitable form for the internal structure of the object. +.IP \(bu 4 +Request parameters of some object +.Sp +The caller (the \fIrequester\fR) sets up the \fBOSSL_PARAM\fR array and +calls some function (the \fIresponder\fR) that has intimate knowledge +about the object, which can take the internal data of the object and +copy (possibly convert) that to the memory prepared by the +\&\fIrequester\fR and pointed at with the \fBOSSL_PARAM\fR \fIdata\fR. +.IP \(bu 4 +Request parameter descriptors +.Sp +The caller gets an array of constant \fBOSSL_PARAM\fR, which describe +available parameters and some of their properties; name, data type and +expected data size. +For a detailed description of each field for this use, see the field +descriptions below. +.Sp +The caller may then use the information from this descriptor array to +build up its own \fBOSSL_PARAM\fR array to pass down to a \fIsetter\fR or +\&\fIresponder\fR. +.PP +Normally, the order of the an \fBOSSL_PARAM\fR array is not relevant. +However, if the \fIresponder\fR can handle multiple elements with the +same key, those elements must be handled in the order they are in. +.PP +An \fBOSSL_PARAM\fR array must have a terminating element, where \fIkey\fR +is NULL. The usual full terminating template is: +.PP +.Vb 1 +\& { NULL, 0, NULL, 0, 0 } +.Ve +.PP +This can also be specified using \fBOSSL_PARAM_END\fR\|(3). +.SS "Functional support" +.IX Subsection "Functional support" +Libcrypto offers a limited set of helper functions to handle +\&\fBOSSL_PARAM\fR items and arrays, please see \fBOSSL_PARAM_get_int\fR\|(3). +Developers are free to extend or replace those as they see fit. +.SS "\fBOSSL_PARAM\fP fields" +.IX Subsection "OSSL_PARAM fields" +.IP \fIkey\fR 4 +.IX Item "key" +The identity of the parameter in the form of a string. +.Sp +In an \fBOSSL_PARAM\fR array, an item with this field set to NULL is +considered a terminating item. +.IP \fIdata_type\fR 4 +.IX Item "data_type" +The \fIdata_type\fR is a value that describes the type and organization of +the data. +See "Supported types" below for a description of the types. +.IP \fIdata\fR 4 +.IX Item "data" +.PD 0 +.IP \fIdata_size\fR 4 +.IX Item "data_size" +.PD +\&\fIdata\fR is a pointer to the memory where the parameter data is (when +setting parameters) or shall (when requesting parameters) be stored, +and \fIdata_size\fR is its size in bytes. +The organization of the data depends on the parameter type and flag. +.Sp +The \fIdata_size\fR needs special attention with the parameter type +\&\fBOSSL_PARAM_UTF8_STRING\fR in relation to C strings. When setting +parameters, the size should be set to the length of the string, not +counting the terminating NUL byte. When requesting parameters, the +size should be set to the size of the buffer to be populated, which +should accommodate enough space for a terminating NUL byte. +.Sp +When \fIrequesting parameters\fR, it\*(Aqs acceptable for \fIdata\fR to be NULL. +This can be used by the \fIrequester\fR to figure out dynamically exactly +how much buffer space is needed to store the parameter data. +In this case, \fIdata_size\fR is ignored. +.Sp +When the \fBOSSL_PARAM\fR is used as a parameter descriptor, \fIdata\fR +should be ignored. +If \fIdata_size\fR is zero, it means that an arbitrary data size is +accepted, otherwise it specifies the maximum size allowed. +.IP \fIreturn_size\fR 4 +.IX Item "return_size" +When an array of \fBOSSL_PARAM\fR is used to request data, the +\&\fIresponder\fR must set this field to indicate size of the parameter +data, including padding as the case may be. +In case the \fIdata_size\fR is an unsuitable size for the data, the +\&\fIresponder\fR must still set this field to indicate the minimum data +size required. +(further notes on this in "NOTES" below). +.Sp +When the \fBOSSL_PARAM\fR is used as a parameter descriptor, +\&\fIreturn_size\fR should be ignored. +.PP +\&\fBNOTE:\fR +.PP +The key names and associated types are defined by the entity that +offers these parameters, i.e. names for parameters provided by the +OpenSSL libraries are defined by the libraries, and names for +parameters provided by providers are defined by those providers, +except for the pointer form of strings (see data type descriptions +below). +Entities that want to set or request parameters need to know what +those keys are and of what type, any functionality between those two +entities should remain oblivious and just pass the \fBOSSL_PARAM\fR array +along. +.SS "Supported types" +.IX Subsection "Supported types" +The \fIdata_type\fR field can be one of the following types: +.IP \fBOSSL_PARAM_INTEGER\fR 4 +.IX Item "OSSL_PARAM_INTEGER" +.PD 0 +.IP \fBOSSL_PARAM_UNSIGNED_INTEGER\fR 4 +.IX Item "OSSL_PARAM_UNSIGNED_INTEGER" +.PD +The parameter data is an integer (signed or unsigned) of arbitrary +length, organized in native form, i.e. most significant byte first on +Big\-Endian systems, and least significant byte first on Little\-Endian +systems. +.IP \fBOSSL_PARAM_REAL\fR 4 +.IX Item "OSSL_PARAM_REAL" +The parameter data is a floating point value in native form. +.IP \fBOSSL_PARAM_UTF8_STRING\fR 4 +.IX Item "OSSL_PARAM_UTF8_STRING" +The parameter data is a printable string. +.IP \fBOSSL_PARAM_OCTET_STRING\fR 4 +.IX Item "OSSL_PARAM_OCTET_STRING" +The parameter data is an arbitrary string of bytes. +.IP \fBOSSL_PARAM_UTF8_PTR\fR 4 +.IX Item "OSSL_PARAM_UTF8_PTR" +The parameter data is a pointer to a printable string. +.Sp +The difference between this and \fBOSSL_PARAM_UTF8_STRING\fR is that \fIdata\fR +doesn\*(Aqt point directly at the data, but to a pointer that points to the data. +.Sp +If there is any uncertainty about which to use, \fBOSSL_PARAM_UTF8_STRING\fR is +almost certainly the correct choice. +.Sp +This is used to indicate that constant data is or will be passed, +and there is therefore no need to copy the data that is passed, just +the pointer to it. +.Sp +\&\fIdata_size\fR must be set to the size of the data, not the size of the +pointer to the data. +If this is used in a parameter request, +\&\fIdata_size\fR is not relevant. However, the \fIresponder\fR will set +\&\fIreturn_size\fR to the size of the data. +.Sp +Note that the use of this type is \fBfragile\fR and can only be safely +used for data that remains constant and in a constant location for a +long enough duration (such as the life\-time of the entity that +offers these parameters). +.IP \fBOSSL_PARAM_OCTET_PTR\fR 4 +.IX Item "OSSL_PARAM_OCTET_PTR" +The parameter data is a pointer to an arbitrary string of bytes. +.Sp +The difference between this and \fBOSSL_PARAM_OCTET_STRING\fR is that +\&\fIdata\fR doesn\*(Aqt point directly at the data, but to a pointer that +points to the data. +.Sp +If there is any uncertainty about which to use, \fBOSSL_PARAM_OCTET_STRING\fR is +almost certainly the correct choice. +.Sp +This is used to indicate that constant data is or will be passed, and +there is therefore no need to copy the data that is passed, just the +pointer to it. +.Sp +\&\fIdata_size\fR must be set to the size of the data, not the size of the +pointer to the data. +If this is used in a parameter request, +\&\fIdata_size\fR is not relevant. However, the \fIresponder\fR will set +\&\fIreturn_size\fR to the size of the data. +.Sp +Note that the use of this type is \fBfragile\fR and can only be safely +used for data that remains constant and in a constant location for a +long enough duration (such as the life\-time of the entity that +offers these parameters). +.SH NOTES +.IX Header "NOTES" +Both when setting and requesting parameters, the functions that are +called will have to decide what is and what is not an error. +The recommended behaviour is: +.IP \(bu 4 +Keys that a \fIsetter\fR or \fIresponder\fR doesn\*(Aqt recognise should simply +be ignored. +That in itself isn\*(Aqt an error. +.IP \(bu 4 +If the keys that a called \fIsetter\fR recognises form a consistent +enough set of data, that call should succeed. +.IP \(bu 4 +Apart from the \fIreturn_size\fR, a \fIresponder\fR must never change the fields +of an \fBOSSL_PARAM\fR. +To return a value, it should change the contents of the memory that +\&\fIdata\fR points at. +.IP \(bu 4 +If the data type for a key that it\*(Aqs associated with is incorrect, +the called function may return an error. +.Sp +The called function may also try to convert the data to a suitable +form (for example, it\*(Aqs plausible to pass a large number as an octet +string, so even though a given key is defined as an +\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR, is plausible to pass the value as an +\&\fBOSSL_PARAM_OCTET_STRING\fR), but this is in no way mandatory. +.IP \(bu 4 +If \fIdata\fR for a \fBOSSL_PARAM_OCTET_STRING\fR or a +\&\fBOSSL_PARAM_UTF8_STRING\fR is NULL, the \fIresponder\fR should +set \fIreturn_size\fR to the size of the item to be returned +and return success. Later the responder will be called again +with \fIdata\fR pointing at the place for the value to be put. +.IP \(bu 4 +If a \fIresponder\fR finds that some data sizes are too small for the +requested data, it must set \fIreturn_size\fR for each such +\&\fBOSSL_PARAM\fR item to the minimum required size, and eventually return +an error. +.IP \(bu 4 +For the integer type parameters (\fBOSSL_PARAM_UNSIGNED_INTEGER\fR and +\&\fBOSSL_PARAM_INTEGER\fR), a \fIresponder\fR may choose to return an error +if the \fIdata_size\fR isn\*(Aqt a suitable size (even if \fIdata_size\fR is +bigger than needed). If the \fIresponder\fR finds the size suitable, it +must fill all \fIdata_size\fR bytes and ensure correct padding for the +native endianness, and set \fIreturn_size\fR to the same value as +\&\fIdata_size\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +A couple of examples to just show how \fBOSSL_PARAM\fR arrays could be +set up. +.PP +\fIExample 1\fR +.IX Subsection "Example 1" +.PP +This example is for setting parameters on some object: +.PP +.Vb 1 +\& #include +\& +\& const char *foo = "some string"; +\& size_t foo_l = strlen(foo); +\& const char bar[] = "some other string"; +\& OSSL_PARAM set[] = { +\& { "foo", OSSL_PARAM_UTF8_PTR, &foo, foo_l, 0 }, +\& { "bar", OSSL_PARAM_UTF8_STRING, (void *)&bar, sizeof(bar) \- 1, 0 }, +\& { NULL, 0, NULL, 0, 0 } +\& }; +.Ve +.PP +\fIExample 2\fR +.IX Subsection "Example 2" +.PP +This example is for requesting parameters on some object: +.PP +.Vb 9 +\& const char *foo = NULL; +\& size_t foo_l; +\& char bar[1024]; +\& size_t bar_l; +\& OSSL_PARAM request[] = { +\& { "foo", OSSL_PARAM_UTF8_PTR, &foo, 0 /*irrelevant*/, 0 }, +\& { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 }, +\& { NULL, 0, NULL, 0, 0 } +\& }; +.Ve +.PP +A \fIresponder\fR that receives this array (as \fIparams\fR in this example) +could fill in the parameters like this: +.PP +.Vb 1 +\& /* OSSL_PARAM *params */ +\& +\& int i; +\& +\& for (i = 0; params[i].key != NULL; i++) { +\& if (strcmp(params[i].key, "foo") == 0) { +\& *(char **)params[i].data = "foo value"; +\& params[i].return_size = 9; /* length of "foo value" string */ +\& } else if (strcmp(params[i].key, "bar") == 0) { +\& memcpy(params[i].data, "bar value", 10); +\& params[i].return_size = 9; /* length of "bar value" string */ +\& } +\& /* Ignore stuff we don\*(Aqt know */ +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), \fBOSSL_PARAM_get_int\fR\|(3), \fBOSSL_PARAM_dup\fR\|(3), \fBOSSL_PARAM_construct_utf8_string\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_PARAM\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM_BLD.3 b/static/netbsd/man3/OSSL_PARAM_BLD.3 new file mode 100644 index 00000000..7d4e816f --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM_BLD.3 @@ -0,0 +1,266 @@ +.\" $NetBSD: OSSL_PARAM_BLD.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM_BLD 3" +.TH OSSL_PARAM_BLD 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param, +OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int, +OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long, +OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32, +OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64, +OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t, +OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double, +OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad, +OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr, +OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr +\&\- functions to assist in the creation of OSSL_PARAM arrays +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct OSSL_PARAM_BLD; +\& +\& OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void); +\& OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld); +\& void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld); +\& +\& int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val); +\& +\& int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key, +\& const BIGNUM *bn); +\& int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key, +\& const BIGNUM *bn, size_t sz); +\& +\& int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key, +\& const char *buf, size_t bsize); +\& int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key, +\& char *buf, size_t bsize); +\& int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key, +\& const void *buf, size_t bsize); +\& int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key, +\& void *buf, size_t bsize); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A collection of utility functions that simplify the creation of OSSL_PARAM +arrays. The \fR\f(BITYPE\fR\fB\fR names are as per \fBOSSL_PARAM_int\fR\|(3). +.PP +\&\fBOSSL_PARAM_BLD_new()\fR allocates and initialises a new OSSL_PARAM_BLD structure +so that values can be added. +Any existing values are cleared. +.PP +\&\fBOSSL_PARAM_BLD_free()\fR deallocates the memory allocates by \fBOSSL_PARAM_BLD_new()\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_PARAM_BLD_to_param()\fR converts a built up OSSL_PARAM_BLD structure +\&\fIbld\fR into an allocated OSSL_PARAM array. +The OSSL_PARAM array and all associated storage must be freed by calling +\&\fBOSSL_PARAM_free()\fR with the functions return value. +\&\fBOSSL_PARAM_BLD_free()\fR can safely be called any time after this function is. +.PP +\&\fBOSSL_PARAM_BLD_push_\fR\f(BITYPE\fR() are a series of functions which will create +OSSL_PARAM objects of the specified size and correct type for the \fIval\fR +argument. +\&\fIval\fR is stored by value and an expression or auto variable can be used. +.PP +When \fR\f(BITYPE\fR\fB\fR denotes an integer type, signed integer types will normally +get the OSSL_PARAM type \fBOSSL_PARAM_INTEGER\fR params. +When \fB\fR\f(BITYPE\fR\fB\fR denotes an unsigned integer type will get the OSSL_PARAM type +\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR. +.PP +\&\fBOSSL_PARAM_BLD_push_BN()\fR is a function that will create an OSSL_PARAM object +that holds the specified BIGNUM \fIbn\fR. +When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes +\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR. +When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR. +If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation +will also be securely allocated. +The \fIbn\fR argument is stored by reference and the underlying BIGNUM object +must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called. +.PP +\&\fBOSSL_PARAM_BLD_push_BN_pad()\fR is a function that will create an OSSL_PARAM object +that holds the specified BIGNUM \fIbn\fR. +The object will be padded to occupy exactly \fIsz\fR bytes, if insufficient space +is specified an error results. +When the \fIbn\fR is zero or positive, its OSSL_PARAM type becomes +\&\fBOSSL_PARAM_UNSIGNED_INTEGER\fR. +When the \fIbn\fR is negative, its OSSL_PARAM type becomes \fBOSSL_PARAM_INTEGER\fR. +If \fIbn\fR is marked as being securely allocated, its OSSL_PARAM representation +will also be securely allocated. +The \fIbn\fR argument is stored by reference and the underlying BIGNUM object +must exist until after \fBOSSL_PARAM_BLD_to_param()\fR has been called. +.PP +\&\fBOSSL_PARAM_BLD_push_utf8_string()\fR is a function that will create an OSSL_PARAM +object that references the UTF8 string specified by \fIbuf\fR. +The length of the string \fIbsize\fR should not include the terminating NUL byte. +If it is zero then it will be calculated. +The string that \fIbuf\fR points to is stored by reference and must remain in +scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called. +.PP +\&\fBOSSL_PARAM_BLD_push_octet_string()\fR is a function that will create an OSSL_PARAM +object that references the octet string specified by \fIbuf\fR and . +The memory that \fIbuf\fR points to is stored by reference and must remain in +scope until after \fBOSSL_PARAM_BLD_to_param()\fR has been called. +.PP +\&\fBOSSL_PARAM_BLD_push_utf8_ptr()\fR is a function that will create an OSSL_PARAM +object that references the UTF8 string specified by \fIbuf\fR. +The length of the string \fIbsize\fR should not include the terminating NUL byte. +If it is zero then it will be calculated. +The string \fIbuf\fR points to is stored by reference and must remain in +scope until the OSSL_PARAM array is freed. +.PP +\&\fBOSSL_PARAM_BLD_push_octet_ptr()\fR is a function that will create an OSSL_PARAM +object that references the octet string specified by \fIbuf\fR. +The memory \fIbuf\fR points to is stored by reference and must remain in +scope until the OSSL_PARAM array is freed. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_PARAM_BLD_new()\fR returns the allocated OSSL_PARAM_BLD structure, or NULL +on error. +.PP +\&\fBOSSL_PARAM_BLD_to_param()\fR returns the allocated OSSL_PARAM array, or NULL +on error. +.PP +All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0 +on error. +.SH NOTES +.IX Header "NOTES" +\&\fBOSSL_PARAM_BLD_push_BN()\fR and \fBOSSL_PARAM_BLD_push_BN_pad()\fR only +support nonnegative \fBBIGNUM\fRs. They return an error on negative +\&\fBBIGNUM\fRs. +To pass signed \fBBIGNUM\fRs, use \fBOSSL_PARAM_BLD_push_signed_BN()\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +Both examples creating an OSSL_PARAM array that contains an RSA key. +For both, the predefined key variables are: +.PP +.Vb 6 +\& BIGNUM *n; /* modulus */ +\& unsigned int e; /* public exponent */ +\& BIGNUM *d; /* private exponent */ +\& BIGNUM *p, *q; /* first two prime factors */ +\& BIGNUM *dmp1, *dmq1; /* first two CRT exponents */ +\& BIGNUM *iqmp; /* first CRT coefficient */ +.Ve +.SS "Example 1" +.IX Subsection "Example 1" +This example shows how to create an OSSL_PARAM array that contains an RSA +private key. +.PP +.Vb 2 +\& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); +\& OSSL_PARAM *params = NULL; +\& +\& if (bld == NULL +\& || !OSSL_PARAM_BLD_push_BN(bld, "n", n) +\& || !OSSL_PARAM_BLD_push_uint(bld, "e", e) +\& || !OSSL_PARAM_BLD_push_BN(bld, "d", d) +\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor1", p) +\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-factor2", q) +\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent1", dmp1) +\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-exponent2", dmq1) +\& || !OSSL_PARAM_BLD_push_BN(bld, "rsa\-coefficient1", iqmp) +\& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) +\& goto err; +\& OSSL_PARAM_BLD_free(bld); +\& /* Use params */ +\& ... +\& OSSL_PARAM_free(params); +.Ve +.SS "Example 2" +.IX Subsection "Example 2" +This example shows how to create an OSSL_PARAM array that contains an RSA +public key. +.PP +.Vb 2 +\& OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new(); +\& OSSL_PARAM *params = NULL; +\& +\& if (nld == NULL +\& || !OSSL_PARAM_BLD_push_BN(bld, "n", n) +\& || !OSSL_PARAM_BLD_push_uint(bld, "e", e) +\& || (params = OSSL_PARAM_BLD_to_param(bld)) == NULL) +\& goto err; +\& OSSL_PARAM_BLD_free(bld); +\& /* Use params */ +\& ... +\& OSSL_PARAM_free(params); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PARAM_int\fR\|(3), \fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were all added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM_allocate_from_text.3 b/static/netbsd/man3/OSSL_PARAM_allocate_from_text.3 new file mode 100644 index 00000000..8be2b69a --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM_allocate_from_text.3 @@ -0,0 +1,257 @@ +.\" $NetBSD: OSSL_PARAM_allocate_from_text.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM_allocate_from_text 3" +.TH OSSL_PARAM_allocate_from_text 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM_allocate_from_text +\&\- OSSL_PARAM construction utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to, +\& const OSSL_PARAM *paramdefs, +\& const char *key, const char *value, +\& size_t value_n, +\& int *found); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +With OpenSSL before version 3.0, parameters were passed down to or +retrieved from algorithm implementations via control functions. +Some of these control functions existed in variants that took string +parameters, for example \fBEVP_PKEY_CTX_ctrl_str\fR\|(3). +.PP +OpenSSL 3.0 introduces a new mechanism to do the same thing with an +array of parameters that contain name, value, value type and value +size (see \fBOSSL_PARAM\fR\|(3) for more information). +.PP +\&\fBOSSL_PARAM_allocate_from_text()\fR uses \fIkey\fR to look up an item in +\&\fIparamdefs\fR. If an item was found, it converts \fIvalue\fR to something +suitable for that item\*(Aqs \fIdata_type\fR, and stores the result in +\&\fIto\->data\fR as well as its size in \fIto\->data_size\fR. +\&\fIto\->key\fR and \fIto\->data_type\fR are assigned the corresponding +values from the item that was found, and \fIto\->return_size\fR is set +to zero. +.PP +\&\fIto\->data\fR is always allocated using \fBOPENSSL_zalloc\fR\|(3) and +needs to be freed by the caller when it\*(Aqs not useful any more, using +\&\fBOPENSSL_free\fR\|(3). +.PP +If \fIfound\fR is not NULL, \fI*found\fR is set to 1 if \fIkey\fR could be +located in \fIparamdefs\fR, and to 0 otherwise. +.SS "The use of \fIkey\fP and \fIvalue\fP in detail" +.IX Subsection "The use of key and value in detail" +\&\fBOSSL_PARAM_allocate_from_text()\fR takes note if \fIkey\fR starts with +"hex", and will only use the rest of \fIkey\fR to look up an item in +\&\fIparamdefs\fR in that case. As an example, if \fIkey\fR is "hexid", "id" +will be looked up in \fIparamdefs\fR. +.PP +When an item in \fIparamdefs\fR has been found, \fIvalue\fR is converted +depending on that item\*(Aqs \fIdata_type\fR, as follows: +.IP "\fBOSSL_PARAM_INTEGER\fR and \fBOSSL_PARAM_UNSIGNED_INTEGER\fR" 4 +.IX Item "OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER" +If \fIkey\fR didn\*(Aqt start with "hex", \fIvalue\fR is assumed to contain +\&\fIvalue_n\fR decimal characters, which are decoded, and the resulting +bytes become the number stored in the \fIto\->data\fR storage. +.Sp +If \fIvalue\fR starts with "0x", it is assumed to contain \fIvalue_n\fR +hexadecimal characters. +.Sp +If \fIkey\fR started with "hex", \fIvalue\fR is assumed to contain +\&\fIvalue_n\fR hexadecimal characters without the "0x" prefix. +.Sp +If \fIvalue\fR contains characters that couldn\*(Aqt be decoded as +hexadecimal or decimal characters, \fBOSSL_PARAM_allocate_from_text()\fR +considers that an error. +.IP \fBOSSL_PARAM_UTF8_STRING\fR 4 +.IX Item "OSSL_PARAM_UTF8_STRING" +If \fIkey\fR started with "hex", \fBOSSL_PARAM_allocate_from_text()\fR +considers that an error. +.Sp +Otherwise, \fIvalue\fR is considered a C string and is copied to the +\&\fIto\->data\fR storage. +On systems where the native character encoding is EBCDIC, the bytes in +\&\fIto\->data\fR are converted to ASCII. +.IP \fBOSSL_PARAM_OCTET_STRING\fR 4 +.IX Item "OSSL_PARAM_OCTET_STRING" +If \fIkey\fR started with "hex", \fIvalue\fR is assumed to contain +\&\fIvalue_n\fR hexadecimal characters, which are decoded, and the +resulting bytes are stored in the \fIto\->data\fR storage. +If \fIvalue\fR contains characters that couldn\*(Aqt be decoded as +hexadecimal or decimal characters, \fBOSSL_PARAM_allocate_from_text()\fR +considers that an error. +.Sp +If \fIkey\fR didn\*(Aqt start with "hex", \fIvalue_n\fR bytes from \fIvalue\fR are +copied to the \fIto\->data\fR storage. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_PARAM_allocate_from_text()\fR returns 1 if \fIkey\fR was found in +\&\fIparamdefs\fR and there was no other failure, otherwise 0. +.SH NOTES +.IX Header "NOTES" +The parameter descriptor array comes from functions dedicated to +return them. +The following \fBOSSL_PARAM\fR\|(3) attributes are used: +.IP \fIkey\fR 4 +.IX Item "key" +.PD 0 +.IP \fIdata_type\fR 4 +.IX Item "data_type" +.IP \fIdata_size\fR 4 +.IX Item "data_size" +.PD +.PP +All other attributes are ignored. +.PP +The \fIdata_size\fR attribute can be zero, meaning that the parameter it +describes expects arbitrary length data. +.SH EXAMPLES +.IX Header "EXAMPLES" +Code that looked like this: +.PP +.Vb 4 +\& int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value) +\& { +\& int rv; +\& char *stmp, *vtmp = NULL; +\& +\& stmp = OPENSSL_strdup(value); +\& if (stmp == NULL) +\& return \-1; +\& vtmp = strchr(stmp, \*(Aq:\*(Aq); +\& if (vtmp != NULL) +\& *vtmp++ = \*(Aq\e0\*(Aq; +\& rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp); +\& OPENSSL_free(stmp); +\& return rv; +\& } +\& +\& ... +\& +\& +\& for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) { +\& char *macopt = sk_OPENSSL_STRING_value(macopts, i); +\& +\& if (pkey_ctrl_string(mac_ctx, macopt) <= 0) { +\& BIO_printf(bio_err, +\& "MAC parameter error \e"%s\e"\en", macopt); +\& ERR_print_errors(bio_err); +\& goto mac_end; +\& } +\& } +.Ve +.PP +Can be written like this instead: +.PP +.Vb 6 +\& OSSL_PARAM *params = +\& OPENSSL_zalloc(sizeof(*params) +\& * (sk_OPENSSL_STRING_num(opts) + 1)); +\& const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac); +\& size_t params_n; +\& char *opt = ""; +\& +\& for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts); +\& params_n++) { +\& char *stmp, *vtmp = NULL; +\& +\& opt = sk_OPENSSL_STRING_value(opts, (int)params_n); +\& if ((stmp = OPENSSL_strdup(opt)) == NULL +\& || (vtmp = strchr(stmp, \*(Aq:\*(Aq)) == NULL) +\& goto err; +\& +\& *vtmp++ = \*(Aq\e0\*(Aq; +\& if (!OSSL_PARAM_allocate_from_text(¶ms[params_n], +\& paramdefs, stmp, +\& vtmp, strlen(vtmp), NULL)) +\& goto err; +\& } +\& params[params_n] = OSSL_PARAM_construct_end(); +\& if (!EVP_MAC_CTX_set_params(ctx, params)) +\& goto err; +\& while (params_n\-\- > 0) +\& OPENSSL_free(params[params_n].data); +\& OPENSSL_free(params); +\& /* ... */ +\& return; +\& +\& err: +\& BIO_printf(bio_err, "MAC parameter error \*(Aq%s\*(Aq\en", opt); +\& ERR_print_errors(bio_err); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_int\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM_dup.3 b/static/netbsd/man3/OSSL_PARAM_dup.3 new file mode 100644 index 00000000..20860519 --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM_dup.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: OSSL_PARAM_dup.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM_dup 3" +.TH OSSL_PARAM_dup 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM_dup, OSSL_PARAM_merge, OSSL_PARAM_free +\&\- OSSL_PARAM array copy functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_PARAM *OSSL_PARAM_dup(const OSSL_PARAM *params); +\& OSSL_PARAM *OSSL_PARAM_merge(const OSSL_PARAM *params, const OSSL_PARAM *params1); +\& void OSSL_PARAM_free(OSSL_PARAM *params); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Algorithm parameters can be exported/imported from/to providers using arrays of +\&\fBOSSL_PARAM\fR\|(3). The following utility functions allow the parameters to be +duplicated and merged with other \fBOSSL_PARAM\fR\|(3) to assist in this process. +.PP +\&\fBOSSL_PARAM_dup()\fR duplicates the parameter array \fIparams\fR. This function does a +deep copy of the data. +.PP +\&\fBOSSL_PARAM_merge()\fR merges the parameter arrays \fIparams\fR and \fIparams1\fR into a +new parameter array. If \fIparams\fR and \fIparams1\fR contain values with the same +\&\*(Aqkey\*(Aq then the value from \fIparams1\fR will replace the \fIparam\fR value. This +function does a shallow copy of the parameters. Either \fIparams\fR or \fIparams1\fR +may be NULL. The behaviour of the merge is unpredictable if \fIparams\fR and +\&\fIparams1\fR contain the same key, and there are multiple entries within either +array that have the same key. +.PP +\&\fBOSSL_PARAM_free()\fR frees the parameter array \fIparams\fR that was created using +\&\fBOSSL_PARAM_dup()\fR, \fBOSSL_PARAM_merge()\fR or \fBOSSL_PARAM_BLD_to_param()\fR. +If the argument to \fBOSSL_PARAM_free()\fR is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions \fBOSSL_PARAM_dup()\fR and \fBOSSL_PARAM_merge()\fR return a newly allocated +\&\fBOSSL_PARAM\fR\|(3) array, or NULL if there was an error. If both parameters are NULL + then NULL is returned. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_PARAM\fR\|(3), \fBOSSL_PARAM_BLD\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM_int.3 b/static/netbsd/man3/OSSL_PARAM_int.3 new file mode 100644 index 00000000..ea756188 --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM_int.3 @@ -0,0 +1,470 @@ +.\" $NetBSD: OSSL_PARAM_int.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM_int 3" +.TH OSSL_PARAM_int 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, +OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, +OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, +OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, +OSSL_PARAM_octet_ptr, +OSSL_PARAM_END, OSSL_PARAM_DEFN, +OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, +OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, +OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, +OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint, +OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, +OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN, +OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, +OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, +OSSL_PARAM_construct_end, +OSSL_PARAM_locate, OSSL_PARAM_locate_const, +OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32, +OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, +OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, +OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, +OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string, +OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr, +OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr, +OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, +OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, +OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, +OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, +OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string, +OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr, +OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified +\&\- OSSL_PARAM helpers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* +\& * TYPE in function names is one of: +\& * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong +\& * Corresponding TYPE in function arguments is one of: +\& * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t, +\& * uint64_t, unsigned long +\& */ +\& +\& #define OSSL_PARAM_TYPE(key, address) +\& #define OSSL_PARAM_BN(key, address, size) +\& #define OSSL_PARAM_utf8_string(key, address, size) +\& #define OSSL_PARAM_octet_string(key, address, size) +\& #define OSSL_PARAM_utf8_ptr(key, address, size) +\& #define OSSL_PARAM_octet_ptr(key, address, size) +\& #define OSSL_PARAM_END +\& +\& #define OSSL_PARAM_UNMODIFIED +\& +\& #define OSSL_PARAM_DEFN(key, type, addr, sz) \e +\& { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED } +\& +\& OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf); +\& OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, +\& size_t bsize); +\& OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, +\& size_t bsize); +\& OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, +\& size_t bsize); +\& OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, +\& size_t bsize); +\& OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, +\& size_t bsize); +\& OSSL_PARAM OSSL_PARAM_construct_end(void); +\& +\& OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); +\& const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, +\& const char *key); +\& +\& int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val); +\& int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val); +\& +\& int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val); +\& int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val); +\& +\& int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, +\& size_t max_len); +\& int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val); +\& +\& int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, +\& size_t max_len, size_t *used_len); +\& int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len); +\& +\& int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val); +\& int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val); +\& +\& int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val, +\& size_t *used_len); +\& int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val, +\& size_t used_len); +\& +\& int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val); +\& int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val, +\& size_t *used_len); +\& +\& int OSSL_PARAM_modified(const OSSL_PARAM *param); +\& void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A collection of utility functions that simplify and add type safety to the +\&\fBOSSL_PARAM\fR\|(3) arrays. The following \fR\f(BITYPE\fR\fB\fR names are supported: +.IP \(bu 2 +double +.IP \(bu 2 +int +.IP \(bu 2 +int32 (int32_t) +.IP \(bu 2 +int64 (int64_t) +.IP \(bu 2 +long int (long) +.IP \(bu 2 +time_t +.IP \(bu 2 +size_t +.IP \(bu 2 +uint32 (uint32_t) +.IP \(bu 2 +uint64 (uint64_t) +.IP \(bu 2 +unsigned int (uint) +.IP \(bu 2 +unsigned long int (ulong) +.PP +\&\fBOSSL_PARAM_TYPE()\fR are a series of macros designed to assist initialising an +array of \fBOSSL_PARAM\fR\|(3) structures. +Each of these macros defines a parameter of the specified \fR\f(BITYPE\fR\fB\fR with the +provided \fIkey\fR and parameter variable \fIaddress\fR. +.PP +\&\fBOSSL_PARAM_utf8_string()\fR, \fBOSSL_PARAM_octet_string()\fR, \fBOSSL_PARAM_utf8_ptr()\fR, +\&\fBOSSL_PARAM_octet_ptr()\fR, \fBOSSL_PARAM_BN()\fR are macros that provide support +for defining UTF8 strings, OCTET strings and big numbers. +A parameter with name \fIkey\fR is defined. +The storage for this parameter is at \fIaddress\fR and is of \fIsize\fR bytes. +.PP +OSSL_PARAM_END provides an end of parameter list marker. +This should terminate all \fBOSSL_PARAM\fR\|(3) arrays. +.PP +The \fBOSSL_PARAM_DEFN()\fR macro provides the ability to construct a single +\&\fBOSSL_PARAM\fR\|(3) (typically used in the construction of \fBOSSL_PARAM\fR arrays). The +\&\fIkey\fR, \fItype\fR, \fIaddr\fR and \fIsz\fR arguments correspond to the \fIkey\fR, +\&\fIdata_type\fR, \fIdata\fR and \fIdata_size\fR fields of the \fBOSSL_PARAM\fR\|(3) structure as +described on the \fBOSSL_PARAM\fR\|(3) page. +.PP +\&\fBOSSL_PARAM_construct_TYPE()\fR are a series of functions that create \fBOSSL_PARAM\fR\|(3) +records dynamically. +A parameter with name \fIkey\fR is created. +The parameter will use storage pointed to by \fIbuf\fR and return size of \fIret\fR. +.PP +\&\fBOSSL_PARAM_construct_BN()\fR is a function that constructs a large integer +\&\fBOSSL_PARAM\fR\|(3) structure. +A parameter with name \fIkey\fR, storage \fIbuf\fR, size \fIbsize\fR and return +size \fIrsize\fR is created. +.PP +\&\fBOSSL_PARAM_construct_utf8_string()\fR is a function that constructs a UTF8 +string \fBOSSL_PARAM\fR\|(3) structure. +A parameter with name \fIkey\fR, storage \fIbuf\fR and size \fIbsize\fR is created. +If \fIbsize\fR is zero, the string length is determined using \fBstrlen\fR\|(3). +Generally pass zero for \fIbsize\fR instead of calling \fBstrlen\fR\|(3) yourself. +.PP +\&\fBOSSL_PARAM_construct_octet_string()\fR is a function that constructs an OCTET +string \fBOSSL_PARAM\fR\|(3) structure. +A parameter with name \fIkey\fR, storage \fIbuf\fR and size \fIbsize\fR is created. +.PP +\&\fBOSSL_PARAM_construct_utf8_ptr()\fR is a function that constructs a UTF8 string +pointer \fBOSSL_PARAM\fR\|(3) structure. +A parameter with name \fIkey\fR, storage pointer \fI*buf\fR and size \fIbsize\fR +is created. +.PP +\&\fBOSSL_PARAM_construct_octet_ptr()\fR is a function that constructs an OCTET string +pointer \fBOSSL_PARAM\fR\|(3) structure. +A parameter with name \fIkey\fR, storage pointer \fI*buf\fR and size \fIbsize\fR +is created. +.PP +\&\fBOSSL_PARAM_construct_end()\fR is a function that constructs the terminating +\&\fBOSSL_PARAM\fR\|(3) structure. +.PP +\&\fBOSSL_PARAM_locate()\fR is a function that searches an \fIarray\fR of parameters for +the one matching the \fIkey\fR name. +.PP +\&\fBOSSL_PARAM_locate_const()\fR behaves exactly like \fBOSSL_PARAM_locate()\fR except for +the presence of \fIconst\fR for the \fIarray\fR argument and its return value. +.PP +\&\fBOSSL_PARAM_get_TYPE()\fR retrieves a value of type \fR\f(BITYPE\fR\fB\fR from the parameter +\&\fIp\fR. +The value is copied to the address \fIval\fR. +Type coercion takes place as discussed in the NOTES section. +.PP +\&\fBOSSL_PARAM_set_TYPE()\fR stores a value \fIval\fR of type \fR\f(BITYPE\fR\fB\fR into the +parameter \fIp\fR. +If the parameter\*(Aqs \fIdata\fR field is NULL, then only its \fIreturn_size\fR field +will be assigned the size the parameter\*(Aqs \fIdata\fR buffer should have. +Type coercion takes place as discussed in the NOTES section. +.PP +\&\fBOSSL_PARAM_get_BN()\fR retrieves a BIGNUM from the parameter pointed to by \fIp\fR. +The BIGNUM referenced by \fIval\fR is updated and is allocated if \fI*val\fR is +NULL. +.PP +\&\fBOSSL_PARAM_set_BN()\fR stores the BIGNUM \fIval\fR into the parameter \fIp\fR. +If the parameter\*(Aqs \fIdata\fR field is NULL, then only its \fIreturn_size\fR field +will be assigned the size the parameter\*(Aqs \fIdata\fR buffer should have. +.PP +\&\fBOSSL_PARAM_get_utf8_string()\fR retrieves a UTF8 string from the parameter +pointed to by \fIp\fR. +The string is stored into \fI*val\fR with a size limit of \fImax_len\fR, +which must be large enough to accommodate a terminating NUL byte, +otherwise this function will fail. +If \fI*val\fR is NULL, memory is allocated for the string (including the +terminating NUL byte) and \fImax_len\fR is ignored. +If memory is allocated by this function, it must be freed by the caller. +.PP +\&\fBOSSL_PARAM_set_utf8_string()\fR sets a UTF8 string from the parameter pointed to +by \fIp\fR to the value referenced by \fIval\fR. +If the parameter\*(Aqs \fIdata\fR field isn\*(Aqt NULL, its \fIdata_size\fR must indicate +that the buffer is large enough to accommodate the string that \fIval\fR points at, +not including the terminating NUL byte, or this function will fail. +A terminating NUL byte is added only if the parameter\*(Aqs \fIdata_size\fR indicates +the buffer is longer than the string length, otherwise the string will not be +NUL terminated. +If the parameter\*(Aqs \fIdata\fR field is NULL, then only its \fIreturn_size\fR field +will be assigned the minimum size the parameter\*(Aqs \fIdata\fR buffer should have +to accommodate the string, not including a terminating NUL byte. +.PP +\&\fBOSSL_PARAM_get_octet_string()\fR retrieves an OCTET string from the parameter +pointed to by \fIp\fR. +The OCTETs are either stored into \fI*val\fR with a length limit of \fImax_len\fR or, +in the case when \fI*val\fR is NULL, memory is allocated and +\&\fImax_len\fR is ignored. \fI*used_len\fR is populated with the number of OCTETs +stored. If \fIval\fR is NULL then the OCTETS are not stored, but \fI*used_len\fR is +still populated. +If memory is allocated by this function, it must be freed by the caller. +.PP +\&\fBOSSL_PARAM_set_octet_string()\fR sets an OCTET string from the parameter +pointed to by \fIp\fR to the value referenced by \fIval\fR. +If the parameter\*(Aqs \fIdata\fR field is NULL, then only its \fIreturn_size\fR field +will be assigned the size the parameter\*(Aqs \fIdata\fR buffer should have. +.PP +\&\fBOSSL_PARAM_get_utf8_ptr()\fR retrieves the UTF8 string pointer from the parameter +referenced by \fIp\fR and stores it in \fI*val\fR. +.PP +\&\fBOSSL_PARAM_set_utf8_ptr()\fR sets the UTF8 string pointer in the parameter +referenced by \fIp\fR to the values \fIval\fR. +.PP +\&\fBOSSL_PARAM_get_octet_ptr()\fR retrieves the OCTET string pointer from the parameter +referenced by \fIp\fR and stores it in \fI*val\fR. +The length of the OCTET string is stored in \fI*used_len\fR. +.PP +\&\fBOSSL_PARAM_set_octet_ptr()\fR sets the OCTET string pointer in the parameter +referenced by \fIp\fR to the values \fIval\fR. +The length of the OCTET string is provided by \fIused_len\fR. +.PP +\&\fBOSSL_PARAM_get_utf8_string_ptr()\fR retrieves the pointer to a UTF8 string from +the parameter pointed to by \fIp\fR, and stores that pointer in \fI*val\fR. +This is different from \fBOSSL_PARAM_get_utf8_string()\fR, which copies the +string. +.PP +\&\fBOSSL_PARAM_get_octet_string_ptr()\fR retrieves the pointer to a octet string +from the parameter pointed to by \fIp\fR, and stores that pointer in \fI*val\fR, +along with the string\*(Aqs length in \fI*used_len\fR. +This is different from \fBOSSL_PARAM_get_octet_string()\fR, which copies the +string. +.PP +The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set. On +creation, via either the macros or construct calls, the \fIreturn_size\fR field +is set to this. If the parameter is set using the calls defined herein, the +\&\fIreturn_size\fR field is changed. +.PP +\&\fBOSSL_PARAM_modified()\fR queries if the parameter \fIparam\fR has been set or not +using the calls defined herein. +.PP +\&\fBOSSL_PARAM_set_all_unmodified()\fR resets the unused indicator for all parameters +in the array \fIparams\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_PARAM_construct_TYPE()\fR, \fBOSSL_PARAM_construct_BN()\fR, +\&\fBOSSL_PARAM_construct_utf8_string()\fR, \fBOSSL_PARAM_construct_octet_string()\fR, +\&\fBOSSL_PARAM_construct_utf8_ptr()\fR and \fBOSSL_PARAM_construct_octet_ptr()\fR +return a populated \fBOSSL_PARAM\fR\|(3) structure. +.PP +\&\fBOSSL_PARAM_locate()\fR and \fBOSSL_PARAM_locate_const()\fR return a pointer to +the matching \fBOSSL_PARAM\fR\|(3) object. They return NULL on error or when +no object matching \fIkey\fR exists in the \fIarray\fR. +.PP +\&\fBOSSL_PARAM_modified()\fR returns 1 if the parameter was set and 0 otherwise. +.PP +All other functions return 1 on success and 0 on failure. +.SH NOTES +.IX Header "NOTES" +Native types will be converted as required only if the value is exactly +representable by the target type or parameter. +Apart from that, the functions must be used appropriately for the +expected type of the parameter. +.PP +\&\fBOSSL_PARAM_get_BN()\fR and \fBOSSL_PARAM_set_BN()\fR only support nonnegative +\&\fBBIGNUM\fRs when the desired data type is \fBOSSL_PARAM_UNSIGNED_INTEGER\fR. +\&\fBOSSL_PARAM_construct_BN()\fR currently constructs an \fBOSSL_PARAM\fR\|(3) structure +with the data type \fBOSSL_PARAM_UNSIGNED_INTEGER\fR. +.PP +For \fBOSSL_PARAM_construct_utf8_ptr()\fR and \fBOSSL_PARAM_consstruct_octet_ptr()\fR, +\&\fIbsize\fR is not relevant if the purpose is to send the \fBOSSL_PARAM\fR\|(3) array +to a \fIresponder\fR, i.e. to get parameter data back. +In that case, \fIbsize\fR can safely be given zero. +See "DESCRIPTION" in \fBOSSL_PARAM\fR\|(3) for further information on the +possible purposes. +.SH EXAMPLES +.IX Header "EXAMPLES" +Reusing the examples from \fBOSSL_PARAM\fR\|(3) to just show how +\&\fBOSSL_PARAM\fR\|(3) arrays can be handled using the macros and functions +defined herein. +.SS "Example 1" +.IX Subsection "Example 1" +This example is for setting parameters on some object: +.PP +.Vb 1 +\& #include +\& +\& const char *foo = "some string"; +\& size_t foo_l = strlen(foo); +\& const char bar[] = "some other string"; +\& const OSSL_PARAM set[] = { +\& OSSL_PARAM_utf8_ptr("foo", &foo, foo_l), +\& OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) \- 1), +\& OSSL_PARAM_END +\& }; +.Ve +.SS "Example 2" +.IX Subsection "Example 2" +This example is for requesting parameters on some object, and also +demonstrates that the requester isn\*(Aqt obligated to request all +available parameters: +.PP +.Vb 7 +\& const char *foo = NULL; +\& char bar[1024]; +\& OSSL_PARAM request[] = { +\& OSSL_PARAM_utf8_ptr("foo", &foo, 0), +\& OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), +\& OSSL_PARAM_END +\& }; +.Ve +.PP +A \fIresponder\fR that receives this array (as \f(CW\*(C`params\*(C'\fR in this example) +could fill in the parameters like this: +.PP +.Vb 1 +\& /* OSSL_PARAM *params */ +\& +\& OSSL_PARAM *p; +\& +\& if ((p = OSSL_PARAM_locate(params, "foo")) != NULL) +\& OSSL_PARAM_set_utf8_ptr(p, "foo value"); +\& if ((p = OSSL_PARAM_locate(params, "bar")) != NULL) +\& OSSL_PARAM_set_utf8_string(p, "bar value"); +\& if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) +\& OSSL_PARAM_set_utf8_ptr(p, "cookie value"); +.Ve +.SS "Example 3" +.IX Subsection "Example 3" +This example shows a special case where +\&\fI\-Wincompatible\-pointer\-types\-discards\-qualifiers\fR may be set during +compilation. The value for \fIbuf\fR cannot be a \fIconst char *\fR type string. An +alternative in this case would be to use \fBOSSL_PARAM\fR macro abbreviated calls +rather than the specific callers which allows you to define the sha1 argument +as a standard character array (\fIchar[]\fR). +.PP +For example, this code: +.PP +.Vb 3 +\& OSSL_PARAM params[2]; +\& params[0] = OSSL_PARAM_construct_utf8_string("digest", "SHA1", 0); +\& params[1] = OSSL_PARAM_construct_end(); +.Ve +.PP +Can be made compatible with the following version: +.PP +.Vb 2 +\& char sha1[] = "SHA1"; /* sha1 is defined as char[] in this case */ +\& OSSL_PARAM params[2]; +\& +\& params[0] = OSSL_PARAM_construct_utf8_string("digest", sha1, 0); +\& params[1] = OSSL_PARAM_construct_end(); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), \fBOSSL_PARAM\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These APIs were introduced in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PARAM_print_to_bio.3 b/static/netbsd/man3/OSSL_PARAM_print_to_bio.3 new file mode 100644 index 00000000..1549c6cf --- /dev/null +++ b/static/netbsd/man3/OSSL_PARAM_print_to_bio.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: OSSL_PARAM_print_to_bio.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PARAM_print_to_bio 3" +.TH OSSL_PARAM_print_to_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PARAM_print_to_bio +\&\- OSSL_PARAM interrogation utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_PARAM_print_to_bio(const OSSL_PARAM *p, BIO *bio, +\& int print_values); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_PARAM_print_to_bio()\fR formats each parameter contained in the +passed in array of \fBOSSL_PARAM\fR values \fIp\fR, and prints both the key, +and optionally its value, to a provided \fBBIO\fR. +\&\fIp\fR must be a non\-null array of OSSL_PARAM values, terminated +with a value containing a null \fIkey\fR member. +\&\fIprint_values\fR is a control parameter, indicating that key values should be +printed, in addition to key names. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_PARAM_print_to_bio()\fR returns 1 on success, and 0 on failure +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_PARAM_print_to_bio()\fR was added in OpenSSL 3.5 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_PROVIDER.3 b/static/netbsd/man3/OSSL_PROVIDER.3 new file mode 100644 index 00000000..cf6fca36 --- /dev/null +++ b/static/netbsd/man3/OSSL_PROVIDER.3 @@ -0,0 +1,349 @@ +.\" $NetBSD: OSSL_PROVIDER.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_PROVIDER 3" +.TH OSSL_PROVIDER 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_PROVIDER_set_default_search_path, +OSSL_PROVIDER_get0_default_search_path, +OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload, +OSSL_PROVIDER_load_ex, OSSL_PROVIDER_try_load_ex, +OSSL_PROVIDER_available, OSSL_PROVIDER_do_all, +OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params, +OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation, +OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_get0_dispatch, +OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_get0_name, OSSL_PROVIDER_get_capabilities, +OSSL_PROVIDER_add_conf_parameter, OSSL_PROVIDER_get_conf_parameters, +OSSL_PROVIDER_conf_get_bool, OSSL_PROVIDER_self_test +\&\- provider routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_provider_st OSSL_PROVIDER; +\& +\& int OSSL_PROVIDER_set_default_search_path(OSSL_LIB_CTX *libctx, +\& const char *path); +\& const char *OSSL_PROVIDER_get0_default_search_path(OSSL_LIB_CTX *libctx); +\& +\& OSSL_PROVIDER *OSSL_PROVIDER_load(OSSL_LIB_CTX *libctx, const char *name); +\& OSSL_PROVIDER *OSSL_PROVIDER_load_ex(OSSL_LIB_CTX *, const char *name, +\& OSSL_PARAM *params); +\& OSSL_PROVIDER *OSSL_PROVIDER_try_load(OSSL_LIB_CTX *libctx, const char *name, +\& int retain_fallbacks); +\& OSSL_PROVIDER *OSSL_PROVIDER_try_load_ex(OSSL_LIB_CTX *, const char *name, +\& OSSL_PARAM *params, +\& int retain_fallbacks); +\& int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov); +\& int OSSL_PROVIDER_available(OSSL_LIB_CTX *libctx, const char *name); +\& int OSSL_PROVIDER_do_all(OSSL_LIB_CTX *ctx, +\& int (*cb)(OSSL_PROVIDER *provider, void *cbdata), +\& void *cbdata); +\& +\& const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov); +\& int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]); +\& +\& const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov, +\& int operation_id, +\& int *no_cache); +\& void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov, +\& int operation_id, +\& const OSSL_ALGORITHM *algs); +\& void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov); +\& const OSSL_DISPATCH *OSSL_PROVIDER_get0_dispatch(const OSSL_PROVIDER *prov); +\& +\& int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name, +\& ossl_provider_init_fn *init_fn); +\& +\& const char *OSSL_PROVIDER_get0_name(const OSSL_PROVIDER *prov); +\& +\& int OSSL_PROVIDER_get_capabilities(const OSSL_PROVIDER *prov, +\& const char *capability, +\& OSSL_CALLBACK *cb, +\& void *arg); +\& int OSSL_PROVIDER_add_conf_parameter(OSSL_PROVIDER *prov, const char *name, +\& const char *value); +\& int OSSL_PROVIDER_get_conf_parameters(OSSL_PROVIDER *prov, +\& OSSL_PARAM params[]); +\& int OSSL_PROVIDER_conf_get_bool(const OSSL_PROVIDER *prov, +\& const char *name, int defval); +\& int OSSL_PROVIDER_self_test(const OSSL_PROVIDER *prov); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_PROVIDER\fR is a type that holds internal information about +implementation providers (see \fBprovider\fR\|(7) for information on what a +provider is). +A provider can be built in to the application or the OpenSSL +libraries, or can be a loadable module. +The functions described here handle both forms. +.PP +Some of these functions operate within a library context, please see +\&\fBOSSL_LIB_CTX\fR\|(3) for further details. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_PROVIDER_set_default_search_path()\fR specifies the default search \fIpath\fR +that is to be used for looking for providers in the specified \fIlibctx\fR. +If left unspecified, an environment variable and a fall back default value will +be used instead. +.PP +\&\fBOSSL_PROVIDER_get0_default_search_path()\fR retrieves the default search \fIpath\fR +that is to be used for looking for providers in the specified \fIlibctx\fR. +If successful returns the path or empty string; the path is valid until the +context is released or \fBOSSL_PROVIDER_set_default_search_path()\fR is called. +.PP +\&\fBOSSL_PROVIDER_add_builtin()\fR is used to add a built in provider to +\&\fBOSSL_PROVIDER\fR store in the given library context, by associating a +provider name with a provider initialization function. +This name can then be used with \fBOSSL_PROVIDER_load()\fR. +.PP +\&\fBOSSL_PROVIDER_load()\fR loads and initializes a provider. +This may simply initialize a provider that was previously added with +\&\fBOSSL_PROVIDER_add_builtin()\fR and run its given initialization function, +or load a provider module with the given name and run its provider +entry point, \f(CW\*(C`OSSL_provider_init\*(C'\fR. The \fIname\fR can be a path +to a provider module, in that case the provider name as returned +by \fBOSSL_PROVIDER_get0_name()\fR will be the path. Interpretation +of relative paths is platform dependent and they are relative +to the configured "MODULESDIR" directory or the path set in +the environment variable OPENSSL_MODULES if set. +.PP +\&\fBOSSL_PROVIDER_try_load()\fR functions like \fBOSSL_PROVIDER_load()\fR, except that +it does not disable the fallback providers if the provider cannot be +loaded and initialized or if \fIretain_fallbacks\fR is nonzero. +If the provider loads successfully and \fIretain_fallbacks\fR is zero, the +fallback providers are disabled. +.PP +\&\fBOSSL_PROVIDER_load_ex()\fR and \fBOSSL_PROVIDER_try_load_ex()\fR are the variants +of the previous functions accepting an \f(CW\*(C`OSSL_PARAM\*(C'\fR array of the parameters +that are passed as the configuration of the loaded provider. The parameters +of any type but \f(CW\*(C`OSSL_PARAM_UTF8_STRING\*(C'\fR are silently ignored. If the +parameters are provided, they replace \fBall\fR the ones specified in the +configuration file. +.PP +\&\fBOSSL_PROVIDER_unload()\fR unloads the given provider. +For a provider added with \fBOSSL_PROVIDER_add_builtin()\fR, this simply +runs its teardown function. +.PP +\&\fBOSSL_PROVIDER_available()\fR checks if a named provider is available +for use. +.PP +\&\fBOSSL_PROVIDER_do_all()\fR iterates over all loaded providers, calling +\&\fIcb\fR for each one, with the current provider in \fIprovider\fR and the +\&\fIcbdata\fR that comes from the caller. If no other provider has been loaded +before calling this function, the default provider is still available as +fallback. +See \fBOSSL_PROVIDER\-default\fR\|(7) for more information on this fallback +behaviour. +.PP +\&\fBOSSL_PROVIDER_gettable_params()\fR is used to get a provider parameter +descriptor set as a constant \fBOSSL_PARAM\fR\|(3) array. +.PP +\&\fBOSSL_PROVIDER_get_params()\fR is used to get provider parameter values. +The caller must prepare the \fBOSSL_PARAM\fR\|(3) array before calling this +function, and the variables acting as buffers for this parameter array +should be filled with data when it returns successfully. +.PP +\&\fBOSSL_PROVIDER_add_conf_parameter()\fR sets the provider configuration parameter +\&\fIname\fR to \fIvalue\fR. +Provider configuration parameters are managed by the OpenSSL core and normally +set in the configuration file, but can also be set early in the main program +before a provider is in use by multiple threads. +Parameters that only affect provider initialisation must, for now, be set in +the configuration file, only parameters that are also queried later have any +affect when set via this interface. +Only text parameters can be given, and it\*(Aqs up to the provider to +interpret them. +.PP +\&\fBOSSL_PROVIDER_get_conf_parameters()\fR retrieves global configuration parameters +associated with \fIprov\fR. +These configuration parameters are stored for each provider by the OpenSSL core, +not the provider itself, parameters managed by the provider are queried via +\&\fBOSSL_PROVIDER_get_params()\fR described above. +The parameters are returned by reference, not as copies, and so the elements of +the \fIparam\fR array must have \fBOSSL_PARAM_UTF8_PTR\fR as their \fBdata_type\fR. +.PP +\&\fBOSSL_PROVIDER_conf_get_bool()\fR parses the global configuration parameter \fIname\fR +associated with provider \fIprov\fR as a boolean value, returning a default value +\&\fIdefval\fR when unable to retrieve or parse the parameter. +Parameter values equal (case\-insensitively) to \f(CW1\fR, \f(CW\*(C`on\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, or \f(CW\*(C`true\*(C'\fR +yield a true (nonzero) result. +Parameter values equal (case\-insensitively) to \f(CW0\fR, \f(CW\*(C`off\*(C'\fR, \f(CW\*(C`no\*(C'\fR, or \f(CW\*(C`false\*(C'\fR +yield a false (zero) result. +.PP +\&\fBOSSL_PROVIDER_self_test()\fR is used to run a provider\*(Aqs self tests on demand. +If the self tests fail then the provider will fail to provide any further +services and algorithms. \fBOSSL_SELF_TEST_set_callback\fR\|(3) may be called +beforehand in order to display diagnostics for the running self tests. +.PP +\&\fBOSSL_PROVIDER_query_operation()\fR calls the provider\*(Aqs \fIquery_operation\fR +function (see \fBprovider\fR\|(7)), if the provider has one. It returns an +array of \fIOSSL_ALGORITHM\fR for the given \fIoperation_id\fR terminated by an all +NULL OSSL_ALGORITHM entry. This is considered a low\-level function that most +applications should not need to call. +.PP +\&\fBOSSL_PROVIDER_unquery_operation()\fR calls the provider\*(Aqs \fIunquery_operation\fR +function (see \fBprovider\fR\|(7)), if the provider has one. This is considered a +low\-level function that most applications should not need to call. +.PP +\&\fBOSSL_PROVIDER_get0_provider_ctx()\fR returns the provider context for the given +provider. The provider context is an opaque handle set by the provider itself +and is passed back to the provider by libcrypto in various function calls. +.PP +\&\fBOSSL_PROVIDER_get0_dispatch()\fR returns the provider\*(Aqs dispatch table as it was +returned in the \fIout\fR parameter from the provider\*(Aqs init function. See +\&\fBprovider\-base\fR\|(7). +.PP +If it is permissible to cache references to this array then \fI*no_store\fR is set +to 0 or 1 otherwise. If the array is not cacheable then it is assumed to +have a short lifetime. +.PP +\&\fBOSSL_PROVIDER_get0_name()\fR returns the name of the given provider. +.PP +\&\fBOSSL_PROVIDER_get_capabilities()\fR provides information about the capabilities +supported by the provider specified in \fIprov\fR with the capability name +\&\fIcapability\fR. For each capability of that name supported by the provider it +will call the callback \fIcb\fR and supply a set of \fBOSSL_PARAM\fR\|(3)s describing the +capability. It will also pass back the argument \fIarg\fR. For more details about +capabilities and what they can be used for please see +"CAPABILITIES" in \fBprovider\-base\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_PROVIDER_set_default_search_path()\fR, \fBOSSL_PROVIDER_add()\fR, +\&\fBOSSL_PROVIDER_unload()\fR, \fBOSSL_PROVIDER_get_params()\fR, +\&\fBOSSL_PROVIDER_add_conf_parameter()\fR, \fBOSSL_PROVIDER_get_conf_parameters()\fR +and +\&\fBOSSL_PROVIDER_get_capabilities()\fR return 1 on success, or 0 on error. +.PP +\&\fBOSSL_PROVIDER_get0_default_search_path()\fR returns a pointer to a path on success, +or NULL on error or if the path has not previously been set. +.PP +\&\fBOSSL_PROVIDER_load()\fR and \fBOSSL_PROVIDER_try_load()\fR return a pointer to a +provider object on success, or NULL on error. +.PP +\&\fBOSSL_PROVIDER_do_all()\fR returns 1 if the callback \fIcb\fR returns 1 for every +provider it is called with, or 0 if any provider callback invocation returns 0; +callback processing stops at the first callback invocation on a provider +that returns 0. +.PP +\&\fBOSSL_PROVIDER_available()\fR returns 1 if the named provider is available, +otherwise 0. +.PP +\&\fBOSSL_PROVIDER_gettable_params()\fR returns a pointer to an array +of constant \fBOSSL_PARAM\fR\|(3), or NULL if none is provided. +.PP +\&\fBOSSL_PROVIDER_get_params()\fR and returns 1 on success, or 0 on error. +.PP +\&\fBOSSL_PROVIDER_query_operation()\fR returns an array of OSSL_ALGORITHM or NULL on +error. +.PP +\&\fBOSSL_PROVIDER_self_test()\fR returns 1 if the self tests pass, or 0 on error. +.SH EXAMPLES +.IX Header "EXAMPLES" +This demonstrates how to load the provider module "foo" and ask for +its build information. +.PP +.Vb 3 +\& #include +\& #include +\& #include +\& +\& OSSL_PROVIDER *prov = NULL; +\& const char *build = NULL; +\& OSSL_PARAM request[] = { +\& { "buildinfo", OSSL_PARAM_UTF8_PTR, &build, 0, 0 }, +\& { NULL, 0, NULL, 0, 0 } +\& }; +\& +\& if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL +\& && OSSL_PROVIDER_get_params(prov, request)) +\& printf("Provider \*(Aqfoo\*(Aq buildinfo: %s\en", build); +\& else +\& ERR_print_errors_fp(stderr); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBprovider\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The type and functions described here were added in OpenSSL 3.0. +.PP +The \fIOSSL_PROVIDER_load_ex\fR and \fIOSSL_PROVIDER_try_load_ex\fR functions were +added in OpenSSL 3.2. +.PP +The +\&\fIOSSL_PROVIDER_add_conf_parameter\fR, +\&\fIOSSL_PROVIDER_get_conf_parameters\fR, and +\&\fIOSSL_PROVIDER_conf_get_bool\fR functions +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_QUIC_client_method.3 b/static/netbsd/man3/OSSL_QUIC_client_method.3 new file mode 100644 index 00000000..24d556ba --- /dev/null +++ b/static/netbsd/man3/OSSL_QUIC_client_method.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: OSSL_QUIC_client_method.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_QUIC_client_method 3" +.TH OSSL_QUIC_client_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method +\&\- Provide SSL_METHOD objects for QUIC enabled functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const SSL_METHOD *OSSL_QUIC_client_method(void); +\& const SSL_METHOD *OSSL_QUIC_client_thread_method(void); +\& const SSL_METHOD *OSSL_QUIC_server_method(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBOSSL_QUIC_client_method()\fR, \fBOSSL_QUIC_client_thread_method()\fR, and +\&\fBOSSL_QUIC_server_method()\fR functions provide methods for the +\&\fBSSL_CTX_new_ex\fR\|(3) function to provide QUIC protocol support. +.PP +The \fBOSSL_QUIC_client_thread_method()\fR uses threads to allow for a blocking +mode of operation and avoid the need to return control to the +OpenSSL library for processing time based events. +The \fBOSSL_QUIC_client_method()\fR does not use threads and depends on +nonblocking mode of operation and the application periodically calling SSL +functions. +.PP +The \fBOSSL_QUIC_server_method()\fR provides server\-side QUIC protocol support and +must be used with the \fBSSL_new_listener\fR\|(3) API. Attempting to use +\&\fBOSSL_QUIC_server_method()\fR with \fBSSL_new\fR\|(3) will result in an error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return pointers to the constant method objects. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_new_ex\fR\|(3), \fBSSL_new_listener\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_QUIC_client_method()\fR and \fBOSSL_QUIC_client_thread_method()\fR were added in +OpenSSL 3.2. +.PP +\&\fBOSSL_QUIC_server_method()\fR was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_SELF_TEST_new.3 b/static/netbsd/man3/OSSL_SELF_TEST_new.3 new file mode 100644 index 00000000..85946876 --- /dev/null +++ b/static/netbsd/man3/OSSL_SELF_TEST_new.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: OSSL_SELF_TEST_new.3,v 1.5 2026/04/08 17:06:45 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_SELF_TEST_new 3" +.TH OSSL_SELF_TEST_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_SELF_TEST_new, +OSSL_SELF_TEST_free, +OSSL_SELF_TEST_onbegin, +OSSL_SELF_TEST_oncorrupt_byte, +OSSL_SELF_TEST_onend \- functionality to trigger a callback during a self test +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_SELF_TEST *OSSL_SELF_TEST_new(OSSL_CALLBACK *cb, void *cbarg); +\& void OSSL_SELF_TEST_free(OSSL_SELF_TEST *st); +\& +\& void OSSL_SELF_TEST_onbegin(OSSL_SELF_TEST *st, const char *type, +\& const char *desc); +\& int OSSL_SELF_TEST_oncorrupt_byte(OSSL_SELF_TEST *st, unsigned char *bytes); +\& void OSSL_SELF_TEST_onend(OSSL_SELF_TEST *st, int ret); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These methods are intended for use by provider implementers, to display +diagnostic information during self testing. +.PP +\&\fBOSSL_SELF_TEST_new()\fR allocates an opaque \fBOSSL_SELF_TEST\fR object that has a +callback and callback argument associated with it. +.PP +The callback \fIcb\fR may be triggered multiple times by a self test to indicate +different phases. +.PP +\&\fBOSSL_SELF_TEST_free()\fR frees the space allocated by \fBOSSL_SELF_TEST_new()\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_SELF_TEST_onbegin()\fR may be inserted at the start of a block of self test +code. It can be used for diagnostic purposes. +If this method is called the callback \fIcb\fR will receive the following +\&\fBOSSL_PARAM\fR\|(3) object. +.IP """st\-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) " 4 +.IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) " +The value is the string "Start" +.PP +\&\fBOSSL_SELF_TEST_oncorrupt_byte()\fR may be inserted just after the known answer is +calculated, but before the self test compares the result. The first byte in the +passed in array of \fIbytes\fR will be corrupted if the callback returns 0, +otherwise it leaves the array unaltered. It can be used for failure testing. +The \fItype\fR and \fIdesc\fR can be used to identify an individual self test to +target for failure testing. +If this method is called the callback \fIcb\fR will receive the following +\&\fBOSSL_PARAM\fR\|(3) object. +.IP """st\-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) " 4 +.IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) " +The value is the string "Corrupt" +.PP +\&\fBOSSL_SELF_TEST_onend()\fR may be inserted at the end of a block of self test code +just before cleanup to indicate if the test passed or failed. It can be used for +diagnostic purposes. +If this method is called the callback \fIcb\fR will receive the following +\&\fBOSSL_PARAM\fR\|(3) object. +.IP """st\-phase"" (\fBOSSL_PROV_PARAM_SELF_TEST_PHASE\fR) " 4 +.IX Item """st-phase"" (OSSL_PROV_PARAM_SELF_TEST_PHASE) " +The value of the string is "Pass" if \fIret\fR is non zero, otherwise it has the +value "Fail". +.PP +After the callback \fIcb\fR has been called the values that were set by +\&\fBOSSL_SELF_TEST_onbegin()\fR for \fItype\fR and \fIdesc\fR are set to the value "None". +.PP +If \fBOSSL_SELF_TEST_onbegin()\fR, \fBOSSL_SELF_TEST_oncorrupt_byte()\fR or +\&\fBOSSL_SELF_TEST_onend()\fR is called the following additional \fBOSSL_PARAM\fR\|(3) are +passed to the callback. +.IP """st\-type"" (\fBOSSL_PROV_PARAM_SELF_TEST_TYPE\fR) " 4 +.IX Item """st-type"" (OSSL_PROV_PARAM_SELF_TEST_TYPE) " +The value is setup by the \fItype\fR passed to \fBOSSL_SELF_TEST_onbegin()\fR. +This allows the callback to identify the type of test being run. +.IP """st\-desc"" (\fBOSSL_PROV_PARAM_SELF_TEST_DESC\fR) " 4 +.IX Item """st-desc"" (OSSL_PROV_PARAM_SELF_TEST_DESC) " +The value is setup by the \fItype\fR passed to \fBOSSL_SELF_TEST_onbegin()\fR. +This allows the callback to identify the sub category of the test being run. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_SELF_TEST_new()\fR returns the allocated \fBOSSL_SELF_TEST\fR object, or NULL if +it fails. +.PP +\&\fBOSSL_SELF_TEST_oncorrupt_byte()\fR returns 1 if corruption occurs, otherwise it +returns 0. +.SH EXAMPLES +.IX Header "EXAMPLES" +A single self test could be set up in the following way: +.PP +.Vb 8 +\& OSSL_SELF_TEST *st = NULL; +\& OSSL_CALLBACK *cb; +\& void *cbarg; +\& int ok = 0; +\& unsigned char out[EVP_MAX_MD_SIZE]; +\& unsigned int out_len = 0; +\& EVP_MD_CTX *ctx = EVP_MD_CTX_new(); +\& EVP_MD *md = EVP_MD_fetch(libctx, t\->algorithm, NULL); +\& +\& /* +\& * Retrieve the callback \- will be NULL if not set by the application via +\& * OSSL_SELF_TEST_set_callback(). +\& */ +\& OSSL_SELF_TEST_get_callback(libctx, &cb, &cbarg); +\& +\& st = OSSL_SELF_TEST_new(cb, cb_arg); +\& +\& /* Trigger the optional callback */ +\& OSSL_SELF_TEST_onbegin(st, OSSL_SELF_TEST_TYPE_KAT_DIGEST, +\& OSSL_SELF_TEST_DESC_MD_SHA2); +\& +\& if (!EVP_DigestInit_ex(ctx, md, NULL) +\& || !EVP_DigestUpdate(ctx, pt, pt_len) +\& || !EVP_DigestFinal(ctx, out, &out_len)) +\& goto err; +\& +\& /* Optional corruption \- If the application callback returns 0 */ +\& OSSL_SELF_TEST_oncorrupt_byte(st, out); +\& +\& if (out_len != t\->expected_len +\& || memcmp(out, t\->expected, out_len) != 0) +\& goto err; +\& ok = 1; +\& err: +\& OSSL_SELF_TEST_onend(st, ok); +\& EVP_MD_free(md); +\& EVP_MD_CTX_free(ctx); +.Ve +.PP +Multiple self test\*(Aqs can be set up in a similar way by repeating the pattern of +\&\fBOSSL_SELF_TEST_onbegin()\fR, \fBOSSL_SELF_TEST_oncorrupt_byte()\fR, \fBOSSL_SELF_TEST_onend()\fR +for each test. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_SELF_TEST_set_callback\fR\|(3), +\&\fBopenssl\-core.h\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_SELF_TEST_set_callback.3 b/static/netbsd/man3/OSSL_SELF_TEST_set_callback.3 new file mode 100644 index 00000000..c1e27f5e --- /dev/null +++ b/static/netbsd/man3/OSSL_SELF_TEST_set_callback.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: OSSL_SELF_TEST_set_callback.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_SELF_TEST_set_callback 3" +.TH OSSL_SELF_TEST_set_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_SELF_TEST_set_callback, +OSSL_SELF_TEST_get_callback \- specify a callback for processing self tests +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void OSSL_SELF_TEST_set_callback(OSSL_LIB_CTX *ctx, OSSL_CALLBACK *cb, void *cbarg); +\& void OSSL_SELF_TEST_get_callback(OSSL_LIB_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Set or gets the optional application callback (and the callback argument) that +is called during self testing. +The application callback \fBOSSL_CALLBACK\fR\|(3) is associated with a \fBOSSL_LIB_CTX\fR. +The application callback function receives information about a running self test, +and may return a result to the calling self test. +See \fBopenssl\-core.h\fR\|(7) for further information on the callback. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_SELF_TEST_get_callback()\fR returns the callback and callback argument that +has been set via \fBOSSL_SELF_TEST_set_callback()\fR for the given library context +\&\fIctx\fR. +These returned parameters will be NULL if \fBOSSL_SELF_TEST_set_callback()\fR has +not been called. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-core.h\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7) +\&\fBOSSL_SELF_TEST_new\fR\|(3) +\&\fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_INFO.3 b/static/netbsd/man3/OSSL_STORE_INFO.3 new file mode 100644 index 00000000..136dd5b6 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_INFO.3 @@ -0,0 +1,277 @@ +.\" $NetBSD: OSSL_STORE_INFO.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_INFO 3" +.TH OSSL_STORE_INFO 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME, +OSSL_STORE_INFO_get0_NAME_description, +OSSL_STORE_INFO_get0_PARAMS, OSSL_STORE_INFO_get0_PUBKEY, +OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL, +OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description, +OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PUBKEY, +OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT, OSSL_STORE_INFO_get1_CRL, +OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free, +OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description, +OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PUBKEY, +OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL, +OSSL_STORE_INFO_new, OSSL_STORE_INFO_get0_data +\&\- Functions to manipulate OSSL_STORE_INFO objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_store_info_st OSSL_STORE_INFO; +\& +\& int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info); +\& const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info); +\& char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info); +\& const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO +\& *store_info); +\& char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info); +\& EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info); +\& EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info); +\& EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info); +\& EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info); +\& EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info); +\& EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info); +\& X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info); +\& X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info); +\& X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info); +\& X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info); +\& +\& const char *OSSL_STORE_INFO_type_string(int type); +\& +\& void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info); +\& +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); +\& int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params); +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey); +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); +\& +\& OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data); +\& void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are primarily useful for applications to retrieve +supported objects from \fBOSSL_STORE_INFO\fR objects and for scheme specific +loaders to create \fBOSSL_STORE_INFO\fR holders. +.SS Types +.IX Subsection "Types" +\&\fBOSSL_STORE_INFO\fR is an opaque type that\*(Aqs just an intermediary holder for +the objects that have been retrieved by \fBOSSL_STORE_load()\fR and similar functions. +Supported OpenSSL type object can be extracted using one of +STORE_INFO_get0_() where can be NAME, PARAMS, PKEY, CERT, or CRL. +The life time of this extracted object is as long as the life time of +the \fBOSSL_STORE_INFO\fR it was extracted from, so care should be taken not +to free the latter too early. +As an alternative, STORE_INFO_get1_() extracts a duplicate (or the +same object with its reference count increased), which can be used +after the containing \fBOSSL_STORE_INFO\fR has been freed. +The object returned by STORE_INFO_get1_() must be freed separately +by the caller. +See "SUPPORTED OBJECTS" for more information on the types that are supported. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_STORE_INFO_get_type()\fR takes a \fBOSSL_STORE_INFO\fR and returns the STORE +type number for the object inside. +.PP +\&\fBSTORE_INFO_get_type_string()\fR takes a STORE type number and returns a +short string describing it. +.PP +\&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR, +\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PUBKEY()\fR, +\&\fBOSSL_STORE_INFO_get0_PKEY()\fR, \fBOSSL_STORE_INFO_get0_CERT()\fR, +\&\fBOSSL_STORE_INFO_get0_CRL()\fR +all take a \fBOSSL_STORE_INFO\fR and return the object it holds if the +\&\fBOSSL_STORE_INFO\fR type (as returned by \fBOSSL_STORE_INFO_get_type()\fR) +matches the function, otherwise NULL. +.PP +\&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR, +\&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PUBKEY()\fR, +\&\fBOSSL_STORE_INFO_get1_PKEY()\fR, \fBOSSL_STORE_INFO_get1_CERT()\fR and +\&\fBOSSL_STORE_INFO_get1_CRL()\fR +all take a \fBOSSL_STORE_INFO\fR and return a duplicate the object it +holds if the \fBOSSL_STORE_INFO\fR type (as returned by +\&\fBOSSL_STORE_INFO_get_type()\fR) matches the function, otherwise NULL. +.PP +\&\fBOSSL_STORE_INFO_free()\fR frees a \fBOSSL_STORE_INFO\fR and its contained type. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_STORE_INFO_new_NAME()\fR , \fBOSSL_STORE_INFO_new_PARAMS()\fR, +, \fBOSSL_STORE_INFO_new_PUBKEY()\fR, \fBOSSL_STORE_INFO_new_PKEY()\fR, +\&\fBOSSL_STORE_INFO_new_CERT()\fR and \fBOSSL_STORE_INFO_new_CRL()\fR +create a \fBOSSL_STORE_INFO\fR object to hold the given input object. +On success the input object is consumed. +.PP +Additionally, for \fBOSSL_STORE_INFO_NAME\fR objects, +\&\fBOSSL_STORE_INFO_set0_NAME_description()\fR can be used to add an extra +description. +This description is meant to be human readable and should be used for +information printout. +.PP +\&\fBOSSL_STORE_INFO_new()\fR creates a \fBOSSL_STORE_INFO\fR with an arbitrary \fItype\fR +number and \fIdata\fR structure. It\*(Aqs the responsibility of the caller to +define type numbers other than the ones defined by \fI\fR, +and to handle freeing the associated data structure on their own. +\&\fIUsing type numbers that are defined by may cause +undefined behaviours, including crashes\fR. +.PP +\&\fBOSSL_STORE_INFO_get0_data()\fR returns the data pointer that was passed to +\&\fBOSSL_STORE_INFO_new()\fR if \fItype\fR matches the type number in \fIinfo\fR. +.PP +\&\fBOSSL_STORE_INFO_new()\fR and \fBOSSL_STORE_INFO_get0_data()\fR may be useful for +applications that define their own STORE data, but must be used with care. +.SH "SUPPORTED OBJECTS" +.IX Header "SUPPORTED OBJECTS" +Currently supported object types are: +.IP OSSL_STORE_INFO_NAME 4 +.IX Item "OSSL_STORE_INFO_NAME" +A name is exactly that, a name. +It\*(Aqs like a name in a directory, but formatted as a complete URI. +For example, the path in URI \f(CW\*(C`file:/foo/bar/\*(C'\fR could include a file +named \f(CW\*(C`cookie.pem\*(C'\fR, and in that case, the returned \fBOSSL_STORE_INFO_NAME\fR +object would have the URI \f(CW\*(C`file:/foo/bar/cookie.pem\*(C'\fR, which can be +used by the application to get the objects in that file. +This can be applied to all schemes that can somehow support a listing +of object URIs. +.Sp +For \f(CW\*(C`file:\*(C'\fR URIs that are used without the explicit scheme, the +returned name will be the path of each object, so if \f(CW\*(C`/foo/bar\*(C'\fR was +given and that path has the file \f(CW\*(C`cookie.pem\*(C'\fR, the name +\&\f(CW\*(C`/foo/bar/cookie.pem\*(C'\fR will be returned. +.Sp +The returned URI is considered canonical and must be unique and permanent +for the storage where the object (or collection of objects) resides. +Each loader is responsible for ensuring that it only returns canonical +URIs. +However, it\*(Aqs possible that certain schemes allow an object (or collection +thereof) to be reached with alternative URIs; just because one URI is +canonical doesn\*(Aqt mean that other variants can\*(Aqt be used. +.Sp +At the discretion of the loader that was used to get these names, an +extra description may be attached as well. +.IP OSSL_STORE_INFO_PARAMS 4 +.IX Item "OSSL_STORE_INFO_PARAMS" +Key parameters. +.IP OSSL_STORE_INFO_PKEY 4 +.IX Item "OSSL_STORE_INFO_PKEY" +A keypair or just a private key (possibly with key parameters). +.IP OSSL_STORE_INFO_PUBKEY 4 +.IX Item "OSSL_STORE_INFO_PUBKEY" +A public key (possibly with key parameters). +.IP OSSL_STORE_INFO_CERT 4 +.IX Item "OSSL_STORE_INFO_CERT" +An X.509 certificate. +.IP OSSL_STORE_INFO_CRL 4 +.IX Item "OSSL_STORE_INFO_CRL" +A X.509 certificate revocation list. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_INFO_get_type()\fR returns the STORE type number of the given +\&\fBOSSL_STORE_INFO\fR. +There is no error value. +.PP +\&\fBOSSL_STORE_INFO_get0_NAME()\fR, \fBOSSL_STORE_INFO_get0_NAME_description()\fR, +\&\fBOSSL_STORE_INFO_get0_PARAMS()\fR, \fBOSSL_STORE_INFO_get0_PKEY()\fR, +\&\fBOSSL_STORE_INFO_get0_CERT()\fR and \fBOSSL_STORE_INFO_get0_CRL()\fR all return +a pointer to the OpenSSL object on success, NULL otherwise. +.PP +\&\fBOSSL_STORE_INFO_get1_NAME()\fR, \fBOSSL_STORE_INFO_get1_NAME_description()\fR, +\&\fBOSSL_STORE_INFO_get1_PARAMS()\fR, \fBOSSL_STORE_INFO_get1_PKEY()\fR, +\&\fBOSSL_STORE_INFO_get1_CERT()\fR and \fBOSSL_STORE_INFO_get1_CRL()\fR all return +a pointer to a duplicate of the OpenSSL object on success, NULL otherwise. +.PP +\&\fBOSSL_STORE_INFO_type_string()\fR returns a string on success, or NULL on +failure. +.PP +\&\fBOSSL_STORE_INFO_new_NAME()\fR, \fBOSSL_STORE_INFO_new_PARAMS()\fR, +\&\fBOSSL_STORE_INFO_new_PKEY()\fR, \fBOSSL_STORE_INFO_new_CERT()\fR and +\&\fBOSSL_STORE_INFO_new_CRL()\fR return a \fBOSSL_STORE_INFO\fR +pointer on success, or NULL on failure. +.PP +\&\fBOSSL_STORE_INFO_set0_NAME_description()\fR returns 1 on success, or 0 on +failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3), \fBOSSL_STORE_register_loader\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OSSL_STORE API was added in OpenSSL 1.1.1. +.PP +The OSSL_STORE_INFO_PUBKEY object type was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_LOADER.3 b/static/netbsd/man3/OSSL_STORE_LOADER.3 new file mode 100644 index 00000000..dde60dd6 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_LOADER.3 @@ -0,0 +1,434 @@ +.\" $NetBSD: OSSL_STORE_LOADER.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_LOADER 3" +.TH OSSL_STORE_LOADER 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_LOADER, +OSSL_STORE_LOADER_fetch, +OSSL_STORE_LOADER_up_ref, +OSSL_STORE_LOADER_free, +OSSL_STORE_LOADER_get0_provider, +OSSL_STORE_LOADER_get0_properties, +OSSL_STORE_LOADER_is_a, +OSSL_STORE_LOADER_get0_description, +OSSL_STORE_LOADER_do_all_provided, +OSSL_STORE_LOADER_names_do_all, +OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new, +OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme, +OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_open_ex, +OSSL_STORE_LOADER_set_attach, OSSL_STORE_LOADER_set_ctrl, +OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find, +OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof, +OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close, +OSSL_STORE_register_loader, OSSL_STORE_unregister_loader, +OSSL_STORE_open_fn, OSSL_STORE_open_ex_fn, +OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn, +OSSL_STORE_expect_fn, OSSL_STORE_find_fn, +OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn, +OSSL_STORE_close_fn \- Types and functions to manipulate, register and +unregister STORE loaders for different URI schemes +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_store_loader_st OSSL_STORE_LOADER; +\& +\& OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx, +\& const char *scheme, +\& const char *properties); +\& int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader); +\& void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); +\& const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER * +\& loader); +\& const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader); +\& const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader); +\& int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader, +\& const char *scheme); +\& void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*user_fn)(OSSL_STORE_LOADER *loader, +\& void *arg), +\& void *user_arg); +\& int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader, +\& void (*fn)(const char *name, void *data), +\& void *data); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 5 +\& OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); +\& const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER +\& *store_loader); +\& const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER +\& *store_loader); +\& +\& /* struct ossl_store_loader_ctx_st is defined differently by each loader */ +\& typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; +\& +\& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)( +\& const char *uri, const UI_METHOD *ui_method, void *ui_data); +\& int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_open_fn store_open_function); +\& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn)( +\& const char *uri, const UI_METHOD *ui_method, void *ui_data); +\& int OSSL_STORE_LOADER_set_open_ex +\& (OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_open_ex_fn store_open_ex_function); +\& typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn) +\& (const OSSL_STORE_LOADER *loader, BIO *bio, +\& OSSL_LIB_CTX *libctx, const char *propq, +\& const UI_METHOD *ui_method, void *ui_data); +\& int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader, +\& OSSL_STORE_attach_fn attach_function); +\& typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd, +\& va_list args); +\& int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_ctrl_fn store_ctrl_function); +\& typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected); +\& int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader, +\& OSSL_STORE_expect_fn expect_function); +\& typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx, +\& OSSL_STORE_SEARCH *criteria); +\& int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader, +\& OSSL_STORE_find_fn find_function); +\& typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, +\& UI_METHOD *ui_method, +\& void *ui_data); +\& int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_load_fn store_load_function); +\& typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_eof_fn store_eof_function); +\& typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_error_fn store_error_function); +\& typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); +\& int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader, +\& OSSL_STORE_close_fn store_close_function); +\& +\& int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); +\& OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_STORE_LOADER\fR is a method for OSSL_STORE loaders, which implement +\&\fBOSSL_STORE_open()\fR, \fBOSSL_STORE_open_ex()\fR, \fBOSSL_STORE_load()\fR, +\&\fBOSSL_STORE_eof()\fR, \fBOSSL_STORE_error()\fR and \fBOSSL_STORE_close()\fR for specific +storage schemes. +.PP +\&\fBOSSL_STORE_LOADER_fetch()\fR looks for an implementation for a storage +\&\fIscheme\fR within the providers that has been loaded into the \fBOSSL_LIB_CTX\fR +given by \fIlibctx\fR, and with the properties given by \fIproperties\fR. +.PP +\&\fBOSSL_STORE_LOADER_up_ref()\fR increments the reference count for the given +\&\fIloader\fR. +.PP +\&\fBOSSL_STORE_LOADER_free()\fR decrements the reference count for the given +\&\fIloader\fR, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_STORE_LOADER_get0_provider()\fR returns the provider of the given +\&\fIloader\fR. +.PP +\&\fBOSSL_STORE_LOADER_get0_properties()\fR returns the property definition associated +with the given \fIloader\fR. +.PP +\&\fBOSSL_STORE_LOADER_is_a()\fR checks if \fIloader\fR is an implementation +of an algorithm that\*(Aqs identifiable with \fIscheme\fR. +.PP +\&\fBOSSL_STORE_LOADER_get0_description()\fR returns a description of the \fIloader\fR, meant +for display and human consumption. The description is at the discretion of the +\&\fIloader\fR implementation. +.PP +\&\fBOSSL_STORE_LOADER_do_all_provided()\fR traverses all store implementations +by all activated providers in the library context \fIlibctx\fR, and for each +of the implementations, calls \fIuser_fn\fR with the implementation method and +\&\fIuser_arg\fR as arguments. +.PP +\&\fBOSSL_STORE_LOADER_names_do_all()\fR traverses all names for the given +\&\fIloader\fR, and calls \fIfn\fR with each name and \fIdata\fR. +.SS "Legacy Types and Functions (deprecated)" +.IX Subsection "Legacy Types and Functions (deprecated)" +These functions help applications and engines to create loaders for +schemes they support. These are all deprecated and discouraged in favour of +provider implementations, see \fBprovider\-storemgmt\fR\|(7). +.PP +\&\fBOSSL_STORE_LOADER_CTX\fR is a type template, to be defined by each loader +using \f(CW\*(C`struct ossl_store_loader_ctx_st { ... }\*(C'\fR. +.PP +\&\fBOSSL_STORE_open_fn\fR, \fBOSSL_STORE_open_ex_fn\fR, +\&\fBOSSL_STORE_ctrl_fn\fR, \fBOSSL_STORE_expect_fn\fR, \fBOSSL_STORE_find_fn\fR, +\&\fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR, and \fBOSSL_STORE_close_fn\fR +are the function pointer types used within a STORE loader. +The functions pointed at define the functionality of the given loader. +.IP "\fBOSSL_STORE_open_fn\fR and \fBOSSL_STORE_open_ex_fn\fR" 4 +.IX Item "OSSL_STORE_open_fn and OSSL_STORE_open_ex_fn" +\&\fBOSSL_STORE_open_ex_fn\fR takes a URI and is expected to +interpret it in the best manner possible according to the scheme the +loader implements. It also takes a \fBUI_METHOD\fR and associated data, +to be used any time something needs to be prompted for, as well as a +library context \fIlibctx\fR with an associated property query \fIpropq\fR, +to be used when fetching necessary algorithms to perform the loads. +Furthermore, this function is expected to initialize what needs to be +initialized, to create a private data store (\fBOSSL_STORE_LOADER_CTX\fR, +see above), and to return it. +If something goes wrong, this function is expected to return NULL. +.Sp +\&\fBOSSL_STORE_open_fn\fR does the same thing as +\&\fBOSSL_STORE_open_ex_fn\fR but uses NULL for the library +context \fIlibctx\fR and property query \fIpropq\fR. +.IP \fBOSSL_STORE_attach_fn\fR 4 +.IX Item "OSSL_STORE_attach_fn" +This function takes a \fBBIO\fR, otherwise works like +\&\fBOSSL_STORE_open_ex_fn\fR. +.IP \fBOSSL_STORE_ctrl_fn\fR 4 +.IX Item "OSSL_STORE_ctrl_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer, a command number +\&\fIcmd\fR and a \fBva_list\fR \fIargs\fR and is used to manipulate loader +specific parameters. +.Sp +Loader specific command numbers must begin at \fBOSSL_STORE_C_CUSTOM_START\fR. +Any number below that is reserved for future globally known command +numbers. +.Sp +This function is expected to return 1 on success, 0 on error. +.IP \fBOSSL_STORE_expect_fn\fR 4 +.IX Item "OSSL_STORE_expect_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and a \fBOSSL_STORE_INFO\fR +identity \fIexpected\fR, and is used to tell the loader what object type is +expected. +\&\fIexpected\fR may be zero to signify that no specific object type is expected. +.Sp +This function is expected to return 1 on success, 0 on error. +.IP \fBOSSL_STORE_find_fn\fR 4 +.IX Item "OSSL_STORE_find_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and a +\&\fBOSSL_STORE_SEARCH\fR search criterion, and is used to tell the loader what +to search for. +.Sp +When called with the loader context being NULL, this function is expected +to return 1 if the loader supports the criterion, otherwise 0. +.Sp +When called with the loader context being something other than NULL, this +function is expected to return 1 on success, 0 on error. +.IP \fBOSSL_STORE_load_fn\fR 4 +.IX Item "OSSL_STORE_load_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and a \fBUI_METHOD\fR +with associated data. +It\*(Aqs expected to load the next available data, mold it into a data +structure that can be wrapped in a \fBOSSL_STORE_INFO\fR using one of the +\&\fBOSSL_STORE_INFO\fR\|(3) functions. +If no more data is available or an error occurs, this function is +expected to return NULL. +The \fBOSSL_STORE_eof_fn\fR and \fBOSSL_STORE_error_fn\fR functions must indicate if +it was in fact the end of data or if an error occurred. +.Sp +Note that this function retrieves \fIone\fR data item only. +.IP \fBOSSL_STORE_eof_fn\fR 4 +.IX Item "OSSL_STORE_eof_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and is expected to +return 1 to indicate that the end of available data has been reached. +It is otherwise expected to return 0. +.IP \fBOSSL_STORE_error_fn\fR 4 +.IX Item "OSSL_STORE_error_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and is expected to +return 1 to indicate that an error occurred in a previous call to the +\&\fBOSSL_STORE_load_fn\fR function. +It is otherwise expected to return 0. +.IP \fBOSSL_STORE_close_fn\fR 4 +.IX Item "OSSL_STORE_close_fn" +This function takes a \fBOSSL_STORE_LOADER_CTX\fR pointer and is expected to +close or shut down what needs to be closed, and finally free the +contents of the \fBOSSL_STORE_LOADER_CTX\fR pointer. +It returns 1 on success and 0 on error. +.PP +\&\fBOSSL_STORE_LOADER_new()\fR creates a new \fBOSSL_STORE_LOADER\fR. +It takes an \fBENGINE\fR \fIe\fR and a string \fIscheme\fR. +\&\fIscheme\fR must \fIalways\fR be set. +Both \fIe\fR and \fIscheme\fR are used as is and must therefore be alive as +long as the created loader is. +.PP +\&\fBOSSL_STORE_LOADER_get0_engine()\fR returns the engine of the \fIstore_loader\fR. +\&\fBOSSL_STORE_LOADER_get0_scheme()\fR returns the scheme of the \fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_open()\fR sets the opener function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_open_ex()\fR sets the opener with library context +function for the \fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_attach()\fR sets the attacher function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR sets the control function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_expect()\fR sets the expect function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_load()\fR sets the loader function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_eof()\fR sets the end of file checker function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_set_close()\fR sets the closing function for the +\&\fIstore_loader\fR. +.PP +\&\fBOSSL_STORE_LOADER_free()\fR frees the given \fIstore_loader\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBOSSL_STORE_register_loader()\fR register the given \fIstore_loader\fR and +thereby makes it available for use with \fBOSSL_STORE_open()\fR, +\&\fBOSSL_STORE_open_ex()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR +and \fBOSSL_STORE_close()\fR. +.PP +\&\fBOSSL_STORE_unregister_loader()\fR unregister the store loader for the given +\&\fIscheme\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_LOADER_fetch()\fR returns a pointer to an OSSL_STORE_LOADER object, +or NULL on error. +.PP +\&\fBOSSL_STORE_LOADER_up_ref()\fR returns 1 on success, or 0 on error. +.PP +\&\fBOSSL_STORE_LOADER_names_do_all()\fR returns 1 if the callback was called for all +names. A return value of 0 means that the callback was not called for any names. +.PP +\&\fBOSSL_STORE_LOADER_free()\fR doesn\*(Aqt return any value. +.PP +\&\fBOSSL_STORE_LOADER_get0_provider()\fR returns a pointer to a provider object, or +NULL on error. +.PP +\&\fBOSSL_STORE_LOADER_get0_properties()\fR returns a pointer to a property +definition string, or NULL on error. +.PP +\&\fBOSSL_STORE_LOADER_is_a()\fR returns 1 if \fIloader\fR was identifiable, +otherwise 0. +.PP +\&\fBOSSL_STORE_LOADER_get0_description()\fR returns a pointer to a description, or NULL if +there isn\*(Aqt one. +.PP +The functions with the types \fBOSSL_STORE_open_fn\fR, +\&\fBOSSL_STORE_open_ex_fn\fR, \fBOSSL_STORE_ctrl_fn\fR, +\&\fBOSSL_STORE_expect_fn\fR, \fBOSSL_STORE_load_fn\fR, \fBOSSL_STORE_eof_fn\fR +and \fBOSSL_STORE_close_fn\fR have the same return values as \fBOSSL_STORE_open()\fR, +\&\fBOSSL_STORE_open_ex()\fR, \fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_expect()\fR, +\&\fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR, respectively. +.PP +\&\fBOSSL_STORE_LOADER_new()\fR returns a pointer to a \fBOSSL_STORE_LOADER\fR on success, +or NULL on failure. +.PP +\&\fBOSSL_STORE_LOADER_set_open()\fR, \fBOSSL_STORE_LOADER_set_open_ex()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, \fBOSSL_STORE_LOADER_set_load()\fR, +\&\fBOSSL_STORE_LOADER_set_eof()\fR and \fBOSSL_STORE_LOADER_set_close()\fR return 1 +on success, or 0 on failure. +.PP +\&\fBOSSL_STORE_register_loader()\fR returns 1 on success, or 0 on failure. +.PP +\&\fBOSSL_STORE_unregister_loader()\fR returns the unregistered loader on success, +or NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3), \fBOSSL_LIB_CTX\fR\|(3), +\&\fBprovider\-storemgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_STORE_LOADER_fetch()\fR, \fBOSSL_STORE_LOADER_up_ref()\fR, +\&\fBOSSL_STORE_LOADER_get0_provider()\fR, \fBOSSL_STORE_LOADER_get0_properties()\fR, +\&\fBOSSL_STORE_LOADER_get0_description()\fR, \fBOSSL_STORE_LOADER_is_a()\fR, +\&\fBOSSL_STORE_LOADER_do_all_provided()\fR and \fBOSSL_STORE_LOADER_names_do_all()\fR +were added in OpenSSL 3.0. +.PP +\&\fBOSSL_STORE_LOADER\fR and \fBOSSL_STORE_LOADER_free()\fR were added in OpenSSL +1.1.1. +.PP +\&\fBOSSL_STORE_LOADER_set_open_ex()\fR and \fBOSSL_STORE_open_ex_fn()\fR were added in +OpenSSL 3.0, and are deprecated. +.PP +\&\fBOSSL_STORE_LOADER_CTX\fR, \fBOSSL_STORE_LOADER_new()\fR, +\&\fBOSSL_STORE_LOADER_set0_scheme()\fR, \fBOSSL_STORE_LOADER_get0_scheme()\fR, +\&\fBOSSL_STORE_LOADER_get0_engine()\fR, \fBOSSL_STORE_LOADER_set_expect()\fR, +\&\fBOSSL_STORE_LOADER_set_find()\fR, \fBOSSL_STORE_LOADER_set_attach()\fR, +\&\fBOSSL_STORE_LOADER_set_open_ex()\fR, \fBOSSL_STORE_LOADER_set_open()\fR, +\&\fBOSSL_STORE_LOADER_set_ctrl()\fR, +\&\fBOSSL_STORE_LOADER_set_load()\fR, \fBOSSL_STORE_LOADER_set_eof()\fR, +\&\fBOSSL_STORE_LOADER_set_close()\fR, +\&\fBOSSL_STORE_register_loader()\fR, \fBOSSL_STORE_LOADER_set_error()\fR, +\&\fBOSSL_STORE_unregister_loader()\fR, \fBOSSL_STORE_open_fn()\fR, \fBOSSL_STORE_ctrl_fn()\fR, +\&\fBOSSL_STORE_load_fn()\fR, \fBOSSL_STORE_eof_fn()\fR and \fBOSSL_STORE_close_fn()\fR +were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_SEARCH.3 b/static/netbsd/man3/OSSL_STORE_SEARCH.3 new file mode 100644 index 00000000..1a2b0722 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_SEARCH.3 @@ -0,0 +1,240 @@ +.\" $NetBSD: OSSL_STORE_SEARCH.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_SEARCH 3" +.TH OSSL_STORE_SEARCH 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_SEARCH, +OSSL_STORE_SEARCH_by_name, +OSSL_STORE_SEARCH_by_issuer_serial, +OSSL_STORE_SEARCH_by_key_fingerprint, +OSSL_STORE_SEARCH_by_alias, +OSSL_STORE_SEARCH_free, +OSSL_STORE_SEARCH_get_type, +OSSL_STORE_SEARCH_get0_name, +OSSL_STORE_SEARCH_get0_serial, +OSSL_STORE_SEARCH_get0_bytes, +OSSL_STORE_SEARCH_get0_string, +OSSL_STORE_SEARCH_get0_digest +\&\- Type and functions to create OSSL_STORE search criteria +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_store_search_st OSSL_STORE_SEARCH; +\& +\& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name); +\& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name, +\& const ASN1_INTEGER +\& *serial); +\& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest, +\& const unsigned char +\& *bytes, int len); +\& OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias); +\& +\& void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search); +\& +\& int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion); +\& X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion); +\& const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH +\& *criterion); +\& const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH +\& *criterion, size_t *length); +\& const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion); +\& const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH +\& *criterion); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are used to specify search criteria to help search for specific +objects through other names than just the URI that\*(Aqs given to \fBOSSL_STORE_open()\fR. +For example, this can be useful for an application that has received a URI +and then wants to add on search criteria in a uniform and supported manner. +.SS Types +.IX Subsection "Types" +\&\fBOSSL_STORE_SEARCH\fR is an opaque type that holds the constructed search +criterion, and that can be given to an OSSL_STORE context with +\&\fBOSSL_STORE_find()\fR. +.PP +The calling application owns the allocation of an \fBOSSL_STORE_SEARCH\fR at all +times, and should therefore be careful not to deallocate it before +\&\fBOSSL_STORE_close()\fR has been called for the OSSL_STORE context it was given +to. +.SS "Application Functions" +.IX Subsection "Application Functions" +\&\fBOSSL_STORE_SEARCH_by_name()\fR, +\&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR, +\&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR, +and \fBOSSL_STORE_SEARCH_by_alias()\fR +are used to create an \fBOSSL_STORE_SEARCH\fR from a subject name, an issuer name +and serial number pair, a key fingerprint, and an alias (for example a friendly +name). +The parameters that are provided are not copied, only referred to in a +criterion, so they must have at least the same life time as the created +\&\fBOSSL_STORE_SEARCH\fR. +.PP +\&\fBOSSL_STORE_SEARCH_free()\fR is used to free the \fBOSSL_STORE_SEARCH\fR. +If the argument is NULL, nothing is done. +.SS "Loader Functions" +.IX Subsection "Loader Functions" +\&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type for the given +\&\fBOSSL_STORE_SEARCH\fR. +.PP +\&\fBOSSL_STORE_SEARCH_get0_name()\fR, \fBOSSL_STORE_SEARCH_get0_serial()\fR, +\&\fBOSSL_STORE_SEARCH_get0_bytes()\fR, \fBOSSL_STORE_SEARCH_get0_string()\fR, +and \fBOSSL_STORE_SEARCH_get0_digest()\fR +are used to retrieve different data from a \fBOSSL_STORE_SEARCH\fR, as +available for each type. +For more information, see "SUPPORTED CRITERION TYPES" below. +.SH "SUPPORTED CRITERION TYPES" +.IX Header "SUPPORTED CRITERION TYPES" +Currently supported criterion types are: +.IP OSSL_STORE_SEARCH_BY_NAME 4 +.IX Item "OSSL_STORE_SEARCH_BY_NAME" +This criterion supports a search by exact match of subject name. +The subject name itself is a \fBX509_NAME\fR pointer. +A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_name()\fR, +and the actual subject name is retrieved with \fBOSSL_STORE_SEARCH_get0_name()\fR. +.IP OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 4 +.IX Item "OSSL_STORE_SEARCH_BY_ISSUER_SERIAL" +This criterion supports a search by exact match of both issuer name and serial +number. +The issuer name itself is a \fBX509_NAME\fR pointer, and the serial number is +a \fBASN1_INTEGER\fR pointer. +A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_issuer_serial()\fR +and the actual issuer name and serial number are retrieved with +\&\fBOSSL_STORE_SEARCH_get0_name()\fR and \fBOSSL_STORE_SEARCH_get0_serial()\fR. +.IP OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 4 +.IX Item "OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT" +This criterion supports a search by exact match of key fingerprint. +The key fingerprint in itself is a string of bytes and its length, as +well as the algorithm that was used to compute the fingerprint. +The digest may be left unspecified (NULL), and in that case, the +loader has to decide on a default digest and compare fingerprints +accordingly. +A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR +and the actual fingerprint and its length can be retrieved with +\&\fBOSSL_STORE_SEARCH_get0_bytes()\fR. +The digest can be retrieved with \fBOSSL_STORE_SEARCH_get0_digest()\fR. +.IP OSSL_STORE_SEARCH_BY_ALIAS 4 +.IX Item "OSSL_STORE_SEARCH_BY_ALIAS" +This criterion supports a search by match of an alias of some kind. +The alias in itself is a simple C string. +A criterion of this type is created with \fBOSSL_STORE_SEARCH_by_alias()\fR +and the actual alias is retrieved with \fBOSSL_STORE_SEARCH_get0_string()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_SEARCH_by_name()\fR, +\&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR, +\&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR, +and \fBOSSL_STORE_SEARCH_by_alias()\fR +return a \fBOSSL_STORE_SEARCH\fR pointer on success, or NULL on failure. +.PP +\&\fBOSSL_STORE_SEARCH_get_type()\fR returns the criterion type of the given +\&\fBOSSL_STORE_SEARCH\fR. +There is no error value. +.PP +\&\fBOSSL_STORE_SEARCH_get0_name()\fR returns a \fBX509_NAME\fR pointer on success, +or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type. +.PP +\&\fBOSSL_STORE_SEARCH_get0_serial()\fR returns a \fBASN1_INTEGER\fR pointer on success, +or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type. +.PP +\&\fBOSSL_STORE_SEARCH_get0_bytes()\fR returns a \fBconst unsigned char\fR pointer and +sets \fI*length\fR to the strings length on success, or NULL when the given +\&\fBOSSL_STORE_SEARCH\fR was of a different type. +.PP +\&\fBOSSL_STORE_SEARCH_get0_string()\fR returns a \fBconst char\fR pointer on success, +or NULL when the given \fBOSSL_STORE_SEARCH\fR was of a different type. +.PP +\&\fBOSSL_STORE_SEARCH_get0_digest()\fR returns a \fBconst EVP_MD\fR pointer. +NULL is a valid value and means that the store loader default will +be used when applicable. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_supports_search\fR\|(3), \fBOSSL_STORE_find\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_STORE_SEARCH\fR, +\&\fBOSSL_STORE_SEARCH_by_name()\fR, +\&\fBOSSL_STORE_SEARCH_by_issuer_serial()\fR, +\&\fBOSSL_STORE_SEARCH_by_key_fingerprint()\fR, +\&\fBOSSL_STORE_SEARCH_by_alias()\fR, +\&\fBOSSL_STORE_SEARCH_free()\fR, +\&\fBOSSL_STORE_SEARCH_get_type()\fR, +\&\fBOSSL_STORE_SEARCH_get0_name()\fR, +\&\fBOSSL_STORE_SEARCH_get0_serial()\fR, +\&\fBOSSL_STORE_SEARCH_get0_bytes()\fR, +and \fBOSSL_STORE_SEARCH_get0_string()\fR +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_attach.3 b/static/netbsd/man3/OSSL_STORE_attach.3 new file mode 100644 index 00000000..6bab24c3 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_attach.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: OSSL_STORE_attach.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_attach 3" +.TH OSSL_STORE_attach 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_attach \- Functions to read objects from a BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& OSSL_STORE_CTX *OSSL_STORE_attach(BIO *bio, const char *scheme, +\& OSSL_LIB_CTX *libctx, const char *propq, +\& const UI_METHOD *ui_method, void *ui_data, +\& const OSSL_PARAM params[], +\& OSSL_STORE_post_process_info_fn post_process, +\& void *post_process_data); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_STORE_attach()\fR works like \fBOSSL_STORE_open\fR\|(3), except it takes a \fBBIO\fR +\&\fIbio\fR instead of a \fIuri\fR, along with a \fIscheme\fR to determine what loader +should be used to process the data. The reference count of the \fBBIO\fR object +is increased by 1 if the call is successful. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_attach()\fR returns a pointer to a \fBOSSL_STORE_CTX\fR on success, or +NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_open\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_STORE_attach()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_expect.3 b/static/netbsd/man3/OSSL_STORE_expect.3 new file mode 100644 index 00000000..a2dbc3d8 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_expect.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: OSSL_STORE_expect.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_expect 3" +.TH OSSL_STORE_expect 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_expect, +OSSL_STORE_supports_search, +OSSL_STORE_find +\&\- Specify what object type is expected +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); +\& +\& int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type); +\& +\& int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_STORE_expect()\fR helps applications filter what \fBOSSL_STORE_load()\fR returns +by specifying a \fBOSSL_STORE_INFO\fR type. +By default, no expectations on the types of objects to be loaded are made. +\&\fIexpected_type\fR may be 0 to indicate explicitly that no expectation is made, +or it may be any of the known object types (see +"SUPPORTED OBJECTS" in \fBOSSL_STORE_INFO\fR\|(3)) except for \fBOSSL_STORE_INFO_NAME\fR. +For example, if \f(CW\*(C`file:/foo/bar/store.pem\*(C'\fR contains several objects of different +type and only certificates are interesting, the application can simply say +that it expects the type \fBOSSL_STORE_INFO_CERT\fR. +.PP +\&\fBOSSL_STORE_find()\fR helps applications specify a criterion for a more fine +grained search of objects. +.PP +\&\fBOSSL_STORE_supports_search()\fR checks if the loader of the given OSSL_STORE +context supports the given search type. +See "SUPPORTED CRITERION TYPES" in \fBOSSL_STORE_SEARCH\fR\|(3) for information on the +supported search criterion types. +.PP +\&\fBOSSL_STORE_expect()\fR and OSSL_STORE_find \fImust\fR be called before the first +\&\fBOSSL_STORE_load()\fR of a given session, or they will fail. +.SH NOTES +.IX Header "NOTES" +If a more elaborate filter is required by the application, a better choice +would be to use a post\-processing function. +See \fBOSSL_STORE_open\fR\|(3) for more information. +.PP +However, some loaders may take advantage of the knowledge of an expected type +to make object retrieval more efficient, so if a single type is expected, this +method is usually preferable. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_expect()\fR returns 1 on success, or 0 on failure. +.PP +\&\fBOSSL_STORE_supports_search()\fR returns 1 if the criterion is supported, or 0 +otherwise. +.PP +\&\fBOSSL_STORE_find()\fR returns 1 on success, or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_INFO\fR\|(3), \fBOSSL_STORE_SEARCH\fR\|(3), +\&\fBOSSL_STORE_load\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_STORE_expect()\fR, \fBOSSL_STORE_supports_search()\fR and \fBOSSL_STORE_find()\fR +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_STORE_open.3 b/static/netbsd/man3/OSSL_STORE_open.3 new file mode 100644 index 00000000..783ff0b5 --- /dev/null +++ b/static/netbsd/man3/OSSL_STORE_open.3 @@ -0,0 +1,244 @@ +.\" $NetBSD: OSSL_STORE_open.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_STORE_open 3" +.TH OSSL_STORE_open 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, +OSSL_STORE_open, OSSL_STORE_open_ex, +OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_delete, +OSSL_STORE_error, OSSL_STORE_close +\&\- Types and functions to read objects from a URI +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ossl_store_ctx_st OSSL_STORE_CTX; +\& +\& typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, +\& void *); +\& +\& OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, +\& void *ui_data, +\& OSSL_STORE_post_process_info_fn post_process, +\& void *post_process_data); +\& OSSL_STORE_CTX * +\& OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, +\& const UI_METHOD *ui_method, void *ui_data, +\& const OSSL_PARAM params[], +\& OSSL_STORE_post_process_info_fn post_process, +\& void *post_process_data); +\& +\& OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); +\& int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); +\& int OSSL_STORE_delete(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, +\& const UI_METHOD *ui_method, void *ui_data, +\& const OSSL_PARAM params[]); +\& int OSSL_STORE_error(OSSL_STORE_CTX *ctx); +\& int OSSL_STORE_close(OSSL_STORE_CTX *ctx); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions help the application to fetch supported objects (see +"SUPPORTED OBJECTS" in \fBOSSL_STORE_INFO\fR\|(3) for information on which those are) +from a given URI. +The general method to do so is to "open" the URI using \fBOSSL_STORE_open()\fR, +read each available and supported object using \fBOSSL_STORE_load()\fR as long as +\&\fBOSSL_STORE_eof()\fR hasn\*(Aqt been reached, and finish it off with \fBOSSL_STORE_close()\fR. +.PP +The retrieved information is stored in a \fBOSSL_STORE_INFO\fR, which is further +described in \fBOSSL_STORE_INFO\fR\|(3). +.SS Types +.IX Subsection "Types" +\&\fBOSSL_STORE_CTX\fR is a context variable that holds all the internal +information for \fBOSSL_STORE_open()\fR, \fBOSSL_STORE_open_ex()\fR, +\&\fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR to work +together. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_STORE_open_ex()\fR takes a uri or path \fIuri\fR, password UI method +\&\fIui_method\fR with associated data \fIui_data\fR, and post processing +callback \fIpost_process\fR with associated data \fIpost_process_data\fR, +a library context \fIlibctx\fR with an associated property query \fIpropq\fR, +and opens a channel to the data located at the URI and returns a +\&\fBOSSL_STORE_CTX\fR with all necessary internal information. +The given \fIui_method\fR and \fIui_data\fR will be reused by all +functions that use \fBOSSL_STORE_CTX\fR when interaction is needed, +for instance to provide a password. +The auxiliary \fBOSSL_PARAM\fR\|(3) parameters in \fIparams\fR can be set to further +modify the store operation. +The given \fIpost_process\fR and \fIpost_process_data\fR will be reused by +\&\fBOSSL_STORE_load()\fR to manipulate or drop the value to be returned. +The \fIpost_process\fR function drops values by returning NULL, which +will cause \fBOSSL_STORE_load()\fR to start its process over with loading +the next object, until \fIpost_process\fR returns something other than +NULL, or the end of data is reached as indicated by \fBOSSL_STORE_eof()\fR. +.PP +\&\fBOSSL_STORE_open()\fR is similar to \fBOSSL_STORE_open_ex()\fR but uses NULL for +the \fIparams\fR, the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBOSSL_STORE_ctrl()\fR takes a \fBOSSL_STORE_CTX\fR, and command number \fIcmd\fR and +more arguments not specified here. +The available loader specific command numbers and arguments they each +take depends on the loader that\*(Aqs used and is documented together with +that loader. +.PP +There are also global controls available: +.IP \fBOSSL_STORE_C_USE_SECMEM\fR 4 +.IX Item "OSSL_STORE_C_USE_SECMEM" +Controls if the loader should attempt to use secure memory for any +allocated \fBOSSL_STORE_INFO\fR and its contents. +This control expects one argument, a pointer to an \fIint\fR that is expected to +have the value 1 (yes) or 0 (no). +Any other value is an error. +.PP +\&\fBOSSL_STORE_load()\fR takes a \fBOSSL_STORE_CTX\fR and tries to load the next +available object and return it wrapped with \fBOSSL_STORE_INFO\fR. +.PP +\&\fBOSSL_STORE_delete()\fR deletes the object identified by \fIuri\fR. +.PP +\&\fBOSSL_STORE_eof()\fR takes a \fBOSSL_STORE_CTX\fR and checks if we\*(Aqve reached the end +of data. +.PP +\&\fBOSSL_STORE_error()\fR takes a \fBOSSL_STORE_CTX\fR and checks if an error occurred in +the last \fBOSSL_STORE_load()\fR call. +Note that it may still be meaningful to try and load more objects, unless +\&\fBOSSL_STORE_eof()\fR shows that the end of data has been reached. +.PP +\&\fBOSSL_STORE_close()\fR takes a \fBOSSL_STORE_CTX\fR, closes the channel that was opened +by \fBOSSL_STORE_open()\fR and frees all other information that was stored in the +\&\fBOSSL_STORE_CTX\fR, as well as the \fBOSSL_STORE_CTX\fR itself. +If \fIctx\fR is NULL it does nothing. +.SH NOTES +.IX Header "NOTES" +A string without a scheme prefix (that is, a non\-URI string) is +implicitly interpreted as using the \fIfile:\fR scheme. +.PP +There are some tools that can be used together with +\&\fBOSSL_STORE_open()\fR to determine if any failure is caused by an unparsable +URI, or if it\*(Aqs a different error (such as memory allocation +failures); if the URI was parsable but the scheme unregistered, the +top error will have the reason \f(CW\*(C`OSSL_STORE_R_UNREGISTERED_SCHEME\*(C'\fR. +.PP +These functions make no direct assumption regarding the pass phrase received +from the password callback. +The loaders may make assumptions, however. +For example, the \fBfile:\fR scheme loader inherits the assumptions made by +OpenSSL functionality that handles the different file types; this is mostly +relevant for PKCS#12 objects. +See \fBpassphrase\-encoding\fR\|(7) for further information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_STORE_open()\fR returns a pointer to a \fBOSSL_STORE_CTX\fR on success, or +NULL on failure. +.PP +\&\fBOSSL_STORE_load()\fR returns a pointer to a \fBOSSL_STORE_INFO\fR on success, or NULL +on error or when end of data is reached. +Use \fBOSSL_STORE_error()\fR and \fBOSSL_STORE_eof()\fR to determine the meaning of a +returned NULL. +.PP +\&\fBOSSL_STORE_eof()\fR returns 1 if the end of data has been reached +or an error occurred, 0 otherwise. +.PP +\&\fBOSSL_STORE_error()\fR returns 1 if an error occurred in an \fBOSSL_STORE_load()\fR call, +otherwise 0. +.PP +\&\fBOSSL_STORE_delete()\fR, \fBOSSL_STORE_ctrl()\fR and \fBOSSL_STORE_close()\fR return 1 on +success, or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl_store\fR\|(7), \fBOSSL_STORE_INFO\fR\|(3), \fBOSSL_STORE_register_loader\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_STORE_delete()\fR was added in OpenSSL 3.2. +.PP +\&\fBOSSL_STORE_open_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBOSSL_STORE_CTX\fR, \fBOSSL_STORE_post_process_info_fn()\fR, \fBOSSL_STORE_open()\fR, +\&\fBOSSL_STORE_ctrl()\fR, \fBOSSL_STORE_load()\fR, \fBOSSL_STORE_eof()\fR and \fBOSSL_STORE_close()\fR +were added in OpenSSL 1.1.1. +.PP +Handling of NULL \fIctx\fR argument for \fBOSSL_STORE_close()\fR +was introduced in OpenSSL 1.1.1h. +.PP +\&\fBOSSL_STORE_ctrl()\fR and \fBOSSL_STORE_vctrl()\fR were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_sleep.3 b/static/netbsd/man3/OSSL_sleep.3 new file mode 100644 index 00000000..c5b49496 --- /dev/null +++ b/static/netbsd/man3/OSSL_sleep.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: OSSL_sleep.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_sleep 3" +.TH OSSL_sleep 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_sleep \- delay execution for a specified number of milliseconds +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void OSSL_sleep(uint64_t millis); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_sleep()\fR is a convenience function to delay execution of the calling +thread for (at least) \fImillis\fR milliseconds. The delay is not guaranteed; +it may be affected by system activity, by the time spent processing the call, +limitation on the underlying system call parameter size or by system timer +granularity. +.PP +In particular on Windows the maximum amount of time it will sleep is +49 days and on systems where the regular \fBsleep\fR\|(3) is used as the underlying +system call the maximum sleep time is about 136 years. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_sleep()\fR does not return any value. +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_sleep()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_trace_enabled.3 b/static/netbsd/man3/OSSL_trace_enabled.3 new file mode 100644 index 00000000..c713b471 --- /dev/null +++ b/static/netbsd/man3/OSSL_trace_enabled.3 @@ -0,0 +1,393 @@ +.\" $NetBSD: OSSL_trace_enabled.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_trace_enabled 3" +.TH OSSL_trace_enabled 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, +OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL, +OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, +OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, +OSSL_TRACEV, +OSSL_TRACE_STRING, OSSL_TRACE_STRING_MAX, OSSL_trace_string, +OSSL_TRACE_ENABLED +\&\- OpenSSL Tracing API +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_trace_enabled(int category); +\& +\& BIO *OSSL_trace_begin(int category); +\& void OSSL_trace_end(int category, BIO *channel); +\& +\& /* trace group macros */ +\& OSSL_TRACE_BEGIN(category) { +\& ... +\& if (some_error) { +\& /* Leave trace group prematurely in case of an error */ +\& OSSL_TRACE_CANCEL(category); +\& goto err; +\& } +\& ... +\& } OSSL_TRACE_END(category); +\& +\& /* one\-shot trace macros */ +\& OSSL_TRACE(category, text) +\& OSSL_TRACE1(category, format, arg1) +\& OSSL_TRACE2(category, format, arg1, arg2) +\& ... +\& OSSL_TRACE9(category, format, arg1, ..., arg9) +\& OSSL_TRACE_STRING(category, text, full, data, len) +\& +\& #define OSSL_TRACE_STRING_MAX 80 +\& int OSSL_trace_string(BIO *out, int text, int full, +\& const unsigned char *data, size_t size); +\& +\& /* check whether a trace category is enabled */ +\& if (OSSL_TRACE_ENABLED(category)) { +\& ... +\& } +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described here are mainly interesting for those who provide +OpenSSL functionality, either in OpenSSL itself or in engine modules +or similar. +.PP +If the tracing facility is enabled (see "Configure Tracing" below), +these functions are used to generate free text tracing output. +.PP +The tracing output is divided into types which are enabled +individually by the application. +The tracing types are described in detail in +"Trace types" in \fBOSSL_trace_set_callback\fR\|(3). +The fallback type \fBOSSL_TRACE_CATEGORY_ALL\fR should \fInot\fR be used +with the functions described here. +.PP +Tracing for a specific category is enabled at run\-time if a so\-called +\&\fItrace channel\fR is attached to it. A trace channel is simply a +BIO object to which the application can write its trace output. +.PP +The application has two different ways of registering a trace channel, +either by directly providing a BIO object using \fBOSSL_trace_set_channel\fR\|(3), +or by providing a callback routine using \fBOSSL_trace_set_callback\fR\|(3). +The latter is wrapped internally by a dedicated BIO object, so for the +tracing code both channel types are effectively indistinguishable. +We call them a \fIsimple trace channel\fR and a \fIcallback trace channel\fR, +respectively. +.PP +To produce trace output, it is necessary to obtain a pointer to the +trace channel (i.e., the BIO object) using \fBOSSL_trace_begin()\fR, write +to it using arbitrary BIO output routines, and finally releases the +channel using \fBOSSL_trace_end()\fR. The \fBOSSL_trace_begin()\fR/\fBOSSL_trace_end()\fR +calls surrounding the trace output create a group, which acts as a +critical section (guarded by a mutex) to ensure that the trace output +of different threads does not get mixed up. +.PP +The tracing code normally does not call OSSL_trace_{begin,end}() directly, +but rather uses a set of convenience macros, see the "Macros" section below. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_trace_enabled()\fR can be used to check if tracing for the given +\&\fIcategory\fR is enabled, i.e., if the tracing facility has been statically +enabled (see "Configure Tracing" below) and a trace channel has been +registered using \fBOSSL_trace_set_channel\fR\|(3) or \fBOSSL_trace_set_callback\fR\|(3). +.PP +\&\fBOSSL_trace_begin()\fR is used to start a tracing section, +and get the channel for the given \fIcategory\fR in form of a BIO. +This BIO can only be used for output. +The pointer returned is NULL if the category is invalid or not enabled. +.PP +\&\fBOSSL_trace_end()\fR is used to end a tracing section. +.PP +Using \fBOSSL_trace_begin()\fR and \fBOSSL_trace_end()\fR to wrap tracing sections +is \fImandatory\fR. +The result of trying to produce tracing output outside of such +sections is undefined. +.PP +\&\fBOSSL_trace_string()\fR outputs \fIdata\fR of length \fIsize\fR as a string on BIO \fIout\fR. +If \fItext\fR is 0, the function masks any included control characters apart from +newlines and makes sure for nonempty input that the output ends with a newline. +Unless \fIfull\fR is nonzero, the length is limited (with a suitable warning) +to \fBOSSL_TRACE_STRING_MAX\fR characters, which currently is 80. +.SS Macros +.IX Subsection "Macros" +There are a number of convenience macros defined, to make tracing +easy and consistent. +.PP +\&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR reserve the \fBBIO\fR \f(CW\*(C`trc_out\*(C'\fR and are +used as follows to wrap a trace section: +.PP +.Vb 1 +\& OSSL_TRACE_BEGIN(TLS) { +\& +\& BIO_printf(trc_out, ... ); +\& +\& } OSSL_TRACE_END(TLS); +.Ve +.PP +This will normally expand to: +.PP +.Vb 8 +\& do { +\& BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); +\& if (trc_out != NULL) { +\& ... +\& BIO_printf(trc_out, ...); +\& } +\& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); +\& } while (0); +.Ve +.PP +\&\fBOSSL_TRACE_CANCEL()\fR must be used before returning from or jumping out of a +trace section: +.PP +.Vb 1 +\& OSSL_TRACE_BEGIN(TLS) { +\& +\& if (some_error) { +\& OSSL_TRACE_CANCEL(TLS); +\& goto err; +\& } +\& BIO_printf(trc_out, ... ); +\& +\& } OSSL_TRACE_END(TLS); +.Ve +.PP +This will normally expand to: +.PP +.Vb 11 +\& do { +\& BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); +\& if (trc_out != NULL) { +\& if (some_error) { +\& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); +\& goto err; +\& } +\& BIO_printf(trc_out, ... ); +\& } +\& OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); +\& } while (0); +.Ve +.PP +\&\fBOSSL_TRACE()\fR and \fBOSSL_TRACE1()\fR, \fBOSSL_TRACE2()\fR, ... \fBOSSL_TRACE9()\fR are +so\-called one\-shot macros: +.PP +The macro call \f(CW\*(C`OSSL_TRACE(category, text)\*(C'\fR, produces literal text trace output. +.PP +The macro call \f(CW\*(C`OSSL_TRACEn(category, format, arg1, ..., argn)\*(C'\fR produces +printf\-style trace output with n format field arguments (n=1,...,9). +It expands to: +.PP +.Vb 3 +\& OSSL_TRACE_BEGIN(category) { +\& BIO_printf(trc_out, format, arg1, ..., argN); +\& } OSSL_TRACE_END(category) +.Ve +.PP +Internally, all one\-shot macros are implemented using a generic \fBOSSL_TRACEV()\fR +macro, since C90 does not support variadic macros. This helper macro has a rather +weird synopsis and should not be used directly. +.PP +The macro call \f(CW\*(C`OSSL_TRACE_STRING(category, text, full, data, len)\*(C'\fR +outputs \fIdata\fR of length \fIsize\fR as a string +if tracing for the given \fIcategory\fR is enabled. +It expands to: +.PP +.Vb 3 +\& OSSL_TRACE_BEGIN(category) { +\& OSSL_trace_string(trc_out, text, full, data, len); +\& } OSSL_TRACE_END(category) +.Ve +.PP +The \fBOSSL_TRACE_ENABLED()\fR macro can be used to conditionally execute some code +only if a specific trace category is enabled. +In some situations this is simpler than entering a trace section using +\&\fBOSSL_TRACE_BEGIN()\fR and \fBOSSL_TRACE_END()\fR. +For example, the code +.PP +.Vb 3 +\& if (OSSL_TRACE_ENABLED(TLS)) { +\& ... +\& } +.Ve +.PP +expands to +.PP +.Vb 3 +\& if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) { +\& ... +\& } +.Ve +.SH NOTES +.IX Header "NOTES" +It is not needed to guard trace output function calls like +\&\fIOSSL_TRACE(category, ...)\fR by \fIOSSL_TRACE_ENABLED(category)\fR. +.PP +If producing the trace output requires carrying out auxiliary calculations, +this auxiliary code should be placed inside a conditional block which is +executed only if the trace category is enabled. +.PP +The most natural way to do this is to place the code inside the trace section +itself because it already introduces such a conditional block. +.PP +.Vb 2 +\& OSSL_TRACE_BEGIN(TLS) { +\& int var = do_some_auxiliary_calculation(); +\& +\& BIO_printf(trc_out, "var = %d\en", var); +\& +\& } OSSL_TRACE_END(TLS); +.Ve +.PP +In some cases it is more advantageous to use a simple conditional group instead +of a trace section. This is the case if calculations and tracing happen in +different locations of the code, or if the calculations are so time consuming +that placing them inside a (critical) trace section would create too much +contention. +.PP +.Vb 2 +\& if (OSSL_TRACE_ENABLED(TLS)) { +\& int var = do_some_auxiliary_calculation(); +\& +\& OSSL_TRACE1("var = %d\en", var); +\& } +.Ve +.PP +Note however that premature optimization of tracing code is in general futile +and it\*(Aqs better to keep the tracing code as simple as possible. +Because most often the limiting factor for the application\*(Aqs speed is the time +it takes to print the trace output, not to calculate it. +.SS "Configure Tracing" +.IX Subsection "Configure Tracing" +By default, the OpenSSL library is built with tracing disabled. To +use the tracing functionality documented here, it is therefore +necessary to configure and build OpenSSL with the \*(Aqenable\-trace\*(Aq option. +.PP +When the library is built with tracing disabled: +.IP \(bu 4 +The macro \fBOPENSSL_NO_TRACE\fR is defined in \fI\fR. +.IP \(bu 4 +all functions are still present, but \fBOSSL_trace_enabled()\fR will always +report the categories as disabled, and all other functions will do +nothing. +.IP \(bu 4 +the convenience macros are defined to produce dead code. +For example, take this example from "Macros" section above: +.Sp +.Vb 1 +\& OSSL_TRACE_BEGIN(TLS) { +\& +\& if (condition) { +\& OSSL_TRACE_CANCEL(TLS); +\& goto err; +\& } +\& BIO_printf(trc_out, ... ); +\& +\& } OSSL_TRACE_END(TLS); +.Ve +.Sp +When the tracing API isn\*(Aqt operational, that will expand to: +.Sp +.Vb 10 +\& do { +\& BIO *trc_out = NULL; +\& if (0) { +\& if (condition) { +\& ((void)0); +\& goto err; +\& } +\& BIO_printf(trc_out, ... ); +\& } +\& } while (0); +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_trace_enabled()\fR returns 1 if tracing for the given \fItype\fR is +operational and enabled, otherwise 0. +.PP +\&\fBOSSL_trace_begin()\fR returns a \fBBIO\fR pointer if the given \fItype\fR is enabled, +otherwise NULL. +.PP +\&\fBOSSL_trace_string()\fR returns the number of characters emitted, or \-1 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_trace_set_channel\fR\|(3), \fBOSSL_trace_set_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL Tracing API was added in OpenSSL 3.0. +.PP +\&\fBOSSL_TRACE_STRING()\fR, OSSL_TRACE_STRING_MAX, and OSSL_trace_string +were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_trace_get_category_num.3 b/static/netbsd/man3/OSSL_trace_get_category_num.3 new file mode 100644 index 00000000..ca3ca2f2 --- /dev/null +++ b/static/netbsd/man3/OSSL_trace_get_category_num.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: OSSL_trace_get_category_num.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_trace_get_category_num 3" +.TH OSSL_trace_get_category_num 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_trace_get_category_num, OSSL_trace_get_category_name +\&\- OpenSSL tracing information functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int OSSL_trace_get_category_num(const char *name); +\& const char *OSSL_trace_get_category_name(int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBOSSL_trace_get_category_num()\fR gives the category number corresponding +to the given \f(CW\*(C`name\*(C'\fR. +.PP +\&\fBOSSL_trace_get_category_name()\fR gives the category name corresponding +to the given \f(CW\*(C`num\*(C'\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_trace_get_category_num()\fR returns the category number if the given +\&\f(CW\*(C`name\*(C'\fR is a recognised category name, otherwise \-1. +.PP +\&\fBOSSL_trace_get_category_name()\fR returns the category name if the given +\&\f(CW\*(C`num\*(C'\fR is a recognised category number, otherwise NULL. +.SH HISTORY +.IX Header "HISTORY" +The OpenSSL Tracing API was added ino OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OSSL_trace_set_channel.3 b/static/netbsd/man3/OSSL_trace_set_channel.3 new file mode 100644 index 00000000..d80d5192 --- /dev/null +++ b/static/netbsd/man3/OSSL_trace_set_channel.3 @@ -0,0 +1,376 @@ +.\" $NetBSD: OSSL_trace_set_channel.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_trace_set_channel 3" +.TH OSSL_trace_set_channel 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix, +OSSL_trace_set_callback, OSSL_trace_cb \- Enabling trace output +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt, +\& int category, int cmd, void *data); +\& +\& void OSSL_trace_set_channel(int category, BIO *bio); +\& void OSSL_trace_set_prefix(int category, const char *prefix); +\& void OSSL_trace_set_suffix(int category, const char *suffix); +\& void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void *data); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +If available (see "Configure Tracing" below), the application can request +internal trace output. +This output comes in form of free text for humans to read. +.PP +The trace output is divided into categories which can be +enabled individually. +Every category can be enabled individually by attaching a so\-called +\&\fItrace channel\fR to it, which in the simplest case is just a BIO object +to which the application can write the tracing output for this category. +Alternatively, the application can provide a tracer callback in order to +get more finegrained trace information. This callback will be wrapped +internally by a dedicated BIO object. +.PP +For the tracing code, both trace channel types are indistinguishable. +These are called a \fIsimple trace channel\fR and a \fIcallback trace channel\fR, +respectively. +.PP +\&\fBOSSL_TRACE_ENABLED\fR\|(3) can be used to check whether tracing is currently +enabled for the given category. +Functions like \fBOSSL_TRACE1\fR\|(3) and macros like \fBOSSL_TRACE_BEGIN\fR\|(3) +can be used for producing free\-text trace output. +.SS Functions +.IX Subsection "Functions" +\&\fBOSSL_trace_set_channel()\fR is used to enable the given trace \f(CW\*(C`category\*(C'\fR +by attaching the \fBBIO\fR \fIbio\fR object as (simple) trace channel. +On success the ownership of the BIO is transferred to the channel, +so the caller must not free it directly. +.PP +\&\fBOSSL_trace_set_prefix()\fR and \fBOSSL_trace_set_suffix()\fR can be used to add +an extra line for each channel, to be output before and after group of +tracing output. +What constitutes an output group is decided by the code that produces +the output. +The lines given here are considered immutable; for more dynamic +tracing prefixes, consider setting a callback with +\&\fBOSSL_trace_set_callback()\fR instead. +.PP +\&\fBOSSL_trace_set_callback()\fR is used to enable the given trace +\&\fIcategory\fR by giving it the tracer callback \fIcb\fR with the associated +data \fIdata\fR, which will simply be passed through to \fIcb\fR whenever +it\*(Aqs called. The callback function is internally wrapped by a +dedicated BIO object, the so\-called \fIcallback trace channel\fR. +This should be used when it\*(Aqs desirable to do form the trace output to +something suitable for application needs where a prefix and suffix +line aren\*(Aqt enough. +.PP +\&\fBOSSL_trace_set_channel()\fR and \fBOSSL_trace_set_callback()\fR are mutually +exclusive, calling one of them will clear whatever was set by the +previous call. +.PP +Calling \fBOSSL_trace_set_channel()\fR with NULL for \fIchannel\fR or +\&\fBOSSL_trace_set_callback()\fR with NULL for \fIcb\fR disables tracing for +the given \fIcategory\fR. +.SS "Trace callback" +.IX Subsection "Trace callback" +The tracer callback must return a \fBsize_t\fR, which must be zero on +error and otherwise return the number of bytes that were output. +It receives a text buffer \fIbuf\fR with \fIcnt\fR bytes of text, as well as +the \fIcategory\fR, a control number \fIcmd\fR, and the \fIdata\fR that was +passed to \fBOSSL_trace_set_callback()\fR. +.PP +The possible control numbers are: +.IP \fBOSSL_TRACE_CTRL_BEGIN\fR 4 +.IX Item "OSSL_TRACE_CTRL_BEGIN" +The callback is called from \fBOSSL_trace_begin()\fR, which gives the +callback the possibility to output a dynamic starting line, or set a +prefix that should be output at the beginning of each line, or +something other. +.IP \fBOSSL_TRACE_CTRL_WRITE\fR 4 +.IX Item "OSSL_TRACE_CTRL_WRITE" +This callback is called whenever data is written to the BIO by some +regular BIO output routine. +An arbitrary number of \fBOSSL_TRACE_CTRL_WRITE\fR callbacks can occur +inside a group marked by a pair of \fBOSSL_TRACE_CTRL_BEGIN\fR and +\&\fBOSSL_TRACE_CTRL_END\fR calls, but never outside such a group. +.IP \fBOSSL_TRACE_CTRL_END\fR 4 +.IX Item "OSSL_TRACE_CTRL_END" +The callback is called from \fBOSSL_trace_end()\fR, which gives the callback +the possibility to output a dynamic ending line, or reset the line +prefix that was set with \fBOSSL_TRACE_CTRL_BEGIN\fR, or something other. +.SS "Trace categories" +.IX Subsection "Trace categories" +The trace categories are simple numbers available through macros. +.IP \fBOSSL_TRACE_CATEGORY_TRACE\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_TRACE" +Traces the OpenSSL trace API itself. +.Sp +More precisely, this will generate trace output any time a new +trace hook is set. +.IP \fBOSSL_TRACE_CATEGORY_INIT\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_INIT" +Traces OpenSSL library initialization and cleanup. +.Sp +This needs special care, as OpenSSL will do automatic cleanup after +exit from \f(CWmain()\fR, and any tracing output done during this cleanup +will be lost if the tracing channel or callback were cleaned away +prematurely. +A suggestion is to make such cleanup part of a function that\*(Aqs +registered very early with \fBatexit\fR\|(3). +.IP \fBOSSL_TRACE_CATEGORY_TLS\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_TLS" +Traces the TLS/SSL protocol. +.IP \fBOSSL_TRACE_CATEGORY_TLS_CIPHER\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_TLS_CIPHER" +Traces the ciphers used by the TLS/SSL protocol. +.IP \fBOSSL_TRACE_CATEGORY_CONF\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_CONF" +Traces details about the provider and engine configuration. +.IP \fBOSSL_TRACE_CATEGORY_ENGINE_TABLE\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_ENGINE_TABLE" +Traces the ENGINE algorithm table selection. +.Sp +More precisely, functions like \fBENGINE_get_pkey_asn1_meth_engine()\fR, +\&\fBENGINE_get_pkey_meth_engine()\fR, \fBENGINE_get_cipher_engine()\fR, +\&\fBENGINE_get_digest_engine()\fR, will generate trace summaries of the +handling of internal tables. +.IP \fBOSSL_TRACE_CATEGORY_ENGINE_REF_COUNT\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT" +Traces the ENGINE reference counting. +.Sp +More precisely, both reference counts in the ENGINE structure will be +monitored with a line of trace output generated for each change. +.IP \fBOSSL_TRACE_CATEGORY_PKCS5V2\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_PKCS5V2" +Traces PKCS#5 v2 key generation. +.IP \fBOSSL_TRACE_CATEGORY_PKCS12_KEYGEN\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_PKCS12_KEYGEN" +Traces PKCS#12 key generation. +.IP \fBOSSL_TRACE_CATEGORY_PKCS12_DECRYPT\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_PKCS12_DECRYPT" +Traces PKCS#12 decryption. +.IP \fBOSSL_TRACE_CATEGORY_X509V3_POLICY\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_X509V3_POLICY" +Traces X509v3 policy processing. +.Sp +More precisely, this generates the complete policy tree at various +point during evaluation. +.IP \fBOSSL_TRACE_CATEGORY_BN_CTX\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_BN_CTX" +Traces BIGNUM context operations. +.IP \fBOSSL_TRACE_CATEGORY_CMP\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_CMP" +Traces CMP client and server activity. +.IP \fBOSSL_TRACE_CATEGORY_STORE\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_STORE" +Traces STORE operations. +.IP \fBOSSL_TRACE_CATEGORY_DECODER\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_DECODER" +Traces decoder operations. +.IP \fBOSSL_TRACE_CATEGORY_ENCODER\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_ENCODER" +Traces encoder operations. +.IP \fBOSSL_TRACE_CATEGORY_REF_COUNT\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_REF_COUNT" +Traces decrementing certain ASN.1 structure references. +.IP \fBOSSL_TRACE_CATEGORY_HTTP\fR 4 +.IX Item "OSSL_TRACE_CATEGORY_HTTP" +Traces the HTTP client, such as message headers being sent and received. +.PP +There is also \fBOSSL_TRACE_CATEGORY_ALL\fR, which works as a fallback +and can be used to get \fIall\fR trace output. +.PP +Note, however, that in this case all trace output will effectively be +associated with the \*(AqALL\*(Aq category, which is undesirable if the +application intends to include the category name in the trace output. +In this case it is better to register separate channels for each +trace category instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOSSL_trace_set_channel()\fR, \fBOSSL_trace_set_prefix()\fR, +\&\fBOSSL_trace_set_suffix()\fR, and \fBOSSL_trace_set_callback()\fR return 1 on +success, or 0 on failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +In all examples below, the trace producing code is assumed to be +the following: +.PP +.Vb 3 +\& int foo = 42; +\& const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7, +\& 8, 9, 10, 11, 12, 13, 14, 15 }; +\& +\& OSSL_TRACE_BEGIN(TLS) { +\& BIO_puts(trc_out, "foo: "); +\& BIO_printf(trc_out, "%d\en", foo); +\& BIO_dump(trc_out, bar, sizeof(bar)); +\& } OSSL_TRACE_END(TLS); +.Ve +.SS "Simple example" +.IX Subsection "Simple example" +An example with just a channel and constant prefix / suffix. +.PP +.Vb 6 +\& int main(int argc, char *argv[]) +\& { +\& BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT); +\& OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err); +\& OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]"); +\& OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]"); +\& +\& /* ... work ... */ +\& } +.Ve +.PP +When the trace producing code above is performed, this will be output +on standard error: +.PP +.Vb 4 +\& BEGIN TRACE[TLS] +\& foo: 42 +\& 0000 \- 00 01 02 03 04 05 06 07\-08 09 0a 0b 0c 0d 0e 0f ................ +\& END TRACE[TLS] +.Ve +.SS "Advanced example" +.IX Subsection "Advanced example" +This example uses the callback, and depends on pthreads functionality. +.PP +.Vb 5 +\& static size_t cb(const char *buf, size_t cnt, +\& int category, int cmd, void *vdata) +\& { +\& BIO *bio = vdata; +\& const char *label = NULL; +\& +\& switch (cmd) { +\& case OSSL_TRACE_CTRL_BEGIN: +\& label = "BEGIN"; +\& break; +\& case OSSL_TRACE_CTRL_END: +\& label = "END"; +\& break; +\& } +\& +\& if (label != NULL) { +\& union { +\& pthread_t tid; +\& unsigned long ltid; +\& } tid; +\& +\& tid.tid = pthread_self(); +\& BIO_printf(bio, "%s TRACE[%s]:%lx\en", +\& label, OSSL_trace_get_category_name(category), tid.ltid); +\& } +\& return (size_t)BIO_puts(bio, buf); +\& } +\& +\& int main(int argc, char *argv[]) +\& { +\& BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT); +\& OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err); +\& +\& /* ... work ... */ +\& } +.Ve +.PP +The output is almost the same as for the simple example above. +.PP +.Vb 4 +\& BEGIN TRACE[TLS]:7f9eb0193b80 +\& foo: 42 +\& 0000 \- 00 01 02 03 04 05 06 07\-08 09 0a 0b 0c 0d 0e 0f ................ +\& END TRACE[TLS]:7f9eb0193b80 +.Ve +.SH NOTES +.IX Header "NOTES" +.SS "Configure Tracing" +.IX Subsection "Configure Tracing" +By default, the OpenSSL library is built with tracing disabled. To +use the tracing functionality documented here, it is therefore +necessary to configure and build OpenSSL with the \*(Aqenable\-trace\*(Aq option. +.PP +When the library is built with tracing disabled, the macro +\&\fBOPENSSL_NO_TRACE\fR is defined in \fI\fR and all +functions described here are inoperational, i.e. will do nothing. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_TRACE_ENABLED\fR\|(3), \fBOSSL_TRACE_BEGIN\fR\|(3), \fBOSSL_TRACE1\fR\|(3), +\&\fBatexit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_trace_set_channel()\fR, \fBOSSL_trace_set_prefix()\fR, +\&\fBOSSL_trace_set_suffix()\fR, and \fBOSSL_trace_set_callback()\fR were all added +in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OpenSSL_add_all_algorithms.3 b/static/netbsd/man3/OpenSSL_add_all_algorithms.3 new file mode 100644 index 00000000..ad0add01 --- /dev/null +++ b/static/netbsd/man3/OpenSSL_add_all_algorithms.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: OpenSSL_add_all_algorithms.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OpenSSL_add_all_algorithms 3" +.TH OpenSSL_add_all_algorithms 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup \- +add algorithms to internal table +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& void OpenSSL_add_all_algorithms(void); +\& void OpenSSL_add_all_ciphers(void); +\& void OpenSSL_add_all_digests(void); +\& +\& void EVP_cleanup(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL keeps an internal table of digest algorithms and ciphers. It uses +this table to lookup ciphers via functions such as \fBEVP_get_cipher_byname()\fR. +.PP +\&\fBOpenSSL_add_all_digests()\fR adds all digest algorithms to the table. +.PP +\&\fBOpenSSL_add_all_algorithms()\fR adds all algorithms to the table (digests and +ciphers). +.PP +\&\fBOpenSSL_add_all_ciphers()\fR adds all encryption algorithms to the table including +password based encryption algorithms. +.PP +In versions prior to 1.1.0 \fBEVP_cleanup()\fR removed all ciphers and digests from +the table. It no longer has any effect in OpenSSL 1.1.0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +None of the functions return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), \fBEVP_DigestInit\fR\|(3), +\&\fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBOpenSSL_add_all_algorithms()\fR, \fBOpenSSL_add_all_ciphers()\fR, +\&\fBOpenSSL_add_all_digests()\fR, and \fBEVP_cleanup()\fR, functions +were deprecated in OpenSSL 1.1.0 by \fBOPENSSL_init_crypto()\fR and should +not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/OpenSSL_add_all_algorithms_conf.3 b/static/netbsd/man3/OpenSSL_add_all_algorithms_conf.3 new file mode 100644 index 00000000..b2310ca8 --- /dev/null +++ b/static/netbsd/man3/OpenSSL_add_all_algorithms_conf.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: OpenSSL_add_all_algorithms_conf.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_core.3 diff --git a/static/netbsd/man3/OpenSSL_add_all_algorithms_noconf.3 b/static/netbsd/man3/OpenSSL_add_all_algorithms_noconf.3 new file mode 100644 index 00000000..4578e4d0 --- /dev/null +++ b/static/netbsd/man3/OpenSSL_add_all_algorithms_noconf.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: OpenSSL_add_all_algorithms_noconf.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_core.3 diff --git a/static/netbsd/man3/OpenSSL_version.3 b/static/netbsd/man3/OpenSSL_version.3 new file mode 100644 index 00000000..d05dfc3a --- /dev/null +++ b/static/netbsd/man3/OpenSSL_version.3 @@ -0,0 +1,297 @@ +.\" $NetBSD: OpenSSL_version.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OpenSSL_version 3" +.TH OpenSSL_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR, OPENSSL_VERSION_PATCH, +OPENSSL_VERSION_PRE_RELEASE, OPENSSL_VERSION_BUILD_METADATA, +OPENSSL_VERSION_TEXT, OPENSSL_VERSION_PREREQ, OPENSSL_version_major, +OPENSSL_version_minor, OPENSSL_version_patch, OPENSSL_version_pre_release, +OPENSSL_version_build_metadata, OpenSSL_version, OPENSSL_VERSION_NUMBER, +OpenSSL_version_num, OPENSSL_info +\&\- get OpenSSL version number and other information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define OPENSSL_VERSION_MAJOR x +\& #define OPENSSL_VERSION_MINOR y +\& #define OPENSSL_VERSION_PATCH z +\& +\& /* The definitions here are typical release values */ +\& #define OPENSSL_VERSION_PRE_RELEASE "" +\& #define OPENSSL_VERSION_BUILD_METADATA "" +\& +\& #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx" +\& +\& #define OPENSSL_VERSION_PREREQ(maj,min) +\& +\& #include +\& +\& unsigned int OPENSSL_version_major(void); +\& unsigned int OPENSSL_version_minor(void); +\& unsigned int OPENSSL_version_patch(void); +\& const char *OPENSSL_version_pre_release(void); +\& const char *OPENSSL_version_build_metadata(void); +\& +\& const char *OpenSSL_version(int t); +\& +\& const char *OPENSSL_info(int t); +\& +\& /* from openssl/opensslv.h */ +\& #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnL +\& +\& /* from openssl/crypto.h */ +\& unsigned long OpenSSL_version_num(); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS Macros +.IX Subsection "Macros" +The three macros \fBOPENSSL_VERSION_MAJOR\fR, \fBOPENSSL_VERSION_MINOR\fR and +\&\fBOPENSSL_VERSION_PATCH\fR represent the three parts of a version +identifier, \fR\f(BIMAJOR\fR\fB.\fR\f(BIMINOR\fR\fB.\fR\f(BIPATCH\fR\fB\fR. +.PP +The macro \fBOPENSSL_VERSION_PRE_RELEASE\fR is an added bit of text that +indicates that this is a pre\-release version, such as \f(CW"\-dev"\fR for an +ongoing development snapshot or \f(CW"\-alpha3"\fR for an alpha release. +The value must be a string. +.PP +The macro \fBOPENSSL_VERSION_BUILD_METADATA\fR is extra information, reserved +for other parties, such as \f(CW"+fips"\fR, or \f(CW"+vendor.1"\fR). +The OpenSSL project will not touch this macro (will leave it an empty string). +The value must be a string. +.PP +\&\fBOPENSSL_VERSION_STR\fR is a convenience macro to get the short version +identifier string, \f(CW"\fR\f(CIMAJOR\fR\f(CW.\fR\f(CIMINOR\fR\f(CW.\fR\f(CIPATCH\fR\f(CW"\fR. +.PP +\&\fBOPENSSL_FULL_VERSION_STR\fR is a convenience macro to get the longer +version identifier string, which combines \fBOPENSSL_VERSION_STR\fR, +\&\fBOPENSSL_VERSION_PRE_RELEASE\fR and \fBOPENSSL_VERSION_BUILD_METADATA\fR. +.PP +\&\fBOPENSSL_VERSION_TEXT\fR is a convenience macro to get a full descriptive +version text, which includes \fBOPENSSL_FULL_VERSION_STR\fR and the release +date. +.PP +\&\fBOPENSSL_VERSION_PREREQ\fR is a useful macro for checking whether the OpenSSL +version for the headers in use is at least at the given pre\-requisite major +(\fBmaj\fR) and minor (\fBmin\fR) number or not. It will evaluate to true if the +header version number (\fBOPENSSL_VERSION_MAJOR\fR.\fBOPENSSL_VERSION_MINOR\fR) is +greater than or equal to \fBmaj\fR.\fBmin\fR. +.PP +\&\fBOPENSSL_VERSION_NUMBER\fR is a combination of the major, minor and +patch version into a single integer 0xMNN00PP0L, where: +.IP M 4 +.IX Item "M" +is the number from \fBOPENSSL_VERSION_MAJOR\fR, in hexadecimal notation +.IP NN 4 +.IX Item "NN" +is the number from \fBOPENSSL_VERSION_MINOR\fR, in hexadecimal notation +.IP PP 4 +.IX Item "PP" +is the number from \fBOPENSSL_VERSION_PATCH\fR, in hexadecimal notation +.SS Functions +.IX Subsection "Functions" +\&\fBOPENSSL_version_major()\fR, \fBOPENSSL_version_minor()\fR, \fBOPENSSL_version_patch()\fR, +\&\fBOPENSSL_version_pre_release()\fR, and \fBOPENSSL_version_build_metadata()\fR return +the values of the macros above for the build of the library, respectively. +.PP +\&\fBOpenSSL_version()\fR returns different strings depending on \fIt\fR: +.IP OPENSSL_VERSION 4 +.IX Item "OPENSSL_VERSION" +The value of \fBOPENSSL_VERSION_TEXT\fR +.IP OPENSSL_VERSION_STRING 4 +.IX Item "OPENSSL_VERSION_STRING" +The value of \fBOPENSSL_VERSION_STR\fR +.IP OPENSSL_FULL_VERSION_STRING 4 +.IX Item "OPENSSL_FULL_VERSION_STRING" +The value of \fBOPENSSL_FULL_VERSION_STR\fR +.IP OPENSSL_CFLAGS 4 +.IX Item "OPENSSL_CFLAGS" +The compiler flags set for the compilation process in the form +\&\f(CW\*(C`compiler: ...\*(C'\fR if available, or \f(CW\*(C`compiler: information not available\*(C'\fR +otherwise. +.IP OPENSSL_BUILT_ON 4 +.IX Item "OPENSSL_BUILT_ON" +The date of the build process in the form \f(CW\*(C`built on: ...\*(C'\fR if available +or \f(CW\*(C`built on: date not available\*(C'\fR otherwise. +The date would not be available in a reproducible build, for example. +.IP OPENSSL_PLATFORM 4 +.IX Item "OPENSSL_PLATFORM" +The "Configure" target of the library build in the form \f(CW\*(C`platform: ...\*(C'\fR +if available, or \f(CW\*(C`platform: information not available\*(C'\fR otherwise. +.IP OPENSSL_DIR 4 +.IX Item "OPENSSL_DIR" +The \fBOPENSSLDIR\fR setting of the library build in the form \f(CW\*(C`OPENSSLDIR: "..."\*(C'\fR +if available, or \f(CW\*(C`OPENSSLDIR: N/A\*(C'\fR otherwise. +.IP OPENSSL_ENGINES_DIR 4 +.IX Item "OPENSSL_ENGINES_DIR" +The \fBENGINESDIR\fR setting of the library build in the form \f(CW\*(C`ENGINESDIR: "..."\*(C'\fR +if available, or \f(CW\*(C`ENGINESDIR: N/A\*(C'\fR otherwise. This option is deprecated in +OpenSSL 3.0. +.IP OPENSSL_MODULES_DIR 4 +.IX Item "OPENSSL_MODULES_DIR" +The \fBMODULESDIR\fR setting of the library build in the form \f(CW\*(C`MODULESDIR: "..."\*(C'\fR +if available, or \f(CW\*(C`MODULESDIR: N/A\*(C'\fR otherwise. +.IP OPENSSL_CPU_INFO 4 +.IX Item "OPENSSL_CPU_INFO" +The current OpenSSL cpu settings. +This is the current setting of the cpu capability flags. It is usually +automatically configured but may be set via an environment variable. +The value has the same syntax as the environment variable. +For x86 the string looks like \f(CW\*(C`CPUINFO: OPENSSL_ia32cap=0x123:0x456\*(C'\fR +or \f(CW\*(C`CPUINFO: N/A\*(C'\fR if not available. +.IP OPENSSL_WINCTX 4 +.IX Item "OPENSSL_WINCTX" +The Windows install context. +The Windows install context is used to compute the OpenSSL registry key name +on Windows. The full registry key is +\&\f(CW\*(C`SOFTWARE\eWOW6432Node\eOpenSSL\-{major}.{minor}\-{context}\*(C'\fR, where \f(CW\*(C`{major}\*(C'\fR, +\&\f(CW\*(C`{minor}\*(C'\fR and \f(CW\*(C`{context}\*(C'\fR are OpenSSL\*(Aqs major version number, minor version +number and the Windows install context, respectively. +.PP +For an unknown \fIt\fR, the text \f(CW\*(C`not available\*(C'\fR is returned. +.PP +\&\fBOPENSSL_info()\fR also returns different strings depending on \fIt\fR: +.IP OPENSSL_INFO_CONFIG_DIR 4 +.IX Item "OPENSSL_INFO_CONFIG_DIR" +The configured \f(CW\*(C`OPENSSLDIR\*(C'\fR, which is the default location for +OpenSSL configuration files. +.IP OPENSSL_INFO_ENGINES_DIR 4 +.IX Item "OPENSSL_INFO_ENGINES_DIR" +The configured \f(CW\*(C`ENGINESDIR\*(C'\fR, which is the default location for +OpenSSL engines. +.IP OPENSSL_INFO_MODULES_DIR 4 +.IX Item "OPENSSL_INFO_MODULES_DIR" +The configured \f(CW\*(C`MODULESDIR\*(C'\fR, which is the default location for +dynamically loadable OpenSSL modules other than engines. +.IP OPENSSL_INFO_DSO_EXTENSION 4 +.IX Item "OPENSSL_INFO_DSO_EXTENSION" +The configured dynamically loadable module extension. +.IP OPENSSL_INFO_DIR_FILENAME_SEPARATOR 4 +.IX Item "OPENSSL_INFO_DIR_FILENAME_SEPARATOR" +The separator between a directory specification and a filename. +Note that on some operating systems, this is not the same as the +separator between directory elements. +.IP OPENSSL_INFO_LIST_SEPARATOR 4 +.IX Item "OPENSSL_INFO_LIST_SEPARATOR" +The OpenSSL list separator. +This is typically used in strings that are lists of items, such as the +value of the environment variable \f(CW$PATH\fR on Unix (where the +separator is \f(CW\*(C`:\*(C'\fR) or \f(CW\*(C`%PATH%\*(C'\fR on Windows (where the separator is +\&\f(CW\*(C`;\*(C'\fR). +.IP OPENSSL_INFO_CPU_SETTINGS 4 +.IX Item "OPENSSL_INFO_CPU_SETTINGS" +The current OpenSSL cpu settings. +This is the current setting of the cpu capability flags. It is usually +automatically configured but may be set via an environment variable. +The value has the same syntax as the environment variable. +For x86 the string looks like \f(CW\*(C`OPENSSL_ia32cap=0x123:0x456\*(C'\fR. +.IP OPENSSL_INFO_WINDOWS_CONTEXT 4 +.IX Item "OPENSSL_INFO_WINDOWS_CONTEXT" +The Windows install context. +The Windows install context is used to compute the OpenSSL registry key name +on Windows. The full registry key is +\&\f(CW\*(C`SOFTWARE\eWOW6432Node\eOpenSSL\-{major}.{minor}\-{context}\*(C'\fR, where \f(CW\*(C`{major}\*(C'\fR, +\&\f(CW\*(C`{minor}\*(C'\fR and \f(CW\*(C`{context}\*(C'\fR are OpenSSL\*(Aqs major version number, minor version +number and the Windows install context, respectively. +.PP +For an unknown \fIt\fR, NULL is returned. +.PP +\&\fBOpenSSL_version_num()\fR returns the value of \fBOPENSSL_VERSION_NUMBER\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOPENSSL_version_major()\fR, \fBOPENSSL_version_minor()\fR and \fBOPENSSL_version_patch()\fR +return the version number parts as integers. +.PP +\&\fBOPENSSL_version_pre_release()\fR and \fBOPENSSL_version_build_metadata()\fR return +the values of \fBOPENSSL_VERSION_PRE_RELEASE\fR and +\&\fBOPENSSL_VERSION_BUILD_METADATA\fR respectively as constant strings. +For any of them that is undefined, the empty string is returned. +.PP +\&\fBOpenSSL_version()\fR returns constant strings. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The macros and functions described here were added in OpenSSL 3.0, +except for OPENSSL_VERSION_NUMBER and \fBOpenSSL_version_num()\fR. +.SH BUGS +.IX Header "BUGS" +There was a discrepancy between this manual and commentary + code +in \fI\fR, where the latter suggested that the +four least significant bits of \fBOPENSSL_VERSION_NUMBER\fR could be +\&\f(CW0x0f\fR in released OpenSSL versions. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PBMAC1_get1_pbkdf2_param.3 b/static/netbsd/man3/PBMAC1_get1_pbkdf2_param.3 new file mode 100644 index 00000000..dda2d5f0 --- /dev/null +++ b/static/netbsd/man3/PBMAC1_get1_pbkdf2_param.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: PBMAC1_get1_pbkdf2_param.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PBMAC1_get1_pbkdf2_param 3" +.TH PBMAC1_get1_pbkdf2_param 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PBMAC1_get1_pbkdf2_param \- Function to manipulate a PBMAC1 +MAC structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PBKDF2PARAM *PBMAC1_get1_pbkdf2_param(const X509_ALGOR *macalg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPBMAC1_get1_pbkdf2_param()\fR retrieves a \fBPBKDF2PARAM\fR structure from an +\&\fIX509_ALGOR\fR structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPBMAC1_get1_pbkdf2_param()\fR returns NULL in case when PBMAC1 uses an algorithm +apart from \fBPBKDF2\fR or when passed incorrect parameters and a pointer to +\&\fBPBKDF2PARAM\fR structure otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 9579 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-pkcs12\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The \fIPBMAC1_get1_pbkdf2_param\fR function was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_X509_INFO_read_bio_ex.3 b/static/netbsd/man3/PEM_X509_INFO_read_bio_ex.3 new file mode 100644 index 00000000..ebd92c1a --- /dev/null +++ b/static/netbsd/man3/PEM_X509_INFO_read_bio_ex.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: PEM_X509_INFO_read_bio_ex.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_X509_INFO_read_bio_ex 3" +.TH PEM_X509_INFO_read_bio_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_X509_INFO_read_ex, PEM_X509_INFO_read, PEM_X509_INFO_read_bio_ex, PEM_X509_INFO_read_bio +\&\- read PEM\-encoded data structures into one or more X509_INFO objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509_INFO) *PEM_X509_INFO_read_ex(FILE *fp, STACK_OF(X509_INFO) *sk, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, +\& const char *propq); +\& STACK_OF(X509_INFO) *PEM_X509_INFO_read(FILE *fp, STACK_OF(X509_INFO) *sk, +\& pem_password_cb *cb, void *u); +\& STACK_OF(X509_INFO) *PEM_X509_INFO_read_bio_ex(BIO *bio, +\& STACK_OF(X509_INFO) *sk, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, +\& const char *propq); +\& STACK_OF(X509_INFO) *PEM_X509_INFO_read_bio(BIO *bp, STACK_OF(X509_INFO) *sk, +\& pem_password_cb *cb, void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPEM_X509_INFO_read_ex()\fR loads the \fBX509_INFO\fR objects from a file \fIfp\fR. +.PP +\&\fBPEM_X509_INFO_read()\fR is similar to \fBPEM_X509_INFO_read_ex()\fR +but uses the default (NULL) library context \fIlibctx\fR +and empty property query \fIpropq\fR. +.PP +\&\fBPEM_X509_INFO_read_bio_ex()\fR loads the \fBX509_INFO\fR objects using a bio \fIbp\fR. +.PP +\&\fBPEM_X509_INFO_read_bio()\fR is similar to \fBPEM_X509_INFO_read_bio_ex()\fR +but uses the default (NULL) library context \fIlibctx\fR +and empty property query \fIpropq\fR. +.PP +Each of the loaded \fBX509_INFO\fR objects can contain a CRL, a certificate, +and/or a private key. +The elements are read sequentially, and as far as they are of different type than +the elements read before, they are combined into the same \fBX509_INFO\fR object. +The idea behind this is that if, for instance, a certificate is followed by +a private key, the private key is supposed to correspond to the certificate. +.PP +If the input stack \fIsk\fR is NULL a new stack is allocated, +else the given stack is extended. +.PP +The optional \fIcb\fR and \fIu\fR parameters can be used for providing a pass phrase +needed for decrypting encrypted PEM structures (normally only private keys). +See \fBPEM_read_bio_PrivateKey\fR\|(3) and \fBpassphrase\-encoding\fR\|(7) for details. +.PP +The library context \fIlibctx\fR and property query \fIpropq\fR are used for fetching +algorithms from providers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_X509_INFO_read_ex()\fR, \fBPEM_X509_INFO_read()\fR, +\&\fBPEM_X509_INFO_read_bio_ex()\fR and \fBPEM_X509_INFO_read_bio()\fR return +a stack of \fBX509_INFO\fR objects or NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_read_bio_ex\fR\|(3), +\&\fBPEM_read_bio_PrivateKey\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBPEM_X509_INFO_read_ex()\fR and +\&\fBPEM_X509_INFO_read_bio_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_bytes_read_bio.3 b/static/netbsd/man3/PEM_bytes_read_bio.3 new file mode 100644 index 00000000..d44fca63 --- /dev/null +++ b/static/netbsd/man3/PEM_bytes_read_bio.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: PEM_bytes_read_bio.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_bytes_read_bio 3" +.TH PEM_bytes_read_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_bytes_read_bio, PEM_bytes_read_bio_secmem \- read a PEM\-encoded data structure from a BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PEM_bytes_read_bio(unsigned char **pdata, long *plen, char **pnm, +\& const char *name, BIO *bp, pem_password_cb *cb, +\& void *u); +\& int PEM_bytes_read_bio_secmem(unsigned char **pdata, long *plen, char **pnm, +\& const char *name, BIO *bp, pem_password_cb *cb, +\& void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPEM_bytes_read_bio()\fR reads PEM\-formatted (IETF RFC 1421 and IETF RFC 7468) +data from the BIO +\&\fIbp\fR for the data type given in \fIname\fR (RSA PRIVATE KEY, CERTIFICATE, +etc.). If multiple PEM\-encoded data structures are present in the same +stream, \fBPEM_bytes_read_bio()\fR will skip non\-matching data types and +continue reading. Non\-PEM data present in the stream may cause an +error. +.PP +The PEM header may indicate that the following data is encrypted; if so, +the data will be decrypted, waiting on user input to supply a passphrase +if needed. The password callback \fIcb\fR and rock \fIu\fR are used to obtain +the decryption passphrase, if applicable. +.PP +Some data types have compatibility aliases, such as a file containing +X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE. +The actual type indicated by the file is returned in \fI*pnm\fR if \fIpnm\fR is +non\-NULL. The caller must free the storage pointed to by \fI*pnm\fR. +.PP +The returned data is the DER\-encoded form of the requested type, in +\&\fI*pdata\fR with length \fI*plen\fR. The caller must free the storage pointed +to by \fI*pdata\fR. +.PP +\&\fBPEM_bytes_read_bio_secmem()\fR is similar to \fBPEM_bytes_read_bio()\fR, but uses +memory from the secure heap for its temporary buffers and the storage +returned in \fI*pdata\fR and \fI*pnm\fR. Accordingly, the caller must use +\&\fBOPENSSL_secure_free()\fR to free that storage. +.SH NOTES +.IX Header "NOTES" +\&\fBPEM_bytes_read_bio_secmem()\fR only enforces that the secure heap is used for +storage allocated within the PEM processing stack. The BIO stack from +which input is read may also use temporary buffers, which are not necessarily +allocated from the secure heap. In cases where it is desirable to ensure +that the contents of the PEM file only appears in memory from the secure heap, +care is needed in generating the BIO passed as \fIbp\fR. In particular, the +use of \fBBIO_s_file()\fR indicates the use of the operating system stdio +functionality, which includes buffering as a feature; \fBBIO_s_fd()\fR is likely +to be more appropriate in such cases. +.PP +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_bytes_read_bio()\fR and \fBPEM_bytes_read_bio_secmem()\fR return 1 for success or +0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_read_bio_ex\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPEM_bytes_read_bio_secmem()\fR was introduced in OpenSSL 1.1.1 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_read.3 b/static/netbsd/man3/PEM_read.3 new file mode 100644 index 00000000..edc50e70 --- /dev/null +++ b/static/netbsd/man3/PEM_read.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: PEM_read.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_read 3" +.TH PEM_read 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO, PEM_write, +PEM_write_bio, PEM_ASN1_write, PEM_ASN1_write_bio, PEM_ASN1_write_bio_ctx +\&\- PEM encoding routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PEM_read(FILE *fp, char **name, char **header, +\& unsigned char **data, long *len); +\& int PEM_read_bio(BIO *bp, char **name, char **header, +\& unsigned char **data, long *len); +\& +\& int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo); +\& int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write(FILE *fp, const char *name, const char *header, +\& const unsigned char *data, long len); +\& int PEM_write_bio(BIO *bp, const char *name, const char *header, +\& const unsigned char *data, long len); +\& int PEM_ASN1_write(i2d_of_void *i2d, const char *name, FILE *fp, +\& const void *x, const EVP_CIPHER *enc, +\& const unsigned char *kstr, int klen, +\& pem_password_cb *callback, void *u); +\& int PEM_ASN1_write_bio(i2d_of_void *i2d, const char *name, BIO *bp, +\& const void *x, const EVP_CIPHER *enc, +\& const unsigned char *kstr, int klen, +\& pem_password_cb *callback, void *u); +\& int PEM_ASN1_write_bio_ctx(OSSL_i2d_of_void_ctx *i2d, void *vctx, +\& const char *name, BIO *bp, const void *x, +\& const EVP_CIPHER *enc, const unsigned char *kstr, +\& int klen, pem_password_cb *callback, void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions read and write PEM\-encoded objects, using the PEM +type \fBname\fR, any additional \fBheader\fR information, and the raw +\&\fBdata\fR of length \fBlen\fR. +.PP +PEM is the term used for binary content encoding first defined in IETF +RFC 1421. The content is a series of base64\-encoded lines, surrounded +by begin/end markers each on their own line. For example: +.PP +.Vb 4 +\& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\- +\& MIICdg.... +\& ... bhTQ== +\& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\- +.Ve +.PP +Optional header line(s) may appear after the begin line, and their +existence depends on the type of object being written or read. +.PP +\&\fBPEM_write()\fR writes to the file \fBfp\fR, while \fBPEM_write_bio()\fR writes to +the BIO \fBbp\fR. The \fBname\fR is the name to use in the marker, the +\&\fBheader\fR is the header value or NULL, and \fBdata\fR and \fBlen\fR specify +the data and its length. +.PP +The final \fBdata\fR buffer is typically an ASN.1 object which can be decoded with +the \fBd2i\fR function appropriate to the type \fBname\fR; see \fBd2i_X509\fR\|(3) +for examples. +.PP +\&\fBPEM_read()\fR reads from the file \fBfp\fR, while \fBPEM_read_bio()\fR reads +from the BIO \fBbp\fR. +Both skip any non\-PEM data that precedes the start of the next PEM object. +When an object is successfully retrieved, the type name from the "\-\-\-\-BEGIN +\-\-\-\-\-" is returned via the \fBname\fR argument, any encapsulation headers +are returned in \fBheader\fR and the base64\-decoded content and its length are +returned via \fBdata\fR and \fBlen\fR respectively. +The \fBname\fR, \fBheader\fR and \fBdata\fR pointers are allocated via \fBOPENSSL_malloc()\fR +and should be freed by the caller via \fBOPENSSL_free()\fR when no longer needed. +.PP +\&\fBPEM_get_EVP_CIPHER_INFO()\fR can be used to determine the \fBdata\fR returned by +\&\fBPEM_read()\fR or \fBPEM_read_bio()\fR is encrypted and to retrieve the associated cipher +and IV. +The caller passes a pointer to structure of type \fBEVP_CIPHER_INFO\fR via the +\&\fBcinfo\fR argument and the \fBheader\fR returned via \fBPEM_read()\fR or \fBPEM_read_bio()\fR. +If the call is successful 1 is returned and the cipher and IV are stored at the +address pointed to by \fBcinfo\fR. +When the header is malformed, or not supported or when the cipher is unknown +or some internal error happens 0 is returned. +This function is deprecated, see \fBNOTES\fR below. +.PP +\&\fBPEM_do_header()\fR can then be used to decrypt the data if the header +indicates encryption. +The \fBcinfo\fR argument is a pointer to the structure initialized by the previous +call to \fBPEM_get_EVP_CIPHER_INFO()\fR. +The \fBdata\fR and \fBlen\fR arguments are those returned by the previous call to +\&\fBPEM_read()\fR or \fBPEM_read_bio()\fR. +The \fBcb\fR and \fBu\fR arguments make it possible to override the default password +prompt function as described in \fBPEM_read_PrivateKey\fR\|(3). +On successful completion the \fBdata\fR is decrypted in place, and \fBlen\fR is +updated to indicate the plaintext length. +This function is deprecated, see \fBNOTES\fR below. +.PP +If the data is a priori known to not be encrypted, then neither \fBPEM_do_header()\fR +nor \fBPEM_get_EVP_CIPHER_INFO()\fR need be called. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_read()\fR, and \fBPEM_read_bio()\fR return 1 on success and 0 on failure, the latter +includes the case when no more PEM objects remain in the input file. To +distinguish end of file from more serious errors the caller must peek at the +error stack and check for \fBPEM_R_NO_START_LINE\fR, which indicates that no more +PEM objects were found. See \fBERR_peek_last_error\fR\|(3), \fBERR_GET_REASON\fR\|(3). +.PP +\&\fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR return 1 on success, and 0 on +failure. +The \fBdata\fR is likely meaningless if these functions fail. +.SH NOTES +.IX Header "NOTES" +The \fBPEM_get_EVP_CIPHER_INFO()\fR and \fBPEM_do_header()\fR functions are deprecated. +This is because the underlying PEM encryption format is obsolete, and should +be avoided. +It uses an encryption format with an OpenSSL\-specific key\-derivation function, +which employs MD5 with an iteration count of 1! +Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 +v2.0 PBE. +See \fBPEM_write_PrivateKey\fR\|(3) and \fBd2i_PKCS8PrivateKey_bio\fR\|(3). +.PP +\&\fBPEM_do_header()\fR makes no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. +.PP +\&\fBPEM_write()\fR and \fBPEM_write_bio()\fR return the number of encoded bytes (not +counting the PEM header and end marker) written on success or 0 on failure. +.PP +\&\fBPEM_ASN1_write_bio()\fR, and \fBPEM_ASN1_write_bio_ctx()\fR return 1 on success and 0 on +failure. The latter function passes an additional application\-provided context +value to the \fBi2d\fR function that serialises the input ASN.1 object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_peek_last_error\fR\|(3), \fBERR_GET_LIB\fR\|(3), +\&\fBd2i_PKCS8PrivateKey_bio\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBPEM_ASN1_write_bio_ctx()\fR function was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 1998\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_read_CMS.3 b/static/netbsd/man3/PEM_read_CMS.3 new file mode 100644 index 00000000..d0bbf97e --- /dev/null +++ b/static/netbsd/man3/PEM_read_CMS.3 @@ -0,0 +1,209 @@ +.\" $NetBSD: PEM_read_CMS.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_read_CMS 3" +.TH PEM_read_CMS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DECLARE_PEM_rw, +PEM_read_CMS, +PEM_read_bio_CMS, +PEM_write_CMS, +PEM_write_bio_CMS, +PEM_write_DHxparams, +PEM_write_bio_DHxparams, +PEM_read_ECPKParameters, +PEM_read_bio_ECPKParameters, +PEM_write_ECPKParameters, +PEM_write_bio_ECPKParameters, +PEM_read_ECPrivateKey, +PEM_write_ECPrivateKey, +PEM_write_bio_ECPrivateKey, +PEM_read_EC_PUBKEY, +PEM_read_bio_EC_PUBKEY, +PEM_write_EC_PUBKEY, +PEM_write_bio_EC_PUBKEY, +PEM_read_NETSCAPE_CERT_SEQUENCE, +PEM_read_bio_NETSCAPE_CERT_SEQUENCE, +PEM_write_NETSCAPE_CERT_SEQUENCE, +PEM_write_bio_NETSCAPE_CERT_SEQUENCE, +PEM_read_PKCS8, +PEM_read_bio_PKCS8, +PEM_write_PKCS8, +PEM_write_bio_PKCS8, +PEM_write_PKCS8_PRIV_KEY_INFO, +PEM_read_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_PKCS8_PRIV_KEY_INFO, +PEM_write_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_SSL_SESSION, +PEM_read_bio_SSL_SESSION, +PEM_write_SSL_SESSION, +PEM_write_bio_SSL_SESSION, +PEM_read_X509_PUBKEY, +PEM_read_bio_X509_PUBKEY, +PEM_write_X509_PUBKEY, +PEM_write_bio_X509_PUBKEY +\&\- PEM object encoding routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& DECLARE_PEM_rw(name, TYPE) +\& +\& TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u); +\& TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u); +\& int PEM_write_TYPE(FILE *fp, const TYPE *a); +\& int PEM_write_bio_TYPE(BIO *bp, const TYPE *a); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include +\& +\& int PEM_write_DHxparams(FILE *out, const DH *dh); +\& int PEM_write_bio_DHxparams(BIO *out, const DH *dh); +\& EC_GROUP *PEM_read_ECPKParameters(FILE *fp, EC_GROUP **x, pem_password_cb *cb, void *u); +\& EC_GROUP *PEM_read_bio_ECPKParameters(BIO *bp, EC_GROUP **x, pem_password_cb *cb, void *u); +\& int PEM_write_ECPKParameters(FILE *out, const EC_GROUP *x); +\& int PEM_write_bio_ECPKParameters(BIO *out, const EC_GROUP *x), +\& +\& EC_KEY *PEM_read_EC_PUBKEY(FILE *fp, EC_KEY **x, pem_password_cb *cb, void *u); +\& EC_KEY *PEM_read_bio_EC_PUBKEY(BIO *bp, EC_KEY **x, pem_password_cb *cb, void *u); +\& int PEM_write_EC_PUBKEY(FILE *out, const EC_KEY *x); +\& int PEM_write_bio_EC_PUBKEY(BIO *out, const EC_KEY *x); +\& +\& EC_KEY *PEM_read_ECPrivateKey(FILE *out, EC_KEY **x, pem_password_cb *cb, void *u); +\& EC_KEY *PEM_read_bio_ECPrivateKey(BIO *out, EC_KEY **x, pem_password_cb *cb, void *u); +\& int PEM_write_ECPrivateKey(FILE *out, const EC_KEY *x, const EVP_CIPHER *enc, +\& const unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_ECPrivateKey(BIO *out, const EC_KEY *x, const EVP_CIPHER *enc, +\& const unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +To replace the deprecated functions listed above, applications should use the +\&\fBEVP_PKEY\fR type and \fBOSSL_DECODER_from_bio()\fR and \fBOSSL_ENCODER_to_bio()\fR to +read and write PEM data containing key parameters or private and public keys. +.PP +In the description below, \fR\f(BITYPE\fR\fB\fR is used +as a placeholder for any of the OpenSSL datatypes, such as \fBX509\fR. +The macro \fBDECLARE_PEM_rw\fR expands to the set of declarations shown in +the next four lines of the synopsis. +.PP +These routines convert between local instances of ASN1 datatypes and +the PEM encoding. For more information on the templates, see +\&\fBASN1_ITEM\fR\|(3). For more information on the lower\-level routines used +by the functions here, see \fBPEM_read\fR\|(3). +.PP +\&\fBPEM_read_\fR\f(BITYPE\fR() reads a PEM\-encoded object of \fB\fR\f(BITYPE\fR\fB\fR from the file +\&\fIfp\fR and returns it. The \fIcb\fR and \fIu\fR parameters are as described in +\&\fBpem_password_cb\fR\|(3). +.PP +\&\fBPEM_read_bio_\fR\f(BITYPE\fR() is similar to \fBPEM_read_\fR\f(BITYPE\fR\fB\fR() but reads from +the BIO \fIbp\fR. +.PP +\&\fBPEM_write_\fR\f(BITYPE\fR() writes the PEM encoding of the object \fIa\fR to the file +\&\fIfp\fR. +.PP +\&\fBPEM_write_bio_\fR\f(BITYPE\fR() similarly writes to the BIO \fIbp\fR. +.SH NOTES +.IX Header "NOTES" +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_read_\fR\f(BITYPE\fR() and \fBPEM_read_bio_\fR\f(BITYPE\fR\fB\fR() return a pointer to an +allocated object, which should be released by calling \fB\fR\f(BITYPE\fR\fB_free\fR(), or +NULL on error. +.PP +\&\fBPEM_write_\fR\f(BITYPE\fR() and \fBPEM_write_bio_\fR\f(BITYPE\fR\fB\fR() return 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_read\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBPEM_write_DHxparams()\fR, \fBPEM_write_bio_DHxparams()\fR, +\&\fBPEM_read_ECPKParameters()\fR, \fBPEM_read_bio_ECPKParameters()\fR, +\&\fBPEM_write_ECPKParameters()\fR, \fBPEM_write_bio_ECPKParameters()\fR, +\&\fBPEM_read_EC_PUBKEY()\fR, \fBPEM_read_bio_EC_PUBKEY()\fR, +\&\fBPEM_write_EC_PUBKEY()\fR, \fBPEM_write_bio_EC_PUBKEY()\fR, +\&\fBPEM_read_ECPrivateKey()\fR, \fBPEM_read_bio_ECPrivateKey()\fR, +\&\fBPEM_write_ECPrivateKey()\fR and \fBPEM_write_bio_ECPrivateKey()\fR +were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 1998\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_read_bio_PrivateKey.3 b/static/netbsd/man3/PEM_read_bio_PrivateKey.3 new file mode 100644 index 00000000..2861c0b8 --- /dev/null +++ b/static/netbsd/man3/PEM_read_bio_PrivateKey.3 @@ -0,0 +1,684 @@ +.\" $NetBSD: PEM_read_bio_PrivateKey.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_read_bio_PrivateKey 3" +.TH PEM_read_bio_PrivateKey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +pem_password_cb, +PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey, +PEM_read_PrivateKey_ex, PEM_read_PrivateKey, +PEM_write_bio_PrivateKey_ex, PEM_write_bio_PrivateKey, +PEM_write_bio_PrivateKey_traditional, +PEM_write_PrivateKey_ex, PEM_write_PrivateKey, +PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, +PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, +PEM_read_bio_PUBKEY_ex, PEM_read_bio_PUBKEY, +PEM_read_PUBKEY_ex, PEM_read_PUBKEY, +PEM_write_bio_PUBKEY_ex, PEM_write_bio_PUBKEY, +PEM_write_PUBKEY_ex, PEM_write_PUBKEY, +PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, +PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, +PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, +PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, +PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, +PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, +PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, +PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters_ex, PEM_read_bio_Parameters, +PEM_write_bio_Parameters, PEM_read_bio_DSAparams, PEM_read_DSAparams, +PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, +PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, +PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, +PEM_read_bio_X509_ACERT, PEM_read_X509_ACERT, +PEM_write_bio_X509_ACERT, PEM_write_X509_ACERT, +PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, +PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, +PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, +PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, +PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, +PEM_write_bio_PKCS7, PEM_write_PKCS7 \- PEM routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); +\& +\& EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, +\& void *u, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_PrivateKey_ex(BIO *bp, const EVP_PKEY *x, +\& const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, +\& const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_PrivateKey_ex(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& EVP_PKEY *PEM_read_bio_PUBKEY_ex(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& EVP_PKEY *PEM_read_PUBKEY_ex(FILE *fp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_PUBKEY_ex(BIO *bp, EVP_PKEY *x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); +\& int PEM_write_PUBKEY_ex(FILE *fp, EVP_PKEY *x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); +\& +\& EVP_PKEY *PEM_read_bio_Parameters_ex(BIO *bp, EVP_PKEY **x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x); +\& int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x); +\& +\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); +\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509(BIO *bp, X509 *x); +\& int PEM_write_X509(FILE *fp, X509 *x); +\& +\& X509_ACERT *PEM_read_bio_X509_ACERT(BIO *bp, X509_ACERT **x, +\& pem_password_cb *cb, void *u); +\& X509_ACERT *PEM_read_X509_ACERT(FILE *fp, X509_ACERT **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509_ACERT(BIO *bp, X509_ACERT *x); +\& int PEM_write_X509_ACERT(FILE *fp, X509_ACERT *x); +\& +\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); +\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); +\& int PEM_write_X509_AUX(FILE *fp, X509 *x); +\& +\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, +\& pem_password_cb *cb, void *u); +\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); +\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); +\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); +\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); +\& +\& X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, +\& pem_password_cb *cb, void *u); +\& X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); +\& int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); +\& +\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); +\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); +\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); +\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); +\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x); +\& +\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); +\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); +\& +\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, +\& pem_password_cb *cb, void *u); +\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, +\& pem_password_cb *cb, void *u); +\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); +\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); +\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); +\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); +\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x); +\& int PEM_write_DSAparams(FILE *fp, DSA *x); +\& +\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); +\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); +\& int PEM_write_bio_DHparams(BIO *bp, DH *x); +\& int PEM_write_DHparams(FILE *fp, DH *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page that have a \fITYPE\fR of \fBDH\fR, \fBDSA\fR +and \fBRSA\fR are deprecated. Applications should use \fBOSSL_ENCODER_to_bio\fR\|(3) and +\&\fBOSSL_DECODER_from_bio\fR\|(3) instead. +.PP +The PEM functions read or write structures in PEM format. In +this sense PEM format is simply base64 encoded data surrounded +by header lines. +.PP +For more details about the meaning of arguments see the +\&\fBPEM FUNCTION ARGUMENTS\fR section. +.PP +Each operation has four functions associated with it. For +brevity the term "\fR\f(BITYPE\fR\fB\fR functions" will be used below to collectively +refer to the \fBPEM_read_bio_\fR\f(BITYPE\fR\fB\fR(), \fBPEM_read_\fR\f(BITYPE\fR\fB\fR(), +\&\fBPEM_write_bio_\fR\f(BITYPE\fR\fB\fR(), and \fBPEM_write_\fR\f(BITYPE\fR\fB\fR() functions. +.PP +Some operations have additional variants that take a library context \fIlibctx\fR +and a property query string \fIpropq\fR. The \fBX509\fR, \fBX509_REQ\fR and \fBX509_CRL\fR +objects may have an associated library context or property query string but +there are no variants of these functions that take a library context or property +query string parameter. In this case it is possible to set the appropriate +library context or property query string by creating an empty \fBX509\fR, +\&\fBX509_REQ\fR or \fBX509_CRL\fR object using \fBX509_new_ex\fR\|(3), \fBX509_REQ_new_ex\fR\|(3) +or \fBX509_CRL_new_ex\fR\|(3) respectively. Then pass the empty object as a parameter +to the relevant PEM function. See the "EXAMPLES" section below. +.PP +The \fBPrivateKey\fR functions read or write a private key in PEM format using +an EVP_PKEY structure. The write routines use PKCS#8 private key format and are +equivalent to \fBPEM_write_bio_PKCS8PrivateKey()\fR. The read functions transparently +handle traditional and PKCS#8 format encrypted and unencrypted keys. +.PP +\&\fBPEM_write_bio_PrivateKey_traditional()\fR writes out a private key in the +"traditional" format with a simple private key marker and should only +be used for compatibility with legacy programs. +.PP +\&\fBPEM_write_bio_PKCS8PrivateKey()\fR and \fBPEM_write_PKCS8PrivateKey()\fR write a private +key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using +PKCS#5 v2.0 password based encryption algorithms. The \fIcipher\fR argument +specifies the encryption algorithm to use: unlike some other PEM routines the +encryption is applied at the PKCS#8 level and not in the PEM headers. If +\&\fIcipher\fR is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo +structure is used instead. +.PP +\&\fBPEM_write_bio_PKCS8PrivateKey_nid()\fR and \fBPEM_write_PKCS8PrivateKey_nid()\fR +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however +it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm +to use is specified in the \fInid\fR parameter and should be the NID of the +corresponding OBJECT IDENTIFIER (see NOTES section). +.PP +The \fBPUBKEY\fR functions process a public key using an EVP_PKEY +structure. The public key is encoded as a SubjectPublicKeyInfo +structure. +.PP +The \fBRSAPrivateKey\fR functions process an RSA private key using an +RSA structure. The write routines uses traditional format. The read +routines handles the same formats as the \fBPrivateKey\fR +functions but an error occurs if the private key is not RSA. +.PP +The \fBRSAPublicKey\fR functions process an RSA public key using an +RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey +structure. +.PP +The \fBRSA_PUBKEY\fR functions also process an RSA public key using +an RSA structure. However, the public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not RSA. +.PP +The \fBDSAPrivateKey\fR functions process a DSA private key using a +DSA structure. The write routines uses traditional format. The read +routines handles the same formats as the \fBPrivateKey\fR +functions but an error occurs if the private key is not DSA. +.PP +The \fBDSA_PUBKEY\fR functions process a DSA public key using +a DSA structure. The public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not DSA. +.PP +The \fBParameters\fR functions read or write key parameters in PEM format using +an EVP_PKEY structure. The encoding depends on the type of key; for DSA key +parameters, it will be a Dss\-Parms structure as defined in RFC2459, and for DH +key parameters, it will be a PKCS#3 DHparameter structure. \fIThese functions +only exist for the \fR\f(BIBIO\fR\fI type\fR. +.PP +The \fBDSAparams\fR functions process DSA parameters using a DSA +structure. The parameters are encoded using a Dss\-Parms structure +as defined in RFC2459. +.PP +The \fBDHparams\fR functions process DH parameters using a DH +structure. The parameters are encoded using a PKCS#3 DHparameter +structure. +.PP +The \fBX509\fR functions process an X509 certificate using an X509 +structure. They will also process a trusted X509 certificate but +any trust settings are discarded. +.PP +The \fBX509_ACERT\fR functions process an X509 attribute certificate using +an X509_ACERT structure. +.PP +The \fBX509_AUX\fR functions process a trusted X509 certificate using +an X509 structure. +.PP +The \fBX509_REQ\fR and \fBX509_REQ_NEW\fR functions process a PKCS#10 +certificate request using an X509_REQ structure. The \fBX509_REQ\fR +write functions use \fBCERTIFICATE REQUEST\fR in the header whereas +the \fBX509_REQ_NEW\fR functions use \fBNEW CERTIFICATE REQUEST\fR +(as required by some CAs). The \fBX509_REQ\fR read functions will +handle either form so there are no \fBX509_REQ_NEW\fR read functions. +.PP +The \fBX509_CRL\fR functions process an X509 CRL using an X509_CRL +structure. +.PP +The \fBPKCS7\fR functions process a PKCS#7 ContentInfo using a PKCS7 +structure. +.SH "PEM FUNCTION ARGUMENTS" +.IX Header "PEM FUNCTION ARGUMENTS" +The PEM functions have many common arguments. +.PP +The \fIbp\fR BIO parameter (if present) specifies the BIO to read from +or write to. The \fIbp\fR BIO parameter \fBMUST NOT\fR be NULL. +.PP +The \fIfp\fR FILE parameter (if present) specifies the FILE pointer to +read from or write to. +.PP +The PEM read functions all take an argument \fR\f(BITYPE\fR\fI **x\fR and return +a \fI\fR\f(BITYPE\fR\fI *\fR pointer. Where \fI\fR\f(BITYPE\fR\fI\fR is whatever structure the function +uses. If \fIx\fR is NULL then the parameter is ignored. If \fIx\fR is not +NULL but \fI*x\fR is NULL then the structure returned will be written +to \fI*x\fR. If neither \fIx\fR nor \fI*x\fR is NULL then an attempt is made +to reuse the structure at \fI*x\fR (but see BUGS and EXAMPLES sections). +Irrespective of the value of \fIx\fR a pointer to the structure is always +returned (or NULL if an error occurred). The caller retains ownership of the +returned object and needs to free it when it is no longer needed, e.g. +using \fBX509_free()\fR for X509 objects or \fBEVP_PKEY_free()\fR for EVP_PKEY objects. +.PP +The PEM functions which write private keys take an \fIenc\fR parameter +which specifies the encryption algorithm to use, encryption is done +at the PEM level. If this parameter is set to NULL then the private +key is written in unencrypted form. +.PP +The \fIcb\fR argument is the callback to use when querying for the pass +phrase used for encrypted PEM structures (normally only private keys). +.PP +For the PEM write routines if the \fIkstr\fR parameter is not NULL then +\&\fIklen\fR bytes at \fIkstr\fR are used as the passphrase and \fIcb\fR is +ignored. +.PP +If the \fIcb\fR parameters is set to NULL and the \fIu\fR parameter is not +NULL then the \fIu\fR parameter is interpreted as a NUL terminated string +to use as the passphrase. If both \fIcb\fR and \fIu\fR are NULL then the +default callback routine is used which will typically prompt for the +passphrase on the current terminal with echoing turned off. +.PP +The default passphrase callback is sometimes inappropriate (for example +in a GUI application) so an alternative can be supplied. The callback +routine has the following form: +.PP +.Vb 1 +\& int cb(char *buf, int size, int rwflag, void *u); +.Ve +.PP +\&\fIbuf\fR is the buffer to write the passphrase to. \fIsize\fR is the maximum +length of the passphrase (i.e. the size of buf). \fIrwflag\fR is a flag +which is set to 0 when reading and 1 when writing. A typical routine +will ask the user to verify the passphrase (for example by prompting +for it twice) if \fIrwflag\fR is 1. The \fIu\fR parameter has the same +value as the \fIu\fR parameter passed to the PEM routine. It allows +arbitrary data to be passed to the callback by the application +(for example a window handle in a GUI application). The callback +\&\fImust\fR return the number of characters in the passphrase or \-1 if +an error occurred. The passphrase can be arbitrary data; in the case where it +is a string, it is not NUL terminated. See the "EXAMPLES" section below. +.PP +Some implementations may need to use cryptographic algorithms during their +operation. If this is the case and \fIlibctx\fR and \fIpropq\fR parameters have been +passed then any algorithm fetches will use that library context and property +query string. Otherwise the default library context and property query string +will be used. +.SH NOTES +.IX Header "NOTES" +The PEM reading functions will skip any extraneous content or PEM data of +a different type than they expect. This allows for example having a certificate +(or multiple certificates) and a key in the PEM format in a single file. +.PP +The old \fBPrivateKey\fR write routines are retained for compatibility. +New applications should write private keys using the +\&\fBPEM_write_bio_PKCS8PrivateKey()\fR or \fBPEM_write_PKCS8PrivateKey()\fR routines +because they are more secure (they use an iteration count of 2048 whereas +the traditional routines use a count of 1) unless compatibility with older +versions of OpenSSL is important. +.PP +The \fBPrivateKey\fR read routines can be used in all applications because +they handle all formats transparently. +.PP +A frequent cause of problems is attempting to use the PEM routines like +this: +.PP +.Vb 1 +\& X509 *x; +\& +\& PEM_read_bio_X509(bp, &x, 0, NULL); +.Ve +.PP +this is a bug because an attempt will be made to reuse the data at \fIx\fR +which is an uninitialised pointer. +.PP +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. +.SH "PEM ENCRYPTION FORMAT" +.IX Header "PEM ENCRYPTION FORMAT" +These old \fBPrivateKey\fR routines use a non standard technique for encryption. +.PP +The private key (or other data) takes the following form: +.PP +.Vb 3 +\& \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\- +\& Proc\-Type: 4,ENCRYPTED +\& DEK\-Info: DES\-EDE3\-CBC,3F17F5316E2BAC89 +\& +\& ...base64 encoded data... +\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\- +.Ve +.PP +The line beginning with \fIProc\-Type\fR contains the version and the +protection on the encapsulated data. The line beginning \fIDEK\-Info\fR +contains two comma separated values: the encryption algorithm name as +used by \fBEVP_get_cipherbyname()\fR and an initialization vector used by the +cipher encoded as a set of hexadecimal digits. After those two lines is +the base64\-encoded encrypted data. +.PP +The encryption key is derived using \fBEVP_BytesToKey()\fR. The cipher\*(Aqs +initialization vector is passed to \fBEVP_BytesToKey()\fR as the \fIsalt\fR +parameter. Internally, \fBPKCS5_SALT_LEN\fR bytes of the salt are used +(regardless of the size of the initialization vector). The user\*(Aqs +password is passed to \fBEVP_BytesToKey()\fR using the \fIdata\fR and \fIdatal\fR +parameters. Finally, the library uses an iteration count of 1 for +\&\fBEVP_BytesToKey()\fR. +.PP +The \fIkey\fR derived by \fBEVP_BytesToKey()\fR along with the original initialization +vector is then used to decrypt the encrypted data. The \fIiv\fR produced by +\&\fBEVP_BytesToKey()\fR is not utilized or needed, and NULL should be passed to +the function. +.PP +The pseudo code to derive the key would look similar to: +.PP +.Vb 2 +\& EVP_CIPHER* cipher = EVP_des_ede3_cbc(); +\& EVP_MD* md = EVP_md5(); +\& +\& unsigned int nkey = EVP_CIPHER_get_key_length(cipher); +\& unsigned int niv = EVP_CIPHER_get_iv_length(cipher); +\& unsigned char key[nkey]; +\& unsigned char iv[niv]; +\& +\& memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); +\& rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); +\& if (rc != nkey) +\& /* Error */ +\& +\& /* On success, use key and iv to initialize the cipher */ +.Ve +.SH BUGS +.IX Header "BUGS" +The PEM read routines in some versions of OpenSSL will not correctly reuse +an existing structure. Therefore, the following: +.PP +.Vb 1 +\& PEM_read_bio_X509(bp, &x, 0, NULL); +.Ve +.PP +where \fIx\fR already contains a valid certificate, may not work, whereas: +.PP +.Vb 2 +\& X509_free(x); +\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); +.Ve +.PP +is guaranteed to work. It is always acceptable for \fIx\fR to contain a newly +allocated, empty \fBX509\fR object (for example allocated via \fBX509_new_ex\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The read routines return either a pointer to the structure read or NULL +if an error occurred. +.PP +The write routines return 1 for success or 0 for failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +Although the PEM routines take several arguments in almost all applications +most of them are set to 0 or NULL. +.PP +To read a certificate with a library context in PEM format from a BIO: +.PP +.Vb 1 +\& X509 *x = X509_new_ex(libctx, NULL); +\& +\& if (x == NULL) +\& /* Error */ +\& +\& if (PEM_read_bio_X509(bp, &x, 0, NULL) == NULL) +\& /* Error */ +.Ve +.PP +Read a certificate in PEM format from a BIO: +.PP +.Vb 1 +\& X509 *x; +\& +\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); +\& if (x == NULL) +\& /* Error */ +.Ve +.PP +Alternative method: +.PP +.Vb 1 +\& X509 *x = NULL; +\& +\& if (!PEM_read_bio_X509(bp, &x, 0, NULL)) +\& /* Error */ +.Ve +.PP +Write a certificate to a BIO: +.PP +.Vb 2 +\& if (!PEM_write_bio_X509(bp, x)) +\& /* Error */ +.Ve +.PP +Write a private key (using traditional format) to a BIO using +triple DES encryption, the pass phrase is prompted for: +.PP +.Vb 2 +\& if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) +\& /* Error */ +.Ve +.PP +Write a private key (using PKCS#8 format) to a BIO using triple +DES encryption, using the pass phrase "hello": +.PP +.Vb 3 +\& if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), +\& NULL, 0, 0, "hello")) +\& /* Error */ +.Ve +.PP +Read a private key from a BIO using a pass phrase callback: +.PP +.Vb 3 +\& key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); +\& if (key == NULL) +\& /* Error */ +.Ve +.PP +Skeleton pass phrase callback: +.PP +.Vb 2 +\& int pass_cb(char *buf, int size, int rwflag, void *u) +\& { +\& +\& /* We\*(Aqd probably do something else if \*(Aqrwflag\*(Aq is 1 */ +\& printf("Enter pass phrase for \e"%s\e"\en", (char *)u); +\& +\& /* get pass phrase, length \*(Aqlen\*(Aq into \*(Aqtmp\*(Aq */ +\& char *tmp = "hello"; +\& if (tmp == NULL) /* An error occurred */ +\& return \-1; +\& +\& size_t len = strlen(tmp); +\& +\& if (len > size) +\& len = size; +\& memcpy(buf, tmp, len); +\& return len; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EncryptInit\fR\|(3), \fBEVP_BytesToKey\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The old Netscape certificate sequences were no longer documented +in OpenSSL 1.1.0; applications should use the PKCS7 standard instead +as they will be formally deprecated in a future releases. +.PP +\&\fBPEM_read_bio_PrivateKey_ex()\fR, \fBPEM_read_PrivateKey_ex()\fR, +\&\fBPEM_read_bio_PUBKEY_ex()\fR, \fBPEM_read_PUBKEY_ex()\fR and +\&\fBPEM_read_bio_Parameters_ex()\fR were introduced in OpenSSL 3.0. +.PP +The functions \fBPEM_read_bio_RSAPrivateKey()\fR, \fBPEM_read_RSAPrivateKey()\fR, +\&\fBPEM_write_bio_RSAPrivateKey()\fR, \fBPEM_write_RSAPrivateKey()\fR, +\&\fBPEM_read_bio_RSAPublicKey()\fR, \fBPEM_read_RSAPublicKey()\fR, +\&\fBPEM_write_bio_RSAPublicKey()\fR, \fBPEM_write_RSAPublicKey()\fR, +\&\fBPEM_read_bio_RSA_PUBKEY()\fR, \fBPEM_read_RSA_PUBKEY()\fR, +\&\fBPEM_write_bio_RSA_PUBKEY()\fR, \fBPEM_write_RSA_PUBKEY()\fR, +\&\fBPEM_read_bio_DSAPrivateKey()\fR, \fBPEM_read_DSAPrivateKey()\fR, +\&\fBPEM_write_bio_DSAPrivateKey()\fR, \fBPEM_write_DSAPrivateKey()\fR, +\&\fBPEM_read_bio_DSA_PUBKEY()\fR, \fBPEM_read_DSA_PUBKEY()\fR, +\&\fBPEM_write_bio_DSA_PUBKEY()\fR, \fBPEM_write_DSA_PUBKEY()\fR; +\&\fBPEM_read_bio_DSAparams()\fR, \fBPEM_read_DSAparams()\fR, +\&\fBPEM_write_bio_DSAparams()\fR, \fBPEM_write_DSAparams()\fR, +\&\fBPEM_read_bio_DHparams()\fR, \fBPEM_read_DHparams()\fR, +\&\fBPEM_write_bio_DHparams()\fR and \fBPEM_write_DHparams()\fR were deprecated in 3.0. +.PP +\&\fBPEM_read_bio_X509_ACERT()\fR, \fBPEM_read_X509_ACERT()\fR, +\&\fBPEM_write_bio_X509_ACERT()\fR, \fBPEM_write_X509_ACERT()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_read_bio_ex.3 b/static/netbsd/man3/PEM_read_bio_ex.3 new file mode 100644 index 00000000..6a1a011b --- /dev/null +++ b/static/netbsd/man3/PEM_read_bio_ex.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: PEM_read_bio_ex.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_read_bio_ex 3" +.TH PEM_read_bio_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_read_bio_ex, PEM_FLAG_SECURE, PEM_FLAG_EAY_COMPATIBLE, +PEM_FLAG_ONLY_B64 \- read PEM format files with custom processing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define PEM_FLAG_SECURE 0x1 +\& #define PEM_FLAG_EAY_COMPATIBLE 0x2 +\& #define PEM_FLAG_ONLY_B64 0x4 +\& int PEM_read_bio_ex(BIO *in, char **name, char **header, +\& unsigned char **data, long *len, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPEM_read_bio_ex()\fR reads in PEM formatted data from an input BIO, outputting +the name of the type of contained data, the header information regarding +the possibly encrypted data, and the binary data payload (after base64 decoding). +It should generally only be used to implement PEM_read_bio_\-family functions +for specific data types or other usage, but is exposed to allow greater flexibility +over how processing is performed, if needed. +.PP +If PEM_FLAG_SECURE is set, the intermediate buffers used to read in lines of +input are allocated from the secure heap. +.PP +If PEM_FLAG_EAY_COMPATIBLE is set, a simple algorithm is used to remove whitespace +and control characters from the end of each line, so as to be compatible with +the historical behavior of \fBPEM_read_bio()\fR. +.PP +If PEM_FLAG_ONLY_B64 is set, all characters are required to be valid base64 +characters (or newlines); non\-base64 characters are treated as end of input. +.PP +If neither PEM_FLAG_EAY_COMPATIBLE or PEM_FLAG_ONLY_B64 is set, control characters +are ignored. +.PP +If both PEM_FLAG_EAY_COMPATIBLE and PEM_FLAG_ONLY_B64 are set, an error is returned; +these options are not compatible with each other. +.SH NOTES +.IX Header "NOTES" +The caller must release the storage allocated for *name, *header, and *data. +If PEM_FLAG_SECURE was set, use \fBOPENSSL_secure_free()\fR; otherwise, +\&\fBOPENSSL_free()\fR is used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_read_bio_ex()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_bytes_read_bio\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBPEM_read_bio_ex()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_write_bio_CMS_stream.3 b/static/netbsd/man3/PEM_write_bio_CMS_stream.3 new file mode 100644 index 00000000..1ca0b7f3 --- /dev/null +++ b/static/netbsd/man3/PEM_write_bio_CMS_stream.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: PEM_write_bio_CMS_stream.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_write_bio_CMS_stream 3" +.TH PEM_write_bio_CMS_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_write_bio_CMS_stream \- output CMS_ContentInfo structure in PEM format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPEM_write_bio_CMS_stream()\fR outputs a CMS_ContentInfo structure in PEM format. +.PP +It is otherwise identical to the function \fBSMIME_write_CMS()\fR. +.SH NOTES +.IX Header "NOTES" +This function is effectively a version of the \fBPEM_write_bio_CMS()\fR supporting +streaming. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_write_bio_CMS_stream()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_verify\fR\|(3), \fBCMS_encrypt\fR\|(3) +\&\fBCMS_decrypt\fR\|(3), +\&\fBPEM_write\fR\|(3), +\&\fBSMIME_write_CMS\fR\|(3), +\&\fBi2d_CMS_bio_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBPEM_write_bio_CMS_stream()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PEM_write_bio_PKCS7_stream.3 b/static/netbsd/man3/PEM_write_bio_PKCS7_stream.3 new file mode 100644 index 00000000..d52d7c70 --- /dev/null +++ b/static/netbsd/man3/PEM_write_bio_PKCS7_stream.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: PEM_write_bio_PKCS7_stream.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PEM_write_bio_PKCS7_stream 3" +.TH PEM_write_bio_PKCS7_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PEM_write_bio_PKCS7_stream \- output PKCS7 structure in PEM format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPEM_write_bio_PKCS7_stream()\fR outputs a PKCS7 structure in PEM format. +.PP +It is otherwise identical to the function \fBSMIME_write_PKCS7()\fR. +.SH NOTES +.IX Header "NOTES" +This function is effectively a version of the \fBPEM_write_bio_PKCS7()\fR supporting +streaming. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPEM_write_bio_PKCS7_stream()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_sign\fR\|(3), +\&\fBPKCS7_verify\fR\|(3), \fBPKCS7_encrypt\fR\|(3) +\&\fBPKCS7_decrypt\fR\|(3), +\&\fBSMIME_write_PKCS7\fR\|(3), +\&\fBi2d_PKCS7_bio_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBPEM_write_bio_PKCS7_stream()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_PBE_keyivgen.3 b/static/netbsd/man3/PKCS12_PBE_keyivgen.3 new file mode 100644 index 00000000..838f739d --- /dev/null +++ b/static/netbsd/man3/PKCS12_PBE_keyivgen.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: PKCS12_PBE_keyivgen.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_PBE_keyivgen 3" +.TH PKCS12_PBE_keyivgen 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_PBE_keyivgen, PKCS12_PBE_keyivgen_ex, +PKCS12_pbe_crypt, PKCS12_pbe_crypt_ex \- PKCS#12 Password based encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md_type, int en_de); +\& int PKCS12_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md_type, int en_de, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& unsigned char *PKCS12_pbe_crypt(const X509_ALGOR *algor, +\& const char *pass, int passlen, +\& const unsigned char *in, int inlen, +\& unsigned char **data, int *datalen, +\& int en_de); +\& unsigned char *PKCS12_pbe_crypt_ex(const X509_ALGOR *algor, +\& const char *pass, int passlen, +\& const unsigned char *in, int inlen, +\& unsigned char **data, int *datalen, +\& int en_de, OSSL_LIB_CTX *libctx, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_PBE_keyivgen()\fR and \fBPKCS12_PBE_keyivgen_ex()\fR take a password \fIpass\fR of +length \fIpasslen\fR, parameters \fIparam\fR and a message digest function \fImd_type\fR +and perform a key derivation according to PKCS#12. The resulting key is +then used to initialise the cipher context \fIctx\fR with a cipher \fIcipher\fR for +encryption (\fIen_de\fR=1) or decryption (\fIen_de\fR=0). +.PP +\&\fBPKCS12_PBE_keyivgen_ex()\fR also allows the application to specify a library context +\&\fIlibctx\fR and property query \fIpropq\fR to select appropriate algorithm +implementations. +.PP +\&\fBPKCS12_pbe_crypt()\fR and \fBPKCS12_pbe_crypt_ex()\fR will encrypt or decrypt a buffer +based on the algorithm in \fIalgor\fR and password \fIpass\fR of length \fIpasslen\fR. +The input is from \fIin\fR of length \fIinlen\fR and output is into a malloc\*(Aqd buffer +returned in \fI*data\fR of length \fIdatalen\fR. The operation is determined by \fIen_de\fR, +encryption (\fIen_de\fR=1) or decryption (\fIen_de\fR=0). +.PP +\&\fBPKCS12_pbe_crypt_ex()\fR allows the application to specify a library context +\&\fIlibctx\fR and property query \fIpropq\fR to select appropriate algorithm +implementations. +.PP +\&\fIpass\fR is the password used in the derivation of length \fIpasslen\fR. \fIpass\fR +is an optional parameter and can be NULL. If \fIpasslen\fR is \-1, then the +function will calculate the length of \fIpass\fR using \fBstrlen()\fR. +.PP +\&\fIsalt\fR is the salt used in the derivation of length \fIsaltlen\fR. If the +\&\fIsalt\fR is NULL, then \fIsaltlen\fR must be 0. The function will not +attempt to calculate the length of the \fIsalt\fR because it is not assumed to +be NULL terminated. +.PP +\&\fIiter\fR is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +\&\fIiter\fR less than 1 is treated as a single iteration. +.PP +\&\fIdigest\fR is the message digest function used in the derivation. +.PP +Functions ending in \fB_ex()\fR take optional parameters \fIlibctx\fR and \fIpropq\fR which +are used to select appropriate algorithm implementations. +.SH NOTES +.IX Header "NOTES" +The functions are typically used in PKCS#12 to encrypt objects. +.PP +These functions make no assumption regarding the given password. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_PBE_keyivgen()\fR, \fBPKCS12_PBE_keyivgen_ex()\fR return 1 on success or 0 on error. +.PP +\&\fBPKCS12_pbe_crypt()\fR and \fBPKCS12_pbe_crypt_ex()\fR return a buffer containing the +output or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PBE_CipherInit_ex\fR\|(3), +\&\fBPKCS8_encrypt_ex\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_PBE_keyivgen_ex()\fR and \fBPKCS12_pbe_crypt_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_SAFEBAG_create_cert.3 b/static/netbsd/man3/PKCS12_SAFEBAG_create_cert.3 new file mode 100644 index 00000000..4962eb23 --- /dev/null +++ b/static/netbsd/man3/PKCS12_SAFEBAG_create_cert.3 @@ -0,0 +1,156 @@ +.\" $NetBSD: PKCS12_SAFEBAG_create_cert.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_SAFEBAG_create_cert 3" +.TH PKCS12_SAFEBAG_create_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_SAFEBAG_create_cert, PKCS12_SAFEBAG_create_crl, +PKCS12_SAFEBAG_create_secret, PKCS12_SAFEBAG_create0_p8inf, +PKCS12_SAFEBAG_create0_pkcs8, PKCS12_SAFEBAG_create_pkcs8_encrypt, +PKCS12_SAFEBAG_create_pkcs8_encrypt_ex \- Create PKCS#12 safeBag objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_cert(X509 *x509); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_crl(X509_CRL *crl); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_secret(int type, int vtype, +\& const unsigned char* value, +\& int len); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create0_p8inf(PKCS8_PRIV_KEY_INFO *p8); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create0_pkcs8(X509_SIG *p8); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_pkcs8_encrypt(int pbe_nid, +\& const char *pass, +\& int passlen, +\& unsigned char *salt, +\& int saltlen, int iter, +\& PKCS8_PRIV_KEY_INFO *p8inf); +\& PKCS12_SAFEBAG *PKCS12_SAFEBAG_create_pkcs8_encrypt_ex(int pbe_nid, +\& const char *pass, +\& int passlen, +\& unsigned char *salt, +\& int saltlen, int iter, +\& PKCS8_PRIV_KEY_INFO *p8inf, +\& OSSL_LIB_CTX *ctx, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_SAFEBAG_create_cert()\fR creates a new \fBPKCS12_SAFEBAG\fR of type \fBNID_certBag\fR +containing the supplied certificate. +.PP +\&\fBPKCS12_SAFEBAG_create_crl()\fR creates a new \fBPKCS12_SAFEBAG\fR of type \fBNID_crlBag\fR +containing the supplied crl. +.PP +\&\fBPKCS12_SAFEBAG_create_secret()\fR creates a new \fBPKCS12_SAFEBAG\fR of type +corresponding to a PKCS#12 \fBsecretBag\fR. The \fBsecretBag\fR contents are tagged as +\&\fItype\fR with an ASN1 value of type \fIvtype\fR constructed using the bytes in +\&\fIvalue\fR of length \fIlen\fR. +.PP +\&\fBPKCS12_SAFEBAG_create0_p8inf()\fR creates a new \fBPKCS12_SAFEBAG\fR of type \fBNID_keyBag\fR +containing the supplied PKCS8 structure. +.PP +\&\fBPKCS12_SAFEBAG_create0_pkcs8()\fR creates a new \fBPKCS12_SAFEBAG\fR of type +\&\fBNID_pkcs8ShroudedKeyBag\fR containing the supplied PKCS8 structure. +.PP +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt()\fR creates a new \fBPKCS12_SAFEBAG\fR of type +\&\fBNID_pkcs8ShroudedKeyBag\fR by encrypting the supplied PKCS8 \fIp8inf\fR. +If \fIpbe_nid\fR is 0, a default encryption algorithm is used. \fIpass\fR is the +passphrase and \fIiter\fR is the iteration count. If \fIiter\fR is zero then a default +value of 2048 is used. If \fIsalt\fR is NULL then a salt is generated randomly. +.PP +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex()\fR is identical to \fBPKCS12_SAFEBAG_create_pkcs8_encrypt()\fR +but allows for a library context \fIctx\fR and property query \fIpropq\fR to be used to select +algorithm implementations. +.SH NOTES +.IX Header "NOTES" +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt()\fR makes assumptions regarding the encoding of the given pass +phrase. +See \fBpassphrase\-encoding\fR\|(7) for more information. +.PP +\&\fBPKCS12_SAFEBAG_create_secret()\fR was added in OpenSSL 3.0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All of these functions return a valid \fBPKCS12_SAFEBAG\fR structure or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3), +\&\fBPKCS12_add_safe\fR\|(3), +\&\fBPKCS12_add_safes\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_SAFEBAG_get0_attrs.3 b/static/netbsd/man3/PKCS12_SAFEBAG_get0_attrs.3 new file mode 100644 index 00000000..94ce9113 --- /dev/null +++ b/static/netbsd/man3/PKCS12_SAFEBAG_get0_attrs.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: PKCS12_SAFEBAG_get0_attrs.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_SAFEBAG_get0_attrs 3" +.TH PKCS12_SAFEBAG_get0_attrs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_SAFEBAG_get0_attrs, PKCS12_get_attr_gen +\&\- Retrieve attributes from a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const STACK_OF(X509_ATTRIBUTE) *PKCS12_SAFEBAG_get0_attrs(const PKCS12_SAFEBAG *bag); +\& +\& ASN1_TYPE *PKCS12_get_attr_gen(const STACK_OF(X509_ATTRIBUTE) *attrs, +\& int attr_nid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_SAFEBAG_get0_attrs()\fR retrieves the stack of \fBX509_ATTRIBUTE\fRs from a +PKCS#12 safeBag. \fIbag\fR is the \fBPKCS12_SAFEBAG\fR to retrieve the attributes from. +.PP +\&\fBPKCS12_get_attr_gen()\fR retrieves an attribute by NID from a stack of +\&\fBX509_ATTRIBUTE\fRs. \fIattr_nid\fR is the NID of the attribute to retrieve. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_SAFEBAG_get0_attrs()\fR returns the stack of \fBX509_ATTRIBUTE\fRs from a +PKCS#12 safeBag, which could be empty. +.PP +\&\fBPKCS12_get_attr_gen()\fR returns an \fBASN1_TYPE\fR object containing the attribute, +or NULL if the attribute was either not present or an error occurred. +.PP +\&\fBPKCS12_get_attr_gen()\fR does not allocate a new attribute. The returned attribute +is still owned by the \fBPKCS12_SAFEBAG\fR in which it resides. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_get_friendlyname\fR\|(3), +\&\fBPKCS12_add_friendlyname_asc\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_SAFEBAG_get1_cert.3 b/static/netbsd/man3/PKCS12_SAFEBAG_get1_cert.3 new file mode 100644 index 00000000..a88475c8 --- /dev/null +++ b/static/netbsd/man3/PKCS12_SAFEBAG_get1_cert.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: PKCS12_SAFEBAG_get1_cert.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_SAFEBAG_get1_cert 3" +.TH PKCS12_SAFEBAG_get1_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_SAFEBAG_get0_attr, PKCS12_SAFEBAG_get0_type, +PKCS12_SAFEBAG_get_nid, PKCS12_SAFEBAG_get_bag_nid, +PKCS12_SAFEBAG_get0_bag_obj, PKCS12_SAFEBAG_get0_bag_type, +PKCS12_SAFEBAG_get1_cert_ex, PKCS12_SAFEBAG_get1_cert, +PKCS12_SAFEBAG_get1_crl_ex, PKCS12_SAFEBAG_get1_crl, +PKCS12_SAFEBAG_get0_safes, PKCS12_SAFEBAG_get0_p8inf, +PKCS12_SAFEBAG_get0_pkcs8 \- Get objects from a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const ASN1_TYPE *PKCS12_SAFEBAG_get0_attr(const PKCS12_SAFEBAG *bag, +\& int attr_nid); +\& const ASN1_OBJECT *PKCS12_SAFEBAG_get0_type(const PKCS12_SAFEBAG *bag); +\& int PKCS12_SAFEBAG_get_nid(const PKCS12_SAFEBAG *bag); +\& int PKCS12_SAFEBAG_get_bag_nid(const PKCS12_SAFEBAG *bag); +\& const ASN1_TYPE *PKCS12_SAFEBAG_get0_bag_obj(const PKCS12_SAFEBAG *bag); +\& const ASN1_OBJECT *PKCS12_SAFEBAG_get0_bag_type(const PKCS12_SAFEBAG *bag); +\& X509_CRL *PKCS12_SAFEBAG_get1_cert_ex(const PKCS12_SAFEBAG *bag, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& X509 *PKCS12_SAFEBAG_get1_cert(const PKCS12_SAFEBAG *bag); +\& X509_CRL *PKCS12_SAFEBAG_get1_crl_ex(const PKCS12_SAFEBAG *bag, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& X509_CRL *PKCS12_SAFEBAG_get1_crl(const PKCS12_SAFEBAG *bag); +\& const STACK_OF(PKCS12_SAFEBAG) *PKCS12_SAFEBAG_get0_safes(const PKCS12_SAFEBAG *bag); +\& const PKCS8_PRIV_KEY_INFO *PKCS12_SAFEBAG_get0_p8inf(const PKCS12_SAFEBAG *bag); +\& const X509_SIG *PKCS12_SAFEBAG_get0_pkcs8(const PKCS12_SAFEBAG *bag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_SAFEBAG_get0_attr()\fR gets the attribute value corresponding to the \fBattr_nid\fR. +.PP +\&\fBPKCS12_SAFEBAG_get0_type()\fR gets the \fBsafeBag\fR type as an OID, whereas +\&\fBPKCS12_SAFEBAG_get_nid()\fR gets the \fBsafeBag\fR type as an NID, which could be +\&\fBNID_certBag\fR, \fBNID_crlBag\fR, \fBNID_keyBag\fR, \fBNID_secretBag\fR, \fBNID_safeContentsBag\fR +or \fBNID_pkcs8ShroudedKeyBag\fR. +.PP +\&\fBPKCS12_SAFEBAG_get_bag_nid()\fR gets the type of the object contained within the +\&\fBPKCS12_SAFEBAG\fR. This corresponds to the bag type for most bags, but can be +arbitrary for \fBsecretBag\fRs. \fBPKCS12_SAFEBAG_get0_bag_type()\fR gets this type as an OID. +.PP +\&\fBPKCS12_SAFEBAG_get0_bag_obj()\fR retrieves the object contained within the safeBag. +.PP +\&\fBPKCS12_SAFEBAG_get1_cert_ex()\fR and \fBPKCS12_SAFEBAG_get1_crl_ex()\fR return new \fBX509\fR or +\&\fBX509_CRL\fR objects from the item in the safeBag. \fIlibctx\fR and \fIpropq\fR are used when +fetching algorithms, and may optionally be set to NULL. +.PP +\&\fBPKCS12_SAFEBAG_get1_cert()\fR and \fBPKCS12_SAFEBAG_get1_crl()\fR are the same as +\&\fBPKCS12_SAFEBAG_get1_cert_ex()\fR and \fBPKCS12_SAFEBAG_get1_crl_ex()\fR and set the \fIlibctx\fR and +\&\fIprop\fR to NULL. This will use the default library context. +.PP +\&\fBPKCS12_SAFEBAG_get0_p8inf()\fR and \fBPKCS12_SAFEBAG_get0_pkcs8()\fR return the PKCS8 object +from a PKCS8shroudedKeyBag or a keyBag. +.PP +\&\fBPKCS12_SAFEBAG_get0_safes()\fR retrieves the set of \fBsafeBags\fR contained within a +safeContentsBag. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_SAFEBAG_get_nid()\fR and \fBPKCS12_SAFEBAG_get_bag_nid()\fR return the NID of the safeBag +or bag object, or \-1 if there is no corresponding NID. +Other functions return a valid object of the specified type or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3), +\&\fBPKCS12_add_safe\fR\|(3), +\&\fBPKCS12_add_safes\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBPKCS12_SAFEBAG_get1_cert_ex()\fR and \fBPKCS12_SAFEBAG_get1_crl_ex()\fR were +added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_SAFEBAG_set0_attrs.3 b/static/netbsd/man3/PKCS12_SAFEBAG_set0_attrs.3 new file mode 100644 index 00000000..f9c9290c --- /dev/null +++ b/static/netbsd/man3/PKCS12_SAFEBAG_set0_attrs.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: PKCS12_SAFEBAG_set0_attrs.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_SAFEBAG_set0_attrs 3" +.TH PKCS12_SAFEBAG_set0_attrs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_SAFEBAG_set0_attrs +\&\- Set attributes for a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void PKCS12_SAFEBAG_set0_attrs(PKCS12_SAFEBAG *bag, STACK_OF(X509_ATTRIBUTE) *attrs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_SAFEBAG_set0_attrs()\fR assigns the stack of \fBX509_ATTRIBUTE\fRs to a +PKCS#12 safeBag. \fIbag\fR is the \fBPKCS12_SAFEBAG\fR to assign the attributes to. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_SAFEBAG_set0_attrs()\fR does not return a value. +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add1_attr_by_NID.3 b/static/netbsd/man3/PKCS12_add1_attr_by_NID.3 new file mode 100644 index 00000000..183e50be --- /dev/null +++ b/static/netbsd/man3/PKCS12_add1_attr_by_NID.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: PKCS12_add1_attr_by_NID.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add1_attr_by_NID 3" +.TH PKCS12_add1_attr_by_NID 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add1_attr_by_NID, PKCS12_add1_attr_by_txt \- Add an attribute to a PKCS#12 +safeBag structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_add1_attr_by_NID(PKCS12_SAFEBAG *bag, int nid, int type, +\& const unsigned char *bytes, int len); +\& int PKCS12_add1_attr_by_txt(PKCS12_SAFEBAG *bag, const char *attrname, int type, +\& const unsigned char *bytes, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions add a PKCS#12 Attribute to the Attribute Set of the \fBbag\fR. +.PP +\&\fBPKCS12_add1_attr_by_NID()\fR adds an attribute of type \fBnid\fR with a value of ASN1 +type \fBtype\fR constructed using \fBlen\fR bytes from \fBbytes\fR. +.PP +\&\fBPKCS12_add1_attr_by_txt()\fR adds an attribute of type \fBattrname\fR with a value of +ASN1 type \fBtype\fR constructed using \fBlen\fR bytes from \fBbytes\fR. +.SH NOTES +.IX Header "NOTES" +These functions do not check whether an existing attribute of the same type is +present. There can be multiple attributes with the same type assigned to a +safeBag. +.PP +Both functions were added in OpenSSL 3.0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +A return value of 1 indicates success, 0 indicates failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add_CSPName_asc.3 b/static/netbsd/man3/PKCS12_add_CSPName_asc.3 new file mode 100644 index 00000000..a1714626 --- /dev/null +++ b/static/netbsd/man3/PKCS12_add_CSPName_asc.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: PKCS12_add_CSPName_asc.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add_CSPName_asc 3" +.TH PKCS12_add_CSPName_asc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add_CSPName_asc \- Add a Microsoft CSP Name attribute to a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_add_CSPName_asc(PKCS12_SAFEBAG *bag, const char *name, int namelen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_add_CSPName_asc()\fR adds an ASCII string representation of the Microsoft CSP Name attribute to a PKCS#12 safeBag. +.PP +\&\fIbag\fR is the \fBPKCS12_SAFEBAG\fR to add the attribute to. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_add_friendlyname_asc\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add_cert.3 b/static/netbsd/man3/PKCS12_add_cert.3 new file mode 100644 index 00000000..9afcc182 --- /dev/null +++ b/static/netbsd/man3/PKCS12_add_cert.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: PKCS12_add_cert.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add_cert 3" +.TH PKCS12_add_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add_cert, PKCS12_add_key, PKCS12_add_key_ex, +PKCS12_add_secret \- Add an object to a set of PKCS#12 safeBags +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS12_SAFEBAG *PKCS12_add_cert(STACK_OF(PKCS12_SAFEBAG) **pbags, X509 *cert); +\& PKCS12_SAFEBAG *PKCS12_add_key(STACK_OF(PKCS12_SAFEBAG) **pbags, +\& EVP_PKEY *key, int key_usage, int iter, +\& int key_nid, const char *pass); +\& PKCS12_SAFEBAG *PKCS12_add_key_ex(STACK_OF(PKCS12_SAFEBAG) **pbags, +\& EVP_PKEY *key, int key_usage, int iter, +\& int key_nid, const char *pass, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& +\& PKCS12_SAFEBAG *PKCS12_add_secret(STACK_OF(PKCS12_SAFEBAG) **pbags, +\& int nid_type, const unsigned char *value, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions create a new \fBPKCS12_SAFEBAG\fR and add it to the set of safeBags +in \fIpbags\fR. +.PP +\&\fBPKCS12_add_cert()\fR creates a PKCS#12 certBag containing the supplied +certificate and adds this to the set of PKCS#12 safeBags. +.PP +\&\fBPKCS12_add_key()\fR creates a PKCS#12 keyBag (unencrypted) or a pkcs8shroudedKeyBag +(encrypted) containing the supplied \fBEVP_PKEY\fR and adds this to the set of PKCS#12 +safeBags. If \fIkey_nid\fR is not \-1 then the key is encrypted with the supplied +algorithm, using \fIpass\fR as the passphrase and \fIiter\fR as the iteration count. If +\&\fIiter\fR is zero then a default value for iteration count of 2048 is used. +.PP +\&\fBPKCS12_add_key_ex()\fR is identical to \fBPKCS12_add_key()\fR but allows for a library +context \fIctx\fR and property query \fIpropq\fR to be used to select algorithm +implementations. +.PP +\&\fBPKCS12_add_secret()\fR creates a PKCS#12 secretBag with an OID corresponding to +the supplied \fInid_type\fR containing the supplied value as an ASN1 octet string. +This is then added to the set of PKCS#12 safeBags. +.SH NOTES +.IX Header "NOTES" +If a certificate contains an \fIalias\fR or a \fIkeyid\fR then this will be +used for the corresponding \fBfriendlyName\fR or \fBlocalKeyID\fR in the +PKCS12 structure. +.PP +\&\fBPKCS12_add_key()\fR makes assumptions regarding the encoding of the given pass +phrase. +See \fBpassphrase\-encoding\fR\|(7) for more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +A valid \fBPKCS12_SAFEBAG\fR structure or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_add_secret()\fR and \fBPKCS12_add_key_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add_friendlyname_asc.3 b/static/netbsd/man3/PKCS12_add_friendlyname_asc.3 new file mode 100644 index 00000000..d213a8f9 --- /dev/null +++ b/static/netbsd/man3/PKCS12_add_friendlyname_asc.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: PKCS12_add_friendlyname_asc.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add_friendlyname_asc 3" +.TH PKCS12_add_friendlyname_asc 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add_friendlyname_asc, PKCS12_add_friendlyname_utf8, +PKCS12_add_friendlyname_uni \- Functions to add the friendlyname attribute to a +PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_add_friendlyname_asc(PKCS12_SAFEBAG *bag, const char *name, +\& int namelen); +\& +\& int PKCS12_add_friendlyname_utf8(PKCS12_SAFEBAG *bag, const char *name, +\& int namelen); +\& +\& int PKCS12_add_friendlyname_uni(PKCS12_SAFEBAG *bag, +\& const unsigned char *name, int namelen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_add_friendlyname_asc()\fR adds an ASCII string representation of the PKCS#9 +friendlyName attribute to a PKCS#12 safeBag. +.PP +\&\fBPKCS12_add_friendlyname_utf8()\fR adds a UTF\-8 string representation of the PKCS#9 +friendlyName attribute to a PKCS#12 safeBag. +.PP +\&\fBPKCS12_add_friendlyname_uni()\fR adds a Unicode string representation of the PKCS#9 +friendlyName attribute to a PKCS#12 safeBag. +.PP +\&\fIbag\fR is the \fBPKCS12_SAFEBAG\fR to add the attribute to. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_get_friendlyname\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add_localkeyid.3 b/static/netbsd/man3/PKCS12_add_localkeyid.3 new file mode 100644 index 00000000..9832c0dd --- /dev/null +++ b/static/netbsd/man3/PKCS12_add_localkeyid.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: PKCS12_add_localkeyid.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add_localkeyid 3" +.TH PKCS12_add_localkeyid 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add_localkeyid \- Add the localKeyId attribute to a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, const char *name, +\& int namelen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_add_localkeyid()\fR adds an octet string representation of the PKCS#9 +localKeyId attribute to a PKCS#12 safeBag. +.PP +\&\fIbag\fR is the \fBPKCS12_SAFEBAG\fR to add the attribute to. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_add_friendlyname_asc\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_add_safe.3 b/static/netbsd/man3/PKCS12_add_safe.3 new file mode 100644 index 00000000..9bbc6a64 --- /dev/null +++ b/static/netbsd/man3/PKCS12_add_safe.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: PKCS12_add_safe.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_add_safe 3" +.TH PKCS12_add_safe 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_add_safe, PKCS12_add_safe_ex, +PKCS12_add_safes, PKCS12_add_safes_ex \- Create and add objects to a PKCS#12 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_add_safe(STACK_OF(PKCS7) **psafes, STACK_OF(PKCS12_SAFEBAG) *bags, +\& int safe_nid, int iter, const char *pass); +\& int PKCS12_add_safe_ex(STACK_OF(PKCS7) **psafes, STACK_OF(PKCS12_SAFEBAG) *bags, +\& int safe_nid, int iter, const char *pass, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& +\& PKCS12 *PKCS12_add_safes(STACK_OF(PKCS7) *safes, int p7_nid); +\& PKCS12 *PKCS12_add_safes_ex(STACK_OF(PKCS7) *safes, int p7_nid, +\& OSSL_LIB_CTX *ctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_add_safe()\fR creates a new PKCS7 contentInfo containing the supplied +\&\fBPKCS12_SAFEBAG\fRs and adds this to a set of PKCS7 contentInfos. Its type +depends on the value of \fBsafe_nid\fR: +.IP \(bu 4 +If \fIsafe_nid\fR is \-1, a plain PKCS7 \fIdata\fR contentInfo is created. +.IP \(bu 4 +If \fIsafe_nid\fR is a valid PBE algorithm NID, a PKCS7 \fBencryptedData\fR +contentInfo is created. The algorithm uses \fIpass\fR as the passphrase and \fIiter\fR +as the iteration count. If \fIiter\fR is zero then a default value for iteration +count of 2048 is used. +.IP \(bu 4 +If \fIsafe_nid\fR is 0, a PKCS7 \fBencryptedData\fR contentInfo is created using +a default encryption algorithm, currently \fBNID_pbe_WithSHA1And3_Key_TripleDES_CBC\fR. +.PP +\&\fBPKCS12_add_safe_ex()\fR is identical to \fBPKCS12_add_safe()\fR but allows for a library +context \fIctx\fR and property query \fIpropq\fR to be used to select algorithm +implementations. +.PP +\&\fBPKCS12_add_safes()\fR creates a \fBPKCS12\fR structure containing the supplied set of +PKCS7 contentInfos. The \fIsafes\fR are enclosed first within a PKCS7 contentInfo +of type \fIp7_nid\fR. Currently the only supported type is \fBNID_pkcs7_data\fR. +.PP +\&\fBPKCS12_add_safes_ex()\fR is identical to \fBPKCS12_add_safes()\fR but allows for a +library context \fIctx\fR and property query \fIpropq\fR to be used to select +algorithm implementations. +.SH NOTES +.IX Header "NOTES" +\&\fBPKCS12_add_safe()\fR makes assumptions regarding the encoding of the given pass +phrase. +See \fBpassphrase\-encoding\fR\|(7) for more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_add_safe()\fR returns a value of 1 indicating success or 0 for failure. +.PP +\&\fBPKCS12_add_safes()\fR returns a valid \fBPKCS12\fR structure or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_add_safe_ex()\fR and \fBPKCS12_add_safes_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_create.3 b/static/netbsd/man3/PKCS12_create.3 new file mode 100644 index 00000000..bed9851f --- /dev/null +++ b/static/netbsd/man3/PKCS12_create.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: PKCS12_create.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_create 3" +.TH PKCS12_create 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_create, PKCS12_create_ex, PKCS12_create_cb, PKCS12_create_ex2 \- create a PKCS#12 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey, +\& X509 *cert, STACK_OF(X509) *ca, +\& int nid_key, int nid_cert, int iter, int mac_iter, int keytype); +\& PKCS12 *PKCS12_create_ex(const char *pass, const char *name, EVP_PKEY *pkey, +\& X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert, +\& int iter, int mac_iter, int keytype, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& +\& typedef int PKCS12_create_cb(PKCS12_SAFEBAG *bag, void *cbarg); +\& +\& PKCS12 *PKCS12_create_ex2(const char *pass, const char *name, EVP_PKEY *pkey, +\& X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert, +\& int iter, int mac_iter, int keytype, +\& OSSL_LIB_CTX *ctx, const char *propq, +\& PKCS12_create_cb *cb, void *cbarg); +\&=head1 DESCRIPTION +.Ve +.PP +\&\fBPKCS12_create()\fR creates a PKCS#12 structure. +.PP +\&\fIpass\fR is the passphrase to use. \fIname\fR is the \fBfriendlyName\fR to use for +the supplied certificate and key. \fIpkey\fR is the private key to include in +the structure and \fIcert\fR its corresponding certificates. \fIca\fR, if not \fBNULL\fR +is an optional set of certificates to also include in the structure. +.PP +\&\fInid_key\fR and \fInid_cert\fR are the encryption algorithms that should be used +for the key and certificate respectively. The modes +GCM, CCM, XTS, and OCB are unsupported. \fIiter\fR is the encryption algorithm +iteration count to use and \fImac_iter\fR is the MAC iteration count to use. +\&\fIkeytype\fR is the type of key. +.PP +\&\fBPKCS12_create_ex()\fR is identical to \fBPKCS12_create()\fR but allows for a library context +\&\fIctx\fR and property query \fIpropq\fR to be used to select algorithm implementations. +.PP +\&\fBPKCS12_create_ex2()\fR is identical to \fBPKCS12_create_ex()\fR but allows for a user defined +callback \fIcb\fR of type \fBPKCS12_create_cb\fR to be specified and also allows for an +optional argument \fIcbarg\fR to be passed back to the callback. +.PP +The \fIcb\fR if specified will be called for every safebag added to the +PKCS12 structure and allows for optional application processing on the associated +safebag. For example one such use could be to add attributes to the safebag. +.SH NOTES +.IX Header "NOTES" +The parameters \fInid_key\fR, \fInid_cert\fR, \fIiter\fR, \fImac_iter\fR and \fIkeytype\fR +can all be set to zero and sensible defaults will be used. +.PP +These defaults are: AES password based encryption (PBES2 with PBKDF2 and +AES\-256\-CBC) for private keys and certificates, the PBKDF2 and MAC key +derivation iteration count of \fBPKCS12_DEFAULT_ITER\fR (currently 2048), and +MAC algorithm HMAC with SHA2\-256. The MAC key derivation algorithm used +for the outer PKCS#12 structure is PKCS12KDF. +.PP +The default MAC iteration count is 1 in order to retain compatibility with +old software which did not interpret MAC iteration counts. If such compatibility +is not required then \fImac_iter\fR should be set to PKCS12_DEFAULT_ITER. +.PP +\&\fIkeytype\fR adds a flag to the store private key. This is a non standard extension +that is only currently interpreted by MSIE. If set to zero the flag is omitted, +if set to \fBKEY_SIG\fR the key can be used for signing only, if set to \fBKEY_EX\fR +it can be used for signing and encryption. This option was useful for old +export grade software which could use signing only keys of arbitrary size but +had restrictions on the permissible sizes of keys which could be used for +encryption. +.PP +If \fIname\fR is \fBNULL\fR and \fIcert\fR contains an \fIalias\fR then this will be +used for the corresponding \fBfriendlyName\fR in the PKCS12 structure instead. +Similarly, if \fIpkey\fR is NULL and \fIcert\fR contains a \fIkeyid\fR then this will be +used for the corresponding \fBlocalKeyID\fR in the PKCS12 structure instead of the +id calculated from the \fIpkey\fR. +.PP +For all certificates in \fIca\fR then if a certificate contains an \fIalias\fR or +\&\fIkeyid\fR then this will be used for the corresponding \fBfriendlyName\fR or +\&\fBlocalKeyID\fR in the PKCS12 structure. +.PP +Either \fIpkey\fR, \fIcert\fR or both can be \fBNULL\fR to indicate that no key or +certificate is required. In previous versions both had to be present or +a fatal error is returned. +.PP +\&\fInid_key\fR or \fInid_cert\fR can be set to \-1 indicating that no encryption +should be used. +.PP +\&\fImac_iter\fR can be set to \-1 and the MAC will then be omitted entirely. +This can be useful when running with the FIPS provider as the PKCS12KDF +is not a FIPS approvable algorithm. +.PP +\&\fBPKCS12_create()\fR makes assumptions regarding the encoding of the given pass +phrase. +See \fBpassphrase\-encoding\fR\|(7) for more information. +.PP +If \fIcb\fR is specified, then it should return 1 for success and \-1 for a fatal error. +A return of 0 is intended to mean to not add the bag after all. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_create()\fR returns a valid \fBPKCS12\fR structure or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\-PKCS12KDF\fR\|(7), +\&\fBd2i_PKCS12\fR\|(3), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_create_ex()\fR was added in OpenSSL 3.0. +\&\fBPKCS12_create_ex2()\fR was added in OpenSSL 3.2. +.PP +The defaults for encryption algorithms, MAC algorithm, and the MAC key +derivation iteration count were changed in OpenSSL 3.0 to more modern +standards. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_decrypt_skey.3 b/static/netbsd/man3/PKCS12_decrypt_skey.3 new file mode 100644 index 00000000..ebd9bcd9 --- /dev/null +++ b/static/netbsd/man3/PKCS12_decrypt_skey.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: PKCS12_decrypt_skey.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_decrypt_skey 3" +.TH PKCS12_decrypt_skey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_decrypt_skey, PKCS12_decrypt_skey_ex \- PKCS12 shrouded keyBag +decrypt functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS8_PRIV_KEY_INFO *PKCS12_decrypt_skey(const PKCS12_SAFEBAG *bag, +\& const char *pass, int passlen); +\& PKCS8_PRIV_KEY_INFO *PKCS12_decrypt_skey_ex(const PKCS12_SAFEBAG *bag, +\& const char *pass, int passlen, +\& OSSL_LIB_CTX *ctx, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_decrypt_skey()\fR Decrypt the PKCS#8 shrouded keybag contained within \fIbag\fR +using the supplied password \fIpass\fR of length \fIpasslen\fR. +.PP +\&\fBPKCS12_decrypt_skey_ex()\fR is similar to the above but allows for a library context +\&\fIctx\fR and property query \fIpropq\fR to be used to select algorithm implementations. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Both functions will return the decrypted key or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS8_decrypt_ex\fR\|(3), +\&\fBPKCS8_encrypt_ex\fR\|(3), +\&\fBPKCS12_add_key_ex\fR\|(3), +\&\fBPKCS12_SAFEBAG_create_pkcs8_encrypt_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_decrypt_skey_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_gen_mac.3 b/static/netbsd/man3/PKCS12_gen_mac.3 new file mode 100644 index 00000000..e07c5a22 --- /dev/null +++ b/static/netbsd/man3/PKCS12_gen_mac.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: PKCS12_gen_mac.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_gen_mac 3" +.TH PKCS12_gen_mac 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_gen_mac, PKCS12_setup_mac, PKCS12_set_mac, +PKCS12_set_pbmac1_pbkdf2, PKCS12_verify_mac, PKCS12_get0_mac \- +Functions to create and manipulate a PKCS#12 MAC structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_gen_mac(PKCS12 *p12, const char *pass, int passlen, +\& unsigned char *mac, unsigned int *maclen); +\& int PKCS12_verify_mac(PKCS12 *p12, const char *pass, int passlen); +\& int PKCS12_set_mac(PKCS12 *p12, const char *pass, int passlen, +\& unsigned char *salt, int saltlen, int iter, +\& const EVP_MD *md_type); +\& int PKCS12_set_pbmac1_pbkdf2(PKCS12 *p12, const char *pass, int passlen, +\& unsigned char *salt, int saltlen, int iter, +\& const EVP_MD *md_type, +\& const char *prf_md_name); +\& int PKCS12_setup_mac(PKCS12 *p12, int iter, unsigned char *salt, +\& int saltlen, const EVP_MD *md_type); +\& +\& void PKCS12_get0_mac(const ASN1_OCTET_STRING **pmac, +\& const X509_ALGOR **pmacalg, +\& const ASN1_OCTET_STRING **psalt, +\& const ASN1_INTEGER **piter, +\& const PKCS12 *p12); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_gen_mac()\fR generates an HMAC over the entire PKCS#12 object using the +supplied password along with a set of already configured parameters. +The default key generation mechanism used is PKCS12KDF. +.PP +\&\fBPKCS12_verify_mac()\fR verifies the PKCS#12 object\*(Aqs HMAC using the supplied +password. +.PP +\&\fBPKCS12_setup_mac()\fR sets the MAC part of the PKCS#12 structure with the supplied +parameters. +.PP +\&\fBPKCS12_set_mac()\fR sets the MAC and MAC parameters into the PKCS#12 object. +\&\fBPKCS12_set_pbmac1_pbkdf2()\fR sets the MAC and MAC parameters into the PKCS#12 +object when \fBPBMAC1\fR with PBKDF2 is used for protection of the PKCS#12 object. +.PP +\&\fIpass\fR is the passphrase to use in the HMAC. \fIsalt\fR is the salt value to use, +\&\fIiter\fR is the iteration count and \fImd_type\fR is the message digest function to +use. \fIprf_md_name\fR specifies the digest used for the PBKDF2 in PBMAC1 KDF. +.PP +\&\fBPKCS12_get0_mac()\fR retrieves any included MAC value, \fBX509_ALGOR\fR object, +\&\fIsalt\fR, and \fIiter\fR count from the PKCS12 object. +.SH NOTES +.IX Header "NOTES" +If \fIsalt\fR is NULL then a suitable salt will be generated and used. +.PP +If \fIiter\fR is 1 then an iteration count will be omitted from the PKCS#12 +structure. +.PP +\&\fBPKCS12_gen_mac()\fR, \fBPKCS12_verify_mac()\fR, \fBPKCS12_set_mac()\fR and +\&\fBPKCS12_set_pbmac1_pbkdf2()\fR make assumptions regarding the encoding of the +given passphrase. See \fBpassphrase\-encoding\fR\|(7) for more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions returning an integer return 1 on success and 0 if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +IETF RFC 9579 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_PKCS12\fR\|(3), +\&\fBEVP_KDF\-PKCS12KDF\fR\|(7), +\&\fBPKCS12_create\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fIPKCS12_set_pbmac1_pbkdf2\fR function was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_get_friendlyname.3 b/static/netbsd/man3/PKCS12_get_friendlyname.3 new file mode 100644 index 00000000..1c106671 --- /dev/null +++ b/static/netbsd/man3/PKCS12_get_friendlyname.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: PKCS12_get_friendlyname.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_get_friendlyname 3" +.TH PKCS12_get_friendlyname 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_get_friendlyname \- Retrieve the friendlyname attribute from a PKCS#12 safeBag +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& char *PKCS12_get_friendlyname(PKCS12_SAFEBAG *bag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_get_friendlyname()\fR retrieves a UTF\-8 string representation of the PKCS#9 +friendlyName attribute for a PKCS#12 safeBag item. +.PP +\&\fIbag\fR is the \fBPKCS12_SAFEBAG\fR to retrieve the attribute from. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +A UTF\-8 string, or NULL if the attribute was either not present or an error occurred. +.PP +The returned string is allocated by OpenSSL and should be freed by the user. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_add_friendlyname_asc\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_init.3 b/static/netbsd/man3/PKCS12_init.3 new file mode 100644 index 00000000..3b437593 --- /dev/null +++ b/static/netbsd/man3/PKCS12_init.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: PKCS12_init.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_init 3" +.TH PKCS12_init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_init, PKCS12_init_ex \- Create a new empty PKCS#12 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS12 *PKCS12_init(int mode); +\& PKCS12 *PKCS12_init_ex(int mode, OSSL_LIB_CTX *ctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_init()\fR creates an empty PKCS#12 structure. Any PKCS#7 authSafes added +to this structure are enclosed first within a single PKCS#7 contentInfo +of type \fImode\fR. Currently the only supported type is \fBNID_pkcs7_data\fR. +.PP +\&\fBPKCS12_init_ex()\fR creates an empty PKCS#12 structure and assigns the supplied +\&\fIctx\fR and \fIpropq\fR to be used to select algorithm implementations for +operations performed on the \fBPKCS12\fR object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_init()\fR and \fBPKCS12_init_ex()\fR return a valid \fBPKCS12\fR structure or NULL +if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_PKCS12\fR\|(3), +\&\fBPKCS12_create\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_init_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_item_decrypt_d2i.3 b/static/netbsd/man3/PKCS12_item_decrypt_d2i.3 new file mode 100644 index 00000000..ac97e2f2 --- /dev/null +++ b/static/netbsd/man3/PKCS12_item_decrypt_d2i.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: PKCS12_item_decrypt_d2i.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_item_decrypt_d2i 3" +.TH PKCS12_item_decrypt_d2i 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_item_decrypt_d2i, PKCS12_item_decrypt_d2i_ex, +PKCS12_item_i2d_encrypt, PKCS12_item_i2d_encrypt_ex \- PKCS12 item +encrypt/decrypt functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void *PKCS12_item_decrypt_d2i(const X509_ALGOR *algor, const ASN1_ITEM *it, +\& const char *pass, int passlen, +\& const ASN1_OCTET_STRING *oct, int zbuf); +\& void *PKCS12_item_decrypt_d2i_ex(const X509_ALGOR *algor, const ASN1_ITEM *it, +\& const char *pass, int passlen, +\& const ASN1_OCTET_STRING *oct, int zbuf, +\& OSSL_LIB_CTX *libctx, +\& const char *propq); +\& ASN1_OCTET_STRING *PKCS12_item_i2d_encrypt(X509_ALGOR *algor, +\& const ASN1_ITEM *it, +\& const char *pass, int passlen, +\& void *obj, int zbuf); +\& ASN1_OCTET_STRING *PKCS12_item_i2d_encrypt_ex(X509_ALGOR *algor, +\& const ASN1_ITEM *it, +\& const char *pass, int passlen, +\& void *obj, int zbuf, +\& OSSL_LIB_CTX *ctx, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_item_decrypt_d2i()\fR and \fBPKCS12_item_decrypt_d2i_ex()\fR decrypt an octet +string containing an ASN.1 encoded object using the algorithm \fIalgor\fR and +password \fIpass\fR of length \fIpasslen\fR. If \fIzbuf\fR is nonzero then the output +buffer will zeroed after the decrypt. +.PP +\&\fBPKCS12_item_i2d_encrypt()\fR and \fBPKCS12_item_i2d_encrypt_ex()\fR encrypt an ASN.1 +object \fIit\fR using the algorithm \fIalgor\fR and password \fIpass\fR of length +\&\fIpasslen\fR, returning an encoded object in \fIobj\fR. If \fIzbuf\fR is nonzero then +the buffer containing the input encoding will be zeroed after the encrypt. +.PP +Functions ending in \fB_ex()\fR allow for a library context \fIctx\fR and property query +\&\fIpropq\fR to be used to select algorithm implementations. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_item_decrypt_d2i()\fR and \fBPKCS12_item_decrypt_d2i_ex()\fR return the decrypted +object or NULL if an error occurred. +.PP +\&\fBPKCS12_item_i2d_encrypt()\fR and \fBPKCS12_item_i2d_encrypt_ex()\fR return the encrypted +data as an ASN.1 Octet String or NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_pbe_crypt_ex\fR\|(3), +\&\fBPKCS8_encrypt_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_item_decrypt_d2i_ex()\fR and \fBPKCS12_item_i2d_encrypt_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_key_gen_utf8_ex.3 b/static/netbsd/man3/PKCS12_key_gen_utf8_ex.3 new file mode 100644 index 00000000..db9da85c --- /dev/null +++ b/static/netbsd/man3/PKCS12_key_gen_utf8_ex.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: PKCS12_key_gen_utf8_ex.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_key_gen_utf8_ex 3" +.TH PKCS12_key_gen_utf8_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_key_gen_asc, PKCS12_key_gen_asc_ex, +PKCS12_key_gen_uni, PKCS12_key_gen_uni_ex, +PKCS12_key_gen_utf8, PKCS12_key_gen_utf8_ex \- PKCS#12 Password based key derivation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_key_gen_asc(const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type); +\& int PKCS12_key_gen_asc_ex(const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& int PKCS12_key_gen_uni(unsigned char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type); +\& int PKCS12_key_gen_uni_ex(unsigned char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& int PKCS12_key_gen_utf8(const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type); +\& int PKCS12_key_gen_utf8_ex(const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int id, int iter, int n, +\& unsigned char *out, const EVP_MD *md_type, +\& OSSL_LIB_CTX *ctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These methods perform a key derivation according to PKCS#12 (RFC7292) +with an input password \fIpass\fR of length \fIpasslen\fR, a salt \fIsalt\fR of length +\&\fIsaltlen\fR, an iteration count \fIiter\fR and a digest algorithm \fImd_type\fR. +The ID byte \fIid\fR determines how the resulting key is intended to be used: +.IP \(bu 4 +If ID=1, then the pseudorandom bits being produced are to be used +as key material for performing encryption or decryption. +.IP \(bu 4 +If ID=2, then the pseudorandom bits being produced are to be used +as an IV (Initial Value) for encryption or decryption. +.IP \(bu 4 +If ID=3, then the pseudorandom bits being produced are to be used +as an integrity key for MACing. +.PP +The intended format of the supplied password is determined by the method chosen: +.IP \(bu 4 +\&\fBPKCS12_key_gen_asc()\fR and \fBPKCS12_key_gen_asc_ex()\fR expect an ASCII\-formatted password. +.IP \(bu 4 +\&\fBPKCS12_key_gen_uni()\fR and \fBPKCS12_key_gen_uni_ex()\fR expect a Unicode\-formatted password. +.IP \(bu 4 +\&\fBPKCS12_key_gen_utf8()\fR and \fBPKCS12_key_gen_utf8_ex()\fR expect a UTF\-8 encoded password. +.PP +\&\fIpass\fR is the password used in the derivation of length \fIpasslen\fR. \fIpass\fR +is an optional parameter and can be NULL. If \fIpasslen\fR is \-1, then the +function will calculate the length of \fIpass\fR using \fBstrlen()\fR. +.PP +\&\fIsalt\fR is the salt used in the derivation of length \fIsaltlen\fR. If the +\&\fIsalt\fR is NULL, then \fIsaltlen\fR must be 0. The function will not +attempt to calculate the length of the \fIsalt\fR because it is not assumed to +be NULL terminated. +.PP +\&\fIiter\fR is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +\&\fIiter\fR less than 1 is treated as a single iteration. +.PP +\&\fIdigest\fR is the message digest function used in the derivation. +.PP +The derived key will be written to \fIout\fR. The size of the \fIout\fR buffer +is specified via \fIn\fR. +.PP +Functions ending in \fB_ex()\fR allow for a library context \fIctx\fR and property query +\&\fIpropq\fR to be used to select algorithm implementations. +.SH NOTES +.IX Header "NOTES" +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the \fIpass\fR, a salt in \fIsalt\fR, +and an iteration count. +.PP +Increasing the \fIiter\fR parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success or 0 on error. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create_ex\fR\|(3), +\&\fBPKCS12_pbe_crypt_ex\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_key_gen_asc_ex()\fR, \fBPKCS12_key_gen_uni_ex()\fR and \fBPKCS12_key_gen_utf8_ex()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_newpass.3 b/static/netbsd/man3/PKCS12_newpass.3 new file mode 100644 index 00000000..93fdd088 --- /dev/null +++ b/static/netbsd/man3/PKCS12_newpass.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: PKCS12_newpass.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_newpass 3" +.TH PKCS12_newpass 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_newpass \- change the password of a PKCS12 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_newpass()\fR changes the password of a PKCS12 structure. +.PP +\&\fBp12\fR is a pointer to a PKCS12 structure. \fBoldpass\fR is the existing password +and \fBnewpass\fR is the new password. +.PP +Each of \fBoldpass\fR and \fBnewpass\fR is independently interpreted as a string in +the UTF\-8 encoding. If it is not valid UTF\-8, it is assumed to be ISO8859\-1 +instead. +.PP +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF\-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +\&\fBUI_OpenSSL\fR\|(3), for example. +.PP +If the PKCS#12 structure does not have a password, then you must use the empty +string "" for \fBoldpass\fR. Using NULL for \fBoldpass\fR will result in a +\&\fBPKCS12_newpass()\fR failure. +.PP +If the wrong password is used for \fBoldpass\fR then the function will fail, +with a MAC verification error. In rare cases the PKCS12 structure does not +contain a MAC: in this case it will usually fail with a decryption padding +error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_newpass()\fR returns 1 on success or 0 on failure. Applications can +retrieve the most recent error from \fBPKCS12_newpass()\fR with \fBERR_get_error()\fR. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example loads a PKCS#12 file, changes its password and writes out +the result to a new file. +.PP +.Vb 5 +\& #include +\& #include +\& #include +\& #include +\& #include +\& +\& int main(int argc, char **argv) +\& { +\& FILE *fp; +\& PKCS12 *p12; +\& +\& if (argc != 5) { +\& fprintf(stderr, "Usage: pkread p12file password newpass opfile\en"); +\& return 1; +\& } +\& if ((fp = fopen(argv[1], "rb")) == NULL) { +\& fprintf(stderr, "Error opening file %s\en", argv[1]); +\& return 1; +\& } +\& p12 = d2i_PKCS12_fp(fp, NULL); +\& fclose(fp); +\& if (p12 == NULL) { +\& fprintf(stderr, "Error reading PKCS#12 file\en"); +\& ERR_print_errors_fp(stderr); +\& return 1; +\& } +\& if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) { +\& fprintf(stderr, "Error changing password\en"); +\& ERR_print_errors_fp(stderr); +\& PKCS12_free(p12); +\& return 1; +\& } +\& if ((fp = fopen(argv[4], "wb")) == NULL) { +\& fprintf(stderr, "Error opening file %s\en", argv[4]); +\& PKCS12_free(p12); +\& return 1; +\& } +\& i2d_PKCS12_fp(fp, p12); +\& PKCS12_free(p12); +\& fclose(fp); +\& return 0; +\& } +.Ve +.SH BUGS +.IX Header "BUGS" +The password format is a NULL terminated ASCII string which is converted to +Unicode form internally. As a result some passwords cannot be supplied to +this function. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_create\fR\|(3), \fBERR_get_error\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_pack_p7encdata.3 b/static/netbsd/man3/PKCS12_pack_p7encdata.3 new file mode 100644 index 00000000..16e630a0 --- /dev/null +++ b/static/netbsd/man3/PKCS12_pack_p7encdata.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: PKCS12_pack_p7encdata.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_pack_p7encdata 3" +.TH PKCS12_pack_p7encdata 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_pack_p7encdata, PKCS12_pack_p7encdata_ex \- Pack a set of PKCS#12 safeBags +into a PKCS#7 encrypted data object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, const char *pass, int passlen, +\& unsigned char *salt, int saltlen, int iter, +\& STACK_OF(PKCS12_SAFEBAG) *bags); +\& PKCS7 *PKCS12_pack_p7encdata_ex(int pbe_nid, const char *pass, int passlen, +\& unsigned char *salt, int saltlen, int iter, +\& STACK_OF(PKCS12_SAFEBAG) *bags, +\& OSSL_LIB_CTX *ctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_pack_p7encdata()\fR generates a PKCS#7 ContentInfo object of encrypted\-data +type from the set of safeBags \fIbags\fR. The algorithm ID in \fIpbe_nid\fR can be +a PKCS#12 or PKCS#5 password based encryption algorithm, or a cipher algorithm. +If a cipher algorithm is passed, the PKCS#5 PBES2 algorithm will be used with +this cipher as a parameter. +The password \fIpass\fR of length \fIpasslen\fR, salt \fIsalt\fR of length \fIsaltlen\fR +and iteration count \fIiter\fR are inputs into the encryption operation. +.PP +\&\fBPKCS12_pack_p7encdata_ex()\fR operates similar to the above but allows for a +library context \fIctx\fR and property query \fIpropq\fR to be used to select the +algorithm implementation. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +A \fBPKCS7\fR object if successful, or NULL if an error occurred. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 2315 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS12_pbe_crypt_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS12_pack_p7encdata_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS12_parse.3 b/static/netbsd/man3/PKCS12_parse.3 new file mode 100644 index 00000000..00930336 --- /dev/null +++ b/static/netbsd/man3/PKCS12_parse.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: PKCS12_parse.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS12_parse 3" +.TH PKCS12_parse 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS12_parse \- parse a PKCS#12 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, +\& STACK_OF(X509) **ca); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS12_parse()\fR parses a PKCS12 structure. +.PP +\&\fBp12\fR is the \fBPKCS12\fR structure to parse. \fBpass\fR is the passphrase to use. +If successful the private key will be written to \fB*pkey\fR, the corresponding +certificate to \fB*cert\fR and any additional certificates to \fB*ca\fR. +.SH NOTES +.IX Header "NOTES" +Each of the parameters \fBpkey\fR, \fBcert\fR, and \fBca\fR can be NULL in which case +the private key, the corresponding certificate, or the additional certificates, +respectively, will be discarded. +If any of \fBpkey\fR and \fBcert\fR is non\-NULL the variable it points to is +initialized. +If \fBca\fR is non\-NULL and \fB*ca\fR is NULL a new STACK will be allocated. +If \fBca\fR is non\-NULL and \fB*ca\fR is a valid STACK +then additional certificates are appended in the given order to \fB*ca\fR. +.PP +The \fBfriendlyName\fR and \fBlocalKeyID\fR attributes (if present) on each +certificate will be stored in the \fBalias\fR and \fBkeyid\fR attributes of the +\&\fBX509\fR structure. +.PP +The parameter \fBpass\fR is interpreted as a string in the UTF\-8 encoding. If it +is not valid UTF\-8, then it is assumed to be ISO8859\-1 instead. +.PP +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF\-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +\&\fBUI_OpenSSL\fR\|(3), for example. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS12_parse()\fR returns 1 for success and zero if an error occurred. +.PP +The error can be obtained from \fBERR_get_error\fR\|(3) +.SH BUGS +.IX Header "BUGS" +Only a single private key and corresponding certificate is returned by this +function. More complex PKCS#12 files with multiple private keys will only +return the first match. +.PP +Only \fBfriendlyName\fR and \fBlocalKeyID\fR attributes are currently stored in +certificates. Other attributes are discarded. +.PP +Attributes currently cannot be stored in the private key \fBEVP_PKEY\fR structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_PKCS12\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS5_PBE_keyivgen.3 b/static/netbsd/man3/PKCS5_PBE_keyivgen.3 new file mode 100644 index 00000000..7c54c389 --- /dev/null +++ b/static/netbsd/man3/PKCS5_PBE_keyivgen.3 @@ -0,0 +1,251 @@ +.\" $NetBSD: PKCS5_PBE_keyivgen.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS5_PBE_keyivgen 3" +.TH PKCS5_PBE_keyivgen 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS5_PBE_keyivgen, PKCS5_PBE_keyivgen_ex, PKCS5_pbe2_set, PKCS5_pbe2_set_iv, +PKCS5_pbe2_set_iv_ex, PKCS5_pbe_set, PKCS5_pbe_set_ex, PKCS5_pbe2_set_scrypt, +PKCS5_pbe_set0_algor, PKCS5_pbe_set0_algor_ex, +PKCS5_v2_PBE_keyivgen, PKCS5_v2_PBE_keyivgen_ex, +PKCS5_v2_scrypt_keyivgen, PKCS5_v2_scrypt_keyivgen_ex, +PKCS5_pbkdf2_set, PKCS5_pbkdf2_set_ex, EVP_PBE_scrypt, EVP_PBE_scrypt_ex +\&\- PKCS#5 Password based encryption routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS5_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md, int en_de); +\& int PKCS5_PBE_keyivgen_ex(EVP_CIPHER_CTX *cctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md, int en_de, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int PKCS5_v2_PBE_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md, int en_de); +\& int PKCS5_v2_PBE_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, int passlen, +\& ASN1_TYPE *param, const EVP_CIPHER *cipher, +\& const EVP_MD *md, int en_de, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int EVP_PBE_scrypt(const char *pass, size_t passlen, +\& const unsigned char *salt, size_t saltlen, +\& uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem, +\& unsigned char *key, size_t keylen); +\& int EVP_PBE_scrypt_ex(const char *pass, size_t passlen, +\& const unsigned char *salt, size_t saltlen, +\& uint64_t N, uint64_t r, uint64_t p, uint64_t maxmem, +\& unsigned char *key, size_t keylen, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& int PKCS5_v2_scrypt_keyivgen(EVP_CIPHER_CTX *ctx, const char *pass, +\& int passlen, ASN1_TYPE *param, +\& const EVP_CIPHER *c, const EVP_MD *md, int en_de); +\& int PKCS5_v2_scrypt_keyivgen_ex(EVP_CIPHER_CTX *ctx, const char *pass, +\& int passlen, ASN1_TYPE *param, +\& const EVP_CIPHER *c, const EVP_MD *md, int en_de, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& #include +\& +\& int PKCS5_pbe_set0_algor(X509_ALGOR *algor, int alg, int iter, +\& const unsigned char *salt, int saltlen); +\& int PKCS5_pbe_set0_algor_ex(X509_ALGOR *algor, int alg, int iter, +\& const unsigned char *salt, int saltlen, +\& OSSL_LIB_CTX *libctx); +\& +\& X509_ALGOR *PKCS5_pbe_set(int alg, int iter, +\& const unsigned char *salt, int saltlen); +\& X509_ALGOR *PKCS5_pbe_set_ex(int alg, int iter, +\& const unsigned char *salt, int saltlen, +\& OSSL_LIB_CTX *libctx); +\& +\& X509_ALGOR *PKCS5_pbe2_set(const EVP_CIPHER *cipher, int iter, +\& unsigned char *salt, int saltlen); +\& X509_ALGOR *PKCS5_pbe2_set_iv(const EVP_CIPHER *cipher, int iter, +\& unsigned char *salt, int saltlen, +\& unsigned char *aiv, int prf_nid); +\& X509_ALGOR *PKCS5_pbe2_set_iv_ex(const EVP_CIPHER *cipher, int iter, +\& unsigned char *salt, int saltlen, +\& unsigned char *aiv, int prf_nid, +\& OSSL_LIB_CTX *libctx); +\& X509_ALGOR *PKCS5_pbe2_set_scrypt(const EVP_CIPHER *cipher, +\& const unsigned char *salt, int saltlen, +\& unsigned char *aiv, uint64_t N, uint64_t r, +\& uint64_t p); +\& +\& X509_ALGOR *PKCS5_pbkdf2_set(int iter, unsigned char *salt, int saltlen, +\& int prf_nid, int keylen); +\& X509_ALGOR *PKCS5_pbkdf2_set_ex(int iter, unsigned char *salt, int saltlen, +\& int prf_nid, int keylen, +\& OSSL_LIB_CTX *libctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS "Key Derivation" +.IX Subsection "Key Derivation" +\&\fBPKCS5_PBE_keyivgen()\fR and \fBPKCS5_PBE_keyivgen_ex()\fR take a password \fIpass\fR of +length \fIpasslen\fR, parameters \fIparam\fR and a message digest function \fImd_type\fR +and performs a key derivation according to PKCS#5 PBES1. The resulting key is +then used to initialise the cipher context \fIctx\fR with a cipher \fIcipher\fR for +encryption (\fIen_de\fR=1) or decryption (\fIen_de\fR=0). +.PP +\&\fIpass\fR is an optional parameter and can be NULL. If \fIpasslen\fR is \-1, then the +function will calculate the length of \fIpass\fR using \fBstrlen()\fR. +.PP +\&\fBPKCS5_v2_PBE_keyivgen()\fR and \fBPKCS5_v2_PBE_keyivgen_ex()\fR are similar to the above +but instead use PKCS#5 PBES2 as the encryption algorithm using the supplied +parameters. +.PP +\&\fBPKCS5_v2_scrypt_keyivgen()\fR and \fBPKCS5_v2_scrypt_keyivgen_ex()\fR use SCRYPT as the +key derivation part of the encryption algorithm. +.PP +\&\fIsalt\fR is the salt used in the derivation of length \fIsaltlen\fR. If the +\&\fIsalt\fR is NULL, then \fIsaltlen\fR must be 0. The function will not +attempt to calculate the length of the \fIsalt\fR because it is not assumed to +be NULL terminated. +.PP +\&\fIiter\fR is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +\&\fIiter\fR less than 1 is treated as a single iteration. +.PP +\&\fIdigest\fR is the message digest function used in the derivation. +.PP +\&\fIaiv\fR is the initialization vector (IV) to use for the encryption algorithm. +If \fIaiv\fR is NULL, then a random IV will be generated. +.PP +\&\fIprf_nid\fR is the numeric identifier (NID) for the pseudo\-random function to +use with PBKDF2. If \fIprf_nid\fR is not specified (for example, \fIprf_nid\fR is set to 0), +a default PRF is used, which is currently set to SHA\-256 (NID_hmacWithSHA256). +.PP +Functions ending in \fB_ex()\fR take optional parameters \fIlibctx\fR and \fIpropq\fR which +are used to select appropriate algorithm implementations. +.SS "Algorithm Identifier Creation" +.IX Subsection "Algorithm Identifier Creation" +\&\fBPKCS5_pbe_set()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set()\fR, \fBPKCS5_pbe2_set_iv()\fR, +\&\fBPKCS5_pbe2_set_iv_ex()\fR and \fBPKCS5_pbe2_set_scrypt()\fR generate an \fBX509_ALGOR\fR +object which represents an AlgorithmIdentifier containing the algorithm OID and +associated parameters for the PBE algorithm. These functions encode the +key derivation parameters (such as salt and iteration count) and the +encryption parameters (such as the IV) into the ASN.1 structure. +.PP +\&\fBPKCS5_pbkdf2_set()\fR and \fBPKCS5_pbkdf2_set_ex()\fR generate an \fBX509_ALGOR\fR +object which represents an AlgorithmIdentifier containing the algorithm OID and +associated parameters for the PBKDF2 algorithm. +.PP +\&\fBPKCS5_pbe_set0_algor()\fR and \fBPKCS5_pbe_set0_algor_ex()\fR set the PBE algorithm OID and +parameters into the supplied \fBX509_ALGOR\fR. +.PP +If \fIsalt\fR is NULL, then \fIsaltlen\fR specifies the size in bytes of the random salt to +generate. If \fIsaltlen\fR is 0 then a default size is used. +For PBE related functions such as \fBPKCS5_pbe_set_ex()\fR the default salt length is 8 bytes. +For PBE2 related functions that use PBKDF2 such as \fBPKCS5_pbkdf2_set()\fR, +\&\fBPKCS5_pbe2_set_scrypt()\fR and \fBPKCS5_pbe2_set()\fR the default salt length is 16 bytes. +.SH NOTES +.IX Header "NOTES" +The *\fB_keyivgen()\fR functions are typically used in PKCS#12 to encrypt objects. +.PP +These functions make no assumption regarding the given password. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS5_PBE_keyivgen()\fR, \fBPKCS5_v2_PBE_keyivgen()\fR, +\&\fBPKCS5_v2_PBE_keyivgen_ex()\fR, \fBPKCS5_v2_scrypt_keyivgen()\fR, +\&\fBPKCS5_v2_scrypt_keyivgen_ex()\fR, \fBPKCS5_pbe_set0_algor()\fR and +\&\fBPKCS5_pbe_set0_algor_ex()\fR return 1 for success and 0 if an error occurs. +.PP +\&\fBPKCS5_pbe_set()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set()\fR, \fBPKCS5_pbe2_set_iv()\fR, +\&\fBPKCS5_pbe2_set_iv_ex()\fR, \fBPKCS5_pbe2_set_scrypt()\fR, +\&\fBPKCS5_pbkdf2_set()\fR and \fBPKCS5_pbkdf2_set_ex()\fR return an \fBX509_ALGOR\fR object or +NULL if an error occurs. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 8018 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PBE_CipherInit_ex\fR\|(3), +\&\fBPKCS12_pbe_crypt_ex\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS5_v2_PBE_keyivgen_ex()\fR, \fBEVP_PBE_scrypt_ex()\fR, \fBPKCS5_v2_scrypt_keyivgen_ex()\fR, +\&\fBPKCS5_pbe_set0_algor_ex()\fR, \fBPKCS5_pbe_set_ex()\fR, \fBPKCS5_pbe2_set_iv_ex()\fR and +\&\fBPKCS5_pbkdf2_set_ex()\fR were added in OpenSSL 3.0. +.PP +From OpenSSL 3.0 the PBKDF1 algorithm used in \fBPKCS5_PBE_keyivgen()\fR and +\&\fBPKCS5_PBE_keyivgen_ex()\fR has been moved to the legacy provider as an EVP_KDF. +.PP +In OpenSSL 3.2 the default salt length changed from 8 bytes to 16 bytes for PBE2 +related functions such as \fBPKCS5_pbe2_set()\fR. +This is required for PBKDF2 FIPS compliance. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS5_PBKDF2_HMAC.3 b/static/netbsd/man3/PKCS5_PBKDF2_HMAC.3 new file mode 100644 index 00000000..98370d87 --- /dev/null +++ b/static/netbsd/man3/PKCS5_PBKDF2_HMAC.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: PKCS5_PBKDF2_HMAC.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS5_PBKDF2_HMAC 3" +.TH PKCS5_PBKDF2_HMAC 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 \- password based derivation routines with salt and iteration count +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, +\& const unsigned char *salt, int saltlen, int iter, +\& const EVP_MD *digest, +\& int keylen, unsigned char *out); +\& +\& int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, +\& const unsigned char *salt, int saltlen, int iter, +\& int keylen, unsigned char *out); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS5_PBKDF2_HMAC()\fR derives a key from a password using a salt and iteration count +as specified in RFC 2898. +.PP +\&\fBpass\fR is the password used in the derivation of length \fBpasslen\fR. \fBpass\fR +is an optional parameter and can be NULL. If \fBpasslen\fR is \-1, then the +function will calculate the length of \fBpass\fR using \fBstrlen()\fR. +.PP +\&\fBsalt\fR is the salt used in the derivation of length \fBsaltlen\fR. If the +\&\fBsalt\fR is NULL, then \fBsaltlen\fR must be 0. The function will not +attempt to calculate the length of the \fBsalt\fR because it is not assumed to +be NULL terminated. +.PP +\&\fBiter\fR is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +\&\fBiter\fR value less than 1 is invalid; such values will result in failure +and raise the PROV_R_INVALID_ITERATION_COUNT error. +.PP +\&\fBdigest\fR is the message digest function used in the derivation. +\&\fBPKCS5_PBKDF2_HMAC_SHA1()\fR calls \fBPKCS5_PBKDF2_HMAC()\fR with \fBEVP_sha1()\fR. +.PP +The derived key will be written to \fBout\fR. The size of the \fBout\fR buffer +is specified via \fBkeylen\fR. +.SH NOTES +.IX Header "NOTES" +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the \fBpass\fR, a salt in \fBsalt\fR, +and an iteration count. +.PP +Increasing the \fBiter\fR parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. +.PP +These functions make no assumption regarding the given password. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS5_PBKDF2_HMAC()\fR and \fBPBKCS5_PBKDF2_HMAC_SHA1()\fR return 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBevp\fR\|(7), \fBRAND_bytes\fR\|(3), +\&\fBEVP_BytesToKey\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS5_PBKDF2_HMAC_SHA1.3 b/static/netbsd/man3/PKCS5_PBKDF2_HMAC_SHA1.3 new file mode 100644 index 00000000..4e725cec --- /dev/null +++ b/static/netbsd/man3/PKCS5_PBKDF2_HMAC_SHA1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: PKCS5_PBKDF2_HMAC_SHA1.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_misc.3 diff --git a/static/netbsd/man3/PKCS7_decrypt.3 b/static/netbsd/man3/PKCS7_decrypt.3 new file mode 100644 index 00000000..54e3ba3c --- /dev/null +++ b/static/netbsd/man3/PKCS7_decrypt.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: PKCS7_decrypt.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_decrypt 3" +.TH PKCS7_decrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_decrypt \- decrypt content from a PKCS#7 envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_decrypt()\fR extracts and decrypts the content from a PKCS#7 envelopedData +structure. \fBpkey\fR is the private key of the recipient, \fBcert\fR is the +recipients certificate, \fBdata\fR is a BIO to write the content to and +\&\fBflags\fR is an optional set of flags. +.SH NOTES +.IX Header "NOTES" +Although the recipients certificate is not needed to decrypt the data it is needed +to locate the appropriate (of possible several) recipients in the PKCS#7 structure. +.PP +The following flags can be passed in the \fBflags\fR parameter. +.PP +If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are deleted +from the content. If the content is not of type \fBtext/plain\fR then an error is +returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_decrypt()\fR returns either 1 for success or 0 for failure. +The error can be obtained from \fBERR_get_error\fR\|(3) +.SH BUGS +.IX Header "BUGS" +\&\fBPKCS7_decrypt()\fR must be passed the correct recipient key and certificate. It would +be better if it could look up the correct key and certificate from a database. +.PP +The lack of single pass processing and need to hold all data in memory as +mentioned in \fBPKCS7_sign()\fR also applies to \fBPKCS7_verify()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_encrypt\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_encrypt.3 b/static/netbsd/man3/PKCS7_encrypt.3 new file mode 100644 index 00000000..62afe960 --- /dev/null +++ b/static/netbsd/man3/PKCS7_encrypt.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: PKCS7_encrypt.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_encrypt 3" +.TH PKCS7_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_encrypt_ex, PKCS7_encrypt +\&\- create a PKCS#7 envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS7 *PKCS7_encrypt_ex(STACK_OF(X509) *certs, BIO *in, +\& const EVP_CIPHER *cipher, int flags, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, +\& int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_encrypt_ex()\fR creates and returns a PKCS#7 envelopedData structure. +\&\fIcerts\fR is a list of recipient certificates. \fIin\fR is the content to be +encrypted. \fIcipher\fR is the symmetric cipher to use. \fIflags\fR is an optional set +of flags. The library context \fIlibctx\fR and the property query \fIpropq\fR are used +when retrieving algorithms from providers. +.PP +Only RSA keys are supported in PKCS#7 and envelopedData so the recipient +certificates supplied to this function must all contain RSA public keys, though +they do not have to be signed using the RSA algorithm. +.PP +\&\fBEVP_des_ede3_cbc()\fR (triple DES) is the algorithm of choice for S/MIME use +because most clients will support it. +.PP +Some old "export grade" clients may only support weak encryption using 40 or 64 +bit RC2. These can be used by passing \fBEVP_rc2_40_cbc()\fR and \fBEVP_rc2_64_cbc()\fR +respectively. +.PP +The algorithm passed in the \fBcipher\fR parameter must support ASN1 encoding of +its parameters. +.PP +Many browsers implement a "sign and encrypt" option which is simply an S/MIME +envelopedData containing an S/MIME signed message. This can be readily produced +by storing the S/MIME signed message in a memory BIO and passing it to +\&\fBPKCS7_encrypt()\fR. +.PP +The following flags can be passed in the \fBflags\fR parameter. +.PP +If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are +prepended to the data. +.PP +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if \fBPKCS7_BINARY\fR is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If \fBPKCS7_BINARY\fR is set then +\&\fBPKCS7_TEXT\fR is ignored. +.PP +If the \fBPKCS7_STREAM\fR flag is set a partial \fBPKCS7\fR structure is output +suitable for streaming I/O: no data is read from the BIO \fBin\fR. +.PP +If the flag \fBPKCS7_STREAM\fR is set the returned \fBPKCS7\fR structure is \fBnot\fR +complete and outputting its contents via a function that does not +properly finalize the \fBPKCS7\fR structure will give unpredictable +results. +.PP +Several functions including \fBSMIME_write_PKCS7()\fR, \fBi2d_PKCS7_bio_stream()\fR, +\&\fBPEM_write_bio_PKCS7_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 \fBBIO\fR directly using +\&\fBBIO_new_PKCS7()\fR. +.PP +\&\fBPKCS7_encrypt()\fR is similar to \fBPKCS7_encrypt_ex()\fR but uses default +values of NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_encrypt_ex()\fR and \fBPKCS7_encrypt()\fR return either a PKCS7 structure +or NULL if an error occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBPKCS7_encrypt_ex()\fR was added in OpenSSL 3.0. +.PP +The \fBPKCS7_STREAM\fR flag was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_get_octet_string.3 b/static/netbsd/man3/PKCS7_get_octet_string.3 new file mode 100644 index 00000000..adcad200 --- /dev/null +++ b/static/netbsd/man3/PKCS7_get_octet_string.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: PKCS7_get_octet_string.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_get_octet_string 3" +.TH PKCS7_get_octet_string 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_get_octet_string \- return octet string from a PKCS#7 envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OCTET_STRING *PKCS7_get_octet_string(PKCS7 *p7); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_get_octet_string()\fR returns a pointer to an ASN1 octet string from a +PKCS#7 envelopedData structure or \fBNULL\fR if the structure cannot be parsed. +.SH NOTES +.IX Header "NOTES" +As the \fB0\fR implies, \fBPKCS7_get_octet_string()\fR returns internal pointers which +should not be freed by the caller. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_get_octet_string()\fR returns an ASN1_OCTET_STRING pointer. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS7_type_is_data\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_sign.3 b/static/netbsd/man3/PKCS7_sign.3 new file mode 100644 index 00000000..7c419481 --- /dev/null +++ b/static/netbsd/man3/PKCS7_sign.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: PKCS7_sign.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_sign 3" +.TH PKCS7_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_sign_ex, PKCS7_sign +\&\- create a PKCS#7 signedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS7 *PKCS7_sign_ex(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, +\& BIO *data, int flags, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, +\& BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_sign_ex()\fR creates and returns a PKCS#7 signedData structure. +\&\fIsigncert\fR is the certificate to sign with, \fIpkey\fR is the corresponding +private key. \fIcerts\fR is an optional set of extra certificates to include +in the PKCS#7 structure (for example any intermediate CAs in the chain). +The library context \fIlibctx\fR and property query \fIpropq\fR are used when +retrieving algorithms from providers. +.PP +The data to be signed is read from BIO \fIdata\fR. +.PP +\&\fIflags\fR is an optional set of flags. +.PP +Any of the following flags (ored together) can be passed in the \fIflags\fR +parameter. +.PP +Many S/MIME clients expect the signed content to include valid MIME headers. If +the \fBPKCS7_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are prepended +to the data. +.PP +If \fBPKCS7_NOCERTS\fR is set the signer\*(Aqs certificate and the extra \fIcerts\fR +will not be included in the PKCS7 structure. +The signer\*(Aqs certificate must still be supplied in the \fIsigncert\fR parameter +though. This can reduce the size of the signatures if the signer\*(Aqs certificates +can be obtained by other means: for example a previously signed message. +.PP +The data being signed is included in the PKCS7 structure, unless +\&\fBPKCS7_DETACHED\fR is set in which case it is omitted. This is used for PKCS7 +detached signatures which are used in S/MIME plaintext signed messages for +example. +.PP +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if \fBPKCS7_BINARY\fR is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. +.PP +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported list of +ciphers in an SMIMECapabilities attribute. If \fBPKCS7_NOATTR\fR is set then no +authenticatedAttributes will be used. If \fBPKCS7_NOSMIMECAP\fR is set then just +the SMIMECapabilities are omitted. +.PP +If present the SMIMECapabilities attribute indicates support for the following +algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of +these algorithms is disabled then it will not be included. +.PP +If the flags \fBPKCS7_STREAM\fR is set then the returned \fBPKCS7\fR structure is +just initialized ready to perform the signing operation. The signing is however +\&\fBnot\fR performed and the data to be signed is not read from the \fIdata\fR +parameter. Signing is deferred until after the data has been written. In this +way data can be signed in a single pass. +.PP +If the \fBPKCS7_PARTIAL\fR flag is set a partial \fBPKCS7\fR structure is output to +which additional signers and capabilities can be added before finalization. +.PP +If the flag \fBPKCS7_STREAM\fR is set the returned \fBPKCS7\fR structure is \fBnot\fR +complete and outputting its contents via a function that does not properly +finalize the \fBPKCS7\fR structure will give unpredictable results. +.PP +Several functions including \fBSMIME_write_PKCS7()\fR, \fBi2d_PKCS7_bio_stream()\fR, +\&\fBPEM_write_bio_PKCS7_stream()\fR finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 \fBBIO\fR directly using +\&\fBBIO_new_PKCS7()\fR. +.PP +If a signer is specified it will use the default digest for the signing +algorithm. This is \fBSHA256\fR for both RSA and DSA keys. +.PP +The \fIcerts\fR, \fIsigncert\fR and \fIpkey\fR parameters can all be +NULL if the \fBPKCS7_PARTIAL\fR flag is set. One or more signers can be added +using the function \fBPKCS7_sign_add_signer()\fR. \fBPKCS7_final()\fR must also be +called to finalize the structure if streaming is not enabled. Alternative +signing digests can also be specified using this method. +.PP +If \fIsigncert\fR and \fIpkey\fR are NULL then a certificates only +PKCS#7 structure is output. +.PP +In versions of OpenSSL before 1.0.0 the \fIsigncert\fR and \fIpkey\fR parameters must +not be NULL. +.PP +\&\fBPKCS7_sign()\fR is like \fBPKCS7_sign_ex()\fR except that it uses default values of +NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR. +This is retained for API backward compatibility. +.SH BUGS +.IX Header "BUGS" +Some advanced attributes such as counter signatures are not supported. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_sign_ex()\fR and \fBPKCS7_sign()\fR return either a valid PKCS7 structure +or NULL if an error occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBPKCS7_sign_ex()\fR was added in OpenSSL 3.0. +.PP +The \fBPKCS7_PARTIAL\fR flag, and the ability for \fIcerts\fR, \fIsigncert\fR, +and \fIpkey\fR parameters to be NULL were added in OpenSSL 1.0.0. +.PP +The \fBPKCS7_STREAM\fR flag was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_sign_add_signer.3 b/static/netbsd/man3/PKCS7_sign_add_signer.3 new file mode 100644 index 00000000..2444e66b --- /dev/null +++ b/static/netbsd/man3/PKCS7_sign_add_signer.3 @@ -0,0 +1,166 @@ +.\" $NetBSD: PKCS7_sign_add_signer.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_sign_add_signer 3" +.TH PKCS7_sign_add_signer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_sign_add_signer, +PKCS7_add_certificate, PKCS7_add_crl \- add information to PKCS7 structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, +\& EVP_PKEY *pkey, const EVP_MD *md, int flags); +\& int PKCS7_add_certificate(PKCS7 *p7, X509 *cert); +\& int PKCS7_add_crl(PKCS7 *p7, X509_CRL *crl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_sign_add_signer()\fR adds a signer with certificate \fIsigncert\fR and private +key \fIpkey\fR using message digest \fImd\fR to a PKCS7 signed data structure \fIp7\fR. +.PP +The \fBPKCS7\fR structure should be obtained from an initial call to \fBPKCS7_sign()\fR +with the flag \fBPKCS7_PARTIAL\fR set or in the case or re\-signing a valid PKCS#7 +signed data structure. +.PP +If the \fImd\fR parameter is NULL then the default digest for the public +key algorithm will be used. +.PP +Unless the \fBPKCS7_REUSE_DIGEST\fR flag is set the returned \fBPKCS7\fR structure +is not complete and must be finalized either by streaming (if applicable) or +a call to \fBPKCS7_final()\fR. +.SH NOTES +.IX Header "NOTES" +The main purpose of this function is to provide finer control over a PKCS#7 +signed data structure where the simpler \fBPKCS7_sign()\fR function defaults are +not appropriate. For example if multiple signers or non default digest +algorithms are needed. +.PP +Any of the following flags (ored together) can be passed in the \fIflags\fR +parameter. +.PP +If \fBPKCS7_REUSE_DIGEST\fR is set then an attempt is made to copy the content +digest value from the \fBPKCS7\fR structure: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. The +returned \fBPKCS7\fR structure will be valid and finalized when this flag is set. +.PP +If \fBPKCS7_PARTIAL\fR is set in addition to \fBPKCS7_REUSE_DIGEST\fR then the +\&\fBPKCS7_SIGNER_INO\fR structure will not be finalized so additional attributes +can be added. In this case an explicit call to \fBPKCS7_SIGNER_INFO_sign()\fR is +needed to finalize it. +.PP +If \fBPKCS7_NOCERTS\fR is set the signer\*(Aqs certificate will not be included in the +\&\fBPKCS7\fR structure, the signer\*(Aqs certificate must still be supplied in the +\&\fIsigncert\fR parameter though. This can reduce the size of the signature if the +signers certificate can be obtained by other means: for example a previously +signed message. +.PP +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported list of +ciphers in an SMIMECapabilities attribute. If \fBPKCS7_NOATTR\fR is set then no +authenticatedAttributes will be used. If \fBPKCS7_NOSMIMECAP\fR is set then just +the SMIMECapabilities are omitted. +.PP +If present the SMIMECapabilities attribute indicates support for the following +algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of +these algorithms is disabled then it will not be included. +.PP +\&\fBPKCS7_sign_add_signers()\fR returns an internal pointer to the \fBPKCS7_SIGNER_INFO\fR +structure just added, which can be used to set additional attributes +before it is finalized. +.PP +\&\fBPKCS7_add_certificate()\fR adds to the \fBPKCS7\fR structure \fIp7\fR the certificate +\&\fIcert\fR, which may be an end\-entity (signer) certificate +or a CA certificate useful for chain building. +This is done internally by \fBPKCS7_sign_ex\fR\|(3) and similar signing functions. +It may have to be used before calling \fBPKCS7_verify\fR\|(3) +in order to provide any missing certificate(s) needed for verification. +.PP +\&\fBPKCS7_add_crl()\fR adds the CRL \fIcrl\fR to the \fBPKCS7\fR structure \fIp7\fR. +This may be called to provide certificate status information +to be included when signing or to use when verifying the \fBPKCS7\fR structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_sign_add_signers()\fR returns an internal pointer to the \fBPKCS7_SIGNER_INFO\fR +structure just added or NULL if an error occurs. +.PP +\&\fBPKCS7_add_certificate()\fR and \fBPKCS7_add_crl()\fR return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_sign_ex\fR\|(3), +\&\fBPKCS7_final\fR\|(3), \fBPKCS7_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBPPKCS7_sign_add_signer()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_type_is_other.3 b/static/netbsd/man3/PKCS7_type_is_other.3 new file mode 100644 index 00000000..2aec876a --- /dev/null +++ b/static/netbsd/man3/PKCS7_type_is_other.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: PKCS7_type_is_other.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_type_is_other 3" +.TH PKCS7_type_is_other 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_type_is_other \- determine content type of PKCS#7 envelopedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS7_type_is_other(PKCS7 *p7); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_type_is_other()\fR returns the whether the content type of a PKCS#7 envelopedData +structure is one of the following content types: +.PP +NID_pkcs7_data +NID_pkcs7_signed +NID_pkcs7_enveloped +NID_pkcs7_signedAndEnveloped +NID_pkcs7_digest +NID_pkcs7_encrypted +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_type_is_other()\fR returns either 0 if the content type is matched or 1 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPKCS7_type_is_data\fR\|(3), \fBPKCS7_get_octet_string\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS7_verify.3 b/static/netbsd/man3/PKCS7_verify.3 new file mode 100644 index 00000000..5e1612eb --- /dev/null +++ b/static/netbsd/man3/PKCS7_verify.3 @@ -0,0 +1,199 @@ +.\" $NetBSD: PKCS7_verify.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS7_verify 3" +.TH PKCS7_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS7_verify, PKCS7_get0_signers \- verify a PKCS#7 signedData structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, +\& BIO *indata, BIO *out, int flags); +\& +\& STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS7_verify()\fR is very similar to \fBCMS_verify\fR\|(3). +It verifies a PKCS#7 signedData structure given in \fIp7\fR. +The optional \fIcerts\fR parameter refers to a set of certificates +in which to search for signer\*(Aqs certificates. +It is also used +as a source of untrusted intermediate CA certificates for chain building. +\&\fIp7\fR may contain extra untrusted CA certificates that may be used for +chain building as well as CRLs that may be used for certificate validation. +\&\fIstore\fR may be NULL or point to +the trusted certificate store to use for chain verification. +\&\fIindata\fR refers to the signed data if the content is detached from \fIp7\fR. +Otherwise \fIindata\fR should be NULL, and then the signed data must be in \fIp7\fR. +The content is written to the BIO \fIout\fR unless it is NULL. +\&\fIflags\fR is an optional set of flags, which can be used to modify the operation. +.PP +\&\fBPKCS7_get0_signers()\fR retrieves the signer\*(Aqs certificates from \fIp7\fR, it does +\&\fBnot\fR check their validity or whether any signatures are valid. The \fIcerts\fR +and \fIflags\fR parameters have the same meanings as in \fBPKCS7_verify()\fR. +.SH "VERIFY PROCESS" +.IX Header "VERIFY PROCESS" +Normally the verify process proceeds as follows. +.PP +Initially some sanity checks are performed on \fIp7\fR. The type of \fIp7\fR must +be SignedData. There must be at least one signature on the data and if +the content is detached \fIindata\fR cannot be NULL. If the content is +not detached and \fIindata\fR is not NULL then the structure has both +embedded and external content. To treat this as an error, use the flag +\&\fBPKCS7_NO_DUAL_CONTENT\fR. +The default behavior allows this, for compatibility with older +versions of OpenSSL. +.PP +An attempt is made to locate all the signer\*(Aqs certificates, first looking in +the \fIcerts\fR parameter (if it is not NULL). Then they are looked up in any +certificates contained in the \fIp7\fR structure unless \fBPKCS7_NOINTERN\fR is set. +If any signer\*(Aqs certificates cannot be located the operation fails. +.PP +Each signer\*(Aqs certificate is chain verified using the \fBsmimesign\fR purpose and +using the trusted certificate store \fIstore\fR if supplied. +Any internal certificates in the message, which may have been added using +\&\fBPKCS7_add_certificate\fR\|(3), are used as untrusted CAs unless \fBPKCS7_NOCHAIN\fR +is set. +If CRL checking is enabled in \fIstore\fR and \fBPKCS7_NOCRL\fR is not set, +any internal CRLs, which may have been added using \fBPKCS7_add_crl\fR\|(3), +are used in addition to attempting to look them up in \fIstore\fR. +If \fIstore\fR is not NULL and any chain verify fails an error code is returned. +.PP +Finally the signed content is read (and written to \fIout\fR unless it is NULL) +and the signature is checked. +.PP +If all signatures verify correctly then the function is successful. +.PP +Any of the following flags (ored together) can be passed in the \fIflags\fR +parameter to change the default verify behaviour. +Only the flag \fBPKCS7_NOINTERN\fR is meaningful to \fBPKCS7_get0_signers()\fR. +.PP +If \fBPKCS7_NOINTERN\fR is set the certificates in the message itself are not +searched when locating the signer\*(Aqs certificates. +This means that all the signer\*(Aqs certificates must be in the \fIcerts\fR parameter. +.PP +If \fBPKCS7_NOCRL\fR is set and CRL checking is enabled in \fIstore\fR then any +CRLs in the message itself are ignored. +.PP +If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \f(CW\*(C`text/plain\*(C'\fR are deleted +from the content. If the content is not of type \f(CW\*(C`text/plain\*(C'\fR then an error is +returned. +.PP +If \fBPKCS7_NOVERIFY\fR is set the signer\*(Aqs certificates are not chain verified. +.PP +If \fBPKCS7_NOCHAIN\fR is set then the certificates contained in the message are +not used as untrusted CAs. This means that the whole verify chain (apart from +the signer\*(Aqs certificates) must be contained in the trusted store. +.PP +If \fBPKCS7_NOSIGS\fR is set then the signatures on the data are not checked. +.SH NOTES +.IX Header "NOTES" +One application of \fBPKCS7_NOINTERN\fR is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the \fIcerts\fR parameter. In this case if the signer\*(Aqs certificate is not one +of the certificates supplied in \fIcerts\fR then the verify will fail because the +signer cannot be found. +.PP +Care should be taken when modifying the default verify behaviour, for example +setting \f(CW\*(C`PKCS7_NOVERIFY|PKCS7_NOSIGS\*(C'\fR will totally disable all verification +and any signed message will be considered valid. This combination is however +useful if one merely wishes to write the content to \fIout\fR and its validity +is not considered important. +.PP +Chain verification should arguably be performed using the signing time rather +than the current time. However, since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS7_verify()\fR returns 1 for a successful verification and 0 if an error occurs. +.PP +\&\fBPKCS7_get0_signers()\fR returns all signers or NULL if an error occurred. +.PP +The error can be obtained from \fBERR_get_error\fR\|(3). +.SH BUGS +.IX Header "BUGS" +The trusted certificate store is not searched for the signer\*(Aqs certificates. +This is primarily due to the inadequacies of the current \fBX509_STORE\fR +functionality. +.PP +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCMS_verify\fR\|(3), \fBPKCS7_add_certificate\fR\|(3), \fBPKCS7_add_crl\fR\|(3), +\&\fBERR_get_error\fR\|(3), \fBPKCS7_sign\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS8_encrypt.3 b/static/netbsd/man3/PKCS8_encrypt.3 new file mode 100644 index 00000000..674ef7fb --- /dev/null +++ b/static/netbsd/man3/PKCS8_encrypt.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: PKCS8_encrypt.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS8_encrypt 3" +.TH PKCS8_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS8_decrypt, PKCS8_decrypt_ex, PKCS8_encrypt, PKCS8_encrypt_ex, +PKCS8_set0_pbe, PKCS8_set0_pbe_ex \- PKCS8 encrypt/decrypt functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS8_PRIV_KEY_INFO *PKCS8_decrypt(const X509_SIG *p8, const char *pass, +\& int passlen); +\& PKCS8_PRIV_KEY_INFO *PKCS8_decrypt_ex(const X509_SIG *p8, const char *pass, +\& int passlen, OSSL_LIB_CTX *ctx, +\& const char *propq); +\& X509_SIG *PKCS8_encrypt(int pbe_nid, const EVP_CIPHER *cipher, +\& const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8); +\& X509_SIG *PKCS8_encrypt_ex(int pbe_nid, const EVP_CIPHER *cipher, +\& const char *pass, int passlen, unsigned char *salt, +\& int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8, +\& OSSL_LIB_CTX *ctx, const char *propq); +\& X509_SIG *PKCS8_set0_pbe(const char *pass, int passlen, +\& PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe); +\& X509_SIG *PKCS8_set0_pbe_ex(const char *pass, int passlen, +\& PKCS8_PRIV_KEY_INFO *p8inf, X509_ALGOR *pbe, +\& OSSL_LIB_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS8_encrypt()\fR and \fBPKCS8_encrypt_ex()\fR perform encryption of an object \fIp8\fR using +the password \fIpass\fR of length \fIpasslen\fR, salt \fIsalt\fR of length \fIsaltlen\fR +and iteration count \fIiter\fR. +The resulting \fBX509_SIG\fR contains the encoded algorithm parameters and encrypted +key. +.PP +\&\fBPKCS8_decrypt()\fR and \fBPKCS8_decrypt_ex()\fR perform decryption of an \fBX509_SIG\fR in +\&\fIp8\fR using the password \fIpass\fR of length \fIpasslen\fR along with algorithm +parameters obtained from the \fIp8\fR. +.PP +\&\fBPKCS8_set0_pbe()\fR and \fBPKCS8_set0_pbe_ex()\fR perform encryption of the \fIp8inf\fR +using the password \fIpass\fR of length \fIpasslen\fR and parameters \fIpbe\fR. +.PP +Functions ending in \fB_ex()\fR allow for a library context \fIctx\fR and property query +\&\fIpropq\fR to be used to select algorithm implementations. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS8_encrypt()\fR, \fBPKCS8_encrypt_ex()\fR, \fBPKCS8_set0_pbe()\fR and \fBPKCS8_set0_pbe_ex()\fR +return an encrypted key in a \fBX509_SIG\fR structure or NULL if an error occurs. +.PP +\&\fBPKCS8_decrypt()\fR and \fBPKCS8_decrypt_ex()\fR return a \fBPKCS8_PRIV_KEY_INFO\fR or NULL +if an error occurs. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +IETF RFC 7292 () +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBPKCS8_decrypt_ex()\fR, \fBPKCS8_encrypt_ex()\fR and \fBPKCS8_set0_pbe_ex()\fR were added in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/PKCS8_pkey_add1_attr.3 b/static/netbsd/man3/PKCS8_pkey_add1_attr.3 new file mode 100644 index 00000000..75a9118d --- /dev/null +++ b/static/netbsd/man3/PKCS8_pkey_add1_attr.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: PKCS8_pkey_add1_attr.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "PKCS8_pkey_add1_attr 3" +.TH PKCS8_pkey_add1_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PKCS8_pkey_get0_attrs, PKCS8_pkey_add1_attr, PKCS8_pkey_add1_attr_by_NID, PKCS8_pkey_add1_attr_by_OBJ \- PKCS8 attribute functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const STACK_OF(X509_ATTRIBUTE) * +\& PKCS8_pkey_get0_attrs(const PKCS8_PRIV_KEY_INFO *p8); +\& int PKCS8_pkey_add1_attr(PKCS8_PRIV_KEY_INFO *p8, X509_ATTRIBUTE *attr); +\& int PKCS8_pkey_add1_attr_by_NID(PKCS8_PRIV_KEY_INFO *p8, int nid, int type, +\& const unsigned char *bytes, int len); +\& int PKCS8_pkey_add1_attr_by_OBJ(PKCS8_PRIV_KEY_INFO *p8, const ASN1_OBJECT *obj, +\& int type, const unsigned char *bytes, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPKCS8_pkey_get0_attrs()\fR returns a const STACK of X509_ATTRIBUTE present in +the passed const PKCS8_PRIV_KEY_INFO structure \fBp8\fR. +.PP +\&\fBPKCS8_pkey_add1_attr()\fR adds a constructed X509_ATTRIBUTE \fBattr\fR to the +existing PKCS8_PRIV_KEY_INFO structure \fBp8\fR. +.PP +\&\fBPKCS8_pkey_add1_attr_by_NID()\fR and \fBPKCS8_pkey_add1_attr_by_OBJ()\fR construct a new +X509_ATTRIBUTE from the passed arguments and add it to the existing +PKCS8_PRIV_KEY_INFO structure \fBp8\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBPKCS8_pkey_add1_attr()\fR, \fBPKCS8_pkey_add1_attr_by_NID()\fR, and +\&\fBPKCS8_pkey_add1_attr_by_OBJ()\fR return 1 for success and 0 for failure. +.SH NOTES +.IX Header "NOTES" +STACK of X509_ATTRIBUTE is present in many X509\-related structures and some of +them have the corresponding set of similar functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_generate.3 b/static/netbsd/man3/RAND_DRBG_generate.3 new file mode 100644 index 00000000..be144e60 --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_generate.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: RAND_DRBG_generate.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_generate 3" +.TH RAND_DRBG_generate 3 "2019-06-09" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_generate, +RAND_DRBG_bytes +\&\- generate random bytes using the given drbg instance +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_DRBG_generate(RAND_DRBG *drbg, +\& unsigned char *out, size_t outlen, +\& int prediction_resistance, +\& const unsigned char *adin, size_t adinlen); +\& +\& int RAND_DRBG_bytes(RAND_DRBG *drbg, +\& unsigned char *out, size_t outlen); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBRAND_DRBG_generate()\fR generates \fBoutlen\fR random bytes using the given +\&\s-1DRBG\s0 instance \fBdrbg\fR and stores them in the buffer at \fBout\fR. +.PP +Before generating the output, the \s-1DRBG\s0 instance checks whether the maximum +number of generate requests (\fIreseed interval\fR) or the maximum timespan +(\fIreseed time interval\fR) since its last seeding have been reached. +If this is the case, the \s-1DRBG\s0 reseeds automatically. +Additionally, an immediate reseeding can be requested by setting the +\&\fBprediction_resistance\fR flag to 1. See \s-1NOTES\s0 section for more details. +.PP +The caller can optionally provide additional data to be used for reseeding +by passing a pointer \fBadin\fR to a buffer of length \fBadinlen\fR. +This additional data is mixed into the internal state of the random +generator but does not contribute to the entropy count. +The additional data can be omitted by setting \fBadin\fR to \s-1NULL\s0 and +\&\fBadinlen\fR to 0; +.PP +\&\fBRAND_DRBG_bytes()\fR generates \fBoutlen\fR random bytes using the given +\&\s-1DRBG\s0 instance \fBdrbg\fR and stores them in the buffer at \fBout\fR. +This function is a wrapper around the \fBRAND_DRBG_generate()\fR call, +which collects some additional data from low entropy sources +(e.g., a high resolution timer) and calls +RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_generate()\fR and \fBRAND_DRBG_bytes()\fR return 1 on success, +and 0 on failure. +.SH "NOTES" +.IX Header "NOTES" +The \fIreseed interval\fR and \fIreseed time interval\fR of the \fBdrbg\fR are set to +reasonable default values, which in general do not have to be adjusted. +If necessary, they can be changed using \fBRAND_DRBG_set_reseed_interval\fR\|(3) +and \fBRAND_DRBG_set_reseed_time_interval\fR\|(3), respectively. +.PP +A request for prediction resistance can only be satisfied by pulling fresh +entropy from one of the approved entropy sources listed in section 5.5.2 of +[\s-1NIST SP 800\-90C\s0]. +Since the default \s-1DRBG\s0 implementation does not have access to such an approved +entropy source, a request for prediction resistance will always fail. +In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_DRBG_set_reseed_interval\fR\|(3), +\&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3), +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_get0_master.3 b/static/netbsd/man3/RAND_DRBG_get0_master.3 new file mode 100644 index 00000000..1d97692b --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_get0_master.3 @@ -0,0 +1,211 @@ +.\" $NetBSD: RAND_DRBG_get0_master.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_get0_master 3" +.TH RAND_DRBG_get0_master 3 "2019-06-09" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_get0_master, +RAND_DRBG_get0_public, +RAND_DRBG_get0_private +\&\- get access to the global RAND_DRBG instances +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& RAND_DRBG *RAND_DRBG_get0_master(void); +\& RAND_DRBG *RAND_DRBG_get0_public(void); +\& RAND_DRBG *RAND_DRBG_get0_private(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The default \s-1RAND API\s0 implementation (\fBRAND_OpenSSL()\fR) utilizes three +shared \s-1DRBG\s0 instances which are accessed via the \s-1RAND API:\s0 +.PP +The and \s-1DRBG\s0 are thread-local instances, which are used +by \fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR, respectively. +The \s-1DRBG\s0 is a global instance, which is not intended to be used +directly, but is used internally to reseed the other two instances. +.PP +These functions here provide access to the shared \s-1DRBG\s0 instances. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_get0_master()\fR returns a pointer to the \s-1DRBG\s0 instance. +.PP +\&\fBRAND_DRBG_get0_public()\fR returns a pointer to the \s-1DRBG\s0 instance. +.PP +\&\fBRAND_DRBG_get0_private()\fR returns a pointer to the \s-1DRBG\s0 instance. +.SH "NOTES" +.IX Header "NOTES" +It is not thread-safe to access the \s-1DRBG\s0 instance. +The and \s-1DRBG\s0 instance can be accessed safely, because +they are thread-local. Note however, that changes to these two instances +apply only to the current thread. +.PP +For that reason it is recommended not to change the settings of these +three instances directly. +Instead, an application should change the default settings for new \s-1DRBG\s0 instances +at initialization time, before creating additional threads. +.PP +During initialization, it is possible to change the reseed interval +and reseed time interval. +It is also possible to exchange the reseeding callbacks entirely. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_DRBG_set_callbacks\fR\|(3), +\&\fBRAND_DRBG_set_reseed_defaults\fR\|(3), +\&\fBRAND_DRBG_set_reseed_interval\fR\|(3), +\&\fBRAND_DRBG_set_reseed_time_interval\fR\|(3), +\&\fBRAND_DRBG_set_callbacks\fR\|(3), +\&\fBRAND_DRBG_generate\fR\|(3), +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_new.3 b/static/netbsd/man3/RAND_DRBG_new.3 new file mode 100644 index 00000000..d031859b --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_new.3 @@ -0,0 +1,258 @@ +.\" $NetBSD: RAND_DRBG_new.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_new 3" +.TH RAND_DRBG_new 3 "2020-12-10" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_new, +RAND_DRBG_secure_new, +RAND_DRBG_set, +RAND_DRBG_set_defaults, +RAND_DRBG_instantiate, +RAND_DRBG_uninstantiate, +RAND_DRBG_free +\&\- initialize and cleanup a RAND_DRBG instance +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& +\& RAND_DRBG *RAND_DRBG_new(int type, +\& unsigned int flags, +\& RAND_DRBG *parent); +\& +\& RAND_DRBG *RAND_DRBG_secure_new(int type, +\& unsigned int flags, +\& RAND_DRBG *parent); +\& +\& int RAND_DRBG_set(RAND_DRBG *drbg, +\& int type, unsigned int flags); +\& +\& int RAND_DRBG_set_defaults(int type, unsigned int flags); +\& +\& int RAND_DRBG_instantiate(RAND_DRBG *drbg, +\& const unsigned char *pers, size_t perslen); +\& +\& int RAND_DRBG_uninstantiate(RAND_DRBG *drbg); +\& +\& void RAND_DRBG_free(RAND_DRBG *drbg); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBRAND_DRBG_new()\fR and \fBRAND_DRBG_secure_new()\fR +create a new \s-1DRBG\s0 instance of the given \fBtype\fR, allocated from the heap resp. +the secure heap +(using \fBOPENSSL_zalloc()\fR resp. \fBOPENSSL_secure_zalloc()\fR). +.PP +\&\fBRAND_DRBG_set()\fR initializes the \fBdrbg\fR with the given \fBtype\fR and \fBflags\fR. +.PP +\&\fBRAND_DRBG_set_defaults()\fR sets the default \fBtype\fR and \fBflags\fR for new \s-1DRBG\s0 +instances. +.PP +Currently, all \s-1DRBG\s0 types are based on AES-CTR, so \fBtype\fR can be one of the +following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr. +Before the \s-1DRBG\s0 can be used to generate random bits, it is necessary to set +its type and to instantiate it. +.PP +The optional \fBflags\fR argument specifies a set of bit flags which can be +joined using the | operator. Currently, the only flag is +\&\s-1RAND_DRBG_FLAG_CTR_NO_DF,\s0 which disables the use of the derivation function +ctr_df. For an explanation, see [\s-1NIST SP 800\-90A\s0 Rev. 1]. +.PP +If a \fBparent\fR instance is specified then this will be used instead of +the default entropy source for reseeding the \fBdrbg\fR. It is said that the +\&\fBdrbg\fR is \fIchained\fR to its \fBparent\fR. +For more information, see the \s-1NOTES\s0 section. +.PP +\&\fBRAND_DRBG_instantiate()\fR +seeds the \fBdrbg\fR instance using random input from trusted entropy sources. +Optionally, a personalization string \fBpers\fR of length \fBperslen\fR can be +specified. +To omit the personalization string, set \fBpers\fR=NULL and \fBperslen\fR=0; +.PP +\&\fBRAND_DRBG_uninstantiate()\fR +clears the internal state of the \fBdrbg\fR and puts it back in the +uninstantiated state. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_new()\fR and \fBRAND_DRBG_secure_new()\fR return a pointer to a \s-1DRBG\s0 +instance allocated on the heap, resp. secure heap. +.PP +\&\fBRAND_DRBG_set()\fR, +\&\fBRAND_DRBG_instantiate()\fR, and +\&\fBRAND_DRBG_uninstantiate()\fR +return 1 on success, and 0 on failure. +.PP +\&\fBRAND_DRBG_free()\fR does not return a value. +.SH "NOTES" +.IX Header "NOTES" +The \s-1DRBG\s0 design supports \fIchaining\fR, which means that a \s-1DRBG\s0 instance can +use another \fBparent\fR \s-1DRBG\s0 instance instead of the default entropy source +to obtain fresh random input for reseeding, provided that \fBparent\fR \s-1DRBG\s0 +instance was properly instantiated, either from a trusted entropy source, +or from yet another parent \s-1DRBG\s0 instance. +For a detailed description of the reseeding process, see \s-1\fBRAND_DRBG\s0\fR\|(7). +.PP +The default \s-1DRBG\s0 type and flags are applied only during creation of a \s-1DRBG\s0 +instance. +To ensure that they are applied to the global and thread-local \s-1DRBG\s0 instances +(, resp. and ), it is necessary to call +\&\fBRAND_DRBG_set_defaults()\fR before creating any thread and before calling any +cryptographic routines that obtain random data directly or indirectly. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOPENSSL_zalloc\fR\|(3), +\&\fBOPENSSL_secure_zalloc\fR\|(3), +\&\fBRAND_DRBG_generate\fR\|(3), +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_reseed.3 b/static/netbsd/man3/RAND_DRBG_reseed.3 new file mode 100644 index 00000000..f76a7fb8 --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_reseed.3 @@ -0,0 +1,247 @@ +.\" $NetBSD: RAND_DRBG_reseed.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_reseed 3" +.TH RAND_DRBG_reseed 3 "2019-06-09" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_reseed, +RAND_DRBG_set_reseed_interval, +RAND_DRBG_set_reseed_time_interval, +RAND_DRBG_set_reseed_defaults +\&\- reseed a RAND_DRBG instance +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_DRBG_reseed(RAND_DRBG *drbg, +\& const unsigned char *adin, size_t adinlen, +\& int prediction_resistance); +\& +\& int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg, +\& unsigned int interval); +\& +\& int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg, +\& time_t interval); +\& +\& int RAND_DRBG_set_reseed_defaults( +\& unsigned int master_reseed_interval, +\& unsigned int slave_reseed_interval, +\& time_t master_reseed_time_interval, +\& time_t slave_reseed_time_interval +\& ); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBRAND_DRBG_reseed()\fR +reseeds the given \fBdrbg\fR, obtaining entropy input from its entropy source +and mixing in the specified additional data provided in the buffer \fBadin\fR +of length \fBadinlen\fR. +The additional data can be omitted by setting \fBadin\fR to \s-1NULL\s0 and \fBadinlen\fR +to 0. +An immediate reseeding from a live entropy source can be requested by setting +the \fBprediction_resistance\fR flag to 1. +This feature is not implemented yet, so reseeding with prediction resistance +requested will always fail. +.PP +\&\fBRAND_DRBG_set_reseed_interval()\fR +sets the reseed interval of the \fBdrbg\fR, which is the maximum allowed number +of generate requests between consecutive reseedings. +If \fBinterval\fR > 0, then the \fBdrbg\fR will reseed automatically whenever the +number of generate requests since its last seeding exceeds the given reseed +interval. +If \fBinterval\fR == 0, then this feature is disabled. +.PP +\&\fBRAND_DRBG_set_reseed_time_interval()\fR +sets the reseed time interval of the \fBdrbg\fR, which is the maximum allowed +number of seconds between consecutive reseedings. +If \fBinterval\fR > 0, then the \fBdrbg\fR will reseed automatically whenever the +elapsed time since its last reseeding exceeds the given reseed time interval. +If \fBinterval\fR == 0, then this feature is disabled. +.PP +\&\fBRAND_DRBG_set_reseed_defaults()\fR sets the default values for the reseed interval +(\fBmaster_reseed_interval\fR and \fBslave_reseed_interval\fR) +and the reseed time interval +(\fBmaster_reseed_time_interval\fR and \fBslave_reseed_tme_interval\fR) +of \s-1DRBG\s0 instances. +The default values are set independently for master \s-1DRBG\s0 instances (which don't +have a parent) and slave \s-1DRBG\s0 instances (which are chained to a parent \s-1DRBG\s0). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_reseed()\fR, +\&\fBRAND_DRBG_set_reseed_interval()\fR, and +\&\fBRAND_DRBG_set_reseed_time_interval()\fR, +return 1 on success, 0 on failure. +.SH "NOTES" +.IX Header "NOTES" +The default OpenSSL random generator is already set up for automatic reseeding, +so in general it is not necessary to reseed it explicitly, or to modify +its reseeding thresholds. +.PP +Normally, the entropy input for seeding a \s-1DRBG\s0 is either obtained from a +trusted os entropy source or from a parent \s-1DRBG\s0 instance, which was seeded +(directly or indirectly) from a trusted os entropy source. +In exceptional cases it is possible to replace the reseeding mechanism entirely +by providing application defined callbacks using \fBRAND_DRBG_set_callbacks()\fR. +.PP +The reseeding default values are applied only during creation of a \s-1DRBG\s0 instance. +To ensure that they are applied to the global and thread-local \s-1DRBG\s0 instances +(, resp. and ), it is necessary to call +\&\fBRAND_DRBG_set_reseed_defaults()\fR before creating any thread and before calling any + cryptographic routines that obtain random data directly or indirectly. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_DRBG_generate\fR\|(3), +\&\fBRAND_DRBG_bytes\fR\|(3), +\&\fBRAND_DRBG_set_callbacks\fR\|(3). +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_set_callbacks.3 b/static/netbsd/man3/RAND_DRBG_set_callbacks.3 new file mode 100644 index 00000000..3812083f --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_set_callbacks.3 @@ -0,0 +1,277 @@ +.\" $NetBSD: RAND_DRBG_set_callbacks.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_set_callbacks 3" +.TH RAND_DRBG_set_callbacks 3 "2020-12-10" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_set_callbacks, +RAND_DRBG_get_entropy_fn, +RAND_DRBG_cleanup_entropy_fn, +RAND_DRBG_get_nonce_fn, +RAND_DRBG_cleanup_nonce_fn +\&\- set callbacks for reseeding +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& +\& int RAND_DRBG_set_callbacks(RAND_DRBG *drbg, +\& RAND_DRBG_get_entropy_fn get_entropy, +\& RAND_DRBG_cleanup_entropy_fn cleanup_entropy, +\& RAND_DRBG_get_nonce_fn get_nonce, +\& RAND_DRBG_cleanup_nonce_fn cleanup_nonce); +.Ve +.SS "Callback Functions" +.IX Subsection "Callback Functions" +.Vb 6 +\& typedef size_t (*RAND_DRBG_get_entropy_fn)( +\& RAND_DRBG *drbg, +\& unsigned char **pout, +\& int entropy, +\& size_t min_len, size_t max_len, +\& int prediction_resistance); +\& +\& typedef void (*RAND_DRBG_cleanup_entropy_fn)( +\& RAND_DRBG *drbg, +\& unsigned char *out, size_t outlen); +\& +\& typedef size_t (*RAND_DRBG_get_nonce_fn)( +\& RAND_DRBG *drbg, +\& unsigned char **pout, +\& int entropy, +\& size_t min_len, size_t max_len); +\& +\& typedef void (*RAND_DRBG_cleanup_nonce_fn)( +\& RAND_DRBG *drbg, +\& unsigned char *out, size_t outlen); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBRAND_DRBG_set_callbacks()\fR sets the callbacks for obtaining fresh entropy and +the nonce when reseeding the given \fBdrbg\fR. +The callback functions are implemented and provided by the caller. +Their parameter lists need to match the function prototypes above. +.PP +Setting the callbacks is allowed only if the \s-1DRBG\s0 has not been initialized yet. +Otherwise, the operation will fail. +To change the settings for one of the three shared DRBGs it is necessary to call +\&\fBRAND_DRBG_uninstantiate()\fR first. +.PP +The \fBget_entropy\fR() callback is called by the \fBdrbg\fR when it requests fresh +random input. +It is expected that the callback allocates and fills a random buffer of size +\&\fBmin_len\fR <= size <= \fBmax_len\fR (in bytes) which contains at least \fBentropy\fR +bits of randomness. +The \fBprediction_resistance\fR flag indicates whether the reseeding was +triggered by a prediction resistance request. +.PP +The buffer's address is to be returned in *\fBpout\fR and the number of collected +randomness bytes as return value. +.PP +If the callback fails to acquire at least \fBentropy\fR bits of randomness, +it must indicate an error by returning a buffer length of 0. +.PP +If \fBprediction_resistance\fR was requested and the random source of the \s-1DRBG\s0 +does not satisfy the conditions requested by [\s-1NIST SP 800\-90C\s0], then +it must also indicate an error by returning a buffer length of 0. +See \s-1NOTES\s0 section for more details. +.PP +The \fBcleanup_entropy\fR() callback is called from the \fBdrbg\fR to clear and +free the buffer allocated previously by \fBget_entropy()\fR. +The values \fBout\fR and \fBoutlen\fR are the random buffer's address and length, +as returned by the \fBget_entropy()\fR callback. +.PP +The \fBget_nonce\fR() and \fBcleanup_nonce\fR() callbacks are used to obtain a nonce +and free it again. A nonce is only required for instantiation (not for reseeding) +and only in the case where the \s-1DRBG\s0 uses a derivation function. +The callbacks are analogous to \fBget_entropy()\fR and \fBcleanup_entropy()\fR, +except for the missing prediction_resistance flag. +.PP +If the derivation function is disabled, then no nonce is used for instantiation, +and the \fBget_nonce\fR() and \fBcleanup_nonce\fR() callbacks can be omitted by +setting them to \s-1NULL.\s0 +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_set_callbacks()\fR return 1 on success, and 0 on failure +.SH "NOTES" +.IX Header "NOTES" +It is important that \fBcleanup_entropy\fR() and \fBcleanup_nonce\fR() clear the buffer +contents safely before freeing it, in order not to leave sensitive information +about the \s-1DRBG\s0's state in memory. +.PP +A request for prediction resistance can only be satisfied by pulling fresh +entropy from one of the approved entropy sources listed in section 5.5.2 of +[\s-1NIST SP 800\-90C\s0]. +Since the default implementation of the get_entropy callback does not have access +to such an approved entropy source, a request for prediction resistance will +always fail. +In other words, prediction resistance is currently not supported yet by the \s-1DRBG.\s0 +.PP +The derivation function is disabled during initialization by calling the +\&\fBRAND_DRBG_set()\fR function with the \s-1RAND_DRBG_FLAG_CTR_NO_DF\s0 flag. +For more information on the derivation function and when it can be omitted, +see [\s-1NIST SP 800\-90A\s0 Rev. 1]. Roughly speaking it can be omitted if the random +source has \*(L"full entropy\*(R", i.e., contains 8 bits of entropy per byte. +.PP +Even if a nonce is required, the \fBget_nonce\fR() and \fBcleanup_nonce\fR() +callbacks can be omitted by setting them to \s-1NULL.\s0 +In this case the \s-1DRBG\s0 will automatically request an extra amount of entropy +(using the \fBget_entropy\fR() and \fBcleanup_entropy\fR() callbacks) which it will +utilize for the nonce, following the recommendations of [\s-1NIST SP 800\-90A\s0 Rev. 1], +section 8.6.7. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_DRBG_new\fR\|(3), +\&\fBRAND_DRBG_reseed\fR\|(3), +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1RAND_DRBG\s0 functions were added in OpenSSL 1.1.1. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_DRBG_set_ex_data.3 b/static/netbsd/man3/RAND_DRBG_set_ex_data.3 new file mode 100644 index 00000000..eb38a8a5 --- /dev/null +++ b/static/netbsd/man3/RAND_DRBG_set_ex_data.3 @@ -0,0 +1,200 @@ +.\" $NetBSD: RAND_DRBG_set_ex_data.3,v 1.3 2020/12/10 00:33:12 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RAND_DRBG_set_ex_data 3" +.TH RAND_DRBG_set_ex_data 3 "2018-09-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RAND_DRBG_set_ex_data, +RAND_DRBG_get_ex_data, +RAND_DRBG_get_ex_new_index +\&\- store and retrieve extra data from the DRBG instance +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_DRBG_set_ex_data(RAND_DRBG *drbg, int idx, void *data); +\& +\& void *RAND_DRBG_get_ex_data(const RAND_DRBG *drbg, int idx); +\& +\& int RAND_DRBG_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBRAND_DRBG_set_ex_data()\fR enables an application to store arbitrary application +specific data \fBdata\fR in a \s-1RAND_DRBG\s0 instance \fBdrbg\fR. The index \fBidx\fR should +be a value previously returned from a call to \fBRAND_DRBG_get_ex_new_index()\fR. +.PP +\&\fBRAND_DRBG_get_ex_data()\fR retrieves application specific data previously stored +in an \s-1RAND_DRBG\s0 instance \fBdrbg\fR. The \fBidx\fR value should be the same as that +used when originally storing the data. +.PP +For more detailed information see \fBCRYPTO_get_ex_data\fR\|(3) and +\&\fBCRYPTO_set_ex_data\fR\|(3) which implement these functions and +\&\fBCRYPTO_get_ex_new_index\fR\|(3) for generating a unique index. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_DRBG_set_ex_data()\fR returns 1 for success or 0 for failure. +.PP +\&\fBRAND_DRBG_get_ex_data()\fR returns the previously stored value or \s-1NULL\s0 on +failure. \s-1NULL\s0 may also be a valid value. +.SH "NOTES" +.IX Header "NOTES" +RAND_DRBG_get_ex_new_index(...) is implemented as a macro and equivalent to +CRYPTO_get_ex_new_index(\s-1CRYPTO_EX_INDEX_DRBG,...\s0). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCRYPTO_get_ex_data\fR\|(3), +\&\fBCRYPTO_set_ex_data\fR\|(3), +\&\fBCRYPTO_get_ex_new_index\fR\|(3), +\&\s-1\fBRAND_DRBG\s0\fR\|(7) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_add.3 b/static/netbsd/man3/RAND_add.3 new file mode 100644 index 00000000..6a81009c --- /dev/null +++ b/static/netbsd/man3/RAND_add.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: RAND_add.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_add 3" +.TH RAND_add 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen, +RAND_keep_random_devices_open +\&\- add randomness to the PRNG or get its status +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_status(void); +\& int RAND_poll(); +\& +\& void RAND_add(const void *buf, int num, double randomness); +\& void RAND_seed(const void *buf, int num); +\& +\& void RAND_keep_random_devices_open(int keep); +.Ve +.PP +The following functions have been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); +\& void RAND_screen(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions can be used to seed the random generator and to check its +seeded state. +In general, manual (re\-)seeding of the default OpenSSL random generator +(\fBRAND_OpenSSL\fR\|(3)) is not necessary (but allowed), since it does (re\-)seed +itself automatically using trusted system entropy sources. +This holds unless the default RAND_METHOD has been replaced or OpenSSL was +built with automatic reseeding disabled, see \fBRAND\fR\|(7) for more details. +.PP +\&\fBRAND_status()\fR indicates whether or not the random generator has been sufficiently +seeded. If not, functions such as \fBRAND_bytes\fR\|(3) will fail. +.PP +\&\fBRAND_poll()\fR uses the system\*(Aqs capabilities to seed the random generator using +random input obtained from polling various trusted entropy sources. +The default choice of the entropy source can be modified at build time, +see \fBRAND\fR\|(7) for more details. +.PP +\&\fBRAND_add()\fR mixes the \fBnum\fR bytes at \fBbuf\fR into the internal state +of the random generator. +This function will not normally be needed, as mentioned above. +The \fBrandomness\fR argument is an estimate of how much randomness is +contained in +\&\fBbuf\fR, in bytes, and should be a number between zero and \fBnum\fR. +Details about sources of randomness and how to estimate their randomness +can be found in the literature; for example [NIST SP 800\-90B]. +The content of \fBbuf\fR cannot be recovered from subsequent random generator output. +Applications that intend to save and restore random state in an external file +should consider using \fBRAND_load_file\fR\|(3) instead. +.PP +NOTE: In FIPS mode, random data provided by the application is not considered to +be a trusted entropy source. It is mixed into the internal state of the RNG as +additional data only and this does not count as a full reseed. +For more details, see \fBEVP_RAND\fR\|(7). +.PP +\&\fBRAND_seed()\fR is equivalent to \fBRAND_add()\fR with \fBrandomness\fR set to \fBnum\fR. +.PP +\&\fBRAND_keep_random_devices_open()\fR is used to control file descriptor +usage by the random seed sources. Some seed sources maintain open file +descriptors by default, which allows such sources to operate in a +\&\fBchroot\fR\|(2) jail without the associated device nodes being available. When +the \fBkeep\fR argument is zero, this call disables the retention of file +descriptors. Conversely, a nonzero argument enables the retention of +file descriptors. This function is usually called during initialization +and it takes effect immediately. This capability only applies to the default +provider. +.PP +\&\fBRAND_event()\fR and \fBRAND_screen()\fR are equivalent to \fBRAND_poll()\fR and exist +for compatibility reasons only. See HISTORY section below. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_status()\fR returns 1 if the random generator has been seeded +with enough data, 0 otherwise. +.PP +\&\fBRAND_poll()\fR returns 1 if it generated seed data, 0 otherwise. +.PP +\&\fBRAND_event()\fR returns \fBRAND_status()\fR. +.PP +The other functions do not return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_egd\fR\|(3), +\&\fBRAND_load_file\fR\|(3), +\&\fBRAND\fR\|(7) +\&\fBEVP_RAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBRAND_event()\fR and \fBRAND_screen()\fR were deprecated in OpenSSL 1.1.0 and should +not be used. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_bytes.3 b/static/netbsd/man3/RAND_bytes.3 new file mode 100644 index 00000000..a026f511 --- /dev/null +++ b/static/netbsd/man3/RAND_bytes.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: RAND_bytes.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_bytes 3" +.TH RAND_bytes 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_bytes, RAND_priv_bytes, RAND_bytes_ex, RAND_priv_bytes_ex, +RAND_pseudo_bytes, RAND_set1_random_provider \- generate random data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_bytes(unsigned char *buf, int num); +\& int RAND_priv_bytes(unsigned char *buf, int num); +\& +\& int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, +\& unsigned int strength); +\& int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, +\& unsigned int strength); +\& +\& int RAND_set1_random_provider(OSSL_LIB_CTX *ctx, OSSL_PROVIDER *p); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int RAND_pseudo_bytes(unsigned char *buf, int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRAND_bytes()\fR generates \fBnum\fR random bytes using a cryptographically +secure pseudo random generator (CSPRNG) and stores them in \fBbuf\fR. \fBbuf\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBRAND_priv_bytes()\fR has the same semantics as \fBRAND_bytes()\fR. It is intended to +be used for generating values that should remain private. If using the +default RAND_METHOD, this function uses a separate "private" PRNG +instance so that a compromise of the "public" PRNG instance will not +affect the secrecy of these private values, as described in \fBRAND\fR\|(7) +and \fBEVP_RAND\fR\|(7). +.PP +\&\fBRAND_bytes_ex()\fR and \fBRAND_priv_bytes_ex()\fR are the same as \fBRAND_bytes()\fR and +\&\fBRAND_priv_bytes()\fR except that they both take additional \fIstrength\fR and +\&\fIctx\fR parameters. The bytes generated will have a security strength of at +least \fIstrength\fR bits. +The DRBG used for the operation is the public or private DRBG associated with +the specified \fIctx\fR. The parameter can be NULL, in which case +the default library context is used (see \fBOSSL_LIB_CTX\fR\|(3). +If the default RAND_METHOD has been changed then for compatibility reasons the +RAND_METHOD will be used in preference and the DRBG of the library context +ignored. +.PP +\&\fBRAND_set1_random_provider()\fR specifies a provider, \fIprov\fR, which will be used +by the library context \fIctx\fR for all of the generate calls above instead +of the built\-in in DRBGs and entropy source. Pass NULL for the provider +to disable the random provider functionality. In this case, the built\-in DRBGs +and entropy source will be used. This call should not be considered thread safe. +.SH NOTES +.IX Header "NOTES" +By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it +was able to seed itself from a trusted entropy source. +On all major platforms supported by OpenSSL (including the Unix\-like platforms +and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use +using the operating systems\*(Aqs random generator. +.PP +If the entropy source fails or is not available, the CSPRNG will enter an +error state and refuse to generate random bytes. For that reason, it is important +to always check the error return value of \fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR and +not take randomness for granted. +.PP +On other platforms, there might not be a trusted entropy source available +or OpenSSL might have been explicitly configured to use different entropy sources. +If you are in doubt about the quality of the entropy source, don\*(Aqt hesitate to ask +your operating system vendor or post a question on GitHub or the openssl\-users +mailing list. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR +return 1 on success, \-1 if not supported by the current +RAND method, or 0 on other failure. The error code can be +obtained by \fBERR_get_error\fR\|(3). +.PP +\&\fBRAND_set1_random_provider()\fR returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_add\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_priv_bytes\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBRAND\fR\|(7), +\&\fBEVP_RAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +.IP \(bu 2 +\&\fBRAND_pseudo_bytes()\fR was deprecated in OpenSSL 1.1.0; use \fBRAND_bytes()\fR instead. +.IP \(bu 2 +The \fBRAND_priv_bytes()\fR function was added in OpenSSL 1.1.1. +.IP \(bu 2 +The \fBRAND_bytes_ex()\fR and \fBRAND_priv_bytes_ex()\fR functions were added in OpenSSL 3.0 +.IP \(bu 2 +The \fBRAND_set1_random_provider()\fR function was added in OpenSSL 3.5 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_cleanup.3 b/static/netbsd/man3/RAND_cleanup.3 new file mode 100644 index 00000000..92baf673 --- /dev/null +++ b/static/netbsd/man3/RAND_cleanup.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: RAND_cleanup.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_cleanup 3" +.TH RAND_cleanup 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_cleanup \- erase the PRNG state +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void RAND_cleanup(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Prior to OpenSSL 1.1.0, \fBRAND_cleanup()\fR released all resources used by +the PRNG. As of version 1.1.0, it does nothing and should not be called, +since no explicit initialisation or de\-initialisation is necessary. See +\&\fBOPENSSL_init_crypto\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_cleanup()\fR returns no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBRAND_cleanup()\fR was deprecated in OpenSSL 1.1.0; do not use it. +See \fBOPENSSL_init_crypto\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_egd.3 b/static/netbsd/man3/RAND_egd.3 new file mode 100644 index 00000000..5104b330 --- /dev/null +++ b/static/netbsd/man3/RAND_egd.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: RAND_egd.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_egd 3" +.TH RAND_egd 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes \- query entropy gathering daemon +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_egd_bytes(const char *path, int num); +\& int RAND_egd(const char *path); +\& +\& int RAND_query_egd_bytes(const char *path, unsigned char *buf, int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +On older platforms without a good source of randomness such as \f(CW\*(C`/dev/urandom\*(C'\fR, +it is possible to query an Entropy Gathering Daemon (EGD) over a local +socket to obtain randomness and seed the OpenSSL RNG. +The protocol used is defined by the EGDs available at + or . +.PP +\&\fBRAND_egd_bytes()\fR requests \fBnum\fR bytes of randomness from an EGD at the +specified socket \fBpath\fR, and passes the data it receives into \fBRAND_add()\fR. +\&\fBRAND_egd()\fR is equivalent to \fBRAND_egd_bytes()\fR with \fBnum\fR set to 255. +.PP +\&\fBRAND_query_egd_bytes()\fR requests \fBnum\fR bytes of randomness from an EGD at +the specified socket \fBpath\fR, where \fBnum\fR must be less than 256. +If \fBbuf\fR is \fBNULL\fR, it is equivalent to \fBRAND_egd_bytes()\fR. +If \fBbuf\fR is not \fBNULL\fR, then the data is copied to the buffer and +\&\fBRAND_add()\fR is not called. +.PP +OpenSSL can be configured at build time to try to use the EGD for seeding +automatically. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_egd()\fR and \fBRAND_egd_bytes()\fR return the number of bytes read from the +daemon on success, or \-1 if the connection failed or the daemon did not +return enough data to fully seed the PRNG. +.PP +\&\fBRAND_query_egd_bytes()\fR returns the number of bytes read from the daemon on +success, or \-1 if the connection failed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_add\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_file_name.3 b/static/netbsd/man3/RAND_file_name.3 new file mode 100644 index 00000000..16f2fdd1 --- /dev/null +++ b/static/netbsd/man3/RAND_file_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_file_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_get0_primary.3 b/static/netbsd/man3/RAND_get0_primary.3 new file mode 100644 index 00000000..57a17766 --- /dev/null +++ b/static/netbsd/man3/RAND_get0_primary.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: RAND_get0_primary.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_get0_primary 3" +.TH RAND_get0_primary 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_get0_primary, +RAND_get0_public, +RAND_get0_private, +RAND_set0_public, +RAND_set0_private +\&\- get access to the global EVP_RAND_CTX instances +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_RAND_CTX *RAND_get0_primary(OSSL_LIB_CTX *ctx); +\& EVP_RAND_CTX *RAND_get0_public(OSSL_LIB_CTX *ctx); +\& EVP_RAND_CTX *RAND_get0_private(OSSL_LIB_CTX *ctx); +\& int RAND_set0_public(OSSL_LIB_CTX *ctx, EVP_RAND_CTX *rand); +\& int RAND_set0_private(OSSL_LIB_CTX *ctx, EVP_RAND_CTX *rand); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The default RAND API implementation (\fBRAND_OpenSSL()\fR) utilizes three +shared DRBG instances which are accessed via the RAND API: +.PP +The \fIpublic\fR and \fIprivate\fR DRBG are thread\-local instances, which are used +by \fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR, respectively. +The \fIprimary\fR DRBG is a global instance, which is not intended to be used +directly, but is used internally to reseed the other two instances. +.PP +The three get functions provide access to the shared DRBG instances. +.PP +The two set functions allow the public and private DRBG instances to be +replaced by another random number generator. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_get0_primary()\fR returns a pointer to the \fIprimary\fR DRBG instance +for the given OSSL_LIB_CTX \fBctx\fR. +.PP +\&\fBRAND_get0_public()\fR returns a pointer to the \fIpublic\fR DRBG instance +for the given OSSL_LIB_CTX \fBctx\fR. +.PP +\&\fBRAND_get0_private()\fR returns a pointer to the \fIprivate\fR DRBG instance +for the given OSSL_LIB_CTX \fBctx\fR. +.PP +\&\fBRAND_set0_public()\fR and \fBRAND_set0_private()\fR return 1 on success and 0 +on error. +.SH NOTES +.IX Header "NOTES" +It is not thread\-safe to access the \fIprimary\fR DRBG instance. +The \fIpublic\fR and \fIprivate\fR DRBG instance can be accessed safely, because +they are thread\-local. Note however, that changes to these two instances +apply only to the current thread. +.PP +For that reason it is recommended not to change the settings of these +three instances directly. +Instead, an application should change the default settings for new DRBG instances +at initialization time, before creating additional threads. +.PP +During initialization, it is possible to change the reseed interval +and reseed time interval. +It is also possible to exchange the reseeding callbacks entirely. +.PP +To set the type of DRBG that will be instantiated, use the +\&\fBRAND_set_DRBG_type\fR\|(3) call before accessing the random number generation +infrastructure. +.PP +The two set functions, operate on the current thread. If you want to +use the same random number generator across all threads, each thread +must individually call the set functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +\&\fBRAND_set_DRBG_type\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBRAND_set0_public()\fR and \fBRAND_set0_private()\fR were added in OpenSSL 3.1. +.PP +The remaining functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_get_rand_method.3 b/static/netbsd/man3/RAND_get_rand_method.3 new file mode 100644 index 00000000..5fde1280 --- /dev/null +++ b/static/netbsd/man3/RAND_get_rand_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_get_rand_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_load_file.3 b/static/netbsd/man3/RAND_load_file.3 new file mode 100644 index 00000000..5a45f093 --- /dev/null +++ b/static/netbsd/man3/RAND_load_file.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: RAND_load_file.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_load_file 3" +.TH RAND_load_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_load_file, RAND_write_file, RAND_file_name \- PRNG seed file +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_load_file(const char *filename, long max_bytes); +\& +\& int RAND_write_file(const char *filename); +\& +\& const char *RAND_file_name(char *buf, size_t num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRAND_load_file()\fR reads a number of bytes from file \fBfilename\fR and +adds them to the PRNG. If \fBmax_bytes\fR is nonnegative, +up to \fBmax_bytes\fR are read; +if \fBmax_bytes\fR is \-1, the complete file is read (unless the file +is not a regular file, in that case a fixed number of bytes, +256 in the current implementation, is attempted to be read). +\&\fBRAND_load_file()\fR can read less than the complete file or the requested number +of bytes if it doesn\*(Aqt fit in the return value type. +Do not load the same file multiple times unless its contents have +been updated by \fBRAND_write_file()\fR between reads. +Also, note that \fBfilename\fR should be adequately protected so that an +attacker cannot replace or examine the contents. +If \fBfilename\fR is not a regular file, then user is considered to be +responsible for any side effects, e.g. non\-anticipated blocking or +capture of controlling terminal. +.PP +\&\fBRAND_write_file()\fR writes a number of random bytes (currently 128) to +file \fBfilename\fR which can be used to initialize the PRNG by calling +\&\fBRAND_load_file()\fR in a later session. +.PP +\&\fBRAND_file_name()\fR generates a default path for the random seed +file. \fBbuf\fR points to a buffer of size \fBnum\fR in which to store the +filename. +.PP +On all systems, if the environment variable \fBRANDFILE\fR is set, its +value will be used as the seed filename. +Otherwise, the file is called \f(CW\*(C`.rnd\*(C'\fR, found in platform dependent locations: +.IP "On Windows (in order of preference)" 4 +.IX Item "On Windows (in order of preference)" +.Vb 1 +\& %HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\e +.Ve +.IP "On VMS" 4 +.IX Item "On VMS" +.Vb 1 +\& SYS$LOGIN: +.Ve +.IP "On all other systems" 4 +.IX Item "On all other systems" +.Vb 1 +\& $HOME +.Ve +.PP +If \f(CW$HOME\fR (on non\-Windows and non\-VMS system) is not set either, or +\&\fBnum\fR is too small for the pathname, an error occurs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_load_file()\fR returns the number of bytes read or \-1 on error. +.PP +\&\fBRAND_write_file()\fR returns the number of bytes written, or \-1 if the +bytes written were generated without appropriate seeding. +.PP +\&\fBRAND_file_name()\fR returns a pointer to \fBbuf\fR on success, and NULL on +error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_add\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_pseudo_bytes.3 b/static/netbsd/man3/RAND_pseudo_bytes.3 new file mode 100644 index 00000000..9895a0f0 --- /dev/null +++ b/static/netbsd/man3/RAND_pseudo_bytes.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_pseudo_bytes.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_seed.3 b/static/netbsd/man3/RAND_seed.3 new file mode 100644 index 00000000..673e695e --- /dev/null +++ b/static/netbsd/man3/RAND_seed.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_seed.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_set_DRBG_type.3 b/static/netbsd/man3/RAND_set_DRBG_type.3 new file mode 100644 index 00000000..4ad868d6 --- /dev/null +++ b/static/netbsd/man3/RAND_set_DRBG_type.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: RAND_set_DRBG_type.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_set_DRBG_type 3" +.TH RAND_set_DRBG_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_set_DRBG_type, +RAND_set_seed_source_type +\&\- specify the global random number generator types +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RAND_set_DRBG_type(OSSL_LIB_CTX *ctx, const char *drbg, const char *propq, +\& const char *cipher, const char *digest); +\& int RAND_set_seed_source_type(OSSL_LIB_CTX *ctx, const char *seed, +\& const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRAND_set_DRBG_type()\fR specifies the random bit generator that will be +used within the library context \fIctx\fR. A generator of name \fIdrbg\fR +with properties \fIpropq\fR will be fetched. It will be instantiated with +either \fIcipher\fR or \fIdigest\fR as its underlying cryptographic algorithm. +This specifies the type that will be used for the primary, public and +private random instances. +.PP +\&\fBRAND_set_seed_source_type()\fR specifies the seed source that will be used +within the library context \fIctx\fR. The seed source of name \fIseed\fR +with properties \fIpropq\fR will be fetched and used to seed the primary +random bit generator. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These function return 1 on success and 0 on failure. +.SH NOTES +.IX Header "NOTES" +These functions must be called before the random bit generators are first +created in the library context. They will return an error if the call +is made too late. +.PP +The default DRBG is "CTR\-DRBG" using the "AES\-256\-CTR" cipher. +.PP +The default seed source can be configured when OpenSSL is compiled by +setting \fB\-DOPENSSL_DEFAULT_SEED_SRC=SEED\-SRC\fR. If not set then +"SEED\-SRC" is used. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 3 +\& unsigned char bytes[100]; +\& RAND_set_seed_source_type(NULL, "JITTER", NULL); +\& RAND_bytes(bytes, 100); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +\&\fBRAND_get0_primary\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_set_rand_engine.3 b/static/netbsd/man3/RAND_set_rand_engine.3 new file mode 100644 index 00000000..ac29a730 --- /dev/null +++ b/static/netbsd/man3/RAND_set_rand_engine.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_set_rand_engine.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_set_rand_method.3 b/static/netbsd/man3/RAND_set_rand_method.3 new file mode 100644 index 00000000..52010830 --- /dev/null +++ b/static/netbsd/man3/RAND_set_rand_method.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: RAND_set_rand_method.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RAND_set_rand_method 3" +.TH RAND_set_rand_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL \- select RAND method +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& RAND_METHOD *RAND_OpenSSL(void); +\& +\& int RAND_set_rand_method(const RAND_METHOD *meth); +\& +\& const RAND_METHOD *RAND_get_rand_method(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBRAND_set_DRBG_type\fR\|(3), +\&\fBEVP_RAND\fR\|(3) and \fBEVP_RAND\fR\|(7). +.PP +A \fBRAND_METHOD\fR specifies the functions that OpenSSL uses for random number +generation. +.PP +\&\fBRAND_OpenSSL()\fR returns the default \fBRAND_METHOD\fR implementation by OpenSSL. +This implementation ensures that the PRNG state is unique for each thread. +.PP +If an \fBENGINE\fR is loaded that provides the RAND API, however, it will +be used instead of the method returned by \fBRAND_OpenSSL()\fR. This is deprecated +in OpenSSL 3.0. +.PP +\&\fBRAND_set_rand_method()\fR makes \fBmeth\fR the method for PRNG use. If an +ENGINE was providing the method, it will be released first. +.PP +\&\fBRAND_get_rand_method()\fR returns a pointer to the current \fBRAND_METHOD\fR. +.SH "THE RAND_METHOD STRUCTURE" +.IX Header "THE RAND_METHOD STRUCTURE" +.Vb 8 +\& typedef struct rand_meth_st { +\& int (*seed)(const void *buf, int num); +\& int (*bytes)(unsigned char *buf, int num); +\& void (*cleanup)(void); +\& int (*add)(const void *buf, int num, double entropy); +\& int (*pseudorand)(unsigned char *buf, int num); +\& int (*status)(void); +\& } RAND_METHOD; +.Ve +.PP +The fields point to functions that are used by, in order, +\&\fBRAND_seed()\fR, \fBRAND_bytes()\fR, internal RAND cleanup, \fBRAND_add()\fR, \fBRAND_pseudo_rand()\fR +and \fBRAND_status()\fR. +Each pointer may be NULL if the function is not implemented. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_set_rand_method()\fR returns 1 on success and 0 on failure. +\&\fBRAND_get_rand_method()\fR and \fBRAND_OpenSSL()\fR return pointers to the respective +methods. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_RAND\fR\|(3), +\&\fBRAND_set_DRBG_type\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBENGINE_by_id\fR\|(3), +\&\fBEVP_RAND\fR\|(7), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RAND_status.3 b/static/netbsd/man3/RAND_status.3 new file mode 100644 index 00000000..bdb21d0d --- /dev/null +++ b/static/netbsd/man3/RAND_status.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_status.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RAND_write_file.3 b/static/netbsd/man3/RAND_write_file.3 new file mode 100644 index 00000000..f83504f2 --- /dev/null +++ b/static/netbsd/man3/RAND_write_file.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RAND_write_file.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rand.3 diff --git a/static/netbsd/man3/RC4_set_key.3 b/static/netbsd/man3/RC4_set_key.3 new file mode 100644 index 00000000..31516cca --- /dev/null +++ b/static/netbsd/man3/RC4_set_key.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: RC4_set_key.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RC4_set_key 3" +.TH RC4_set_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RC4_set_key, RC4 \- RC4 encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); +\& +\& void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, +\& unsigned char *outdata); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. Applications should +instead use \fBEVP_EncryptInit_ex\fR\|(3), \fBEVP_EncryptUpdate\fR\|(3) and +\&\fBEVP_EncryptFinal_ex\fR\|(3) or the equivalently named decrypt functions. +.PP +This library implements the Alleged RC4 cipher, which is described for +example in \fIApplied Cryptography\fR. It is believed to be compatible +with RC4[TM], a proprietary cipher of RSA Security Inc. +.PP +RC4 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. +.PP +RC4 consists of a key setup phase and the actual encryption or +decryption phase. +.PP +\&\fBRC4_set_key()\fR sets up the \fBRC4_KEY\fR \fBkey\fR using the \fBlen\fR bytes long +key at \fBdata\fR. +.PP +\&\fBRC4()\fR encrypts or decrypts the \fBlen\fR bytes of data at \fBindata\fR using +\&\fBkey\fR and places the result at \fBoutdata\fR. Repeated \fBRC4()\fR calls with +the same \fBkey\fR yield a continuous key stream. +.PP +Since RC4 is a stream cipher (the input is XORed with a pseudo\-random +key stream to produce the output), decryption uses the same function +calls as encryption. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRC4_set_key()\fR and \fBRC4()\fR do not return values. +.SH NOTE +.IX Header "NOTE" +Applications should use the higher level functions +\&\fBEVP_EncryptInit\fR\|(3) etc. instead of calling these +functions directly. +.PP +It is difficult to securely use stream ciphers. For example, do not perform +multiple encryptions using the same key stream. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RELEASE_NOTES-2.3 b/static/netbsd/man3/RELEASE_NOTES-2.3 new file mode 100644 index 00000000..a1ac8c04 --- /dev/null +++ b/static/netbsd/man3/RELEASE_NOTES-2.3 @@ -0,0 +1,761 @@ +The stable Postfix release is called postfix-2.3.x where 2=major +release number, 3=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-2.4-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +Critical notes +-------------- + +See RELEASE_NOTES_2.2 if you upgrade from Postfix 2.1 or earlier. + +Some Postfix internal protocols have changed. You need to "postfix +reload" or restart Postfix, otherwise many servers will log warning +messages like "unexpected attribute xxx" or "problem talking to +service yyy", and mail will not be delivered. + +The Sendmail-compatible Milter support introduces three new queue +file record types. As long as you leave this feature turned off, +you can still go back to Postfix version 2.2 without losing mail +that was received by Postfix 2.3. + +Major changes - DNS lookups +--------------------------- + +[Incompat 20050726] Name server replies that contain a malformed +hostname are now flagged as permanent errors instead of transient +errors. This change works around a questionable proposal to use +syntactically invalid hostnames in MX records. + +Major changes - DSN +------------------- + +[Feature 20050615] DSN support as described in RFC 3461 .. RFC 3464. +This gives senders control over successful and failed delivery +notifications. DSN involves extra parameters to the SMTP "MAIL +FROM" and "RCPT TO" commands, as well as extra Postfix sendmail +command line options for mail submission. + +See DSN_README for details. Some implementation notes can be found +in implementation-notes/DSN. + +[Incompat 20050615] The new DSN support conflicts with VERP support. +For Sendmail compatibility, Postfix now uses the sendmail -V command +line option for DSN. To request VERP style delivery, you must now +specify -XV instead of -V. The Postfix sendmail command will +recognize if you try to use -V for VERP-style delivery. It will +usually do the right thing, and remind you of the new syntax. + +[Incompat 20050828] Postfix no longer sends DSN SUCCESS notification +after virtual alias expansions when the cleanup server rejects the +content or size of mail that was submitted with the Postfix sendmail +command, mail that was forwarded with the local(8) delivery agent, +or mail that was re-queued with "postsuper -r". Since all the +recipients are reported as failed, the SUCCESS notification seems +redundant. + +Major changes - LMTP client +--------------------------- + +See the "SASL authentication" and "TLS" sections for changes related +to SASL authentication and TLS support, respectively. + +[Feature 20051208] The SMTP client now implements the LMTP protocol. +Most but not all smtp_xxx parameters now have an lmtp_xxx equivalent. +This means there are lot of new LMTP features, including support +for TLS and for the shared connection cache. See the "SMTP client" +section for details. + +[Incompat 20051208] The LMTP client now reports the server as +"myhostname[/path/name]". With the real server hostname in delivery +status reports, the information will be more useful. + +Major changes - Milter support +------------------------------ + +[Feature 20060515] Milter (mail filter) application support, +compatible with Sendmail version 8.13.6 and earlier. This allows +you to run a large number of plug-ins to reject unwanted mail, and +to sign mail with for example domain keys. All Milter functions are +implemented except replacing the message body, which will be added +later. Milters are before-queue filters, so they don't change the +queue ID. + +See the MILTER_README document for a discussion of how to use Milter +support with Postfix, and limitations of the current implementation. + +The Sendmail-compatible Milter support introduces three new queue +file record types. As long as you leave this feature turned off, +you can still go back to Postfix version 2.2 without losing mail +that was received by Postfix 2.3. + +[Incompat 20060515] Milter support introduces new logfile event +types: milter-reject, milter-discard and milter-hold, that identify +actions from Milter applications. This may affect logfile processing +software. + +Major changes - SASL authentication +----------------------------------- + +[Feature 20051220] Plug-in support for SASL authentication in the +SMTP server and in the SMTP/LMTP client. With this, Postfix can +support multiple SASL implementations without source code patches. +Some distributors may even make SASL support a run-time linking +option, just like they already do with Postfix lookup tables. + +Hints and tips for plug-in developers are in the xsasl/README file. + +For backwards compatibility the default plug-in type is Cyrus SASL, +so everything should behave like it did before. Some error messages +are slightly different, but these are generally improvements. + +The "postconf -a" command shows what plug-in implementations are +available for the SMTP server, and "postconf -A" does the same for +the SMTP/LMTP client. Plug-in implementations are selected with +the smtpd_sasl_type, smtp_sasl_type and lmtp_sasl_type configuration +parameters. + +Other new configuration parameters are smtpd_sasl_path, smtp_sasl_path +and lmtp_sasl_path. These are better left alone; they are introduced +for the convenience of other SASL implementations. + +[Feature 20051222] Dovecot SASL support (SMTP server only). Details +can be found in the SASL_README document. + +[Incompat 20051220] The Postfix-with-Cyrus-SASL build procedure has +changed. You now need to specify -DUSE_CYRUS_SASL in addition to +-DUSE_SASL_AUTH or else you end up without any Cyrus SASL support. +The error messages are: + + unsupported SASL server implementation: cyrus + unsupported SASL client implementation: cyrus + +[Feature 20051125] This snapshot adds support for sender-dependent +ISP accounts. + +- Sender-dependent smarthost lookup tables. The maps are searched + with the sender address and with the sender @domain. The result + overrides the global relayhost setting, but otherwise has identical + behavior. See the postconf(5) manual page for more details. + + Example: + /etc/postfix/main.cf: + sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay + +- Sender-dependent SASL authentication support. This disables SMTP + connection caching to ensure that mail from different senders + will use the correct authentication credentials. The SMTP SASL + password file is first searched by sender address, and then by + the remote domain and hostname as usual. + + Example: + /etc/postfix/main.cf: + smtp_sasl_auth_enable = yes + smtp_sender_dependent_authentication = yes + smtp_sasl_password_maps = hash:/etc/postfix/sasl_pass + +[Incompat 20060707] The SMTP/LMTP client now defers delivery when +a SASL password exists but the server does not announce support for +SASL authentication. This can happen with servers that announce +SASL support only when TLS is turned on. When an opportunistic TLS +handshake fails, Postfix >= 2.3 retries delivery in plaintext, and +the remote server rejects mail from the unauthenticated client. +Specify "smtp_sasl_auth_enforce = no" to deliver mail anyway. + +Major changes - SMTP client +--------------------------- + +See the "SASL authentication" and "TLS" sections for changes related +to SASL authentication and TLS support, respectively. + +[Feature 20051208] The SMTP client now implements the LMTP protocol. +Most but not all smtp_xxx parameters now have an lmtp_xxx equivalent. +This means there are lot of new LMTP features, including support +for TLS and for the shared connection cache. + +[Incompat 20060112] The Postfix SMTP/LMTP client by default no +longer allows DNS CNAME records to override the server hostname +that is used for logging, SASL password lookup, TLS policy selection +and TLS server certificate verification. Specify +"smtp_cname_overrides_servername = yes" to get the old behavior. + +[Incompat 20060103] The Postfix SMTP/LMTP client no longer defers +mail delivery when it receives a malformed SMTP server reply in a +session with command pipelining. When helpful warnings are enabled, +it will suggest that command pipelining be disabled for the affected +destination. + +[Incompat 20051208] The fallback_relay feature is renamed to +smtp_fallback_relay, to make clear that the combined SMTP/LMTP +client uses this setting only for SMTP deliveries. The old name +still works. + +[Incompat 20051106] The relay=... logging has changed and now +includes the remote SMTP server port number as hostname[hostaddr]:port. + +[Incompat 20051026] The smtp_connection_cache_reuse_limit parameter +(which limits the number of deliveries per SMTP connection) is +replaced by the new smtp_connection_reuse_time_limit parameter (the +time after which a connection is no longer stored into the connection +cache). + +[Feature 20051026] This snapshot addresses a performance stability +problem with remote SMTP servers. The problem is not specific to +Postfix: it can happen when any MTA sends large amounts of SMTP +email to a site that has multiple MX hosts. The insight that led +to the solution, as well as an initial implementation, are due to +Victor Duchovni. + +The problem starts when one of a set of MX hosts becomes slower +than the rest. Even though SMTP clients connect to fast and slow +MX hosts with equal probability, the slow MX host ends up with more +simultaneous inbound connections than the faster MX hosts, because +the slow MX host needs more time to serve each client request. + +The slow MX host becomes a connection attractor. If one MX host +becomes N times slower than the rest, it dominates mail delivery +latency unless there are more than N fast MX hosts to counter the +effect. And if the number of MX hosts is smaller than N, the mail +delivery latency becomes effectively that of the slowest MX host +divided by the total number of MX hosts. + +The solution uses connection caching in a way that differs from +Postfix 2.2. By limiting the amount of time during which a connection +can be used repeatedly (instead of limiting the number of deliveries +over that connection), Postfix not only restores fairness in the +distribution of simultaneous connections across a set of MX hosts, +it also favors deliveries over connections that perform well, which +is exactly what we want. + +The smtp_connection_reuse_time_limit feature implements the connection +reuse time limit as discussed above. It limits the amount of time +after which an SMTP connection is no longer stored into the connection +cache. The default limit, 300s, can result in a huge number of +deliveries over a single connection. + +This solution will be complete when Postfix logging is updated to +include information about the number of times that a connection was +used. This information is needed to diagnose inter-operability +problems with servers that exhibit bugs when they receive multiple +messages over the same connection. + +[Incompat 20050627] The Postfix SMTP client no longer applies the +smtp_mx_session_limit to non-permanent errors during the TCP, SMTP, +HELO or TLS handshake. Previous versions did that only with TCP +and SMTP handshake errors. + +[Incompat 20050622] The Postfix SMTP client by default limits the +number of MX server addresses to smtp_mx_address_limit=5. Previously +this limit was disabled by default. The new limit prevents Postfix +from spending lots of time trying to connect to lots of bogus MX +servers. + +Major changes - SMTP server +--------------------------- + +See the "SASL authentication" and "TLS" sections for changes related +to SASL authentication and TLS support, respectively. + +[Feature 20051222] To accept the non-compliant user@ipaddress form, +specify "resolve_numeric_domain = yes". Postfix will deliver the +mail to user@[ipaddress] instead. + +[Incompat 20051202] The Postfix SMTP server now refuses to receive +mail from the network if it isn't running with postfix mail_owner +privileges. This prevents surprises when, for example, "sendmail +-bs" is configured to run as root from xinetd. + +[Incompat 20051121] Although the permit_mx_backup feature still +accepts mail for authorized destinations (see permit_mx_backup for +definition), with all other destinations it now requires that the +local MTA is listed as non-primary MX server. This prevents mail +loop problems when someone points their primary MX record at a +Postfix system. + +[Feature 20051011] Optional suppression of remote SMTP client +hostname lookup and hostname verification. Specify "smtpd_peername_lookup += no" to eliminate DNS lookup latencies, but do so only under extreme +conditions, as it makes Postfix logging less informative. + +[Feature 20050724] SMTPD Access control based on the existence of +an address->name mapping, with reject_unknown_reverse_client_hostname. +There is no corresponding access table lookup feature, because the +name is not validated in any way (except that it has proper syntax). + +Several confusing SMTPD access restrictions were renamed: + + reject_unknown_client -> reject_unknown_client_hostname, + reject_unknown_hostname -> reject_unknown_helo_hostname, + reject_invalid_hostname -> reject_invalid_helo_hostname, + reject_non_fqdn_hostname -> reject_non_fqdn_helo_hostname. + +The old names are still recognized and documented. + +Major changes - TLS +------------------- + +Major revisions were made to Postfix TLS support; see TLS_README +for the details. For backwards compatibility, the old TLS policy +user interface will be kept intact for a few releases so that sites +can upgrade Postfix without being forced to use a different TLS +policy mechanism. + +[Feature 20060614] New concept: TLS security levels ("none", "may", +"encrypt", "verify" or "secure") in the Postfix SMTP client. You +can specify the TLS security level via the smtp_tls_security_level +parameter. This is more convenient than controlling TLS with the +multiple smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername, +parameters. + +[Feature 20060709] TLS security levels ("none", "may", "encrypt") +in the Postfix SMTP server. You specify the security level with the +smtpd_tls_security_level parameter. This overrides the multiple +smtpd_use_tls and smtpd_enforce_tls parameters. When one of the +unimplemented "verify" or "secure" levels is specified, the Postfix +SMTP server logs a warning and uses "encrypt" instead. + +[Feature 20060123] A new per-site TLS policy mechanism for the +Postfix SMTP client that supports the new TLS security levels, +and that eliminates DNS spoofing attacks more effectively. + +[Feature 20060626] Both the Postfix SMTP client and server can be +configured without a client or server certificate. An SMTP server +without certificate can use only anonymous ciphers, and will not +inter-operate with most clients. + +The Postfix SMTP server supports anonymous ciphers when 1) no client +certificates are requested or required, and 2) the administrator +has not excluded the "aNULL" OpenSSL cipher type with the +smtpd_tls_exclude_ciphers parameter. + +The Postfix SMTP client supports anonymous ciphers when 1) no server +certificate is required and 2) the administrator has not excluded +the "aNULL" OpenSSL cipher type with the smtp_tls_exclude_ciphers +parameter. + +[Incompat 20060707] The SMTPD policy client now encodes the +ccert_subject and ccert_issuer attributes as xtext. Some characters +are represented by +XX, where XX is the two-digit hexadecimal +representation of the character value. + +[Feature 20060614] The smtpd_tls_protocols parameter restricts the +list of TLS protocols supported by the SMTP server. This is +recommended for use with MSA configurations only. It should not +be used with MX hosts that receive mail from the Internet, as it +reduces inter-operability. + +[Incompat 20060614] The smtp_tls_cipherlist parameter only applies +when TLS is mandatory. It is ignored with opportunistic TLS sessions. + +[Incompat 20060614] At (lmtp|smtp|smtpd)_tls_loglevel >= 2, Postfix +now also logs TLS session cache activity. Use level 2 and higher +for debugging only; use levels 0 or 1 as production settings. + +[Incompat 20060207] The Postfix SMTP server no longer complains +when TLS support is not compiled in while permit_tls_clientcerts, +permit_tls_all_clientcerts, or check_ccert_access are specified in +main.cf. These features now are effectively ignored. However, the +reject_plaintext_session feature is not ignored and will reject +plain-text mail. + +[Feature 20060123] Some obscure behavior was eliminated from the +smtp_tls_per_site feature, without changes to the user interface. +Some Postfix internals had to be re-structured for the new TLS +policy mechanism; for this, smtp_tls_per_site had to be re-implemented. +The obscure behavior was found during compatibility testing. + +[Feature 20051011] Optional protection against SMTP clients that +hammer the server with too many new (i.e. uncached) SMTP-over-TLS +sessions. Cached sessions are much less expensive in terms of CPU +cycles. Use the smtpd_client_new_tls_session_rate_limit parameter +to specify a limit that is at least the inbound client concurrency +limit, or else you may deny legitimate service requests. + +Major changes - VERP +-------------------- + +[Incompat 20050615] The new DSN support conflicts with VERP support. +For Sendmail compatibility, Postfix now uses the sendmail -V command +line option for DSN. In order to request VERP style delivery, you +must now specify -XV instead of -V. The Postfix sendmail command +will recognize if you try to use -V for VERP-style delivery. It +will do the right thing and will remind you of the new syntax. + +Major changes - XCLIENT and XFORWARD +------------------------------------ + +[Incompat 20060611] The SMTP server XCLIENT implementation has +changed. The SMTP server now resets state to the initial server +greeting stage, immediately before the EHLO/HELO greeting. This +was needed to correctly simulate the effect of connection-level +access restrictions. Without this change, XCLIENT would not work +at all with Milter applications. + +[Incompat 20060611] The SMTP server XCLIENT and XFORWARD commands +now expect that attributes are xtext encoded (RFC 1891). For backwards +compatibility they will also accept unencoded attribute values. The +XFORWARD client code in the SMTP client and in the SMTPD_PROXY +client now always encode attribute values. This change will have a +visible effect only for malformed hostname and helo parameter values. + +For more details, see the XCLIENT_README and XFORWARD_README +documents. + +Major changes - address manipulation +------------------------------------ + +[Incompat 20060123] Postfix now preserves uppercase information +while mapping addresses with canonical, virtual, relocated or generic +maps; this happens even with $number substitutions in regular +expression maps. However, the local(8) and virtual(8) delivery +agents still fold addresses to lower case. + +As a side effect, Postfix now also does a better job at being case +insensitive where it should be, for example while searching per-host +TLS policies or SASL passwords. + +By default, Postfix now folds the search string to lowercase only +with tables that have fixed-case lookup fields such as btree:, +hash:, dbm:, ldap:, or *sql:. The search string is no longer case +folded with tables whose lookup fields can match both upper or lower +case, such as regexp:, pcre:, or cidr:. + +For safety reasons, Postfix no longer allows $number substitution +in regexp: or pcre: transport tables or per-sender relayhost tables. + +Major changes - bounce message templates +---------------------------------------- + +[Feature 20051113] Configurable bounce messages, based on a format +that was developed by Nicolas Riendeau. The file with templates is +specified with the bounce_template_file parameter. Details are in +the bounce(5) manual page, and examples of the built-in templates +can be found in $config_directory/bounce.cf.default. The template +for the default bounce message looks like this: + + failure_template = < + + If you do so, please include this problem report. You can + delete your own text from the attached returned message. + + The $mail_name program + EOF + +Major changes - built-in filters +-------------------------------- + +[Feature 20050828] Configurable filters to reject or remove unwanted +characters in email content. The message_reject_characters and +message_strip_characters parameters understand the usual C-like +escape sequences: \a \b \f \n \r \t \v \ddd (up to three octal +digits) and \\. + +[Incompat 20050828] When a header/body_checks rule or when +message_reject_characters rejects mail that was submitted with the +Postfix sendmail command (or re-queued with "postsuper -r"), the +returned message is now limited to just the message headers, to +avoid the risk of exposure to harmful content in the message body +or attachments. + +Major changes - database support +-------------------------------- + +[Incompat 20060611] The PostgreSQL client was updated after the +PostgreSQL developers made major database API changes in response +to SQL injection problems. This breaks support for PGSQL versions +prior to 8.1.4, 8.0.8, 7.4.13, and 7.3.15. Support for these requires +major code changes which are not possible in the time that is left +for completing the Postfix 2.3 stable release. + +Major changes - enhanced status codes +------------------------------------- + +[Feature 20050328] This release introduces support for RFC 3463 +enhanced status codes. For example, status code 5.1.1 means +"recipient unknown". Postfix recognizes enhanced status codes in +remote server replies, generates enhanced status codes while handling +email, and reports enhanced status codes in non-delivery notifications. +This improves the user experience with mail clients that translate +enhanced status codes into text in the user's own language. + +You can, but don't have to, specify RFC 3463 enhanced status codes +in the output from commands that receive mail from a pipe. If a +command terminates with non-zero exit status, and an enhanced status +code is present at the beginning of the command output, then that +status code takes precedence over the non-zero exit status. + +You can, but don't have to, specify RFC 3463 enhanced status codes +in Postfix access maps, header/body_checks REJECT actions, or in +RBL replies. For example: + + REJECT 5.7.1 You can't go here from there + +The status 5.7.1 means "no authorization, message refused", and is +the default for access maps, header/body_checks REJECT actions, and +for RBL replies. + +[Feature 20050328] If you specify your own enhanced status code, +the Postfix SMTP server will automatically change a leading '5' +digit (hard error) into '4' where appropriate. This is needed, for +example, with soft_bounce=yes. + +[Feature 20050510] This release improves usability of enhanced +status codes in Postfix access tables, RBL reply templates and in +transport maps that use the error(8) delivery agent. + +- When the SMTP server rejects a sender address, it transforms a + recipient DSN status (e.g., 4.1.1-4.1.6) into the corresponding + sender DSN status, and vice versa. + +- When the SMTP server rejects non-address information (such as the + HELO command parameter or the client hostname/address), it + transforms a sender or recipient DSN status into a generic + non-address DSN status (e.g., 4.0.0). + +These transformations are needed when the same access table or RBL +reply template are used for client, helo, sender, or recipient +restrictions; or when the same error(8) mailer information is used +for both senders and recipients. + +Major changes - local alias expansion +------------------------------------- + +[Incompat 20051011] The Postfix local(8) delivery agent no longer +updates its idea of the Delivered-To: address while it expands +aliases or .forward files. With deeply nested aliases or .forward +files, this can greatly reduce the number of queue files and cleanup +process instances. To get the earlier behavior, specify +"frozen_delivered_to = no". + +The frozen_delivered_to feature can help to alleviate a long-standing +problem with multiple deliveries to recipients that are listed +multiple times in a hierarchy of nested aliases. For this to work, +only the top-level alias should have an owner- alias, and none of +the subordinate aliases. + +Major changes - logging +----------------------- + +[Incompat 20060515] Milter support introduces new logfile event +types: milter-reject, milter-discard and milter-hold, that identify +actions from Milter applications. This may affect logfile processing +software. + +[Incompat 20051106] The relay=... logging has changed and now +includes the remote SMTP server port number as hostname[hostaddr]:port. + +[Incompat 20060112] The Postfix SMTP/LMTP client by default no +longer allows DNS CNAME records to override the server hostname +that is used for logging, SASL password lookup, TLS policy selection +and TLS server certificate verification. Specify +"smtp_cname_overrides_servername = yes" to get the old behavior. + +[Incompat 20051105] All delay logging now has sub-second resolution, +including the over-all "delay=nnn" logging. A patch is available +for pflogsumm (pflogsumm-conn-delays-dsn-patch). The qshape script +has been updated (auxiliary/qshape/qshape.pl). + +[Feature 20051103] This release makes a beginning with a series of +new attributes in Postfix logfile records. + +- Better insight into the nature of performance bottle necks, with + detailed logging of delays in various stages of message delivery. + Postfix logs additional delay information as "delays=a/b/c/d" + where a=time before queue manager, including message transmission; + b=time in queue manager; c=connection setup time including DNS, + HELO and TLS; d=message transmission time. + +- Logging of the connection reuse count when SMTP connections are + used for more than one message delivery. This information is + needed because Postfix can now reuse connections hundreds of times + or more. Logging of the connection reuse count can help to diagnose + inter-operability problems with servers that suffer from memory + leaks or other resource leaks. + +At this point the Postfix logging for a recipient looks like this: + + Nov 3 16:04:31 myname postfix/smtp[30840]: 19B6B2900FE: + to=, orig_to=, + relay=mail.example.com[1.2.3.4], conn_use=2, delay=0, + delays=0/0.01/0.05/0.1, dsn=2.0.0, status=sent (250 2.0.0 Ok) + +The following two logfile fields may or may not be present: + + orig_to This is omitted when the address did not change. + conn_use This is omitted when a connection is used once. + +[Incompat 20050503] The format of some "warning:" messages in the +maillog has changed so that they are easier to sort: + +- The logging now talks about "access table", instead of using three + different expressions "access table", "access map" and "SMTPD + access map" for the same thing. + +- "non-SMTP command" is now logged BEFORE the client name/address + and the offending client input, instead of at the end. + +[Incompat 20050328] The logging format has changed. Postfix delivery +agents now log the RFC 3463 enhanced status code as "dsn=x.y.z" +where y and z can be up to three digits each. + +[Incompat 20051208] The LMTP client now reports the server as +"myhostname[/path/name]". With the real server hostname in delivery +status reports, the information will be more useful. + +Major changes - performance +--------------------------- + +[Incompat 20051105] All delay logging now has sub-second resolution, +including the over-all "delay=nnn" logging. A patch is available +for pflogsumm (pflogsumm-conn-delays-dsn-patch). The qshape script +has been updated (auxiliary/qshape/qshape.pl). + +[Incompat 20050622] The Postfix SMTP client by default limits the +number of MX server addresses to smtp_mx_address_limit=5. Previously +this limit was disabled by default. The new limit prevents Postfix +from spending lots of time trying to connect to lots of bogus MX +servers. + +[Feature 20051026] This snapshot addresses a performance stability +problem with remote SMTP servers. The problem is not specific to +Postfix: it can happen when any MTA sends large amounts of SMTP +email to a site that has multiple MX hosts. The insight that led +to the solution, as well as an initial implementation, are due to +Victor Duchovni. + +The problem starts when one of a set of MX hosts becomes slower +than the rest. Even though SMTP clients connect to fast and slow +MX hosts with equal probability, the slow MX host ends up with more +simultaneous inbound connections than the faster MX hosts, because +the slow MX host needs more time to serve each client request. + +The slow MX host becomes a connection attractor. If one MX host +becomes N times slower than the rest, it dominates mail delivery +latency unless there are more than N fast MX hosts to counter the +effect. And if the number of MX hosts is smaller than N, the mail +delivery latency becomes effectively that of the slowest MX host +divided by the total number of MX hosts. + +The solution uses connection caching in a way that differs from +Postfix 2.2. By limiting the amount of time during which a connection +can be used repeatedly (instead of limiting the number of deliveries +over that connection), Postfix not only restores fairness in the +distribution of simultaneous connections across a set of MX hosts, +it also favors deliveries over connections that perform well, which +is exactly what we want. + +The smtp_connection_reuse_time_limit feature implements the connection +reuse time limit as discussed above. It limits the amount of time +after which an SMTP connection is no longer stored into the connection +cache. The default limit, 300s, can result in a huge number of +deliveries over a single connection. + +This solution will be complete when Postfix logging is updated to +include information about the number of times that a connection was +used. This information is needed to diagnose inter-operability +problems with servers that exhibit bugs when they receive multiple +messages over the same connection. + +[Feature 20051011] Optional protection against SMTP clients that +hammer the server with too many new (i.e. uncached) SMTP-over-TLS +sessions. Cached sessions are much less expensive in terms of CPU +cycles. Use the smtpd_client_new_tls_session_rate_limit parameter +to specify a limit that is at least the inbound client concurrency +limit, or else you may deny legitimate service requests. + +[Feature 20051011] Optional suppression of remote SMTP client +hostname lookup and hostname verification. Specify "smtpd_peername_lookup += no" to eliminate DNS lookup latencies, but do so only under extreme +conditions, as it makes Postfix logging less informative. + +Major changes - portability +--------------------------- + +[Incompat 20050716] Internal interfaces have changed; this may break +third-party patches because the types of function arguments and of +result values have changed. The types of buffer lengths and offsets +were changed from "int" or "unsigned int" (32 bit on 32-bit and +LP64 systems) to "ssize_t" or "size_t" (64 bit on LP64 systems, 32 +bit on 32-bit systems). + +This change makes no difference in Postfix behavior on 32-bit +systems. On LP64 systems, however, this change not only eliminates +some obscure portability bugs, it also eliminates unnecessary +conversions between 32/64 bit integer types, because many system +library routines take "(s)size_t" arguments or return "(s)size_t" +values. + +This change may break software on LP64 systems 1) when Postfix is +linked with pre-compiled code that was compiled with old Postfix +interface definitions and 2) when compiling Postfix source that was +modified by a third-party patch: incorrect code will be generated +when the patch passes the wrong integer argument type in contexts +that disable automatic argument type conversions. Examples of such +contexts are formatting with printf-like arguments, and invoking +functions that write Postfix request or reply attributes across +inter-process communication channels. Unfortunately, gcc reports +"(unsigned) int" versus "(s)size_t" format string argument mis-matches +only on LP64 systems. + +Major changes - safety +---------------------- + +[Incompat 20051121] Although the permit_mx_backup feature still +accepts mail for authorized destinations (see permit_mx_backup for +definition), with all other destinations it now requires that the +local MTA is listed as non-primary MX. This prevents mail loop +problems when someone points the primary MX record at a Postfix +system. + +[Incompat 20051011] The Postfix local(8) delivery agent no longer +updates its idea of the Delivered-To: address while it expands +aliases or .forward files. With deeply nested aliases or .forward +files, this can greatly reduce the number of queue files and cleanup +process instances. To get the earlier behavior, specify +"frozen_delivered_to = no". + +The frozen_delivered_to feature can help to alleviate a long-standing +problem with multiple deliveries to recipients that are listed +multiple times in a hierarchy of nested aliases. For this to work, +only the top-level alias should have an owner- alias, and none of +the subordinate aliases. + +[Incompat 20050828] When a header/body_checks rule or when +message_reject_characters rejects mail that was submitted with the +Postfix sendmail command (or re-queued with "postsuper -r"), the +returned message is now limited to just the message headers, to +avoid the risk of exposure to harmful content in the message body +or attachments. + +[Incompat 20051202] The Postfix SMTP server now refuses to receive +mail from the network if it isn't running with postfix mail_owner +privileges. This prevents surprises when, for example, "sendmail +-bs" is configured to run as root from xinetd. + +[Incompat 20060123] For safety reasons, Postfix no longer allows +$number substitution in regexp: or pcre: transport tables or +per-sender relayhost tables. + +[Incompat 20060112] The Postfix SMTP/LMTP client by default no +longer allows DNS CNAME records to override the server hostname +that is used for logging, SASL password lookup, TLS policy selection +and TLS server certificate verification. Specify +"smtp_cname_overrides_servername = yes" to get the old behavior. diff --git a/static/netbsd/man3/RELEASE_NOTES-3.3 b/static/netbsd/man3/RELEASE_NOTES-3.3 new file mode 100644 index 00000000..e3762d8d --- /dev/null +++ b/static/netbsd/man3/RELEASE_NOTES-3.3 @@ -0,0 +1,124 @@ +This is the Postfix 3.3 (stable) release. + +The stable Postfix release is called postfix-3.3.x where 3=major +release number, 3=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-3.4-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +If you upgrade from Postfix 3.1 or earlier, read RELEASE_NOTES-3.2 +before proceeding. + +License change +--------------- + +This software is distributed with a dual license: in addition to the +historical IBM Public License 1.0, it is now also distributed with the +more recent Eclipse Public License 2.0. Recipients can choose to take +the software under the license of their choice. Those who are more +comfortable with the IPL can continue with that license. + +Major changes - compatibility safety net +---------------------------------------- + +[20180106] With compatibility_level < 1, the Postfix SMTP server +now warns for mail that would be blocked by the Postfix 2.10 +smtpd_relay_restrictions feature, without blocking that mail. This +extends the compatibility safety net for sites that upgrade from +earlier Postfix versions (questions on the postfix-users list show +there is a steady trickle). See COMPATIBILITY_README for details. + +Major changes - configuration +----------------------------- + +[20170617] The postconf command now warns about unknown parameter +names in a Postfix database configuration file. As with other unknown +parameter names, these warnings can help to find typos early. + +[20180113] New read-only service_name parameter that contains the +master.cf service name of a Postfix daemon process (it that is empty +in a non-daemon process). This can make Postfix SMTP server logging +logging distinct by setting the syslog_name in master.cf with "-o +syslog_name=postfix/$service_name" for the "submission" and "smtps" +services, and can make Postfix SMTP client distinct by setting "-o +syslog_name=postfix/$service_name" for the "relay" service. + +Major changes - container support +--------------------------------- + +[20171218] Preliminary support to run Postfix in the foreground, +with "postfix start-fg". This requires that Postfix multi-instance +support is disabled. To receive Postfix syslog information on the +container's host, mount the host's /dev/log socket inside the +container (example: "docker run -v /dev/log:/dev/log ..."), and +specify a distinct Postfix "syslog_name" prefix that identifies the +logging from the Postfix instance. Postfix does not log systemd +events. + +Major changes - database support +--------------------------------- + +[20170617] The postconf command warns about unknown parameter names +in a Postfix database configuration file. + +[20171227] The pgsql_table(5) hosts parameter now supports the +postgresql:// URI syntax. Contributed by Magosányi Ãrpád. + +Major changes - header format +----------------------------- + +[20180010] This release changes the format of 'full name' information +in Postfix-generated From: headers, when a local program such as +/bin/mail submits a message without From: header. + +Postfix-generated From: headers with 'full name' information are +now formatted as "From: name
" by default. Specify +"header_from_format = obsolete" to get the earlier form "From: +address (name)". See the postconf(5) manpage for more details. + +Major changes - invisible changes +--------------------------------- + +[20170617] Additional paranoia in the VSTRING implementation: a +null byte after the end of vstring buffers (this is a safety net +so that C-style string operations won't scribble past the end); +earlier detection of bad length and precision format string specifiers +(these are the result of programming error, as Postfix format strings +cannot be specified externally). + +Major changes - milter support +------------------------------ + +[20171223] Milter applications can now send RET and ENVID parameters +in SMFIR_CHGFROM (change envelope sender) requests. + +Major changes - mixed IPv6/IPv4 support +--------------------------------------- + +[20170505] Workaround for mail delivery problems when 1) both Postfix +IPv6 and IPv4 support are enabled, 2) some destination announces +more primary IPv6 MX addresses than primary IPv4 MX addresses, 3) +the destination is unreachable over IPv6, and 4) Postfix runs into +the smtp_mx_address_limit before it can try to deliver over IPv4. + +When both Postfix IPv6 and IPv4 support are enabled, the Postfix +SMTP client will now relax MX preferences so that it can schedule +similar numbers of IPv4 and IPv6 destination addresses. This ensures +that an IPv6 connectivity problem will not prevent mail from being +delivered over IPv4 (and vice versa). Specify "smtp_balance_inet_protocols += no" to disable this workaround. + +Major changes - xclient +----------------------- + +[20171218] The Postfix SMTP server now allows the XCLIENT command +before STARTTLS when TLS is required. This is useful for servers +that run behind a reverse proxy server such as nginx. + diff --git a/static/netbsd/man3/RIPEMD160_Init.3 b/static/netbsd/man3/RIPEMD160_Init.3 new file mode 100644 index 00000000..211e9640 --- /dev/null +++ b/static/netbsd/man3/RIPEMD160_Init.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: RIPEMD160_Init.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RIPEMD160_Init 3" +.TH RIPEMD160_Init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final \- +RIPEMD\-160 hash function +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int RIPEMD160_Init(RIPEMD160_CTX *c); +\& int RIPEMD160_Update(RIPEMD160_CTX *c, const void *data, unsigned long len); +\& int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3). +.PP +RIPEMD\-160 is a cryptographic hash function with a +160 bit output. +.PP +\&\fBRIPEMD160()\fR computes the RIPEMD\-160 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If \fBmd\fR is NULL, the digest +is placed in a static array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBRIPEMD160_Init()\fR initializes a \fBRIPEMD160_CTX\fR structure. +.PP +\&\fBRIPEMD160_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fBRIPEMD160_Final()\fR places the message digest in \fBmd\fR, which must have +space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases +the \fBRIPEMD160_CTX\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRIPEMD160()\fR returns a pointer to the hash value. +.PP +\&\fBRIPEMD160_Init()\fR, \fBRIPEMD160_Update()\fR and \fBRIPEMD160_Final()\fR return 1 for +success, 0 otherwise. +.SH NOTE +.IX Header "NOTE" +Applications should use the higher level functions +\&\fBEVP_DigestInit\fR\|(3) etc. instead of calling these +functions directly. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +ISO/IEC 10118\-3:2016 Dedicated Hash\-Function 1 (RIPEMD\-160). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_blinding_on.3 b/static/netbsd/man3/RSA_blinding_on.3 new file mode 100644 index 00000000..822b5ba2 --- /dev/null +++ b/static/netbsd/man3/RSA_blinding_on.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: RSA_blinding_on.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_blinding_on 3" +.TH RSA_blinding_on 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_blinding_on, RSA_blinding_off \- protect the RSA operation from timing attacks +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); +\& +\& void RSA_blinding_off(RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +.PP +RSA is vulnerable to timing attacks. In a setup where attackers can +measure the time of RSA decryption or signature operations, blinding +must be used to protect the RSA operation from that attack. +.PP +\&\fBRSA_blinding_on()\fR turns blinding on for key \fBrsa\fR and generates a +random blinding factor. \fBctx\fR is \fBNULL\fR or a preallocated and +initialized \fBBN_CTX\fR. +.PP +\&\fBRSA_blinding_off()\fR turns blinding off and frees the memory used for +the blinding factor. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_blinding_on()\fR returns 1 on success, and 0 if an error occurred. +.PP +\&\fBRSA_blinding_off()\fR returns no value. +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_check_key.3 b/static/netbsd/man3/RSA_check_key.3 new file mode 100644 index 00000000..e03d4de0 --- /dev/null +++ b/static/netbsd/man3/RSA_check_key.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: RSA_check_key.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_check_key 3" +.TH RSA_check_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_check_key_ex, RSA_check_key \- validate private RSA keys +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int RSA_check_key_ex(const RSA *rsa, BN_GENCB *cb); +\& +\& int RSA_check_key(const RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Both of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_public_check\fR\|(3), +\&\fBEVP_PKEY_private_check\fR\|(3) and \fBEVP_PKEY_pairwise_check\fR\|(3). +.PP +\&\fBRSA_check_key_ex()\fR function validates RSA keys. +It checks that \fBp\fR and \fBq\fR are +in fact prime, and that \fBn = p*q\fR. +.PP +It does not work on RSA public keys that have only the modulus +and public exponent elements populated. +It also checks that \fBd*e = 1 mod (p\-1*q\-1)\fR, +and that \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR are set correctly or are \fBNULL\fR. +It performs integrity checks on all +the RSA key material, so the RSA key structure must contain all the private +key data too. +Therefore, it cannot be used with any arbitrary RSA key object, +even if it is otherwise fit for regular RSA operation. +.PP +The \fBcb\fR parameter is a callback that will be invoked in the same +manner as \fBBN_is_prime_ex\fR\|(3). +.PP +\&\fBRSA_check_key()\fR is equivalent to \fBRSA_check_key_ex()\fR with a NULL \fBcb\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_check_key_ex()\fR and \fBRSA_check_key()\fR +return 1 if \fBrsa\fR is a valid RSA key, and 0 otherwise. +They return \-1 if an error occurs while checking the key. +.PP +If the key is invalid or an error occurred, the reason code can be +obtained using \fBERR_get_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +Unlike most other RSA functions, this function does \fBnot\fR work +transparently with any underlying ENGINE implementation because it uses the +key data in the RSA structure directly. An ENGINE implementation can +override the way key data is stored and handled, and can even provide +support for HSM keys \- in which case the RSA structure may contain \fBno\fR +key data at all! If the ENGINE in question is only being used for +acceleration or analysis purposes, then in all likelihood the RSA key data +is complete and untouched, but this can\*(Aqt be assumed in the general case. +.SH BUGS +.IX Header "BUGS" +A method of verifying the RSA key using opaque RSA API functions might need +to be considered. Right now \fBRSA_check_key()\fR simply uses the RSA structure +elements directly, bypassing the RSA_METHOD table altogether (and +completely violating encapsulation and object\-orientation in the process). +The best fix will probably be to introduce a "\fBcheck_key()\fR" handler to the +RSA_METHOD function table so that alternative implementations can also +provide their own verifiers. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBN_is_prime_ex\fR\|(3), +\&\fBERR_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +\&\fBRSA_check_key_ex()\fR appeared after OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_free.3 b/static/netbsd/man3/RSA_free.3 new file mode 100644 index 00000000..0d7ed475 --- /dev/null +++ b/static/netbsd/man3/RSA_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/RSA_generate_key.3 b/static/netbsd/man3/RSA_generate_key.3 new file mode 100644 index 00000000..bab8bf93 --- /dev/null +++ b/static/netbsd/man3/RSA_generate_key.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: RSA_generate_key.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_generate_key 3" +.TH RSA_generate_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_RSA_gen, +RSA_generate_key_ex, RSA_generate_key, +RSA_generate_multi_prime_key \- generate RSA key pair +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *EVP_RSA_gen(unsigned int bits); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); +\& int RSA_generate_multi_prime_key(RSA *rsa, int bits, int primes, BIGNUM *e, BN_GENCB *cb); +.Ve +.PP +The following function has been deprecated since OpenSSL 0.9.8, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& RSA *RSA_generate_key(int bits, unsigned long e, +\& void (*callback)(int, int, void *), void *cb_arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_RSA_gen()\fR generates a new RSA key pair with modulus size \fIbits\fR. +.PP +All of the functions described below are deprecated. +Applications should instead use \fBEVP_RSA_gen()\fR, \fBEVP_PKEY_Q_keygen\fR\|(3), or +\&\fBEVP_PKEY_keygen_init\fR\|(3) and \fBEVP_PKEY_keygen\fR\|(3). +.PP +\&\fBRSA_generate_key_ex()\fR generates a 2\-prime RSA key pair and stores it in the +\&\fBRSA\fR structure provided in \fIrsa\fR. +.PP +\&\fBRSA_generate_multi_prime_key()\fR generates a multi\-prime RSA key pair and stores +it in the \fBRSA\fR structure provided in \fIrsa\fR. The number of primes is given by +the \fIprimes\fR parameter. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +The modulus size will be of length \fIbits\fR, the number of primes to form the +modulus will be \fIprimes\fR, and the public exponent will be \fIe\fR. Key sizes +with \fInum\fR < 1024 should be considered insecure. The exponent is an odd +number, typically 3, 17 or 65537. +.PP +In order to maintain adequate security level, the maximum number of permitted +\&\fIprimes\fR depends on modulus bit length: +.PP +.Vb 3 +\& <1024 | >=1024 | >=4096 | >=8192 +\& \-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- +\& 2 | 3 | 4 | 5 +.Ve +.PP +A callback function may be used to provide feedback about the +progress of the key generation. If \fIcb\fR is not NULL, it +will be called as follows using the \fBBN_GENCB_call()\fR function +described on the \fBBN_generate_prime\fR\|(3) page. +.PP +\&\fBRSA_generate_key()\fR is similar to \fBRSA_generate_key_ex()\fR but +expects an old\-style callback function; see +\&\fBBN_generate_prime\fR\|(3) for information on the old\-style callback. +.IP \(bu 2 +While a random prime number is generated, it is called as +described in \fBBN_generate_prime\fR\|(3). +.IP \(bu 2 +When the n\-th randomly generated prime is rejected as not +suitable for the key, \fIBN_GENCB_call(cb, 2, n)\fR is called. +.IP \(bu 2 +When a random p has been found with p\-1 relatively prime to \fIe\fR, +it is called as \fIBN_GENCB_call(cb, 3, 0)\fR. +.PP +The process is then repeated for prime q and other primes (if any) +with \fIBN_GENCB_call(cb, 3, i)\fR where \fIi\fR indicates the i\-th prime. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBEVP_RSA_gen()\fR returns an \fIEVP_PKEY\fR or NULL on failure. +.PP +\&\fBRSA_generate_multi_prime_key()\fR returns 1 on success or 0 on error. +\&\fBRSA_generate_key_ex()\fR returns 1 on success or 0 on error. +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.PP +\&\fBRSA_generate_key()\fR returns a pointer to the RSA structure or +NULL if the key generation fails. +.SH BUGS +.IX Header "BUGS" +\&\fIBN_GENCB_call(cb, 2, x)\fR is used with two different meanings. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_Q_keygen\fR\|(3) +\&\fBBN_generate_prime\fR\|(3), \fBERR_get_error\fR\|(3), +\&\fBRAND_bytes\fR\|(3), \fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBEVP_RSA_gen()\fR was added in OpenSSL 3.0. +All other functions described here were deprecated in OpenSSL 3.0. +For replacement see \fBEVP_PKEY\-RSA\fR\|(7). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_get0_key.3 b/static/netbsd/man3/RSA_get0_key.3 new file mode 100644 index 00000000..b130e096 --- /dev/null +++ b/static/netbsd/man3/RSA_get0_key.3 @@ -0,0 +1,253 @@ +.\" $NetBSD: RSA_get0_key.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_get0_key 3" +.TH RSA_get0_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key, +RSA_get0_factors, RSA_get0_crt_params, +RSA_get0_n, RSA_get0_e, RSA_get0_d, RSA_get0_p, RSA_get0_q, +RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp, RSA_get0_pss_params, +RSA_clear_flags, +RSA_test_flags, RSA_set_flags, RSA_get0_engine, RSA_get_multi_prime_extra_count, +RSA_get0_multi_prime_factors, RSA_get0_multi_prime_crt_params, +RSA_set0_multi_prime_params, RSA_get_version +\&\- Routines for getting and setting data in an RSA object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d); +\& int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q); +\& int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp); +\& void RSA_get0_key(const RSA *r, +\& const BIGNUM **n, const BIGNUM **e, const BIGNUM **d); +\& void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q); +\& void RSA_get0_crt_params(const RSA *r, +\& const BIGNUM **dmp1, const BIGNUM **dmq1, +\& const BIGNUM **iqmp); +\& const BIGNUM *RSA_get0_n(const RSA *d); +\& const BIGNUM *RSA_get0_e(const RSA *d); +\& const BIGNUM *RSA_get0_d(const RSA *d); +\& const BIGNUM *RSA_get0_p(const RSA *d); +\& const BIGNUM *RSA_get0_q(const RSA *d); +\& const BIGNUM *RSA_get0_dmp1(const RSA *r); +\& const BIGNUM *RSA_get0_dmq1(const RSA *r); +\& const BIGNUM *RSA_get0_iqmp(const RSA *r); +\& const RSA_PSS_PARAMS *RSA_get0_pss_params(const RSA *r); +\& void RSA_clear_flags(RSA *r, int flags); +\& int RSA_test_flags(const RSA *r, int flags); +\& void RSA_set_flags(RSA *r, int flags); +\& ENGINE *RSA_get0_engine(RSA *r); +\& int RSA_get_multi_prime_extra_count(const RSA *r); +\& int RSA_get0_multi_prime_factors(const RSA *r, const BIGNUM *primes[]); +\& int RSA_get0_multi_prime_crt_params(const RSA *r, const BIGNUM *exps[], +\& const BIGNUM *coeffs[]); +\& int RSA_set0_multi_prime_params(RSA *r, BIGNUM *primes[], BIGNUM *exps[], +\& BIGNUM *coeffs[], int pnum); +\& int RSA_get_version(RSA *r); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_bn_param\fR\|(3) for any methods that +return a \fBBIGNUM\fR. Refer to \fBEVP_PKEY\-DH\fR\|(7) for more information. +.PP +An RSA object contains the components for the public and private key, +\&\fBn\fR, \fBe\fR, \fBd\fR, \fBp\fR, \fBq\fR, \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR. \fBn\fR is +the modulus common to both public and private key, \fBe\fR is the public +exponent and \fBd\fR is the private exponent. \fBp\fR, \fBq\fR, \fBdmp1\fR, +\&\fBdmq1\fR and \fBiqmp\fR are the factors for the second representation of a +private key (see PKCS#1 section 3 Key Types), where \fBp\fR and \fBq\fR are +the first and second factor of \fBn\fR and \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR +are the exponents and coefficient for CRT calculations. +.PP +For multi\-prime RSA (defined in RFC 8017), there are also one or more +\&\*(Aqtriplet\*(Aq in an RSA object. A triplet contains three members, \fBr\fR, \fBd\fR +and \fBt\fR. \fBr\fR is the additional prime besides \fBp\fR and \fBq\fR. \fBd\fR and +\&\fBt\fR are the exponent and coefficient for CRT calculations. +.PP +The \fBn\fR, \fBe\fR and \fBd\fR parameters can be obtained by calling +\&\fBRSA_get0_key()\fR. If they have not been set yet, then \fB*n\fR, \fB*e\fR and +\&\fB*d\fR will be set to NULL. Otherwise, they are set to pointers to +their respective values. These point directly to the internal +representations of the values and therefore should not be freed +by the caller. +.PP +The \fBn\fR, \fBe\fR and \fBd\fR parameter values can be set by calling +\&\fBRSA_set0_key()\fR and passing the new values for \fBn\fR, \fBe\fR and \fBd\fR as +parameters to the function. The values \fBn\fR and \fBe\fR must be non\-NULL +the first time this function is called on a given RSA object. The +value \fBd\fR may be NULL. On subsequent calls any of these values may be +NULL which means the corresponding RSA field is left untouched. +Calling this function transfers the memory management of the values to +the RSA object, and therefore the values that have been passed in +should not be freed by the caller after this function has been called. +.PP +In a similar fashion, the \fBp\fR and \fBq\fR parameters can be obtained and +set with \fBRSA_get0_factors()\fR and \fBRSA_set0_factors()\fR, and the \fBdmp1\fR, +\&\fBdmq1\fR and \fBiqmp\fR parameters can be obtained and set with +\&\fBRSA_get0_crt_params()\fR and \fBRSA_set0_crt_params()\fR. +.PP +For \fBRSA_get0_key()\fR, \fBRSA_get0_factors()\fR, and \fBRSA_get0_crt_params()\fR, +NULL value BIGNUM ** output parameters are permitted. The functions +ignore NULL parameters but return values for other, non\-NULL, parameters. +.PP +For multi\-prime RSA, \fBRSA_get0_multi_prime_factors()\fR and \fBRSA_get0_multi_prime_params()\fR +can be used to obtain other primes and related CRT parameters. The +return values are stored in an array of \fBBIGNUM *\fR. \fBRSA_set0_multi_prime_params()\fR +sets a collect of multi\-prime \*(Aqtriplet\*(Aq members (prime, exponent and coefficient) +into an RSA object. +.PP +Any of the values \fBn\fR, \fBe\fR, \fBd\fR, \fBp\fR, \fBq\fR, \fBdmp1\fR, \fBdmq1\fR, and \fBiqmp\fR can also be +retrieved separately by the corresponding function +\&\fBRSA_get0_n()\fR, \fBRSA_get0_e()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_p()\fR, \fBRSA_get0_q()\fR, +\&\fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR, and \fBRSA_get0_iqmp()\fR, respectively. +.PP +\&\fBRSA_get0_pss_params()\fR is used to retrieve the RSA\-PSS parameters. +.PP +\&\fBRSA_set_flags()\fR sets the flags in the \fBflags\fR parameter on the RSA +object. Multiple flags can be passed in one go (bitwise ORed together). +Any flags that are already set are left set. \fBRSA_test_flags()\fR tests to +see whether the flags passed in the \fBflags\fR parameter are currently +set in the RSA object. Multiple flags can be tested in one go. All +flags that are currently set are returned, or zero if none of the +flags are set. \fBRSA_clear_flags()\fR clears the specified flags within the +RSA object. +.PP +\&\fBRSA_get0_engine()\fR returns a handle to the ENGINE that has been set for +this RSA object, or NULL if no such ENGINE has been set. +.PP +\&\fBRSA_get_version()\fR returns the version of an RSA object \fBr\fR. +.SH NOTES +.IX Header "NOTES" +Values retrieved with \fBRSA_get0_key()\fR are owned by the RSA object used +in the call and may therefore \fInot\fR be passed to \fBRSA_set0_key()\fR. If +needed, duplicate the received value using \fBBN_dup()\fR and pass the +duplicate. The same applies to \fBRSA_get0_factors()\fR and \fBRSA_set0_factors()\fR +as well as \fBRSA_get0_crt_params()\fR and \fBRSA_set0_crt_params()\fR. +.PP +The caller should obtain the size by calling \fBRSA_get_multi_prime_extra_count()\fR +in advance and allocate sufficient buffer to store the return values before +calling \fBRSA_get0_multi_prime_factors()\fR and \fBRSA_get0_multi_prime_params()\fR. +.PP +\&\fBRSA_set0_multi_prime_params()\fR always clears the original multi\-prime +triplets in RSA object \fBr\fR and assign the new set of triplets into it. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_set0_key()\fR, \fBRSA_set0_factors()\fR, \fBRSA_set0_crt_params()\fR and +\&\fBRSA_set0_multi_prime_params()\fR return 1 on success or 0 on failure. +.PP +\&\fBRSA_get0_n()\fR, \fBRSA_get0_e()\fR, \fBRSA_get0_d()\fR, \fBRSA_get0_p()\fR, \fBRSA_get0_q()\fR, +\&\fBRSA_get0_dmp1()\fR, \fBRSA_get0_dmq1()\fR, and \fBRSA_get0_iqmp()\fR +return the respective value. +.PP +\&\fBRSA_get0_pss_params()\fR returns a \fBRSA_PSS_PARAMS\fR pointer, or NULL if +there is none. +.PP +\&\fBRSA_get0_multi_prime_factors()\fR and \fBRSA_get0_multi_prime_crt_params()\fR return +1 on success or 0 on failure. +.PP +\&\fBRSA_get_multi_prime_extra_count()\fR returns two less than the number of primes +in use, which is 0 for traditional RSA and the number of extra primes for +multi\-prime RSA. +.PP +\&\fBRSA_get_version()\fR returns \fBRSA_ASN1_VERSION_MULTI\fR for multi\-prime RSA and +\&\fBRSA_ASN1_VERSION_DEFAULT\fR for normal two\-prime RSA, as defined in RFC 8017. +.PP +\&\fBRSA_test_flags()\fR returns the current state of the flags in the RSA object. +.PP +\&\fBRSA_get0_engine()\fR returns the ENGINE set for the RSA object or NULL if no +ENGINE has been set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRSA_new\fR\|(3), \fBRSA_size\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBRSA_get0_pss_params()\fR function was added in OpenSSL 1.1.1e. +.PP +The +\&\fBRSA_get_multi_prime_extra_count()\fR, \fBRSA_get0_multi_prime_factors()\fR, +\&\fBRSA_get0_multi_prime_crt_params()\fR, \fBRSA_set0_multi_prime_params()\fR, +and \fBRSA_get_version()\fR functions were added in OpenSSL 1.1.1. +.PP +Other functions described here were added in OpenSSL 1.1.0. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_get_app_data.3 b/static/netbsd/man3/RSA_get_app_data.3 new file mode 100644 index 00000000..90278cc3 --- /dev/null +++ b/static/netbsd/man3/RSA_get_app_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_get_app_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/RSA_get_ex_new_index.3 b/static/netbsd/man3/RSA_get_ex_new_index.3 new file mode 100644 index 00000000..5c2f4cbd --- /dev/null +++ b/static/netbsd/man3/RSA_get_ex_new_index.3 @@ -0,0 +1,251 @@ +.\" $NetBSD: RSA_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RSA_get_ex_new_index 3" +.TH RSA_get_ex_new_index 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data \- add application specific data to RSA structures +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RSA_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int RSA_set_ex_data(RSA *r, int idx, void *arg); +\& +\& void *RSA_get_ex_data(RSA *r, int idx); +\& +\& typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, +\& int idx, long argl, void *argp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application specific data attached to them. +This has several potential uses, it can be used to cache data associated with +a structure (for example the hash of some part of the structure) or some +additional data (for example a handle to the data in an external library). +.PP +Since the application data can be anything at all it is passed and retrieved +as a \fBvoid *\fR type. +.PP +The \fB\f(BIRSA_get_ex_new_index()\fB\fR function is initially called to \*(L"register\*(R" some +new application specific data. It takes three optional function pointers which +are called when the parent structure (in this case an \s-1RSA\s0 structure) is +initially created, when it is copied and when it is freed up. If any or all of +these function pointer arguments are not used they should be set to \s-1NULL.\s0 The +precise manner in which these function pointers are called is described in more +detail below. \fB\f(BIRSA_get_ex_new_index()\fB\fR also takes additional long and pointer +parameters which will be passed to the supplied functions but which otherwise +have no special meaning. It returns an \fBindex\fR which should be stored +(typically in a static variable) and passed used in the \fBidx\fR parameter in +the remaining functions. Each successful call to \fB\f(BIRSA_get_ex_new_index()\fB\fR +will return an index greater than any previously returned, this is important +because the optional functions are called in order of increasing index value. +.PP +\&\fB\f(BIRSA_set_ex_data()\fB\fR is used to set application specific data, the data is +supplied in the \fBarg\fR parameter and its precise meaning is up to the +application. +.PP +\&\fB\f(BIRSA_get_ex_data()\fB\fR is used to retrieve application specific data. The data +is returned to the application, this will be the same value as supplied to +a previous \fB\f(BIRSA_set_ex_data()\fB\fR call. +.PP +\&\fB\f(BInew_func()\fB\fR is called when a structure is initially allocated (for example +with \fB\f(BIRSA_new()\fB\fR. The parent structure members will not have any meaningful +values at this point. This function will typically be used to allocate any +application specific structure. +.PP +\&\fB\f(BIfree_func()\fB\fR is called when a structure is being freed up. The dynamic parent +structure members should not be accessed because they will be freed up when +this function is called. +.PP +\&\fB\f(BInew_func()\fB\fR and \fB\f(BIfree_func()\fB\fR take the same parameters. \fBparent\fR is a +pointer to the parent \s-1RSA\s0 structure. \fBptr\fR is a the application specific data +(this wont be of much use in \fB\f(BInew_func()\fB\fR. \fBad\fR is a pointer to the +\&\fB\s-1CRYPTO_EX_DATA\s0\fR structure from the parent \s-1RSA\s0 structure: the functions +\&\fB\f(BICRYPTO_get_ex_data()\fB\fR and \fB\f(BICRYPTO_set_ex_data()\fB\fR can be called to manipulate +it. The \fBidx\fR parameter is the index: this will be the same value returned by +\&\fB\f(BIRSA_get_ex_new_index()\fB\fR when the functions were initially registered. Finally +the \fBargl\fR and \fBargp\fR parameters are the values originally passed to the same +corresponding parameters when \fB\f(BIRSA_get_ex_new_index()\fB\fR was called. +.PP +\&\fB\f(BIdup_func()\fB\fR is called when a structure is being copied. Pointers to the +destination and source \fB\s-1CRYPTO_EX_DATA\s0\fR structures are passed in the \fBto\fR and +\&\fBfrom\fR parameters respectively. The \fBfrom_d\fR parameter is passed a pointer to +the source application data when the function is called, when the function returns +the value is copied to the destination: the application can thus modify the data +pointed to by \fBfrom_d\fR and have different values in the source and destination. +The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are the same as those in \fB\f(BInew_func()\fB\fR +and \fB\f(BIfree_func()\fB\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fB\f(BIRSA_get_ex_new_index()\fB\fR returns a new index or \-1 on failure (note 0 is a valid +index value). +.PP +\&\fB\f(BIRSA_set_ex_data()\fB\fR returns 1 on success or 0 on failure. +.PP +\&\fB\f(BIRSA_get_ex_data()\fB\fR returns the application data or 0 on failure. 0 may also +be valid application data but currently it can only fail if given an invalid \fBidx\fR +parameter. +.PP +\&\fB\f(BInew_func()\fB\fR and \fB\f(BIdup_func()\fB\fR should return 0 for failure and 1 for success. +.PP +On failure an error code can be obtained from \fIERR_get_error\fR\|(3). +.SH "BUGS" +.IX Header "BUGS" +\&\fB\f(BIdup_func()\fB\fR is currently never called. +.PP +The return value of \fB\f(BInew_func()\fB\fR is ignored. +.PP +The \fB\f(BInew_func()\fB\fR function isn't very useful because no meaningful values are +present in the parent \s-1RSA\s0 structure when it is called. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_rsa\fR\|(3), \fICRYPTO_set_ex_data\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR are +available since SSLeay 0.9.0. diff --git a/static/netbsd/man3/RSA_get_method.3 b/static/netbsd/man3/RSA_get_method.3 new file mode 100644 index 00000000..b11e42bc --- /dev/null +++ b/static/netbsd/man3/RSA_get_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_get_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/RSA_meth_new.3 b/static/netbsd/man3/RSA_meth_new.3 new file mode 100644 index 00000000..63404979 --- /dev/null +++ b/static/netbsd/man3/RSA_meth_new.3 @@ -0,0 +1,331 @@ +.\" $NetBSD: RSA_meth_new.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_meth_new 3" +.TH RSA_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_meth_get0_app_data, RSA_meth_set0_app_data, +RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name, +RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags, +RSA_meth_get_pub_enc, +RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec, +RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec, +RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp, +RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init, +RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish, +RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify, +RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen, +RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen +\&\- Routines to build up RSA methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& RSA_METHOD *RSA_meth_new(const char *name, int flags); +\& void RSA_meth_free(RSA_METHOD *meth); +\& +\& RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth); +\& +\& const char *RSA_meth_get0_name(const RSA_METHOD *meth); +\& int RSA_meth_set1_name(RSA_METHOD *meth, const char *name); +\& +\& int RSA_meth_get_flags(const RSA_METHOD *meth); +\& int RSA_meth_set_flags(RSA_METHOD *meth, int flags); +\& +\& void *RSA_meth_get0_app_data(const RSA_METHOD *meth); +\& int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data); +\& +\& int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& int RSA_meth_set_pub_enc(RSA_METHOD *rsa, +\& int (*pub_enc)(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, +\& int padding)); +\& +\& int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth)) +\& (int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& int RSA_meth_set_pub_dec(RSA_METHOD *rsa, +\& int (*pub_dec)(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, +\& int padding)); +\& +\& int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, +\& int padding); +\& int RSA_meth_set_priv_enc(RSA_METHOD *rsa, +\& int (*priv_enc)(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding)); +\& +\& int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth))(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, +\& int padding); +\& int RSA_meth_set_priv_dec(RSA_METHOD *rsa, +\& int (*priv_dec)(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding)); +\& +\& /* Can be null */ +\& int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *i, +\& RSA *rsa, BN_CTX *ctx); +\& int RSA_meth_set_mod_exp(RSA_METHOD *rsa, +\& int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, +\& BN_CTX *ctx)); +\& +\& /* Can be null */ +\& int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))(BIGNUM *r, const BIGNUM *a, +\& const BIGNUM *p, const BIGNUM *m, +\& BN_CTX *ctx, BN_MONT_CTX *m_ctx); +\& int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa, +\& int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, +\& const BIGNUM *p, const BIGNUM *m, +\& BN_CTX *ctx, BN_MONT_CTX *m_ctx)); +\& +\& /* called at new */ +\& int (*RSA_meth_get_init(const RSA_METHOD *meth) (RSA *rsa); +\& int RSA_meth_set_init(RSA_METHOD *rsa, int (*init (RSA *rsa)); +\& +\& /* called at free */ +\& int (*RSA_meth_get_finish(const RSA_METHOD *meth))(RSA *rsa); +\& int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish)(RSA *rsa)); +\& +\& int (*RSA_meth_get_sign(const RSA_METHOD *meth))(int type, const unsigned char *m, +\& unsigned int m_length, +\& unsigned char *sigret, +\& unsigned int *siglen, const RSA *rsa); +\& int RSA_meth_set_sign(RSA_METHOD *rsa, +\& int (*sign)(int type, const unsigned char *m, +\& unsigned int m_length, unsigned char *sigret, +\& unsigned int *siglen, const RSA *rsa)); +\& +\& int (*RSA_meth_get_verify(const RSA_METHOD *meth))(int dtype, const unsigned char *m, +\& unsigned int m_length, +\& const unsigned char *sigbuf, +\& unsigned int siglen, const RSA *rsa); +\& int RSA_meth_set_verify(RSA_METHOD *rsa, +\& int (*verify)(int dtype, const unsigned char *m, +\& unsigned int m_length, +\& const unsigned char *sigbuf, +\& unsigned int siglen, const RSA *rsa)); +\& +\& int (*RSA_meth_get_keygen(const RSA_METHOD *meth))(RSA *rsa, int bits, BIGNUM *e, +\& BN_GENCB *cb); +\& int RSA_meth_set_keygen(RSA_METHOD *rsa, +\& int (*keygen)(RSA *rsa, int bits, BIGNUM *e, +\& BN_GENCB *cb)); +\& +\& int (*RSA_meth_get_multi_prime_keygen(const RSA_METHOD *meth))(RSA *rsa, int bits, +\& int primes, BIGNUM *e, +\& BN_GENCB *cb); +\& +\& int RSA_meth_set_multi_prime_keygen(RSA_METHOD *meth, +\& int (*keygen) (RSA *rsa, int bits, +\& int primes, BIGNUM *e, +\& BN_GENCB *cb)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +The \fBRSA_METHOD\fR type is a structure used for the provision of custom +RSA implementations. It provides a set of functions used by OpenSSL +for the implementation of the various RSA capabilities. +.PP +\&\fBRSA_meth_new()\fR creates a new \fBRSA_METHOD\fR structure. It should be +given a unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a +NULL terminated string, which will be duplicated and stored in the +\&\fBRSA_METHOD\fR object. It is the callers responsibility to free the +original string. The flags will be used during the construction of a +new \fBRSA\fR object based on this \fBRSA_METHOD\fR. Any new \fBRSA\fR object +will have those flags set by default. +.PP +\&\fBRSA_meth_dup()\fR creates a duplicate copy of the \fBRSA_METHOD\fR object +passed as a parameter. This might be useful for creating a new +\&\fBRSA_METHOD\fR based on an existing one, but with some differences. +.PP +\&\fBRSA_meth_free()\fR destroys an \fBRSA_METHOD\fR structure and frees up any +memory associated with it. If the argument is NULL, nothing is done. +.PP +\&\fBRSA_meth_get0_name()\fR will return a pointer to the name of this +RSA_METHOD. This is a pointer to the internal name string and so +should not be freed by the caller. \fBRSA_meth_set1_name()\fR sets the name +of the RSA_METHOD to \fBname\fR. The string is duplicated and the copy is +stored in the RSA_METHOD structure, so the caller remains responsible +for freeing the memory associated with the name. +.PP +\&\fBRSA_meth_get_flags()\fR returns the current value of the flags associated +with this RSA_METHOD. \fBRSA_meth_set_flags()\fR provides the ability to set +these flags. +.PP +The functions \fBRSA_meth_get0_app_data()\fR and \fBRSA_meth_set0_app_data()\fR +provide the ability to associate implementation specific data with the +RSA_METHOD. It is the application\*(Aqs responsibility to free this data +before the RSA_METHOD is freed via a call to \fBRSA_meth_free()\fR. +.PP +\&\fBRSA_meth_get_sign()\fR and \fBRSA_meth_set_sign()\fR get and set the function +used for creating an RSA signature respectively. This function will be +called in response to the application calling \fBRSA_sign()\fR. The +parameters for the function have the same meaning as for \fBRSA_sign()\fR. +.PP +\&\fBRSA_meth_get_verify()\fR and \fBRSA_meth_set_verify()\fR get and set the +function used for verifying an RSA signature respectively. This +function will be called in response to the application calling +\&\fBRSA_verify()\fR. The parameters for the function have the same meaning as +for \fBRSA_verify()\fR. +.PP +\&\fBRSA_meth_get_mod_exp()\fR and \fBRSA_meth_set_mod_exp()\fR get and set the +function used for CRT computations. +.PP +\&\fBRSA_meth_get_bn_mod_exp()\fR and \fBRSA_meth_set_bn_mod_exp()\fR get and set +the function used for CRT computations, specifically the following +value: +.PP +.Vb 1 +\& r = a ^ p mod m +.Ve +.PP +Both the \fBmod_exp()\fR and \fBbn_mod_exp()\fR functions are called by the +default OpenSSL method during encryption, decryption, signing and +verification. +.PP +\&\fBRSA_meth_get_init()\fR and \fBRSA_meth_set_init()\fR get and set the function +used for creating a new RSA instance respectively. This function will +be called in response to the application calling \fBRSA_new()\fR (if the +current default RSA_METHOD is this one) or \fBRSA_new_method()\fR. The +\&\fBRSA_new()\fR and \fBRSA_new_method()\fR functions will allocate the memory for +the new RSA object, and a pointer to this newly allocated structure +will be passed as a parameter to the function. This function may be +NULL. +.PP +\&\fBRSA_meth_get_finish()\fR and \fBRSA_meth_set_finish()\fR get and set the +function used for destroying an instance of an RSA object respectively. +This function will be called in response to the application calling +\&\fBRSA_free()\fR. A pointer to the RSA to be destroyed is passed as a +parameter. The destroy function should be used for RSA implementation +specific clean up. The memory for the RSA itself should not be freed +by this function. This function may be NULL. +.PP +\&\fBRSA_meth_get_keygen()\fR and \fBRSA_meth_set_keygen()\fR get and set the +function used for generating a new RSA key pair respectively. This +function will be called in response to the application calling +\&\fBRSA_generate_key_ex()\fR. The parameter for the function has the same +meaning as for \fBRSA_generate_key_ex()\fR. +.PP +\&\fBRSA_meth_get_multi_prime_keygen()\fR and \fBRSA_meth_set_multi_prime_keygen()\fR get +and set the function used for generating a new multi\-prime RSA key pair +respectively. This function will be called in response to the application calling +\&\fBRSA_generate_multi_prime_key()\fR. The parameter for the function has the same +meaning as for \fBRSA_generate_multi_prime_key()\fR. +.PP +\&\fBRSA_meth_get_pub_enc()\fR, \fBRSA_meth_set_pub_enc()\fR, +\&\fBRSA_meth_get_pub_dec()\fR, \fBRSA_meth_set_pub_dec()\fR, +\&\fBRSA_meth_get_priv_enc()\fR, \fBRSA_meth_set_priv_enc()\fR, +\&\fBRSA_meth_get_priv_dec()\fR, \fBRSA_meth_set_priv_dec()\fR get and set the +functions used for public and private key encryption and decryption. +These functions will be called in response to the application calling +\&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR, \fBRSA_private_encrypt()\fR and +\&\fBRSA_public_decrypt()\fR and take the same parameters as those. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_meth_new()\fR and \fBRSA_meth_dup()\fR return the newly allocated +RSA_METHOD object or NULL on failure. +.PP +\&\fBRSA_meth_get0_name()\fR and \fBRSA_meth_get_flags()\fR return the name and +flags associated with the RSA_METHOD respectively. +.PP +All other RSA_meth_get_*() functions return the appropriate function +pointer that has been set in the RSA_METHOD, or NULL if no such +pointer has yet been set. +.PP +RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on +success or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRSA_new\fR\|(3), \fBRSA_generate_key_ex\fR\|(3), \fBRSA_sign\fR\|(3), +\&\fBRSA_set_method\fR\|(3), \fBRSA_size\fR\|(3), \fBRSA_get0_key\fR\|(3), +\&\fBRSA_generate_multi_prime_key\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +\&\fBRSA_meth_get_multi_prime_keygen()\fR and \fBRSA_meth_set_multi_prime_keygen()\fR were +added in OpenSSL 1.1.1. +.PP +Other functions described here were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_new.3 b/static/netbsd/man3/RSA_new.3 new file mode 100644 index 00000000..0d3cdbd4 --- /dev/null +++ b/static/netbsd/man3/RSA_new.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: RSA_new.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_new 3" +.TH RSA_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_new, RSA_free \- allocate and free RSA objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& RSA *RSA_new(void); +\& +\& void RSA_free(RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRSA_new()\fR allocates and initializes an \fBRSA\fR structure. It is equivalent to +calling RSA_new_method(NULL). +.PP +\&\fBRSA_free()\fR frees the \fBRSA\fR structure and its components. The key is +erased before the memory is returned to the system. +If \fBrsa\fR is NULL nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBRSA_new()\fR returns \fBNULL\fR and sets an error +code that can be obtained by \fBERR_get_error\fR\|(3). Otherwise it returns +a pointer to the newly allocated structure. +.PP +\&\fBRSA_free()\fR returns no value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBRSA_generate_key\fR\|(3), +\&\fBRSA_new_method\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All functions described here were deprecated in OpenSSL 3.0. +For replacement see \fBEVP_PKEY\-RSA\fR\|(7). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_new_method.3 b/static/netbsd/man3/RSA_new_method.3 new file mode 100644 index 00000000..e461b517 --- /dev/null +++ b/static/netbsd/man3/RSA_new_method.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_new_method.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/RSA_padding_add_PKCS1_type_1.3 b/static/netbsd/man3/RSA_padding_add_PKCS1_type_1.3 new file mode 100644 index 00000000..f6d42856 --- /dev/null +++ b/static/netbsd/man3/RSA_padding_add_PKCS1_type_1.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: RSA_padding_add_PKCS1_type_1.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_padding_add_PKCS1_type_1 3" +.TH RSA_padding_add_PKCS1_type_1 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, +RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, +RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, +RSA_padding_add_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1, +RSA_padding_add_none, RSA_padding_check_none \- asymmetric encryption +padding +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, +\& const unsigned char *f, int fl); +\& +\& int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, int rsa_len); +\& +\& int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, +\& const unsigned char *f, int fl); +\& +\& int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, int rsa_len); +\& +\& int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, +\& const unsigned char *p, int pl); +\& +\& int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, int rsa_len, +\& const unsigned char *p, int pl); +\& +\& int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, +\& const unsigned char *p, int pl, +\& const EVP_MD *md, const EVP_MD *mgf1md); +\& +\& int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, int rsa_len, +\& const unsigned char *p, int pl, +\& const EVP_MD *md, const EVP_MD *mgf1md); +\& +\& int RSA_padding_add_none(unsigned char *to, int tlen, +\& const unsigned char *f, int fl); +\& +\& int RSA_padding_check_none(unsigned char *to, int tlen, +\& const unsigned char *f, int fl, int rsa_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the EVP PKEY APIs. +.PP +The \fBRSA_padding_xxx_xxx()\fR functions are called from the RSA encrypt, +decrypt, sign and verify functions. Normally they should not be called +from application programs. +.PP +However, they can also be called directly to implement padding for other +asymmetric ciphers. \fBRSA_padding_add_PKCS1_OAEP()\fR and +\&\fBRSA_padding_check_PKCS1_OAEP()\fR may be used in an application combined +with \fBRSA_NO_PADDING\fR in order to implement OAEP with an encoding +parameter. +.PP +\&\fBRSA_padding_add_xxx()\fR encodes \fBfl\fR bytes from \fBf\fR so as to fit into +\&\fBtlen\fR bytes and stores the result at \fBto\fR. An error occurs if \fBfl\fR +does not meet the size requirements of the encoding method. +.PP +The following encoding methods are implemented: +.IP PKCS1_type_1 4 +.IX Item "PKCS1_type_1" +PKCS #1 v2.0 EMSA\-PKCS1\-v1_5 (PKCS #1 v1.5 block type 1); used for signatures +.IP PKCS1_type_2 4 +.IX Item "PKCS1_type_2" +PKCS #1 v2.0 EME\-PKCS1\-v1_5 (PKCS #1 v1.5 block type 2) +.IP PKCS1_OAEP 4 +.IX Item "PKCS1_OAEP" +PKCS #1 v2.0 EME\-OAEP +.IP none 4 +.IX Item "none" +simply copy the data +.PP +The random number generator must be seeded prior to calling +\&\fBRSA_padding_add_xxx()\fR. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +\&\fBRSA_padding_check_xxx()\fR verifies that the \fBfl\fR bytes at \fBf\fR contain +a valid encoding for a \fBrsa_len\fR byte RSA key in the respective +encoding method and stores the recovered data of at most \fBtlen\fR bytes +(for \fBRSA_NO_PADDING\fR: of size \fBtlen\fR) +at \fBto\fR. +.PP +For \fBRSA_padding_xxx_OAEP()\fR, \fBp\fR points to the encoding parameter +of length \fBpl\fR. \fBp\fR may be \fBNULL\fR if \fBpl\fR is 0. +.PP +For \fBRSA_padding_xxx_OAEP_mgf1()\fR, \fBmd\fR points to the md hash, +if \fBmd\fR is \fBNULL\fR that means md=sha1, and \fBmgf1md\fR points to +the mgf1 hash, if \fBmgf1md\fR is \fBNULL\fR that means mgf1md=md. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBRSA_padding_add_xxx()\fR functions return 1 on success, 0 on error. +The \fBRSA_padding_check_xxx()\fR functions return the length of the +recovered data, \-1 on error. Error codes can be obtained by calling +\&\fBERR_get_error\fR\|(3). +.SH WARNINGS +.IX Header "WARNINGS" +The result of \fBRSA_padding_check_PKCS1_type_2()\fR is exactly the +information which is used to mount a classical Bleichenbacher +padding oracle attack. This is an inherent weakness in the PKCS #1 +v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not +possible, the result of \fBRSA_padding_check_PKCS1_type_2()\fR should be +checked in constant time if it matches the expected length of the +plaintext and additionally some application specific consistency +checks on the plaintext need to be performed in constant time. +If the plaintext is rejected it must be kept secret which of the +checks caused the application to reject the message. +Do not remove the zero\-padding from the decrypted raw RSA data +which was computed by \fBRSA_private_decrypt()\fR with \fBRSA_NO_PADDING\fR, +as this would create a small timing side channel which could be +used to mount a Bleichenbacher attack against any padding mode +including PKCS1_OAEP. +.PP +You should prefer the use of EVP PKEY APIs for PKCS#1 v1.5 decryption +as they implement the necessary workarounds internally. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRSA_public_encrypt\fR\|(3), +\&\fBRSA_private_decrypt\fR\|(3), +\&\fBRSA_sign\fR\|(3), \fBRSA_verify\fR\|(3), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_print.3 b/static/netbsd/man3/RSA_print.3 new file mode 100644 index 00000000..8faff3e9 --- /dev/null +++ b/static/netbsd/man3/RSA_print.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: RSA_print.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_print 3" +.TH RSA_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_print, RSA_print_fp, +DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp, +DHparams_print, DHparams_print_fp \- print cryptographic parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_print(BIO *bp, const RSA *x, int offset); +\& int RSA_print_fp(FILE *fp, const RSA *x, int offset); +\& +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& int DSAparams_print(BIO *bp, const DSA *x); +\& int DSAparams_print_fp(FILE *fp, const DSA *x); +\& int DSA_print(BIO *bp, const DSA *x, int offset); +\& int DSA_print_fp(FILE *fp, const DSA *x, int offset); +\& +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int DHparams_print(BIO *bp, DH *x); +\& int DHparams_print_fp(FILE *fp, const DH *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_print_params\fR\|(3) and +\&\fBEVP_PKEY_print_private\fR\|(3). +.PP +A human\-readable hexadecimal output of the components of the RSA +key, DSA parameters or key or DH parameters is printed to \fBbp\fR or \fBfp\fR. +.PP +The output lines are indented by \fBoffset\fR spaces. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDSAparams_print()\fR, \fBDSAparams_print_fp()\fR, \fBDSA_print()\fR, and \fBDSA_print_fp()\fR +return 1 for success and 0 or a negative value for failure. +.PP +\&\fBDHparams_print()\fR and \fBDHparams_print_fp()\fR return 1 on success, 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +.Vb 3 +\& L, +\& L, +\& L +.Ve +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_private_encrypt.3 b/static/netbsd/man3/RSA_private_encrypt.3 new file mode 100644 index 00000000..3b7b38b5 --- /dev/null +++ b/static/netbsd/man3/RSA_private_encrypt.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: RSA_private_encrypt.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_private_encrypt 3" +.TH RSA_private_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_private_encrypt, RSA_public_decrypt \- low\-level signature operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_private_encrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& int RSA_public_decrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Both of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_sign_init_ex\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_recover_init\fR\|(3), and +\&\fBEVP_PKEY_verify_recover\fR\|(3). +.PP +These functions handle RSA signatures at a low\-level. +.PP +\&\fBRSA_private_encrypt()\fR signs the \fBflen\fR bytes at \fBfrom\fR (usually a +message digest with an algorithm identifier) using the private key +\&\fBrsa\fR and stores the signature in \fBto\fR. \fBto\fR must point to +\&\fBRSA_size(rsa)\fR bytes of memory. +.PP +\&\fBpadding\fR denotes one of the following modes: +.IP RSA_PKCS1_PADDING 4 +.IX Item "RSA_PKCS1_PADDING" +PKCS #1 v1.5 padding. This function does not handle the +\&\fBalgorithmIdentifier\fR specified in PKCS #1. When generating or +verifying PKCS #1 signatures, \fBRSA_sign\fR\|(3) and \fBRSA_verify\fR\|(3) should be +used. +.IP RSA_NO_PADDING 4 +.IX Item "RSA_NO_PADDING" +Raw RSA signature. This mode should \fIonly\fR be used to implement +cryptographically sound padding modes in the application code. +Signing user data directly with RSA is insecure. +.PP +\&\fBRSA_public_decrypt()\fR recovers the message digest from the \fBflen\fR +bytes long signature at \fBfrom\fR using the signer\*(Aqs public key +\&\fBrsa\fR. \fBto\fR must point to a memory section large enough to hold the +message digest (which is smaller than \fBRSA_size(rsa) \- +11\fR). \fBpadding\fR is the padding mode that was used to sign the data. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_private_encrypt()\fR returns the size of the signature (i.e., +RSA_size(rsa)). \fBRSA_public_decrypt()\fR returns the size of the +recovered message digest. +.PP +On error, \-1 is returned; the error codes can be +obtained by \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBRSA_sign\fR\|(3), \fBRSA_verify\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), \fBEVP_PKEY_verify_recover\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Both of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_public_encrypt.3 b/static/netbsd/man3/RSA_public_encrypt.3 new file mode 100644 index 00000000..822b85eb --- /dev/null +++ b/static/netbsd/man3/RSA_public_encrypt.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: RSA_public_encrypt.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_public_encrypt 3" +.TH RSA_public_encrypt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_public_encrypt, RSA_private_decrypt \- RSA public key cryptography +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_public_encrypt(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& int RSA_private_decrypt(int flen, const unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Both of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_encrypt_init_ex\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), \fBEVP_PKEY_decrypt_init_ex\fR\|(3) and +\&\fBEVP_PKEY_decrypt\fR\|(3). +.PP +\&\fBRSA_public_encrypt()\fR encrypts the \fBflen\fR bytes at \fBfrom\fR (usually a +session key) using the public key \fBrsa\fR and stores the ciphertext in +\&\fBto\fR. \fBto\fR must point to RSA_size(\fBrsa\fR) bytes of memory. +.PP +\&\fBpadding\fR denotes one of the following modes: +.IP RSA_PKCS1_PADDING 4 +.IX Item "RSA_PKCS1_PADDING" +PKCS #1 v1.5 padding. This currently is the most widely used mode. +However, it is highly recommended to use RSA_PKCS1_OAEP_PADDING in +new applications. SEE WARNING BELOW. +.IP RSA_PKCS1_OAEP_PADDING 4 +.IX Item "RSA_PKCS1_OAEP_PADDING" +EME\-OAEP as defined in PKCS #1 v2.0 with SHA\-1, MGF1 and an empty +encoding parameter. This mode is recommended for all new applications. +.IP RSA_NO_PADDING 4 +.IX Item "RSA_NO_PADDING" +Raw RSA encryption. This mode should \fIonly\fR be used to implement +cryptographically sound padding modes in the application code. +Encrypting user data directly with RSA is insecure. +.PP +When encrypting \fBflen\fR must not be more than RSA_size(\fBrsa\fR) \- 11 for the +PKCS #1 v1.5 based padding modes, not more than RSA_size(\fBrsa\fR) \- 42 for +RSA_PKCS1_OAEP_PADDING and exactly RSA_size(\fBrsa\fR) for RSA_NO_PADDING. +When a padding mode other than RSA_NO_PADDING is in use, then +\&\fBRSA_public_encrypt()\fR will include some random bytes into the ciphertext +and therefore the ciphertext will be different each time, even if the +plaintext and the public key are exactly identical. +The returned ciphertext in \fBto\fR will always be zero padded to exactly +RSA_size(\fBrsa\fR) bytes. +\&\fBto\fR and \fBfrom\fR may overlap. +.PP +\&\fBRSA_private_decrypt()\fR decrypts the \fBflen\fR bytes at \fBfrom\fR using the +private key \fBrsa\fR and stores the plaintext in \fBto\fR. \fBflen\fR should +be equal to RSA_size(\fBrsa\fR) but may be smaller, when leading zero +bytes are in the ciphertext. Those are not important and may be removed, +but \fBRSA_public_encrypt()\fR does not do that. \fBto\fR must point +to a memory section large enough to hold the maximal possible decrypted +data (which is equal to RSA_size(\fBrsa\fR) for RSA_NO_PADDING, +RSA_size(\fBrsa\fR) \- 11 for the PKCS #1 v1.5 based padding modes and +RSA_size(\fBrsa\fR) \- 42 for RSA_PKCS1_OAEP_PADDING). +\&\fBpadding\fR is the padding mode that was used to encrypt the data. +\&\fBto\fR and \fBfrom\fR may overlap. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_public_encrypt()\fR returns the size of the encrypted data (i.e., +RSA_size(\fBrsa\fR)). \fBRSA_private_decrypt()\fR returns the size of the +recovered plaintext. A return value of 0 is not an error and +means only that the plaintext was empty. +.PP +On error, \-1 is returned; the error codes can be +obtained by \fBERR_get_error\fR\|(3). +.SH WARNINGS +.IX Header "WARNINGS" +Decryption failures in the RSA_PKCS1_PADDING mode leak information +which can potentially be used to mount a Bleichenbacher padding oracle +attack. This is an inherent weakness in the PKCS #1 v1.5 padding +design. Prefer RSA_PKCS1_OAEP_PADDING. +.PP +In OpenSSL before version 3.2.0, both the return value and the length of +returned value could be used to mount the Bleichenbacher attack. +Since version 3.2.0, the default provider in OpenSSL does not return an +error when padding checks fail. Instead it generates a random +message based on used private +key and provided ciphertext so that application code doesn\*(Aqt have to implement +a side\-channel secure error handling. +Applications that want to be secure against side\-channel attacks with +providers that don\*(Aqt implement implicit rejection, still need to +handle the returned values using side\-channel free code. +Side\-channel free handling of the error stack can be performed using +either a pair of unconditional \fBERR_set_mark\fR\|(3) and \fBERR_pop_to_mark\fR\|(3) +calls or by using the \fBERR_clear_error\fR\|(3) call. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +SSL, PKCS #1 v2.0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBRAND_bytes\fR\|(3), +\&\fBRSA_size\fR\|(3), \fBEVP_PKEY_decrypt\fR\|(3), \fBEVP_PKEY_encrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Both of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_set_app_data.3 b/static/netbsd/man3/RSA_set_app_data.3 new file mode 100644 index 00000000..dcfad303 --- /dev/null +++ b/static/netbsd/man3/RSA_set_app_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_set_app_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/RSA_set_method.3 b/static/netbsd/man3/RSA_set_method.3 new file mode 100644 index 00000000..aca5745a --- /dev/null +++ b/static/netbsd/man3/RSA_set_method.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: RSA_set_method.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_set_method 3" +.TH RSA_set_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_set_default_method, RSA_get_default_method, RSA_set_method, +RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, +RSA_new_method \- select RSA method +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void RSA_set_default_method(const RSA_METHOD *meth); +\& +\& const RSA_METHOD *RSA_get_default_method(void); +\& +\& int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); +\& +\& const RSA_METHOD *RSA_get_method(const RSA *rsa); +\& +\& const RSA_METHOD *RSA_PKCS1_OpenSSL(void); +\& +\& int RSA_flags(const RSA *rsa); +\& +\& RSA *RSA_new_method(ENGINE *engine); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use the OSSL_PROVIDER APIs. +.PP +An \fBRSA_METHOD\fR specifies the functions that OpenSSL uses for RSA +operations. By modifying the method, alternative implementations such as +hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these RSA API functions are affected by the +use of \fBENGINE\fR API calls. +.PP +Initially, the default RSA_METHOD is the OpenSSL internal implementation, +as returned by \fBRSA_PKCS1_OpenSSL()\fR. +.PP +\&\fBRSA_set_default_method()\fR makes \fBmeth\fR the default method for all RSA +structures created later. +\&\fBNB\fR: This is true only whilst no ENGINE has +been set as a default for RSA, so this function is no longer recommended. +This function is not thread\-safe and should not be called at the same time +as other OpenSSL functions. +.PP +\&\fBRSA_get_default_method()\fR returns a pointer to the current default +RSA_METHOD. However, the meaningfulness of this result is dependent on +whether the ENGINE API is being used, so this function is no longer +recommended. +.PP +\&\fBRSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key +\&\fBrsa\fR. This will replace the RSA_METHOD used by the RSA key and if the +previous method was supplied by an ENGINE, the handle to that ENGINE will +be released during the change. It is possible to have RSA keys that only +work with certain RSA_METHOD implementations (e.g. from an ENGINE module +that supports embedded hardware\-protected keys), and in such cases +attempting to change the RSA_METHOD for the key can have unexpected +results. +.PP +\&\fBRSA_get_method()\fR returns a pointer to the RSA_METHOD being used by \fBrsa\fR. +This method may or may not be supplied by an ENGINE implementation, but if +it is, the return value can only be guaranteed to be valid as long as the +RSA key itself is valid and does not have its implementation changed by +\&\fBRSA_set_method()\fR. +.PP +\&\fBRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR\*(Aqs current +RSA_METHOD. See the BUGS section. +.PP +\&\fBRSA_new_method()\fR allocates and initializes an RSA structure so that +\&\fBengine\fR will be used for the RSA operations. If \fBengine\fR is NULL, the +default ENGINE for RSA operations is used, and if no default ENGINE is set, +the RSA_METHOD controlled by \fBRSA_set_default_method()\fR is used. +.PP +\&\fBRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR\*(Aqs current method. +.PP +\&\fBRSA_new_method()\fR allocates and initializes an \fBRSA\fR structure so that +\&\fBmethod\fR will be used for the RSA operations. If \fBmethod\fR is \fBNULL\fR, +the default method is used. +.SH "THE RSA_METHOD STRUCTURE" +.IX Header "THE RSA_METHOD STRUCTURE" +.Vb 4 +\& typedef struct rsa_meth_st +\& { +\& /* name of the implementation */ +\& const char *name; +\& +\& /* encrypt */ +\& int (*rsa_pub_enc)(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& /* verify arbitrary data */ +\& int (*rsa_pub_dec)(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& /* sign arbitrary data */ +\& int (*rsa_priv_enc)(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& /* decrypt */ +\& int (*rsa_priv_dec)(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& +\& /* compute r0 = r0 ^ I mod rsa\->n (May be NULL for some implementations) */ +\& int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); +\& +\& /* compute r = a ^ p mod m (May be NULL for some implementations) */ +\& int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); +\& +\& /* called at RSA_new */ +\& int (*init)(RSA *rsa); +\& +\& /* called at RSA_free */ +\& int (*finish)(RSA *rsa); +\& +\& /* +\& * RSA_FLAG_EXT_PKEY \- rsa_mod_exp is called for private key +\& * operations, even if p,q,dmp1,dmq1,iqmp +\& * are NULL +\& * RSA_METHOD_FLAG_NO_CHECK \- don\*(Aqt check pub/private match +\& */ +\& int flags; +\& +\& char *app_data; /* ?? */ +\& +\& int (*rsa_sign)(int type, +\& const unsigned char *m, unsigned int m_length, +\& unsigned char *sigret, unsigned int *siglen, const RSA *rsa); +\& int (*rsa_verify)(int dtype, +\& const unsigned char *m, unsigned int m_length, +\& const unsigned char *sigbuf, unsigned int siglen, +\& const RSA *rsa); +\& /* keygen. If NULL built\-in RSA key generation will be used */ +\& int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); +\& +\& } RSA_METHOD; +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_PKCS1_OpenSSL()\fR, \fBRSA_PKCS1_null_method()\fR, \fBRSA_get_default_method()\fR +and \fBRSA_get_method()\fR return pointers to the respective RSA_METHODs. +.PP +\&\fBRSA_set_default_method()\fR returns no value. +.PP +\&\fBRSA_set_method()\fR returns 1 for success. It always succeeds. +.PP +\&\fBRSA_new_method()\fR returns NULL and sets an error code that can be obtained +by \fBERR_get_error\fR\|(3) if the allocation fails. Otherwise +it returns a pointer to the newly allocated structure. +.SH BUGS +.IX Header "BUGS" +The behaviour of \fBRSA_flags()\fR is a mis\-feature that is left as\-is for now +to avoid creating compatibility problems. RSA functionality, such as the +encryption functions, are controlled by the \fBflags\fR value in the RSA key +itself, not by the \fBflags\fR value in the RSA_METHOD attached to the RSA key +(which is what this function returns). If the flags element of an RSA key +is changed, the changes will be honoured by RSA functionality but will not +be reflected in the return value of the \fBRSA_flags()\fR function \- in effect +\&\fBRSA_flags()\fR behaves more like an \fBRSA_default_flags()\fR function (which does +not currently exist). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRSA_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The \fBRSA_null_method()\fR, which was a partial attempt to avoid patent issues, +was replaced to always return NULL in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_sign.3 b/static/netbsd/man3/RSA_sign.3 new file mode 100644 index 00000000..edf6f04b --- /dev/null +++ b/static/netbsd/man3/RSA_sign.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: RSA_sign.3,v 1.5 2026/04/08 17:06:46 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_sign 3" +.TH RSA_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_sign, RSA_verify \- RSA signatures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int RSA_sign(int type, const unsigned char *m, unsigned int m_len, +\& unsigned char *sigret, unsigned int *siglen, RSA *rsa); +\& +\& int RSA_verify(int type, const unsigned char *m, unsigned int m_len, +\& unsigned char *sigbuf, unsigned int siglen, RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_sign_init\fR\|(3), \fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify_init\fR\|(3) and \fBEVP_PKEY_verify\fR\|(3). +.PP +\&\fBRSA_sign()\fR signs the message digest \fBm\fR of size \fBm_len\fR using the +private key \fBrsa\fR using RSASSA\-PKCS1\-v1_5 as specified in RFC 3447. It +stores the signature in \fBsigret\fR and the signature size in \fBsiglen\fR. +\&\fBsigret\fR must point to RSA_size(\fBrsa\fR) bytes of memory. +Note that PKCS #1 adds meta\-data, placing limits on the size of the +key that can be used. +See \fBRSA_private_encrypt\fR\|(3) for lower\-level +operations. +.PP +\&\fBtype\fR denotes the message digest algorithm that was used to generate +\&\fBm\fR. +If \fBtype\fR is \fBNID_md5_sha1\fR, +an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding +and no algorithm identifier) is created. +.PP +\&\fBRSA_verify()\fR verifies that the signature \fBsigbuf\fR of size \fBsiglen\fR +matches a given message digest \fBm\fR of size \fBm_len\fR. \fBtype\fR denotes +the message digest algorithm that was used to generate the signature. +\&\fBrsa\fR is the signer\*(Aqs public key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_sign()\fR returns 1 on success and 0 for failure. +\&\fBRSA_verify()\fR returns 1 on successful verification and 0 for failure. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +SSL, PKCS #1 v2.0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBRSA_private_encrypt\fR\|(3), +\&\fBRSA_public_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 b/static/netbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 new file mode 100644 index 00000000..e78345d5 --- /dev/null +++ b/static/netbsd/man3/RSA_sign_ASN1_OCTET_STRING.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: RSA_sign_ASN1_OCTET_STRING.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_sign_ASN1_OCTET_STRING 3" +.TH RSA_sign_ASN1_OCTET_STRING 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING \- RSA signatures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, +\& unsigned int m_len, unsigned char *sigret, +\& unsigned int *siglen, RSA *rsa); +\& +\& int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, +\& unsigned int m_len, unsigned char *sigbuf, +\& unsigned int siglen, RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use EVP PKEY APIs. +.PP +\&\fBRSA_sign_ASN1_OCTET_STRING()\fR signs the octet string \fBm\fR of size +\&\fBm_len\fR using the private key \fBrsa\fR represented in DER using PKCS #1 +padding. It stores the signature in \fBsigret\fR and the signature size +in \fBsiglen\fR. \fBsigret\fR must point to \fBRSA_size(rsa)\fR bytes of +memory. +.PP +\&\fBdummy\fR is ignored. +.PP +The random number generator must be seeded when calling +\&\fBRSA_sign_ASN1_OCTET_STRING()\fR. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +.PP +\&\fBRSA_verify_ASN1_OCTET_STRING()\fR verifies that the signature \fBsigbuf\fR +of size \fBsiglen\fR is the DER representation of a given octet string +\&\fBm\fR of size \fBm_len\fR. \fBdummy\fR is ignored. \fBrsa\fR is the signer\*(Aqs +public key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_sign_ASN1_OCTET_STRING()\fR returns 1 on success, 0 otherwise. +\&\fBRSA_verify_ASN1_OCTET_STRING()\fR returns 1 on successful verification, 0 +otherwise. +.PP +The error codes can be obtained by \fBERR_get_error\fR\|(3). +.SH BUGS +.IX Header "BUGS" +These functions serve no recognizable purpose. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBRAND_bytes\fR\|(3), \fBRSA_sign\fR\|(3), +\&\fBRSA_verify\fR\|(3), +\&\fBRAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_size.3 b/static/netbsd/man3/RSA_size.3 new file mode 100644 index 00000000..b476022c --- /dev/null +++ b/static/netbsd/man3/RSA_size.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: RSA_size.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "RSA_size 3" +.TH RSA_size 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RSA_size, RSA_bits, RSA_security_bits \- get RSA modulus size or security bits +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int RSA_bits(const RSA *rsa); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int RSA_size(const RSA *rsa); +\& +\& int RSA_security_bits(const RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRSA_bits()\fR returns the number of significant bits. +.PP +\&\fBrsa\fR and \fBrsa\->n\fR must not be \fBNULL\fR. +.PP +The remaining functions described on this page are deprecated. +Applications should instead use \fBEVP_PKEY_get_size\fR\|(3), \fBEVP_PKEY_get_bits\fR\|(3) +and \fBEVP_PKEY_get_security_bits\fR\|(3). +.PP +\&\fBRSA_size()\fR returns the RSA modulus size in bytes. It can be used to +determine how much memory must be allocated for an RSA encrypted +value. +.PP +\&\fBRSA_security_bits()\fR returns the number of security bits of the given \fBrsa\fR +key. See \fBBN_security_bits\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRSA_bits()\fR returns the number of bits in the key. +.PP +\&\fBRSA_size()\fR returns the size of modulus in bytes. +.PP +\&\fBRSA_security_bits()\fR returns the number of security bits. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBN_num_bits\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBRSA_size()\fR and \fBRSA_security_bits()\fR functions were deprecated in OpenSSL 3.0. +.PP +The \fBRSA_bits()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/RSA_up_ref.3 b/static/netbsd/man3/RSA_up_ref.3 new file mode 100644 index 00000000..9a193027 --- /dev/null +++ b/static/netbsd/man3/RSA_up_ref.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: RSA_up_ref.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_rsa.3 diff --git a/static/netbsd/man3/SCT_new.3 b/static/netbsd/man3/SCT_new.3 new file mode 100644 index 00000000..274b4539 --- /dev/null +++ b/static/netbsd/man3/SCT_new.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: SCT_new.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SCT_new 3" +.TH SCT_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, +SCT_get_version, SCT_set_version, +SCT_get_log_entry_type, SCT_set_log_entry_type, +SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, +SCT_get_timestamp, SCT_set_timestamp, +SCT_get_signature_nid, SCT_set_signature_nid, +SCT_get0_signature, SCT_set0_signature, SCT_set1_signature, +SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions, +SCT_get_source, SCT_set_source +\&\- A Certificate Transparency Signed Certificate Timestamp +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef enum { +\& CT_LOG_ENTRY_TYPE_NOT_SET = \-1, +\& CT_LOG_ENTRY_TYPE_X509 = 0, +\& CT_LOG_ENTRY_TYPE_PRECERT = 1 +\& } ct_log_entry_type_t; +\& +\& typedef enum { +\& SCT_VERSION_NOT_SET = \-1, +\& SCT_VERSION_V1 = 0 +\& } sct_version_t; +\& +\& typedef enum { +\& SCT_SOURCE_UNKNOWN, +\& SCT_SOURCE_TLS_EXTENSION, +\& SCT_SOURCE_X509V3_EXTENSION, +\& SCT_SOURCE_OCSP_STAPLED_RESPONSE +\& } sct_source_t; +\& +\& SCT *SCT_new(void); +\& SCT *SCT_new_from_base64(unsigned char version, +\& const char *logid_base64, +\& ct_log_entry_type_t entry_type, +\& uint64_t timestamp, +\& const char *extensions_base64, +\& const char *signature_base64); +\& +\& void SCT_free(SCT *sct); +\& void SCT_LIST_free(STACK_OF(SCT) *a); +\& +\& sct_version_t SCT_get_version(const SCT *sct); +\& int SCT_set_version(SCT *sct, sct_version_t version); +\& +\& ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct); +\& int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type); +\& +\& size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id); +\& int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len); +\& int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len); +\& +\& uint64_t SCT_get_timestamp(const SCT *sct); +\& void SCT_set_timestamp(SCT *sct, uint64_t timestamp); +\& +\& int SCT_get_signature_nid(const SCT *sct); +\& int SCT_set_signature_nid(SCT *sct, int nid); +\& +\& size_t SCT_get0_signature(const SCT *sct, unsigned char **sig); +\& void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len); +\& int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len); +\& +\& size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext); +\& void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len); +\& int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len); +\& +\& sct_source_t SCT_get_source(const SCT *sct); +\& int SCT_set_source(SCT *sct, sct_source_t source); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2. +They constitute a promise by a Certificate Transparency (CT) log to publicly +record a certificate. By cryptographically verifying that a log did indeed issue +an SCT, some confidence can be gained that the certificate is publicly known. +.PP +An internal representation of an SCT can be created in one of two ways. +The first option is to create a blank SCT, using \fBSCT_new()\fR, and then populate +it using: +.IP \(bu 2 +\&\fBSCT_set_version()\fR to set the SCT version. +.Sp +Only SCT_VERSION_V1 is currently supported. +.IP \(bu 2 +\&\fBSCT_set_log_entry_type()\fR to set the type of certificate the SCT was issued for: +.Sp +\&\fBCT_LOG_ENTRY_TYPE_X509\fR for a normal certificate. +\&\fBCT_LOG_ENTRY_TYPE_PRECERT\fR for a pre\-certificate. +.IP \(bu 2 +\&\fBSCT_set0_log_id()\fR or \fBSCT_set1_log_id()\fR to set the LogID of the CT log that the SCT came from. +.Sp +The former takes ownership, whereas the latter makes a copy. +See RFC 6962, Section 3.2 for the definition of LogID. +.IP \(bu 2 +\&\fBSCT_set_timestamp()\fR to set the time the SCT was issued (time in milliseconds +since the Unix Epoch). +.IP \(bu 2 +\&\fBSCT_set_signature_nid()\fR to set the NID of the signature. +.IP \(bu 2 +\&\fBSCT_set0_signature()\fR or \fBSCT_set1_signature()\fR to set the raw signature value. +.Sp +The former takes ownership, whereas the latter makes a copy. +.IP \(bu 2 +\&\fBSCT_set0_extensions()\fR or \fBSCT_set1_extensions\fR to provide SCT extensions. +.Sp +The former takes ownership, whereas the latter makes a copy. +.PP +Alternatively, the SCT can be pre\-populated from the following data using +\&\fBSCT_new_from_base64()\fR: +.IP \(bu 2 +The SCT version (only SCT_VERSION_V1 is currently supported). +.IP \(bu 2 +The LogID (see RFC 6962, Section 3.2), base64 encoded. +.IP \(bu 2 +The type of certificate the SCT was issued for: +\&\fBCT_LOG_ENTRY_TYPE_X509\fR for a normal certificate. +\&\fBCT_LOG_ENTRY_TYPE_PRECERT\fR for a pre\-certificate. +.IP \(bu 2 +The time that the SCT was issued (time in milliseconds since the Unix Epoch). +.IP \(bu 2 +The SCT extensions, base64 encoded. +.IP \(bu 2 +The SCT signature, base64 encoded. +.PP +\&\fBSCT_set_source()\fR can be used to record where the SCT was found +(TLS extension, X.509 certificate extension or OCSP response). This is not +required for verifying the SCT. +.PP +\&\fBSCT_free()\fR frees the specified SCT. +If the argument is NULL, nothing is done. +.PP +\&\fBSCT_LIST_free()\fR frees the specified stack of SCTs. +If the argument is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +Some of the setters return int, instead of void. These will all return 1 on +success, 0 on failure. They will not make changes on failure. +.PP +All of the setters will reset the validation status of the SCT to +SCT_VALIDATION_STATUS_NOT_SET (see \fBSCT_validate\fR\|(3)). +.PP +\&\fBSCT_set_source()\fR will call \fBSCT_set_log_entry_type()\fR if the type of +certificate the SCT was issued for can be inferred from where the SCT was found. +For example, an SCT found in an X.509 extension must have been issued for a pre\- +certificate. +.PP +\&\fBSCT_set_source()\fR will not refuse unknown values. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSCT_set_version()\fR returns 1 if the specified version is supported, 0 otherwise. +.PP +\&\fBSCT_set_log_entry_type()\fR returns 1 if the specified log entry type is supported, 0 otherwise. +.PP +\&\fBSCT_set0_log_id()\fR and \fBSCT_set1_log_id\fR return 1 if the specified LogID is a +valid SHA\-256 hash, 0 otherwise. Additionally, \fBSCT_set1_log_id\fR returns 0 if +malloc fails. +.PP +\&\fBSCT_set_signature_nid\fR returns 1 if the specified NID is supported, 0 otherwise. +.PP +\&\fBSCT_set1_extensions\fR and \fBSCT_set1_signature\fR return 1 if the supplied buffer +is copied successfully, 0 otherwise (i.e. if malloc fails). +.PP +\&\fBSCT_set_source\fR returns 1 on success, 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7), +\&\fBSCT_validate\fR\|(3), +\&\fBOBJ_nid2obj\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SCT_print.3 b/static/netbsd/man3/SCT_print.3 new file mode 100644 index 00000000..59129c99 --- /dev/null +++ b/static/netbsd/man3/SCT_print.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: SCT_print.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SCT_print 3" +.TH SCT_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SCT_print, SCT_LIST_print, SCT_validation_status_string \- +Prints Signed Certificate Timestamps in a human\-readable way +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs); +\& void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent, +\& const char *separator, const CTLOG_STORE *logs); +\& const char *SCT_validation_status_string(const SCT *sct); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSCT_print()\fR prints a single Signed Certificate Timestamp (SCT) to a \fBBIO\fR in +a human\-readable format. \fBSCT_LIST_print()\fR prints an entire list of SCTs in a +similar way. A separator can be specified to delimit each SCT in the output. +.PP +The output can be indented by a specified number of spaces. If a \fBCTLOG_STORE\fR +is provided, it will be used to print the description of the CT log that issued +each SCT (if that log is in the CTLOG_STORE). Alternatively, NULL can be passed +as the CTLOG_STORE parameter to disable this feature. +.PP +\&\fBSCT_validation_status_string()\fR will return the validation status of an SCT as +a human\-readable string. Call \fBSCT_validate()\fR or \fBSCT_LIST_validate()\fR +beforehand in order to set the validation status of an SCT first. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSCT_validation_status_string()\fR returns a NUL\-terminated string representing +the validation status of an \fBSCT\fR object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7), +\&\fBbio\fR\|(7), +\&\fBCTLOG_STORE_new\fR\|(3), +\&\fBSCT_validate\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SCT_validate.3 b/static/netbsd/man3/SCT_validate.3 new file mode 100644 index 00000000..82fc83a5 --- /dev/null +++ b/static/netbsd/man3/SCT_validate.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: SCT_validate.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SCT_validate 3" +.TH SCT_validate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SCT_validate, SCT_LIST_validate, SCT_get_validation_status \- +checks Signed Certificate Timestamps (SCTs) are valid +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef enum { +\& SCT_VALIDATION_STATUS_NOT_SET, +\& SCT_VALIDATION_STATUS_UNKNOWN_LOG, +\& SCT_VALIDATION_STATUS_VALID, +\& SCT_VALIDATION_STATUS_INVALID, +\& SCT_VALIDATION_STATUS_UNVERIFIED, +\& SCT_VALIDATION_STATUS_UNKNOWN_VERSION +\& } sct_validation_status_t; +\& +\& int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx); +\& int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx); +\& sct_validation_status_t SCT_get_validation_status(const SCT *sct); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSCT_validate()\fR will check that an SCT is valid and verify its signature. +\&\fBSCT_LIST_validate()\fR performs the same checks on an entire stack of SCTs. +The result of the validation checks can be obtained by passing the SCT to +\&\fBSCT_get_validation_status()\fR. +.PP +A CT_POLICY_EVAL_CTX must be provided that specifies: +.IP \(bu 2 +The certificate the SCT was issued for. +.Sp +Failure to provide the certificate will result in the validation status being +SCT_VALIDATION_STATUS_UNVERIFIED. +.IP \(bu 2 +The issuer of that certificate. +.Sp +This is only required if the SCT was issued for a pre\-certificate +(see RFC 6962). If it is required but not provided, the validation status will +be SCT_VALIDATION_STATUS_UNVERIFIED. +.IP \(bu 2 +A CTLOG_STORE that contains the CT log that issued this SCT. +.Sp +If the SCT was issued by a log that is not in this CTLOG_STORE, the validation +status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. +.PP +If the SCT is of an unsupported version (only v1 is currently supported), the +validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION. +.PP +If the SCT\*(Aqs signature is incorrect, its timestamp is in the future (relative to +the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation +status will be SCT_VALIDATION_STATUS_INVALID. +.PP +If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID. +.SH NOTES +.IX Header "NOTES" +A return value of 0 from \fBSCT_LIST_validate()\fR should not be interpreted as a +failure. At a minimum, only one valid SCT may provide sufficient confidence +that a certificate has been publicly logged. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSCT_validate()\fR returns a negative integer if an internal error occurs, 0 if the +SCT fails validation, or 1 if the SCT passes validation. +.PP +\&\fBSCT_LIST_validate()\fR returns a negative integer if an internal error occurs, 0 +if any of SCTs fails validation, or 1 if they all pass validation. +.PP +\&\fBSCT_get_validation_status()\fR returns the validation status of the SCT. +If \fBSCT_validate()\fR or \fBSCT_LIST_validate()\fR have not been passed that SCT, the +returned value will be SCT_VALIDATION_STATUS_NOT_SET. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SHA256_Init.3 b/static/netbsd/man3/SHA256_Init.3 new file mode 100644 index 00000000..3b29359b --- /dev/null +++ b/static/netbsd/man3/SHA256_Init.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: SHA256_Init.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SHA256_Init 3" +.TH SHA256_Init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, +SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, +SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, +SHA512_Final \- Secure Hash Algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned char *SHA1(const unsigned char *data, size_t count, unsigned char *md_buf); +\& unsigned char *SHA224(const unsigned char *data, size_t count, unsigned char *md_buf); +\& unsigned char *SHA256(const unsigned char *data, size_t count, unsigned char *md_buf); +\& unsigned char *SHA384(const unsigned char *data, size_t count, unsigned char *md_buf); +\& unsigned char *SHA512(const unsigned char *data, size_t count, unsigned char *md_buf); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& int SHA1_Init(SHA_CTX *c); +\& int SHA1_Update(SHA_CTX *c, const void *data, size_t len); +\& int SHA1_Final(unsigned char *md, SHA_CTX *c); +\& +\& int SHA224_Init(SHA256_CTX *c); +\& int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); +\& int SHA224_Final(unsigned char *md, SHA256_CTX *c); +\& +\& int SHA256_Init(SHA256_CTX *c); +\& int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); +\& int SHA256_Final(unsigned char *md, SHA256_CTX *c); +\& +\& int SHA384_Init(SHA512_CTX *c); +\& int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); +\& int SHA384_Final(unsigned char *md, SHA512_CTX *c); +\& +\& int SHA512_Init(SHA512_CTX *c); +\& int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); +\& int SHA512_Final(unsigned char *md, SHA512_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page +except for \fBSHA1()\fR, \fBSHA224()\fR, \fBSHA256()\fR, \fBSHA384()\fR and \fBSHA512()\fR are deprecated. +Applications should instead use \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3), or the quick one\-shot function \fBEVP_Q_digest\fR\|(3). +\&\fBSHA1()\fR, \fBSHA224()\fR, \fBSHA256()\fR, \fBSHA384()\fR, and \fBSHA256()\fR +can continue to be used. They can also be replaced by, e.g., +.PP +.Vb 1 +\& (EVP_Q_digest(d, n, md, NULL, NULL, "SHA256", NULL) ? md : NULL) +.Ve +.PP +SHA\-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. +.PP +\&\fBSHA1()\fR computes the SHA\-1 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If \fBmd\fR is NULL, the digest +is placed in a static array. Note: setting \fBmd\fR to NULL is \fBnot thread safe\fR. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBSHA1_Init()\fR initializes a \fBSHA_CTX\fR structure. +.PP +\&\fBSHA1_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fBSHA1_Final()\fR places the message digest in \fBmd\fR, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the \fBSHA_CTX\fR. +.PP +The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the +same way as for the SHA1 functions. Note that SHA224 and SHA256 use a +\&\fBSHA256_CTX\fR object instead of \fBSHA_CTX\fR. SHA384 and SHA512 use \fBSHA512_CTX\fR. +The buffer \fBmd\fR must have space for the output from the SHA variant being used +(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and +SHA512_DIGEST_LENGTH). Also note that, as for the \fBSHA1()\fR function above, the +\&\fBSHA224()\fR, \fBSHA256()\fR, \fBSHA384()\fR and \fBSHA512()\fR functions are not thread safe if +\&\fBmd\fR is NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSHA1()\fR, \fBSHA224()\fR, \fBSHA256()\fR, \fBSHA384()\fR and \fBSHA512()\fR return a pointer to the hash +value. +.PP +\&\fBSHA1_Init()\fR, \fBSHA1_Update()\fR and \fBSHA1_Final()\fR and equivalent SHA224, SHA256, +SHA384 and SHA512 functions return 1 for success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +US Federal Information Processing Standard FIPS PUB 180\-4 (Secure Hash +Standard), +ANSI X9.30 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_Q_digest\fR\|(3), +\&\fBEVP_DigestInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions except SHA*() were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SHA3_Selftest.3 b/static/netbsd/man3/SHA3_Selftest.3 new file mode 100644 index 00000000..ca5df8ae --- /dev/null +++ b/static/netbsd/man3/SHA3_Selftest.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: SHA3_Selftest.3,v 1.1 2017/11/30 16:00:48 wiz Exp $ +.\" +.\" Copyright (c) 2015 Taylor R. Campbell +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 14, 2015 +.Dt SHA3_SELFTEST 3 +.Os +.Sh NAME +.Nm SHA3_Selftest +.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.Sh SYNOPSIS +.In sha3.h +.Ft int +.Fn SHA3_Selftest "void" +.Sh DESCRIPTION +The +.Nm +function automatically tests a number of SHA-3 computations on fixed +inputs with with known outputs to make sure the +.Xr sha3 3 +library is not catastrophically broken. +Applications should call +.Fn SHA3_Selftest +and confirm that it succeeded before using the +.Xr sha3 3 , +.Xr SHAKE 3 , +or +.Xr keccak 3 +functions. +.Pp +.Fn SHA3_Selftest +returns 0 if successful, or -1 if the self-test failed. +.Pp +The +.Fn SHA3_Selftest +function costs a few hundred thousand cycles on most CPUs, since it +involves a little over a hundred calls to the Keccak permutation, +which usually take one or two thousand cycles each. +.Sh SEE ALSO +.Xr keccak 3 , +.Xr sha3 3 , +.Xr SHAKE 3 +.Sh STANDARDS +.Rs +.%A National Institute of Standards and Technology +.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.%O FIPS PUB 202 +.%D August 2015 +.Re +.Sh AUTHORS +.An Taylor R Campbell Aq campbell+sha3@mumble.net diff --git a/static/netbsd/man3/SHAKE.3 b/static/netbsd/man3/SHAKE.3 new file mode 100644 index 00000000..694b58b6 --- /dev/null +++ b/static/netbsd/man3/SHAKE.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: SHAKE.3,v 1.1 2017/11/30 16:00:48 wiz Exp $ +.\" +.\" Copyright (c) 2015 Taylor R. Campbell +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 14, 2015 +.Dt SHAKE 3 +.Os +.Sh NAME +.Nm SHAKE +.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.Sh SYNOPSIS +.In sha3.h +.Ft void +.Fn SHAKE128_Init "SHAKE128_CTX *ctx" +.Ft void +.Fn SHAKE128_Update "SHAKE128_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHAKE128_Final "uint8_t *output[]" "size_t outlen" "SHAKE128_CTX *ctx" +.Ft void +.Fn SHAKE256_Init "SHAKE256_CTX *ctx" +.Ft void +.Fn SHAKE256_Update "SHAKE256_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHAKE256_Final "uint8_t *output[]" "size_t outlen" "SHAKE256_CTX *ctx" +.Sh DESCRIPTION +The +.Nm +functions implement the extendable-output functions of the NIST SHA-3 +standard, FIPS PUB 202. +The +.Nm +functions absorb an arbitrary-length message m and yield an +arbitrary-length output SHAKE128(m) or SHAKE256(m), truncated to a +specified number of octets. +.Pp +Before using the +.Nm +functions, applications should first call +.Xr SHA3_Selftest 3 +and confirm that it succeeded. +.Pp +Only the +.Nm SHAKE128 +functions are specified in detail; the +.Nm SHAKE256 +functions are analogous. +.Pp +The caller must allocate memory for a +.Vt SHAKE128_CTX +object to hold the state of a SHAKE128 computation over a message. +.Vt SHAKE128_CTX +objects may be copied or relocated in memory. +.Bl -tag -width abcd +.It Fn SHAKE128_Init "ctx" +Initialize a SHAKE128 context. +Must be done before any other operations on +.Fa ctx . +.It Fn SHAKE128_Update "ctx" "data" "len" +Append +.Fa len +octets at +.Fa data +to the message. +.It Fn SHAKE128_Final "output" "outlen" "ctx" +Store at +.Fa output +the first +.Fa outlen +octets of the SHAKE128 output for the message obtained by concatenating +all prior inputs to +.Fn SHAKE128_Update +on +.Fa ctx . +.Pp +Subsequent use of +.Fa ctx +is not allowed, unless it is reinitialized with +.Fn SHAKE128_Init . +.El +.Sh SEE ALSO +.Xr keccak 3 , +.Xr sha3 3 , +.Xr SHA3_Selftest 3 +.Sh STANDARDS +.Rs +.%A National Institute of Standards and Technology +.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.%O FIPS PUB 202 +.%D August 2015 +.Re +.Sh AUTHORS +.An Taylor R Campbell Aq campbell+sha3@mumble.net diff --git a/static/netbsd/man3/SMIME_read_ASN1.3 b/static/netbsd/man3/SMIME_read_ASN1.3 new file mode 100644 index 00000000..bf3709c1 --- /dev/null +++ b/static/netbsd/man3/SMIME_read_ASN1.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: SMIME_read_ASN1.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_read_ASN1 3" +.TH SMIME_read_ASN1 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_read_ASN1_ex, SMIME_read_ASN1 +\&\- parse S/MIME message +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_VALUE *SMIME_read_ASN1_ex(BIO *in, int flags, BIO **bcont, +\& const ASN1_ITEM *it, ASN1_VALUE **x, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& ASN1_VALUE *SMIME_read_ASN1(BIO *in, BIO **bcont, const ASN1_ITEM *it); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_read_ASN1_ex()\fR parses a message in S/MIME format. +.PP +\&\fIin\fR is a BIO to read the message from. +If the \fIflags\fR argument contains \fBCMS_BINARY\fR then the input is assumed to be +in binary format and is not translated to canonical form. +If in addition \fBSMIME_ASCIICRLF\fR is set then the binary input is assumed +to be followed by \fBCR\fR and \fBLF\fR characters, else only by an \fBLF\fR character. +\&\fIx\fR can be used to optionally supply +a previously created \fIit\fR ASN1_VALUE object (such as CMS_ContentInfo or PKCS7), +it can be set to NULL. Valid values that can be used by ASN.1 structure \fIit\fR +are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo). Any algorithm +fetches that occur during the operation will use the \fBOSSL_LIB_CTX\fR supplied in +the \fIlibctx\fR parameter, and use the property query string \fIpropq\fR See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further details about algorithm fetching. +.PP +If cleartext signing is used then the content is saved in a memory bio which is +written to \fI*bcont\fR, otherwise \fI*bcont\fR is set to NULL. +.PP +The parsed ASN1_VALUE structure is returned or NULL if an error occurred. +.PP +\&\fBSMIME_read_ASN1()\fR is similar to \fBSMIME_read_ASN1_ex()\fR but sets the value of \fIx\fR +to NULL and the value of \fIflags\fR to 0. +.SH NOTES +.IX Header "NOTES" +The higher level functions \fBSMIME_read_CMS_ex\fR\|(3) and +\&\fBSMIME_read_PKCS7_ex\fR\|(3) should be used instead of \fBSMIME_read_ASN1_ex()\fR. +.PP +To support future functionality if \fIbcont\fR is not NULL \fI*bcont\fR should be +initialized to NULL. +.SH BUGS +.IX Header "BUGS" +The MIME parser used by \fBSMIME_read_ASN1_ex()\fR is somewhat primitive. While it will +handle most S/MIME messages more complex compound formats may not work. +.PP +The use of a memory BIO to hold the signed content limits the size of message +which can be processed due to memory restraints: a streaming single pass option +should be available. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_read_ASN1_ex()\fR and \fBSMIME_read_ASN1()\fR return a valid \fBASN1_VALUE\fR +structure or \fBNULL\fR if an error occurred. The error can be obtained from +\&\fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBSMIME_read_CMS_ex\fR\|(3), +\&\fBSMIME_read_PKCS7_ex\fR\|(3), +\&\fBSMIME_write_ASN1\fR\|(3), +\&\fBSMIME_write_ASN1_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBSMIME_read_ASN1_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SMIME_read_CMS.3 b/static/netbsd/man3/SMIME_read_CMS.3 new file mode 100644 index 00000000..e9f08be4 --- /dev/null +++ b/static/netbsd/man3/SMIME_read_CMS.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: SMIME_read_CMS.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_read_CMS 3" +.TH SMIME_read_CMS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_read_CMS_ex, SMIME_read_CMS \- parse S/MIME message +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *SMIME_read_CMS_ex(BIO *bio, int flags, BIO **bcont, +\& CMS_ContentInfo **cms); +\& CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_read_CMS()\fR parses a message in S/MIME format. +.PP +\&\fBin\fR is a BIO to read the message from. +.PP +If cleartext signing is used then the content is saved in a memory bio which is +written to \fB*bcont\fR, otherwise \fB*bcont\fR is set to NULL. +.PP +The parsed CMS_ContentInfo structure is returned or NULL if an +error occurred. +.PP +\&\fBSMIME_read_CMS_ex()\fR is similar to \fBSMIME_read_CMS()\fR but optionally a previously +created \fIcms\fR CMS_ContentInfo object can be supplied as well as some \fIflags\fR. +To create a \fIcms\fR object use \fBCMS_ContentInfo_new_ex\fR\|(3). +If the \fIflags\fR argument contains \fBCMS_BINARY\fR then the input is assumed to be +in binary format and is not translated to canonical form. +If in addition \fBSMIME_ASCIICRLF\fR is set then the binary input is assumed +to be followed by \fBCR\fR and \fBLF\fR characters, else only by an \fBLF\fR character. +If \fIflags\fR is 0 and \fIcms\fR is NULL then it is identical to \fBSMIME_read_CMS()\fR. +.SH NOTES +.IX Header "NOTES" +If \fB*bcont\fR is not NULL then the message is clear text signed. \fB*bcont\fR can +then be passed to \fBCMS_verify()\fR with the \fBCMS_DETACHED\fR flag set. +.PP +Otherwise the type of the returned structure can be determined +using \fBCMS_get0_type()\fR. +.PP +To support future functionality if \fBbcont\fR is not NULL \fB*bcont\fR should be +initialized to NULL. For example: +.PP +.Vb 2 +\& BIO *cont = NULL; +\& CMS_ContentInfo *cms; +\& +\& cms = SMIME_read_CMS(in, &cont); +.Ve +.SH BUGS +.IX Header "BUGS" +The MIME parser used by \fBSMIME_read_CMS()\fR is somewhat primitive. While it will +handle most S/MIME messages more complex compound formats may not work. +.PP +The parser assumes that the CMS_ContentInfo structure is always base64 encoded +and will not handle the case where it is in binary format or uses quoted +printable format. +.PP +The use of a memory BIO to hold the signed content limits the size of message +which can be processed due to memory restraints: a streaming single pass option +should be available. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_read_CMS_ex()\fR and \fBSMIME_read_CMS()\fR return a valid \fBCMS_ContentInfo\fR +structure or \fBNULL\fR if an error occurred. The error can be obtained from +\&\fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBCMS_sign\fR\|(3), +\&\fBCMS_verify\fR\|(3), +\&\fBCMS_encrypt\fR\|(3), +\&\fBCMS_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBSMIME_read_CMS_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SMIME_read_PKCS7.3 b/static/netbsd/man3/SMIME_read_PKCS7.3 new file mode 100644 index 00000000..bf18fc3e --- /dev/null +++ b/static/netbsd/man3/SMIME_read_PKCS7.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: SMIME_read_PKCS7.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_read_PKCS7 3" +.TH SMIME_read_PKCS7 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_read_PKCS7_ex, SMIME_read_PKCS7 \- parse S/MIME message +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& PKCS7 *SMIME_read_PKCS7_ex(BIO *bio, BIO **bcont, PKCS7 **p7); +\& PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_read_PKCS7()\fR parses a message in S/MIME format. +.PP +\&\fBin\fR is a BIO to read the message from. +.PP +If cleartext signing is used then the content is saved in +a memory bio which is written to \fB*bcont\fR, otherwise +\&\fB*bcont\fR is set to \fBNULL\fR. +.PP +The parsed PKCS#7 structure is returned or \fBNULL\fR if an +error occurred. +.PP +\&\fBSMIME_read_PKCS7_ex()\fR is similar to \fBSMIME_read_PKCS7()\fR but can optionally supply +a previously created \fIp7\fR PKCS#7 object. If \fIp7\fR is NULL then it is identical +to \fBSMIME_read_PKCS7()\fR. +To create a \fIp7\fR object use \fBPKCS7_new_ex\fR\|(3). +.SH NOTES +.IX Header "NOTES" +If \fB*bcont\fR is not \fBNULL\fR then the message is clear text +signed. \fB*bcont\fR can then be passed to \fBPKCS7_verify()\fR with +the \fBPKCS7_DETACHED\fR flag set. +.PP +Otherwise the type of the returned structure can be determined +using \fBPKCS7_type_is_enveloped()\fR, etc. +.PP +To support future functionality if \fBbcont\fR is not \fBNULL\fR +\&\fB*bcont\fR should be initialized to \fBNULL\fR. For example: +.PP +.Vb 2 +\& BIO *cont = NULL; +\& PKCS7 *p7; +\& +\& p7 = SMIME_read_PKCS7(in, &cont); +.Ve +.SH BUGS +.IX Header "BUGS" +The MIME parser used by \fBSMIME_read_PKCS7()\fR is somewhat primitive. +While it will handle most S/MIME messages more complex compound +formats may not work. +.PP +The parser assumes that the PKCS7 structure is always base64 +encoded and will not handle the case where it is in binary format +or uses quoted printable format. +.PP +The use of a memory BIO to hold the signed content limits the size +of message which can be processed due to memory restraints: a +streaming single pass option should be available. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_read_PKCS7_ex()\fR and \fBSMIME_read_PKCS7()\fR return a valid \fBPKCS7\fR structure +or \fBNULL\fR if an error occurred. The error can be obtained from \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBSMIME_read_PKCS7\fR\|(3), \fBPKCS7_sign\fR\|(3), +\&\fBPKCS7_verify\fR\|(3), \fBPKCS7_encrypt\fR\|(3) +\&\fBPKCS7_decrypt\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBSMIME_read_PKCS7_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SMIME_write_ASN1.3 b/static/netbsd/man3/SMIME_write_ASN1.3 new file mode 100644 index 00000000..cf95f196 --- /dev/null +++ b/static/netbsd/man3/SMIME_write_ASN1.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: SMIME_write_ASN1.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_write_ASN1 3" +.TH SMIME_write_ASN1 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_write_ASN1_ex, SMIME_write_ASN1 +\&\- convert structure to S/MIME format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SMIME_write_ASN1_ex(BIO *out, ASN1_VALUE *val, BIO *data, int flags, +\& int ctype_nid, int econt_nid, +\& STACK_OF(X509_ALGOR) *mdalgs, const ASN1_ITEM *it, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& +\& int SMIME_write_ASN1(BIO *out, +\& ASN1_VALUE *val, BIO *data, int flags, int ctype_nid, int econt_nid, +\& STACK_OF(X509_ALGOR) *mdalgs, const ASN1_ITEM *it); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_write_ASN1_ex()\fR adds the appropriate MIME headers to an object +structure to produce an S/MIME message. +.PP +\&\fIout\fR is the BIO to write the data to. \fIvalue\fR is the appropriate ASN1_VALUE +structure (either CMS_ContentInfo or PKCS7). If streaming is enabled then the +content must be supplied via \fIdata\fR. +\&\fIflags\fR is an optional set of flags. \fIctype_nid\fR is the NID of the content +type, \fIecont_nid\fR is the NID of the embedded content type and \fImdalgs\fR is a +list of signed data digestAlgorithms. Valid values that can be used by the +ASN.1 structure \fIit\fR are ASN1_ITEM_rptr(PKCS7) or ASN1_ITEM_rptr(CMS_ContentInfo). +The library context \fIlibctx\fR and the property query \fIpropq\fR are used when +retrieving algorithms from providers. +.SH NOTES +.IX Header "NOTES" +The higher level functions \fBSMIME_write_CMS\fR\|(3) and +\&\fBSMIME_write_PKCS7\fR\|(3) should be used instead of \fBSMIME_write_ASN1()\fR. +.PP +The following flags can be passed in the \fBflags\fR parameter. +.PP +If \fBCMS_DETACHED\fR is set then cleartext signing will be used, this option only +makes sense for SignedData where \fBCMS_DETACHED\fR is also set when the \fBsign()\fR +method is called. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are added to +the content, this only makes sense if \fBCMS_DETACHED\fR is also set. +.PP +If the \fBCMS_STREAM\fR flag is set streaming is performed. This flag should only +be set if \fBCMS_STREAM\fR was also set in the previous call to a CMS_ContentInfo +or PKCS7 creation function. +.PP +If cleartext signing is being used and \fBCMS_STREAM\fR not set then the data must +be read twice: once to compute the signature in sign method and once to output +the S/MIME message. +.PP +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_write_ASN1_ex()\fR and \fBSMIME_write_ASN1()\fR return 1 for success or +0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBSMIME_write_CMS\fR\|(3), +\&\fBSMIME_write_PKCS7\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SMIME_write_CMS.3 b/static/netbsd/man3/SMIME_write_CMS.3 new file mode 100644 index 00000000..e3b5c3ca --- /dev/null +++ b/static/netbsd/man3/SMIME_write_CMS.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: SMIME_write_CMS.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_write_CMS 3" +.TH SMIME_write_CMS 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_write_CMS \- convert CMS structure to S/MIME format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_write_CMS()\fR adds the appropriate MIME headers to a CMS +structure to produce an S/MIME message. +.PP +\&\fBout\fR is the BIO to write the data to. \fBcms\fR is the appropriate +\&\fBCMS_ContentInfo\fR structure. If streaming is enabled then the content must be +supplied in the \fBdata\fR argument. \fBflags\fR is an optional set of flags. +.SH NOTES +.IX Header "NOTES" +The following flags can be passed in the \fBflags\fR parameter. +.PP +If \fBCMS_DETACHED\fR is set then cleartext signing will be used, this option only +makes sense for SignedData where \fBCMS_DETACHED\fR is also set when \fBCMS_sign()\fR is +called. +.PP +If the \fBCMS_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR are added to +the content, this only makes sense if \fBCMS_DETACHED\fR is also set. +.PP +If the \fBCMS_STREAM\fR flag is set streaming is performed. This flag should only +be set if \fBCMS_STREAM\fR was also set in the previous call to a CMS_ContentInfo +creation function. +.PP +If cleartext signing is being used and \fBCMS_STREAM\fR not set then the data must +be read twice: once to compute the signature in \fBCMS_sign()\fR and once to output +the S/MIME message. +.PP +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. +.SH BUGS +.IX Header "BUGS" +\&\fBSMIME_write_CMS()\fR always base64 encodes CMS structures, there should be an +option to disable this. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_write_CMS()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_verify\fR\|(3), \fBCMS_encrypt\fR\|(3) +\&\fBCMS_decrypt\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SMIME_write_PKCS7.3 b/static/netbsd/man3/SMIME_write_PKCS7.3 new file mode 100644 index 00000000..b36e772b --- /dev/null +++ b/static/netbsd/man3/SMIME_write_PKCS7.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: SMIME_write_PKCS7.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SMIME_write_PKCS7 3" +.TH SMIME_write_PKCS7 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SMIME_write_PKCS7 \- convert PKCS#7 structure to S/MIME format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSMIME_write_PKCS7()\fR adds the appropriate MIME headers to a PKCS#7 +structure to produce an S/MIME message. +.PP +\&\fBout\fR is the BIO to write the data to. \fBp7\fR is the appropriate \fBPKCS7\fR +structure. If streaming is enabled then the content must be supplied in the +\&\fBdata\fR argument. \fBflags\fR is an optional set of flags. +.SH NOTES +.IX Header "NOTES" +The following flags can be passed in the \fBflags\fR parameter. +.PP +If \fBPKCS7_DETACHED\fR is set then cleartext signing will be used, +this option only makes sense for signedData where \fBPKCS7_DETACHED\fR +is also set when \fBPKCS7_sign()\fR is also called. +.PP +If the \fBPKCS7_TEXT\fR flag is set MIME headers for type \fBtext/plain\fR +are added to the content, this only makes sense if \fBPKCS7_DETACHED\fR +is also set. +.PP +If the \fBPKCS7_STREAM\fR flag is set streaming is performed. This flag should +only be set if \fBPKCS7_STREAM\fR was also set in the previous call to +\&\fBPKCS7_sign()\fR or \fBPKCS7_encrypt()\fR. +.PP +If cleartext signing is being used and \fBPKCS7_STREAM\fR not set then +the data must be read twice: once to compute the signature in \fBPKCS7_sign()\fR +and once to output the S/MIME message. +.PP +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. +.SH BUGS +.IX Header "BUGS" +\&\fBSMIME_write_PKCS7()\fR always base64 encodes PKCS#7 structures, there +should be an option to disable this. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSMIME_write_PKCS7()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_sign\fR\|(3), +\&\fBPKCS7_verify\fR\|(3), \fBPKCS7_encrypt\fR\|(3) +\&\fBPKCS7_decrypt\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SQLITE_ACCESS_EXISTS.3 b/static/netbsd/man3/SQLITE_ACCESS_EXISTS.3 new file mode 100644 index 00000000..c79f7299 --- /dev/null +++ b/static/netbsd/man3/SQLITE_ACCESS_EXISTS.3 @@ -0,0 +1,40 @@ +.Dd January 24, 2024 +.Dt SQLITE_ACCESS_EXISTS 3 +.Os +.Sh NAME +.Nm SQLITE_ACCESS_EXISTS , +.Nm SQLITE_ACCESS_READWRITE , +.Nm SQLITE_ACCESS_READ +.Nd flags for the xAccess VFS method +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_ACCESS_EXISTS +.Fd #define SQLITE_ACCESS_READWRITE +.Fd #define SQLITE_ACCESS_READ +.Sh DESCRIPTION +These integer constants can be used as the third parameter to the xAccess +method of an sqlite3_vfs object. +They determine what kind of permissions the xAccess method is looking +for. +With SQLITE_ACCESS_EXISTS, the xAccess method simply checks whether +the file exists. +With SQLITE_ACCESS_READWRITE, the xAccess method checks whether the +named directory is both readable and writable (in other words, if files +can be added, removed, and renamed within the directory). +The SQLITE_ACCESS_READWRITE constant is currently used only by the +temp_store_directory pragma, though this +could change in a future release of SQLite. +With SQLITE_ACCESS_READ, the xAccess method checks whether the file +is readable. +The SQLITE_ACCESS_READ constant is currently unused, though it might +be used in a future release of SQLite. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1505. +.Bd -literal +#define SQLITE_ACCESS_EXISTS 0 +#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */ +#define SQLITE_ACCESS_READ 2 /* Unused */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/SQLITE_CHANGESETAPPLY_NOSAVEPOINT.3 b/static/netbsd/man3/SQLITE_CHANGESETAPPLY_NOSAVEPOINT.3 new file mode 100644 index 00000000..c0ab09b4 --- /dev/null +++ b/static/netbsd/man3/SQLITE_CHANGESETAPPLY_NOSAVEPOINT.3 @@ -0,0 +1,65 @@ +.Dd January 24, 2024 +.Dt SQLITE_CHANGESETAPPLY_NOSAVEPOINT 3 +.Os +.Sh NAME +.Nm SQLITE_CHANGESETAPPLY_NOSAVEPOINT , +.Nm SQLITE_CHANGESETAPPLY_INVERT , +.Nm SQLITE_CHANGESETAPPLY_IGNORENOOP , +.Nm SQLITE_CHANGESETAPPLY_FKNOACTION +.Nd flags for sqlite3changeset_apply_v2 +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT +.Fd #define SQLITE_CHANGESETAPPLY_INVERT +.Fd #define SQLITE_CHANGESETAPPLY_IGNORENOOP +.Fd #define SQLITE_CHANGESETAPPLY_FKNOACTION +.Sh DESCRIPTION +The following flags may passed via the 9th parameter to sqlite3changeset_apply_v2 +and sqlite3changeset_apply_v2_strm: +.Bl -tag -width Ds +.It SQLITE_CHANGESETAPPLY_NOSAVEPOINT +Usually, the sessions module encloses all operations performed by a +single call to apply_v2() or apply_v2_strm() in a SAVEPOINT. +The SAVEPOINT is committed if the changeset or patchset is successfully +applied, or rolled back if an error occurs. +Specifying this flag causes the sessions module to omit this savepoint. +In this case, if the caller has an open transaction or savepoint when +apply_v2() is called, it may revert the partially applied changeset +by rolling it back. +.It SQLITE_CHANGESETAPPLY_INVERT +Invert the changeset before applying it. +This is equivalent to inverting a changeset using sqlite3changeset_invert() +before applying it. +It is an error to specify this flag with a patchset. +.It SQLITE_CHANGESETAPPLY_IGNORENOOP +Do not invoke the conflict handler callback for any changes that would +not actually modify the database even if they were applied. +Specifically, this means that the conflict handler is not invoked for: +.Bl -bullet +.It +a delete change if the row being deleted cannot be found, +.It +an update change if the modified fields are already set to their new +values in the conflicting row, or +.It +an insert change if all fields of the conflicting row match the row +being inserted. +.El +.Pp +.It SQLITE_CHANGESETAPPLY_FKNOACTION +If this flag it set, then all foreign key constraints in the target +database behave as if they were declared with "ON UPDATE NO ACTION +ON DELETE NO ACTION", even if they are actually CASCADE, RESTRICT, +SET NULL or SET DEFAULT. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12211. +.Bd -literal +#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001 +#define SQLITE_CHANGESETAPPLY_INVERT 0x0002 +#define SQLITE_CHANGESETAPPLY_IGNORENOOP 0x0004 +#define SQLITE_CHANGESETAPPLY_FKNOACTION 0x0008 +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_apply_strm 3 diff --git a/static/netbsd/man3/SQLITE_CHANGESETSTART_INVERT.3 b/static/netbsd/man3/SQLITE_CHANGESETSTART_INVERT.3 new file mode 100644 index 00000000..086d25e1 --- /dev/null +++ b/static/netbsd/man3/SQLITE_CHANGESETSTART_INVERT.3 @@ -0,0 +1,26 @@ +.Dd January 24, 2024 +.Dt SQLITE_CHANGESETSTART_INVERT 3 +.Os +.Sh NAME +.Nm SQLITE_CHANGESETSTART_INVERT +.Nd flags for sqlite3changeset_start_v2 +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CHANGESETSTART_INVERT +.Sh DESCRIPTION +The following flags may passed via the 4th parameter to sqlite3changeset_start_v2 +and sqlite3changeset_start_v2_strm: +.It SQLITE_CHANGESETAPPLY_INVERT +Invert the changeset while iterating through it. +This is equivalent to inverting a changeset using sqlite3changeset_invert() +before applying it. +It is an error to specify this flag with a patchset. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11488. +.Bd -literal +#define SQLITE_CHANGESETSTART_INVERT 0x0002 +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply_strm 3 , +.Xr sqlite3changeset_start 3 diff --git a/static/netbsd/man3/SQLITE_CHANGESET_DATA.3 b/static/netbsd/man3/SQLITE_CHANGESET_DATA.3 new file mode 100644 index 00000000..87fc7b5c --- /dev/null +++ b/static/netbsd/man3/SQLITE_CHANGESET_DATA.3 @@ -0,0 +1,74 @@ +.Dd January 24, 2024 +.Dt SQLITE_CHANGESET_DATA 3 +.Os +.Sh NAME +.Nm SQLITE_CHANGESET_DATA , +.Nm SQLITE_CHANGESET_NOTFOUND , +.Nm SQLITE_CHANGESET_CONFLICT , +.Nm SQLITE_CHANGESET_CONSTRAINT , +.Nm SQLITE_CHANGESET_FOREIGN_KEY +.Nd constants passed to the conflict handler +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CHANGESET_DATA +.Fd #define SQLITE_CHANGESET_NOTFOUND +.Fd #define SQLITE_CHANGESET_CONFLICT +.Fd #define SQLITE_CHANGESET_CONSTRAINT +.Fd #define SQLITE_CHANGESET_FOREIGN_KEY +.Sh DESCRIPTION +Values that may be passed as the second argument to a conflict-handler. +.Bl -tag -width Ds +.It SQLITE_CHANGESET_DATA +The conflict handler is invoked with CHANGESET_DATA as the second argument +when processing a DELETE or UPDATE change if a row with the required +PRIMARY KEY fields is present in the database, but one or more other +(non primary-key) fields modified by the update do not contain the +expected "before" values. +.Pp +The conflicting row, in this case, is the database row with the matching +primary key. +.It SQLITE_CHANGESET_NOTFOUND +The conflict handler is invoked with CHANGESET_NOTFOUND as the second +argument when processing a DELETE or UPDATE change if a row with the +required PRIMARY KEY fields is not present in the database. +.Pp +There is no conflicting row in this case. +The results of invoking the sqlite3changeset_conflict() API are undefined. +.It SQLITE_CHANGESET_CONFLICT +CHANGESET_CONFLICT is passed as the second argument to the conflict +handler while processing an INSERT change if the operation would result +in duplicate primary key values. +.Pp +The conflicting row in this case is the database row with the matching +primary key. +.It SQLITE_CHANGESET_FOREIGN_KEY +If foreign key handling is enabled, and applying a changeset leaves +the database in a state containing foreign key violations, the conflict +handler is invoked with CHANGESET_FOREIGN_KEY as the second argument +exactly once before the changeset is committed. +If the conflict handler returns CHANGESET_OMIT, the changes, including +those that caused the foreign key constraint violation, are committed. +Or, if it returns CHANGESET_ABORT, the changeset is rolled back. +.Pp +No current or conflicting row information is provided. +The only function it is possible to call on the supplied sqlite3_changeset_iter +handle is sqlite3changeset_fk_conflicts(). +.It SQLITE_CHANGESET_CONSTRAINT +If any other constraint violation occurs while applying a change (i.e. +a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is invoked +with CHANGESET_CONSTRAINT as the second argument. +.Pp +There is no conflicting row in this case. +The results of invoking the sqlite3changeset_conflict() API are undefined. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12256. +.Bd -literal +#define SQLITE_CHANGESET_DATA 1 +#define SQLITE_CHANGESET_NOTFOUND 2 +#define SQLITE_CHANGESET_CONFLICT 3 +#define SQLITE_CHANGESET_CONSTRAINT 4 +#define SQLITE_CHANGESET_FOREIGN_KEY 5 +.Ed diff --git a/static/netbsd/man3/SQLITE_CHANGESET_OMIT.3 b/static/netbsd/man3/SQLITE_CHANGESET_OMIT.3 new file mode 100644 index 00000000..2ba9e9db --- /dev/null +++ b/static/netbsd/man3/SQLITE_CHANGESET_OMIT.3 @@ -0,0 +1,49 @@ +.Dd January 24, 2024 +.Dt SQLITE_CHANGESET_OMIT 3 +.Os +.Sh NAME +.Nm SQLITE_CHANGESET_OMIT , +.Nm SQLITE_CHANGESET_REPLACE , +.Nm SQLITE_CHANGESET_ABORT +.Nd constants returned by the conflict handler +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CHANGESET_OMIT +.Fd #define SQLITE_CHANGESET_REPLACE +.Fd #define SQLITE_CHANGESET_ABORT +.Sh DESCRIPTION +A conflict handler callback must return one of the following three +values. +.Bl -tag -width Ds +.It SQLITE_CHANGESET_OMIT +If a conflict handler returns this value no special action is taken. +The change that caused the conflict is not applied. +The session module continues to the next change in the changeset. +.It SQLITE_CHANGESET_REPLACE +This value may only be returned if the second argument to the conflict +handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. +If this is not the case, any changes applied so far are rolled back +and the call to sqlite3changeset_apply() returns SQLITE_MISUSE. +.Pp +If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict +handler, then the conflicting row is either updated or deleted, depending +on the type of change. +.Pp +If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict +handler, then the conflicting row is removed from the database and +a second attempt to apply the change is made. +If this second attempt fails, the original row is restored to the database +before continuing. +.It SQLITE_CHANGESET_ABORT +If this value is returned, any changes applied so far are rolled back +and the call to sqlite3changeset_apply() returns SQLITE_ABORT. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12317. +.Bd -literal +#define SQLITE_CHANGESET_OMIT 0 +#define SQLITE_CHANGESET_REPLACE 1 +#define SQLITE_CHANGESET_ABORT 2 +.Ed diff --git a/static/netbsd/man3/SQLITE_CHECKPOINT_PASSIVE.3 b/static/netbsd/man3/SQLITE_CHECKPOINT_PASSIVE.3 new file mode 100644 index 00000000..b33153a7 --- /dev/null +++ b/static/netbsd/man3/SQLITE_CHECKPOINT_PASSIVE.3 @@ -0,0 +1,35 @@ +.Dd January 24, 2024 +.Dt SQLITE_CHECKPOINT_PASSIVE 3 +.Os +.Sh NAME +.Nm SQLITE_CHECKPOINT_PASSIVE , +.Nm SQLITE_CHECKPOINT_FULL , +.Nm SQLITE_CHECKPOINT_RESTART , +.Nm SQLITE_CHECKPOINT_TRUNCATE +.Nd checkpoint mode values +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CHECKPOINT_PASSIVE +.Fd #define SQLITE_CHECKPOINT_FULL +.Fd #define SQLITE_CHECKPOINT_RESTART +.Fd #define SQLITE_CHECKPOINT_TRUNCATE +.Sh DESCRIPTION +These constants define all valid values for the "checkpoint mode" passed +as the third parameter to the +.Fn sqlite3_wal_checkpoint_v2 +interface. +See the +.Fn sqlite3_wal_checkpoint_v2 +documentation for details on the meaning of each of these checkpoint +modes. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9706. +.Bd -literal +#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */ +#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */ +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */ +#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_wal_checkpoint_v2 3 diff --git a/static/netbsd/man3/SQLITE_CONFIG_SINGLETHREAD.3 b/static/netbsd/man3/SQLITE_CONFIG_SINGLETHREAD.3 new file mode 100644 index 00000000..27fa9b7c --- /dev/null +++ b/static/netbsd/man3/SQLITE_CONFIG_SINGLETHREAD.3 @@ -0,0 +1,513 @@ +.Dd January 24, 2024 +.Dt SQLITE_CONFIG_SINGLETHREAD 3 +.Os +.Sh NAME +.Nm SQLITE_CONFIG_SINGLETHREAD , +.Nm SQLITE_CONFIG_MULTITHREAD , +.Nm SQLITE_CONFIG_SERIALIZED , +.Nm SQLITE_CONFIG_MALLOC , +.Nm SQLITE_CONFIG_GETMALLOC , +.Nm SQLITE_CONFIG_SCRATCH , +.Nm SQLITE_CONFIG_PAGECACHE , +.Nm SQLITE_CONFIG_HEAP , +.Nm SQLITE_CONFIG_MEMSTATUS , +.Nm SQLITE_CONFIG_MUTEX , +.Nm SQLITE_CONFIG_GETMUTEX , +.Nm SQLITE_CONFIG_LOOKASIDE , +.Nm SQLITE_CONFIG_PCACHE , +.Nm SQLITE_CONFIG_GETPCACHE , +.Nm SQLITE_CONFIG_LOG , +.Nm SQLITE_CONFIG_URI , +.Nm SQLITE_CONFIG_PCACHE2 , +.Nm SQLITE_CONFIG_GETPCACHE2 , +.Nm SQLITE_CONFIG_COVERING_INDEX_SCAN , +.Nm SQLITE_CONFIG_SQLLOG , +.Nm SQLITE_CONFIG_MMAP_SIZE , +.Nm SQLITE_CONFIG_WIN32_HEAPSIZE , +.Nm SQLITE_CONFIG_PCACHE_HDRSZ , +.Nm SQLITE_CONFIG_PMASZ , +.Nm SQLITE_CONFIG_STMTJRNL_SPILL , +.Nm SQLITE_CONFIG_SMALL_MALLOC , +.Nm SQLITE_CONFIG_SORTERREF_SIZE , +.Nm SQLITE_CONFIG_MEMDB_MAXSIZE +.Nd configuration options +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CONFIG_SINGLETHREAD +.Fd #define SQLITE_CONFIG_MULTITHREAD +.Fd #define SQLITE_CONFIG_SERIALIZED +.Fd #define SQLITE_CONFIG_MALLOC +.Fd #define SQLITE_CONFIG_GETMALLOC +.Fd #define SQLITE_CONFIG_SCRATCH +.Fd #define SQLITE_CONFIG_PAGECACHE +.Fd #define SQLITE_CONFIG_HEAP +.Fd #define SQLITE_CONFIG_MEMSTATUS +.Fd #define SQLITE_CONFIG_MUTEX +.Fd #define SQLITE_CONFIG_GETMUTEX +.Fd #define SQLITE_CONFIG_LOOKASIDE +.Fd #define SQLITE_CONFIG_PCACHE +.Fd #define SQLITE_CONFIG_GETPCACHE +.Fd #define SQLITE_CONFIG_LOG +.Fd #define SQLITE_CONFIG_URI +.Fd #define SQLITE_CONFIG_PCACHE2 +.Fd #define SQLITE_CONFIG_GETPCACHE2 +.Fd #define SQLITE_CONFIG_COVERING_INDEX_SCAN +.Fd #define SQLITE_CONFIG_SQLLOG +.Fd #define SQLITE_CONFIG_MMAP_SIZE +.Fd #define SQLITE_CONFIG_WIN32_HEAPSIZE +.Fd #define SQLITE_CONFIG_PCACHE_HDRSZ +.Fd #define SQLITE_CONFIG_PMASZ +.Fd #define SQLITE_CONFIG_STMTJRNL_SPILL +.Fd #define SQLITE_CONFIG_SMALL_MALLOC +.Fd #define SQLITE_CONFIG_SORTERREF_SIZE +.Fd #define SQLITE_CONFIG_MEMDB_MAXSIZE +.Sh DESCRIPTION +These constants are the available integer configuration options that +can be passed as the first argument to the +.Fn sqlite3_config +interface. +.Pp +Most of the configuration options for sqlite3_config() will only work +if invoked prior to +.Fn sqlite3_initialize +or after +.Fn sqlite3_shutdown . +The few exceptions to this rule are called "anytime configuration options". +Calling +.Fn sqlite3_config +with a first argument that is not an anytime configuration option in +between calls to +.Fn sqlite3_initialize +and +.Fn sqlite3_shutdown +is a no-op that returns SQLITE_MISUSE. +.Pp +The set of anytime configuration options can change (by insertions +and/or deletions) from one release of SQLite to the next. +As of SQLite version 3.42.0, the complete set of anytime configuration +options is: +.Bl -bullet +.It +SQLITE_CONFIG_LOG +.It +SQLITE_CONFIG_PCACHE_HDRSZ +.El +.Pp +New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. +Applications should check the return code from +.Fn sqlite3_config +to make sure that the call worked. +The +.Fn sqlite3_config +interface will return a non-zero error code if a discontinued +or unsupported configuration option is invoked. +.Bl -tag -width Ds +.It SQLITE_CONFIG_SINGLETHREAD +There are no arguments to this option. +This option sets the threading mode to Single-thread. +In other words, it disables all mutexing and puts SQLite into a mode +where it can only be used by a single thread. +If SQLite is compiled with the SQLITE_THREADSAFE=0 +compile-time option then it is not possible to change the threading mode +from its default value of Single-thread and so +.Fn sqlite3_config +will return SQLITE_ERROR if called with the SQLITE_CONFIG_SINGLETHREAD +configuration option. +.It SQLITE_CONFIG_MULTITHREAD +There are no arguments to this option. +This option sets the threading mode to Multi-thread. +In other words, it disables mutexing on database connection +and prepared statement objects. +The application is responsible for serializing access to database connections +and prepared statements. +But other mutexes are enabled so that SQLite will be safe to use in +a multi-threaded environment as long as no two threads attempt to use +the same database connection at the same time. +If SQLite is compiled with the SQLITE_THREADSAFE=0 +compile-time option then it is not possible to set the Multi-thread +threading mode and +.Fn sqlite3_config +will return SQLITE_ERROR if called with the SQLITE_CONFIG_MULTITHREAD +configuration option. +.It SQLITE_CONFIG_SERIALIZED +There are no arguments to this option. +This option sets the threading mode to Serialized. +In other words, this option enables all mutexes including the recursive +mutexes on database connection and prepared statement +objects. +In this mode (which is the default when SQLite is compiled with SQLITE_THREADSAFE=1) +the SQLite library will itself serialize access to database connections +and prepared statements so that the application +is free to use the same database connection or the +same prepared statement in different threads at the +same time. +If SQLite is compiled with the SQLITE_THREADSAFE=0 +compile-time option then it is not possible to set the Serialized threading mode +and +.Fn sqlite3_config +will return SQLITE_ERROR if called with the SQLITE_CONFIG_SERIALIZED +configuration option. +.It SQLITE_CONFIG_MALLOC +The SQLITE_CONFIG_MALLOC option takes a single argument which is a +pointer to an instance of the sqlite3_mem_methods +structure. +The argument specifies alternative low-level memory allocation routines +to be used in place of the memory allocation routines built into SQLite. +SQLite makes its own private copy of the content of the sqlite3_mem_methods +structure before the +.Fn sqlite3_config +call returns. +.It SQLITE_CONFIG_GETMALLOC +The SQLITE_CONFIG_GETMALLOC option takes a single argument which is +a pointer to an instance of the sqlite3_mem_methods +structure. +The sqlite3_mem_methods structure is filled with +the currently defined memory allocation routines. +This option can be used to overload the default memory allocation routines +with a wrapper that simulations memory allocation failure or tracks +memory usage, for example. +.It SQLITE_CONFIG_SMALL_MALLOC +The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of type +int, interpreted as a boolean, which if true provides a hint to SQLite +that it should avoid large memory allocations if possible. +SQLite will run faster if it is free to make large memory allocations, +but some application might prefer to run slower in exchange for guarantees +about memory fragmentation that are possible if large allocations are +avoided. +This hint is normally off. +.It SQLITE_CONFIG_MEMSTATUS +The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int, +interpreted as a boolean, which enables or disables the collection +of memory allocation statistics. +When memory allocation statistics are disabled, the following SQLite +interfaces become non-operational: +.Bl -bullet +.It +.Fn sqlite3_hard_heap_limit64 +.It +.Fn sqlite3_memory_used +.It +.Fn sqlite3_memory_highwater +.It +.Fn sqlite3_soft_heap_limit64 +.It +.Fn sqlite3_status64 +.El +.Pp +Memory allocation statistics are enabled by default unless SQLite is +compiled with SQLITE_DEFAULT_MEMSTATUS=0 in +which case memory allocation statistics are disabled by default. +.It SQLITE_CONFIG_SCRATCH +The SQLITE_CONFIG_SCRATCH option is no longer used. +.It SQLITE_CONFIG_PAGECACHE +The SQLITE_CONFIG_PAGECACHE option specifies a memory pool that SQLite +can use for the database page cache with the default page cache implementation. +This configuration option is a no-op if an application-defined page +cache implementation is loaded using the SQLITE_CONFIG_PCACHE2. +There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to +8-byte aligned memory (pMem), the size of each page cache line (sz), +and the number of cache lines (N). +The sz argument should be the size of the largest database page (a +power of two between 512 and 65536) plus some extra bytes for each +page header. +The number of extra bytes needed by the page header can be determined +using SQLITE_CONFIG_PCACHE_HDRSZ. +It is harmless, apart from the wasted memory, for the sz parameter +to be larger than necessary. +The pMem argument must be either a NULL pointer or a pointer to an +8-byte aligned block of memory of at least sz*N bytes, otherwise subsequent +behavior is undefined. +When pMem is not NULL, SQLite will strive to use the memory provided +to satisfy page cache needs, falling back to +.Fn sqlite3_malloc +if a page cache line is larger than sz bytes or if all of the pMem +buffer is exhausted. +If pMem is NULL and N is non-zero, then each database connection does +an initial bulk allocation for page cache memory from +.Fn sqlite3_malloc +sufficient for N cache lines if N is positive or of -1024*N bytes if +N is negative, . +If additional page cache memory is needed beyond what is provided by +the initial allocation, then SQLite goes to +.Fn sqlite3_malloc +separately for each additional cache line. +.It SQLITE_CONFIG_HEAP +The SQLITE_CONFIG_HEAP option specifies a static memory buffer that +SQLite will use for all of its dynamic memory allocation needs beyond +those provided for by SQLITE_CONFIG_PAGECACHE. +The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled +with either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 +and returns SQLITE_ERROR if invoked otherwise. +There are three arguments to SQLITE_CONFIG_HEAP: An 8-byte aligned +pointer to the memory, the number of bytes in the memory buffer, and +the minimum allocation size. +If the first pointer (the memory pointer) is NULL, then SQLite reverts +to using its default memory allocator (the system malloc() implementation), +undoing any prior invocation of SQLITE_CONFIG_MALLOC. +If the memory pointer is not NULL then the alternative memory allocator +is engaged to handle all of SQLites memory allocation needs. +The first pointer (the memory pointer) must be aligned to an 8-byte +boundary or subsequent behavior of SQLite will be undefined. +The minimum allocation size is capped at 2**12. +Reasonable values for the minimum allocation size are 2**5 through +2**8. +.It SQLITE_CONFIG_MUTEX +The SQLITE_CONFIG_MUTEX option takes a single argument which is a pointer +to an instance of the sqlite3_mutex_methods structure. +The argument specifies alternative low-level mutex routines to be used +in place the mutex routines built into SQLite. +SQLite makes a copy of the content of the sqlite3_mutex_methods +structure before the call to +.Fn sqlite3_config +returns. +If SQLite is compiled with the SQLITE_THREADSAFE=0 +compile-time option then the entire mutexing subsystem is omitted from +the build and hence calls to +.Fn sqlite3_config +with the SQLITE_CONFIG_MUTEX configuration option will return SQLITE_ERROR. +.It SQLITE_CONFIG_GETMUTEX +The SQLITE_CONFIG_GETMUTEX option takes a single argument which is +a pointer to an instance of the sqlite3_mutex_methods +structure. +The sqlite3_mutex_methods structure is filled +with the currently defined mutex routines. +This option can be used to overload the default mutex allocation routines +with a wrapper used to track mutex usage for performance profiling +or testing, for example. +If SQLite is compiled with the SQLITE_THREADSAFE=0 +compile-time option then the entire mutexing subsystem is omitted from +the build and hence calls to +.Fn sqlite3_config +with the SQLITE_CONFIG_GETMUTEX configuration option will return SQLITE_ERROR. +.It SQLITE_CONFIG_LOOKASIDE +The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine +the default size of lookaside memory on each database connection. +The first argument is the size of each lookaside buffer slot and the +second is the number of slots allocated to each database connection. +SQLITE_CONFIG_LOOKASIDE sets the \fIdefault\fP lookaside size. +The SQLITE_DBCONFIG_LOOKASIDE option to +.Fn sqlite3_db_config +can be used to change the lookaside configuration on individual connections. +.It SQLITE_CONFIG_PCACHE2 +The SQLITE_CONFIG_PCACHE2 option takes a single argument which is a +pointer to an sqlite3_pcache_methods2 object. +This object specifies the interface to a custom page cache implementation. +SQLite makes a copy of the sqlite3_pcache_methods2 +object. +.It SQLITE_CONFIG_GETPCACHE2 +The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which is +a pointer to an sqlite3_pcache_methods2 object. +SQLite copies of the current page cache implementation into that object. +.It SQLITE_CONFIG_LOG +The SQLITE_CONFIG_LOG option is used to configure the SQLite global +error log. +(The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a function +with a call signature of void(*)(void*,int,const char*), and a pointer +to void. +If the function pointer is not NULL, it is invoked by +.Fn sqlite3_log +to process each logging event. +If the function pointer is NULL, the +.Fn sqlite3_log +interface becomes a no-op. +The void pointer that is the second argument to SQLITE_CONFIG_LOG is +passed through as the first parameter to the application-defined logger +function whenever that function is invoked. +The second parameter to the logger function is a copy of the first +parameter to the corresponding +.Fn sqlite3_log +call and is intended to be a result code or an extended result code. +The third parameter passed to the logger is log message after formatting +via +.Fn sqlite3_snprintf . +The SQLite logging interface is not reentrant; the logger function +supplied by the application must not invoke any SQLite interface. +In a multi-threaded application, the application-defined logger function +must be threadsafe. +.It SQLITE_CONFIG_URI +The SQLITE_CONFIG_URI option takes a single argument of type int. +If non-zero, then URI handling is globally enabled. +If the parameter is zero, then URI handling is globally disabled. +If URI handling is globally enabled, all filenames passed to +.Fn sqlite3_open , +.Fn sqlite3_open_v2 , +.Fn sqlite3_open16 +or specified as part of ATTACH commands are interpreted as URIs, +regardless of whether or not the SQLITE_OPEN_URI flag +is set when the database connection is opened. +If it is globally disabled, filenames are only interpreted as URIs +if the SQLITE_OPEN_URI flag is set when the database connection is +opened. +By default, URI handling is globally disabled. +The default value may be changed by compiling with the SQLITE_USE_URI +symbol defined. +.It SQLITE_CONFIG_COVERING_INDEX_SCAN +The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer +argument which is interpreted as a boolean in order to enable or disable +the use of covering indices for full table scans in the query optimizer. +The default setting is determined by the SQLITE_ALLOW_COVERING_INDEX_SCAN +compile-time option, or is "on" if that compile-time option is omitted. +The ability to disable the use of covering indices for full table scans +is because some incorrectly coded legacy applications might malfunction +when the optimization is enabled. +Providing the ability to disable the optimization allows the older, +buggy application code to work without change even with newer versions +of SQLite. +.It SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE +These options are obsolete and should not be used by new code. +They are retained for backwards compatibility but are now no-ops. +.It SQLITE_CONFIG_SQLLOG +This option is only available if sqlite is compiled with the SQLITE_ENABLE_SQLLOG +pre-processor macro defined. +The first argument should be a pointer to a function of type void(*)(void*,sqlite3*,const +char*, int). +The second should be of type (void*). +The callback is invoked by the library in three separate circumstances, +identified by the value passed as the fourth parameter. +If the fourth parameter is 0, then the database connection passed as +the second argument has just been opened. +The third argument points to a buffer containing the name of the main +database file. +If the fourth parameter is 1, then the SQL statement that the third +parameter points to has just been executed. +Or, if the fourth parameter is 2, then the connection being passed +as the second parameter is being closed. +The third parameter is passed NULL In this case. +An example of using this configuration option can be seen in the "test_sqllog.c" +source file in the canonical SQLite source tree. +.It SQLITE_CONFIG_MMAP_SIZE +SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values +that are the default mmap size limit (the default setting for PRAGMA mmap_size) +and the maximum allowed mmap size limit. +The default setting can be overridden by each database connection using +either the PRAGMA mmap_size command, or by using the +SQLITE_FCNTL_MMAP_SIZE file control. +The maximum allowed mmap size will be silently truncated if necessary +so that it does not exceed the compile-time maximum mmap size set by +the SQLITE_MAX_MMAP_SIZE compile-time option. +If either argument to this option is negative, then that argument is +changed to its compile-time default. +.It SQLITE_CONFIG_WIN32_HEAPSIZE +The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite +is compiled for Windows with the SQLITE_WIN32_MALLOC +pre-processor macro defined. +SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value +that specifies the maximum size of the created heap. +.It SQLITE_CONFIG_PCACHE_HDRSZ +The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which +is a pointer to an integer and writes into that integer the number +of extra bytes per page required for each page in SQLITE_CONFIG_PAGECACHE. +The amount of extra space required can change depending on the compiler, +target platform, and SQLite version. +.It SQLITE_CONFIG_PMASZ +The SQLITE_CONFIG_PMASZ option takes a single parameter which is an +unsigned integer and sets the "Minimum PMA Size" for the multithreaded +sorter to that integer. +The default minimum PMA Size is set by the SQLITE_SORTER_PMASZ +compile-time option. +New threads are launched to help with sort operations when multithreaded +sorting is enabled (using the PRAGMA threads command) +and the amount of content to be sorted exceeds the page size times +the minimum of the PRAGMA cache_size setting and this +value. +.It SQLITE_CONFIG_STMTJRNL_SPILL +The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which +becomes the statement journal spill-to-disk threshold. +Statement journals are held in memory until their +size (in bytes) exceeds this threshold, at which point they are written +to disk. +Or if the threshold is -1, statement journals are always held exclusively +in memory. +Since many statement journals never become large, setting the spill +threshold to a value such as 64KiB can greatly reduce the amount of +I/O required to support statement rollback. +The default value for this setting is controlled by the SQLITE_STMTJRNL_SPILL +compile-time option. +.It SQLITE_CONFIG_SORTERREF_SIZE +The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter +of type (int) - the new value of the sorter-reference size threshold. +Usually, when SQLite uses an external sort to order records according +to an ORDER BY clause, all fields required by the caller are present +in the sorted records. +However, if SQLite determines based on the declared type of a table +column that its values are likely to be very large - larger than the +configured sorter-reference size threshold - then a reference is stored +in each sorted record and the required column values loaded from the +database as records are returned in sorted order. +The default value for this option is to never use this optimization. +Specifying a negative value for this option restores the default behavior. +This option is only available if SQLite is compiled with the SQLITE_ENABLE_SORTER_REFERENCES +compile-time option. +.It SQLITE_CONFIG_MEMDB_MAXSIZE +The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter sqlite3_int64 +parameter which is the default maximum size for an in-memory database +created using +.Fn sqlite3_deserialize . +This default maximum size can be adjusted up or down for individual +databases using the SQLITE_FCNTL_SIZE_LIMIT +file-control. +If this configuration setting is never used, then the default maximum +is determined by the SQLITE_MEMDB_DEFAULT_MAXSIZE +compile-time option. +If that compile-time option is not set, then the default maximum is +1073741824. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1777. +.Bd -literal +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ +#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */ +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ +#define SQLITE_CONFIG_PCACHE 14 /* no-op */ +#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ +#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ +#define SQLITE_CONFIG_URI 17 /* int */ +#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ +#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ +#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ +#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ +#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ +#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ +#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ +#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ +#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ +#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */ +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_config 3 , +.Xr sqlite3_db_config 3 , +.Xr sqlite3_deserialize 3 , +.Xr sqlite3_file_control 3 , +.Xr sqlite3_initialize 3 , +.Xr sqlite3_log 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mem_methods 3 , +.Xr sqlite3_memory_used 3 , +.Xr sqlite3_mprintf 3 , +.Xr sqlite3_mutex_methods 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_pcache_methods2 3 , +.Xr sqlite3_soft_heap_limit64 3 , +.Xr sqlite3_status 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_DBCONFIG_MAINDBNAME 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 , +.Xr sqlite_int64 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_OPEN_READONLY 3 diff --git a/static/netbsd/man3/SQLITE_CREATE_INDEX.3 b/static/netbsd/man3/SQLITE_CREATE_INDEX.3 new file mode 100644 index 00000000..36d6945b --- /dev/null +++ b/static/netbsd/man3/SQLITE_CREATE_INDEX.3 @@ -0,0 +1,136 @@ +.Dd January 24, 2024 +.Dt SQLITE_CREATE_INDEX 3 +.Os +.Sh NAME +.Nm SQLITE_CREATE_INDEX , +.Nm SQLITE_CREATE_TABLE , +.Nm SQLITE_CREATE_TEMP_INDEX , +.Nm SQLITE_CREATE_TEMP_TABLE , +.Nm SQLITE_CREATE_TEMP_TRIGGER , +.Nm SQLITE_CREATE_TEMP_VIEW , +.Nm SQLITE_CREATE_TRIGGER , +.Nm SQLITE_CREATE_VIEW , +.Nm SQLITE_DELETE , +.Nm SQLITE_DROP_INDEX , +.Nm SQLITE_DROP_TABLE , +.Nm SQLITE_DROP_TEMP_INDEX , +.Nm SQLITE_DROP_TEMP_TABLE , +.Nm SQLITE_DROP_TEMP_TRIGGER , +.Nm SQLITE_DROP_TEMP_VIEW , +.Nm SQLITE_DROP_TRIGGER , +.Nm SQLITE_DROP_VIEW , +.Nm SQLITE_INSERT , +.Nm SQLITE_PRAGMA , +.Nm SQLITE_READ , +.Nm SQLITE_SELECT , +.Nm SQLITE_TRANSACTION , +.Nm SQLITE_UPDATE , +.Nm SQLITE_ATTACH , +.Nm SQLITE_DETACH , +.Nm SQLITE_ALTER_TABLE , +.Nm SQLITE_REINDEX , +.Nm SQLITE_ANALYZE , +.Nm SQLITE_CREATE_VTABLE , +.Nm SQLITE_DROP_VTABLE , +.Nm SQLITE_FUNCTION , +.Nm SQLITE_SAVEPOINT , +.Nm SQLITE_COPY , +.Nm SQLITE_RECURSIVE +.Nd authorizer action codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_CREATE_INDEX +.Fd #define SQLITE_CREATE_TABLE +.Fd #define SQLITE_CREATE_TEMP_INDEX +.Fd #define SQLITE_CREATE_TEMP_TABLE +.Fd #define SQLITE_CREATE_TEMP_TRIGGER +.Fd #define SQLITE_CREATE_TEMP_VIEW +.Fd #define SQLITE_CREATE_TRIGGER +.Fd #define SQLITE_CREATE_VIEW +.Fd #define SQLITE_DELETE +.Fd #define SQLITE_DROP_INDEX +.Fd #define SQLITE_DROP_TABLE +.Fd #define SQLITE_DROP_TEMP_INDEX +.Fd #define SQLITE_DROP_TEMP_TABLE +.Fd #define SQLITE_DROP_TEMP_TRIGGER +.Fd #define SQLITE_DROP_TEMP_VIEW +.Fd #define SQLITE_DROP_TRIGGER +.Fd #define SQLITE_DROP_VIEW +.Fd #define SQLITE_INSERT +.Fd #define SQLITE_PRAGMA +.Fd #define SQLITE_READ +.Fd #define SQLITE_SELECT +.Fd #define SQLITE_TRANSACTION +.Fd #define SQLITE_UPDATE +.Fd #define SQLITE_ATTACH +.Fd #define SQLITE_DETACH +.Fd #define SQLITE_ALTER_TABLE +.Fd #define SQLITE_REINDEX +.Fd #define SQLITE_ANALYZE +.Fd #define SQLITE_CREATE_VTABLE +.Fd #define SQLITE_DROP_VTABLE +.Fd #define SQLITE_FUNCTION +.Fd #define SQLITE_SAVEPOINT +.Fd #define SQLITE_COPY +.Fd #define SQLITE_RECURSIVE +.Sh DESCRIPTION +The +.Fn sqlite3_set_authorizer +interface registers a callback function that is invoked to authorize +certain SQL statement actions. +The second parameter to the callback is an integer code that specifies +what action is being authorized. +These are the integer action codes that the authorizer callback may +be passed. +.Pp +These action code values signify what kind of operation is to be authorized. +The 3rd and 4th parameters to the authorization callback function will +be parameters or NULL depending on which of these codes is used as +the second parameter. +The 5th parameter to the authorizer callback is the name of the database +("main", "temp", etc.) if applicable. +The 6th parameter to the authorizer callback is the name of the inner-most +trigger or view that is responsible for the access attempt or NULL +if this access attempt is directly from top-level SQL code. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3234. +.Bd -literal +/******************************************* 3rd ************ 4th ***********/ +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ +#define SQLITE_DELETE 9 /* Table Name NULL */ +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ +#define SQLITE_DROP_VIEW 17 /* View Name NULL */ +#define SQLITE_INSERT 18 /* Table Name NULL */ +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ +#define SQLITE_READ 20 /* Table Name Column Name */ +#define SQLITE_SELECT 21 /* NULL NULL */ +#define SQLITE_TRANSACTION 22 /* Operation NULL */ +#define SQLITE_UPDATE 23 /* Table Name Column Name */ +#define SQLITE_ATTACH 24 /* Filename NULL */ +#define SQLITE_DETACH 25 /* Database Name NULL */ +#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ +#define SQLITE_REINDEX 27 /* Index Name NULL */ +#define SQLITE_ANALYZE 28 /* Table Name NULL */ +#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ +#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ +#define SQLITE_FUNCTION 31 /* NULL Function Name */ +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ +#define SQLITE_COPY 0 /* No longer used */ +#define SQLITE_RECURSIVE 33 /* NULL NULL */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_set_authorizer 3 diff --git a/static/netbsd/man3/SQLITE_DBCONFIG_LOOKASIDE.3 b/static/netbsd/man3/SQLITE_DBCONFIG_LOOKASIDE.3 new file mode 100644 index 00000000..d80cee94 --- /dev/null +++ b/static/netbsd/man3/SQLITE_DBCONFIG_LOOKASIDE.3 @@ -0,0 +1,115 @@ +.Dd December 18, 2016 +.Dt SQLITE_DBCONFIG_LOOKASIDE 3 +.Os +.Sh NAME +.Nm SQLITE_DBCONFIG_LOOKASIDE , +.Nm SQLITE_DBCONFIG_ENABLE_FKEY , +.Nm SQLITE_DBCONFIG_ENABLE_TRIGGER , +.Nm SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER , +.Nm SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +.Nd Database Connection Configuration Options +.Sh SYNOPSIS +.Fd #define SQLITE_DBCONFIG_LOOKASIDE +.Fd #define SQLITE_DBCONFIG_ENABLE_FKEY +.Fd #define SQLITE_DBCONFIG_ENABLE_TRIGGER +.Fd #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER +.Fd #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +.Sh DESCRIPTION +These constants are the available integer configuration options that +can be passed as the second argument to the sqlite3_db_config() +interface. +.Pp +New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. +Applications should check the return code from sqlite3_db_config() +to make sure that the call worked. +The sqlite3_db_config() interface will return a +non-zero error code if a discontinued or unsupported configuration +option is invoked. +.Bl -tag -width Ds +.It SQLITE_DBCONFIG_LOOKASIDE +This option takes three additional arguments that determine the lookaside memory allocator +configuration for the database connection. +The first argument (the third parameter to sqlite3_db_config() +is a pointer to a memory buffer to use for lookaside memory. +The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be +NULL in which case SQLite will allocate the lookaside buffer itself +using sqlite3_malloc(). +The second argument is the size of each lookaside buffer slot. +The third argument is the number of slots. +The size of the buffer in the first argument must be greater than or +equal to the product of the second and third arguments. +The buffer must be aligned to an 8-byte boundary. +If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple +of 8, it is internally rounded down to the next smaller multiple of +8. +The lookaside memory configuration for a database connection can only +be changed when that connection is not currently using lookaside memory, +or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_CONFIG_LOOKASIDE,...) +is zero. +Any attempt to change the lookaside memory configuration when lookaside +memory is in use leaves the configuration unchanged and returns SQLITE_BUSY. +.It SQLITE_DBCONFIG_ENABLE_FKEY +This option is used to enable or disable the enforcement of foreign key constraints. +There should be two additional arguments. +The first argument is an integer which is 0 to disable FK enforcement, +positive to enable FK enforcement or negative to leave FK enforcement +unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether FK enforcement is off or on following this +call. +The second parameter may be a NULL pointer, in which case the FK enforcement +setting is not reported back. +.It SQLITE_DBCONFIG_ENABLE_TRIGGER +This option is used to enable or disable triggers. +There should be two additional arguments. +The first argument is an integer which is 0 to disable triggers, positive +to enable triggers or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether triggers are disabled or enabled following +this call. +The second parameter may be a NULL pointer, in which case the trigger +setting is not reported back. +.It SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER +This option is used to enable or disable the two-argument version of +the fts3_tokenizer() function which is part of the +FTS3 full-text search engine extension. +There should be two additional arguments. +The first argument is an integer which is 0 to disable fts3_tokenizer() +or positive to enable fts3_tokenizer() or negative to leave the setting +unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether fts3_tokenizer is disabled or enabled following +this call. +The second parameter may be a NULL pointer, in which case the new setting +is not reported back. +.It SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +This option is used to enable or disable the sqlite3_load_extension() +interface independently of the load_extension() SQL +function. +The sqlite3_enable_load_extension() +API enables or disables both the C-API sqlite3_load_extension() +and the SQL function load_extension(). +There should be two additional arguments. +When the first argument to this interface is 1, then only the C-API +is enabled and the SQL function remains disabled. +If the first argment to this interface is 0, then both the C-API and +the SQL function are disabled. +If the first argument is -1, then no changes are made to state of either +the C-API or the SQL function. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether sqlite3_load_extension() +interface is disabled or enabled following this call. +The second parameter may be a NULL pointer, in which case the new setting +is not reported back. +.El +.Pp +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_db_config 3 , +.Xr sqlite3_db_status 3 , +.Xr sqlite3_enable_load_extension 3 , +.Xr sqlite3_load_extension 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/SQLITE_DBCONFIG_MAINDBNAME.3 b/static/netbsd/man3/SQLITE_DBCONFIG_MAINDBNAME.3 new file mode 100644 index 00000000..b07ebd3d --- /dev/null +++ b/static/netbsd/man3/SQLITE_DBCONFIG_MAINDBNAME.3 @@ -0,0 +1,405 @@ +.Dd January 24, 2024 +.Dt SQLITE_DBCONFIG_MAINDBNAME 3 +.Os +.Sh NAME +.Nm SQLITE_DBCONFIG_MAINDBNAME , +.Nm SQLITE_DBCONFIG_LOOKASIDE , +.Nm SQLITE_DBCONFIG_ENABLE_FKEY , +.Nm SQLITE_DBCONFIG_ENABLE_TRIGGER , +.Nm SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER , +.Nm SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION , +.Nm SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE , +.Nm SQLITE_DBCONFIG_ENABLE_QPSG , +.Nm SQLITE_DBCONFIG_TRIGGER_EQP , +.Nm SQLITE_DBCONFIG_RESET_DATABASE , +.Nm SQLITE_DBCONFIG_DEFENSIVE , +.Nm SQLITE_DBCONFIG_WRITABLE_SCHEMA , +.Nm SQLITE_DBCONFIG_LEGACY_ALTER_TABLE , +.Nm SQLITE_DBCONFIG_DQS_DML , +.Nm SQLITE_DBCONFIG_DQS_DDL , +.Nm SQLITE_DBCONFIG_ENABLE_VIEW , +.Nm SQLITE_DBCONFIG_LEGACY_FILE_FORMAT , +.Nm SQLITE_DBCONFIG_TRUSTED_SCHEMA , +.Nm SQLITE_DBCONFIG_STMT_SCANSTATUS , +.Nm SQLITE_DBCONFIG_REVERSE_SCANORDER , +.Nm SQLITE_DBCONFIG_MAX +.Nd database connection configuration options +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_DBCONFIG_MAINDBNAME +.Fd #define SQLITE_DBCONFIG_LOOKASIDE +.Fd #define SQLITE_DBCONFIG_ENABLE_FKEY +.Fd #define SQLITE_DBCONFIG_ENABLE_TRIGGER +.Fd #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER +.Fd #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +.Fd #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE +.Fd #define SQLITE_DBCONFIG_ENABLE_QPSG +.Fd #define SQLITE_DBCONFIG_TRIGGER_EQP +.Fd #define SQLITE_DBCONFIG_RESET_DATABASE +.Fd #define SQLITE_DBCONFIG_DEFENSIVE +.Fd #define SQLITE_DBCONFIG_WRITABLE_SCHEMA +.Fd #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE +.Fd #define SQLITE_DBCONFIG_DQS_DML +.Fd #define SQLITE_DBCONFIG_DQS_DDL +.Fd #define SQLITE_DBCONFIG_ENABLE_VIEW +.Fd #define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT +.Fd #define SQLITE_DBCONFIG_TRUSTED_SCHEMA +.Fd #define SQLITE_DBCONFIG_STMT_SCANSTATUS +.Fd #define SQLITE_DBCONFIG_REVERSE_SCANORDER +.Fd #define SQLITE_DBCONFIG_MAX +.Sh DESCRIPTION +These constants are the available integer configuration options that +can be passed as the second argument to the +.Fn sqlite3_db_config +interface. +.Pp +New configuration options may be added in future releases of SQLite. +Existing configuration options might be discontinued. +Applications should check the return code from +.Fn sqlite3_db_config +to make sure that the call worked. +The +.Fn sqlite3_db_config +interface will return a non-zero error code if a discontinued +or unsupported configuration option is invoked. +.Bl -tag -width Ds +.It SQLITE_DBCONFIG_LOOKASIDE +This option takes three additional arguments that determine the lookaside memory allocator +configuration for the database connection. +The first argument (the third parameter to +.Fn sqlite3_db_config +is a pointer to a memory buffer to use for lookaside memory. +The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb may be +NULL in which case SQLite will allocate the lookaside buffer itself +using +.Fn sqlite3_malloc . +The second argument is the size of each lookaside buffer slot. +The third argument is the number of slots. +The size of the buffer in the first argument must be greater than or +equal to the product of the second and third arguments. +The buffer must be aligned to an 8-byte boundary. +If the second argument to SQLITE_DBCONFIG_LOOKASIDE is not a multiple +of 8, it is internally rounded down to the next smaller multiple of +8. +The lookaside memory configuration for a database connection can only +be changed when that connection is not currently using lookaside memory, +or in other words when the "current value" returned by sqlite3_db_status(D,SQLITE_DBSTATUS_LOOKASIDE_USED,...) +is zero. +Any attempt to change the lookaside memory configuration when lookaside +memory is in use leaves the configuration unchanged and returns SQLITE_BUSY. +.It SQLITE_DBCONFIG_ENABLE_FKEY +This option is used to enable or disable the enforcement of foreign key constraints. +There should be two additional arguments. +The first argument is an integer which is 0 to disable FK enforcement, +positive to enable FK enforcement or negative to leave FK enforcement +unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether FK enforcement is off or on following this +call. +The second parameter may be a NULL pointer, in which case the FK enforcement +setting is not reported back. +.It SQLITE_DBCONFIG_ENABLE_TRIGGER +This option is used to enable or disable triggers. +There should be two additional arguments. +The first argument is an integer which is 0 to disable triggers, positive +to enable triggers or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether triggers are disabled or enabled following +this call. +The second parameter may be a NULL pointer, in which case the trigger +setting is not reported back. +.Pp +Originally this option disabled all triggers. +However, since SQLite version 3.35.0, TEMP triggers are still allowed +even if this option is off. +So, in other words, this option now only disables triggers in the main +database schema or in the schemas of ATTACH-ed databases. +.It SQLITE_DBCONFIG_ENABLE_VIEW +This option is used to enable or disable views. +There should be two additional arguments. +The first argument is an integer which is 0 to disable views, positive +to enable views or negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether views are disabled or enabled following +this call. +The second parameter may be a NULL pointer, in which case the view +setting is not reported back. +.Pp +Originally this option disabled all views. +However, since SQLite version 3.35.0, TEMP views are still allowed +even if this option is off. +So, in other words, this option now only disables views in the main +database schema or in the schemas of ATTACH-ed databases. +.It SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER +This option is used to enable or disable the +.Fn fts3_tokenizer +function which is part of the FTS3 full-text search engine extension. +There should be two additional arguments. +The first argument is an integer which is 0 to disable fts3_tokenizer() +or positive to enable fts3_tokenizer() or negative to leave the setting +unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether fts3_tokenizer is disabled or enabled following +this call. +The second parameter may be a NULL pointer, in which case the new setting +is not reported back. +.It SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +This option is used to enable or disable the +.Fn sqlite3_load_extension +interface independently of the +.Fn load_extension +SQL function. +The +.Fn sqlite3_enable_load_extension +API enables or disables both the C-API +.Fn sqlite3_load_extension +and the SQL function +.Fn load_extension . +There should be two additional arguments. +When the first argument to this interface is 1, then only the C-API +is enabled and the SQL function remains disabled. +If the first argument to this interface is 0, then both the C-API and +the SQL function are disabled. +If the first argument is -1, then no changes are made to state of either +the C-API or the SQL function. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether +.Fn sqlite3_load_extension +interface is disabled or enabled following this call. +The second parameter may be a NULL pointer, in which case the new setting +is not reported back. +.It SQLITE_DBCONFIG_MAINDBNAME +This option is used to change the name of the "main" database schema. +The sole argument is a pointer to a constant UTF8 string which will +become the new schema name in place of "main". +SQLite does not make a copy of the new main schema name string, so +the application must ensure that the argument passed into this DBCONFIG +option is unchanged until after the database connection closes. +.It SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE +Usually, when a database in wal mode is closed or detached from a database +handle, SQLite checks if this will mean that there are now no connections +at all to the database. +If so, it performs a checkpoint operation before closing the connection. +This option may be used to override this behavior. +The first parameter passed to this operation is an integer - positive +to disable checkpoints-on-close, or zero (the default) to enable them, +and negative to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether checkpoints-on-close have been disabled +- 0 if they are not disabled, 1 if they are. +.It SQLITE_DBCONFIG_ENABLE_QPSG +The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates the +query planner stability guarantee +(QPSG). +When the QPSG is active, a single SQL query statement will always use +the same algorithm regardless of values of bound parameters. +The QPSG disables some query optimizations that look at the values +of bound parameters, which can make some queries slower. +But the QPSG has the advantage of more predictable behavior. +With the QPSG active, SQLite will always use the same query plan in +the field as was used during testing in the lab. +The first argument to this setting is an integer which is 0 to disable +the QPSG, positive to enable QPSG, or negative to leave the setting +unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether the QPSG is disabled or enabled following +this call. +.It SQLITE_DBCONFIG_TRIGGER_EQP +By default, the output of EXPLAIN QUERY PLAN commands does not include +output for any operations performed by trigger programs. +This option is used to set or clear (the default) a flag that governs +this behavior. +The first parameter passed to this operation is an integer - positive +to enable output for trigger programs, or zero to disable it, or negative +to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether output-for-triggers has been disabled - +0 if it is not disabled, 1 if it is. +.It SQLITE_DBCONFIG_RESET_DATABASE +Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run VACUUM +in order to reset a database back to an empty database with no schema +and no content. +The following process works even for a badly corrupted database file: +.Bl -enum +.It +If the database connection is newly opened, make sure it has read the +database schema by preparing then discarding some query against the +database, or calling sqlite3_table_column_metadata(), ignoring any +errors. +This step is only necessary if the application desires to keep the +database in WAL mode after the reset if it was in WAL mode before the +reset. +.It +sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); +.It +sqlite3_exec(db, "VACUUM", 0, 0, 0); +.It +sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); +.El +.Pp +Because resetting a database is destructive and irreversible, the process +requires the use of this obscure API and multiple steps to help ensure +that it does not happen by accident. +Because this feature must be capable of resetting corrupt databases, +and shutting down virtual tables may require access to that corrupt +storage, the library must abandon any installed virtual tables without +calling their xDestroy() methods. +.It SQLITE_DBCONFIG_DEFENSIVE +The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the "defensive" +flag for a database connection. +When the defensive flag is enabled, language features that allow ordinary +SQL to deliberately corrupt the database file are disabled. +The disabled features include but are not limited to the following: +.Bl -bullet +.It +The PRAGMA writable_schema=ON statement. +.It +The PRAGMA journal_mode=OFF statement. +.It +The PRAGMA schema_version=N statement. +.It +Writes to the sqlite_dbpage virtual table. +.It +Direct writes to shadow tables. +.El +.Pp +.It SQLITE_DBCONFIG_WRITABLE_SCHEMA +The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates +the "writable_schema" flag. +This has the same effect and is logically equivalent to setting PRAGMA writable_schema=ON +or PRAGMA writable_schema=OFF. +The first argument to this setting is an integer which is 0 to disable +the writable_schema, positive to enable writable_schema, or negative +to leave the setting unchanged. +The second parameter is a pointer to an integer into which is written +0 or 1 to indicate whether the writable_schema is enabled or disabled +following this call. +.It SQLITE_DBCONFIG_LEGACY_ALTER_TABLE +The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates +the legacy behavior of the ALTER TABLE RENAME command +such it behaves as it did prior to version 3.24.0 (2018-06-04). +See the "Compatibility Notice" on the ALTER TABLE RENAME documentation +for additional information. +This feature can also be turned on and off using the PRAGMA legacy_alter_table +statement. +.It SQLITE_DBCONFIG_DQS_DML +The SQLITE_DBCONFIG_DQS_DML option activates or deactivates the legacy +double-quoted string literal misfeature +for DML statements only, that is DELETE, INSERT, SELECT, and UPDATE +statements. +The default value of this setting is determined by the -DSQLITE_DQS +compile-time option. +.It SQLITE_DBCONFIG_DQS_DDL +The SQLITE_DBCONFIG_DQS option activates or deactivates the legacy +double-quoted string literal misfeature +for DDL statements, such as CREATE TABLE and CREATE INDEX. +The default value of this setting is determined by the -DSQLITE_DQS +compile-time option. +.It SQLITE_DBCONFIG_TRUSTED_SCHEMA +The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to assume that +database schemas are untainted by malicious content. +When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite +takes additional defensive steps to protect the application from harm +including: +.Bl -bullet +.It +Prohibit the use of SQL functions inside triggers, views, CHECK constraints, +DEFAULT clauses, expression indexes, partial indexes, or generated +columns unless those functions are tagged with SQLITE_INNOCUOUS. +.It +Prohibit the use of virtual tables inside of triggers or views unless +those virtual tables are tagged with SQLITE_VTAB_INNOCUOUS. +.El +.Pp +This setting defaults to "on" for legacy compatibility, however all +applications are advised to turn it off if possible. +This setting can also be controlled using the PRAGMA trusted_schema +statement. +.It SQLITE_DBCONFIG_LEGACY_FILE_FORMAT +The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates +the legacy file format flag. +When activated, this flag causes all newly created database file to +have a schema format version number (the 4-byte integer found at offset +44 into the database header) of 1. +This in turn means that the resulting database file will be readable +and writable by any SQLite version back to 3.0.0 (dateof:3.0.0). +Without this setting, newly created databases are generally not understandable +by SQLite versions prior to 3.3.0 (dateof:3.3.0). +As these words are written, there is now scarcely any need to generate +database files that are compatible all the way back to version 3.0.0, +and so this setting is of little practical use, but is provided so +that SQLite can continue to claim the ability to generate new database +files that are compatible with version 3.0.0. +.Pp +Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on, +the VACUUM command will fail with an obscure error when attempting +to process a table with generated columns and a descending index. +This is not considered a bug since SQLite versions 3.3.0 and earlier +do not support either generated columns or descending indexes. +.It SQLITE_DBCONFIG_STMT_SCANSTATUS +The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in SQLITE_ENABLE_STMT_SCANSTATUS +builds. +In this case, it sets or clears a flag that enables collection of the +sqlite3_stmt_scanstatus_v2() statistics. +For statistics to be collected, the flag must be set on the database +handle both when the SQL statement is prepared and when it is stepped. +The flag is set (collection of statistics is enabled) by default. +This option takes two arguments: an integer and a pointer to an integer.. +The first argument is 1, 0, or -1 to enable, disable, or leave unchanged +the statement scanstatus option. +If the second argument is not NULL, then the value of the statement +scanstatus setting after processing the first argument is written into +the integer that the second argument points to. +.It SQLITE_DBCONFIG_REVERSE_SCANORDER +The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order +in which tables and indexes are scanned so that the scans start at +the end and work toward the beginning rather than starting at the beginning +and working toward the end. +Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the same as setting PRAGMA reverse_unordered_selects. +This option takes two arguments which are an integer and a pointer +to an integer. +The first argument is 1, 0, or -1 to enable, disable, or leave unchanged +the reverse scan order flag, respectively. +If the second argument is not NULL, then 0 or 1 is written into the +integer that the second argument points to depending on if the reverse +scan order flag is set after processing the first argument. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2177. +.Bd -literal +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ +#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ +#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ +#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */ +#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */ +#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */ +#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */ +#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */ +#define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */ +#define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */ +#define SQLITE_DBCONFIG_MAX 1019 /* Largest DBCONFIG */ +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_db_config 3 , +.Xr sqlite3_db_status 3 , +.Xr sqlite3_enable_load_extension 3 , +.Xr sqlite3_exec 3 , +.Xr sqlite3_load_extension 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_DBSTATUS_LOOKASIDE_USED 3 , +.Xr SQLITE_DETERMINISTIC 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_VTAB_CONSTRAINT_SUPPORT 3 diff --git a/static/netbsd/man3/SQLITE_DBSTATUS_LOOKASIDE_USED.3 b/static/netbsd/man3/SQLITE_DBSTATUS_LOOKASIDE_USED.3 new file mode 100644 index 00000000..b4752a00 --- /dev/null +++ b/static/netbsd/man3/SQLITE_DBSTATUS_LOOKASIDE_USED.3 @@ -0,0 +1,158 @@ +.Dd January 24, 2024 +.Dt SQLITE_DBSTATUS_LOOKASIDE_USED 3 +.Os +.Sh NAME +.Nm SQLITE_DBSTATUS_LOOKASIDE_USED , +.Nm SQLITE_DBSTATUS_CACHE_USED , +.Nm SQLITE_DBSTATUS_SCHEMA_USED , +.Nm SQLITE_DBSTATUS_STMT_USED , +.Nm SQLITE_DBSTATUS_LOOKASIDE_HIT , +.Nm SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE , +.Nm SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL , +.Nm SQLITE_DBSTATUS_CACHE_HIT , +.Nm SQLITE_DBSTATUS_CACHE_MISS , +.Nm SQLITE_DBSTATUS_CACHE_WRITE , +.Nm SQLITE_DBSTATUS_DEFERRED_FKS , +.Nm SQLITE_DBSTATUS_CACHE_USED_SHARED , +.Nm SQLITE_DBSTATUS_CACHE_SPILL , +.Nm SQLITE_DBSTATUS_MAX +.Nd status parameters for database connections +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_DBSTATUS_LOOKASIDE_USED +.Fd #define SQLITE_DBSTATUS_CACHE_USED +.Fd #define SQLITE_DBSTATUS_SCHEMA_USED +.Fd #define SQLITE_DBSTATUS_STMT_USED +.Fd #define SQLITE_DBSTATUS_LOOKASIDE_HIT +.Fd #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE +.Fd #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL +.Fd #define SQLITE_DBSTATUS_CACHE_HIT +.Fd #define SQLITE_DBSTATUS_CACHE_MISS +.Fd #define SQLITE_DBSTATUS_CACHE_WRITE +.Fd #define SQLITE_DBSTATUS_DEFERRED_FKS +.Fd #define SQLITE_DBSTATUS_CACHE_USED_SHARED +.Fd #define SQLITE_DBSTATUS_CACHE_SPILL +.Fd #define SQLITE_DBSTATUS_MAX +.Sh DESCRIPTION +These constants are the available integer "verbs" that can be passed +as the second argument to the +.Fn sqlite3_db_status +interface. +.Pp +New verbs may be added in future releases of SQLite. +Existing verbs might be discontinued. +Applications should check the return code from +.Fn sqlite3_db_status +to make sure that the call worked. +The +.Fn sqlite3_db_status +interface will return a non-zero error code if a discontinued or unsupported +verb is invoked. +.Bl -tag -width Ds +.It SQLITE_DBSTATUS_LOOKASIDE_USED +This parameter returns the number of lookaside memory slots currently +checked out. +.It SQLITE_DBSTATUS_LOOKASIDE_HIT +This parameter returns the number of malloc attempts that were satisfied +using lookaside memory. +Only the high-water value is meaningful; the current value is always +zero. +.It SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE +This parameter returns the number malloc attempts that might have been +satisfied using lookaside memory but failed due to the amount of memory +requested being larger than the lookaside slot size. +Only the high-water value is meaningful; the current value is always +zero. +.It SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL +This parameter returns the number malloc attempts that might have been +satisfied using lookaside memory but failed due to all lookaside memory +already being in use. +Only the high-water value is meaningful; the current value is always +zero. +.It SQLITE_DBSTATUS_CACHE_USED +This parameter returns the approximate number of bytes of heap memory +used by all pager caches associated with the database connection. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always +0. +.It SQLITE_DBSTATUS_CACHE_USED_SHARED +This parameter is similar to DBSTATUS_CACHE_USED, except that if a +pager cache is shared between two or more connections the bytes of +heap memory used by that pager cache is divided evenly between the +attached connections. +In other words, if none of the pager caches associated with the database +connection are shared, this request returns the same value as DBSTATUS_CACHE_USED. +Or, if one or more or the pager caches are shared, the value returned +by this call will be smaller than that returned by DBSTATUS_CACHE_USED. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED_SHARED +is always 0. +.It SQLITE_DBSTATUS_SCHEMA_USED +This parameter returns the approximate number of bytes of heap memory +used to store the schema for all databases associated with the connection +- main, temp, and any ATTACH-ed databases. +The full amount of memory used by the schemas is reported, even if +the schema memory is shared with other database connections due to +shared cache mode being enabled. +The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always +0. +.It SQLITE_DBSTATUS_STMT_USED +This parameter returns the approximate number of bytes of heap and +lookaside memory used by all prepared statements associated with the +database connection. +The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always +0. +.It SQLITE_DBSTATUS_CACHE_HIT +This parameter returns the number of pager cache hits that have occurred. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT is always +0. +.It SQLITE_DBSTATUS_CACHE_MISS +This parameter returns the number of pager cache misses that have occurred. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS is always +0. +.It SQLITE_DBSTATUS_CACHE_WRITE +This parameter returns the number of dirty cache entries that have +been written to disk. +Specifically, the number of pages written to the wal file in wal mode +databases, or the number of pages written to the database file in rollback +mode databases. +Any pages written as part of transaction rollback or database recovery +operations are not included. +If an IO or other error occurs while writing a page to disk, the effect +on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. +The highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always +0. +.It SQLITE_DBSTATUS_CACHE_SPILL +This parameter returns the number of dirty cache entries that have +been written to disk in the middle of a transaction due to the page +cache overflowing. +Transactions are more efficient if they are written to disk all at +once. +When pages spill mid-transaction, that introduces additional overhead. +This parameter can be used help identify inefficiencies that can be +resolved by increasing the cache size. +.It SQLITE_DBSTATUS_DEFERRED_FKS +This parameter returns zero for the current value if and only if all +foreign key constraints (deferred or immediate) have been resolved. +The highwater mark is always 0. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8652. +.Bd -literal +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 +#define SQLITE_DBSTATUS_CACHE_USED 1 +#define SQLITE_DBSTATUS_SCHEMA_USED 2 +#define SQLITE_DBSTATUS_STMT_USED 3 +#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 +#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 +#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 +#define SQLITE_DBSTATUS_CACHE_HIT 7 +#define SQLITE_DBSTATUS_CACHE_MISS 8 +#define SQLITE_DBSTATUS_CACHE_WRITE 9 +#define SQLITE_DBSTATUS_DEFERRED_FKS 10 +#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 +#define SQLITE_DBSTATUS_CACHE_SPILL 12 +#define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_status 3 diff --git a/static/netbsd/man3/SQLITE_DENY.3 b/static/netbsd/man3/SQLITE_DENY.3 new file mode 100644 index 00000000..0f8c90ff --- /dev/null +++ b/static/netbsd/man3/SQLITE_DENY.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE_DENY 3 +.Os +.Sh NAME +.Nm SQLITE_DENY , +.Nm SQLITE_IGNORE +.Nd authorizer return codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_DENY +.Fd #define SQLITE_IGNORE +.Sh DESCRIPTION +The authorizer callback function must return +either SQLITE_OK or one of these two constants in order to +signal SQLite whether or not the action is permitted. +See the authorizer documentation for additional +information. +.Pp +Note that SQLITE_IGNORE is also used as a conflict resolution mode +returned from the +.Fn sqlite3_vtab_on_conflict +interface. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3219. +.Bd -literal +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_set_authorizer 3 , +.Xr sqlite3_vtab_on_conflict 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_ROLLBACK 3 diff --git a/static/netbsd/man3/SQLITE_DESERIALIZE_FREEONCLOSE.3 b/static/netbsd/man3/SQLITE_DESERIALIZE_FREEONCLOSE.3 new file mode 100644 index 00000000..76d24a55 --- /dev/null +++ b/static/netbsd/man3/SQLITE_DESERIALIZE_FREEONCLOSE.3 @@ -0,0 +1,46 @@ +.Dd January 24, 2024 +.Dt SQLITE_DESERIALIZE_FREEONCLOSE 3 +.Os +.Sh NAME +.Nm SQLITE_DESERIALIZE_FREEONCLOSE , +.Nm SQLITE_DESERIALIZE_RESIZEABLE , +.Nm SQLITE_DESERIALIZE_READONLY +.Nd flags for sqlite3_deserialize() +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_DESERIALIZE_FREEONCLOSE +.Fd #define SQLITE_DESERIALIZE_RESIZEABLE +.Fd #define SQLITE_DESERIALIZE_READONLY +.Sh DESCRIPTION +The following are allowed values for 6th argument (the F argument) +to the sqlite3_deserialize(D,S,P,N,M,F) +interface. +.Pp +The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization +in the P argument is held in memory obtained from +.Fn sqlite3_malloc64 +and that SQLite should take ownership of this memory and automatically +free it when it has finished using it. +Without this flag, the caller is responsible for freeing any dynamically +allocated memory. +.Pp +The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed +to grow the size of the database using calls to +.Fn sqlite3_realloc64 . +This flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is +also used. +Without this flag, the deserialized database cannot increase in size +beyond the number of bytes specified by the M parameter. +.Pp +The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database +should be treated as read-only. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10754. +.Bd -literal +#define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */ +#define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */ +#define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 diff --git a/static/netbsd/man3/SQLITE_DETERMINISTIC.3 b/static/netbsd/man3/SQLITE_DETERMINISTIC.3 new file mode 100644 index 00000000..625aaef2 --- /dev/null +++ b/static/netbsd/man3/SQLITE_DETERMINISTIC.3 @@ -0,0 +1,129 @@ +.Dd January 24, 2024 +.Dt SQLITE_DETERMINISTIC 3 +.Os +.Sh NAME +.Nm SQLITE_DETERMINISTIC , +.Nm SQLITE_DIRECTONLY , +.Nm SQLITE_SUBTYPE , +.Nm SQLITE_INNOCUOUS , +.Nm SQLITE_RESULT_SUBTYPE +.Nd function flags +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_DETERMINISTIC +.Fd #define SQLITE_DIRECTONLY +.Fd #define SQLITE_SUBTYPE +.Fd #define SQLITE_INNOCUOUS +.Fd #define SQLITE_RESULT_SUBTYPE +.Sh DESCRIPTION +These constants may be ORed together with the preferred text encoding +as the fourth argument to +.Fn sqlite3_create_function , +.Fn sqlite3_create_function16 , +or +.Fn sqlite3_create_function_v2 . +.Bl -tag -width Ds +.It SQLITE_DETERMINISTIC +The SQLITE_DETERMINISTIC flag means that the new function always gives +the same output when the input parameters are the same. +The abs() function is deterministic, for example, but +randomblob() is not. +Functions must be deterministic in order to be used in certain contexts +such as with the WHERE clause of partial indexes or +in generated columns. +SQLite might also optimize deterministic functions by factoring them +out of inner loops. +.It SQLITE_DIRECTONLY +The SQLITE_DIRECTONLY flag means that the function may only be invoked +from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in +schema structures such as CHECK constraints, DEFAULT clauses, +expression indexes, partial indexes, +or generated columns. +.Pp +The SQLITE_DIRECTONLY flag is recommended for any application-defined SQL function +that has side-effects or that could potentially leak sensitive information. +This will prevent attacks in which an application is tricked into using +a database file that has had its schema surreptitiously modified to +invoke the application-defined function in ways that are harmful. +.Pp +Some people say it is good practice to set SQLITE_DIRECTONLY on all +application-defined SQL functions, +regardless of whether or not they are security sensitive, as doing +so prevents those functions from being used inside of the database +schema, and thus ensures that the database can be inspected and modified +using generic tools (such as the CLI) that do not have access to +the application-defined functions. +.It SQLITE_INNOCUOUS +The SQLITE_INNOCUOUS flag means that the function is unlikely to cause +problems even if misused. +An innocuous function should have no side effects and should not depend +on any values other than its input parameters. +The abs() function is an example of an innocuous function. +The load_extension() SQL function is not +innocuous because of its side effects. +.Pp +SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not exactly +the same. +The random() function is an example of a function +that is innocuous but not deterministic. +.Pp +Some heightened security settings (SQLITE_DBCONFIG_TRUSTED_SCHEMA +and PRAGMA trusted_schema=OFF) disable the +use of SQL functions inside views and triggers and in schema structures +such as CHECK constraints, DEFAULT clauses, +expression indexes, partial indexes, +and generated columns unless the function is tagged +with SQLITE_INNOCUOUS. +Most built-in functions are innocuous. +Developers are advised to avoid using the SQLITE_INNOCUOUS flag for +application-defined functions unless the function has been carefully +audited and found to be free of potentially security-adverse side-effects +and information-leaks. +.It SQLITE_SUBTYPE +The SQLITE_SUBTYPE flag indicates to SQLite that a function might call +.Fn sqlite3_value_subtype +to inspect the sub-types of its arguments. +This flag instructs SQLite to omit some corner-case optimizations that +might disrupt the operation of the +.Fn sqlite3_value_subtype +function, causing it to return zero rather than the correct subtype(). +SQL functions that invokes +.Fn sqlite3_value_subtype +should have this property. +If the SQLITE_SUBTYPE property is omitted, then the return value from +.Fn sqlite3_value_subtype +might sometimes be zero even though a non-zero subtype was specified +by the function argument expression. +.It SQLITE_RESULT_SUBTYPE +The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function +might call +.Fn sqlite3_result_subtype +to cause a sub-type to be associated with its result. +Every function that invokes +.Fn sqlite3_result_subtype +should have this property. +If it does not, then the call to +.Fn sqlite3_result_subtype +might become a no-op if the function is used as term in an expression index. +On the other hand, SQL functions that never invoke +.Fn sqlite3_result_subtype +should avoid setting this property, as the purpose of this property +is to disable certain optimizations that are incompatible with subtypes. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5513. +.Bd -literal +#define SQLITE_DETERMINISTIC 0x000000800 +#define SQLITE_DIRECTONLY 0x000080000 +#define SQLITE_SUBTYPE 0x000100000 +#define SQLITE_INNOCUOUS 0x000200000 +#define SQLITE_RESULT_SUBTYPE 0x001000000 +.Ed +.Sh SEE ALSO +.Xr sqlite3_create_function 3 , +.Xr sqlite3_result_subtype 3 , +.Xr sqlite3_value_subtype 3 , +.Xr SQLITE_DBCONFIG_MAINDBNAME 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/SQLITE_ERROR_MISSING_COLLSEQ.3 b/static/netbsd/man3/SQLITE_ERROR_MISSING_COLLSEQ.3 new file mode 100644 index 00000000..a657efae --- /dev/null +++ b/static/netbsd/man3/SQLITE_ERROR_MISSING_COLLSEQ.3 @@ -0,0 +1,262 @@ +.Dd January 24, 2024 +.Dt SQLITE_ERROR_MISSING_COLLSEQ 3 +.Os +.Sh NAME +.Nm SQLITE_ERROR_MISSING_COLLSEQ , +.Nm SQLITE_ERROR_RETRY , +.Nm SQLITE_ERROR_SNAPSHOT , +.Nm SQLITE_IOERR_READ , +.Nm SQLITE_IOERR_SHORT_READ , +.Nm SQLITE_IOERR_WRITE , +.Nm SQLITE_IOERR_FSYNC , +.Nm SQLITE_IOERR_DIR_FSYNC , +.Nm SQLITE_IOERR_TRUNCATE , +.Nm SQLITE_IOERR_FSTAT , +.Nm SQLITE_IOERR_UNLOCK , +.Nm SQLITE_IOERR_RDLOCK , +.Nm SQLITE_IOERR_DELETE , +.Nm SQLITE_IOERR_BLOCKED , +.Nm SQLITE_IOERR_NOMEM , +.Nm SQLITE_IOERR_ACCESS , +.Nm SQLITE_IOERR_CHECKRESERVEDLOCK , +.Nm SQLITE_IOERR_LOCK , +.Nm SQLITE_IOERR_CLOSE , +.Nm SQLITE_IOERR_DIR_CLOSE , +.Nm SQLITE_IOERR_SHMOPEN , +.Nm SQLITE_IOERR_SHMSIZE , +.Nm SQLITE_IOERR_SHMLOCK , +.Nm SQLITE_IOERR_SHMMAP , +.Nm SQLITE_IOERR_SEEK , +.Nm SQLITE_IOERR_DELETE_NOENT , +.Nm SQLITE_IOERR_MMAP , +.Nm SQLITE_IOERR_GETTEMPPATH , +.Nm SQLITE_IOERR_CONVPATH , +.Nm SQLITE_IOERR_VNODE , +.Nm SQLITE_IOERR_AUTH , +.Nm SQLITE_IOERR_BEGIN_ATOMIC , +.Nm SQLITE_IOERR_COMMIT_ATOMIC , +.Nm SQLITE_IOERR_ROLLBACK_ATOMIC , +.Nm SQLITE_IOERR_DATA , +.Nm SQLITE_IOERR_CORRUPTFS , +.Nm SQLITE_IOERR_IN_PAGE , +.Nm SQLITE_LOCKED_SHAREDCACHE , +.Nm SQLITE_LOCKED_VTAB , +.Nm SQLITE_BUSY_RECOVERY , +.Nm SQLITE_BUSY_SNAPSHOT , +.Nm SQLITE_BUSY_TIMEOUT , +.Nm SQLITE_CANTOPEN_NOTEMPDIR , +.Nm SQLITE_CANTOPEN_ISDIR , +.Nm SQLITE_CANTOPEN_FULLPATH , +.Nm SQLITE_CANTOPEN_CONVPATH , +.Nm SQLITE_CANTOPEN_DIRTYWAL , +.Nm SQLITE_CANTOPEN_SYMLINK , +.Nm SQLITE_CORRUPT_VTAB , +.Nm SQLITE_CORRUPT_SEQUENCE , +.Nm SQLITE_CORRUPT_INDEX , +.Nm SQLITE_READONLY_RECOVERY , +.Nm SQLITE_READONLY_CANTLOCK , +.Nm SQLITE_READONLY_ROLLBACK , +.Nm SQLITE_READONLY_DBMOVED , +.Nm SQLITE_READONLY_CANTINIT , +.Nm SQLITE_READONLY_DIRECTORY , +.Nm SQLITE_ABORT_ROLLBACK , +.Nm SQLITE_CONSTRAINT_CHECK , +.Nm SQLITE_CONSTRAINT_COMMITHOOK , +.Nm SQLITE_CONSTRAINT_FOREIGNKEY , +.Nm SQLITE_CONSTRAINT_FUNCTION , +.Nm SQLITE_CONSTRAINT_NOTNULL , +.Nm SQLITE_CONSTRAINT_PRIMARYKEY , +.Nm SQLITE_CONSTRAINT_TRIGGER , +.Nm SQLITE_CONSTRAINT_UNIQUE , +.Nm SQLITE_CONSTRAINT_VTAB , +.Nm SQLITE_CONSTRAINT_ROWID , +.Nm SQLITE_CONSTRAINT_PINNED , +.Nm SQLITE_CONSTRAINT_DATATYPE , +.Nm SQLITE_NOTICE_RECOVER_WAL , +.Nm SQLITE_NOTICE_RECOVER_ROLLBACK , +.Nm SQLITE_NOTICE_RBU , +.Nm SQLITE_WARNING_AUTOINDEX , +.Nm SQLITE_AUTH_USER , +.Nm SQLITE_OK_LOAD_PERMANENTLY , +.Nm SQLITE_OK_SYMLINK +.Nd extended result codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_ERROR_MISSING_COLLSEQ +.Fd #define SQLITE_ERROR_RETRY +.Fd #define SQLITE_ERROR_SNAPSHOT +.Fd #define SQLITE_IOERR_READ +.Fd #define SQLITE_IOERR_SHORT_READ +.Fd #define SQLITE_IOERR_WRITE +.Fd #define SQLITE_IOERR_FSYNC +.Fd #define SQLITE_IOERR_DIR_FSYNC +.Fd #define SQLITE_IOERR_TRUNCATE +.Fd #define SQLITE_IOERR_FSTAT +.Fd #define SQLITE_IOERR_UNLOCK +.Fd #define SQLITE_IOERR_RDLOCK +.Fd #define SQLITE_IOERR_DELETE +.Fd #define SQLITE_IOERR_BLOCKED +.Fd #define SQLITE_IOERR_NOMEM +.Fd #define SQLITE_IOERR_ACCESS +.Fd #define SQLITE_IOERR_CHECKRESERVEDLOCK +.Fd #define SQLITE_IOERR_LOCK +.Fd #define SQLITE_IOERR_CLOSE +.Fd #define SQLITE_IOERR_DIR_CLOSE +.Fd #define SQLITE_IOERR_SHMOPEN +.Fd #define SQLITE_IOERR_SHMSIZE +.Fd #define SQLITE_IOERR_SHMLOCK +.Fd #define SQLITE_IOERR_SHMMAP +.Fd #define SQLITE_IOERR_SEEK +.Fd #define SQLITE_IOERR_DELETE_NOENT +.Fd #define SQLITE_IOERR_MMAP +.Fd #define SQLITE_IOERR_GETTEMPPATH +.Fd #define SQLITE_IOERR_CONVPATH +.Fd #define SQLITE_IOERR_VNODE +.Fd #define SQLITE_IOERR_AUTH +.Fd #define SQLITE_IOERR_BEGIN_ATOMIC +.Fd #define SQLITE_IOERR_COMMIT_ATOMIC +.Fd #define SQLITE_IOERR_ROLLBACK_ATOMIC +.Fd #define SQLITE_IOERR_DATA +.Fd #define SQLITE_IOERR_CORRUPTFS +.Fd #define SQLITE_IOERR_IN_PAGE +.Fd #define SQLITE_LOCKED_SHAREDCACHE +.Fd #define SQLITE_LOCKED_VTAB +.Fd #define SQLITE_BUSY_RECOVERY +.Fd #define SQLITE_BUSY_SNAPSHOT +.Fd #define SQLITE_BUSY_TIMEOUT +.Fd #define SQLITE_CANTOPEN_NOTEMPDIR +.Fd #define SQLITE_CANTOPEN_ISDIR +.Fd #define SQLITE_CANTOPEN_FULLPATH +.Fd #define SQLITE_CANTOPEN_CONVPATH +.Fd #define SQLITE_CANTOPEN_DIRTYWAL +.Fd #define SQLITE_CANTOPEN_SYMLINK +.Fd #define SQLITE_CORRUPT_VTAB +.Fd #define SQLITE_CORRUPT_SEQUENCE +.Fd #define SQLITE_CORRUPT_INDEX +.Fd #define SQLITE_READONLY_RECOVERY +.Fd #define SQLITE_READONLY_CANTLOCK +.Fd #define SQLITE_READONLY_ROLLBACK +.Fd #define SQLITE_READONLY_DBMOVED +.Fd #define SQLITE_READONLY_CANTINIT +.Fd #define SQLITE_READONLY_DIRECTORY +.Fd #define SQLITE_ABORT_ROLLBACK +.Fd #define SQLITE_CONSTRAINT_CHECK +.Fd #define SQLITE_CONSTRAINT_COMMITHOOK +.Fd #define SQLITE_CONSTRAINT_FOREIGNKEY +.Fd #define SQLITE_CONSTRAINT_FUNCTION +.Fd #define SQLITE_CONSTRAINT_NOTNULL +.Fd #define SQLITE_CONSTRAINT_PRIMARYKEY +.Fd #define SQLITE_CONSTRAINT_TRIGGER +.Fd #define SQLITE_CONSTRAINT_UNIQUE +.Fd #define SQLITE_CONSTRAINT_VTAB +.Fd #define SQLITE_CONSTRAINT_ROWID +.Fd #define SQLITE_CONSTRAINT_PINNED +.Fd #define SQLITE_CONSTRAINT_DATATYPE +.Fd #define SQLITE_NOTICE_RECOVER_WAL +.Fd #define SQLITE_NOTICE_RECOVER_ROLLBACK +.Fd #define SQLITE_NOTICE_RBU +.Fd #define SQLITE_WARNING_AUTOINDEX +.Fd #define SQLITE_AUTH_USER +.Fd #define SQLITE_OK_LOAD_PERMANENTLY +.Fd #define SQLITE_OK_SYMLINK +.Sh DESCRIPTION +In its default configuration, SQLite API routines return one of 30 +integer result codes. +However, experience has shown that many of these result codes are too +coarse-grained. +They do not provide as much information about problems as programmers +might like. +In an effort to address this, newer versions of SQLite (version 3.3.8 +dateof:3.3.8 and later) include support for additional +result codes that provide more detailed information about errors. +These extended result codes are enabled or disabled +on a per database connection basis using the +.Fn sqlite3_extended_result_codes +API. +Or, the extended code for the most recent error can be obtained using +.Fn sqlite3_extended_errcode . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 479. +.Bd -literal +#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8)) +#define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8)) +#define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8)) +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) +#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8)) +#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) +#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) +#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) +#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) +#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8)) +#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8)) +#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8)) +#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8)) +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8)) +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8)) +#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8)) +#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8)) +#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8)) +#define SQLITE_IOERR_DATA (SQLITE_IOERR | (32<<8)) +#define SQLITE_IOERR_CORRUPTFS (SQLITE_IOERR | (33<<8)) +#define SQLITE_IOERR_IN_PAGE (SQLITE_IOERR | (34<<8)) +#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) +#define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8)) +#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) +#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) +#define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3<<8)) +#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) +#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) +#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) +#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) +#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */ +#define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6<<8)) +#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) +#define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8)) +#define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3<<8)) +#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) +#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) +#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) +#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) +#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8)) +#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8)) +#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) +#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8)) +#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8)) +#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8)) +#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8)) +#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) +#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) +#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) +#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) +#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) +#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) +#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8)) +#define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8)) +#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) +#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) +#define SQLITE_NOTICE_RBU (SQLITE_NOTICE | (3<<8)) +#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) +#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) +#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) +#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_errcode 3 , +.Xr sqlite3_extended_result_codes 3 diff --git a/static/netbsd/man3/SQLITE_FCNTL_LOCKSTATE.3 b/static/netbsd/man3/SQLITE_FCNTL_LOCKSTATE.3 new file mode 100644 index 00000000..6ea1b260 --- /dev/null +++ b/static/netbsd/man3/SQLITE_FCNTL_LOCKSTATE.3 @@ -0,0 +1,519 @@ +.Dd January 24, 2024 +.Dt SQLITE_FCNTL_LOCKSTATE 3 +.Os +.Sh NAME +.Nm SQLITE_FCNTL_LOCKSTATE , +.Nm SQLITE_FCNTL_GET_LOCKPROXYFILE , +.Nm SQLITE_FCNTL_SET_LOCKPROXYFILE , +.Nm SQLITE_FCNTL_LAST_ERRNO , +.Nm SQLITE_FCNTL_SIZE_HINT , +.Nm SQLITE_FCNTL_CHUNK_SIZE , +.Nm SQLITE_FCNTL_FILE_POINTER , +.Nm SQLITE_FCNTL_SYNC_OMITTED , +.Nm SQLITE_FCNTL_WIN32_AV_RETRY , +.Nm SQLITE_FCNTL_PERSIST_WAL , +.Nm SQLITE_FCNTL_OVERWRITE , +.Nm SQLITE_FCNTL_VFSNAME , +.Nm SQLITE_FCNTL_POWERSAFE_OVERWRITE , +.Nm SQLITE_FCNTL_PRAGMA , +.Nm SQLITE_FCNTL_BUSYHANDLER , +.Nm SQLITE_FCNTL_TEMPFILENAME , +.Nm SQLITE_FCNTL_MMAP_SIZE , +.Nm SQLITE_FCNTL_TRACE , +.Nm SQLITE_FCNTL_HAS_MOVED , +.Nm SQLITE_FCNTL_SYNC , +.Nm SQLITE_FCNTL_COMMIT_PHASETWO , +.Nm SQLITE_FCNTL_WIN32_SET_HANDLE , +.Nm SQLITE_FCNTL_WAL_BLOCK , +.Nm SQLITE_FCNTL_ZIPVFS , +.Nm SQLITE_FCNTL_RBU , +.Nm SQLITE_FCNTL_VFS_POINTER , +.Nm SQLITE_FCNTL_JOURNAL_POINTER , +.Nm SQLITE_FCNTL_WIN32_GET_HANDLE , +.Nm SQLITE_FCNTL_PDB , +.Nm SQLITE_FCNTL_BEGIN_ATOMIC_WRITE , +.Nm SQLITE_FCNTL_COMMIT_ATOMIC_WRITE , +.Nm SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE , +.Nm SQLITE_FCNTL_LOCK_TIMEOUT , +.Nm SQLITE_FCNTL_DATA_VERSION , +.Nm SQLITE_FCNTL_SIZE_LIMIT , +.Nm SQLITE_FCNTL_CKPT_DONE , +.Nm SQLITE_FCNTL_RESERVE_BYTES , +.Nm SQLITE_FCNTL_CKPT_START , +.Nm SQLITE_FCNTL_EXTERNAL_READER , +.Nm SQLITE_FCNTL_CKSM_FILE , +.Nm SQLITE_FCNTL_RESET_CACHE +.Nd standard file control opcodes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_FCNTL_LOCKSTATE +.Fd #define SQLITE_FCNTL_GET_LOCKPROXYFILE +.Fd #define SQLITE_FCNTL_SET_LOCKPROXYFILE +.Fd #define SQLITE_FCNTL_LAST_ERRNO +.Fd #define SQLITE_FCNTL_SIZE_HINT +.Fd #define SQLITE_FCNTL_CHUNK_SIZE +.Fd #define SQLITE_FCNTL_FILE_POINTER +.Fd #define SQLITE_FCNTL_SYNC_OMITTED +.Fd #define SQLITE_FCNTL_WIN32_AV_RETRY +.Fd #define SQLITE_FCNTL_PERSIST_WAL +.Fd #define SQLITE_FCNTL_OVERWRITE +.Fd #define SQLITE_FCNTL_VFSNAME +.Fd #define SQLITE_FCNTL_POWERSAFE_OVERWRITE +.Fd #define SQLITE_FCNTL_PRAGMA +.Fd #define SQLITE_FCNTL_BUSYHANDLER +.Fd #define SQLITE_FCNTL_TEMPFILENAME +.Fd #define SQLITE_FCNTL_MMAP_SIZE +.Fd #define SQLITE_FCNTL_TRACE +.Fd #define SQLITE_FCNTL_HAS_MOVED +.Fd #define SQLITE_FCNTL_SYNC +.Fd #define SQLITE_FCNTL_COMMIT_PHASETWO +.Fd #define SQLITE_FCNTL_WIN32_SET_HANDLE +.Fd #define SQLITE_FCNTL_WAL_BLOCK +.Fd #define SQLITE_FCNTL_ZIPVFS +.Fd #define SQLITE_FCNTL_RBU +.Fd #define SQLITE_FCNTL_VFS_POINTER +.Fd #define SQLITE_FCNTL_JOURNAL_POINTER +.Fd #define SQLITE_FCNTL_WIN32_GET_HANDLE +.Fd #define SQLITE_FCNTL_PDB +.Fd #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE +.Fd #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE +.Fd #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE +.Fd #define SQLITE_FCNTL_LOCK_TIMEOUT +.Fd #define SQLITE_FCNTL_DATA_VERSION +.Fd #define SQLITE_FCNTL_SIZE_LIMIT +.Fd #define SQLITE_FCNTL_CKPT_DONE +.Fd #define SQLITE_FCNTL_RESERVE_BYTES +.Fd #define SQLITE_FCNTL_CKPT_START +.Fd #define SQLITE_FCNTL_EXTERNAL_READER +.Fd #define SQLITE_FCNTL_CKSM_FILE +.Fd #define SQLITE_FCNTL_RESET_CACHE +.Sh DESCRIPTION +These integer constants are opcodes for the xFileControl method of +the sqlite3_io_methods object and for the +.Fn sqlite3_file_control +interface. +.Bl -bullet +.It +The SQLITE_FCNTL_LOCKSTATE opcode is used for +debugging. +This opcode causes the xFileControl method to write the current state +of the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, +SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, +or SQLITE_LOCK_EXCLUSIVE) into an integer that +the pArg argument points to. +This capability is only available if SQLite is compiled with SQLITE_DEBUG. +.It +The SQLITE_FCNTL_SIZE_HINT opcode is used by +SQLite to give the VFS layer a hint of how large the database file +will grow to be during the current transaction. +This hint is not guaranteed to be accurate but it is often close. +The underlying VFS might choose to preallocate database file space +based on this hint in order to help writes to the database file run +faster. +.It +The SQLITE_FCNTL_SIZE_LIMIT opcode is used by +in-memory VFS that implements +.Fn sqlite3_deserialize +to set an upper bound on the size of the in-memory database. +The argument is a pointer to a sqlite3_int64. +If the integer pointed to is negative, then it is filled in with the +current limit. +Otherwise the limit is set to the larger of the value of the integer +pointed to and the current database size. +The integer pointed to is set to the new limit. +.It +The SQLITE_FCNTL_CHUNK_SIZE opcode is used to +request that the VFS extends and truncates the database file in chunks +of a size specified by the user. +The fourth argument to +.Fn sqlite3_file_control +should point to an integer (type int) containing the new chunk-size +to use for the nominated database. +Allocating database file space in large chunks (say 1MB at a time), +may reduce file-system fragmentation and improve performance on some +systems. +.It +The SQLITE_FCNTL_FILE_POINTER opcode is used +to obtain a pointer to the sqlite3_file object associated +with a particular database connection. +See also SQLITE_FCNTL_JOURNAL_POINTER. +.It +The SQLITE_FCNTL_JOURNAL_POINTER opcode +is used to obtain a pointer to the sqlite3_file object +associated with the journal file (either the rollback journal +or the write-ahead log) for a particular database connection. +See also SQLITE_FCNTL_FILE_POINTER. +.It +No longer in use. +.It +The SQLITE_FCNTL_SYNC opcode is generated internally +by SQLite and sent to the VFS immediately before the xSync method is +invoked on a database file descriptor. +Or, if the xSync method is not invoked because the user has configured +SQLite with PRAGMA synchronous=OFF it is invoked +in place of the xSync method. +In most cases, the pointer argument passed with this file-control is +NULL. +However, if the database file is being synced as part of a multi-database +commit, the argument points to a nul-terminated string containing the +transactions super-journal file name. +VFSes that do not need this signal should silently ignore this opcode. +Applications should not call +.Fn sqlite3_file_control +with this opcode as doing so may disrupt the operation of the specialized +VFSes that do require it. +.It +The SQLITE_FCNTL_COMMIT_PHASETWO opcode +is generated internally by SQLite and sent to the VFS after a transaction +has been committed immediately but before the database is unlocked. +VFSes that do not need this signal should silently ignore this opcode. +Applications should not call +.Fn sqlite3_file_control +with this opcode as doing so may disrupt the operation of the specialized +VFSes that do require it. +.It +The SQLITE_FCNTL_WIN32_AV_RETRY opcode is +used to configure automatic retry counts and intervals for certain +disk I/O operations for the windows VFS in order to provide robustness +in the presence of anti-virus programs. +By default, the windows VFS will retry file read, file write, and file +delete operations up to 10 times, with a delay of 25 milliseconds before +the first retry and with the delay increasing by an additional 25 milliseconds +with each subsequent retry. +This opcode allows these two values (10 retries and 25 milliseconds +of delay) to be adjusted. +The values are changed for all database connections within the same +process. +The argument is a pointer to an array of two integers where the first +integer is the new retry count and the second integer is the delay. +If either integer is negative, then the setting is not changed but +instead the prior value of that setting is written into the array entry, +allowing the current retry settings to be interrogated. +The zDbName parameter is ignored. +.It +The SQLITE_FCNTL_PERSIST_WAL opcode is used +to set or query the persistent Write Ahead Log setting. +By default, the auxiliary write ahead log (WAL file) and shared +memory files used for transaction control are automatically deleted +when the latest connection to the database closes. +Setting persistent WAL mode causes those files to persist after close. +Persisting the files is useful when other processes that do not have +write permission on the directory containing the database file want +to read the database file, as the WAL and shared memory files must +exist in order for the database to be readable. +The fourth parameter to +.Fn sqlite3_file_control +for this opcode should be a pointer to an integer. +That integer is 0 to disable persistent WAL mode or 1 to enable persistent +WAL mode. +If the integer is -1, then it is overwritten with the current WAL persistence +setting. +.It +The SQLITE_FCNTL_POWERSAFE_OVERWRITE +opcode is used to set or query the persistent "powersafe-overwrite" +or "PSOW" setting. +The PSOW setting determines the SQLITE_IOCAP_POWERSAFE_OVERWRITE +bit of the xDeviceCharacteristics methods. +The fourth parameter to +.Fn sqlite3_file_control +for this opcode should be a pointer to an integer. +That integer is 0 to disable zero-damage mode or 1 to enable zero-damage +mode. +If the integer is -1, then it is overwritten with the current zero-damage +mode setting. +.It +The SQLITE_FCNTL_OVERWRITE opcode is invoked +by SQLite after opening a write transaction to indicate that, unless +it is rolled back for some reason, the entire database file will be +overwritten by the current transaction. +This is used by VACUUM operations. +.It +The SQLITE_FCNTL_VFSNAME opcode can be used to +obtain the names of all VFSes in the VFS stack. +The names are of all VFS shims and the final bottom-level VFS are written +into memory obtained from +.Fn sqlite3_malloc +and the result is stored in the char* variable that the fourth parameter +of +.Fn sqlite3_file_control +points to. +The caller is responsible for freeing the memory when done. +As with all file-control actions, there is no guarantee that this will +actually do anything. +Callers should initialize the char* variable to a NULL pointer in case +this file-control is not implemented. +This file-control is intended for diagnostic use only. +.It +The SQLITE_FCNTL_VFS_POINTER opcode finds a +pointer to the top-level VFSes currently in use. +The argument X in sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) +must be of type "sqlite3_vfs **". +This opcodes will set *X to a pointer to the top-level VFS. +When there are multiple VFS shims in the stack, this opcode finds the +upper-most shim only. +.It +Whenever a PRAGMA statement is parsed, an SQLITE_FCNTL_PRAGMA +file control is sent to the open sqlite3_file object corresponding +to the database file to which the pragma statement refers. +The argument to the SQLITE_FCNTL_PRAGMA file control +is an array of pointers to strings (char**) in which the second element +of the array is the name of the pragma and the third element is the +argument to the pragma or NULL if the pragma has no argument. +The handler for an SQLITE_FCNTL_PRAGMA file control +can optionally make the first element of the char** argument point +to a string obtained from +.Fn sqlite3_mprintf +or the equivalent and that string will become the result of the pragma +or the error message if the pragma fails. +If the SQLITE_FCNTL_PRAGMA file control returns +SQLITE_NOTFOUND, then normal PRAGMA processing +continues. +If the SQLITE_FCNTL_PRAGMA file control returns +SQLITE_OK, then the parser assumes that the VFS has handled +the PRAGMA itself and the parser generates a no-op prepared statement +if result string is NULL, or that returns a copy of the result string +if the string is non-NULL. +If the SQLITE_FCNTL_PRAGMA file control returns +any result code other than SQLITE_OK or SQLITE_NOTFOUND, +that means that the VFS encountered an error while handling the PRAGMA +and the compilation of the PRAGMA fails with an error. +The SQLITE_FCNTL_PRAGMA file control occurs at the +beginning of pragma statement analysis and so it is able to override +built-in PRAGMA statements. +.It +The SQLITE_FCNTL_BUSYHANDLER file-control may +be invoked by SQLite on the database file handle shortly after it is +opened in order to provide a custom VFS with access to the connection's +busy-handler callback. +The argument is of type (void**) - an array of two (void *) values. +The first (void *) actually points to a function of type (int (*)(void +*)). +In order to invoke the connection's busy-handler, this function should +be invoked with the second (void *) in the array as the only argument. +If it returns non-zero, then the operation should be retried. +If it returns zero, the custom VFS should abandon the current operation. +.It +Applications can invoke the SQLITE_FCNTL_TEMPFILENAME +file-control to have SQLite generate a temporary filename using the +same algorithm that is followed to generate temporary filenames for +TEMP tables and other internal uses. +The argument should be a char** which will be filled with the filename +written into memory obtained from +.Fn sqlite3_malloc . +The caller should invoke +.Fn sqlite3_free +on the result to avoid a memory leak. +.It +The SQLITE_FCNTL_MMAP_SIZE file control is used +to query or set the maximum number of bytes that will be used for memory-mapped +I/O. +The argument is a pointer to a value of type sqlite3_int64 that is +an advisory maximum number of bytes in the file to memory map. +The pointer is overwritten with the old value. +The limit is not changed if the value originally pointed to is negative, +and so the current limit can be queried by passing in a pointer to +a negative number. +This file-control is used internally to implement PRAGMA mmap_size. +.It +The SQLITE_FCNTL_TRACE file control provides advisory +information to the VFS about what the higher layers of the SQLite stack +are doing. +This file control is used by some VFS activity tracing shims. +The argument is a zero-terminated string. +Higher layers in the SQLite stack may generate instances of this file +control if the SQLITE_USE_FCNTL_TRACE compile-time +option is enabled. +.It +The SQLITE_FCNTL_HAS_MOVED file control interprets +its argument as a pointer to an integer and it writes a boolean into +that integer depending on whether or not the file has been renamed, +moved, or deleted since it was first opened. +.It +The SQLITE_FCNTL_WIN32_GET_HANDLE opcode +can be used to obtain the underlying native file handle associated +with a file handle. +This file control interprets its argument as a pointer to a native +file handle and writes the resulting value there. +.It +The SQLITE_FCNTL_WIN32_SET_HANDLE opcode +is used for debugging. +This opcode causes the xFileControl method to swap the file handle +with the one pointed to by the pArg argument. +This capability is used during testing and only needs to be supported +when SQLITE_TEST is defined. +.It +The SQLITE_FCNTL_WAL_BLOCK is a signal to the +VFS layer that it might be advantageous to block on the next WAL lock +if the lock is not immediately available. +The WAL subsystem issues this signal during rare circumstances in order +to fix a problem with priority inversion. +Applications should \fBnot\fP use this file-control. +.It +The SQLITE_FCNTL_ZIPVFS opcode is implemented by +zipvfs only. +All other VFS should return SQLITE_NOTFOUND for this opcode. +.It +The SQLITE_FCNTL_RBU opcode is implemented by the special +VFS used by the RBU extension only. +All other VFS should return SQLITE_NOTFOUND for this opcode. +.It +If the SQLITE_FCNTL_BEGIN_ATOMIC_WRITE +opcode returns SQLITE_OK, then the file descriptor is placed in "batch +write mode", which means all subsequent write operations will be deferred +and done atomically at the next SQLITE_FCNTL_COMMIT_ATOMIC_WRITE. +Systems that do not support batch atomic writes will return SQLITE_NOTFOUND. +Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to +the closing SQLITE_FCNTL_COMMIT_ATOMIC_WRITE +or SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE, +SQLite will make no VFS interface calls on the same sqlite3_file +file descriptor except for calls to the xWrite method and the xFileControl +method with SQLITE_FCNTL_SIZE_HINT. +.It +The SQLITE_FCNTL_COMMIT_ATOMIC_WRITE +opcode causes all write operations since the previous successful call +to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to +be performed atomically. +This file control returns SQLITE_OK if and only if the writes +were all performed successfully and have been committed to persistent +storage. +Regardless of whether or not it is successful, this file control takes +the file descriptor out of batch write mode so that all subsequent +write operations are independent. +SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without a +prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE. +.It +The SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE +opcode causes all write operations since the previous successful call +to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to +be rolled back. +This file control takes the file descriptor out of batch write mode +so that all subsequent write operations are independent. +SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without +a prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE. +.It +The SQLITE_FCNTL_LOCK_TIMEOUT opcode is used +to configure a VFS to block for up to M milliseconds before failing +when attempting to obtain a file lock using the xLock or xShmLock methods +of the VFS. +The parameter is a pointer to a 32-bit signed integer that contains +the value that M is to be set to. +Before returning, the 32-bit signed integer is overwritten with the +previous value of M. +.It +The SQLITE_FCNTL_DATA_VERSION opcode is used +to detect changes to a database file. +The argument is a pointer to a 32-bit unsigned integer. +The "data version" for the pager is written into the pointer. +The "data version" changes whenever any change occurs to the corresponding +database file, either through SQL statements on the same database connection +or through transactions committed by separate database connections +possibly in other processes. +The +.Fn sqlite3_total_changes +interface can be used to find if any database on the connection has +changed, but that interface responds to changes on TEMP as well as +MAIN and does not provide a mechanism to detect changes to MAIN only. +Also, the +.Fn sqlite3_total_changes +interface responds to internal changes only and omits changes made +by other database connections. +The PRAGMA data_version command provides a mechanism +to detect changes to a single attached database that occur due to other +database connections, but omits changes implemented by the database +connection on which it is called. +This file control is the only mechanism to detect changes that happen +either internally or externally and that are associated with a particular +attached database. +.It +The SQLITE_FCNTL_CKPT_START opcode is invoked +from within a checkpoint in wal mode before the client starts to copy +pages from the wal file to the database file. +.It +The SQLITE_FCNTL_CKPT_DONE opcode is invoked +from within a checkpoint in wal mode after the client has finished +copying pages from the wal file to the database file, but before the +*-shm file is updated to record the fact that the pages have been checkpointed. +.It +The EXPERIMENTAL SQLITE_FCNTL_EXTERNAL_READER +opcode is used to detect whether or not there is a database client +in another process with a wal-mode transaction open on the database +or not. +It is only available on unix.The (void*) argument passed with this +file-control should be a pointer to a value of type (int). +The integer value is set to 1 if the database is a wal mode database +and there exists at least one client in another process that currently +has an SQL transaction open on the database. +It is set to 0 if the database is not a wal-mode db, or if there is +no such connection in any other process. +This opcode cannot be used to detect transactions opened by clients +within the current process, only within other processes. +.It +The SQLITE_FCNTL_CKSM_FILE opcode is for use +internally by the checksum VFS shim only. +.It +If there is currently no transaction open on the database, and the +database is not a temp db, then the SQLITE_FCNTL_RESET_CACHE +file-control purges the contents of the in-memory page cache. +If there is an open transaction, or if the db is a temp-db, this opcode +is a no-op, not an error. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 862. +.Bd -literal +#define SQLITE_FCNTL_LOCKSTATE 1 +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2 +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3 +#define SQLITE_FCNTL_LAST_ERRNO 4 +#define SQLITE_FCNTL_SIZE_HINT 5 +#define SQLITE_FCNTL_CHUNK_SIZE 6 +#define SQLITE_FCNTL_FILE_POINTER 7 +#define SQLITE_FCNTL_SYNC_OMITTED 8 +#define SQLITE_FCNTL_WIN32_AV_RETRY 9 +#define SQLITE_FCNTL_PERSIST_WAL 10 +#define SQLITE_FCNTL_OVERWRITE 11 +#define SQLITE_FCNTL_VFSNAME 12 +#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13 +#define SQLITE_FCNTL_PRAGMA 14 +#define SQLITE_FCNTL_BUSYHANDLER 15 +#define SQLITE_FCNTL_TEMPFILENAME 16 +#define SQLITE_FCNTL_MMAP_SIZE 18 +#define SQLITE_FCNTL_TRACE 19 +#define SQLITE_FCNTL_HAS_MOVED 20 +#define SQLITE_FCNTL_SYNC 21 +#define SQLITE_FCNTL_COMMIT_PHASETWO 22 +#define SQLITE_FCNTL_WIN32_SET_HANDLE 23 +#define SQLITE_FCNTL_WAL_BLOCK 24 +#define SQLITE_FCNTL_ZIPVFS 25 +#define SQLITE_FCNTL_RBU 26 +#define SQLITE_FCNTL_VFS_POINTER 27 +#define SQLITE_FCNTL_JOURNAL_POINTER 28 +#define SQLITE_FCNTL_WIN32_GET_HANDLE 29 +#define SQLITE_FCNTL_PDB 30 +#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31 +#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32 +#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33 +#define SQLITE_FCNTL_LOCK_TIMEOUT 34 +#define SQLITE_FCNTL_DATA_VERSION 35 +#define SQLITE_FCNTL_SIZE_LIMIT 36 +#define SQLITE_FCNTL_CKPT_DONE 37 +#define SQLITE_FCNTL_RESERVE_BYTES 38 +#define SQLITE_FCNTL_CKPT_START 39 +#define SQLITE_FCNTL_EXTERNAL_READER 40 +#define SQLITE_FCNTL_CKSM_FILE 41 +#define SQLITE_FCNTL_RESET_CACHE 42 +.Ed +.Sh SEE ALSO +.Xr sqlite3_deserialize 3 , +.Xr sqlite3_file 3 , +.Xr sqlite3_file_control 3 , +.Xr sqlite3_io_methods 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mprintf 3 , +.Xr sqlite3_total_changes 3 , +.Xr sqlite3_vfs 3 , +.Xr sqlite_int64 3 , +.Xr SQLITE_IOCAP_ATOMIC 3 , +.Xr SQLITE_LOCK_NONE 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/SQLITE_INDEX_CONSTRAINT_EQ.3 b/static/netbsd/man3/SQLITE_INDEX_CONSTRAINT_EQ.3 new file mode 100644 index 00000000..a108b181 --- /dev/null +++ b/static/netbsd/man3/SQLITE_INDEX_CONSTRAINT_EQ.3 @@ -0,0 +1,105 @@ +.Dd January 24, 2024 +.Dt SQLITE_INDEX_CONSTRAINT_EQ 3 +.Os +.Sh NAME +.Nm SQLITE_INDEX_CONSTRAINT_EQ , +.Nm SQLITE_INDEX_CONSTRAINT_GT , +.Nm SQLITE_INDEX_CONSTRAINT_LE , +.Nm SQLITE_INDEX_CONSTRAINT_LT , +.Nm SQLITE_INDEX_CONSTRAINT_GE , +.Nm SQLITE_INDEX_CONSTRAINT_MATCH , +.Nm SQLITE_INDEX_CONSTRAINT_LIKE , +.Nm SQLITE_INDEX_CONSTRAINT_GLOB , +.Nm SQLITE_INDEX_CONSTRAINT_REGEXP , +.Nm SQLITE_INDEX_CONSTRAINT_NE , +.Nm SQLITE_INDEX_CONSTRAINT_ISNOT , +.Nm SQLITE_INDEX_CONSTRAINT_ISNOTNULL , +.Nm SQLITE_INDEX_CONSTRAINT_ISNULL , +.Nm SQLITE_INDEX_CONSTRAINT_IS , +.Nm SQLITE_INDEX_CONSTRAINT_LIMIT , +.Nm SQLITE_INDEX_CONSTRAINT_OFFSET , +.Nm SQLITE_INDEX_CONSTRAINT_FUNCTION +.Nd virtual table constraint operator codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_INDEX_CONSTRAINT_EQ +.Fd #define SQLITE_INDEX_CONSTRAINT_GT +.Fd #define SQLITE_INDEX_CONSTRAINT_LE +.Fd #define SQLITE_INDEX_CONSTRAINT_LT +.Fd #define SQLITE_INDEX_CONSTRAINT_GE +.Fd #define SQLITE_INDEX_CONSTRAINT_MATCH +.Fd #define SQLITE_INDEX_CONSTRAINT_LIKE +.Fd #define SQLITE_INDEX_CONSTRAINT_GLOB +.Fd #define SQLITE_INDEX_CONSTRAINT_REGEXP +.Fd #define SQLITE_INDEX_CONSTRAINT_NE +.Fd #define SQLITE_INDEX_CONSTRAINT_ISNOT +.Fd #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL +.Fd #define SQLITE_INDEX_CONSTRAINT_ISNULL +.Fd #define SQLITE_INDEX_CONSTRAINT_IS +.Fd #define SQLITE_INDEX_CONSTRAINT_LIMIT +.Fd #define SQLITE_INDEX_CONSTRAINT_OFFSET +.Fd #define SQLITE_INDEX_CONSTRAINT_FUNCTION +.Sh DESCRIPTION +These macros define the allowed values for the sqlite3_index_info.aConstraint[].op +field. +Each value represents an operator that is part of a constraint term +in the WHERE clause of a query that uses a virtual table. +.Pp +The left-hand operand of the operator is given by the corresponding +aConstraint[].iColumn field. +An iColumn of -1 indicates the left-hand operand is the rowid. +The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET +operators have no left-hand operand, and so for those operators the +corresponding aConstraint[].iColumn is meaningless and should not be +used. +.Pp +All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through value +255 are reserved to represent functions that are overloaded by the +xFindFunction method of the virtual table implementation. +.Pp +The right-hand operands for each constraint might be accessible using +the +.Fn sqlite3_vtab_rhs_value +interface. +Usually the right-hand operand is only available if it appears as a +single constant literal in the input SQL. +If the right-hand operand is another column or an expression (even +a constant expression) or a parameter, then the sqlite3_vtab_rhs_value() +probably will not be able to extract it. +The SQLITE_INDEX_CONSTRAINT_ISNULL and SQLITE_INDEX_CONSTRAINT_ISNOTNULL +operators have no right-hand operand and hence calls to sqlite3_vtab_rhs_value() +for those operators will always return SQLITE_NOTFOUND. +.Pp +The collating sequence to be used for comparison can be found using +the +.Fn sqlite3_vtab_collation +interface. +For most real-world virtual tables, the collating sequence of constraints +does not matter (for example because the constraints are numeric) and +so the sqlite3_vtab_collation() interface is not commonly needed. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7474. +.Bd -literal +#define SQLITE_INDEX_CONSTRAINT_EQ 2 +#define SQLITE_INDEX_CONSTRAINT_GT 4 +#define SQLITE_INDEX_CONSTRAINT_LE 8 +#define SQLITE_INDEX_CONSTRAINT_LT 16 +#define SQLITE_INDEX_CONSTRAINT_GE 32 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64 +#define SQLITE_INDEX_CONSTRAINT_LIKE 65 +#define SQLITE_INDEX_CONSTRAINT_GLOB 66 +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 +#define SQLITE_INDEX_CONSTRAINT_NE 68 +#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 +#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 +#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 +#define SQLITE_INDEX_CONSTRAINT_IS 72 +#define SQLITE_INDEX_CONSTRAINT_LIMIT 73 +#define SQLITE_INDEX_CONSTRAINT_OFFSET 74 +#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 +.Ed +.Sh SEE ALSO +.Xr sqlite3_index_info 3 , +.Xr sqlite3_vtab_collation 3 , +.Xr sqlite3_vtab_rhs_value 3 diff --git a/static/netbsd/man3/SQLITE_INDEX_SCAN_UNIQUE.3 b/static/netbsd/man3/SQLITE_INDEX_SCAN_UNIQUE.3 new file mode 100644 index 00000000..9464063b --- /dev/null +++ b/static/netbsd/man3/SQLITE_INDEX_SCAN_UNIQUE.3 @@ -0,0 +1,20 @@ +.Dd January 24, 2024 +.Dt SQLITE_INDEX_SCAN_UNIQUE 3 +.Os +.Sh NAME +.Nm SQLITE_INDEX_SCAN_UNIQUE +.Nd virtual table scan flags +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_INDEX_SCAN_UNIQUE +.Sh DESCRIPTION +Virtual table implementations are allowed to set the sqlite3_index_info.idxFlags +field to some combination of these bits. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7465. +.Bd -literal +#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_index_info 3 diff --git a/static/netbsd/man3/SQLITE_INTEGER.3 b/static/netbsd/man3/SQLITE_INTEGER.3 new file mode 100644 index 00000000..71d999be --- /dev/null +++ b/static/netbsd/man3/SQLITE_INTEGER.3 @@ -0,0 +1,55 @@ +.Dd January 24, 2024 +.Dt SQLITE_INTEGER 3 +.Os +.Sh NAME +.Nm SQLITE_INTEGER , +.Nm SQLITE_FLOAT , +.Nm SQLITE_BLOB , +.Nm SQLITE_NULL , +.Nm SQLITE_TEXT , +.Nm SQLITE3_TEXT +.Nd fundamental datatypes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_INTEGER +.Fd #define SQLITE_FLOAT +.Fd #define SQLITE_BLOB +.Fd #define SQLITE_NULL +.Fd #define SQLITE_TEXT +.Fd #define SQLITE3_TEXT +.Sh DESCRIPTION +Every value in SQLite has one of five fundamental datatypes: +.Bl -bullet +.It +64-bit signed integer +.It +64-bit IEEE floating point number +.It +string +.It +BLOB +.It +NULL +.El +.Pp +These constants are codes for each of those types. +.Pp +Note that the SQLITE_TEXT constant was also used in SQLite version +2 for a completely different meaning. +Software that links against both SQLite version 2 and SQLite version +3 should use SQLITE3_TEXT, not SQLITE_TEXT. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5009. +.Bd -literal +#define SQLITE_INTEGER 1 +#define SQLITE_FLOAT 2 +#define SQLITE_BLOB 4 +#define SQLITE_NULL 5 +#ifdef SQLITE_TEXT +# undef SQLITE_TEXT +#else +# define SQLITE_TEXT 3 +#endif +#define SQLITE3_TEXT 3 +.Ed diff --git a/static/netbsd/man3/SQLITE_IOCAP_ATOMIC.3 b/static/netbsd/man3/SQLITE_IOCAP_ATOMIC.3 new file mode 100644 index 00000000..85622233 --- /dev/null +++ b/static/netbsd/man3/SQLITE_IOCAP_ATOMIC.3 @@ -0,0 +1,89 @@ +.Dd January 24, 2024 +.Dt SQLITE_IOCAP_ATOMIC 3 +.Os +.Sh NAME +.Nm SQLITE_IOCAP_ATOMIC , +.Nm SQLITE_IOCAP_ATOMIC512 , +.Nm SQLITE_IOCAP_ATOMIC1K , +.Nm SQLITE_IOCAP_ATOMIC2K , +.Nm SQLITE_IOCAP_ATOMIC4K , +.Nm SQLITE_IOCAP_ATOMIC8K , +.Nm SQLITE_IOCAP_ATOMIC16K , +.Nm SQLITE_IOCAP_ATOMIC32K , +.Nm SQLITE_IOCAP_ATOMIC64K , +.Nm SQLITE_IOCAP_SAFE_APPEND , +.Nm SQLITE_IOCAP_SEQUENTIAL , +.Nm SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN , +.Nm SQLITE_IOCAP_POWERSAFE_OVERWRITE , +.Nm SQLITE_IOCAP_IMMUTABLE , +.Nm SQLITE_IOCAP_BATCH_ATOMIC +.Nd device characteristics +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_IOCAP_ATOMIC +.Fd #define SQLITE_IOCAP_ATOMIC512 +.Fd #define SQLITE_IOCAP_ATOMIC1K +.Fd #define SQLITE_IOCAP_ATOMIC2K +.Fd #define SQLITE_IOCAP_ATOMIC4K +.Fd #define SQLITE_IOCAP_ATOMIC8K +.Fd #define SQLITE_IOCAP_ATOMIC16K +.Fd #define SQLITE_IOCAP_ATOMIC32K +.Fd #define SQLITE_IOCAP_ATOMIC64K +.Fd #define SQLITE_IOCAP_SAFE_APPEND +.Fd #define SQLITE_IOCAP_SEQUENTIAL +.Fd #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN +.Fd #define SQLITE_IOCAP_POWERSAFE_OVERWRITE +.Fd #define SQLITE_IOCAP_IMMUTABLE +.Fd #define SQLITE_IOCAP_BATCH_ATOMIC +.Sh DESCRIPTION +The xDeviceCharacteristics method of the sqlite3_io_methods +object returns an integer which is a vector of these bit values expressing +I/O characteristics of the mass storage device that holds the file +that the sqlite3_io_methods refers to. +.Pp +The SQLITE_IOCAP_ATOMIC property means that all writes of any size +are atomic. +The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are +nnn bytes in size and are aligned to an address which is an integer +multiple of nnn are atomic. +The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended +to a file, the data is appended first then the size of the file is +extended, never the other way around. +The SQLITE_IOCAP_SEQUENTIAL property means that information is written +to disk in the same order as calls to xWrite(). +The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that after reboot +following a crash or power loss, the only bytes in a file that were +written at the application level might have changed and that adjacent +bytes, even bytes within the same sector are guaranteed to be unchanged. +The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN flag indicates that a file cannot +be deleted when open. +The SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on read-only +media and cannot be changed even by processes with elevated privileges. +.Pp +The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying filesystem +supports doing multiple write operations atomically when those write +operations are bracketed by SQLITE_FCNTL_BEGIN_ATOMIC_WRITE +and SQLITE_FCNTL_COMMIT_ATOMIC_WRITE. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 622. +.Bd -literal +#define SQLITE_IOCAP_ATOMIC 0x00000001 +#define SQLITE_IOCAP_ATOMIC512 0x00000002 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 +#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 +#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 +#define SQLITE_IOCAP_IMMUTABLE 0x00002000 +#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000 +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 diff --git a/static/netbsd/man3/SQLITE_IOERR_READ.3 b/static/netbsd/man3/SQLITE_IOERR_READ.3 new file mode 100644 index 00000000..6828df0e --- /dev/null +++ b/static/netbsd/man3/SQLITE_IOERR_READ.3 @@ -0,0 +1,136 @@ +.Dd March 11, 2017 +.Dt SQLITE_IOERR_READ 3 +.Os +.Sh NAME +.Nm SQLITE_IOERR_READ , +.Nm SQLITE_IOERR_SHORT_READ , +.Nm SQLITE_IOERR_WRITE , +.Nm SQLITE_IOERR_FSYNC , +.Nm SQLITE_IOERR_DIR_FSYNC , +.Nm SQLITE_IOERR_TRUNCATE , +.Nm SQLITE_IOERR_FSTAT , +.Nm SQLITE_IOERR_UNLOCK , +.Nm SQLITE_IOERR_RDLOCK , +.Nm SQLITE_IOERR_DELETE , +.Nm SQLITE_IOERR_BLOCKED , +.Nm SQLITE_IOERR_NOMEM , +.Nm SQLITE_IOERR_ACCESS , +.Nm SQLITE_IOERR_CHECKRESERVEDLOCK , +.Nm SQLITE_IOERR_LOCK , +.Nm SQLITE_IOERR_CLOSE , +.Nm SQLITE_IOERR_DIR_CLOSE , +.Nm SQLITE_IOERR_SHMOPEN , +.Nm SQLITE_IOERR_SHMSIZE , +.Nm SQLITE_IOERR_SHMLOCK , +.Nm SQLITE_IOERR_SHMMAP , +.Nm SQLITE_IOERR_SEEK , +.Nm SQLITE_IOERR_DELETE_NOENT , +.Nm SQLITE_IOERR_MMAP , +.Nm SQLITE_IOERR_GETTEMPPATH , +.Nm SQLITE_IOERR_CONVPATH , +.Nm SQLITE_IOERR_VNODE , +.Nm SQLITE_IOERR_AUTH , +.Nm SQLITE_LOCKED_SHAREDCACHE , +.Nm SQLITE_BUSY_RECOVERY , +.Nm SQLITE_BUSY_SNAPSHOT , +.Nm SQLITE_CANTOPEN_NOTEMPDIR , +.Nm SQLITE_CANTOPEN_ISDIR , +.Nm SQLITE_CANTOPEN_FULLPATH , +.Nm SQLITE_CANTOPEN_CONVPATH , +.Nm SQLITE_CORRUPT_VTAB , +.Nm SQLITE_READONLY_RECOVERY , +.Nm SQLITE_READONLY_CANTLOCK , +.Nm SQLITE_READONLY_ROLLBACK , +.Nm SQLITE_READONLY_DBMOVED , +.Nm SQLITE_ABORT_ROLLBACK , +.Nm SQLITE_CONSTRAINT_CHECK , +.Nm SQLITE_CONSTRAINT_COMMITHOOK , +.Nm SQLITE_CONSTRAINT_FOREIGNKEY , +.Nm SQLITE_CONSTRAINT_FUNCTION , +.Nm SQLITE_CONSTRAINT_NOTNULL , +.Nm SQLITE_CONSTRAINT_PRIMARYKEY , +.Nm SQLITE_CONSTRAINT_TRIGGER , +.Nm SQLITE_CONSTRAINT_UNIQUE , +.Nm SQLITE_CONSTRAINT_VTAB , +.Nm SQLITE_CONSTRAINT_ROWID , +.Nm SQLITE_NOTICE_RECOVER_WAL , +.Nm SQLITE_NOTICE_RECOVER_ROLLBACK , +.Nm SQLITE_WARNING_AUTOINDEX , +.Nm SQLITE_AUTH_USER , +.Nm SQLITE_OK_LOAD_PERMANENTLY +.Nd Extended Result Codes +.Sh SYNOPSIS +.Fd #define SQLITE_IOERR_READ +.Fd #define SQLITE_IOERR_SHORT_READ +.Fd #define SQLITE_IOERR_WRITE +.Fd #define SQLITE_IOERR_FSYNC +.Fd #define SQLITE_IOERR_DIR_FSYNC +.Fd #define SQLITE_IOERR_TRUNCATE +.Fd #define SQLITE_IOERR_FSTAT +.Fd #define SQLITE_IOERR_UNLOCK +.Fd #define SQLITE_IOERR_RDLOCK +.Fd #define SQLITE_IOERR_DELETE +.Fd #define SQLITE_IOERR_BLOCKED +.Fd #define SQLITE_IOERR_NOMEM +.Fd #define SQLITE_IOERR_ACCESS +.Fd #define SQLITE_IOERR_CHECKRESERVEDLOCK +.Fd #define SQLITE_IOERR_LOCK +.Fd #define SQLITE_IOERR_CLOSE +.Fd #define SQLITE_IOERR_DIR_CLOSE +.Fd #define SQLITE_IOERR_SHMOPEN +.Fd #define SQLITE_IOERR_SHMSIZE +.Fd #define SQLITE_IOERR_SHMLOCK +.Fd #define SQLITE_IOERR_SHMMAP +.Fd #define SQLITE_IOERR_SEEK +.Fd #define SQLITE_IOERR_DELETE_NOENT +.Fd #define SQLITE_IOERR_MMAP +.Fd #define SQLITE_IOERR_GETTEMPPATH +.Fd #define SQLITE_IOERR_CONVPATH +.Fd #define SQLITE_IOERR_VNODE +.Fd #define SQLITE_IOERR_AUTH +.Fd #define SQLITE_LOCKED_SHAREDCACHE +.Fd #define SQLITE_BUSY_RECOVERY +.Fd #define SQLITE_BUSY_SNAPSHOT +.Fd #define SQLITE_CANTOPEN_NOTEMPDIR +.Fd #define SQLITE_CANTOPEN_ISDIR +.Fd #define SQLITE_CANTOPEN_FULLPATH +.Fd #define SQLITE_CANTOPEN_CONVPATH +.Fd #define SQLITE_CORRUPT_VTAB +.Fd #define SQLITE_READONLY_RECOVERY +.Fd #define SQLITE_READONLY_CANTLOCK +.Fd #define SQLITE_READONLY_ROLLBACK +.Fd #define SQLITE_READONLY_DBMOVED +.Fd #define SQLITE_ABORT_ROLLBACK +.Fd #define SQLITE_CONSTRAINT_CHECK +.Fd #define SQLITE_CONSTRAINT_COMMITHOOK +.Fd #define SQLITE_CONSTRAINT_FOREIGNKEY +.Fd #define SQLITE_CONSTRAINT_FUNCTION +.Fd #define SQLITE_CONSTRAINT_NOTNULL +.Fd #define SQLITE_CONSTRAINT_PRIMARYKEY +.Fd #define SQLITE_CONSTRAINT_TRIGGER +.Fd #define SQLITE_CONSTRAINT_UNIQUE +.Fd #define SQLITE_CONSTRAINT_VTAB +.Fd #define SQLITE_CONSTRAINT_ROWID +.Fd #define SQLITE_NOTICE_RECOVER_WAL +.Fd #define SQLITE_NOTICE_RECOVER_ROLLBACK +.Fd #define SQLITE_WARNING_AUTOINDEX +.Fd #define SQLITE_AUTH_USER +.Fd #define SQLITE_OK_LOAD_PERMANENTLY +.Sh DESCRIPTION +In its default configuration, SQLite API routines return one of 30 +integer result codes. +However, experience has shown that many of these result codes are too +coarse-grained. +They do not provide as much information about problems as programmers +might like. +In an effort to address this, newer versions of SQLite (version 3.3.8 +dateof:3.3.8 and later) include support for additional +result codes that provide more detailed information about errors. +These extended result codes are enabled or disabled +on a per database connection basis using the sqlite3_extended_result_codes() +API. +Or, the extended code for the most recent error can be obtained using +sqlite3_extended_errcode(). +.Sh SEE ALSO +.Xr sqlite3_errcode 3 , +.Xr sqlite3_extended_result_codes 3 diff --git a/static/netbsd/man3/SQLITE_LIMIT_LENGTH.3 b/static/netbsd/man3/SQLITE_LIMIT_LENGTH.3 new file mode 100644 index 00000000..db12e1d4 --- /dev/null +++ b/static/netbsd/man3/SQLITE_LIMIT_LENGTH.3 @@ -0,0 +1,94 @@ +.Dd January 24, 2024 +.Dt SQLITE_LIMIT_LENGTH 3 +.Os +.Sh NAME +.Nm SQLITE_LIMIT_LENGTH , +.Nm SQLITE_LIMIT_SQL_LENGTH , +.Nm SQLITE_LIMIT_COLUMN , +.Nm SQLITE_LIMIT_EXPR_DEPTH , +.Nm SQLITE_LIMIT_COMPOUND_SELECT , +.Nm SQLITE_LIMIT_VDBE_OP , +.Nm SQLITE_LIMIT_FUNCTION_ARG , +.Nm SQLITE_LIMIT_ATTACHED , +.Nm SQLITE_LIMIT_LIKE_PATTERN_LENGTH , +.Nm SQLITE_LIMIT_VARIABLE_NUMBER , +.Nm SQLITE_LIMIT_TRIGGER_DEPTH , +.Nm SQLITE_LIMIT_WORKER_THREADS +.Nd run-Time limit categories +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_LIMIT_LENGTH +.Fd #define SQLITE_LIMIT_SQL_LENGTH +.Fd #define SQLITE_LIMIT_COLUMN +.Fd #define SQLITE_LIMIT_EXPR_DEPTH +.Fd #define SQLITE_LIMIT_COMPOUND_SELECT +.Fd #define SQLITE_LIMIT_VDBE_OP +.Fd #define SQLITE_LIMIT_FUNCTION_ARG +.Fd #define SQLITE_LIMIT_ATTACHED +.Fd #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH +.Fd #define SQLITE_LIMIT_VARIABLE_NUMBER +.Fd #define SQLITE_LIMIT_TRIGGER_DEPTH +.Fd #define SQLITE_LIMIT_WORKER_THREADS +.Sh DESCRIPTION +These constants define various performance limits that can be lowered +at run-time using +.Fn sqlite3_limit . +The synopsis of the meanings of the various limits is shown below. +Additional information is available at Limits in SQLite. +.Bl -tag -width Ds +.It SQLITE_LIMIT_LENGTH +The maximum size of any string or BLOB or table row, in bytes. +.It SQLITE_LIMIT_SQL_LENGTH +The maximum length of an SQL statement, in bytes. +.It SQLITE_LIMIT_COLUMN +The maximum number of columns in a table definition or in the result +set of a SELECT or the maximum number of columns in an index +or in an ORDER BY or GROUP BY clause. +.It SQLITE_LIMIT_EXPR_DEPTH +The maximum depth of the parse tree on any expression. +.It SQLITE_LIMIT_COMPOUND_SELECT +The maximum number of terms in a compound SELECT statement. +.It SQLITE_LIMIT_VDBE_OP +The maximum number of instructions in a virtual machine program used +to implement an SQL statement. +If +.Fn sqlite3_prepare_v2 +or the equivalent tries to allocate space for more than this many opcodes +in a single prepared statement, an SQLITE_NOMEM error is returned. +.It SQLITE_LIMIT_FUNCTION_ARG +The maximum number of arguments on a function. +.It SQLITE_LIMIT_ATTACHED +The maximum number of attached databases. +.It SQLITE_LIMIT_LIKE_PATTERN_LENGTH +The maximum length of the pattern argument to the LIKE or GLOB +operators. +.It SQLITE_LIMIT_VARIABLE_NUMBER +The maximum index number of any parameter in an SQL statement. +.It SQLITE_LIMIT_TRIGGER_DEPTH +The maximum depth of recursion for triggers. +.It SQLITE_LIMIT_WORKER_THREADS +The maximum number of auxiliary worker threads that a single prepared statement +may start. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4068. +.Bd -literal +#define SQLITE_LIMIT_LENGTH 0 +#define SQLITE_LIMIT_SQL_LENGTH 1 +#define SQLITE_LIMIT_COLUMN 2 +#define SQLITE_LIMIT_EXPR_DEPTH 3 +#define SQLITE_LIMIT_COMPOUND_SELECT 4 +#define SQLITE_LIMIT_VDBE_OP 5 +#define SQLITE_LIMIT_FUNCTION_ARG 6 +#define SQLITE_LIMIT_ATTACHED 7 +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 +#define SQLITE_LIMIT_VARIABLE_NUMBER 9 +#define SQLITE_LIMIT_TRIGGER_DEPTH 10 +#define SQLITE_LIMIT_WORKER_THREADS 11 +.Ed +.Sh SEE ALSO +.Xr sqlite3_limit 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/SQLITE_LOCK_NONE.3 b/static/netbsd/man3/SQLITE_LOCK_NONE.3 new file mode 100644 index 00000000..773ec7bb --- /dev/null +++ b/static/netbsd/man3/SQLITE_LOCK_NONE.3 @@ -0,0 +1,37 @@ +.Dd January 24, 2024 +.Dt SQLITE_LOCK_NONE 3 +.Os +.Sh NAME +.Nm SQLITE_LOCK_NONE , +.Nm SQLITE_LOCK_SHARED , +.Nm SQLITE_LOCK_RESERVED , +.Nm SQLITE_LOCK_PENDING , +.Nm SQLITE_LOCK_EXCLUSIVE +.Nd file locking levels +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_LOCK_NONE +.Fd #define SQLITE_LOCK_SHARED +.Fd #define SQLITE_LOCK_RESERVED +.Fd #define SQLITE_LOCK_PENDING +.Fd #define SQLITE_LOCK_EXCLUSIVE +.Sh DESCRIPTION +SQLite uses one of these integer values as the second argument to calls +it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods +object. +These values are ordered from lest restrictive to most restrictive. +.Pp +The argument to xLock() is always SHARED or higher. +The argument to xUnlock is either SHARED or NONE. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 671. +.Bd -literal +#define SQLITE_LOCK_NONE 0 /* xUnlock() only */ +#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */ +#define SQLITE_LOCK_RESERVED 2 /* xLock() only */ +#define SQLITE_LOCK_PENDING 3 /* xLock() only */ +#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 diff --git a/static/netbsd/man3/SQLITE_MUTEX_FAST.3 b/static/netbsd/man3/SQLITE_MUTEX_FAST.3 new file mode 100644 index 00000000..78c8474f --- /dev/null +++ b/static/netbsd/man3/SQLITE_MUTEX_FAST.3 @@ -0,0 +1,71 @@ +.Dd January 24, 2024 +.Dt SQLITE_MUTEX_FAST 3 +.Os +.Sh NAME +.Nm SQLITE_MUTEX_FAST , +.Nm SQLITE_MUTEX_RECURSIVE , +.Nm SQLITE_MUTEX_STATIC_MAIN , +.Nm SQLITE_MUTEX_STATIC_MEM , +.Nm SQLITE_MUTEX_STATIC_MEM2 , +.Nm SQLITE_MUTEX_STATIC_OPEN , +.Nm SQLITE_MUTEX_STATIC_PRNG , +.Nm SQLITE_MUTEX_STATIC_LRU , +.Nm SQLITE_MUTEX_STATIC_LRU2 , +.Nm SQLITE_MUTEX_STATIC_PMEM , +.Nm SQLITE_MUTEX_STATIC_APP1 , +.Nm SQLITE_MUTEX_STATIC_APP2 , +.Nm SQLITE_MUTEX_STATIC_APP3 , +.Nm SQLITE_MUTEX_STATIC_VFS1 , +.Nm SQLITE_MUTEX_STATIC_VFS2 , +.Nm SQLITE_MUTEX_STATIC_VFS3 +.Nd mutex types +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_MUTEX_FAST +.Fd #define SQLITE_MUTEX_RECURSIVE +.Fd #define SQLITE_MUTEX_STATIC_MAIN +.Fd #define SQLITE_MUTEX_STATIC_MEM +.Fd #define SQLITE_MUTEX_STATIC_MEM2 +.Fd #define SQLITE_MUTEX_STATIC_OPEN +.Fd #define SQLITE_MUTEX_STATIC_PRNG +.Fd #define SQLITE_MUTEX_STATIC_LRU +.Fd #define SQLITE_MUTEX_STATIC_LRU2 +.Fd #define SQLITE_MUTEX_STATIC_PMEM +.Fd #define SQLITE_MUTEX_STATIC_APP1 +.Fd #define SQLITE_MUTEX_STATIC_APP2 +.Fd #define SQLITE_MUTEX_STATIC_APP3 +.Fd #define SQLITE_MUTEX_STATIC_VFS1 +.Fd #define SQLITE_MUTEX_STATIC_VFS2 +.Fd #define SQLITE_MUTEX_STATIC_VFS3 +.Sh DESCRIPTION +The +.Fn sqlite3_mutex_alloc +interface takes a single argument which is one of these integer constants. +.Pp +The set of static mutexes may change from one SQLite release to the +next. +Applications that override the built-in mutex logic must be prepared +to accommodate additional static mutexes. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8178. +.Bd -literal +#define SQLITE_MUTEX_FAST 0 +#define SQLITE_MUTEX_RECURSIVE 1 +#define SQLITE_MUTEX_STATIC_MAIN 2 +#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ +#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ +#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */ +#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ +#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ +#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ +#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ +#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ +#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ +#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ +#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ +#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_mutex_alloc 3 diff --git a/static/netbsd/man3/SQLITE_OK.3 b/static/netbsd/man3/SQLITE_OK.3 new file mode 100644 index 00000000..b7b19320 --- /dev/null +++ b/static/netbsd/man3/SQLITE_OK.3 @@ -0,0 +1,115 @@ +.Dd January 24, 2024 +.Dt SQLITE_OK 3 +.Os +.Sh NAME +.Nm SQLITE_OK , +.Nm SQLITE_ERROR , +.Nm SQLITE_INTERNAL , +.Nm SQLITE_PERM , +.Nm SQLITE_ABORT , +.Nm SQLITE_BUSY , +.Nm SQLITE_LOCKED , +.Nm SQLITE_NOMEM , +.Nm SQLITE_READONLY , +.Nm SQLITE_INTERRUPT , +.Nm SQLITE_IOERR , +.Nm SQLITE_CORRUPT , +.Nm SQLITE_NOTFOUND , +.Nm SQLITE_FULL , +.Nm SQLITE_CANTOPEN , +.Nm SQLITE_PROTOCOL , +.Nm SQLITE_EMPTY , +.Nm SQLITE_SCHEMA , +.Nm SQLITE_TOOBIG , +.Nm SQLITE_CONSTRAINT , +.Nm SQLITE_MISMATCH , +.Nm SQLITE_MISUSE , +.Nm SQLITE_NOLFS , +.Nm SQLITE_AUTH , +.Nm SQLITE_FORMAT , +.Nm SQLITE_RANGE , +.Nm SQLITE_NOTADB , +.Nm SQLITE_NOTICE , +.Nm SQLITE_WARNING , +.Nm SQLITE_ROW , +.Nm SQLITE_DONE +.Nd result codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_OK +.Fd #define SQLITE_ERROR +.Fd #define SQLITE_INTERNAL +.Fd #define SQLITE_PERM +.Fd #define SQLITE_ABORT +.Fd #define SQLITE_BUSY +.Fd #define SQLITE_LOCKED +.Fd #define SQLITE_NOMEM +.Fd #define SQLITE_READONLY +.Fd #define SQLITE_INTERRUPT +.Fd #define SQLITE_IOERR +.Fd #define SQLITE_CORRUPT +.Fd #define SQLITE_NOTFOUND +.Fd #define SQLITE_FULL +.Fd #define SQLITE_CANTOPEN +.Fd #define SQLITE_PROTOCOL +.Fd #define SQLITE_EMPTY +.Fd #define SQLITE_SCHEMA +.Fd #define SQLITE_TOOBIG +.Fd #define SQLITE_CONSTRAINT +.Fd #define SQLITE_MISMATCH +.Fd #define SQLITE_MISUSE +.Fd #define SQLITE_NOLFS +.Fd #define SQLITE_AUTH +.Fd #define SQLITE_FORMAT +.Fd #define SQLITE_RANGE +.Fd #define SQLITE_NOTADB +.Fd #define SQLITE_NOTICE +.Fd #define SQLITE_WARNING +.Fd #define SQLITE_ROW +.Fd #define SQLITE_DONE +.Sh DESCRIPTION +Many SQLite functions return an integer result code from the set shown +here in order to indicate success or failure. +.Pp +New error codes may be added in future versions of SQLite. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 434. +.Bd -literal +#define SQLITE_OK 0 /* Successful result */ +/* beginning-of-error-codes */ +#define SQLITE_ERROR 1 /* Generic error */ +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ +#define SQLITE_PERM 3 /* Access permission denied */ +#define SQLITE_ABORT 4 /* Callback routine requested an abort */ +#define SQLITE_BUSY 5 /* The database file is locked */ +#define SQLITE_LOCKED 6 /* A table in the database is locked */ +#define SQLITE_NOMEM 7 /* A malloc() failed */ +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ +#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */ +#define SQLITE_FULL 13 /* Insertion failed because database is full */ +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ +#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ +#define SQLITE_EMPTY 16 /* Internal use only */ +#define SQLITE_SCHEMA 17 /* The database schema changed */ +#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ +#define SQLITE_MISMATCH 20 /* Data type mismatch */ +#define SQLITE_MISUSE 21 /* Library used incorrectly */ +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ +#define SQLITE_AUTH 23 /* Authorization denied */ +#define SQLITE_FORMAT 24 /* Not used */ +#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ +#define SQLITE_NOTADB 26 /* File opened that is not a database file */ +#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */ +#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */ +#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ +#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ +/* end-of-error-codes */ +.Ed +.Sh SEE ALSO +.Xr SQLITE_ERROR_MISSING_COLLSEQ 3 diff --git a/static/netbsd/man3/SQLITE_OPEN_READONLY.3 b/static/netbsd/man3/SQLITE_OPEN_READONLY.3 new file mode 100644 index 00000000..de6242cf --- /dev/null +++ b/static/netbsd/man3/SQLITE_OPEN_READONLY.3 @@ -0,0 +1,102 @@ +.Dd January 24, 2024 +.Dt SQLITE_OPEN_READONLY 3 +.Os +.Sh NAME +.Nm SQLITE_OPEN_READONLY , +.Nm SQLITE_OPEN_READWRITE , +.Nm SQLITE_OPEN_CREATE , +.Nm SQLITE_OPEN_DELETEONCLOSE , +.Nm SQLITE_OPEN_EXCLUSIVE , +.Nm SQLITE_OPEN_AUTOPROXY , +.Nm SQLITE_OPEN_URI , +.Nm SQLITE_OPEN_MEMORY , +.Nm SQLITE_OPEN_MAIN_DB , +.Nm SQLITE_OPEN_TEMP_DB , +.Nm SQLITE_OPEN_TRANSIENT_DB , +.Nm SQLITE_OPEN_MAIN_JOURNAL , +.Nm SQLITE_OPEN_TEMP_JOURNAL , +.Nm SQLITE_OPEN_SUBJOURNAL , +.Nm SQLITE_OPEN_SUPER_JOURNAL , +.Nm SQLITE_OPEN_NOMUTEX , +.Nm SQLITE_OPEN_FULLMUTEX , +.Nm SQLITE_OPEN_SHAREDCACHE , +.Nm SQLITE_OPEN_PRIVATECACHE , +.Nm SQLITE_OPEN_WAL , +.Nm SQLITE_OPEN_NOFOLLOW , +.Nm SQLITE_OPEN_EXRESCODE +.Nd flags for file open operations +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_OPEN_READONLY +.Fd #define SQLITE_OPEN_READWRITE +.Fd #define SQLITE_OPEN_CREATE +.Fd #define SQLITE_OPEN_DELETEONCLOSE +.Fd #define SQLITE_OPEN_EXCLUSIVE +.Fd #define SQLITE_OPEN_AUTOPROXY +.Fd #define SQLITE_OPEN_URI +.Fd #define SQLITE_OPEN_MEMORY +.Fd #define SQLITE_OPEN_MAIN_DB +.Fd #define SQLITE_OPEN_TEMP_DB +.Fd #define SQLITE_OPEN_TRANSIENT_DB +.Fd #define SQLITE_OPEN_MAIN_JOURNAL +.Fd #define SQLITE_OPEN_TEMP_JOURNAL +.Fd #define SQLITE_OPEN_SUBJOURNAL +.Fd #define SQLITE_OPEN_SUPER_JOURNAL +.Fd #define SQLITE_OPEN_NOMUTEX +.Fd #define SQLITE_OPEN_FULLMUTEX +.Fd #define SQLITE_OPEN_SHAREDCACHE +.Fd #define SQLITE_OPEN_PRIVATECACHE +.Fd #define SQLITE_OPEN_WAL +.Fd #define SQLITE_OPEN_NOFOLLOW +.Fd #define SQLITE_OPEN_EXRESCODE +.Sh DESCRIPTION +These bit values are intended for use in the 3rd parameter to the +.Fn sqlite3_open_v2 +interface and in the 4th parameter to the sqlite3_vfs.xOpen +method. +.Pp +Only those flags marked as "Ok for sqlite3_open_v2()" may be used as +the third argument to the +.Fn sqlite3_open_v2 +interface. +The other flags have historically been ignored by sqlite3_open_v2(), +though future versions of SQLite might change so that an error is raised +if any of the disallowed bits are passed into sqlite3_open_v2(). +Applications should not depend on the historical behavior. +.Pp +Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into +.Fn sqlite3_open_v2 +does *not* cause the underlying database file to be opened using O_EXCL. +Passing SQLITE_OPEN_EXCLUSIVE into +.Fn sqlite3_open_v2 +has historically be a no-op and might become an error in future versions +of SQLite. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 574. +.Bd -literal +#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ +#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ +#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */ +#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ +#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */ +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */ +#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */ +#define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */ +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */ +#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */ +#define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_open 3 diff --git a/static/netbsd/man3/SQLITE_PREPARE_PERSISTENT.3 b/static/netbsd/man3/SQLITE_PREPARE_PERSISTENT.3 new file mode 100644 index 00000000..5f46411c --- /dev/null +++ b/static/netbsd/man3/SQLITE_PREPARE_PERSISTENT.3 @@ -0,0 +1,66 @@ +.Dd January 24, 2024 +.Dt SQLITE_PREPARE_PERSISTENT 3 +.Os +.Sh NAME +.Nm SQLITE_PREPARE_PERSISTENT , +.Nm SQLITE_PREPARE_NORMALIZE , +.Nm SQLITE_PREPARE_NO_VTAB +.Nd prepare flags +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_PREPARE_PERSISTENT +.Fd #define SQLITE_PREPARE_NORMALIZE +.Fd #define SQLITE_PREPARE_NO_VTAB +.Sh DESCRIPTION +These constants define various flags that can be passed into "prepFlags" +parameter of the +.Fn sqlite3_prepare_v3 +and +.Fn sqlite3_prepare16_v3 +interfaces. +.Pp +New flags may be added in future releases of SQLite. +.Bl -tag -width Ds +.It SQLITE_PREPARE_PERSISTENT +The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner that +the prepared statement will be retained for a long time and probably +reused many times. +Without this flag, +.Fn sqlite3_prepare_v3 +and +.Fn sqlite3_prepare16_v3 +assume that the prepared statement will be used just once or at most +a few times and then destroyed using +.Fn sqlite3_finalize +relatively soon. +The current implementation acts on this hint by avoiding the use of +lookaside memory so as not to deplete the limited store +of lookaside memory. +Future versions of SQLite may act on this hint differently. +.It SQLITE_PREPARE_NORMALIZE +The SQLITE_PREPARE_NORMALIZE flag is a no-op. +This flag used to be required for any prepared statement that wanted +to use the +.Fn sqlite3_normalized_sql +interface. +However, the +.Fn sqlite3_normalized_sql +interface is now available to all prepared statements, regardless of +whether or not they use this flag. +.It SQLITE_PREPARE_NO_VTAB +The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler to return an +error (error code SQLITE_ERROR) if the statement uses any virtual tables. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4137. +.Bd -literal +#define SQLITE_PREPARE_PERSISTENT 0x01 +#define SQLITE_PREPARE_NORMALIZE 0x02 +#define SQLITE_PREPARE_NO_VTAB 0x04 +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_sql 3 diff --git a/static/netbsd/man3/SQLITE_ROLLBACK.3 b/static/netbsd/man3/SQLITE_ROLLBACK.3 new file mode 100644 index 00000000..39ea8867 --- /dev/null +++ b/static/netbsd/man3/SQLITE_ROLLBACK.3 @@ -0,0 +1,38 @@ +.Dd January 24, 2024 +.Dt SQLITE_ROLLBACK 3 +.Os +.Sh NAME +.Nm SQLITE_ROLLBACK , +.Nm SQLITE_FAIL , +.Nm SQLITE_REPLACE +.Nd conflict resolution modes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_ROLLBACK +.Fd #define SQLITE_FAIL +.Fd #define SQLITE_REPLACE +.Sh DESCRIPTION +These constants are returned by +.Fn sqlite3_vtab_on_conflict +to inform a virtual table implementation what the ON CONFLICT +mode is for the SQL statement being evaluated. +.Pp +Note that the SQLITE_IGNORE constant is also used as a +potential return value from the +.Fn sqlite3_set_authorizer +callback and that SQLITE_ABORT is also a result code. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10125. +.Bd -literal +#define SQLITE_ROLLBACK 1 +/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */ +#define SQLITE_FAIL 3 +/* #define SQLITE_ABORT 4 // Also an error code */ +#define SQLITE_REPLACE 5 +.Ed +.Sh SEE ALSO +.Xr sqlite3_set_authorizer 3 , +.Xr sqlite3_vtab_on_conflict 3 , +.Xr SQLITE_DENY 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/SQLITE_SCANSTAT_COMPLEX.3 b/static/netbsd/man3/SQLITE_SCANSTAT_COMPLEX.3 new file mode 100644 index 00000000..6764cbad --- /dev/null +++ b/static/netbsd/man3/SQLITE_SCANSTAT_COMPLEX.3 @@ -0,0 +1,16 @@ +.Dd January 24, 2024 +.Dt SQLITE_SCANSTAT_COMPLEX 3 +.Os +.Sh NAME +.Nm SQLITE_SCANSTAT_COMPLEX +.Nd prepared statement scan status +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SCANSTAT_COMPLEX +.Sh DESCRIPTION +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10266. +.Bd -literal +#define SQLITE_SCANSTAT_COMPLEX 0x0001 +.Ed diff --git a/static/netbsd/man3/SQLITE_SCANSTAT_NLOOP.3 b/static/netbsd/man3/SQLITE_SCANSTAT_NLOOP.3 new file mode 100644 index 00000000..7d1d92a8 --- /dev/null +++ b/static/netbsd/man3/SQLITE_SCANSTAT_NLOOP.3 @@ -0,0 +1,95 @@ +.Dd January 24, 2024 +.Dt SQLITE_SCANSTAT_NLOOP 3 +.Os +.Sh NAME +.Nm SQLITE_SCANSTAT_NLOOP , +.Nm SQLITE_SCANSTAT_NVISIT , +.Nm SQLITE_SCANSTAT_EST , +.Nm SQLITE_SCANSTAT_NAME , +.Nm SQLITE_SCANSTAT_EXPLAIN , +.Nm SQLITE_SCANSTAT_SELECTID , +.Nm SQLITE_SCANSTAT_PARENTID , +.Nm SQLITE_SCANSTAT_NCYCLE +.Nd prepared statement scan status opcodes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SCANSTAT_NLOOP +.Fd #define SQLITE_SCANSTAT_NVISIT +.Fd #define SQLITE_SCANSTAT_EST +.Fd #define SQLITE_SCANSTAT_NAME +.Fd #define SQLITE_SCANSTAT_EXPLAIN +.Fd #define SQLITE_SCANSTAT_SELECTID +.Fd #define SQLITE_SCANSTAT_PARENTID +.Fd #define SQLITE_SCANSTAT_NCYCLE +.Sh DESCRIPTION +The following constants can be used for the T parameter to the sqlite3_stmt_scanstatus(S,X,T,V) +interface. +Each constant designates a different metric for sqlite3_stmt_scanstatus() +to return. +.Pp +When the value returned to V is a string, space to hold that string +is managed by the prepared statement S and will be automatically freed +when S is finalized. +.Pp +Not all values are available for all query elements. +When a value is not available, the output variable is set to -1 if +the value is numeric, or to NULL if it is a string (SQLITE_SCANSTAT_NAME). +.Bl -tag -width Ds +.It SQLITE_SCANSTAT_NLOOP +The sqlite3_int64 variable pointed to by the V parameter +will be set to the total number of times that the X-th loop has run. +.It SQLITE_SCANSTAT_NVISIT +The sqlite3_int64 variable pointed to by the V parameter +will be set to the total number of rows examined by all iterations +of the X-th loop. +.It SQLITE_SCANSTAT_EST +The "double" variable pointed to by the V parameter will be set to +the query planner's estimate for the average number of rows output +from each iteration of the X-th loop. +If the query planner's estimates was accurate, then this value will +approximate the quotient NVISIT/NLOOP and the product of this value +for all prior loops with the same SELECTID will be the NLOOP value +for the current loop. +.It SQLITE_SCANSTAT_NAME +The "const char *" variable pointed to by the V parameter will be set +to a zero-terminated UTF-8 string containing the name of the index +or table used for the X-th loop. +.It SQLITE_SCANSTAT_EXPLAIN +The "const char *" variable pointed to by the V parameter will be set +to a zero-terminated UTF-8 string containing the EXPLAIN QUERY PLAN +description for the X-th loop. +.It SQLITE_SCANSTAT_SELECTID +The "int" variable pointed to by the V parameter will be set to the +id for the X-th query plan element. +The id value is unique within the statement. +The select-id is the same value as is output in the first column of +an EXPLAIN QUERY PLAN query. +.It SQLITE_SCANSTAT_PARENTID +The "int" variable pointed to by the V parameter will be set to the +the id of the parent of the current query element, if applicable, or +to zero if the query element has no parent. +This is the same value as returned in the second column of an EXPLAIN QUERY PLAN +query. +.It SQLITE_SCANSTAT_NCYCLE +The sqlite3_int64 output value is set to the number of cycles, according +to the processor time-stamp counter, that elapsed while the query element +was being processed. +This value is not available for all query elements - if it is unavailable +the output variable is set to -1. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10143. +.Bd -literal +#define SQLITE_SCANSTAT_NLOOP 0 +#define SQLITE_SCANSTAT_NVISIT 1 +#define SQLITE_SCANSTAT_EST 2 +#define SQLITE_SCANSTAT_NAME 3 +#define SQLITE_SCANSTAT_EXPLAIN 4 +#define SQLITE_SCANSTAT_SELECTID 5 +#define SQLITE_SCANSTAT_PARENTID 6 +#define SQLITE_SCANSTAT_NCYCLE 7 +.Ed +.Sh SEE ALSO +.Xr sqlite_int64 3 diff --git a/static/netbsd/man3/SQLITE_SERIALIZE_NOCOPY.3 b/static/netbsd/man3/SQLITE_SERIALIZE_NOCOPY.3 new file mode 100644 index 00000000..65cb7fb8 --- /dev/null +++ b/static/netbsd/man3/SQLITE_SERIALIZE_NOCOPY.3 @@ -0,0 +1,33 @@ +.Dd January 24, 2024 +.Dt SQLITE_SERIALIZE_NOCOPY 3 +.Os +.Sh NAME +.Nm SQLITE_SERIALIZE_NOCOPY +.Nd flags for sqlite3_serialize +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SERIALIZE_NOCOPY +.Sh DESCRIPTION +Zero or more of the following constants can be OR-ed together for the +F argument to sqlite3_serialize(D,S,P,F). +.Pp +SQLITE_SERIALIZE_NOCOPY means that +.Fn sqlite3_serialize +will return a pointer to contiguous in-memory database that it is currently +using, without making a copy of the database. +If SQLite is not currently using a contiguous in-memory database, then +this option causes +.Fn sqlite3_serialize +to return a NULL pointer. +SQLite will only be using a contiguous in-memory database if it has +been initialized by a prior call to +.Fn sqlite3_deserialize . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10686. +.Bd -literal +#define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_deserialize 3 , +.Xr sqlite3_serialize 3 diff --git a/static/netbsd/man3/SQLITE_SESSION_CONFIG_STRMSIZE.3 b/static/netbsd/man3/SQLITE_SESSION_CONFIG_STRMSIZE.3 new file mode 100644 index 00000000..17b28693 --- /dev/null +++ b/static/netbsd/man3/SQLITE_SESSION_CONFIG_STRMSIZE.3 @@ -0,0 +1,16 @@ +.Dd January 24, 2024 +.Dt SQLITE_SESSION_CONFIG_STRMSIZE 3 +.Os +.Sh NAME +.Nm SQLITE_SESSION_CONFIG_STRMSIZE +.Nd values for sqlite3session_config() +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SESSION_CONFIG_STRMSIZE +.Sh DESCRIPTION +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12715. +.Bd -literal +#define SQLITE_SESSION_CONFIG_STRMSIZE 1 +.Ed diff --git a/static/netbsd/man3/SQLITE_SESSION_OBJCONFIG_SIZE.3 b/static/netbsd/man3/SQLITE_SESSION_OBJCONFIG_SIZE.3 new file mode 100644 index 00000000..c042742b --- /dev/null +++ b/static/netbsd/man3/SQLITE_SESSION_OBJCONFIG_SIZE.3 @@ -0,0 +1,49 @@ +.Dd January 24, 2024 +.Dt SQLITE_SESSION_OBJCONFIG_SIZE 3 +.Os +.Sh NAME +.Nm SQLITE_SESSION_OBJCONFIG_SIZE , +.Nm SQLITE_SESSION_OBJCONFIG_ROWID +.Nd options for sqlite3session_object_config +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SESSION_OBJCONFIG_SIZE +.Fd #define SQLITE_SESSION_OBJCONFIG_ROWID +.Sh DESCRIPTION +The following values may passed as the the 2nd parameter to sqlite3session_object_config(). +.It SQLITE_SESSION_OBJCONFIG_SIZE +This option is used to set, clear or query the flag that enables the +.Fn sqlite3session_changeset_size +API. +Because it imposes some computational overhead, this API is disabled +by default. +Argument pArg must point to a value of type (int). +If the value is initially 0, then the sqlite3session_changeset_size() +API is disabled. +If it is greater than 0, then the same API is enabled. +Or, if the initial value is less than zero, no change is made. +In all cases the (int) variable is set to 1 if the sqlite3session_changeset_size() +API is enabled following the current call, or 0 otherwise. +.Pp +It is an error (SQLITE_MISUSE) to attempt to modify this setting after +the first table has been attached to the session object. +.It SQLITE_SESSION_OBJCONFIG_ROWID +This option is used to set, clear or query the flag that enables collection +of data for tables with no explicit PRIMARY KEY. +.Pp +Normally, tables with no explicit PRIMARY KEY are simply ignored by +the sessions module. +However, if this flag is set, it behaves as if such tables have a column +"_rowid_ INTEGER PRIMARY KEY" inserted as their leftmost columns. +.Pp +It is an error (SQLITE_MISUSE) to attempt to modify this setting after +the first table has been attached to the session object. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11016. +.Bd -literal +#define SQLITE_SESSION_OBJCONFIG_SIZE 1 +#define SQLITE_SESSION_OBJCONFIG_ROWID 2 +.Ed +.Sh SEE ALSO +.Xr sqlite3session_changeset_size 3 diff --git a/static/netbsd/man3/SQLITE_SHM_NLOCK.3 b/static/netbsd/man3/SQLITE_SHM_NLOCK.3 new file mode 100644 index 00000000..bd58f9e8 --- /dev/null +++ b/static/netbsd/man3/SQLITE_SHM_NLOCK.3 @@ -0,0 +1,22 @@ +.Dd January 24, 2024 +.Dt SQLITE_SHM_NLOCK 3 +.Os +.Sh NAME +.Nm SQLITE_SHM_NLOCK +.Nd maximum xShmLock index +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SHM_NLOCK +.Sh DESCRIPTION +The xShmLock method on sqlite3_io_methods may use +values between 0 and this upper bound as its "offset" argument. +The SQLite core will never attempt to acquire or release a lock outside +of this range +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1556. +.Bd -literal +#define SQLITE_SHM_NLOCK 8 +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 diff --git a/static/netbsd/man3/SQLITE_SHM_UNLOCK.3 b/static/netbsd/man3/SQLITE_SHM_UNLOCK.3 new file mode 100644 index 00000000..82e6f7ab --- /dev/null +++ b/static/netbsd/man3/SQLITE_SHM_UNLOCK.3 @@ -0,0 +1,48 @@ +.Dd January 24, 2024 +.Dt SQLITE_SHM_UNLOCK 3 +.Os +.Sh NAME +.Nm SQLITE_SHM_UNLOCK , +.Nm SQLITE_SHM_LOCK , +.Nm SQLITE_SHM_SHARED , +.Nm SQLITE_SHM_EXCLUSIVE +.Nd flags for the xShmLock VFS method +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SHM_UNLOCK +.Fd #define SQLITE_SHM_LOCK +.Fd #define SQLITE_SHM_SHARED +.Fd #define SQLITE_SHM_EXCLUSIVE +.Sh DESCRIPTION +These integer constants define the various locking operations allowed +by the xShmLock method of sqlite3_io_methods. +The following are the only legal combinations of flags to the xShmLock +method: +.Bl -bullet +.It +SQLITE_SHM_LOCK | SQLITE_SHM_SHARED +.It +SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE +.It +SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED +.It +SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE +.El +.Pp +When unlocking, the same SHARED or EXCLUSIVE flag must be supplied +as was given on the corresponding lock. +.Pp +The xShmLock method can transition between unlocked and SHARED or between +unlocked and EXCLUSIVE. +It cannot transition between SHARED and EXCLUSIVE. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1529. +.Bd -literal +#define SQLITE_SHM_UNLOCK 1 +#define SQLITE_SHM_LOCK 2 +#define SQLITE_SHM_SHARED 4 +#define SQLITE_SHM_EXCLUSIVE 8 +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 diff --git a/static/netbsd/man3/SQLITE_STATUS_MEMORY_USED.3 b/static/netbsd/man3/SQLITE_STATUS_MEMORY_USED.3 new file mode 100644 index 00000000..fb364064 --- /dev/null +++ b/static/netbsd/man3/SQLITE_STATUS_MEMORY_USED.3 @@ -0,0 +1,111 @@ +.Dd January 24, 2024 +.Dt SQLITE_STATUS_MEMORY_USED 3 +.Os +.Sh NAME +.Nm SQLITE_STATUS_MEMORY_USED , +.Nm SQLITE_STATUS_PAGECACHE_USED , +.Nm SQLITE_STATUS_PAGECACHE_OVERFLOW , +.Nm SQLITE_STATUS_SCRATCH_USED , +.Nm SQLITE_STATUS_SCRATCH_OVERFLOW , +.Nm SQLITE_STATUS_MALLOC_SIZE , +.Nm SQLITE_STATUS_PARSER_STACK , +.Nm SQLITE_STATUS_PAGECACHE_SIZE , +.Nm SQLITE_STATUS_SCRATCH_SIZE , +.Nm SQLITE_STATUS_MALLOC_COUNT +.Nd status parameters +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_STATUS_MEMORY_USED +.Fd #define SQLITE_STATUS_PAGECACHE_USED +.Fd #define SQLITE_STATUS_PAGECACHE_OVERFLOW +.Fd #define SQLITE_STATUS_SCRATCH_USED +.Fd #define SQLITE_STATUS_SCRATCH_OVERFLOW +.Fd #define SQLITE_STATUS_MALLOC_SIZE +.Fd #define SQLITE_STATUS_PARSER_STACK +.Fd #define SQLITE_STATUS_PAGECACHE_SIZE +.Fd #define SQLITE_STATUS_SCRATCH_SIZE +.Fd #define SQLITE_STATUS_MALLOC_COUNT +.Sh DESCRIPTION +These integer constants designate various run-time status parameters +that can be returned by +.Fn sqlite3_status . +.Bl -tag -width Ds +.It SQLITE_STATUS_MEMORY_USED +This parameter is the current amount of memory checked out using +.Fn sqlite3_malloc , +either directly or indirectly. +The figure includes calls made to +.Fn sqlite3_malloc +by the application and internal memory usage by the SQLite library. +Auxiliary page-cache memory controlled by SQLITE_CONFIG_PAGECACHE +is not included in this parameter. +The amount returned is the sum of the allocation sizes as reported +by the xSize method in sqlite3_mem_methods. +.It SQLITE_STATUS_MALLOC_SIZE +This parameter records the largest memory allocation request handed +to +.Fn sqlite3_malloc +or +.Fn sqlite3_realloc +(or their internal equivalents). +Only the value returned in the *pHighwater parameter to +.Fn sqlite3_status +is of interest. +The value written into the *pCurrent parameter is undefined. +.It SQLITE_STATUS_MALLOC_COUNT +This parameter records the number of separate memory allocations currently +checked out. +.It SQLITE_STATUS_PAGECACHE_USED +This parameter returns the number of pages used out of the pagecache memory allocator +that was configured using SQLITE_CONFIG_PAGECACHE. +The value returned is in pages, not in bytes. +.It SQLITE_STATUS_PAGECACHE_OVERFLOW +This parameter returns the number of bytes of page cache allocation +which could not be satisfied by the SQLITE_CONFIG_PAGECACHE +buffer and where forced to overflow to +.Fn sqlite3_malloc . +The returned value includes allocations that overflowed because they +where too large (they were larger than the "sz" parameter to SQLITE_CONFIG_PAGECACHE) +and allocations that overflowed because no space was left in the page +cache. +.It SQLITE_STATUS_PAGECACHE_SIZE +This parameter records the largest memory allocation request handed +to the pagecache memory allocator. +Only the value returned in the *pHighwater parameter to +.Fn sqlite3_status +is of interest. +The value written into the *pCurrent parameter is undefined. +.It SQLITE_STATUS_SCRATCH_USED +No longer used. +.It SQLITE_STATUS_SCRATCH_OVERFLOW +No longer used. +.It SQLITE_STATUS_SCRATCH_SIZE +No longer used. +.It SQLITE_STATUS_PARSER_STACK +The *pHighwater parameter records the deepest parser stack. +The *pCurrent value is undefined. +The *pHighwater value is only meaningful if SQLite is compiled with +YYTRACKMAXSTACKDEPTH. +.El +.Pp +New status parameters may be added from time to time. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8549. +.Bd -literal +#define SQLITE_STATUS_MEMORY_USED 0 +#define SQLITE_STATUS_PAGECACHE_USED 1 +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 +#define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */ +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */ +#define SQLITE_STATUS_MALLOC_SIZE 5 +#define SQLITE_STATUS_PARSER_STACK 6 +#define SQLITE_STATUS_PAGECACHE_SIZE 7 +#define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */ +#define SQLITE_STATUS_MALLOC_COUNT 9 +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mem_methods 3 , +.Xr sqlite3_status 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/SQLITE_STMTSTATUS_FULLSCAN_STEP.3 b/static/netbsd/man3/SQLITE_STMTSTATUS_FULLSCAN_STEP.3 new file mode 100644 index 00000000..acccb3e5 --- /dev/null +++ b/static/netbsd/man3/SQLITE_STMTSTATUS_FULLSCAN_STEP.3 @@ -0,0 +1,99 @@ +.Dd January 24, 2024 +.Dt SQLITE_STMTSTATUS_FULLSCAN_STEP 3 +.Os +.Sh NAME +.Nm SQLITE_STMTSTATUS_FULLSCAN_STEP , +.Nm SQLITE_STMTSTATUS_SORT , +.Nm SQLITE_STMTSTATUS_AUTOINDEX , +.Nm SQLITE_STMTSTATUS_VM_STEP , +.Nm SQLITE_STMTSTATUS_REPREPARE , +.Nm SQLITE_STMTSTATUS_RUN , +.Nm SQLITE_STMTSTATUS_FILTER_MISS , +.Nm SQLITE_STMTSTATUS_FILTER_HIT , +.Nm SQLITE_STMTSTATUS_MEMUSED +.Nd status parameters for prepared statements +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_STMTSTATUS_FULLSCAN_STEP +.Fd #define SQLITE_STMTSTATUS_SORT +.Fd #define SQLITE_STMTSTATUS_AUTOINDEX +.Fd #define SQLITE_STMTSTATUS_VM_STEP +.Fd #define SQLITE_STMTSTATUS_REPREPARE +.Fd #define SQLITE_STMTSTATUS_RUN +.Fd #define SQLITE_STMTSTATUS_FILTER_MISS +.Fd #define SQLITE_STMTSTATUS_FILTER_HIT +.Fd #define SQLITE_STMTSTATUS_MEMUSED +.Sh DESCRIPTION +These preprocessor macros define integer codes that name counter values +associated with the +.Fn sqlite3_stmt_status +interface. +The meanings of the various counters are as follows: +.Bl -tag -width Ds +.It SQLITE_STMTSTATUS_FULLSCAN_STEP +This is the number of times that SQLite has stepped forward in a table +as part of a full table scan. +Large numbers for this counter may indicate opportunities for performance +improvement through careful use of indices. +.It SQLITE_STMTSTATUS_SORT +This is the number of sort operations that have occurred. +A non-zero value in this counter may indicate an opportunity to improvement +performance through careful use of indices. +.It SQLITE_STMTSTATUS_AUTOINDEX +This is the number of rows inserted into transient indices that were +created automatically in order to help joins run faster. +A non-zero value in this counter may indicate an opportunity to improvement +performance by adding permanent indices that do not need to be reinitialized +each time the statement is run. +.It SQLITE_STMTSTATUS_VM_STEP +This is the number of virtual machine operations executed by the prepared +statement if that number is less than or equal to 2147483647. +The number of virtual machine operations can be used as a proxy for +the total work done by the prepared statement. +If the number of virtual machine operations exceeds 2147483647 then +the value returned by this statement status code is undefined. +.It SQLITE_STMTSTATUS_REPREPARE +This is the number of times that the prepare statement has been automatically +regenerated due to schema changes or changes to bound parameters +that might affect the query plan. +.It SQLITE_STMTSTATUS_RUN +This is the number of times that the prepared statement has been run. +A single "run" for the purposes of this counter is one or more calls +to +.Fn sqlite3_step +followed by a call to +.Fn sqlite3_reset . +The counter is incremented on the first +.Fn sqlite3_step +call of each cycle. +.It SQLITE_STMTSTATUS_FILTER_HIT SQLITE_STMTSTATUS_FILTER_MISS +SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join step +was bypassed because a Bloom filter returned not-found. +The corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number +of times that the Bloom filter returned a find, and thus the join step +had to be processed as normal. +.It SQLITE_STMTSTATUS_MEMUSED +This is the approximate number of bytes of heap memory used to store +the prepared statement. +This value is not actually a counter, and so the resetFlg parameter +to sqlite3_stmt_status() is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8805. +.Bd -literal +#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 +#define SQLITE_STMTSTATUS_SORT 2 +#define SQLITE_STMTSTATUS_AUTOINDEX 3 +#define SQLITE_STMTSTATUS_VM_STEP 4 +#define SQLITE_STMTSTATUS_REPREPARE 5 +#define SQLITE_STMTSTATUS_RUN 6 +#define SQLITE_STMTSTATUS_FILTER_MISS 7 +#define SQLITE_STMTSTATUS_FILTER_HIT 8 +#define SQLITE_STMTSTATUS_MEMUSED 99 +.Ed +.Sh SEE ALSO +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt_status 3 diff --git a/static/netbsd/man3/SQLITE_SYNC_NORMAL.3 b/static/netbsd/man3/SQLITE_SYNC_NORMAL.3 new file mode 100644 index 00000000..726b8b14 --- /dev/null +++ b/static/netbsd/man3/SQLITE_SYNC_NORMAL.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE_SYNC_NORMAL 3 +.Os +.Sh NAME +.Nm SQLITE_SYNC_NORMAL , +.Nm SQLITE_SYNC_FULL , +.Nm SQLITE_SYNC_DATAONLY +.Nd synchronization type flags +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_SYNC_NORMAL +.Fd #define SQLITE_SYNC_FULL +.Fd #define SQLITE_SYNC_DATAONLY +.Sh DESCRIPTION +When SQLite invokes the xSync() method of an sqlite3_io_methods +object it uses a combination of these integer values as the second +argument. +.Pp +When the SQLITE_SYNC_DATAONLY flag is used, it means that the sync +operation only needs to flush data to mass storage. +Inode information need not be flushed. +If the lower four bits of the flag equal SQLITE_SYNC_NORMAL, that means +to use normal fsync() semantics. +If the lower four bits equal SQLITE_SYNC_FULL, that means to use Mac +OS X style fullsync instead of fsync(). +.Pp +Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags with +the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL +settings. +The synchronous pragma determines when calls to the +xSync VFS method occur and applies uniformly across all platforms. +The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how energetic +or rigorous or forceful the sync operations are and only make a difference +on Mac OSX for the default SQLite code. +(Third-party VFS implementations might also make the distinction between +SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the operating systems +natively supported by SQLite, only Mac OSX cares about the difference.) +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 688. +.Bd -literal +#define SQLITE_SYNC_NORMAL 0x00002 +#define SQLITE_SYNC_FULL 0x00003 +#define SQLITE_SYNC_DATAONLY 0x00010 +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 diff --git a/static/netbsd/man3/SQLITE_TESTCTRL_FIRST.3 b/static/netbsd/man3/SQLITE_TESTCTRL_FIRST.3 new file mode 100644 index 00000000..9f0972d1 --- /dev/null +++ b/static/netbsd/man3/SQLITE_TESTCTRL_FIRST.3 @@ -0,0 +1,131 @@ +.Dd January 24, 2024 +.Dt SQLITE_TESTCTRL_FIRST 3 +.Os +.Sh NAME +.Nm SQLITE_TESTCTRL_FIRST , +.Nm SQLITE_TESTCTRL_PRNG_SAVE , +.Nm SQLITE_TESTCTRL_PRNG_RESTORE , +.Nm SQLITE_TESTCTRL_PRNG_RESET , +.Nm SQLITE_TESTCTRL_FK_NO_ACTION , +.Nm SQLITE_TESTCTRL_BITVEC_TEST , +.Nm SQLITE_TESTCTRL_FAULT_INSTALL , +.Nm SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS , +.Nm SQLITE_TESTCTRL_PENDING_BYTE , +.Nm SQLITE_TESTCTRL_ASSERT , +.Nm SQLITE_TESTCTRL_ALWAYS , +.Nm SQLITE_TESTCTRL_RESERVE , +.Nm SQLITE_TESTCTRL_JSON_SELFCHECK , +.Nm SQLITE_TESTCTRL_OPTIMIZATIONS , +.Nm SQLITE_TESTCTRL_ISKEYWORD , +.Nm SQLITE_TESTCTRL_SCRATCHMALLOC , +.Nm SQLITE_TESTCTRL_INTERNAL_FUNCTIONS , +.Nm SQLITE_TESTCTRL_LOCALTIME_FAULT , +.Nm SQLITE_TESTCTRL_EXPLAIN_STMT , +.Nm SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD , +.Nm SQLITE_TESTCTRL_NEVER_CORRUPT , +.Nm SQLITE_TESTCTRL_VDBE_COVERAGE , +.Nm SQLITE_TESTCTRL_BYTEORDER , +.Nm SQLITE_TESTCTRL_ISINIT , +.Nm SQLITE_TESTCTRL_SORTER_MMAP , +.Nm SQLITE_TESTCTRL_IMPOSTER , +.Nm SQLITE_TESTCTRL_PARSER_COVERAGE , +.Nm SQLITE_TESTCTRL_RESULT_INTREAL , +.Nm SQLITE_TESTCTRL_PRNG_SEED , +.Nm SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS , +.Nm SQLITE_TESTCTRL_SEEK_COUNT , +.Nm SQLITE_TESTCTRL_TRACEFLAGS , +.Nm SQLITE_TESTCTRL_TUNE , +.Nm SQLITE_TESTCTRL_LOGEST , +.Nm SQLITE_TESTCTRL_USELONGDOUBLE , +.Nm SQLITE_TESTCTRL_LAST +.Nd testing interface operation codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_TESTCTRL_FIRST +.Fd #define SQLITE_TESTCTRL_PRNG_SAVE +.Fd #define SQLITE_TESTCTRL_PRNG_RESTORE +.Fd #define SQLITE_TESTCTRL_PRNG_RESET +.Fd #define SQLITE_TESTCTRL_FK_NO_ACTION +.Fd #define SQLITE_TESTCTRL_BITVEC_TEST +.Fd #define SQLITE_TESTCTRL_FAULT_INSTALL +.Fd #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS +.Fd #define SQLITE_TESTCTRL_PENDING_BYTE +.Fd #define SQLITE_TESTCTRL_ASSERT +.Fd #define SQLITE_TESTCTRL_ALWAYS +.Fd #define SQLITE_TESTCTRL_RESERVE +.Fd #define SQLITE_TESTCTRL_JSON_SELFCHECK +.Fd #define SQLITE_TESTCTRL_OPTIMIZATIONS +.Fd #define SQLITE_TESTCTRL_ISKEYWORD +.Fd #define SQLITE_TESTCTRL_SCRATCHMALLOC +.Fd #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS +.Fd #define SQLITE_TESTCTRL_LOCALTIME_FAULT +.Fd #define SQLITE_TESTCTRL_EXPLAIN_STMT +.Fd #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD +.Fd #define SQLITE_TESTCTRL_NEVER_CORRUPT +.Fd #define SQLITE_TESTCTRL_VDBE_COVERAGE +.Fd #define SQLITE_TESTCTRL_BYTEORDER +.Fd #define SQLITE_TESTCTRL_ISINIT +.Fd #define SQLITE_TESTCTRL_SORTER_MMAP +.Fd #define SQLITE_TESTCTRL_IMPOSTER +.Fd #define SQLITE_TESTCTRL_PARSER_COVERAGE +.Fd #define SQLITE_TESTCTRL_RESULT_INTREAL +.Fd #define SQLITE_TESTCTRL_PRNG_SEED +.Fd #define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS +.Fd #define SQLITE_TESTCTRL_SEEK_COUNT +.Fd #define SQLITE_TESTCTRL_TRACEFLAGS +.Fd #define SQLITE_TESTCTRL_TUNE +.Fd #define SQLITE_TESTCTRL_LOGEST +.Fd #define SQLITE_TESTCTRL_USELONGDOUBLE +.Fd #define SQLITE_TESTCTRL_LAST +.Sh DESCRIPTION +These constants are the valid operation code parameters used as the +first argument to +.Fn sqlite3_test_control . +These parameters and their meanings are subject to change without notice. +These values are for testing purposes only. +Applications should not use any of these parameters or the +.Fn sqlite3_test_control +interface. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8283. +.Bd -literal +#define SQLITE_TESTCTRL_FIRST 5 +#define SQLITE_TESTCTRL_PRNG_SAVE 5 +#define SQLITE_TESTCTRL_PRNG_RESTORE 6 +#define SQLITE_TESTCTRL_PRNG_RESET 7 /* NOT USED */ +#define SQLITE_TESTCTRL_FK_NO_ACTION 7 +#define SQLITE_TESTCTRL_BITVEC_TEST 8 +#define SQLITE_TESTCTRL_FAULT_INSTALL 9 +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 +#define SQLITE_TESTCTRL_PENDING_BYTE 11 +#define SQLITE_TESTCTRL_ASSERT 12 +#define SQLITE_TESTCTRL_ALWAYS 13 +#define SQLITE_TESTCTRL_RESERVE 14 /* NOT USED */ +#define SQLITE_TESTCTRL_JSON_SELFCHECK 14 +#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 +#define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */ +#define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ +#define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17 +#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 +#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ +#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 +#define SQLITE_TESTCTRL_NEVER_CORRUPT 20 +#define SQLITE_TESTCTRL_VDBE_COVERAGE 21 +#define SQLITE_TESTCTRL_BYTEORDER 22 +#define SQLITE_TESTCTRL_ISINIT 23 +#define SQLITE_TESTCTRL_SORTER_MMAP 24 +#define SQLITE_TESTCTRL_IMPOSTER 25 +#define SQLITE_TESTCTRL_PARSER_COVERAGE 26 +#define SQLITE_TESTCTRL_RESULT_INTREAL 27 +#define SQLITE_TESTCTRL_PRNG_SEED 28 +#define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29 +#define SQLITE_TESTCTRL_SEEK_COUNT 30 +#define SQLITE_TESTCTRL_TRACEFLAGS 31 +#define SQLITE_TESTCTRL_TUNE 32 +#define SQLITE_TESTCTRL_LOGEST 33 +#define SQLITE_TESTCTRL_USELONGDOUBLE 34 +#define SQLITE_TESTCTRL_LAST 34 /* Largest TESTCTRL */ +.Ed +.Sh SEE ALSO +.Xr sqlite3_test_control 3 diff --git a/static/netbsd/man3/SQLITE_TRACE_STMT.3 b/static/netbsd/man3/SQLITE_TRACE_STMT.3 new file mode 100644 index 00000000..d1732f4a --- /dev/null +++ b/static/netbsd/man3/SQLITE_TRACE_STMT.3 @@ -0,0 +1,81 @@ +.Dd January 24, 2024 +.Dt SQLITE_TRACE_STMT 3 +.Os +.Sh NAME +.Nm SQLITE_TRACE_STMT , +.Nm SQLITE_TRACE_PROFILE , +.Nm SQLITE_TRACE_ROW , +.Nm SQLITE_TRACE_CLOSE +.Nd SQL trace event codes +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_TRACE_STMT +.Fd #define SQLITE_TRACE_PROFILE +.Fd #define SQLITE_TRACE_ROW +.Fd #define SQLITE_TRACE_CLOSE +.Sh DESCRIPTION +These constants identify classes of events that can be monitored using +the +.Fn sqlite3_trace_v2 +tracing logic. +The M argument to sqlite3_trace_v2(D,M,X,P) +is an OR-ed combination of one or more of the following constants. +The first argument to the trace callback is one of the following constants. +.Pp +New tracing constants may be added in future releases. +.Pp +A trace callback has four arguments: xCallback(T,C,P,X). +The T argument is one of the integer type codes above. +The C argument is a copy of the context pointer passed in as the fourth +argument to +.Fn sqlite3_trace_v2 . +The P and X arguments are pointers whose meanings depend on T. +.Bl -tag -width Ds +.It SQLITE_TRACE_STMT +An SQLITE_TRACE_STMT callback is invoked when a prepared statement +first begins running and possibly at other times during the execution +of the prepared statement, such as at the start of each trigger subprogram. +The P argument is a pointer to the prepared statement. +The X argument is a pointer to a string which is the unexpanded SQL +text of the prepared statement or an SQL comment that indicates the +invocation of a trigger. +The callback can compute the same text that would have been returned +by the legacy +.Fn sqlite3_trace +interface by using the X argument when X begins with "--" and invoking +sqlite3_expanded_sql(P) otherwise. +.It SQLITE_TRACE_PROFILE +An SQLITE_TRACE_PROFILE callback provides approximately the same information +as is provided by the +.Fn sqlite3_profile +callback. +The P argument is a pointer to the prepared statement +and the X argument points to a 64-bit integer which is approximately +the number of nanoseconds that the prepared statement took to run. +The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes. +.It SQLITE_TRACE_ROW +An SQLITE_TRACE_ROW callback is invoked whenever a prepared statement +generates a single row of result. +The P argument is a pointer to the prepared statement +and the X argument is unused. +.It SQLITE_TRACE_CLOSE +An SQLITE_TRACE_CLOSE callback is invoked when a database connection +closes. +The P argument is a pointer to the database connection +object and the X argument is unused. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3326. +.Bd -literal +#define SQLITE_TRACE_STMT 0x01 +#define SQLITE_TRACE_PROFILE 0x02 +#define SQLITE_TRACE_ROW 0x04 +#define SQLITE_TRACE_CLOSE 0x08 +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_stmt 3 , +.Xr sqlite3_trace 3 , +.Xr sqlite3_trace_v2 3 diff --git a/static/netbsd/man3/SQLITE_TXN_NONE.3 b/static/netbsd/man3/SQLITE_TXN_NONE.3 new file mode 100644 index 00000000..ea3e3263 --- /dev/null +++ b/static/netbsd/man3/SQLITE_TXN_NONE.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE_TXN_NONE 3 +.Os +.Sh NAME +.Nm SQLITE_TXN_NONE , +.Nm SQLITE_TXN_READ , +.Nm SQLITE_TXN_WRITE +.Nd allowed return values from sqlite3_txn_state() +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_TXN_NONE +.Fd #define SQLITE_TXN_READ +.Fd #define SQLITE_TXN_WRITE +.Sh DESCRIPTION +These constants define the current transaction state of a database +file. +The sqlite3_txn_state(D,S) interface returns +one of these constants in order to describe the transaction state of +schema S in database connection D. +.Bl -tag -width Ds +.It SQLITE_TXN_NONE +The SQLITE_TXN_NONE state means that no transaction is currently pending. +.It SQLITE_TXN_READ +The SQLITE_TXN_READ state means that the database is currently in a +read transaction. +Content has been read from the database file but nothing in the database +file has changed. +The transaction state will advanced to SQLITE_TXN_WRITE if any changes +occur and there are no other conflicting concurrent write transactions. +The transaction state will revert to SQLITE_TXN_NONE following a ROLLBACK +or COMMIT. +.It SQLITE_TXN_WRITE +The SQLITE_TXN_WRITE state means that the database is currently in +a write transaction. +Content has been written to the database file but has not yet committed. +The transaction state will change to to SQLITE_TXN_NONE at the next +ROLLBACK or COMMIT. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6673. +.Bd -literal +#define SQLITE_TXN_NONE 0 +#define SQLITE_TXN_READ 1 +#define SQLITE_TXN_WRITE 2 +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 diff --git a/static/netbsd/man3/SQLITE_UTF8.3 b/static/netbsd/man3/SQLITE_UTF8.3 new file mode 100644 index 00000000..0b13bf87 --- /dev/null +++ b/static/netbsd/man3/SQLITE_UTF8.3 @@ -0,0 +1,33 @@ +.Dd January 24, 2024 +.Dt SQLITE_UTF8 3 +.Os +.Sh NAME +.Nm SQLITE_UTF8 , +.Nm SQLITE_UTF16LE , +.Nm SQLITE_UTF16BE , +.Nm SQLITE_UTF16 , +.Nm SQLITE_ANY , +.Nm SQLITE_UTF16_ALIGNED +.Nd text encodings +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_UTF8 +.Fd #define SQLITE_UTF16LE +.Fd #define SQLITE_UTF16BE +.Fd #define SQLITE_UTF16 +.Fd #define SQLITE_ANY +.Fd #define SQLITE_UTF16_ALIGNED +.Sh DESCRIPTION +These constant define integer codes that represent the various text +encodings supported by SQLite. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5500. +.Bd -literal +#define SQLITE_UTF8 1 /* IMP: R-37514-35566 */ +#define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */ +#define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */ +#define SQLITE_UTF16 4 /* Use native byte order */ +#define SQLITE_ANY 5 /* Deprecated */ +#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ +.Ed diff --git a/static/netbsd/man3/SQLITE_VERSION.3 b/static/netbsd/man3/SQLITE_VERSION.3 new file mode 100644 index 00000000..88204bfa --- /dev/null +++ b/static/netbsd/man3/SQLITE_VERSION.3 @@ -0,0 +1,46 @@ +.Dd January 24, 2024 +.Dt SQLITE_VERSION 3 +.Os +.Sh NAME +.Nm SQLITE_VERSION , +.Nm SQLITE_VERSION_NUMBER , +.Nm SQLITE_SOURCE_ID +.Nd compile-Time library version numbers +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_VERSION +.Fd #define SQLITE_VERSION_NUMBER +.Fd #define SQLITE_SOURCE_ID +.Sh DESCRIPTION +The SQLITE_VERSION C preprocessor macro in the sqlite3.h +header evaluates to a string literal that is the SQLite version in +the format "X.Y.Z" where X is the major version number (always 3 for +SQLite3) and Y is the minor version number and Z is the release number. +The SQLITE_VERSION_NUMBER C preprocessor macro +resolves to an integer with the value (X*1000000 + Y*1000 + Z) where +X, Y, and Z are the same numbers used in SQLITE_VERSION. +The SQLITE_VERSION_NUMBER for any given release of SQLite will also +be larger than the release from which it is derived. +Either Y will be held constant and Z will be incremented or else Y +will be incremented and Z will be reset to zero. +.Pp +Since version 3.6.18 (dateof:3.6.18), SQLite +source code has been stored in the Fossil configuration management +system. +The SQLITE_SOURCE_ID macro evaluates to a string which identifies a +particular check-in of SQLite within its configuration management system. +The SQLITE_SOURCE_ID string contains the date and time of the check-in +(UTC) and a SHA1 or SHA3-256 hash of the entire source tree. +If the source code has been edited in any way since it was last checked +in, then the last four hexadecimal digits of the hash may be modified. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 120. +.Bd -literal +#define SQLITE_VERSION "3.45.1" +#define SQLITE_VERSION_NUMBER 3045001 +#define SQLITE_SOURCE_ID "2024-01-30 16:01:20 e876e51a0ed5c5b3126f52e532044363a014bc594cfefa87ffb5b82257cc467a" +.Ed +.Sh SEE ALSO +.Xr sqlite3_version 3 diff --git a/static/netbsd/man3/SQLITE_VTAB_CONSTRAINT_SUPPORT.3 b/static/netbsd/man3/SQLITE_VTAB_CONSTRAINT_SUPPORT.3 new file mode 100644 index 00000000..54721019 --- /dev/null +++ b/static/netbsd/man3/SQLITE_VTAB_CONSTRAINT_SUPPORT.3 @@ -0,0 +1,90 @@ +.Dd January 24, 2024 +.Dt SQLITE_VTAB_CONSTRAINT_SUPPORT 3 +.Os +.Sh NAME +.Nm SQLITE_VTAB_CONSTRAINT_SUPPORT , +.Nm SQLITE_VTAB_INNOCUOUS , +.Nm SQLITE_VTAB_DIRECTONLY , +.Nm SQLITE_VTAB_USES_ALL_SCHEMAS +.Nd virtual table configuration options +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_VTAB_CONSTRAINT_SUPPORT +.Fd #define SQLITE_VTAB_INNOCUOUS +.Fd #define SQLITE_VTAB_DIRECTONLY +.Fd #define SQLITE_VTAB_USES_ALL_SCHEMAS +.Sh DESCRIPTION +These macros define the various options to the +.Fn sqlite3_vtab_config +interface that virtual table implementations can use to +customize and optimize their behavior. +.Bl -tag -width Ds +.It SQLITE_VTAB_CONSTRAINT_SUPPORT +Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) +are supported, where X is an integer. +If X is zero, then the virtual table whose xCreate +or xConnect method invoked +.Fn sqlite3_vtab_config +does not support constraints. +In this configuration (which is the default) if a call to the xUpdate +method returns SQLITE_CONSTRAINT, then the entire +statement is rolled back as if OR ABORT had been specified +as part of the users SQL statement, regardless of the actual ON CONFLICT +mode specified. +.Pp +If X is non-zero, then the virtual table implementation guarantees +that if xUpdate returns SQLITE_CONSTRAINT, +it will do so before any modifications to internal or persistent data +structures have been made. +If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, +SQLite is able to roll back a statement or database transaction, and +abandon or continue processing the current SQL statement as appropriate. +If the ON CONFLICT mode is REPLACE and the xUpdate method returns +SQLITE_CONSTRAINT, SQLite handles this as if the ON +CONFLICT mode had been ABORT. +.Pp +Virtual table implementations that are required to handle OR REPLACE +must do so within the xUpdate method. +If a call to the +.Fn sqlite3_vtab_on_conflict +function indicates that the current ON CONFLICT policy is REPLACE, +the virtual table implementation should silently replace the appropriate +rows within the xUpdate callback and return SQLITE_OK. +Or, if this is not possible, it may return SQLITE_CONSTRAINT, in which +case SQLite falls back to OR ABORT constraint handling. +.It SQLITE_VTAB_DIRECTONLY +Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_DIRECTONLY) +from within the the xConnect or xCreate methods of a +virtual table implementation prohibits that virtual table +from being used from within triggers and views. +.It SQLITE_VTAB_INNOCUOUS +Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_INNOCUOUS) +from within the the xConnect or xCreate methods of a +virtual table implementation identify that virtual table +as being safe to use from within triggers and views. +Conceptually, the SQLITE_VTAB_INNOCUOUS tag means that the virtual +table can do no serious harm even if it is controlled by a malicious +hacker. +Developers should avoid setting the SQLITE_VTAB_INNOCUOUS flag unless +absolutely necessary. +.It SQLITE_VTAB_USES_ALL_SCHEMAS +Calls of the form sqlite3_vtab_config(db,SQLITE_VTAB_USES_ALL_SCHEMA) +from within the the xConnect or xCreate methods of a +virtual table implementation instruct the query planner +to begin at least a read transaction on all schemas ("main", "temp", +and any ATTACH-ed databases) whenever the virtual table is used. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9740. +.Bd -literal +#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1 +#define SQLITE_VTAB_INNOCUOUS 2 +#define SQLITE_VTAB_DIRECTONLY 3 +#define SQLITE_VTAB_USES_ALL_SCHEMAS 4 +.Ed +.Sh SEE ALSO +.Xr sqlite3_vtab_config 3 , +.Xr sqlite3_vtab_on_conflict 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/SQLITE_WIN32_DATA_DIRECTORY_TYPE.3 b/static/netbsd/man3/SQLITE_WIN32_DATA_DIRECTORY_TYPE.3 new file mode 100644 index 00000000..035bb564 --- /dev/null +++ b/static/netbsd/man3/SQLITE_WIN32_DATA_DIRECTORY_TYPE.3 @@ -0,0 +1,24 @@ +.Dd January 24, 2024 +.Dt SQLITE_WIN32_DATA_DIRECTORY_TYPE 3 +.Os +.Sh NAME +.Nm SQLITE_WIN32_DATA_DIRECTORY_TYPE , +.Nm SQLITE_WIN32_TEMP_DIRECTORY_TYPE +.Nd win32 directory types +.Sh SYNOPSIS +.In sqlite3.h +.Fd #define SQLITE_WIN32_DATA_DIRECTORY_TYPE +.Fd #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE +.Sh DESCRIPTION +These macros are only available on Windows. +They define the allowed values for the type argument to the sqlite3_win32_set_directory +interface. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6545. +.Bd -literal +#define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1 +#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2 +.Ed +.Sh SEE ALSO +.Xr sqlite3_win32_set_directory 3 diff --git a/static/netbsd/man3/SRP_Calc_B.3 b/static/netbsd/man3/SRP_Calc_B.3 new file mode 100644 index 00000000..97c94b47 --- /dev/null +++ b/static/netbsd/man3/SRP_Calc_B.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: SRP_Calc_B.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SRP_Calc_B 3" +.TH SRP_Calc_B 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SRP_Calc_server_key, +SRP_Calc_A, +SRP_Calc_B_ex, +SRP_Calc_B, +SRP_Calc_u_ex, +SRP_Calc_u, +SRP_Calc_x_ex, +SRP_Calc_x, +SRP_Calc_client_key_ex, +SRP_Calc_client_key +\&\- SRP authentication primitives +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 7 +\& /* server side .... */ +\& BIGNUM *SRP_Calc_server_key(const BIGNUM *A, const BIGNUM *v, const BIGNUM *u, +\& const BIGNUM *b, const BIGNUM *N); +\& BIGNUM *SRP_Calc_B_ex(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g, +\& const BIGNUM *v, OSSL_LIB_CTX *libctx, const char *propq); +\& BIGNUM *SRP_Calc_B(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g, +\& const BIGNUM *v); +\& +\& BIGNUM *SRP_Calc_u_ex(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& BIGNUM *SRP_Calc_u(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N); +\& +\& /* client side .... */ +\& BIGNUM *SRP_Calc_client_key_ex(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g, +\& const BIGNUM *x, const BIGNUM *a, const BIGNUM *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& BIGNUM *SRP_Calc_client_key(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g, +\& const BIGNUM *x, const BIGNUM *a, const BIGNUM *u); +\& BIGNUM *SRP_Calc_x_ex(const BIGNUM *s, const char *user, const char *pass, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& BIGNUM *SRP_Calc_x(const BIGNUM *s, const char *user, const char *pass); +\& BIGNUM *SRP_Calc_A(const BIGNUM *a, const BIGNUM *N, const BIGNUM *g); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. There are no +available replacement functions at this time. +.PP +The SRP functions described on this page are used to calculate various +parameters and keys used by SRP as defined in RFC2945. The server key and \fIB\fR +and \fIu\fR parameters are used on the server side and are calculated via +\&\fBSRP_Calc_server_key()\fR, \fBSRP_Calc_B_ex()\fR, \fBSRP_Calc_B()\fR, \fBSRP_Calc_u_ex()\fR and +\&\fBSRP_Calc_u()\fR. The client key and \fBx\fR and \fBA\fR parameters are used on the +client side and are calculated via the functions \fBSRP_Calc_client_key_ex()\fR, +\&\fBSRP_Calc_client_key()\fR, \fBSRP_Calc_x_ex()\fR, \fBSRP_Calc_x()\fR and \fBSRP_Calc_A()\fR. See +RFC2945 for a detailed description of their usage and the meaning of the various +BIGNUM parameters to these functions. +.PP +Most of these functions come in two forms. Those that take a \fIlibctx\fR and +\&\fIpropq\fR parameter, and those that don\*(Aqt. Any cryptogrpahic functions that +are fetched and used during the calculation use the provided \fIlibctx\fR and +\&\fIpropq\fR. See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more details. The variants +that do not take a \fIlibctx\fR and \fIpropq\fR parameter use the default library +context and property query string. The \fBSRP_Calc_server_key()\fR and \fBSRP_Calc_A()\fR +functions do not have a form that takes \fIlibctx\fR or \fIpropq\fR parameters because +they do not need to fetch any cryptographic algorithms. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return the calculated key or parameter, or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-srp\fR\|(1), +\&\fBSRP_VBASE_new\fR\|(3), +\&\fBSRP_user_pwd_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +SRP_Calc_B_ex, SRP_Calc_u_ex, SRP_Calc_client_key_ex and SRP_Calc_x_ex were +introduced in OpenSSL 3.0. +.PP +All of the other functions were added in OpenSSL 1.0.1. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SRP_VBASE_new.3 b/static/netbsd/man3/SRP_VBASE_new.3 new file mode 100644 index 00000000..e5dba8f0 --- /dev/null +++ b/static/netbsd/man3/SRP_VBASE_new.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: SRP_VBASE_new.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SRP_VBASE_new 3" +.TH SRP_VBASE_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SRP_VBASE_new, +SRP_VBASE_free, +SRP_VBASE_init, +SRP_VBASE_add0_user, +SRP_VBASE_get1_by_user, +SRP_VBASE_get_by_user +\&\- Functions to create and manage a stack of SRP user verifier information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& SRP_VBASE *SRP_VBASE_new(char *seed_key); +\& void SRP_VBASE_free(SRP_VBASE *vb); +\& +\& int SRP_VBASE_init(SRP_VBASE *vb, char *verifier_file); +\& +\& int SRP_VBASE_add0_user(SRP_VBASE *vb, SRP_user_pwd *user_pwd); +\& SRP_user_pwd *SRP_VBASE_get1_by_user(SRP_VBASE *vb, char *username); +\& SRP_user_pwd *SRP_VBASE_get_by_user(SRP_VBASE *vb, char *username); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. There are no +available replacement functions at this time. +.PP +The \fBSRP_VBASE_new()\fR function allocates a structure to store server side SRP +verifier information. +If \fBseed_key\fR is not NULL a copy is stored and used to generate dummy parameters +for users that are not found by \fBSRP_VBASE_get1_by_user()\fR. This allows the server +to hide the fact that it doesn\*(Aqt have a verifier for a particular username, +as described in section 2.5.1.3 \*(AqUnknown SRP\*(Aq of RFC 5054. +The seed string should contain random NUL terminated binary data (therefore +the random data should not contain NUL bytes!). +.PP +The \fBSRP_VBASE_free()\fR function frees up the \fBvb\fR structure. +If \fBvb\fR is NULL, nothing is done. +.PP +The \fBSRP_VBASE_init()\fR function parses the information in a verifier file and +populates the \fBvb\fR structure. +The verifier file is a text file containing multiple entries, whose format is: +flag base64(verifier) base64(salt) username gNid userinfo(optional) +where the flag can be \*(AqV\*(Aq (valid) or \*(AqR\*(Aq (revoked). +Note that the base64 encoding used here is non\-standard so it is recommended +to use \fBopenssl\-srp\fR\|(1) to generate this file. +.PP +The \fBSRP_VBASE_add0_user()\fR function adds the \fBuser_pwd\fR verifier information +to the \fBvb\fR structure. See \fBSRP_user_pwd_new\fR\|(3) to create and populate this +record. +The library takes ownership of \fBuser_pwd\fR, it should not be freed by the caller. +.PP +The \fBSRP_VBASE_get1_by_user()\fR function returns the password info for the user +whose username matches \fBusername\fR. It replaces the deprecated +\&\fBSRP_VBASE_get_by_user()\fR. +If no matching user is found but a seed_key and default gN parameters have been +set, dummy authentication information is generated from the seed_key, allowing +the server to hide the fact that it doesn\*(Aqt have a verifier for a particular +username. When using SRP as a TLS authentication mechanism, this will cause +the handshake to proceed normally but the first client will be rejected with +a "bad_record_mac" alert, as if the password was incorrect. +If no matching user is found and the seed_key is not set, NULL is returned. +Ownership of the returned pointer is released to the caller, it must be freed +with \fBSRP_user_pwd_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSRP_VBASE_init()\fR returns \fBSRP_NO_ERROR\fR (0) on success and a positive value +on failure. +The error codes are \fBSRP_ERR_OPEN_FILE\fR if the file could not be opened, +\&\fBSRP_ERR_VBASE_INCOMPLETE_FILE\fR if the file could not be parsed, +\&\fBSRP_ERR_MEMORY\fR on memory allocation failure and \fBSRP_ERR_VBASE_BN_LIB\fR +for invalid decoded parameter values. +.PP +\&\fBSRP_VBASE_add0_user()\fR returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-srp\fR\|(1), +\&\fBSRP_create_verifier\fR\|(3), +\&\fBSRP_user_pwd_new\fR\|(3), +\&\fBSSL_CTX_set_srp_password\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSRP_VBASE_add0_user()\fR function was added in OpenSSL 3.0. +.PP +All other functions were added in OpenSSL 1.0.1. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SRP_create_verifier.3 b/static/netbsd/man3/SRP_create_verifier.3 new file mode 100644 index 00000000..1596d3b6 --- /dev/null +++ b/static/netbsd/man3/SRP_create_verifier.3 @@ -0,0 +1,200 @@ +.\" $NetBSD: SRP_create_verifier.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SRP_create_verifier 3" +.TH SRP_create_verifier 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SRP_create_verifier_ex, +SRP_create_verifier, +SRP_create_verifier_BN_ex, +SRP_create_verifier_BN, +SRP_check_known_gN_param, +SRP_get_default_gN +\&\- SRP authentication primitives +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 11 +\& int SRP_create_verifier_BN_ex(const char *user, const char *pass, BIGNUM **salt, +\& BIGNUM **verifier, const BIGNUM *N, +\& const BIGNUM *g, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& char *SRP_create_verifier_BN(const char *user, const char *pass, BIGNUM **salt, +\& BIGNUM **verifier, const BIGNUM *N, const BIGNUM *g); +\& char *SRP_create_verifier_ex(const char *user, const char *pass, char **salt, +\& char **verifier, const char *N, const char *g, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& char *SRP_create_verifier(const char *user, const char *pass, char **salt, +\& char **verifier, const char *N, const char *g); +\& +\& char *SRP_check_known_gN_param(const BIGNUM *g, const BIGNUM *N); +\& SRP_gN *SRP_get_default_gN(const char *id); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. There are no +available replacement functions at this time. +.PP +The \fBSRP_create_verifier_BN_ex()\fR function creates an SRP password verifier from +the supplied parameters as defined in section 2.4 of RFC 5054 using the library +context \fIlibctx\fR and property query string \fIpropq\fR. Any cryptographic +algorithms that need to be fetched will use the \fIlibctx\fR and \fIpropq\fR. See +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7). +.PP +\&\fBSRP_create_verifier_BN()\fR is the same as \fBSRP_create_verifier_BN_ex()\fR except the +default library context and property query string is used. +.PP +On successful exit \fI*verifier\fR will point to a newly allocated BIGNUM containing +the verifier and (if a salt was not provided) \fI*salt\fR will be populated with a +newly allocated BIGNUM containing a random salt. If \fI*salt\fR is not NULL then +the provided salt is used instead. +The caller is responsible for freeing the allocated \fI*salt\fR and \fI*verifier\fR +BIGNUMS (use \fBBN_free\fR\|(3)). +.PP +The \fBSRP_create_verifier()\fR function is similar to \fBSRP_create_verifier_BN()\fR but +all numeric parameters are in a non\-standard base64 encoding originally designed +for compatibility with libsrp. This is mainly present for historical compatibility +and its use is discouraged. +It is possible to pass NULL as \fIN\fR and an SRP group id as \fIg\fR instead to +load the appropriate gN values (see \fBSRP_get_default_gN()\fR). +If both \fIN\fR and \fIg\fR are NULL the 8192\-bit SRP group parameters are used. +The caller is responsible for freeing the allocated \fI*salt\fR and \fI*verifier\fR +(use \fBOPENSSL_free\fR\|(3)). +.PP +The \fBSRP_check_known_gN_param()\fR function checks that \fIg\fR and \fIN\fR are valid +SRP group parameters from RFC 5054 appendix A. +.PP +The \fBSRP_get_default_gN()\fR function returns the gN parameters for the RFC 5054 \fIid\fR +SRP group size. +The known ids are "1024", "1536", "2048", "3072", "4096", "6144" and "8192". +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSRP_create_verifier_BN_ex()\fR and \fBSRP_create_verifier_BN()\fR return 1 on success and +0 on failure. +.PP +\&\fBSRP_create_verifier_ex()\fR and \fBSRP_create_verifier()\fR return NULL on failure and a +non\-NULL value on success: +"*" if \fIN\fR is not NULL, the selected group id otherwise. This value should +not be freed. +.PP +\&\fBSRP_check_known_gN_param()\fR returns the text representation of the group id +(i.e. the prime bit size) or NULL if the arguments are not valid SRP group parameters. +This value should not be freed. +.PP +\&\fBSRP_get_default_gN()\fR returns NULL if \fIid\fR is not a valid group size, +or the 8192\-bit group parameters if \fIid\fR is NULL. +.SH EXAMPLES +.IX Header "EXAMPLES" +Generate and store a 8192 bit password verifier (error handling +omitted for clarity): +.PP +.Vb 2 +\& #include +\& #include +\& +\& const char *username = "username"; +\& const char *password = "password"; +\& +\& SRP_VBASE *srpData = SRP_VBASE_new(NULL); +\& +\& SRP_gN *gN = SRP_get_default_gN("8192"); +\& +\& BIGNUM *salt = NULL, *verifier = NULL; +\& SRP_create_verifier_BN_ex(username, password, &salt, &verifier, gN\->N, gN\->g, +\& NULL, NULL); +\& +\& SRP_user_pwd *pwd = SRP_user_pwd_new(); +\& SRP_user_pwd_set1_ids(pwd, username, NULL); +\& SRP_user_pwd_set0_sv(pwd, salt, verifier); +\& SRP_user_pwd_set_gN(pwd, gN\->g, gN\->N); +\& +\& SRP_VBASE_add0_user(srpData, pwd); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-srp\fR\|(1), +\&\fBSRP_VBASE_new\fR\|(3), +\&\fBSRP_user_pwd_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSRP_create_verifier_BN_ex()\fR and \fBSRP_create_verifier_ex()\fR were introduced in +OpenSSL 3.0. All other functions were added in OpenSSL 1.0.1. +.PP +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SRP_user_pwd_new.3 b/static/netbsd/man3/SRP_user_pwd_new.3 new file mode 100644 index 00000000..16986cb0 --- /dev/null +++ b/static/netbsd/man3/SRP_user_pwd_new.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: SRP_user_pwd_new.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SRP_user_pwd_new 3" +.TH SRP_user_pwd_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SRP_user_pwd_new, +SRP_user_pwd_free, +SRP_user_pwd_set1_ids, +SRP_user_pwd_set_gN, +SRP_user_pwd_set0_sv +\&\- Functions to create a record of SRP user verifier information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& SRP_user_pwd *SRP_user_pwd_new(void); +\& void SRP_user_pwd_free(SRP_user_pwd *user_pwd); +\& +\& int SRP_user_pwd_set1_ids(SRP_user_pwd *user_pwd, const char *id, const char *info); +\& void SRP_user_pwd_set_gN(SRP_user_pwd *user_pwd, const BIGNUM *g, const BIGNUM *N); +\& int SRP_user_pwd_set0_sv(SRP_user_pwd *user_pwd, BIGNUM *s, BIGNUM *v); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. There are no +available replacement functions at this time. +.PP +The \fBSRP_user_pwd_new()\fR function allocates a structure to store a user verifier +record. +.PP +The \fBSRP_user_pwd_free()\fR function frees up the \fBuser_pwd\fR structure. +If \fBuser_pwd\fR is NULL, nothing is done. +.PP +The \fBSRP_user_pwd_set1_ids()\fR function sets the username to \fBid\fR and the optional +user info to \fBinfo\fR for \fBuser_pwd\fR. +The library allocates new copies of \fBid\fR and \fBinfo\fR, the caller still +owns the original memory. +.PP +The \fBSRP_user_pwd_set0_sv()\fR function sets the user salt to \fBs\fR and the verifier +to \fBv\fR for \fBuser_pwd\fR. +The library takes ownership of the values, they should not be freed by the caller. +.PP +The \fBSRP_user_pwd_set_gN()\fR function sets the SRP group parameters for \fBuser_pwd\fR. +The memory is not freed by \fBSRP_user_pwd_free()\fR, the caller must make sure it is +freed once it is no longer used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSRP_user_pwd_set1_ids()\fR returns 1 on success and 0 on failure or if \fBid\fR was NULL. +.PP +\&\fBSRP_user_pwd_set0_sv()\fR returns 1 if both \fBs\fR and \fBv\fR are not NULL, 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-srp\fR\|(1), +\&\fBSRP_create_verifier\fR\|(3), +\&\fBSRP_VBASE_new\fR\|(3), +\&\fBSSL_CTX_set_srp_password\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were made public in OpenSSL 3.0 and are deprecated. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CIPHER_get_name.3 b/static/netbsd/man3/SSL_CIPHER_get_name.3 new file mode 100644 index 00000000..f940efdb --- /dev/null +++ b/static/netbsd/man3/SSL_CIPHER_get_name.3 @@ -0,0 +1,267 @@ +.\" $NetBSD: SSL_CIPHER_get_name.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CIPHER_get_name 3" +.TH SSL_CIPHER_get_name 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CIPHER_get_name, +SSL_CIPHER_standard_name, +OPENSSL_cipher_name, +SSL_CIPHER_get_bits, +SSL_CIPHER_get_version, +SSL_CIPHER_description, +SSL_CIPHER_get_cipher_nid, +SSL_CIPHER_get_digest_nid, +SSL_CIPHER_get_handshake_digest, +SSL_CIPHER_get_kx_nid, +SSL_CIPHER_get_auth_nid, +SSL_CIPHER_is_aead, +SSL_CIPHER_find, +SSL_CIPHER_get_id, +SSL_CIPHER_get_protocol_id +\&\- get SSL_CIPHER properties +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); +\& const char *SSL_CIPHER_standard_name(const SSL_CIPHER *cipher); +\& const char *OPENSSL_cipher_name(const char *stdname); +\& int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); +\& const char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); +\& char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); +\& int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c); +\& int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c); +\& const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c); +\& int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c); +\& int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c); +\& int SSL_CIPHER_is_aead(const SSL_CIPHER *c); +\& const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr); +\& uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c); +\& uint16_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CIPHER_get_name()\fR returns a pointer to the name of \fBcipher\fR. If the +\&\fBcipher\fR is NULL, it returns "(NONE)". +.PP +\&\fBSSL_CIPHER_standard_name()\fR returns a pointer to the standard RFC name of +\&\fBcipher\fR. If the \fBcipher\fR is NULL, it returns "(NONE)". If the \fBcipher\fR +has no standard name, it returns \fBNULL\fR. If \fBcipher\fR was defined in both +SSLv3 and TLS, it returns the TLS name. +.PP +\&\fBOPENSSL_cipher_name()\fR returns a pointer to the OpenSSL name of \fBstdname\fR. +If the \fBstdname\fR is NULL, or \fBstdname\fR has no corresponding OpenSSL name, +it returns "(NONE)". Where both exist, \fBstdname\fR should be the TLS name rather +than the SSLv3 name. +.PP +\&\fBSSL_CIPHER_get_bits()\fR returns the number of secret bits used for \fBcipher\fR. +If \fBcipher\fR is NULL, 0 is returned. +.PP +\&\fBSSL_CIPHER_get_version()\fR returns string which indicates the SSL/TLS protocol +version that first defined the cipher. It returns "(NONE)" if \fBcipher\fR is NULL. +.PP +\&\fBSSL_CIPHER_get_cipher_nid()\fR returns the cipher NID corresponding to \fBc\fR. +If there is no cipher (e.g. for cipher suites with no encryption) then +\&\fBNID_undef\fR is returned. +.PP +\&\fBSSL_CIPHER_get_digest_nid()\fR returns the digest NID corresponding to the MAC +used by \fBc\fR during record encryption/decryption. If there is no digest (e.g. +for AEAD cipher suites) then \fBNID_undef\fR is returned. +.PP +\&\fBSSL_CIPHER_get_handshake_digest()\fR returns an EVP_MD for the digest used during +the SSL/TLS handshake when using the SSL_CIPHER \fBc\fR. Note that this may be +different to the digest used to calculate the MAC for encrypted records. +.PP +\&\fBSSL_CIPHER_get_kx_nid()\fR returns the key exchange NID corresponding to the method +used by \fBc\fR. If there is no key exchange, then \fBNID_undef\fR is returned. +If any appropriate key exchange algorithm can be used (as in the case of TLS 1.3 +cipher suites) \fBNID_kx_any\fR is returned. Examples (not comprehensive): +.PP +.Vb 4 +\& NID_kx_rsa +\& NID_kx_ecdhe +\& NID_kx_dhe +\& NID_kx_psk +.Ve +.PP +\&\fBSSL_CIPHER_get_auth_nid()\fR returns the authentication NID corresponding to the method +used by \fBc\fR. If there is no authentication, then \fBNID_undef\fR is returned. +If any appropriate authentication algorithm can be used (as in the case of +TLS 1.3 cipher suites) \fBNID_auth_any\fR is returned. Examples (not comprehensive): +.PP +.Vb 3 +\& NID_auth_rsa +\& NID_auth_ecdsa +\& NID_auth_psk +.Ve +.PP +\&\fBSSL_CIPHER_is_aead()\fR returns 1 if the cipher \fBc\fR is AEAD (e.g. GCM or +ChaCha20/Poly1305), and 0 if it is not AEAD. +.PP +\&\fBSSL_CIPHER_find()\fR returns a \fBSSL_CIPHER\fR structure which has the cipher ID stored +in \fBptr\fR. The \fBptr\fR parameter is a two element array of \fBchar\fR, which stores the +two\-byte TLS cipher ID (as allocated by IANA) in network byte order. This parameter +is usually retrieved from a TLS packet by using functions like +\&\fBSSL_client_hello_get0_ciphers\fR\|(3). \fBSSL_CIPHER_find()\fR returns NULL if an +error occurs or the indicated cipher is not found. +.PP +\&\fBSSL_CIPHER_get_id()\fR returns the OpenSSL\-specific ID of the given cipher \fBc\fR. That ID is +not the same as the IANA\-specific ID. +.PP +\&\fBSSL_CIPHER_get_protocol_id()\fR returns the two\-byte ID used in the TLS protocol of the given +cipher \fBc\fR. +.PP +\&\fBSSL_CIPHER_description()\fR returns a textual description of the cipher used +into the buffer \fBbuf\fR of length \fBlen\fR provided. If \fBbuf\fR is provided, it +must be at least 128 bytes. If \fBbuf\fR is NULL it will be allocated using +\&\fBOPENSSL_malloc()\fR. If the provided buffer is too small, or the allocation fails, +\&\fBNULL\fR is returned. +.PP +The string returned by \fBSSL_CIPHER_description()\fR consists of several fields +separated by whitespace: +.IP 4 +.IX Item "" +Textual representation of the cipher name. +.IP "" 4 +.IX Item "" +The minimum protocol version that the ciphersuite supports, such as \fBTLSv1.2\fR. +Note that this is not always the same as the protocol version in which the +ciphersuite was first defined because some ciphersuites are backwards compatible +with earlier protocol versions. +.IP "Kx=" 4 +.IX Item "Kx=" +Key exchange method such as \fBRSA\fR, \fBECDHE\fR, etc. +.IP Au= 4 +.IX Item "Au=" +Authentication method such as \fBRSA\fR, \fBNone\fR, etc.. None is the +representation of anonymous ciphers. +.IP "Enc=" 4 +.IX Item "Enc=" +Encryption method, with number of secret bits, such as \fBAESGCM(128)\fR. +.IP "Mac=" 4 +.IX Item "Mac=" +Message digest, such as \fBSHA256\fR. +.PP +Some examples for the output of \fBSSL_CIPHER_description()\fR: +.PP +.Vb 2 +\& ECDHE\-RSA\-AES256\-GCM\-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD +\& RSA\-PSK\-AES256\-CBC\-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CIPHER_get_name()\fR, \fBSSL_CIPHER_standard_name()\fR, \fBOPENSSL_cipher_name()\fR, +\&\fBSSL_CIPHER_get_version()\fR and \fBSSL_CIPHER_description()\fR return the corresponding +value in a NUL\-terminated string for a specific cipher or "(NONE)" +if the cipher is not found. +.PP +\&\fBSSL_CIPHER_get_bits()\fR returns a positive integer representing the number of +secret bits or 0 if an error occurred. +.PP +\&\fBSSL_CIPHER_get_cipher_nid()\fR, \fBSSL_CIPHER_get_digest_nid()\fR, +\&\fBSSL_CIPHER_get_kx_nid()\fR and \fBSSL_CIPHER_get_auth_nid()\fR return the NID value or +\&\fBNID_undef\fR if an error occurred. +.PP +\&\fBSSL_CIPHER_get_handshake_digest()\fR returns a valid \fBEVP_MD\fR structure or NULL +if an error occurred. +.PP +\&\fBSSL_CIPHER_is_aead()\fR returns 1 if the cipher is AEAD or 0 otherwise. +.PP +\&\fBSSL_CIPHER_find()\fR returns a valid \fBSSL_CIPHER\fR structure or NULL if an error +occurred. +.PP +\&\fBSSL_CIPHER_get_id()\fR returns a 4\-byte integer representing the OpenSSL\-specific ID. +.PP +\&\fBSSL_CIPHER_get_protocol_id()\fR returns a 2\-byte integer representing the TLS +protocol\-specific ID. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_current_cipher\fR\|(3), +\&\fBSSL_get_ciphers\fR\|(3), \fBopenssl\-ciphers\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CIPHER_get_version()\fR function was updated to always return the +correct protocol string in OpenSSL 1.1.0. +.PP +The \fBSSL_CIPHER_description()\fR function was changed to return \fBNULL\fR on error, +rather than a fixed string, in OpenSSL 1.1.0. +.PP +The \fBSSL_CIPHER_get_handshake_digest()\fR function was added in OpenSSL 1.1.1. +.PP +The \fBSSL_CIPHER_standard_name()\fR function was globally available in OpenSSL 1.1.1. + Before OpenSSL 1.1.1, tracing (\fBenable\-ssl\-trace\fR argument to Configure) was +required to enable this function. +.PP +The \fBOPENSSL_cipher_name()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_COMP_add_compression_method.3 b/static/netbsd/man3/SSL_COMP_add_compression_method.3 new file mode 100644 index 00000000..c8eddd86 --- /dev/null +++ b/static/netbsd/man3/SSL_COMP_add_compression_method.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: SSL_COMP_add_compression_method.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_COMP_add_compression_method 3" +.TH SSL_COMP_add_compression_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_COMP_add_compression_method, SSL_COMP_get_compression_methods, +SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods +\&\- handle SSL/TLS integrated compression methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); +\& STACK_OF(SSL_COMP) *SSL_COMP_get_compression_methods(void); +\& const char *SSL_COMP_get0_name(const SSL_COMP *comp); +\& int SSL_COMP_get_id(const SSL_COMP *comp); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void SSL_COMP_free_compression_methods(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_COMP_add_compression_method()\fR adds the compression method \fBcm\fR with +the identifier \fBid\fR to the list of available compression methods. This +list is globally maintained for all SSL operations within this application. +It cannot be set for specific SSL_CTX or SSL objects. +.PP +\&\fBSSL_COMP_get_compression_methods()\fR returns a stack of all of the available +compression methods or NULL on error. +.PP +\&\fBSSL_COMP_get0_name()\fR returns the name of the compression method \fBcomp\fR. +.PP +\&\fBSSL_COMP_get_id()\fR returns the id of the compression method \fBcomp\fR. +.PP +\&\fBSSL_COMP_free_compression_methods()\fR releases any resources acquired to +maintain the internal table of compression methods. +.SH NOTES +.IX Header "NOTES" +The TLS standard (or SSLv3) allows the integration of compression methods +into the communication. The TLS RFC does however not specify compression +methods or their corresponding identifiers, so there is currently no compatible +way to integrate compression with unknown peers. It is therefore currently not +recommended to integrate compression into applications. Applications for +non\-public use may agree on certain compression methods. Using different +compression methods with the same identifier will lead to connection failure. +.PP +An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) +will unconditionally send the list of all compression methods enabled with +\&\fBSSL_COMP_add_compression_method()\fR to the server during the handshake. +Unlike the mechanisms to set a cipher list, there is no method available to +restrict the list of compression method on a per connection basis. +.PP +An OpenSSL server will match the identifiers listed by a client against +its own compression methods and will unconditionally activate compression +when a matching identifier is found. There is no way to restrict the list +of compression methods supported on a per connection basis. +.PP +If enabled during compilation, the OpenSSL library will have the +following compression methods available: +.IP \fBCOMP_zlib()\fR 4 +.IX Item "COMP_zlib()" +.PD 0 +.IP \fBCOMP_brotli()\fR 4 +.IX Item "COMP_brotli()" +.IP \fBCOMP_brotli_oneshot()\fR 4 +.IX Item "COMP_brotli_oneshot()" +.IP \fBCOMP_zstd()\fR 4 +.IX Item "COMP_zstd()" +.IP \fBCOMP_zstd_oneshot()\fR 4 +.IX Item "COMP_zstd_oneshot()" +.PD +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_COMP_add_compression_method()\fR may return the following values: +.IP 0 4 +The operation succeeded. +.IP 1 4 +.IX Item "1" +The operation failed. Check the error queue to find out the reason. +.PP +\&\fBSSL_COMP_get_compression_methods()\fR returns the stack of compressions methods or +NULL on error. +.PP +\&\fBSSL_COMP_get0_name()\fR returns the name of the compression method or NULL on error. +.PP +\&\fBSSL_COMP_get_id()\fR returns the name of the compression method or \-1 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_COMP_free_compression_methods()\fR function was deprecated in OpenSSL 1.1.0. +The \fBSSL_COMP_get0_name()\fR and \fBSSL_comp_get_id()\fR functions were added in OpenSSL 1.1.0d. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_CTX_new.3 b/static/netbsd/man3/SSL_CONF_CTX_new.3 new file mode 100644 index 00000000..8e83579d --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_CTX_new.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: SSL_CONF_CTX_new.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_CTX_new 3" +.TH SSL_CONF_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_CTX_new, SSL_CONF_CTX_free \- SSL configuration allocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_CONF_CTX *SSL_CONF_CTX_new(void); +\& void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBSSL_CONF_CTX_new()\fR allocates and initialises an \fBSSL_CONF_CTX\fR +structure for use with the SSL_CONF functions. +.PP +The function \fBSSL_CONF_CTX_free()\fR frees up the context \fBcctx\fR. +If \fBcctx\fR is NULL nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_CTX_new()\fR returns either the newly allocated \fBSSL_CONF_CTX\fR structure +or \fBNULL\fR if an error occurs. +.PP +\&\fBSSL_CONF_CTX_free()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_set_flags\fR\|(3), +\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), +\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), +\&\fBSSL_CONF_cmd\fR\|(3), +\&\fBSSL_CONF_cmd_argv\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_CTX_set1_prefix.3 b/static/netbsd/man3/SSL_CONF_CTX_set1_prefix.3 new file mode 100644 index 00000000..564f1cfa --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_CTX_set1_prefix.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: SSL_CONF_CTX_set1_prefix.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_CTX_set1_prefix 3" +.TH SSL_CONF_CTX_set1_prefix 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_CTX_set1_prefix \- Set configuration context command prefix +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBSSL_CONF_CTX_set1_prefix()\fR sets the command prefix of \fBcctx\fR +to \fBprefix\fR. If \fBprefix\fR is \fBNULL\fR it is restored to the default value. +.SH NOTES +.IX Header "NOTES" +Command prefixes alter the commands recognised by subsequent \fBSSL_CONF_cmd()\fR +calls. For example for files, if the prefix "SSL" is set then command names +such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol" +and "Options". Similarly for command lines if the prefix is "\-\-ssl\-" then +"\-\-ssl\-no_tls1_2" is recognised instead of "\-no_tls1_2". +.PP +If the \fBSSL_CONF_FLAG_CMDLINE\fR flag is set then prefix checks are case +sensitive and "\-" is the default. In the unlikely even an application +explicitly wants to set no prefix it must be explicitly set to "". +.PP +If the \fBSSL_CONF_FLAG_FILE\fR flag is set then prefix checks are case +insensitive and no prefix is the default. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_CTX_set1_prefix()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_new\fR\|(3), +\&\fBSSL_CONF_CTX_set_flags\fR\|(3), +\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), +\&\fBSSL_CONF_cmd\fR\|(3), +\&\fBSSL_CONF_cmd_argv\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_CTX_set_flags.3 b/static/netbsd/man3/SSL_CONF_CTX_set_flags.3 new file mode 100644 index 00000000..20af74e5 --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_CTX_set_flags.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: SSL_CONF_CTX_set_flags.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_CTX_set_flags 3" +.TH SSL_CONF_CTX_set_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags \- Set or clear SSL configuration context flags +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags); +\& unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBSSL_CONF_CTX_set_flags()\fR sets \fBflags\fR in the context \fBcctx\fR. +.PP +The function \fBSSL_CONF_CTX_clear_flags()\fR clears \fBflags\fR in the context \fBcctx\fR. +.SH NOTES +.IX Header "NOTES" +The flags set affect how subsequent calls to \fBSSL_CONF_cmd()\fR or +\&\fBSSL_CONF_argv()\fR behave. +.PP +Currently the following \fBflags\fR values are recognised: +.IP "SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE" 4 +.IX Item "SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE" +recognise options intended for command line or configuration file use. At +least one of these flags must be set. +.IP "SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER" 4 +.IX Item "SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER" +recognise options intended for use in SSL/TLS clients or servers. One or +both of these flags must be set. +.IP SSL_CONF_FLAG_CERTIFICATE 4 +.IX Item "SSL_CONF_FLAG_CERTIFICATE" +recognise certificate and private key options. +.IP SSL_CONF_FLAG_REQUIRE_PRIVATE 4 +.IX Item "SSL_CONF_FLAG_REQUIRE_PRIVATE" +If this option is set then if a private key is not specified for a certificate +it will attempt to load a private key from the certificate file when +\&\fBSSL_CONF_CTX_finish()\fR is called. If a key cannot be loaded from the certificate +file an error occurs. +.IP SSL_CONF_FLAG_SHOW_ERRORS 4 +.IX Item "SSL_CONF_FLAG_SHOW_ERRORS" +indicate errors relating to unrecognised options or missing arguments in +the error queue. If this option isn\*(Aqt set such errors are only reflected +in the return values of \fBSSL_CONF_set_cmd()\fR or \fBSSL_CONF_set_argv()\fR +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_CTX_set_flags()\fR and \fBSSL_CONF_CTX_clear_flags()\fR returns the new flags +value after setting or clearing flags. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_new\fR\|(3), +\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), +\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), +\&\fBSSL_CONF_cmd\fR\|(3), +\&\fBSSL_CONF_cmd_argv\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_CTX_set_ssl_ctx.3 b/static/netbsd/man3/SSL_CONF_CTX_set_ssl_ctx.3 new file mode 100644 index 00000000..b0490afd --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_CTX_set_ssl_ctx.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: SSL_CONF_CTX_set_ssl_ctx.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_CTX_set_ssl_ctx 3" +.TH SSL_CONF_CTX_set_ssl_ctx 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_CTX_finish, +SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl \- set context to configure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx); +\& void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl); +\& int SSL_CONF_CTX_finish(SSL_CONF_CTX *cctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CONF_CTX_set_ssl_ctx()\fR sets the context associated with \fBcctx\fR to the +\&\fBSSL_CTX\fR structure \fBctx\fR. Any previous \fBSSL\fR or \fBSSL_CTX\fR associated with +\&\fBcctx\fR is cleared. Subsequent calls to \fBSSL_CONF_cmd()\fR will be sent to +\&\fBctx\fR. +.PP +\&\fBSSL_CONF_CTX_set_ssl()\fR sets the context associated with \fBcctx\fR to the +\&\fBSSL\fR structure \fBssl\fR. Any previous \fBSSL\fR or \fBSSL_CTX\fR associated with +\&\fBcctx\fR is cleared. Subsequent calls to \fBSSL_CONF_cmd()\fR will be sent to +\&\fBssl\fR. +.PP +The function \fBSSL_CONF_CTX_finish()\fR must be called after all configuration +operations have been completed. It is used to finalise any operations +or to process defaults. +.SH NOTES +.IX Header "NOTES" +The context need not be set or it can be set to \fBNULL\fR in which case only +syntax checking of commands is performed, where possible. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_CTX_set_ssl_ctx()\fR and \fBSSL_CTX_set_ssl()\fR do not return a value. +.PP +\&\fBSSL_CONF_CTX_finish()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_new\fR\|(3), +\&\fBSSL_CONF_CTX_set_flags\fR\|(3), +\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), +\&\fBSSL_CONF_cmd\fR\|(3), +\&\fBSSL_CONF_cmd_argv\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_cmd.3 b/static/netbsd/man3/SSL_CONF_cmd.3 new file mode 100644 index 00000000..26d97643 --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_cmd.3 @@ -0,0 +1,898 @@ +.\" $NetBSD: SSL_CONF_cmd.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_cmd 3" +.TH SSL_CONF_cmd 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_cmd_value_type, +SSL_CONF_cmd \- send configuration command +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CONF_cmd(SSL_CONF_CTX *ctx, const char *option, const char *value); +\& int SSL_CONF_cmd_value_type(SSL_CONF_CTX *ctx, const char *option); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBSSL_CONF_cmd()\fR performs configuration operation \fBoption\fR with +optional parameter \fBvalue\fR on \fBctx\fR. Its purpose is to simplify application +configuration of \fBSSL_CTX\fR or \fBSSL\fR structures by providing a common +framework for command line options or configuration files. +.PP +\&\fBSSL_CONF_cmd_value_type()\fR returns the type of value that \fBoption\fR refers to. +.SH "SUPPORTED COMMAND LINE COMMANDS" +.IX Header "SUPPORTED COMMAND LINE COMMANDS" +Currently supported \fBoption\fR names for command lines (i.e. when the +flag \fBSSL_CONF_FLAG_CMDLINE\fR is set) are listed below. Note: all \fBoption\fR +names are case sensitive. Unless otherwise stated commands can be used by +both clients and servers and the \fBvalue\fR parameter is not used. The default +prefix for command line commands is \fB\-\fR and that is reflected below. +.IP \fB\-bugs\fR 4 +.IX Item "-bugs" +Various bug workarounds are set, same as setting \fBSSL_OP_ALL\fR. +.IP \fB\-no_comp\fR 4 +.IX Item "-no_comp" +Disables support for SSL/TLS compression, same as setting +\&\fBSSL_OP_NO_COMPRESSION\fR. +As of OpenSSL 1.1.0, compression is off by default. +.IP \fB\-comp\fR 4 +.IX Item "-comp" +Enables support for SSL/TLS compression, same as clearing +\&\fBSSL_OP_NO_COMPRESSION\fR. +This command was introduced in OpenSSL 1.1.0. +As of OpenSSL 1.1.0, compression is off by default. TLS compression can only be +used in security level 1 or lower. From OpenSSL 3.2.0 and above the default +security level is 2, so this option will have no effect without also changing +the security level. See \fBSSL_CTX_set_security_level\fR\|(3). +.IP \fB\-no_ticket\fR 4 +.IX Item "-no_ticket" +Disables support for session tickets, same as setting \fBSSL_OP_NO_TICKET\fR. +.IP \fB\-serverpref\fR 4 +.IX Item "-serverpref" +Use server and not client preference order when determining which cipher suite, +signature algorithm or elliptic curve to use for an incoming connection. +Equivalent to \fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR. Only used by servers. +.IP \fB\-client_renegotiation\fR 4 +.IX Item "-client_renegotiation" +Allows servers to accept client\-initiated renegotiation. Equivalent to +setting \fBSSL_OP_ALLOW_CLIENT_RENEGOTIATION\fR. +Only used by servers. +.IP \fB\-legacy_renegotiation\fR 4 +.IX Item "-legacy_renegotiation" +Permits the use of unsafe legacy renegotiation. Equivalent to setting +\&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR. +.IP \fB\-no_renegotiation\fR 4 +.IX Item "-no_renegotiation" +Disables all attempts at renegotiation in (D)TLSv1.2 and earlier, same as setting +\&\fBSSL_OP_NO_RENEGOTIATION\fR. +.IP \fB\-no_resumption_on_reneg\fR 4 +.IX Item "-no_resumption_on_reneg" +Sets \fBSSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\fR. Only used by servers. +.IP "\fB\-legacy_server_connect\fR, \fB\-no_legacy_server_connect\fR" 4 +.IX Item "-legacy_server_connect, -no_legacy_server_connect" +Permits or prohibits the use of unsafe legacy renegotiation for OpenSSL +clients only. Equivalent to setting or clearing \fBSSL_OP_LEGACY_SERVER_CONNECT\fR. +.IP \fB\-prioritize_chacha\fR 4 +.IX Item "-prioritize_chacha" +Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of +its preference list. This usually indicates a client without AES hardware +acceleration (e.g. mobile) is in use. Equivalent to \fBSSL_OP_PRIORITIZE_CHACHA\fR. +Only used by servers. Requires \fB\-serverpref\fR. +.IP \fB\-allow_no_dhe_kex\fR 4 +.IX Item "-allow_no_dhe_kex" +In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means +that there will be no forward secrecy for the resumed session. +.IP \fB\-prefer_no_dhe_kex\fR 4 +.IX Item "-prefer_no_dhe_kex" +In TLSv1.3, on resumption let the server prefer a non\-(ec)dhe based key +exchange mode over an (ec)dhe based one. Requires \fB\-allow_no_dhe_kex\fR. +Equivalent to \fBSSL_OP_PREFER_NO_DHE_KEX\fR. Only used by servers. +.IP \fB\-strict\fR 4 +.IX Item "-strict" +Enables strict mode protocol handling. Equivalent to setting +\&\fBSSL_CERT_FLAG_TLS_STRICT\fR. +.IP "\fB\-sigalgs\fR \fIalgs\fR" 4 +.IX Item "-sigalgs algs" +This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. +For clients this value is used directly for the supported signature +algorithms extension. For servers it is used to determine which signature +algorithms to support. +.Sp +The \fBalgs\fR argument should be a colon separated list of signature +algorithms in order of decreasing preference of the form \fBalgorithm+hash\fR +or \fBsignature_scheme\fR. For the default providers shipped with OpenSSL, +\&\fBalgorithm\fR is one of \fBRSA\fR, \fBDSA\fR or \fBECDSA\fR and +\&\fBhash\fR is a supported algorithm OID short name such as \fBSHA1\fR, \fBSHA224\fR, +\&\fBSHA256\fR, \fBSHA384\fR or \fBSHA512\fR. +\&\fBsignature_scheme\fR is one of the signature schemes defined +in TLSv1.3, specified using the IETF name, e.g., \fBecdsa_secp256r1_sha256\fR, +\&\fBed25519\fR, or \fBrsa_pss_pss_sha256\fR. Additional providers may make available +further algorithms via the TLS\-SIGALG capability. +Signature scheme names and public key algorithm names (but not the hash names) +in the \fBalgorithm+hash\fR form are case\-insensitive. +See \fBprovider\-base\fR\|(7). +.Sp +If this option is not set then all signature algorithms supported by all +activated providers are permissible. +.Sp +Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by +using \fBRSA\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR +identifiers) are ignored in TLSv1.3 and will not be negotiated. +.IP "\fB\-client_sigalgs\fR \fIalgs\fR" 4 +.IX Item "-client_sigalgs algs" +This sets the supported signature algorithms associated with client +authentication for TLSv1.2 and TLSv1.3. For servers the \fBalgs\fR is used +in the \fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message. +For clients it is used to determine which signature algorithm to use with +the client certificate. If a server does not request a certificate this +option has no effect. +.Sp +The syntax of \fBalgs\fR is identical to \fB\-sigalgs\fR. If not set, then the +value set for \fB\-sigalgs\fR will be used instead. +.IP "\fB\-groups\fR \fIgroups\fR" 4 +.IX Item "-groups groups" +This sets the supported groups. For clients, the groups are sent using +the supported groups extension. For servers, it is used to determine which +group to use. This setting affects groups used for signatures (in TLSv1.2 +and earlier) and key exchange. +.Sp +In its simplest form the \fIgroups\fR argument is a colon separated list of +groups. The preferred names are those listed in the IANA +TLS Supported Groups +registry. +.Sp +For some groups, OpenSSL supports additional aliases. +Such an alias could be a \fBNIST\fR name (e.g. \fBP\-256\fR), an OpenSSL OID name +(e.g. \fBprime256v1\fR), or some other commonly used name. +Group names are case\-insensitive in OpenSSL 3.5 and later. +The list should be in order of preference with the most preferred group first. +.Sp +The first group listed will also be used for the \fBkey_share\fR sent by a client +in a TLSv1.3 \fBClientHello\fR. +.Sp +The commands below list the IANA names for TLS 1.2 and TLS 1.3, +respectively: +.Sp +.Vb 2 +\& $ openssl list \-tls1_2 \-tls\-groups +\& $ openssl list \-tls1_3 \-tls\-groups +.Ve +.Sp +The recommended groups for TLS 1.3 are presently documented in the default +TLS group list in the OpenSSL code base. Starting with OpenSSL 3.5, the +hybrid algorithm \fBX25519MLKEM768\fR is first in this default list. +It mitigates against threats from future quantum computers while +still providing state\-of\-the\-art classical key exchange protection. +.Sp +Further details regarding post\-quantum algorithm considerations are documented +in the HISTORY section below. +.Sp +An enriched alternative syntax, that enables clients to send multiple keyshares +and allows servers to prioritise some groups over others, is described in +\&\fBSSL_CTX_set1_groups_list\fR\|(3). +Since TLS 1.2 has neither keyshares nor a hello retry mechanism, with TLS 1.2 +the enriched syntax is ultimately equivalent to just a simple ordered list of +groups, as with the simple form above. +.IP "\fB\-curves\fR \fIgroups\fR" 4 +.IX Item "-curves groups" +This is a synonym for the \fB\-groups\fR command. +.IP "\fB\-named_curve\fR \fIcurve\fR" 4 +.IX Item "-named_curve curve" +This sets the temporary curve used for ephemeral ECDH modes. +This is only applicable in TLS 1.0 and 1.1, and should not be used with later +protocol versions. +.Sp +The \fIcurve\fR argument is a curve name or the special value \fBauto\fR which +picks an appropriate curve based on client and server preferences. The +curve can be either the \fBNIST\fR name (e.g. \fBP\-256\fR) or an OpenSSL OID name +(e.g. \fBprime256v1\fR). +Even with TLS 1.0 and 1.1, the default value of \f(CW\*(C`auto\*(C'\fR is strongly recommended +over choosing a specific curve. +Curve names are case\-insensitive in OpenSSL 3.5 and later. +.IP \fB\-tx_cert_comp\fR 4 +.IX Item "-tx_cert_comp" +Enables support for sending TLSv1.3 compressed certificates. +.IP \fB\-no_tx_cert_comp\fR 4 +.IX Item "-no_tx_cert_comp" +Disables support for sending TLSv1.3 compressed certificates. +.IP \fB\-rx_cert_comp\fR 4 +.IX Item "-rx_cert_comp" +Enables support for receiving TLSv1.3 compressed certificates. +.IP \fB\-no_rx_cert_comp\fR 4 +.IX Item "-no_rx_cert_comp" +Disables support for receiving TLSv1.3 compressed certificates. +.IP \fB\-comp\fR 4 +.IX Item "-comp" +.PD 0 +.IP "\fB\-cipher\fR \fIciphers\fR" 4 +.IX Item "-cipher ciphers" +.PD +Sets the TLSv1.2 and below ciphersuite list to \fBciphers\fR. This list will be +combined with any configured TLSv1.3 ciphersuites. Note: syntax checking +of \fBciphers\fR is currently not performed unless a \fBSSL\fR or \fBSSL_CTX\fR +structure is associated with \fBctx\fR. +.IP "\fB\-ciphersuites\fR \fI1.3ciphers\fR" 4 +.IX Item "-ciphersuites 1.3ciphers" +Sets the available ciphersuites for TLSv1.3 to value. This is a +colon\-separated list of TLSv1.3 ciphersuite names in order of preference. This +list will be combined any configured TLSv1.2 and below ciphersuites. +See \fBopenssl\-ciphers\fR\|(1) for more information. +.IP "\fB\-min_protocol\fR \fIminprot\fR, \fB\-max_protocol\fR \fImaxprot\fR" 4 +.IX Item "-min_protocol minprot, -max_protocol maxprot" +Sets the minimum and maximum supported protocol. +Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, +\&\fBTLSv1.2\fR, \fBTLSv1.3\fR for TLS; \fBDTLSv1\fR, \fBDTLSv1.2\fR for DTLS, and \fBNone\fR +for no limit. +If either the lower or upper bound is not specified then only the other bound +applies, if specified. +If your application supports both TLS and DTLS you can specify any of these +options twice, once with a bound for TLS and again with an appropriate bound +for DTLS. +To restrict the supported protocol versions use these commands rather than the +deprecated alternative commands below. +.IP "\fB\-record_padding\fR \fIpadding\fR" 4 +.IX Item "-record_padding padding" +Controls use of TLSv1.3 record layer padding. \fBpadding\fR is a string of the +form "number[,number]" where the (required) first number is the padding block +size (in octets) for application data, and the optional second number is the +padding block size for handshake and alert messages. If the optional second +number is omitted, the same padding will be applied to all messages. +.Sp +Padding attempts to pad TLSv1.3 records so that they are a multiple of the set +length on send. A value of 0 or 1 turns off padding as relevant. Otherwise, the +values must be >1 or <=16384. +.IP \fB\-debug_broken_protocol\fR 4 +.IX Item "-debug_broken_protocol" +Ignored. +.IP \fB\-no_middlebox\fR 4 +.IX Item "-no_middlebox" +Turn off "middlebox compatibility", as described below. +.SS "Additional Options" +.IX Subsection "Additional Options" +The following options are accepted by \fBSSL_CONF_cmd()\fR, but are not +processed by the OpenSSL commands. +.IP "\fB\-cert\fR \fIfile\fR" 4 +.IX Item "-cert file" +Attempts to use \fBfile\fR as the certificate for the appropriate context. It +currently uses \fBSSL_CTX_use_certificate_chain_file()\fR if an \fBSSL_CTX\fR +structure is set or \fBSSL_use_certificate_file()\fR with filetype PEM if an +\&\fBSSL\fR structure is set. This option is only supported if certificate +operations are permitted. +.IP "\fB\-key\fR \fIfile\fR" 4 +.IX Item "-key file" +Attempts to use \fBfile\fR as the private key for the appropriate context. This +option is only supported if certificate operations are permitted. Note: +if no \fB\-key\fR option is set then a private key is not loaded unless the +flag \fBSSL_CONF_FLAG_REQUIRE_PRIVATE\fR is set. +.IP "\fB\-dhparam\fR \fIfile\fR" 4 +.IX Item "-dhparam file" +Attempts to use \fBfile\fR as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. +.IP "\fB\-no_ssl3\fR, \fB\-no_tls1\fR, \fB\-no_tls1_1\fR, \fB\-no_tls1_2\fR, \fB\-no_tls1_3\fR" 4 +.IX Item "-no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2, -no_tls1_3" +Disables protocol support for SSLv3, TLSv1.0, TLSv1.1, TLSv1.2 or TLSv1.3 by +setting the corresponding options \fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, +\&\fBSSL_OP_NO_TLSv1_1\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR +respectively. These options are deprecated, use \fB\-min_protocol\fR and +\&\fB\-max_protocol\fR instead. +.IP "\fB\-anti_replay\fR, \fB\-no_anti_replay\fR" 4 +.IX Item "-anti_replay, -no_anti_replay" +Switches replay protection, on or off respectively. With replay protection on, +OpenSSL will automatically detect if a session ticket has been used more than +once, TLSv1.3 has been negotiated, and early data is enabled on the server. A +full handshake is forced if a session ticket is used a second or subsequent +time. Anti\-Replay is on by default unless overridden by a configuration file and +is only used by servers. Anti\-replay measures are required for compliance with +the TLSv1.3 specification. Some applications may be able to mitigate the replay +risks in other ways and in such cases the built\-in OpenSSL functionality is not +required. Switching off anti\-replay is equivalent to \fBSSL_OP_NO_ANTI_REPLAY\fR. +.SH "SUPPORTED CONFIGURATION FILE COMMANDS" +.IX Header "SUPPORTED CONFIGURATION FILE COMMANDS" +Currently supported \fBoption\fR names for configuration files (i.e., when the +flag \fBSSL_CONF_FLAG_FILE\fR is set) are listed below. All configuration file +\&\fBoption\fR names are case insensitive so \fBsignaturealgorithms\fR is recognised +as well as \fBSignatureAlgorithms\fR. Unless otherwise stated the \fBvalue\fR names +are also case insensitive. +.PP +Note: the command prefix (if set) alters the recognised \fBoption\fR values. +.IP \fBCipherString\fR 4 +.IX Item "CipherString" +Sets the ciphersuite list for TLSv1.2 and below to \fBvalue\fR. This list will be +combined with any configured TLSv1.3 ciphersuites. Note: syntax +checking of \fBvalue\fR is currently not performed unless an \fBSSL\fR or \fBSSL_CTX\fR +structure is associated with \fBctx\fR. +.IP \fBCiphersuites\fR 4 +.IX Item "Ciphersuites" +Sets the available ciphersuites for TLSv1.3 to \fBvalue\fR. This is a +colon\-separated list of TLSv1.3 ciphersuite names in order of preference. This +list will be combined any configured TLSv1.2 and below ciphersuites. +See \fBopenssl\-ciphers\fR\|(1) for more information. +.IP \fBCertificate\fR 4 +.IX Item "Certificate" +Attempts to use the file \fBvalue\fR as the certificate for the appropriate +context. It currently uses \fBSSL_CTX_use_certificate_chain_file()\fR if an \fBSSL_CTX\fR +structure is set or \fBSSL_use_certificate_file()\fR with filetype PEM if an \fBSSL\fR +structure is set. This option is only supported if certificate operations +are permitted. +.IP \fBPrivateKey\fR 4 +.IX Item "PrivateKey" +Attempts to use the file \fBvalue\fR as the private key for the appropriate +context. This option is only supported if certificate operations +are permitted. Note: if no \fBPrivateKey\fR option is set then a private key is +not loaded unless the \fBSSL_CONF_FLAG_REQUIRE_PRIVATE\fR is set. +.IP "\fBChainCAFile\fR, \fBChainCAPath\fR, \fBVerifyCAFile\fR, \fBVerifyCAPath\fR" 4 +.IX Item "ChainCAFile, ChainCAPath, VerifyCAFile, VerifyCAPath" +These options indicate a file or directory used for building certificate +chains or verifying certificate chains. These options are only supported +if certificate operations are permitted. +.IP \fBRequestCAFile\fR 4 +.IX Item "RequestCAFile" +This option indicates a file containing a set of certificates in PEM form. +The subject names of the certificates are sent to the peer in the +\&\fBcertificate_authorities\fR extension for TLS 1.3 (in ClientHello or +CertificateRequest) or in a certificate request for previous versions or +TLS. +.IP \fBServerInfoFile\fR 4 +.IX Item "ServerInfoFile" +Attempts to use the file \fBvalue\fR in the "serverinfo" extension using the +function SSL_CTX_use_serverinfo_file. +.IP \fBDHParameters\fR 4 +.IX Item "DHParameters" +Attempts to use the file \fBvalue\fR as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. +.IP \fBRecordPadding\fR 4 +.IX Item "RecordPadding" +Controls use of TLSv1.3 record layer padding. \fBvalue\fR is a string of the form +"number[,number]" where the (required) first number is the padding block size +(in octets) for application data, and the optional second number is the padding +block size for handshake and alert messages. If the optional second number is +omitted, the same padding will be applied to all messages. +.Sp +Padding attempts to pad TLSv1.3 records so that they are a multiple of the set +length on send. A value of 0 or 1 turns off padding as relevant. Otherwise, the +values must be >1 or <=16384. +.Sp +Note that, for QUIC objects, padding is always performed at the +packet level, and so cannot be done at the record level. Given that, when the +config file is created, there is no knowledge of what kind of SSL objects are +being created, this option is silently ignored for QUIC objects. +.IP \fBSignatureAlgorithms\fR 4 +.IX Item "SignatureAlgorithms" +This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. +For clients this +value is used directly for the supported signature algorithms extension. For +servers it is used to determine which signature algorithms to support. +.Sp +The \fBvalue\fR argument should be a colon separated list of signature algorithms +in order of decreasing preference of the form \fBalgorithm+hash\fR or +\&\fBsignature_scheme\fR. For the default providers shipped with OpenSSL, +\&\fBalgorithm\fR is one of \fBRSA\fR, \fBDSA\fR or \fBECDSA\fR and \fBhash\fR is a supported +algorithm OID short name such as \fBSHA1\fR, \fBSHA224\fR, \fBSHA256\fR, \fBSHA384\fR +or \fBSHA512\fR. +\&\fBsignature_scheme\fR is one of the signature schemes defined in TLSv1.3, +specified using the IANA name, e.g., \fBecdsa_secp256r1_sha256\fR, \fBed25519\fR, +or \fBrsa_pss_pss_sha256\fR. +Signature scheme names and public key algorithm names (but not the hash names) +in the \fBalgorithm+hash\fR form are case\-insensitive. +Additional providers may make available further signature schemes via the +TLS_SIGALG capability. See "CAPABILITIES" in \fBprovider\-base\fR\|(7). +.Sp +If this option is not set then all signature algorithms supported by all +activated providers are permissible. +.Sp +Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by +using \fBRSA\fR as the \fBalgorithm\fR or by using one of the \fBrsa_pkcs1_*\fR +identifiers) are ignored in TLSv1.3 and will not be negotiated. +.IP \fBClientSignatureAlgorithms\fR 4 +.IX Item "ClientSignatureAlgorithms" +This sets the supported signature algorithms associated with client +authentication for TLSv1.2 and TLSv1.3. +For servers the value is used in the +\&\fBsignature_algorithms\fR field of a \fBCertificateRequest\fR message. +For clients it is +used to determine which signature algorithm to use with the client certificate. +If a server does not request a certificate this option has no effect. +.Sp +The syntax of \fBvalue\fR is identical to \fBSignatureAlgorithms\fR. If not set then +the value set for \fBSignatureAlgorithms\fR will be used instead. +.IP \fBGroups\fR 4 +.IX Item "Groups" +This sets the supported groups. For clients, the groups are +sent using the supported groups extension. For servers, it is used +to determine which group to use. This setting affects groups used for +signatures (in TLSv1.2 and earlier) and key exchange. The first group listed +will also be used for the \fBkey_share\fR sent by a client in a TLSv1.3 +\&\fBClientHello\fR. +.Sp +The \fBgroups\fR argument is a colon separated list of groups. The preferred +names are those listed in the IANA +TLS Supported Groups +registry. +For some groups, OpenSSL supports additional aliases. +Such an alias could be a \fBNIST\fR name (e.g. \fBP\-256\fR), an OpenSSL OID name +(e.g. \fBprime256v1\fR), or some other commonly used name. +Group names are case\-insensitive in OpenSSL 3.5 and later. +The list should be in order of preference with the most preferred group first. +.Sp +The commands below list the available groups for TLS 1.2 and TLS 1.3, +respectively: +.Sp +.Vb 2 +\& $ openssl list \-tls1_2 \-tls\-groups +\& $ openssl list \-tls1_3 \-tls\-groups +.Ve +.Sp +An enriched alternative syntax, that enables clients to send multiple keyshares +and allows servers to prioritise some groups over others, is described in +\&\fBSSL_CTX_set1_groups_list\fR\|(3). +Since TLS 1.2 has neither keyshares nor a hello retry mechanism, with TLS 1.2 +the enriched syntax is ultimately equivalent to just a simple ordered list of +groups, as with the simple form above. +.IP \fBCurves\fR 4 +.IX Item "Curves" +This is a synonym for the "Groups" command. +.IP \fBMinProtocol\fR 4 +.IX Item "MinProtocol" +This sets the minimum supported SSL, TLS or DTLS version. +.Sp +Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, +\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. +The SSL and TLS bounds apply only to TLS\-based contexts, while the DTLS bounds +apply only to DTLS\-based contexts. +The command can be repeated with one instance setting a TLS bound, and the +other setting a DTLS bound. +The value \fBNone\fR applies to both types of contexts and disables the limits. +.IP \fBMaxProtocol\fR 4 +.IX Item "MaxProtocol" +This sets the maximum supported SSL, TLS or DTLS version. +.Sp +Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, +\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. +The SSL and TLS bounds apply only to TLS\-based contexts, while the DTLS bounds +apply only to DTLS\-based contexts. +The command can be repeated with one instance setting a TLS bound, and the +other setting a DTLS bound. +The value \fBNone\fR applies to both types of contexts and disables the limits. +.IP \fBProtocol\fR 4 +.IX Item "Protocol" +This can be used to enable or disable certain versions of the SSL, +TLS or DTLS protocol. +.Sp +The \fBvalue\fR argument is a comma separated list of supported protocols +to enable or disable. +If a protocol is preceded by \fB\-\fR that version is disabled. +.Sp +All protocol versions are enabled by default. +You need to disable at least one protocol version for this setting have any +effect. +Only enabling some protocol versions does not disable the other protocol +versions. +.Sp +Currently supported protocol values are \fBSSLv3\fR, \fBTLSv1\fR, \fBTLSv1.1\fR, +\&\fBTLSv1.2\fR, \fBTLSv1.3\fR, \fBDTLSv1\fR and \fBDTLSv1.2\fR. +The special value \fBALL\fR refers to all supported versions. +.Sp +This can\*(Aqt enable protocols that are disabled using \fBMinProtocol\fR +or \fBMaxProtocol\fR, but can disable protocols that are still allowed +by them. +.Sp +The \fBProtocol\fR command is fragile and deprecated; do not use it. +Use \fBMinProtocol\fR and \fBMaxProtocol\fR instead. +If you do use \fBProtocol\fR, make sure that the resulting range of enabled +protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make +sure to also leave TLS 1.1 enabled. +.IP \fBOptions\fR 4 +.IX Item "Options" +The \fBvalue\fR argument is a comma separated list of various flags to set. +If a flag string is preceded \fB\-\fR it is disabled. +See the \fBSSL_CTX_set_options\fR\|(3) function for more details of +individual options. +.Sp +Each option is listed below. Where an operation is enabled by default +the \fB\-flag\fR syntax is needed to disable it. +.Sp +\&\fBSessionTicket\fR: session ticket support, enabled by default. Inverse of +\&\fBSSL_OP_NO_TICKET\fR: that is \fB\-SessionTicket\fR is the same as setting +\&\fBSSL_OP_NO_TICKET\fR. +.Sp +\&\fBCompression\fR: SSL/TLS compression support, disabled by default. Inverse +of \fBSSL_OP_NO_COMPRESSION\fR. +.Sp +\&\fBEmptyFragments\fR: use empty fragments as a countermeasure against a +SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It +is set by default. Inverse of \fBSSL_OP_DONT_INSERT_EMPTY_FRAGMENTS\fR. +.Sp +\&\fBBugs\fR: enable various bug workarounds. Same as \fBSSL_OP_ALL\fR. +.Sp +\&\fBDHSingle\fR: enable single use DH keys, set by default. Inverse of +\&\fBSSL_OP_DH_SINGLE\fR. Only used by servers. +.Sp +\&\fBECDHSingle\fR: enable single use ECDH keys, set by default. Inverse of +\&\fBSSL_OP_ECDH_SINGLE\fR. Only used by servers. +.Sp +\&\fBServerPreference\fR: use server and not client preference order when +determining which cipher suite, signature algorithm or elliptic curve +to use for an incoming connection. Equivalent to +\&\fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR. Only used by servers. +.Sp +\&\fBPrioritizeChaCha\fR: prioritizes ChaCha ciphers when the client has a +ChaCha20 cipher at the top of its preference list. This usually indicates +a mobile client is in use. Equivalent to \fBSSL_OP_PRIORITIZE_CHACHA\fR. +Only used by servers. +.Sp +\&\fBNoResumptionOnRenegotiation\fR: set +\&\fBSSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION\fR flag. Only used by servers. +.Sp +\&\fBNoRenegotiation\fR: disables all attempts at renegotiation in TLSv1.2 and +earlier, same as setting \fBSSL_OP_NO_RENEGOTIATION\fR. +.Sp +\&\fBUnsafeLegacyRenegotiation\fR: permits the use of unsafe legacy renegotiation. +Equivalent to \fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR. +.Sp +\&\fBUnsafeLegacyServerConnect\fR: permits the use of unsafe legacy renegotiation +for OpenSSL clients only. Equivalent to \fBSSL_OP_LEGACY_SERVER_CONNECT\fR. +.Sp +\&\fBEncryptThenMac\fR: use encrypt\-then\-mac extension, enabled by +default. Inverse of \fBSSL_OP_NO_ENCRYPT_THEN_MAC\fR: that is, +\&\fB\-EncryptThenMac\fR is the same as setting \fBSSL_OP_NO_ENCRYPT_THEN_MAC\fR. +.Sp +\&\fBAllowNoDHEKEX\fR: In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on +resumption. This means that there will be no forward secrecy for the resumed +session. Equivalent to \fBSSL_OP_ALLOW_NO_DHE_KEX\fR. +.Sp +\&\fBPreferNoDHEKEX\fR: In TLSv1.3, on resumption let the server prefer a +non\-(ec)dhe based key exchange mode over an (ec)dhe based one. Requires +\&\fBAllowNoDHEKEX\fR. Equivalent to \fBSSL_OP_PREFER_NO_DHE_KEX\fR. Only used by +servers. +.Sp +\&\fBMiddleboxCompat\fR: If set then dummy Change Cipher Spec (CCS) messages are sent +in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that +middleboxes that do not understand TLSv1.3 will not drop the connection. This +option is set by default. A future version of OpenSSL may not set this by +default. Equivalent to \fBSSL_OP_ENABLE_MIDDLEBOX_COMPAT\fR. +.Sp +\&\fBAntiReplay\fR: If set then OpenSSL will automatically detect if a session ticket +has been used more than once, TLSv1.3 has been negotiated, and early data is +enabled on the server. A full handshake is forced if a session ticket is used a +second or subsequent time. This option is set by default and is only used by +servers. Anti\-replay measures are required to comply with the TLSv1.3 +specification. Some applications may be able to mitigate the replay risks in +other ways and in such cases the built\-in OpenSSL functionality is not required. +Disabling anti\-replay is equivalent to setting \fBSSL_OP_NO_ANTI_REPLAY\fR. +.Sp +\&\fBExtendedMasterSecret\fR: use extended master secret extension, enabled by +default. Inverse of \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR: that is, +\&\fB\-ExtendedMasterSecret\fR is the same as setting \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR. +.Sp +\&\fBCANames\fR: use CA names extension, enabled by +default. Inverse of \fBSSL_OP_DISABLE_TLSEXT_CA_NAMES\fR: that is, +\&\fB\-CANames\fR is the same as setting \fBSSL_OP_DISABLE_TLSEXT_CA_NAMES\fR. +.Sp +\&\fBKTLS\fR: Enables kernel TLS if support has been compiled in, and it is supported +by the negotiated ciphersuites and extensions. Equivalent to +\&\fBSSL_OP_ENABLE_KTLS\fR. +.Sp +\&\fBStrictCertCheck\fR: Enable strict certificate checking. Equivalent to +setting \fBSSL_CERT_FLAG_TLS_STRICT\fR with \fBSSL_CTX_set_cert_flags()\fR. +.Sp +\&\fBTxCertificateCompression\fR: support sending compressed certificates, enabled by +default. Inverse of \fBSSL_OP_NO_TX_CERTIFICATE_COMPRESSION\fR: that is, +\&\fB\-TxCertificateCompression\fR is the same as setting \fBSSL_OP_NO_TX_CERTIFICATE_COMPRESSION\fR. +.Sp +\&\fBRxCertificateCompression\fR: support receiving compressed certificates, enabled by +default. Inverse of \fBSSL_OP_NO_RX_CERTIFICATE_COMPRESSION\fR: that is, +\&\fB\-RxCertificateCompression\fR is the same as setting \fBSSL_OP_NO_RX_CERTIFICATE_COMPRESSION\fR. +.Sp +\&\fBKTLSTxZerocopySendfile\fR: use the zerocopy TX mode of \fBsendfile()\fR, which gives +a performance boost when used with KTLS hardware offload. Note that invalid TLS +records might be transmitted if the file is changed while being sent. This +option has no effect if \fBKTLS\fR is not enabled. Equivalent to +\&\fBSSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE\fR. This option only applies to Linux. +KTLS sendfile on FreeBSD doesn\*(Aqt offer an option to disable zerocopy and +always runs in this mode. +.Sp +\&\fBIgnoreUnexpectedEOF\fR: Equivalent to \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR. +You should only enable this option if the protocol running over TLS can detect +a truncation attack itself, and that the application is checking for that +truncation attack. +.IP \fBVerifyMode\fR 4 +.IX Item "VerifyMode" +The \fBvalue\fR argument is a comma separated list of flags to set. +.Sp +\&\fBPeer\fR enables peer verification: for clients only. +.Sp +\&\fBRequest\fR requests but does not require a certificate from the client. +Servers only. +.Sp +\&\fBRequire\fR requests and requires a certificate from the client: an error +occurs if the client does not present a certificate. Servers only. +.Sp +\&\fBOnce\fR requests a certificate from a client only on the initial connection: +not when renegotiating. Servers only. +.Sp +\&\fBRequestPostHandshake\fR configures the connection to support requests but does +not require a certificate from the client post\-handshake. A certificate will +not be requested during the initial handshake. The server application must +provide a mechanism to request a certificate post\-handshake. Servers only. +TLSv1.3 only. +.Sp +\&\fBRequiresPostHandshake\fR configures the connection to support requests and +requires a certificate from the client post\-handshake: an error occurs if the +client does not present a certificate. A certificate will not be requested +during the initial handshake. The server application must provide a mechanism +to request a certificate post\-handshake. Servers only. TLSv1.3 only. +.IP "\fBClientCAFile\fR, \fBClientCAPath\fR" 4 +.IX Item "ClientCAFile, ClientCAPath" +A file or directory of certificates in PEM format whose names are used as the +set of acceptable names for client CAs. Servers only. This option is only +supported if certificate operations are permitted. +.SH "SUPPORTED COMMAND TYPES" +.IX Header "SUPPORTED COMMAND TYPES" +The function \fBSSL_CONF_cmd_value_type()\fR currently returns one of the following +types: +.IP \fBSSL_CONF_TYPE_UNKNOWN\fR 4 +.IX Item "SSL_CONF_TYPE_UNKNOWN" +The \fBoption\fR string is unrecognised, this return value can be use to flag +syntax errors. +.IP \fBSSL_CONF_TYPE_STRING\fR 4 +.IX Item "SSL_CONF_TYPE_STRING" +The value is a string without any specific structure. +.IP \fBSSL_CONF_TYPE_FILE\fR 4 +.IX Item "SSL_CONF_TYPE_FILE" +The value is a filename. +.IP \fBSSL_CONF_TYPE_DIR\fR 4 +.IX Item "SSL_CONF_TYPE_DIR" +The value is a directory name. +.IP \fBSSL_CONF_TYPE_NONE\fR 4 +.IX Item "SSL_CONF_TYPE_NONE" +The value string is not used e.g. a command line option which doesn\*(Aqt take an +argument. +.SH NOTES +.IX Header "NOTES" +The order of operations is significant. This can be used to set either defaults +or values which cannot be overridden. For example if an application calls: +.PP +.Vb 2 +\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); +\& SSL_CONF_cmd(ctx, userparam, uservalue); +.Ve +.PP +it will disable SSLv3 support by default but the user can override it. If +however the call sequence is: +.PP +.Vb 2 +\& SSL_CONF_cmd(ctx, userparam, uservalue); +\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); +.Ve +.PP +SSLv3 is \fBalways\fR disabled and attempt to override this by the user are +ignored. +.PP +By checking the return code of \fBSSL_CONF_cmd()\fR it is possible to query if a +given \fBoption\fR is recognised, this is useful if \fBSSL_CONF_cmd()\fR values are +mixed with additional application specific operations. +.PP +For example an application might call \fBSSL_CONF_cmd()\fR and if it returns +\&\-2 (unrecognised command) continue with processing of application specific +commands. +.PP +Applications can also use \fBSSL_CONF_cmd()\fR to process command lines though the +utility function \fBSSL_CONF_cmd_argv()\fR is normally used instead. One way +to do this is to set the prefix to an appropriate value using +\&\fBSSL_CONF_CTX_set1_prefix()\fR, pass the current argument to \fBoption\fR and the +following argument to \fBvalue\fR (which may be NULL). +.PP +In this case if the return value is positive then it is used to skip that +number of arguments as they have been processed by \fBSSL_CONF_cmd()\fR. If \-2 is +returned then \fBoption\fR is not recognised and application specific arguments +can be checked instead. If \-3 is returned a required argument is missing +and an error is indicated. If 0 is returned some other error occurred and +this can be reported back to the user. +.PP +The function \fBSSL_CONF_cmd_value_type()\fR can be used by applications to +check for the existence of a command or to perform additional syntax +checking or translation of the command value. For example if the return +value is \fBSSL_CONF_TYPE_FILE\fR an application could translate a relative +pathname to an absolute pathname. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_cmd()\fR returns 1 if the value of \fBoption\fR is recognised and \fBvalue\fR is +\&\fBNOT\fR used and 2 if both \fBoption\fR and \fBvalue\fR are used. In other words it +returns the number of arguments processed. This is useful when processing +command lines. +.PP +A return value of \-2 means \fBoption\fR is not recognised. +.PP +A return value of \-3 means \fBoption\fR is recognised and the command requires a +value but \fBvalue\fR is NULL. +.PP +A return code of 0 indicates that both \fBoption\fR and \fBvalue\fR are valid but an +error occurred attempting to perform the operation: for example due to an +error in the syntax of \fBvalue\fR in this case the error queue may provide +additional information. +.SH EXAMPLES +.IX Header "EXAMPLES" +Set supported signature algorithms: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); +.Ve +.PP +There are various ways to select the supported protocols. +.PP +This set the minimum protocol version to TLSv1, and so disables SSLv3. +This is the recommended way to disable protocols. +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); +.Ve +.PP +The following also disables SSLv3: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Protocol", "\-SSLv3"); +.Ve +.PP +The following will first enable all protocols, and then disable +SSLv3. +If no protocol versions were disabled before this has the same effect as +"\-SSLv3", but if some versions were disables this will re\-enable them before +disabling SSLv3. +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Protocol", "ALL,\-SSLv3"); +.Ve +.PP +Only enable TLSv1.2: +.PP +.Vb 2 +\& SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); +\& SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); +.Ve +.PP +This also only enables TLSv1.2: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Protocol", "\-ALL,TLSv1.2"); +.Ve +.PP +Disable TLS session tickets: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Options", "\-SessionTicket"); +.Ve +.PP +Enable compression: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Options", "Compression"); +.Ve +.PP +Set supported curves to P\-256, P\-384: +.PP +.Vb 1 +\& SSL_CONF_cmd(ctx, "Curves", "P\-256:P\-384"); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_new\fR\|(3), +\&\fBSSL_CONF_CTX_set_flags\fR\|(3), +\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), +\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), +\&\fBSSL_CONF_cmd_argv\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CONF_cmd()\fR function was added in OpenSSL 1.0.2. +.PP +The \fBSSL_OP_NO_SSL2\fR option doesn\*(Aqt have effect since 1.1.0, but the macro +is retained for backwards compatibility. +.PP +The \fBSSL_CONF_TYPE_NONE\fR was added in OpenSSL 1.1.0. In earlier versions of +OpenSSL passing a command which didn\*(Aqt take an argument would return +\&\fBSSL_CONF_TYPE_UNKNOWN\fR. +.PP +\&\fBMinProtocol\fR and \fBMaxProtocol\fR where added in OpenSSL 1.1.0. +.PP +\&\fBAllowNoDHEKEX\fR and \fBPrioritizeChaCha\fR were added in OpenSSL 1.1.1. +.PP +The \fBUnsafeLegacyServerConnect\fR option is no longer set by default from +OpenSSL 3.0. +.PP +The \fBTxCertificateCompression\fR and \fBRxCertificateCompression\fR options were +added in OpenSSL 3.2. +.PP +\&\fBPreferNoDHEKEX\fR was added in OpenSSL 3.3. +.PP +OpenSSL 3.5 introduces support for post\-quantum (PQ) TLS key exchange via the +\&\fBMLKEM512\fR, \fBMLKEM768\fR and \fBMLKEM1024\fR TLS groups. +These are based on the underlying \fBML\-KEM\-512\fR, \fBML\-KEM\-768\fR and +\&\fBML\-KEM\-1024\fR algorithms from FIPS 203. +.PP +OpenSSL 3.5 also introduces support for three \fBhybrid\fR ECDH PQ key exchange +TLS groups: \fBX25519MLKEM768\fR, \fBSecP256r1MLKEM768\fR and +\&\fBSecP384r1MLKEM1024\fR. +They offer CPU performance comparable to the associated ECDH group, though at +the cost of significantly larger key exchange messages. +The third group, \fBSecP384r1MLKEM1024\fR is substantially more CPU\-intensive, +largely as a result of the high CPU cost of ECDH for the underlying \fBP\-384\fR +group. +Also its key exchange messages at close to 1700 bytes are larger than the +roughly 1200 bytes for the first two groups. +.PP +As of OpenSSL 3.5 key exchange group names are case\-insensitive. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CONF_cmd_argv.3 b/static/netbsd/man3/SSL_CONF_cmd_argv.3 new file mode 100644 index 00000000..aa607b1b --- /dev/null +++ b/static/netbsd/man3/SSL_CONF_cmd_argv.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: SSL_CONF_cmd_argv.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CONF_cmd_argv 3" +.TH SSL_CONF_cmd_argv 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CONF_cmd_argv \- SSL configuration command line processing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBSSL_CONF_cmd_argv()\fR processes at most two command line +arguments from \fBpargv\fR and \fBpargc\fR. The values of \fBpargv\fR and \fBpargc\fR +are updated to reflect the number of command options processed. The \fBpargc\fR +argument can be set to \fBNULL\fR if it is not used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CONF_cmd_argv()\fR returns the number of command arguments processed: 0, 1, 2 +or a negative error code. +.PP +If \-2 is returned then an argument for a command is missing. +.PP +If \-1 is returned the command is recognised but couldn\*(Aqt be processed due +to an error: for example a syntax error in the argument. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CONF_CTX_new\fR\|(3), +\&\fBSSL_CONF_CTX_set_flags\fR\|(3), +\&\fBSSL_CONF_CTX_set1_prefix\fR\|(3), +\&\fBSSL_CONF_CTX_set_ssl_ctx\fR\|(3), +\&\fBSSL_CONF_cmd\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_add1_chain_cert.3 b/static/netbsd/man3/SSL_CTX_add1_chain_cert.3 new file mode 100644 index 00000000..3a9ebb1f --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_add1_chain_cert.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: SSL_CTX_add1_chain_cert.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_add1_chain_cert 3" +.TH SSL_CTX_add1_chain_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, +SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, +SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, +SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, +SSL_build_cert_chain, SSL_CTX_select_current_cert, +SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert \- extra +chain certificate processing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); +\& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); +\& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); +\& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); +\& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); +\& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); +\& +\& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); +\& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); +\& int SSL_add0_chain_cert(SSL *ssl, X509 *x509); +\& int SSL_add1_chain_cert(SSL *ssl, X509 *x509); +\& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); +\& int SSL_clear_chain_certs(SSL *ssl); +\& +\& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); +\& int SSL_build_cert_chain(SSL *ssl, flags); +\& +\& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); +\& int SSL_select_current_cert(SSL *ssl, X509 *x509); +\& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); +\& int SSL_set_current_cert(SSL *ssl, long op); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set0_chain()\fR and \fBSSL_CTX_set1_chain()\fR set the certificate chain +associated with the current certificate of \fBctx\fR to \fBsk\fR. +.PP +\&\fBSSL_CTX_add0_chain_cert()\fR and \fBSSL_CTX_add1_chain_cert()\fR append the single +certificate \fBx509\fR to the chain associated with the current certificate of +\&\fBctx\fR. +.PP +\&\fBSSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current +certificate of \fBctx\fR. +.PP +\&\fBSSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the +current certificate of \fBctx\fR. (This is implemented by calling +\&\fBSSL_CTX_set0_chain()\fR with \fBsk\fR set to \fBNULL\fR). +.PP +\&\fBSSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR. +Normally this uses the chain store +or the verify store if the chain store is not set. +If the function is successful the built chain will replace any existing chain. +The \fBflags\fR parameter can be set to \fBSSL_BUILD_CHAIN_FLAG_UNTRUSTED\fR to use +existing chain certificates as untrusted CAs, \fBSSL_BUILD_CHAIN_FLAG_NO_ROOT\fR +to omit the root CA from the built chain, \fBSSL_BUILD_CHAIN_FLAG_CHECK\fR to +use all existing chain certificates only to build the chain (effectively +sanity checking and rearranging them if necessary), the flag +\&\fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\fR ignores any errors during verification: +if flag \fBSSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\fR is also set verification errors +are cleared from the error queue. +Details of the chain building process are described in +"Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1). +.PP +Each of these functions operates on the \fIcurrent\fR end entity +(i.e. server or client) certificate. This is the last certificate loaded or +selected on the corresponding \fBctx\fR structure. +.PP +\&\fBSSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity +certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a +function such as \fBSSL_CTX_use_certificate()\fR. +.PP +\&\fBSSL_set0_chain()\fR, \fBSSL_set1_chain()\fR, \fBSSL_add0_chain_cert()\fR, +\&\fBSSL_add1_chain_cert()\fR, \fBSSL_get0_chain_certs()\fR, \fBSSL_clear_chain_certs()\fR, +\&\fBSSL_build_cert_chain()\fR, \fBSSL_select_current_cert()\fR and \fBSSL_set_current_cert()\fR +are similar except they apply to SSL structure \fBssl\fR. +.PP +\&\fBSSL_CTX_set_current_cert()\fR changes the current certificate to a value based +on the \fBop\fR argument. Currently \fBop\fR can be \fBSSL_CERT_SET_FIRST\fR to use +the first valid certificate or \fBSSL_CERT_SET_NEXT\fR to set the next valid +certificate after the current certificate. These two operations can be +used to iterate over all certificates in an \fBSSL_CTX\fR structure. +.PP +\&\fBSSL_set_current_cert()\fR also supports the option \fBSSL_CERT_SET_SERVER\fR. +If \fBssl\fR is a server and has sent a certificate to a connected client +this option sets that certificate to the current certificate and returns 1. +If the negotiated cipher suite is anonymous (and thus no certificate will +be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR +is not a server or a certificate has not been sent 0 is returned and +the current certificate is unchanged. +.PP +All these functions are implemented as macros. Those containing a \fB1\fR +increment the reference count of the supplied certificate or chain so it must +be freed at some point after the operation. Those containing a \fB0\fR do +not increment reference counts and the supplied certificate or chain +\&\fBMUST NOT\fR be freed after the operation. +.SH NOTES +.IX Header "NOTES" +The chains associate with an SSL_CTX structure are copied to any SSL +structures when \fBSSL_new()\fR is called. SSL structures will not be affected +by any chains subsequently changed in the parent SSL_CTX. +.PP +One chain can be set for each key type supported by a server. So, for example, +an RSA and a DSA certificate can (and often will) have different chains. +.PP +The functions \fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR can +be used to check application configuration and to ensure any necessary +subordinate CAs are sent in the correct order. Misconfigured applications +sending incorrect certificate chains often cause problems with peers. +.PP +For example an application can add any set of certificates using +\&\fBSSL_CTX_use_certificate_chain_file()\fR then call \fBSSL_CTX_build_cert_chain()\fR +with the option \fBSSL_BUILD_CHAIN_FLAG_CHECK\fR to check and reorder them. +.PP +Applications can issue non fatal warnings when checking chains by setting +the flag \fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\fR and checking the return +value. +.PP +Calling \fBSSL_CTX_build_cert_chain()\fR or \fBSSL_build_cert_chain()\fR is more +efficient than the automatic chain building as it is only performed once. +Automatic chain building is performed on each new session. +.PP +If any certificates are added using these functions no certificates added +using \fBSSL_CTX_add_extra_chain_cert()\fR will be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_current_cert()\fR with \fBSSL_CERT_SET_SERVER\fR return 1 for success, 2 if +no server certificate is used because the cipher suites is anonymous and 0 +for failure. +.PP +\&\fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR return 1 for success +and 0 for failure. If the flag \fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\fR and +a verification error occurs then 2 is returned. +.PP +All other functions return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_add_extra_chain_cert.3 b/static/netbsd/man3/SSL_CTX_add_extra_chain_cert.3 new file mode 100644 index 00000000..cb6f8d0a --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_add_extra_chain_cert.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: SSL_CTX_add_extra_chain_cert.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_add_extra_chain_cert 3" +.TH SSL_CTX_add_extra_chain_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_add_extra_chain_cert, +SSL_CTX_get_extra_chain_certs, +SSL_CTX_get_extra_chain_certs_only, +SSL_CTX_clear_extra_chain_certs +\&\- add, get or clear extra chain certificates +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509); +\& long SSL_CTX_get_extra_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); +\& long SSL_CTX_get_extra_chain_certs_only(SSL_CTX *ctx, STACK_OF(X509) **sk); +\& long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_add_extra_chain_cert()\fR adds the certificate \fBx509\fR to the extra chain +certificates associated with \fBctx\fR. Several certificates can be added one +after another. +.PP +\&\fBSSL_CTX_get_extra_chain_certs()\fR retrieves the extra chain certificates +associated with \fBctx\fR, or the chain associated with the current certificate +of \fBctx\fR if the extra chain is empty. +The returned stack should not be freed by the caller. +.PP +\&\fBSSL_CTX_get_extra_chain_certs_only()\fR retrieves the extra chain certificates +associated with \fBctx\fR. +The returned stack should not be freed by the caller. +.PP +\&\fBSSL_CTX_clear_extra_chain_certs()\fR clears all extra chain certificates +associated with \fBctx\fR. +.PP +These functions are implemented as macros. +.SH NOTES +.IX Header "NOTES" +When sending a certificate chain, extra chain certificates are sent in order +following the end entity certificate. +.PP +If no chain is specified, the library will try to complete the chain from the +available CA certificates in the trusted CA storage, see +\&\fBSSL_CTX_load_verify_locations\fR\|(3). +.PP +The \fBx509\fR certificate provided to \fBSSL_CTX_add_extra_chain_cert()\fR will be +freed by the library when the \fBSSL_CTX\fR is destroyed. An application +\&\fBshould not\fR free the \fBx509\fR object. +.SH RESTRICTIONS +.IX Header "RESTRICTIONS" +Only one set of extra chain certificates can be specified per SSL_CTX +structure. Different chains for different certificates (for example if both +RSA and DSA certificates are specified by the same server) or different SSL +structures with the same parent SSL_CTX cannot be specified using this +function. For more flexibility functions such as \fBSSL_add1_chain_cert()\fR should +be used instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_add_extra_chain_cert()\fR and \fBSSL_CTX_clear_extra_chain_certs()\fR return +1 on success and 0 for failure. Check out the error stack to find out the +reason for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_use_certificate\fR\|(3), +\&\fBSSL_CTX_set_client_cert_cb\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +\&\fBSSL_CTX_set0_chain\fR\|(3) +\&\fBSSL_CTX_set1_chain\fR\|(3) +\&\fBSSL_CTX_add0_chain_cert\fR\|(3) +\&\fBSSL_CTX_add1_chain_cert\fR\|(3) +\&\fBSSL_set0_chain\fR\|(3) +\&\fBSSL_set1_chain\fR\|(3) +\&\fBSSL_add0_chain_cert\fR\|(3) +\&\fBSSL_add1_chain_cert\fR\|(3) +\&\fBSSL_CTX_build_cert_chain\fR\|(3) +\&\fBSSL_build_cert_chain\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_add_session.3 b/static/netbsd/man3/SSL_CTX_add_session.3 new file mode 100644 index 00000000..468771e8 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_add_session.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: SSL_CTX_add_session.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_add_session 3" +.TH SSL_CTX_add_session 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_add_session, SSL_CTX_remove_session \- manipulate session cache +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); +\& +\& int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_add_session()\fR adds the session \fBc\fR to the context \fBctx\fR. The +reference count for session \fBc\fR is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +\&\fBSSL_SESSION_free\fR\|(3). +.PP +\&\fBSSL_CTX_remove_session()\fR removes the session \fBc\fR from the context \fBctx\fR and +marks it as non\-resumable. \fBSSL_SESSION_free\fR\|(3) is called once for \fBc\fR. +.SH NOTES +.IX Header "NOTES" +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. In this case +it is assumed that both sessions are identical. If the same session is +stored in a different SSL_SESSION object, The old session is +removed and replaced by the new session. If the session is actually +identical (the SSL_SESSION object is identical), \fBSSL_CTX_add_session()\fR +is a no\-op, and the return value is 0. +.PP +If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE +flag then the internal cache will not be populated automatically by new +sessions negotiated by the SSL/TLS implementation, even though the internal +cache will be searched automatically for session\-resume requests (the +latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the +application can use \fBSSL_CTX_add_session()\fR directly to have full control +over the sessions that can be resumed if desired. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following values are returned by all functions: +.IP 0 4 +The operation failed. In case of the add operation, it was tried to add +the same (identical) session twice. In case of the remove operation, the +session was not found in the cache. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_config.3 b/static/netbsd/man3/SSL_CTX_config.3 new file mode 100644 index 00000000..08702f7a --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_config.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: SSL_CTX_config.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_config 3" +.TH SSL_CTX_config 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_config, SSL_config \- configure SSL_CTX or SSL structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_config(SSL_CTX *ctx, const char *name); +\& int SSL_config(SSL *s, const char *name); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions \fBSSL_CTX_config()\fR and \fBSSL_config()\fR configure an \fBSSL_CTX\fR or +\&\fBSSL\fR structure using the configuration \fBname\fR. +.PP +By calling \fBSSL_CTX_config()\fR or \fBSSL_config()\fR an application can perform many +complex tasks based on the contents of the configuration file: greatly +simplifying application configuration code. A degree of future proofing +can also be achieved: an application can support configuration features +in newer versions of OpenSSL automatically. +.PP +A configuration file must have been previously loaded, for example using +\&\fBCONF_modules_load_file()\fR. See \fBconfig\fR\|(5) for details of the configuration +file syntax. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_config()\fR and \fBSSL_config()\fR return 1 for success or 0 if an error +occurred. +.SH EXAMPLES +.IX Header "EXAMPLES" +If the file "config.cnf" contains the following: +.PP +.Vb 1 +\& testapp = test_sect +\& +\& [test_sect] +\& # list of configuration modules +\& +\& ssl_conf = ssl_sect +\& +\& [ssl_sect] +\& server = server_section +\& +\& [server_section] +\& RSA.Certificate = server\-rsa.pem +\& ECDSA.Certificate = server\-ecdsa.pem +\& Ciphers = ALL:!RC4 +.Ve +.PP +An application could call: +.PP +.Vb 4 +\& if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) { +\& fprintf(stderr, "Error processing config file\en"); +\& goto err; +\& } +\& +\& ctx = SSL_CTX_new(TLS_server_method()); +\& +\& if (SSL_CTX_config(ctx, "server") == 0) { +\& fprintf(stderr, "Error configuring server.\en"); +\& goto err; +\& } +.Ve +.PP +In this example two certificates and the cipher list are configured without +the need for any additional application code. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBconfig\fR\|(5), +\&\fBSSL_CONF_cmd\fR\|(3), +\&\fBCONF_modules_load_file\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CTX_config()\fR and \fBSSL_config()\fR functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_ctrl.3 b/static/netbsd/man3/SSL_CTX_ctrl.3 new file mode 100644 index 00000000..083e1347 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_ctrl.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: SSL_CTX_ctrl.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_ctrl 3" +.TH SSL_CTX_ctrl 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl \- internal handling functions for SSL_CTX and SSL objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg); +\& long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); +\& +\& long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); +\& long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The SSL_*\fB_ctrl()\fR family of functions is used to manipulate settings of +the SSL_CTX and SSL objects. Depending on the command \fBcmd\fR the arguments +\&\fBlarg\fR, \fBparg\fR, or \fBfp\fR are evaluated. These functions should never +be called directly. All functionalities needed are made available via +other functions or macros. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The return values of the SSL*\fB_ctrl()\fR functions depend on the command +supplied via the \fBcmd\fR parameter. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_dane_enable.3 b/static/netbsd/man3/SSL_CTX_dane_enable.3 new file mode 100644 index 00000000..9fcb07de --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_dane_enable.3 @@ -0,0 +1,444 @@ +.\" $NetBSD: SSL_CTX_dane_enable.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_dane_enable 3" +.TH SSL_CTX_dane_enable 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, +SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, +SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, +SSL_dane_set_flags, SSL_dane_clear_flags +\&\- enable DANE TLS authentication of the remote TLS server in the local +TLS client +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_dane_enable(SSL_CTX *ctx); +\& int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, +\& uint8_t mtype, uint8_t ord); +\& int SSL_dane_enable(SSL *s, const char *basedomain); +\& int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, +\& uint8_t mtype, const unsigned char *data, size_t dlen); +\& int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); +\& int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, +\& uint8_t *mtype, const unsigned char **data, +\& size_t *dlen); +\& unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); +\& unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); +\& unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); +\& unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions implement support for DANE TLSA (RFC6698 and RFC7671) +peer authentication. +.PP +\&\fBSSL_CTX_dane_enable()\fR must be called first to initialize the shared state +required for DANE support. +Individual connections associated with the context can then enable +per\-connection DANE support as appropriate. +DANE authentication is implemented in the \fBX509_verify_cert\fR\|(3) function, and +applications that override \fBX509_verify_cert\fR\|(3) via +\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3) are responsible to authenticate the peer +chain in whatever manner they see fit. +.PP +\&\fBSSL_CTX_dane_mtype_set()\fR may then be called zero or more times to adjust the +supported digest algorithms. +This must be done before any SSL handles are created for the context. +.PP +The \fBmtype\fR argument specifies a DANE TLSA matching type and the \fBmd\fR +argument specifies the associated digest algorithm handle. +The \fBord\fR argument specifies a strength ordinal. +Algorithms with a larger strength ordinal are considered more secure. +Strength ordinals are used to implement RFC7671 digest algorithm agility. +Specifying a \fBNULL\fR digest algorithm for a matching type disables +support for that matching type. +Matching type \fBFull\fR\|(0) cannot be modified or disabled. +.PP +By default, matching type \f(CW\*(C`SHA2\-256(1)\*(C'\fR (see RFC7218 for definitions +of the DANE TLSA parameter acronyms) is mapped to \f(CWEVP_sha256()\fR +with a strength ordinal of \f(CW1\fR and matching type \f(CW\*(C`SHA2\-512(2)\*(C'\fR +is mapped to \f(CWEVP_sha512()\fR with a strength ordinal of \f(CW2\fR. +.PP +\&\fBSSL_dane_enable()\fR must be called before the SSL handshake is initiated with +\&\fBSSL_connect\fR\|(3) if (and only if) you want to enable DANE for that connection. +(The connection must be associated with a DANE\-enabled SSL context). +The \fBbasedomain\fR argument specifies the RFC7671 TLSA base domain, +which will be the primary peer reference identifier for certificate +name checks. +Additional server names can be specified via \fBSSL_add1_host\fR\|(3). +The \fBbasedomain\fR is used as the default SNI hint if none has yet been +specified via \fBSSL_set_tlsext_host_name\fR\|(3). +.PP +\&\fBSSL_dane_tlsa_add()\fR may then be called one or more times, to load each of the +TLSA records that apply to the remote TLS peer. +(This too must be done prior to the beginning of the SSL handshake). +The arguments specify the fields of the TLSA record. +The \fBdata\fR field is provided in binary (wire RDATA) form, not the hexadecimal +ASCII presentation form, with an explicit length passed via \fBdlen\fR. +The library takes a copy of the \fBdata\fR buffer contents and the caller may +free the original \fBdata\fR buffer when convenient. +A return value of 0 indicates that "unusable" TLSA records (with invalid or +unsupported parameters) were provided. +A negative return value indicates an internal error in processing the record. +.PP +The caller is expected to check the return value of each \fBSSL_dane_tlsa_add()\fR +call and take appropriate action if none are usable or an internal error +is encountered in processing some records. +.PP +If no TLSA records are added successfully, DANE authentication is not enabled, +and authentication will be based on any configured traditional trust\-anchors; +authentication success in this case does not mean that the peer was +DANE\-authenticated. +.PP +\&\fBSSL_get0_dane_authority()\fR can be used to get more detailed information about +the matched DANE trust\-anchor after successful connection completion. +The return value is negative if DANE verification failed (or was not enabled), +0 if an EE TLSA record directly matched the leaf certificate, or a positive +number indicating the depth at which a TA record matched an issuer certificate. +The complete verified chain can be retrieved via \fBSSL_get0_verified_chain\fR\|(3). +The return value is an index into this verified chain, rather than the list of +certificates sent by the peer as returned by \fBSSL_get_peer_cert_chain\fR\|(3). +.PP +If the \fBmcert\fR argument is not \fBNULL\fR and a TLSA record matched a chain +certificate, a pointer to the matching certificate is returned via \fBmcert\fR. +The returned address is a short\-term internal reference to the certificate and +must not be freed by the application. +Applications that want to retain access to the certificate can call +\&\fBX509_up_ref\fR\|(3) to obtain a long\-term reference which must then be freed via +\&\fBX509_free\fR\|(3) once no longer needed. +.PP +If no TLSA records directly matched any elements of the certificate chain, but +a \fBDANE\-TA\fR\|(2) \fBSPKI\fR\|(1) \fBFull\fR\|(0) record provided the public key that signed an +element of the chain, then that key is returned via \fBmspki\fR argument (if not +NULL). +In this case the return value is the depth of the top\-most element of the +validated certificate chain. +As with \fBmcert\fR this is a short\-term internal reference, and +\&\fBEVP_PKEY_up_ref\fR\|(3) and \fBEVP_PKEY_free\fR\|(3) can be used to acquire and +release long\-term references respectively. +.PP +\&\fBSSL_get0_dane_tlsa()\fR can be used to retrieve the fields of the TLSA record that +matched the peer certificate chain. +The return value indicates the match depth or failure to match just as with +\&\fBSSL_get0_dane_authority()\fR. +When the return value is nonnegative, the storage pointed to by the \fBusage\fR, +\&\fBselector\fR, \fBmtype\fR and \fBdata\fR parameters is updated to the corresponding +TLSA record fields. +The \fBdata\fR field is in binary wire form, and is therefore not NUL\-terminated, +its length is returned via the \fBdlen\fR parameter. +If any of these parameters is NULL, the corresponding field is not returned. +The \fBdata\fR parameter is set to a short\-term internal\-copy of the associated +data field and must not be freed by the application. +Applications that need long\-term access to this field need to copy the content. +.PP +\&\fBSSL_CTX_dane_set_flags()\fR and \fBSSL_dane_set_flags()\fR can be used to enable +optional DANE verification features. +\&\fBSSL_CTX_dane_clear_flags()\fR and \fBSSL_dane_clear_flags()\fR can be used to disable +the same features. +The \fBflags\fR argument is a bit\-mask of the features to enable or disable. +The \fBflags\fR set for an \fBSSL_CTX\fR context are copied to each \fBSSL\fR handle +associated with that context at the time the handle is created. +Subsequent changes in the context\*(Aqs \fBflags\fR have no effect on the \fBflags\fR set +for the handle. +.PP +At present, the only available option is \fBDANE_FLAG_NO_DANE_EE_NAMECHECKS\fR +which can be used to disable server name checks when authenticating via +\&\fBDANE\-EE\fR\|(3) TLSA records. +For some applications, primarily web browsers, it is not safe to disable name +checks due to "unknown key share" attacks, in which a malicious server can +convince a client that a connection to a victim server is instead a secure +connection to the malicious server. +The malicious server may then be able to violate cross\-origin scripting +restrictions. +Thus, despite the text of RFC7671, name checks are by default enabled for +\&\fBDANE\-EE\fR\|(3) TLSA records, and can be disabled in applications where it is safe +to do so. +In particular, SMTP and XMPP clients should set this option as SRV and MX +records already make it possible for a remote domain to redirect client +connections to any server of its choice, and in any case SMTP and XMPP clients +do not execute scripts downloaded from remote servers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions \fBSSL_CTX_dane_enable()\fR, \fBSSL_CTX_dane_mtype_set()\fR, +\&\fBSSL_dane_enable()\fR and \fBSSL_dane_tlsa_add()\fR return a positive value on success. +Negative return values indicate resource problems (out of memory, etc.) in the +SSL library, while a return value of \fB0\fR indicates incorrect usage or invalid +input, such as an unsupported TLSA record certificate usage, selector or +matching type. +Invalid input also includes malformed data, either a digest length that does +not match the digest algorithm, or a \f(CWFull(0)\fR (binary ASN.1 DER form) +certificate or a public key that fails to parse. +.PP +The functions \fBSSL_get0_dane_authority()\fR and \fBSSL_get0_dane_tlsa()\fR return a +negative value when DANE authentication failed or was not enabled, a +nonnegative value indicates the chain depth at which the TLSA record matched a +chain certificate, or the depth of the top\-most certificate, when the TLSA +record is a full public key that is its signer. +.PP +The functions \fBSSL_CTX_dane_set_flags()\fR, \fBSSL_CTX_dane_clear_flags()\fR, +\&\fBSSL_dane_set_flags()\fR and \fBSSL_dane_clear_flags()\fR return the \fBflags\fR in effect +before they were called. +.SH EXAMPLES +.IX Header "EXAMPLES" +Suppose "smtp.example.com" is the MX host of the domain "example.com", and has +DNSSEC\-validated TLSA records. +The calls below will perform DANE authentication and arrange to match either +the MX hostname or the destination domain name in the SMTP server certificate. +Wildcards are supported, but must match the entire label. +The actual name matched in the certificate (which might be a wildcard) is +retrieved, and must be copied by the application if it is to be retained beyond +the lifetime of the SSL connection. +.PP +.Vb 7 +\& SSL_CTX *ctx; +\& SSL *ssl; +\& int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; +\& int num_usable = 0; +\& const char *nexthop_domain = "example.com"; +\& const char *dane_tlsa_domain = "smtp.example.com"; +\& uint8_t usage, selector, mtype; +\& +\& if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) +\& /* error */ +\& if (SSL_CTX_dane_enable(ctx) <= 0) +\& /* error */ +\& if ((ssl = SSL_new(ctx)) == NULL) +\& /* error */ +\& if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) +\& /* error */ +\& +\& /* +\& * For many applications it is safe to skip DANE\-EE(3) namechecks. Do not +\& * disable the checks unless "unknown key share" attacks pose no risk for +\& * your application. +\& */ +\& SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); +\& +\& if (!SSL_add1_host(ssl, nexthop_domain)) +\& /* error */ +\& SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); +\& +\& for (... each TLSA record ...) { +\& unsigned char *data; +\& size_t len; +\& int ret; +\& +\& /* set usage, selector, mtype, data, len */ +\& +\& /* +\& * Opportunistic DANE TLS clients support only DANE\-TA(2) or DANE\-EE(3). +\& * They treat all other certificate usages, and in particular PKIX\-TA(0) +\& * and PKIX\-EE(1), as unusable. +\& */ +\& switch (usage) { +\& default: +\& case 0: /* PKIX\-TA(0) */ +\& case 1: /* PKIX\-EE(1) */ +\& continue; +\& case 2: /* DANE\-TA(2) */ +\& case 3: /* DANE\-EE(3) */ +\& break; +\& } +\& +\& ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); +\& /* free data as appropriate */ +\& +\& if (ret < 0) +\& /* handle SSL library internal error */ +\& else if (ret == 0) +\& /* handle unusable TLSA record */ +\& else +\& ++num_usable; +\& } +\& +\& /* +\& * At this point, the verification mode is still the default SSL_VERIFY_NONE. +\& * Opportunistic DANE clients use unauthenticated TLS when all TLSA records +\& * are unusable, so continue the handshake even if authentication fails. +\& */ +\& if (num_usable == 0) { +\& /* Log all records unusable? */ +\& +\& /* Optionally set verify_cb to a suitable non\-NULL callback. */ +\& SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); +\& } else { +\& /* At least one usable record. We expect to verify the peer */ +\& +\& /* Optionally set verify_cb to a suitable non\-NULL callback. */ +\& +\& /* +\& * Below we elect to fail the handshake when peer verification fails. +\& * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, +\& * complete the handshake, check the verification status, and if not +\& * verified disconnect gracefully at the application layer, especially if +\& * application protocol supports informing the server that authentication +\& * failed. +\& */ +\& SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); +\& } +\& +\& /* +\& * Load any saved session for resumption, making sure that the previous +\& * session applied the same security and authentication requirements that +\& * would be expected of a fresh connection. +\& */ +\& +\& /* Perform SSL_connect() handshake and handle errors here */ +\& +\& if (SSL_session_reused(ssl)) { +\& if (SSL_get_verify_result(ssl) == X509_V_OK) { +\& /* +\& * Resumed session was originally verified, this connection is +\& * authenticated. +\& */ +\& } else { +\& /* +\& * Resumed session was not originally verified, this connection is not +\& * authenticated. +\& */ +\& } +\& } else if (SSL_get_verify_result(ssl) == X509_V_OK) { +\& const char *peername = SSL_get0_peername(ssl); +\& EVP_PKEY *mspki = NULL; +\& +\& int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); +\& if (depth >= 0) { +\& (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); +\& printf("DANE TLSA %d %d %d ", usage, selector, mtype); +\& if (SSL_get0_peer_rpk(ssl) == NULL) +\& printf("%s certificate at depth %d\en", +\& (mspki != NULL) ? "signed the peer" : +\& mdpth ? "matched the TA" : "matched the EE", mdpth); +\& else +\& printf(bio, "matched the peer raw public key\en"); +\& } +\& if (peername != NULL) { +\& /* Name checks were in scope and matched the peername */ +\& printf("Verified peername: %s\en", peername); +\& } +\& } else { +\& /* +\& * Not authenticated, presumably all TLSA rrs unusable, but possibly a +\& * callback suppressed connection termination despite the presence of +\& * usable TLSA RRs none of which matched. Do whatever is appropriate for +\& * fresh unauthenticated connections. +\& */ +\& } +.Ve +.SH NOTES +.IX Header "NOTES" +It is expected that the majority of clients employing DANE TLS will be doing +"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. +That is, they will use DANE authentication when DNSSEC\-validated TLSA records +are published for a given peer, and otherwise will use unauthenticated TLS or +even cleartext. +.PP +Such applications should generally treat any TLSA records published by the peer +with usages \fBPKIX\-TA\fR\|(0) and \fBPKIX\-EE\fR\|(1) as "unusable", and should not include +them among the TLSA records used to authenticate peer connections. +In addition, some TLSA records with supported usages may be "unusable" as a +result of invalid or unsupported parameters. +.PP +When a peer has TLSA records, but none are "usable", an opportunistic +application must avoid cleartext, but cannot authenticate the peer, +and so should generally proceed with an unauthenticated connection. +Opportunistic applications need to note the return value of each +call to \fBSSL_dane_tlsa_add()\fR, and if all return 0 (due to invalid +or unsupported parameters) disable peer authentication by calling +\&\fBSSL_set_verify\fR\|(3) with \fBmode\fR equal to \fBSSL_VERIFY_NONE\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_new\fR\|(3), +\&\fBSSL_add1_host\fR\|(3), +\&\fBSSL_set_hostflags\fR\|(3), +\&\fBSSL_set_tlsext_host_name\fR\|(3), +\&\fBSSL_set_verify\fR\|(3), +\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3), +\&\fBSSL_get0_verified_chain\fR\|(3), +\&\fBSSL_get_peer_cert_chain\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_connect\fR\|(3), +\&\fBSSL_get0_peername\fR\|(3), +\&\fBX509_verify_cert\fR\|(3), +\&\fBX509_up_ref\fR\|(3), +\&\fBX509_free\fR\|(3), +\&\fBEVP_get_digestbyname\fR\|(3), +\&\fBEVP_PKEY_up_ref\fR\|(3), +\&\fBEVP_PKEY_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_flush_sessions.3 b/static/netbsd/man3/SSL_CTX_flush_sessions.3 new file mode 100644 index 00000000..80220f84 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_flush_sessions.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: SSL_CTX_flush_sessions.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_flush_sessions 3" +.TH SSL_CTX_flush_sessions 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_flush_sessions_ex, SSL_CTX_flush_sessions \- remove expired sessions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_flush_sessions_ex(SSL_CTX *ctx, time_t tm); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.4, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_flush_sessions_ex()\fR causes a run through the session cache of +\&\fBctx\fR to remove sessions expired at time \fBtm\fR. +.PP +\&\fBSSL_CTX_flush_sessions()\fR is an older variant of the function that is not +Y2038 safe due to usage of long datatype instead of time_t. +.SH NOTES +.IX Header "NOTES" +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see \fBSSL_CTX_sess_set_cache_size()\fR). +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. This can either be done +automatically whenever 255 new sessions were established (see +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3)) +or manually by calling \fBSSL_CTX_flush_sessions_ex()\fR. +.PP +The parameter \fBtm\fR specifies the time which should be used for the +expiration test, in most cases the actual time given by \fBtime\fR\|(0) +will be used. +.PP +\&\fBSSL_CTX_flush_sessions_ex()\fR will only check sessions stored in the internal +cache. When a session is found and removed, the remove_session_cb is however +called to synchronize with the external cache (see +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_flush_sessions_ex()\fR does not return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_CTX_set_timeout\fR\|(3), +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_flush_sessions_ex()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_free.3 b/static/netbsd/man3/SSL_CTX_free.3 new file mode 100644 index 00000000..fd5409ce --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_free.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: SSL_CTX_free.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_free 3" +.TH SSL_CTX_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_free \- free an allocated SSL_CTX object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_free(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_free()\fR decrements the reference count of \fBctx\fR, and removes the +SSL_CTX object pointed to by \fBctx\fR and frees up the allocated memory if the reference count has reached 0. +.PP +It also calls the \fBfree()\fRing procedures for indirectly affected items, if +applicable: the session cache, the list of ciphers, the list of Client CAs, +the certificates and keys. +.PP +If \fBctx\fR is NULL nothing is done. +.SH WARNINGS +.IX Header "WARNINGS" +If a session\-remove callback is set (\fBSSL_CTX_sess_set_remove_cb()\fR), this +callback will be called for each session being freed from \fBctx\fR\*(Aqs +session cache. This implies, that all corresponding sessions from an +external session cache are removed as well. If this is not desired, the user +should explicitly unset the callback by calling +SSL_CTX_sess_set_remove_cb(\fBctx\fR, NULL) prior to calling \fBSSL_CTX_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_free()\fR does not provide diagnostic information. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_new\fR\|(3), \fBssl\fR\|(7), +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_get0_param.3 b/static/netbsd/man3/SSL_CTX_get0_param.3 new file mode 100644 index 00000000..73ef8e79 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_get0_param.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: SSL_CTX_get0_param.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_get0_param 3" +.TH SSL_CTX_get0_param 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param, +SSL_CTX_set_purpose, SSL_CTX_set_trust, SSL_set_purpose, SSL_set_trust \- +get and set verification parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx); +\& X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl); +\& int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm); +\& int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm); +\& +\& int SSL_CTX_set_purpose(SSL_CTX *ctx, int purpose); +\& int SSL_set_purpose(SSL *ssl, int purpose); +\& +\& int SSL_CTX_set_trust(SSL_CTX *ctx, int trust); +\& int SSL_set_trust(SSL *ssl, int trust); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_get0_param()\fR and \fBSSL_get0_param()\fR retrieve an internal pointer to +the verification parameters for \fBctx\fR or \fBssl\fR respectively. The returned +pointer must not be freed by the calling application. +.PP +\&\fBSSL_CTX_set1_param()\fR and \fBSSL_set1_param()\fR set the verification parameters +to \fBvpm\fR for \fBctx\fR or \fBssl\fR. +.PP +The functions \fBSSL_CTX_set_purpose()\fR and \fBSSL_set_purpose()\fR are shorthands which +set the purpose parameter on the verification parameters object. These functions +are equivalent to calling \fBX509_VERIFY_PARAM_set_purpose()\fR directly. +.PP +The functions \fBSSL_CTX_set_trust()\fR and \fBSSL_set_trust()\fR are similarly shorthands +which set the trust parameter on the verification parameters object. These +functions are equivalent to calling \fBX509_VERIFY_PARAM_set_trust()\fR directly. +.SH NOTES +.IX Header "NOTES" +Typically parameters are retrieved from an \fBSSL_CTX\fR or \fBSSL\fR structure +using \fBSSL_CTX_get0_param()\fR or \fBSSL_get0_param()\fR and an application modifies +them to suit its needs: for example to add a hostname check. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_get0_param()\fR and \fBSSL_get0_param()\fR return a pointer to an +\&\fBX509_VERIFY_PARAM\fR structure. +.PP +\&\fBSSL_CTX_set1_param()\fR, \fBSSL_set1_param()\fR, \fBSSL_CTX_set_purpose()\fR, +\&\fBSSL_set_purpose()\fR, \fBSSL_CTX_set_trust()\fR and \fBSSL_set_trust()\fR return 1 for success +and 0 for failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +Check hostname matches "www.foo.com" in peer certificate: +.PP +.Vb 2 +\& X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); +\& X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBX509_VERIFY_PARAM_set_flags\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_get_ex_new_index.3 b/static/netbsd/man3/SSL_CTX_get_ex_new_index.3 new file mode 100644 index 00000000..6288cace --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_get_ex_new_index.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: SSL_CTX_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_get_ex_new_index 3" +.TH SSL_CTX_get_ex_new_index 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data \- internal application specific data functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); +\& +\& void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); +\& +\& typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, +\& int idx, long argl, void *argp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.PP +\&\fISSL_CTX_get_ex_new_index()\fR is used to register a new index for application +specific data. +.PP +\&\fISSL_CTX_set_ex_data()\fR is used to store application data at \fBarg\fR for \fBidx\fR +into the \fBctx\fR object. +.PP +\&\fISSL_CTX_get_ex_data()\fR is used to retrieve the information for \fBidx\fR from +\&\fBctx\fR. +.PP +A detailed description for the \fB*\f(BI_get_ex_new_index()\fB\fR functionality +can be found in \fIRSA_get_ex_new_index\fR\|(3). +The \fB*\f(BI_get_ex_data()\fB\fR and \fB*\f(BI_set_ex_data()\fB\fR functionality is described in +\&\fICRYPTO_set_ex_data\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(3), +\&\fIRSA_get_ex_new_index\fR\|(3), +\&\fICRYPTO_set_ex_data\fR\|(3) diff --git a/static/netbsd/man3/SSL_CTX_get_verify_mode.3 b/static/netbsd/man3/SSL_CTX_get_verify_mode.3 new file mode 100644 index 00000000..fa85a373 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_get_verify_mode.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: SSL_CTX_get_verify_mode.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_get_verify_mode 3" +.TH SSL_CTX_get_verify_mode 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback \- get currently set verification parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); +\& int SSL_get_verify_mode(const SSL *ssl); +\& int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); +\& int SSL_get_verify_depth(const SSL *ssl); +\& int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *); +\& int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_get_verify_mode()\fR returns the verification mode currently set in +\&\fBctx\fR. +.PP +\&\fBSSL_get_verify_mode()\fR returns the verification mode currently set in +\&\fBssl\fR. +.PP +\&\fBSSL_CTX_get_verify_depth()\fR returns the verification depth limit currently set +in \fBctx\fR. If no limit has been explicitly set, \-1 is returned and the +default value will be used. +.PP +\&\fBSSL_get_verify_depth()\fR returns the verification depth limit currently set +in \fBssl\fR. If no limit has been explicitly set, \-1 is returned and the +default value will be used. +.PP +\&\fBSSL_CTX_get_verify_callback()\fR returns a function pointer to the verification +callback currently set in \fBctx\fR. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. +.PP +\&\fBSSL_get_verify_callback()\fR returns a function pointer to the verification +callback currently set in \fBssl\fR. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +See DESCRIPTION +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_verify\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_has_client_custom_ext.3 b/static/netbsd/man3/SSL_CTX_has_client_custom_ext.3 new file mode 100644 index 00000000..9dff6b21 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_has_client_custom_ext.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: SSL_CTX_has_client_custom_ext.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_has_client_custom_ext 3" +.TH SSL_CTX_has_client_custom_ext 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_has_client_custom_ext \- check whether a handler exists for a particular +client extension type +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_has_client_custom_ext()\fR checks whether a handler has been set for a +client extension of type \fBext_type\fR using \fBSSL_CTX_add_client_custom_ext()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 if a handler has been set, 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_add_client_custom_ext\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_load_verify_locations.3 b/static/netbsd/man3/SSL_CTX_load_verify_locations.3 new file mode 100644 index 00000000..558709f0 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_load_verify_locations.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: SSL_CTX_load_verify_locations.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_load_verify_locations 3" +.TH SSL_CTX_load_verify_locations 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file, +SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths, +SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file, +SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations +\&\- set default locations for trusted CA certificates +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath); +\& int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile); +\& int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore); +\& +\& int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); +\& +\& int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx); +\& int SSL_CTX_set_default_verify_file(SSL_CTX *ctx); +\& int SSL_CTX_set_default_verify_store(SSL_CTX *ctx); +\& +\& int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, +\& const char *CApath); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_load_verify_locations()\fR, \fBSSL_CTX_load_verify_dir()\fR, +\&\fBSSL_CTX_load_verify_file()\fR, \fBSSL_CTX_load_verify_store()\fR specifies the +locations for \fBctx\fR, at which CA certificates for verification purposes +are located. The certificates available via \fBCAfile\fR, \fBCApath\fR and +\&\fBCAstore\fR are trusted. \fBctx\fR \fBMUST NOT\fR be NULL +.PP +Details of the certificate verification and chain checking process are +described in "Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1). +.PP +\&\fBSSL_CTX_set_default_verify_paths()\fR specifies that the default locations from +which CA certificates are loaded should be used. There is one default directory, +one default file and one default store. +The default CA certificates directory is called \fIcerts\fR in the default OpenSSL +directory, and this is also the default store. +Alternatively the \fBSSL_CERT_DIR\fR environment variable can be defined to +override this location. +The default CA certificates file is called \fIcert.pem\fR in the default +OpenSSL directory. +Alternatively the \fBSSL_CERT_FILE\fR environment variable can be defined to +override this location. +\&\fBctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_CTX_set_default_verify_dir()\fR is similar to +\&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default directory is +used. +.PP +\&\fBSSL_CTX_set_default_verify_file()\fR is similar to +\&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default file is +used. +.PP +\&\fBSSL_CTX_set_default_verify_store()\fR is similar to +\&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default store is +used. +.SH NOTES +.IX Header "NOTES" +If \fBCAfile\fR is not NULL, it points to a file of CA certificates in PEM +format. The file can contain several CA certificates identified by +.PP +.Vb 3 +\& \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\- +\& ... (CA certificate in base64 encoding) ... +\& \-\-\-\-\-END CERTIFICATE\-\-\-\-\- +.Ve +.PP +sequences. Before, between, and after the certificates text is allowed +which can be used e.g. for descriptions of the certificates. +.PP +The \fBCAfile\fR is processed on execution of the \fBSSL_CTX_load_verify_locations()\fR +function. +.PP +If \fBCApath\fR is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain one CA certificate. The files are +looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. +Use the \fBc_rehash\fR utility to create the necessary links. +.PP +The certificates in \fBCApath\fR are only looked up when required, e.g. when +building the certificate chain or when actually performing the verification +of a peer certificate. +.PP +When looking up CA certificates for chain building, the OpenSSL library +will search for suitable certificates first in \fBCAfile\fR, then in \fBCApath\fR. +Details of the chain building process are described in +"Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1). +.PP +If \fBCAstore\fR is not NULL, it\*(Aqs a URI for to a store, which may +represent a single container or a whole catalogue of containers. +Apart from the \fBCAstore\fR not necessarily being a local file or +directory, it\*(Aqs generally treated the same way as a \fBCApath\fR. +.PP +In server mode, when requesting a client certificate, the server must send +the list of CAs of which it will accept client certificates. This list +is not influenced by the contents of \fBCAfile\fR or \fBCApath\fR and must +explicitly be set using the +\&\fBSSL_CTX_set_client_CA_list\fR\|(3) +family of functions. +.PP +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from \fBCAfile\fR/\fBCApath\fR, if the +certificate chain was not explicitly specified (see +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), +\&\fBSSL_CTX_use_certificate\fR\|(3). +.SH WARNINGS +.IX Header "WARNINGS" +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +For SSL_CTX_load_verify_locations the following return values can occur: +.IP 0 4 +The operation failed because \fBCAfile\fR and \fBCApath\fR are NULL or the +processing at one of the locations specified failed. Check the error +stack to find out the reason. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.PP +\&\fBSSL_CTX_set_default_verify_paths()\fR, \fBSSL_CTX_set_default_verify_dir()\fR and +\&\fBSSL_CTX_set_default_verify_file()\fR all return 1 on success or 0 on failure. A +missing default location is still treated as a success. +.SH EXAMPLES +.IX Header "EXAMPLES" +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: +.PP +.Vb 5 +\& #!/bin/sh +\& rm CAfile.pem +\& for i in ca1.pem ca2.pem ca3.pem ; do +\& openssl x509 \-in $i \-text >> CAfile.pem +\& done +.Ve +.PP +Prepare the directory /some/where/certs containing several CA certificates +for use as \fBCApath\fR: +.PP +.Vb 2 +\& cd /some/where/certs +\& c_rehash . +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_client_CA_list\fR\|(3), +\&\fBSSL_get_client_CA_list\fR\|(3), +\&\fBSSL_CTX_use_certificate\fR\|(3), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), +\&\fBSSL_CTX_set_cert_store\fR\|(3), +\&\fBSSL_CTX_set_client_CA_list\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_new.3 b/static/netbsd/man3/SSL_CTX_new.3 new file mode 100644 index 00000000..f7295c80 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_new.3 @@ -0,0 +1,299 @@ +.\" $NetBSD: SSL_CTX_new.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_new 3" +.TH SSL_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, +SSL_CTX_new, SSL_CTX_new_ex, SSL_CTX_up_ref, SSLv3_method, +SSLv3_server_method, SSLv3_client_method, TLSv1_method, TLSv1_server_method, +TLSv1_client_method, TLSv1_1_method, TLSv1_1_server_method, +TLSv1_1_client_method, TLS_method, TLS_server_method, TLS_client_method, +SSLv23_method, SSLv23_server_method, SSLv23_client_method, DTLS_method, +DTLS_server_method, DTLS_client_method, DTLSv1_method, DTLSv1_server_method, +DTLSv1_client_method, DTLSv1_2_method, DTLSv1_2_server_method, +DTLSv1_2_client_method +\&\- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_CTX *SSL_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq, +\& const SSL_METHOD *method); +\& SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); +\& int SSL_CTX_up_ref(SSL_CTX *ctx); +\& +\& const SSL_METHOD *TLS_method(void); +\& const SSL_METHOD *TLS_server_method(void); +\& const SSL_METHOD *TLS_client_method(void); +\& +\& const SSL_METHOD *SSLv23_method(void); +\& const SSL_METHOD *SSLv23_server_method(void); +\& const SSL_METHOD *SSLv23_client_method(void); +\& +\& #ifndef OPENSSL_NO_SSL3_METHOD +\& const SSL_METHOD *SSLv3_method(void); +\& const SSL_METHOD *SSLv3_server_method(void); +\& const SSL_METHOD *SSLv3_client_method(void); +\& #endif +\& +\& #ifndef OPENSSL_NO_TLS1_METHOD +\& const SSL_METHOD *TLSv1_method(void); +\& const SSL_METHOD *TLSv1_server_method(void); +\& const SSL_METHOD *TLSv1_client_method(void); +\& #endif +\& +\& #ifndef OPENSSL_NO_TLS1_1_METHOD +\& const SSL_METHOD *TLSv1_1_method(void); +\& const SSL_METHOD *TLSv1_1_server_method(void); +\& const SSL_METHOD *TLSv1_1_client_method(void); +\& #endif +\& +\& #ifndef OPENSSL_NO_TLS1_2_METHOD +\& const SSL_METHOD *TLSv1_2_method(void); +\& const SSL_METHOD *TLSv1_2_server_method(void); +\& const SSL_METHOD *TLSv1_2_client_method(void); +\& #endif +\& +\& const SSL_METHOD *DTLS_method(void); +\& const SSL_METHOD *DTLS_server_method(void); +\& const SSL_METHOD *DTLS_client_method(void); +\& +\& #ifndef OPENSSL_NO_DTLS1_METHOD +\& const SSL_METHOD *DTLSv1_method(void); +\& const SSL_METHOD *DTLSv1_server_method(void); +\& const SSL_METHOD *DTLSv1_client_method(void); +\& #endif +\& +\& #ifndef OPENSSL_NO_DTLS1_2_METHOD +\& const SSL_METHOD *DTLSv1_2_method(void); +\& const SSL_METHOD *DTLSv1_2_server_method(void); +\& const SSL_METHOD *DTLSv1_2_client_method(void); +\& #endif +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_new_ex()\fR creates a new \fBSSL_CTX\fR object, which holds various +configuration and data relevant to SSL/TLS or DTLS session establishment. +These are later inherited by the \fBSSL\fR object representing an active session. +The \fImethod\fR parameter specifies whether the context will be used for the +client or server side or both \- for details see the "NOTES" below. +The library context \fIlibctx\fR (see \fBOSSL_LIB_CTX\fR\|(3)) is used to provide the +cryptographic algorithms needed for the session. Any cryptographic algorithms +that are used by any \fBSSL\fR objects created from this \fBSSL_CTX\fR will be fetched +from the \fIlibctx\fR using the property query string \fIpropq\fR (see +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7). Either or both the \fIlibctx\fR or \fIpropq\fR +parameters may be NULL. +.PP +\&\fBSSL_CTX_new()\fR does the same as \fBSSL_CTX_new_ex()\fR except that the default +library context is used and no property query string is specified. +.PP +An \fBSSL_CTX\fR object is reference counted. Creating an \fBSSL_CTX\fR object for the +first time increments the reference count. Freeing the \fBSSL_CTX\fR (using +SSL_CTX_free) decrements it. When the reference count drops to zero, any memory +or resources allocated to the \fBSSL_CTX\fR object are freed. \fBSSL_CTX_up_ref()\fR +increments the reference count for an existing \fBSSL_CTX\fR structure. +.PP +An \fBSSL_CTX\fR object should not be changed after it is used to create any \fBSSL\fR +objects or from multiple threads concurrently, since the implementation does not +provide serialization of access for these cases. +.SH NOTES +.IX Header "NOTES" +On session establishment, by default, no peer credentials verification is done. +This must be explicitly requested, typically using \fBSSL_CTX_set_verify\fR\|(3). +For verifying peer certificates many options can be set using various functions +such as \fBSSL_CTX_load_verify_locations\fR\|(3) and \fBSSL_CTX_set1_param\fR\|(3). +.PP +The SSL/(D)TLS implementation uses the \fBX509_STORE_CTX_set_default\fR\|(3) +function to prepare checks for \fBX509_PURPOSE_SSL_SERVER\fR on the client side +and \fBX509_PURPOSE_SSL_CLIENT\fR on the server side. +The \fBX509_VERIFY_PARAM_set_purpose\fR\|(3) function can be used, also in conjunction +with \fBSSL_CTX_get0_param\fR\|(3), to override the default purpose of the session. +.PP +The SSL_CTX object uses \fImethod\fR as the connection method. +Three method variants are available: a generic method (for either client or +server use), a server\-only method, and a client\-only method. +.PP +The \fImethod\fR parameter of \fBSSL_CTX_new_ex()\fR and \fBSSL_CTX_new()\fR +can be one of the following: +.IP "\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR" 4 +.IX Item "TLS_method(), TLS_server_method(), TLS_client_method()" +These are the general\-purpose \fIversion\-flexible\fR SSL/TLS methods. +The actual protocol version used will be negotiated to the highest version +mutually supported by the client and the server. +The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. +Applications should use these methods, and avoid the version\-specific +methods described below, which are deprecated. +.IP "\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR, \fBSSLv23_client_method()\fR" 4 +.IX Item "SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()" +These functions do not exist anymore, they have been renamed to +\&\fBTLS_method()\fR, \fBTLS_server_method()\fR and \fBTLS_client_method()\fR respectively. +Currently, the old function calls are renamed to the corresponding new +ones by preprocessor macros, to ensure that existing code which uses the +old function names still compiles. However, using the old function names +is deprecated and new code should call the new functions instead. +.IP "\fBTLSv1_2_method()\fR, \fBTLSv1_2_server_method()\fR, \fBTLSv1_2_client_method()\fR" 4 +.IX Item "TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()" +A TLS/SSL connection established with these methods will only understand the +TLSv1.2 protocol. These methods are deprecated. +.IP "\fBTLSv1_1_method()\fR, \fBTLSv1_1_server_method()\fR, \fBTLSv1_1_client_method()\fR" 4 +.IX Item "TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()" +A TLS/SSL connection established with these methods will only understand the +TLSv1.1 protocol. These methods are deprecated. +.IP "\fBTLSv1_method()\fR, \fBTLSv1_server_method()\fR, \fBTLSv1_client_method()\fR" 4 +.IX Item "TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()" +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. These methods are deprecated. +.IP "\fBSSLv3_method()\fR, \fBSSLv3_server_method()\fR, \fBSSLv3_client_method()\fR" 4 +.IX Item "SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()" +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. +The SSLv3 protocol is deprecated and should not be used. +.IP "\fBDTLS_method()\fR, \fBDTLS_server_method()\fR, \fBDTLS_client_method()\fR" 4 +.IX Item "DTLS_method(), DTLS_server_method(), DTLS_client_method()" +These are the version\-flexible DTLS methods. +Currently supported protocols are DTLS 1.0 and DTLS 1.2. +.IP "\fBDTLSv1_2_method()\fR, \fBDTLSv1_2_server_method()\fR, \fBDTLSv1_2_client_method()\fR" 4 +.IX Item "DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()" +These are the version\-specific methods for DTLSv1.2. +These methods are deprecated. +.IP "\fBDTLSv1_method()\fR, \fBDTLSv1_server_method()\fR, \fBDTLSv1_client_method()\fR" 4 +.IX Item "DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()" +These are the version\-specific methods for DTLSv1. +These methods are deprecated. +.PP +\&\fBSSL_CTX_new()\fR initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates and the options to their default values. +.PP +\&\fBTLS_method()\fR, \fBTLS_server_method()\fR, \fBTLS_client_method()\fR, \fBDTLS_method()\fR, +\&\fBDTLS_server_method()\fR and \fBDTLS_client_method()\fR are the \fIversion\-flexible\fR +methods. +All other methods only support one specific protocol version. +Use the \fIversion\-flexible\fR methods instead of the version specific methods. +.PP +If you want to limit the supported protocols for the version flexible +methods you can use \fBSSL_CTX_set_min_proto_version\fR\|(3), +\&\fBSSL_set_min_proto_version\fR\|(3), \fBSSL_CTX_set_max_proto_version\fR\|(3) and +\&\fBSSL_set_max_proto_version\fR\|(3) functions. +Using these functions it is possible to choose e.g. \fBTLS_server_method()\fR +and be able to negotiate with all possible clients, but to only +allow newer protocols like TLS 1.0, TLS 1.1, TLS 1.2 or TLS 1.3. +.PP +The list of protocols available can also be limited using the +\&\fBSSL_OP_NO_SSLv3\fR, \fBSSL_OP_NO_TLSv1\fR, \fBSSL_OP_NO_TLSv1_1\fR, +\&\fBSSL_OP_NO_TLSv1_3\fR, \fBSSL_OP_NO_TLSv1_2\fR and \fBSSL_OP_NO_TLSv1_3\fR +options of the +\&\fBSSL_CTX_set_options\fR\|(3) or \fBSSL_set_options\fR\|(3) functions, but this approach +is not recommended. Clients should avoid creating "holes" in the set of +protocols they support. When disabling a protocol, make sure that you also +disable either all previous or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling \fIall\fR +previous protocol versions, the effect is to also disable all subsequent +protocol versions. +.PP +The SSLv3 protocol is deprecated and should generally not be used. +Applications should typically use \fBSSL_CTX_set_min_proto_version\fR\|(3) to set +the minimum protocol to at least \fBTLS1_VERSION\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +The creation of a new SSL_CTX object failed. Check the error stack to find out +the reason. +.IP "Pointer to an SSL_CTX object" 4 +.IX Item "Pointer to an SSL_CTX object" +The return value points to an allocated SSL_CTX object. +.Sp +\&\fBSSL_CTX_up_ref()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_set_options\fR\|(3), \fBSSL_CTX_free\fR\|(3), \fBX509_STORE_CTX_set_default\fR\|(3), +\&\fBSSL_CTX_set_verify\fR\|(3), \fBSSL_CTX_set1_param\fR\|(3), \fBSSL_CTX_get0_param\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3), +\&\fBSSL_CTX_set_min_proto_version\fR\|(3), \fBssl\fR\|(7), \fBSSL_set_connect_state\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Support for SSLv2 and the corresponding \fBSSLv2_method()\fR, +\&\fBSSLv2_server_method()\fR and \fBSSLv2_client_method()\fR functions where +removed in OpenSSL 1.1.0. +.PP +\&\fBSSLv23_method()\fR, \fBSSLv23_server_method()\fR and \fBSSLv23_client_method()\fR +were deprecated and the preferred \fBTLS_method()\fR, \fBTLS_server_method()\fR +and \fBTLS_client_method()\fR functions were added in OpenSSL 1.1.0. +.PP +All version\-specific methods were deprecated in OpenSSL 1.1.0. +.PP +\&\fBSSL_CTX_new_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_sess_number.3 b/static/netbsd/man3/SSL_CTX_sess_number.3 new file mode 100644 index 00000000..afe1cc8f --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_sess_number.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: SSL_CTX_sess_number.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_sess_number 3" +.TH SSL_CTX_sess_number 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full \- obtain session cache statistics +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_sess_number(SSL_CTX *ctx); +\& long SSL_CTX_sess_connect(SSL_CTX *ctx); +\& long SSL_CTX_sess_connect_good(SSL_CTX *ctx); +\& long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx); +\& long SSL_CTX_sess_accept(SSL_CTX *ctx); +\& long SSL_CTX_sess_accept_good(SSL_CTX *ctx); +\& long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx); +\& long SSL_CTX_sess_hits(SSL_CTX *ctx); +\& long SSL_CTX_sess_cb_hits(SSL_CTX *ctx); +\& long SSL_CTX_sess_misses(SSL_CTX *ctx); +\& long SSL_CTX_sess_timeouts(SSL_CTX *ctx); +\& long SSL_CTX_sess_cache_full(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_sess_number()\fR returns the current number of sessions in the internal +session cache. +.PP +\&\fBSSL_CTX_sess_connect()\fR returns the number of started SSL/TLS handshakes in +client mode. +.PP +\&\fBSSL_CTX_sess_connect_good()\fR returns the number of successfully established +SSL/TLS sessions in client mode. +.PP +\&\fBSSL_CTX_sess_connect_renegotiate()\fR returns the number of started renegotiations +in client mode. +.PP +\&\fBSSL_CTX_sess_accept()\fR returns the number of started SSL/TLS handshakes in +server mode. +.PP +\&\fBSSL_CTX_sess_accept_good()\fR returns the number of successfully established +SSL/TLS sessions in server mode. +.PP +\&\fBSSL_CTX_sess_accept_renegotiate()\fR returns the number of started renegotiations +in server mode. +.PP +\&\fBSSL_CTX_sess_hits()\fR returns the number of successfully reused sessions. +In client mode a session set with \fBSSL_set_session\fR\|(3) +successfully reused is counted as a hit. In server mode a session successfully +retrieved from internal or external cache is counted as a hit. +.PP +\&\fBSSL_CTX_sess_cb_hits()\fR returns the number of successfully retrieved sessions +from the external session cache in server mode. +.PP +\&\fBSSL_CTX_sess_misses()\fR returns the number of sessions proposed by clients +that were not found in the internal session cache in server mode. +.PP +\&\fBSSL_CTX_sess_timeouts()\fR returns the number of sessions proposed by clients +and either found in the internal or external session cache in server mode, + but that were invalid due to timeout. These sessions are not included in +the \fBSSL_CTX_sess_hits()\fR count. +.PP +\&\fBSSL_CTX_sess_cache_full()\fR returns the number of sessions that were removed +because the maximum session cache size was exceeded. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions return the values indicated in the DESCRIPTION section. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3) +\&\fBSSL_CTX_sess_set_cache_size\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_sess_set_cache_size.3 b/static/netbsd/man3/SSL_CTX_sess_set_cache_size.3 new file mode 100644 index 00000000..c6f8c38b --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_sess_set_cache_size.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: SSL_CTX_sess_set_cache_size.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_sess_set_cache_size 3" +.TH SSL_CTX_sess_set_cache_size 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size \- manipulate session cache size +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); +\& long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_sess_set_cache_size()\fR sets the size of the internal session cache +of context \fBctx\fR to \fBt\fR. +This value is a hint and not an absolute; see the notes below. +.PP +\&\fBSSL_CTX_sess_get_cache_size()\fR returns the currently valid session cache size. +.SH NOTES +.IX Header "NOTES" +The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, +currently 1024*20, so that up to 20000 sessions can be held. This size +can be modified using the \fBSSL_CTX_sess_set_cache_size()\fR call. A special +case is the size 0, which is used for unlimited size. +.PP +If adding the session makes the cache exceed its size, then unused +sessions are dropped from the end of the cache. +Cache space may also be reclaimed by calling +\&\fBSSL_CTX_flush_sessions\fR\|(3) to remove +expired sessions. +.PP +If the size of the session cache is reduced and more sessions are already +in the session cache, old session will be removed at the next time a +session shall be added. This removal is not synchronized with the +expiration of sessions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_sess_set_cache_size()\fR returns the previously valid size. +.PP +\&\fBSSL_CTX_sess_get_cache_size()\fR returns the currently valid size. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_CTX_sess_number\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_sess_set_get_cb.3 b/static/netbsd/man3/SSL_CTX_sess_set_get_cb.3 new file mode 100644 index 00000000..cd3fbbe8 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_sess_set_get_cb.3 @@ -0,0 +1,181 @@ +.\" $NetBSD: SSL_CTX_sess_set_get_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_sess_set_get_cb 3" +.TH SSL_CTX_sess_set_get_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb \- provide callback functions for server side external session caching +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, +\& int (*new_session_cb)(SSL *, SSL_SESSION *)); +\& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, +\& void (*remove_session_cb)(SSL_CTX *ctx, +\& SSL_SESSION *)); +\& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, +\& SSL_SESSION (*get_session_cb)(SSL *, +\& const unsigned char *, +\& int, int *)); +\& +\& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, +\& SSL_SESSION *sess); +\& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, +\& SSL_SESSION *sess); +\& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, +\& const unsigned char *data, +\& int len, int *copy); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_sess_set_new_cb()\fR sets the callback function that is +called whenever a new session was negotiated. +.PP +\&\fBSSL_CTX_sess_set_remove_cb()\fR sets the callback function that is +called whenever a session is removed by the SSL engine. For example, +this can occur because a session is considered faulty or has become obsolete +because of exceeding the timeout value. +.PP +\&\fBSSL_CTX_sess_set_get_cb()\fR sets the callback function that is called +whenever a TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3)). +(TLS server only.) +.PP +\&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR, and +\&\fBSSL_CTX_sess_get_get_cb()\fR retrieve the function pointers set by the +corresponding set callback functions. If a callback function has not been +set, the NULL pointer is returned. +.SH NOTES +.IX Header "NOTES" +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. Inside these callback +functions, session can be saved to disk or put into a database using the +\&\fBd2i_SSL_SESSION\fR\|(3) interface. +.PP +The \fBnew_session_cb()\fR is called whenever a new session has been negotiated and +session caching is enabled (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). The +\&\fBnew_session_cb()\fR is passed the \fBssl\fR connection and the nascent +ssl session \fBsess\fR. +Since sessions are reference\-counted objects, the reference count on the +session is incremented before the callback, on behalf of the application. If +the callback returns \fB0\fR, the session will be immediately removed from the +internal cache and the reference count released. If the callback returns \fB1\fR, +the application retains the reference (for an entry in the +application\-maintained "external session cache"), and is responsible for +calling \fBSSL_SESSION_free()\fR when the session reference is no longer in use. +.PP +Note that in TLSv1.3, sessions are established after the main +handshake has completed. The server decides when to send the client the session +information and this may occur some time after the end of the handshake (or not +at all). This means that applications should expect the \fBnew_session_cb()\fR +function to be invoked during the handshake (for <= TLSv1.2) or after the +handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to +be established with a single connection. In these case the \fBnew_session_cb()\fR +function will be invoked multiple times. +.PP +In TLSv1.3 it is recommended that each SSL_SESSION object is only used for +resumption once. One way of enforcing that is for applications to call +\&\fBSSL_CTX_remove_session\fR\|(3) after a session has been used. +.PP +The \fBremove_session_cb()\fR is called whenever the SSL engine removes a session +from the internal cache. This can happen when the session is removed because +it is expired or when a connection was not shutdown cleanly. It also happens +for all sessions in the internal session cache when +\&\fBSSL_CTX_free\fR\|(3) is called. The \fBremove_session_cb()\fR is passed +the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback. +.PP +The \fBget_session_cb()\fR is only called on SSL/TLS servers, and is given +the session id +proposed by the client. The \fBget_session_cb()\fR is always called, even when +session caching was disabled. The \fBget_session_cb()\fR is passed the +\&\fBssl\fR connection and the session id of length \fBlength\fR at the memory location +\&\fBdata\fR. By setting the parameter \fBcopy\fR to \fB1\fR, the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object; +setting \fBcopy\fR to \fB0\fR causes the reference count to remain unchanged. +If the \fBget_session_cb()\fR does not write to \fBcopy\fR, the reference count +is incremented and the session must be explicitly freed with +\&\fBSSL_SESSION_free\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR and \fBSSL_CTX_sess_get_get_cb()\fR +return different callback function pointers respectively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBd2i_SSL_SESSION\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3), +\&\fBSSL_CTX_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_sessions.3 b/static/netbsd/man3/SSL_CTX_sessions.3 new file mode 100644 index 00000000..8b53a693 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_sessions.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: SSL_CTX_sessions.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_sessions 3" +.TH SSL_CTX_sessions 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_sessions \- access internal session cache +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& LHASH_OF(SSL_SESSION) *SSL_CTX_sessions(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_sessions()\fR returns a pointer to the lhash databases containing the +internal session cache for \fBctx\fR. +.SH NOTES +.IX Header "NOTES" +The sessions in the internal session cache are kept in an +\&\fBLHASH\fR\|(3) type database. It is possible to directly +access this database e.g. for searching. In parallel, the sessions +form a linked list which is maintained separately from the +\&\fBLHASH\fR\|(3) operations, so that the database must not be +modified directly but by using the +\&\fBSSL_CTX_add_session\fR\|(3) family of functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_sessions()\fR returns a pointer to the lhash of \fBSSL_SESSION\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBLHASH\fR\|(3), +\&\fBSSL_CTX_add_session\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set0_CA_list.3 b/static/netbsd/man3/SSL_CTX_set0_CA_list.3 new file mode 100644 index 00000000..f3da40ad --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set0_CA_list.3 @@ -0,0 +1,247 @@ +.\" $NetBSD: SSL_CTX_set0_CA_list.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set0_CA_list 3" +.TH SSL_CTX_set0_CA_list 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_client_CA_list, +SSL_set_client_CA_list, +SSL_get_client_CA_list, +SSL_CTX_get_client_CA_list, +SSL_CTX_add_client_CA, +SSL_add_client_CA, +SSL_set0_CA_list, +SSL_CTX_set0_CA_list, +SSL_get0_CA_list, +SSL_CTX_get0_CA_list, +SSL_add1_to_CA_list, +SSL_CTX_add1_to_CA_list, +SSL_get0_peer_CA_list +\&\- get or set CA list +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); +\& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); +\& STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); +\& STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); +\& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); +\& int SSL_add_client_CA(SSL *ssl, X509 *cacert); +\& +\& void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list); +\& void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list); +\& const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx); +\& const STACK_OF(X509_NAME) *SSL_get0_CA_list(const SSL *s); +\& int SSL_CTX_add1_to_CA_list(SSL_CTX *ctx, const X509 *x); +\& int SSL_add1_to_CA_list(SSL *ssl, const X509 *x); +\& +\& const STACK_OF(X509_NAME) *SSL_get0_peer_CA_list(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described here set and manage the list of CA names that are sent +between two communicating peers. +.PP +For TLS versions 1.2 and earlier the list of CA names is only sent from the +server to the client when requesting a client certificate. So any list of CA +names set is never sent from client to server and the list of CA names retrieved +by \fBSSL_get0_peer_CA_list()\fR is always \fBNULL\fR. +.PP +For TLS 1.3 the list of CA names is sent using the \fBcertificate_authorities\fR +extension and may be sent by a client (in the ClientHello message) or by +a server (when requesting a certificate). +.PP +In most cases it is not necessary to set CA names on the client side. The list +of CA names that are acceptable to the client will be sent in plaintext to the +server. This has privacy implications and may also have performance implications +if the list is large. This optional capability was introduced as part of TLSv1.3 +and therefore setting CA names on the client side will have no impact if that +protocol version has been disabled. Most servers do not need this and so this +should be avoided unless required. +.PP +The "client CA list" functions below only have an effect when called on the +server side. +.PP +\&\fBSSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when +requesting a client certificate for \fBctx\fR. Ownership of \fBlist\fR is transferred +to \fBctx\fR and it should not be freed by the caller. +.PP +\&\fBSSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when +requesting a client certificate for the chosen \fBssl\fR, overriding the +setting valid for \fBssl\fR\*(Aqs SSL_CTX object. Ownership of \fBlist\fR is transferred +to \fBs\fR and it should not be freed by the caller. +.PP +\&\fBSSL_CTX_get_client_CA_list()\fR returns the list of client CAs explicitly set for +\&\fBctx\fR using \fBSSL_CTX_set_client_CA_list()\fR. The returned list should not be freed +by the caller. +.PP +\&\fBSSL_get_client_CA_list()\fR returns the list of client CAs explicitly +set for \fBssl\fR using \fBSSL_set_client_CA_list()\fR or \fBssl\fR\*(Aqs SSL_CTX object with +\&\fBSSL_CTX_set_client_CA_list()\fR, when in server mode. In client mode, +SSL_get_client_CA_list returns the list of client CAs sent from the server, if +any. The returned list should not be freed by the caller. +.PP +\&\fBSSL_CTX_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the +list of CAs sent to the client when requesting a client certificate for +\&\fBctx\fR. +.PP +\&\fBSSL_add_client_CA()\fR adds the CA name extracted from \fBcacert\fR to the +list of CAs sent to the client when requesting a client certificate for +the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR\*(Aqs SSL_CTX object. +.PP +\&\fBSSL_get0_peer_CA_list()\fR retrieves the list of CA names (if any) the peer +has sent. This can be called on either the server or the client side. The +returned list should not be freed by the caller. +.PP +The "generic CA list" functions below are very similar to the "client CA +list" functions except that they have an effect on both the server and client +sides. The lists of CA names managed are separate \- so you cannot (for example) +set CA names using the "client CA list" functions and then get them using the +"generic CA list" functions. Where a mix of the two types of functions has been +used on the server side then the "client CA list" functions take precedence. +Typically, on the server side, the "client CA list " functions should be used in +preference. As noted above in most cases it is not necessary to set CA names on +the client side. +.PP +\&\fBSSL_CTX_set0_CA_list()\fR sets the list of CAs to be sent to the peer to +\&\fBname_list\fR. Ownership of \fBname_list\fR is transferred to \fBctx\fR and +it should not be freed by the caller. +.PP +\&\fBSSL_set0_CA_list()\fR sets the list of CAs to be sent to the peer to \fBname_list\fR +overriding any list set in the parent \fBSSL_CTX\fR of \fBs\fR. Ownership of +\&\fBname_list\fR is transferred to \fBs\fR and it should not be freed by the caller. +.PP +\&\fBSSL_CTX_get0_CA_list()\fR retrieves any previously set list of CAs set for +\&\fBctx\fR. The returned list should not be freed by the caller. +.PP +\&\fBSSL_get0_CA_list()\fR retrieves any previously set list of CAs set for +\&\fBs\fR or if none are set the list from the parent \fBSSL_CTX\fR is retrieved. The +returned list should not be freed by the caller. +.PP +\&\fBSSL_CTX_add1_to_CA_list()\fR appends the CA subject name extracted from \fBx\fR to the +list of CAs sent to peer for \fBctx\fR. +.PP +\&\fBSSL_add1_to_CA_list()\fR appends the CA subject name extracted from \fBx\fR to the +list of CAs sent to the peer for \fBs\fR, overriding the setting in the parent +\&\fBSSL_CTX\fR. +.SH NOTES +.IX Header "NOTES" +When a TLS/SSL server requests a client certificate (see +\&\fBSSL_CTX_set_verify\|(3)\fR), it sends a list of CAs, for which it will accept +certificates, to the client. +.PP +This list must explicitly be set using \fBSSL_CTX_set_client_CA_list()\fR or +\&\fBSSL_CTX_set0_CA_list()\fR for \fBctx\fR and \fBSSL_set_client_CA_list()\fR or +\&\fBSSL_set0_CA_list()\fR for the specific \fBssl\fR. The list specified +overrides the previous setting. The CAs listed do not become trusted (\fBlist\fR +only contains the names, not the complete certificates); use +\&\fBSSL_CTX_load_verify_locations\fR\|(3) to additionally load them for verification. +.PP +If the list of acceptable CAs is compiled in a file, the +\&\fBSSL_load_client_CA_file\fR\|(3) function can be used to help to import the +necessary data. +.PP +\&\fBSSL_CTX_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR, \fBSSL_add_client_CA()\fR and +\&\fBSSL_add1_to_CA_list()\fR can be used to add additional items the list of CAs. If no +list was specified before using \fBSSL_CTX_set_client_CA_list()\fR, +\&\fBSSL_CTX_set0_CA_list()\fR, \fBSSL_set_client_CA_list()\fR or \fBSSL_set0_CA_list()\fR, a +new CA list for \fBctx\fR or \fBssl\fR (as appropriate) is opened. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR, +\&\fBSSL_CTX_set_client_CA_list()\fR, \fBSSL_set_client_CA_list()\fR, \fBSSL_CTX_set0_CA_list()\fR +and \fBSSL_set0_CA_list()\fR do not return a value. +.PP +\&\fBSSL_CTX_get_client_CA_list()\fR, \fBSSL_get_client_CA_list()\fR, \fBSSL_CTX_get0_CA_list()\fR +and \fBSSL_get0_CA_list()\fR return a stack of CA names or \fBNULL\fR is no CA names are +set. +.PP +\&\fBSSL_CTX_add_client_CA()\fR,\fBSSL_add_client_CA()\fR, \fBSSL_CTX_add1_to_CA_list()\fR and +\&\fBSSL_add1_to_CA_list()\fR return 1 for success and 0 for failure. +.PP +\&\fBSSL_get0_peer_CA_list()\fR returns a stack of CA names sent by the peer or +\&\fBNULL\fR or an empty stack if no list was sent. +.SH EXAMPLES +.IX Header "EXAMPLES" +Scan all certificates in \fBCAfile\fR and list them as acceptable CAs: +.PP +.Vb 1 +\& SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_load_client_CA_file\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set1_cert_comp_preference.3 b/static/netbsd/man3/SSL_CTX_set1_cert_comp_preference.3 new file mode 100644 index 00000000..d33a0191 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set1_cert_comp_preference.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: SSL_CTX_set1_cert_comp_preference.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set1_cert_comp_preference 3" +.TH SSL_CTX_set1_cert_comp_preference 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set1_cert_comp_preference, +SSL_set1_cert_comp_preference, +SSL_CTX_compress_certs, +SSL_compress_certs, +SSL_CTX_get1_compressed_cert, +SSL_get1_compressed_cert, +SSL_CTX_set1_compressed_cert, +SSL_set1_compressed_cert \- Certificate compression functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set1_cert_comp_preference(SSL_CTX *ctx, int *algs, size_t len); +\& int SSL_set1_cert_comp_preference(SSL *ssl, int *algs, size_t len); +\& +\& int SSL_CTX_compress_certs(SSL_CTX *ctx, int alg); +\& int SSL_compress_certs(SSL *ssl, int alg); +\& +\& size_t SSL_CTX_get1_compressed_cert(SSL_CTX *ctx, int alg, unsigned char **data, +\& size_t *orig_len); +\& size_t SSL_get1_compressed_cert(SSL *ssl, int alg, unsigned char **data, +\& size_t *orig_len); +\& +\& int SSL_CTX_set1_compressed_cert(SSL_CTX *ctx, int alg, +\& unsigned char *comp_data, +\& size_t comp_length, size_t orig_length); +\& int SSL_set1_compressed_cert(SSL *ssl, int alg, unsigned char *comp_data, +\& size_t comp_length, size_t orig_length); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions control the certificate compression feature. Certificate +compression is only available for TLSv1.3 as defined in RFC8879. +.PP +\&\fBSSL_CTX_set1_cert_comp_preference()\fR and \fBSSL_set1_cert_comp_preference()\fR are used +to specify the preferred compression algorithms. The \fBalgs\fR argument is an array +of algorithms, and \fBlength\fR is number of elements in the \fBalgs\fR array. Only +those algorithms enabled in the library will be accepted in \fBalgs\fR, unknown +algorithms in \fBalgs\fR are ignored. On an error, the preference order is left +unmodified. +.PP +The following compression algorithms (\fBalg\fR arguments) may be used: +.IP \(bu 4 +TLSEXT_comp_cert_brotli +.IP \(bu 4 +TLSEXT_comp_cert_zlib +.IP \(bu 4 +TLSEXT_comp_cert_zstd +.PP +The above is also the default preference order. If a preference order is not +specified, then the default preference order is sent to the peer and the +received peer\*(Aqs preference order will be used when compressing a certificate. +Otherwise, the configured preference order is sent to the peer and is used +to filter the peer\*(Aqs preference order. +.PP +\&\fBSSL_CTX_compress_certs()\fR and \fBSSL_compress_certs()\fR are used to pre\-compress all +the configured certificates on an SSL_CTX/SSL object with algorithm \fBalg\fR. If +\&\fBalg\fR is 0, then the certificates are compressed with the algorithms specified +in the preference list. Calling these functions on a client SSL_CTX/SSL object +will result in an error, as only server certificates may be pre\-compressed. +.PP +\&\fBSSL_CTX_get1_compressed_cert()\fR and \fBSSL_get1_compressed_cert()\fR are used to get +the pre\-compressed certificate most recently set that may be stored for later +use. Calling these functions on a client SSL_CTX/SSL object will result in an +error, as only server certificates may be pre\-compressed. The \fBdata\fR and +\&\fBorig_len\fR arguments are required. +.PP +The compressed certificate data may be passed to \fBSSL_CTX_set1_compressed_cert()\fR +or \fBSSL_set1_compressed_cert()\fR to provide a pre\-compressed version of the +most recently set certificate. This pre\-compressed certificate can only be used +by a server. +.SH NOTES +.IX Header "NOTES" +Each side of the connection sends their compression algorithm preference list +to their peer indicating compressed certificate support. The received preference +list is filtered by the configured preference list (i.e. the intersection is +saved). As the default list includes all the enabled algorithms, not specifying +a preference will allow any enabled algorithm by the peer. The filtered peer\*(Aqs +preference order is used to determine what algorithm to use when sending a +compressed certificate. +.PP +Only server certificates may be pre\-compressed. Calling any of these functions +(except \fBSSL_CTX_set1_cert_comp_preference()\fR/\fBSSL_set1_cert_comp_preference()\fR) +on a client SSL_CTX/SSL object will return an error. Client certificates are +compressed on\-demand as unique context data from the server is compressed along +with the certificate. +.PP +For \fBSSL_CTX_set1_cert_comp_preference()\fR and \fBSSL_set1_cert_comp_preference()\fR +the \fBlen\fR argument is the size of the \fBalgs\fR argument in bytes. +.PP +The compressed certificate returned by \fBSSL_CTX_get1_compressed_cert()\fR and +\&\fBSSL_get1_compressed_cert()\fR is the last certificate set on the SSL_CTX/SSL object. +The certificate is copied by the function and the caller must free \fB*data\fR via +\&\fBOPENSSL_free()\fR. +.PP +The compressed certificate data set by \fBSSL_CTX_set1_compressed_cert()\fR and +\&\fBSSL_set1_compressed_cert()\fR is copied into the SSL_CTX/SSL object. +.PP +\&\fBSSL_CTX_compress_certs()\fR and \fBSSL_compress_certs()\fR return an error under the +following conditions: +.IP \(bu 4 +If no certificates have been configured. +.IP \(bu 4 +If the specified algorithm \fBalg\fR is not enabled. +.IP \(bu 4 +If \fBalg\fR is 0 and no compression algorithms are enabled. +.PP +Sending compressed certificates may be disabled on a connection via the +SSL_OP_NO_TX_CERTIFICATE_COMPRESSION option. Receiving compressed certificates +may be disabled on a connection via the SSL_OP_NO_RX_CERTIFICATE_COMPRESSION +option. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set1_cert_comp_preference()\fR, +\&\fBSSL_set1_cert_comp_preference()\fR, +\&\fBSSL_CTX_compress_certs()\fR, +\&\fBSSL_compress_certs()\fR, +\&\fBSSL_CTX_set1_compressed_cert()\fR, and +\&\fBSSL_set1_compressed_cert()\fR +return 1 for success and 0 on error. +.PP +\&\fBSSL_CTX_get1_compressed_cert()\fR and +\&\fBSSL_get1_compressed_cert()\fR +return the length of the allocated memory on success and 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_CTX_use_certificate\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set1_curves.3 b/static/netbsd/man3/SSL_CTX_set1_curves.3 new file mode 100644 index 00000000..7c2101fc --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set1_curves.3 @@ -0,0 +1,470 @@ +.\" $NetBSD: SSL_CTX_set1_curves.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set1_curves 3" +.TH SSL_CTX_set1_curves 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups, +SSL_set1_groups_list, SSL_get1_groups, SSL_get0_iana_groups, +SSL_get_shared_group, SSL_get_negotiated_group, SSL_CTX_set1_curves, +SSL_CTX_set1_curves_list, SSL_set1_curves, SSL_set1_curves_list, +SSL_get1_curves, SSL_get_shared_curve, SSL_CTX_get0_implemented_groups +\&\- EC supported curve functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set1_groups(SSL_CTX *ctx, int *glist, int glistlen); +\& int SSL_CTX_set1_groups_list(SSL_CTX *ctx, char *list); +\& +\& int SSL_set1_groups(SSL *ssl, int *glist, int glistlen); +\& int SSL_set1_groups_list(SSL *ssl, char *list); +\& +\& int SSL_get1_groups(SSL *ssl, int *groups); +\& int SSL_get0_iana_groups(SSL *ssl, uint16_t **out); +\& int SSL_get_shared_group(SSL *s, int n); +\& int SSL_get_negotiated_group(SSL *s); +\& +\& int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); +\& int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); +\& +\& int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); +\& int SSL_set1_curves_list(SSL *ssl, char *list); +\& +\& int SSL_get1_curves(SSL *ssl, int *curves); +\& int SSL_get_shared_curve(SSL *s, int n); +\& +\& int SSL_CTX_get0_implemented_groups(SSL_CTX *ctx, int all, +\& STACK_OF(OPENSSL_CSTRING) *names); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For all of the functions below that set the supported groups there must be at +least one group in the list. A number of these functions identify groups via a +unique integer \fBNID\fR value. However, support for some groups may be added by +external providers. In this case there will be no \fBNID\fR assigned for the group. +When setting such groups applications should use the "list" form of these +functions (i.e. \fBSSL_CTX_set1_groups_list()\fR and \fBSSL_set1_groups_list()\fR). +.PP +\&\fBSSL_CTX_set1_groups()\fR sets the supported groups for \fBctx\fR to \fBglistlen\fR +groups in the array \fBglist\fR. The array consist of all \fBNIDs\fR of supported groups. +The supported groups for \fBTLSv1.3\fR include: +\&\fBNID_X9_62_prime256v1\fR, +\&\fBNID_secp384r1\fR, +\&\fBNID_secp521r1\fR, +\&\fBNID_X25519\fR, +\&\fBNID_X448\fR, +\&\fBNID_brainpoolP256r1tls13\fR, +\&\fBNID_brainpoolP384r1tls13\fR, +\&\fBNID_brainpoolP512r1tls13\fR, +\&\fBNID_ffdhe2048\fR, +\&\fBNID_ffdhe3072\fR, +\&\fBNID_ffdhe4096\fR, +\&\fBNID_ffdhe6144\fR, and +\&\fBNID_ffdhe8192\fR. +OpenSSL will use this array in different ways based on the TLS version, and +whether the groups are used in a client or server. +.PP +For a TLS client, the groups are used directly in the supported groups +extension. The extension\*(Aqs preference order, to be evaluated by the server, is +determined by the order of the elements in the array. +.PP +For a TLS 1.2 server, the groups determine the selected group. If +\&\fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR is set, the order of the elements in the +array determines the selected group. Otherwise, the order is ignored and the +client\*(Aqs order determines the selection. +.PP +For a TLS 1.3 server, the groups determine the selected group, but selection is +more complex. +A TLS 1.3 client sends both a group list and predicted keyshares for a subset +of groups. +A server choosing a group outside the client\*(Aqs predicted subset incurs an extra +roundtrip. +However, in some situations, the most preferred group may not be predicted. +.PP +When groups are specified via \fBSSL_CTX_set1_groups()\fR as a list of \fBNID\fR +values, OpenSSL considers all supported groups in \fIclist\fR to be comparable in +security and prioritises avoiding roundtrips above either client or server +preference order. +If an application uses an external provider to extend OpenSSL with, e.g., a +post\-quantum algorithm, this behavior may allow a network attacker to downgrade +connections to a weaker algorithm. +It is therefore recommended to use \fBSSL_CTX_set1_groups_list()\fR instead, making +it possible to specify group tuples as described below. +.PP +\&\fBSSL_CTX_set1_groups_list()\fR sets the supported groups for \fBctx\fR to +string \fIlist\fR. In contrast to \fBSSL_CTX_set1_groups()\fR, the names of the +groups, rather than their \fBNIDs\fR, are used. +.PP +The commands below list the available groups for TLS 1.2 and TLS 1.3, +respectively: +.PP +.Vb 2 +\& $ openssl list \-tls1_2 \-tls\-groups +\& $ openssl list \-tls1_3 \-tls\-groups +.Ve +.PP +Each group can be either the \fBNIST\fR name (e.g. \fBP\-256\fR), some other commonly +used name where applicable (e.g. \fBX25519\fR, \fBffdhe2048\fR) or an OpenSSL OID name +(e.g. \fBprime256v1\fR). +Group names are case\-insensitive in OpenSSL 3.5 and later. +The preferred group names are those defined by +IANA . +.PP +The \fIlist\fR can be used to define several group tuples of comparable security +levels, and can specify which predicted key shares should be sent by a client. +Group tuples are used by OpenSSL TLS servers to decide whether to request a +stronger keyshare than those predicted by sending a Hello Retry Request +(\fBHRR\fR) even if some of the predicted groups are supported. +OpenSSL clients ignore tuple boundaries, and pay attenion only to the overall +order of \fIlist\fR elements and which groups are selected as predicted keyshares +as described below. +.PP +The specified list elements can optionally be ignored if not implemented +(listing unknown groups otherwise results in error). +It is also possible to specify the built\-in default set of groups, and to +explicitly remove a group from that list. +.PP +In its simplest legacy form, the string \fIlist\fR is just a colon separated list +of group names, for example "P\-521:P\-384:P\-256:X25519:ffdhe2048". +The first group listed will in this case be used as the sole predicted +\&\fBkey_share\fR sent by a client in a TLSv1.3 \fBClientHello\fR. +The list should be in order of preference with the most preferred group first. +.PP +A more expressive syntax supports definition of group tuples of comparable +security by separating them from each other with \f(CW\*(C`/\*(C'\fR characters. +.PP +The predicted keyshares to be sent by clients can be explicitly specified by +adding a \f(CW\*(C`*\*(C'\fR prefix to the associated group name. +These \f(CW\*(C`*\*(C'\fR prefixes are ignored by servers. +.PP +If a group name is prefixed with the \f(CW\*(C`?\*(C'\fR character, it will be ignored if an +implementation is missing. +Otherwise, listing an unknown group name will cause a failure to parse the +\&\fIlist\fR. +Note that whether a group is known or not may depend on the OpenSSL version, +how OpenSSL was compiled and/or which providers are loaded. +Make sure you have the correct spelling of the group name and when in doubt +prefix it with a \f(CW\*(C`?\*(C'\fR to handle configurations in which it might nevertheless +be unknown. +.PP +If a group name is prefixed with the \f(CW\*(C`\-\*(C'\fR character, it will be removed from +the list of groups specified up to that point. +It can be added again if specified later. +Removal of groups that have not been included earlier in the list is silently +ignored. +.PP +The pseudo group name \f(CW\*(C`DEFAULT\*(C'\fR can be used to select the OpenSSL built\-in +default list of groups. +Prepending one or more groups to \f(CW\*(C`DEFAULT\*(C'\fR using only \f(CW\*(C`:\*(C'\fR separators prepends those +groups to the built\-in default list\*(Aqs first tuple. +Additional tuples can be prepended by use of the \f(CW\*(C`/\*(C'\fR separator. +Appending a set of groups to \f(CW\*(C`DEFAULT\*(C'\fR using only \f(CW\*(C`:\*(C'\fR separators appends those +groups to the built\-in default list\*(Aqs last tuple. +Additional tuples can be appended by use of the \f(CW\*(C`/\*(C'\fR separator. +.PP +The \fBDEFAULT\fR list selects \fBX25519MLKEM768\fR as one of the predicted keyshares. +In rare cases this can lead to failures or timeouts because the resulting +larger TLS Client Hello message may no longer fit in a single TCP segment and +firewall software may erroneously disrupt the TLS handshake. +If this is an issue or concern, prepending \f(CW\*(C`?X25519MLKEM768:\*(C'\fR without a \f(CW\*(C`*\*(C'\fR +prefix leads to its occurrence in the default list to be ignored as a duplicate, +and along with that also the keyshare prediction. +The group will then only be selected by servers that specifically expect it, +after a Hello Retry Request (HRR). +Servers that specifically prefer \fBX25519MLKEM768\fR, are much less likely to be +found behind problematic firewalls. +.PP +The following string \fIlist\fR for example defines three tuples when used on the +server\-side, and triggers the generation of three key shares when used on the +client\-side: P\-521:*P\-256/*P\-384/*X25519:P\-384:ffdhe2048. +.PP +For a TLS 1.3 client, all the groups in the string \fIlist\fR are added to the +supported groups extension of a \f(CW\*(C`ClientHello\*(C'\fR, in the order in which they are listed, +thereby interpreting tuple separators as group separators. The extension\*(Aqs +preference order, to be evaluated by the server, is determined by the +order of the elements in the array, see below. +.PP +If a group name is preceded by \f(CW\*(C`*\*(C'\fR, a key share will be sent for this group. +When preceding \f(CW\*(C`DEFAULT\*(C'\fR with \f(CW\*(C`*\*(C'\fR, a key share will be sent for the first group +of the OpenSSL built\-in default list of groups. If no \f(CW\*(C`*\*(C'\fR is used anywhere in the list, +a single key share for the leftmost valid group is sent. A maximum of 4 key shares +are supported. Example: "P\-521:*P\-256/*P\-384" will add P\-521, P\-256 and P\-384 to the +supported groups extension in a \f(CW\*(C`ClientHello\*(C'\fR and will send key shares for P\-256 and P\-384. +.PP +For a TLS 1.3 server, the groups in the string \fIlist\fR will be used to determine which group +is used for the key agreement. The preference order of the group tuples is determined +by the order of the tuples in the array, and the preference order of the groups within +a group tuple is determined by the order of the groups in the tuple. Server preference +can be enforced by setting \fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR using +\&\fBSSL_set_options\fR (default: client preference). +.PP +The server will select the group to be used for a key agreement using the following +pseudo\-code algorithm: +.PP +.Vb 12 +\& FOR each group tuple +\& IF client preference (= default) +\& FOR each client key\-share group +\& IF current key\-share group is also part of current group tuple: SH, return success +\& FOR each client supported groups +\& IF current supported group is also part of current group tuple: HRR, return success +\& ELSE (= server preference = with SSL_OP_CIPHER_SERVER_PREFERENCE option set) +\& FOR each group in current tuple +\& IF current group is also part of client key\-share groups: SH, return success +\& FOR each group in current tuple +\& IF current group is also part of client supported groups: HRR, return success +\& return failure +\& +\& with : SH: Server hello with current group +\& HRR: Server retry request with current group +.Ve +.PP +Hence, if a client supports a group in a server group tuple, but does not send a key +share for this group, a Hello Retry Request (HRR) is triggered, asking the client +to send a new Hello message with a more preferred keyshare. See examples below. +.PP +A group name can optionally be preceded by any of \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`?\*(C'\fR or \f(CW\*(C`\-\*(C'\fR, in any order, with +the exception that only \f(CW\*(C`*\*(C'\fR is allowed to precede \f(CW\*(C`DEFAULT\*(C'\fR. Separator characters +\&\f(CW\*(C`:\*(C'\fR and \f(CW\*(C`/\*(C'\fR are only allowed inside the \fIlist\fR and not at the very beginning or end. +.PP +\&\fBSSL_set1_groups()\fR and \fBSSL_set1_groups_list()\fR are similar except they set +supported groups for the SSL structure \fBssl\fR. +.PP +\&\fBSSL_get1_groups()\fR returns the set of supported groups sent by a client +in the supported groups extension. It returns the total number of +supported groups. The \fBgroups\fR parameter can be \fBNULL\fR to simply +return the number of groups for memory allocation purposes. The +\&\fBgroups\fR array is in the form of a set of group NIDs in preference +order. It can return zero if the client did not send a supported groups +extension. If a supported group NID is unknown then the value is set to the +bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. +.PP +\&\fBSSL_get0_iana_groups()\fR retrieves the list of groups sent by the +client in the supported_groups extension. The \fB*out\fR array of bytes +is populated with the host\-byte\-order representation of the uint16_t group +identifiers, as assigned by IANA. The group list is returned in the same order +that was received in the ClientHello. The return value is the number of groups, +not the number of bytes written. +.PP +\&\fBSSL_get_shared_group()\fR returns the NID of the shared group \fBn\fR for a +server\-side SSL \fBssl\fR. If \fBn\fR is \-1 then the total number of shared groups is +returned, which may be zero. Other than for diagnostic purposes, +most applications will only be interested in the first shared group +so \fBn\fR is normally set to zero. If the value \fBn\fR is out of range, +NID_undef is returned. If the NID for the shared group is unknown then the value +is set to the bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the +group. +.PP +\&\fBSSL_get_negotiated_group()\fR returns the NID of the negotiated group used for +the handshake key exchange process. For TLSv1.3 connections this typically +reflects the state of the current connection, though in the case of PSK\-only +resumption, the returned value will be from a previous connection. For earlier +TLS versions, when a session has been resumed, it always reflects the group +used for key exchange during the initial handshake (otherwise it is from the +current, non\-resumption, connection). This can be called by either client or +server. If the NID for the shared group is unknown then the value is set to the +bitwise OR of TLSEXT_nid_unknown (0x1000000) and the id of the group. See also +\&\fBSSL_get0_group_name\fR\|(3) which returns the name of the negotiated group +directly and is generally preferred over \fBSSL_get_negotiated_group()\fR. +.PP +\&\fBSSL_CTX_get0_implemented_groups()\fR populates a stack with the names of TLS +groups that are compatible with the TLS version of the \fBctx\fR argument. +The returned names are references to internal constants and must not be +modified or freed. When \fBall\fR is nonzero, the returned list includes not +only the preferred IANA names of the groups, but also any associated aliases. +If the SSL_CTX is version\-flexible, the groups will be those compatible +with any configured minimum and maximum protocol versions. +The \fBnames\fR stack should be allocated by the caller and be empty, the +matching group names are appended to the provided stack. +The \fB\-tls\-groups\fR and \fB\-all\-tls\-groups\fR options of the +openssl list command output these lists for either +TLS 1.2 or TLS 1.3 (by default). +.PP +All these functions are implemented as macros. +.PP +The curve functions are synonyms for the equivalently named group functions and +are identical in every respect. They exist because, prior to TLS1.3, there was +only the concept of supported curves. In TLS1.3 this was renamed to supported +groups, and extended to include Diffie Hellman groups. The group functions +should be used in preference. +.SH NOTES +.IX Header "NOTES" +If an application wishes to make use of several of these functions for +configuration purposes either on a command line or in a file it should +consider using the SSL_CONF interface instead of manually parsing options. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set1_groups()\fR, \fBSSL_CTX_set1_groups_list()\fR, \fBSSL_set1_groups()\fR, +\&\fBSSL_set1_groups_list()\fR, and \fBSSL_CTX_get0_implemented_groups()\fR return 1 for +success and 0 for failure. +.PP +\&\fBSSL_get1_groups()\fR returns the number of groups, which may be zero. +.PP +\&\fBSSL_get0_iana_groups()\fR returns the number of (uint16_t) groups, which may be zero. +.PP +\&\fBSSL_get_shared_group()\fR returns the NID of shared group \fBn\fR or NID_undef if there +is no shared group \fBn\fR; or the total number of shared groups if \fBn\fR +is \-1. +.PP +When called on a client \fBssl\fR, \fBSSL_get_shared_group()\fR has no meaning and +returns \-1. +.PP +\&\fBSSL_get_negotiated_group()\fR returns the NID of the negotiated group used for +key exchange, or NID_undef if there was no negotiated group. +.SH EXAMPLES +.IX Header "EXAMPLES" +Assume the server \fIlist\fR is "P\-521:P\-256/P\-384/X25519:ffdhe2048" and client +\&\fIlist\fR is "P\-521:*P\-384" when connecting to such a server, meaning that the +client supports \f(CW\*(C`P\-521\*(C'\fR but does not send a key share for this group to the +server, and the client supports \f(CW\*(C`P\-384\*(C'\fR including key share for this group. +With both server and client preference, an HRR will be triggered for \f(CW\*(C`P\-521\*(C'\fR +despite the availability of a key share for P\-384, which overlaps with a lower +priority server\-side tuple. +.PP +As a separate example, consider a server \fIlist\fR "A:B/C:D/E:F". Listed in order +of highest preference to least, 3 group tuples are created: "A:B", "C:D", and +"E:F". Here are some examples of a client \fIlist\fR where setting server/client +preference will not change the outcome: +.PP +\&\- "A:D:*F": Both prefer "A", but the server didn\*(Aqt receive a keyshare for the +most\-preferred tuple in which there\*(Aqs at least one group supported by both. +Therefore, an HRR is triggered for "A". +.PP +\&\- "B:*C": Both prefer "B" from the first group tuple "A:B", so an HRR is +triggered for "B". +.PP +\&\- "C:*F": Both prefer "C" from the second group tuple "C:D", so an HRR is +triggered for "C". +.PP +\&\- "C:*D": Even though both prefer "C" over "D", the server will accept +the key share for "D". Within a tuple, existing keyshares trump preference +order. +.PP +\&\- "*C:*D": The server accepts the "C" key share. +.PP +\&\- "F": Even though it is not prepended with a "*", the client will send a key +share for "F". The server will then accept the key share for "F". +.PP +\&\- "*E:C:A": The server prefers "A" from the "A:B" group tuple, so an HRR is +triggered for "A". +.PP +\&\- "*E:B:*A": The server uses the key share for "A". +.PP +Here are some examples where setting server/client preference will change the +result: +.PP +\&\- "*D:*C" + \- Client preference: The server uses the key share for "D". + \- Server preference: The server uses the key share for "C". +.PP +\&\- "B:A:*C" + \- Client preference: The server triggers an HRR for "B". For the server, +"A" and "B" are considered comparable in security. But because the client +prefers "B", the server will trigger an HRR for "B". + \- Server preference: The server triggers an HRR for "A". +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), +\&\fBSSL_get0_group_name\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The curve functions were added in OpenSSL 1.0.2. The equivalent group +functions were added in OpenSSL 1.1.1. The \fBSSL_get_negotiated_group()\fR function +was added in OpenSSL 3.0.0. +.PP +Support for ignoring unknown groups in \fBSSL_CTX_set1_groups_list()\fR and +\&\fBSSL_set1_groups_list()\fR was added in OpenSSL 3.3. +.PP +Support for \fBML\-KEM\fR was added in OpenSSL 3.5. +.PP +OpenSSL 3.5 also introduces support for three \fIhybrid\fR ECDH PQ key exchange +TLS groups: \fBX25519MLKEM768\fR, \fBSecP256r1MLKEM768\fR and +\&\fBSecP384r1MLKEM1024\fR. +They offer CPU performance comparable to the associated ECDH group, though at +the cost of significantly larger key exchange messages. +The third group, \fBSecP384r1MLKEM1024\fR is substantially more CPU\-intensive, +largely as a result of the high CPU cost of ECDH for the underlying \fBP\-384\fR +group. +Also its key exchange messages at close to 1700 bytes are larger than the +roughly 1200 bytes for the first two groups. +.PP +As of OpenSSL 3.5 key exchange group names are case\-insensitive. +.PP +\&\fBSSL_CTX_get0_implemented_groups\fR was first implemented in OpenSSL 3.5. +.PP +Earlier versions of this document described the list as a preference order. +However, OpenSSL\*(Aqs behavior as a TLS 1.3 server is to consider \fIall\fR +supported groups as comparable in security. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set1_sigalgs.3 b/static/netbsd/man3/SSL_CTX_set1_sigalgs.3 new file mode 100644 index 00000000..3776f9bd --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set1_sigalgs.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: SSL_CTX_set1_sigalgs.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set1_sigalgs 3" +.TH SSL_CTX_set1_sigalgs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list, +SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs, +SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list, +SSL_set1_client_sigalgs_list \- set supported signature algorithms +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); +\& long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen); +\& long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str); +\& long SSL_set1_sigalgs_list(SSL *ssl, const char *str); +\& +\& long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); +\& long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen); +\& long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str); +\& long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set1_sigalgs()\fR and \fBSSL_set1_sigalgs()\fR set the supported signature +algorithms for \fBctx\fR or \fBssl\fR. The array \fBslist\fR of length \fBslistlen\fR +must consist of pairs of NIDs corresponding to digest and public key +algorithms. +.PP +\&\fBSSL_CTX_set1_sigalgs_list()\fR and \fBSSL_set1_sigalgs_list()\fR set the supported +signature algorithms for \fBctx\fR or \fBssl\fR. The \fBstr\fR parameter +must be a null terminated string consisting of a colon separated list of +elements, where each element is either a combination of a public key +algorithm and a digest separated by \fB+\fR, or a TLS 1.3\-style named +SignatureScheme such as rsa_pss_pss_sha256. +Signature scheme names and public key algorithm names (but not the digest +names) in the \fBalgorithm+hash\fR form are case\-insensitive. +If a list entry is preceded with the \f(CW\*(C`?\*(C'\fR character, it will be ignored if an +implementation is missing. +.PP +\&\fBSSL_CTX_set1_client_sigalgs()\fR, \fBSSL_set1_client_sigalgs()\fR, +\&\fBSSL_CTX_set1_client_sigalgs_list()\fR and \fBSSL_set1_client_sigalgs_list()\fR set +signature algorithms related to client authentication, otherwise they are +identical to \fBSSL_CTX_set1_sigalgs()\fR, \fBSSL_set1_sigalgs()\fR, +\&\fBSSL_CTX_set1_sigalgs_list()\fR and \fBSSL_set1_sigalgs_list()\fR. +.PP +All these functions are implemented as macros. The signature algorithm +parameter (integer array or string) is not freed: the application should +free it, if necessary. +.SH NOTES +.IX Header "NOTES" +If an application wishes to allow the setting of signature algorithms +as one of many user configurable options it should consider using the more +flexible SSL_CONF API instead. +.PP +The signature algorithms set by a client are used directly in the supported +signature algorithm in the client hello message. +.PP +The supported signature algorithms set by a server are not sent to the +client but are used to determine the set of shared signature algorithms +and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE) +their order. +.PP +The client authentication signature algorithms set by a server are sent +in a certificate request message if client authentication is enabled, +otherwise they are unused. +.PP +Similarly client authentication signature algorithms set by a client are +used to determined the set of client authentication shared signature +algorithms. +.PP +Signature algorithms will neither be advertised nor used if the security level +prohibits them (for example SHA1 if the security level is 4 or more). +.PP +Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and +NID_sha512 digest NIDs are supported and the public key algorithm NIDs +EVP_PKEY_RSA, EVP_PKEY_RSA_PSS, EVP_PKEY_DSA and EVP_PKEY_EC. +.PP +The short or long name values for digests can be used in a string (for +example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and +the public key algorithm strings "RSA", "RSA\-PSS", "DSA" or "ECDSA". +.PP +The TLS 1.3 signature scheme names (such as "rsa_pss_pss_sha256") can also +be used with the \fB_list\fR forms of the API. +.PP +The use of MD5 as a digest is strongly discouraged due to security weaknesses. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 for failure. +.SH EXAMPLES +.IX Header "EXAMPLES" +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using an array: +.PP +.Vb 1 +\& const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA}; +\& +\& SSL_CTX_set1_sigalgs(ctx, slist, 4); +.Ve +.PP +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using a string: +.PP +.Vb 1 +\& SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_shared_sigalgs\fR\|(3), +\&\fBSSL_CONF_CTX_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +Support for ignoring unknown signature algorithms in +\&\fBSSL_CTX_set1_sigalgs_list()\fR, \fBSSL_set1_sigalgs_list()\fR, +\&\fBSSL_CTX_set1_client_sigalgs_list()\fR and \fBSSL_set1_client_sigalgs_list()\fR +was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set1_verify_cert_store.3 b/static/netbsd/man3/SSL_CTX_set1_verify_cert_store.3 new file mode 100644 index 00000000..ebda22e9 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set1_verify_cert_store.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: SSL_CTX_set1_verify_cert_store.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set1_verify_cert_store 3" +.TH SSL_CTX_set1_verify_cert_store 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store, +SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store, +SSL_set0_verify_cert_store, SSL_set1_verify_cert_store, +SSL_set0_chain_cert_store, SSL_set1_chain_cert_store, +SSL_CTX_get0_verify_cert_store, SSL_CTX_get0_chain_cert_store, +SSL_get0_verify_cert_store, SSL_get0_chain_cert_store \- set certificate +verification or chain store +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); +\& int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); +\& int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); +\& int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); +\& int SSL_CTX_get0_verify_cert_store(SSL_CTX *ctx, X509_STORE **st); +\& int SSL_CTX_get0_chain_cert_store(SSL_CTX *ctx, X509_STORE **st); +\& +\& int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st); +\& int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st); +\& int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st); +\& int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st); +\& int SSL_get0_verify_cert_store(SSL *ctx, X509_STORE **st); +\& int SSL_get0_chain_cert_store(SSL *ctx, X509_STORE **st); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set0_verify_cert_store()\fR and \fBSSL_CTX_set1_verify_cert_store()\fR +set the certificate store used for certificate verification to \fBst\fR. +.PP +\&\fBSSL_CTX_set0_chain_cert_store()\fR and \fBSSL_CTX_set1_chain_cert_store()\fR +set the certificate store used for certificate chain building to \fBst\fR. +.PP +\&\fBSSL_set0_verify_cert_store()\fR, \fBSSL_set1_verify_cert_store()\fR, +\&\fBSSL_set0_chain_cert_store()\fR and \fBSSL_set1_chain_cert_store()\fR are similar +except they apply to SSL structure \fBssl\fR. +.PP +\&\fBSSL_CTX_get0_verify_chain_store()\fR, \fBSSL_get0_verify_chain_store()\fR, +\&\fBSSL_CTX_get0_chain_cert_store()\fR and \fBSSL_get0_chain_cert_store()\fR retrieve the +objects previously set via the above calls. A pointer to the object (or NULL if +no such object has been set) is written to \fB*st\fR. +.PP +All these functions are implemented as macros. Those containing a \fB1\fR +increment the reference count of the supplied store so it must +be freed at some point after the operation. Those containing a \fB0\fR do +not increment reference counts and the supplied store \fBMUST NOT\fR be freed +after the operation. +.SH NOTES +.IX Header "NOTES" +The stores pointers associated with an SSL_CTX structure are copied to any SSL +structures when \fBSSL_new()\fR is called. As a result SSL structures will not be +affected if the parent SSL_CTX store pointer is set to a new value. +.PP +The verification store is used to verify the certificate chain sent by the +peer: that is an SSL/TLS client will use the verification store to verify +the server\*(Aqs certificate chain and an SSL/TLS server will use it to verify +any client certificate chain. +.PP +The chain store is used to build the certificate chain. +Details of the chain building and checking process are described in +"Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1) and +"Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1). +.PP +If the mode \fBSSL_MODE_NO_AUTO_CHAIN\fR is set or a certificate chain is +configured already (for example using the functions such as +\&\fBSSL_CTX_add1_chain_cert\fR\|(3) or +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3)) then +automatic chain building is disabled. +.PP +If the mode \fBSSL_MODE_NO_AUTO_CHAIN\fR is set then automatic chain building +is disabled. +.PP +If the chain or the verification store is not set then the store associated +with the parent SSL_CTX is used instead to retain compatibility with previous +versions of OpenSSL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3) +\&\fBSSL_CTX_set0_chain\fR\|(3) +\&\fBSSL_CTX_set1_chain\fR\|(3) +\&\fBSSL_CTX_add0_chain_cert\fR\|(3) +\&\fBSSL_CTX_add1_chain_cert\fR\|(3) +\&\fBSSL_set0_chain\fR\|(3) +\&\fBSSL_set1_chain\fR\|(3) +\&\fBSSL_add0_chain_cert\fR\|(3) +\&\fBSSL_add1_chain_cert\fR\|(3) +\&\fBSSL_CTX_build_cert_chain\fR\|(3) +\&\fBSSL_build_cert_chain\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_alpn_select_cb.3 b/static/netbsd/man3/SSL_CTX_set_alpn_select_cb.3 new file mode 100644 index 00000000..de4bb60e --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_alpn_select_cb.3 @@ -0,0 +1,259 @@ +.\" $NetBSD: SSL_CTX_set_alpn_select_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_alpn_select_cb 3" +.TH SSL_CTX_set_alpn_select_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, +SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, +SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated +\&\- handle application layer protocol negotiation (ALPN) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, +\& unsigned int protos_len); +\& int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, +\& unsigned int protos_len); +\& void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx, +\& int (*cb) (SSL *ssl, +\& const unsigned char **out, +\& unsigned char *outlen, +\& const unsigned char *in, +\& unsigned int inlen, +\& void *arg), void *arg); +\& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, +\& unsigned int *len); +\& +\& void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, +\& int (*cb)(SSL *ssl, +\& const unsigned char **out, +\& unsigned int *outlen, +\& void *arg), +\& void *arg); +\& void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, +\& int (*cb)(SSL *s, +\& unsigned char **out, +\& unsigned char *outlen, +\& const unsigned char *in, +\& unsigned int inlen, +\& void *arg), +\& void *arg); +\& int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, +\& const unsigned char *server, +\& unsigned int server_len, +\& const unsigned char *client, +\& unsigned int client_len); +\& void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, +\& unsigned *len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR are used by the client to +set the list of protocols available to be negotiated. The \fBprotos\fR must be in +protocol\-list format, described below. The length of \fBprotos\fR is specified in +\&\fBprotos_len\fR. Setting \fBprotos_len\fR to 0 clears any existing list of ALPN +protocols and no ALPN extension will be sent to the server. +.PP +\&\fBSSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a +server to select which protocol to use for the incoming connection. When \fBcb\fR +is NULL, ALPN is not used. The \fBarg\fR value is a pointer which is passed to +the application callback. +.PP +\&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a +vector in protocol\-list format. The value of the \fBout\fR, \fBoutlen\fR vector +should be set to the value of a single protocol selected from the \fBin\fR, +\&\fBinlen\fR vector. The \fBout\fR buffer may point directly into \fBin\fR, or to a +buffer that outlives the handshake. The \fBarg\fR parameter is the pointer set via +\&\fBSSL_CTX_set_alpn_select_cb()\fR. +.PP +\&\fBSSL_select_next_proto()\fR is a helper function used to select protocols. It +implements the standard protocol selection. It is expected that this function +is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR, +\&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol\-list format +described below. The first item in the \fBserver\fR, \fBserver_len\fR list that +matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned +in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or +\&\fBclient\fR, so it should be copied immediately. The client list must include at +least one valid (nonempty) protocol entry in the list. +.PP +The \fBSSL_select_next_proto()\fR helper function can be useful from either the ALPN +callback or the NPN callback (described below). If no match is found, the first +item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR and +\&\fBOPENSSL_NPN_NO_OVERLAP\fR is returned. This can be useful when implementing +the NPN callback. In the ALPN case, the value returned in \fBout\fR and \fBoutlen\fR +must be ignored if \fBOPENSSL_NPN_NO_OVERLAP\fR has been returned from +\&\fBSSL_select_next_proto()\fR. +.PP +\&\fBSSL_CTX_set_next_proto_select_cb()\fR sets a callback \fBcb\fR that is called when a +client needs to select a protocol from the server\*(Aqs provided list, and a +user\-defined pointer argument \fBarg\fR which will be passed to this callback. +For the callback itself, \fBout\fR +must be set to point to the selected protocol (which may be within \fBin\fR). +The length of the protocol name must be written into \fBoutlen\fR. The +server\*(Aqs advertised protocols are provided in \fBin\fR and \fBinlen\fR. The +callback can assume that \fBin\fR is syntactically valid. The client must +select a protocol (although it may be an empty, zero length protocol). It is +fatal to the connection if this callback returns a value other than +\&\fBSSL_TLSEXT_ERR_OK\fR or if the zero length protocol is selected. The \fBarg\fR +parameter is the pointer set via \fBSSL_CTX_set_next_proto_select_cb()\fR. +.PP +\&\fBSSL_CTX_set_next_protos_advertised_cb()\fR sets a callback \fBcb\fR that is called +when a TLS server needs a list of supported protocols for Next Protocol +Negotiation. The returned list must be in protocol\-list format, described +below. The list is +returned by setting \fBout\fR to point to it and \fBoutlen\fR to its length. This +memory will not be modified, but the \fBSSL\fR does keep a +reference to it. The callback should return \fBSSL_TLSEXT_ERR_OK\fR if it +wishes to advertise. Otherwise, no such extension will be included in the +ServerHello. +.PP +\&\fBSSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR +with length \fBlen\fR. It is not NUL\-terminated. \fBdata\fR is set to NULL and \fBlen\fR +is set to 0 if no protocol has been selected. \fBdata\fR must not be freed. +.PP +\&\fBSSL_get0_next_proto_negotiated()\fR sets \fBdata\fR and \fBlen\fR to point to the +client\*(Aqs requested protocol for this connection. If the client did not +request any protocol or NPN is not enabled, then \fBdata\fR is set to NULL and +\&\fBlen\fR to 0. Note that +the client can request any protocol it chooses. The value returned from +this function need not be a member of the list of supported protocols +provided by the callback. +.PP +NPN functionality cannot be used with QUIC SSL objects. Use of ALPN is mandatory +when using QUIC SSL objects. \fBSSL_CTX_set_next_protos_advertised_cb()\fR and +\&\fBSSL_CTX_set_next_proto_select_cb()\fR have no effect if called on a QUIC SSL +context. +.SH NOTES +.IX Header "NOTES" +The protocol\-lists must be in wire\-format, which is defined as a vector of +nonempty, 8\-bit length\-prefixed, byte strings. The length\-prefix byte is not +included in the length. Each string is limited to 255 bytes. A byte\-string +length of 0 is invalid. A truncated byte\-string is invalid. The length of the +vector is not in the vector itself, but in a separate variable. +.PP +Example: +.PP +.Vb 5 +\& unsigned char vector[] = { +\& 6, \*(Aqs\*(Aq, \*(Aqp\*(Aq, \*(Aqd\*(Aq, \*(Aqy\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, +\& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq1\*(Aq +\& }; +\& unsigned int length = sizeof(vector); +.Ve +.PP +The ALPN callback is executed after the servername callback; as that servername +callback may update the SSL_CTX, and subsequently, the ALPN callback. +.PP +If there is no ALPN proposed in the ClientHello, the ALPN callback is not +invoked. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR return 0 on success, and +non\-0 on failure. WARNING: these functions reverse the return value convention. +.PP +\&\fBSSL_select_next_proto()\fR returns one of the following: +.IP OPENSSL_NPN_NEGOTIATED 4 +.IX Item "OPENSSL_NPN_NEGOTIATED" +A match was found and is returned in \fBout\fR, \fBoutlen\fR. +.IP OPENSSL_NPN_NO_OVERLAP 4 +.IX Item "OPENSSL_NPN_NO_OVERLAP" +No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in +\&\fBout\fR, \fBoutlen\fR (or \fBNULL\fR and 0 in the case where the first entry in +\&\fBclient\fR is invalid). +.PP +The ALPN select callback \fBcb\fR, must return one of the following: +.IP SSL_TLSEXT_ERR_OK 4 +.IX Item "SSL_TLSEXT_ERR_OK" +ALPN protocol selected. +.IP SSL_TLSEXT_ERR_ALERT_FATAL 4 +.IX Item "SSL_TLSEXT_ERR_ALERT_FATAL" +There was no overlap between the client\*(Aqs supplied list and the server +configuration. +.IP SSL_TLSEXT_ERR_NOACK 4 +.IX Item "SSL_TLSEXT_ERR_NOACK" +ALPN protocol not selected, e.g., because no ALPN protocols are configured for +this connection. +.PP +The callback set using \fBSSL_CTX_set_next_proto_select_cb()\fR should return +\&\fBSSL_TLSEXT_ERR_OK\fR if successful. Any other value is fatal to the connection. +.PP +The callback set using \fBSSL_CTX_set_next_protos_advertised_cb()\fR should return +\&\fBSSL_TLSEXT_ERR_OK\fR if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_tlsext_servername_callback\fR\|(3), +\&\fBSSL_CTX_set_tlsext_servername_arg\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_cert_cb.3 b/static/netbsd/man3/SSL_CTX_set_cert_cb.3 new file mode 100644 index 00000000..88453454 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_cert_cb.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: SSL_CTX_set_cert_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_cert_cb 3" +.TH SSL_CTX_set_cert_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_cert_cb, SSL_set_cert_cb \- handle certificate callback function +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), +\& void *arg); +\& void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR sets the \fIcert_cb\fR callback, +\&\fIarg\fR value is pointer which is passed to the application callback. +.PP +When \fIcert_cb\fR is NULL, no callback function is used. +.PP +\&\fIcert_cb\fR is the application defined callback. It is called before a +certificate will be used by a client or server. The callback can then inspect +the passed \fIssl\fR structure and set or clear any appropriate certificates. If +the callback is successful it \fBMUST\fR return 1 even if no certificates have +been set. A zero is returned on error which will abort the handshake with a +fatal internal error alert. A negative return value will suspend the handshake +and the handshake function will return immediately. +\&\fBSSL_get_error\fR\|(3) will return SSL_ERROR_WANT_X509_LOOKUP to +indicate, that the handshake was suspended. The next call to the handshake +function will again lead to the call of \fIcert_cb\fR. It is the job of the +\&\fIcert_cb\fR to store information about the state of the last call, +if required to continue. +.SH NOTES +.IX Header "NOTES" +An application will typically call \fBSSL_use_certificate()\fR and +\&\fBSSL_use_PrivateKey()\fR to set the end entity certificate and private key. +It can add intermediate and optionally the root CA certificates using +\&\fBSSL_add1_chain_cert()\fR. +.PP +It might also call \fBSSL_certs_clear()\fR to delete any certificates associated +with the \fBSSL\fR object. +.PP +The certificate callback functionality supersedes the (largely broken) +functionality provided by the old client certificate callback interface. +It is \fBalways\fR called even is a certificate is already set so the callback +can modify or delete the existing certificate. +.PP +A more advanced callback might examine the handshake parameters and set +whatever chain is appropriate. For example a legacy client supporting only +TLSv1.0 might receive a certificate chain signed using SHA1 whereas a +TLSv1.2 or later client which advertises support for SHA256 could receive a +chain using SHA256. +.PP +Normal server sanity checks are performed on any certificates set +by the callback. So if an EC chain is set for a curve the client does not +support it will \fBnot\fR be used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR do not return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_use_certificate\fR\|(3), +\&\fBSSL_add1_chain_cert\fR\|(3), +\&\fBSSL_get_client_CA_list\fR\|(3), +\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_cert_store.3 b/static/netbsd/man3/SSL_CTX_set_cert_store.3 new file mode 100644 index 00000000..bef83213 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_cert_store.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: SSL_CTX_set_cert_store.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_cert_store 3" +.TH SSL_CTX_set_cert_store 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_cert_store, SSL_CTX_set1_cert_store, SSL_CTX_get_cert_store \- manipulate X509 certificate verification storage +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); +\& void SSL_CTX_set1_cert_store(SSL_CTX *ctx, X509_STORE *store); +\& X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_cert_store()\fR sets/replaces the certificate verification storage +of \fBctx\fR to/with \fBstore\fR. If another X509_STORE object is currently +set in \fBctx\fR, it will be \fBX509_STORE_free()\fRed. \fBSSL_CTX_set_cert_store()\fR will +take ownership of the \fBstore\fR, i.e., the call \f(CWX509_STORE_free(store)\fR is no +longer needed. +.PP +\&\fBSSL_CTX_set1_cert_store()\fR sets/replaces the certificate verification storage +of \fBctx\fR to/with \fBstore\fR. The \fBstore\fR\*(Aqs reference count is incremented. +If another X509_STORE object is currently set in \fBctx\fR, it will be \fBX509_STORE_free()\fRed. +.PP +\&\fBSSL_CTX_get_cert_store()\fR returns a pointer to the current certificate +verification storage. \fBctx\fR \fBMUST NOT\fR be NULL. +.SH NOTES +.IX Header "NOTES" +In order to verify the certificates presented by the peer, trusted CA +certificates must be accessed. These CA certificates are made available +via lookup methods, handled inside the X509_STORE. From the X509_STORE +the X509_STORE_CTX used when verifying certificates is created. +.PP +Typically the trusted certificate store is handled indirectly via using +\&\fBSSL_CTX_load_verify_locations\fR\|(3). +Using the \fBSSL_CTX_set_cert_store()\fR and \fBSSL_CTX_get_cert_store()\fR functions +it is possible to manipulate the X509_STORE object beyond the +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +call. +.PP +Currently no detailed documentation on how to use the X509_STORE +object is available. Not all members of the X509_STORE are used when +the verification takes place. So will e.g. the \fBverify_callback()\fR be +overridden with the \fBverify_callback()\fR set via the +\&\fBSSL_CTX_set_verify\fR\|(3) family of functions. +This document must therefore be updated when documentation about the +X509_STORE object and its handling becomes available. +.PP +\&\fBSSL_CTX_set_cert_store()\fR does not increment the \fBstore\fR\*(Aqs reference +count, so it should not be used to assign an X509_STORE that is owned +by another SSL_CTX. +.PP +To share X509_STOREs between two SSL_CTXs, use \fBSSL_CTX_get_cert_store()\fR +to get the X509_STORE from the first SSL_CTX, and then use +\&\fBSSL_CTX_set1_cert_store()\fR to assign to the second SSL_CTX and +increment the reference count of the X509_STORE. +.SH RESTRICTIONS +.IX Header "RESTRICTIONS" +The X509_STORE structure used by an SSL_CTX is used for verifying peer +certificates and building certificate chains, it is also shared by +every child SSL structure. Applications wanting finer control can use +functions such as \fBSSL_CTX_set1_verify_cert_store()\fR instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_cert_store()\fR does not return diagnostic output. +.PP +\&\fBSSL_CTX_set1_cert_store()\fR does not return diagnostic output. +.PP +\&\fBSSL_CTX_get_cert_store()\fR returns the current setting. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_load_verify_locations\fR\|(3), +\&\fBSSL_CTX_set_verify\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_cert_verify_callback.3 b/static/netbsd/man3/SSL_CTX_set_cert_verify_callback.3 new file mode 100644 index 00000000..c14ff139 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_cert_verify_callback.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: SSL_CTX_set_cert_verify_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_cert_verify_callback 3" +.TH SSL_CTX_set_cert_verify_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_cert_verify_callback \- set peer certificate verification procedure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, +\& int (*callback)(X509_STORE_CTX *, void *), +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_cert_verify_callback()\fR sets the verification callback function for +\&\fIctx\fR. SSL objects that are created from \fIctx\fR inherit the setting valid at +the time when \fBSSL_new\fR\|(3) is called. +.SH NOTES +.IX Header "NOTES" +When a peer certificate has been received during an SSL/TLS handshake, +a verification function is called regardless of the verification mode. +If the application does not explicitly specify a verification callback function, +the built\-in verification function is used. +If a verification callback \fIcallback\fR is specified via +\&\fBSSL_CTX_set_cert_verify_callback()\fR, the supplied callback function is called +instead with the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). +The argument \fIarg\fR is specified by the application when setting \fIcallback\fR. +By setting \fIcallback\fR to NULL, the default behaviour is restored. +.PP +\&\fIcallback\fR should return 1 to indicate verification success +and 0 to indicate verification failure. +In server mode, a return value of 0 leads to handshake failure. +In client mode, the behaviour is as follows. +All values, including 0, are ignored +if the verification mode is \fBSSL_VERIFY_NONE\fR. +Otherwise, when the return value is less than or equal to 0, the handshake will +fail. +.PP +In client mode \fIcallback\fR may also call the \fBSSL_set_retry_verify\fR\|(3) +function on the \fBSSL\fR object set in the \fIx509_store_ctx\fR ex data (see +\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3)) and return 1. This would be +typically done in case the certificate verification was not yet able +to succeed. This makes the handshake suspend and return control to the +calling application with \fBSSL_ERROR_WANT_RETRY_VERIFY\fR. The app can for +instance fetch further certificates or cert status information needed for +the verification. Calling \fBSSL_connect\fR\|(3) again resumes the connection +attempt by retrying the server certificate verification step. +This process may even be repeated if need be. +.PP +In any case a viable verification result value must be reflected +in the \fBerror\fR member of \fIx509_store_ctx\fR, +which can be done using \fBX509_STORE_CTX_set_error\fR\|(3). +This is particularly important in case +the \fIcallback\fR allows the connection to continue (by returning 1). +Note that the verification status in the store context is a possibly durable +indication of the chain\*(Aqs validity! +This gets recorded in the SSL session (and thus also in session tickets) +and the validity of the originally presented chain is then visible +on resumption, even though no chain is presented int that case. +Moreover, the calling application will be informed about the detailed result of +the verification procedure and may elect to base further decisions on it. +.PP +\&\fIcallback\fR may call \fBX509_verify_cert\fR\|(3) to run the built\-in verification +function. This may be useful if application wishes to dynamically reconfigure +\&\fIx509_store_ctx\fR before verification, or postprocess the result. In this case, +\&\fBX509_verify_cert\fR\|(3) will set the \fBerror\fR member as described above. +.PP +Within \fIx509_store_ctx\fR, \fIcallback\fR has access to the \fIverify_callback\fR +function set using \fBSSL_CTX_set_verify\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_cert_verify_callback()\fR does not return a value. +.SH WARNINGS +.IX Header "WARNINGS" +Do not mix the verification callback described in this function with the +\&\fBverify_callback\fR function called during the verification process. The +latter is set using the \fBSSL_CTX_set_verify\fR\|(3) +family of functions. +.PP +Providing a complete verification procedure including certificate purpose +settings etc is a complex task. The built\-in procedure is quite powerful +and in most cases it should be sufficient to modify its behaviour using +the \fBverify_callback\fR function. +.SH BUGS +.IX Header "BUGS" +\&\fBSSL_CTX_set_cert_verify_callback()\fR does not provide diagnostic information. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_verify\fR\|(3), +\&\fBX509_STORE_CTX_set_error\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_set_retry_verify\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_cipher_list.3 b/static/netbsd/man3/SSL_CTX_set_cipher_list.3 new file mode 100644 index 00000000..e96ab59b --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_cipher_list.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: SSL_CTX_set_cipher_list.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_cipher_list 3" +.TH SSL_CTX_set_cipher_list 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_cipher_list, +SSL_set_cipher_list, +SSL_CTX_set_ciphersuites, +SSL_set_ciphersuites, +OSSL_default_cipher_list, +OSSL_default_ciphersuites +\&\- choose list of available SSL_CIPHERs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); +\& int SSL_set_cipher_list(SSL *ssl, const char *str); +\& +\& int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str); +\& int SSL_set_ciphersuites(SSL *s, const char *str); +\& +\& const char *OSSL_default_cipher_list(void); +\& const char *OSSL_default_ciphersuites(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_cipher_list()\fR sets the list of available ciphers (TLSv1.2 and below) +for \fBctx\fR using the control string \fBstr\fR. The format of the string is described +in \fBopenssl\-ciphers\fR\|(1). The list of ciphers is inherited by all +\&\fBssl\fR objects created from \fBctx\fR. This function does not impact TLSv1.3 +ciphersuites. Use \fBSSL_CTX_set_ciphersuites()\fR to configure those. \fBctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_set_cipher_list()\fR sets the list of ciphers (TLSv1.2 and below) only for +\&\fBssl\fR. +.PP +\&\fBSSL_CTX_set_ciphersuites()\fR is used to configure the available TLSv1.3 +ciphersuites for \fBctx\fR. This is a simple colon (":") separated list of TLSv1.3 +ciphersuite names in order of preference. Valid TLSv1.3 ciphersuite names are: +.IP TLS_AES_128_GCM_SHA256 4 +.IX Item "TLS_AES_128_GCM_SHA256" +.PD 0 +.IP TLS_AES_256_GCM_SHA384 4 +.IX Item "TLS_AES_256_GCM_SHA384" +.IP TLS_CHACHA20_POLY1305_SHA256 4 +.IX Item "TLS_CHACHA20_POLY1305_SHA256" +.IP TLS_AES_128_CCM_SHA256 4 +.IX Item "TLS_AES_128_CCM_SHA256" +.IP TLS_AES_128_CCM_8_SHA256 4 +.IX Item "TLS_AES_128_CCM_8_SHA256" +.IP "TLS_SHA384_SHA384 \- integrity\-only" 4 +.IX Item "TLS_SHA384_SHA384 - integrity-only" +.IP "TLS_SHA256_SHA256 \- integrity\-only" 4 +.IX Item "TLS_SHA256_SHA256 - integrity-only" +.PD +.PP +An empty list is permissible. The default value for this setting is: +.PP +"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" +.PP +\&\fBSSL_set_ciphersuites()\fR is the same as \fBSSL_CTX_set_ciphersuites()\fR except it +configures the ciphersuites for \fBssl\fR. +.PP +\&\fBOSSL_default_cipher_list()\fR returns the default cipher string for TLSv1.2 +(and earlier) ciphers. \fBOSSL_default_ciphersuites()\fR returns the default +cipher string for TLSv1.3 ciphersuites. +.SH NOTES +.IX Header "NOTES" +The control string \fBstr\fR for \fBSSL_CTX_set_cipher_list()\fR, \fBSSL_set_cipher_list()\fR, +\&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR should be universally +usable and not depend on details of the library configuration (ciphers compiled +in). Thus no syntax checking takes place. Items that are not recognized, because +the corresponding ciphers are not compiled in or because they are mistyped, +are simply ignored. Failure is only flagged if no ciphers could be collected +at all. +.PP +It should be noted, that inclusion of a cipher to be used into the list is +a necessary condition. On the client side, the inclusion into the list is +also sufficient unless the security level excludes it. On the server side, +additional restrictions apply. All ciphers have additional requirements. +ADH ciphers don\*(Aqt need a certificate, but DH\-parameters must have been set. +All other ciphers need a corresponding certificate and key. +.PP +An RSA cipher can only be chosen, when an RSA certificate is available. +RSA ciphers using DHE need a certificate and key and additional DH\-parameters +(see \fBSSL_CTX_set_tmp_dh_callback\fR\|(3)). +.PP +A DSA cipher can only be chosen, when a DSA certificate is available. +DSA ciphers always use DH key exchange and therefore need DH\-parameters +(see \fBSSL_CTX_set_tmp_dh_callback\fR\|(3)). +.PP +When these conditions are not met for any cipher in the list (e.g. a +client only supports export RSA ciphers with an asymmetric key length +of 512 bits and the server is not configured to use temporary RSA +keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated +and the handshake will fail. +.PP +\&\fBOSSL_default_cipher_list()\fR and \fBOSSL_default_ciphersuites()\fR replace +SSL_DEFAULT_CIPHER_LIST and TLS_DEFAULT_CIPHERSUITES, respectively. The +cipher list defines are deprecated as of 3.0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_cipher_list()\fR and \fBSSL_set_cipher_list()\fR return 1 if any cipher +could be selected and 0 on complete failure. +.PP +\&\fBSSL_CTX_set_ciphersuites()\fR and \fBSSL_set_ciphersuites()\fR return 1 if the requested +ciphersuite list was configured, and 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_ciphers\fR\|(3), +\&\fBSSL_CTX_use_certificate\fR\|(3), +\&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3), +\&\fBopenssl\-ciphers\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +\&\fBOSSL_default_cipher_list()\fR and \fBOSSL_default_ciphersites()\fR are new in 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_client_CA_list.3 b/static/netbsd/man3/SSL_CTX_set_client_CA_list.3 new file mode 100644 index 00000000..68f44a3e --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_client_CA_list.3 @@ -0,0 +1,228 @@ +.\" $NetBSD: SSL_CTX_set_client_CA_list.3,v 1.18 2018/09/23 13:33:07 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_client_CA_list 3" +.TH SSL_CTX_set_client_CA_list 3 "2018-09-17" "1.1.1" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, +SSL_add_client_CA \- set list of CAs sent to the client when requesting a +client certificate +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); +\& void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); +\& int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); +\& int SSL_add_client_CA(SSL *ssl, X509 *cacert); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_CTX_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when +requesting a client certificate for \fBctx\fR. +.PP +\&\fISSL_set_client_CA_list()\fR sets the \fBlist\fR of CAs sent to the client when +requesting a client certificate for the chosen \fBssl\fR, overriding the +setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object. +.PP +\&\fISSL_CTX_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the +list of CAs sent to the client when requesting a client certificate for +\&\fBctx\fR. +.PP +\&\fISSL_add_client_CA()\fR adds the \s-1CA\s0 name extracted from \fBcacert\fR to the +list of CAs sent to the client when requesting a client certificate for +the chosen \fBssl\fR, overriding the setting valid for \fBssl\fR's \s-1SSL_CTX\s0 object. +.SH "NOTES" +.IX Header "NOTES" +When a \s-1TLS/SSL\s0 server requests a client certificate (see +\&\fB\f(BISSL_CTX_set_verify\fB\|(3)\fR), it sends a list of CAs, for which +it will accept certificates, to the client. +.PP +This list must explicitly be set using \fISSL_CTX_set_client_CA_list()\fR for +\&\fBctx\fR and \fISSL_set_client_CA_list()\fR for the specific \fBssl\fR. The list +specified overrides the previous setting. The CAs listed do not become +trusted (\fBlist\fR only contains the names, not the complete certificates); use +\&\fISSL_CTX_load_verify_locations\fR\|(3) +to additionally load them for verification. +.PP +If the list of acceptable CAs is compiled in a file, the +\&\fISSL_load_client_CA_file\fR\|(3) +function can be used to help importing the necessary data. +.PP +\&\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR can be used to add additional +items the list of client CAs. If no list was specified before using +\&\fISSL_CTX_set_client_CA_list()\fR or \fISSL_set_client_CA_list()\fR, a new client +\&\s-1CA\s0 list for \fBctx\fR or \fBssl\fR (as appropriate) is opened. +.PP +These functions are only useful for \s-1TLS/SSL\s0 servers. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fISSL_CTX_set_client_CA_list()\fR and \fISSL_set_client_CA_list()\fR do not return +diagnostic information. +.PP +\&\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR have the following return +values: +.IP "0" 4 +A failure while manipulating the \s-1STACK_OF\s0(X509_NAME) object occurred or +the X509_NAME could not be extracted from \fBcacert\fR. Check the error stack +to find out the reason. +.IP "1" 4 +.IX Item "1" +The operation succeeded. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Scan all certificates in \fBCAfile\fR and list them as acceptable CAs: +.PP +.Vb 1 +\& SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(7), +\&\fISSL_get_client_CA_list\fR\|(3), +\&\fISSL_load_client_CA_file\fR\|(3), +\&\fISSL_CTX_load_verify_locations\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_client_cert_cb.3 b/static/netbsd/man3/SSL_CTX_set_client_cert_cb.3 new file mode 100644 index 00000000..486af466 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_client_cert_cb.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: SSL_CTX_set_client_cert_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_client_cert_cb 3" +.TH SSL_CTX_set_client_cert_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb \- handle client certificate callback function +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, +\& int (*client_cert_cb)(SSL *ssl, X509 **x509, +\& EVP_PKEY **pkey)); +\& int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, +\& EVP_PKEY **pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_client_cert_cb()\fR sets the \fIclient_cert_cb\fR callback, that is +called when a client certificate is requested by a server and no certificate +was yet set for the SSL object. +.PP +When \fIclient_cert_cb\fR is NULL, no callback function is used. +.PP +\&\fBSSL_CTX_get_client_cert_cb()\fR returns a pointer to the currently set callback +function. +.PP +\&\fIclient_cert_cb\fR is the application defined callback. If it wants to +set a certificate, a certificate/private key combination must be set +using the \fIx509\fR and \fIpkey\fR arguments and "1" must be returned. The +certificate will be installed into \fIssl\fR, see the NOTES and BUGS sections. +If no certificate should be set, "0" has to be returned and no certificate +will be sent. A negative return value will suspend the handshake and the +handshake function will return immediately. \fBSSL_get_error\fR\|(3) +will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was +suspended. The next call to the handshake function will again lead to the call +of \fIclient_cert_cb\fR. It is the job of the \fIclient_cert_cb\fR to store information +about the state of the last call, if required to continue. +.SH NOTES +.IX Header "NOTES" +During a handshake (or renegotiation) a server may request a certificate +from the client. A client certificate must only be sent, when the server +did send the request. +.PP +When a certificate was set using the +\&\fBSSL_CTX_use_certificate\fR\|(3) family of functions, +it will be sent to the server. The TLS standard requires that only a +certificate is sent, if it matches the list of acceptable CAs sent by the +server. This constraint is violated by the default behavior of the OpenSSL +library. Using the callback function it is possible to implement a proper +selection routine or to allow a user interaction to choose the certificate to +be sent. +.PP +If a callback function is defined and no certificate was yet defined for the +SSL object, the callback function will be called. +If the callback function returns a certificate, the OpenSSL library +will try to load the private key and certificate data into the SSL +object using the \fBSSL_use_certificate()\fR and \fBSSL_use_private_key()\fR functions. +Thus it will permanently install the certificate and key for this SSL +object. It will not be reset by calling \fBSSL_clear\fR\|(3). +If the callback returns no certificate, the OpenSSL library will not send +a certificate. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_get_client_cert_cb()\fR returns function pointer of \fIclient_cert_cb\fR or +NULL if the callback is not set. +.SH BUGS +.IX Header "BUGS" +The \fIclient_cert_cb\fR cannot return a complete certificate chain, it can +only return one client certificate. If the chain only has a length of 2, +the root CA certificate may be omitted according to the TLS standard and +thus a standard conforming answer can be sent to the server. For a +longer chain, the client must send the complete chain (with the option +to leave out the root CA certificate). This can only be accomplished by +either adding the intermediate CA certificates into the trusted +certificate store for the SSL_CTX object (resulting in having to add +CA certificates that otherwise maybe would not be trusted), or by adding +the chain certificates using the +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3) +function, which is only available for the SSL_CTX object as a whole and that +therefore probably can only apply for one client certificate, making +the concept of the callback function (to allow the choice from several +certificates) questionable. +.PP +Once the SSL object has been used in conjunction with the callback function, +the certificate will be set for the SSL object and will not be cleared +even when \fBSSL_clear\fR\|(3) is being called. It is therefore +mandatory to destroy the SSL object using \fBSSL_free\fR\|(3) +and create a new one to return to the previous state. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_use_certificate\fR\|(3), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3), +\&\fBSSL_get_client_CA_list\fR\|(3), +\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_client_hello_cb.3 b/static/netbsd/man3/SSL_CTX_set_client_hello_cb.3 new file mode 100644 index 00000000..5f7ec082 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_client_hello_cb.3 @@ -0,0 +1,215 @@ +.\" $NetBSD: SSL_CTX_set_client_hello_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_client_hello_cb 3" +.TH SSL_CTX_set_client_hello_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_client_hello_get0_legacy_version, SSL_client_hello_get0_random, SSL_client_hello_get0_session_id, SSL_client_hello_get0_ciphers, SSL_client_hello_get0_compression_methods, SSL_client_hello_get1_extensions_present, SSL_client_hello_get_extension_order, SSL_client_hello_get0_ext \- callback functions for early server\-side ClientHello processing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 10 +\& typedef int (*SSL_client_hello_cb_fn)(SSL *s, int *al, void *arg); +\& void SSL_CTX_set_client_hello_cb(SSL_CTX *c, SSL_client_hello_cb_fn *f, +\& void *arg); +\& int SSL_client_hello_isv2(SSL *s); +\& unsigned int SSL_client_hello_get0_legacy_version(SSL *s); +\& size_t SSL_client_hello_get0_random(SSL *s, const unsigned char **out); +\& size_t SSL_client_hello_get0_session_id(SSL *s, const unsigned char **out); +\& size_t SSL_client_hello_get0_ciphers(SSL *s, const unsigned char **out); +\& size_t SSL_client_hello_get0_compression_methods(SSL *s, +\& const unsigned char **out); +\& int SSL_client_hello_get1_extensions_present(SSL *s, int **out, +\& size_t *outlen); +\& int SSL_client_hello_get_extension_order(SSL *s, uint16_t *exts, +\& size_t *num_exts); +\& int SSL_client_hello_get0_ext(SSL *s, unsigned int type, const unsigned char **out, +\& size_t *outlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_client_hello_cb()\fR sets the callback function, which is automatically +called during the early stages of ClientHello processing on the server. +The argument supplied when setting the callback is passed back to the +callback at run time. A callback that returns failure (0) will cause the +connection to terminate, and callbacks returning failure should indicate +what alert value is to be sent in the \fBal\fR parameter. A callback may +also return a negative value to suspend the handshake, and the handshake +function will return immediately. \fBSSL_get_error\fR\|(3) will return +SSL_ERROR_WANT_CLIENT_HELLO_CB to indicate that the handshake was suspended. +It is the job of the ClientHello callback to store information about the state +of the last call if needed to continue. On the next call into the handshake +function, the ClientHello callback will be called again, and, if it returns +success, normal handshake processing will continue from that point. +.PP +\&\fBSSL_client_hello_isv2()\fR indicates whether the ClientHello was carried in a +SSLv2 record and is in the SSLv2 format. The SSLv2 format has substantial +differences from the normal SSLv3 format, including using three bytes per +cipher suite, and not allowing extensions. Additionally, the SSLv2 format +\&\*(Aqchallenge\*(Aq field is exposed via \fBSSL_client_hello_get0_random()\fR, padded to +SSL3_RANDOM_SIZE bytes with zeros if needed. For SSLv2 format ClientHellos, +\&\fBSSL_client_hello_get0_compression_methods()\fR returns a dummy list that only includes +the null compression method, since the SSLv2 format does not include a +mechanism by which to negotiate compression. +.PP +\&\fBSSL_client_hello_get0_random()\fR, \fBSSL_client_hello_get0_session_id()\fR, +\&\fBSSL_client_hello_get0_ciphers()\fR, and +\&\fBSSL_client_hello_get0_compression_methods()\fR provide access to the corresponding +ClientHello fields, returning the field length and optionally setting an out +pointer to the octets of that field. +.PP +Similarly, \fBSSL_client_hello_get0_ext()\fR provides access to individual extensions +from the ClientHello on a per\-extension basis. For the provided wire +protocol extension type value, the extension value and length are returned +in the output parameters (if present). +.PP +\&\fBSSL_client_hello_get1_extensions_present()\fR can be used prior to +\&\fBSSL_client_hello_get0_ext()\fR, to determine which extensions are present in the +ClientHello before querying for them. The \fBout\fR and \fBoutlen\fR parameters are +both required, and on success the caller must release the storage allocated for +\&\fB*out\fR using \fBOPENSSL_free()\fR. The contents of \fB*out\fR is an array of integers +holding the numerical value of the TLS extension types in the order they appear +in the ClientHello. \fB*outlen\fR contains the number of elements in the array. +In situations when the ClientHello has no extensions, the function will return +success with \fB*out\fR set to NULL and \fB*outlen\fR set to 0. +Note that \fBSSL_client_hello_get1_extensions_present()\fR returns only recognised +extensions; therefore, unrecognised (including GREASE) extensions will not +appear in the output. +.PP +\&\fBSSL_client_hello_get_extension_order()\fR is similar to +\&\fBSSL_client_hello_get1_extensions_present()\fR, without internal memory allocation. +When called with \fBexts\fR set to NULL, returns the number of extensions +(e.g., to allocate storage for a subsequent call). Otherwise, \fB*exts\fR is populated +with the ExtensionType values in the order that the corresponding extensions +appeared in the ClientHello. \fB*num_exts\fR is an input/output parameter, used +as input to supply the size of storage allocated by the caller, and as output to +indicate how many ExtensionType values were written. If the input \fB*num_exts\fR +is smaller then the number of extensions in question, that is treated as an error. +A subsequent call with \fBexts\fR set to NULL can retrieve the size of storage needed. +A ClientHello that contained no extensions is treated as success, with \fB*num_exts\fR +set to 0. +.SH NOTES +.IX Header "NOTES" +The ClientHello callback provides a vast window of possibilities for application +code to affect the TLS handshake. A primary use of the callback is to +allow the server to examine the server name indication extension provided +by the client in order to select an appropriate certificate to present, +and make other configuration adjustments relevant to that server name +and its configuration. Such configuration changes can include swapping out +the associated SSL_CTX pointer, modifying the server\*(Aqs list of permitted TLS +versions, changing the server\*(Aqs cipher list in response to the client\*(Aqs +cipher list, etc. +.PP +It is also recommended that applications utilize a ClientHello callback and +not use a servername callback, in order to avoid unexpected behavior that +occurs due to the relative order of processing between things like session +resumption and the historical servername callback. +.PP +The SSL_client_hello_* family of functions may only be called from code +executing within a ClientHello callback. +.PP +The SSL_client_hello_get0_*() functions return raw ClientHello data, whereas +\&\fBSSL_client_hello_get1_extensions_present()\fR returns only recognized extensions +(so unknown/GREASE\-extensions are not included). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The application\*(Aqs supplied ClientHello callback returns +SSL_CLIENT_HELLO_SUCCESS on success, SSL_CLIENT_HELLO_ERROR on failure, and +SSL_CLIENT_HELLO_RETRY to suspend processing. +.PP +\&\fBSSL_client_hello_isv2()\fR returns 1 for SSLv2\-format ClientHellos and 0 otherwise. +.PP +\&\fBSSL_client_hello_get0_random()\fR, \fBSSL_client_hello_get0_session_id()\fR, +\&\fBSSL_client_hello_get0_ciphers()\fR, and +\&\fBSSL_client_hello_get0_compression_methods()\fR return the length of the +corresponding ClientHello fields. If zero is returned, the output pointer +should not be assumed to be valid. +.PP +\&\fBSSL_client_hello_get0_ext()\fR returns 1 if the extension of type \*(Aqtype\*(Aq is present, and +0 otherwise. +.PP +\&\fBSSL_client_hello_get1_extensions_present()\fR returns 1 on success and 0 on failure. +.PP +\&\fBSSL_client_hello_get_extension_order()\fR returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_tlsext_servername_callback\fR\|(3), +\&\fBSSL_bytes_to_cipher_list\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The SSL ClientHello callback, \fBSSL_client_hello_isv2()\fR, +\&\fBSSL_client_hello_get0_random()\fR, \fBSSL_client_hello_get0_session_id()\fR, +\&\fBSSL_client_hello_get0_ciphers()\fR, \fBSSL_client_hello_get0_compression_methods()\fR, +\&\fBSSL_client_hello_get0_ext()\fR, and \fBSSL_client_hello_get1_extensions_present()\fR +were added in OpenSSL 1.1.1. +\&\fBSSL_client_hello_get_extension_order()\fR +was added in OpenSSL 3.2.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_ct_validation_callback.3 b/static/netbsd/man3/SSL_CTX_set_ct_validation_callback.3 new file mode 100644 index 00000000..d98391b5 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_ct_validation_callback.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: SSL_CTX_set_ct_validation_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_ct_validation_callback 3" +.TH SSL_CTX_set_ct_validation_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ssl_ct_validation_cb, +SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, +SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, +SSL_ct_is_enabled, SSL_CTX_ct_is_enabled \- +control Certificate Transparency policy +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, +\& const STACK_OF(SCT) *scts, void *arg); +\& +\& int SSL_enable_ct(SSL *s, int validation_mode); +\& int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); +\& int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, +\& void *arg); +\& int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, +\& ssl_ct_validation_cb callback, +\& void *arg); +\& void SSL_disable_ct(SSL *s); +\& void SSL_CTX_disable_ct(SSL_CTX *ctx); +\& int SSL_ct_is_enabled(const SSL *s); +\& int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_enable_ct()\fR and \fBSSL_CTX_enable_ct()\fR enable the processing of signed +certificate timestamps (SCTs) either for a given SSL connection or for all +connections that share the given SSL context, respectively. +This is accomplished by setting a built\-in CT validation callback. +The behaviour of the callback is determined by the \fBvalidation_mode\fR argument, +which can be either of \fBSSL_CT_VALIDATION_PERMISSIVE\fR or +\&\fBSSL_CT_VALIDATION_STRICT\fR as described below. +.PP +If \fBvalidation_mode\fR is equal to \fBSSL_CT_VALIDATION_STRICT\fR, then in a full +TLS handshake with the verification mode set to \fBSSL_VERIFY_PEER\fR, if the peer +presents no valid SCTs the handshake will be aborted. +If the verification mode is \fBSSL_VERIFY_NONE\fR, the handshake will continue +despite lack of valid SCTs. +However, in that case if the verification status before the built\-in callback +was \fBX509_V_OK\fR it will be set to \fBX509_V_ERR_NO_VALID_SCTS\fR after the +callback. +Applications can call \fBSSL_get_verify_result\fR\|(3) to check the status at +handshake completion, even after session resumption since the verification +status is part of the saved session state. +See \fBSSL_set_verify\fR\|(3), <\fBSSL_get_verify_result\fR\|(3)>, \fBSSL_session_reused\fR\|(3). +.PP +If \fBvalidation_mode\fR is equal to \fBSSL_CT_VALIDATION_PERMISSIVE\fR, then the +handshake continues, and the verification status is not modified, regardless of +the validation status of any SCTs. +The application can still inspect the validation status of the SCTs at +handshake completion. +Note that with session resumption there will not be any SCTs presented during +the handshake. +Therefore, in applications that delay SCT policy enforcement until after +handshake completion, such delayed SCT checks should only be performed when the +session is not resumed. +.PP +\&\fBSSL_set_ct_validation_callback()\fR and \fBSSL_CTX_set_ct_validation_callback()\fR +register a custom callback that may implement a different policy than either of +the above. +This callback can examine the peer\*(Aqs SCTs and determine whether they are +sufficient to allow the connection to continue. +The TLS handshake is aborted if the verification mode is not \fBSSL_VERIFY_NONE\fR +and the callback returns a non\-positive result. +.PP +An arbitrary callback data argument, \fBarg\fR, can be passed in when setting +the callback. +This will be passed to the callback whenever it is invoked. +Ownership of this context remains with the caller. +.PP +If no callback is set, SCTs will not be requested and Certificate Transparency +validation will not occur. +.PP +No callback will be invoked when the peer presents no certificate, e.g. by +employing an anonymous (aNULL) cipher suite. +In that case the handshake continues as it would had no callback been +requested. +Callbacks are also not invoked when the peer certificate chain is invalid or +validated via \fBDANE\-TA\fR\|(2) or \fBDANE\-EE\fR\|(3) TLSA records which use a private X.509 +PKI, or no X.509 PKI at all, respectively. +Clients that require SCTs are expected to not have enabled any aNULL ciphers +nor to have specified server verification via \fBDANE\-TA\fR\|(2) or \fBDANE\-EE\fR\|(3) TLSA +records. +.PP +\&\fBSSL_disable_ct()\fR and \fBSSL_CTX_disable_ct()\fR turn off CT processing, whether +enabled via the built\-in or the custom callbacks, by setting a NULL callback. +These may be implemented as macros. +.PP +\&\fBSSL_ct_is_enabled()\fR and \fBSSL_CTX_ct_is_enabled()\fR return 1 if CT processing is +enabled via either \fBSSL_enable_ct()\fR or a non\-null custom callback, and 0 +otherwise. +.SH NOTES +.IX Header "NOTES" +When SCT processing is enabled, OCSP stapling will be enabled. This is because +one possible source of SCTs is the OCSP response from a server. +.PP +The time returned by \fBSSL_SESSION_get_time_ex()\fR will be used to evaluate whether any +presented SCTs have timestamps that are in the future (and therefore invalid). +.SH RESTRICTIONS +.IX Header "RESTRICTIONS" +Certificate Transparency validation cannot be enabled and so a callback cannot +be set if a custom client extension handler has been registered to handle SCT +extensions (\fBTLSEXT_TYPE_signed_certificate_timestamp\fR). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_enable_ct()\fR, \fBSSL_CTX_enable_ct()\fR, \fBSSL_CTX_set_ct_validation_callback()\fR and +\&\fBSSL_set_ct_validation_callback()\fR return 1 if the \fBcallback\fR is successfully +set. +They return 0 if an error occurs, e.g. a custom client extension handler has +been setup to handle SCTs. +.PP +\&\fBSSL_disable_ct()\fR and \fBSSL_CTX_disable_ct()\fR do not return a result. +.PP +\&\fBSSL_CTX_ct_is_enabled()\fR and \fBSSL_ct_is_enabled()\fR return a 1 if a non\-null CT +validation callback is set, or 0 if no callback (or equivalently a NULL +callback) is set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +<\fBSSL_get_verify_result\fR\|(3)>, +\&\fBSSL_session_reused\fR\|(3), +\&\fBSSL_set_verify\fR\|(3), +\&\fBSSL_CTX_set_verify\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_ctlog_list_file.3 b/static/netbsd/man3/SSL_CTX_set_ctlog_list_file.3 new file mode 100644 index 00000000..7cc4a363 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_ctlog_list_file.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: SSL_CTX_set_ctlog_list_file.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_ctlog_list_file 3" +.TH SSL_CTX_set_ctlog_list_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file \- +load a Certificate Transparency log list from a file +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx); +\& int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_default_ctlog_list_file()\fR loads a list of Certificate Transparency +(CT) logs from the default file location, "ct_log_list.cnf", found in the +directory where OpenSSL is installed. +.PP +\&\fBSSL_CTX_set_ctlog_list_file()\fR loads a list of CT logs from a specific path. +See \fBCTLOG_STORE_new\fR\|(3) for the file format. +.SH NOTES +.IX Header "NOTES" +These functions will not clear the existing CT log list \- it will be appended +to. To replace the existing list, use \fBSSL_CTX_set0_ctlog_store\fR\|(3) first. +.PP +If an error occurs whilst parsing a particular log entry in the file, that log +entry will be skipped. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_default_ctlog_list_file()\fR and \fBSSL_CTX_set_ctlog_list_file()\fR +return 1 if the log list is successfully loaded, and 0 if an error occurs. In +the case of an error, the log list may have been partially loaded. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_ct_validation_callback\fR\|(3), +\&\fBCTLOG_STORE_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_custom_cli_ext.3 b/static/netbsd/man3/SSL_CTX_set_custom_cli_ext.3 new file mode 100644 index 00000000..61f545de --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_custom_cli_ext.3 @@ -0,0 +1,264 @@ +.\" $NetBSD: SSL_CTX_set_custom_cli_ext.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_custom_cli_ext 3" +.TH SSL_CTX_set_custom_cli_ext 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext \- custom TLS extension handling +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, +\& custom_ext_add_cb add_cb, +\& custom_ext_free_cb free_cb, void *add_arg, +\& custom_ext_parse_cb parse_cb, +\& void *parse_arg); +\& +\& int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, +\& custom_ext_add_cb add_cb, +\& custom_ext_free_cb free_cb, void *add_arg, +\& custom_ext_parse_cb parse_cb, +\& void *parse_arg); +\& +\& int SSL_extension_supported(unsigned int ext_type); +\& +\& typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char **out, +\& size_t *outlen, int *al, +\& void *add_arg); +\& +\& typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char *out, +\& void *add_arg); +\& +\& typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char *in, +\& size_t inlen, int *al, +\& void *parse_arg); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_CTX_add_client_custom_ext()\fR adds a custom extension for a \s-1TLS\s0 client +with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and +\&\fBparse_cb\fR. +.PP +\&\fISSL_CTX_add_server_custom_ext()\fR adds a custom extension for a \s-1TLS\s0 server +with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and +\&\fBparse_cb\fR. +.PP +In both cases the extension type must not be handled by OpenSSL internally +or an error occurs. +.PP +\&\fISSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled +internally by OpenSSL and 0 otherwise. +.SH "EXTENSION CALLBACKS" +.IX Header "EXTENSION CALLBACKS" +The callback \fBadd_cb\fR is called to send custom extension data to be +included in ClientHello for \s-1TLS\s0 clients or ServerHello for servers. The +\&\fBext_type\fR parameter is set to the extension type which will be added and +\&\fBadd_arg\fR to the value set when the extension handler was added. +.PP +If the application wishes to include the extension \fBext_type\fR it should +set \fB*out\fR to the extension data, set \fB*outlen\fR to the length of the +extension data and return 1. +.PP +If the \fBadd_cb\fR does not wish to include the extension it must return 0. +.PP +If \fBadd_cb\fR returns \-1 a fatal handshake error occurs using the \s-1TLS\s0 +alert value specified in \fB*al\fR. +.PP +For clients (but not servers) if \fBadd_cb\fR is set to \s-1NULL\s0 a zero length +extension is added for \fBext_type\fR. +.PP +For clients every registered \fBadd_cb\fR is always called to see if the +application wishes to add an extension to ClientHello. +.PP +For servers every registered \fBadd_cb\fR is called once if and only if the +corresponding extension was received in ClientHello to see if the application +wishes to add the extension to ServerHello. That is, if no corresponding extension +was received in ClientHello then \fBadd_cb\fR will not be called. +.PP +If an extension is added (that is \fBadd_cb\fR returns 1) \fBfree_cb\fR is called +(if it is set) with the value of \fBout\fR set by the add callback. It can be +used to free up any dynamic extension data set by \fBadd_cb\fR. Since \fBout\fR is +constant (to permit use of constant data in \fBadd_cb\fR) applications may need to +cast away const to free the data. +.PP +The callback \fBparse_cb\fR receives data for \s-1TLS\s0 extensions. For \s-1TLS\s0 clients +the extension data will come from ServerHello and for \s-1TLS\s0 servers it will +come from ClientHello. +.PP +The extension data consists of \fBinlen\fR bytes in the buffer \fBin\fR for the +extension \fBextension_type\fR. +.PP +If the \fBparse_cb\fR considers the extension data acceptable it must return +1. If it returns 0 or a negative value a fatal handshake error occurs +using the \s-1TLS\s0 alert value specified in \fB*al\fR. +.PP +The buffer \fBin\fR is a temporary internal buffer which will not be valid after +the callback returns. +.SH "NOTES" +.IX Header "NOTES" +The \fBadd_arg\fR and \fBparse_arg\fR parameters can be set to arbitrary values +which will be passed to the corresponding callbacks. They can, for example, +be used to store the extension data received in a convenient structure or +pass the extension data to be added or freed when adding extensions. +.PP +The \fBext_type\fR parameter corresponds to the \fBextension_type\fR field of +\&\s-1RFC5246\s0 et al. It is \fBnot\fR a \s-1NID.\s0 +.PP +If the same custom extension type is received multiple times a fatal +\&\fBdecode_error\fR alert is sent and the handshake aborts. If a custom extension +is received in ServerHello which was not sent in ClientHello a fatal +\&\fBunsupported_extension\fR alert is sent and the handshake is aborted. The +ServerHello \fBadd_cb\fR callback is only called if the corresponding extension +was received in ClientHello. This is compliant with the \s-1TLS\s0 specifications. +This behaviour ensures that each callback is called at most once and that +an application can never send unsolicited extensions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fISSL_CTX_add_client_custom_ext()\fR and \fISSL_CTX_add_server_custom_ext()\fR return 1 for +success and 0 for failure. A failure can occur if an attempt is made to +add the same \fBext_type\fR more than once, if an attempt is made to use an +extension type handled internally by OpenSSL or if an internal error occurs +(for example a memory allocation failure). +.PP +\&\fISSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled +internally by OpenSSL and 0 otherwise. diff --git a/static/netbsd/man3/SSL_CTX_set_default_passwd_cb.3 b/static/netbsd/man3/SSL_CTX_set_default_passwd_cb.3 new file mode 100644 index 00000000..c52ac66f --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_default_passwd_cb.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: SSL_CTX_set_default_passwd_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_default_passwd_cb 3" +.TH SSL_CTX_set_default_passwd_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, +SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, +SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, +SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata \- set or +get passwd callback for encrypted PEM file handling +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); +\& void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); +\& pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); +\& void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); +\& +\& void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb); +\& void SSL_set_default_passwd_cb_userdata(SSL *s, void *u); +\& pem_password_cb *SSL_get_default_passwd_cb(SSL *s); +\& void *SSL_get_default_passwd_cb_userdata(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_default_passwd_cb()\fR sets the default password callback called +when loading/storing a PEM certificate with encryption. +.PP +\&\fBSSL_CTX_set_default_passwd_cb_userdata()\fR sets a pointer to userdata, \fBu\fR, +which will be provided to the password callback on invocation. +.PP +\&\fBSSL_CTX_get_default_passwd_cb()\fR returns a function pointer to the password +callback currently set in \fBctx\fR. If no callback was explicitly set, the +NULL pointer is returned. +.PP +\&\fBSSL_CTX_get_default_passwd_cb_userdata()\fR returns a pointer to the userdata +currently set in \fBctx\fR. If no userdata was explicitly set, the NULL pointer +is returned. +.PP +\&\fBSSL_set_default_passwd_cb()\fR, \fBSSL_set_default_passwd_cb_userdata()\fR, +\&\fBSSL_get_default_passwd_cb()\fR and \fBSSL_get_default_passwd_cb_userdata()\fR perform +the same function as their SSL_CTX counterparts, but using an SSL object. +.PP +The password callback, which must be provided by the application, hands back the +password to be used during decryption. +On invocation a pointer to userdata +is provided. The function must store the password into the provided buffer +\&\fBbuf\fR which is of size \fBsize\fR. The actual length of the password must +be returned to the calling function. \fBrwflag\fR indicates whether the +callback is used for reading/decryption (rwflag=0) or writing/encryption +(rwflag=1). +For more details, see \fBpem_password_cb\fR\|(3). +.SH NOTES +.IX Header "NOTES" +When loading or storing private keys, a password might be supplied to +protect the private key. The way this password can be supplied may depend +on the application. If only one private key is handled, it can be practical +to have the callback handle the password dialog interactively. If several +keys have to be handled, it can be practical to ask for the password once, +then keep it in memory and use it several times. In the last case, the +password could be stored into the userdata storage and the +callback only returns the password already stored. +.PP +When asking for the password interactively, the callback can use +\&\fBrwflag\fR to check, whether an item shall be encrypted (rwflag=1). +In this case the password dialog may ask for the same password twice +for comparison in order to catch typos, that would make decryption +impossible. +.PP +Other items in PEM formatting (certificates) can also be encrypted, it is +however not usual, as certificate information is considered public. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions do not provide diagnostic information. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following example returns the password provided as userdata to the +calling function. The password is considered to be a \*(Aq\e0\*(Aq terminated +string. If the password does not fit into the buffer, the password is +truncated. +.PP +.Vb 6 +\& int my_cb(char *buf, int size, int rwflag, void *u) +\& { +\& strncpy(buf, (char *)u, size); +\& buf[size \- 1] = \*(Aq\e0\*(Aq; +\& return strlen(buf); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_use_certificate\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_get_default_passwd_cb()\fR, \fBSSL_CTX_get_default_passwd_cb_userdata()\fR, +\&\fBSSL_set_default_passwd_cb()\fR and \fBSSL_set_default_passwd_cb_userdata()\fR were +added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_domain_flags.3 b/static/netbsd/man3/SSL_CTX_set_domain_flags.3 new file mode 100644 index 00000000..a4b826f3 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_domain_flags.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: SSL_CTX_set_domain_flags.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_domain_flags 3" +.TH SSL_CTX_set_domain_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_domain_flags, SSL_CTX_get_domain_flags, SSL_get_domain_flags, +SSL_DOMAIN_FLAG_SINGLE_THREAD, +SSL_DOMAIN_FLAG_MULTI_THREAD, +SSL_DOMAIN_FLAG_THREAD_ASSISTED, +SSL_DOMAIN_FLAG_BLOCKING, +SSL_DOMAIN_FLAG_LEGACY_BLOCKING +\&\- control the concurrency model used by a QUIC domain +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_DOMAIN_FLAG_SINGLE_THREAD +\& #define SSL_DOMAIN_FLAG_MULTI_THREAD +\& #define SSL_DOMAIN_FLAG_LEGACY_BLOCKING +\& #define SSL_DOMAIN_FLAG_BLOCKING +\& #define SSL_DOMAIN_FLAG_THREAD_ASSISTED +\& +\& int SSL_CTX_set_domain_flags(SSL_CTX *ctx, uint64_t flags); +\& int SSL_CTX_get_domain_flags(SSL_CTX *ctx, uint64_t *flags); +\& +\& int SSL_get_domain_flags(SSL *ssl, uint64_t *flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_domain_flags()\fR and \fBSSL_CTX_get_domain_flags()\fR set and get the QUIC +domain flags on a \fBSSL_CTX\fR using a QUIC \fBSSL_METHOD\fR. These flags determine +the concurrency model which is used for a QUIC domain. A detailed introduction +to these concepts can be found in \fBopenssl\-quic\-concurrency\fR\|(7). +.PP +Applications may use either one the flags here: +.IP \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_SINGLE_THREAD" +Specifying this flag configures the Single\-Threaded Concurrency Model (SCM). +.IP \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR 4 +.IX Item "SSL_DOMAIN_FLAG_MULTI_THREAD" +Specifying this flag configures the Contentive Concurrency Model (CCM) (unless +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR is also specified). +.Sp +If OpenSSL was built without thread support, this is identical to +\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR. +.IP \fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR 4 +.IX Item "SSL_DOMAIN_FLAG_THREAD_ASSISTED" +Specifying this flag configures the Thread\-Assisted Concurrency Model (TACM). +It implies \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR and \fBSSL_DOMAIN_FLAG_BLOCKING\fR. +.Sp +This concurrency model is not available if OpenSSL was built without thread +support, in which case attempting to configure it will result in an error. +.IP \fBSSL_DOMAIN_FLAG_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_BLOCKING" +Enable reliable support for blocking I/O calls, allocating whatever OS resources +are necessary to realise this. If this flag is specified, +\&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is ignored. +.IP \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR 4 +.IX Item "SSL_DOMAIN_FLAG_LEGACY_BLOCKING" +Enables legacy blocking compatibility mode. See +"Legacy Blocking Support Compatibility" in \fBopenssl\-quic\-concurrency\fR\|(7). +.PP +Mutually exclusive flag combinations result in an error (for example, combining +\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR and \fBSSL_DOMAIN_FLAG_MULTI_THREADED\fR). +.PP +Because exactly one concurrency model must be chosen, the domain flags cannot be +set to 0 and attempting to do so will result in an error. +.PP +Changing these flags using \fBSSL_CTX_set_domain_flags()\fR has no effect on QUIC +domains which have already been created. +.PP +The default set of domain flags set on a newly created \fBSSL_CTX\fR may vary by +OpenSSL version, chosen \fBSSL_METHOD\fR, and operating environment. See +\&\fBopenssl\-quic\-concurrency\fR\|(7) for details. An application can retrieve the +default domain flags by calling \fBSSL_CTX_get_domain_flags()\fR immediately after +constructing a \fBSSL_CTX\fR. +.PP +\&\fBSSL_get_domain_flags()\fR retrieves the domain flags which are effective for a QUIC +domain when called on any QUIC SSL object under that domain. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_domain_flags()\fR, \fBSSL_CTX_get_domain_flags()\fR and +\&\fBSSL_get_domain_flags()\fR return 1 on success and 0 on failure. +.PP +\&\fBSSL_CTX_set_domain_flags()\fR fails if called with a set of flags which are +inconsistent or which cannot be supported given the current environment. +.PP +\&\fBSSL_CTX_set_domain_flags()\fR and \fBSSL_CTX_get_domain_flags()\fR fail if called on a +\&\fBSSL_CTX\fR which is not using a QUIC \fBSSL_METHOD\fR. +.PP +\&\fBSSL_get_domain_flags()\fR fails if called on a non\-QUIC SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_new_domain\fR\|(3), \fBopenssl\-quic\-concurrency\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_ex_data.3 b/static/netbsd/man3/SSL_CTX_set_ex_data.3 new file mode 100644 index 00000000..305fd113 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_ex_data.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: SSL_CTX_set_ex_data.3,v 1.4 2020/12/10 00:33:13 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_ex_data 3" +.TH SSL_CTX_set_ex_data 3 "2018-09-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_CTX_get_ex_data, SSL_CTX_set_ex_data, +SSL_get_ex_data, SSL_set_ex_data +\&\- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx); +\& +\& int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg); +\& +\& void *SSL_get_ex_data(const SSL *s, int idx); +\& +\& int SSL_set_ex_data(SSL *s, int idx, void *arg); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +SSL*\fB_set_ex_data()\fR functions can be used to store arbitrary user data into the +\&\fB\s-1SSL_CTX\s0\fR, or \fB\s-1SSL\s0\fR object. The user must supply a unique index +which they can subsequently use to retrieve the data using SSL*\fB_get_ex_data()\fR. +.PP +For more detailed information see \fBCRYPTO_get_ex_data\fR\|(3) and +\&\fBCRYPTO_set_ex_data\fR\|(3) which implement these functions and +\&\fBCRYPTO_get_ex_new_index\fR\|(3) for generating a unique index. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The SSL*\fB_set_ex_data()\fR functions return 1 if the item is successfully stored +and 0 if it is not. +The SSL*\fB_get_ex_data()\fR functions return the ex_data pointer if successful, +otherwise \s-1NULL.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBCRYPTO_get_ex_data\fR\|(3), \fBCRYPTO_set_ex_data\fR\|(3), +\&\fBCRYPTO_get_ex_new_index\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_generate_session_id.3 b/static/netbsd/man3/SSL_CTX_set_generate_session_id.3 new file mode 100644 index 00000000..29d181a9 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,196 @@ +.\" $NetBSD: SSL_CTX_set_generate_session_id.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_generate_session_id 3" +.TH SSL_CTX_set_generate_session_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, +SSL_has_matching_session_id, GEN_SESSION_CB +\&\- manipulate generation of SSL session IDs (server only) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*GEN_SESSION_CB)(SSL *ssl, unsigned char *id, +\& unsigned int *id_len); +\& +\& int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); +\& int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); +\& int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, +\& unsigned int id_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_generate_session_id()\fR sets the callback function for generating +new session ids for SSL/TLS sessions for \fBctx\fR to be \fBcb\fR. +.PP +\&\fBSSL_set_generate_session_id()\fR sets the callback function for generating +new session ids for SSL/TLS sessions for \fBssl\fR to be \fBcb\fR. +.PP +\&\fBSSL_has_matching_session_id()\fR checks, whether a session with id \fBid\fR +(of length \fBid_len\fR) is already contained in the internal session cache +of the parent context of \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +When a new session is established between client and server, the server +generates a session id. The session id is an arbitrary sequence of bytes. +The length of the session id is between 1 and 32 bytes. The session id is not +security critical but must be unique for the server. Additionally, the session id is +transmitted in the clear when reusing the session so it must not contain +sensitive information. +.PP +Without a callback being set, an OpenSSL server will generate a unique +session id from pseudo random numbers of the maximum possible length. +Using the callback function, the session id can be changed to contain +additional information like e.g. a host id in order to improve load balancing +or external caching techniques. +.PP +The callback function receives a pointer to the memory location to put +\&\fBid\fR into and a pointer to the maximum allowed length \fBid_len\fR. The +buffer at location \fBid\fR is only guaranteed to have the size \fBid_len\fR. +The callback is only allowed to generate a shorter id and reduce \fBid_len\fR; +the callback \fBmust never\fR increase \fBid_len\fR or write to the location +\&\fBid\fR exceeding the given limit. +.PP +The location \fBid\fR is filled with 0x00 before the callback is called, so the +callback may only fill part of the possible length and leave \fBid_len\fR +untouched while maintaining reproducibility. +.PP +Since the sessions must be distinguished, session ids must be unique. +Without the callback a random number is used, so that the probability +of generating the same session id is extremely small (2^256 for SSLv3/TLSv1). +In order to assure the uniqueness of the generated session id, the callback must call +\&\fBSSL_has_matching_session_id()\fR and generate another id if a conflict occurs. +If an id conflict is not resolved, the handshake will fail. +If the application codes e.g. a unique host id, a unique process number, and +a unique sequence number into the session id, uniqueness could easily be +achieved without randomness added (it should however be taken care that +no confidential information is leaked this way). If the application can not +guarantee uniqueness, it is recommended to use the maximum \fBid_len\fR and +fill in the bytes not used to code special information with random data +to avoid collisions. +.PP +\&\fBSSL_has_matching_session_id()\fR will only query the internal session cache, +not the external one. Since the session id is generated before the +handshake is completed, it is not immediately added to the cache. If +another thread is using the same internal session cache, a race condition +can occur in that another thread generates the same session id. +Collisions can also occur when using an external session cache, since +the external cache is not tested with \fBSSL_has_matching_session_id()\fR +and the same race condition applies. +.PP +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_generate_session_id()\fR and \fBSSL_set_generate_session_id()\fR +return 1 on success and 0 for failure. +.PP +\&\fBSSL_has_matching_session_id()\fR returns 1 if another session with the +same id is already in the cache, or 0 otherwise. +.SH EXAMPLES +.IX Header "EXAMPLES" +The callback function listed will generate a session id with the +server id given, and will fill the rest with pseudo random bytes: +.PP +.Vb 1 +\& const char session_id_prefix = "www\-18"; +\& +\& #define MAX_SESSION_ID_ATTEMPTS 10 +\& static int generate_session_id(SSL *ssl, unsigned char *id, +\& unsigned int *id_len) +\& { +\& unsigned int count = 0; +\& +\& do { +\& RAND_pseudo_bytes(id, *id_len); +\& /* +\& * Prefix the session_id with the required prefix. NB: If our +\& * prefix is too long, clip it \- but there will be worse effects +\& * anyway, e.g. the server could only possibly create 1 session +\& * ID (i.e. the prefix!) so all future session negotiations will +\& * fail due to conflicts. +\& */ +\& memcpy(id, session_id_prefix, strlen(session_id_prefix) < *id_len ? +\& strlen(session_id_prefix) : *id_len); +\& } while (SSL_has_matching_session_id(ssl, id, *id_len) +\& && ++count < MAX_SESSION_ID_ATTEMPTS); +\& if (count >= MAX_SESSION_ID_ATTEMPTS) +\& return 0; +\& return 1; +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_version\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_info_callback.3 b/static/netbsd/man3/SSL_CTX_set_info_callback.3 new file mode 100644 index 00000000..ba1ba1d0 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_info_callback.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: SSL_CTX_set_info_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_info_callback 3" +.TH SSL_CTX_set_info_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_info_callback, +SSL_CTX_get_info_callback, +SSL_set_info_callback, +SSL_get_info_callback +\&\- handle information callback for SSL connections +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_info_callback(SSL_CTX *ctx, +\& void (*callback) (const SSL *ssl, int type, int val)); +\& +\& void (*SSL_CTX_get_info_callback(SSL_CTX *ctx)) (const SSL *ssl, int type, int val); +\& +\& void SSL_set_info_callback(SSL *ssl, +\& void (*callback) (const SSL *ssl, int type, int val)); +\& +\& void (*SSL_get_info_callback(const SSL *ssl)) (const SSL *ssl, int type, int val); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to +obtain state information for SSL objects created from \fBctx\fR during connection +setup and use. The setting for \fBctx\fR is overridden from the setting for +a specific SSL object, if specified. +When \fBcallback\fR is NULL, no callback function is used. +.PP +\&\fBSSL_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to +obtain state information for \fBssl\fR during connection setup and use. +When \fBcallback\fR is NULL, the callback setting currently valid for +\&\fBctx\fR is used. \fBssl\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_CTX_get_info_callback()\fR returns a pointer to the currently set information +callback function for \fBctx\fR. +.PP +\&\fBSSL_get_info_callback()\fR returns a pointer to the currently set information +callback function for \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +When setting up a connection and during use, it is possible to obtain state +information from the SSL/TLS engine. When set, an information callback function +is called whenever a significant event occurs such as: the state changes, +an alert appears, or an error occurs. +.PP +The callback function is called as \fBcallback(SSL *ssl, int where, int ret)\fR. +The \fBwhere\fR argument specifies information about where (in which context) +the callback function was called. If \fBret\fR is 0, an error condition occurred. +If an alert is handled, SSL_CB_ALERT is set and \fBret\fR specifies the alert +information. +.PP +\&\fBwhere\fR is a bit\-mask made up of the following bits: +.IP SSL_CB_LOOP 4 +.IX Item "SSL_CB_LOOP" +Callback has been called to indicate state change or some other significant +state machine event. This may mean that the callback gets invoked more than once +per state in some situations. +.IP SSL_CB_EXIT 4 +.IX Item "SSL_CB_EXIT" +Callback has been called to indicate exit of a handshake function. This will +happen after the end of a handshake, but may happen at other times too such as +on error or when IO might otherwise block and nonblocking is being used. +.IP SSL_CB_READ 4 +.IX Item "SSL_CB_READ" +Callback has been called during read operation. +.IP SSL_CB_WRITE 4 +.IX Item "SSL_CB_WRITE" +Callback has been called during write operation. +.IP SSL_CB_ALERT 4 +.IX Item "SSL_CB_ALERT" +Callback has been called due to an alert being sent or received. +.IP "SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)" 4 +.IX Item "SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)" +.PD 0 +.IP "SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)" 4 +.IX Item "SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)" +.IP "SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)" 4 +.IX Item "SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)" +.IP "SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)" 4 +.IX Item "SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)" +.IP "SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)" 4 +.IX Item "SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)" +.IP "SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)" 4 +.IX Item "SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)" +.IP SSL_CB_HANDSHAKE_START 4 +.IX Item "SSL_CB_HANDSHAKE_START" +.PD +Callback has been called because a new handshake is started. It also occurs when +resuming a handshake following a pause to handle early data. +.IP SSL_CB_HANDSHAKE_DONE 4 +.IX Item "SSL_CB_HANDSHAKE_DONE" +Callback has been called because a handshake is finished. It also occurs if the +handshake is paused to allow the exchange of early data. +.PP +The current state information can be obtained using the +\&\fBSSL_state_string\fR\|(3) family of functions. +.PP +The \fBret\fR information can be evaluated using the +\&\fBSSL_alert_type_string\fR\|(3) family of functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_info_callback()\fR does not provide diagnostic information. +.PP +\&\fBSSL_get_info_callback()\fR returns the current setting. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following example callback function prints state strings, information +about alerts being handled and error messages to the \fBbio_err\fR BIO. +.PP +.Vb 4 +\& void apps_ssl_info_callback(const SSL *s, int where, int ret) +\& { +\& const char *str; +\& int w = where & ~SSL_ST_MASK; +\& +\& if (w & SSL_ST_CONNECT) +\& str = "SSL_connect"; +\& else if (w & SSL_ST_ACCEPT) +\& str = "SSL_accept"; +\& else +\& str = "undefined"; +\& +\& if (where & SSL_CB_LOOP) { +\& BIO_printf(bio_err, "%s:%s\en", str, SSL_state_string_long(s)); +\& } else if (where & SSL_CB_ALERT) { +\& str = (where & SSL_CB_READ) ? "read" : "write"; +\& BIO_printf(bio_err, "SSL3 alert %s:%s:%s\en", str, +\& SSL_alert_type_string_long(ret), +\& SSL_alert_desc_string_long(ret)); +\& } else if (where & SSL_CB_EXIT) { +\& if (ret == 0) { +\& BIO_printf(bio_err, "%s:failed in %s\en", +\& str, SSL_state_string_long(s)); +\& } else if (ret < 0) { +\& BIO_printf(bio_err, "%s:error in %s\en", +\& str, SSL_state_string_long(s)); +\& } +\& } +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_state_string\fR\|(3), +\&\fBSSL_alert_type_string\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_keylog_callback.3 b/static/netbsd/man3/SSL_CTX_set_keylog_callback.3 new file mode 100644 index 00000000..ac2e0be0 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_keylog_callback.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: SSL_CTX_set_keylog_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_keylog_callback 3" +.TH SSL_CTX_set_keylog_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_keylog_callback, SSL_CTX_get_keylog_callback, +SSL_CTX_keylog_cb_func \- logging TLS key material +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef void (*SSL_CTX_keylog_cb_func)(const SSL *ssl, const char *line); +\& +\& void SSL_CTX_set_keylog_callback(SSL_CTX *ctx, SSL_CTX_keylog_cb_func cb); +\& SSL_CTX_keylog_cb_func SSL_CTX_get_keylog_callback(const SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_keylog_callback()\fR sets the TLS key logging callback. This callback +is called whenever TLS key material is generated or received, in order to allow +applications to store this keying material for debugging purposes. +.PP +\&\fBSSL_CTX_get_keylog_callback()\fR retrieves the previously set TLS key logging +callback. If no callback has been set, this will return NULL. When there is no +key logging callback, or if SSL_CTX_set_keylog_callback is called with NULL as +the value of cb, no logging of key material will be done. +.PP +The key logging callback is called with two items: the \fBssl\fR object associated +with the connection, and \fBline\fR, a string containing the key material in the +format used by NSS for its \fBSSLKEYLOGFILE\fR debugging output. To recreate that +file, the key logging callback should log \fBline\fR, followed by a newline. +\&\fBline\fR will always be a NUL\-terminated string. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_get_keylog_callback()\fR returns a pointer to \fBSSL_CTX_keylog_cb_func\fR or +NULL if the callback is not set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_max_cert_list.3 b/static/netbsd/man3/SSL_CTX_set_max_cert_list.3 new file mode 100644 index 00000000..18082432 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_max_cert_list.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: SSL_CTX_set_max_cert_list.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_max_cert_list 3" +.TH SSL_CTX_set_max_cert_list 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list \- manipulate allowed size for the peer\*(Aqs certificate chain +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); +\& long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); +\& +\& long SSL_set_max_cert_list(SSL *ssl, long size); +\& long SSL_get_max_cert_list(SSL *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_max_cert_list()\fR sets the maximum size allowed for the peer\*(Aqs +certificate chain for all SSL objects created from \fBctx\fR to be bytes. +The SSL objects inherit the setting valid for \fBctx\fR at the time +\&\fBSSL_new\fR\|(3) is being called. +.PP +\&\fBSSL_CTX_get_max_cert_list()\fR returns the currently set maximum size for \fBctx\fR. +.PP +\&\fBSSL_set_max_cert_list()\fR sets the maximum size allowed for the peer\*(Aqs +certificate chain for \fBssl\fR to be bytes. This setting stays valid +until a new value is set. +.PP +\&\fBSSL_get_max_cert_list()\fR returns the currently set maximum size for \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +During the handshake process, the peer may send a certificate chain. +The TLS/SSL standard does not give any maximum size of the certificate chain. +The OpenSSL library handles incoming data by a dynamically allocated buffer. +In order to prevent this buffer from growing without bounds due to data +received from a faulty or malicious peer, a maximum size for the certificate +chain is set. +.PP +The default value for the maximum certificate chain size is 100kB (30kB +on the 16\-bit DOS platform). This should be sufficient for usual certificate +chains (OpenSSL\*(Aqs default maximum chain length is 10, see +\&\fBSSL_CTX_set_verify\fR\|(3), and certificates +without special extensions have a typical size of 1\-2kB). +.PP +For special applications it can be necessary to extend the maximum certificate +chain size allowed to be sent by the peer, see e.g. the work on +"Internet X.509 Public Key Infrastructure Proxy Certificate Profile" +and "TLS Delegation Protocol" at http://www.ietf.org/ and +http://www.globus.org/ . +.PP +Under normal conditions it should never be necessary to set a value smaller +than the default, as the buffer is handled dynamically and only uses the +memory actually required by the data sent by the peer. +.PP +If the maximum certificate chain size allowed is exceeded, the handshake will +fail with an SSL_R_EXCESSIVE_MESSAGE_SIZE error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_max_cert_list()\fR and \fBSSL_set_max_cert_list()\fR return the previously +set value. +.PP +\&\fBSSL_CTX_get_max_cert_list()\fR and \fBSSL_get_max_cert_list()\fR return the currently +set value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), +\&\fBSSL_CTX_set_verify\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_min_proto_version.3 b/static/netbsd/man3/SSL_CTX_set_min_proto_version.3 new file mode 100644 index 00000000..f45596ff --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_min_proto_version.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: SSL_CTX_set_min_proto_version.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_min_proto_version 3" +.TH SSL_CTX_set_min_proto_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, +SSL_CTX_get_min_proto_version, SSL_CTX_get_max_proto_version, +SSL_set_min_proto_version, SSL_set_max_proto_version, +SSL_get_min_proto_version, SSL_get_max_proto_version \- Get and set minimum +and maximum supported protocol version +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version); +\& int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version); +\& int SSL_CTX_get_min_proto_version(SSL_CTX *ctx); +\& int SSL_CTX_get_max_proto_version(SSL_CTX *ctx); +\& +\& int SSL_set_min_proto_version(SSL *ssl, int version); +\& int SSL_set_max_proto_version(SSL *ssl, int version); +\& int SSL_get_min_proto_version(SSL *ssl); +\& int SSL_get_max_proto_version(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions get or set the minimum and maximum supported protocol versions +for the \fBctx\fR or \fBssl\fR. +This works in combination with the options set via +\&\fBSSL_CTX_set_options\fR\|(3) that also make it possible to disable +specific protocol versions. +Use these functions instead of disabling specific protocol versions. +.PP +Setting the minimum or maximum version to 0 (default), will enable protocol +versions down to the lowest version, or up to the highest version +supported by the library, respectively. The supported versions might be +controlled by system configuration. +.PP +Getters return 0 in case \fBctx\fR or \fBssl\fR have been configured to +automatically use the lowest or highest version supported by the library. +.PP +Currently supported versions are \fBSSL3_VERSION\fR, \fBTLS1_VERSION\fR, +\&\fBTLS1_1_VERSION\fR, \fBTLS1_2_VERSION\fR, \fBTLS1_3_VERSION\fR for TLS and +\&\fBDTLS1_VERSION\fR, \fBDTLS1_2_VERSION\fR for DTLS. +.PP +In the current version of OpenSSL only QUICv1 is supported in conjunction with +TLSv1.3. Calling these functions on a QUIC object has no effect. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These setter functions return 1 on success and 0 on failure. The getter +functions return the configured version or 0 for auto\-configuration of +lowest or highest protocol, respectively. +.SH NOTES +.IX Header "NOTES" +All these functions are implemented using macros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_options\fR\|(3), \fBSSL_CONF_cmd\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The setter functions were added in OpenSSL 1.1.0. The getter functions +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_mode.3 b/static/netbsd/man3/SSL_CTX_set_mode.3 new file mode 100644 index 00000000..a63bd52c --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_mode.3 @@ -0,0 +1,196 @@ +.\" $NetBSD: SSL_CTX_set_mode.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_mode 3" +.TH SSL_CTX_set_mode 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_mode, SSL_CTX_clear_mode, SSL_set_mode, SSL_clear_mode, SSL_CTX_get_mode, SSL_get_mode \- manipulate SSL engine mode +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); +\& long SSL_CTX_clear_mode(SSL_CTX *ctx, long mode); +\& long SSL_set_mode(SSL *ssl, long mode); +\& long SSL_clear_mode(SSL *ssl, long mode); +\& +\& long SSL_CTX_get_mode(SSL_CTX *ctx); +\& long SSL_get_mode(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_mode()\fR adds the mode set via bit\-mask in \fBmode\fR to \fBctx\fR. +Options already set before are not cleared. +\&\fBSSL_CTX_clear_mode()\fR removes the mode set via bit\-mask in \fBmode\fR from \fBctx\fR. +.PP +\&\fBSSL_set_mode()\fR adds the mode set via bit\-mask in \fBmode\fR to \fBssl\fR. +Options already set before are not cleared. +\&\fBSSL_clear_mode()\fR removes the mode set via bit\-mask in \fBmode\fR from \fBssl\fR. +.PP +\&\fBSSL_CTX_get_mode()\fR returns the mode set for \fBctx\fR. +.PP +\&\fBSSL_get_mode()\fR returns the mode set for \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +The following mode changes are available: +.IP SSL_MODE_ENABLE_PARTIAL_WRITE 4 +.IX Item "SSL_MODE_ENABLE_PARTIAL_WRITE" +Allow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success +when just a single record has been written). This works in a similar way for +\&\fBSSL_write()\fR. When not set (the default), \fBSSL_write_ex()\fR or \fBSSL_write()\fR will only +report success once the complete chunk was written. Once \fBSSL_write_ex()\fR or +\&\fBSSL_write()\fR returns successful, \fBr\fR bytes have been written and the next call +to \fBSSL_write_ex()\fR or \fBSSL_write()\fR must only send the n\-r bytes left, imitating +the behaviour of \fBwrite()\fR. +.Sp +This mode cannot be enabled while in the middle of an incomplete write +operation. +.IP SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER 4 +.IX Item "SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER" +Make it possible to retry \fBSSL_write_ex()\fR or \fBSSL_write()\fR with changed buffer +location (the buffer contents must stay the same). This is not the default to +avoid the misconception that nonblocking \fBSSL_write()\fR behaves like +nonblocking \fBwrite()\fR. +.IP SSL_MODE_AUTO_RETRY 4 +.IX Item "SSL_MODE_AUTO_RETRY" +During normal operations, non\-application data records might need to be sent or +received that the application is not aware of. +If a non\-application data record was processed, +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_read\fR\|(3) can return with a failure and indicate the +need to retry with \fBSSL_ERROR_WANT_READ\fR. +If such a non\-application data record was processed, the flag +\&\fBSSL_MODE_AUTO_RETRY\fR causes it to try to process the next record instead of +returning. +.Sp +In a nonblocking environment applications must be prepared to handle +incomplete read/write operations. +Setting \fBSSL_MODE_AUTO_RETRY\fR for a nonblocking \fBBIO\fR will process +non\-application data records until either no more data is available or +an application data record has been processed. +.Sp +In a blocking environment, applications are not always prepared to +deal with the functions returning intermediate reports such as retry +requests, and setting the \fBSSL_MODE_AUTO_RETRY\fR flag will cause the functions +to only return after successfully processing an application data record or a +failure. +.Sp +Turning off \fBSSL_MODE_AUTO_RETRY\fR can be useful with blocking \fBBIO\fRs in case +they are used in combination with something like \fBselect()\fR or \fBpoll()\fR. +Otherwise the call to \fBSSL_read()\fR or \fBSSL_read_ex()\fR might hang when a +non\-application record was sent and no application data was sent. +.IP SSL_MODE_RELEASE_BUFFERS 4 +.IX Item "SSL_MODE_RELEASE_BUFFERS" +When we no longer need a read buffer or a write buffer for a given SSL, +then release the memory we were using to hold it. +Using this flag can +save around 34k per idle SSL connection. +This flag has no effect on SSL v2 connections, or on DTLS connections. +.IP SSL_MODE_SEND_FALLBACK_SCSV 4 +.IX Item "SSL_MODE_SEND_FALLBACK_SCSV" +Send TLS_FALLBACK_SCSV in the ClientHello. +To be set only by applications that reconnect with a downgraded protocol +version; see draft\-ietf\-tls\-downgrade\-scsv\-00 for details. +.Sp +DO NOT ENABLE THIS if your application attempts a normal handshake. +Only use this in explicit fallback retries, following the guidance +in draft\-ietf\-tls\-downgrade\-scsv\-00. +.IP SSL_MODE_ASYNC 4 +.IX Item "SSL_MODE_ASYNC" +Enable asynchronous processing. TLS I/O operations may indicate a retry with +SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is +used to perform cryptographic operations. See \fBSSL_get_error\fR\|(3). +.IP SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG 4 +.IX Item "SSL_MODE_DTLS_SCTP_LABEL_LENGTH_BUG" +Older versions of OpenSSL had a bug in the computation of the label length +used for computing the endpoint\-pair shared secret. The bug was that the +terminating zero was included in the length of the label. Setting this option +enables this behaviour to allow interoperability with such broken +implementations. Please note that setting this option breaks interoperability +with correct implementations. This option only applies to DTLS over SCTP. +.PP +All modes are off by default except for SSL_MODE_AUTO_RETRY which is on by +default since 1.1.1. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_mode()\fR and \fBSSL_set_mode()\fR return the new mode bit\-mask +after adding \fBmode\fR. +.PP +\&\fBSSL_CTX_get_mode()\fR and \fBSSL_get_mode()\fR return the current bit\-mask. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or +\&\fBSSL_write\fR\|(3), \fBSSL_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +SSL_MODE_ASYNC was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_msg_callback.3 b/static/netbsd/man3/SSL_CTX_set_msg_callback.3 new file mode 100644 index 00000000..a0a0190b --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_msg_callback.3 @@ -0,0 +1,227 @@ +.\" $NetBSD: SSL_CTX_set_msg_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_msg_callback 3" +.TH SSL_CTX_set_msg_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_msg_callback, +SSL_CTX_set_msg_callback_arg, +SSL_set_msg_callback, +SSL_set_msg_callback_arg, +SSL_trace +\&\- install callback for observing protocol messages +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_msg_callback(SSL_CTX *ctx, +\& void (*cb)(int write_p, int version, +\& int content_type, const void *buf, +\& size_t len, SSL *ssl, void *arg)); +\& void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); +\& +\& void SSL_set_msg_callback(SSL *ssl, +\& void (*cb)(int write_p, int version, +\& int content_type, const void *buf, +\& size_t len, SSL *ssl, void *arg)); +\& void SSL_set_msg_callback_arg(SSL *ssl, void *arg); +\& +\& void SSL_trace(int write_p, int version, int content_type, +\& const void *buf, size_t len, SSL *ssl, void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_msg_callback()\fR or \fBSSL_set_msg_callback()\fR can be used to +define a message callback function \fIcb\fR for observing all SSL/TLS/QUIC +protocol messages (such as handshake messages) that are received or +sent, as well as other events that occur during processing. +\&\fBSSL_CTX_set_msg_callback_arg()\fR and \fBSSL_set_msg_callback_arg()\fR +can be used to set argument \fIarg\fR to the callback function, which is +available for arbitrary application use. +.PP +\&\fBSSL_CTX_set_msg_callback()\fR and \fBSSL_CTX_set_msg_callback_arg()\fR specify +default settings that will be copied to new \fBSSL\fR objects by +\&\fBSSL_new\fR\|(3). \fBSSL_set_msg_callback()\fR and +\&\fBSSL_set_msg_callback_arg()\fR modify the actual settings of an \fBSSL\fR +object. Using a \fBNULL\fR pointer for \fIcb\fR disables the message callback. +.PP +When \fIcb\fR is called by the SSL/TLS/QUIC library the function arguments have the +following meaning: +.IP \fIwrite_p\fR 4 +.IX Item "write_p" +This flag is \fB0\fR when a protocol message has been received and \fB1\fR +when a protocol message has been sent. +.IP \fIversion\fR 4 +.IX Item "version" +The protocol version according to which the protocol message is +interpreted by the library such as \fBTLS1_3_VERSION\fR, \fBTLS1_2_VERSION\fR, +\&\fBOSSL_QUIC1_VERSION\fR etc. For the SSL3_RT_HEADER pseudo +content type (see NOTES below) this value will be the decoded +version/legacy_version field of the record header. +.IP \fIcontent_type\fR 4 +.IX Item "content_type" +This is one of the content type values defined in the protocol specification +(\fBSSL3_RT_CHANGE_CIPHER_SPEC\fR, \fBSSL3_RT_ALERT\fR, \fBSSL3_RT_HANDSHAKE\fR; but never +\&\fBSSL3_RT_APPLICATION_DATA\fR because the callback will only be called for protocol +messages). Alternatively it may be a "pseudo" content type. These pseudo +content types are used to signal some other event in the processing of data (see +NOTES below). +.IP "\fIbuf\fR, \fIlen\fR" 4 +.IX Item "buf, len" +\&\fIbuf\fR points to a buffer containing the protocol message or other data (in the +case of pseudo content types), which consists of \fIlen\fR bytes. The buffer is no +longer valid after the callback function has returned. +.IP \fIssl\fR 4 +.IX Item "ssl" +The \fBSSL\fR object that received or sent the message. +.IP \fIarg\fR 4 +.IX Item "arg" +The user\-defined argument optionally defined by +\&\fBSSL_CTX_set_msg_callback_arg()\fR or \fBSSL_set_msg_callback_arg()\fR. +.PP +The \fBSSL_trace()\fR function can be used as a pre\-written callback in a call to +\&\fBSSL_CTX_set_msg_callback()\fR or \fBSSL_set_msg_callback()\fR. It requires a BIO to be +set as the callback argument via \fBSSL_CTX_set_msg_callback_arg()\fR or +\&\fBSSL_set_msg_callback_arg()\fR. Setting this callback will cause human readable +diagostic tracing information about an SSL/TLS/QUIC connection to be written to +the BIO. +.SH NOTES +.IX Header "NOTES" +Protocol messages are passed to the callback function after decryption +and fragment collection where applicable. (Thus record boundaries are +not visible.) +.PP +If processing a received protocol message results in an error, +the callback function may not be called. For example, the callback +function will never see messages that are considered too large to be +processed. +.PP +Due to automatic protocol version negotiation, \fIversion\fR is not +necessarily the protocol version used by the sender of the message: If +a TLS 1.0 ClientHello message is received by an SSL 3.0\-only server, +\&\fIversion\fR will be \fBSSL3_VERSION\fR. +.PP +Pseudo content type values may be sent at various points during the processing +of data. The following pseudo content types are currently defined: +.IP \fBSSL3_RT_HEADER\fR 4 +.IX Item "SSL3_RT_HEADER" +Used when a TLS record is sent or received. The \fBbuf\fR contains the record header +bytes only. +.IP \fBSSL3_RT_INNER_CONTENT_TYPE\fR 4 +.IX Item "SSL3_RT_INNER_CONTENT_TYPE" +Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3 +records the content type in the record header is always +SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in +an "inner" content type. \fBbuf\fR contains the encoded "inner" content type byte. +.IP \fBSSL3_RT_QUIC_DATAGRAM\fR 4 +.IX Item "SSL3_RT_QUIC_DATAGRAM" +Used when a QUIC datagram is sent or received. +.IP \fBSSL3_RT_QUIC_PACKET\fR 4 +.IX Item "SSL3_RT_QUIC_PACKET" +Used when a QUIC packet is sent or received. +.IP \fBSSL3_RT_QUIC_FRAME_FULL\fR 4 +.IX Item "SSL3_RT_QUIC_FRAME_FULL" +Used when a QUIC frame is sent or received. This is only used for non\-crypto +and stream data related frames. The full QUIC frame data is supplied. +.IP \fBSSL3_RT_QUIC_FRAME_HEADER\fR 4 +.IX Item "SSL3_RT_QUIC_FRAME_HEADER" +Used when a QUIC stream data or crypto frame is sent or received. Only the QUIC +frame header data is supplied. +.IP \fBSSL3_RT_QUIC_FRAME_PADDING\fR 4 +.IX Item "SSL3_RT_QUIC_FRAME_PADDING" +Used when a sequence of one or more QUIC padding frames is sent or received. +A padding frame consists of a single byte and it is common to have multiple +such frames in a sequence. Rather than supplying each frame individually the +callback will supply all the padding frames in one go via this pseudo content +type. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_msg_callback()\fR, \fBSSL_CTX_set_msg_callback_arg()\fR, \fBSSL_set_msg_callback()\fR +and \fBSSL_set_msg_callback_arg()\fR do not return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The pseudo content type \fBSSL3_RT_INNER_CONTENT_TYPE\fR was added in OpenSSL 1.1.1. +.PP +The pseudo content types \fBSSL3_RT_QUIC_DATAGRAM\fR, \fBSSL3_RT_QUIC_PACKET\fR, +\&\fBSSL3_RT_QUIC_FRAME_FULL\fR, \fBSSL3_RT_QUIC_FRAME_HEADER\fR and +\&\fBSSL3_RT_QUIC_FRAME_PADDING\fR were added in OpenSSL 3.2. +.PP +In versions previous to OpenSSL 3.0 \fIcb\fR was called with 0 as \fIversion\fR for +the pseudo content type \fBSSL3_RT_HEADER\fR for TLS records. +.PP +In versions previous to OpenSSL 3.2 \fIcb\fR was called with 0 as \fIversion\fR for +the pseudo content type \fBSSL3_RT_HEADER\fR for DTLS records. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_new_pending_conn_cb.3 b/static/netbsd/man3/SSL_CTX_set_new_pending_conn_cb.3 new file mode 100644 index 00000000..013f1259 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_new_pending_conn_cb.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: SSL_CTX_set_new_pending_conn_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_new_pending_conn_cb 3" +.TH SSL_CTX_set_new_pending_conn_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_new_pending_conn_cb, SSL_set_new_pending_conn_cb_fn \- callback function to report creation of QUIC connection SSL objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 5 +\& typedef int (*SSL_set_new_pending_conn_cb_fn)(SSL_CTX *c, SSL *new_ssl, +\& void *arg); +\& void SSL_CTX_set_new_pending_conn_cb(SSL_CTX *c, +\& SSL_set_new_pending_conn_cb_fn *f, +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_new_pending_conn_cb()\fR sets the new_pending_conn callback function and +associated application data argument \fIarg\fR. When using the QUIC transport, TLS +handshake processing may occur independently from the thread which accepts the +connection that the handshake is establishing. As such, \fBSSL\fR objects +representing the connection may be allocated and initialized prior to a call to +\&\fBSSL_accept_connection()\fR. This registered callback may be used to decorate the +preallocated \fBSSL\fR object or create other associations with its parent +\&\fBSSL\fR prior to a call to \fBSSL_accept_connection()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_new_pending_conn_cb()\fR returns no value. +.PP +\&\fBSSL_set_new_pending_conn_cb_fn()\fR returns an integer value. A return value of +0 indicates that the QUIC stack must discard this newly created \fBSSL\fR object, +implying that the associated new connection will not be available for handling +on a subsequent call to \fBSSL_accept_connection()\fR. A nonzero return +value is treated as success, allowing the new connection to be enqueued to the +accept queue. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_set_ex_data\fR\|(3) +.SH NOTES +.IX Header "NOTES" +Callbacks in QUIC connections have some limitations to them that should be taken +into consideration when writing an application. +.Sp +.RS 4 +QUIC connections may begin processing prior to when an application calls +\&\fBSSL_accept_connection()\fR on them. As such, it may occur that callbacks are +delivered to applications\*(Aq registered TLS callbacks prior to those SSL objects +being returned in \fBSSL_accept_connection()\fR. Applications should expect this +possibility. +.Sp +In particular no references should be held on SSL objects passed to callbacks +for QUIC connections until such time as they are returned through a call to +SSL_accept_connection. +.RE +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_new_pending_conn_cb()\fR was added in OpenSSL 3.5 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_num_tickets.3 b/static/netbsd/man3/SSL_CTX_set_num_tickets.3 new file mode 100644 index 00000000..f78913f7 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_num_tickets.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: SSL_CTX_set_num_tickets.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_num_tickets 3" +.TH SSL_CTX_set_num_tickets 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_num_tickets, +SSL_get_num_tickets, +SSL_CTX_set_num_tickets, +SSL_CTX_get_num_tickets, +SSL_new_session_ticket +\&\- control the number of TLSv1.3 session tickets that are issued +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set_num_tickets(SSL *s, size_t num_tickets); +\& size_t SSL_get_num_tickets(const SSL *s); +\& int SSL_CTX_set_num_tickets(SSL_CTX *ctx, size_t num_tickets); +\& size_t SSL_CTX_get_num_tickets(const SSL_CTX *ctx); +\& int SSL_new_session_ticket(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_num_tickets()\fR and \fBSSL_set_num_tickets()\fR can be called for a server +application and set the number of TLSv1.3 session tickets that will be sent to +the client after a full handshake. Set the desired value (which could be 0) in +the \fBnum_tickets\fR argument. Typically these functions should be called before +the start of the handshake. +.PP +The default number of tickets is 2. Following a resumption the number of tickets +issued will never be more than 1 regardless of the value set via +\&\fBSSL_set_num_tickets()\fR or \fBSSL_CTX_set_num_tickets()\fR. If \fBnum_tickets\fR is set to +0 then no tickets will be issued for either a normal connection or a resumption. +.PP +Tickets are also issued on receipt of a post\-handshake certificate from the +client following a request by the server using +\&\fBSSL_verify_client_post_handshake\fR\|(3). These new tickets will be associated +with the updated client identity (i.e. including their certificate and +verification status). The number of tickets issued will normally be the same as +was used for the initial handshake. If the initial handshake was a full +handshake then \fBSSL_set_num_tickets()\fR can be called again prior to calling +\&\fBSSL_verify_client_post_handshake()\fR to update the number of tickets that will be +sent. +.PP +To issue tickets after other events (such as application\-layer changes), +\&\fBSSL_new_session_ticket()\fR is used by a server application to request that a new +ticket be sent when it is safe to do so. New tickets are only allowed to be +sent in this manner after the initial handshake has completed, and only for +TLS 1.3 connections. By default, the ticket generation and transmission are +delayed until the server is starting a new write operation, so that it is +bundled with other application data being written and properly aligned to a +record boundary. If the connection was at a record boundary when +\&\fBSSL_new_session_ticket()\fR was called, the ticket can be sent immediately +(without waiting for the next application write) by calling +\&\fBSSL_do_handshake()\fR. \fBSSL_new_session_ticket()\fR can be called more than once to +request additional tickets be sent; all such requests are queued and written +together when it is safe to do so and triggered by \fBSSL_write()\fR or +\&\fBSSL_do_handshake()\fR. Note that a successful return from +\&\fBSSL_new_session_ticket()\fR indicates only that the request to send a ticket was +processed, not that the ticket itself was sent. To be notified when the +ticket itself is sent, a new\-session callback can be registered with +\&\fBSSL_CTX_sess_set_new_cb\fR\|(3) that will be invoked as the ticket or tickets +are generated. +.PP +\&\fBSSL_CTX_get_num_tickets()\fR and \fBSSL_get_num_tickets()\fR return the number of +tickets set by a previous call to \fBSSL_CTX_set_num_tickets()\fR or +\&\fBSSL_set_num_tickets()\fR, or 2 if no such call has been made. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_num_tickets()\fR, \fBSSL_set_num_tickets()\fR, and +\&\fBSSL_new_session_ticket()\fR return 1 on success or 0 on failure. +.PP +\&\fBSSL_CTX_get_num_tickets()\fR and \fBSSL_get_num_tickets()\fR return the number of tickets +that have been previously set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_new_session_ticket()\fR was added in OpenSSL 3.0.0. +\&\fBSSL_set_num_tickets()\fR, \fBSSL_get_num_tickets()\fR, \fBSSL_CTX_set_num_tickets()\fR, and +\&\fBSSL_CTX_get_num_tickets()\fR were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_options.3 b/static/netbsd/man3/SSL_CTX_set_options.3 new file mode 100644 index 00000000..af8745fa --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_options.3 @@ -0,0 +1,555 @@ +.\" $NetBSD: SSL_CTX_set_options.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_options 3" +.TH SSL_CTX_set_options 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, +SSL_clear_options, SSL_CTX_get_options, SSL_get_options, +SSL_get_secure_renegotiation_support \- manipulate SSL options +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& uint64_t SSL_CTX_set_options(SSL_CTX *ctx, uint64_t options); +\& uint64_t SSL_set_options(SSL *ssl, uint64_t options); +\& +\& uint64_t SSL_CTX_clear_options(SSL_CTX *ctx, uint64_t options); +\& uint64_t SSL_clear_options(SSL *ssl, uint64_t options); +\& +\& uint64_t SSL_CTX_get_options(const SSL_CTX *ctx); +\& uint64_t SSL_get_options(const SSL *ssl); +\& +\& long SSL_get_secure_renegotiation_support(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_options()\fR adds the options set via bit\-mask in \fBoptions\fR to \fBctx\fR. +\&\fBctx\fR \fBMUST NOT\fR be NULL. +Options already set before are not cleared! +.PP +\&\fBSSL_set_options()\fR adds the options set via bit\-mask in \fBoptions\fR to \fBssl\fR. +Options already set before are not cleared! +.PP +\&\fBSSL_CTX_clear_options()\fR clears the options set via bit\-mask in \fBoptions\fR +to \fBctx\fR. +.PP +\&\fBSSL_clear_options()\fR clears the options set via bit\-mask in \fBoptions\fR to \fBssl\fR. +.PP +\&\fBSSL_CTX_get_options()\fR returns the options set for \fBctx\fR. +.PP +\&\fBSSL_get_options()\fR returns the options set for \fBssl\fR. +.PP +\&\fBSSL_get_secure_renegotiation_support()\fR indicates whether the peer supports +secure renegotiation. +Note, this is implemented via a macro. +.SH NOTES +.IX Header "NOTES" +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bit\-masks and can be combined by a bitwise \fBor\fR +operation (|). +.PP +\&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR affect the (external) +protocol behaviour of the SSL library. The (internal) behaviour of +the API can be changed by using the similar +\&\fBSSL_CTX_set_mode\fR\|(3) and \fBSSL_set_mode()\fR functions. +.PP +During a handshake, the option settings of the SSL object are used. When +a new SSL object is created from a context using \fBSSL_new()\fR, the current +option setting is copied. Changes to \fBctx\fR do not affect already created +SSL objects. \fBSSL_clear()\fR does not affect the settings. +.PP +The following \fBbug workaround\fR options are available: +.IP SSL_OP_CRYPTOPRO_TLSEXT_BUG 4 +.IX Item "SSL_OP_CRYPTOPRO_TLSEXT_BUG" +Add server\-hello extension from the early version of cryptopro draft +when GOST ciphersuite is negotiated. Required for interoperability with CryptoPro +CSP 3.x. +.IP SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 4 +.IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS" +Disables a countermeasure against an SSL 3.0/TLS 1.0 protocol +vulnerability affecting CBC ciphers, which cannot be handled by some +broken SSL implementations. This option has no effect for connections +using other ciphers. +.IP SSL_OP_SAFARI_ECDHE_ECDSA_BUG 4 +.IX Item "SSL_OP_SAFARI_ECDHE_ECDSA_BUG" +Don\*(Aqt prefer ECDHE\-ECDSA ciphers when the client appears to be Safari on OS X. +OS X 10.8..10.8.3 has broken support for ECDHE\-ECDSA ciphers. +.IP SSL_OP_TLSEXT_PADDING 4 +.IX Item "SSL_OP_TLSEXT_PADDING" +Adds a padding extension to ensure the ClientHello size is never between +256 and 511 bytes in length. This is needed as a workaround for some +implementations. +.IP SSL_OP_ALL 4 +.IX Item "SSL_OP_ALL" +All of the above bug workarounds. +.PP +It is usually safe to use \fBSSL_OP_ALL\fR to enable the bug workaround +options if compatibility with somewhat broken implementations is +desired. +.PP +The following \fBmodifying\fR options are available: +.IP SSL_OP_ALLOW_CLIENT_RENEGOTIATION 4 +.IX Item "SSL_OP_ALLOW_CLIENT_RENEGOTIATION" +Client\-initiated renegotiation is disabled by default. Use +this option to enable it. +.IP SSL_OP_ALLOW_NO_DHE_KEX 4 +.IX Item "SSL_OP_ALLOW_NO_DHE_KEX" +In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means +that there will be no forward secrecy for the resumed session. +.IP SSL_OP_PREFER_NO_DHE_KEX 4 +.IX Item "SSL_OP_PREFER_NO_DHE_KEX" +In TLSv1.3, on resumption let the server prefer a non\-(ec)dhe based key +exchange mode over an (ec)dhe based one. Ignored without \fBSSL_OP_ALLOW_NO_DHE_KEX\fR +being set as well. Always ignored on the client. +.IP SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 4 +.IX Item "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION" +Allow legacy insecure renegotiation between OpenSSL and unpatched clients or +servers. See the \fBSECURE RENEGOTIATION\fR section for more details. +.IP SSL_OP_CIPHER_SERVER_PREFERENCE 4 +.IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE" +When choosing a cipher, use the server\*(Aqs preferences instead of the client +preferences. When not set, the SSL server will always follow the clients +preferences. When set, the SSL/TLS server will choose following its +own preferences. +.IP SSL_OP_CISCO_ANYCONNECT 4 +.IX Item "SSL_OP_CISCO_ANYCONNECT" +Use Cisco\*(Aqs version identifier of DTLS_BAD_VER when establishing a DTLSv1 +connection. Only available when using the deprecated \fBDTLSv1_client_method()\fR API. +.IP SSL_OP_CLEANSE_PLAINTEXT 4 +.IX Item "SSL_OP_CLEANSE_PLAINTEXT" +By default TLS and QUIC SSL objects keep a copy of received plaintext +application data in a static buffer until it is overwritten by the +next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT +deciphered application data is cleansed by calling \fBOPENSSL_cleanse\fR\|(3) +after passing data to the application. Data is also cleansed when +releasing the connection (e.g. \fBSSL_free\fR\|(3)). +.Sp +Since OpenSSL only cleanses internal buffers, the application is still +responsible for cleansing all other buffers. Most notably, this +applies to buffers passed to functions like \fBSSL_read\fR\|(3), +\&\fBSSL_peek\fR\|(3) but also like \fBSSL_write\fR\|(3). +.Sp +TLS connections do not buffer data to be sent in plaintext. QUIC stream +objects do buffer plaintext data to be sent and this option will also cause +that data to be cleansed when it is discarded. +.Sp +This option can be set differently on individual QUIC stream objects and +has no effect on QUIC connection objects (except where a default stream is +being used). +.IP SSL_OP_COOKIE_EXCHANGE 4 +.IX Item "SSL_OP_COOKIE_EXCHANGE" +Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects +DTLS connections. +.IP SSL_OP_DISABLE_TLSEXT_CA_NAMES 4 +.IX Item "SSL_OP_DISABLE_TLSEXT_CA_NAMES" +Disable TLS Extension CA Names. You may want to disable it for security reasons +or for compatibility with some Windows TLS implementations crashing when this +extension is larger than 1024 bytes. +.IP SSL_OP_ENABLE_KTLS 4 +.IX Item "SSL_OP_ENABLE_KTLS" +Enable the use of kernel TLS. In order to benefit from kernel TLS OpenSSL must +have been compiled with support for it, and it must be supported by the +negotiated ciphersuites and extensions. The specific ciphersuites and extensions +that are supported may vary by platform and kernel version. +.Sp +The kernel TLS data\-path implements the record layer, and the encryption +algorithm. The kernel will utilize the best hardware +available for encryption. Using the kernel data\-path should reduce the memory +footprint of OpenSSL because no buffering is required. Also, the throughput +should improve because data copy is avoided when user data is encrypted into +kernel memory instead of the usual encrypt then copy to kernel. +.Sp +Kernel TLS might not support all the features of OpenSSL. For instance, +renegotiation, and setting the maximum fragment size is not possible as of +Linux 4.20. +.Sp +Note that with kernel TLS enabled some cryptographic operations are performed +by the kernel directly and not via any available OpenSSL Providers. This might +be undesirable if, for example, the application requires all cryptographic +operations to be performed by the FIPS provider. +.IP SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE 4 +.IX Item "SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE" +With this option, \fBsendfile()\fR will use the zerocopy mode, which gives a +performance boost when used with KTLS hardware offload. Note that invalid TLS +records might be transmitted if the file is changed while being sent. This +option has no effect if \fBSSL_OP_ENABLE_KTLS\fR is not enabled. +.Sp +This option only applies to Linux. KTLS sendfile on FreeBSD doesn\*(Aqt offer an +option to disable zerocopy and always runs in this mode. +.IP SSL_OP_ENABLE_MIDDLEBOX_COMPAT 4 +.IX Item "SSL_OP_ENABLE_MIDDLEBOX_COMPAT" +If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This +has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that +do not understand TLSv1.3 will not drop the connection. Regardless of whether +this option is set or not CCS messages received from the peer will always be +ignored in TLSv1.3. This option is set by default. To switch it off use +\&\fBSSL_clear_options()\fR. A future version of OpenSSL may not set this by default. +.IP SSL_OP_IGNORE_UNEXPECTED_EOF 4 +.IX Item "SSL_OP_IGNORE_UNEXPECTED_EOF" +Some TLS implementations do not send the mandatory close_notify alert on +shutdown. If the application tries to wait for the close_notify alert but the +peer closes the connection without sending it, an error is generated. When this +option is enabled the peer does not need to send the close_notify alert and a +closed connection will be treated as if the close_notify alert was received. +.Sp +You should only enable this option if the protocol running over TLS +can detect a truncation attack itself, and that the application is checking for +that truncation attack. +.Sp +For more information on shutting down a connection, see \fBSSL_shutdown\fR\|(3). +.IP SSL_OP_LEGACY_SERVER_CONNECT 4 +.IX Item "SSL_OP_LEGACY_SERVER_CONNECT" +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +\&\fBonly\fR. See the \fBSECURE RENEGOTIATION\fR section for more details. +.IP SSL_OP_NO_ANTI_REPLAY 4 +.IX Item "SSL_OP_NO_ANTI_REPLAY" +By default, when a server is configured for early data (i.e., max_early_data > 0), +OpenSSL will switch on replay protection. See \fBSSL_read_early_data\fR\|(3) for a +description of the replay protection feature. Anti\-replay measures are required +to comply with the TLSv1.3 specification. Some applications may be able to +mitigate the replay risks in other ways and in such cases the built in OpenSSL +functionality is not required. Those applications can turn this feature off by +setting this option. This is a server\-side option only. It is ignored by +clients. +.IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4 +.IX Item "SSL_OP_NO_TX_CERTIFICATE_COMPRESSION" +Normally clients and servers will transparently attempt to negotiate the +RFC8879 certificate compression option on TLSv1.3 connections. +.Sp +If this option is set, the certificate compression extension is ignored +upon receipt and compressed certificates will not be sent to the peer. +.IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4 +.IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION" +Normally clients and servers will transparently attempt to negotiate the +RFC8879 certificate compression option on TLSv1.3 connections. +.Sp +If this option is set, the certificate compression extension will not be sent +and compressed certificates will not be accepted from the peer. +.IP SSL_OP_NO_COMPRESSION 4 +.IX Item "SSL_OP_NO_COMPRESSION" +Do not use TLS record compression even if it is supported. This option is set by +default. To switch it off use \fBSSL_clear_options()\fR. Note that TLS record +compression is not recommended and is not available at security level 2 or +above. From OpenSSL 3.2 the default security level is 2, so clearing this option +will have no effect without also changing the default security level. See +\&\fBSSL_CTX_set_security_level\fR\|(3). +.IP SSL_OP_NO_ENCRYPT_THEN_MAC 4 +.IX Item "SSL_OP_NO_ENCRYPT_THEN_MAC" +Normally clients and servers will transparently attempt to negotiate the +RFC7366 Encrypt\-then\-MAC option on TLS and DTLS connection. +.Sp +If this option is set, Encrypt\-then\-MAC is disabled. Clients will not +propose, and servers will not accept the extension. +.IP SSL_OP_NO_EXTENDED_MASTER_SECRET 4 +.IX Item "SSL_OP_NO_EXTENDED_MASTER_SECRET" +Normally clients and servers will transparently attempt to negotiate the +RFC7627 Extended Master Secret option on TLS and DTLS connection. +.Sp +If this option is set, Extended Master Secret is disabled. Clients will +not propose, and servers will not accept the extension. +.IP SSL_OP_NO_QUERY_MTU 4 +.IX Item "SSL_OP_NO_QUERY_MTU" +Do not query the MTU. Only affects DTLS connections. +.IP SSL_OP_NO_RENEGOTIATION 4 +.IX Item "SSL_OP_NO_RENEGOTIATION" +Disable all renegotiation in (D)TLSv1.2 and earlier. Do not send HelloRequest +messages, and ignore renegotiation requests via ClientHello. +.IP SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 4 +.IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION" +When performing renegotiation as a server, always start a new session +(i.e., session resumption requests are only accepted in the initial +handshake). This option is not needed for clients. +.IP "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2" 4 +.IX Item "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2" +These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol +versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS, +respectively. +As of OpenSSL 1.1.0, these options are deprecated, use +\&\fBSSL_CTX_set_min_proto_version\fR\|(3) and +\&\fBSSL_CTX_set_max_proto_version\fR\|(3) instead. +.IP SSL_OP_NO_TICKET 4 +.IX Item "SSL_OP_NO_TICKET" +SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless +session tickets. +.Sp +When using session ids a copy of the session information is +cached on the server and a unique id is sent to the client. When the client +wishes to resume it provides the unique id so that the server can retrieve the +session information from its cache. +.Sp +When using stateless session tickets the server uses a session ticket encryption +key to encrypt the session information. This encrypted data is sent to the +client as a "ticket". When the client wishes to resume it sends the encrypted +data back to the server. The server uses its key to decrypt the data and resume +the session. In this way the server can operate statelessly \- no session +information needs to be cached locally. +.Sp +The TLSv1.3 protocol only supports tickets and does not directly support session +ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful +and stateless. Stateless tickets work the same way as in TLSv1.2 and below. +Stateful tickets mimic the session id behaviour available in TLSv1.2 and below. +The session information is cached on the server and the session id is wrapped up +in a ticket and sent back to the client. When the client wishes to resume, it +presents a ticket in the same way as for stateless tickets. The server can then +extract the session id from the ticket and retrieve the session information from +its cache. +.Sp +By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will +cause stateless tickets to not be issued. In TLSv1.2 and below this means no +ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be +sent. This is a server\-side option only. +.Sp +In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from +being sent by calling \fBSSL_CTX_set_num_tickets\fR\|(3) or +\&\fBSSL_set_num_tickets\fR\|(3). +.IP SSL_OP_PRIORITIZE_CHACHA 4 +.IX Item "SSL_OP_PRIORITIZE_CHACHA" +When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize +ChaCha20\-Poly1305 ciphers to the top of the server cipher list if a +ChaCha20\-Poly1305 cipher is at the top of the client cipher list. This helps +those clients (e.g. mobile) use ChaCha20\-Poly1305 if that cipher is anywhere +in the server cipher list; but still allows other clients to use AES and other +ciphers. Requires \fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR. +.IP SSL_OP_TLS_ROLLBACK_BUG 4 +.IX Item "SSL_OP_TLS_ROLLBACK_BUG" +Disable version rollback attack detection. +.Sp +During the client key exchange, the client must send the same information +about acceptable SSL/TLS protocol levels as during the first hello. Some +clients violate this rule by adapting to the server\*(Aqs answer. (Example: +the client sends an SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server +only understands up to SSLv3. In this case the client must still use the +same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect +to the server\*(Aqs answer and violate the version rollback protection.) +.PP +The following options no longer have any effect but their identifiers are +retained for compatibility purposes: +.IP SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 4 +.IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG" +.PD 0 +.IP SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 4 +.IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER" +.IP SSL_OP_SSLEAY_080_CLIENT_DH_BUG 4 +.IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG" +.IP SSL_OP_TLS_D5_BUG 4 +.IX Item "SSL_OP_TLS_D5_BUG" +.IP SSL_OP_TLS_BLOCK_PADDING_BUG 4 +.IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG" +.IP SSL_OP_MSIE_SSLV2_RSA_PADDING 4 +.IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING" +.IP SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 4 +.IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG" +.IP SSL_OP_MICROSOFT_SESS_ID_BUG 4 +.IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG" +.IP SSL_OP_NETSCAPE_CHALLENGE_BUG 4 +.IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG" +.IP SSL_OP_PKCS1_CHECK_1 4 +.IX Item "SSL_OP_PKCS1_CHECK_1" +.IP SSL_OP_PKCS1_CHECK_2 4 +.IX Item "SSL_OP_PKCS1_CHECK_2" +.IP SSL_OP_SINGLE_DH_USE 4 +.IX Item "SSL_OP_SINGLE_DH_USE" +.IP SSL_OP_SINGLE_ECDH_USE 4 +.IX Item "SSL_OP_SINGLE_ECDH_USE" +.IP SSL_OP_EPHEMERAL_RSA 4 +.IX Item "SSL_OP_EPHEMERAL_RSA" +.IP SSL_OP_NETSCAPE_CA_DN_BUG 4 +.IX Item "SSL_OP_NETSCAPE_CA_DN_BUG" +.IP SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 4 +.IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG" +.PD +.SH "SECURE RENEGOTIATION" +.IX Header "SECURE RENEGOTIATION" +OpenSSL always attempts to use secure renegotiation as +described in RFC5746. This counters the prefix attack described in +CVE\-2009\-3555 and elsewhere. +.PP +This attack has far reaching consequences which application writers should be +aware of. In the description below an implementation supporting secure +renegotiation is referred to as \fIpatched\fR. A server not supporting secure +renegotiation is referred to as \fIunpatched\fR. +.PP +The following sections describe the operations permitted by OpenSSL\*(Aqs secure +renegotiation implementation. +.SS "Patched client and server" +.IX Subsection "Patched client and server" +Connections and renegotiation are always permitted by OpenSSL implementations. +.SS "Unpatched client and patched OpenSSL server" +.IX Subsection "Unpatched client and patched OpenSSL server" +The initial connection succeeds but client renegotiation is denied by the +server with a \fBno_renegotiation\fR warning alert if TLS v1.0 is used or a fatal +\&\fBhandshake_failure\fR alert in SSL v3.0. +.PP +If the patched OpenSSL server attempts to renegotiate a fatal +\&\fBhandshake_failure\fR alert is sent. This is because the server code may be +unaware of the unpatched nature of the client. +.PP +If the option \fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then +renegotiation \fBalways\fR succeeds. +.SS "Patched OpenSSL client and unpatched server" +.IX Subsection "Patched OpenSSL client and unpatched server" +If the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR or +\&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then initial connections +and renegotiation between patched OpenSSL clients and unpatched servers +succeeds. If neither option is set then initial connections to unpatched +servers will fail. +.PP +Setting the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR has security implications; +clients that are willing to connect to servers that do not implement +RFC 5746 secure renegotiation are subject to attacks such as +CVE\-2009\-3555. +.PP +OpenSSL client applications wishing to ensure they can connect to unpatched +servers should always \fBset\fR \fBSSL_OP_LEGACY_SERVER_CONNECT\fR +.PP +OpenSSL client applications that want to ensure they can \fBnot\fR connect to +unpatched servers (and thus avoid any security issues) should always \fBclear\fR +\&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR using \fBSSL_CTX_clear_options()\fR or +\&\fBSSL_clear_options()\fR. +.PP +The difference between the \fBSSL_OP_LEGACY_SERVER_CONNECT\fR and +\&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR options is that +\&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR enables initial connections and secure +renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while +\&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR allows initial connections +and renegotiation between OpenSSL and unpatched clients or servers. +.SS "Applicability of options to QUIC connections and streams" +.IX Subsection "Applicability of options to QUIC connections and streams" +These options apply to SSL objects referencing a QUIC connection: +.IP SSL_OP_ALLOW_NO_DHE_KEX 4 +.IX Item "SSL_OP_ALLOW_NO_DHE_KEX" +.PD 0 +.IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4 +.IX Item "SSL_OP_NO_TX_CERTIFICATE_COMPRESSION" +.IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4 +.IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION" +.IP SSL_OP_NO_TICKET 4 +.IX Item "SSL_OP_NO_TICKET" +.IP SSL_OP_PRIORITIZE_CHACHA 4 +.IX Item "SSL_OP_PRIORITIZE_CHACHA" +.PD +.PP +These options apply to SSL objects referencing a QUIC stream: +.IP SSL_OP_CLEANSE_PLAINTEXT 4 +.IX Item "SSL_OP_CLEANSE_PLAINTEXT" +.PP +Options on QUIC connections are initialized from the options set on SSL_CTX +before a QUIC connection SSL object is created. Options on QUIC streams are +initialised from the options configured on the QUIC connection SSL object +they are created from. +.PP +Setting options which relate to QUIC streams on a QUIC connection SSL object has +no direct effect on the QUIC connection SSL object itself, but will change the +options set on the default stream (if there is one) and will also determine the +default options set on any future streams which are created. +.PP +Other options not mentioned above do not have an effect and will be ignored. +.PP +Options which relate to QUIC streams may also be set directly on QUIC stream SSL +objects. Setting connection\-related options on such an object has no effect. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR return the new options bit\-mask +after adding \fBoptions\fR. +.PP +\&\fBSSL_CTX_clear_options()\fR and \fBSSL_clear_options()\fR return the new options bit\-mask +after clearing \fBoptions\fR. +.PP +\&\fBSSL_CTX_get_options()\fR and \fBSSL_get_options()\fR return the current bit\-mask. +.PP +\&\fBSSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports +secure renegotiation and 0 if it does not. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3), \fBSSL_shutdown\fR\|(3) +\&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3), +\&\fBSSL_CTX_set_min_proto_version\fR\|(3), +\&\fBopenssl\-dhparam\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The attempt to always try to use secure renegotiation was added in +OpenSSL 0.9.8m. +.PP +The \fBSSL_OP_PRIORITIZE_CHACHA\fR and \fBSSL_OP_NO_RENEGOTIATION\fR options +were added in OpenSSL 1.1.1. +.PP +The \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR and \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR +options were added in OpenSSL 3.0. +.PP +The \fBSSL_OP_\fR constants and the corresponding parameter and return values +of the affected functions were changed to \f(CW\*(C`uint64_t\*(C'\fR type in OpenSSL 3.0. +For that reason it is no longer possible use the \fBSSL_OP_\fR macro values +in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. However it is still possible to test +whether these macros are defined or not. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_psk_client_callback.3 b/static/netbsd/man3/SSL_CTX_set_psk_client_callback.3 new file mode 100644 index 00000000..f7a97a77 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_psk_client_callback.3 @@ -0,0 +1,236 @@ +.\" $NetBSD: SSL_CTX_set_psk_client_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_psk_client_callback 3" +.TH SSL_CTX_set_psk_client_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_psk_client_cb_func, +SSL_psk_use_session_cb_func, +SSL_CTX_set_psk_client_callback, +SSL_set_psk_client_callback, +SSL_CTX_set_psk_use_session_callback, +SSL_set_psk_use_session_callback +\&\- set PSK client callback +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md, +\& const unsigned char **id, +\& size_t *idlen, +\& SSL_SESSION **sess); +\& +\& +\& void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx, +\& SSL_psk_use_session_cb_func cb); +\& void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb); +\& +\& +\& typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl, +\& const char *hint, +\& char *identity, +\& unsigned int max_identity_len, +\& unsigned char *psk, +\& unsigned int max_psk_len); +\& +\& void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb); +\& void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A client application wishing to use TLSv1.3 PSKs should use either +\&\fBSSL_CTX_set_psk_use_session_callback()\fR or \fBSSL_set_psk_use_session_callback()\fR as +appropriate. These functions cannot be used for TLSv1.2 and below PSKs. +.PP +The callback function is given a pointer to the SSL connection in \fBssl\fR. +.PP +The first time the callback is called for a connection the \fBmd\fR parameter is +NULL. In some circumstances the callback will be called a second time. In that +case the server will have specified a ciphersuite to use already and the PSK +must be compatible with the digest for that ciphersuite. The digest will be +given in \fBmd\fR. The PSK returned by the callback is allowed to be different +between the first and second time it is called. +.PP +On successful completion the callback must store a pointer to an identifier for +the PSK in \fB*id\fR. The identifier length in bytes should be stored in \fB*idlen\fR. +The memory pointed to by \fB*id\fR remains owned by the application and should +be freed by it as required at any point after the handshake is complete. +.PP +Additionally the callback should store a pointer to an SSL_SESSION object in +\&\fB*sess\fR. This is used as the basis for the PSK, and should, at a minimum, have +the following fields set: +.IP "The master key" 4 +.IX Item "The master key" +This can be set via a call to \fBSSL_SESSION_set1_master_key\fR\|(3). +.IP "A ciphersuite" 4 +.IX Item "A ciphersuite" +Only the handshake digest associated with the ciphersuite is relevant for the +PSK (the server may go on to negotiate any ciphersuite which is compatible with +the digest). The application can use any TLSv1.3 ciphersuite. If \fBmd\fR is +not NULL the handshake digest for the ciphersuite should be the same. +The ciphersuite can be set via a call to <\fBSSL_SESSION_set_cipher\fR\|(3)>. The +handshake digest of an SSL_CIPHER object can be checked using +<\fBSSL_CIPHER_get_handshake_digest\fR\|(3)>. +.IP "The protocol version" 4 +.IX Item "The protocol version" +This can be set via a call to \fBSSL_SESSION_set_protocol_version\fR\|(3) and should +be TLS1_3_VERSION. +.PP +Additionally the maximum early data value should be set via a call to +\&\fBSSL_SESSION_set_max_early_data\fR\|(3) if the PSK will be used for sending early +data. +.PP +Alternatively an SSL_SESSION created from a previous non\-PSK handshake may also +be used as the basis for a PSK. +.PP +Ownership of the SSL_SESSION object is passed to the OpenSSL library and so it +should not be freed by the application. +.PP +Note that as described above, the callback may be called a second time during a +handshake. Since ownership of the SSL_SESSION is transferred to OpenSSL on each +call, if the callback wishes to return the same SSL_SESSION pointer on a +subsequent invocation, it must first call \fBSSL_SESSION_up_ref\fR\|(3) to increment +the reference count. Failure to do so will result in a use\-after\-free error. +Alternatively, the callback may return a different SSL_SESSION object on each +call (e.g., by calling \fBSSL_SESSION_dup\fR\|(3)). +.PP +It is also possible for the callback to succeed but not supply a PSK. In this +case no PSK will be sent to the server but the handshake will continue. To do +this the callback should return successfully and ensure that \fB*sess\fR is +NULL. The contents of \fB*id\fR and \fB*idlen\fR will be ignored. +.PP +A client application wishing to use PSK ciphersuites for TLSv1.2 and below must +provide a different callback function. This function will be called when the +client is sending the ClientKeyExchange message to the server. +.PP +The purpose of the callback function is to select the PSK identity and +the pre\-shared key to use during the connection setup phase. +.PP +The callback is set using functions \fBSSL_CTX_set_psk_client_callback()\fR +or \fBSSL_set_psk_client_callback()\fR. The callback function is given the +connection in parameter \fBssl\fR, a \fBNUL\fR\-terminated PSK identity hint +sent by the server in parameter \fBhint\fR, a buffer \fBidentity\fR of +length \fBmax_identity_len\fR bytes (including the \fBNUL\fR\-terminator) where the +resulting \fBNUL\fR\-terminated identity is to be stored, and a buffer \fBpsk\fR +of length \fBmax_psk_len\fR bytes where the resulting pre\-shared key is to +be stored. +.PP +The callback for use in TLSv1.2 will also work in TLSv1.3 although it is +recommended to use \fBSSL_CTX_set_psk_use_session_callback()\fR +or \fBSSL_set_psk_use_session_callback()\fR for this purpose instead. If TLSv1.3 has +been negotiated then OpenSSL will first check to see if a callback has been set +via \fBSSL_CTX_set_psk_use_session_callback()\fR or \fBSSL_set_psk_use_session_callback()\fR +and it will use that in preference. If no such callback is present then it will +check to see if a callback has been set via \fBSSL_CTX_set_psk_client_callback()\fR or +\&\fBSSL_set_psk_client_callback()\fR and use that. In this case the \fBhint\fR value will +always be NULL and the handshake digest will default to SHA\-256 for any returned +PSK. TLSv1.3 early data exchanges are possible in PSK connections only with the +\&\fBSSL_psk_use_session_cb_func\fR callback, and are not possible with the +\&\fBSSL_psk_client_cb_func\fR callback. +.SH NOTES +.IX Header "NOTES" +Note that parameter \fBhint\fR given to the callback may be \fBNULL\fR. +.PP +A connection established via a TLSv1.3 PSK will appear as if session resumption +has occurred so that \fBSSL_session_reused\fR\|(3) will return true. +.PP +There are no known security issues with sharing the same PSK between TLSv1.2 (or +below) and TLSv1.3. However, the RFC has this note of caution: +.PP +"While there is no known way in which the same PSK might produce related output +in both versions, only limited analysis has been done. Implementations can +ensure safety from cross\-protocol related output by not reusing PSKs between +TLS 1.3 and TLS 1.2." +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Return values from the \fBSSL_psk_client_cb_func\fR callback are interpreted as +follows: +.PP +On success (callback found a PSK identity and a pre\-shared key to use) +the length (> 0) of \fBpsk\fR in bytes is returned. +.PP +Otherwise or on errors the callback should return 0. In this case +the connection setup fails. +.PP +The SSL_psk_use_session_cb_func callback should return 1 on success or 0 on +failure. In the event of failure the connection setup fails. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_psk_find_session_callback\fR\|(3), +\&\fBSSL_set_psk_find_session_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_psk_use_session_callback()\fR and \fBSSL_set_psk_use_session_callback()\fR +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_quiet_shutdown.3 b/static/netbsd/man3/SSL_CTX_set_quiet_shutdown.3 new file mode 100644 index 00000000..2f08f08b --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_quiet_shutdown.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: SSL_CTX_set_quiet_shutdown.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_quiet_shutdown 3" +.TH SSL_CTX_set_quiet_shutdown 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, +SSL_get_quiet_shutdown \- manipulate shutdown behaviour +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); +\& int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); +\& +\& void SSL_set_quiet_shutdown(SSL *ssl, int mode); +\& int SSL_get_quiet_shutdown(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_quiet_shutdown()\fR sets the "quiet shutdown" flag for \fBctx\fR to be +\&\fBmode\fR. SSL objects created from \fBctx\fR inherit the \fBmode\fR valid at the time +\&\fBSSL_new\fR\|(3) is called. \fBmode\fR may be 0 or 1. +.PP +\&\fBSSL_CTX_get_quiet_shutdown()\fR returns the "quiet shutdown" setting of \fBctx\fR. +.PP +\&\fBSSL_set_quiet_shutdown()\fR sets the "quiet shutdown" flag for \fBssl\fR to be +\&\fBmode\fR. The setting stays valid until \fBssl\fR is removed with +\&\fBSSL_free\fR\|(3) or \fBSSL_set_quiet_shutdown()\fR is called again. +It is not changed when \fBSSL_clear\fR\|(3) is called. +\&\fBmode\fR may be 0 or 1. +.PP +\&\fBSSL_get_quiet_shutdown()\fR returns the "quiet shutdown" setting of \fBssl\fR. +.PP +These functions are not supported for QUIC SSL objects. \fBSSL_set_quiet_shutdown()\fR +has no effect if called on a QUIC SSL object. +.SH NOTES +.IX Header "NOTES" +Normally when an SSL connection is finished, the parties must send out +close_notify alert messages using \fBSSL_shutdown\fR\|(3) +for a clean shutdown. +.PP +When setting the "quiet shutdown" flag to 1, \fBSSL_shutdown\fR\|(3) +will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. +(\fBSSL_shutdown\fR\|(3) then behaves like +\&\fBSSL_set_shutdown\fR\|(3) called with +SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.) +The session is thus considered to be shutdown, but no close_notify alert +is sent to the peer. This behaviour violates the TLS standard. +.PP +The default is normal shutdown behaviour as described by the TLS standard. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_quiet_shutdown()\fR and \fBSSL_set_quiet_shutdown()\fR do not return +diagnostic information. +.PP +\&\fBSSL_CTX_get_quiet_shutdown()\fR and \fBSSL_get_quiet_shutdown()\fR return the current +setting. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_shutdown\fR\|(3), +\&\fBSSL_set_shutdown\fR\|(3), \fBSSL_new\fR\|(3), +\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_read_ahead.3 b/static/netbsd/man3/SSL_CTX_set_read_ahead.3 new file mode 100644 index 00000000..d7c17723 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_read_ahead.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: SSL_CTX_set_read_ahead.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_read_ahead 3" +.TH SSL_CTX_set_read_ahead 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead, +SSL_set_read_ahead, SSL_get_read_ahead, +SSL_CTX_get_default_read_ahead +\&\- manage whether to read as many input bytes as possible +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_set_read_ahead(SSL *s, int yes); +\& int SSL_get_read_ahead(const SSL *s); +\& +\& SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); +\& long SSL_CTX_get_read_ahead(SSL_CTX *ctx); +\& long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_read_ahead()\fR and \fBSSL_set_read_ahead()\fR set whether we should read as +many input bytes as possible (for nonblocking reads) or not. For example if +\&\fBx\fR bytes are currently required by OpenSSL, but \fBy\fR bytes are available from +the underlying BIO (where \fBy\fR > \fBx\fR), then OpenSSL will read all \fBy\fR bytes +into its buffer (providing that the buffer is large enough) if reading ahead is +on, or \fBx\fR bytes otherwise. +Setting the parameter \fByes\fR to 0 turns reading ahead is off, other values turn +it on. +\&\fBSSL_CTX_set_default_read_ahead()\fR is identical to \fBSSL_CTX_set_read_ahead()\fR. +.PP +\&\fBSSL_CTX_get_read_ahead()\fR and \fBSSL_get_read_ahead()\fR indicate whether reading +ahead has been set or not. +\&\fBSSL_CTX_get_default_read_ahead()\fR is identical to \fBSSL_CTX_get_read_ahead()\fR. +.PP +These functions cannot be used with QUIC SSL objects. \fBSSL_set_read_ahead()\fR +has no effect if called on a QUIC SSL object. +.SH NOTES +.IX Header "NOTES" +These functions have no impact when used with DTLS. The return values for +\&\fBSSL_CTX_get_read_head()\fR and \fBSSL_get_read_ahead()\fR are undefined for DTLS. Setting +\&\fBread_ahead\fR can impact the behaviour of the \fBSSL_pending()\fR function +(see \fBSSL_pending\fR\|(3)). +.PP +Since \fBSSL_read()\fR can return \fBSSL_ERROR_WANT_READ\fR for non\-application data +records, and \fBSSL_has_pending()\fR can\*(Aqt tell the difference between processed and +unprocessed data, it\*(Aqs recommended that if read ahead is turned on that +\&\fBSSL_MODE_AUTO_RETRY\fR is not turned off using \fBSSL_CTX_clear_mode()\fR. +That will prevent getting \fBSSL_ERROR_WANT_READ\fR when there is still a complete +record available that hasn\*(Aqt been processed. +.PP +If the application wants to continue to use the underlying transport (e.g. TCP +connection) after the SSL connection is finished using \fBSSL_shutdown()\fR reading +ahead should be turned off. +Otherwise the SSL structure might read data that it shouldn\*(Aqt. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_read_ahead()\fR and \fBSSL_CTX_get_read_ahead()\fR return 0 if reading ahead is off, +and non zero otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_pending\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_record_padding_callback.3 b/static/netbsd/man3/SSL_CTX_set_record_padding_callback.3 new file mode 100644 index 00000000..a7748a5c --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_record_padding_callback.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: SSL_CTX_set_record_padding_callback.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_record_padding_callback 3" +.TH SSL_CTX_set_record_padding_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_record_padding_callback, +SSL_set_record_padding_callback, +SSL_CTX_set_record_padding_callback_arg, +SSL_set_record_padding_callback_arg, +SSL_CTX_get_record_padding_callback_arg, +SSL_get_record_padding_callback_arg, +SSL_CTX_set_block_padding, +SSL_CTX_set_block_padding_ex, +SSL_set_block_padding, +SSL_set_block_padding_ex \- install callback to specify TLS 1.3 record padding +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg)); +\& int SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg)); +\& +\& void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg); +\& void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx); +\& +\& void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg); +\& void *SSL_get_record_padding_callback_arg(const SSL *ssl); +\& +\& int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size); +\& int SSL_set_block_padding(SSL *ssl, size_t block_size); +\& int SSL_CTX_set_block_padding_ex(SSL_CTX *ctx, size_t app_block_size, size_t hs_block_size); +\& int SSL_set_block_padding_ex(SSL *ssl, size_t app_block_size, size_t hs_block_size); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_record_padding_callback()\fR or \fBSSL_set_record_padding_callback()\fR +can be used to assign a callback function \fIcb\fR to specify the padding +for TLS 1.3 records. The value set in \fBctx\fR is copied to a new SSL by \fBSSL_new()\fR. +Kernel TLS is not possible if the record padding callback is set, and the callback +function cannot be set if Kernel TLS is already configured for the current SSL object. +.PP +\&\fBSSL_CTX_set_record_padding_callback_arg()\fR and \fBSSL_set_record_padding_callback_arg()\fR +assign a value \fBarg\fR that is passed to the callback when it is invoked. The value +set in \fBctx\fR is copied to a new SSL by \fBSSL_new()\fR. +.PP +\&\fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR +retrieve the \fBarg\fR value that is passed to the callback. +.PP +\&\fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR pads the record to a multiple +of the \fBblock_size\fR. A \fBblock_size\fR of 0 or 1 disables block padding. The limit of +\&\fBblock_size\fR is SSL3_RT_MAX_PLAIN_LENGTH. +.PP +\&\fBSSL_CTX_set_block_padding_ex()\fR and \fBSSL_set_block_padding_ex()\fR do similarly but +allow the caller to separately specify the padding block size to be applied to +handshake and application data messages. +.PP +The callback is invoked for every record before encryption. +The \fBtype\fR parameter is the TLS record type that is being processed; may be +one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT. +The \fBlen\fR parameter is the current plaintext length of the record before encryption. +The \fBarg\fR parameter is the value set via \fBSSL_CTX_set_record_padding_callback_arg()\fR +or \fBSSL_set_record_padding_callback_arg()\fR. +.PP +These functions cannot be used with QUIC SSL objects. +\&\fBSSL_set_record_padding_callback()\fR and \fBSSL_set_block_padding()\fR fail if called on +a QUIC SSL object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR +functions return the \fBarg\fR value assigned in the corresponding set functions. +.PP +The \fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR functions return 1 on success +or 0 if \fBblock_size\fR is too large. +.PP +The \fBcb\fR returns the number of padding bytes to add to the record. A return of 0 +indicates no padding will be added. A return value that causes the record to +exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the +maximum record size. +.PP +The \fBSSL_CTX_get_record_padding_callback_arg()\fR function returns 1 on success or 0 if +the callback function is not set because Kernel TLS is configured for the SSL object. +.SH NOTES +.IX Header "NOTES" +The default behavior is to add no padding to the record. +.PP +A user\-supplied padding callback function will override the behavior set by +\&\fBSSL_set_block_padding()\fR or \fBSSL_CTX_set_block_padding()\fR. Setting the user\-supplied +callback to NULL will restore the configured block padding behavior. +.PP +These functions only apply to TLS 1.3 records being written. +.PP +Padding bytes are not added in constant\-time. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1. +.PP +The return type of \fBSSL_CTX_set_record_padding_callback()\fR function was +changed to int in OpenSSL 3.0. +.PP +The functions \fBSSL_set_block_padding_ex()\fR and \fBSSL_CTX_set_block_padding_ex()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_security_level.3 b/static/netbsd/man3/SSL_CTX_set_security_level.3 new file mode 100644 index 00000000..17744a59 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_security_level.3 @@ -0,0 +1,234 @@ +.\" $NetBSD: SSL_CTX_set_security_level.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_security_level 3" +.TH SSL_CTX_set_security_level 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data \- SSL/TLS security framework +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); +\& void SSL_set_security_level(SSL *s, int level); +\& +\& int SSL_CTX_get_security_level(const SSL_CTX *ctx); +\& int SSL_get_security_level(const SSL *s); +\& +\& void SSL_CTX_set_security_callback(SSL_CTX *ctx, +\& int (*cb)(SSL *s, SSL_CTX *ctx, int op, +\& int bits, int nid, +\& void *other, void *ex)); +\& +\& void SSL_set_security_callback(SSL *s, int (*cb)(SSL *s, SSL_CTX *ctx, int op, +\& int bits, int nid, +\& void *other, void *ex)); +\& +\& int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, +\& int bits, int nid, void *other, +\& void *ex); +\& int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, +\& int bits, int nid, void *other, +\& void *ex); +\& +\& void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); +\& void SSL_set0_security_ex_data(SSL *s, void *ex); +\& +\& void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); +\& void *SSL_get0_security_ex_data(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions \fBSSL_CTX_set_security_level()\fR and \fBSSL_set_security_level()\fR set +the security level to \fBlevel\fR. If not set the library default security level +is used. +.PP +The functions \fBSSL_CTX_get_security_level()\fR and \fBSSL_get_security_level()\fR +retrieve the current security level. +.PP +\&\fBSSL_CTX_set_security_callback()\fR, \fBSSL_set_security_callback()\fR, +\&\fBSSL_CTX_get_security_callback()\fR and \fBSSL_get_security_callback()\fR get or set +the security callback associated with \fBctx\fR or \fBs\fR. If not set a default +security callback is used. The meaning of the parameters and the behaviour +of the default callbacks is described below. +.PP +\&\fBSSL_CTX_set0_security_ex_data()\fR, \fBSSL_set0_security_ex_data()\fR, +\&\fBSSL_CTX_get0_security_ex_data()\fR and \fBSSL_get0_security_ex_data()\fR set the +extra data pointer passed to the \fBex\fR parameter of the callback. This +value is passed to the callback verbatim and can be set to any convenient +application specific value. +.SH "DEFAULT CALLBACK BEHAVIOUR" +.IX Header "DEFAULT CALLBACK BEHAVIOUR" +If an application doesn\*(Aqt set its own security callback the default +callback is used. It is intended to provide sane defaults. The meaning +of each level is described below. +.IP "\fBLevel 0\fR" 4 +.IX Item "Level 0" +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. +.IP "\fBLevel 1\fR" 4 +.IX Item "Level 1" +The security level corresponds to a minimum of 80 bits of security. Any +parameters offering below 80 bits of security are excluded. As a result RSA, +DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits +are prohibited. Any cipher suite using MD5 for the MAC is also prohibited. Any +cipher suites using CCM with a 64 bit authentication tag are prohibited. Note +that signatures using SHA1 and MD5 are also forbidden at this level as they +have less than 80 security bits. Additionally, SSLv3, TLS 1.0, TLS 1.1 and +DTLS 1.0 are all disabled at this level. +.IP "\fBLevel 2\fR" 4 +.IX Item "Level 2" +Security level set to 112 bits of security. As a result RSA, DSA and DH keys +shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +In addition to the level 1 exclusions any cipher suite using RC4 is also +prohibited. Compression is disabled. +.IP "\fBLevel 3\fR" 4 +.IX Item "Level 3" +Security level set to 128 bits of security. As a result RSA, DSA and DH keys +shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. +In addition to the level 2 exclusions cipher suites not offering forward +secrecy are prohibited. Session tickets are disabled. +.IP "\fBLevel 4\fR" 4 +.IX Item "Level 4" +Security level set to 192 bits of security. As a result RSA, DSA and +DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are +prohibited. Cipher suites using SHA1 for the MAC are prohibited. +.IP "\fBLevel 5\fR" 4 +.IX Item "Level 5" +Security level set to 256 bits of security. As a result RSA, DSA and DH keys +shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. +.SH "APPLICATION DEFINED SECURITY CALLBACKS" +.IX Header "APPLICATION DEFINED SECURITY CALLBACKS" +\&\fIDocumentation to be provided.\fR +.SH NOTES +.IX Header "NOTES" +The default security level can be configured when OpenSSL is compiled by +setting \fB\-DOPENSSL_TLS_SECURITY_LEVEL=level\fR. If not set then 2 is used. +.PP +The security framework disables or reject parameters inconsistent with the +set security level. In the past this was difficult as applications had to set +a number of distinct parameters (supported ciphers, supported curves supported +signature algorithms) to achieve this end and some cases (DH parameter size +for example) could not be checked at all. +.PP +By setting an appropriate security level much of this complexity can be +avoided. +.PP +The bits of security limits affect all relevant parameters including +cipher suite encryption algorithms, supported ECC curves, supported +signature algorithms, DH parameter sizes, certificate key sizes and +signature algorithms. This limit applies no matter what other custom +settings an application has set: so if the cipher suite is set to \fBALL\fR +then only cipher suites consistent with the security level are permissible. +.PP +See SP800\-57 for how the security limits are related to individual +algorithms. +.PP +Some security levels require large key sizes for non\-ECC public key +algorithms which can severely degrade performance. For example 256 bits +of security requires the use of RSA keys of at least 15360 bits in size. +.PP +Some restrictions can be gracefully handled: for example cipher suites +offering insufficient security are not sent by the client and will not +be selected by the server. Other restrictions such as the peer certificate +key size or the DH parameter size will abort the handshake with a fatal +alert. +.PP +Attempts to set certificates or parameters with insufficient security are +also blocked. For example trying to set a certificate using a 512 bit RSA key +or a certificate with a signature with SHA1 digest at level 1 using +\&\fBSSL_CTX_use_certificate()\fR. Applications which do not check the return values +for errors will misbehave: for example it might appear that a certificate is +not set at all because it had been rejected. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_security_level()\fR and \fBSSL_set_security_level()\fR do not return values. +.PP +\&\fBSSL_CTX_get_security_level()\fR and \fBSSL_get_security_level()\fR return a integer that +represents the security level with \fBSSL_CTX\fR or \fBSSL\fR, respectively. +.PP +\&\fBSSL_CTX_set_security_callback()\fR and \fBSSL_set_security_callback()\fR do not return +values. +.PP +\&\fBSSL_CTX_get_security_callback()\fR and \fBSSL_get_security_callback()\fR return the pointer +to the security callback or NULL if the callback is not set. +.PP +\&\fBSSL_CTX_get0_security_ex_data()\fR and \fBSSL_get0_security_ex_data()\fR return the extra +data pointer or NULL if the ex data is not set. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_session_cache_mode.3 b/static/netbsd/man3/SSL_CTX_set_session_cache_mode.3 new file mode 100644 index 00000000..46d08a18 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_session_cache_mode.3 @@ -0,0 +1,190 @@ +.\" $NetBSD: SSL_CTX_set_session_cache_mode.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_session_cache_mode 3" +.TH SSL_CTX_set_session_cache_mode 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode \- enable/disable session caching +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); +\& long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_session_cache_mode()\fR enables/disables session caching +by setting the operational mode for \fBctx\fR to . +.PP +\&\fBSSL_CTX_get_session_cache_mode()\fR returns the currently used cache mode. +.SH NOTES +.IX Header "NOTES" +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each \fBctx\fR, if more than one +SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX +object. +.PP +In order to reuse a session, a client must send the session\*(Aqs id to the +server. It can only send exactly one id. The server then either +agrees to reuse the session or it starts a full handshake (to create a new +session). +.PP +A server will look up the session in its internal session storage. If the +session is not found in internal storage or lookups for the internal storage +have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try +the external storage if available. +.PP +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +\&\fBSSL_CTX_set_session_id_context\fR\|(3)). +.PP +The following session cache modes and modifiers are available: +.IP SSL_SESS_CACHE_OFF 4 +.IX Item "SSL_SESS_CACHE_OFF" +No session caching for client or server takes place. +.IP SSL_SESS_CACHE_CLIENT 4 +.IX Item "SSL_SESS_CACHE_CLIENT" +Client sessions are added to the session cache. As there is no reliable way +for the OpenSSL library to know whether a session should be reused or which +session to choose (due to the abstract BIO layer the SSL engine does not +have details about the connection), the application must select the session +to be reused by using the \fBSSL_set_session\fR\|(3) +function. This option is not activated by default. +.IP SSL_SESS_CACHE_SERVER 4 +.IX Item "SSL_SESS_CACHE_SERVER" +Server sessions are added to the session cache. When a client proposes a +session to be reused, the server looks for the corresponding session in (first) +the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), +then (second) in the external cache if available. If the session is found, the +server will try to reuse the session. This is the default. +.IP SSL_SESS_CACHE_BOTH 4 +.IX Item "SSL_SESS_CACHE_BOTH" +Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. +.IP SSL_SESS_CACHE_NO_AUTO_CLEAR 4 +.IX Item "SSL_SESS_CACHE_NO_AUTO_CLEAR" +Normally the session cache is checked for expired sessions every +255 connections using the +\&\fBSSL_CTX_flush_sessions\fR\|(3) function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and +\&\fBSSL_CTX_flush_sessions\fR\|(3) can be called +explicitly by the application. +.IP SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 4 +.IX Item "SSL_SESS_CACHE_NO_INTERNAL_LOOKUP" +By setting this flag, session\-resume operations in an SSL/TLS server will not +automatically look up sessions in the internal cache, even if sessions are +automatically stored there. If external session caching callbacks are in use, +this flag guarantees that all lookups are directed to the external cache. +As automatic lookup only applies for SSL/TLS servers, the flag has no effect on +clients. +.IP SSL_SESS_CACHE_NO_INTERNAL_STORE 4 +.IX Item "SSL_SESS_CACHE_NO_INTERNAL_STORE" +Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER, +sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. +Normally a new session is added to the internal cache as well as any external +session caching (callback) that is configured for the SSL_CTX. This flag will +prevent sessions being stored in the internal cache (though the application can +add them manually using \fBSSL_CTX_add_session\fR\|(3)). Note: +in any SSL/TLS servers where external caching is configured, any successful +session lookups in the external cache (i.e. for session\-resume requests) would +normally be copied into the local cache before processing continues \- this flag +prevents these additions to the internal cache as well. +.IP SSL_SESS_CACHE_NO_INTERNAL 4 +.IX Item "SSL_SESS_CACHE_NO_INTERNAL" +Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and +SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. +.IP SSL_SESS_CACHE_UPDATE_TIME 4 +.IX Item "SSL_SESS_CACHE_UPDATE_TIME" +Updates the timestamp of the session when it is used, increasing the lifespan +of the session. The session timeout applies to last use, rather then creation +time. +.PP +The default mode is SSL_SESS_CACHE_SERVER. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_session_cache_mode()\fR returns the previously set cache mode. +.PP +\&\fBSSL_CTX_get_session_cache_mode()\fR returns the currently set cache mode. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3), +\&\fBSSL_session_reused\fR\|(3), +\&\fBSSL_CTX_add_session\fR\|(3), +\&\fBSSL_CTX_sess_number\fR\|(3), +\&\fBSSL_CTX_sess_set_cache_size\fR\|(3), +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3), +\&\fBSSL_CTX_set_session_id_context\fR\|(3), +\&\fBSSL_CTX_set_timeout\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_session_id_context.3 b/static/netbsd/man3/SSL_CTX_set_session_id_context.3 new file mode 100644 index 00000000..136f0211 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_session_id_context.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: SSL_CTX_set_session_id_context.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_session_id_context 3" +.TH SSL_CTX_set_session_id_context 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_session_id_context, SSL_set_session_id_context \- set context within which session can be reused (server side only) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, +\& unsigned int sid_ctx_len); +\& int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, +\& unsigned int sid_ctx_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length +\&\fBsid_ctx_len\fR within which a session can be reused for the \fBctx\fR object. +.PP +\&\fBSSL_set_session_id_context()\fR sets the context \fBsid_ctx\fR of length +\&\fBsid_ctx_len\fR within which a session can be reused for the \fBssl\fR object. +.SH NOTES +.IX Header "NOTES" +Sessions are generated within a certain context. When exporting/importing +sessions with \fBi2d_SSL_SESSION\fR/\fBd2i_SSL_SESSION\fR it would be possible, +to re\-import a session generated from another context (e.g. another +application), which might lead to malfunctions. Therefore, each application +must set its own session id context \fBsid_ctx\fR which is used to distinguish +the contexts and is stored in exported sessions. The \fBsid_ctx\fR can be +any kind of binary data with a given length, it is therefore possible +to use e.g. the name of the application and/or the hostname and/or service +name ... +.PP +The session id context becomes part of the session. The session id context +is set by the SSL/TLS server. The \fBSSL_CTX_set_session_id_context()\fR and +\&\fBSSL_set_session_id_context()\fR functions are therefore only useful on the +server side. +.PP +OpenSSL clients will check the session id context returned by the server +when reusing a session. +.PP +The maximum length of the \fBsid_ctx\fR is limited to +\&\fBSSL_MAX_SID_CTX_LENGTH\fR. +.SH WARNINGS +.IX Header "WARNINGS" +If the session id context is not set on an SSL/TLS server and client +certificates are used, stored sessions +will not be reused but a fatal error will be flagged and the handshake +will fail. +.PP +If a server returns a different session id context to an OpenSSL client +when reusing a session, an error will be flagged and the handshake will +fail. OpenSSL servers will always return the correct session id context, +as an OpenSSL server checks the session id context itself before reusing +a session as described above. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_session_id_context()\fR and \fBSSL_set_session_id_context()\fR +return the following values: +.IP 0 4 +The length \fBsid_ctx_len\fR of the session id context \fBsid_ctx\fR exceeded +the maximum allowed length of \fBSSL_MAX_SID_CTX_LENGTH\fR. The error +is logged to the error stack. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_session_ticket_cb.3 b/static/netbsd/man3/SSL_CTX_set_session_ticket_cb.3 new file mode 100644 index 00000000..5606d440 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_session_ticket_cb.3 @@ -0,0 +1,232 @@ +.\" $NetBSD: SSL_CTX_set_session_ticket_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_session_ticket_cb 3" +.TH SSL_CTX_set_session_ticket_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_session_ticket_cb, +SSL_SESSION_get0_ticket_appdata, +SSL_SESSION_set1_ticket_appdata, +SSL_CTX_generate_session_ticket_fn, +SSL_CTX_decrypt_session_ticket_fn \- manage session ticket application data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg); +\& typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss, +\& const unsigned char *keyname, +\& size_t keyname_len, +\& SSL_TICKET_STATUS status, +\& void *arg); +\& int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx, +\& SSL_CTX_generate_session_ticket_fn gen_cb, +\& SSL_CTX_decrypt_session_ticket_fn dec_cb, +\& void *arg); +\& int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len); +\& int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_set_session_ticket_cb()\fR sets the application callbacks \fBgen_cb\fR +and \fBdec_cb\fR that are used by a server to set and get application data stored +with a session, and placed into a session ticket. Either callback function may +be set to NULL. The value of \fBarg\fR is passed to the callbacks. +.PP +\&\fBgen_cb\fR is the application defined callback invoked when a session ticket is +about to be created. The application can call \fBSSL_SESSION_set1_ticket_appdata()\fR +at this time to add application data to the session ticket. The value of \fBarg\fR +is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The \fBgen_cb\fR +callback is defined as type \fBSSL_CTX_generate_session_ticket_fn\fR. +.PP +\&\fBdec_cb\fR is the application defined callback invoked after session ticket +decryption has been attempted and any session ticket application data is +available. If ticket decryption was successful then the \fBss\fR argument contains +the session data. The \fBkeyname\fR and \fBkeyname_len\fR arguments identify the key +used to decrypt the session ticket. The \fBstatus\fR argument is the result of the +ticket decryption. See the "NOTES" section below for further details. The value +of \fBarg\fR is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The +\&\fBdec_cb\fR callback is defined as type \fBSSL_CTX_decrypt_session_ticket_fn\fR. +.PP +\&\fBSSL_SESSION_set1_ticket_appdata()\fR sets the application data specified by +\&\fBdata\fR and \fBlen\fR into \fBss\fR which is then placed into any generated session +tickets. It can be called at any time before a session ticket is created to +update the data placed into the session ticket. However, given that sessions +and tickets are created by the handshake, the \fBgen_cb\fR is provided to notify +the application that a session ticket is about to be generated. +.PP +\&\fBSSL_SESSION_get0_ticket_appdata()\fR assigns \fBdata\fR to the session ticket +application data and assigns \fBlen\fR to the length of the session ticket +application data from \fBss\fR. The application data can be set via +\&\fBSSL_SESSION_set1_ticket_appdata()\fR or by a session ticket. NULL will be assigned +to \fBdata\fR and 0 will be assigned to \fBlen\fR if there is no session ticket +application data. \fBSSL_SESSION_get0_ticket_appdata()\fR can be called any time +after a session has been created. The \fBdec_cb\fR is provided to notify the +application that a session ticket has just been decrypted. +.SH NOTES +.IX Header "NOTES" +When the \fBdec_cb\fR callback is invoked, the SSL_SESSION \fBss\fR has not yet been +assigned to the SSL \fBs\fR. The \fBstatus\fR indicates the result of the ticket +decryption. The callback must check the \fBstatus\fR value before performing any +action, as it is called even if ticket decryption fails. +.PP +The \fBkeyname\fR and \fBkeyname_len\fR arguments to \fBdec_cb\fR may be used to identify +the key that was used to encrypt the session ticket. +.PP +The \fBstatus\fR argument can be any of these values: +.IP SSL_TICKET_EMPTY 4 +.IX Item "SSL_TICKET_EMPTY" +Empty ticket present. No ticket data will be used and a new ticket should be +sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not +valid for a client to send an empty ticket. +.IP SSL_TICKET_NO_DECRYPT 4 +.IX Item "SSL_TICKET_NO_DECRYPT" +The ticket couldn\*(Aqt be decrypted. No ticket data will be used and a new ticket +should be sent to the client. +.IP SSL_TICKET_SUCCESS 4 +.IX Item "SSL_TICKET_SUCCESS" +A ticket was successfully decrypted, any session ticket application data should +be available. A new ticket should not be sent to the client. +.IP SSL_TICKET_SUCCESS_RENEW 4 +.IX Item "SSL_TICKET_SUCCESS_RENEW" +Same as \fBSSL_TICKET_SUCCESS\fR, but a new ticket should be sent to the client. +.PP +The return value can be any of these values: +.IP SSL_TICKET_RETURN_ABORT 4 +.IX Item "SSL_TICKET_RETURN_ABORT" +The handshake should be aborted, either because of an error or because of some +policy. Note that in TLSv1.3 a client may send more than one ticket in a single +handshake. Therefore, just because one ticket is unacceptable it does not mean +that all of them are. For this reason this option should be used with caution. +.IP SSL_TICKET_RETURN_IGNORE 4 +.IX Item "SSL_TICKET_RETURN_IGNORE" +Do not use a ticket (if one was available). Do not send a renewed ticket to the +client. +.IP SSL_TICKET_RETURN_IGNORE_RENEW 4 +.IX Item "SSL_TICKET_RETURN_IGNORE_RENEW" +Do not use a ticket (if one was available). Send a renewed ticket to the client. +.Sp +If the callback does not wish to change the default ticket behaviour then it +should return this value if \fBstatus\fR is \fBSSL_TICKET_EMPTY\fR or +\&\fBSSL_TICKET_NO_DECRYPT\fR. +.IP SSL_TICKET_RETURN_USE 4 +.IX Item "SSL_TICKET_RETURN_USE" +Use the ticket. Do not send a renewed ticket to the client. It is an error for +the callback to return this value if \fBstatus\fR has a value other than +\&\fBSSL_TICKET_SUCCESS\fR or \fBSSL_TICKET_SUCCESS_RENEW\fR. +.Sp +If the callback does not wish to change the default ticket behaviour then it +should return this value if \fBstatus\fR is \fBSSL_TICKET_SUCCESS\fR. +.IP SSL_TICKET_RETURN_USE_RENEW 4 +.IX Item "SSL_TICKET_RETURN_USE_RENEW" +Use the ticket. Send a renewed ticket to the client. It is an error for the +callback to return this value if \fBstatus\fR has a value other than +\&\fBSSL_TICKET_SUCCESS\fR or \fBSSL_TICKET_SUCCESS_RENEW\fR. +.Sp +If the callback does not wish to change the default ticket behaviour then it +should return this value if \fBstatus\fR is \fBSSL_TICKET_SUCCESS_RENEW\fR. +.PP +If \fBstatus\fR has the value \fBSSL_TICKET_EMPTY\fR or \fBSSL_TICKET_NO_DECRYPT\fR then +no session data will be available and the callback must not use the \fBss\fR +argument. If \fBstatus\fR has the value \fBSSL_TICKET_SUCCESS\fR or +\&\fBSSL_TICKET_SUCCESS_RENEW\fR then the application can call +\&\fBSSL_SESSION_get0_ticket_appdata()\fR using the session provided in the \fBss\fR +argument to retrieve the application data. +.PP +When the \fBgen_cb\fR callback is invoked, the \fBSSL_get_session()\fR function can be +used to retrieve the SSL_SESSION for \fBSSL_SESSION_set1_ticket_appdata()\fR. +.PP +By default, in TLSv1.2 and below, a new session ticket is not issued on a +successful resumption and therefore \fBgen_cb\fR will not be called. In TLSv1.3 the +default behaviour is to always issue a new ticket on resumption. In both cases +this behaviour can be changed if a ticket key callback is in use (see +\&\fBSSL_CTX_set_tlsext_ticket_key_cb\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR and +\&\fBSSL_SESSION_get0_ticket_appdata()\fR functions return 1 on success and 0 on +failure. +.PP +The \fBgen_cb\fR callback must return 1 to continue the connection. A return of 0 +will terminate the connection with an INTERNAL_ERROR alert. +.PP +The \fBdec_cb\fR callback must return a value as described in "NOTES" above. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_get_session\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR +and \fBSSL_SESSION_get_ticket_appdata()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_split_send_fragment.3 b/static/netbsd/man3/SSL_CTX_set_split_send_fragment.3 new file mode 100644 index 00000000..a7a52c6e --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_split_send_fragment.3 @@ -0,0 +1,245 @@ +.\" $NetBSD: SSL_CTX_set_split_send_fragment.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_split_send_fragment 3" +.TH SSL_CTX_set_split_send_fragment 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment, +SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment, +SSL_CTX_set_max_pipelines, SSL_set_max_pipelines, +SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len, +SSL_CTX_set_tlsext_max_fragment_length, +SSL_set_tlsext_max_fragment_length, +SSL_SESSION_get_max_fragment_length \- Control fragment size settings and pipelining operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); +\& long SSL_set_max_send_fragment(SSL *ssl, long m); +\& +\& long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); +\& long SSL_set_max_pipelines(SSL_CTX *ssl, long m); +\& +\& long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); +\& long SSL_set_split_send_fragment(SSL *ssl, long m); +\& +\& void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); +\& void SSL_set_default_read_buffer_len(SSL *s, size_t len); +\& +\& int SSL_CTX_set_tlsext_max_fragment_length(SSL_CTX *ctx, uint8_t mode); +\& int SSL_set_tlsext_max_fragment_length(SSL *ssl, uint8_t mode); +\& uint8_t SSL_SESSION_get_max_fragment_length(const SSL_SESSION *session); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Some engines are able to process multiple simultaneous crypto operations. This +capability could be utilised to parallelise the processing of a single +connection. For example a single write can be split into multiple records and +each one encrypted independently and in parallel. Note: this will only work in +TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This +capability is known as "pipelining" within OpenSSL. +.PP +In order to benefit from the pipelining capability. You need to have an engine +that provides ciphers that support this. The OpenSSL "dasync" engine provides +AES128\-SHA based ciphers that have this capability. However, these are for +development and test purposes only. +.PP +\&\fBSSL_CTX_set_max_send_fragment()\fR and \fBSSL_set_max_send_fragment()\fR set the +\&\fBmax_send_fragment\fR parameter for SSL_CTX and SSL objects respectively. This +value restricts the amount of plaintext bytes that will be sent in any one +SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These +functions will only accept a value in the range 512 \- SSL3_RT_MAX_PLAIN_LENGTH. +.PP +\&\fBSSL_CTX_set_max_pipelines()\fR and \fBSSL_set_max_pipelines()\fR set the maximum number +of pipelines that will be used at any one time. This value applies to both +"read" pipelining and "write" pipelining. By default only one pipeline will be +used (i.e. normal non\-parallel operation). The number of pipelines set must be +in the range 1 \- SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also +automatically turn on "read_ahead" (see \fBSSL_CTX_set_read_ahead\fR\|(3)). This is +explained further below. OpenSSL will only ever use more than one pipeline if +a cipher suite is negotiated that uses a pipeline capable cipher provided by an +engine. +.PP +Pipelining operates slightly differently for reading encrypted data compared to +writing encrypted data. \fBSSL_CTX_set_split_send_fragment()\fR and +\&\fBSSL_set_split_send_fragment()\fR define how data is split up into pipelines when +writing encrypted data. The number of pipelines used will be determined by the +amount of data provided to the \fBSSL_write_ex()\fR or \fBSSL_write()\fR call divided by +\&\fBsplit_send_fragment\fR. +.PP +For example if \fBsplit_send_fragment\fR is set to 2000 and \fBmax_pipelines\fR is 4 +then: +.PP +SSL_write/SSL_write_ex called with 0\-2000 bytes == 1 pipeline used +.PP +SSL_write/SSL_write_ex called with 2001\-4000 bytes == 2 pipelines used +.PP +SSL_write/SSL_write_ex called with 4001\-6000 bytes == 3 pipelines used +.PP +SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used +.PP +\&\fBsplit_send_fragment\fR must always be less than or equal to +\&\fBmax_send_fragment\fR. By default it is set to be equal to \fBmax_send_fragment\fR. +This will mean that the same number of records will always be created as would +have been created in the non\-parallel case, although the data will be +apportioned differently. In the parallel case data will be spread equally +between the pipelines. +.PP +Read pipelining is controlled in a slightly different way than with write +pipelining. While reading we are constrained by the number of records that the +peer (and the network) can provide to us in one go. The more records we can get +in one go the more opportunity we have to parallelise the processing. As noted +above when setting \fBmax_pipelines\fR to a value greater than one, \fBread_ahead\fR +is automatically set. The \fBread_ahead\fR parameter causes OpenSSL to attempt to +read as much data into the read buffer as the network can provide and will fit +into the buffer. Without this set data is read into the read buffer one record +at a time. The more data that can be read, the more opportunity there is for +parallelising the processing at the cost of increased memory overhead per +connection. Setting \fBread_ahead\fR can impact the behaviour of the \fBSSL_pending()\fR +function (see \fBSSL_pending\fR\|(3)). In addition the default size of the internal +read buffer is multiplied by the number of pipelines available to ensure that we +can read multiple records in one go. This can therefore have a significant +impact on memory usage. +.PP +The \fBSSL_CTX_set_default_read_buffer_len()\fR and \fBSSL_set_default_read_buffer_len()\fR +functions control the size of the read buffer that will be used. The \fBlen\fR +parameter sets the size of the buffer. The value will only be used if it is +greater than the default that would have been used anyway. The normal default +value depends on a number of factors but it will be at least +SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. +.PP +\&\fBSSL_CTX_set_tlsext_max_fragment_length()\fR sets the default maximum fragment +length negotiation mode via value \fBmode\fR to \fBctx\fR. +This setting affects only SSL instances created after this function is called. +It affects the client\-side as only its side may initiate this extension use. +.PP +\&\fBSSL_set_tlsext_max_fragment_length()\fR sets the maximum fragment length +negotiation mode via value \fBmode\fR to \fBssl\fR. +This setting will be used during a handshake when extensions are exchanged +between client and server. +So it only affects SSL sessions created after this function is called. +It affects the client\-side as only its side may initiate this extension use. +.PP +\&\fBSSL_SESSION_get_max_fragment_length()\fR gets the maximum fragment length +negotiated in \fBsession\fR. +.PP +These functions cannot be used with QUIC SSL objects. +\&\fBSSL_set_max_send_fragment()\fR, \fBSSL_set_max_pipelines()\fR, +\&\fBSSL_set_split_send_fragment()\fR, \fBSSL_set_default_read_buffer_len()\fR and +\&\fBSSL_set_tlsext_max_fragment_length()\fR fail if called on a QUIC SSL object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All non\-void functions return 1 on success and 0 on failure. +.SH NOTES +.IX Header "NOTES" +The Maximum Fragment Length extension support is optional on the server side. +If the server does not support this extension then +\&\fBSSL_SESSION_get_max_fragment_length()\fR will return: +TLSEXT_max_fragment_length_DISABLED. +.PP +The following modes are available: +.IP TLSEXT_max_fragment_length_DISABLED 4 +.IX Item "TLSEXT_max_fragment_length_DISABLED" +Disables Maximum Fragment Length Negotiation (default). +.IP TLSEXT_max_fragment_length_512 4 +.IX Item "TLSEXT_max_fragment_length_512" +Sets Maximum Fragment Length to 512 bytes. +.IP TLSEXT_max_fragment_length_1024 4 +.IX Item "TLSEXT_max_fragment_length_1024" +Sets Maximum Fragment Length to 1024. +.IP TLSEXT_max_fragment_length_2048 4 +.IX Item "TLSEXT_max_fragment_length_2048" +Sets Maximum Fragment Length to 2048. +.IP TLSEXT_max_fragment_length_4096 4 +.IX Item "TLSEXT_max_fragment_length_4096" +Sets Maximum Fragment Length to 4096. +.PP +With the exception of \fBSSL_CTX_set_default_read_buffer_len()\fR +\&\fBSSL_set_default_read_buffer_len()\fR, \fBSSL_CTX_set_tlsext_max_fragment_length()\fR, +\&\fBSSL_set_tlsext_max_fragment_length()\fR and \fBSSL_SESSION_get_max_fragment_length()\fR +all these functions are implemented using macros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_read_ahead\fR\|(3), \fBSSL_pending\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CTX_set_max_pipelines()\fR, \fBSSL_set_max_pipelines()\fR, +\&\fBSSL_CTX_set_split_send_fragment()\fR, \fBSSL_set_split_send_fragment()\fR, +\&\fBSSL_CTX_set_default_read_buffer_len()\fR and \fBSSL_set_default_read_buffer_len()\fR +functions were added in OpenSSL 1.1.0. +.PP +The \fBSSL_CTX_set_tlsext_max_fragment_length()\fR, \fBSSL_set_tlsext_max_fragment_length()\fR +and \fBSSL_SESSION_get_max_fragment_length()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_srp_password.3 b/static/netbsd/man3/SSL_CTX_set_srp_password.3 new file mode 100644 index 00000000..0304f711 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_srp_password.3 @@ -0,0 +1,287 @@ +.\" $NetBSD: SSL_CTX_set_srp_password.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_srp_password 3" +.TH SSL_CTX_set_srp_password 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_srp_username, +SSL_CTX_set_srp_password, +SSL_CTX_set_srp_strength, +SSL_CTX_set_srp_cb_arg, +SSL_CTX_set_srp_username_callback, +SSL_CTX_set_srp_client_pwd_callback, +SSL_CTX_set_srp_verify_param_callback, +SSL_set_srp_server_param, +SSL_set_srp_server_param_pw, +SSL_get_srp_g, +SSL_get_srp_N, +SSL_get_srp_username, +SSL_get_srp_userinfo +\&\- SRP control operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& int SSL_CTX_set_srp_username(SSL_CTX *ctx, char *name); +\& int SSL_CTX_set_srp_password(SSL_CTX *ctx, char *password); +\& int SSL_CTX_set_srp_strength(SSL_CTX *ctx, int strength); +\& int SSL_CTX_set_srp_cb_arg(SSL_CTX *ctx, void *arg); +\& int SSL_CTX_set_srp_username_callback(SSL_CTX *ctx, +\& int (*cb) (SSL *s, int *ad, void *arg)); +\& int SSL_CTX_set_srp_client_pwd_callback(SSL_CTX *ctx, +\& char *(*cb) (SSL *s, void *arg)); +\& int SSL_CTX_set_srp_verify_param_callback(SSL_CTX *ctx, +\& int (*cb) (SSL *s, void *arg)); +\& +\& int SSL_set_srp_server_param(SSL *s, const BIGNUM *N, const BIGNUM *g, +\& BIGNUM *sa, BIGNUM *v, char *info); +\& int SSL_set_srp_server_param_pw(SSL *s, const char *user, const char *pass, +\& const char *grp); +\& +\& BIGNUM *SSL_get_srp_g(SSL *s); +\& BIGNUM *SSL_get_srp_N(SSL *s); +\& +\& char *SSL_get_srp_username(SSL *s); +\& char *SSL_get_srp_userinfo(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. There are no +available replacement functions at this time. +.PP +These functions provide access to SRP (Secure Remote Password) parameters, +an alternate authentication mechanism for TLS. SRP allows the use of usernames +and passwords over unencrypted channels without revealing the password to an +eavesdropper. SRP also supplies a shared secret at the end of the authentication +sequence that can be used to generate encryption keys. +.PP +The SRP protocol, version 3 is specified in RFC 2945. SRP version 6 is described +in RFC 5054 with applications to TLS authentication. +.PP +The \fBSSL_CTX_set_srp_username()\fR function sets the SRP username for \fBctx\fR. This +should be called on the client prior to creating a connection to the server. +The length of \fBname\fR must be shorter or equal to 255 characters. +.PP +The \fBSSL_CTX_set_srp_password()\fR function sets the SRP password for \fBctx\fR. This +may be called on the client prior to creating a connection to the server. +This overrides the effect of \fBSSL_CTX_set_srp_client_pwd_callback()\fR. +.PP +The \fBSSL_CTX_set_srp_strength()\fR function sets the SRP strength for \fBctx\fR. This +is the minimal length of the SRP prime in bits. If not specified 1024 is used. +If not satisfied by the server key exchange the connection will be rejected. +.PP +The \fBSSL_CTX_set_srp_cb_arg()\fR function sets an extra parameter that will +be passed to all following callbacks as \fBarg\fR. +.PP +The \fBSSL_CTX_set_srp_username_callback()\fR function sets the server side callback +that is invoked when an SRP username is found in a ClientHello. +The callback parameters are the SSL connection \fBs\fR, a writable error flag \fBad\fR +and the extra argument \fBarg\fR set by \fBSSL_CTX_set_srp_cb_arg()\fR. +This callback should setup the server for the key exchange by calling +\&\fBSSL_set_srp_server_param()\fR with the appropriate parameters for the received +username. The username can be obtained by calling \fBSSL_get_srp_username()\fR. +See \fBSRP_VBASE_init\fR\|(3) to parse the verifier file created by \fBopenssl\-srp\fR\|(1) or +\&\fBSRP_create_verifier\fR\|(3) to generate it. +The callback should return \fBSSL_ERROR_NONE\fR to proceed with the server key exchange, +\&\fBSSL3_AL_FATAL\fR for a fatal error or any value < 0 for a retryable error. +In the event of a \fBSSL3_AL_FATAL\fR the alert flag given by \fB*al\fR will be sent +back. By default this will be \fBSSL_AD_UNKNOWN_PSK_IDENTITY\fR. +.PP +The \fBSSL_CTX_set_srp_client_pwd_callback()\fR function sets the client password +callback on the client. +The callback parameters are the SSL connection \fBs\fR and the extra argument \fBarg\fR +set by \fBSSL_CTX_set_srp_cb_arg()\fR. +The callback will be called as part of the generation of the client secrets. +It should return the client password in text form or NULL to abort the connection. +The resulting memory will be freed by the library as part of the callback resolution. +This overrides the effect of \fBSSL_CTX_set_srp_password()\fR. +.PP +The \fBSSL_CTX_set_srp_verify_param_callback()\fR sets the SRP gN parameter verification +callback on the client. This allows the client to perform custom verification when +receiving the server SRP proposed parameters. +The callback parameters are the SSL connection \fBs\fR and the extra argument \fBarg\fR +set by \fBSSL_CTX_set_srp_cb_arg()\fR. +The callback should return a positive value to accept the server parameters. +Returning 0 or a negative value will abort the connection. The server parameters +can be obtained by calling \fBSSL_get_srp_N()\fR and \fBSSL_get_srp_g()\fR. +Sanity checks are already performed by the library after the handshake +(B % N non zero, check against the strength parameter) and are not necessary. +If no callback is set the g and N parameters will be checked against +known RFC 5054 values. +.PP +The \fBSSL_set_srp_server_param()\fR function sets all SRP parameters for +the connection \fBs\fR. \fBN\fR and \fBg\fR are the SRP group parameters, \fBsa\fR is the +user salt, \fBv\fR the password verifier and \fBinfo\fR is the optional user info. +.PP +The \fBSSL_set_srp_server_param_pw()\fR function sets all SRP parameters for the +connection \fBs\fR by generating a random salt and a password verifier. +\&\fBuser\fR is the username, \fBpass\fR the password and \fBgrp\fR the SRP group parameters +identifier for \fBSRP_get_default_gN\fR\|(3). +.PP +The \fBSSL_get_srp_g()\fR function returns the SRP group generator for \fBs\fR, or from +the underlying SSL_CTX if it is NULL. +.PP +The \fBSSL_get_srp_N()\fR function returns the SRP prime for \fBs\fR, or from +the underlying SSL_CTX if it is NULL. +.PP +The \fBSSL_get_srp_username()\fR function returns the SRP username for \fBs\fR, or from +the underlying SSL_CTX if it is NULL. +.PP +The \fBSSL_get_srp_userinfo()\fR function returns the SRP user info for \fBs\fR, or from +the underlying SSL_CTX if it is NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All SSL_CTX_set_* functions return 1 on success and 0 on failure. +.PP +\&\fBSSL_set_srp_server_param()\fR returns 1 on success and \-1 on failure. +.PP +The SSL_get_SRP_* functions return a pointer to the requested data, the memory +is owned by the library and should not be freed by the caller. +.SH EXAMPLES +.IX Header "EXAMPLES" +Setup SRP parameters on the client: +.PP +.Vb 1 +\& #include +\& +\& const char *username = "username"; +\& const char *password = "password"; +\& +\& SSL_CTX *ctx = SSL_CTX_new(TLS_client_method()); +\& if (!ctx) +\& /* Error */ +\& if (!SSL_CTX_set_srp_username(ctx, username)) +\& /* Error */ +\& if (!SSL_CTX_set_srp_password(ctx, password)) +\& /* Error */ +.Ve +.PP +Setup SRP server with verifier file: +.PP +.Vb 2 +\& #include +\& #include +\& +\& const char *srpvfile = "password.srpv"; +\& +\& int srpServerCallback(SSL *s, int *ad, void *arg) +\& { +\& SRP_VBASE *srpData = (SRP_VBASE*) arg; +\& char *username = SSL_get_srp_username(s); +\& +\& SRP_user_pwd *user_pwd = SRP_VBASE_get1_by_user(srpData, username); +\& if (!user_pwd) +\& /* Error */ +\& return SSL3_AL_FATAL; +\& +\& if (SSL_set_srp_server_param(s, user_pwd\->N, user_pwd\->g, +\& user_pwd\->s, user_pwd\->v, user_pwd\->info) < 0) +\& /* Error */ +\& +\& SRP_user_pwd_free(user_pwd); +\& return SSL_ERROR_NONE; +\& } +\& +\& SSL_CTX *ctx = SSL_CTX_new(TLS_server_method()); +\& if (!ctx) +\& /* Error */ +\& +\& /* +\& * seedKey should contain a NUL terminated sequence +\& * of random non NUL bytes +\& */ +\& const char *seedKey; +\& +\& SRP_VBASE *srpData = SRP_VBASE_new(seedKey); +\& if (SRP_VBASE_init(srpData, (char*) srpvfile) != SRP_NO_ERROR) +\& /* Error */ +\& +\& SSL_CTX_set_srp_cb_arg(ctx, srpData); +\& SSL_CTX_set_srp_username_callback(ctx, srpServerCallback); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBopenssl\-srp\fR\|(1), +\&\fBSRP_VBASE_new\fR\|(3), +\&\fBSRP_create_verifier\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.1 and deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_ssl_version.3 b/static/netbsd/man3/SSL_CTX_set_ssl_version.3 new file mode 100644 index 00000000..8f6ce8c5 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_ssl_version.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: SSL_CTX_set_ssl_version.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_ssl_version 3" +.TH SSL_CTX_set_ssl_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_ssl_version, SSL_CTX_get_ssl_method, SSL_set_ssl_method, SSL_get_ssl_method +\&\- choose a new TLS/SSL method +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method); +\& const SSL_METHOD *SSL_CTX_get_ssl_method(const SSL_CTX *ctx); +\& +\& int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method); +\& const SSL_METHOD *SSL_get_ssl_method(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_ssl_version()\fR sets a new default TLS/SSL \fBmethod\fR for SSL objects +newly created from this \fBctx\fR. Most of the configuration attached to the +SSL_CTX object is retained, with the exception of the configured TLS ciphers, +which are reset to the default values. SSL objects already created from this +SSL_CTX with \fBSSL_new\fR\|(3) are not affected, except when \fBSSL_clear\fR\|(3) is +being called, as described below. +.PP +\&\fBSSL_CTX_get_ssl_method()\fR returns the SSL_METHOD which was used to construct the +SSL_CTX. +.PP +\&\fBSSL_set_ssl_method()\fR sets a new TLS/SSL \fBmethod\fR for a particular \fBssl\fR +object. It may be reset, when \fBSSL_clear()\fR is called. +.PP +\&\fBSSL_get_ssl_method()\fR returns a pointer to the TLS/SSL method +set in \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +The available \fBmethod\fR choices are described in +\&\fBSSL_CTX_new\fR\|(3). +.PP +When \fBSSL_clear\fR\|(3) is called and no session is connected to +an SSL object, the method of the SSL object is reset to the method currently +set in the corresponding SSL_CTX object. +.PP +\&\fBSSL_CTX_set_version()\fR has unusual semantics and no clear use case; +it would usually be preferable to create a new SSL_CTX object than to +try to reuse an existing one in this fashion. Its usage is considered +deprecated. +.PP +\&\fBSSL_set_ssl_method()\fR cannot be used to change a non\-QUIC SSL object to a QUIC +SSL object or vice versa, or change a QUIC SSL object from one QUIC method to +another. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur for \fBSSL_CTX_set_ssl_version()\fR +and \fBSSL_set_ssl_method()\fR: +.IP 0 4 +The new choice failed, check the error stack to find out the reason. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.PP +\&\fBSSL_CTX_get_ssl_method()\fR and \fBSSL_get_ssl_method()\fR always return non\-NULL +pointers. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_new\fR\|(3), \fBSSL_new\fR\|(3), +\&\fBSSL_clear\fR\|(3), \fBssl\fR\|(7), +\&\fBSSL_set_connect_state\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_ssl_version()\fR was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_stateless_cookie_generate_cb.3 b/static/netbsd/man3/SSL_CTX_set_stateless_cookie_generate_cb.3 new file mode 100644 index 00000000..3934ab1d --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_stateless_cookie_generate_cb.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: SSL_CTX_set_stateless_cookie_generate_cb.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_stateless_cookie_generate_cb 3" +.TH SSL_CTX_set_stateless_cookie_generate_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_stateless_cookie_generate_cb, +SSL_CTX_set_stateless_cookie_verify_cb, +SSL_CTX_set_cookie_generate_cb, +SSL_CTX_set_cookie_verify_cb +\&\- Callback functions for stateless TLS1.3 cookies +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_stateless_cookie_generate_cb( +\& SSL_CTX *ctx, +\& int (*gen_stateless_cookie_cb) (SSL *ssl, +\& unsigned char *cookie, +\& size_t *cookie_len)); +\& void SSL_CTX_set_stateless_cookie_verify_cb( +\& SSL_CTX *ctx, +\& int (*verify_stateless_cookie_cb) (SSL *ssl, +\& const unsigned char *cookie, +\& size_t cookie_len)); +\& +\& void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx, +\& int (*app_gen_cookie_cb) (SSL *ssl, +\& unsigned char +\& *cookie, +\& unsigned int +\& *cookie_len)); +\& void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx, +\& int (*app_verify_cookie_cb) (SSL *ssl, +\& const unsigned +\& char *cookie, +\& unsigned int +\& cookie_len)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_stateless_cookie_generate_cb()\fR sets the callback used by +\&\fBSSL_stateless\fR\|(3) to generate the application\-controlled portion of the cookie +provided to clients in the HelloRetryRequest transmitted as a response to a +ClientHello with a missing or invalid cookie. \fBgen_stateless_cookie_cb()\fR must +write at most SSL_COOKIE_LENGTH bytes into \fBcookie\fR, and must write the number +of bytes written to \fBcookie_len\fR. If a cookie cannot be generated, a zero +return value can be used to abort the handshake. +.PP +\&\fBSSL_CTX_set_stateless_cookie_verify_cb()\fR sets the callback used by +\&\fBSSL_stateless\fR\|(3) to determine whether the application\-controlled portion of a +ClientHello cookie is valid. The cookie data is pointed to by \fBcookie\fR and is of +length \fBcookie_len\fR. A nonzero return value from \fBverify_stateless_cookie_cb()\fR +communicates that the cookie is valid. The integrity of the entire cookie, +including the application\-controlled portion, is automatically verified by HMAC +before \fBverify_stateless_cookie_cb()\fR is called. +.PP +\&\fBSSL_CTX_set_cookie_generate_cb()\fR sets the callback used by \fBDTLSv1_listen\fR\|(3) +to generate the cookie provided to clients in the HelloVerifyRequest transmitted +as a response to a ClientHello with a missing or invalid cookie. +\&\fBapp_gen_cookie_cb()\fR must write at most DTLS1_COOKIE_LENGTH bytes into +\&\fBcookie\fR, and must write the number of bytes written to \fBcookie_len\fR. If a +cookie cannot be generated, a zero return value can be used to abort the +handshake. +.PP +\&\fBSSL_CTX_set_cookie_verify_cb()\fR sets the callback used by \fBDTLSv1_listen\fR\|(3) to +determine whether the cookie in a ClientHello is valid. The cookie data is +pointed to by \fBcookie\fR and is of length \fBcookie_len\fR. A nonzero return value +from \fBapp_verify_cookie_cb()\fR communicates that the cookie is valid. The +integrity of the cookie is not verified by OpenSSL. This is an application +responsibility. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Neither function returns a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_stateless\fR\|(3), +\&\fBDTLSv1_listen\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_stateless_cookie_generate_cb()\fR and +\&\fBSSL_CTX_set_stateless_cookie_verify_cb()\fR were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_timeout.3 b/static/netbsd/man3/SSL_CTX_set_timeout.3 new file mode 100644 index 00000000..8bb0e536 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_timeout.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: SSL_CTX_set_timeout.3,v 1.5 2026/04/08 17:06:47 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_timeout 3" +.TH SSL_CTX_set_timeout 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_timeout, SSL_CTX_get_timeout \- manipulate timeout values for session caching +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); +\& long SSL_CTX_get_timeout(SSL_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_timeout()\fR sets the timeout for newly created sessions for +\&\fBctx\fR to \fBt\fR. The timeout value \fBt\fR must be given in seconds. +.PP +\&\fBSSL_CTX_get_timeout()\fR returns the currently set timeout value for \fBctx\fR. +.SH NOTES +.IX Header "NOTES" +Whenever a new session is created, it is assigned a maximum lifetime. This +lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. If the actual time is later than creation +time plus timeout, the session is not reused. +.PP +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. Changes of the timeout value +do not affect already established sessions. +.PP +The expiration time of a single session can be modified using the +\&\fBSSL_SESSION_get_time\fR\|(3) family of functions. +.PP +Expired sessions are removed from the internal session cache, whenever +\&\fBSSL_CTX_flush_sessions\fR\|(3) is called, either +directly by the application or automatically (see +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3)) +.PP +The default value for session timeout is decided on a per protocol +basis, see \fBSSL_get_default_timeout\fR\|(3). +All currently supported protocols have the same default timeout value +of 300 seconds. +.PP +This timeout value is used as the ticket lifetime hint for stateless session +tickets. It is also used as the timeout value within the ticket itself. +.PP +For TLSv1.3, RFC8446 limits transmission of this value to 1 week (604800 +seconds). +.PP +For TLSv1.2, tickets generated during an initial handshake use the value +as specified. Tickets generated during a resumed handshake have a value +of 0 for the ticket lifetime hint. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_timeout()\fR returns the previously set timeout value. +.PP +\&\fBSSL_CTX_get_timeout()\fR returns the currently set timeout value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3), +\&\fBSSL_get_default_timeout\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 b/static/netbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 new file mode 100644 index 00000000..192c77bf --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tlsext_servername_callback.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: SSL_CTX_set_tlsext_servername_callback.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tlsext_servername_callback 3" +.TH SSL_CTX_set_tlsext_servername_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg, +SSL_get_servername_type, SSL_get_servername, +SSL_set_tlsext_host_name \- handle server name indication (SNI) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx, +\& int (*cb)(SSL *s, int *al, void *arg)); +\& long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg); +\& +\& const char *SSL_get_servername(const SSL *s, const int type); +\& int SSL_get_servername_type(const SSL *s); +\& +\& int SSL_set_tlsext_host_name(const SSL *s, const char *name); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functionality provided by the servername callback is mostly superseded by +the ClientHello callback, which can be set using \fBSSL_CTX_set_client_hello_cb()\fR. +However, even where the ClientHello callback is used, the servername callback is +still necessary in order to acknowledge the servername requested by the client. +.PP +\&\fBSSL_CTX_set_tlsext_servername_callback()\fR sets the application callback \fBcb\fR +used by a server to perform any actions or configuration required based on +the servername extension received in the incoming connection. When \fBcb\fR +is NULL, SNI is not used. +.PP +The servername callback should return one of the following values: +.IP SSL_TLSEXT_ERR_OK 4 +.IX Item "SSL_TLSEXT_ERR_OK" +This is used to indicate that the servername requested by the client has been +accepted. Typically a server will call \fBSSL_set_SSL_CTX()\fR in the callback to set +up a different configuration for the selected servername in this case. +.IP SSL_TLSEXT_ERR_ALERT_FATAL 4 +.IX Item "SSL_TLSEXT_ERR_ALERT_FATAL" +In this case the servername requested by the client is not accepted and the +handshake will be aborted. The value of the alert to be used should be stored in +the location pointed to by the \fBal\fR parameter to the callback. By default this +value is initialised to SSL_AD_UNRECOGNIZED_NAME. +.IP SSL_TLSEXT_ERR_ALERT_WARNING 4 +.IX Item "SSL_TLSEXT_ERR_ALERT_WARNING" +If this value is returned then the servername is not accepted by the server. +However, the handshake will continue and send a warning alert instead. The value +of the alert should be stored in the location pointed to by the \fBal\fR parameter +as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support +warning alerts, so if TLSv1.3 has been negotiated then this return value is +treated the same way as SSL_TLSEXT_ERR_NOACK. +.IP SSL_TLSEXT_ERR_NOACK 4 +.IX Item "SSL_TLSEXT_ERR_NOACK" +This return value indicates that the servername is not accepted by the server. +No alerts are sent and the server will not acknowledge the requested servername. +.PP +\&\fBSSL_CTX_set_tlsext_servername_arg()\fR sets a context\-specific argument to be +passed into the callback (via the \fBarg\fR parameter) for this \fBSSL_CTX\fR. +.PP +The behaviour of \fBSSL_get_servername()\fR depends on a number of different factors. +In particular note that in TLSv1.3 the servername is negotiated in every +handshake. In TLSv1.2 the servername is only negotiated on initial handshakes +and not on resumption handshakes. +.IP "On the client, before the handshake" 4 +.IX Item "On the client, before the handshake" +If a servername has been set via a call to \fBSSL_set_tlsext_host_name()\fR then it +will return that servername. +.Sp +If one has not been set, but a TLSv1.2 resumption is being attempted and the +session from the original handshake had a servername accepted by the server then +it will return that servername. +.Sp +Otherwise it returns NULL. +.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" 4 +.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" +If the session from the original handshake had a servername accepted by the +server then it will return that servername. +.Sp +Otherwise it returns the servername set via \fBSSL_set_tlsext_host_name()\fR or NULL +if it was not called. +.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" 4 +.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" +It will return the servername set via \fBSSL_set_tlsext_host_name()\fR or NULL if it +was not called. +.IP "On the server, before the handshake" 4 +.IX Item "On the server, before the handshake" +The function will always return NULL before the handshake +.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" 4 +.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" +If a servername was accepted by the server in the original handshake then it +will return that servername, or NULL otherwise. +.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" 4 +.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" +The function will return the servername requested by the client in this +handshake or NULL if none was requested. +.PP +Note that the ClientHello callback occurs before a servername extension from the +client is processed. The servername, certificate and ALPN callbacks occur after +a servername extension from the client is processed. +.PP +\&\fBSSL_get_servername_type()\fR returns the servername type or \-1 if no servername +is present. Currently the only supported type (defined in RFC3546) is +\&\fBTLSEXT_NAMETYPE_host_name\fR. +.PP +\&\fBSSL_set_tlsext_host_name()\fR sets the server name indication ClientHello extension +to contain the value \fBname\fR. The type of server name indication extension is set +to \fBTLSEXT_NAMETYPE_host_name\fR (defined in RFC3546). +.SH NOTES +.IX Header "NOTES" +Several callbacks are executed during ClientHello processing, including +the ClientHello, ALPN, and servername callbacks. The ClientHello callback is +executed first, then the servername callback, followed by the ALPN callback. +.PP +The \fBSSL_set_tlsext_host_name()\fR function should only be called on SSL objects +that will act as clients; otherwise the configured \fBname\fR will be ignored. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_tlsext_servername_callback()\fR and +\&\fBSSL_CTX_set_tlsext_servername_arg()\fR both always return 1 indicating success. +\&\fBSSL_set_tlsext_host_name()\fR returns 1 on success, 0 in case of error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_alpn_select_cb\fR\|(3), +\&\fBSSL_get0_alpn_selected\fR\|(3), \fBSSL_CTX_set_client_hello_cb\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_get_servername()\fR historically provided some unexpected results in certain +corner cases. This has been fixed from OpenSSL 1.1.1e. +.PP +Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2 +handshake, the server accepted it, and then the client successfully resumed but +set a different explicit servername in the second handshake then when called by +the client it returned the servername from the second handshake. This has now +been changed to return the servername requested in the original handshake. +.PP +Also prior to 1.1.1e, if the client sent a servername in the first handshake but +the server did not accept it, and then a second handshake occurred where TLSv1.2 +resumption was successful then when called by the server it returned the +servername requested in the original handshake. This has now been changed to +NULL. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tlsext_status_cb.3 b/static/netbsd/man3/SSL_CTX_set_tlsext_status_cb.3 new file mode 100644 index 00000000..94b13c70 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tlsext_status_cb.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: SSL_CTX_set_tlsext_status_cb.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tlsext_status_cb 3" +.TH SSL_CTX_set_tlsext_status_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_tlsext_status_cb, +SSL_CTX_get_tlsext_status_cb, +SSL_CTX_set_tlsext_status_arg, +SSL_CTX_get_tlsext_status_arg, +SSL_CTX_set_tlsext_status_type, +SSL_CTX_get_tlsext_status_type, +SSL_set_tlsext_status_type, +SSL_get_tlsext_status_type, +SSL_get_tlsext_status_ocsp_resp, +SSL_set_tlsext_status_ocsp_resp +\&\- OCSP Certificate Status Request functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *)); +\& long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *)); +\& +\& long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); +\& long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg); +\& +\& long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type); +\& long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx); +\& +\& long SSL_set_tlsext_status_type(SSL *s, int type); +\& long SSL_get_tlsext_status_type(SSL *s); +\& +\& long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp); +\& long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A client application may request that a server send back an OCSP status response +(also known as OCSP stapling). To do so the client should call the +\&\fBSSL_CTX_set_tlsext_status_type()\fR function prior to the creation of any SSL +objects. Alternatively an application can call the \fBSSL_set_tlsext_status_type()\fR +function on an individual SSL object prior to the start of the handshake. +Currently the only supported type is \fBTLSEXT_STATUSTYPE_ocsp\fR. This value +should be passed in the \fBtype\fR argument. Calling +\&\fBSSL_CTX_get_tlsext_status_type()\fR will return the type \fBTLSEXT_STATUSTYPE_ocsp\fR +previously set via \fBSSL_CTX_set_tlsext_status_type()\fR or \-1 if not set. +.PP +The client should additionally provide a callback function to decide what to do +with the returned OCSP response by calling \fBSSL_CTX_set_tlsext_status_cb()\fR. The +callback function should determine whether the returned OCSP response is +acceptable or not. The callback will be passed as an argument the value +previously set via a call to \fBSSL_CTX_set_tlsext_status_arg()\fR. Note that the +callback will not be called in the event of a handshake where session resumption +occurs (because there are no Certificates exchanged in such a handshake). +The callback previously set via \fBSSL_CTX_set_tlsext_status_cb()\fR can be retrieved +by calling \fBSSL_CTX_get_tlsext_status_cb()\fR, and the argument by calling +\&\fBSSL_CTX_get_tlsext_status_arg()\fR. +.PP +On the client side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether +the client has previously called \fBSSL_set_tlsext_status_type()\fR. It will return +\&\fBTLSEXT_STATUSTYPE_ocsp\fR if it has been called or \-1 otherwise. On the server +side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether the client +requested OCSP stapling. If the client requested it then this function will +return \fBTLSEXT_STATUSTYPE_ocsp\fR, or \-1 otherwise. +.PP +The response returned by the server can be obtained via a call to +\&\fBSSL_get_tlsext_status_ocsp_resp()\fR. The value \fB*resp\fR will be updated to point +to the OCSP response data and the return value will be the length of that data. +Typically a callback would obtain an OCSP_RESPONSE object from this data via a +call to the \fBd2i_OCSP_RESPONSE()\fR function. If the server has not provided any +response data then \fB*resp\fR will be NULL and the return value from +\&\fBSSL_get_tlsext_status_ocsp_resp()\fR will be \-1. +.PP +A server application must also call the \fBSSL_CTX_set_tlsext_status_cb()\fR function +if it wants to be able to provide clients with OCSP Certificate Status +responses. Typically the server callback would obtain the server certificate +that is being sent back to the client via a call to \fBSSL_get_certificate()\fR; +obtain the OCSP response to be sent back; and then set that response data by +calling \fBSSL_set_tlsext_status_ocsp_resp()\fR. A pointer to the response data should +be provided in the \fBresp\fR argument, and the length of that data should be in +the \fBlen\fR argument. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The callback when used on the client side should return a negative value on +error; 0 if the response is not acceptable (in which case the handshake will +fail) or a positive value if it is acceptable. +.PP +The callback when used on the server side should return with either +SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be +returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be +returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has +occurred). +.PP +\&\fBSSL_CTX_set_tlsext_status_cb()\fR, \fBSSL_CTX_set_tlsext_status_arg()\fR, +\&\fBSSL_CTX_set_tlsext_status_type()\fR, \fBSSL_set_tlsext_status_type()\fR and +\&\fBSSL_set_tlsext_status_ocsp_resp()\fR return 0 on error or 1 on success. +.PP +\&\fBSSL_CTX_get_tlsext_status_type()\fR returns the value previously set by +\&\fBSSL_CTX_set_tlsext_status_type()\fR, or \-1 if not set. +.PP +\&\fBSSL_get_tlsext_status_ocsp_resp()\fR returns the length of the OCSP response data +or \-1 if there is no OCSP response data. +.PP +\&\fBSSL_get_tlsext_status_type()\fR returns \fBTLSEXT_STATUSTYPE_ocsp\fR on the client +side if \fBSSL_set_tlsext_status_type()\fR was previously called, or on the server +side if the client requested OCSP stapling. Otherwise \-1 is returned. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_get_tlsext_status_type()\fR, \fBSSL_CTX_get_tlsext_status_type()\fR +and \fBSSL_CTX_set_tlsext_status_type()\fR functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 b/static/netbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 new file mode 100644 index 00000000..1d46d310 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tlsext_ticket_key_cb.3 @@ -0,0 +1,302 @@ +.\" $NetBSD: SSL_CTX_set_tlsext_ticket_key_cb.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tlsext_ticket_key_cb 3" +.TH SSL_CTX_set_tlsext_ticket_key_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_tlsext_ticket_key_evp_cb, +SSL_CTX_set_tlsext_ticket_key_cb +\&\- set a callback for session ticket processing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx, +\& int (*cb)(SSL *s, unsigned char key_name[16], +\& unsigned char iv[EVP_MAX_IV_LENGTH], +\& EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc)); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, +\& int (*cb)(SSL *s, unsigned char key_name[16], +\& unsigned char iv[EVP_MAX_IV_LENGTH], +\& EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR sets a callback function \fIcb\fR for handling +session tickets for the ssl context \fIsslctx\fR. Session tickets, defined in +RFC5077 provide an enhanced session resumption capability where the server +implementation is not required to maintain per session state. It only applies +to TLS and there is no SSLv3 implementation. +.PP +The callback function \fIcb\fR will be called for every client instigated TLS +session when session ticket extension is presented in the TLS hello +message. It is the responsibility of this function to create or retrieve the +cryptographic parameters and to maintain their state. +.PP +The OpenSSL library uses your callback function to help implement a common TLS +ticket construction state according to RFC5077 Section 4 such that per session +state is unnecessary and a small set of cryptographic variables needs to be +maintained by the callback function implementation. +.PP +In order to reuse a session, a TLS client must send the session ticket +extension to the server. The client must send exactly one session ticket. +The server, through the callback function, either agrees to reuse the session +ticket information or it starts a full TLS handshake to create a new session +ticket. +.PP +Before the callback function is started \fIctx\fR and \fIhctx\fR have been +initialised with \fBEVP_CIPHER_CTX_reset\fR\|(3) and \fBEVP_MAC_CTX_new\fR\|(3) +respectively. +.PP +For new sessions tickets, when the client doesn\*(Aqt present a session ticket, or +an attempted retrieval of the ticket failed, or a renew option was indicated, +the callback function will be called with \fIenc\fR equal to 1. The OpenSSL +library expects that the function will set an arbitrary \fIname\fR, initialize +\&\fIiv\fR, and set the cipher context \fIctx\fR and the hash context \fIhctx\fR. +.PP +The \fIname\fR is 16 characters long and is used as a key identifier. +.PP +The \fIiv\fR length is the length of the IV of the corresponding cipher. The +maximum IV length is \fBEVP_MAX_IV_LENGTH\fR bytes defined in \fI\fR. +.PP +The initialization vector \fIiv\fR should be a random value. The cipher context +\&\fIctx\fR should use the initialisation vector \fIiv\fR. The cipher context can be +set using \fBEVP_EncryptInit_ex\fR\|(3). The hmac context and digest can be set using +\&\fBEVP_MAC_CTX_set_params\fR\|(3) with the \fBOSSL_MAC_PARAM_KEY\fR and +\&\fBOSSL_MAC_PARAM_DIGEST\fR parameters respectively. +.PP +When the client presents a session ticket, the callback function with be called +with \fIenc\fR set to 0 indicating that the \fIcb\fR function should retrieve a set +of parameters. In this case \fIname\fR and \fIiv\fR have already been parsed out of +the session ticket. The OpenSSL library expects that the \fIname\fR will be used +to retrieve a cryptographic parameters and that the cryptographic context +\&\fIctx\fR will be set with the retrieved parameters and the initialization vector +\&\fIiv\fR. using a function like \fBEVP_DecryptInit_ex\fR\|(3). The key material and +digest for \fIhctx\fR need to be set using \fBEVP_MAC_CTX_set_params\fR\|(3) with the +\&\fBOSSL_MAC_PARAM_KEY\fR and \fBOSSL_MAC_PARAM_DIGEST\fR parameters respectively. +.PP +If the \fIname\fR is still valid but a renewal of the ticket is required the +callback function should return 2. The library will call the callback again +with an argument of enc equal to 1 to set the new ticket. +.PP +The return value of the \fIcb\fR function is used by OpenSSL to determine what +further processing will occur. The following return values have meaning: +.IP 2 4 +.IX Item "2" +This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can +continue on those parameters. Additionally it indicates that the session +ticket is in a renewal period and should be replaced. The OpenSSL library will +call \fIcb\fR again with an enc argument of 1 to set the new ticket (see RFC5077 +3.3 paragraph 2). +.IP 1 4 +.IX Item "1" +This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can +continue on those parameters. +.IP 0 4 +This indicates that it was not possible to set/retrieve a session ticket and +the SSL/TLS session will continue by negotiating a set of cryptographic +parameters or using the alternate SSL/TLS resumption mechanism, session ids. +.Sp +If called with enc equal to 0 the library will call the \fIcb\fR again to get +a new set of parameters. +.IP "less than 0" 4 +.IX Item "less than 0" +This indicates an error. +.PP +The \fBSSL_CTX_set_tlsext_ticket_key_cb()\fR function is identical to +\&\fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR except that it takes a deprecated +HMAC_CTX pointer instead of an EVP_MAC_CTX one. +Before this callback function is started \fIhctx\fR will have been +initialised with \fBEVP_MAC_CTX_new\fR\|(3) and the digest set with +\&\fBEVP_MAC_CTX_set_params\fR\|(3). +The \fIhctx\fR key material can be set using \fBHMAC_Init_ex\fR\|(3). +.SH NOTES +.IX Header "NOTES" +Session resumption shortcuts the TLS handshake so that the client certificate +negotiation doesn\*(Aqt occur. It makes up for this by storing the client certificate +and all other negotiated state information encrypted within the ticket. In a +resumed session the applications will have all this state information available +exactly as if a full negotiation had occurred. +.PP +If an attacker can obtain the key used to encrypt a session ticket, they can +obtain the master secret for any ticket using that key and decrypt any traffic +using that session: even if the cipher suite supports forward secrecy. As +a result applications may wish to use multiple keys and avoid using long term +keys stored in files. +.PP +Applications can use longer keys to maintain a consistent level of security. +For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key +the overall security is only 128 bits because breaking the ticket key will +enable an attacker to obtain the session keys. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 to indicate the callback function was set and 0 otherwise. +.SH EXAMPLES +.IX Header "EXAMPLES" +Reference Implementation: +.PP +.Vb 2 +\& SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb); +\& ... +\& +\& static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], +\& unsigned char *iv, EVP_CIPHER_CTX *ctx, +\& EVP_MAC_CTX *hctx, int enc) +\& { +\& OSSL_PARAM params[3]; +\& your_type_t *key; /* something that you need to implement */ +\& +\& if (enc) { /* create new session */ +\& if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0) +\& return \-1; /* insufficient random */ +\& +\& key = currentkey(); /* something that you need to implement */ +\& if (key == NULL) { +\& /* current key doesn\*(Aqt exist or isn\*(Aqt valid */ +\& key = createkey(); /* +\& * Something that you need to implement. +\& * createkey needs to initialise a name, +\& * an aes_key, a hmac_key and optionally +\& * an expire time. +\& */ +\& if (key == NULL) /* key couldn\*(Aqt be created */ +\& return 0; +\& } +\& memcpy(key_name, key\->name, 16); +\& +\& if (EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key\->aes_key, +\& iv) == 0) +\& return \-1; /* error in cipher initialisation */ +\& +\& params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, +\& key\->hmac_key, 32); +\& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, +\& "sha256", 0); +\& params[2] = OSSL_PARAM_construct_end(); +\& if (EVP_MAC_CTX_set_params(hctx, params) == 0) +\& return \-1; /* error in mac initialisation */ +\& +\& return 1; +\& +\& } else { /* retrieve session */ +\& time_t t = time(NULL); +\& key = findkey(key_name); /* something that you need to implement */ +\& +\& if (key == NULL || key\->expire < t) +\& return 0; +\& +\& params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, +\& key\->hmac_key, 32); +\& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, +\& "sha256", 0); +\& params[2] = OSSL_PARAM_construct_end(); +\& if (EVP_MAC_CTX_set_params(hctx, params) == 0) +\& return \-1; /* error in mac initialisation */ +\& +\& if (EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key\->aes_key, +\& iv) == 0) +\& return \-1; /* error in cipher initialisation */ +\& +\& if (key\->expire < t \- RENEW_TIME) { /* RENEW_TIME: implement */ +\& /* +\& * return 2 \- This session will get a new ticket even though the +\& * current one is still valid. +\& */ +\& return 2; +\& } +\& return 1; +\& } +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3), +\&\fBSSL_session_reused\fR\|(3), +\&\fBSSL_CTX_add_session\fR\|(3), +\&\fBSSL_CTX_sess_number\fR\|(3), +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3), +\&\fBSSL_CTX_set_session_id_context\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CTX_set_tlsext_ticket_key_cb()\fR function was deprecated in OpenSSL 3.0. +.PP +The \fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR function was introduced in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 b/static/netbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 new file mode 100644 index 00000000..2746c312 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tlsext_use_srtp.3 @@ -0,0 +1,191 @@ +.\" $NetBSD: SSL_CTX_set_tlsext_use_srtp.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tlsext_use_srtp 3" +.TH SSL_CTX_set_tlsext_use_srtp 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_tlsext_use_srtp, +SSL_set_tlsext_use_srtp, +SSL_get_srtp_profiles, +SSL_get_selected_srtp_profile +\&\- Configure and query SRTP support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles); +\& int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles); +\& +\& STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl); +\& SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +SRTP is the Secure Real\-Time Transport Protocol. OpenSSL implements support for +the "use_srtp" DTLS extension defined in RFC5764. This provides a mechanism for +establishing SRTP keying material, algorithms and parameters using DTLS. This +capability may be used as part of an implementation that conforms to RFC5763. +OpenSSL does not implement SRTP itself or RFC5763. Note that OpenSSL does not +support the use of SRTP Master Key Identifiers (MKIs). Also note that this +extension is only supported in DTLS. Any SRTP configuration will be ignored if a +TLS connection is attempted. +.PP +An OpenSSL client wishing to send the "use_srtp" extension should call +\&\fBSSL_CTX_set_tlsext_use_srtp()\fR to set its use for all SSL objects subsequently +created from an SSL_CTX. Alternatively a client may call +\&\fBSSL_set_tlsext_use_srtp()\fR to set its use for an individual SSL object. The +\&\fBprofiles\fR parameters should point to a NUL\-terminated, colon delimited list of +SRTP protection profile names. +.PP +The currently supported protection profile names are: +.IP SRTP_AES128_CM_SHA1_80 4 +.IX Item "SRTP_AES128_CM_SHA1_80" +This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC5764. +.IP SRTP_AES128_CM_SHA1_32 4 +.IX Item "SRTP_AES128_CM_SHA1_32" +This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC5764. +.IP SRTP_AEAD_AES_128_GCM 4 +.IX Item "SRTP_AEAD_AES_128_GCM" +This corresponds to the profile of the same name defined in RFC7714. +.IP SRTP_AEAD_AES_256_GCM 4 +.IX Item "SRTP_AEAD_AES_256_GCM" +This corresponds to the profile of the same name defined in RFC7714. +.IP SRTP_DOUBLE_AEAD_AES_128_GCM_AEAD_AES_128_GCM 4 +.IX Item "SRTP_DOUBLE_AEAD_AES_128_GCM_AEAD_AES_128_GCM" +This corresponds to the profile of the same name defined in RFC8723. +.IP SRTP_DOUBLE_AEAD_AES_256_GCM_AEAD_AES_256_GCM 4 +.IX Item "SRTP_DOUBLE_AEAD_AES_256_GCM_AEAD_AES_256_GCM" +This corresponds to the profile of the same name defined in RFC8723. +.IP SRTP_ARIA_128_CTR_HMAC_SHA1_80 4 +.IX Item "SRTP_ARIA_128_CTR_HMAC_SHA1_80" +This corresponds to the profile of the same name defined in RFC8269. +.IP SRTP_ARIA_128_CTR_HMAC_SHA1_32 4 +.IX Item "SRTP_ARIA_128_CTR_HMAC_SHA1_32" +This corresponds to the profile of the same name defined in RFC8269. +.IP SRTP_ARIA_256_CTR_HMAC_SHA1_80 4 +.IX Item "SRTP_ARIA_256_CTR_HMAC_SHA1_80" +This corresponds to the profile of the same name defined in RFC8269. +.IP SRTP_ARIA_256_CTR_HMAC_SHA1_32 4 +.IX Item "SRTP_ARIA_256_CTR_HMAC_SHA1_32" +This corresponds to the profile of the same name defined in RFC8269. +.IP SRTP_AEAD_ARIA_128_GCM 4 +.IX Item "SRTP_AEAD_ARIA_128_GCM" +This corresponds to the profile of the same name defined in RFC8269. +.IP SRTP_AEAD_ARIA_256_GCM 4 +.IX Item "SRTP_AEAD_ARIA_256_GCM" +This corresponds to the profile of the same name defined in RFC8269. +.PP +Supplying an unrecognised protection profile name will result in an error. +.PP +An OpenSSL server wishing to support the "use_srtp" extension should also call +\&\fBSSL_CTX_set_tlsext_use_srtp()\fR or \fBSSL_set_tlsext_use_srtp()\fR to indicate the +protection profiles that it is willing to negotiate. +.PP +The currently configured list of protection profiles for either a client or a +server can be obtained by calling \fBSSL_get_srtp_profiles()\fR. This returns a stack +of SRTP_PROTECTION_PROFILE objects. The memory pointed to in the return value of +this function should not be freed by the caller. +.PP +After a handshake has been completed the negotiated SRTP protection profile (if +any) can be obtained (on the client or the server) by calling +\&\fBSSL_get_selected_srtp_profile()\fR. This function will return NULL if no SRTP +protection profile was negotiated. The memory returned from this function should +not be freed by the caller. +.PP +If an SRTP protection profile has been successfully negotiated then the SRTP +keying material (on both the client and server) should be obtained via a call to +\&\fBSSL_export_keying_material\fR\|(3). This call should provide a label value of +"EXTRACTOR\-dtls_srtp" and a NULL context value (use_context is 0). The total +length of keying material obtained should be equal to two times the sum of the +master key length and the salt length as defined for the protection profile in +use. This provides the client write master key, the server write master key, the +client write master salt and the server write master salt in that order. +.PP +These functions cannot be used with QUIC SSL objects. +\&\fBSSL_CTX_set_tlsext_use_srtp()\fR fails if called on a QUIC SSL context. +\&\fBSSL_set_tlsext_use_srtp()\fR fails if called on a QUIC SSL object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_tlsext_use_srtp()\fR and \fBSSL_set_tlsext_use_srtp()\fR return 0 on success +or 1 on error. +.PP +\&\fBSSL_get_srtp_profiles()\fR returns a stack of SRTP_PROTECTION_PROFILE objects on +success or NULL on error or if no protection profiles have been configured. +.PP +\&\fBSSL_get_selected_srtp_profile()\fR returns a pointer to an SRTP_PROTECTION_PROFILE +object if one has been negotiated or NULL otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_export_keying_material\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tmp_dh_callback.3 b/static/netbsd/man3/SSL_CTX_set_tmp_dh_callback.3 new file mode 100644 index 00000000..c123d9fc --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tmp_dh_callback.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tmp_dh_callback 3" +.TH SSL_CTX_set_tmp_dh_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_dh_auto, SSL_set_dh_auto, SSL_CTX_set0_tmp_dh_pkey, +SSL_set0_tmp_dh_pkey, SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, +SSL_set_tmp_dh_callback, SSL_set_tmp_dh +\&\- handle DH keys for ephemeral key exchange +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_dh_auto(SSL_CTX *ctx, int onoff); +\& long SSL_set_dh_auto(SSL *s, int onoff); +\& int SSL_CTX_set0_tmp_dh_pkey(SSL_CTX *ctx, EVP_PKEY *dhpkey); +\& int SSL_set0_tmp_dh_pkey(SSL *s, EVP_PKEY *dhpkey); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, +\& DH *(*tmp_dh_callback)(SSL *ssl, int is_export, +\& int keylength)); +\& long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); +\& +\& void SSL_set_tmp_dh_callback(SSL *ctx, +\& DH *(*tmp_dh_callback)(SSL *ssl, int is_export, +\& int keylength)); +\& long SSL_set_tmp_dh(SSL *ssl, DH *dh); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions described on this page are relevant for servers only. +.PP +Some ciphersuites may use ephemeral Diffie\-Hellman (DH) key exchange. In these +cases, the session data is negotiated using the ephemeral/temporary DH key and +the key supplied and certified by the certificate chain is only used for +signing. Anonymous ciphers (without a permanent server key) also use ephemeral +DH keys. +.PP +Using ephemeral DH key exchange yields forward secrecy as the connection +can only be decrypted when the DH key is known. By generating a temporary +DH key inside the server application that is lost when the application +is left, it becomes impossible for an attacker to decrypt past sessions, +even if they get hold of the normal (certified) key, as this key was +only used for signing. +.PP +In order to perform a DH key exchange the server must use a DH group +(DH parameters) and generate a DH key. The server will always generate +a new DH key during the negotiation. +.PP +As generating DH parameters is extremely time consuming, an application +should not generate the parameters on the fly. DH parameters can be reused, as +the actual key is newly generated during the negotiation. +.PP +Typically applications should use well known DH parameters that have built\-in +support in OpenSSL. The macros \fBSSL_CTX_set_dh_auto()\fR and \fBSSL_set_dh_auto()\fR +configure OpenSSL to use the default built\-in DH parameters for the \fBSSL_CTX\fR +and \fBSSL\fR objects respectively. Passing a value of 2 or 1 in the \fIonoff\fR +parameter switches it on. If the \fIonoff\fR parameter is set to 2, it will force +the DH key size to 1024 if the \fBSSL_CTX\fR or \fBSSL\fR security level +\&\fBSSL_CTX_set_security_level\fR\|(3) is 0 or 1. Passing a value of 0 switches +it off. The default setting is off. +.PP +If "auto" DH parameters are switched on then the parameters will be selected to +be consistent with the size of the key associated with the server\*(Aqs certificate. +If there is no certificate (e.g. for PSK ciphersuites), then it it will be +consistent with the size of the negotiated symmetric cipher key. +.PP +Applications may supply their own DH parameters instead of using the built\-in +values. This approach is discouraged and applications should in preference use +the built\-in parameter support described above. Applications wishing to supply +their own DH parameters should call \fBSSL_CTX_set0_tmp_dh_pkey()\fR or +\&\fBSSL_set0_tmp_dh_pkey()\fR to supply the parameters for the \fBSSL_CTX\fR or \fBSSL\fR +respectively. The parameters should be supplied in the \fIdhpkey\fR argument as +an \fBEVP_PKEY\fR containing DH parameters. Ownership of the \fIdhpkey\fR value is +passed to the \fBSSL_CTX\fR or \fBSSL\fR object as a result of this call, and so the +caller should not free it if the function call is successful. +.PP +The deprecated macros \fBSSL_CTX_set_tmp_dh()\fR and \fBSSL_set_tmp_dh()\fR do the same +thing as \fBSSL_CTX_set0_tmp_dh_pkey()\fR and \fBSSL_set0_tmp_dh_pkey()\fR except that the +DH parameters are supplied in a \fBDH\fR object instead in the \fIdh\fR argument, and +ownership of the \fBDH\fR object is retained by the application. Applications +should use "auto" parameters instead, or call \fBSSL_CTX_set0_tmp_dh_pkey()\fR or +\&\fBSSL_set0_tmp_dh_pkey()\fR as appropriate. +.PP +An application may instead specify the DH parameters via a callback function +using the functions \fBSSL_CTX_set_tmp_dh_callback()\fR or \fBSSL_set_tmp_dh_callback()\fR +to set the callback for the \fBSSL_CTX\fR or \fBSSL\fR object respectively. These +functions are deprecated. Applications should instead use "auto" parameters, or +specify the parameters via \fBSSL_CTX_set0_tmp_dh_pkey()\fR or \fBSSL_set0_tmp_dh_pkey()\fR +as appropriate. +.PP +The callback will be invoked during a connection when DH parameters are +required. The \fBSSL\fR object for the current connection is supplied as an +argument. Previous versions of OpenSSL used the \fBis_export\fR and \fBkeylength\fR +arguments to control parameter generation for export and non\-export +cipher suites. Modern OpenSSL does not support export ciphersuites and so these +arguments are unused and can be ignored by the callback. The callback should +return the parameters to be used in a DH object. Ownership of the DH object is +retained by the application and should later be freed. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All of these functions/macros return 1 for success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_cipher_list\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), +\&\fBopenssl\-ciphers\fR\|(1), \fBopenssl\-dhparam\fR\|(1) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tmp_ecdh.3 b/static/netbsd/man3/SSL_CTX_set_tmp_ecdh.3 new file mode 100644 index 00000000..bf784e96 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tmp_ecdh.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: SSL_CTX_set_tmp_ecdh.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tmp_ecdh 3" +.TH SSL_CTX_set_tmp_ecdh 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_tmp_ecdh, SSL_set_tmp_ecdh, SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto +\&\- handle ECDH keys for ephemeral key exchange +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_CTX_set_tmp_ecdh(SSL_CTX *ctx, const EC_KEY *ecdh); +\& long SSL_set_tmp_ecdh(SSL *ssl, const EC_KEY *ecdh); +\& +\& long SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int state); +\& long SSL_set_ecdh_auto(SSL *ssl, int state); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_tmp_ecdh()\fR sets ECDH parameters to be used to be \fBecdh\fR. +The key is inherited by all \fBssl\fR objects created from \fBctx\fR. +This macro is deprecated in favor of \fBSSL_CTX_set1_groups\fR\|(3). +.PP +\&\fBSSL_set_tmp_ecdh()\fR sets the parameters only for \fBssl\fR. +This macro is deprecated in favor of \fBSSL_set1_groups\fR\|(3). +.PP +\&\fBSSL_CTX_set_ecdh_auto()\fR and \fBSSL_set_ecdh_auto()\fR are deprecated and +have no effect. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_tmp_ecdh()\fR and \fBSSL_set_tmp_ecdh()\fR return 1 on success and 0 +on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set1_curves\fR\|(3), \fBSSL_CTX_set_cipher_list\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), \fBSSL_CTX_set_tmp_dh_callback\fR\|(3), +\&\fBopenssl\-ciphers\fR\|(1), \fBopenssl\-ecparam\fR\|(1) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 b/static/netbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 new file mode 100644 index 00000000..19620780 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,292 @@ +.\" $NetBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_tmp_rsa_callback 3" +.TH SSL_CTX_set_tmp_rsa_callback 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa \- handle RSA keys for ephemeral key exchange +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, +\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); +\& long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa); +\& long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx); +\& +\& void SSL_set_tmp_rsa_callback(SSL_CTX *ctx, +\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); +\& long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa) +\& long SSL_need_tmp_rsa(SSL *ssl) +\& +\& RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_CTX_set_tmp_rsa_callback()\fR sets the callback function for \fBctx\fR to be +used when a temporary/ephemeral \s-1RSA\s0 key is required to \fBtmp_rsa_callback\fR. +The callback is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR +with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected. +.PP +\&\fISSL_CTX_set_tmp_rsa()\fR sets the temporary/ephemeral \s-1RSA\s0 key to be used to be +\&\fBrsa\fR. The key is inherited by all \s-1SSL\s0 objects newly created from \fBctx\fR +with <\fISSL_new\fR\|(3)|\fISSL_new\fR\|(3)>. Already created \s-1SSL\s0 objects are not affected. +.PP +\&\fISSL_CTX_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed +for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key +with a keysize larger than 512 bits is installed. +.PP +\&\fISSL_set_tmp_rsa_callback()\fR sets the callback only for \fBssl\fR. +.PP +\&\fISSL_set_tmp_rsa()\fR sets the key only for \fBssl\fR. +.PP +\&\fISSL_need_tmp_rsa()\fR returns 1, if a temporary/ephemeral \s-1RSA\s0 key is needed, +for RSA-based strength-limited 'exportable' ciphersuites because a \s-1RSA\s0 key +with a keysize larger than 512 bits is installed. +.PP +These functions apply to \s-1SSL/TLS\s0 servers only. +.SH "NOTES" +.IX Header "NOTES" +When using a cipher with \s-1RSA\s0 authentication, an ephemeral \s-1RSA\s0 key exchange +can take place. In this case the session data are negotiated using the +ephemeral/temporary \s-1RSA\s0 key and the \s-1RSA\s0 key supplied and certified +by the certificate chain is only used for signing. +.PP +Under previous export restrictions, ciphers with \s-1RSA\s0 keys shorter (512 bits) +than the usual key length of 1024 bits were created. To use these ciphers +with \s-1RSA\s0 keys of usual length, an ephemeral key exchange must be performed, +as the normal (certified) key cannot be directly used. +.PP +Using ephemeral \s-1RSA\s0 key exchange yields forward secrecy, as the connection +can only be decrypted, when the \s-1RSA\s0 key is known. By generating a temporary +\&\s-1RSA\s0 key inside the server application that is lost when the application +is left, it becomes impossible for an attacker to decrypt past sessions, +even if he gets hold of the normal (certified) \s-1RSA\s0 key, as this key was +used for signing only. The downside is that creating a \s-1RSA\s0 key is +computationally expensive. +.PP +Additionally, the use of ephemeral \s-1RSA\s0 key exchange is only allowed in +the \s-1TLS\s0 standard, when the \s-1RSA\s0 key can be used for signing only, that is +for export ciphers. Using ephemeral \s-1RSA\s0 key exchange for other purposes +violates the standard and can break interoperability with clients. +It is therefore strongly recommended to not use ephemeral \s-1RSA\s0 key +exchange and use \s-1DHE \s0(Ephemeral Diffie-Hellman) key exchange instead +in order to achieve forward secrecy (see +\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3)). +.PP +An application may either directly specify the key or can supply the key via a +callback function. The callback approach has the advantage, that the callback +may generate the key only in case it is actually needed. As the generation of a +\&\s-1RSA\s0 key is however costly, it will lead to a significant delay in the handshake +procedure. Another advantage of the callback function is that it can supply +keys of different size while the explicit setting of the key is only useful for +key size of 512 bits to satisfy the export restricted ciphers and does give +away key length if a longer key would be allowed. +.PP +The \fBtmp_rsa_callback\fR is called with the \fBkeylength\fR needed and +the \fBis_export\fR information. The \fBis_export\fR flag is set, when the +ephemeral \s-1RSA\s0 key exchange is performed with an export cipher. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Generate temporary \s-1RSA\s0 keys to prepare ephemeral \s-1RSA\s0 key exchange. As the +generation of a \s-1RSA\s0 key costs a lot of computer time, they saved for later +reuse. For demonstration purposes, two keys for 512 bits and 1024 bits +respectively are generated. +.PP +.Vb 4 +\& ... +\& /* Set up ephemeral RSA stuff */ +\& RSA *rsa_512 = NULL; +\& RSA *rsa_1024 = NULL; +\& +\& rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL); +\& if (rsa_512 == NULL) +\& evaluate_error_queue(); +\& +\& rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL); +\& if (rsa_1024 == NULL) +\& evaluate_error_queue(); +\& +\& ... +\& +\& RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength) +\& { +\& RSA *rsa_tmp=NULL; +\& +\& switch (keylength) { +\& case 512: +\& if (rsa_512) +\& rsa_tmp = rsa_512; +\& else { /* generate on the fly, should not happen in this example */ +\& rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL); +\& rsa_512 = rsa_tmp; /* Remember for later reuse */ +\& } +\& break; +\& case 1024: +\& if (rsa_1024) +\& rsa_tmp=rsa_1024; +\& else +\& should_not_happen_in_this_example(); +\& break; +\& default: +\& /* Generating a key on the fly is very costly, so use what is there */ +\& if (rsa_1024) +\& rsa_tmp=rsa_1024; +\& else +\& rsa_tmp=rsa_512; /* Use at least a shorter key */ +\& } +\& return(rsa_tmp); +\& } +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fISSL_CTX_set_tmp_rsa_callback()\fR and \fISSL_set_tmp_rsa_callback()\fR do not return +diagnostic output. +.PP +\&\fISSL_CTX_set_tmp_rsa()\fR and \fISSL_set_tmp_rsa()\fR do return 1 on success and 0 +on failure. Check the error queue to find out the reason of failure. +.PP +\&\fISSL_CTX_need_tmp_rsa()\fR and \fISSL_need_tmp_rsa()\fR return 1 if a temporary +\&\s-1RSA\s0 key is needed and 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(3), \fISSL_CTX_set_cipher_list\fR\|(3), +\&\fISSL_CTX_set_options\fR\|(3), +\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3), +\&\fISSL_new\fR\|(3), \fIopenssl_ciphers\fR\|(1) diff --git a/static/netbsd/man3/SSL_CTX_set_verify.3 b/static/netbsd/man3/SSL_CTX_set_verify.3 new file mode 100644 index 00000000..46382fe8 --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_set_verify.3 @@ -0,0 +1,427 @@ +.\" $NetBSD: SSL_CTX_set_verify.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_set_verify 3" +.TH SSL_CTX_set_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_ex_data_X509_STORE_CTX_idx, +SSL_CTX_set_verify, SSL_set_verify, +SSL_CTX_set_verify_depth, SSL_set_verify_depth, +SSL_verify_cb, +SSL_verify_client_post_handshake, +SSL_set_post_handshake_auth, +SSL_CTX_set_post_handshake_auth +\&\- set various SSL/TLS parameters for peer certificate verification +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx); +\& +\& void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); +\& void SSL_set_verify(SSL *ssl, int mode, SSL_verify_cb verify_callback); +\& SSL_get_ex_data_X509_STORE_CTX_idx(void); +\& +\& void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); +\& void SSL_set_verify_depth(SSL *ssl, int depth); +\& +\& int SSL_verify_client_post_handshake(SSL *ssl); +\& void SSL_CTX_set_post_handshake_auth(SSL_CTX *ctx, int val); +\& void SSL_set_post_handshake_auth(SSL *ssl, int val); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_verify()\fR sets the verification flags for \fBctx\fR to be \fBmode\fR and +specifies the \fBverify_callback\fR function to be used. If no callback function +shall be specified, the NULL pointer can be used for \fBverify_callback\fR. \fBctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_set_verify()\fR sets the verification flags for \fBssl\fR to be \fBmode\fR and +specifies the \fBverify_callback\fR function to be used. If no callback function +shall be specified, the NULL pointer can be used for \fBverify_callback\fR. In +this case last \fBverify_callback\fR set specifically for this \fBssl\fR remains. If +no special \fBcallback\fR was set before, the default callback for the underlying +\&\fBctx\fR is used, that was valid at the time \fBssl\fR was created with +\&\fBSSL_new\fR\|(3). Within the callback function, +\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR can be called to get the data index +of the current SSL object that is doing the verification. +.PP +In client mode \fBverify_callback\fR may also call the \fBSSL_set_retry_verify\fR\|(3) +function on the \fBSSL\fR object set in the \fIx509_store_ctx\fR ex data (see +\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3)) and return 1. +This would be typically done in case the certificate verification was not yet +able to succeed. +This makes the handshake suspend and return control to the calling application +with \fBSSL_ERROR_WANT_RETRY_VERIFY\fR. +The application can for instance fetch further certificates or cert status +information needed for the verification. +Calling \fBSSL_connect\fR\|(3) again resumes the connection attempt by retrying the +server certificate verification step. +This process may even be repeated if need be. +Note that the handshake may still be aborted if a subsequent invocation of the +callback (e.g., at a lower depth, or for a separate error condition) returns 0. +.PP +\&\fBSSL_CTX_set_verify_depth()\fR sets the maximum \fBdepth\fR for the certificate chain +verification that shall be allowed for \fBctx\fR. +.PP +\&\fBSSL_set_verify_depth()\fR sets the maximum \fBdepth\fR for the certificate chain +verification that shall be allowed for \fBssl\fR. +.PP +\&\fBSSL_CTX_set_post_handshake_auth()\fR and \fBSSL_set_post_handshake_auth()\fR enable the +Post\-Handshake Authentication extension to be added to the ClientHello such that +post\-handshake authentication can be requested by the server. If \fBval\fR is 0 +then the extension is not sent, otherwise it is. By default the extension is not +sent. A certificate callback will need to be set via +\&\fBSSL_CTX_set_client_cert_cb()\fR if no certificate is provided at initialization. +.PP +\&\fBSSL_verify_client_post_handshake()\fR causes a CertificateRequest message to be +sent by a server on the given \fBssl\fR connection. The SSL_VERIFY_PEER flag must +be set; the SSL_VERIFY_POST_HANDSHAKE flag is optional. +.SH NOTES +.IX Header "NOTES" +The verification of certificates can be controlled by a set of logically +or\*(Aqed \fBmode\fR flags: +.IP SSL_VERIFY_NONE 4 +.IX Item "SSL_VERIFY_NONE" +\&\fBServer mode:\fR the server will not send a client certificate request to the +client, so the client will not send a certificate. +.Sp +\&\fBClient mode:\fR if not using an anonymous cipher (by default disabled), the +server will send a certificate which will be checked. The result of the +certificate verification process can be checked after the TLS/SSL handshake +using the \fBSSL_get_verify_result\fR\|(3) function. +The handshake will be continued regardless of the verification result. +.IP SSL_VERIFY_PEER 4 +.IX Item "SSL_VERIFY_PEER" +\&\fBServer mode:\fR the server sends a client certificate request to the client. +The certificate returned (if any) is checked. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. +The behaviour can be controlled by the additional +SSL_VERIFY_FAIL_IF_NO_PEER_CERT, SSL_VERIFY_CLIENT_ONCE and +SSL_VERIFY_POST_HANDSHAKE flags. +.Sp +\&\fBClient mode:\fR the server certificate is verified. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. If no server certificate is sent, because an +anonymous cipher is used, SSL_VERIFY_PEER is ignored. +.IP SSL_VERIFY_FAIL_IF_NO_PEER_CERT 4 +.IX Item "SSL_VERIFY_FAIL_IF_NO_PEER_CERT" +\&\fBServer mode:\fR if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a "handshake failure" alert. +This flag must be used together with SSL_VERIFY_PEER. +.Sp +\&\fBClient mode:\fR ignored (see BUGS) +.IP SSL_VERIFY_CLIENT_ONCE 4 +.IX Item "SSL_VERIFY_CLIENT_ONCE" +\&\fBServer mode:\fR only request a client certificate once during the +connection. Do not ask for a client certificate again during +renegotiation or post\-authentication if a certificate was requested +during the initial handshake. This flag must be used together with +SSL_VERIFY_PEER. +.Sp +\&\fBClient mode:\fR ignored (see BUGS) +.IP SSL_VERIFY_POST_HANDSHAKE 4 +.IX Item "SSL_VERIFY_POST_HANDSHAKE" +\&\fBServer mode:\fR the server will not send a client certificate request +during the initial handshake, but will send the request via +\&\fBSSL_verify_client_post_handshake()\fR. This allows the SSL_CTX or SSL +to be configured for post\-handshake peer verification before the +handshake occurs. This flag must be used together with +SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre\-TLSv1.3 connections. +.Sp +\&\fBClient mode:\fR ignored (see BUGS) +.PP +If the \fBmode\fR is SSL_VERIFY_NONE none of the other flags may be set. +.PP +If verification flags are not modified explicitly by \f(CWSSL_CTX_set_verify()\fR +or \f(CWSSL_set_verify()\fR, the default value will be SSL_VERIFY_NONE. +.PP +The actual verification procedure is performed either using the built\-in +verification procedure or using another application provided verification +function set with +\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3). +The following descriptions apply in the case of the built\-in procedure. An +application provided procedure also has access to the verify depth information +and the \fBverify_callback()\fR function, but the way this information is used +may be different. +.PP +\&\fBSSL_CTX_set_verify_depth()\fR and \fBSSL_set_verify_depth()\fR set a limit on the +number of certificates between the end\-entity and trust\-anchor certificates. +Neither the +end\-entity nor the trust\-anchor certificates count against \fBdepth\fR. If the +certificate chain needed to reach a trusted issuer is longer than \fBdepth+2\fR, +X509_V_ERR_CERT_CHAIN_TOO_LONG will be issued. +The depth count is "level 0:peer certificate", "level 1: CA certificate", +"level 2: higher level CA certificate", and so on. Setting the maximum +depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end\-entity and 3 the +trust\-anchor). +The default depth limit is 100, +allowing for the peer certificate, at most 100 intermediate CA certificates and +a final trust anchor certificate. +.PP +The \fBverify_callback\fR function is used to control the behaviour when the +SSL_VERIFY_PEER flag is set. It must be supplied by the application and +receives two arguments: \fBpreverify_ok\fR indicates, whether the verification of +the certificate in question was passed (preverify_ok=1) or not +(preverify_ok=0). \fBx509_ctx\fR is a pointer to the complete context used +for the certificate chain verification. +.PP +The certificate chain is checked starting with the deepest nesting level +(the root CA certificate) and worked upward to the peer\*(Aqs certificate. +At each level signatures and issuer attributes are checked. Whenever +a verification error is found, the error number is stored in \fBx509_ctx\fR +and \fBverify_callback\fR is called with \fBpreverify_ok\fR=0. By applying +X509_CTX_store_* functions \fBverify_callback\fR can locate the certificate +in question and perform additional steps (see EXAMPLES). If no error is +found for a certificate, \fBverify_callback\fR is called with \fBpreverify_ok\fR=1 +before advancing to the next level. +.PP +The return value of \fBverify_callback\fR controls the strategy of the further +verification process. If \fBverify_callback\fR returns 0, the verification +process is immediately stopped with "verification failed" state. If +SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and +the TLS/SSL handshake is terminated. If \fBverify_callback\fR returns 1, +the verification process is continued. If \fBverify_callback\fR always returns +1, the TLS/SSL handshake will not be terminated with respect to verification +failures and the connection will be established. The calling process can +however retrieve the error code of the last verification error using +\&\fBSSL_get_verify_result\fR\|(3) or by maintaining its +own error storage managed by \fBverify_callback\fR. +.PP +If no \fBverify_callback\fR is specified, the default callback will be used. +Its return value is identical to \fBpreverify_ok\fR, so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if SSL_VERIFY_PEER is set. +.PP +After calling \fBSSL_set_post_handshake_auth()\fR, the client will need to add a +certificate or certificate callback to its configuration before it can +successfully authenticate. This must be called before \fBSSL_connect()\fR. +.PP +\&\fBSSL_verify_client_post_handshake()\fR requires that verify flags have been +previously set, and that a client sent the post\-handshake authentication +extension. When the client returns a certificate the verify callback will be +invoked. A write operation must take place for the Certificate Request to be +sent to the client, this can be done with \fBSSL_do_handshake()\fR or \fBSSL_write_ex()\fR. +Only one certificate request may be outstanding at any time. +.PP +When post\-handshake authentication occurs, a refreshed NewSessionTicket +message is sent to the client. +.PP +Post\-handshake authentication cannot be used with QUIC. +\&\fBSSL_set_post_handshake_auth()\fR has no effect if called on a QUIC SSL object. +.SH BUGS +.IX Header "BUGS" +In client mode, it is not checked whether the SSL_VERIFY_PEER flag +is set, but whether any flags other than SSL_VERIFY_NONE are set. This can +lead to unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as +required. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The SSL*_set_verify*() functions do not provide diagnostic information. +.PP +The \fBSSL_verify_client_post_handshake()\fR function returns 1 if the request +succeeded, and 0 if the request failed. The error stack can be examined +to determine the failure reason. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following code sequence realizes an example \fBverify_callback\fR function +that will always continue the TLS/SSL handshake regardless of verification +failure, if wished. The callback realizes a verification depth limit with +more informational output. +.PP +All verification errors are printed; information about the certificate chain +is printed on request. +The example is realized for a server that does allow but not require client +certificates. +.PP +The example makes use of the ex_data technique to store application data +into/retrieve application data from the SSL structure +(see \fBCRYPTO_get_ex_new_index\fR\|(3), +\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3)). +.PP +.Vb 7 +\& ... +\& typedef struct { +\& int verbose_mode; +\& int verify_depth; +\& int always_continue; +\& } mydata_t; +\& int mydata_index; +\& +\& ... +\& static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) +\& { +\& char buf[256]; +\& X509 *err_cert; +\& int err, depth; +\& SSL *ssl; +\& mydata_t *mydata; +\& +\& err_cert = X509_STORE_CTX_get_current_cert(ctx); +\& err = X509_STORE_CTX_get_error(ctx); +\& depth = X509_STORE_CTX_get_error_depth(ctx); +\& +\& /* +\& * Retrieve the pointer to the SSL of the connection currently treated +\& * and the application specific data stored into the SSL object. +\& */ +\& ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); +\& mydata = SSL_get_ex_data(ssl, mydata_index); +\& +\& X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); +\& +\& /* +\& * Catch a too long certificate chain. The depth limit set using +\& * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so +\& * that whenever the "depth>verify_depth" condition is met, we +\& * have violated the limit and want to log this error condition. +\& * We must do it here, because the CHAIN_TOO_LONG error would not +\& * be found explicitly; only errors introduced by cutting off the +\& * additional certificates would be logged. +\& */ +\& if (depth > mydata\->verify_depth) { +\& preverify_ok = 0; +\& err = X509_V_ERR_CERT_CHAIN_TOO_LONG; +\& X509_STORE_CTX_set_error(ctx, err); +\& } +\& if (!preverify_ok) { +\& printf("verify error:num=%d:%s:depth=%d:%s\en", err, +\& X509_verify_cert_error_string(err), depth, buf); +\& } else if (mydata\->verbose_mode) { +\& printf("depth=%d:%s\en", depth, buf); +\& } +\& +\& /* +\& * At this point, err contains the last verification error. We can use +\& * it for something special +\& */ +\& if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) { +\& X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256); +\& printf("issuer= %s\en", buf); +\& } +\& +\& if (mydata\->always_continue) +\& return 1; +\& else +\& return preverify_ok; +\& } +\& ... +\& +\& mydata_t mydata; +\& +\& ... +\& mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); +\& +\& ... +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_CLIENT_ONCE, +\& verify_callback); +\& +\& /* +\& * Let the verify_callback catch the verify_depth error so that we get +\& * an appropriate error in the logfile. +\& */ +\& SSL_CTX_set_verify_depth(verify_depth + 1); +\& +\& /* +\& * Set up the SSL specific data into "mydata" and store it into th SSL +\& * structure. +\& */ +\& mydata.verify_depth = verify_depth; ... +\& SSL_set_ex_data(ssl, mydata_index, &mydata); +\& +\& ... +\& SSL_accept(ssl); /* check of success left out for clarity */ +\& if (peer = SSL_get_peer_certificate(ssl)) { +\& if (SSL_get_verify_result(ssl) == X509_V_OK) { +\& /* The client sent a certificate which verified OK */ +\& } +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), +\&\fBSSL_CTX_get_verify_mode\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3), +\&\fBSSL_get_peer_certificate\fR\|(3), +\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3), +\&\fBSSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3), +\&\fBSSL_CTX_set_client_cert_cb\fR\|(3), +\&\fBCRYPTO_get_ex_new_index\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The SSL_VERIFY_POST_HANDSHAKE option, and the \fBSSL_verify_client_post_handshake()\fR +and \fBSSL_set_post_handshake_auth()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_use_certificate.3 b/static/netbsd/man3/SSL_CTX_use_certificate.3 new file mode 100644 index 00000000..6720002a --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_use_certificate.3 @@ -0,0 +1,264 @@ +.\" $NetBSD: SSL_CTX_use_certificate.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_use_certificate 3" +.TH SSL_CTX_use_certificate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, +SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, +SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, +SSL_use_certificate_chain_file, +SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, +SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, +SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, +SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, +SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, +SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key, +SSL_CTX_use_cert_and_key, SSL_use_cert_and_key +\&\- load certificate and key data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); +\& int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, const unsigned char *d); +\& int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); +\& int SSL_use_certificate(SSL *ssl, X509 *x); +\& int SSL_use_certificate_ASN1(SSL *ssl, const unsigned char *d, int len); +\& int SSL_use_certificate_file(SSL *ssl, const char *file, int type); +\& +\& int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); +\& int SSL_use_certificate_chain_file(SSL *ssl, const char *file); +\& +\& int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); +\& int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, const unsigned char *d, +\& long len); +\& int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); +\& int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); +\& int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, const unsigned char *d, long len); +\& int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); +\& int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); +\& int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, const unsigned char *d, long len); +\& int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); +\& int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); +\& int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, const unsigned char *d, long len); +\& int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); +\& +\& int SSL_CTX_check_private_key(const SSL_CTX *ctx); +\& int SSL_check_private_key(const SSL *ssl); +\& +\& int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); +\& int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions load the certificates and private keys into the SSL_CTX +or SSL object, respectively. +.PP +The SSL_CTX_* class of functions loads the certificates and keys into the +SSL_CTX object \fBctx\fR. The information is passed to SSL objects \fBssl\fR +created from \fBctx\fR with \fBSSL_new\fR\|(3) by copying, so that +changes applied to \fBctx\fR do not propagate to already existing SSL objects. +.PP +The SSL_* class of functions only loads certificates and keys into a +specific SSL object. The specific information is kept, when +\&\fBSSL_clear\fR\|(3) is called for this SSL object. +.PP +\&\fBSSL_CTX_use_certificate()\fR loads the certificate \fBx\fR into \fBctx\fR, +\&\fBSSL_use_certificate()\fR loads \fBx\fR into \fBssl\fR. The rest of the +certificates needed to form the complete certificate chain can be +specified using the +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3) +function. On success the reference counter of the \fBx\fR is incremented. +.PP +\&\fBSSL_CTX_use_certificate_ASN1()\fR loads the ASN1 encoded certificate from +the memory location \fBd\fR (with length \fBlen\fR) into \fBctx\fR, +\&\fBSSL_use_certificate_ASN1()\fR loads the ASN1 encoded certificate into \fBssl\fR. +.PP +\&\fBSSL_CTX_use_certificate_file()\fR loads the first certificate stored in \fBfile\fR +into \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +\&\fBSSL_use_certificate_file()\fR loads the certificate from \fBfile\fR into \fBssl\fR. +See the NOTES section on why \fBSSL_CTX_use_certificate_chain_file()\fR +should be preferred. +.PP +\&\fBSSL_CTX_use_certificate_chain_file()\fR loads a certificate chain from +\&\fBfile\fR into \fBctx\fR. The certificates must be in PEM format and must +be sorted starting with the subject\*(Aqs certificate (actual client or server +certificate), followed by intermediate CA certificates if applicable, and +ending at the highest level (root) CA. \fBSSL_use_certificate_chain_file()\fR is +similar except it loads the certificate chain into \fBssl\fR. +.PP +\&\fBSSL_CTX_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBctx\fR. \fBctx\fR \fBMUST NOT\fR be NULL. +\&\fBSSL_CTX_use_RSAPrivateKey()\fR adds the private key \fBrsa\fR of type RSA +to \fBctx\fR. \fBSSL_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBssl\fR; +\&\fBSSL_use_RSAPrivateKey()\fR adds \fBrsa\fR as private key of type RSA to \fBssl\fR. +If a certificate has already been set and the private key does not belong +to the certificate an error is returned. To change a [certificate/private\-key] +pair, the new certificate needs to be set first with \fBSSL_use_certificate()\fR or +\&\fBSSL_CTX_use_certificate()\fR before setting the private key with +\&\fBSSL_CTX_use_PrivateKey()\fR or \fBSSL_use_PrivateKey()\fR. +On success the reference counter of the \fBpkey\fR/\fBrsa\fR is incremented. +.PP +\&\fBSSL_CTX_use_cert_and_key()\fR and \fBSSL_use_cert_and_key()\fR assign the X.509 +certificate \fBx\fR, private key \fBkey\fR, and certificate \fBchain\fR onto the +corresponding \fBssl\fR or \fBctx\fR. The \fBpkey\fR argument must be the private +key of the X.509 certificate \fBx\fR. If the \fBoverride\fR argument is 0, then +\&\fBx\fR, \fBpkey\fR and \fBchain\fR are set only if all were not previously set. +If \fBoverride\fR is non\-0, then the certificate, private key and chain certs +are always set. If \fBpkey\fR is NULL, then the public key of \fBx\fR is used as +the private key. This is intended to be used with hardware (via the ENGINE +interface) that stores the private key securely, such that it cannot be +accessed by OpenSSL. The reference count of the public key is incremented +(twice if there is no private key); it is not copied nor duplicated. This +allows all private key validations checks to succeed without an actual +private key being assigned via \fBSSL_CTX_use_PrivateKey()\fR, etc. +.PP +\&\fBSSL_CTX_use_PrivateKey_ASN1()\fR adds the private key of type \fBpk\fR +stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR. +\&\fBSSL_CTX_use_RSAPrivateKey_ASN1()\fR adds the private key of type RSA +stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR. +\&\fBSSL_use_PrivateKey_ASN1()\fR and \fBSSL_use_RSAPrivateKey_ASN1()\fR add the private +key to \fBssl\fR. +.PP +\&\fBSSL_CTX_use_PrivateKey_file()\fR adds the first private key found in +\&\fBfile\fR to \fBctx\fR. The formatting \fBtype\fR of the private key must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +\&\fBSSL_CTX_use_RSAPrivateKey_file()\fR adds the first private RSA key found in +\&\fBfile\fR to \fBctx\fR. \fBSSL_use_PrivateKey_file()\fR adds the first private key found +in \fBfile\fR to \fBssl\fR; \fBSSL_use_RSAPrivateKey_file()\fR adds the first private +RSA key found to \fBssl\fR. \fBctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_CTX_check_private_key()\fR checks the consistency of a private key with +the corresponding certificate loaded into \fBctx\fR. If more than one +key/certificate pair (RSA/DSA) is installed, the last item installed will +be checked. If e.g. the last item was an RSA certificate or key, the RSA +key/certificate pair will be checked. \fBSSL_check_private_key()\fR performs +the same check for \fBssl\fR. If no key/certificate was explicitly added for +this \fBssl\fR, the last item added into \fBctx\fR will be checked. +.SH NOTES +.IX Header "NOTES" +The internal certificate store of OpenSSL can hold several private +key/certificate pairs at a time. The certificate used depends on the +cipher selected, see also \fBSSL_CTX_set_cipher_list\fR\|(3). +.PP +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as \fBDER\fR, binary encoding) can only contain +one certificate or private key, consequently +\&\fBSSL_CTX_use_certificate_chain_file()\fR is only applicable to PEM formatting. +Files of type SSL_FILETYPE_PEM can contain more than one item. +.PP +\&\fBSSL_CTX_use_certificate_chain_file()\fR adds the first certificate found +in the file to the certificate store. The other certificates are added +to the store of chain certificates using \fBSSL_CTX_add1_chain_cert\fR\|(3). +Note: versions of OpenSSL before 1.0.2 only had a single +certificate chain store for all certificate types, OpenSSL 1.0.2 and later +have a separate chain store for each type. \fBSSL_CTX_use_certificate_chain_file()\fR +should be used instead of the \fBSSL_CTX_use_certificate_file()\fR function in order +to allow the use of complete certificate chains even when no trusted CA +storage is used or when the CA issuing the certificate shall not be added to +the trusted CA storage. +.PP +If additional certificates are needed to complete the chain during the +TLS negotiation, CA certificates are additionally looked up in the +locations of trusted CA certificates, see +\&\fBSSL_CTX_load_verify_locations\fR\|(3). +.PP +The private keys loaded from file can be encrypted. In order to successfully +load encrypted keys, a function returning the passphrase must have been +supplied, see +\&\fBSSL_CTX_set_default_passwd_cb\fR\|(3). +(Certificate files might be encrypted as well from the technical point +of view, it however does not make sense as the data in the certificate +is considered public anyway.) +.PP +All of the functions to set a new certificate will replace any existing +certificate of the same type that has already been set. Similarly all of the +functions to set a new private key will replace any private key that has already +been set. Applications should call \fBSSL_CTX_check_private_key\fR\|(3) or +\&\fBSSL_check_private_key\fR\|(3) as appropriate after loading a new certificate and +private key to confirm that the certificate and key match. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3), +\&\fBSSL_CTX_set_default_passwd_cb\fR\|(3), +\&\fBSSL_CTX_set_cipher_list\fR\|(3), +\&\fBSSL_CTX_set_client_CA_list\fR\|(3), +\&\fBSSL_CTX_set_client_cert_cb\fR\|(3), +\&\fBSSL_CTX_add_extra_chain_cert\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_use_psk_identity_hint.3 b/static/netbsd/man3/SSL_CTX_use_psk_identity_hint.3 new file mode 100644 index 00000000..31c17d0a --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_use_psk_identity_hint.3 @@ -0,0 +1,206 @@ +.\" $NetBSD: SSL_CTX_use_psk_identity_hint.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_use_psk_identity_hint 3" +.TH SSL_CTX_use_psk_identity_hint 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_psk_server_cb_func, +SSL_psk_find_session_cb_func, +SSL_CTX_use_psk_identity_hint, +SSL_use_psk_identity_hint, +SSL_CTX_set_psk_server_callback, +SSL_set_psk_server_callback, +SSL_CTX_set_psk_find_session_callback, +SSL_set_psk_find_session_callback +\&\- set PSK identity hint to use +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl, +\& const unsigned char *identity, +\& size_t identity_len, +\& SSL_SESSION **sess); +\& +\& +\& void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx, +\& SSL_psk_find_session_cb_func cb); +\& void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb); +\& +\& typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl, +\& const char *identity, +\& unsigned char *psk, +\& unsigned int max_psk_len); +\& +\& int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); +\& int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); +\& +\& void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb); +\& void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A server application wishing to use TLSv1.3 PSKs should set a callback +using either \fBSSL_CTX_set_psk_find_session_callback()\fR or +\&\fBSSL_set_psk_find_session_callback()\fR as appropriate. +.PP +The callback function is given a pointer to the SSL connection in \fBssl\fR and +an identity in \fBidentity\fR of length \fBidentity_len\fR. The callback function +should identify an SSL_SESSION object that provides the PSK details and store it +in \fB*sess\fR. The SSL_SESSION object should, as a minimum, set the master key, +the ciphersuite and the protocol version. See +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3) for details. +.PP +It is also possible for the callback to succeed but not supply a PSK. In this +case no PSK will be used but the handshake will continue. To do this the +callback should return successfully and ensure that \fB*sess\fR is +NULL. +.PP +Identity hints are not relevant for TLSv1.3. A server application wishing to use +PSK ciphersuites for TLSv1.2 and below may call \fBSSL_CTX_use_psk_identity_hint()\fR +to set the given \fBNUL\fR\-terminated PSK identity hint \fBhint\fR for SSL context +object \fBctx\fR. \fBSSL_use_psk_identity_hint()\fR sets the given \fBNUL\fR\-terminated PSK +identity hint \fBhint\fR for the SSL connection object \fBssl\fR. If \fBhint\fR is +\&\fBNULL\fR the current hint from \fBctx\fR or \fBssl\fR is deleted. +.PP +In the case where PSK identity hint is \fBNULL\fR, the server does not send the +ServerKeyExchange message to the client. +.PP +A server application wishing to use PSKs for TLSv1.2 and below must provide a +callback function which is called when the server receives the +ClientKeyExchange message from the client. The purpose of the callback function +is to validate the received PSK identity and to fetch the pre\-shared key used +during the connection setup phase. The callback is set using the functions +\&\fBSSL_CTX_set_psk_server_callback()\fR or \fBSSL_set_psk_server_callback()\fR. The callback +function is given the connection in parameter \fBssl\fR, \fBNUL\fR\-terminated PSK +identity sent by the client in parameter \fBidentity\fR, and a buffer \fBpsk\fR of +length \fBmax_psk_len\fR bytes where the pre\-shared key is to be stored. +.PP +The callback for use in TLSv1.2 will also work in TLSv1.3 although it is +recommended to use \fBSSL_CTX_set_psk_find_session_callback()\fR +or \fBSSL_set_psk_find_session_callback()\fR for this purpose instead. If TLSv1.3 has +been negotiated then OpenSSL will first check to see if a callback has been set +via \fBSSL_CTX_set_psk_find_session_callback()\fR or \fBSSL_set_psk_find_session_callback()\fR +and it will use that in preference. If no such callback is present then it will +check to see if a callback has been set via \fBSSL_CTX_set_psk_server_callback()\fR or +\&\fBSSL_set_psk_server_callback()\fR and use that. In this case the handshake digest +will default to SHA\-256 for any returned PSK. TLSv1.3 early data exchanges are +possible in PSK connections only with the \fBSSL_psk_find_session_cb_func\fR +callback, and are not possible with the \fBSSL_psk_server_cb_func\fR callback. +.PP +A connection established via a TLSv1.3 PSK will appear as if session resumption +has occurred so that \fBSSL_session_reused\fR\|(3) will return true. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_use_psk_identity_hint()\fR and \fBSSL_use_psk_identity_hint()\fR return +1 on success, 0 otherwise. +.PP +Return values from the TLSv1.2 and below server callback are interpreted as +follows: +.IP 0 4 +PSK identity was not found. An "unknown_psk_identity" alert message +will be sent and the connection setup fails. +.IP >0 4 +.IX Item ">0" +PSK identity was found and the server callback has provided the PSK +successfully in parameter \fBpsk\fR. Return value is the length of +\&\fBpsk\fR in bytes. It is an error to return a value greater than +\&\fBmax_psk_len\fR. +.Sp +If the PSK identity was not found but the callback instructs the +protocol to continue anyway, the callback must provide some random +data to \fBpsk\fR and return the length of the random data, so the +connection will fail with decryption_error before it will be finished +completely. +.PP +The \fBSSL_psk_find_session_cb_func\fR callback should return 1 on success or 0 on +failure. In the event of failure the connection setup fails. +.SH NOTES +.IX Header "NOTES" +There are no known security issues with sharing the same PSK between TLSv1.2 (or +below) and TLSv1.3. However, the RFC has this note of caution: +.PP +"While there is no known way in which the same PSK might produce related output +in both versions, only limited analysis has been done. Implementations can +ensure safety from cross\-protocol related output by not reusing PSKs between +TLS 1.3 and TLS 1.2." +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3), +\&\fBSSL_set_psk_use_session_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_psk_find_session_callback()\fR and \fBSSL_set_psk_find_session_callback()\fR +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_CTX_use_serverinfo.3 b/static/netbsd/man3/SSL_CTX_use_serverinfo.3 new file mode 100644 index 00000000..d984d54e --- /dev/null +++ b/static/netbsd/man3/SSL_CTX_use_serverinfo.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: SSL_CTX_use_serverinfo.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_CTX_use_serverinfo 3" +.TH SSL_CTX_use_serverinfo 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_use_serverinfo_ex, +SSL_CTX_use_serverinfo, +SSL_CTX_use_serverinfo_file +\&\- use serverinfo extension +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_use_serverinfo_ex(SSL_CTX *ctx, unsigned int version, +\& const unsigned char *serverinfo, +\& size_t serverinfo_length); +\& +\& int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, +\& size_t serverinfo_length); +\& +\& int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions load "serverinfo" TLS extensions into the SSL_CTX. A +"serverinfo" extension is returned in response to an empty ClientHello +Extension. +.PP +\&\fBSSL_CTX_use_serverinfo_ex()\fR loads one or more serverinfo extensions from +a byte array into \fBctx\fR. The \fBversion\fR parameter specifies the format of the +byte array provided in \fB*serverinfo\fR which is of length \fBserverinfo_length\fR. +.PP +If \fBversion\fR is \fBSSL_SERVERINFOV2\fR then the extensions in the array must +consist of a 4\-byte context, a 2\-byte Extension Type, a 2\-byte length, and then +length bytes of extension_data. The context and type values have the same +meaning as for \fBSSL_CTX_add_custom_ext\fR\|(3). If serverinfo is being loaded for +extensions to be added to a Certificate message, then the extension will only +be added for the first certificate in the message (which is always the +end\-entity certificate). +.PP +If \fBversion\fR is \fBSSL_SERVERINFOV1\fR then the extensions in the array must +consist of a 2\-byte Extension Type, a 2\-byte length, and then length bytes of +extension_data. The type value has the same meaning as for +\&\fBSSL_CTX_add_custom_ext\fR\|(3). The following default context value will be used +in this case: +.PP +.Vb 2 +\& SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO +\& | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION +.Ve +.PP +\&\fBSSL_CTX_use_serverinfo()\fR does the same thing as \fBSSL_CTX_use_serverinfo_ex()\fR +except that there is no \fBversion\fR parameter so a default version of +SSL_SERVERINFOV1 is used instead. +.PP +\&\fBSSL_CTX_use_serverinfo_file()\fR loads one or more serverinfo extensions from +\&\fBfile\fR into \fBctx\fR. The extensions must be in PEM format. Each extension +must be in a format as described above for \fBSSL_CTX_use_serverinfo_ex()\fR. Each +PEM extension name must begin with the phrase "BEGIN SERVERINFOV2 FOR " for +SSL_SERVERINFOV2 data or "BEGIN SERVERINFO FOR " for SSL_SERVERINFOV1 data. +.PP +If more than one certificate (RSA/DSA) is installed using +\&\fBSSL_CTX_use_certificate()\fR, the serverinfo extension will be loaded into the +last certificate installed. If e.g. the last item was an RSA certificate, the +loaded serverinfo extension data will be loaded for that certificate. To +use the serverinfo extension for multiple certificates, +\&\fBSSL_CTX_use_serverinfo()\fR needs to be called multiple times, once \fBafter\fR +each time a certificate is loaded via a call to \fBSSL_CTX_use_certificate()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +On success, the functions return 1. +On failure, the functions return 0. Check out the error stack to find out +the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2013\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_free.3 b/static/netbsd/man3/SSL_SESSION_free.3 new file mode 100644 index 00000000..2366ff8f --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_free.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: SSL_SESSION_free.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_free 3" +.TH SSL_SESSION_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_new, +SSL_SESSION_dup, +SSL_SESSION_up_ref, +SSL_SESSION_free \- create, free and manage SSL_SESSION structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_SESSION *SSL_SESSION_new(void); +\& SSL_SESSION *SSL_SESSION_dup(const SSL_SESSION *src); +\& int SSL_SESSION_up_ref(SSL_SESSION *ses); +\& void SSL_SESSION_free(SSL_SESSION *session); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_new()\fR creates a new SSL_SESSION structure and returns a pointer to +it. +.PP +\&\fBSSL_SESSION_dup()\fR creates a new SSL_SESSION structure that is a copy of \fBsrc\fR. +The copy is not owned by any cache that \fBsrc\fR may have been in. +.PP +\&\fBSSL_SESSION_up_ref()\fR increments the reference count on the given SSL_SESSION +structure. +.PP +\&\fBSSL_SESSION_free()\fR decrements the reference count of \fBsession\fR and removes +the \fBSSL_SESSION\fR structure pointed to by \fBsession\fR and frees up the allocated +memory, if the reference count has reached 0. +If \fBsession\fR is NULL nothing is done. +.SH NOTES +.IX Header "NOTES" +SSL_SESSION objects are allocated, when a TLS/SSL handshake operation +is successfully completed. Depending on the settings, see +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +the SSL_SESSION objects are internally referenced by the SSL_CTX and +linked into its session cache. SSL objects may be using the SSL_SESSION object; +as a session may be reused, several SSL objects may be using one SSL_SESSION +object at the same time. It is therefore crucial to keep the reference +count (usage information) correct and not delete an SSL_SESSION object +that is still used, as this may lead to program failures due to +dangling pointers. These failures may also appear delayed, e.g. +when an SSL_SESSION object was completely freed as the reference count +incorrectly became 0, but it is still referenced in the internal +session cache and the cache list is processed during a +\&\fBSSL_CTX_flush_sessions\fR\|(3) operation. +.PP +\&\fBSSL_SESSION_free()\fR must only be called for SSL_SESSION objects, for +which the reference count was explicitly incremented (e.g. +by calling \fBSSL_get1_session()\fR, see \fBSSL_get_session\fR\|(3)) +or when the SSL_SESSION object was generated outside a TLS handshake +operation, e.g. by using \fBd2i_SSL_SESSION\fR\|(3). +It must not be called on other SSL_SESSION objects, as this would cause +incorrect reference counts and therefore program failures. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure +or NULL on error. +.PP +SSL_SESSION_dup returns a pointer to the new copy or NULL on error. +.PP +SSL_SESSION_up_ref returns 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_session\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3), +\&\fBd2i_SSL_SESSION\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_dup()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get0_cipher.3 b/static/netbsd/man3/SSL_SESSION_get0_cipher.3 new file mode 100644 index 00000000..d96ff982 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get0_cipher.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: SSL_SESSION_get0_cipher.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get0_cipher 3" +.TH SSL_SESSION_get0_cipher 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get0_cipher, +SSL_SESSION_set_cipher +\&\- set and retrieve the SSL cipher associated with a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSION *s); +\& int SSL_SESSION_set_cipher(SSL_SESSION *s, const SSL_CIPHER *cipher); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get0_cipher()\fR retrieves the cipher that was used by the +connection when the session was created, or NULL if it cannot be determined. +.PP +The value returned is a pointer to an object maintained within \fBs\fR and +should not be released. +.PP +\&\fBSSL_SESSION_set_cipher()\fR can be used to set the ciphersuite associated with the +SSL_SESSION \fBs\fR to \fBcipher\fR. For example, this could be used to set up a +session based PSK (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get0_cipher()\fR returns the SSL_CIPHER associated with the SSL_SESSION +or NULL if it cannot be determined. +.PP +\&\fBSSL_SESSION_set_cipher()\fR returns 1 on success or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBd2i_SSL_SESSION\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3), +\&\fBSSL_SESSION_get0_hostname\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3), +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_get0_cipher()\fR function was added in OpenSSL 1.1.0. +The \fBSSL_SESSION_set_cipher()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get0_hostname.3 b/static/netbsd/man3/SSL_SESSION_get0_hostname.3 new file mode 100644 index 00000000..74de3d7e --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get0_hostname.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: SSL_SESSION_get0_hostname.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get0_hostname 3" +.TH SSL_SESSION_get0_hostname 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get0_hostname, +SSL_SESSION_set1_hostname, +SSL_SESSION_get0_alpn_selected, +SSL_SESSION_set1_alpn_selected +\&\- get and set SNI and ALPN data associated with a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_SESSION_get0_hostname(const SSL_SESSION *s); +\& int SSL_SESSION_set1_hostname(SSL_SESSION *s, const char *hostname); +\& +\& void SSL_SESSION_get0_alpn_selected(const SSL_SESSION *s, +\& const unsigned char **alpn, +\& size_t *len); +\& int SSL_SESSION_set1_alpn_selected(SSL_SESSION *s, const unsigned char *alpn, +\& size_t len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get0_hostname()\fR retrieves the Server Name Indication (SNI) value +that was sent by the client when the session was created if the server +acknowledged the client\*(Aqs SNI extension by including an empty SNI extension +in response. Otherwise NULL is returned. +.PP +The value returned is a pointer to memory maintained within \fBs\fR and +should not be free\*(Aqd. +.PP +\&\fBSSL_SESSION_set1_hostname()\fR sets the SNI value for the hostname to a copy of +the string provided in hostname. +.PP +\&\fBSSL_SESSION_get0_alpn_selected()\fR retrieves the selected ALPN protocol for this +session and its associated length in bytes. The returned value of \fB*alpn\fR is a +pointer to memory maintained within \fBs\fR and should not be free\*(Aqd. +.PP +\&\fBSSL_SESSION_set1_alpn_selected()\fR sets the ALPN protocol for this session to the +value in \fBalpn\fR which should be of length \fBlen\fR bytes. A copy of the input +value is made, and the caller retains ownership of the memory pointed to by +\&\fBalpn\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get0_hostname()\fR returns the SNI string if available, or NULL if not. +.PP +\&\fBSSL_SESSION_set1_hostname()\fR returns 1 on success or 0 on error. +.PP +\&\fBSSL_SESSION_set1_alpn_selected()\fR returns 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBd2i_SSL_SESSION\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_set1_hostname()\fR, \fBSSL_SESSION_get0_alpn_selected()\fR and +\&\fBSSL_SESSION_set1_alpn_selected()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get0_id_context.3 b/static/netbsd/man3/SSL_SESSION_get0_id_context.3 new file mode 100644 index 00000000..166f0a84 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get0_id_context.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: SSL_SESSION_get0_id_context.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get0_id_context 3" +.TH SSL_SESSION_get0_id_context 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get0_id_context, +SSL_SESSION_set1_id_context +\&\- get and set the SSL ID context associated with a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, +\& unsigned int *len); +\& int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx, +\& unsigned int sid_ctx_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +See \fBSSL_CTX_set_session_id_context\fR\|(3) for further details on session ID +contexts. +.PP +\&\fBSSL_SESSION_get0_id_context()\fR returns the ID context associated with +the SSL/TLS session \fBs\fR. The length of the ID context is written to +\&\fB*len\fR if \fBlen\fR is not NULL. +.PP +The value returned is a pointer to an object maintained within \fBs\fR and +should not be released. +.PP +\&\fBSSL_SESSION_set1_id_context()\fR takes a copy of the provided ID context given in +\&\fBsid_ctx\fR and associates it with the session \fBs\fR. The length of the ID context +is given by \fBsid_ctx_len\fR which must not exceed SSL_MAX_SID_CTX_LENGTH bytes. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_set1_id_context()\fR returns 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_set_session_id_context\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_get0_id_context()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get0_peer.3 b/static/netbsd/man3/SSL_SESSION_get0_peer.3 new file mode 100644 index 00000000..3feff3b8 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get0_peer.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: SSL_SESSION_get0_peer.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get0_peer 3" +.TH SSL_SESSION_get0_peer 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get0_peer +\&\- get details about peer\*(Aqs certificate for a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get0_peer()\fR returns the peer certificate associated with the session +\&\fBs\fR or NULL if no peer certificate is available. The caller should not free the +returned value (unless \fBX509_up_ref\fR\|(3) has also been called). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get0_peer()\fR returns a pointer to the peer certificate or NULL if +no peer certificate is available. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get_compress_id.3 b/static/netbsd/man3/SSL_SESSION_get_compress_id.3 new file mode 100644 index 00000000..58781c21 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get_compress_id.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: SSL_SESSION_get_compress_id.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get_compress_id 3" +.TH SSL_SESSION_get_compress_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get_compress_id +\&\- get details about the compression associated with a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +If compression has been negotiated for an ssl session then +\&\fBSSL_SESSION_get_compress_id()\fR will return the id for the compression method or +0 otherwise. The only built\-in supported compression method is zlib which has an +id of 1. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get_compress_id()\fR returns the id of the compression method or 0 if +none. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get_ex_data.3 b/static/netbsd/man3/SSL_SESSION_get_ex_data.3 new file mode 100644 index 00000000..a16c5b2c --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get_ex_data.3 @@ -0,0 +1,183 @@ +.\" $NetBSD: SSL_SESSION_get_ex_data.3,v 1.4 2020/12/10 00:33:13 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get_ex_data 3" +.TH SSL_SESSION_get_ex_data 3 "2018-09-23" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_SESSION_set_ex_data, +SSL_SESSION_get_ex_data +\&\- get and set application specific data on a session +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); +\& void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_set_ex_data()\fR enables an application to store arbitrary application +specific data \fBdata\fR in an \s-1SSL_SESSION\s0 structure \fBss\fR. The index \fBidx\fR should +be a value previously returned from a call to \fBCRYPTO_get_ex_new_index\fR\|(3). +.PP +\&\fBSSL_SESSION_get_ex_data()\fR retrieves application specific data previously stored +in an \s-1SSL_SESSION\s0 structure \fBs\fR. The \fBidx\fR value should be the same as that +used when originally storing the data. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_set_ex_data()\fR returns 1 for success or 0 for failure. +.PP +\&\fBSSL_SESSION_get_ex_data()\fR returns the previously stored value or \s-1NULL\s0 on +failure. \s-1NULL\s0 may also be a valid value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBCRYPTO_get_ex_new_index\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get_ex_new_index.3 b/static/netbsd/man3/SSL_SESSION_get_ex_new_index.3 new file mode 100644 index 00000000..1221e5f3 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get_ex_new_index.3 @@ -0,0 +1,194 @@ +.\" $NetBSD: SSL_SESSION_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get_ex_new_index 3" +.TH SSL_SESSION_get_ex_new_index 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data \- internal application specific data functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); +\& +\& void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx); +\& +\& typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, +\& int idx, long argl, void *argp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.PP +\&\fISSL_SESSION_get_ex_new_index()\fR is used to register a new index for application +specific data. +.PP +\&\fISSL_SESSION_set_ex_data()\fR is used to store application data at \fBarg\fR for \fBidx\fR +into the \fBsession\fR object. +.PP +\&\fISSL_SESSION_get_ex_data()\fR is used to retrieve the information for \fBidx\fR from +\&\fBsession\fR. +.PP +A detailed description for the \fB*\f(BI_get_ex_new_index()\fB\fR functionality +can be found in \fIRSA_get_ex_new_index\fR\|(3). +The \fB*\f(BI_get_ex_data()\fB\fR and \fB*\f(BI_set_ex_data()\fB\fR functionality is described in +\&\fICRYPTO_set_ex_data\fR\|(3). +.SH "WARNINGS" +.IX Header "WARNINGS" +The application data is only maintained for sessions held in memory. The +application data is not included when dumping the session with +\&\fIi2d_SSL_SESSION()\fR (and all functions indirectly calling the dump functions +like \fIPEM_write_SSL_SESSION()\fR and \fIPEM_write_bio_SSL_SESSION()\fR) and can +therefore not be restored. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(3), +\&\fIRSA_get_ex_new_index\fR\|(3), +\&\fICRYPTO_set_ex_data\fR\|(3) diff --git a/static/netbsd/man3/SSL_SESSION_get_protocol_version.3 b/static/netbsd/man3/SSL_SESSION_get_protocol_version.3 new file mode 100644 index 00000000..204a3dba --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get_protocol_version.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: SSL_SESSION_get_protocol_version.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get_protocol_version 3" +.TH SSL_SESSION_get_protocol_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get_protocol_version, +SSL_SESSION_set_protocol_version +\&\- get and set the session protocol version +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_get_protocol_version(const SSL_SESSION *s); +\& int SSL_SESSION_set_protocol_version(SSL_SESSION *s, int version); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get_protocol_version()\fR returns the protocol version number used +by session \fBs\fR. +.PP +\&\fBSSL_SESSION_set_protocol_version()\fR sets the protocol version associated with the +SSL_SESSION object \fBs\fR to the value \fBversion\fR. This value should be a version +constant such as \fBTLS1_3_VERSION\fR etc. For example, this could be used to set +up a session based PSK (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get_protocol_version()\fR returns a number indicating the protocol +version used for the session; this number matches the constants \fIe.g.\fR +\&\fBTLS1_VERSION\fR, \fBTLS1_2_VERSION\fR or \fBTLS1_3_VERSION\fR. +.PP +Note that the \fBSSL_SESSION_get_protocol_version()\fR function +does \fBnot\fR perform a null check on the provided session \fBs\fR pointer. +.PP +\&\fBSSL_SESSION_set_protocol_version()\fR returns 1 on success or 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_get_protocol_version()\fR function was added in OpenSSL 1.1.0. +The \fBSSL_SESSION_set_protocol_version()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_get_time.3 b/static/netbsd/man3/SSL_SESSION_get_time.3 new file mode 100644 index 00000000..728a0326 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_get_time.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: SSL_SESSION_get_time.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_get_time 3" +.TH SSL_SESSION_get_time 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, +SSL_SESSION_set_timeout, SSL_SESSION_get_time_ex, SSL_SESSION_set_time_ex, +SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout +\&\- retrieve and manipulate session time and timeout settings +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_SESSION_get_timeout(const SSL_SESSION *s); +\& long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); +\& +\& long SSL_get_timeout(const SSL_SESSION *s); +\& long SSL_set_timeout(SSL_SESSION *s, long tm); +\& +\& time_t SSL_SESSION_get_time_ex(const SSL_SESSION *s); +\& time_t SSL_SESSION_set_time_ex(SSL_SESSION *s, time_t tm); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.4, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& long SSL_SESSION_get_time(const SSL_SESSION *s); +\& long SSL_SESSION_set_time(SSL_SESSION *s, long tm); +\& long SSL_get_time(const SSL_SESSION *s); +\& long SSL_set_time(SSL_SESSION *s, long tm); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get_time_ex()\fR returns the time at which the session \fBs\fR was +established. The time is given in seconds since the Epoch and therefore +compatible to the time delivered by the \fBtime()\fR call. +.PP +\&\fBSSL_SESSION_set_time_ex()\fR replaces the creation time of the session \fBs\fR with +the chosen value \fBtm\fR. +.PP +\&\fBSSL_SESSION_get_timeout()\fR returns the timeout value set for session \fBs\fR +in seconds. +.PP +\&\fBSSL_SESSION_set_timeout()\fR sets the timeout value for session \fBs\fR in seconds +to \fBtm\fR. +.PP +\&\fBSSL_SESSION_get_time()\fR and \fBSSL_SESSION_set_time()\fR functions use +the long datatype instead of time_t and are therefore deprecated due to not +being Y2038\-safe on 32 bit systems. Note that such systems still need +to be configured to use 64 bit time_t to be able to avoid overflow in system time. +.PP +The \fBSSL_get_time()\fR, \fBSSL_set_time()\fR, \fBSSL_get_timeout()\fR, and \fBSSL_set_timeout()\fR +functions are synonyms for the SSL_SESSION_*() counterparts. +.SH NOTES +.IX Header "NOTES" +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the +default timeout value at creation, respectively, as set by +\&\fBSSL_CTX_set_timeout\fR\|(3). +Using these functions it is possible to extend or shorten the lifetime +of the session. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get_time_ex()\fR and \fBSSL_SESSION_get_timeout()\fR return the currently +valid values. +.PP +\&\fBSSL_SESSION_set_time_ex()\fR returns time on success. +.PP +\&\fBSSL_SESSION_set_timeout()\fR returns 1 on success. +.PP +If any of the function is passed the NULL pointer for the session \fBs\fR, +0 is returned. +.SH BUGS +.IX Header "BUGS" +The data type long is typically 32 bits on many systems, hence the old +functions \fBSSL_SESSION_get_time()\fR and \fBSSL_SESSION_set_time()\fR are not always +Y2038 safe. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_timeout\fR\|(3), +\&\fBSSL_get_default_timeout\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBSSL_SESSION_get_time_ex()\fR and \fBSSL_SESSION_set_time_ex()\fR were +added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_has_ticket.3 b/static/netbsd/man3/SSL_SESSION_has_ticket.3 new file mode 100644 index 00000000..ae6ba1f9 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_has_ticket.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: SSL_SESSION_has_ticket.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_has_ticket 3" +.TH SSL_SESSION_has_ticket 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get0_ticket, +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint +\&\- get details about the ticket associated with a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_has_ticket(const SSL_SESSION *s); +\& unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s); +\& void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick, +\& size_t *len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_has_ticket()\fR returns 1 if there is a Session Ticket associated with +this session, and 0 otherwise. +.PP +SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds +associated with the session ticket. +.PP +SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a +session. The length of the ticket is written to \fB*len\fR. If \fBtick\fR is non +NULL then a pointer to the ticket is written to \fB*tick\fR. The pointer is only +valid while the connection is in use. The session (and hence the ticket pointer) +may also become invalid as a result of a call to \fBSSL_CTX_flush_sessions()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_has_ticket()\fR returns 1 if session ticket exists or 0 otherwise. +.PP +\&\fBSSL_SESSION_get_ticket_lifetime_hint()\fR returns the number of seconds. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBd2i_SSL_SESSION\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_has_ticket()\fR, \fBSSL_SESSION_get_ticket_lifetime_hint()\fR +and \fBSSL_SESSION_get0_ticket()\fR functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_is_resumable.3 b/static/netbsd/man3/SSL_SESSION_is_resumable.3 new file mode 100644 index 00000000..449f9e4a --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_is_resumable.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: SSL_SESSION_is_resumable.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_is_resumable 3" +.TH SSL_SESSION_is_resumable 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_is_resumable +\&\- determine whether an SSL_SESSION object can be used for resumption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_is_resumable(const SSL_SESSION *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_is_resumable()\fR determines whether an SSL_SESSION object can be used +to resume a session or not. Returns 1 if it can or 0 if not. Note that +attempting to resume with a non\-resumable session will result in a full +handshake. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_is_resumable()\fR returns 1 if the session is resumable or 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_get_session\fR\|(3), +\&\fBSSL_CTX_sess_set_new_cb\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_is_resumable()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_print.3 b/static/netbsd/man3/SSL_SESSION_print.3 new file mode 100644 index 00000000..96eaa796 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_print.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: SSL_SESSION_print.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_print 3" +.TH SSL_SESSION_print 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_print, +SSL_SESSION_print_fp, +SSL_SESSION_print_keylog +\&\- printf information about a session +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses); +\& int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses); +\& int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_print()\fR prints summary information about the session provided in +\&\fBses\fR to the BIO \fBfp\fR. +.PP +\&\fBSSL_SESSION_print_fp()\fR does the same as \fBSSL_SESSION_print()\fR except it prints it +to the FILE \fBfp\fR. +.PP +\&\fBSSL_SESSION_print_keylog()\fR prints session information to the provided BIO +in NSS keylog format. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_print()\fR, \fBSSL_SESSION_print_fp()\fR and SSL_SESSION_print_keylog return +1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_SESSION_set1_id.3 b/static/netbsd/man3/SSL_SESSION_set1_id.3 new file mode 100644 index 00000000..6efd8f64 --- /dev/null +++ b/static/netbsd/man3/SSL_SESSION_set1_id.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: SSL_SESSION_set1_id.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_SESSION_set1_id 3" +.TH SSL_SESSION_set1_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_SESSION_get_id, +SSL_SESSION_set1_id +\&\- get and set the SSL session ID +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s, +\& unsigned int *len); +\& int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, +\& unsigned int sid_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_SESSION_get_id()\fR returns a pointer to the internal session id value for the +session \fBs\fR. The length of the id in bytes is stored in \fB*len\fR. The length may +be 0. The caller should not free the returned pointer directly. +.PP +\&\fBSSL_SESSION_set1_id()\fR sets the session ID for the \fBssl\fR SSL/TLS session +to \fBsid\fR of length \fBsid_len\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_get_id()\fR returns a pointer to the session id value. +\&\fBSSL_SESSION_set1_id()\fR returns 1 for success and 0 for failure, for example +if the supplied session ID length exceeds \fBSSL_MAX_SSL_SESSION_ID_LENGTH\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_SESSION_set1_id()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_accept.3 b/static/netbsd/man3/SSL_accept.3 new file mode 100644 index 00000000..a892aefc --- /dev/null +++ b/static/netbsd/man3/SSL_accept.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: SSL_accept.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_accept 3" +.TH SSL_accept 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_accept \- wait for a TLS/SSL client to initiate a TLS/SSL handshake +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_accept(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_accept()\fR waits for a TLS/SSL client to initiate the TLS/SSL handshake. +The communication channel must already have been set and assigned to the +\&\fBssl\fR by setting an underlying \fBBIO\fR. +.SH NOTES +.IX Header "NOTES" +The behaviour of \fBSSL_accept()\fR depends on the underlying BIO. +.PP +If the underlying BIO is \fBblocking\fR, \fBSSL_accept()\fR will only return once the +handshake has been finished or an error occurred. +.PP +If the underlying BIO is \fBnonblocking\fR, \fBSSL_accept()\fR will also return +when the underlying BIO could not satisfy the needs of \fBSSL_accept()\fR +to continue the handshake, indicating the problem by the return value \-1. +In this case a call to \fBSSL_get_error()\fR with the +return value of \fBSSL_accept()\fR will yield \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of \fBSSL_accept()\fR. +The action depends on the underlying BIO. When using a nonblocking socket, +nothing is to be done, but \fBselect()\fR can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call \fBSSL_get_error()\fR with the +return value \fBret\fR to find out the reason. +.IP 1 4 +.IX Item "1" +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. +.IP <0 4 +.IX Item "<0" +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur if action is needed to continue the operation +for nonblocking BIOs. Call \fBSSL_get_error()\fR with the return value \fBret\fR +to find out the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7), +\&\fBSSL_set_connect_state\fR\|(3), +\&\fBSSL_do_handshake\fR\|(3), +\&\fBSSL_CTX_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_accept_stream.3 b/static/netbsd/man3/SSL_accept_stream.3 new file mode 100644 index 00000000..db1812ef --- /dev/null +++ b/static/netbsd/man3/SSL_accept_stream.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: SSL_accept_stream.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_accept_stream 3" +.TH SSL_accept_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_accept_stream, SSL_get_accept_stream_queue_len, SSL_ACCEPT_STREAM_NO_BLOCK \- +accept an incoming QUIC stream from a QUIC peer +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_ACCEPT_STREAM_NO_BLOCK +\& +\& SSL *SSL_accept_stream(SSL *ssl, uint64_t flags); +\& +\& size_t SSL_get_accept_stream_queue_len(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_accept_stream()\fR function attempts to dequeue an incoming stream from the +given QUIC connection SSL object and returns the newly allocated QUIC stream SSL +object. +.PP +If the queue of incoming streams is empty, this function returns NULL (in +nonblocking mode) or waits for an incoming stream (in blocking mode). This +function may still return NULL in blocking mode, for example if the underlying +connection is terminated. +.PP +The caller is responsible for managing the lifetime of the returned QUIC stream +SSL object; for more information, see \fBSSL_free\fR\|(3). +.PP +This function will block if the QUIC connection SSL object is configured in +blocking mode (see \fBSSL_set_blocking_mode\fR\|(3)), but this may be bypassed by +passing the flag \fBSSL_ACCEPT_STREAM_NO_BLOCK\fR in \fIflags\fR. If this flag is set, +this function never blocks. +.PP +Calling \fBSSL_accept_stream()\fR if there is no default stream already present +inhibits the future creation of a default stream. See \fBopenssl\-quic\fR\|(7). +.PP +\&\fBSSL_get_accept_stream_queue_len()\fR returns the number of incoming streams +currently waiting in the accept queue. +.PP +These functions can be used from multiple threads for the same QUIC connection. +.PP +Depending on whether default stream functionality is being used, it may be +necessary to explicitly configure the incoming stream policy before streams can +be accepted; see \fBSSL_set_incoming_stream_policy\fR\|(3). See also +"MODES OF OPERATION" in \fBopenssl\-quic\fR\|(7) for more information on default stream +functionality. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_accept_stream()\fR returns a newly allocated QUIC stream SSL object, or NULL if +no new incoming streams are available, or if the connection has been terminated, +or if called on an SSL object other than a QUIC connection SSL object. +\&\fBSSL_get_error\fR\|(3) can be used to obtain further information in this case. +.PP +\&\fBSSL_get_accept_stream_queue_len()\fR returns the number of incoming streams +currently waiting in the accept queue, or 0 if called on an SSL object other than +a QUIC connection SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"MODES OF OPERATION" in \fBopenssl\-quic\fR\|(7), \fBSSL_new_stream\fR\|(3), +\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_accept_stream()\fR and \fBSSL_get_accept_stream_queue_len()\fR were added in OpenSSL +3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_alert_type_string.3 b/static/netbsd/man3/SSL_alert_type_string.3 new file mode 100644 index 00000000..62ec891b --- /dev/null +++ b/static/netbsd/man3/SSL_alert_type_string.3 @@ -0,0 +1,267 @@ +.\" $NetBSD: SSL_alert_type_string.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_alert_type_string 3" +.TH SSL_alert_type_string 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long \- get textual description of alert information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_alert_type_string(int value); +\& const char *SSL_alert_type_string_long(int value); +\& +\& const char *SSL_alert_desc_string(int value); +\& const char *SSL_alert_desc_string_long(int value); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_alert_type_string()\fR returns a one letter string indicating the +type of the alert specified by \fBvalue\fR. +.PP +\&\fBSSL_alert_type_string_long()\fR returns a string indicating the type of the alert +specified by \fBvalue\fR. +.PP +\&\fBSSL_alert_desc_string()\fR returns a two letter string as a short form +describing the reason of the alert specified by \fBvalue\fR. +.PP +\&\fBSSL_alert_desc_string_long()\fR returns a string describing the reason +of the alert specified by \fBvalue\fR. +.SH NOTES +.IX Header "NOTES" +When one side of an SSL/TLS communication wants to inform the peer about +a special situation, it sends an alert. The alert is sent as a special message +and does not influence the normal data stream (unless its contents results +in the communication being canceled). +.PP +A warning alert is sent, when a non\-fatal error condition occurs. The +"close notify" alert is sent as a warning alert. Other examples for +non\-fatal errors are certificate errors ("certificate expired", +"unsupported certificate"), for which a warning alert may be sent. +(The sending party may however decide to send a fatal error.) The +receiving side may cancel the connection on reception of a warning +alert on it discretion. +.PP +Several alert messages must be sent as fatal alert messages as specified +by the TLS RFC. A fatal alert always leads to a connection abort. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following strings can occur for \fBSSL_alert_type_string()\fR or +\&\fBSSL_alert_type_string_long()\fR: +.IP """W""/""warning""" 4 +.IX Item """W""/""warning""" +.PD 0 +.IP """F""/""fatal""" 4 +.IX Item """F""/""fatal""" +.IP """U""/""unknown""" 4 +.IX Item """U""/""unknown""" +.PD +This indicates that no support is available for this alert type. +Probably \fBvalue\fR does not contain a correct alert message. +.PP +The following strings can occur for \fBSSL_alert_desc_string()\fR or +\&\fBSSL_alert_desc_string_long()\fR: +.IP """CN""/""close notify""" 4 +.IX Item """CN""/""close notify""" +The connection shall be closed. This is a warning alert. +.IP """UM""/""unexpected message""" 4 +.IX Item """UM""/""unexpected message""" +An inappropriate message was received. This alert is always fatal +and should never be observed in communication between proper +implementations. +.IP """BM""/""bad record mac""" 4 +.IX Item """BM""/""bad record mac""" +This alert is returned if a record is received with an incorrect +MAC. This message is always fatal. +.IP """DF""/""decompression failure""" 4 +.IX Item """DF""/""decompression failure""" +The decompression function received improper input (e.g. data +that would expand to excessive length). This message is always +fatal. +.IP """HF""/""handshake failure""" 4 +.IX Item """HF""/""handshake failure""" +Reception of a handshake_failure alert message indicates that the +sender was unable to negotiate an acceptable set of security +parameters given the options available. This is a fatal error. +.IP """NC""/""no certificate""" 4 +.IX Item """NC""/""no certificate""" +A client, that was asked to send a certificate, does not send a certificate +(SSLv3 only). +.IP """BC""/""bad certificate""" 4 +.IX Item """BC""/""bad certificate""" +A certificate was corrupt, contained signatures that did not +verify correctly, etc +.IP """UC""/""unsupported certificate""" 4 +.IX Item """UC""/""unsupported certificate""" +A certificate was of an unsupported type. +.IP """CR""/""certificate revoked""" 4 +.IX Item """CR""/""certificate revoked""" +A certificate was revoked by its signer. +.IP """CE""/""certificate expired""" 4 +.IX Item """CE""/""certificate expired""" +A certificate has expired or is not currently valid. +.IP """CU""/""certificate unknown""" 4 +.IX Item """CU""/""certificate unknown""" +Some other (unspecified) issue arose in processing the +certificate, rendering it unacceptable. +.IP """IP""/""illegal parameter""" 4 +.IX Item """IP""/""illegal parameter""" +A field in the handshake was out of range or inconsistent with +other fields. This is always fatal. +.IP """DC""/""decryption failed""" 4 +.IX Item """DC""/""decryption failed""" +A TLSCiphertext decrypted in an invalid way: either it wasn\*(Aqt an +even multiple of the block length or its padding values, when +checked, weren\*(Aqt correct. This message is always fatal. +.IP """RO""/""record overflow""" 4 +.IX Item """RO""/""record overflow""" +A TLSCiphertext record was received which had a length more than +2^14+2048 bytes, or a record decrypted to a TLSCompressed record +with more than 2^14+1024 bytes. This message is always fatal. +.IP """CA""/""unknown CA""" 4 +.IX Item """CA""/""unknown CA""" +A valid certificate chain or partial chain was received, but the +certificate was not accepted because the CA certificate could not +be located or couldn\*(Aqt be matched with a known, trusted CA. This +message is always fatal. +.IP """AD""/""access denied""" 4 +.IX Item """AD""/""access denied""" +A valid certificate was received, but when access control was +applied, the sender decided not to proceed with negotiation. +This message is always fatal. +.IP """DE""/""decode error""" 4 +.IX Item """DE""/""decode error""" +A message could not be decoded because some field was out of the +specified range or the length of the message was incorrect. This +message is always fatal. +.IP """CY""/""decrypt error""" 4 +.IX Item """CY""/""decrypt error""" +A handshake cryptographic operation failed, including being +unable to correctly verify a signature, decrypt a key exchange, +or validate a finished message. +.IP """ER""/""export restriction""" 4 +.IX Item """ER""/""export restriction""" +A negotiation not in compliance with export restrictions was +detected; for example, attempting to transfer a 1024 bit +ephemeral RSA key for the RSA_EXPORT handshake method. This +message is always fatal. +.IP """PV""/""protocol version""" 4 +.IX Item """PV""/""protocol version""" +The protocol version the client has attempted to negotiate is +recognized, but not supported. (For example, old protocol +versions might be avoided for security reasons). This message is +always fatal. +.IP """IS""/""insufficient security""" 4 +.IX Item """IS""/""insufficient security""" +Returned instead of handshake_failure when a negotiation has +failed specifically because the server requires ciphers more +secure than those supported by the client. This message is always +fatal. +.IP """IE""/""internal error""" 4 +.IX Item """IE""/""internal error""" +An internal error unrelated to the peer or the correctness of the +protocol makes it impossible to continue (such as a memory +allocation failure). This message is always fatal. +.IP """US""/""user canceled""" 4 +.IX Item """US""/""user canceled""" +This handshake is being canceled for some reason unrelated to a +protocol failure. If the user cancels an operation after the +handshake is complete, just closing the connection by sending a +close_notify is more appropriate. This alert should be followed +by a close_notify. This message is generally a warning. +.IP """NR""/""no renegotiation""" 4 +.IX Item """NR""/""no renegotiation""" +Sent by the client in response to a hello request or by the +server in response to a client hello after initial handshaking. +Either of these would normally lead to renegotiation; when that +is not appropriate, the recipient should respond with this alert; +at that point, the original requester can decide whether to +proceed with the connection. One case where this would be +appropriate would be where a server has spawned a process to +satisfy a request; the process might receive security parameters +(key length, authentication, etc.) at startup and it might be +difficult to communicate changes to these parameters after that +point. This message is always a warning. +.IP """UP""/""unknown PSK identity""" 4 +.IX Item """UP""/""unknown PSK identity""" +Sent by the server to indicate that it does not recognize a PSK +identity or an SRP identity. +.IP """UK""/""unknown""" 4 +.IX Item """UK""/""unknown""" +This indicates that no description is available for this alert type. +Probably \fBvalue\fR does not contain a correct alert message. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_info_callback\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_alloc_buffers.3 b/static/netbsd/man3/SSL_alloc_buffers.3 new file mode 100644 index 00000000..51b83647 --- /dev/null +++ b/static/netbsd/man3/SSL_alloc_buffers.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: SSL_alloc_buffers.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_alloc_buffers 3" +.TH SSL_alloc_buffers 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_free_buffers, SSL_alloc_buffers \- manage SSL structure buffers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_free_buffers(SSL *ssl); +\& int SSL_alloc_buffers(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_free_buffers()\fR frees the read and write buffers of the given \fBssl\fR. +\&\fBSSL_alloc_buffers()\fR allocates the read and write buffers of the given \fBssl\fR. +.PP +The \fBSSL_MODE_RELEASE_BUFFERS\fR mode releases read or write buffers whenever +the buffers have been drained. These functions allow applications to manually +control when buffers are freed and allocated. +.PP +After freeing the buffers, the buffers are automatically reallocated upon a +new read or write. The \fBSSL_alloc_buffers()\fR does not need to be called, but +can be used to make sure the buffers are preallocated. This can be used to +avoid allocation during data processing or with \fBCRYPTO_set_mem_functions()\fR +to control where and how buffers are allocated. +.PP +These functions are no\-ops when used with QUIC SSL objects. For QUIC, +\&\fBSSL_free_buffers()\fR always fails, and \fBSSL_alloc_buffers()\fR always succeeds. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP "0 (Failure)" 4 +.IX Item "0 (Failure)" +The \fBSSL_free_buffers()\fR function returns 0 when there is pending data to be +read or written. The \fBSSL_alloc_buffers()\fR function returns 0 when there is +an allocation failure. +.IP "1 (Success)" 4 +.IX Item "1 (Success)" +The \fBSSL_free_buffers()\fR function returns 1 if the buffers have been freed. This +value is also returned if the buffers had been freed before calling +\&\fBSSL_free_buffers()\fR. +The \fBSSL_alloc_buffers()\fR function returns 1 if the buffers have been allocated. +This value is also returned if the buffers had been allocated before calling +\&\fBSSL_alloc_buffers()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_free\fR\|(3), \fBSSL_clear\fR\|(3), +\&\fBSSL_new\fR\|(3), \fBSSL_CTX_set_mode\fR\|(3), +\&\fBCRYPTO_set_mem_functions\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_check_chain.3 b/static/netbsd/man3/SSL_check_chain.3 new file mode 100644 index 00000000..b7da9c85 --- /dev/null +++ b/static/netbsd/man3/SSL_check_chain.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: SSL_check_chain.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_check_chain 3" +.TH SSL_check_chain 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_check_chain \- check certificate chain suitability +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_check_chain()\fR checks whether certificate \fBx\fR, private key \fBpk\fR and +certificate chain \fBchain\fR is suitable for use with the current session +\&\fBs\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_check_chain()\fR returns a bitmap of flags indicating the validity of the +chain. +.PP +\&\fBCERT_PKEY_VALID\fR: the chain can be used with the current session. +If this flag is \fBnot\fR set then the certificate will never be used even +if the application tries to set it because it is inconsistent with the +peer preferences. +.PP +\&\fBCERT_PKEY_SIGN\fR: the EE key can be used for signing. +.PP +\&\fBCERT_PKEY_EE_SIGNATURE\fR: the signature algorithm of the EE certificate is +acceptable. +.PP +\&\fBCERT_PKEY_CA_SIGNATURE\fR: the signature algorithms of all CA certificates +are acceptable. +.PP +\&\fBCERT_PKEY_EE_PARAM\fR: the parameters of the end entity certificate are +acceptable (e.g. it is a supported curve). +.PP +\&\fBCERT_PKEY_CA_PARAM\fR: the parameters of all CA certificates are acceptable. +.PP +\&\fBCERT_PKEY_EXPLICIT_SIGN\fR: the end entity certificate algorithm +can be used explicitly for signing (i.e. it is mentioned in the signature +algorithms extension). +.PP +\&\fBCERT_PKEY_ISSUER_NAME\fR: the issuer name is acceptable. This is only +meaningful for client authentication. +.PP +\&\fBCERT_PKEY_CERT_TYPE\fR: the certificate type is acceptable. Only meaningful +for client authentication. +.PP +\&\fBCERT_PKEY_SUITEB\fR: chain is suitable for Suite B use. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_check_chain()\fR must be called in servers after a client hello message or in +clients after a certificate request message. It will typically be called +in the certificate callback. +.PP +An application wishing to support multiple certificate chains may call this +function on each chain in turn: starting with the one it considers the +most secure. It could then use the chain of the first set which returns +suitable flags. +.PP +As a minimum the flag \fBCERT_PKEY_VALID\fR must be set for a chain to be +usable. An application supporting multiple chains with different CA signature +algorithms may also wish to check \fBCERT_PKEY_CA_SIGNATURE\fR too. If no +chain is suitable a server should fall back to the most secure chain which +sets \fBCERT_PKEY_VALID\fR. +.PP +The validity of a chain is determined by checking if it matches a supported +signature algorithm, supported curves and in the case of client authentication +certificate types and issuer names. +.PP +Since the supported signature algorithms extension is only used in TLS 1.2, +TLS 1.3 and DTLS 1.2 the results for earlier versions of TLS and DTLS may not +be very useful. Applications may wish to specify a different "legacy" chain +for earlier versions of TLS or DTLS. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_set_cert_cb\fR\|(3), +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_clear.3 b/static/netbsd/man3/SSL_clear.3 new file mode 100644 index 00000000..4435f9ec --- /dev/null +++ b/static/netbsd/man3/SSL_clear.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: SSL_clear.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_clear 3" +.TH SSL_clear 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_clear \- reset SSL object to allow another connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_clear(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Reset \fBssl\fR to allow another connection. All settings (method, ciphers, +BIOs) are kept. +.SH NOTES +.IX Header "NOTES" +SSL_clear is used to prepare an SSL object for a new connection. While all +settings are kept, a side effect is the handling of the current SSL session. +If a session is still \fBopen\fR, it is considered bad and will be removed +from the session cache, as required by RFC2246. A session is considered open, +if \fBSSL_shutdown\fR\|(3) was not called for the connection +or at least \fBSSL_set_shutdown\fR\|(3) was used to +set the SSL_SENT_SHUTDOWN state. +.PP +If a session was closed cleanly, the session object will be kept and all +settings corresponding. This explicitly means, that e.g. the special method +used during the session will be kept for the next handshake. So if the +session was a TLSv1 session, an SSL client object will use a TLSv1 client +method for the next handshake and an SSL server object will use a TLSv1 +server method, even if TLS_*_methods were chosen on startup. This +will might lead to connection failures (see \fBSSL_new\fR\|(3)) +for a description of the method\*(Aqs properties. +.PP +This function is not supported on QUIC SSL objects and returns failure if called +on such an object. +.SH WARNINGS +.IX Header "WARNINGS" +\&\fBSSL_clear()\fR resets the SSL object to allow for another connection. The +reset operation however keeps several settings of the last sessions +(some of these settings were made automatically during the last +handshake). It only makes sense for a new connection with the exact +same peer that shares these settings, and may fail if that peer +changes its settings between connections. Use the sequence +\&\fBSSL_get_session\fR\|(3); +\&\fBSSL_new\fR\|(3); +\&\fBSSL_set_session\fR\|(3); +\&\fBSSL_free\fR\|(3) +instead to avoid such failures +(or simply \fBSSL_free\fR\|(3); \fBSSL_new\fR\|(3) +if session reuse is not desired). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The \fBSSL_clear()\fR operation could not be performed. Check the error stack to +find out the reason. +.IP 1 4 +.IX Item "1" +The \fBSSL_clear()\fR operation was successful. +.PP +\&\fBSSL_new\fR\|(3), \fBSSL_free\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), \fBssl\fR\|(7), +\&\fBSSL_CTX_set_client_cert_cb\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_connect.3 b/static/netbsd/man3/SSL_connect.3 new file mode 100644 index 00000000..4554e8f9 --- /dev/null +++ b/static/netbsd/man3/SSL_connect.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: SSL_connect.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_connect 3" +.TH SSL_connect 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_connect \- initiate the TLS/SSL handshake with an TLS/SSL server +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_connect(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_connect()\fR initiates the TLS/SSL handshake with a server. The communication +channel must already have been set and assigned to the \fBssl\fR by setting an +underlying \fBBIO\fR. \fBssl\fR \fBMUST NOT\fR be NULL. +.SH NOTES +.IX Header "NOTES" +The behaviour of \fBSSL_connect()\fR depends on the underlying BIO. +.PP +If the underlying BIO is \fBblocking\fR, \fBSSL_connect()\fR will only return once the +handshake has been finished or an error occurred. +.PP +If the underlying BIO is \fBnonblocking\fR, \fBSSL_connect()\fR will also return +when the underlying BIO could not satisfy the needs of \fBSSL_connect()\fR +to continue the handshake, indicating the problem by the return value \-1. +In this case a call to \fBSSL_get_error()\fR with the +return value of \fBSSL_connect()\fR will yield \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of \fBSSL_connect()\fR. +The action depends on the underlying BIO. When using a nonblocking socket, +nothing is to be done, but \fBselect()\fR can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. +.PP +Many systems implement Nagle\*(Aqs algorithm by default which means that it will +buffer outgoing TCP data if a TCP packet has already been sent for which no +corresponding ACK has been received yet from the peer. This can have performance +impacts after a successful TLSv1.3 handshake or a successful TLSv1.2 (or below) +resumption handshake, because the last peer to communicate in the handshake is +the client. If the client is also the first to send application data (as is +typical for many protocols) then this data could be buffered until an ACK has +been received for the final handshake message. +.PP +The \fBTCP_NODELAY\fR socket option is often available to disable Nagle\*(Aqs +algorithm. If an application opts to disable Nagle\*(Aqs algorithm consideration +should be given to turning it back on again later if appropriate. The helper +function \fBBIO_set_tcp_ndelay()\fR can be used to turn on or off the \fBTCP_NODELAY\fR +option. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call \fBSSL_get_error()\fR with the +return value \fBret\fR to find out the reason. +.IP 1 4 +.IX Item "1" +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. +.IP <0 4 +.IX Item "<0" +The TLS/SSL handshake was not successful, because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur if action is needed to continue the operation +for nonblocking BIOs. Call \fBSSL_get_error()\fR with the return value \fBret\fR +to find out the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_accept\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7), +\&\fBSSL_set_connect_state\fR\|(3), +\&\fBSSL_do_handshake\fR\|(3), +\&\fBSSL_CTX_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_do_handshake.3 b/static/netbsd/man3/SSL_do_handshake.3 new file mode 100644 index 00000000..1464914c --- /dev/null +++ b/static/netbsd/man3/SSL_do_handshake.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: SSL_do_handshake.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_do_handshake 3" +.TH SSL_do_handshake 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_do_handshake \- perform a TLS/SSL handshake +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_do_handshake(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_do_handshake()\fR will wait for an SSL/TLS handshake to take place. If the +connection is in client mode, the handshake will be started. The handshake +routines may have to be explicitly set in advance using either +\&\fBSSL_set_connect_state\fR\|(3) or +\&\fBSSL_set_accept_state\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The behaviour of \fBSSL_do_handshake()\fR depends on the underlying BIO. +.PP +If the underlying BIO is \fBblocking\fR, \fBSSL_do_handshake()\fR will only return +once the handshake has been finished or an error occurred. +.PP +If the underlying BIO is \fBnonblocking\fR, \fBSSL_do_handshake()\fR will also return +when the underlying BIO could not satisfy the needs of \fBSSL_do_handshake()\fR +to continue the handshake. In this case a call to \fBSSL_get_error()\fR with the +return value of \fBSSL_do_handshake()\fR will yield \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of \fBSSL_do_handshake()\fR. +The action depends on the underlying BIO. When using a nonblocking socket, +nothing is to be done, but \fBselect()\fR can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call \fBSSL_get_error()\fR with the +return value \fBret\fR to find out the reason. +.IP 1 4 +.IX Item "1" +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. +.IP <0 4 +.IX Item "<0" +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur if action is needed to continue the operation +for nonblocking BIOs. Call \fBSSL_get_error()\fR with the return value \fBret\fR +to find out the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3), +\&\fBSSL_accept\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7), +\&\fBSSL_set_connect_state\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_export_keying_material.3 b/static/netbsd/man3/SSL_export_keying_material.3 new file mode 100644 index 00000000..b59ce3f2 --- /dev/null +++ b/static/netbsd/man3/SSL_export_keying_material.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: SSL_export_keying_material.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_export_keying_material 3" +.TH SSL_export_keying_material 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_export_keying_material, +SSL_export_keying_material_early +\&\- obtain keying material for application use +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen, +\& const char *label, size_t llen, +\& const unsigned char *context, +\& size_t contextlen, int use_context); +\& +\& int SSL_export_keying_material_early(SSL *s, unsigned char *out, size_t olen, +\& const char *label, size_t llen, +\& const unsigned char *context, +\& size_t contextlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +During the creation of a TLS or DTLS connection shared keying material is +established between the two endpoints. The functions +\&\fBSSL_export_keying_material()\fR and \fBSSL_export_keying_material_early()\fR enable an +application to use some of this keying material for its own purposes in +accordance with RFC5705 (for TLSv1.2 and below) or RFC8446 (for TLSv1.3). +.PP +\&\fBSSL_export_keying_material()\fR derives keying material using +the \fIexporter_master_secret\fR established in the handshake. +.PP +\&\fBSSL_export_keying_material_early()\fR is only usable with TLSv1.3, and derives +keying material using the \fIearly_exporter_master_secret\fR (as defined in the +TLS 1.3 RFC). For the client, the \fIearly_exporter_master_secret\fR is only +available when the client attempts to send 0\-RTT data. For the server, it is +only available when the server accepts 0\-RTT data. +.PP +An application may need to securely establish the context within which this +keying material will be used. For example this may include identifiers for the +application session, application algorithms or parameters, or the lifetime of +the context. The context value is left to the application but must be the same +on both sides of the communication. +.PP +For a given SSL connection \fBs\fR, \fBolen\fR bytes of data will be written to +\&\fBout\fR. The application specific context should be supplied in the location +pointed to by \fBcontext\fR and should be \fBcontextlen\fR bytes long. Provision of +a context is optional. If the context should be omitted entirely then +\&\fBuse_context\fR should be set to 0. Otherwise it should be any other value. If +\&\fBuse_context\fR is 0 then the values of \fBcontext\fR and \fBcontextlen\fR are ignored. +Note that in TLSv1.2 and below a zero length context is treated differently from +no context at all, and will result in different keying material being returned. +In TLSv1.3 a zero length context is that same as no context at all and will +result in the same keying material being returned. +.PP +An application specific label should be provided in the location pointed to by +\&\fBlabel\fR and should be \fBllen\fR bytes long. Typically this will be a value from +the IANA Exporter Label Registry +(). +Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard +to be used without registration. TLSv1.3 imposes a maximum label length of +249 bytes. +.PP +Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and +above. Attempting to use it in SSLv3 will result in an error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_export_keying_material()\fR returns 0 or \-1 on failure or 1 on success. +.PP +\&\fBSSL_export_keying_material_early()\fR returns 0 on failure or 1 on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_export_keying_material_early()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_extension_supported.3 b/static/netbsd/man3/SSL_extension_supported.3 new file mode 100644 index 00000000..99f0eafe --- /dev/null +++ b/static/netbsd/man3/SSL_extension_supported.3 @@ -0,0 +1,336 @@ +.\" $NetBSD: SSL_extension_supported.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_extension_supported 3" +.TH SSL_extension_supported 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_extension_supported, +SSL_custom_ext_add_cb_ex, +SSL_custom_ext_free_cb_ex, +SSL_custom_ext_parse_cb_ex, +SSL_CTX_add_custom_ext, +SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, +custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb +\&\- custom TLS extension handling +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_custom_ext_add_cb_ex)(SSL *s, unsigned int ext_type, +\& unsigned int context, +\& const unsigned char **out, +\& size_t *outlen, X509 *x, +\& size_t chainidx, int *al, +\& void *add_arg); +\& +\& typedef void (*SSL_custom_ext_free_cb_ex)(SSL *s, unsigned int ext_type, +\& unsigned int context, +\& const unsigned char *out, +\& void *add_arg); +\& +\& typedef int (*SSL_custom_ext_parse_cb_ex)(SSL *s, unsigned int ext_type, +\& unsigned int context, +\& const unsigned char *in, +\& size_t inlen, X509 *x, +\& size_t chainidx, int *al, +\& void *parse_arg); +\& +\& int SSL_CTX_add_custom_ext(SSL_CTX *ctx, unsigned int ext_type, +\& unsigned int context, +\& SSL_custom_ext_add_cb_ex add_cb, +\& SSL_custom_ext_free_cb_ex free_cb, +\& void *add_arg, +\& SSL_custom_ext_parse_cb_ex parse_cb, +\& void *parse_arg); +\& +\& typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char **out, +\& size_t *outlen, int *al, +\& void *add_arg); +\& +\& typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char *out, +\& void *add_arg); +\& +\& typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, +\& const unsigned char *in, +\& size_t inlen, int *al, +\& void *parse_arg); +\& +\& int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, +\& custom_ext_add_cb add_cb, +\& custom_ext_free_cb free_cb, void *add_arg, +\& custom_ext_parse_cb parse_cb, +\& void *parse_arg); +\& +\& int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, +\& custom_ext_add_cb add_cb, +\& custom_ext_free_cb free_cb, void *add_arg, +\& custom_ext_parse_cb parse_cb, +\& void *parse_arg); +\& +\& int SSL_extension_supported(unsigned int ext_type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_add_custom_ext()\fR adds a custom extension for a TLS/DTLS client or server +for all supported protocol versions with extension type \fBext_type\fR and +callbacks \fBadd_cb\fR, \fBfree_cb\fR and \fBparse_cb\fR (see the +"EXTENSION CALLBACKS" section below). The \fBcontext\fR value determines +which messages and under what conditions the extension will be added/parsed (see +the "EXTENSION CONTEXTS" section below). +.PP +\&\fBSSL_CTX_add_client_custom_ext()\fR adds a custom extension for a TLS/DTLS client +with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and +\&\fBparse_cb\fR. This function is similar to \fBSSL_CTX_add_custom_ext()\fR except it only +applies to clients, uses the older style of callbacks, and implicitly sets the +\&\fBcontext\fR value to: +.PP +.Vb 2 +\& SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO +\& | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION +.Ve +.PP +\&\fBSSL_CTX_add_server_custom_ext()\fR adds a custom extension for a TLS/DTLS server +with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and +\&\fBparse_cb\fR. This function is similar to \fBSSL_CTX_add_custom_ext()\fR except it +only applies to servers, uses the older style of callbacks, and implicitly sets +the \fBcontext\fR value to the same as for \fBSSL_CTX_add_client_custom_ext()\fR above. +.PP +The \fBext_type\fR parameter corresponds to the \fBextension_type\fR field of +RFC5246 et al. It is \fBnot\fR a NID. In all cases the extension type must not be +handled by OpenSSL internally or an error occurs. +.PP +\&\fBSSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled +internally by OpenSSL and 0 otherwise. +.SH "EXTENSION CALLBACKS" +.IX Header "EXTENSION CALLBACKS" +The callback \fBadd_cb\fR is called to send custom extension data to be +included in various TLS messages. The \fBext_type\fR parameter is set to the +extension type which will be added and \fBadd_arg\fR to the value set when the +extension handler was added. When using the new style callbacks the \fBcontext\fR +parameter will indicate which message is currently being constructed e.g. for +the ClientHello it will be set to \fBSSL_EXT_CLIENT_HELLO\fR. +.PP +If the application wishes to include the extension \fBext_type\fR it should +set \fB*out\fR to the extension data, set \fB*outlen\fR to the length of the +extension data and return 1. +.PP +If the \fBadd_cb\fR does not wish to include the extension it must return 0. +.PP +If \fBadd_cb\fR returns \-1 a fatal handshake error occurs using the TLS +alert value specified in \fB*al\fR. +.PP +When constructing the ClientHello, if \fBadd_cb\fR is set to NULL a zero length +extension is added for \fBext_type\fR. For all other messages if \fBadd_cb\fR is set +to NULL then no extension is added. +.PP +When constructing a Certificate message the callback will be called for each +certificate in the message. The \fBx\fR parameter will indicate the +current certificate and the \fBchainidx\fR parameter will indicate the position +of the certificate in the message. The first certificate is always the end +entity certificate and has a \fBchainidx\fR value of 0. The certificates are in the +order that they were received in the Certificate message. +.PP +For all messages except the ServerHello and EncryptedExtensions every +registered \fBadd_cb\fR is always called to see if the application wishes to add an +extension (as long as all requirements of the specified \fBcontext\fR are met). +.PP +For the ServerHello and EncryptedExtension messages every registered \fBadd_cb\fR +is called once if and only if the requirements of the specified \fBcontext\fR are +met and the corresponding extension was received in the ClientHello. That is, if +no corresponding extension was received in the ClientHello then \fBadd_cb\fR will +not be called. +.PP +If an extension is added (that is \fBadd_cb\fR returns 1) \fBfree_cb\fR is called +(if it is set) with the value of \fBout\fR set by the add callback. It can be +used to free up any dynamic extension data set by \fBadd_cb\fR. Since \fBout\fR is +constant (to permit use of constant data in \fBadd_cb\fR) applications may need to +cast away const to free the data. +.PP +The callback \fBparse_cb\fR receives data for TLS extensions. The callback is only +called if the extension is present and relevant for the context (see +"EXTENSION CONTEXTS" below). +.PP +The extension data consists of \fBinlen\fR bytes in the buffer \fBin\fR for the +extension \fBext_type\fR. +.PP +If the message being parsed is a TLSv1.3 compatible Certificate message then +\&\fBparse_cb\fR will be called for each certificate contained within the message. +The \fBx\fR parameter will indicate the current certificate and the \fBchainidx\fR +parameter will indicate the position of the certificate in the message. The +first certificate is always the end entity certificate and has a \fBchainidx\fR +value of 0. +.PP +If the \fBparse_cb\fR considers the extension data acceptable it must return +1. If it returns 0 or a negative value a fatal handshake error occurs +using the TLS alert value specified in \fB*al\fR. +.PP +The buffer \fBin\fR is a temporary internal buffer which will not be valid after +the callback returns. +.SH "EXTENSION CONTEXTS" +.IX Header "EXTENSION CONTEXTS" +An extension context defines which messages and under which conditions an +extension should be added or expected. The context is built up by performing +a bitwise OR of multiple pre\-defined values together. The valid context values +are: +.IP SSL_EXT_TLS_ONLY 4 +.IX Item "SSL_EXT_TLS_ONLY" +The extension is only allowed in TLS +.IP SSL_EXT_DTLS_ONLY 4 +.IX Item "SSL_EXT_DTLS_ONLY" +The extension is only allowed in DTLS +.IP SSL_EXT_TLS_IMPLEMENTATION_ONLY 4 +.IX Item "SSL_EXT_TLS_IMPLEMENTATION_ONLY" +The extension is allowed in DTLS, but there is only a TLS implementation +available (so it is ignored in DTLS). +.IP SSL_EXT_SSL3_ALLOWED 4 +.IX Item "SSL_EXT_SSL3_ALLOWED" +Extensions are not typically defined for SSLv3. Setting this value will allow +the extension in SSLv3. Applications will not typically need to use this. +.IP SSL_EXT_TLS1_2_AND_BELOW_ONLY 4 +.IX Item "SSL_EXT_TLS1_2_AND_BELOW_ONLY" +The extension is only defined for TLSv1.2/DTLSv1.2 and below. Servers will +ignore this extension if it is present in the ClientHello and TLSv1.3 is +negotiated. +.IP SSL_EXT_TLS1_3_ONLY 4 +.IX Item "SSL_EXT_TLS1_3_ONLY" +The extension is only defined for TLS1.3 and above. Servers will ignore this +extension if it is present in the ClientHello and TLSv1.2 or below is +negotiated. +.IP SSL_EXT_IGNORE_ON_RESUMPTION 4 +.IX Item "SSL_EXT_IGNORE_ON_RESUMPTION" +The extension will be ignored during parsing if a previous session is being +successfully resumed. +.IP SSL_EXT_CLIENT_HELLO 4 +.IX Item "SSL_EXT_CLIENT_HELLO" +The extension may be present in the ClientHello message. +.IP SSL_EXT_TLS1_2_SERVER_HELLO 4 +.IX Item "SSL_EXT_TLS1_2_SERVER_HELLO" +The extension may be present in a TLSv1.2 or below compatible ServerHello +message. +.IP SSL_EXT_TLS1_3_SERVER_HELLO 4 +.IX Item "SSL_EXT_TLS1_3_SERVER_HELLO" +The extension may be present in a TLSv1.3 compatible ServerHello message. +.IP SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS 4 +.IX Item "SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS" +The extension may be present in an EncryptedExtensions message. +.IP SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST 4 +.IX Item "SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST" +The extension may be present in a HelloRetryRequest message. +.IP SSL_EXT_TLS1_3_CERTIFICATE 4 +.IX Item "SSL_EXT_TLS1_3_CERTIFICATE" +The extension may be present in a TLSv1.3 compatible Certificate message. +.IP SSL_EXT_TLS1_3_NEW_SESSION_TICKET 4 +.IX Item "SSL_EXT_TLS1_3_NEW_SESSION_TICKET" +The extension may be present in a TLSv1.3 compatible NewSessionTicket message. +.IP SSL_EXT_TLS1_3_CERTIFICATE_REQUEST 4 +.IX Item "SSL_EXT_TLS1_3_CERTIFICATE_REQUEST" +The extension may be present in a TLSv1.3 compatible CertificateRequest message. +.PP +The context must include at least one message value (otherwise the extension +will never be used). +.SH NOTES +.IX Header "NOTES" +The \fBadd_arg\fR and \fBparse_arg\fR parameters can be set to arbitrary values +which will be passed to the corresponding callbacks. They can, for example, +be used to store the extension data received in a convenient structure or +pass the extension data to be added or freed when adding extensions. +.PP +If the same custom extension type is received multiple times a fatal +\&\fBdecode_error\fR alert is sent and the handshake aborts. If a custom extension +is received in a ServerHello/EncryptedExtensions message which was not sent in +the ClientHello a fatal \fBunsupported_extension\fR alert is sent and the +handshake is aborted. The ServerHello/EncryptedExtensions \fBadd_cb\fR callback is +only called if the corresponding extension was received in the ClientHello. This +is compliant with the TLS specifications. This behaviour ensures that each +callback is called at most once and that an application can never send +unsolicited extensions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_add_custom_ext()\fR, \fBSSL_CTX_add_client_custom_ext()\fR and +\&\fBSSL_CTX_add_server_custom_ext()\fR return 1 for success and 0 for failure. A +failure can occur if an attempt is made to add the same \fBext_type\fR more than +once, if an attempt is made to use an extension type handled internally by +OpenSSL or if an internal error occurs (for example a memory allocation +failure). +.PP +\&\fBSSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled +internally by OpenSSL and 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_CTX_add_custom_ext()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_free.3 b/static/netbsd/man3/SSL_free.3 new file mode 100644 index 00000000..d174d084 --- /dev/null +++ b/static/netbsd/man3/SSL_free.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: SSL_free.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_free 3" +.TH SSL_free 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_free \- free an allocated SSL structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_free(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_free()\fR decrements the reference count of \fBssl\fR, and removes the SSL +structure pointed to by \fBssl\fR and frees up the allocated memory if the +reference count has reached 0. +If \fBssl\fR is NULL nothing is done. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_free()\fR also calls the \fBfree()\fRing procedures for indirectly affected items, if +applicable: the buffering BIO, the read and write BIOs, +cipher lists specially created for this \fBssl\fR, the \fBSSL_SESSION\fR. +Do not explicitly free these indirectly freed up items before or after +calling \fBSSL_free()\fR, as trying to free things twice may lead to program +failure. +.PP +The ssl session has reference counts from two users: the SSL object, for +which the reference count is removed by \fBSSL_free()\fR and the internal +session cache. If the session is considered bad, because +\&\fBSSL_shutdown\fR\|(3) was not called for the connection +and \fBSSL_set_shutdown\fR\|(3) was not used to set the +SSL_SENT_SHUTDOWN state, the session will also be removed +from the session cache as required by RFC2246. +.PP +When used to free a QUIC stream SSL object, the respective sending and receiving +parts of the stream are reset unless those parts have already been concluded +normally: +.IP \(bu 4 +If the stream has a sending part (in other words, if it is bidirectional or a +locally\-initiated unidirectional stream) and that part has not been concluded +via a call to \fBSSL_stream_conclude\fR\|(3) or \fBSSL_stream_reset\fR\|(3) on the QUIC +stream SSL object, a call to \fBSSL_free()\fR automatically resets the sending part of +the stream as though \fBSSL_stream_reset\fR\|(3) were called with a QUIC application +error code of 0. +.IP \(bu 4 +If the stream has a receiving part (in other words, if it is bidirectional or a +remotely\-initiated unidirectional stream), and the peer has not yet concluded +that part of the stream normally (such as via a call to +\&\fBSSL_stream_conclude\fR\|(3) on its own end), a call to \fBSSL_free()\fR automatically +requests the reset of the receiving part of the stream using a QUIC STOP_SENDING +frame with a QUIC application error code of 0. Note that as per the QUIC +protocol, this will automatically cause the peer to reset that part of the +stream in turn (which is its sending part). +.PP +A QUIC stream SSL object maintains a reference to a QUIC connection SSL object +internally, therefore a QUIC stream SSL object and its parent QUIC connection +SSL object can be freed in either order. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_free()\fR does not provide diagnostic information. +.PP +\&\fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3), +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get0_connection.3 b/static/netbsd/man3/SSL_get0_connection.3 new file mode 100644 index 00000000..0db5b0c7 --- /dev/null +++ b/static/netbsd/man3/SSL_get0_connection.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: SSL_get0_connection.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get0_connection 3" +.TH SSL_get0_connection 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get0_connection, SSL_is_connection \- get a QUIC connection SSL object from a +QUIC stream SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL *SSL_get0_connection(SSL *ssl); +\& int SSL_is_connection(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_get0_connection()\fR function, when called on a QUIC stream SSL object, +returns the QUIC connection SSL object which the QUIC stream SSL object belongs +to. +.PP +When called on a QUIC connection SSL object, it returns the same object. +.PP +When called on a non\-QUIC object, it returns the same object it was passed. +.PP +\&\fBSSL_is_connection()\fR returns 1 for QUIC connection SSL objects and for non\-QUIC +SSL objects, but returns 0 for QUIC stream SSL objects. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get0_connection()\fR returns the QUIC connection SSL object (for a QUIC stream +SSL object) and otherwise returns the same SSL object passed. It always returns +non\-NULL. +.PP +\&\fBSSL_is_connection()\fR returns 1 if the SSL object is not a QUIC stream SSL object +and 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_new\fR\|(3), \fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get0_group_name.3 b/static/netbsd/man3/SSL_get0_group_name.3 new file mode 100644 index 00000000..89459983 --- /dev/null +++ b/static/netbsd/man3/SSL_get0_group_name.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: SSL_get0_group_name.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get0_group_name 3" +.TH SSL_get0_group_name 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get0_group_name \- get name of the group that was used for the key +agreement of the current TLS session establishment +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_get0_group_name(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get0_group_name()\fR returns the name of the group that was used for +the key agreement of the current TLS session establishment. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If non\-NULL, \fBSSL_get0_group_name()\fR returns the name of the group that was used for +the key agreement of the current TLS session establishment. +If \fBSSL_get0_group_name()\fR returns NULL, an error occurred; possibly no TLS session +has been established. See also \fBSSL_get_negotiated_group\fR\|(3). +.PP +Note that the return value is valid only during the lifetime of the +SSL object \fIssl\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_get_negotiated_group\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get0_peer_rpk.3 b/static/netbsd/man3/SSL_get0_peer_rpk.3 new file mode 100644 index 00000000..489a3ced --- /dev/null +++ b/static/netbsd/man3/SSL_get0_peer_rpk.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: SSL_get0_peer_rpk.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get0_peer_rpk 3" +.TH SSL_get0_peer_rpk 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_add_expected_rpk, +SSL_get_negotiated_client_cert_type, +SSL_get_negotiated_server_cert_type, +SSL_get0_peer_rpk, +SSL_SESSION_get0_peer_rpk \- raw public key (RFC7250) support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_add_expected_rpk(SSL *s, EVP_PKEY *rpk); +\& int SSL_get_negotiated_client_cert_type(const SSL *s); +\& int SSL_get_negotiated_server_cert_type(const SSL *s); +\& EVP_PKEY *SSL_get0_peer_rpk(const SSL *s); +\& EVP_PKEY *SSL_SESSION_get0_peer_rpk(const SSL_SESSION *ss); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_add_expected_rpk()\fR adds a DANE TLSA record matching public key \fBrpk\fR +to SSL \fBs\fR\*(Aqs DANE validation policy. +.PP +\&\fBSSL_get_negotiated_client_cert_type()\fR returns the connection\*(Aqs negotiated +client certificate type. +.PP +\&\fBSSL_get_negotiated_server_cert_type()\fR returns the connection\*(Aqs negotiated +server certificate type. +.PP +\&\fBSSL_get0_peer_rpk()\fR returns the peer\*(Aqs raw public key from SSL \fBs\fR. +.PP +\&\fBSSL_SESSION_get0_peer_rpk()\fR returns the peer\*(Aqs raw public key from +SSL_SESSION \fBss\fR. +.SH NOTES +.IX Header "NOTES" +Raw public keys are used in place of certificates when the option is +negotiated. +\&\fBSSL_add_expected_rpk()\fR may be called multiple times to configure +multiple trusted keys, this makes it possible to allow for key rotation, +where a peer might be expected to offer an "old" or "new" key and the +endpoint must be able to accept either one. +.PP +When raw public keys are used, the certificate verify callback is called, and +may be used to inspect the public key via \fBX509_STORE_CTX_get0_rpk\fR\|(3). +Raw public keys have no subject, issuer, validity dates nor digital signature +to verify. They can, however, be matched verbatim or by their digest value, this +is done by specifying one or more TLSA records, see \fBSSL_CTX_dane_enable\fR\|(3). +.PP +The raw public key is typically taken from the certificate assigned to the +connection (e.g. via \fBSSL_use_certificate\fR\|(3)), but if a certificate is not +configured, then the public key will be extracted from the assigned +private key. +.PP +The \fBSSL_add_expected_rpk()\fR function is a wrapper around +\&\fBSSL_dane_tlsa_add\fR\|(3). +When DANE is enabled via \fBSSL_dane_enable\fR\|(3), the configured TLSA records +will be used to validate the peer\*(Aqs public key or certificate. +If DANE is not enabled, then no validation will occur. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_add_expected_rpk()\fR returns 1 on success and 0 on failure. +.PP +\&\fBSSL_get0_peer_rpk()\fR and \fBSSL_SESSION_get0_peer_rpk()\fR return the peer\*(Aqs raw +public key as an EVP_PKEY or NULL when the raw public key is not available. +.PP +\&\fBSSL_get_negotiated_client_cert_type()\fR and \fBSSL_get_negotiated_server_cert_type()\fR +return one of the following values: +.IP TLSEXT_cert_type_x509 4 +.IX Item "TLSEXT_cert_type_x509" +.PD 0 +.IP TLSEXT_cert_type_rpk 4 +.IX Item "TLSEXT_cert_type_rpk" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_dane_enable\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_dane_enable\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_set_verify\fR\|(3), +\&\fBSSL_use_certificate\fR\|(3), +\&\fBX509_STORE_CTX_get0_rpk\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. diff --git a/static/netbsd/man3/SSL_get0_peer_scts.3 b/static/netbsd/man3/SSL_get0_peer_scts.3 new file mode 100644 index 00000000..5ea02e9e --- /dev/null +++ b/static/netbsd/man3/SSL_get0_peer_scts.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: SSL_get0_peer_scts.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get0_peer_scts 3" +.TH SSL_get0_peer_scts 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get0_peer_scts \- get SCTs received +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get0_peer_scts()\fR returns the signed certificate timestamps (SCTs) that have +been received. If this is the first time that this function has been called for +a given \fBSSL\fR instance, it will examine the TLS extensions, OCSP response and +the peer\*(Aqs certificate for SCTs. Future calls will return the same SCTs. +.SH RESTRICTIONS +.IX Header "RESTRICTIONS" +If no Certificate Transparency validation callback has been set (using +\&\fBSSL_CTX_set_ct_validation_callback\fR or \fBSSL_set_ct_validation_callback\fR), +this function is not guaranteed to return all of the SCTs that the peer is +capable of sending. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get0_peer_scts()\fR returns a list of SCTs found, or NULL if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_ct_validation_callback\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get1_builtin_sigalgs.3 b/static/netbsd/man3/SSL_get1_builtin_sigalgs.3 new file mode 100644 index 00000000..d2c491bb --- /dev/null +++ b/static/netbsd/man3/SSL_get1_builtin_sigalgs.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: SSL_get1_builtin_sigalgs.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get1_builtin_sigalgs 3" +.TH SSL_get1_builtin_sigalgs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get1_builtin_sigalgs \- get list of built\-in signature algorithms +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& char *SSL_get1_builtin_sigalgs(OSSL_LIB_CTX *libctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Return the colon\-separated list of built\-in and available TLS signature +algorithms. +The string returned must be freed by the user using \fBOPENSSL_free\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The string may be empty (strlen==0) if none of the built\-in TLS signature +algorithms can be activated, e.g., if suitable providers are missing. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +NULL may be returned if no memory could be allocated. Otherwise, a +newly allocated string is always returned but it may have strlen == 0. +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_SSL_CTX.3 b/static/netbsd/man3/SSL_get_SSL_CTX.3 new file mode 100644 index 00000000..98a25fdb --- /dev/null +++ b/static/netbsd/man3/SSL_get_SSL_CTX.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: SSL_get_SSL_CTX.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_SSL_CTX 3" +.TH SSL_get_SSL_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_SSL_CTX \- get the SSL_CTX from which an SSL is created +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_SSL_CTX()\fR returns a pointer to the SSL_CTX object, from which +\&\fBssl\fR was created with \fBSSL_new\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The pointer to the SSL_CTX object is returned. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_all_async_fds.3 b/static/netbsd/man3/SSL_get_all_async_fds.3 new file mode 100644 index 00000000..24dc20c2 --- /dev/null +++ b/static/netbsd/man3/SSL_get_all_async_fds.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: SSL_get_all_async_fds.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_all_async_fds 3" +.TH SSL_get_all_async_fds 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_waiting_for_async, +SSL_get_all_async_fds, +SSL_get_changed_async_fds +\&\- manage asynchronous operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& int SSL_waiting_for_async(SSL *s); +\& int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds); +\& int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds, +\& OSSL_ASYNC_FD *delfd, size_t *numdelfds); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_waiting_for_async()\fR determines whether an SSL connection is currently +waiting for asynchronous operations to complete (see the \fBSSL_MODE_ASYNC\fR mode +in \fBSSL_CTX_set_mode\fR\|(3)). +.PP +\&\fBSSL_get_all_async_fds()\fR returns a list of file descriptor which can be used in a +call to \fBselect()\fR or \fBpoll()\fR to determine whether the current asynchronous +operation has completed or not. A completed operation will result in data +appearing as "read ready" on the file descriptor (no actual data should be read +from the file descriptor). This function should only be called if the \fBSSL\fR +object is currently waiting for asynchronous work to complete (i.e. +\&\fBSSL_ERROR_WANT_ASYNC\fR has been received \- see \fBSSL_get_error\fR\|(3)). Typically +the list will only contain one file descriptor. However, if multiple asynchronous +capable engines are in use then more than one is possible. The number of file +descriptors returned is stored in \fI*numfds\fR and the file descriptors themselves +are in \fI*fds\fR. The \fIfds\fR parameter may be NULL in which case no file +descriptors are returned but \fI*numfds\fR is still populated. It is the callers +responsibility to ensure sufficient memory is allocated at \fI*fds\fR so typically +this function is called twice (once with a NULL \fIfds\fR parameter and once +without). +.PP +\&\fBSSL_get_changed_async_fds()\fR returns a list of the asynchronous file descriptors +that have been added and a list that have been deleted since the last +\&\fBSSL_ERROR_WANT_ASYNC\fR was received (or since the \fBSSL\fR object was created if +no \fBSSL_ERROR_WANT_ASYNC\fR has been received). Similar to \fBSSL_get_all_async_fds()\fR +it is the callers responsibility to ensure that \fI*addfd\fR and \fI*delfd\fR have +sufficient memory allocated, although they may be NULL. The number of added fds +and the number of deleted fds are stored in \fI*numaddfds\fR and \fI*numdelfds\fR +respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_waiting_for_async()\fR will return 1 if the current SSL operation is waiting +for an async operation to complete and 0 otherwise. +.PP +\&\fBSSL_get_all_async_fds()\fR and \fBSSL_get_changed_async_fds()\fR return 1 on success or +0 on error. +.SH NOTES +.IX Header "NOTES" +On Windows platforms the \fI\fR header is dependent on some +of the types customarily made available by including \fI\fR. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore, +it is defined as an application developer\*(Aqs responsibility to include +\&\fI\fR prior to \fI\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_get_error\fR\|(3), \fBSSL_CTX_set_mode\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_waiting_for_async()\fR, \fBSSL_get_all_async_fds()\fR +and \fBSSL_get_changed_async_fds()\fR functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_certificate.3 b/static/netbsd/man3/SSL_get_certificate.3 new file mode 100644 index 00000000..c7db9793 --- /dev/null +++ b/static/netbsd/man3/SSL_get_certificate.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: SSL_get_certificate.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_certificate 3" +.TH SSL_get_certificate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_certificate, SSL_get_privatekey \- retrieve TLS/SSL certificate and +private key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *SSL_get_certificate(const SSL *s); +\& EVP_PKEY *SSL_get_privatekey(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_certificate()\fR returns a pointer to an \fBX509\fR object representing a +certificate used as the local peer\*(Aqs identity. +.PP +Multiple certificates can be configured; for example, a server might have both +RSA and ECDSA certificates. The certificate which is returned by +\&\fBSSL_get_certificate()\fR is determined as follows: +.IP \(bu 4 +If it is called before certificate selection has occurred, it returns the most +recently added certificate, or NULL if no certificate has been added. +.IP \(bu 4 +After certificate selection has occurred, it returns the certificate which was +selected during the handshake, or NULL if no certificate was selected (for +example, on a client where no client certificate is in use). +.PP +Certificate selection occurs during the handshake; therefore, the value returned +by \fBSSL_get_certificate()\fR during any callback made during the handshake process +will depend on whether that callback is made before or after certificate +selection occurs. +.PP +A specific use for \fBSSL_get_certificate()\fR is inside a callback set via a call to +\&\fBSSL_CTX_set_tlsext_status_cb\fR\|(3). This callback occurs after certificate +selection, where it can be used to examine a server\*(Aqs chosen certificate, for +example for the purpose of identifying a certificate\*(Aqs OCSP responder URL so +that an OCSP response can be obtained. +.PP +\&\fBSSL_get_privatekey()\fR returns a pointer to the \fBEVP_PKEY\fR object corresponding +to the certificate returned by \fBSSL_get_certificate()\fR, if any. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return pointers to their respective objects, or NULL if no such +object is available. Returned objects are owned by the SSL object and should not +be freed by users of these functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_tlsext_status_cb\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_ciphers.3 b/static/netbsd/man3/SSL_get_ciphers.3 new file mode 100644 index 00000000..631a434c --- /dev/null +++ b/static/netbsd/man3/SSL_get_ciphers.3 @@ -0,0 +1,177 @@ +.\" $NetBSD: SSL_get_ciphers.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_ciphers 3" +.TH SSL_get_ciphers 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get1_supported_ciphers, +SSL_get_client_ciphers, +SSL_get_ciphers, +SSL_CTX_get_ciphers, +SSL_bytes_to_cipher_list, +SSL_get_cipher_list, +SSL_get_shared_ciphers +\&\- get list of available SSL_CIPHERs +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); +\& STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx); +\& STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s); +\& STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl); +\& int SSL_bytes_to_cipher_list(SSL *s, const unsigned char *bytes, size_t len, +\& int isv2format, STACK_OF(SSL_CIPHER) **sk, +\& STACK_OF(SSL_CIPHER) **scsvs); +\& const char *SSL_get_cipher_list(const SSL *ssl, int priority); +\& char *SSL_get_shared_ciphers(const SSL *s, char *buf, int size); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBssl\fR, +sorted by preference. If \fBssl\fR is NULL or no ciphers are available, NULL +is returned. +.PP +\&\fBSSL_CTX_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBctx\fR. +.PP +\&\fBSSL_get1_supported_ciphers()\fR returns the stack of enabled SSL_CIPHERs for +\&\fBssl\fR as would be sent in a ClientHello (that is, sorted by preference). +The list depends on settings like the cipher list, the supported protocol +versions, the security level, and the enabled signature algorithms. +SRP and PSK ciphers are only enabled if the appropriate callbacks or settings +have been applied. +The list of ciphers that would be sent in a ClientHello can differ from +the list of ciphers that would be acceptable when acting as a server. +For example, additional ciphers may be usable by a server if there is +a gap in the list of supported protocols, and some ciphers may not be +usable by a server if there is not a suitable certificate configured. +If \fBssl\fR is NULL or no ciphers are available, NULL is returned. +.PP +\&\fBSSL_get_client_ciphers()\fR returns the stack of available SSL_CIPHERs matching the +list received from the client on \fBssl\fR. If \fBssl\fR is NULL, no ciphers are +available, or \fBssl\fR is not operating in server mode, NULL is returned. +.PP +\&\fBSSL_bytes_to_cipher_list()\fR treats the supplied \fBlen\fR octets in \fBbytes\fR +as a wire\-protocol cipher suite specification (in the three\-octet\-per\-cipher +SSLv2 wire format if \fBisv2format\fR is nonzero; otherwise the two\-octet +SSLv3/TLS wire format), and parses the cipher suites supported by the library +into the returned stacks of SSL_CIPHER objects sk and Signalling Cipher\-Suite +Values scsvs. Unsupported cipher suites are ignored. Returns 1 on success +and 0 on failure. +.PP +\&\fBSSL_get_cipher_list()\fR returns a pointer to the name of the SSL_CIPHER +listed for \fBssl\fR with \fBpriority\fR. If \fBssl\fR is NULL, no ciphers are +available, or there are less ciphers than \fBpriority\fR available, NULL +is returned. +.PP +\&\fBSSL_get_shared_ciphers()\fR creates a colon separated and NUL terminated list of +SSL_CIPHER names that are available in both the client and the server. \fBbuf\fR is +the buffer that should be populated with the list of names and \fBsize\fR is the +size of that buffer. A pointer to \fBbuf\fR is returned on success or NULL on +error. If the supplied buffer is not large enough to contain the complete list +of names then a truncated list of names will be returned. Note that just because +a ciphersuite is available (i.e. it is configured in the cipher list) and shared +by both the client and the server it does not mean that it is enabled (see the +description of \fBSSL_get1_supported_ciphers()\fR above). This function will return +available shared ciphersuites whether or not they are enabled. This is a server +side function only and must only be called after the completion of the initial +handshake. +The function sets an empty string when \fBssl\fR fails the handshake due to the +absence of shared ciphers. +.SH NOTES +.IX Header "NOTES" +The details of the ciphers obtained by \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR +\&\fBSSL_get1_supported_ciphers()\fR and \fBSSL_get_client_ciphers()\fR can be obtained using +the \fBSSL_CIPHER_get_name\fR\|(3) family of functions. +.PP +Call \fBSSL_get_cipher_list()\fR with \fBpriority\fR starting from 0 to obtain the +sorted list of available ciphers, until NULL is returned. +.PP +Note: \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR and \fBSSL_get_client_ciphers()\fR +return a pointer to an internal cipher stack, which will be freed later on when +the SSL or SSL_SESSION object is freed. Therefore, the calling code \fBMUST NOT\fR +free the return value itself. +.PP +The stack returned by \fBSSL_get1_supported_ciphers()\fR should be freed using +\&\fBsk_SSL_CIPHER_free()\fR. +.PP +The stacks returned by \fBSSL_bytes_to_cipher_list()\fR should be freed using +\&\fBsk_SSL_CIPHER_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +See DESCRIPTION +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_cipher_list\fR\|(3), +\&\fBSSL_CIPHER_get_name\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_client_CA_list.3 b/static/netbsd/man3/SSL_get_client_CA_list.3 new file mode 100644 index 00000000..63612ae2 --- /dev/null +++ b/static/netbsd/man3/SSL_get_client_CA_list.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: SSL_get_client_CA_list.3,v 1.18 2018/09/23 13:33:07 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_get_client_CA_list 3" +.TH SSL_get_client_CA_list 3 "2018-09-17" "1.1.1" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_get_client_CA_list, SSL_CTX_get_client_CA_list \- get list of client CAs +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); +\& STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_CTX_get_client_CA_list()\fR returns the list of client CAs explicitly set for +\&\fBctx\fR using \fISSL_CTX_set_client_CA_list\fR\|(3). +.PP +\&\fISSL_get_client_CA_list()\fR returns the list of client CAs explicitly +set for \fBssl\fR using \fISSL_set_client_CA_list()\fR or \fBssl\fR's \s-1SSL_CTX\s0 object with +\&\fISSL_CTX_set_client_CA_list\fR\|(3), when in +server mode. In client mode, SSL_get_client_CA_list returns the list of +client CAs sent from the server, if any. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fISSL_CTX_set_client_CA_list()\fR and \fISSL_set_client_CA_list()\fR do not return +diagnostic information. +.PP +\&\fISSL_CTX_add_client_CA()\fR and \fISSL_add_client_CA()\fR have the following return +values: +.IP "\s-1STACK_OF\s0(X509_NAMES)" 4 +.IX Item "STACK_OF(X509_NAMES)" +List of \s-1CA\s0 names explicitly set (for \fBctx\fR or in server mode) or send +by the server (client mode). +.IP "\s-1NULL\s0" 4 +.IX Item "NULL" +No client \s-1CA\s0 list was explicitly set (for \fBctx\fR or in server mode) or +the server did not send a list of CAs (client mode). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(7), +\&\fISSL_CTX_set_client_CA_list\fR\|(3), +\&\fISSL_CTX_set_client_cert_cb\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_client_random.3 b/static/netbsd/man3/SSL_get_client_random.3 new file mode 100644 index 00000000..012b6e20 --- /dev/null +++ b/static/netbsd/man3/SSL_get_client_random.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: SSL_get_client_random.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_client_random 3" +.TH SSL_get_client_random 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_client_random, +SSL_get_server_random, +SSL_SESSION_get_master_key, +SSL_SESSION_set1_master_key +\&\- get internal TLS/SSL random values and get/set master key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen); +\& size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen); +\& size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, +\& unsigned char *out, size_t outlen); +\& int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in, +\& size_t len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_client_random()\fR extracts the random value sent from the client +to the server during the initial SSL/TLS handshake. It copies as many +bytes as it can of this value into the buffer provided in \fBout\fR, +which must have at least \fBoutlen\fR bytes available. It returns the +total number of bytes that were actually copied. If \fBoutlen\fR is +zero, \fBSSL_get_client_random()\fR copies nothing, and returns the +total size of the client_random value. +.PP +\&\fBSSL_get_server_random()\fR behaves the same, but extracts the random value +sent from the server to the client during the initial SSL/TLS handshake. +.PP +\&\fBSSL_SESSION_get_master_key()\fR behaves the same, but extracts the master +secret used to guarantee the security of the SSL/TLS session. This one +can be dangerous if misused; see NOTES below. +.PP +\&\fBSSL_SESSION_set1_master_key()\fR sets the master key value associated with the +SSL_SESSION \fBsess\fR. For example, this could be used to set up a session based +PSK (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). The master key of length +\&\fBlen\fR should be provided at \fBin\fR. The supplied master key is copied by the +function, so the caller is responsible for freeing and cleaning any memory +associated with \fBin\fR. The caller must ensure that the length of the key is +suitable for the ciphersuite associated with the SSL_SESSION. +.SH NOTES +.IX Header "NOTES" +You probably shouldn\*(Aqt use these functions. +.PP +These functions expose internal values from the TLS handshake, for +use in low\-level protocols. You probably should not use them, unless +you are implementing something that needs access to the internal protocol +details. +.PP +Despite the names of \fBSSL_get_client_random()\fR and \fBSSL_get_server_random()\fR, they +ARE NOT random number generators. Instead, they return the mostly\-random values that +were already generated and used in the TLS protocol. Using them +in place of \fBRAND_bytes()\fR would be grossly foolish. +.PP +The security of your TLS session depends on keeping the master key secret: +do not expose it, or any information about it, to anybody. +If you need to calculate another secret value that depends on the master +secret, you should probably use \fBSSL_export_keying_material()\fR instead, and +forget that you ever saw these functions. +.PP +In current versions of the TLS protocols, the length of client_random +(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for +other outlen arguments to the SSL_get_*\fB_random()\fR functions is provided +in case of the unlikely event that a future version or variant of TLS +uses some other length there. +.PP +Finally, though the "client_random" and "server_random" values are called +"random", many TLS implementations will generate four bytes of those +values based on their view of the current time. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_SESSION_set1_master_key()\fR returns 1 on success or 0 on failure. +.PP +For the other functions, if \fBoutlen\fR is greater than 0 then these functions +return the number of bytes actually copied, which will be less than or equal to +\&\fBoutlen\fR. If \fBoutlen\fR is 0 then these functions return the maximum number +of bytes they would copy \-\- that is, the length of the underlying field. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBRAND_bytes\fR\|(3), +\&\fBSSL_export_keying_material\fR\|(3), +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_conn_close_info.3 b/static/netbsd/man3/SSL_get_conn_close_info.3 new file mode 100644 index 00000000..5acd5201 --- /dev/null +++ b/static/netbsd/man3/SSL_get_conn_close_info.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: SSL_get_conn_close_info.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_conn_close_info 3" +.TH SSL_get_conn_close_info 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL, +SSL_CONN_CLOSE_FLAG_TRANSPORT, +OSSL_QUIC_ERR_NO_ERROR, +OSSL_QUIC_ERR_INTERNAL_ERROR, +OSSL_QUIC_ERR_CONNECTION_REFUSED, +OSSL_QUIC_ERR_FLOW_CONTROL_ERROR, +OSSL_QUIC_ERR_STREAM_LIMIT_ERROR, +OSSL_QUIC_ERR_STREAM_STATE_ERROR, +OSSL_QUIC_ERR_FINAL_SIZE_ERROR, +OSSL_QUIC_ERR_FRAME_ENCODING_ERROR, +OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR, +OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR, +OSSL_QUIC_ERR_PROTOCOL_VIOLATION, +OSSL_QUIC_ERR_INVALID_TOKEN, +OSSL_QUIC_ERR_APPLICATION_ERROR, +OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED, +OSSL_QUIC_ERR_KEY_UPDATE_ERROR, +OSSL_QUIC_ERR_AEAD_LIMIT_REACHED, +OSSL_QUIC_ERR_NO_VIABLE_PATH, +OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN, +OSSL_QUIC_ERR_CRYPTO_ERR_END, +OSSL_QUIC_ERR_CRYPTO_ERR, +OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT +\&\- get information about why a QUIC connection was closed +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_CONN_CLOSE_FLAG_LOCAL +\& #define SSL_CONN_CLOSE_FLAG_TRANSPORT +\& +\& typedef struct ssl_conn_close_info_st { +\& uint64_t error_code, frame_type; +\& char *reason; +\& size_t reason_len; +\& uint32_t flags; +\& } SSL_CONN_CLOSE_INFO; +\& +\& int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info, +\& size_t info_len); +\& +\& #define OSSL_QUIC_ERR_NO_ERROR 0x00 +\& #define OSSL_QUIC_ERR_INTERNAL_ERROR 0x01 +\& #define OSSL_QUIC_ERR_CONNECTION_REFUSED 0x02 +\& #define OSSL_QUIC_ERR_FLOW_CONTROL_ERROR 0x03 +\& #define OSSL_QUIC_ERR_STREAM_LIMIT_ERROR 0x04 +\& #define OSSL_QUIC_ERR_STREAM_STATE_ERROR 0x05 +\& #define OSSL_QUIC_ERR_FINAL_SIZE_ERROR 0x06 +\& #define OSSL_QUIC_ERR_FRAME_ENCODING_ERROR 0x07 +\& #define OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08 +\& #define OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09 +\& #define OSSL_QUIC_ERR_PROTOCOL_VIOLATION 0x0A +\& #define OSSL_QUIC_ERR_INVALID_TOKEN 0x0B +\& #define OSSL_QUIC_ERR_APPLICATION_ERROR 0x0C +\& #define OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED 0x0D +\& #define OSSL_QUIC_ERR_KEY_UPDATE_ERROR 0x0E +\& #define OSSL_QUIC_ERR_AEAD_LIMIT_REACHED 0x0F +\& #define OSSL_QUIC_ERR_NO_VIABLE_PATH 0x10 +\& +\& /* Inclusive range for handshake\-specific errors. */ +\& #define OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN 0x0100 +\& #define OSSL_QUIC_ERR_CRYPTO_ERR_END 0x01FF +\& +\& #define OSSL_QUIC_ERR_CRYPTO_ERR(X) +\& +\& #define OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_get_conn_close_info()\fR function provides information about why and how a +QUIC connection was closed. +.PP +Connection closure information is written to \fI*info\fR, which must be non\-NULL. +\&\fIinfo_len\fR must be set to \f(CWsizeof(*info)\fR. +.PP +The following fields are set: +.IP \fIerror_code\fR 4 +.IX Item "error_code" +This is a 62\-bit QUIC error code. It is either a 62\-bit application error code +(if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR not set in \fIflags\fR) or a 62\-bit standard +QUIC transport error code (if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set in +\&\fIflags\fR). +.IP \fIframe_type\fR 4 +.IX Item "frame_type" +If \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set, this may be set to a QUIC frame type +number which caused the connection to be closed. It may also be set to 0 if no +frame type was specified as causing the connection to be closed. If +\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is not set, this is set to 0. +.IP \fIreason\fR 4 +.IX Item "reason" +If non\-NULL, this is intended to be a UTF\-8 textual string briefly describing +the reason for connection closure. The length of the reason string in bytes is +given in \fIreason_len\fR. While, if non\-NULL, OpenSSL guarantees that this string +will be zero terminated, consider that this buffer may originate from the +(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use +of \fIreason_len\fR is recommended. +.Sp +While it is intended as per the QUIC protocol that this be a UTF\-8 string, there +is no guarantee that this is the case for strings received from the peer. +.IP \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR 4 +.IX Item "SSL_CONN_CLOSE_FLAG_LOCAL" +If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR set, connection closure was locally +triggered. This could be due to an application request (e.g. if +\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is unset), or (if +\&\fISSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set) due to logic internal to the QUIC +implementation (for example, if the peer engages in a protocol violation, or an +idle timeout occurs). +.Sp +If unset, connection closure was remotely triggered. +.IP \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR 4 +.IX Item "SSL_CONN_CLOSE_FLAG_TRANSPORT" +If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR set, connection closure was +triggered for QUIC protocol reasons. Otherwise, connection closure was triggered +by the local or remote application. +.PP +The \fBOSSL_QUIC_ERR\fR macro definitions provide the QUIC transport error codes as +defined by RFC 9000. The \fBOSSL_QUIC_ERR_CRYPTO_ERR()\fR macro can be used to convert +a TLS alert code into a QUIC transport error code by mapping it into the range +reserved for such codes by RFC 9000. This range begins at +\&\fBOSSL_QUIC_ERR_CRYPTO_ERR_BEGIN\fR and ends at \fBOSSL_QUIC_ERR_CRYPTO_ERR_END\fR +inclusive. +.SH "NON\-STANDARD TRANSPORT ERROR CODES" +.IX Header "NON-STANDARD TRANSPORT ERROR CODES" +Some conditions which can cause QUIC connection termination are not signalled on +the wire and therefore do not have standard error codes. OpenSSL indicates these +errors via \fBSSL_get_conn_close_info()\fR by setting \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR +and using one of the following error values. These codes are specific to +OpenSSL, and cannot be sent over the wire, as they are above 2**62. +.IP \fBOSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT\fR 4 +.IX Item "OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT" +The connection was terminated immediately due to the idle timeout expiring. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_conn_close_info()\fR returns 1 on success and 0 on failure. This function +fails if called on a QUIC connection SSL object which has not yet been +terminated. It also fails if called on a QUIC stream SSL object or a non\-QUIC +SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_shutdown_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_current_cipher.3 b/static/netbsd/man3/SSL_get_current_cipher.3 new file mode 100644 index 00000000..cd6f5037 --- /dev/null +++ b/static/netbsd/man3/SSL_get_current_cipher.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: SSL_get_current_cipher.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_current_cipher 3" +.TH SSL_get_current_cipher 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher, +SSL_get_cipher_bits, SSL_get_cipher_version, +SSL_get_pending_cipher \- get SSL_CIPHER of a connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); +\& const SSL_CIPHER *SSL_get_pending_cipher(const SSL *ssl); +\& +\& const char *SSL_get_cipher_name(const SSL *s); +\& const char *SSL_get_cipher(const SSL *s); +\& int SSL_get_cipher_bits(const SSL *s, int *np); +\& const char *SSL_get_cipher_version(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_current_cipher()\fR returns a pointer to an SSL_CIPHER object containing +the description of the actually used cipher of a connection established with +the \fBssl\fR object. \fBssl\fR \fBMUST NOT\fR be NULL. +See \fBSSL_CIPHER_get_name\fR\|(3) for more details. +.PP +\&\fBSSL_get_cipher_name()\fR obtains the +name of the currently used cipher. +\&\fBSSL_get_cipher()\fR is identical to \fBSSL_get_cipher_name()\fR. +\&\fBSSL_get_cipher_bits()\fR is a +macro to obtain the number of secret/algorithm bits used and +\&\fBSSL_get_cipher_version()\fR returns the protocol name. +.PP +\&\fBSSL_get_pending_cipher()\fR returns a pointer to an SSL_CIPHER object containing +the description of the cipher (if any) that has been negotiated for future use +on the connection established with the \fBssl\fR object, but is not yet in use. +This may be the case during handshake processing, when control flow can be +returned to the application via any of several callback methods. The internal +sequencing of handshake processing and callback invocation is not guaranteed +to be stable from release to release, and at present only the callback set +by \fBSSL_CTX_set_alpn_select_cb()\fR is guaranteed to have a non\-NULL return value. +Other callbacks may be added to this list over time. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_current_cipher()\fR returns the cipher actually used, or NULL if +no session has been established. +.PP +\&\fBSSL_get_pending_cipher()\fR returns the cipher to be used at the next change +of cipher suite, or NULL if no such cipher is known. +.SH NOTES +.IX Header "NOTES" +SSL_get_cipher, SSL_get_cipher_bits, SSL_get_cipher_version, and +SSL_get_cipher_name are implemented as macros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CIPHER_get_name\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_default_timeout.3 b/static/netbsd/man3/SSL_get_default_timeout.3 new file mode 100644 index 00000000..293b386d --- /dev/null +++ b/static/netbsd/man3/SSL_get_default_timeout.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: SSL_get_default_timeout.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_default_timeout 3" +.TH SSL_get_default_timeout 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_default_timeout \- get default session timeout value +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_get_default_timeout(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_default_timeout()\fR returns the default timeout value assigned to +SSL_SESSION objects negotiated for the protocol valid for \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +Whenever a new session is negotiated, it is assigned a timeout value, +after which it will not be accepted for session reuse. If the timeout +value was not explicitly set using +\&\fBSSL_CTX_set_timeout\fR\|(3), the hardcoded default +timeout for the protocol will be used. +.PP +\&\fBSSL_get_default_timeout()\fR return this hardcoded value, which is 300 seconds +for all currently supported protocols. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +See description. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3), +\&\fBSSL_SESSION_get_time\fR\|(3), +\&\fBSSL_CTX_flush_sessions\fR\|(3), +\&\fBSSL_get_default_timeout\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_error.3 b/static/netbsd/man3/SSL_get_error.3 new file mode 100644 index 00000000..ec19c8d0 --- /dev/null +++ b/static/netbsd/man3/SSL_get_error.3 @@ -0,0 +1,250 @@ +.\" $NetBSD: SSL_get_error.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_error 3" +.TH SSL_get_error 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_error \- obtain result code for TLS/SSL I/O operation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_error(const SSL *ssl, int ret); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_error()\fR returns a result code (suitable for the C "switch" +statement) for a preceding call to \fBSSL_connect()\fR, \fBSSL_accept()\fR, \fBSSL_do_handshake()\fR, +\&\fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, \fBSSL_peek()\fR, \fBSSL_shutdown()\fR, +\&\fBSSL_write_ex()\fR or \fBSSL_write()\fR on \fBssl\fR. The value returned by that TLS/SSL I/O +function must be passed to \fBSSL_get_error()\fR in parameter \fBret\fR. +.PP +In addition to \fBssl\fR and \fBret\fR, \fBSSL_get_error()\fR inspects the +current thread\*(Aqs OpenSSL error queue. Thus, \fBSSL_get_error()\fR must be +used in the same thread that performed the TLS/SSL I/O operation, and no +other OpenSSL function calls should appear in between. The current +thread\*(Aqs error queue must be empty before the TLS/SSL I/O operation is +attempted, or \fBSSL_get_error()\fR will not work reliably. Emptying the +current thread\*(Aqs error queue is done with \fBERR_clear_error\fR\|(3). +.SH NOTES +.IX Header "NOTES" +Some TLS implementations do not send a close_notify alert on shutdown. +.PP +On an unexpected EOF, versions before OpenSSL 3.0 returned +\&\fBSSL_ERROR_SYSCALL\fR, nothing was added to the error stack, and errno was 0. +Since OpenSSL 3.0 the returned error is \fBSSL_ERROR_SSL\fR with a meaningful +error on the error stack (SSL_R_UNEXPECTED_EOF_WHILE_READING). This error reason +code may be used for control flow decisions (see the man page for +\&\fBERR_GET_REASON\fR\|(3) for further details on this). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can currently occur: +.IP SSL_ERROR_NONE 4 +.IX Item "SSL_ERROR_NONE" +The TLS/SSL I/O operation completed. This result code is returned +if and only if \fBret > 0\fR. +.IP SSL_ERROR_ZERO_RETURN 4 +.IX Item "SSL_ERROR_ZERO_RETURN" +The TLS/SSL peer has closed the connection for writing by sending the +close_notify alert. +No more data can be read. +Note that \fBSSL_ERROR_ZERO_RETURN\fR does not necessarily +indicate that the underlying transport has been closed. +.Sp +This error can also appear when the option \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR +is set. See \fBSSL_CTX_set_options\fR\|(3) for more details. +.IP "SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE" 4 +.IX Item "SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE" +The operation did not complete and can be retried later. +.Sp +For non\-QUIC SSL objects, \fBSSL_ERROR_WANT_READ\fR is returned when the last +operation was a read operation from a nonblocking \fBBIO\fR. +It means that not enough data was available at this time to complete the +operation. +If at a later time the underlying \fBBIO\fR has data available for reading the same +function can be called again. +.Sp +\&\fBSSL_read()\fR and \fBSSL_read_ex()\fR can also set \fBSSL_ERROR_WANT_READ\fR when there is +still unprocessed data available at either the \fBSSL\fR or the \fBBIO\fR layer, even +for a blocking \fBBIO\fR. +See \fBSSL_read\fR\|(3) for more information. +.Sp +For non\-QUIC SSL objects, \fBSSL_ERROR_WANT_WRITE\fR is returned when the last +operation was a write to a nonblocking \fBBIO\fR and it was unable to send all data +to the \fBBIO\fR. When the \fBBIO\fR is writable again, the same function can be +called again. +.Sp +Note that the retry may again lead to an \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR condition. +There is no fixed upper limit for the number of iterations that +may be necessary until progress becomes visible at application +protocol level. +.Sp +For QUIC SSL objects, the meaning of \fBSSL_ERROR_WANT_READ\fR and +\&\fBSSL_ERROR_WANT_WRITE\fR have different but largely compatible semantics. Since +QUIC implements its own flow control and uses UDP datagrams, backpressure +conditions in terms of the underlying BIO providing network I/O are not directly +relevant to the circumstances in which these errors are produced. In particular, +\&\fBSSL_ERROR_WANT_WRITE\fR indicates that the OpenSSL internal send buffer for a +given QUIC stream has been filled. Likewise, \fBSSL_ERROR_WANT_READ\fR indicates +that the OpenSSL internal receive buffer for a given QUIC stream is empty. +.Sp +It is safe to call \fBSSL_read()\fR or \fBSSL_read_ex()\fR when more data is available +even when the call that set this error was an \fBSSL_write()\fR or \fBSSL_write_ex()\fR. +However, if the call was an \fBSSL_write()\fR or \fBSSL_write_ex()\fR, it should be called +again to continue sending the application data. If you get \fBSSL_ERROR_WANT_WRITE\fR +from \fBSSL_write()\fR or \fBSSL_write_ex()\fR then you should not do any other operation +that could trigger \fBIO\fR other than to repeat the previous \fBSSL_write()\fR call. +.Sp +For socket \fBBIO\fRs (e.g. when \fBSSL_set_fd()\fR was used), \fBselect()\fR or +\&\fBpoll()\fR on the underlying socket can be used to find out when the +TLS/SSL I/O function should be retried. +.Sp +Caveat: Any TLS/SSL I/O function can lead to either of +\&\fBSSL_ERROR_WANT_READ\fR and \fBSSL_ERROR_WANT_WRITE\fR. +In particular, +\&\fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, or \fBSSL_peek()\fR may want to write data +and \fBSSL_write()\fR or \fBSSL_write_ex()\fR may want to read data. +This is mainly because +TLS/SSL handshakes may occur at any time during the protocol (initiated by +either the client or the server); \fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, +\&\fBSSL_peek()\fR, \fBSSL_write_ex()\fR, and \fBSSL_write()\fR will handle any pending handshakes. +.IP "SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT" 4 +.IX Item "SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT" +The operation did not complete; the same TLS/SSL I/O function should be +called again later. The underlying BIO was not connected yet to the peer +and the call would block in \fBconnect()\fR/\fBaccept()\fR. The SSL function should be +called again when the connection is established. These messages can only +appear with a \fBBIO_s_connect()\fR or \fBBIO_s_accept()\fR BIO, respectively. +In order to find out, when the connection has been successfully established, +on many platforms \fBselect()\fR or \fBpoll()\fR for writing on the socket file descriptor +can be used. +.IP SSL_ERROR_WANT_X509_LOOKUP 4 +.IX Item "SSL_ERROR_WANT_X509_LOOKUP" +The operation did not complete because an application callback set by +\&\fBSSL_CTX_set_client_cert_cb()\fR has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. +.IP SSL_ERROR_WANT_ASYNC 4 +.IX Item "SSL_ERROR_WANT_ASYNC" +The operation did not complete because an asynchronous engine is still +processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC +using \fBSSL_CTX_set_mode\fR\|(3) or \fBSSL_set_mode\fR\|(3) and an asynchronous capable +engine is being used. An application can determine whether the engine has +completed its processing using \fBselect()\fR or \fBpoll()\fR on the asynchronous wait file +descriptor. This file descriptor is available by calling +\&\fBSSL_get_all_async_fds\fR\|(3) or \fBSSL_get_changed_async_fds\fR\|(3). The TLS/SSL I/O +function should be called again later. The function \fBmust\fR be called from the +same thread that the original call was made from. +.IP SSL_ERROR_WANT_ASYNC_JOB 4 +.IX Item "SSL_ERROR_WANT_ASYNC_JOB" +The asynchronous job could not be started because there were no async jobs +available in the pool (see \fBASYNC_init_thread\fR\|(3)). This will only occur if the +mode has been set to SSL_MODE_ASYNC using \fBSSL_CTX_set_mode\fR\|(3) or +\&\fBSSL_set_mode\fR\|(3) and a maximum limit has been set on the async job pool +through a call to \fBASYNC_init_thread\fR\|(3). The application should retry the +operation after a currently executing asynchronous operation for the current +thread has completed. +.IP SSL_ERROR_WANT_CLIENT_HELLO_CB 4 +.IX Item "SSL_ERROR_WANT_CLIENT_HELLO_CB" +The operation did not complete because an application callback set by +\&\fBSSL_CTX_set_client_hello_cb()\fR has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. +.IP SSL_ERROR_SYSCALL 4 +.IX Item "SSL_ERROR_SYSCALL" +Some non\-recoverable, fatal I/O error occurred. The OpenSSL error queue may +contain more information on the error. For socket I/O on Unix systems, consult +\&\fBerrno\fR for details. If this error occurs then no further I/O operations should +be performed on the connection and \fBSSL_shutdown()\fR must not be called. +.Sp +This value can also be returned for other errors, check the error queue for +details. +.IP SSL_ERROR_SSL 4 +.IX Item "SSL_ERROR_SSL" +A non\-recoverable, fatal error in the SSL library occurred, usually a protocol +error. The OpenSSL error queue contains more information on the error. If this +error occurs then no further I/O operations should be performed on the +connection and \fBSSL_shutdown()\fR must not be called. +.PP +The OpenSSL error queue can be inspected with the \fBERR\fR family of functions, +such as \fBERR_print_errors\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBERR_clear_error\fR\|(3), \fBERR_print_errors\fR\|(3), \fBERR_peek_last_error_all\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The SSL_ERROR_WANT_ASYNC error code was added in OpenSSL 1.1.0. +The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_event_timeout.3 b/static/netbsd/man3/SSL_get_event_timeout.3 new file mode 100644 index 00000000..56302dc9 --- /dev/null +++ b/static/netbsd/man3/SSL_get_event_timeout.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: SSL_get_event_timeout.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_event_timeout 3" +.TH SSL_get_event_timeout 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_event_timeout \- determine when an SSL object next needs to have events +handled +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_event_timeout()\fR determines when the SSL object next needs to perform +internal processing due to the passage of time. +.PP +All arguments are required; \fItv\fR and \fIis_infinite\fR must be non\-NULL. +.PP +Upon the successful return of \fBSSL_get_event_timeout()\fR, one of the following +cases applies: +.IP \(bu 4 +The SSL object has events which need to be handled immediately; The fields of +\&\fI*tv\fR are set to 0 and \fI*is_infinite\fR is set to 0. +.IP \(bu 4 +The SSL object has events which need to be handled after some amount of time +(relative to the time at which \fBSSL_get_event_timeout()\fR was called). \fI*tv\fR is +set to the amount of time after which \fBSSL_handle_events\fR\|(3) should be called +and \fI*is_infinite\fR is set to 0. +.IP \(bu 4 +There are currently no timer events which require handling in the future. The +value of \fI*tv\fR is unspecified and \fI*is_infinite\fR is set to 1. +.PP +This function is currently applicable only to DTLS and QUIC connection SSL +objects. If it is called on any other kind of SSL object, it always outputs +infinity. This is considered a success condition. +.PP +For DTLS, this function can be used instead of the older +\&\fBDTLSv1_get_timeout\fR\|(3) function. Note that this function differs from +\&\fBDTLSv1_get_timeout\fR\|(3) in that the case where no timeout is active is +considered a success condition. +.PP +Note that the value output by a call to \fBSSL_get_event_timeout()\fR may change as a +result of other calls to the SSL object. +.PP +Once the timeout expires, \fBSSL_handle_events\fR\|(3) should be called to handle any +internal processing which is due; for more information, see +\&\fBSSL_handle_events\fR\|(3). +.PP +Note that \fBSSL_get_event_timeout()\fR supersedes the older \fBDTLSv1_get_timeout\fR\|(3) +function for all use cases. +.PP +If the call to \fBSSL_get_event_timeout()\fR fails, the values of \fI*tv\fR and +\&\fI*is_infinite\fR may still be changed and their values become unspecified. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBDTLSv1_get_timeout\fR\|(3), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_get_event_timeout()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 b/static/netbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 new file mode 100644 index 00000000..7188f93f --- /dev/null +++ b/static/netbsd/man3/SSL_get_ex_data_X509_STORE_CTX_idx.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: SSL_get_ex_data_X509_STORE_CTX_idx.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_get_ex_data_X509_STORE_CTX_idx 3" +.TH SSL_get_ex_data_X509_STORE_CTX_idx 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_get_ex_data_X509_STORE_CTX_idx \- get ex_data index to access SSL structure +from X509_STORE_CTX +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_ex_data_X509_STORE_CTX_idx(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_get_ex_data_X509_STORE_CTX_idx()\fR returns the index number under which +the pointer to the \s-1SSL\s0 object is stored into the X509_STORE_CTX object. +.SH "NOTES" +.IX Header "NOTES" +Whenever a X509_STORE_CTX object is created for the verification of the +peers certificate during a handshake, a pointer to the \s-1SSL\s0 object is +stored into the X509_STORE_CTX object to identify the connection affected. +To retrieve this pointer the \fIX509_STORE_CTX_get_ex_data()\fR function can +be used with the correct index. This index is globally the same for all +X509_STORE_CTX objects and can be retrieved using +\&\fISSL_get_ex_data_X509_STORE_CTX_idx()\fR. The index value is set when +\&\fISSL_get_ex_data_X509_STORE_CTX_idx()\fR is first called either by the application +program directly or indirectly during other \s-1SSL\s0 setup functions or during +the handshake. +.PP +The value depends on other index values defined for X509_STORE_CTX objects +before the \s-1SSL\s0 index is created. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +.IP ">=0" 4 +.IX Item ">=0" +The index value to access the pointer. +.IP "<0" 4 +.IX Item "<0" +An error occurred, check the error stack for a detailed error message. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +The index returned from \fISSL_get_ex_data_X509_STORE_CTX_idx()\fR allows to +access the \s-1SSL\s0 object for the connection to be accessed during the +\&\fIverify_callback()\fR when checking the peers certificate. Please check +the example in \fISSL_CTX_set_verify\fR\|(3), +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(3), \fISSL_CTX_set_verify\fR\|(3), +\&\fICRYPTO_set_ex_data\fR\|(3) diff --git a/static/netbsd/man3/SSL_get_ex_new_index.3 b/static/netbsd/man3/SSL_get_ex_new_index.3 new file mode 100644 index 00000000..ad49367d --- /dev/null +++ b/static/netbsd/man3/SSL_get_ex_new_index.3 @@ -0,0 +1,192 @@ +.\" $NetBSD: SSL_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_get_ex_new_index 3" +.TH SSL_get_ex_new_index 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data \- internal application specific data functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int SSL_set_ex_data(SSL *ssl, int idx, void *arg); +\& +\& void *SSL_get_ex_data(const SSL *ssl, int idx); +\& +\& typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, +\& int idx, long argl, void *argp); +\& typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, +\& int idx, long argl, void *argp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.PP +\&\fISSL_get_ex_new_index()\fR is used to register a new index for application +specific data. +.PP +\&\fISSL_set_ex_data()\fR is used to store application data at \fBarg\fR for \fBidx\fR into +the \fBssl\fR object. +.PP +\&\fISSL_get_ex_data()\fR is used to retrieve the information for \fBidx\fR from +\&\fBssl\fR. +.PP +A detailed description for the \fB*\f(BI_get_ex_new_index()\fB\fR functionality +can be found in \fIRSA_get_ex_new_index\fR\|(3). +The \fB*\f(BI_get_ex_data()\fB\fR and \fB*\f(BI_set_ex_data()\fB\fR functionality is described in +\&\fICRYPTO_set_ex_data\fR\|(3). +.SH "EXAMPLES" +.IX Header "EXAMPLES" +An example on how to use the functionality is included in the example +\&\fIverify_callback()\fR in \fISSL_CTX_set_verify\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(3), +\&\fIRSA_get_ex_new_index\fR\|(3), +\&\fICRYPTO_set_ex_data\fR\|(3), +\&\fISSL_CTX_set_verify\fR\|(3) diff --git a/static/netbsd/man3/SSL_get_extms_support.3 b/static/netbsd/man3/SSL_get_extms_support.3 new file mode 100644 index 00000000..fd275882 --- /dev/null +++ b/static/netbsd/man3/SSL_get_extms_support.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: SSL_get_extms_support.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_extms_support 3" +.TH SSL_get_extms_support 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_extms_support \- extended master secret support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_extms_support(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_extms_support()\fR indicates whether the current session used extended +master secret. +.PP +This function is implemented as a macro. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_extms_support()\fR returns 1 if the current session used extended +master secret, 0 if it did not and \-1 if a handshake is currently in +progress i.e. it is not possible to determine if extended master secret +was used. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_fd.3 b/static/netbsd/man3/SSL_get_fd.3 new file mode 100644 index 00000000..0766df8e --- /dev/null +++ b/static/netbsd/man3/SSL_get_fd.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: SSL_get_fd.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_fd 3" +.TH SSL_get_fd 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_fd, SSL_get_rfd, SSL_get_wfd \- get file descriptor linked to an SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_fd(const SSL *ssl); +\& int SSL_get_rfd(const SSL *ssl); +\& int SSL_get_wfd(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_fd()\fR returns the file descriptor which is linked to \fBssl\fR. +\&\fBSSL_get_rfd()\fR and \fBSSL_get_wfd()\fR return the file descriptors for the +read or the write channel, which can be different. If the read and the +write channel are different, \fBSSL_get_fd()\fR will return the file descriptor +of the read channel. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP \-1 4 +.IX Item "-1" +The operation failed, because the underlying BIO is not of the correct type +(suitable for file descriptors). +.IP >=0 4 +.IX Item ">=0" +The file descriptor linked to \fBssl\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_set_fd\fR\|(3), \fBssl\fR\|(7) , \fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_handshake_rtt.3 b/static/netbsd/man3/SSL_get_handshake_rtt.3 new file mode 100644 index 00000000..02da07d0 --- /dev/null +++ b/static/netbsd/man3/SSL_get_handshake_rtt.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: SSL_get_handshake_rtt.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_handshake_rtt 3" +.TH SSL_get_handshake_rtt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_handshake_rtt +\&\- get round trip time for SSL Handshake +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_handshake_rtt(const SSL *s, uint64_t *rtt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_handshake_rtt()\fR retrieves the round\-trip time (RTT) for \fIssl\fR. +.PP +This metric is represented in microseconds (us) as a uint64_t data type. +.SH NOTES +.IX Header "NOTES" +This metric is created by taking two timestamps during the handshake and +providing the difference between these two times. +.PP +When acting as the server, one timestamp is taken when the server is finished +writing to the client. This is during the ServerFinished in TLS 1.3 and +ServerHelloDone in TLS 1.2. The other timestamp is taken when the server is +done reading the client\*(Aqs response. This is after the client has responded +with ClientFinished. +.PP +When acting as the client, one timestamp is taken when the client is finished +writing the ClientHello and early data (if any). The other is taken when +client is done reading the server\*(Aqs response. This is after ServerFinished in +TLS 1.3 and after ServerHelloDone in TLS 1.2. +.PP +In addition to network propagation delay and network stack overhead, this +metric includes processing time on both endpoints, as this is based on TLS +protocol\-level messages and the TLS protocol is not designed to measure +network timings. In some cases the processing time can be significant, +especially when the processing includes asymmetric cryptographic operations. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 if the TLS handshake RTT is successfully retrieved. +Returns 0 if the TLS handshake RTT cannot be determined yet. +Returns \-1 if, while retrieving the TLS handshake RTT, an error occurs. +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_peer_cert_chain.3 b/static/netbsd/man3/SSL_get_peer_cert_chain.3 new file mode 100644 index 00000000..fe626812 --- /dev/null +++ b/static/netbsd/man3/SSL_get_peer_cert_chain.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: SSL_get_peer_cert_chain.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_peer_cert_chain 3" +.TH SSL_get_peer_cert_chain 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_peer_cert_chain, SSL_get0_verified_chain \- get the X509 certificate +chain of the peer +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); +\& STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_peer_cert_chain()\fR returns a pointer to STACK_OF(X509) certificates +forming the certificate chain sent by the peer. If called on the client side, +the stack also contains the peer\*(Aqs certificate; if called on the server +side, the peer\*(Aqs certificate must be obtained separately using +\&\fBSSL_get_peer_certificate\fR\|(3). +If the peer did not present a certificate, NULL is returned. +.PP +NB: \fBSSL_get_peer_cert_chain()\fR returns the peer chain as sent by the peer: it +only consists of certificates the peer has sent (in the order the peer +has sent them) it is \fBnot\fR a verified chain. +.PP +\&\fBSSL_get0_verified_chain()\fR returns the \fBverified\fR certificate chain +of the peer including the peer\*(Aqs end entity certificate. It must be called +after a session has been successfully established. If peer verification was +not successful (as indicated by \fBSSL_get_verify_result()\fR not returning +X509_V_OK) the chain may be incomplete or invalid. +.SH NOTES +.IX Header "NOTES" +If the session is resumed peers do not send certificates so a NULL pointer +is returned by these functions. Applications can call \fBSSL_session_reused()\fR +to determine whether a session is resumed. +.PP +The reference count of each certificate in the returned STACK_OF(X509) object +is not incremented and the returned stack may be invalidated by renegotiation. +If applications wish to use any certificates in the returned chain +indefinitely they must increase the reference counts using \fBX509_up_ref()\fR or +obtain a copy of the whole chain with \fBX509_chain_up_ref()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +No certificate was presented by the peer or no connection was established +or the certificate chain is no longer available when a session is reused. +.IP "Pointer to a STACK_OF(X509)" 4 +.IX Item "Pointer to a STACK_OF(X509)" +The return value points to the certificate chain presented by the peer. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_peer_certificate\fR\|(3), \fBX509_up_ref\fR\|(3), +\&\fBX509_chain_up_ref\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_peer_certificate.3 b/static/netbsd/man3/SSL_get_peer_certificate.3 new file mode 100644 index 00000000..1efbe74c --- /dev/null +++ b/static/netbsd/man3/SSL_get_peer_certificate.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: SSL_get_peer_certificate.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_peer_certificate 3" +.TH SSL_get_peer_certificate 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_peer_certificate, +SSL_get0_peer_certificate, +SSL_get1_peer_certificate \- get the X509 certificate of the peer +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *SSL_get0_peer_certificate(const SSL *ssl); +\& X509 *SSL_get1_peer_certificate(const SSL *ssl); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, +and can be hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable +version value, see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& X509 *SSL_get_peer_certificate(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions return a pointer to the X509 certificate the +peer presented. If the peer did not present a certificate, NULL is returned. +.SH NOTES +.IX Header "NOTES" +Due to the protocol definition, a TLS/SSL server will always send a +certificate, if present. A client will only send a certificate when +explicitly requested to do so by the server (see +\&\fBSSL_CTX_set_verify\fR\|(3)). If an anonymous cipher +is used, no certificates are sent. +.PP +That a certificate is returned does not indicate information about the +verification state, use \fBSSL_get_verify_result\fR\|(3) +to check the verification state. +.PP +The reference count of the X509 object returned by \fBSSL_get1_peer_certificate()\fR +is incremented by one, so that it will not be destroyed when the session +containing the peer certificate is freed. The X509 object must be explicitly +freed using \fBX509_free()\fR. +.PP +The reference count of the X509 object returned by \fBSSL_get0_peer_certificate()\fR +is not incremented, and must not be freed. +.PP +\&\fBSSL_get_peer_certificate()\fR is an alias of \fBSSL_get1_peer_certificate()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +No certificate was presented by the peer or no connection was established. +.IP "Pointer to an X509 certificate" 4 +.IX Item "Pointer to an X509 certificate" +The return value points to the certificate presented by the peer. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_CTX_set_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_get0_peer_certificate()\fR and \fBSSL_get1_peer_certificate()\fR were added in 3.0.0. +\&\fBSSL_get_peer_certificate()\fR was deprecated in 3.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_peer_signature_nid.3 b/static/netbsd/man3/SSL_get_peer_signature_nid.3 new file mode 100644 index 00000000..a7aa1faf --- /dev/null +++ b/static/netbsd/man3/SSL_get_peer_signature_nid.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: SSL_get_peer_signature_nid.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_peer_signature_nid 3" +.TH SSL_get_peer_signature_nid 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get0_peer_signature_name, SSL_get_peer_signature_nid, +SSL_get_peer_signature_type_nid, SSL_get0_signature_name, +SSL_get_signature_nid, SSL_get_signature_type_nid \- +get TLS message signing types +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get0_peer_signature_name(const SSL *ssl, const char **sigalg); +\& int SSL_get_peer_signature_nid(SSL *ssl, int *psig_nid); +\& int SSL_get_peer_signature_type_nid(const SSL *ssl, int *psigtype_nid); +\& int SSL_get0_signature_name(SSL *ssl, const char **sigalg); +\& int SSL_get_signature_nid(SSL *ssl, int *psig_nid); +\& int SSL_get_signature_type_nid(const SSL *ssl, int *psigtype_nid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get0_peer_signature_name()\fR sets \fI*sigalg\fR to the IANA name of the +signature scheme +used by the peer to sign the TLS handshake. +The caller must not free the returned pointer. +The returned string should be copied if it is to be retained beyond the +lifetime of the SSL connection. +.PP +\&\fBSSL_get_peer_signature_nid()\fR sets \fB*psig_nid\fR to the NID of the digest used +by the peer to sign TLS messages. It is implemented as a macro. +.PP +\&\fBSSL_get_peer_signature_type_nid()\fR sets \fB*psigtype_nid\fR to the signature +type used by the peer to sign TLS messages. Currently the signature type +is the NID of the public key type used for signing except for PSS signing +where it is \fBEVP_PKEY_RSA_PSS\fR. To differentiate between +\&\fBrsa_pss_rsae_*\fR and \fBrsa_pss_pss_*\fR signatures, it\*(Aqs necessary to check +the type of public key in the peer\*(Aqs certificate. +.PP +\&\fBSSL_get0_signature_name()\fR, \fBSSL_get_signature_nid()\fR and +\&\fBSSL_get_signature_type_nid()\fR return the equivalent information for the local +end of the connection. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return 1 for success and 0 for failure. There are several +possible reasons for failure: the peer or local end is a client and did not +sign the handshake (did not use a client certificate), the cipher suite has no +signature (e.g. it uses RSA key exchange or is anonymous), the TLS version is +below 1.2 or the functions were called too early, e.g. before the peer signed a +message. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_peer_certificate\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_get0_peer_signature_name()\fR and \fBSSL_get0_signature_name()\fR functions were +added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_peer_tmp_key.3 b/static/netbsd/man3/SSL_get_peer_tmp_key.3 new file mode 100644 index 00000000..687b69b0 --- /dev/null +++ b/static/netbsd/man3/SSL_get_peer_tmp_key.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: SSL_get_peer_tmp_key.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_peer_tmp_key 3" +.TH SSL_get_peer_tmp_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_peer_tmp_key, SSL_get_server_tmp_key, SSL_get_tmp_key \- get information +about temporary keys used during a handshake +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_get_peer_tmp_key(SSL *ssl, EVP_PKEY **key); +\& long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key); +\& long SSL_get_tmp_key(SSL *ssl, EVP_PKEY **key); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_peer_tmp_key()\fR returns the temporary key provided by the peer and +used during key exchange. For example, if ECDHE is in use, then this represents +the peer\*(Aqs public ECDHE key. On success a pointer to the key is stored in +\&\fB*key\fR. It is the caller\*(Aqs responsibility to free this key after use using +\&\fBEVP_PKEY_free\fR\|(3). +.PP +\&\fBSSL_get_server_tmp_key()\fR is a backwards compatibility alias for +\&\fBSSL_get_peer_tmp_key()\fR. +Under that name it worked just on the client side of the connection, its +behaviour on the server end is release\-dependent. +.PP +\&\fBSSL_get_tmp_key()\fR returns the equivalent information for the local +end of the connection. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All these functions return 1 on success and 0 otherwise. +.SH NOTES +.IX Header "NOTES" +This function is implemented as a macro. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBEVP_PKEY_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_psk_identity.3 b/static/netbsd/man3/SSL_get_psk_identity.3 new file mode 100644 index 00000000..9c50268a --- /dev/null +++ b/static/netbsd/man3/SSL_get_psk_identity.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: SSL_get_psk_identity.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_psk_identity 3" +.TH SSL_get_psk_identity 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_psk_identity, SSL_get_psk_identity_hint \- get PSK client identity and hint +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_get_psk_identity_hint(const SSL *ssl); +\& const char *SSL_get_psk_identity(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_psk_identity_hint()\fR is used to retrieve the PSK identity hint +used during the connection setup related to SSL object +\&\fBssl\fR. Similarly, \fBSSL_get_psk_identity()\fR is used to retrieve the PSK +identity used during the connection setup. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If non\-\fBNULL\fR, \fBSSL_get_psk_identity_hint()\fR returns the PSK identity +hint and \fBSSL_get_psk_identity()\fR returns the PSK identity. Both are +\&\fBNULL\fR\-terminated. \fBSSL_get_psk_identity_hint()\fR may return \fBNULL\fR if +no PSK identity hint was used during the connection setup. +.PP +Note that the return value is valid only during the lifetime of the +SSL object \fBssl\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_rbio.3 b/static/netbsd/man3/SSL_get_rbio.3 new file mode 100644 index 00000000..25c9ba78 --- /dev/null +++ b/static/netbsd/man3/SSL_get_rbio.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: SSL_get_rbio.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_rbio 3" +.TH SSL_get_rbio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_rbio, SSL_get_wbio \- get BIO linked to an SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& BIO *SSL_get_rbio(SSL *ssl); +\& BIO *SSL_get_wbio(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_rbio()\fR and \fBSSL_get_wbio()\fR return pointers to the BIOs for the +read or the write channel, which can be different. The reference count +of the BIO is not incremented. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +No BIO was connected to the SSL object +.IP "Any other pointer" 4 +.IX Item "Any other pointer" +The BIO linked to \fBssl\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_set_bio\fR\|(3), \fBssl\fR\|(7) , \fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_rpoll_descriptor.3 b/static/netbsd/man3/SSL_get_rpoll_descriptor.3 new file mode 100644 index 00000000..be31a3db --- /dev/null +++ b/static/netbsd/man3/SSL_get_rpoll_descriptor.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: SSL_get_rpoll_descriptor.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_rpoll_descriptor 3" +.TH SSL_get_rpoll_descriptor 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired, +SSL_net_write_desired \- obtain information which can be used to determine when +network I/O can be performed +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc); +\& int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc); +\& int SSL_net_read_desired(SSL *s); +\& int SSL_net_write_desired(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The functions \fBSSL_get_rpoll_descriptor()\fR and \fBSSL_get_wpoll_descriptor()\fR can be +used to determine when an SSL object which represents a QUIC connection can +perform useful network I/O, so that an application using a QUIC connection SSL +object in nonblocking mode can determine when it should call \fBSSL_handle_events()\fR. +.PP +On success, these functions output poll descriptors. For more information on +poll descriptors, see \fBBIO_get_rpoll_descriptor\fR\|(3). +.PP +The functions \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR return 1 or 0 +depending on whether the SSL object is currently interested in receiving data +from the network and/or writing data to the network respectively. +If an SSL object is not interested in reading data from the network at the +current time, \fBSSL_net_read_desired()\fR will return 0; likewise, if an SSL object is +not interested in writing data to the network at the current time, +\&\fBSSL_net_write_desired()\fR will return 0. +.PP +The intention is that an application using QUIC in nonblocking mode can use +these calls, in conjunction with \fBSSL_get_event_timeout\fR\|(3) to wait for network +I/O conditions which allow the SSL object to perform useful work. When such a +condition arises, \fBSSL_handle_events\fR\|(3) should be called. +.PP +In particular, the expected usage is as follows: +.IP \(bu 4 +\&\fBSSL_handle_events()\fR should be called whenever the timeout returned by +\&\fBSSL_get_event_timeout\fR\|(3) (if any) expires +.IP \(bu 4 +If the last call to \fBSSL_net_read_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called +whenever the poll descriptor output by \fBSSL_get_rpoll_descriptor()\fR becomes +readable. +.IP \(bu 4 +If the last call to \fBSSL_net_write_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called +whenever the poll descriptor output by \fBSSL_get_wpoll_descriptor()\fR becomes +writable. +.PP +The return values of the \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR functions +may change in response to any call to the SSL object other than +\&\fBSSL_net_read_desired()\fR, \fBSSL_net_write_desired()\fR, \fBSSL_get_rpoll_descriptor()\fR, +\&\fBSSL_get_wpoll_descriptor()\fR and \fBSSL_get_event_timeout()\fR. +.PP +On non\-QUIC SSL objects, calls to \fBSSL_get_rpoll_descriptor()\fR and +\&\fBSSL_get_wpoll_descriptor()\fR function the same as calls to +\&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR on the respective read +and write BIOs configured on the SSL object. +.PP +On non\-QUIC SSL objects, calls to \fBSSL_net_read_desired()\fR and +\&\fBSSL_net_write_desired()\fR function identically to calls to \fBSSL_want_read()\fR and +\&\fBSSL_want_write()\fR respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_get_rpoll_descriptor()\fR, \fBSSL_get_wpoll_descriptor()\fR, \fBSSL_net_read_desired()\fR +and \fBSSL_net_write_desired()\fR functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_server_tmp_key.3 b/static/netbsd/man3/SSL_get_server_tmp_key.3 new file mode 100644 index 00000000..91e1602d --- /dev/null +++ b/static/netbsd/man3/SSL_get_server_tmp_key.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: SSL_get_server_tmp_key.3,v 1.1 2018/09/23 13:33:08 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSL_get_server_tmp_key 3" +.TH SSL_get_server_tmp_key 3 "2018-09-17" "1.1.1" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL_get_server_tmp_key \- get information about the server's temporary key used +during a handshake +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSL_get_server_tmp_key()\fR returns the temporary key provided by the server and +used during key exchange. For example, if \s-1ECDHE\s0 is in use, then this represents +the server's public \s-1ECDHE\s0 key. On success a pointer to the key is stored in +\&\fB*key\fR. It is the caller's responsibility to free this key after use using +\&\fIEVP_PKEY_free\fR\|(3). This function may only be called by the client. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fISSL_get_server_tmp_key()\fR returns 1 on success or 0 otherwise. +.SH "NOTES" +.IX Header "NOTES" +This function is implemented as a macro. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIssl\fR\|(7), \fIEVP_PKEY_free\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_session.3 b/static/netbsd/man3/SSL_get_session.3 new file mode 100644 index 00000000..be9a1a85 --- /dev/null +++ b/static/netbsd/man3/SSL_get_session.3 @@ -0,0 +1,165 @@ +.\" $NetBSD: SSL_get_session.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_session 3" +.TH SSL_get_session 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_session, SSL_get0_session, SSL_get1_session \- retrieve TLS/SSL session data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_SESSION *SSL_get_session(const SSL *ssl); +\& SSL_SESSION *SSL_get0_session(const SSL *ssl); +\& SSL_SESSION *SSL_get1_session(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_session()\fR returns a pointer to the \fBSSL_SESSION\fR actually used in +\&\fBssl\fR. The reference count of the \fBSSL_SESSION\fR is not incremented, so +that the pointer can become invalid by other operations. +.PP +\&\fBSSL_get0_session()\fR is the same as \fBSSL_get_session()\fR. +.PP +\&\fBSSL_get1_session()\fR is the same as \fBSSL_get_session()\fR, but the reference +count of the \fBSSL_SESSION\fR is incremented by one. +.SH NOTES +.IX Header "NOTES" +The ssl session contains all information required to re\-establish the +connection without a full handshake for SSL versions up to and including +TLSv1.2. In TLSv1.3 the same is true, but sessions are established after the +main handshake has occurred. The server will send the session information to the +client at a time of its choosing, which may be some while after the initial +connection is established (or never). Calling these functions on the client side +in TLSv1.3 before the session has been established will still return an +SSL_SESSION object but that object cannot be used for resuming the session. See +\&\fBSSL_SESSION_is_resumable\fR\|(3) for information on how to determine whether an +SSL_SESSION object can be used for resumption or not. +.PP +Additionally, in TLSv1.3, a server can send multiple messages that establish a +session for a single connection. In that case, on the client side, the above +functions will only return information on the last session that was received. On +the server side they will only return information on the last session that was +sent, or if no session tickets were sent then the session for the current +connection. +.PP +The preferred way for applications to obtain a resumable SSL_SESSION object is +to use a new session callback as described in \fBSSL_CTX_sess_set_new_cb\fR\|(3). +The new session callback is only invoked when a session is actually established, +so this avoids the problem described above where an application obtains an +SSL_SESSION object that cannot be used for resumption in TLSv1.3. It also +enables applications to obtain information about all sessions sent by the +server. +.PP +A session will be automatically removed from the session cache and marked as +non\-resumable if the connection is not closed down cleanly, e.g. if a fatal +error occurs on the connection or \fBSSL_shutdown\fR\|(3) is not called prior to +\&\fBSSL_free\fR\|(3). +.PP +In TLSv1.3 it is recommended that each SSL_SESSION object is only used for +resumption once. +.PP +\&\fBSSL_get0_session()\fR returns a pointer to the actual session. As the +reference counter is not incremented, the pointer is only valid while +the connection is in use. If \fBSSL_clear\fR\|(3) or +\&\fBSSL_free\fR\|(3) is called, the session may be removed completely +(if considered bad), and the pointer obtained will become invalid. Even +if the session is valid, it can be removed at any time due to timeout +during \fBSSL_CTX_flush_sessions\fR\|(3). +.PP +If the data is to be kept, \fBSSL_get1_session()\fR will increment the reference +count, so that the session will not be implicitly removed by other operations +but stays in memory. In order to remove the session +\&\fBSSL_SESSION_free\fR\|(3) must be explicitly called once +to decrement the reference count again. +.PP +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object\*(Aqs session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +There is no session available in \fBssl\fR. +.IP "Pointer to an SSL_SESSION" 4 +.IX Item "Pointer to an SSL_SESSION" +The return value points to the data of an SSL session. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_free\fR\|(3), +\&\fBSSL_clear\fR\|(3), +\&\fBSSL_SESSION_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_shared_sigalgs.3 b/static/netbsd/man3/SSL_get_shared_sigalgs.3 new file mode 100644 index 00000000..de2af38e --- /dev/null +++ b/static/netbsd/man3/SSL_get_shared_sigalgs.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: SSL_get_shared_sigalgs.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_shared_sigalgs 3" +.TH SSL_get_shared_sigalgs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_shared_sigalgs, SSL_get_sigalgs \- get supported signature algorithms +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_shared_sigalgs(SSL *s, int idx, +\& int *psign, int *phash, int *psignhash, +\& unsigned char *rsig, unsigned char *rhash); +\& +\& int SSL_get_sigalgs(SSL *s, int idx, +\& int *psign, int *phash, int *psignhash, +\& unsigned char *rsig, unsigned char *rhash); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_shared_sigalgs()\fR returns information about the shared signature +algorithms supported by peer \fBs\fR. The parameter \fBidx\fR indicates the index +of the shared signature algorithm to return starting from zero. The signature +algorithm NID is written to \fB*psign\fR, the hash NID to \fB*phash\fR and the +sign and hash NID to \fB*psignhash\fR. The raw signature and hash values +are written to \fB*rsig\fR and \fB*rhash\fR. +.PP +\&\fBSSL_get_sigalgs()\fR is similar to \fBSSL_get_shared_sigalgs()\fR except it returns +information about all signature algorithms supported by \fBs\fR in the order +they were sent by the peer. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_shared_sigalgs()\fR and \fBSSL_get_sigalgs()\fR return the number of +signature algorithms or \fB0\fR if the \fBidx\fR parameter is out of range. +.SH NOTES +.IX Header "NOTES" +These functions are typically called for debugging purposes (to report +the peer\*(Aqs preferences) or where an application wants finer control over +certificate selection. Most applications will rely on internal handling +and will not need to call them. +.PP +If an application is only interested in the highest preference shared +signature algorithm it can just set \fBidx\fR to zero. +.PP +Any or all of the parameters \fBpsign\fR, \fBphash\fR, \fBpsignhash\fR, \fBrsig\fR or +\&\fBrhash\fR can be set to \fBNULL\fR if the value is not required. By setting +them all to \fBNULL\fR and setting \fBidx\fR to zero the total number of +signature algorithms can be determined: which can be zero. +.PP +These functions must be called after the peer has sent a list of supported +signature algorithms: after a client hello (for servers) or a certificate +request (for clients). They can (for example) be called in the certificate +callback. +.PP +Only TLS 1.2, TLS 1.3 and DTLS 1.2 currently support signature algorithms. +If these +functions are called on an earlier version of TLS or DTLS zero is returned. +.PP +The shared signature algorithms returned by \fBSSL_get_shared_sigalgs()\fR are +ordered according to configuration and peer preferences. +.PP +The raw values correspond to the on the wire form as defined by RFC5246 et al. +The NIDs are OpenSSL equivalents. For example if the peer sent \fBsha256\fR\|(4) and +\&\fBrsa\fR\|(1) then \fB*rhash\fR would be 4, \fB*rsign\fR 1, \fB*phash\fR NID_sha256, \fB*psig\fR +NID_rsaEncryption and \fB*psignhash\fR NID_sha256WithRSAEncryption. +.PP +If a signature algorithm is not recognised the corresponding NIDs +will be set to \fBNID_undef\fR. This may be because the value is not supported, +is not an appropriate combination (for example MD5 and DSA) or the +signature algorithm does not use a hash (for example Ed25519). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_set_cert_cb\fR\|(3), +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_stream_id.3 b/static/netbsd/man3/SSL_get_stream_id.3 new file mode 100644 index 00000000..4d75ff29 --- /dev/null +++ b/static/netbsd/man3/SSL_get_stream_id.3 @@ -0,0 +1,159 @@ +.\" $NetBSD: SSL_get_stream_id.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_stream_id 3" +.TH SSL_get_stream_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_stream_id, SSL_get_stream_type, SSL_STREAM_TYPE_NONE, +SSL_STREAM_TYPE_READ, SSL_STREAM_TYPE_WRITE, SSL_STREAM_TYPE_BIDI, +SSL_is_stream_local \- get QUIC stream ID and stream type information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& uint64_t SSL_get_stream_id(SSL *ssl); +\& +\& #define SSL_STREAM_TYPE_NONE +\& #define SSL_STREAM_TYPE_BIDI +\& #define SSL_STREAM_TYPE_READ +\& #define SSL_STREAM_TYPE_WRITE +\& int SSL_get_stream_type(SSL *ssl); +\& +\& int SSL_is_stream_local(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_get_stream_id()\fR function returns the QUIC stream ID for a QUIC stream +SSL object, or for a QUIC connection SSL object which has a default stream +attached. +.PP +The \fBSSL_get_stream_type()\fR function identifies what operations can be performed +on the stream, and returns one of the following values: +.IP \fBSSL_STREAM_TYPE_NONE\fR 4 +.IX Item "SSL_STREAM_TYPE_NONE" +The SSL object is a QUIC connection SSL object without a default stream +attached. +.IP \fBSSL_STREAM_TYPE_BIDI\fR 4 +.IX Item "SSL_STREAM_TYPE_BIDI" +The SSL object is a non\-QUIC SSL object, or is a QUIC stream object (or QUIC +connection SSL object with a default stream attached), and that stream is a +bidirectional QUIC stream. +.IP \fBSSL_STREAM_TYPE_READ\fR 4 +.IX Item "SSL_STREAM_TYPE_READ" +The SSL object is a QUIC stream object (or QUIC connection SSL object with a +default stream attached), and that stream is a unidirectional QUIC stream which +was initiated by the remote peer; thus, it can be read from, but not written to. +.IP \fBSSL_STREAM_TYPE_WRITE\fR 4 +.IX Item "SSL_STREAM_TYPE_WRITE" +The SSL object is a QUIC stream object (or QUIC connection SSL object with a +default stream attached), and that stream is a unidirectional QUIC stream which +was initiated by the local application; thus, it can be written to, but not read +from. +.PP +The \fBSSL_is_stream_local()\fR function determines whether a stream was locally +created. +.SH NOTES +.IX Header "NOTES" +While QUICv1 assigns specific meaning to the low two bits of a QUIC stream ID, +QUIC stream IDs in future versions of QUIC are not required to have the same +semantics. Do not determine stream properties using these bits. Instead, use +\&\fBSSL_get_stream_type()\fR to determine the stream type and \fBSSL_get_stream_is_local()\fR +to determine the stream initiator. +.PP +The \fBSSL_get_stream_type()\fR identifies the type of a QUIC stream based on its +identity, and does not indicate whether an operation can currently be +successfully performed on a stream. For example, you might locally initiate a +unidirectional stream, write to it, and then conclude the stream using +\&\fBSSL_stream_conclude\fR\|(3), meaning that it can no longer be written to, but +\&\fBSSL_get_stream_type()\fR would still return \fBSSL_STREAM_TYPE_WRITE\fR. The value +returned by \fBSSL_get_stream_type()\fR does not vary over the lifespan of a stream. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_stream_id()\fR returns a QUIC stream ID, or \fBUINT64_MAX\fR if called on an +SSL object which is not a QUIC SSL object, or if called on a QUIC connection SSL +object without a default stream attached. Note that valid QUIC stream IDs are +always below 2**62. +.PP +\&\fBSSL_get_stream_type()\fR returns one of the \fBSSL_STREAM_TYPE\fR values. +.PP +\&\fBSSL_is_stream_local()\fR returns 1 if called on a QUIC stream SSL object which +represents a stream which was locally initiated. It returns 0 if called on a +QUIC stream SSL object which represents a stream which was remotely initiated by +a peer, and \-1 if called on any other kind of SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_stream_read_state.3 b/static/netbsd/man3/SSL_get_stream_read_state.3 new file mode 100644 index 00000000..4ec5e818 --- /dev/null +++ b/static/netbsd/man3/SSL_get_stream_read_state.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: SSL_get_stream_read_state.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_stream_read_state 3" +.TH SSL_get_stream_read_state 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_stream_read_state, SSL_get_stream_write_state, +SSL_get_stream_read_error_code, SSL_get_stream_write_error_code, +SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR, +SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL, +SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED \- get QUIC stream +state +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_STREAM_STATE_NONE +\& #define SSL_STREAM_STATE_OK +\& #define SSL_STREAM_STATE_WRONG_DIR +\& #define SSL_STREAM_STATE_FINISHED +\& #define SSL_STREAM_STATE_RESET_LOCAL +\& #define SSL_STREAM_STATE_RESET_REMOTE +\& #define SSL_STREAM_STATE_CONN_CLOSED +\& +\& int SSL_get_stream_read_state(SSL *ssl); +\& int SSL_get_stream_write_state(SSL *ssl); +\& +\& int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code); +\& int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_stream_read_state()\fR and \fBSSL_get_stream_write_state()\fR retrieve the +overall state of the receiving and sending parts of a QUIC stream, respectively. +.PP +They both return one of the following values: +.IP \fBSSL_STREAM_STATE_NONE\fR 4 +.IX Item "SSL_STREAM_STATE_NONE" +This value is returned if called on a non\-QUIC SSL object, or on a QUIC +connection SSL object without a default stream attached. +.IP \fBSSL_STREAM_STATE_OK\fR 4 +.IX Item "SSL_STREAM_STATE_OK" +This value is returned on a stream which has not been concluded and remains +healthy. +.IP \fBSSL_STREAM_STATE_WRONG_DIR\fR 4 +.IX Item "SSL_STREAM_STATE_WRONG_DIR" +This value is returned if \fBSSL_get_stream_read_state()\fR is called on a +locally\-initiated (and thus send\-only) unidirectional stream, or, conversely, if +\&\fBSSL_get_stream_write_state()\fR is called on a remotely\-initiated (and thus +receive\-only) unidirectional stream. +.IP \fBSSL_STREAM_STATE_FINISHED\fR 4 +.IX Item "SSL_STREAM_STATE_FINISHED" +For \fBSSL_get_stream_read_state()\fR, this value is returned when the remote peer has +signalled the end of the receiving part of the stream. Note that there may still +be residual data available to read via \fBSSL_read\fR\|(3) when this state is +returned. +.Sp +For \fBSSL_get_stream_write_state()\fR, this value is returned when the local +application has concluded the stream using \fBSSL_stream_conclude\fR\|(3). Future +\&\fBSSL_write\fR\|(3) calls will not succeed. +.IP \fBSSL_STREAM_STATE_RESET_LOCAL\fR 4 +.IX Item "SSL_STREAM_STATE_RESET_LOCAL" +This value is returned when the applicable stream part was reset by the local +application. +.Sp +For \fBSSL_get_stream_read_state()\fR, this means that the receiving part of the +stream was aborted using a locally transmitted QUIC \fBSTOP_SENDING\fR frame. It +may or may not still be possible to obtain any residual data which remains to be +read by calling \fBSSL_read\fR\|(3). +.Sp +For \fBSSL_get_stream_write_state()\fR, this means that the sending part of the stream +was aborted, for example because the application called \fBSSL_stream_reset\fR\|(3), +or because a QUIC stream SSL object with an un\-concluded sending part was freed +using \fBSSL_free\fR\|(3). Calls to \fBSSL_write\fR\|(3) will fail. +.Sp +When this value is returned, the application error code which was signalled can +be obtained by calling \fBSSL_get_stream_read_error_code()\fR or +\&\fBSSL_get_stream_write_error_code()\fR as appropriate. +.IP \fBSSL_STREAM_STATE_RESET_REMOTE\fR 4 +.IX Item "SSL_STREAM_STATE_RESET_REMOTE" +This value is returned when the applicable stream part was reset by the remote +peer. +.Sp +For \fBSSL_get_stream_read_state()\fR, this means that the peer sent a QUIC +\&\fBRESET_STREAM\fR frame for the receiving part of the stream; the receiving part +of the stream was logically aborted by the peer. +.Sp +For \fBSSL_get_stream_write_state()\fR, this means that the peer sent a QUIC +\&\fBSTOP_SENDING\fR frame for the sending part of the stream; the peer has indicated +that it does not wish to receive further data on the sending part of the stream. +Calls to \fBSSL_write\fR\|(3) will fail. +.Sp +When this value is returned, the application error code which was signalled can +be obtained by calling \fBSSL_get_stream_read_error_code()\fR or +\&\fBSSL_get_stream_write_error_code()\fR as appropriate. +.IP \fBSSL_STREAM_STATE_CONN_CLOSED\fR 4 +.IX Item "SSL_STREAM_STATE_CONN_CLOSED" +The QUIC connection to which the stream belongs was closed. You can obtain +information about the circumstances of this closure using +\&\fBSSL_get_conn_close_info\fR\|(3). There may still be residual data available to +read via \fBSSL_read\fR\|(3) when this state is returned. Calls to \fBSSL_write\fR\|(3) +will fail. \fBSSL_get_stream_read_state()\fR will return this state if and only if +\&\fBSSL_get_stream_write_state()\fR will also return this state. +.PP +\&\fBSSL_get_stream_read_error_code()\fR and \fBSSL_get_stream_write_error_code()\fR provide +the application error code which was signalled during non\-normal termination of +the receiving or sending parts of a stream, respectively. On success, the +application error code is written to \fI*app_error_code\fR. +.SH NOTES +.IX Header "NOTES" +If a QUIC connection is closed, the stream state for all streams transitions to +\&\fBSSL_STREAM_STATE_CONN_CLOSED\fR, but no application error code can be retrieved +using \fBSSL_get_stream_read_error_code()\fR or \fBSSL_get_stream_write_error_code()\fR, as +the QUIC connection closure process does not cause an application error code to +be associated with each individual stream still existing at the time of +connection closure. However, you can obtain the overall error code associated +with the connection closure using \fBSSL_get_conn_close_info\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_stream_read_state()\fR and \fBSSL_get_stream_write_state()\fR return one of the +\&\fBSSL_STREAM_STATE\fR values. If called on a non\-QUIC SSL object, or a QUIC +connection SSL object without a default stream, \fBSSL_STREAM_STATE_NONE\fR is +returned. +.PP +\&\fBSSL_get_stream_read_error_code()\fR and \fBSSL_get_stream_write_error_code()\fR return 1 +on success and 0 if the stream was terminated normally. They return \-1 on error, +for example if the stream is still healthy, was still healthy at the time of +connection closure, if called on a stream for which the respective stream part +does not exist (e.g. on a unidirectional stream), or if called on a non\-QUIC +object or a QUIC connection SSL object without a default stream attached. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_stream_conclude\fR\|(3), \fBSSL_stream_reset\fR\|(3), \fBSSL_new_stream\fR\|(3), +\&\fBSSL_accept_stream\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_value_uint.3 b/static/netbsd/man3/SSL_get_value_uint.3 new file mode 100644 index 00000000..4e778ff9 --- /dev/null +++ b/static/netbsd/man3/SSL_get_value_uint.3 @@ -0,0 +1,376 @@ +.\" $NetBSD: SSL_get_value_uint.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_value_uint 3" +.TH SSL_get_value_uint 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_value_uint, SSL_set_value_uint, SSL_get_generic_value_uint, +SSL_set_generic_value_uint, SSL_get_feature_request_uint, +SSL_set_feature_request_uint, SSL_get_feature_peer_request_uint, +SSL_get_feature_negotiated_uint, SSL_get_quic_stream_bidi_local_avail, +SSL_get_quic_stream_bidi_remote_avail, SSL_get_quic_stream_uni_local_avail, +SSL_get_quic_stream_uni_remote_avail, SSL_VALUE_CLASS_GENERIC, +SSL_VALUE_CLASS_FEATURE_REQUEST, SSL_VALUE_CLASS_FEATURE_PEER_REQUEST, +SSL_VALUE_CLASS_FEATURE_NEGOTIATED, SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL, +SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL, SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL, +SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, SSL_VALUE_QUIC_IDLE_TIMEOUT, +SSL_VALUE_EVENT_HANDLING_MODE, +SSL_VALUE_EVENT_HANDLING_MODE_INHERIT, +SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT, +SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT, +SSL_get_event_handling_mode, +SSL_set_event_handling_mode, +SSL_VALUE_STREAM_WRITE_BUF_SIZE, +SSL_get_stream_write_buf_size, +SSL_VALUE_STREAM_WRITE_BUF_USED, +SSL_get_stream_write_buf_used, +SSL_VALUE_STREAM_WRITE_BUF_AVAIL, +SSL_get_stream_write_buf_avail \- +manage negotiable features and configuration values for an SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_get_value_uint(SSL *ssl, uint32_t class_, uint32_t id, +\& uint64_t *value); +\& int SSL_set_value_uint(SSL *ssl, uint32_t class_, uint32_t id, +\& uint64_t value); +\& +\& #define SSL_VALUE_CLASS_GENERIC +\& #define SSL_VALUE_CLASS_FEATURE_REQUEST +\& #define SSL_VALUE_CLASS_FEATURE_PEER_REQUEST +\& #define SSL_VALUE_CLASS_FEATURE_NEGOTIATED +\& +\& #define SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL +\& #define SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL +\& #define SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL +\& #define SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL +\& #define SSL_VALUE_QUIC_IDLE_TIMEOUT +\& +\& #define SSL_VALUE_EVENT_HANDLING_MODE +\& #define SSL_VALUE_EVENT_HANDLING_MODE_INHERIT +\& #define SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT +\& #define SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT +\& +\& #define SSL_VALUE_STREAM_WRITE_BUF_SIZE +\& #define SSL_VALUE_STREAM_WRITE_BUF_USED +\& #define SSL_VALUE_STREAM_WRITE_BUF_AVAIL +.Ve +.PP +The following convenience macros can also be used: +.PP +.Vb 2 +\& int SSL_get_generic_value_uint(SSL *ssl, uint32_t id, uint64_t *value); +\& int SSL_set_generic_value_uint(SSL *ssl, uint32_t id, uint64_t value); +\& +\& int SSL_get_feature_request_uint(SSL *ssl, uint32_t id, uint64_t *value); +\& int SSL_set_feature_request_uint(SSL *ssl, uint32_t id, uint64_t value); +\& +\& int SSL_get_feature_peer_request_uint(SSL *ssl, uint32_t id, uint64_t *value); +\& int SSL_get_feature_negotiated_uint(SSL *ssl, uint32_t id, uint64_t *value); +\& +\& int SSL_get_quic_stream_bidi_local_avail(SSL *ssl, uint64_t *value); +\& int SSL_get_quic_stream_bidi_remote_avail(SSL *ssl, uint64_t *value); +\& int SSL_get_quic_stream_uni_local_avail(SSL *ssl, uint64_t *value); +\& int SSL_get_quic_stream_uni_remote_avail(SSL *ssl, uint64_t *value); +\& +\& int SSL_get_event_handling_mode(SSL *ssl, uint64_t *value); +\& int SSL_set_event_handling_mode(SSL *ssl, uint64_t value); +\& +\& int SSL_get_stream_write_buf_size(SSL *ssl, uint64_t *value); +\& int SSL_get_stream_write_buf_avail(SSL *ssl, uint64_t *value); +\& int SSL_get_stream_write_buf_used(SSL *ssl, uint64_t *value); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_value_uint()\fR and \fBSSL_set_value_uint()\fR provide access to configurable +parameters for a given SSL object. Amongst other things, they are used to +provide control over the feature negotiation process during establishment of a +connection, and access to statistics about that connection. +.PP +\&\fBSSL_get_value_uint()\fR and \fBSSL_set_value_uint()\fR get and set configurable values +within a given value class. The value classes are enumerated by +\&\fBSSL_VALUE_CLASS\fR and are as follows: +.IP \fBSSL_VALUE_CLASS_GENERIC\fR 4 +.IX Item "SSL_VALUE_CLASS_GENERIC" +Values in this class do not participate in the feature negotiation process. They +may represent connection parameters which do not participate in explicit +negotiation or provide connection statistics. Values in this class might be +read\-write or read\-only. +.Sp +You can access values in this class using the convenience macros +\&\fBSSL_get_generic_value_uint()\fR and \fBSSL_set_generic_value_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_REQUEST\fR 4 +.IX Item "SSL_VALUE_CLASS_FEATURE_REQUEST" +Values in this class are read\-write, and represent what the local party is +requesting during feature negotiation. Such a request will not necessarily be +honoured; see \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR. +.Sp +A value in this class may become read\-only in certain circumstances; for +example, after a connection has been established, for a value which cannot be +renegotiated after connection establishment. Setting a value in this class after +connection establishment represents a request for online renegotiation of the +specified feature. +.Sp +You can access values in this class using the convenience macros +\&\fBSSL_get_feature_request_uint()\fR and \fBSSL_set_feature_request_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_PEER_REQUEST\fR 4 +.IX Item "SSL_VALUE_CLASS_FEATURE_PEER_REQUEST" +Values in this value class are read\-only, and represent what was requested by a +peer during feature negotiation. Such a request has not necessarily been +honoured; see \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR. +.Sp +You can access values in this class using the convenience macro +\&\fBSSL_get_feature_peer_request_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR 4 +.IX Item "SSL_VALUE_CLASS_FEATURE_NEGOTIATED" +Values in this value class are read\-only, and represent the value which was +actually negotiated based on both local and peer input during feature +negotiation. This is the effective value in actual use. +.Sp +Attempting to read a value in this class will generally fail if the feature +negotiation process has not yet completed and the value is therefore currently +unknown, unless the nature of the feature in question causes a provisional value +to be used prior to completion of feature negotiation, in which case that value +may be returned. If an online (post\-handshake) renegotiation of a feature is +in progress, retrieving the negotiated value will continue to retrieve the +previous negotiated value until that process is completed. See the documentation +of specific values for full details of its behaviour. +.Sp +You can access values in this class using the convenience macro +\&\fBSSL_get_feature_negotiated_uint()\fR for brevity. +.SH "CONFIGURABLE VALUES FOR QUIC OBJECTS" +.IX Header "CONFIGURABLE VALUES FOR QUIC OBJECTS" +The following configurable values are supported for QUIC SSL objects. Whether a +value is supported for a QUIC connection SSL object or a QUIC stream SSL object +is indicated in the heading for each value. Values supported for QUIC stream SSL +objects are also supported on QUIC connection SSL objects if they have a default +stream attached. +.PP +\&\fBSSL_get_value()\fR does not cause internal event processing to occur unless the +documentation for a specific value specifies otherwise. +.IP "\fBSSL_VALUE_QUIC_IDLE_TIMEOUT\fR (connection object)" 4 +.IX Item "SSL_VALUE_QUIC_IDLE_TIMEOUT (connection object)" +Negotiated feature value. This configures the desired QUIC idle timeout in +milliseconds, where 0 represents a lack of an idle timeout. This feature can +only be configured prior to connection establishment and cannot be subsequently +changed. +.Sp +This release of OpenSSL uses a default value of 30 seconds. This default value +may change between releases of OpenSSL. +.IP "\fBSSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL\fR (connection object)" 4 +.IX Item "SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL (connection object)" +Generic read\-only statistical value. The number of bidirectional, +locally\-initiated streams available to be created (but not yet created). For +example, a value of 100 would mean that \fBSSL_new_stream\fR\|(3) could be called 100 +times to create 100 bidirectional streams before \fBSSL_new_stream\fR\|(3) would +block or fail due to backpressure. +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_bidi_local_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL\fR (connection object)" 4 +.IX Item "SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL (connection object)" +As above, but provides the number of unidirectional, locally\-initiated streams +available to be created (but not yet created). +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_uni_local_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL\fR (connection object)" 4 +.IX Item "SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL (connection object)" +As above, but provides the number of bidirectional, remotely\-initiated streams +available to be created (but not yet created) by the peer. This represents the +number of streams the local endpoint has authorised the peer to create in terms +of QUIC stream creation flow control. +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_bidi_remote_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL\fR (connection object)" 4 +.IX Item "SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL (connection object)" +As above, but provides the number of unidirectional, remotely\-initiated streams +available to be created (but not yet created). +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_uni_remote_avail()\fR. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE\fR (connection or stream object)" 4 +.IX Item "SSL_VALUE_EVENT_HANDLING_MODE (connection or stream object)" +Generic value. This is an integer value which takes one of the following values, +and determines the event handling mode in use: +.RS 4 +.IP \fBSSL_VALUE_EVENT_HANDLING_MODE_INHERIT\fR 4 +.IX Item "SSL_VALUE_EVENT_HANDLING_MODE_INHERIT" +When set, the event handling mode used is inherited from the value set on the +parent connection (for a stream), or, for a connection, defaults to the implicit +event handling model. +.Sp +When a new connection is created, or a new stream is created or accepted, it +defaults to this setting. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT\fR (Implicit event handling)" 4 +.IX Item "SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT (Implicit event handling)" +If set to this value, the implicit event handling model is used. Under this +model, QUIC objects will automatically perform background event processing +(equivalent to a call to \fBSSL_handle_events\fR\|(3)) when calls to I/O functions +such as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) are made on a QUIC SSL object. +This helps to maintain the health of the QUIC connection and ensures that +incoming datagrams and timeout events are processed. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT\fR (Explicit event handling)" 4 +.IX Item "SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT (Explicit event handling)" +If set to this value, the explicit event handling model is used. Under this +model, \fBnonblocking\fR calls to I/O functions such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3) do not result in the automatic processing of QUIC events. Any +new incoming network traffic is not handled; no new outgoing network traffic is +generated, and pending timeout events are not processed. This allows an +application to obtain greater control over the circumstances in which QUIC event +processing occurs. If this event handling model is used, it is the application\*(Aqs +responsibility to call \fBSSL_handle_events\fR\|(3) as and when called for by the +QUIC implementation; see the \fBSSL_get_rpoll_descriptor\fR\|(3) man page for more +information. +.Sp +Selecting this model does not affect the operation of blocking I/O calls, which +will continue to use the implicit event handling model. Therefore, applications +using this model will generally want to disable blocking operation using +\&\fBSSL_set_blocking_mode\fR\|(3). +.RE +.RS 4 +.Sp +Can be configured using the convenience macros \fBSSL_get_event_handling_mode()\fR and +\&\fBSSL_set_event_handling_mode()\fR. +.Sp +A call to \fBSSL_set_value_uint()\fR which causes this value to switch back to the +implicit event handling model does not in itself cause implicit event handling +to occur; such handling will occur on the next I/O API call. Equally, a call to +\&\fBSSL_set_value_uint()\fR which causes this value to switch to the explicit event +handling model will not cause event handling to occur before making that +transition. +.Sp +This value controls whether implicit event handling occurs when making an I/O +API call on the SSL object it is set on. However, event processing is not +confined to state which relates to only that object. For example, if you +configure explicit event handling on QUIC stream SSL object "A" and configure +implicit event handling on QUIC stream SSL object "B", a call to an I/O function +on "B" may result in state changes to "A". In other words, if event handling +does happen as a result of an API call to an object related to a connection, +processing of background events (for example, received QUIC network traffic) may +also affect the state of any other object related to a connection. +.RE +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_SIZE\fR (stream object)" 4 +.IX Item "SSL_VALUE_STREAM_WRITE_BUF_SIZE (stream object)" +Generic read\-only statistical value. The size of the write buffer allocated to +hold data written to a stream with \fBSSL_write_ex\fR\|(3) until it is transmitted +and subsequently acknowledged by the peer. This value may change at any time, as +buffer sizes are optimised in response to network conditions to optimise +throughput. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_size()\fR. +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_USED\fR (stream object)" 4 +.IX Item "SSL_VALUE_STREAM_WRITE_BUF_USED (stream object)" +Generic read\-only statistical value. The number of bytes currently consumed +in the write buffer which have yet to be acknowledged by the peer. Successful +calls to \fBSSL_write_ex\fR\|(3) which accept data cause this number to increase. +This number will then decrease as data is acknowledged by the peer. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_used()\fR. +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_AVAIL\fR (stream object)" 4 +.IX Item "SSL_VALUE_STREAM_WRITE_BUF_AVAIL (stream object)" +Generic read\-only statistical value. The number of bytes available in the write +buffer which have yet to be consumed by calls to \fBSSL_write_ex\fR\|(3). Successful +calls to \fBSSL_write_ex\fR\|(3) which accept data cause this number to decrease. +This number will increase as data is acknowledged by the peer. It may also +change if the buffer is resized automatically to optimise throughput. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_avail()\fR. +.PP +No configurable values are currently defined for non\-QUIC SSL objects. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success or 0 on failure. This function can fail for a number of +reasons: +.IP \(bu 4 +An argument is invalid (e.g. NULL pointer or invalid class). +.IP \(bu 4 +The given value is not supported by the SSL object on which it was called. +.IP \(bu 4 +The given operation (get or set) is not supported by the specified +configurable value. +.IP \(bu 4 +You are trying to modify the given value and the value is not modifiable at this +time. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_ctrl\fR\|(3), \fBSSL_get_accept_stream_queue_len\fR\|(3), +\&\fBSSL_get_stream_read_state\fR\|(3), \fBSSL_get_stream_write_state\fR\|(3), +\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_stream_write_error_code\fR\|(3), +\&\fBSSL_set_default_stream_mode\fR\|(3), \fBSSL_set_incoming_stream_policy\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_verify_result.3 b/static/netbsd/man3/SSL_get_verify_result.3 new file mode 100644 index 00000000..d70095ac --- /dev/null +++ b/static/netbsd/man3/SSL_get_verify_result.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: SSL_get_verify_result.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_verify_result 3" +.TH SSL_get_verify_result 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_verify_result \- get result of peer certificate verification +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long SSL_get_verify_result(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_verify_result()\fR returns the result of the verification of the +X509 certificate presented by the peer, if any. \fIssl\fR \fBMUST NOT\fR be NULL. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_get_verify_result()\fR can only return one error code while the verification +of a certificate can fail because of many reasons at the same time. Only +the last verification error that occurred during the processing is available +from \fBSSL_get_verify_result()\fR. +.PP +Sometimes there can be a sequence of errors leading to the verification +failure as reported by \fBSSL_get_verify_result()\fR. +To get the errors, it is necessary to setup a verify callback via +\&\fBSSL_CTX_set_verify\fR\|(3) or \fBSSL_set_verify\fR\|(3) and retrieve the errors +from the error stack there, because once \fBSSL_connect\fR\|(3) returns, +these errors may no longer be available. +.PP +The verification result is part of the established session and is restored +when a session is reused. +.SH BUGS +.IX Header "BUGS" +If no peer certificate was presented, the returned result code is +X509_V_OK. This is because no verification error occurred, it does however +not indicate success. \fBSSL_get_verify_result()\fR is only useful in connection +with \fBSSL_get_peer_certificate\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can currently occur: +.IP X509_V_OK 4 +.IX Item "X509_V_OK" +The verification succeeded or no peer certificate was presented. +.IP "Any other value" 4 +.IX Item "Any other value" +Documented in \fBopenssl\-verify\fR\|(1). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_set_verify_result\fR\|(3), +\&\fBSSL_get_peer_certificate\fR\|(3), +\&\fBopenssl\-verify\fR\|(1) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_get_version.3 b/static/netbsd/man3/SSL_get_version.3 new file mode 100644 index 00000000..7579225c --- /dev/null +++ b/static/netbsd/man3/SSL_get_version.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: SSL_get_version.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_get_version 3" +.TH SSL_get_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_client_version, SSL_get_version, SSL_is_dtls, SSL_is_tls, SSL_is_quic, +SSL_version \- get the protocol information of a connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_client_version(const SSL *s); +\& +\& const char *SSL_get_version(const SSL *ssl); +\& +\& int SSL_is_dtls(const SSL *ssl); +\& int SSL_is_tls(const SSL *ssl); +\& int SSL_is_quic(const SSL *ssl); +\& +\& int SSL_version(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +For SSL, TLS and DTLS protocols \fBSSL_client_version()\fR returns the numeric +protocol version advertised by the client in the legacy_version field of the +ClientHello when initiating the connection. Note that, for TLS, this value +will never indicate a version greater than TLSv1.2 even if TLSv1.3 is +subsequently negotiated. For QUIC connections it returns OSSL_QUIC1_VERSION. +.PP +\&\fBSSL_get_version()\fR returns the name of the protocol used for the connection. +\&\fBSSL_version()\fR returns the numeric protocol version used for the connection. +They should only be called after the initial handshake has been completed. +Prior to that the results returned from these functions may be unreliable. +.PP +\&\fBSSL_is_dtls()\fR returns 1 if the connection is using DTLS or 0 if not. +.PP +\&\fBSSL_is_tls()\fR returns 1 if the connection is using SSL/TLS or 0 if not. +.PP +\&\fBSSL_is_quic()\fR returns 1 if the connection is using QUIC or 0 if not. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_version()\fR returns one of the following strings: +.IP SSLv3 4 +.IX Item "SSLv3" +The connection uses the SSLv3 protocol. +.IP TLSv1 4 +.IX Item "TLSv1" +The connection uses the TLSv1.0 protocol. +.IP TLSv1.1 4 +.IX Item "TLSv1.1" +The connection uses the TLSv1.1 protocol. +.IP TLSv1.2 4 +.IX Item "TLSv1.2" +The connection uses the TLSv1.2 protocol. +.IP TLSv1.3 4 +.IX Item "TLSv1.3" +The connection uses the TLSv1.3 protocol. +.IP DTLSv0.9 4 +.IX Item "DTLSv0.9" +The connection uses an obsolete pre\-standardisation DTLS protocol +.IP DTLSv1 4 +.IX Item "DTLSv1" +The connection uses the DTLSv1 protocol +.IP DTLSv1.2 4 +.IX Item "DTLSv1.2" +The connection uses the DTLSv1.2 protocol +.IP QUICv1 4 +.IX Item "QUICv1" +The connection uses the QUICv1 protocol. +.IP unknown 4 +.IX Item "unknown" +This indicates an unknown protocol version. +.PP +\&\fBSSL_version()\fR and \fBSSL_client_version()\fR return an integer which could include any +of the following: +.IP SSL3_VERSION 4 +.IX Item "SSL3_VERSION" +The connection uses the SSLv3 protocol. +.IP TLS1_VERSION 4 +.IX Item "TLS1_VERSION" +The connection uses the TLSv1.0 protocol. +.IP TLS1_1_VERSION 4 +.IX Item "TLS1_1_VERSION" +The connection uses the TLSv1.1 protocol. +.IP TLS1_2_VERSION 4 +.IX Item "TLS1_2_VERSION" +The connection uses the TLSv1.2 protocol. +.IP TLS1_3_VERSION 4 +.IX Item "TLS1_3_VERSION" +The connection uses the TLSv1.3 protocol (never returned for +\&\fBSSL_client_version()\fR). +.IP DTLS1_BAD_VER 4 +.IX Item "DTLS1_BAD_VER" +The connection uses an obsolete pre\-standardisation DTLS protocol +.IP DTLS1_VERSION 4 +.IX Item "DTLS1_VERSION" +The connection uses the DTLSv1 protocol +.IP DTLS1_2_VERSION 4 +.IX Item "DTLS1_2_VERSION" +The connection uses the DTLSv1.2 protocol +.IP OSSL_QUIC1_VERSION 4 +.IX Item "OSSL_QUIC1_VERSION" +The connection uses the QUICv1 protocol. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_is_dtls()\fR function was added in OpenSSL 1.1.0. The \fBSSL_is_tls()\fR and +\&\fBSSL_is_quic()\fR functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_group_to_name.3 b/static/netbsd/man3/SSL_group_to_name.3 new file mode 100644 index 00000000..49f42a6d --- /dev/null +++ b/static/netbsd/man3/SSL_group_to_name.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: SSL_group_to_name.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_group_to_name 3" +.TH SSL_group_to_name 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_group_to_name \- get name of group +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_group_to_name(SSL *ssl, int id); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_group_to_name()\fR is used to retrieve the TLS group name +associated with a given TLS group ID, as registered via built\-in +or external providers and as returned by a call to \fBSSL_get1_groups()\fR +or \fBSSL_get_shared_group()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If non\-NULL, \fBSSL_group_to_name()\fR returns the TLS group name +corresponding to the given \fIid\fR as a NUL\-terminated string. +If \fBSSL_group_to_name()\fR returns NULL, an error occurred; possibly no +corresponding tlsname was registered during provider initialisation. +.PP +Note that the return value is valid only during the lifetime of the +SSL object \fIssl\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_handle_events.3 b/static/netbsd/man3/SSL_handle_events.3 new file mode 100644 index 00000000..aa293125 --- /dev/null +++ b/static/netbsd/man3/SSL_handle_events.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: SSL_handle_events.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_handle_events 3" +.TH SSL_handle_events 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_handle_events \- advance asynchronous state machine and perform network I/O +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_handle_events(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_handle_events()\fR performs any internal processing which is due on an SSL object. The +exact operations performed by \fBSSL_handle_events()\fR vary depending on what kind of protocol +is being used with the given SSL object. For example, \fBSSL_handle_events()\fR may handle +timeout events which have become due, or may attempt, to the extent currently +possible, to perform network I/O operations on one of the BIOs underlying the +SSL object. +.PP +The primary use case for \fBSSL_handle_events()\fR is to allow an application which uses +OpenSSL in nonblocking mode to give OpenSSL an opportunity to handle timer +events, or to respond to the availability of new data to be read from an +underlying BIO, or to respond to the opportunity to write pending data to an +underlying BIO. +.PP +\&\fBSSL_handle_events()\fR can be used only with the following types of SSL object: +.IP "DTLS SSL objects" 4 +.IX Item "DTLS SSL objects" +Using \fBSSL_handle_events()\fR on an SSL object being used with a DTLS method allows timeout +events to be handled properly. This is equivalent to a call to +\&\fBDTLSv1_handle_timeout\fR\|(3). Since \fBSSL_handle_events()\fR handles a superset of the use +cases of \fBDTLSv1_handle_timeout\fR\|(3), it should be preferred for new +applications which do not require support for OpenSSL 3.1 or older. +.Sp +When using DTLS, an application must call \fBSSL_handle_events()\fR as indicated by +calls to \fBSSL_get_event_timeout\fR\|(3); event handling is not performed +automatically by calls to other SSL functions such as \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3). Note that this is different to QUIC which also performs event +handling implicitly; see below. +.IP "QUIC connection SSL objects" 4 +.IX Item "QUIC connection SSL objects" +Using \fBSSL_handle_events()\fR on an SSL object which represents a QUIC connection allows +timeout events to be handled properly, as well as incoming network data to be +processed, and queued outgoing network data to be written, if the underlying BIO +has the capacity to accept it. +.Sp +Ordinarily, when an application uses an SSL object in blocking mode, it does not +need to call \fBSSL_handle_events()\fR because OpenSSL performs ticking internally on an +automatic basis. However, if an application uses a QUIC connection in +nonblocking mode, it must at a minimum ensure that \fBSSL_handle_events()\fR is called +periodically to allow timeout events to be handled. An application can find out +when it next needs to call \fBSSL_handle_events()\fR for this purpose (if at all) by calling +\&\fBSSL_get_event_timeout\fR\|(3). +.Sp +Calling \fBSSL_handle_events()\fR on a QUIC connection SSL object being used in blocking mode +is not necessary unless no I/O calls (such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3)) +will be made to the object for a substantial period of time. So long as at least +one call to the SSL object is blocking, no such call is needed. However, +\&\fBSSL_handle_events()\fR may optionally be used on a QUIC connection object if desired. +.Sp +With the thread\-assisted mode of operation \fBOSSL_QUIC_client_thread_method\fR\|(3) +it is unnecessary to call \fBSSL_handle_events()\fR as the assist thread handles the QUIC +connection events. +.PP +Calling \fBSSL_handle_events()\fR on any other kind of SSL object is a no\-op. This is +considered a success case. +.PP +Note that \fBSSL_handle_events()\fR supersedes the older \fBDTLSv1_handle_timeout\fR\|(3) function +for all use cases. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_event_timeout\fR\|(3), \fBDTLSv1_handle_timeout\fR\|(3), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_handle_events()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_in_init.3 b/static/netbsd/man3/SSL_in_init.3 new file mode 100644 index 00000000..72658142 --- /dev/null +++ b/static/netbsd/man3/SSL_in_init.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: SSL_in_init.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_in_init 3" +.TH SSL_in_init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_in_before, +SSL_in_init, +SSL_is_init_finished, +SSL_in_connect_init, +SSL_in_accept_init, +SSL_get_state +\&\- retrieve information about the handshake state machine +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_in_init(const SSL *s); +\& int SSL_in_before(const SSL *s); +\& int SSL_is_init_finished(const SSL *s); +\& +\& int SSL_in_connect_init(SSL *s); +\& int SSL_in_accept_init(SSL *s); +\& +\& OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_in_init()\fR returns 1 if the SSL/TLS state machine is currently processing or +awaiting handshake messages, or 0 otherwise. +.PP +\&\fBSSL_in_before()\fR returns 1 if no SSL/TLS handshake has yet been initiated, or 0 +otherwise. +.PP +\&\fBSSL_is_init_finished()\fR returns 1 if the SSL/TLS connection is in a state where +fully protected application data can be transferred or 0 otherwise. +.PP +Note that in some circumstances (such as when early data is being transferred) +\&\fBSSL_in_init()\fR, \fBSSL_in_before()\fR and \fBSSL_is_init_finished()\fR can all return 0. +.PP +\&\fBs\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_in_connect_init()\fR returns 1 if \fBs\fR is acting as a client and \fBSSL_in_init()\fR +would return 1, or 0 otherwise. +.PP +\&\fBSSL_in_accept_init()\fR returns 1 if \fBs\fR is acting as a server and \fBSSL_in_init()\fR +would return 1, or 0 otherwise. +.PP +\&\fBSSL_in_connect_init()\fR and \fBSSL_in_accept_init()\fR are implemented as macros. +.PP +\&\fBSSL_get_state()\fR returns a value indicating the current state of the handshake +state machine. OSSL_HANDSHAKE_STATE is an enumerated type where each value +indicates a discrete state machine state. Note that future versions of OpenSSL +may define more states so applications should expect to receive unrecognised +state values. The naming format is made up of a number of elements as follows: +.PP +\&\fBprotocol\fR_ST_\fBrole\fR_\fBmessage\fR +.PP +\&\fBprotocol\fR is one of TLS or DTLS. DTLS is used where a state is specific to the +DTLS protocol. Otherwise TLS is used. +.PP +\&\fBrole\fR is one of CR, CW, SR or SW to indicate "client reading", +"client writing", "server reading" or "server writing" respectively. +.PP +\&\fBmessage\fR is the name of a handshake message that is being or has been sent, or +is being or has been processed. +.PP +Additionally there are some special states that do not conform to the above +format. These are: +.IP TLS_ST_BEFORE 4 +.IX Item "TLS_ST_BEFORE" +No handshake messages have yet been been sent or received. +.IP TLS_ST_OK 4 +.IX Item "TLS_ST_OK" +Handshake message sending/processing has completed. +.IP TLS_ST_EARLY_DATA 4 +.IX Item "TLS_ST_EARLY_DATA" +Early data is being processed +.IP TLS_ST_PENDING_EARLY_DATA_END 4 +.IX Item "TLS_ST_PENDING_EARLY_DATA_END" +Awaiting the end of early data processing +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_in_init()\fR, \fBSSL_in_before()\fR, \fBSSL_is_init_finished()\fR, \fBSSL_in_connect_init()\fR +and \fBSSL_in_accept_init()\fR return values as indicated above. +.PP +\&\fBSSL_get_state()\fR returns the current handshake state. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_read_early_data\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_inject_net_dgram.3 b/static/netbsd/man3/SSL_inject_net_dgram.3 new file mode 100644 index 00000000..c473b4cb --- /dev/null +++ b/static/netbsd/man3/SSL_inject_net_dgram.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: SSL_inject_net_dgram.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_inject_net_dgram 3" +.TH SSL_inject_net_dgram 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_inject_net_dgram \- inject a datagram as though received from the network +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_inject_net_dgram(SSL *s, const unsigned char *buf, +\& size_t buf_len, +\& const BIO_ADDR *peer, +\& const BIO_ADDR *local); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This function can be used to inject a datagram payload to a QUIC connection SSL +object. The payload is processed as though it was received from the network. +This function can be used for debugging purposes or to allow datagrams to be fed +to QUIC from alternative sources. +.PP +\&\fIbuf\fR is required and must point to a datagram payload to inject. \fIbuf_len\fR is +the length of the buffer in bytes. The buffer is copied and need not remain +valid after this function returns. +.PP +\&\fIpeer\fR and \fIlocal\fR are optional values pointing to \fBBIO_ADDR\fR structures +describing the remote and local UDP endpoint addresses for the packet. Though +the injected packet was not actually received from the network directly by +OpenSSL, the packet will be processed as though the received datagram had the +given addresses. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success or 0 on failure. This function always fails if called +on an SSL object which is not a QUIC connection SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_QUIC_client_method\fR\|(3), \fBSSL_handle_events\fR\|(3), \fBSSL_set_blocking_mode\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBSSL_inject_net_dgram()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_key_update.3 b/static/netbsd/man3/SSL_key_update.3 new file mode 100644 index 00000000..8f4a28c2 --- /dev/null +++ b/static/netbsd/man3/SSL_key_update.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: SSL_key_update.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_key_update 3" +.TH SSL_key_update 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_key_update, +SSL_get_key_update_type, +SSL_renegotiate, +SSL_renegotiate_abbreviated, +SSL_renegotiate_pending +\&\- initiate and obtain information about updating connection keys +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_key_update(SSL *s, int updatetype); +\& int SSL_get_key_update_type(const SSL *s); +\& +\& int SSL_renegotiate(SSL *s); +\& int SSL_renegotiate_abbreviated(SSL *s); +\& int SSL_renegotiate_pending(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_key_update()\fR schedules an update of the keys for the current TLS connection. +If the \fBupdatetype\fR parameter is set to \fBSSL_KEY_UPDATE_NOT_REQUESTED\fR then +the sending keys for this connection will be updated and the peer will be +informed of the change. If the \fBupdatetype\fR parameter is set to +\&\fBSSL_KEY_UPDATE_REQUESTED\fR then the sending keys for this connection will be +updated and the peer will be informed of the change along with a request for the +peer to additionally update its sending keys. It is an error if \fBupdatetype\fR is +set to \fBSSL_KEY_UPDATE_NONE\fR. +.PP +\&\fBSSL_key_update()\fR must only be called after the initial handshake has been +completed and TLSv1.3 or QUIC has been negotiated, at the same time, the +application needs to ensure that the writing of data has been completed. The key +update will not take place until the next time an IO operation such as +\&\fBSSL_read_ex()\fR or \fBSSL_write_ex()\fR takes place on the connection. Alternatively +\&\fBSSL_do_handshake()\fR can be called to force the update to take place immediately. +.PP +\&\fBSSL_get_key_update_type()\fR can be used to determine whether a key update +operation has been scheduled but not yet performed. The type of the pending key +update operation will be returned if there is one, or SSL_KEY_UPDATE_NONE +otherwise. +.PP +\&\fBSSL_renegotiate()\fR and \fBSSL_renegotiate_abbreviated()\fR should only be called for +connections that have negotiated TLSv1.2 or less. Calling them on any other +connection will result in an error. +.PP +When called from the client side, \fBSSL_renegotiate()\fR schedules a completely new +handshake over an existing SSL/TLS connection. The next time an IO operation +such as \fBSSL_read_ex()\fR or \fBSSL_write_ex()\fR takes place on the connection a check +will be performed to confirm that it is a suitable time to start a +renegotiation. If so, then it will be initiated immediately. OpenSSL will not +attempt to resume any session associated with the connection in the new +handshake. Note that some servers will respond to reneogitation attempts with +a "no_renegotiation" alert. An OpenSSL will immediately fail the connection in +this case. +.PP +When called from the client side, \fBSSL_renegotiate_abbreviated()\fR works in the +same was as \fBSSL_renegotiate()\fR except that OpenSSL will attempt to resume the +session associated with the current connection in the new handshake. +.PP +When called from the server side, \fBSSL_renegotiate()\fR and +\&\fBSSL_renegotiate_abbreviated()\fR behave identically. They both schedule a request +for a new handshake to be sent to the client. The next time an IO operation is +performed then the same checks as on the client side are performed and then, if +appropriate, the request is sent. The client may or may not respond with a new +handshake and it may or may not attempt to resume an existing session. If +a new handshake is started then this will be handled transparently by calling +any OpenSSL IO function. +.PP +If an OpenSSL client receives a renegotiation request from a server then again +this will be handled transparently through calling any OpenSSL IO function. For +a TLS connection the client will attempt to resume the current session in the +new handshake. For historical reasons, DTLS clients will not attempt to resume +the session in the new handshake. +.PP +The \fBSSL_renegotiate_pending()\fR function returns 1 if a renegotiation or +renegotiation request has been scheduled but not yet acted on, or 0 otherwise. +.SH "USAGE WITH QUIC" +.IX Header "USAGE WITH QUIC" +\&\fBSSL_key_update()\fR can also be used to perform a key update when using QUIC. The +function must be called on a QUIC connection SSL object. This is normally done +automatically when needed. Since a locally initiated QUIC key update always +causes a peer to also trigger a key update, passing +\&\fBSSL_KEY_UPDATE_NOT_REQUESTED\fR as \fBupdatetype\fR has the same effect as passing +\&\fBSSL_KEY_UPDATE_REQUESTED\fR. +.PP +The QUIC connection must have been fully established before a key update can be +performed, and other QUIC protocol rules govern how frequently QUIC key update +can be performed. \fBSSL_key_update()\fR will fail if these requirements are not met. +.PP +Because QUIC key updates are always handled immediately, +\&\fBSSL_get_key_update_type()\fR always returns SSL_KEY_UPDATE_NONE when called on a +QUIC connection SSL object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_key_update()\fR, \fBSSL_renegotiate()\fR and \fBSSL_renegotiate_abbreviated()\fR return 1 +on success or 0 on error. +.PP +\&\fBSSL_get_key_update_type()\fR returns the update type of the pending key update +operation or SSL_KEY_UPDATE_NONE if there is none. +.PP +\&\fBSSL_renegotiate_pending()\fR returns 1 if a renegotiation or renegotiation request +has been scheduled but not yet acted on, or 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_read_ex\fR\|(3), +\&\fBSSL_write_ex\fR\|(3), +\&\fBSSL_do_handshake\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_key_update()\fR and \fBSSL_get_key_update_type()\fR functions were added in +OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_library_init.3 b/static/netbsd/man3/SSL_library_init.3 new file mode 100644 index 00000000..2570bba2 --- /dev/null +++ b/static/netbsd/man3/SSL_library_init.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: SSL_library_init.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_library_init 3" +.TH SSL_library_init 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_library_init, OpenSSL_add_ssl_algorithms +\&\- initialize SSL library by registering algorithms +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_library_init(void); +\& +\& int OpenSSL_add_ssl_algorithms(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_library_init()\fR registers the available SSL/TLS ciphers and digests. +.PP +\&\fBOpenSSL_add_ssl_algorithms()\fR is a synonym for \fBSSL_library_init()\fR and is +implemented as a macro. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_library_init()\fR must be called before any other action takes place. +\&\fBSSL_library_init()\fR is not reentrant. +.SH WARNINGS +.IX Header "WARNINGS" +\&\fBSSL_library_init()\fR adds ciphers and digests used directly and indirectly by +SSL/TLS. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_library_init()\fR always returns "1", so it is safe to discard the return +value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBRAND_add\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_library_init()\fR and \fBOpenSSL_add_ssl_algorithms()\fR functions were +deprecated in OpenSSL 1.1.0 by \fBOPENSSL_init_ssl()\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_load_client_CA_file.3 b/static/netbsd/man3/SSL_load_client_CA_file.3 new file mode 100644 index 00000000..434ef333 --- /dev/null +++ b/static/netbsd/man3/SSL_load_client_CA_file.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: SSL_load_client_CA_file.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_load_client_CA_file 3" +.TH SSL_load_client_CA_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_load_client_CA_file_ex, SSL_load_client_CA_file, +SSL_add_file_cert_subjects_to_stack, +SSL_add_dir_cert_subjects_to_stack, +SSL_add_store_cert_subjects_to_stack +\&\- load certificate names +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509_NAME) *SSL_load_client_CA_file_ex(const char *file, +\& OSSL_LIB_CTX *libctx, +\& const char *propq); +\& STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); +\& +\& int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack, +\& const char *file); +\& int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack, +\& const char *dir); +\& int SSL_add_store_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack, +\& const char *store); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_load_client_CA_file_ex()\fR reads certificates from \fIfile\fR and returns +a STACK_OF(X509_NAME) with the subject names found. The library context \fIlibctx\fR +and property query \fIpropq\fR are used when fetching algorithms from providers. +.PP +\&\fBSSL_load_client_CA_file()\fR is similar to \fBSSL_load_client_CA_file_ex()\fR +but uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBSSL_add_file_cert_subjects_to_stack()\fR reads certificates from \fIfile\fR, +and adds their subject name to the already existing \fIstack\fR. +.PP +\&\fBSSL_add_dir_cert_subjects_to_stack()\fR reads certificates from every +file in the directory \fIdir\fR, and adds their subject name to the +already existing \fIstack\fR. +.PP +\&\fBSSL_add_store_cert_subjects_to_stack()\fR loads certificates from the +\&\fIstore\fR URI, and adds their subject name to the already existing +\&\fIstack\fR. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_load_client_CA_file()\fR reads a file of PEM formatted certificates and +extracts the X509_NAMES of the certificates found. While the name suggests +the specific usage as support function for +\&\fBSSL_CTX_set_client_CA_list\fR\|(3), +it is not limited to CA certificates. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur for \fBSSL_load_client_CA_file_ex()\fR, and +\&\fBSSL_load_client_CA_file()\fR: +.IP NULL 4 +.IX Item "NULL" +The operation failed, check out the error stack for the reason. +.IP "Pointer to STACK_OF(X509_NAME)" 4 +.IX Item "Pointer to STACK_OF(X509_NAME)" +Pointer to the subject names of the successfully read certificates. +.PP +The following return values can occur for \fBSSL_add_file_cert_subjects_to_stack()\fR, +\&\fBSSL_add_dir_cert_subjects_to_stack()\fR, and \fBSSL_add_store_cert_subjects_to_stack()\fR: +.IP "0 (Failure)" 4 +.IX Item "0 (Failure)" +The operation failed. +.IP "1 (Success)" 4 +.IX Item "1 (Success)" +The operation succeeded. +.SH EXAMPLES +.IX Header "EXAMPLES" +Load names of CAs from file and use it as a client CA list: +.PP +.Vb 2 +\& SSL_CTX *ctx; +\& STACK_OF(X509_NAME) *cert_names; +\& +\& ... +\& cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); +\& if (cert_names != NULL) +\& SSL_CTX_set_client_CA_list(ctx, cert_names); +\& else +\& /* error */ +\& ... +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBossl_store\fR\|(7), +\&\fBSSL_CTX_set_client_CA_list\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_load_client_CA_file_ex()\fR and \fBSSL_add_store_cert_subjects_to_stack()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_new.3 b/static/netbsd/man3/SSL_new.3 new file mode 100644 index 00000000..e6873da3 --- /dev/null +++ b/static/netbsd/man3/SSL_new.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: SSL_new.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_new 3" +.TH SSL_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_dup, SSL_new, SSL_up_ref \- create an SSL structure for a connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL *SSL_dup(SSL *s); +\& SSL *SSL_new(SSL_CTX *ctx); +\& int SSL_up_ref(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_new()\fR creates a new \fBSSL\fR structure which is needed to hold the +data for a TLS/SSL connection. The new structure inherits the settings +of the underlying context \fBctx\fR: connection method, +options, verification settings, timeout settings. An \fBSSL\fR structure is +reference counted. Creating an \fBSSL\fR structure for the first time increments +the reference count. Freeing it (using SSL_free) decrements it. When the +reference count drops to zero, any memory or resources allocated to the \fBSSL\fR +structure are freed. +.PP +\&\fBSSL_up_ref()\fR increments the reference count for an +existing \fBSSL\fR structure. +.PP +The function \fBSSL_dup()\fR creates and returns a new \fBSSL\fR structure from the same +\&\fBSSL_CTX\fR that was used to create \fIs\fR. It additionally duplicates a subset of +the settings in \fIs\fR into the new \fBSSL\fR object. +.PP +For \fBSSL_dup()\fR to work, the connection MUST be in its initial state and +MUST NOT have yet started the SSL handshake. For connections that are not in +their initial state \fBSSL_dup()\fR just increments an internal +reference count and returns the \fIsame\fR handle. It may be possible to +use \fBSSL_clear\fR\|(3) to recycle an SSL handle that is not in its initial +state for reuse, but this is best avoided. Instead, save and restore +the session, if desired, and construct a fresh handle for each connection. +.PP +The subset of settings in \fIs\fR that are duplicated are: +.IP "any session data if configured (including the session_id_context)" 4 +.IX Item "any session data if configured (including the session_id_context)" +.PD 0 +.IP "any tmp_dh settings set via \fBSSL_set_tmp_dh\fR\|(3), \fBSSL_set_tmp_dh_callback\fR\|(3), or \fBSSL_set_dh_auto\fR\|(3)" 4 +.IX Item "any tmp_dh settings set via SSL_set_tmp_dh, SSL_set_tmp_dh_callback, or SSL_set_dh_auto" +.IP "any configured certificates, private keys or certificate chains" 4 +.IX Item "any configured certificates, private keys or certificate chains" +.IP "any configured signature algorithms, or client signature algorithms" 4 +.IX Item "any configured signature algorithms, or client signature algorithms" +.IP "any DANE settings" 4 +.IX Item "any DANE settings" +.IP "any Options set via \fBSSL_set_options\fR\|(3)" 4 +.IX Item "any Options set via SSL_set_options" +.IP "any Mode set via \fBSSL_set_mode\fR\|(3)" 4 +.IX Item "any Mode set via SSL_set_mode" +.IP "any minimum or maximum protocol settings set via \fBSSL_set_min_proto_version\fR\|(3) or \fBSSL_set_max_proto_version\fR\|(3) (Note: Only from OpenSSL 1.1.1h and above)" 4 +.IX Item "any minimum or maximum protocol settings set via SSL_set_min_proto_version or SSL_set_max_proto_version (Note: Only from OpenSSL 1.1.1h and above)" +.IP "any verify mode, callback or depth set via \fBSSL_set_verify\fR\|(3) or \fBSSL_set_verify_depth\fR\|(3) or any configured X509 verification parameters" 4 +.IX Item "any verify mode, callback or depth set via SSL_set_verify or SSL_set_verify_depth or any configured X509 verification parameters" +.IP "any msg callback or info callback set via \fBSSL_set_msg_callback\fR\|(3) or \fBSSL_set_info_callback\fR\|(3)" 4 +.IX Item "any msg callback or info callback set via SSL_set_msg_callback or SSL_set_info_callback" +.IP "any default password callback set via \fBSSL_set_default_passwd_cb\fR\|(3)" 4 +.IX Item "any default password callback set via SSL_set_default_passwd_cb" +.IP "any session id generation callback set via \fBSSL_set_generate_session_id\fR\|(3)" 4 +.IX Item "any session id generation callback set via SSL_set_generate_session_id" +.IP "any configured Cipher List" 4 +.IX Item "any configured Cipher List" +.IP "initial accept (server) or connect (client) state" 4 +.IX Item "initial accept (server) or connect (client) state" +.IP "the max cert list value set via \fBSSL_set_max_cert_list\fR\|(3)" 4 +.IX Item "the max cert list value set via SSL_set_max_cert_list" +.IP "the read_ahead value set via \fBSSL_set_read_ahead\fR\|(3)" 4 +.IX Item "the read_ahead value set via SSL_set_read_ahead" +.IP "application specific data set via \fBSSL_set_ex_data\fR\|(3)" 4 +.IX Item "application specific data set via SSL_set_ex_data" +.IP "any CA list or client CA list set via \fBSSL_set0_CA_list\fR\|(3), \fBSSL_set0_client_CA_list()\fR or similar functions" 4 +.IX Item "any CA list or client CA list set via SSL_set0_CA_list, SSL_set0_client_CA_list() or similar functions" +.IP "any security level settings or callbacks" 4 +.IX Item "any security level settings or callbacks" +.IP "any configured serverinfo data" 4 +.IX Item "any configured serverinfo data" +.IP "any configured PSK identity hint" 4 +.IX Item "any configured PSK identity hint" +.IP "any configured custom extensions" 4 +.IX Item "any configured custom extensions" +.IP "any client certificate types configured via SSL_set1_client_certificate_types" 4 +.IX Item "any client certificate types configured via SSL_set1_client_certificate_types" +.PD +.PP +\&\fBSSL_dup()\fR is not supported on QUIC SSL objects and returns NULL if called on +such an object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP NULL 4 +.IX Item "NULL" +The creation of a new SSL structure failed. Check the error stack to +find out the reason. +.IP "Pointer to an SSL structure" 4 +.IX Item "Pointer to an SSL structure" +The return value points to an allocated SSL structure. +.Sp +\&\fBSSL_up_ref()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_free\fR\|(3), \fBSSL_clear\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_get_SSL_CTX\fR\|(3), +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_new_domain.3 b/static/netbsd/man3/SSL_new_domain.3 new file mode 100644 index 00000000..c08a91eb --- /dev/null +++ b/static/netbsd/man3/SSL_new_domain.3 @@ -0,0 +1,158 @@ +.\" $NetBSD: SSL_new_domain.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_new_domain 3" +.TH SSL_new_domain 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_new_domain, +SSL_is_domain, +SSL_get0_domain +\&\- SSL object interface for managing QUIC event domains +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL *SSL_new_domain(SSL_CTX *ctx, uint64_t flags); +\& +\& int SSL_is_domain(SSL *ssl); +\& SSL *SSL_get0_domain(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_new_domain()\fR function creates a new QUIC event domain, represented as an +SSL object. This is known as a QUIC domain SSL object (QDSO). The concept of a +QUIC event domain is discussed in detail in \fBopenssl\-quic\-concurrency\fR\|(7). +.PP +The \fIflags\fR argument to \fBSSL_new_domain()\fR specifies a set of domain flags. If the +\&\fIflags\fR argument to \fBSSL_new_domain()\fR does not specify one of the flags +\&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or +\&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR, the domain flags configured on the +\&\fBSSL_CTX\fR are inherited as a default and any other flags in \fIflags\fR are added +to the set of inherited flags. Otherwise, the domain flags in \fIflags\fR +are used. See \fBSSL_CTX_set_domain_flags\fR\|(3) for details of the available domain +flags and how they can be configured on a \fBSSL_CTX\fR. +.PP +A QUIC domain SSL object can be managed in the same way as any other SSL object, +in that it can be refcounted and freed normally. A QUIC domain SSL object is the +parent of a number of child objects such as QUIC listener SSL objects. Once a +QUIC domain SSL object has been created, a listener can be created under it +using \fBSSL_new_listener_from\fR\|(3). +.PP +\&\fBSSL_is_domain()\fR returns 1 if a SSL object is a QUIC domain SSL object. +.PP +\&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in a SSL +object hierarchy (if any). +.PP +All SSL objects in a QUIC event domain use the same domain flags, and the domain +flags for a QUIC domain cannot be changed after construction. +.SS "Supported Operations" +.IX Subsection "Supported Operations" +A QUIC domain SSL object exists to contain other QUIC SSL objects and provide +unified event handling. As such, it supports only the following operations: +.IP \(bu 4 +Standard reference counting and free operations, such as \fBSSL_up_ref\fR\|(3) and +\&\fBSSL_free\fR\|(3); +.IP \(bu 4 +Event processing and polling enablement APIs such as \fBSSL_handle_events\fR\|(3), +and \fBSSL_get_event_timeout\fR\|(3). +.IP \(bu 4 +Creating listeners under the domain using \fBSSL_new_listener_from\fR\|(3). +.PP +The basic workflow of using a domain object is as follows: +.IP \(bu 4 +Create a new domain object using \fBSSL_new_domain()\fR using a \fBSSL_CTX\fR which uses +a supported \fBSSL_METHOD\fR (such as \fBOSSL_QUIC_server_method\fR\|(3)); +.IP \(bu 4 +Create listeners under the domain using \fBSSL_new_listener_from\fR\|(3). +.PP +Refer to \fBSSL_new_listener_from\fR\|(3) for details on using listeners. +.PP +Currently, domain SSL objects are only supported for QUIC usage via any QUIC +\&\fBSSL_METHOD\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_new_domain()\fR returns a new domain SSL object or NULL on failure. +.PP +\&\fBSSL_is_domain()\fR returns 0 or 1 depending on the type of the SSL object on +which it is called. +.PP +\&\fBSSL_get0_domain()\fR returns an SSL object pointer (potentially to the same object +on which it is called) or NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_new_listener_from\fR\|(3) \fBSSL_handle_events\fR\|(3), +\&\fBSSL_CTX_set_domain_flags\fR\|(3), \fBopenssl\-quic\-concurrency\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_new_listener.3 b/static/netbsd/man3/SSL_new_listener.3 new file mode 100644 index 00000000..cfe8c2ad --- /dev/null +++ b/static/netbsd/man3/SSL_new_listener.3 @@ -0,0 +1,270 @@ +.\" $NetBSD: SSL_new_listener.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_new_listener 3" +.TH SSL_new_listener 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener, +SSL_listen, +SSL_accept_connection, SSL_get_accept_connection_queue_len, +SSL_new_from_listener, +SSL_ACCEPT_CONNECTION_NO_BLOCK \- SSL object interface for abstracted connection +acceptance +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags); +\& SSL *SSL_new_listener_from(SSL *ssl, uint64_t flags); +\& +\& int SSL_is_listener(SSL *ssl); +\& SSL *SSL_get0_listener(SSL *ssl); +\& +\& int SSL_listen(SSL *ssl); +\& +\& #define SSL_ACCEPT_CONNECTION_NO_BLOCK +\& SSL *SSL_accept_connection(SSL *ssl, uint64_t flags); +\& +\& size_t SSL_get_accept_connection_queue_len(SSL *ssl); +\& +\& SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_new_listener()\fR function creates a listener SSL object. Listener SSL +objects are specialised to only accept network connections in a protocol\- +agnostic manner. They cannot be used, for example, for sending or receiving data +using \fBSSL_write_ex\fR\|(3) or \fBSSL_read_ex\fR\|(3). In general, only those functions +expressly documented as being supported on a listener SSL object are available. +.PP +The \fBSSL_new_listener_from()\fR function creates a listener SSL object which is +subordinate to a QUIC domain SSL object \fIssl\fR. See \fBSSL_new_domain\fR\|(3) and +\&\fBopenssl\-quic\-concurrency\fR\|(7) for details on QUIC domain SSL objects. +.PP +A listener SSL object supports the following operations: +.IP \(bu 4 +Standard reference counting and free operations, such as \fBSSL_up_ref\fR\|(3) and +\&\fBSSL_free\fR\|(3); +.IP \(bu 4 +Network BIO configuration operations, such as \fBSSL_set_bio\fR\|(3); +.IP \(bu 4 +Event processing and polling enablement APIs such as \fBSSL_handle_events\fR\|(3), +\&\fBSSL_get_event_timeout\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3), +\&\fBSSL_get_wpoll_descriptor\fR\|(3), \fBSSL_net_read_desired\fR\|(3) and +\&\fBSSL_net_write_desired\fR\|(3); +.IP \(bu 4 +Certain configurable parameters described in \fBSSL_get_value_uint\fR\|(3) (see +\&\fBSSL_get_value_uint\fR\|(3) for details); +.IP \(bu 4 +Accepting network connections using the functions documented in this manual +page, such as \fBSSL_accept_connection()\fR. +.PP +The basic workflow of using a listener object is as follows: +.IP \(bu 4 +Create a new listener object using \fBSSL_new_listener()\fR using a \fBSSL_CTX\fR which +uses a supported \fBSSL_METHOD\fR (such as \fBOSSL_QUIC_server_method\fR\|(3)); +.IP \(bu 4 +Configure appropriate network BIOs using \fBSSL_set_bio\fR\|(3) on the listener SSL +object; +.IP \(bu 4 +Configure the blocking mode using \fBSSL_set_blocking_mode\fR\|(3); +.IP \(bu 4 +Accept connections in a loop by calling \fBSSL_accept_connection()\fR. Each returned +SSL object is a valid connection which can be used in a normal manner. +.PP +The \fBSSL_is_listener()\fR function returns 1 if and only if a SSL object is a +listener SSL object. +.PP +The \fBSSL_get0_listener()\fR function returns a listener object which is related to +the given SSL object, if there is one. For a listener object, this is the same +object (the function returns its argument). For a connection object which was +created by a listener object, that listener object is returned. If the \fIssl\fR +argument is an SSL object which is not a listener object and which is not +descended from a listener object (e.g. a connection obtained using +\&\fBSSL_accept_connection()\fR) or indirectly from a listener object (e.g. a QUIC +stream SSL object obtained using \fBSSL_accept_stream()\fR called on a connection +obtained using \fBSSL_accept_connection()\fR) the return value is NULL. See NOTES +below for caveats related to pending SSL connections on a QUIC listener\*(Aqs accept +queue. +.PP +The \fBSSL_listen()\fR function begins monitoring the listener \fIssl\fR for incoming +connections. Appropriate BIOs must have been configured before calling +\&\fBSSL_listen()\fR, along with any other needed configuration for the listener SSL +object. It is typically not necessary to call \fBSSL_listen()\fR because it will be +called automatically on the first call to \fBSSL_accept_connection()\fR. However, +\&\fBSSL_listen()\fR may be called explicitly if it is desired to control precisely when +the listening process begins, or to ensure that no errors occur when starting to +listen for connections. After a call to \fBSSL_listen()\fR (or +\&\fBSSL_accept_connection()\fR) succeeds. The \fBSSL_listen()\fR function is idempotent, +subsequent calls on the same \fIssl\fR object are no\-ops. This call is supported +only on listener SSL objects. +.PP +The \fBSSL_accept_connection()\fR call is supported only on a listener SSL object and +accepts a new incoming connection. A new SSL object representing the accepted +connection is created and returned on success. If no incoming connection is +available and the listener SSL object is configured in nonblocking mode, NULL is +returned. +.PP +The new SSL object returned from \fBSSL_accept_connection()\fR may or may not have +completed its handshake at the point it is returned. Optionally, you may use the +function \fBSSL_is_init_finished\fR\|(3) to determine this. You may call the +functions \fBSSL_accept\fR\|(3), \fBSSL_do_handshake\fR\|(3) or \fBSSL_handle_events\fR\|(3) to +progress the state of the SSL object towards handshake completion. Other "I/O" +functions may also implicitly progress the state of the handshake such as +\&\fBSSL_poll\fR\|(3), \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). +.PP +The \fBSSL_ACCEPT_CONNECTION_NO_BLOCK\fR flag may be specified to +\&\fBSSL_accept_connection()\fR. If specified, the call does not block even if the +listener SSL object is configured in blocking mode. +.PP +The \fBSSL_get_accept_connection_queue_len()\fR call returns the number of pending +connections on the \fIssl\fR listener\*(Aqs queue. \fBSSL_accept_connection()\fR returns the +next pending connection, removing it from the queue. The returned connection +count is a point\-in\-time value, the actual number of connections that will +ultimately be returned may be different. +.PP +Currently, listener SSL objects are only supported for QUIC server usage via +\&\fBOSSL_QUIC_server_method\fR\|(3), or QUIC client\-only usage via +\&\fBOSSL_QUIC_client_method\fR\|(3) or \fBOSSL_QUIC_client_thread_method\fR\|(3) (see +"CLIENT\-ONLY USAGE"). It is expected that the listener interface, which +provides an abstracted API for connection acceptance, will be expanded to +support other protocols, such as TLS over TCP, plain TCP or DTLS in future. +.PP +\&\fBSSL_listen()\fR and \fBSSL_accept_connection()\fR are "I/O" functions, meaning that they +update the value returned by \fBSSL_get_error\fR\|(3) if they fail. +.SH "CLIENT\-ONLY USAGE" +.IX Header "CLIENT-ONLY USAGE" +It is also possible to use the listener interface without accepting any +connections and without listening for connections. This can be useful in +circumstances where it is desirable for multiple connections to share the same +underlying network resources. For example, multiple outgoing QUIC client +connections could be made to use the same underlying UDP socket. +.PP +To disable client address validation on a listener SSL object, the flag +\&\fBSSL_LISTENER_FLAG_NO_VALIDATE\fR may be passed in the flags field of both +\&\fBSSL_new_listener()\fR and \fBSSL_new_listener_from()\fR. Note that this flag only +impacts the sending of retry frames for server address validation. Tokens may +still be communicated from the server via NEW_TOKEN frames, which will still +be validated on receipt in future connections. Note that this setting is not +recommended and may be dangerous in untrusted environments. Not performing +address validation exposes the server to malicious clients that may open large +numbers of connections and never transact data on them (roughly equivalent to +a TCP syn flood attack), which address validation mitigates. +.PP +The \fBSSL_new_from_listener()\fR function creates a client connection under a given +listener SSL object. For QUIC, it is also possible to use +\&\fBSSL_new_from_listener()\fR, leading to a UDP network endpoint which has both +incoming and outgoing connections. +.PP +The \fIflags\fR argument of \fBSSL_new_from_listener()\fR is reserved and must be set to +0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_new_listener()\fR and \fBSSL_new_listener_from()\fR return a new listener SSL object +or NULL on failure. +.PP +\&\fBSSL_is_listener()\fR returns 1 if its \fIssl\fR argument is a listener object, 0 +otherwise. +.PP +\&\fBSSL_get0_listener()\fR returns an SSL object pointer (potentially to the same +object on which it is called) or NULL. +.PP +\&\fBSSL_listen()\fR returns 1 on success or 0 on failure. +.PP +\&\fBSSL_accept_connection()\fR returns a pointer to a new SSL object on success or NULL +on failure. On success, the caller assumes ownership of the reference. +.PP +\&\fBSSL_get_accept_connection_queue_len()\fR returns a nonnegative value, or 0 if the +queue is empty, or called on an unsupported SSL object type. +.PP +\&\fBSSL_new_from_listener()\fR returns a pointer to a new SSL object on success or NULL +on failure. On success, the caller assumes ownership of the reference. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_get0_listener()\fR behaves somewhat differently in SSL callbacks for QUIC +connections. As QUIC connections begin TLS handshake operations prior to them +being accepted via \fBSSL_accept_connection()\fR, an application may receive callbacks +for such pending connection prior to acceptance via \fBSSL_accept_connection()\fR. As +listener association takes place during the accept process, prior to being +returned from \fBSSL_accept_connection()\fR, calls to \fBSSL_get0_listener()\fR made from +such SSL callbacks will return NULL. This can be used as an indicator within +the callback that the referenced SSL object has not yet been accepted. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_QUIC_server_method\fR\|(3), \fBSSL_free\fR\|(3), \fBSSL_set_bio\fR\|(3), +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_rpoll_descriptor\fR\|(3), +\&\fBSSL_set_blocking_mode\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_new_stream.3 b/static/netbsd/man3/SSL_new_stream.3 new file mode 100644 index 00000000..13bb23b3 --- /dev/null +++ b/static/netbsd/man3/SSL_new_stream.3 @@ -0,0 +1,158 @@ +.\" $NetBSD: SSL_new_stream.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_new_stream 3" +.TH SSL_new_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK, +SSL_STREAM_FLAG_ADVANCE \- create a new locally\-initiated QUIC stream +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_STREAM_FLAG_UNI (1U << 0) +\& #define SSL_STREAM_FLAG_NO_BLOCK (1U << 1) +\& #define SSL_STREAM_FLAG_ADVANCE (1U << 2) +\& SSL *SSL_new_stream(SSL *ssl, uint64_t flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_new_stream()\fR function, when passed a QUIC connection SSL object, creates +a new locally\-initiated bidirectional or unidirectional QUIC stream and returns +the newly created QUIC stream SSL object. +.PP +If the \fBSSL_STREAM_FLAG_UNI\fR flag is passed, a unidirectional stream is +created; else a bidirectional stream is created. +.PP +To retrieve the stream ID of the newly created stream, use +\&\fBSSL_get_stream_id\fR\|(3). +.PP +It is the caller\*(Aqs responsibility to free the QUIC stream SSL object using +\&\fBSSL_free\fR\|(3). The lifetime of the QUIC connection SSL object must exceed that +of the QUIC stream SSL object; in other words, the QUIC stream SSL object must +be freed first. +.PP +Once a stream has been created using \fBSSL_new_stream()\fR, it may be used in the +normal way using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). +.PP +This function can only be used to create stream objects for locally\-initiated +streams. To accept incoming streams initiated by a peer, use +\&\fBSSL_accept_stream\fR\|(3). +.PP +Calling \fBSSL_new_stream()\fR if there is no default stream already present +inhibits the future creation of a default stream. See \fBopenssl\-quic\fR\|(7). +.PP +The creation of new streams is subject to flow control by the QUIC protocol. If +it is currently not possible to create a new locally initiated stream of the +specified type, a call to \fBSSL_new_stream()\fR will either block (if the connection +is configured in blocking mode) until a new stream can be created, or otherwise +return NULL. +.PP +This function operates in blocking mode if the QUIC connection SSL object is +configured in blocking mode (see \fBSSL_set_blocking_mode\fR\|(3)). It may also be +used in nonblocking mode on a connection configured in blocking mode by passing +the flag \fBSSL_STREAM_FLAG_NO_BLOCK\fR. +.PP +The flag \fBSSL_STREAM_FLAG_ADVANCE\fR may be used to create a QUIC stream SSL +object even if a new QUIC stream cannot yet be opened due to flow control. The +caller may begin to use the new stream and fill the write buffer of the stream +by calling \fBSSL_write\fR\|(3). However, no actual stream data (or QUIC frames +regarding the stream) will be sent until QUIC flow control allows it. Any queued +data will be sent as soon as a peer permits it. There is no guarantee the stream +will be eventually created; for example, the connection could fail, or a peer +might simply decide never to increase the number of allowed streams for the +remainder of the connection lifetime. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_new_stream()\fR returns a new stream object, or NULL on error. +.PP +This function fails if called on a QUIC stream SSL object or on a non\-QUIC SSL +object. +.PP +\&\fBSSL_new_stream()\fR may also fail if the underlying connection has reached the +maximum stream count, based on the \fBmax_streams_bidi\fR or \fBmax_streams_uni\fR +transport parameter values negotiated with the peer. In this event the NULL +return will be accompanied by an error on the error stack (obtainable via +\&\fBERR_get_error()\fR), which will contain a reason code of +\&\fBSSL_R_STREAM_COUNT_LIMITED\fR. When this error is encountered, the operation +may be retried. It is recommended that, prior to retry, the error stack be +cleared via a call to \fBERR_clear_error()\fR, and that the TLS state machine be +activated via a call to \fBSSL_handle_events()\fR to process any potential updates +from the server allowing additional streams to be created. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_new_stream()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_pending.3 b/static/netbsd/man3/SSL_pending.3 new file mode 100644 index 00000000..bef25e05 --- /dev/null +++ b/static/netbsd/man3/SSL_pending.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: SSL_pending.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_pending 3" +.TH SSL_pending 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_pending, SSL_has_pending \- check for readable bytes buffered in an +SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_pending(const SSL *ssl); +\& int SSL_has_pending(const SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Data is received in whole blocks known as records from the peer. A whole record +is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is +read by the application via a call to \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3). +.PP +\&\fBSSL_pending()\fR returns the number of bytes which have been processed, buffered +and are available inside \fBssl\fR for immediate read. +.PP +If the \fBSSL\fR object\*(Aqs \fIread_ahead\fR flag is set (see +\&\fBSSL_CTX_set_read_ahead\fR\|(3)), additional protocol bytes (beyond the current +record) may have been read containing more TLS/SSL records. This also applies to +DTLS and pipelining (see \fBSSL_CTX_set_split_send_fragment\fR\|(3)). These +additional bytes will be buffered by OpenSSL but will remain unprocessed until +they are needed. As these bytes are still in an unprocessed state \fBSSL_pending()\fR +will ignore them. Therefore, it is possible for no more bytes to be readable from +the underlying BIO (because OpenSSL has already read them) and for \fBSSL_pending()\fR +to return 0, even though readable application data bytes are available (because +the data is in unprocessed buffered records). +.PP +\&\fBSSL_has_pending()\fR returns 1 if \fBs\fR has buffered data (whether processed or +unprocessed) and 0 otherwise. Note that it is possible for \fBSSL_has_pending()\fR to +return 1, and then a subsequent call to \fBSSL_read_ex()\fR or \fBSSL_read()\fR to return no +data because the unprocessed buffered data when processed yielded no application +data (for example this can happen during renegotiation). It is also possible in +this scenario for \fBSSL_has_pending()\fR to continue to return 1 even after an +\&\fBSSL_read_ex()\fR or \fBSSL_read()\fR call because the buffered and unprocessed data is +not yet processable (e.g. because OpenSSL has only received a partial record so +far). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_pending()\fR returns the number of buffered and processed application data +bytes that are pending and are available for immediate read. \fBSSL_has_pending()\fR +returns 1 if there is buffered record data in the SSL object and 0 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_CTX_set_read_ahead\fR\|(3), +\&\fBSSL_CTX_set_split_send_fragment\fR\|(3), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_has_pending()\fR function was added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_poll.3 b/static/netbsd/man3/SSL_poll.3 new file mode 100644 index 00000000..4453468a --- /dev/null +++ b/static/netbsd/man3/SSL_poll.3 @@ -0,0 +1,430 @@ +.\" $NetBSD: SSL_poll.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_poll 3" +.TH SSL_poll 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_poll, +SSL_POLL_EVENT_NONE, +SSL_POLL_EVENT_F, +SSL_POLL_EVENT_EL, +SSL_POLL_EVENT_EC, +SSL_POLL_EVENT_ECD, +SSL_POLL_EVENT_ER, +SSL_POLL_EVENT_EW, +SSL_POLL_EVENT_R, +SSL_POLL_EVENT_W, +SSL_POLL_EVENT_IC, +SSL_POLL_EVENT_ISB, +SSL_POLL_EVENT_ISU, +SSL_POLL_EVENT_OSB, +SSL_POLL_EVENT_OSU, +SSL_POLL_EVENT_RW, +SSL_POLL_EVENT_RE, +SSL_POLL_EVENT_WE, +SSL_POLL_EVENT_RWE, +SSL_POLL_EVENT_E, +SSL_POLL_EVENT_IS, +SSL_POLL_EVENT_ISE, +SSL_POLL_EVENT_I, +SSL_POLL_EVENT_OS, +SSL_POLL_EVENT_OSE, +SSL_POLL_FLAG_NO_HANDLE_EVENTS +\&\- determine or await readiness conditions for one or more pollable objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_POLL_EVENT_NONE 0 +\& +\& #define SSL_POLL_EVENT_F /* F (Failure) */ +\& #define SSL_POLL_EVENT_EL /* EL (Exception on Listener) */ +\& #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */ +\& #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */ +\& #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */ +\& #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */ +\& #define SSL_POLL_EVENT_R /* R (Readable) */ +\& #define SSL_POLL_EVENT_W /* W (Writable) */ +\& #define SSL_POLL_EVENT_IC /* IC (Incoming Connection) */ +\& #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */ +\& #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */ +\& #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */ +\& #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */ +\& +\& #define SSL_POLL_EVENT_RW /* R | W */ +\& #define SSL_POLL_EVENT_RE /* R | ER */ +\& #define SSL_POLL_EVENT_WE /* W | EW */ +\& #define SSL_POLL_EVENT_RWE /* RE | WE */ +\& #define SSL_POLL_EVENT_E /* EL | EC | ER | EW */ +\& #define SSL_POLL_EVENT_IS /* ISB | ISU */ +\& #define SSL_POLL_EVENT_ISE /* IS | EC */ +\& #define SSL_POLL_EVENT_I /* IS */ +\& #define SSL_POLL_EVENT_OS /* OSB | OSU */ +\& #define SSL_POLL_EVENT_OSE /* OS | EC */ +\& +\& typedef struct ssl_poll_item_st { +\& BIO_POLL_DESCRIPTOR desc; +\& uint64_t events, revents; +\& } SSL_POLL_ITEM; +\& +\& #define SSL_POLL_FLAG_NO_HANDLE_EVENTS +\& +\& int SSL_poll(SSL_POLL_ITEM *items, +\& size_t num_items, +\& size_t stride, +\& const struct timeval *timeout, +\& uint64_t flags, +\& size_t *result_count); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_poll()\fR allows the readiness conditions of the resources represented by one +or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can +be used to query for readiness conditions on QUIC connection SSL objects and +QUIC stream SSL objects in a single call. It can also be used to block until at +least one of the given resources is ready. +.PP +A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR structures, each of +which designates a resource which is being polled for readiness, and a set of +event flags which indicate the specific readiness events which the caller is +interested in in relation to the specified resource. +.PP +The fields of \fBSSL_POLL_ITEM\fR are as follows: +.IP \fIdesc\fR 4 +.IX Item "desc" +The resource being polled for readiness, as represented by a +\&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type +\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing an SSL object pointer, and the SSL +object must be a QUIC connection SSL object or QUIC stream SSL object. +.Sp +If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of +\&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the +\&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on +return. +.IP \fIevents\fR 4 +.IX Item "events" +This is the set of zero or more events which the caller is interested in +learning about in relation to the resource described by \fIdesc\fR. It is a +collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a +description of each of the event types. +.IP \fIrevents\fR 4 +.IX Item "revents" +After \fBSSL_poll()\fR returns, this is the set of zero or more events which are +actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR, +it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags. +.Sp +\&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some +event types are defined as always being enabled (non\-maskable). See "EVENT +TYPES" for more information. +.PP +To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The +array need remain allocated only for the duration of the call. \fInum_items\fR must +be set to the number of entries in the array, and \fIstride\fR must be set to +\&\f(CWsizeof(SSL_POLL_ITEM)\fR. +.PP +The \fItimeout\fR argument specifies the timeout to use, and, implicitly, whether +to use \fBSSL_poll()\fR in blocking or nonblocking mode: +.IP \(bu 4 +If \fItimeout\fR is NULL, the function blocks indefinitely until at least one +resource is ready. +.IP \(bu 4 +If \fItimeout\fR is non\-NULL, and it points to a \fBstruct timeval\fR which is set to +zero, the function operates in nonblocking mode and returns immediately with +readiness information. +.IP \(bu 4 +If \fItimeout\fR is non\-NULL, and it points to a \fBstruct timeval\fR which is set to +a value other than zero, the function blocks for the specified interval or until +at least one of the specified resources is ready, whichever comes first. +.PP +The present implementation of \fBSSL_poll()\fR is a subset of the functionality which +will eventually be available. For more information, see "LIMITATIONS". +.PP +The following flags are currently defined for the \fIflags\fR argument: +.IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4 +.IX Item "SSL_POLL_FLAG_NO_HANDLE_EVENTS" +This flag indicates that internal state machine processing should not be +performed in an attempt to generate new readiness events. Only existing +readiness events will be reported. +.Sp +If this flag is used in nonblocking mode (with a timeout of zero), no internal +state machine processing is performed. +.Sp +If this flag is used in blocking mode (for example, with \fItimeout\fR set to +NULL), event processing does not occur unless the function blocks. +.PP +The \fIresult_count\fR argument is optional. If it is non\-NULL, it is used to +output the number of entries in the array which have nonzero \fIrevents\fR fields +when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details. +.SH "EVENT TYPES" +.IX Header "EVENT TYPES" +The \fBSSL_poll()\fR interface reports zero or more event types on a given resource, +represented by a bit mask. +.PP +All of the event types are level triggered and represent a readiness or +permanent exception condition; as such, after an event has been reported by +\&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR +calls until the condition ceases to be in effect. A caller must mask the given +event type bit in future \fBSSL_poll()\fR calls if it does not wish to receive +repeated notifications and has not caused the underlying readiness condition +(for example, consuming all available data using \fBSSL_read_ex\fR\|(3) after +\&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted. +.PP +Some event types do not make sense on a given kind of resource. In this case, +specifying that event type in \fIevents\fR is a no\-op and will be ignored, and the +given event will never be reported in \fIrevents\fR. +.PP +Failure of the polling mechanism itself is considered distinct from an exception +condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR +and "RETURN VALUES" for details. +.PP +In general, an application should always listen for the event types +corresponding to exception conditions if it is listening to the corresponding +non\-exception event types (e.g. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR +for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design. +.PP +Some event types are non\-maskable and may be reported in \fIrevents\fR regardless +of whether they were requested in \fIevents\fR. +.PP +The following event types are supported: +.IP \fBSSL_POLL_EVENT_F\fR 4 +.IX Item "SSL_POLL_EVENT_F" +Polling failure. This event is raised when a resource could not be polled. It is +distinct from an exception condition reported on a resource which was +successfully polled and represents a failure of the polling process itself in +relation to a resource. This may mean that \fBSSL_poll()\fR does not support the kind +of resource specified. +.Sp +Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will +return 0 and the ERR stack will contain information pertaining to the first item +in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more +information. +.Sp +This event type may be raised even if it was not requested in \fIevents\fR; +specifying this event type in \fIevents\fR does nothing. +.IP \fBSSL_POLL_EVENT_EL\fR 4 +.IX Item "SSL_POLL_EVENT_EL" +Error at listener level. This event is raised when a listener has failed, for +example if a network BIO has encountered a permanent error. +.Sp +This event is never raised on objects which are not listeners, but its +occurrence will cause \fBSSL_POLL_EVENT_EC\fR to be raised on all dependent +connections. +.IP \fBSSL_POLL_EVENT_EC\fR 4 +.IX Item "SSL_POLL_EVENT_EC" +Error at connection level. This event is raised when a connection has failed. +In particular, it is raised when a connection begins terminating. +.Sp +This event is never raised on objects which are not connections. +.IP \fBSSL_POLL_EVENT_ECD\fR 4 +.IX Item "SSL_POLL_EVENT_ECD" +Error at connection level (drained). This event is raised when a connection has +finished terminating, and has reached the terminated state. This event will +generally occur after an interval of time passes after the \fBSSL_POLL_EVENT_EC\fR +event is raised on a connection. +.Sp +This event is never raised on objects which are not connections. +.IP \fBSSL_POLL_EVENT_ER\fR 4 +.IX Item "SSL_POLL_EVENT_ER" +Error in read direction. For QUIC, this is raised only in the event that a +stream has a read part and that read part has been reset by the peer (for +example, using a \fBRESET_STREAM\fR frame). +.IP \fBSSL_POLL_EVENT_EW\fR 4 +.IX Item "SSL_POLL_EVENT_EW" +Error in write direction. For QUIC, this is raised only in the event that a +stream has a write part and that write part has been reset by the peer using a +\&\fBSTOP_SENDING\fR frame. +.IP \fBSSL_POLL_EVENT_R\fR 4 +.IX Item "SSL_POLL_EVENT_R" +Readable. This event is raised when a QUIC stream SSL object (or a QUIC +connection SSL object with a default stream attached) has application data +waiting to be read using \fBSSL_read_ex\fR\|(3), or a FIN event as represented by +\&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read. +.Sp +It is not raised in the event of the receiving part of the QUIC stream being +reset by the peer; see \fBSSL_POLL_EVENT_ER\fR. +.IP \fBSSL_POLL_EVENT_W\fR 4 +.IX Item "SSL_POLL_EVENT_W" +Writable. This event is raised when a QUIC stream SSL object (or a QUIC +connection SSL object with a default stream attached) could accept more +application data using \fBSSL_write_ex\fR\|(3). +.Sp +This event is never raised by a receive\-only stream. +.Sp +This event is never raised by a stream which has had its send part concluded +normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with +\&\fBSSL_stream_reset\fR\|(3)). +.Sp +This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will +succeed. +.IP \fBSSL_POLL_EVENT_IC\fR 4 +.IX Item "SSL_POLL_EVENT_IC" +This event, which is only raised by a QUIC listener SSL object, is raised when +one or more incoming QUIC connections are available to be accepted using +\&\fBSSL_accept_connection\fR\|(3). +.IP \fBSSL_POLL_EVENT_ISB\fR 4 +.IX Item "SSL_POLL_EVENT_ISB" +This event, which is only raised by a QUIC connection SSL object, is raised when +one or more incoming bidirectional streams are available to be accepted using +\&\fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_POLL_EVENT_ISU\fR 4 +.IX Item "SSL_POLL_EVENT_ISU" +This event, which is only raised by a QUIC connection SSL object, is raised when +one or more incoming unidirectional streams are available to be accepted using +\&\fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_POLL_EVENT_OSB\fR 4 +.IX Item "SSL_POLL_EVENT_OSB" +This event, which is only raised by a QUIC connection SSL object, is raised when +QUIC stream creation flow control currently permits at least one additional +bidirectional stream to be locally created. +.IP \fBSSL_POLL_EVENT_OSU\fR 4 +.IX Item "SSL_POLL_EVENT_OSU" +This event, which is only raised by a QUIC connection SSL object, is raised when +QUIC stream creation flow control currently permits at least one additional +unidirectional stream to be locally created. +.SH LIMITATIONS +.IX Header "LIMITATIONS" +\&\fBSSL_poll()\fR as presently implemented has the following limitation: +.IP \(bu 4 +Only \fBBIO_POLL_DESCRIPTOR\fR structures with type +\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC listener, connection or +stream SSL objects, are supported. +.PP +This limitation may be revised in a future release of OpenSSL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_poll()\fR returns 1 on success and 0 on failure. +.PP +Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise +the \fIrevents\fR fields of all items in the input array upon returning, even if it +returns failure. +.PP +If \fIresult_count\fR is non\-NULL, it is always written with the number of items in +the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns +failure. +.PP +It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR +call returns success, namely if no events were output but the polling process +was successful (e.g. in nonblocking usage) or timed out. +.PP +It is possible for \fIresult_count\fR to be written as a nonzero value if the +\&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events, +or because some events were detected and output before encountering a failure +condition while processing a subsequent entry in the \fIitems\fR array. +.PP +If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed +to return 0 and guaranteed to place at least one ERR on the error stack +describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any +additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may +not return more than one \fBSSL_POLL_EVENT_F\fR event at once. +.PP +"Normal" events representing exceptional I/O conditions which do not +constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered +errors by \fBSSL_poll()\fR and are instead represented using their own event type; see +"EVENT TYPES" for details. +.PP +The caller can establish the meaning of the \fBSSL_poll()\fR return and output values +as follows: +.IP \(bu 4 +If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out +before any resource was ready. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were +output. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic +usage error; check the ERR stack for details. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR +array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type +raised in \fIrevents\fR. The entries added to the ERR stack (of which there is +guaranteed to be at least one) reflect the cause of the failure of the first +item in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events +other than \fISSL_POLL_EVENT_F\fR output for items which come before the first +item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR +events may or may not have been output, both of which which will be reflected in +\&\fIresult_count\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3), +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_poll()\fR was added in OpenSSL 3.3. +.PP +Before 3.5, \fBSSL_poll()\fR did not support blocking operation and +would fail if called with a NULL \fItimeout\fR parameter or a \fItimeout\fR parameter +pointing to a \fBstruct timeval\fR which was not zero. +.PP +Before 3.5, the \fBSSL_POLL_EVENT_EL\fR and \fBSSL_POLL_EVENT_IC\fR +event types were not present. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_read.3 b/static/netbsd/man3/SSL_read.3 new file mode 100644 index 00000000..e63de837 --- /dev/null +++ b/static/netbsd/man3/SSL_read.3 @@ -0,0 +1,211 @@ +.\" $NetBSD: SSL_read.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_read 3" +.TH SSL_read 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek +\&\- read bytes from a TLS/SSL connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes); +\& int SSL_read(SSL *ssl, void *buf, int num); +\& +\& int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes); +\& int SSL_peek(SSL *ssl, void *buf, int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_read_ex()\fR and \fBSSL_read()\fR try to read \fBnum\fR bytes from the specified \fBssl\fR +into the buffer \fBbuf\fR. On success \fBSSL_read_ex()\fR will store the number of bytes +actually read in \fB*readbytes\fR. +.PP +\&\fBSSL_peek_ex()\fR and \fBSSL_peek()\fR are identical to \fBSSL_read_ex()\fR and \fBSSL_read()\fR +respectively except no bytes are actually removed from the underlying BIO during +the read, so that a subsequent call to \fBSSL_read_ex()\fR or \fBSSL_read()\fR will yield +at least the same bytes. +.SH NOTES +.IX Header "NOTES" +In the paragraphs below a "read function" is defined as one of \fBSSL_read_ex()\fR, +\&\fBSSL_read()\fR, \fBSSL_peek_ex()\fR or \fBSSL_peek()\fR. +.PP +If necessary, a read function will negotiate a TLS/SSL session, if not already +explicitly performed by \fBSSL_connect\fR\|(3) or \fBSSL_accept\fR\|(3). If the +peer requests a re\-negotiation, it will be performed transparently during +the read function operation. The behaviour of the read functions depends on the +underlying BIO. +.PP +For the transparent negotiation to succeed, the \fBssl\fR must have been +initialized to client or server mode. This is being done by calling +\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state()\fR before the first +invocation of a read function. +.PP +The read functions work based on the SSL/TLS records. The data are received in +records (with a maximum record size of 16kB). Only when a record has been +completely received, can it be processed (decryption and check of integrity). +Therefore, data that was not retrieved at the last read call can still be +buffered inside the SSL layer and will be retrieved on the next read +call. If \fBnum\fR is higher than the number of bytes buffered then the read +functions will return with the bytes buffered. If no more bytes are in the +buffer, the read functions will trigger the processing of the next record. +Only when the record has been received and processed completely will the read +functions return reporting success. At most the contents of one record will +be returned. As the size of an SSL/TLS record may exceed the maximum packet size +of the underlying transport (e.g. TCP), it may be necessary to read several +packets from the transport layer before the record is complete and the read call +can succeed. +.PP +If \fBSSL_MODE_AUTO_RETRY\fR has been switched off and a non\-application data +record has been processed, the read function can return and set the error to +\&\fBSSL_ERROR_WANT_READ\fR. +In this case there might still be unprocessed data available in the \fBBIO\fR. +If read ahead was set using \fBSSL_CTX_set_read_ahead\fR\|(3), there might also still +be unprocessed data available in the \fBSSL\fR. +This behaviour can be controlled using the \fBSSL_CTX_set_mode\fR\|(3) call. +.PP +If the underlying BIO is \fBblocking\fR, a read function will only return once the +read operation has been finished or an error occurred, except when a +non\-application data record has been processed and \fBSSL_MODE_AUTO_RETRY\fR is +not set. +Note that if \fBSSL_MODE_AUTO_RETRY\fR is set and only non\-application data is +available the call will hang. +.PP +If the underlying BIO is \fBnonblocking\fR, a read function will also return when +the underlying BIO could not satisfy the needs of the function to continue the +operation. +In this case a call to \fBSSL_get_error\fR\|(3) with the +return value of the read function will yield \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR. +As at any time it\*(Aqs possible that non\-application data needs to be sent, +a read function can also cause write operations. +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of the read function. +The action depends on the underlying BIO. +When using a nonblocking socket, nothing is to be done, but \fBselect()\fR can be +used to check for the required condition. +When using a buffering BIO, like a BIO pair, data must be written into or +retrieved out of the BIO before being able to continue. +.PP +\&\fBSSL_pending\fR\|(3) can be used to find out whether there +are buffered bytes available for immediate retrieval. +In this case the read function can be called without blocking or actually +receiving new data from the underlying socket. +.PP +When used with a QUIC SSL object, calling an I/O function such as \fBSSL_read()\fR +allows internal network event processing to be performed. It is important that +this processing is performed regularly. If an application is not using thread +assisted mode, an application should ensure that an I/O function such as +\&\fBSSL_read()\fR is called regularly, or alternatively ensure that \fBSSL_handle_events()\fR +is called regularly. See \fBopenssl\-quic\fR\|(7) and \fBSSL_handle_events\fR\|(3) for more +information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_read_ex()\fR and \fBSSL_peek_ex()\fR will return 1 for success or 0 for failure. +Success means that 1 or more application data bytes have been read from the SSL +connection. +Failure means that no bytes could be read from the SSL connection. +Failures can be retryable (e.g. we are waiting for more bytes to +be delivered by the network) or non\-retryable (e.g. a fatal network error). +In the event of a failure call \fBSSL_get_error\fR\|(3) to find out the reason which +indicates whether the call is retryable or not. +.PP +For \fBSSL_read()\fR and \fBSSL_peek()\fR the following return values can occur: +.IP "> 0" 4 +.IX Item "> 0" +The read operation was successful. +The return value is the number of bytes actually read from the TLS/SSL +connection. +.IP "<= 0" 4 +.IX Item "<= 0" +The read operation was not successful, because either the connection was closed, +an error occurred or action must be taken by the calling process. +Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason. +.Sp +Old documentation indicated a difference between 0 and \-1, and that \-1 was +retryable. +You should instead call \fBSSL_get_error()\fR to find out if it\*(Aqs retryable. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_write_ex\fR\|(3), +\&\fBSSL_CTX_set_mode\fR\|(3), \fBSSL_CTX_new\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3) +\&\fBSSL_set_connect_state\fR\|(3), +\&\fBSSL_pending\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3), +\&\fBssl\fR\|(7), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_read_ex()\fR and \fBSSL_peek_ex()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_read_early_data.3 b/static/netbsd/man3/SSL_read_early_data.3 new file mode 100644 index 00000000..a86c1027 --- /dev/null +++ b/static/netbsd/man3/SSL_read_early_data.3 @@ -0,0 +1,429 @@ +.\" $NetBSD: SSL_read_early_data.3,v 1.5 2026/04/08 17:06:48 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_read_early_data 3" +.TH SSL_read_early_data 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_max_early_data, +SSL_CTX_set_max_early_data, +SSL_get_max_early_data, +SSL_CTX_get_max_early_data, +SSL_set_recv_max_early_data, +SSL_CTX_set_recv_max_early_data, +SSL_get_recv_max_early_data, +SSL_CTX_get_recv_max_early_data, +SSL_SESSION_get_max_early_data, +SSL_SESSION_set_max_early_data, +SSL_write_early_data, +SSL_read_early_data, +SSL_get_early_data_status, +SSL_allow_early_data_cb_fn, +SSL_CTX_set_allow_early_data_cb, +SSL_set_allow_early_data_cb +\&\- functions for sending and receiving early data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_CTX_set_max_early_data(SSL_CTX *ctx, uint32_t max_early_data); +\& uint32_t SSL_CTX_get_max_early_data(const SSL_CTX *ctx); +\& int SSL_set_max_early_data(SSL *s, uint32_t max_early_data); +\& uint32_t SSL_get_max_early_data(const SSL *s); +\& +\& int SSL_CTX_set_recv_max_early_data(SSL_CTX *ctx, uint32_t recv_max_early_data); +\& uint32_t SSL_CTX_get_recv_max_early_data(const SSL_CTX *ctx); +\& int SSL_set_recv_max_early_data(SSL *s, uint32_t recv_max_early_data); +\& uint32_t SSL_get_recv_max_early_data(const SSL *s); +\& +\& uint32_t SSL_SESSION_get_max_early_data(const SSL_SESSION *s); +\& int SSL_SESSION_set_max_early_data(SSL_SESSION *s, uint32_t max_early_data); +\& +\& int SSL_write_early_data(SSL *s, const void *buf, size_t num, size_t *written); +\& +\& int SSL_read_early_data(SSL *s, void *buf, size_t num, size_t *readbytes); +\& +\& int SSL_get_early_data_status(const SSL *s); +\& +\& +\& typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg); +\& +\& void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx, +\& SSL_allow_early_data_cb_fn cb, +\& void *arg); +\& void SSL_set_allow_early_data_cb(SSL *s, +\& SSL_allow_early_data_cb_fn cb, +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are used to send and receive early data where TLSv1.3 has been +negotiated. Early data can be sent by the client immediately after its initial +ClientHello without having to wait for the server to complete the handshake. +Early data can be sent if a session has previously been established with the +server or when establishing a new session using an out\-of\-band PSK, and only +when the server is known to support it. Additionally these functions can be used +to send data from the server to the client when the client has not yet completed +the authentication stage of the handshake. +.PP +Early data has weaker security properties than other data sent over an SSL/TLS +connection. In particular the data does not have forward secrecy. There are also +additional considerations around replay attacks (see "REPLAY PROTECTION" +below). For these reasons extreme care should be exercised when using early +data. For specific details, consult the TLS 1.3 specification. +.PP +When a server receives early data it may opt to immediately respond by sending +application data back to the client. Data sent by the server at this stage is +done before the full handshake has been completed. Specifically the client\*(Aqs +authentication messages have not yet been received, i.e. the client is +unauthenticated at this point and care should be taken when using this +capability. +.PP +A server or client can determine whether the full handshake has been completed +or not by calling \fBSSL_is_init_finished\fR\|(3). +.PP +On the client side, the function \fBSSL_SESSION_get_max_early_data()\fR can be used to +determine if a session established with a server can be used to send early data. +If the session cannot be used then this function will return 0. Otherwise it +will return the maximum number of early data bytes that can be sent. +.PP +The function \fBSSL_SESSION_set_max_early_data()\fR sets the maximum number of early +data bytes that can be sent for a session. This would typically be used when +creating a PSK session file (see \fBSSL_CTX_set_psk_use_session_callback\fR\|(3)). If +using a ticket based PSK then this is set automatically to the value provided by +the server. +.PP +A client uses the function \fBSSL_write_early_data()\fR to send early data. This +function is similar to the \fBSSL_write_ex\fR\|(3) function, but with the following +differences. See \fBSSL_write_ex\fR\|(3) for information on how to write bytes to +the underlying connection, and how to handle any errors that may arise. This +page describes the differences between \fBSSL_write_early_data()\fR and +\&\fBSSL_write_ex\fR\|(3). +.PP +When called by a client, \fBSSL_write_early_data()\fR must be the first IO function +called on a new connection, i.e. it must occur before any calls to +\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_connect\fR\|(3), \fBSSL_do_handshake\fR\|(3) +or other similar functions. It may be called multiple times to stream data to +the server, but the total number of bytes written must not exceed the value +returned from \fBSSL_SESSION_get_max_early_data()\fR. Once the initial +\&\fBSSL_write_early_data()\fR call has completed successfully the client may interleave +calls to \fBSSL_read_ex\fR\|(3) and \fBSSL_read\fR\|(3) with calls to +\&\fBSSL_write_early_data()\fR as required. +.PP +If \fBSSL_write_early_data()\fR fails you should call \fBSSL_get_error\fR\|(3) to determine +the correct course of action, as for \fBSSL_write_ex\fR\|(3). +.PP +When the client no longer wishes to send any more early data then it should +complete the handshake by calling a function such as \fBSSL_connect\fR\|(3) or +\&\fBSSL_do_handshake\fR\|(3). Alternatively you can call a standard write function +such as \fBSSL_write_ex\fR\|(3), which will transparently complete the connection and +write the requested data. +.PP +A server may choose to ignore early data that has been sent to it. Once the +connection has been completed you can determine whether the server accepted or +rejected the early data by calling \fBSSL_get_early_data_status()\fR. This will return +SSL_EARLY_DATA_ACCEPTED if the data was accepted, SSL_EARLY_DATA_REJECTED if it +was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function +may be called by either the client or the server. +.PP +A server uses the \fBSSL_read_early_data()\fR function to receive early data on a +connection for which early data has been enabled using +\&\fBSSL_CTX_set_max_early_data()\fR or \fBSSL_set_max_early_data()\fR. As for +\&\fBSSL_write_early_data()\fR, this must be the first IO function +called on a connection, i.e. it must occur before any calls to +\&\fBSSL_write_ex\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_accept\fR\|(3), \fBSSL_do_handshake\fR\|(3), +or other similar functions. +.PP +\&\fBSSL_read_early_data()\fR is similar to \fBSSL_read_ex\fR\|(3) with the following +differences. Refer to \fBSSL_read_ex\fR\|(3) for full details. +.PP +\&\fBSSL_read_early_data()\fR may return 3 possible values: +.IP SSL_READ_EARLY_DATA_ERROR 4 +.IX Item "SSL_READ_EARLY_DATA_ERROR" +This indicates an IO or some other error occurred. This should be treated in the +same way as a 0 return value from \fBSSL_read_ex\fR\|(3). +.IP SSL_READ_EARLY_DATA_SUCCESS 4 +.IX Item "SSL_READ_EARLY_DATA_SUCCESS" +This indicates that early data was successfully read. This should be treated in +the same way as a 1 return value from \fBSSL_read_ex\fR\|(3). You should continue to +call \fBSSL_read_early_data()\fR to read more data. +.IP SSL_READ_EARLY_DATA_FINISH 4 +.IX Item "SSL_READ_EARLY_DATA_FINISH" +This indicates that no more early data can be read. It may be returned on the +first call to \fBSSL_read_early_data()\fR if the client has not sent any early data, +or if the early data was rejected. +.PP +Once the initial \fBSSL_read_early_data()\fR call has completed successfully (i.e. it +has returned SSL_READ_EARLY_DATA_SUCCESS or SSL_READ_EARLY_DATA_FINISH) then the +server may choose to write data immediately to the unauthenticated client using +\&\fBSSL_write_early_data()\fR. If \fBSSL_read_early_data()\fR returned +SSL_READ_EARLY_DATA_FINISH then in some situations (e.g. if the client only +supports TLSv1.2) the handshake may have already been completed and calls +to \fBSSL_write_early_data()\fR are not allowed. Call \fBSSL_is_init_finished\fR\|(3) to +determine whether the handshake has completed or not. If the handshake is still +in progress then the server may interleave calls to \fBSSL_write_early_data()\fR with +calls to \fBSSL_read_early_data()\fR as required. +.PP +Servers must not call \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or +\&\fBSSL_write\fR\|(3) until \fBSSL_read_early_data()\fR has returned with +SSL_READ_EARLY_DATA_FINISH. Once it has done so the connection to the client +still needs to be completed. Complete the connection by calling a function such +as \fBSSL_accept\fR\|(3) or \fBSSL_do_handshake\fR\|(3). Alternatively you can call a +standard read function such as \fBSSL_read_ex\fR\|(3), which will transparently +complete the connection and read the requested data. Note that it is an error to +attempt to complete the connection before \fBSSL_read_early_data()\fR has returned +SSL_READ_EARLY_DATA_FINISH. +.PP +Only servers may call \fBSSL_read_early_data()\fR. +.PP +Calls to \fBSSL_read_early_data()\fR may, in certain circumstances, complete the +connection immediately without further need to call a function such as +\&\fBSSL_accept\fR\|(3). This can happen if the client is using a protocol version less +than TLSv1.3. Applications can test for this by calling +\&\fBSSL_is_init_finished\fR\|(3). Alternatively, applications may choose to call +\&\fBSSL_accept\fR\|(3) anyway. Such a call will successfully return immediately with no +further action taken. +.PP +When a session is created between a server and a client the server will specify +the maximum amount of any early data that it will accept on any future +connection attempt. By default the server does not accept early data; a +server may indicate support for early data by calling +\&\fBSSL_CTX_set_max_early_data()\fR or +\&\fBSSL_set_max_early_data()\fR to set it for the whole SSL_CTX or an individual SSL +object respectively. The \fBmax_early_data\fR parameter specifies the maximum +amount of early data in bytes that is permitted to be sent on a single +connection. Similarly the \fBSSL_CTX_get_max_early_data()\fR and +\&\fBSSL_get_max_early_data()\fR functions can be used to obtain the current maximum +early data settings for the SSL_CTX and SSL objects respectively. Generally a +server application will either use both of \fBSSL_read_early_data()\fR and +\&\fBSSL_CTX_set_max_early_data()\fR (or \fBSSL_set_max_early_data()\fR), or neither of them, +since there is no practical benefit from using only one of them. If the maximum +early data setting for a server is nonzero then replay protection is +automatically enabled (see "REPLAY PROTECTION" below). +.PP +If the server rejects the early data sent by a client then it will skip over +the data that is sent. The maximum amount of received early data that is skipped +is controlled by the recv_max_early_data setting. If a client sends more than +this then the connection will abort. This value can be set by calling +\&\fBSSL_CTX_set_recv_max_early_data()\fR or \fBSSL_set_recv_max_early_data()\fR. The current +value for this setting can be obtained by calling +\&\fBSSL_CTX_get_recv_max_early_data()\fR or \fBSSL_get_recv_max_early_data()\fR. The default +value for this setting is 16,384 bytes. +.PP +The recv_max_early_data value also has an impact on early data that is accepted. +The amount of data that is accepted will always be the lower of the +max_early_data for the session and the recv_max_early_data setting for the +server. If a client sends more data than this then the connection will abort. +.PP +The configured value for max_early_data on a server may change over time as +required. However, clients may have tickets containing the previously configured +max_early_data value. The recv_max_early_data should always be equal to or +higher than any recently configured max_early_data value in order to avoid +aborted connections. The recv_max_early_data should never be set to less than +the current configured max_early_data value. +.PP +Some server applications may wish to have more control over whether early data +is accepted or not, for example to mitigate replay risks (see "REPLAY PROTECTION" +below) or to decline early_data when the server is heavily loaded. The functions +\&\fBSSL_CTX_set_allow_early_data_cb()\fR and \fBSSL_set_allow_early_data_cb()\fR set a +callback which is called at a point in the handshake immediately before a +decision is made to accept or reject early data. The callback is provided with a +pointer to the user data argument that was provided when the callback was first +set. Returning 1 from the callback will allow early data and returning 0 will +reject it. Note that the OpenSSL library may reject early data for other reasons +in which case this callback will not get called. Notably, the built\-in replay +protection feature will still be used even if a callback is present unless it +has been explicitly disabled using the SSL_OP_NO_ANTI_REPLAY option. See +"REPLAY PROTECTION" below. +.PP +These functions cannot currently be used with QUIC SSL objects. +\&\fBSSL_set_max_early_data()\fR, \fBSSL_set_recv_max_early_data()\fR, \fBSSL_write_early_data()\fR, +\&\fBSSL_read_early_data()\fR, \fBSSL_get_early_data_status()\fR and +\&\fBSSL_set_allow_early_data_cb()\fR fail if called on a QUIC SSL object. +.SH NOTES +.IX Header "NOTES" +The whole purpose of early data is to enable a client to start sending data to +the server before a full round trip of network traffic has occurred. Application +developers should ensure they consider optimisation of the underlying TCP socket +to obtain a performant solution. For example Nagle\*(Aqs algorithm is commonly used +by operating systems in an attempt to avoid lots of small TCP packets. In many +scenarios this is beneficial for performance, but it does not work well with the +early data solution as implemented in OpenSSL. In Nagle\*(Aqs algorithm the OS will +buffer outgoing TCP data if a TCP packet has already been sent which we have not +yet received an ACK for from the peer. The buffered data will only be +transmitted if enough data to fill an entire TCP packet is accumulated, or if +the ACK is received from the peer. The initial ClientHello will be sent in the +first TCP packet along with any data from the first call to +\&\fBSSL_write_early_data()\fR. If the amount of data written will exceed the size of a +single TCP packet, or if there are more calls to \fBSSL_write_early_data()\fR then +that additional data will be sent in subsequent TCP packets which will be +buffered by the OS and not sent until an ACK is received for the first packet +containing the ClientHello. This means the early data is not actually +sent until a complete round trip with the server has occurred which defeats the +objective of early data. +.PP +In many operating systems the TCP_NODELAY socket option is available to disable +Nagle\*(Aqs algorithm. If an application opts to disable Nagle\*(Aqs algorithm +consideration should be given to turning it back on again after the handshake is +complete if appropriate. +.PP +In rare circumstances, it may be possible for a client to have a session that +reports a max early data value greater than 0, but where the server does not +support this. For example, this can occur if a server has had its configuration +changed to accept a lower max early data value such as by calling +\&\fBSSL_CTX_set_recv_max_early_data()\fR. Another example is if a server used to +support TLSv1.3 but was later downgraded to TLSv1.2. Sending early data to such +a server will cause the connection to abort. Clients that encounter an aborted +connection while sending early data may want to retry the connection without +sending early data as this does not happen automatically. A client will have to +establish a new transport layer connection to the server and attempt the SSL/TLS +connection again but without sending early data. Note that it is inadvisable to +retry with a lower maximum protocol version. +.SH "REPLAY PROTECTION" +.IX Header "REPLAY PROTECTION" +When early data is in use the TLS protocol provides no security guarantees that +the same early data was not replayed across multiple connections. As a +mitigation for this issue OpenSSL automatically enables replay protection if the +server is configured with a nonzero max early data value. With replay +protection enabled sessions are forced to be single use only. If a client +attempts to reuse a session ticket more than once, then the second and +subsequent attempts will fall back to a full handshake (and any early data that +was submitted will be ignored). Note that single use tickets are enforced even +if a client does not send any early data. +.PP +The replay protection mechanism relies on the internal OpenSSL server session +cache (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)). When replay protection is +being used the server will operate as if the SSL_OP_NO_TICKET option had been +selected (see \fBSSL_CTX_set_options\fR\|(3)). Sessions will be added to the cache +whenever a session ticket is issued. When a client attempts to resume the +session, OpenSSL will check for its presence in the internal cache. If it exists +then the resumption is allowed and the session is removed from the cache. If it +does not exist then the resumption is not allowed and a full handshake will +occur. +.PP +Note that some applications may maintain an external cache of sessions (see +\&\fBSSL_CTX_sess_set_new_cb\fR\|(3) and similar functions). It is the application\*(Aqs +responsibility to ensure that any sessions in the external cache are also +populated in the internal cache and that once removed from the internal cache +they are similarly removed from the external cache. Failing to do this could +result in an application becoming vulnerable to replay attacks. Note that +OpenSSL will lock the internal cache while a session is removed but that lock is +not held when the remove session callback (see \fBSSL_CTX_sess_set_remove_cb\fR\|(3)) +is called. This could result in a small amount of time where the session has +been removed from the internal cache but is still available in the external +cache. Applications should be designed with this in mind in order to minimise +the possibility of replay attacks. +.PP +The OpenSSL replay protection does not apply to external Pre Shared Keys (PSKs) +(e.g. see \fBSSL_CTX_set_psk_find_session_callback\fR\|(3)). Therefore, extreme caution +should be applied when combining external PSKs with early data. +.PP +Some applications may mitigate the replay risks in other ways. For those +applications it is possible to turn off the built\-in replay protection feature +using the \fBSSL_OP_NO_ANTI_REPLAY\fR option. See \fBSSL_CTX_set_options\fR\|(3) for +details. Applications can also set a callback to make decisions about accepting +early data or not. See \fBSSL_CTX_set_allow_early_data_cb()\fR above for details. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_write_early_data()\fR returns 1 for success or 0 for failure. In the event of a +failure call \fBSSL_get_error\fR\|(3) to determine the correct course of action. +.PP +\&\fBSSL_read_early_data()\fR returns SSL_READ_EARLY_DATA_ERROR for failure, +SSL_READ_EARLY_DATA_SUCCESS for success with more data to read and +SSL_READ_EARLY_DATA_FINISH for success with no more to data be read. In the +event of a failure call \fBSSL_get_error\fR\|(3) to determine the correct course of +action. +.PP +\&\fBSSL_get_max_early_data()\fR, \fBSSL_CTX_get_max_early_data()\fR and +\&\fBSSL_SESSION_get_max_early_data()\fR return the maximum number of early data bytes +that may be sent. +.PP +\&\fBSSL_set_max_early_data()\fR, \fBSSL_CTX_set_max_early_data()\fR and +\&\fBSSL_SESSION_set_max_early_data()\fR return 1 for success or 0 for failure. +.PP +\&\fBSSL_get_early_data_status()\fR returns SSL_EARLY_DATA_ACCEPTED if early data was +accepted by the server, SSL_EARLY_DATA_REJECTED if early data was rejected by +the server, or SSL_EARLY_DATA_NOT_SENT if no early data was sent. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), +\&\fBSSL_write_ex\fR\|(3), +\&\fBSSL_read_ex\fR\|(3), +\&\fBSSL_connect\fR\|(3), +\&\fBSSL_accept\fR\|(3), +\&\fBSSL_do_handshake\fR\|(3), +\&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3), +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of the functions described above were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_rstate_string.3 b/static/netbsd/man3/SSL_rstate_string.3 new file mode 100644 index 00000000..c807ca97 --- /dev/null +++ b/static/netbsd/man3/SSL_rstate_string.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: SSL_rstate_string.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_rstate_string 3" +.TH SSL_rstate_string 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_rstate_string, SSL_rstate_string_long \- get textual description of state of an SSL object during read operation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_rstate_string(SSL *ssl); +\& const char *SSL_rstate_string_long(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_rstate_string()\fR returns a 2 letter string indicating the current read state +of the SSL object \fBssl\fR. +.PP +\&\fBSSL_rstate_string_long()\fR returns a string indicating the current read state of +the SSL object \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +When performing a read operation, the SSL/TLS engine must parse the record, +consisting of header and body. When working in a blocking environment, +SSL_rstate_string[_long]() should always return "RD"/"read done". +.PP +This function should only seldom be needed in applications. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_rstate_string()\fR and \fBSSL_rstate_string_long()\fR can return the following +values: +.IP """RH""/""read header""" 4 +.IX Item """RH""/""read header""" +The header of the record is being evaluated. +.IP """RB""/""read body""" 4 +.IX Item """RB""/""read body""" +The body of the record is being evaluated. +.IP """unknown""/""unknown""" 4 +.IX Item """unknown""/""unknown""" +The read state is unknown. This should never happen. +.PP +When used with QUIC SSL objects, these functions always return "RH"/"read +header" in normal conditions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_session_reused.3 b/static/netbsd/man3/SSL_session_reused.3 new file mode 100644 index 00000000..0ad1cc91 --- /dev/null +++ b/static/netbsd/man3/SSL_session_reused.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: SSL_session_reused.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_session_reused 3" +.TH SSL_session_reused 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_session_reused \- query whether a reused session was negotiated during handshake +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_session_reused(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Query, whether a reused session was negotiated during the handshake. +.SH NOTES +.IX Header "NOTES" +During the negotiation, a client can propose to reuse a session. The server +then looks up the session in its cache. If both client and server agree +on the session, it will be reused and a flag is being set that can be +queried by the application. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +A new session was negotiated. +.IP 1 4 +.IX Item "1" +A session was reused. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set1_host.3 b/static/netbsd/man3/SSL_set1_host.3 new file mode 100644 index 00000000..10b5178f --- /dev/null +++ b/static/netbsd/man3/SSL_set1_host.3 @@ -0,0 +1,186 @@ +.\" $NetBSD: SSL_set1_host.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set1_host 3" +.TH SSL_set1_host 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername \- +SSL server verification parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set1_host(SSL *s, const char *host); +\& int SSL_add1_host(SSL *s, const char *host); +\& void SSL_set_hostflags(SSL *s, unsigned int flags); +\& const char *SSL_get0_peername(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions configure server hostname checks in the SSL client. +.PP +\&\fBSSL_set1_host()\fR sets in the verification parameters of \fIs\fR +the expected DNS hostname or IP address to \fIhost\fR, +clearing any previously specified IP address and hostnames. +If \fIhost\fR is NULL or the empty string, IP address +and hostname checks are not performed on the peer certificate. +When a nonempty \fIhost\fR is specified, certificate verification automatically +checks the peer hostname via \fBX509_check_host\fR\|(3) with \fIflags\fR as specified +via \fBSSL_set_hostflags()\fR. Clients that enable DANE TLSA authentication +via \fBSSL_dane_enable\fR\|(3) should leave it to that function to set +the primary reference identifier of the peer, and should not call +\&\fBSSL_set1_host()\fR. +.PP +\&\fBSSL_add1_host()\fR adds \fIhost\fR as an additional reference identifier +that can match the peer\*(Aqs certificate. Any previous hostnames +set via \fBSSL_set1_host()\fR or \fBSSL_add1_host()\fR are retained. +Adding an IP address is allowed only if no IP address has been set before. +No change is made if \fIhost\fR is NULL or empty. +When an IP address and/or multiple hostnames are configured, +the peer is considered verified when any of these matches. +This function is required for DANE TLSA in the presence of service name indirection +via CNAME, MX or SRV records as specified in RFCs 7671, 7672, and 7673. +.PP +TLS clients are recommended to use \fBSSL_set1_host()\fR or \fBSSL_add1_host()\fR +for server hostname or IP address validation, +as well as \fBSSL_set_tlsext_host_name\fR\|(3) for Server Name Indication (SNI), +which may be crucial also for correct routing of the connection request. +.PP +\&\fBSSL_set_hostflags()\fR sets the \fIflags\fR that will be passed to +\&\fBX509_check_host\fR\|(3) when name checks are applicable, by default +the \fIflags\fR value is 0. See \fBX509_check_host\fR\|(3) for the list +of available flags and their meaning. +.PP +\&\fBSSL_get0_peername()\fR returns the DNS hostname or subject CommonName +from the peer certificate that matched one of the reference +identifiers. When wildcard matching is not disabled, the name +matched in the peer certificate may be a wildcard name. When one +of the reference identifiers configured via \fBSSL_set1_host()\fR or +\&\fBSSL_add1_host()\fR starts with ".", which indicates a parent domain prefix +rather than a fixed name, the matched peer name may be a sub\-domain +of the reference identifier. The returned string is allocated by +the library and is no longer valid once the associated \fIssl\fR handle +is cleared or freed, or a renegotiation takes place. Applications +must not free the return value. +.PP +SSL clients are advised to use these functions in preference to +explicitly calling \fBX509_check_host\fR\|(3). Hostname checks may be out +of scope with the RFC 7671 \fBDANE\-EE\fR\|(3) certificate usage, and the +internal check will be suppressed as appropriate when DANE is +enabled. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set1_host()\fR and \fBSSL_add1_host()\fR return 1 for success and 0 for +failure. +.PP +\&\fBSSL_set_hostflags()\fR returns nothing at all. +.PP +\&\fBSSL_get0_peername()\fR returns NULL if peername verification is not +applicable (as with RFC 7671 \fBDANE\-EE\fR\|(3)), or no trusted peername was +matched. Otherwise, it returns the matched peername. To determine +whether verification succeeded call \fBSSL_get_verify_result\fR\|(3). +.SH EXAMPLES +.IX Header "EXAMPLES" +Suppose "smtp.example.com" is the MX host of the domain "example.com". +The calls below will arrange to match either the MX hostname or the +destination domain name in the SMTP server certificate. Wildcards +are supported, but must match the entire label. The actual name +matched in the certificate (which might be a wildcard) is retrieved, +and must be copied by the application if it is to be retained beyond +the lifetime of the SSL connection. +.PP +.Vb 5 +\& SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); +\& if (!SSL_set1_host(ssl, "smtp.example.com")) +\& /* error */ +\& if (!SSL_add1_host(ssl, "example.com")) +\& /* error */ +\& +\& /* XXX: Perform SSL_connect() handshake and handle errors here */ +\& +\& if (SSL_get_verify_result(ssl) == X509_V_OK) { +\& const char *peername = SSL_get0_peername(ssl); +\& +\& if (peername != NULL) +\& /* Name checks were in scope and matched the peername */ +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBX509_check_host\fR\|(3), \fBSSL_set_tlsext_host_name\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), \fBSSL_dane_enable\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set1_initial_peer_addr.3 b/static/netbsd/man3/SSL_set1_initial_peer_addr.3 new file mode 100644 index 00000000..70da3085 --- /dev/null +++ b/static/netbsd/man3/SSL_set1_initial_peer_addr.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: SSL_set1_initial_peer_addr.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set1_initial_peer_addr 3" +.TH SSL_set1_initial_peer_addr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set1_initial_peer_addr \- set the initial peer address for a QUIC connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *addr); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set1_initial_peer_addr()\fR sets the initial destination peer address to be used +for the purposes of establishing a QUIC connection in client mode. This function +can be used only on a QUIC connection SSL object, and can be used only before a +connection attempt is first made. \fIaddr\fR must point to a \fBBIO_ADDR\fR +representing a UDP destination address of the server to connect to. +.PP +Where a QUIC connection object is provided with a write BIO which supports the +\&\fBBIO_CTRL_DGRAM_GET_PEER\fR control (for example, \fBBIO_s_dgram\fR), the initial +destination peer address can be detected automatically; if +\&\fBBIO_CTRL_DGRAM_GET_PEER\fR returns a valid (non\-\fBAF_UNSPEC\fR) peer address and +no valid peer address has yet been set, this will be set automatically as the +initial peer address. This behaviour can be overridden by calling +\&\fBSSL_set1_initial_peer_addr()\fR with a valid peer address explicitly. +.PP +The destination address used by QUIC may change over time in response to +connection events, such as connection migration (where supported). +\&\fBSSL_set1_initial_peer_addr()\fR configures the destination address used for initial +connection establishment, and does not confer any guarantee about the +destination address being used for communication at any later time in the +connection lifecycle. +.PP +This function makes a copy of the address passed by the caller; the \fBBIO_ADDR\fR +structure pointed to by \fIaddr\fR may be freed by the caller after this function +returns. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_ADDR\fR\|(3), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_set1_initial_peer_addr()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set1_server_cert_type.3 b/static/netbsd/man3/SSL_set1_server_cert_type.3 new file mode 100644 index 00000000..deefa2d7 --- /dev/null +++ b/static/netbsd/man3/SSL_set1_server_cert_type.3 @@ -0,0 +1,250 @@ +.\" $NetBSD: SSL_set1_server_cert_type.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set1_server_cert_type 3" +.TH SSL_set1_server_cert_type 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set1_client_cert_type, +SSL_set1_server_cert_type, +SSL_CTX_set1_client_cert_type, +SSL_CTX_set1_server_cert_type, +SSL_get0_client_cert_type, +SSL_get0_server_cert_type, +SSL_CTX_get0_client_cert_type, +SSL_CTX_get0_server_cert_type \- certificate type (RFC7250) support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set1_client_cert_type(SSL *s, const unsigned char *val, size_t len); +\& int SSL_set1_server_cert_type(SSL *s, const unsigned char *val, size_t len); +\& int SSL_CTX_set1_client_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len); +\& int SSL_CTX_set1_server_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len); +\& int SSL_get0_client_cert_type(const SSL *s, unsigned char **val, size_t *len); +\& int SSL_get0_server_cert_type(const SSL *s, unsigned char **val, size_t *len); +\& int SSL_CTX_get0_client_cert_type(const SSL_CTX *ctx, unsigned char **val, size_t *len); +\& int SSL_CTX_get0_server_cert_type(const SSL_CTX *s, unsigned char **val, size_t *len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_set1_client_cert_type()\fR and \fBSSL_CTX_set1_client_cert_type()\fR functions +set the values for the client certificate type extension. +The \fBSSL_get0_client_cert_type()\fR and \fBSSL_CTX_get0_client_cert_type()\fR functions +retrieve the local values to be used in the client certificate type extension. +.PP +The \fBSSL_set1_server_cert_type()\fR and \fBSSL_CTX_set1_server_cert_type()\fR functions +set the values for the server certificate type extension. +The \fBSSL_get0_server_cert_type()\fR and \fBSSL_CTX_get0_server_cert_type()\fR functions +retrieve the local values to be used in the server certificate type extension. +.SH NOTES +.IX Header "NOTES" +The certificate type extensions are used to negotiate the certificate type to +be used in the handshake. +These extensions let each side know what its peer is able to accept. +.PP +The client certificate type is sent from the client to the server to indicate +what certificate types the client is able to present. +Values are configured in preference order. +On the server, this setting determines which certificate types the server is +willing to accept. +The server ultimately chooses what type to request (if any) from the values +that are mutually supported. +By default (if no explicit settings are specified), only X.509 certificates +are supported. +.PP +The server certificate type is sent from the client to the server to indicate +what certificate types the client accepts. +Values are configured in preference order. +On the server, this setting determines which certificate types the server is +willing to present. +The server ultimately chooses what type to use from the values that are +mutually supported. +By default (if no explicit settings are specified), only X.509 certificates +are supported. +.PP +Having RPK specified first means that side will attempt to send (or request) +RPKs if its peer also supports RPKs, otherwise X.509 certificate will be used +if both have specified that (or have not configured these options). +.PP +The two supported values in the \fBval\fR array are: +.IP TLSEXT_cert_type_x509 4 +.IX Item "TLSEXT_cert_type_x509" +Which corresponds to an X.509 certificate normally used in TLS. +.IP TLSEXT_cert_type_rpk 4 +.IX Item "TLSEXT_cert_type_rpk" +Which corresponds to a raw public key. +.PP +If \fBval\fR is set to a non\-NULL value, then the extension is sent in the handshake. +If b is set to a NULL value (and \fBlen\fR is 0), then the extension is +disabled. The default value is NULL, meaning the extension is not sent, and +X.509 certificates are used in the handshake. +.PP +Raw public keys may be used in place of certificates when specified in the +certificate type and negotiated. +Raw public keys have no subject, issuer, validity dates or digital signature. +.PP +Use the \fBSSL_get_negotiated_client_cert_type\fR\|(3) and +\&\fBSSL_get_negotiated_server_cert_type\fR\|(3) functions to get the negotiated cert +type values (at the conclusion of the handshake, or in callbacks that happen +after the TLS ServerHello has been processed). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return 1 on success and 0 on failure. +.PP +The memory returned from the get0 functions must not be freed. +.SH EXAMPLES +.IX Header "EXAMPLES" +To use raw public keys on the server, set up the SSL_CTX and SSL as follows: +.PP +.Vb 4 +\& SSL_CTX *ctx; +\& SSL *ssl; +\& unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 }; +\& EVP_PKEY *rpk; +\& +\& /* Assign rpk to an EVP_PKEY from a file or other means */ +\& +\& if ((ctx = SSL_CTX_new(TLS_server_method())) == NULL) +\& /* error */ +\& if ((ssl = SSL_new(ctx)) == NULL) +\& /* error */ +\& if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type))) +\& /* error */ +\& +\& /* A certificate does not need to be specified when using raw public keys */ +\& if (!SSL_use_PrivateKey(ssl, rpk)) +\& /* error */ +\& +\& /* Perform SSL_accept() operations */ +.Ve +.PP +To connect to this server, set the client SSL_CTX and SSL as follows: +.PP +.Vb 1 +\& /* Connect function */ +\& +\& SSL_CTX *ctx; +\& SSL *ssl; +\& const char *dane_tlsa_domain = "smtp.example.com"; +\& unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 }; +\& EVP_PKEY *rpk; +\& int verify_result; +\& +\& /* Assign rpk to an EVP_PKEY from a file or other means */ +\& +\& if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) +\& /* error */ +\& if (SSL_CTX_dane_enable(ctx) <= 0) +\& /* error */ +\& if ((ssl = SSL_new(ctx)) == NULL) +\& /* error */ +\& /* +\& * The \`dane_tlsa_domain\` arguments sets the default SNI hostname. +\& * It may be set to NULL when enabling DANE on the server side. +\& */ +\& if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) +\& /* error */ +\& if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type))) +\& /* error */ +\& if (!SSL_add_expected_rpk(ssl, rpk)) +\& /* error */ +\& +\& /* Do SSL_connect() handshake and handle errors here */ +\& +\& /* Optional: verify the peer RPK */ +\& verify_result = SSL_get_verify_result(ssl); +\& if (verify_result == X509_V_OK) { +\& /* The server\*(Aqs raw public key matched the TLSA record */ +\& } else if (verify_result == X509_V_ERR_DANE_NO_MATCH) { +\& /* +\& * The server\*(Aqs raw public key, or public key in certificate, did not +\& * match the TLSA record +\& */ +\& } else if (verify_result == X509_V_ERR_RPK_UNTRUSTED) { +\& /* +\& * No TLSA records of the correct type are available to verify the +\& * server\*(Aqs raw public key. This would not happen in this example, +\& * as a TLSA record is configured. +\& */ +\& } else { +\& /* Some other verify error */ +\& } +.Ve +.PP +To validate client raw public keys, code from the client example may need to be +incorporated into the server side. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get0_peer_rpk\fR\|(3), +\&\fBSSL_get_negotiated_client_cert_type\fR\|(3), +\&\fBSSL_get_negotiated_server_cert_type\fR\|(3), +\&\fBSSL_use_certificate\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. diff --git a/static/netbsd/man3/SSL_set_async_callback.3 b/static/netbsd/man3/SSL_set_async_callback.3 new file mode 100644 index 00000000..07e7a732 --- /dev/null +++ b/static/netbsd/man3/SSL_set_async_callback.3 @@ -0,0 +1,165 @@ +.\" $NetBSD: SSL_set_async_callback.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_async_callback 3" +.TH SSL_set_async_callback 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_CTX_set_async_callback, +SSL_CTX_set_async_callback_arg, +SSL_set_async_callback, +SSL_set_async_callback_arg, +SSL_get_async_status, +SSL_async_callback_fn +\&\- manage asynchronous operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*SSL_async_callback_fn)(SSL *s, void *arg); +\& int SSL_CTX_set_async_callback(SSL_CTX *ctx, SSL_async_callback_fn callback); +\& int SSL_CTX_set_async_callback_arg(SSL_CTX *ctx, void *arg); +\& int SSL_set_async_callback(SSL *s, SSL_async_callback_fn callback); +\& int SSL_set_async_callback_arg(SSL *s, void *arg); +\& int SSL_get_async_status(SSL *s, int *status); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_CTX_set_async_callback()\fR sets an asynchronous callback function. All \fBSSL\fR +objects generated based on this \fBSSL_CTX\fR will get this callback. If an engine +supports the callback mechanism, it will be automatically called if +\&\fBSSL_MODE_ASYNC\fR has been set and an asynchronous capable engine completes a +cryptography operation to notify the application to resume the paused work flow. +.PP +\&\fBSSL_CTX_set_async_callback_arg()\fR sets the callback argument. +.PP +\&\fBSSL_set_async_callback()\fR allows an application to set a callback in an +asynchronous \fBSSL\fR object, so that when an engine completes a cryptography +operation, the callback will be called to notify the application to resume the +paused work flow. +.PP +\&\fBSSL_set_async_callback_arg()\fR sets an argument for the \fBSSL\fR object when the +above callback is called. +.PP +\&\fBSSL_get_async_status()\fR returns the engine status. This function facilitates the +communication from the engine to the application. During an SSL session, +cryptographic operations are dispatched to an engine. The engine status is very +useful for an application to know if the operation has been successfully +dispatched. If the engine does not support this additional callback method, +\&\fBASYNC_STATUS_UNSUPPORTED\fR will be returned. See \fBASYNC_WAIT_CTX_set_status()\fR +for a description of all of the status values. +.PP +An example of the above functions would be the following: +.IP 1. 4 +Application sets the async callback and callback data on an SSL connection +by calling \fBSSL_set_async_callback()\fR. +.IP 2. 4 +Application sets \fBSSL_MODE_ASYNC\fR and makes an asynchronous SSL call +.IP 3. 4 +OpenSSL submits the asynchronous request to the engine. If a retry occurs at +this point then the status within the \fBASYNC_WAIT_CTX\fR would be set and the +async callback function would be called (goto Step 7). +.IP 4. 4 +The OpenSSL engine pauses the current job and returns, so that the +application can continue processing other connections. +.IP 5. 4 +At a future point in time (probably via a polling mechanism or via an +interrupt) the engine will become aware that the asynchronous request has +finished processing. +.IP 6. 4 +The engine will call the application\*(Aqs callback passing the callback data as +a parameter. +.IP 7. 4 +The callback function should then run. Note: it is a requirement that the +callback function is small and nonblocking as it will be run in the context of +a polling mechanism or an interrupt. +.IP 8. 4 +It is the application\*(Aqs responsibility via the callback function to schedule +recalling the OpenSSL asynchronous function and to continue processing. +.IP 9. 4 +The callback function has the option to check the status returned via +\&\fBSSL_get_async_status()\fR to determine whether a retry happened instead of the +request being submitted, allowing different processing if required. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_CTX_set_async_callback()\fR, \fBSSL_set_async_callback()\fR, +\&\fBSSL_CTX_set_async_callback_arg()\fR, \fBSSL_CTX_set_async_callback_arg()\fR and +\&\fBSSL_get_async_status()\fR return 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_CTX_set_async_callback()\fR, \fBSSL_CTX_set_async_callback_arg()\fR, +\&\fBSSL_set_async_callback()\fR, \fBSSL_set_async_callback_arg()\fR and +\&\fBSSL_get_async_status()\fR were first added to OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_bio.3 b/static/netbsd/man3/SSL_set_bio.3 new file mode 100644 index 00000000..35b06a07 --- /dev/null +++ b/static/netbsd/man3/SSL_set_bio.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: SSL_set_bio.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_bio 3" +.TH SSL_set_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio \- connect the SSL object with a BIO +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); +\& void SSL_set0_rbio(SSL *s, BIO *rbio); +\& void SSL_set0_wbio(SSL *s, BIO *wbio); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set0_rbio()\fR connects the BIO \fBrbio\fR for the read operations of the \fBssl\fR +object. The SSL engine inherits the behaviour of \fBrbio\fR. If the BIO is +nonblocking then the \fBssl\fR object will also have nonblocking behaviour. This +function transfers ownership of \fBrbio\fR to \fBssl\fR. It will be automatically +freed using \fBBIO_free_all\fR\|(3) when the \fBssl\fR is freed. On calling this +function, any existing \fBrbio\fR that was previously set will also be freed via a +call to \fBBIO_free_all\fR\|(3) (this includes the case where the \fBrbio\fR is set to +the same value as previously). +.PP +If using a custom BIO, \fBrbio\fR must implement either +\&\fBBIO_meth_set_read_ex\fR\|(3) or \fBBIO_meth_set_read\fR\|(3). +.PP +\&\fBSSL_set0_wbio()\fR works in the same as \fBSSL_set0_rbio()\fR except that it connects +the BIO \fBwbio\fR for the write operations of the \fBssl\fR object. Note that if the +rbio and wbio are the same then \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR each take +ownership of one reference. Therefore, it may be necessary to increment the +number of references available using \fBBIO_up_ref\fR\|(3) before calling the set0 +functions. +.PP +If using a custom BIO, \fBwbio\fR must implement +\&\fBBIO_meth_set_write_ex\fR\|(3) or \fBBIO_meth_set_write\fR\|(3). It additionally must +implement \fBBIO_flush\fR\|(3) using \fBBIO_CTRL_FLUSH\fR and \fBBIO_meth_set_ctrl\fR\|(3). +If flushing is unnecessary with \fBwbio\fR, \fBBIO_flush\fR\|(3) should return one and +do nothing. +.PP +\&\fBSSL_set_bio()\fR is similar to \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR except +that it connects both the \fBrbio\fR and the \fBwbio\fR at the same time, and +transfers the ownership of \fBrbio\fR and \fBwbio\fR to \fBssl\fR according to +the following set of rules: +.IP \(bu 2 +If neither the \fBrbio\fR or \fBwbio\fR have changed from their previous values +then nothing is done. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are different and both are different +to their +previously set values then one reference is consumed for the rbio and one +reference is consumed for the wbio. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are the same and the \fBrbio\fR is not +the same as the previously set value then one reference is consumed. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are the same and the \fBrbio\fR is the +same as the previously set value, then no additional references are consumed. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBrbio\fR is the +same as the +previously set value then one reference is consumed for the \fBwbio\fR and no +references are consumed for the \fBrbio\fR. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBwbio\fR is the +same as the previously set value and the old \fBrbio\fR and \fBwbio\fR values +were the same as each other then one reference is consumed for the \fBrbio\fR +and no references are consumed for the \fBwbio\fR. +.IP \(bu 2 +If the \fBrbio\fR and \fBwbio\fR parameters are different and the \fBwbio\fR +is the same as the +previously set value and the old \fBrbio\fR and \fBwbio\fR values were different +to each other, then one reference is consumed for the \fBrbio\fR and one +reference is consumed for the \fBwbio\fR. +.PP +Because of this complexity, this function should be avoided; +use \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR instead. +.PP +Where a new BIO is set on a QUIC connection SSL object, blocking mode will be +disabled on that SSL object if the BIO cannot support blocking mode. If another +BIO is subsequently set on the SSL object which can support blocking mode, +blocking mode will not be automatically re\-enabled. For more information, see +\&\fBSSL_set_blocking_mode\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_bio()\fR, \fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR cannot fail. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_rbio\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBssl\fR\|(7), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_set0_rbio()\fR and \fBSSL_set0_wbio()\fR were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_blocking_mode.3 b/static/netbsd/man3/SSL_set_blocking_mode.3 new file mode 100644 index 00000000..72b2f552 --- /dev/null +++ b/static/netbsd/man3/SSL_set_blocking_mode.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: SSL_set_blocking_mode.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_blocking_mode 3" +.TH SSL_set_blocking_mode 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_blocking_mode, SSL_get_blocking_mode \- configure blocking mode for a +QUIC SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set_blocking_mode(SSL *s, int blocking); +\& int SSL_get_blocking_mode(SSL *s); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_blocking_mode()\fR can be used to enable or disable blocking mode on a QUIC +connection SSL object. By default, blocking is enabled, unless the SSL object is +configured to use an underlying read or write BIO which cannot provide a poll +descriptor (see \fBBIO_get_rpoll_descriptor\fR\|(3)), as blocking mode cannot be +supported in this case. +.PP +To enable blocking mode, call \fBSSL_set_blocking_mode()\fR with \fIblocking\fR set to 1; +to disable it, call \fBSSL_set_blocking_mode()\fR with \fIblocking\fR set to 0. +.PP +To retrieve the current blocking mode, call \fBSSL_get_blocking_mode()\fR. +.PP +Blocking mode means that calls such as \fBSSL_read()\fR and \fBSSL_write()\fR will block +until the requested operation can be performed. In nonblocking mode, these +calls will fail if the requested operation cannot be performed immediately; see +\&\fBSSL_get_error\fR\|(3). +.PP +These functions are only applicable to QUIC connection SSL objects. Other kinds +of SSL object, such as those for TLS, automatically function in blocking or +nonblocking mode based on whether the underlying network read and write BIOs +provided to the SSL object are themselves configured in nonblocking mode. +.PP +Where a QUIC connection SSL object is used in nonblocking mode, an application +is responsible for ensuring that the SSL object is ticked regularly; see +\&\fBSSL_handle_events\fR\|(3). +.PP +Blocking mode is disabled automatically if the application provides a QUIC +connection SSL object with a network BIO which cannot support blocking mode. To +re\-enable blocking mode in this case, an application must set a network BIO +which can support blocking mode and explicitly call \fBSSL_set_blocking_mode()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_blocking_mode()\fR returns 1 on success and 0 on failure. The function +fails if called on an SSL object which does not represent a QUIC connection, +or if blocking mode cannot be used for the given connection. +.PP +\&\fBSSL_get_blocking_mode()\fR returns 1 if blocking is currently enabled. It returns +\&\-1 if called on an unsupported SSL object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_poll\fR\|(3), \fBopenssl\-quic\fR\|(7), +\&\fBopenssl\-quic\-concurrency\fR\|(7), \fBssl\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_set_blocking_mode()\fR and \fBSSL_get_blocking_mode()\fR functions were added in +OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_connect_state.3 b/static/netbsd/man3/SSL_set_connect_state.3 new file mode 100644 index 00000000..1320c075 --- /dev/null +++ b/static/netbsd/man3/SSL_set_connect_state.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: SSL_set_connect_state.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_connect_state 3" +.TH SSL_set_connect_state 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_connect_state, SSL_set_accept_state, SSL_is_server +\&\- functions for manipulating and examining the client or server mode of an SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_set_connect_state(SSL *ssl); +\& +\& void SSL_set_accept_state(SSL *ssl); +\& +\& int SSL_is_server(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_connect_state()\fR sets \fBssl\fR to work in client mode. +.PP +\&\fBSSL_set_accept_state()\fR sets \fBssl\fR to work in server mode. +.PP +\&\fBSSL_is_server()\fR checks if \fBssl\fR is working in server mode. +.SH NOTES +.IX Header "NOTES" +When the SSL_CTX object was created with \fBSSL_CTX_new\fR\|(3), +it was either assigned a dedicated client method, a dedicated server +method, or a generic method, that can be used for both client and +server connections. (The method might have been changed with +\&\fBSSL_CTX_set_ssl_version\fR\|(3) or +\&\fBSSL_set_ssl_method\fR\|(3).) +.PP +When beginning a new handshake, the SSL engine must know whether it must +call the connect (client) or accept (server) routines. Even though it may +be clear from the method chosen, whether client or server mode was +requested, the handshake routines must be explicitly set. +.PP +When using the \fBSSL_connect\fR\|(3) or +\&\fBSSL_accept\fR\|(3) routines, the correct handshake +routines are automatically set. When performing a transparent negotiation +using \fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3), or \fBSSL_read\fR\|(3), +the handshake routines must be explicitly set in advance using either +\&\fBSSL_set_connect_state()\fR or \fBSSL_set_accept_state()\fR. +.PP +If \fBSSL_is_server()\fR is called before \fBSSL_set_connect_state()\fR or +\&\fBSSL_set_accept_state()\fR is called (either automatically or explicitly), +the result depends on what method was used when SSL_CTX was created with +\&\fBSSL_CTX_new\fR\|(3). If a generic method or a dedicated server method was +passed to \fBSSL_CTX_new\fR\|(3), \fBSSL_is_server()\fR returns 1; otherwise, it returns 0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_connect_state()\fR and \fBSSL_set_accept_state()\fR do not return diagnostic +information. +.PP +\&\fBSSL_is_server()\fR returns 1 if \fBssl\fR is working in server mode or 0 for client mode. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_CTX_new\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3), +\&\fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), +\&\fBSSL_do_handshake\fR\|(3), +\&\fBSSL_CTX_set_ssl_version\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_default_stream_mode.3 b/static/netbsd/man3/SSL_set_default_stream_mode.3 new file mode 100644 index 00000000..c6d32803 --- /dev/null +++ b/static/netbsd/man3/SSL_set_default_stream_mode.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: SSL_set_default_stream_mode.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_default_stream_mode 3" +.TH SSL_set_default_stream_mode 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_default_stream_mode, +SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI, +SSL_DEFAULT_STREAM_MODE_AUTO_UNI \- manage the default stream for a QUIC +connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_DEFAULT_STREAM_MODE_NONE +\& #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI +\& #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI +\& +\& int SSL_set_default_stream_mode(SSL *conn, uint32_t mode); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A QUIC connection SSL object may have a default stream attached to it. A default +stream is a QUIC stream to which calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) +made on a QUIC connection SSL object are redirected. Default stream handling +allows legacy applications to use QUIC similarly to a traditional TLS +connection. +.PP +When not disabled, a default stream is automatically created on an outgoing +connection once \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called. +.PP +A QUIC stream must be explicitly designated as client\-initiated or +server\-initiated up front. This broadly corresponds to whether an application +protocol involves the client transmitting first, or the server transmitting +first. As such, if \fBSSL_read\fR\|(3) is called first (before any call to +\&\fBSSL_write\fR\|(3)) after establishing a connection, OpenSSL will wait for the +server to open the first server\-initiated stream, and then bind this as the +default stream. Conversely, if \fBSSL_write\fR\|(3) is called before any call to +\&\fBSSL_read\fR\|(3), OpenSSL assumes the client wishes to transmit first, creates a +client\-initiated stream, and binds this as the default stream. +.PP +By default, the default stream created is bidirectional. If a unidirectional +stream is desired, or if the application wishes to disable default stream +functionality, \fBSSL_set_default_stream_mode()\fR (discussed below) can be used to +accomplish this. +.PP +When a QUIC connection SSL object has no default stream currently associated +with it, for example because default stream functionality was disabled, calls to +functions which require a stream on the QUIC connection SSL object (for example, +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)) will fail. +.PP +It is recommended that new applications and applications which rely on multiple +streams forego use of the default stream functionality, which is intended for +legacy applications. +.PP +\&\fBSSL_set_default_stream_mode()\fR can be used to configure or disable default stream +handling. It can only be called on a QUIC connection SSL object prior to any +default stream being created. If used, it is recommended to call it immediately +after calling \fBSSL_new\fR\|(3), prior to initiating a connection. The argument +\&\fImode\fR may be one of the following options: +.IP SSL_DEFAULT_STREAM_MODE_AUTO_BIDI 4 +.IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_BIDI" +This is the default setting. If \fBSSL_write\fR\|(3) is called prior to any call to +\&\fBSSL_read\fR\|(3), a bidirectional client\-initiated stream is created and bound as +the default stream. If \fBSSL_read\fR\|(3) is called prior to any call to +\&\fBSSL_write\fR\|(3), OpenSSL waits for an incoming stream from the peer (causing +\&\fBSSL_read\fR\|(3) to block if the connection is in blocking mode), and then binds +that stream as the default stream. Note that this incoming stream may be either +bidirectional or unidirectional; thus, this setting does not guarantee the +presence of a bidirectional stream when \fBSSL_read\fR\|(3) is called first. To +determine the type of a stream after a call to \fBSSL_read\fR\|(3), use +\&\fBSSL_get_stream_type\fR\|(3). +.IP SSL_DEFAULT_STREAM_MODE_AUTO_UNI 4 +.IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_UNI" +In this mode, if \fBSSL_write\fR\|(3) is called prior to any call to \fBSSL_read\fR\|(3), +a unidirectional client\-initiated stream is created and bound as the default +stream. The behaviour is otherwise identical to that of +\&\fBSSL_DEFAULT_STREAM_MODE_AUTO_BIDI\fR. The behaviour when \fBSSL_read\fR\|(3) is +called prior to any call to \fBSSL_write\fR\|(3) is unchanged. +.IP SSL_DEFAULT_STREAM_MODE_NONE 4 +.IX Item "SSL_DEFAULT_STREAM_MODE_NONE" +Default stream creation is inhibited. This is the recommended mode of operation. +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls cannot be made on the QUIC connection +SSL object directly. You must obtain streams using \fBSSL_new_stream\fR\|(3) or +\&\fBSSL_accept_stream\fR\|(3) in order to communicate with the peer. +.PP +A default stream will not be automatically created on a QUIC connection SSL +object if the default stream mode is set to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. +.PP +\&\fBSSL_set_incoming_stream_policy\fR\|(3) interacts significantly with the default +stream functionality. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_default_stream_mode()\fR returns 1 on success and 0 on failure. +.PP +\&\fBSSL_set_default_stream_mode()\fR fails if it is called after a default stream has +already been established. +.PP +These functions fail if called on a QUIC stream SSL object or on a non\-QUIC SSL +object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3), +\&\fBSSL_set_incoming_stream_policy\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_fd.3 b/static/netbsd/man3/SSL_set_fd.3 new file mode 100644 index 00000000..20d1e6ab --- /dev/null +++ b/static/netbsd/man3/SSL_set_fd.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: SSL_set_fd.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_fd 3" +.TH SSL_set_fd 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_fd, SSL_set_rfd, SSL_set_wfd \- connect the SSL object with a file descriptor +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set_fd(SSL *ssl, int fd); +\& int SSL_set_rfd(SSL *ssl, int fd); +\& int SSL_set_wfd(SSL *ssl, int fd); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_fd()\fR sets the file descriptor \fBfd\fR as the input/output facility +for the TLS/SSL (encrypted) side of \fBssl\fR. \fBfd\fR will typically be the +socket file descriptor of a network connection. +.PP +When performing the operation, a \fBsocket BIO\fR is automatically created to +interface between the \fBssl\fR and \fBfd\fR. The BIO and hence the SSL engine +inherit the behaviour of \fBfd\fR. If \fBfd\fR is nonblocking, the \fBssl\fR will +also have nonblocking behaviour. +.PP +When used on a QUIC connection SSL object, a \fBdatagram BIO\fR is automatically +created instead of a \fBsocket BIO\fR. These functions fail if called +on a QUIC stream SSL object. +.PP +If there was already a BIO connected to \fBssl\fR, \fBBIO_free()\fR will be called +(for both the reading and writing side, if different). +.PP +\&\fBSSL_set_rfd()\fR and \fBSSL_set_wfd()\fR perform the respective action, but only +for the read channel or the write channel, which can be set independently. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The operation failed. Check the error stack to find out why. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.SH NOTES +.IX Header "NOTES" +On Windows, a socket handle is a 64\-bit data type (UINT_PTR), which leads to a +compiler warning (conversion from \*(AqSOCKET\*(Aq to \*(Aqint\*(Aq, possible loss of data) when +passing the socket handle to SSL_set_*\fBfd()\fR. For the time being, this warning can +safely be ignored, because although the Microsoft documentation claims that the +upper limit is INVALID_SOCKET\-1 (2^64 \- 2), in practice the current \fBsocket()\fR +implementation returns an index into the kernel handle table, the size of which +is limited to 2^24. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_fd\fR\|(3), \fBSSL_set_bio\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3), +\&\fBSSL_shutdown\fR\|(3), \fBssl\fR\|(7) , \fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_incoming_stream_policy.3 b/static/netbsd/man3/SSL_set_incoming_stream_policy.3 new file mode 100644 index 00000000..7305ade6 --- /dev/null +++ b/static/netbsd/man3/SSL_set_incoming_stream_policy.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: SSL_set_incoming_stream_policy.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_incoming_stream_policy 3" +.TH SSL_set_incoming_stream_policy 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_incoming_stream_policy, SSL_INCOMING_STREAM_POLICY_AUTO, +SSL_INCOMING_STREAM_POLICY_ACCEPT, +SSL_INCOMING_STREAM_POLICY_REJECT \- manage the QUIC incoming stream +policy +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_INCOMING_STREAM_POLICY_AUTO +\& #define SSL_INCOMING_STREAM_POLICY_ACCEPT +\& #define SSL_INCOMING_STREAM_POLICY_REJECT +\& +\& int SSL_set_incoming_stream_policy(SSL *conn, int policy, +\& uint64_t app_error_code); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_incoming_stream_policy()\fR policy changes the incoming stream policy for a +QUIC connection. Depending on the policy configured, OpenSSL QUIC may +automatically reject incoming streams initiated by the peer. This is intended to +ensure that legacy applications using single\-stream operation with a default +stream on a QUIC connection SSL object are not passed remotely\-initiated streams +by a peer which those applications are not prepared to handle. +.PP +\&\fIapp_error_code\fR is an application error code which will be used in any QUIC +\&\fBSTOP_SENDING\fR or \fBRESET_STREAM\fR frames generated to implement the policy. The +default application error code is 0. +.PP +The valid values for \fIpolicy\fR are: +.IP SSL_INCOMING_STREAM_POLICY_AUTO 4 +.IX Item "SSL_INCOMING_STREAM_POLICY_AUTO" +This is the default setting. Incoming streams are accepted according to the +following rules: +.RS 4 +.IP \(bu 4 +If the default stream mode (configured using \fBSSL_set_default_stream_mode\fR\|(3)) +is set to \fBSSL_DEFAULT_STREAM_MODE_AUTO_BIDI\fR (the default) or +\&\fBSSL_DEFAULT_STREAM_MODE_AUTO_UNI\fR, the incoming stream is rejected. +.IP \(bu 4 +Otherwise (where the default stream mode is \fBSSL_DEFAULT_STREAM_MODE_NONE\fR), +the application is assumed to be stream aware, and the incoming stream is +accepted. +.RE +.RS 4 +.RE +.IP SSL_INCOMING_STREAM_POLICY_ACCEPT 4 +.IX Item "SSL_INCOMING_STREAM_POLICY_ACCEPT" +Always accept incoming streams, allowing them to be dequeued using +\&\fBSSL_accept_stream\fR\|(3). +.IP SSL_INCOMING_STREAM_POLICY_REJECT 4 +.IX Item "SSL_INCOMING_STREAM_POLICY_REJECT" +Always reject incoming streams. +.PP +Where an incoming stream is rejected, it is rejected immediately and it is not +possible to gain access to the stream using \fBSSL_accept_stream\fR\|(3). The stream +is rejected using QUIC \fBSTOP_SENDING\fR and \fBRESET_STREAM\fR frames as +appropriate. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.PP +This function fails if called on a QUIC stream SSL object, or on a non\-QUIC SSL +object. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_set_default_stream_mode\fR\|(3), \fBSSL_accept_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_set_incoming_stream_policy()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_quic_tls_cbs.3 b/static/netbsd/man3/SSL_set_quic_tls_cbs.3 new file mode 100644 index 00000000..44593204 --- /dev/null +++ b/static/netbsd/man3/SSL_set_quic_tls_cbs.3 @@ -0,0 +1,248 @@ +.\" $NetBSD: SSL_set_quic_tls_cbs.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_quic_tls_cbs 3" +.TH SSL_set_quic_tls_cbs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn, +OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn, +OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn, +OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn, +OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn, +OSSL_FUNC_SSL_QUIC_TLS_alert_fn, +SSL_set_quic_tls_cbs, +SSL_set_quic_tls_transport_params, +SSL_set_quic_tls_early_data_enabled +\&\- Use the OpenSSL TLS implementation for a third party QUIC implementation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& /* QUIC TLS callbacks available via an OSSL_DISPATCH table */ +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s, +\& const unsigned char *buf, +\& size_t buf_len, +\& size_t *consumed, +\& void *arg); +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s, +\& const unsigned char **buf, +\& size_t *bytes_read, +\& void *arg); +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *, +\& size_t bytes_read, +\& void *arg); +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s, +\& uint32_t prot_level, +\& int direction, +\& const unsigned char *secret, +\& size_t secret_len, +\& void *arg); +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s, +\& const unsigned char *params, +\& size_t params_len, +\& void *arg); +\& +\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */ +\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s, +\& unsigned char alert_code, +\& void *arg); +\& +\& int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg); +\& int SSL_set_quic_tls_transport_params(SSL *s, +\& const unsigned char *params, +\& size_t params_len); +\& int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_quic_tls_cbs()\fR can be used to replace the standard TLS record layer with +a custom record layer for use by a third party QUIC implementation. For the +given SSL object \fIs\fR, a set of callbacks are supplied in an \fBOSSL_DISPATCH\fR +table via \fIqtdis\fR. The \fIarg\fR parameter will be passed as an argument when the +various callbacks are called. +.PP +The above callbacks are invoked, as needed, by \fBSSL_do_handshake()\fR and \fBSSL_read()\fR (including +SSL_read_ex, SSL_peek, SSL_peek_ex). Once the SSL handshake is complete, the QUIC +stack must arrange to call one of the \fBSSL_read()\fR variants whenever a post\-handshake CRYPTO +frame is received. The number of bytes requested may be zero. +.PP +An \fBOSSL_DISPATCH\fR table should consist of an array of \fBOSSL_DISPATCH\fR entries +where each entry is a function id, and a function pointer. The array should be +terminated with an empty entry (i.e. a 0 function id, and a NULL function +pointer). +.PP +Calling the \fBSSL_set_quic_tls_cbs()\fR function will switch off the +\&\fBSSL_OP_ENABLE_MIDDLEBOX_COMPAT\fR option (if set). See \fBSSL_set_options\fR\|(3). +Additionally the minimum TLS protocol version will be set to TLS1_3_VERSION. It +is an error to call this function with anything other than a TLS connection SSL +object. +.PP +The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND\fR) is called when CRYPTO frame data should +be sent to the peer. The data to be sent is supplied in the buffer \fIbuf\fR which +is of length \fIbuf_len\fR. The callback may choose to consume less data than was +supplied in the buffer. On successful completion of the callback the \fIconsumed\fR +parameter should be populated with the amount of data that the callback +consumed. This should be less than or equal to the value in \fIbuf_len\fR. CRYPTO +data should be sent using the most recent write encryption level set via the +OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called). +.PP +The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD\fR) is used to receive CRYPTO frame data +from the peer. When OpenSSL wants to read data from the peer this callback is +called. The callback should populate \fI*buf\fR with a pointer to a buffer +containing CRYPTO data that has been received from the peer. The size of the +buffer should be populated in \fI*bytes_read\fR. The buffer should remain valid +until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback. +CRYPTO frame data is assumed to have been decrypted using the most recent read +protection level set via the yield_secret_cb callback (if it has been called). +.PP +The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD\fR) is called when data previously +read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The +\&\fIbytes_read\fR argument is always equal to the size of the buffer previously +provided in the crypto_receive_rcd_cb callback. Only one record at a time will +ever be read by OpenSSL. +.PP +The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET\fR) is called when a new secret has been +established. The \fIprot_level\fR argument identities the TLS protection level and +will be one of \fBOSSL_RECORD_PROTECTION_LEVEL_NONE\fR, +\&\fBOSSL_RECORD_PROTECTION_LEVEL_EARLY\fR, \fBOSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE\fR +or \fBOSSL_RECORD_PROTECTION_LEVEL_APPLICATION\fR. The \fIdirection\fR will either be +0 (for the read secret) or 1 (for the write secret). The secret itself will +be in the buffer pointed to by \fIsecret\fR and the buffer will be of length +\&\fIsecret_len\fR. +.PP +The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS\fR) is called when transport +parameters have been received from the peer. The parameters are held in the +\&\fIparams\fR buffer which is of length \fIparams_len\fR. +.PP +The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id +\&\fBOSSL_FUNC_SSL_QUIC_TLS_ALERT\fR) is called when OpenSSL is attempting to send an +alert to the peer. The code for the alert is supplied in \fIalert_code\fR. +.PP +The \fBSSL_set_quic_tls_transport_params()\fR function is used to set the transport +parameters to be sent by this endpoint. The parameters are in the \fIparams\fR +buffer which should be of length \fIparams_len\fR. The buffer containing the +parameters should remain valid until after the parameters have been sent. This +function must have been called by the time the transport parameters need to be +sent. For a client this will be before the connection has been initiated. For a +server this might typically occur during the got_transport_params_cb. +.PP +The \fBSSL_set_quic_tls_early_data_enabled()\fR function is used to enable the 0\-RTT +feature for a third party QUIC implementation. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return 1 on success and 0 on failure. +.PP +All of the callbacks should also return 1 on success and 0 on failure. A +failure response is fatal to the connection. +.SH EXAMPLES +.IX Header "EXAMPLES" +A call to \fBSSL_set_quic_tls_cbs()\fR might look something like the following, given +suitable definitions of the various callback functions: +.PP +.Vb 10 +\& const OSSL_DISPATCH qtdis[] = { +\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb}, +\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD, +\& (void (*)(void))crypto_recv_rcd_cb}, +\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD, +\& (void (*)(void))crypto_release_rcd_cb}, +\& {OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET, +\& (void (*)(void))yield_secret_cb}, +\& {OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS, +\& (void (*)(void))got_transport_params_cb}, +\& {OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb}, +\& {0, NULL} +\& }; +\& +\& if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL)) +\& goto err; +.Ve +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_retry_verify.3 b/static/netbsd/man3/SSL_set_retry_verify.3 new file mode 100644 index 00000000..b77841c1 --- /dev/null +++ b/static/netbsd/man3/SSL_set_retry_verify.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: SSL_set_retry_verify.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_retry_verify 3" +.TH SSL_set_retry_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_retry_verify \- indicate that certificate verification should be retried +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set_retry_verify(SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_retry_verify()\fR should be called from the certificate verification +callback on a client when the application wants to indicate that the handshake +should be suspended and the control should be returned to the application. +\&\fBSSL_want_retry_verify\fR\|(3) will return 1 as a consequence until the handshake +is resumed again by the application, retrying the verification step. +.PP +Please refer to \fBSSL_CTX_set_cert_verify_callback\fR\|(3) for further details. +.SH NOTES +.IX Header "NOTES" +The effect of calling \fBSSL_set_retry_verify()\fR outside of the certificate +verification callback on the client side is undefined. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +SSL_set_retry \fBverify()\fR returns 1 on success, 0 otherwise. +.SH EXAMPLES +.IX Header "EXAMPLES" +The following code snippet shows how to obtain the \fBSSL\fR object associated +with the \fBX509_STORE_CTX\fR to call the \fBSSL_set_retry_verify()\fR function: +.PP +.Vb 2 +\& int idx = SSL_get_ex_data_X509_STORE_CTX_idx(); +\& SSL *ssl; +\& +\& /* this should not happen but check anyway */ +\& if (idx < 0 +\& || (ssl = X509_STORE_CTX_get_ex_data(ctx, idx)) == NULL) +\& return 0; +\& +\& if (/* we need to retry verification callback */) +\& return SSL_set_retry_verify(ssl); +\& +\& /* do normal processing of the verification callback */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_connect\fR\|(3), \fBSSL_CTX_set_cert_verify_callback\fR\|(3), +\&\fBSSL_want_retry_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_set_retry_verify()\fR was added in OpenSSL 3.0.2 to replace backwards +incompatible handling of a negative return value from the verification +callback. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_session.3 b/static/netbsd/man3/SSL_set_session.3 new file mode 100644 index 00000000..d8619baf --- /dev/null +++ b/static/netbsd/man3/SSL_set_session.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: SSL_set_session.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_session 3" +.TH SSL_set_session 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_session \- set a TLS/SSL session to be used during TLS/SSL connect +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_set_session(SSL *ssl, SSL_SESSION *session); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_session()\fR sets \fBsession\fR to be used when the TLS/SSL connection +is to be established. \fBSSL_set_session()\fR is only useful for TLS/SSL clients. +When the session is set, the reference count of \fBsession\fR is incremented +by 1. If the session is not reused, the reference count is decremented +again during \fBSSL_connect()\fR. Whether the session was reused can be queried +with the \fBSSL_session_reused\fR\|(3) call. +.PP +If there is already a session set inside \fBssl\fR (because it was set with +\&\fBSSL_set_session()\fR before or because the same \fBssl\fR was already used for +a connection), \fBSSL_SESSION_free()\fR will be called for that session. +This is also the case when \fBsession\fR is a NULL pointer. If that old +session is still \fBopen\fR, it is considered bad and will be removed from the +session cache (if used). A session is considered open, if \fBSSL_shutdown\fR\|(3) was +not called for the connection (or at least \fBSSL_set_shutdown\fR\|(3) was used to +set the SSL_SENT_SHUTDOWN state). +.SH NOTES +.IX Header "NOTES" +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object\*(Aqs session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.IP 0 4 +The operation failed; check the error stack to find out the reason. +.IP 1 4 +.IX Item "1" +The operation succeeded. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_SESSION_free\fR\|(3), +\&\fBSSL_get_session\fR\|(3), +\&\fBSSL_session_reused\fR\|(3), +\&\fBSSL_CTX_set_session_cache_mode\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_session_secret_cb.3 b/static/netbsd/man3/SSL_set_session_secret_cb.3 new file mode 100644 index 00000000..68a8beaa --- /dev/null +++ b/static/netbsd/man3/SSL_set_session_secret_cb.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: SSL_set_session_secret_cb.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_session_secret_cb 3" +.TH SSL_set_session_secret_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_session_secret_cb, tls_session_secret_cb_fn +\&\- set the session secret callback +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len, +\& STACK_OF(SSL_CIPHER) *peer_ciphers, +\& const SSL_CIPHER **cipher, void *arg); +\& +\& int SSL_set_session_secret_cb(SSL *s, +\& tls_session_secret_cb_fn session_secret_cb, +\& void *arg); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_session_secret_cb()\fR sets the session secret callback to be used +(\fIsession_secret_cb\fR), and an optional argument (\fIarg\fR) to be passed to that +callback when it is called. This is only useful for an implementation of +EAP\-FAST (RFC4851). The presence of the callback also modifies the internal +OpenSSL TLS state machine to match the modified TLS behaviour as described in +RFC4851. Therefore this callback should not be used except when implementing +EAP\-FAST. +.PP +The callback is expected to set the master secret to be used by filling in the +data pointed to by \fI*secret\fR. The size of the secret buffer is initially +available in \fI*secret_len\fR and may be updated by the callback (but must not be +larger than the initial value). +.PP +On the server side the set of ciphersuites offered by the peer is provided in +the \fIpeer_ciphers\fR stack. Optionally the callback may select the preferred +ciphersuite by setting it in \fI*cipher\fR. +.PP +On the client side the \fIpeer_ciphers\fR stack will always be NULL. The callback +may specify the preferred cipher in \fI*cipher\fR and this will be associated with +the \fBSSL_SESSION\fR \- but it does not affect the ciphersuite selected by the +server. +.PP +The callback is also supplied with an additional argument in \fIarg\fR which is the +argument that was provided to the original \fBSSL_set_session_secret_cb()\fR call. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_session_secret_cb()\fR returns 1 on success and 0 on failure. +.PP +If the callback returns 1 then this indicates it has successfully set the +secret. A return value of 0 indicates that the secret has not been set. On the +client this will cause an immediate abort of the handshake. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), +\&\fBSSL_get_session\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_shutdown.3 b/static/netbsd/man3/SSL_set_shutdown.3 new file mode 100644 index 00000000..3c3b31b7 --- /dev/null +++ b/static/netbsd/man3/SSL_set_shutdown.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: SSL_set_shutdown.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_shutdown 3" +.TH SSL_set_shutdown 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_shutdown, SSL_get_shutdown \- manipulate shutdown state of an SSL connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_set_shutdown(SSL *ssl, int mode); +\& +\& int SSL_get_shutdown(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_shutdown()\fR sets the shutdown state of \fBssl\fR to \fBmode\fR. +.PP +\&\fBSSL_get_shutdown()\fR returns the shutdown mode of \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +The shutdown state of an ssl connection is a bit\-mask of: +.IP 0 4 +No shutdown setting, yet. +.IP SSL_SENT_SHUTDOWN 4 +.IX Item "SSL_SENT_SHUTDOWN" +A close_notify shutdown alert was sent to the peer, the connection is being +considered closed and the session is closed and correct. +.IP SSL_RECEIVED_SHUTDOWN 4 +.IX Item "SSL_RECEIVED_SHUTDOWN" +A shutdown alert was received form the peer, either a normal close_notify +or a fatal error. +.PP +SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. +.PP +The shutdown state of the connection is used to determine the state of +the ssl session. If the session is still open, when +\&\fBSSL_clear\fR\|(3) or \fBSSL_free\fR\|(3) is called, +it is considered bad and removed according to RFC2246. +The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the close_notify +alert but to not wait for the peer\*(Aqs answer, when the underlying connection +is closed). +\&\fBSSL_set_shutdown()\fR can be used to set this state without sending a +close alert to the peer (see \fBSSL_shutdown\fR\|(3)). +.PP +If a close_notify was received, SSL_RECEIVED_SHUTDOWN will be set, +for setting SSL_SENT_SHUTDOWN the application must however still call +\&\fBSSL_shutdown\fR\|(3) or \fBSSL_set_shutdown()\fR itself. +.PP +\&\fBSSL_set_shutdown()\fR is not supported for QUIC SSL objects. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_shutdown()\fR does not return diagnostic information. +.PP +\&\fBSSL_get_shutdown()\fR returns the current shutdown state as set or based +on the actual connection state. +.PP +\&\fBSSL_get_shutdown()\fR returns 0 if called on a QUIC stream SSL object. If it +is called on a QUIC connection SSL object, it returns a value with +SSL_SENT_SHUTDOWN set if CONNECTION_CLOSE has been sent to the peer and +it returns a value with SSL_RECEIVED_SHUTDOWN set if CONNECTION_CLOSE +has been received from the peer or the QUIC connection is fully terminated +for other reasons. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_shutdown\fR\|(3), +\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), +\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_set_verify_result.3 b/static/netbsd/man3/SSL_set_verify_result.3 new file mode 100644 index 00000000..998a0944 --- /dev/null +++ b/static/netbsd/man3/SSL_set_verify_result.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: SSL_set_verify_result.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_set_verify_result 3" +.TH SSL_set_verify_result 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_set_verify_result \- override result of peer certificate verification +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void SSL_set_verify_result(SSL *ssl, long verify_result); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_set_verify_result()\fR sets \fBverify_result\fR of the object \fBssl\fR to be the +result of the verification of the X509 certificate presented by the peer, +if any. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_set_verify_result()\fR overrides the verification result. It only changes +the verification result of the \fBssl\fR object. It does not become part of the +established session, so if the session is to be reused later, the original +value will reappear. +.PP +The valid codes for \fBverify_result\fR are documented in \fBopenssl\-verify\fR\|(1). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_set_verify_result()\fR does not provide a return value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_get_peer_certificate\fR\|(3), +\&\fBopenssl\-verify\fR\|(1) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_shutdown.3 b/static/netbsd/man3/SSL_shutdown.3 new file mode 100644 index 00000000..16513ba1 --- /dev/null +++ b/static/netbsd/man3/SSL_shutdown.3 @@ -0,0 +1,455 @@ +.\" $NetBSD: SSL_shutdown.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_shutdown 3" +.TH SSL_shutdown 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_shutdown, SSL_shutdown_ex \- shut down a TLS/SSL or QUIC connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_shutdown(SSL *ssl); +\& +\& typedef struct ssl_shutdown_ex_args_st { +\& uint64_t quic_error_code; +\& const char *quic_reason; +\& } SSL_SHUTDOWN_EX_ARGS; +\& +\& _\|_owur int SSL_shutdown_ex(SSL *ssl, uint64_t flags, +\& const SSL_SHUTDOWN_EX_ARGS *args, +\& size_t args_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_shutdown()\fR shuts down an active connection represented by an SSL object. \fIssl\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_shutdown_ex()\fR is an extended version of \fBSSL_shutdown()\fR. If non\-NULL, \fIargs\fR +must point to a \fBSSL_SHUTDOWN_EX_ARGS\fR structure and \fIargs_len\fR must be set to +\&\f(CWsizeof(SSL_SHUTDOWN_EX_ARGS)\fR. The \fBSSL_SHUTDOWN_EX_ARGS\fR structure must be +zero\-initialized. If \fIargs\fR is NULL, the behaviour is the same as passing a +zero\-initialised \fBSSL_SHUTDOWN_EX_ARGS\fR structure. Currently, all extended +arguments relate to usage with QUIC, therefore this call functions identically +to \fBSSL_shutdown()\fR when not being used with QUIC. +.PP +While the general operation of \fBSSL_shutdown()\fR is common between protocols, the +exact nature of how a shutdown is performed depends on the underlying protocol +being used. See the section below pertaining to each protocol for more +information. +.PP +In general, calling \fBSSL_shutdown()\fR in nonblocking mode will initiate the +shutdown process and return 0 to indicate that the shutdown process has not yet +completed. Once the shutdown process has completed, subsequent calls to +\&\fBSSL_shutdown()\fR will return 1. See the RETURN VALUES section for more +information. +.PP +\&\fBSSL_shutdown()\fR should not be called if a previous fatal error has occurred on a +connection; i.e., if \fBSSL_get_error\fR\|(3) has returned \fBSSL_ERROR_SYSCALL\fR or +\&\fBSSL_ERROR_SSL\fR. +.SH "TLS AND DTLS\-SPECIFIC CONSIDERATIONS" +.IX Header "TLS AND DTLS-SPECIFIC CONSIDERATIONS" +Shutdown for SSL/TLS and DTLS is implemented in terms of the SSL/TLS/DTLS +close_notify alert message. The shutdown process for SSL/TLS and DTLS +consists of two steps: +.IP \(bu 4 +A close_notify shutdown alert message is sent to the peer. +.IP \(bu 4 +A close_notify shutdown alert message is received from the peer. +.PP +These steps can occur in either order depending on whether the connection +shutdown process was first initiated by the local application or by the peer. +.SS "Locally\-Initiated Shutdown" +.IX Subsection "Locally-Initiated Shutdown" +Calling \fBSSL_shutdown()\fR on an SSL/TLS or DTLS SSL object initiates the shutdown +process and causes OpenSSL to try to send a close_notify shutdown alert to the +peer. The shutdown process will then be considered completed once the peer +responds in turn with a close_notify shutdown alert message. +.PP +Calling \fBSSL_shutdown()\fR only closes the write direction of the connection; the +read direction is closed by the peer. Once \fBSSL_shutdown()\fR is called, +\&\fBSSL_write\fR\|(3) can no longer be used, but \fBSSL_read\fR\|(3) may still be used +until the peer decides to close the connection in turn. The peer might +continue sending data for some period of time before handling the local +application\*(Aqs shutdown indication. +.PP +\&\fBSSL_shutdown()\fR does not affect an underlying network connection such as a TCP +connection, which remains open. +.SS "Remotely\-Initiated Shutdown" +.IX Subsection "Remotely-Initiated Shutdown" +If the peer was the first to initiate the shutdown process by sending a +close_notify alert message, an application will be notified of this as an EOF +condition when calling +\&\fBSSL_read\fR\|(3) (i.e., \fBSSL_read\fR\|(3) will fail and \fBSSL_get_error\fR\|(3) will +return \fBSSL_ERROR_ZERO_RETURN\fR), after all application data sent by the peer +prior to initiating the shutdown has been read. An application should handle +this condition by calling \fBSSL_shutdown()\fR to respond with a close_notify alert in +turn, completing the shutdown process, though it may choose to write additional +application data using \fBSSL_write\fR\|(3) before doing so. If an application does +not call \fBSSL_shutdown()\fR in this case, a close_notify alert will not be sent and +the behaviour will not be fully standards compliant. +.SS "Shutdown Lifecycle" +.IX Subsection "Shutdown Lifecycle" +Regardless of whether a shutdown was initiated locally or by the peer, if the +underlying BIO is blocking, a call to \fBSSL_shutdown()\fR will return firstly once a +close_notify alert message is written to the peer (returning 0), and upon a +second and subsequent call, once a corresponding message is received from the +peer (returning 1 and completing the shutdown process). Calls to \fBSSL_shutdown()\fR +with a blocking underlying BIO will also return if an error occurs. +.PP +If the underlying BIO is nonblocking and the shutdown process is not yet +complete (for example, because a close_notify alert message has not yet been +received from the peer, or because a close_notify alert message needs to be sent +but would currently block), \fBSSL_shutdown()\fR returns 0 to indicate that the +shutdown process is still ongoing; in this case, a call to \fBSSL_get_error\fR\|(3) +will yield \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR. +.PP +An application can then detect completion of the shutdown process by calling +\&\fBSSL_shutdown()\fR again repeatedly until it returns 1, indicating that the shutdown +process is complete (with a close_notify alert having both been sent and +received). +.PP +However, the preferred method of waiting for the shutdown to complete is to use +\&\fBSSL_read\fR\|(3) until \fBSSL_get_error\fR\|(3) indicates EOF by returning +\&\fBSSL_ERROR_ZERO_RETURN\fR. This ensures any data received immediately before the +peer\*(Aqs close_notify alert is still provided to the application. It also ensures +any final handshake\-layer messages received are processed (for example, messages +issuing new session tickets). +.PP +If this approach is not used, the second call to \fBSSL_shutdown()\fR (to complete the +shutdown by confirming receipt of the peer\*(Aqs close_notify message) will fail if +it is called when the application has not read all pending application data +sent by the peer using \fBSSL_read\fR\|(3). +.PP +When calling \fBSSL_shutdown()\fR, the \fBSSL_SENT_SHUTDOWN\fR flag is set once an +attempt is made to send a close_notify alert, regardless of whether the attempt +was successful. The \fBSSL_RECEIVED_SHUTDOWN\fR flag is set once a close_notify +alert is received, which may occur during any call which processes incoming data +from the network, such as \fBSSL_read\fR\|(3) or \fBSSL_shutdown()\fR. These flags +may be checked using \fBSSL_get_shutdown\fR\|(3). +.SS "Fast Shutdown" +.IX Subsection "Fast Shutdown" +Alternatively, it is acceptable for an application to call \fBSSL_shutdown()\fR once +(such that it returns 0) and then close the underlying connection without +waiting for the peer\*(Aqs response. This allows for a more rapid shutdown process +if the application does not wish to wait for the peer. +.PP +This alternative "fast shutdown" approach should only be done if it is known +that the peer will not send more data, otherwise there is a risk of an +application exposing itself to a truncation attack. The full \fBSSL_shutdown()\fR +process, in which both parties send close_notify alerts and \fBSSL_shutdown()\fR +returns 1, provides a cryptographically authenticated indication of the end of a +connection. +.PP +This approach of a single \fBSSL_shutdown()\fR call without waiting is preferable to +simply calling \fBSSL_free\fR\|(3) or \fBSSL_clear\fR\|(3) as calling \fBSSL_shutdown()\fR +beforehand makes an SSL session eligible for subsequent reuse and notifies the +peer of connection shutdown. +.PP +The fast shutdown approach can only be used if there is no intention to reuse +the underlying connection (e.g. a TCP connection) for further communication; in +this case, the full shutdown process must be performed to ensure +synchronisation. +.SS "Effects on Session Reuse" +.IX Subsection "Effects on Session Reuse" +Calling \fBSSL_shutdown()\fR sets the SSL_SENT_SHUTDOWN flag (see +\&\fBSSL_set_shutdown\fR\|(3)), regardless of whether the transmission of the +close_notify alert was successful or not. This makes the SSL session eligible +for reuse; the SSL session is considered properly closed and can be reused for +future connections. +.SS "Quiet Shutdown" +.IX Subsection "Quiet Shutdown" +\&\fBSSL_shutdown()\fR can be modified to set the connection to the "shutdown" +state without actually sending a close_notify alert message; see +\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3). When "quiet shutdown" is enabled, +\&\fBSSL_shutdown()\fR will always succeed and return 1 immediately. +.PP +This is not standards\-compliant behaviour. It should only be done when the +application protocol in use enables the peer to ensure that all data has been +received, such that it doesn\*(Aqt need to wait for a close_notify alert, otherwise +application data may be truncated unexpectedly. +.SS "Non\-Compliant Peers" +.IX Subsection "Non-Compliant Peers" +There are SSL/TLS implementations that never send the required close_notify +alert message but simply close the underlying transport (e.g. a TCP connection) +instead. This will ordinarily result in an error being generated. +.PP +If compatibility with such peers is desired, the option +\&\fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR can be set. For more information, see +\&\fBSSL_CTX_set_options\fR\|(3). +.PP +Note that use of this option means that the EOF condition for application data +does not receive cryptographic protection, and therefore renders an application +potentially vulnerable to truncation attacks. Thus, this option must only be +used in conjunction with an application protocol which indicates unambiguously +when all data has been received. +.PP +An alternative approach is to simply avoid calling \fBSSL_read\fR\|(3) if it is known +that no more data is going to be sent. This requires an application protocol +which indicates unambiguously when all data has been sent. +.SS "Session Ticket Handling" +.IX Subsection "Session Ticket Handling" +If a client application only writes to an SSL/TLS or DTLS connection and never +reads, OpenSSL may never process new SSL/TLS session tickets sent by the server. +This is because OpenSSL ordinarily processes handshake messages received from a +peer during calls to \fBSSL_read\fR\|(3) by the application. +.PP +Therefore, client applications which only write and do not read but which wish +to benefit from session resumption are advised to perform a complete shutdown +procedure by calling \fBSSL_shutdown()\fR until it returns 1, as described above. This +will ensure there is an opportunity for SSL/TLS session ticket messages to be +received and processed by OpenSSL. +.SH "QUIC\-SPECIFIC SHUTDOWN CONSIDERATIONS" +.IX Header "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS" +When used with a QUIC connection SSL object, \fBSSL_shutdown()\fR initiates a QUIC +immediate close using QUIC \fBCONNECTION_CLOSE\fR frames. +.PP +\&\fBSSL_shutdown()\fR cannot be used on QUIC stream SSL objects. To conclude a stream +normally, see \fBSSL_stream_conclude\fR\|(3); to perform a non\-normal stream +termination, see \fBSSL_stream_reset\fR\|(3). +.PP +\&\fBSSL_shutdown_ex()\fR may be used instead of \fBSSL_shutdown()\fR by an application to +provide additional information to the peer on the reason why a connection is +being shut down. The information which can be provided is as follows: +.IP \fIquic_error_code\fR 4 +.IX Item "quic_error_code" +An optional 62\-bit application error code to be signalled to the peer. The value +must be in the range [0, 2**62\-1], else the call to \fBSSL_shutdown_ex()\fR fails. If +not provided, an error code of 0 is used by default. +.IP \fIquic_reason\fR 4 +.IX Item "quic_reason" +An optional zero\-terminated (UTF\-8) reason string to be signalled to the peer. +The application is responsible for providing a valid UTF\-8 string and OpenSSL +will not validate the string. If a reason is not provided, or \fBSSL_shutdown()\fR is +used, a zero\-length string is used as the reason. If provided, the reason string +is copied and stored inside the QUIC connection SSL object and need not remain +allocated after the call to \fBSSL_shutdown_ex()\fR returns. Reason strings are +bounded by the path MTU and may be silently truncated if they are too long to +fit in a QUIC packet. +.Sp +Reason strings are intended for human diagnostic purposes only, and should not +be used for application signalling. +.PP +The arguments to \fBSSL_shutdown_ex()\fR are used only on the first call to +\&\fBSSL_shutdown_ex()\fR (or \fBSSL_shutdown()\fR) for a given QUIC connection SSL object. +These arguments are ignored on subsequent calls. +.PP +These functions do not affect an underlying network BIO or the resource it +represents; for example, a UDP datagram provided to a QUIC connection as the +network BIO will remain open. +.PP +Note that when using QUIC, an application must call \fBSSL_shutdown()\fR if it wants +to ensure that all transmitted data was received by the peer. This is unlike a +TLS/TCP connection, where reliable transmission of buffered data is the +responsibility of the operating system. If an application calls \fBSSL_free()\fR on a +QUIC connection SSL object or exits before completing the shutdown process using +\&\fBSSL_shutdown()\fR, data which was written by the application using \fBSSL_write()\fR, but +could not yet be transmitted, or which was sent but lost in the network, may not +be received by the peer. +.PP +When using QUIC, calling \fBSSL_shutdown()\fR allows internal network event processing +to be performed. It is important that this processing is performed regularly, +whether during connection usage or during shutdown. If an application is not +using thread assisted mode, an application conducting shutdown should either +ensure that \fBSSL_shutdown()\fR is called regularly, or alternatively ensure that +\&\fBSSL_handle_events()\fR is called regularly. See \fBopenssl\-quic\fR\|(7) and +\&\fBSSL_handle_events\fR\|(3) for more information. +.SS "Application Data Drainage Behaviour" +.IX Subsection "Application Data Drainage Behaviour" +When using QUIC, \fBSSL_shutdown()\fR or \fBSSL_shutdown_ex()\fR ordinarily waits until all +data written to a stream by an application has been acknowledged by the peer. In +other words, the shutdown process waits until all data written by the +application has been sent to the peer, and until the receipt of all such data is +acknowledged by the peer. Only once this process is completed is the shutdown +considered complete. +.PP +An exception to this is streams which terminated in a non\-normal fashion, for +example due to a stream reset; only streams which are non\-terminated at the time +\&\fBSSL_shutdown()\fR is called, or which terminated in a normal fashion, have their +pending send buffers flushed in this manner. +.PP +This behaviour of flushing streams during the shutdown process can be skipped by +setting the \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\fR flag in a call to +\&\fBSSL_shutdown_ex()\fR; in this case, data remaining in stream send buffers may not +be transmitted to the peer. This flag may be used when a non\-normal application +condition has occurred and the delivery of data written to streams via +\&\fBSSL_write\fR\|(3) is no longer relevant. +.SS "Shutdown Mode" +.IX Subsection "Shutdown Mode" +Aspects of how QUIC handles connection closure must be taken into account by +applications. Ordinarily, QUIC expects a connection to continue to be serviced +for a substantial period of time after it is nominally closed. This is necessary +to ensure that any connection closure notification sent to the peer was +successfully received. However, a consequence of this is that a fully +RFC\-compliant QUIC connection closure process could take of the order of +seconds. This may be unsuitable for some applications, such as short\-lived +processes which need to exit immediately after completing an application\-layer +transaction. +.PP +As such, there are two shutdown modes available to users of QUIC connection SSL +objects: +.IP "RFC compliant shutdown mode" 4 +.IX Item "RFC compliant shutdown mode" +This is the default behaviour. The shutdown process may take a period of time up +to three times the current estimated RTT to the peer. It is possible for the +closure process to complete much faster in some circumstances but this cannot be +relied upon. +.Sp +In blocking mode, the function will return once the closure process is complete. +In nonblocking mode, \fBSSL_shutdown_ex()\fR should be called until it returns 1, +indicating the closure process is complete and the connection is now fully shut +down. +.IP "Rapid shutdown mode" 4 +.IX Item "Rapid shutdown mode" +In this mode, the peer is notified of connection closure on a best effort basis +by sending a single QUIC packet. If that QUIC packet is lost, the peer will not +know that the connection has terminated until the negotiated idle timeout (if +any) expires. +.Sp +This will generally return 0 on success, indicating that the connection has not +yet been fully shut down (unless it has already done so, in which case it will +return 1). +.PP +If \fBSSL_SHUTDOWN_FLAG_RAPID\fR is specified in \fIflags\fR, a rapid shutdown is +performed, otherwise an RFC\-compliant shutdown is performed. +.PP +If an application calls \fBSSL_shutdown_ex()\fR with \fBSSL_SHUTDOWN_FLAG_RAPID\fR, an +application can subsequently change its mind about performing a rapid shutdown +by making a subsequent call to \fBSSL_shutdown_ex()\fR without the flag set. +.SS "Peer\-Initiated Shutdown" +.IX Subsection "Peer-Initiated Shutdown" +In some cases, an application may wish to wait for a shutdown initiated by the +peer rather than triggered locally. To do this, call \fBSSL_shutdown_ex()\fR with +\&\fISSL_SHUTDOWN_FLAG_WAIT_PEER\fR specified in \fIflags\fR. In blocking mode, this +waits until the peer initiates a shutdown or the connection otherwise becomes +terminated for another reason. In nonblocking mode it exits immediately with +either success or failure depending on whether a shutdown has occurred. +.PP +If a locally initiated shutdown has already been triggered or the connection has +started terminating for another reason, this flag has no effect. +.PP +\&\fBSSL_SHUTDOWN_FLAG_WAIT_PEER\fR implies \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\fR, as +stream data cannot be flushed after a peer closes the connection. Stream data +may still be sent to the peer in any time spent waiting before the peer closes +the connection, though there is no guarantee of this. +.SS "Nonblocking Mode" +.IX Subsection "Nonblocking Mode" +\&\fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR block if the connection is configured in +blocking mode. This may be overridden by specifying +\&\fBSSL_SHUTDOWN_FLAG_NO_BLOCK\fR in \fIflags\fR when calling \fBSSL_shutdown_ex()\fR, which +causes the call to operate as though in nonblocking mode. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +For both \fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR the following return values can occur: +.IP 0 4 +The shutdown process is ongoing and has not yet completed. +.Sp +For TLS and DTLS, this means that a close_notify alert has been sent but the +peer has not yet replied in turn with its own close_notify. +.Sp +For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been +sent but the connection closure process has not yet completed. +.Sp +Unlike most other functions, returning 0 does not indicate an error. +\&\fBSSL_get_error\fR\|(3) should not be called; it may misleadingly indicate an error +even though no error occurred. +.IP 1 4 +.IX Item "1" +The shutdown was successfully completed. +.Sp +For TLS and DTLS, this means that a close_notify alert was sent and the peer\*(Aqs +close_notify alert was received. +.Sp +For QUIC connection SSL objects, this means that the connection closure process +has completed. +.IP <0 4 +.IX Item "<0" +The shutdown was not successful. +Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason. +It can occur if an action is needed to continue the operation for nonblocking +BIOs. +.Sp +It can also occur when not all data was read using \fBSSL_read()\fR, or if called +on a QUIC stream SSL object. +.Sp +This value is also returned when called on QUIC stream SSL objects. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3), +\&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3), +\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), \fBSSL_CTX_set_options\fR\|(3) +\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3), +\&\fBssl\fR\|(7), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_shutdown_ex()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_state_string.3 b/static/netbsd/man3/SSL_state_string.3 new file mode 100644 index 00000000..9cc8635b --- /dev/null +++ b/static/netbsd/man3/SSL_state_string.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: SSL_state_string.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_state_string 3" +.TH SSL_state_string 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_state_string, SSL_state_string_long \- get textual description of state of an SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSL_state_string(const SSL *ssl); +\& const char *SSL_state_string_long(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_state_string()\fR returns an abbreviated string indicating the current state +of the SSL object \fBssl\fR. The returned NUL\-terminated string contains 6 or fewer characters. +.PP +\&\fBSSL_state_string_long()\fR returns a descriptive string indicating the current state of +the SSL object \fBssl\fR. +.SH NOTES +.IX Header "NOTES" +During its use, an SSL objects passes several states. The state is internally +maintained. Querying the state information is not very informative before +or when a connection has been established. It however can be of significant +interest during the handshake. +.PP +When using nonblocking sockets, the function call performing the handshake +may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, +so that SSL_state_string[_long]() may be called. +.PP +For both blocking or nonblocking sockets, the details state information +can be used within the info_callback function set with the +\&\fBSSL_set_info_callback()\fR call. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Detailed description of possible states to be included later. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_CTX_set_info_callback\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_stream_conclude.3 b/static/netbsd/man3/SSL_stream_conclude.3 new file mode 100644 index 00000000..161aac8b --- /dev/null +++ b/static/netbsd/man3/SSL_stream_conclude.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: SSL_stream_conclude.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_stream_conclude 3" +.TH SSL_stream_conclude 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_stream_conclude \- conclude the sending part of a QUIC stream +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& _\|_owur int SSL_stream_conclude(SSL *s, uint64_t flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_stream_conclude()\fR signals the normal end\-of\-stream condition for the send +part of a QUIC stream. If called on a QUIC connection SSL object with an +associated default stream, it signals the end of the single stream to the peer. +.PP +Any data already queued for transmission via a call to \fBSSL_write()\fR will still be +written in a reliable manner before the end\-of\-stream is signalled, assuming the +connection remains healthy. This function can be thought of as appending a +logical end\-of\-stream marker after any data which has previously been written to +the stream via calls to \fBSSL_write()\fR. Further attempts to call \fBSSL_write()\fR after +calling this function will fail. +.PP +When calling this on a stream, the receive part of the stream remains +unaffected, and the peer may continue to send data until it also signals the end +of the stream. Thus, \fBSSL_read()\fR can still be used. +.PP +\&\fIflags\fR is reserved and should be set to 0. +.PP +Only the first call to this function has any effect for a given stream; +subsequent calls are no\-ops. This is considered a success case. +.PP +This function is not supported on an object other than a QUIC stream SSL object. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.PP +Returns 0 if called on an SSL object not representing a QUIC stream. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-quic\fR\|(7), \fBssl\fR\|(7), \fBSSL_shutdown_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_stream_conclude()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_stream_reset.3 b/static/netbsd/man3/SSL_stream_reset.3 new file mode 100644 index 00000000..ce2d6a28 --- /dev/null +++ b/static/netbsd/man3/SSL_stream_reset.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: SSL_stream_reset.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_stream_reset 3" +.TH SSL_stream_reset 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_stream_reset \- reset a QUIC stream +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ssl_stream_reset_args_st { +\& uint64_t quic_error_code; +\& } SSL_STREAM_RESET_ARGS; +\& +\& int SSL_stream_reset(SSL *ssl, +\& const SSL_STREAM_RESET_ARGS *args, +\& size_t args_len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_stream_reset()\fR function resets the send part of a QUIC stream when +called on a QUIC stream SSL object, or on a QUIC connection SSL object with a +default stream attached. +.PP +If \fIargs\fR is non\-NULL, \fIargs_len\fR must be set to \f(CWsizeof(*args)\fR. +.PP +\&\fIquic_error_code\fR is an application\-specified error code, which must be in the +range [0, 2**62\-1]. If \fIargs\fR is NULL, a value of 0 is used. +.PP +Resetting a stream indicates to an application that the sending part of the +stream is terminating abnormally. When a stream is reset, the implementation +does not guarantee that any data already passed to \fBSSL_write\fR\|(3) will be +received by the peer, and data already passed to \fBSSL_write\fR\|(3) but not yet +transmitted may or may not be discarded. As such, you should only reset +a stream when the information transmitted on the stream no longer matters, for +example due to an error condition. +.PP +This function cannot be called on a unidirectional stream initiated by the peer, +as only the sending side of a stream can initiate a stream reset. +.PP +It is also possible to trigger a stream reset by calling \fBSSL_free\fR\|(3); see the +documentation for \fBSSL_free\fR\|(3) for details. +.PP +The receiving part of the stream (for bidirectional streams) continues to +function normally. +.SH NOTES +.IX Header "NOTES" +This function corresponds to the QUIC \fBRESET_STREAM\fR frame. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success and 0 on failure. +.PP +This function fails if called on a QUIC connection SSL object without a default +stream attached, or on a non\-QUIC SSL object. +.PP +After the first call to this function succeeds for a given stream, +subsequent calls succeed but are ignored. The application error code +used is that passed to the first successful call to this function. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_free\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_stream_reset()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_want.3 b/static/netbsd/man3/SSL_want.3 new file mode 100644 index 00000000..d27a1e9e --- /dev/null +++ b/static/netbsd/man3/SSL_want.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: SSL_want.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_want 3" +.TH SSL_want 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, +SSL_want_x509_lookup, SSL_want_retry_verify, SSL_want_async, SSL_want_async_job, +SSL_want_client_hello_cb \- obtain state information TLS/SSL I/O operation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int SSL_want(const SSL *ssl); +\& int SSL_want_nothing(const SSL *ssl); +\& int SSL_want_read(const SSL *ssl); +\& int SSL_want_write(const SSL *ssl); +\& int SSL_want_x509_lookup(const SSL *ssl); +\& int SSL_want_retry_verify(const SSL *ssl); +\& int SSL_want_async(const SSL *ssl); +\& int SSL_want_async_job(const SSL *ssl); +\& int SSL_want_client_hello_cb(const SSL *ssl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_want()\fR returns state information for the SSL object \fBssl\fR. \fBssl\fR \fBMUST NOT\fR be NULL. +.PP +The other SSL_want_*() calls are shortcuts for the possible states returned +by \fBSSL_want()\fR. +.SH NOTES +.IX Header "NOTES" +\&\fBSSL_want()\fR examines the internal state information of the SSL object. Its +return values are similar to that of \fBSSL_get_error\fR\|(3). +Unlike \fBSSL_get_error\fR\|(3), which also evaluates the +error queue, the results are obtained by examining an internal state flag +only. The information must therefore only be used for normal operation under +nonblocking I/O. Error conditions are not handled and must be treated +using \fBSSL_get_error\fR\|(3). +.PP +The result returned by \fBSSL_want()\fR should always be consistent with +the result of \fBSSL_get_error\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can currently occur for \fBSSL_want()\fR: +.IP SSL_NOTHING 4 +.IX Item "SSL_NOTHING" +There is no data to be written or to be read. +.IP SSL_WRITING 4 +.IX Item "SSL_WRITING" +There are data in the SSL buffer that must be written to the underlying +\&\fBBIO\fR layer in order to complete the actual SSL_*() operation. +A call to \fBSSL_get_error\fR\|(3) should return \fBSSL_ERROR_WANT_WRITE\fR. +.IP SSL_READING 4 +.IX Item "SSL_READING" +More data must be read from the underlying \fBBIO\fR layer in order to +complete the actual SSL_*() operation. +A call to \fBSSL_get_error\fR\|(3) should return \fBSSL_ERROR_WANT_READ\fR. +.IP SSL_X509_LOOKUP 4 +.IX Item "SSL_X509_LOOKUP" +The operation did not complete because an application callback set by +\&\fBSSL_CTX_set_client_cert_cb()\fR has asked to be called again. +A call to \fBSSL_get_error\fR\|(3) should return \fBSSL_ERROR_WANT_X509_LOOKUP\fR. +.IP SSL_RETRY_VERIFY 4 +.IX Item "SSL_RETRY_VERIFY" +The operation did not complete because a certificate verification callback +has asked to be called again via \fBSSL_set_retry_verify\fR\|(3). +A call to \fBSSL_get_error\fR\|(3) should return \fBSSL_ERROR_WANT_RETRY_VERIFY\fR. +.IP SSL_ASYNC_PAUSED 4 +.IX Item "SSL_ASYNC_PAUSED" +An asynchronous operation partially completed and was then paused. See +\&\fBSSL_get_all_async_fds\fR\|(3). A call to \fBSSL_get_error\fR\|(3) should return +\&\fBSSL_ERROR_WANT_ASYNC\fR. +.IP SSL_ASYNC_NO_JOBS 4 +.IX Item "SSL_ASYNC_NO_JOBS" +The asynchronous job could not be started because there were no async jobs +available in the pool (see \fBASYNC_init_thread\fR\|(3)). A call to \fBSSL_get_error\fR\|(3) +should return \fBSSL_ERROR_WANT_ASYNC_JOB\fR. +.IP SSL_CLIENT_HELLO_CB 4 +.IX Item "SSL_CLIENT_HELLO_CB" +The operation did not complete because an application callback set by +\&\fBSSL_CTX_set_client_hello_cb()\fR has asked to be called again. +A call to \fBSSL_get_error\fR\|(3) should return \fBSSL_ERROR_WANT_CLIENT_HELLO_CB\fR. +.PP +\&\fBSSL_want_nothing()\fR, \fBSSL_want_read()\fR, \fBSSL_want_write()\fR, +\&\fBSSL_want_x509_lookup()\fR, \fBSSL_want_retry_verify()\fR, +\&\fBSSL_want_async()\fR, \fBSSL_want_async_job()\fR, and \fBSSL_want_client_hello_cb()\fR +return 1 when the corresponding condition is true or 0 otherwise. +.SH "QUIC\-SPECIFIC CONSIDERATIONS" +.IX Header "QUIC-SPECIFIC CONSIDERATIONS" +For QUIC, these functions relate only to the TLS handshake layer. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_want_client_hello_cb()\fR function and the SSL_CLIENT_HELLO_CB return value +were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSL_write.3 b/static/netbsd/man3/SSL_write.3 new file mode 100644 index 00000000..24321d16 --- /dev/null +++ b/static/netbsd/man3/SSL_write.3 @@ -0,0 +1,248 @@ +.\" $NetBSD: SSL_write.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "SSL_write 3" +.TH SSL_write 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_write_ex2, SSL_write_ex, SSL_write, SSL_sendfile, SSL_WRITE_FLAG_CONCLUDE \- +write bytes to a TLS/SSL connection +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& #define SSL_WRITE_FLAG_CONCLUDE +\& +\& ossl_ssize_t SSL_sendfile(SSL *s, int fd, off_t offset, size_t size, int flags); +\& int SSL_write_ex2(SSL *s, const void *buf, size_t num, +\& uint64_t flags, +\& size_t *written); +\& int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); +\& int SSL_write(SSL *ssl, const void *buf, int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_write_ex()\fR and \fBSSL_write()\fR write \fBnum\fR bytes from the buffer \fBbuf\fR into +the specified \fBssl\fR connection. On success \fBSSL_write_ex()\fR will store the number +of bytes written in \fB*written\fR. +.PP +\&\fBSSL_write_ex2()\fR functions similarly to \fBSSL_write_ex()\fR but can also accept +optional flags which modify its behaviour. Calling \fBSSL_write_ex2()\fR with a +\&\fIflags\fR argument of 0 is exactly equivalent to calling \fBSSL_write_ex()\fR. +.PP +\&\fBSSL_sendfile()\fR writes \fBsize\fR bytes from offset \fBoffset\fR in the file +descriptor \fBfd\fR to the specified SSL connection \fBs\fR. This function provides +efficient zero\-copy semantics. \fBSSL_sendfile()\fR is available only when +Kernel TLS is enabled, which can be checked by calling \fBBIO_get_ktls_send()\fR. +It is provided here to allow users to maintain the same interface. +The meaning of \fBflags\fR is platform dependent. +Currently, under Linux it is ignored. +.PP +The \fIflags\fR argument to \fBSSL_write_ex2()\fR can accept zero or more of the +following flags. Note that which flags are supported will depend on the kind of +SSL object and underlying protocol being used: +.IP \fBSSL_WRITE_FLAG_CONCLUDE\fR 4 +.IX Item "SSL_WRITE_FLAG_CONCLUDE" +This flag is only supported on QUIC stream SSL objects (or QUIC connection SSL +objects with a default stream attached). +.Sp +If this flag is set, and the call to \fBSSL_write_ex2()\fR succeeds, and all of the +data passed to the call is written (meaning that \f(CW\*(C`*written == num\*(C'\fR), the +relevant QUIC stream\*(Aqs send part is concluded automatically as though +\&\fBSSL_stream_conclude\fR\|(3) was called (causing transmission of a FIN for the +stream). +.Sp +While using this flag is semantically equivalent to calling +\&\fBSSL_stream_conclude\fR\|(3) after a successful call to this function, using this +flag enables greater efficiency than making these two API calls separately, as +it enables the written stream data and the FIN flag indicating the end of the +stream to be scheduled as part of the same QUIC STREAM frame and QUIC packet. +.Sp +Setting this flag does not cause a stream\*(Aqs send part to be concluded if not all +of the data passed to the call was consumed. +.PP +A call to \fBSSL_write_ex2()\fR fails if a flag is passed which is not supported or +understood by the given SSL object. An application should determine if a flag is +supported (for example, for \fBSSL_WRITE_FLAG_CONCLUDE\fR, that a QUIC stream SSL +object is being used) before attempting to use it. +.SH NOTES +.IX Header "NOTES" +In the paragraphs below a "write function" is defined as one of either +\&\fBSSL_write_ex()\fR, or \fBSSL_write()\fR. +.PP +If necessary, a write function will negotiate a TLS/SSL session, if not already +explicitly performed by \fBSSL_connect\fR\|(3) or \fBSSL_accept\fR\|(3). If the peer +requests a re\-negotiation, it will be performed transparently during +the write function operation. The behaviour of the write functions depends on the +underlying BIO. +.PP +For the transparent negotiation to succeed, the \fBssl\fR must have been +initialized to client or server mode. This is being done by calling +\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state()\fR +before the first call to a write function. +.PP +If the underlying BIO is \fBblocking\fR, the write functions will only return, once +the write operation has been finished or an error occurred. +.PP +If the underlying BIO is \fBnonblocking\fR the write functions will also return +when the underlying BIO could not satisfy the needs of the function to continue +the operation. In this case a call to \fBSSL_get_error\fR\|(3) with the +return value of the write function will yield \fBSSL_ERROR_WANT_READ\fR +or \fBSSL_ERROR_WANT_WRITE\fR. As at any time a re\-negotiation is possible, a +call to a write function can also cause read operations! The calling process +then must repeat the call after taking appropriate action to satisfy the needs +of the write function. The action depends on the underlying BIO. When using a +nonblocking socket, nothing is to be done, but \fBselect()\fR can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. +.PP +The write functions will only return with success when the complete contents of +\&\fBbuf\fR of length \fBnum\fR has been written. This default behaviour can be changed +with the SSL_MODE_ENABLE_PARTIAL_WRITE option of \fBSSL_CTX_set_mode\fR\|(3). When +this flag is set the write functions will also return with success when a +partial write has been successfully completed. In this case the write function +operation is considered completed. The bytes are sent and a new write call with +a new buffer (with the already sent bytes removed) must be started. A partial +write is performed with the size of a message block, which is 16kB. +.PP +When used with a QUIC SSL object, calling an I/O function such as \fBSSL_write()\fR +allows internal network event processing to be performed. It is important that +this processing is performed regularly. If an application is not using thread +assisted mode, an application should ensure that an I/O function such as +\&\fBSSL_write()\fR is called regularly, or alternatively ensure that \fBSSL_handle_events()\fR +is called regularly. See \fBopenssl\-quic\fR\|(7) and \fBSSL_handle_events\fR\|(3) for more +information. +.SH WARNINGS +.IX Header "WARNINGS" +When a write function call has to be repeated because \fBSSL_get_error\fR\|(3) +returned \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR, it must be repeated +with the same arguments. +The data that was passed might have been partially processed. +When \fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR was set using \fBSSL_CTX_set_mode\fR\|(3) +the pointer can be different, but the data and length should still be the same. +.PP +You should not call \fBSSL_write()\fR with num=0, it will return an error. +\&\fBSSL_write_ex()\fR can be called with num=0, but will not send application data to +the peer. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_write_ex()\fR and \fBSSL_write_ex2()\fR return 1 for success or 0 for failure. +Success means that all requested application data bytes have been written to the +SSL connection or, if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 +application data byte has been written to the SSL connection. Failure means that +not all the requested bytes have been written yet (if +SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or no bytes could be written to the +SSL connection (if SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be +retryable (e.g. the network write buffer has temporarily filled up) or +non\-retryable (e.g. a fatal network error). In the event of a failure call +\&\fBSSL_get_error\fR\|(3) to find out the reason which indicates whether the call is +retryable or not. +.PP +For \fBSSL_write()\fR the following return values can occur: +.IP "> 0" 4 +.IX Item "> 0" +The write operation was successful, the return value is the number of +bytes actually written to the TLS/SSL connection. +.IP "<= 0" 4 +.IX Item "<= 0" +The write operation was not successful, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call \fBSSL_get_error()\fR with the return value \fBret\fR to find out the reason. +.Sp +Old documentation indicated a difference between 0 and \-1, and that \-1 was +retryable. +You should instead call \fBSSL_get_error()\fR to find out if it\*(Aqs retryable. +.PP +For \fBSSL_sendfile()\fR, the following return values can occur: +.IP ">= 0" 4 +.IX Item ">= 0" +The write operation was successful, the return value is the number +of bytes of the file written to the TLS/SSL connection. The return +value can be less than \fBsize\fR for a partial write. +.IP "< 0" 4 +.IX Item "< 0" +The write operation was not successful, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call \fBSSL_get_error()\fR with the return value to find out the reason. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_error\fR\|(3), \fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3) +\&\fBSSL_CTX_set_mode\fR\|(3), \fBSSL_CTX_new\fR\|(3), +\&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3) +\&\fBSSL_set_connect_state\fR\|(3), \fBBIO_ctrl\fR\|(3), +\&\fBssl\fR\|(7), \fBbio\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_write_ex()\fR function was added in OpenSSL 1.1.1. +The \fBSSL_sendfile()\fR function was added in OpenSSL 3.0. +The \fBSSL_write_ex2()\fR function was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/SSLeay_version.3 b/static/netbsd/man3/SSLeay_version.3 new file mode 100644 index 00000000..f7589593 --- /dev/null +++ b/static/netbsd/man3/SSLeay_version.3 @@ -0,0 +1,192 @@ +.\" $NetBSD: SSLeay_version.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SSLeay_version 3" +.TH SSLeay_version 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSLeay_version \- retrieve version/build information about OpenSSL library +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *SSLeay_version(int type); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fISSLeay_version()\fR returns a pointer to a constant string describing the +version of the OpenSSL library or giving information about the library +build. +.PP +The following \fBtype\fR values are supported: +.IP "\s-1SSLEAY_VERSION\s0" 4 +.IX Item "SSLEAY_VERSION" +The version of the OpenSSL library including the release date. +.IP "\s-1SSLEAY_CFLAGS\s0" 4 +.IX Item "SSLEAY_CFLAGS" +The compiler flags set for the compilation process in the form +\&\*(L"compiler: ...\*(R" if available or \*(L"compiler: information not available\*(R" +otherwise. +.IP "\s-1SSLEAY_BUILT_ON\s0" 4 +.IX Item "SSLEAY_BUILT_ON" +The date of the build process in the form \*(L"built on: ...\*(R" if available +or \*(L"built on: date not available\*(R" otherwise. +.IP "\s-1SSLEAY_PLATFORM\s0" 4 +.IX Item "SSLEAY_PLATFORM" +The \*(L"Configure\*(R" target of the library build in the form \*(L"platform: ...\*(R" +if available or \*(L"platform: information not available\*(R" otherwise. +.IP "\s-1SSLEAY_DIR\s0" 4 +.IX Item "SSLEAY_DIR" +The \*(L"\s-1OPENSSLDIR\*(R"\s0 setting of the library build in the form \*(L"\s-1OPENSSLDIR: \*(R"..."\*(L"\s0 +if available or \*(R"\s-1OPENSSLDIR: N/A"\s0 otherwise. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The following return values can occur: +.ie n .IP """not available""" 4 +.el .IP "``not available''" 4 +.IX Item "not available" +An invalid value for \fBtype\fR was given. +.IP "Pointer to constant string" 4 +.IX Item "Pointer to constant string" +Textual description. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypto\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fB\s-1SSLEAY_DIR\s0\fR was added in OpenSSL 0.9.7. diff --git a/static/netbsd/man3/TS_RESP_CTX_new.3 b/static/netbsd/man3/TS_RESP_CTX_new.3 new file mode 100644 index 00000000..20bf25f7 --- /dev/null +++ b/static/netbsd/man3/TS_RESP_CTX_new.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: TS_RESP_CTX_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "TS_RESP_CTX_new 3" +.TH TS_RESP_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +TS_RESP_CTX_new_ex, TS_RESP_CTX_new, +TS_RESP_CTX_free \- Timestamp response context object creation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& TS_RESP_CTX *TS_RESP_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq); +\& TS_RESP_CTX *TS_RESP_CTX_new(void); +\& void TS_RESP_CTX_free(TS_RESP_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Creates a response context that can be used for generating responses. +.PP +\&\fBTS_RESP_CTX_new_ex()\fR allocates and initializes a TS_RESP_CTX structure with a +library context of \fIlibctx\fR and a property query of \fIpropq\fR. +The library context and property query can be used to select which providers +supply the fetched algorithms. +.PP +\&\fBTS_RESP_CTX_new()\fR is similar to \fBTS_RESP_CTX_new_ex()\fR but sets the library context +and property query to NULL. This results in the default (NULL) library context +being used for any operations requiring algorithm fetches. +.PP +\&\fBTS_RESP_CTX_free()\fR frees the \fBTS_RESP_CTX\fR object \fIctx\fR. +If the argument is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBTS_RESP_CTX_new_ex()\fR and \fBTS_RESP_CTX_new()\fR return NULL, +otherwise it returns a pointer to the newly allocated structure. +.SH HISTORY +.IX Header "HISTORY" +The function \fBTS_RESP_CTX_new_ex()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/TS_VERIFY_CTX.3 b/static/netbsd/man3/TS_VERIFY_CTX.3 new file mode 100644 index 00000000..cac6628b --- /dev/null +++ b/static/netbsd/man3/TS_VERIFY_CTX.3 @@ -0,0 +1,216 @@ +.\" $NetBSD: TS_VERIFY_CTX.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "TS_VERIFY_CTX 3" +.TH TS_VERIFY_CTX 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +TS_VERIFY_CTX, TS_VERIFY_CTX_new, TS_VERIFY_CTX_init, TS_VERIFY_CTX_free, +TS_VERIFY_CTX_cleanup, TS_VERIFY_CTX_set_flags, TS_VERIFY_CTX_add_flags, +TS_VERIFY_CTX_set0_data, TS_VERIFY_CTX_set0_imprint, TS_VERIFY_CTX_set0_store, +TS_VERIFY_CTX_set0_certs, TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs, +TS_VERIFY_CTX_set_data, TS_VERIFY_CTX_set_imprint, TS_VERIFY_CTX_set_store +\&\- manage the TS response verification context +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct TS_verify_ctx TS_VERIFY_CTX; +\& +\& TS_VERIFY_CTX *TS_VERIFY_CTX_new(void); +\& void TS_VERIFY_CTX_init(TS_VERIFY_CTX *ctx); +\& void TS_VERIFY_CTX_free(TS_VERIFY_CTX *ctx); +\& void TS_VERIFY_CTX_cleanup(TS_VERIFY_CTX *ctx); +\& int TS_VERIFY_CTX_set_flags(TS_VERIFY_CTX *ctx, int f); +\& int TS_VERIFY_CTX_add_flags(TS_VERIFY_CTX *ctx, int f); +\& int TS_VERIFY_CTX_set0_data(TS_VERIFY_CTX *ctx, BIO *b); +\& int TS_VERIFY_CTX_set0_imprint(TS_VERIFY_CTX *ctx, +\& unsigned char *hexstr, long len); +\& int TS_VERIFY_CTX_set0_store(TS_VERIFY_CTX *ctx, X509_STORE *s); +\& int TS_VERIFY_CTX_set0_certs(TS_VERIFY_CTX *ctx, STACK_OF(X509) *certs); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.4: +.PP +.Vb 6 +\& BIO *TS_VERIFY_CTX_set_data(TS_VERIFY_CTX *ctx, BIO *b); +\& unsigned char *TS_VERIFY_CTX_set_imprint(TS_VERIFY_CTX *ctx, +\& unsigned char *hexstr, long len); +\& X509_STORE *TS_VERIFY_CTX_set_store(TS_VERIFY_CTX *ctx, X509_STORE *s); +\& STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx, +\& STACK_OF(X509) *certs); +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0: +.PP +.Vb 2 +\& STACK_OF(X509) *TS_VERIFY_CTS_set_certs(TS_VERIFY_CTX *ctx, +\& STACK_OF(X509) *certs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Time\-Stamp Protocol (TSP) is defined by RFC 3161. TSP is a protocol used to +provide long\-term proof of the existence of certain data before a particular +time. TSP defines a Time Stamping Authority (TSA) and an entity that makes +requests to the TSA. Usually, the TSA is referred to as the server side, and the +requesting entity is referred to as the client. +.PP +In TSP, when a server sends a response to a client, the server normally +needs to sign the response data \- the TimeStampToken (TST) \- with its private +key. Then the client verifies the received TST using the server\*(Aqs certificate +chain. +.PP +For all the following methods, unless noted otherwise, \fIctx\fR is the +verification context created in advance. +.PP +\&\fBTS_VERIFY_CTX_new()\fR returns an allocated \fBTS_VERIFY_CTX\fR structure. +.PP +\&\fBTS_VERIFY_CTX_init()\fR initializes a verification context. +.PP +\&\fBTS_VERIFY_CTX_free()\fR frees up a \fBTS_VERIFY_CTX\fR object. \fIctx\fR is the +verification context to be freed. If \fIctx\fR is NULL, the call is ignored. +.PP +\&\fBTS_VERIFY_CTX_set_flags()\fR sets the flags in the verification context. \fIf\fR are +the flags to be set. +.PP +\&\fBTS_VERIFY_CTX_add_flags()\fR adds flags to the verification context. \fIf\fR are the +flags to be added (OR\*(Aqd). +.PP +\&\fBTS_VERIFY_CTX_set0_data()\fR sets the data to be verified. \fIb\fR is the \fBBIO\fR with +the data. A previously assigned \fBBIO\fR is freed. +.PP +\&\fBTS_VERIFY_CTX_set0_imprint()\fR sets the message imprint. \fIhexstr\fR is the +message imprint to be assigned. A previously assigned imprint is freed. +.PP +\&\fBTS_VERIFY_CTX_set0_store()\fR sets the store for the verification context. \fIs\fR is +the store to be assigned. A previously assigned store is freed. +.PP +\&\fBTS_VERIFY_CTX_set0_certs()\fR is used to set the server\*(Aqs certificate chain when +verifying a TST. \fIcerts\fR is a stack of \fBX509\fR certificates. +.PP +\&\fBTS_VERIFY_CTX_cleanup()\fR frees all data associated with the given +\&\fBTS_VERIFY_CTX\fR object and initializes it. \fIctx\fR is the verification context +created in advance. If \fIctx\fR is NULL, the call is ignored. +.PP +All of the following functions described are deprecated. Applications should +instead use the functions \fBTS_VERIFY_CTX_set0_data\fR\|(3), +\&\fBTS_VERIFY_CTX_set0_imprint\fR\|(3), \fBTS_VERIFY_CTX_set0_store\fR\|(3), +\&\fBTS_VERIFY_CTX_set0_certs\fR\|(3). +.PP +\&\fBTS_VERIFY_CTX_set_data()\fR is used to set the BIO with the data to be verified. +A previously assigned BIO is \fBnot freed\fR by this call. \fIb\fR is the \fBBIO\fR +with the data to assign. +.PP +\&\fBTS_VERIFY_CTX_set_imprint()\fR is used to set the message imprint. A previously +assigned imprint \fBis freed\fR by this call. \fIhexstr\fR is the string with the +message imprint to assign. +.PP +\&\fBTS_VERIFY_CTX_set_store()\fR is used to set the certificate store. A previously +assigned store is \fBnot freed\fR by this call. \fIs\fR is the store to assign. +.PP +\&\fBTS_VERIFY_CTX_set_certs()\fR is used to set the server\*(Aqs certificate chain. +A previously assigned stack is \fBnot freed\fR by this call. \fIcerts\fR is a stack +of \fBX509\fR certificates. +.PP +\&\fBTS_VERIFY_CTS_set_certs()\fR is a misspelled version of \fBTS_VERIFY_CTX_set_certs()\fR +which takes the same parameters and returns the same result. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBTS_VERIFY_CTX_new()\fR returns an allocated \fBTS_VERIFY_CTX\fR structure. +.PP +\&\fBTS_VERIFY_CTX_set_flags()\fR returns the flags passed via parameter \fIf\fR. +.PP +\&\fBTS_VERIFY_CTX_add_flags()\fR returns the flags of the context after the ones +passed via parameter \fIf\fR are added to it. +.PP +\&\fBTS_VERIFY_CTX_set0_data()\fR, \fBTS_VERIFY_CTX_set0_imprint()\fR, +\&\fBTS_VERIFY_CTX_set0_store()\fR, and \fBTS_VERIFY_CTX_set0_certs()\fR return 1 if the +value could be successfully set and 0 in case of any error. +.PP +The deprecated functions \fBTS_VERIFY_CTX_set_data()\fR, \fBTS_VERIFY_CTX_set_imprint()\fR, +\&\fBTS_VERIFY_CTX_set_store()\fR, \fBTS_VERIFY_CTX_set_certs()\fR return the parameter +the user passes via parameter \fIbio\fR, \fIhexstr\fR, \fIs\fR or \fIcerts\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_ESS_check_signing_certs\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBTS_VERIFY_CTX_set0_data()\fR, \fBTS_VERIFY_CTX_set0_imprint()\fR, +\&\fBTS_VERIFY_CTX_set0_store()\fR, \fBTS_VERIFY_CTX_set0_certs()\fR replace the functions +\&\fBTS_VERIFY_CTX_set_data()\fR, \fBTS_VERIFY_CTX_set_imprint()\fR, +\&\fBTS_VERIFY_CTX_set_store()\fR, \fBTS_VERIFY_CTX_set_certs()\fR that were deprecated +in OpenSSL 3.4.0. +.PP +The spelling of \fBTS_VERIFY_CTX_set_certs()\fR was corrected in OpenSSL 3.0.0. +The misspelled version \fBTS_VERIFY_CTS_set_certs()\fR has been retained for +compatibility reasons, but it is deprecated in OpenSSL 3.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/TS_VERIFY_CTX_set_certs.3 b/static/netbsd/man3/TS_VERIFY_CTX_set_certs.3 new file mode 100644 index 00000000..fcf04170 --- /dev/null +++ b/static/netbsd/man3/TS_VERIFY_CTX_set_certs.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: TS_VERIFY_CTX_set_certs.3,v 1.6 2025/04/16 15:23:16 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "TS_VERIFY_CTX_set_certs 3" +.TH TS_VERIFY_CTX_set_certs 3 2025-02-11 3.0.16 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +TS_VERIFY_CTX_set_certs, TS_VERIFY_CTS_set_certs +\&\- set certificates for TS response verification +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509) *TS_VERIFY_CTX_set_certs(TS_VERIFY_CTX *ctx, +\& STACK_OF(X509) *certs); +\& STACK_OF(X509) *TS_VERIFY_CTS_set_certs(TS_VERIFY_CTX *ctx, +\& STACK_OF(X509) *certs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Time-Stamp Protocol (TSP) is defined by RFC 3161. TSP is a protocol used to +provide long term proof of the existence of a certain datum before a particular +time. TSP defines a Time Stamping Authority (TSA) and an entity who shall make +requests to the TSA. Usually the TSA is denoted as the server side and the +requesting entity is denoted as the client. +.PP +In TSP, when a server is sending a response to a client, the server normally +needs to sign the response data \- the TimeStampToken (TST) \- with its private +key. Then the client shall verify the received TST by the server's certificate +chain. +.PP +\&\fBTS_VERIFY_CTX_set_certs()\fR is used to set the server's certificate chain when +verifying a TST. \fBctx\fR is the verification context created in advance and +\&\fBcerts\fR is a stack of \fBX509\fR certificates. +.PP +\&\fBTS_VERIFY_CTS_set_certs()\fR is a misspelled version of \fBTS_VERIFY_CTX_set_certs()\fR +which takes the same parameters and returns the same result. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBTS_VERIFY_CTX_set_certs()\fR returns the stack of \fBX509\fR certificates the user +passes in via parameter \fBcerts\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_ESS_check_signing_certs\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The spelling of \fBTS_VERIFY_CTX_set_certs()\fR was corrected in OpenSSL 3.0.0. +The misspelled version \fBTS_VERIFY_CTS_set_certs()\fR has been retained for +compatibility reasons, but it is deprecated in OpenSSL 3.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/Tspi_ChangeAuth.3 b/static/netbsd/man3/Tspi_ChangeAuth.3 new file mode 100644 index 00000000..6a9b9f68 --- /dev/null +++ b/static/netbsd/man3/Tspi_ChangeAuth.3 @@ -0,0 +1,75 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Change_Auth" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_ChangeAuth \- change the authorization data of an entity. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_ChangeAuth(TSS_HOBJECT " hObjectToChange ", TSS_HOBJECT " hParentObject "," +.BI " TSS_HPOLICY " hNewPolicy " );" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_ChangeAuth \fR changes the authorization data (secret) of an entity (object) and assigns the object to the policy object. All classes using secrets provide this method for changing their authorization data. +.SH "PARAMETERS" +.PP +.SS hObjectToChange +Handle of the object to change authorization for. +.PP +.SS hParentObject +Handle of the parent object wrapping the object addressed by hObjectToChange. +.PP +.SS hNewPolicy +Handle of the policy object providing the new authorization data. +.SH "RETURN CODES" +.PP +\fBTspi_ChangeAuth\fR returns TSS_SUCCESS on success,otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhObjectToChange\fR, or \fIhParentObject\fR are not a valid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_ChangeAuth\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_ChangeAuthAsym\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_ChangeAuthAsym.3 b/static/netbsd/man3/Tspi_ChangeAuthAsym.3 new file mode 100644 index 00000000..46726013 --- /dev/null +++ b/static/netbsd/man3/Tspi_ChangeAuthAsym.3 @@ -0,0 +1,76 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_ChangeAuthAsym" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_ChangeAuthAsym \- change the authorization data of an entity using asymmetric change protocol. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_ChangeAuthAsym(TSS_HOBJECT " hObjectToChange ", TSS_HOBJECT " hParentObject "," +.BI " TSS_HKEY " hIdentKey ", TSS_HPOLICY " hNewPolicy ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_ChangeAuthAsym\fR changes the authorization data (secret) of an entity (object) utilizing the asymmetric change protocol and assigns the object to the policy object. All classes using secrets provide this method for changing their authorization data. +This method changes the authorization data of an object ensuring that the parent of the object does not get knowledge of the new secret. +.SH "PARAMETERS" +.PP +.SS hObjectToChange +Handle of the object the authorization data should be changed. +.PP +.SS hParentObject +Handle of the parent object wrapping the object addressed by \fIhObjectToChange\fR. +.PP +.SS hIdentKey +Handle of the identity key object required to proof the internally created temporary key. +.PP +.SS hNewPolicy +Handle of the policy object providing the new authorization data. +.SH "RETURN CODES" +.PP +\fBTspi_ChangeAuthAsym\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhObjectToChange\fR, \fIhParentObject\fR, or \fIhIdentKey\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_ChangeAuthAsym\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_ChangeAuth\fR(3). diff --git a/static/netbsd/man3/Tspi_Context_Close.3 b/static/netbsd/man3/Tspi_Context_Close.3 new file mode 100644 index 00000000..c8c7da40 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_Close.3 @@ -0,0 +1,68 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_Close" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_Close \- destroy a TSP context handle. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_Close(TSS_HCONTEXT " hLocalContext ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_Context_Close\fR destroys a context by passing in the handle to that context. +.SH "PARAMETERS" +.PP +.SS hLocalContext +The handle to the context to be closed. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_Close\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhLocalContext\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_Close\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Create\fR(3), \fBTspi_Context_Connect\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_Context_CloseObject.3 b/static/netbsd/man3/Tspi_Context_CloseObject.3 new file mode 100644 index 00000000..eabf74ef --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_CloseObject.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_CloseObject" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_CloseObject \- destroy resources associated with an object handle. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI " TSS_RESULT Tspi_Context_CloseObject(TSS_HCONTEXT " hContext ", TSS_HOBJECT " hObject ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTSS_Context_CloseObject\fR destroys the object associated with the object handle. All allocated resources associated within the object are also released. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS hObject +The handle of the object to be destroyed. +.SH "RETURN CODES" +.PP +\fBTspi_Context_CloseObject\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhContext\fR or \fIhObject\fR are invalid handles. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_CloseObject\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_CreateObject\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_Context_Connect.3 b/static/netbsd/man3/Tspi_Context_Connect.3 new file mode 100644 index 00000000..f92bc2f9 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_Connect.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_Connect" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME. +Tspi_Context_Connect\- connect a TSP to a Core Services daemon +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_Connect(TSS_HCONTEXT " hLocalContext ", UNICODE* " wszDestination ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_Context_Connect\fR creates a connetion between the application and the local or remote TSS System. +.SH "PARAMETERS" +.PP +.SS hLocalContext +The handle to the context to be connected. +.PP +.SS wszDestination +A null terminated unicode string which specifies the local or remote system to which one will be connected. If \fIwszDestination\fR is NULL, the connection will be to a local TCS. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_Connect\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhLocalContext\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_Connect\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Create\fR(3), \fBTspi_Context_Close\fR(3). + + diff --git a/static/netbsd/man3/Tspi_Context_Create.3 b/static/netbsd/man3/Tspi_Context_Create.3 new file mode 100644 index 00000000..1a7cd480 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_Create.3 @@ -0,0 +1,66 @@ +.\" Copyright (C) 2005 International Business Machines Corporation +.\" Written by Kent Yoder based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_Create" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_Create \- create a TSP context handle. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_Create(TSS_HCONTEXT* " phContext ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_Context_Create\fR creates a handle to a new context object. The context is then used by other API functions to track resources related to it. +.SH "PARAMETERS" +.PP +.SS phContext +Receives the handle to the created context object. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_Create\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INTERNAL_ERROR - An internal error occurred in the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_Create\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Close\fR(3), \fBTspi_Context_Connect\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_Context_CreateObject.3 b/static/netbsd/man3/Tspi_Context_CreateObject.3 new file mode 100644 index 00000000..1438629a --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_CreateObject.3 @@ -0,0 +1,125 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_CreateObject" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_CreateObject \- create an empty object and return a handle to that object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_CreateObject(TSS_HCONTEXT " hContext ", TSS_FLAG " objectType "," +.BI " TSS_FLAG " initFlags ", TSS_HOBJECT* " phObject ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTSS_Context_CreateObject\fR creates and initializes an empty object of the specified type and returns a handle addressing that object. The object is bound to an already opened context \fIhContext\fR. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS objectType +Flag indicating the object type to create. Possible types are: +.TP +.SM TSS_OBJECT_TYPE_POLICY - a policy object. +.TP +.SM TSS_OBJECT_TYPE_ENCDATA - an encrypted data object (either sealed or bound data). +.TP +.SM TSS_OBJECT_TYPE_RSAKEY - an RSA key. +.TP +.SM TSS_OBJECT_TYPE_PCRS - a PCR composite object. +.TP +.SM TSS_OBJECT_TYPE_HASH - a hash object. +.PP +.SS initFlags +Flag indicating the default attributes of the object. Attributes for each type of object are: +.TP +.SM Policy: + \fBTSS_POLICY_USAGE\fR - a usage policy (for authorization to use an object). + \fBTSS_POLICY_MIGRATION\fR - a migration policy. +.TP +.SM Encrypted data objects: + \fBTSS_ENCDATA_SEAL\fR - A data object used for a Seal operation. + \fBTSS_ENCDATA_BIND\fR - A data object used for a Bind operation. + \fBTSS_ENCDATA_LEGACY\fR - A data object for a bind operation using a legacy key. +.TP +.SM RSA Keys: + \fBTSS_KEY_SIZE_DEFAULT\fR - Use the default key size of the TCS you're connected to. + \fBTSS_KEY_SIZE_512\fR - Create a 512 bit key. + \fBTSS_KEY_SIZE_1024\fR - Create a 1024 bit key. + \fBTSS_KEY_SIZE_2048\fR - Create a 2048 bit key. + \fBTSS_KEY_SIZE_4096\fR - Create a 4096 bit key. + \fBTSS_KEY_SIZE_8192\fR - Create a 8192 bit key. + \fBTSS_KEY_SIZE_16384\fR - Create a 16384 bit key. + \fBTSS_KEY_TYPE_STORAGE\fR - Create a storage key. (Used to wrap other keys). + \fBTSS_KEY_TYPE_SIGNING\fR - Create a signing key. + \fBTSS_KEY_TYPE_BIND\fR - Create a binding key. (Used to encrypt data). + \fBTSS_KEY_TYPE_IDENTITY\fR - Create an identity key. (Used for an identity). + \fBTSS_KEY_TYPE_LEGACY\fR - Create a legacy key. (Can be used for signing and binding, created from data external to a TSS). + \fBTSS_KEY_TYPE_AUTHCHANGE\fR - Create an ephemeral key used to change authorization values. + \fBTSS_KEY_VOLATILE\fR - Create a volatile key. (Must be unloaded at startup). + \fBTSS_KEY_NON_VOLATILE\fR - Create a non-volatile key. (May be unloaded at startup). + \fBTSS_KEY_MIGRATABLE\fR - Create a migratable key. + \fBTSS_KEY_NOT_MIGRATABLE\fR - Create a non-migratable key. [DEFAULT] + \fBTSS_KEY_AUTHORIZATION\fR - Key will require authorization. + \fBTSS_KEY_NO_AUTHORIZATION\fR - Key will not require authorization. [DEFAULT] + \fBTSS_KEY_EMPTY_KEY\fR - Key template which will be returned as an object with very few attributes. + +.TP +.SM PCR composite objects: + None. +.TP +.SM Hash objects: + \fBTSS_HASH_SHA1\fR - a hash object of type SHA-1. + \fBTSS_HASH_OTHER\fR - a hash object of type other than SHA-1. +.PP +.PP +.SS phObject +The handle of the object to be created. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_CreateObject\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhContext\fR or \fIphObject\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_CreateObject\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_CloseObject\fR(3). diff --git a/static/netbsd/man3/Tspi_Context_FreeMemory.3 b/static/netbsd/man3/Tspi_Context_FreeMemory.3 new file mode 100644 index 00000000..417ae385 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_FreeMemory.3 @@ -0,0 +1,81 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_FreeMemory" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Context_FreeMemory \- Free allocated memory for a given context. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.br +.HP +.BI "TSS_RESULT Tspi_Context_FreeMemory(TSS_HCONTEXT " hContext ", BYTE* " rgbMemory ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_FreeMemory\fR frees memory allocated by the TSS Service Provider on a per-context basis. +This should be used before Tspi_Context_Close is called, to avoid memory leaks. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle to the local context. +.SS rgbMemory +The \fIrgbMemory\fR parameter is a pointer to the memory block to +be freed. If this is NULL, all memory blocks bound to the context are freed. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_FreeMemory\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_FreeMemory\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Create\fR(3), \fBTspi_Context_Close\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_GetCapability.3 b/static/netbsd/man3/Tspi_Context_GetCapability.3 new file mode 100644 index 00000000..9a48b495 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetCapability.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetCapability" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_GetCapability \- provide the capabilites of a TSS Core Service, TSS Service Provider, or TPM. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_GetCapability(TSS_HCONTEXT " hContext ", TSS_FLAG " capArea "," +.BI " UINT32 " ulSubCapLength ", BYTE* " rgbSubCap "," +.BI " UINT32* " pulRespDataLength ", BYTE** " prgbRespData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_GetCapability\fR provides the capabilities of the TSS Core Service or TSS Service Provider +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS capArea +Flag indicating the attribute to query. +.PP +.SS ulSubCapLength +The length (in bytes) of the rgbSubCap parameter. +.PP +.SS rgbSubCap +Data indicating the attribute to query. +.PP +.SS pulRespDataLength +Recieves the length (in bytes) of the prgbRespData parameter. +.PP +.SS prgbRespData +On successful completion of the command, this parameter points to a buffer containing the actual data of the specified capability. +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetCapability\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhContext\fR is an invalid handle. +.TP +.SM TSS_E_BAD_PARAMETER - One of the parameters did not match. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetCapability\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fB(none)\fR. diff --git a/static/netbsd/man3/Tspi_Context_GetDefaultPolicy.3 b/static/netbsd/man3/Tspi_Context_GetDefaultPolicy.3 new file mode 100644 index 00000000..fba2f7c1 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetDefaultPolicy.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetDefaultPolicy" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Context_GetDefaultPolicy \- Get a handle to the default policy object +of a given context. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.HP +.BI "TSS_RESULT Tspi_Context_GetDefaultPolicy(TSS_HCONTEXT " hContext ", TSS_HPOLICY " *phPolicy "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_GetDefaultPolicy\fR +determines what policy is used by all of the keys in a given context. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle of the context object. +.SS phPolicy +The \fIphPolicy\fR parameter receives the handle of the default +policy object bound to the context. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetDefaultPolicy\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetDefaultPolicy\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Create\fR(3), \fBTspi_Context_Connect\fR(3), +\fBTspi_Context_FreeMemory\fR(3), \fBTspi_Context_Close\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_GetKeyByPublicInfo.3 b/static/netbsd/man3/Tspi_Context_GetKeyByPublicInfo.3 new file mode 100644 index 00000000..3f0a8811 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetKeyByPublicInfo.3 @@ -0,0 +1,81 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetKeyByPublicInfo" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_GetKeyByPublicInfo \- search the persistent storage for a registered key using the provided public key information +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_GetKeyByPublicInfo(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType "," +.BI " TSS_ALGORITHM_ID " algID ", UINT32 " ulPublicInfoLength "," +.BI " BYTE* " rgbPublicInfo ", TSS_HKEY* " phKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_GetKeyByPublicInfo\fR searches the persistent storage for a registered key using the provided public key information and creates a key object initalized according to the found data. On successful completion of the method a handle to the created new key object is returned. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS persistentStorageType +Flag indicating the persistent storage the key is registered in. +.PP +.SS algId +This parameter indicates the algorithm of the requested key. +.PP +.SS ulPublicInfoLength +The length of the public key info provided at the parameter rgbPublicInfo. +.PP +.SS rgbPublicInfo +The public key info is provided to identify the key to be look for at the persistent storage. In case algID equals to TSS_ALG_RSA this prameter contains the modulus of the public RSA key. +.PP +.SS hKey +Recieves the handle of the key object representing the key. In case the key hasn't been found, this value will be NULL. +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetKeyByPublicInfo\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhContext\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetKeyByPublicInfo\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR(3). diff --git a/static/netbsd/man3/Tspi_Context_GetKeyByUUID.3 b/static/netbsd/man3/Tspi_Context_GetKeyByUUID.3 new file mode 100644 index 00000000..c68c22e1 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetKeyByUUID.3 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetKeyByUUID" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Context_GetKeyByUUID \- get a handle to a key registered in persistent storage. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_GetKeyByUUID(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType "," +.BI " TSS_UUID " uuidData ", TSS_HKEY* " phKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_GetKeyByUUID\fR searches the Persistent Storage database for a registered key using the +given UUID. It then creates a key object initialized to the found data and +returns a handle to the key object. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle of the context object. +.SS persistentStorageType +The \fIpersistentStorageType\fR parameter indicates the persistent +storage the key is registered in. +.SS uuidData +The \fIuuidData\fR parameter is the UUID by which the key is registered in +persistent storage. +.SS phKey +The \fIphKey\fR parameter receives the handle of the key object representing +the key. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetKeyByUUID\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is an invalid handle. + +.TP +.SM TSS_E_PS_KEY_NOTFOUND +The key cannot be found in the persistent storage database. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetKeyByUUID\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_GetTpmObject\fR(3), \fBTspi_Context_LoadKeyByUUID\fR(3), +\fBTspi_Context_GetRegisteredKeysByUUID\fR(3), +\fBTspi_Context_GetKeyByPublicInfo\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID.3 b/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID.3 new file mode 100644 index 00000000..c3714810 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID.3 @@ -0,0 +1,81 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetRegisteredKeysByUUID" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_GetRegisteredKeysByUUID \- get an array of TSS_KM_KEYINFO structures based on the state of persistent storage. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_GetRegisteredKeysByUUID(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType "," +.BI " TSS_UUID* " pUuidData ", UINT32* " pulKeyHierarchySize "," +.BI " TSS_KM_KEYINFO** " ppKeyHierarchy ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_GetRegisteredKeysByUUID\fR gets an array of TSS_KM_KEYINFO structures. This information reflects the state of the registered key hierarchy. The keys stored in the persistent storage are totallly independent from either the context provided in the function call or the context, which was provided while processing the key registration. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS persistentStorageType +Flag indicating the persistent storage the key is registered in. +.PP +.SS pUuidData +The UUID the key was registered in the persistent storage (TSP or connected TCS). If no key UUID is provided, thus KeyUUID is NULL, the returned array of the TSS_KM_KEYINFO structure contins data reflecting the whole key hierarchy starting with root key. If a certain key is UUID is provided, the returned array of TSS_KM_KEYINFO structures only contains data reflecting the path of the key hierarchy regarding that key. The first array entry is the key addressed by the given UUID followed by its parent key up to the root key. +.PP +.SS pulKeyHierarchySize +Recieves the length (number of array entries) of the ppKeyHierarchy parameter. +.PP +.SS ppKeyHierarchy +On successful completion of the command, this parameter points to a buffer containing the actual key hierarchy data. +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetRegisteredKeysByUUID\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhContext\fR is an invalid handle. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetRegisteredKeysByUUID\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR(3). diff --git a/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID2.3 b/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID2.3 new file mode 100644 index 00000000..86e3d09f --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetRegisteredKeysByUUID2.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 2004,2007 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" Revised by Ramon Brandão based on Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetRegisteredKeysByUUID2" 3 "2007-07-06" "TSS 1.2" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_GetRegisteredKeysByUUID2 \- get an array of TSS_KM_KEYINFO2 structures based on the state of persistent storage. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_GetRegisteredKeysByUUID2(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType "," +.BI " TSS_UUID* " pUuidData ", UINT32* " pulKeyHierarchySize "," +.BI " TSS_KM_KEYINFO2** " ppKeyHierarchy ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_GetRegisteredKeysByUUID2\fR gets an array of TSS_KM_KEYINFO2 structures. This information reflects the state of the registered key hierarchy. The keys stored in the persistent storage are totallly independent from either the context provided in the function call or the context, which was provided while processing the key registration. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS persistentStorageType +Flag indicating the persistent storage the key is registered in. +.PP +.SS pUuidData +The UUID the key was registered in the persistent storage (TSP or connected TCS). If no key UUID is provided, thus KeyUUID is NULL, the returned array of the TSS_KM_KEYINFO2 structure contains data reflecting the whole key hierarchy starting with root key. If a certain key is UUID is provided, the returned array of TSS_KM_KEYINFO2 structures only contains data reflecting the path of the key hierarchy regarding that key. The first array entry is the key addressed by the given UUID followed by its parent key up to the root key. +.PP +.SS pulKeyHierarchySize +Recieves the length (number of array entries) of the ppKeyHierarchy parameter. +.PP +.SS ppKeyHierarchy +On successful completion of the command, this parameter points to a buffer containing the actual key hierarchy data. +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetRegisteredKeysByUUID2\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhContext\fR is an invalid handle. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetRegisteredKeysByUUID2\fR conforms to the Trusted Computing Group Software Specification version 1.2 +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR(3). diff --git a/static/netbsd/man3/Tspi_Context_GetTpmObject.3 b/static/netbsd/man3/Tspi_Context_GetTpmObject.3 new file mode 100644 index 00000000..8acb8ce6 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_GetTpmObject.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_GetTpmObject" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Context_GetTpmObject \- get the handle of the TPM object associated with a context. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.br +.HP +.BI "TSS_RESULT Tspi_Context_GetTpmObject(TSS_HCONTEXT " hContext ", TSS_HTPM* " phTPM "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_GetTpmObject\fR retrieves the TPM object of a context. Only one instance of this +object exists for a given context and implicitly represents a TPM owner. This function is normally called at the beginning of a program, right after the context is established. You must have a context established prior to calling this function. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle of the context object +(already existing). +.SS phTPM +The \fIphTPM\fR parameter is a pointer to where the handle of the +TPM will be placed. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_GetTpmObject\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more of the parameters is incorrect. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_GetTpmObject\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_Create\fR(3), \fBTspi_Context_Connect\fR(3), \fBTspi_Context_FreeMemory\fR(3), \fBTspi_Context_Close\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_LoadKeyByBlob.3 b/static/netbsd/man3/Tspi_Context_LoadKeyByBlob.3 new file mode 100644 index 00000000..0d0c6cdd --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_LoadKeyByBlob.3 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_LoadKeyByBlob" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Context_LoadKeyByBlob \- load a key into the TPM using the key's blob. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_LoadKeyByBlob(TSS_HCONTEXT " hContext ", TSS_HKEY " hUnwrappingKey "," +.BI " UINT32 " ulBlobLength ", BYTE* " rgbBlobData "," +.BI " TSS_HKEY* " phKey "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_LoadKeyByBlob\fR +creates a key based on the information gotten by the key blob. It then +loads the key into the TPM, which unwraps the key blob by using the key +associated with \fIhUnwrappingKey\fR. The key blob addressed by +\fihUnwrappingKey\fR must have been already loaded into the TPM. This +function returns a handle to the created key object. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle of the context object. +.SS hUnwrappingKey +The \fIhUnwrappingKey\fR parameter is the handle of the key object +which should be used to unwrap the key information associated with +\fIrgbBlobData\fR. +.SS rgbBlobData +The \fIrgbBlobData\fR parameter is the wrapped key to load. +.SS phKey +The \fIphKey\fR parameter receives the handle of the key object +representing the loaded key. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_LoadKeyByBlob\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_LoadKeyByBlob\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR(3), \fBTspi_Policy_SetSecret\fR(3), +\fBTspi_GetPolicyObject\fR(3), \fBTspi_Key_CreateKey\fR(3), +\fBTspi_GetAttribUint32\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_LoadKeyByUUID.3 b/static/netbsd/man3/Tspi_Context_LoadKeyByUUID.3 new file mode 100644 index 00000000..3784de18 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_LoadKeyByUUID.3 @@ -0,0 +1,78 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_LoadKeyByUUID" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_LoadKeyByUUID \- load a key that's been registered in persistent storage. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_LoadKeyByUUID(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType ", " +.BI " TSS_UUID " uuidData ", TSS_HKEY* " phKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_LoadKeyByUUID\fR +creates a key object based on the information got from the manager using the UUID and loads the key into the TPM. The persistent storage provides all information to load the parent keys required to load the key associated with the given UUID. +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS persistentStorageType +Flag indicating the persistent storage the key is registered in. Should be either TSS_PS_TYPE_USER ot TSS_PS_TYPE_SYSTEM. +.PP +.SS uuidData +The UUID of the key by which the key was registered in the persistent storage (TSP or connected TCS). +.PP +.SS phKey +Receives the handle of the key object representing the loaded key. +.SH "RETURN CODES" +.PP +\fBTspi_Context_LoadKeyByUUID\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhContext\fR is an invalid handle. +.TP +.SM TSS_E_BAD_PARAMETER - \fIpersistentStorageType\fR is not valid. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByBlob(3)\fR, \fBTspi_Key_LoadKey(3)\fR. diff --git a/static/netbsd/man3/Tspi_Context_RegisterKey.3 b/static/netbsd/man3/Tspi_Context_RegisterKey.3 new file mode 100644 index 00000000..fe68b767 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_RegisterKey.3 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_RegisterKey" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Context_RegisterKey \- register a key in the TSS Persistent Storage database +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_RegisterKey(TSS_HCONTEXT " hContext ", TSS_HKEY " hKey "," +.BI " TSS_FLAG " persistentStorageType ", TSS_UUID " uuidKey "," +.BI " TSS_FLAG " persistentStorageTypeParent ", TSS_UUID " uuidParentKey "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Context_RegisterKey\fR is the API that +registers a key with the TSS Persistent Storage database so that it +can be loaded as necessary. It also includes all information required +for loading the key, as well as information about its parent key. + +.SH "PARAMETERS" +.PP +.SS hContext +The \fIhContext\fR parameter is the handle of the context object. +.SS hKey +The \fIhKey\fR parameter is the handle of the key object addressing the key +to be registered. +.SS persistentStorageType +The \fIpersistentStorageType\fR parameter indicates the persistent +storage the key is registered in. +.SS uuidKey +The \fIuuidKey\fR parameter is the UUID by which the key is registered in +persistent storage. +.SS persistentStorageTypeParent +The \fIpersistentStorageTypeParent\fR parameter indicates the persistent storage +that the parent key is registered in. +.SS uuidParentKey +The \fIuuidParentKey\fR parameter is the UUID by which the parent key is +registered in persistent storage. + +.SH "RETURN CODES" +.PP +\fBTspi_Context_RegisterKey\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_PS_KEY_NOTFOUND +The key cannot be found in the persistent storage database. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "EXAMPLE" +.nf +#include + +int +main(void) +{ + TSS_FLAGS initFlags = ...; + TSS_HKEY hKey, hSRK; + TSS_UUID keyUUID = {...}; + + // Create a TSP handle + result = Tspi_Context_Create(&hContext); + if (result != TSS_SUCCESS) + Error_Path(); + + // Connect to the TCSD + result = Tspi_Context_Connect(hContext, GLOBALSERVER); + if (result != TSS_SUCCESS) + Error_Path(); + + // Create the Key Object + result = Tspi_Context_CreateObject(hContext, + TSS_OBJECT_TYPE_RSAKEY, + initFlags, &hKey); + if (result != TSS_SUCCESS) + Error_Path(); + + // Load parent Key by UUID + result = Tspi_Context_LoadKeyByUUID(hContext, TSS_PS_TYPE_SYSTEM, + SRK_UUID, &hSRK); + if (result != TSS_SUCCESS) + Error_Path(); + + // Do policy/secret handling here + + result = Tspi_Key_CreateKey(hKey, hSRK, 0); + if (result != TSS_SUCCESS) + Error_Path(); + + // Register the Key in System PS (on the TCSD's platform) + result = Tspi_Context_RegisterKey(hContext, hKey, TSS_PS_TYPE_SYSTEM, + keyUUID, TSS_PS_TYPE_SYSTEM, + SRK_UUID); + if (result != TSS_SUCCESS) + Error_Path(); + + /* ... + * + * Use the key as needed, exiting the program if necessary, reloading + * the key using Tspi_Context_LoadKeyByUUID() after each restart. Once + * the key is no longer useful, unregister it from system PS as part + * of clean up. + */ + + // Unregister the Key + result = Tspi_Context_UnregisterKey(hContext, TSS_PS_TYPE_SYSTEM, + migratableSignUUID, &hKey); + if (result != TSS_SUCCESS) + Error_Path(); + + // exit, discarding hKey +} +.fi + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_RegisterKey\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_UnregisterKey\fR(3), \fBTspi_Context_LoadKeyByUUID\fR(3), +\fBTspi_Context_GetRegisteredKeyByUUID\fR(3). + diff --git a/static/netbsd/man3/Tspi_Context_UnregisterKey.3 b/static/netbsd/man3/Tspi_Context_UnregisterKey.3 new file mode 100644 index 00000000..fbda5887 --- /dev/null +++ b/static/netbsd/man3/Tspi_Context_UnregisterKey.3 @@ -0,0 +1,150 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Context_UnregisterKey" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Context_UnregisterKey \- unregister a key from the persistent storage device. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Context_UnregisterKey(TSS_HCONTEXT " hContext ", TSS_FLAG " persistentStorageType "," +.BI " TSS_UUID " uuidKey ", TSS_HKEY* " phKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Context_UnregisterKey\fR +provides the capabilities of the TSS Core Service or TSS Service Provider +.SH "PARAMETERS" +.PP +.SS hContext +The handle of the context object. +.PP +.SS persistentStorageType +Flag indicating the persistent storage. +.PP +.SS uuidKey +The UUID of the key to be removed from the persistent storage. +.PP +.SS phKey +Recieves the handle of a key object containing the information from the archive. +.PP +.SS pulRespDataLength +Recieves the length (in bytes) of the prgbRespData parameter. +.PP +.SS prgbRespData +On successful completion of the command, this parameter points to the buffer containing the actual data of the specified capability. +The handle of the object to be destroyed + +.SH "RETURN CODES" +.PP +\fBTspi_Context_UnregisterKey\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - the parameter \fIhContext\fR is an invalid parameter. +.TP +.SM TSS_E_PS_KEY_NOTFOUND - the parameter \fIuuidKey\fR is an invalid UUID. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "EXAMPLE" +.nf +#include + +int +main(void) +{ + TSS_FLAGS initFlags = ...; + TSS_HKEY hKey, hSRK; + TSS_UUID keyUUID = {...}; + + // Create a TSP handle + result = Tspi_Context_Create(&hContext); + if (result != TSS_SUCCESS) + Error_Path(); + + // Connect to the TCSD + result = Tspi_Context_Connect(hContext, GLOBALSERVER); + if (result != TSS_SUCCESS) + Error_Path(); + + // Create the Key Object + result = Tspi_Context_CreateObject(hContext, + TSS_OBJECT_TYPE_RSAKEY, + initFlags, &hKey); + if (result != TSS_SUCCESS) + Error_Path(); + + // Load parent Key by UUID + result = Tspi_Context_LoadKeyByUUID(hContext, TSS_PS_TYPE_SYSTEM, + SRK_UUID, &hSRK); + if (result != TSS_SUCCESS) + Error_Path(); + + // Do policy/secret handling here + + result = Tspi_Key_CreateKey(hKey, hSRK, 0); + if (result != TSS_SUCCESS) + Error_Path(); + + // Register the Key in System PS (on the TCSD's platform) + result = Tspi_Context_RegisterKey(hContext, hKey, TSS_PS_TYPE_SYSTEM, + keyUUID, TSS_PS_TYPE_SYSTEM, + SRK_UUID); + if (result != TSS_SUCCESS) + Error_Path(); + + /* ... + * + * Use the key as needed, exiting the program if necessary, reloading + * the key using Tspi_Context_LoadKeyByUUID() after each restart. Once + * the key is no longer useful, unregister it from system PS as part + * of clean up. + */ + + // Unregister the Key + result = Tspi_Context_UnregisterKey(hContext, TSS_PS_TYPE_SYSTEM, + migratableSignUUID, &hKey); + if (result != TSS_SUCCESS) + Error_Path(); + + // exit, discarding hKey +} +.fi + +.SH "CONFORMING TO" + +.PP +\fBTspi_Context_UnregisterKey\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Key_CreateKey\fR(3), \fBTspi_Context_RegisterKey\fR(3). diff --git a/static/netbsd/man3/Tspi_DAA_IssueCredential.3 b/static/netbsd/man3/Tspi_DAA_IssueCredential.3 new file mode 100644 index 00000000..144524a5 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_IssueCredential.3 @@ -0,0 +1,103 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_IssueCredential" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_IssueCredential \- issue a DAA credential for a TCG platform +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_IssueCredential(" +.BI " TSS_HDAA " hDAA "," +.BI " UINT32 " attributesIssuerLength "," +.BI " BYTE** " attributesIssuer "," +.BI " TSS_DAA_CREDENTIAL_REQUEST " credentialRequest "," +.BI " TSS_DAA_JOIN_ISSUER_SESSION " joinSession "," +.BI " TSS_DAA_CRED_ISSUER* " credIssuer +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_IssueCredential\fR +is part of the DAA Issuer component. It's the last function out of 2 in order to issue a DAA +Credential for a TCG Platform. It detects rogue TPM according to published rogue TPM DAA keys. +This is an optional function and does not require a TPM or a TCS. + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS attributesIssuerLength +The \fIattributesIssuerLength\fR parameter is the length of the attributesIssuer array, which is +determined by the DAA Issuer public key (li). The length of a single attribute is if/8. +.SS attributesIssuer +The \fIattributesIssuer\fR parameter is the array of attributes to be encoded into the DAA Credential +visible to the DAA Issuer . +.SS credentialRequest +The \fIcredentialRequest\fR parameter is the credential request of the Platform, it contains the +blinded DAA public key of the platform on which the DAA Issuer will issue the credential the +blinded attributes chosen by the Platform. +.SS joinSession +The \fIjoinSession\fR parameter is the structure containing the DAA Join session information. +.SS credIssuer +The \fIcredIssuer\fR parameter is the structure containing the DAA Credential issued by the DAA +Issuer, the proof of correctness of the credential and the attributes chosen by the DAA Issuer. + +.SH "RETURN CODES" +.PP +\fBTspi_DAA_IssueCredential\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.TP +.SM TSS_E_DAA_AUTHENTICATION_ERROR +The authentication proof of the TPM is incorrect. +.TP +.SM TSS_E_DAA_PSEUDONYM_ERROR +The TPM is rogue. +.TP +.SM TSS_E_DAA_CREDENTIAL_REQUEST_PROOF_ERROR +The proof of the credential request is incorrect. + +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_IssueCredential\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssuerKeyVerification\fR(3) + diff --git a/static/netbsd/man3/Tspi_DAA_IssueInit.3 b/static/netbsd/man3/Tspi_DAA_IssueInit.3 new file mode 100644 index 00000000..dd32d720 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_IssueInit.3 @@ -0,0 +1,113 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_IssueInit" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_IssueInit \- initialize the Issuer for a join operation +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_IssueInit(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HKEY " issuerAuthPK "," +.BI " TSS_HKEY " issuerKeyPair "," +.BI " TSS_DAA_IDENTITY_PROOF " identityProof "," +.BI " UINT32 " capitalUprimeLength "," +.BI " BYTE* " capitalUprime "," +.BI " UINT32 " daaCounter "," +.BI " UINT32* " nonceIssuerLength "," +.BI " BYTE** " nonceIssuer "," +.BI " UINT32* " authenticationChallengeLength "," +.BI " BYTE** " authenticationChallenge "," +.BI " TSS_DAA_JOIN_ISSUER_SESSION* " joinSession +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_IssueInit\fR +is a function that is part of the DAA Issuer component. It's the first function out of 2 in order +to issue a DAA Credential for a TCG Platform. It assumes that the endorsement key and its associated +credentials are from a genuine and valid TPM. (Verification of the credentials is a process defined +by the TCG Infrastructure WG.) + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS issuerAuthPK +The \fIissuerAuthPKh\fR parameter is the root authentication (public) key of DAA Issuer. +.SS issuerKeyPair +The \fIissuerKeyPair\fR parameter is the handle of the main DAA Issuer key pair (private and public portion). +.SS identityProof +The \fIidentityProof\fR parameter is the structure containing endorsement, platform and conformance +credential of the TPM requesting the DAA Credential. +.SS capitalUprimeLength +The \fIcapitalUprimeLength\fR parameter is the length of capitalUprime which is . +.SS capitalUprime +The \fIcapitalUprime\fR parameter is U'. +.SS daaCounter +The \fIdaaCounter\fR parameter is the DAA counter. +.SS nonceIssuerLength +The \fInonceIssuerLength\fR parameter is the length of nonceIssuer (20 bytes). +.SS nonceIssuer +The \fInonceIssuer\fR parameter is the nonce of the DAA Issuer. +.SS authenticationChallengeLength +The \fIauthenticationChallengeLength\fR parameter is the length of authenticationChallenge +(256 bytes - DAA_SIZE_NE1). +.SS authenticationChallenge +The \fIauthenticationChallenge\fR parameter is the second nonce of the DAA Issuer that is +encrypted by the endorsement public key. It is used as a challenge to authenticate the TPM. +.SS joinSession +The \fIjoinSession\fR parameter is the structure containing the DAA Join session information. +.SH "RETURN CODES" +.PP +\fBTspi_DAA_IssueInit\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_IssueInit\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssuerKeyVerification\fR(3) + diff --git a/static/netbsd/man3/Tspi_DAA_IssueSetup.3 b/static/netbsd/man3/Tspi_DAA_IssueSetup.3 new file mode 100644 index 00000000..1f52b2b8 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_IssueSetup.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_IssueSetup" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_IssueSetup \- generate a DAA Issuer public and private key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_IssueSetup(" +.BI " TSS_HDAA " hDAA "," +.BI " UINT32 " issuerBaseNameLength "," +.BI " BYTE* " issuerBaseName "," +.BI " UINT32 " numberPlatformAttributes "," +.BI " UINT32 " numberIssuerAttributes "," +.BI " TSS_HKEY* " keyPair "," +.BI " TSS_DAA_PK_PROOF** " identity_proof +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_IssueSetup\fR +is part of the DAA Issuer component. It defines the generation of a DAA Issuer +public and secret key. Further it defines the generation of a non-interactive proof (using +the Fiat-Shamir heuristic) that the public keys were chosen correctly. The latter will guarantee +the security requirements of the platform (respectively, its user), i.e., that the privacy and +anonymity of signatures will hold. +The generation of the authentication keys of the DAA Issuer, which are used to authenticate +(main) DAA Issuer keys, is not defined by this function. +This is an optional function and does not require a TPM or a TCS. + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS issuerBaseNameLength +The \fIissuerBaseNameLength\fR parameter is the length of the issuerBaseName. +.SS issuerBaseName +The \fIissuerBaseName\fR parameter is the unique name of the DAA Issuer. +.SS numberPlatformAttributes +The \fInumberPlatformAttributes\fR parameter is the number of attributes that the Platform can choose and which will not be visible to the Issuer. +.SS numberIssuerAttributes +The \fInumberIssuerAttributes\fR parameter is number of attributes that the Issuer can choose and which will be visible to both the Platform and the Issuer. +.SS keyPair +The \fIkeyPair\fR parameter is the handle of the main DAA Issuer key pair (private and public portion). +.SS publicKeyProof +The \fIpublicKeyProof\fR parameter is the Handle of the proof of the main DAA Issuer public key. + +.SH "RETURN CODES" +.PP +\fBTspi_DAA_IssueSetup\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_IssueSetup\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssuerKeyVerification\fR(3) + diff --git a/static/netbsd/man3/Tspi_DAA_IssuerKeyVerification.3 b/static/netbsd/man3/Tspi_DAA_IssuerKeyVerification.3 new file mode 100644 index 00000000..4c7e4b99 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_IssuerKeyVerification.3 @@ -0,0 +1,87 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_IssuerKeyVerification" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_IssuerKeyVerification \- verifies the DAA public key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_IssuerKeyVerification(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HKEY " issuerPk "," +.BI " TSS_DAA_PK_PROOF* " issuerPkProof "," +.BI " TSS_BOOL* " isCorrect +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_IssuerKeyVerification\fR +verifies the DAA public key of a DAA Issuer with respect to its associated proof. +This is a resource consuming task. It can be done by trusted third party (certification). +This is an optional function and does not require a TPM or a TCS. + + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS issuerPk +The \fIissuerPk\fR parameter is a DAA Issuer public key. +.SS issuerPkProof +The \fIissuerPkProof\fR parameter is a structure representing the proofs of the correctness of the DAA Issuer public key. +.SS isCorrect +The \fIisCorrect\fR parameter is the return corectness of the proof. + +.SH "RETURN CODES" +.PP +\fBTspi_DAA_IssuerKeyVerification\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_IssuerKeyVerification\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssueSetup\fR(3) + diff --git a/static/netbsd/man3/Tspi_DAA_VerifyInit.3 b/static/netbsd/man3/Tspi_DAA_VerifyInit.3 new file mode 100644 index 00000000..fb9c6d00 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_VerifyInit.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_VerifyInit" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_VerifyInit \- creates a challenge for the TCG platform +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_VerifyInit(" +.BI " TSS_HDAA " hDAA "," +.BI " UINT32* " nonceVerifierLength "," +.BI " BYTE** " nonceVerifier "," +.BI " UINT32* " baseNameLength "," +.BI " BYTE** " baseName +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_VerifyInit\fR +is part of the DAA Verifier component. It's the first function out of 2 in order to verify +a DAA Credential of a TCG platform. It creates a challenge for the TCG platform. +This is an optional function and does not require a TPM or a TCS. + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS nonceVerifierLength +The \fInonceVerifierLength\fR parameter is the length of the nonceVerifier. +.SS nonceVerifier +The \fInonceVerifier\fR parameter is the challenge for the platform. +.SS baseNameLength +The \fIbaseNameLength\fR parameter is the length of the baseName. +.SS baseName +The \fIbaseName\fR parameter is the base name that was chosen for the DAA Signature. + +.SH "RETURN CODES" +.PP +\fBTspi_DAA_VerifyInit\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_VerifyInit\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssuerKeyVerification\fR(3) + diff --git a/static/netbsd/man3/Tspi_DAA_VerifySignature.3 b/static/netbsd/man3/Tspi_DAA_VerifySignature.3 new file mode 100644 index 00000000..8dda7ce8 --- /dev/null +++ b/static/netbsd/man3/Tspi_DAA_VerifySignature.3 @@ -0,0 +1,106 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DAA_VerifySignature" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_DAA_VerifySignature \- creates a challenge for the TCG platform +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_DAA_VerifySignature(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_DAA_SIGNATURE " daaSignature "," +.BI " TSS_HKEY " hPubKeyIssuer "," +.BI " TSS_DAA_SIGN_DATA " signData "," +.BI " UINT32 " attributesLength "," +.BI " BYTE** " attributes "," +.BI " UINT32 " nonceVerifierLength "," +.BI " BYTE* " nonceVerifier "," +.BI " UINT32 " baseNameLength "," +.BI " BYTE* " baseName "," +.BI " TSS_BOOL* " isCorrect +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_DAA_VerifySignature\fR +is part of the DAA Verifier component. It's the last function out of 2 in order to verify a +DAA Credential of a TCG platform. It verifies the DAA Credential and detects public rogue TPMs. +This is an optional function and does not require a TPM or a TCS. + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS daaSignature +The \fIdaaSignature\fR parameter is the DAA signature contains proof of +ownership of the DAA Credential, as well as a signature on either an AIK or a message. +.SS hPubKeyIssuer +The \fIhPubKeyIssuer\fR parameter is the handle of the DAA public key of the DAA Issuer +of the credential. +.SS signData +The \fIsignData\fR parameter defines what data is signed (AIK or message). +.SS attributesLength +The \fIattributesLength\fR parameter is the Length of attributes array that is determined by +the DAA Issuer public key (lh+li). The length of a single attribute is lf/8. +.SS attributes +The \fIattributes\fR parameter is the array of attributes which the DAA Credential owner reveals. +.SS nonceVerifierLength +The \fInonceVerifierLength\fR parameter is the length of nonceVerifier (20 bytes). +.SS nonceVerifier +The \fInonceVerifier\fR parameter is the nonce that was computed in the previous function (Tspi_VerifyInit). +.SS baseNameLength +The \fIbaseNameLength\fR parameter the length of the baseName. +.SS baseName +The \fIbaseName\fR parameter is the base name that was chosen for the DAA Signature. +.SS isCorrect +The \fIisCorrect\fR parameter denotes if the verification of the DAA Signature was successful. + +.SH "RETURN CODES" +.PP +\fBTspi_DAA_VerifySignature\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.SH "CONFORMING TO" +.PP +\fBTspi_DAA_VerifySignature\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_DAA_IssuerKeyVerification\fR(3) + diff --git a/static/netbsd/man3/Tspi_Data_Bind.3 b/static/netbsd/man3/Tspi_Data_Bind.3 new file mode 100644 index 00000000..c8a01315 --- /dev/null +++ b/static/netbsd/man3/Tspi_Data_Bind.3 @@ -0,0 +1,116 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Data_Bind" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Data_Bind \- Encrypts a data blob +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Data_Bind(TSS_HENCDATA " hEncData ", TSS_HKEY " hEncKey "," +.BI " UINT32 " ulDataLength ", BYTE* " rgbDataToBind ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Data_Bind\fR encrypts a data blob in a manner +that is decryptable by \fBTspi_Data_Unbind\fR. The data blob is +encrypted using a public key operation with the key addressed by the +given encryption key object. To bind data that is larger than the RSA +public key modulus is the responsibility of the caller to perform the +blocking and subsequent combination of data. The bound data blob is +stored in the data object addressed by \fIhEncData\fR and can be +exported from the object by \fBTspi_GetAttribData\fR. The caller of +this function should perform validations that the public key presented +to it is from a valid TPM. + +.SH "PARAMETERS" +.PP +.SS hEncData +The handle of the data object which contains the encrypted data on +successful completion of the command. +.SS hEncKey +Handle to the key object addressing the public key which is used +to encrypt the data. +.SS ulDataLength +Indicates the length of the data provided at the parameter \fIrgbDataToBind\fR. +.SS rgbDataToBind +A pointer to the data to be encrypted. + +.SH "RETURN CODES" +.PP +\fBTspi_Data_Bind\fR returns TSS_SUCCESS on success, otherwise one of +the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhHash\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_INVALID_ENCSCHEME +Invalid encryption scheme. + +.TP +.SM TSS_E_ENC_INVALID_LENGTH +Invalid length of data to be encypted. + +.TP +.SM TSS_E_ENC_NO_DATA +No data to encrypt. + +.TP +.SM TSS_E_ENC_INVALID_TYPE +Invalid encryption type. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Data_Bind\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Data_Unbind\fR(3), \fBTspi_Data_Unseal\fR(3), +\fBTspi_Data_Seal\fR(3). + diff --git a/static/netbsd/man3/Tspi_Data_Seal.3 b/static/netbsd/man3/Tspi_Data_Seal.3 new file mode 100644 index 00000000..69b6f6d8 --- /dev/null +++ b/static/netbsd/man3/Tspi_Data_Seal.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Data_Seal" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Data_Seal \- encrypt a data blob in a mannar that is only decryptable by Tspi_Data_Unseal on the same system. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Data_Seal(TSS_HENCDATA " hEncData ", TSS_HKEY " hEncKey "," +.BI " UINT32 " ulDataLength ", BYTE* " rgbDataToSeal "," +.BI " TSS_HPCRS " hPcrComposite ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Data_Seal\fR encrypts a data blob in a mannar that is only decryptable by Tspi_Data_Unseal on the same system. The data blob is encrypted using a public key operation with the nonmigratable key addressed by the given encryption key object. +.SH "PARAMETERS" +.PP +.SS hEncData +Handle of the data object which contains the sealed data on successful completion of the command. +.PP +.SS hEncKey +Handle to the key object addressing the nonmigratable key which is used to encrypt the data. +.PP +.SS ulDataLength +The Length (in bytes) of the rgbDataToSeal parameter. +.PP +.SS rgbDataToSeal +Pointer to memory containing the data to be encrypted. +.PP +.SS hPcrComposite +Handle of the PCR Composite object specifying the PCRs which are part of the sealed data blob. Set to NULL, if the encrypted data should only be bound to the system and PCRs are not of interest. +.SH "RETURN CODES" +.PP +\fBTspi_Data_Seal\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - One of the following parameters \fIhEncData\fR, \fIhEncKey\fR, \fIrgbDataToSeal\fR is invalid. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Data_Seal\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Data_Unseal\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_Data_Unbind.3 b/static/netbsd/man3/Tspi_Data_Unbind.3 new file mode 100644 index 00000000..a5df697d --- /dev/null +++ b/static/netbsd/man3/Tspi_Data_Unbind.3 @@ -0,0 +1,109 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Data_Unbind" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Data_Unbind \- Decrypts data that has been bound to a key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Data_Unbind(TSS_HENCDATA " hEncData ", TSS_HKEY " hEncKey "," +.BI " UINT32* " pulUnboundDataLength ", BYTE** " prgbUnboundData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Data_Unbind\fR decrypts the encrypted data +blob exportedfrom the data object used in \fBTspi_Data_Bind\fR. The +encrypted data blob must be imported to the object addressed by +\fBTspi_SetAttribData\fR before calling this method. + +.SH "PARAMETERS" +.PP +.SS hEncData +The handle of the data object which contains the encrypted data. +.SS hEncKey +Handle to the key object addressing the private key which is used +to decrypt the data. +.SS pulDataLength +Receives the length of the data at the parameter \fIprgbUnboundData\fR. +.SS prgbUnboundData +Receives a pointer to a buffer containing the plaintext data. + +.SH "RETURN CODES" +.PP +\fBTspi_Data_Unbind\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhEncData\fR or \fIhEncKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_INVALID_ENCSCHEME +Invalid encryption scheme. + +.TP +.SM TSS_E_ENC_INVALID_LENGTH +Invalid length of data to be encypted. + +.TP +.SM TSS_E_ENC_NO_DATA +No data to encrypt. + +.TP +.SM TSS_E_ENC_INVALID_TYPE +Invalid encryption type. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Data_Unbind\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Data_Bind\fR(3), \fBTspi_Data_Unseal\fR(3), +\fBTspi_Data_Seal\fR(3). + diff --git a/static/netbsd/man3/Tspi_Data_Unseal.3 b/static/netbsd/man3/Tspi_Data_Unseal.3 new file mode 100644 index 00000000..f2553566 --- /dev/null +++ b/static/netbsd/man3/Tspi_Data_Unseal.3 @@ -0,0 +1,81 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Data_Unseal" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Data_Unseal \- dencrypt data encrypted by Tspi_Data_Seal() only if it was encrypted on the same platform and under the current configuration. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Data_Unseal(TSS_HENCDATA " hEncData ", TSS_HKEY " hKey "," +.BI " UINT32 " pulUnsealedDataLength ", BYTE** " prgbUnsealedData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Data_Unseal\fR reveals data encrypted by the Tspi_Data_Seal only if it was encrypted on the same platform and the current configuration. This is internally proofed and guaranteed by the TPM. +.SH "PARAMETERS" +.PP +.SS hEncData +Handle of the data object which contains the sealed data. +.PP +.SS hKey +Handle to the key object addressing the nonmigratable key which is used to decrypt the data. +.PP +.SS pulUnsealedDataLength +The length (in bytes) of the prgbUnsealedData parameter. +.PP +.SS prgbUnsealedData +On successful completion of the command, this parameter points to a buffer containing the plaintext data. +.PP +.SS hPcrComposite +Handle of the PCR Composite object specifying the PCRs which are part of the sealed data blob. Set to NULL, if the encrypted data should only be bound to the system and PCRs are not of interest. +.SH "RETURN CODES" +.PP +\fBTspi_Data_Unseal\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fBhEncData\fR or \fBhKey\fR is not a valid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Data_Unseal\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Data_Seal\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_DecodeBER_TssBlob.3 b/static/netbsd/man3/Tspi_DecodeBER_TssBlob.3 new file mode 100644 index 00000000..4da9706f --- /dev/null +++ b/static/netbsd/man3/Tspi_DecodeBER_TssBlob.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" Written by Tom Lendacky based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_DecodeBER_TssBlob" 3 "2007-06-12" "TSS 1.2" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_DecodeBER_TssBlob \- unwraps a BER-encoded TSS blob. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.sp +.BI "TSS_RESULT Tspi_DecodeBER_TssBlob(UINT32 " berBlobSize ", BYTE* " berBlob "," +.BI " UINT32* " blobType ", UINT32* " rawBlobSize "," +.BI " BYTE* " rawBlob ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_DecodeBER_TssBlob\fR is used to unwrap a BER-encoded blob in accordance with the ASN.1 data definitions in the Portable Data section of the Trusted Computing Group Software Stack Specification Version 1.2. +.SH "PARAMETERS" +.PP +.SS berBlobSize +Size of the BER-encoded blob. +.PP +.SS berBlob +Pointer to the BER-encoded blob. +.PP +.SS blobType +Pointer to the type of blob being unwrapped (refer to the TSS_BLOB_TYPE_* constants). +.PP +.SS rawBlobSize +Pointer to the size of the rawBlob buffer. On input this parameter contains a pointer to the maximum size of the supplied rawBlob buffer. On output this parameter contains a pointer to the actual size of the unwrapped blob. On input, if this parameter points to a value of 0, then this function will return the size of the buffer required to hold the unwrapped blob without writing to the rawBlob buffer. +.sp +\fBNote:\fR The output data must be shorter than the BER-encoding, so berBlobSize is a useful upper limit on rawBlob buffer size. +.PP +.SS rawBlob +Pointer to a buffer to hold the unwrapped blob. +.SH "RETURN CODES" +.PP +\fBTspi_EncodeDER_TssBlob\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_DecodeBER_TssBlob\fR conforms to the Trusted Computing Group Software Specification Version 1.2 +.SH "SEE ALSO" + +.PP +\fBTspi_DecodeBER_TssBlob\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_EncodeDER_TssBlob.3 b/static/netbsd/man3/Tspi_EncodeDER_TssBlob.3 new file mode 100644 index 00000000..b8e9ab6a --- /dev/null +++ b/static/netbsd/man3/Tspi_EncodeDER_TssBlob.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" Written by Tom Lendacky based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_EncodeDER_TssBlob" 3 "2007-06-12" "TSS 1.2" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_EncodeDER_TssBlob \- generate a DER encoded TSS blob. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.sp +.BI "TSS_RESULT Tspi_EncodeDER_TssBlob(UINT32 " rawBlobSize ", BYTE* " rawBlob "," +.BI " UINT32 " blobType ", UINT32* " derBlobSize "," +.BI " BYTE* " derBlob ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_EncodeDER_TssBlob\fR is used to generate a DER-encoded blob in accordance with the ASN.1 data definitions in the Portable Data section of the Trusted Computing Group Software Stack Specification Version 1.2. +.SH "PARAMETERS" +.PP +.SS rawBlobSize +Size of the unwrapped blob. +.PP +.SS rawBlob +Pointer to the unwrapped blob. +.PP +.SS blobType +Type of blob being wrapped (refer to the TSS_BLOB_TYPE_* constants). +.PP +.SS derBlobSize +Pointer to the size of the derBlob buffer. On input this parameter contains a pointer to the maximum size of the supplied derBlob buffer. On output this parameter contains a pointer to the actual size of the DER-encoded blob. On input, if this parameter points to a value of 0, then this function will return the size of the buffer required to hold the DER-encoded blob without writing to the derBlob buffer. +.sp +\fBNote:\fR If the raw data blob length is less than 2^16 bytes then the DER-encoding may add no more than 20 bytes. +.PP +.SS derBlob +Pointer to a buffer to hold the DER-encoded blob. +.SH "RETURN CODES" +.PP +\fBTspi_EncodeDER_TssBlob\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_EncodeDER_TssBlob\fR conforms to the Trusted Computing Group Software Specification Version 1.2 +.SH "SEE ALSO" + +.PP +\fBTspi_DecodeBER_TssBlob\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_GetAttribData.3 b/static/netbsd/man3/Tspi_GetAttribData.3 new file mode 100644 index 00000000..b1f1433b --- /dev/null +++ b/static/netbsd/man3/Tspi_GetAttribData.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_GetAttribData" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_GetAttribData \- get a non 32bit attribute of the object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_GetAttribData(TSS_HOBJECT " hObject ", TSS_FLAG " attribFlag "," +.BI " TSS_FLAG " subFlag ", UINT32* " pulAttribDataSize "," +.BI " BYTE** " prgbAttribData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_GetAttribData\fR is used to get the value of a particular attribute associated iwth a particular object where that attribute does not happen to be a UINT32. The structure and size of the attribute data depends on the attribute. +.SH "PARAMETERS" +.PP +.SS hObject +Handle of the object where to retrieve the attribute. +.PP +.SS attribFlag +Flag indicating the attribute to query. +.PP +.SS subFlag +Sub flag indicating the attribute to query. +.PP +.SS pulAttribDataSize +Recieves the length (in bytes) of the prgbAttribData parameter. +.PP +.SS prgbAttribData +On successful completion of the command, this parameter points to a buffer containing the actual data of the specified attribute. +.SH "RETURN CODES" +.PP +\fBTspi_GetAttribData\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhObject\fR, \fIattribFlag\fR, or \fIsubFlag\fR are invalid. +.TP +.SM TSS_E_ATTRIB_FLAG +.TP +.SM TSS_E_ATTRIB_SUBFLAG +.TP +.SM TSS_E_ATTRIB_DATA +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_GetAttribData\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_SetAttribData\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_GetAttribUint32.3 b/static/netbsd/man3/Tspi_GetAttribUint32.3 new file mode 100644 index 00000000..db98f353 --- /dev/null +++ b/static/netbsd/man3/Tspi_GetAttribUint32.3 @@ -0,0 +1,105 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_GetAttribUint32" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_GetAttribUint32 \- get the value of particular attribute associated with a given class or object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_GetAttribUint32(TSS_HOBJECT " hObject ", TSS_FLAG " attribFlag "," +.BI " TSS_FLAG " subFlag ", UINT32* " pulAttrib "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_GetAttribUint32\fR +returns a specified uint32 attribute associated with a given class +or object. In order to use this command, you must first create an +object and then find the attributes you wish to set. + +.SH "PARAMETERS" +.PP +.SS hObject +The \fIhObject\fR parameter is the handle of the object to retrieve +the attribute from. +.SS attribFlag +The \fIattribFlag\fR parameter indicates the specific attribute to query. +.SS subFlag +The \fIsubFlag\fR parameter also indicates the specific attribute to query. +.SS pulAttrib +The \fIpulAttrib\fR parameter is a pointer to the location where the +attribute value is returned. + +.SH "RETURN CODES" +.PP +\fBTspi_GetAttribUint32\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhObject\fR is not a valid handle. + +.TP +.SM TSS_E_INVALID_ATTRIB_FLAG +\fIattribFlag\fR is incorrect. + +.TP +.SM TSS_E_INVALID_ATTRIB_SUBFLAG +\fIsubFlag\fR is incorrect. + +.TP +.SM TSS_E_INVALID_ATTRIB_DATA +\fIpulAttrib\fR is incorrect. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_GetAttribUint32\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_GetAttribData\fR(3), \fBTspi_SetAttribUint32\fR(3), +\fBTspi_SetAttribData\fR(3). + diff --git a/static/netbsd/man3/Tspi_GetPolicyObject.3 b/static/netbsd/man3/Tspi_GetPolicyObject.3 new file mode 100644 index 00000000..932f472f --- /dev/null +++ b/static/netbsd/man3/Tspi_GetPolicyObject.3 @@ -0,0 +1,90 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_GetPolicyObject" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_GetPolicyObject \- get a policy object assigned to a working object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_GetPolicyObject(TSS_HOBJECT " hObject ", TSS_FLAG " policyType "," +.BI " TSS_HPOLICY* " phPolicy "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_GetPolicyObject\fR +returns a policy object currently assigned to a working object. If you +determine that the policy is different from what you require, you can +change the policy by creating a new one and using Tspi_Policy_AssignToObject. + +.SH "PARAMETERS" +.PP +.SS hObject +The \fIhObject\fR parameter is the handle of the object. +.SS policyType +The \fIpolicyType\fR parameter indicates the policy type of interest. +Types are TSS_POLICY_USAGE and TSS_POLICY_MIGRATION. +.SS phPolicy +The \fIphPolicy\fR parameter receives the handle to the assigned policy object. + +.SH "RETURN CODES" +.PP +\fBTspi_GetPolicyObject\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhContext\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_GetPolicyObject\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_GetTpmObject\fR(3), \fBTspi_Context_LoadKeyByUUID\fR(3), +\fBTspi_SetAttribUint32\fR(3), \fBTspi_Policy_AssignToObject\fR(3). + diff --git a/static/netbsd/man3/Tspi_Hash_GetHashValue.3 b/static/netbsd/man3/Tspi_Hash_GetHashValue.3 new file mode 100644 index 00000000..b45b8aff --- /dev/null +++ b/static/netbsd/man3/Tspi_Hash_GetHashValue.3 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Hash_GetHashValue" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Hash_GetHashValue \- get the current hash value of a hash object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Hash_GetHashValue(TSS_HHASH " hHash ", UINT32* " pulHashValueLength ", BYTE** " prgbHashValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Hash_GetHashValue\fR gets the hash value of +a hash object. \fBTspi_Context_FreeMemory\fR must be used to clean +up after this function, as memory is allocated for the +\fIprgbHashValue\fR data. + +.SH "PARAMETERS" +.PP +.SS hHash +The handle to the hash object instance whose hash value should be signed. +.SS pulHashValueLength +Receives the length of the hash value data returned at the parameter +\fIprgbHashValue\fR. +.SS prgbHashValue +Receives a pointer to the hash value data. + +.SH "RETURN CODES" +.PP +\fBTspi_Hash_GetHashValue\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhHash\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_HASH_INVALID_LENGTH +Hash length is inconsistent with hash algorithm. + +.TP +.SM TSS_E_HASH_NO_DATA +Hash object has no internal hash value. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Hash_GetHashValue\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Hash_UpdateHashValue\fR(3), \fBTspi_Hash_Sign\fR(3), +\fBTspi_Hash_VerifySignature\fR(3), \fBTspi_Hash_SetHashValue\fR(3). + diff --git a/static/netbsd/man3/Tspi_Hash_SetHashValue.3 b/static/netbsd/man3/Tspi_Hash_SetHashValue.3 new file mode 100644 index 00000000..cd16ba15 --- /dev/null +++ b/static/netbsd/man3/Tspi_Hash_SetHashValue.3 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Hash_SetHashValue" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Hash_SetHashValue \- Sets the hash value of a hash object for non-SHA1 hash objects. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Hash_SetHashValue(TSS_HHASH " hHash ", UINT32 " ulHashValueLength ", BYTE* " rgbHashValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Hash_SetHashValue\fR sets the hash value of +a hash object. If the object was created with the flag TSS_HASH_OTHER, +then the hash identifier has to be set by calling \fBTspi_SetAttribData\fR +to perform the sign operation. + +.SH "PARAMETERS" +.PP +.SS hHash +The handle to the hash object instance whose hash value should be signed. +.SS ulHashValueLength +Indicates the length of the hash value data provided at the parameter +\fIrgbHashValue\fR. +.SS rgbHashValue +A pointer to the hash value data. + +.SH "RETURN CODES" +.PP +\fBTspi_Hash_SetHashValue\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhHash\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_HASH_INVALID_LENGTH +Hash length is inconsistent with hash algorithm. + +.TP +.SM TSS_E_HASH_NO_DATA +Hash object has no internal hash value. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Hash_SetHashValue\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Hash_UpdateHashValue\fR(3), \fBTspi_Hash_Sign\fR(3), +\fBTspi_Hash_GetHashValue\fR(3). + diff --git a/static/netbsd/man3/Tspi_Hash_Sign.3 b/static/netbsd/man3/Tspi_Hash_Sign.3 new file mode 100644 index 00000000..6d46fc5c --- /dev/null +++ b/static/netbsd/man3/Tspi_Hash_Sign.3 @@ -0,0 +1,108 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Hash_Sign" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Hash_Sign \- sign the hash data of an object with a signing key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Hash_Sign(TSS_HHASH " hHash ", TSS_HKEY " hKey "," +.BI " UINT32 " pulSignatureLength ", BYTE** " prgbSignature ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Hash_Sign\fR signs the hash data of an +object with a given signing key. The data must be set at the hash +instance associated with \fIhHash\fR by calling +\fBTspi_Hash_SetHashValue\fR or \fBTspi_Hash_UpdateHashValue\fR. The +\fBTspi_Hash_Sign\fR method allocates a memory block for the +\fIprgbSignature\fR data. This memory must be released using +\fBTspi_Context_FreeMemory\fR. + +.SH "PARAMETERS" +.PP +.SS hHash +The handle to the hash object instance whose hash value should be signed. +.SS hKey +Handle to the key object which should be used for the signature. +.SS pulSignatureLength +Receives the length of the signature data returned at the parameter +\fIprgbSignature\fR on successful completion. +.SS prgbSignature +Receives a pointer to the signature data on successful completion. + +.SH "RETURN CODES" +.PP +\fBTspi_Hash_Sign\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_HASH_INVALID_LENGTH +Hash length is inconsistent with hash algorithm. + +.TP +.SM TSS_E_HASH_NO_DATA +Hash object has no internal hash value. + +.TP +.SM TSS_E_HASH_NO_IDENTIFIER +The hash algorithm identifier is not set. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Hash_Sign\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Hash_UpdateHashValue\fR(3), \fBTspi_Hash_SetHashValue\fR(3), +\fBTspi_Hash_VerifySignature\fR(3). + diff --git a/static/netbsd/man3/Tspi_Hash_UpdateHashValue.3 b/static/netbsd/man3/Tspi_Hash_UpdateHashValue.3 new file mode 100644 index 00000000..059435cc --- /dev/null +++ b/static/netbsd/man3/Tspi_Hash_UpdateHashValue.3 @@ -0,0 +1,99 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Hash_UpdateHashValue" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Hash_UpdateHashValue \- update the hash value of a hash object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Hash_UpdateHashValue(TSS_HHASH " hHash ", UINT32 " ulDataLength ", BYTE* " rgbData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Hash_UpdateHashValue\fR updates the hash value +of a hash object with new information. If the object was created with +the flag TSS_HASH_OTHER, then this method will return an error. \fBThe +object can't be modified after Tspi_Hash_SetHashValue, +Tspi_Hash_GetHashValue, Tspi_Hash_Sign, or Tspi_Hash_VerifySignature +have been called on it.\fR + +.SH "PARAMETERS" +.PP +.SS hHash +The handle to the hash object instance whose hash value should be signed. +.SS ulDataLength +Indicates the length of the data provided at the parameter \fIrgbData\fR. +.SS rgbData +A pointer to the data. + +.SH "RETURN CODES" +.PP +\fBTspi_Hash_UpdateHashValue\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhHash\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_HASH_INVALID_LENGTH +Hash length is inconsistent with hash algorithm. + +.TP +.SM TSS_E_HASH_NO_DATA +Hash object has no internal hash value. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Hash_UpdateHashValue\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Hash_GetHashValue\fR(3), \fBTspi_Hash_Sign\fR(3), +\fBTspi_Hash_SetHashValue\fR(3), \fBTspi_Hash_VerifySignature\fR(3). + diff --git a/static/netbsd/man3/Tspi_Hash_VerifySignature.3 b/static/netbsd/man3/Tspi_Hash_VerifySignature.3 new file mode 100644 index 00000000..47ffd745 --- /dev/null +++ b/static/netbsd/man3/Tspi_Hash_VerifySignature.3 @@ -0,0 +1,105 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Hash_VerifySignature" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Hash_VerifySignature \- verify the hash value with a given signature +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Hash_VerifySignature(TSS_HHASH " hHash ", TSS_HKEY " hKey "," +.BI " UINT32 " ulSignatureLength ", BYTE* " rgbSignature ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Hash_VerifySignature\fR verifies the hash value +of a given hash object with a given signature. In order to use this +command, one must have a hash and a signature of the hash that one is +trying to verify. The public key which corresponds to the private key +used to sign the hash is also needed. + +.SH "PARAMETERS" +.PP +.SS hHash +The handle to the hash object instance whose hash value should be signed. +.SS hKey +Handle to the key object which should be used for the signature verification. +.SS ulSignatureLength +The length of the signature data provided at the parameter \fIrgbSignature\fR. +.SS rgbSignature +A pointer to the signature data. + +.SH "RETURN CODES" +.PP +\fBTspi_Hash_VerifySignature\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_HASH_INVALID_LENGTH +Hash length is inconsistent with hash algorithm. + +.TP +.SM TSS_E_HASH_NO_DATA +Hash object has no internal hash value. + +.TP +.SM TSS_E_INVALID_SIGSCHEME +Invalid signature scheme. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_Hash_VerifySignature\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Hash_UpdateHashValue\fR(3), \fBTspi_Hash_SetHashValue\fR(3), +\fBTspi_Hash_Sign\fR(3), \fRTspi_Hash_GetHashValue\fR(3). + diff --git a/static/netbsd/man3/Tspi_Key_CertifyKey.3 b/static/netbsd/man3/Tspi_Key_CertifyKey.3 new file mode 100644 index 00000000..c64b0882 --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_CertifyKey.3 @@ -0,0 +1,76 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_CertifyKey" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Key_CertifyKey \- sign a public key. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_CertifyKey(TSS_HKEY " hKey ", TSS_HKEY " hCertifyingKey "," +.BI " TSS_VALIDATION* " pValidationData ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_Key_CertifyKey\fR signs a public key. +.SH "PARAMETERS" +.PP +.SS hKey +Handle of the key object to be loaded. +.PP +.SS hCertifyingKey +Handle to the certifying key used to sign the addressed by hKey. +.PP +.SS pValidationData +Pointer to a structure of the type TSS_VALIDATION. After successful completion of the call the member rgbValidationData of this structure contains the signature data of the command. The member prgbData of the structure points to a buffer containing a TCPA_CERTIFY_INFO data stream as specified within the TCPA 1.1b Main Specification. +.SH "RETURN CODES" +.PP +\fBTspi_Key_CertifyKey\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhKey\fR or \fIhCertifyingKey\fR are invalid handles. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_CertifyKey\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Key_CreateKey\fR(3), \fBTspi_Key_WrapKey\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_Key_ConvertMigrationBlob.3 b/static/netbsd/man3/Tspi_Key_ConvertMigrationBlob.3 new file mode 100644 index 00000000..0b8d49dc --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_ConvertMigrationBlob.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_ConvertMigrationBlob" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Key_ConvertMigrationBlob \- create a wrapped key from a migration blob +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_ConvertMigrationBlob(TSS_HKEY " hKeyToMigrate ", TSS_HKEY " hParentKey "," +.BI " UINT32 " ulRandomLength ", BYTE* " rgbRandom "," +.BI " UINT32 " ulMigrationBlobLength ", BYTE* " rgbMigrationBlob ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Key_ConvertMigrationBlob\fR takes the +migration blob built by \fBTspi_Key_CreateMigrationBlob\fR using the +migration scheme TSS_MS_MIGRATE and creates a normal wrapped key. The +resulting normal wrapped key blob is stored in the instance associated +with hKeyToMigrate and may be retrieved from that instance by +\fBTspi_GetAttribData\fR. + +.SH "PARAMETERS" +.PP +.SS hKeyToMigrate +The handle of the key object to convert. +.SS hParentKey +Handle to the parent key related to the key addressed by \fIhKeyToMigrate\fR. +.SS ulRandomLength +Length of random data provided at the parameter \fIrgbRandom\fR. +.SS rgbRandom +Random data as returned together with the migration blob by the +method \fBTspi_Key_CreateMigrationBlob\fR. +.SS ulMigrationBlobLength +Length of the migration blob data provided at the parameter \fIrgbMigrationBlob\fR. +.SS rgbMigrationBlob +Migration blob data as returned by a previously called method +\fBTspi_Key_CreateMigrationBlob\fR. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_ConvertMigrationBlob\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhKeyToMigrate\fR or \fIhParentKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_ConvertMigrationBlob\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Key_LoadKey\fR(3), \fBTspi_Key_UnloadKey\fR(3), +\fBTspi_Key_CertifyKey\fR(3), \fBTspi_Key_CreateMigrationBlob\fR(3). + diff --git a/static/netbsd/man3/Tspi_Key_CreateKey.3 b/static/netbsd/man3/Tspi_Key_CreateKey.3 new file mode 100644 index 00000000..27b4364e --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_CreateKey.3 @@ -0,0 +1,71 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_CreateKey" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Key_CreateKey \- create a key pair within the TPM, wrapping it with the key addressed by hWrappingKey. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_CreateKey(TSS_HKEY " hKey ", TSS_HKEY " hWrappingKey ", TSS_HPCRS " hPcrComposite ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTSS_Key_CreateKey\fR +calls the TPM command TPM_CreateWrapKey. If hPcrComposite is not set to NULL, the created key blob is bound to this PCR values. The key object addressed by hKey must contain the key information needed for the creation. +.SH "PARAMETERS" +.PP +.SS hKey +The handle of the key object to create. +.PP +.SS hWrappingKey +The handle to the key used to wrap the newly created key. +.PP +.SS hPcrComposite +The handle to an object, if the value of the handle doesn't equal NULL, the newly create key will be bound ot the PCR values described with this object. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_CreateKey\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhKey\fR, \fIhWrappingKey\fR or \fIhPcrComposite\fR are invalid parameters. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_CreateKey\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Key_WrapKey\fR(3), \fBTspi_Key_CertifyKey\fR(3), \fBTspi_Key_RegisterKey\fR(3). diff --git a/static/netbsd/man3/Tspi_Key_CreateMigrationBlob.3 b/static/netbsd/man3/Tspi_Key_CreateMigrationBlob.3 new file mode 100644 index 00000000..97538494 --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_CreateMigrationBlob.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_CreateMigrationBlob" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Key_CreateMigrationBlob \- create a key blob suitable for migrating to another TPM. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_CreateMigrationBlob(TSS_HKEY " hKeyToMigrate ", TSS_HKEY " hParentKey "," +.BI " UINT32 " ulMigTicketLength ", BYTE* " rgbMigTicket "," +.BI " UINT32* " pulRandomLength ", BYTE** " prgbRandom "," +.BI " UINT32* " pulMigrationBlobLength ", BYTE** " prgbMigrationBlob ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_Key_CreateMigrationBlob\fR returns a key blob containing an encrypted section, which will be different depending on the migration scheme indicated within the migration ticket previously created by the method Tspi_TPM_AuthorizeMigrationTicket(). +.SH "PARAMETERS" +.PP +.SS hKeyToMigrate +Handle of the key object to migrate. +.PP +.SS hParentKey +Handle to the parent key related to the key addressed by hKeyToMigrate. +.PP +.SS ulMigTicketLength +The length (in bytes) of the rgbMigTickey parameter. +.PP +.SS rgbMigTicket +Pointer to memory containing the migration ticket (migration public key and its authorization digest). +.PP +.SS pulRandomLength +On successful completion this parameter returns the random data length returned at the parameter prgbRandom. +.PP +.SS prgbRandom +On successful completion this parameter returns the random data. +.PP +.SS pulMigrationBlobLength +On successful completion this parameter returns the length of the migration blob data returned at the parameter prgbMigrationBlob. +.PP +.SS prgbMigrationBlob +On successful completion this parameter returns the migration data blob. +.PP +.SH "RETURN CODES" +.PP +\fBTspi_Key_CreateMigrationBlob\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhKeyToMigrate\fR, \fIhParentKey\fR or \fIrgbMigTicket\fR are invalid parameters. +.TP +.SM TSS_E_BAD_PARAMETER - One of the passed parameters is wrong. +.TP +.SM TSS_E_KEY_NO_MIGRATION_POLICY - No migration policy picked. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_CreateMigrationBlob\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Key_CreateKey\fR(3), \fBTspi_Key_CertifyKey\fR(3). + + + + diff --git a/static/netbsd/man3/Tspi_Key_GetPubKey.3 b/static/netbsd/man3/Tspi_Key_GetPubKey.3 new file mode 100644 index 00000000..c298efb9 --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_GetPubKey.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_GetPubKey" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Key_GetPubKey \- get the public key of an object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_GetPubKey(TSS_HKEY " hKey ", UINT32* " pulPubKeyLength ", BYTE** " prgbPubKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Key_GetPubKey\fR gets the public portion of a +given key object. + +.SH "PARAMETERS" +.PP +.SS hKey +The \fIhKey\fR parameter is the handle of the key object to unload. +.SS pulPubKeyLength +The \fIpulPubKeyLength\fR parameter receives the length in bytes of the +\fIprgbPubKey\fR parameter. +.SS prgbPubKey +The \fIprgbPubKey\fR parameter receives a pointer to the memory block +containing the public key blob retrieved for the key object referenced +by \fIhKey\fR. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_GetPubKey\fR returns TSS_SUCCESS on success, otherwise one of +the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_GetPubKey\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Key_LoadKey\fR(3), \fBTspi_Key_UnloadKey\fR(3), +\fBTspi_Key_CertifyKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_Key_LoadKey.3 b/static/netbsd/man3/Tspi_Key_LoadKey.3 new file mode 100644 index 00000000..00541f24 --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_LoadKey.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2005 International Business Machines Corporation +.\" Written by Kent Yoder based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_LoadKey" 3 "2005-02-01" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Key_LoadKey \- load a key into the TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_LoadKey(TSS_HKEY " hKey ", TSS_HKEY " hUnwrappingKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Key_LoadKey\fR loads the key referenced +by \fIhKey\fR into the TPM. + +.SH "PARAMETERS" +.PP +.SS hKey +The \fIhKey\fR parameter is the handle of the key object to load. +.SS hUnwrappingKey +The \fIhUnwrappingKey\fR parameter is the handle of the key which should be used to unwrap the key addressed by \fIhKey\fR. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_LoadKey\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either \fIhKey\fR or \fIhUnwrappingKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_LoadKey\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Key_UnloadKey\fR(3), \fBTspi_Key_GetPubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_Key_UnloadKey.3 b/static/netbsd/man3/Tspi_Key_UnloadKey.3 new file mode 100644 index 00000000..42c5009a --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_UnloadKey.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_UnloadKey" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_Key_UnloadKey \- unload a key from the TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_UnloadKey(TSS_HKEY " hKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Key_UnloadKey\fR unloads the key referenced +by the given key object from the TPM. This call will result in a +TPM_EvictKey operation for the specified key. + + +.SH "PARAMETERS" +.PP +.SS hKey +The \fIhKey\fR parameter is the handle of the key object to unload. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_UnloadKey\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_UnloadKey\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Key_LoadKey\fR(3), \fBTspi_Key_GetPubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_Key_WrapKey.3 b/static/netbsd/man3/Tspi_Key_WrapKey.3 new file mode 100644 index 00000000..d9e0673c --- /dev/null +++ b/static/netbsd/man3/Tspi_Key_WrapKey.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Kent Yoder based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Key_WrapKey" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Key_WrapKey \- wrap a key with the key addressed by hWrappingKey. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Key_WrapKey(TSS_HKEY " hKey ", TSS_HKEY " hWrappingKey "," +.BI " TSS_HPCRS " hPcrComposite ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTSS_Key_WrapKey\fR +wraps the private key \fIhKey\fR using the public key addressed by \fIhWrappingKey\fR. If hPcrComposite is not set to NULL (0), the created key blob is bound to its PCR values. The key object addressed by \fIhKey\fR must contain the key information needed for the creation. On successful return from this call, \fIhKey\fR can be loaded into a TPM. \fIhKey\fR must have been created as a migratable key and should have its usage and migrations secrets set using \fBTspi_Policy_SetSecret(3)\fR. Also, \fIhKey\fR should have had its private key set to either RSA private component, p or q. +.SH "PARAMETERS" +.PP +.SS hKey +The handle of the key object that is wrapped. +.PP +.SS hWrappingKey +The handle to the key used to wrap the newly created key. +.PP +.SS hPcrComposite +The handle to an object, if the value of the handle doesn't equal NULL, the newly create key will be bound ot the PCR values described with this object. + +.SH "RETURN CODES" +.PP +\fBTspi_Key_WrapKey\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhKey\fR, \fIhWrappingKey\fR or \fIhPcrComposite\fR are invalid handles. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Key_WrapKey\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Key_CreateKey\fR(3), \fBTspi_Key_CertifyKey\fR(3), \fBTspi_Key_RegisterKey\fR(3). diff --git a/static/netbsd/man3/Tspi_PcrComposite_GetPcrValue.3 b/static/netbsd/man3/Tspi_PcrComposite_GetPcrValue.3 new file mode 100644 index 00000000..f807956e --- /dev/null +++ b/static/netbsd/man3/Tspi_PcrComposite_GetPcrValue.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_PcrComposite_GetPcrValue" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_PcrComposite_GetPcrValue \- get the digest value of a given PCR index inside a PCR composite object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_PcrComposite_GetPcrValue(TSS_HPCRS " hPcrComposite ", UINT32 " ulPcrIndex "," +.BI " UINT32* " ulPcrValueLength ", BYTE** " rgbPcrValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_PcrComposite_GetPcrValue\fR returns the digest value of a given PCR index inside a PCR composite object. +.SH "PARAMETERS" +.PP +.SS hPcrComposite +Handle of the PCR composite object instance where a PCR value should be returned. +.PP +.SS ulPcrIndex +This parameter indicates the index of the PCR to read. +.PP +.SS ulPcrValueLength +The length (in bytes) of the rgbPcrValue parameter. +.PP +.SS rgbPcrValue +After successful completion this parameter recieves a pointer to the memory block containing the PCR value of the PCR indicated by ulPcrIndex. +.SH "RETURN CODES" +.PP +\fBTspi_PcrComposite_GetPcrValue\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhPcrComposite\fR or \fIulPcrIndex\fR is an invalid parameter. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_PcrComposite_GetPcrValue\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_PcrComposite_SelectPcrIndex\fR(3), \fBTspi_PcrComposite_SetPcrValue\fR(3). + + diff --git a/static/netbsd/man3/Tspi_PcrComposite_SelectPcrIndex.3 b/static/netbsd/man3/Tspi_PcrComposite_SelectPcrIndex.3 new file mode 100644 index 00000000..812ba480 --- /dev/null +++ b/static/netbsd/man3/Tspi_PcrComposite_SelectPcrIndex.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_PcrComposite_SelectPcrIndex" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_PcrComposite_SelectPcrIndex\- select a PCR index inside a PCR composite object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_PcrComposite_SelectPcrIndex(TSS_HPCRS " hPcrComposite ", UINT32 " ulPcrIndex ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_PcrComposite_SelectPcrIndex\fR selects a PCR index inside a PCR composite object. The PCR composite object must be created withthe function Tspi_Context_CreateObject(). An exampled for the usage is the selection of PCR registeres before calling Tspi_TPM_Quote(). +.SH "PARAMETERS" +.PP +.SS hPcrComposite +Handle of the PCR composite object instance where the index should be selected. +.PP +.SS ulPcrIndex +This parameter indicates the index of the PCR to select. +.SH "RETURN CODES" +.PP +\fBTspi_PcrComposite_SelectPcrIndex\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhPcrComposite\fR or \fIulPcrIndex\fR is an invalid handle. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_PcrComposite_SelectPcrIndex\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_Quote\fR(3), \fBTspi_PcrComposite_SetPcrValue\fR(3), \fBTspi_PcrComposite_GetPcrValue\fR(3). + + diff --git a/static/netbsd/man3/Tspi_PcrComposite_SetPcrValue.3 b/static/netbsd/man3/Tspi_PcrComposite_SetPcrValue.3 new file mode 100644 index 00000000..d010ee1c --- /dev/null +++ b/static/netbsd/man3/Tspi_PcrComposite_SetPcrValue.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_PcrComposite_SetPcrValue" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_PcrComposite_SetPcrValue\- set the digest for a given PCR index inside a PCR composite object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_PcrComposite_SetPcrValue(TSS_HPCRS " hPcrComposite ", UINT32 " ulPcrIndex "," +.BI " UINT32 " ulPcrValueLength ", BYTE* " rgbPcrValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_PcrComposite_SetPcrValue\fR sets the digest for a given PCR index inside the PCR composite object. +.SH "PARAMETERS" +.PP +.SS hPcrComposite +Handle of the PCR composite object instance where a PCR value should be set. +.PP +.SS ulPcrIndex +This parameter indicates the index of the PCR to set. +.PP +.SS ulPcrValueLength +The length (in bytes) of the rgbPcrValue parameter. +.PP +.SS rgbPcrValue +Pointer to memory containing the actual value which should be set for the PCR indicated by ulPcrIndex. +.SH "RETURN CODES" +.PP +\fBTspi_PcrComposite_SetPcrValue\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - Either \fIhPcrComposite\fR or \fIulPcrIndex\fR is an invalid parameter. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_PcrComposite_SetPcrValue\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_PcrComposite_SelectPcrIndex\fR(3), \fBTspi_PcrComposite_GetPcrValue\fR(3). + + diff --git a/static/netbsd/man3/Tspi_Policy_AssignToObject.3 b/static/netbsd/man3/Tspi_Policy_AssignToObject.3 new file mode 100644 index 00000000..fdf10496 --- /dev/null +++ b/static/netbsd/man3/Tspi_Policy_AssignToObject.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Policy_AssignToObject" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Policy_AssignToObject \- assign a policy to an object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Policy_AssignToObject(TSS_HPOLICY " hPolicy ", TSS_HOBJECT " hObject ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Policy_AssignToObject\fR assigns a given object +to a certain policy. The object then uses its assigned policy to process +an authorized TPM command. When each new object is initialized, it is +assigned to the default policy, which is created when a context object +is created. When an object is assigned to a policy, a reference is added +to the list of assigned objects stored in the policy, and a reference +to the policy is stored in the object by internal object functions. + +.SH "PARAMETERS" +.PP +.SS hPolicy +The \fIhPolicy\fR parameter is the handle of the policy object to be +assigned to. +.SS hObject +The \fIhObject\fR parameter is the object that will be assigned to +\fIhPolicy\fR. + +.SH "RETURN CODES" +.PP +\fBTspi_Policy_AssignToObject\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhPolicy\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Policy_AssignToObject\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Policy_SetSecret\fR(3), \fBTspi_Policy_FlushSecret\fR(3). + diff --git a/static/netbsd/man3/Tspi_Policy_FlushSecret.3 b/static/netbsd/man3/Tspi_Policy_FlushSecret.3 new file mode 100644 index 00000000..eea7fdac --- /dev/null +++ b/static/netbsd/man3/Tspi_Policy_FlushSecret.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Policy_FlushSecret" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_Policy_FlushSecret \- flush a cached secret +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Policy_FlushSecret(TSS_HPOLICY " hPolicy ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_Policy_FlushSecret\fR +tells the TSS to flush a secret that it had cached for a user. + +.SH "PARAMETERS" +.PP +.SS hPolicy +The \fIhPolicy\fR parameter is the handle of the policy object to be flushed. + +.SH "RETURN CODES" +.PP +\fBTspi_Policy_FlushSecret\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhPolicy\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_Policy_FlushSecret\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Policy_SetSecret\fR(3), \fBTspi_Policy_AssignToObject\fR(3). + diff --git a/static/netbsd/man3/Tspi_Policy_SetSecret.3 b/static/netbsd/man3/Tspi_Policy_SetSecret.3 new file mode 100644 index 00000000..47ed4ab3 --- /dev/null +++ b/static/netbsd/man3/Tspi_Policy_SetSecret.3 @@ -0,0 +1,80 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_Policy_SetSecret" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_Policy_SetSecret \- set the authorization data of a policy object and define the handling of its retrieval +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_Policy_SetSecret(TSS_HPOLICY " hPolicy ", TSS_FLAG " secretMode "," +.BI " UINT32 " ulSecretLength ", BYTE* " rgbSecret ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_Policy_SetSecret\fR +sets the authorization data for an object. This mthod also defines the handling of its retrieving. There are mand different paths as specified by the secretMode Flag. +.SH "PARAMETERS" +.PP +.SS hPolicy +The handle of the policy object. +.PP +.SS secretMode +Flag indicating the policy secret mode to set. Possible values are: + \fBTSS_SECRET_MODE_SHA1\fR - Secret in the form of 20 bytes of SHA-1 data. The secret will not be touched by the TSP. + \fBTSS_SECRET_MODE_PLAIN\fR - The data passed in will be hashed by the TSP using SHA-1. + \fBTSS_SECRET_MODE_POPUP\fR - The TSP will ask for a secret by displaying a GUI pop-up window. + \fBTSS_SECRET_MODE_CALLBACK\fR - The application will provide a callback function for authorization data. + \fBTSS_SECRET_MODE_NONE\fR - \fIulSecretLen\fR and \fIrgbSecret\fR are ignored and any object requiring auth assigned this policy will return an error. +.PP +.SS ulSecretLength +The length (in bytes) of the rgbSecret parameter. +.PP +.SS rgbSecret +The secret data blob. +.SH "RETURN CODES" +.PP +\fBTspi_Policy_SetSecret\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - hPolicy is an invalid parameter. +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_Policy_SetSecret\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Policy_FlushSecret\fR(3). diff --git a/static/netbsd/man3/Tspi_SetAttribData.3 b/static/netbsd/man3/Tspi_SetAttribData.3 new file mode 100644 index 00000000..d16ab473 --- /dev/null +++ b/static/netbsd/man3/Tspi_SetAttribData.3 @@ -0,0 +1,87 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_SetAttribData" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_SetAttribData \- set a non 32bit attribute of an object. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_SetAttribData(TSS_HOBJECT " hObject ", TSS_FLAG " attribFlag "," +.BI " TSS_FLAG " subFlag ", UINT32 " ulAttribDataSize "," +.BI " BYTE* " rgbAttribData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_SetAttribData\fR sets the attributes associated with a given class of object that aren't UINT32. The structure and size of hte attribute data depends on the attribute. +.SH "PARAMETERS" +.PP +.SS hObject +Handle of the object where the attribute is to be set. +.PP +.SS attribFlag +Flag indicating the attribute to set. +.PP +.SS subFlag +Sub flag indicating the attribute to set +.PP +.SS ulAttribDataSize +Supplies the length (in bytes) of the rgbAttribData. +.PP +.SS rgbAttribData +Pointer to the actual data which is to be set for the specified attribute. +.SH "RETURN CODES" +.PP +\fBTspi_SetAttribData\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhObject\fR is an invalid parameter. +.TP +.SM TSS_E_ATTRIB_FLAG - \fIattribFlag\fR is an invalid parameter. +.TP +.SM TSS_E_ATTRIB_SUBFLAG - \fIsubFlag\fR is an invalid parameter. +.TP +.SM TSS_E_ATTRIB_DATA - \fIrgbAttribData\fR is an invalid parameter. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_SetAttribData\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_GetAttribData\fR(3). diff --git a/static/netbsd/man3/Tspi_SetAttribUint32.3 b/static/netbsd/man3/Tspi_SetAttribUint32.3 new file mode 100644 index 00000000..3c8280c8 --- /dev/null +++ b/static/netbsd/man3/Tspi_SetAttribUint32.3 @@ -0,0 +1,106 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_SetAttribUint32" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developers Reference +.SH NAME +Tspi_SetAttribUint32 \- set a 32bit attribute associated with a given class or object +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_SetAttribUint32(TSS_HOBJECT " hObject ", TSS_FLAG " attribFlag "," +.BI " TSS_FLAG " subFlag ", UINT32 " ulAttrib "); " +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_SetAttribUint32\fR sets a uint32 attribute +associated with a given class or object. In order to use this +command, you must first create an object and then find the attributes +you wish to set. + +.SH "PARAMETERS" +.PP +.SS hObject +The \fIhObject\fR parameter is the handle of the object or class +whose attributes are being set. Note that this is any object handler +- context, policy, TPM, key, hash, etc. +.SS attribFlag +The \fIattribFlag\fR parameter indicates the specific attribute to be set. +.SS subFlag +The \fIsubFlag\fR parameter also indicates the specific attribute to be set. +.SS ulAttrib +The \fIulAttrib\fR parameter is the value that the specified attribute +will be set to. + +.SH "RETURN CODES" +.PP +\fBTspi_SetAttribUint32\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhObject\fR is not a valid handle. + +.TP +.SM TSS_E_INVALID_ATTRIB_FLAG +\fIattribFlag\fR is incorrect. + +.TP +.SM TSS_E_INVALID_ATTRIB_SUBFLAG +\fIsubFlag\fR is incorrect. + +.TP +.SM TSS_E_INVALID_ATTRIB_DATA +\fIulAttrib\fR is incorrect. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_SetAttribUint32\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_GetAttribUint32\fR(3), \fBTspi_SetAttribData\fR(3), +\fBTspi_GetAttribData\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_AuthorizeMigrationTicket.3 b/static/netbsd/man3/Tspi_TPM_AuthorizeMigrationTicket.3 new file mode 100644 index 00000000..a68a7c0d --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_AuthorizeMigrationTicket.3 @@ -0,0 +1,84 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_AuthorizeMigrationTicket" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_AuthorizeMigrationTicket\- create the migration ticket required for the migration process. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_AuthorizeMigrationTicket(TSS_HTPM " hTPM ", TSS_HKEY " hMigrationKey "," +.BI " TSS_MIGRATE_SCHEME " migrationScheme ", UINT32* " pulMigTicketLength "," +.BI " BYTE** " prgbMigTicket ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_AuthorizeMigrationTicket\fR is used by the owner to authorize a target public key for migration. This mean sthat when a system is set up, the owner can decide that all archives should be done on a particular server. Then as keys are created, the user can pick one of these servers for the target of the migration of their keys, if they wish. This provides one of the two authorizations necessary to migrate a key. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object +.PP +.SS hMigrationKey +Handle of the object representing the migration key. +.PP +.SS migrationScheme +Flag indiating the migration scheme to be used. +.PP +.SS pulMigTicketLength +Recieves the length (in bytes) of the prgbMigTicket parameter. +.PP +.SS prgbMigTicket +Recieves a pointer to thememory block containing the migration ticket blob. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_AuthorizeMigrationTicket\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either \fBhTPM\fR or \fBhMigrationKey\fR is not a valid handle. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_AuthorizeMigrationTicket\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fB(none)\fR. + + + diff --git a/static/netbsd/man3/Tspi_TPM_CMKSetRestrictions.3 b/static/netbsd/man3/Tspi_TPM_CMKSetRestrictions.3 new file mode 100644 index 00000000..1b233d42 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CMKSetRestrictions.3 @@ -0,0 +1,93 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CMKSetRestrictions" 3 "2007-12-13" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_CMKSetRestrictions \- set restrictions on use of delegated Certified Migratable Keys +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CMKSetRestrictions(TSS_HTPM " hTPM ", TSS_CMK_DELEGATE " CmkDelegate ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_CMKSetRestrictions\fR is used to set restrictions on the delegated use of Certified Migratable Keys (CMKs). Use of this command cannot itself be delegated. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS CmkDelegate +The \fICmkDelegate\fR parameter is a bitmask describing the kinds of CMKs that can be used in a delegated auth session. Each bit represents a type of key. If the bit of a key type is set, then the CMK can be used in a delegated authorization session, otherwise use of that key will result in a TPM_E_INVALID_KEYUSAGE return code from the TPM. + +The possible values of \fICmkDelegate\fR are any combination of the following flags logically OR'd together: + +.TP +.SM "TSS_CMK_DELEGATE_SIGNING" +Allow use of signing keys. + +.TP +.SM "TSS_CMK_DELEGATE_STORAGE" +Allow use of storage keys. + +.TP +.SM "TSS_CMK_DELEGATE_BIND" +Allow use of binding keys. + +.TP +.SM "TSS_CMK_DELEGATE_LEGACY" +Allow use of legacy keys. + +.TP +.SM "TSS_CMK_DELEGATE_MIGRATE" +Allow use of migratable keys. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CMKSetRestrictions\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CMKSetRestrictions\fR conforms to the Trusted Computing Group +Software Specification version 1.2 Errata A + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_CMKApproveMA\fR(3), \fBTspi_TPM_CMKCreateTicket\fR(3), \fBTspi_Key_CMKCreateBlob\fR(3) + diff --git a/static/netbsd/man3/Tspi_TPM_CertifySelfTest.3 b/static/netbsd/man3/Tspi_TPM_CertifySelfTest.3 new file mode 100644 index 00000000..995ac7dd --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CertifySelfTest.3 @@ -0,0 +1,80 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CertifySelfTest" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_CertifySelfTest\- have the TPM sign its self test data +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CertifySelfTest(TSS_HTPM " hTPM ", TSS_HKEY " hKey "," +.BI " TSS_VALIDATION* " pValidationData " );" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_CertifySelfTest\fR performs a self-test of each internal TPM function and returns an authenticated value (signature) if the test has passed. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object +.PP +.SS hKey +Handle of the signature key object +.PP +.SS +pValidationData +Validation data structure. +[IN] Provide externalData information required to compute the signature. +[OUT] On successful completion of the ocmmand, the structure provides a buffer containing the validation data and a buffer containing the data the validation data was computed from. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CertifySelfTest\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fBhTPM\fR is not a valid handle to a TPM object. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CertifySelfTest\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_SelfTestFull\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_CheckMaintenancePubKey.3 b/static/netbsd/man3/Tspi_TPM_CheckMaintenancePubKey.3 new file mode 100644 index 00000000..e95ced21 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CheckMaintenancePubKey.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CheckMaintenancePubKey" 3 "2004-05-26" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_CheckMaintenancePubKey\- check the public maintenance key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CheckMaintenancePubKey(TSS_HTPM " hTPM ", TSS_HKEY " hMaintenanceKey "," +.BI " TSS_VALIDATION* " pValidationData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_CheckMaintenancePubKey\fR +checks the public maintenance key. If \fIhMaintenanceKey\fR +is NULL, then \fIpValidationData\fR must not be NULL; the caller has to +proof the digest on its own. If \fIhMaintenanceKey\fR is not NULL, then +\fIpValidationData\fR must be NULL; the TSS service provider proofs the +digest got internally from the TPM. The key information required for +proofing the public maintenance key must be set in the key object by +Tspi_SetAttribData before this method is called. \fBThis function is +not yet implemented\fR. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object +.PP +.SS hMaintenanceKey +Handle of the maintenance key object +.PP +.SS pValidationData +Validation data structure. +[IN] Provide externalData information required to compute the signature. +[OUT] On successful completion of the ocmmand, the structure provides a +buffer containing the validation data and a buffer containing the data +the validation data was computed from. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CheckMaintenancePubKey\fR returns TSS_SUCCESS on success, +otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.TP +.SM TSS_E_BAD_PARAMETER +One or more of the parameters is incorrect. +.TP +.SM TSS_E_NOTIMPL +The command is not implemented. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CheckMaintenancePubKey\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_LoadMaintenancePubKey\fR(3), +\fBTspi_TPM_CreateMaintenanceArchive\fR(3), +\fBTspi_TPM_KillMaintenanceFeature\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_ClearOwner.3 b/static/netbsd/man3/Tspi_TPM_ClearOwner.3 new file mode 100644 index 00000000..cd474d4d --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_ClearOwner.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_ClearOwner" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_ClearOwner \- clear TPM ownership +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_ClearOwner(TSS_HTPM " hTPM ", TSS_BOOL " fForcedClear ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_ClearOwner\fR +wipes the TPM of everything but its endorsement key. It will wipe the SRK, so +anything locked to the SRK will also disappear when this command is executed. +This is the only way to be certain that keys are gone, as it is the only way +to guarantee that nothing can keep a copy of the key. You must assert either +physical presence or owner authorization in order to use this command. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS fForcedClear +The \fIfForcedClear\fR parameter is used to tell whether this command is being +executed with owner authorization or with physical presence. If FALSE, then +TPM owner authorization is used. If TRUE, then physical presence is required +to clear the TPM. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_ClearOwner\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_ClearOwner\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_TakeOwnership\fR(3) diff --git a/static/netbsd/man3/Tspi_TPM_CollateIdentityRequest.3 b/static/netbsd/man3/Tspi_TPM_CollateIdentityRequest.3 new file mode 100644 index 00000000..60ab76f0 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CollateIdentityRequest.3 @@ -0,0 +1,102 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CollateIdentityRequest" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_CollateIdentityRequest \- Gets all the informatin necessary to send to a trusted third party (TTP), repartory to asking the TTP to create a certificate for identity. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CollateIdentityRequest(TSS_HTPM " hTPM ", TSS_HKEY " hKeySRK "," +.BI " TSS_HKEY " hCAPPubKey "," +.BI " UINT32 " ulIdentityLabelData ", BYTE* " rgbIdentityLabelData "," +.BI " TSS_HKEY " hIdentityKey ", TSS_ALGORITHM_ID " algid "," +.BI " UINT32* " pulTCPAIdentityReqLength ", BYTE** " prgbTCPAIdentityReq ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTSS_TPM_CollateIdentityRequest\fR +creates an identity key, binds it to the label and returns a certificate request package. The privacty CA requires this certificate request to attest the identity key. + +Only the Owner of the TPM has the privledge of creating a TPM identity key. + +The symmetric session key is required to provide confidentiality of the "TCPA_IDENTITY_REQ" data structure, which should be sent to the Privacy CA chosen by the owner. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS hKeySRK +Handle to the key object representing the Storage Root Key +.PP +.SS hCAPubKey +Handle to the key object representing the public key of the CA which signs the certificate of the created identity key. +.PP +.SS ulIdentityLabelLength +Supplies the length (in bytes) of the rgbIdentityLabelData parameter +.PP +.SS rgbLabelData +Pointer to a memory block containing the identity label, which should be a UNICODE string +.PP +.SS hIdentityKey +Handle to the identity key object +.PP +.SS algid +The type of symmetric algorithm touse as requred by the Enhanced CA. +.PP +.SS pulTCPAIdentityReqLength +Recieves the length (in bytes) of the prgbTCPAIdentityReq parameter +.PP +.SS prgbTCPAIdentyReq +Pointer to the memory block containing the certicficate request structure. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CollateIdentityRequest\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either \fBhTPM\fR or \fBhKeySRK\fR or \fBhCAPubKey\fR is not a valid handle. +.TP +.SM TSS_E_BAD_PARAMETER + +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CollateIdentityRequest\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_Context_LoadKeyByUUID\fR(3). diff --git a/static/netbsd/man3/Tspi_TPM_CreateEndorsementKey.3 b/static/netbsd/man3/Tspi_TPM_CreateEndorsementKey.3 new file mode 100644 index 00000000..5c772ca3 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CreateEndorsementKey.3 @@ -0,0 +1,94 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CreateEndorsementKey" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_CreateEndorsementKey \- create the endorsement key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CreateEndorsementKey(TSS_HTPM " hTPM ", TSS_HKEY " hKey "," +.BI " TSS_VALIDATION* " pValidationData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_CreateEndorsementKey\fR +creates an endorsement key. \fBThis function is currently not implemented\fR. +Before this method is called, the key information for creating the key +must be set in the key object by \fITspi_SetAttribData\fR. On return, +the public endorsement key can be retrieved by \fITspi_GetAttribData\fR from +the key object. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS hKey +The \fIhKey\fR parameter is the handle of the key specifying the +attributes of the endorsement key to create. +.SS pValidationData +The \fIpValidationData\fR parameter is a validation data structure. It provides +external information required to compute the signature. Once the command is +completed, the structure provides a buffer containing the validation data and +a buffer containing the data the validation data was computed from. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CreateEndorsementKey\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR or \fIhKey\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CreateEndorsementKey\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetPubEndorsementKey\fR(3), \fBTspi_Key_GetPubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_CreateMaintenanceArchive.3 b/static/netbsd/man3/Tspi_TPM_CreateMaintenanceArchive.3 new file mode 100644 index 00000000..edf08354 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_CreateMaintenanceArchive.3 @@ -0,0 +1,107 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_CreateMaintenanceArchive" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_CreateMaintenanceArchive \- create the TPM manufacturer specific maintenance archive data. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_CreateMaintenanceArchive(TSS_HTPM " hTPM ", TSS_BOOL " fGenerateRndNumber "," +.BI " UINT32* " pulRndNumberLength ", BYTE** " prgbRndNumber "," +.BI " UINT32* " pulArchiveDataLength ", BYTE** " prgbArchiveData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_CreateMaintenanceArchive\fR +creates the TPM Manufacturer specific maintenance archive data. +\fBThis command is not currently implemented by any manufacturer\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS fGenerateRndNumber +The \fIfGenerateRndNumber\fR parameter determines how the random number +is generated. If TRUE, a random number is generated by the TPM and +returned. If FALSE, a random number is calculated based on the owner +secret. +.SS pulRndNumberLength +The \fIpulRndNumberLength\fR parameter receives the length in bytes of +the \fIprgbRndNumber\fR parameter. This is 0 if \fIfGenerateRndNumber\fR +is FALSE. +.SS prgbRndNumber +The \fIprgbRndNumber\fR parameter receives a pointer to the random number +data attributes. This is NULL if \fIfGenerateRndNumber\fR is FALSE. +.SS pulArchiveDataLength +The \fIpulArchiveDataLength\fR parameter receives the length in bytes of +the \fIprgbArchiveData\fR parameter. +.SS prgbArchiveData +The \fIprgbArchiveData\fR parameter receives a pointer to the archive data. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_CreateMaintenanceArchive\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_NOTIMPL +The function is not implemented. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_CreateMaintenanceArchive\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_KillMaintenanceFeature\fR(3), +\fBTspi_TPM_LoadMaintenancePubKey\fR(3), +\fBTspi_TPM_CheckMaintenancePubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_DAA_JoinCreateDaaPubKey.3 b/static/netbsd/man3/Tspi_TPM_DAA_JoinCreateDaaPubKey.3 new file mode 100644 index 00000000..42b4e673 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DAA_JoinCreateDaaPubKey.3 @@ -0,0 +1,112 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DAA_JoinCreateDaaPubKey" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DAA_JoinCreateDaaPubKey \- computes the credential request for the DAA Issuer +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_DAA_JoinCreateDaaPubKey(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HTPM " hTPM "," +.BI " UINT32 " authenticationChallengeLength "," +.BI " BYTE* " authenticationChallenge "," +.BI " UINT32 " nonceIssuerLength "," +.BI " BYTE* " nonceIssuer "," +.BI " UINT32 " attributesPlatformLength "," +.BI " BYTE** " attributesPlatform "," +.BI " TSS_DAA_JOIN_SESSION* " joinSession "," +.BI " TSS_DAA_CREDENTIAL_REQUEST* " credentialRequest +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_TPM_DAA_JoinCreateDaaPubKey\fR +is the second (between \fBTspi_TPM_DAA_JoinInit()\fR and \fBTspi_TPM_DAA_JoinStoreCredential()\fR) + out of 3 functions to execute in order to receive a DAA Credential. +It computes the credential request for the DAA Issuer, which also includes the Platforms's +DAA public key and the attributes that were chosen by the Platform, and which are not visible +to the DAA Issuer. The Platform can commit to the attribute values it has chosen. +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS hTPM +The \fIhTPM\fR parameter is the handle to the TPM object. +.SS authenticationChallengeLength +The \fIauthenticationChallengeLength\fR parameter is length of authenticationChallenge (256 bytes - DAA_SIZE_NE1). +.SS authenticationChallenge +The \fIauthenticationChallenge\fR parameter is the second nonce of the DAA Issuer that is encrypted by the endorsement public key. +It is used as a challenge to authenticate the underlying TPM. +.SS nonceIssuerLength +The \fInonceIssuerLength\fR parameter is the length of nonceIssuer (20 bytes). +.SS nonceIssuer +The \fInonceIssuer\fR parameter is the nonce of the DAA Issuer. +.SS attributesPlatformLength +The \fIattributesPlatformLength\fR parameter is length of attributesPlatform array, which is determined +by the DAA Issuer public key (). The length of a single attribute is ln/8. ln is defined as the size of +the RSA modulus (2048). +.SS attributesPlatform +The \fIattributesPlatform\fR parameter is an array of attributes to be encoded into the DAA Credential +not visible to the DAA Issuer. +.SS joinSession +The \fIjoinSession\fR parameter is a structure containing the DAA Join session information. +.SS credentialRequest +The \fIcredentialRequest\fR parameter is the credential request of the Platform, it contains the blinded +DAA public key of the platform on which the DAA Issuer will issue the credential the blinded attributes +chosen by the Platform. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DAA_JoinCreateDaaPubKey\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" +.PP +\fBTspi_TPM_DAA_JoinCreateDaaPubKey\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_DAA_JoinInit\fR(3) +\fBTspi_TPM_DAA_JoinStoreCredential\fR(3) + diff --git a/static/netbsd/man3/Tspi_TPM_DAA_JoinInit.3 b/static/netbsd/man3/Tspi_TPM_DAA_JoinInit.3 new file mode 100644 index 00000000..01423052 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DAA_JoinInit.3 @@ -0,0 +1,119 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DAA_JoinInit" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DAA_JoinInit \- start the DAA Join process +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSPICALL Tspi_TPM_DAA_JoinInit(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HTPM " hTPM "," +.BI " TSS_HKEY " issuer_pk "," +.BI " UINT32 " issuer_authentication_PKLength "," +.BI " TSS_HKEY* " issuer_authentication_PK "," +.BI " UINT32 " issuer_authentication_PK_signaturesLength "," +.BI " BYTE** " issuer_authentication_PK_signatures "," +.BI " UINT32* " capital_UprimeLength "," +.BI " BYTE** " capital_Uprime "," +.BI " TSS_DAA_IDENTITY_PROOF* " identity_proof "," +.BI " TSS_DAA_JOIN_SESSION* " join_session +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_TPM_DAA_JoinInit\fR +is the first out of 3 functions to execute in order to receive a DAA Credential. It +verifies the keys of the DAA Issuer and computes the TPM DAA public key. + +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS hTPM +The \fIhTPM\fR parameter is the handle to the TPM object. +.SS issuer_pk +The \fIissuer_pk\fR parameter is the of the DAA Issuer public key. +.SS issuer_authentication_PKLength +The \fIissuer_authentication_PKLength\fR parameter is the length of the array of \fIissuerAuthPKs\fR. +.SS issuer_authentication_PK +The \fIissuer_authentication_PK\fR parameter is an array of RSA public keys (key chain) of + the DAA Issuer used to authenticate the DAA Issuer public key. The size of the modulus must + be TPM_DAA_SIZE_issuerModulus (256). +.SS issuer_authentication_PK_signaturesLength +The \fIissuer_authentication_PK_signaturesLength\fR parameter is the length of the array of + issuerAuthPKSignatures. It is equal to issuerAuthPKsLength. The length of an element of the + array is TPM_DAA_SIZE_issuerModulus (256). +.SS issuer_authentication_PK_signatures +The \fIissuer_authentication_PK_signatures\fR parameter is the array of byte arrays representing + signatures on the modulus of the above key chain (issuerAuthPKs) in more details, the array has + the following content (S(K[1],K[0]),S(K[2],N[1]),..S(K[ k ],K[n-1]), S(TPM_DAA_ISSUER,K[ k ])), + where S(msg,privateKey) denotes the signature function with msg being signed by the privateKey. +.SS capital_UprimeLength +The \fIcapital_UprimeLength\fR parameter is the length of capitalUprime which is ln/8. ln is +defined as the size of the RSA modulus (2048). +.SS capital_Uprime +The \fIcapital_Uprime\fR parameter is U'. +.SS identityProof +The \fIidentityProof\fR parameter is a structure containing the endorsement, platform and conformance + credential. +.SS joinSession +The \fIjoinSession\fR parameter is a structure containing DAA Join session information. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DAA_JoinInit\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA or the TPM handler is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.TP +.SM TSS_E_DAA_ISSUER_KEY_ERROR + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_DAA_JoinInit\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_DAA_JoinCreateDaaPubKey\fR(3) +\fBTspi_TPM_DAA_JoinStoreCredential\fR(3) + diff --git a/static/netbsd/man3/Tspi_TPM_DAA_JoinStoreCredential.3 b/static/netbsd/man3/Tspi_TPM_DAA_JoinStoreCredential.3 new file mode 100644 index 00000000..1bbe8bd8 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DAA_JoinStoreCredential.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DAA_JoinStoreCredential" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DAA_JoinStoreCredential \- compute the final DAA Credential +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_DAA_JoinStoreCredential(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HTPM " hTPM "," +.BI " TSS_DAA_CRED_ISSUER " credIssuer "," +.BI " TSS_DAA_JOIN_SESSION " joinSession "," +.BI " TSS_HKEY* " hDaaCredential +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_TPM_DAA_JoinStoreCredential\fR +is the last out of 3 functions (after \fBTspi_TPM_DAA_JoinInit()\fR and \fBTspi_TPM_DAA_JoinCreateDaaPubKey()\fR) + to execute in order to receive a DAA Credential. It verifies the issued credential from the DAA Issuer +and computes the final DAA Credential. +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS hTPM +The \fIhTPM\fR parameter is the handle to the TPM object. +.SS credIssuer +The \fIcredIssuer\fR parameter is the DAA Credential issued by the DAA Issuer including proof of correctness. +.SS joinSession +The \fIjoinSession\fR parameter is the structure containing the DAA Join session information. +.SS hDaaCredential +The \fIhDaaCredential\fR parameter is the handle of the received DAA Credential. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DAA_JoinStoreCredential\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA or the TPM handler is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.SM TSS_E_DAA_CREDENTIAL_PROOF_ERROR +One of the verification of the issued credential failed +.SH "CONFORMING TO" +.PP +\fBTspi_TPM_DAA_JoinStoreCredential\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_DAA_JoinInit\fR(3) +\fBTspi_TPM_DAA_JoinCreateDaaPubKey\fR(3) diff --git a/static/netbsd/man3/Tspi_TPM_DAA_Sign.3 b/static/netbsd/man3/Tspi_TPM_DAA_Sign.3 new file mode 100644 index 00000000..da607fcc --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DAA_Sign.3 @@ -0,0 +1,109 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Anthony Bussani based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DAA_Sign" 3 "2006-09-04" "TSS 1.2" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DAA_Sign \- creates a DAA Signature that proofs ownership of the DAA Credential +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_DAA_Sign(" +.BI " TSS_HDAA " hDAA "," +.BI " TSS_HTPM " hTPM "," +.BI " TSS_HKEY " hDaaCredential "," +.BI " TSS_DAA_SELECTED_ATTRIB " revealAttributes "," +.BI " UINT32 " verifierBaseNameLength "," +.BI " BYTE* " verifierBaseName "," +.BI " UINT32 " verifierNonceLength "," +.BI " BYTE* " verifierNonce "," +.BI " TSS_DAA_SIGN_DATA " signData "," +.BI " TSS_DAA_SIGNATURE* " daaSignature +.BI ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\Tspi_TPM_DAA_Sign\fR +creates a DAA Signature that proofs ownership of the DAA Credential and includes a +signature on either a public AIK or a message. If anonymity revocation is enabled, the value Nv +is not provided in the clear anymore but encrypted under the public key of anonymity revocation +authority, a trusted third party (TTP). Thus the DAA Verifier cannot check for revocation or link +a transaction/signature to prior ones. Depending on how is chosen, the protocol either allows +implementing anonymity revocation (i.e., using the DAA Issuer's long-term base name as the DAA +Verifier's base name ), or having the TTP doing the linking of different signatures for the same +DAA Verifier (i.e., using the DAA Verifier's base name ). +.SH "PARAMETERS" +.PP +.SS hDAA +The \fIhDAA\fR parameter is used to specify the handle of the DAA object. +.SS hTPM +The \fIhTPM\fR parameter is the handle to the TPM object. +.SS hDaaCredential +The \fIhDaaCredential\fR parameter is the Handle of the DAA Credential. +.SS revealAttributes +The \fIrevealAttributes\fR parameter is the attributes which the credential owner wants to reveal +to the DAA Verifier. +.SS verifierBaseNameLength +The \fIverifierBaseNameLength\fR parameter is the Length of verifierBaseName. +.SS verifierBaseName +The \fIverifierBaseName\fR parameter is the base name chosen by the DAA Verifier. If it equals to null, +the platform chooses a random base name. +.SS verifierNonceLength +The \fIverifierNonceLength\fR parameter is the length of verifierNonceName (20 bytes). +.SS verifierNonce +The \fIverifierNonce\fR parameter is the nonce created by the DAA Verifier. +.SS signData +The \fIsignData\fR parameter is the handle of the received DAA Credential. +.SS daaSignature +The \fIdaaSignature\fR parameter is the DAA signature containing the proof of ownership of the DAA Credential, +as well as a signature on either an AIK or a message. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DAA_Sign\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the DAA or the TPM handler is not valid. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" +.PP +\fBTspi_TPM_DAA_Sign\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP diff --git a/static/netbsd/man3/Tspi_TPM_DirRead.3 b/static/netbsd/man3/Tspi_TPM_DirRead.3 new file mode 100644 index 00000000..c60a4541 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DirRead.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2006 International Business Machines Corporation +.\" Written by Kent Yoder based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DirRead" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DirRead \- Read a Data Integrity Register +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_DirRead(TSS_HTPM " hTPM ", UINT32 " ulDirIndex "," +.BI " UINT32* " pulDirDataLength ", BYTE** " prgbDirData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_DirRead\fR reads a data integrity register. DIRs are non-volatile (persistent +across reboots) memory areas maintained by the TPM. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. +.SS ulDirIndex +The \fIulDirIndex\fR parameter is the index of the DIR to read. To query the TPM for the +number of DIR registers it supports, use \fBTspi_TPM_GetCapability\fR(3). +.SS pulDirDataLength +The \fIpulDirDataLength\fR parameter receives the length in bytes of the \fIprgbDirData\fR parameter. +.SS prgbDirData +The \fIprgbDirData\fR parameter receives a pointer to memory containing the DIR data. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DirRead\fR returns TSS_SUCCESS on success, otherwise one of +the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_DirRead\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" +.PP +\fBTspi_TPM_GetCapability\fR(3), \fBTspi_TPM_DirWrite\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_DirWrite.3 b/static/netbsd/man3/Tspi_TPM_DirWrite.3 new file mode 100644 index 00000000..7b7e0efa --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_DirWrite.3 @@ -0,0 +1,91 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_DirWrite" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_DirWrite \- write to a Data Integrity Register +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_DirWrite(TSS_HTPM " hTPM ", UINT32 " ulDirIndex "," +.BI " UINT32 " ulDirDataLength ", BYTE* " rgbDirData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_DirWrite\fR writes a data integrity +register. You need to know the DIR index and data you wish to write +to the DIR prior to using this command. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. +.SS ulDirIndex +The \fIulDirIndex\fR parameter is the index of the DIR to write. To query the TPM for the +number of DIR registers it supports, use \fBTspi_TPM_GetCapability\fR(3). +.SS ulDirDataLength +The \fIulDirDataLength\fR parameter is the length in bytes of the \fIrgbDirData\fR parameter. +.SS rgbDirData +The \fIrgbDirData\fR parameter is a pointer to memory containing the +data to be written to the DIR. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_DirWrite\fR returns TSS_SUCCESS on success, otherwise one of +the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_DirWrite\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" +.PP +\fBTspi_TPM_GetCapability\fR(3), \fBTspi_TPM_DirRead\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_GetAuditDigest.3 b/static/netbsd/man3/Tspi_TPM_GetAuditDigest.3 new file mode 100644 index 00000000..dc7caaf3 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetAuditDigest.3 @@ -0,0 +1,87 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" Written by Tom Lendacky based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetAuditDigest" 3 "2007-06-27" "TSS 1.2" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_GetAuditDigest \- retrieve the audit digest. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetAuditDigest(TSS_HTPM " hTpm ", TSS_HKEY " hKey "," +.BI " TSS_BOOL " closeAudit ", UINT32* " pulAuditDigestSize "," +.BI " BYTE** " prgbAuditDigest ", TPM_COUNTER_VALUE* " pCounterValue "," +.BI " TSS_VALIDATION* " pValidationData ", UINT32* " ordSize "," +.BI " UINT32** " ordList ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetAuditDigest\fR is used to retrieve the audit digest. The audit digest may be signed or unsigned. If the audit digest is signed (hKey is non-NULL) then the current audit digest, the current audit counter and, optionally, the hash of the audited ordinal list and a signature are returned. If the audit digest is not signed (hKey is NULL) then the current audit digest, the current audit counter and the full list of audited ordinals is returned. +.SH "PARAMETERS" +.PP +.SS hTpm +Handle of the TPM object. +.PP +.SS hKey +Handle of the signature key object (the handle can be NULL). +.PP +.SS closeAudit +A flag indicating whether or not to close the current audit digest after it is signed. This parameter is ignored if \fIhKey\fR is NULL. +.PP +.SS pulAuditDigestSize +Pointer to the size of the returned audit digest. +.PP +.SS prgbAuditDigest +Pointer to a buffer that holds the returned audit digest. +.PP +.SS pCounterValue +Pointer to a TPM_COUNTER_VALUE structure that holds the returned audit counter. +.PP +.SS pValidationData +Pointer to a validation data structure. The validation data structure provides external information required to compute the signature. On input, the fields representing the ExternalData must contain an anti-replay nonce that will be used in the signing operation. On output, this structure provides a buffer containing the data used to compute the validation data and a buffer containing the validation data (a signature generated by signing the data using the key referenced by \fIhKey\fR). If this parameter is NULL then the TSS will perform the validation. This parameter is ignored if \fIhKey\fR is NULL. +.PP +.SS ordSize +Pointer to the number of ordinals in the returned audited ordinal list. This parameter is ignored if \fIhKey\fR is non-NULL. +.PP +.SS ordList +Pointer to a buffer that holds the returned audited ordinal list. This parameter is ignored if \fIhKey\fR is non-NULL. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetAuditDigest\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetAuditDigest\fR conforms to the Trusted Computing Group Software Specification Version 1.2 + + + diff --git a/static/netbsd/man3/Tspi_TPM_GetCapability.3 b/static/netbsd/man3/Tspi_TPM_GetCapability.3 new file mode 100644 index 00000000..c77145b7 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetCapability.3 @@ -0,0 +1,125 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetCapability" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_GetCapability \- get information on the capabilities of the TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetCapability(TSS_HTPM " hTPM ", TSS_FLAG " capArea "," +.BI " UINT32 " ulSubCapLength ", BYTE* " rgbSubCap ", " +.BI " UINT32* " pulRespDataLength ", BYTE** " prgbRespData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetCapability\fR +gets information on various capabilities of the TPM. This command can +be used to learn how many PCRs the TPM supports, etc. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS capArea +The \fIcapArea\fR parameter is the flag indicating the attribute to query. Possible values are: +.SS ulSubCapLength +The \fIulSubCapLength\fR parameter is the length in bytes of the +\fIrgbSubCap\fR parameter. +.SS rgbSubCap +The \fIrgbSubCap\fR parameter is the data indicating the attribute to query. Possible values are: +.SS pulRespDataLength +The \fIpulRespDataLength\fR parameter is the length in bytes of the +\fIprgbRespData\fR parameter. +.SS prgbRespData +The \fIprgbRespData\fR parameter receives a pointer to the actual data +of the specified attribute. + +.SH "NOTES" +.PP +The following Capability Areas and Sub-Capability Areas are supported by 1.1 TSS's: +.sp 2 +.BR TSS_TPMCAP_ORD " - query whether an ordinal is supported by the TPM. " + subCaps: TPM_ORD_* (see tcpa_literals.h) +.sp +.BR TSS_TPMCAP_FLAG " - query for the volatile and non-volatile flags inside the TPM. (Must be owner authorized). In this case, the 2 UINT32 values will be returned concatenated together in prgbRespData. " + subCaps: ignored. +.sp +.BR TSS_TPMCAP_ALG " - query whether an algorithm is supported by the TPM. " + subCaps: TSS_ALG_RSA + TSS_ALG_DES + TSS_ALG_3DES + TSS_ALG_SHA + TSS_ALG_HMAC + TSS_ALG_AES +.sp +.BR TSS_TPMCAP_PROPERTY " - query a property of the TPM. " + subCaps: TSS_TPMCAP_PROP_PCR + TSS_TPMCAP_PROP_DIR + TSS_TPMCAP_PROP_MANUFACTURER + TSS_TPMCAP_PROP_SLOTS +.sp +.BR TSS_TPMCAP_VERSION " - get the TSS_VERSION structure tha identifies the TPM. " + subCaps: ignored. + + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetCapability\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetCapability\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetCapabilitySigned\fR(3), \fBTspi_TPM_GetEvent\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_GetEvent.3 b/static/netbsd/man3/Tspi_TPM_GetEvent.3 new file mode 100644 index 00000000..5a5d77a4 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetEvent.3 @@ -0,0 +1,80 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetEvent" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_GetEvent\- get a PCR event for a given PCR index and event number. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetEvent(TSS_HTPM " hTPM ", UINT32 " ulPcrIndex "," +.BI " UINT32 " ulEventNumber ", TSS_PCR_EVENT* " pPcrEvent ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetEvent\fR provides a PCR event for a given PCR index and event number. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS ulPcrIndex +Index of the PCR to request. +.PP +.SS ulEventNumber +Index of the event to request. +.PP +.SS pPcrEvent +Receives the PCR event data. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetEvent\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fBhTPM\fR is not a valid handle to the TPM object. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetEvent\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetEvents\fR(3) \fBTspi_TPM_GetEventLog\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_GetEventLog.3 b/static/netbsd/man3/Tspi_TPM_GetEventLog.3 new file mode 100644 index 00000000..c6cfb842 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetEventLog.3 @@ -0,0 +1,78 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetEventLog" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_GetEventLog\- get the entire PCR event log. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetEventLog(TSS_HTPM " hTPM ", UINT32* " pulEventNumber "," +.BI " TSS_PCR_EVENT** " prgPcrEvents ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetEventLog\fR provides the whole event log that was used to create all of the PCRs. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS pulEventNumber +Receives number of returned event data structures in prgPcrEvents parameter. +.PP +.SS prgPcrEvents +Receives a pointer to an array of PCR event data. +If NULL, only the numberof elements is returned in pulEventNumber parameter. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetEventLog\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fBhTPM\fR is not a valid handle to the TPM object. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetEventLog\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetEvent\fR(3) \fBTspi_TPM_GetEvents\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_GetEvents.3 b/static/netbsd/man3/Tspi_TPM_GetEvents.3 new file mode 100644 index 00000000..83fb3686 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetEvents.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetEvents" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_GetEvents\- get a specific number of PCR events for a given index. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetEvents(TSS_HTPM " hTPM ", UINT32 " ulPcrIndex ", " +.BI " UINT32 " ulStartNumber ", UINT32* " pulEventNumber ", " +.BI " TSS_PCR_EVENT* " prgbPcrEvents ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetEvents\fR provides a specific number of PCR events for a given index. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS ulPcrIndex +Index of the PCR to request. +.PP +.SS ulStartNumber +Indext of the first event to request +.PP +.SS pulEventNumber +[IN] Number of elements to request. +[OUT] Receives number of returned event data structures in prgbPcrEvents parameter. +.PP +.SS prgbPcrEvents +Receives a pointer to an array of PCR event data. +If NULL, only the number of elements is returned in pulEventNumber parameter. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetEvents\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fBhTPM\fR is not a valid handle to the TPM object. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetEvents\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetEvent\fR(3) \fBTspi_TPM_GetEventLog\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_GetPubEndorsementKey.3 b/static/netbsd/man3/Tspi_TPM_GetPubEndorsementKey.3 new file mode 100644 index 00000000..16ded4d2 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetPubEndorsementKey.3 @@ -0,0 +1,101 @@ +.\" Copyright (C) 2004, 2005 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetPubEndorsementKey" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_GetPubEndorsementKey \- create a TSS key object from the TPM's public endorsement key +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetPubEndorsementKey(TSS_HTPM " hTPM ", TSS_BOOL " fOwnerAuthorized "," +.BI " TSS_VALIDATION* " pValidationData ", TSS_HKEY* " phEndorsementPubKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetPubEndorsementKey\fR +This function retrieves the public endorsement key (PubEK) from the TPM and creates a TSS +key object for it, whose handle is returned in \fIphEndorsementPubKey\fR. Due to +the fact that different TPM chips validate the PubEK in different ways, application +verification of the PubEK (using a non-NULL \fIpValidationData\fR is \fBbroken\fR. +Tspi_TPM_GetPubEndorsementKey should be called with a NULL \fIpValidationData\fR parameter +to allow the TSS to verify the PubEK itself. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS fOwnerAuthorized +If TRUE, the TPM owner secret must be provided to get the public endorsement key. +If FALSE, no TPM owner secret must be provided to get the public endorsement key. +.SS pValidationData +If non-NULL, the application should set the pValidationData->rgbExternalData parameter +to 20 bytes of random data before calling Tspi_TPM_GetPubEndorsementKey. On successful +completion of the command, the structure will provide buffers containing the validation +data and the buffer the validation data was computed from. +.SS phEndorsementPubKey +Receives a handle to a key object representing the TPM's public endorsement key. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetPubEndorsementKey\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TPM_E_DISABLED_CMD +Reading of PubEK from TPM has been disabled. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetPubEndorsementKey\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Key_GetPubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_GetRandom.3 b/static/netbsd/man3/Tspi_TPM_GetRandom.3 new file mode 100644 index 00000000..c00089d5 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetRandom.3 @@ -0,0 +1,88 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetRandom" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_GetRandom \- generate a random number on the TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetRandom(TSS_HTPM " hTPM ", UINT32 " size ", BYTE** " random ");" +.fi +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetRandom\fR gets a good random number +for the purpose of generating symmetric keys, nonces, or +seeding a random number generator. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. The command to get the TPM to test itself will be sent here. +.SS size +The \fIsize\fR parameter is the number of random bytes requested. +.SS random +The \fIrandom\fR parameter is a pointer to memory containing the random +data. This is where the generated number goes. Because this internally +allocates memory, Tspi_Context_FreeMemory should also be used. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetRandom\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetRandom\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_FreeMemory\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_GetStatus.3 b/static/netbsd/man3/Tspi_TPM_GetStatus.3 new file mode 100644 index 00000000..f1cd1650 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetStatus.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetStatus" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_GetStatus \- query the TPM's status +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetStatus(TSS_HTPM " hTPM ", TSS_FLAG " statusFlag ", BOOL* " pfTpmState ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetStatus\fR queries the status of the +TPM, returning a specific status based on the flags specified. +\fBThis command is not currently implemented\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS statusFlag +The \fIstatusFlag\fR parameter is the status to be retrieved. +.SS fTpmState +The \fIpfTpmState\fR parameter is a pointer to the value of the status queried. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetStatus\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetStatus\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_SetStatus\fR(3), \fBTspi_TPM_GetCapability\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_GetTestResult.3 b/static/netbsd/man3/Tspi_TPM_GetTestResult.3 new file mode 100644 index 00000000..d2594092 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_GetTestResult.3 @@ -0,0 +1,76 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_GetTestResult" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_GetTestResult\- get manufacturer specific information regarding the results of a self test. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_GetTestResult(TSS_HTPM " hTPM ", UINT32* " pulTestResultLength ", BYTE** " prgbTestResult ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_GetTestResult\fR is provided by a manufacturer of a TPM to provide manufacturer specific self test results. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object +.PP +.SS pulTestREsultLength +Receives the length (in bytes) of the prgbTestResult parameter +.PP +.SS prgbTestResult +Pointer to the memory block containing the TPM manufacturer specific information. +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetTestResult\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fBhTPM\fR is not a valid handle to the TPM object. +.TP +.SM TSS_E_INTERNAL_ERROR +An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_GetTestResult\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_SelfTestFull\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_KillMaintenanceFeature.3 b/static/netbsd/man3/Tspi_TPM_KillMaintenanceFeature.3 new file mode 100644 index 00000000..7a2a0861 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_KillMaintenanceFeature.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_KillMaintenanceFeature" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_KillMaintenanceFeature \- Disables the ability to create a maintenance archive +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_KillMaintenanceFeature(TSS_HTPM " hTPM ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_KillMaintenanceFeature\fR disables the +functionality of creating a maintenance archive. \fBThis feature is +not yet implemented\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_KillMaintenanceFeature\fR returns TSS_SUCCESS on success, +otherwise one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_NOTIMPL +The function is not implemented. + + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_KillMaintenanceFeature\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_CreateMaintenanceArchive\fR(3), +\fBTspi_TPM_LoadMaintenancePubKey\fR(3), +\fBTspi_TPM_CheckMaintenancePubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_LoadMaintenancePubKey.3 b/static/netbsd/man3/Tspi_TPM_LoadMaintenancePubKey.3 new file mode 100644 index 00000000..37ced393 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_LoadMaintenancePubKey.3 @@ -0,0 +1,102 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_LoadMaintenancePubKey" 3 "2004-05-26" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_LoadMaintenancePubKey\- load the public maintenance key into the TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_LoadMaintenancePubKey(TSS_HTPM " hTPM ", TSS_HKEY " hMaintenanceKey "," +.BI " TSS_VALIDATION* " pValidationData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_LoadMaintenancePubKey\fR +loads the public maintenance key into the TPM. The +maintenance key can only be loaded once; any subsequent calls to +this function will fail. The key information for loading the +maintenance public key must be set in the key object by +Tspi_SetAttribData before this method is called. If +\fIpValidationData\fR is NULL, the TSS service provider proofs the +digest got internally from the TPM. Otherwise, the caller has to +proof the digest by its own. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object +.PP +.SS hMaintenanceKey +Handle of the maintenance key object +.PP +.SS pValidationData +Validation data structure. +[IN] Provide externalData information required to compute the signature. +[OUT] On successful completion of the ocmmand, the structure provides a +buffer containing the validation data and a buffer containing the data +the validation data was computed from. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_LoadMaintenancePubKey\fR returns TSS_SUCCESS on success, +otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR or \fIhMaintenanceKey\fR is not a valid handle. +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. +.TP +.SM TSS_E_BAD_PARAMETER +One or more of the parameters is incorrect. +.TP +.SM TSS_E_NOTIMPL +The command is not implemented. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_LoadMaintenancePubKey\fR conforms to the Trusted Computing +Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_CheckMaintenancePubKey\fR(3), +\fBTspi_TPM_KillMaintenanceFeature\fR(3), +\fBTspi_TPM_CreateMaintenanceArchive\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_OwnerGetSRKPubKey.3 b/static/netbsd/man3/Tspi_TPM_OwnerGetSRKPubKey.3 new file mode 100644 index 00000000..56fa6491 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_OwnerGetSRKPubKey.3 @@ -0,0 +1,87 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" Written by Loulwa Salem based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_OwnerGetSRKPubKey" 3 "2007-07-19" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_OwnerGetSRKPubKey \- get public key of the SRK +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.sp +.B "#include " +.B "" +.BI "TSS_RESULT Tspi_TPM_OwnerGetSRKPubKey(TSS_HTPM " hTPM "," +.BI " UINT32* " pulPubKeyLength "," +.BI " BYTE** " prgbPubKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_OwnerGetSRKPubKey\fR +returns the public key of the key object using owner authorization. +This can only be used on 1.2 TPMs, and only to return the public key of the SRK. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS pulPubKeyLength +The \fIpulPubKeyLength\fR parameter is the length (in bytes) of the prgbPubKey parameter. +.SS prgbPubKey +The \fIprgbPubKey\fR parameter is the pointer to the memory block containing the public key blob retrieved for the key object referenced by hKey. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_OwnerGetSRKPubKey\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_TPM_UNSUPPORTED +The TPM is not version 1.2 or later - (Note: still unimplemented) + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_OwnerGetSRKPubKey\fR conforms to the Trusted Computing Group +Software Specification version 1.2 + +.SH "SEE ALSO" + +.PP +\fBTspi_Context_FreeMemory\fR(3), \fBTspi_Key_GetPubKey\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_PcrExtend.3 b/static/netbsd/man3/Tspi_TPM_PcrExtend.3 new file mode 100644 index 00000000..dbd74937 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_PcrExtend.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_PcrExtend" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_PcrExtend \- extend a PCR register and optionally write the PCR event log. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_PcrExtend(TSS_HTPM " hTPM ", UINT32 " ulPcrIndex "," +.BI " UINT32 " ulPcrDataLength ", BYTE* " pbPcrData "," +.BI " TSS_PCR_EVENT* " pPcrEvent "," +.BI " UINT32* " pulPcrValueLength ", BYTE** " prgbPcrValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_PcrExtend\fR extends a PCR register and writes the PCR event log if +one is supplied by the user. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. The command to get the TPM to test itself will be sent here. +.SS ulPcrIndex +The \fIulPcrIndex\fR parameter is the index of the PCR to extend. +.SS ulPcrDataLength +The \fIulPcrDataLength\fR parameter is the length in bytes of the \fIpbPcrData\fR parameter. +.SS pbPcrData +The \fIpbPcrData\fR parameter is a pointer to data which will be used in the extend operation. +.SS pPcrEvent +The \fIpPcrEvent\fR parameter is the TSS_PCR_EVENT structure to be passed to the TCS +to record the extend event. If \fIpPcrEvent\fR is not NULL, the application should +fill out the members of the structure that it cares about. +.SS pulPcrValueLength +The \fIpulPcrValueLength\fR parameter receives the length in bytes of the \fIprgbPcrValue\fR parameter. +.SS prgbPcrValue +The \fIprgbPcrValue\fR receives a pointer to the memory block containing the PCR data after the +extend operation. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_PcrExtend\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_PcrExtend\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_PcrRead\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_PcrRead.3 b/static/netbsd/man3/Tspi_TPM_PcrRead.3 new file mode 100644 index 00000000..0771a99d --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_PcrRead.3 @@ -0,0 +1,91 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_PcrRead" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_PcrRead \- read the value in a PCR register +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_PcrRead(TSS_HTPM " hTPM ", UINT32 " ulPcrIndex "," +.BI " UINT32* " pulPcrValueLength ", BYTE** " prgbPcrValue ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_PcrRead\fR reads a PCR register to find +the current values. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. The command to get the TPM to test itself will be sent here. +.SS ulPcrIndex +The \fIulPcrIndex\fR parameter is the index of the PCR to read. +.SS pulPcrValueLength +The \fIpulPcrValueLength\fR parameter receives the length in bytes +of the \fIprgbPcrValue\fR parameter. +.SS prgbPcrValue +The \fIprgbPcrValue\fR parameter receives a pointer to the memory +block containing the PCR data. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_PcrRead\fR returns TSS_SUCCESS on success, otherwise one +of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_PcrRead\fR conforms to the Trusted Computing Group Software +Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_PcrExtend\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_Quote.3 b/static/netbsd/man3/Tspi_TPM_Quote.3 new file mode 100644 index 00000000..6ce85b0e --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_Quote.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Kathy Robertson based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_Quote" 3 "2004-05-26" "TSS 1.1" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_Quote \- retreive a signed set of PCR values. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_Quote(TSS_HTPM " hTPM ", TSS_HKEY " hIdentKey "," +.BI " TSS_HPCRS " hPcrComposite ", TSS_VALIDATION* " pValidationData ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_Quote\fR destroys a context by passing in the handle to that context. +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS hIdentKey +Handle of the signature key object. +.PP +.SS hPcrComposite +Handle of the PCR composite object +.PP +.SS pValidationData +Validation data structure +[IN] Provide externalData information required to compute the signature. +[OUT] On successful completion of the command, the structure provides a buffer containing the validation data and a buffer containing the data the validation data was computed form. +.PP + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_Quote\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhTPM\fR, \fIhIdentKey\fR or \fIhPcrComposite\fR is not a valid handle. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_Quote\fR conforms to the Trusted Computing Group Software Specification version 1.1 Golden +.SH "SEE ALSO" + +.PP +\fB(none)\fR. + + + diff --git a/static/netbsd/man3/Tspi_TPM_Quote2.3 b/static/netbsd/man3/Tspi_TPM_Quote2.3 new file mode 100644 index 00000000..30cb1c02 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_Quote2.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2007 International Business Machines Corporation +.\" Written by Ramon Brandão based on the Trusted Computing Group Software Stack Specification Version 1.2 +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_Quote2" 3 "2007-04-03" "TSS 1.2" "TCG Software Stack Developer's Reference" +.SH NAME +Tspi_TPM_Quote2 \- retreive a signed set of PCR values with a more complete view than Tspi_TPM_Quote. +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_Quote2(TSS_HTPM " hTPM ", TSS_HKEY " hIdentKey "," +.BI " TSS_BOOL " fAddVersion ", TSS_HPCRS " hPcrComposite "," +.BI " TSS_VALIDATION* " pValidationData ", UINT32* " versionInfoSize "," +.BI " BYTE** " versionInfo ");" +.fi +.sp +.ad +.hy +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_Quote2\fR quotes a TCG system, providing the requestor +with a more complete view of the current platform configuration, +than \fBTspi_TPM_Quote\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +Handle of the TPM object. +.PP +.SS hIdentKey +Handle of the signature key object. +.PP +.SS fAddVersion +If TRUE, the TPM version is added to the output. If FALSE, the TPM version +isn't added to the output. +.PP +.SS hPcrComposite +Handle of the PCR composite object, which contains the PCRs to be quoted. +.PP +.SS pValidationData +Validation data structure +[IN] Provide externalData information required to compute the signature. +[OUT] On successful completion of the command, the structure provides a buffer containing the validation data and a buffer containing the data the validation data was computed form. +.PP +.SS versionInfoSize +The size of the bytestream returned by versionInfo. If the \fIfAddVersion\fR is False +this is zero. +.PP +.SS versionInfo +The version information returned as a byte stream reflecting the data in +TSS_CAP_VERSION_INFO if the fAddVersion is TRUE. Else it's NULL. +.PP + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_Quote\fR returns TSS_SUCCESS on success, otherwise one of the following values are returned: +.TP +.SM TSS_E_INVALID_HANDLE - \fIhTPM\fR, \fIhIdentKey\fR or \fIhPcrComposite\fR is not a valid handle. +.TP +.SM TSS_E_BAD_PARAMETER +.TP +.SM TSS_E_INTERNAL_ERROR - An error occurred internal to the TSS. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_Quote2\fR conforms to the Trusted Computing Group Software Specification version 1.2 +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_Quote\fR(3). + + + diff --git a/static/netbsd/man3/Tspi_TPM_SelfTestFull.3 b/static/netbsd/man3/Tspi_TPM_SelfTestFull.3 new file mode 100644 index 00000000..3b00140e --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_SelfTestFull.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_SelfTestFull" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_SelfTestFull \- perform a self-test of each internal TPM function +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_SelfTestFull(TSS_HTPM " hTPM ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_SelfTestFull\fR +assures that the TPM is functioning as designed. For FIPS certification, +crypto modules are required to test themselves before they are used, and +this command is used to fulfill that requirement. This command can also be +used to check the TPM whenever such a check is desired. \fBThis command is not +currently implemented\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object on +which the self-tests will be run. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_GetStatus\fR returns TSS_SUCCESS on success, otherwise one of +the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_SelfTestFull\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_CertifySelfTest\fR(3), \fBTspi_TPM_GetTestResults\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_SetStatus.3 b/static/netbsd/man3/Tspi_TPM_SetStatus.3 new file mode 100644 index 00000000..22ca6b77 --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_SetStatus.3 @@ -0,0 +1,90 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_SetStatus" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_SetStatus \- modify the TPM's status +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_SetStatus(TSS_HTPM " hTPM ", TSS_FLAG " statusFlag "," +.BI " TSS_BOOL " fTpmState ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_SetStatus\fR alters the status of the +TPM. Depending on the chosen \fIstatusFlag\fR, \fIfTpmState\fR may +or may not be ignored. This command requires that the TPM be on and +the handle to the TPM available. \fBThis command is not currently +implemented\fR. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS statusFlag +The \fIstatusFlag\fR parameter is what the TPM status should be set to. +.SS fTpmState +The \fIfTpmState\fR parameter is the status value to set. For some states, +this flag is ignored. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_SetStatus\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_SetStatus\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetStatus\fR(3), \fBTspi_TPM_GetCapability\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_StirRandom.3 b/static/netbsd/man3/Tspi_TPM_StirRandom.3 new file mode 100644 index 00000000..e102391f --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_StirRandom.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2004 International Business Machines Corporation +.\" Written by Megan Schneider based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_StirRandom" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_StirRandom \- add entropy to the TPM random number generator +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_StirRandom(TSS_HTPM " hTPM ", UINT32 " ulEntropyDataLength ", BYTE* " rgbEntropyData ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_StirRandom\fR adds entropy to the TPM +random number generator for the purpose of generating better random +numbers. The \fIentropy\fR variable should assigned an appropriately +seeded random number before this function is called. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM +object. The command to get the TPM to test itself will be sent here. +.SS ulEntropyDataLength +The \fIulEntropyDataLength\fR parameter is the length in bytes of +the \fIrgbEntropyData\fR parameter. +.SS rgbEntropyData +The \fIrgbEntropyData\fR parameter is a pointer to the entropy data. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_StirRandom\fR returns TSS_SUCCESS on success, otherwise +one of the following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +\fIhTPM\fR is not a valid handle. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.TP +.SM TSS_E_BAD_PARAMETER +One or more parameters is bad. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_StirRandom\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_GetRandom\fR(3). + diff --git a/static/netbsd/man3/Tspi_TPM_TakeOwnership.3 b/static/netbsd/man3/Tspi_TPM_TakeOwnership.3 new file mode 100644 index 00000000..811e20ac --- /dev/null +++ b/static/netbsd/man3/Tspi_TPM_TakeOwnership.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2005 International Business Machines Corporation +.\" Written by Kent Yoder based on the Trusted Computing Group Software Stack Specification Version 1.1 Golden +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "Tspi_TPM_TakeOwnership" 3 "2004-05-25" "TSS 1.1" +.ce 1 +TCG Software Stack Developer's Reference +.SH NAME +Tspi_TPM_TakeOwnership \- take ownership of a TPM +.SH "SYNOPSIS" +.ad l +.hy 0 +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "TSS_RESULT Tspi_TPM_TakeOwnership(TSS_HTPM " hTPM ", TSS_HKEY " hKeySRK "," +.BI " TSS_HKEY " hEndorsementPubKey ");" +.fi +.sp +.ad +.hy + +.SH "DESCRIPTION" +.PP +\fBTspi_TPM_TakeOwnership\fR +takes ownership of a TPM. Taking ownership is the process of inserting a shared secret into the TPM. The owner of the TPM (anyone who knows the shared secret) has the right to perform special operations. + +.SH "PARAMETERS" +.PP +.SS hTPM +The \fIhTPM\fR parameter is used to specify the handle of the TPM object. +.SS hKeySRK +The \fIhKeySRK\fR parameter is the handle to the object representing the TPM's Storage Root Key. +.SS hEndorsementPubKey +The \fIhEndorsementPubKey\fR parameter is the handle to the object representing the TPM's endorsement public key. This key is required for encrypting the secret of the SRK and the TPM owner secret. If NULL, the TSP internally queries the TPM for that endorsement public key. + +.SH "RETURN CODES" +.PP +\fBTspi_TPM_TakeOwnership\fR returns TSS_SUCCESS on success, otherwise one of the +following values is returned: +.TP +.SM TSS_E_INVALID_HANDLE +Either the TPM or one of the key handles is not valid. + +.TP +.SM TSS_E_INTERNAL_ERROR +An internal SW error has been detected. + +.SH "CONFORMING TO" + +.PP +\fBTspi_TPM_TakeOwnership\fR conforms to the Trusted Computing Group +Software Specification version 1.1 Golden + +.SH "SEE ALSO" + +.PP +\fBTspi_TPM_ClearOwner\fR(3) +.PP + diff --git a/static/netbsd/man3/UI_STRING.3 b/static/netbsd/man3/UI_STRING.3 new file mode 100644 index 00000000..c6524cd2 --- /dev/null +++ b/static/netbsd/man3/UI_STRING.3 @@ -0,0 +1,206 @@ +.\" $NetBSD: UI_STRING.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "UI_STRING 3" +.TH UI_STRING 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +UI_STRING, UI_string_types, UI_get_string_type, +UI_get_input_flags, UI_get0_output_string, +UI_get0_action_string, UI_get0_result_string, UI_get_result_string_length, +UI_get0_test_string, UI_get_result_minsize, +UI_get_result_maxsize, UI_set_result, UI_set_result_ex +\&\- User interface string parsing +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ui_string_st UI_STRING; +\& +\& enum UI_string_types { +\& UIT_NONE = 0, +\& UIT_PROMPT, /* Prompt for a string */ +\& UIT_VERIFY, /* Prompt for a string and verify */ +\& UIT_BOOLEAN, /* Prompt for a yes/no response */ +\& UIT_INFO, /* Send info to the user */ +\& UIT_ERROR /* Send an error message to the user */ +\& }; +\& +\& enum UI_string_types UI_get_string_type(UI_STRING *uis); +\& int UI_get_input_flags(UI_STRING *uis); +\& const char *UI_get0_output_string(UI_STRING *uis); +\& const char *UI_get0_action_string(UI_STRING *uis); +\& const char *UI_get0_result_string(UI_STRING *uis); +\& int UI_get_result_string_length(UI_STRING *uis); +\& const char *UI_get0_test_string(UI_STRING *uis); +\& int UI_get_result_minsize(UI_STRING *uis); +\& int UI_get_result_maxsize(UI_STRING *uis); +\& int UI_set_result(UI *ui, UI_STRING *uis, const char *result); +\& int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBUI_STRING\fR gets created internally and added to a \fBUI\fR whenever +one of the functions \fBUI_add_input_string()\fR, \fBUI_dup_input_string()\fR, +\&\fBUI_add_verify_string()\fR, \fBUI_dup_verify_string()\fR, +\&\fBUI_add_input_boolean()\fR, \fBUI_dup_input_boolean()\fR, \fBUI_add_info_string()\fR, +\&\fBUI_dup_info_string()\fR, \fBUI_add_error_string()\fR or \fBUI_dup_error_string()\fR +is called. +For a \fBUI_METHOD\fR user, there\*(Aqs no need to know more. +For a \fBUI_METHOD\fR creator, it is of interest to fetch text from these +\&\fBUI_STRING\fR objects as well as adding results to some of them. +.PP +\&\fBUI_get_string_type()\fR is used to retrieve the type of the given +\&\fBUI_STRING\fR. +.PP +\&\fBUI_get_input_flags()\fR is used to retrieve the flags associated with the +given \fBUI_STRING\fR. +.PP +\&\fBUI_get0_output_string()\fR is used to retrieve the actual string to +output (prompt, info, error, ...). +.PP +\&\fBUI_get0_action_string()\fR is used to retrieve the action description +associated with a \fBUIT_BOOLEAN\fR type \fBUI_STRING\fR. +For all other \fBUI_STRING\fR types, NULL is returned. +See \fBUI_add_input_boolean\fR\|(3). +.PP +\&\fBUI_get0_result_string()\fR and \fBUI_get_result_string_length()\fR are used to +retrieve the result of a prompt and its length. +This is only useful for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings. +For all other \fBUI_STRING\fR types, \fBUI_get0_result_string()\fR returns NULL +and \fBUI_get_result_string_length()\fR returns \-1. +.PP +\&\fBUI_get0_test_string()\fR is used to retrieve the string to compare the +prompt result with. +This is only useful for \fBUIT_VERIFY\fR type strings. +For all other \fBUI_STRING\fR types, NULL is returned. +.PP +\&\fBUI_get_result_minsize()\fR and \fBUI_get_result_maxsize()\fR are used to +retrieve the minimum and maximum required size of the result. +This is only useful for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings. +For all other \fBUI_STRING\fR types, \-1 is returned. +.PP +\&\fBUI_set_result_ex()\fR is used to set the result value of a prompt and its length. +For \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings, this sets the +result retrievable with \fBUI_get0_result_string()\fR by copying the +contents of \fBresult\fR if its length fits the minimum and maximum size +requirements. +For \fBUIT_BOOLEAN\fR type UI strings, this sets the first character of +the result retrievable with \fBUI_get0_result_string()\fR to the first +\&\fBok_char\fR given with \fBUI_add_input_boolean()\fR or \fBUI_dup_input_boolean()\fR +if the \fBresult\fR matched any of them, or the first of the +\&\fBcancel_chars\fR if the \fBresult\fR matched any of them, otherwise it\*(Aqs +set to the NUL char \f(CW\*(C`\e0\*(C'\fR. +See \fBUI_add_input_boolean\fR\|(3) for more information on \fBok_chars\fR and +\&\fBcancel_chars\fR. +.PP +\&\fBUI_set_result()\fR does the same thing as \fBUI_set_result_ex()\fR, but calculates +its length internally. +It expects the string to be terminated with a NUL byte, and is therefore +only useful with normal C strings. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBUI_get_string_type()\fR returns the UI string type. +.PP +\&\fBUI_get_input_flags()\fR returns the UI string flags. +.PP +\&\fBUI_get0_output_string()\fR returns the UI string output string. +.PP +\&\fBUI_get0_action_string()\fR returns the UI string action description +string for \fBUIT_BOOLEAN\fR type UI strings, NULL for any other type. +.PP +\&\fBUI_get0_result_string()\fR returns the UI string result buffer for +\&\fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings, NULL for any other +type. +.PP +\&\fBUI_get_result_string_length()\fR returns the UI string result buffer\*(Aqs +content length for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings, +\&\-1 for any other type. +.PP +\&\fBUI_get0_test_string()\fR returns the UI string action description +string for \fBUIT_VERIFY\fR type UI strings, NULL for any other type. +.PP +\&\fBUI_get_result_minsize()\fR returns the minimum allowed result size for +the UI string for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings, +\&\-1 for any other type. +.PP +\&\fBUI_get_result_maxsize()\fR returns the minimum allowed result size for +the UI string for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings, +\&\-1 for any other type. +.PP +\&\fBUI_set_result()\fR returns 0 on success or when the UI string is of any +type other than \fBUIT_PROMPT\fR, \fBUIT_VERIFY\fR or \fBUIT_BOOLEAN\fR, \-1 on +error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBUI\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/UI_UTIL_read_pw.3 b/static/netbsd/man3/UI_UTIL_read_pw.3 new file mode 100644 index 00000000..79966a0a --- /dev/null +++ b/static/netbsd/man3/UI_UTIL_read_pw.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: UI_UTIL_read_pw.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "UI_UTIL_read_pw 3" +.TH UI_UTIL_read_pw 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +UI_UTIL_read_pw_string, UI_UTIL_read_pw, +UI_UTIL_wrap_read_pem_callback \- user interface utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int UI_UTIL_read_pw_string(char *buf, int length, const char *prompt, +\& int verify); +\& int UI_UTIL_read_pw(char *buf, char *buff, int size, const char *prompt, +\& int verify); +\& UI_METHOD *UI_UTIL_wrap_read_pem_callback(pem_password_cb *cb, int rwflag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBUI_UTIL_read_pw_string()\fR asks for a passphrase, using \fBprompt\fR as a +prompt, and stores it in \fBbuf\fR. +The maximum allowed size is given with \fBlength\fR, including the +terminating NUL byte. +If \fBverify\fR is nonzero, the password will be verified as well. +.PP +\&\fBUI_UTIL_read_pw()\fR does the same as \fBUI_UTIL_read_pw_string()\fR, the +difference is that you can give it an external buffer \fBbuff\fR for the +verification passphrase. +.PP +\&\fBUI_UTIL_wrap_read_pem_callback()\fR can be used to create a temporary +\&\fBUI_METHOD\fR that wraps a given PEM password callback \fBcb\fR. +\&\fBrwflag\fR is used to specify if this method will be used for +passphrase entry without (0) or with (1) verification. +When not used any more, the returned method should be freed with +\&\fBUI_destroy_method()\fR. +.SH NOTES +.IX Header "NOTES" +\&\fBUI_UTIL_read_pw_string()\fR and \fBUI_UTIL_read_pw()\fR use default +\&\fBUI_METHOD\fR. +See \fBUI_get_default_method\fR\|(3) and friends for more information. +.PP +The result from the \fBUI_METHOD\fR created by +\&\fBUI_UTIL_wrap_read_pem_callback()\fR will generate password strings in the +encoding that the given password callback generates. +The default password prompting functions (apart from +\&\fBUI_UTIL_read_pw_string()\fR and \fBUI_UTIL_read_pw()\fR, there is +\&\fBPEM_def_callback()\fR, \fBEVP_read_pw_string()\fR and \fBEVP_read_pw_string_min()\fR) +all use the default \fBUI_METHOD\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBUI_UTIL_read_pw_string()\fR and \fBUI_UTIL_read_pw()\fR return 0 on success or a negative +value on error. +.PP +\&\fBUI_UTIL_wrap_read_pem_callback()\fR returns a valid \fBUI_METHOD\fR structure or NULL +if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBUI_get_default_method\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/UI_create_method.3 b/static/netbsd/man3/UI_create_method.3 new file mode 100644 index 00000000..d1d4d0f0 --- /dev/null +++ b/static/netbsd/man3/UI_create_method.3 @@ -0,0 +1,255 @@ +.\" $NetBSD: UI_create_method.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "UI_create_method 3" +.TH UI_create_method 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +UI_METHOD, +UI_create_method, UI_destroy_method, UI_method_set_opener, +UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, +UI_method_set_closer, UI_method_set_data_duplicator, +UI_method_set_prompt_constructor, UI_method_set_ex_data, +UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher, +UI_method_get_reader, UI_method_get_closer, +UI_method_get_data_duplicator, UI_method_get_data_destructor, +UI_method_get_prompt_constructor, UI_method_get_ex_data \- user +interface method creation and destruction +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ui_method_st UI_METHOD; +\& +\& UI_METHOD *UI_create_method(const char *name); +\& void UI_destroy_method(UI_METHOD *ui_method); +\& int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui)); +\& int UI_method_set_writer(UI_METHOD *method, +\& int (*writer) (UI *ui, UI_STRING *uis)); +\& int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui)); +\& int UI_method_set_reader(UI_METHOD *method, +\& int (*reader) (UI *ui, UI_STRING *uis)); +\& int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui)); +\& int UI_method_set_data_duplicator(UI_METHOD *method, +\& void *(*duplicator) (UI *ui, void *ui_data), +\& void (*destructor)(UI *ui, void *ui_data)); +\& int UI_method_set_prompt_constructor(UI_METHOD *method, +\& char *(*prompt_constructor) (UI *ui, +\& const char +\& *object_desc, +\& const char +\& *object_name)); +\& int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data); +\& int (*UI_method_get_opener(const UI_METHOD *method)) (UI *); +\& int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *); +\& int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *); +\& int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *); +\& int (*UI_method_get_closer(const UI_METHOD *method)) (UI *); +\& char *(*UI_method_get_prompt_constructor(const UI_METHOD *method)) +\& (UI *, const char *, const char *); +\& void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *); +\& void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *); +\& const void *UI_method_get_ex_data(const UI_METHOD *method, int idx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A method contains a few functions that implement the low\-level of the +User Interface. +These functions are: +.IP "an opener" 4 +.IX Item "an opener" +This function takes a reference to a UI and starts a session, for +example by opening a channel to a tty, or by creating a dialog box. +.IP "a writer" 4 +.IX Item "a writer" +This function takes a reference to a UI and a UI String, and writes +the string where appropriate, maybe to the tty, maybe added as a field +label in a dialog box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. +.IP "a flusher" 4 +.IX Item "a flusher" +This function takes a reference to a UI, and flushes everything that +has been output so far. +For example, if the method builds up a dialog box, this can be used to +actually display it and accepting input ended with a pressed button. +.IP "a reader" 4 +.IX Item "a reader" +This function takes a reference to a UI and a UI string and reads off +the given prompt, maybe from the tty, maybe from a field in a dialog +box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. +.IP "a closer" 4 +.IX Item "a closer" +This function takes a reference to a UI, and closes the session, maybe +by closing the channel to the tty, maybe by destroying a dialog box. +.PP +All of these functions are expected to return 0 on error, 1 on +success, or \-1 on out\-off\-band events, for example if some prompting +has been cancelled (by pressing Ctrl\-C, for example). +Only the flusher or the reader are expected to return \-1. +If returned by another of the functions, it\*(Aqs treated as if 0 was +returned. +.PP +Regarding the writer and the reader, don\*(Aqt assume the former should +only write and don\*(Aqt assume the latter should only read. +This depends on the needs of the method. +.PP +For example, a typical tty reader wouldn\*(Aqt write the prompts in the +write, but would rather do so in the reader, because of the sequential +nature of prompting on a tty. +This is how the \fBUI_OpenSSL()\fR method does it. +.PP +In contrast, a method that builds up a dialog box would add all prompt +text in the writer, have all input read in the flusher and store the +results in some temporary buffer, and finally have the reader just +fetch those results. +.PP +The central function that uses these method functions is \fBUI_process()\fR, +and it does it in five steps: +.IP 1. 4 +Open the session using the opener function if that one\*(Aqs defined. +If an error occurs, jump to 5. +.IP 2. 4 +For every UI String associated with the UI, call the writer function +if that one\*(Aqs defined. +If an error occurs, jump to 5. +.IP 3. 4 +Flush everything using the flusher function if that one\*(Aqs defined. +If an error occurs, jump to 5. +.IP 4. 4 +For every UI String associated with the UI, call the reader function +if that one\*(Aqs defined. +If an error occurs, jump to 5. +.IP 5. 4 +Close the session using the closer function if that one\*(Aqs defined. +.PP +\&\fBUI_create_method()\fR creates a new UI method with a given \fBname\fR. +.PP +\&\fBUI_destroy_method()\fR destroys the given UI method \fBui_method\fR. +.PP +\&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR, +\&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR and +\&\fBUI_method_set_closer()\fR set the five main method function to the given +function pointer. +.PP +\&\fBUI_method_set_data_duplicator()\fR sets the user data duplicator and destructor. +See \fBUI_dup_user_data\fR\|(3). +.PP +\&\fBUI_method_set_prompt_constructor()\fR sets the prompt constructor. +See \fBUI_construct_prompt\fR\|(3). +.PP +\&\fBUI_method_set_ex_data()\fR sets application specific data with a given +EX_DATA index. +See \fBCRYPTO_get_ex_new_index\fR\|(3) for general information on how to +get that index. +.PP +\&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR, +\&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR, +\&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR, +\&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR +return the different method functions. +.PP +\&\fBUI_method_get_ex_data()\fR returns the application data previously stored +with \fBUI_method_set_ex_data()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBUI_create_method()\fR returns a UI_METHOD pointer on success, NULL on +error. +.PP +\&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR, +\&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR, +\&\fBUI_method_set_closer()\fR, \fBUI_method_set_data_duplicator()\fR and +\&\fBUI_method_set_prompt_constructor()\fR +return 0 on success, \-1 if the given \fBmethod\fR is NULL. +.PP +\&\fBUI_method_set_ex_data()\fR returns 1 on success and 0 on error (because +\&\fBCRYPTO_set_ex_data()\fR does so). +.PP +\&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR, +\&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR, +\&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR, +\&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR +return the requested function pointer if it\*(Aqs set in the method, +otherwise NULL. +.PP +\&\fBUI_method_get_ex_data()\fR returns a pointer to the application specific +data associated with the method. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBUI\fR\|(3), \fBCRYPTO_get_ex_data\fR\|(3), \fBUI_STRING\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBUI_method_set_data_duplicator()\fR, \fBUI_method_get_data_duplicator()\fR +and \fBUI_method_get_data_destructor()\fR functions were added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/UI_new.3 b/static/netbsd/man3/UI_new.3 new file mode 100644 index 00000000..2c48cf9e --- /dev/null +++ b/static/netbsd/man3/UI_new.3 @@ -0,0 +1,319 @@ +.\" $NetBSD: UI_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "UI_new 3" +.TH UI_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +UI, +UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, +UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, +UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, +UI_add_error_string, UI_dup_error_string, UI_construct_prompt, +UI_add_user_data, UI_dup_user_data, UI_get0_user_data, UI_get0_result, +UI_get_result_length, +UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method, +UI_get_method, UI_set_method, UI_OpenSSL, UI_null \- user interface +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct ui_st UI; +\& +\& UI *UI_new(void); +\& UI *UI_new_method(const UI_METHOD *method); +\& void UI_free(UI *ui); +\& +\& int UI_add_input_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize); +\& int UI_dup_input_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize); +\& int UI_add_verify_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize, +\& const char *test_buf); +\& int UI_dup_verify_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize, +\& const char *test_buf); +\& int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, +\& const char *ok_chars, const char *cancel_chars, +\& int flags, char *result_buf); +\& int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, +\& const char *ok_chars, const char *cancel_chars, +\& int flags, char *result_buf); +\& int UI_add_info_string(UI *ui, const char *text); +\& int UI_dup_info_string(UI *ui, const char *text); +\& int UI_add_error_string(UI *ui, const char *text); +\& int UI_dup_error_string(UI *ui, const char *text); +\& +\& char *UI_construct_prompt(UI *ui_method, +\& const char *phrase_desc, const char *object_name); +\& +\& void *UI_add_user_data(UI *ui, void *user_data); +\& int UI_dup_user_data(UI *ui, void *user_data); +\& void *UI_get0_user_data(UI *ui); +\& +\& const char *UI_get0_result(UI *ui, int i); +\& int UI_get_result_length(UI *ui, int i); +\& +\& int UI_process(UI *ui); +\& +\& int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); +\& +\& void UI_set_default_method(const UI_METHOD *meth); +\& const UI_METHOD *UI_get_default_method(void); +\& const UI_METHOD *UI_get_method(UI *ui); +\& const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); +\& +\& UI_METHOD *UI_OpenSSL(void); +\& const UI_METHOD *UI_null(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +UI stands for User Interface, and is general purpose set of routines to +prompt the user for text\-based information. Through user\-written methods +(see \fBUI_create_method\fR\|(3)), prompting can be done in any way +imaginable, be it plain text prompting, through dialog boxes or from a +cell phone. +.PP +All the functions work through a context of the type UI. This context +contains all the information needed to prompt correctly as well as a +reference to a UI_METHOD, which is an ordered vector of functions that +carry out the actual prompting. +.PP +The first thing to do is to create a UI with \fBUI_new()\fR or \fBUI_new_method()\fR, +then add information to it with the UI_add or UI_dup functions. Also, +user\-defined random data can be passed down to the underlying method +through calls to \fBUI_add_user_data()\fR or \fBUI_dup_user_data()\fR. The default +UI method doesn\*(Aqt care about these data, but other methods might. Finally, +use \fBUI_process()\fR to actually perform the prompting and \fBUI_get0_result()\fR +and \fBUI_get_result_length()\fR to find the result to the prompt and its length. +.PP +A UI can contain more than one prompt, which are performed in the given +sequence. Each prompt gets an index number which is returned by the +UI_add and UI_dup functions, and has to be used to get the corresponding +result with \fBUI_get0_result()\fR and \fBUI_get_result_length()\fR. +.PP +\&\fBUI_process()\fR can be called more than once on the same UI, thereby allowing +a UI to have a long lifetime, but can just as well have a short lifetime. +.PP +The functions are as follows: +.PP +\&\fBUI_new()\fR creates a new UI using the default UI method. When done with +this UI, it should be freed using \fBUI_free()\fR. +.PP +\&\fBUI_new_method()\fR creates a new UI using the given UI method. When done with +this UI, it should be freed using \fBUI_free()\fR. +.PP +\&\fBUI_OpenSSL()\fR returns the built\-in UI method (note: not necessarily the +default one, since the default can be changed. See further on). This +method is the most machine/OS dependent part of OpenSSL and normally +generates the most problems when porting. +.PP +\&\fBUI_null()\fR returns a UI method that does nothing. Its use is to avoid +getting internal defaults for passed UI_METHOD pointers. +.PP +\&\fBUI_free()\fR removes a UI from memory, along with all other pieces of memory +that\*(Aqs connected to it, like duplicated input strings, results and others. +If \fBui\fR is NULL nothing is done. +.PP +\&\fBUI_add_input_string()\fR and \fBUI_add_verify_string()\fR add a prompt to the UI, +as well as flags and a result buffer and the desired minimum and maximum +sizes of the result, not counting the final NUL character. The given +information is used to prompt for information, for example a password, +and to verify a password (i.e. having the user enter it twice and check +that the same string was entered twice). \fBUI_add_verify_string()\fR takes +and extra argument that should be a pointer to the result buffer of the +input string that it\*(Aqs supposed to verify, or verification will fail. +.PP +\&\fBUI_add_input_boolean()\fR adds a prompt to the UI that\*(Aqs supposed to be answered +in a boolean way, with a single character for yes and a different character +for no. A set of characters that can be used to cancel the prompt is given +as well. The prompt itself is divided in two, one part being the +descriptive text (given through the \fIprompt\fR argument) and one describing +the possible answers (given through the \fIaction_desc\fR argument). +.PP +\&\fBUI_add_info_string()\fR and \fBUI_add_error_string()\fR add strings that are shown at +the same time as the prompt for extra information or to show an error string. +The difference between the two is only conceptual. With the built\-in method, +there\*(Aqs no technical difference between them. Other methods may make a +difference between them, however. +.PP +The flags currently supported are \fBUI_INPUT_FLAG_ECHO\fR, which is relevant for +\&\fBUI_add_input_string()\fR and will have the users response be echoed (when +prompting for a password, this flag should obviously not be used, and +\&\fBUI_INPUT_FLAG_DEFAULT_PWD\fR, which means that a default password of some +sort will be used (completely depending on the application and the UI +method). +.PP +\&\fBUI_dup_input_string()\fR, \fBUI_dup_verify_string()\fR, \fBUI_dup_input_boolean()\fR, +\&\fBUI_dup_info_string()\fR and \fBUI_dup_error_string()\fR are basically the same +as their UI_add counterparts, except that they make their own copies +of all strings. +.PP +\&\fBUI_construct_prompt()\fR is a helper function that can be used to create +a prompt from two pieces of information: a phrase description \fIphrase_desc\fR +and an object name \fIobject_name\fR, where the latter may be NULL. +The default constructor (if there is none provided by the method used) +creates a string "Enter \fIphrase_desc\fR for \fIobject_name\fR:" +where the " for \fIobject_name\fR" part is left out if \fIobject_name\fR is NULL. +With the description "pass phrase" and the filename "foo.key", that becomes +"Enter pass phrase for foo.key:". Other methods may create whatever +string and may include encodings that will be processed by the other +method functions. +.PP +\&\fBUI_add_user_data()\fR sets the user data pointer for the method to use at any +time. The built\-in UI method doesn\*(Aqt care about this info. Note that several +calls to this function doesn\*(Aqt add data, it replaces the previous pointer +with the one given as argument. +The return value is the previously set user data pointer if it was set +using \fBUI_add_user_data()\fR and thus the caller owns it, otherwise NULL. +.PP +\&\fBUI_dup_user_data()\fR duplicates the user data and works as an alternative +to \fBUI_add_user_data()\fR when the user data needs to be preserved for a longer +duration, perhaps even the lifetime of the application. The UI object takes +ownership of this duplicate and will free it whenever it gets replaced or +the UI is destroyed. \fBUI_dup_user_data()\fR returns 0 on success, or \-1 on memory +allocation failure or if the method doesn\*(Aqt have a duplicator and a destructor +function. +.PP +\&\fBUI_get0_user_data()\fR retrieves the data that has last been given to the +UI with \fBUI_add_user_data()\fR or UI_dup_user_data. +.PP +\&\fBUI_get0_result()\fR returns a pointer to the result buffer associated with +the information indexed by \fIi\fR. +.PP +\&\fBUI_get_result_length()\fR returns the length of the result buffer associated with +the information indexed by \fIi\fR. +.PP +\&\fBUI_process()\fR goes through the information given so far, does all the printing +and prompting and returns the final status, which is \-2 on out\-of\-band events +(Interrupt, Cancel, ...), \-1 on error and 0 on success. +.PP +\&\fBUI_ctrl()\fR adds extra control for the application author. For now, it +understands two commands: \fBUI_CTRL_PRINT_ERRORS\fR, which makes \fBUI_process()\fR +print the OpenSSL error stack as part of processing the UI, and +\&\fBUI_CTRL_IS_REDOABLE\fR, which returns a flag saying if the used UI can +be used again or not. +.PP +\&\fBUI_set_default_method()\fR changes the default UI method to the one given. +This function is not thread\-safe and should not be called at the same time +as other OpenSSL functions. +.PP +\&\fBUI_get_default_method()\fR returns a pointer to the current default UI method. +.PP +\&\fBUI_get_method()\fR returns the UI method associated with a given UI. +.PP +\&\fBUI_set_method()\fR changes the UI method associated with a given UI. +.SH NOTES +.IX Header "NOTES" +The resulting strings that the built in method \fBUI_OpenSSL()\fR generate +are assumed to be encoded according to the current locale or (for +Windows) code page. +For applications having different demands, these strings need to be +converted appropriately by the caller. +For Windows, if the \fBOPENSSL_WIN32_UTF8\fR environment variable is set, +the built\-in method \fBUI_OpenSSL()\fR will produce UTF\-8 encoded strings +instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBUI_new()\fR and \fBUI_new_method()\fR return a valid \fBUI\fR structure or NULL if an error +occurred. +.PP +\&\fBUI_add_input_string()\fR, \fBUI_dup_input_string()\fR, \fBUI_add_verify_string()\fR, +\&\fBUI_dup_verify_string()\fR, \fBUI_add_input_boolean()\fR, \fBUI_dup_input_boolean()\fR, +\&\fBUI_add_info_string()\fR, \fBUI_dup_info_string()\fR, \fBUI_add_error_string()\fR +and \fBUI_dup_error_string()\fR return a positive number on success or a value which +is less than or equal to 0 otherwise. +.PP +\&\fBUI_construct_prompt()\fR returns a string or NULL if an error occurred. +.PP +\&\fBUI_add_user_data()\fR returns +the user data pointer previously set using this function, otherwise NULL. +.PP +\&\fBUI_dup_user_data()\fR returns 0 on success or \-1 on error. +.PP +\&\fBUI_get0_result()\fR returns a string or NULL on error. +.PP +\&\fBUI_get_result_length()\fR returns a positive integer or 0 on success; otherwise it +returns \-1 on error. +.PP +\&\fBUI_process()\fR returns 0 on success or a negative value on error. +.PP +\&\fBUI_ctrl()\fR returns a mask on success or \-1 on error. +.PP +\&\fBUI_get_default_method()\fR, \fBUI_get_method()\fR, \fBUI_OpenSSL()\fR, \fBUI_null()\fR and +\&\fBUI_set_method()\fR return either a valid \fBUI_METHOD\fR structure or NULL +respectively. +.SH HISTORY +.IX Header "HISTORY" +The \fBUI_dup_user_data()\fR function was added in OpenSSL 1.1.1. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM.3 b/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM.3 new file mode 100644 index 00000000..9ceca81e --- /dev/null +++ b/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: WINCNG_CIPHER_ALGORITHM.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3 b/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3 new file mode 100644 index 00000000..3cf8fe12 --- /dev/null +++ b/static/netbsd/man3/WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: WINCNG_CIPHER_ALGORITHM_UNAVAILABLE.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hcrypto_evp.3 diff --git a/static/netbsd/man3/X509V3_get_d2i.3 b/static/netbsd/man3/X509V3_get_d2i.3 new file mode 100644 index 00000000..592da0ea --- /dev/null +++ b/static/netbsd/man3/X509V3_get_d2i.3 @@ -0,0 +1,327 @@ +.\" $NetBSD: X509V3_get_d2i.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509V3_get_d2i 3" +.TH X509V3_get_d2i 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, +X509_get_ext_d2i, X509_add1_ext_i2d, +X509_ACERT_get_ext_d2i, X509_ACERT_add1_ext_i2d, +X509_CRL_get_ext_d2i, X509_CRL_add1_ext_i2d, +X509_REVOKED_get_ext_d2i, X509_REVOKED_add1_ext_i2d, +X509_get0_extensions, X509_ACERT_get0_extensions, X509_CRL_get0_extensions, +X509_REVOKED_get0_extensions \- X509 extension decode and encode functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit, +\& int *idx); +\& int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, +\& int crit, unsigned long flags); +\& +\& void *X509V3_EXT_d2i(X509_EXTENSION *ext); +\& X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); +\& +\& void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx); +\& int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, +\& unsigned long flags); +\& +\& void *X509_ACERT_get_ext_d2i(const X509_ACERT *x, int nid, int *crit, int *idx); +\& int X509_ACERT_add1_ext_i2d(X509_ACERT *x, int nid, void *value, int crit, +\& unsigned long flags); +\& +\& void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx); +\& int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit, +\& unsigned long flags); +\& +\& void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx); +\& int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit, +\& unsigned long flags); +\& +\& const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x); +\& const STACK_OF(X509_EXTENSION) *X509_ACERT_get0_extensions(const X509 *x); +\& const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl); +\& const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509V3_get_d2i()\fR looks for an extension with OID \fInid\fR in the extensions +\&\fIx\fR and, if found, decodes it. If \fIidx\fR is NULL then only one +occurrence of an extension is permissible, otherwise the first extension after +index \fI*idx\fR is returned and \fI*idx\fR updated to the location of the extension. +If \fIcrit\fR is not NULL then \fI*crit\fR is set to a status value: \-2 if the +extension occurs multiple times (this is only returned if \fIidx\fR is NULL), +\&\-1 if the extension could not be found, 0 if the extension is found and is +not critical and 1 if critical. A pointer to an extension specific structure +or NULL is returned. +.PP +\&\fBX509V3_add1_i2d()\fR adds extension \fIvalue\fR to STACK \fI*x\fR (allocating a new +STACK if necessary) using OID \fInid\fR and criticality \fIcrit\fR according +to \fIflags\fR. +.PP +\&\fBX509V3_EXT_d2i()\fR attempts to decode the ASN.1 data contained in extension +\&\fIext\fR and returns a pointer to an extension specific structure or NULL +if the extension could not be decoded (invalid syntax or not supported). +.PP +\&\fBX509V3_EXT_i2d()\fR encodes the extension specific structure \fIext_struc\fR +with OID \fIext_nid\fR and criticality \fIcrit\fR. +.PP +\&\fBX509_get_ext_d2i()\fR and \fBX509_add1_ext_i2d()\fR operate on the extensions of +certificate \fIx\fR. They are otherwise identical to \fBX509V3_get_d2i()\fR and +\&\fBX509V3_add1_i2d()\fR. +.PP +\&\fBX509_ACERT_get_ext_d2i()\fR and \fBX509_ACERT_add1_ext_i2d()\fR operate on the extensions +of \fBX509_ACERT\fR structure \fIx\fR. They are otherwise identical to \fBX509V3_get_d2i()\fR +and \fBX509V3_add1_i2d()\fR. +.PP +\&\fBX509_CRL_get_ext_d2i()\fR and \fBX509_CRL_add1_ext_i2d()\fR operate on the extensions +of CRL \fIcrl\fR. They are otherwise identical to \fBX509V3_get_d2i()\fR and +\&\fBX509V3_add1_i2d()\fR. +.PP +\&\fBX509_REVOKED_get_ext_d2i()\fR and \fBX509_REVOKED_add1_ext_i2d()\fR operate on the +extensions of \fBX509_REVOKED\fR structure \fIr\fR (i.e for CRL entry extensions). +They are otherwise identical to \fBX509V3_get_d2i()\fR and \fBX509V3_add1_i2d()\fR. +.PP +\&\fBX509_get0_extensions()\fR, \fBX509_ACERT_get0_extensions()\fR, +\&\fBX509_CRL_get0_extensions()\fR and \fBX509_REVOKED_get0_extensions()\fR return a +STACK of all the extensions of a certificate, an attribute certificate, +a CRL or a CRL entry respectively. +.SH NOTES +.IX Header "NOTES" +In almost all cases an extension can occur at most once and multiple +occurrences is an error. Therefore, the \fIidx\fR parameter is usually NULL. +.PP +The \fIflags\fR parameter may be one of the following values. +.PP +\&\fBX509V3_ADD_DEFAULT\fR appends a new extension only if the extension does +not exist. An error is returned if the extension exists. +.PP +\&\fBX509V3_ADD_APPEND\fR appends a new extension, ignoring whether the extension +exists. +.PP +\&\fBX509V3_ADD_REPLACE\fR replaces an existing extension. If the extension does +not exist, appends a new extension. +.PP +\&\fBX509V3_ADD_REPLACE_EXISTING\fR replaces an existing extension. If the +extension does not exist, returns an error. +.PP +\&\fBX509V3_ADD_KEEP_EXISTING\fR appends a new extension only if the extension does +not exist. An error is \fBnot\fR returned if the extension exists. +.PP +\&\fBX509V3_ADD_DELETE\fR deletes and frees an existing extension. If the extension +does not exist, returns an error. No new extension is added. +.PP +If \fBX509V3_ADD_SILENT\fR is bitwise ORed with \fIflags\fR: any error returned +will not be added to the error queue. +.PP +The function \fBX509V3_get_d2i()\fR and its variants +will return NULL if the extension is not +found, occurs multiple times or cannot be decoded. It is possible to +determine the precise reason by checking the value of \fI*crit\fR. +The returned pointer must be explicitly freed. +.PP +The function \fBX509V3_add1_i2d()\fR and its variants allocate \fBX509_EXTENSION\fR +objects on STACK \fI*x\fR depending on \fIflags\fR. The \fBX509_EXTENSION\fR objects +must be explicitly freed using \fBX509_EXTENSION_free()\fR. +.SH "SUPPORTED EXTENSIONS" +.IX Header "SUPPORTED EXTENSIONS" +The following sections contain a list of all supported extensions +including their name and NID. +.SS "PKIX Certificate Extensions" +.IX Subsection "PKIX Certificate Extensions" +The following certificate extensions are defined in PKIX standards such as +RFC5280. +.PP +.Vb 3 +\& Basic Constraints NID_basic_constraints +\& Key Usage NID_key_usage +\& Extended Key Usage NID_ext_key_usage +\& +\& Subject Key Identifier NID_subject_key_identifier +\& Authority Key Identifier NID_authority_key_identifier +\& +\& Private Key Usage Period NID_private_key_usage_period +\& +\& Subject Alternative Name NID_subject_alt_name +\& Issuer Alternative Name NID_issuer_alt_name +\& +\& Authority Information Access NID_info_access +\& Subject Information Access NID_sinfo_access +\& +\& Name Constraints NID_name_constraints +\& +\& Certificate Policies NID_certificate_policies +\& Policy Mappings NID_policy_mappings +\& Policy Constraints NID_policy_constraints +\& Inhibit Any Policy NID_inhibit_any_policy +\& +\& TLS Feature NID_tlsfeature +.Ve +.SS "Netscape Certificate Extensions" +.IX Subsection "Netscape Certificate Extensions" +The following are (largely obsolete) Netscape certificate extensions. +.PP +.Vb 8 +\& Netscape Cert Type NID_netscape_cert_type +\& Netscape Base Url NID_netscape_base_url +\& Netscape Revocation Url NID_netscape_revocation_url +\& Netscape CA Revocation Url NID_netscape_ca_revocation_url +\& Netscape Renewal Url NID_netscape_renewal_url +\& Netscape CA Policy Url NID_netscape_ca_policy_url +\& Netscape SSL Server Name NID_netscape_ssl_server_name +\& Netscape Comment NID_netscape_comment +.Ve +.SS "Miscellaneous Certificate Extensions" +.IX Subsection "Miscellaneous Certificate Extensions" +.Vb 2 +\& Strong Extranet ID NID_sxnet +\& Proxy Certificate Information NID_proxyCertInfo +.Ve +.SS "PKIX CRL Extensions" +.IX Subsection "PKIX CRL Extensions" +The following are CRL extensions from PKIX standards such as RFC5280. +.PP +.Vb 6 +\& CRL Number NID_crl_number +\& CRL Distribution Points NID_crl_distribution_points +\& Delta CRL Indicator NID_delta_crl +\& Freshest CRL NID_freshest_crl +\& Invalidity Date NID_invalidity_date +\& Issuing Distribution Point NID_issuing_distribution_point +.Ve +.PP +The following are CRL entry extensions from PKIX standards such as RFC5280. +.PP +.Vb 2 +\& CRL Reason Code NID_crl_reason +\& Certificate Issuer NID_certificate_issuer +.Ve +.SS "OCSP Extensions" +.IX Subsection "OCSP Extensions" +.Vb 7 +\& OCSP Nonce NID_id_pkix_OCSP_Nonce +\& OCSP CRL ID NID_id_pkix_OCSP_CrlID +\& Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses +\& OCSP No Check NID_id_pkix_OCSP_noCheck +\& OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff +\& OCSP Service Locator NID_id_pkix_OCSP_serviceLocator +\& Hold Instruction Code NID_hold_instruction_code +.Ve +.SS "Certificate Transparency Extensions" +.IX Subsection "Certificate Transparency Extensions" +The following extensions are used by certificate transparency, RFC6962 +.PP +.Vb 2 +\& CT Precertificate SCTs NID_ct_precert_scts +\& CT Certificate SCTs NID_ct_cert_scts +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509V3_get_d2i()\fR, its variants, and \fBX509V3_EXT_d2i()\fR return +a pointer to an extension specific structure or NULL if an error occurs. +.PP +\&\fBX509V3_add1_i2d()\fR and its variants return 1 if the operation is successful +and 0 if it fails due to a non\-fatal error (extension not found, already exists, +cannot be encoded) or \-1 due to a fatal error such as a memory allocation +failure. +.PP +\&\fBX509V3_EXT_i2d()\fR returns a pointer to an \fBX509_EXTENSION\fR structure +or NULL if an error occurs. +.PP +\&\fBX509_get0_extensions()\fR, \fBX509_CRL_get0_extensions()\fR and +\&\fBX509_REVOKED_get0_extensions()\fR return a stack of extensions. They return +NULL if no extensions are present. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_ACERT_get_ext_d2i()\fR, \fBX509_ACERT_add1_ext_i2d()\fR, +\&\fBX509_ACERT_get0_extensions()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509V3_set_ctx.3 b/static/netbsd/man3/X509V3_set_ctx.3 new file mode 100644 index 00000000..911b2383 --- /dev/null +++ b/static/netbsd/man3/X509V3_set_ctx.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: X509V3_set_ctx.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509V3_set_ctx 3" +.TH X509V3_set_ctx 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509V3_set_ctx, +X509V3_set_issuer_pkey \- X.509 v3 extension generation utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, +\& X509_REQ *req, X509_CRL *crl, int flags); +\& int X509V3_set_issuer_pkey(X509V3_CTX *ctx, EVP_PKEY *pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509V3_set_ctx()\fR fills in the basic fields of \fIctx\fR of type \fBX509V3_CTX\fR, +providing details potentially needed by functions producing X509 v3 extensions. +These may make use of fields of the certificate \fIsubject\fR, the certification +request \fIreq\fR, or the certificate revocation list \fIcrl\fR. +At most one of these three parameters can be non\-NULL. +When constructing the subject key identifier of a certificate by computing a +hash value of its public key, the public key is taken from \fIsubject\fR or \fIreq\fR. +Similarly, when constructing subject alternative names from any email addresses +contained in a subject DN, the subject DN is taken from \fIsubject\fR or \fIreq\fR. +If \fIsubject\fR or \fIcrl\fR is provided, \fIissuer\fR should point to its issuer, for +instance as a reference for generating the authority key identifier extension. +\&\fIissuer\fR may be the same pointer value as \fIsubject\fR (which usually is an +indication that the \fIsubject\fR certificate is self\-issued or even self\-signed). +In this case the fallback source for generating the authority key identifier +extension will be taken from any value provided using \fBX509V3_set_issuer_pkey()\fR. +\&\fIflags\fR may be 0 +or contain \fBX509V3_CTX_TEST\fR, which means that just the syntax of +extension definitions is to be checked without actually producing any extension, +or \fBX509V3_CTX_REPLACE\fR, which means that each X.509v3 extension added as +defined in some configuration section shall replace any already existing +extension with the same OID. +.PP +\&\fBX509V3_set_issuer_pkey()\fR explicitly sets the issuer private key of +the subject certificate that has been provided in \fIctx\fR. +This should be done in case the \fIissuer\fR and \fIsubject\fR arguments to +\&\fBX509V3_set_ctx()\fR have the same pointer value +to provide fallback data for the authority key identifier extension. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509V3_set_issuer_pkey()\fR returns 1 on success and 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_add_ext\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509V3_set_issuer_pkey()\fR was added in OpenSSL 3.0. +.PP +CTX_TEST was deprecated in OpenSSL 3.0; use X509V3_CTX_TEST instead. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ACERT_add1_attr.3 b/static/netbsd/man3/X509_ACERT_add1_attr.3 new file mode 100644 index 00000000..b17b4c65 --- /dev/null +++ b/static/netbsd/man3/X509_ACERT_add1_attr.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: X509_ACERT_add1_attr.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ACERT_add1_attr 3" +.TH X509_ACERT_add1_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ACERT_add1_attr, +X509_ACERT_add1_attr_by_NID, +X509_ACERT_add1_attr_by_OBJ, +X509_ACERT_add1_attr_by_txt, +X509_ACERT_delete_attr +\&\- X509_ACERT attribute functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_ACERT_add1_attr(X509_ACERT *x, X509_ATTRIBUTE *attr); +\& int X509_ACERT_add1_attr_by_NID(X509_ACERT *x, int nid, int type, +\& const void *bytes, int len); +\& int X509_ACERT_add1_attr_by_OBJ(X509_ACERT *x, const ASN1_OBJECT *obj, +\& int type, const void *bytes, int len); +\& int X509_ACERT_add1_attr_by_txt(X509_ACERT *x, const char *attrname, int type, +\& const unsigned char *bytes, int len); +\& X509_ATTRIBUTE *X509_ACERT_delete_attr(X509_ACERT *x, int loc); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ACERT_add1_attr()\fR adds a constructed X509_ATTRIBUTE \fBattr\fR to the +existing X509_ACERT structure \fBx\fR. +.PP +\&\fBX509_ACERT_add1_attr_by_NID()\fR and \fBX509_ACERT_add1_attr_by_OBJ()\fR +add an attribute of type \fInid\fR or \fIobj\fR with a value of ASN1 +type \fItype\fR constructed using \fIlen\fR bytes from \fIbytes\fR. +.PP +\&\fBX509_ACERT_add1_attr_by_txt()\fR adds an attribute of type \fIattrname\fR with a value of +ASN1 type \fItype\fR constructed using \fIlen\fR bytes from \fIbytes\fR. +.PP +\&\fBX509_ACERT_delete_attr()\fR will delete the \fIloc\fRth attribute from \fIx\fR and +return a pointer to it or NULL if there are fewer than \fIloc\fR attributes +contained in \fIx\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_ACERT_add1_attr()\fR, \fBX509_ACERT_add1_attr_by_NID()\fR, and +\&\fBX509_ACERT_add1_attr_by_OBJ()\fR return 1 for success and 0 for failure. +.PP +\&\fBX509_ACERT_delete_attr()\fR returns a \fBX509_ATTRIBUTE\fR pointer on +success or NULL on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_ACERT_get_attr_count\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_ACERT_add1_attr()\fR, \fBX509_ACERT_add1_attr_by_NID()\fR, \fBX509_ACERT_add1_attr_by_OBJ()\fR, +\&\fBX509_ACERT_add1_attr_by_txt()\fR and \fBX509_ACERT_delete_attr()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ACERT_add_attr_nconf.3 b/static/netbsd/man3/X509_ACERT_add_attr_nconf.3 new file mode 100644 index 00000000..a8351eea --- /dev/null +++ b/static/netbsd/man3/X509_ACERT_add_attr_nconf.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: X509_ACERT_add_attr_nconf.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ACERT_add_attr_nconf 3" +.TH X509_ACERT_add_attr_nconf 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ACERT_add_attr_nconf +\&\- Add attributes to X509_ACERT from configuration section +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_ACERT_add_attr_nconf(CONF *conf, const char *section, +\& X509_ACERT *acert); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ACERT_add_attr_nconf()\fR adds one or more \fBX509_ATTRIBUTE\fRs to the +existing \fBX509_ACERT\fR structure \fIacert\fR. The attributes are read +from a \fIsection\fR of the \fIconf\fR object. +.PP +The give \fIsection\fR of the configuration should contain attribute +descriptions of the form: +.PP +.Vb 1 +\& attribute_name = value +.Ve +.PP +The format of \fBvalue\fR will vary depending on the \fBattribute_name\fR. +\&\fBvalue\fR can either be a string value or an \fBASN1_TYPE\fR +object. +.PP +To encode an \fBASN1_TYPE\fR object, use the prefix "ASN1:" followed by +the object description that uses the same syntax as \fBASN1_generate_nconf\fR\|(3). +For example: +.PP +.Vb 1 +\& id\-aca\-group = ASN1:SEQUENCE:ietfattr +\& +\& [ietfattr] +\& values = SEQUENCE:groups +\& +\& [groups] +\& 1.string = UTF8:mygroup1 +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_ACERT_add_attr_nconf()\fR returns 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_generate_nconf\fR\|(3). +.SH HISTORY +.IX Header "HISTORY" +The function \fBX509_ACERT_add_attr_nconf()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ACERT_get0_holder_baseCertId.3 b/static/netbsd/man3/X509_ACERT_get0_holder_baseCertId.3 new file mode 100644 index 00000000..434084a1 --- /dev/null +++ b/static/netbsd/man3/X509_ACERT_get0_holder_baseCertId.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: X509_ACERT_get0_holder_baseCertId.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ACERT_get0_holder_baseCertId 3" +.TH X509_ACERT_get0_holder_baseCertId 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ACERT_get0_holder_baseCertId, +X509_ACERT_get0_holder_digest, +X509_ACERT_get0_holder_entityName, +X509_ACERT_set0_holder_baseCertId, +X509_ACERT_set0_holder_digest, +X509_ACERT_set0_holder_entityName, +OSSL_ISSUER_SERIAL_get0_issuer, +OSSL_ISSUER_SERIAL_get0_issuerUID, +OSSL_ISSUER_SERIAL_get0_serial, +OSSL_ISSUER_SERIAL_set1_issuer, +OSSL_ISSUER_SERIAL_set1_issuerUID, +OSSL_ISSUER_SERIAL_set1_serial, +OSSL_OBJECT_DIGEST_INFO_get0_digest, +OSSL_OBJECT_DIGEST_INFO_set1_digest \- get and set Attribute Certificate holder fields +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const GENERAL_NAMES *X509_ACERT_get0_holder_entityName(const X509_ACERT *x); +\& OSSL_ISSUER_SERIAL *X509_ACERT_get0_holder_baseCertId(const X509_ACERT *x); +\& OSSL_OBJECT_DIGEST_INFO * X509_ACERT_get0_holder_digest(const X509_ACERT *x); +\& void X509_ACERT_set0_holder_entityName(X509_ACERT *x, GENERAL_NAMES *name); +\& void X509_ACERT_set0_holder_baseCertId(X509_ACERT *x, OSSL_ISSUER_SERIAL *isss); +\& void X509_ACERT_set0_holder_digest(X509_ACERT *x, +\& OSSL_OBJECT_DIGEST_INFO *dinfo); +\& +\& X509_NAME *OSSL_ISSUER_SERIAL_get0_issuer(OSSL_ISSUER_SERIAL *isss); +\& ASN1_INTEGER *OSSL_ISSUER_SERIAL_get0_serial(OSSL_ISSUER_SERIAL *isss); +\& ASN1_BIT_STRING *OSSL_ISSUER_SERIAL_get0_issuerUID(OSSL_ISSUER_SERIAL *isss); +\& int OSSL_ISSUER_SERIAL_set1_issuer(OSSL_ISSUER_SERIAL *isss, X509_NAME *issuer); +\& int OSSL_ISSUER_SERIAL_set1_serial(OSSL_ISSUER_SERIAL *isss, ASN1_INTEGER *serial); +\& int OSSL_ISSUER_SERIAL_set1_issuerUID(OSSL_ISSUER_SERIAL *isss, ASN1_BIT_STRING *uid); +\& +\& void OSSL_OBJECT_DIGEST_INFO_get0_digest(OSSL_OBJECT_DIGEST_INFO *o, +\& ASN1_ENUMERATED **digestedObjectType, +\& X509_ALGOR **digestAlgorithm, +\& ASN1_BIT_STRING **digest); +\& void OSSL_OBJECT_DIGEST_INFO_set1_digest(OSSL_OBJECT_DIGEST_INFO *o, +\& ASN1_ENUMERATED *digestedObjectType, +\& X509_ALGOR *digestAlgorithm, +\& ASN1_BIT_STRING *digest); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These routines set and get the holder identity of an X509 attribute certificate. +.PP +\&\fBX509_ACERT_set0_holder_entityName()\fR sets the identity as a \fBGENERAL_NAME\fR +\&\fIname\fR, \fBX509_ACERT_set0_holder_baseCertId()\fR sets the identity based on the +issuer and serial number of a certificate detailed in \fIisss\fR and +\&\fBX509_ACERT_set0_holder_digest()\fR sets the holder entity based on digest +information \fIdinfo\fR. Although RFC 5755 section 4.2.2 recommends that only +one of the above methods be used to set the holder identity for a given +attribute certificate \fIx\fR, setting multiple methods at the same time is +possible. It is up to the application to handle cases when conflicting +identity information is specified using different methods. +.PP +Pointers to the internal structures describing the holder identity of +attribute certificate \fIx\fR can be retrieved with +\&\fBX509_ACERT_get0_holder_entityName()\fR, \fBX509_ACERT_get0_holder_baseCertId()\fR, and +\&\fBX509_ACERT_get0_holder_digest()\fR. +.PP +A \fBOSSL_ISSUER_SERIAL\fR object holds the subject name and UID of a certificate +issuer and a certificate\*(Aqs serial number. \fBOSSL_ISSUER_SERIAL_set1_issuer()\fR, +\&\fBOSSL_ISSUER_SERIAL_set1_issuerUID()\fR, and \fBOSSL_ISSUER_SERIAL_set1_serial()\fR +respectively copy these values into the \fBOSSL_ISSUER_SERIAL\fR structure. +The application is responsible for freeing its own copy of these values after +use. \fBOSSL_ISSUER_SERIAL_get0_issuer()\fR, \fBOSSL_ISSUER_SERIAL_get0_issuerUID()\fR, +and \fBOSSL_ISSUER_SERIAL_get0_serial()\fR return pointers to these values in the object. +.PP +An \fBOSSL_OBJECT_DIGEST_INFO\fR object holds a digest of data to identify the +attribute certificate holder. \fBOSSL_OBJECT_DIGEST_INFO_set1_digest()\fR sets the +digest information of the object. The type of \fIdigest\fR information is given +by \fIdigestedObjectType\fR and can be one of: +.IP OSSL_OBJECT_DIGEST_INFO_PUBLIC_KEY 4 +.IX Item "OSSL_OBJECT_DIGEST_INFO_PUBLIC_KEY" +Hash of a public key +.IP OSSL_OBJECT_DIGEST_INFO_PUBLIC_KEY_CERT 4 +.IX Item "OSSL_OBJECT_DIGEST_INFO_PUBLIC_KEY_CERT" +Hash of a public key certificate +.IP OSSL_OBJECT_DIGEST_INFO_OTHER 4 +.IX Item "OSSL_OBJECT_DIGEST_INFO_OTHER" +Hash of another object. See NOTES below. +.PP +\&\fIdigestAlgorithm\fR indicates the algorithm used to compute \fIdigest\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All \fIset0\fR/\fIset1\fR routines return 1 for success and 0 for failure. +All \fIget0\fR functions return a pointer to the object\*(Aqs inner structure. These +pointers must not be freed after use. +.SH NOTES +.IX Header "NOTES" +Although the value of \fBOSSL_OBJECT_DIGEST_INFO_OTHER\fR is defined in RFC 5755, +its use is prohibited for conformant attribute certificates. +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ACERT_get_attr.3 b/static/netbsd/man3/X509_ACERT_get_attr.3 new file mode 100644 index 00000000..a65d7e8d --- /dev/null +++ b/static/netbsd/man3/X509_ACERT_get_attr.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: X509_ACERT_get_attr.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ACERT_get_attr 3" +.TH X509_ACERT_get_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ACERT_get_attr, +X509_ACERT_get_attr_by_NID, +X509_ACERT_get_attr_by_OBJ, +X509_ACERT_get_attr_count +\&\- Retrieve attributes from an X509_ACERT structure +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_ATTRIBUTE *X509_ACERT_get_attr(const X509_ACERT *x, int loc); +\& int X509_ACERT_get_attr_by_NID(const X509_ACERT *x, int nid, int lastpos); +\& int X509_ACERT_get_attr_by_OBJ(const X509_ACERT *x, const ASN1_OBJECT *obj, +\& int lastpos); +\& int X509_ACERT_get_attr_count(const X509_ACERT *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ACERT_get0_attr()\fR retrieves the \fIloc\fRth \fBX509_ATTRIBUTE\fR from an +\&\fBX509_ACERT\fR \fIx\fR. \fBX509_ACERT_get_attr_count()\fR returns the total number +of attributes in the \fBX509_ACERT\fR. +.PP +\&\fBX509_ACERT_get_attr_by_NID()\fR and \fBX509_ACERT_get_attr_by_OBJ()\fR retrieve the next +attribute location matching \fInid\fR or \fIobj\fR after \fIlastpos\fR. \fIlastpos\fR +should initially be set to \-1. +If there are no more entries \-1 is returned. If \fInid\fR is invalid +(doesn\*(Aqt correspond to a valid OID) then \-2 is returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_ACERT_get0_attr()\fR return a \fBX509_ATTRIBUTE\fR from an attribute +certificate, or NULL if the specified attribute is not found. +.PP +\&\fBX509_ACERT_get_attr_by_NID()\fR and \fBX509_ACERT_get_attr_by_OBJ()\fR return +the location of the next attribute requested or \-1 if not found. +\&\fBX509_ACERT_get_attr_by_NID()\fR can also return \-2 if the supplied NID is invalid. +.PP +\&\fBX509_ACERT_get_attr_count()\fR returns the number of attributes in the given +attribute certificate. +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_ACERT_get0_attr()\fR, \fBX509_ACERT_get_attr_by_NID()\fR, \fBX509_ACERT_get_attr_by_OBJ()\fR and +\&\fBX509_ACERT_get_attr_count()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ACERT_print_ex.3 b/static/netbsd/man3/X509_ACERT_print_ex.3 new file mode 100644 index 00000000..089a60b0 --- /dev/null +++ b/static/netbsd/man3/X509_ACERT_print_ex.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: X509_ACERT_print_ex.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ACERT_print_ex 3" +.TH X509_ACERT_print_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ACERT_print_ex, X509_ACERT_print +\&\- X509_ACERT printing routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_ACERT_print(BIO *bp, X509_ACERT *acert); +\& int X509_ACERT_print_ex(BIO *bp, X509_ACERT *acert, unsigned long nmflags, +\& unsigned long cflag); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ACERT_print_ex()\fR prints a human readable version of the attribute +certificate \fIacert\fR to BIO \fIbp\fR. +.PP +The following data contained in the attribute certificate is printed +in order: +.IP \(bu 4 +The header text "Attribute certificate:" and "Data:" (X509_FLAG_NO_HEADER) +.Sp += item * +.Sp +The attribute certificate version number as defined by the standard, +followed in parentheses by the value contained in the version field in +hexadecimal notation. If the version number is not a valid value according +to the specification, only the raw value is printed. +See \fBX509_ACERT_get_version\fR\|(3) for details. (X509_FLAG_NO_VERSION) +.Sp += item * +.Sp +The serial number of the attribute certificate (X509_FLAG_NO_SERIAL) +.Sp += item * +.Sp +The identity of the holder of the attribute certificate. If the +holder issuer name is present, the first GENERAL_NAME +returned by \fBX509_ACERT_get0_holder_entityName()\fR is printed. +If the holder baseCertificateId is present, the issuer name +(printed with X509_NAME_print_ex) and serial number of the +holder\*(Aqs certificate are displayed. (X509_FLAG_NO_SUBJECT) +.Sp += item * +.Sp +The name of the attribute certificate issuer as returned from +\&\fBX509_ACERT_get0_issuerName()\fR and printed using \fBX509_NAME_print_ex()\fR. +(X509_FLAG_NO_ISSUER) +.Sp += item * +.Sp +The period of validity between the times returned from \fBX509_ACERT_get0_notBefore()\fR +and \fBX509_ACERT_get0_notAfter()\fR. The values are printed as a generalized times +using \fBASN1_GENERALIZEDTIME_print()\fR. (X509_FLAG_NO_VALIDITY) +.Sp += item * +.Sp +The list of attributes contained in the attribute certificate. +The attribute type is printed with \fBi2a_ASN1_OBJECT()\fR. String valued +attributes are printed as raw string data. ASN1 encoded values are +printed with \fBASN1_parse_dump()\fR. (X509_FLAG_NO_ATTRIBUTES) +.Sp += item * +.Sp +All X.509 extensions contained in the attribute certificate. (X509_FLAG_NO_EXTENSIONS) +.Sp += item * +.Sp +The signature is printed with \fBX509_signature_print()\fR. (X509_FLAG_NO_SIGDUMP) +.Sp +If \fIcflag\fR is specifies as X509_FLAG_COMPAT, all of the above data in the +attribute certificate will be printed. +.Sp +The \fInmflags\fR flag determines the format used to output all fields printed using +\&\fBX509_NAME_print_ex()\fR. See \fBX509_NAME_print_ex\fR\|(3) for details. +.Sp +\&\fBX509_ACERT_print()\fR is equivalent to calling \fBX509_ACERT_print_ex()\fR with the +\&\fInmflags\fR and \fIcflags\fR set to XN_FLAG_COMPAT and X509_FLAG_COMPAT +respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_ACERT_print_ex()\fR \fBX509_ACERT_print()\fR return 1 for +success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_NAME_print_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_ACERT_print()\fR and \fBX509_ACERT_print_ex()\fR were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ALGOR_dup.3 b/static/netbsd/man3/X509_ALGOR_dup.3 new file mode 100644 index 00000000..ac85dd07 --- /dev/null +++ b/static/netbsd/man3/X509_ALGOR_dup.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: X509_ALGOR_dup.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ALGOR_dup 3" +.TH X509_ALGOR_dup 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ALGOR_dup, +X509_ALGOR_set0, X509_ALGOR_get0, +X509_ALGOR_set_md, X509_ALGOR_cmp, +X509_ALGOR_copy \- AlgorithmIdentifier functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg); +\& int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval); +\& void X509_ALGOR_get0(const ASN1_OBJECT **paobj, int *pptype, +\& const void **ppval, const X509_ALGOR *alg); +\& void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); +\& int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); +\& int X509_ALGOR_copy(X509_ALGOR *dest, const X509_ALGOR *src); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ALGOR_dup()\fR returns a copy of \fIalg\fR. +.PP +\&\fBX509_ALGOR_set0()\fR sets the algorithm OID of \fIalg\fR to \fIaobj\fR and the +associated parameter type to \fIptype\fR with value \fIpval\fR. If \fIptype\fR is +\&\fBV_ASN1_UNDEF\fR the parameter is omitted, otherwise \fIptype\fR and \fIpval\fR have +the same meaning as the \fItype\fR and \fIvalue\fR parameters to \fBASN1_TYPE_set()\fR. +All the supplied parameters are used internally so must \fBNOT\fR be freed after +this call succeeded; +otherwise ownership remains with the caller and \fIalg\fR remains untouched. +.PP +\&\fBX509_ALGOR_get0()\fR is the inverse of \fBX509_ALGOR_set0()\fR: it returns the +algorithm OID in \fI*paobj\fR and the associated parameter in \fI*pptype\fR +and \fI*ppval\fR from the \fBAlgorithmIdentifier\fR \fIalg\fR. +.PP +\&\fBX509_ALGOR_set_md()\fR sets the \fBAlgorithmIdentifier\fR \fIalg\fR to appropriate +values for the message digest \fImd\fR. +.PP +\&\fBX509_ALGOR_cmp()\fR compares \fIa\fR and \fIb\fR and returns 0 if they have identical +encodings and nonzero otherwise. +.PP +\&\fBX509_ALGOR_copy()\fR copies the source values into the dest structs; making +a duplicate of each (and free any thing pointed to from within *dest). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_ALGOR_dup()\fR returns a valid \fBX509_ALGOR\fR structure or NULL if an error +occurred. +.PP +\&\fBX509_ALGOR_set0()\fR and \fBX509_ALGOR_copy()\fR return 1 on success or 0 on error. +.PP +\&\fBX509_ALGOR_get0()\fR and \fBX509_ALGOR_set_md()\fR return no values. +.PP +\&\fBX509_ALGOR_cmp()\fR returns 0 if the two parameters have identical encodings and +nonzero otherwise. +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_ALGOR_copy()\fR was added in 1.1.1e. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_ATTRIBUTE.3 b/static/netbsd/man3/X509_ATTRIBUTE.3 new file mode 100644 index 00000000..099ff903 --- /dev/null +++ b/static/netbsd/man3/X509_ATTRIBUTE.3 @@ -0,0 +1,326 @@ +.\" $NetBSD: X509_ATTRIBUTE.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_ATTRIBUTE 3" +.TH X509_ATTRIBUTE 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_ATTRIBUTE, X509at_get_attr, +X509at_get_attr_count, X509at_get_attr_by_NID, X509at_get_attr_by_OBJ, +X509at_delete_attr, +X509at_add1_attr, +X509at_add1_attr_by_OBJ, X509at_add1_attr_by_NID, X509at_add1_attr_by_txt, +X509at_get0_data_by_OBJ, +X509_ATTRIBUTE_create, X509_ATTRIBUTE_create_by_NID, +X509_ATTRIBUTE_create_by_OBJ, X509_ATTRIBUTE_create_by_txt, +X509_ATTRIBUTE_set1_object, X509_ATTRIBUTE_set1_data, +X509_ATTRIBUTE_count, +X509_ATTRIBUTE_get0_data, X509_ATTRIBUTE_get0_object, X509_ATTRIBUTE_get0_type +\&\- X509 attribute functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef struct x509_attributes_st X509_ATTRIBUTE; +\& +\& int X509at_get_attr_count(const STACK_OF(X509_ATTRIBUTE) *x); +\& int X509at_get_attr_by_NID(const STACK_OF(X509_ATTRIBUTE) *x, int nid, +\& int lastpos); +\& int X509at_get_attr_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *sk, +\& const ASN1_OBJECT *obj, int lastpos); +\& X509_ATTRIBUTE *X509at_get_attr(const STACK_OF(X509_ATTRIBUTE) *x, int loc); +\& X509_ATTRIBUTE *X509at_delete_attr(STACK_OF(X509_ATTRIBUTE) *x, int loc); +\& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr(STACK_OF(X509_ATTRIBUTE) **x, +\& X509_ATTRIBUTE *attr); +\& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_OBJ(STACK_OF(X509_ATTRIBUTE) +\& **x, const ASN1_OBJECT *obj, +\& int type, +\& const unsigned char *bytes, +\& int len); +\& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_NID(STACK_OF(X509_ATTRIBUTE) +\& **x, int nid, int type, +\& const unsigned char *bytes, +\& int len); +\& STACK_OF(X509_ATTRIBUTE) *X509at_add1_attr_by_txt(STACK_OF(X509_ATTRIBUTE) +\& **x, const char *attrname, +\& int type, +\& const unsigned char *bytes, +\& int len); +\& void *X509at_get0_data_by_OBJ(const STACK_OF(X509_ATTRIBUTE) *x, +\& const ASN1_OBJECT *obj, int lastpos, int type); +\& X509_ATTRIBUTE *X509_ATTRIBUTE_create(int nid, int atrtype, void *value); +\& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **attr, int nid, +\& int atrtype, const void *data, +\& int len); +\& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **attr, +\& const ASN1_OBJECT *obj, +\& int atrtype, const void *data, +\& int len); +\& X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_txt(X509_ATTRIBUTE **attr, +\& const char *atrname, int type, +\& const unsigned char *bytes, +\& int len); +\& int X509_ATTRIBUTE_set1_object(X509_ATTRIBUTE *attr, const ASN1_OBJECT *obj); +\& int X509_ATTRIBUTE_set1_data(X509_ATTRIBUTE *attr, int attrtype, +\& const void *data, int len); +\& void *X509_ATTRIBUTE_get0_data(X509_ATTRIBUTE *attr, int idx, int atrtype, +\& void *data); +\& int X509_ATTRIBUTE_count(const X509_ATTRIBUTE *attr); +\& ASN1_OBJECT *X509_ATTRIBUTE_get0_object(X509_ATTRIBUTE *attr); +\& ASN1_TYPE *X509_ATTRIBUTE_get0_type(X509_ATTRIBUTE *attr, int idx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_ATTRIBUTE\fR objects are used by many standards including X509, X509_REQ, +PKCS12, PKCS8, PKCS7 and CMS. +.PP +The \fBX509_ATTRIBUTE\fR object is used to represent the ASN.1 Attribute as defined +in RFC 5280, i.e. +.PP +.Vb 3 +\& Attribute ::= SEQUENCE { +\& type AttributeType, +\& values SET OF AttributeValue } +\& +\& AttributeType ::= OBJECT IDENTIFIER +\& AttributeValue ::= ANY \-\- DEFINED BY AttributeType +.Ve +.PP +For example CMS defines the signing\-time attribute as: +.PP +.Vb 2 +\& id\-signingTime OBJECT IDENTIFIER ::= { iso(1) member\-body(2) +\& us(840) rsadsi(113549) pkcs(1) pkcs9(9) 5 } +\& +\& SigningTime ::= Time +\& +\& Time ::= CHOICE { +\& utcTime UTCTime, +\& generalizedTime GeneralizedTime } +.Ve +.PP +In OpenSSL \fBAttributeType\fR maps to an \fBASN1_OBJECT\fR object +and \fBAttributeValue\fR maps to a list of \fBASN1_TYPE\fR objects. +.PP +The following functions are used for \fBX509_ATTRIBUTE\fR objects. +.PP +\&\fBX509at_get_attr_by_OBJ()\fR finds the location of the first matching object \fIobj\fR +in a list of attributes \fIsk\fR. The search starts at the position after \fIlastpos\fR. +If the returned value is positive then it can be used on the next call to +\&\fBX509at_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in order to iterate through +the remaining attributes. \fIlastpos\fR can be set to any negative value on the +first call, in order to start searching from the start of the list. +.PP +\&\fBX509at_get_attr_by_NID()\fR is similar to \fBX509at_get_attr_by_OBJ()\fR except that it +passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBX509at_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the +list of attributes \fIx\fR. \fIloc\fR should be in the range from 0 to +\&\fBX509at_get_attr_count()\fR \- 1. +.PP +\&\fBX509at_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in +the list of attributes \fIx\fR. +.PP +\&\fBX509at_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR object +to the list \fIx\fR. +Both \fIx\fR and \fIattr\fR must be non NULL or an error will occur. +If \fI*x\fR is NULL then a new list is created, otherwise it uses the +passed in list. An error will occur if an existing attribute (with the same +attribute type) already exists in the attribute list. +.PP +\&\fBX509at_add1_attr_by_OBJ()\fR creates a new \fBX509_ATTRIBUTE\fR using +\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new +\&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it +to the attribute list \fIx\fR. Both \fIx\fR and \fIattr\fR must be non NULL or an error +will occur. If \fI*x\fR is NULL then a new attribute list is created. If \fIobj\fR +already exists in the attribute list then an error occurs. +.PP +\&\fBX509at_add1_attr_by_NID()\fR is similar to \fBX509at_add1_attr_by_OBJ()\fR except that it +passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBX509at_add1_attr_by_txt()\fR is similar to \fBX509at_add1_attr_by_OBJ()\fR except that it +passes a name \fIattrname\fR associated with the object. +See for a list of SN_* names. +.PP +\&\fBX509_ATTRIBUTE_set1_object()\fR assigns a \fBASN1_OBJECT\fR \fIobj\fR +to the attribute \fIattr\fR. If \fIattr\fR contained an existing \fBASN1_OBJECT\fR then +it is freed. An error occurs if either \fIattr\fR or \fIobj\fR are NULL, or if +the passed in \fIobj\fR cannot be duplicated. +.PP +\&\fBX509_ATTRIBUTE_set1_data()\fR pushes a new \fBASN1_TYPE\fR object onto the \fIattr\fR +attributes list. The new object is assigned a copy of the data in \fIdata\fR of +size \fIlen\fR. +If \fIattrtype\fR has flag \fIMBSTRING_FLAG\fR set then a table lookup using the +\&\fIattr\fR attributes NID is used to set an \fBASN1_STRING\fR using +\&\fBASN1_STRING_set_by_NID()\fR, and the passed in \fIdata\fR must be in the format +required for that object type or an error will occur. +If \fIlen\fR is not \-1 then internally \fBASN1_STRING_type_new()\fR is +used with the passed in \fIattrtype\fR. +If \fIattrtype\fR is 0 the call does nothing except return 1. +.PP +\&\fBX509_ATTRIBUTE_create()\fR creates a new \fBX509_ATTRIBUTE\fR using the \fInid\fR +to set the \fBASN1_OBJECT\fR OID and the \fIatrtype\fR and \fIvalue\fR to set the +\&\fBASN1_TYPE\fR. +.PP +\&\fBX509_ATTRIBUTE_create_by_OBJ()\fR uses \fBX509_ATTRIBUTE_set1_object()\fR and +\&\fBX509_ATTRIBUTE_set1_data()\fR to assign a new \fIobj\fR with type \fIatrtype\fR and +data \fIdata\fR of length \fIlen\fR. If the passed in attribute \fIattr\fR OR \fI*attr\fR is +NULL then a new \fBX509_ATTRIBUTE\fR will be returned, otherwise the passed in +\&\fBX509_ATTRIBUTE\fR is used. Note that the ASN1_OBJECT \fIobj\fR is pushed onto the +attributes existing list of objects, which could be an issue if the attributes + was different. +.PP +\&\fBX509_ATTRIBUTE_create_by_NID()\fR is similar to \fBX509_ATTRIBUTE_create_by_OBJ()\fR +except that it passes the numerical identifier (NID) \fInid\fR associated with the +object. See for a list of NID_*. +.PP +\&\fBX509_ATTRIBUTE_create_by_txt()\fR is similar to \fBX509_ATTRIBUTE_create_by_OBJ()\fR +except that it passes a name \fIatrname\fR associated with the +object. See for a list of SN_* names. +.PP +\&\fBX509_ATTRIBUTE_count()\fR returns the number of \fBASN1_TYPE\fR objects in an +attribute \fIattr\fR. +.PP +\&\fBX509_ATTRIBUTE_get0_type()\fR returns the \fBASN1_TYPE\fR object at index \fIidx\fR in +the attribute list \fIattr\fR. \fIidx\fR should be in the +range of 0 to \fBX509_ATTRIBUTE_count()\fR \- 1 or an error will occur. +.PP +\&\fBX509_ATTRIBUTE_get0_data()\fR returns the data of an \fBASN1_TYPE\fR object at +index \fIidx\fR in the attribute \fIattr\fR. \fIdata\fR is unused and can be set to NULL. +An error will occur if the attribute type \fIatrtype\fR does not match the type of +the \fBASN1_TYPE\fR object at index \fIidx\fR OR if \fIatrtype\fR is either +\&\fBV_ASN1_BOOLEAN\fR or \fBV_ASN1_NULL\fR OR if the \fIidx\fR is not in the +range 0 to \fBX509_ATTRIBUTE_count()\fR \- 1. +.PP +\&\fBX509at_get0_data_by_OBJ()\fR finds the first attribute in an attribute list \fIx\fR +that matches the \fIobj\fR starting at index \fIlastpos\fR and returns the data +retrieved from the found attributes first \fBASN1_TYPE\fR object. An error will +occur if the attribute type \fItype\fR does not match the type of the \fBASN1_TYPE\fR +object OR if \fItype\fR is either \fBV_ASN1_BOOLEAN\fR or \fBV_ASN1_NULL\fR OR the +attribute is not found. +If \fIlastpos\fR is less than \-1 then an error will occur if there are multiple +objects in the list \fIx\fR that match \fIobj\fR. +If \fIlastpos\fR is less than \-2 then an error will occur if there is more than +one \fBASN1_TYPE\fR object in the found attribute. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509at_get_attr_count()\fR returns the number of attributes in the list \fIx\fR or \-1 +if \fIx\fR is NULL. +.PP +\&\fBX509at_get_attr_by_OBJ()\fR returns \-1 if either the list is empty OR the object +is not found, otherwise it returns the location of the object in the list. +.PP +\&\fBX509at_get_attr_by_NID()\fR is similar to \fBX509at_get_attr_by_OBJ()\fR, except that +it returns \-2 if the \fInid\fR is not known by OpenSSL. +.PP +\&\fBX509at_get_attr()\fR returns either an \fBX509_ATTRIBUTE\fR or NULL if there is a error. +.PP +\&\fBX509at_delete_attr()\fR returns either the removed \fBX509_ATTRIBUTE\fR or NULL if +there is a error. +.PP +\&\fBX509_ATTRIBUTE_count()\fR returns \-1 on error, otherwise it returns the number +of \fBASN1_TYPE\fR elements. +.PP +\&\fBX509_ATTRIBUTE_get0_type()\fR returns NULL on error, otherwise it returns a +\&\fBASN1_TYPE\fR object. +.PP +\&\fBX509_ATTRIBUTE_get0_data()\fR returns NULL if an error occurs, +otherwise it returns the data associated with an \fBASN1_TYPE\fR object. +.PP +\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR returns 1 on +success, or 0 otherwise. +.PP +\&\fBX509_ATTRIBUTE_create()\fR, \fBX509_ATTRIBUTE_create_by_OBJ()\fR, +\&\fBX509_ATTRIBUTE_create_by_NID()\fR and \fBX509_ATTRIBUTE_create_by_txt()\fR return either +a \fBX509_ATTRIBUTE\fR on success, or NULL if there is a error. +.PP +\&\fBX509at_add1_attr()\fR, \fBX509at_add1_attr_by_OBJ()\fR, \fBX509at_add1_attr_by_NID()\fR and +\&\fBX509at_add1_attr_by_txt()\fR return NULL on error, otherwise they return a list +of \fBX509_ATTRIBUTE\fR. +.PP +\&\fBX509at_get0_data_by_OBJ()\fR returns the data retrieved from the found attributes +first \fBASN1_TYPE\fR object, or NULL if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_TYPE_get\fR\|(3), +\&\fBASN1_INTEGER_get\fR\|(3), +\&\fBASN1_ENUMERATED_get\fR\|(3), +\&\fBASN1_STRING_get0_data\fR\|(3), +\&\fBASN1_STRING_length\fR\|(3), +\&\fBASN1_STRING_type\fR\|(3), +\&\fBX509_REQ_get_attr\fR\|(3), +\&\fBEVP_PKEY_get_attr\fR\|(3), +\&\fBCMS_signed_get_attr\fR\|(3), +\&\fBPKCS8_pkey_get0_attrs\fR\|(3), +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_CRL_get0_by_serial.3 b/static/netbsd/man3/X509_CRL_get0_by_serial.3 new file mode 100644 index 00000000..da7946c4 --- /dev/null +++ b/static/netbsd/man3/X509_CRL_get0_by_serial.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: X509_CRL_get0_by_serial.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_CRL_get0_by_serial 3" +.TH X509_CRL_get0_by_serial 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_CRL_get0_by_serial, X509_CRL_get0_by_cert, X509_CRL_get_REVOKED, +X509_REVOKED_get0_serialNumber, X509_REVOKED_get0_revocationDate, +X509_REVOKED_set_serialNumber, X509_REVOKED_set_revocationDate, +X509_CRL_add0_revoked, X509_CRL_sort \- CRL revoked entry utility +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_CRL_get0_by_serial(X509_CRL *crl, +\& X509_REVOKED **ret, const ASN1_INTEGER *serial); +\& int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x); +\& +\& STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl); +\& +\& const ASN1_INTEGER *X509_REVOKED_get0_serialNumber(const X509_REVOKED *r); +\& const ASN1_TIME *X509_REVOKED_get0_revocationDate(const X509_REVOKED *r); +\& +\& int X509_REVOKED_set_serialNumber(X509_REVOKED *r, ASN1_INTEGER *serial); +\& int X509_REVOKED_set_revocationDate(X509_REVOKED *r, ASN1_TIME *tm); +\& +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& +\& int X509_CRL_sort(X509_CRL *crl); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_CRL_get0_by_serial()\fR attempts to find a revoked entry in \fIcrl\fR for +serial number \fIserial\fR. If it is successful, it sets \fI*ret\fR to the internal +pointer of the matching entry. As a result, \fI*ret\fR \fBMUST NOT\fR be freed +after the call. +.PP +\&\fBX509_CRL_get0_by_cert()\fR is similar to \fBX509_get0_by_serial()\fR except it +looks for a revoked entry using the serial number of certificate \fIx\fR. +.PP +\&\fBX509_CRL_get_REVOKED()\fR returns an internal pointer to a STACK of all +revoked entries for \fIcrl\fR. +.PP +\&\fBX509_REVOKED_get0_serialNumber()\fR returns an internal pointer to the +serial number of \fIr\fR. +.PP +\&\fBX509_REVOKED_get0_revocationDate()\fR returns an internal pointer to the +revocation date of \fIr\fR. +.PP +\&\fBX509_REVOKED_set_serialNumber()\fR sets the serial number of \fIr\fR to \fIserial\fR. +The supplied \fIserial\fR pointer is not used internally so it should be +freed after use. +.PP +\&\fBX509_REVOKED_set_revocationDate()\fR sets the revocation date of \fIr\fR to +\&\fItm\fR. The supplied \fItm\fR pointer is not used internally so it should be +freed after use. +.PP +\&\fBX509_CRL_add0_revoked()\fR appends revoked entry \fIrev\fR to CRL \fIcrl\fR. The +pointer \fIrev\fR is used internally so it \fBMUST NOT\fR be freed after the call: +it is freed when the parent CRL is freed. +.PP +\&\fBX509_CRL_sort()\fR sorts the revoked entries of \fIcrl\fR into ascending serial +number order. +.SH NOTES +.IX Header "NOTES" +Applications can determine the number of revoked entries returned by +\&\fBX509_CRL_get_REVOKED()\fR using \fBsk_X509_REVOKED_num()\fR and examine each one +in turn using \fBsk_X509_REVOKED_value()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_CRL_get0_by_serial()\fR and \fBX509_CRL_get0_by_cert()\fR return 0 for failure, +1 on success except if the revoked entry has the reason \f(CW\*(C`removeFromCRL\*(C'\fR (8), +in which case 2 is returned. +.PP +\&\fBX509_CRL_get_REVOKED()\fR returns a STACK of revoked entries. +.PP +\&\fBX509_REVOKED_get0_serialNumber()\fR returns an \fBASN1_INTEGER\fR structure. +.PP +\&\fBX509_REVOKED_get0_revocationDate()\fR returns an \fBASN1_TIME\fR structure. +.PP +\&\fBX509_REVOKED_set_serialNumber()\fR, \fBX509_REVOKED_set_revocationDate()\fR, +\&\fBX509_CRL_add0_revoked()\fR and \fBX509_CRL_sort()\fR return 1 for success and 0 for +failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_EXTENSION_set_object.3 b/static/netbsd/man3/X509_EXTENSION_set_object.3 new file mode 100644 index 00000000..8ba3b76c --- /dev/null +++ b/static/netbsd/man3/X509_EXTENSION_set_object.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: X509_EXTENSION_set_object.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_EXTENSION_set_object 3" +.TH X509_EXTENSION_set_object 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_EXTENSION_set_object, X509_EXTENSION_set_critical, +X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID, +X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object, +X509_EXTENSION_get_critical, X509_EXTENSION_get_data \- extension utility +functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj); +\& int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit); +\& int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data); +\& +\& X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex, +\& int nid, int crit, +\& ASN1_OCTET_STRING *data); +\& X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex, +\& const ASN1_OBJECT *obj, int crit, +\& ASN1_OCTET_STRING *data); +\& +\& ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex); +\& int X509_EXTENSION_get_critical(const X509_EXTENSION *ex); +\& ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_EXTENSION_set_object()\fR sets the extension type of \fBex\fR to \fBobj\fR. The +\&\fBobj\fR pointer is duplicated internally so \fBobj\fR should be freed up after use. +.PP +\&\fBX509_EXTENSION_set_critical()\fR sets the criticality of \fBex\fR to \fBcrit\fR. If +\&\fBcrit\fR is zero the extension in non\-critical otherwise it is critical. +.PP +\&\fBX509_EXTENSION_set_data()\fR sets the data in extension \fBex\fR to \fBdata\fR. The +\&\fBdata\fR pointer is duplicated internally. +.PP +\&\fBX509_EXTENSION_create_by_NID()\fR creates an extension of type \fBnid\fR, +criticality \fBcrit\fR using data \fBdata\fR. The created extension is returned and +written to \fB*ex\fR reusing or allocating a new extension if necessary so \fB*ex\fR +should either be \fBNULL\fR or a valid \fBX509_EXTENSION\fR structure it must +\&\fBnot\fR be an uninitialised pointer. +.PP +\&\fBX509_EXTENSION_create_by_OBJ()\fR is identical to \fBX509_EXTENSION_create_by_NID()\fR +except it creates and extension using \fBobj\fR instead of a NID. +.PP +\&\fBX509_EXTENSION_get_object()\fR returns the extension type of \fBex\fR as an +\&\fBASN1_OBJECT\fR pointer. The returned pointer is an internal value which must +not be freed up. +.PP +\&\fBX509_EXTENSION_get_critical()\fR returns the criticality of extension \fBex\fR it +returns \fB1\fR for critical and \fB0\fR for non\-critical. +.PP +\&\fBX509_EXTENSION_get_data()\fR returns the data of extension \fBex\fR. The returned +pointer is an internal value which must not be freed up. +.SH NOTES +.IX Header "NOTES" +These functions manipulate the contents of an extension directly. Most +applications will want to parse or encode and add an extension: they should +use the extension encode and decode functions instead such as +\&\fBX509_add1_ext_i2d()\fR and \fBX509_get_ext_d2i()\fR. +.PP +The \fBdata\fR associated with an extension is the extension encoding in an +\&\fBASN1_OCTET_STRING\fR structure. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_EXTENSION_set_object()\fR \fBX509_EXTENSION_set_critical()\fR and +\&\fBX509_EXTENSION_set_data()\fR return \fB1\fR for success and \fB0\fR for failure. +.PP +\&\fBX509_EXTENSION_create_by_NID()\fR and \fBX509_EXTENSION_create_by_OBJ()\fR return +an \fBX509_EXTENSION\fR pointer or \fBNULL\fR if an error occurs. +.PP +\&\fBX509_EXTENSION_get_object()\fR returns an \fBASN1_OBJECT\fR pointer. +.PP +\&\fBX509_EXTENSION_get_critical()\fR returns \fB0\fR for non\-critical and \fB1\fR for +critical. +.PP +\&\fBX509_EXTENSION_get_data()\fR returns an \fBASN1_OCTET_STRING\fR pointer. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509V3_get_d2i\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_LOOKUP.3 b/static/netbsd/man3/X509_LOOKUP.3 new file mode 100644 index 00000000..4d0fd475 --- /dev/null +++ b/static/netbsd/man3/X509_LOOKUP.3 @@ -0,0 +1,298 @@ +.\" $NetBSD: X509_LOOKUP.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_LOOKUP 3" +.TH X509_LOOKUP 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_LOOKUP, X509_LOOKUP_TYPE, +X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init, +X509_LOOKUP_shutdown, +X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data, +X509_LOOKUP_ctrl_ex, X509_LOOKUP_ctrl, +X509_LOOKUP_load_file_ex, X509_LOOKUP_load_file, +X509_LOOKUP_add_dir, +X509_LOOKUP_add_store_ex, X509_LOOKUP_add_store, +X509_LOOKUP_load_store_ex, X509_LOOKUP_load_store, +X509_LOOKUP_get_store, +X509_LOOKUP_by_subject_ex, X509_LOOKUP_by_subject, +X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint, +X509_LOOKUP_by_alias +\&\- OpenSSL certificate lookup mechanisms +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef x509_lookup_st X509_LOOKUP; +\& +\& typedef enum X509_LOOKUP_TYPE; +\& +\& X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method); +\& int X509_LOOKUP_init(X509_LOOKUP *ctx); +\& int X509_LOOKUP_shutdown(X509_LOOKUP *ctx); +\& void X509_LOOKUP_free(X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data); +\& void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_ctrl_ex(X509_LOOKUP *ctx, int cmd, const char *argc, long argl, +\& char **ret, OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc, +\& long argl, char **ret); +\& int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type); +\& int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type); +\& int X509_LOOKUP_add_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int X509_LOOKUP_add_store(X509_LOOKUP *ctx, char *uri); +\& int X509_LOOKUP_load_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int X509_LOOKUP_load_store(X509_LOOKUP *ctx, char *uri); +\& +\& X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_by_subject_ex(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, +\& const X509_NAME *name, X509_OBJECT *ret, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, +\& const X509_NAME *name, X509_OBJECT *ret); +\& int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, +\& const X509_NAME *name, +\& const ASN1_INTEGER *serial, X509_OBJECT *ret); +\& int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, +\& const unsigned char *bytes, int len, +\& X509_OBJECT *ret); +\& int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, +\& const char *str, int len, X509_OBJECT *ret); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_LOOKUP\fR structure holds the information needed to look up +certificates and CRLs according to an associated \fBX509_LOOKUP_METHOD\fR\|(3). +Multiple \fBX509_LOOKUP\fR instances can be added to an \fBX509_STORE\fR\|(3) +to enable lookup in that store. +.PP +\&\fBX509_LOOKUP_new()\fR creates a new \fBX509_LOOKUP\fR using the given lookup +\&\fImethod\fR. +It can also be created by calling \fBX509_STORE_add_lookup\fR\|(3), which +will associate a \fBX509_STORE\fR with the lookup mechanism. +.PP +\&\fBX509_LOOKUP_init()\fR initializes the internal state and resources as +needed by the given \fBX509_LOOKUP\fR to do its work. +.PP +\&\fBX509_LOOKUP_shutdown()\fR tears down the internal state and resources of +the given \fBX509_LOOKUP\fR. +.PP +\&\fBX509_LOOKUP_free()\fR destructs the given \fBX509_LOOKUP\fR. +If the argument is NULL, nothing is done. +.PP +\&\fBX509_LOOKUP_set_method_data()\fR and \fBX509_LOOKUP_get_method_data()\fR +associates and retrieves a pointer to application data to and from the +given \fBX509_LOOKUP\fR, respectively. +.PP +\&\fBX509_LOOKUP_ctrl_ex()\fR is used to set or get additional data to or from +a \fBX509_LOOKUP\fR structure using any control function in the +associated \fBX509_LOOKUP_METHOD\fR\|(3). +The arguments of the control command are passed via \fIargc\fR and \fIargl\fR, +its return value via \fI*ret\fR. The library context \fIlibctx\fR and property +query \fIpropq\fR are used when fetching algorithms from providers. +The meaning of the arguments depends on the \fIcmd\fR number of the +control command. In general, this function is not called directly, but +wrapped by a macro call, see below. +The control \fIcmd\fRs known to OpenSSL are discussed in more depth +in "Control Commands". +.PP +\&\fBX509_LOOKUP_ctrl()\fR is similar to \fBX509_LOOKUP_ctrl_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_LOOKUP_load_file_ex()\fR passes a filename to be loaded immediately +into the associated \fBX509_STORE\fR. The library context \fIlibctx\fR and property +query \fIpropq\fR are used when fetching algorithms from providers. +\&\fItype\fR indicates what type of object is expected. +This can only be used with a lookup using the implementation +\&\fBX509_LOOKUP_file\fR\|(3). +.PP +\&\fBX509_LOOKUP_load_file()\fR is similar to \fBX509_LOOKUP_load_file_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_LOOKUP_add_dir()\fR passes a directory specification from which +certificates and CRLs are loaded on demand into the associated +\&\fBX509_STORE\fR. +\&\fItype\fR indicates what type of object is expected. +This can only be used with a lookup using the implementation +\&\fBX509_LOOKUP_hash_dir\fR\|(3). +.PP +\&\fBX509_LOOKUP_add_store_ex()\fR passes a URI for a directory\-like structure +from which containers with certificates and CRLs are loaded on demand +into the associated \fBX509_STORE\fR. The library context \fIlibctx\fR and property +query \fIpropq\fR are used when fetching algorithms from providers. +.PP +\&\fBX509_LOOKUP_add_store()\fR is similar to \fBX509_LOOKUP_add_store_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_LOOKUP_load_store_ex()\fR passes a URI for a single container from +which certificates and CRLs are immediately loaded into the associated +\&\fBX509_STORE\fR. The library context \fIlibctx\fR and property query \fIpropq\fR are used +when fetching algorithms from providers. +These functions can only be used with a lookup using the +implementation \fBX509_LOOKUP_store\fR\|(3). +.PP +\&\fBX509_LOOKUP_load_store()\fR is similar to \fBX509_LOOKUP_load_store_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_LOOKUP_load_file_ex()\fR, \fBX509_LOOKUP_load_file()\fR, +\&\fBX509_LOOKUP_add_dir()\fR, +\&\fBX509_LOOKUP_add_store_ex()\fR \fBX509_LOOKUP_add_store()\fR, +\&\fBX509_LOOKUP_load_store_ex()\fR and \fBX509_LOOKUP_load_store()\fR are +implemented as macros that use \fBX509_LOOKUP_ctrl()\fR. +.PP +\&\fBX509_LOOKUP_by_subject_ex()\fR, \fBX509_LOOKUP_by_subject()\fR, +\&\fBX509_LOOKUP_by_issuer_serial()\fR, \fBX509_LOOKUP_by_fingerprint()\fR, and +\&\fBX509_LOOKUP_by_alias()\fR look up certificates and CRLs in the \fBX509_STORE\fR\|(3) +associated with the \fBX509_LOOKUP\fR using different criteria, where the looked up +object is stored in \fIret\fR. +Some of the underlying \fBX509_LOOKUP_METHOD\fRs will also cache objects +matching the criteria in the associated \fBX509_STORE\fR, which makes it +possible to handle cases where the criteria have more than one hit. +.SS "Control Commands" +.IX Subsection "Control Commands" +The \fBX509_LOOKUP_METHOD\fRs built into OpenSSL recognize the following +\&\fBX509_LOOKUP_ctrl()\fR \fIcmd\fRs: +.IP \fBX509_L_FILE_LOAD\fR 4 +.IX Item "X509_L_FILE_LOAD" +This is the command that \fBX509_LOOKUP_load_file_ex()\fR and +\&\fBX509_LOOKUP_load_file()\fR use. +The filename is passed in \fIargc\fR, and the type in \fIargl\fR. +.IP \fBX509_L_ADD_DIR\fR 4 +.IX Item "X509_L_ADD_DIR" +This is the command that \fBX509_LOOKUP_add_dir()\fR uses. +The directory specification is passed in \fIargc\fR, and the type in +\&\fIargl\fR. +.IP \fBX509_L_ADD_STORE\fR 4 +.IX Item "X509_L_ADD_STORE" +This is the command that \fBX509_LOOKUP_add_store_ex()\fR and +\&\fBX509_LOOKUP_add_store()\fR use. +The URI is passed in \fIargc\fR. +.IP \fBX509_L_LOAD_STORE\fR 4 +.IX Item "X509_L_LOAD_STORE" +This is the command that \fBX509_LOOKUP_load_store_ex()\fR and +\&\fBX509_LOOKUP_load_store()\fR use. +The URI is passed in \fIargc\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_LOOKUP_new()\fR returns a \fBX509_LOOKUP\fR pointer when successful, +or NULL on error. +.PP +\&\fBX509_LOOKUP_init()\fR and \fBX509_LOOKUP_shutdown()\fR return 1 on success, or +0 on error. +.PP +\&\fBX509_LOOKUP_ctrl_ex()\fR and \fBX509_LOOKUP_ctrl()\fR +return \-1 if the \fBX509_LOOKUP\fR doesn\*(Aqt have an +associated \fBX509_LOOKUP_METHOD\fR, or 1 if the +doesn\*(Aqt have a control function. +Otherwise, it returns what the control function in the +\&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 on error +but could also be \-1 on failure. +.IX Xref "509_LOOKUP_METHOD" +.PP +\&\fBX509_LOOKUP_get_store()\fR returns a \fBX509_STORE\fR pointer if there is +one, otherwise NULL. +.PP +\&\fBX509_LOOKUP_by_subject_ex()\fR returns 0 if there is no \fBX509_LOOKUP_METHOD\fR +that implements any of the \fBget_by_subject_ex()\fR or \fBget_by_subject()\fR functions. +It calls \fBget_by_subject_ex()\fR if present, otherwise \fBget_by_subject()\fR, and returns +the result of the function, which is usually 1 on success and 0 on error. +.PP +\&\fBX509_LOOKUP_by_subject()\fR is similar to \fBX509_LOOKUP_by_subject_ex()\fR +but passes NULL for both the libctx and propq. +.PP +\&\fBX509_LOOKUP_by_issuer_serial()\fR, \fBX509_LOOKUP_by_fingerprint()\fR, and +\&\fBX509_LOOKUP_by_alias()\fR all return 0 if there is no \fBX509_LOOKUP_METHOD\fR or that +method doesn\*(Aqt implement the corresponding function. +Otherwise, they return what the corresponding function in the +\&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 in +error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_LOOKUP_METHOD\fR\|(3), \fBX509_STORE\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBX509_LOOKUP_by_subject_ex()\fR and +\&\fBX509_LOOKUP_ctrl_ex()\fR were added in OpenSSL 3.0. +.PP +The macros \fBX509_LOOKUP_load_file_ex()\fR, +\&\fBX509_LOOKUP_load_store_ex()\fR and 509_LOOKUP_add_store_ex() were +added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_LOOKUP_hash_dir.3 b/static/netbsd/man3/X509_LOOKUP_hash_dir.3 new file mode 100644 index 00000000..e4a70f31 --- /dev/null +++ b/static/netbsd/man3/X509_LOOKUP_hash_dir.3 @@ -0,0 +1,218 @@ +.\" $NetBSD: X509_LOOKUP_hash_dir.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_LOOKUP_hash_dir 3" +.TH X509_LOOKUP_hash_dir 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, +X509_load_cert_file_ex, X509_load_cert_file, +X509_load_crl_file, +X509_load_cert_crl_file_ex, X509_load_cert_crl_file +\&\- Default OpenSSL certificate lookup methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); +\& X509_LOOKUP_METHOD *X509_LOOKUP_file(void); +\& X509_LOOKUP_METHOD *X509_LOOKUP_store(void); +\& +\& int X509_load_cert_file_ex(X509_LOOKUP *ctx, const char *file, int type, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); +\& int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); +\& int X509_load_cert_crl_file_ex(X509_LOOKUP *ctx, const char *file, int type, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_LOOKUP_hash_dir\fR and \fBX509_LOOKUP_file\fR are two certificate +lookup methods to use with \fBX509_STORE\fR, provided by OpenSSL library. +.PP +Users of the library typically do not need to create instances of these +methods manually, they would be created automatically by +\&\fBX509_STORE_load_locations\fR\|(3) or +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +functions. +.PP +Internally loading of certificates and CRLs is implemented via functions +\&\fBX509_load_cert_crl_file\fR, \fBX509_load_cert_file\fR and +\&\fBX509_load_crl_file\fR. These functions support parameter \fItype\fR, which +can be one of constants \fBFILETYPE_PEM\fR, \fBFILETYPE_ASN1\fR and +\&\fBFILETYPE_DEFAULT\fR. They load certificates and/or CRLs from specified +file into memory cache of \fBX509_STORE\fR objects which given \fBctx\fR +parameter is associated with. +.PP +Functions \fBX509_load_cert_file\fR and +\&\fBX509_load_crl_file\fR can load both PEM and DER formats depending of +type value. Because DER format cannot contain more than one certificate +or CRL object (while PEM can contain several concatenated PEM objects) +\&\fBX509_load_cert_crl_file\fR with \fBFILETYPE_ASN1\fR is equivalent to +\&\fBX509_load_cert_file\fR. +.PP +Constant \fBFILETYPE_DEFAULT\fR with NULL filename causes these functions +to load default certificate store file (see +\&\fBX509_STORE_set_default_paths\fR\|(3). +.PP +Functions return number of objects loaded from file or 0 in case of +error. +.PP +Both methods support adding several certificate locations into one +\&\fBX509_STORE\fR. +.PP +This page documents certificate store formats used by these methods and +caching policy. +.SS "File Method" +.IX Subsection "File Method" +The \fBX509_LOOKUP_file\fR method loads all the certificates or CRLs +present in a file into memory at the time the file is added as a +lookup source. +.PP +File format is ASCII text which contains concatenated PEM certificates +and CRLs. +.PP +This method should be used by applications which work with a small +set of CAs. +.SS "Hashed Directory Method" +.IX Subsection "Hashed Directory Method" +\&\fBX509_LOOKUP_hash_dir\fR is a more advanced method, which loads +certificates and CRLs on demand, and caches them in memory once +they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs +upon each lookup, so that newer CRLs are as soon as they appear in +the directory. +.PP +The directory should contain one certificate or CRL per file in PEM format, +with a filename of the form \fIhash\fR.\fIN\fR for a certificate, or +\&\fIhash\fR.\fBr\fR\fIN\fR for a CRL. +The \fIhash\fR is the value returned by the \fBX509_NAME_hash_ex\fR\|(3) function +applied to the subject name for certificates or issuer name for CRLs. +The hash can also be obtained via the \fB\-hash\fR option of the +\&\fBopenssl\-x509\fR\|(1) or \fBopenssl\-crl\fR\|(1) commands. +.PP +The .\fIN\fR or .\fBr\fR\fIN\fR suffix is a sequence number that starts at zero, and is +incremented consecutively for each certificate or CRL with the same \fIhash\fR +value. +Gaps in the sequence numbers are not supported, it is assumed that there are no +more objects with the same hash beyond the first missing number in the +sequence. +.PP +Sequence numbers make it possible for the directory to contain multiple +certificates with same subject name hash value. +For example, it is possible to have in the store several certificates with same +subject or several CRLs with same issuer (and, for example, different validity +period). +.PP +When checking for new CRLs once one CRL for given hash value is +loaded, hash_dir lookup method checks only for certificates with +sequence number greater than that of the already cached CRL. +.PP +Note that the hash algorithm used for subject name hashing changed in OpenSSL +1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL +0.9.8 to 1.0.0. +.PP +OpenSSL includes a \fBopenssl\-rehash\fR\|(1) utility which creates symlinks with +hashed names for all files with \fI.pem\fR suffix in a given directory. +.SS "OSSL_STORE Method" +.IX Subsection "OSSL_STORE Method" +\&\fBX509_LOOKUP_store\fR is a method that allows access to any store of +certificates and CRLs through any loader supported by +\&\fBossl_store\fR\|(7). +It works with the help of URIs, which can be direct references to +certificates or CRLs, but can also be references to catalogues of such +objects (that behave like directories). +.PP +This method overlaps the "File Method" and "Hashed Directory Method" +because of the \*(Aqfile:\*(Aq scheme loader. +It does no caching of its own, but can use a caching \fBossl_store\fR\|(7) +loader, and therefore depends on the loader\*(Aqs capability. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_LOOKUP_hash_dir()\fR, \fBX509_LOOKUP_file()\fR and \fBX509_LOOKUP_store()\fR +always return a valid \fBX509_LOOKUP_METHOD\fR structure. +.PP +\&\fBX509_load_cert_file()\fR, \fBX509_load_crl_file()\fR and \fBX509_load_cert_crl_file()\fR return +the number of loaded objects or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_read_PrivateKey\fR\|(3), +\&\fBX509_STORE_load_locations\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3), +\&\fBX509_LOOKUP_meth_new\fR\|(3), +\&\fBossl_store\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBX509_load_cert_file_ex()\fR, +\&\fBX509_load_cert_crl_file_ex()\fR and \fBX509_LOOKUP_store()\fR were added in +OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_LOOKUP_meth_new.3 b/static/netbsd/man3/X509_LOOKUP_meth_new.3 new file mode 100644 index 00000000..b0f36d83 --- /dev/null +++ b/static/netbsd/man3/X509_LOOKUP_meth_new.3 @@ -0,0 +1,255 @@ +.\" $NetBSD: X509_LOOKUP_meth_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_LOOKUP_meth_new 3" +.TH X509_LOOKUP_meth_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_LOOKUP_METHOD, +X509_LOOKUP_meth_new, X509_LOOKUP_meth_free, X509_LOOKUP_meth_set_new_item, +X509_LOOKUP_meth_get_new_item, X509_LOOKUP_meth_set_free, +X509_LOOKUP_meth_get_free, X509_LOOKUP_meth_set_init, +X509_LOOKUP_meth_get_init, X509_LOOKUP_meth_set_shutdown, +X509_LOOKUP_meth_get_shutdown, +X509_LOOKUP_ctrl_fn, X509_LOOKUP_meth_set_ctrl, X509_LOOKUP_meth_get_ctrl, +X509_LOOKUP_get_by_subject_fn, X509_LOOKUP_meth_set_get_by_subject, +X509_LOOKUP_meth_get_get_by_subject, +X509_LOOKUP_get_by_issuer_serial_fn, X509_LOOKUP_meth_set_get_by_issuer_serial, +X509_LOOKUP_meth_get_get_by_issuer_serial, +X509_LOOKUP_get_by_fingerprint_fn, X509_LOOKUP_meth_set_get_by_fingerprint, +X509_LOOKUP_meth_get_get_by_fingerprint, +X509_LOOKUP_get_by_alias_fn, X509_LOOKUP_meth_set_get_by_alias, +X509_LOOKUP_meth_get_get_by_alias, +X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL +\&\- Routines to build up X509_LOOKUP methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef x509_lookup_method_st X509_LOOKUP_METHOD; +\& +\& X509_LOOKUP_METHOD *X509_LOOKUP_meth_new(const char *name); +\& void X509_LOOKUP_meth_free(X509_LOOKUP_METHOD *method); +\& +\& int X509_LOOKUP_meth_set_new_item(X509_LOOKUP_METHOD *method, +\& int (*new_item) (X509_LOOKUP *ctx)); +\& int (*X509_LOOKUP_meth_get_new_item(const X509_LOOKUP_METHOD* method)) +\& (X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_meth_set_free(X509_LOOKUP_METHOD *method, +\& void (*free) (X509_LOOKUP *ctx)); +\& void (*X509_LOOKUP_meth_get_free(const X509_LOOKUP_METHOD* method)) +\& (X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_meth_set_init(X509_LOOKUP_METHOD *method, +\& int (*init) (X509_LOOKUP *ctx)); +\& int (*X509_LOOKUP_meth_get_init(const X509_LOOKUP_METHOD* method)) +\& (X509_LOOKUP *ctx); +\& +\& int X509_LOOKUP_meth_set_shutdown(X509_LOOKUP_METHOD *method, +\& int (*shutdown) (X509_LOOKUP *ctx)); +\& int (*X509_LOOKUP_meth_get_shutdown(const X509_LOOKUP_METHOD* method)) +\& (X509_LOOKUP *ctx); +\& +\& typedef int (*X509_LOOKUP_ctrl_fn)(X509_LOOKUP *ctx, int cmd, const char *argc, +\& long argl, char **ret); +\& int X509_LOOKUP_meth_set_ctrl(X509_LOOKUP_METHOD *method, +\& X509_LOOKUP_ctrl_fn ctrl_fn); +\& X509_LOOKUP_ctrl_fn X509_LOOKUP_meth_get_ctrl(const X509_LOOKUP_METHOD *method); +\& +\& typedef int (*X509_LOOKUP_get_by_subject_fn)(X509_LOOKUP *ctx, +\& X509_LOOKUP_TYPE type, +\& const X509_NAME *name, +\& X509_OBJECT *ret); +\& int X509_LOOKUP_meth_set_get_by_subject(X509_LOOKUP_METHOD *method, +\& X509_LOOKUP_get_by_subject_fn fn); +\& X509_LOOKUP_get_by_subject_fn X509_LOOKUP_meth_get_get_by_subject( +\& const X509_LOOKUP_METHOD *method); +\& +\& typedef int (*X509_LOOKUP_get_by_issuer_serial_fn)(X509_LOOKUP *ctx, +\& X509_LOOKUP_TYPE type, +\& const X509_NAME *name, +\& const ASN1_INTEGER *serial, +\& X509_OBJECT *ret); +\& int X509_LOOKUP_meth_set_get_by_issuer_serial( +\& X509_LOOKUP_METHOD *method, X509_LOOKUP_get_by_issuer_serial_fn fn); +\& X509_LOOKUP_get_by_issuer_serial_fn X509_LOOKUP_meth_get_get_by_issuer_serial( +\& const X509_LOOKUP_METHOD *method); +\& +\& typedef int (*X509_LOOKUP_get_by_fingerprint_fn)(X509_LOOKUP *ctx, +\& X509_LOOKUP_TYPE type, +\& const unsigned char* bytes, +\& int len, +\& X509_OBJECT *ret); +\& int X509_LOOKUP_meth_set_get_by_fingerprint(X509_LOOKUP_METHOD *method, +\& X509_LOOKUP_get_by_fingerprint_fn fn); +\& X509_LOOKUP_get_by_fingerprint_fn X509_LOOKUP_meth_get_get_by_fingerprint( +\& const X509_LOOKUP_METHOD *method); +\& +\& typedef int (*X509_LOOKUP_get_by_alias_fn)(X509_LOOKUP *ctx, +\& X509_LOOKUP_TYPE type, +\& const char *str, +\& int len, +\& X509_OBJECT *ret); +\& int X509_LOOKUP_meth_set_get_by_alias(X509_LOOKUP_METHOD *method, +\& X509_LOOKUP_get_by_alias_fn fn); +\& X509_LOOKUP_get_by_alias_fn X509_LOOKUP_meth_get_get_by_alias( +\& const X509_LOOKUP_METHOD *method); +\& +\& int X509_OBJECT_set1_X509(X509_OBJECT *a, X509 *obj); +\& int X509_OBJECT_set1_X509_CRL(X509_OBJECT *a, X509_CRL *obj); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_LOOKUP_METHOD\fR type is a structure used for the implementation of new +X509_LOOKUP types. It provides a set of functions used by OpenSSL for the +implementation of various X509 and X509_CRL lookup capabilities. One instance +of an X509_LOOKUP_METHOD can be associated to many instantiations of an +\&\fBX509_LOOKUP\fR structure. +.PP +\&\fBX509_LOOKUP_meth_new()\fR creates a new \fBX509_LOOKUP_METHOD\fR structure. It should +be given a human\-readable string containing a brief description of the lookup +method. +.PP +\&\fBX509_LOOKUP_meth_free()\fR destroys a \fBX509_LOOKUP_METHOD\fR structure. +If the argument is NULL, nothing is done. +.PP +\&\fBX509_LOOKUP_get_new_item()\fR and \fBX509_LOOKUP_set_new_item()\fR get and set the +function that is called when an \fBX509_LOOKUP\fR object is created with +\&\fBX509_LOOKUP_new()\fR. If an X509_LOOKUP_METHOD requires any per\-X509_LOOKUP +specific data, the supplied new_item function should allocate this data and +invoke \fBX509_LOOKUP_set_method_data\fR\|(3). +.PP +\&\fBX509_LOOKUP_get_free()\fR and \fBX509_LOOKUP_set_free()\fR get and set the function +that is used to free any method data that was allocated and set from within +new_item function. +.PP +\&\fBX509_LOOKUP_meth_get_init()\fR and \fBX509_LOOKUP_meth_set_init()\fR get and set the +function that is used to initialize the method data that was set with +\&\fBX509_LOOKUP_set_method_data\fR\|(3) as part of the new_item routine. +.PP +\&\fBX509_LOOKUP_meth_get_shutdown()\fR and \fBX509_LOOKUP_meth_set_shutdown()\fR get and set +the function that is used to shut down the method data whose state was +previously initialized in the init function. +.PP +\&\fBX509_LOOKUP_meth_get_ctrl()\fR and \fBX509_LOOKUP_meth_set_ctrl()\fR get and set a +function to be used to handle arbitrary control commands issued by +\&\fBX509_LOOKUP_ctrl()\fR. The control function is given the X509_LOOKUP +\&\fBctx\fR, along with the arguments passed by X509_LOOKUP_ctrl. \fBcmd\fR is +an arbitrary integer that defines some operation. \fBargc\fR is a pointer +to an array of characters. \fBargl\fR is an integer. \fBret\fR, if set, +points to a location where any return data should be written to. How +\&\fBargc\fR and \fBargl\fR are used depends entirely on the control function. +.PP +\&\fBX509_LOOKUP_set_get_by_subject()\fR, \fBX509_LOOKUP_set_get_by_issuer_serial()\fR, +\&\fBX509_LOOKUP_set_get_by_fingerprint()\fR, \fBX509_LOOKUP_set_get_by_alias()\fR set +the functions used to retrieve an X509 or X509_CRL object by the object\*(Aqs +subject, issuer, fingerprint, and alias respectively. These functions are given +the X509_LOOKUP context, the type of the X509_OBJECT being requested, parameters +related to the lookup, and an X509_OBJECT that will receive the requested +object. +.PP +Implementations must add objects they find to the \fBX509_STORE\fR object +using \fBX509_STORE_add_cert()\fR or \fBX509_STORE_add_crl()\fR. This increments +its reference count. However, the \fBX509_STORE_CTX_get_by_subject\fR\|(3) +function also increases the reference count which leads to one too +many references being held. Therefore, applications should +additionally call \fBX509_free()\fR or \fBX509_CRL_free()\fR to decrement the +reference count again. +.PP +Implementations should also use either \fBX509_OBJECT_set1_X509()\fR or +\&\fBX509_OBJECT_set1_X509_CRL()\fR to set the result. Note that this also +increments the result\*(Aqs reference count. +.PP +Any method data that was created as a result of the new_item function +set by \fBX509_LOOKUP_meth_set_new_item()\fR can be accessed with +\&\fBX509_LOOKUP_get_method_data\fR\|(3). The \fBX509_STORE\fR object that owns the +X509_LOOKUP may be accessed with \fBX509_LOOKUP_get_store\fR\|(3). Successful +lookups should return 1, and unsuccessful lookups should return 0. +.PP +\&\fBX509_LOOKUP_get_get_by_subject()\fR, \fBX509_LOOKUP_get_get_by_issuer_serial()\fR, +\&\fBX509_LOOKUP_get_get_by_fingerprint()\fR, \fBX509_LOOKUP_get_get_by_alias()\fR retrieve +the function set by the corresponding setter. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBX509_LOOKUP_meth_set\fR functions return 1 on success or 0 on error. +.PP +The \fBX509_LOOKUP_meth_get\fR functions return the corresponding function +pointers. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_STORE_CTX_get_by_subject\fR\|(3), +\&\fBX509_STORE_new\fR\|(3), \fBSSL_CTX_set_cert_store\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions described here were added in OpenSSL 1.1.0i. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2018\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_NAME_ENTRY_get_object.3 b/static/netbsd/man3/X509_NAME_ENTRY_get_object.3 new file mode 100644 index 00000000..fdf3f715 --- /dev/null +++ b/static/netbsd/man3/X509_NAME_ENTRY_get_object.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: X509_NAME_ENTRY_get_object.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_NAME_ENTRY_get_object 3" +.TH X509_NAME_ENTRY_get_object 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, +X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data, +X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID, +X509_NAME_ENTRY_create_by_OBJ \- X509_NAME_ENTRY utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OBJECT *X509_NAME_ENTRY_get_object(const X509_NAME_ENTRY *ne); +\& ASN1_STRING *X509_NAME_ENTRY_get_data(const X509_NAME_ENTRY *ne); +\& +\& int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj); +\& int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, +\& const unsigned char *bytes, int len); +\& +\& X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, +\& int type, const unsigned char *bytes, +\& int len); +\& X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, +\& int type, const unsigned char *bytes, +\& int len); +\& X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, +\& const ASN1_OBJECT *obj, int type, +\& const unsigned char *bytes, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_NAME_ENTRY_get_object()\fR retrieves the field name of \fBne\fR in +and \fBASN1_OBJECT\fR structure. +.PP +\&\fBX509_NAME_ENTRY_get_data()\fR retrieves the field value of \fBne\fR in +and \fBASN1_STRING\fR structure. +.PP +\&\fBX509_NAME_ENTRY_set_object()\fR sets the field name of \fBne\fR to \fBobj\fR. +.PP +\&\fBX509_NAME_ENTRY_set_data()\fR sets the field value of \fBne\fR to string type +\&\fBtype\fR and value determined by \fBbytes\fR and \fBlen\fR. +.PP +\&\fBX509_NAME_ENTRY_create_by_txt()\fR, \fBX509_NAME_ENTRY_create_by_NID()\fR +and \fBX509_NAME_ENTRY_create_by_OBJ()\fR create and return an +\&\fBX509_NAME_ENTRY\fR structure. +.SH NOTES +.IX Header "NOTES" +\&\fBX509_NAME_ENTRY_get_object()\fR and \fBX509_NAME_ENTRY_get_data()\fR can be +used to examine an \fBX509_NAME_ENTRY\fR function as returned by +\&\fBX509_NAME_get_entry()\fR for example. +.PP +\&\fBX509_NAME_ENTRY_create_by_txt()\fR, \fBX509_NAME_ENTRY_create_by_OBJ()\fR, +\&\fBX509_NAME_ENTRY_create_by_NID()\fR and \fBX509_NAME_ENTRY_set_data()\fR +are seldom used in practice because \fBX509_NAME_ENTRY\fR structures +are almost always part of \fBX509_NAME\fR structures and the +corresponding \fBX509_NAME\fR functions are typically used to +create and add new entries in a single operation. +.PP +The arguments of these functions support similar options to the similarly +named ones of the corresponding \fBX509_NAME\fR functions such as +\&\fBX509_NAME_add_entry_by_txt()\fR. So for example \fBtype\fR can be set to +\&\fBMBSTRING_ASC\fR but in the case of \fBX509_set_data()\fR the field name must be +set first so the relevant field information can be looked up internally. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_NAME_ENTRY_get_object()\fR returns a valid \fBASN1_OBJECT\fR structure if it is +set or NULL if an error occurred. +.PP +\&\fBX509_NAME_ENTRY_get_data()\fR returns a valid \fBASN1_STRING\fR structure if it is set +or NULL if an error occurred. +.PP +\&\fBX509_NAME_ENTRY_set_object()\fR and \fBX509_NAME_ENTRY_set_data()\fR return 1 on success +or 0 on error. +.PP +\&\fBX509_NAME_ENTRY_create_by_txt()\fR, \fBX509_NAME_ENTRY_create_by_NID()\fR and +\&\fBX509_NAME_ENTRY_create_by_OBJ()\fR return a valid \fBX509_NAME_ENTRY\fR on success or +NULL if an error occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBd2i_X509_NAME\fR\|(3), +\&\fBOBJ_nid2obj\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_NAME_add_entry_by_txt.3 b/static/netbsd/man3/X509_NAME_add_entry_by_txt.3 new file mode 100644 index 00000000..2bd1dec8 --- /dev/null +++ b/static/netbsd/man3/X509_NAME_add_entry_by_txt.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: X509_NAME_add_entry_by_txt.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_NAME_add_entry_by_txt 3" +.TH X509_NAME_add_entry_by_txt 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID, +X509_NAME_add_entry, X509_NAME_delete_entry \- X509_NAME modification functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, +\& const unsigned char *bytes, int len, int loc, int set); +\& +\& int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, +\& const unsigned char *bytes, int len, int loc, int set); +\& +\& int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, +\& const unsigned char *bytes, int len, int loc, int set); +\& +\& int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set); +\& +\& X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_NAME_add_entry_by_txt()\fR, \fBX509_NAME_add_entry_by_OBJ()\fR and +\&\fBX509_NAME_add_entry_by_NID()\fR add a field whose name is defined +by a string \fBfield\fR, an object \fBobj\fR or a NID \fBnid\fR respectively. +The field value to be added is in \fBbytes\fR of length \fBlen\fR. If +\&\fBlen\fR is \-1 then the field length is calculated internally using +strlen(bytes). +.PP +The type of field is determined by \fBtype\fR which can either be a +definition of the type of \fBbytes\fR (such as \fBMBSTRING_ASC\fR) or a +standard ASN1 type (such as \fBV_ASN1_IA5STRING\fR). The new entry is +added to a position determined by \fBloc\fR and \fBset\fR. +.PP +\&\fBX509_NAME_add_entry()\fR adds a copy of \fBX509_NAME_ENTRY\fR structure \fBne\fR +to \fBname\fR. The new entry is added to a position determined by \fBloc\fR +and \fBset\fR. Since a copy of \fBne\fR is added \fBne\fR must be freed up after +the call. +.PP +\&\fBX509_NAME_delete_entry()\fR deletes an entry from \fBname\fR at position +\&\fBloc\fR. The deleted entry is returned and must be freed up. +.SH NOTES +.IX Header "NOTES" +The use of string types such as \fBMBSTRING_ASC\fR or \fBMBSTRING_UTF8\fR +is strongly recommended for the \fBtype\fR parameter. This allows the +internal code to correctly determine the type of the field and to +apply length checks according to the relevant standards. This is +done using \fBASN1_STRING_set_by_NID()\fR. +.PP +If instead an ASN1 type is used no checks are performed and the +supplied data in \fBbytes\fR is used directly. +.PP +In \fBX509_NAME_add_entry_by_txt()\fR the \fBfield\fR string represents +the field name using OBJ_txt2obj(field, 0). +.PP +The \fBloc\fR and \fBset\fR parameters determine where a new entry should +be added. For almost all applications \fBloc\fR can be set to \-1 and \fBset\fR +to 0. This adds a new entry to the end of \fBname\fR as a single valued +RelativeDistinguishedName (RDN). +.PP +\&\fBloc\fR actually determines the index where the new entry is inserted: +if it is \-1 it is appended. +.PP +\&\fBset\fR determines how the new type is added. +If it is zero a new RDN is created. +.PP +If \fBset\fR is \-1 or 1 it is added as a new set member +to the previous or next RDN structure, respectively. +This will then become part of a multi\-valued RDN (containing a set of AVAs). +Since multi\-valued RDNs are very rarely used \fBset\fR typically will be zero. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_NAME_add_entry_by_txt()\fR, \fBX509_NAME_add_entry_by_OBJ()\fR, +\&\fBX509_NAME_add_entry_by_NID()\fR and \fBX509_NAME_add_entry()\fR return 1 for +success of 0 if an error occurred. +.PP +\&\fBX509_NAME_delete_entry()\fR returns either the deleted \fBX509_NAME_ENTRY\fR +structure or \fBNULL\fR if an error occurred. +.SH EXAMPLES +.IX Header "EXAMPLES" +Create an \fBX509_NAME\fR structure: +.PP +"C=UK, O=Disorganized Organization, CN=Joe Bloggs" +.PP +.Vb 1 +\& X509_NAME *nm; +\& +\& nm = X509_NAME_new(); +\& if (nm == NULL) +\& /* Some error */ +\& if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, +\& "UK", \-1, \-1, 0)) +\& /* Error */ +\& if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, +\& "Disorganized Organization", \-1, \-1, 0)) +\& /* Error */ +\& if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, +\& "Joe Bloggs", \-1, \-1, 0)) +\& /* Error */ +.Ve +.SH BUGS +.IX Header "BUGS" +\&\fBtype\fR can still be set to \fBV_ASN1_APP_CHOOSE\fR to use a +different algorithm to determine field types. Since this form does +not understand multicharacter types, performs no length checks and +can result in invalid field types its use is strongly discouraged. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBd2i_X509_NAME\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_NAME_get0_der.3 b/static/netbsd/man3/X509_NAME_get0_der.3 new file mode 100644 index 00000000..dac34400 --- /dev/null +++ b/static/netbsd/man3/X509_NAME_get0_der.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: X509_NAME_get0_der.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_NAME_get0_der 3" +.TH X509_NAME_get0_der 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_get0_der \- get X509_NAME DER encoding +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_NAME_get0_der(const X509_NAME *nm, const unsigned char **pder, +\& size_t *pderlen); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The function \fBX509_NAME_get0_der()\fR returns an internal pointer to the +encoding of an \fBX509_NAME\fR structure in \fB*pder\fR and consisting of +\&\fB*pderlen\fR bytes. It is useful for applications that wish to examine +the encoding of an \fBX509_NAME\fR structure without copying it. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The function \fBX509_NAME_get0_der()\fR returns 1 for success and 0 if an error +occurred. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_NAME_get_index_by_NID.3 b/static/netbsd/man3/X509_NAME_get_index_by_NID.3 new file mode 100644 index 00000000..361255cc --- /dev/null +++ b/static/netbsd/man3/X509_NAME_get_index_by_NID.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: X509_NAME_get_index_by_NID.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_NAME_get_index_by_NID 3" +.TH X509_NAME_get_index_by_NID 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, +X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \- +X509_NAME lookup and enumeration functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos); +\& int X509_NAME_get_index_by_OBJ(const X509_NAME *name, +\& const ASN1_OBJECT *obj, int lastpos); +\& +\& int X509_NAME_entry_count(const X509_NAME *name); +\& X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc); +\& +\& int X509_NAME_get_text_by_NID(const X509_NAME *name, int nid, +\& char *buf, int len); +\& int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj, +\& char *buf, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions allow an \fBX509_NAME\fR structure to be examined. The +\&\fBX509_NAME\fR structure is the same as the \fBName\fR type defined in +RFC2459 (and elsewhere) and used for example in certificate subject +and issuer names. +.PP +\&\fBX509_NAME_get_index_by_NID()\fR and \fBX509_NAME_get_index_by_OBJ()\fR retrieve +the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR +should initially be set to \-1. If there are no more entries \-1 is returned. +If \fBnid\fR is invalid (doesn\*(Aqt correspond to a valid OID) then \-2 is returned. +.PP +\&\fBX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR. +.PP +\&\fBX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR +corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from +0 to (X509_NAME_entry_count(name) \- 1). The value returned is an +internal pointer which must not be freed. +.PP +\&\fBX509_NAME_get_text_by_NID()\fR, \fBX509_NAME_get_text_by_OBJ()\fR retrieve +the "text" from the first entry in \fBname\fR which matches \fBnid\fR or +\&\fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes +will be written and the text written to \fBbuf\fR will be null +terminated. The length of the output string written is returned +excluding the terminating null. If \fBbuf\fR is then the amount +of space needed in \fBbuf\fR (excluding the final null) is returned. +.SH NOTES +.IX Header "NOTES" +\&\fBX509_NAME_get_text_by_NID()\fR and \fBX509_NAME_get_text_by_OBJ()\fR should be +considered deprecated because they +have various limitations which make them +of minimal use in practice. They can only find the first matching +entry and will copy the contents of the field verbatim: this can +be highly confusing if the target is a multicharacter string type +like a BMPString or a UTF8String. +.PP +For a more general solution \fBX509_NAME_get_index_by_NID()\fR or +\&\fBX509_NAME_get_index_by_OBJ()\fR should be used followed by +\&\fBX509_NAME_get_entry()\fR on any matching indices and then the +various \fBX509_NAME_ENTRY\fR utility functions on the result. +.PP +The list of all relevant \fBNID_*\fR and \fBOBJ_* codes\fR can be found in +the source code header files \fI\fR and/or +\&\fI\fR. +.PP +Applications which could pass invalid NIDs to \fBX509_NAME_get_index_by_NID()\fR +should check for the return value of \-2. Alternatively the NID validity +can be determined first by checking OBJ_nid2obj(nid) is not NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_NAME_get_index_by_NID()\fR and \fBX509_NAME_get_index_by_OBJ()\fR +return the index of the next matching entry or \-1 if not found. +\&\fBX509_NAME_get_index_by_NID()\fR can also return \-2 if the supplied +NID is invalid. +.PP +\&\fBX509_NAME_entry_count()\fR returns the total number of entries, and 0 +for failure. +.PP +\&\fBX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the +requested entry or \fBNULL\fR if the index is invalid. +.SH EXAMPLES +.IX Header "EXAMPLES" +Process all entries: +.PP +.Vb 2 +\& int i; +\& X509_NAME_ENTRY *e; +\& +\& for (i = 0; i < X509_NAME_entry_count(nm); i++) { +\& e = X509_NAME_get_entry(nm, i); +\& /* Do something with e */ +\& } +.Ve +.PP +Process all commonName entries: +.PP +.Vb 2 +\& int lastpos = \-1; +\& X509_NAME_ENTRY *e; +\& +\& for (;;) { +\& lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); +\& if (lastpos == \-1) +\& break; +\& e = X509_NAME_get_entry(nm, lastpos); +\& /* Do something with e */ +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBd2i_X509_NAME\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_NAME_print_ex.3 b/static/netbsd/man3/X509_NAME_print_ex.3 new file mode 100644 index 00000000..67fc5ed5 --- /dev/null +++ b/static/netbsd/man3/X509_NAME_print_ex.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: X509_NAME_print_ex.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_NAME_print_ex 3" +.TH X509_NAME_print_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, +X509_NAME_oneline \- X509_NAME printing routines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, +\& int indent, unsigned long flags); +\& int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, +\& int indent, unsigned long flags); +\& char *X509_NAME_oneline(const X509_NAME *a, char *buf, int size); +\& int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_NAME_print_ex()\fR prints a human readable version of \fInm\fR to BIO \fIout\fR. +Each line (for multiline formats) is indented by \fIindent\fR spaces. The +output format can be extensively customised by use of the \fIflags\fR parameter. +.PP +\&\fBX509_NAME_print_ex_fp()\fR is identical to \fBX509_NAME_print_ex()\fR +except the output is written to FILE pointer \fIfp\fR. +.PP +\&\fBX509_NAME_oneline()\fR prints an ASCII version of \fIa\fR to \fIbuf\fR. +This supports multi\-valued RDNs and escapes \fB/\fR and \fB+\fR characters in values. +If \fIbuf\fR is \fBNULL\fR then a buffer is dynamically allocated and returned, and +\&\fIsize\fR is ignored. +Otherwise, at most \fIsize\fR bytes will be written, including the ending \*(Aq\e0\*(Aq, +and \fIbuf\fR is returned. +.PP +\&\fBX509_NAME_print()\fR prints out \fIname\fR to \fIbp\fR on a single line. +The \fIobase\fR parameter is ignored and retained only for API compatibility. +.SH NOTES +.IX Header "NOTES" +The functions \fBX509_NAME_oneline()\fR and \fBX509_NAME_print()\fR +produce a non standard output form, they don\*(Aqt handle multi\-character fields and +have various quirks and inconsistencies. +Their use is strongly discouraged in new applications and they could +be deprecated in a future release. +.PP +Although there are a large number of possible flags for most purposes +\&\fBXN_FLAG_ONELINE\fR, \fBXN_FLAG_MULTILINE\fR or \fBXN_FLAG_RFC2253\fR will suffice. +As noted on the \fBASN1_STRING_print_ex\fR\|(3) manual page +for UTF8 terminals the \fBASN1_STRFLGS_ESC_MSB\fR should be unset: so for example +\&\fBXN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB\fR would be used. +.PP +The complete set of the flags supported by \fBX509_NAME_print_ex()\fR is listed below. +.PP +Several options can be ored together. +.PP +The options \fBXN_FLAG_SEP_COMMA_PLUS\fR, \fBXN_FLAG_SEP_CPLUS_SPC\fR, +\&\fBXN_FLAG_SEP_SPLUS_SPC\fR and \fBXN_FLAG_SEP_MULTILINE\fR +determine the field separators to use. +Two distinct separators are used between distinct RelativeDistinguishedName +components and separate values in the same RDN for a multi\-valued RDN. +Multi\-valued RDNs are currently very rare +so the second separator will hardly ever be used. +.PP +\&\fBXN_FLAG_SEP_COMMA_PLUS\fR uses comma and plus as separators. +\&\fBXN_FLAG_SEP_CPLUS_SPC\fR uses comma and plus with spaces: +this is more readable that plain comma and plus. +\&\fBXN_FLAG_SEP_SPLUS_SPC\fR uses spaced semicolon and plus. +\&\fBXN_FLAG_SEP_MULTILINE\fR uses spaced newline and plus respectively. +.PP +If \fBXN_FLAG_DN_REV\fR is set the whole DN is printed in reversed order. +.PP +The fields \fBXN_FLAG_FN_SN\fR, \fBXN_FLAG_FN_LN\fR, \fBXN_FLAG_FN_OID\fR, +\&\fBXN_FLAG_FN_NONE\fR determine how a field name is displayed. It will +use the short name (e.g. CN) the long name (e.g. commonName) always +use OID numerical form (normally OIDs are only used if the field name is not +recognised) and no field name respectively. +.PP +If \fBXN_FLAG_SPC_EQ\fR is set then spaces will be placed around the \*(Aq=\*(Aq character +separating field names and values. +.PP +If \fBXN_FLAG_DUMP_UNKNOWN_FIELDS\fR is set then the encoding of unknown fields is +printed instead of the values. +.PP +If \fBXN_FLAG_FN_ALIGN\fR is set then field names are padded to 20 characters: this +is only of use for multiline format. +.PP +Additionally all the options supported by \fBASN1_STRING_print_ex()\fR can be used to +control how each field value is displayed. +.PP +In addition a number options can be set for commonly used formats. +.PP +\&\fBXN_FLAG_RFC2253\fR sets options which produce an output compatible with RFC2253. +It is equivalent to: + \f(CW\*(C`ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV + | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS\*(C'\fR +.PP +\&\fBXN_FLAG_ONELINE\fR is a more readable one line format which is the same as: + \f(CW\*(C`ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC + | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN\*(C'\fR +.PP +\&\fBXN_FLAG_MULTILINE\fR is a multiline format which is the same as: + \f(CW\*(C`ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE + | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN\*(C'\fR +.PP +\&\fBXN_FLAG_COMPAT\fR uses a format identical to \fBX509_NAME_print()\fR: +in fact it calls \fBX509_NAME_print()\fR internally. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_NAME_oneline()\fR returns a valid string on success or NULL on error. +.PP +\&\fBX509_NAME_print()\fR returns 1 on success or 0 on error. +.PP +\&\fBX509_NAME_print_ex()\fR and \fBX509_NAME_print_ex_fp()\fR return 1 on success or 0 on +error if the \fBXN_FLAG_COMPAT\fR is set, which is the same as \fBX509_NAME_print()\fR. +Otherwise, it returns \-1 on error or other values on success. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBASN1_STRING_print_ex\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_PUBKEY_new.3 b/static/netbsd/man3/X509_PUBKEY_new.3 new file mode 100644 index 00000000..18a4630b --- /dev/null +++ b/static/netbsd/man3/X509_PUBKEY_new.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: X509_PUBKEY_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_PUBKEY_new 3" +.TH X509_PUBKEY_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_PUBKEY_new_ex, X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup, +X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get, +d2i_PUBKEY_ex, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_ex_bio, d2i_PUBKEY_bio, +d2i_PUBKEY_ex_fp, d2i_PUBKEY_fp, i2d_PUBKEY_fp, i2d_PUBKEY_bio, +X509_PUBKEY_set0_public_key, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param, +X509_PUBKEY_eq \- SubjectPublicKeyInfo public key functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_PUBKEY *X509_PUBKEY_new_ex(OSSL_LIB_CTX *libctx, const char *propq); +\& X509_PUBKEY *X509_PUBKEY_new(void); +\& void X509_PUBKEY_free(X509_PUBKEY *a); +\& X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a); +\& +\& int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); +\& EVP_PKEY *X509_PUBKEY_get0(const X509_PUBKEY *key); +\& EVP_PKEY *X509_PUBKEY_get(const X509_PUBKEY *key); +\& +\& EVP_PKEY *d2i_PUBKEY_ex(EVP_PKEY **a, const unsigned char **pp, long length, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); +\& int i2d_PUBKEY(const EVP_PKEY *a, unsigned char **pp); +\& +\& EVP_PKEY *d2i_PUBKEY_ex_bio(BIO *bp, EVP_PKEY **a, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); +\& +\& EVP_PKEY *d2i_PUBKEY_ex_fp(FILE *fp, EVP_PKEY **a, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); +\& +\& int i2d_PUBKEY_fp(const FILE *fp, EVP_PKEY *pkey); +\& int i2d_PUBKEY_bio(BIO *bp, const EVP_PKEY *pkey); +\& +\& void X509_PUBKEY_set0_public_key(X509_PUBKEY *pub, +\& unsigned char *penc, int penclen); +\& int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, +\& int ptype, void *pval, +\& unsigned char *penc, int penclen); +\& int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, +\& const unsigned char **pk, int *ppklen, +\& X509_ALGOR **pa, const X509_PUBKEY *pub); +\& int X509_PUBKEY_eq(X509_PUBKEY *a, X509_PUBKEY *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_PUBKEY\fR structure represents the ASN.1 \fBSubjectPublicKeyInfo\fR +structure defined in RFC5280 and used in certificates and certificate requests. +.PP +\&\fBX509_PUBKEY_new_ex()\fR allocates and initializes an \fBX509_PUBKEY\fR structure +associated with the given \fBOSSL_LIB_CTX\fR in the \fIlibctx\fR parameter. Any +algorithm fetches associated with using the \fBX509_PUBKEY\fR object will use +the property query string \fIpropq\fR. See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for +further information about algorithm fetching. +.PP +\&\fBX509_PUBKEY_new()\fR is the same as \fBX509_PUBKEY_new_ex()\fR except that the default +(NULL) \fBOSSL_LIB_CTX\fR and a NULL property query string are used. +.PP +\&\fBX509_PUBKEY_dup()\fR creates a duplicate copy of the \fBX509_PUBKEY\fR object +specified by \fIa\fR. +.PP +\&\fBX509_PUBKEY_free()\fR frees up \fBX509_PUBKEY\fR structure \fIa\fR. If \fIa\fR is NULL +nothing is done. +.PP +\&\fBX509_PUBKEY_set()\fR sets the public key in \fI*x\fR to the public key contained +in the \fBEVP_PKEY\fR structure \fIpkey\fR. If \fI*x\fR is not NULL any existing +public key structure will be freed. +.PP +\&\fBX509_PUBKEY_get0()\fR returns the public key contained in \fIkey\fR. The returned +value is an internal pointer which \fBMUST NOT\fR be freed after use. +.PP +\&\fBX509_PUBKEY_get()\fR is similar to \fBX509_PUBKEY_get0()\fR except the reference +count on the returned key is incremented so it \fBMUST\fR be freed using +\&\fBEVP_PKEY_free()\fR after use. +.PP +\&\fBd2i_PUBKEY_ex()\fR decodes an \fBEVP_PKEY\fR structure using \fBSubjectPublicKeyInfo\fR +format. Some public key decoding implementations may use cryptographic +algorithms. In this case the supplied library context \fIlibctx\fR and property +query string \fIpropq\fR are used. +\&\fBd2i_PUBKEY()\fR does the same as \fBd2i_PUBKEY_ex()\fR except that the default +library context and property query string are used. +.PP +\&\fBi2d_PUBKEY()\fR encodes an \fBEVP_PKEY\fR structure using \fBSubjectPublicKeyInfo\fR +format. +.PP +\&\fBd2i_PUBKEY_bio()\fR, \fBd2i_PUBKEY_fp()\fR, \fBi2d_PUBKEY_bio()\fR and \fBi2d_PUBKEY_fp()\fR are +similar to \fBd2i_PUBKEY()\fR and \fBi2d_PUBKEY()\fR except they decode or encode using a +\&\fBBIO\fR or \fBFILE\fR pointer. +.PP +\&\fBd2i_PUBKEY_ex_bio()\fR and \fBd2i_PUBKEY_ex_fp()\fR are similar to \fBd2i_PUBKEY_ex()\fR except +they decode using a \fBBIO\fR or \fBFILE\fR pointer. +.PP +\&\fBX509_PUBKEY_set0_public_key()\fR sets the public\-key encoding of \fIpub\fR +to the \fIpenclen\fR bytes contained in buffer \fIpenc\fR. +Any earlier public\-key encoding in \fIpub\fR is freed. +\&\fIpenc\fR may be NULL to indicate that there is no actual public key data. +Ownership of the \fIpenc\fR argument is passed to \fIpub\fR. +.PP +\&\fBX509_PUBKEY_set0_param()\fR sets the public\-key parameters of \fIpub\fR. +The OID associated with the algorithm is set to \fIaobj\fR. The type of the +algorithm parameters is set to \fItype\fR using the structure \fIpval\fR. +If \fIpenc\fR is not NULL the encoding of the public key itself is set +to the \fIpenclen\fR bytes contained in buffer \fIpenc\fR and +any earlier public\-key encoding in \fIpub\fR is freed. +On success ownership of all the supplied arguments is passed to \fIpub\fR +so they must not be freed after the call. +.PP +\&\fBX509_PUBKEY_get0_param()\fR retrieves the public key parameters from \fIpub\fR, +\&\fI*ppkalg\fR is set to the associated OID and the encoding consists of +\&\fI*ppklen\fR bytes at \fI*pk\fR, \fI*pa\fR is set to the associated +AlgorithmIdentifier for the public key. If the value of any of these +parameters is not required it can be set to NULL. All of the +retrieved pointers are internal and must not be freed after the +call. +.PP +\&\fBX509_PUBKEY_eq()\fR compares two \fBX509_PUBKEY\fR values. +.SH NOTES +.IX Header "NOTES" +The \fBX509_PUBKEY\fR functions can be used to encode and decode public keys +in a standard format. +.PP +In many cases applications will not call the \fBX509_PUBKEY\fR functions +directly: they will instead call wrapper functions such as \fBX509_get0_pubkey()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBX509_PUBKEY_new()\fR and \fBX509_PUBKEY_dup()\fR return +NULL and set an error code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise they return a pointer to the newly allocated structure. +.PP +\&\fBX509_PUBKEY_free()\fR does not return a value. +.PP +\&\fBX509_PUBKEY_get0()\fR, \fBX509_PUBKEY_get()\fR, \fBd2i_PUBKEY_ex()\fR, \fBd2i_PUBKEY()\fR, +\&\fBd2i_PUBKEY_ex_bio()\fR, \fBd2i_PUBKEY_bio()\fR, \fBd2i_PUBKEY_ex_fp()\fR and \fBd2i_PUBKEY_fp()\fR +return a pointer to an \fBEVP_PKEY\fR structure or NULL if an error occurs. +.PP +\&\fBi2d_PUBKEY()\fR returns the number of bytes successfully encoded or a +negative value if an error occurs. +.PP +\&\fBi2d_PUBKEY_fp()\fR and \fBi2d_PUBKEY_bio()\fR return 1 if successfully +encoded or 0 if an error occurs. +.PP +\&\fBX509_PUBKEY_set0_public_key()\fR does not return a value. +.PP +\&\fBX509_PUBKEY_set()\fR, \fBX509_PUBKEY_set0_param()\fR and \fBX509_PUBKEY_get0_param()\fR +return 1 for success and 0 if an error occurred. +.PP +\&\fBX509_PUBKEY_eq()\fR returns 1 for equal, 0 for different, and < 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_PUBKEY_new_ex()\fR and \fBX509_PUBKEY_eq()\fR functions were added in OpenSSL +3.0. +.PP +The \fBX509_PUBKEY_set0_public_key()\fR, \fBd2i_PUBKEY_ex_bio()\fR and \fBd2i_PUBKEY_ex_fp()\fR +functions were added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_REQ_get_attr.3 b/static/netbsd/man3/X509_REQ_get_attr.3 new file mode 100644 index 00000000..084b89ff --- /dev/null +++ b/static/netbsd/man3/X509_REQ_get_attr.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: X509_REQ_get_attr.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_REQ_get_attr 3" +.TH X509_REQ_get_attr 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_REQ_get_attr_count, +X509_REQ_get_attr_by_NID, X509_REQ_get_attr_by_OBJ, X509_REQ_get_attr, +X509_REQ_delete_attr, +X509_REQ_add1_attr, X509_REQ_add1_attr_by_OBJ, X509_REQ_add1_attr_by_NID, +X509_REQ_add1_attr_by_txt +\&\- X509_ATTRIBUTE support for signed certificate requests +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_REQ_get_attr_count(const X509_REQ *req); +\& int X509_REQ_get_attr_by_NID(const X509_REQ *req, int nid, int lastpos); +\& int X509_REQ_get_attr_by_OBJ(const X509_REQ *req, const ASN1_OBJECT *obj, +\& int lastpos); +\& X509_ATTRIBUTE *X509_REQ_get_attr(const X509_REQ *req, int loc); +\& X509_ATTRIBUTE *X509_REQ_delete_attr(X509_REQ *req, int loc); +\& int X509_REQ_add1_attr(X509_REQ *req, X509_ATTRIBUTE *attr); +\& int X509_REQ_add1_attr_by_OBJ(X509_REQ *req, +\& const ASN1_OBJECT *obj, int type, +\& const unsigned char *bytes, int len); +\& int X509_REQ_add1_attr_by_NID(X509_REQ *req, +\& int nid, int type, +\& const unsigned char *bytes, int len); +\& int X509_REQ_add1_attr_by_txt(X509_REQ *req, +\& const char *attrname, int type, +\& const unsigned char *bytes, int len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_REQ_get_attr_by_OBJ()\fR finds the location of the first matching object \fIobj\fR +in the \fIreq\fR attribute list. The search starts at the position after \fIlastpos\fR. +If the returned value is positive then it can be used on the next call to +\&\fBX509_REQ_get_attr_by_OBJ()\fR as the value of \fIlastpos\fR in order to iterate through +the remaining attributes. \fIlastpos\fR can be set to any negative value on the +first call, in order to start searching from the start of the attribute list. +.PP +\&\fBX509_REQ_get_attr_by_NID()\fR is similar to \fBX509_REQ_get_attr_by_OBJ()\fR except that +it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBX509_REQ_get_attr()\fR returns the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in the +\&\fIreq\fR attribute list. \fIloc\fR should be in the range from 0 to +\&\fBX509_REQ_get_attr_count()\fR \- 1. +.PP +\&\fBX509_REQ_delete_attr()\fR removes the \fBX509_ATTRIBUTE\fR object at index \fIloc\fR in +the \fIreq\fR objects list of attributes. An error occurs if \fIreq\fR is NULL. +.PP +\&\fBX509_REQ_add1_attr()\fR pushes a copy of the passed in \fBX509_ATTRIBUTE\fR \fRattr> +to the \fIreq\fR object\*(Aqs attribute list. An error will occur if either the +attribute list is NULL or the attribute already exists. +.PP +\&\fBX509_REQ_add1_attr_by_OBJ()\fR creates a new \fBX509_ATTRIBUTE\fR using +\&\fBX509_ATTRIBUTE_set1_object()\fR and \fBX509_ATTRIBUTE_set1_data()\fR to assign a new +\&\fIobj\fR with type \fItype\fR and data \fIbytes\fR of length \fIlen\fR and then pushes it +to the \fIreq\fR object\*(Aqs attribute list. \fIreq\fR must be non NULL or an error +will occur. If \fIobj\fR already exists in the attribute list then an error occurs. +.PP +\&\fBX509_REQ_add1_attr_by_NID()\fR is similar to \fBX509_REQ_add1_attr_by_OBJ()\fR except +that it passes the numerical identifier (NID) \fInid\fR associated with the object. +See for a list of NID_*. +.PP +\&\fBX509_REQ_add1_attr_by_txt()\fR is similar to \fBX509_REQ_add1_attr_by_OBJ()\fR except +that it passes a name \fIattrname\fR associated with the object. +See for a list of SN_* names. +.PP +Refer to \fBX509_ATTRIBUTE\fR\|(3) for information related to attributes. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_REQ_get_attr_count()\fR returns the number of attributes in the \fIreq\fR object +attribute list or \-1 if the attribute list is NULL. +.PP +\&\fBX509_REQ_get_attr_by_OBJ()\fR returns \-1 if either the \fIreq\fR object\*(Aqs attribute +list is empty OR \fIobj\fR is not found, otherwise it returns the location of the +\&\fIobj\fR in the attribute list. +.PP +\&\fBX509_REQ_get_attr_by_NID()\fR is similar to \fBX509_REQ_get_attr_by_OBJ()\fR, except that +it returns \-2 if the \fInid\fR is not known by OpenSSL. +.PP +\&\fBX509_REQ_get_attr()\fR returns either an \fBX509_ATTRIBUTE\fR or NULL on error. +.PP +\&\fBX509_REQ_delete_attr()\fR returns either the removed \fBX509_ATTRIBUTE\fR or NULL if +there is a error. +.PP +\&\fBX509_REQ_add1_attr()\fR, \fBX509_REQ_add1_attr_by_OBJ()\fR, \fBX509_REQ_add1_attr_by_NID()\fR +and \fBX509_REQ_add1_attr_by_txt()\fR return 1 on success or 0 on error. +.SH NOTES +.IX Header "NOTES" +Any functions that modify the attributes (add or delete) internally set a flag +to indicate the ASN.1 encoding has been modified. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_ATTRIBUTE\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_REQ_get_extensions.3 b/static/netbsd/man3/X509_REQ_get_extensions.3 new file mode 100644 index 00000000..d44f8424 --- /dev/null +++ b/static/netbsd/man3/X509_REQ_get_extensions.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: X509_REQ_get_extensions.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_REQ_get_extensions 3" +.TH X509_REQ_get_extensions 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_REQ_get_extensions, +X509_REQ_add_extensions, X509_REQ_add_extensions_nid +\&\- handle X.509 extension attributes of a CSR +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509_EXTENSION) *X509_REQ_get_extensions(const X509_REQ *req); +\& int X509_REQ_add_extensions(X509_REQ *req, const STACK_OF(X509_EXTENSION) *exts); +\& int X509_REQ_add_extensions_nid(X509_REQ *req, +\& const STACK_OF(X509_EXTENSION) *exts, int nid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_REQ_get_extensions()\fR returns the first list of X.509 extensions +found in the attributes of \fIreq\fR. +The returned list is empty if there are no such extensions in \fIreq\fR. +The caller is responsible for freeing the list obtained. +.PP +\&\fBX509_REQ_add_extensions_nid()\fR adds to \fIreq\fR a list of X.509 extensions \fIexts\fR, +using \fInid\fR to identify the extensions attribute. +\&\fIreq\fR is unchanged if \fIexts\fR is NULL or an empty list. +This function may be called more than once on the same \fIreq\fR and \fInid\fR. +In such case any previous extensions are augmented, where an extension to be +added that has the same OID as a pre\-existing one replaces this earlier one. +.PP +\&\fBX509_REQ_add_extensions()\fR is like \fBX509_REQ_add_extensions_nid()\fR +except that the default \fBNID_ext_req\fR is used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_REQ_get_extensions()\fR returns a pointer to \fBSTACK_OF(X509_EXTENSION)\fR +or NULL on error. +.PP +\&\fBX509_REQ_add_extensions()\fR and \fBX509_REQ_add_extensions_nid()\fR +return 1 on success, 0 on error. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_SIG_get0.3 b/static/netbsd/man3/X509_SIG_get0.3 new file mode 100644 index 00000000..0559302f --- /dev/null +++ b/static/netbsd/man3/X509_SIG_get0.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: X509_SIG_get0.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_SIG_get0 3" +.TH X509_SIG_get0 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_SIG_get0, X509_SIG_getm \- DigestInfo functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **palg, +\& const ASN1_OCTET_STRING **pdigest); +\& void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **palg, +\& ASN1_OCTET_STRING **pdigest); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_SIG_get0()\fR returns pointers to the algorithm identifier and digest +value in \fBsig\fR. \fBX509_SIG_getm()\fR is identical to \fBX509_SIG_get0()\fR +except the pointers returned are not constant and can be modified: +for example to initialise them. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_SIG_get0()\fR and \fBX509_SIG_getm()\fR return no values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_CTX_get_by_subject.3 b/static/netbsd/man3/X509_STORE_CTX_get_by_subject.3 new file mode 100644 index 00000000..d9f6b832 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_CTX_get_by_subject.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: X509_STORE_CTX_get_by_subject.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_CTX_get_by_subject 3" +.TH X509_STORE_CTX_get_by_subject 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_CTX_get_by_subject, +X509_STORE_CTX_get_obj_by_subject +\&\- X509 and X509_CRL lookup functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_STORE_CTX_get_by_subject(const X509_STORE_CTX *vs, +\& X509_LOOKUP_TYPE type, +\& const X509_NAME *name, X509_OBJECT *ret); +\& X509_OBJECT *X509_STORE_CTX_get_obj_by_subject(X509_STORE_CTX *vs, +\& X509_LOOKUP_TYPE type, +\& const X509_NAME *name); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_STORE_CTX_get_by_subject()\fR tries to find an object +of given \fItype\fR, which may be \fBX509_LU_X509\fR or \fBX509_LU_CRL\fR, +and subject \fIname\fR from the store in the provided store context \fIvs\fR. +If found and \fIret\fR is not NULL, it increments the reference count and +stores the looked up object in \fIret\fR. +.PP +\&\fBX509_STORE_CTX_get_obj_by_subject()\fR is like \fBX509_STORE_CTX_get_by_subject()\fR +but returns the found object on success, else NULL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_CTX_get_by_subject()\fR returns 1 if the lookup was successful, else 0. +.PP +\&\fBX509_STORE_CTX_get_obj_by_subject()\fR returns an object on success, else NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_LOOKUP_meth_set_get_by_subject\fR\|(3), +\&\fBX509_LOOKUP_by_subject\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_CTX_get_error.3 b/static/netbsd/man3/X509_STORE_CTX_get_error.3 new file mode 100644 index 00000000..4d1ab841 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_CTX_get_error.3 @@ -0,0 +1,460 @@ +.\" $NetBSD: X509_STORE_CTX_get_error.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_CTX_get_error 3" +.TH X509_STORE_CTX_get_error 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, +X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth, +X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert, +X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain, +X509_verify_cert_error_string \- get or set certificate verification status +information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_STORE_CTX_get_error(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s); +\& int X509_STORE_CTX_get_error_depth(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth); +\& X509 *X509_STORE_CTX_get_current_cert(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x); +\& X509 *X509_STORE_CTX_get0_cert(const X509_STORE_CTX *ctx); +\& +\& STACK_OF(X509) *X509_STORE_CTX_get1_chain(const X509_STORE_CTX *ctx); +\& +\& const char *X509_verify_cert_error_string(long n); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions are typically called after certificate or chain verification +using \fBX509_verify_cert\fR\|(3) or \fBX509_STORE_CTX_verify\fR\|(3) has indicated +an error or in a verification callback to determine the nature of an error. +.PP +\&\fBX509_STORE_CTX_get_error()\fR returns the error code of \fIctx\fR. \fIctx\fR \fBMUST NOT\fR be NULL. +See the "ERROR CODES" section for a full description of all error codes. +It may return a code != X509_V_OK even if \fBX509_verify_cert()\fR did not indicate +an error, likely because a verification callback function has waived the error. +.PP +\&\fBX509_STORE_CTX_set_error()\fR sets the error code of \fIctx\fR to \fIs\fR. For example +it might be used in a verification callback to set an error based on additional +checks. \fIctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBX509_STORE_CTX_get_error_depth()\fR returns the \fIdepth\fR of the error. This is a +nonnegative integer representing where in the certificate chain the error +occurred. If it is zero it occurred in the end entity certificate, one if +it is the certificate which signed the end entity certificate and so on. +\&\fIctx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBX509_STORE_CTX_set_error_depth()\fR sets the error \fIdepth\fR. +This can be used in combination with \fBX509_STORE_CTX_set_error()\fR to set the +depth at which an error condition was detected. +.PP +\&\fBX509_STORE_CTX_get_current_cert()\fR returns the current certificate in +\&\fIctx\fR. If an error occurred, the current certificate will be the one +that is most closely related to the error, or possibly NULL if no such +certificate is relevant. +.PP +\&\fBX509_STORE_CTX_set_current_cert()\fR sets the certificate \fIx\fR in \fIctx\fR which +caused the error. +This value is not intended to remain valid for very long, and remains owned by +the caller. +It may be examined by a verification callback invoked to handle each error +encountered during chain verification and is no longer required after such a +callback. +If a callback wishes the save the certificate for use after it returns, it +needs to increment its reference count via \fBX509_up_ref\fR\|(3). +Once such a \fIsaved\fR certificate is no longer needed it can be freed with +\&\fBX509_free\fR\|(3). +.PP +\&\fBX509_STORE_CTX_get0_cert()\fR retrieves an internal pointer to the +certificate being verified by the \fIctx\fR. It may be NULL if a raw public +key is being verified. +.PP +\&\fBX509_STORE_CTX_get1_chain()\fR returns a complete validate chain if a previous +verification is successful. Otherwise the returned chain may be incomplete or +invalid. The returned chain persists after the \fIctx\fR structure is freed. +When it is no longer needed it should be free up using: +.PP +.Vb 1 +\& OSSL_STACK_OF_X509_free(chain); +.Ve +.PP +\&\fBX509_verify_cert_error_string()\fR returns a human readable error string for +verification error \fIn\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_CTX_get_error()\fR returns \fBX509_V_OK\fR or an error code. +.PP +\&\fBX509_STORE_CTX_get_error_depth()\fR returns a nonnegative error depth. +.PP +\&\fBX509_STORE_CTX_get_current_cert()\fR returns the certificate which caused the +error or NULL if no certificate is relevant to the error. +.PP +\&\fBX509_verify_cert_error_string()\fR returns a human readable error string for +verification error \fIn\fR. +.SH "ERROR CODES" +.IX Header "ERROR CODES" +A list of error codes and messages is shown below. Some of the +error codes are defined but currently never returned: these are described as +"unused". +.IP "\fBX509_V_OK: ok\fR" 4 +.IX Item "X509_V_OK: ok" +The operation was successful. +.IP "\fBX509_V_ERR_UNSPECIFIED: unspecified certificate verification error\fR" 4 +.IX Item "X509_V_ERR_UNSPECIFIED: unspecified certificate verification error" +Unspecified error; should not happen. +.IP "\fBX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate" +The issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. +To allow any certificate (not only a self\-signed one) in the trust store +to terminate the chain the \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag may be set. +.IP "\fBX509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL" +The CRL of a certificate could not be found. +.IP "\fBX509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate\*(Aqs signature\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature" +The certificate signature could not be decrypted. This means that the actual +signature value could not be determined rather than it not matching the +expected value, this is only meaningful for RSA keys. +.IP "\fBX509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL\*(Aqs signature\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature" +The CRL signature could not be decrypted: this means that the actual signature +value could not be determined rather than it not matching the expected value. +Unused. +.IP "\fBX509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key" +The public key in the certificate \f(CW\*(C`SubjectPublicKeyInfo\*(C'\fR field could +not be read. +.IP "\fBX509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure\fR" 4 +.IX Item "X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure" +The signature of the certificate is invalid. +.IP "\fBX509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure\fR" 4 +.IX Item "X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure" +The signature of the CRL is invalid. +.IP "\fBX509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid\fR" 4 +.IX Item "X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid" +The certificate is not yet valid: the \f(CW\*(C`notBefore\*(C'\fR date is after the +current time. +.IP "\fBX509_V_ERR_CERT_HAS_EXPIRED: certificate has expired\fR" 4 +.IX Item "X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired" +The certificate has expired: that is the \f(CW\*(C`notAfter\*(C'\fR date is before the +current time. +.IP "\fBX509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid\fR" 4 +.IX Item "X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid" +The CRL is not yet valid. +.IP "\fBX509_V_ERR_CRL_HAS_EXPIRED: CRL has expired\fR" 4 +.IX Item "X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired" +The CRL has expired. +.IP "\fBX509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate\*(Aqs notBefore field\fR" 4 +.IX Item "X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field" +The certificate \f(CW\*(C`notBefore\*(C'\fR field contains an invalid time. +.IP "\fBX509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate\*(Aqs notAfter field\fR" 4 +.IX Item "X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field" +The certificate \f(CW\*(C`notAfter\*(C'\fR field contains an invalid time. +.IP "\fBX509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL\*(Aqs lastUpdate field\fR" 4 +.IX Item "X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field" +The CRL \fBlastUpdate\fR field contains an invalid time. +.IP "\fBX509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL\*(Aqs nextUpdate field\fR" 4 +.IX Item "X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field" +The CRL \f(CW\*(C`nextUpdate\*(C'\fR field contains an invalid time. +.IP "\fBX509_V_ERR_OUT_OF_MEM: out of memory\fR" 4 +.IX Item "X509_V_ERR_OUT_OF_MEM: out of memory" +An error occurred trying to allocate memory. +.IP "\fBX509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self\-signed certificate\fR" 4 +.IX Item "X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate" +The passed certificate is self\-signed and the same certificate cannot be found +in the list of trusted certificates. +.IP "\fBX509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self\-signed certificate in certificate chain\fR" 4 +.IX Item "X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self-signed certificate in certificate chain" +The certificate chain could be built up using the untrusted certificates +but no suitable trust anchor (which typically is a self\-signed root certificate) +could be found in the trust store. +.IP "\fBX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate" +The issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. +.IP "\fBX509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate" +No signatures could be verified because the chain contains only one certificate +and it is not self\-signed and the \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag is not set. +.IP "\fBX509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long\fR" 4 +.IX Item "X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long" +The certificate chain length is greater than the supplied maximum depth. +.IP "\fBX509_V_ERR_CERT_REVOKED: certificate revoked\fR" 4 +.IX Item "X509_V_ERR_CERT_REVOKED: certificate revoked" +The certificate has been revoked. +.IP "\fBX509_V_ERR_NO_ISSUER_PUBLIC_KEY: issuer certificate doesn\*(Aqt have a public key\fR" 4 +.IX Item "X509_V_ERR_NO_ISSUER_PUBLIC_KEY: issuer certificate doesn't have a public key" +The issuer certificate does not have a public key. +.IP "\fBX509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded\fR" 4 +.IX Item "X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded" +The basicConstraints path\-length parameter has been exceeded. +.IP "\fBX509_V_ERR_INVALID_PURPOSE: unsuitable certificate purpose\fR" 4 +.IX Item "X509_V_ERR_INVALID_PURPOSE: unsuitable certificate purpose" +The target certificate cannot be used for the specified purpose. +.IP "\fBX509_V_ERR_CERT_UNTRUSTED: certificate not trusted\fR" 4 +.IX Item "X509_V_ERR_CERT_UNTRUSTED: certificate not trusted" +The root CA is not marked as trusted for the specified purpose. +.IP "\fBX509_V_ERR_CERT_REJECTED: certificate rejected\fR" 4 +.IX Item "X509_V_ERR_CERT_REJECTED: certificate rejected" +The root CA is marked to reject the specified purpose. +.IP "\fBX509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch\fR" 4 +.IX Item "X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch" +The current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. +.IP "\fBX509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch\fR" 4 +.IX Item "X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch" +The current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. +.IP "\fBX509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch\fR" 4 +.IX Item "X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch" +The current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier of +the current certificate. +.IP "\fBX509_V_ERR_KEYUSAGE_NO_CERTSIGN: key usage does not include certificate signing\fR" 4 +.IX Item "X509_V_ERR_KEYUSAGE_NO_CERTSIGN: key usage does not include certificate signing" +The current candidate issuer certificate was rejected because its \f(CW\*(C`keyUsage\*(C'\fR +extension does not permit certificate signing. +.IP "\fBX509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate\fR" 4 +.IX Item "X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate" +Unable to get CRL issuer certificate. +.IP "\fBX509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension\fR" 4 +.IX Item "X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension" +Unhandled critical extension. +.IP "\fBX509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing\fR" 4 +.IX Item "X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing" +Key usage does not include CRL signing. +.IP "\fBX509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension\fR" 4 +.IX Item "X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension" +Unhandled critical CRL extension. +.IP "\fBX509_V_ERR_INVALID_NON_CA: invalid non\-CA certificate (has CA markings)\fR" 4 +.IX Item "X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)" +Invalid non\-CA certificate has CA markings. +.IP "\fBX509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint exceeded\fR" 4 +.IX Item "X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint exceeded" +Proxy path length constraint exceeded. +.IP "\fBX509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature\fR" 4 +.IX Item "X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature" +Key usage does not include digital signature, and therefore cannot sign +certificates. +.IP "\fBX509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag\fR" 4 +.IX Item "X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag" +Proxy certificates not allowed unless the \fBX509_V_FLAG_ALLOW_PROXY_CERTS\fR flag +is set. +.IP "\fBX509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension\fR" 4 +.IX Item "X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension" +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. +.IP "\fBX509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension\fR" 4 +.IX Item "X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension" +A certificate policies extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. This error only +occurs if policy processing is enabled. +.IP "\fBX509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy\fR" 4 +.IX Item "X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy" +The verification flags were set to require and explicit policy but none was +present. +.IP "\fBX509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope\fR" 4 +.IX Item "X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope" +The only CRLs that could be found did not match the scope of the certificate. +.IP "\fBX509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: unsupported extension feature\fR" 4 +.IX Item "X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: unsupported extension feature" +Some feature of a certificate extension is not supported. Unused. +.IP "\fBX509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent\*(Aqs resources\fR" 4 +.IX Item "X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's resources" +See RFC 3779 for details. +.IP "\fBX509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation\fR" 4 +.IX Item "X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation" +A name constraint violation occurred in the permitted subtrees. +.IP "\fBX509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation\fR" 4 +.IX Item "X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation" +A name constraint violation occurred in the excluded subtrees. +.IP "\fBX509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported\fR" 4 +.IX Item "X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported" +A certificate name constraints extension included a minimum or maximum field: +this is not supported. +.IP "\fBX509_V_ERR_APPLICATION_VERIFICATION: application verification failure\fR" 4 +.IX Item "X509_V_ERR_APPLICATION_VERIFICATION: application verification failure" +An application specific error. This will never be returned unless explicitly +set by an application callback. +.IP "\fBX509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type\fR" 4 +.IX Item "X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type" +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. +.IP "\fBX509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax\fR" 4 +.IX Item "X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax" +The format of the name constraint is not recognised: for example an email +address format of a form not mentioned in RFC3280. This could be caused by +a garbage extension or some new feature not currently supported. +.IP "\fBX509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax\fR" 4 +.IX Item "X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax" +Unsupported or invalid name syntax. +.IP "\fBX509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error\fR" 4 +.IX Item "X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error" +An error occurred when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. +.IP "\fBX509_V_ERR_PATH_LOOP: path loop\fR" 4 +.IX Item "X509_V_ERR_PATH_LOOP: path loop" +Path loop. +.IP "\fBX509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch\fR" 4 +.IX Item "X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch" +Hostname mismatch. +.IP "\fBX509_V_ERR_EMAIL_MISMATCH: email address mismatch\fR" 4 +.IX Item "X509_V_ERR_EMAIL_MISMATCH: email address mismatch" +Email address mismatch. +.IP "\fBX509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch\fR" 4 +.IX Item "X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch" +IP address mismatch. +.IP "\fBX509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records\fR" 4 +.IX Item "X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records" +DANE TLSA authentication is enabled, but no TLSA records matched the +certificate chain. +This error is only possible in \fBopenssl\-s_client\fR\|(1). +.IP "\fBX509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak\fR" 4 +.IX Item "X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak" +EE certificate key too weak. +.IP "\fBX509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak\fR" 4 +.IX Item "X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak" +CA certificate key too weak. +.IP "\fBX509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak\fR" 4 +.IX Item "X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak" +CA signature digest algorithm too weak. +.IP "\fBX509_V_ERR_INVALID_CALL: invalid certificate verification context\fR" 4 +.IX Item "X509_V_ERR_INVALID_CALL: invalid certificate verification context" +Invalid certificate verification context. +.IP "\fBX509_V_ERR_STORE_LOOKUP: issuer certificate lookup error\fR" 4 +.IX Item "X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error" +Issuer certificate lookup error. +.IP "\fBX509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found\fR" 4 +.IX Item "X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found" +Certificate Transparency required, but no valid SCTs found. +.IP "\fBX509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation\fR" 4 +.IX Item "X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation" +Proxy subject name violation. +.IP "\fBX509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed\fR" 4 +.IX Item "X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed" +Returned by the verify callback to indicate an OCSP verification is needed. +.IP "\fBX509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed\fR" 4 +.IX Item "X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed" +Returned by the verify callback to indicate OCSP verification failed. +.IP "\fBX509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert\fR" 4 +.IX Item "X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert" +Returned by the verify callback to indicate that the certificate is not +recognized by the OCSP responder. +.IP "\fBX509_V_ERR_UNSUPPORTED_SIGNATURE_ALGORITHM: unsupported signature algorithm\fR" 4 +.IX Item "X509_V_ERR_UNSUPPORTED_SIGNATURE_ALGORITHM: unsupported signature algorithm" +Cannot find certificate signature algorithm. +.IP "\fBX509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH: subject signature algorithm and issuer public key algorithm mismatch\fR" 4 +.IX Item "X509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH: subject signature algorithm and issuer public key algorithm mismatch" +The issuer\*(Aqs public key is not of the type required by the signature in +the subject\*(Aqs certificate. +.IP "\fBX509_V_ERR_SIGNATURE_ALGORITHM_INCONSISTENCY: cert info signature and signature algorithm mismatch\fR" 4 +.IX Item "X509_V_ERR_SIGNATURE_ALGORITHM_INCONSISTENCY: cert info signature and signature algorithm mismatch" +The algorithm given in the certificate info is inconsistent + with the one used for the certificate signature. +.IP "\fBX509_V_ERR_INVALID_CA: invalid CA certificate\fR" 4 +.IX Item "X509_V_ERR_INVALID_CA: invalid CA certificate" +A CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. +.IP "\fBX509_V_ERR_RPK_UNTRUSTED: raw public key untrusted, no trusted keys configured\fR" 4 +.IX Item "X509_V_ERR_RPK_UNTRUSTED: raw public key untrusted, no trusted keys configured" +No TLS records were configured to validate the raw public key, or DANE was not +enabled on the connection. +.SH NOTES +.IX Header "NOTES" +The above functions should be used instead of directly referencing the fields +in the \fBX509_VERIFY_CTX\fR structure. +.PP +In versions of OpenSSL before 1.0 the current certificate returned by +\&\fBX509_STORE_CTX_get_current_cert()\fR was never NULL. Applications should +check the return value before printing out any debugging information relating +to the current certificate. +.PP +If an unrecognised error code is passed to \fBX509_verify_cert_error_string()\fR the +numerical value of the unknown code is returned in a static buffer. This is not +thread safe but will never happen unless an invalid code is passed. +.SH BUGS +.IX Header "BUGS" +Previous versions of this documentation swapped the meaning of the +\&\fBX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT\fR and +\&\fBX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY\fR error codes. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify_cert\fR\|(3), \fBX509_STORE_CTX_verify\fR\|(3), +\&\fBX509_up_ref\fR\|(3), +\&\fBX509_free\fR\|(3). +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_CTX_get_ex_new_index.3 b/static/netbsd/man3/X509_STORE_CTX_get_ex_new_index.3 new file mode 100644 index 00000000..19c64ab1 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_CTX_get_ex_new_index.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: X509_STORE_CTX_get_ex_new_index.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "X509_STORE_CTX_get_ex_new_index 3" +.TH X509_STORE_CTX_get_ex_new_index 3 "2014-06-05" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data \- add application specific data to X509_STORE_CTX structures +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& +\& int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); +\& +\& void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions handle application specific data in X509_STORE_CTX structures. +Their usage is identical to that of \fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR +and \fIRSA_get_ex_data()\fR as described in \fIRSA_get_ex_new_index\fR\|(3). +.SH "NOTES" +.IX Header "NOTES" +This mechanism is used internally by the \fBssl\fR library to store the \fB\s-1SSL\s0\fR +structure associated with a verification operation in an \fBX509_STORE_CTX\fR +structure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIRSA_get_ex_new_index\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIX509_STORE_CTX_get_ex_new_index()\fR, \fIX509_STORE_CTX_set_ex_data()\fR and +\&\fIX509_STORE_CTX_get_ex_data()\fR are available since OpenSSL 0.9.5. diff --git a/static/netbsd/man3/X509_STORE_CTX_new.3 b/static/netbsd/man3/X509_STORE_CTX_new.3 new file mode 100644 index 00000000..f3855887 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_CTX_new.3 @@ -0,0 +1,387 @@ +.\" $NetBSD: X509_STORE_CTX_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_CTX_new 3" +.TH X509_STORE_CTX_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup, +X509_STORE_CTX_free, X509_STORE_CTX_init, +X509_STORE_CTX_init_rpk, +X509_STORE_CTX_set0_trusted_stack, +X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, +X509_STORE_CTX_set0_rpk, +X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, +X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, +X509_STORE_CTX_get_num_untrusted, +X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, +X509_STORE_CTX_get0_rpk, +X509_STORE_CTX_set_default, +X509_STORE_CTX_set_verify, +X509_STORE_CTX_verify_fn, +X509_STORE_CTX_set_purpose, +X509_STORE_CTX_set_trust, +X509_STORE_CTX_purpose_inherit +\&\- X509_STORE_CTX initialisation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_STORE_CTX *X509_STORE_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq); +\& X509_STORE_CTX *X509_STORE_CTX_new(void); +\& void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_free(X509_STORE_CTX *ctx); +\& +\& int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store, +\& X509 *target, STACK_OF(X509) *untrusted); +\& int X509_STORE_CTX_init_rpk(X509_STORE_CTX *ctx, X509_STORE *trust_store, +\& EVP_PKEY *rpk); +\& +\& void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); +\& +\& void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target); +\& void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); +\& void X509_STORE_CTX_set0_rpk(X509_STORE_CTX *ctx, EVP_PKEY *target); +\& +\& X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); +\& +\& STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); +\& +\& int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx); +\& STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain); +\& EVP_PKEY *X509_STORE_CTX_get0_rpk(const X509_STORE_CTX *ctx); +\& +\& int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); +\& typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *); +\& void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); +\& +\& int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose); +\& int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust); +\& int X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose, +\& int purpose, int trust); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions initialise an \fBX509_STORE_CTX\fR structure for subsequent use +by \fBX509_verify_cert\fR\|(3) or \fBX509_STORE_CTX_verify\fR\|(3). +.PP +\&\fBX509_STORE_CTX_new_ex()\fR returns a newly initialised \fBX509_STORE_CTX\fR +structure associated with the specified library context \fIlibctx\fR and property +query string \fIpropq\fR. Any cryptographic algorithms fetched while performing +processing with the X509_STORE_CTX will use that library context and property +query string. +.PP +\&\fBX509_STORE_CTX_new()\fR is the same as \fBX509_STORE_CTX_new_ex()\fR except that +the default library context and a NULL property query string are used. +.PP +\&\fBX509_STORE_CTX_cleanup()\fR internally cleans up an \fBX509_STORE_CTX\fR structure. +It is used by \fBX509_STORE_CTX_init()\fR and \fBX509_STORE_CTX_free()\fR. +.PP +\&\fBX509_STORE_CTX_free()\fR completely frees up \fIctx\fR. After this call \fIctx\fR +is no longer valid. +If \fIctx\fR is NULL nothing is done. +.PP +\&\fBX509_STORE_CTX_init()\fR sets up \fIctx\fR for a subsequent verification operation. +.PP +\&\fBX509_STORE_CTX_init()\fR initializes the internal state and resources of the +given \fIctx\fR. Among others, it sets the verification parameters associated +with the method name \f(CW\*(C`default\*(C'\fR, which includes the \f(CW\*(C`any\*(C'\fR purpose, +and takes over callback function pointers from \fItrust_store\fR (unless NULL). +It must be called before each call to \fBX509_verify_cert\fR\|(3) or +\&\fBX509_STORE_CTX_verify\fR\|(3), i.e., a context is only good for one verification. +If you want to verify a further certificate or chain with the same \fIctx\fR +then you must call \fBX509_STORE_CTX_init()\fR again. +The trusted certificate store is set to \fItrust_store\fR of type \fBX509_STORE\fR. +This may be NULL because there are no trusted certificates or because +they are provided simply as a list using \fBX509_STORE_CTX_set0_trusted_stack()\fR. +The certificate to be verified is set to \fItarget\fR, +and a list of additional certificates may be provided in \fIuntrusted\fR, +which will be untrusted but may be used to build the chain. +The \fItarget\fR certificate is not copied (its reference count is not updated), +and the caller must not free it before verification is complete. +Each of the \fItrust_store\fR, \fItarget\fR and \fIuntrusted\fR parameters can be NULL. +Yet note that \fBX509_verify_cert\fR\|(3) and \fBX509_STORE_CTX_verify\fR\|(3) +will need a verification target. +This can also be set using \fBX509_STORE_CTX_set_cert()\fR. +For \fBX509_STORE_CTX_verify\fR\|(3), which takes by default the first element of the +list of untrusted certificates as its verification target, +this can be also set indirectly using \fBX509_STORE_CTX_set0_untrusted()\fR. +.PP +\&\fBX509_STORE_CTX_init_rpk()\fR sets up \fIctx\fR for a subsequent verification +operation for the \fItarget\fR raw public key. +It behaves similarly to \fBX509_STORE_CTX_init()\fR. +The \fItarget\fR raw public key can also be supplied separately, via +\&\fBX509_STORE_CTX_set0_rpk()\fR. +The \fItarget\fR public key is not copied (its reference count is not updated), +and the caller must not free it before verification is complete. +.PP +\&\fBX509_STORE_CTX_set0_trusted_stack()\fR sets the set of trusted certificates of +\&\fIctx\fR to \fIsk\fR. This is an alternative way of specifying trusted certificates +instead of using an \fBX509_STORE\fR where its complexity is not needed +or to make sure that only the given set \fIsk\fR of certificates are trusted. +.PP +\&\fBX509_STORE_CTX_set_cert()\fR sets the target certificate to be verified in \fIctx\fR +to \fItarget\fR. +The target certificate is not copied (its reference count is not updated), +and the caller must not free it before verification is complete. +.PP +\&\fBX509_STORE_CTX_set0_rpk()\fR sets the target raw public key to be verified in \fIctx\fR +to \fItarget\fR, a non\-NULL raw public key preempts any target certificate, which +is then ignored. +The \fItarget\fR public key is not copied (its reference count is not updated), +and the caller must not free it before verification is complete. +.PP +\&\fBX509_STORE_CTX_set0_verified_chain()\fR sets the validated chain to \fIchain\fR. +Ownership of the chain is transferred to \fIctx\fR, +and so it should not be free\*(Aqd by the caller. +.PP +\&\fBX509_STORE_CTX_get0_chain()\fR returns the internal pointer used by the +\&\fIctx\fR that contains the constructed (output) chain. +.PP +\&\fBX509_STORE_CTX_get0_rpk()\fR returns the internal pointer used by the +\&\fIctx\fR that contains the raw public key. +.PP +\&\fBX509_STORE_CTX_set0_crls()\fR sets a set of CRLs to use to aid certificate +verification to \fIsk\fR. These CRLs will only be used if CRL verification is +enabled in the associated \fBX509_VERIFY_PARAM\fR structure. This might be +used where additional "useful" CRLs are supplied as part of a protocol, +for example in a PKCS#7 structure. +.PP +\&\fBX509_STORE_CTX_get0_param()\fR retrieves an internal pointer +to the verification parameters associated with \fIctx\fR. +.PP +\&\fBX509_STORE_CTX_set0_param()\fR sets the internal verification parameter pointer +to \fIparam\fR. After this call \fBparam\fR should not be used. +.PP +\&\fBX509_STORE_CTX_get0_untrusted()\fR retrieves an internal pointer to the +stack of untrusted certificates associated with \fIctx\fR. +.PP +\&\fBX509_STORE_CTX_set0_untrusted()\fR sets the internal pointer to the stack +of untrusted certificates associated with \fIctx\fR to \fIsk\fR. +\&\fBX509_STORE_CTX_verify()\fR will take the first element, if any, +as its default target if the target certificate is not set explicitly. +.PP +\&\fBX509_STORE_CTX_get_num_untrusted()\fR returns the number of untrusted certificates +that were used in building the chain. +This is can be used after calling \fBX509_verify_cert\fR\|(3) and similar functions. +With \fBX509_STORE_CTX_verify\fR\|(3), this does not count the first chain element. +.PP +\&\fBX509_STORE_CTX_get0_chain()\fR returns the internal pointer used by the +\&\fIctx\fR that contains the validated chain. +.PP +Details of the chain building and checking process are described in +"Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1) and +"Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1). +.PP +\&\fBX509_STORE_CTX_set0_verified_chain()\fR sets the validated chain used +by \fIctx\fR to be \fIchain\fR. +Ownership of the chain is transferred to \fIctx\fR, +and so it should not be free\*(Aqd by the caller. +.PP +\&\fBX509_STORE_CTX_set_default()\fR looks up and sets the default verification method. +This uses the function \fBX509_VERIFY_PARAM_lookup()\fR to find +the set of parameters associated with the given verification method \fIname\fR. +Among others, the parameters determine the trust model and verification purpose. +More detail, including the list of currently predefined methods, +is described for the \fB\-verify_name\fR command\-line option +in "Verification Options" in \fBopenssl\-verification\-options\fR\|(1). +.PP +\&\fBX509_STORE_CTX_set_verify()\fR provides the capability for overriding the default +verify function. This function is responsible for verifying chain signatures and +expiration times. +.PP +A verify function is defined as an X509_STORE_CTX_verify type which has the +following signature: +.PP +.Vb 1 +\& int (*verify)(X509_STORE_CTX *); +.Ve +.PP +This function should receive the current X509_STORE_CTX as a parameter and +return 1 on success or 0 on failure. +.PP +X509 certificates may contain information about what purposes keys contained +within them can be used for. For example "TLS WWW Server Authentication" or +"Email Protection". This "key usage" information is held internally to the +certificate itself. In addition the trust store containing trusted certificates +can declare what purposes we trust different certificates for. This "trust" +information is not held within the certificate itself but is "meta" information +held alongside it. This "meta" information is associated with the certificate +after it is issued and could be determined by a system administrator. For +example a certificate might declare that it is suitable for use for both +"TLS WWW Server Authentication" and "TLS Client Authentication", but a system +administrator might only trust it for the former. An X.509 certificate extension +exists that can record extended key usage information to supplement the purpose +information described above. This extended mechanism is arbitrarily extensible +and not well suited for a generic library API; applications that need to +validate extended key usage information in certificates will need to define a +custom "purpose" (see below) or supply a nondefault verification callback +(\fBX509_STORE_set_verify_cb_func\fR\|(3)). +.PP +\&\fBX509_STORE_CTX_set_purpose()\fR sets the purpose for the target certificate being +verified in the \fIctx\fR. Built\-in available values for the \fIpurpose\fR argument +are \fBX509_PURPOSE_SSL_CLIENT\fR, \fBX509_PURPOSE_SSL_SERVER\fR, +\&\fBX509_PURPOSE_NS_SSL_SERVER\fR, \fBX509_PURPOSE_SMIME_SIGN\fR, +\&\fBX509_PURPOSE_SMIME_ENCRYPT\fR, \fBX509_PURPOSE_CRL_SIGN\fR, \fBX509_PURPOSE_ANY\fR, +\&\fBX509_PURPOSE_OCSP_HELPER\fR, \fBX509_PURPOSE_TIMESTAMP_SIGN\fR and +\&\fBX509_PURPOSE_CODE_SIGN\fR. It is also +possible to create a custom purpose value. Setting a purpose requests that +the key usage and extended key usage (EKU) extensions optionally declared within +the certificate and its chain are verified to be consistent with that purpose. +For SSL client, SSL server, and S/MIME purposes, the EKU is checked also for the +CA certificates along the chain, including any given trust anchor certificate. +Potentially also further checks are done (depending on the purpose given). +Every purpose also has an associated default trust value, which will also be set +at the same time. During verification, this trust setting will be verified +to check whether it is consistent with the trust set by the system administrator +for certificates in the chain. +.PP +\&\fBX509_STORE_CTX_set_trust()\fR sets the trust value for the target certificate +being verified in the \fIctx\fR. Built\-in available values for the \fItrust\fR +argument are \fBX509_TRUST_COMPAT\fR, \fBX509_TRUST_SSL_CLIENT\fR, +\&\fBX509_TRUST_SSL_SERVER\fR, \fBX509_TRUST_EMAIL\fR, \fBX509_TRUST_OBJECT_SIGN\fR, +\&\fBX509_TRUST_OCSP_SIGN\fR, \fBX509_TRUST_OCSP_REQUEST\fR and \fBX509_TRUST_TSA\fR. It is +also possible to create a custom trust value. Since \fBX509_STORE_CTX_set_purpose()\fR +also sets the trust value it is normally sufficient to only call that function. +If both are called then \fBX509_STORE_CTX_set_trust()\fR should be called after +\&\fBX509_STORE_CTX_set_purpose()\fR since the trust setting of the last call will be +used. +.PP +It should not normally be necessary for end user applications to call +\&\fBX509_STORE_CTX_purpose_inherit()\fR directly. Typically applications should call +\&\fBX509_STORE_CTX_set_purpose()\fR or \fBX509_STORE_CTX_set_trust()\fR instead. Using this +function it is possible to set the purpose and trust values for the \fIctx\fR at +the same time. +Both \fIctx\fR and its internal verification parameter pointer must not be NULL. +The \fIdef_purpose\fR and \fIpurpose\fR arguments can have the same +purpose values as described for \fBX509_STORE_CTX_set_purpose()\fR above. The \fItrust\fR +argument can have the same trust values as described in +\&\fBX509_STORE_CTX_set_trust()\fR above. Any of the \fIdef_purpose\fR, \fIpurpose\fR or +\&\fItrust\fR values may also have the value 0 to indicate that the supplied +parameter should be ignored. After calling this function the purpose to be used +for verification is set from the \fIpurpose\fR argument unless the purpose was +already set in \fIctx\fR before, and the trust is set from the \fItrust\fR argument +unless the trust was already set in \fIctx\fR before. +If \fItrust\fR is 0 then the trust value will be set from +the default trust value for \fIpurpose\fR. If the default trust value for the +purpose is \fIX509_TRUST_DEFAULT\fR and \fItrust\fR is 0 then the default trust value +associated with the \fIdef_purpose\fR value is used for the trust setting instead. +.SH NOTES +.IX Header "NOTES" +The certificates and CRLs in a store are used internally and should \fBnot\fR +be freed up until after the associated \fBX509_STORE_CTX\fR is freed. +.SH BUGS +.IX Header "BUGS" +The certificates and CRLs in a context are used internally and should \fBnot\fR +be freed up until after the associated \fBX509_STORE_CTX\fR is freed. Copies +should be made or reference counts increased instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_CTX_new()\fR returns a newly allocated context or NULL if an +error occurred. +.PP +\&\fBX509_STORE_CTX_init()\fR and \fBX509_STORE_CTX_init_rpk()\fR return 1 for success +or 0 if an error occurred. +.PP +\&\fBX509_STORE_CTX_get0_param()\fR returns a pointer to an \fBX509_VERIFY_PARAM\fR +structure or NULL if an error occurred. +.PP +\&\fBX509_STORE_CTX_get0_rpk()\fR returns a pointer to an \fBEVP_PKEY\fR structure if +present, or NULL if absent. +.PP +\&\fBX509_STORE_CTX_cleanup()\fR, \fBX509_STORE_CTX_free()\fR, +\&\fBX509_STORE_CTX_set0_trusted_stack()\fR, +\&\fBX509_STORE_CTX_set_cert()\fR, +\&\fBX509_STORE_CTX_set0_crls()\fR and \fBX509_STORE_CTX_set0_param()\fR do not return +values. +.PP +\&\fBX509_STORE_CTX_set_default()\fR returns 1 for success or 0 if an error occurred. +.PP +\&\fBX509_STORE_CTX_get_num_untrusted()\fR returns the number of untrusted certificates +used. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify_cert\fR\|(3), \fBX509_STORE_CTX_verify\fR\|(3), +\&\fBX509_VERIFY_PARAM_set_flags\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_STORE_CTX_set0_crls()\fR function was added in OpenSSL 1.0.0. +The \fBX509_STORE_CTX_get_num_untrusted()\fR function was added in OpenSSL 1.1.0. +The \fBX509_STORE_CTX_new_ex()\fR function was added in OpenSSL 3.0. +The \fBX509_STORE_CTX_init_rpk()\fR, \fBX509_STORE_CTX_get0_rpk()\fR, and +\&\fBX509_STORE_CTX_set0_rpk()\fR functions were added in OpenSSL 3.2. +.PP +There is no need to call \fBX509_STORE_CTX_cleanup()\fR explicitly since OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_CTX_set_verify_cb.3 b/static/netbsd/man3/X509_STORE_CTX_set_verify_cb.3 new file mode 100644 index 00000000..718d7d9c --- /dev/null +++ b/static/netbsd/man3/X509_STORE_CTX_set_verify_cb.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: X509_STORE_CTX_set_verify_cb.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_CTX_set_verify_cb 3" +.TH X509_STORE_CTX_set_verify_cb 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_CTX_get_cleanup, +X509_STORE_CTX_get_lookup_crls, +X509_STORE_CTX_get_lookup_certs, +X509_STORE_CTX_get_check_policy, +X509_STORE_CTX_get_cert_crl, +X509_STORE_CTX_get_check_crl, +X509_STORE_CTX_get_get_crl, +X509_STORE_CTX_set_get_crl, +X509_STORE_CTX_get_check_revocation, +X509_STORE_CTX_get_check_issued, +X509_STORE_CTX_get_get_issuer, +X509_STORE_CTX_get_verify_cb, +X509_STORE_CTX_set_verify_cb, +X509_STORE_CTX_verify_cb, +X509_STORE_CTX_print_verify_cb, +X509_STORE_CTX_set_current_reasons +\&\- get and set X509_STORE_CTX components such as verification callback +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); +\& int X509_STORE_CTX_print_verify_cb(int ok, X509_STORE_CTX *ctx); +\& +\& X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx); +\& +\& void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, +\& X509_STORE_CTX_verify_cb verify_cb); +\& +\& X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx); +\& +\& X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx); +\& +\& void X509_STORE_CTX_set_get_crl(X509_STORE_CTX *ctx, +\& X509_STORE_CTX_get_crl_fn get_crl); +\& +\& X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx); +\& X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx); +\& void X509_STORE_CTX_set_current_reasons(X509_STORE_CTX *ctx, +\& unsigned int current_reasons); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_STORE_CTX_set_verify_cb()\fR sets the verification callback of \fBctx\fR to +\&\fBverify_cb\fR overwriting any existing callback. +.PP +The verification callback can be used to customise the operation of certificate +verification, for instance by overriding error conditions or logging errors for +debugging purposes. +.PP +However, a verification callback is \fBnot\fR essential and the default operation +is often sufficient. +.PP +The \fBok\fR parameter to the callback indicates the value the callback should +return to retain the default behaviour. If it is zero then an error condition +is indicated. If it is 1 then no error occurred. If the flag +\&\fBX509_V_FLAG_NOTIFY_POLICY\fR is set then \fBok\fR is set to 2 to indicate the +policy checking is complete. +.PP +The \fBctx\fR parameter to the callback is the \fBX509_STORE_CTX\fR structure that +is performing the verification operation. A callback can examine this +structure and receive additional information about the error, for example +by calling \fBX509_STORE_CTX_get_current_cert()\fR. Additional application data can +be passed to the callback via the \fBex_data\fR mechanism. +.PP +\&\fBX509_STORE_CTX_print_verify_cb()\fR is a verification callback function that, +when a certificate verification has failed, adds an entry to the error queue +with code \fBX509_R_CERTIFICATE_VERIFICATION_FAILED\fR and with diagnostic details, +including the most relevant fields of the target certificate that failed to +verify and, if appropriate, of the available untrusted and trusted certificates. +.PP +\&\fBX509_STORE_CTX_get_verify_cb()\fR returns the value of the current callback +for the specific \fBctx\fR. +.PP +\&\fBX509_STORE_CTX_get_get_issuer()\fR, +\&\fBX509_STORE_CTX_get_check_issued()\fR, \fBX509_STORE_CTX_get_check_revocation()\fR, +\&\fBX509_STORE_CTX_get_get_crl()\fR, \fBX509_STORE_CTX_get_check_crl()\fR, +\&\fBX509_STORE_CTX_get_cert_crl()\fR, \fBX509_STORE_CTX_get_check_policy()\fR, +\&\fBX509_STORE_CTX_get_lookup_certs()\fR, \fBX509_STORE_CTX_get_lookup_crls()\fR +and \fBX509_STORE_CTX_get_cleanup()\fR return the function pointers cached +from the corresponding \fBX509_STORE\fR, please see +\&\fBX509_STORE_set_verify\fR\|(3) for more information. +.PP +\&\fBX509_STORE_CTX_set_get_crl()\fR sets the function to get the crl for a given +certificate \fIx\fR. +When found, the crl must be assigned to \fI*crl\fR. +This function must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_CTX_set_current_reasons()\fR is used in conjunction with +X509_STORE_CTX_get_crl_fn. The X509_STORE_CTX_get_crl_fn callback must +use this method to set the reason why the certificate is invalid. +.SH WARNINGS +.IX Header "WARNINGS" +In general a verification callback should \fBNOT\fR unconditionally return 1 in +all circumstances because this will allow verification to succeed no matter +what the error. This effectively removes all security from the application +because \fBany\fR certificate (including untrusted generated ones) will be +accepted. +.SH NOTES +.IX Header "NOTES" +The verification callback can be set and inherited from the parent structure +performing the operation. In some cases (such as S/MIME verification) the +\&\fBX509_STORE_CTX\fR structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated \fBX509_STORE\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_CTX_set_verify_cb()\fR does not return a value. +.SH EXAMPLES +.IX Header "EXAMPLES" +Default callback operation: +.PP +.Vb 3 +\& int verify_callback(int ok, X509_STORE_CTX *ctx) { +\& return ok; +\& } +.Ve +.PP +Simple example, suppose a certificate in the chain is expired and we wish +to continue after this error: +.PP +.Vb 7 +\& int verify_callback(int ok, X509_STORE_CTX *ctx) { +\& /* Tolerate certificate expiration */ +\& if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) +\& return 1; +\& /* Otherwise don\*(Aqt override */ +\& return ok; +\& } +.Ve +.PP +More complex example, we don\*(Aqt wish to continue after \fBany\fR certificate has +expired just one specific case: +.PP +.Vb 4 +\& int verify_callback(int ok, X509_STORE_CTX *ctx) +\& { +\& int err = X509_STORE_CTX_get_error(ctx); +\& X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); +\& +\& if (err == X509_V_ERR_CERT_HAS_EXPIRED) { +\& if (check_is_acceptable_expired_cert(err_cert) +\& return 1; +\& } +\& return ok; +\& } +.Ve +.PP +Full featured logging callback. In this case the \fBbio_err\fR is assumed to be +a global logging \fBBIO\fR, an alternative would to store a BIO in \fBctx\fR using +\&\fBex_data\fR. +.PP +.Vb 4 +\& int verify_callback(int ok, X509_STORE_CTX *ctx) +\& { +\& X509 *err_cert; +\& int err, depth; +\& +\& err_cert = X509_STORE_CTX_get_current_cert(ctx); +\& err = X509_STORE_CTX_get_error(ctx); +\& depth = X509_STORE_CTX_get_error_depth(ctx); +\& +\& BIO_printf(bio_err, "depth=%d ", depth); +\& if (err_cert) { +\& X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), +\& 0, XN_FLAG_ONELINE); +\& BIO_puts(bio_err, "\en"); +\& } +\& else +\& BIO_puts(bio_err, "\en"); +\& if (!ok) +\& BIO_printf(bio_err, "verify error:num=%d:%s\en", err, +\& X509_verify_cert_error_string(err)); +\& switch (err) { +\& case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: +\& BIO_puts(bio_err, "issuer= "); +\& X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), +\& 0, XN_FLAG_ONELINE); +\& BIO_puts(bio_err, "\en"); +\& break; +\& case X509_V_ERR_CERT_NOT_YET_VALID: +\& case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: +\& BIO_printf(bio_err, "notBefore="); +\& ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert)); +\& BIO_printf(bio_err, "\en"); +\& break; +\& case X509_V_ERR_CERT_HAS_EXPIRED: +\& case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: +\& BIO_printf(bio_err, "notAfter="); +\& ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); +\& BIO_printf(bio_err, "\en"); +\& break; +\& case X509_V_ERR_NO_EXPLICIT_POLICY: +\& policies_print(bio_err, ctx); +\& break; +\& } +\& if (err == X509_V_OK && ok == 2) +\& /* print out policies */ +\& +\& BIO_printf(bio_err, "verify return:%d\en", ok); +\& return(ok); +\& } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_STORE_CTX_get_error\fR\|(3) +\&\fBX509_STORE_set_verify_cb_func\fR\|(3) +\&\fBX509_STORE_CTX_get_ex_new_index\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The +\&\fBX509_STORE_CTX_get_get_issuer()\fR, +\&\fBX509_STORE_CTX_get_check_issued()\fR, \fBX509_STORE_CTX_get_check_revocation()\fR, +\&\fBX509_STORE_CTX_get_get_crl()\fR, \fBX509_STORE_CTX_get_check_crl()\fR, +\&\fBX509_STORE_CTX_get_cert_crl()\fR, \fBX509_STORE_CTX_get_check_policy()\fR, +\&\fBX509_STORE_CTX_get_lookup_certs()\fR, \fBX509_STORE_CTX_get_lookup_crls()\fR +and \fBX509_STORE_CTX_get_cleanup()\fR functions were added in OpenSSL 1.1.0. +.PP +\&\fBX509_STORE_CTX_print_verify_cb()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_add_cert.3 b/static/netbsd/man3/X509_STORE_add_cert.3 new file mode 100644 index 00000000..51e70be6 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_add_cert.3 @@ -0,0 +1,230 @@ +.\" $NetBSD: X509_STORE_add_cert.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_add_cert 3" +.TH X509_STORE_add_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE, +X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth, +X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust, +X509_STORE_add_lookup, +X509_STORE_load_file_ex, X509_STORE_load_file, X509_STORE_load_path, +X509_STORE_load_store_ex, X509_STORE_load_store, +X509_STORE_set_default_paths_ex, X509_STORE_set_default_paths, +X509_STORE_load_locations_ex, X509_STORE_load_locations +\&\- X509_STORE manipulation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef x509_store_st X509_STORE; +\& +\& int X509_STORE_add_cert(X509_STORE *xs, X509 *x); +\& int X509_STORE_add_crl(X509_STORE *xs, X509_CRL *x); +\& int X509_STORE_set_depth(X509_STORE *store, int depth); +\& int X509_STORE_set_flags(X509_STORE *xs, unsigned long flags); +\& int X509_STORE_set_purpose(X509_STORE *xs, int purpose); +\& int X509_STORE_set_trust(X509_STORE *xs, int trust); +\& +\& X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store, +\& X509_LOOKUP_METHOD *meth); +\& +\& int X509_STORE_set_default_paths_ex(X509_STORE *xs, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int X509_STORE_set_default_paths(X509_STORE *xs); +\& int X509_STORE_load_file_ex(X509_STORE *xs, const char *file, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_STORE_load_file(X509_STORE *xs, const char *file); +\& int X509_STORE_load_path(X509_STORE *xs, const char *dir); +\& int X509_STORE_load_store_ex(X509_STORE *xs, const char *uri, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_STORE_load_store(X509_STORE *xs, const char *uri); +\& int X509_STORE_load_locations_ex(X509_STORE *xs, const char *file, +\& const char *dir, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int X509_STORE_load_locations(X509_STORE *xs, +\& const char *file, const char *dir); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_STORE\fR structure is intended to be a consolidated mechanism for +holding information about X.509 certificates and CRLs, and constructing +and validating chains of certificates terminating in trusted roots. +It admits multiple lookup mechanisms and efficient scaling performance +with large numbers of certificates, and a great deal of flexibility in +how validation and policy checks are performed. +.PP +Details of the chain building and checking process are described in +"Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1) and +"Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1). +.PP +\&\fBX509_STORE_new\fR\|(3) creates an empty \fBX509_STORE\fR structure, which contains +no information about trusted certificates or where such certificates +are located on disk, and is generally not usable. Normally, trusted +certificates will be added to the \fBX509_STORE\fR to prepare it for use, +via mechanisms such as \fBX509_STORE_add_lookup()\fR and \fBX509_LOOKUP_file()\fR, or +\&\fBPEM_read_bio_X509_AUX()\fR and \fBX509_STORE_add_cert()\fR. CRLs can also be added, +and many behaviors configured as desired. +.PP +Once the \fBX509_STORE\fR is suitably configured, \fBX509_STORE_CTX_new()\fR is +used to instantiate a single\-use \fBX509_STORE_CTX\fR for each chain\-building +and verification operation. That process includes providing the end\-entity +certificate to be verified and an additional set of untrusted certificates +that may be used in chain\-building. As such, it is expected that the +certificates included in the \fBX509_STORE\fR are certificates that represent +trusted entities such as root certificate authorities (CAs). +OpenSSL represents these trusted certificates internally as \fBX509\fR objects +with an associated \fBX509_CERT_AUX\fR, as are produced by +\&\fBPEM_read_bio_X509_AUX()\fR and similar routines that refer to X509_AUX. +The public interfaces that operate on such trusted certificates still +operate on pointers to \fBX509\fR objects, though. +.PP +\&\fBX509_STORE_add_cert()\fR and \fBX509_STORE_add_crl()\fR add the respective object +to the \fBX509_STORE\fR\*(Aqs local storage. Untrusted objects should not be +added in this way. The added object\*(Aqs reference count is incremented by one, +hence the caller retains ownership of the object and needs to free it when it +is no longer needed. +.PP +\&\fBX509_STORE_set_depth()\fR, \fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR, +\&\fBX509_STORE_set_trust()\fR, and \fBX509_STORE_set1_param()\fR set the default values +for the corresponding values used in certificate chain validation. Their +behavior is documented in the corresponding \fBX509_VERIFY_PARAM\fR manual +pages, e.g., \fBX509_VERIFY_PARAM_set_depth\fR\|(3). The \fBX509_STORE\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBX509_STORE_add_lookup()\fR finds or creates a \fBX509_LOOKUP\fR\|(3) with the +\&\fBX509_LOOKUP_METHOD\fR\|(3) \fImeth\fR and adds it to the \fBX509_STORE\fR +\&\fIstore\fR. This also associates the \fBX509_STORE\fR with the lookup, so +\&\fBX509_LOOKUP\fR functions can look up objects in that store. +.PP +\&\fBX509_STORE_load_file_ex()\fR loads trusted certificate(s) into an +\&\fBX509_STORE\fR from a given file. The library context \fIlibctx\fR and property +query \fIpropq\fR are used when fetching algorithms from providers. +.PP +\&\fBX509_STORE_load_file()\fR is similar to \fBX509_STORE_load_file_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_STORE_load_path()\fR loads trusted certificate(s) into an +\&\fBX509_STORE\fR from a given directory path. +The certificates in the directory must be in hashed form, as +documented in \fBX509_LOOKUP_hash_dir\fR\|(3). +.PP +\&\fBX509_STORE_load_store_ex()\fR loads trusted certificate(s) into an +\&\fBX509_STORE\fR from a store at a given URI. The library context \fIlibctx\fR and +property query \fIpropq\fR are used when fetching algorithms from providers. +.PP +\&\fBX509_STORE_load_store()\fR is similar to \fBX509_STORE_load_store_ex()\fR but +uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_STORE_load_locations_ex()\fR combines +\&\fBX509_STORE_load_file_ex()\fR and \fBX509_STORE_load_path()\fR for a given file +and/or directory path. +It is permitted to specify just a file, just a directory, or both +paths. +.PP +\&\fBX509_STORE_load_locations()\fR is similar to \fBX509_STORE_load_locations_ex()\fR +but uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR. +.PP +\&\fBX509_STORE_set_default_paths_ex()\fR is somewhat misnamed, in that it does +not set what default paths should be used for loading certificates. Instead, +it loads certificates into the \fBX509_STORE\fR from the hardcoded default +paths. The library context \fIlibctx\fR and property query \fIpropq\fR are used when +fetching algorithms from providers. +.PP +\&\fBX509_STORE_set_default_paths()\fR is similar to +\&\fBX509_STORE_set_default_paths_ex()\fR but uses NULL for the library +context \fIlibctx\fR and property query \fIpropq\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_add_cert()\fR, \fBX509_STORE_add_crl()\fR, \fBX509_STORE_set_depth()\fR, +\&\fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR, \fBX509_STORE_set_trust()\fR, +\&\fBX509_STORE_load_file_ex()\fR, \fBX509_STORE_load_file()\fR, +\&\fBX509_STORE_load_path()\fR, +\&\fBX509_STORE_load_store_ex()\fR, \fBX509_STORE_load_store()\fR, +\&\fBX509_STORE_load_locations_ex()\fR, \fBX509_STORE_load_locations()\fR, +\&\fBX509_STORE_set_default_paths_ex()\fR and \fBX509_STORE_set_default_paths()\fR +return 1 on success or 0 on failure. +.PP +\&\fBX509_STORE_add_lookup()\fR returns the found or created +\&\fBX509_LOOKUP\fR\|(3), or NULL on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_LOOKUP_hash_dir\fR\|(3). +\&\fBX509_VERIFY_PARAM_set_depth\fR\|(3). +\&\fBX509_STORE_new\fR\|(3), +\&\fBX509_STORE_get0_param\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBX509_STORE_set_default_paths_ex()\fR, +\&\fBX509_STORE_load_file_ex()\fR, \fBX509_STORE_load_store_ex()\fR and +\&\fBX509_STORE_load_locations_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_get0_param.3 b/static/netbsd/man3/X509_STORE_get0_param.3 new file mode 100644 index 00000000..7a745477 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_get0_param.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: X509_STORE_get0_param.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_get0_param 3" +.TH X509_STORE_get0_param 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_get0_param, X509_STORE_set1_param, +X509_STORE_get1_objects, X509_STORE_get0_objects, X509_STORE_get1_all_certs +\&\- X509_STORE setter and getter functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_VERIFY_PARAM *X509_STORE_get0_param(const X509_STORE *xs); +\& int X509_STORE_set1_param(X509_STORE *xs, const X509_VERIFY_PARAM *pm); +\& STACK_OF(X509_OBJECT) *X509_STORE_get1_objects(X509_STORE *xs); +\& STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(const X509_STORE *xs); +\& STACK_OF(X509) *X509_STORE_get1_all_certs(X509_STORE *xs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_STORE_set1_param()\fR sets the verification parameters to \fIpm\fR for \fIxs\fR. +.PP +\&\fBX509_STORE_get0_param()\fR retrieves an internal pointer to the verification +parameters for \fIxs\fR. The returned pointer must not be freed by the +calling application +.PP +\&\fBX509_STORE_get1_objects()\fR returns a snapshot of all objects in the store\*(Aqs X509 +cache. The cache contains \fBX509\fR and \fBX509_CRL\fR objects. The caller +is responsible for freeing the returned list, +using sk_X509_OBJECT_pop_free(sk, X509_OBJECT_free). +.PP +\&\fBX509_STORE_get0_objects()\fR retrieves an internal pointer to the store\*(Aqs +X509 object cache. The cache contains \fBX509\fR and \fBX509_CRL\fR objects. The +returned pointer must not be freed by the calling application. If the store is +shared across multiple threads, it is not safe to use the result of this +function. Use \fBX509_STORE_get1_objects()\fR instead, which avoids this problem. +.PP +\&\fBX509_STORE_get1_all_certs()\fR returns a list of all certificates in the store. +The caller is responsible for freeing the returned list +with \fBOSSL_STACK_OF_X509_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_get0_param()\fR returns a pointer to an +\&\fBX509_VERIFY_PARAM\fR structure. +.PP +\&\fBX509_STORE_set1_param()\fR returns 1 for success and 0 for failure. +.PP +\&\fBX509_STORE_get1_objects()\fR returns a pointer to a stack of the retrieved +objects on success, else NULL. +.PP +\&\fBX509_STORE_get0_objects()\fR returns a pointer to a stack of \fBX509_OBJECT\fR. +.PP +\&\fBX509_STORE_get1_all_certs()\fR returns a pointer to a stack of the retrieved +certificates on success, else NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBDEFINE_STACK_OF\fR\|(3), +\&\fBX509_STORE_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_STORE_get0_param\fR and \fBX509_STORE_get0_objects\fR were added in +OpenSSL 1.1.0. +\&\fBX509_STORE_get1_certs\fR was added in OpenSSL 3.0. +\&\fBX509_STORE_get1_objects\fR was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_new.3 b/static/netbsd/man3/X509_STORE_new.3 new file mode 100644 index 00000000..c916372f --- /dev/null +++ b/static/netbsd/man3/X509_STORE_new.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: X509_STORE_new.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_new 3" +.TH X509_STORE_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, +X509_STORE_lock,X509_STORE_unlock +\&\- X509_STORE allocation, freeing and locking functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_STORE *X509_STORE_new(void); +\& void X509_STORE_free(X509_STORE *xs); +\& int X509_STORE_lock(X509_STORE *xs); +\& int X509_STORE_unlock(X509_STORE *xs); +\& int X509_STORE_up_ref(X509_STORE *xs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_STORE_new()\fR function returns a new X509_STORE. +.PP +\&\fBX509_STORE_up_ref()\fR increments the reference count associated with the +X509_STORE object. +.PP +\&\fBX509_STORE_lock()\fR locks the store from modification by other threads, +\&\fBX509_STORE_unlock()\fR unlocks it. +.PP +\&\fBX509_STORE_free()\fR frees up a single X509_STORE object. +If the argument is NULL, nothing is done. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_STORE_new()\fR returns a newly created X509_STORE or NULL if the call fails. +.PP +\&\fBX509_STORE_up_ref()\fR, \fBX509_STORE_lock()\fR and \fBX509_STORE_unlock()\fR return +1 for success and 0 for failure. +.PP +\&\fBX509_STORE_free()\fR does not return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_STORE_set_verify_cb_func\fR\|(3) +\&\fBX509_STORE_get0_param\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_STORE_up_ref()\fR, \fBX509_STORE_lock()\fR and \fBX509_STORE_unlock()\fR +functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_STORE_set_verify_cb_func.3 b/static/netbsd/man3/X509_STORE_set_verify_cb_func.3 new file mode 100644 index 00000000..cf371531 --- /dev/null +++ b/static/netbsd/man3/X509_STORE_set_verify_cb_func.3 @@ -0,0 +1,343 @@ +.\" $NetBSD: X509_STORE_set_verify_cb_func.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_STORE_set_verify_cb_func 3" +.TH X509_STORE_set_verify_cb_func 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_STORE_set_lookup_crls_cb, +X509_STORE_set_verify_func, +X509_STORE_get_cleanup, +X509_STORE_set_cleanup, +X509_STORE_get_lookup_crls, +X509_STORE_set_lookup_crls, +X509_STORE_get_lookup_certs, +X509_STORE_set_lookup_certs, +X509_STORE_get_check_policy, +X509_STORE_set_check_policy, +X509_STORE_get_cert_crl, +X509_STORE_set_cert_crl, +X509_STORE_get_check_crl, +X509_STORE_set_check_crl, +X509_STORE_get_get_crl, +X509_STORE_set_get_crl, +X509_STORE_get_check_revocation, +X509_STORE_set_check_revocation, +X509_STORE_get_check_issued, +X509_STORE_set_check_issued, +X509_STORE_CTX_get1_issuer, +X509_STORE_get_get_issuer, +X509_STORE_set_get_issuer, +X509_STORE_CTX_get_verify, +X509_STORE_set_verify, +X509_STORE_get_verify_cb, +X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb, +X509_STORE_CTX_cert_crl_fn, X509_STORE_CTX_check_crl_fn, +X509_STORE_CTX_check_issued_fn, X509_STORE_CTX_check_policy_fn, +X509_STORE_CTX_check_revocation_fn, X509_STORE_CTX_cleanup_fn, +X509_STORE_CTX_get_crl_fn, X509_STORE_CTX_get_issuer_fn, +X509_STORE_CTX_lookup_certs_fn, X509_STORE_CTX_lookup_crls_fn +\&\- set verification callback +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer, +\& X509_STORE_CTX *ctx, X509 *x); +\& typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx, +\& X509 *x, X509 *issuer); +\& typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx); +\& typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx, +\& X509_CRL **crl, X509 *x); +\& typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl); +\& typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx, +\& X509_CRL *crl, X509 *x); +\& typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx); +\& typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx, +\& const X509_NAME *nm); +\& typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(const +\& X509_STORE_CTX *ctx, +\& const X509_NAME *nm); +\& typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_verify_cb(X509_STORE *xs, +\& X509_STORE_CTX_verify_cb verify_cb); +\& X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_verify(X509_STORE *xs, X509_STORE_CTX_verify_fn verify); +\& X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(const X509_STORE_CTX *ctx); +\& +\& int X509_STORE_CTX_get1_issuer(X509 **issuer, X509_STORE_CTX *ctx, X509 *x); +\& X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(const X509_STORE_CTX *ctx); +\& void X509_STORE_set_get_issuer(X509_STORE *xs, +\& X509_STORE_CTX_get_issuer_fn get_issuer); +\& +\& void X509_STORE_set_check_issued(X509_STORE *xs, +\& X509_STORE_CTX_check_issued_fn check_issued); +\& X509_STORE_CTX_check_issued_fn +\& X509_STORE_get_check_issued(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_check_revocation(X509_STORE *xs, +\& X509_STORE_CTX_check_revocation_fn check_revocation); +\& X509_STORE_CTX_check_revocation_fn +\& X509_STORE_get_check_revocation(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_get_crl(X509_STORE *xs, +\& X509_STORE_CTX_get_crl_fn get_crl); +\& X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_check_crl(X509_STORE *xs, +\& X509_STORE_CTX_check_crl_fn check_crl); +\& X509_STORE_CTX_check_crl_fn +\& X509_STORE_get_check_crl(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_cert_crl(X509_STORE *xs, +\& X509_STORE_CTX_cert_crl_fn cert_crl); +\& X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_check_policy(X509_STORE *xs, +\& X509_STORE_CTX_check_policy_fn check_policy); +\& X509_STORE_CTX_check_policy_fn +\& X509_STORE_get_check_policy(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_lookup_certs(X509_STORE *xs, +\& X509_STORE_CTX_lookup_certs_fn lookup_certs); +\& X509_STORE_CTX_lookup_certs_fn +\& X509_STORE_get_lookup_certs(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_lookup_crls(X509_STORE *xs, +\& X509_STORE_CTX_lookup_crls_fn lookup_crls); +\& X509_STORE_CTX_lookup_crls_fn +\& X509_STORE_get_lookup_crls(const X509_STORE_CTX *ctx); +\& +\& void X509_STORE_set_cleanup(X509_STORE *xs, +\& X509_STORE_CTX_cleanup_fn cleanup); +\& X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(const X509_STORE_CTX *ctx); +\& +\& /* Aliases */ +\& void X509_STORE_set_verify_cb_func(X509_STORE *st, +\& X509_STORE_CTX_verify_cb verify_cb); +\& void X509_STORE_set_verify_func(X509_STORE *xs, +\& X509_STORE_CTX_verify_fn verify); +\& void X509_STORE_set_lookup_crls_cb(X509_STORE *xs, +\& X509_STORE_CTX_lookup_crls_fn lookup_crls); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_STORE_set_verify_cb()\fR sets the verification callback of \fIxs\fR to +\&\fIverify_cb\fR overwriting the previous callback. +The callback assigned with this function becomes a default for the one +that can be assigned directly to the corresponding \fBX509_STORE_CTX\fR, +please see \fBX509_STORE_CTX_set_verify_cb\fR\|(3) for further information. +.PP +\&\fBX509_STORE_set_verify()\fR sets the final chain verification function for +\&\fIxs\fR to \fIverify\fR. +Its purpose is to go through the chain of certificates and check that +all signatures are valid and that the current time is within the +limits of each certificate\*(Aqs first and last validity time. +The final chain verification functions must return 0 on failure and 1 +on success. +\&\fIIf no chain verification function is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_CTX_get1_issuer()\fR tries to find a certificate from the \fIstore\fR +component of \fIctx\fR that has a subject name matching the issuer name of \fIx\fR +and is accepted by the \fIcheck_issued\fR function in \fIctx\fR. +On success it assigns to \fI*issuer\fR the first match that has a suitable validity +period or otherwise has the latest expiration date of all matching certificates. +If the function returns 1 the caller is responsible for freeing \fI*issuer\fR. +Note that this search does not support backtracking. +.PP +\&\fBX509_STORE_set_get_issuer()\fR sets the function \fIget_issuer\fR that is used +to get the "best" candidate issuer certificate of the given certificate \fIx\fR. +When such a certificate is found, \fIget_issuer\fR must up\-ref and assign it +to \fI*issuer\fR and then return 1. +Otherwise \fIget_issuer\fR must return 0 if not found and \-1 (or 0) on failure. +If \fBX509_STORE_set_get_issuer()\fR is not used or \fIget_issuer\fR is NULL +then \fBX509_STORE_CTX_get1_issuer()\fR is used as the default implementation. +.PP +\&\fBX509_STORE_set_check_issued()\fR sets the function to check that a given +certificate \fIx\fR is issued by the issuer certificate \fIissuer\fR. +This function must return 0 on failure (among others if \fIx\fR hasn\*(Aqt +been issued with \fIissuer\fR) and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_check_revocation()\fR sets the revocation checking +function. +Its purpose is to look through the final chain and check the +revocation status for each certificate. +It must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_get_crl()\fR sets the function to get the crl for a given +certificate \fIx\fR. +When found, the crl must be assigned to \fI*crl\fR. +This function must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_check_crl()\fR sets the function to check the validity of +the given \fIcrl\fR. +This function must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_cert_crl()\fR sets the function to check the revocation +status of the given certificate \fIx\fR against the given \fIcrl\fR. +This function must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_check_policy()\fR sets the function to check the policies +of all the certificates in the final chain.. +This function must return 0 on failure and 1 on success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_lookup_certs()\fR and \fBX509_STORE_set_lookup_crls()\fR set the +functions to look up all the certs or all the CRLs that match the +given name \fInm\fR. +These functions return NULL on failure and a pointer to a stack of +certificates (\fBX509\fR) or to a stack of CRLs (\fBX509_CRL\fR) on +success. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_set_cleanup()\fR sets the final cleanup function, which is +called when the context (\fBX509_STORE_CTX\fR) is being torn down. +This function doesn\*(Aqt return any value. +\&\fIIf no function to get the issuer is provided, the internal default +function will be used instead.\fR +.PP +\&\fBX509_STORE_get_verify_cb()\fR, \fBX509_STORE_CTX_get_verify()\fR, +\&\fBX509_STORE_get_get_issuer()\fR, \fBX509_STORE_get_check_issued()\fR, +\&\fBX509_STORE_get_check_revocation()\fR, \fBX509_STORE_get_get_crl()\fR, +\&\fBX509_STORE_get_check_crl()\fR, \fBX509_STORE_set_verify()\fR, +\&\fBX509_STORE_set_get_issuer()\fR, \fBX509_STORE_get_cert_crl()\fR, +\&\fBX509_STORE_get_check_policy()\fR, \fBX509_STORE_get_lookup_certs()\fR, +\&\fBX509_STORE_get_lookup_crls()\fR and \fBX509_STORE_get_cleanup()\fR all return +the function pointer assigned with \fBX509_STORE_set_check_issued()\fR, +\&\fBX509_STORE_set_check_revocation()\fR, \fBX509_STORE_set_get_crl()\fR, +\&\fBX509_STORE_set_check_crl()\fR, \fBX509_STORE_set_cert_crl()\fR, +\&\fBX509_STORE_set_check_policy()\fR, \fBX509_STORE_set_lookup_certs()\fR, +\&\fBX509_STORE_set_lookup_crls()\fR and \fBX509_STORE_set_cleanup()\fR, or NULL if +no assignment has been made. +.PP +\&\fBX509_STORE_set_verify_cb_func()\fR, \fBX509_STORE_set_verify_func()\fR and +\&\fBX509_STORE_set_lookup_crls_cb()\fR are aliases for +\&\fBX509_STORE_set_verify_cb()\fR, \fBX509_STORE_set_verify()\fR and +X509_STORE_set_lookup_crls, available as macros for backward +compatibility. +.SH NOTES +.IX Header "NOTES" +All the callbacks from a \fBX509_STORE\fR are inherited by the +corresponding \fBX509_STORE_CTX\fR structure when it is initialized. +See \fBX509_STORE_CTX_set_verify_cb\fR\|(3) for further details. +.SH BUGS +.IX Header "BUGS" +The macro version of this function was the only one available before +OpenSSL 1.0.0. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The X509_STORE_set_*() functions do not return a value. +.PP +The X509_STORE_get_*() functions return a pointer of the appropriate +function type. +.PP +\&\fBX509_STORE_CTX_get1_issuer()\fR returns +1 if a suitable certificate is found, 0 if not found, \-1 on other error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_STORE_CTX_set_verify_cb\fR\|(3), \fBX509_STORE_CTX_get0_chain\fR\|(3), +\&\fBX509_STORE_CTX_verify_cb\fR\|(3), \fBX509_STORE_CTX_verify_fn\fR\|(3), +\&\fBCMS_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_STORE_set_verify_cb()\fR function was added in OpenSSL 1.0.0. +.PP +The functions +\&\fBX509_STORE_set_verify_cb()\fR, \fBX509_STORE_get_verify_cb()\fR, +\&\fBX509_STORE_set_verify()\fR, \fBX509_STORE_CTX_get_verify()\fR, +\&\fBX509_STORE_set_get_issuer()\fR, \fBX509_STORE_get_get_issuer()\fR, +\&\fBX509_STORE_set_check_issued()\fR, \fBX509_STORE_get_check_issued()\fR, +\&\fBX509_STORE_set_check_revocation()\fR, \fBX509_STORE_get_check_revocation()\fR, +\&\fBX509_STORE_set_get_crl()\fR, \fBX509_STORE_get_get_crl()\fR, +\&\fBX509_STORE_set_check_crl()\fR, \fBX509_STORE_get_check_crl()\fR, +\&\fBX509_STORE_set_cert_crl()\fR, \fBX509_STORE_get_cert_crl()\fR, +\&\fBX509_STORE_set_check_policy()\fR, \fBX509_STORE_get_check_policy()\fR, +\&\fBX509_STORE_set_lookup_certs()\fR, \fBX509_STORE_get_lookup_certs()\fR, +\&\fBX509_STORE_set_lookup_crls()\fR, \fBX509_STORE_get_lookup_crls()\fR, +\&\fBX509_STORE_set_cleanup()\fR and \fBX509_STORE_get_cleanup()\fR +were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_VERIFY_PARAM_set_flags.3 b/static/netbsd/man3/X509_VERIFY_PARAM_set_flags.3 new file mode 100644 index 00000000..0530f40f --- /dev/null +++ b/static/netbsd/man3/X509_VERIFY_PARAM_set_flags.3 @@ -0,0 +1,481 @@ +.\" $NetBSD: X509_VERIFY_PARAM_set_flags.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_VERIFY_PARAM_set_flags 3" +.TH X509_VERIFY_PARAM_set_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, +X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, +X509_VERIFY_PARAM_get_purpose, +X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags, +X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, +X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, +X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, +X509_VERIFY_PARAM_get_time, +X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, +X509_VERIFY_PARAM_get0_host, +X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, +X509_VERIFY_PARAM_set_hostflags, +X509_VERIFY_PARAM_get_hostflags, +X509_VERIFY_PARAM_get0_peername, +X509_VERIFY_PARAM_get0_email, X509_VERIFY_PARAM_set1_email, +X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_get1_ip_asc, +X509_VERIFY_PARAM_set1_ip_asc +\&\- X509 verification parameters +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, +\& unsigned long flags); +\& int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, +\& unsigned long flags); +\& unsigned long X509_VERIFY_PARAM_get_flags(const X509_VERIFY_PARAM *param); +\& +\& int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, +\& uint32_t flags); +\& uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param); +\& +\& int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); +\& int X509_VERIFY_PARAM_get_purpose(X509_VERIFY_PARAM *param); +\& int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); +\& +\& void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); +\& time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param); +\& +\& int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, +\& ASN1_OBJECT *policy); +\& int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, +\& STACK_OF(ASN1_OBJECT) *policies); +\& +\& void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); +\& int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); +\& +\& void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, +\& int auth_level); +\& int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); +\& +\& char *X509_VERIFY_PARAM_get0_host(X509_VERIFY_PARAM *param, int n); +\& int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, +\& const char *name, size_t namelen); +\& int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, +\& const char *name, size_t namelen); +\& void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, +\& unsigned int flags); +\& unsigned int X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param); +\& char *X509_VERIFY_PARAM_get0_peername(const X509_VERIFY_PARAM *param); +\& char *X509_VERIFY_PARAM_get0_email(X509_VERIFY_PARAM *param); +\& int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, +\& const char *email, size_t emaillen); +\& char *X509_VERIFY_PARAM_get1_ip_asc(X509_VERIFY_PARAM *param); +\& int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, +\& const unsigned char *ip, size_t iplen); +\& int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions manipulate the \fBX509_VERIFY_PARAM\fR structure associated with +a certificate verification operation. +.PP +The \fBX509_VERIFY_PARAM_set_flags()\fR function sets the flags in \fBparam\fR by oring +it with \fBflags\fR. See "VERIFICATION FLAGS" for a complete +description of values the \fBflags\fR parameter can take. +.PP +\&\fBX509_VERIFY_PARAM_get_flags()\fR returns the flags in \fBparam\fR. +.PP +\&\fBX509_VERIFY_PARAM_get_inh_flags()\fR returns the inheritance flags in \fBparam\fR +which specifies how verification flags are copied from one structure to +another. \fBX509_VERIFY_PARAM_set_inh_flags()\fR sets the inheritance flags. +See the \fBINHERITANCE FLAGS\fR section for a description of these bits. +.PP +\&\fBX509_VERIFY_PARAM_clear_flags()\fR clears the flags \fBflags\fR in \fBparam\fR. +.PP +\&\fBX509_VERIFY_PARAM_set_purpose()\fR sets the verification purpose in \fBparam\fR +to \fBpurpose\fR. This determines the acceptable purpose of the certificate +chain, for example \fBX509_PURPOSE_SSL_CLIENT\fR. +The purpose requirement is cleared if \fBpurpose\fR is X509_PURPOSE_DEFAULT_ANY. +.PP +\&\fBX509_VERIFY_PARAM_get_purpose()\fR returns the purpose in \fBparam\fR. +.PP +\&\fBX509_VERIFY_PARAM_set_trust()\fR sets the trust setting in \fBparam\fR to +\&\fBtrust\fR. +.PP +\&\fBX509_VERIFY_PARAM_set_time()\fR sets the verification time in \fBparam\fR to +\&\fBt\fR. Normally the current time is used. +.PP +\&\fBX509_VERIFY_PARAM_add0_policy()\fR adds \fBpolicy\fR to the acceptable policy set. +Contrary to preexisting documentation of this function it does not enable +policy checking. +.PP +\&\fBX509_VERIFY_PARAM_set1_policies()\fR enables policy checking (it is disabled +by default) and sets the acceptable policy set to \fBpolicies\fR. Any existing +policy set is cleared. The \fBpolicies\fR parameter can be \fBNULL\fR to clear +an existing policy set. +.PP +\&\fBX509_VERIFY_PARAM_set_depth()\fR sets the maximum verification depth to \fBdepth\fR. +That is the maximum number of intermediate CA certificates that can appear in a +chain. +A maximal depth chain contains 2 more certificates than the limit, since +neither the end\-entity certificate nor the trust\-anchor count against this +limit. +Thus a \fBdepth\fR limit of 0 only allows the end\-entity certificate to be signed +directly by the trust anchor, while with a \fBdepth\fR limit of 1 there can be one +intermediate CA certificate between the trust anchor and the end\-entity +certificate. +.PP +\&\fBX509_VERIFY_PARAM_set_auth_level()\fR sets the authentication security level to +\&\fBauth_level\fR. +The authentication security level determines the acceptable signature and public +key strength when verifying certificate chains. +For a certificate chain to validate, the public keys of all the certificates +must meet the specified security level. +The signature algorithm security level is not enforced for the chain\*(Aqs \fItrust +anchor\fR certificate, which is either directly trusted or validated by means other +than its signature. +See \fBSSL_CTX_set_security_level\fR\|(3) for the definitions of the available +levels. +The default security level is \-1, or "not set". +At security level 0 or lower all algorithms are acceptable. +Security level 1 requires at least 80\-bit\-equivalent security and is broadly +interoperable, though it will, for example, reject MD5 signatures or RSA keys +shorter than 1024 bits. +.PP +\&\fBX509_VERIFY_PARAM_get0_host()\fR returns the \fBn\fRth expected DNS hostname that has +been set using \fBX509_VERIFY_PARAM_set1_host()\fR or \fBX509_VERIFY_PARAM_add1_host()\fR. +To obtain all names start with \fBn\fR = 0 and increment \fBn\fR as long as no NULL +pointer is returned. +.PP +\&\fBX509_VERIFY_PARAM_set1_host()\fR sets the expected DNS hostname to +\&\fBname\fR clearing any previously specified hostname. If +\&\fBname\fR is NULL, or empty the list of hostnames is cleared, and +name checks are not performed on the peer certificate. If \fBname\fR +is NUL\-terminated, \fBnamelen\fR may be zero, otherwise \fBnamelen\fR +must be set to the length of \fBname\fR. +.PP +When a hostname is specified, +certificate verification automatically invokes \fBX509_check_host\fR\|(3) +with flags equal to the \fBflags\fR argument given to +\&\fBX509_VERIFY_PARAM_set_hostflags()\fR (default zero). Applications +are strongly advised to use this interface in preference to explicitly +calling \fBX509_check_host\fR\|(3), hostname checks may be out of scope +with the \fBDANE\-EE\fR\|(3) certificate usage, and the internal check will +be suppressed as appropriate when DANE verification is enabled. +.PP +When the subject CommonName will not be ignored, whether as a result of the +\&\fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR host flag, or because no DNS subject +alternative names are present in the certificate, any DNS name constraints in +issuer certificates apply to the subject CommonName as well as the subject +alternative name extension. +.PP +When the subject CommonName will be ignored, whether as a result of the +\&\fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR host flag, or because some DNS subject +alternative names are present in the certificate, DNS name constraints in +issuer certificates will not be applied to the subject DN. +As described in \fBX509_check_host\fR\|(3) the \fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR +flag takes precedence over the \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR flag. +.PP +\&\fBX509_VERIFY_PARAM_get_hostflags()\fR returns any host flags previously set via a +call to \fBX509_VERIFY_PARAM_set_hostflags()\fR. +.PP +\&\fBX509_VERIFY_PARAM_add1_host()\fR adds \fBname\fR as an additional reference +identifier that can match the peer\*(Aqs certificate. Any previous names +set via \fBX509_VERIFY_PARAM_set1_host()\fR or \fBX509_VERIFY_PARAM_add1_host()\fR +are retained, no change is made if \fBname\fR is NULL or empty. When +multiple names are configured, the peer is considered verified when +any name matches. +.PP +\&\fBX509_VERIFY_PARAM_get0_peername()\fR returns the DNS hostname or subject +CommonName from the peer certificate that matched one of the reference +identifiers. When wildcard matching is not disabled, or when a +reference identifier specifies a parent domain (starts with ".") +rather than a hostname, the peer name may be a wildcard name or a +sub\-domain of the reference identifier respectively. The return +string is allocated by the library and is no longer valid once the +associated \fBparam\fR argument is freed. Applications must not free +the return value. +.PP +\&\fBX509_VERIFY_PARAM_get0_email()\fR returns the expected RFC822 email address. +.PP +\&\fBX509_VERIFY_PARAM_set1_email()\fR sets the expected RFC822 email address to +\&\fBemail\fR. If \fBemail\fR is NUL\-terminated, \fBemaillen\fR may be zero, otherwise +\&\fBemaillen\fR must be set to the length of \fBemail\fR. When an email address +is specified, certificate verification automatically invokes +\&\fBX509_check_email\fR\|(3). +.PP +\&\fBX509_VERIFY_PARAM_get1_ip_asc()\fR returns the expected IP address as a string. +The caller is responsible for freeing it. +.PP +\&\fBX509_VERIFY_PARAM_set1_ip()\fR sets the expected IP address to \fBip\fR. +The \fBip\fR argument is in binary format, in network byte\-order and +\&\fBiplen\fR must be set to 4 for IPv4 and 16 for IPv6. When an IP +address is specified, certificate verification automatically invokes +\&\fBX509_check_ip\fR\|(3). +.PP +\&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR sets the expected IP address to +\&\fBipasc\fR. The \fBipasc\fR argument is a NUL\-terminal ASCII string: +dotted decimal quad for IPv4 and colon\-separated hexadecimal for +IPv6. The condensed "::" notation is supported for IPv6 addresses. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_VERIFY_PARAM_set_flags()\fR, \fBX509_VERIFY_PARAM_clear_flags()\fR, +\&\fBX509_VERIFY_PARAM_set_inh_flags()\fR, +\&\fBX509_VERIFY_PARAM_set_purpose()\fR, \fBX509_VERIFY_PARAM_set_trust()\fR, +\&\fBX509_VERIFY_PARAM_add0_policy()\fR \fBX509_VERIFY_PARAM_set1_policies()\fR, +\&\fBX509_VERIFY_PARAM_set1_host()\fR, \fBX509_VERIFY_PARAM_add1_host()\fR, +\&\fBX509_VERIFY_PARAM_set1_email()\fR, \fBX509_VERIFY_PARAM_set1_ip()\fR and +\&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR return 1 for success and 0 for +failure. +.PP +\&\fBX509_VERIFY_PARAM_get0_host()\fR, \fBX509_VERIFY_PARAM_get0_email()\fR, and +\&\fBX509_VERIFY_PARAM_get1_ip_asc()\fR, return the string pointers specified above +or NULL if the respective value has not been set or on error. +.PP +\&\fBX509_VERIFY_PARAM_get_flags()\fR returns the current verification flags. +.PP +\&\fBX509_VERIFY_PARAM_get_hostflags()\fR returns any current host flags. +.PP +\&\fBX509_VERIFY_PARAM_get_inh_flags()\fR returns the current inheritance flags. +.PP +\&\fBX509_VERIFY_PARAM_set_time()\fR and \fBX509_VERIFY_PARAM_set_depth()\fR do not return +values. +.PP +\&\fBX509_VERIFY_PARAM_get_depth()\fR returns the current verification depth. +.PP +\&\fBX509_VERIFY_PARAM_get_auth_level()\fR returns the current authentication security +level. +.PP +\&\fBX509_VERIFY_PARAM_get_purpose()\fR returns the current purpose, +which may be \fBX509_PURPOSE_DEFAULT_ANY\fR if unset. +.SH "VERIFICATION FLAGS" +.IX Header "VERIFICATION FLAGS" +The verification flags consists of zero or more of the following flags +ored together. +.PP +\&\fBX509_V_FLAG_CRL_CHECK\fR enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. +.PP +\&\fBX509_V_FLAG_CRL_CHECK_ALL\fR expands CRL checking to the entire certificate +chain if \fBX509_V_FLAG_CRL_CHECK\fR has also been enabled, and is otherwise ignored. +.PP +\&\fBX509_V_FLAG_IGNORE_CRITICAL\fR disables critical extension checking. By default +any unhandled critical extensions in certificates or (if checked) CRLs result +in a fatal error. If this flag is set unhandled critical extensions are +ignored. \fBWARNING\fR setting this option for anything other than debugging +purposes can be a security risk. Finer control over which extensions are +supported can be performed in the verification callback. +.PP +The \fBX509_V_FLAG_X509_STRICT\fR flag disables workarounds for some broken +certificates and makes the verification strictly apply \fBX509\fR rules. +.PP +\&\fBX509_V_FLAG_ALLOW_PROXY_CERTS\fR enables proxy certificate verification. +.PP +\&\fBX509_V_FLAG_POLICY_CHECK\fR enables certificate policy checking, by default +no policy checking is performed. Additional information is sent to the +verification callback relating to policy checking. +.PP +\&\fBX509_V_FLAG_EXPLICIT_POLICY\fR, \fBX509_V_FLAG_INHIBIT_ANY\fR and +\&\fBX509_V_FLAG_INHIBIT_MAP\fR set the \fBrequire explicit policy\fR, \fBinhibit any +policy\fR and \fBinhibit policy mapping\fR flags respectively as defined in +\&\fBRFC3280\fR. Policy checking is automatically enabled if any of these flags +are set. +.PP +If \fBX509_V_FLAG_NOTIFY_POLICY\fR is set and the policy checking is successful +a special status code is set to the verification callback. This permits it +to examine the valid policy tree and perform additional checks or simply +log it for debugging purposes. +.PP +By default some additional features such as indirect CRLs and CRLs signed by +different keys are disabled. If \fBX509_V_FLAG_EXTENDED_CRL_SUPPORT\fR is set +they are enabled. +.PP +If \fBX509_V_FLAG_USE_DELTAS\fR is set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. +.PP +\&\fBX509_V_FLAG_CHECK_SS_SIGNATURE\fR requests checking the signature of +the last certificate in a chain if the certificate is supposedly self\-signed. +This is prohibited and will result in an error if it is a non\-conforming CA +certificate with key usage restrictions not including the \fIkeyCertSign\fR bit. +By default this check is disabled because it doesn\*(Aqt +add any additional security but in some cases applications might want to +check the signature anyway. A side effect of not checking the self\-signature +of such a certificate is that disabled or unsupported message digests used for +the signature are not treated as fatal errors. +.PP +When \fBX509_V_FLAG_TRUSTED_FIRST\fR is set, which is always the case since +OpenSSL 1.1.0, construction of the certificate chain +in \fBX509_verify_cert\fR\|(3) searches the trust store for issuer certificates +before searching the provided untrusted certificates. +Local issuer certificates are often more likely to satisfy local security +requirements and lead to a locally trusted root. +This is especially important when some certificates in the trust store have +explicit trust settings (see "TRUST SETTINGS" in \fBopenssl\-x509\fR\|(1)). +.PP +The \fBX509_V_FLAG_NO_ALT_CHAINS\fR flag could have been used before OpenSSL 1.1.0 +to suppress checking for alternative chains. +By default, unless \fBX509_V_FLAG_TRUSTED_FIRST\fR is set, when building a +certificate chain, if the first certificate chain found is not trusted, then +OpenSSL will attempt to replace untrusted certificates supplied by the peer +with certificates from the trust store to see if an alternative chain can be +found that is trusted. +As of OpenSSL 1.1.0, with \fBX509_V_FLAG_TRUSTED_FIRST\fR always set, this option +has no effect. +.PP +The \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag causes non\-self\-signed certificates in the +trust store to be treated as trust anchors, in the same way as self\-signed +root CA certificates. +This makes it possible to trust self\-issued certificates as well as certificates +issued by an intermediate CA without having to trust their ancestor root CA. +With OpenSSL 1.1.0 and later and \fBX509_V_FLAG_PARTIAL_CHAIN\fR set, chain +construction stops as soon as the first certificate contained in the trust store +is added to the chain, whether that certificate is a self\-signed "root" +certificate or a not self\-signed "intermediate" or self\-issued certificate. +Thus, when an intermediate certificate is found in the trust store, the +verified chain passed to callbacks may be shorter than it otherwise would +be without the \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag. +.PP +The \fBX509_V_FLAG_NO_CHECK_TIME\fR flag suppresses checking the validity period +of certificates and CRLs against the current time. If \fBX509_VERIFY_PARAM_set_time()\fR +is used to specify a verification time, the check is not suppressed. +.SH "INHERITANCE FLAGS" +.IX Header "INHERITANCE FLAGS" +These flags specify how parameters are "inherited" from one structure to +another. +.PP +If \fBX509_VP_FLAG_ONCE\fR is set then the current setting is zeroed +after the next call. +.PP +If \fBX509_VP_FLAG_LOCKED\fR is set then no values are copied. This overrides +all of the following flags. +.PP +If \fBX509_VP_FLAG_DEFAULT\fR is set then anything set in the source is copied +to the destination. Effectively the values in "to" become default values +which will be used only if nothing new is set in "from". This is the +default. +.PP +If \fBX509_VP_FLAG_OVERWRITE\fR is set then all value are copied across whether +they are set or not. Flags is still Ored though. +.PP +If \fBX509_VP_FLAG_RESET_FLAGS\fR is set then the flags value is copied instead +of ORed. +.SH NOTES +.IX Header "NOTES" +The above functions should be used to manipulate verification parameters +instead of functions which work in specific structures such as +\&\fBX509_STORE_CTX_set_flags()\fR which are likely to be deprecated in a future +release. +.SH BUGS +.IX Header "BUGS" +Delta CRL checking is currently primitive. Only a single delta can be used and +(partly due to limitations of \fBX509_STORE\fR) constructed CRLs are not +maintained. +.PP +If CRLs checking is enable CRLs are expected to be available in the +corresponding \fBX509_STORE\fR structure. No attempt is made to download +CRLs from the CRL distribution points extension. +.SH EXAMPLES +.IX Header "EXAMPLES" +Enable CRL checking when performing certificate verification during SSL +connections associated with an \fBSSL_CTX\fR structure \fBctx\fR: +.PP +.Vb 1 +\& X509_VERIFY_PARAM *param; +\& +\& param = X509_VERIFY_PARAM_new(); +\& X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); +\& SSL_CTX_set1_param(ctx, param); +\& X509_VERIFY_PARAM_free(param); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify_cert\fR\|(3), +\&\fBX509_check_host\fR\|(3), +\&\fBX509_check_email\fR\|(3), +\&\fBX509_check_ip\fR\|(3), +\&\fBopenssl\-x509\fR\|(1) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_V_FLAG_NO_ALT_CHAINS\fR flag was added in OpenSSL 1.1.0. +The flag \fBX509_V_FLAG_CB_ISSUER_CHECK\fR was deprecated in OpenSSL 1.1.0 +and has no effect. +.PP +The \fBX509_VERIFY_PARAM_get_hostflags()\fR function was added in OpenSSL 1.1.0i. +.PP +The \fBX509_VERIFY_PARAM_get0_host()\fR, \fBX509_VERIFY_PARAM_get0_email()\fR, +and \fBX509_VERIFY_PARAM_get1_ip_asc()\fR functions were added in OpenSSL 3.0. +.PP +The function \fBX509_VERIFY_PARAM_add0_policy()\fR was historically documented as +enabling policy checking however the implementation has never done this. +The documentation was changed to align with the implementation. +.PP +The \fBX509_VERIFY_PARAM_get_purpose()\fR function was added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_add_cert.3 b/static/netbsd/man3/X509_add_cert.3 new file mode 100644 index 00000000..1caa7cd2 --- /dev/null +++ b/static/netbsd/man3/X509_add_cert.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: X509_add_cert.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_add_cert 3" +.TH X509_add_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_add_cert, +X509_add_certs \- +X509 certificate list addition functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_add_cert(STACK_OF(X509) *sk, X509 *cert, int flags); +\& int X509_add_certs(STACK_OF(X509) *sk, STACK_OF(X509) *certs, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_add_cert()\fR adds a certificate \fIcert\fR to the given list \fIsk\fR. +It is an error for the \fIcert\fR argument to be NULL. +.PP +\&\fBX509_add_certs()\fR adds a list of certificate \fIcerts\fR to the given list \fIsk\fR. +The \fIcerts\fR argument may be NULL, which implies no effect. +It does not modify the list \fIcerts\fR but +in case the \fBX509_ADD_FLAG_UP_REF\fR flag (described below) is set +the reference counters of those of its members added to \fIsk\fR are increased. +.PP +Both these functions have a \fIflags\fR parameter, +which is used to control details of the operation. +.PP +The value \fBX509_ADD_FLAG_DEFAULT\fR, which equals 0, means no special semantics. +.PP +If \fBX509_ADD_FLAG_UP_REF\fR is set then +the reference counts of those certificates added successfully are increased. +.PP +If \fBX509_ADD_FLAG_PREPEND\fR is set then the certificates are prepended to \fIsk\fR. +By default they are appended to \fIsk\fR. +In both cases the original order of the added certificates is preserved. +.PP +If \fBX509_ADD_FLAG_NO_DUP\fR is set then certificates already contained in \fIsk\fR, +which is determined using \fBX509_cmp\fR\|(3), are ignored. +.PP +If \fBX509_ADD_FLAG_NO_SS\fR is set then certificates that are marked self\-signed, +which is determined using \fBX509_self_signed\fR\|(3), are ignored. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Both functions return 1 for success and 0 for failure. +.SH NOTES +.IX Header "NOTES" +If \fBX509_add_certs()\fR is used with the flags \fBX509_ADD_FLAG_NO_DUP\fR or +\&\fBX509_ADD_FLAG_NO_SS\fR it is advisable to use also \fBX509_ADD_FLAG_UP_REF\fR +because otherwise likely not for all members of the \fIcerts\fR list +the ownership is transferred to the list of certificates \fIsk\fR. +.PP +Care should also be taken in case the \fIcerts\fR argument equals \fIsk\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_cmp\fR\|(3) +\&\fBX509_self_signed\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBX509_add_cert()\fR and \fBX509_add_certs()\fR +were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_check_ca.3 b/static/netbsd/man3/X509_check_ca.3 new file mode 100644 index 00000000..47549425 --- /dev/null +++ b/static/netbsd/man3/X509_check_ca.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: X509_check_ca.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_check_ca 3" +.TH X509_check_ca 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_check_ca \- check if given certificate is CA certificate +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_check_ca(X509 *cert); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This function checks if given certificate is CA certificate (can be used +to sign other certificates). The certificate must be a complete certificate +otherwise an error is returned. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Function return 0, if it is not CA certificate, 1 if it is proper X509v3 +CA certificate with \fBbasicConstraints\fR extension CA:TRUE, +3, if it is self\-signed X509 v1 certificate, 4, if it is certificate with +\&\fBkeyUsage\fR extension with bit \fBkeyCertSign\fR set, but without +\&\fBbasicConstraints\fR, and 5 if it has outdated Netscape Certificate Type +extension telling that it is CA certificate. +.PP +This function will also return 0 on error. +.PP +Actually, any nonzero value means that this certificate could have been +used to sign other certificates. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify_cert\fR\|(3), +\&\fBX509_check_issued\fR\|(3), +\&\fBX509_check_purpose\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_check_host.3 b/static/netbsd/man3/X509_check_host.3 new file mode 100644 index 00000000..5a01312f --- /dev/null +++ b/static/netbsd/man3/X509_check_host.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: X509_check_host.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_check_host 3" +.TH X509_check_host 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc \- X.509 certificate matching +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_check_host(X509 *, const char *name, size_t namelen, +\& unsigned int flags, char **peername); +\& int X509_check_email(X509 *, const char *address, size_t addresslen, +\& unsigned int flags); +\& int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, +\& unsigned int flags); +\& int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The certificate matching functions are used to check whether a +certificate matches a given hostname, email address, or IP address. +The validity of the certificate and its trust level has to be checked by +other means. +.PP +\&\fBX509_check_host()\fR checks if the certificate Subject Alternative +Name (SAN) or Subject CommonName (CN) matches the specified hostname, +which must be encoded in the preferred name syntax described +in section 3.5 of RFC 1034. By default, wildcards are supported +and they match only in the left\-most label; but they may match +part of that label with an explicit prefix or suffix. For example, +by default, the host \fBname\fR "www.example.com" would match a +certificate with a SAN or CN value of "*.example.com", "w*.example.com" +or "*w.example.com". +.PP +Per section 6.4.2 of RFC 6125, \fBname\fR values representing international +domain names must be given in A\-label form. The \fBnamelen\fR argument +must be the number of characters in the name string or zero in which +case the length is calculated with strlen(\fBname\fR). When \fBname\fR starts +with a dot (e.g. ".example.com"), it will be matched by a certificate +valid for any sub\-domain of \fBname\fR, (see also +\&\fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR below). +.PP +When the certificate is matched, and \fBpeername\fR is not NULL, a +pointer to a copy of the matching SAN or CN from the peer certificate +is stored at the address passed in \fBpeername\fR. The application +is responsible for freeing the peername via \fBOPENSSL_free()\fR when it +is no longer needed. +.PP +\&\fBX509_check_email()\fR checks if the certificate matches the specified +email \fBaddress\fR. The mailbox syntax of RFC 822 is supported, +comments are not allowed, and no attempt is made to normalize quoted +characters. The mailbox syntax of RFC 6531 is supported for +SmtpUTF8Mailbox address in subjectAltName according to RFC 8398, +with similar limitations as for RFC 822 syntax, and no attempt +is made to convert from A\-label to U\-label before comparison. +The \fBaddresslen\fR argument must be the number of +characters in the address string or zero in which case the length +is calculated with strlen(\fBaddress\fR). +.PP +\&\fBX509_check_ip()\fR checks if the certificate matches a specified IPv4 or +IPv6 address. The \fBaddress\fR array is in binary format, in network +byte order. The length is either 4 (IPv4) or 16 (IPv6). Only +explicitly marked addresses in the certificates are considered; IP +addresses stored in DNS names and Common Names are ignored. There are +currently no \fBflags\fR that would affect the behavior of this call. +.PP +\&\fBX509_check_ip_asc()\fR is similar, except that the NUL\-terminated +string \fBaddress\fR is first converted to the internal representation. +.PP +The \fBflags\fR argument is usually 0. It can be the bitwise OR of the +flags: +.IP \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR, 4 +.IX Item "X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT," +.PD 0 +.IP \fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR, 4 +.IX Item "X509_CHECK_FLAG_NEVER_CHECK_SUBJECT," +.IP \fBX509_CHECK_FLAG_NO_WILDCARDS\fR, 4 +.IX Item "X509_CHECK_FLAG_NO_WILDCARDS," +.IP \fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR, 4 +.IX Item "X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS," +.IP \fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR. 4 +.IX Item "X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS." +.IP \fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR. 4 +.IX Item "X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS." +.PD +.PP +The \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR flag causes the function +to consider the subject DN even if the certificate contains at least +one subject alternative name of the right type (DNS name or email +address as appropriate); the default is to ignore the subject DN +when at least one corresponding subject alternative names is present. +.PP +The \fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR flag causes the function to never +consider the subject DN even if the certificate contains no subject alternative +names of the right type (DNS name or email address as appropriate); the default +is to use the subject DN when no corresponding subject alternative names are +present. +If both \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR and +\&\fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR are specified, the latter takes +precedence and the subject DN is not checked for matching names. +.PP +If set, \fBX509_CHECK_FLAG_NO_WILDCARDS\fR disables wildcard +expansion; this only applies to \fBX509_check_host\fR. +.PP +If set, \fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR suppresses support +for "*" as wildcard pattern in labels that have a prefix or suffix, +such as: "www*" or "*www"; this only applies to \fBX509_check_host\fR. +.PP +If set, \fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR allows a "*" that +constitutes the complete label of a DNS name (e.g. "*.example.com") +to match more than one label in \fBname\fR; this flag only applies +to \fBX509_check_host\fR. +.PP +If set, \fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR restricts \fBname\fR +values which start with ".", that would otherwise match any sub\-domain +in the peer certificate, to only match direct child sub\-domains. +Thus, for instance, with this flag set a \fBname\fR of ".example.com" +would match a peer certificate with a DNS name of "www.example.com", +but would not match a peer certificate with a DNS name of +"www.sub.example.com"; this flag only applies to \fBX509_check_host\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The functions return 1 for a successful match, 0 for a failed match +and \-1 for an internal error: typically a memory allocation failure +or an ASN.1 decoding error. +.PP +All functions can also return \-2 if the input is malformed. For example, +\&\fBX509_check_host()\fR returns \-2 if the provided \fBname\fR contains embedded +NULs. +.SH NOTES +.IX Header "NOTES" +Applications are encouraged to use \fBX509_VERIFY_PARAM_set1_host()\fR +rather than explicitly calling \fBX509_check_host\fR\|(3). Hostname +checks may be out of scope with the \fBDANE\-EE\fR\|(3) certificate usage, +and the internal checks will be suppressed as appropriate when +DANE support is enabled. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBX509_VERIFY_PARAM_set1_host\fR\|(3), +\&\fBX509_VERIFY_PARAM_add1_host\fR\|(3), +\&\fBX509_VERIFY_PARAM_set1_email\fR\|(3), +\&\fBX509_VERIFY_PARAM_set1_ip\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.0.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2012\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_check_issued.3 b/static/netbsd/man3/X509_check_issued.3 new file mode 100644 index 00000000..d5596adf --- /dev/null +++ b/static/netbsd/man3/X509_check_issued.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: X509_check_issued.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_check_issued 3" +.TH X509_check_issued 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_check_issued \- checks if certificate is apparently issued by another +certificate +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_check_issued(X509 *issuer, X509 *subject); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_check_issued()\fR checks if certificate \fIsubject\fR was apparently issued +using (CA) certificate \fIissuer\fR. This function takes into account not only +matching of the issuer field of \fIsubject\fR with the subject field of \fIissuer\fR, +but also compares all sub\-fields of the \fBauthorityKeyIdentifier\fR extension of +\&\fIsubject\fR, as far as present, with the respective \fBsubjectKeyIdentifier\fR, +serial number, and issuer fields of \fIissuer\fR, as far as present. It also checks +if the \fBkeyUsage\fR field (if present) of \fIissuer\fR allows certificate signing. +It does not actually check the certificate signature. An error is returned +if the \fIissuer\fR or the \fIsubject\fR are incomplete certificates. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_check_issued()\fR returns \fBX509_V_OK\fR if all checks are successful +or some \fBX509_V_ERR*\fR constant to indicate an error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify_cert\fR\|(3), \fBX509_verify\fR\|(3), \fBX509_check_ca\fR\|(3), +\&\fBopenssl\-verify\fR\|(1), \fBX509_self_signed\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_check_private_key.3 b/static/netbsd/man3/X509_check_private_key.3 new file mode 100644 index 00000000..73cab5f4 --- /dev/null +++ b/static/netbsd/man3/X509_check_private_key.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: X509_check_private_key.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_check_private_key 3" +.TH X509_check_private_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_check_private_key, X509_REQ_check_private_key \- check the consistency +of a private key with the public key in an X509 certificate or certificate +request +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_check_private_key(const X509 *cert, EVP_PKEY *pkey); +\& +\& int X509_REQ_check_private_key(X509_REQ *req, EVP_PKEY *pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_check_private_key()\fR function checks the consistency of private +key \fIpkey\fR with the public key in \fIcert\fR. +.PP +\&\fBX509_REQ_check_private_key()\fR is equivalent to \fBX509_check_private_key()\fR +except that \fIreq\fR represents a certificate request of structure \fBX509_REQ\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_check_private_key()\fR and \fBX509_REQ_check_private_key()\fR return 1 if +the keys match each other, and 0 if not. +.PP +If the key is invalid or an error occurred, the reason code can be +obtained using \fBERR_get_error\fR\|(3). +.SH BUGS +.IX Header "BUGS" +The \fBX509_check_private_key()\fR and \fBX509_REQ_check_private_key()\fR functions +do not check if \fIpkey\fR itself is indeed a private key or not. +They merely compare the public materials (e.g., exponent and modulus of an RSA +key) and/or key parameters (e.g. EC params of an EC key) of a key pair. +So they also return success if \fIpkey\fR is a matching public key. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_check_purpose.3 b/static/netbsd/man3/X509_check_purpose.3 new file mode 100644 index 00000000..52d1bb24 --- /dev/null +++ b/static/netbsd/man3/X509_check_purpose.3 @@ -0,0 +1,236 @@ +.\" $NetBSD: X509_check_purpose.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_check_purpose 3" +.TH X509_check_purpose 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_check_purpose, +X509_PURPOSE_get_count, +X509_PURPOSE_get_unused_id, +X509_PURPOSE_get_by_sname, +X509_PURPOSE_get_by_id, +X509_PURPOSE_add, +X509_PURPOSE_cleanup, +X509_PURPOSE_get0, +X509_PURPOSE_get_id, +X509_PURPOSE_get0_name, +X509_PURPOSE_get0_sname, +X509_PURPOSE_get_trust, +X509_PURPOSE_set \- functions related to checking the purpose of a certificate +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_check_purpose(X509 *x, int id, int ca); +\& +\& int X509_PURPOSE_get_count(void); +\& int X509_PURPOSE_get_unused_id(OSSL_LIB_CTX *libctx); +\& int X509_PURPOSE_get_by_sname(const char *sname); +\& int X509_PURPOSE_get_by_id(int id); +\& int X509_PURPOSE_add(int id, int trust, int flags, +\& int (*ck) (const X509_PURPOSE *, const X509 *, int), +\& const char *name, const char *sname, void *arg); +\& void X509_PURPOSE_cleanup(void); +\& +\& X509_PURPOSE *X509_PURPOSE_get0(int idx); +\& int X509_PURPOSE_get_id(const X509_PURPOSE *); +\& char *X509_PURPOSE_get0_name(const X509_PURPOSE *xp); +\& char *X509_PURPOSE_get0_sname(const X509_PURPOSE *xp); +\& int X509_PURPOSE_get_trust(const X509_PURPOSE *xp); +\& int X509_PURPOSE_set(int *p, int purpose); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_check_purpose()\fR checks if certificate \fIx\fR was created with the purpose +represented by \fIid\fR. If \fIca\fR is nonzero, then certificate \fIx\fR is +checked to determine if it\*(Aqs a possible CA with various levels of certainty +possibly returned. The certificate \fIx\fR must be a complete certificate +otherwise the function returns an error. +.PP +Below are the potential ID\*(Aqs that can be checked: +.PP +.Vb 10 +\& # define X509_PURPOSE_SSL_CLIENT 1 +\& # define X509_PURPOSE_SSL_SERVER 2 +\& # define X509_PURPOSE_NS_SSL_SERVER 3 +\& # define X509_PURPOSE_SMIME_SIGN 4 +\& # define X509_PURPOSE_SMIME_ENCRYPT 5 +\& # define X509_PURPOSE_CRL_SIGN 6 +\& # define X509_PURPOSE_ANY 7 +\& # define X509_PURPOSE_OCSP_HELPER 8 +\& # define X509_PURPOSE_TIMESTAMP_SIGN 9 +\& # define X509_PURPOSE_CODE_SIGN 10 +.Ve +.PP +The checks performed take into account the X.509 extensions +keyUsage, extendedKeyUsage, and basicConstraints. +.PP +\&\fBX509_PURPOSE_get_count()\fR returns the number of currently defined purposes. +.PP +\&\fBX509_PURPOSE_get_unused_id()\fR returns the smallest purpose id not yet used, +which is guaranteed to be unique and larger than \fBX509_PURPOSE_MAX\fR. +The \fIlibctx\fR parameter should be used to provide the library context. +It is currently ignored as the purpose mapping table is global. +.PP +\&\fBX509_PURPOSE_get_by_sname()\fR returns the index of +the purpose with the given short name or \-1 if not found. +.PP +\&\fBX509_PURPOSE_get_by_id()\fR returns the index of +the purpose with the given id or \-1 if not found. +.PP +\&\fBX509_PURPOSE_add()\fR adds or modifies a purpose entry identified by \fIsname\fR. +Unless the id stays the same for an existing entry, \fIid\fR must be fresh, +which can be achieved by using the result of \fBX509_PURPOSE_get_unused_id()\fR. +The function also sets in the entry the trust id \fItrust\fR, the given \fIflags\fR, +the purpose (long) name \fIname\fR, the short name \fIsname\fR, the purpose checking +function \fIck\fR of type \fBint (*) (const X509_PURPOSE *, const X509 *, int)\fR, +and its user data \fIarg\fR which may be retrieved via the \fBX509_PURPOSE\fR pointer. +.PP +\&\fBX509_PURPOSE_cleanup()\fR removes all purposes that are not pre\-defined. +.PP +\&\fBX509_PURPOSE_get0()\fR returns an \fBX509_PURPOSE\fR pointer or NULL on error. +.PP +\&\fBX509_PURPOSE_get_id()\fR returns the id of the given \fBX509_PURPOSE\fR structure. +.PP +\&\fBX509_PURPOSE_get0_name()\fR returns the (long) name of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_get0_sname()\fR returns the short name of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_get_trust()\fR returns the trust id of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_set()\fR assigns the given \fIpurpose\fR id to the location pointed at by +\&\fIp\fR. +This resets to the any purpose if \fIpurpose\fR is \fBX509_PURPOSE_DEFAULT_ANY\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_check_purpose()\fR returns the following values. +For non\-CA checks +.IP "\-1 an error condition has occurred" 4 +.IX Item "-1 an error condition has occurred" +.PD 0 +.IP " 1 if the certificate was created to perform the purpose represented by \fIid\fR" 4 +.IX Item " 1 if the certificate was created to perform the purpose represented by id" +.IP " 0 if the certificate was not created to perform the purpose represented by \fIid\fR" 4 +.IX Item " 0 if the certificate was not created to perform the purpose represented by id" +.PD +.PP +For CA checks the below integers could be returned with the following meanings: +.IP "\-1 an error condition has occurred" 4 +.IX Item "-1 an error condition has occurred" +.PD 0 +.IP " 0 not a CA or does not have the purpose represented by \fIid\fR" 4 +.IX Item " 0 not a CA or does not have the purpose represented by id" +.IP " 1 is a CA." 4 +.IX Item " 1 is a CA." +.IP " 2 Only possible in old versions of openSSL when basicConstraints are absent. New versions will not return this value. May be a CA" 4 +.IX Item " 2 Only possible in old versions of openSSL when basicConstraints are absent. New versions will not return this value. May be a CA" +.IP " 3 basicConstraints absent but self signed V1." 4 +.IX Item " 3 basicConstraints absent but self signed V1." +.IP " 4 basicConstraints absent but keyUsage present and keyCertSign asserted." 4 +.IX Item " 4 basicConstraints absent but keyUsage present and keyCertSign asserted." +.IP " 5 legacy Netscape specific CA Flags present" 4 +.IX Item " 5 legacy Netscape specific CA Flags present" +.PD +.PP +\&\fBX509_PURPOSE_get_count()\fR returns the number of currently defined purposes. +.PP +\&\fBX509_PURPOSE_get_unused_id()\fR returns the smallest purpose id not yet used. +.PP +\&\fBX509_PURPOSE_get_by_sname()\fR returns the index of +the purpose with the given short name or \-1 if not found. +.PP +\&\fBX509_PURPOSE_get_by_id()\fR returns the index of +the purpose with the given id or \-1 if not found. +.PP +int \fBX509_PURPOSE_add()\fR returns 1 on success, 0 on error. +.PP +\&\fBX509_PURPOSE_cleanup()\fR does not return anything. +.PP +\&\fBX509_PURPOSE_get0()\fR returns an \fBX509_PURPOSE\fR pointer or NULL on error. +.PP +\&\fBX509_PURPOSE_get_id()\fR returns the id of the given \fBX509_PURPOSE\fR structure. +.PP +\&\fBX509_PURPOSE_get0_name()\fR returns the (long) name of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_get0_sname()\fR returns the short name of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_get_trust()\fR returns the trust id of the given \fBX509_PURPOSE\fR. +.PP +\&\fBX509_PURPOSE_set()\fR returns 1 on success, 0 on error. +.SH BUGS +.IX Header "BUGS" +The X509_PURPOSE implementation so far is not thread\-safe. +There may be race conditions retrieving purpose information while +\&\fBX509_PURPOSE_add()\fR or X509_PURPOSE_cleanup(void) is being called. +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_PURPOSE_get_unused_id()\fR was added in OpensSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved. +Licensed under the Apache License 2.0 (the "License"). You may not use this +file except in compliance with the License. You can obtain a copy in the file +LICENSE in the source distribution or at . diff --git a/static/netbsd/man3/X509_cmp.3 b/static/netbsd/man3/X509_cmp.3 new file mode 100644 index 00000000..4954c8ca --- /dev/null +++ b/static/netbsd/man3/X509_cmp.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: X509_cmp.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_cmp 3" +.TH X509_cmp 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_cmp, X509_NAME_cmp, +X509_issuer_and_serial_cmp, X509_issuer_name_cmp, X509_subject_name_cmp, +X509_CRL_cmp, X509_CRL_match +\&\- compare X509 certificates and related values +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_cmp(const X509 *a, const X509 *b); +\& int X509_NAME_cmp(const X509_NAME *a, const X509_NAME *b); +\& int X509_issuer_and_serial_cmp(const X509 *a, const X509 *b); +\& int X509_issuer_name_cmp(const X509 *a, const X509 *b); +\& int X509_subject_name_cmp(const X509 *a, const X509 *b); +\& int X509_CRL_cmp(const X509_CRL *a, const X509_CRL *b); +\& int X509_CRL_match(const X509_CRL *a, const X509_CRL *b); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This set of functions are used to compare X509 objects, including X509 +certificates, X509 CRL objects and various values in an X509 certificate. +.PP +The \fBX509_cmp()\fR function compares two \fBX509\fR objects indicated by parameters +\&\fIa\fR and \fIb\fR. The comparison is based on the \fBmemcmp\fR result of the hash +values of two \fBX509\fR objects and the canonical (DER) encoding values. +.PP +The \fBX509_NAME_cmp()\fR function compares two \fBX509_NAME\fR objects indicated by +parameters \fIa\fR and \fIb\fR, any of which may be NULL. +The comparison is based on the \fBmemcmp\fR result of the +canonical (DER) encoding values of the two objects using \fBi2d_X509_NAME\fR\|(3). +This procedure adheres to the matching rules for Distinguished Names (DN) +given in RFC 4517 section 4.2.15 and RFC 5280 section 7.1. +In particular, the order of Relative Distinguished Names (RDNs) is relevant. +On the other hand, if an RDN is multi\-valued, i.e., it contains a set of +AttributeValueAssertions (AVAs), its members are effectively not ordered. +.PP +The \fBX509_issuer_and_serial_cmp()\fR function compares the serial number and issuer +values in the given \fBX509\fR objects \fIa\fR and \fIb\fR. +.PP +The \fBX509_issuer_name_cmp()\fR, \fBX509_subject_name_cmp()\fR and \fBX509_CRL_cmp()\fR functions +are effectively wrappers of the \fBX509_NAME_cmp()\fR function. These functions compare +issuer names and subject names of the objects, or issuers of \fBX509_CRL\fR +objects, respectively. +.IX Xref "509" +.PP +The \fBX509_CRL_match()\fR function compares two \fBX509_CRL\fR objects. Unlike the +\&\fBX509_CRL_cmp()\fR function, this function compares the whole CRL content instead +of just the issuer name. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBX509\fR comparison functions return \fB\-1\fR, \fB0\fR, or \fB1\fR if object \fIa\fR is +found to be less than, to match, or be greater than object \fIb\fR, respectively. +.PP +\&\fBX509_NAME_cmp()\fR, \fBX509_issuer_and_serial_cmp()\fR, \fBX509_issuer_name_cmp()\fR, +\&\fBX509_subject_name_cmp()\fR, \fBX509_CRL_cmp()\fR, and \fBX509_CRL_match()\fR +may return \fB\-2\fR to indicate an error. +.SH NOTES +.IX Header "NOTES" +These functions in fact utilize the underlying \fBmemcmp\fR of the C library to do +the comparison job. Data to be compared varies from DER encoding data, hash +value or \fBASN1_STRING\fR. The sign of the comparison can be used to order the +objects but it does not have a special meaning in some cases. +.PP +\&\fBX509_NAME_cmp()\fR and wrappers utilize the value \fB\-2\fR to indicate errors in some +circumstances, which could cause confusion for the applications. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBi2d_X509_NAME\fR\|(3), \fBi2d_X509\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_cmp_time.3 b/static/netbsd/man3/X509_cmp_time.3 new file mode 100644 index 00000000..aac7d83b --- /dev/null +++ b/static/netbsd/man3/X509_cmp_time.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: X509_cmp_time.3,v 1.5 2026/04/08 17:06:49 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_cmp_time 3" +.TH X509_cmp_time 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_cmp_time, X509_cmp_current_time, X509_cmp_timeframe, +X509_time_adj, X509_time_adj_ex, X509_gmtime_adj +\&\- X509 time functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 8 +\& int X509_cmp_time(const ASN1_TIME *asn1_time, time_t *in_tm); +\& int X509_cmp_current_time(const ASN1_TIME *asn1_time); +\& int X509_cmp_timeframe(const X509_VERIFY_PARAM *vpm, +\& const ASN1_TIME *start, const ASN1_TIME *end); +\& ASN1_TIME *X509_time_adj(ASN1_TIME *asn1_time, long offset_sec, time_t *in_tm); +\& ASN1_TIME *X509_time_adj_ex(ASN1_TIME *asn1_time, int offset_day, long +\& offset_sec, time_t *in_tm); +\& ASN1_TIME *X509_gmtime_adj(ASN1_TIME *asn1_time, long offset_sec); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_cmp_time()\fR compares the ASN1_TIME in \fIasn1_time\fR with the time +in . +.PP +\&\fBX509_cmp_current_time()\fR compares the ASN1_TIME in +\&\fIasn1_time\fR with the current time, expressed as time_t. +.PP +\&\fBX509_cmp_timeframe()\fR compares the given time period with the reference time +included in the verification parameters \fIvpm\fR if they are not NULL and contain +\&\fBX509_V_FLAG_USE_CHECK_TIME\fR; else the current time is used as reference time. +.PP +\&\fBX509_time_adj_ex()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time +\&\fIoffset_day\fR and \fIoffset_sec\fR after \fIin_tm\fR. +.PP +\&\fBX509_time_adj()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time +\&\fIoffset_sec\fR after \fIin_tm\fR. This method can only handle second +offsets up to the capacity of long, so the newer \fBX509_time_adj_ex()\fR +API should be preferred. +.PP +In both methods, if \fIasn1_time\fR is NULL, a new ASN1_TIME structure +is allocated and returned. +.PP +In all methods, if \fIin_tm\fR is NULL, the current time, expressed as +time_t, is used. +.PP +\&\fIasn1_time\fR must satisfy the ASN1_TIME format mandated by RFC 5280, +i.e., its format must be either YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ. +.PP +\&\fBX509_gmtime_adj()\fR sets the ASN1_TIME structure \fIasn1_time\fR to the time +\&\fIoffset_sec\fR after the current time. It is equivalent to calling +\&\fBX509_time_adj()\fR with the last parameter as NULL. +.SH BUGS +.IX Header "BUGS" +Unlike many standard comparison functions, \fBX509_cmp_time()\fR and +\&\fBX509_cmp_current_time()\fR return 0 on error. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_cmp_time()\fR and \fBX509_cmp_current_time()\fR return \-1 if \fIasn1_time\fR +is earlier than, or equal to, \fIin_tm\fR (resp. current time), and 1 +otherwise. These methods return 0 on error. +.PP +\&\fBX509_cmp_timeframe()\fR returns 0 if \fIvpm\fR is not NULL and the verification +parameters do not contain \fBX509_V_FLAG_USE_CHECK_TIME\fR +but do contain \fBX509_V_FLAG_NO_CHECK_TIME\fR. Otherwise it returns +1 if the end time is not NULL and the reference time (which has determined as +stated above) is past the end time, \-1 if the start time is not NULL and the +reference time is before, else 0 to indicate that the reference time is in range +(implying that the end time is not before the start time if both are present). +.PP +\&\fBX509_time_adj()\fR, \fBX509_time_adj_ex()\fR and \fBX509_gmtime_adj()\fR return a pointer to +the updated ASN1_TIME structure, and NULL on error. +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_cmp_timeframe()\fR was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_digest.3 b/static/netbsd/man3/X509_digest.3 new file mode 100644 index 00000000..ed9b39e1 --- /dev/null +++ b/static/netbsd/man3/X509_digest.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: X509_digest.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_digest 3" +.TH X509_digest 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_digest, +X509_digest_sig, +X509_CRL_digest, +X509_pubkey_digest, +X509_NAME_digest, +X509_REQ_digest, +PKCS7_ISSUER_AND_SERIAL_digest +\&\- get digest of various objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_digest(const X509 *data, const EVP_MD *type, unsigned char *md, +\& unsigned int *len); +\& ASN1_OCTET_STRING *X509_digest_sig(const X509 *cert, +\& EVP_MD **md_used, int *md_is_fallback); +\& +\& int X509_CRL_digest(const X509_CRL *data, const EVP_MD *type, unsigned char *md, +\& unsigned int *len); +\& +\& int X509_pubkey_digest(const X509 *data, const EVP_MD *type, +\& unsigned char *md, unsigned int *len); +\& +\& int X509_REQ_digest(const X509_REQ *data, const EVP_MD *type, +\& unsigned char *md, unsigned int *len); +\& +\& int X509_NAME_digest(const X509_NAME *data, const EVP_MD *type, +\& unsigned char *md, unsigned int *len); +\& +\& #include +\& +\& int PKCS7_ISSUER_AND_SERIAL_digest(PKCS7_ISSUER_AND_SERIAL *data, +\& const EVP_MD *type, unsigned char *md, +\& unsigned int *len); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_digest_sig()\fR calculates a digest of the given certificate \fIcert\fR +using the same hash algorithm as in its signature, if the digest +is an integral part of the certificate signature algorithm identifier. +Otherwise, a fallback hash algorithm is determined as follows: +SHA512 if the signature algorithm is ED25519, +SHAKE256 if it is ED448, otherwise SHA256. +The output parameters are assigned as follows. +Unless \fImd_used\fR is NULL, the hash algorithm used is provided +in \fI*md_used\fR and must be freed by the caller (if it is not NULL). +Unless \fImd_is_fallback\fR is NULL, +the \fI*md_is_fallback\fR is set to 1 if the hash algorithm used is a fallback, +otherwise to 0. +.PP +\&\fBX509_pubkey_digest()\fR returns a digest of the DER representation of the public +key in the specified X509 \fIdata\fR object. +.PP +All other functions described here return a digest of the DER representation +of their entire \fIdata\fR objects. +.PP +The \fItype\fR parameter specifies the digest to +be used, such as \fBEVP_sha1()\fR. The \fImd\fR is a pointer to the buffer where the +digest will be copied and is assumed to be large enough; the constant +\&\fBEVP_MAX_MD_SIZE\fR is suggested. The \fIlen\fR parameter, if not NULL, points +to a place where the digest size will be stored. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_digest_sig()\fR returns an ASN1_OCTET_STRING pointer on success, else NULL. +.PP +All other functions described here return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_sha1\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_digest_sig()\fR function was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_dup.3 b/static/netbsd/man3/X509_dup.3 new file mode 100644 index 00000000..c5f799ab --- /dev/null +++ b/static/netbsd/man3/X509_dup.3 @@ -0,0 +1,673 @@ +.\" $NetBSD: X509_dup.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_dup 3" +.TH X509_dup 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DECLARE_ASN1_FUNCTIONS, +IMPLEMENT_ASN1_FUNCTIONS, +ASN1_ITEM, +ACCESS_DESCRIPTION_free, +ACCESS_DESCRIPTION_new, +ADMISSIONS_free, +ADMISSIONS_new, +ADMISSION_SYNTAX_free, +ADMISSION_SYNTAX_new, +ASIdOrRange_free, +ASIdOrRange_new, +ASIdentifierChoice_free, +ASIdentifierChoice_new, +ASIdentifiers_free, +ASIdentifiers_new, +ASRange_free, +ASRange_new, +AUTHORITY_INFO_ACCESS_free, +AUTHORITY_INFO_ACCESS_new, +AUTHORITY_KEYID_free, +AUTHORITY_KEYID_new, +BASIC_CONSTRAINTS_free, +BASIC_CONSTRAINTS_new, +CERTIFICATEPOLICIES_free, +CERTIFICATEPOLICIES_new, +CMS_ContentInfo_free, +CMS_ContentInfo_new, +CMS_ContentInfo_new_ex, +CMS_ContentInfo_print_ctx, +CMS_EnvelopedData_it, +CMS_EnvelopedData_dup, +CMS_ReceiptRequest_free, +CMS_ReceiptRequest_new, +CMS_SignedData_free, +CMS_SignedData_new, +CRL_DIST_POINTS_free, +CRL_DIST_POINTS_new, +DIRECTORYSTRING_free, +DIRECTORYSTRING_new, +DISPLAYTEXT_free, +DISPLAYTEXT_new, +DIST_POINT_NAME_free, +DIST_POINT_NAME_new, +DIST_POINT_NAME_dup, +DIST_POINT_free, +DIST_POINT_new, +DSAparams_dup, +ECPARAMETERS_free, +ECPARAMETERS_new, +ECPKPARAMETERS_free, +ECPKPARAMETERS_new, +EDIPARTYNAME_free, +EDIPARTYNAME_new, +ESS_CERT_ID_dup, +ESS_CERT_ID_free, +ESS_CERT_ID_new, +ESS_CERT_ID_V2_dup, +ESS_CERT_ID_V2_free, +ESS_CERT_ID_V2_new, +ESS_ISSUER_SERIAL_dup, +ESS_ISSUER_SERIAL_free, +ESS_ISSUER_SERIAL_new, +ESS_SIGNING_CERT_dup, +ESS_SIGNING_CERT_free, +ESS_SIGNING_CERT_it, +ESS_SIGNING_CERT_new, +ESS_SIGNING_CERT_V2_dup, +ESS_SIGNING_CERT_V2_free, +ESS_SIGNING_CERT_V2_it, +ESS_SIGNING_CERT_V2_new, +EXTENDED_KEY_USAGE_free, +EXTENDED_KEY_USAGE_new, +GENERAL_NAMES_free, +GENERAL_NAMES_new, +GENERAL_NAME_dup, +GENERAL_NAME_free, +GENERAL_NAME_new, +GENERAL_SUBTREE_free, +GENERAL_SUBTREE_new, +OSSL_IETF_ATTR_SYNTAX_free, +OSSL_IETF_ATTR_SYNTAX_it, +OSSL_IETF_ATTR_SYNTAX_new, +IPAddressChoice_free, +IPAddressChoice_new, +IPAddressFamily_free, +IPAddressFamily_new, +IPAddressOrRange_free, +IPAddressOrRange_new, +IPAddressRange_free, +IPAddressRange_new, +ISSUER_SIGN_TOOL_free, +ISSUER_SIGN_TOOL_it, +ISSUER_SIGN_TOOL_new, +ISSUING_DIST_POINT_free, +ISSUING_DIST_POINT_it, +ISSUING_DIST_POINT_new, +NAME_CONSTRAINTS_free, +NAME_CONSTRAINTS_new, +NAMING_AUTHORITY_free, +NAMING_AUTHORITY_new, +NETSCAPE_CERT_SEQUENCE_free, +NETSCAPE_CERT_SEQUENCE_new, +NETSCAPE_SPKAC_free, +NETSCAPE_SPKAC_new, +NETSCAPE_SPKI_free, +NETSCAPE_SPKI_new, +NOTICEREF_free, +NOTICEREF_new, +OCSP_BASICRESP_free, +OCSP_BASICRESP_new, +OCSP_CERTID_dup, +OCSP_CERTID_new, +OCSP_CERTSTATUS_free, +OCSP_CERTSTATUS_new, +OCSP_CRLID_free, +OCSP_CRLID_new, +OCSP_ONEREQ_free, +OCSP_ONEREQ_new, +OCSP_REQINFO_free, +OCSP_REQINFO_new, +OCSP_RESPBYTES_free, +OCSP_RESPBYTES_new, +OCSP_RESPDATA_free, +OCSP_RESPDATA_new, +OCSP_RESPID_free, +OCSP_RESPID_new, +OCSP_RESPONSE_new, +OCSP_REVOKEDINFO_free, +OCSP_REVOKEDINFO_new, +OCSP_SERVICELOC_free, +OCSP_SERVICELOC_new, +OCSP_SIGNATURE_free, +OCSP_SIGNATURE_new, +OCSP_SINGLERESP_free, +OCSP_SINGLERESP_new, +OSSL_AA_DIST_POINT_free, +OSSL_AA_DIST_POINT_new, +OSSL_AA_DIST_POINT_it, +OSSL_ALLOWED_ATTRIBUTES_CHOICE_free, +OSSL_ALLOWED_ATTRIBUTES_CHOICE_new, +OSSL_ALLOWED_ATTRIBUTES_CHOICE_it, +OSSL_ALLOWED_ATTRIBUTES_ITEM_free, +OSSL_ALLOWED_ATTRIBUTES_ITEM_new, +OSSL_ALLOWED_ATTRIBUTES_ITEM_it, +OSSL_ALLOWED_ATTRIBUTES_SYNTAX_free, +OSSL_ALLOWED_ATTRIBUTES_SYNTAX_new, +OSSL_ALLOWED_ATTRIBUTES_SYNTAX_it, +OSSL_ATAV_free, +OSSL_ATAV_new, +OSSL_ATAV_it, +OSSL_ATTRIBUTE_DESCRIPTOR_free, +OSSL_ATTRIBUTE_DESCRIPTOR_new, +OSSL_ATTRIBUTE_DESCRIPTOR_it, +OSSL_ATTRIBUTE_MAPPING_free, +OSSL_ATTRIBUTE_MAPPING_new, +OSSL_ATTRIBUTE_MAPPING_it, +OSSL_ATTRIBUTE_MAPPINGS_free, +OSSL_ATTRIBUTE_MAPPINGS_new, +OSSL_ATTRIBUTE_MAPPINGS_it, +OSSL_ATTRIBUTE_TYPE_MAPPING_free, +OSSL_ATTRIBUTE_TYPE_MAPPING_new, +OSSL_ATTRIBUTE_TYPE_MAPPING_it, +OSSL_ATTRIBUTE_VALUE_MAPPING_free, +OSSL_ATTRIBUTE_VALUE_MAPPING_new, +OSSL_ATTRIBUTE_VALUE_MAPPING_it, +OSSL_ATTRIBUTES_SYNTAX_free, +OSSL_ATTRIBUTES_SYNTAX_it, +OSSL_ATTRIBUTES_SYNTAX_new, +OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_free, +OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_it, +OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_new, +OSSL_BASIC_ATTR_CONSTRAINTS_free, +OSSL_BASIC_ATTR_CONSTRAINTS_it, +OSSL_BASIC_ATTR_CONSTRAINTS_new, +OSSL_CMP_ATAVS_new, +OSSL_CMP_ATAVS_free, +OSSL_CMP_ATAVS_it, +OSSL_CMP_CRLSTATUS_free, +OSSL_CMP_ITAV_dup, +OSSL_CMP_ITAV_free, +OSSL_CMP_MSG_dup, +OSSL_CMP_MSG_it, +OSSL_CMP_MSG_free, +OSSL_CMP_PKIHEADER_free, +OSSL_CMP_PKIHEADER_it, +OSSL_CMP_PKIHEADER_new, +OSSL_CMP_PKISI_dup, +OSSL_CMP_PKISI_free, +OSSL_CMP_PKISI_it, +OSSL_CMP_PKISI_new, +OSSL_CMP_PKISTATUS_it, +OSSL_CRMF_CERTID_dup, +OSSL_CRMF_CERTID_free, +OSSL_CRMF_CERTID_it, +OSSL_CRMF_CERTID_new, +OSSL_CRMF_CERTTEMPLATE_free, +OSSL_CRMF_CERTTEMPLATE_it, +OSSL_CRMF_CERTTEMPLATE_new, +OSSL_CRMF_CERTTEMPLATE_dup, +OSSL_CRMF_ATTRIBUTETYPEANDVALUE_dup, +OSSL_CRMF_ATTRIBUTETYPEANDVALUE_free, +OSSL_CRMF_ENCRYPTEDKEY_free, +OSSL_CRMF_ENCRYPTEDKEY_it, +OSSL_CRMF_ENCRYPTEDKEY_new, +OSSL_CRMF_ENCRYPTEDVALUE_free, +OSSL_CRMF_ENCRYPTEDVALUE_it, +OSSL_CRMF_ENCRYPTEDVALUE_new, +OSSL_CRMF_MSGS_free, +OSSL_CRMF_MSGS_it, +OSSL_CRMF_MSGS_new, +OSSL_CRMF_MSG_dup, +OSSL_CRMF_MSG_free, +OSSL_CRMF_MSG_it, +OSSL_CRMF_MSG_new, +OSSL_CRMF_PBMPARAMETER_free, +OSSL_CRMF_PBMPARAMETER_it, +OSSL_CRMF_PBMPARAMETER_new, +OSSL_CRMF_PKIPUBLICATIONINFO_free, +OSSL_CRMF_PKIPUBLICATIONINFO_it, +OSSL_CRMF_PKIPUBLICATIONINFO_new, +OSSL_CRMF_SINGLEPUBINFO_free, +OSSL_CRMF_SINGLEPUBINFO_it, +OSSL_CRMF_SINGLEPUBINFO_new, +OSSL_DAY_TIME_free, +OSSL_DAY_TIME_new, +OSSL_DAY_TIME_it, +OSSL_DAY_TIME_BAND_free, +OSSL_DAY_TIME_BAND_new, +OSSL_DAY_TIME_BAND_it, +OSSL_HASH_free, +OSSL_HASH_it, +OSSL_HASH_new, +OSSL_INFO_SYNTAX_free, +OSSL_INFO_SYNTAX_it, +OSSL_INFO_SYNTAX_new, +OSSL_INFO_SYNTAX_POINTER_free, +OSSL_INFO_SYNTAX_POINTER_it, +OSSL_INFO_SYNTAX_POINTER_new, +OSSL_PRIVILEGE_POLICY_ID_free, +OSSL_PRIVILEGE_POLICY_ID_it, +OSSL_PRIVILEGE_POLICY_ID_new, +OSSL_TARGET_CERT_free, +OSSL_TARGET_CERT_it, +OSSL_TARGET_CERT_new, +OSSL_TARGET_free, +OSSL_TARGET_it, +OSSL_TARGET_new, +OSSL_TARGETING_INFORMATION_free, +OSSL_TARGETING_INFORMATION_it, +OSSL_TARGETING_INFORMATION_new, +OSSL_TARGETS_free, +OSSL_TARGETS_it, +OSSL_TARGETS_new, +OSSL_IETF_ATTR_SYNTAX_VALUE_free, +OSSL_IETF_ATTR_SYNTAX_VALUE_it, +OSSL_IETF_ATTR_SYNTAX_VALUE_new, +OSSL_ISSUER_SERIAL_free, +OSSL_ISSUER_SERIAL_new, +OSSL_NAMED_DAY_free, +OSSL_NAMED_DAY_new, +OSSL_NAMED_DAY_it, +OSSL_OBJECT_DIGEST_INFO_free, +OSSL_OBJECT_DIGEST_INFO_new, +OSSL_ROLE_SPEC_CERT_ID_free, +OSSL_ROLE_SPEC_CERT_ID_new, +OSSL_ROLE_SPEC_CERT_ID_it, +OSSL_ROLE_SPEC_CERT_ID_SYNTAX_free, +OSSL_ROLE_SPEC_CERT_ID_SYNTAX_new, +OSSL_ROLE_SPEC_CERT_ID_SYNTAX_it, +OSSL_TIME_PERIOD_free, +OSSL_TIME_PERIOD_new, +OSSL_TIME_PERIOD_it, +OSSL_TIME_SPEC_ABSOLUTE_free, +OSSL_TIME_SPEC_ABSOLUTE_new, +OSSL_TIME_SPEC_ABSOLUTE_it, +OSSL_TIME_SPEC_free, +OSSL_TIME_SPEC_new, +OSSL_TIME_SPEC_it, +OSSL_TIME_SPEC_DAY_free, +OSSL_TIME_SPEC_DAY_new, +OSSL_TIME_SPEC_DAY_it, +OSSL_TIME_SPEC_MONTH_free, +OSSL_TIME_SPEC_MONTH_new, +OSSL_TIME_SPEC_MONTH_it, +OSSL_TIME_SPEC_TIME_free, +OSSL_TIME_SPEC_TIME_new, +OSSL_TIME_SPEC_TIME_it, +OSSL_TIME_SPEC_WEEKS_free, +OSSL_TIME_SPEC_WEEKS_new, +OSSL_TIME_SPEC_WEEKS_it, +OSSL_TIME_SPEC_X_DAY_OF_free, +OSSL_TIME_SPEC_X_DAY_OF_new, +OSSL_TIME_SPEC_X_DAY_OF_it, +OSSL_USER_NOTICE_SYNTAX_free, +OSSL_USER_NOTICE_SYNTAX_new, +OSSL_USER_NOTICE_SYNTAX_it, +OTHERNAME_free, +OTHERNAME_new, +PBE2PARAM_free, +PBE2PARAM_new, +PBEPARAM_free, +PBEPARAM_new, +PBKDF2PARAM_free, +PBKDF2PARAM_new, +PBMAC1PARAM_free, +PBMAC1PARAM_it, +PBMAC1PARAM_new, +PKCS12_BAGS_free, +PKCS12_BAGS_new, +PKCS12_MAC_DATA_free, +PKCS12_MAC_DATA_new, +PKCS12_SAFEBAG_free, +PKCS12_SAFEBAG_new, +PKCS12_free, +PKCS12_new, +PKCS7_DIGEST_free, +PKCS7_DIGEST_new, +PKCS7_ENCRYPT_free, +PKCS7_ENCRYPT_new, +PKCS7_ENC_CONTENT_free, +PKCS7_ENC_CONTENT_new, +PKCS7_ENVELOPE_free, +PKCS7_ENVELOPE_new, +PKCS7_ISSUER_AND_SERIAL_free, +PKCS7_ISSUER_AND_SERIAL_new, +PKCS7_RECIP_INFO_free, +PKCS7_RECIP_INFO_new, +PKCS7_SIGNED_free, +PKCS7_SIGNED_new, +PKCS7_SIGNER_INFO_free, +PKCS7_SIGNER_INFO_new, +PKCS7_SIGN_ENVELOPE_free, +PKCS7_SIGN_ENVELOPE_new, +PKCS7_dup, +PKCS7_free, +PKCS7_new_ex, +PKCS7_new, +PKCS7_print_ctx, +PKCS8_PRIV_KEY_INFO_free, +PKCS8_PRIV_KEY_INFO_new, +PKEY_USAGE_PERIOD_free, +PKEY_USAGE_PERIOD_new, +POLICYINFO_free, +POLICYINFO_new, +POLICYQUALINFO_free, +POLICYQUALINFO_new, +POLICY_CONSTRAINTS_free, +POLICY_CONSTRAINTS_new, +POLICY_MAPPING_free, +POLICY_MAPPING_new, +PROFESSION_INFOS_free, +PROFESSION_INFOS_new, +PROFESSION_INFO_free, +PROFESSION_INFO_new, +PROXY_CERT_INFO_EXTENSION_free, +PROXY_CERT_INFO_EXTENSION_new, +PROXY_POLICY_free, +PROXY_POLICY_new, +RSAPrivateKey_dup, +RSAPublicKey_dup, +RSA_OAEP_PARAMS_free, +RSA_OAEP_PARAMS_new, +RSA_PSS_PARAMS_free, +RSA_PSS_PARAMS_new, +RSA_PSS_PARAMS_dup, +SCRYPT_PARAMS_free, +SCRYPT_PARAMS_new, +SXNETID_free, +SXNETID_new, +SXNET_free, +SXNET_new, +TLS_FEATURE_free, +TLS_FEATURE_new, +TS_ACCURACY_dup, +TS_ACCURACY_free, +TS_ACCURACY_new, +TS_MSG_IMPRINT_dup, +TS_MSG_IMPRINT_free, +TS_MSG_IMPRINT_new, +TS_REQ_dup, +TS_REQ_free, +TS_REQ_new, +TS_RESP_dup, +TS_RESP_free, +TS_RESP_new, +TS_STATUS_INFO_dup, +TS_STATUS_INFO_free, +TS_STATUS_INFO_new, +TS_TST_INFO_dup, +TS_TST_INFO_free, +TS_TST_INFO_new, +USERNOTICE_free, +USERNOTICE_new, +X509_ACERT_dup, +X509_ACERT_free, +X509_ACERT_it, +X509_ACERT_new, +X509_ACERT_INFO_free, +X509_ACERT_INFO_it, +X509_ACERT_INFO_new, +X509_ACERT_ISSUER_V2FORM_free, +X509_ACERT_ISSUER_V2FORM_new, +X509_ALGOR_free, +X509_ALGOR_it, +X509_ALGOR_new, +X509_ATTRIBUTE_dup, +X509_ATTRIBUTE_free, +X509_ATTRIBUTE_new, +X509_CERT_AUX_free, +X509_CERT_AUX_new, +X509_CINF_free, +X509_CINF_new, +X509_CRL_INFO_free, +X509_CRL_INFO_new, +X509_CRL_dup, +X509_CRL_free, +X509_CRL_new_ex, +X509_CRL_new, +X509_EXTENSION_dup, +X509_EXTENSION_free, +X509_EXTENSION_new, +X509_NAME_ENTRY_dup, +X509_NAME_ENTRY_free, +X509_NAME_ENTRY_new, +X509_NAME_dup, +X509_NAME_free, +X509_NAME_new, +X509_REQ_INFO_free, +X509_REQ_INFO_new, +X509_REQ_dup, +X509_REQ_free, +X509_REQ_new, +X509_REQ_new_ex, +X509_REVOKED_dup, +X509_REVOKED_free, +X509_REVOKED_new, +X509_SIG_free, +X509_SIG_new, +X509_VAL_free, +X509_VAL_new, +X509_dup, +\&\- ASN1 object utilities +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& DECLARE_ASN1_FUNCTIONS(type) +\& IMPLEMENT_ASN1_FUNCTIONS(stname) +\& +\& typedef struct ASN1_ITEM_st ASN1_ITEM; +\& +\& extern const ASN1_ITEM TYPE_it; +\& TYPE *TYPE_new(void); +\& TYPE *TYPE_dup(const TYPE *a); +\& void TYPE_free(TYPE *a); +\& int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 3 +\& DSA *DSAparams_dup(const DSA *dsa); +\& RSA *RSAPrivateKey_dup(const RSA *rsa); +\& RSA *RSAPublicKey_dup(const RSA *rsa); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In the description below, \fR\f(BITYPE\fR\fB\fR is used +as a placeholder for any of the OpenSSL datatypes, such as \fBX509\fR. +.PP +The OpenSSL ASN1 parsing library templates are like a data\-driven bytecode +interpreter. +Every ASN1 object as a global variable, TYPE_it, that describes the item +such as its fields. (On systems which cannot export variables from shared +libraries, the global is instead a function which returns a pointer to a +static variable. +.PP +The macro \fBDECLARE_ASN1_FUNCTIONS()\fR is typically used in header files +to generate the function declarations. +.PP +The macro \fBIMPLEMENT_ASN1_FUNCTIONS()\fR is used once in a source file +to generate the function bodies. +.PP +\&\fR\f(BITYPE\fR\fB_new\fR() allocates an empty object of the indicated type. +The object returned must be released by calling \fB\fR\f(BITYPE\fR\fB_free\fR(). +.PP +\&\fR\f(BITYPE\fR\fB_new_ex\fR() is similar to \fB\fR\f(BITYPE\fR\fB_new\fR() but also passes the +library context \fIlibctx\fR and the property query \fIpropq\fR to use when retrieving +algorithms from providers. This created object can then be used when loading +binary data using \fBd2i_\fR\f(BITYPE\fR\fB\fR(). +.PP +\&\fR\f(BITYPE\fR\fB_dup\fR() copies an existing object, leaving it untouched. +Note, however, that the internal representation of the object +may contain (besides the ASN.1 structure) further data, which is not copied. +For instance, an \fBX509\fR object usually is augmented by cached information +on X.509v3 extensions, etc., and losing it can lead to wrong validation results. +To avoid such situations, better use \fB\fR\f(BITYPE\fR\fB_up_ref\fR() if available. +For the case of \fBX509\fR objects, an alternative to using \fBX509_up_ref\fR\|(3) +may be to still call \fB\fR\f(BITYPE\fR\fB_dup\fR(), e.g., \fIcopied_cert = X509_dup(cert)\fR, +followed by \fIX509_check_purpose(copied_cert, \-1, 0)\fR, +which re\-builds the cached data. +.PP +\&\fR\f(BITYPE\fR\fB_free\fR() releases the object and all pointers and sub\-objects +within it. If the argument is NULL, nothing is done. +.PP +\&\fR\f(BITYPE\fR\fB_print_ctx\fR() prints the object \fIa\fR on the specified BIO \fIout\fR. +Each line will be prefixed with \fIindent\fR spaces. +The \fIpctx\fR specifies the printing context and is for internal +use; use NULL to get the default behavior. If a print function is +user\-defined, then pass in any \fIpctx\fR down to any nested calls. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fR\f(BITYPE\fR\fB_new\fR(), \fB\fR\f(BITYPE\fR\fB_new_ex\fR() and \fB\fR\f(BITYPE\fR\fB_dup\fR() return a pointer to +the object or NULL on failure. +.PP +\&\fR\f(BITYPE\fR\fB_print_ctx\fR() returns 1 on success or zero on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_up_ref\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBX509_REQ_new_ex()\fR, \fBX509_CRL_new_ex()\fR, \fBPKCS7_new_ex()\fR and +\&\fBCMS_ContentInfo_new_ex()\fR were added in OpenSSL 3.0. +.PP +The functions \fBDSAparams_dup()\fR, \fBRSAPrivateKey_dup()\fR and \fBRSAPublicKey_dup()\fR were +deprecated in 3.0. +.PP +\&\fBCMS_EnvelopedData_it()\fR, \fBCMS_SignedData_free()\fR, \fBCMS_SignedData_new()\fR +were added in OpenSSL 3.2. +.PP +\&\fBDIST_POINT_NAME_dup()\fR, \fBOSSL_IETF_ATTR_SYNTAX_free()\fR, \fBOSSL_IETF_ATTR_SYNTAX_it()\fR, +\&\fBOSSL_IETF_ATTR_SYNTAX_new()\fR, \fBOSSL_ATTRIBUTES_SYNTAX_free()\fR, +\&\fBOSSL_ATTRIBUTES_SYNTAX_it()\fR, \fBOSSL_ATTRIBUTES_SYNTAX_new()\fR, +\&\fBOSSL_BASIC_ATTR_CONSTRAINTS_free()\fR, \fBOSSL_BASIC_ATTR_CONSTRAINTS_it()\fR, +\&\fBOSSL_BASIC_ATTR_CONSTRAINTS_new()\fR, \fBOSSL_CMP_ATAVS_new()\fR, \fBOSSL_CMP_ATAVS_free()\fR, +\&\fBOSSL_CMP_ATAVS_it()\fR, \fBOSSL_CMP_CRLSTATUS_free()\fR, \fBOSSL_CRMF_CERTTEMPLATE_dup()\fR, +\&\fBOSSL_CRMF_ATTRIBUTETYPEANDVALUE_dup()\fR, \fBOSSL_CRMF_ATTRIBUTETYPEANDVALUE_free()\fR, +\&\fBOSSL_TARGET_free()\fR, \fBOSSL_TARGET_it()\fR, \fBOSSL_TARGET_new()\fR, +\&\fBOSSL_TARGETING_INFORMATION_free()\fR, \fBOSSL_TARGETING_INFORMATION_it()\fR, +\&\fBOSSL_TARGETING_INFORMATION_new()\fR, \fBOSSL_TARGETS_free()\fR, +\&\fBOSSL_TARGETS_it()\fR, \fBOSSL_TARGETS_new()\fR, \fBOSSL_IETF_ATTR_SYNTAX_VALUE_free()\fR, +\&\fBOSSL_IETF_ATTR_SYNTAX_VALUE_it()\fR, \fBOSSL_IETF_ATTR_SYNTAX_VALUE_new()\fR, +\&\fBOSSL_ISSUER_SERIAL_free()\fR, \fBOSSL_ISSUER_SERIAL_new()\fR, +\&\fBOSSL_OBJECT_DIGEST_INFO_free()\fR, \fBOSSL_OBJECT_DIGEST_INFO_new()\fR, +\&\fBOSSL_USER_NOTICE_SYNTAX_free()\fR, \fBOSSL_USER_NOTICE_SYNTAX_new()\fR, +\&\fBOSSL_USER_NOTICE_SYNTAX_it()\fR, \fBPBMAC1PARAM_free()\fR, \fBPBMAC1PARAM_it()\fR, +\&\fBPBMAC1PARAM_new()\fR, \fBX509_ACERT_dup()\fR, \fBX509_ACERT_free()\fR, \fBX509_ACERT_it()\fR, +\&\fBX509_ACERT_new()\fR, \fBX509_ACERT_INFO_free()\fR, \fBX509_ACERT_INFO_it()\fR, +\&\fBX509_ACERT_INFO_new()\fR, \fBX509_ACERT_ISSUER_V2FORM_free()\fR, +\&\fBX509_ACERT_ISSUER_V2FORM_new()\fR +were added in OpenSSL 3.4. +.PP +\&\fBOSSL_AA_DIST_POINT_free()\fR, \fBOSSL_AA_DIST_POINT_new()\fR, \fBOSSL_AA_DIST_POINT_it()\fR, +\&\fBOSSL_ALLOWED_ATTRIBUTES_CHOICE_free()\fR, \fBOSSL_ALLOWED_ATTRIBUTES_CHOICE_new()\fR, +\&\fBOSSL_ALLOWED_ATTRIBUTES_CHOICE_it()\fR, \fBOSSL_ALLOWED_ATTRIBUTES_ITEM_free()\fR, +\&\fBOSSL_ALLOWED_ATTRIBUTES_ITEM_new()\fR, \fBOSSL_ALLOWED_ATTRIBUTES_ITEM_it()\fR, +\&\fBOSSL_ALLOWED_ATTRIBUTES_SYNTAX_free()\fR, \fBOSSL_ALLOWED_ATTRIBUTES_SYNTAX_new()\fR, +\&\fBOSSL_ALLOWED_ATTRIBUTES_SYNTAX_it()\fR, +\&\fBOSSL_ATAV_free()\fR, \fBOSSL_ATAV_it()\fR, \fBOSSL_ATAV_new()\fR, +\&\fBOSSL_ATTRIBUTE_DESCRIPTOR_free()\fR, \fBOSSL_ATTRIBUTE_DESCRIPTOR_new()\fR, +\&\fBOSSL_ATTRIBUTE_DESCRIPTOR_it()\fR, +\&\fBOSSL_ATTRIBUTE_MAPPINGS_free()\fR, \fBOSSL_ATTRIBUTE_MAPPINGS_it()\fR, +\&\fBOSSL_ATTRIBUTE_MAPPINGS_new()\fR, \fBOSSL_ATTRIBUTE_MAPPING_free()\fR, +\&\fBOSSL_ATTRIBUTE_MAPPING_it()\fR, \fBOSSL_ATTRIBUTE_MAPPING_new()\fR, +\&\fBOSSL_ATTRIBUTE_TYPE_MAPPING_free()\fR, \fBOSSL_ATTRIBUTE_TYPE_MAPPING_it()\fR, +\&\fBOSSL_ATTRIBUTE_TYPE_MAPPING_new()\fR, \fBOSSL_ATTRIBUTE_VALUE_MAPPING_free()\fR, +\&\fBOSSL_ATTRIBUTE_VALUE_MAPPING_it()\fR, \fBOSSL_ATTRIBUTE_VALUE_MAPPING_new()\fR, +\&\fBOSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_free()\fR, +\&\fBOSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_it()\fR, \fBOSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX_new()\fR, +\&\fBOSSL_HASH_free()\fR, \fBOSSL_HASH_it()\fR, \fBOSSL_HASH_new()\fR, \fBOSSL_INFO_SYNTAX_free()\fR, +\&\fBOSSL_INFO_SYNTAX_it()\fR, \fBOSSL_INFO_SYNTAX_new()\fR, \fBOSSL_INFO_SYNTAX_POINTER_free()\fR, +\&\fBOSSL_INFO_SYNTAX_POINTER_it()\fR, \fBOSSL_INFO_SYNTAX_POINTER_new()\fR, +\&\fBOSSL_PRIVILEGE_POLICY_ID_free()\fR, \fBOSSL_PRIVILEGE_POLICY_ID_it()\fR, +\&\fBOSSL_PRIVILEGE_POLICY_ID_new()\fR, \fBOSSL_ROLE_SPEC_CERT_ID_free()\fR, +\&\fBOSSL_ROLE_SPEC_CERT_ID_new()\fR, \fBOSSL_ROLE_SPEC_CERT_ID_it()\fR, +\&\fBOSSL_ROLE_SPEC_CERT_ID_SYNTAX_free()\fR, \fBOSSL_ROLE_SPEC_CERT_ID_SYNTAX_new()\fR, +\&\fBOSSL_ROLE_SPEC_CERT_ID_SYNTAX_it()\fR, \fBOSSL_DAY_TIME_BAND_free()\fR, +\&\fBOSSL_DAY_TIME_BAND_it()\fR, \fBOSSL_DAY_TIME_BAND_new()\fR, +\&\fBOSSL_DAY_TIME_free()\fR, \fBOSSL_DAY_TIME_it()\fR, \fBOSSL_DAY_TIME_new()\fR, +\&\fBOSSL_NAMED_DAY_free()\fR, \fBOSSL_NAMED_DAY_it()\fR, \fBOSSL_NAMED_DAY_new()\fR, +\&\fBOSSL_TIME_PERIOD_free()\fR, \fBOSSL_TIME_PERIOD_it()\fR, \fBOSSL_TIME_PERIOD_new()\fR, +\&\fBOSSL_TIME_SPEC_ABSOLUTE_free()\fR, \fBOSSL_TIME_SPEC_ABSOLUTE_it()\fR, +\&\fBOSSL_TIME_SPEC_ABSOLUTE_new()\fR, \fBOSSL_TIME_SPEC_DAY_free()\fR, +\&\fBOSSL_TIME_SPEC_DAY_it()\fR, \fBOSSL_TIME_SPEC_DAY_new()\fR, +\&\fBOSSL_TIME_SPEC_MONTH_free()\fR, \fBOSSL_TIME_SPEC_MONTH_it()\fR, +\&\fBOSSL_TIME_SPEC_MONTH_new()\fR, \fBOSSL_TIME_SPEC_TIME_free()\fR, +\&\fBOSSL_TIME_SPEC_TIME_it()\fR, \fBOSSL_TIME_SPEC_TIME_new()\fR, +\&\fBOSSL_TIME_SPEC_WEEKS_free()\fR, \fBOSSL_TIME_SPEC_WEEKS_it()\fR, +\&\fBOSSL_TIME_SPEC_WEEKS_new()\fR, \fBOSSL_TIME_SPEC_X_DAY_OF_free()\fR, +\&\fBOSSL_TIME_SPEC_X_DAY_OF_it()\fR, \fBOSSL_TIME_SPEC_X_DAY_OF_new()\fR, +\&\fBOSSL_TIME_SPEC_free()\fR, \fBOSSL_TIME_SPEC_it()\fR, \fBOSSL_TIME_SPEC_new()\fR, +\&\fBCMS_EnvelopedData_dup()\fR, \fBOSSL_CRMF_ENCRYPTEDKEY_free()\fR, +\&\fBOSSL_CRMF_ENCRYPTEDKEY_it()\fR and \fBOSSL_CRMF_ENCRYPTEDKEY_new()\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get0_distinguishing_id.3 b/static/netbsd/man3/X509_get0_distinguishing_id.3 new file mode 100644 index 00000000..0ce76327 --- /dev/null +++ b/static/netbsd/man3/X509_get0_distinguishing_id.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: X509_get0_distinguishing_id.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get0_distinguishing_id 3" +.TH X509_get0_distinguishing_id 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get0_distinguishing_id, X509_set0_distinguishing_id, +X509_REQ_get0_distinguishing_id, X509_REQ_set0_distinguishing_id +\&\- get or set the Distinguishing ID for certificate operations +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x); +\& void X509_set0_distinguishing_id(X509 *x, ASN1_OCTET_STRING *distid); +\& ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x); +\& void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *distid); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Distinguishing ID is defined in FIPS 196 as follows: +.IP "\fIDistinguishing identifier\fR" 4 +.IX Item "Distinguishing identifier" +Information which unambiguously distinguishes +an entity in the authentication process. +.PP +The SM2 signature algorithm requires a Distinguishing ID value when generating +and verifying a signature, but the Ddistinguishing ID may also find other uses. +In the context of SM2, the Distinguishing ID is often referred to as the "SM2 +ID". +.PP +For the purpose off verifying a certificate or a certification request, a +Distinguishing ID may be attached to it, so functions like \fBX509_verify\fR\|(3) +or \fBX509_REQ_verify\fR\|(3) have easy access to that identity for signature +verification. +.PP +\&\fBX509_get0_distinguishing_id()\fR gets the Distinguishing ID value of a certificate +\&\fBx\fR by returning an \fBASN1_OCTET_STRING\fR object which should not be freed by +the caller. +.PP +\&\fBX509_set0_distinguishing_id()\fR assigns \fBdistid\fR to the certificate \fBx\fR. +Calling this function transfers the memory management of the value to the X509 +object, and therefore the value that has been passed in should not be freed by +the caller after this function has been called. +.PP +\&\fBX509_REQ_get0_distinguishing_id()\fR and \fBX509_REQ_set0_distinguishing_id()\fR +have the same functionality as \fBX509_get0_distinguishing_id()\fR and +\&\fBX509_set0_distinguishing_id()\fR except that they deal with \fBX509_REQ\fR +objects instead of \fBX509\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_set0_distinguishing_id()\fR and \fBX509_REQ_set0_distinguishing_id()\fR do not +return a value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_verify\fR\|(3), \fBSM2\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get0_notBefore.3 b/static/netbsd/man3/X509_get0_notBefore.3 new file mode 100644 index 00000000..c7b8abd8 --- /dev/null +++ b/static/netbsd/man3/X509_get0_notBefore.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: X509_get0_notBefore.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get0_notBefore 3" +.TH X509_get0_notBefore 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get0_notBefore, X509_getm_notBefore, X509_get0_notAfter, +X509_getm_notAfter, X509_set1_notBefore, X509_set1_notAfter, +X509_ACERT_get0_notBefore, X509_ACERT_get0_notAfter, +X509_ACERT_set1_notBefore, X509_ACERT_set1_notAfter, +X509_CRL_get0_lastUpdate, X509_CRL_get0_nextUpdate, X509_CRL_set1_lastUpdate, +X509_CRL_set1_nextUpdate \- get or set certificate or CRL dates +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const ASN1_TIME *X509_get0_notBefore(const X509 *x); +\& const ASN1_TIME *X509_get0_notAfter(const X509 *x); +\& +\& ASN1_TIME *X509_getm_notBefore(const X509 *x); +\& ASN1_TIME *X509_getm_notAfter(const X509 *x); +\& +\& int X509_set1_notBefore(X509 *x, const ASN1_TIME *tm); +\& int X509_set1_notAfter(X509 *x, const ASN1_TIME *tm); +\& +\& const ASN1_GENERALIZEDTIME *X509_ACERT_get0_notBefore(const X509 *x); +\& const ASN1_GENERALIZEDTIME *X509_ACERT_get0_notAfter(const X509 *x); +\& +\& int X509_ACERT_set1_notBefore(X509_ACERT *x, const ASN1_GENERALIZEDTIME *tm); +\& int X509_ACERT_set1_notAfter(X509_ACERT *x, const ASN1_GENERALIZEDTIME *tm); +\& +\& const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl); +\& const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl); +\& +\& int X509_CRL_set1_lastUpdate(X509_CRL *x, const ASN1_TIME *tm); +\& int X509_CRL_set1_nextUpdate(X509_CRL *x, const ASN1_TIME *tm); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_get0_notBefore()\fR and \fBX509_get0_notAfter()\fR return the \fBnotBefore\fR +and \fBnotAfter\fR fields of certificate \fIx\fR respectively. The value +returned is an internal pointer which must not be freed up after +the call. \fIx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBX509_getm_notBefore()\fR and \fBX509_getm_notAfter()\fR are similar to +\&\fBX509_get0_notBefore()\fR and \fBX509_get0_notAfter()\fR except they return +non\-constant mutable references to the associated date field of +the certificate. +.PP +\&\fBX509_set1_notBefore()\fR and \fBX509_set1_notAfter()\fR set the \fBnotBefore\fR +and \fBnotAfter\fR fields of \fIx\fR to \fItm\fR. Ownership of the passed +parameter \fItm\fR is not transferred by these functions so it must +be freed up after the call. +.PP +\&\fBX509_ACERT_get0_notBefore()\fR and \fBX509_ACERT_get0_notAfter()\fR return +the \fBnotBefore\fR and \fBnotAfter\fR fields of certificate \fBx\fR respectively. +returned is an internal pointer which must not be freed up after +the call. +.PP +\&\fBX509_ACERT_set1_notBefore()\fR and \fBX509_ACERT_set1_notAfter()\fR set the \fBnotBefore\fR +and \fBnotAfter\fR fields of \fBx\fR to \fBtm\fR. Ownership of the passed +parameter \fBtm\fR is not transferred by these functions so it must +be freed up after the call. +.PP +\&\fBX509_CRL_get0_lastUpdate()\fR and \fBX509_CRL_get0_nextUpdate()\fR return the +\&\fBlastUpdate\fR and \fBnextUpdate\fR fields of \fIcrl\fR. The value +returned is an internal pointer which must not be freed up after +the call. If the \fBnextUpdate\fR field is absent from \fIcrl\fR then +NULL is returned. +.PP +\&\fBX509_CRL_set1_lastUpdate()\fR and \fBX509_CRL_set1_nextUpdate()\fR set the \fBlastUpdate\fR +and \fBnextUpdate\fR fields of \fIcrl\fR to \fItm\fR. Ownership of the passed parameter +\&\fItm\fR is not transferred by these functions so it must be freed up after the +call. +For \fBX509_CRL_set1_nextUpdate()\fR the \fItm\fR argument may be NULL, +which implies removal of the optional \fBnextUpdate\fR field. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get0_notBefore()\fR, \fBX509_get0_notAfter()\fR and \fBX509_CRL_get0_lastUpdate()\fR +return a pointer to an \fBASN1_TIME\fR structure. +.PP +\&\fBX509_CRL_get0_lastUpdate()\fR return a pointer to an \fBASN1_TIME\fR structure +or NULL if the \fBlastUpdate\fR field is absent. +.PP +\&\fBX509_set1_notBefore()\fR, \fBX509_set1_notAfter()\fR, \fBX509_CRL_set1_lastUpdate()\fR and +\&\fBX509_CRL_set1_nextUpdate()\fR return 1 for success or 0 for failure. +.SH NOTES +.IX Header "NOTES" +Unlike the \fBX509\fR and \fBX509_CRL\fR routines, the \fBX509_ACERT\fR routines +use the ASN1_GENERALIZEDTIME format instead of ASN1_TIME for holding time +data. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBASN1_GENERALIZEDTIME_check\fR\|(3) +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_get_notBefore()\fR and \fBX509_get_notAfter()\fR were deprecated in OpenSSL +1.1.0. +.PP +\&\fBX509_ACERT_get0_notBefore()\fR, \fBX509_ACERT_get0_notAfter()\fR, +\&\fBX509_ACERT_set1_notBefore()\fR, \fBX509_ACERT_set1_notAfter()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get0_signature.3 b/static/netbsd/man3/X509_get0_signature.3 new file mode 100644 index 00000000..abc75a0a --- /dev/null +++ b/static/netbsd/man3/X509_get0_signature.3 @@ -0,0 +1,217 @@ +.\" $NetBSD: X509_get0_signature.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get0_signature 3" +.TH X509_get0_signature 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get0_signature, X509_REQ_set0_signature, X509_REQ_set1_signature_algo, +X509_get_signature_nid, X509_get0_tbs_sigalg, X509_REQ_get0_signature, +X509_REQ_get_signature_nid, X509_CRL_get0_signature, X509_CRL_get_signature_nid, +X509_ACERT_get0_signature, X509_ACERT_get0_info_sigalg, +X509_ACERT_get_signature_nid, X509_get_signature_info, +X509_SIG_INFO_get, X509_SIG_INFO_set \- signature information +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void X509_get0_signature(const ASN1_BIT_STRING **psig, +\& const X509_ALGOR **palg, +\& const X509 *x); +\& void X509_REQ_set0_signature(X509_REQ *req, ASN1_BIT_STRING *psig); +\& int X509_REQ_set1_signature_algo(X509_REQ *req, X509_ALGOR *palg); +\& int X509_get_signature_nid(const X509 *x); +\& const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x); +\& +\& void X509_REQ_get0_signature(const X509_REQ *crl, +\& const ASN1_BIT_STRING **psig, +\& const X509_ALGOR **palg); +\& int X509_REQ_get_signature_nid(const X509_REQ *crl); +\& +\& const X509_ALGOR *X509_ACERT_get0_info_sigalg(const X509_ACERT *x); +\& +\& void X509_CRL_get0_signature(const X509_CRL *crl, +\& const ASN1_BIT_STRING **psig, +\& const X509_ALGOR **palg); +\& int X509_CRL_get_signature_nid(const X509_CRL *crl); +\& +\& int X509_get_signature_info(X509 *x, int *mdnid, int *pknid, int *secbits, +\& uint32_t *flags); +\& +\& int X509_SIG_INFO_get(const X509_SIG_INFO *siginf, int *mdnid, int *pknid, +\& int *secbits, uint32_t *flags); +\& void X509_SIG_INFO_set(X509_SIG_INFO *siginf, int mdnid, int pknid, +\& int secbits, uint32_t flags); +\& +\& #include +\& +\& void X509_ACERT_get0_signature(const X509_ACERT *x, +\& const ASN1_BIT_STRING **psig, +\& const X509_ALGOR **palg); +\& int X509_ACERT_get_signature_nid(const X509_ACERT *x); +\&=head1 DESCRIPTION +.Ve +.PP +\&\fBX509_get0_signature()\fR sets \fB*psig\fR to the signature of \fBx\fR and \fB*palg\fR +to the signature algorithm of \fBx\fR. The values returned are internal +pointers which \fBMUST NOT\fR be freed up after the call. +.PP +\&\fBX509_set0_signature()\fR and \fBX509_REQ_set1_signature_algo()\fR are the +equivalent setters for the two values of \fBX509_get0_signature()\fR. +.PP +\&\fBX509_get0_tbs_sigalg()\fR returns the signature algorithm in the signed +portion of \fBx\fR. +.PP +\&\fBX509_get_signature_nid()\fR returns the NID corresponding to the signature +algorithm of \fBx\fR. +.PP +\&\fBX509_REQ_get0_signature()\fR, \fBX509_REQ_get_signature_nid()\fR +\&\fBX509_CRL_get0_signature()\fR and \fBX509_CRL_get_signature_nid()\fR perform the +same function for certificate requests and CRLs. +.PP +\&\fBX509_ACERT_get0_signature()\fR, \fBX509_ACERT_get_signature_nid()\fR and +\&\fBX509_ACERT_get0_info_sigalg()\fR perform the same function for attribute +certificates. +.PP +\&\fBX509_get_signature_info()\fR retrieves information about the signature of +certificate \fBx\fR. The NID of the signing digest is written to \fB*mdnid\fR, +the public key algorithm to \fB*pknid\fR, the effective security bits to +\&\fB*secbits\fR and flag details to \fB*flags\fR. Any of the parameters can +be set to \fBNULL\fR if the information is not required. +.PP +\&\fBX509_SIG_INFO_get()\fR and \fBX509_SIG_INFO_set()\fR get and set information +about a signature in an \fBX509_SIG_INFO\fR structure. They are only +used by implementations of algorithms which need to set custom +signature information: most applications will never need to call +them. +.SH NOTES +.IX Header "NOTES" +These functions provide lower level access to signatures in certificates +where an application wishes to analyse or generate a signature in a form +where \fBX509_sign()\fR et al is not appropriate (for example a non standard +or unsupported format). +.PP +The security bits returned by \fBX509_get_signature_info()\fR refers to information +available from the certificate signature (such as the signing digest). In some +cases the actual security of the signature is less because the signing +key is less secure: for example a certificate signed using SHA\-512 and a +1024 bit RSA key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_signature_nid()\fR, \fBX509_REQ_get_signature_nid()\fR and +\&\fBX509_CRL_get_signature_nid()\fR return a NID. +.PP +\&\fBX509_get0_signature()\fR, \fBX509_REQ_get0_signature()\fR and +\&\fBX509_CRL_get0_signature()\fR do not return values. +.PP +\&\fBX509_get_signature_info()\fR returns 1 if the signature information +returned is valid or 0 if the information is not available (e.g. +unknown algorithms or malformed parameters). +.PP +\&\fBX509_REQ_set1_signature_algo()\fR returns 0 on success; or 1 on an +error (e.g. null ALGO pointer). X509_REQ_set0_signature does +not return an error value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The +\&\fBX509_get0_signature()\fR and \fBX509_get_signature_nid()\fR functions were +added in OpenSSL 1.0.2. +.PP +The +\&\fBX509_REQ_get0_signature()\fR, \fBX509_REQ_get_signature_nid()\fR, +\&\fBX509_CRL_get0_signature()\fR and \fBX509_CRL_get_signature_nid()\fR were +added in OpenSSL 1.1.0. +.PP +The \fBX509_REQ_set0_signature()\fR and \fBX509_REQ_set1_signature_algo()\fR +were added in OpenSSL 1.1.1e. +.PP +The \fBX509_ACERT_get0_signature()\fR, \fBX509_ACERT_get0_info_sigalg()\fR and +\&\fBX509_ACERT_get_signature_nid()\fR functions were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get0_uids.3 b/static/netbsd/man3/X509_get0_uids.3 new file mode 100644 index 00000000..10983353 --- /dev/null +++ b/static/netbsd/man3/X509_get0_uids.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: X509_get0_uids.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get0_uids 3" +.TH X509_get0_uids 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get0_uids, X509_ACERT_get0_issuerUID +\&\- get certificate and attribute certificate unique identifiers +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void X509_get0_uids(const X509 *x, const ASN1_BIT_STRING **piuid, +\& const ASN1_BIT_STRING **psuid); +\& +\& #include +\& +\& ASN1_BIT_STRING *X509_ACERT_get0_issuerUID(X509_ACERT *x); +\&=head1 DESCRIPTION +.Ve +.PP +\&\fBX509_get0_uids()\fR sets \fB*piuid\fR and \fB*psuid\fR to the issuer and subject unique +identifiers of certificate \fBx\fR or NULL if the fields are not present. +.PP +\&\fBX509_ACERT_get0_issuerUID()\fR returns the issuer unique identifier of the +attribute certificate \fBx\fR or NULL if the field is not present. +.SH NOTES +.IX Header "NOTES" +The issuer and subject unique identifier fields are very rarely encountered in +practice outside test cases. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get0_uids()\fR does not return a value. +.PP +\&\fBX509_ACERT_get0_issuerUID()\fR returns a unique identifier on success or NULL +on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_get0_uids()\fR was added in OpenSSL 1.1.0. +.PP +\&\fBX509_ACERT_get0_issuerUID()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_default_cert_file.3 b/static/netbsd/man3/X509_get_default_cert_file.3 new file mode 100644 index 00000000..25eb7aef --- /dev/null +++ b/static/netbsd/man3/X509_get_default_cert_file.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: X509_get_default_cert_file.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_default_cert_file 3" +.TH X509_get_default_cert_file 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get_default_cert_file, X509_get_default_cert_file_env, +X509_get_default_cert_dir, X509_get_default_cert_dir_env \- +retrieve default locations for trusted CA certificates +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& const char *X509_get_default_cert_file(void); +\& const char *X509_get_default_cert_dir(void); +\& +\& const char *X509_get_default_cert_file_env(void); +\& const char *X509_get_default_cert_dir_env(void); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX509_get_default_cert_file()\fR function returns the default path +to a file containing trusted CA certificates. OpenSSL will use this as +the default path when it is asked to load trusted CA certificates +from a file and no other path is specified. If the file exists, CA certificates +are loaded from the file. +.PP +The \fBX509_get_default_cert_dir()\fR function returns a default delimeter\-separated +list of paths to a directories containing trusted CA certificates named in the +hashed format. OpenSSL will use this as the default list of paths when it is +asked to load trusted CA certificates from a directory and no other path is +specified. If a given directory in the list exists, OpenSSL attempts to lookup +CA certificates in this directory by calculating a filename based on a hash of +the certificate\*(Aqs subject name. +.PP +\&\fBX509_get_default_cert_file_env()\fR returns an environment variable name which is +recommended to specify a nondefault value to be used instead of the value +returned by \fBX509_get_default_cert_file()\fR. The value returned by the latter +function is not affected by these environment variables; you must check for this +environment variable yourself, using this function to retrieve the correct +environment variable name. If an environment variable is not set, the value +returned by the \fBX509_get_default_cert_file()\fR should be used. +.PP +\&\fBX509_get_default_cert_dir_env()\fR returns the environment variable name which is +recommended to specify a nondefault value to be used instead of the value +returned by \fBX509_get_default_cert_dir()\fR. The value specified by this environment +variable can also be a store URI (but see BUGS below). +.SH BUGS +.IX Header "BUGS" +By default (for example, when \fBX509_STORE_set_default_paths\fR\|(3) is used), the +environment variable name returned by \fBX509_get_default_cert_dir_env()\fR is +interpreted both as a delimiter\-separated list of paths, and as a store URI. +This is ambiguous. For example, specifying a value of \fB"file:///etc/certs"\fR +would cause instantiation of the "file" store provided as part of the default +provider, but would also cause an \fBX509_LOOKUP_hash_dir\fR\|(3) instance to look +for certificates in the directory \fB"file"\fR (relative to the current working +directory) and the directory \fB"///etc/certs"\fR. This can be avoided by avoiding +use of the environment variable mechanism and using other methods to construct +X509_LOOKUP instances. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions return pointers to constant strings with static storage +duration. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_LOOKUP\fR\|(3), +\&\fBSSL_CTX_set_default_verify_file\fR\|(3), +\&\fBSSL_CTX_set_default_verify_dir\fR\|(3), +\&\fBSSL_CTX_set_default_verify_store\fR\|(3), +\&\fBSSL_CTX_load_verify_file\fR\|(3), +\&\fBSSL_CTX_load_verify_dir\fR\|(3), +\&\fBSSL_CTX_load_verify_store\fR\|(3), +\&\fBSSL_CTX_load_verify_locations\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_extension_flags.3 b/static/netbsd/man3/X509_get_extension_flags.3 new file mode 100644 index 00000000..c0a6f859 --- /dev/null +++ b/static/netbsd/man3/X509_get_extension_flags.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: X509_get_extension_flags.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_extension_flags 3" +.TH X509_get_extension_flags 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get0_subject_key_id, +X509_get0_authority_key_id, +X509_get0_authority_issuer, +X509_get0_authority_serial, +X509_get_pathlen, +X509_get_extension_flags, +X509_get_key_usage, +X509_get_extended_key_usage, +X509_set_proxy_flag, +X509_set_proxy_pathlen, +X509_get_proxy_pathlen \- retrieve certificate extension data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long X509_get_pathlen(X509 *x); +\& uint32_t X509_get_extension_flags(X509 *x); +\& uint32_t X509_get_key_usage(X509 *x); +\& uint32_t X509_get_extended_key_usage(X509 *x); +\& const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x); +\& const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x); +\& const GENERAL_NAMES *X509_get0_authority_issuer(X509 *x); +\& const ASN1_INTEGER *X509_get0_authority_serial(X509 *x); +\& void X509_set_proxy_flag(X509 *x); +\& void X509_set_proxy_pathlen(int l); +\& long X509_get_proxy_pathlen(X509 *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions retrieve information related to commonly used certificate extensions. +.PP +\&\fBX509_get_pathlen()\fR retrieves the path length extension from a certificate. +This extension is used to limit the length of a cert chain that may be +issued from that CA. +.PP +\&\fBX509_get_extension_flags()\fR retrieves general information about a certificate, +it will return one or more of the following flags ored together. +.IP \fBEXFLAG_V1\fR 4 +.IX Item "EXFLAG_V1" +The certificate is an obsolete version 1 certificate. +.IP \fBEXFLAG_BCONS\fR 4 +.IX Item "EXFLAG_BCONS" +The certificate contains a basic constraints extension. +.IP \fBEXFLAG_CA\fR 4 +.IX Item "EXFLAG_CA" +The certificate contains basic constraints and asserts the CA flag. +.IP \fBEXFLAG_PROXY\fR 4 +.IX Item "EXFLAG_PROXY" +The certificate is a valid proxy certificate. +.IP \fBEXFLAG_SI\fR 4 +.IX Item "EXFLAG_SI" +The certificate is self issued (that is subject and issuer names match). +.IP \fBEXFLAG_SS\fR 4 +.IX Item "EXFLAG_SS" +The subject and issuer names match and extension values imply it is self +signed. +.IP \fBEXFLAG_FRESHEST\fR 4 +.IX Item "EXFLAG_FRESHEST" +The freshest CRL extension is present in the certificate. +.IP \fBEXFLAG_CRITICAL\fR 4 +.IX Item "EXFLAG_CRITICAL" +The certificate contains an unhandled critical extension. +.IP \fBEXFLAG_INVALID\fR 4 +.IX Item "EXFLAG_INVALID" +Some certificate extension values are invalid or inconsistent. +The certificate should be rejected. +This bit may also be raised after an out\-of\-memory error while +processing the X509 object, so it may not be related to the processed +ASN1 object itself. +.IP \fBEXFLAG_NO_FINGERPRINT\fR 4 +.IX Item "EXFLAG_NO_FINGERPRINT" +Failed to compute the internal SHA1 hash value of the certificate or CRL. +This may be due to malloc failure or because no SHA1 implementation was found. +.IP \fBEXFLAG_INVALID_POLICY\fR 4 +.IX Item "EXFLAG_INVALID_POLICY" +The NID_certificate_policies certificate extension is invalid or +inconsistent. The certificate should be rejected. +This bit may also be raised after an out\-of\-memory error while +processing the X509 object, so it may not be related to the processed +ASN1 object itself. +.IP \fBEXFLAG_KUSAGE\fR 4 +.IX Item "EXFLAG_KUSAGE" +The certificate contains a key usage extension. The value can be retrieved +using \fBX509_get_key_usage()\fR. +.IP \fBEXFLAG_XKUSAGE\fR 4 +.IX Item "EXFLAG_XKUSAGE" +The certificate contains an extended key usage extension. The value can be +retrieved using \fBX509_get_extended_key_usage()\fR. +.PP +\&\fBX509_get_key_usage()\fR returns the value of the key usage extension. If key +usage is present will return zero or more of the flags: +\&\fBKU_DIGITAL_SIGNATURE\fR, \fBKU_NON_REPUDIATION\fR, \fBKU_KEY_ENCIPHERMENT\fR, +\&\fBKU_DATA_ENCIPHERMENT\fR, \fBKU_KEY_AGREEMENT\fR, \fBKU_KEY_CERT_SIGN\fR, +\&\fBKU_CRL_SIGN\fR, \fBKU_ENCIPHER_ONLY\fR or \fBKU_DECIPHER_ONLY\fR corresponding to +individual key usage bits. If key usage is absent then \fBUINT32_MAX\fR is +returned. +.PP +\&\fBX509_get_extended_key_usage()\fR returns the value of the extended key usage +extension. If extended key usage is present it will return zero or more of the +flags: \fBXKU_SSL_SERVER\fR, \fBXKU_SSL_CLIENT\fR, \fBXKU_SMIME\fR, \fBXKU_CODE_SIGN\fR +\&\fBXKU_OCSP_SIGN\fR, \fBXKU_TIMESTAMP\fR, \fBXKU_DVCS\fR or \fBXKU_ANYEKU\fR. These +correspond to the OIDs \fBid\-kp\-serverAuth\fR, \fBid\-kp\-clientAuth\fR, +\&\fBid\-kp\-emailProtection\fR, \fBid\-kp\-codeSigning\fR, \fBid\-kp\-OCSPSigning\fR, +\&\fBid\-kp\-timeStamping\fR, \fBid\-kp\-dvcs\fR and \fBanyExtendedKeyUsage\fR respectively. +Additionally \fBXKU_SGC\fR is set if either Netscape or Microsoft SGC OIDs are +present. +.PP +\&\fBX509_get0_subject_key_id()\fR returns an internal pointer to the subject key +identifier of \fBx\fR as an \fBASN1_OCTET_STRING\fR or \fBNULL\fR if the extension +is not present or cannot be parsed. +.PP +\&\fBX509_get0_authority_key_id()\fR returns an internal pointer to the authority key +identifier of \fBx\fR as an \fBASN1_OCTET_STRING\fR or \fBNULL\fR if the extension +is not present or cannot be parsed. +.PP +\&\fBX509_get0_authority_issuer()\fR returns an internal pointer to the authority +certificate issuer of \fBx\fR as a stack of \fBGENERAL_NAME\fR structures or +\&\fBNULL\fR if the extension is not present or cannot be parsed. +.PP +\&\fBX509_get0_authority_serial()\fR returns an internal pointer to the authority +certificate serial number of \fBx\fR as an \fBASN1_INTEGER\fR or \fBNULL\fR if the +extension is not present or cannot be parsed. +.PP +\&\fBX509_set_proxy_flag()\fR marks the certificate with the \fBEXFLAG_PROXY\fR flag. +This is for the users who need to mark non\-RFC3820 proxy certificates as +such, as OpenSSL only detects RFC3820 compliant ones. +.PP +\&\fBX509_set_proxy_pathlen()\fR sets the proxy certificate path length for the given +certificate \fBx\fR. This is for the users who need to mark non\-RFC3820 proxy +certificates as such, as OpenSSL only detects RFC3820 compliant ones. +.PP +\&\fBX509_get_proxy_pathlen()\fR returns the proxy certificate path length for the +given certificate \fBx\fR if it is a proxy certificate. +.SH NOTES +.IX Header "NOTES" +The value of the flags correspond to extension values which are cached +in the \fBX509\fR structure. If the flags returned do not provide sufficient +information an application should examine extension values directly +for example using \fBX509_get_ext_d2i()\fR. +.PP +If the key usage or extended key usage extension is absent then typically usage +is unrestricted. For this reason \fBX509_get_key_usage()\fR and +\&\fBX509_get_extended_key_usage()\fR return \fBUINT32_MAX\fR when the corresponding +extension is absent. Applications can additionally check the return value of +\&\fBX509_get_extension_flags()\fR and take appropriate action is an extension is +absent. +.PP +If \fBX509_get0_subject_key_id()\fR returns \fBNULL\fR then the extension may be +absent or malformed. Applications can determine the precise reason using +\&\fBX509_get_ext_d2i()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_pathlen()\fR returns the path length value, or \-1 if the extension +is not present. +.PP +\&\fBX509_get_extension_flags()\fR, \fBX509_get_key_usage()\fR and +\&\fBX509_get_extended_key_usage()\fR return sets of flags corresponding to the +certificate extension values. +.PP +\&\fBX509_get0_subject_key_id()\fR returns the subject key identifier as a +pointer to an \fBASN1_OCTET_STRING\fR structure or \fBNULL\fR if the extension +is absent or an error occurred during parsing. +.PP +\&\fBX509_get_proxy_pathlen()\fR returns the path length value if the given +certificate is a proxy one and has a path length set, and \-1 otherwise. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509_check_purpose\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_get_pathlen()\fR, \fBX509_set_proxy_flag()\fR, \fBX509_set_proxy_pathlen()\fR and +\&\fBX509_get_proxy_pathlen()\fR were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_pubkey.3 b/static/netbsd/man3/X509_get_pubkey.3 new file mode 100644 index 00000000..6294d530 --- /dev/null +++ b/static/netbsd/man3/X509_get_pubkey.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: X509_get_pubkey.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_pubkey 3" +.TH X509_get_pubkey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY, +X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey, +X509_REQ_get_X509_PUBKEY \- get or set certificate or certificate request +public key +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *X509_get_pubkey(X509 *x); +\& EVP_PKEY *X509_get0_pubkey(const X509 *x); +\& int X509_set_pubkey(X509 *x, EVP_PKEY *pkey); +\& X509_PUBKEY *X509_get_X509_PUBKEY(const X509 *x); +\& +\& EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *req); +\& EVP_PKEY *X509_REQ_get0_pubkey(X509_REQ *req); +\& int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey); +\& X509_PUBKEY *X509_REQ_get_X509_PUBKEY(X509_REQ *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_get_pubkey()\fR attempts to decode the public key for certificate \fBx\fR. If +successful it returns the public key as an \fBEVP_PKEY\fR pointer with its +reference count incremented: this means the returned key must be freed up +after use. \fBX509_get0_pubkey()\fR is similar except it does \fBnot\fR increment +the reference count of the returned \fBEVP_PKEY\fR so it must not be freed up +after use. +.PP +\&\fBX509_get_X509_PUBKEY()\fR returns an internal pointer to the \fBX509_PUBKEY\fR +structure which encodes the certificate of \fBx\fR. The returned value +must not be freed up after use. +.PP +\&\fBX509_set_pubkey()\fR attempts to set the public key for certificate \fBx\fR to +\&\fBpkey\fR. The key \fBpkey\fR should be freed up after use. +.PP +\&\fBX509_REQ_get_pubkey()\fR, \fBX509_REQ_get0_pubkey()\fR, \fBX509_REQ_set_pubkey()\fR and +\&\fBX509_REQ_get_X509_PUBKEY()\fR are similar but operate on certificate request \fBreq\fR. +.SH NOTES +.IX Header "NOTES" +The first time a public key is decoded the \fBEVP_PKEY\fR structure is +cached in the certificate or certificate request itself. Subsequent calls +return the cached structure with its reference count incremented to +improve performance. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_pubkey()\fR, \fBX509_get0_pubkey()\fR, \fBX509_get_X509_PUBKEY()\fR, +\&\fBX509_REQ_get_pubkey()\fR and \fBX509_REQ_get_X509_PUBKEY()\fR return a public key or +\&\fBNULL\fR if an error occurred. +.PP +\&\fBX509_set_pubkey()\fR and \fBX509_REQ_set_pubkey()\fR return 1 for success and 0 +for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_serialNumber.3 b/static/netbsd/man3/X509_get_serialNumber.3 new file mode 100644 index 00000000..413dcfec --- /dev/null +++ b/static/netbsd/man3/X509_get_serialNumber.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: X509_get_serialNumber.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_serialNumber 3" +.TH X509_get_serialNumber 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get_serialNumber, +X509_get0_serialNumber, +X509_set_serialNumber, +X509_ACERT_get0_serialNumber, +X509_ACERT_set1_serialNumber +\&\- get or set certificate serial number +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_INTEGER *X509_get_serialNumber(X509 *x); +\& const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x); +\& int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial); +\& +\& #include +\& +\& ASN1_INTEGER *X509_ACERT_get0_serialNumber(X509_ACERT *x); +\& int X509_ACERT_set1_serialNumber(X509_ACERT *x, ASN1_INTEGER *serial); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_get_serialNumber()\fR returns the serial number of certificate \fBx\fR as an +\&\fBASN1_INTEGER\fR structure which can be examined or initialised. The value +returned is an internal pointer which \fBMUST NOT\fR be freed up after the call. +.PP +\&\fBX509_get0_serialNumber()\fR is the same as \fBX509_get_serialNumber()\fR except it +accepts a const parameter and returns a const result. +.PP +\&\fBX509_set_serialNumber()\fR sets the serial number of certificate \fBx\fR to +\&\fBserial\fR. A copy of the serial number is used internally so \fBserial\fR should +be freed up after use. +.PP +\&\fBX509_ACERT_get0_serialNumber()\fR performs the same operation as +\&\fBX509_get_serialNumber()\fR for attribute certificates. +.PP +\&\fBX509_ACERT_set1_serialNumber()\fR performs the same operation as +\&\fBX509_set_serialNumber()\fR for attribute certificates. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_serialNumber()\fR, \fBX509_get0_serialNumber()\fR and +\&\fBX509_ACERT_get0_serialNumber()\fR return a pointer to an \fBASN1_INTEGER\fR structure. +.PP +\&\fBX509_set_serialNumber()\fR and \fBX509_ACERT_set1_serialNumber()\fR return 1 for success +and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_get_serialNumber()\fR and \fBX509_set_serialNumber()\fR functions are +available in all versions of OpenSSL. +The \fBX509_get0_serialNumber()\fR function was added in OpenSSL 1.1.0. +The \fBX509_ACERT_get0_serialNumber()\fR and \fBX509_ACERT_set1_serialNumber()\fR +functions were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_subject_name.3 b/static/netbsd/man3/X509_get_subject_name.3 new file mode 100644 index 00000000..f17f0573 --- /dev/null +++ b/static/netbsd/man3/X509_get_subject_name.3 @@ -0,0 +1,201 @@ +.\" $NetBSD: X509_get_subject_name.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_subject_name 3" +.TH X509_get_subject_name 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_NAME_hash_ex, X509_NAME_hash, +X509_get_subject_name, X509_set_subject_name, X509_subject_name_hash, +X509_get_issuer_name, X509_set_issuer_name, X509_issuer_name_hash, +X509_REQ_get_subject_name, X509_REQ_set_subject_name, +X509_ACERT_get0_issuerName, X509_ACERT_set1_issuerName, +X509_CRL_get_issuer, X509_CRL_set_issuer_name \- +get X509_NAME hashes or get and set issuer or subject names +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& unsigned long X509_NAME_hash_ex(const X509_NAME *x, OSSL_LIB_CTX *libctx, +\& const char *propq, int *ok); +\& +\& X509_NAME *X509_get_subject_name(const X509 *x); +\& int X509_set_subject_name(X509 *x, const X509_NAME *name); +\& unsigned long X509_subject_name_hash(X509 *x); +\& +\& X509_NAME *X509_get_issuer_name(const X509 *x); +\& int X509_set_issuer_name(X509 *x, const X509_NAME *name); +\& unsigned long X509_issuer_name_hash(X509 *x); +\& +\& X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req); +\& int X509_REQ_set_subject_name(X509_REQ *req, const X509_NAME *name); +\& +\& X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl); +\& int X509_CRL_set_issuer_name(X509_CRL *x, const X509_NAME *name); +\& +\& #include +\& +\& X509_NAME *X509_ACERT_get0_issuerName(const X509_ACERT *x); +\& int X509_ACERT_set1_issuerName(X509_ACERT *x, const X509_NAME *name); +.Ve +.PP +The following macro has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #define X509_NAME_hash(x) X509_NAME_hash_ex(x, NULL, NULL, NULL) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_NAME_hash_ex()\fR returns a hash value of name \fIx\fR or 0 on failure, +using any given library context \fIlibctx\fR and property query \fIpropq\fR. +The \fIok\fR result argument may be NULL +or else is used to return 1 for success and 0 for failure. +Failure may happen on malloc error or if no SHA1 implementation is available. +.PP +\&\fBX509_NAME_hash()\fR returns a hash value of name \fIx\fR or 0 on failure, +using the default library context and default property query. +.PP +\&\fBX509_get_subject_name()\fR returns the subject name of certificate \fIx\fR. The +returned value is an internal pointer which \fBMUST NOT\fR be freed. \fIx\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBX509_set_subject_name()\fR sets the issuer name of certificate \fIx\fR to +\&\fIname\fR. The \fIname\fR parameter is copied internally and should be freed +up when it is no longer needed. +.PP +\&\fBX509_subject_name_hash()\fR returns a hash value of the subject name of +certificate \fIx\fR. +.PP +\&\fBX509_get_issuer_name()\fR, \fBX509_set_issuer_name()\fR, and \fBX509_issuer_name_hash()\fR +are identical to +\&\fBX509_get_subject_name()\fR, \fBX509_set_subject_name()\fR, and \fBX509_subject_name_hash()\fR +except they relate to the issuer name of \fIx\fR. +.PP +Similarly \fBX509_REQ_get_subject_name()\fR, \fBX509_REQ_set_subject_name()\fR, +\&\fBX509_ACERT_get0_issuerName()\fR, \fBX509_ACERT_set1_issuerName()\fR, +\&\fBX509_CRL_get_issuer()\fR and \fBX509_CRL_set_issuer_name()\fR get or set the subject +or issuer names of certificate requests of CRLs respectively. +.PP +Since attribute certificates do not have a subject name, only the issuer name +can be set. For details on setting X509_ACERT holder identities, see +\&\fBX509_ACERT_set0_holder_entityName\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_subject_name()\fR, \fBX509_get_issuer_name()\fR, \fBX509_REQ_get_subject_name()\fR +\&\fBX509_ACERT_get0_issuerName()\fR and \fBX509_CRL_get_issuer()\fR return +an \fBX509_NAME\fR pointer. +.PP +\&\fBX509_NAME_hash_ex()\fR, \fBX509_NAME_hash()\fR, +\&\fBX509_subject_name_hash()\fR and \fBX509_issuer_name_hash()\fR +return the first four bytes of the SHA1 hash value, +converted to \fBunsigned long\fR in little endian order, +or 0 on failure. +.PP +\&\fBX509_set_subject_name()\fR, \fBX509_set_issuer_name()\fR, \fBX509_REQ_set_subject_name()\fR, +\&\fBX509_ACERT_get0_issuerName()\fR and \fBX509_CRL_set_issuer_name()\fR return 1 for +success and 0 for failure. +.SH BUGS +.IX Header "BUGS" +In case \fBX509_NAME_hash()\fR, \fBX509_subject_name_hash()\fR, or \fBX509_issuer_name_hash()\fR +returns 0 it remains unclear if this is the real hash value or due to failure. +Better use \fBX509_NAME_hash_ex()\fR instead. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), \fBd2i_X509\fR\|(3) +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_REQ_get_subject_name()\fR is a function in OpenSSL 1.1.0 and a macro in +earlier versions. +.PP +\&\fBX509_CRL_get_issuer()\fR is a function in OpenSSL 1.1.0. It was previously +added in OpenSSL 1.0.0 as a macro. +.PP +\&\fBX509_NAME_hash()\fR was turned into a macro and deprecated in OpenSSL 3.0. +.PP +\&\fBX509_ACERT_get0_issuerName()\fR, \fBX509_ACERT_set1_issuerName()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_get_version.3 b/static/netbsd/man3/X509_get_version.3 new file mode 100644 index 00000000..71357d60 --- /dev/null +++ b/static/netbsd/man3/X509_get_version.3 @@ -0,0 +1,153 @@ +.\" $NetBSD: X509_get_version.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_get_version 3" +.TH X509_get_version 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_get_version, X509_set_version, X509_REQ_get_version, X509_REQ_set_version, +X509_ACERT_get_version, X509_ACERT_set_version, X509_CRL_get_version, +X509_CRL_set_version \- get or set certificate, +certificate request or CRL version +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& long X509_get_version(const X509 *x); +\& int X509_set_version(X509 *x, long version); +\& +\& long X509_REQ_get_version(const X509_REQ *req); +\& int X509_REQ_set_version(X509_REQ *x, long version); +\& +\& long X509_CRL_get_version(const X509_CRL *crl); +\& int X509_CRL_set_version(X509_CRL *x, long version); +\& +\& #include +\& +\& int X509_ACERT_set_version(X509_ACERT *x, long version); +\& long X509_ACERT_get_version(const X509_ACERT *x); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_get_version()\fR returns the numerical value of the version field of +certificate \fIx\fR. These correspond to the constants \fBX509_VERSION_1\fR, +\&\fBX509_VERSION_2\fR, and \fBX509_VERSION_3\fR. Note: the values of these constants +are defined by standards (X.509 et al) to be one less than the certificate +version. So \fBX509_VERSION_3\fR has value 2 and \fBX509_VERSION_1\fR has value 0. +.PP +\&\fBX509_set_version()\fR sets the numerical value of the version field of certificate +\&\fIx\fR to \fIversion\fR. +.PP +Similarly \fBX509_REQ_get_version()\fR, \fBX509_REQ_set_version()\fR, +\&\fBX509_ACERT_get_version()\fR, \fBX509_ACERT_set_version()\fR, +\&\fBX509_CRL_get_version()\fR and \fBX509_CRL_set_version()\fR get and set the version +number of certificate requests and CRLs. They use constants +\&\fBX509_REQ_VERSION_1\fR, \fBX509_ACERT_VERSION_2\fR, \fBX509_CRL_VERSION_1\fR, +and \fBX509_CRL_VERSION_2\fR. +.SH NOTES +.IX Header "NOTES" +The version field of certificates, certificate requests and CRLs has a +DEFAULT value of \fBv1\|(0)\fR meaning the field should be omitted for version +1. This is handled transparently by these functions. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_get_version()\fR, \fBX509_REQ_get_version()\fR and \fBX509_CRL_get_version()\fR +return the numerical value of the version field. +.PP +\&\fBX509_set_version()\fR, \fBX509_REQ_set_version()\fR and \fBX509_CRL_set_version()\fR +return 1 for success and 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_get_version()\fR, \fBX509_REQ_get_version()\fR and \fBX509_CRL_get_version()\fR are +functions in OpenSSL 1.1.0, in previous versions they were macros. +.PP +\&\fBX509_ACERT_get_version()\fR, \fBX509_ACERT_set_version()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_load_http.3 b/static/netbsd/man3/X509_load_http.3 new file mode 100644 index 00000000..6459403f --- /dev/null +++ b/static/netbsd/man3/X509_load_http.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: X509_load_http.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_load_http 3" +.TH X509_load_http 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_load_http, +X509_http_nbio, +X509_CRL_load_http, +X509_CRL_http_nbio +\&\- certificate and CRL loading functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *X509_load_http(const char *url, BIO *bio, BIO *rbio, int timeout); +\& X509_CRL *X509_CRL_load_http(const char *url, BIO *bio, BIO *rbio, int timeout); +.Ve +.PP +The following macros have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& #define X509_http_nbio(rctx, pcert) +\& #define X509_CRL_http_nbio(rctx, pcrl) +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_load_http()\fR and \fBX509_CRL_load_http()\fR loads a certificate or a CRL, +respectively, in ASN.1 format using HTTP from the given \fBurl\fR. +.PP +Maximum size of the HTTP response is 100 kB for certificates and 32 MB for CRLs +and hard coded in the functions. +.PP +If \fBbio\fR is given and \fBrbio\fR is NULL then this BIO is used instead of an +internal one for connecting, writing the request, and reading the response. +If both \fBbio\fR and \fBrbio\fR are given (which may be memory BIOs, for instance) +then no explicit connection is attempted, +\&\fBbio\fR is used for writing the request, and \fBrbio\fR for reading the response. +.PP +If the \fBtimeout\fR parameter is > 0 this indicates the maximum number of seconds +to wait until the transfer is complete. +A value of 0 enables waiting indefinitely, +while a value < 0 immediately leads to a timeout condition. +.PP +\&\fBX509_http_nbio()\fR and \fBX509_CRL_http_nbio()\fR are macros for backward compatibility +that have the same effect as the functions above but with infinite timeout +and without the possibility to specify custom BIOs. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +On success the function yield the loaded value, else NULL. +Error conditions include connection/transfer timeout, parse errors, etc. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_HTTP_get\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_load_http()\fR and \fBX509_CRL_load_http()\fR were added in OpenSSL 3.0. +\&\fBX509_http_nbio()\fR and \fBX509_CRL_http_nbio()\fR were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_new.3 b/static/netbsd/man3/X509_new.3 new file mode 100644 index 00000000..345afa25 --- /dev/null +++ b/static/netbsd/man3/X509_new.3 @@ -0,0 +1,165 @@ +.\" $NetBSD: X509_new.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_new 3" +.TH X509_new 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_new, X509_new_ex, +X509_free, X509_up_ref, +X509_chain_up_ref, +OSSL_STACK_OF_X509_free +\&\- X509 certificate ASN1 allocation and deallocation functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *X509_new(void); +\& X509 *X509_new_ex(OSSL_LIB_CTX *libctx, const char *propq); +\& void X509_free(X509 *a); +\& int X509_up_ref(X509 *a); +\& STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x); +\& void OSSL_STACK_OF_X509_free(STACK_OF(X509) *certs); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The X509 ASN1 allocation routines allocate and free an +X509 structure, which represents an X509 certificate. +.PP +\&\fBX509_new_ex()\fR allocates and initializes a X509 structure with a +library context of \fIlibctx\fR, property query of \fIpropq\fR and a reference +count of \fB1\fR. Many X509 functions such as \fBX509_check_purpose()\fR, and +\&\fBX509_verify()\fR use this library context to select which providers supply the +fetched algorithms (SHA1 is used internally). This created X509 object can then +be used when loading binary data using \fBd2i_X509()\fR. +.PP +\&\fBX509_new()\fR is similar to \fBX509_new_ex()\fR but sets the library context +and property query to NULL. This results in the default (NULL) library context +being used for any X509 operations requiring algorithm fetches. +.PP +\&\fBX509_free()\fR decrements the reference count of \fBX509\fR structure \fBa\fR and +frees it up if the reference count is zero. If the argument is NULL, +nothing is done. +.PP +\&\fBX509_up_ref()\fR increments the reference count of \fBa\fR. +.PP +\&\fBX509_chain_up_ref()\fR increases the reference count of all certificates in +chain \fBx\fR and returns a copy of the stack, or an empty stack if \fBa\fR is NULL. +.PP +\&\fBOSSL_STACK_OF_X509_free()\fR deallocates the given list of pointers to +certificates after calling \fBX509_free()\fR on all its elements. +If the argument is NULL, nothing is done. +.SH NOTES +.IX Header "NOTES" +The function \fBX509_up_ref()\fR if useful if a certificate structure is being +used by several different operations each of which will free it up after +use: this avoids the need to duplicate the entire certificate structure. +.PP +The function \fBX509_chain_up_ref()\fR doesn\*(Aqt just up the reference count of +each certificate. It also returns a copy of the stack, using \fBsk_X509_dup()\fR, +but it serves a similar purpose: the returned chain persists after the +original has been freed. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +If the allocation fails, \fBX509_new()\fR returns NULL and sets an error +code that can be obtained by \fBERR_get_error\fR\|(3). +Otherwise it returns a pointer to the newly allocated structure. +.PP +\&\fBX509_up_ref()\fR returns 1 for success and 0 for failure. +.PP +\&\fBX509_chain_up_ref()\fR returns a copy of the stack or NULL if an error occurred. +.PP +\&\fBOSSL_STACK_OF_X509_free()\fR has no return value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_new_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBOSSL_STACK_OF_X509_free()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_sign.3 b/static/netbsd/man3/X509_sign.3 new file mode 100644 index 00000000..6469c473 --- /dev/null +++ b/static/netbsd/man3/X509_sign.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: X509_sign.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_sign 3" +.TH X509_sign 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_sign, X509_sign_ctx, +X509_REQ_sign, X509_REQ_sign_ctx, +X509_ACERT_sign, X509_ACERT_sign_ctx, +X509_CRL_sign, X509_CRL_sign_ctx \- +sign certificate, certificate request, or CRL signature +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md); +\& int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx); +\& +\& int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md); +\& int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx); +\& +\& int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md); +\& int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx); +\& +\& #include +\& +\& int X509_ACERT_sign(X509_ACERT *x, EVP_PKEY *pkey, const EVP_MD *md); +\& int X509_ACERT_sign_ctx(X509_ACERT *x, EVP_MD_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_sign()\fR signs certificate \fIx\fR using private key \fIpkey\fR and message +digest \fImd\fR and sets the signature in \fIx\fR. \fBX509_sign_ctx()\fR also signs +certificate \fIx\fR but uses the parameters contained in digest context \fIctx\fR. +If the certificate information includes X.509 extensions, +these two functions make sure that the certificate bears X.509 version 3. +.PP +\&\fBX509_REQ_sign()\fR, \fBX509_REQ_sign_ctx()\fR, +\&\fBX509_ACERT_sign()\fR, \fBX509_ACERT_sign_ctx()\fR, +\&\fBX509_CRL_sign()\fR, and \fBX509_CRL_sign_ctx()\fR +sign certificate requests and CRLs, respectively. +.SH NOTES +.IX Header "NOTES" +\&\fBX509_sign_ctx()\fR is used where the default parameters for the corresponding +public key and digest are not suitable. It can be used to sign keys using +RSA\-PSS for example. +.PP +For efficiency reasons and to work around ASN.1 encoding issues the encoding +of the signed portion of a certificate, certificate request and CRL is cached +internally. If the signed portion of the structure is modified the encoding +is not always updated meaning a stale version is sometimes used. This is not +normally a problem because modifying the signed portion will invalidate the +signature and signing will always update the encoding. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All functions return the size of the signature +in bytes for success and zero for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_verify_cert\fR\|(3), +\&\fBX509_verify\fR\|(3), +\&\fBX509_REQ_verify_ex\fR\|(3), \fBX509_REQ_verify\fR\|(3), +\&\fBX509_CRL_verify\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_sign()\fR, \fBX509_REQ_sign()\fR and \fBX509_CRL_sign()\fR functions are +available in all versions of OpenSSL. +.PP +The \fBX509_sign_ctx()\fR, \fBX509_REQ_sign_ctx()\fR +and \fBX509_CRL_sign_ctx()\fR functions were added in OpenSSL 1.0.1. +.PP +The \fBX509_ACERT_sign()\fR and \fBX509_ACERT_sign_ctx()\fR functions were added +in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_verify.3 b/static/netbsd/man3/X509_verify.3 new file mode 100644 index 00000000..136fc12a --- /dev/null +++ b/static/netbsd/man3/X509_verify.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: X509_verify.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_verify 3" +.TH X509_verify 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_verify, X509_self_signed, +X509_REQ_verify_ex, X509_REQ_verify, +X509_CRL_verify, X509_ACERT_verify \- +verify certificate, certificate request, or CRL signature +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509_verify(X509 *x, EVP_PKEY *pkey); +\& int X509_self_signed(X509 *cert, int verify_signature); +\& +\& int X509_REQ_verify_ex(X509_REQ *a, EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r); +\& int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r); +\& +\& #include +\& int X509_ACERT_verify(X509_CRL *a, EVP_PKEY *r); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_verify()\fR verifies the signature of certificate \fIx\fR using public key +\&\fIpkey\fR. Only the signature is checked: no other checks (such as certificate +chain validity) are performed. +.PP +\&\fBX509_self_signed()\fR checks whether certificate \fIcert\fR is self\-signed. +For success the issuer and subject names must match, the components of the +authority key identifier (if present) must match the subject key identifier etc. +The signature itself is actually verified only if \fBverify_signature\fR is 1, as +for explicitly trusted certificates this verification is not worth the effort. +.PP +\&\fBX509_REQ_verify_ex()\fR, \fBX509_REQ_verify()\fR, \fBX509_CRL_verify()\fR and \fBX509_ACERT_verify()\fR +verify the signatures of certificate requests, CRLs and attribute certificates +respectively. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_verify()\fR, +\&\fBX509_REQ_verify_ex()\fR, \fBX509_REQ_verify()\fR and \fBX509_CRL_verify()\fR +return 1 if the signature is valid and 0 if the signature check fails. +If the signature could not be checked at all because it was ill\-formed, +the certificate or the request was not complete or some other error occurred +then \-1 is returned. +.PP +\&\fBX509_self_signed()\fR returns the same values but also returns 1 +if all respective fields match and \fBverify_signature\fR is 0. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3), +\&\fBOSSL_LIB_CTX\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBX509_verify()\fR, \fBX509_REQ_verify()\fR, and \fBX509_CRL_verify()\fR +functions are available in all versions of OpenSSL. +.PP +\&\fBX509_REQ_verify_ex()\fR, and \fBX509_self_signed()\fR were added in OpenSSL 3.0. +.PP +\&\fBX509_ACERT_verify()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509_verify_cert.3 b/static/netbsd/man3/X509_verify_cert.3 new file mode 100644 index 00000000..8480b6c6 --- /dev/null +++ b/static/netbsd/man3/X509_verify_cert.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: X509_verify_cert.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509_verify_cert 3" +.TH X509_verify_cert 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509_build_chain, +X509_verify_cert, +X509_STORE_CTX_verify \- build and verify X509 certificate chain +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs, +\& X509_STORE *store, int with_self_signed, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int X509_verify_cert(X509_STORE_CTX *ctx); +\& int X509_STORE_CTX_verify(X509_STORE_CTX *ctx); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509_build_chain()\fR builds a certificate chain starting from \fItarget\fR +using the optional list of intermediate CA certificates \fIcerts\fR. +If \fIstore\fR is NULL it builds the chain as far down as possible, ignoring errors. +Else the chain must reach a trust anchor contained in \fIstore\fR. +It internally uses a \fBX509_STORE_CTX\fR structure associated with the library +context \fIlibctx\fR and property query string \fIpropq\fR, both of which may be NULL. +In case there is more than one possibility for the chain, only one is taken. +.PP +On success it returns a pointer to a new stack of (up_ref\*(Aqed) certificates +starting with \fItarget\fR and followed by all available intermediate certificates. +A self\-signed trust anchor is included only if \fItarget\fR is the trust anchor +of \fIwith_self_signed\fR is 1. +If a non\-NULL stack is returned the caller is responsible for freeing it. +.PP +The \fBX509_verify_cert()\fR function attempts to discover and validate a +certificate chain based on parameters in \fIctx\fR. +The verification context, of type \fBX509_STORE_CTX\fR, can be constructed +using \fBX509_STORE_CTX_new\fR\|(3) and \fBX509_STORE_CTX_init\fR\|(3). +It usually includes a target certificate to be verified, +a set of certificates serving as trust anchors, +a list of non\-trusted certificates that may be helpful for chain construction, +flags such as X509_V_FLAG_X509_STRICT, and various other optional components +such as a callback function that allows customizing the verification outcome. +A complete description of the certificate verification process is contained in +the \fBopenssl\-verification\-options\fR\|(1) manual page. +.PP +Applications rarely call this function directly but it is used by +OpenSSL internally for certificate validation, in both the S/MIME and +SSL/TLS code. +.PP +A negative return value from \fBX509_verify_cert()\fR can occur if it is invoked +incorrectly, such as with no certificate set in \fIctx\fR, or when it is called +twice in succession without reinitialising \fIctx\fR for the second call. +A negative return value can also happen due to internal resource problems +or because an internal inconsistency has been detected. +Applications must interpret any return value <= 0 as an error. +.PP +The \fBX509_STORE_CTX_verify()\fR behaves like \fBX509_verify_cert()\fR except that its +target certificate is the first element of the list of untrusted certificates +in \fIctx\fR unless a target certificate is set explicitly. +.PP +When the verification target is a raw public key, rather than a certificate, +both functions validate the target raw public key. +In that case the number of possible checks is significantly reduced. +The raw public key can be authenticated only via DANE TLSA records, either +locally synthesised or obtained by the application from DNS. +Raw public key DANE TLSA records may be added via \fBSSL_add_expected_rpk\fR\|(3) or +\&\fBSSL_dane_tlsa_add\fR\|(3). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509_build_chain()\fR returns NULL on error, else a stack of certificates. +.PP +Both \fBX509_verify_cert()\fR and \fBX509_STORE_CTX_verify()\fR +return 1 if a complete chain can be built and validated, +otherwise they return 0, and in exceptional circumstances (such as malloc +failure and internal errors) they can also return a negative code. +.PP +If a complete chain can be built and validated both functions return 1. +If the certificate must be rejected on the basis of the data available +or any required certificate status data is not available they return 0. +If no definite answer possible they usually return a negative code. +.PP +On error or failure additional error information can be obtained by +examining \fIctx\fR using, for example, \fBX509_STORE_CTX_get_error\fR\|(3). Even if +verification indicated success, the stored error code may be different from +X509_V_OK, likely because a verification callback function has waived the error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_add_expected_rpk\fR\|(3), +\&\fBSSL_CTX_dane_enable\fR\|(3), +\&\fBSSL_dane_tlsa_add\fR\|(3), +\&\fBX509_STORE_CTX_new\fR\|(3), +\&\fBX509_STORE_CTX_init\fR\|(3), +\&\fBX509_STORE_CTX_init_rpk\fR\|(3), +\&\fBX509_STORE_CTX_get_error\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509_build_chain()\fR and \fBX509_STORE_CTX_verify()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2009\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/X509v3_get_ext_by_NID.3 b/static/netbsd/man3/X509v3_get_ext_by_NID.3 new file mode 100644 index 00000000..1425281c --- /dev/null +++ b/static/netbsd/man3/X509v3_get_ext_by_NID.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: X509v3_get_ext_by_NID.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "X509v3_get_ext_by_NID 3" +.TH X509v3_get_ext_by_NID 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID, +X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext, +X509v3_add_ext, X509v3_add_extensions, X509_get_ext_count, X509_get_ext, +X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical, +X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext, +X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical, +X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count, +X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ, +X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext, +X509_REVOKED_add_ext \- extension stack utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x); +\& X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc); +\& +\& int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, +\& int nid, int lastpos); +\& int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x, +\& const ASN1_OBJECT *obj, int lastpos); +\& int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x, +\& int crit, int lastpos); +\& X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc); +\& STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x, +\& X509_EXTENSION *ex, int loc); +\& STACK_OF(X509_EXTENSION) +\& *X509v3_add_extensions(STACK_OF(X509_EXTENSION) **target, +\& const STACK_OF(X509_EXTENSION) *exts); +\& +\& int X509_get_ext_count(const X509 *x); +\& X509_EXTENSION *X509_get_ext(const X509 *x, int loc); +\& int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos); +\& int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos); +\& int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos); +\& X509_EXTENSION *X509_delete_ext(X509 *x, int loc); +\& int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc); +\& +\& int X509_CRL_get_ext_count(const X509_CRL *x); +\& X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc); +\& int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos); +\& int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, +\& int lastpos); +\& int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos); +\& X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc); +\& int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc); +\& +\& int X509_REVOKED_get_ext_count(const X509_REVOKED *x); +\& X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc); +\& int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos); +\& int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj, +\& int lastpos); +\& int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos); +\& X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc); +\& int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBX509v3_get_ext_count()\fR retrieves the number of extensions in \fIx\fR. +.PP +\&\fBX509v3_get_ext()\fR retrieves extension \fIloc\fR from \fIx\fR. The index \fIloc\fR +can take any value from 0 to X509_get_ext_count(\fIx\fR) \- 1. The returned +extension is an internal pointer which \fBMUST NOT\fR be freed by the +application. +.PP +\&\fBX509v3_get_ext_by_NID()\fR and \fBX509v3_get_ext_by_OBJ()\fR look for an extension +with \fInid\fR or \fIobj\fR from extension STACK \fIx\fR. The search starts from the +extension after \fIlastpos\fR or from the beginning if \fIlastpos\fR is \-1. If +the extension is found, its index is returned, otherwise \-1 is returned. +.PP +\&\fBX509v3_get_ext_by_critical()\fR is similar to \fBX509v3_get_ext_by_NID()\fR except it +looks for an extension of criticality \fIcrit\fR. A zero value for \fIcrit\fR +looks for a non\-critical extension. A nonzero value looks for a critical +extension. +.PP +\&\fBX509v3_delete_ext()\fR deletes the extension with index \fIloc\fR from \fIx\fR. +The deleted extension is returned and must be freed by the caller. +If \fIloc\fR is an invalid index value, NULL is returned. +.PP +\&\fBX509v3_add_ext()\fR inserts extension \fIex\fR to STACK \fI*x\fR at position \fIloc\fR. +If \fIloc\fR is \-1, the new extension is added to the end. +A new STACK is allocated if \fI*x\fR is NULL. +The passed extension \fIex\fR is duplicated so it must be freed after use. +.PP +\&\fBX509v3_add_extensions()\fR adds the list of extensions \fIexts\fR to STACK \fI*target\fR. +The STACK \fI*target\fR is returned unchanged if \fIexts\fR is NULL or an empty list. +Otherwise a new stack is allocated if \fI*target\fR is NULL. +An extension to be added +that has the same OID as a pre\-existing one replaces this earlier one. +.PP +\&\fBX509_get_ext_count()\fR, \fBX509_get_ext()\fR, \fBX509_get_ext_by_NID()\fR, +\&\fBX509_get_ext_by_OBJ()\fR, \fBX509_get_ext_by_critical()\fR, \fBX509_delete_ext()\fR +and \fBX509_add_ext()\fR operate on the extensions of certificate \fIx\fR. They are +otherwise identical to the X509v3 functions. +.PP +\&\fBX509_CRL_get_ext_count()\fR, \fBX509_CRL_get_ext()\fR, \fBX509_CRL_get_ext_by_NID()\fR, +\&\fBX509_CRL_get_ext_by_OBJ()\fR, \fBX509_CRL_get_ext_by_critical()\fR, +\&\fBX509_CRL_delete_ext()\fR and \fBX509_CRL_add_ext()\fR operate on the extensions of +CRL \fIx\fR. They are otherwise identical to the X509v3 functions. +.PP +\&\fBX509_REVOKED_get_ext_count()\fR, \fBX509_REVOKED_get_ext()\fR, +\&\fBX509_REVOKED_get_ext_by_NID()\fR, \fBX509_REVOKED_get_ext_by_OBJ()\fR, +\&\fBX509_REVOKED_get_ext_by_critical()\fR, \fBX509_REVOKED_delete_ext()\fR and +\&\fBX509_REVOKED_add_ext()\fR operate on the extensions of CRL entry \fIx\fR. +They are otherwise identical to the X509v3 functions. +.SH NOTES +.IX Header "NOTES" +These functions are used to examine stacks of extensions directly. +Applications that want to parse or encode and add an extension should +use the extension encode and decode functions instead, such as +\&\fBX509_add1_ext_i2d()\fR and \fBX509_get_ext_d2i()\fR. +.PP +For \fBX509v3_get_ext_by_NID()\fR, \fBX509v3_get_ext_by_OBJ()\fR, +\&\fBX509v3_get_ext_by_critical()\fR and its variants, a zero index return value +is not an error since extension STACK \fIx\fR indices start from zero. +These search functions start from the extension \fBafter\fR the \fIlastpos\fR parameter +so it should initially be set to \-1. If it is set to zero, the initial extension +will not be checked. +.PP +\&\fBX509v3_delete_ext()\fR and its variants are a bit counter\-intuitive +because these functions do not free the extension they delete. +They return an \fBX509_EXTENSION\fR object which must be explicitly freed +using \fBX509_EXTENSION_free()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBX509v3_get_ext_count()\fR returns the extension count or 0 for failure. +.PP +\&\fBX509v3_get_ext()\fR, \fBX509v3_delete_ext()\fR and \fBX509_delete_ext()\fR return an +\&\fBX509_EXTENSION\fR structure or NULL if an error occurs. +.PP +\&\fBX509v3_get_ext_by_OBJ()\fR and \fBX509v3_get_ext_by_critical()\fR return +the extension index or \-1 if an error occurs. +.PP +\&\fBX509v3_get_ext_by_NID()\fR returns the extension index or negative values if an +error occurs. +.PP +\&\fBX509v3_add_ext()\fR returns a STACK of extensions or NULL on error. +.PP +\&\fBX509v3_add_extensions()\fR returns a STACK of extensions +or NULL on error or if \fI*target\fR is NULL and \fIexts\fR is NULL or an empty list. +.PP +\&\fBX509_add_ext()\fR returns 1 on success and 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBX509V3_get_d2i\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBX509v3_add_extensions()\fR was added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/__builtin_object_size.3 b/static/netbsd/man3/__builtin_object_size.3 new file mode 100644 index 00000000..9daa68a4 --- /dev/null +++ b/static/netbsd/man3/__builtin_object_size.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: __builtin_object_size.3,v 1.11 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd July 18, 2012 +.Dt __BUILTIN_OBJECT_SIZE 3 +.Os +.Sh NAME +.Nm __builtin_object_size +.Nd return the size of the given object +.Sh SYNOPSIS +.Ft size_t +.Fn __builtin_object_size "void *ptr" "int type" +.Sh DESCRIPTION +The +.Fn __builtin_object_size +function is a +.Xr gcc 1 +built-in function that returns the size of the +.Fa ptr +object if known at compile time and the object does not have any side +effects. +.Sh RETURN VALUES +If the size of the object is not known or it has side effects the +.Fn __builtin_object_size +function returns: +.Bl -tag -width (size_t)\-1 -offset indent +.It Dv (size_t)\-1 +for +.Fa type +.Dv 0 +and +.Dv 1 . +.It Dv (size_t)0 +for +.Fa type +.Dv 2 +and +.Dv 3 . +.El +.Pp +If the size of the object is known, then the +.Fn __builtin_object_size +function returns the maximum size of all the objects that the compiler +knows that they can be pointed to by +.Fa ptr +when +.Fa type +.Dv & 2 == 0 , +and the minimum size when +.Fa type +.Dv & 2 != 0 . +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __builtin_return_address 3 , +.Xr attribute 3 , +.Xr ssp 3 +.Sh HISTORY +The +.Fn __builtin_object_size +appeared in +.Tn GCC 4.1 . +.Sh CAVEATS +This is a non-standard, compiler-specific extension. +.Pp +Note that currently the object size calculation pass is only done at -O1 +or above, meaning that this function always returns \-1 when the optimizer +is off. +.Pp +There are some discussions about always doing the object size pass, but +the issue is that without the optimization pass data sizes are not going +to be correct. +.Pp +For that reason currently code fortification (size-checked replacement +functions) is disabled when optimization is off. diff --git a/static/netbsd/man3/_lwp_makecontext.3 b/static/netbsd/man3/_lwp_makecontext.3 new file mode 100644 index 00000000..9994c98d --- /dev/null +++ b/static/netbsd/man3/_lwp_makecontext.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: _lwp_makecontext.3,v 1.4 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 16, 2003 +.Dt _LWP_MAKECONTEXT 3 +.Os +.Sh NAME +.Nm _lwp_makecontext +.Nd create a new initial light-weight process execution context +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In lwp.h +.Ft void +.Fn _lwp_makecontext "ucontext_t *context" "void (*start_routine)(void *)" \ + "void *arg" "void *private" "caddr_t stack_base" "size_t stack_size" +.Sh DESCRIPTION +.Fn _lwp_makecontext +initializes the context structure pointed to by +.Fa context +in a manner suitable for using with +.Xr _lwp_create 2 . +The LWP will begin execution at the function specified by +.Fa start_routine +which will be passed a single argument +.Fa arg . +The LWP private data pointer will be set to +.Fa private . +The stack region for the new LWP is specified by the +.Fa stack_base +and +.Fa stack_size +arguments. +.Pp +The signal mask in the context structure is not initialized by +.Fn _lwp_makecontext . +.Sh SEE ALSO +.Xr _lwp_create 2 , +.Xr _lwp_getprivate 2 +.Sh HISTORY +The +.Fn _lwp_create +system call first appeared in +.Nx 2.0 . +.Sh BUGS +The LWP private data pointer is not initialized by the current +implementation of +.Fn _lwp_makecontext . diff --git a/static/netbsd/man3/a64l.3 b/static/netbsd/man3/a64l.3 new file mode 100644 index 00000000..7f008027 --- /dev/null +++ b/static/netbsd/man3/a64l.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: a64l.3,v 1.10 2010/05/06 18:55:34 jruoho Exp $ +.\" +.\" Copyright (c) 1998, 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 6, 2010 +.Dt A64L 3 +.Os +.Sh NAME +.Nm a64l , +.Nm l64a , +.Nm l64a_r +.Nd "convert between a long integer and a base-64 ASCII string" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft long +.Fn a64l "const char *s" +.Ft char * +.Fn l64a "long int l" +.Ft int +.Fn l64a_r "long int l" "char *buffer" "int buflen" +.Sh DESCRIPTION +The +.Fn a64l +and +.Fn l64a +functions convert between a long integer and its base-64 ASCII string +representation. +.Pp +The characters used to represent ``digits'' are +`.' for 0, +`/' for 1, +`0' - `9' for 2 - 11, +`A' - `Z' for 12 - 37, and +`a' - `z' for 38 - 63. +.Pp +.Fn a64l +takes a pointer to a NUL-terminated base-64 ASCII string +representation, +.Fa s , +and returns the corresponding long integer value. +.Pp +.Fn l64a +takes a long integer value, +.Fa l , +and returns a pointer to the corresponding NUL-terminated base-64 +ASCII string representation. +.Pp +.Fn l64a_r +performs a conversion identical to that of +.Fn l64a +and stores the resulting representation in the memory area pointed to by +.Fa buffer , +consuming at most +.Fa buflen +characters including the terminating NUL character. +.Sh RETURN VALUES +On successful completion, +.Fn a64l +returns the long integer value corresponding to the input string. +If the string pointed to by +.Fa s +is an empty string, +.Fn a64l +returns a value of 0L. +.Pp +.Fn l64a +returns a pointer to the base-64 ASCII string representation corresponding to +the input value. +If +.Fa l +is 0L, +.Fn l64a +returns a pointer to an empty string. +.Pp +On successful completion, +.Fn l64a_r +returns 0; if +.Fa buffer +is of insufficient length, -1 is returned. +.Sh SEE ALSO +.Xr strtol 3 +.Sh STANDARDS +The +.Fn a64l +and +.Fn l64a +functions conform to +.St -xpg4.2 +and +.St -p1003.1-2004 . +The +.Fn l64a_r +function conforms to +.St -svid4 , +Multithreading Extension. +.Sh BUGS +The +.Fn l64a +function is not reentrant. +The value returned by it points into a static buffer area; +subsequent calls to +.Fn la64a +may overwrite this buffer. +In multi-threaded applications, +.Fn l64a_r +should be used instead. diff --git a/static/netbsd/man3/abort.3 b/static/netbsd/man3/abort.3 new file mode 100644 index 00000000..c75aeb6c --- /dev/null +++ b/static/netbsd/man3/abort.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: abort.3,v 1.13 2012/06/12 21:16:17 jdf Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)abort.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd August 11, 2002 +.Dt ABORT 3 +.Os +.Sh NAME +.Nm abort +.Nd cause abnormal program termination +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn abort void +.Sh DESCRIPTION +The +.Fn abort +function causes abnormal program termination to occur, unless the +signal +.Dv SIGABRT +is being caught and the signal handler does not return. +.Pp +Calling the +.Fn abort +function results in temporary files being removed. +Any open streams are flushed and closed. +.Sh RETURN VALUES +The +.Fn abort +function +never returns. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr exit 3 +.Sh STANDARDS +The +.Fn abort +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/abs.3 b/static/netbsd/man3/abs.3 new file mode 100644 index 00000000..e3cb9e12 --- /dev/null +++ b/static/netbsd/man3/abs.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: abs.3,v 1.14 2011/04/13 06:56:50 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)abs.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 13, 2011 +.Dt ABS 3 +.Os +.Sh NAME +.Nm abs , +.Nm labs , +.Nm llabs , +.Nm imaxabs +.Nd functions for integer absolute value +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn abs "int x" +.Ft long int +.Fn labs "long int x" +.Ft long long int +.Fn llabs "long long int x" +.In inttypes.h +.Ft intmax_t +.Fn imaxabs "intmax_t x" +.Sh DESCRIPTION +These functions return the absolute value of the integer +.Fa x . +The listed functions differ only with respect +to the type of the return value and +.Fa x . +.Sh SEE ALSO +.Xr cabs 3 , +.Xr fabs 3 , +.Xr floor 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . +.Sh BUGS +The absolute value of the most negative integer remains negative. diff --git a/static/netbsd/man3/acl.3 b/static/netbsd/man3/acl.3 new file mode 100644 index 00000000..a5c1002b --- /dev/null +++ b/static/netbsd/man3/acl.3 @@ -0,0 +1,307 @@ +.\" $NetBSD: acl.3,v 1.3 2022/01/17 17:56:48 christos Exp $ +.\"- +.\" Copyright (c) 2000, 2001, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl.3 296196 2016-02-29 16:52:06Z trasz $ +.\" +.Dd January 17, 2022 +.Dt ACL 3 +.Os +.Sh NAME +.Nm acl +.Nd introduction to the POSIX.1e/NFSv4 ACL security API +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Sh DESCRIPTION +.Fx +permits file systems to export Access Control Lists via the VFS, and +provides a library for userland access to and manipulation of these ACLs. +.Fx +supports POSIX.1e and NFSv4 ACLs, but +not all file systems provide support for ACLs, and some may require that +ACL support be explicitly enabled by the administrator. +The library calls include routines to allocate, duplicate, retrieve, set, +and validate ACLs associated with file objects. +As well as the POSIX.1e routines, there are a number of non-portable +extensions defined that allow for ACL semantics alternative to +POSIX.1e, such as NFSv4. +Where routines are non-standard, they are suffixed with _np to indicate that +they are not portable. +.Pp +POSIX.1e describes a set of ACL manipulation routines to manage the +contents of ACLs, as well as their relationships with files; almost +all of these support routines are implemented in +.Fx . +.Pp +Available functions, sorted by behavior, include: +.Bl -tag -width indent +.It Fn acl_add_flag_np +This function is described in +.Xr acl_add_flag_np 3 , +and may be used to add flags to a flagset. +.It Fn acl_add_perm +This function is described in +.Xr acl_add_perm 3 , +and may be used to add permissions to a permission set. +.It Fn acl_calc_mask +This function is described in +.Xr acl_calc_mask 3 , +and may be used to calculate and set the permissions associated with +the +.Dv ACL_MASK +entry. +.It Fn acl_clear_flags_np +This function is described in +.Xr acl_clear_flags_np 3 , +and may be used to clear all flags from a flagset. +.It Fn acl_clear_perms +This function is described in +.Xr acl_clear_perms 3 , +and may be used to clear all permissions from a permission set. +.It Fn acl_copy_entry +This function is described in +.Xr acl_copy_entry 3 , +and may be used to copy the contents of an ACL entry. +.It Xo +.Fn acl_create_entry , +.Fn acl_create_entry_np +.Xc +These functions are described in +.Xr acl_create_entry 3 , +and may be used to create an empty entry in an ACL. +.It Xo +.Fn acl_delete_def_file , +.Fn acl_delete_def_link_np , +.Fn acl_delete_fd_np , +.Fn acl_delete_file_np , +.Fn acl_delete_link_np +.Xc +These functions are described in +.Xr acl_delete 3 , +and may be used to delete ACLs from file system objects. +.It Xo +.Fn acl_delete_entry , +.Fn acl_delete_entry_np , +.Xc +This functions are described in +.Xr acl_delete_entry 3 , +and may be used to delete an entry from an ACL. +.It Fn acl_delete_flag_np +This function is described in +.Xr acl_delete_flag_np 3 , +and may be used to delete flags from a flagset. +.It Fn acl_delete_perm +This function is described in +.Xr acl_delete_perm 3 , +and may be used to delete permissions from a permset. +.It Fn acl_dup +This function is described in +.Xr acl_dup 3 , +and may be used to duplicate an ACL structure. +.It Fn acl_free +This function is described in +.Xr acl_free 3 , +and may be used to free userland working ACL storage. +.It Fn acl_from_text +This function is described in +.Xr acl_from_text 3 , +and may be used to convert a text-form ACL into working ACL state, if +the ACL has POSIX.1e or NFSv4 semantics. +.It Fn acl_get_brand_np +This function is described in +.Xr acl_get_brand_np 3 +and may be used to determine whether the ACL has POSIX.1e or NFSv4 semantics. +.It Fn acl_get_entry +This function is described in +.Xr acl_get_entry 3 , +and may be used to retrieve a designated ACL entry from an ACL. +.It Xo +.Fn acl_get_fd , +.Fn acl_get_fd_np , +.Fn acl_get_file , +.Fn acl_get_link_np +.Xc +These functions are described in +.Xr acl_get 3 , +and may be used to retrieve ACLs from file system objects. +.It Fn acl_get_entry_type_np +This function is described in +.Xr acl_get_entry_type_np 3 , +and may be used to retrieve an ACL type from an ACL entry. +.It Fn acl_get_flagset_np +This function is described in +.Xr acl_get_flagset_np 3 , +and may be used to retrieve a flagset from an ACL entry. +.It Fn acl_get_permset +This function is described in +.Xr acl_get_permset 3 , +and may be used to retrieve a permset from an ACL entry. +.It Fn acl_get_qualifier +This function is described in +.Xr acl_get_qualifier 3 , +and may be used to retrieve the qualifier from an ACL entry. +.It Fn acl_get_tag_type +This function is described in +.Xr acl_get_tag_type 3 , +and may be used to retrieve the tag type from an ACL entry. +.It Fn acl_init +This function is described in +.Xr acl_init 3 , +and may be used to allocate a fresh (empty) ACL structure. +.It Fn acl_is_trivial_np +This function is described in +.Xr acl_is_trivial_np 3 , +and may be used to find out whether ACL is trivial. +.It Xo +.Fn acl_set_fd , +.Fn acl_set_fd_np , +.Fn acl_set_file , +.Fn acl_set_link_np +.Xc +These functions are described in +.Xr acl_set 3 , +and may be used to assign an ACL to a file system object. +.It Fn acl_set_entry_type_np +This function is described in +.Xr acl_set_entry_type_np 3 , +and may be used to set the ACL type of an ACL entry. +.It Fn acl_set_flagset_np +This function is described in +.Xr acl_set_flagset_np 3 , +and may be used to set the flags of an ACL entry from a flagset. +.It Fn acl_set_permset +This function is described in +.Xr acl_set_permset 3 , +and may be used to set the permissions of an ACL entry from a permset. +.It Fn acl_set_qualifier +This function is described in +.Xr acl_set_qualifier 3 , +and may be used to set the qualifier of an ACL. +.It Fn acl_set_tag_type +This function is described in +.Xr acl_set_tag_type 3 , +and may be used to set the tag type of an ACL. +.It Fn acl_strip_np +This function is described in +.Xr acl_strip_np 3 , +and may be used to remove extended entries from an ACL. +.It Xo +.Fn acl_to_text , +.Fn acl_to_text_np +.Xc +These functions are described in +.Xr acl_to_text 3 , +and may be used to generate a text-form of a POSIX.1e or NFSv4 semantics ACL. +.It Xo +.Fn acl_valid , +.Fn acl_valid_fd_np , +.Fn acl_valid_file_np , +.Fn acl_valid_link_np +.Xc +These functions are described in +.Xr acl_valid 3 , +and may be used to validate an ACL as correct POSIX.1e-semantics, or +as appropriate for a particular file system object regardless of semantics. +.El +.Pp +Documentation of the internal kernel interfaces backing these calls may +be found in +.Xr acl 9 . +The syscalls between the internal interfaces and the public library +routines may change over time, and as such are not documented. +They are not intended to be called directly without going through the +library. +.Sh SEE ALSO +.Xr getfacl 1 , +.Xr setfacl 1 , +.Xr acl_add_flag_np 3 , +.Xr acl_add_perm 3 , +.Xr acl_calc_mask 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_clear_perms 3 , +.Xr acl_copy_entry 3 , +.Xr acl_create_entry 3 , +.Xr acl_delete_entry 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_delete_perm 3 , +.Xr acl_dup 3 , +.Xr acl_free 3 , +.Xr acl_from_text 3 , +.Xr acl_get 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_get_entry_type_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr acl_get_permset 3 , +.Xr acl_get_qualifier 3 , +.Xr acl_get_tag_type 3 , +.Xr acl_init 3 , +.Xr acl_is_trivial_np 3 , +.Xr acl_set 3 , +.Xr acl_set_entry_type_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr acl_set_permset 3 , +.Xr acl_set_qualifier 3 , +.Xr acl_set_tag_type 3 , +.Xr acl_strip_np 3 , +.Xr acl_to_text 3 , +.Xr acl_valid 3 , +.Xr posix1e 3 , +.Xr acl 9 +.Sh STANDARDS +POSIX.1e assigns security labels to all objects, extending the security +functionality described in POSIX.1. +These additional labels provide fine-grained discretionary access control, +fine-grained capabilities, and labels necessary for mandatory access +control. +POSIX.2c describes a set of userland utilities for manipulating these +labels. +.Pp +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e +implementation mailing list. +To join this list, see the +.Fx +POSIX.1e implementation page for more information. +.Sh HISTORY +Both NFSv4 and POSIX.1e ACL support were introduced in +.Nx 10.0 . +Support was ported from +.Fx +and is based on extended attributes +for the UFS and UFS2 file systems. +.Pp +The +.Xr getfacl 1 +and +.Xr setfacl 1 +utilities describe the user tools that permit direct manipulation of complete +file ACLs. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_add_flag_np.3 b/static/netbsd/man3/acl_add_flag_np.3 new file mode 100644 index 00000000..b1b94659 --- /dev/null +++ b/static/netbsd/man3/acl_add_flag_np.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: acl_add_flag_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_add_flag_np.3 287445 2015-09-04 00:14:20Z delphij $ +.\" +.Dd September 4, 2015 +.Dt ACL_ADD_FLAG_NP 3 +.Os +.Sh NAME +.Nm acl_add_flag_np +.Nd add flags to a flagset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_add_flag_np "acl_flagset_t flagset_d" "acl_flag_t flag" +.Sh DESCRIPTION +The +.Fn acl_add_flag_np +function +is a non-portable call that adds the NFSv4 ACL flags contained in +.Fa flags +to the flagset +.Fa flagset_d . +.Pp +Note: it is not considered an error to attempt to add flags +that already exist in the flagset. +.Pp +Valid values are: +.Bl -column -offset 3n "ACL_ENTRY_NO_PROPAGATE_INHERIT" +.It ACL_ENTRY_FILE_INHERIT Ta "Will be inherited by files." +.It ACL_ENTRY_DIRECTORY_INHERIT Ta "Will be inherited by directories." +.It ACL_ENTRY_NO_PROPAGATE_INHERIT Ta "Will not propagate." +.It ACL_ENTRY_INHERIT_ONLY Ta "Inherit-only." +.It ACL_ENTRY_INHERITED Ta "Inherited from parent" +.El +.Sh RETURN VALUES +.Rv -std acl_add_flag_np +.Sh ERRORS +The +.Fn acl_add_flag_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa flagset_d +is not a valid descriptor for a flagset within an ACL entry. +Argument +.Fa flag +does not contain a valid +.Vt acl_flag_t +value. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_add_flag_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_add_flag_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_add_perm.3 b/static/netbsd/man3/acl_add_perm.3 new file mode 100644 index 00000000..953231ef --- /dev/null +++ b/static/netbsd/man3/acl_add_perm.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: acl_add_perm.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_add_perm.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_ADD_PERM 3 +.Os +.Sh NAME +.Nm acl_add_perm +.Nd add permissions to a permission set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_add_perm "acl_permset_t permset_d" "acl_perm_t perm" +.Sh DESCRIPTION +The +.Fn acl_add_perm +function +is a POSIX.1e call that adds the permission contained in +.Fa perm +to the permission set +.Fa permset_d . +.Pp +Note: it is not considered an error to attempt to add permissions +that already exist in the permission set. +.Pp +For POSIX.1e ACLs, valid values are: +.Bl -column -offset 3n "ACL_WRITE_NAMED_ATTRS" +.It ACL_EXECUTE Execute permission +.It ACL_WRITE Write permission +.It ACL_READ Read permission +.El +.Pp +For NFSv4 ACLs, valid values are: +.Bl -column -offset 3n "ACL_WRITE_NAMED_ATTRS" +.It ACL_READ_DATA Ta "Read permission" +.It ACL_LIST_DIRECTORY Ta "Same as ACL_READ_DATA" +.It ACL_WRITE_DATA Ta "Write permission, or permission to create files" +.It ACL_ADD_FILE Ta "Same as ACL_READ_DATA" +.It ACL_APPEND_DATA Ta "Permission to create directories. Ignored for files" +.It ACL_ADD_SUBDIRECTORY Ta "Same as ACL_APPEND_DATA" +.It ACL_READ_NAMED_ATTRS Ta "Ignored" +.It ACL_WRITE_NAMED_ATTRS Ta "Ignored" +.It ACL_EXECUTE Ta "Execute permission" +.It ACL_DELETE_CHILD Ta "Permission to delete files and subdirectories" +.It ACL_READ_ATTRIBUTES Ta "Permission to read basic attributes" +.It ACL_WRITE_ATTRIBUTES Ta "Permission to change basic attributes" +.It ACL_DELETE Ta "Permission to delete the object this ACL is placed on" +.It ACL_READ_ACL Ta "Permission to read ACL" +.It ACL_WRITE_ACL Ta "Permission to change the ACL and file mode" +.It ACL_SYNCHRONIZE Ta "Ignored" +.El +.Pp +Calling +.Fn acl_add_perm +with +.Fa perm +equal to ACL_WRITE or ACL_READ brands the ACL as POSIX. +Calling it with ACL_READ_DATA, ACL_LIST_DIRECTORY, ACL_WRITE_DATA, +ACL_ADD_FILE, ACL_APPEND_DATA, ACL_ADD_SUBDIRECTORY, ACL_READ_NAMED_ATTRS, +ACL_WRITE_NAMED_ATTRS, ACL_DELETE_CHILD, ACL_READ_ATTRIBUTES, +ACL_WRITE_ATTRIBUTES, ACL_DELETE, ACL_READ_ACL, ACL_WRITE_ACL +or ACL_SYNCHRONIZE brands the ACL as NFSv4. +.Sh RETURN VALUES +.Rv -std acl_add_perm +.Sh ERRORS +The +.Fn acl_add_perm +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa permset_d +is not a valid descriptor for a permission set within an ACL entry. +Argument +.Fa perm +does not contain a valid +.Vt acl_perm_t +value. +ACL is already branded differently. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_clear_perms 3 , +.Xr acl_delete_perm 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_get_permset 3 , +.Xr acl_set_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_add_perm +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_add_perm +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_calc_mask.3 b/static/netbsd/man3/acl_calc_mask.3 new file mode 100644 index 00000000..0db9a1a0 --- /dev/null +++ b/static/netbsd/man3/acl_calc_mask.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: acl_calc_mask.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_calc_mask.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_CALC_MASK 3 +.Os +.Sh NAME +.Nm acl_calc_mask +.Nd calculate and set ACL mask permissions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_calc_mask "acl_t *acl_p" +.Sh DESCRIPTION +The +.Fn acl_calc_mask +function +is a POSIX.1e call that calculates and set the permissions +associated with the +.Dv ACL_MASK +ACL entry of the ACL referred to by +.Fa acl_p . +.Pp +The value of new permissions are the union of the permissions +granted by the +.Dv ACL_GROUP , ACL_GROUP_OBJ , ACL_USER +tag types which +match processes in the file group class contained in the ACL +referred to by +.Fa acl_p . +.Pp +If the ACL referred to by +.Fa acl_p +already contains an +.Dv ACL_MASK +entry, its permissions shall be +overwritten; if it does not contain an +.Dv ACL_MASK +entry, one shall +be added. +.Sh RETURN VALUES +.Rv -std acl_calc_mask +.Sh ERRORS +The +.Fn acl_calc_mask +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa acl_p +does not point to a pointer to a valid ACL. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get_entry 3 , +.Xr acl_valid 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_calc_mask +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_calc_mask +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_clear_flags_np.3 b/static/netbsd/man3/acl_clear_flags_np.3 new file mode 100644 index 00000000..abcdf1a3 --- /dev/null +++ b/static/netbsd/man3/acl_clear_flags_np.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: acl_clear_flags_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_clear_flags_np.3 273853 2014-10-30 10:49:50Z trasz $ +.\" +.Dd October 30, 2014 +.Dt ACL_CLEAR_FLAGS_NP 3 +.Os +.Sh NAME +.Nm acl_clear_flags_np +.Nd clear flags from a flagset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_clear_flags_np "acl_flagset_t flagset_d" +.Sh DESCRIPTION +The +.Fn acl_clear_flags_np +function +is a non-portable call that clears all NFSv4 ACL flags from flagset +.Fa flagset_d . +.Sh RETURN VALUES +.Rv -std acl_clear_flags_np +.Sh ERRORS +The +.Fn acl_clear_flags_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa flagset_d +is not a valid descriptor for a flagset. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_flag_np 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_clear_flags_np +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_clear_flags_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_clear_perms.3 b/static/netbsd/man3/acl_clear_perms.3 new file mode 100644 index 00000000..d1537e25 --- /dev/null +++ b/static/netbsd/man3/acl_clear_perms.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: acl_clear_perms.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_clear_perms.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_CLEAR_PERMS 3 +.Os +.Sh NAME +.Nm acl_clear_perms +.Nd clear permissions from a permission set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_clear_perms "acl_permset_t permset_d" +.Sh DESCRIPTION +The +.Fn acl_clear_perms +function +is a POSIX.1e call that clears all permissions from permissions set +.Fa permset_d . +.Sh RETURN VALUES +.Rv -std acl_clear_perms +.Sh ERRORS +The +.Fn acl_clear_perms +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa permset_d +is not a valid descriptor for a permission set. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_perm 3 , +.Xr acl_delete_perm 3 , +.Xr acl_get_permset 3 , +.Xr acl_set_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_clear_perms +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_clear_perms +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_copy_entry.3 b/static/netbsd/man3/acl_copy_entry.3 new file mode 100644 index 00000000..2cb96587 --- /dev/null +++ b/static/netbsd/man3/acl_copy_entry.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: acl_copy_entry.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_copy_entry.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_COPY_ENTRY 3 +.Os +.Sh NAME +.Nm acl_copy_entry +.Nd copy an ACL entry to another ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_copy_entry "acl_entry_t dest_d" "acl_entry_t src_d" +.Sh DESCRIPTION +The +.Fn acl_copy_entry +function +is a POSIX.1e call that copies the contents of ACL entry +.Fa src_d +to ACL entry +.Fa dest_d . +.Sh RETURN VALUES +.Rv -std acl_copy_entry +.Sh ERRORS +The +.Fn acl_copy_entry +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa src_d +or +.Fa dest_d +is not a valid descriptor for an ACL entry, or +arguments +.Fa src_d +and +.Fa dest_d +reference the same ACL entry. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get_entry 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_copy_entry +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_copy_entry +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_create_entry.3 b/static/netbsd/man3/acl_create_entry.3 new file mode 100644 index 00000000..bdd778a9 --- /dev/null +++ b/static/netbsd/man3/acl_create_entry.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: acl_create_entry.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_create_entry.3 318708 2017-05-23 07:11:15Z ngie $ +.\" +.Dd June 25, 2009 +.Dt ACL_CREATE_ENTRY 3 +.Os +.Sh NAME +.Nm acl_create_entry , +.Nm acl_create_entry_np +.Nd create a new ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_create_entry "acl_t *acl_p" "acl_entry_t *entry_p" +.Ft int +.Fn acl_create_entry_np "acl_t *acl_p" "acl_entry_t *entry_p" "int index" +.Sh DESCRIPTION +The +.Fn acl_create_entry +function +is a POSIX.1e call that creates a new ACL entry in the ACL +pointed to by +.Fa acl_p . +The +.Fn acl_create_entry_np +function is a non-portable version that creates the ACL entry +at position +.Fa index . +Positions are numbered starting from zero, i.e. calling +.Fn acl_create_entry_np +with +.Fa index +argument equal to zero will prepend the entry to the ACL. +.Sh RETURN VALUES +.Rv -std acl_create_entry +.Sh ERRORS +The +.Fn acl_create_entry +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa acl_p +does not point to a pointer to a valid ACL. +Argument +.Fa index +is out of bounds. +.It Bq Er ENOMEM +The ACL working storage requires more memory than is +allowed by the hardware or system-imposed memory +management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_delete_entry 3 , +.Xr acl_get_entry 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_create_entry +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_create_entry +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_delete.3 b/static/netbsd/man3/acl_delete.3 new file mode 100644 index 00000000..49f2abfb --- /dev/null +++ b/static/netbsd/man3/acl_delete.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: acl_delete.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_delete.3 131635 2004-07-05 17:12:53Z ru $ +.\" +.Dd December 29, 2002 +.Dt ACL_DELETE 3 +.Os +.Sh NAME +.Nm acl_delete_def_file , +.Nm acl_delete_def_link_np , +.Nm acl_delete_fd_np , +.Nm acl_delete_file_np , +.Nm acl_delete_link_np +.Nd delete an ACL from a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_delete_def_file "const char *path_p" +.Ft int +.Fn acl_delete_def_link_np "const char *path_p" +.Ft int +.Fn acl_delete_fd_np "int filedes" "acl_type_t type" +.Ft int +.Fn acl_delete_file_np "const char *path_p" "acl_type_t type" +.Ft int +.Fn acl_delete_link_np "const char *path_p" "acl_type_t type" +.Sh DESCRIPTION +The +.Fn acl_delete_def_file , +.Fn acl_delete_def_link_np , +.Fn acl_delete_fd_np , +.Fn acl_delete_file_np , +and +.Fn acl_delete_link_np +each allow the deletion of an ACL from a file. +The +.Fn acl_delete_def_file +function +is a POSIX.1e call that deletes the default ACL from a file (normally a +directory) by name; the remainder of the calls are non-portable extensions +that permit the deletion of arbitrary ACL types from a file/directory +either by path name or file descriptor. +The +.Fn _file +variations follow a symlink if it occurs in the last segment of the +path name; the +.Fn _link +variations operate on the symlink itself. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +If any of the following conditions occur, these functions shall return -1 +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, or the +object exists and the process does not have appropriate access rights. +.It Bq Er EBADF +The +.Va fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The ACL type passed is invalid for this file object. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an +entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named object does not exist, or the +.Va path_p +argument points to an empty string. +.It Bq Er ENOMEM +Insufficient memory available to fulfill request. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.Pp +Argument +.Va path_p +must be a directory, and is not. +.It Bq Er EOPNOTSUPP +The file system does not support ACL deletion. +.It Bq Er EPERM +The process does not have appropriate privilege to perform the operation +to delete an ACL. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get 3 , +.Xr acl_set 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_delete_entry.3 b/static/netbsd/man3/acl_delete_entry.3 new file mode 100644 index 00000000..2f830f08 --- /dev/null +++ b/static/netbsd/man3/acl_delete_entry.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: acl_delete_entry.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_delete_entry.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_DELETE_ENTRY 3 +.Os +.Sh NAME +.Nm acl_delete_entry , +.Nm acl_delete_entry_np +.Nd delete an ACL entry from an ACL +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_delete_entry "acl_t acl" "acl_entry_t entry_d" +.Ft int +.Fn acl_delete_entry_np "acl_t acl" "int index" +.Sh DESCRIPTION +The +.Fn acl_delete_entry +function +is a POSIX.1e call that removes the ACL entry +.Fa entry_d +from ACL +.Fa acl . +The +.Fn acl_delete_entry_np +function is a non-portable version that removes the ACL entry +at position +.Fa index +from ACL +.Fa acl . +Positions are numbered starting from zero, i.e. calling +.Fn acl_delete_entry_np +with +.Fa index +argument equal to zero will remove the first ACL entry. +.Sh RETURN VALUES +.Rv -std acl_delete_entry +.Sh ERRORS +The +.Fn acl_delete_entry +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa acl +does not point to a valid ACL. +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry in +.Fa acl . +Argument +.Fa index +is out of bounds. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_copy_entry 3 , +.Xr acl_get_entry 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_delete_entry +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_delete_entry +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_delete_flag_np.3 b/static/netbsd/man3/acl_delete_flag_np.3 new file mode 100644 index 00000000..e6ea8051 --- /dev/null +++ b/static/netbsd/man3/acl_delete_flag_np.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: acl_delete_flag_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_delete_flag_np.3 296196 2016-02-29 16:52:06Z trasz $ +.\" +.Dd October 30, 2014 +.Dt ACL_DELETE_FLAG_NP 3 +.Os +.Sh NAME +.Nm acl_delete_flag_np +.Nd delete flags from a flagset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_delete_flag_np "acl_flagset_t flagset_d" "acl_flag_t flag" +.Sh DESCRIPTION +The +.Fn acl_delete_flag_np +function +is a non-portable call that removes specific NFSv4 ACL flags from flagset +.Fa flags . +.Sh RETURN VALUES +.Rv -std acl_delete_flag_np +.Sh ERRORS +The +.Fn acl_delete_flag_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa flagset_d +is not a valid descriptor for a flagset. +Argument +.Fa flag +does not contain a valid +.Vt acl_flag_t +value. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_flag_np 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_delete_flag_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_delete_flag_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_delete_perm.3 b/static/netbsd/man3/acl_delete_perm.3 new file mode 100644 index 00000000..a6ebbc86 --- /dev/null +++ b/static/netbsd/man3/acl_delete_perm.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: acl_delete_perm.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_delete_perm.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_DELETE_PERM 3 +.Os +.Sh NAME +.Nm acl_delete_perm +.Nd delete permissions from a permission set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_delete_perm "acl_permset_t permset_d" "acl_perm_t perm" +.Sh DESCRIPTION +The +.Fn acl_delete_perm +function +is a POSIX.1e call that removes specific permissions from permissions set +.Fa perm . +.Sh RETURN VALUES +.Rv -std acl_delete_perm +.Sh ERRORS +The +.Fn acl_delete_perm +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa permset_d +is not a valid descriptor for a permission set. +Argument +.Fa perm +does not contain a valid +.Vt acl_perm_t +value. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_perm 3 , +.Xr acl_clear_perms 3 , +.Xr acl_get_permset 3 , +.Xr acl_set_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_delete_perm +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_delete_perm +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_dup.3 b/static/netbsd/man3/acl_dup.3 new file mode 100644 index 00000000..74bae1ba --- /dev/null +++ b/static/netbsd/man3/acl_dup.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: acl_dup.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_dup.3 131504 2004-07-02 23:52:20Z ru $ +.\" +.Dd January 28, 2000 +.Dt ACL_DUP 3 +.Os +.Sh NAME +.Nm acl_dup +.Nd duplicate an ACL +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft acl_t +.Fn acl_dup "acl_t acl" +.Sh DESCRIPTION +The +.Fn acl_dup +function returns a pointer to a copy of the ACL pointed to by the argument +.Va acl . +.Pp +This function may cause memory to be allocated. +The caller should free any +releasable memory, when the new ACL is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void*)acl_t +as an argument. +.Pp +Any existing ACL pointers that refer to the ACL referred to by +.Va acl +shall continue to refer to the ACL. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, this function shall return a pointer to the +duplicate ACL. +Otherwise, a value of +.Va (acl_t)NULL +shall be returned, and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_init +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Va acl +does not point to a valid ACL. +.It Bq Er ENOMEM +The +.Va acl_t +to be returned requires more memory than is allowed by the hardware or +system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_free 3 , +.Xr acl_get 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_free.3 b/static/netbsd/man3/acl_free.3 new file mode 100644 index 00000000..e7d7bf5d --- /dev/null +++ b/static/netbsd/man3/acl_free.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: acl_free.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_free.3 131504 2004-07-02 23:52:20Z ru $ +.\" +.Dd January 28, 2000 +.Dt ACL_FREE 3 +.Os +.Sh NAME +.Nm acl_free +.Nd free ACL working state +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_free "void *obj_p" +.Sh DESCRIPTION +The +.Fn acl_free +call allows the freeing of ACL working space, such as is allocated by +.Xr acl_dup 3 , +or +.Xr acl_from_text 3 . +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +.Rv -std acl_free +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_free +function shall return -1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Va obj_p +argument is invalid. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_dup 3 , +.Xr acl_from_text 3 , +.Xr acl_get 3 , +.Xr acl_init 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_from_text.3 b/static/netbsd/man3/acl_from_text.3 new file mode 100644 index 00000000..58696e89 --- /dev/null +++ b/static/netbsd/man3/acl_from_text.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: acl_from_text.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_from_text.3 131504 2004-07-02 23:52:20Z ru $ +.\" +.Dd January 28, 2000 +.Dt ACL_FROM_TEXT 3 +.Os +.Sh NAME +.Nm acl_from_text +.Nd create an ACL from text +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft acl_t +.Fn acl_from_text "const char *buf_p" +.Sh DESCRIPTION +The +.Fn acl_from_text +function converts the text form of an ACL referred to by +.Va buf_p +into the internal working structure for ACLs, appropriate for applying to +files or manipulating. +.Pp +This function may cause memory to be allocated. +The caller should free any +releasable memory, when the new ACL is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void *)acl_t +as an argument. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, the function shall return a pointer to the +internal representation of the ACL in working storage. +Otherwise, a value +of +.Va (acl_t)NULL +shall be returned, and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_from_text +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Va buf_p +cannot be translated into an ACL. +.It Bq Er ENOMEM +The ACL working storage requires more memory than is allowed by the +hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_free 3 , +.Xr acl_get 3 , +.Xr acl_to_text 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +The +.Fn acl_from_text +and +.Fn acl_to_text +functions +rely on the +.Xr getpwent 3 +library calls to manage username and uid mapping, as well as the +.Xr getgrent 3 +library calls to manage groupname and gid mapping. +These calls are not +thread safe, and so transitively, neither are +.Fn acl_from_text +and +.Fn acl_to_text . +These functions may also interfere with stateful +calls associated with the +.Fn getpwent +and +.Fn getgrent +calls. diff --git a/static/netbsd/man3/acl_get.3 b/static/netbsd/man3/acl_get.3 new file mode 100644 index 00000000..62e281b5 --- /dev/null +++ b/static/netbsd/man3/acl_get.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: acl_get.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get.3 213573 2010-10-08 12:40:16Z uqs $ +.\" +.Dd June 25, 2009 +.Dt ACL_GET 3 +.Os +.Sh NAME +.Nm acl_get_fd , +.Nm acl_get_fd_np , +.Nm acl_get_file , +.Nm acl_get_link_np +.Nd get an ACL for a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft acl_t +.Fn acl_get_fd "int fd" +.Ft acl_t +.Fn acl_get_fd_np "int fd" "acl_type_t type" +.Ft acl_t +.Fn acl_get_file "const char *path_p" "acl_type_t type" +.Ft acl_t +.Fn acl_get_link_np "const char *path_p" "acl_type_t type" +.Sh DESCRIPTION +The +.Fn acl_get_fd , +.Fn acl_get_file , +.Fn acl_get_link_np , +and +.Fn acl_get_fd_np +each allow the retrieval of an ACL from a file. +The +.Fn acl_get_fd +is a POSIX.1e call that allows the retrieval of an ACL of type +ACL_TYPE_ACCESS +from a file descriptor. +The +.Fn acl_get_fd_np +function +is a non-portable form of +.Fn acl_get_fd +that allows the retrieval of any type of ACL from a file descriptor. +The +.Fn acl_get_file +function is a POSIX.1e call that allows the retrieval of a +specified type of ACL from a file by name; +.Fn acl_get_link_np +is a non-portable variation on +.Fn acl_get_file +which does not follow a symlink if the target of the call is a +symlink. +.Pp +These functions may cause memory to be allocated. +The caller should free +any releasable memory, when the new ACL is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void *)acl_t +as an argument. +.Pp +The ACL in the working storage is an independent copy of the ACL associated +with the object referred to by +.Va fd . +The ACL in the working storage shall not participate in any access control +decisions. +.Pp +Valid values for the +.Va type +argument are: +.Bl -column -offset 3n "ACL_TYPE_DEFAULT" +.It ACL_TYPE_ACCESS POSIX.1e access ACL +.It ACL_TYPE_DEFAULT POSIX.1e default ACL +.It ACL_TYPE_NFS4 NFSv4 ACL +.El +.Pp +The ACL returned will be branded accordingly. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, the function shall return a pointer to the ACL +that was retrieved. +Otherwise, a value of +.Va (acl_t)NULL +shall be returned, and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_get_fd +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, or the +object exists and the process does not have appropriate access rights. +.It Bq Er EBADF +The +.Va fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The ACL type passed is invalid for this file object. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an +entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named object does not exist, or the +.Va path_p +argument points to an empty string. +.It Bq Er ENOMEM +Insufficient memory available to fulfill request. +.It Bq Er EOPNOTSUPP +The file system does not support ACL retrieval. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_free 3 , +.Xr acl_get 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_set 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_get_brand_np.3 b/static/netbsd/man3/acl_get_brand_np.3 new file mode 100644 index 00000000..5425ab2f --- /dev/null +++ b/static/netbsd/man3/acl_get_brand_np.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: acl_get_brand_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_brand_np.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_GET_BRAND_NP 3 +.Os +.Sh NAME +.Nm acl_get_brand_np +.Nd retrieve the ACL brand from an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_brand_np "acl_t acl" "int *brand_p" +.Sh DESCRIPTION +The +.Fn acl_get_brand_np +function +is a non-portable call that returns the ACL brand for the ACL +.Fa acl . +Upon successful completion, the location referred to by the argument +.Fa brand_p +will be set to the ACL brand of the ACL +.Fa acl . +.Pp +Branding is an internal mechanism intended to prevent mixing POSIX.1e +and NFSv4 entries by mistake. +It's also used by the libc to determine how to print out the ACL. +The first call to function that is specific for one particular brand - POSIX.1e +or NFSv4 - "brands" the ACL. +After that, calling function specific to another brand will result in error. +.Sh RETURN VALUES +.Rv -std acl_get_brand_np +.Sh ERRORS +The +.Fn acl_get_brand_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa acl +does not point to a valid ACL. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_brand_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_get_brand_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_get_entry.3 b/static/netbsd/man3/acl_get_entry.3 new file mode 100644 index 00000000..393d5f98 --- /dev/null +++ b/static/netbsd/man3/acl_get_entry.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: acl_get_entry.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_entry.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd April 13, 2001 +.Dt ACL_GET_ENTRY 3 +.Os +.Sh NAME +.Nm acl_get_entry +.Nd retrieve an ACL entry from an ACL +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p" +.Sh DESCRIPTION +The +.Fn acl_get_entry +function +is a POSIX.1e call that retrieves a descriptor for an ACL entry +specified by the argument +.Fa entry_d +within the ACL indicated by the argument +.Fa acl . +.Pp +If the value of +.Fa entry_id +is +.Dv ACL_FIRST_ENTRY , +then the function will return in +.Fa entry_p +a descriptor for the first ACL entry within +.Fa acl . +If a call is made to +.Fn acl_get_entry +with +.Fa entry_id +set to +.Dv ACL_NEXT_ENTRY +when there has not been either an initial successful call to +.Fn acl_get_entry , +or a previous successful call to +.Fn acl_create_entry , +.Fn acl_delete_entry , +.Fn acl_dup , +.Fn acl_from_text , +.Fn acl_get_fd , +.Fn acl_get_file , +.Fn acl_set_fd , +.Fn acl_set_file , +or +.Fn acl_valid , +then the result is unspecified. +.Sh RETURN VALUES +If the +.Fn acl_get_entry +function successfully obtains an ACL entry, a value of 1 is returned. +If the ACL has no ACL entries, the +.Fn acl_get_entry +returns a value of 0. +If the value of +.Fa entry_id +is +.Dv ACL_NEXT_ENTRY +and the last ACL entry in the ACL has already been returned by a +previous call to +.Fn acl_get_entry , +a value of 0 will be returned until a successful call with +.Fa entry_id +of +.Dv ACL_FIRST_ENTRY +is made. +Otherwise, a value of -1 will be returned and +the global variable +.Va errno +will be set to indicate the error. +.Sh ERRORS +The +.Fn acl_get_entry +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa acl +does not point to a valid ACL. +Argument +.Fa entry_id +is neither +.Dv ACL_FIRST_ENTRY +nor +.Dv ACL_NEXT_ENTRY . +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_calc_mask 3 , +.Xr acl_create_entry 3 , +.Xr acl_delete_entry 3 , +.Xr acl_dup 3 , +.Xr acl_from_text 3 , +.Xr acl_get_fd 3 , +.Xr acl_get_file 3 , +.Xr acl_init 3 , +.Xr acl_set_fd 3 , +.Xr acl_set_file 3 , +.Xr acl_valid 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_entry +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_entry +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_get_entry_type_np.3 b/static/netbsd/man3/acl_get_entry_type_np.3 new file mode 100644 index 00000000..40ab2ef5 --- /dev/null +++ b/static/netbsd/man3/acl_get_entry_type_np.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: acl_get_entry_type_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_entry_type_np.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_GET_ENTRY_TYPE_NP 3 +.Os +.Sh NAME +.Nm acl_get_entry_type_np +.Nd retrieve the ACL type from an NFSv4 ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_entry_type_np "acl_entry_t entry_d" "acl_entry_type_t *entry_type_p" +.Sh DESCRIPTION +The +.Fn acl_get_entry_type_np +function +is a non-portable call that returns the ACL type for the NFSv4 ACL entry +.Fa entry_d . +Upon successful completion, the location referred to by the argument +.Fa entry_type_p +will be set to the ACL type of the ACL entry +.Fa entry_d . +.Sh RETURN VALUES +.Rv -std acl_get_entry_type_np +.Sh ERRORS +The +.Fn acl_get_entry_type_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an NFSv4 ACL entry; +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_set_entry_type_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_entry_type_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_get_entry_type_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_get_flag_np.3 b/static/netbsd/man3/acl_get_flag_np.3 new file mode 100644 index 00000000..67ca4b2e --- /dev/null +++ b/static/netbsd/man3/acl_get_flag_np.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: acl_get_flag_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_flag_np.3 273853 2014-10-30 10:49:50Z trasz $ +.\" +.Dd October 30, 2014 +.Dt ACL_GET_FLAG_NP 3 +.Os +.Sh NAME +.Nm acl_get_flag_np +.Nd check if a flag is set in a flagset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_flag_np "acl_flagset_t flagset_d" "acl_flag_t flag" +.Sh DESCRIPTION +The +.Fn acl_get_flag_np +function +is a non-portable function that checks if a NFSv4 ACL flag is set in +a flagset. +.Sh RETURN VALUES +If the flag in +.Fa flag +is set in the flagset +.Fa flagset_d , +a value of +1 +is returned, otherwise a value of +0 +is returned. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_get_flag_np +function will return a value of +\-1 +and set global variable +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa flag +does not contain a valid ACL flag or argument +.Fa flagset_d +is not a valid ACL flagset. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_flag_np 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_flag_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_get_flag_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_get_flagset_np.3 b/static/netbsd/man3/acl_get_flagset_np.3 new file mode 100644 index 00000000..a9e793b2 --- /dev/null +++ b/static/netbsd/man3/acl_get_flagset_np.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: acl_get_flagset_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_flagset_np.3 273853 2014-10-30 10:49:50Z trasz $ +.\" +.Dd October 30, 2014 +.Dt ACL_GET_FLAGSET_NP 3 +.Os +.Sh NAME +.Nm acl_get_flagset_np +.Nd retrieve flagset from an NFSv4 ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_flagset_np "acl_entry_t entry_d" "acl_flagset_t *flagset_p" +.Sh DESCRIPTION +The +.Fn acl_get_flagset_np +function +is a non-portable call that returns via +.Fa flagset_np_p +a descriptor to the flagset in the NFSv4 ACL entry +.Fa entry_d . +Subsequent operations using the returned flagset operate +on the flagset within the ACL entry. +.Sh RETURN VALUES +.Rv -std acl_get_flagset_np +.Sh ERRORS +The +.Fn acl_get_flagset_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_flag_np 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_set_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_flagset_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_get_flagset_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_get_perm_np.3 b/static/netbsd/man3/acl_get_perm_np.3 new file mode 100644 index 00000000..8cb5ae5d --- /dev/null +++ b/static/netbsd/man3/acl_get_perm_np.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: acl_get_perm_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_perm_np.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd April 10, 2001 +.Dt ACL_GET_PERM_NP 3 +.Os +.Sh NAME +.Nm acl_get_perm_np +.Nd "check if a permission is set in a permission set" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_perm_np "acl_permset_t permset_d" "acl_perm_t perm" +.Sh DESCRIPTION +The +.Fn acl_get_perm_np +function +is a non-portable function that checks if a permission is set in +a permission set. +.Sh RETURN VALUES +If the permission in +.Fa perm +is set in the permission set +.Fa permset_d , +a value of +1 +is returned, otherwise a value of +0 +is returned. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_get_perm_np +function will return a value of +\-1 +and set global variable +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa perm +does not contain a valid ACL permission or argument +.Fa permset_d +is not a valid ACL permset. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_perm 3 , +.Xr acl_clear_perms 3 , +.Xr acl_delete_perm 3 , +.Xr acl_get_permset 3 , +.Xr acl_set_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_perm_np +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_perm_np +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_get_permset.3 b/static/netbsd/man3/acl_get_permset.3 new file mode 100644 index 00000000..7baef77f --- /dev/null +++ b/static/netbsd/man3/acl_get_permset.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: acl_get_permset.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_permset.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_GET_PERMSET 3 +.Os +.Sh NAME +.Nm acl_get_permset +.Nd retrieve permission set from an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_permset "acl_entry_t entry_d" "acl_permset_t *permset_p" +.Sh DESCRIPTION +The +.Fn acl_get_permset +function +is a POSIX.1e call that returns via +.Fa permset_p +a descriptor to the permission set in the ACL entry +.Fa entry_d . +Subsequent operations using the returned permission set operate +on the permission set within the ACL entry. +.Sh RETURN VALUES +.Rv -std acl_get_permset +.Sh ERRORS +The +.Fn acl_get_permset +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_perm 3 , +.Xr acl_clear_perms 3 , +.Xr acl_delete_perm 3 , +.Xr acl_set_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_permset +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_permset +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_get_qualifier.3 b/static/netbsd/man3/acl_get_qualifier.3 new file mode 100644 index 00000000..7462e9a3 --- /dev/null +++ b/static/netbsd/man3/acl_get_qualifier.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: acl_get_qualifier.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_qualifier.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 13, 2001 +.Dt ACL_GET_QUALIFIER 3 +.Os +.Sh NAME +.Nm acl_get_qualifier +.Nd retrieve the qualifier from an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft void * +.Fn acl_get_qualifier "acl_entry_t entry_d" +.Sh DESCRIPTION +The +.Fn acl_get_qualifier +function +is a POSIX.1e call that retrieves the qualifier of the tag for +the ACL entry indicated by the argument +.Fa entry_d +into working storage and returns a pointer to that storage. +.Pp +If the value of the tag type in the ACL entry referred to by +.Fa entry_d +is +.Dv ACL_USER , +then the value returned by +.Fn acl_get_qualifier +will be a pointer to type +.Vt uid_t . +.Pp +If the value of the tag type in +the ACL entry referred to by +.Fa entry_d +is +.Dv ACL_GROUP , +then the value returned by +.Fn acl_get_qualifier +will be a pointer to type +.Vt gid_t . +.Pp +If the value of the tag type in the ACL entry referred to by +.Fa entry_d +is +.Dv ACL_UNDEFINED_TAG , ACL_USER_OBJ , ACL_GROUP_OBJ , +.Dv ACL_OTHER , ACL_MASK , +or an implementation-defined value for which a qualifier +is not supported, then +.Fn acl_get_qualifier +will return a value of +.Vt ( void * ) Ns Dv NULL +and the function will fail. +.Pp +This function may cause memory to be allocated. +The caller should +free any releasable memory, when the new qualifier is no longer +required, by calling +.Fn acl_free +with +.Vt void * +as the argument. +.Sh RETURN VALUES +The +.Fn acl_get_qualifier +function returns a pointer to the allocated storage if successful; +otherwise a +.Dv NULL +pointer is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn acl_get_qualifier +fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +does not point to a valid descriptor for an ACL entry. +The +value of the tag type in the ACL entry referenced by argument +.Fa entry_d +is not +.Dv ACL_USER +or +.Dv ACL_GROUP . +.It Bq Er ENOMEM +The value to be returned requires more memory than is allowed +by the hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_create_entry 3 , +.Xr acl_free 3 , +.Xr acl_get_entry 3 , +.Xr acl_get_tag_type 3 , +.Xr acl_set_qualifier 3 , +.Xr acl_set_tag_type 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_qualifier +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_qualifier +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_get_tag_type.3 b/static/netbsd/man3/acl_get_tag_type.3 new file mode 100644 index 00000000..423e8f87 --- /dev/null +++ b/static/netbsd/man3/acl_get_tag_type.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: acl_get_tag_type.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_get_tag_type.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_GET_TAG_TYPE 3 +.Os +.Sh NAME +.Nm acl_get_tag_type +.Nd retrieve the tag type from an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_get_tag_type "acl_entry_t entry_d" "acl_tag_t *tag_type_p" +.Sh DESCRIPTION +The +.Fn acl_get_tag_type +function +is a POSIX.1e call that returns the tag type for the ACL entry +.Fa entry_d . +Upon successful completion, the location referred to by the argument +.Fa tag_type_p +will be set to the tag type of the ACL entry +.Fa entry_d . +.Sh RETURN VALUES +.Rv -std acl_get_tag_type +.Sh ERRORS +The +.Fn acl_get_tag_type +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry; +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_create_entry 3 , +.Xr acl_get_entry 3 , +.Xr acl_get_qualifier 3 , +.Xr acl_init 3 , +.Xr acl_set_qualifier 3 , +.Xr acl_set_tag_type 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_tag_type +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_tag_type +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_init.3 b/static/netbsd/man3/acl_init.3 new file mode 100644 index 00000000..f129e727 --- /dev/null +++ b/static/netbsd/man3/acl_init.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: acl_init.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_init.3 131504 2004-07-02 23:52:20Z ru $ +.\" +.Dd January 28, 2000 +.Dt ACL_INIT 3 +.Os +.Sh NAME +.Nm acl_init +.Nd initialize ACL working storage +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft acl_t +.Fn acl_init "int count" +.Sh DESCRIPTION +The +.Fn acl_init +function allocates and initializes the working storage for an ACL of at +least +.Va count +ACL entries. +A pointer to the working storage is returned. +The working +storage allocated to contain the ACL is freed by a call to +.Xr acl_free 3 . +When the area is first allocated, it shall contain an ACL that contains +no ACL entries. +.Pp +This function may cause memory to be allocated. +The caller should free any +releasable memory, when the new ACL is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void*)acl_t +as an argument. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, this function shall return a pointer to the +working storage. +Otherwise, a value of +.Va (acl_t)NULL +shall be returned, and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_init +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of count is less than zero. +.It Bq Er ENOMEM +The +.Va acl_t +to be returned requires more memory than is allowed by the hardware or +system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_free 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_is_trivial_np.3 b/static/netbsd/man3/acl_is_trivial_np.3 new file mode 100644 index 00000000..c15ed6e0 --- /dev/null +++ b/static/netbsd/man3/acl_is_trivial_np.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: acl_is_trivial_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_is_trivial_np.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd November 12, 2013 +.Dt ACL_STRIP_NP 3 +.Os +.Sh NAME +.Nm acl_is_trivial_np +.Nd determine whether ACL is trivial +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_is_trivial_np "const acl_t aclp" "int *trivialp" +.Sh DESCRIPTION +The +.Fn acl_is_trivial +function determines whether the ACL pointed to by the argument +.Va acl +is trivial. +Upon successful completion, the location referred to by the argument +.Fa trivialp +will be set to 1, if the ACL +.Fa aclp +points to is trivial, or 0 if it's not. +.Pp +ACL is trivial if it can be fully expressed as a file mode without losing +any access rules. +For POSIX.1e ACLs, ACL is trivial if it has the three required entries, +one for owner, one for owning group, and one for other. +For NFSv4 ACLs, ACL is trivial if it is identical to the ACL generated by +.Fn acl_strip_np 3 . +Files that have non-trivial ACL have a plus sign appended after mode bits +in "ls -l" output. +.Sh RETURN VALUES +.Rv -std acl_get_tag_type +.Sh SEE ALSO +.Xr acl 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_is_trivial_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org diff --git a/static/netbsd/man3/acl_set.3 b/static/netbsd/man3/acl_set.3 new file mode 100644 index 00000000..6b5035ba --- /dev/null +++ b/static/netbsd/man3/acl_set.3 @@ -0,0 +1,158 @@ +.\" $NetBSD: acl_set.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set.3 213573 2010-10-08 12:40:16Z uqs $ +.\" +.Dd June 25, 2009 +.Dt ACL_SET 3 +.Os +.Sh NAME +.Nm acl_set_fd , +.Nm acl_set_fd_np , +.Nm acl_set_file , +.Nm acl_set_link_np +.Nd set an ACL for a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_fd "int fd" "acl_t acl" +.Ft int +.Fn acl_set_fd_np "int fd" "acl_t acl" "acl_type_t type" +.Ft int +.Fn acl_set_file "const char *path_p" "acl_type_t type" "acl_t acl" +.Ft int +.Fn acl_set_link_np "const char *path_p" "acl_type_t type" "acl_t acl" +.Sh DESCRIPTION +The +.Fn acl_set_fd , +.Fn acl_set_fd_np , +.Fn acl_set_file , +and +.Fn acl_set_link_np +each associate an ACL with an object referred to by +.Va fd +or +.Va path_p . +The +.Fn acl_set_fd_np +and +.Fn acl_set_link_np +functions are not POSIX.1e calls. +The +.Fn acl_set_fd +function allows only the setting of ACLs of type ACL_TYPE_ACCESS +where as +.Fn acl_set_fd_np +allows the setting of ACLs of any type. +The +.Fn acl_set_link_np +function acts on a symlink rather than its target, if the target of the +path is a symlink. +.Pp +Valid values for the +.Va type +argument are: +.Bl -column -offset 3n "ACL_TYPE_DEFAULT" +.It ACL_TYPE_ACCESS POSIX.1e access ACL +.It ACL_TYPE_DEFAULT POSIX.1e default ACL +.It ACL_TYPE_NFS4 NFSv4 ACL +.El +.Pp +Trying to set ACL_TYPE_NFS4 with +.Va acl +branded as POSIX.1e, or ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT with ACL +branded as NFSv4, will result in error. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +If any of the following conditions occur, these functions shall return +-1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, or the +object exists and the process does not have appropriate access rights. +.It Bq Er EBADF +The +.Va fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +Argument +.Va acl +does not point to a valid ACL for this object, or the ACL type +specified in +.Va type +is invalid for this object, or there is branding mismatch. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an +entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named object does not exist, or the +.Va path_p +argument points to an empty string. +.It Bq Er ENOMEM +Insufficient memory available to fulfill request. +.It Bq Er ENOSPC +The directory or file system that would contain the new ACL cannot be +extended, or the file system is out of file allocation resources. +.It Bq Er EOPNOTSUPP +The file system does not support ACL retrieval. +.It Bq Er EROFS +This function requires modification of a file system which is currently +read-only. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_delete 3 , +.Xr acl_get 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_valid 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acl_set_entry_type_np.3 b/static/netbsd/man3/acl_set_entry_type_np.3 new file mode 100644 index 00000000..fc2b8e3b --- /dev/null +++ b/static/netbsd/man3/acl_set_entry_type_np.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: acl_set_entry_type_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set_entry_type_np.3 273853 2014-10-30 10:49:50Z trasz $ +.\" +.Dd October 30, 2014 +.Dt ACL_SET_ENTRY_TYPE_NP 3 +.Os +.Sh NAME +.Nm acl_set_entry_type_np +.Nd set NFSv4 ACL entry type +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_entry_type_np "acl_entry_t entry_d" "acl_entry_type_t entry_type" +.Sh DESCRIPTION +The +.Fn acl_set_entry_type_np +function +is a non-portable call that sets the type of the NFSv4 ACL entry +.Fa entry_d +to the value referred to by +.Fa entry_type . +.Pp +Valid values are: +.Bl -column -offset 3n "ACL_ENTRY_TYPE_ALLOW" +.It ACL_ENTRY_TYPE_ALLOW Ta "allow" type entry +.It ACL_ENTRY_TYPE_DENY Ta "deny" type entry +.El +.Pp +This call brands the ACL as NFSv4. +.Sh RETURN VALUES +.Rv -std acl_set_entry_type_np +.Sh ERRORS +The +.Fn acl_set_entry_type_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +The value pointed to by +.Fa entry_type +is not valid. +ACL is already branded as POSIX.1e. +.It Bq Er ENOMEM +The value to be returned requires more memory than is allowed +by the hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_get_entry_type_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_entry_type_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_get_entry_type_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_set_flagset_np.3 b/static/netbsd/man3/acl_set_flagset_np.3 new file mode 100644 index 00000000..721d9cef --- /dev/null +++ b/static/netbsd/man3/acl_set_flagset_np.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: acl_set_flagset_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set_flagset_np.3 276006 2014-12-21 12:36:36Z brueffer $ +.\" +.Dd October 30, 2014 +.Dt ACL_SET_FLAGSET_NP 3 +.Os +.Sh NAME +.Nm acl_set_flagset_np +.Nd set the flags of an NFSv4 ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_flagset_np "acl_entry_t entry_d" "acl_flagset_t flagset_d" +.Sh DESCRIPTION +The +.Fn acl_set_flagset_np +function +is a non-portable call that sets the flags of NFSv4 ACL entry +.Fa entry_d +with the flags contained in +.Fa flagset_d . +.Pp +This call brands the ACL as NFSv4. +.Sh RETURN VALUES +.Rv -std acl_set_flagset_np +.Sh ERRORS +The +.Fn acl_set_flagset_np +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +ACL is already branded as POSIX.1e. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_flag_np 3 , +.Xr acl_clear_flags_np 3 , +.Xr acl_delete_flag_np 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_get_flagset_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_set_flagset_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +The +.Fn acl_set_flagset_np +function was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . diff --git a/static/netbsd/man3/acl_set_permset.3 b/static/netbsd/man3/acl_set_permset.3 new file mode 100644 index 00000000..97f4dcff --- /dev/null +++ b/static/netbsd/man3/acl_set_permset.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: acl_set_permset.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set_permset.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_SET_PERMSET 3 +.Os +.Sh NAME +.Nm acl_set_permset +.Nd set the permissions of an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_permset "acl_entry_t entry_d" "acl_permset_t permset_d" +.Sh DESCRIPTION +The +.Fn acl_set_permset +function +is a POSIX.1e call that sets the permissions of ACL entry +.Fa entry_d +with the permissions contained in +.Fa permset_d . +.Sh RETURN VALUES +.Rv -std acl_set_permset +.Sh ERRORS +The +.Fn acl_set_permset +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_add_perm 3 , +.Xr acl_clear_perms 3 , +.Xr acl_delete_perm 3 , +.Xr acl_get_permset 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_set_permset +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_set_permset +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_set_qualifier.3 b/static/netbsd/man3/acl_set_qualifier.3 new file mode 100644 index 00000000..0d08d1f7 --- /dev/null +++ b/static/netbsd/man3/acl_set_qualifier.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: acl_set_qualifier.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set_qualifier.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd March 10, 2001 +.Dt ACL_SET_QUALIFIER 3 +.Os +.Sh NAME +.Nm acl_set_qualifier +.Nd set ACL tag qualifier +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_qualifier "acl_entry_t entry_d" "const void *tag_qualifier_p" +.Sh DESCRIPTION +The +.Fn acl_set_qualifier +function +is a POSIX.1e call that sets the qualifier of the tag for the ACL entry +.Fa entry_d +to the value referred to by +.Fa tag_qualifier_p . +.Sh RETURN VALUES +.Rv -std acl_set_qualifier +.Sh ERRORS +The +.Fn acl_set_qualifier +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +The tag type of the +ACL entry +.Fa entry_d +is not +.Dv ACL_USER +or +.Dv ACL_GROUP . +The value pointed to by +.Fa tag_qualifier_p +is not valid. +.It Bq Er ENOMEM +The value to be returned requires more memory than is allowed +by the hardware or system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get_qualifier 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_get_qualifier +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_get_qualifier +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_set_tag_type.3 b/static/netbsd/man3/acl_set_tag_type.3 new file mode 100644 index 00000000..2590441d --- /dev/null +++ b/static/netbsd/man3/acl_set_tag_type.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: acl_set_tag_type.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2001 Chris D. Faulhaber +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_set_tag_type.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_SET_TAG_TYPE 3 +.Os +.Sh NAME +.Nm acl_set_tag_type +.Nd set the tag type of an ACL entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_set_tag_type "acl_entry_t entry_d" "acl_tag_t tag_type" +.Sh DESCRIPTION +The +.Fn acl_set_tag_type +function +is a POSIX.1e call that sets the ACL tag type of ACL entry +.Fa entry_d +to the value of +.Fa tag_type . +.Pp +Valid values are: +.Bl -column -offset 3n "ACL_OTHER_OBJ" +.It ACL_USER_OBJ Ta "Permissions apply to file owner" +.It ACL_USER Ta "Permissions apply to additional user specified by qualifier" +.It ACL_GROUP_OBJ Ta "Permissions apply to file group" +.It ACL_GROUP Ta "Permissions apply to additional group specified by qualifier" +.It ACL_MASK Ta "Permissions specify mask" +.It ACL_OTHER Ta Permissions apply to "other" +.It ACL_OTHER_OBJ Ta "Same as ACL_OTHER" +.It ACL_EVERYONE Ta Permissions apply to "everyone@" +.El +.Pp +Calling +.Fn acl_set_tag_type +with +.Fa tag_type +equal to ACL_MASK, ACL_OTHER or ACL_OTHER_OBJ brands the ACL as POSIX.1e. +Calling it with ACL_EVERYONE brands the ACL as NFSv4. +.Sh RETURN VALUES +.Rv -std acl_set_tag_type +.Sh ERRORS +The +.Fn acl_set_tag_type +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Fa entry_d +is not a valid descriptor for an ACL entry. +Argument +.Fa tag_type +is not a valid ACL tag type. +ACL is already branded differently. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get_brand_np 3 , +.Xr acl_get_tag_type 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_set_tag_type +function was added in +.Fx 5.0 . +.Sh AUTHORS +The +.Fn acl_set_tag_type +function was written by +.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . diff --git a/static/netbsd/man3/acl_strip_np.3 b/static/netbsd/man3/acl_strip_np.3 new file mode 100644 index 00000000..94be2e29 --- /dev/null +++ b/static/netbsd/man3/acl_strip_np.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: acl_strip_np.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2008, 2009 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_strip_np.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd June 25, 2009 +.Dt ACL_STRIP_NP 3 +.Os +.Sh NAME +.Nm acl_strip_np +.Nd strip extended entries from an ACL +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft acl_t +.Fn acl_strip_np "const acl_t acl" "int recalculate_mask" +.Sh DESCRIPTION +The +.Fn acl_strip_np +function returns a pointer to a trivial ACL computed from the ACL pointed +to by the argument +.Va acl . +.Pp +This function may cause memory to be allocated. +The caller should free any +releasable memory, when the new ACL is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void*)acl_t +as an argument. +.Pp +Any existing ACL pointers that refer to the ACL referred to by +.Va acl +shall continue to refer to the ACL. +.Sh RETURN VALUES +Upon successful completion, this function shall return a pointer to the +newly allocated ACL. +Otherwise, a value of +.Va (acl_t)NULL +shall be returned, and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_init +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Va acl +does not point to a valid ACL. +.It Bq Er ENOMEM +The +.Va acl_t +to be returned requires more memory than is allowed by the hardware or +system-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_is_trivial_np 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 . +The +.Fn acl_strip_np +function was added in +.Fx 8.0 . +.Sh AUTHORS +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org diff --git a/static/netbsd/man3/acl_to_text.3 b/static/netbsd/man3/acl_to_text.3 new file mode 100644 index 00000000..f656619c --- /dev/null +++ b/static/netbsd/man3/acl_to_text.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: acl_to_text.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_to_text.3 318709 2017-05-23 07:12:31Z ngie $ +.\" +.Dd June 25, 2009 +.Dt ACL_TO_TEXT 3 +.Os +.Sh NAME +.Nm acl_to_text , +.Nm acl_to_text_np +.Nd convert an ACL to text +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft char * +.Fn acl_to_text "acl_t acl" "ssize_t *len_p" +.Ft char * +.Fn acl_to_text_np "acl_t acl" "ssize_t *len_p" "int flags" +.Sh DESCRIPTION +The +.Fn acl_to_text +and +.Fn acl_to_text_np +functions translate the ACL pointed to by argument +.Va acl +into a NULL terminated character string. +If the pointer +.Va len_p +is not NULL, then the function shall return the length of the string (not +including the NULL terminator) in the location pointed to by +.Va len_p . +If the ACL is POSIX.1e, the format of the text string returned by +.Fn acl_to_text +shall be the POSIX.1e long ACL form. +If the ACL is NFSv4, the format of the text string shall be the compact form, unless +the +.Va ACL_TEXT_VERBOSE +flag is given. +.Pp +The flags specified are formed by +.Em or Ns 'ing +the following values +.Bl -column -offset 3n "ACL_TEXT_NUMERIC_IDS" +.It ACL_TEXT_VERBOSE Ta "Format ACL using verbose form" +.It ACL_TEXT_NUMERIC_IDS Ta "Do not resolve IDs into user or group names" +.It ACL_TEXT_APPEND_ID Ta "In addition to user and group names, append numeric IDs" +.El +.Pp +This function allocates any memory necessary to contain the string and +returns a pointer to the string. +The caller should free any releasable +memory, when the new string is no longer required, by calling +.Xr acl_free 3 +with the +.Va (void*)char +as an argument. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +Upon successful completion, the function shall return a pointer to the +long text form of an ACL. +Otherwise, a value of +.Va (char*)NULL +shall be returned and +.Va errno +shall be set to indicate the error. +.Sh ERRORS +If any of the following conditions occur, the +.Fn acl_to_text +function shall return a value of +.Va (acl_t)NULL +and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +Argument +.Va acl +does not point to a valid ACL. +.Pp +The ACL denoted by +.Va acl +contains one or more improperly formed ACL entries, or for some other +reason cannot be translated into a text form of an ACL. +.It Bq Er ENOMEM +The character string to be returned requires more memory than is allowed +by the hardware or software-imposed memory management constraints. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_free 3 , +.Xr acl_from_text 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson +.Sh BUGS +The +.Fn acl_from_text +and +.Fn acl_to_text +functions +rely on the +.Xr getpwent 3 +library calls to manage username and uid mapping, as well as the +.Xr getgrent 3 +library calls to manage groupname and gid mapping. +These calls are not +thread safe, and so transitively, neither are +.Fn acl_from_text +and +.Fn acl_to_text . +These functions may also interfere with stateful +calls associated with the +.Fn getpwent +and +.Fn getgrent +calls. diff --git a/static/netbsd/man3/acl_valid.3 b/static/netbsd/man3/acl_valid.3 new file mode 100644 index 00000000..d0cf555d --- /dev/null +++ b/static/netbsd/man3/acl_valid.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: acl_valid.3,v 1.2 2020/06/18 19:46:34 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2002 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/acl_valid.3 140288 2005-01-15 12:21:03Z ru $ +.\" +.Dd December 29, 2002 +.Dt ACL_VALID 3 +.Os +.Sh NAME +.Nm acl_valid , +.Nm acl_valid_fd_np , +.Nm acl_valid_file_np , +.Nm acl_valid_link_np +.Nd validate an ACL +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.Ft int +.Fn acl_valid "acl_t acl" +.Ft int +.Fn acl_valid_fd_np "int fd" "acl_type_t type" "acl_t acl" +.Ft int +.Fn acl_valid_file_np "const char *path_p" "acl_type_t type" "acl_t acl" +.Ft int +.Fn acl_valid_link_np "const char *path_p" "acl_type_t type" "acl_t acl" +.Sh DESCRIPTION +These functions check that the ACL referred to by the argument +.Va acl +is valid. +The POSIX.1e routine, +.Fn acl_valid , +checks this validity only with POSIX.1e ACL semantics, and irrespective +of the context in which the ACL is to be used. +The non-portable forms, +.Fn acl_valid_fd_np , +.Fn acl_valid_file_np , +and +.Fn acl_valid_link_np +allow an ACL to be checked in the context of a specific acl type, +.Va type , +and file system object. +In environments where additional ACL types are +supported than just POSIX.1e, this makes more sense. +Whereas +.Fn acl_valid_file_np +will follow the symlink if the specified path is to a symlink, +.Fn acl_valid_link_np +will not. +.Pp +For POSIX.1e semantics, the checks include: +.Bl -bullet +.It +The three required entries +.Dv ( ACL_USER_OBJ , ACL_GROUP_OBJ , +and +.Dv ACL_OTHER ) +shall exist exactly once in the ACL. +If the ACL contains any +.Dv ACL_USER , ACL_GROUP , +or any other +implementation-defined entries in the file group class +then one +.Dv ACL_MASK +entry shall also be required. +The ACL shall contain at most one +.Dv ACL_MASK +entry. +.It +The qualifier field shall be unique among all entries of +the same POSIX.1e ACL facility defined tag type. +The +tag type field shall contain valid values including any +implementation-defined values. +Validation of the values +of the qualifier field is implementation-defined. +.El +.Pp +The POSIX.1e +.Fn acl_valid +function may reorder the ACL for the purposes of verification; the +non-portable validation functions will not. +.Sh IMPLEMENTATION NOTES +.Fx Ns 's +support for POSIX.1e interfaces and features is still under +development at this time. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +If any of the following conditions occur, these functions shall return +-1 and set +.Va errno +to the corresponding value: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, or the +object exists and the process does not have appropriate access rights. +.It Bq Er EBADF +The +.Va fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +Argument +.Va acl +does not point to a valid ACL. +.Pp +One or more of the required ACL entries is not present in +.Va acl . +.Pp +The ACL contains entries that are not unique. +.Pp +The file system rejects the ACL based on fs-specific semantics issues. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an +entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named object does not exist, or the +.Va path_p +argument points to an empty string. +.It Bq Er ENOMEM +Insufficient memory available to fulfill request. +.It Bq Er EOPNOTSUPP +The file system does not support ACL retrieval. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr acl_get 3 , +.Xr acl_init 3 , +.Xr acl_set 3 , +.Xr posix1e 3 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion +of the draft continues on the cross-platform POSIX.1e implementation +mailing list. +To join this list, see the +.Fx +POSIX.1e implementation +page for more information. +.Sh HISTORY +POSIX.1e support was introduced in +.Fx 4.0 , +and development continues. +.Sh AUTHORS +.An Robert N M Watson diff --git a/static/netbsd/man3/acos.3 b/static/netbsd/man3/acos.3 new file mode 100644 index 00000000..b3f3d4ba --- /dev/null +++ b/static/netbsd/man3/acos.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)acos.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: acos.3,v 1.19 2022/12/04 11:25:09 uwe Exp $ +.\" +.Dd January 29, 2013 +.Dt ACOS 3 +.Os +.Sh NAME +.Nm acos , +.Nm acosf , +.Nm acosl +.Nd arc cosine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn acos "double x" +.Ft float +.Fn acosf "float x" +.Ft long double +.Fn acosl "long double x" +.Sh DESCRIPTION +The +.Fn acos , +.Fn acosf , +and +.Fn acosl +functions compute the principal value of the arc cosine of +.Fa x +in the range +.Bq 0 , \*(Pi . +.Sh RETURN VALUES +If |x|>1, +.Fn acos "x" , +.Fn acosf "x" , +and +.Fn acosl "x" +.\" POSIX_MODE +set the global variable +.Va errno +to +.Er EDOM . +.\" SYSV_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn acos +function conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/acosh.3 b/static/netbsd/man3/acosh.3 new file mode 100644 index 00000000..5b6b3cd7 --- /dev/null +++ b/static/netbsd/man3/acosh.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)acosh.3 5.2 (Berkeley) 5/6/91 +.\" $NetBSD: acosh.3,v 1.18 2022/12/04 11:25:09 uwe Exp $ +.\" +.Dd January 29, 2013 +.Dt ACOSH 3 +.Os +.Sh NAME +.Nm acosh , +.Nm acoshf , +.Nm acoshl +.Nd inverse hyperbolic cosine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn acosh "double x" +.Ft float +.Fn acoshf "float x" +.Ft long double +.Fn acoshl "long double x" +.Sh DESCRIPTION +The +.Fn acosh , +.Fn acoshf , +and +.Fn acoshl +functions compute the inverse hyperbolic cosine +of the real +argument +.Ar x . +.Sh RETURN VALUES +.\" POSIX_MODE +If x is less than one, +.Fn acosh "x" , +.Fn acoshf "x" , +and +.Fn acoshl "x" +return NaN and set the global variable +.Va errno +to +.Er EDOM . +.\" SVR4_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr asinh 3 , +.Xr atanh 3 , +.Xr exp 3 , +.Xr math 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn acosh +function conforms to +.St -isoC-99 . +.Sh HISTORY +The +.Fn acosh +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/affinity.3 b/static/netbsd/man3/affinity.3 new file mode 100644 index 00000000..50a3d604 --- /dev/null +++ b/static/netbsd/man3/affinity.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: affinity.3,v 1.10 2025/02/25 10:15:41 riastradh Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius . +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 21, 2025 +.Dt AFFINITY 3 +.Os +.Sh NAME +.Nm pthread_setaffinity_np , +.Nm pthread_getaffinity_np +.Nd affinity of threads +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In sched.h +.Ft int +.Fn pthread_setaffinity_np "pthread_t thread" "size_t size" "cpuset_t *set" +.Ft int +.Fn pthread_getaffinity_np "pthread_t thread" "size_t size" "cpuset_t *set" +.Sh DESCRIPTION +Thread affinity allows to run the thread on specified CPU or CPUs only. +.Pp +The +.Fn pthread_setaffinity_np +function sets the affinity mask +.Fa set +for +.Fa thread . +At least one valid CPU must be set in the mask. +.Pp +The +.Fn pthread_getaffinity_np +function gets the affinity mask of +.Fa thread +into +.Fa set . +Note that +.Fa set +must be created and initialized using the +.Xr cpuset 3 +functions. +.Sh IMPLEMENTATION NOTES +Setting CPU +.Nm +requires super-user privileges. +Ordinary users can be allowed to control CPU affinity +of their threads via the +.Pa security.models.extensions.user_set_cpu_affinity +.Xr sysctl 7 . +See +.Xr secmodel_extensions 9 . +.Pp +Portable applications should not use the +.Fn pthread_setaffinity_np +and +.Fn pthread_getaffinity_np +functions. +.Sh RETURN VALUES +The +.Fn pthread_setaffinity_np +and +.Fn pthread_getaffinity_np +functions return 0 on success. +Otherwise, an error number is returned to indicate the error. +.Sh EXAMPLES +An example of code fragment, which sets the affinity for the current +thread to the CPU whose ID is 0: +.Bd -literal + cpuset_t *cset; + pthread_t pth; + cpuid_t ci; + int error; + + cset = cpuset_create(); + if (cset == NULL) { + err(EXIT_FAILURE, "cpuset_create"); + } + ci = 0; + cpuset_set(ci, cset); + + pth = pthread_self(); + error = pthread_setaffinity_np(pth, cpuset_size(cset), cset); + if (error) { + errc(EXIT_FAILURE, error, "pthread_setaffinity_np failed"); + } + cpuset_destroy(cset); +.Ed +.Sh COMPATIBILITY +Both functions are non-standard extensions. +.Sh ERRORS +Both functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified +.Fa set +was invalid. +.It Bq Er EPERM +The calling process lacks the appropriate privileges to perform +the operation. +.It Bq Er ESRCH +No thread could be found corresponding to the one specified by +.Fa thread . +.El +.Sh NOTES +There is an alternative processor sets interface, see +.Xr pset 3 . +However, thread affinity and processor sets are mutually exclusive, +hence mixing of these interfaces is prohibited. +.Sh SEE ALSO +.Xr cpuset 3 , +.Xr pset 3 , +.Xr pthread_getschedparam 3 , +.Xr pthread_setschedparam 3 , +.Xr sched 3 , +.Xr schedctl 8 diff --git a/static/netbsd/man3/aio.3 b/static/netbsd/man3/aio.3 new file mode 100644 index 00000000..af1abf37 --- /dev/null +++ b/static/netbsd/man3/aio.3 @@ -0,0 +1,348 @@ +.\" $NetBSD: aio.3,v 1.5 2010/05/19 06:35:20 jruoho Exp $ $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 19, 2010 +.Dt AIO 3 +.Os +.Sh NAME +.Nm aio +.Nd asynchronous I/O (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Sh DESCRIPTION +The +.St -p1003.1-2001 +standard defines an interface for asynchronous input and output. +Although in +.Nx +this is provided as part of the +.Lb librt , +the implementation largely resides in the kernel. +.Ss Rationale +The rationale can be roughly summarized with the following points. +.Bl -enum -offset 2n +.It +To increase performance by providing a mechanism to carry out +.Tn I/O +without blocking. +Theoretically, if +.Tn I/O +would never block, +neither at the software nor at the hardware level, +the overhead of +.Tn I/O +would become zero, and processes would no longer be +.Tn I/O +bound. +.It +To segregate the different +.Tn I/O +operations into logically distinctive procedures. +Unlike with the standard +.Xr stdio 3 , +the +.Nm +interface separates queuing and submitting +.Tn I/O +operations to the kernel, and +receiving notifications of operation completion from the kernel. +.It +To provide an uniform and standardized framework for asynchronous +.Tn I/O . +For instance, +.Nm +avoids the need for (and the overhead of) extra worker threads +sometimes used to perform asynchronous +.Tn I/O . +.El +.Ss Asynchronous I/O Control Block +The Asynchronous I/O Control Block is the basic operational unit behind +.Nm . +This is required since an arbitrary number of operations can be started +at once, and because each operation can be either input or output. +This block is represented by the +.Em aiocb +structure, which is defined in the +.In aio.h +header. +The following fields are available for user applications: +.Bd -literal -offset indent +off_t aio_offset; +void *aio_buf; +size_t aio_nbytes; +int aio_fildes; +int aio_lio_opcode; +int aio_reqprio; +struct sigevent aio_sigevent; +.Ed +.Pp +The fields are: +.Bl -enum -offset indent +.It +The +.Va aio_offset +specifies the implicit file offset at which the +.Tn I/O +operations are performed. +This cannot be expected to be the actual read/write offset of the +file descriptor. +.It +The +.Va aio_buf +member is a pointer to the buffer to which data is going to be written or +to which the read operation stores data. +.It +The +.Va aio_nbytes +specifies the length of +.Va aio_buf . +.It +The +.Va aio_fildes +specifies the used file descriptor. +.It +The +.Va aio_lio_opcode +is used by the +.Fn lio_listio +function to initialize a list of +.Tn I/O +requests with a single call. +.It +The +.Va aio_reqprio +member can be used to lower the scheduling priority of an +.Nm +operation. +This is only available if +.Dv _POSIX_PRIORITIZED_IO +and +.Dv _POSIX_PRIORITY_SCHEDULING +are defined, and the associated file descriptor supports it. +.It +The +.Va aio_sigevent +member is used to specify how the calling process is notified once an +.Nm +operation completes. +.El +.Pp +The members +.Va aio_buf , +.Va aio_fildes , +and +.Va aio_nbytes +are conceptually similar to the parameters +.Sq buf , +.Sq fildes , +and +.Sq nbytes +used in the standard +.Xr read 2 +and +.Xr write 2 +functions. +For example, the caller can read +.Va aio_nbytes +from a file associated with the file descriptor +.Va aio_fildes +into the buffer +.Va aio_buf . +All appropriate fields should be initialized by the caller before +.Fn aio_read +or +.Fn aio_write +is called. +.Ss File Offsets +Asynchronous +.Tn I/O +operations are not strictly sequential; +operations are carried out in arbitrary order and more than one +operation for one file descriptor can be started. +The requested read or write operation starts +from the absolute position specified by +.Va aio_offset , +as if +.Xr lseek 2 +would have been called with +.Dv SEEK_SET +immediately prior to the operation. +The +.Tn POSIX +standard does not specify what happens after an +.Nm +operation has been successfully completed. +Depending on the implementation, +the actual file offset may or may not be updated. +.Ss Errors and Completion +Asynchronous +.Tn I/O +operations are said to be complete when: +.Bl -bullet -offset 2n +.It +An error is detected. +.It +The +.Tn I/O +transfer is performed successfully. +.It +The operation is canceled. +.El +.Pp +If an error condition is detected that prevents +an operation from being started, the request is not enqueued. +In this case the read and write functions, +.Fn aio_read +and +.Fn aio_write , +return immediately, setting the global +.Va errno +to indicate the cause of the error. +.Pp +After an operation has been successfully enqueued, +.Fn aio_error +and +.Fn aio_return +must be used to determine the status of the operation and to determine +any error conditions. +This includes the conditions reported by the standard +.Xr read 2 , +.Xr write 2 , +and +.Xr fsync 2 . +The request remains enqueued and consumes process and +system resources until +.Fn aio_return +is called. +.Ss Waiting for Completion +The +.Nm +interface supports both polling and notification models. +The first can be implemented by simply repeatedly calling the +.Fn aio_error +function to test the status of an operation. +Once the operation has completed, +.Fn aio_return +is used to free the +.Va aiocb +structure for re-use. +.Pp +The notification model is implemented by using the +.Va aio_sigevent +member of the Asynchronous I/O Control Block. +The operational model and the used structure are described in +.Xr sigevent 3 . +.Pp +The +.Fn aio_suspend +function can be used to wait for the completion of one or more operations. +It is possible to set a timeout so that the process can continue the +execution and take recovery actions if the +.Nm +operations do not complete as expected. +.Ss Cancellation and Synchronization +The +.Fn aio_cancel +function can be used to request cancellation of an asynchronous +.Tn I/O +operation. +Note however that not all of them can be canceled. +The same +.Va aiocb +used to start the operation may be used as a handle for identification. +It is also possible to request cancellation of all operations pending +for a file. +.Pp +Comparable to +.Xr fsync 2 , +the +.Fn aio_fsync +function can be used to synchronize the contents of +permanent storage when multiple asynchronous +.Tn I/O +operations are outstanding for the file or device. +The synchronization operation includes only those requests that have +already been successfully enqueued. +.Sh FUNCTIONS +The following functions comprise the +.Tn API +of the +.Nm +interface: +.Bl -column -offset indent "aio_suspend " "XXX" +.It Sy Function Ta Sy Description +.It Xr aio_cancel 3 Ta cancel an outstanding asynchronous I/O operation +.It Xr aio_error 3 Ta retrieve error status of asynchronous I/O operation +.It Xr aio_fsync 3 Ta asynchronous data synchronization of file +.It Xr aio_read 3 Ta asynchronous read from a file +.It Xr aio_return 3 Ta get return status of asynchronous I/O operation +.It Xr aio_suspend 3 Ta suspend until operations or timeout complete +.It Xr aio_write 3 Ta asynchronous write to a file +.It Xr lio_listio 3 Ta list directed I/O +.El +.Sh COMPATIBILITY +Unfortunately, the +.Tn POSIX +asynchronous +.Tn I/O +implementations vary slightly. +Some implementations provide a slightly different +.Tn API +with possible extensions. +For instance, the +.Fx +implementation uses a function +.Sq Fn aio_waitcomplete +to wait for the next completion of an +.Nm aio +request. +.Sh STANDARDS +The +.Nm +interface is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 5.0 . +.Sh CAVEATS +Few limitations can be mentioned: +.Bl -bullet +.It +Undefined behavior results if simultaneous asynchronous operations +use the same Asynchronous I/O Control Block. +.It +When an asynchronous read operation is outstanding, +undefined behavior may follow if the contents of +.Va aiocb +are altered, or if memory associated with the structure, or the +.Va aio_buf +buffer, is deallocated. +.El diff --git a/static/netbsd/man3/aio_cancel.3 b/static/netbsd/man3/aio_cancel.3 new file mode 100644 index 00000000..187fa50d --- /dev/null +++ b/static/netbsd/man3/aio_cancel.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: aio_cancel.3,v 1.5 2010/09/15 07:28:46 yamt Exp $ +.\" +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_cancel.2,v 1.22 2003/01/13 10:37:11 tjr Exp $ +.\" +.Dd May 17, 2010 +.Dt AIO_CANCEL 3 +.Os +.Sh NAME +.Nm aio_cancel +.Nd cancel an outstanding asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_cancel "int fildes" "struct aiocb * aiocbp" +.Sh DESCRIPTION +The +.Fn aio_cancel +system call cancels the outstanding asynchronous +I/O request for the file descriptor specified in +.Fa fildes . +If +.Fa aiocbp +is specified, only that specific asynchronous I/O request is cancelled. +.Pp +Normal asynchronous notification occurs for cancelled requests. +Requests complete with an error result of +.Er ECANCELED . +.Sh RETURN VALUES +The +.Fn aio_cancel +system call returns \-1 to indicate an error, or one of the following: +.Bl -tag -width Er +.It Bq Dv AIO_CANCELED +All outstanding requests meeting the criteria specified were cancelled. +.It Bq Dv AIO_NOTCANCELED +Some requests were not cancelled, status for the requests should be +checked with +.Xr aio_error 3 . +.It Bq Dv AIO_ALLDONE +All of the requests meeting the criteria have finished. +.El +.Sh ERRORS +An error return from +.Fn aio_cancel +indicates: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument is an invalid file descriptor. +.El +.Sh SEE ALSO +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_cancel +system call is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_cancel +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_error.3 b/static/netbsd/man3/aio_error.3 new file mode 100644 index 00000000..5ba7bbeb --- /dev/null +++ b/static/netbsd/man3/aio_error.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: aio_error.3,v 1.4 2010/05/17 19:22:31 jruoho Exp $ +.\" +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_error.2,v 1.20 2006/09/26 09:47:46 vd Exp $ +.\" +.Dd May 17, 2010 +.Dt AIO_ERROR 3 +.Os +.Sh NAME +.Nm aio_error +.Nd retrieve error status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_error "const struct aiocb *aiocbp" +.Sh DESCRIPTION +The +.Fn aio_error +system call returns the error status of the asynchronous I/O request +associated with the structure pointed to by +.Fa aiocbp . +.Sh RETURN VALUES +If the asynchronous I/O request has completed successfully, +.Fn aio_error +returns 0. +If the request has not yet completed, +.Er EINPROGRESS +is returned. +If the request has completed unsuccessfully the error +status is returned as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_error +returns \-1 and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_error +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa aiocb +argument +does not reference an outstanding asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_error +system call +is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_error +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_fsync.3 b/static/netbsd/man3/aio_fsync.3 new file mode 100644 index 00000000..51cccc35 --- /dev/null +++ b/static/netbsd/man3/aio_fsync.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: aio_fsync.3,v 1.8 2017/07/03 21:32:51 wiz Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 17, 2010 +.Dt AIO_FSYNC 3 +.Os +.Sh NAME +.Nm aio_fsync +.Nd asynchronous data synchronization of file (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_fsync "int op" "struct aiocb *aiocbp" +.Sh DESCRIPTION +The +.Fn aio_fsync +system call allows the calling process to force all modified data +associated with the file descriptor +.Fa aiocbp->aio_fildes +to be flushed to the stable storage device. +The call returns immediately after the synchronization request has been +enqueued to the descriptor; the synchronization may or may not have +completed at the time the call returns. +If the request could not be enqueued, generally due to invalid arguments, +the call returns without having enqueued the request. +.Pp +The +.Fa op +argument could be set only to +.Dv O_DSYNC +or +.Dv O_SYNC . +If +.Fa op +is +.Dv O_DSYNC , +then +.Fn aio_fsync +does the same as a +.Fn fdatasync +call, if +.Dv O_SYNC , +then the same as +.Fn fsync . +.Pp +If +.Dv _POSIX_PRIORITIZED_IO +is defined, and the descriptor supports it, then the enqueued +operation is submitted at a priority equal to that of the calling +process minus +.Fa aiocbp->aio_reqprio . +.Pp +The +.Fa aiocbp +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Sh RETURN VALUES +.Rv -std aio_fsync +.Sh ERRORS +The +.Fn aio_fsync +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_fsync +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, +.Fn aio_fsync +returns \-1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return \-1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa aiocbp->aio_fildes +is invalid for writing. +.It Bq Er EINVAL +This implementation does not support synchronized I/O for this file, +or the +.Fa op +argument is neither set to +.Dv O_DSYNC +nor +.Dv O_SYNC . +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr fdatasync 2 , +.Xr fsync 2 , +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_fsync +system call is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_fsync +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_read.3 b/static/netbsd/man3/aio_read.3 new file mode 100644 index 00000000..e1b627cd --- /dev/null +++ b/static/netbsd/man3/aio_read.3 @@ -0,0 +1,199 @@ +.\" $NetBSD: aio_read.3,v 1.6 2022/12/04 01:29:33 uwe Exp $ +.\" +.\" Copyright (c) 1998 Terry Lambert +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_read.2,v 1.23 2005/12/13 13:43:35 davidxu Exp $ +.\" +.Dd May 17, 2010 +.Dt AIO_READ 3 +.Os +.Sh NAME +.Nm aio_read +.Nd asynchronous read from a file (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_read "struct aiocb *aiocbp" +.Sh DESCRIPTION +The +.Fn aio_read +system call allows the calling process to read +.Fa aiocbp->aio_nbytes +from the descriptor +.Fa aiocbp->aio_fildes +beginning at the offset +.Fa aiocbp->aio_offset +into the buffer pointed to by +.Fa aiocbp->aio_buf . +The call returns immediately after the read request has +been enqueued to the descriptor; the read may or may not have +completed at the time the call returns. +.Pp +If +.Dv _POSIX_PRIORITIZED_IO +is defined, and the descriptor supports it, +then the enqueued operation is submitted at a priority equal to that +of the calling process minus +.Fa aiocbp->aio_reqprio . +.Pp +The +.Fa aiocbp->aio_lio_opcode +argument +is ignored by the +.Fn aio_read +system call. +.Pp +The +.Fa aiocbp +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +then the call returns without having enqueued the request. +.Pp +If the request is successfully enqueued, the value of +.Fa aiocbp->aio_offset +can be modified during the request as context, so this value must +not be referenced after the request is enqueued. +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa aiocbp +and the buffer that the +.Fa aiocbp->aio_buf +member of that structure references must remain valid until the +operation has completed. +For this reason, use of auto (stack) variables +for these objects is discouraged. +.Pp +The asynchronous I/O control buffer +.Fa aiocbp +should be zeroed before the +.Fn aio_read +call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents after the request has been enqueued, but before the +request has completed, are not allowed. +.Pp +If the file offset in +.Fa aiocbp->aio_offset +is past the offset maximum for +.Fa aiocbp->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_read +.Sh ERRORS +The +.Fn aio_read +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_read +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +.Fn aio_read +returns \-1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return \-1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Pp +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa aiocbp->aio_fildes +argument +is invalid. +.It Bq Er EINVAL +The offset +.Fa aiocbp->aio_offset +is not valid, the priority specified by +.Fa aiocbp->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa aiocbp->aio_nbytes +is not valid. +.It Bq Er EOVERFLOW +The file is a regular file, +.Fa aiocbp->aio_nbytes +is greater than zero, the starting offset in +.Fa aiocbp->aio_offset +is before the end of the file, but is at or beyond the +.Fa aiocbp->aio_fildes +offset maximum. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr read 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa aiocbp->aio_fildes +argument +is invalid for reading. +.It Bq Er ECANCELED +The request was explicitly cancelled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa aiocbp->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr siginfo 2 , +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_read +system call is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_read +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_return.3 b/static/netbsd/man3/aio_return.3 new file mode 100644 index 00000000..339a2733 --- /dev/null +++ b/static/netbsd/man3/aio_return.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: aio_return.3,v 1.5 2011/08/13 11:10:31 jmcneill Exp $ +.\" +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_return.2,v 1.19 2006/10/07 10:49:20 trhodes Exp $ +.\" +.Dd August 13, 2011 +.Dt AIO_RETURN 3 +.Os +.Sh NAME +.Nm aio_return +.Nd retrieve return status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft ssize_t +.Fn aio_return "struct aiocb *aiocbp" +.Sh DESCRIPTION +The +.Fn aio_return +system call returns the final status of the asynchronous I/O request +associated with the structure pointed to by +.Fa aiocbp . +.Pp +The +.Fn aio_return +system call +should only be called once, to obtain the final status of an asynchronous +I/O operation once it has completed +.Po Xr aio_error 3 +returns something other than +.Er EINPROGRESS Pc . +.Sh RETURN VALUES +If the asynchronous I/O request has completed, the status is returned +as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +Otherwise, +.Fn aio_return +returns \-1 and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_return +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa aiocbp +argument +does not reference a completed asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_return +system call +is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_return +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_suspend.3 b/static/netbsd/man3/aio_suspend.3 new file mode 100644 index 00000000..93503c72 --- /dev/null +++ b/static/netbsd/man3/aio_suspend.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: aio_suspend.3,v 1.5 2011/01/06 15:22:20 njoly Exp $ +.\" +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_suspend.2,v 1.22 2004/12/23 23:45:25 keramida Exp $ +.\" +.Dd May 17, 2010 +.Dt AIO_SUSPEND 3 +.Os +.Sh NAME +.Nm aio_suspend +.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_suspend "const struct aiocb * const list[]" "int nent" "const struct timespec * timeout" +.Sh DESCRIPTION +The +.Fn aio_suspend +system call suspends the calling process until at least one of the +specified asynchronous I/O requests have completed, a signal is +delivered, or the +.Fa struct timeout +(see +.Xr timespec 3 ) +has passed. +.Pp +The +.Fa list +argument +is an array of +.Fa nent +pointers to asynchronous I/O requests. +Array members containing +.Dv NULL +pointers will be silently ignored. +.Pp +If +.Fa timeout +is not a +.Dv NULL +pointer, it specifies a maximum interval to suspend. +If +.Fa timeout +is a +.Dv NULL +pointer, the suspend blocks indefinitely. +To effect a poll, the +.Fa timeout +should point to a zero-value timespec structure. +.Sh RETURN VALUES +If one or more of the specified asynchronous I/O requests have +completed, +.Fn aio_suspend +returns 0. +Otherwise it returns \-1 and sets +.Va errno +to indicate the error, as enumerated below. +.Sh ERRORS +The +.Fn aio_suspend +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Fa timeout +expired before any I/O requests completed. +.It Bq Er EINTR +The suspend was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa list +argument +contains more than +.Dv AIO_LISTIO_MAX +asynchronous I/O requests, or at least one of the requests is not +valid. +.El +.Sh SEE ALSO +.Xr aio 3 , +.Xr timespec 3 +.Sh STANDARDS +The +.Fn aio_suspend +system call +is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_suspend +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/aio_write.3 b/static/netbsd/man3/aio_write.3 new file mode 100644 index 00000000..0831971c --- /dev/null +++ b/static/netbsd/man3/aio_write.3 @@ -0,0 +1,196 @@ +.\" $NetBSD: aio_write.3,v 1.5 2017/07/03 21:32:51 wiz Exp $ +.\" +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_write.2,v 1.20 2005/12/13 13:43:35 davidxu Exp $ +.\" +.Dd May 17, 2010 +.Dt AIO_WRITE 3 +.Os +.Sh NAME +.Nm aio_write +.Nd asynchronous write to a file (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_write "struct aiocb *aiocbp" +.Sh DESCRIPTION +The +.Fn aio_write +system call allows the calling process to write +.Fa aiocbp->aio_nbytes +from the buffer pointed to by +.Fa aiocbp->aio_buf +to the descriptor +.Fa aiocbp->aio_fildes . +The call returns immediately after the write request has been enqueued +to the descriptor; the write may or may not have completed at the time +the call returns. +If the request could not be enqueued, generally due +to invalid arguments, the call returns without having enqueued the +request. +.Pp +If +.Dv O_APPEND +is set for +.Fa aiocbp->aio_fildes , +.Fn aio_write +operations append to the file in the same order as the calls were +made. +If +.Dv O_APPEND +is not set for the file descriptor, the write operation will occur at +the absolute position from the beginning of the file plus +.Fa aiocbp->aio_offset . +.Pp +If +.Dv _POSIX_PRIORITIZED_IO +is defined, and the descriptor supports it, then the enqueued +operation is submitted at a priority equal to that of the calling +process minus +.Fa aiocbp->aio_reqprio . +.Pp +The +.Fa aiocbp +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request is successfully enqueued, the value of +.Fa aiocbp->aio_offset +can be modified during the request as context, so this value must not +be referenced after the request is enqueued. +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa aiocbp +and the buffer that the +.Fa aiocbp->aio_buf +member of that structure references must remain valid until the +operation has completed. +For this reason, use of auto (stack) variables +for these objects is discouraged. +.Pp +The asynchronous I/O control buffer +.Fa aiocbp +should be zeroed before the +.Fn aio_write +system call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents after the request has been enqueued, but before the +request has completed, are not allowed. +.Pp +If the file offset in +.Fa aiocbp->aio_offset +is past the offset maximum for +.Fa aiocbp->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_write +.Sh ERRORS +The +.Fn aio_write +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_write +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +.Fn aio_write +returns \-1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return \-1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Pp +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa aiocbp->aio_fildes +argument +is invalid, or is not opened for writing. +.It Bq Er EINVAL +The offset +.Fa aiocbp->aio_offset +is not valid, the priority specified by +.Fa aiocbp->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa aiocbp->aio_nbytes +is not valid. +.El +.Pp +If the request is successfully enqueued, but subsequently canceled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr write 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr write 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa aiocbp->aio_fildes +argument +is invalid for writing. +.It Bq Er ECANCELED +The request was explicitly canceled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa aiocbp->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr siginfo 2 , +.Xr aio 3 +.Sh STANDARDS +The +.Fn aio_write +system call +is expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn aio_write +system call first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/alarm.3 b/static/netbsd/man3/alarm.3 new file mode 100644 index 00000000..4eba8834 --- /dev/null +++ b/static/netbsd/man3/alarm.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: alarm.3,v 1.22 2003/08/07 16:42:45 agc Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)alarm.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd April 19, 1994 +.Dt ALARM 3 +.Os +.Sh NAME +.Nm alarm +.Nd set signal timer alarm +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft unsigned int +.Fn alarm "unsigned int seconds" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr setitimer 2 . +.Ef +.Pp +The +.Fn alarm +function sets a timer to deliver the signal +.Dv SIGALRM +to the calling process +.Ar seconds +after the call to +.Fn alarm . +If an alarm has already been set with +.Fn alarm +but has not been delivered, another call to +.Fn alarm +will supersede the prior call. +The request +.Fn alarm "0" +voids the current +alarm and the signal SIGALRM will not be delivered. +The maximum number of +.Ar seconds +allowed +is 2147483647. +.Pp +The return value of +.Fn alarm +is the amount of time left on the timer from a previous call to +.Fn alarm . +If no alarm is currently set, the return value is 0. +If there is an error setting the timer, +.Fn alarm +returns ((unsigned int) -1). +.Sh SEE ALSO +.Xr setitimer 2 , +.Xr sigaction 2 , +.Xr sigsuspend 2 , +.Xr signal 3 , +.Xr sigvec 3 , +.Xr sleep 3 , +.Xr ualarm 3 , +.Xr usleep 3 +.Sh STANDARDS +The +.Fn alarm +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +An +.Fn alarm +function appeared in +.At v7 . diff --git a/static/netbsd/man3/alloca.3 b/static/netbsd/man3/alloca.3 new file mode 100644 index 00000000..1e680250 --- /dev/null +++ b/static/netbsd/man3/alloca.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: alloca.3,v 1.16 2012/10/24 22:56:27 wiz Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)alloca.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd October 24, 2012 +.Dt ALLOCA 3 +.Os +.Sh NAME +.Nm alloca +.Nd memory allocator +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn alloca "size_t size" +.Sh DESCRIPTION +The +.Fn alloca +function +allocates +.Fa size +bytes of space in the stack frame of the caller. +This temporary space is automatically freed on +return. +.Sh RETURN VALUES +The +.Fn alloca +function returns a pointer to the beginning of the allocated space. +If the allocation failed, a +.Dv NULL +pointer is returned. +.Sh SEE ALSO +.Xr cc 1 , +.Xr brk 2 , +.Xr calloc 3 , +.Xr getpagesize 3 , +.Xr malloc 3 , +.Xr realloc 3 , +.Xr security 7 +.Sh CAVEATS +Few limitations can be mentioned: +.Bl -bullet +.It +The +.Fn alloca +function is not part of any C standard and its use is not portable. +.It +The +.Fn alloca +function should be supplied by the compiler because the compiler is allowed to +make assumptions about the stack and frame pointers. +The libc +.Fn alloca +implementation cannot account for those assumptions. +While there is a +machine dependent implementation of +.Fn alloca +in libc, its use is discouraged and in most cases it will not work. +Using this implementation will produce linker warnings. +.It +The +.Fn alloca +function is unsafe because it cannot ensure that the pointer +returned points to a valid and usable block of memory. +The allocation made may exceed the bounds of the stack, or even go +further into other objects in memory, and +.Fn alloca +cannot determine such an error. +For that all +.Fn alloca +allocations should be bounded and limited to a small size. +.It +Since +.Fn alloca +modifies the stack at runtime and the stack usage of each function frame +cannot be predicted, it makes many compiler security features +(such as +.Xr cc 1 +.Fl fstack-protector ) +useless for the calling function. +See +.Xr security 7 +for a discussion. +.El +.\" .Sh HISTORY +.\" The +.\" .Fn alloca +.\" function appeared in +.\" .Bx ?? . +.\" The function appeared in 32v, pwb and pwb.2 and in 3bsd 4bsd +.\" The first man page (or link to a man page that I can find at the +.\" moment is 4.3... diff --git a/static/netbsd/man3/apropos-utils.3 b/static/netbsd/man3/apropos-utils.3 new file mode 100644 index 00000000..bafc102d --- /dev/null +++ b/static/netbsd/man3/apropos-utils.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: apropos-utils.3,v 1.5 2022/09/11 20:32:37 gutteridge Exp $ +.\" +.\" Copyright (c) 2011 Abhinav Upadhyay +.\" All rights reserved. +.\" +.\" This code was developed as part of Google's Summer of Code 2011 program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 23, 2016 +.Dt APROPOS-UTILS 3 +.Os +.Sh NAME +.Nm apropos-utils +.Nd support functions for querying the man page index +.Sh SYNOPSIS +.In apropos-utils.h +.Ft sqlite3 * +.Fn init_db "mandb_access_mode db_flag" "const char * manconf" +.Ft void +.Fn close_db "sqlite3 *db" +.Ft int +.Fn run_query "sqlite3 *db" "query_format fmt" "query_args *args" +.Sh DESCRIPTION +These functions all live in the +.Pa apropos-utils.h +header file. +They operate on +.Pa /var/db/man.db +which is an SQLite database containing a full text search index of the manual +pages. +The functions provide an easy to use interface to query the database and +develop applications on top of it. +.Sh SEE ALSO +.Xr close_db 3 , +.Xr init_db 3 , +.Xr run_query 3 +.Sh AUTHORS +.An Abhinav Upadhyay diff --git a/static/netbsd/man3/arc4random.3 b/static/netbsd/man3/arc4random.3 new file mode 100644 index 00000000..27fa8fb7 --- /dev/null +++ b/static/netbsd/man3/arc4random.3 @@ -0,0 +1,332 @@ +.\" $NetBSD: arc4random.3,v 1.23 2024/08/28 14:39:16 riastradh Exp $ +.\" +.\" Copyright (c) 2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 27, 2024 +.Dt ARC4RANDOM 3 +.Os +.Sh NAME +.Nm arc4random , +.Nm arc4random_uniform , +.Nm arc4random_buf , +.Nm arc4random_stir , +.Nm arc4random_addrandom +.Nd random number generator +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft uint32_t +.Fn arc4random "void" +.Ft uint32_t +.Fn arc4random_uniform "uint32_t bound" +.Ft void +.Fn arc4random_buf "void *buf" "size_t len" +.Ft void +.Fn arc4random_stir "void" +.Ft void +.Fn arc4random_addrandom "unsigned char *buf" "int len" +.Sh DESCRIPTION +The +.Nm +family of functions provides a cryptographic pseudorandom number +generator automatically seeded from the system entropy pool and safe to +use from multiple threads. +.Nm +is designed to prevent an adversary from guessing outputs, +unlike +.Xr rand 3 +and +.Xr random 3 , +and is faster and more convenient than reading from +.Pa /dev/urandom +directly. +.Pp +.Fn arc4random +returns an integer in [0, 2^32) chosen independently with uniform +distribution. +.Pp +.Fn arc4random_uniform +returns an integer in [0, +.Fa bound ) +chosen independently with uniform distribution. +.Pp +.Fn arc4random_buf +stores +.Fa len +bytes into the memory pointed to by +.Fa buf , +each byte chosen independently from [0, 256) with uniform +distribution. +.Pp +.Fn arc4random_stir +draws entropy from the operating system and incorporates it into the +library's PRNG state to influence future outputs. +.Pp +.Fn arc4random_addrandom +incorporates +.Fa len +bytes, which must be nonnegative, from the buffer +.Fa buf , +into the library's PRNG state to influence future outputs. +.Pp +It is not necessary for an application to call +.Fn arc4random_stir +or +.Fn arc4random_addrandom +before calling other +.Nm +functions. +The first call to any +.Nm +function will initialize the PRNG state unpredictably from the system +entropy pool. +.Sh SECURITY MODEL +The +.Nm +functions provide the following security properties against three +different classes of attackers, assuming enough entropy is provided by +the operating system: +.Bl -enum -offset abcd +.It +An attacker who has seen some outputs of any of the +.Nm +functions cannot predict past or future unseen outputs. +.It +An attacker who has seen the library's PRNG state in memory cannot +predict past outputs. +.It +An attacker who has seen one process's PRNG state cannot predict past +or future outputs in other processes, particularly its parent or +siblings. +.El +.Pp +One +.Sq output +means the result of any single request to an +.Nm +function, no matter how short it is. +.Pp +The second property is sometimes called +.Sq forward secrecy , +.Sq backtracking resistance , +or +.Sq key erasure after each output . +.Sh IMPLEMENTATION NOTES +The +.Nm +functions are currently implemented using the ChaCha20 pseudorandom +function family. +For any 32-byte string +.Fa s , +.Pf ChaCha20_ Fa s +is a function from 16-byte strings to 64-byte strings. +It is conjectured that if +.Fa s +is chosen with uniform distribution, then the distribution on +.Pf ChaCha20_ Fa s +is indistinguishable to a computationally bounded adversary from a +uniform distribution on all functions from 16-byte strings to 64-byte +strings. +.Pp +The PRNG state is a 32-byte ChaCha20 key +.Fa s . +Each request to +an +.Nm +function +.Bl -bullet -offset abcd -compact +.It +computes the 64-byte quantity +.Fa x += +.Pf ChaCha20_ Fa s Ns Pq 0 , +.It +splits +.Fa x +into two 32-byte quantities +.Fa s' +and +.Fa k , +.It +replaces +.Fa s +by +.Fa s' , +and +.It +uses +.Fa k +as output. +.El +.Pp +.Fn arc4random +yields the first four bytes of +.Fa k +as output directly. +.Fn arc4random_buf +either yields up to 32 bytes of +.Fa k +as output directly, or, for longer +requests, uses +.Fa k +as a ChaCha20 key and yields the concatenation +.Pf ChaCha20_ Fa k Ns Pq 0 +|| +.Pf ChaCha20_ Fa k Ns Pq 1 +|| ... as output. +.Fn arc4random_uniform +repeats +.Fn arc4random +until it obtains an integer in [2^32 % +.Fa bound , +2^32), and reduces that modulo +.Fa bound . +.Pp +The PRNG state is per-thread, unless memory allocation fails inside the +library, in which case some threads may share global PRNG state with a +mutex. +The global PRNG state is zeroed on fork in the parent via +.Xr pthread_atfork 3 , +and the per-thread PRNG state is zeroed on fork in the child via +.Xr minherit 2 +with +.Dv MAP_INHERIT_ZERO , +so that the child cannot reuse or see the parent's PRNG state. +The PRNG state is reseeded automatically from the system entropy pool +on the first use of an +.Nm +function after zeroing. +.Pp +The first use of an +.Nm +function may abort the process in the highly unlikely event that +library initialization necessary to implement the security model fails. +Additionally, +.Fn arc4random_stir +and +.Fn arc4random_addrandom +may abort the process in the highly unlikely event that the operating +system fails to provide entropy. +.Pp +If +.Nm +detects that the sysctl variable +.Li kern.entropy.epoch +.Pq see Xr rnd 4 +has changed since its last output, it reseeds itself with additional +data from the system entropy pool again before generating its next +output. +.Sh SEE ALSO +.Xr rand 3 , +.Xr random 3 , +.Xr rnd 4 , +.Xr cprng 9 +.Rs +.%A Daniel J. Bernstein +.%T ChaCha, a variant of Salsa20 +.%D 2008-01-28 +.%O Document ID: 4027b5256e17b9796842e6d0f68b0b5e +.%U http://cr.yp.to/papers.html#chacha +.Re +.Sh BUGS +There is no way to get deterministic, reproducible results out of +.Nm +for testing purposes. +.Pp +The name +.Sq arc4random +was chosen for hysterical raisins \(em it was originally implemented +using the RC4 stream cipher, which has been known since shortly after +it was published in 1994 to have observable biases in the output, and +is now known to be broken badly enough to admit practical attacks in +the real world. +.\" Bob Jenkins, sci.crypt post dated 1994-09-16, message-id +.\" <359qjg$55v$1@mhadg.production.compuserve.com>, +.\" https://groups.google.com/d/msg/sci.crypt/JsO3xEATGFA/-wO4ttv7BCYJ +.\" +.\" Andrew Roos, `A Class of Weak Keys in the RC4 Stream Cipher', +.\" sci.crypt posts dated 1995-09-22, message-ids +.\" <43u1eh$1j3@hermes.is.co.za> and <44ebge$llf@hermes.is.co.za>. +.\" +.\" Paul Crowley, `Small bias in RC4 experimentally verified', March +.\" 1998, http://www.ciphergoth.org/crypto/rc4/ +Unfortunately, the library found widespread adoption and the name stuck +before anyone recognized that it was silly. +.Pp +The signature of +.Fn arc4random_addrandom +is silly. +There is no reason to require casts or accept negative lengths: +it should take a +.Vt void * +buffer and a +.Vt size_t +length. +But it's too late to change that now. +.Pp +.Fn arc4random_uniform +does not help to choose integers in [0, +.Fa n ) +uniformly at random when +.Fa n +> 2^32. +.Pp +The security model of +.Nm +is stronger than many applications need, and stronger than other +operating systems provide. +For example, applications encrypting messages with random, but not +secret, initialization vectors need only prevent an adversary from +guessing future outputs, since past outputs will have been published +already. +.Pp +On the one hand, +.Nm +could be marginally faster if it were not necessary to prevent an +adversary who sees the state from predicting past outputs. +On the other hand, there are applications in the wild that use +.Nm +to generate key material, such as OpenSSH, so for the sake of +.Nx +users it would be imprudent to weaken the security model. +On the third hand, relying on the security model of +.Nm +in +.Nx +may lead you to an unpleasant surprise on another operating system +whose implementation of +.Nm +has a weaker security model. +.Pp +One may be tempted to create new APIs to accommodate different +security models and performance constraints without unpleasant +surprises on different operating systems. +This should not be done lightly, though, because there are already too +many different choices, and too many opportunities for programmers to +reach for one and pick the wrong one. diff --git a/static/netbsd/man3/archive_entry.3 b/static/netbsd/man3/archive_entry.3 new file mode 100644 index 00000000..0fc0f8cc --- /dev/null +++ b/static/netbsd/man3/archive_entry.3 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY 3 +.Os +.Sh NAME +.Nm archive_entry_clear , +.Nm archive_entry_clone , +.Nm archive_entry_free , +.Nm archive_entry_new +.Nd functions for managing archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft "struct archive_entry *" +.Fn archive_entry_clear "struct archive_entry *" +.Ft struct archive_entry * +.Fn archive_entry_clone "struct archive_entry *" +.Ft void +.Fn archive_entry_free "struct archive_entry *" +.Ft struct archive_entry * +.Fn archive_entry_new "void" +.Sh DESCRIPTION +These functions create and manipulate data objects that +represent entries within an archive. +You can think of a +.Tn struct archive_entry +as a heavy-duty version of +.Tn struct stat : +it includes everything from +.Tn struct stat +plus associated pathname, textual group and user names, etc. +These objects are used by +.Xr libarchive 3 +to represent the metadata associated with a particular +entry in an archive. +.Ss Create and Destroy +There are functions to allocate, destroy, clear, and copy +.Va archive_entry +objects: +.Bl -tag -compact -width indent +.It Fn archive_entry_clear +Erases the object, resetting all internal fields to the +same state as a newly-created object. +This is provided to allow you to quickly recycle objects +without thrashing the heap. +.It Fn archive_entry_clone +A deep copy operation; all text fields are duplicated. +.It Fn archive_entry_free +Releases the +.Tn struct archive_entry +object. +.It Fn archive_entry_new +Allocate and return a blank +.Tn struct archive_entry +object. +.El +.Ss Function groups +Due to high number of functions, the accessor functions can be found in +man pages grouped by the purpose. +.Bl -tag -width ".Xr archive_entry_perms 3" +.It Xr archive_entry_acl 3 +Access Control List manipulation +.It Xr archive_entry_paths 3 +Path name manipulation +.It Xr archive_entry_perms 3 +User, group and mode manipulation +.It Xr archive_entry_stat 3 +Functions not in the other groups and copying to/from +.Vt struct stat . +.It Xr archive_entry_time 3 +Time field manipulation +.El +.Pp +Most of the functions set or read entries in an object. +Such functions have one of the following forms: +.Bl -tag -compact -width indent +.It Fn archive_entry_set_XXXX +Stores the provided data in the object. +In particular, for strings, the pointer is stored, +not the referenced string. +.It Fn archive_entry_copy_XXXX +As above, except that the referenced data is copied +into the object. +.It Fn archive_entry_XXXX +Returns the specified data. +In the case of strings, a const-qualified pointer to +the string is returned. +.El +String data can be set or accessed as wide character strings +or normal +.Va char +strings. +The functions that use wide character strings are suffixed with +.Cm _w . +Note that these are different representations of the same data: +For example, if you store a narrow string and read the corresponding +wide string, the object will transparently convert formats +using the current locale. +Similarly, if you store a wide string and then store a +narrow string for the same data, the previously-set wide string will +be discarded in favor of the new data. +.\" .Sh EXAMPLE +.\" .Sh RETURN VALUES +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr archive_entry_acl 3 , +.Xr archive_entry_paths 3 , +.Xr archive_entry_perms 3 , +.Xr archive_entry_time 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.\" .Sh BUGS diff --git a/static/netbsd/man3/archive_entry_acl.3 b/static/netbsd/man3/archive_entry_acl.3 new file mode 100644 index 00000000..4d0d8b50 --- /dev/null +++ b/static/netbsd/man3/archive_entry_acl.3 @@ -0,0 +1,458 @@ +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" Copyright (c) 2016 Martin Matuska +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 15, 2017 +.Dt ARCHIVE_ENTRY_ACL 3 +.Os +.Sh NAME +.Nm archive_entry_acl_add_entry , +.Nm archive_entry_acl_add_entry_w , +.Nm archive_entry_acl_clear , +.Nm archive_entry_acl_count , +.Nm archive_entry_acl_from_text , +.Nm archive_entry_acl_from_text_w , +.Nm archive_entry_acl_next , +.Nm archive_entry_acl_reset , +.Nm archive_entry_acl_to_text , +.Nm archive_entry_acl_to_text_w , +.Nm archive_entry_acl_types +.Nd functions for manipulating Access Control Lists in archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft void +.Fo archive_entry_acl_add_entry +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qualifier" +.Fa "const char *name" +.Fc +.Ft void +.Fo archive_entry_acl_add_entry_w +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int permset" +.Fa "int tag" +.Fa "int qualifier" +.Fa "const wchar_t *name" +.Fc +.Ft void +.Fn archive_entry_acl_clear "struct archive_entry *a" +.Ft int +.Fn archive_entry_acl_count "struct archive_entry *a" "int type" +.Ft int +.Fo archive_entry_acl_from_text +.Fa "struct archive_entry *a" +.Fa "const char *text" +.Fa "int type" +.Fc +.Ft int +.Fo archive_entry_acl_from_text_w +.Fa "struct archive_entry *a" +.Fa "const wchar_t *text" +.Fa "int type" +.Fc +.Ft int +.Fo archive_entry_acl_next +.Fa "struct archive_entry *a" +.Fa "int type" +.Fa "int *ret_type" +.Fa "int *ret_permset" +.Fa "int *ret_tag" +.Fa "int *ret_qual" +.Fa "const char **ret_name" +.Fc +.Ft int +.Fn archive_entry_acl_reset "struct archive_entry *a" "int type" +.Ft char * +.Fo archive_entry_acl_to_text +.Fa "struct archive_entry *a" +.Fa "ssize_t *len_p" +.Fa "int flags" +.Fc +.Ft wchar_t * +.Fo archive_entry_acl_to_text_w +.Fa "struct archive_entry *a" +.Fa "ssize_t *len_p" +.Fa "int flags" +.Fc +.Ft int +.Fn archive_entry_acl_types "struct archive_entry *a" +.\" enum? +.Sh DESCRIPTION +The +.Dq Access Control Lists (ACLs) +extend the standard Unix permission model. +The ACL interface of +.Nm libarchive +supports both POSIX.1e and NFSv4 style ACLs. +Use of ACLs is restricted by +various levels of ACL support in operating systems, file systems and archive +formats. +.Ss POSIX.1e Access Control Lists +A POSIX.1e ACL consists of a number of independent entries. +Each entry specifies the permission set as a bitmask of basic permissions. +Valid permissions in the +.Fa permset +are: +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_EXECUTE" +.It Dv ARCHIVE_ENTRY_ACL_READ ( Sy r ) +.It Dv ARCHIVE_ENTRY_ACL_WRITE ( Sy w ) +.It Dv ARCHIVE_ENTRY_ACL_EXECUTE ( Sy x ) +.El +The permissions correspond to the normal Unix permissions. +.Pp +The +.Fa tag +specifies the principal to which the permission applies. +Valid values are: +.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" +.It Dv ARCHIVE_ENTRY_ACL_USER +The user specified by the name field. +.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ +The owner of the file. +.It Dv ARCHIVE_ENTRY_ACL_GROUP +The group specified by the name field. +.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ +The group which owns the file. +.It Dv ARCHIVE_ENTRY_ACL_MASK +The maximum permissions to be obtained via group permissions. +.It Dv ARCHIVE_ENTRY_ACL_OTHER +Any principal who is not the file owner or a member of the owning group. +.El +.Pp +The principals +.Dv ARCHIVE_ENTRY_ACL_USER_OBJ , +.Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ +and +.Dv ARCHIVE_ENTRY_ACL_OTHER +are equivalent to user, group and other in the classic Unix permission +model and specify non-extended ACL entries. +.Pp +All files have an access ACL +.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS . +This specifies the permissions required for access to the file itself. +Directories have an additional ACL +.Pq Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT , +which controls the initial access ACL for newly-created directory entries. +.Ss NFSv4 Access Control Lists +A NFSv4 ACL consists of multiple individual entries called Access Control +Entries (ACEs). +.Pp +There are four possible types of a NFSv4 ACE: +.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYE_ALLOW" +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALLOW +Allow principal to perform actions requiring given permissions. +.It Dv ARCHIVE_ENTRY_ACL_TYPE_DENY +Prevent principal from performing actions requiring given permissions. +.It Dv ARCHIVE_ENTRY_ACL_TYPE_AUDIT +Log access attempts by principal which require given permissions. +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALARM +Trigger a system alarm on access attempts by principal which require given +permissions. +.El +.Pp +The +.Fa tag +specifies the principal to which the permission applies. +Valid values are: +.Bl -hang -offset indent -compact -width "ARCHIVE_ENTRY_ACL_GROUP_OBJ" +.It Dv ARCHIVE_ENTRY_ACL_USER +The user specified by the name field. +.It Dv ARCHIVE_ENTRY_ACL_USER_OBJ +The owner of the file. +.It Dv ARCHIVE_ENTRY_ACL_GROUP +The group specified by the name field. +.It Dv ARCHIVE_ENTRY_ACL_GROUP_OBJ +The group which owns the file. +.It Dv ARCHIVE_ENTRY_ACL_EVERYONE +Any principal who is not the file owner or a member of the owning group. +.El +.Pp +Entries with the +.Dv ARCHIVE_ENTRY_ACL_USER +or +.Dv ARCHIVE_ENTRY_ACL_GROUP +tag store the user and group name in the +.Fa name +string and optionally the user or group ID in the +.Fa qualifier +integer. +.Pp +NFSv4 ACE permissions and flags are stored in the same +.Fa permset +bitfield. +Some permissions share the same constant and permission character +but have different effect on directories than on files. +The following ACE permissions are supported: +.Bl -tag -offset indent -compact -width ARCHIV +.It Dv ARCHIVE_ENTRY_ACL_READ_DATA ( Sy r ) +Read data (file). +.It Dv ARCHIVE_ENTRY_ACL_LIST_DIRECTORY ( Sy r ) +List entries (directory). +.It ARCHIVE_ENTRY_ACL_WRITE_DATA ( Sy w ) +Write data (file). +.It ARCHIVE_ENTRY_ACL_ADD_FILE ( Sy w ) +Create files (directory). +.It Dv ARCHIVE_ENTRY_ACL_EXECUTE ( Sy x ) +Execute file or change into a directory. +.It Dv ARCHIVE_ENTRY_ACL_APPEND_DATA ( Sy p ) +Append data (file). +.It Dv ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY ( Sy p ) +Create subdirectories (directory). +.It Dv ARCHIVE_ENTRY_ACL_DELETE_CHILD ( Sy D ) +Remove files and subdirectories inside a directory. +.It Dv ARCHIVE_ENTRY_ACL_DELETE ( Sy d ) +Remove file or directory. +.It Dv ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES ( Sy a ) +Read file or directory attributes. +.It Dv ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES ( Sy A ) +Write file or directory attributes. +.It Dv ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS ( Sy R ) +Read named file or directory attributes. +.It Dv ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS ( Sy W ) +Write named file or directory attributes. +.It Dv ARCHIVE_ENTRY_ACL_READ_ACL ( Sy c ) +Read file or directory ACL. +.It Dv ARCHIVE_ENTRY_ACL_WRITE_ACL ( Sy C ) +Write file or directory ACL. +.It Dv ARCHIVE_ENTRY_ACL_WRITE_OWNER ( Sy o ) +Change owner of a file or directory. +.It Dv ARCHIVE_ENTRY_ACL_SYNCHRONIZE ( Sy s ) +Use synchronous I/O. +.El +.Pp +The following NFSv4 ACL inheritance flags are supported: +.Bl -tag -offset indent -compact -width ARCHIV +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT ( Sy f ) +Inherit parent directory ACE to files. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT ( Sy d ) +Inherit parent directory ACE to subdirectories. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY ( Sy i ) +Only inherit, do not apply the permission on the directory itself. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT ( Sy n ) +Do not propagate inherit flags. +Only first-level entries inherit ACLs. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS ( Sy S ) +Trigger alarm or audit on successful access. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS ( Sy F ) +Trigger alarm or audit on failed access. +.It Dv ARCHIVE_ENTRY_ACL_ENTRY_INHERITED ( Sy I ) +Mark that ACE was inherited. +.El +.Ss Functions +.Fn archive_entry_acl_add_entry +and +.Fn archive_entry_acl_add_entry_w +add a single ACL entry. +For the access ACL and non-extended principals, the classic Unix permissions +are updated. +An archive entry cannot contain both POSIX.1e and NFSv4 ACL entries. +.Pp +.Fn archive_entry_acl_clear +removes all ACL entries and resets the enumeration pointer. +.Pp +.Fn archive_entry_acl_count +counts the ACL entries that have the given type mask. +.Fa type +can be the bitwise-or of +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_DEFAULT" +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT +.El +for POSIX.1e ACLs and +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_ALLOW" +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALLOW +.It Dv ARCHIVE_ENTRY_ACL_TYPE_DENY +.It Dv ARCHIVE_ENTRY_ACL_TYPE_AUDIT +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ALARM +.El +for NFSv4 ACLs. +For POSIX.1e ACLs if +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +is included and at least one extended ACL entry is found, +the three non-extended ACLs are added. +.Pp +.Fn archive_entry_acl_from_text +and +.Fn archive_entry_acl_from_text_w +add new +.Pq or merge with existing +ACL entries from +.Pq wide +text. +The argument +.Fa type +may take one of the following values: +.Bl -tag -offset indent -compact -width "ARCHIVE_ENTRY_ACL_TYPE_DEFAULT" +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT +.It Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 +.El +Supports all formats that can be created with +.Fn archive_entry_acl_to_text +or respectively +.Fn archive_entry_acl_to_text_w . +Existing ACL entries are preserved. +To get a clean new ACL from text +.Fn archive_entry_acl_clear +must be called first. +Entries prefixed with +.Dq default: +are treated as +.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT +unless +.Fa type +is +.Dv ARCHIVE_ENTRY_ACL_TYPE_NFS4 . +Invalid entries, non-parseable ACL entries and entries beginning with +the +.Sq # +character +.Pq comments +are skipped. +.Pp +.Fn archive_entry_acl_next +return the next entry of the ACL list. +This functions may only be called after +.Fn archive_entry_acl_reset +has indicated the presence of extended ACL entries. +.Pp +.Fn archive_entry_acl_reset +prepare reading the list of ACL entries with +.Fn archive_entry_acl_next . +The function returns 0 if no non-extended ACLs are found. +In this case, the access permissions should be obtained by +.Xr archive_entry_mode 3 +or set using +.Xr chmod 2 . +Otherwise, the function returns the same value as +.Fn archive_entry_acl_count . +.Pp +.Fn archive_entry_acl_to_text +and +.Fn archive_entry_acl_to_text_w +convert the ACL entries for the given type into a +.Pq wide +string of ACL entries separated by newline. +If the pointer +.Fa len_p +is not NULL, then the function shall return the length of the string +.Pq not including the NULL terminator +in the location pointed to by +.Fa len_p . +The +.Fa flag +argument is a bitwise-or. +.Pp +The following flags are effective only on POSIX.1e ACL: +.Bl -tag -offset indent -compact -width ARCHIV +.It Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +Output access ACLs. +.It Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT +Output POSIX.1e default ACLs. +.It Dv ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT +Prefix each default ACL entry with the word +.Dq default: . +.It Dv ARCHIVE_ENTRY_ACL_STYLE_SOLARIS +The mask and other ACLs don not contain a double colon. +.El +.Pp +The following flags are effective only on NFSv4 ACL: +.Bl -tag -offset indent -compact -width ARCHIV +.It Dv ARCHIVE_ENTRY_ACL_STYLE_COMPACT +Do not output minus characters for unset permissions and flags in NFSv4 ACL +permission and flag fields. +.El +.Pp +The following flags are effective on both POSIX.1e and NFSv4 ACL: +.Bl -tag -offset indent -compact -width ARCHIV +.It Dv ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID +Add an additional colon-separated field containing the user or group id. +.It Dv ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA +Separate ACL entries with comma instead of newline. +.El +.Pp +If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are returned. +It the entry contains POSIX.1e ACLs and none of the flags +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +or +.Dv ARCHIVE_ENTRY_ACL_TYPE_DEFAULT +are specified, both access and default entries are returned and default entries +are prefixed with +.Dq default: . +.Pp +.Fn archive_entry_acl_types +get ACL entry types contained in an archive entry's ACL. +As POSIX.1e and NFSv4 +ACL entries cannot be mixed, this function is a very efficient way to detect if +an ACL already contains POSIX.1e or NFSv4 ACL entries. +.Sh RETURN VALUES +.Fn archive_entry_acl_count +and +.Fn archive_entry_acl_reset +returns the number of ACL entries that match the given type mask. +For POSIX.1e ACLS if the type mask includes +.Dv ARCHIVE_ENTRY_ACL_TYPE_ACCESS +and at least one extended ACL entry exists, the three classic Unix +permissions are counted. +.Pp +.Fn archive_entry_acl_from_text +and +.Fn archive_entry_acl_from_text_w +return +.Dv ARCHIVE_OK +if all entries were successfully parsed and +.Dv ARCHIVE_WARN +if one or more entries were invalid or non-parseable. +.Pp +.Fn archive_entry_acl_next +returns +.Dv ARCHIVE_OK +on success, +.Dv ARCHIVE_EOF +if no more ACL entries exist +and +.Dv ARCHIVE_WARN +if +.Fn archive_entry_acl_reset +has not been called first. +.Pp +.Fn archive_entry_acl_to_text +returns a string representing the ACL entries matching the given type and +flags on success or NULL on error. +.Pp +.Fn archive_entry_acl_to_text_w +returns a wide string representing the ACL entries matching the given type +and flags on success or NULL on error. +.Pp +.Fn archive_entry_acl_types +returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries. +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_entry_linkify.3 b/static/netbsd/man3/archive_entry_linkify.3 new file mode 100644 index 00000000..8c19fddb --- /dev/null +++ b/static/netbsd/man3/archive_entry_linkify.3 @@ -0,0 +1,224 @@ +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY_LINKIFY 3 +.Os +.Sh NAME +.Nm archive_entry_linkresolver , +.Nm archive_entry_linkresolver_new , +.Nm archive_entry_linkresolver_set_strategy , +.Nm archive_entry_linkresolver_free , +.Nm archive_entry_linkify +.Nd hardlink resolver functions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft struct archive_entry_linkresolver * +.Fn archive_entry_linkresolver_new void +.Ft void +.Fo archive_entry_linkresolver_set_strategy +.Fa "struct archive_entry_linkresolver *resolver" +.Fa "int format" +.Fc +.Ft void +.Fo archive_entry_linkresolver_free +.Fa "struct archive_entry_linkresolver *resolver" +.Fc +.Ft void +.Fo archive_entry_linkify +.Fa "struct archive_entry_linkresolver *resolver" +.Fa "struct archive_entry **entry" +.Fa "struct archive_entry **sparse" +.Fc +.Sh DESCRIPTION +Programs that want to create archives have to deal with hardlinks. +Hardlinks are handled in different ways by the archive formats. +The basic strategies are: +.Bl -enum +.It +Ignore hardlinks and store the body for each reference (old cpio, zip). +.It +Store the body the first time an inode is seen (ustar, pax). +.It +Store the body the last time an inode is seen (new cpio). +.El +.Pp +The +.Nm +functions help by providing a unified interface and handling the complexity +behind the scene. +.Pp +The +.Nm +functions assume that +.Vt archive_entry +instances have valid nlinks, inode and device values. +The inode and device value is used to match entries. +The nlinks value is used to determined if all references have been found and +if the internal references can be recycled. +.Pp +The +.Fn archive_entry_linkresolver_new +function allocates a new link resolver. +The instance can be freed using +.Fn archive_entry_linkresolver_free . +All deferred entries are flushed and the internal storage is freed. +.Pp +The +.Fn archive_entry_linkresolver_set_strategy +function selects the optimal hardlink strategy for the given format. +The format code can be obtained from +.Xr archive_format 3 . +The function can be called more than once, but it is recommended to +flush all deferred entries first. +.Pp +The +.Fn archive_entry_linkify +function is the core of +.Nm . +The +.Fn entry +argument points to the +.Vt archive_entry +that should be written. +Depending on the strategy one of the following actions is taken: +.Bl -enum +.It +For the simple archive formats +.Va *entry +is left unmodified and +.Va *sparse +is set to +.Dv NULL . +.It +For tar like archive formats, +.Va *sparse +is set to +.Dv NULL . +If +.Va *entry +is +.Dv NULL , +no action is taken. +If the hardlink count of +.Va *entry +is larger than 1 and the file type is a regular file or symbolic link, +the internal list is searched for a matching inode. +If such an inode is found, the link count is decremented and the file size +of +.Va *entry +is set to 0 to notify that no body should be written. +If no such inode is found, a copy of the entry is added to the internal cache +with a link count reduced by one. +.It +For new cpio like archive formats a value for +.Va *entry +of +.Dv NULL +is used to flush deferred entries. +In that case +.Va *entry +is set to an arbitrary deferred entry and the entry itself is removed from the +internal list. +If the internal list is empty, +.Va *entry +is set to +.Dv NULL . +In either case, +.Va *sparse +is set to +.Dv NULL +and the function returns. +If the hardlink count of +.Va *entry +is one or the file type is a directory or device, +.Va *sparse +is set to +.Dv NULL +and no further action is taken. +Otherwise, the internal list is searched for a matching inode. +If such an inode is not found, the entry is added to the internal list, +both +.Va *entry +and +.Va *sparse +are set to +.Dv NULL +and the function returns. +If such an inode is found, the link count is decremented. +If it remains larger than one, the existing entry on the internal list +is swapped with +.Va *entry +after retaining the link count. +The existing entry is returned in +.Va *entry . +If the link count reached one, the new entry is also removed from the +internal list and returned in +.Va *sparse . +Otherwise +.Va *sparse +is set to +.Dv NULL . +.El +.Pp +The general usage is therefore: +.Bl -enum +.It +For each new archive entry, call +.Fn archive_entry_linkify . +.It +Keep in mind that the entries returned may have a size of 0 now. +.It +If +.Va *entry +is not +.Dv NULL , +archive it. +.It +If +.Va *sparse +is not +.Dv NULL , +archive it. +.It +After all entries have been written to disk, call +.Fn archive_entry_linkify +with +.Va *entry +set to +.Dv NULL +and archive the returned entry as long as it is not +.Dv NULL . +.El +.Sh RETURN VALUES +.Fn archive_entry_linkresolver_new +returns +.Dv NULL +on +.Xr malloc 3 +failures. +.Sh SEE ALSO +.Xr archive_entry 3 diff --git a/static/netbsd/man3/archive_entry_misc.3 b/static/netbsd/man3/archive_entry_misc.3 new file mode 100644 index 00000000..dfab7ddb --- /dev/null +++ b/static/netbsd/man3/archive_entry_misc.3 @@ -0,0 +1,63 @@ +.\" Copyright (c) 2019 Martin Matuska +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 15, 2019 +.Dt ARCHIVE_ENTRY_MISC 3 +.Os +.Sh NAME +.Nm archive_entry_symlink_type , +.Nm archive_entry_set_symlink_type +.Nd miscellaneous functions for manipulating properties of archive_entry +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft int +.Fn archive_entry_symlink_type "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_symlink_type "struct archive_entry *a" "int" +.Sh DESCRIPTION +The function +.Fn archive_entry_symlink_type +returns and the function +.Fn archive_entry_set_symlink_type +sets the type of the symbolic link stored in an archive entry. +These functions +have special meaning on operating systems that support multiple symbolic link +types (e.g. Microsoft Windows). +.Pp +Supported values are: +.Bl -tag -width "AE_SYMLINK_TYPE_DIRECTORY" -compact +.It AE_SYMLINK_TYPE_UNDEFINED +Symbolic link target type is not defined (default on unix systems) +.It AE_SYMLINK_TYPE_FILE +Symbolic link points to a file +.It AE_SYMLINK_TYPE_DIRECTORY +Symbolic link points to a directory +.El +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr archive_entry_paths 3 , +.Xr archive_entry_stat 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_entry_paths.3 b/static/netbsd/man3/archive_entry_paths.3 new file mode 100644 index 00000000..f739b172 --- /dev/null +++ b/static/netbsd/man3/archive_entry_paths.3 @@ -0,0 +1,153 @@ +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY_PATHS 3 +.Os +.Sh NAME +.Nm archive_entry_hardlink , +.Nm archive_entry_hardlink_w , +.Nm archive_entry_set_hardlink , +.Nm archive_entry_copy_hardlink , +.Nm archive_entry_copy_hardlink_w , +.Nm archive_entry_update_hardlink_utf8 , +.Nm archive_entry_set_link , +.Nm archive_entry_copy_link , +.Nm archive_entry_copy_link_w , +.Nm archive_entry_update_link_utf8 , +.Nm archive_entry_pathname , +.Nm archive_entry_pathname_w , +.Nm archive_entry_set_pathname , +.Nm archive_entry_copy_pathname , +.Nm archive_entry_copy_pathname_w , +.Nm archive_entry_update_pathname_utf8 , +.Nm archive_entry_sourcepath , +.Nm archive_entry_copy_sourcepath , +.Nm archive_entry_symlink , +.Nm archive_entry_symlink_w , +.Nm archive_entry_set_symlink , +.Nm archive_entry_copy_symlink , +.Nm archive_entry_copy_symlink_w , +.Nm archive_entry_update_symlink_utf8 +.Nd functions for manipulating path names in archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft const char * +.Fn archive_entry_hardlink "struct archive_entry *a" +.Ft const wchar_t * +.Fn archive_entry_hardlink_w "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_hardlink "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_hardlink "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_hardlink_w "struct archive_entry *a" "const wchar_t *path" +.Ft int +.Fn archive_entry_update_hardlink_utf8 "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_set_link "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_link "struct archive_entry *a" " const char *path" +.Ft void +.Fn archive_entry_copy_link_w "struct archive_entry *a" " const wchar_t *path" +.Ft int +.Fn archive_entry_update_link_utf8 "struct archive_entry *a" " const char *path" +.Ft const char * +.Fn archive_entry_pathname "struct archive_entry *a" +.Ft const wchar_t * +.Fn archive_entry_pathname_w "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_pathname "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_pathname "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_pathname_w "struct archive_entry *a" "const wchar_t *path" +.Ft int +.Fn archive_entry_update_pathname_utf8 "struct archive_entry *a" "const char *path" +.Ft const char * +.Fn archive_entry_sourcepath "struct archive_entry *a" +.Ft void +.Fn archive_entry_copy_sourcepath "struct archive_entry *a" "const char *path" +.Ft const char * +.Fn archive_entry_symlink "struct archive_entry *a" +.Ft const wchar_t * +.Fn archive_entry_symlink_w "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_symlink "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_symlink "struct archive_entry *a" "const char *path" +.Ft void +.Fn archive_entry_copy_symlink_w "struct archive_entry *a" "const wchar_t *path" +.Ft int +.Fn archive_entry_update_symlink_utf8 "struct archive_entry *a" "const char *path" +.Sh DESCRIPTION +Path names supported by +.Xr archive_entry 3 : +.Bl -tag -width "sourcepath" -compact +.It hardlink +Destination of the hardlink. +.It link +Update only. +For a symlink, update the destination. +Otherwise, make the entry a hardlink and alter +the destination for that. +.It pathname +Path in the archive +.It sourcepath +Path on the disk for use by +.Xr archive_read_disk 3 . +.It symlink +Destination of the symbolic link. +.El +.Pp +Path names can be provided in one of three different ways: +.Bl -tag -width "wchar_t *" +.It char * +Multibyte strings in the current locale. +.It wchar_t * +Wide character strings in the current locale. +The accessor functions are named +.Fn XXX_w . +.It UTF-8 +Unicode strings encoded as UTF-8. +These are convenience functions to update both the multibyte and wide +character strings at the same time. +.El +.Pp +The sourcepath is a pure filesystem concept and never stored in an +archive directly. +.Pp +For that reason, it is only available as multibyte string. +The link path is a convenience function for conditionally setting +hardlink or symlink destination. +It doesn't have a corresponding get accessor function. +.Pp +.Fn archive_entry_set_XXX +is an alias for +.Fn archive_entry_copy_XXX . +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_entry_perms.3 b/static/netbsd/man3/archive_entry_perms.3 new file mode 100644 index 00000000..4bfbfc3c --- /dev/null +++ b/static/netbsd/man3/archive_entry_perms.3 @@ -0,0 +1,210 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY_PERMS 3 +.Os +.Sh NAME +.Nm archive_entry_gid , +.Nm archive_entry_set_gid , +.Nm archive_entry_uid , +.Nm archive_entry_set_uid , +.Nm archive_entry_perm , +.Nm archive_entry_set_perm , +.Nm archive_entry_strmode , +.Nm archive_entry_uname , +.Nm archive_entry_uname_w , +.Nm archive_entry_set_uname , +.Nm archive_entry_copy_uname , +.Nm archive_entry_copy_uname_w , +.Nm archive_entry_update_uname_utf8 , +.Nm archive_entry_gname , +.Nm archive_entry_gname_w , +.Nm archive_entry_set_gname , +.Nm archive_entry_copy_gname , +.Nm archive_entry_copy_gname_w , +.Nm archive_entry_update_gname_utf8 , +.Nm archive_entry_fflags , +.Nm archive_entry_fflags_text , +.Nm archive_entry_set_fflags , +.Nm archive_entry_copy_fflags_text , +.Nm archive_entry_copy_fflags_text_w +.Nd functions for manipulating ownership and permissions in archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft gid_t +.Fn archive_entry_gid "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_gid "struct archive_entry *a" "gid_t gid" +.Ft uid_t +.Fn archive_entry_uid "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_uid "struct archive_entry *a" "uid_t uid" +.Ft mode_t +.Fn archive_entry_perm "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_perm "struct archive_entry *a" "mode_t mode" +.Ft const char * +.Fn archive_entry_strmode "struct archive_entry *a" +.Ft const char * +.Fn archive_entry_gname "struct archive_entry *a" +.Ft const wchar_t * +.Fn archive_entry_gname_w "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_gname "struct archive_entry *a" "const char *a" +.Ft void +.Fn archive_entry_copy_gname "struct archive_entry *a" "const char *name" +.Ft void +.Fn archive_entry_copy_gname_w "struct archive_entry *a" "const wchar_t *name" +.Ft int +.Fn archive_entry_update_gname_utf8 "struct archive_entry *a" "const char *name" +.Ft const char * +.Fn archive_entry_uname "struct archive_entry *a" +.Ft const wchar_t * +.Fn archive_entry_uname_w "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_uname "struct archive_entry *a" "const char *name" +.Ft void +.Fn archive_entry_copy_uname "struct archive_entry *a" "const char *name" +.Ft void +.Fn archive_entry_copy_uname_w "struct archive_entry *a" "const wchar_t *name" +.Ft int +.Fn archive_entry_update_uname_utf8 "struct archive_entry *a" "const char *name" +.Ft void +.Fo archive_entry_fflags +.Fa "struct archive_entry *a" +.Fa "unsigned long *set_bits" +.Fa "unsigned long *clear_bits" +.Fc +.Ft const char * +.Fn archive_entry_fflags_text "struct archive_entry *a" +.Ft void +.Fo archive_entry_set_fflags +.Fa "struct archive_entry *a" +.Fa "unsigned long set_bits" +.Fa "unsigned long clear_bits" +.Fc +.Ft const char * +.Fn archive_entry_copy_fflags_text "struct archive_entry *a" "const char *text" +.Ft const wchar_t * +.Fn archive_entry_copy_fflags_text_w "struct archive_entry *a" "const wchar_t *text" +.Sh DESCRIPTION +.Ss User id, group id and mode +The functions +.Fn archive_entry_uid , +.Fn archive_entry_gid , +and +.Fn archive_entry_perm +can be used to extract the user id, group id and permission from the given entry. +The corresponding functions +.Fn archive_entry_set_uid , +.Fn archive_entry_set_gid , +and +.Fn archive_entry_set_perm +store the given user id, group id and permission in the entry. +The permission is also set as a side effect of calling +.Fn archive_entry_set_mode . +.Pp +.Fn archive_entry_strmode +returns a string representation of the permission as used by the long mode of +.Xr ls 1 . +.Ss User and group name +User and group names can be provided in one of three different ways: +.Bl -tag -width "wchar_t *" +.It char * +Multibyte strings in the current locale. +.It wchar_t * +Wide character strings in the current locale. +The accessor functions are named +.Fn XXX_w . +.It UTF-8 +Unicode strings encoded as UTF-8. +These are convenience functions to update both the multibyte and wide +character strings at the same time. +.El +.Pp +.Fn archive_entry_set_XXX +is an alias for +.Fn archive_entry_copy_XXX . +The strings are copied, and don't need to outlive the call. +.Ss File Flags +File flags are transparently converted between a bitmap +representation and a textual format. +For example, if you set the bitmap and ask for text, the library +will build a canonical text format. +However, if you set a text format and request a text format, +you will get back the same text, even if it is ill-formed. +If you need to canonicalize a textual flags string, you should first set the +text form, then request the bitmap form, then use that to set the bitmap form. +Setting the bitmap format will clear the internal text representation +and force it to be reconstructed when you next request the text form. +.Pp +The bitmap format consists of two integers, one containing bits +that should be set, the other specifying bits that should be +cleared. +Bits not mentioned in either bitmap will be ignored. +Usually, the bitmap of bits to be cleared will be set to zero. +In unusual circumstances, you can force a fully-specified set +of file flags by setting the bitmap of flags to clear to the complement +of the bitmap of flags to set. +(This differs from +.Xr fflagstostr 3 , +which only includes names for set bits.) +Converting a bitmap to a textual string is a platform-specific +operation; bits that are not meaningful on the current platform +will be ignored. +.Pp +The canonical text format is a comma-separated list of flag names. +The +.Fn archive_entry_copy_fflags_text +and +.Fn archive_entry_copy_fflags_text_w +functions parse the provided text and set the internal bitmap values. +This is a platform-specific operation; names that are not meaningful +on the current platform will be ignored. +The function returns a pointer to the start of the first name that was not +recognized, or NULL if every name was recognized. +Note that every name \(em including names that follow an unrecognized +name \(em will be evaluated, and the bitmaps will be set to reflect +every name that is recognized. +(In particular, this differs from +.Xr strtofflags 3 , +which stops parsing at the first unrecognized name.) +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr archive_entry_acl 3 , +.Xr archive_read_disk 3 , +.Xr archive_write_disk 3 , +.Xr libarchive 3 +.Sh BUGS +The platform types +.Vt uid_t +and +.Vt gid_t +are often 16 or 32 bit wide. +In this case it is possible that the ids can not be correctly restored +from archives and get truncated. diff --git a/static/netbsd/man3/archive_entry_stat.3 b/static/netbsd/man3/archive_entry_stat.3 new file mode 100644 index 00000000..2f4a1920 --- /dev/null +++ b/static/netbsd/man3/archive_entry_stat.3 @@ -0,0 +1,274 @@ +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY_STAT 3 +.Os +.Sh NAME +.Nm archive_entry_stat , +.Nm archive_entry_copy_stat , +.Nm archive_entry_filetype , +.Nm archive_entry_set_filetype , +.Nm archive_entry_mode , +.Nm archive_entry_set_mode , +.Nm archive_entry_size , +.Nm archive_entry_size_is_set , +.Nm archive_entry_set_size , +.Nm archive_entry_unset_size , +.Nm archive_entry_dev , +.Nm archive_entry_set_dev , +.Nm archive_entry_dev_is_set , +.Nm archive_entry_devmajor , +.Nm archive_entry_set_devmajor , +.Nm archive_entry_devminor , +.Nm archive_entry_set_devminor , +.Nm archive_entry_ino , +.Nm archive_entry_set_ino , +.Nm archive_entry_ino_is_set , +.Nm archive_entry_ino64 , +.Nm archive_entry_set_ino64 , +.Nm archive_entry_nlink , +.Nm archive_entry_rdev , +.Nm archive_entry_set_rdev , +.Nm archive_entry_rdevmajor , +.Nm archive_entry_set_rdevmajor , +.Nm archive_entry_rdevminor , +.Nm archive_entry_set_rdevminor +.Nd accessor functions for manipulating archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft const struct stat * +.Fn archive_entry_stat "struct archive_entry *a" +.Ft void +.Fn archive_entry_copy_stat "struct archive_entry *a" "const struct stat *sb" +.Ft mode_t +.Fn archive_entry_filetype "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_filetype "struct archive_entry *a" "unsigned int type" +.Ft mode_t +.Fn archive_entry_mode "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_mode "struct archive_entry *a" "mode_t mode" +.Ft int64_t +.Fn archive_entry_size "struct archive_entry *a" +.Ft int +.Fn archive_entry_size_is_set "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_size "struct archive_entry *a" "int64_t size" +.Ft void +.Fn archive_entry_unset_size "struct archive_entry *a" +.Ft dev_t +.Fn archive_entry_dev "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_dev "struct archive_entry *a" "dev_t dev" +.Ft int +.Fn archive_entry_dev_is_set "struct archive_entry *a" +.Ft dev_t +.Fn archive_entry_devmajor "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_devmajor "struct archive_entry *a" "dev_t major" +.Ft dev_t +.Fn archive_entry_devminor "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_devminor "struct archive_entry *a" "dev_t minor" +.Ft ino_t +.Fn archive_entry_ino "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_ino "struct archive_entry *a" "unsigned long ino" +.Ft int +.Fn archive_entry_ino_is_set "struct archive_entry *a" +.Ft int64_t +.Fn archive_entry_ino64 "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_ino64 "struct archive_entry *a" "int64_t ino" +.Ft unsigned int +.Fn archive_entry_nlink "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_nlink "struct archive_entry *a" "unsigned int count" +.Ft dev_t +.Fn archive_entry_rdev "struct archive_entry *a" +.Ft dev_t +.Fn archive_entry_rdevmajor "struct archive_entry *a" +.Ft dev_t +.Fn archive_entry_rdevminor "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_rdev "struct archive_entry *a" "dev_t dev" +.Ft void +.Fn archive_entry_set_rdevmajor "struct archive_entry *a" "dev_t major" +.Ft void +.Fn archive_entry_set_rdevminor "struct archive_entry *a" "dev_t minor" +.Sh DESCRIPTION +.Ss Copying to and from Vt struct stat +The function +.Fn archive_entry_stat +converts the various fields stored in the archive entry to the format +used by +.Xr stat 2 . +The return value remains valid until either +.Fn archive_entry_clear +or +.Fn archive_entry_free +is called. +It is not affected by calls to the set accessor functions. +It currently sets the following values in +.Vt struct stat : +.Vt st_atime , +.Vt st_ctime , +.Vt st_dev , +.Vt st_gid , +.Vt st_ino , +.Vt st_mode , +.Vt st_mtime , +.Vt st_nlink , +.Vt st_rdev , +.Vt st_size , +.Vt st_uid . +In addition, +.Vt st_birthtime +and high-precision information for time-related fields +will be included on platforms that support it. +.Pp +The function +.Fn archive_entry_copy_stat +copies fields from the platform's +.Vt struct stat . +Fields not provided by +.Vt struct stat +are unchanged. +.Ss General accessor functions +The functions +.Fn archive_entry_filetype +and +.Fn archive_entry_set_filetype +get respectively set the filetype. +The file type is one of the following constants: +.Bl -tag -width "AE_IFSOCK" -compact -offset indent +.It AE_IFREG +Regular file +.It AE_IFLNK +Symbolic link +.It AE_IFSOCK +Socket +.It AE_IFCHR +Character device +.It AE_IFBLK +Block device +.It AE_IFDIR +Directory +.It AE_IFIFO +Named pipe (fifo) +.El +Not all file types are supported by all platforms. +The constants used by +.Xr stat 2 +may have different numeric values from the +corresponding constants above. +.Pp +The functions +.Fn archive_entry_mode +and +.Fn archive_entry_set_mode +get/set a combination of file type and permissions and provide the +equivalent of +.Va st_mode . +Use of +.Fn archive_entry_filetype +and +.Fn archive_entry_perm +for getting and +.Fn archive_entry_set_filetype +and +.Fn archive_entry_set_perm +for setting is recommended. +.Pp +The function +.Fn archive_entry_size +returns the file size, if it has been set, and 0 otherwise. +.Fn archive_entry_size_is_set +can be used to query that status. +.Fn archive_entry_set_size +and +.Fn archive_entry_unset_size +set and unset the size, respectively. +.Pp +The number of references (hardlinks) can be obtained by calling +.Fn archive_entry_nlink +and set with +.Fn archive_entry_set_nlink . +.Ss Identifying unique files +The functions +.Fn archive_entry_dev +and +.Fn archive_entry_ino64 +are used by +.Xr archive_entry_linkify 3 +to find hardlinks. +The pair of device and inode is supposed to identify hardlinked files. +.Pp +The device major and minor number can be obtained independently using +.Fn archive_entry_devmajor +and +.Fn archive_entry_devminor . +The device can be set either via +.Fn archive_entry_set_dev +or by the combination of major and minor number using +.Fn archive_entry_set_devmajor +and +.Fn archive_entry_set_devminor . +.Pp +The inode number can be obtained using +.Fn archive_entry_ino . +This is a legacy interface that uses the platform +.Vt ino_t , +which may be very small. +To set the inode number, +.Fn archive_entry_set_ino64 +is the preferred interface. +.Ss Accessor functions for block and character devices +Block and character devices are characterised either using a device number +or a pair of major and minor number. +The combined device number can be obtained with +.Fn archive_device_rdev +and set with +.Fn archive_device_set_rdev . +The major and minor numbers are accessed by +.Fn archive_device_rdevmajor , +.Fn archive_device_rdevminor +.Fn archive_device_set_rdevmajor +and +.Fn archive_device_set_rdevminor . +.Pp +The process of splitting the combined device number into major and +minor number and the reverse process of combing them differs between +platforms. +Some archive formats use the combined form, while other formats use +the split form. +.Sh SEE ALSO +.Xr stat 2 , +.Xr archive_entry_acl 3 , +.Xr archive_entry_perms 3 , +.Xr archive_entry_time 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_entry_time.3 b/static/netbsd/man3/archive_entry_time.3 new file mode 100644 index 00000000..0f1dbb02 --- /dev/null +++ b/static/netbsd/man3/archive_entry_time.3 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" Copyright (c) 2010 Joerg Sonnenberger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_ENTRY_TIME 3 +.Os +.Sh NAME +.Nm archive_entry_atime , +.Nm archive_entry_atime_nsec , +.Nm archive_entry_atime_is_set , +.Nm archive_entry_set_atime , +.Nm archive_entry_unset_atime , +.Nm archive_entry_birthtime , +.Nm archive_entry_birthtime_nsec , +.Nm archive_entry_birthtime_is_set , +.Nm archive_entry_set_birthtime , +.Nm archive_entry_unset_birthtime , +.Nm archive_entry_ctime , +.Nm archive_entry_ctime_nsec , +.Nm archive_entry_ctime_is_set , +.Nm archive_entry_set_ctime , +.Nm archive_entry_unset_ctime , +.Nm archive_entry_mtime , +.Nm archive_entry_mtime_nsec , +.Nm archive_entry_mtime_is_set , +.Nm archive_entry_set_mtime , +.Nm archive_entry_unset_mtime +.Nd functions for manipulating times in archive entry descriptions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive_entry.h +.Ft time_t +.Fn archive_entry_atime "struct archive_entry *a" +.Ft long +.Fn archive_entry_atime_nsec "struct archive_entry *a" +.Ft int +.Fn archive_entry_atime_is_set "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_atime "struct archive_entry *a" "time_t sec" "long nanosec" +.Ft void +.Fn archive_entry_unset_atime "struct archive_entry *a" +.Ft time_t +.Fn archive_entry_birthtime "struct archive_entry *a" +.Ft long +.Fn archive_entry_birthtime_nsec "struct archive_entry *a" +.Ft int +.Fn archive_entry_birthtime_is_set "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_birthtime "struct archive_entry *a" "time_t sec" "long nanosec" +.Ft void +.Fn archive_entry_unset_birthtime "struct archive_entry *a" +.Ft time_t +.Fn archive_entry_ctime "struct archive_entry *a" +.Ft long +.Fn archive_entry_ctime_nsec "struct archive_entry *a" +.Ft int +.Fn archive_entry_ctime_is_set "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_ctime "struct archive_entry *a" "time_t sec" "long nanosec" +.Ft void +.Fn archive_entry_unset_ctime "struct archive_entry *a" +.Ft time_t +.Fn archive_entry_mtime "struct archive_entry *a" +.Ft long +.Fn archive_entry_mtime_nsec "struct archive_entry *a" +.Ft int +.Fn archive_entry_mtime_is_set "struct archive_entry *a" +.Ft void +.Fn archive_entry_set_mtime "struct archive_entry *a" "time_t sec" "long nanosec" +.Ft void +.Fn archive_entry_unset_mtime "struct archive_entry *a" +.Sh DESCRIPTION +These functions create and manipulate the time fields in an +.Vt archive_entry . +Supported time fields are atime (access time), birthtime (creation time), +ctime (last time an inode property was changed) and mtime (modification time). +.Pp +.Xr libarchive 3 +provides a high-resolution interface. +The timestamps are truncated automatically depending on the archive format +(for archiving) or the filesystem capabilities (for restoring). +.Pp +All timestamp fields are optional. +The +.Fn XXX_unset +functions can be used to mark the corresponding field as missing. +The current state can be queried using +.Fn XXX_is_set . +Unset time fields have a second and nanosecond field of 0. +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.\" .Sh BUGS diff --git a/static/netbsd/man3/archive_read.3 b/static/netbsd/man3/archive_read.3 new file mode 100644 index 00000000..c81c98be --- /dev/null +++ b/static/netbsd/man3/archive_read.3 @@ -0,0 +1,250 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ 3 +.Os +.Sh NAME +.Nm archive_read +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Sh DESCRIPTION +These functions provide a complete API for reading streaming archives. +The general process is to first create the +.Tn struct archive +object, set options, initialize the reader, iterate over the archive +headers and associated data, then close the archive and release all +resources. +.\" +.Ss Create archive object +See +.Xr archive_read_new 3 . +.Pp +To read an archive, you must first obtain an initialized +.Tn struct archive +object from +.Fn archive_read_new . +.\" +.Ss Enable filters and formats +See +.Xr archive_read_filter 3 +and +.Xr archive_read_format 3 . +.Pp +You can then modify this object for the desired operations with the +various +.Fn archive_read_set_XXX +and +.Fn archive_read_support_XXX +functions. +In particular, you will need to invoke appropriate +.Fn archive_read_support_XXX +functions to enable the corresponding compression and format +support. +Note that these latter functions perform two distinct operations: +they cause the corresponding support code to be linked into your +program, and they enable the corresponding auto-detect code. +Unless you have specific constraints, you will generally want +to invoke +.Fn archive_read_support_filter_all +and +.Fn archive_read_support_format_all +to enable auto-detect for all formats and compression types +currently supported by the library. +.\" +.Ss Set options +See +.Xr archive_read_set_options 3 . +.\" +.Ss Open archive +See +.Xr archive_read_open 3 . +.Pp +Once you have prepared the +.Tn struct archive +object, you call +.Fn archive_read_open +to actually open the archive and prepare it for reading. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, +.Ft "FILE *" +object, or a block of memory from which to read the archive data. +Note that the core library makes no assumptions about the +size of the blocks read; +callback functions are free to read whatever block size is +most appropriate for the medium. +.\" +.Ss Consume archive +See +.Xr archive_read_header 3 , +.Xr archive_read_data 3 +and +.Xr archive_read_extract 3 . +.Pp +Each archive entry consists of a header followed by a certain +amount of data. +You can obtain the next header with +.Fn archive_read_next_header , +which returns a pointer to an +.Tn struct archive_entry +structure with information about the current archive element. +If the entry is a regular file, then the header will be followed +by the file data. +You can use +.Fn archive_read_data +(which works much like the +.Xr read 2 +system call) +to read this data from the archive, or +.Fn archive_read_data_block +which provides a slightly more efficient interface. +You may prefer to use the higher-level +.Fn archive_read_data_skip , +which reads and discards the data for this entry, +.Fn archive_read_data_into_fd , +which copies the data to the provided file descriptor, or +.Fn archive_read_extract , +which recreates the specified entry on disk and copies data +from the archive. +In particular, note that +.Fn archive_read_extract +uses the +.Tn struct archive_entry +structure that you provide it, which may differ from the +entry just read from the archive. +In particular, many applications will want to override the +pathname, file permissions, or ownership. +.\" +.Ss Release resources +See +.Xr archive_read_free 3 . +.Pp +Once you have finished reading data from the archive, you +should call +.Fn archive_read_close +to close the archive, then call +.Fn archive_read_free +to release all resources, including all memory allocated by the library. +.\" +.Sh EXAMPLES +The following illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +.Xr open 2 , +.Xr read 2 , +and +.Xr close 2 +system calls. +.Bd -literal -offset indent +void +list_archive(const char *name) +{ + struct mydata *mydata; + struct archive *a; + struct archive_entry *entry; + + mydata = malloc(sizeof(struct mydata)); + a = archive_read_new(); + mydata->name = name; + archive_read_support_filter_all(a); + archive_read_support_format_all(a); + archive_read_open(a, mydata, myopen, myread, myclose); + while (archive_read_next_header(a, &entry) == ARCHIVE_OK) { + printf("%s\en",archive_entry_pathname(entry)); + archive_read_data_skip(a); + } + archive_read_free(a); + free(mydata); +} + +la_ssize_t +myread(struct archive *a, void *client_data, const void **buff) +{ + struct mydata *mydata = client_data; + + *buff = mydata->buff; + return (read(mydata->fd, mydata->buff, 10240)); +} + +int +myopen(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + + mydata->fd = open(mydata->name, O_RDONLY); + return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL); +} + +int +myclose(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + + if (mydata->fd > 0) + close(mydata->fd); + return (ARCHIVE_OK); +} +.Ed +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read_data 3 , +.Xr archive_read_extract 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_header 3 , +.Xr archive_read_new 3 , +.Xr archive_read_open 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Many traditional archiver programs treat +empty files as valid empty archives. +For example, many implementations of +.Xr tar 1 +allow you to append entries to an empty file. +Of course, it is impossible to determine the format of an empty file +by inspecting the contents, so this library treats empty files as +having a special +.Dq empty +format. diff --git a/static/netbsd/man3/archive_read_add_passphrase.3 b/static/netbsd/man3/archive_read_add_passphrase.3 new file mode 100644 index 00000000..c35cfeb3 --- /dev/null +++ b/static/netbsd/man3/archive_read_add_passphrase.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2014 Michihiro NAKAJIMA +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 14, 2014 +.Dt ARCHIVE_READ_ADD_PASSPHRASE 3 +.Os +.Sh NAME +.Nm archive_read_add_passphrase , +.Nm archive_read_set_passphrase_callback +.Nd functions for reading encrypted archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_read_add_passphrase +.Fa "struct archive *" +.Fa "const char *passphrase" +.Fc +.Ft int +.Fo archive_read_set_passphrase_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_passphrase_callback *" +.Fc +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_read_add_passphrase +Register passphrases for reading an encryption archive. +If +.Ar passphrase +is +.Dv NULL +or empty, this function will do nothing and +.Cm ARCHIVE_FAILED +will be returned. +Otherwise, +.Cm ARCHIVE_OK +will be returned. +.It Fn archive_read_set_passphrase_callback +Register a callback function that will be invoked to get a passphrase +for decryption after trying all the passphrases registered by the +.Fn archive_read_add_passphrase +function failed. +.El +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_read_set_options 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_read_data.3 b/static/netbsd/man3/archive_read_data.3 new file mode 100644 index 00000000..694f2926 --- /dev/null +++ b/static/netbsd/man3/archive_read_data.3 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_DATA 3 +.Os +.Sh NAME +.Nm archive_read_data , +.Nm archive_read_data_block , +.Nm archive_read_data_skip , +.Nm archive_read_data_into_fd +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft la_ssize_t +.Fn archive_read_data "struct archive *" "void *buff" "size_t len" +.Ft int +.Fo archive_read_data_block +.Fa "struct archive *" +.Fa "const void **buff" +.Fa "size_t *len" +.Fa "off_t *offset" +.Fc +.Ft int +.Fn archive_read_data_skip "struct archive *" +.Ft int +.Fn archive_read_data_into_fd "struct archive *" "int fd" +.\" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Fn archive_read_data +Read data associated with the header just read. +Internally, this is a convenience function that calls +.Fn archive_read_data_block +and fills any gaps with nulls so that callers see a single +continuous stream of data. +.It Fn archive_read_data_block +Return the next available block of data for this entry. +Unlike +.Fn archive_read_data , +the +.Fn archive_read_data_block +function avoids copying data and allows you to correctly handle +sparse files, as supported by some archive formats. +The library guarantees that offsets will increase and that blocks +will not overlap. +Note that the blocks returned from this function can be much larger +than the block size read from disk, due to compression +and internal buffer optimizations. +.It Fn archive_read_data_skip +A convenience function that repeatedly calls +.Fn archive_read_data_block +to skip all of the data for this archive entry. +Note that this function is invoked automatically by +.Fn archive_read_next_header2 +if the previous entry was not completely consumed. +.It Fn archive_read_data_into_fd +A convenience function that repeatedly calls +.Fn archive_read_data_block +to copy the entire entry to the provided file descriptor. +.El +.\" +.Sh RETURN VALUES +Most functions return zero on success, non-zero on error. +The possible return codes include: +.Cm ARCHIVE_OK +(the operation succeeded), +.Cm ARCHIVE_WARN +(the operation succeeded but a non-critical error was encountered), +.Cm ARCHIVE_EOF +(end-of-archive was encountered), +.Cm ARCHIVE_RETRY +(the operation failed but can be retried), +and +.Cm ARCHIVE_FATAL +(there was a fatal error; the archive should be closed immediately). +.Pp +.Fn archive_read_data +returns a count of bytes actually read or zero at the end of the entry. +On error, a value of +.Cm ARCHIVE_FATAL , +.Cm ARCHIVE_WARN , +or +.Cm ARCHIVE_RETRY +is returned. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_read_extract 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_header 3 , +.Xr archive_read_open 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_read_disk.3 b/static/netbsd/man3/archive_read_disk.3 new file mode 100644 index 00000000..990c1514 --- /dev/null +++ b/static/netbsd/man3/archive_read_disk.3 @@ -0,0 +1,422 @@ +.\" Copyright (c) 2003-2009 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 3, 2017 +.Dt ARCHIVE_READ_DISK 3 +.Os +.Sh NAME +.Nm archive_read_disk_new , +.Nm archive_read_disk_open , +.Nm archive_read_disk_open_w , +.Nm archive_read_disk_set_behavior , +.Nm archive_read_disk_set_symlink_logical , +.Nm archive_read_disk_set_symlink_physical , +.Nm archive_read_disk_set_symlink_hybrid , +.Nm archive_read_disk_entry_from_file , +.Nm archive_read_disk_gname , +.Nm archive_read_disk_uname , +.Nm archive_read_disk_set_uname_lookup , +.Nm archive_read_disk_set_gname_lookup , +.Nm archive_read_disk_set_standard_lookup , +.Nm archive_read_disk_descend , +.Nm archive_read_disk_can_descend , +.Nm archive_read_disk_current_filesystem , +.Nm archive_read_disk_current_filesystem_is_synthetic , +.Nm archive_read_disk_current_filesystem_is_remote , +.Nm archive_read_disk_set_matching , +.Nm archive_read_disk_set_metadata_filter_callback , +.Nd functions for reading objects from disk +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_read_disk_new "void" +.Ft int +.Fn archive_read_disk_open "struct archive *" "const char *" +.Ft int +.Fn archive_read_disk_open_w "struct archive *" "const wchar_t *" +.Ft int +.Fn archive_read_disk_set_behavior "struct archive *" "int" +.Ft int +.Fn archive_read_disk_set_symlink_logical "struct archive *" +.Ft int +.Fn archive_read_disk_set_symlink_physical "struct archive *" +.Ft int +.Fn archive_read_disk_set_symlink_hybrid "struct archive *" +.Ft const char * +.Fn archive_read_disk_gname "struct archive *" "gid_t" +.Ft const char * +.Fn archive_read_disk_uname "struct archive *" "uid_t" +.Ft int +.Fo archive_read_disk_set_gname_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "const char *(*lookup)(void *, gid_t)" +.Fa "void (*cleanup)(void *)" +.Fc +.Ft int +.Fo archive_read_disk_set_uname_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "const char *(*lookup)(void *, uid_t)" +.Fa "void (*cleanup)(void *)" +.Fc +.Ft int +.Fn archive_read_disk_set_standard_lookup "struct archive *" +.Ft int +.Fo archive_read_disk_entry_from_file +.Fa "struct archive *" +.Fa "struct archive_entry *" +.Fa "int fd" +.Fa "const struct stat *" +.Fc +.Ft int +.Fn archive_read_disk_descend "struct archive *" +.Ft int +.Fn archive_read_disk_can_descend "struct archive *" +.Ft int +.Fn archive_read_disk_current_filesystem "struct archive *" +.Ft int +.Fn archive_read_disk_current_filesystem_is_synthetic "struct archive *" +.Ft int +.Fn archive_read_disk_current_filesystem_is_remote "struct archive *" +.Ft int +.Fo archive_read_disk_set_matching +.Fa "struct archive *" +.Fa "struct archive *" +.Fa "void (*excluded_func)(struct archive *, void *, struct archive entry *)" +.Fa "void *" +.Fc +.Ft int +.Fo archive_read_disk_set_metadata_filter_callback +.Fa "struct archive *" +.Fa "int (*metadata_filter_func)(struct archive *, void*, struct archive_entry *)" +.Fa "void *" +.Fc +.Sh DESCRIPTION +These functions provide an API for reading information about +objects on disk. +In particular, they provide an interface for populating +.Tn struct archive_entry +objects. +.Bl -tag -width indent +.It Fn archive_read_disk_new +Allocates and initializes a +.Tn struct archive +object suitable for reading object information from disk. +.It Fn archive_read_disk_open +Opens the file or directory from the given path and prepares the +.Tn struct archive +to read it from disk. +.It Fn archive_read_disk_open_w +Opens the file or directory from the given path as a wide character string and prepares the +.Tn struct archive +to read it from disk. +.It Fn archive_read_disk_set_behavior +Configures various behavior options when reading entries from disk. +The flags field consists of a bitwise OR of one or more of the +following values: +.Bl -tag -compact -width "indent" +.It Cm ARCHIVE_READDISK_HONOR_NODUMP +Skip files and directories with the nodump file attribute (file flag) set. +By default, the nodump file attribute is ignored. +.It Cm ARCHIVE_READDISK_MAC_COPYFILE +Mac OS X specific. +Read metadata (ACLs and extended attributes) with +.Xr copyfile 3 . +By default, metadata is read using +.Xr copyfile 3 . +.It Cm ARCHIVE_READDISK_NO_ACL +Do not read Access Control Lists. +By default, ACLs are read from disk. +.It Cm ARCHIVE_READDISK_NO_FFLAGS +Do not read file attributes (file flags). +By default, file attributes are read from disk. +See +.Xr chattr 1 +.Pq Linux +or +.Xr chflags 1 +.Pq FreeBSD, Mac OS X +for more information on file attributes. +.It Cm ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS +Do not traverse mount points. +By default, mount points are traversed. +.It Cm ARCHIVE_READDISK_NO_XATTR +Do not read extended file attributes (xattrs). +By default, extended file attributes are read from disk. +See +.Xr xattr 7 +.Pq Linux , +.Xr xattr 2 +.Pq Mac OS X , +or +.Xr getextattr 8 +.Pq FreeBSD +for more information on extended file attributes. +.It Cm ARCHIVE_READDISK_RESTORE_ATIME +Restore access time of traversed files. +By default, access time of traversed files is not restored. +.It Cm ARCHIVE_READDISK_NO_SPARSE +Do not read sparse file information. +By default, sparse file information is read from disk. +.El +.It Xo +.Fn archive_read_disk_set_symlink_logical , +.Fn archive_read_disk_set_symlink_physical , +.Fn archive_read_disk_set_symlink_hybrid +.Xc +This sets the mode used for handling symbolic links. +The +.Dq logical +mode follows all symbolic links. +The +.Dq physical +mode does not follow any symbolic links. +The +.Dq hybrid +mode currently behaves identically to the +.Dq logical +mode. +.It Xo +.Fn archive_read_disk_gname , +.Fn archive_read_disk_uname +.Xc +Returns a user or group name given a gid or uid value. +By default, these always return a NULL string. +.It Xo +.Fn archive_read_disk_set_gname_lookup , +.Fn archive_read_disk_set_uname_lookup +.Xc +These allow you to override the functions used for +user and group name lookups. +You may also provide a +.Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +.Tn struct archive +object is destroyed or when new lookup functions are registered. +.It Fn archive_read_disk_set_standard_lookup +This convenience function installs a standard set of user +and group name lookup functions. +These functions use +.Xr getpwuid 3 +and +.Xr getgrgid 3 +to convert ids to names, defaulting to NULL if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +.Xr getpwuid 3 +and +.Xr getgrgid 3 . +.It Fn archive_read_disk_entry_from_file +Populates a +.Tn struct archive_entry +object with information about a particular file. +The +.Tn archive_entry +object must have already been created with +.Xr archive_entry_new 3 +and at least one of the source path or path fields must already be set. +(If both are set, the source path will be used.) +.Pp +Information is read from disk using the path name from the +.Tn struct archive_entry +object. +If a file descriptor is provided, some information will be obtained using +that file descriptor, on platforms that support the appropriate +system calls. +.Pp +If a pointer to a +.Tn struct stat +is provided, information from that structure will be used instead +of reading from the disk where appropriate. +This can provide performance benefits in scenarios where +.Tn struct stat +information has already been read from the disk as a side effect +of some other operation. +(For example, directory traversal libraries often provide this information.) +.Pp +Where necessary, user and group ids are converted to user and group names +using the currently-registered lookup functions above. +This affects the file ownership fields and ACL values in the +.Tn struct archive_entry +object. +.It Fn archive_read_disk_descend +If the current entry can be descended, this function will mark the directory as the next entry for +.Xr archive_read_header 3 +to visit. +.It Fn archive_read_disk_can_descend +Returns 1 if the current entry is an unvisited directory and 0 otherwise. +.It Fn archive_read_disk_current_filesystem +Returns the index of the most recent filesystem entry that has been visited through archive_read_disk +.It Fn archive_read_disk_current_filesystem_is_synthetic +Returns 1 if the current filesystem is a virtual filesystem. Returns 0 if the current filesystem is not a virtual filesystem. Returns -1 if it is unknown. +.It Fn archive_read_disk_current_filesystem_is_remote +Returns 1 if the current filesystem is a remote filesystem. Returns 0 if the current filesystem is not a remote filesystem. Returns -1 if it is unknown. +.It Fn archive_read_disk_set_matching +Allows the caller to set +.Tn struct archive +*_ma to compare each entry during +.Xr archive_read_header 3 +calls. If matched based on calls to +.Tn archive_match_path_excluded , +.Tn archive_match_time_excluded , +or +.Tn archive_match_owner_excluded , +then the callback function specified by the _excluded_func parameter will execute. This function will receive data provided to the fourth parameter, void *_client_data. +.It Fn archive_read_disk_set_metadata_filter_callback +Allows the caller to set a callback function during calls to +.Xr archive_read_header 3 +to filter out metadata for each entry. The callback function receives the +.Tn struct archive +object, void* custom filter data, and the +.Tn struct archive_entry . +If the callback function returns an error, ARCHIVE_RETRY will be returned and the entry will not be further processed. +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +.Sh EXAMPLES +The following illustrates basic usage of the library by +showing how to use it to copy an item on disk into an archive. +.Bd -literal -offset indent +void +file_to_archive(struct archive *a, const char *name) +{ + char buff[8192]; + size_t bytes_read; + struct archive *ard; + struct archive_entry *entry; + int fd; + + ard = archive_read_disk_new(); + archive_read_disk_set_standard_lookup(ard); + entry = archive_entry_new(); + fd = open(name, O_RDONLY); + if (fd < 0) + return; + archive_entry_copy_pathname(entry, name); + archive_read_disk_entry_from_file(ard, entry, fd, NULL); + archive_write_header(a, entry); + while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) + archive_write_data(a, buff, bytes_read); + archive_write_finish_entry(a); + archive_read_free(ard); + archive_entry_free(entry); +} +.Ed +.Sh RETURN VALUES +Most functions return +.Cm ARCHIVE_OK +(zero) on success, or one of several negative +error codes for errors. +Specific error codes include: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +.Pp +.Fn archive_read_disk_new +returns a pointer to a newly-allocated +.Tn struct archive +object or NULL if the allocation failed for any reason. +.Pp +.Fn archive_read_disk_gname +and +.Fn archive_read_disk_uname +return +.Tn const char * +pointers to the textual name or NULL if the lookup failed for any reason. +The returned pointer points to internal storage that +may be reused on the next call to either of these functions; +callers should copy the string if they need to continue accessing it. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_util 3 , +.Xr archive_write 3 , +.Xr archive_write_disk 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +The +.Nm archive_read_disk +interface was added to +.Nm libarchive 2.6 +and first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@FreeBSD.org . +.Sh BUGS +The +.Dq standard +user name and group name lookup functions are not the defaults because +.Xr getgrgid 3 +and +.Xr getpwuid 3 +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +.Pp +The full list of metadata read from disk by +.Fn archive_read_disk_entry_from_file +is necessarily system-dependent. +.Pp +The +.Fn archive_read_disk_entry_from_file +function reads as much information as it can from disk. +Some method should be provided to limit this so that clients who +do not need ACLs, for instance, can avoid the extra work needed +to look up such information. +.Pp +This API should provide a set of methods for walking a directory tree. +That would make it a direct parallel of the +.Xr archive_read 3 +API. +When such methods are implemented, the +.Dq hybrid +symbolic link mode will make sense. diff --git a/static/netbsd/man3/archive_read_extract.3 b/static/netbsd/man3/archive_read_extract.3 new file mode 100644 index 00000000..f3feb5ad --- /dev/null +++ b/static/netbsd/man3/archive_read_extract.3 @@ -0,0 +1,135 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_EXTRACT 3 +.Os +.Sh NAME +.Nm archive_read_extract , +.Nm archive_read_extract2 , +.Nm archive_read_extract_set_progress_callback +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_read_extract +.Fa "struct archive *" +.Fa "struct archive_entry *" +.Fa "int flags" +.Fc +.Ft int +.Fo archive_read_extract2 +.Fa "struct archive *src" +.Fa "struct archive_entry *" +.Fa "struct archive *dest" +.Fc +.Ft void +.Fo archive_read_extract_set_progress_callback +.Fa "struct archive *" +.Fa "void (*func)(void *)" +.Fa "void *user_data" +.Fc +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Fn archive_read_extract , Fn archive_read_extract_set_skip_file +A convenience function that wraps the corresponding +.Xr archive_write_disk 3 +interfaces. +The first call to +.Fn archive_read_extract +creates a restore object using +.Xr archive_write_disk_new 3 +and +.Xr archive_write_disk_set_standard_lookup 3 , +then transparently invokes +.Xr archive_write_disk_set_options 3 , +.Xr archive_write_header 3 , +.Xr archive_write_data 3 , +and +.Xr archive_write_finish_entry 3 +to create the entry on disk and copy data into it. +The +.Va flags +argument is passed unmodified to +.Xr archive_write_disk_set_options 3 . +.It Fn archive_read_extract2 +This is another version of +.Fn archive_read_extract +that allows you to provide your own restore object. +In particular, this allows you to override the standard lookup functions +using +.Xr archive_write_disk_set_group_lookup 3 , +and +.Xr archive_write_disk_set_user_lookup 3 . +Note that +.Fn archive_read_extract2 +does not accept a +.Va flags +argument; you should use +.Fn archive_write_disk_set_options +to set the restore options yourself. +.It Fn archive_read_extract_set_progress_callback +Sets a pointer to a user-defined callback that can be used +for updating progress displays during extraction. +The progress function will be invoked during the extraction of large +regular files. +The progress function will be invoked with the pointer provided to this call. +Generally, the data pointed to should include a reference to the archive +object and the archive_entry object so that various statistics +can be retrieved for the progress display. +.El +.\" +.Sh RETURN VALUES +Most functions return zero on success, non-zero on error. +The possible return codes include: +.Cm ARCHIVE_OK +(the operation succeeded), +.Cm ARCHIVE_WARN +(the operation succeeded but a non-critical error was encountered), +.Cm ARCHIVE_EOF +(end-of-archive was encountered), +.Cm ARCHIVE_RETRY +(the operation failed but can be retried), +and +.Cm ARCHIVE_FATAL +(there was a fatal error; the archive should be closed immediately). +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_read_data 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_open 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_read_filter.3 b/static/netbsd/man3/archive_read_filter.3 new file mode 100644 index 00000000..72ff240f --- /dev/null +++ b/static/netbsd/man3/archive_read_filter.3 @@ -0,0 +1,162 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 9, 2020 +.Dt ARCHIVE_READ_FILTER 3 +.Os +.Sh NAME +.Nm archive_read_support_filter_all , +.Nm archive_read_support_filter_bzip2 , +.Nm archive_read_support_filter_compress , +.Nm archive_read_support_filter_gzip , +.Nm archive_read_support_filter_lz4 , +.Nm archive_read_support_filter_lzma , +.Nm archive_read_support_filter_none , +.Nm archive_read_support_filter_rpm , +.Nm archive_read_support_filter_uu , +.Nm archive_read_support_filter_xz , +.Nm archive_read_support_filter_zstd , +.Nm archive_read_support_filter_program , +.Nm archive_read_support_filter_program_signature +.Nd functions for reading streaming archives +.\" +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_read_support_filter_all "struct archive *" +.Ft int +.Fn archive_read_support_filter_by_code "struct archive *" "int" +.Ft int +.Fn archive_read_support_filter_bzip2 "struct archive *" +.Ft int +.Fn archive_read_support_filter_compress "struct archive *" +.Ft int +.Fn archive_read_support_filter_grzip "struct archive *" +.Ft int +.Fn archive_read_support_filter_gzip "struct archive *" +.Ft int +.Fn archive_read_support_filter_lrzip "struct archive *" +.Ft int +.Fn archive_read_support_filter_lz4 "struct archive *" +.Ft int +.Fn archive_read_support_filter_lzma "struct archive *" +.Ft int +.Fn archive_read_support_filter_lzop "struct archive *" +.Ft int +.Fn archive_read_support_filter_none "struct archive *" +.Ft int +.Fn archive_read_support_filter_rpm "struct archive *" +.Ft int +.Fn archive_read_support_filter_uu "struct archive *" +.Ft int +.Fn archive_read_support_filter_xz "struct archive *" +.Ft int +.Fn archive_read_support_filter_zstd "struct archive *" +.Ft int +.Fo archive_read_support_filter_program +.Fa "struct archive *" +.Fa "const char *cmd" +.Fc +.Ft int +.Fo archive_read_support_filter_program_signature +.Fa "struct archive *" +.Fa "const char *cmd" +.Fa "const void *signature" +.Fa "size_t signature_length" +.Fc +.\" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Xo +.Fn archive_read_support_filter_bzip2 , +.Fn archive_read_support_filter_compress , +.Fn archive_read_support_filter_grzip , +.Fn archive_read_support_filter_gzip , +.Fn archive_read_support_filter_lrzip , +.Fn archive_read_support_filter_lz4 , +.Fn archive_read_support_filter_lzma , +.Fn archive_read_support_filter_lzop , +.Fn archive_read_support_filter_none , +.Fn archive_read_support_filter_rpm , +.Fn archive_read_support_filter_uu , +.Fn archive_read_support_filter_xz , +.Fn archive_read_support_filter_zstd , +.Xc +Enables auto-detection code and decompression support for the +specified compression. +These functions may fall back on external programs if an appropriate +library was not available at build time. +Decompression using an external program is usually slower than +decompression through built-in libraries. +Note that +.Dq none +is always enabled by default. +.It Fn archive_read_support_filter_all +Enables all available decompression filters. +.It Fn archive_read_support_filter_by_code +Enables a single filter specified by the filter code. +This function does not work with +.Cm ARCHIVE_FILTER_PROGRAM . +Note: In statically-linked executables, this will cause +your program to include support for every filter. +If executable size is a concern, you may wish to avoid +using this function. +.It Fn archive_read_support_filter_program +Data is fed through the specified external program before being dearchived. +Note that this disables automatic detection of the compression format, +so it makes no sense to specify this in conjunction with any other +decompression option. +.It Fn archive_read_support_filter_program_signature +This feeds data through the specified external program +but only if the initial bytes of the data match the specified +signature value. +.El +.\" +.\". Sh EXAMPLE +.\" +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +if the compression is fully supported, +.Cm ARCHIVE_WARN +if the compression is supported only through an external program. +.Pp +.Fn archive_read_support_filter_none +always succeeds. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr archive_read 3 , +.Xr archive_read_data 3 , +.Xr archive_read_format 3 , +.Xr archive_read_format 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_read_format.3 b/static/netbsd/man3/archive_read_format.3 new file mode 100644 index 00000000..660cc74a --- /dev/null +++ b/static/netbsd/man3/archive_read_format.3 @@ -0,0 +1,190 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_FORMAT 3 +.Os +.Sh NAME +.Nm archive_read_support_format_7zip , +.Nm archive_read_support_format_all , +.Nm archive_read_support_format_ar , +.Nm archive_read_support_format_by_code , +.Nm archive_read_support_format_cab , +.Nm archive_read_support_format_cpio , +.Nm archive_read_support_format_empty , +.Nm archive_read_support_format_iso9660 , +.Nm archive_read_support_format_lha , +.Nm archive_read_support_format_mtree , +.Nm archive_read_support_format_rar , +.Nm archive_read_support_format_rar5 , +.Nm archive_read_support_format_raw , +.Nm archive_read_support_format_tar , +.Nm archive_read_support_format_warc , +.Nm archive_read_support_format_xar , +.Nm archive_read_support_format_zip +.Nd functions for reading streaming archives +.\" +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_read_support_format_7zip "struct archive *" +.Ft int +.Fn archive_read_support_format_all "struct archive *" +.Ft int +.Fn archive_read_support_format_ar "struct archive *" +.Ft int +.Fn archive_read_support_format_by_code "struct archive *" "int" +.Ft int +.Fn archive_read_support_format_cab "struct archive *" +.Ft int +.Fn archive_read_support_format_cpio "struct archive *" +.Ft int +.Fn archive_read_support_format_empty "struct archive *" +.Ft int +.Fn archive_read_support_format_iso9660 "struct archive *" +.Ft int +.Fn archive_read_support_format_lha "struct archive *" +.Ft int +.Fn archive_read_support_format_mtree "struct archive *" +.Ft int +.Fn archive_read_support_format_rar "struct archive *" +.Ft int +.Fn archive_read_support_format_rar5 "struct archive *" +.Ft int +.Fn archive_read_support_format_raw "struct archive *" +.Ft int +.Fn archive_read_support_format_tar "struct archive *" +.Ft int +.Fn archive_read_support_format_warc "struct archive *" +.Ft int +.Fn archive_read_support_format_xar "struct archive *" +.Ft int +.Fn archive_read_support_format_zip "struct archive *" +.\" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Xo +.Fn archive_read_support_format_7zip , +.Fn archive_read_support_format_ar , +.Fn archive_read_support_format_cab , +.Fn archive_read_support_format_cpio , +.Fn archive_read_support_format_iso9660 , +.Fn archive_read_support_format_lha , +.Fn archive_read_support_format_mtree , +.Fn archive_read_support_format_rar , +.Fn archive_read_support_format_rar5 , +.Fn archive_read_support_format_raw , +.Fn archive_read_support_format_tar , +.Fn archive_read_support_format_warc , +.Fn archive_read_support_format_xar , +.Fn archive_read_support_format_zip +.Xc +Enables support---including auto-detection code---for the +specified archive format. +For example, +.Fn archive_read_support_format_tar +enables support for a variety of standard tar formats, old-style tar, +ustar, pax interchange format, and many common variants. +.Fn archive_read_support_format_zip +enables support for both the streaming and the seeking zip readers, +which can separately be enabled by respectively +.Fn archive_read_support_format_zip_streamable +and +.Fn archive_read_support_format_zip_seekable +. +.It Fn archive_read_support_format_all +Enables support for all available formats except the +.Dq raw +format (see below). +.It Fn archive_read_support_format_by_code +Enables a single format specified by the format code. +This can be useful when reading a single archive twice; +use +.Fn archive_format +after reading the first time and pass the resulting code +to this function to selectively enable only the necessary +format support. +Note: In statically-linked executables, this will cause +your program to include support for every format. +If executable size is a concern, you may wish to avoid +using this function. +.It Fn archive_read_support_format_empty +Enables support for treating empty files as empty archives. +Because empty files are valid for several different formats, +it is not possible to accurately determine a format for +an empty file based purely on contents. +So empty files are treated by libarchive as a distinct +format. +.It Fn archive_read_support_format_raw +The +.Dq raw +format handler allows libarchive to be used to read arbitrary data. +It treats any data stream as an archive with a single entry. +The pathname of this entry is +.Dq data ; +all other entry fields are unset. +This is not enabled by +.Fn archive_read_support_format_all +in order to avoid erroneous handling of damaged archives. +.El +.\" .Sh EXAMPLE +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read_data 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 +.Sh BUGS +Many traditional archiver programs treat +empty files as valid empty archives. +For example, many implementations of +.Xr tar 1 +allow you to append entries to an empty file. +Of course, it is impossible to determine the format of an empty file +by inspecting the contents, so this library treats empty files as +having a special +.Dq empty +format. +.Pp +Using the +.Dq raw +handler together with any other handler will often work +but can produce surprising results. diff --git a/static/netbsd/man3/archive_read_free.3 b/static/netbsd/man3/archive_read_free.3 new file mode 100644 index 00000000..7dc121fc --- /dev/null +++ b/static/netbsd/man3/archive_read_free.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_FREE 3 +.Os +.Sh NAME +.Nm archive_read_close , +.Nm archive_read_finish , +.Nm archive_read_free +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_read_close "struct archive *" +.Ft int +.Fn archive_read_finish "struct archive *" +.Ft int +.Fn archive_read_free "struct archive *" +.\" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Fn archive_read_close +Complete the archive and invoke the close callback. +.It Fn archive_read_finish +This is a deprecated synonym for +.Fn archive_read_free . +The new name was introduced with libarchive 3.0. +Applications that need to compile with either libarchive 2 +or libarchive 3 should continue to use the +.Fn archive_read_finish +name. +Both names will be supported until libarchive 4.0 is +released, which is not expected to occur earlier +than 2013. +.It Fn archive_read_free +Invokes +.Fn archive_read_close +if it was not invoked manually, then release all resources. +Note: In libarchive 1.x, this function was declared to return +.Ft void , +which made it impossible to detect certain errors when +.Fn archive_read_close +was invoked implicitly from this function. +The declaration is corrected beginning with libarchive 2.0. +.El +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr archive_read_data 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_new 3 , +.Xr archive_read_open 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_read_header.3 b/static/netbsd/man3/archive_read_header.3 new file mode 100644 index 00000000..024dc41d --- /dev/null +++ b/static/netbsd/man3/archive_read_header.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_HEADER 3 +.Os +.Sh NAME +.Nm archive_read_next_header , +.Nm archive_read_next_header2 +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_read_next_header "struct archive *" "struct archive_entry **" +.Ft int +.Fn archive_read_next_header2 "struct archive *" "struct archive_entry *" +.\" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Fn archive_read_next_header +Read the header for the next entry and return a pointer to +a +.Tn struct archive_entry . +This is a convenience wrapper around +.Fn archive_read_next_header2 +that reuses an internal +.Tn struct archive_entry +object for each request. +.It Fn archive_read_next_header2 +Read the header for the next entry and populate the provided +.Tn struct archive_entry . +.El +.\" +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +(the operation succeeded), +.Cm ARCHIVE_WARN +(the operation succeeded but a non-critical error was encountered), +.Cm ARCHIVE_EOF +(end-of-archive was encountered), +.Cm ARCHIVE_RETRY +(the operation failed but can be retried), +and +.Cm ARCHIVE_FATAL +(there was a fatal error; the archive should be closed immediately). +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_read_data 3 , +.Xr archive_read_extract 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_open 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_read_new.3 b/static/netbsd/man3/archive_read_new.3 new file mode 100644 index 00000000..c2b5cdde --- /dev/null +++ b/static/netbsd/man3/archive_read_new.3 @@ -0,0 +1,57 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_NEW 3 +.Os +.Sh NAME +.Nm archive_read_new +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_read_new "void" +.Sh DESCRIPTION +Allocates and initializes a +.Tn struct archive +object suitable for reading from an archive. +.Dv NULL +is returned on error. +.Pp +A complete description of the +.Tn struct archive +object can be found in the overview manual page for +.Xr libarchive 3 . +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read_data 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_read_open.3 b/static/netbsd/man3/archive_read_open.3 new file mode 100644 index 00000000..081b7114 --- /dev/null +++ b/static/netbsd/man3/archive_read_open.3 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_READ_OPEN 3 +.Os +.Sh NAME +.Nm archive_read_open , +.Nm archive_read_open2 , +.Nm archive_read_open_fd , +.Nm archive_read_open_FILE , +.Nm archive_read_open_filename , +.Nm archive_read_open_memory +.Nd functions for reading streaming archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_read_open +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_read_callback *" +.Fa "archive_close_callback *" +.Fc +.Ft int +.Fo archive_read_open2 +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_read_callback *" +.Fa "archive_skip_callback *" +.Fa "archive_close_callback *" +.Fc +.Ft int +.Fn archive_read_open_FILE "struct archive *" "FILE *file" +.Ft int +.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size" +.Ft int +.Fo archive_read_open_filename +.Fa "struct archive *" +.Fa "const char *filename" +.Fa "size_t block_size" +.Fc +.Ft int +.Fn archive_read_open_memory "struct archive *" "const void *buff" "size_t size" +.Sh DESCRIPTION +.Bl -tag -compact -width indent +.It Fn archive_read_open +The same as +.Fn archive_read_open2 , +except that the skip callback is assumed to be +.Dv NULL . +.It Fn archive_read_open2 +Freeze the settings, open the archive, and prepare for reading entries. +This is the most generic version of this call, which accepts +four callback functions. +Most clients will want to use +.Fn archive_read_open_filename , +.Fn archive_read_open_FILE , +.Fn archive_read_open_fd , +or +.Fn archive_read_open_memory +instead. +The library invokes the client-provided functions to obtain +raw bytes from the archive. +.It Fn archive_read_open_FILE +Like +.Fn archive_read_open , +except that it accepts a +.Ft "FILE *" +pointer. +This function should not be used with tape drives or other devices +that require strict I/O blocking. +.It Fn archive_read_open_fd +Like +.Fn archive_read_open , +except that it accepts a file descriptor and block size rather than +a set of function pointers. +Note that the file descriptor will not be automatically closed at +end-of-archive. +This function is safe for use with tape drives or other blocked devices. +.It Fn archive_read_open_file +This is a deprecated synonym for +.Fn archive_read_open_filename . +.It Fn archive_read_open_filename +Like +.Fn archive_read_open , +except that it accepts a simple filename and a block size. +A NULL filename represents standard input. +This function is safe for use with tape drives or other blocked devices. +.It Fn archive_read_open_memory +Like +.Fn archive_read_open , +except that it accepts a pointer and size of a block of +memory containing the archive data. +.El +.Pp +A complete description of the +.Tn struct archive +and +.Tn struct archive_entry +objects can be found in the overview manual page for +.Xr libarchive 3 . +.Sh CLIENT CALLBACKS +The callback functions must match the following prototypes: +.Bl -item -offset indent +.It +.Ft typedef la_ssize_t +.Fo archive_read_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "const void **buffer" +.Fc +.It +.Ft typedef la_int64_t +.Fo archive_skip_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "off_t request" +.Fc +.It +.Ft typedef int +.Fn archive_open_callback "struct archive *" "void *client_data" +.It +.Ft typedef int +.Fn archive_close_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.Fn archive_set_error +to register an error code and message and return +.Cm ARCHIVE_FATAL . +.Pp +The read callback is invoked whenever the library +requires raw bytes from the archive. +The read callback should read data into a buffer, +set the +.Li const void **buffer +argument to point to the available data, and +return a count of the number of bytes available. +The library will invoke the read callback again +only after it has consumed this data. +The library imposes no constraints on the size +of the data blocks returned. +On end-of-file, the read callback should +return zero. +On error, the read callback should invoke +.Fn archive_set_error +to register an error code and message and +return -1. +.Pp +The skip callback is invoked when the +library wants to ignore a block of data. +The return value is the number of bytes actually +skipped, which may differ from the request. +If the callback cannot skip data, it should return +zero. +If the skip callback is not provided (the +function pointer is +.Dv NULL ), +the library will invoke the read function +instead and simply discard the result. +A skip callback can provide significant +performance gains when reading uncompressed +archives from slow disk drives or other media +that can skip quickly. +.Pp +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +return +.Cm ARCHIVE_FATAL . +.\" .Sh EXAMPLE +.\" +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_read_data 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr libarchive 3 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_read_set_options.3 b/static/netbsd/man3/archive_read_set_options.3 new file mode 100644 index 00000000..ef18dfaa --- /dev/null +++ b/static/netbsd/man3/archive_read_set_options.3 @@ -0,0 +1,290 @@ +.\" Copyright (c) 2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 31, 2020 +.Dt ARCHIVE_READ_OPTIONS 3 +.Os +.Sh NAME +.Nm archive_read_set_filter_option , +.Nm archive_read_set_format_option , +.Nm archive_read_set_option , +.Nm archive_read_set_options +.Nd functions controlling options for reading archives +.\" +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.Ft int +.Fo archive_read_set_filter_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_read_set_format_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_read_set_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_read_set_options +.Fa "struct archive *" +.Fa "const char *options" +.Fc +.Sh DESCRIPTION +These functions provide a way for libarchive clients to configure +specific read modules. +.Bl -tag -width indent +.It Xo +.Fn archive_read_set_filter_option , +.Fn archive_read_set_format_option +.Xc +Specifies an option that will be passed to currently-registered +filters (including decompression filters) or format readers. +.Pp +If +.Ar option +and +.Ar value +are both +.Dv NULL , +these functions will do nothing and +.Cm ARCHIVE_OK +will be returned. +If +.Ar option +is +.Dv NULL +but +.Ar value +is not, these functions will do nothing and +.Cm ARCHIVE_FAILED +will be returned. +.Pp +If +.Ar module +is not +.Dv NULL , +.Ar option +and +.Ar value +will be provided to the filter or reader named +.Ar module . +The return value will be that of the module. +If there is no such module, +.Cm ARCHIVE_FAILED +will be returned. +.Pp +If +.Ar module +is +.Dv NULL , +.Ar option +and +.Ar value +will be provided to every registered module. +If any module returns +.Cm ARCHIVE_FATAL , +this value will be returned immediately. +Otherwise, +.Cm ARCHIVE_OK +will be returned if any module accepts the option, and +.Cm ARCHIVE_FAILED +in all other cases. +.\" +.It Xo +.Fn archive_read_set_option +.Xc +Calls +.Fn archive_read_set_format_option , +then +.Fn archive_read_set_filter_option . +If either function returns +.Cm ARCHIVE_FATAL , +.Cm ARCHIVE_FATAL +will be returned +immediately. +Otherwise, greater of the two values will be returned. +.\" +.It Xo +.Fn archive_read_set_options +.Xc +.Ar options +is a comma-separated list of options. +If +.Ar options +is +.Dv NULL +or empty, +.Cm ARCHIVE_OK +will be returned immediately. +.Pp +Calls +.Fn archive_read_set_option +with each option in turn. +If any +.Fn archive_read_set_option +call returns +.Cm ARCHIVE_FATAL , +.Cm ARCHIVE_FATAL +will be returned immediately. +.Pp +Individual options have one of the following forms: +.Bl -tag -compact -width indent +.It Ar option=value +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.It Ar option +The option will be provided to every module with a value of +.Dq 1 . +.It Ar !option +The option will be provided to every module with a NULL value. +.It Ar module:option=value , Ar module:option , Ar module:!option +As above, but the corresponding option and value will be provided +only to modules whose name matches +.Ar module . +.El +.El +.\" +.Sh OPTIONS +.Bl -tag -compact -width indent +.It Format cab +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format cpio +.Bl -tag -compact -width indent +.It Cm compat-2x +Libarchive 2.x incorrectly encoded Unicode filenames on +some platforms. +This option mimics the libarchive 2.x filename handling +so that such archives can be read correctly. +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.It Cm pwb +When reading a binary CPIO archive, assume that it is +in the original PWB cpio format, and handle file mode +bits accordingly. The default is to assume v7 format. +.El +.It Format iso9660 +.Bl -tag -compact -width indent +.It Cm joliet +Support Joliet extensions. +Defaults to enabled, use +.Cm !joliet +to disable. +.It Cm rockridge +Support RockRidge extensions. +Defaults to enabled, use +.Cm !rockridge +to disable. +.El +.It Format lha +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format mtree +.Bl -tag -compact -width indent +.It Cm checkfs +Allow reading information missing from the mtree from the file system. +Disabled by default. +.El +.It Format rar +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format tar +.Bl -tag -compact -width indent +.It Cm compat-2x +Libarchive 2.x incorrectly encoded Unicode filenames on +some platforms. +This option mimics the libarchive 2.x filename handling +so that such archives can be read correctly. +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.It Cm mac-ext +Support Mac OS metadata extension that records data in special +files beginning with a period and underscore. +Defaults to enabled on Mac OS, disabled on other platforms. +Use +.Cm !mac-ext +to disable. +.It Cm read_concatenated_archives +Ignore zeroed blocks in the archive, which occurs when multiple tar archives +have been concatenated together. +Without this option, only the contents of +the first concatenated archive would be read. +.El +.It Format zip +.Bl -tag -compact -width indent +.It Cm compat-2x +Libarchive 2.x incorrectly encoded Unicode filenames on +some platforms. +This option mimics the libarchive 2.x filename handling +so that such archives can be read correctly. +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.It Cm ignorecrc32 +Skip the CRC32 check. +Mostly used for testing. +.It Cm mac-ext +Support Mac OS metadata extension that records data in special +files beginning with a period and underscore. +Defaults to enabled on Mac OS, disabled on other platforms. +Use +.Cm !mac-ext +to disable. +.El +.El +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/archive_util.3 b/static/netbsd/man3/archive_util.3 new file mode 100644 index 00000000..3aa508f2 --- /dev/null +++ b/static/netbsd/man3/archive_util.3 @@ -0,0 +1,222 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_UTIL 3 +.Os +.Sh NAME +.Nm archive_clear_error , +.Nm archive_compression , +.Nm archive_compression_name , +.Nm archive_copy_error , +.Nm archive_errno , +.Nm archive_error_string , +.Nm archive_file_count , +.Nm archive_filter_code , +.Nm archive_filter_count , +.Nm archive_filter_name , +.Nm archive_format , +.Nm archive_format_name , +.Nm archive_position , +.Nm archive_set_error +.Nd libarchive utility functions +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft void +.Fn archive_clear_error "struct archive *" +.Ft int +.Fn archive_compression "struct archive *" +.Ft const char * +.Fn archive_compression_name "struct archive *" +.Ft void +.Fn archive_copy_error "struct archive *" "struct archive *" +.Ft int +.Fn archive_errno "struct archive *" +.Ft const char * +.Fn archive_error_string "struct archive *" +.Ft int +.Fn archive_file_count "struct archive *" +.Ft int +.Fn archive_filter_code "struct archive *" "int" +.Ft int +.Fn archive_filter_count "struct archive *" "int" +.Ft const char * +.Fn archive_filter_name "struct archive *" "int" +.Ft int +.Fn archive_format "struct archive *" +.Ft const char * +.Fn archive_format_name "struct archive *" +.Ft int64_t +.Fn archive_position "struct archive *" "int" +.Ft void +.Fo archive_set_error +.Fa "struct archive *" +.Fa "int error_code" +.Fa "const char *fmt" +.Fa "..." +.Fc +.Sh DESCRIPTION +These functions provide access to various information about the +.Tn struct archive +object used in the +.Xr libarchive 3 +library. +.Bl -tag -compact -width indent +.It Fn archive_clear_error +Clears any error information left over from a previous call. +Not generally used in client code. +.It Fn archive_compression +Synonym for +.Fn archive_filter_code a 0 . +.It Fn archive_compression_name +Synonym for +.Fn archive_filter_name a 0 . +.It Fn archive_copy_error +Copies error information from one archive to another. +.It Fn archive_errno +Returns a numeric error code (see +.Xr errno 2 ) +indicating the reason for the most recent error return. +Note that this can not be reliably used to detect whether an +error has occurred. +It should be used only after another libarchive function +has returned an error status. +.It Fn archive_error_string +Returns a textual error message suitable for display. +The error message here is usually more specific than that +obtained from passing the result of +.Fn archive_errno +to +.Xr strerror 3 . +.It Fn archive_file_count +Returns a count of the number of files processed by this archive object. +The count is incremented by calls to +.Xr archive_write_header 3 +or +.Xr archive_read_next_header 3 . +.It Fn archive_filter_code +Returns a numeric code identifying the indicated filter. +See +.Fn archive_filter_count +for details of the numbering. +.It Fn archive_filter_count +Returns the number of filters in the current pipeline. +For read archive handles, these filters are added automatically +by the automatic format detection. +For write archive handles, these filters are added by calls to the various +.Fn archive_write_add_filter_XXX +functions. +Filters in the resulting pipeline are numbered so that filter 0 +is the filter closest to the format handler. +As a convenience, functions that expect a filter number will +accept -1 as a synonym for the highest-numbered filter. +.Pp +For example, when reading a uuencoded gzipped tar archive, there +are three filters: +filter 0 is the gunzip filter, +filter 1 is the uudecode filter, +and filter 2 is the pseudo-filter that wraps the archive read functions. +In this case, requesting +.Fn archive_position a -1 +would be a synonym for +.Fn archive_position a 2 +which would return the number of bytes currently read from the archive, while +.Fn archive_position a 1 +would return the number of bytes after uudecoding, and +.Fn archive_position a 0 +would return the number of bytes after decompression. +.It Fn archive_filter_name +Returns a textual name identifying the indicated filter. +See +.Fn archive_filter_count +for details of the numbering. +.It Fn archive_format +Returns a numeric code indicating the format of the current +archive entry. +This value is set by a successful call to +.Fn archive_read_next_header . +Note that it is common for this value to change from +entry to entry. +For example, a tar archive might have several entries that +utilize GNU tar extensions and several entries that do not. +These entries will have different format codes. +.It Fn archive_format_name +A textual description of the format of the current entry. +.It Fn archive_position +Returns the number of bytes read from or written to the indicated filter. +In particular, +.Fn archive_position a 0 +returns the number of bytes read or written by the format handler, while +.Fn archive_position a -1 +returns the number of bytes read or written to the archive. +See +.Fn archive_filter_count +for details of the numbering here. +.It Fn archive_set_error +Sets the numeric error code and error description that will be returned +by +.Fn archive_errno +and +.Fn archive_error_string . +This function should be used within I/O callbacks to set system-specific +error codes and error descriptions. +This function accepts a printf-like format string and arguments. +However, you should be careful to use only the following printf +format specifiers: +.Dq %c , +.Dq %d , +.Dq %jd , +.Dq %jo , +.Dq %ju , +.Dq %jx , +.Dq %ld , +.Dq %lo , +.Dq %lu , +.Dq %lx , +.Dq %o , +.Dq %u , +.Dq %s , +.Dq %x , +.Dq %% . +Field-width specifiers and other printf features are +not uniformly supported and should not be used. +.El +.Sh SEE ALSO +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr libarchive 3 , +.Xr printf 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . diff --git a/static/netbsd/man3/archive_write.3 b/static/netbsd/man3/archive_write.3 new file mode 100644 index 00000000..227e4e02 --- /dev/null +++ b/static/netbsd/man3/archive_write.3 @@ -0,0 +1,266 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_WRITE 3 +.Os +.Sh NAME +.Nm archive_write +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Sh DESCRIPTION +These functions provide a complete API for creating streaming +archive files. +The general process is to first create the +.Tn struct archive +object, set any desired options, initialize the archive, append entries, then +close the archive and release all resources. +.\" +.Ss Create archive object +See +.Xr archive_write_new 3 . +.Pp +To write an archive, you must first obtain an initialized +.Tn struct archive +object from +.Fn archive_write_new . +.\" +.Ss Enable filters and formats, configure block size and padding +See +.Xr archive_write_filter 3 , +.Xr archive_write_format 3 +and +.Xr archive_write_blocksize 3 . +.Pp +You can then modify this object for the desired operations with the +various +.Fn archive_write_set_XXX +functions. +In particular, you will need to invoke appropriate +.Fn archive_write_add_XXX +and +.Fn archive_write_set_XXX +functions to enable the corresponding compression and format +support. +.\" +.Ss Set options +See +.Xr archive_write_set_options 3 . +.\" +.Ss Open archive +See +.Xr archive_write_open 3 . +.Pp +Once you have prepared the +.Tn struct archive +object, you call +.Fn archive_write_open +to actually open the archive and prepare it for writing. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, +.Ft "FILE *" +object, or a block of memory from which to write the archive data. +.\" +.Ss Produce archive +See +.Xr archive_write_header 3 +and +.Xr archive_write_data 3 . +.Pp +Individual archive entries are written in a three-step +process: +You first initialize a +.Tn struct archive_entry +structure with information about the new entry. +At a minimum, you should set the pathname of the +entry and provide a +.Va struct stat +with a valid +.Va st_mode +field, which specifies the type of object and +.Va st_size +field, which specifies the size of the data portion of the object. +.\" +.Ss Release resources +See +.Xr archive_write_free 3 . +.Pp +After all entries have been written, use the +.Fn archive_write_free +function to release all resources. +.\" +.Sh EXAMPLES +The following sketch illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +.Xr open 2 , +.Xr write 2 , +and +.Xr close 2 +system calls. +.Bd -literal -offset indent +#ifdef __linux__ +#define _FILE_OFFSET_BITS 64 +#endif +#include +#include +#include +#include +#include +#include + +struct mydata { + const char *name; + int fd; +}; + +int +myopen(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + + mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); + if (mydata->fd >= 0) + return (ARCHIVE_OK); + else + return (ARCHIVE_FATAL); +} + +la_ssize_t +mywrite(struct archive *a, void *client_data, const void *buff, size_t n) +{ + struct mydata *mydata = client_data; + + return (write(mydata->fd, buff, n)); +} + +int +myclose(struct archive *a, void *client_data) +{ + struct mydata *mydata = client_data; + + if (mydata->fd > 0) + close(mydata->fd); + return (0); +} + +void +write_archive(const char *outname, const char **filename) +{ + struct mydata *mydata = malloc(sizeof(struct mydata)); + struct archive *a; + struct archive_entry *entry; + struct stat st; + char buff[8192]; + int len; + int fd; + + a = archive_write_new(); + mydata->name = outname; + /* Set archive format and filter according to output file extension. + * If it fails, set default format. Platform depended function. + * See supported formats in archive_write_set_format_filter_by_ext.c */ + if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) { + archive_write_add_filter_gzip(a); + archive_write_set_format_ustar(a); + } + archive_write_open(a, mydata, myopen, mywrite, myclose); + while (*filename) { + stat(*filename, &st); + entry = archive_entry_new(); + archive_entry_copy_stat(entry, &st); + archive_entry_set_pathname(entry, *filename); + archive_write_header(a, entry); + if ((fd = open(*filename, O_RDONLY)) != -1) { + len = read(fd, buff, sizeof(buff)); + while (len > 0) { + archive_write_data(a, buff, len); + len = read(fd, buff, sizeof(buff)); + } + close(fd); + } + archive_entry_free(entry); + filename++; + } + archive_write_free(a); +} + +int main(int argc, const char **argv) +{ + const char *outname; + argv++; + outname = *argv++; + write_archive(outname, argv); + return 0; +} +.Ed +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +There are many peculiar bugs in historic tar implementations that may cause +certain programs to reject archives written by this library. +For example, several historic implementations calculated header checksums +incorrectly and will thus reject valid archives; GNU tar does not fully support +pax interchange format; some old tar implementations required specific +field terminations. +.Pp +The default pax interchange format eliminates most of the historic +tar limitations and provides a generic key/value attribute facility +for vendor-defined extensions. +One oversight in POSIX is the failure to provide a standard attribute +for large device numbers. +This library uses +.Dq SCHILY.devminor +and +.Dq SCHILY.devmajor +for device numbers that exceed the range supported by the backwards-compatible +ustar header. +These keys are compatible with Joerg Schilling's +.Nm star +archiver. +Other implementations may not recognize these keys and will thus be unable +to correctly restore device nodes with large device numbers from archives +created by this library. diff --git a/static/netbsd/man3/archive_write_blocksize.3 b/static/netbsd/man3/archive_write_blocksize.3 new file mode 100644 index 00000000..3508851c --- /dev/null +++ b/static/netbsd/man3/archive_write_blocksize.3 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_WRITE_BLOCKSIZE 3 +.Os +.Sh NAME +.Nm archive_write_get_bytes_per_block , +.Nm archive_write_set_bytes_per_block , +.Nm archive_write_get_bytes_in_last_block , +.Nm archive_write_set_bytes_in_last_block +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_get_bytes_per_block "struct archive *" +.Ft int +.Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block" +.Ft int +.Fn archive_write_get_bytes_in_last_block "struct archive *" +.Ft int +.Fn archive_write_set_bytes_in_last_block "struct archive *" "int" +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_write_set_bytes_per_block +Sets the block size used for writing the archive data. +Every call to the write callback function, except possibly the last one, will +use this value for the length. +The default is to use a block size of 10240 bytes. +Note that a block size of zero will suppress internal blocking +and cause writes to be sent directly to the write callback as they occur. +.It Fn archive_write_get_bytes_per_block +Retrieve the block size to be used for writing. +A value of -1 here indicates that the library should use default values. +A value of zero indicates that internal blocking is suppressed. +.It Fn archive_write_set_bytes_in_last_block +Sets the block size used for writing the last block. +If this value is zero, the last block will be padded to the same size +as the other blocks. +Otherwise, the final block will be padded to a multiple of this size. +In particular, setting it to 1 will cause the final block to not be padded. +For compressed output, any padding generated by this option +is applied only after the compression. +The uncompressed data is always unpadded. +The default is to pad the last block to the full block size (note that +.Fn archive_write_open_filename +will set this based on the file type). +Unlike the other +.Dq set +functions, this function can be called after the archive is opened. +.It Fn archive_write_get_bytes_in_last_block +Retrieve the currently-set value for last block size. +A value of -1 here indicates that the library should use default values. +.El +.\" .Sh EXAMPLE +.Sh RETURN VALUES +.Fn archive_write_set_bytes_per_block +and +.Fn archive_write_set_bytes_in_last_block +return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.Pp +.Fn archive_write_get_bytes_per_block +and +.Fn archive_write_get_bytes_in_last_block +return currently configured block size +.Po +.Li -1 +indicates the default block size +.Pc , +or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_data.3 b/static/netbsd/man3/archive_write_data.3 new file mode 100644 index 00000000..9f239f7c --- /dev/null +++ b/static/netbsd/man3/archive_write_data.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 28, 2017 +.Dt ARCHIVE_WRITE_DATA 3 +.Os +.Sh NAME +.Nm archive_write_data , +.Nm archive_write_data_block +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft la_ssize_t +.Fn archive_write_data "struct archive *" "const void *" "size_t" +.Ft la_ssize_t +.Fn archive_write_data_block "struct archive *" "const void *" "size_t size" "int64_t offset" +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_write_data +Write data corresponding to the header just written. +.It Fn archive_write_data_block +Write data corresponding to the header just written. +This is like +.Fn archive_write_data +except that it performs a seek on the file being +written to the specified offset before writing the data. +This is useful when restoring sparse files from archive +formats that support sparse files. +Returns number of bytes written or -1 on error. +(Note: This is currently not supported for +.Tn archive_write +handles, only for +.Tn archive_write_disk +handles. +.El +.\" .Sh EXAMPLE +.\" +.Sh RETURN VALUES +This function returns the number of bytes actually written, or +a negative error code on error. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh BUGS +In libarchive 3.x, this function sometimes returns +zero on success instead of returning the number of bytes written. +Specifically, this occurs when writing to an +.Vt archive_write_disk +handle. +Clients should treat any value less than zero as an error +and consider any non-negative value as success. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_finish_entry 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_disk.3 b/static/netbsd/man3/archive_write_disk.3 new file mode 100644 index 00000000..b046168c --- /dev/null +++ b/static/netbsd/man3/archive_write_disk.3 @@ -0,0 +1,360 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 19, 2020 +.Dt ARCHIVE_WRITE_DISK 3 +.Os +.Sh NAME +.Nm archive_write_disk_new , +.Nm archive_write_disk_set_options , +.Nm archive_write_disk_set_skip_file , +.Nm archive_write_disk_set_group_lookup , +.Nm archive_write_disk_set_standard_lookup , +.Nm archive_write_disk_set_user_lookup +.Nd functions for creating objects on disk +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_write_disk_new "void" +.Ft int +.Fn archive_write_disk_set_options "struct archive *" "int flags" +.Ft int +.Fn archive_write_disk_set_skip_file "struct archive *" "dev_t" "ino_t" +.Ft int +.Fo archive_write_disk_set_group_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "gid_t (*)(void *, const char *gname, gid_t gid)" +.Fa "void (*cleanup)(void *)" +.Fc +.Ft int +.Fn archive_write_disk_set_standard_lookup "struct archive *" +.Ft int +.Fo archive_write_disk_set_user_lookup +.Fa "struct archive *" +.Fa "void *" +.Fa "uid_t (*)(void *, const char *uname, uid_t uid)" +.Fa "void (*cleanup)(void *)" +.Fc +.Sh DESCRIPTION +These functions provide a complete API for creating objects on +disk from +.Tn struct archive_entry +descriptions. +They are most naturally used when extracting objects from an archive +using the +.Fn archive_read +interface. +The general process is to read +.Tn struct archive_entry +objects from an archive, then write those objects to a +.Tn struct archive +object created using the +.Fn archive_write_disk +family functions. +This interface is deliberately very similar to the +.Fn archive_write +interface used to write objects to a streaming archive. +.Bl -tag -width indent +.It Fn archive_write_disk_new +Allocates and initializes a +.Tn struct archive +object suitable for writing objects to disk. +.It Fn archive_write_disk_set_skip_file +Records the device and inode numbers of a file that should not be +overwritten. +This is typically used to ensure that an extraction process does not +overwrite the archive from which objects are being read. +This capability is technically unnecessary but can be a significant +performance optimization in practice. +.It Fn archive_write_disk_set_options +The options field consists of a bitwise OR of one or more of the +following values: +.Bl -tag -compact -width "indent" +.It Cm ARCHIVE_EXTRACT_ACL +Attempt to restore Access Control Lists. +By default, extended ACLs are ignored. +.It Cm ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS +Before removing a file system object prior to replacing it, clear +platform-specific file flags which might prevent its removal. +.It Cm ARCHIVE_EXTRACT_FFLAGS +Attempt to restore file attributes (file flags). +By default, file attributes are ignored. +See +.Xr chattr 1 +.Pq Linux +or +.Xr chflags 1 +.Pq FreeBSD, Mac OS X +for more information on file attributes. +.It Cm ARCHIVE_EXTRACT_MAC_METADATA +Mac OS X specific. +Restore metadata using +.Xr copyfile 3 . +By default, +.Xr copyfile 3 +metadata is ignored. +.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE +Existing files on disk will not be overwritten. +By default, existing regular files are truncated and overwritten; +existing directories will have their permissions updated; +other pre-existing objects are unlinked and recreated from scratch. +.It Cm ARCHIVE_EXTRACT_OWNER +The user and group IDs should be set on the restored file. +By default, the user and group IDs are not restored. +.It Cm ARCHIVE_EXTRACT_PERM +Full permissions (including SGID, SUID, and sticky bits) should +be restored exactly as specified, without obeying the +current umask. +Note that SUID and SGID bits can only be restored if the +user and group ID of the object on disk are correct. +If +.Cm ARCHIVE_EXTRACT_OWNER +is not specified, then SUID and SGID bits will only be restored +if the default user and group IDs of newly-created objects on disk +happen to match those specified in the archive entry. +By default, only basic permissions are restored, and umask is obeyed. +.It Cm ARCHIVE_EXTRACT_SAFE_WRITES +Extract files atomically, by first creating a unique temporary file and then +renaming it to its required destination name. +This avoids a race where an application might see a partial file (or no +file) during extraction. +.It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS +Refuse to extract an absolute path. +The default is to not refuse such paths. +.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT +Refuse to extract a path that contains a +.Pa .. +element anywhere within it. +The default is to not refuse such paths. +Note that paths ending in +.Pa .. +always cause an error, regardless of this flag. +.It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS +Refuse to extract any object whose final location would be altered +by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. +The default is not to perform this check. +If +.Cm ARCHIVE_EXTRACT_UNLINK +is specified together with this option, the library will +remove any intermediate symlinks it finds and return an +error only if such symlink could not be removed. +.It Cm ARCHIVE_EXTRACT_SPARSE +Scan data for blocks of NUL bytes and try to recreate them with holes. +This results in sparse files, independent of whether the archive format +supports or uses them. +.It Cm ARCHIVE_EXTRACT_TIME +The timestamps (mtime, ctime, and atime) should be restored. +By default, they are ignored. +Note that restoring of atime is not currently supported. +.It Cm ARCHIVE_EXTRACT_UNLINK +Existing files on disk will be unlinked before any attempt to +create them. +In some cases, this can prove to be a significant performance improvement. +By default, existing files are truncated and rewritten, but +the file is not recreated. +In particular, the default behavior does not break existing hard links. +.It Cm ARCHIVE_EXTRACT_XATTR +Attempt to restore extended file attributes. +By default, they are ignored. +See +.Xr xattr 7 +.Pq Linux , +.Xr xattr 2 +.Pq Mac OS X , +or +.Xr getextattr 8 +.Pq FreeBSD +for more information on extended file attributes. +.El +.It Xo +.Fn archive_write_disk_set_group_lookup , +.Fn archive_write_disk_set_user_lookup +.Xc +The +.Tn struct archive_entry +objects contain both names and ids that can be used to identify users +and groups. +These names and ids describe the ownership of the file itself and +also appear in ACL lists. +By default, the library uses the ids and ignores the names, but +this can be overridden by registering user and group lookup functions. +To register, you must provide a lookup function which +accepts both a name and id and returns a suitable id. +You may also provide a +.Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +.Tn struct archive +object is destroyed. +.It Fn archive_write_disk_set_standard_lookup +This convenience function installs a standard set of user +and group lookup functions. +These functions use +.Xr getpwnam 3 +and +.Xr getgrnam 3 +to convert names to ids, defaulting to the ids if the names cannot +be looked up. +These functions also implement a simple memory cache to reduce +the number of calls to +.Xr getpwnam 3 +and +.Xr getgrnam 3 . +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +Many of these functions are also documented under +.Xr archive_write 3 . +.Sh RETURN VALUES +Most functions return +.Cm ARCHIVE_OK +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +.Pp +.Fn archive_write_disk_new +returns a pointer to a newly-allocated +.Tn struct archive +object. +.Pp +.Fn archive_write_data +returns a count of the number of bytes actually written, +or +.Li -1 +on error. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +The +.Nm archive_write_disk +interface was added to +.Nm libarchive 2.0 +and first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Directories are actually extracted in two distinct phases. +Directories are created during +.Fn archive_write_header , +but final permissions are not set until +.Fn archive_write_close . +This separation is necessary to correctly handle borderline +cases such as a non-writable directory containing +files, but can cause unexpected results. +In particular, directory permissions are not fully +restored until the archive is closed. +If you use +.Xr chdir 2 +to change the current directory between calls to +.Fn archive_read_extract +or before calling +.Fn archive_read_close , +you may confuse the permission-setting logic with +the result that directory permissions are restored +incorrectly. +.Pp +The library attempts to create objects with filenames longer than +.Cm PATH_MAX +by creating prefixes of the full path and changing the current directory. +Currently, this logic is limited in scope; the fixup pass does +not work correctly for such objects and the symlink security check +option disables the support for very long pathnames. +.Pp +Restoring the path +.Pa aa/../bb +does create each intermediate directory. +In particular, the directory +.Pa aa +is created as well as the final object +.Pa bb . +In theory, this can be exploited to create an entire directory hierarchy +with a single request. +Of course, this does not work if the +.Cm ARCHIVE_EXTRACT_NODOTDOT +option is specified. +.Pp +Implicit directories are always created obeying the current umask. +Explicit objects are created obeying the current umask unless +.Cm ARCHIVE_EXTRACT_PERM +is specified, in which case they current umask is ignored. +.Pp +SGID and SUID bits are restored only if the correct user and +group could be set. +If +.Cm ARCHIVE_EXTRACT_OWNER +is not specified, then no attempt is made to set the ownership. +In this case, SGID and SUID bits are restored only if the +user and group of the final object happen to match those specified +in the entry. +.Pp +The +.Dq standard +user-id and group-id lookup functions are not the defaults because +.Xr getgrnam 3 +and +.Xr getpwnam 3 +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +.Pp +There should be a corresponding +.Nm archive_read_disk +interface that walks a directory hierarchy and returns archive +entry objects. diff --git a/static/netbsd/man3/archive_write_filter.3 b/static/netbsd/man3/archive_write_filter.3 new file mode 100644 index 00000000..b39cabe0 --- /dev/null +++ b/static/netbsd/man3/archive_write_filter.3 @@ -0,0 +1,132 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 14, 2014 +.Dt ARCHIVE_WRITE_FILTER 3 +.Os +.Sh NAME +.Nm archive_write_add_filter_b64encode , +.Nm archive_write_add_filter_by_name , +.Nm archive_write_add_filter_bzip2 , +.Nm archive_write_add_filter_compress , +.Nm archive_write_add_filter_grzip , +.Nm archive_write_add_filter_gzip , +.Nm archive_write_add_filter_lrzip , +.Nm archive_write_add_filter_lz4 , +.Nm archive_write_add_filter_lzip , +.Nm archive_write_add_filter_lzma , +.Nm archive_write_add_filter_lzop , +.Nm archive_write_add_filter_none , +.Nm archive_write_add_filter_program , +.Nm archive_write_add_filter_uuencode , +.Nm archive_write_add_filter_xz , +.Nm archive_write_add_filter_zstd +.Nd functions enabling output filters +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_add_filter_b64encode "struct archive *" +.Ft int +.Fn archive_write_add_filter_bzip2 "struct archive *" +.Ft int +.Fn archive_write_add_filter_compress "struct archive *" +.Ft int +.Fn archive_write_add_filter_grzip "struct archive *" +.Ft int +.Fn archive_write_add_filter_gzip "struct archive *" +.Ft int +.Fn archive_write_add_filter_lrzip "struct archive *" +.Ft int +.Fn archive_write_add_filter_lz4 "struct archive *" +.Ft int +.Fn archive_write_add_filter_lzip "struct archive *" +.Ft int +.Fn archive_write_add_filter_lzma "struct archive *" +.Ft int +.Fn archive_write_add_filter_lzop "struct archive *" +.Ft int +.Fn archive_write_add_filter_none "struct archive *" +.Ft int +.Fn archive_write_add_filter_program "struct archive *" "const char * cmd" +.Ft int +.Fn archive_write_add_filter_uuencode "struct archive *" +.Ft int +.Fn archive_write_add_filter_xz "struct archive *" +.Ft int +.Fn archive_write_add_filter_zstd "struct archive *" +.Sh DESCRIPTION +.Bl -tag -width indent +.It Xo +.Fn archive_write_add_filter_bzip2 , +.Fn archive_write_add_filter_compress , +.Fn archive_write_add_filter_grzip , +.Fn archive_write_add_filter_gzip , +.Fn archive_write_add_filter_lrzip , +.Fn archive_write_add_filter_lz4 , +.Fn archive_write_add_filter_lzip , +.Fn archive_write_add_filter_lzma , +.Fn archive_write_add_filter_lzop , +.Fn archive_write_add_filter_xz , +.Fn archive_write_add_filter_zstd , +.Xc +The resulting archive will be compressed as specified. +Note that the compressed output is always properly blocked. +.It Xo +.Fn archive_write_add_filter_b64encode , +.Fn archive_write_add_filter_uuencode , +.Xc +The output will be encoded as specified. +The encoded output is always properly blocked. +.It Fn archive_write_add_filter_none +This is never necessary. +It is provided only for backwards compatibility. +.It Fn archive_write_add_filter_program +The archive will be fed into the specified compression program. +The output of that program is blocked and written to the client +write callbacks. +.El +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write 3 , +.Xr archive_write_format 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_finish_entry.3 b/static/netbsd/man3/archive_write_finish_entry.3 new file mode 100644 index 00000000..574d6008 --- /dev/null +++ b/static/netbsd/man3/archive_write_finish_entry.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 28, 2017 +.Dt ARCHIVE_WRITE_FINISH_ENTRY 3 +.Os +.Sh NAME +.Nm archive_write_finish_entry +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_finish_entry "struct archive *" +.Sh DESCRIPTION +Close out the entry just written. +In particular, this writes out the final padding required by some formats. +Ordinarily, clients never need to call this, as it +is called automatically by +.Fn archive_write_header +and +.Fn archive_write_close +as needed. +For +.Tn archive_write_disk +handles, this flushes pending file attribute changes like modification time. +.\" .Sh EXAMPLE +.Sh RETURN VALUES +This function returns +.Cm ARCHIVE_OK +on success, or one of several non-zero +error codes for errors. +Specific error codes include: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_data 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_format.3 b/static/netbsd/man3/archive_write_format.3 new file mode 100644 index 00000000..9e331368 --- /dev/null +++ b/static/netbsd/man3/archive_write_format.3 @@ -0,0 +1,185 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 14, 2013 +.Dt ARCHIVE_WRITE_FORMAT 3 +.Os +.Sh NAME +.Nm archive_write_set_format , +.Nm archive_write_set_format_7zip , +.Nm archive_write_set_format_ar , +.Nm archive_write_set_format_ar_bsd , +.Nm archive_write_set_format_ar_svr4 , +.Nm archive_write_set_format_by_name , +.Nm archive_write_set_format_cpio , +.Nm archive_write_set_format_cpio_bin , +.Nm archive_write_set_format_cpio_newc , +.Nm archive_write_set_format_cpio_odc , +.Nm archive_write_set_format_cpio_pwb , +.Nm archive_write_set_format_filter_by_ext , +.Nm archive_write_set_format_filter_by_ext_def , +.Nm archive_write_set_format_gnutar , +.Nm archive_write_set_format_iso9660 , +.Nm archive_write_set_format_mtree , +.Nm archive_write_set_format_mtree_classic , +.Nm archive_write_set_format_mtree_default , +.Nm archive_write_set_format_pax , +.Nm archive_write_set_format_pax_restricted , +.Nm archive_write_set_format_raw , +.Nm archive_write_set_format_shar , +.Nm archive_write_set_format_shar_dump , +.Nm archive_write_set_format_ustar , +.Nm archive_write_set_format_v7tar , +.Nm archive_write_set_format_warc , +.Nm archive_write_set_format_xar , +.Nm archive_write_set_format_zip +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_set_format "struct archive *" "int code" +.Ft int +.Fn archive_write_set_format_7zip "struct archive *" +.Ft int +.Fn archive_write_set_format_ar "struct archive *" +.Ft int +.Fn archive_write_set_format_ar_bsd "struct archive *" +.Ft int +.Fn archive_write_set_format_ar_svr4 "struct archive *" +.Ft int +.Fn archive_write_set_format_by_name "struct archive *" "const char *name" +.Ft int +.Fn archive_write_set_format_cpio "struct archive *" +.Ft int +.Fn archive_write_set_format_cpio_bin "struct archive *" +.Ft int +.Fn archive_write_set_format_cpio_newc "struct archive *" +.Ft int +.Fn archive_write_set_format_cpio_odc "struct archive *" +.Ft int +.Fn archive_write_set_format_cpio_pwb "struct archive *" +.Ft int +.Fn archive_write_set_format_filter_by_ext "struct archive *" "const char *filename" +.Ft int +.Fn archive_write_set_format_filter_by_ext_def "struct archive *" "const char *filename" "const char *def_ext" +.Ft int +.Fn archive_write_set_format_gnutar "struct archive *" +.Ft int +.Fn archive_write_set_format_iso9660 "struct archive *" +.Ft int +.Fn archive_write_set_format_mtree "struct archive *" +.Ft int +.Fn archive_write_set_format_pax "struct archive *" +.Ft int +.Fn archive_write_set_format_pax_restricted "struct archive *" +.Ft int +.Fn archive_write_set_format_raw "struct archive *" +.Ft int +.Fn archive_write_set_format_shar "struct archive *" +.Ft int +.Fn archive_write_set_format_shar_dump "struct archive *" +.Ft int +.Fn archive_write_set_format_ustar "struct archive *" +.Ft int +.Fn archive_write_set_format_v7tar "struct archive *" +.Ft int +.Fn archive_write_set_format_warc "struct archive *" +.Ft int +.Fn archive_write_set_format_xar "struct archive *" +.Ft int +.Fn archive_write_set_format_zip "struct archive *" +.Sh DESCRIPTION +These functions set the format that will be used for the archive. +.Pp +The library can write a variety of common archive formats. +.Bl -tag -width indent +.It Fn archive_write_set_format +Sets the format based on the format code (see +.Pa archive.h +for the full list of format codes). +In particular, this can be used in conjunction with +.Fn archive_format +to create a new archive with the same format as an existing archive. +.It Fn archive_write_set_format_by_name +Sets the corresponding format based on the common name. +.It Xo +.Fn archive_write_set_format_filter_by_ext +.Fn archive_write_set_format_filter_by_ext_def +.Xc +Sets both filters and format based on the output filename. +Supported extensions: .7z, .zip, .jar, .cpio, .iso, .a, .ar, .tar, .tgz, .tar.gz, .tar.bz2, .tar.xz +.It Xo +.Fn archive_write_set_format_7zip +.Fn archive_write_set_format_ar_bsd +.Fn archive_write_set_format_ar_svr4 +.Fn archive_write_set_format_cpio +.Fn archive_write_set_format_cpio_bin +.Fn archive_write_set_format_cpio_newc +.Fn archive_write_set_format_cpio_odc +.Fn archive_write_set_format_cpio_pwb +.Fn archive_write_set_format_gnutar +.Fn archive_write_set_format_iso9660 +.Fn archive_write_set_format_mtree +.Fn archive_write_set_format_mtree_classic +.Fn archive_write_set_format_pax +.Fn archive_write_set_format_pax_restricted +.Fn archive_write_set_format_raw +.Fn archive_write_set_format_shar +.Fn archive_write_set_format_shar_dump +.Fn archive_write_set_format_ustar +.Fn archive_write_set_format_v7tar +.Fn archive_write_set_format_warc +.Fn archive_write_set_format_xar +.Fn archive_write_set_format_zip +.Xc +Set the format as specified. +More details on the formats supported by libarchive can be found in the +.Xr libarchive-formats 5 +manual page. +.El +.\" +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr libarchive-formats 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_free.3 b/static/netbsd/man3/archive_write_free.3 new file mode 100644 index 00000000..f6b84eae --- /dev/null +++ b/static/netbsd/man3/archive_write_free.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_WRITE_FREE 3 +.Os +.Sh NAME +.Nm archive_write_fail , +.Nm archive_write_close , +.Nm archive_write_finish , +.Nm archive_write_free +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_fail "struct archive *" +.Ft int +.Fn archive_write_close "struct archive *" +.Ft int +.Fn archive_write_finish "struct archive *" +.Ft int +.Fn archive_write_free "struct archive *" +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_write_fail +Always returns +.Cm ARCHIVE_FATAL . +This marks the archive object as being unusable; +after calling this function, the only call that can succeed is +.Fn archive_write_free +to release the resources. +This can be used to speed recovery when the archive creation +must be aborted. +Note that the created archive is likely to be malformed in this case; +.It Fn archive_write_close +Complete the archive and invoke the close callback. +.It Fn archive_write_finish +This is a deprecated synonym for +.Fn archive_write_free . +.It Fn archive_write_free +Invokes +.Fn archive_write_close +if necessary, then releases all resources. +If you need detailed information about +.Fn archive_write_close +failures, you should be careful to call it separately, as +you cannot obtain error information after +.Fn archive_write_free +returns. +.El +.\" .Sh EXAMPLE +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_header.3 b/static/netbsd/man3/archive_write_header.3 new file mode 100644 index 00000000..9c6ecec4 --- /dev/null +++ b/static/netbsd/man3/archive_write_header.3 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_WRITE_HEADER 3 +.Os +.Sh NAME +.Nm archive_write_header +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fn archive_write_header "struct archive *" "struct archive_entry *" +.Sh DESCRIPTION +Build and write a header using the data in the provided +.Tn struct archive_entry +structure. +See +.Xr archive_entry 3 +for information on creating and populating +.Tn struct archive_entry +objects. +.\" .Sh EXAMPLE +.Sh RETURN VALUES +This function returns +.Cm ARCHIVE_OK +on success, or one of the following on error: +.Cm ARCHIVE_RETRY +for operations that might succeed if retried, +.Cm ARCHIVE_WARN +for unusual conditions that do not prevent further operations, and +.Cm ARCHIVE_FATAL +for serious errors that make remaining operations impossible. +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_new.3 b/static/netbsd/man3/archive_write_new.3 new file mode 100644 index 00000000..15a7c407 --- /dev/null +++ b/static/netbsd/man3/archive_write_new.3 @@ -0,0 +1,56 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 2, 2012 +.Dt ARCHIVE_WRITE_NEW 3 +.Os +.Sh NAME +.Nm archive_write_new +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft struct archive * +.Fn archive_write_new "void" +.Sh DESCRIPTION +Allocates and initializes a +.Tn struct archive +object suitable for writing a tar archive. +.Dv NULL +is returned on error. +.Pp +A complete description of the +.Tn struct archive +object can be found in the overview manual page for +.Xr libarchive 3 . +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_open.3 b/static/netbsd/man3/archive_write_open.3 new file mode 100644 index 00000000..b12d0970 --- /dev/null +++ b/static/netbsd/man3/archive_write_open.3 @@ -0,0 +1,270 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 12, 2020 +.Dt ARCHIVE_WRITE_OPEN 3 +.Os +.Sh NAME +.Nm archive_write_open , +.Nm archive_write_open2 , +.Nm archive_write_open_fd , +.Nm archive_write_open_FILE , +.Nm archive_write_open_filename , +.Nm archive_write_open_memory +.Nd functions for creating archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_write_open +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_write_callback *" +.Fa "archive_close_callback *" +.Fc +.Ft int +.Fo archive_write_open2 +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_write_callback *" +.Fa "archive_close_callback *" +.Fa "archive_free_callback *" +.Fc +.Ft int +.Fn archive_write_open_fd "struct archive *" "int fd" +.Ft int +.Fn archive_write_open_FILE "struct archive *" "FILE *file" +.Ft int +.Fn archive_write_open_filename "struct archive *" "const char *filename" +.Ft int +.Fo archive_write_open_memory +.Fa "struct archive *" +.Fa "void *buffer" +.Fa "size_t bufferSize" +.Fa "size_t *outUsed" +.Fc +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_write_open +Freeze the settings, open the archive, and prepare for writing entries. +This is the most generic form of this function, which accepts +pointers to three callback functions which will be invoked by +the compression layer to write the constructed archive. +This does not alter the default archive padding. +.It Fn archive_write_open2 +Same as +.Fn archive_write_open +with an additional fourth free callback. This function should be preferred to +.Fn archive_write_open . +.It Fn archive_write_open_fd +A convenience form of +.Fn archive_write_open +that accepts a file descriptor. +The +.Fn archive_write_open_fd +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_FILE +A convenience form of +.Fn archive_write_open +that accepts a +.Ft "FILE *" +pointer. +Note that +.Fn archive_write_open_FILE +is not safe for writing to tape drives or other devices +that require correct blocking. +.It Fn archive_write_open_file +A deprecated synonym for +.Fn archive_write_open_filename . +.It Fn archive_write_open_filename +A convenience form of +.Fn archive_write_open +that accepts a filename. +A NULL argument indicates that the output should be written to standard output; +an argument of +.Dq - +will open a file with that name. +If you have not invoked +.Fn archive_write_set_bytes_in_last_block , +then +.Fn archive_write_open_filename +will adjust the last-block padding depending on the file: +it will enable padding when writing to standard output or +to a character or block device node, it will disable padding otherwise. +You can override this by manually invoking +.Fn archive_write_set_bytes_in_last_block +before calling +.Fn archive_write_open2 . +The +.Fn archive_write_open_filename +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_memory +A convenience form of +.Fn archive_write_open2 +that accepts a pointer to a block of memory that will receive +the archive. +The final +.Ft "size_t *" +argument points to a variable that will be updated +after each write to reflect how much of the buffer +is currently in use. +You should be careful to ensure that this variable +remains allocated until after the archive is +closed. +This function will disable padding unless you +have specifically set the block size. +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +.Pp +Note that the convenience forms above vary in how +they block the output. +See +.Xr archive_write_blocksize 3 +if you need to control the block size used for writes +or the end-of-file padding behavior. +.\" +.Sh CLIENT CALLBACKS +To use this library, you will need to define and register +callback functions that will be invoked to write data to the +resulting archive. +These functions are registered by calling +.Fn archive_write_open2 : +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_open_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_write_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.Fn archive_set_error +to register an error code and message and return +.Cm ARCHIVE_FATAL . +Please note that if open fails, close is not called and resources must be +freed inside the open callback or with the free callback. +.Bl -item -offset indent +.It +.Ft typedef la_ssize_t +.Fo archive_write_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "const void *buffer" +.Fa "size_t length" +.Fc +.El +.Pp +The write callback is invoked whenever the library +needs to write raw bytes to the archive. +For correct blocking, each call to the write callback function +should translate into a single +.Xr write 2 +system call. +This is especially critical when writing archives to tape drives. +On success, the write callback should return the +number of bytes actually written. +On error, the callback should invoke +.Fn archive_set_error +to register an error code and message and return -1. +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_close_callback "struct archive *" "void *client_data" +.El +.Pp +The close callback is invoked by archive_close when +the archive processing is complete. If the open callback fails, the close +callback is not invoked. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +return +.Cm ARCHIVE_FATAL . +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_free_callback "struct archive *" "void *client_data" +.El +.Pp +The free callback is always invoked on archive_free. +The return code of this callback is not processed. +.Pp +Note that if the client-provided write callback function +returns a non-zero value, that error will be propagated back to the caller +through whatever API function resulted in that call, which +may include +.Fn archive_write_header , +.Fn archive_write_data , +.Fn archive_write_close , +.Fn archive_write_finish , +or +.Fn archive_write_free . +The client callback can call +.Fn archive_set_error +to provide values that can then be retrieved by +.Fn archive_errno +and +.Fn archive_error_string . +.\" .Sh EXAMPLE +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.\" +.Sh ERRORS +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write 3 , +.Xr archive_write_blocksize 3 , +.Xr archive_write_filter 3 , +.Xr archive_write_format 3 , +.Xr archive_write_new 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5 diff --git a/static/netbsd/man3/archive_write_set_options.3 b/static/netbsd/man3/archive_write_set_options.3 new file mode 100644 index 00000000..c3de50c8 --- /dev/null +++ b/static/netbsd/man3/archive_write_set_options.3 @@ -0,0 +1,761 @@ +.\" Copyright (c) 2003-2010 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 31, 2020 +.Dt ARCHIVE_WRITE_OPTIONS 3 +.Os +.Sh NAME +.Nm archive_write_set_filter_option , +.Nm archive_write_set_format_option , +.Nm archive_write_set_option , +.Nm archive_write_set_options +.Nd functions controlling options for writing archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.Ft int +.Fo archive_write_set_filter_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_write_set_format_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_write_set_option +.Fa "struct archive *" +.Fa "const char *module" +.Fa "const char *option" +.Fa "const char *value" +.Fc +.Ft int +.Fo archive_write_set_options +.Fa "struct archive *" +.Fa "const char *options" +.Fc +.Sh DESCRIPTION +These functions provide a way for libarchive clients to configure +specific write modules. +.Bl -tag -width indent +.It Xo +.Fn archive_write_set_filter_option , +.Fn archive_write_set_format_option +.Xc +Specifies an option that will be passed to the currently-registered +filters (including decompression filters) or format readers. +.Pp +If +.Ar option +and +.Ar value +are both +.Dv NULL , +these functions will do nothing and +.Cm ARCHIVE_OK +will be returned. +If +.Ar option +is +.Dv NULL +but +.Ar value +is not, these functions will do nothing and +.Cm ARCHIVE_FAILED +will be returned. +.Pp +If +.Ar module +is not +.Dv NULL , +.Ar option +and +.Ar value +will be provided to the filter or reader named +.Ar module . +The return value will be either +.Cm ARCHIVE_OK +if the option was successfully handled or +.Cm ARCHIVE_WARN +if the option was unrecognized by the module or could otherwise +not be handled. +If there is no such module, +.Cm ARCHIVE_FAILED +will be returned. +.Pp +If +.Ar module +is +.Dv NULL , +.Ar option +and +.Ar value +will be provided to every registered module. +If any module returns +.Cm ARCHIVE_FATAL , +this value will be returned immediately. +Otherwise, +.Cm ARCHIVE_OK +will be returned if any module accepts the option, and +.Cm ARCHIVE_FAILED +in all other cases. +.\" +.It Fn archive_write_set_option +Calls +.Fn archive_write_set_format_option , +then +.Fn archive_write_set_filter_option . +If either function returns +.Cm ARCHIVE_FATAL , +.Cm ARCHIVE_FATAL +will be returned +immediately. +Otherwise, the greater of the two values will be returned. +.\" +.It Fn archive_write_set_options +.Ar options +is a comma-separated list of options. +If +.Ar options +is +.Dv NULL +or empty, +.Cm ARCHIVE_OK +will be returned immediately. +.Pp +Individual options have one of the following forms: +.Bl -tag -compact -width indent +.It Ar option=value +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.It Ar option +The option will be provided to every module with a value of +.Dq 1 . +.It Ar !option +The option will be provided to every module with a NULL value. +.It Ar module:option=value , Ar module:option , Ar module:!option +As above, but the corresponding option and value will be provided +only to modules whose name matches +.Ar module . +.El +.El +.\" +.Sh OPTIONS +.Bl -tag -compact -width indent +.It Filter b64encode +.Bl -tag -compact -width indent +.It Cm mode +The value is interpreted as octal digits specifying the file mode. +.It Cm name +The value specifies the file name. +.El +.It Filter bzip2 +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +bzip2 compression level. Supported values are from 1 to 9. +.El +.It Filter gzip +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +gzip compression level. Supported values are from 0 to 9. +.It Cm timestamp +Store timestamp. This is enabled by default. +.El +.It Filter lrzip +.Bl -tag -compact -width indent +.It Cm compression Ns = Ns Ar type +Use +.Ar type +as compression method. +Supported values are +.Dq bzip2 , +.Dq gzipi , +.Dq lzo +.Pq ultra fast , +and +.Dq zpaq +.Pq best, extremely slow . +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +lrzip compression level. Supported values are from 1 to 9. +.El +.It Filter lz4 +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +lz4 compression level. Supported values are from 0 to 9. +.It Cm stream-checksum +Enable stream checksum. This is enabled by default. +.It Cm block-checksum +Enable block checksum. This is disabled by default. +.It Cm block-size +The value is interpreted as a decimal integer specifying the +lz4 compression block size. Supported values are from 4 to 7 +.Pq default . +.It Cm block-dependence +Use the previous block of the block being compressed for +a compression dictionary to improve compression ratio. +This is disabled by default. +.El +.It Filter lzop +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +lzop compression level. Supported values are from 1 to 9. +.El +.It Filter uuencode +.Bl -tag -compact -width indent +.It Cm mode +The value is interpreted as octal digits specifying the file mode. +.It Cm name +The value specifies the file name. +.El +.It Filter xz +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +compression level. Supported values are from 0 to 9. +.It Cm threads +The value is interpreted as a decimal integer specifying the +number of threads for multi-threaded lzma compression. +If supported, the default value is read from +.Fn lzma_cputhreads . +.El +.It Filter zstd +.Bl -tag -compact -width indent +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +compression level. Supported values depend on the library version, +common values are from 1 to 22. +.It Cm long +Enables long distance matching. The value is interpreted as a +decimal integer specifying log2 window size in bytes. Values from +10 to 30 for 32 bit, or 31 for 64 bit, are supported. +.It Cm threads +The value is interpreted as a decimal integer specifying the +number of threads for multi-threaded zstd compression. +If set to 0, zstd will attempt to detect and use the number +of active physical CPU cores. +.El +.It Format 7zip +.Bl -tag -compact -width indent +.It Cm compression +The value is one of +.Dq store , +.Dq copy , +.Dq deflate , +.Dq bzip2 , +.Dq lzma1 , +.Dq lzma2 , +.Dq ppmd , +or +.Dq zstd +to indicate how the following entries should be compressed. +The values +.Dq store +and +.Dq copy +are synonyms. +Note that this setting is ignored for directories, symbolic links, +and other special entries. +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +compression level. +Values between 0 and 9 are supported, with the exception of bzip2 +which only supports values between 1 and 9, and zstd which may +support negative values depending on the library version and +commonly used values 1 through 22. +The interpretation of the compression level depends on the chosen +compression method. +.It Cm threads +The value is interpreted as a decimal integer specifying the +number of threads for multi-threaded compression (for compressors +like zstd that support it). If set to 0, an attempt will be made +to discover the number of CPU cores. +.El +.It Format bin +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format gnutar +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file, group and user names. +.El +.It Format iso9660 - volume metadata +These options are used to set standard ISO9660 metadata. +.Bl -tag -compact -width indent +.It Cm abstract-file Ns = Ns Ar filename +The file with the specified name will be identified in the ISO9660 metadata +as holding the abstract for this volume. +Default: none. +.It Cm application-id Ns = Ns Ar filename +The file with the specified name will be identified in the ISO9660 metadata +as holding the application identifier for this volume. +Default: none. +.It Cm biblio-file Ns = Ns Ar filename +The file with the specified name will be identified in the ISO9660 metadata +as holding the bibliography for this volume. +Default: none. +.It Cm copyright-file Ns = Ns Ar filename +The file with the specified name will be identified in the ISO9660 metadata +as holding the copyright for this volume. +Default: none. +.It Cm publisher Ns = Ns Ar filename +The file with the specified name will be identified in the ISO9660 metadata +as holding the publisher information for this volume. +Default: none. +.It Cm volume-id Ns = Ns Ar string +The specified string will be used as the Volume Identifier in the ISO9660 metadata. +It is limited to 32 bytes. +Default: none. +.El +.It Format iso9660 - boot support +These options are used to make an ISO9660 image that can be directly +booted on various systems. +.Bl -tag -compact -width indent +.It Cm boot Ns = Ns Ar filename +The file matching this name will be used as the El Torito boot image file. +.It Cm boot-catalog Ns = Ns Ar name +The name that will be used for the El Torito boot catalog. +Default: +.Ar boot.catalog +.It Cm boot-info-table +The boot image file provided by the +.Cm boot Ns = Ns Ar filename +option will be edited with appropriate boot information in bytes 8 through 64. +Default: disabled +.It Cm boot-load-seg Ns = Ns Ar hexadecimal-number +The load segment for a no-emulation boot image. +.It Cm boot-load-size Ns = Ns Ar decimal-number +The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image. +Some very old BIOSes can only load very small images, setting this +value to 4 will often allow such BIOSes to load the first part of +the boot image (which will then need to be intelligent enough to +load the rest of itself). +This should not be needed unless you are trying to support systems with very old BIOSes. +This defaults to the full size of the image. +.It Cm boot-type Ns = Ns Ar value +Specifies the boot semantics used by the El Torito boot image: +If the +.Ar value +is +.Cm fd , +then the boot image is assumed to be a bootable floppy image. +If the +.Ar value +is +.Cm hd , +then the boot image is assumed to be a bootable hard disk image. +If the +.Ar value +is +.Cm no-emulation , +the boot image is used without floppy or hard disk emulation. +If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then +the default is +.Cm fd , +otherwise the default is +.Cm no-emulation . +.El +.It Format iso9660 - filename and size extensions +Various extensions to the base ISO9660 format. +.Bl -tag -compact -width indent +.It Cm allow-ldots +If enabled, allows filenames to begin with a leading period. +If disabled, filenames that begin with a leading period will have +that period replaced by an underscore character in the standard ISO9660 +namespace. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: disabled. +.It Cm allow-lowercase +If enabled, allows filenames to contain lowercase characters. +If disabled, filenames will be forced to uppercase. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: disabled. +.It Cm allow-multidot +If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification. +If disabled, additional periods will be converted to underscore characters. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: disabled. +.It Cm allow-period +If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification. +If disabled, trailing periods will be converted to underscore characters. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: disabled. +.It Cm allow-pvd-lowercase +If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification. +If disabled, characters will be converted to uppercase ASCII. +Default: disabled. +.It Cm allow-sharp-tilde +If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification. +If disabled, such characters will be converted to underscore characters. +Default: disabled. +.It Cm allow-vernum +If enabled, version numbers will be included with files. +If disabled, version numbers will be suppressed, in violation of the ISO9660 standard. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: enabled. +.It Cm iso-level +This enables support for file size and file name extensions in the +core ISO9660 area. +The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas. +.Bl -tag -compact -width indent +.It Cm iso-level=1 +The most compliant form of ISO9660 image. +Filenames are limited to 8.3 uppercase format, +directory names are limited to 8 uppercase characters, +files are limited to 4 GiB, +the complete ISO9660 image cannot exceed 4 GiB. +.It Cm iso-level=2 +Filenames are limited to 30 uppercase characters with a 30-character extension, +directory names are limited to 30 characters, +files are limited to 4 GiB. +.It Cm iso-level=3 +As with +.Cm iso-level=2 , +except that files may exceed 4 GiB. +.It Cm iso-level=4 +As with +.Cm iso-level=3 , +except that filenames may be up to 193 characters +and may include arbitrary 8-bit characters. +.El +.It Cm joliet +Microsoft's Joliet extensions store a completely separate set of directory information about each file. +In particular, this information includes Unicode filenames of up to 255 characters. +Default: enabled. +.It Cm limit-depth +If enabled, libarchive will use directory relocation records to ensure that +no pathname exceeds the ISO9660 limit of 8 directory levels. +If disabled, no relocation will occur. +Default: enabled. +.It Cm limit-dirs +If enabled, libarchive will cause an error if there are more than +65536 directories. +If disabled, there is no limit on the number of directories. +Default: enabled +.It Cm pad +If enabled, 300 kiB of zero bytes will be appended to the end of the archive. +Default: enabled +.It Cm relaxed-filenames +If enabled, all 7-bit ASCII characters are permitted in filenames +(except lowercase characters unless +.Cm allow-lowercase +is also specified). +This violates ISO9660 standards. +This does not impact names stored in the Rockridge or Joliet extension area. +Default: disabled. +.It Cm rockridge +The Rockridge extensions store an additional set of POSIX-style file +information with each file, including mtime, atime, ctime, permissions, +and long filenames with arbitrary 8-bit characters. +These extensions also support symbolic links and other POSIX file types. +Default: enabled. +.El +.It Format iso9660 - zisofs support +The zisofs extensions permit each file to be independently compressed +using a gzip-compatible compression. +This can provide significant size savings, but requires the reading +system to have support for these extensions. +These extensions are disabled by default. +.Bl -tag -compact -width indent +.It Cm compression-level Ns = Ns number +The compression level used by the deflate compressor. +Ranges from 0 (least effort) to 9 (most effort). +Default: 6 +.It Cm zisofs +Synonym for +.Cm zisofs=direct . +.It Cm zisofs=direct +Compress each file in the archive. +Unlike +.Cm zisofs=indirect , +this is handled entirely within libarchive and does not require a +separate utility. +For best results, libarchive tests each file and will store +the file uncompressed if the compression does not actually save any space. +In particular, files under 2k will never be compressed. +Note that boot image files are never compressed. +.It Cm zisofs=indirect +Recognizes files that have already been compressed with the +.Cm mkzftree +utility and sets up the necessary file metadata so that +readers will correctly identify these as zisofs-compressed files. +.It Cm zisofs-exclude Ns = Ns Ar filename +Specifies a filename that should not be compressed when using +.Cm zisofs=direct . +This option can be provided multiple times to suppress compression +on many files. +.El +.It Format mtree +.Bl -tag -compact -width indent +.It Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname +Enable a particular keyword in the mtree output. +Prefix with an exclamation mark to disable the corresponding keyword. +The default is equivalent to +.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . +.It Cm all +Enables all of the above keywords. +.It Cm use-set +Enables generation of +.Cm /set +lines that specify default values for the following files and/or directories. +.It Cm indent +XXX needs explanation XXX +.El +.It Format newc +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format odc +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format pwb +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.El +.It Format pax +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file, group and user names. +The value is one of +.Dq BINARY +or +.Dq UTF-8 . +With +.Dq BINARY +there is no character conversion, with +.Dq UTF-8 +names are converted to UTF-8. +.It Cm xattrheader +When storing extended attributes, this option configures which +headers should be written. The value is one of +.Dq all , +.Dq LIBARCHIVE , +or +.Dq SCHILY . +By default, both +.Dq LIBARCHIVE.xattr +and +.Dq SCHILY.xattr +headers are written. +.El +.It Format ustar +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file, group and user names. +.El +.It Format v7tar +.Bl -tag -compact -width indent +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file, group and user names. +.El +.It Format warc +.Bl -tag -compact -width indent +.It Cm omit-warcinfo +Set to +.Dq true +to disable output of the warcinfo record. +.El +.It Format xar +.Bl -tag -compact -width indent +.It Cm checksum Ns = Ns Ar type +Use +.Ar type +as file checksum method. +Supported values are +.Dq none , +.Dq md5 , +and +.Dq sha1 +.Pq default . +.It Cm compression Ns = Ns Ar type +Use +.Ar type +as compression method. +Supported values are +.Dq none , +.Dq bzip2 , +.Dq gzip +.Pq default , +.Dq lzma +and +.Dq xz . +.It Cm compression_level +The value is a decimal integer from 1 to 9 specifying the compression level. +.It Cm toc-checksum Ns = Ns Ar type +Use +.Ar type +as table of contents checksum method. +Supported values are +.Dq none , +.Dq md5 +and +.Dq sha1 +.Pq default . +.El +.It Format zip +.Bl -tag -compact -width indent +.It Cm compression +The value is either +.Dq store , +.Dq deflate , +.Dq bzip2 , +.Dq lzma , +.Dq xz , +or +.Dq zstd +to indicate how the following entries should be compressed. +Note that this setting is ignored for directories, symbolic links, +and other special entries. +.It Cm compression-level +The value is interpreted as a decimal integer specifying the +compression level. +Values between 0 and 9 are supported. +A compression level of 0 switches the compression method to +.Dq store , +other values will enable +.Dq deflate , +.Dq bzip2 , +.Dq lzma , +or +.Dq zstd +compression (in order of priority, depending on what libraries +are linked) with the given level. +.It Cm threads +The value is interpreted as a decimal integer specifying the +number of threads to use for compression. +It is supported only for +.Dq xz +or +.Dq zstd +compression and ignored for any other. +A threads value of 0 is a special one requesting to detect and use as +many threads as the number of active physical CPU cores. +.It Cm encryption +Enable encryption using traditional zip encryption. +.It Cm encryption Ns = Ns Ar type +Use +.Ar type +as encryption type. +Supported values are +.Dq zipcrypt +.Pq traditional zip encryption , +.Dq aes128 +.Pq WinZip AES-128 encryption +and +.Dq aes256 +.Pq WinZip AES-256 encryption . +.It Cm experimental +This boolean option enables or disables experimental Zip features +that may not be compatible with other Zip implementations. +.It Cm fakecrc32 +This boolean option disables CRC calculations. +All CRC fields are set to zero. +It should not be used except for testing purposes. +.It Cm hdrcharset +The value is used as a character set name that will be +used when translating file names. +.It Cm zip64 +Zip64 extensions provide additional file size information +for entries larger than 4 GiB. +They also provide extended file offset and archive size information +when archives exceed 4 GiB. +By default, the Zip writer selectively enables these extensions only as needed. +In particular, if the file size is unknown, the Zip writer will +include Zip64 extensions to guard against the possibility that the +file might be larger than 4 GiB. +.Pp +Setting this boolean option will force the writer to use Zip64 extensions +even for small files that would not otherwise require them. +This is primarily useful for testing. +.Pp +Disabling this option with +.Cm !zip64 +will force the Zip writer to avoid Zip64 extensions: +It will reject files with size greater than 4 GiB, +it will reject any new entries once the total archive size reaches 4 GiB, +and it will not use Zip64 extensions for files with unknown size. +In particular, this can improve compatibility when generating archives +where the entry sizes are not known in advance. +.El +.El +.Sh EXAMPLES +The following example creates an archive write handle to +create a gzip-compressed ISO9660 format image. +The two options here specify that the ISO9660 archive will use +.Ar kernel.img +as the boot image for El Torito booting, and that the gzip +compressor should use the maximum compression level. +.Bd -literal -offset indent +a = archive_write_new(); +archive_write_add_filter_gzip(a); +archive_write_set_format_iso9660(a); +archive_write_set_options(a, "boot=kernel.img,compression=9"); +archive_write_open_filename(a, filename, blocksize); +.Ed +.\" +.Sh ERRORS +More detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.\" +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_read_set_options 3 , +.Xr archive_write 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The options support for libarchive was originally implemented by +.An Michihiro NAKAJIMA . +.Sh BUGS diff --git a/static/netbsd/man3/archive_write_set_passphrase.3 b/static/netbsd/man3/archive_write_set_passphrase.3 new file mode 100644 index 00000000..629e059b --- /dev/null +++ b/static/netbsd/man3/archive_write_set_passphrase.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2014 Michihiro NAKAJIMA +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 21, 2014 +.Dt ARCHIVE_WRITE_SET_PASSPHRASE 3 +.Os +.Sh NAME +.Nm archive_write_set_passphrase , +.Nm archive_write_set_passphrase_callback +.Nd functions for writing encrypted archives +.Sh LIBRARY +Streaming Archive Library (libarchive, -larchive) +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_write_set_passphrase +.Fa "struct archive *" +.Fa "const char *passphrase" +.Fc +.Ft int +.Fo archive_write_set_passphrase_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_passphrase_callback *" +.Fc +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn archive_write_set_passphrase +Set a passphrase for writing an encrypted archive. +If +.Ar passphrase +is +.Dv NULL +or empty, this function will do nothing and +.Cm ARCHIVE_FAILED +will be returned. +Otherwise, +.Cm ARCHIVE_OK +will be returned. +.It Fn archive_write_set_passphrase_callback +Register a callback function that will be invoked to get a passphrase +for encryption if the passphrase was not set by the +.Fn archive_write_set_passphrase +function. +.El +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_write 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/asin.3 b/static/netbsd/man3/asin.3 new file mode 100644 index 00000000..fdf57d89 --- /dev/null +++ b/static/netbsd/man3/asin.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)asin.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: asin.3,v 1.18 2017/07/03 21:32:50 wiz Exp $ +.\" +.Dd January 29, 2013 +.Dt ASIN 3 +.Os +.Sh NAME +.Nm asin , +.Nm asinf , +.Nm asinl +.Nd arc sine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn asin "double x" +.Ft float +.Fn asinf "float x" +.Ft long double +.Fn asinl "long double x" +.Sh DESCRIPTION +The +.Fn asin , +.Fn asinf , +and +.Fn asinl +functions compute the principal value of the arc sine of +.Fa x +in the range +.Bk -words +.Bq -\*(Pi/2, +\*(Pi/2 . +.Ek +.Sh RETURN VALUES +.\" POSIX_MODE +If |x|>1, +.Fn asin "x" , +.Fn asinf "x" , +and +.Fn asinl "x" +return NaN and set the global variable +.Va errno +to EDOM. +.\" SYSV_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr acos 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn asin +function conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/asinh.3 b/static/netbsd/man3/asinh.3 new file mode 100644 index 00000000..14d58e65 --- /dev/null +++ b/static/netbsd/man3/asinh.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)asinh.3 6.4 (Berkeley) 5/6/91 +.\" $NetBSD: asinh.3,v 1.17 2014/09/19 16:02:58 wiz Exp $ +.\" +.Dd January 29, 2013 +.Dt ASINH 3 +.Os +.Sh NAME +.Nm asinh , +.Nm asinhf , +.Nm asinhl +.Nd inverse hyperbolic sine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn asinh "double x" +.Ft float +.Fn asinhf "float x" +.Ft long double +.Fn asinhl "long double x" +.Sh DESCRIPTION +The +.Fn asinh , +.Fn asinhf , +and +.Fn asinhl +functions compute the inverse hyperbolic sine +of the real +argument +.Sh RETURN VALUES +The +.Fn asinh , +.Fn asinhf , +and +.Fn asinhl +functions return the inverse hyperbolic sine of +.Ar x . +.\" SYSV_MODE +.\" .Sh RETURN VALUES +.\" Exceptional cases are handled by +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr acosh 3 , +.Xr atanh 3 , +.Xr exp 3 , +.Xr math 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn asinh +function conforms to +.St -isoC-99 . +.Sh HISTORY +The +.Fn asinh +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/at_quick_exit.3 b/static/netbsd/man3/at_quick_exit.3 new file mode 100644 index 00000000..5ac0b7ae --- /dev/null +++ b/static/netbsd/man3/at_quick_exit.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: at_quick_exit.3,v 1.2 2013/04/26 19:37:18 wiz Exp $ +.\" Copyright (c) 2011 David Chisnall +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libc/stdlib/at_quick_exit.3,v 1.5 2012/11/17 01:49:41 svnexp Exp $ +.\" +.Dd April 26, 2013 +.Dt AT_QUICK_EXIT 3 +.Os +.Sh NAME +.Nm at_quick_exit +.Nd registers a cleanup function to run on quick exit +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn at_quick_exit "void (*func)(void)" +.Sh DESCRIPTION +The +.Fn at_quick_exit +function registers a cleanup function to be called when the program exits as a +result of calling +.Xr quick_exit 3 . +The cleanup functions are called in the reverse order and will not be called if +the program exits by calling +.Xr exit 3 , +.Xr _Exit 2 , +or +.Xr abort 3 . +.Sh RETURN VALUES +The +.Fn at_quick_exit +function returns the value 0 if successful and a non-zero value on failure. +.Sh SEE ALSO +.Xr exit 3 , +.Xr quick_exit 3 +.Sh STANDARDS +The +.Fn at_quick_exit +function conforms to +.St -isoC-2011 . diff --git a/static/netbsd/man3/atan.3 b/static/netbsd/man3/atan.3 new file mode 100644 index 00000000..59d456b4 --- /dev/null +++ b/static/netbsd/man3/atan.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atan.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: atan.3,v 1.17 2013/01/29 02:54:30 matt Exp $ +.\" +.Dd January 29, 2013 +.Dt ATAN 3 +.Os +.Sh NAME +.Nm atan , +.Nm atanf , +.Nm atanl +.Nd arc tangent function of one variable +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn atan "double x" +.Ft float +.Fn atanf "float x" +.Ft long double +.Fn atanl "long double x" +.Sh DESCRIPTION +The +.Fn atan , +.Fn atanf , +and +.Fn atanl +functions compute the principal value of the arc tangent of +.Fa x +in the range +.Bk -words +.Bq -\*(Pi/2 , +\*(Pi/2 . +.Ek +.\" SYSV_MODE +.\" .Sh RETURN VALUES +.\" Exceptional cases are handled by +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn atan +functions conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/atan2.3 b/static/netbsd/man3/atan2.3 new file mode 100644 index 00000000..5873d451 --- /dev/null +++ b/static/netbsd/man3/atan2.3 @@ -0,0 +1,196 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atan2.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: atan2.3,v 1.19 2017/07/03 21:32:50 wiz Exp $ +.\" +.Dd January 29, 2013 +.Dt ATAN2 3 +.Os +.Sh NAME +.Nm atan2 , +.Nm atan2f , +.Nm atan2l +.Nd arc tangent function of two variables +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn atan2 "double y" "double x" +.Ft float +.Fn atan2f "float y" "float x" +.Ft long double +.Fn atan2l "long double y" "long double x" +.Sh DESCRIPTION +The +.Fn atan2 , +.Fn atan2f , +and +.Fn atan2l +functions compute the principal value of the arc tangent of +.Ar y/ Ns Ar x , +using the signs of both arguments to determine the quadrant of +the return value. +.Sh RETURN VALUES +The +.Fn atan2 +function, if successful, +returns the arc tangent of +.Ar y/ Ns Ar x +in the range +.Bk -words +.Bq \&- Ns \*(Pi , \&+ Ns \*(Pi +.Ek +radians. +If both +.Ar x +and +.Ar y +are zero, the global variable +.Va errno +is set to +.Er EDOM . +On the +.Tn VAX : +.Bl -column atan_(y,x)_:=____ sign(y)_(Pi_atan2(Xy_xX))___ +.It Fn atan2 y x No := Ta +.Fn atan y/x Ta +if +.Ar x +> 0, +.It Ta sign( Ns Ar y Ns )*(\*(Pi - +.Fn atan "\*(Bay/x\*(Ba" ) Ta +if +.Ar x +< 0, +.It Ta +.No 0 Ta +if x = y = 0, or +.It Ta +.Pf sign( Ar y Ns )*\*(Pi/2 Ta +if +.Ar x += 0 \*(!= +.Ar y . +.El +.Sh NOTES +The function +.Fn atan2 +defines "if x > 0," +.Fn atan2 0 0 += 0 on a +.Tn VAX +despite that previously +.Fn atan2 0 0 +may have generated an error message. +The reasons for assigning a value to +.Fn atan2 0 0 +are these: +.Bl -enum -offset indent +.It +Programs that test arguments to avoid computing +.Fn atan2 0 0 +must be indifferent to its value. +Programs that require it to be invalid are vulnerable +to diverse reactions to that invalidity on diverse computer systems. +.It +The +.Fn atan2 +function is used mostly to convert from rectangular (x,y) +to polar +.if n\ +(r,theta) +.if t\ +(r,\(*h) +coordinates that must satisfy x = +.if n\ +r\(**cos theta +.if t\ +r\(**cos\(*h +and y = +.if n\ +r\(**sin theta. +.if t\ +r\(**sin\(*h. +These equations are satisfied when (x=0,y=0) +is mapped to +.if n \ +(r=0,theta=0) +.if t \ +(r=0,\(*h=0) +on a VAX. +In general, conversions to polar coordinates should be computed thus: +.Bd -unfilled -offset indent +.if n \{\ +r := hypot(x,y); ... := sqrt(x\(**x+y\(**y) +theta := atan2(y,x). +.\} +.if t \{\ +r := hypot(x,y); ... := \(sr(x\u\s82\s10\d+y\u\s82\s10\d) +\(*h := atan2(y,x). +.\} +.Ed +.It +The foregoing formulas need not be altered to cope in a +reasonable way with signed zeros and infinities +on a machine that conforms to +.Tn IEEE 754 ; +the versions of +.Xr hypot 3 +and +.Fn atan2 +provided for +such a machine are designed to handle all cases. +That is why +.Fn atan2 \(+-0 \-0 += \(+-\*(Pi +for instance. +In general the formulas above are equivalent to these: +.Bd -unfilled -offset indent +.if n \ +r := sqrt(x\(**x+y\(**y); if r = 0 then x := copysign(1,x); +.if t \ +r := \(sr(x\(**x+y\(**y);\0\0if r = 0 then x := copysign(1,x); +.Ed +.El +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn atan2 +function conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/atanh.3 b/static/netbsd/man3/atanh.3 new file mode 100644 index 00000000..6402da26 --- /dev/null +++ b/static/netbsd/man3/atanh.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atanh.3 5.2 (Berkeley) 5/6/91 +.\" $NetBSD: atanh.3,v 1.18 2022/12/04 11:25:09 uwe Exp $ +.\" +.Dd January 29, 2013 +.Dt ATANH 3 +.Os +.Sh NAME +.Nm atanh , +.Nm atanhf , +.Nm atanhl +.Nd inverse hyperbolic tangent function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn atanh "double x" +.Ft float +.Fn atanhf "float x" +.Ft long double +.Fn atanhl "long double x" +.Sh DESCRIPTION +The +.Fn atanh , +.Fn atanhf , +and +.Fn atanhl +functions compute the inverse hyperbolic tangent +of the real +argument +.Ar x . +.Sh RETURN VALUES +If |x|\*[Ge]1, +.Fn atanh "x" , +.Fn atanhf "x" , +and +.Fn atanhl "x" +.\" POSIX_MODE +return +inf, -inf or NaN, and sets the global variable +.Va errno +to +.Er EDOM . +.\" SYSV_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr acosh 3 , +.Xr asinh 3 , +.Xr exp 3 , +.Xr math 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn atanh +function conforms to +.St -isoC-99 . +.Sh HISTORY +The +.Fn atanh +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/atexit.3 b/static/netbsd/man3/atexit.3 new file mode 100644 index 00000000..64fcdc63 --- /dev/null +++ b/static/netbsd/man3/atexit.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: atexit.3,v 1.11 2013/04/26 19:37:04 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atexit.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt ATEXIT 3 +.Os +.Sh NAME +.Nm atexit +.Nd register a function to be called on exit +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn atexit "void (*function)(void)" +.Sh DESCRIPTION +The +.Fn atexit +function +registers the given +.Ar function +to be called at program exit, whether via +.Xr exit 3 +or via return from the program's +.Em main . +Functions so registered are called in reverse order; +no arguments are passed. +At least 32 functions can always be registered, +and more are allowed as long as sufficient memory can be allocated. +.Sh RETURN VALUES +.Rv -std atexit +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOMEM +No memory was available to add the function to the list. +The existing list of functions is unmodified. +.El +.Sh SEE ALSO +.Xr at_quick_exit 3 , +.Xr exit 3 , +.Xr quick_exit 3 +.Sh STANDARDS +The +.Fn atexit +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/atf-c++-api.3 b/static/netbsd/man3/atf-c++-api.3 new file mode 100644 index 00000000..c086c909 --- /dev/null +++ b/static/netbsd/man3/atf-c++-api.3 @@ -0,0 +1,635 @@ +.\" +.\" Automated Testing Framework (atf) +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 15, 2013 +.Dt ATF-C++-API 3 +.Os +.Sh NAME +.Nm atf-c++-api , +.Nm ATF_ADD_TEST_CASE , +.Nm ATF_CHECK_ERRNO , +.Nm ATF_FAIL , +.Nm ATF_INIT_TEST_CASES , +.Nm ATF_PASS , +.Nm ATF_REQUIRE , +.Nm ATF_REQUIRE_EQ , +.Nm ATF_REQUIRE_ERRNO , +.Nm ATF_REQUIRE_IN , +.Nm ATF_REQUIRE_MATCH , +.Nm ATF_REQUIRE_NOT_IN , +.Nm ATF_REQUIRE_THROW , +.Nm ATF_REQUIRE_THROW_RE , +.Nm ATF_SKIP , +.Nm ATF_TEST_CASE , +.Nm ATF_TEST_CASE_BODY , +.Nm ATF_TEST_CASE_CLEANUP , +.Nm ATF_TEST_CASE_HEAD , +.Nm ATF_TEST_CASE_NAME , +.Nm ATF_TEST_CASE_USE , +.Nm ATF_TEST_CASE_WITH_CLEANUP , +.Nm ATF_TEST_CASE_WITHOUT_HEAD , +.Nm atf::utils::cat_file , +.Nm atf::utils::compare_file , +.Nm atf::utils::copy_file , +.Nm atf::utils::create_file , +.Nm atf::utils::file_exists , +.Nm atf::utils::fork , +.Nm atf::utils::grep_collection , +.Nm atf::utils::grep_file , +.Nm atf::utils::grep_string , +.Nm atf::utils::redirect , +.Nm atf::utils::wait +.Nd C++ API to write ATF-based test programs +.Sh SYNOPSIS +.In atf-c++.hpp +.Fn ATF_ADD_TEST_CASE "tcs" "name" +.Fn ATF_CHECK_ERRNO "exp_errno" "bool_expression" +.Fn ATF_FAIL "reason" +.Fn ATF_INIT_TEST_CASES "tcs" +.Fn ATF_PASS +.Fn ATF_REQUIRE "expression" +.Fn ATF_REQUIRE_EQ "expression_1" "expression_2" +.Fn ATF_REQUIRE_ERRNO "exp_errno" "bool_expression" +.Fn ATF_REQUIRE_IN "element" "collection" +.Fn ATF_REQUIRE_MATCH "regexp" "string_expression" +.Fn ATF_REQUIRE_NOT_IN "element" "collection" +.Fn ATF_REQUIRE_THROW "expected_exception" "statement" +.Fn ATF_REQUIRE_THROW_RE "expected_exception" "regexp" "statement" +.Fn ATF_SKIP "reason" +.Fn ATF_TEST_CASE "name" +.Fn ATF_TEST_CASE_BODY "name" +.Fn ATF_TEST_CASE_CLEANUP "name" +.Fn ATF_TEST_CASE_HEAD "name" +.Fn ATF_TEST_CASE_NAME "name" +.Fn ATF_TEST_CASE_USE "name" +.Fn ATF_TEST_CASE_WITH_CLEANUP "name" +.Fn ATF_TEST_CASE_WITHOUT_HEAD "name" +.Ft void +.Fo atf::utils::cat_file +.Fa "const std::string& path" +.Fa "const std::string& prefix" +.Fc +.Ft bool +.Fo atf::utils::compare_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Ft void +.Fo atf::utils::copy_file +.Fa "const std::string& source" +.Fa "const std::string& destination" +.Fc +.Ft void +.Fo atf::utils::create_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Ft void +.Fo atf::utils::file_exists +.Fa "const std::string& path" +.Fc +.Ft pid_t +.Fo atf::utils::fork +.Fa "void" +.Fc +.Ft bool +.Fo atf::utils::grep_collection +.Fa "const std::string& regexp" +.Fa "const Collection& collection" +.Fc +.Ft bool +.Fo atf::utils::grep_file +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Ft bool +.Fo atf::utils::grep_string +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Ft void +.Fo atf::utils::redirect +.Fa "const int fd" +.Fa "const std::string& path" +.Fc +.Ft void +.Fo atf::utils::wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const std::string& expected_stdout" +.Fa "const std::string& expected_stderr" +.Fc +.Sh DESCRIPTION +ATF provides a C++ programming interface to implement test programs. +C++-based test programs follow this template: +.Bd -literal -offset indent +extern "C" { +.Ns ... C-specific includes go here ... +} + +.Ns ... C++-specific includes go here ... + +#include + +ATF_TEST_CASE(tc1); +ATF_TEST_CASE_HEAD(tc1) +{ + ... first test case's header ... +} +ATF_TEST_CASE_BODY(tc1) +{ + ... first test case's body ... +} + +ATF_TEST_CASE_WITH_CLEANUP(tc2); +ATF_TEST_CASE_HEAD(tc2) +{ + ... second test case's header ... +} +ATF_TEST_CASE_BODY(tc2) +{ + ... second test case's body ... +} +ATF_TEST_CASE_CLEANUP(tc2) +{ + ... second test case's cleanup ... +} + +ATF_TEST_CASE(tc3); +ATF_TEST_CASE_BODY(tc3) +{ + ... third test case's body ... +} + +.Ns ... additional test cases ... + +ATF_INIT_TEST_CASES(tcs) +{ + ATF_ADD_TEST_CASE(tcs, tc1); + ATF_ADD_TEST_CASE(tcs, tc2); + ATF_ADD_TEST_CASE(tcs, tc3); + ... add additional test cases ... +} +.Ed +.Ss Definition of test cases +Test cases have an identifier and are composed of three different parts: +the header, the body and an optional cleanup routine, all of which are +described in +.Xr atf-test-case 4 . +To define test cases, one can use the +.Fn ATF_TEST_CASE , +.Fn ATF_TEST_CASE_WITH_CLEANUP +or the +.Fn ATF_TEST_CASE_WITHOUT_HEAD +macros, which take a single parameter specifiying the test case's +name. +.Fn ATF_TEST_CASE , +requires to define a head and a body for the test case, +.Fn ATF_TEST_CASE_WITH_CLEANUP +requires to define a head, a body and a cleanup for the test case and +.Fn ATF_TEST_CASE_WITHOUT_HEAD +requires only a body for the test case. +It is important to note that these +.Em do not +set the test case up for execution when the program is run. +In order to do so, a later registration is needed through the +.Fn ATF_ADD_TEST_CASE +macro detailed in +.Sx Program initialization . +.Pp +Later on, one must define the three parts of the body by means of three +functions. +Their headers are given by the +.Fn ATF_TEST_CASE_HEAD , +.Fn ATF_TEST_CASE_BODY +and +.Fn ATF_TEST_CASE_CLEANUP +macros, all of which take the test case's name. +Following each of these, a block of code is expected, surrounded by the +opening and closing brackets. +.Pp +Additionally, the +.Fn ATF_TEST_CASE_NAME +macro can be used to obtain the name of the class corresponding to a +particular test case, as the name is internally manged by the library to +prevent clashes with other user identifiers. +Similarly, the +.Fn ATF_TEST_CASE_USE +macro can be executed on a particular test case to mark it as "used" and +thus prevent compiler warnings regarding unused symbols. +Note that +.Em you should never have to use these macros during regular operation. +.Ss Program initialization +The library provides a way to easily define the test program's +.Fn main +function. +You should never define one on your own, but rely on the +library to do it for you. +This is done by using the +.Fn ATF_INIT_TEST_CASES +macro, which is passed the name of the list that will hold the test cases. +This name can be whatever you want as long as it is a valid variable value. +.Pp +After the macro, you are supposed to provide the body of a function, which +should only use the +.Fn ATF_ADD_TEST_CASE +macro to register the test cases the test program will execute. +The first parameter of this macro matches the name you provided in the +former call. +.Ss Header definitions +The test case's header can define the meta-data by using the +.Fn set_md_var +method, which takes two parameters: the first one specifies the +meta-data variable to be set and the second one specifies its value. +Both of them are strings. +.Ss Configuration variables +The test case has read-only access to the current configuration variables +by means of the +.Ft bool +.Fn has_config_var +and the +.Ft std::string +.Fn get_config_var +methods, which can be called in any of the three parts of a test case. +.Ss Access to the source directory +It is possible to get the path to the test case's source directory from any +of its three components by querying the +.Sq srcdir +configuration variable. +.Ss Requiring programs +Aside from the +.Va require.progs +meta-data variable available in the header only, one can also check for +additional programs in the test case's body by using the +.Fn require_prog +function, which takes the base name or full path of a single binary. +Relative paths are forbidden. +If it is not found, the test case will be automatically skipped. +.Ss Test case finalization +The test case finalizes either when the body reaches its end, at which +point the test is assumed to have +.Em passed , +or at any explicit call to +.Fn ATF_PASS , +.Fn ATF_FAIL +or +.Fn ATF_SKIP . +These three macros terminate the execution of the test case immediately. +The cleanup routine will be processed afterwards in a completely automated +way, regardless of the test case's termination reason. +.Pp +.Fn ATF_PASS +does not take any parameters. +.Fn ATF_FAIL +and +.Fn ATF_SKIP +take a single string that describes why the test case failed or +was skipped, respectively. +It is very important to provide a clear error message in both cases so that +the user can quickly know why the test did not pass. +.Ss Expectations +Everything explained in the previous section changes when the test case +expectations are redefined by the programmer. +.Pp +Each test case has an internal state called +.Sq expect +that describes what the test case expectations are at any point in time. +The value of this property can change during execution by any of: +.Bl -tag -width indent +.It Fn expect_death "reason" +Expects the test case to exit prematurely regardless of the nature of the +exit. +.It Fn expect_exit "exitcode" "reason" +Expects the test case to exit cleanly. +If +.Va exitcode +is not +.Sq -1 , +.Xr atf-run 1 +will validate that the exit code of the test case matches the one provided +in this call. +Otherwise, the exact value will be ignored. +.It Fn expect_fail "reason" +Any failure (be it fatal or non-fatal) raised in this mode is recorded. +However, such failures do not report the test case as failed; instead, the +test case finalizes cleanly and is reported as +.Sq expected failure ; +this report includes the provided +.Fa reason +as part of it. +If no error is raised while running in this mode, then the test case is +reported as +.Sq failed . +.Pp +This mode is useful to reproduce actual known bugs in tests. +Whenever the developer fixes the bug later on, the test case will start +reporting a failure, signaling the developer that the test case must be +adjusted to the new conditions. +In this situation, it is useful, for example, to set +.Fa reason +as the bug number for tracking purposes. +.It Fn expect_pass +This is the normal mode of execution. +In this mode, any failure is reported as such to the user and the test case +is marked as +.Sq failed . +.It Fn expect_race "reason" +Any failure or timeout during the execution of the test case will be +considered as if a race condition has been triggered and reported as such. +If no problems arise, the test will continue execution as usual. +.It Fn expect_signal "signo" "reason" +Expects the test case to terminate due to the reception of a signal. +If +.Va signo +is not +.Sq -1 , +.Xr atf-run 1 +will validate that the signal that terminated the test case matches the one +provided in this call. +Otherwise, the exact value will be ignored. +.It Fn expect_timeout "reason" +Expects the test case to execute for longer than its timeout. +.El +.Ss Helper macros for common checks +The library provides several macros that are very handy in multiple +situations. +These basically check some condition after executing a given statement or +processing a given expression and, if the condition is not met, they +automatically call +.Fn ATF_FAIL +with an appropriate error message. +.Pp +.Fn ATF_REQUIRE +takes an expression and raises a failure if it evaluates to false. +.Pp +.Fn ATF_REQUIRE_EQ +takes two expressions and raises a failure if the two do not evaluate to +the same exact value. +.Pp +.Fn ATF_REQUIRE_IN +takes an element and a collection and validates that the element is present in +the collection. +.Pp +.Fn ATF_REQUIRE_MATCH +takes a regular expression and a string and raises a failure if the regular +expression does not match the string. +.Pp +.Fn ATF_REQUIRE_NOT_IN +takes an element and a collection and validates that the element is not present +in the collection. +.Pp +.Fn ATF_REQUIRE_THROW +takes the name of an exception and a statement and raises a failure if +the statement does not throw the specified exception. +.Fn ATF_REQUIRE_THROW_RE +takes the name of an exception, a regular expresion and a statement and raises a +failure if the statement does not throw the specified exception and if the +message of the exception does not match the regular expression. +.Pp +.Fn ATF_CHECK_ERRNO +and +.Fn ATF_REQUIRE_ERRNO +take, first, the error code that the check is expecting to find in the +.Va errno +variable and, second, a boolean expression that, if evaluates to true, +means that a call failed and +.Va errno +has to be checked against the first value. +.Ss Utility functions +The following functions are provided as part of the +.Nm +API to simplify the creation of a variety of tests. +In particular, these are useful to write tests for command-line interfaces. +.Pp +.Ft void +.Fo atf::utils::cat_file +.Fa "const std::string& path" +.Fa "const std::string& prefix" +.Fc +.Bd -ragged -offset indent +Prints the contents of +.Fa path +to the standard output, prefixing every line with the string in +.Fa prefix . +.Ed +.Pp +.Ft bool +.Fo atf::utils::compare_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Bd -ragged -offset indent +Returns true if the given +.Fa path +matches exactly the expected inlined +.Fa contents . +.Ed +.Pp +.Ft void +.Fo atf::utils::copy_file +.Fa "const std::string& source" +.Fa "const std::string& destination" +.Fc +.Bd -ragged -offset indent +Copies the file +.Fa source +to +.Fa destination . +The permissions of the file are preserved during the code. +.Ed +.Pp +.Ft void +.Fo atf::utils::create_file +.Fa "const std::string& path" +.Fa "const std::string& contents" +.Fc +.Bd -ragged -offset indent +Creates +.Fa file +with the text given in +.Fa contents . +.Ed +.Pp +.Ft void +.Fo atf::utils::file_exists +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Checks if +.Fa path +exists. +.Ed +.Pp +.Ft pid_t +.Fo atf::utils::fork +.Fa "void" +.Fc +.Bd -ragged -offset indent +Forks a process and redirects the standard output and standard error of the +child to files for later validation with +.Fn atf::utils::wait . +Fails the test case if the fork fails, so this does not return an error. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_collection +.Fa "const std::string& regexp" +.Fa "const Collection& collection" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in any of the strings contained in the +.Fa collection . +This is a template that accepts any one-dimensional container of strings. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_file +.Fa "const std::string& regexp" +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in the file +.Fa path . +The variable arguments are used to construct the regular expression. +.Ed +.Pp +.Ft bool +.Fo atf::utils::grep_string +.Fa "const std::string& regexp" +.Fa "const std::string& str" +.Fc +.Bd -ragged -offset indent +Searches for the regular expression +.Fa regexp +in the string +.Fa str . +.Ed +.Ft void +.Fo atf::utils::redirect +.Fa "const int fd" +.Fa "const std::string& path" +.Fc +.Bd -ragged -offset indent +Redirects the given file descriptor +.Fa fd +to the file +.Fa path . +This function exits the process in case of an error and does not properly mark +the test case as failed. +As a result, it should only be used in subprocesses of the test case; specially +those spawned by +.Fn atf::utils::fork . +.Ed +.Pp +.Ft void +.Fo atf::utils::wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const std::string& expected_stdout" +.Fa "const std::string& expected_stderr" +.Fc +.Bd -ragged -offset indent +Waits and validates the result of a subprocess spawned with +.Fn atf::utils::wait . +The validation involves checking that the subprocess exited cleanly and returned +the code specified in +.Fa expected_exit_status +and that its standard output and standard error match the strings given in +.Fa expected_stdout +and +.Fa expected_stderr . +.Pp +If any of the +.Fa expected_stdout +or +.Fa expected_stderr +strings are prefixed with +.Sq save: , +then they specify the name of the file into which to store the stdout or stderr +of the subprocess, and no comparison is performed. +.Ed +.Sh EXAMPLES +The following shows a complete test program with a single test case that +validates the addition operator: +.Bd -literal -offset indent +#include + +ATF_TEST_CASE(addition); +ATF_TEST_CASE_HEAD(addition) +{ + set_md_var("descr", "Sample tests for the addition operator"); +} +ATF_TEST_CASE_BODY(addition) +{ + ATF_REQUIRE_EQ(0 + 0, 0); + ATF_REQUIRE_EQ(0 + 1, 1); + ATF_REQUIRE_EQ(1 + 0, 1); + + ATF_REQUIRE_EQ(1 + 1, 2); + + ATF_REQUIRE_EQ(100 + 200, 300); +} + +ATF_TEST_CASE(open_failure); +ATF_TEST_CASE_HEAD(open_failure) +{ + set_md_var("descr", "Sample tests for the open function"); +} +ATF_TEST_CASE_BODY(open_failure) +{ + ATF_REQUIRE_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1); +} + +ATF_TEST_CASE(known_bug); +ATF_TEST_CASE_HEAD(known_bug) +{ + set_md_var("descr", "Reproduces a known bug"); +} +ATF_TEST_CASE_BODY(known_bug) +{ + expect_fail("See bug number foo/bar"); + ATF_REQUIRE_EQ(3, 1 + 1); + expect_pass(); + ATF_REQUIRE_EQ(3, 1 + 2); +} + +ATF_INIT_TEST_CASES(tcs) +{ + ATF_ADD_TEST_CASE(tcs, addition); + ATF_ADD_TEST_CASE(tcs, open_failure); + ATF_ADD_TEST_CASE(tcs, known_bug); +} +.Ed +.Sh SEE ALSO +.Xr atf-test-program 1 , +.Xr atf-test-case 4 , +.Xr atf 7 diff --git a/static/netbsd/man3/atf-c-api.3 b/static/netbsd/man3/atf-c-api.3 new file mode 100644 index 00000000..c7538583 --- /dev/null +++ b/static/netbsd/man3/atf-c-api.3 @@ -0,0 +1,775 @@ +.\" +.\" Automated Testing Framework (atf) +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 14, 2023 +.Dt ATF-C-API 3 +.Os +.Sh NAME +.Nm atf-c-api , +.Nm ATF_CHECK , +.Nm ATF_CHECK_MSG , +.Nm ATF_CHECK_EQ , +.Nm ATF_CHECK_EQ_MSG , +.Nm ATF_CHECK_MATCH , +.Nm ATF_CHECK_MATCH_MSG , +.Nm ATF_CHECK_STREQ , +.Nm ATF_CHECK_STREQ_MSG , +.Nm ATF_CHECK_ERRNO , +.Nm ATF_REQUIRE , +.Nm ATF_REQUIRE_MSG , +.Nm ATF_REQUIRE_EQ , +.Nm ATF_REQUIRE_EQ_MSG , +.Nm ATF_REQUIRE_MATCH , +.Nm ATF_REQUIRE_MATCH_MSG , +.Nm ATF_REQUIRE_STREQ , +.Nm ATF_REQUIRE_STREQ_MSG , +.Nm ATF_REQUIRE_ERRNO , +.Nm ATF_TC , +.Nm ATF_TC_BODY , +.Nm ATF_TC_BODY_NAME , +.Nm ATF_TC_CLEANUP , +.Nm ATF_TC_CLEANUP_NAME , +.Nm ATF_TC_HEAD , +.Nm ATF_TC_HEAD_NAME , +.Nm ATF_TC_NAME , +.Nm ATF_TC_WITH_CLEANUP , +.Nm ATF_TC_WITHOUT_HEAD , +.Nm ATF_TP_ADD_TC , +.Nm ATF_TP_ADD_TCS , +.Nm atf_tc_get_config_var , +.Nm atf_tc_get_config_var_wd , +.Nm atf_tc_get_config_var_as_bool , +.Nm atf_tc_get_config_var_as_bool_wd , +.Nm atf_tc_get_config_var_as_long , +.Nm atf_tc_get_config_var_as_long_wd , +.Nm atf_no_error , +.Nm atf_tc_expect_death , +.Nm atf_tc_expect_exit , +.Nm atf_tc_expect_fail , +.Nm atf_tc_expect_pass , +.Nm atf_tc_expect_signal , +.Nm atf_tc_expect_timeout , +.Nm atf_tc_fail , +.Nm atf_tc_fail_nonfatal , +.Nm atf_tc_pass , +.Nm atf_tc_skip , +.Nm atf_utils_cat_file , +.Nm atf_utils_compare_file , +.Nm atf_utils_copy_file , +.Nm atf_utils_create_file , +.Nm atf_utils_file_exists , +.Nm atf_utils_fork , +.Nm atf_utils_free_charpp , +.Nm atf_utils_grep_file , +.Nm atf_utils_grep_string , +.Nm atf_utils_readline , +.Nm atf_utils_redirect , +.Nm atf_utils_wait +.Nd C API to write ATF-based test programs +.Sh SYNOPSIS +.In atf-c.h +.Fn ATF_CHECK "expression" +.Fn ATF_CHECK_MSG "expression" "fail_msg_fmt" ... +.Fn ATF_CHECK_EQ "expression_1" "expression_2" +.Fn ATF_CHECK_EQ_MSG "expression_1" "expression_2" "fail_msg_fmt" ... +.Fn ATF_CHECK_MATCH "regexp" "string" +.Fn ATF_CHECK_MATCH_MSG "regexp" "string" "fail_msg_fmt" ... +.Fn ATF_CHECK_STREQ "string_1" "string_2" +.Fn ATF_CHECK_STREQ_MSG "string_1" "string_2" "fail_msg_fmt" ... +.Fn ATF_CHECK_ERRNO "exp_errno" "bool_expression" +.Fn ATF_REQUIRE "expression" +.Fn ATF_REQUIRE_MSG "expression" "fail_msg_fmt" ... +.Fn ATF_REQUIRE_EQ "expression_1" "expression_2" +.Fn ATF_REQUIRE_EQ_MSG "expression_1" "expression_2" "fail_msg_fmt" ... +.Fn ATF_REQUIRE_MATCH "regexp" "string" +.Fn ATF_REQUIRE_MATCH_MSG "regexp" "string" "fail_msg_fmt" ... +.Fn ATF_REQUIRE_STREQ "string_1" "string_2" +.Fn ATF_REQUIRE_STREQ_MSG "string_1" "string_2" "fail_msg_fmt" ... +.Fn ATF_REQUIRE_ERRNO "exp_errno" "bool_expression" +.Fn ATF_TC "name" +.Fn ATF_TC_BODY "name" "tc" +.Fn ATF_TC_BODY_NAME "name" +.Fn ATF_TC_CLEANUP "name" "tc" +.Fn ATF_TC_CLEANUP_NAME "name" +.Fn ATF_TC_HEAD "name" "tc" +.Fn ATF_TC_HEAD_NAME "name" +.Fn ATF_TC_NAME "name" +.Fn ATF_TC_WITH_CLEANUP "name" +.Fn ATF_TC_WITHOUT_HEAD "name" +.Fn ATF_TP_ADD_TC "tp_name" "tc_name" +.Fn ATF_TP_ADD_TCS "tp_name" +.Fn atf_tc_get_config_var "tc" "varname" +.Fn atf_tc_get_config_var_wd "tc" "variable_name" "default_value" +.Fn atf_tc_get_config_var_as_bool "tc" "variable_name" +.Fn atf_tc_get_config_var_as_bool_wd "tc" "variable_name" "default_value" +.Fn atf_tc_get_config_var_as_long "tc" "variable_name" +.Fn atf_tc_get_config_var_as_long_wd "tc" "variable_name" "default_value" +.Fn atf_no_error +.Fn atf_tc_expect_death "reason" "..." +.Fn atf_tc_expect_exit "exitcode" "reason" "..." +.Fn atf_tc_expect_fail "reason" "..." +.Fn atf_tc_expect_pass +.Fn atf_tc_expect_signal "signo" "reason" "..." +.Fn atf_tc_expect_timeout "reason" "..." +.Fn atf_tc_fail "reason" +.Fn atf_tc_fail_nonfatal "reason" +.Fn atf_tc_pass +.Fn atf_tc_skip "reason" +.Ft void +.Fo atf_utils_cat_file +.Fa "const char *file" +.Fa "const char *prefix" +.Fc +.Ft bool +.Fo atf_utils_compare_file +.Fa "const char *file" +.Fa "const char *contents" +.Fc +.Ft void +.Fo atf_utils_copy_file +.Fa "const char *source" +.Fa "const char *destination" +.Fc +.Ft void +.Fo atf_utils_create_file +.Fa "const char *file" +.Fa "const char *contents" +.Fa "..." +.Fc +.Ft void +.Fo atf_utils_file_exists +.Fa "const char *file" +.Fc +.Ft pid_t +.Fo atf_utils_fork +.Fa "void" +.Fc +.Ft void +.Fo atf_utils_free_charpp +.Fa "char **argv" +.Fc +.Ft bool +.Fo atf_utils_grep_file +.Fa "const char *regexp" +.Fa "const char *file" +.Fa "..." +.Fc +.Ft bool +.Fo atf_utils_grep_string +.Fa "const char *regexp" +.Fa "const char *str" +.Fa "..." +.Fc +.Ft char * +.Fo atf_utils_readline +.Fa "int fd" +.Fc +.Ft void +.Fo atf_utils_redirect +.Fa "const int fd" +.Fa "const char *file" +.Fc +.Ft void +.Fo atf_utils_wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const char *expected_stdout" +.Fa "const char *expected_stderr" +.Fc +.Sh DESCRIPTION +ATF provides a C programming interface to implement test programs. +C-based test programs follow this template: +.Bd -literal -offset indent +.Ns ... C-specific includes go here ... + +#include + +ATF_TC(tc1); +ATF_TC_HEAD(tc1, tc) +{ + ... first test case's header ... +} +ATF_TC_BODY(tc1, tc) +{ + ... first test case's body ... +} + +ATF_TC_WITH_CLEANUP(tc2); +ATF_TC_HEAD(tc2, tc) +{ + ... second test case's header ... +} +ATF_TC_BODY(tc2, tc) +{ + ... second test case's body ... +} +ATF_TC_CLEANUP(tc2, tc) +{ + ... second test case's cleanup ... +} + +ATF_TC_WITHOUT_HEAD(tc3); +ATF_TC_BODY(tc3, tc) +{ + ... third test case's body ... +} + +.Ns ... additional test cases ... + +ATF_TP_ADD_TCS(tp) +{ + ATF_TP_ADD_TC(tp, tc1); + ATF_TP_ADD_TC(tp, tc2); + ATF_TP_ADD_TC(tp, tc3); + ... add additional test cases ... + + return atf_no_error(); +} +.Ed +.Ss Definition of test cases +Test cases have an identifier and are composed of three different parts: +the header, the body and an optional cleanup routine, all of which are +described in +.Xr atf-test-case 4 . +To define test cases, one can use the +.Fn ATF_TC , +.Fn ATF_TC_WITH_CLEANUP +or the +.Fn ATF_TC_WITHOUT_HEAD +macros, which take a single parameter specifiying the test case's name. +.Fn ATF_TC , +requires to define a head and a body for the test case, +.Fn ATF_TC_WITH_CLEANUP +requires to define a head, a body and a cleanup for the test case and +.Fn ATF_TC_WITHOUT_HEAD +requires only a body for the test case. +It is important to note that these +.Em do not +set the test case up for execution when the program is run. +In order to do so, a later registration is needed with the +.Fn ATF_TP_ADD_TC +macro detailed in +.Sx Program initialization . +.Pp +Later on, one must define the three parts of the test by means of three +functions. +Their headers are given by the +.Fn ATF_TC_HEAD , +.Fn ATF_TC_BODY , +and +.Fn ATF_TC_CLEANUP +macros, all of which take the test case name provided to the +.Fn ATF_TC , +.Fn ATF_TC_WITH_CLEANUP , +or +.Fn ATF_TC_WITHOUT_HEAD +macros and the name of the variable that will hold a pointer to the +test case data. +Following each of these, a block of code is expected, surrounded by the +opening and closing brackets. +.Ss Program initialization +The library provides a way to easily define the test program's +.Fn main +function. +You should never define one on your own, but rely on the +library to do it for you. +This is done by using the +.Fn ATF_TP_ADD_TCS +macro, which is passed the name of the object that will hold the test +cases; i.e. the test program instance. +This name can be whatever you want as long as it is a valid variable +identifier. +.Pp +After the macro, you are supposed to provide the body of a function, which +should only use the +.Fn ATF_TP_ADD_TC +macro to register the test cases the test program will execute and return +a success error code. +The first parameter of this macro matches the name you provided in the +former call. +The success status can be returned using the +.Fn atf_no_error +function. +.Ss Header definitions +The test case's header can define the meta-data by using the +.Fn atf_tc_set_md_var +method, which takes three parameters: the first one points to the test +case data, the second one specifies the meta-data variable to be set +and the third one specifies its value. +Both of them are strings. +.Ss Configuration variables +The test case has read-only access to the current configuration variables +by means of the +.Ft bool +.Fn atf_tc_has_config_var , +.Ft const char * +.Fn atf_tc_get_config_var , +.Ft const char * +.Fn atf_tc_get_config_var_wd , +.Ft bool +.Fn atf_tc_get_config_var_as_bool , +.Ft bool +.Fn atf_tc_get_config_var_as_bool_wd , +.Ft long +.Fn atf_tc_get_config_var_as_long , +and the +.Ft long +.Fn atf_tc_get_config_var_as_long_wd +functions, which can be called in any of the three parts of a test case. +.Pp +The +.Sq _wd +variants take a default value for the variable which is returned if the +variable is not defined. +The other functions without the +.Sq _wd +suffix +.Em require +the variable to be defined. +.Ss Access to the source directory +It is possible to get the path to the test case's source directory from any +of its three components by querying the +.Sq srcdir +configuration variable. +.Ss Requiring programs +Aside from the +.Va require.progs +meta-data variable available in the header only, one can also check for +additional programs in the test case's body by using the +.Fn atf_tc_require_prog +function, which takes the base name or full path of a single binary. +Relative paths are forbidden. +If it is not found, the test case will be automatically skipped. +.Ss Test case finalization +The test case finalizes either when the body reaches its end, at which +point the test is assumed to have +.Em passed , +unless any non-fatal errors were raised using +.Fn atf_tc_fail_nonfatal , +or at any explicit call to +.Fn atf_tc_pass , +.Fn atf_tc_fail +or +.Fn atf_tc_skip . +These three functions terminate the execution of the test case immediately. +The cleanup routine will be processed afterwards in a completely automated +way, regardless of the test case's termination reason. +.Pp +.Fn atf_tc_pass +does not take any parameters. +.Fn atf_tc_fail , +.Fn atf_tc_fail_nonfatal +and +.Fn atf_tc_skip +take a format string and a variable list of parameters, which describe, in +a user-friendly manner, why the test case failed or was skipped, +respectively. +It is very important to provide a clear error message in both cases so that +the user can quickly know why the test did not pass. +.Ss Expectations +Everything explained in the previous section changes when the test case +expectations are redefined by the programmer. +.Pp +Each test case has an internal state called +.Sq expect +that describes what the test case expectations are at any point in time. +The value of this property can change during execution by any of: +.Bl -tag -width indent +.It Fn atf_tc_expect_death "reason" "..." +Expects the test case to exit prematurely regardless of the nature of the +exit. +.It Fn atf_tc_expect_exit "exitcode" "reason" "..." +Expects the test case to exit cleanly. +If +.Va exitcode +is not +.Sq -1 , +.Xr atf-run 1 +will validate that the exit code of the test case matches the one provided +in this call. +Otherwise, the exact value will be ignored. +.It Fn atf_tc_expect_fail "reason" "..." +Any failure (be it fatal or non-fatal) raised in this mode is recorded. +However, such failures do not report the test case as failed; instead, the +test case finalizes cleanly and is reported as +.Sq expected failure ; +this report includes the provided +.Fa reason +as part of it. +If no error is raised while running in this mode, then the test case is +reported as +.Sq failed . +.Pp +This mode is useful to reproduce actual known bugs in tests. +Whenever the developer fixes the bug later on, the test case will start +reporting a failure, signaling the developer that the test case must be +adjusted to the new conditions. +In this situation, it is useful, for example, to set +.Fa reason +as the bug number for tracking purposes. +.It Fn atf_tc_expect_pass +This is the normal mode of execution. +In this mode, any failure is reported as such to the user and the test case +is marked as +.Sq failed . +.It Fn atf_tc_expect_signal "signo" "reason" "..." +Expects the test case to terminate due to the reception of a signal. +If +.Va signo +is not +.Sq -1 , +.Xr atf-run 1 +will validate that the signal that terminated the test case matches the one +provided in this call. +Otherwise, the exact value will be ignored. +.It Fn atf_tc_expect_timeout "reason" "..." +Expects the test case to execute for longer than its timeout. +.El +.Ss Helper macros for common checks +The library provides several macros that are very handy in multiple +situations. +These basically check some condition after executing a given statement or +processing a given expression and, if the condition is not met, they +report the test case as failed. +.Pp +The +.Sq REQUIRE +variant of the macros immediately abort the test case as soon as an error +condition is detected by calling the +.Fn atf_tc_fail +function. +Use this variant whenever it makes no sense to continue the execution of a +test case when the checked condition is not met. +The +.Sq CHECK +variant, on the other hand, reports a failure as soon as it is encountered +using the +.Fn atf_tc_fail_nonfatal +function, but the execution of the test case continues as if nothing had +happened. +Use this variant whenever the checked condition is important as a result of +the test case, but there are other conditions that can be subsequently +checked on the same run without aborting. +.Pp +Additionally, the +.Sq MSG +variants take an extra set of parameters to explicitly specify the failure +message. +This failure message is formatted according to the +.Xr printf 3 +formatters. +.Pp +.Fn ATF_CHECK , +.Fn ATF_CHECK_MSG , +.Fn ATF_REQUIRE +and +.Fn ATF_REQUIRE_MSG +take an expression and fail if the expression evaluates to false. +.Pp +.Fn ATF_CHECK_EQ , +.Fn ATF_CHECK_EQ_MSG , +.Fn ATF_REQUIRE_EQ +and +.Fn ATF_REQUIRE_EQ_MSG +take two expressions and fail if the two evaluated values are not equal. +.Pp +.Fn ATF_CHECK_MATCH , +.Fn ATF_CHECK_MATCH_MSG , +.Fn ATF_REQUIRE_MATCH +and +.Fn ATF_REQUIRE_MATCH_MSG +take a regular expression and a string and fail if the regular expression does +not match the given string. +Note that the regular expression is not anchored, so it will match anywhere in +the string. +.Pp +.Fn ATF_CHECK_STREQ , +.Fn ATF_CHECK_STREQ_MSG , +.Fn ATF_REQUIRE_STREQ +and +.Fn ATF_REQUIRE_STREQ_MSG +take two strings and fail if the two are not equal character by character. +.Pp +.Fn ATF_CHECK_ERRNO +and +.Fn ATF_REQUIRE_ERRNO +take, first, the error code that the check is expecting to find in the +.Va errno +variable and, second, a boolean expression that, if evaluates to true, +means that a call failed and +.Va errno +has to be checked against the first value. +.Ss Utility functions +The following functions are provided as part of the +.Nm +API to simplify the creation of a variety of tests. +In particular, these are useful to write tests for command-line interfaces. +.Pp +.Ft void +.Fo atf_utils_cat_file +.Fa "const char *file" +.Fa "const char *prefix" +.Fc +.Bd -ragged -offset indent +Prints the contents of +.Fa file +to the standard output, prefixing every line with the string in +.Fa prefix . +.Ed +.Pp +.Ft bool +.Fo atf_utils_compare_file +.Fa "const char *file" +.Fa "const char *contents" +.Fc +.Bd -ragged -offset indent +Returns true if the given +.Fa file +matches exactly the expected inlined +.Fa contents . +.Ed +.Pp +.Ft void +.Fo atf_utils_copy_file +.Fa "const char *source" +.Fa "const char *destination" +.Fc +.Bd -ragged -offset indent +Copies the file +.Fa source +to +.Fa destination . +The permissions of the file are preserved during the code. +.Ed +.Pp +.Ft void +.Fo atf_utils_create_file +.Fa "const char *file" +.Fa "const char *contents" +.Fa "..." +.Fc +.Bd -ragged -offset indent +Creates +.Fa file +with the text given in +.Fa contents , +which is a formatting string that uses the rest of the variable arguments. +.Ed +.Pp +.Ft void +.Fo atf_utils_file_exists +.Fa "const char *file" +.Fc +.Bd -ragged -offset indent +Checks if +.Fa file +exists. +.Ed +.Pp +.Ft pid_t +.Fo atf_utils_fork +.Fa "void" +.Fc +.Bd -ragged -offset indent +Forks a process and redirects the standard output and standard error of the +child to files for later validation with +.Fn atf_utils_wait . +Fails the test case if the fork fails, so this does not return an error. +.Ed +.Pp +.Ft void +.Fo atf_utils_free_charpp +.Fa "char **argv" +.Fc +.Bd -ragged -offset indent +Frees a dynamically-allocated array of dynamically-allocated strings. +.Ed +.Pp +.Ft bool +.Fo atf_utils_grep_file +.Fa "const char *regexp" +.Fa "const char *file" +.Fa "..." +.Fc +.Bd -ragged -offset indent +Searches for the +.Fa regexp , +which is a formatting string representing the regular expression, +in the +.Fa file . +The variable arguments are used to construct the regular expression. +.Ed +.Pp +.Ft bool +.Fo atf_utils_grep_string +.Fa "const char *regexp" +.Fa "const char *str" +.Fa "..." +.Fc +.Bd -ragged -offset indent +Searches for the +.Fa regexp , +which is a formatting string representing the regular expression, +in the literal string +.Fa str . +The variable arguments are used to construct the regular expression. +.Ed +.Pp +.Ft char * +.Fo atf_utils_readline +.Fa "int fd" +.Fc +.Bd -ragged -offset indent +Reads a line from the file descriptor +.Fa fd . +The line, if any, is returned as a dynamically-allocated buffer that must be +released with +.Xr free 3 . +If there was nothing to read, returns +.Sq NULL . +.Ed +.Pp +.Ft void +.Fo atf_utils_redirect +.Fa "const int fd" +.Fa "const char *file" +.Fc +.Bd -ragged -offset indent +Redirects the given file descriptor +.Fa fd +to +.Fa file . +This function exits the process in case of an error and does not properly mark +the test case as failed. +As a result, it should only be used in subprocesses of the test case; specially +those spawned by +.Fn atf_utils_fork . +.Ed +.Pp +.Ft void +.Fo atf_utils_wait +.Fa "const pid_t pid" +.Fa "const int expected_exit_status" +.Fa "const char *expected_stdout" +.Fa "const char *expected_stderr" +.Fc +.Bd -ragged -offset indent +Waits and validates the result of a subprocess spawned with +.Fn atf_utils_wait . +The validation involves checking that the subprocess exited cleanly and returned +the code specified in +.Fa expected_exit_status +and that its standard output and standard error match the strings given in +.Fa expected_stdout +and +.Fa expected_stderr . +.Pp +If any of the +.Fa expected_stdout +or +.Fa expected_stderr +strings are prefixed with +.Sq save: , +then they specify the name of the file into which to store the stdout or stderr +of the subprocess, and no comparison is performed. +.Ed +.Sh EXAMPLES +The following shows a complete test program with a single test case that +validates the addition operator: +.Bd -literal -offset indent +#include + +ATF_TC(addition); +ATF_TC_HEAD(addition, tc) +{ + atf_tc_set_md_var(tc, "descr", + "Sample tests for the addition operator"); +} +ATF_TC_BODY(addition, tc) +{ + ATF_CHECK_EQ(0 + 0, 0); + ATF_CHECK_EQ(0 + 1, 1); + ATF_CHECK_EQ(1 + 0, 1); + + ATF_CHECK_EQ(1 + 1, 2); + + ATF_CHECK_EQ(100 + 200, 300); +} + +ATF_TC(string_formatting); +ATF_TC_HEAD(string_formatting, tc) +{ + atf_tc_set_md_var(tc, "descr", + "Sample tests for the snprintf"); +} +ATF_TC_BODY(string_formatting, tc) +{ + char buf[1024]; + snprintf(buf, sizeof(buf), "a %s", "string"); + ATF_CHECK_STREQ_MSG("a string", buf, "%s is not working"); +} + +ATF_TC(open_failure); +ATF_TC_HEAD(open_failure, tc) +{ + atf_tc_set_md_var(tc, "descr", + "Sample tests for the open function"); +} +ATF_TC_BODY(open_failure, tc) +{ + ATF_CHECK_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1); +} + +ATF_TC(known_bug); +ATF_TC_HEAD(known_bug, tc) +{ + atf_tc_set_md_var(tc, "descr", + "Reproduces a known bug"); +} +ATF_TC_BODY(known_bug, tc) +{ + atf_tc_expect_fail("See bug number foo/bar"); + ATF_CHECK_EQ(3, 1 + 1); + atf_tc_expect_pass(); + ATF_CHECK_EQ(3, 1 + 2); +} + +ATF_TP_ADD_TCS(tp) +{ + ATF_TP_ADD_TC(tp, addition); + ATF_TP_ADD_TC(tp, string_formatting); + ATF_TP_ADD_TC(tp, open_failure); + ATF_TP_ADD_TC(tp, known_bug); + + return atf_no_error(); +} +.Ed +.Sh SEE ALSO +.Xr atf-test-program 1 , +.Xr atf-test-case 4 , +.Xr atf 7 diff --git a/static/netbsd/man3/atf-sh-api.3 b/static/netbsd/man3/atf-sh-api.3 new file mode 100644 index 00000000..6e8abf73 --- /dev/null +++ b/static/netbsd/man3/atf-sh-api.3 @@ -0,0 +1,393 @@ +.\" +.\" Automated Testing Framework (atf) +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 15, 2017 +.Dt ATF-SH-API 3 +.Os +.Sh NAME +.Nm atf_add_test_case , +.Nm atf_check , +.Nm atf_check_equal , +.Nm atf_config_get , +.Nm atf_config_has , +.Nm atf_expect_death , +.Nm atf_expect_exit , +.Nm atf_expect_fail , +.Nm atf_expect_pass , +.Nm atf_expect_signal , +.Nm atf_expect_timeout , +.Nm atf_fail , +.Nm atf_get , +.Nm atf_get_srcdir , +.Nm atf_pass , +.Nm atf_require_prog , +.Nm atf_set , +.Nm atf_skip , +.Nm atf_test_case +.Nd POSIX shell API to write ATF-based test programs +.Sh SYNOPSIS +.Ic atf_add_test_case Dq name +.br +.Ic atf_check Dq command +.br +.Ic atf_check_equal Do expr1 Dc Dq expr2 +.br +.Ic atf_config_get Dq var_name +.br +.Ic atf_config_has Dq var_name +.br +.Ic atf_expect_death Do reason Dc Dq \&... +.br +.Ic atf_expect_exit Do exitcode Dc Do reason Dc Dq \&... +.br +.Ic atf_expect_fail Do reason Dc Dq \&... +.br +.Ic atf_expect_pass +.br +.Ic atf_expect_signal Do signo Dc Do reason Dc Dq \&... +.br +.Ic atf_expect_timeout Do reason Dc Dq \&... +.br +.Ic atf_fail Dq reason +.br +.Ic atf_get Dq var_name +.br +.Ic atf_get_srcdir +.br +.Ic atf_pass +.br +.Ic atf_require_prog Dq prog_name +.br +.Ic atf_set Do var_name Dc Dq value +.br +.Ic atf_skip Dq reason +.br +.Ic atf_test_case Do name Dc Dq cleanup +.br +.Sh DESCRIPTION +ATF +provides a simple but powerful interface to easily write test programs in +the POSIX shell language. +These are extremely helpful given that they are trivial to write due to the +language simplicity and the great deal of available external tools, so they +are often ideal to test other applications at the user level. +.Pp +Test programs written using this library must be run using the +.Xr atf-sh 1 +interpreter by putting the following on their very first line: +.Bd -literal -offset indent +#! /usr/bin/env atf-sh +.Ed +.Pp +Shell-based test programs always follow this template: +.Bd -literal -offset indent +atf_test_case tc1 +tc1_head() { + ... first test case's header ... +} +tc1_body() { + ... first test case's body ... +} + +atf_test_case tc2 cleanup +tc2_head() { + ... second test case's header ... +} +tc2_body() { + ... second test case's body ... +} +tc2_cleanup() { + ... second test case's cleanup ... +} + +.Ns ... additional test cases ... + +atf_init_test_cases() { + atf_add_test_case tc1 + atf_add_test_case tc2 + ... add additional test cases ... +} +.Ed +.Pp +All of these functions are required to return with an exit-status of +zero, or ATF will determine that the test is faulty. +In particular, this means that none may end with a conditional like: +.Bd -literal -offset indent +atf_sh_function() { + ... appropriate code here ... + condition-test && { + ... more code here ... + } +} +.Ed +.Pp +as if condition-test fails +the return code from atf_sh_function will not be 0. +This can be corrected by adding +.Bd -literal -offset indent + return 0 +.Ed +.Pp +before the end of the function, or by writing it as +.Bd -literal -offset indent +atf_sh_function() { + ... appropriate code here ... + if condition-test + then + ... more code here ... + fi +} +.Ed +.Ss Definition of test cases +Test cases have an identifier and are composed of three different parts: +the header, the body and an optional cleanup routine, all of which are +described in +.Xr atf-test-case 4 . +To define test cases, one can use the +.Ic atf_test_case +function, which takes a first parameter specifiying the test case's +name and instructs the library to set things up to accept it as a valid +test case. +The second parameter is optional and, if provided, must be +.Sq cleanup ; +providing this parameter allows defining a cleanup routine for the test +case. +It is important to note that this function +.Em does not +set the test case up for execution when the program is run. +In order to do so, a later registration is needed through the +.Ic atf_add_test_case +function detailed in +.Sx Program initialization . +.Pp +Later on, one must define the three parts of the body by providing two +or three functions (remember that the cleanup routine is optional). +These functions are named after the test case's identifier, and are +.Ic _head , +.Ic _body +and +.Ic _cleanup. +None of these take parameters when executed. +.Ss Program initialization +The test program must define an +.Ic atf_init_test_cases +function, which is in charge of registering the test cases that will be +executed at run time by using the +.Ic atf_add_test_case +function, which takes the name of a test case as its single parameter. +This main function should not do anything else, except maybe sourcing +auxiliary source files that define extra variables and functions, +or perhaps running simple tests to determine which test cases to add. +.Ss Configuration variables +The test case has read-only access to the current configuration variables +through the +.Ic atf_config_has +and +.Ic atf_config_get +methods. +The former takes a single parameter specifying a variable name and returns +a boolean indicating whether the variable is defined or not. +The latter can take one or two parameters. +If it takes only one, it specifies the variable from which to get the +value, and this variable must be defined. +If it takes two, the second one specifies a default value to be returned +if the variable is not available. +.Ss Access to the source directory +It is possible to get the path to the test case's source directory from +anywhere in the test program by using the +.Ic atf_get_srcdir +function. +It is interesting to note that this can be used inside +.Ic atf_init_test_cases +to silently include additional helper files from the source directory. +.Ss Requiring programs +Aside from the +.Va require.progs +meta-data variable available in the header only, one can also check for +additional programs in the test case's body by using the +.Ic atf_require_prog +function, which takes the base name or full path of a single binary. +Relative paths are forbidden. +If it is not found, the test case will be automatically skipped. +.Ss Test case finalization +The test case finalizes either when the body reaches its end, at which +point the test is assumed to have +.Em passed , +or at any explicit call to +.Ic atf_pass , +.Ic atf_fail +.Ic atf_skip . +These three functions terminate the execution of the test case immediately. +The cleanup routine will be processed afterwards in a completely automated +way, regardless of the test case's termination reason. +.Pp +.Fn atf_pass +does not take any parameters. +.Fn atf_fail +and +.Fn atf_skip +take a single string parameter that describes why the test case failed or +was skipped, respectively. +It is very important to provide a clear error message in both cases so that +the user can quickly know why the test did not pass. +This message must be a single line (no embedded newline characers.) +.Ss Expectations +Everything explained in the previous section changes when the test case +expectations are redefined by the programmer. +.Pp +Each test case has an internal state called +.Sq expect +that describes what the test case expectations are at any point in time. +The value of this property can change during execution by any of: +.Bl -tag -width indent +.It Ic atf_expect_death Do reason Dc Dq \&... +Expects the test case to exit prematurely regardless of the nature of the +exit. +.It Ic atf_expect_exit Do exitcode Dc Do reason Dc Dq \&... +Expects the test case to exit cleanly. +If +.Va exitcode +is not +.Sq \-1 , +.Xr atf-run 1 +will validate that the exit code of the test case matches the one provided +in this call. +Otherwise, the exact value will be ignored. +.It Ic atf_expect_fail Dq reason +Any failure raised in this mode is recorded, but such failures do not report +the test case as failed; instead, the test case finalizes cleanly and is +reported as +.Sq expected failure ; +this report includes the provided +.Fa reason +as part of it. +If no error is raised while running in this mode, then the test case is +reported as +.Sq failed . +.Pp +This mode is useful to reproduce actual known bugs in tests. +Whenever the developer fixes the bug later on, the test case will start +reporting a failure, signaling the developer that the test case must be +adjusted to the new conditions. +In this situation, it is useful, for example, to set +.Va reason +as the bug number for tracking purposes. +.It Ic atf_expect_pass +This is the normal mode of execution. +In this mode, any failure is reported as such to the user and the test case +is marked as +.Sq failed . +.It Ic atf_expect_signal Do signo Dc Do reason Dc Dq \&... +Expects the test case to terminate due to the reception of a signal. +If +.Va signo +is not +.Sq \-1 , +.Xr atf-run 1 +will validate that the signal that terminated the test case matches the one +provided in this call. +Otherwise, the exact value will be ignored. +.It Ic atf_expect_timeout Do reason Dc Dq \&... +Expects the test case to execute for longer than its timeout. +.El +.Ss Helper functions for common checks +.Ic atf_check Oo options Oc command Op args +.Pp +This function wraps the execution of the +.Nm atf-check +tool and makes the test case fail if the tool reports failure. +You should always use this function instead of the tool in your scripts. +For more details on the parameters of this function, refer to +.Xr atf-check 1 . +.Pp +.Ic atf_check_equal expr1 expr2 +.Pp +This function takes two expressions, evaluates them and, if their +results differ, aborts the test case with an appropriate failure message. +.Sh EXAMPLES +The following shows a complete test program with a single test case that +validates the addition operator: +.Bd -literal -offset indent +atf_test_case addition +addition_head() { + atf_set "descr" "Sample tests for the addition operator" +} +addition_body() { + atf_check_equal $((0 + 0)) 0 + atf_check_equal $((0 + 1)) 1 + atf_check_equal $((1 + 0)) 0 + + atf_check_equal $((1 + 1)) 2 + + atf_check_equal $((100 + 200)) 300 +} + +atf_init_test_cases() { + atf_add_test_case addition +} +.Ed +.Pp +This other example shows how to include a file with extra helper functions +in the test program: +.Bd -literal -offset indent +.Ns ... definition of test cases ... + +atf_init_test_cases() { + . $(atf_get_srcdir)/helper_functions.sh + + atf_add_test_case foo1 + atf_add_test_case foo2 +} +.Ed +.Pp +This example demonstrates the use of the very useful +.Fn atf_check +function: +.Bd -literal -offset indent +# Check for silent output +atf_check -s exit:0 -o empty -e empty 'true' + +# Check for silent output and failure +atf_check -s exit:1 -o empty -e empty 'false' + +# Check for known stdout and silent stderr +echo foo >expout +atf_check -s exit:0 -o file:expout -e empty 'echo foo' + +# Generate a file for later inspection +atf_check -s exit:0 -o save:stdout -e empty 'ls' +grep foo ls || atf_fail "foo file not found in listing" + +# Or just do the match along the way +atf_check -s exit:0 -o match:"^foo$" -e empty 'ls' +.Ed +.Sh SEE ALSO +.Xr atf-sh 1 , +.Xr atf-test-program 1 , +.Xr atf-test-case 4 , +.Xr atf 7 diff --git a/static/netbsd/man3/atof.3 b/static/netbsd/man3/atof.3 new file mode 100644 index 00000000..1d620f73 --- /dev/null +++ b/static/netbsd/man3/atof.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: atof.3,v 1.9 2003/08/07 16:43:38 agc Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atof.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt ATOF 3 +.Os +.Sh NAME +.Nm atof +.Nd convert +.Tn ASCII +string to double +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft double +.Fn atof "const char *nptr" +.Sh DESCRIPTION +The +.Fn atof +function converts the initial portion of the string pointed to by +.Ar nptr +to +.Ar double +representation. +.Pp +It is equivalent to: +.Bd -literal -offset indent +strtod(nptr, (char **)NULL); +.Ed +.Sh SEE ALSO +.Xr atoi 3 , +.Xr atol 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn atof +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/atoi.3 b/static/netbsd/man3/atoi.3 new file mode 100644 index 00000000..8a89c13b --- /dev/null +++ b/static/netbsd/man3/atoi.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: atoi.3,v 1.11 2018/06/13 09:38:32 eadler Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atoi.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 13, 2018 +.Dt ATOI 3 +.Os +.Sh NAME +.Nm atoi +.Nd convert +.Tn ASCII +string to integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn atoi "const char *nptr" +.Sh DESCRIPTION +The +.Fn atoi +function converts the initial portion of the string pointed to by +.Em nptr +to +.Em integer +representation. +.Pp +It is equivalent to: +.Bd -literal -offset indent +(int)strtol(nptr, NULL, 10); +.Ed +.Sh SEE ALSO +.Xr atof 3 , +.Xr atol 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn atoi +function conforms to +.St -ansiC . +.Sh CAVEATS +.Nm +does no overflow checking, handles unsigned numbers poorly, +and handles strings containing trailing extra characters +(like +.Dq 123abc ) +poorly. +Careful use of +.Xr strtol 3 +and +.Xr strtoul 3 +can alleviate these problems. diff --git a/static/netbsd/man3/atol.3 b/static/netbsd/man3/atol.3 new file mode 100644 index 00000000..1206adec --- /dev/null +++ b/static/netbsd/man3/atol.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: atol.3,v 1.8 2003/08/07 16:43:38 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atol.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt ATOL 3 +.Os +.Sh NAME +.Nm atol +.Nd convert +.Tn ASCII +string to long integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft long +.Fn atol "const char *nptr" +.Sh DESCRIPTION +The +.Fn atol +function converts the initial portion of the string pointed to by +.Ar nptr +to +.Em long integer +representation. +.Pp +It is equivalent to: +.Bd -literal -offset indent +strtol(nptr, (char **)NULL, 10); +.Ed +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn atol +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/atoll.3 b/static/netbsd/man3/atoll.3 new file mode 100644 index 00000000..0bdcd601 --- /dev/null +++ b/static/netbsd/man3/atoll.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: atoll.3,v 1.6 2003/09/08 17:54:33 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)atol.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd March 6, 2000 +.Dt ATOLL 3 +.Os +.Sh NAME +.Nm atoll +.Nd convert +.Tn ASCII +string to long long integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft long long int +.Fn atoll "const char *nptr" +.Sh DESCRIPTION +The +.Fn atoll +function converts the initial portion of the string pointed to by +.Ar nptr +to +.Em long long integer +representation. +.Pp +It is equivalent to: +.Bd -literal -offset indent +strtoll(nptr, (char **)NULL, 10); +.Ed +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoll 3 , +.Xr strtoul 3 , +.Xr strtoull 3 +.Sh STANDARDS +The +.Fn atoll +function +conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/atomic_add.3 b/static/netbsd/man3/atomic_add.3 new file mode 100644 index 00000000..b6f8adbb --- /dev/null +++ b/static/netbsd/man3/atomic_add.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: atomic_add.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_ADD 3 +.Os +.Sh NAME +.Nm atomic_add , +.Nm atomic_add_32 , +.Nm atomic_add_int , +.Nm atomic_add_long , +.Nm atomic_add_ptr , +.Nm atomic_add_64 , +.Nm atomic_add_32_nv , +.Nm atomic_add_int_nv , +.Nm atomic_add_long_nv , +.Nm atomic_add_ptr_nv , +.Nm atomic_add_64_nv +.Nd atomic add operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_add_32 "volatile uint32_t *ptr" "int32_t delta" +.Ft void +.Fn atomic_add_int "volatile unsigned int *ptr" "int delta" +.Ft void +.Fn atomic_add_long "volatile unsigned long *ptr" "long delta" +.Ft void +.Fn atomic_add_ptr "volatile void *ptr" "ssize_t delta" +.Ft void +.Fn atomic_add_64 "volatile uint64_t *ptr" "int64_t delta" +.Ft uint32_t +.Fn atomic_add_32_nv "volatile uint32_t *ptr" "int32_t delta" +.Ft unsigned int +.Fn atomic_add_int_nv "volatile unsigned int *ptr" "int delta" +.Ft unsigned long +.Fn atomic_add_long_nv "volatile unsigned long *ptr" "long delta" +.Ft void * +.Fn atomic_add_ptr_nv "volatile void *ptr" "ssize_t delta" +.Ft uint64_t +.Fn atomic_add_64_nv "volatile uint64_t *ptr" "int64_t delta" +.Sh DESCRIPTION +The +.Nm atomic_add +family of functions add a signed value +.Fa delta +to the variable referenced by +.Fa ptr +in an atomic fashion. +.Pp +The +.Fn *_nv +variants of these functions return the new value. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_add +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_and.3 b/static/netbsd/man3/atomic_and.3 new file mode 100644 index 00000000..f3e2c8d1 --- /dev/null +++ b/static/netbsd/man3/atomic_and.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: atomic_and.3,v 1.2 2018/06/16 08:11:32 dholland Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_AND 3 +.Os +.Sh NAME +.Nm atomic_and , +.Nm atomic_and_32 , +.Nm atomic_and_uint , +.Nm atomic_and_ulong , +.Nm atomic_and_64 , +.Nm atomic_and_32_nv , +.Nm atomic_and_uint_nv , +.Nm atomic_and_ulong_nv , +.Nm atomic_and_64_nv +.Nd atomic bitwise +.Sq and +operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_and_32 "volatile uint32_t *ptr" "uint32_t bits" +.Ft void +.Fn atomic_and_uint "volatile unsigned int *ptr" "unsigned int bits" +.Ft void +.Fn atomic_and_ulong "volatile unsigned long *ptr" "unsigned long bits" +.Ft void +.Fn atomic_and_64 "volatile uint64_t *ptr" "uint64_t bits" +.Ft uint32_t +.Fn atomic_and_32_nv "volatile uint32_t *ptr" "uint32_t bits" +.Ft unsigned int +.Fn atomic_and_uint_nv "volatile unsigned int *ptr" "unsigned int bits" +.Ft unsigned long +.Fn atomic_and_ulong_nv "volatile unsigned long *ptr" "unsigned long bits" +.Ft uint64_t +.Fn atomic_and_64_nv "volatile uint64_t *ptr" "uint64_t bits" +.Sh DESCRIPTION +The +.Nm atomic_and +family of functions load the value of the variable referenced by +.Fa ptr , +perform a bitwise +.Sq and +with the value +.Fa bits , +and store the result back to the variable referenced by +.Fa ptr +in an atomic fashion. +.Pp +The +.Fn *_nv +variants of these functions return the new value. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_and +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_cas.3 b/static/netbsd/man3/atomic_cas.3 new file mode 100644 index 00000000..04e4416e --- /dev/null +++ b/static/netbsd/man3/atomic_cas.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: atomic_cas.3,v 1.5 2014/02/02 18:06:33 dholland Exp $ +.\" +.\" Copyright (c) 2007, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 2, 2014 +.Dt ATOMIC_CAS 3 +.Os +.Sh NAME +.Nm atomic_cas , +.Nm atomic_cas_32 , +.Nm atomic_cas_uint , +.Nm atomic_cas_ulong , +.Nm atomic_cas_ptr , +.Nm atomic_cas_64 , +.Nm atomic_cas_32_ni , +.Nm atomic_cas_uint_ni , +.Nm atomic_cas_ulong_ni , +.Nm atomic_cas_ptr_ni , +.Nm atomic_cas_64_ni +.Nd atomic compare-and-swap operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft uint32_t +.Fn atomic_cas_32 "volatile uint32_t *ptr" "uint32_t expected" "uint32_t new" +.Ft unsigned int +.Fn atomic_cas_uint "volatile unsigned int *ptr" "unsigned int expected" \ + "unsigned int new" +.Ft unsigned long +.Fn atomic_cas_ulong "volatile unsigned long *ptr" "unsigned long expected" \ + "unsigned long new" +.Ft void * +.Fn atomic_cas_ptr "volatile void *ptr" "void *expected" "void *new" +.Ft uint64_t +.Fn atomic_cas_64 "volatile uint64_t *ptr" "uint64_t expected" "uint64_t new" +.Ft uint32_t +.Fn atomic_cas_32_ni "volatile uint32_t *ptr" "uint32_t expected" \ + "uint32_t new" +.Ft unsigned int +.Fn atomic_cas_uint_ni "volatile unsigned int *ptr" "unsigned int expected" \ + "unsigned int new" +.Ft unsigned long +.Fn atomic_cas_ulong_ni "volatile unsigned long *ptr" \ + "unsigned long expected" "unsigned long new" +.Ft void * +.Fn atomic_cas_ptr_ni "volatile void *ptr" "void *expected" "void *new" +.Ft uint64_t +.Fn atomic_cas_64_ni "volatile uint64_t *ptr" "uint64_t expected" \ + "uint64_t new" +.Sh DESCRIPTION +The +.Nm atomic_cas +family of functions perform an atomic conditional assignment. +The value +.Fa new +is assigned to the variable referenced by +.Fa ptr . +The assignment succeeds +if and only if its current value matches the value +.Fa expected . +If the value is different, the assignment fails and no change is +made. +This operation is sometimes known as +.Dq compare-and-swap . +These functions always return the value found via +.Fa ptr . +Callers test for success by comparing the return value to the value +passed as +.Fa expected ; +if they are equal then the new value was stored; if they are not, the +value was not changed. +.Pp +The non-interlocked variants, +.Fn *_ni , +guarantee atomicity within the same CPU with respect to +interrupts and preemption. +They are not atomic with respect to different CPUs. +These can be used to avoid interprocessor synchronization overhead +in some cases; for example, they are suitable for synchronized +operations on a variable shared by a thread and an interrupt that are +bound to the same CPU. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_cas +functions first appeared in +.Nx 5.0 . +.Sh NOTES +On some architectures, a +.Fn *_ni +variant is merely an alias for the corresponding standard +compare-and-swap operation. +While the non-interlocked variant behaves correctly on those +architectures, it does not avoid the interprocessor synchronization +overhead. diff --git a/static/netbsd/man3/atomic_dec.3 b/static/netbsd/man3/atomic_dec.3 new file mode 100644 index 00000000..654ed24a --- /dev/null +++ b/static/netbsd/man3/atomic_dec.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: atomic_dec.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_DEC 3 +.Os +.Sh NAME +.Nm atomic_dec , +.Nm atomic_dec_32 , +.Nm atomic_dec_uint , +.Nm atomic_dec_ulong , +.Nm atomic_dec_ptr , +.Nm atomic_dec_64 , +.Nm atomic_dec_32_nv , +.Nm atomic_dec_uint_nv , +.Nm atomic_dec_ulong_nv , +.Nm atomic_dec_ptr_nv , +.Nm atomic_dec_64_nv +.Nd atomic decrement operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_dec_32 "volatile uint32_t *ptr" +.Ft void +.Fn atomic_dec_uint "volatile unsigned int *ptr" +.Ft void +.Fn atomic_dec_ulong "volatile unsigned long *ptr" +.Ft void +.Fn atomic_dec_ptr "volatile void *ptr" +.Ft void +.Fn atomic_dec_64 "volatile uint64_t *ptr" +.Ft uint32_t +.Fn atomic_dec_32_nv "volatile uint32_t *ptr" +.Ft unsigned int +.Fn atomic_dec_uint_nv "volatile unsigned int *ptr" +.Ft unsigned long +.Fn atomic_dec_ulong_nv "volatile unsigned long *ptr" +.Ft void * +.Fn atomic_dec_ptr_nv "volatile void *ptr" +.Ft uint64_t +.Fn atomic_dec_64_nv "volatile uint64_t *ptr" +.Sh DESCRIPTION +The +.Nm atomic_dec +family of functions decrement +.Pq by one +the variable referenced by +.Fa ptr +in an atomic fashion. +.Pp +The +.Fn *_nv +variants of these functions return the new value. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_dec +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_inc.3 b/static/netbsd/man3/atomic_inc.3 new file mode 100644 index 00000000..a03429e9 --- /dev/null +++ b/static/netbsd/man3/atomic_inc.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: atomic_inc.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_INC 3 +.Os +.Sh NAME +.Nm atomic_inc , +.Nm atomic_inc_32 , +.Nm atomic_inc_uint , +.Nm atomic_inc_ulong , +.Nm atomic_inc_ptr , +.Nm atomic_inc_64 , +.Nm atomic_inc_32_nv , +.Nm atomic_inc_uint_nv , +.Nm atomic_inc_ulong_nv , +.Nm atomic_inc_ptr_nv , +.Nm atomic_inc_64_nv +.Nd atomic increment operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_inc_32 "volatile uint32_t *ptr" +.Ft void +.Fn atomic_inc_uint "volatile unsigned int *ptr" +.Ft void +.Fn atomic_inc_ulong "volatile unsigned long *ptr" +.Ft void +.Fn atomic_inc_ptr "volatile void *ptr" +.Ft void +.Fn atomic_inc_64 "volatile uint64_t *ptr" +.Ft uint32_t +.Fn atomic_inc_32_nv "volatile uint32_t *ptr" +.Ft unsigned int +.Fn atomic_inc_uint_nv "volatile unsigned int *ptr" +.Ft unsigned long +.Fn atomic_inc_ulong_nv "volatile unsigned long *ptr" +.Ft void * +.Fn atomic_inc_ptr_nv "volatile void *ptr" +.Ft uint64_t +.Fn atomic_inc_64_nv "volatile uint64_t *ptr" +.Sh DESCRIPTION +The +.Nm atomic_inc +family of functions increment +.Pq by one +the variable referenced by +.Fa ptr +in an atomic fashion. +.Pp +The +.Fn *_nv +variants of these functions return the new value. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_inc +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_ops.3 b/static/netbsd/man3/atomic_ops.3 new file mode 100644 index 00000000..bc24e951 --- /dev/null +++ b/static/netbsd/man3/atomic_ops.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: atomic_ops.3,v 1.10 2025/12/24 16:29:39 christos Exp $ +.\" +.\" Copyright (c) 2007, 2008, 2020, 2023 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe, and by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 24, 2025 +.Dt ATOMIC_OPS 3 +.Os +.Sh NAME +.Nm atomic_ops +.Nd atomic memory operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Sh DESCRIPTION +The +.Nm atomic_ops +family of functions provide atomic memory operations. +There are 7 classes of atomic memory operations available: +.Pp +.Bl -tag -width "atomic_swap(3)" -offset indent +.It Xr atomic_add 3 +These functions perform atomic addition. +.It Xr atomic_and 3 +These functions perform atomic bitwise +.Dq and . +.It Xr atomic_cas 3 +These functions perform atomic compare-and-swap. +.It Xr atomic_dec 3 +These functions perform atomic decrement. +.It Xr atomic_inc 3 +These functions perform atomic increment. +.It Xr atomic_or 3 +These functions perform atomic bitwise +.Dq or . +.It Xr atomic_swap 3 +These functions perform atomic swap. +.El +.Ss Synchronization Mechanisms +Where the architecture does not provide hardware support for atomic compare +and swap (CAS), atomicity is provided by a restartable sequence or by a +spinlock. +The chosen method is not ordinarily distinguishable by or visible to users +of the interface. +The following architectures can be assumed to provide CAS in hardware: +aarch64, alpha, amd64, i386, powerpc, powerpc64, sparc64. +.Ss Scope and Restrictions +If hardware CAS is available, the atomic operations are globally atomic: +operations within a memory region shared between processes are +guaranteed to be performed atomically. +If hardware CAS is not available, it may only be assumed that the operations +are atomic with respect to threads in the same process. +Additionally, if hardware CAS is not available, the atomic operations must +not be used within a signal handler. +.Pp +Users of atomic memory operations should not make assumptions about how +the memory access is performed +.Pq specifically, the width of the memory access . +For this reason, applications making use of atomic memory operations should +limit their use to regular memory. +The results of using atomic memory operations on anything other than +regular memory are undefined. +.Pp +Users of atomic memory operations should take care to modify any given +memory location either entirely with atomic operations or entirely with +some other synchronization mechanism. +Intermixing of atomic operations with other synchronization mechanisms +for the same memory location results in undefined behavior. +.Ss Visibility and Ordering of Memory Accesses +If hardware CAS is available, stores to the target memory location by an +atomic operation will reach global visibility before the operation +completes. +If hardware CAS is not available, the store may not reach global visibility +until some time after the atomic operation has completed. +However, in all cases a subsequent atomic operation on the same memory cell +will be delayed until the result of any preceding operation has reached +global visibility. +.Pp +Atomic operations are strongly ordered with respect to each other. +The global visibility of other loads and stores before and after an atomic +operation is undefined. +Applications that require synchronization of loads and stores with respect +to an atomic operation must use memory barriers. +See +.Xr membar_ops 3 . +.Ss Performance +Because atomic memory operations require expensive synchronization at the +hardware level, applications should take care to minimize their use. +In certain cases, it may be more appropriate to use a mutex, especially +if more than one memory location will be modified. +.Sh SEE ALSO +.Xr atomic_add 3 , +.Xr atomic_and 3 , +.Xr atomic_cas 3 , +.Xr atomic_dec 3 , +.Xr atomic_inc 3 , +.Xr atomic_or 3 , +.Xr atomic_swap 3 , +.Xr membar_ops 3 , +.Xr atomic_loadstore 9 +.Sh HISTORY +The +.Nm atomic_ops +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_or.3 b/static/netbsd/man3/atomic_or.3 new file mode 100644 index 00000000..42018362 --- /dev/null +++ b/static/netbsd/man3/atomic_or.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: atomic_or.3,v 1.2 2018/06/16 08:11:32 dholland Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_OR 3 +.Os +.Sh NAME +.Nm atomic_or , +.Nm atomic_or_32 , +.Nm atomic_or_uint , +.Nm atomic_or_ulong , +.Nm atomic_or_64 , +.Nm atomic_or_32_nv , +.Nm atomic_or_uint_nv , +.Nm atomic_or_ulong_nv , +.Nm atomic_or_64_nv +.Nd atomic bitwise +.Sq or +operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_or_32 "volatile uint32_t *ptr" "uint32_t bits" +.Ft void +.Fn atomic_or_uint "volatile unsigned int *ptr" "unsigned int bits" +.Ft void +.Fn atomic_or_ulong "volatile unsigned long *ptr" "unsigned long bits" +.Ft void +.Fn atomic_or_64 "volatile uint64_t *ptr" "uint64_t bits" +.Ft uint32_t +.Fn atomic_or_32_nv "volatile uint32_t *ptr" "uint32_t bits" +.Ft unsigned int +.Fn atomic_or_uint_nv "volatile unsigned int *ptr" "unsigned int bits" +.Ft unsigned long +.Fn atomic_or_ulong_nv "volatile unsigned long *ptr" "unsigned long bits" +.Ft uint64_t +.Fn atomic_or_64_nv "volatile uint64_t *ptr" "uint64_t bits" +.Sh DESCRIPTION +The +.Nm atomic_or +family of functions load the value of the variable referenced by +.Fa ptr , +perform a bitwise +.Sq or +with the value +.Fa bits , +and store the result back to the variable referenced by +.Fa ptr +in an atomic fashion. +.Pp +The +.Fn *_nv +variants of these functions return the new value. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_or +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/atomic_swap.3 b/static/netbsd/man3/atomic_swap.3 new file mode 100644 index 00000000..27436525 --- /dev/null +++ b/static/netbsd/man3/atomic_swap.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: atomic_swap.3,v 1.1 2008/06/23 10:22:40 ad Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2007 +.Dt ATOMIC_SWAP 3 +.Os +.Sh NAME +.Nm atomic_swap , +.Nm atomic_swap_32 , +.Nm atomic_swap_uint , +.Nm atomic_swap_ulong , +.Nm atomic_swap_ptr , +.Nm atomic_swap_64 +.Nd atomic swap operations +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.Ft uint32_t +.Fn atomic_swap_32 "volatile uint32_t *ptr" "uint32_t new" +.Ft unsigned int +.Fn atomic_swap_uint "volatile unsigned int *ptr" "unsigned int new" +.Ft unsigned long +.Fn atomic_swap_ulong "volatile unsigned long *ptr" "unsigned long new" +.Ft void * +.Fn atomic_swap_ptr "volatile void *ptr" "void *new" +.Ft uint64_t +.Fn atomic_swap_64 "volatile uint64_t *ptr" "uint64_t new" +.Sh DESCRIPTION +The +.Nm atomic_swap +family of functions perform a swap operation in an atomic fashion. +The value of the variable referenced by +.Fa ptr +is replaced by +.Fa new +and the old value returned. +.Pp +The 64-bit variants of these functions are available only on platforms +that can support atomic 64-bit memory access. +Applications can check for the availability of 64-bit atomic memory +operations by testing if the pre-processor macro +.Dv __HAVE_ATOMIC64_OPS +is defined. +.Sh SEE ALSO +.Xr atomic_ops 3 +.Sh HISTORY +The +.Nm atomic_swap +functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/b2i_PVK_bio_ex.3 b/static/netbsd/man3/b2i_PVK_bio_ex.3 new file mode 100644 index 00000000..25c281d5 --- /dev/null +++ b/static/netbsd/man3/b2i_PVK_bio_ex.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: b2i_PVK_bio_ex.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "b2i_PVK_bio_ex 3" +.TH b2i_PVK_bio_ex 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +b2i_PVK_bio, b2i_PVK_bio_ex, i2b_PVK_bio, i2b_PVK_bio_ex \- Decode and encode +functions for reading and writing MSBLOB format private keys +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *b2i_PVK_bio(BIO *in, pem_password_cb *cb, void *u); +\& EVP_PKEY *b2i_PVK_bio_ex(BIO *in, pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +\& int i2b_PVK_bio(BIO *out, const EVP_PKEY *pk, int enclevel, +\& pem_password_cb *cb, void *u); +\& int i2b_PVK_bio_ex(BIO *out, const EVP_PKEY *pk, int enclevel, +\& pem_password_cb *cb, void *u, +\& OSSL_LIB_CTX *libctx, const char *propq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBb2i_PVK_bio_ex()\fR decodes a private key of MSBLOB format read from a \fBBIO\fR. It +attempts to automatically determine the key type. If the key is encrypted then +\&\fIcb\fR is called with the user data \fIu\fR in order to obtain a password to decrypt +the key. The supplied library context \fIlibctx\fR and property query +string \fIpropq\fR are used in any decrypt operation. +.PP +\&\fBb2i_PVK_bio()\fR does the same as \fBb2i_PVK_bio_ex()\fR except that the default +library context and property query string are used. +.PP +\&\fBi2b_PVK_bio_ex()\fR encodes \fIpk\fR using MSBLOB format. If \fIenclevel\fR is 1 then +a password obtained via \fIpem_password_cb\fR is used to encrypt the private key. +If \fIenclevel\fR is 0 then no encryption is applied. The user data in \fIu\fR is +passed to the password callback. The supplied library context \fIlibctx\fR and +property query string \fIpropq\fR are used in any decrypt operation. +.PP +\&\fBi2b_PVK_bio()\fR does the same as \fBi2b_PVK_bio_ex()\fR except that the default +library context and property query string are used. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBb2i_PVK_bio()\fR and \fBb2i_PVK_bio_ex()\fR functions return a valid \fBEVP_KEY\fR +structure or \fBNULL\fR if an error occurs. The error code can be obtained by calling +\&\fBERR_get_error\fR\|(3). +.PP +\&\fBi2b_PVK_bio()\fR and \fBi2b_PVK_bio_ex()\fR return the number of bytes successfully +encoded or a negative value if an error occurs. The error code can be obtained +by calling \fBERR_get_error\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBd2i_PKCS8PrivateKey_bio\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBb2i_PVK_bio_ex()\fR and \fBi2b_PVK_bio_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/backtrace.3 b/static/netbsd/man3/backtrace.3 new file mode 100644 index 00000000..6d130ab4 --- /dev/null +++ b/static/netbsd/man3/backtrace.3 @@ -0,0 +1,181 @@ +.\" $NetBSD: backtrace.3,v 1.11 2025/01/23 12:08:12 christos Exp $ +.\" +.\" Copyright (c) 2012 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 22, 2025 +.Dt BACKTRACE 3 +.Os +.Sh NAME +.Nm backtrace , +.Nm backtrace_symbols , +.Nm backtrace_symbols_fd , +.Nm backtrace_symbols_fmt , +.Nm backtrace_symbols_fd_fmt +.Nd fill in the backtrace of the currently executing thread +.Sh LIBRARY +.Lb libexecinfo +.Sh SYNOPSIS +.In execinfo.h +.Ft size_t +.Fn backtrace "void **addrlist" "size_t len" +.Ft "int" +.Fn backtrace_sandbox_init "void" +.Ft "void" +.Fn backtrace_sandbox_fini "void" +.Ft "char **" +.Fn backtrace_symbols "void * const *addrlist" "size_t len" +.Ft int +.Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd" +.Ft "char **" +.Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt" +.Ft int +.Fn backtrace_symbols_fd_fmt "void * const *addrlist" "size_t len" "int fd" "const char *fmt" +.Sh DESCRIPTION +The +.Fn backtrace +function places into the array pointed by +.Fa addrlist +the array of the values of the program counter for each frame called up to +.Fa len +frames. +The number of frames found (which can be fewer than +.Fa len ) +is returned. +.Pp +The +.Fn backtrace_sandbox_init +and +.Fn backtrace_sandbox_fini +functions are intended to enable sandbox usage of +.Nm . +The +.Fn backtrace_sandbox_init +function must be called before the sandbox is entered, and will acquire any +resources needed to function in a sandbox. +The +.Fn backtrace_sandbox_fini +function will release the resources it acquired. +.Pp +The +.Fn backtrace_symbols_fmt +function takes an array of previously filled addresses from +.Fn backtrace +in +.Fa addrlist +of +.Fa len +elements, and uses +.Fa fmt +to format them. +The formatting characters available are: +.Bl -tag -width a -offset indent +.It Dv a +The numeric address of each element as would be printed using %p. +.It Dv n +The name of the nearest function symbol (smaller than the address element) +as determined by +.Xr dladdr 3 +if the symbol was dynamic, or looked up in the executable if static and +the /proc filesystem is available to determine the executable path. +.It Dv d +The difference of the symbol address and the address element printed +using 0x%tx. +.It Dv D +The difference of the symbol address and the address element printed using ++0x%tx if non-zero, or nothing if zero. +.It Dv f +The filename of the symbol as determined by +.Xr dladdr 3 . +.El +.Pp +The array of formatted strings is returned as a contiguous memory address which +can be freed by a single +.Xr free 3 . +.Pp +The +.Fn backtrace_symbols +function is equivalent of calling +.Fn backtrace_symbols_fmt +with a format argument of +.Dq "%a <%n%D> at %f" +.Pp +The +.Fn backtrace_symbols_fd +and +.Fn backtrace_symbols_fd_fmt +are similar to the non _fd named functions, only instead of returning +an array of strings, they print a new-line separated array of strings in +fd, and return +.Dv 0 +on success and +.Dv \-1 +on failure. +.Sh RETURN VALUES +The +.Fn backtrace +function returns the number of elements that were filled in the backtrace. +The +.Fn backtrace_symbols +and +.Fn backtrace_symbols_fmt +return a string array on success, and +.Dv NULL +on failure, setting +.Va errno . +Diagnostic output may also be produced by the ELF symbol lookup functions. +.Sh SEE ALSO +.Xr dladdr 3 , +.Xr elf 3 +.Sh HISTORY +The +.Fn backtrace +library of functions first appeared in +.Nx 7.0 . +.Sh BUGS +.Bl -enum +.It +Errors should not be printed but communicated to the caller differently. +.It +Because these functions use +.Xr elf 3 +this is a separate library instead of being part of libc/libutil +so that no library dependencies are introduced. +.It +The Linux versions of the functions (there are no _fmt variants) use +.Ft int +instead of +.Ft size_t +arguments. +.It +Since +.Xr dladdr 3 +only deals with dynamic symbols, we need to find the symbols from the main +portion of the program. +For that we need to locate the executable, and we use procfs for +finding it, which is not portable. +.El diff --git a/static/netbsd/man3/bad.include-toplevel.3 b/static/netbsd/man3/bad.include-toplevel.3 new file mode 100644 index 00000000..3a219a8a --- /dev/null +++ b/static/netbsd/man3/bad.include-toplevel.3 @@ -0,0 +1,6 @@ +include-toplevel: include.withclauses.* +server: + identity: "top 1" + include: include.withoutclauses.* + include-toplevel: include.withclauses.* +include: include.withoutclauses.* diff --git a/static/netbsd/man3/basename.3 b/static/netbsd/man3/basename.3 new file mode 100644 index 00000000..7fe1e96d --- /dev/null +++ b/static/netbsd/man3/basename.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: basename.3,v 1.14 2008/05/10 22:39:40 christos Exp $ +.\" +.\" Copyright (c) 1997, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein and Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 10, 2008 +.Dt BASENAME 3 +.Os +.Sh NAME +.Nm basename +.Nd return the last component of a pathname +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In libgen.h +.Ft char * +.Fn basename "char *path" +.Sh DESCRIPTION +The +.Fn basename +function takes the pathname pointed to by +.Ar path +and returns a pointer to the final component of the pathname, +deleting any trailing +.Sq / +characters. +.Pp +If +.Ar path +consists entirely of +.Sq / +characters, +.Fn basename +returns a pointer to the string +.Dq / . +.Pp +If +.Ar path +is a null pointer or points to an empty string, +.Fn basename +returns a pointer to the string +.Dq \&. . +.Sh RETURN VALUES +The +.Fn basename +function returns a pointer to the final component of +.Ar path . +.Sh SEE ALSO +.Xr basename 1 , +.Xr dirname 3 +.Sh STANDARDS +.Bl -bullet -compact +.It +.St -xpg4.2 +.It +.St -p1003.1-2001 +.El +.Sh BUGS +If the length of the result is longer than +.Dv PATH_MAX +bytes +.Pq including the terminating nul , +the result will be truncated. +.Pp +The +.Fn basename +function returns a pointer to static storage that may be overwritten +by subsequent calls to +.Fn basename . +This is not strictly a bug; it is explicitly allowed by +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/bcmp.3 b/static/netbsd/man3/bcmp.3 new file mode 100644 index 00000000..c78c2571 --- /dev/null +++ b/static/netbsd/man3/bcmp.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bcmp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bcmp.3,v 1.14 2012/05/05 21:24:19 dholland Exp $ +.\" +.Dd May 5, 2012 +.Dt BCMP 3 +.Os +.Sh NAME +.Nm bcmp +.Nd compare byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fn bcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn bcmp +function +compares byte string +.Fa b1 +against byte string +.Fa b2 , +returning zero if they are identical, non-zero otherwise. +Both strings are assumed to be +.Fa len +bytes long. +Zero-length strings are always identical. +.Pp +The strings may overlap. +.Pp +This function is obsolete. +The equivalent function +.Xr memcmp 3 +should be used instead. +.Sh SEE ALSO +.Xr memcmp 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn bcmp +function conforms to +.St -p1003.1-2001 . +The +.St -p1003.1-2004 +revision marked it as legacy and recommended the use of +.Xr memcmp 3 +instead. +The +.St -p1003.1-2008 +revision removed +.Fn bcmp +from the specification. +.Sh HISTORY +A +.Fn bcmp +function first appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/bcopy.3 b/static/netbsd/man3/bcopy.3 new file mode 100644 index 00000000..d806a007 --- /dev/null +++ b/static/netbsd/man3/bcopy.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bcopy.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bcopy.3,v 1.15 2015/06/20 04:18:00 dholland Exp $ +.\" +.Dd May 5, 2012 +.Dt BCOPY 3 +.Os +.Sh NAME +.Nm bcopy +.Nd copy byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft void +.Fn bcopy "const void *src" "void *dst" "size_t len" +.Sh DESCRIPTION +The +.Fn bcopy +function +copies +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +The two strings may overlap. +If +.Fa len +is zero, no bytes are copied. +.Pp +This function is obsolete. +The functions +.Xr memcpy 3 +and/or +.Xr memmove 3 +should be used instead. +Note that +.Fn bcopy +takes its +.Fa src +and +.Fa dst +arguments in the opposite order from these. +.Sh SEE ALSO +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strncpy 3 +.Sh STANDARDS +The +.Fn bcopy +function conforms to +.St -p1003.1-2001 . +The +.St -p1003.1-2004 +revision marked it as legacy; the +.St -p1003.1-2008 +revision removed it from the specification. +.Sh HISTORY +A +.Fn bcopy +function appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/bind_textdomain_codeset.3 b/static/netbsd/man3/bind_textdomain_codeset.3 new file mode 100644 index 00000000..376c92b0 --- /dev/null +++ b/static/netbsd/man3/bind_textdomain_codeset.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; 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 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" GNU gettext source code and manual +.\" LI18NUX 2000 Globalization Specification +.\" +.TH BIND_TEXTDOMAIN_CODESET 3 "May 2001" "GNU gettext 0.16.1" +.SH NAME +bind_textdomain_codeset \- set encoding of message translations +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char * bind_textdomain_codeset (const char * " domainname , +.BI " const char * " codeset ); +.fi +.SH DESCRIPTION +The \fBbind_textdomain_codeset\fP function sets the output codeset for message +catalogs for domain \fIdomainname\fP. +.PP +A message domain is a set of translatable \fImsgid\fP messages. Usually, +every software package has its own message domain. +.PP +By default, the \fBgettext\fP family of functions returns translated messages +in the locale's character encoding, which can be retrieved as +\fBnl_langinfo(CODESET)\fP. The need for calling \fBbind_textdomain_codeset\fP +arises for programs which store strings in a locale independent way (e.g. +UTF-8) and want to avoid an extra character set conversion on the returned +translated messages. +.PP +\fIdomainname\fP must be a non-empty string. +.PP +If \fIcodeset\fP is not NULL, it must be a valid encoding name which can be +used for the \fBiconv_open\fP function. The \fBbind_textdomain_codeset\fP +function sets the output codeset for message catalogs belonging to domain +\fIdomainname\fP to \fIcodeset\fP. The function makes copies of the argument +strings as needed. +.PP +If \fIcodeset\fP is NULL, the function returns the previously set codeset for +domain \fIdomainname\fP. The default is NULL, denoting the locale's character +encoding. +.SH "RETURN VALUE" +If successful, the \fBbind_textdomain_codeset\fP function returns the current +codeset for domain \fIdomainname\fP, after possibly changing it. The resulting +string is valid until the next \fBbind_textdomain_codeset\fP call for the same +\fIdomainname\fP and must not be modified or freed. If a memory allocation +failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns NULL. If no +codeset has been set for domain \fIdomainname\fP, it returns NULL. +.SH ERRORS +The following error can occur, among others: +.TP +.B ENOMEM +Not enough memory available. +.SH BUGS +The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid +warnings in C code predating ANSI C. +.SH "SEE ALSO" +.BR gettext (3), +.BR dgettext (3), +.BR dcgettext (3), +.BR ngettext (3), +.BR dngettext (3), +.BR dcngettext (3), +.BR textdomain (3), +.BR nl_langinfo (3), +.BR iconv_open (3) diff --git a/static/netbsd/man3/bindresvport.3 b/static/netbsd/man3/bindresvport.3 new file mode 100644 index 00000000..3d317825 --- /dev/null +++ b/static/netbsd/man3/bindresvport.3 @@ -0,0 +1,106 @@ +.\" @(#)bindresvport.3n 2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI +.\" $NetBSD: bindresvport.3,v 1.14 2017/07/03 21:32:49 wiz Exp $ +.\" +.Dd January 27, 2007 +.Dt BINDRESVPORT 3 +.Os +.Sh NAME +.Nm bindresvport , +.Nm bindresvport_sa +.Nd bind a socket to a reserved privileged IP port +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In rpc/rpc.h +.Ft int +.Fn bindresvport "int sd" "struct sockaddr_in *sin" +.Ft int +.Fn bindresvport_sa "int sd" "struct sockaddr *sa" +.Sh DESCRIPTION +.Fn bindresvport +and +.Fn bindresvport_sa +are used to bind a socket descriptor to a reserved privileged +.Tn IP +port, that is, a +port number in the range 0-1023. +The routine returns 0 if it is successful, +otherwise -1 is returned and +.Va errno +set to reflect the cause of the error. +.Pp +If +.Fa sin +is a pointer to a +.Ft "struct sockaddr_in" +then the appropriate fields in the structure should be defined. +Note that +.Fa sin->sin_family +must be initialized to the address family of the socket, passed by +.Fa sd . +If +.Fa sin->sin_port +is +.Sq 0 +then a port (in the range 600-1023) will be +chosen, and if +.Xr bind 2 +is successful, the +.Fa sin->sin_port +will be updated to contain the allocated port. +.Pp +If +.Fa sin +is the +.Dv NULL +pointer, +a port will be allocated (as above). +However, there is no way for +.Fn bindresvport +to return the allocated port in this case. +.Xr getsockname 2 +can be used to determine the assigned port. +.Pp +Only root can bind to a privileged port; this call will fail for any +other users. +.Pp +Function prototype of +.Fn bindresvport +is biased to +.Dv AF_INET +socket. +.Fn bindresvport_sa +acts exactly the same, with more neutral function prototype. +Note that both functions behave exactly the same, and +both support +.Dv AF_INET6 +sockets as well as +.Dv AF_INET +sockets. +.Sh RETURN VALUES +If the bind is successful, a 0 value is returned. +A return value of -1 indicates an error, which is +further specified in the global +.Va errno . +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPFNOSUPPORT +If second argument was supplied, +and address family did not match between arguments. +.El +.Pp +.Fn bindresvport +may also fail and set +.Va errno +for any of the errors specified for the calls +.Xr bind 2 , +.Xr getsockopt 2 , +or +.Xr setsockopt 2 . +.Sh SEE ALSO +.Xr bind 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr setsockopt 2 , +.Xr ip 4 diff --git a/static/netbsd/man3/bindtextdomain.3 b/static/netbsd/man3/bindtextdomain.3 new file mode 100644 index 00000000..e076828b --- /dev/null +++ b/static/netbsd/man3/bindtextdomain.3 @@ -0,0 +1,69 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; 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 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" GNU gettext source code and manual +.\" LI18NUX 2000 Globalization Specification +.\" +.TH BINDTEXTDOMAIN 3 "May 2001" "GNU gettext 0.16.1" +.SH NAME +bindtextdomain \- set directory containing message catalogs +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char * bindtextdomain (const char * " domainname ", const char * " dirname ); +.fi +.SH DESCRIPTION +The \fBbindtextdomain\fP function sets the base directory of the hierarchy +containing message catalogs for a given message domain. +.PP +A message domain is a set of translatable \fImsgid\fP messages. Usually, +every software package has its own message domain. The need for calling +\fBbindtextdomain\fP arises because packages are not always installed with +the same prefix as the header and the libc/libintl libraries. +.PP +Message catalogs will be expected at the pathnames +\fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo, +where \fIlocale\fP is a locale name and \fIcategory\fP is a locale facet such +as \fBLC_MESSAGES\fP. +.PP +\fIdomainname\fP must be a non-empty string. +.PP +If \fIdirname\fP is not NULL, the base directory for message catalogs belonging +to domain \fIdomainname\fP is set to \fIdirname\fP. The function makes copies +of the argument strings as needed. If the program wishes to call the +\fBchdir\fP function, it is important that \fIdirname\fP be an absolute +pathname; otherwise it cannot be guaranteed that the message catalogs will +be found. +.PP +If \fIdirname\fP is NULL, the function returns the previously set base +directory for domain \fIdomainname\fP. +.SH "RETURN VALUE" +If successful, the \fBbindtextdomain\fP function returns the current base +directory for domain \fIdomainname\fP, after possibly changing it. The +resulting string is valid until the next \fBbindtextdomain\fP call for the +same \fIdomainname\fP and must not be modified or freed. If a memory allocation +failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns NULL. +.SH ERRORS +The following error can occur, among others: +.TP +.B ENOMEM +Not enough memory available. +.SH BUGS +The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid +warnings in C code predating ANSI C. +.SH "SEE ALSO" +.BR gettext (3), +.BR dgettext (3), +.BR dcgettext (3), +.BR ngettext (3), +.BR dngettext (3), +.BR dcngettext (3), +.BR textdomain (3), +.BR realpath (3) diff --git a/static/netbsd/man3/bluetooth.3 b/static/netbsd/man3/bluetooth.3 new file mode 100644 index 00000000..1202d246 --- /dev/null +++ b/static/netbsd/man3/bluetooth.3 @@ -0,0 +1,300 @@ +.\" $NetBSD: bluetooth.3,v 1.10 2022/12/04 01:29:31 uwe Exp $ +.\" +.\" Copyright (c) 2003 Maksim Yevmenkin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $ +.\" +.Dd October 25, 2011 +.Dt BLUETOOTH 3 +.Os +.Sh NAME +.Nm bt_gethostbyname , +.Nm bt_gethostbyaddr , +.Nm bt_gethostent , +.Nm bt_sethostent , +.Nm bt_endhostent , +.Nm bt_getprotobyname , +.Nm bt_getprotobynumber , +.Nm bt_getprotoent , +.Nm bt_setprotoent , +.Nm bt_endprotoent , +.Nm bt_aton , +.Nm bt_ntoa +.Nd Bluetooth host lookup routines +.Sh LIBRARY +.Lb libbluetooth +.Sh SYNOPSIS +.In bluetooth.h +.Ft struct hostent * +.Fn bt_gethostbyname "const char *name" +.Ft struct hostent * +.Fn bt_gethostbyaddr "const char *addr" "int len" "int type" +.Ft struct hostent * +.Fn bt_gethostent void +.Ft void +.Fn bt_sethostent "int stayopen" +.Ft void +.Fn bt_endhostent void +.Ft struct protoent * +.Fn bt_getprotobyname "const char *name" +.Ft struct protoent * +.Fn bt_getprotobynumber "int proto" +.Ft struct protoent * +.Fn bt_getprotoent void +.Ft void +.Fn bt_setprotoent "int stayopen" +.Ft void +.Fn bt_endprotoent void +.Ft int +.Fn bt_aton "const char *str" "bdaddr_t *ba" +.Ft const char * +.Fn bt_ntoa "const bdaddr_t *ba" "char *str" +.Sh DESCRIPTION +The +.Fn bt_gethostent , +.Fn bt_gethostbyname , +and +.Fn bt_gethostbyaddr +functions each return a pointer to an object with the +.Vt hostent +structure describing a Bluetooth host +referenced by name or by address, respectively. +.Pp +The +.Fa name +argument passed to +.Fn bt_gethostbyname +should point to a +.Dv NUL Ns -terminated +hostname. +The +.Fa addr +argument passed to +.Fn bt_gethostbyaddr +should point to an address which is +.Fa len +bytes long, +in binary form +(i.e., not a Bluetooth BD_ADDR in human readable +.Tn ASCII +form). +The +.Fa type +argument specifies the address family of this address and must be set to +.Dv AF_BLUETOOTH . +.Pp +The structure returned contains the information obtained from a line in +.Pa /etc/bluetooth/hosts +file. +.Pp +The +.Fn bt_sethostent +function controls whether +.Pa /etc/bluetooth/hosts +file should stay open after each call to +.Fn bt_gethostbyname +or +.Fn bt_gethostbyaddr . +If the +.Fa stayopen +flag is non-zero, the file will not be closed. +.Pp +The +.Fn bt_endhostent +function closes the +.Pa /etc/bluetooth/hosts +file. +.Pp +The +.Fn bt_getprotoent , +.Fn bt_getprotobyname , +and +.Fn bt_getprotobynumber +functions each return a pointer to an object with the +.Vt protoent +structure describing a Bluetooth Protocol Service Multiplexer referenced +by name or number, respectively. +.Pp +The +.Fa name +argument passed to +.Fn bt_getprotobyname +should point to a +.Dv NUL Ns -terminated +Bluetooth Protocol Service Multiplexer name. +The +.Fa proto +argument passed to +.Fn bt_getprotobynumber +should have numeric value of the desired Bluetooth Protocol Service +Multiplexer. +.Pp +The structure returned contains the information obtained from a line in +.Pa /etc/bluetooth/protocols +file. +.Pp +The +.Fn bt_setprotoent +function controls whether +.Pa /etc/bluetooth/protocols +file should stay open after each call to +.Fn bt_getprotobyname +or +.Fn bt_getprotobynumber . +If the +.Fa stayopen +flag is non-zero, the file will not be closed. +.Pp +The +.Fn bt_endprotoent +function closes the +.Pa /etc/bluetooth/protocols +file. +.Pp +The +.Fn bt_aton +routine interprets the specified character string as a Bluetooth address, +placing the address into the structure provided. +It returns 1 if the string was successfully interpreted, +or 0 if the string is invalid. +.Pp +The routine +.Fn bt_ntoa +takes a Bluetooth address and places an +.Tn ASCII +string representing the address into the buffer provided. +It is up to the caller to ensure that provided buffer has enough space. +If no buffer was provided then an internal static buffer will be used. +.Sh FILES +.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact +.It Pa /etc/bluetooth/hosts +.It Pa /etc/bluetooth/protocols +.El +.Sh EXAMPLES +Print out the hostname associated with a specific BD_ADDR: +.Bd -literal -offset indent +const char *bdstr = "00:01:02:03:04:05"; +bdaddr_t bd; +struct hostent *hp; + +if (!bt_aton(bdstr, &bd)) + errx(1, "can't parse BD_ADDR %s", bdstr); + +if ((hp = bt_gethostbyaddr((const char *)&bd, + sizeof(bd), AF_BLUETOOTH)) == NULL) + errx(1, "no name associated with %s", bdstr); + +printf("name associated with %s is %s\en", bdstr, hp->h_name); +.Ed +.Sh RETURN VALUES +Error return status from +.Fn bt_gethostent , +.Fn bt_gethostbyname , +and +.Fn bt_gethostbyaddr +is indicated by return of a +.Dv NULL +pointer. +The external integer +.Va h_errno +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The routine +.Xr herror 3 +can be used to print an error message describing the failure. +If its argument +.Fa string +is +.Pf non- Dv NULL , +it is printed, followed by a colon and a space. +The error message is printed with a trailing newline. +.Pp +The variable +.Va h_errno +can have the following values: +.Bl -tag -width ".Dv HOST_NOT_FOUND" +.It Dv HOST_NOT_FOUND +No such host is known. +.It Dv NO_RECOVERY +Some unexpected server failure was encountered. +This is a non-recoverable error. +.El +.Pp +The +.Fn bt_getprotoent , +.Fn bt_getprotobyname , +and +.Fn bt_getprotobynumber +return +.Dv NULL +on EOF or error. +.Sh SEE ALSO +.Xr gethostbyaddr 3 , +.Xr gethostbyname 3 , +.Xr getprotobyname 3 , +.Xr getprotobynumber 3 , +.Xr herror 3 , +.Xr inet_aton 3 , +.Xr inet_ntoa 3 +.Sh HISTORY +.Nm libbluetooth +first appeared in +.Fx +was ported to +.Nx 4.0 +and extended by +.An Iain Hibbert +for Itronix, Inc. +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.An Iain Hibbert +.Sh CAVEATS +The +.Fn bt_gethostent +function reads the next line of +.Pa /etc/bluetooth/hosts , +opening the file if necessary. +.Pp +The +.Fn bt_sethostent +function opens and/or rewinds the +.Pa /etc/bluetooth/hosts +file. +.Pp +The +.Fn bt_getprotoent +function reads the next line of +.Pa /etc/bluetooth/protocols , +opening the file if necessary. +.Pp +The +.Fn bt_setprotoent +function opens and/or rewinds the +.Pa /etc/bluetooth/protocols +file. +.Sh BUGS +These functions use static data storage; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. diff --git a/static/netbsd/man3/bm.3 b/static/netbsd/man3/bm.3 new file mode 100644 index 00000000..cd4e9fc4 --- /dev/null +++ b/static/netbsd/man3/bm.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: bm.3,v 1.9 2016/01/23 00:43:42 dholland Exp $ +.\" +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Andrew Hume of AT&T Bell Laboratories. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bm.3 8.4 (Berkeley) 6/21/94 +.\" +.Dd April 8, 2001 +.Dt BM 3 +.Os +.Sh NAME +.Nm bm_comp , +.Nm bm_exec , +.Nm bm_free +.Nd Boyer-Moore string search +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In bm.h +.Ft bm_pat * +.Fn bm_comp "unsigned char *pattern" "size_t patlen" "unsigned char freq[256]" +.Ft unsigned char * +.Fn bm_exec "bm_pat *pdesc" "unsigned char *text" "size_t len" +.Ft void +.Fn bm_free "bm_pat *pdesc" +.Sh DESCRIPTION +These routines implement an efficient mechanism to find an +occurrence of a byte string within another byte string. +.Pp +.Fn bm_comp +evaluates the +.Fa patlen +bytes starting at +.Fa pattern , +and returns a pointer to a structure describing them. +The bytes referenced by +.Fa pattern +may be of any value. +.Pp +The search takes advantage of the frequency distribution of the +bytes in the text to be searched. +If specified, +.Fa freq +should be an array of 256 values, +with higher values indicating that the corresponding character occurs +more frequently. +(A less than optimal frequency distribution can only result in less +than optimal performance, not incorrect results.) +If +.Fa freq +is +.Dv NULL , +a system default table is used. +.Pp +.Fn bm_exec +returns a pointer to the leftmost occurrence of the string given to +.Fn bm_comp +within +.Fa text , +or +.Dv NULL +if none occurs. +The number of bytes in +.Fa text +must be specified by +.Fa len . +.Pp +Space allocated for the returned description is discarded +by calling +.Fn bm_free +with the returned description as an argument. +.Pp +The asymptotic speed of +.Fn bm_exec +is O(len/patlen). +.Sh SEE ALSO +.Xr regexp 3 , +.Xr strstr 3 +.Rs +.%A Hume and Sunday +.%D November 1991 +.%J "Software Practice and Experience" +.%P pp. 1221-48 +.%T "Fast String Searching" +.%V Vol. 21, 11 +.Re diff --git a/static/netbsd/man3/bsd_signal.3 b/static/netbsd/man3/bsd_signal.3 new file mode 100644 index 00000000..47e7690f --- /dev/null +++ b/static/netbsd/man3/bsd_signal.3 @@ -0,0 +1,68 @@ +.\" $NetBSD: bsd_signal.3,v 1.2 2016/06/06 08:27:22 wiz Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)bsd_signal.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd June 4, 2016 +.Dt BSD_SIGNAL 3 +.Os +.Sh NAME +.Nm bsd_signal +.Nd BSD version of +.Xr signal 3 +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.\" The following is Quite Ugly, but syntactically correct. Don't try to +.\" fix it. +.Ft void \*(lp* +.Fn bsd_signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint" +.Sh DESCRIPTION +The +.Fn bsd_signal +function provides a partially compatible interface for programs written to +historical system interfaces. +.Sh RETURN VALUES +The previous action is returned on a successful call. +Otherwise, +.Dv SIG_ERR +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh SEE ALSO +.Xr signal 3 +.Sh STANDARDS +The +.Fn bsd_signal +function conforms to +.St -p1003.1-2004 . +It was moved from X/Open to zbase in Issue 4 version 2. +It first appeared in +.Nx 8 . diff --git a/static/netbsd/man3/bsdmalloc.3 b/static/netbsd/man3/bsdmalloc.3 new file mode 100644 index 00000000..b6d93398 --- /dev/null +++ b/static/netbsd/man3/bsdmalloc.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: bsdmalloc.3,v 1.3 2023/07/06 01:32:52 uwe Exp $ +.\" +.\" Copyright (c) 2023 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 4, 2023 +.Dt BSDMALLOC 3 +.Os +.Sh NAME +.Nm bsdmalloc +.Nd lightweight historic BSD memory allocator replacement +.Sh LIBRARY +.Lb libbsdmalloc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn malloc "size_t size" +.Ft void * +.Fn calloc "size_t nmemb" "size_t size" +.Ft void * +.Fn realloc "void *ptr" "size_t size" +.Ft void * +.Fn aligned_alloc "size_t alignment" "size_t size" +.Ft int +.Fn posix_memalign "void **memptr" "size_t alignment" "size_t size" +.Ft void +.Fn free "void *ptr" +.Ft void +.Fn _malloc_prefork "void" +.Ft void +.Fn _malloc_postfork "void" +.Ft void +.Fn _malloc_postfork_child "void" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +library provides a lower-performance but smaller-size drop-in +replacement for the standard +.Xr malloc 3 +family of functions provided by +.Lb libc , +as well as internal hooks for +.Xr fork 2 +safety in multithreaded programs. +.Pp +Programs can be statically linked with +.Li -lbsdmalloc +for smaller code footprint, at a higher cost to run-time performance +and scalability and limited diagnostics. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr malloc 3 , +.Xr posix_memalign 3 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh BUGS +.Nm Ns No 's +implementation of +.Fn malloc , +.Fn calloc , +and +.Fn realloc +doesn't correctly set +.Xr errno 2 +on failure. diff --git a/static/netbsd/man3/bsearch.3 b/static/netbsd/man3/bsearch.3 new file mode 100644 index 00000000..5653e9d1 --- /dev/null +++ b/static/netbsd/man3/bsearch.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: bsearch.3,v 1.10 2003/08/07 16:43:38 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bsearch.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd April 19, 1994 +.Dt BSEARCH 3 +.Os +.Sh NAME +.Nm bsearch +.Nd binary search of a sorted table +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn bsearch "const void *key" "const void *base" "size_t nmemb" "size_t size" "int (*compar) (const void *, const void *)" +.Sh DESCRIPTION +The +.Fn bsearch +function searches an array of +.Fa nmemb +objects, the initial member of which is +pointed to by +.Fa base , +for a member that matches the object pointed to by +.Fa key . +The size of each member of the array is specified by +.Fa size . +.Pp +The contents of the array should be in ascending sorted order according +to the comparison function referenced by +.Fa compar . +The +.Fa compar +routine +is expected to have +two arguments which point to the +.Fa key +object and to an array member, in that order, and should return an integer +less than, equal to, or greater than zero if the +.Fa key +object is found, respectively, to be less than, to match, or be +greater than the array member. +.Sh RETURN VALUES +The +.Fn bsearch +function returns a pointer to a matching member of the array, or a null +pointer if no match is found. +If two members compare as equal, which member is matched is unspecified. +.Sh SEE ALSO +.Xr db 3 , +.Xr lsearch 3 , +.Xr qsort 3 , +.Xr tsearch 3 +.Sh STANDARDS +The +.Fn bsearch +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/bstring.3 b/static/netbsd/man3/bstring.3 new file mode 100644 index 00000000..b85ef8f8 --- /dev/null +++ b/static/netbsd/man3/bstring.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bstring.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bstring.3,v 1.11 2007/02/17 09:04:57 wiz Exp $ +.\" +.Dd February 9, 2007 +.Dt BSTRING 3 +.Os +.Sh NAME +.Nm memccpy , +.Nm memchr , +.Nm memcmp , +.Nm memcpy , +.Nm memmem , +.Nm memmove , +.Nm memset +.Nd byte string operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memchr "const void *b" "int c" "size_t len" +.Ft int +.Fn memcmp "const void *b1" "const void *b2" "size_t len" +.Ft void * +.Fn memccpy "void *dst" "const void *src" "int c" "size_t len" +.Ft void * +.Fn memcpy "void *dst" "const void *src" "size_t len" +.Ft void * +.Fn memmem "const void *block" "size_t blen" "const void *pat" "size_t plen" +.Ft void * +.Fn memmove "void *dst" "const void *src" "size_t len" +.Ft void * +.Fn memset "void *b" "int c" "size_t len" +.Sh DESCRIPTION +These functions operate on variable length strings of bytes. +They do not check for terminating nul bytes as the routines +listed in +.Xr string 3 +do. +.Pp +See the specific manual pages for more information. +.Sh SEE ALSO +.Xr memccpy 3 , +.Xr memchr 3 , +.Xr memcmp 3 , +.Xr memcpy 3 , +.Xr memmem 3 , +.Xr memmove 3 , +.Xr memset 3 +.Sh STANDARDS +The functions +.Fn memchr , +.Fn memcmp , +.Fn memcpy , +.Fn memmove , +and +.Fn memset +conform to +.St -ansiC . +.Sh HISTORY +The function +.Fn memccpy +appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/bswap.3 b/static/netbsd/man3/bswap.3 new file mode 100644 index 00000000..cb8d03f0 --- /dev/null +++ b/static/netbsd/man3/bswap.3 @@ -0,0 +1,54 @@ +.\" $NetBSD: bswap.3,v 1.11 2009/10/22 21:50:01 bouyer Exp $ +.\" +.\" Copyright (c) 1998 Manuel Bouyer. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 17, 1998 +.Dt BSWAP 3 +.Os +.Sh NAME +.Nm bswap16 , +.Nm bswap32 , +.Nm bswap64 +.Nd byte-order swapping functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In machine/bswap.h +.Ft uint16_t +.Fn bswap16 "uint16_t" +.Ft uint32_t +.Fn bswap32 "uint32_t" +.Ft uint64_t +.Fn bswap64 "uint64_t" +.Sh DESCRIPTION +The +.Fn bswap16 , +.Fn bswap32 , +and +.Fn bswap64 +functions return the value of their argument with the bytes inverted. +They can be used to convert 16, 32 or 64 bits integers from little to big +endian, or vice-versa. +.Sh SEE ALSO +.Xr byteorder 3 diff --git a/static/netbsd/man3/bt_dev.3 b/static/netbsd/man3/bt_dev.3 new file mode 100644 index 00000000..9c8489ed --- /dev/null +++ b/static/netbsd/man3/bt_dev.3 @@ -0,0 +1,373 @@ +.\" $NetBSD: bt_dev.3,v 1.4 2016/01/22 08:51:40 plunky Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 25, 2011 +.Dt BT_DEV 3 +.Os +.Sh NAME +.Nm bt_devaddr , +.Nm bt_devname , +.Nm bt_devenum , +.Nm bt_devinfo , +.Nm bt_devopen , +.Nm bt_devsend , +.Nm bt_devrecv , +.Nm bt_devreq , +.Nm bt_devfilter , +.Nm bt_devfilter_pkt_set , +.Nm bt_devfilter_pkt_clr , +.Nm bt_devfilter_pkt_tst , +.Nm bt_devfilter_evt_set , +.Nm bt_devfilter_evt_clr , +.Nm bt_devfilter_evt_tst , +.Nm bt_devinquiry +.Nd Bluetooth device access routines +.Sh LIBRARY +.Lb libbluetooth +.Sh SYNOPSIS +.In bluetooth.h +.Ft int +.Fn bt_devaddr "const char *name" "bdaddr_t *bdaddr" +.Ft int +.Fn bt_devname "char *name" "const bdaddr_t *bdaddr" +.Ft int +.Fn bt_devenum "int (*cb)(int, const struct bt_devinfo *, void *)" "void *arg" +.Ft int +.Fn bt_devinfo "const char *name" "struct bt_devinfo *info" +.Ft int +.Fn bt_devopen "const char *name" "int flags" +.Ft ssize_t +.Fn bt_devsend "int s" "uint16_t opcode" "void *param" "size_t plen" +.Ft ssize_t +.Fn bt_devrecv "int s" "void *buf" "size_t size" "time_t timeout" +.Ft int +.Fn bt_devreq "int s" "struct bt_devreq *req" "time_t timeout" +.Ft int +.Fn bt_devfilter "int s" "const struct bt_devfilter *new" "struct bt_devfilter *old" +.Ft void +.Fn bt_devfilter_pkt_set "struct bt_devfilter *filter" "uint8_t type" +.Ft void +.Fn bt_devfilter_pkt_clr "struct bt_devfilter *filter" "uint8_t type" +.Ft int +.Fn bt_devfilter_pkt_tst "const struct bt_devfilter *filter" "uint8_t type" +.Ft void +.Fn bt_devfilter_evt_set "struct bt_devfilter *filter" "uint8_t event" +.Ft void +.Fn bt_devfilter_evt_clr "struct bt_devfilter *filter" "uint8_t event" +.Ft int +.Fn bt_devfilter_evt_tst "const struct bt_devfilter *filter" "uint8_t event" +.Ft int +.Fn bt_devinquiry "const char *name" "time_t timeout" "int max_rsp" "struct bt_devinquiry **iip" +.Sh DESCRIPTION +These routines are designed to provide access to locally configured Bluetooth +devices in an operating system independent manner via a socket providing access +to Bluetooth HCI packets. +.Sh FUNCTIONS +.Bl -tag -width 4n +.It Fn bt_devaddr "name" "bdaddr" +Return a Bluetooth device address. +.Fn bt_devaddr +will return 1 if the NUL-terminated +.Fa name +string refers to a Bluetooth device present in the system, otherwise 0. +The name may be given as a device name +.Pq eg Qo ubt0 Qc +or Bluetooth device address +.Pq eg Qo 00:11:22:33:44:55 Qc +and the actual device address will be written to +.Fa bdaddr +if not +.Dv NULL . +.It Fn bt_devname "name" "bdaddr" +Return a Bluetooth device name. +.Fn bt_devname +returns 1 if the +.Fa bdaddr +refers to a Bluetooth device present in the system, otherwise 0. +The +.Fa name +buffer, if given, should have space for at least +.Dv HCI_DEVNAME_SIZE +bytes and the string will be NUL-terminated. +.It Fn bt_devenum "cb" "arg" +Enumerate Bluetooth devices present in the system. +For each device found, the +.Fa cb +function +.Pq if not Dv NULL +will be called with the +.Fa arg +argument provided, a fully populated +.Ft bt_devinfo +structure and, where the device is enabled, a socket handle as returned by +.Fn bt_devopen . +The callback function can halt the enumeration by returning a +non-zero value, and +.Fn bt_devenum +returns the number of successfully enumerated devices. +.It Fn bt_devinfo "name" "info" +Obtain information from a Bluetooth device present in the system. +The +.Fa info +argument is a pointer to a +.Ft bt_devinfo +structure into which information about device +.Fa name +is placed. +The +.Ft bt_devinfo +structure contains at least the following members: +.Bd -literal + char devname[HCI_DEVNAME_SIZE]; + int enabled; /* device is enabled */ + + /* device information */ + bdaddr_t bdaddr; + uint8_t features[HCI_FEATURES_SIZE]; + uint16_t acl_size; /* max ACL data size */ + uint16_t acl_pkts; /* total ACL packet buffers */ + uint16_t sco_size; /* max SCO data size */ + uint16_t sco_pkts; /* total SCO packet buffers */ + + /* flow control */ + uint16_t cmd_free; /* available CMD packet buffers */ + uint16_t acl_free; /* available ACL packet buffers */ + uint16_t sco_free; /* available SCO packet buffers */ + + /* statistics */ + uint32_t cmd_sent; + uint32_t evnt_recv; + uint32_t acl_recv; + uint32_t acl_sent; + uint32_t sco_recv; + uint32_t sco_sent; + uint32_t bytes_recv; + uint32_t bytes_sent; + + /* device settings */ + uint16_t link_policy_info; + uint16_t packet_type_info; + uint16_t role_switch_info; +.Ed +.Lp +Because a Bluetooth device must be enabled in order to retrieve +information, the +.Fa enabled +flag should be tested to be non-zero before relying on further data. +.It Fn bt_devopen "name" "flags" +Return a Bluetooth HCI socket handle bound and connected to the +named Bluetooth device or, if +.Fa name +is +.Dv NULL , +enabled to receive packets from any device. +The socket should be closed using +.Xr close 2 +after use. +Any combination of the following +.Fa flags +may be used to pre-set the socket options: +.Bl -tag -width ".Dv BTOPT_DIRECTION" +.It Dv BTOPT_DIRECTION +Enable control messages on each packet indicating the direction of travel. +.It Dv BTOPT_TIMESTAMP +Enable control messages providing packet timestamps. +.El +.Lp +The default filter on the socket will only allow the HCI Event packets +.Qq Command Status +and +.Qq Command Complete +to be received. +.It Fn bt_devsend "s" "opcode" "param" "plen" +Send an HCI command packet on the socket +.Fa s . +The +.Fa opcode +should be in host byte order and the +.Fa param +and +.Fa plen +arguments can be used to provide command parameter data. +.Fn bt_devsend +will return the number of bytes successfully written. +.It Fn bt_devrecv "s" "buf" "size" "timeout" +Receive a single HCI packet on the socket +.Fa s . +.Fn bt_devrecv +will return the number of bytes successfully received unless the +provided buffer could not contain the entire packet, or if a timeout was +requested with a non-negative +.Fa timeout +value. +.It Fn bt_devreq "s" "req" "timeout" +Make an HCI request on the socket +.Fa s . +The +.Fa req +argument is a pointer to a +.Ft bt_devreq +structure, defined as: +.Bd -literal -offset indent +struct bt_devreq { + uint16_t opcode; + uint8_t event; + void *cparam; + size_t clen; + void *rparam; + size_t rlen; +}; +.Ed +.Lp +.Fn bt_devreq +sends an HCI command packet with the given +.Fa opcode +and command parameters of +.Fa clen +bytes at +.Fa cparam +then waits up to +.Fa timeout +seconds for the command to return a +.Qq Command Complete +event. +In the case where the command returns +.Qq Command Status +and an additional event, and where the status indicates +that the command is in progress, +.Fn bt_devreq +will wait for the additional +.Fa event +specified in the request. +If required, any response will be copied into the buffer of +.Fa rlen +bytes at +.Fa rparam , +and +.Fa rlen +will be adjusted to indicate the number of bytes stored. +.Fn bt_devreq +temporarily modifies the socket filter. +.It Fn bt_devfilter "s" "new" "old" +Update or extract the packet filter on HCI socket +.Fa s . +Filters can be set to indicate packet types +.Pq Commands, Events, ACL and SCO data , +and individual event IDs. +Where +.Fa old +is given, the currently set filter will be extracted first, then if +.Fa new +is given, the filter will be updated. +.It Fn bt_devfilter_pkt_set "filter" "type" +Set packet +.Fa type +in +.Fa filter . +.It Fn bt_devfilter_pkt_clr "filter" "type" +Clear packet +.Fa type +from +.Fa filter . +.It Fn bt_devfilter_pkt_tst "filter" "type" +Test if +.Fa filter +has packet +.Fa type +set. +.It Fn bt_devfilter_evt_set "filter" "event" +Set +.Fa event +ID in +.Fa filter . +.It Fn bt_devfilter_evt_clr "filter" "event" +Clear +.Fa event +ID from +.Fa filter . +.It Fn bt_devfilter_evt_tst "filter" "event" +Test if +.Fa filter +has +.Fa event +ID set. +.It Fn bt_devinquiry "name" "timeout" "max_rsp" "iip" +Perform a Bluetooth Inquiry using the device +.Fa name , +or the first available device if +.Dv NULL +is passed. +The inquiry length will be +.Fa timeout +seconds, and the number of responses +.Pq up to a limit of Fa max_rsp +will be returned. +A pointer to an array of +.Ft bt_devinquiry +structures, defined as: +.Bd -literal -offset indent +struct bt_devinquiry { + bdaddr_t bdaddr; + uint8_t pscan_rep_mode; + uint8_t pscan_period_mode; + uint8_t dev_class[3]; + uint16_t clock_offset; + int8_t rssi; + uint8_t data[240]; +}; +.Ed +.Lp +will be stored in the location given by +.Fa iip +and this should be released after use with +.Xr free 3 . +.El +.Sh RETURN VALUES +These Bluetooth device access routines return \-1 on failure, and +.Va errno +will be set to indicate the error. +.Sh ERRORS +In addition to errors returned by the standard C library IO functions, +the following errors may be indicated by device access routines. +.Bl -tag -offset indent -width ".Bq Er ETIMEDOUT" +.It Bq Er EINVAL +A provided function argument was not valid. +.It Bq Er EIO +A device response was not properly understood. +.It Bq Er ETIMEDOUT +An operation exceeded the given time limit. +.El +.Sh SEE ALSO +.Xr bluetooth 3 +.Sh HISTORY +The Bluetooth device access API was created by +.An Maksim Yevmenkin +and first appeared in +.Fx . +This implementation written for +.Nx +by +.An Iain Hibbert . diff --git a/static/netbsd/man3/btowc.3 b/static/netbsd/man3/btowc.3 new file mode 100644 index 00000000..003531d5 --- /dev/null +++ b/static/netbsd/man3/btowc.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: btowc.3,v 1.4 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 3, 2003 +.Dt BTOWC 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm btowc +.Nd convert a single byte character to a wide character +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft wint_t +.Fn btowc "int c" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn btowc +function converts a single byte character +.Fa c +in the initial shift state of the current locale to a corresponding +wide character. +.Pp +The behaviour of +.Fn btowc +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn btowc +function returns: +.Bl -tag -width 012345678901 +.It Dv WEOF +If +.Fa c +is +.Dv EOF +or if (unsigned char) +.Fa c +does not correspond to a valid single byte character representation. +.It (otherwise) +A wide character corresponding to +.Fa c . +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbrtowc 3 , +.Xr setlocale 3 , +.Xr wctob 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn btowc +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/btree.3 b/static/netbsd/man3/btree.3 new file mode 100644 index 00000000..c226251c --- /dev/null +++ b/static/netbsd/man3/btree.3 @@ -0,0 +1,254 @@ +.\" $NetBSD: btree.3,v 1.13 2012/10/13 15:28:33 njoly Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" +.Dd April 17, 2003 +.Dt BTREE 3 +.Os +.Sh NAME +.Nm btree +.Nd btree database access method +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is btree files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the btree specific information. +.Pp +The btree data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.Pp +The btree access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal +typedef struct { + u_long flags; + u_int cachesize; + int maxkeypage; + int minkeypage; + u_int psize; + int (*compare)(const DBT *key1, const DBT *key2); + size_t (*prefix)(const DBT *key1, const DBT *key2); + int lorder; +} BTREEINFO; +.Ed +.Pp +The elements of this structure are as follows: +.Bl -tag -width maxkeypagex +.It Fa flags +The flag value is specified by or'ing any of the following values: +.Bl -tag -width R_DUP -offset indent +.It Dv R_DUP +Permit duplicate keys in the tree, i.e. permit insertion if the key to +be inserted already exists in the tree. +The default behavior, as described in +.Xr dbopen 3 , +is to overwrite a matching key when inserting a new key or to fail if +the +.Dv R_NOOVERWRITE +flag is specified. +The +.Dv R_DUP +flag is overridden by the +.Dv R_NOOVERWRITE +flag, and if the +.Dv R_NOOVERWRITE +flag is specified, attempts to insert duplicate keys into the tree +will fail. +.Pp +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.Em get +routine is used, however, +.Em seq +routine calls with the +.Dv R_CURSOR +flag set will always return the logical +.Dq first +of any group of duplicate keys. +.El +.It Fa cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather than +fail. +Since every search examines the root page of the tree, caching the +most recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a +moderate cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood +of corruption or lost data if the system crashes while a tree is being +modified. +If +.Fa cachesize +is 0 (no size is specified) a default cache is used. +.It Fa maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the btree data structure works, +.\" .Fa maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .Fa maxkeypage +.\" is 0 (no maximum number of keys is specified) the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.It Fa minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, i.e., if a key or data item is longer than the pagesize divided +by the +.Fa minkeypage +value, it will be stored on overflow pages instead of in the page +itself. +If +.Fa minkeypage +is 0 (no minimum number of keys is specified) a value of 2 is used. +.It Fa psize +Page size is the size (in bytes) of the pages used for nodes in the +tree. +The minimum page size is 512 bytes and the maximum page size is 64K. +If +.Fa psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +.It Fa compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if +the first key argument is considered to be respectively less than, +equal to, or greater than the second key argument. +The same comparison function must be used on a given tree every time +it is opened. +If +.Fa compare +is +.Dv NULL +(no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.It Fa prefix +Prefix is the prefix comparison function. +If specified, this routine must return the number of bytes of the +second key argument which are necessary to determine that it is +greater than the first key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data dependent, but, in +some data sets can produce significantly reduced tree sizes and search +times. +If +.Fa prefix +is +.Dv NULL +(no prefix function is specified), +.Em and +no comparison function is specified, a default lexical comparison +routine is used. +If +.Fa prefix +is +.Dv NULL +and a comparison routine is specified, no prefix comparison is done. +.It Fa lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Fa lorder +is 0 (no order is specified) the current host order is used. +.El +.Pp +If the file already exists (and the +.Dv O_TRUNC +flag is not specified), the values specified for the parameters flags, +lorder and psize are ignored in favor of the values used when the tree +was created. +.Pp +Forward sequential scans of a tree are from the least key to the +greatest. +.Pp +Space freed up by deleting key/data pairs from the tree is never +reclaimed, although it is normally made available for reuse. +This means that the btree storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a +fresh tree periodically from a scan of an existing one. +.Pp +Searches, insertions, and deletions in a btree will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into btrees results in a low fill +factor. +This implementation has been modified to make ordered insertion the +best case, resulting in a much better than normal page fill factor. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr dbopen 3 , +.Xr hash 3 , +.Xr mpool 3 , +.Xr recno 3 +.Rs +.%T "The Ubiquitous B-tree" +.%A "Douglas Comer" +.%J "ACM Comput. Surv." +.%V 2 +.%N 11 +.%D June 1979 +.%P 121-138 +.Re +.Rs +.%T "Prefix B-trees" +.%A "Bayer" +.%A "Unterauer" +.%J "ACM Transactions on Database Systems" +.%V Vol. 2 +.%N 1 +.%D March 1977 +.%P 11-26 +.Re +.Rs +.%B "The Art of Computer Programming Vol. 3: Sorting and Searching" +.%A "D.E. Knuth" +.%D 1968 +.%P 471-480 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/static/netbsd/man3/buffer.h.3 b/static/netbsd/man3/buffer.h.3 new file mode 100644 index 00000000..411419ca --- /dev/null +++ b/static/netbsd/man3/buffer.h.3 @@ -0,0 +1,1361 @@ +.TH "event2/buffer.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/buffer.h \- Functions for buffering data for network sending or receiving\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBevbuffer\fP" +.br +.RI "\fIAn evbuffer is an opaque data type for efficiently buffering data to be sent or received on the network\&. \fP" +.ti -1c +.RI "struct \fBevbuffer_cb_info\fP" +.br +.RI "\fIStructure passed to an evbuffer_cb_func evbuffer callback\&. \fP" +.ti -1c +.RI "struct \fBevbuffer_iovec\fP" +.br +.RI "\fIDescribes a single extent of memory inside an evbuffer\&. \fP" +.ti -1c +.RI "struct \fBevbuffer_ptr\fP" +.br +.RI "\fIPointer to a position within an evbuffer\&. \fP" +.in -1c +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVBUF_FS_CLOSE_ON_FREE\fP 0x01" +.br +.RI "\fIFlag for creating evbuffer_file_segment: If this flag is set, then when the evbuffer_file_segment is freed and no longer in use by any evbuffer, the underlying fd is closed\&. \fP" +.ti -1c +.RI "#define \fBEVBUF_FS_DISABLE_LOCKING\fP 0x08" +.br +.RI "\fIFlag for creating evbuffer_file_segment: Do not allocate a lock for this segment\&. \fP" +.ti -1c +.RI "#define \fBEVBUF_FS_DISABLE_MMAP\fP 0x02" +.br +.RI "\fIFlag for creating evbuffer_file_segment: Disable memory-map based implementations\&. \fP" +.ti -1c +.RI "#define \fBEVBUF_FS_DISABLE_SENDFILE\fP 0x04" +.br +.RI "\fIFlag for creating evbuffer_file_segment: Disable direct fd-to-fd implementations (including sendfile and splice)\&. \fP" +.ti -1c +.RI "#define \fBEVBUFFER_CB_ENABLED\fP 1" +.br +.RI "\fIIf this flag is not set, then a callback is temporarily disabled, and should not be invoked\&. \fP" +.ti -1c +.RI "#define \fBEVBUFFER_FLAG_DRAINS_TO_FD\fP 1" +.br +.RI "\fIIf this flag is set, then we will not use \fBevbuffer_peek()\fP, \fBevbuffer_remove()\fP, \fBevbuffer_remove_buffer()\fP, and so on to read bytes from this buffer: we'll only take bytes out of this buffer by writing them to the network (as with evbuffer_write_atmost), by removing them without observing them (as with evbuffer_drain), or by copying them all out at once (as with evbuffer_add_buffer)\&. \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void(* \fBevbuffer_cb_func\fP) (struct \fBevbuffer\fP *buffer, const struct \fBevbuffer_cb_info\fP *info, void *arg)" +.br +.RI "\fIType definition for a callback that is invoked whenever data is added or removed from an evbuffer\&. \fP" +.ti -1c +.RI "typedef void(* \fBevbuffer_file_segment_cleanup_cb\fP) (struct evbuffer_file_segment const *seg, int flags, void *arg)" +.br +.RI "\fIA cleanup function for a evbuffer_file_segment added to an evbuffer for reference\&. \fP" +.ti -1c +.RI "typedef void(* \fBevbuffer_ref_cleanup_cb\fP) (const void *data, size_t datalen, void *extra)" +.br +.RI "\fIA cleanup function for a piece of memory added to an evbuffer by reference\&. \fP" +.in -1c +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBevbuffer_eol_style\fP { \fBEVBUFFER_EOL_ANY\fP, \fBEVBUFFER_EOL_CRLF\fP, \fBEVBUFFER_EOL_CRLF_STRICT\fP, \fBEVBUFFER_EOL_LF\fP, \fBEVBUFFER_EOL_NUL\fP } +.RI "\fIUsed to tell evbuffer_readln what kind of line-ending to look for\&. \fP"" +.br +.ti -1c +.RI "enum \fBevbuffer_ptr_how\fP { \fBEVBUFFER_PTR_SET\fP, \fBEVBUFFER_PTR_ADD\fP } +.RI "\fIDefines how to adjust an \fBevbuffer_ptr\fP by \fBevbuffer_ptr_set()\fP \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add\fP (struct \fBevbuffer\fP *buf, const void *data, size_t datlen)" +.br +.RI "\fIAppend data to the end of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_buffer\fP (struct \fBevbuffer\fP *outbuf, struct \fBevbuffer\fP *inbuf)" +.br +.RI "\fIMove all data from one evbuffer into another evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_buffer_reference\fP (struct \fBevbuffer\fP *outbuf, struct \fBevbuffer\fP *inbuf)" +.br +.RI "\fICopy data from one evbuffer into another evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evbuffer_cb_entry * \fBevbuffer_add_cb\fP (struct \fBevbuffer\fP *buffer, \fBevbuffer_cb_func\fP cb, void *cbarg)" +.br +.RI "\fIAdd a new callback to an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_file\fP (struct \fBevbuffer\fP *outbuf, int fd, ev_off_t offset, ev_off_t length)" +.br +.RI "\fICopy data from a file into the evbuffer for writing to a socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_file_segment\fP (struct \fBevbuffer\fP *buf, struct evbuffer_file_segment *seg, ev_off_t offset, ev_off_t length)" +.br +.RI "\fIInsert some or all of an evbuffer_file_segment at the end of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL size_t \fBevbuffer_add_iovec\fP (struct \fBevbuffer\fP *buffer, struct \fBevbuffer_iovec\fP *vec, int n_vec)" +.br +.RI "\fIAppend data from 1 or more iovec's to an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_printf\fP (struct \fBevbuffer\fP *buf, const char *fmt,\&.\&.\&.)" +.br +.RI "\fIAppend a formatted string to the end of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_reference\fP (struct \fBevbuffer\fP *outbuf, const void *data, size_t datlen, \fBevbuffer_ref_cleanup_cb\fP cleanupfn, void *cleanupfn_arg)" +.br +.RI "\fIReference memory into an evbuffer without copying\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_add_vprintf\fP (struct \fBevbuffer\fP *buf, const char *fmt, va_list ap)" +.br +.RI "\fIAppend a va_list formatted string to the end of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_cb_clear_flags\fP (struct \fBevbuffer\fP *buffer, struct evbuffer_cb_entry *cb, ev_uint32_t flags)" +.br +.RI "\fIChange the flags that are set for a callback on a buffer by removing some\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_cb_set_flags\fP (struct \fBevbuffer\fP *buffer, struct evbuffer_cb_entry *cb, ev_uint32_t flags)" +.br +.RI "\fIChange the flags that are set for a callback on a buffer by adding more\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_clear_flags\fP (struct \fBevbuffer\fP *buf, ev_uint64_t flags)" +.br +.RI "\fIChange the flags that are set for an evbuffer by removing some\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_commit_space\fP (struct \fBevbuffer\fP *buf, struct \fBevbuffer_iovec\fP *vec, int n_vecs)" +.br +.RI "\fICommits previously reserved space\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBevbuffer_copyout\fP (struct \fBevbuffer\fP *buf, void *data_out, size_t datlen)" +.br +.RI "\fIRead data from an evbuffer, and leave the buffer unchanged\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBevbuffer_copyout_from\fP (struct \fBevbuffer\fP *buf, const struct \fBevbuffer_ptr\fP *pos, void *data_out, size_t datlen)" +.br +.RI "\fIRead data from the middle of an evbuffer, and leave the buffer unchanged\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_defer_callbacks\fP (struct \fBevbuffer\fP *buffer, struct \fBevent_base\fP *base)" +.br +.RI "\fIForce all the callbacks on an evbuffer to be run, not immediately after the evbuffer is altered, but instead from inside the event loop\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_drain\fP (struct \fBevbuffer\fP *buf, size_t len)" +.br +.RI "\fIRemove a specified number of bytes data from the beginning of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_enable_locking\fP (struct \fBevbuffer\fP *buf, void *lock)" +.br +.RI "\fIEnable locking on an evbuffer so that it can safely be used by multiple threads at the same time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_expand\fP (struct \fBevbuffer\fP *buf, size_t datlen)" +.br +.RI "\fIExpands the available space in an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_file_segment_add_cleanup_cb\fP (struct evbuffer_file_segment *seg, \fBevbuffer_file_segment_cleanup_cb\fP cb, void *arg)" +.br +.RI "\fIAdd cleanup callback and argument for the callback to an evbuffer_file_segment\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_file_segment_free\fP (struct evbuffer_file_segment *seg)" +.br +.RI "\fIFree an evbuffer_file_segment\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evbuffer_file_segment * \fBevbuffer_file_segment_new\fP (int fd, ev_off_t offset, ev_off_t length, unsigned flags)" +.br +.RI "\fICreate and return a new evbuffer_file_segment for reading data from a file and sending it out via an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_free\fP (struct \fBevbuffer\fP *buf)" +.br +.RI "\fIDeallocate storage for an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_freeze\fP (struct \fBevbuffer\fP *buf, int at_front)" +.br +.RI "\fIPrevent calls that modify an evbuffer from succeeding\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL size_t \fBevbuffer_get_contiguous_space\fP (const struct \fBevbuffer\fP *buf)" +.br +.RI "\fIReturns the number of contiguous available bytes in the first buffer chain\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL size_t \fBevbuffer_get_length\fP (const struct \fBevbuffer\fP *buf)" +.br +.RI "\fIReturns the total number of bytes stored in the evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_lock\fP (struct \fBevbuffer\fP *buf)" +.br +.RI "\fIAcquire the lock on an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP * \fBevbuffer_new\fP (void)" +.br +.RI "\fIAllocate storage for a new evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_peek\fP (struct \fBevbuffer\fP *buffer, ev_ssize_t len, struct \fBevbuffer_ptr\fP *start_at, struct \fBevbuffer_iovec\fP *vec_out, int n_vec)" +.br +.RI "\fIFunction to peek at data inside an evbuffer without removing it or copying it out\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_prepend\fP (struct \fBevbuffer\fP *buf, const void *data, size_t size)" +.br +.RI "\fIPrepends data to the beginning of the evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_prepend_buffer\fP (struct \fBevbuffer\fP *dst, struct \fBevbuffer\fP *src)" +.br +.RI "\fIPrepends all data from the src evbuffer to the beginning of the dst evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_ptr_set\fP (struct \fBevbuffer\fP *buffer, struct \fBevbuffer_ptr\fP *ptr, size_t position, enum \fBevbuffer_ptr_how\fP how)" +.br +.RI "\fISets the search pointer in the buffer to position\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL unsigned char * \fBevbuffer_pullup\fP (struct \fBevbuffer\fP *buf, ev_ssize_t size)" +.br +.RI "\fIMakes the data at the beginning of an evbuffer contiguous\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_read\fP (struct \fBevbuffer\fP *buffer, \fBevutil_socket_t\fP fd, int howmuch)" +.br +.RI "\fIRead from a file descriptor and store the result in an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevbuffer_readln\fP (struct \fBevbuffer\fP *buffer, size_t *n_read_out, enum \fBevbuffer_eol_style\fP eol_style)" +.br +.RI "\fIRead a single line from an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_remove\fP (struct \fBevbuffer\fP *buf, void *data, size_t datlen)" +.br +.RI "\fIRead data from an evbuffer and drain the bytes read\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_remove_buffer\fP (struct \fBevbuffer\fP *src, struct \fBevbuffer\fP *dst, size_t datlen)" +.br +.RI "\fIRead data from an evbuffer into another evbuffer, draining the bytes from the source buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_remove_cb\fP (struct \fBevbuffer\fP *buffer, \fBevbuffer_cb_func\fP cb, void *cbarg)" +.br +.RI "\fIRemove a callback from an evbuffer, given the function and argument used to add it\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_remove_cb_entry\fP (struct \fBevbuffer\fP *buffer, struct evbuffer_cb_entry *ent)" +.br +.RI "\fIRemove a callback from an evbuffer, given a handle returned from evbuffer_add_cb\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_reserve_space\fP (struct \fBevbuffer\fP *buf, ev_ssize_t size, struct \fBevbuffer_iovec\fP *vec, int n_vec)" +.br +.RI "\fIReserves space in the last chain or chains of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP \fBevbuffer_search\fP (struct \fBevbuffer\fP *buffer, const char *what, size_t len, const struct \fBevbuffer_ptr\fP *start)" +.br +.RI "\fISearch for a string within an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP \fBevbuffer_search_eol\fP (struct \fBevbuffer\fP *buffer, struct \fBevbuffer_ptr\fP *start, size_t *eol_len_out, enum \fBevbuffer_eol_style\fP eol_style)" +.br +.RI "\fISearch for an end-of-line string within an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP \fBevbuffer_search_range\fP (struct \fBevbuffer\fP *buffer, const char *what, size_t len, const struct \fBevbuffer_ptr\fP *start, const struct \fBevbuffer_ptr\fP *end)" +.br +.RI "\fISearch for a string within part of an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_set_flags\fP (struct \fBevbuffer\fP *buf, ev_uint64_t flags)" +.br +.RI "\fIChange the flags that are set for an evbuffer by adding more\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_unfreeze\fP (struct \fBevbuffer\fP *buf, int at_front)" +.br +.RI "\fIRe-enable calls that modify an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_unlock\fP (struct \fBevbuffer\fP *buf)" +.br +.RI "\fIRelease the lock on an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_write\fP (struct \fBevbuffer\fP *buffer, \fBevutil_socket_t\fP fd)" +.br +.RI "\fIWrite the contents of an evbuffer to a file descriptor\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevbuffer_write_atmost\fP (struct \fBevbuffer\fP *buffer, \fBevutil_socket_t\fP fd, ev_ssize_t howmuch)" +.br +.RI "\fIWrite some of the contents of an evbuffer to a file descriptor\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Functions for buffering data for network sending or receiving\&. + +An evbuffer can be used for preparing data before sending it to the network or conversely for reading data from the network\&. Evbuffers try to avoid memory copies as much as possible\&. As a result, evbuffers can be used to pass data around without actually incurring the overhead of copying the data\&. +.PP +A new evbuffer can be allocated with \fBevbuffer_new()\fP, and can be freed with \fBevbuffer_free()\fP\&. Most users will be using evbuffers via the bufferevent interface\&. To access a bufferevent's evbuffers, use \fBbufferevent_get_input()\fP and \fBbufferevent_get_output()\fP\&. +.PP +There are several guidelines for using evbuffers\&. +.PP +.IP "\(bu" 2 +if you already know how much data you are going to add as a result of calling \fBevbuffer_add()\fP multiple times, it makes sense to use \fBevbuffer_expand()\fP first to make sure that enough memory is allocated before hand\&. +.IP "\(bu" 2 +\fBevbuffer_add_buffer()\fP adds the contents of one buffer to the other without incurring any unnecessary memory copies\&. +.IP "\(bu" 2 +\fBevbuffer_add()\fP and \fBevbuffer_add_buffer()\fP do not mix very well: if you use them, you will wind up with fragmented memory in your buffer\&. +.IP "\(bu" 2 +For high-performance code, you may want to avoid copying data into and out of buffers\&. You can skip the copy step by using \fBevbuffer_reserve_space()\fP/evbuffer_commit_space() when writing into a buffer, and \fBevbuffer_peek()\fP when reading\&. +.PP +.PP +In Libevent 2\&.0 and later, evbuffers are represented using a linked list of memory chunks, with pointers to the first and last chunk in the chain\&. +.PP +As the contents of an evbuffer can be stored in multiple different memory blocks, it cannot be accessed directly\&. Instead, \fBevbuffer_pullup()\fP can be used to force a specified number of bytes to be contiguous\&. This will cause memory reallocation and memory copies if the data is split across multiple blocks\&. It is more efficient, however, to use \fBevbuffer_peek()\fP if you don't require that the memory to be contiguous\&. +.SH "Macro Definition Documentation" +.PP +.SS "#define EVBUF_FS_DISABLE_LOCKING 0x08" + +.PP +Flag for creating evbuffer_file_segment: Do not allocate a lock for this segment\&. If this option is set, then neither the segment nor any evbuffer it is added to may ever be accessed from more than one thread at a time\&. +.SS "#define EVBUF_FS_DISABLE_SENDFILE 0x04" + +.PP +Flag for creating evbuffer_file_segment: Disable direct fd-to-fd implementations (including sendfile and splice)\&. You might want to use this option if data needs to be taken from the evbuffer by any means other than writing it to the network: the sendfile backend is fast, but it only works for sending files directly to the network\&. +.SS "#define EVBUFFER_CB_ENABLED 1" + +.PP +If this flag is not set, then a callback is temporarily disabled, and should not be invoked\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_cb_set_flags()\fP, \fBevbuffer_cb_clear_flags()\fP +.RE +.PP + +.SS "#define EVBUFFER_FLAG_DRAINS_TO_FD 1" + +.PP +If this flag is set, then we will not use \fBevbuffer_peek()\fP, \fBevbuffer_remove()\fP, \fBevbuffer_remove_buffer()\fP, and so on to read bytes from this buffer: we'll only take bytes out of this buffer by writing them to the network (as with evbuffer_write_atmost), by removing them without observing them (as with evbuffer_drain), or by copying them all out at once (as with evbuffer_add_buffer)\&. Using this option allows the implementation to use sendfile-based operations for \fBevbuffer_add_file()\fP; see that function for more information\&. +.PP +This flag is on by default for bufferevents that can take advantage of it; you should never actually need to set it on a bufferevent's output buffer\&. +.SH "Typedef Documentation" +.PP +.SS "typedef void(* evbuffer_cb_func) (struct \fBevbuffer\fP *buffer, const struct \fBevbuffer_cb_info\fP *info, void *arg)" + +.PP +Type definition for a callback that is invoked whenever data is added or removed from an evbuffer\&. An evbuffer may have one or more callbacks set at a time\&. The order in which they are executed is undefined\&. +.PP +A callback function may add more callbacks, or remove itself from the list of callbacks, or add or remove data from the buffer\&. It may not remove another callback from the list\&. +.PP +If a callback adds or removes data from the buffer or from another buffer, this can cause a recursive invocation of your callback or other callbacks\&. If you ask for an infinite loop, you might just get one: watch out! +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the buffer whose size has changed +.br +\fIinfo\fP a structure describing how the buffer changed\&. +.br +\fIarg\fP a pointer to user data +.RE +.PP + +.SS "typedef void(* evbuffer_ref_cleanup_cb) (const void *data, size_t datalen, void *extra)" + +.PP +A cleanup function for a piece of memory added to an evbuffer by reference\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_add_reference()\fP +.RE +.PP + +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBevbuffer_eol_style\fP" + +.PP +Used to tell evbuffer_readln what kind of line-ending to look for\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVBUFFER_EOL_ANY \fP\fP +Any sequence of CR and LF characters is acceptable as an EOL\&. Note that this style can produce ambiguous results: the sequence 'CRLF' will be treated as a single EOL if it is all in the buffer at once, but if you first read a CR from the network and later read an LF from the network, it will be treated as two EOLs\&. +.TP +\fB\fIEVBUFFER_EOL_CRLF \fP\fP +An EOL is an LF, optionally preceded by a CR\&. This style is most useful for implementing text-based internet protocols\&. +.TP +\fB\fIEVBUFFER_EOL_CRLF_STRICT \fP\fP +An EOL is a CR followed by an LF\&. +.TP +\fB\fIEVBUFFER_EOL_LF \fP\fP +An EOL is a LF\&. +.TP +\fB\fIEVBUFFER_EOL_NUL \fP\fP +An EOL is a NUL character (that is, a single byte with value 0) +.SS "enum \fBevbuffer_ptr_how\fP" + +.PP +Defines how to adjust an \fBevbuffer_ptr\fP by \fBevbuffer_ptr_set()\fP +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_ptr_set()\fP +.RE +.PP + +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVBUFFER_PTR_SET \fP\fP +Sets the pointer to the position; can be called on with an uninitialized \fBevbuffer_ptr\fP\&. +.TP +\fB\fIEVBUFFER_PTR_ADD \fP\fP +Advances the pointer by adding to the current position\&. +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add (struct \fBevbuffer\fP * buf, const void * data, size_t datlen)" + +.PP +Append data to the end of an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be appended to +.br +\fIdata\fP pointer to the beginning of the data buffer +.br +\fIdatlen\fP the number of bytes to be copied from the data buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_buffer (struct \fBevbuffer\fP * outbuf, struct \fBevbuffer\fP * inbuf)" + +.PP +Move all data from one evbuffer into another evbuffer\&. This is a destructive add\&. The data from one buffer moves into the other buffer\&. However, no unnecessary memory copies occur\&. +.PP +\fBParameters:\fP +.RS 4 +\fIoutbuf\fP the output buffer +.br +\fIinbuf\fP the input buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_remove_buffer()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_buffer_reference (struct \fBevbuffer\fP * outbuf, struct \fBevbuffer\fP * inbuf)" + +.PP +Copy data from one evbuffer into another evbuffer\&. This is a non-destructive add\&. The data from one buffer is copied into the other buffer\&. However, no unnecessary memory copies occur\&. +.PP +Note that buffers already containing buffer references can't be added to other buffers\&. +.PP +\fBParameters:\fP +.RS 4 +\fIoutbuf\fP the output buffer +.br +\fIinbuf\fP the input buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evbuffer_cb_entry* evbuffer_add_cb (struct \fBevbuffer\fP * buffer, \fBevbuffer_cb_func\fP cb, void * cbarg)" + +.PP +Add a new callback to an evbuffer\&. Subsequent calls to \fBevbuffer_add_cb()\fP add new callbacks\&. To remove this callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be monitored +.br +\fIcb\fP the callback function to invoke when the evbuffer is modified, or NULL to remove all callbacks\&. +.br +\fIcbarg\fP an argument to be provided to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +a handle to the callback on success, or NULL on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_file (struct \fBevbuffer\fP * outbuf, int fd, ev_off_t offset, ev_off_t length)" + +.PP +Copy data from a file into the evbuffer for writing to a socket\&. This function avoids unnecessary data copies between userland and kernel\&. If sendfile is available and the EVBUFFER_FLAG_DRAINS_TO_FD flag is set, it uses those functions\&. Otherwise, it tries to use mmap (or CreateFileMapping on Windows)\&. +.PP +The function owns the resulting file descriptor and will close it when finished transferring data\&. +.PP +The results of using \fBevbuffer_remove()\fP or \fBevbuffer_pullup()\fP on evbuffers whose data was added using this function are undefined\&. +.PP +For more fine-grained control, use evbuffer_add_file_segment\&. +.PP +\fBParameters:\fP +.RS 4 +\fIoutbuf\fP the output buffer +.br +\fIfd\fP the file descriptor +.br +\fIoffset\fP the offset from which to read data +.br +\fIlength\fP how much data to read, or -1 to read as much as possible\&. (-1 requires that 'fd' support fstat\&.) +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_file_segment (struct \fBevbuffer\fP * buf, struct evbuffer_file_segment * seg, ev_off_t offset, ev_off_t length)" + +.PP +Insert some or all of an evbuffer_file_segment at the end of an evbuffer\&. Note that the offset and length parameters of this function have a different meaning from those provided to evbuffer_file_segment_new: When you create the segment, the offset is the offset \fIwithin the file\fP, and the length is the length \fIof the segment\fP, whereas when you add a segment to an evbuffer, the offset is \fIwithin the segment\fP and the length is the length of the _part of the segment you want to use\&. +.PP +In other words, if you have a 10 KiB file, and you create an evbuffer_file_segment for it with offset 20 and length 1000, it will refer to bytes 20\&.\&.1019 inclusive\&. If you then pass this segment to evbuffer_add_file_segment and specify an offset of 20 and a length of 50, you will be adding bytes 40\&.\&.99 inclusive\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to append to +.br +\fIseg\fP the segment to add +.br +\fIoffset\fP the offset within the segment to start from +.br +\fIlength\fP the amount of data to add, or -1 to add it all\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL size_t evbuffer_add_iovec (struct \fBevbuffer\fP * buffer, struct \fBevbuffer_iovec\fP * vec, int n_vec)" + +.PP +Append data from 1 or more iovec's to an evbuffer\&. Calculates the number of bytes needed for an iovec structure and guarantees all data will fit into a single chain\&. Can be used in lieu of functionality which calls \fBevbuffer_add()\fP constantly before being used to increase performance\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the destination buffer +.br +\fIvec\fP the source iovec +.br +\fIn_vec\fP the number of iovec structures\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes successfully written to the output buffer\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_printf (struct \fBevbuffer\fP * buf, const char * fmt, \&.\&.\&.)" + +.PP +Append a formatted string to the end of an evbuffer\&. The string is formated as printf\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer that will be appended to +.br +\fIfmt\fP a format string +.br +\fI\&.\&.\&.\fP arguments that will be passed to printf(3) +.RE +.PP +\fBReturns:\fP +.RS 4 +The number of bytes added if successful, or -1 if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +evutil_printf(), \fBevbuffer_add_vprintf()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_reference (struct \fBevbuffer\fP * outbuf, const void * data, size_t datlen, \fBevbuffer_ref_cleanup_cb\fP cleanupfn, void * cleanupfn_arg)" + +.PP +Reference memory into an evbuffer without copying\&. The memory needs to remain valid until all the added data has been read\&. This function keeps just a reference to the memory without actually incurring the overhead of a copy\&. +.PP +\fBParameters:\fP +.RS 4 +\fIoutbuf\fP the output buffer +.br +\fIdata\fP the memory to reference +.br +\fIdatlen\fP how memory to reference +.br +\fIcleanupfn\fP callback to be invoked when the memory is no longer referenced by this evbuffer\&. +.br +\fIcleanupfn_arg\fP optional argument to the cleanup callback +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_add_vprintf (struct \fBevbuffer\fP * buf, const char * fmt, va_list ap)" + +.PP +Append a va_list formatted string to the end of an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer that will be appended to +.br +\fIfmt\fP a format string +.br +\fIap\fP a varargs va_list argument array that will be passed to vprintf(3) +.RE +.PP +\fBReturns:\fP +.RS 4 +The number of bytes added if successful, or -1 if an error occurred\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_cb_clear_flags (struct \fBevbuffer\fP * buffer, struct evbuffer_cb_entry * cb, ev_uint32_t flags)" + +.PP +Change the flags that are set for a callback on a buffer by removing some\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer that the callback is watching\&. +.br +\fIcb\fP the callback whose status we want to change\&. +.br +\fIflags\fP EVBUFFER_CB_ENABLED to disable the callback\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_cb_set_flags (struct \fBevbuffer\fP * buffer, struct evbuffer_cb_entry * cb, ev_uint32_t flags)" + +.PP +Change the flags that are set for a callback on a buffer by adding more\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer that the callback is watching\&. +.br +\fIcb\fP the callback whose status we want to change\&. +.br +\fIflags\fP EVBUFFER_CB_ENABLED to re-enable the callback\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_clear_flags (struct \fBevbuffer\fP * buf, ev_uint64_t flags)" + +.PP +Change the flags that are set for an evbuffer by removing some\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer that the callback is watching\&. +.br +\fIcb\fP the callback whose status we want to change\&. +.br +\fIflags\fP One or more EVBUFFER_FLAG_* options +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_commit_space (struct \fBevbuffer\fP * buf, struct \fBevbuffer_iovec\fP * vec, int n_vecs)" + +.PP +Commits previously reserved space\&. Commits some of the space previously reserved with \fBevbuffer_reserve_space()\fP\&. It then becomes available for reading\&. +.PP +This function may return an error if the pointer in the extents do not match those returned from evbuffer_reserve_space, or if data has been added to the buffer since the space was reserved\&. +.PP +If you want to commit less data than you got reserved space for, modify the iov_len pointer of the appropriate extent to a smaller value\&. Note that you may have received more space than you requested if it was available! +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer in which to reserve space\&. +.br +\fIvec\fP one or two extents returned by evbuffer_reserve_space\&. +.br +\fIn_vecs\fP the number of extents\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on error +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_reserve_space()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL ev_ssize_t evbuffer_copyout (struct \fBevbuffer\fP * buf, void * data_out, size_t datlen)" + +.PP +Read data from an evbuffer, and leave the buffer unchanged\&. If more bytes are requested than are available in the evbuffer, we only extract as many bytes as were available\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be read from +.br +\fIdata_out\fP the destination buffer to store the result +.br +\fIdatlen\fP the maximum size of the destination buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes read, or -1 if we can't drain the buffer\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL ev_ssize_t evbuffer_copyout_from (struct \fBevbuffer\fP * buf, const struct \fBevbuffer_ptr\fP * pos, void * data_out, size_t datlen)" + +.PP +Read data from the middle of an evbuffer, and leave the buffer unchanged\&. If more bytes are requested than are available in the evbuffer, we only extract as many bytes as were available\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be read from +.br +\fIpos\fP the position to start reading from +.br +\fIdata_out\fP the destination buffer to store the result +.br +\fIdatlen\fP the maximum size of the destination buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes read, or -1 if we can't drain the buffer\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_defer_callbacks (struct \fBevbuffer\fP * buffer, struct \fBevent_base\fP * base)" + +.PP +Force all the callbacks on an evbuffer to be run, not immediately after the evbuffer is altered, but instead from inside the event loop\&. This can be used to serialize all the callbacks to a single thread of execution\&. +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_drain (struct \fBevbuffer\fP * buf, size_t len)" + +.PP +Remove a specified number of bytes data from the beginning of an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be drained +.br +\fIlen\fP the number of bytes to drain from the beginning of the buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_enable_locking (struct \fBevbuffer\fP * buf, void * lock)" + +.PP +Enable locking on an evbuffer so that it can safely be used by multiple threads at the same time\&. NOTE: when locking is enabled, the lock will be held when callbacks are invoked\&. This could result in deadlock if you aren't careful\&. Plan accordingly! +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP An evbuffer to make lockable\&. +.br +\fIlock\fP A lock object, or NULL if we should allocate our own\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_expand (struct \fBevbuffer\fP * buf, size_t datlen)" + +.PP +Expands the available space in an evbuffer\&. Expands the available space in the evbuffer to at least datlen, so that appending datlen additional bytes will not require any new allocations\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be expanded +.br +\fIdatlen\fP the new minimum length requirement +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_file_segment_add_cleanup_cb (struct evbuffer_file_segment * seg, \fBevbuffer_file_segment_cleanup_cb\fP cb, void * arg)" + +.PP +Add cleanup callback and argument for the callback to an evbuffer_file_segment\&. The cleanup callback will be invoked when no more references to the evbuffer_file_segment exist\&. +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_file_segment_free (struct evbuffer_file_segment * seg)" + +.PP +Free an evbuffer_file_segment\&. It is safe to call this function even if the segment has been added to one or more evbuffers\&. The evbuffer_file_segment will not be freed until no more references to it exist\&. +.SS "EVENT2_EXPORT_SYMBOL struct evbuffer_file_segment* evbuffer_file_segment_new (int fd, ev_off_t offset, ev_off_t length, unsigned flags)" + +.PP +Create and return a new evbuffer_file_segment for reading data from a file and sending it out via an evbuffer\&. This function avoids unnecessary data copies between userland and kernel\&. Where available, it uses sendfile or splice\&. +.PP +The file descriptor must not be closed so long as any evbuffer is using this segment\&. +.PP +The results of using \fBevbuffer_remove()\fP or \fBevbuffer_pullup()\fP or any other function that reads bytes from an evbuffer on any evbuffer containing the newly returned segment are undefined, unless you pass the EVBUF_FS_DISABLE_SENDFILE flag to this function\&. +.PP +\fBParameters:\fP +.RS 4 +\fIfd\fP an open file to read from\&. +.br +\fIoffset\fP an index within the file at which to start reading +.br +\fIlength\fP how much data to read, or -1 to read as much as possible\&. (-1 requires that 'fd' support fstat\&.) +.br +\fIflags\fP any number of the EVBUF_FS_* flags +.RE +.PP +\fBReturns:\fP +.RS 4 +a new evbuffer_file_segment, or NULL on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_free (struct \fBevbuffer\fP * buf)" + +.PP +Deallocate storage for an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP pointer to the evbuffer to be freed +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_freeze (struct \fBevbuffer\fP * buf, int at_front)" + +.PP +Prevent calls that modify an evbuffer from succeeding\&. A buffer may frozen at the front, at the back, or at both the front and the back\&. +.PP +If the front of a buffer is frozen, operations that drain data from the front of the buffer, or that prepend data to the buffer, will fail until it is unfrozen\&. If the back a buffer is frozen, operations that append data from the buffer will fail until it is unfrozen\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP The buffer to freeze +.br +\fIat_front\fP If true, we freeze the front of the buffer\&. If false, we freeze the back\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL size_t evbuffer_get_contiguous_space (const struct \fBevbuffer\fP * buf)" + +.PP +Returns the number of contiguous available bytes in the first buffer chain\&. This is useful when processing data that might be split into multiple chains, or that might all be in the first chain\&. Calls to \fBevbuffer_pullup()\fP that cause reallocation and copying of data can thus be avoided\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP pointer to the evbuffer +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if no data is available, otherwise the number of available bytes in the first buffer chain\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL size_t evbuffer_get_length (const struct \fBevbuffer\fP * buf)" + +.PP +Returns the total number of bytes stored in the evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP pointer to the evbuffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes stored in the evbuffer +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_lock (struct \fBevbuffer\fP * buf)" + +.PP +Acquire the lock on an evbuffer\&. Has no effect if locking was not enabled with evbuffer_enable_locking\&. +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP* evbuffer_new (void)" + +.PP +Allocate storage for a new evbuffer\&. +.PP +\fBReturns:\fP +.RS 4 +a pointer to a newly allocated evbuffer struct, or NULL if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_peek (struct \fBevbuffer\fP * buffer, ev_ssize_t len, struct \fBevbuffer_ptr\fP * start_at, struct \fBevbuffer_iovec\fP * vec_out, int n_vec)" + +.PP +Function to peek at data inside an evbuffer without removing it or copying it out\&. Pointers to the data are returned by filling the 'vec_out' array with pointers to one or more extents of data inside the buffer\&. +.PP +The total data in the extents that you get back may be more than you requested (if there is more data last extent than you asked for), or less (if you do not provide enough evbuffer_iovecs, or if the buffer does not have as much data as you asked to see)\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to peek into, +.br +\fIlen\fP the number of bytes to try to peek\&. If len is negative, we will try to fill as much of vec_out as we can\&. If len is negative and vec_out is not provided, we return the number of evbuffer_iovecs that would be needed to get all the data in the buffer\&. +.br +\fIstart_at\fP an \fBevbuffer_ptr\fP indicating the point at which we should start looking for data\&. NULL means, 'At the start of the + buffer\&.' +.br +\fIvec_out\fP an array of \fBevbuffer_iovec\fP +.br +\fIn_vec\fP the length of vec_out\&. If 0, we only count how many extents would be necessary to point to the requested amount of data\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +The number of extents needed\&. This may be less than n_vec if we didn't need all the evbuffer_iovecs we were given, or more than n_vec if we would need more to return all the data that was requested\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_prepend (struct \fBevbuffer\fP * buf, const void * data, size_t size)" + +.PP +Prepends data to the beginning of the evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to which to prepend data +.br +\fIdata\fP a pointer to the memory to prepend +.br +\fIsize\fP the number of bytes to prepend +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 otherwise +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_prepend_buffer (struct \fBevbuffer\fP * dst, struct \fBevbuffer\fP * src)" + +.PP +Prepends all data from the src evbuffer to the beginning of the dst evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIdst\fP the evbuffer to which to prepend data +.br +\fIsrc\fP the evbuffer to prepend; it will be emptied as a result +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 otherwise +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_ptr_set (struct \fBevbuffer\fP * buffer, struct \fBevbuffer_ptr\fP * ptr, size_t position, enum \fBevbuffer_ptr_how\fP how)" + +.PP +Sets the search pointer in the buffer to position\&. There are two ways to use this function: you can call evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_SET) to move 'pos' to a position 'N' bytes after the start of the buffer, or evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_ADD) to move 'pos' forward by 'N' bytes\&. +.PP +If \fBevbuffer_ptr\fP is not initialized, this function can only be called with EVBUFFER_PTR_SET\&. +.PP +An \fBevbuffer_ptr\fP can represent any position from the start of the buffer to a position immediately after the end of the buffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be search +.br +\fIptr\fP a pointer to a struct \fBevbuffer_ptr\fP +.br +\fIposition\fP the position at which to start the next search +.br +\fIhow\fP determines how the pointer should be manipulated\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success or -1 otherwise +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL unsigned char* evbuffer_pullup (struct \fBevbuffer\fP * buf, ev_ssize_t size)" + +.PP +Makes the data at the beginning of an evbuffer contiguous\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to make contiguous +.br +\fIsize\fP the number of bytes to make contiguous, or -1 to make the entire buffer contiguous\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to the contiguous memory array, or NULL if param size requested more data than is present in the buffer\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_read (struct \fBevbuffer\fP * buffer, \fBevutil_socket_t\fP fd, int howmuch)" + +.PP +Read from a file descriptor and store the result in an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to store the result +.br +\fIfd\fP the file descriptor to read from +.br +\fIhowmuch\fP the number of bytes to be read +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes read, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_write()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL char* evbuffer_readln (struct \fBevbuffer\fP * buffer, size_t * n_read_out, enum \fBevbuffer_eol_style\fP eol_style)" + +.PP +Read a single line from an evbuffer\&. Reads a line terminated by an EOL as determined by the evbuffer_eol_style argument\&. Returns a newly allocated nul-terminated string; the caller must free the returned value\&. The EOL is not included in the returned string\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to read from +.br +\fIn_read_out\fP if non-NULL, points to a size_t that is set to the number of characters in the returned string\&. This is useful for strings that can contain NUL characters\&. +.br +\fIeol_style\fP the style of line-ending to use\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +pointer to a single line, or NULL if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_remove (struct \fBevbuffer\fP * buf, void * data, size_t datlen)" + +.PP +Read data from an evbuffer and drain the bytes read\&. If more bytes are requested than are available in the evbuffer, we only extract as many bytes as were available\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer to be read from +.br +\fIdata\fP the destination buffer to store the result +.br +\fIdatlen\fP the maximum size of the destination buffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes read, or -1 if we can't drain the buffer\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_remove_buffer (struct \fBevbuffer\fP * src, struct \fBevbuffer\fP * dst, size_t datlen)" + +.PP +Read data from an evbuffer into another evbuffer, draining the bytes from the source buffer\&. This function avoids copy operations to the extent possible\&. +.PP +If more bytes are requested than are available in src, the src buffer is drained completely\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsrc\fP the evbuffer to be read from +.br +\fIdst\fP the destination evbuffer to store the result into +.br +\fIdatlen\fP the maximum numbers of bytes to transfer +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes read +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_remove_cb (struct \fBevbuffer\fP * buffer, \fBevbuffer_cb_func\fP cb, void * cbarg)" + +.PP +Remove a callback from an evbuffer, given the function and argument used to add it\&. +.PP +\fBReturns:\fP +.RS 4 +0 if a callback was removed, or -1 if no matching callback was found\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_remove_cb_entry (struct \fBevbuffer\fP * buffer, struct evbuffer_cb_entry * ent)" + +.PP +Remove a callback from an evbuffer, given a handle returned from evbuffer_add_cb\&. Calling this function invalidates the handle\&. +.PP +\fBReturns:\fP +.RS 4 +0 if a callback was removed, or -1 if no matching callback was found\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_reserve_space (struct \fBevbuffer\fP * buf, ev_ssize_t size, struct \fBevbuffer_iovec\fP * vec, int n_vec)" + +.PP +Reserves space in the last chain or chains of an evbuffer\&. Makes space available in the last chain or chains of an evbuffer that can be arbitrarily written to by a user\&. The space does not become available for reading until it has been committed with \fBevbuffer_commit_space()\fP\&. +.PP +The space is made available as one or more extents, represented by an initial pointer and a length\&. You can force the memory to be available as only one extent\&. Allowing more extents, however, makes the function more efficient\&. +.PP +Multiple subsequent calls to this function will make the same space available until \fBevbuffer_commit_space()\fP has been called\&. +.PP +It is an error to do anything that moves around the buffer's internal memory structures before committing the space\&. +.PP +NOTE: The code currently does not ever use more than two extents\&. This may change in future versions\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP the evbuffer in which to reserve space\&. +.br +\fIsize\fP how much space to make available, at minimum\&. The total length of the extents may be greater than the requested length\&. +.br +\fIvec\fP an array of one or more \fBevbuffer_iovec\fP structures to hold pointers to the reserved extents of memory\&. +.br +\fIn_vec\fP The length of the vec array\&. Must be at least 1; 2 is more efficient\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of provided extents, or -1 on error\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_commit_space()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP evbuffer_search (struct \fBevbuffer\fP * buffer, const char * what, size_t len, const struct \fBevbuffer_ptr\fP * start)" + +.PP +Search for a string within an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be searched +.br +\fIwhat\fP the string to be searched for +.br +\fIlen\fP the length of the search string +.br +\fIstart\fP NULL or a pointer to a valid struct \fBevbuffer_ptr\fP\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +a struct \fBevbuffer_ptr\fP whose 'pos' field has the offset of the first occurrence of the string in the buffer after 'start'\&. The 'pos' field of the result is -1 if the string was not found\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP evbuffer_search_eol (struct \fBevbuffer\fP * buffer, struct \fBevbuffer_ptr\fP * start, size_t * eol_len_out, enum \fBevbuffer_eol_style\fP eol_style)" + +.PP +Search for an end-of-line string within an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be searched +.br +\fIstart\fP NULL or a pointer to a valid struct \fBevbuffer_ptr\fP to start searching at\&. +.br +\fIeol_len_out\fP If non-NULL, the pointed-to value will be set to the length of the end-of-line string\&. +.br +\fIeol_style\fP The kind of EOL to look for; see \fBevbuffer_readln()\fP for more information +.RE +.PP +\fBReturns:\fP +.RS 4 +a struct \fBevbuffer_ptr\fP whose 'pos' field has the offset of the first occurrence EOL in the buffer after 'start'\&. The 'pos' field of the result is -1 if the string was not found\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer_ptr\fP evbuffer_search_range (struct \fBevbuffer\fP * buffer, const char * what, size_t len, const struct \fBevbuffer_ptr\fP * start, const struct \fBevbuffer_ptr\fP * end)" + +.PP +Search for a string within part of an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be searched +.br +\fIwhat\fP the string to be searched for +.br +\fIlen\fP the length of the search string +.br +\fIstart\fP NULL or a pointer to a valid struct \fBevbuffer_ptr\fP that indicates where we should start searching\&. +.br +\fIend\fP NULL or a pointer to a valid struct \fBevbuffer_ptr\fP that indicates where we should stop searching\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +a struct \fBevbuffer_ptr\fP whose 'pos' field has the offset of the first occurrence of the string in the buffer after 'start'\&. The 'pos' field of the result is -1 if the string was not found\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_set_flags (struct \fBevbuffer\fP * buf, ev_uint64_t flags)" + +.PP +Change the flags that are set for an evbuffer by adding more\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer that the callback is watching\&. +.br +\fIcb\fP the callback whose status we want to change\&. +.br +\fIflags\fP One or more EVBUFFER_FLAG_* options +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_unfreeze (struct \fBevbuffer\fP * buf, int at_front)" + +.PP +Re-enable calls that modify an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuf\fP The buffer to un-freeze +.br +\fIat_front\fP If true, we unfreeze the front of the buffer\&. If false, we unfreeze the back\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_unlock (struct \fBevbuffer\fP * buf)" + +.PP +Release the lock on an evbuffer\&. Has no effect if locking was not enabled with evbuffer_enable_locking\&. +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_write (struct \fBevbuffer\fP * buffer, \fBevutil_socket_t\fP fd)" + +.PP +Write the contents of an evbuffer to a file descriptor\&. The evbuffer will be drained after the bytes have been successfully written\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be written and drained +.br +\fIfd\fP the file descriptor to be written to +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes written, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_read()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evbuffer_write_atmost (struct \fBevbuffer\fP * buffer, \fBevutil_socket_t\fP fd, ev_ssize_t howmuch)" + +.PP +Write some of the contents of an evbuffer to a file descriptor\&. The evbuffer will be drained after the bytes have been successfully written\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be written and drained +.br +\fIfd\fP the file descriptor to be written to +.br +\fIhowmuch\fP the largest allowable number of bytes to write, or -1 to write as many bytes as we can\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes written, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_read()\fP +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/buffer_compat.h.3 b/static/netbsd/man3/buffer_compat.h.3 new file mode 100644 index 00000000..bd07c362 --- /dev/null +++ b/static/netbsd/man3/buffer_compat.h.3 @@ -0,0 +1,144 @@ +.TH "event2/buffer_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/buffer_compat.h \- Obsolete and deprecated versions of the functions in \fBbuffer\&.h\fP: provided only for backward compatibility\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br + +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVBUFFER_DATA\fP(x) \fBevbuffer_pullup\fP((x), \-1)" +.br +.RI "\fIdeprecated in favor of calling the functions directly \fP" +.ti -1c +.RI "#define \fBEVBUFFER_LENGTH\fP(x) \fBevbuffer_get_length\fP(x)" +.br +.RI "\fIdeprecated in favor of calling the functions directly \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void(* \fBevbuffer_cb\fP) (struct \fBevbuffer\fP *buffer, size_t old_len, size_t new_len, void *arg)" +.br +.RI "\fIType definition for a callback that is invoked whenever data is added or removed from an evbuffer\&. \fP" +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL unsigned char * \fBevbuffer_find\fP (struct \fBevbuffer\fP *buffer, const unsigned char *what, size_t len)" +.br +.RI "\fIFind a string within an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevbuffer_readline\fP (struct \fBevbuffer\fP *buffer)" +.br +.RI "\fIObsolete alias for evbuffer_readln(buffer, NULL, EVBUFFER_EOL_ANY)\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevbuffer_setcb\fP (struct \fBevbuffer\fP *buffer, \fBevbuffer_cb\fP cb, void *cbarg)" +.br +.RI "\fIReplace all callbacks on an evbuffer with a single new callback, or remove them\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Obsolete and deprecated versions of the functions in \fBbuffer\&.h\fP: provided only for backward compatibility\&. + + +.SH "Typedef Documentation" +.PP +.SS "typedef void(* evbuffer_cb) (struct \fBevbuffer\fP *buffer, size_t old_len, size_t new_len, void *arg)" + +.PP +Type definition for a callback that is invoked whenever data is added or removed from an evbuffer\&. An evbuffer may have one or more callbacks set at a time\&. The order in which they are executed is undefined\&. +.PP +A callback function may add more callbacks, or remove itself from the list of callbacks, or add or remove data from the buffer\&. It may not remove another callback from the list\&. +.PP +If a callback adds or removes data from the buffer or from another buffer, this can cause a recursive invocation of your callback or other callbacks\&. If you ask for an infinite loop, you might just get one: watch out! +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the buffer whose size has changed +.br +\fIold_len\fP the previous length of the buffer +.br +\fInew_len\fP the current length of the buffer +.br +\fIarg\fP a pointer to user data +.RE +.PP + +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL unsigned char* evbuffer_find (struct \fBevbuffer\fP * buffer, const unsigned char * what, size_t len)" + +.PP +Find a string within an evbuffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be searched +.br +\fIwhat\fP the string to be searched for +.br +\fIlen\fP the length of the search string +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to the beginning of the search string, or NULL if the search failed\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL char* evbuffer_readline (struct \fBevbuffer\fP * buffer)" + +.PP +Obsolete alias for evbuffer_readln(buffer, NULL, EVBUFFER_EOL_ANY)\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because its behavior is not correct for almost any protocol, and also because it's wholly subsumed by \fBevbuffer_readln()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to read from +.RE +.PP +\fBReturns:\fP +.RS 4 +pointer to a single line, or NULL if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evbuffer_setcb (struct \fBevbuffer\fP * buffer, \fBevbuffer_cb\fP cb, void * cbarg)" + +.PP +Replace all callbacks on an evbuffer with a single new callback, or remove them\&. Subsequent calls to \fBevbuffer_setcb()\fP replace callbacks set by previous calls\&. Setting the callback to NULL removes any previously set callback\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it clears all previous callbacks set on the evbuffer, which can cause confusing behavior if multiple parts of the code all want to add their own callbacks on a buffer\&. Instead, use \fBevbuffer_add()\fP, evbuffer_del(), and evbuffer_setflags() to manage your own evbuffer callbacks without interfering with callbacks set by others\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIbuffer\fP the evbuffer to be monitored +.br +\fIcb\fP the callback function to invoke when the evbuffer is modified, or NULL to remove all callbacks\&. +.br +\fIcbarg\fP an argument to be provided to the callback function +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/bufferevent.3 b/static/netbsd/man3/bufferevent.3 new file mode 100644 index 00000000..d63eb4b6 --- /dev/null +++ b/static/netbsd/man3/bufferevent.3 @@ -0,0 +1,27 @@ +.TH "bufferevent" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +bufferevent \- An opaque type for handling buffered IO\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +An opaque type for handling buffered IO\&. + + +.PP +\fBSee also:\fP +.RS 4 +\fBevent2/bufferevent\&.h\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/bufferevent.h.3 b/static/netbsd/man3/bufferevent.h.3 new file mode 100644 index 00000000..26f36d64 --- /dev/null +++ b/static/netbsd/man3/bufferevent.h.3 @@ -0,0 +1,1253 @@ +.TH "event2/bufferevent.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/bufferevent.h \- Functions for buffering data for network sending or receiving\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBbufferevent\fP" +.br +.RI "\fIAn opaque type for handling buffered IO\&. \fP" +.in -1c +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEV_RATE_LIMIT_MAX\fP EV_SSIZE_MAX" +.br +.RI "\fIMaximum configurable rate- or burst-limit\&. \fP" +.in -1c +.PP +.RI "\fBBufferevent event codes\fP" +.br +These flags are passed as arguments to a bufferevent's event callback\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBBEV_EVENT_READING\fP 0x01" +.br +.RI "\fIerror encountered while reading \fP" +.ti -1c +.RI "#define \fBBEV_EVENT_WRITING\fP 0x02" +.br +.RI "\fIerror encountered while writing \fP" +.ti -1c +.RI "#define \fBBEV_EVENT_EOF\fP 0x10" +.br +.RI "\fIeof file reached \fP" +.ti -1c +.RI "#define \fBBEV_EVENT_ERROR\fP 0x20" +.br +.RI "\fIunrecoverable error encountered \fP" +.ti -1c +.RI "#define \fBBEV_EVENT_TIMEOUT\fP 0x40" +.br +.RI "\fIuser-specified timeout reached \fP" +.ti -1c +.RI "#define \fBBEV_EVENT_CONNECTED\fP 0x80" +.br +.RI "\fIconnect operation finished\&. \fP" +.in -1c +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void(* \fBbufferevent_data_cb\fP) (struct \fBbufferevent\fP *bev, void *ctx)" +.br +.RI "\fIA read or write callback for a bufferevent\&. \fP" +.ti -1c +.RI "typedef void(* \fBbufferevent_event_cb\fP) (struct \fBbufferevent\fP *bev, short what, void *ctx)" +.br +.RI "\fIAn event/error callback for a bufferevent\&. \fP" +.in -1c +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBbufferevent_flush_mode\fP { \fBBEV_NORMAL\fP = 0, \fBBEV_FLUSH\fP = 1, \fBBEV_FINISHED\fP = 2 } +.RI "\fIFlags that can be passed into filters to let them know how to deal with the incoming data\&. \fP"" +.br +.ti -1c +.RI "enum \fBbufferevent_options\fP { \fBBEV_OPT_CLOSE_ON_FREE\fP = (1<<0), \fBBEV_OPT_THREADSAFE\fP = (1<<1), \fBBEV_OPT_DEFER_CALLBACKS\fP = (1<<2), \fBBEV_OPT_UNLOCK_CALLBACKS\fP = (1<<3) } +.RI "\fIOptions that can be specified when creating a bufferevent\&. \fP"" +.br +.ti -1c +.RI "enum \fBbufferevent_trigger_options\fP { \fBBEV_TRIG_IGNORE_WATERMARKS\fP = (1<<16), \fBBEV_TRIG_DEFER_CALLBACKS\fP = BEV_OPT_DEFER_CALLBACKS } +.RI "\fIFlags for bufferevent_trigger(_event) that modify when and how to trigger the callback\&. \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_add_to_rate_limit_group\fP (struct \fBbufferevent\fP *bev, struct bufferevent_rate_limit_group *g)" +.br +.RI "\fIAdd 'bev' to the list of bufferevents whose aggregate reading and writing is restricted by 'g'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_base_set\fP (struct \fBevent_base\fP *base, struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIAssign a bufferevent to a specific \fBevent_base\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_decref\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIPublic interface to manually decrement the reference count of a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_disable\fP (struct \fBbufferevent\fP *bufev, short \fBevent\fP)" +.br +.RI "\fIDisable a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_enable\fP (struct \fBbufferevent\fP *bufev, short \fBevent\fP)" +.br +.RI "\fIEnable a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_flush\fP (struct \fBbufferevent\fP *bufev, short iotype, enum \fBbufferevent_flush_mode\fP mode)" +.br +.RI "\fITriggers the bufferevent to produce more data if possible\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_free\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIDeallocate the storage associated with a bufferevent structure\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBbufferevent_get_base\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIReturn the \fBevent_base\fP used by a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL short \fBbufferevent_get_enabled\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturn the events that are enabled on a given bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP * \fBbufferevent_get_input\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturns the input buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_max_single_read\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIGet the current size limit for single read operation\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_max_single_write\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIGet the current size limit for single write operation\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_max_to_read\fP (struct \fBbufferevent\fP *bev)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_max_to_write\fP (struct \fBbufferevent\fP *bev)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP * \fBbufferevent_get_output\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturns the output buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_get_priority\fP (const struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturn the priority of a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const struct ev_token_bucket_cfg * \fBbufferevent_get_token_bucket_cfg\fP (const struct \fBbufferevent\fP *bev)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_get_underlying\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturns the underlying bufferevent associated with a bufferevent (if the bufferevent is a wrapper), or NULL if there is no underlying bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_getcb\fP (struct \fBbufferevent\fP *bufev, \fBbufferevent_data_cb\fP *readcb_ptr, \fBbufferevent_data_cb\fP *writecb_ptr, \fBbufferevent_event_cb\fP *eventcb_ptr, void **cbarg_ptr)" +.br +.RI "\fIRetrieves the callbacks for a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL \fBevutil_socket_t\fP \fBbufferevent_getfd\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturns the file descriptor associated with a bufferevent, or -1 if no file descriptor is associated with the bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_getwatermark\fP (struct \fBbufferevent\fP *bufev, short events, size_t *lowmark, size_t *highmark)" +.br +.RI "\fIRetrieves the watermarks for read or write events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_incref\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIPublic interface to manually increase the reference count of a bufferevent this is useful in situations where a user may reference the bufferevent somewhere eles (unknown to libevent) \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_lock\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIAcquire the lock on a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_pair_get_partner\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIGiven one bufferevent returned by \fBbufferevent_pair_new()\fP, returns the other one if it still exists\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_pair_new\fP (struct \fBevent_base\fP *base, int options, struct \fBbufferevent\fP *pair[2])" +.br +.RI "\fIAllocate a pair of linked bufferevents\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_priority_set\fP (struct \fBbufferevent\fP *bufev, int pri)" +.br +.RI "\fIAssign a priority to a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_rate_limit_group_free\fP (struct bufferevent_rate_limit_group *)" +.br +.RI "\fIFree a rate-limiting group\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_rate_limit_group_get_totals\fP (struct bufferevent_rate_limit_group *grp, ev_uint64_t *total_read_out, ev_uint64_t *total_written_out)" +.br +.RI "\fIInspect the total bytes read/written on a group\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct bufferevent_rate_limit_group * \fBbufferevent_rate_limit_group_new\fP (struct \fBevent_base\fP *base, const struct ev_token_bucket_cfg *cfg)" +.br +.RI "\fICreate a new rate-limit group for bufferevents\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_rate_limit_group_reset_totals\fP (struct bufferevent_rate_limit_group *grp)" +.br +.RI "\fIReset the total bytes read/written on a group\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_rate_limit_group_set_cfg\fP (struct bufferevent_rate_limit_group *, const struct ev_token_bucket_cfg *)" +.br +.RI "\fIChange the rate-limiting settings for a given rate-limiting group\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_rate_limit_group_set_min_share\fP (struct bufferevent_rate_limit_group *, size_t)" +.br +.RI "\fIChange the smallest quantum we're willing to allocate to any single bufferevent in a group for reading or writing at a time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL size_t \fBbufferevent_read\fP (struct \fBbufferevent\fP *bufev, void *data, size_t size)" +.br +.RI "\fIRead data from a bufferevent buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_read_buffer\fP (struct \fBbufferevent\fP *bufev, struct \fBevbuffer\fP *buf)" +.br +.RI "\fIRead data from a bufferevent buffer into an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_remove_from_rate_limit_group\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIRemove 'bev' from its current rate-limit group (if any)\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_set_max_single_read\fP (struct \fBbufferevent\fP *bev, size_t size)" +.br +.RI "\fISet the size limit for single read operation\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_set_max_single_write\fP (struct \fBbufferevent\fP *bev, size_t size)" +.br +.RI "\fISet the size limit for single write operation\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_set_rate_limit\fP (struct \fBbufferevent\fP *bev, struct ev_token_bucket_cfg *cfg)" +.br +.RI "\fISet the rate-limit of a the bufferevent 'bev' to the one specified in 'cfg'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_set_timeouts\fP (struct \fBbufferevent\fP *bufev, const struct timeval *timeout_read, const struct timeval *timeout_write)" +.br +.RI "\fISet the read and write timeout for a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_setcb\fP (struct \fBbufferevent\fP *bufev, \fBbufferevent_data_cb\fP readcb, \fBbufferevent_data_cb\fP writecb, \fBbufferevent_event_cb\fP eventcb, void *cbarg)" +.br +.RI "\fIChanges the callbacks for a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_setfd\fP (struct \fBbufferevent\fP *bufev, \fBevutil_socket_t\fP fd)" +.br +.RI "\fIChanges the file descriptor on which the bufferevent operates\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_setwatermark\fP (struct \fBbufferevent\fP *bufev, short events, size_t lowmark, size_t highmark)" +.br +.RI "\fISets the watermarks for read and write events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_socket_connect\fP (struct \fBbufferevent\fP *, const struct sockaddr *, int)" +.br +.RI "\fILaunch a connect() attempt with a socket-based bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_socket_connect_hostname\fP (struct \fBbufferevent\fP *, struct evdns_base *, int, const char *, int)" +.br +.RI "\fIResolve the hostname 'hostname' and connect to it as with \fBbufferevent_socket_connect()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_socket_get_dns_error\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIReturn the error code for the last failed DNS lookup attempt made by \fBbufferevent_socket_connect_hostname()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_socket_new\fP (struct \fBevent_base\fP *base, \fBevutil_socket_t\fP fd, int options)" +.br +.RI "\fICreate a new socket bufferevent over an existing socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_trigger\fP (struct \fBbufferevent\fP *bufev, short iotype, int options)" +.br +.RI "\fITriggers bufferevent data callbacks\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_trigger_event\fP (struct \fBbufferevent\fP *bufev, short what, int options)" +.br +.RI "\fITriggers the bufferevent event callback\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_unlock\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIRelease the lock on a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_write\fP (struct \fBbufferevent\fP *bufev, const void *data, size_t size)" +.br +.RI "\fIWrite data to a bufferevent buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_write_buffer\fP (struct \fBbufferevent\fP *bufev, struct \fBevbuffer\fP *buf)" +.br +.RI "\fIWrite data from an evbuffer to a bufferevent buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBev_token_bucket_cfg_free\fP (struct ev_token_bucket_cfg *cfg)" +.br +.RI "\fIFree all storage held in 'cfg'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct ev_token_bucket_cfg * \fBev_token_bucket_cfg_new\fP (size_t read_rate, size_t read_burst, size_t write_rate, size_t write_burst, const struct timeval *tick_len)" +.br +.RI "\fIInitialize and return a new object to configure the rate-limiting behavior of bufferevents\&. \fP" +.in -1c +.PP +.RI "\fBRate limit inspection\fP" +.br +Return the current read or write bucket size for a bufferevent\&. +.PP +If it is not configured with a per-bufferevent ratelimit, return EV_SSIZE_MAX\&. This function does not inspect the group limit, if any\&. Note that it can return a negative value if the bufferevent has been made to read or write more than its limit\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_read_limit\fP (struct \fBbufferevent\fP *bev)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_get_write_limit\fP (struct \fBbufferevent\fP *bev)" +.br +.in -1c +.in -1c +.PP +.RI "\fBGroup Rate limit inspection\fP" +.br +Return the read or write bucket size for a bufferevent rate limit group\&. +.PP +Note that it can return a negative value if bufferevents in the group have been made to read or write more than their limits\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_rate_limit_group_get_read_limit\fP (struct bufferevent_rate_limit_group *)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_ssize_t \fBbufferevent_rate_limit_group_get_write_limit\fP (struct bufferevent_rate_limit_group *)" +.br +.in -1c +.in -1c +.PP +.RI "\fBRate limit manipulation\fP" +.br +Subtract a number of bytes from a bufferevent's read or write bucket\&. +.PP +The decrement value can be negative, if you want to manually refill the bucket\&. If the change puts the bucket above or below zero, the bufferevent will resume or suspend reading writing as appropriate\&. These functions make no change in the buckets for the bufferevent's group, if any\&. +.PP +Returns 0 on success, -1 on internal error\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_decrement_read_limit\fP (struct \fBbufferevent\fP *bev, ev_ssize_t decr)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_decrement_write_limit\fP (struct \fBbufferevent\fP *bev, ev_ssize_t decr)" +.br +.in -1c +.in -1c +.PP +.RI "\fBGroup rate limit manipulation\fP" +.br +Subtract a number of bytes from a bufferevent rate-limiting group's read or write bucket\&. +.PP +The decrement value can be negative, if you want to manually refill the bucket\&. If the change puts the bucket above or below zero, the bufferevents in the group will resume or suspend reading writing as appropriate\&. +.PP +Returns 0 on success, -1 on internal error\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_rate_limit_group_decrement_read\fP (struct bufferevent_rate_limit_group *, ev_ssize_t)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_rate_limit_group_decrement_write\fP (struct bufferevent_rate_limit_group *, ev_ssize_t)" +.br +.in -1c +.in -1c +.SS "Filtering support" + +.in +1c +.ti -1c +.RI "enum \fBbufferevent_filter_result\fP { \fBBEV_OK\fP = 0, \fBBEV_NEED_MORE\fP = 1, \fBBEV_ERROR\fP = 2 } +.RI "\fIValues that filters can return\&. \fP"" +.br +.ti -1c +.RI "typedef enum \fBbufferevent_filter_result\fP(* \fBbufferevent_filter_cb\fP) (struct \fBevbuffer\fP *src, struct \fBevbuffer\fP *dst, ev_ssize_t dst_limit, enum \fBbufferevent_flush_mode\fP mode, void *ctx)" +.br +.RI "\fIA callback function to implement a filter for a bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_filter_new\fP (struct \fBbufferevent\fP *underlying, \fBbufferevent_filter_cb\fP input_filter, \fBbufferevent_filter_cb\fP output_filter, int options, void(*free_context)(void *), void *ctx)" +.br +.RI "\fIAllocate a new filtering bufferevent on top of an existing bufferevent\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Functions for buffering data for network sending or receiving\&. + +Bufferevents are higher level than evbuffers: each has an underlying evbuffer for reading and one for writing, and callbacks that are invoked under certain circumstances\&. +.PP +A bufferevent provides input and output buffers that get filled and drained automatically\&. The user of a bufferevent no longer deals directly with the I/O, but instead is reading from input and writing to output buffers\&. +.PP +Once initialized, the bufferevent structure can be used repeatedly with \fBbufferevent_enable()\fP and \fBbufferevent_disable()\fP\&. +.PP +When reading is enabled, the bufferevent will try to read from the file descriptor onto its input buffer, and call the read callback\&. When writing is enabled, the bufferevent will try to write data onto its file descriptor when the output buffer has enough data, and call the write callback when the output buffer is sufficiently drained\&. +.PP +Bufferevents come in several flavors, including: +.PP +.IP "\fBSocket-based bufferevents \fP" 1c +A bufferevent that reads and writes data onto a network socket\&. Created with \fBbufferevent_socket_new()\fP\&. +.PP +.IP "\fBPaired bufferevents \fP" 1c +A pair of bufferevents that send and receive data to one another without touching the network\&. Created with \fBbufferevent_pair_new()\fP\&. +.PP +.IP "\fBFiltering bufferevents \fP" 1c +A bufferevent that transforms data, and sends or receives it over another underlying bufferevent\&. Created with \fBbufferevent_filter_new()\fP\&. +.PP +.IP "\fBSSL-backed bufferevents \fP" 1c +A bufferevent that uses the openssl library to send and receive data over an encrypted connection\&. Created with \fBbufferevent_openssl_socket_new()\fP or \fBbufferevent_openssl_filter_new()\fP\&. +.PP + +.SH "Macro Definition Documentation" +.PP +.SS "#define BEV_EVENT_CONNECTED 0x80" + +.PP +connect operation finished\&. +.SS "#define EV_RATE_LIMIT_MAX EV_SSIZE_MAX" + +.PP +Maximum configurable rate- or burst-limit\&. +.SH "Typedef Documentation" +.PP +.SS "typedef void(* bufferevent_data_cb) (struct \fBbufferevent\fP *bev, void *ctx)" + +.PP +A read or write callback for a bufferevent\&. The read callback is triggered when new data arrives in the input buffer and the amount of readable data exceed the low watermark which is 0 by default\&. +.PP +The write callback is triggered if the write buffer has been exhausted or fell below its low watermark\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbev\fP the bufferevent that triggered the callback +.br +\fIctx\fP the user-specified context for this bufferevent +.RE +.PP + +.SS "typedef void(* bufferevent_event_cb) (struct \fBbufferevent\fP *bev, short what, void *ctx)" + +.PP +An event/error callback for a bufferevent\&. The event callback is triggered if either an EOF condition or another unrecoverable error was encountered\&. +.PP +For bufferevents with deferred callbacks, this is a bitwise OR of all errors that have happened on the bufferevent since the last callback invocation\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbev\fP the bufferevent for which the error condition was reached +.br +\fIwhat\fP a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING to indicate if the error was encountered on the read or write path, and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR, BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED\&. +.br +\fIctx\fP the user-specified context for this bufferevent +.RE +.PP + +.SS "typedef enum \fBbufferevent_filter_result\fP(* bufferevent_filter_cb) (struct \fBevbuffer\fP *src, struct \fBevbuffer\fP *dst, ev_ssize_t dst_limit, enum \fBbufferevent_flush_mode\fP mode, void *ctx)" + +.PP +A callback function to implement a filter for a bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsrc\fP An evbuffer to drain data from\&. +.br +\fIdst\fP An evbuffer to add data to\&. +.br +\fIlimit\fP A suggested upper bound of bytes to write to dst\&. The filter may ignore this value, but doing so means that it will overflow the high-water mark associated with dst\&. -1 means 'no limit'\&. +.br +\fImode\fP Whether we should write data as may be convenient (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), or flush as much as we can, possibly including an end-of-stream marker (BEV_FINISH)\&. +.br +\fIctx\fP A user-supplied pointer\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +BEV_OK if we wrote some data; BEV_NEED_MORE if we can't produce any more output until we get some input; and BEV_ERROR on an error\&. +.RE +.PP + +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBbufferevent_filter_result\fP" + +.PP +Values that filters can return\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBEV_OK \fP\fP +everything is okay +.TP +\fB\fIBEV_NEED_MORE \fP\fP +the filter needs to read more data before output +.TP +\fB\fIBEV_ERROR \fP\fP +the filter encountered a critical error, no further data can be processed\&. +.SS "enum \fBbufferevent_flush_mode\fP" + +.PP +Flags that can be passed into filters to let them know how to deal with the incoming data\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBEV_NORMAL \fP\fP +usually set when processing data +.TP +\fB\fIBEV_FLUSH \fP\fP +want to checkpoint all data sent\&. +.TP +\fB\fIBEV_FINISHED \fP\fP +encountered EOF on read or done sending data +.SS "enum \fBbufferevent_options\fP" + +.PP +Options that can be specified when creating a bufferevent\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBEV_OPT_CLOSE_ON_FREE \fP\fP +If set, we close the underlying file descriptor/bufferevent/whatever when this bufferevent is freed\&. +.TP +\fB\fIBEV_OPT_THREADSAFE \fP\fP +If set, and threading is enabled, operations on this bufferevent are protected by a lock\&. +.TP +\fB\fIBEV_OPT_DEFER_CALLBACKS \fP\fP +If set, callbacks are run deferred in the event loop\&. +.TP +\fB\fIBEV_OPT_UNLOCK_CALLBACKS \fP\fP +If set, callbacks are executed without locks being held on the bufferevent\&. This option currently requires that BEV_OPT_DEFER_CALLBACKS also be set; a future version of Libevent might remove the requirement\&. +.SS "enum \fBbufferevent_trigger_options\fP" + +.PP +Flags for bufferevent_trigger(_event) that modify when and how to trigger the callback\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIBEV_TRIG_IGNORE_WATERMARKS \fP\fP +trigger the callback regardless of the watermarks +.TP +\fB\fIBEV_TRIG_DEFER_CALLBACKS \fP\fP +defer even if the callbacks are not +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_add_to_rate_limit_group (struct \fBbufferevent\fP * bev, struct bufferevent_rate_limit_group * g)" + +.PP +Add 'bev' to the list of bufferevents whose aggregate reading and writing is restricted by 'g'\&. If 'g' is NULL, remove 'bev' from its current group\&. +.PP +A bufferevent may belong to no more than one rate-limit group at a time\&. If 'bev' is already a member of a group, it will be removed from its old group before being added to 'g'\&. +.PP +Return 0 on success and -1 on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_base_set (struct \fBevent_base\fP * base, struct \fBbufferevent\fP * bufev)" + +.PP +Assign a bufferevent to a specific \fBevent_base\fP\&. NOTE that only socket bufferevents support this function\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP an \fBevent_base\fP returned by \fBevent_init()\fP +.br +\fIbufev\fP a bufferevent struct returned by bufferevent_new() or \fBbufferevent_socket_new()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +bufferevent_new() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_decref (struct \fBbufferevent\fP * bufev)" + +.PP +Public interface to manually decrement the reference count of a bufferevent\&. Warning: make sure you know what you're doing\&. This is mainly used in conjunction with \fBbufferevent_incref()\fP\&. This will free up all data associated with a bufferevent if the reference count hits 0\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to decrement the refcount on +.RE +.PP +\fBReturns:\fP +.RS 4 +1 if the bufferevent was freed, otherwise 0 (still referenced) +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_disable (struct \fBbufferevent\fP * bufev, short event)" + +.PP +Disable a bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be disabled +.br +\fIevent\fP any combination of EV_READ | EV_WRITE\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBbufferevent_enable()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_enable (struct \fBbufferevent\fP * bufev, short event)" + +.PP +Enable a bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be enabled +.br +\fIevent\fP any combination of EV_READ | EV_WRITE\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBbufferevent_disable()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP* bufferevent_filter_new (struct \fBbufferevent\fP * underlying, \fBbufferevent_filter_cb\fP input_filter, \fBbufferevent_filter_cb\fP output_filter, int options, void(*)(void *) free_context, void * ctx)" + +.PP +Allocate a new filtering bufferevent on top of an existing bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIunderlying\fP the underlying bufferevent\&. +.br +\fIinput_filter\fP The filter to apply to data we read from the underlying bufferevent +.br +\fIoutput_filter\fP The filer to apply to data we write to the underlying bufferevent +.br +\fIoptions\fP A bitfield of bufferevent options\&. +.br +\fIfree_context\fP A function to use to free the filter context when this bufferevent is freed\&. +.br +\fIctx\fP A context pointer to pass to the filter functions\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_flush (struct \fBbufferevent\fP * bufev, short iotype, enum \fBbufferevent_flush_mode\fP mode)" + +.PP +Triggers the bufferevent to produce more data if possible\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent object +.br +\fIiotype\fP either EV_READ or EV_WRITE or both\&. +.br +\fImode\fP either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED +.RE +.PP +\fBReturns:\fP +.RS 4 +-1 on failure, 0 if no data was produces, 1 if data was produced +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_free (struct \fBbufferevent\fP * bufev)" + +.PP +Deallocate the storage associated with a bufferevent structure\&. If there is pending data to write on the bufferevent, it probably won't be flushed before the bufferevent is freed\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent structure to be freed\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL short bufferevent_get_enabled (struct \fBbufferevent\fP * bufev)" + +.PP +Return the events that are enabled on a given bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to inspect +.RE +.PP +\fBReturns:\fP +.RS 4 +A combination of EV_READ | EV_WRITE +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP* bufferevent_get_input (struct \fBbufferevent\fP * bufev)" + +.PP +Returns the input buffer\&. The user MUST NOT set the callback on this buffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent from which to get the evbuffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the evbuffer object for the input buffer +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_single_read (struct \fBbufferevent\fP * bev)" + +.PP +Get the current size limit for single read operation\&. +.SS "EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_single_write (struct \fBbufferevent\fP * bev)" + +.PP +Get the current size limit for single write operation\&. +.SS "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP* bufferevent_get_output (struct \fBbufferevent\fP * bufev)" + +.PP +Returns the output buffer\&. The user MUST NOT set the callback on this buffer\&. +.PP +When filters are being used, the filters need to be manually triggered if the output buffer was manipulated\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent from which to get the evbuffer +.RE +.PP +\fBReturns:\fP +.RS 4 +the evbuffer object for the output buffer +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_get_priority (const struct \fBbufferevent\fP * bufev)" + +.PP +Return the priority of a bufferevent\&. Only supported for socket bufferevents +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_getcb (struct \fBbufferevent\fP * bufev, \fBbufferevent_data_cb\fP * readcb_ptr, \fBbufferevent_data_cb\fP * writecb_ptr, \fBbufferevent_event_cb\fP * eventcb_ptr, void ** cbarg_ptr)" + +.PP +Retrieves the callbacks for a bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to examine\&. +.br +\fIreadcb_ptr\fP if readcb_ptr is nonnull, *readcb_ptr is set to the current read callback for the bufferevent\&. +.br +\fIwritecb_ptr\fP if writecb_ptr is nonnull, *writecb_ptr is set to the current write callback for the bufferevent\&. +.br +\fIeventcb_ptr\fP if eventcb_ptr is nonnull, *eventcb_ptr is set to the current event callback for the bufferevent\&. +.br +\fIcbarg_ptr\fP if cbarg_ptr is nonnull, *cbarg_ptr is set to the current callback argument for the bufferevent\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +buffervent_setcb() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_getwatermark (struct \fBbufferevent\fP * bufev, short events, size_t * lowmark, size_t * highmark)" + +.PP +Retrieves the watermarks for read or write events\&. Returns non-zero if events contains not only EV_READ or EV_WRITE\&. Returns zero if events equal EV_READ or EV_WRITE +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be examined +.br +\fIevents\fP EV_READ or EV_WRITE +.br +\fIlowmark\fP receives the lower watermark if not NULL +.br +\fIhighmark\fP receives the high watermark if not NULL +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_incref (struct \fBbufferevent\fP * bufev)" + +.PP +Public interface to manually increase the reference count of a bufferevent this is useful in situations where a user may reference the bufferevent somewhere eles (unknown to libevent) +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to increase the refcount on +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_lock (struct \fBbufferevent\fP * bufev)" + +.PP +Acquire the lock on a bufferevent\&. Has no effect if locking was not enabled with BEV_OPT_THREADSAFE\&. +.SS "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP* bufferevent_pair_get_partner (struct \fBbufferevent\fP * bev)" + +.PP +Given one bufferevent returned by \fBbufferevent_pair_new()\fP, returns the other one if it still exists\&. Otherwise returns NULL\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_pair_new (struct \fBevent_base\fP * base, int options, struct \fBbufferevent\fP * pair[2])" + +.PP +Allocate a pair of linked bufferevents\&. The bufferevents behave as would two bufferevent_sock instances connected to opposite ends of a socketpair(), except that no internal socketpair is allocated\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP The event base to associate with the socketpair\&. +.br +\fIoptions\fP A set of options for this bufferevent +.br +\fIpair\fP A pointer to an array to hold the two new bufferevent objects\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_priority_set (struct \fBbufferevent\fP * bufev, int pri)" + +.PP +Assign a priority to a bufferevent\&. Only supported for socket bufferevents\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP a bufferevent struct +.br +\fIpri\fP the priority to be assigned +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_free (struct bufferevent_rate_limit_group *)" + +.PP +Free a rate-limiting group\&. The group must have no members when this function is called\&. +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_get_totals (struct bufferevent_rate_limit_group * grp, ev_uint64_t * total_read_out, ev_uint64_t * total_written_out)" + +.PP +Inspect the total bytes read/written on a group\&. Set the variable pointed to by total_read_out to the total number of bytes ever read on grp, and the variable pointed to by total_written_out to the total number of bytes ever written on grp\&. +.SS "EVENT2_EXPORT_SYMBOL struct bufferevent_rate_limit_group* bufferevent_rate_limit_group_new (struct \fBevent_base\fP * base, const struct ev_token_bucket_cfg * cfg)" + +.PP +Create a new rate-limit group for bufferevents\&. A rate-limit group constrains the maximum number of bytes sent and received, in toto, by all of its bufferevents\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP An \fBevent_base\fP to run any necessary timeouts for the group\&. Note that all bufferevents in the group do not necessarily need to share this \fBevent_base\fP\&. +.br +\fIcfg\fP The rate-limit for this group\&. +.RE +.PP +Note that all rate-limits hare are currently best-effort: future versions of Libevent may implement them more tightly\&. +.PP +Note also that only some bufferevent types currently respect rate-limiting\&. They are: socket-based bufferevents (normal and IOCP-based), and SSL-based bufferevents\&. +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_reset_totals (struct bufferevent_rate_limit_group * grp)" + +.PP +Reset the total bytes read/written on a group\&. Reset the number of bytes read or written on grp as given by \fBbufferevent_rate_limit_group_reset_totals()\fP\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_cfg (struct bufferevent_rate_limit_group *, const struct ev_token_bucket_cfg *)" + +.PP +Change the rate-limiting settings for a given rate-limiting group\&. Return 0 on success, -1 on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_min_share (struct bufferevent_rate_limit_group *, size_t)" + +.PP +Change the smallest quantum we're willing to allocate to any single bufferevent in a group for reading or writing at a time\&. The rationale is that, because of TCP/IP protocol overheads and kernel behavior, if a rate-limiting group is so tight on bandwidth that you're only willing to send 1 byte per tick per bufferevent, you might instead want to batch up the reads and writes so that you send N bytes per 1/N of the bufferevents (chosen at random) each tick, so you still wind up send 1 byte per tick per bufferevent on average, but you don't send so many tiny packets\&. +.PP +The default min-share is currently 64 bytes\&. +.PP +Returns 0 on success, -1 on faulre\&. +.SS "EVENT2_EXPORT_SYMBOL size_t bufferevent_read (struct \fBbufferevent\fP * bufev, void * data, size_t size)" + +.PP +Read data from a bufferevent buffer\&. The \fBbufferevent_read()\fP function is used to read data from the input buffer\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be read from +.br +\fIdata\fP pointer to a buffer that will store the data +.br +\fIsize\fP the size of the data buffer, in bytes +.RE +.PP +\fBReturns:\fP +.RS 4 +the amount of data read, in bytes\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_read_buffer (struct \fBbufferevent\fP * bufev, struct \fBevbuffer\fP * buf)" + +.PP +Read data from a bufferevent buffer into an evbuffer\&. This avoids memory copies\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be read from +.br +\fIbuf\fP the evbuffer to which to add data +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_remove_from_rate_limit_group (struct \fBbufferevent\fP * bev)" + +.PP +Remove 'bev' from its current rate-limit group (if any)\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_set_max_single_read (struct \fBbufferevent\fP * bev, size_t size)" + +.PP +Set the size limit for single read operation\&. Set to 0 for a reasonable default\&. +.PP +Return 0 on success and -1 on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_set_max_single_write (struct \fBbufferevent\fP * bev, size_t size)" + +.PP +Set the size limit for single write operation\&. Set to 0 for a reasonable default\&. +.PP +Return 0 on success and -1 on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_set_rate_limit (struct \fBbufferevent\fP * bev, struct ev_token_bucket_cfg * cfg)" + +.PP +Set the rate-limit of a the bufferevent 'bev' to the one specified in 'cfg'\&. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on 'bev'\&. +.PP +Note that only some bufferevent types currently respect rate-limiting\&. They are: socket-based bufferevents (normal and IOCP-based), and SSL-based bufferevents\&. +.PP +Return 0 on sucess, -1 on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_set_timeouts (struct \fBbufferevent\fP * bufev, const struct timeval * timeout_read, const struct timeval * timeout_write)" + +.PP +Set the read and write timeout for a bufferevent\&. A bufferevent's timeout will fire the first time that the indicated amount of time has elapsed since a successful read or write operation, during which the bufferevent was trying to read or write\&. +.PP +(In other words, if reading or writing is disabled, or if the bufferevent's read or write operation has been suspended because there's no data to write, or not enough banwidth, or so on, the timeout isn't active\&. The timeout only becomes active when we we're willing to actually read or write\&.) +.PP +Calling bufferevent_enable or setting a timeout for a bufferevent whose timeout is already pending resets its timeout\&. +.PP +If the timeout elapses, the corresponding operation (EV_READ or EV_WRITE) becomes disabled until you re-enable it again\&. The bufferevent's event callback is called with the BEV_EVENT_TIMEOUT|BEV_EVENT_READING or BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be modified +.br +\fItimeout_read\fP the read timeout, or NULL +.br +\fItimeout_write\fP the write timeout, or NULL +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_setcb (struct \fBbufferevent\fP * bufev, \fBbufferevent_data_cb\fP readcb, \fBbufferevent_data_cb\fP writecb, \fBbufferevent_event_cb\fP eventcb, void * cbarg)" + +.PP +Changes the callbacks for a bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent object for which to change callbacks +.br +\fIreadcb\fP callback to invoke when there is data to be read, or NULL if no callback is desired +.br +\fIwritecb\fP callback to invoke when the file descriptor is ready for writing, or NULL if no callback is desired +.br +\fIeventcb\fP callback to invoke when there is an event on the file descriptor +.br +\fIcbarg\fP an argument that will be supplied to each of the callbacks (readcb, writecb, and errorcb) +.RE +.PP +\fBSee also:\fP +.RS 4 +bufferevent_new() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_setfd (struct \fBbufferevent\fP * bufev, \fBevutil_socket_t\fP fd)" + +.PP +Changes the file descriptor on which the bufferevent operates\&. Not supported for all bufferevent types\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent object for which to change the file descriptor +.br +\fIfd\fP the file descriptor to operate on +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_setwatermark (struct \fBbufferevent\fP * bufev, short events, size_t lowmark, size_t highmark)" + +.PP +Sets the watermarks for read and write events\&. On input, a bufferevent does not invoke the user read callback unless there is at least low watermark data in the buffer\&. If the read buffer is beyond the high watermark, the bufferevent stops reading from the network\&. +.PP +On output, the user write callback is invoked whenever the buffered data falls below the low watermark\&. Filters that write to this bufev will try not to write more bytes to this buffer than the high watermark would allow, except when flushing\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be modified +.br +\fIevents\fP EV_READ, EV_WRITE or both +.br +\fIlowmark\fP the lower watermark to set +.br +\fIhighmark\fP the high watermark to set +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect (struct \fBbufferevent\fP *, const struct sockaddr *, int)" + +.PP +Launch a connect() attempt with a socket-based bufferevent\&. When the connect succeeds, the eventcb will be invoked with BEV_EVENT_CONNECTED set\&. +.PP +If the bufferevent does not already have a socket set, we allocate a new socket here and make it nonblocking before we begin\&. +.PP +If no address is provided, we assume that the socket is already connecting, and configure the bufferevent so that a BEV_EVENT_CONNECTED event will be yielded when it is done connecting\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP an existing bufferevent allocated with \fBbufferevent_socket_new()\fP\&. +.br +\fIaddr\fP the address we should connect to +.br +\fIsocklen\fP The length of the address +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect_hostname (struct \fBbufferevent\fP *, struct evdns_base *, int, const char *, int)" + +.PP +Resolve the hostname 'hostname' and connect to it as with \fBbufferevent_socket_connect()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP An existing bufferevent allocated with \fBbufferevent_socket_new()\fP +.br +\fIevdns_base\fP Optionally, an evdns_base to use for resolving hostnames asynchronously\&. May be set to NULL for a blocking resolve\&. +.br +\fIfamily\fP A preferred address family to resolve addresses to, or AF_UNSPEC for no preference\&. Only AF_INET, AF_INET6, and AF_UNSPEC are supported\&. +.br +\fIhostname\fP The hostname to resolve; see below for notes on recognized formats +.br +\fIport\fP The port to connect to on the resolved address\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, -1 on failure\&. +.RE +.PP +Recognized hostname formats are: +.PP +.nf +www.example.com (hostname) +1.2.3.4 (ipv4address) +::1 (ipv6address) +[::1] ([ipv6address]) + +.fi +.PP +.PP +Performance note: If you do not provide an evdns_base, this function may block while it waits for a DNS response\&. This is probably not what you want\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_socket_get_dns_error (struct \fBbufferevent\fP * bev)" + +.PP +Return the error code for the last failed DNS lookup attempt made by \fBbufferevent_socket_connect_hostname()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbev\fP The bufferevent object\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +DNS error code\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +evutil_gai_strerror() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP* bufferevent_socket_new (struct \fBevent_base\fP * base, \fBevutil_socket_t\fP fd, int options)" + +.PP +Create a new socket bufferevent over an existing socket\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the event base to associate with the new bufferevent\&. +.br +\fIfd\fP the file descriptor from which data is read and written to\&. This file descriptor is not allowed to be a pipe(2)\&. It is safe to set the fd to -1, so long as you later set it with bufferevent_setfd or \fBbufferevent_socket_connect()\fP\&. +.br +\fIoptions\fP Zero or more BEV_OPT_* flags +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to a newly allocated bufferevent struct, or NULL if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBbufferevent_free()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_trigger (struct \fBbufferevent\fP * bufev, short iotype, int options)" + +.PP +Triggers bufferevent data callbacks\&. The function will honor watermarks unless options contain BEV_TRIG_IGNORE_WATERMARKS\&. If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent object +.br +\fIiotype\fP either EV_READ or EV_WRITE or both\&. +.br +\fIoptions\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_trigger_event (struct \fBbufferevent\fP * bufev, short what, int options)" + +.PP +Triggers the bufferevent event callback\&. If the options contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent object +.br +\fIwhat\fP the flags to pass onto the event callback +.br +\fIoptions\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void bufferevent_unlock (struct \fBbufferevent\fP * bufev)" + +.PP +Release the lock on a bufferevent\&. Has no effect if locking was not enabled with BEV_OPT_THREADSAFE\&. +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_write (struct \fBbufferevent\fP * bufev, const void * data, size_t size)" + +.PP +Write data to a bufferevent buffer\&. The \fBbufferevent_write()\fP function can be used to write data to the file descriptor\&. The data is appended to the output buffer and written to the descriptor automatically as it becomes available for writing\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be written to +.br +\fIdata\fP a pointer to the data to be written +.br +\fIsize\fP the length of the data, in bytes +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBbufferevent_write_buffer()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_write_buffer (struct \fBbufferevent\fP * bufev, struct \fBevbuffer\fP * buf)" + +.PP +Write data from an evbuffer to a bufferevent buffer\&. The evbuffer is being drained as a result\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbufev\fP the bufferevent to be written to +.br +\fIbuf\fP the evbuffer to be written +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBbufferevent_write()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void ev_token_bucket_cfg_free (struct ev_token_bucket_cfg * cfg)" + +.PP +Free all storage held in 'cfg'\&. Note: 'cfg' is not currently reference-counted; it is not safe to free it until no bufferevent is using it\&. +.SS "EVENT2_EXPORT_SYMBOL struct ev_token_bucket_cfg* ev_token_bucket_cfg_new (size_t read_rate, size_t read_burst, size_t write_rate, size_t write_burst, const struct timeval * tick_len)" + +.PP +Initialize and return a new object to configure the rate-limiting behavior of bufferevents\&. +.PP +\fBParameters:\fP +.RS 4 +\fIread_rate\fP The maximum number of bytes to read per tick on average\&. +.br +\fIread_burst\fP The maximum number of bytes to read in any single tick\&. +.br +\fIwrite_rate\fP The maximum number of bytes to write per tick on average\&. +.br +\fIwrite_burst\fP The maximum number of bytes to write in any single tick\&. +.br +\fItick_len\fP The length of a single tick\&. Defaults to one second\&. Any fractions of a millisecond are ignored\&. +.RE +.PP +Note that all rate-limits hare are currently best-effort: future versions of Libevent may implement them more tightly\&. +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/bufferevent_ssl.h.3 b/static/netbsd/man3/bufferevent_ssl.h.3 new file mode 100644 index 00000000..6f7ec85a --- /dev/null +++ b/static/netbsd/man3/bufferevent_ssl.h.3 @@ -0,0 +1,135 @@ +.TH "event2/bufferevent_ssl.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/bufferevent_ssl.h \- OpenSSL support for bufferevents\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBbufferevent_ssl_state\fP { \fBBUFFEREVENT_SSL_OPEN\fP = 0, \fBBUFFEREVENT_SSL_CONNECTING\fP = 1, \fBBUFFEREVENT_SSL_ACCEPTING\fP = 2 } +.RI "\fIThe state of an SSL object to be used when creating a new SSL bufferevent\&. \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL unsigned long \fBbufferevent_get_openssl_error\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIReturn the most recent OpenSSL error reported on an SSL bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_openssl_filter_new\fP (struct \fBevent_base\fP *base, struct \fBbufferevent\fP *underlying, struct ssl_st *ssl, enum \fBbufferevent_ssl_state\fP state, int options)" +.br +.RI "\fICreate a new SSL bufferevent to send its data over another bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_openssl_get_allow_dirty_shutdown\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fIControl how to report dirty SSL shutdowns\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct ssl_st * \fBbufferevent_openssl_get_ssl\fP (struct \fBbufferevent\fP *bufev)" +.br +.RI "\fIReturn the underlying openssl SSL * object for an SSL bufferevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBbufferevent_openssl_set_allow_dirty_shutdown\fP (struct \fBbufferevent\fP *bev, int allow_dirty_shutdown)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBbufferevent_openssl_socket_new\fP (struct \fBevent_base\fP *base, \fBevutil_socket_t\fP fd, struct ssl_st *ssl, enum \fBbufferevent_ssl_state\fP state, int options)" +.br +.RI "\fICreate a new SSL bufferevent to send its data over an SSL * on a socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBbufferevent_ssl_renegotiate\fP (struct \fBbufferevent\fP *bev)" +.br +.RI "\fITells a bufferevent to begin SSL renegotiation\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +OpenSSL support for bufferevents\&. + + +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL unsigned long bufferevent_get_openssl_error (struct \fBbufferevent\fP * bev)" + +.PP +Return the most recent OpenSSL error reported on an SSL bufferevent\&. +.SS "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP* bufferevent_openssl_filter_new (struct \fBevent_base\fP * base, struct \fBbufferevent\fP * underlying, struct ssl_st * ssl, enum \fBbufferevent_ssl_state\fP state, int options)" + +.PP +Create a new SSL bufferevent to send its data over another bufferevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP An \fBevent_base\fP to use to detect reading and writing\&. It must also be the base for the underlying bufferevent\&. +.br +\fIunderlying\fP A socket to use for this SSL +.br +\fIssl\fP A SSL* object from openssl\&. +.br +\fIstate\fP The current state of the SSL connection +.br +\fIoptions\fP One or more bufferevent_options +.RE +.PP +\fBReturns:\fP +.RS 4 +A new bufferevent on success, or NULL on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_openssl_get_allow_dirty_shutdown (struct \fBbufferevent\fP * bev)" + +.PP +Control how to report dirty SSL shutdowns\&. If the peer (or the network, or an attacker) closes the TCP connection before closing the SSL channel, and the protocol is SSL >= v3, this is a 'dirty' shutdown\&. If allow_dirty_shutdown is 0 (default), this is reported as BEV_EVENT_ERROR\&. +.PP +If instead allow_dirty_shutdown=1, a dirty shutdown is reported as BEV_EVENT_EOF\&. +.PP +(Note that if the protocol is < SSLv3, you will always receive BEV_EVENT_EOF, since SSL 2 and earlier cannot distinguish a secure connection close from a dirty one\&. This is one reason (among many) not to use SSL 2\&.) +.SS "EVENT2_EXPORT_SYMBOL struct ssl_st* bufferevent_openssl_get_ssl (struct \fBbufferevent\fP * bufev)" + +.PP +Return the underlying openssl SSL * object for an SSL bufferevent\&. +.SS "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP* bufferevent_openssl_socket_new (struct \fBevent_base\fP * base, \fBevutil_socket_t\fP fd, struct ssl_st * ssl, enum \fBbufferevent_ssl_state\fP state, int options)" + +.PP +Create a new SSL bufferevent to send its data over an SSL * on a socket\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP An \fBevent_base\fP to use to detect reading and writing +.br +\fIfd\fP A socket to use for this SSL +.br +\fIssl\fP A SSL* object from openssl\&. +.br +\fIstate\fP The current state of the SSL connection +.br +\fIoptions\fP One or more bufferevent_options +.RE +.PP +\fBReturns:\fP +.RS 4 +A new bufferevent on success, or NULL on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int bufferevent_ssl_renegotiate (struct \fBbufferevent\fP * bev)" + +.PP +Tells a bufferevent to begin SSL renegotiation\&. +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/byteorder.3 b/static/netbsd/man3/byteorder.3 new file mode 100644 index 00000000..68502eb9 --- /dev/null +++ b/static/netbsd/man3/byteorder.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: byteorder.3,v 1.15 2011/05/03 04:07:39 jruoho Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)byteorder.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 3, 2011 +.Dt BYTEORDER 3 +.Os +.Sh NAME +.Nm htonl , +.Nm htons , +.Nm ntohl , +.Nm ntohs +.Nd convert values between host and network byte order +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In arpa/inet.h +.Ft uint32_t +.Fn htonl "uint32_t host32" +.Ft uint16_t +.Fn htons "uint16_t host16" +.Ft uint32_t +.Fn ntohl "uint32_t net32" +.Ft uint16_t +.Fn ntohs "uint16_t net16" +.Sh DESCRIPTION +These routines convert 16 and 32 bit quantities between network +byte order and host byte order. +.Pp +On machines which have a byte order which is the same as the network +order, these routines are defined as macros that expand to the value of +their argument. +.Pp +These routines are most often used in conjunction with Internet +addresses and ports as returned by +.Xr gethostbyname 3 +and +.Xr getservent 3 . +.Sh SEE ALSO +.Xr bswap 3 , +.Xr gethostbyname 3 , +.Xr getservent 3 +.Sh STANDARDS +The described functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Nm byteorder +functions appeared in +.Bx 4.2 . +.Sh BUGS +The `l' and `s' suffixes in the names are not meaningful in machines +where long integers are not 32 bits. diff --git a/static/netbsd/man3/bzero.3 b/static/netbsd/man3/bzero.3 new file mode 100644 index 00000000..b47d5b88 --- /dev/null +++ b/static/netbsd/man3/bzero.3 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)bzero.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: bzero.3,v 1.13 2010/04/29 06:54:26 jruoho Exp $ +.\" +.Dd April 29, 2010 +.Dt BZERO 3 +.Os +.Sh NAME +.Nm bzero +.Nd write zeroes to a byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft void +.Fn bzero "void *b" "size_t len" +.Sh DESCRIPTION +The +.Fn bzero +function +writes +.Fa len +zero bytes to the string +.Fa b . +If +.Fa len +is zero, +.Fn bzero +does nothing. +.Sh SEE ALSO +.Xr memset 3 , +.Xr swab 3 +.Sh STANDARDS +The +.Fn bzero +function conforms to +.St -p1003.1-2001 . +The +.St -p1003.1-2004 +revision marked it as legacy and recommended the use of +.Xr memset 3 +instead. +The +.St -p1003.1-2008 +revision removed +.Fn bzero +from the specification. +.Sh HISTORY +A +.Fn bzero +function +appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/c16rtomb.3 b/static/netbsd/man3/c16rtomb.3 new file mode 100644 index 00000000..e8e623d2 --- /dev/null +++ b/static/netbsd/man3/c16rtomb.3 @@ -0,0 +1,222 @@ +.\" $NetBSD: c16rtomb.3,v 1.11 2024/08/20 20:36:30 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 14, 2024 +.Dt C16RTOMB 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm c16rtomb +.Nd Restartable UTF-16 to multibyte conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo c16rtomb +.Fa "char * restrict s" +.Fa "char16_t c16" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function decodes UTF-16 and converts it to multibyte characters in the +current locale, keeping state to remember incremental progress if +restarted. +.Pp +Each call to +.Nm +updates the conversion state +.Fa ps +with a UTF-16 code unit +.Fa c16 , +writes up to +.Dv MB_CUR_MAX +bytes to +.Fa s +(possibly none), and returns either the number of bytes written to +.Fa s +or +.Li (size_t)-1 +to denote error. +.Pp +If +.Fa s +is a null pointer, +no output is produced and +.Fa ps +is reset to the initial conversion state, as if the call had been +.Fo c8rtomb +.Va buf , +.Li 0 , +.Fa ps +.Fc +for some internal buffer +.Va buf . +.Pp +If +.Fa c16 +is zero, +.Nm +discards any pending incomplete UTF-16 code unit sequence in +.Fa ps , +outputs a (possibly empty) shift sequence to restore the initial state +followed by a NUL byte, and resets +.Fa ps +to the initial conversion state. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by other functions such as +.Xr mbrtoc16 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns the number of bytes written to +.Fa s +on success, or sets +.Xr errno 2 +and returns +.Li "(size_t)-1" +on failure. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +Convert a UTF-16 code unit sequence to a multibyte string, +NUL-terminate it (with any shift sequence needed to restore the initial +state), and print it: +.Bd -literal -offset indent +char16_t c16[] = { 0xd83d, 0xdca9 }; +char buf[(__arraycount(c16) + 1)*MB_LEN_MAX], *s = buf; +size_t i; +mbstate_t mbs = {0}; /* initial conversion state */ + +for (i = 0; i < __arraycount(c16); i++) { + size_t len; + + len = c16rtomb(s, c16[i], &mbs); + if (len == (size_t)-1) + err(1, "c16rtomb"); + assert(len < sizeof(buf) - (s - buf)); + s += len; +} +len = c16rtomb(s, 0, &mbs); /* NUL-terminate */ +if (len == (size_t)-1) + err(1, "c16rtomb"); +assert(len <= sizeof(buf) - (s - buf)); +printf("%s\en", buf); +.Ed +.Pp +To avoid a variable-length array, this code uses +.Dv MB_LEN_MAX , +which is a constant upper bound on the locale-dependent +.Dv MB_CUR_MAX . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +.Fa c16 +is invalid as the next code unit in the conversion state +.Fa ps . +.It Bq Er EILSEQ +The input cannot be encoded as a multibyte sequence in the current +locale. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c32rtomb 3 , +.Xr c8rtomb 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 , +.Xr mbrtoc8 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.Rs +.%A P. Hoffman +.%A F. Yergeau +.%T UTF-16, an encoding of ISO 10646 +.%R RFC 2781 +.%D February 2000 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc2781 +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh STANDARDS +The +.Nm +function conforms to +.St -isoC-2011 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh BUGS +The standard requires that passing zero as +.Fa c16 +unconditionally reset the conversion state and output a NUL byte: +.Bd -filled -offset indent +If +.Fa c16 +is a null wide character, a null byte is stored, preceded by any shift +sequence needed to restore the initial shift state; the resulting state +described is the initial conversion state. +.Ed +.Pp +However, some implementations such as +.Fx 14.0 , +.Ox 7.4 , +and glibc 2.36 ignore this clause and, if the zero was preceded by an +incomplete UTF-16 code unit sequence, fail with +.Er EILSEQ +instead. diff --git a/static/netbsd/man3/c32rtomb.3 b/static/netbsd/man3/c32rtomb.3 new file mode 100644 index 00000000..72cbce18 --- /dev/null +++ b/static/netbsd/man3/c32rtomb.3 @@ -0,0 +1,200 @@ +.\" $NetBSD: c32rtomb.3,v 1.11 2024/08/20 20:36:30 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 14, 2024 +.Dt C32RTOMB 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm c32rtomb +.Nd Restartable UTF-32 to multibyte conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo c32rtomb +.Fa "char * restrict s" +.Fa "char32_t c32" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function converts Unicode scalar values to multibyte characters in the +current locale, keeping state to remember incremental progress if +restarted. +.Pp +Each call to +.Nm +updates the conversion state +.Fa ps +with a UTF-32 code unit +.Fa c32 , +writes up to +.Dv MB_CUR_MAX +bytes to +.Fa s , +and returns either the number of bytes written to +.Fa s +or +.Li (size_t)-1 +to denote error. +.Pp +The input +.Fa c32 +is a UTF-32 code unit, representing a Unicode scalar value, i.e., a +Unicode code point that is not a surrogate code point \(em in other +words, +.Fa c32 +is an integer either in [0,0xd7ff] or in [0xe000,0x10ffff]. +.Pp +If +.Fa s +is a null pointer, +no output is produced and +.Fa ps +is reset to the initial conversion state, as if the call had been +.Fo c8rtomb +.Va buf , +.Li 0 , +.Fa ps +.Fc +for some internal buffer +.Va buf . +.Pp +If +.Fa c32 +is zero, +.Nm +outputs a (possibly empty) shift sequence to restore the initial state +followed by a NUL byte and resets +.Fa ps +to the initial conversion state. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by other functions such as +.Xr mbrtoc32 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns the number of bytes written to +.Fa s +on success, or sets +.Xr errno 2 +and returns +.Li "(size_t)-1" +on failure. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +Convert a sequence of Unicode scalar values to a multibyte sequence, +NUL-terminate it (with any shift sequence needed to restore the initial +state), and print it: +.Bd -literal -offset indent +char32_t c32[] = { 0x1f4a9, 0x20ac, 0x21 }; +char buf[(__arraycount(c32) + 1)*MB_LEN_MAX], *s = buf; +size_t i; +mbstate_t mbs = {0}; /* initial conversion state */ + +for (i = 0; i < __arraycount(c32); i++) { + size_t len; + + len = c32rtomb(s, c32[i], &mbs); + if (len == (size_t)-1) + err(1, "c32rtomb"); + assert(len < sizeof(buf) - (s - buf)); + s += len; +} +len = c32rtomb(s, 0, &mbs); /* NUL-terminate */ +if (len == (size_t)-1) + err(1, "c32rtomb"); +assert(len <= sizeof(buf) - (s - buf)); +printf("%s\en", buf); +.Ed +.Pp +To avoid a variable-length array, this code uses +.Dv MB_LEN_MAX , +which is a constant upper bound on the locale-dependent +.Dv MB_CUR_MAX . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +.Fa c32 +is not a Unicode scalar value, i.e., it is a surrogate code point in +the interval [0xd800,0xdfff] or it lies outside the Unicode codespace +[0,0x10ffff] altogether. +.It Bq Er EILSEQ +The input cannot be encoded as a multibyte sequence in the current +locale. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c16rtomb 3 , +.Xr c8rtomb 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 , +.Xr mbrtoc8 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh STANDARDS +The +.Nm +function conforms to +.St -isoC-2011 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man3/c8rtomb.3 b/static/netbsd/man3/c8rtomb.3 new file mode 100644 index 00000000..ae040128 --- /dev/null +++ b/static/netbsd/man3/c8rtomb.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: c8rtomb.3,v 1.9 2024/08/20 20:36:30 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 15, 2024 +.Dt C8RTOMB 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm c8rtomb +.Nd Restartable UTF-8 to multibyte conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo c8rtomb +.Fa "char * restrict s" +.Fa "char8_t c8" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function decodes UTF-8 and converts it to multibyte characters in the +current locale, keeping state to remember incremental progress if +restarted. +.Pp +Each call to +.Nm +updates the conversion state +.Fa ps +with a UTF-8 code unit +.Fa c8 , +writes up to +.Dv MB_CUR_MAX +bytes (possibly none) to +.Fa s , +and returns either the number of bytes written to +.Fa s +or +.Li (size_t)-1 +to denote error. +.Pp +If +.Fa s +is a null pointer, +no output is produced and +.Fa ps +is reset to the initial conversion state, as if the call had been +.Fo c8rtomb +.Va buf , +.Li 0 , +.Fa ps +.Fc +for some internal buffer +.Va buf . +.Pp +If +.Fa c8 +is zero, +.Nm +discards any pending incomplete UTF-8 code unit sequence in +.Fa ps , +outputs a (possibly empty) shift sequence to restore the initial state +followed by a NUL byte, and resets +.Fa ps +to the initial conversion state. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by other functions such as +.Xr mbrtoc8 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns the number of bytes written to +.Fa s +on success, or sets +.Xr errno 2 +and returns +.Li "(size_t)-1" +on failure. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +Convert a UTF-8 code unit sequence to a multibyte string, +NUL-terminate it (with any shift sequence needed to restore the initial +state), and print it: +.Bd -literal -offset indent +char8_t c8[] = { 0xf0, 0x9f, 0x92, 0xa9 }; +char buf[(__arraycount(c8) + 1)*MB_LEN_MAX], *s = buf; +size_t i; +mbstate_t mbs = {0}; /* initial conversion state */ + +for (i = 0; i < __arraycount(c8); i++) { + size_t len; + + len = c8rtomb(s, c8[i], &mbs); + if (len == (size_t)-1) + err(1, "c8rtomb"); + assert(len < sizeof(buf) - (s - buf)); + s += len; +} +len = c8rtomb(s, 0, &mbs); /* NUL-terminate */ +if (len == (size_t)-1) + err(1, "c16rtomb"); +assert(len <= sizeof(buf) - (s - buf)); +printf("%s\en", buf); +.Ed +.Pp +To avoid a variable-length array, this code uses +.Dv MB_LEN_MAX , +which is a constant upper bound on the locale-dependent +.Dv MB_CUR_MAX . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +.Fa c8 +is invalid as the next code unit in the conversion state +.Fa ps . +.It Bq Er EILSEQ +The input cannot be encoded as a multibyte sequence in the current +locale. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c16rtomb 3 , +.Xr c32rtomb 3 , +.Xr mbrtoc8 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.Rs +.%A F. Yergeau +.%T UTF-8, a transformation format of ISO 10646 +.%R RFC 3629 +.%D November 2003 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc3629 +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" .Sh STANDARDS +.\" The +.\" .Nm +.\" function conforms to +.\" .St -isoC-2023 . +.\" .\" XXX PR misc/58600: man pages lack C17, C23, C++98, C++03, C++11, C++17, C++20, C++23 citation syntax +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh CAVEATS +The standard requires that passing zero as +.Fa c8 +unconditionally reset the conversion state and output a NUL byte: +.Bd -filled -offset indent +If +.Fa c8 +is a null character, a null byte is stored, preceded by any shift +sequence needed to restore the initial shift state; the resulting state +described is the initial conversion state. +.Ed +.Pp +However, some implementations such as glibc 2.36 ignore this clause +and, if the zero was preceded by a nonempty incomplete UTF-8 code unit +sequence, fail with +.Er EILSEQ +instead. diff --git a/static/netbsd/man3/cabs.3 b/static/netbsd/man3/cabs.3 new file mode 100644 index 00000000..7aec7368 --- /dev/null +++ b/static/netbsd/man3/cabs.3 @@ -0,0 +1,44 @@ +.\" $NetBSD: cabs.3,v 1.4 2017/09/27 09:20:27 maya Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd September 27, 2017 +.Dt CABS 3 +.Os +.Sh NAME +.Nm cabs , +.Nm cabsf , +.Nm cabsl +.Nd return a complex absolute value +.Sh SYNOPSIS +.In complex.h +.Ft double +.Fn cabs "double complex z" +.Ft float +.Fn cabsf "float complex z" +.Ft long double +.Fn cabsl "long double complex z" +.In tgmath.h +.Ft complex-floating +.Fn cabs "complex-floating z" +.Sh DESCRIPTION +These functions compute the complex absolute value (also called +norm, modulus, or magnitude) of +.Ar z . +.Sh RETURN VALUES +These functions return the complex absolute value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cacos.3 b/static/netbsd/man3/cacos.3 new file mode 100644 index 00000000..5672244e --- /dev/null +++ b/static/netbsd/man3/cacos.3 @@ -0,0 +1,45 @@ +.\" $NetBSD: cacos.3,v 1.3 2013/01/29 02:05:08 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CACOS 3 +.Os +.Sh NAME +.Nm cacos , +.Nm cacosf , +.Nm cacosl +.Nd complex arc cosine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn cacos "double complex z" +.Ft float complex +.Fn cacosf "float complex z" +.Ft long double complex +.Fn cacosl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc cosine of +.Ar z , +with branch cuts outside the interval [\-1,\ +1] along the +real axis. +.Sh RETURN VALUES +These functions return the complex arc cosine value, in the +range of a strip mathematically unbounded along the imaginary +axis and in the interval [0,\ pi] along the real axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr ccos 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cacosh.3 b/static/netbsd/man3/cacosh.3 new file mode 100644 index 00000000..27bdbf86 --- /dev/null +++ b/static/netbsd/man3/cacosh.3 @@ -0,0 +1,45 @@ +.\" $NetBSD: cacosh.3,v 1.4 2013/03/14 19:15:34 njoly Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CACOSH 3 +.Os +.Sh NAME +.Nm cacosh , +.Nm cacoshf , +.Nm cacoshl +.Nd complex arc hyperbolic cosine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn cacosh "double complex z" +.Ft float complex +.Fn cacoshf "float complex z" +.Ft long double complex +.Fn cacoshl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc hyperbolic cosine of +.Ar z , +with a branch cut at values less than 1 along the real axis. +.Sh RETURN VALUES +These functions return the complex arc hyperbolic cosine value, +in the range of a half-strip of non-negative values along +the real axis and in the interval [\-i pi,\ +i pi] along +the imaginary axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr ccosh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/call_once.3 b/static/netbsd/man3/call_once.3 new file mode 100644 index 00000000..d44e7f7b --- /dev/null +++ b/static/netbsd/man3/call_once.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: call_once.3,v 1.2 2019/04/27 10:57:11 wiz Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt CALL_ONCE 3 +.Os +.Sh NAME +.Nm call_once +.Nd calls function exactly once +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Ft void +.Fn call_once "once_flag *flag" "void (*func)(void)" +.Vt #define ONCE_FLAG_INIT /* implementation specified */ +.Sh DESCRIPTION +The +.Nm +function uses the +.Fa flag +parameter to ensure that +.Fa func +is called exactly once, +even if called from several threads. +.Pp +The +.Dv ONCE_FLAG_INIT +definition expands to a value that can be used to initialize an object of type +.Dv once_flag . +.Pp +This portable interface is implemented on top of the +.Xr pthread_once 3 +functionality. +.Sh RETURN VALUES +None. +.Sh EXAMPLES +The following calls +.Nm +from two threads using the portable +.Xr thrd 3 +interface. +.Bd -literal -offset indent +#include +#include + +static once_flag oflag = ONCE_FLAG_INIT; + +void +called_once(void) +{ + printf("called once\n"); +} + +int +tfun(void *ptr) +{ + call_once(&oflag, called_once); +} + +int +main(int argc, char **argv) +{ + thrd_t th1, th2; + + thrd_create(&th1, tfun, NULL); + thrd_create(&th2, tfun, NULL); + + thrd_join(th1, NULL); + thrd_join(th2, NULL); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr pthread_once 3 , +.Xr threads 3 +.Sh STANDARDS +The +.Nm +function conforms to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/carg.3 b/static/netbsd/man3/carg.3 new file mode 100644 index 00000000..57c2fc80 --- /dev/null +++ b/static/netbsd/man3/carg.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: carg.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CARG 3 +.Os +.Sh NAME +.Nm carg , +.Nm cargf , +.Nm cargl +.Nd complex argument functions +.Sh SYNOPSIS +.In complex.h +.Ft double +.Fn carg "double complex z" +.Ft float +.Fn cargf "float complex z" +.Ft long double +.Fn cargl "long double complex z" +.Sh DESCRIPTION +These functions compute the argument (also called phase angle) +of +.Ar z , +with a branch cut along the negative real axis. +.Sh RETURN VALUES +These functions return the value of the argument in the interval +[\-pi,\ +pi]. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cimag 3 , +.Xr conj 3 , +.Xr cproj 3 , +.St -p1003.1-2001 +.Aq Pa complex .h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/casin.3 b/static/netbsd/man3/casin.3 new file mode 100644 index 00000000..f718866e --- /dev/null +++ b/static/netbsd/man3/casin.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: casin.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CASIN 3 +.Os +.Sh NAME +.Nm casin , +.Nm casinf , +.Nm casinl +.Nd complex arc sine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn casin "double complex z" +.Ft float complex +.Fn casinf "float complex z" +.Ft long double complex +.Fn casinl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc sine of +.Ar z , +with branch cuts outside the interval [\-1,\ +1] along the +real axis. +.Sh RETURN VALUES +These functions return the complex arc sine value, in the range +of a strip mathematically unbounded along the imaginary +axis and in the interval [\-pi/2,\ +pi/2] along the +real axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr csin 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/casinh.3 b/static/netbsd/man3/casinh.3 new file mode 100644 index 00000000..e8da9b26 --- /dev/null +++ b/static/netbsd/man3/casinh.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: casinh.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CASINH 3 +.Os +.Sh NAME +.Nm casinh , +.Nm casinhf , +.Nm casinhl +.Nd complex arc hyperbolic sine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn casinh "double complex z" +.Ft float complex +.Fn casinhf "float complex z" +.Ft long double complex +.Fn casinhl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc hyperbolic sine of +.Ar z , +with branch cuts outside the interval +[\-i,\ +i] along the imaginary axis. +.Sh RETURN VALUES +These functions return the complex arc hyperbolic sine value, +in the range of a strip mathematically unbounded along the +real axis and in the interval [\-i pi/2,\ +i pi/2] along +the imaginary axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr csinh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/catan.3 b/static/netbsd/man3/catan.3 new file mode 100644 index 00000000..e304db5a --- /dev/null +++ b/static/netbsd/man3/catan.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: catan.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CATAN 3 +.Os +.Sh NAME +.Nm catan , +.Nm catanf , +.Nm catanl +.Nd complex arc tangent functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn catan "double complex z" +.Ft float complex +.Fn catanf "float complex z" +.Ft long double complex +.Fn catanl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc tangent of +.Ar z , +with branch cuts outside the interval +[\- i,\ +i] along the imaginary axis. +.Sh RETURN VALUES +These functions return the complex arc tangent value, in the +range of a strip mathematically unbounded along the imaginary +axis and in the interval [-pi/2,\ +pi/2] along the +real axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr ctan 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/catanh.3 b/static/netbsd/man3/catanh.3 new file mode 100644 index 00000000..64269b95 --- /dev/null +++ b/static/netbsd/man3/catanh.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: catanh.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CATANH 3 +.Os +.Sh NAME +.Nm catanh , +.Nm catanhf , +.Nm catanhl +.Nd complex arc hyperbolic tangent functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn catanh "double complex z" +.Ft float complex +.Fn catanhf "float complex z" +.Ft long double complex +.Fn catanhl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex arc hyperbolic tangent of +.Ar z , +with branch cuts outside the interval +[\-1,\ +1] along the real axis. +.Sh RETURN VALUES +These functions return the complex arc hyperbolic tangent value, +in the range of a strip mathematically unbounded along +the real axis and in the interval [\-i pi/2,\ +i pi/2] along +the imaginary axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr ctanh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/catclose.3 b/static/netbsd/man3/catclose.3 new file mode 100644 index 00000000..abfada75 --- /dev/null +++ b/static/netbsd/man3/catclose.3 @@ -0,0 +1,32 @@ +.\" $NetBSD: catclose.3,v 1.12 2003/07/26 19:24:49 salo Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd May 29, 1994 +.Dt CATCLOSE 3 +.Os +.Sh NAME +.Nm catclose +.Nd close message catalog +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In nl_types.h +.Ft int +.Fn catclose "nl_catd catd" +.Sh DESCRIPTION +The +.Fn catclose +function closes the message catalog specified by the argument +.Fa catd . +.Sh SEE ALSO +.Xr gencat 1 , +.Xr catgets 3 , +.Xr catopen 3 , +.Xr nls 7 +.Sh STANDARDS +The +.Fn catclose +function conforms to +.St -xpg3 . diff --git a/static/netbsd/man3/catgets.3 b/static/netbsd/man3/catgets.3 new file mode 100644 index 00000000..87c798f7 --- /dev/null +++ b/static/netbsd/man3/catgets.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: catgets.3,v 1.16 2003/07/26 19:24:49 salo Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd February 12, 2003 +.Dt CATGETS 3 +.Os +.Sh NAME +.Nm catgets +.Nd retrieve string from message catalog +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In nl_types.h +.Ft char * +.Fn catgets "nl_catd catd" "int set_id" "int msg_id" "const char *s" +.Sh DESCRIPTION +The +.Fn catgets +function attempts to retrieve message +.Fa msg_id +of set +.Fa set_id +from the message catalog referenced by the descriptor +.Fa catd . +The argument +.Fa s +points to a default message which is returned if the function +is unable to retrieve the specified message. +.Sh RETURN VALUES +If the specified message was retrieved successfully, +.Fn catgets +returns a pointer to an internal buffer containing the message string; +otherwise it returns +.Fa s . +.Sh ERRORS +The +.Fn catgets +function will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa catd +argument is not a valid message catalog descriptor open for reading. +.It Bq Er EINTR +The operation was interrupted by a signal. +.It Bq Er ENOMSG +The message identified by +.Fa set_id +and +.Fa msg_id +is not in the message catalog. +.El +.Sh SEE ALSO +.Xr gencat 1 , +.Xr catclose 3 , +.Xr catopen 3 , +.Xr nls 7 +.Sh STANDARDS +The +.Fn catgets +function conforms to +.St -xpg4.2 . +.Pp +Major Unix vendors are split over the adoption of the two most +important message catalog specifications: catgets or +.Xr gettext 3 . +The primary concern with the catgets interface is that every +translatable string has to define a number (or a symbolic constant) +which must correspond to the message in the catalog. +Duplicate message IDs are not allowed. +Constructing message catalogs is difficult. diff --git a/static/netbsd/man3/catopen.3 b/static/netbsd/man3/catopen.3 new file mode 100644 index 00000000..c26364f7 --- /dev/null +++ b/static/netbsd/man3/catopen.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: catopen.3,v 1.14 2003/07/26 19:24:49 salo Exp $ +.\" +.\" Written by J.T. Conklin . +.\" Public domain. +.\" +.Dd May 29, 1994 +.Dt CATOPEN 3 +.Os +.Sh NAME +.Nm catopen +.Nd open message catalog +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In nl_types.h +.Ft nl_catd +.Fn catopen "const char *name" "int oflag" +.Sh DESCRIPTION +The +.Fn catopen +function opens the message catalog specified by +.Fa name +and returns a message catalog descriptor. +If +.Fa name +contains a +.Sq / +then +.Fa name +specifies the full pathname for the message catalog, otherwise the value +of the environment variable +.Ev NLSPATH +is used with +.Fa name +substituted for %N. +.Pp +The +.Fa oflag +argument is reserved for future use and should be set to zero. +.Sh RETURN VALUES +Upon successful completion, +.Fn catopen +returns a message catalog descriptor. +Otherwise, (nl_catd) -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory is available. +.El +.Sh SEE ALSO +.Xr gencat 1 , +.Xr catclose 3 , +.Xr catgets 3 , +.Xr nls 7 +.Sh STANDARDS +The +.Fn catopen +function conforms to +.St -xpg3 . diff --git a/static/netbsd/man3/ccos.3 b/static/netbsd/man3/ccos.3 new file mode 100644 index 00000000..6d3c51cf --- /dev/null +++ b/static/netbsd/man3/ccos.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: ccos.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CCOS 3 +.Os +.Sh NAME +.Nm ccos , +.Nm ccosf , +.Nm ccosl +.Nd complex cosine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn ccos "double complex z" +.Ft float complex +.Fn ccosf "float complex z" +.Ft long double complex +.Fn ccosl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex cosine of +.Ar z . +.Sh RETURN VALUES +These functions return the complex cosine value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cacos 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/ccosh.3 b/static/netbsd/man3/ccosh.3 new file mode 100644 index 00000000..e003fac6 --- /dev/null +++ b/static/netbsd/man3/ccosh.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: ccosh.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CCOSH 3 +.Os +.Sh NAME +.Nm ccosh , +.Nm ccoshf , +.Nm ccoshl +.Nd complex hyperbolic cosine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn ccosh "double complex z" +.Ft float complex +.Fn ccoshf "float complex z" +.Ft long double complex +.Fn ccoshl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex hyperbolic cosine of +.Ar z . +.Sh RETURN VALUES +These functions return the complex hyperbolic cosine value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cacosh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cdbr.3 b/static/netbsd/man3/cdbr.3 new file mode 100644 index 00000000..0b90cfd4 --- /dev/null +++ b/static/netbsd/man3/cdbr.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: cdbr.3,v 1.7 2023/10/27 04:05:55 simonb Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd December 1, 2018 +.Dt CDBR 3 +.Os +.Sh NAME +.Nm cdbr , +.Nm cdbr_open , +.Nm cdbr_open_mem , +.Nm cdbr_entries , +.Nm cdbr_get , +.Nm cdbr_find , +.Nm cdbr_close +.Nd constant database access methods +.Sh SYNOPSIS +.In cdbr.h +.Ft "struct cdbr *" +.Fn cdbr_open "const char *path" "int flags" +.Ft "struct cdbr *" +.Fo cdbr_open_mem +.Fa "void *base" +.Fa "size_t size" +.Fa "int flags" +.Fa "void (*unmap)(void *, void *, size_t)" +.Fa "void *cookie" +.Fc +.Ft uint32_t +.Fn cdbr_entries "struct cdbr *cdbr" +.Ft int +.Fn cdbr_get "struct cdbr *cdbr" "uint32_t index" "const void **data" "size_t *datalen" +.Ft int +.Fo cdbr_find +.Fa "struct cdbr *cdbr" +.Fa "const void *key" +.Fa "size_t keylen" +.Fa "const void **data" +.Fa "size_t *datalen" +.Fc +.Ft void +.Fn cdbr_close "struct cdbr *cdbr" +.Sh DESCRIPTION +The +.Nm +library provides a space efficient (key,value) database based +on perfect hashing. +.Pp +A cdb database is opened for reading by calling +.Fn cdbr_open . +The only supported value for +.Va flags +is +.Dv CDBR_DEFAULT . +The function returns a handle to pass to the other functions. +The database is closed by invoking +.Fn cdbr_close . +All resources associated with the handle are freed and the memory +returned by +.Fn cdbr_get +and +.Fn cdbr_find +is invalidated. +.Fn cdbr_open_mem +works like +.Fn cdbr_open , +but takes a memory reference to the content of the database file. +If +.Va unmap +is not +.Dv NULL , +it is called by +.Fn cdbr_close +with +.Va cookie , +.Va base +and +.Va size +as arguments. +It is not called by +.Fn cdbr_open_mem +on error. +.Pp +The number of records in the database can be obtained by calling +.Fn cdbr_entries . +Records can be obtained by record number using +.Fn cdbr_get +or by key using +.Fn cdbr_find . +Both functions return 0 on success and update +.Va data +and +.Va datalen +accordingly. +The location +.Va *data +remains valid until +.Fn cdbr_close +is called. +It is the responsibility of the caller of +.Fn cdbr_find +to ensure that the key matches the returned data. +The function returns the only possible match, but the database doesn't store +the keys to minimize overhead. +.Sh SEE ALSO +.Xr nbperf 1 , +.Xr cdbw 3 , +.Xr db 3 , +.Xr cdb 5 +.Sh HISTORY +Support for the +.Nm cdb +format first appeared in +.Nx 6.0 . +.Sh AUTHORS +The +.Nm cdbr +and +.Nm cdbw +functions have been written by +.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org . diff --git a/static/netbsd/man3/cdbw.3 b/static/netbsd/man3/cdbw.3 new file mode 100644 index 00000000..4f7994a6 --- /dev/null +++ b/static/netbsd/man3/cdbw.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: cdbw.3,v 1.9 2023/08/08 10:34:08 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd February 6, 2014 +.Dt CDBW 3 +.Os +.Sh NAME +.Nm cdbw_open , +.Nm cdbw_put , +.Nm cdbw_put_data , +.Nm cdbw_put_key , +.Nm cdbw_stable_seeder , +.Nm cdbw_output , +.Nm cdbw_close +.Nd create constant databases +.Sh SYNOPSIS +.In cdbw.h +.Ft "struct cdbw *" +.Fn cdbw_open "void" +.Ft int +.Fo cdbw_put +.Fa "struct cdbw *cdbw" +.Fa "const void *key" +.Fa "size_t keylen" +.Fa "const void *data" +.Fa "size_t datalen" +.Fc +.Ft int +.Fo cdbw_put_data +.Fa "struct cdbw *cdbw" +.Fa "const void *data" +.Fa "size_t datalen" +.Fa "uint32_t *index" +.Fc +.Ft int +.Fo cdbw_put_key +.Fa "struct cdbw *cdbw" +.Fa "const void *key" +.Fa "size_t keylen" +.Fa "uint32_t index" +.Fc +.Ft uint32_t +.Fo cdbw_stable_seeder +.Fa "void" +.Fc +.Ft int +.Fo cdbw_output +.Fa "struct cdbw *cdbw" +.Fa "int output" +.Fa "const char *descr" +.Fa "uint32_t (*seedgen)(void)" +.Fc +.Ft void +.Fn cdbw_close "struct cdbw *cdbw" +.Sh DESCRIPTION +The +.Nm cdbw +functions are used to create a constant databases for use with +.Xr cdbr 3 . +Details about the file format, including overhead and limitations, +can be found in +.Xr cdb 5 . +.Pp +.Fn cdbw_open +prepares a new +.Nm cdb +writer. +The function returns a handle to pass to the other functions. +.Pp +.Fn cdbw_close +frees all resources associated with the handle. +.Pp +.Fn cdbw_put +adds the given (key,value) pair after checking for a duplicate key. +.Fn cdbw_put_data +adds the given value to the writer without adding a key reference. +The returned index can be used in subsequent calls to +.Fn cdbw_put_key +to add one or more keys pointing to this value. +.Fn cdbw_put_key +checks for duplicate keys and valid index arguments. +On success it adds the given key. +.Pp +.Fn cdbw_output +computes the database file and writes it to the given descriptor. +The function returns an error if the file cannot be written correctly. +The +.Fa descr +parameter, a string of up to 16 bytes, provides a human readable +description of the database content. +The +.Fa seedgen +parameter can be used to override the default PRNG. +The bitwise layout of the output depends on the chosen seed. +The function should return a different value for each invocation. +The +.Fn cdbw_stable_seeder +can be used to create reproducible output. +It may be slower than the default. +.Sh SEE ALSO +.Xr cdbr 3 , +.Xr cdb 5 +.Sh HISTORY +Support for the +.Nm cdb +format first appeared in +.Nx 6.0 . +.Sh AUTHORS +The +.Nm cdbr +and +.Nm cdbw +functions have been written by +.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org . diff --git a/static/netbsd/man3/ceil.3 b/static/netbsd/man3/ceil.3 new file mode 100644 index 00000000..9babbb90 --- /dev/null +++ b/static/netbsd/man3/ceil.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)ceil.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: ceil.3,v 1.21 2017/02/01 16:06:19 abhinav Exp $ +.\" +.Dd November 12, 2013 +.Dt CEIL 3 +.Os +.Sh NAME +.Nm ceil , +.Nm ceilf , +.Nm ceill , +.Nm floor , +.Nm floorf , +.Nm floorl +.Nd ceiling and floor +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn ceil "double x" +.Ft float +.Fn ceilf "float x" +.Ft long double +.Fn ceill "long double x" +.Ft double +.Fn floor "double x" +.Ft float +.Fn floorf "float x" +.Ft long double +.Fn floorl "long double x" +.Sh DESCRIPTION +The +.Fn ceil , +.Fn ceilf , +and +.Fn ceill +functions return the smallest integral value +greater than or equal to +.Fa x . +Conversely, the +.Fn floor , +.Fn floorf , +and +.Fn floorl +functions return the largest integral value +less than or equal to +.Fa x . +.Sh SEE ALSO +.Xr abs 3 , +.Xr fabs 3 , +.Xr math 3 , +.Xr nextafter 3 , +.Xr rint 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/cexp.3 b/static/netbsd/man3/cexp.3 new file mode 100644 index 00000000..e4f6b282 --- /dev/null +++ b/static/netbsd/man3/cexp.3 @@ -0,0 +1,43 @@ +.\" $NetBSD: cexp.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CEXP 3 +.Os +.Sh NAME +.Nm cexp , +.Nm cexpf , +.Nm cexpl +.Nd complex exponential functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn cexp "double complex z" +.Ft float complex +.Fn cexpf "float complex z" +.Ft long double complex +.Fn cexpl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex exponent of +.Ar z , +defined as e**z. +.Sh RETURN VALUES +These functions return the complex exponential value of +.Ar z . +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr clog 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cgetcap.3 b/static/netbsd/man3/cgetcap.3 new file mode 100644 index 00000000..152d7afa --- /dev/null +++ b/static/netbsd/man3/cgetcap.3 @@ -0,0 +1,373 @@ +.\" $NetBSD: cgetcap.3,v 1.10 2022/12/04 01:29:32 uwe Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Casey Leedom of Lawrence Livermore National Laboratory. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 +.\" +.Dd April 5, 2012 +.Dt CGETCAP 3 +.Os +.Sh NAME +.Nm cgetent , +.Nm cgetset , +.Nm cgetmatch , +.Nm cgetcap , +.Nm cgetnum , +.Nm cgetstr , +.Nm cgetustr , +.Nm cgetfirst , +.Nm cgetnext , +.Nm cgetclose , +.Nm csetexpandtc +.Nd capability database access routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn cgetent "char **buf" "const char * const *db_array" "const char *name" +.Ft int +.Fn cgetset "const char *ent" +.Ft int +.Fn cgetmatch "const char *buf" "const char *name" +.Ft char * +.Fn cgetcap "char *buf" "const char *cap" "int type" +.Ft int +.Fn cgetnum "char *buf" "const char *cap" "long *num" +.Ft int +.Fn cgetstr "char *buf" "const char *cap" "char **str" +.Ft int +.Fn cgetustr "char *buf" "const char *cap" "char **str" +.Ft int +.Fn cgetfirst "char **buf" "const char * const *db_array" +.Ft int +.Fn cgetnext "char **buf" "const char * const *db_array" +.Ft int +.Fn cgetclose "void" +.Ft void +.Fn csetexpandtc "int expandtc" +.Sh DESCRIPTION +.Fn cgetent +extracts the capability +.Fa name +from the database specified by the +.Dv NULL +terminated file array +.Fa db_array +and returns a pointer to a +.Xr malloc 3 Ap d +copy of it in +.Fa buf . +.Fn cgetent +will first look for files ending in +.Pa .db +(see +.Xr cap_mkdb 1 ) +before accessing the +.Tn ASCII +file. +.Pp +.Fa buf +must be retained through all subsequent calls to +.Fn cgetmatch , +.Fn cgetcap , +.Fn cgetnum , +.Fn cgetstr , +and +.Fn cgetustr , +but may then be +.Xr free 3 Ap d . +.Pp +On success 0 is returned, 1 if the returned record contains an unresolved +.Qq tc +expansion, \-1 if the requested record couldn't be found, \-2 if +a system error was encountered (couldn't open/read a file, etc.) +also setting +.Va errno , +and \-3 if a potential reference loop is detected (see +.Qq tc=name +comments below). +.Pp +.Fn cgetset +enables the addition of a character buffer containing a single capability +record entry to the capability database. +Conceptually, the entry is added as the first +.Dq file +in the database, and +is therefore searched first on the call to +.Fn cgetent . +The entry is passed in +.Fa ent . +If +.Fa ent +is +.Dv NULL , +the current entry is removed from the database. +.Pp +.Fn cgetset +must precede the database traversal. +It must be called before the +.Fn cgetent +call. +If a sequential access is being performed (see below), it must be called +before the first sequential access call +.Po +.Fn cgetfirst +or +.Fn cgetnext +.Pc , +or be directly preceded by a +.Fn cgetclose +call. +On success 0 is returned and \-1 on failure. +.Pp +.Fn cgetmatch +will return 0 if +.Fa name +is one of the names of the capability record +.Fa buf , +\-1 if not. +.Pp +.Fn cgetcap +searches the capability record +.Fa buf +for the capability +.Fa cap +with type +.Fa type . +A +.Fa type +is specified using any single character. +If a colon +.Pq Sq \&: +is used, an untyped capability will be searched +for (see below for explanation of types). +A pointer to the value of +.Fa cap +in +.Fa buf +is returned on success, +.Dv NULL +if the requested capability couldn't be found. +The end of the capability value is signaled by a +.Sq \&: . +See +.Xr capfile 5 +for a description of the capability syntax. +.Pp +.Fn cgetnum +retrieves the value of the numeric capability +.Fa cap +from the capability record pointed to by +.Fa buf . +The numeric value is returned in the +.Ft long +pointed to by +.Fa num . +0 is returned on success, +\-1 if the requested numeric capability couldn't be found. +.Pp +.Fn cgetstr +retrieves the value of the string capability +.Fa cap +from the capability record pointed to by +.Fa buf . +A pointer to a decoded, +.Dv NUL +terminated, +.Xr malloc 3 Ap d +copy of the string is returned in the +.Ft char * +pointed to by +.Fa str . +The number of characters in the decoded string not including the trailing +.Dv NUL +is returned on success, \-1 if the requested string capability couldn't +be found, \-2 if a system error was encountered (storage allocation +failure). +.Pp +.Fn cgetustr +is identical to +.Fn cgetstr +except that it does not expand special characters, but rather returns each +character of the capability string literally. +.Pp +.Fn cgetfirst , +.Fn cgetnext , +comprise a function group that provides for sequential access of the +.Dv NULL +pointer terminated array of file names, +.Fa db_array . +.Fn cgetfirst +returns the first record in the database and resets the access +to the first record. +.Fn cgetnext +returns the next record in the database with respect to the +record returned by the previous +.Fn cgetfirst +or +.Fn cgetnext +call. +If there is no such previous call, +the first record in the database is returned. +Each record is returned in a +.Xr malloc 3 Ap d +copy pointed to by +.Fa buf . +.Qq tc +expansion is done (see +.Qq tc=name +comments below). +.Pp +Upon completion of the database 0 is returned, 1 is returned upon successful +return of record with possibly more remaining (we haven't reached the end of +the database yet), 2 is returned if the record contains an unresolved +.Qq tc +expansion, \-1 is returned if an system error occurred, and \-2 +is returned if a potential reference loop is detected (see +.Qq tc=name +comments below). +Upon completion of database (0 return) the database is closed. +.Pp +.Fn cgetclose +closes the sequential access and frees any memory and file descriptors +being used. +Note that it does not erase the buffer pushed by a call to +.Fn cgetset . +.Sh CAPABILITY DATABASE SEMANTICS +Capability records describe a set of (name, value) bindings. +Names may have multiple values bound to them. +Different values for a name are distinguished by their +.Fa types . +.Fn cgetcap +will return a pointer to a value of a name given the capability name and +the type of the value. +.Pp +The types +.Sq # +and +.Sq = +are conventionally used to denote numeric and +string typed values, but no restriction on those types is enforced. +The functions +.Fn cgetnum +and +.Fn cgetstr +can be used to implement the traditional syntax and semantics of +.Sq # +and +.Sq = . +Typeless capabilities are typically used to denote boolean objects with +presence or absence indicating truth and false values respectively. +This interpretation is conveniently represented by: +.Pp +.Dl "(getcap(buf, name, ':') != NULL)" +.Pp +A special capability, +.Qq tc=name , +is used to indicate that the record specified by +.Fa name +should be substituted for the +.Qq tc +capability. +.Qq tc +capabilities may interpolate records which also contain +.Qq tc +capabilities and more than one +.Qq tc +capability may be used in a record. +A +.Qq tc +expansion scope (i.e. where the argument is searched for) contains the +file in which the +.Qq tc +is declared and all subsequent files in the file array. +.Pp +.Fn csetexpandtc +can be used to control if +.Qq tc +expansion is performed or not. +.Sh RETURN VALUES +.Fn cgetent , +.Fn cgetset , +.Fn cgetmatch , +.Fn cgetnum , +.Fn cgetstr , +.Fn cgetustr , +.Fn cgetfirst , +and +.Fn cgetnext +return a value greater than or equal to 0 on success and a value less +than 0 on failure. +.Fn cgetcap +returns a character pointer on success and a +.Dv NULL +on failure. +.Pp +.Fn cgetclose , +.Fn cgetent , +.Fn cgetfirst , +and +.Fn cgetnext +may fail and set +.Va errno +for any of the errors specified for the library functions: +.Xr fopen 3 , +.Xr fclose 3 , +.Xr open 2 , +and +.Xr close 2 . +.Pp +.Fn cgetent , +.Fn cgetset , +.Fn cgetstr , +and +.Fn cgetustr +may fail and set +.Va errno +as follows: +.Bl -tag -width Er +.It Bq Er ENOMEM +No memory to allocate. +.El +.Sh SEE ALSO +.Xr cap_mkdb 1 , +.Xr malloc 3 , +.Xr capfile 5 +.Sh BUGS +There are no checks for +.Qq tc=name +loops in +.Fn cgetent . +.Pp +The buffer added to the database by a call to +.Fn cgetset +is not unique to the database but is rather prepended to any database used. diff --git a/static/netbsd/man3/cimag.3 b/static/netbsd/man3/cimag.3 new file mode 100644 index 00000000..39dca4cc --- /dev/null +++ b/static/netbsd/man3/cimag.3 @@ -0,0 +1,51 @@ +.\" $NetBSD: cimag.3,v 1.4 2012/12/27 21:34:10 wiz Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd December 27, 2012 +.Dt CIMAG 3 +.Os +.Sh NAME +.Nm cimag , +.Nm cimagf , +.Nm cimagl +.Nd complex imaginary functions +.Sh SYNOPSIS +.In complex.h +.Ft double +.Fn cimag "double complex z" +.Ft float +.Fn cimagf "float complex z" +.Ft long double +.Fn cimagl "long double complex z" +.Sh DESCRIPTION +These functions compute the imaginary part of +.Ar z . +.Sh RETURN VALUES +These functions return the imaginary part value (as a real). +.Sh ERRORS +No errors are defined. +.Sh APPLICATION USAGE +For a variable +.Ar z +of complex type: +.Bd -literal -offset indent +z = creal(z) + cimag(z)*I +.Ed +.Sh SEE ALSO +.Xr carg 3 , +.Xr conj 3 , +.Xr cproj 3 , +.Xr creal 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/clock.3 b/static/netbsd/man3/clock.3 new file mode 100644 index 00000000..678e7ac9 --- /dev/null +++ b/static/netbsd/man3/clock.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: clock.3,v 1.10 2003/08/07 16:42:46 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)clock.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt CLOCK 3 +.Os +.Sh NAME +.Nm clock +.Nd determine processor time used +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft clock_t +.Fn clock void +.Sh DESCRIPTION +The +.Fn clock +function +determines the amount of processor time used since the invocation of the +calling process, measured in +.Dv CLOCKS_PER_SEC Ns s . +.Sh RETURN VALUES +The +.Fn clock +function returns the amount of time used unless an error occurs, in which +case the return value is \-1. +.Sh SEE ALSO +.Xr getrusage 2 +.Sh STANDARDS +The +.Fn clock +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/clog.3 b/static/netbsd/man3/clog.3 new file mode 100644 index 00000000..ce431e5a --- /dev/null +++ b/static/netbsd/man3/clog.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: clog.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CLOG 3 +.Os +.Sh NAME +.Nm clog , +.Nm clogf , +.Nm clogl +.Nd complex natural logarithm functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn clog "double complex z" +.Ft float complex +.Fn clogf "float complex z" +.Ft long double complex +.Fn clogl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex natural (base e) logarithm +of +.Ar z , +with a branch cut along the negative real axis. +.Sh RETURN VALUES +These functions return the complex natural logarithm value, +in the range of a strip mathematically unbounded along the +real axis and in the interval [\-i pi,\ +i pi] along the +imaginary axis. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cexp 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/close_db.3 b/static/netbsd/man3/close_db.3 new file mode 100644 index 00000000..ec48a1c3 --- /dev/null +++ b/static/netbsd/man3/close_db.3 @@ -0,0 +1,60 @@ +.\" $NetBSD: close_db.3,v 1.3 2022/09/11 20:32:37 gutteridge Exp $ +.\" +.\" Copyright (c) 2011 Abhinav Upadhyay +.\" All rights reserved. +.\" +.\" This code was developed as part of Google's Summer of Code 2011 program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 23, 2016 +.Dt CLOSE_DB 3 +.Os +.Sh NAME +.Nm close_db +.Nd close apropos database connection +.Sh SYNOPSIS +.In apropos-utils.h +.Ft void +.Fn close_db "sqlite3 *db" +.Sh DESCRIPTION +The +.Fn close_db +function will close the connection to +.Pa /var/db/man.db +referenced by +.Fa db +and release any resources being used by it safely. +.Sh FILES +.Bl -hang -width /var/db/man.db -compact +.It Pa /var/db/man.db +The SQLite FTS database which contains an index of the manual pages. +.El +.Sh SEE ALSO +.Xr apropos-utils 3 , +.Xr init_db 3 , +.Xr run_query 3 +.Sh AUTHORS +.An Abhinav Upadhyay diff --git a/static/netbsd/man3/closefrom.3 b/static/netbsd/man3/closefrom.3 new file mode 100644 index 00000000..c2218a9a --- /dev/null +++ b/static/netbsd/man3/closefrom.3 @@ -0,0 +1,64 @@ +.\" $NetBSD: closefrom.3,v 1.6 2022/11/10 00:47:01 gutteridge Exp $ +.\" $OpenBSD: closefrom.2,v 1.2 2004/01/12 20:52:09 jmc Exp $ +.\" +.\" Copyright (c) 2004 Ted Unangst. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd November 9, 2022 +.Dt CLOSEFROM 3 +.Os +.Sh NAME +.Nm closefrom +.Nd delete many descriptors +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn closefrom "int fd" +.Sh DESCRIPTION +The +.Fn closefrom +call deletes all descriptors numbered +.Fa fd +and higher from the per-process file descriptor table. +It is effectively the same as calling +.Xr close 2 +on each descriptor. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn closefrom +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fd +is invalid. +.It Bq Er EINTR +An interrupt was received. +.El +.Sh SEE ALSO +.Xr close 2 +.Sh HISTORY +This function first appeared in +.Nx 3 . diff --git a/static/netbsd/man3/cnd.3 b/static/netbsd/man3/cnd.3 new file mode 100644 index 00000000..0ab733c1 --- /dev/null +++ b/static/netbsd/man3/cnd.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: cnd.3,v 1.3 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt CND 3 +.Os +.Sh NAME +.Nm cnd +.Nd condition variable functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Ft int +.Fn cnd_broadcast "cnd_t *cond" +.Ft void +.Fn cnd_destroy "cnd_t *cond" +.Ft int +.Fn cnd_init "cnd_t *cond" +.Ft int +.Fn cnd_signal "cnd_t *cond" +.Ft int +.Fo cnd_timedwait +.Fa "cnd_t * restrict cond" +.Fa "mtx_t * restrict mtx" +.Fa "const struct timespec * restrict ts" +.Fc +.Ft int +.Fn cnd_wait "cnd_t *cond" "mtx_t *mtx" +.Sh DESCRIPTION +The +.Fn cnd_broadcast +function unblocks all threads that are blocked on a condition variable +.Fa cond +at the time of the call. +If no thread is blocked on the +.Fa cond +condition variable at the time of the call, +the function does nothing and returns success. +.Pp +The +.Fn cnd_destroy +function destroys the +.Fa cond +condition variable. +.Pp +The +.Fn cnd_init +function initializes a new +.Fa cond +variable. +.Pp +The +.Fn cnd_signal +function unblock one thread that currently waits on the +.Fa cond +variable. +If there are no threads blocked, +.Fn cnd_signal +does nothing and returns success. +.Pp +The +.Fn cnd_timedwait +function atomically unlocks the mutex +.Fa mtx +and blocks on the condition variable +.Fa cond +until a thread is signalled by a call to +.Fn cnd_signal +or +.Fn cnd_broadcast +or timeout +.Fa ts +has been reached. +The +.Fa ts +parameter is specified as +.Dv TIME_UTC +based calendar time. +If the mutex is not locked by the calling thread then behavior is undefined. +.Pp +The +.Fn cnd_wait +function atomically unlocks the mutex +.Fa mtx +and tries to block on the conditional variable +.Fa cond +until a thread is signalled by a call to +.Fn cnd_signal +or +.Fn cnd_broadcast . +The +.Fa mtx +mutex is locked again before the function returns. +If the mutex is not locked by the calling thread then behavior is undefined. +.Sh RETURN VALUES +The +.Fn cnd_broadcast +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn cnd_destroy +function returns no value. +.Pp +The +.Fn cnd_init +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn cnd_signal +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn cnd_timedwait +function returns +.Dv thrd_success +on success, otherwise +.Dv thrd_timedout +to indicate that system time has reached or exceeded the time specified in +.Dv ts , +or +.Dv thrd_error +on failure. +.Pp +The +.Fn cnd_wait +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Sh SEE ALSO +.Xr pthread_cond 3 , +.Xr threads 3 +.Sh STANDARDS +The +.Nm +interface conforms to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/com_err.3 b/static/netbsd/man3/com_err.3 new file mode 100644 index 00000000..ec37221a --- /dev/null +++ b/static/netbsd/man3/com_err.3 @@ -0,0 +1,248 @@ +.\" $NetBSD: com_err.3,v 1.5 2023/06/19 21:41:42 christos Exp $ +.\" +.\" Copyright (c) 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.\" This manpage was contributed by Gregory McGarry. +.\" +.Dd July 7, 2005 +.Dt COM_ERR 3 +.Os +.Sh NAME +.Nm com_err , +.Nm com_err_va , +.Nm error_message , +.Nm error_table_name , +.Nm init_error_table , +.Nm set_com_err_hook , +.Nm reset_com_err_hook , +.Nm add_to_error_table , +.Nm initialize_error_table_r +.Nm free_error_table , +.Nm com_right +.Nd common error display library +.Sh LIBRARY +Common Error Library (libcom_err, -lcom_err) +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd #include \&"XXX_err.h\&" +.Pp +typedef void (*errf)(const char *, long, const char *, ...); +.Ft void +.Fn com_err "const char *whoami" "long code" "const char *format" "..." +.Ft void +.Fn com_err_va "const char *whoami" "long code" "const char *format" "..." +.Ft const char * +.Fn error_message "long code" +.Ft const char * +.Fn error_table_name "int num" +.Ft int +.Fn init_error_table "const char **msgs" "long base" "int count" +.Ft errf +.Fn set_com_err_hook "errf func" +.Ft errf +.Fn reset_com_err_hook "" +.Ft void +.Fn add_to_error_table "struct et_list *new_table" +.Ft void +.Fn initialize_error_table_r "struct et_list **et_list" "const char **msgs" "int base" "long count" +.Ft void +.Fn free_error_table "struct et_list *" +.Ft const char * +.Fn com_right "struct et_list *list" long code" +.Sh DESCRIPTION +The +.Nm +library provides a common error-reporting mechanism for defining and +accessing error codes and descriptions for application software +packages. Error descriptions are defined in a table and error codes +are used to index the table. The error table, the descriptions and +the error codes are generated using +.Xr compile_et 1 . +.Pp +The error table is registered with the +.Nm +library by calling its initialisation function defined in its header +file. The initialisation function is generally defined as +.Fn initialize__error_table , +where +.Em name +is the name of the error table. +.Pp +If a thread-safe version of the library is needed +.Fn initialize__error_table_r +that internally calls +.Fn initialize_error_table_r +instead be used. +.Pp +Any variable which is to contain an error code should be declared +.Em _error_number +where +.Em name +is the name of the error table. +.Sh FUNCTIONS +The following functions are available to the application developer: +.Bl -tag -width compact +.It Fn com_err "whoami" "code" "format" "..." +Displays an error message on standard error composed of the +.Fa whoami +string, which should specify the program name, followed by an error +message generated from +.Fa code , +and a string produced using the +.Xr printf 3 +.Fa format +string and any following arguments. If +.Fa format +is NULL, the formatted message will not be +printed. The argument +.Fa format +may not be omitted. +.It Fn com_err_va "whoami" "code" "format" "va_list args" +This routine provides an interface, equivalent to +.Fn com_err , +which may be used by higher-level variadic functions (functions which +accept variable numbers of arguments). +.It Fn error_message "code" +Returns the character string error message associated with +.Fa code . +If +.Fa code +is associated with an unknown error table, or if +.Fa code +is associated with a known error table but is not in the table, a +string of the form `Unknown code XXXX NN' is returned, where XXXX is +the error table name produced by reversing the compaction performed on +the error table number implied by that error code, and NN is the +offset from that base value. +.Pp +Although this routine is available for use when needed, its use should +be left to circumstances which render +.Fn com_err +unusable. +.Pp +.Fn com_right +returns the error string just like +.Fa com_err +but in a thread-safe way. +.Pp +.It Fn error_table_name "num" +Convert a machine-independent error table number +.Fa num +into an error table name. +.It Fn init_error_table "msgs" "base" "count" +Initialise the internal error table with the array of character string +error messages in +.Fa msgs +of length +.Fa count . +The error codes are assigned incrementally from +.Fa base . +This function is useful for using the error-reporting mechanism with +custom error tables that have not been generated with +.Xr compile_et 1 . +Although this routine is available for use when needed, its use should +be restricted. +.Pp +.Fn initialize_error_table_r +initialize the +.Fa et_list +in the same way as +.Fn init_error_table , +but in a thread-safe way. +.Pp +.It Fn set_com_err_hook "func" +Provides a hook into the +.Nm +library to allow the routine +.Fa func +to be dynamically substituted for +.Fn com_err . +After +.Fn set_com_err_hook + has been called, calls to +.Fn com_err +will turn into calls to the new hook routine. This function is +intended to be used in daemons to use a routine which calls +.Xr syslog 3 , +or in a window system application to pop up a dialogue box. +.It Fn reset_com_err_hook "" +Turns off the hook set in +.Fn set_com_err_hook . +.It Fn add_to_error_table "new_table" +Add the error table, its messages strings and error codes in +.Fa new_table +to the internal error table. +.El +.Sh EXAMPLES +The following is an example using the table defined in +.Xr compile_et 1 : +.Pp +.Bd -literal + #include + #include + #include + + #include "test_err.h" + + void + hook(const char *whoami, long code, + const char *format, va_list args) + { + char buffer[BUFSIZ]; + static int initialized = 0; + + if (!initialized) { + openlog(whoami, LOG_NOWAIT, LOG_DAEMON); + initialized = 1; + } + vsprintf(buffer, format, args); + syslog(LOG_ERR, "%s %s", error_message(code), buffer); + } + + int + main(int argc, char *argv[]) + { + char *whoami = argv[0]; + + initialize_test_error_table(); + com_err(whoami, TEST_INVAL, "before hook"); + set_com_err_hook(hook); + com_err(whoami, TEST_IO, "after hook"); + return (0); + } +.Ed +.Sh SEE ALSO +.Xr compile_et 1 diff --git a/static/netbsd/man3/confstr.3 b/static/netbsd/man3/confstr.3 new file mode 100644 index 00000000..17c5a5e5 --- /dev/null +++ b/static/netbsd/man3/confstr.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: confstr.3,v 1.20 2010/04/22 08:00:34 jruoho Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)confstr.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 22, 2010 +.Dt CONFSTR 3 +.Os +.Sh NAME +.Nm confstr +.Nd get string-valued configurable variables +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft size_t +.Fn confstr "int name" "char *buf" "size_t len" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr sysctl 3 . +.Ef +.Pp +The +.Fn confstr +function provides a method for applications to get configuration +defined string values. +.Pp +The +.Fa name +argument specifies the system variable to be queried. +Symbolic constants for each name value are found in the +.In unistd.h +header. +The +.Fa len +argument specifies the size of the buffer referenced by the +argument +.Fa buf . +If +.Fa len +is non-zero, +.Fa buf +is a non-null pointer, and +.Fa name +has a value, up to +.Fa len +\- 1 bytes of the value are copied into the buffer +.Fa buf . +The copied value is always null terminated. +.Pp +The available values are as follows: +.Pp +.Bl -tag -width "123456" +.It Li _CS_PATH +Return a value for the +.Ev PATH +environment variable that finds all the standard utilities. +.El +.Sh RETURN VALUES +If the call to +.Nm confstr +is not successful, 0 is returned and +.Va errno +is set appropriately. +Otherwise, if the variable does not have a configuration defined value, +0 is returned and +.Va errno +is not modified. +Otherwise, the buffer size needed to hold the entire configuration-defined +value is returned. +If this size is greater than the argument +.Fa len , +the string in +.Fa buf +was truncated. +.Sh ERRORS +The +.Nm confstr +function may fail and set +.Va error +for any of the errors specified for the library functions +.Xr malloc 3 +and +.Xr sysctl 3 . +.Pp +In addition, the following errors may be reported: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa name +argument is invalid. +.El +.Sh SEE ALSO +.Xr sysctl 3 +.Sh STANDARDS +The +.Nm confstr +function conforms to +.St -p1003.2-92 . +.Sh HISTORY +The +.Nm confstr +function first appeared in +.Bx 4.4 . +.Sh BUGS +The standards require us to return 0 both on errors, and when the value +is not set. diff --git a/static/netbsd/man3/conj.3 b/static/netbsd/man3/conj.3 new file mode 100644 index 00000000..1bc43c61 --- /dev/null +++ b/static/netbsd/man3/conj.3 @@ -0,0 +1,45 @@ +.\" $NetBSD: conj.3,v 1.4 2012/12/27 21:34:10 wiz Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd December 27, 2012 +.Dt CONJ 3 +.Os +.Sh NAME +.Nm conj , +.Nm conjf , +.Nm conjl +.Nd complex conjugate functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn conj "double complex z" +.Ft float complex +.Fn conjf "float complex z" +.Ft long double complex +.Fn conjl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex conjugate of +.Ar z , +by reversing the sign of its imaginary part. +.Sh RETURN VALUES +These functions return the complex conjugate value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr carg 3 , +.Xr cimag 3 , +.Xr cproj 3 , +.Xr creal 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/consttime_memequal.3 b/static/netbsd/man3/consttime_memequal.3 new file mode 100644 index 00000000..6af5a101 --- /dev/null +++ b/static/netbsd/man3/consttime_memequal.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: consttime_memequal.3,v 1.5 2015/03/23 07:41:16 apb Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 23, 2015 +.Dt CONSTTIME_MEMEQUAL 3 +.Os +.Sh NAME +.Nm consttime_memequal +.Nd compare byte strings for equality without timing leaks +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn consttime_memequal "void *b1" "void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn consttime_memequal +function compares +.Fa len +bytes of memory at +.Fa b1 +and +.Fa b2 +for equality, returning 0 if they are distinct and 1 if they are +identical. +.Pp +The time taken by +.Fn consttime_memequal +depends on +.Fa len , +but not on the data at +.Fa b1 +or +.Fa b2 . +Thus, +.Fn consttime_memequal +is appropriate for comparing cryptographic secrets, hashes, message +authentication codes, etc., without leaking information about them +through a timing side channel. +In crypto literature, +.Fn consttime_memequal +is said to take +.Sq constant time , +meaning time that does not vary depending on the data it processes. +.Pp +Note that unlike +.Xr memcmp 3 , +.Fn consttime_memequal +does not return a lexicographic ordering on the data at +.Fa b1 +and +.Fa b2 ; +it tells only whether they are equal. +.Nx +does not provide a +.Fn consttime_memcmp +function, because all known use cases that require +.Sq constant time +memory comparison also require only comparison for equality, +not lexicographic ordering. +.Sh SEE ALSO +.Xr explicit_memset 3 , +.Xr memcmp 3 +.Sh HISTORY +The +.Fn consttime_memequal +function appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/copysign.3 b/static/netbsd/man3/copysign.3 new file mode 100644 index 00000000..e8ea10f8 --- /dev/null +++ b/static/netbsd/man3/copysign.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: copysign.3,v 1.4 2017/09/28 15:03:18 maya Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 28, 2017 +.Dt COPYSIGN 3 +.Os +.Sh NAME +.Nm copysign , +.Nm copysignf , +.Nm copysignl +.Nd functions to manipulate signs +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn copysign "double x" "double y" +.Ft float +.Fn copysignf "float x" "float y" +.Ft long double +.Fn copysignl "long double x" "long double y" +.In tgmath.h +.Ft real-floating +.Fn copysign "real-floating x" "real-floating y" +.Sh DESCRIPTION +The +.Fn copysign , +.Fn copysignf , +and +.Fn copysignl +functions return a value whose absolute value matches +.Fa x , +but whose sign bit is taken from +.Fa y . +.Sh RETURN VALUES +Upon successful completion, +all three functions return a value with the magnitude of +.Fa x +and the sign of +.Fa y . +If +.Fa x +is +\*(Na , +the functions return a +\*(Na +with the sign of +.Fa y . +.Sh SEE ALSO +.Xr math 3 , +.Xr signbit 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . +.\" +.\" XXX: Verify this. +.\" +.\" The functions are also recommended by +.\" .St -ieee754 +.\" +.\" .Sh HISTORY +.\" +.\" XXX: Fill this. +.\" +.\" These functions first appeared in ???. +.\" +.Sh CAVEATS +Note that on implementations that represent a signed zero +but do not treat negative zero consistently in arithmetic operations, +these functions may regard the sign of zero as positive. diff --git a/static/netbsd/man3/cos.3 b/static/netbsd/man3/cos.3 new file mode 100644 index 00000000..a9330178 --- /dev/null +++ b/static/netbsd/man3/cos.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)cos.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: cos.3,v 1.17 2019/09/02 00:51:48 sevan Exp $ +.\" +.Dd September 2, 2019 +.Dt COS 3 +.Os +.Sh NAME +.Nm cos , +.Nm cosf , +.Nm cosl +.Nd cosine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn cos "double x" +.Ft float +.Fn cosf "float x" +.Ft long double +.Fn cosl "long double x" +.Sh DESCRIPTION +The +.Fn cos , +.Fn cosf , +and +.Fn cosl +functions compute the cosine of +.Fa x +(measured in radians). +A large magnitude argument may yield a result with little or no +significance. +For a discussion of error due to roundoff, see +.Xr math 3 . +.Sh RETURN VALUES +The +.Fn cos +function returns the cosine value. +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn cos +function conforms to +.St -ansiC . +.Sh HISTORY +A +.Fn cos +function appeared in +.At v1 . diff --git a/static/netbsd/man3/cosh.3 b/static/netbsd/man3/cosh.3 new file mode 100644 index 00000000..eae5fce6 --- /dev/null +++ b/static/netbsd/man3/cosh.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)cosh.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: cosh.3,v 1.17 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd May 2, 1991 +.Dt COSH 3 +.Os +.Sh NAME +.Nm cosh , +.Nm coshf , +.Nm coshl , +.Nd hyperbolic cosine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn cosh "double x" +.Ft float +.Fn coshf "float x" +.Ft long double +.Fn coshl "long double x" +.Sh DESCRIPTION +The +.Fn cosh , +.Fn coshf +and +.Fn coshl +functions compute the hyperbolic cosine of +.Fa x . +.Sh RETURN VALUES +If the magnitude of x is too large, +.Fn cosh "x" +and +.Fn coshf "x" +.\" POSIX_MODE +return Inf and sets the global variable +.Va errno +to +.Er ERANGE . +.\" SYSV_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn cosh +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/cpow.3 b/static/netbsd/man3/cpow.3 new file mode 100644 index 00000000..30c671fa --- /dev/null +++ b/static/netbsd/man3/cpow.3 @@ -0,0 +1,43 @@ +.\" $NetBSD: cpow.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CPOW 3 +.Os +.Sh NAME +.Nm cpow , +.Nm cpowf , +.Nm cpowl +.Nd complex power functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn cpow "double complex x" "double complex y" +.Ft float complex +.Fn cpowf "float complex x" "float complex y" +.Ft long double complex +.Fn cpowl "long double complex x" "long double complex y" +.Sh DESCRIPTION +These functions compute the complex power function x**y, +with a branch cut for the first +parameter along the negative real axis. +.Sh RETURN VALUES +These functions return the complex power function value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cabs 3 , +.Xr csqrt 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cproj.3 b/static/netbsd/man3/cproj.3 new file mode 100644 index 00000000..0a05858d --- /dev/null +++ b/static/netbsd/man3/cproj.3 @@ -0,0 +1,62 @@ +.\" $NetBSD: cproj.3,v 1.5 2017/09/27 09:20:27 maya Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd September 27, 2017 +.Dt CPROJ 3 +.Os +.Sh NAME +.Nm cproj , +.Nm cprojf , +.Nm cprojl +.Nd complex projection functions +.Sh SYNOPSIS +.In complex.h +.Ft double +.Fn cproj "double complex z" +.Ft float +.Fn cprojf "float complex z" +.Ft long double +.Fn cprojl "long double complex z" +.In tgmath.h +.Ft complex-floating +.Fn cproj "complex-floating z" +.Sh DESCRIPTION +These functions compute a projection of +.Ar z +onto the Riemann sphere: +.Ar z +projects to +.Ar z , +except that all complex infinities (even those +with one infinite part and one NaN part) project to positive infinity on the +real axis. +If +.Ar z +has an infinite part, then +.Fn cproj +shall be equivalent to: +.Bd -literal -offset indent +INFINITY + I * copysign(0.0, cimag(z)) +.Ed +.Sh RETURN VALUES +These functions return the value of the projection onto the Riemann sphere. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr carg 3 , +.Xr cimag 3 , +.Xr conj 3 , +.Xr creal 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/cpuset.3 b/static/netbsd/man3/cpuset.3 new file mode 100644 index 00000000..8a329837 --- /dev/null +++ b/static/netbsd/man3/cpuset.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: cpuset.3,v 1.6 2011/11/02 20:25:20 wiz Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius . +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 2, 2011 +.Dt CPUSET 3 +.Os +.Sh NAME +.Nm cpuset_create , +.Nm cpuset_destroy , +.Nm cpuset_zero , +.Nm cpuset_set , +.Nm cpuset_clr , +.Nm cpuset_isset , +.Nm cpuset_size +.Nd dynamic CPU sets +.Sh SYNOPSIS +.In sched.h +.Ft cpuset_t * +.Fn cpuset_create "void" +.Ft void +.Fn cpuset_destroy "cpuset_t *set" +.Ft void +.Fn cpuset_zero "cpuset_t *set" +.Ft int +.Fn cpuset_set "cpuid_t cpu" "cpuset_t *set" +.Ft int +.Fn cpuset_clr "cpuid_t cpu" "cpuset_t *set" +.Ft int +.Fn cpuset_isset "cpuid_t cpu" "const cpuset_t *set" +.Ft size_t +.Fn cpuset_size "const cpuset_t *set" +.Sh DESCRIPTION +This section describes the functions used to create, set, use and destroy +the dynamic CPU sets. +.Pp +This API can be used with the POSIX threads, see +.Xr pthread 3 +and +.Xr affinity 3 . +.Pp +The ID of the primary CPU in the system is 0. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn cpuset_create +Allocates and initializes a clean CPU-set. +Returns the pointer to the CPU-set, or +.Dv NULL +on failure. +.It Fn cpuset_destroy set +Destroy the CPU-set specified by +.Fa set . +.It Fn cpuset_zero set +Makes the CPU-set specified by +.Fa set +clean, that is, memory is initialized to zero bytes, and none of +the CPUs set. +.It Fn cpuset_set cpu set +Sets the CPU specified by +.Fa cpu +in +.Fa set . +Returns zero on success, and \-1 if +.Fa cpu +is invalid. +.It Fn cpuset_clr cpu set +Clears the CPU specified by +.Fa cpu +in the CPU-set +.Fa set . +Returns zero on success, and \-1 if +.Fa cpu +is invalid. +.It Fn cpuset_isset cpu set +Checks if CPU specified by +.Fa cpu +is set in the CPU-set +.Fa set . +Returns the positive number if set, zero if not set, and \-1 if +.Fa cpu +is invalid. +.It Fn cpuset_size set +Returns the size in bytes of CPU-set specified by +.Fa set . +.El +.Sh SEE ALSO +.Xr affinity 3 , +.Xr pset 3 , +.Xr sched 3 , +.Xr schedctl 8 , +.Xr kcpuset 9 +.Sh HISTORY +The dynamic CPU sets appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/creal.3 b/static/netbsd/man3/creal.3 new file mode 100644 index 00000000..87aa3dc9 --- /dev/null +++ b/static/netbsd/man3/creal.3 @@ -0,0 +1,55 @@ +.\" $NetBSD: creal.3,v 1.5 2017/09/27 09:20:27 maya Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd September 27, 2017 +.Dt CREAL 3 +.Os +.Sh NAME +.Nm creal , +.Nm crealf , +.Nm creall +.Nd complex real functions +.Sh SYNOPSIS +.In complex.h +.Ft double +.Fn creal "double complex z" +.Ft float +.Fn crealf "float complex z" +.Ft long double +.Fn creall "long double complex z" +.In tgmath.h +.Ft complex-float +.Fn creal "complex-float z" +.Sh DESCRIPTION +These functions compute the real part of +.Ar z . +.Sh RETURN VALUES +These functions return the real part value. +.Sh ERRORS +No errors are defined. +.Sh APPLICATION USAGE +For a variable +.Ar z +of type +.Vt complex : +.Bd -literal -offset indent +z == creal(z) + cimag(z)*I +.Ed +.Sh SEE ALSO +.Xr carg 3 , +.Xr cimag 3 , +.Xr conj 3 , +.Xr cproj 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/creat.3 b/static/netbsd/man3/creat.3 new file mode 100644 index 00000000..80226de2 --- /dev/null +++ b/static/netbsd/man3/creat.3 @@ -0,0 +1,65 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)creat.2 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: creat.3,v 1.17 2019/09/01 19:28:31 sevan Exp $ +.\" +.Dd September 1, 2019 +.Dt CREAT 3 +.Os +.Sh NAME +.Nm creat +.Nd create a new file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn creat "const char *path" "mode_t mode" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by: +.Ef +.Xr open 2 . +.Pp +.Fn creat +is the same as: +.Bd -literal -offset indent +open(path, O_CREAT | O_TRUNC | O_WRONLY, mode); +.Ed +.Sh SEE ALSO +.Xr open 2 +.Sh STANDARDS +The +.Fn creat +function call conforms to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn creat +function call appeared in +.At v1 . diff --git a/static/netbsd/man3/crypt.3 b/static/netbsd/man3/crypt.3 new file mode 100644 index 00000000..7989a632 --- /dev/null +++ b/static/netbsd/man3/crypt.3 @@ -0,0 +1,529 @@ +.\" $NetBSD: crypt.3,v 1.37 2025/11/17 21:28:37 uwe Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)crypt.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd November 17, 2025 +.Dt CRYPT 3 +.Os +. +.Sh NAME +.Nm crypt , +.Nm setkey , +.Nm encrypt , +.Nm des_setkey , +.Nm des_cipher +.Nd password hashing +. +.Sh LIBRARY +.Lb libcrypt +. +.Sh SYNOPSIS +. +.In unistd.h +. +.Ft "char *" +.Fn crypt "const char *key" "const char *setting" +. +.Ft int +.Fn encrypt "char *block" "int flag" +. +.Ft int +.Fn des_setkey "const char *key" +. +.Ft int +.Fn des_cipher "const char *in" "char *out" "long salt" "int count" +. +.In stdlib.h +. +.Ft int +.Fn setkey "const char *key" +. +.Sh DESCRIPTION +. +The +.Fn crypt +function performs password hashing. +The password hashing scheme used by +.Fn crypt +is dependent upon the contents of the +.Tn NUL Ns -terminated +string +.Fa setting\| : +.Pp +If +.Fa setting +begins with a string character +.Pq Ql $ +then a different algorithm is used depending on the +following characters. +At the moment a +.Ql $1 +chooses MD5 hashing, +.Ql $2 +chooses Blowfish hashing, and +.Ql $argon2d , +.Ql $argon2i , +or +.Ql $argon2id +choose Argon2 hashing. +In either case, the additional parameters for the +hashing algorithm are separated by further +.Ql $ +characters; +see below for more information. +.Pp +If +.Fa setting +begins with the +.Ql _ +character, +.Tn DES +password hashing with a user specified number of +perturbations is selected. +If +.Fa setting +begins with any other character, +.Tn DES +password hashing with a fixed +number of perturbations is selected. +. +.Ss DES password hashing +. +The +.Tn DES +password hashing scheme is derived from the +.Tn NBS +Data Encryption Standard. +Additional code has been added to deter key search attempts and to use +stronger hashing algorithms. +In the +.Tn DES +case, the second argument to +.Fn crypt +is a character array, 9 bytes in length, consisting of an underscore +.Pq Ql _ +followed by 4 bytes of iteration count and 4 bytes of salt. +Both the iteration +.Fa count +and the +.Fa salt +are encoded with 6 bits per character, least significant bits first. +The values 0 to 63 are encoded by the characters +.Ql ./0-9A-Za-z , +respectively. +.Pp +The +.Fa salt +is used to induce disorder in to the +.Tn DES +algorithm in one of 16777216 possible ways +.Po +specifically, if bit +.Em i +of the +.Fa salt +is set then bits +.Em i +and +.Em i+24 +are swapped in the +.Tn DES +.Dq E +box output +.Pc . +The +.Fa key +is divided into groups of 8 characters +.Po +a short final group is +.Tn NUL Ns -padded +.Pc +and the low-order 7 bits of each character +.Pq 56 bits per group +are used to form the +.Tn DES +key as follows: the first group of 56 bits becomes the initial +.Tn DES +key. +For each additional group, the XOR of the group bits and the encryption of the +.Tn DES +key with itself becomes the next +.Tn DES +key. +Then the final +.Tn DES +key is used to perform +.Fa count +cumulative encryptions of a 64-bit constant yielding a +.Dq ciphertext . +The value returned is a +.Tn NUL Ns -terminated +string, 20 bytes in length, consisting of the +.Fa setting +followed by the encoded 64-bit +.Dq ciphertext . +.Pp +For compatibility with historical versions of +.Fn crypt , +the +.Fa setting +may consist of 2 bytes of salt, encoded as above, in which case an +iteration +.Fa count +of 25 is used, fewer perturbations of +.Tn DES +are available, at most 8 characters of +.Fa key +are used, and the returned value is a +.Tn NUL Ns -terminated +string 13 bytes in length. +.Pp +The functions +.Fn encrypt , +.Fn setkey , +.Fn des_setkey +and +.Fn des_cipher +allow limited access to the +.Tn DES +algorithm itself. +The +.Fa key +argument to +.Fn setkey +is a 64 character array of binary values +.Pq numeric 0 or\~1 . +A 56-bit key is derived from this array by dividing the array +into groups of 8 and ignoring the last bit in each group. +.Pp +The +.Fn encrypt +argument +.Fa block +is also a 64 character array of binary values. +If the value of +.Fa flag +is 0, +the argument +.Fa block +is encrypted, otherwise it is decrypted. +The encryption or decryption is returned in the original array +.Fa block +after using the key specified by +.Fn setkey +to process it. +.Pp +The +.Fn des_setkey +and +.Fn des_cipher +functions are faster but less portable than +.Fn setkey +and +.Fn encrypt . +The argument to +.Fn des_setkey +is a character array of length 8. +The +.Em least +significant bit in each character is ignored and the next 7 bits of each +character are concatenated to yield a 56-bit key. +The function +.Fn des_cipher +encrypts +.Po +or decrypts if +.Fa count +is negative +.Pc +the 64-bits stored in the 8 characters at +.Fa in +using +.Xr abs 3 +of +.Fa count +iterations of +.Tn DES +and stores the 64-bit result in the 8 characters at +.Fa out . +The +.Fa salt +specifies perturbations to +.Tn DES +as described above. +. +.Ss MD5 password hashing +. +For the +.Tn MD5 +password hashing scheme, the version number +.Pq in this case Ql 1 +and +.Fa salt +are separated by the +.Ql $ +character and passed to +.Nm +via the +.Fa setting +argument as, e.g., +.Ql $1$2qGr5PPQ . +Only the first 8 characters of the +.Fa salt +are used; any other characters are silently ignored. +. +.Ss Argon2 password hashing +. +Argon2 is a memory-hard password hashing algorithm. +.Fn crypt +provides all three variants: Argon2d, Argon2i, and Argon2id. +It is recommended to use Argon2id, which provides a hybrid combination +using Argon2i on the first pass, and Argon2d on the remaining passes. +We parameterize on three variables, +although four variables separated by +.Ql $ +are specified: +.Pp +The first parameter, +.Va version ( Li v ) , +specifies the version of Argon to be used. +This version is currently fixed per RFC9106 as decimal\~19. +Next, +.Va m_cost ( Li m ) , +specifies the memory usage in +.Tn KB ; +.Va t_cost ( Li t ) , +specifies the number of iterations, and lastly +.Va parallelism ( Li p ) +specifies the number of threads. +This is currently ignored and one thread will always be used. +Following these parameters is the salt. +.Pp +A complete Argon2 +.Fa setting +string might be +.Pp +.Dl $argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB +. +.Ss \(lqBlowfish\(rq bcrypt +. +The Blowfish version of +.Fn crypt +has 128 bits of +.Fa salt +in order to make building dictionaries of common passwords space consuming. +The initial state of the Blowfish cipher is expanded using the +.Fa salt +and the +.Fa password +repeating the process a variable number of rounds, which is encoded in +the password hash. +The maximum password length is 72. +The final Blowfish password output is created by encrypting the string +.Pp +.Dl OrpheanBeholderScryDoubt +.Pp +with the Blowfish state 64 times. +.Pp +The version number, the logarithm of the number of rounds, and +the concatenation of salt and hashed password are separated by the +.Ql $ +character. +Currently, the only supported version number on +.Nx +is +.Ql 2a . +An encoded +.Ql 12 +would specify 4096 rounds. +Only the first 22 characters of the +.Fa salt +are used; any other characters are silently ignored. +.Pp +A complete Blowfish +.Fa setting +string might be +.Pp +.Dl $2a$12$eIAq8PR8sIUnJ1HaohxX2O +. +.Sh RETURN VALUES +. +The function +.Fn crypt +returns a pointer to the encoded hash on success. +.Pp +The behavior of +.Fn crypt +on errors isn't well standardized. +Some implementations simply can't fail +.Po +unless the process dies, in which case they obviously can't return +.Pc , +others return +.Dv NULL +or a fixed string. +Most implementations don't set +.Va errno , +but some do. +.St -susv2 +specifies only returning +.Dv NULL +and setting +.Va errno +as a valid behavior, and defines only one possible error +.Po +.Er ENOSYS , +.Dq The functionality is not supported on this implementation. +.Pc +Unfortunately, most existing applications aren't prepared to handle +.Dv NULL +returns from +.Fn crypt . +The description below corresponds to this implementation of +.Fn crypt +only. +The behavior may change to match standards, other implementations or existing +applications. +.Pp +.Fn crypt +may only fail (and return) when passed an invalid or unsupported +.Fa setting , +in which case it returns a pointer to a magic string that is shorter +than 13 characters and is guaranteed to differ from +.Fa setting . +This behavior is safe for older applications which assume that +.Fn crypt +can't fail, when both setting new passwords and authenticating against +existing password hashes. +.Pp +The functions +.Fn setkey , +.Fn encrypt , +.Fn des_setkey , +and +.Fn des_cipher +return 0 on success and 1 on failure. +Historically, the functions +.Fn setkey +and +.Fn encrypt +did not return any value. +They have been provided return values primarily to distinguish +implementations where hardware support is provided but not +available or where the +.Tn DES +encryption is not available due to the usual political silliness. +. +.Sh SEE ALSO +. +.Xr login 1 , +.Xr passwd 1 , +.Xr pwhash 1 , +.Xr getpass 3 , +.Xr md5 3 , +.Xr passwd 5 , +.Xr passwd.conf 5 +.Rs +.%T "Argon2: the memory-hard function for password hashing and other applications" +.%A Alex Biryukov +.%A Daniel Dinu +.%A Dmitry Khovratovich +.%D 2017 +.%I University of Luxembourg +.%U https://www.password-hashing.net/ +.Re +.Rs +.%T "Mathematical Cryptology for Computer Scientists and Mathematicians" +.%A Wayne Patterson +.%D 1987 +.%N ISBN 0-8476-7438-X +.Re +.Rs +.%T "Password Security: A Case History" +.%A R. Morris +.%A Ken Thompson +.%J "Communications of the ACM" +.%V vol. 22 +.%P pp. 594-597 +.%D Nov. 1979 +.Re +.Rs +.%T "DES will be Totally Insecure within Ten Years" +.%A M.E. Hellman +.%J "IEEE Spectrum" +.%V vol. 16 +.%P pp. 32-39 +.%D July 1979 +.Re +. +.Sh HISTORY +. +A rotor-based +.Fn crypt +function appeared in +.At v6 . +The current style +.Fn crypt +first appeared in +.At v7 . +. +.Sh BUGS +. +Dropping the +.Em least +significant bit in each character of the argument to +.Fn des_setkey +is ridiculous. +.Pp +The +.Fn crypt +function leaves its result in an internal static object and returns +a pointer to that object. +Subsequent calls to +.Fn crypt +will modify the same object. +.Pp +Before +.Nx 6.0 +.Fn crypt +returned either +.Dv NULL +or +.Li \*q:\*q +on error. +.Pp +The term +.Dq encryption +for password hashing does not match the terminology of modern +cryptography, but the name of the library is entrenched. +.Pp +A library for password hashing has no business directly exposing the +.Tn DES +cipher itself, which is obsolete and broken as a cipher. diff --git a/static/netbsd/man3/crypto.3 b/static/netbsd/man3/crypto.3 new file mode 100644 index 00000000..dcd4b1b7 --- /dev/null +++ b/static/netbsd/man3/crypto.3 @@ -0,0 +1,207 @@ +.\" $NetBSD: crypto.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "crypto 3" +.TH crypto 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +crypto \- OpenSSL cryptographic library +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL \fBcrypto\fR library implements a wide range of cryptographic +algorithms used in various Internet standards. The services provided +by this library are used by the OpenSSL implementations of \s-1SSL, TLS\s0 +and S/MIME, and they have also been used to implement \s-1SSH,\s0 OpenPGP, and +other cryptographic standards. +.SH "OVERVIEW" +.IX Header "OVERVIEW" +\&\fBlibcrypto\fR consists of a number of sub-libraries that implement the +individual algorithms. +.PP +The functionality includes symmetric encryption, public key +cryptography and key agreement, certificate handling, cryptographic +hash functions and a cryptographic pseudo-random number generator. +.IP "\s-1SYMMETRIC CIPHERS\s0" 4 +.IX Item "SYMMETRIC CIPHERS" +\&\fIopenssl_blowfish\fR\|(3), \fIcast\fR\|(3), \fIopenssl_des\fR\|(3), +\&\fIidea\fR\|(3), \fIrc2\fR\|(3), \fIopenssl_rc4\fR\|(3), \fIrc5\fR\|(3) +.IP "\s-1PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT\s0" 4 +.IX Item "PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT" +\&\fIopenssl_dsa\fR\|(3), \fIopenssl_dh\fR\|(3), \fIopenssl_rsa\fR\|(3) +.IP "\s-1CERTIFICATES\s0" 4 +.IX Item "CERTIFICATES" +\&\fIx509\fR\|(3), \fIx509v3\fR\|(3) +.IP "\s-1AUTHENTICATION CODES, HASH FUNCTIONS\s0" 4 +.IX Item "AUTHENTICATION CODES, HASH FUNCTIONS" +\&\fIopenssl_hmac\fR\|(3), \fImd2\fR\|(3), \fImd4\fR\|(3), +\&\fIopenssl_md5\fR\|(3), \fIopenssl_mdc2\fR\|(3), \fIopenssl_ripemd\fR\|(3), +\&\fIopenssl_sha\fR\|(3) +.IP "\s-1AUXILIARY FUNCTIONS\s0" 4 +.IX Item "AUXILIARY FUNCTIONS" +\&\fIopenssl_err\fR\|(3), \fIopenssl_threads\fR\|(3), \fIopenssl_rand\fR\|(3), +\&\s-1\fIOPENSSL_VERSION_NUMBER\s0\fR\|(3) +.IP "\s-1INPUT/OUTPUT, DATA ENCODING\s0" 4 +.IX Item "INPUT/OUTPUT, DATA ENCODING" +\&\fIasn1\fR\|(3), \fIopenssl_bio\fR\|(3), \fIopenssl_evp\fR\|(3), \fIpem\fR\|(3), +\&\fIpkcs7\fR\|(3), \fIpkcs12\fR\|(3) +.IP "\s-1INTERNAL FUNCTIONS\s0" 4 +.IX Item "INTERNAL FUNCTIONS" +\&\fIopenssl_bn\fR\|(3), \fIopenssl_buffer\fR\|(3), \fIec\fR\|(3), \fIopenssl_lhash\fR\|(3), +\&\fIobjects\fR\|(3), \fIstack\fR\|(3), +\&\fItxt_db\fR\|(3) +.SH "NOTES" +.IX Header "NOTES" +Some of the newer functions follow a naming convention using the numbers +\&\fB0\fR and \fB1\fR. For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj); +.Ve +.PP +The \fB0\fR version uses the supplied structure pointer directly +in the parent and it will be freed up when the parent is freed. +In the above example \fBcrl\fR would be freed but \fBrev\fR would not. +.PP +The \fB1\fR function uses a copy of the supplied structure pointer +(or in some cases increases its link count) in the parent and +so both (\fBx\fR and \fBobj\fR above) should be freed up. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl\fR\|(1), \fIssl\fR\|(3) diff --git a/static/netbsd/man3/csh.3 b/static/netbsd/man3/csh.3 new file mode 100644 index 00000000..a6a6f66e --- /dev/null +++ b/static/netbsd/man3/csh.3 @@ -0,0 +1,648 @@ +.\" $NetBSD: csh.3,v 1.5 2003/08/07 09:05:08 agc Exp $ +.\" +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)csh.3 8.1 (Berkeley) 6/8/93 +.\" +.nr H1 2 +.NH +Shell control structures and command scripts +.NH 2 +Introduction +.PP +It is possible to place commands in files and to cause shells to be +invoked to read and execute commands from these files, +which are called +.I "shell scripts." +We here detail those features of the shell useful to the writers of such +scripts. +.NH 2 +Make +.PP +It is important to first note what shell scripts are +.I not +useful for. +There is a program called +.I make +which is very useful for maintaining a group of related files +or performing sets of operations on related files. +For instance a large program consisting of one or more files +can have its dependencies described in a +.I makefile +which contains definitions of the commands used to create these +different files when changes occur. +Definitions of the means for printing listings, cleaning up the directory +in which the files reside, and installing the resultant programs +are easily, and most appropriately placed in this +.I makefile. +This format is superior and preferable to maintaining a group of shell +procedures to maintain these files. +.PP +Similarly when working on a document a +.I makefile +may be created which defines how different versions of the document +are to be created and which options of +.I nroff +or +.I troff +are appropriate. +.NH 2 +Invocation and the argv variable +.PP +A +.I csh +command script may be interpreted by saying +.DS +% csh script ... +.DE +where +.I script +is the name of the file containing a group of +.I csh +commands and +`\&...' is replaced by a sequence of arguments. +The shell places these arguments in the variable +.I argv +and then begins to read commands from the script. +These parameters are then available through the same mechanisms +which are used to reference any other shell variables. +.PP +If you make the file +`script' +executable by doing +.DS +chmod 755 script +.DE +and place a shell comment at the beginning of the shell script +(i.e. begin the file with a `#' character) +then a `/bin/csh' will automatically be invoked to execute `script' when +you type +.DS +script +.DE +If the file does not begin with a `#' then the standard shell +`/bin/sh' will be used to execute it. +This allows you to convert your older shell scripts to use +.I csh +at your convenience. +.NH 2 +Variable substitution +.PP +After each input line is broken into words and history substitutions +are done on it, the input line is parsed into distinct commands. +Before each command is executed a mechanism know as +.I "variable substitution" +is done on these words. +Keyed by the character `$' this substitution replaces the names +of variables by their values. +Thus +.DS +echo $argv +.DE +when placed in a command script would cause the current value of the +variable +.I argv +to be echoed to the output of the shell script. +It is an error for +.I argv +to be unset at this point. +.PP +A number of notations are provided for accessing components and attributes +of variables. +The notation +.DS +$?name +.DE +expands to `1' if name is +.I set +or to `0' +if name is not +.I set. +It is the fundamental mechanism used for checking whether particular +variables have been assigned values. +All other forms of reference to undefined variables cause errors. +.PP +The notation +.DS +$#name +.DE +expands to the number of elements in the variable +.I name. +Thus +.DS +% set argv=(a b c) +% echo $?argv +1 +% echo $#argv +3 +% unset argv +% echo $?argv +0 +% echo $argv +Undefined variable: argv. +% +.DE +.PP +It is also possible to access the components of a variable +which has several values. +Thus +.DS +$argv[1] +.DE +gives the first component of +.I argv +or in the example above `a'. +Similarly +.DS +$argv[$#argv] +.DE +would give `c', +and +.DS +$argv[1\-2] +.DE +would give `a b'. Other notations useful in shell scripts are +.DS +$\fIn\fR +.DE +where +.I n +is an integer as a shorthand for +.DS +$argv[\fIn\fR\|] +.DE +the +.I n\|th +parameter and +.DS +$* +.DE +which is a shorthand for +.DS +$argv +.DE +The form +.DS +$$ +.DE +expands to the process number of the current shell. +Since this process number is unique in the system it can +be used in generation of unique temporary file names. +The form +.DS +$< +.DE +is quite special and is replaced by the next line of input read from +the shell's standard input (not the script it is reading). This is +useful for writing shell scripts that are interactive, reading +commands from the terminal, or even writing a shell script that +acts as a filter, reading lines from its input file. Thus the sequence +.DS +echo 'yes or no?\ec' +set a=($<) +.DE +would write out the prompt `yes or no?' without a newline and then +read the answer into the variable `a'. In this case `$#a' would be +`0' if either a blank line or end-of-file (^D) was typed. +.PP +One minor difference between `$\fIn\fR\|' and `$argv[\fIn\fR\|]' +should be noted here. +The form +`$argv[\fIn\fR\|]' +will yield an error if +.I n +is not in the range +`1\-$#argv' +while `$n' +will never yield an out of range subscript error. +This is for compatibility with the way older shells handled parameters. +.PP +Another important point is that it is never an error to give a subrange +of the form `n\-'; if there are less than +.I n +components of the given variable then no words are substituted. +A range of the form `m\-n' likewise returns an empty vector without giving +an error when \fIm\fR exceeds the number of elements of the given variable, +provided the subscript \fIn\fR is in range. +.NH 2 +Expressions +.PP +In order for interesting shell scripts to be constructed it +must be possible to evaluate expressions in the shell based on the +values of variables. +In fact, all the arithmetic operations of the language C are available +in the shell +with the same precedence that they have in C. +In particular, the operations `==' and `!=' compare strings +and the operators `&&' and `|\|\||' implement the boolean and/or operations. +The special operators `=~' and `!~' are similar to `==' and `!=' except +that the string on the right side can have pattern matching characters +(like *, ? or []) and the test is whether the string on the left matches +the pattern on the right. +.PP +The shell also allows file enquiries of the form +.DS +\-? filename +.DE +where `?' is replace by a number of single characters. +For instance the expression primitive +.DS +\-e filename +.DE +tell whether the file +`filename' +exists. +Other primitives test for read, write and execute access to the file, +whether it is a directory, or has non-zero length. +.PP +It is possible to test whether a command terminates normally, +by a primitive of the +form `{ command }' which returns true, i.e. `1' if the command +succeeds exiting normally with exit status 0, or `0' if the command +terminates abnormally or with exit status non-zero. +If more detailed information about the execution status of a command +is required, it can be executed and the variable `$status' examined +in the next command. +Since `$status' is set by every command, it is very transient. +It can be saved if it is inconvenient to use it only in the single +immediately following command. +.PP +For a full list of expression components available see the manual +section for the shell. +.NH 2 +Sample shell script +.PP +A sample shell script which makes use of the expression mechanism +of the shell and some of its control structure follows: +.DS +% cat copyc +# +# Copyc copies those C programs in the specified list +# to the directory ~/backup if they differ from the files +# already in ~/backup +# +set noglob +foreach i ($argv) + + if ($i !~ *.c) continue # not a .c file so do nothing + + if (! \-r ~/backup/$i:t) then + echo $i:t not in backup... not cp\e\'ed + continue + endif + + cmp \-s $i ~/backup/$i:t # to set $status + + if ($status != 0) then + echo new backup of $i + cp $i ~/backup/$i:t + endif +end +.DE +.PP +This script makes use of the +.I foreach +command, which causes the shell to execute the commands between the +.I foreach +and the matching +.I end +for each of the values given between `(' and `)' with the named +variable, in this case `i' set to successive values in the list. +Within this loop we may use the command +.I break +to stop executing the loop +and +.I continue +to prematurely terminate one iteration +and begin the next. +After the +.I foreach +loop the iteration variable +(\fIi\fR in this case) +has the value at the last iteration. +.PP +We set the variable +.I noglob +here to prevent filename expansion of the members of +.I argv. +This is a good idea, in general, if the arguments to a shell script +are filenames which have already been expanded or if the arguments +may contain filename expansion metacharacters. +It is also possible to quote each use of a `$' variable expansion, +but this is harder and less reliable. +.PP +The other control construct used here is a statement of the form +.DS +\fBif\fR ( expression ) \fBthen\fR + command + ... +\fBendif\fR +.DE +The placement of the keywords here is +.B not +flexible due to the current implementation of the shell.\(dg +.FS +\(dgThe following two formats are not currently acceptable to the shell: +.sp +.in +5 +.nf +\fBif\fR ( expression ) # \fBWon't work!\fR +\fBthen\fR + command + ... +\fBendif\fR +.fi +.in -5 +.sp +and +.sp +.in +5 +.nf +\fBif\fR ( expression ) \fBthen\fR command \fBendif\fR # \fBWon't work\fR +.in -5 +.fi +.FE +.PP +The shell does have another form of the if statement of the form +.DS +\fBif\fR ( expression ) \fBcommand\fR +.DE +which can be written +.DS +\fBif\fR ( expression ) \e + command +.DE +Here we have escaped the newline for the sake of appearance. +The command must not involve `\||\|', `&' or `;' +and must not be another control command. +The second form requires the final `\e' to +.B immediately +precede the end-of-line. +.PP +The more general +.I if +statements above also admit a sequence of +.I else\-if +pairs followed by a single +.I else +and an +.I endif, +e.g.: +.DS +\fBif\fR ( expression ) \fBthen\fR + commands +\fBelse\fR \fBif\fR (expression ) \fBthen\fR + commands +\&... + +\fBelse\fR + commands +\fBendif\fR +.DE +.PP +Another important mechanism used in shell scripts is the `:' modifier. +We can use the modifier `:r' here to extract a root of a filename or +`:e' to extract the +.I extension. +Thus if the variable +.I i +has the value +`/mnt/foo.bar' +then +.sp +.in +5 +.nf +% echo $i $i:r $i:e +/mnt/foo.bar /mnt/foo bar +% +.sp +.in -5 +.fi +shows how the `:r' modifier strips off the trailing `.bar' and the +the `:e' modifier leaves only the `bar'. +Other modifiers will take off the last component of a pathname leaving +the head `:h' or all but the last component of a pathname leaving the +tail `:t'. +These modifiers are fully described in the +.I csh +manual pages in the User's Reference Manual. +It is also possible to use the +.I "command substitution" +mechanism described in the next major section to perform modifications +on strings to then reenter the shell's environment. +Since each usage of this mechanism involves the creation of a new process, +it is much more expensive to use than the `:' modification mechanism.\(dd +.FS +\(dd It is also important to note that +the current implementation of the shell limits the number of `:' modifiers +on a `$' substitution to 1. +Thus +.sp +.nf +.in +5 +% echo $i $i:h:t +/a/b/c /a/b:t +% +.in -5 +.fi +.sp +does not do what one would expect. +.FE +Finally, we note that the character `#' lexically introduces a shell +comment in shell scripts (but not from the terminal). +All subsequent characters on the input line after a `#' are discarded +by the shell. +This character can be quoted using `\'' or `\e' to place it in +an argument word. +.NH 2 +Other control structures +.PP +The shell also has control structures +.I while +and +.I switch +similar to those of C. +These take the forms +.DS +\fBwhile\fR ( expression ) + commands +\fBend\fR +.DE +and +.DS +\fBswitch\fR ( word ) + +\fBcase\fR str1: + commands + \fBbreaksw\fR + +\& ... + +\fBcase\fR strn: + commands + \fBbreaksw\fR + +\fBdefault:\fR + commands + \fBbreaksw\fR + +\fBendsw\fR +.DE +For details see the manual section for +.I csh. +C programmers should note that we use +.I breaksw +to exit from a +.I switch +while +.I break +exits a +.I while +or +.I foreach +loop. +A common mistake to make in +.I csh +scripts is to use +.I break +rather than +.I breaksw +in switches. +.PP +Finally, +.I csh +allows a +.I goto +statement, with labels looking like they do in C, i.e.: +.DS +loop: + commands + \fBgoto\fR loop +.DE +.NH 2 +Supplying input to commands +.PP +Commands run from shell scripts receive by default the standard +input of the shell which is running the script. +This is different from previous shells running +under \s-2UNIX\s0. It allows shell scripts to fully participate +in pipelines, but mandates extra notation for commands which are to take +inline data. +.PP +Thus we need a metanotation for supplying inline data to commands in +shell scripts. +As an example, consider this script which runs the editor to +delete leading blanks from the lines in each argument file: +.DS +% cat deblank +# deblank \-\- remove leading blanks +foreach i ($argv) +ed \- $i << \'EOF\' +1,$s/^[ ]*// +w +q +\&\'EOF\' +end +% +.DE +The notation `<< \'EOF\'' +means that the standard input for the +.I ed +command is to come from the text in the shell script file +up to the next line consisting of exactly `\'EOF\''. +The fact that the `EOF' is enclosed in `\'' characters, i.e. quoted, +causes the shell to not perform variable substitution on the +intervening lines. +In general, if any part of the word following the `<<' which the +shell uses to terminate the text to be given to the command is quoted +then these substitutions will not be performed. +In this case since we used the form `1,$' in our editor script +we needed to insure that this `$' was not variable substituted. +We could also have insured this by preceding the `$' here with a `\e', +i.e.: +.DS +1,\e$s/^[ ]*// +.DE +but quoting the `EOF' terminator is a more reliable way of achieving the +same thing. +.NH 2 +Catching interrupts +.PP +If our shell script creates temporary files, we may wish to catch +interruptions of the shell script so that we can clean up +these files. +We can then do +.DS +onintr label +.DE +where +.I label +is a label in our program. +If an interrupt is received the shell will do a +`goto label' +and we can remove the temporary files and then do an +.I exit +command (which is built in to the shell) +to exit from the shell script. +If we wish to exit with a non-zero status we can do +.DS +exit(1) +.DE +e.g. to exit with status `1'. +.NH 2 +What else? +.PP +There are other features of the shell useful to writers of shell +procedures. +The +.I verbose +and +.I echo +options and the related +.I \-v +and +.I \-x +command line options can be used to help trace the actions of the shell. +The +.I \-n +option causes the shell only to read commands and not to execute +them and may sometimes be of use. +.PP +One other thing to note is that +.I csh +will not execute shell scripts which do not begin with the +character `#', that is shell scripts that do not begin with a comment. +Similarly, the `/bin/sh' on your system may well defer to `csh' +to interpret shell scripts which begin with `#'. +This allows shell scripts for both shells to live in harmony. +.PP +There is also another quotation mechanism using `"' which allows +only some of the expansion mechanisms we have so far discussed to occur +on the quoted string and serves to make this string into a single word +as `\'' does. +.bp diff --git a/static/netbsd/man3/csin.3 b/static/netbsd/man3/csin.3 new file mode 100644 index 00000000..377f518b --- /dev/null +++ b/static/netbsd/man3/csin.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: csin.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CSIN 3 +.Os +.Sh NAME +.Nm csin , +.Nm csinf , +.Nm csinl +.Nd complex sine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn csin "double complex z" +.Ft float complex +.Fn csinf "float complex z" +.Ft long double complex +.Fn csinl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex sine of +.Ar z . +.Sh RETURN VALUES +These functions return the complex sine value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr casin 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/csinh.3 b/static/netbsd/man3/csinh.3 new file mode 100644 index 00000000..9e4dc219 --- /dev/null +++ b/static/netbsd/man3/csinh.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: csinh.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CSINH 3 +.Os +.Sh NAME +.Nm csinh , +.Nm csinhf , +.Nm csinhl +.Nd complex hyperbolic sine functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn csinh "double complex z" +.Ft float complex +.Fn csinhf "float complex z" +.Ft long double complex +.Fn csinhl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex hyperbolic sine of +.Ar z . +.Sh RETURN VALUES +These functions return the complex hyperbolic sine value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr casinh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/csqrt.3 b/static/netbsd/man3/csqrt.3 new file mode 100644 index 00000000..ecba1791 --- /dev/null +++ b/static/netbsd/man3/csqrt.3 @@ -0,0 +1,44 @@ +.\" $NetBSD: csqrt.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CSQRT 3 +.Os +.Sh NAME +.Nm csqrt , +.Nm csqrtf , +.Nm csqrtl +.Nd complex square root functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn csqrt "double complex z" +.Ft float complex +.Fn csqrtf "float complex z" +.Ft long double complex +.Fn csqrtl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex square root of +.Ar z , +with a branch cut along the negative real axis. +.Sh RETURN VALUES +These functions return the complex square root value, in the +range of the right half-plane (including the imaginary axis). +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr cabs 3 , +.Xr cpow 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/ctan.3 b/static/netbsd/man3/ctan.3 new file mode 100644 index 00000000..b988d5bf --- /dev/null +++ b/static/netbsd/man3/ctan.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: ctan.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CTAN 3 +.Os +.Sh NAME +.Nm ctan , +.Nm ctanf , +.Nm ctanl +.Nd complex tangent functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn ctan "double complex z" +.Ft float complex +.Fn ctanf "float complex z" +.Ft long double complex +.Fn ctanl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex tangent of +.Ar z . +.Sh RETURN VALUES +These functions return the complex tangent value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr catan 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/ctanh.3 b/static/netbsd/man3/ctanh.3 new file mode 100644 index 00000000..c4ff01cb --- /dev/null +++ b/static/netbsd/man3/ctanh.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: ctanh.3,v 1.3 2013/01/29 02:05:09 matt Exp $ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.Dd January 29, 2013 +.Dt CTANH 3 +.Os +.Sh NAME +.Nm ctanh , +.Nm ctanhf , +.Nm ctanhl +.Nd complex hyperbolic tangent functions +.Sh SYNOPSIS +.In complex.h +.Ft double complex +.Fn ctanh "double complex z" +.Ft float complex +.Fn ctanhf "float complex z" +.Ft long double complex +.Fn ctanhl "long double complex z" +.Sh DESCRIPTION +These functions compute the complex hyperbolic tangent of +.Ar z . +.Sh RETURN VALUES +These functions return the complex hyperbolic tangent value. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr catanh 3 , +.St -p1003.1-2001 +.Aq Pa complex.h +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/ctermid.3 b/static/netbsd/man3/ctermid.3 new file mode 100644 index 00000000..b167392b --- /dev/null +++ b/static/netbsd/man3/ctermid.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: ctermid.3,v 1.11 2010/03/22 19:30:53 joerg Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ctermid.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt CTERMID 3 +.Os +.Sh NAME +.Nm ctermid +.Nd generate terminal pathname +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn ctermid "char *buf" +.Sh DESCRIPTION +The +.Fn ctermid +function generates a string, that, when used as a pathname, refers to +the current controlling terminal of the calling process. +.Pp +If +.Ar buf +is the +.Dv NULL +pointer, a pointer to a static area is returned. +Otherwise, the pathname is copied into the memory referenced by +.Ar buf . +The argument +.Ar buf +is assumed to point to an array at least +.Dv L_ctermid +bytes long (as defined in the include file +.In stdio.h ) . +.Pp +The current implementation simply returns +.Ql /dev/tty . +.Sh RETURN VALUES +Upon successful completion, a +.Pf non- Dv NULL +pointer is returned. +Otherwise, a +.Dv NULL +pointer is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The current implementation detects no error conditions. +.Sh SEE ALSO +.Xr ttyname 3 +.Sh STANDARDS +The +.Fn ctermid +function conforms to +.St -p1003.1-90 . +.Sh BUGS +By default the +.Fn ctermid +function writes all information to an internal static object. +Subsequent calls to +.Fn ctermid +will modify the same object. diff --git a/static/netbsd/man3/ctime.3 b/static/netbsd/man3/ctime.3 new file mode 100644 index 00000000..98bf59e7 --- /dev/null +++ b/static/netbsd/man3/ctime.3 @@ -0,0 +1,650 @@ +.\" $NetBSD: ctime.3,v 1.74 2026/03/08 21:04:54 christos Exp $ +.\" +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.\" +.Dd March 8, 2026 +.Dt CTIME 3 +.Os +.Sh NAME +.Nm asctime , +.Nm asctime_r , +.Nm ctime , +.Nm ctime_r , +.Nm ctime_rz , +.Nm difftime , +.Nm gmtime , +.Nm gmtime_r , +.Nm localtime , +.Nm localtime_r , +.Nm localtime_rz , +.Nm mktime , +.Nm mktime_z +.Nd convert date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Vt extern char *tzname[2]; +.Ft [[deprecated]] char * +.Fn asctime "const struct tm *tm" +.Ft [[only in POSIX.1-2017 and earlier]] char * +.Fn asctime_r "const struct tm *restrict tm" "char * restrict buf" +.Ft [[deprecated]] char * +.Fn ctime "const time_t *clock" +.Ft [[only in POSIX.1-2017 and earlier]] char * +.Fn ctime_r "const time_t *clock" "char *buf" +.Ft char * +.Fn ctime_rz "timezone_t restrict tz" "const time_t *clock" "char *buf" +.Ft double +.Fn difftime "time_t time1" "time_t time0" +.Ft struct tm * +.Fn gmtime "const time_t *clock" +.Ft struct tm * +.Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result" +.Ft struct tm * +.Fn localtime "const time_t *clock" +.Ft struct tm * +.Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result" +.Ft struct tm * +.Fn localtime_rz "timezone_t restrict tz" "const time_t * restrict clock" "struct tm * restrict result" +.Ft time_t +.Fn mktime "struct tm *tm" +.Ft time_t +.Fn mktime_z "timezone_t restrict tz" "struct tm *restrict tm" +.Sh DESCRIPTION +The +.Nm +family of functions provide various standard library routines +to operate with time and conversions related to time. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn asctime "tm" +The +.Fn asctime +function converts a time value contained in the +.Fa tm +structure to a string with the following general format: +.Bd -literal -offset indent +Thu Nov 24 18:22:48 1986\en\e0 +.Ed +Years requiring fewer than four characters are padded with leading zeroes. +For years longer than four characters, the string is of the form: +.Bd -literal -offset indent +Thu Nov 24 18:22:48 81986\n\0 +.Ed +with five spaces before the year. +This unusual format is designed to make it less likely that older +software that expects exactly 26 bytes of output will mistakenly output +misleading values for out-of-range years. +This function is deprecated starting in C23. +Callers can use +.Fn strftime +instead. +.Pp +The +.Fa tm +structure is described in +.Xr tm 3 . +.Pp +This function is deprecated starting in C23. +Callers can use +.Fn strftime +instead. +.It Fn asctime_r "tm" "buf" +The +.Fn asctime_r +has the same behavior as +.Fn asctime , +but the result is stored in +.Fa buf , +which should have a size of at least 26 bytes. +.It Fn ctime "clock" +The +.Fn ctime +function converts a +.Vt time_t , +pointed to by +.Fa clock , +and returns a pointer to a string with the format described above. +Years requiring fewer than four characters are padded with leading zeroes. +For years longer than four characters, the string is of the form +.Bd -literal -offset indent +Thu Nov 24 18:22:48 81986\en\e0 +.Ed +.Pp +with five spaces before the year. +These unusual formats are designed to make it less likely that older +software that expects exactly 26 bytes of output will mistakenly output +misleading values for out-of-range years. +.Pp +The +.Fa clock +time stamp represents the time in seconds since 1970-01-01 00:00:00 +Coordinated Universal Time (UTC). +The POSIX standard says that time stamps must be nonnegative +and must ignore leap seconds. +Many implementations extend POSIX by allowing negative time stamps, +and can therefore represent time stamps that predate the +introduction of UTC and are some other flavor of Universal Time (UT). +Some implementations support leap seconds, in contradiction to POSIX. +.Pp +The +.Fn ctime +function is deprecated starting in C23. +Callers can use +.Fn localtime_r +and +.Fn strftime +instead. +.It Fn ctime_r "clock" "buf" +The +.Fn ctime_r +is similar to +.Fn ctime , +except it places the result of the conversion in the +.Fa buf +argument, which should be 26 or more bytes long, +instead of using a global static buffer. +.It Fn ctime_rz "tz" "clock" "buf" +The +.Fn ctime_rz +function is similar to +.Fn ctime_r , +but it also takes a +.Ft "timezone_t" +argument, as returned by a previous call to +.Fn tzalloc , +or a +.Dv NULL +pointer denoting +Coordinated Universal Time +.Pq UTC . +.It Fn difftime "time1" "time2" +The +.Fn difftime +function returns the difference between two calendar times, +.Fa ( time1 No - Fa time0 ) , +expressed in seconds. +.It Fn gmtime "clock" +The +.Fn gmtime +functions +convert an integer, pointed to by +.Fa clock , +to Coordinated Universal Time +.Pq UTC +and returns a pointer to the +.Va tm +structure described in +.Xr tm 3 . +.It Fn gmtime_r "clock" "result" +The +.Fn gmtime_r +function provides the same functionality as +.Fn gmtime , +differing in that the caller must supply a buffer area +.Fa result +in which the result is stored. +If the integer is out of range for conversion, +these functions return a null pointer. +.It Fn localtime "clock" +Also +.Fn localtime +is comparable to +.Fn gmtime . +However, +.Fn localtime +corrects for the timezone and any timezone adjustments +(such as Daylight Saving Time in the U.S.A.). +After filling in the +.Va tm +structure, the function sets the +.Fa tm_isdst Ns 'th +element of +.Fa tzname +to a pointer to an +ASCII string that is the timezone abbreviation to be used with +.Fn localtime Ns 's +return value. +.It Fn localtime_r "clock" "result" +As +.Fn gmtime_r , +the +.Fn localtime_r +takes an additional buffer +.Fa result +as a parameter and stores the result in it. +Note however that +.Fn localtime_r +does not imply initialization of the local time conversion information; +the application may need to do so by calling +.Xr tzset 3 . +.It Fn localtime_rz "tz" "clock" "result" +The +.Fn localtime_rz +function is similar to +.Fn localtime_r , +but it also takes a +.Ft "timezone_t" +argument, returned by a previous call to +.Fn tzalloc , +or a +.Dv NULL +pointer denoting Coordinated Universal Time +.Pq UTC . +.It Fn mktime "tm" +The +.Fn mktime +function converts the broken-down time, +expressed as local time in the +.Xr tm 3 +structure, into a calendar time value with +the same encoding as that of the values returned by the +.Xr time 3 +function. +The following remarks should be taken into account. +.Bl -bullet +.It +The original values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are ignored, +and the original values of the other components are not restricted +to their normal ranges and will be normalized, +if need be. +.Pp +For example, +consider a +.Fa struct tm +initialized with +.Fa tm_year += 122, +.Fa tm_mon += 10, +.Fa tm_mday += 30, +.Fa tm_hour += 22, +.Fa tm_min += 57, +and +.Fa tm_sec += 0. +Incrementing +.Fa tm_min +by 13 and calling +.Fn mktime +would lead to +.Fa tm_hour += 23 and +.Fa tm_min += 10. +.Pp +This normalizing can lead to cascading changes: +Again using a +.Fa struct tm +initialized as in the above example but with +.Fa tm_hour += 23, +the same change would lead to +.Fa tm_mon += 11, +.Fa tm_mday += 1, +.Fa tm_hour += 0, and +.Fa tm_min += 10. +.Pp +Negative values may also be normalized with similar +cascading effect such that e.g., +a +.Fa tm_hour +of \-1 means 1 hour before midnight on the previous +day and so on. +.It +A positive or zero value for +.Fa tm_isdst +causes +.Fn mktime +to presume initially that daylight saving time +respectively, +is or is not in effect for the specified time. +.It +A negative value for +.Fa tm_isdst +causes the +.Fn mktime +function to attempt to divine whether daylight saving time is in effect +for the specified time; in this case it does not use a consistent +rule and may give a different answer when later +presented with the same argument. +.It +On successful completion, the values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are set appropriately, +and the other components are set to represent the specified calendar time, +but with their values forced to their normal ranges; the final value of +.Fa tm_mday +is not set until +.Fa tm_mon +and +.Fa tm_year +are determined. +.El +.Pp +The function returns the specified calendar time; +if the calendar time cannot be represented, it returns +.Va "(time_t)\-1" . +This can happen either because the resulting conversion would not fit +in a +.Vt time_t +variable, or because the time specified happens to be in the daylight +savings gap and +.Fa tm_isdst +was set to +.Dv \-1 . +Other +.Fn mktime +implementations do not return an error in the second case and return +the appropriate time offset after the daylight savings gap. +There is code to mimick this behavior, but it is not enabled by default. +.It Fn mktime_z "tz" "tm" +The +.Fn mktime_z +function is similar to +.Fn mktime +but it also takes a +.Ft "const timezone_t" +argument, returned by a previous call to +.Fn tzalloc , +or a null pointer denoting +Coordinated Universal Time +.Pq UTC . +.El +.Pp +Declarations of all the functions and externals, and the +.Ft tm +structure, are in the +.In time.h +header file. +The structure (of type) +.Ft struct tm +includes the following fields: +.Bd -literal + int tm_sec; /* seconds (0 - 60) */ + int tm_min; /* minutes (0 - 59) */ + int tm_hour; /* hours (0 - 23) */ + int tm_mday; /* day of month (1 - 31) */ + int tm_mon; /* month of year (0 - 11) */ + int tm_year; /* year - 1900 */ + int tm_wday; /* day of week (Sunday = 0) */ + int tm_yday; /* day of year (0 - 365) */ + int tm_isdst; /* is daylight saving time in effect? */ + char *tm_zone; /* abbreviation of timezone name (optional) */ + long tm_gmtoff; /* offset from UT in seconds (optional) */ +.Ed +.Bl -bullet +.It +.Va tm_isdst +is non-zero if daylight saving time is in effect. +.It +.Va tm_gmtoff +is the offset (in seconds) of the time represented from UT, +with positive values indicating east of the Prime Meridian. +The field's name is derived from Greenwich Mean Time, a precursor of UT. +.El +In +.Ft struct tm +the +.Fa tm_zone +and +.Fa tm_gmtoff +fields exist, and are filled in, only if arrangements to do +so were made when the library containing these functions was +created. +Similarly, the +.Va tzname +variable is optional; also, there is no guarantee that +.Dv tzname +will +continue to exist in this form in future releases of this code. +.Pp +The +.Fn ctime_r , +.Fn localtime_r , +.Fn gmtime_r , +and +.Fn asctime_r +functions +are like their unsuffixed counterparts, except that they accept an +additional argument specifying where to store the result if successful. +.Pp +The +.Fn ctime_rz , +.Fn localtime_rz , +and +.Fn mktime_z +functions +are like their unsuffixed counterparts, except that they accept an +extra initial +.Ar zone +argument specifying the timezone to be used for conversion. +If +.Fa zone +is +.Dv NULL , +UT is used; otherwise, +.Fa zone +should have been allocated by +.Fn tzalloc +and should not be freed until after all uses (e.g., by calls to +.Fn strftime ) +of the filled-in +.Fn tm_zone +fields. +.Sh RETURN VALUES +.Bl -bullet +.It +On success the +.Fn asctime +and +.Fn ctime +functions return a pointer to a static character buffer, and the +.Fn asctime_r , +.Fn ctime_r , +and +.Fn ctime_rz +function return a pointer to the user-supplied buffer. +On failure they all return +.Dv NULL +and no errors are defined for them. +.It +On success the +.Fn gmtime , +and +.Fn localtime +functions return a pointer to a statically allocated +.Va "struct tm" +whereas the +.Fn gmtime_r , +.Fn localtime_r , +and +.Fn localtime_rz , +functions return a pointer to the user-supplied +.Va "struct tm" . +On failure they all return +.Dv NULL +and the global variable +.Va errno +is set to indicate the error. +.It +The +.Fn mktime +and +.Fn mktime_z +function returns the specified time since the Epoch as a +.Vt time_t +type value. +If the time cannot be represented, then +.Fn mktime +and +.Fn mktime_z +return +.Va "(time_t)-1" +setting the global variable +.Va errno +to indicate the error. +.It +The +.Fn tzalloc +function returns a pointer to a +.Ft timezone_t +object or +.Dv NULL +on failure, setting +.Va errno +to indicate the error. +It may also return +.Dv NULL +when the +.Fa name +argument is +.Dv NULL , +and this is not an error, but a way of referring to +Coordinated Universal Time +.Pq UTC . +.It +.Fn tzgetzone +function returns string containing the name of the timezone given in +.Fa tz . +.El +.Sh FILES +.Bl -tag -width /usr/share/zoneinfo/localtime -compact +.It Pa /etc/localtime +local timezone file +.It Pa /usr/share/zoneinfo +timezone information directory +.It Pa /usr/share/zoneinfo/localtime +local timezone file +.It Pa /usr/share/zoneinfo/GMT +for UTC leap seconds +.El +.Pp +If +.Pa /usr/share/zoneinfo/GMT +is absent, UTC leap seconds are loaded from +.Pa /usr/share/zoneinfo/posixrules . +.Sh ERRORS +The described functions may fail with +.Bl -tag -width Er +.It Bq Er EINVAL +The result cannot be represented because a parameter is incorrect, or +the conversion failed because no such time exists (for example a time +in the DST gap). +.It Bq Er EOVERFLOW +The result cannot be represented because the time requested is out of bounds +and the time calculation resulted in overflow. +.El +.Pp +All functions that return values, except their +.Dq z +variants, can also return the same errors as +.Xr open 2 +and +.Xr malloc 3 . +.Sh SEE ALSO +.Xr getenv 3 , +.Xr strftime 3 , +.Xr time 3 , +.Xr tm 3 , +.Xr tzset 3 , +.Xr tzfile 5 +.Sh STANDARDS +The +.Fn ctime , +.Fn difftime , +.Fn asctime , +.Fn localtime , +.Fn gmtime +and +.Fn mktime +functions conform to +.St -ansiC . +Rest of the functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +A +.Fn ctime +function appeared in +.At v1 . +.Sh CAVEATS +The functions that do not take an explicit +.Ft timezone_t +argument return values pointing to static data; the data is overwritten by +each call. +For the above functions the +.Dv tzname +variable (once set) and the +.Fa tm_zone +field of a returned +.Va "struct tm" +point to an array of characters that +can be freed or overwritten by later calls to the functions +.Fn localtime , +.Fn tzfree , +and +.Fn tzset , +if these functions affect the timezone information that specifies the +abbreviation in question. +The remaining functions and data are thread-safe. +The functions that do take an explicit +.Ft timezone_t +argument and set the fields of a supplied +.Va "struct tm" +should not call +.Fn tzfree +since the +.Fa tm_zone +field of the +.Va "struct tm" +points to data allocated by +.Fn tzalloc . +.Pp +The +.Fn asctime , +.Fn asctime_r , +.Fn ctime , +.Fn ctime_r , +and +.Fn ctime_rz , +functions behave strangely for years before 1000 or after 9999. +The 1989 and 1999 editions of the C Standard say +that years from \-99 through 999 are converted without +extra spaces, but this conflicts with longstanding +tradition and with this implementation. +The 2011 edition says that the behavior +is undefined if the year is before 1000 or after 9999. +Traditional implementations of these two functions are +restricted to years in the range 1900 through 2099. +To avoid this portability mess, new programs should use +.Fn strftime +instead. +.Pp +The +.Fa clock +timestamp represents the time in seconds since 1970-01-01 00:00:00 +Coordinated Universal Time +.Pq UTC . +The POSIX standard says that timestamps must be nonnegative +and must ignore leap seconds. +Many implementations extend POSIX by allowing negative timestamps, +and can therefore represent timestamps that predate the +introduction of UTC and are some other flavor of Universal Time +.Pq UT . +Some implementations support leap seconds, in contradiction to POSIX. +.\" 2009-05-17 by Arthur David Olson. diff --git a/static/netbsd/man3/ctype.3 b/static/netbsd/man3/ctype.3 new file mode 100644 index 00000000..0286714d --- /dev/null +++ b/static/netbsd/man3/ctype.3 @@ -0,0 +1,229 @@ +.\" $NetBSD: ctype.3,v 1.35 2025/10/05 00:35:47 riastradh Exp $ +.\" +.\" Copyright (c) 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ctype.3 6.5 (Berkeley) 4/19/91 +.\" +.Dd September 14, 2025 +.Dt CTYPE 3 +.Os +.Sh NAME +.Nm ctype +.Nd character classification and mapping functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Fn isalpha "int c" +.Fn isupper "int c" +.Fn islower "int c" +.Fn isdigit "int c" +.Fn isxdigit "int c" +.Fn isalnum "int c" +.Fn isspace "int c" +.Fn ispunct "int c" +.Fn isprint "int c" +.Fn isgraph "int c" +.Fn iscntrl "int c" +.Fn isblank "int c" +.Fn toupper "int c" +.Fn tolower "int c" +.Sh DESCRIPTION +The above functions perform character tests and conversions on the integer +.Ar c . +.Pp +See the specific manual pages for information about the +test or conversion performed by each function. +.Sh ENVIRONMENT +In +.Nx 11 , +the +.Nm +functions will always crash with a signal on certain invalid inputs as +a diagnostic aid for applications; see +.Sx CAVEATS . +Setting the environment variable +.Ev LIBC_ALLOWCTYPEABUSE +before starting a program will restore the old behavior of returning +nonsense answers for these inputs, or sometimes but not always +crashing, depending on factors such as address space layout +randomization. +.Sh EXAMPLES +To print an upper-case version of a string to stdout, +the following code can be used: +.Bd -literal -offset indent +const char *s = "xyz"; + +while (*s != '\e0') { + putchar(toupper((unsigned char)*s)); + s++; +} +.Ed +.Sh SEE ALSO +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +These functions, with the exception of +.Fn isblank , +conform to +.St -ansiC . +All described functions, including +.Fn isblank , +also conform to +.St -p1003.1-2001 . +.Sh CAVEATS +The argument of these functions is of type +.Vt int , +but only a very restricted subset of values are actually valid. +The argument must either be the value of the macro +.Dv EOF +(which has a negative value), +or must be a non-negative value within the range representable as +.Vt unsigned char . +Passing invalid values leads to undefined behavior. +.Pp +Values of type +.Vt int +that were returned by +.Xr getc 3 , +.Xr fgetc 3 , +and similar functions or macros +are already in the correct range, and may be safely passed to these +.Nm ctype +functions without any casts. +.Pp +Values of type +.Vt char +or +.Vt signed char +must first be cast to +.Vt unsigned char , +to ensure that the values are within the correct range. +Casting a negative-valued +.Vt char +or +.Vt signed char +directly to +.Vt int +will produce a negative-valued +.Vt int , +which will be outside the range of allowed values +(unless it happens to be equal to +.Dv EOF , +but even that would not give the desired result). +.Pp +Because the bugs may manifest as silent misbehavior or as crashes only +when fed input outside the US-ASCII range, the +.Nx +implementation of the +.Nm +functions is designed to elicit a compiler warning for code that passes +inputs of type +.Vt char +in order to flag code that may pass negative values at runtime that +would lead to undefined behavior: +.Bd -literal -offset indent +#include +#include +#include + +int +main(int argc, char **argv) +{ + + if (argc < 2) + return 1; + setlocale(LC_ALL, ""); + + printf(" char=%-4d isprint? %d\en", + (int)*argv[1], + isprint(*argv[1]) ? 1 : 0); + printf("u_char=%-4d isprint? %d\en", + (int)(unsigned char)*argv[1], + isprint((unsigned char)*argv[1]) ? 1 : 0); + return 0; +} +.Ed +.Pp +When compiling this program, GCC reports a warning for the line that +passes +.Vt char . +At runtime, you may get nonsense answers for some inputs without the +cast \(em if you're lucky and it doesn't crash: +.Bd -literal +% gcc -Wall -o test test.c +In file included from /usr/include/ctype.h:100, + from test.c:1: +test.c: In function 'main': +test.c:15:21: warning: array subscript has type 'char' [-Wchar-subscripts] + 15 | isprint(*argv[1]) ? 1 : 0); + | ^ +% LC_CTYPE=C ./test $(printf '\e270') + char=-72 isprint? 1 +u_char=184 isprint? 0 +% LC_CTYPE=C ./test $(printf '\e377') + char=-1 isprint? 0 +u_char=255 isprint? 0 +% LC_CTYPE=fr_FR.ISO8859-1 ./test $(printf '\e377') + char=-1 isprint? 0 +u_char=255 isprint? 1 +.Ed +.Pp +Some implementations of libc, such as glibc as of 2018, hide the +undefined behavior by defining the functions to work for all integer +inputs representable by either +.Vt unsigned char +or +.Vt char , +and suppress the warning. +However, this is not an excuse for avoiding conversion to +.Vt unsigned char : +if +.Dv EOF +coincides with any such value, as it does when it is \-1 on platforms +with signed +.Vt char , +programs that pass +.Vt char +will still necessarily confuse the classification and mapping of +.Dv EOF +with the classification and mapping of some non-EOF inputs. diff --git a/static/netbsd/man3/curses.3 b/static/netbsd/man3/curses.3 new file mode 100644 index 00000000..1569455c --- /dev/null +++ b/static/netbsd/man3/curses.3 @@ -0,0 +1,379 @@ +.\" $NetBSD: curses.3,v 1.74 2019/09/02 09:08:29 roy Exp $ +.\" +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)curses.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd August 29, 2019 +.Dt CURSES 3 +.Os +.Sh NAME +.Nm curses +.Nd screen functions with +.Dq optimal +cursor motion +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.Nm cc +.Op Ar flags +.Ar files +.Fl lcurses +.Op Ar libraries +.Sh DESCRIPTION +These routines give the user a method of updating screens with reasonable +optimization. +They keep an image of the current screen, +and the user sets up an image of a new one. +Then the +.Fn refresh +tells the routines to make the current screen look like the new one. +In order to initialize the routines, the routine +.Fn initscr +must be called before any of the other routines that deal with windows and +screens are used. +The routine +.Fn endwin +should be called before exiting. +The routine +.Fn start_color +must be called before any of the other routines that deal with color are used. +.Sh FUNCTIONS +.Bl -column "subwin(win,lines,cols,begin_y,begin_x)" +.It Sy "Function Name" Ta Sy "Manual Page Name" +.It addch Ta Xr curses_addch 3 +.It addchnstr Ta Xr curses_addchstr 3 +.It addchstr Ta Xr curses_addchstr 3 +.It addnstr Ta Xr curses_addstr 3 +.It addstr Ta Xr curses_addstr 3 +.It assume_default_colors Ta Xr curses_default_colors 3 +.It attr_get Ta Xr curses_attributes 3 +.It attr_off Ta Xr curses_attributes 3 +.It attr_on Ta Xr curses_attributes 3 +.It attr_set Ta Xr curses_attributes 3 +.It attroff Ta Xr curses_attributes 3 +.It attron Ta Xr curses_attributes 3 +.It attrset Ta Xr curses_attributes 3 +.It baudrate Ta Xr curses_tty 3 +.It beep Ta Xr curses_tty 3 +.It bkgd Ta Xr curses_background 3 +.It bkgdset Ta Xr curses_background 3 +.It border Ta Xr curses_border 3 +.It box Ta Xr curses_border 3 +.It can_change_color Ta Xr curses_color 3 +.It cbreak Ta Xr curses_tty 3 +.It chgat Ta Xr curses_chgat 3 +.It clear Ta Xr curses_clear 3 +.It clearok Ta Xr curses_clear 3 +.It clrtobot Ta Xr curses_clear 3 +.It clrtoeol Ta Xr curses_clear 3 +.It color_content Ta Xr curses_color 3 +.It color_set Ta Xr curses_attributes 3 +.It copywin Ta Xr curses_window 3 +.It curs_set Ta Xr curses_tty 3 +.It curses_version Ta Xr curses_version 3 +.It def_prog_mode Ta Xr curses_tty 3 +.It def_shell_mode Ta Xr curses_tty 3 +.It define_key Ta Xr curses_input 3 +.It delay_output Ta Xr curses_tty 3 +.It delch Ta Xr curses_delch 3 +.It deleteln Ta Xr curses_deleteln 3 +.It delscreen Ta Xr curses_screen 3 +.It delwin Ta Xr curses_window 3 +.It derwin Ta Xr curses_window 3 +.It doupdate Ta Xr curses_refresh 3 +.It dupwin Ta Xr curses_window 3 +.It echo Ta Xr curses_tty 3 +.It endwin Ta Xr curses_screen 3 +.It erase Ta Xr curses_clear 3 +.It erasechar Ta Xr curses_tty 3 +.It filter Ta Xr curses_screen 3 +.It flash Ta Xr curses_tty 3 +.It flushinp Ta Xr curses_tty 3 +.It flushok Ta Xr curses_refresh 3 +.It fullname Ta Xr curses_termcap 3 +.It getattrs Ta Xr curses_attributes 3 +.It getbegx Ta Xr curses_cursor 3 +.It getbegy Ta Xr curses_cursor 3 +.It getbkgd Ta Xr curses_background 3 +.It getch Ta Xr curses_input 3 +.It getcurx Ta Xr curses_cursor 3 +.It getcury Ta Xr curses_cursor 3 +.It getmaxx Ta Xr curses_cursor 3 +.It getmaxy Ta Xr curses_cursor 3 +.It getnstr Ta Xr curses_input 3 +.It getparx Ta Xr curses_cursor 3 +.It getpary Ta Xr curses_cursor 3 +.It getparyx Ta Xr curses_cursor 3 +.It getstr Ta Xr curses_input 3 +.It gettmode Ta Xr curses_tty 3 +.It getwin Ta Xr curses_fileio 3 +.It getyx Ta Xr curses_cursor 3 +.It has_colors Ta Xr curses_color 3 +.It has_ic Ta Xr curses_tty 3 +.It has_il Ta Xr curses_tty 3 +.It has_key Ta Xr curses_input 3 +.It hline Ta Xr curses_line 3 +.It idcok Ta Xr curses_tty 3 +.It idlok Ta Xr curses_tty 3 +.It immedok Ta Xr curses_refresh 3 +.It inch Ta Xr curses_inch 3 +.It inchnstr Ta Xr curses_inch 3 +.It inchstr Ta Xr curses_inch 3 +.It init_color Ta Xr curses_color 3 +.It init_pair Ta Xr curses_color 3 +.It initscr Ta Xr curses_screen 3 +.It innstr Ta Xr curses_inch 3 +.It insch Ta Xr curses_insch 3 +.It insdelln Ta Xr curses_insdelln 3 +.It insertln Ta Xr curses_insertln 3 +.It instr Ta Xr curses_inch 3 +.It intrflush Ta Xr curses_tty 3 +.It is_keypad Ta Xr curses_input 3 +.It is_leaveok Ta Xr curses_refresh 3 +.It is_linetouched Ta Xr curses_touch 3 +.It is_pad Ta Xr curses_pad 3 +.It is_term_resized Ta Xr curses_screen 3 +.It is_wintouched Ta Xr curses_touch 3 +.It isendwin Ta Xr curses_screen 3 +.It keyname Ta Xr curses_keyname 3 +.It keyok Ta Xr curses_input 3 +.It keypad Ta Xr curses_input 3 +.It killchar Ta Xr curses_tty 3 +.It leaveok Ta Xr curses_tty 3 +.It meta Ta Xr curses_tty 3 +.It move Ta Xr curses_cursor 3 +.It mvaddch Ta Xr curses_addch 3 +.It mvaddchnstr Ta Xr curses_addchstr 3 +.It mvaddchstr Ta Xr curses_addchstr 3 +.It mvaddnstr Ta Xr curses_addstr 3 +.It mvaddstr Ta Xr curses_addstr 3 +.It mvchgat Ta Xr curses_chgat 3 +.It mvcur Ta Xr curses_cursor 3 +.It mvderwin Ta Xr curses_window 3 +.It mvgetnstr Ta Xr curses_input 3 +.It mvgetstr Ta Xr curses_input 3 +.It mvhline Ta Xr curses_line 3 +.It mvinchstr Ta Xr curses_inch 3 +.It mvinchnstr Ta Xr curses_inch 3 +.It mvinsch Ta Xr curses_insch 3 +.It mvprintw Ta Xr curses_print 3 +.It mvscanw Ta Xr curses_scanw 3 +.It mvvline Ta Xr curses_line 3 +.It mvwaddch Ta Xr curses_addch 3 +.It mvwaddchnstr Ta Xr curses_addchstr 3 +.It mvwaddchstr Ta Xr curses_addchstr 3 +.It mvwaddnstr Ta Xr curses_addstr 3 +.It mvwaddstr Ta Xr curses_addstr 3 +.It mvwchgat Ta Xr curses_chgat 3 +.It mvwgetnstr Ta Xr curses_input 3 +.It mvwgetstr Ta Xr curses_input 3 +.It mvwhline Ta Xr curses_line 3 +.It mvwinchstr Ta Xr curses_inch 3 +.It mvwinchnstr Ta Xr curses_inch 3 +.It mvwinsch Ta Xr curses_insch 3 +.It mvwprintw Ta Xr curses_print 3 +.It mvwscanw Ta Xr curses_scanw 3 +.It mvwvline Ta Xr curses_line 3 +.It napms Ta Xr curses_tty 3 +.It newpad Ta Xr curses_pad 3 +.It newterm Ta Xr curses_screen 3 +.It newwin Ta Xr curses_window 3 +.It \&nl Ta Xr curses_tty 3 +.It nocbreak Ta Xr curses_tty 3 +.It nodelay Ta Xr curses_input 3 +.It noecho Ta Xr curses_tty 3 +.It nonl Ta Xr curses_tty 3 +.It noqiflush Ta Xr curses_tty 3 +.It noraw Ta Xr curses_tty 3 +.It notimeout Ta Xr curses_input 3 +.It overlay Ta Xr curses_window 3 +.It overwrite Ta Xr curses_window 3 +.It pair_content Ta Xr curses_color 3 +.It pnoutrefresh Ta Xr curses_pad 3 +.It prefresh Ta Xr curses_pad 3 +.It printw Ta Xr curses_print 3 +.It putwin Ta Xr curses_fileio 3 +.It qiflush Ta Xr curses_tty 3 +.It raw Ta Xr curses_tty 3 +.It redrawwin Ta Xr curses_touch 3 +.It refresh Ta Xr curses_refresh 3 +.It reset_prog_mode Ta Xr curses_tty 3 +.It reset_shell_mode Ta Xr curses_tty 3 +.It resetty Ta Xr curses_tty 3 +.It resize_term Ta Xr curses_screen 3 +.It resizeterm Ta Xr curses_screen 3 +.It ripoffline Ta Xr curses_screen 3 +.It savetty Ta Xr curses_tty 3 +.It scanw Ta Xr curses_scanw 3 +.It scrl Ta Xr curses_scroll 3 +.It scroll Ta Xr curses_scroll 3 +.It scrollok Ta Xr curses_scroll 3 +.It set_escdelay Ta Xr curses_input 3 +.It set_tabsize Ta Xr curses_screen 3 +.It set_term Ta Xr curses_screen 3 +.It setscrreg Ta Xr curses_scroll 3 +.It setterm Ta Xr curses_screen 3 +.It slk_attroff Ta Xr curses_slk 3 +.It slk_attr_off Ta Xr curses_slk 3 +.It slk_attron Ta Xr curses_slk 3 +.It slk_attr_on Ta Xr curses_slk 3 +.It slk_attrset Ta Xr curses_slk 3 +.It slk_attr_set Ta Xr curses_slk 3 +.It slk_clear Ta Xr curses_slk 3 +.It slk_color Ta Xr curses_slk 3 +.It slk_init Ta Xr curses_slk 3 +.It slk_label Ta Xr curses_slk 3 +.It slk_noutrefresh Ta Xr curses_slk 3 +.It slk_refresh Ta Xr curses_slk 3 +.It slk_restore Ta Xr curses_slk 3 +.It slk_set Ta Xr curses_slk 3 +.It slk_touch Ta Xr curses_slk 3 +.It slk_wset Ta Xr curses_slk 3 +.It standend Ta Xr curses_standout 3 +.It standout Ta Xr curses_standout 3 +.It start_color Ta Xr curses_color 3 +.It syncok Ta Xr curses_touch 3 +.It subpad Ta Xr curses_pad 3 +.It subwin Ta Xr curses_window 3 +.It termattrs Ta Xr curses_attributes 3 +.It timeout Ta Xr curses_input 3 +.It touchline Ta Xr curses_touch 3 +.It touchoverlap Ta Xr curses_touch 3 +.It touchwin Ta Xr curses_touch 3 +.It typeahead Ta Xr curses_tty 3 +.It unctrl Ta Xr curses_print 3 +.It underend Ta Xr curses_underscore 3 +.It underscore Ta Xr curses_underscore 3 +.It ungetch Ta Xr curses_input 3 +.It untouchwin Ta Xr curses_touch 3 +.It use_default_colors Ta Xr curses_default_colors 3 +.It use_env Ta Xr curses_screen 3 +.It vline Ta Xr curses_line 3 +.It waddch Ta Xr curses_addch 3 +.It waddchnstr Ta Xr curses_addchstr 3 +.It waddchstr Ta Xr curses_addchstr 3 +.It waddnstr Ta Xr curses_addstr 3 +.It waddstr Ta Xr curses_addstr 3 +.It wattr_get Ta Xr curses_attributes 3 +.It wattr_off Ta Xr curses_attributes 3 +.It wattr_on Ta Xr curses_attributes 3 +.It wattr_set Ta Xr curses_attributes 3 +.It wattroff Ta Xr curses_attributes 3 +.It wattron Ta Xr curses_attributes 3 +.It wattrset Ta Xr curses_attributes 3 +.It wbkgd Ta Xr curses_background 3 +.It wbkgdset Ta Xr curses_background 3 +.It wborder Ta Xr curses_border 3 +.It wchgat Ta Xr curses_chgat 3 +.It wclear Ta Xr curses_clear 3 +.It wclrtobot Ta Xr curses_clear 3 +.It wclrtoeol Ta Xr curses_clear 3 +.It wcolor_set Ta Xr curses_attributes 3 +.It wcursyncup Ta Xr curses_cursor 3 +.It wdelch Ta Xr curses_delch 3 +.It wdeleteln Ta Xr curses_deleteln 3 +.It werase Ta Xr curses_clear 3 +.It wgetch Ta Xr curses_input 3 +.It wgetnstr Ta Xr curses_input 3 +.It wgetstr Ta Xr curses_input 3 +.It whline Ta Xr curses_line 3 +.It winch Ta Xr curses_inch 3 +.It winchnstr Ta Xr curses_inch 3 +.It winchstr Ta Xr curses_inch 3 +.It winnstr Ta Xr curses_inch 3 +.It winsch Ta Xr curses_insch 3 +.It winsdelln Ta Xr curses_insdelln 3 +.It winsertln Ta Xr curses_insertln 3 +.It winstr Ta Xr curses_inch 3 +.It wmove Ta Xr curses_cursor 3 +.It wnoutrefresh Ta Xr curses_refresh 3 +.It wprintw Ta Xr curses_print 3 +.It wredrawln Ta Xr curses_touch 3 +.It wrefresh Ta Xr curses_refresh 3 +.It wresize Ta Xr curses_window 3 +.It wscanw Ta Xr curses_scanw 3 +.It wscrl Ta Xr curses_scroll 3 +.It wsetscrreg Ta Xr curses_scroll 3 +.It wstandend Ta Xr curses_standout 3 +.It wstandout Ta Xr curses_standout 3 +.It wsyncup Ta Xr curses_touch 3 +.It wsyncdown Ta Xr curses_touch 3 +.It wtimeout Ta Xr curses_input 3 +.It wtouchln Ta Xr curses_touch 3 +.It wunderend Ta Xr curses_underscore 3 +.It wunderscore Ta Xr curses_underscore 3 +.It wvline Ta Xr curses_line 3 +.El +.Sh ENVIRONMENT +.Bl -tag -width CURSES_TRACE_MASK +.It Ev COLUMNS +The number of columns in the terminal if set. +This is usually automatically configured by querying the kernel. +.It Ev CURSES_TRACE_MASK +An integer mask that enables specific debugging traces. +Enabled only in the debug build of curses. +.It Ev CURSES_TRACE_FILE +A file where to output debugging information. +Enabled only in the debug build of curses. +.It Ev ESCDELAY +The maximum delay in milliseconds between characters in multi-character +keystrokes (such are arrow keys) where the adjacent characters are considered +part of the same multi-character sequence. +The default is 300 milliseconds. +.It Ev LINES +The number of lines in the terminal if set. +is usually automatically configured by querying the kernel. +.It Ev TABSIZE +The number of spaces making up a tab. +The default is 8 if not specified by the terminal description. +.It Ev TERM +The terminal type of the current terminal. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr getenv 3 , +.Xr tty 4 , +.Xr terminfo 5 +.Rs +.%T Screen Updating and Cursor Movement Optimization: A Library Package +.%A Ken Arnold +.Re +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +.Sh AUTHORS +.An Ken Arnold +.An Julian Coleman +.An Brett Lymn +.An Roy Marples diff --git a/static/netbsd/man3/curses_addch.3 b/static/netbsd/man3/curses_addch.3 new file mode 100644 index 00000000..2fc2bf99 --- /dev/null +++ b/static/netbsd/man3/curses_addch.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: curses_addch.3,v 1.11 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 25, 2018 +.Dt CURSES_ADDCH 3 +.Os +.Sh NAME +.Nm curses_addch , +.Nm addch , +.Nm waddch , +.Nm mvaddch , +.Nm mvwaddch +.Nd curses add characters to windows routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn addch "chtype ch" +.Ft int +.Fn waddch "WINDOW *win" "chtype ch" +.Ft int +.Fn mvaddch "int y" "int x" "chtype ch" +.Ft int +.Fn mvwaddch "WINDOW *win" "int y" "int x" "chtype ch" +.Sh DESCRIPTION +These functions add characters to +.Va stdscr +or to the specified window. +.Pp +The +.Fn addch +function adds the character given in +.Fa ch +to +.Va stdscr +at the current cursor position and advances the current cursor position by one. +Any character attributes set in +.Fa ch +will be merged with the background attributes currently set on +.Va stdscr . +.Pp +The +.Fn waddch +function is the same as the +.Fn addch +function, excepting that the character is added to the window specified by +.Fa win . +.Pp +The +.Fn mvaddch +and +.Fn mvwaddch +functions are the same as the +.Fn addch +and +.Fn waddch +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the character is added to the window. +.Ss LINE DRAWING CHARACTERS +Some terminals support the display of line drawing and graphics characters. +These characters can be added using their defined names, as shown in the +table below. +Where the terminal does not support a specific character, the default +(non-graphics) character is displayed instead. +.Bl -column -offset indent ".Sy System V Name" ".Sy Default" +.It Sy "Name" Ta Sy "Default" Ta Sy "Description" +.It ACS_RARROW Ta > Ta "Arrow pointing right" +.It ACS_LARROW Ta < Ta "Arrow pointing left" +.It ACS_UARROW Ta ^ Ta "Arrow pointing up" +.It ACS_DARROW Ta v Ta "Arrow pointing down" +.It ACS_BLOCK Ta # Ta "Solid square block" +.It ACS_DIAMOND Ta + Ta "Diamond" +.It ACS_CKBOARD Ta : Ta "Checker board (stipple)" +.It ACS_DEGREE Ta ' Ta "Degree symbol" +.It ACS_PLMINUS Ta # Ta "Plus/minus" +.It ACS_BOARD Ta # Ta "Board of squares" +.It ACS_LANTERN Ta # Ta "Lantern symbol" +.It ACS_LRCORNER Ta + Ta "Lower right-hand corner" +.It ACS_URCORNER Ta + Ta "Upper right-hand corner" +.It ACS_ULCORNER Ta + Ta "Upper left-hand corner" +.It ACS_LLCORNER Ta + Ta "Lower left-hand corner" +.It ACS_PLUS Ta + Ta "Plus" +.It ACS_HLINE Ta - Ta "Horizontal line" +.It ACS_S1 Ta - Ta "Scan line 1" +.It ACS_S9 Ta - Ta "Scan line 9" +.It ACS_LTEE Ta + Ta "Left tee" +.It ACS_RTEE Ta + Ta "Right tee" +.It ACS_BTEE Ta + Ta "Bottom tee" +.It ACS_TTEE Ta + Ta "Top tee" +.It ACS_VLINE Ta | Ta "Vertical line" +.It ACS_BULLET Ta o Ta "Bullet" +.El +.Pp +The following additional, +.Em ncurses +compatible, characters are also supported. +.Bl -column -offset indent ".Sy System V Name" ".Sy Default" +.It Sy "Name" Ta Sy "Default" Ta Sy "Description" +.It ACS_S3 Ta - Ta "Scan line 3" +.It ACS_S7 Ta - Ta "Scan line 7" +.It ACS_LEQUAL Ta < Ta "Less than or equal to" +.It ACS_GEQUAL Ta > Ta "Greater than or equal to" +.It ACS_PI Ta * Ta "Pi symbol" +.It ACS_NEQUAL Ta ! Ta "Not equal to" +.It ACS_STERLING Ta f Ta "Sterling symbol" +.El +.Pp +For compatibility with some +.Em System V +implementations, the following definitions are also supported. +.Bl -column -offset indent ".Sy System V Name" ".Sy Default" +.It Sy "System V Name" Ta Sy "NetBSD Curses Name" +.It ACS_SBBS Ta ACS_LRCORNER +.It ACS_BBSS Ta ACS_URCORNER +.It ACS_BSSB Ta ACS_ULCORNER +.It ACS_SSBB Ta ACS_LLCORNER +.It ACS_SSSS Ta ACS_PLUS +.It ACS_BSBS Ta ACS_HLINE +.It ACS_SSSB Ta ACS_LTEE +.It ACS_SBSS Ta ACS_RTEE +.It ACS_SSBS Ta ACS_BTEE +.It ACS_BSSS Ta ACS_TTEE +.It ACS_SBSB Ta ACS_VLINE +.El +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addchstr 3 , +.Xr curses_addstr 3 , +.Xr curses_attributes 3 , +.Xr curses_cursor 3 , +.Xr curses_delch 3 , +.Xr curses_inch 3 , +.Xr curses_insch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_addchstr.3 b/static/netbsd/man3/curses_addchstr.3 new file mode 100644 index 00000000..f784352d --- /dev/null +++ b/static/netbsd/man3/curses_addchstr.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: curses_addchstr.3,v 1.4 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2003 +.\" Douwe Kiela (virtus@wanadoo.nl) +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Douwe Kiela (virtus@wanadoo.nl). +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd May 21, 2003 +.Dt CURSES_ADDCHSTR 3 +.Os +.Sh NAME +.Nm curses_addchstr , +.Nm addchstr , +.Nm waddchstr , +.Nm addchnstr , +.Nm waddchnstr , +.Nm mvaddchstr , +.Nm mvwaddchstr , +.Nm mvaddchnstr , +.Nm mvwaddchnstr +.Nd curses add character strings to windows routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn addchstr "const chtype *chstr" +.Ft int +.Fn waddchstr "WINDOW *win" "const chtype *chstr" +.Ft int +.Fn mvaddchstr "int y" "int x" "const chtype *chstr" +.Ft int +.Fn mvwaddchstr "WINDOW *win" "int y" "int x" "const chtype *chstr" +.Ft int +.Fn addchnstr "const chtype *chstr" "int n" +.Ft int +.Fn waddchnstr "WINDOW *win" "const chtype *chstr" "int n" +.Ft int +.Fn mvaddchnstr "int y" "int x" "const chtype *chstr" "int n" +.Ft int +.Fn mvwaddchnstr "WINDOW *win" "int y" "int x" "const chtype *chstr" "int n" +.Sh DESCRIPTION +These functions add character strings and attributes to +.Va stdscr +or to the specified window. +.Pp +The +.Fn addchstr +function will add the characters and their attributes passed in +.Fa chstr +to +.Va stdscr +starting at the current cursor position. +Any character attributes set in +.Fa chstr +will be merged with the background attributes currently set on +.Va stdscr . +The +.Fn waddstr +function does the same as +.Fn addchstr +but adds the string to the window specified by +.Fn win . +.Pp +The +.Fn addchnstr +function will add the contents of +.Fa string +to +.Va stdscr +but will limit the number of characters added to be, at most, +.Fa n . +If +.Fa n +is \-1 then +.Fa addchnstr +will add the number of characters contained in the null terminated string +.Fa chstr . +Any character attributes set in +.Fa chstr +will be merged with the background attributes currently set on +.Va stdscr . +.Pp +The +.Fn waddchnstr +function does the same as +.Fa addchnstr +but adds the string to the window specified by +.Fa win . +.Pp +The functions +.Fn mvaddchstr , +.Fn mwaddchnstr , +.Fn mvwaddchstr +and +.Fn mvwaddchnstr +are the same as the functions +.Fn addchstr , +.Fn waddchstr , +.Fn waddchstr +and +.Fn waddchnstr , +respectively, except that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the string is added to the window. +.Sh RETURN VALUES +The functions will return one of the following values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_addstr 3 , +.Xr curses_attributes 3 , +.Xr curses_cursor 3 , +.Xr curses_inch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +These functions first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/curses_addstr.3 b/static/netbsd/man3/curses_addstr.3 new file mode 100644 index 00000000..38ea9b31 --- /dev/null +++ b/static/netbsd/man3/curses_addstr.3 @@ -0,0 +1,183 @@ +.\" $NetBSD: curses_addstr.3,v 1.8 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd July 28, 2019 +.Dt CURSES_ADDSTR 3 +.Os +.Sh NAME +.Nm curses_addstr , +.Nm addstr , +.Nm addwstr , +.Nm waddstr , +.Nm waddwstr , +.Nm addnstr , +.Nm addnwstr , +.Nm waddnstr , +.Nm waddnwstr , +.Nm mvaddstr , +.Nm mvaddwstr , +.Nm mvwaddstr , +.Nm mvwaddwstr , +.Nm mvaddnstr , +.Nm mvaddnwstr , +.Nm mvwaddnstr , +.Nm mvwaddnwstr +.Nd curses add character strings to windows routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn addstr "const char *string" +.Ft int +.Fn addwstr "const wchar_t *string" +.Ft int +.Fn waddstr "WINDOW *win" "const char *string" +.Ft int +.Fn waddwstr "WINDOW *win" "const wchar_t *string" +.Ft int +.Fn mvaddstr "int y" "int x" "const char *string" +.Ft int +.Fn mvaddwstr "int y" "int x" "const wchar_t *string" +.Ft int +.Fn mvwaddstr "WINDOW *win" "int y" "int x" "const char *string" +.Ft int +.Fn mvwaddwstr "WINDOW *win" "int y" "int x" "const wchar_t *string" "int len" +.Ft int +.Fn addnstr "const char *string" "int len" +.Ft int +.Fn addnwstr "const wchar_t *string" "int len" +.Ft int +.Fn waddnstr "WINDOW *win" "const char *string" "int len" +.Ft int +.Fn waddnwstr "WINDOW *win" "const wchar_t *string" "int len" +.Ft int +.Fn mvaddnstr "int y" "int x" "const char *string" "int len" +.Ft int +.Fn mvaddnwstr "int y" "int x" "const wchar_t *string" "int len" +.Ft int +.Fn mvwaddnstr "WINDOW *win" "int y" "int x" "const char *string" "int len" +.Ft int +.Fn mvwaddnwstr "WINDOW *win" "int y" "int x" "const wchar_t *string" "int len" +.Sh DESCRIPTION +These functions add character strings to +.Va stdscr +or to the specified window. +.Pp +The +.Fn addstr +function +will add the characters passed in +.Fa string +to +.Va stdscr +starting at the current cursor position. +Any background attributes currently set on +.Va stdscr +will be applied to the added character. +The +.Fn waddstr +function does the same as +.Fn addstr +but adds the string to the window specified by +.Fn win . +.Pp +The +.Fn addnstr +function will add the contents of +.Fa string +to +.Va stdscr +but will limit the number of characters added to be, at most, +.Fa len . +If +.Fa len +is \-1 then +.Fa addnstr +will add the number of characters contained in the null terminated string +.Fa string . +Any background attributes currently set on +.Va stdscr +will be applied to the added character. +The +.Fn waddnstr +function +does the same as +.Fa addnstr +but adds the string to the window specified by +.Fa win . +.Pp +The functions +.Fn mvaddstr , +.Fn mwaddnstr , +.Fn mvwaddstr +and +.Fn mvwaddnstr +are the same as the functions +.Fn addstr , +.Fn waddstr , +.Fn waddstr +and +.Fn waddnstr , +respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the string is added to the window. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_addchstr 3 , +.Xr curses_attributes 3 , +.Xr curses_cursor 3 , +.Xr curses_inch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_attributes.3 b/static/netbsd/man3/curses_attributes.3 new file mode 100644 index 00000000..9e3df9a8 --- /dev/null +++ b/static/netbsd/man3/curses_attributes.3 @@ -0,0 +1,347 @@ +.\" $NetBSD: curses_attributes.3,v 1.12 2025/04/11 23:57:20 uwe Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 27, 2021 +.Dt CURSES_ATTRIBUTES 3 +.Os +.Sh NAME +.Nm curses_attributes , +.Nm attron , +.Nm attroff , +.Nm attrset , +.Nm color_set , +.Nm getattrs , +.Nm termattrs , +.Nm wattron , +.Nm wattroff , +.Nm wattrset , +.Nm wcolor_set , +.Nm attr_on , +.Nm attr_off , +.Nm attr_set , +.Nm attr_get , +.Nm term_attrs , +.Nm wattr_on , +.Nm wattr_off , +.Nm wattr_set , +.Nm wattr_get +.Nd curses general attribute manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn attron "int attr" +.Ft int +.Fn attroff "int attr" +.Ft int +.Fn attrset "int attr" +.Ft int +.Fn color_set "short pair" "void *opt" +.Ft chtype +.Fn getattrs "WINDOW *win" +.Ft chtype +.Fn termattrs "void" +.Ft int +.Fn wcolor_set "WINDOW *win" "short pair" "void *opt" +.Ft int +.Fn wattron "WINDOW * win" "int attr" +.Ft int +.Fn wattroff "WINDOW * win" "int attr" +.Ft int +.Fn wattrset "WINDOW * win" "int attr" +.Ft int +.Fn attr_on "attr_t attr" "void *opt" +.Ft int +.Fn attr_off "attr_t attr" "void *opt" +.Ft int +.Fn attr_set "attr_t attr" "short pair" "void *opt" +.Ft int +.Fn attr_get "attr_t *attr" "short *pair" "void *opt" +.Ft attr_t +.Fn term_attrs "void" +.Ft int +.Fn wattr_on "WINDOW *win" "attr_t attr" "void *opt" +.Ft int +.Fn wattr_off "WINDOW *win" "attr_t attr" "void *opt" +.Ft int +.Fn wattr_set "WINDOW *win" "attr_t attr" "short pair" "void *opt" +.Ft int +.Fn wattr_get "WINDOW *win" "attr_t *attr" "short *pair" "void *opt" +.Sh DESCRIPTION +These functions manipulate attributes on +.Va stdscr +or on the specified window. +The attributes that can be manipulated are: +.Pp +.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent +.It A_NORMAL +no special attributes are applied +.It A_STANDOUT +characters are displayed in the "best" supported highlighting mode of the +terminal +.It A_UNDERLINE +characters are displayed underlined +.It A_REVERSE +characters are displayed in inverse video +.It A_BLINK +characters blink +.It A_DIM +characters are displayed at a lower intensity +.It A_BOLD +characters are displayed at a higher intensity +.It A_INVIS +characters are added invisibly +.It A_PROTECT +characters are protected from modification +.It A_ALTCHARSET +characters are displayed using the alternate character set (ACS) +.It COLOR_PAIR(n) +characters are displayed using color pair n. +.El +.Pp +The +.Fn attron +function turns on the attributes specified in +.Fa attr +on +.Va stdscr , +while the +.Fn attroff +function turns off the attributes specified in +.Fa attr +on +.Va stdscr . +.Pp +The function +.Fn attrset +sets the attributes of +.Va stdscr +to those specified in +.Fa attr , +turning off any others. +To turn off all the attributes (including color and alternate character set), +use +.Fn attrset A_NORMAL . +.Pp +Multiple attributes can be manipulated by combining the attributes +using a logical +.Em OR . +For example, +.Fn attron "A_REVERSE | A_BOLD" +will turn on both inverse video and higher intensity. +.Pp +The function +.Fn color_set +sets the color pair attribute to the pair specified in +.Fa pair . +.Pp +The function +.Fn getattrs +returns the attributes that are currently applied to window specified by +.Fa win . +.Pp +The function +.Fn termattrs +returns the logical +.Em OR +of attributes that can be applied to the screen. +.Pp +The functions +.Fn wattron , +.Fn wattroff , +.Fn wattrset , +and +.Fn wcolor_set +are equivalent to +.Fn attron , +.Fn attroff +.Fn attrset , +and +.Fn color_set +respectively, excepting that the attributes are applied to the window +specified by +.Fa win . +.Pp +The following functions additionally manipulate wide attributes on +.Va stdscr +or on the specified window. +The additional wide attributes that can be manipulated are: +.Pp +.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent +.It WA_STANDOUT +characters are displayed in the "best" supported highlighting mode of the +terminal +.It WA_UNDERLINE +characters are displayed underlined +.It WA_REVERSE +characters are displayed in inverse video +.It WA_BLINK +characters blink +.It WA_DIM +characters are displayed at a lower intensity +.It WA_BOLD +characters are displayed at a higher intensity +.It WA_INVIS +characters are added invisibly +.It WA_PROTECT +characters are protected from modification +.It WA_ALTCHARSET +characters are displayed using the alternate character set (ACS) +.It WA_LOW +characters are displayed with low highlight +.It WA_TOP +characters are displayed with top highlight +.It WA_HORIZONTAL +characters are displayed with horizontal highlight +.It WA_VERTICAL +characters are displayed with vertical highlight +.It WA_LEFT +characters are displayed with left highlight +.It WA_RIGHT +characters are displayed with right highlight +.El +.Pp +The +.Fn attr_on +function turns on the wide attributes specified in +.Fa attr +on +.Va stdscr , +while the +.Fn attr_off +function turns off the wide attributes specified in +.Fa attr +on +.Va stdscr . +.Pp +The function +.Fn attr_set +sets the wide attributes of +.Va stdscr +to those specified in +.Fa attr +and +.Fa pair , +turning off any others. +Note that a color pair specified in +.Fa pair +will override any color pair specified in +.Fa attr . +.Pp +The function +.Fn attr_get +sets +.Fa attr +to the wide attributes and +.Fa pair +to the color pair currently applied to +.Va stdscr . +Either of +.Fa attr +and +.Fa pair +can be +.Dv NULL , +if the relevant value is of no interest. +.Pp +The function +.Fn term_attrs +returns the logical +.Em OR +of wide attributes that can be applied to the screen. +.Pp +The functions +.Fn wattr_on , +.Fn wattr_off +and +.Fn wattr_set +are equivalent to +.Fn attr_on , +.Fn attr_off +and +.Fn attr_set +respectively, excepting that the character is added to the window specified by +.Fa win . +.Pp +The function +.Fn wattr_get +is equivalent to +.Fn attr_get , +excepting that the wide attributes and color pair currently applied to +.Fa win +are set. +.Pp +The following constants can be used to extract the components of a +.Dv chtype : +.Pp +.Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent +.It A_ATTRIBUTES +bit-mask containing attributes part +.It A_CHARTEXT +bit-mask containing character part +.It A_COLOR +bit-mask containing color-pair part +.El +.Sh RETURN VALUES +These functions return OK on success and ERR on failure. +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_addchstr 3 , +.Xr curses_addstr 3 , +.Xr curses_background 3 , +.Xr curses_color 3 , +.Xr curses_insch 3 , +.Xr curses_standout 3 , +.Xr curses_underscore 3 +.Sh NOTES +The +.Fa opt +argument is not currently used but is reserved for a future version of the +specification. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Pp +The +.Fn getattrs +function +is a +.Nx +extension. +.Sh HISTORY +These functions first appeared in +.Nx 1.5 . +.Sh CAVEATS +Some terminals do not support characters with both color and other attributes +set. +In this case, the other attribute is displayed instead of the color attribute. +.Pp +The standout attribute is a higher level alias and should not be mixed with +other attributes. diff --git a/static/netbsd/man3/curses_background.3 b/static/netbsd/man3/curses_background.3 new file mode 100644 index 00000000..6464182c --- /dev/null +++ b/static/netbsd/man3/curses_background.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: curses_background.3,v 1.8 2025/04/11 23:57:20 uwe Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 29, 2018 +.Dt CURSES_BACKGROUND 3 +.Os +.Sh NAME +.Nm curses_background , +.Nm bkgd , +.Nm bkgdset , +.Nm getbkgd , +.Nm wbkgd , +.Nm wbkgdset +.Nd curses attribute manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn bkgd chtype +.Ft void +.Fn bkgdset chtype +.Ft chtype +.Fn getbkgd "WINDOW *" +.Ft int +.Fn wbkgd "WINDOW *" chtype +.Ft void +.Fn wbkgdset "WINDOW *" chtype +.Sh DESCRIPTION +These functions manipulate the background attributes on +.Va stdscr +or on the specified window. +.Pp +The function +.Fn wbkgdset win ch +sets the background attributes of the specified window +.Fa win +to +.Fa ch . +.Pp +When the background attributes are set on a window, characters are added to +the window with the logical +.Em OR +of the background attributes and the character's attributes. +If both the background attribute and the character attribute contain color, +the color of the character attribute is rendered. +If the background attribute contains a non-space character, then this +character is added where the foreground character is a space character. +.Pp +Note that subwindows created from +.Fa win +inherit the background attributes of +.Fa win . +.Pp +The function +.Fn wbkgd win ch +sets the background attributes of the specified window +.Fa win +to +.Fa ch +and also sets the rendition of every character position on that window, +as if the characters had been newly added to +.Fa win . +The rendition of characters on subwindows of +.Fa win +is also set to +.Fa ch . +.Pp +The functions +.Fn bkgdset ch +and +.Fn bkgd ch +are equivalent to +.Fn wbkgdset stdscr ch +and +.Fn wbkgd stdscr ch , +respectively. +.Pp +The function +.Fn getbkgd win +returns the background attributes for the window +.Fa win . +.Sh RETURN VALUES +The functions +.Fn wbkgdset +and +.Fn wbkgd +return OK on success and ERR on failure. +.Sh SEE ALSO +.Xr curses_attributes 3 , +.Xr curses_color 3 , +.Xr curses_window 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +These functions first appeared in +.Nx 1.6 . diff --git a/static/netbsd/man3/curses_border.3 b/static/netbsd/man3/curses_border.3 new file mode 100644 index 00000000..2c2a74f5 --- /dev/null +++ b/static/netbsd/man3/curses_border.3 @@ -0,0 +1,159 @@ +.\" $NetBSD: curses_border.3,v 1.5 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 12, 2002 +.Dt CURSES_BORDER 3 +.Os +.Sh NAME +.Nm curses_border , +.Nm border , +.Nm box , +.Nm wborder +.Nd curses border drawing routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fo border +.Fa "chtype ls" +.Fa "chtype rs" +.Fa "chtype ts" +.Fa "chtype bs" +.Fa "chtype tl" +.Fa "chtype tr" +.Fa "chtype bl" +.Fa "chtype br" +.Fc +.Ft int +.Fn box "WINDOW *win" "chtype vertical" "chtype horizontal" +.Ft int +.Fo wborder +.Fa "WINDOW *win" +.Fa "chtype ls" +.Fa "chtype rs" +.Fa "chtype ts" +.Fa "chtype bs" +.Fa "chtype tl" +.Fa "chtype tr" +.Fa "chtype bl" +.Fa "chtype br" +.Fc +.Sh DESCRIPTION +These functions draw borders around +.Va stdscr +or around the specified window. +.Pp +The +.Fn border +function draws a border around +.Va stdscr +using the characters given as arguments to the function. +The +.Fa ls , +.Fa rs , +.Fa ts +and +.Fa bs +are the characters used to draw the left, right, top and bottom sides, +respectively. +The +.Fa tl , +.Fa tr , +.Fa bl +and +.Fa br +are the characters used to draw the top-left, top-right, bottom-left +and bottom-right corners, respectively. +If any of the characters have a text portion that is 0 then a default +alternate character set character is used for that character. +Note that even though the text portion of the argument is 0, the argument +can still be used to specify the attributes for that portion of the border. +The following table shows the default characters for each argument: +.Pp +.Bl -column "ls" -offset indent +.It ls ACS_VLINE +.It rs ACS_VLINE +.It ts ACS_HLINE +.It bs ACS_HLINE +.It tl ACS_ULCORNER +.It tr ACS_URCORNER +.It bl ACS_LLCORNER +.It br ACS_LRCORNER +.El +.Pp +.Fn wborder +is the same as +.Fn border +excepting that the border is drawn around the specified window. +.Pp +The +.Fn box +command draws a box around the window given in +.Fa win +using the +.Fa vertical +character for the vertical lines and the +.Fa horizontal +character for the horizontal lines. +The corner characters of this box will be the defaults as described for +.Fn border +above. +Passing characters with text portion that is 0 to +.Fn box +will result in the same defaults as those for +.Fn border +as described above. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_attributes 3 , +.Xr curses_line 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_cchar.3 b/static/netbsd/man3/curses_cchar.3 new file mode 100644 index 00000000..8765e11f --- /dev/null +++ b/static/netbsd/man3/curses_cchar.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: curses_cchar.3,v 1.3 2021/10/04 14:35:20 andvar Exp $ +.\" +.\" Copyright (c) 2018 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 19, 2018 +.Dt CURSES_CCHAR 3 +.Os +.Sh NAME +.Nm curses_cchar , +.Nm getcchar , +.Nm setcchar +.Nd curses representation of wide characters +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.\" +.In curses.h +.\" +.Ft int +.Fo getcchar +.Fa "const cchar_t *wcval" +.Fa "wchar_t *wch" +.Fa "attr_t *attrs" +.Fa "short *color_pair" +.Fa "void *opts" +.Fc +.\" +.Ft int +.Fo setcchar +.Fa "cchar_t *wcval" +.Fa "const wchar_t *wch" +.Fa "const attr_t attrs" +.Fa "short color_pair" +.Fa "const void *opts" +.Fc +.Sh DESCRIPTION +Curses uses the opaque type +.Vt cchar_t +to represent a string of wide characters up to an +implementation-dependent length along with a color pair and zero or +more attributes. +A null +.Vt cchar_t +object is an object that references an empty wide-character string. +Arrays of +.Vt cchar_t +objects are terminated by a null +.Vt cchar_t +object. +.Pp +Objects of type +.Vt cchar_t +can be manipulated using the +.Nm getcchar +and +.Nm setcchar +functions. +Both these functions take as their last parameter the +.Fa opts +argument which is reserved for future extensions. +Currently, the application must provide a null pointer as +.Fa opts . +.\" +.Pp +When the +.Nm getcchar +function is called with non-null +.Fa wch +it extracts the information from the +.Fa wcval +object. +The string of wide characters in +.Fa wcval +is copied to the +.Fa wch +array. +The attributes are stored in +.Fa attrs +and the color pair is stored in +.Fa color_pair . +In this case it returns +.Er OK +upon successful completion, and +.Er ERR +otherwise. +.Pp +When +.Nm getcchar +is called with null +.Fa wch +it doesn't store any information but returns the number of wide +characters referenced by +.Fa wcval , +including the null terminator. +.\" +.Pp +.Nm setcchar +initializes +.Fa wcval +with the wide-character string +.Fa wch , +attributes +.Fa attrs , +and color pair +.Fa color_pair . +.Sh RETURN VALUES +.Nm getchar +called with null +.Fa wch +returns the number of wide characters referenced by +.Fa wcval , +including the null terminator. +.Pp +Otherwise these functions return one of the following values: +.Bl -tag -width "Er ERR" -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.\" .Sh SEE ALSO +.\" XXX no other man pages yet for HAVE_WCHAR functions +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +.Pp +Wide characters support appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/curses_chgat.3 b/static/netbsd/man3/curses_chgat.3 new file mode 100644 index 00000000..db726efc --- /dev/null +++ b/static/netbsd/man3/curses_chgat.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: curses_chgat.3,v 1.5 2011/02/10 08:54:12 blymn Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 6, 2009 +.Dt CURSES_CHGAT 3 +.Os +.Sh NAME +.Nm chgat , +.Nm wchgat , +.Nm mvchgat , +.Nm mvwchgat +.Nd curses on-screen attribute manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn chgat "int n" "attr_t attr" "short color" "const void *opts" +.Ft int +.Fn wchgat "WINDOW *win" "int n" "attr_t attr" "short color" \ +"const void *opts" +.Ft int +.Fn mvchgat "int y" "int x" "int n" "attr_t attr" "short color" \ +"const void *opts" +.Ft int +.Fn mvwchgat "WINDOW *win" "int y" "int x" "int n" "attr_t attr" \ +"short color" "const void *opts" +.Sh DESCRIPTION +These functions modify the attributes of the drawn content on stdscr or +on the specified window. +.Pp +The +.Fn chgat +function sets the attributes of the next +.Fa n +characters to +.Fa attr +and the color pair to +.Fa color . +If +.Fa n +is negative or larger than the remainder of the line, it gets truncated. +.Pp +The +.Fn wchgat +is the same as the +.Fn chgat +function, excepting that the attributes are changed in the window specified by +.Fa win . +.Pp +The +.Fn mvchgat +and +.Fn mvwchgat +functions are the same as the +.Fn chgat +and +.Fn wchgat +functions, respectively, excepting that they operate from the position +specified by +.Fa y , +.Fa x . +.Pp +These functions do not perform wrapping. +They do not update the cursor position. +.Sh RETURN VALUES +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_attributes 3 +.Sh STANDARDS +The +.Fn chgat , +.Fn wchgat , +.Fn mvchgat , +and +.Fn mvwchgat +functions conform to +.St -xcurses4.2 . +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +Support for the +.Fn chgat +family was added in +.Nx 6.0 . diff --git a/static/netbsd/man3/curses_clear.3 b/static/netbsd/man3/curses_clear.3 new file mode 100644 index 00000000..4f5c649f --- /dev/null +++ b/static/netbsd/man3/curses_clear.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: curses_clear.3,v 1.5 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd January 11, 2019 +.Dt CURSES_CLEAR 3 +.Os +.Sh NAME +.Nm curses_clear , +.Nm clear , +.Nm wclear , +.Nm clearok , +.Nm clrtobot , +.Nm clrtoeol , +.Nm erase , +.Nm werase , +.Nm wclrtobot , +.Nm wclrtoeol +.Nd curses clear window routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn clear "void" +.Ft int +.Fn clearok "WINDOW *win" "bool flag" +.Ft int +.Fn clrtobot "void" +.Ft int +.Fn clrtoeol "void" +.Ft int +.Fn erase "void" +.Ft int +.Fn wclear "WINDOW *win" +.Ft int +.Fn werase "WINDOW *win" +.Ft int +.Fn wclrtobot "WINDOW *win" +.Ft int +.Fn wclrtoeol "WINDOW *win" +.Sh DESCRIPTION +These functions clear all or part of +.Va stdscr +or of the specified window. +.Pp +The +.Fn clear +and +.Fn erase +functions erase all characters on +.Va stdscr . +These differ in that +.Fn clear +uses +.Fn clearok +to force a complete redraw on the next refresh, and +.Fn erase +does not. +.Fn wclear +and +.Fn werase +perform the same function as +.Fn clear +and +.Fn erase , +respectively, excepting that the specified window is cleared. +.Pp +By setting +.Fa flag +to +.Dv TRUE , +the +.Fn clearok +function is used to force the next call to +.Fn wrefresh +to clear and completely redraw the window given in +.Fa win . +.Pp +The function +.Fn clrtobot +will clear +.Va stdscr +from the current row to the bottom of the screen. +.Fn clrtoeol +will clear +.Va stdscr +from the current column position to the end of the line. +.Fn wclrtobot +and +.Fn wclrtoeol +are the same as +.Fn clrtobot +and +.Fn clrtoeol , +respectively, excepting the window specified is operated on instead of +.Va stdscr . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_refresh 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_color.3 b/static/netbsd/man3/curses_color.3 new file mode 100644 index 00000000..0360a805 --- /dev/null +++ b/static/netbsd/man3/curses_color.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: curses_color.3,v 1.14 2025/04/11 23:41:14 uwe Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 20, 2009 +.Dt CURSES_COLOR 3 +.Os +.Sh NAME +.Nm curses_color , +.Nm has_colors , +.Nm can_change_color , +.Nm start_color , +.Nm init_pair , +.Nm pair_content , +.Nm COLOR_PAIR , +.Nm PAIR_NUMBER , +.Nm init_color , +.Nm color_content , +.Nm no_color_attributes +.Nd curses color manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft bool +.Fn has_colors void +.Ft bool +.Fn can_change_color void +.Ft int +.Fn start_color void +.Ft int +.Fn init_pair "short pair" "short fore" "short back" +.Ft int +.Fn pair_content "short pair" "short *fore" "short *back" +.Ft int +.Fn COLOR_PAIR "int n" +.Ft int +.Fn PAIR_NUMBER "int val" +.Ft int +.Fn init_color "short color" "short red" "short green" "short blue" +.Ft int +.Fn color_content "short color" "short *red" "short *green" "short *blue" +.Ft attr_t +.Fn no_color_attributes void +.Pp +.Vt extern int Va COLORS ; +.Pp +.Vt extern int Va COLOR_PAIRS ; +.Sh DESCRIPTION +These functions manipulate color on terminals that support color attributes. +.Pp +The function +.Fn has_colors +indicates whether a terminal is capable of displaying color attributes. +It returns +.Dv TRUE +if the terminal is capable of displaying color attributes and +.Dv FALSE +otherwise. +.Pp +The function +.Fn can_change_color +indicates whether a terminal is capable of redefining colors. +It returns +.Dv TRUE +if colors can be redefined and +.Dv FALSE +if they can not. +.Pp +The function +.Fn start_color +initializes the curses color support on a terminal. +It must be called before any color manipulation functions are called on that +terminal. +The function initializes the eight basic colors (black, red, green, yellow, +blue, magenta, cyan and white) that are specified using the color macros +(such as +.Dv COLOR_BLACK ) +defined in +.In curses.h . +.Fn start_color +also initializes the global external variables +.Va COLORS +and +.Va COLOR_PAIRS . +.Va COLORS +defines the number of colors that the terminal supports and +.Va COLOR_PAIRS +defines the number of color-pairs that the terminal supports. +These color-pairs are initialized to white foreground on black background. +.Fn start_color +sets the colors on the terminal to the curses defaults of white +foreground on black background unless the functions +.Fn assume_default_colors +or +.Fn use_default_colors +have been called previously. +.Pp +The function +.Fn init_pair pair fore back +sets foreground color +.Fa fore +and background color +.Fa back +for color-pair number +.Fa pair . +The valid range for the color-pair +.Fa pair +is from 1 to +.Va COLOR_PAIRS Ns No \|\-\|1 +and the valid range for the colors is any number less than +.Va COLORS . +Specifying a negative number will set that color to the default foreground +or background color. +The 8 initial colors are defined as: +.Pp +.Bl -inset -compact -offset indent +.It Dv COLOR_BLACK +.It Dv COLOR_RED +.It Dv COLOR_GREEN +.It Dv COLOR_YELLOW +.It Dv COLOR_BLUE +.It Dv COLOR_MAGENTA +.It Dv COLOR_CYAN +.It Dv COLOR_WHITE +.El +.Pp +Color-pair 0 is used as the default color pair, so changing this will +have no effect. +Use the function +.Fn assume_default_colors +to change the default colors. +.Pp +The function +.Fn pair_content pair *fore *back +stores the foreground and background color numbers of color-pair +.Fa pair +in the variables +.Fa fore +and +.Fa back , +respectively. +.Pp +The macro +.Fn COLOR_PAIR n +gives the attribute value of color-pair number +.Fa n . +This is the value that is used to set the attribute of a character to this +color-pair. +For example, +.Dl attrset(COLOR_PAIR(2)) +will display characters using color-pair 2. +.Pp +The macro +.Fn PAIR_NUMBER val +gives the color-pair number associated with the attribute value +.Fa val . +.Pp +The function +.Fn init_color color red green blue +sets the red, green and blue intensity components of color +.Fa color +to the values +.Fa red , +.Fa green +and +.Fa blue , +respectively. +The minimum intensity value is 0 and the maximum intensity value is 1000. +.Pp +The function +.Fn color_content color *red *green *blue +stores the red, green and blue intensity components of color +.Fa color +in the variables +.Fa red , +.Fa green , +and +.Fa blue , +respectively. +.Pp +The function +.Fn no_color_attributes +returns those attributes that a terminal is unable to combine with color. +.Sh RETURN VALUES +The functions +.Fn start_color , +.Fn init_pair , +.Fn pair_content , +.Fn init_color +and +.Fn color_content +return +.Dv OK +on success and +.Dv ERR +on failure. +.Sh SEE ALSO +.Xr curses_attributes 3 , +.Xr curses_background 3 , +.Xr curses_default_colors 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Pp +The function +.Fn no_color_attributes +and the use of negative color numbers +are extensions to the X/Open Curses specification. +.Sh HISTORY +These functions first appeared in +.Nx 1.5 . diff --git a/static/netbsd/man3/curses_cursor.3 b/static/netbsd/man3/curses_cursor.3 new file mode 100644 index 00000000..2dcd3019 --- /dev/null +++ b/static/netbsd/man3/curses_cursor.3 @@ -0,0 +1,261 @@ +.\" $NetBSD: curses_cursor.3,v 1.9 2017/01/05 09:46:32 wiz Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd December 31, 2016 +.Dt CURSES 3 +.Os +.Sh NAME +.Nm curses_cursor , +.Nm getcury , +.Nm getcurx , +.Nm getsyx , +.Nm getyx , +.Nm getbegy , +.Nm getbegx , +.Nm getbegyx , +.Nm getmaxy , +.Nm getmaxx , +.Nm getmaxyx , +.Nm getpary , +.Nm getparx , +.Nm getparyx , +.Nm move , +.Nm setsyx , +.Nm wmove , +.Nm mvcur , +.Nm wcursyncup +.Nd curses cursor and window location and positioning routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn getcury "WINDOW *win" +.Ft int +.Fn getcurx "WINDOW *win" +.Ft int +.Fn getsyx "int y" "int x" +.Ft void +.Fn getyx "WINDOW *win" "int y" "int x" +.Ft int +.Fn getbegy "WINDOW *win" +.Ft int +.Fn getbegx "WINDOW *win" +.Ft void +.Fn getbegyx "WINDOW *win" "int y" "int x" +.Ft int +.Fn getmaxy "WINDOW *win" +.Ft int +.Fn getmaxx "WINDOW *win" +.Ft void +.Fn getmaxyx "WINDOW *win" "int y" "int x" +.Ft int +.Fn getpary "WINDOW *win" +.Ft int +.Fn getparx "WINDOW *win" +.Ft void +.Fn getparyx "WINDOW *win" "int y" "int x" +.Ft int +.Fn move "int y" "int x" +.Ft int +.Fn setsyx "int y" "int x" +.Ft int +.Fn wmove "WINDOW *win" "int y" "int x" +.Ft int +.Fn mvcur "int oldy" "int oldx" "int y" "int x" +.Ft void +.Fn wcursyncup "WINDOW *win" +.Sh DESCRIPTION +These functions and macros locate and position cursors and windows. +.Pp +The +.Fn getcury +and +.Fn getcurx +functions get the current row and column positions, respectively, of the cursor in +the window +.Fa win . +The +.Fn getyx +macro sets the values of +.Fa y +and +.Fa x +to the current row and column positions of the cursor in the window +.Fa win . +.Pp +The +.Fn getsyx +macro sets the values of +.Fa y +and +.Fa x +of the current window if +.Fn is_leaveok +is false, otherwise \-1, \-1. +The +.Fn setsyx +macro sets the row and column positions, respectively, of the cursor in the +current window to the values of +.Fa y +and +.Fa x . +If both +.Fa y +and +.Fa x +are both \-1 then +.Fn leaveok +is set. +.Pp +The origin row and columns of a window +.Fa win +can be +determined by calling the +.Fn getbegy +and +.Fn getbegx +functions, respectively, and the maximum row and column for the window can be +found by calling the functions +.Fn getmaxy +and +.Fn getmaxx , +respectively. +The +.Fn getbegyx +and +.Fn getmaxyx +macros set the values of +.Fa y +and +.Fa x +to the origin and maximum row and column positions, respectively, for the window +.Fa win . +.Pp +The +.Fn getpary +and +.Fn getparx +functions return the row and column position of the given subwindow relative to +the window's parent. +The macro +.Fn getparyx +sets the values of +.Fa y +and +.Fa x +to the origin of the subwindow relative to the window's parent. +.Pp +The +.Fn move +function positions the cursor on the current window at the position given by +.Fa y , +.Fa x . +The cursor position is not changed on the screen until the next +.Fn refresh . +.Pp +The +.Fn wmove +function is the same as the +.Fn move +function, excepting that the cursor is moved in the window specified by +.Fa win . +.Pp +The function +.Fn mvcur +moves the cursor to +.Fa y , +.Fa x +on the screen. +The arguments +.Fa oldy , +.Fa oldx +define the previous cursor position for terminals that do not support +absolute cursor motions. +The curses library may optimise the cursor motion based on these values. +If the +.Fn mvcur +succeeds then the curses internal structures are updated with the new +position of the cursor. +If the destination arguments for +.Fn mvcur +exceed the terminal bounds an error will be returned and the cursor +position will be unchanged. +.Pp +The +.Fn wcursyncup +function sets the cursor positions of all ancestors of +.Fa win +to that of +.Fa win . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_refresh 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +The +.Fn getbegx , +.Fn getbegy , +.Fn getcurx , +.Fn getcury , +.Fn getmaxx , +.Fn getmaxy , +.Fn getparx , +and +.Fn getpary +functions are extensions. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn getsyx +and +.Fn setsyx +functions are +.Em ncurses +extensions to the Curses library and were added in +.Nx 8.0 . diff --git a/static/netbsd/man3/curses_default_colors.3 b/static/netbsd/man3/curses_default_colors.3 new file mode 100644 index 00000000..2efd8c3f --- /dev/null +++ b/static/netbsd/man3/curses_default_colors.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: curses_default_colors.3,v 1.6 2008/04/30 13:10:51 martin Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 13, 2002 +.Dt CURSES_DEFAULT_COLORS 3 +.Os +.Sh NAME +.Nm curses_default_colors , +.Nm assume_default_colors , +.Nm use_default_colors +.Nd curses default colors setting routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn assume_default_colors "short fore" "short back" +.Ft int +.Fn use_default_colors "" +.Sh DESCRIPTION +These functions tell the curses library to set the default colors or to use +the terminal's default colors instead of using the default colors for curses +applications (which are white foreground on black background). +.Pp +The function +.Fn assume_default_colors fore back +sets the default colors to foreground color +.Fa fore +and background color +.Fa back . +If a value of \-1 is used for a color, then the terminal default color is used +for that color. +.Pp +The function +.Fn use_default_colors +sets both the foreground and background colors to the terminal default colors. +This is equivalent to +.Fn assume_default_colors \-1 \-1 . +.Sh RETURN VALUES +These functions return OK on success and ERR on failure. +.Sh SEE ALSO +.Xr curses_color 3 +.Sh STANDARDS +These functions are based on +.Em ncurses +extensions to the curses standards. +.Sh HISTORY +These functions first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/curses_delch.3 b/static/netbsd/man3/curses_delch.3 new file mode 100644 index 00000000..e998e9e3 --- /dev/null +++ b/static/netbsd/man3/curses_delch.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: curses_delch.3,v 1.5 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 25, 2018 +.Dt CURSES_DELCH 3 +.Os +.Sh NAME +.Nm curses_delch , +.Nm delch , +.Nm wdelch +.Nd curses delete characters routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn delch "void" +.Ft int +.Fn wdelch "WINDOW *win" +.Sh DESCRIPTION +These functions delete characters from +.Va stdscr +or from the specified window. +.Pp +The +.Fn delch +function deletes the character at the current cursor position on +.Va stdscr . +Characters to the right of the deleted character are moved one position +to the left. +The cursor position is unchanged. +.Pp +The +.Fn wdelch +function is the same as the +.Fn delch +function, excepting that the character is deleted from the specified window. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_insch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_deleteln.3 b/static/netbsd/man3/curses_deleteln.3 new file mode 100644 index 00000000..75d08e7c --- /dev/null +++ b/static/netbsd/man3/curses_deleteln.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: curses_deleteln.3,v 1.5 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 12, 2002 +.Dt CURSES_DELETELN 3 +.Os +.Sh NAME +.Nm curses_deleteln , +.Nm deleteln , +.Nm wdeleteln +.Nd curses delete single line routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn deleteln "void" +.Ft int +.Fn wdeleteln "WINDOW *win" +.Sh DESCRIPTION +These functions delete a single line from +.Va stdscr +or from the specified window. +.Pp +The +.Fn deleteln +function deletes the screen line containing the cursor in the +.Va stdscr . +The +.Fn wdeleteln +function is the same as the +.Fn deleteln +function, excepting that the line is deleted from the window specified by +.Fa win . +.Pp +All lines following the deleted line are moved up one line toward the cursor. +The last line of the window is cleared. +The cursor position is unchanged. +.Pp +If a scrolling region has been set with the +.Fn setscrreg +or +.Fn wsetscrreg +functions and the current cursor position is inside the scrolling region, +then only the lines from the current line to the bottom of the scrolling +region are moved up and the bottom line of the scrolling region cleared. +.Pp +The functions +.Fn deleteln +and +.Fn wdeleteln win +are equivalent to +.Fn winsdelln stdscr \-1 +and +.Fn winsdelln win \-1 +respectively. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_insdelln 3 , +.Xr curses_insertln 3 , +.Xr curses_scroll 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_echochar.3 b/static/netbsd/man3/curses_echochar.3 new file mode 100644 index 00000000..e64e2460 --- /dev/null +++ b/static/netbsd/man3/curses_echochar.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: curses_echochar.3,v 1.4 2025/04/11 23:57:20 uwe Exp $ +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 27, 2004 +.Dt CURSES_ECHOCHAR 3 +.Os +.Sh NAME +.Nm curses_echochar , +.Nm echochar , +.Nm wechochar , +.Nm pechochar +.Nd curses add characters and then refresh routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn echochar "const chtype ch" +.Ft int +.Fn wechochar "WINDOW *win" "const chtype ch" +.Ft int +.Fn pechochar "WINDOW *pad" "const chtype ch" +.Sh DESCRIPTION +These functions add characters to +.Va stdscr +or to the specified window or pad and then cause an immediate +.Fn refresh +of that window or pad. +.Pp +The +.Fn echochar +function adds the character given in +.Fa ch +to +.Va stdscr +at the current cursor position and advances the current cursor position by one. +Any character attributes set in +.Fa ch +will be merged with the background attributes currently set on +.Va stdscr . +.Va stdscr +is then refreshed. +Calling +.Fn echochar +is equivalent to calling +.Fn addch +followed by +.Fn refresh . +.Pp +The +.Fn wechochar +function is the same as the +.Fn echochar +function, excepting that the character is added to the window specified by +.Fa win +and +.Fa win +is refreshed. +.Pp +The +.Fn pechochar +function is the similar to the +.Fn echochar +function, excepting that the character is added to the pad specified by +.Fa pad +and +.Fa pad +is refreshed at its previous location on the screen. +Calling +.Fn pechochar +is equivalent to calling +.Fn addch +followed by +.Fn prefresh . +.Sh RETURN VALUES +These functions will return one of the following values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_attributes 3 , +.Xr curses_pad 3 , +.Xr curses_refresh 3 +.Sh STANDARDS +The +.Fn echochar , +.Fn wechochar , +and +.Fn pechochar +functions comply with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_fileio.3 b/static/netbsd/man3/curses_fileio.3 new file mode 100644 index 00000000..f85c248d --- /dev/null +++ b/static/netbsd/man3/curses_fileio.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: curses_fileio.3,v 1.4 2010/12/09 11:21:49 njoly Exp $ +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 31, 2008 +.Dt CURSES_FILEIO 3 +.Os +.Sh NAME +.Nm curses_fileio , +.Nm getwin , +.Nm putwin +.Nd curses file input/output routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft WINDOW * +.Fn getwin "FILE *fp" +.Ft int +.Fn putwin "WINDOW *win" "FILE *fp" +.Sh DESCRIPTION +These functions read and write data to and from files. +.Pp +The +.Fn getwin +function reads window data that has been stored in the file to which +.Fa fp +points, and then creates a new window using that data. +.Pp +The +.Fn putwin +function writes window data from the window +.Fa win +to the file pointed to by +.Fa fp . +.Sh RETURN VALUES +The +.Fn getwin +function returns one of the following values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Pp +The +.Fn putwin +function returns +.Dv NULL +if an error is detected. +.Sh SEE ALSO +.Xr curses_window 3 , +.Xr fread 3 , +.Xr fwrite 3 +.Sh NOTES +Subwindows can not be created by the +.Fn getwin +function, nor written by the +.Fn putwin +function. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +These functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/curses_inch.3 b/static/netbsd/man3/curses_inch.3 new file mode 100644 index 00000000..f8587b08 --- /dev/null +++ b/static/netbsd/man3/curses_inch.3 @@ -0,0 +1,264 @@ +.\" $NetBSD: curses_inch.3,v 1.15 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 25, 2018 +.Dt CURSES_INCH 3 +.Os +.Sh NAME +.Nm curses_inch , +.Nm inch , +.Nm winch , +.Nm inchnstr , +.Nm mvinchnstr , +.Nm winchnstr , +.Nm mvwinchnstr , +.Nm inchstr , +.Nm mvinchstr , +.Nm winchstr , +.Nm mvwinchstr , +.Nm innstr , +.Nm winnstr , +.Nm mvinnstr , +.Nm mvwinnstr , +.Nm instr , +.Nm winstr , +.Nm mvinstr , +.Nm mvwinstr +.Nd curses read screen contents routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft chtype +.Fn inch "void" +.Ft chtype +.Fn winch "WINDOW *win" +.Ft int +.Fn inchnstr "chtype *chars" "int n" +.Ft int +.Fn mvinchnstr "int y" "int x" "chtype *chstr" "int n" +.Ft int +.Fn winchnstr "WINDOW *win" "chtype *chars" "int n" +.Ft int +.Fn mvwinchnstr "WINDOW *win" "int y" "int x" "chtype *chstr" "int n" +.Ft int +.Fn inchstr "chtype *chars" +.Ft int +.Fn mvinchstr "int y" "int x" "chtype *chstr" +.Ft int +.Fn winchstr "WINDOW *win" "chtype *chars" +.Ft int +.Ft mvwinchstr "WINDOW *win" "int y" "int x" "chtype *chstr" +.Ft int +.Fn innstr "char *str" "int n" +.Ft int +.Fn winnstr "WINDOW *win" "char *str" "int n" +.Ft int +.Fn mvinnstr "int y" "int x" "char *str" "int n" +.Ft int +.Fn mvwinnstr "WINDOW *win" "int y" "int x" "char *str" "int n" +.Ft int +.Fn instr "char *str" +.Ft int +.Fn winstr "WINDOW *win" "char *str" +.Ft int +.Fn mvinstr "int y" "int x" "char *str" +.Ft int +.Fn mvwinstr "WINDOW *win" "int y" "int x" "char *str" +.Sh DESCRIPTION +These functions read the contents of +.Va stdscr +or of the specified window. +.Pp +The +.Fn inch +function returns the character that is displayed on +.Va stdscr +at the current cursor position. +.Pp +The +.Fn winch +function is the same as the +.Fn inch +function, excepting that the character is read from window specified by +.Fa win . +.Pp +The +.Fn inchnstr +function fills an array of +.Ft chtype +with characters read from +.Va stdscr , +the characters are read starting from the current cursor position and +continuing until either n \- 1 characters are read or the right hand +side of the screen is reached. +The resulting character array will be +.Dv NULL +terminated. +.Pp +The +.Fn winchnstr +function is the same as +.Fn inchnstr +excepting that the characters are read from the window specified by +.Fa win . +.Pp +The +.Fn inchstr +and +.Fn winchstr +functions are the same as the +.Fn inchnstr +and +.Fn winchnstr +functions, respectively, excepting that they do not limit the number +of characters read. +The characters returned are those from the current starting position to +the right hand side of the screen. +The use of +.Fn inchstr +and +.Fn winchstr +is not recommended as the character buffer can be overflowed. +.Pp +The +.Fn innstr +function +is similar to the +.Fn inchstr +function, excepting that the array of characters returned is stripped of all +the curses attributes making it a plain character string. +.Pp +The +.Fn mvinchstr , +.Fn mvinchnstr , +.Fn mvwinchstr , +and +.Fn mvwinchnstr +functions are the same as the +.Fn inchstr , +.Fn inchnstr , +.Fn winchstr , +and +.Fn winchstr +functions, respectively, except that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the output is printed on the window. +Likewise, the +.Fn mvinstr , +.Fn mvinnstr , +.Fn mvwinstr , +and +.Fn mvwinnstr +functions are the same as the +.Fn instr , +.Fn innstr , +.Fn winstr , +and +.Fn winstr +functions, respectively, except that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the output is printed on the window. +.Pp +The +.Fn winnstr +function is the same as the +.Fn innstr +function, excepting that characters are read from the window specified by +.Fa win . +.Pp +The +.Fn instr +and +.Fn winstr +functions +are the same as the +.Fn innstr +and +.Fn winnstr +functions, respectively, excepting that there are no limits placed on the +size of the returned string, which may cause buffer overflows. +For this reason, the use of +.Fn instr +and +.Fn winstr +is not recommended. +.Sh RETURN VALUES +If the calls +.Fn innstr , +.Fn mvinnstr , +.Fn mvwinnstr , +and +.Fn winnstr +succeed then they will return the number of characters actually read. +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_addstr 3 , +.Xr curses_attributes 3 , +.Xr curses_insch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part +of the Single Unix Specification. +.Sh NOTES +The +.Fn inchnstr +and +.Fn innstr +function read at most n \- 1 characters from the screen so as to leave +room for +.Dv NULL +termination. +The X/Open specification is unclear as to whether or not this is the correct +behaviour. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_input.3 b/static/netbsd/man3/curses_input.3 new file mode 100644 index 00000000..c42ee804 --- /dev/null +++ b/static/netbsd/man3/curses_input.3 @@ -0,0 +1,624 @@ +.\" $NetBSD: curses_input.3,v 1.33 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd May 14, 2024 +.Dt CURSES_INPUT 3 +.Os +.Sh NAME +.Nm curses_input , +.Nm getch , +.Nm wgetch , +.Nm mvgetch , +.Nm mvwgetch , +.Nm define_key , +.Nm keyok , +.Nm has_key , +.Nm getnstr , +.Nm wgetnstr , +.Nm mvgetnstr , +.Nm mvwgetnstr , +.Nm getstr , +.Nm wgetstr , +.Nm mvgetstr , +.Nm mvwgetstr , +.Nm keypad , +.Nm is_keypad , +.Nm notimeout , +.Nm timeout , +.Nm wtimeout , +.Nm nodelay , +.Nm ungetch , +.Nm set_escdelay +.Nd curses input stream routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn getch "void" +.Ft int +.Fn wgetch "WINDOW *win" +.Ft int +.Fn mvgetch "int y" "int x" +.Ft int +.Fn mvwgetch "WINDOW *win" "int y" "int x" +.Ft int +.Fn keyok "int key_symbol" "bool flag" +.Ft int +.Fn has_key "int key_symbol" +.Ft int +.Fn define_key "const char *sequence" "int key_symbol" +.Ft int +.Fn getnstr "char *str" "int limit" +.Ft int +.Fn wgetnstr "WINDOW *win" "char *str" "int limit" +.Ft int +.Fn mvgetnstr "int y" "int x" "char *str" "int limit" +.Ft int +.Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit" +.Ft int +.Fn getstr "char *str" +.Ft int +.Fn wgetstr "WINDOW *win" "char *str" +.Ft int +.Fn mvgetstr "int y" "int x" "char *str" +.Ft int +.Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str" +.Ft int +.Fn keypad "WINDOW *win" "bool flag" +.Ft bool +.Fn is_keypad "const WINDOW *win" +.Ft int +.Fn notimeout "WINDOW *win" "bool flag" +.Ft void +.Fn timeout "int delay" +.Ft void +.Fn wtimeout "WINDOW *win" "int delay" +.Ft int +.Fn nodelay "WINDOW *win" "bool flag" +.Ft int +.Fn ungetch "int c" +.Ft int +.Fn set_escdelay "int escdelay" +.Pp +.Va extern int ESCDELAY ; +.Sh DESCRIPTION +These functions read characters and strings from the window input file +descriptor. +.Pp +The +.Fn getch +function reads a character from the +.Va stdscr +input file descriptor and returns it. +If the +.Fn keypad +flag has been set to +.Dv TRUE , +then +.Fn getch +will assemble multi-character key sequences into key symbols, +If the terminal is resized, +.Fn getch +will return +.Dv KEY_RESIZE , +regardless of the setting of +.Fn keypad . +Calling +.Fn getch +will cause an implicit +.Fn refresh +on +.Va stdscr . +.Pp +The +.Fn wgetch +function is the same as the +.Fn getch +function, excepting that it reads from the input file descriptor associated +with the window specified by +.Fa win . +.Pp +If the +.Fn keypad +flag is +.Dv TRUE +then the assembly of specific key symbols can be disabled by using the +.Fn keyok +function. +If the +.Fa flag +is set to +.Dv FALSE +on a key symbol then +.Fn getch +will behave as if the character sequence associated with that key symbol +was not recognised and will return the component characters one at a time to +the caller. +The +.Fn is_keypad +function returns +.Dv TRUE +if the +.Fn +keypad +flag is set for the window specified by +.Fa win . +.Pp +The +.Fn has_key +function takes a key value and returns +.Dv TRUE +if the current terminal recognises a key with that value, otherwise +.Dv FALSE . +.Pp +Custom associations between sequences of characters and a key symbol can +be made by using the +.Fn define_key +function. +Normally, these associations are made by the information in the +.Xr terminfo 5 +database but the +.Fn define_key +function gives the capability to remove or add more associations. +If +.Fn define_key +is passed a non-NULL string in +.Fa sequence +it will associate that sequence with the key symbol passed in +.Fa key_symbol . +The key symbol may be one of the ones listed below or a custom value that +is application defined. +It is valid to have multiple character sequences map to the same key +symbol and there are no constraints on the length of the sequence allowed. +The assembly of custom sequences follow the same rules for inter-character +timing and so forth as the +.Xr terminfo 5 +derived ones. +If +.Fn define_key +is passed a NULL in +.Fa sequence +then all associations for the key symbol in +.Fa key_symbol +will be deleted, this includes any associations that were derived from +.Xr terminfo 5 . +.Pp +The +.Fn mvgetch +and +.Fn mvwgetch +functions are the same as the +.Fn getch +and +.Fn wgetch +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the character is read. +.Pp +Calling +.Fn getnstr , +.Fn wgetnstr , +.Fn mvgetnstr +or +.Fn mvwgetnstr +is effectively the same as calling +.Fn getch +repeatedly until a newline is received or the character limit +.Fa limit +is reached. +Once this happens the string is +.Dv NULL +terminated and returned in +.Fa str . +During input, the normal curses input key processing is performed and +affects the input buffer. +The +.Fn mvgetnstr +function calls +.Fn wmove +to move the cursor to the position given by +.Fa y , +.Fa x +before getting the string, +.Fn wgetnstr +reads the input from the designated window, +.Fn mvwgetnstr +moves the cursor to the position given by +.Fa y , +.Fa x +before getting the input from the designated window. +.Pp +The functions +.Fn getstr , +.Fn wgetstr , +.Fn mvgetstr , +and +.Fn mvwgetstr +are similar to +.Fn getnstr , +.Fn wgetnstr , +.Fn mvgetnstr , +and +.Fn mvwgetnstr , +respectively, excepting that there is no limit on the number of characters +that may be inserted into +.Fa str . +This may cause the buffer to be overflowed, so their use is not recommended. +.Pp +The +.Fn keypad +function is used to affect how +.Fn getch +processes input characters. +If +.Fa flag +is set to +.Dv TRUE , +then +.Fn getch +will scan the input stream looking for multi-character key sequences +that are emitted by some terminal function keys. +If a recognised sequence of characters is found, then +.Fn getch +will collapse that sequence into an integer key symbol, as shown below. +The default setting for the flag is +.Dv FALSE . +.Pp +The +.Fn notimeout +function controls whether or not +.Fn getch +will wait indefinitely between characters in a multi-character key +sequence or not. +If +.Fa flag +is +.Dv TRUE , +then there is no timeout applied between characters comprising a +multi-character key sequence. +If +.Fa flag +is +.Dv FALSE , +then the component characters of a multi-character sequence must not +have an inter-character gap of more than +.Va ESCDELAY . +If this timing is exceeded, then the multi-character key assembly is +deemed to have failed and the characters read thus far are returned +one at a time when +.Fn getch +is called. +The default setting for the flag is +.Dv FALSE . +The default value of +.Va ESCDELAY +is 300ms. +If +.Va ESCDELAY +is negative, no timeout is applied between characters comprising a +multi-character key sequence. +.Pp +The +.Fn timeout +function affects the behaviour of +.Fn getch +when reading a character from +.Va stdscr . +If +.Fa delay +is negative, then +.Fn getch +will block indefinitely on a read. +If +.Fa delay +is 0, then +.Fn getch +will return immediately with +.Dv ERR +if there are no characters immediately available. +If +.Fa delay +is a positive number, then +.Fn getch +will wait for that many milliseconds before returning and, if no character +was available, then +.Dv ERR +will be returned. +Note that for a positive number, the timeout is only accurate to the nearest +tenth of a second. +Also, the maximum value of +.Fa delay +is 25500 milliseconds. +The +.Fn wtimeout +function does the same as +.Fn timeout +but applies to the specified window +.Fa win . +.Pp +The +.Fn nodelay +function turns on and off blocking reads for +.Fn getch . +If +.Fa flag +is +.Dv TRUE , +then +.Fn getch +will not block on reads, if +.Fa flag +is +.Dv FALSE , +then reads will block. +The default setting for the flag is +.Dv FALSE . +.Fn nodelay win TRUE +is equivalent to +.Fn wtimeout win 0 +and +.Fn nodelay win FALSE +is equivalent to +.Fn wtimeout win \-1 . +.Pp +.Fn ungetch +will convert +.Fa c +into an unsigned char and push that character back onto the input stream. +Only one character of push-back is guaranteed to work, more may be possible +depending on system resources. +.Pp +The +.Fn set_escdelay +function sets the +.Va ESCDELAY +value of the current screen to +.Fa escdelay . +.Sh RETURN VALUES +The functions +.Fn getch , +.Fn wgetch , +.Fn mvgetch , +and +.Fn mvwgetch +will return the value of the key pressed or +.Dv ERR +in the case of an error or a timeout. +Additionally, if +.Fn keypad TRUE +has been called on a window, then it may return one of the following values: +.Pp +.Bl -column "Termcap entry" "getch Return Value" "Key Function" -offset indent +.It Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function" +.It \&!1 Ta KEY_SSAVE Ta Shift Save +.It \&!2 Ta KEY_SSUSPEND Ta Shift Suspend +.It \&!3 Ta KEY_SUNDO Ta Shift Undo +.It \ Ta KEY_SHELP Ta Shift Help +.It \ Ta KEY_SHOME Ta Shift Home +.It \ Ta KEY_SIC Ta Shift Insert Character +.It \ Ta KEY_SLEFT Ta Shift Left Arrow +.It \&%0 Ta KEY_REDO Ta Redo +.It \&%1 Ta KEY_HELP Ta Help +.It \&%2 Ta KEY_MARK Ta Mark +.It \&%3 Ta KEY_MESSAGE Ta Message +.It \&%4 Ta KEY_MOVE Ta Move +.It \&%5 Ta KEY_NEXT Ta Next Object +.It \&%6 Ta KEY_OPEN Ta Open +.It \&%7 Ta KEY_OPTIONS Ta Options +.It \&%8 Ta KEY_PREVIOUS Ta Previous Object +.It \&%9 Ta KEY_PRINT Ta Print +.It \&%a Ta KEY_SMESSAGE Ta Shift Message +.It \&%b Ta KEY_SMOVE Ta Shift Move +.It \&%c Ta KEY_SNEXT Ta Shift Next Object +.It \&%d Ta KEY_SOPTIONS Ta Shift Options +.It \&%e Ta KEY_SPREVIOUS Ta Shift Previous Object +.It \&%f Ta KEY_SPRINT Ta Shift Print +.It \&%g Ta KEY_SREDO Ta Shift Redo +.It \&%h Ta KEY_SREPLACE Ta Shift Replace +.It \&%i Ta KEY_SRIGHT Ta Shift Right Arrow +.It \&%j Ta KEY_SRSUME Ta Shift Resume +.It \&&0 Ta KEY_SCANCEL Ta Shift Cancel +.It \&&1 Ta KEY_REFERENCE Ta Reference +.It \&&2 Ta KEY_REFRESH Ta Refresh +.It \&&3 Ta KEY_REPLACE Ta Replace +.It \&&4 Ta KEY_RESTART Ta Restart +.It \&&5 Ta KEY_RESUME Ta Resume +.It \&&6 Ta KEY_SAVE Ta Save +.It \&&7 Ta KEY_SUSPEND Ta Suspend +.It \&&8 Ta KEY_UNDO Ta Undo +.It \&&9 Ta KEY_SBEG Ta Shift Begin +.It \&*0 Ta KEY_SFIND Ta Shift Find +.It \&*1 Ta KEY_SCOMMAND Ta Shift Command +.It \&*2 Ta KEY_SCOPY Ta Shift Copy +.It \&*3 Ta KEY_SCREATE Ta Shift Create +.It \&*4 Ta KEY_SDC Ta Shift Delete Character +.It \&*5 Ta KEY_SDL Ta Shift Delete Line +.It \&*6 Ta KEY_SELECT Ta Select +.It \&*7 Ta KEY_SEND Ta Shift End +.It \&*8 Ta KEY_SEOL Ta Shift Clear to EOL +.It \&*9 Ta KEY_SEXIT Ta Shift Exit +.It \&@0 Ta KEY_FIND Ta Find +.It \&@1 Ta KEY_BEG Ta Begin +.It \&@2 Ta KEY_CANCEL Ta Cancel +.It \&@3 Ta KEY_CLOSE Ta Close +.It \&@4 Ta KEY_COMMAND Ta Command +.It \&@5 Ta KEY_COPY Ta Copy +.It \&@6 Ta KEY_CREATE Ta Create +.It \&@7 Ta KEY_END Ta End +.It \&@8 Ta KEY_ENTER Ta Enter +.It \&@9 Ta KEY_EXIT Ta Exit +.It \&F1 Ta KEY_F(11) Ta Function Key 11 +.It \&F2 Ta KEY_F(12) Ta Function Key 12 +.It \&F3 Ta KEY_F(13) Ta Function Key 13 +.It \&F4 Ta KEY_F(14) Ta Function Key 14 +.It \&F5 Ta KEY_F(15) Ta Function Key 15 +.It \&F6 Ta KEY_F(16) Ta Function Key 16 +.It \&F7 Ta KEY_F(17) Ta Function Key 17 +.It \&F8 Ta KEY_F(18) Ta Function Key 18 +.It \&F9 Ta KEY_F(19) Ta Function Key 19 +.It \&FA Ta KEY_F(20) Ta Function Key 20 +.It \&FB Ta KEY_F(21) Ta Function Key 21 +.It \&FC Ta KEY_F(22) Ta Function Key 22 +.It \&FD Ta KEY_F(23) Ta Function Key 23 +.It \&FE Ta KEY_F(24) Ta Function Key 24 +.It \&FF Ta KEY_F(25) Ta Function Key 25 +.It \&FG Ta KEY_F(26) Ta Function Key 26 +.It \&FH Ta KEY_F(27) Ta Function Key 27 +.It \&FI Ta KEY_F(28) Ta Function Key 28 +.It \&FJ Ta KEY_F(29) Ta Function Key 29 +.It \&FK Ta KEY_F(30) Ta Function Key 30 +.It \&FL Ta KEY_F(31) Ta Function Key 31 +.It \&FM Ta KEY_F(32) Ta Function Key 32 +.It \&FN Ta KEY_F(33) Ta Function Key 33 +.It \&FO Ta KEY_F(34) Ta Function Key 34 +.It \&FP Ta KEY_F(35) Ta Function Key 35 +.It \&FQ Ta KEY_F(36) Ta Function Key 36 +.It \&FR Ta KEY_F(37) Ta Function Key 37 +.It \&FS Ta KEY_F(38) Ta Function Key 38 +.It \&FT Ta KEY_F(39) Ta Function Key 39 +.It \&FU Ta KEY_F(40) Ta Function Key 40 +.It \&FV Ta KEY_F(41) Ta Function Key 41 +.It \&FW Ta KEY_F(42) Ta Function Key 42 +.It \&FX Ta KEY_F(43) Ta Function Key 43 +.It \&FY Ta KEY_F(44) Ta Function Key 44 +.It \&FZ Ta KEY_F(45) Ta Function Key 45 +.It \&Fa Ta KEY_F(46) Ta Function Key 46 +.It \&Fb Ta KEY_F(47) Ta Function Key 47 +.It \&Fc Ta KEY_F(48) Ta Function Key 48 +.It \&Fd Ta KEY_F(49) Ta Function Key 49 +.It \&Fe Ta KEY_F(50) Ta Function Key 50 +.It \&Ff Ta KEY_F(51) Ta Function Key 51 +.It \&Fg Ta KEY_F(52) Ta Function Key 52 +.It \&Fh Ta KEY_F(53) Ta Function Key 53 +.It \&Fi Ta KEY_F(54) Ta Function Key 54 +.It \&Fj Ta KEY_F(55) Ta Function Key 55 +.It \&Fk Ta KEY_F(56) Ta Function Key 56 +.It \&Fl Ta KEY_F(57) Ta Function Key 57 +.It \&Fm Ta KEY_F(58) Ta Function Key 58 +.It \&Fn Ta KEY_F(59) Ta Function Key 59 +.It \&Fo Ta KEY_F(60) Ta Function Key 60 +.It \&Fp Ta KEY_F(61) Ta Function Key 61 +.It \&Fq Ta KEY_F(62) Ta Function Key 62 +.It \&Fr Ta KEY_F(63) Ta Function Key 63 +.It \&K1 Ta KEY_A1 Ta Upper left key in keypad +.It \&K2 Ta KEY_B2 Ta Centre key in keypad +.It \&K3 Ta KEY_A3 Ta Upper right key in keypad +.It \&K4 Ta KEY_C1 Ta Lower left key in keypad +.It \&K5 Ta KEY_C3 Ta Lower right key in keypad +.It \&Km Ta KEY_MOUSE Ta Mouse Event +.It \&k0 Ta KEY_F0 Ta Function Key 0 +.It \&k1 Ta KEY_F(1) Ta Function Key 1 +.It \&k2 Ta KEY_F(2) Ta Function Key 2 +.It \&k3 Ta KEY_F(3) Ta Function Key 3 +.It \&k4 Ta KEY_F(4) Ta Function Key 4 +.It \&k5 Ta KEY_F(5) Ta Function Key 5 +.It \&k6 Ta KEY_F(6) Ta Function Key 6 +.It \&k7 Ta KEY_F(7) Ta Function Key 7 +.It \&k8 Ta KEY_F(8) Ta Function Key 8 +.It \&k9 Ta KEY_F(9) Ta Function Key 9 +.It \&k; Ta KEY_F(10) Ta Function Key 10 +.It \&kA Ta KEY_IL Ta Insert Line +.It \&ka Ta KEY_CATAB Ta Clear All Tabs +.It \&kB Ta KEY_BTAB Ta Back Tab +.It \&kb Ta KEY_BACKSPACE Ta Backspace +.It \&kC Ta KEY_CLEAR Ta Clear +.It \&kD Ta KEY_DC Ta Delete Character +.It \&kd Ta KEY_DOWN Ta Down Arrow +.It \&kE Ta KEY_EOL Ta Clear to End Of Line +.It \&kF Ta KEY_SF Ta Scroll Forward one line +.It \&kH Ta KEY_LL Ta Home Down +.It \&kh Ta KEY_HOME Ta Home +.It \&kI Ta KEY_IC Ta Insert Character +.It \&kL Ta KEY_DL Ta Delete Line +.It \&kl Ta KEY_LEFT Ta Left Arrow +.It \&kM Ta KEY_EIC Ta Exit Insert Character Mode +.It \&kN Ta KEY_NPAGE Ta Next Page +.It \&kP Ta KEY_PPAGE Ta Previous Page +.It \&kR Ta KEY_SR Ta Scroll One Line Back +.It \&kr Ta KEY_RIGHT Ta Right Arrow +.It \&kS Ta KEY_EOS Ta Clear to End Of Screen +.It \&kT Ta KEY_STAB Ta Set Tab +.It \&kt Ta KEY_CTAB Ta Clear Tab +.It \&ku Ta KEY_UP Ta Up Arrow +.El +.Pp +Note that not all terminals are capable of generating all the keycodes +listed above nor are terminfo entries normally configured with all the +above capabilities defined. +.Pp +Other functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Pp +Functions returning pointers will return +.Dv NULL +if an error is detected. +.Sh SEE ALSO +.Xr curses_cursor 3 , +.Xr curses_keyname 3 , +.Xr curses_refresh 3 , +.Xr curses_tty 3 , +.Xr terminfo 5 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh NOTES +The +.Fn keyok +and +.Fn define_key +functions are implementations of extensions made by the NCurses library +to the Curses standard. +Portable implementations should avoid the use of these functions. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn is_keypad +and +.Fn set_tabsize +functions are +.Em ncurses +extension to the Curses library and was added in +.Nx 8.0 . diff --git a/static/netbsd/man3/curses_insch.3 b/static/netbsd/man3/curses_insch.3 new file mode 100644 index 00000000..5807c809 --- /dev/null +++ b/static/netbsd/man3/curses_insch.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: curses_insch.3,v 1.3 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 25, 2018 +.Dt CURSES_INSCH 3 +.Os +.Sh NAME +.Nm curses_insch , +.Nm insch , +.Nm winsch , +.Nm mvinsch , +.Nm mvwinsch +.Nd curses insert characters routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn insch "chtype ch" +.Ft int +.Fn winsch "WINDOW *win" "chtype ch" +.Ft int +.Fn mvinsch "int y" "int x" "chtype ch" +.Ft int +.Fn mvwinsch "WINDOW *win" "int y" "int x" "chtype ch" +.Sh DESCRIPTION +These functions insert characters on +.Va stdscr +or on the specified window. +.Pp +The +.Fn insch +function inserts the character given in +.Fa ch +at the current cursor position on +.Va stdscr . +The cursor is not advanced and wrapping is not performed. +.Pp +The +.Fn winsch +function is the same as the +.Fn insch +function, excepting that the character is inserted on the window specified by +.Fa win . +.Pp +The +.Fn mvinsch +and +.Fn mvwinsch +functions are the same as the +.Fn insch +and +.Fn insch +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the character is inserted on the window. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_addch 3 , +.Xr curses_cursor 3 , +.Xr curses_delch 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_insdelln.3 b/static/netbsd/man3/curses_insdelln.3 new file mode 100644 index 00000000..2b60c5bb --- /dev/null +++ b/static/netbsd/man3/curses_insdelln.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: curses_insdelln.3,v 1.4 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 12, 2002 +.Dt CURSES_INSDEL 3 +.Os +.Sh NAME +.Nm curses_insdelln , +.Nm insdelln , +.Nm winsdelln +.Nd curses insert or delete lines routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn insdelln "int n" +.Ft int +.Fn winsdelln "WINDOW *win" "int n" +.Sh DESCRIPTION +These functions insert or delete lines on +.Va stdscr +or on the specified window. +.Pp +If +.Fn insdelln +is called with a positive number in +.Fa n , +then the specified number of lines are inserted before the current line on +.Va stdscr . +The last +.Fa n +lines of the screen are no longer displayed. +If +.Fa n +is negative, then +.Fa n +lines are deleted from +.Va stdscr , +starting at the current line. +The last +.Fa n +lines of +.Va stdscr +are cleared. +.Pp +The +.Fn winsdelln +function is the same as the +.Fn insdelln +function, excepting that lines are inserted or deleted from the window +specified by +.Fa win . +.Pp +If a scrolling region has been set with the +.Fn setscrreg +or +.Fn wsetscrreg +functions and the current cursor position is inside the scrolling region, +then only the lines from the current line to the bottom of the scrolling +region are affected. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_deleteln 3 , +.Xr curses_insertln 3 , +.Xr curses_scroll 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_insertln.3 b/static/netbsd/man3/curses_insertln.3 new file mode 100644 index 00000000..fd324840 --- /dev/null +++ b/static/netbsd/man3/curses_insertln.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: curses_insertln.3,v 1.5 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd February 5, 2006 +.Dt CURSES_INSERTLN 3 +.Os +.Sh NAME +.Nm curses_insertln , +.Nm insertln , +.Nm winsertln +.Nd curses insert single line routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn insertln "void" +.Ft int +.Fn winsertln "WINDOW *win" +.Sh DESCRIPTION +These functions insert a single line on +.Va stdscr +or on the specified window. +.Pp +The +.Fn insertln +function inserts a blank line before the current line on +.Va stdscr . +The current line and all lines below are moved down one line away from +the cursor and the bottom line of the window is lost. +.Pp +The +.Fn winsertln +function is the same as the +.Fn insertln +function, excepting that the line is inserted on the window +.Fa win . +.Pp +If a scrolling region has been set with the +.Fn setscrreg +or +.Fn wsetscrreg +functions and the current cursor position is inside the scrolling region, +then only the lines from the current line to the bottom of the scrolling +region are moved down and the bottom line of the scrolling region lost. +.Pp +The functions +.Fn insertln +and +.Fn winsertln win +are equivalent to +.Fn insdelln 1 +and +.Fn winsdelln win 1 , +respectively. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_deleteln 3 , +.Xr curses_insdelln 3 , +.Xr curses_scroll 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_keyname.3 b/static/netbsd/man3/curses_keyname.3 new file mode 100644 index 00000000..bb0bda0d --- /dev/null +++ b/static/netbsd/man3/curses_keyname.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: curses_keyname.3,v 1.5 2008/04/30 13:10:51 martin Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 17, 2007 +.Dt CURSES_KEYNAME 3 +.Os +.Sh NAME +.Nm curses_keyname , +.Nm keyname +.Nd curses report key name routine +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft "char *" +.Fn keyname "int key" +.Sh DESCRIPTION +The function +.Fn keyname +generates a character string containing a description of the key specified in +.Fa key . +.Pp +The string is formatted according to the following table: +.Bl -column "Meta + control character" "KEY_MIN - KEY_MAX" "String format" +.It "Description" Ta "Key range" Ta "String format" +.It Li "Control character" Ta "0 - 31" Ta "^X" +.It Li "Visible character" Ta "32 - 126" Ta "X" +.It Li "Delete character" Ta "127" Ta "^?" +.It Li "Meta + control character" Ta "128 - 158" Ta "M-^X" +.It Li "Meta + visible character" Ta "159 - 254" Ta "M-X" +.It Li "Meta + delete character" Ta "255" Ta "M-^?" +.It Li "Named key" Ta "KEY_MIN - KEY_MAX" Ta "KEY_EXIT" +.It Li "Unknown key" Ta "" Ta "-1" +.El +.Sh SEE ALSO +.Xr curses_input 3 +.Sh NOTE +The return value of +.Fn keyname +is a static buffer, which will be overwritten on a subsequent call. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +These functions first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/curses_line.3 b/static/netbsd/man3/curses_line.3 new file mode 100644 index 00000000..0df9b741 --- /dev/null +++ b/static/netbsd/man3/curses_line.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: curses_line.3,v 1.7 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd February 19, 2010 +.Dt CURSES_LINE 3 +.Os +.Sh NAME +.Nm curses_line , +.Nm hline , +.Nm whline , +.Nm vline , +.Nm wvline , +.Nm mvhline , +.Nm mvwhline , +.Nm mvvline , +.Nm mvwvline +.Nd curses draw lines on windows routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn hline "chtype ch" "int n" +.Ft int +.Fn whline "WINDOW *win" "chtype ch" "int n" +.Ft int +.Fn mvhline "int y" "int x" "chtype ch" "int n" +.Ft int +.Fn mvwvline "WINDOW *win" "int y" "int x" "chtype c" "int n" +.Ft int +.Fn vline "chtype c" "int n" +.Ft int +.Fn wvline "WINDOW *win" "chtype c" "int n" +.Ft int +.Fn mvvline "int y" "int x" "chtype ch" "int n" +.Ft int +.Fn mvwhline "WINDOW *win" "int y" "int x" "chtype c" "int n" +.Sh DESCRIPTION +These functions draw lines on +.Va stdscr +or on the specified window. +.Pp +The +.Fn hline +function draws a horizontal line of the character +.Fa ch +on +.Va stdscr +starting at the current cursor position and extending for +.Fa n +characters, or until the right hand side of +.Va stdscr +is reached. +If the text portion of +.Fa ch +is 0 then the line will be drawn with the +.Dv ACS_HLINE +character. +.Pp +The +.Fn whline +function is the same as the +.Fn hline +function, excepting that the line is drawn in the window specified by +.Fa win . +.Pp +The +.Fn vline +function draws a vertical line of character +.Fa ch +on +.Va stdscr +starting at the current cursor position and moving down until either +.Fa n +characters have been drawn or the bottom of +.Va stdscr +is reached. +If the text portion of +.Fa ch +is 0 then the line will be drawn with the +.Dv ACS_VLINE +character. +.Pp +The +.Fn wvline +function is the same as the +.Fn vline +function, excepting that the line is drawn on the given window. +.Pp +The +.Fn mvhline , +.Fn mvwhline , +.Fn mvvline +and +.Fn mvwvline +functions are the same as the +.Fn hline , +.Fn whline , +.Fn vline +and +.Fn wvline +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the line is drawn on the window. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_border 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of +the Single Unix Specification. +.Pp +The use of +.Dv ACS_HLINE +and +.Dv ACS_VLINE +as default drawing character in +.Fn hline +and +.Fn vline +is a +.Nx +extension which should not be relied on in portable code. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_mouse.3 b/static/netbsd/man3/curses_mouse.3 new file mode 100644 index 00000000..05e1e15c --- /dev/null +++ b/static/netbsd/man3/curses_mouse.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: curses_mouse.3,v 1.2 2020/03/23 16:14:20 wiz Exp $ +.\" +.\" Copyright (c) 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd March 22, 2020 +.Dt CURSES_MOUSE 3 +.Os +.Sh NAME +.Nm has_mouse , +.Nm getmouse , +.Nm ungetmouse , +.Nm mousemask , +.Nm wenclose , +.Nm mouse_trafo , +.Nm wmouse_trafo , +.Nm mouseinterval +.Nd Curses mouse interface +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft bool +.Fn has_mouse "void" +.Ft int +.Fn getmouse "MEVENT *event" +.Ft int +.Fn ungetmouse "MEVENT *event" +.Ft mmask_t +.Fn mousemask "mmask_t newmask" "mmask_t *oldmask" +.Ft bool +.Fn wenclose "const WINDOW *win" "int y" "int x" +.Ft bool +.Fn mouse_trafo "int *y" "int *x" "bool to_screen" +.Ft bool +.Fn wmouse_trafo "const WINDOW *win" "int *y" "int *x" "bool to_screen" +.Ft int +.Fn mouseinterval "int erval" +.Sh DESCRIPTION +This is the curses interface to mouse events. +Mouse events are reported via the +.Dv KEY_MOUSE +value in the +.Xr wgetch 3 +input stream. +.Pp +The +.Fn has_mouse +function returns true if the mouse support has been initialised for the +terminal, otherwise false. +.Pp +The +.Fn getmouse +function reads a mouse event. +The +.Fa x +and +.Fa y +values are screen relative and the state mask will have exactly one bit set +to represent the event type. +The +.Fn ungetmouse +function behave like +.Xr ungetch 3 +and pushes the mouse event into the input stream. +.Pp +The +.Fn mousemask +function sets the mouse events to be reported. +By default, there are no mouse events reported. +It returns a mask indicating which of the specified mouse events can be +reported, zero indicating a failure. +If oldmask is given, it is filled with the previous mouse event mask. +.Pp +The +.Fn wenclose +function returns true if the screen relative +.Fa x +and +.Fa y +co-ordinates are enclosed by the window +.Fa win , +otherwise false. +.Pp +The +.Fn wmouse_trafo +function transforms the +.Fa x +and +.Fa y +co-ordinates from screen relative to window relative or vice versa +depending on the value of +.Fa to_screen . +If the co-ordinates are not enclosed by the window +.Fa win +then false is returned, otherwise the +.Fa x +and +.Fa y +values are transformed and true is returned. +The +.Fn mouse_trainfo +function calls +.Fn wmouse_trainfo +using +.Va stdscr +for +.Fa win . +.Pp +The +.Fn mouseinterval +function sets the maximum time that can elapse between press and release +events, which determins a click. +The value is in thousands of seconds. +The default value is one fifth of a second. +The returned value is the old value. +.Sh RETURN VALUES +Unless otherwise noted, the functions that return an int will return one of +the following values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr wsmouse 4 +.Sh STANDARDS +These functions are ncurses extensions to the Curses library. +.Sh HISTORY +The mouse functions were added in +.Nx 10.0 . +.Sh BUGS +There is currently no actual mouse support, +.Fn has_mouse +will always return false. diff --git a/static/netbsd/man3/curses_pad.3 b/static/netbsd/man3/curses_pad.3 new file mode 100644 index 00000000..d2e6b00f --- /dev/null +++ b/static/netbsd/man3/curses_pad.3 @@ -0,0 +1,156 @@ +.\" $NetBSD: curses_pad.3,v 1.6 2017/01/05 23:15:43 roy Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 5, 2016 +.Dt CURSES_PAD 3 +.Os +.Sh NAME +.Nm curses_pad , +.Nm newpad , +.Nm subpad , +.Nm prefresh , +.Nm pnoutrefresh +.Nd curses pad routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft WINDOW * +.Fn newpad "int lines" "int cols" +.Ft WINDOW * +.Fn subpad "WINDOW *pad" "int lines" "int cols" "int begin_y" "int begin_x" +.Ft int +.Fn prefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x" +.Ft int +.Fn pnoutrefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x" +.Ft bool +.Fn is_pad "const WINDOW *pad" +.Sh DESCRIPTION +These functions create and display pads on the current screen. +.Pp +The +.Fn newpad +function creates a new pad of size +.Fa lines , +.Fa cols . +.Pp +.Fn subpad +is similar to +.Fn newpad +excepting that the size of the subpad is bounded by the parent +pad +.Fa pad . +The subpad shares internal data structures with the parent pad +and will be refreshed when the parent pad is refreshed. +The starting column and row +.Fa begin_y , +.Fa begin_x +are relative to the parent pad origin. +.Pp +The +.Fn pnoutrefresh +function performs the internal processing required by curses to determine +what changes need to be made to synchronise the internal screen buffer +and the terminal but does not modify the terminal display. +A rectangular area of the pad starting at column and row +.Fa pbeg_y , +.Fa pbeg_x +is copied to the corresponding rectangular area of the screen buffer starting +at column and row +.Fa sbeg_y , +.Fa sbeg_x +and extending to +.Fa smax_y , +.Fa smax_x . +.Pp +The +.Fn prefresh +function causes curses to propagate changes made to the pad specified by +.Fa pad +to the terminal display. +A rectangular area of the pad starting at column and row +.Fa pbeg_y , +.Fa pbeg_x +is copied to the corresponding rectangular area of the terminal starting +at column and row +.Fa sbeg_y , +.Fa sbeg_x +and extending to +.Fa smax_y , +.Fa smax_x . +.Pp +The +.Fn pnoutrefresh +and +.Fn doupdate +functions can be used together to speed up terminal redraws by +deferring the actual terminal updates until after a batch of updates +to multiple pads has been done. +.Pp +The +.Fn is_pad +function returns true if the given window was created by +.Fn newpad , +otherwise false. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_refresh 3 , +.Xr curses_window 3 +.Sh NOTES +The +.Fn subpad +function is similar to the +.Xr derwin 3 +function, and not the +.Xr subwin 3 +function. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn is_pad +function is a +.Em ncurses +extension to the Curses library and was added in +.Nx 8.0 . diff --git a/static/netbsd/man3/curses_print.3 b/static/netbsd/man3/curses_print.3 new file mode 100644 index 00000000..20a7d966 --- /dev/null +++ b/static/netbsd/man3/curses_print.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: curses_print.3,v 1.8 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd April 6, 2011 +.Dt CURSES_PRINT 3 +.Os +.Sh NAME +.Nm curses_print , +.Nm printw , +.Nm wprintw , +.Nm mvprintw , +.Nm mvwprintw , +.Nm unctrl +.Nd curses print formatted strings on windows routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn printw "const char *fmt" "..." +.Ft int +.Fn wprintw "WINDOW *win" "const char *fmt" "..." +.Ft int +.Fn mvprintw "int y" "int x" "const char *fmt" "..." +.Ft int +.Fn mvwprintw "WINDOW *win" "int y" "int x" "const char *fmt" "..." +.Ft char * +.Fn unctrl "chtype ch" +.Sh DESCRIPTION +These functions print formatted strings on +.Va stdscr +or on the specified window. +.Pp +The +.Fn printw +function formats and prints its arguments on +.Va stdscr . +The behavior is deliberately similar to that of +.Xr printf 3 , +but, notably, the return value differs. +.Pp +The +.Fn wprintw +function is the same as the +.Fn printw +function, excepting that the resulting output is printed on the window +specified by +.Fa win . +.Pp +The +.Fn mvprintw +and +.Fn mvwprintw +functions are the same as the +.Fn printw +and +.Fn wprintw +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the output is printed on the window. +.Pp +The +.Fn unctrl +function returns a printable string representation of the character +.Fa ch . +If +.Fa ch +is a control character then it will be converted to the form ^Y. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -offset indent +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_cursor 3 , +.Xr curses_scanw 3 , +.Xr printf 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_refresh.3 b/static/netbsd/man3/curses_refresh.3 new file mode 100644 index 00000000..be8a3f11 --- /dev/null +++ b/static/netbsd/man3/curses_refresh.3 @@ -0,0 +1,179 @@ +.\" $NetBSD: curses_refresh.3,v 1.14 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd January 2, 2017 +.Dt CURSES_REFRESH 3 +.Os +.Sh NAME +.Nm curses_refresh , +.Nm refresh , +.Nm wrefresh , +.Nm wnoutrefresh , +.Nm doupdate , +.Nm immedok , +.Nm flushok , +.Nm leaveok , +.Nm is_leaveok +.Nd curses terminal update routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn refresh "void" +.Ft int +.Fn wrefresh "WINDOW *win" +.Ft int +.Fn wnoutrefresh "WINDOW *win" +.Ft int +.Fn doupdate "void" +.Ft int +.Fn immedok "WINDOW *win" "boolf flag" +.Ft int +.Fn flushok "WINDOW *win" "boolf flag" +.Ft int +.Fn leaveok "WINDOW *win" "boolf flag" +.Ft bool +.Fn is_leaveok "const WINDOW *win" +.Sh DESCRIPTION +These functions update the terminal with the contents of +.Va stdscr +or of the specified window(s). +.Pp +The +.Fn refresh +function causes curses to propagate changes made to +.Va stdscr +to the terminal display. +Any changes made to subwindows of +.Va stdscr +are also propagated. +.Pp +The +.Fn wrefresh +function is the same as the +.Fn refresh +function, excepting that changes are propagated to the terminal from the +window specified by +.Fa win . +.Pp +The +.Fn wnoutrefresh +function performs the internal processing required by curses to determine +what changes need to be made to synchronise the internal screen buffer +and the terminal but does not modify the terminal display. +.Pp +The +.Fn doupdate +function updates the terminal display to match the internal curses +representation of the display. +.Pp +The +.Fn wnoutrefresh +and +.Fn doupdate +functions can be used together to speed up terminal redraws by +deferring the actual terminal updates until after a batch of updates +to multiple windows has been done. +.Pp +The +.Fn refresh +function is equivalent to +.Fn wnoutrefresh stdscr +followed by +.Fn doupdate . +.Pp +The +.Fn immedok +function determines whether the screen is refreshed whenever the window is +changed. +The initial state is +.Dv FALSE . +.Pp +The +.Fn flushok +function is used to determine whether or not the screen's output file +descriptor will be flushed on refresh. +Setting +.Fa flag +to +.Dv TRUE +will cause the output to be flushed. +.Pp +The +.Fn leaveok +function determines whether refresh operations may leave the screen cursor +in an arbitrary position on the screen. +Setting +.Fa flag +to +.Dv FALSE +ensures that the screen cursor is positioned at the current cursor +position after a refresh operation has taken place. +The +.Fn is_leaveok +function returns the setting. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_pad 3 , +.Xr curses_touch 3 , +.Xr getch 3 +.Sh NOTES +Calling +.Fn wrefresh +on a new, unchanged window has no effect. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn is_leaveok +function is a +.Em ncurses +extension to the Curses library and was added in +.Nx 8.0 . diff --git a/static/netbsd/man3/curses_scanw.3 b/static/netbsd/man3/curses_scanw.3 new file mode 100644 index 00000000..ce7cbcd1 --- /dev/null +++ b/static/netbsd/man3/curses_scanw.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: curses_scanw.3,v 1.6 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 12, 2002 +.Dt CURSES_SCANW 3 +.Os +.Sh NAME +.Nm curses_scanw , +.Nm scanw , +.Nm wscanw , +.Nm mvscanw , +.Nm mvwscanw +.Nd curses read formatted data from screen routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn scanw "const char *fmt" "..." +.Ft int +.Fn wscanw "WINDOW *win" "const char *fmt" "..." +.Ft int +.Fn mvscanw "int y" "int x" "const char *fmt" "..." +.Ft int +.Fn mvwscanw "WINDOW *win" "int y" "int x" "const char *fmt" "..." +.Sh DESCRIPTION +These functions read formatted data from +.Va stdscr +or from the specified window. +.Pp +The +.Fn scanw +function is the same as the +.Fn scanf +function, excepting that the input data stream is read from the current +cursor position on +.Va stdscr , +.Pp +The +.Fn wscanw +function is the same +as the +.Fn scanw +function, excepting that the data stream is read from the window specified by +.Fa win . +.Pp +The +.Fn mvscanw +and +.Fn mvwscanw +functions are the same as the +.Fn scanw +and +.Fn mvscanw +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the data is read from the window. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_cursor 3 , +.Xr curses_print 3 , +.Xr scanf 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_screen.3 b/static/netbsd/man3/curses_screen.3 new file mode 100644 index 00000000..d01ad8c6 --- /dev/null +++ b/static/netbsd/man3/curses_screen.3 @@ -0,0 +1,317 @@ +.\" $NetBSD: curses_screen.3,v 1.30 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd May 16, 2024 +.Dt CURSES_SCREEN 3 +.Os +.Sh NAME +.Nm curses_screen , +.Nm filter , +.Nm ripoffline , +.Nm use_env , +.Nm newterm , +.Nm set_term , +.Nm delscreen , +.Nm endwin , +.Nm initscr , +.Nm isendwin , +.Nm is_term_resized , +.Nm resize_term , +.Nm resizeterm , +.Nm setterm , +.Nm set_tabsize +.Nd curses terminal and screen routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft void +.Fn filter "void" +.Ft int +.Fn ripoffline "int line" "int (*init)(WINDOW *win, int cols)" +.Ft void +.Fn use_env "bool value" +.Ft SCREEN * +.Fn newterm "const char *type" "FILE *outfd" "FILE *infd" +.Ft SCREEN * +.Fn set_term "SCREEN *screen" +.Ft void +.Fn delscreen "SCREEN *screen" +.Ft int +.Fn endwin "void" +.Ft WINDOW * +.Fn initscr "void" +.Ft bool +.Fn isendwin "void" +.Ft bool +.Fn is_term_resized "int lines" "int cols" +.Ft int +.Fn resize_term "int lines" "int cols" +.Ft int +.Fn resizeterm "int lines" "int cols" +.Ft int +.Fn setterm "const char *name" +.Ft int +.Fn set_tabsize "int value" +.Pp +.Va extern int LINES ; +.Pp +.Va extern int COLS ; +.Sh DESCRIPTION +These functions initialize terminals and screens. +.Pp +The +.Fn newterm +function initialises the curses data structures and pointers ready for +use by curses. +The +.Fa type +argument points to a +.Xr terminfo 5 +entry, or it may be +.Dv NULL +in which case the +.Ev TERM +environment variable is used. +The +.Fa outfd +and +.Fa infd +are the output and input file descriptors for the terminal. +The +.Fn newterm +function must only be called once per terminal. +.Pp +The +.Fn set_term +function can be used to switch between the screens defined by calling +.Fn newterm , +a pointer to the previous screen structure that was in use will be +returned on success. +.Pp +Calling +.Fn delscreen +will destroy the given screen and free all allocated resources. +.Pp +Calling +.Fn endwin +will end the curses session and restore the saved terminal settings. +.Pp +The curses session must be initialised by calling +.Fn initscr +which saves the current terminal state and sets up the terminal and +internal data structures to support the curses application. +This +function call must be, with few exceptions, the first Curses library +call made. +The exception to this rule is the +.Fn newterm +call which may be called prior to +.Fn initscr . +The size of the curses screen is determined by checking the +.Xr tty 4 +size and then the +.Xr terminfo 5 +entries for the terminal type. +If the environment variables +.Ev LINES +or +.Ev COLUMNS +are set, then these will be used instead. +.Pp +When either +.Fn newterm +or +.Fn initscr +are called, the Curses library sets up signal handlers for +.Dv SIGTSTP +and +.Dv SIGWINCH . +If a signal handler is already installed for +.Dv SIGWINCH , +this will also be called when the Curses library handler is called. +.Pp +The +.Fn isendwin +function can be used to determine whether or not a refresh of the +screen has occurred since the last call to +.Fn endwin . +.Pp +The size of the screen may be changed by calling +.Fn resize_term +with the updated number of lines and columns. +This will resize the curses internal data structures to accommodate the +changed terminal geometry. +The +.Dv curscr +and +.Va stdscr +windows and any of their subwindows will be resized to fit the new +screen size. +The application must redraw the screen after a call to +.Fn resize_term . +The +.Fn resizeterm +function is a wrapper for +.Fn resize_term +and adjusts other structure data that handles window dimensions. +The +.Fn is_term_resized +function tests if either of the above functions need to be called. +.Pp +The +.Fn setterm +function sets the terminal type for the current screen to the one +passed, initialising all the curses internal data structures with +information related to the named terminal. +The +.Fa name +argument must be a valid name or alias in the +.Xr terminfo 5 +database for this function to succeed. +.Pp +The +.Fn filter +function changes the way the terminal is initialised. +A subsequent call to +.Fn initscr +or +.Fn newterm +performs the following additional actions: +.Bl -bullet -compact +.It +Disable use of clear, cud, cud1, cup, cuu, cuu1 and vpa. +.It +Set the value of the home string to the value of the cr string. +.It +Set lines equal to 1. +.El +.Pp +The +.Fn ripoffline +function will rip a line from +.Va stdscr +at the top if +.Fa line +is positive, or at the bottom if negative. +When +.Fn initscr +or +.Fn newterm +is called, a window will be created for each line ripped and passed +to the +.Fa init +function pointer alongwith the number of columns in the window. +This init function cannot use the +.Dv LINES +or +.Dv COLS +variables and cannot call +.Xr wrefresh 3 +or +.Xr doupdate 3 , +but may call +.Xr wnoutrefresh 3 . +.Fn ripoffline +can be called up to five times. +.Pp +The +.Fn use_env +function determines whether the environment variables +.Ev LINES +and +.Ev COLUMNS +override the normal values. +The default is true. +Any call to +.Fn use_env +must precede calls to +.Fn initscr , +.Fn newterm , +or +.Fn setupterm . +.Pp +The +.Fn set_tabsize +function will set +.Va TABSIZE +of the current screen to +.Va tabsize . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected with the exception of +.Fn initscr +which will log a diagnostic to standard error output and then call +.Xr exit 3 . +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_window 3 , +.Xr tty 4 , +.Xr terminfo 5 , +.Xr signal 7 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn resizeterm +function is an +.Em ncurses +extension to the Curses library and was added in +.Nx 1.6 . +The +.Fn is_term_resized , +.Fn resize_term +and +.Fn set_tabsize +functions are +.Em ncurses +extensions to the Curses library and were added in +.Nx 8.0 . +.Sh BUGS +There is currently an issue with cursor movement in a 1 line sized window +which causes the screen to scroll up. +This can obviously be seen when using +.Fn ripoffline . diff --git a/static/netbsd/man3/curses_scroll.3 b/static/netbsd/man3/curses_scroll.3 new file mode 100644 index 00000000..9bf62b0f --- /dev/null +++ b/static/netbsd/man3/curses_scroll.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: curses_scroll.3,v 1.7 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd December 31, 2024 +.Dt CURSES_SCROLL 3 +.Os +.Sh NAME +.Nm curses_scroll , +.Nm getscrreg , +.Nm scrl , +.Nm wscrl +.Nm scroll , +.Nm scrollok , +.Nm setscrreg , +.Nm wgetscrreg +.Nm wsetscrreg +.Nd curses window scrolling routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn getscrreg "int *top" "int *bottom" +.Ft int +.Fn scrl "int n" +.Ft int +.Fn wscrl "WINDOW *win" "int n" +.Ft int +.Fn scroll "WINDOW *win" +.Ft int +.Fn scrollok "WINDOW *win" "boolf flag" +.Ft int +.Fn setscrreg "int top" "int bottom" +.Ft int +.Fn wgetscrreg "WINDOW *win" "int *top" "int *bottom" +.Ft int +.Fn wsetscrreg "WINDOW *win" "int top" "int bottom" +.Sh DESCRIPTION +The +.Fn getscrreg +function gets the software scrolling region lines on +.Va stdscr +which defines a region of the screen that will be scrolled. +.Pp +These functions scroll areas on +.Va stdscr +or on the specified window. +.Pp +The +.Fn scrl +function scrolls +.Va stdscr +by +.Fa n +lines. +If +.Fa n +is positive then then +.Va stdscr +is scrolled up. +.Fa n +lines are lost from the top of +.Va stdscr +and +.Fa n +blank lines are inserted at the bottom. +If +.Fa n +is negative then +.Va stdscr +is scrolled down. +.Fa n +blank lines are inserted at the top of +.Va stdscr +and +.Fa n +lines are lost from the bottom. +.Pp +The +.Fn wscrl +function is the same as the +.Fn scrl +function, excepting that it scrolls the window specified by +.Fa win . +.Pp +The +.Fn scroll +function scrolls the window +.Fa win +up by one line. +.Pp +The scrolling behaviour of a window can be controlled by using the +.Fn scrollok +function. +If the +.Fa flag +argument is +.Dv TRUE +then a line wrap at the bottom of the window will cause the window to +be scrolled up one line, if +.Fa flag +is +.Dv FALSE +then lines that would force a scroll will be truncated. +.Pp +The +.Fn setscrreg +function sets up a software scrolling region on +.Va stdscr +which will define a region of the screen that will be scrolled. +The scrolling of this region is also controlled by the +.Fn scrollok +function. +.Pp +The +.Fn wgetscrreg +function does the same as the +.Fn getscrreg +function, except that the scrolling region is retrieved from the window +specified by +.Fa win . +.Pp +The +.Fn wsetscrreg +function does the same as the +.Fn setscrreg +function, except that the scrolling region is set on the window specified by +.Fa win . +.Pp +If a scrolling region has been set with the +.Fn setscrreg +or +.Fn wsetscrreg +functions and the current cursor position is inside the scrolling region, +then only the area inside the scrolling region is scrolled. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_deleteln 3 , +.Xr curses_insdelln 3 , +.Xr curses_insertln 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_slk.3 b/static/netbsd/man3/curses_slk.3 new file mode 100644 index 00000000..cec86dcb --- /dev/null +++ b/static/netbsd/man3/curses_slk.3 @@ -0,0 +1,244 @@ +.\" $NetBSD: curses_slk.3,v 1.3 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2017 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd September 29, 2018 +.Dt CURSES_SLK 3 +.Os +.Sh NAME +.Nm slk_attroff , +.Nm slk_attr_off , +.Nm slk_attron , +.Nm slk_attr_on , +.Nm slk_attrset , +.Nm slk_attr_set , +.Nm slk_clear , +.Nm slk_color , +.Nm slk_init , +.Nm slk_label , +.Nm slk_noutrefresh , +.Nm slk_refresh , +.Nm slk_restore , +.Nm slk_set , +.Nm slk_touch , +.Nm slk_wset +.Nd Curses soft label key routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn slk_attroff "const chtype attr" +.Ft int +.Fn slk_attr_off "const attr_t attr" "void *opt" +.Ft int +.Fn slk_attron "const chtype attr" +.Ft int +.Fn slk_attr_on "const attr_t attr" "void *opt" +.Ft int +.Fn slk_attrset "const chtype attr" +.Ft int +.Fn slk_attr_set "const attr_t attr" "short pair" "void *opt" +.Ft void +.Fn slk_clear "void" +.Ft int +.Fn slk_color "short pair" +.Ft int +.Fn slk_init "int fmt" +.Ft char * +.Fn slk_label "int labnum" +.Ft int +.Fn slk_noutrefresh "void" +.Ft int +.Fn slk_refresh "void" +.Ft int +.Fn slk_restore "void" +.Ft int +.Fn slk_set "int labnum" "const char *label" "int justify" +.Ft int +.Fn slk_touch "void" +.Ft int +.Fn slk_wset "int labnum" "const wchar_t *label" "int justify" +.Sh DESCRIPTION +This Curses interface manipulates the set of soft function-key labels that +exist on some terminals. +For those terminals that do not have soft labels, Curses takes over the bottom +line of +.Dv stdstr , +reducing the size of +.Va stdscr +and the value of the +.Dv LINES +external variable. +There can be up to eight labels of up to eight display columns each. +.Pp +To use soft labels, +.Fn slk_init +must be called before +.Xr initscr 3 , +.Xr newterm 3 , +or +.Xr ripoffline 3 +is called. +If +.Xr newterm 3 +eventually uses a line from +.Va stdscr +to emulate the soft labels, then +.Fa fmt +determines how the labels are arranged on the screen from the following list: +.Bl -tag -width ERR -compact +.It 0 +indicates a 3-2-3 arrangement. +.It 1 +indicates a 4-4 arrangement. +.El +.Pp +The +.Fn slk_set +and +.Fn slk_wset +functions specify the text of soft label number +.Fa labnum , +within the range from 1 to 8 inclusive. +The +.Fa label +argument is the string to be put on the label. +The +.Fa justify +argument can have the following values to indicate how to justify +.Fa label +within the space reserved for it: +.Bl -tag -width ERR -compact +.It 0 +Left align. +.It 1 +Center align. +.It 2 +Right align. +.El +.Pp +The +.Fn slk_refresh +and +.Fn slk_noutrefresh +functions correspond to the +.Xr wrefresh 3 +and +.Xr wnoutrefresh 3 +functions. +.Pp +The +.Fn slk_label +function returns a pointer to the text displayed in the label. +.Pp +The +.Fn slk_clear +function immediately clears the soft labels from the screen. +.Pp +The +.Fn slk_restore +function immediately restores the soft labels to the screen after a call to +.Fn slk_clear . +.Pp +The +.Fn slk_touch +function forces all soft labels to be output the next time +.Fn slk_noutrefresh +or +.Fn slk_refresh +is called. +.Pp +The +.Fn slk_attron , +.Fn slk_attrset +and +.Fn slk_attroff +functions correspond to +.Xr attron 3 , +.Xr attrset 3 +and +.Xr attroff 3 . +The have an effect only if soft labels are simulated on the bottom line of the +screen. +.Pp +The +.Fn slk_attr_on , +.Fn slk_attr_set , +.Fn slk_color +and +.Fn slk_attr_off +functions correspond to +.Xr attr_on 3 , +.Xr attr_set 3 , +.Xr color_set 3 +and +.Xr attr_off 3 +and thus support the attribute constants with the WA_ prefix and color. +The have an effect only if soft labels are simulated on the bottom line of the +screen. +.Pp +The +.Fa opt +argument is reserved for future use. +Currently the application must provide a NULL pointer as +.Fa opt . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr terminfo 5 +.Sh NOTES +This has not been tested on a terminal with real soft label keys. +.Dv label_height , +.Dv label_width , +.Dv label_format +and +.Dv lab_f* +are currently not used. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The soft label key functions were added in +.Nx 8.0 . diff --git a/static/netbsd/man3/curses_standout.3 b/static/netbsd/man3/curses_standout.3 new file mode 100644 index 00000000..68e2a917 --- /dev/null +++ b/static/netbsd/man3/curses_standout.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: curses_standout.3,v 1.11 2025/04/11 23:57:21 uwe Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 27, 2021 +.Dt CURSES_STANDOUT 3 +.Os +.Sh NAME +.Nm curses_standout , +.Nm standout , +.Nm standend , +.Nm wstandout , +.Nm wstandend +.Nd curses standout attribute manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn standout void +.Ft int +.Fn standend void +.Ft int +.Fo wstandout +.Fa "WINDOW *win" +.Fc +.Ft int +.Fo wstandend +.Fa "WINDOW *win" +.Fc +.Sh DESCRIPTION +These functions manipulate the standout attribute on +.Va stdscr +or on the specified window. +The standout attribute applies the "best" supported highlighting mode +supported by the current terminal, which may be an alias of +other attributes. +.Pp +The +.Fn standout +function turns on the standout attribute +on +.Va stdscr . +The +.Fn standend +function turns off all attributes +on +.Va stdscr . +.Pp +The +.Fn wstandout +and +.Fn wstandend +functions are equivalent to +.Fn standout +and +.Fn standend , +respectively, excepting that the attribute is manipulated on the +window specified by +.Fa win . +.Pp +The +.Fn standout +and +.Fn standend +functions are equivalent to +.Fn attron A_STANDOUT +and +.Fn attroff A_STANDOUT , +respectively. +.Sh RETURN VALUES +These functions always return 1. +.Sh SEE ALSO +.Xr curses_attributes 3 , +.Xr curses_underscore 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +.Sh CAVEATS +On some terminals, characters with standout set may have the same appearance +as characters with the reverse video or bold attribute set. +However, on legacy terminals, standout may be the only attribute that can be +used to emphasize characters. +The standout attribute should not be mixed with other attributes. diff --git a/static/netbsd/man3/curses_termcap.3 b/static/netbsd/man3/curses_termcap.3 new file mode 100644 index 00000000..b61411ba --- /dev/null +++ b/static/netbsd/man3/curses_termcap.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: curses_termcap.3,v 1.7 2024/05/14 10:38:16 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd May 14, 2024 +.Dt CURSES_TERMCAP 3 +.Os +.Sh NAME +.Nm curses_termcap , +.Nm fullname +.Nd curses termcap querying routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft char * +.Fn fullname "const char *termbuf" "char *name" +.Sh DESCRIPTION +The +.Fn fullname +function takes the termcap entry in +.Fa termbuf +and copies the full name of the terminal from the entry into the +target variable +.Fa name . +The full name of the terminal is assumed to be the last alias in the +termcap entry name. +It is assumed that the +.Fa name +variable has sufficient storage to hold the full name of the terminal. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr terminfo 5 +.Sh STANDARDS +The +.Lb libcurses +library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_touch.3 b/static/netbsd/man3/curses_touch.3 new file mode 100644 index 00000000..24497011 --- /dev/null +++ b/static/netbsd/man3/curses_touch.3 @@ -0,0 +1,209 @@ +.\" $NetBSD: curses_touch.3,v 1.10 2018/02/08 09:05:16 dholland Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd January 2, 2017 +.Dt CURSES_TOUCH 3 +.Os +.Sh NAME +.Nm curses_touch , +.Nm touchline , +.Nm touchoverlap , +.Nm touchwin , +.Nm untouchwin , +.Nm wtouchln , +.Nm is_linetouched , +.Nm is_wintouched , +.Nm redrawwin , +.Nm wredrawln , +.Nm syncok , +.Nm wsyncup , +.Nm wsyncdown +.Nd curses window modification routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn touchline "WINDOW *win" "int start" "int count" +.Ft int +.Fn touchoverlap "WINDOW *win1" "WINDOW *win2" +.Ft int +.Fn touchwin "WINDOW *win" +.Ft int +.Fn untouchwin "WINDOW *win" +.Ft int +.Fn wtouchln "WINDOW *win" "int line" "int n" "boolf changed" +.Ft bool +.Fn is_linetouched "WINDOW *win" "int line" +.Ft bool +.Fn is_wintouched "WINDOW *win" +.Ft int +.Fn redrawwin "WINDOW *win" +.Ft int +.Fn wredrawln "WINDOW *win" "int line" "int n" +.Ft int +.Fn syncok "WINDOW *win" +.Ft void +.Fn wsyncup "WINDOW *win" +.Ft void +.Fn wsyncdown "WINDOW *win" +.Sh DESCRIPTION +These functions mark lines and windows as modified and check the modification +status of lines and windows. +.Pp +The +.Fn touchline +function marks +.Fa count +lines starting from +.Fa start +in window +.Fa win +as having been modified. +These characters will be synced to the terminal on the next call to +.Fn wrefresh . +.Pp +The +.Fn touchoverlap +function marks the portion of +.Fa win2 +that overlaps +.Fa win1 +as being modified. +.Pp +The +.Fn touchwin +function marks the entire window +.Fa win +as having been modified. +Conversely, +the +.Fn untouchwin +function marks the window +.Fa win +as being unmodified, so that any changes made to that window will +not be synced to the terminal during a +.Fn wrefresh . +.Pp +The +.Fn wtouchln +function performs one of two operations on +.Fa n +lines starting at +.Fa line +in the given window. +If +.Fa changed +is 1 then the given line range is marked as being modified, if +.Fa changed +is 0 then the given line range is set to being unmodified. +.Pp +The +.Fn is_linetouched +function returns +.Dv TRUE +if +.Fa line +in window +.Fa win +has been modified since the last refresh was done, otherwise +.Dv FALSE +is returned. +.Pp +.Fn is_wintouched +returns +.Dv TRUE +if the window +.Fa win +has been modified since the last refresh, otherwise +.Dv FALSE +is returned. +.Pp +The +.Fn redrawwin +function marks the entire window +.Fa win +as having been corrupted. +Is is equivalent to the +.Fn touchwin +function. +.Pp +The +.Fn wredrawln +function marks +.Fa n +lines starting at +.Fa line +in the given window as corrupted. +It is equivalent to +.Fn wtouchln win line n 1 . +.Pp +The +.Fn syncok +function determines whether all the ancestors of the specified window are +implicitly touched whenever there is a change in the window. +The initial state is +.Dv FALSE . +.Pp +The +.Fn wsyncup +function touches all ancestors of +.Fa win . +.Pp +The +.Fn wsyncdown +function touches +.Fa win +if any of its ancestors is touched. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_refresh 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_tty.3 b/static/netbsd/man3/curses_tty.3 new file mode 100644 index 00000000..fe13509f --- /dev/null +++ b/static/netbsd/man3/curses_tty.3 @@ -0,0 +1,389 @@ +.\" $NetBSD: curses_tty.3,v 1.15 2025/04/11 23:48:40 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd February 17, 2017 +.Dt CURSES_TTY 3 +.Os +.Sh NAME +.Nm curses_tty , +.Nm baudrate , +.Nm beep , +.Nm flash , +.Nm curs_set , +.Nm def_prog_mode , +.Nm reset_prog_mode , +.Nm def_shell_mode , +.Nm reset_shell_mode , +.Nm echo , +.Nm noecho , +.Nm delay_output , +.Nm erasechar , +.Nm flushinp , +.Nm gettmode , +.Nm halfdelay , +.Nm has_ic , +.Nm has_il , +.Nm idcok , +.Nm idlok , +.Nm intrflush , +.Nm noqiflush , +.Nm qiflush , +.Nm killchar , +.Nm meta , +.Nm napms , +.Nm nl , +.Nm nonl , +.Nm cbreak , +.Nm nocbreak , +.Nm raw , +.Nm noraw , +.Nm typeahead , +.Nm savetty , +.Nm resetty +.Nd curses terminal manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn baudrate "void" +.Ft int +.Fn beep "void" +.Ft int +.Fn flash "void" +.Ft int +.Fn curs_set "int visibility" +.Ft int +.Fn def_prog_mode "void" +.Ft int +.Fn reset_prog_mode "void" +.Ft int +.Fn def_shell_mode "void" +.Ft int +.Fn reset_shell_mode "void" +.Ft int +.Fn echo "void" +.Ft int +.Fn noecho "void" +.Ft int +.Fn delay_output "int ms" +.Ft char +.Fn erasechar "void" +.Ft int +.Fn flushinp "void" +.Ft int +.Fn gettmode "void" +.Ft bool +.Fn has_ic "void" +.Ft bool +.Fn has_il "void" +.Ft int +.Fn idcok "WINDOW *win" "bool flag" +.Ft int +.Fn idlok "WINDOW *win" "bool flag" +.Ft int +.Fn intrflush "WINDOW *win" "bool flag" +.Ft void +.Fn noqiflush "void" +.Ft void +.Fn qiflush "void" +.Ft char +.Fn killchar "void" +.Ft int +.Fn meta "WINDOW *win" "bool flag" +.Ft int +.Fn napms "int ms" +.Ft int +.Fn nl "void" +.Ft int +.Fn nonl "void" +.Ft int +.Fn cbreak "void" +.Ft int +.Fn nocbreak "void" +.Ft int +.Fn halfdelay "int" +.Ft int +.Fn raw "void" +.Ft int +.Fn noraw "void" +.Ft int +.Fn typeahead "int filedes" +.Ft int +.Fn savetty "void" +.Ft int +.Fn resetty "void" +.Sh DESCRIPTION +These functions manipulate curses terminal settings. +.Pp +The +.Fn baudrate +function extracts the output speed of the terminal +and returns it in bits per second. +.Pp +The +.Fn beep +function rings the terminal bell, if this is possible. +Failing that, the terminal screen will be flashed. +If neither of these are possible, then no action will be taken. +.Fn flash +will flash the terminal screen if possible. +Failing that, the terminal bell will be rung. +If neither of these are possible then no action will be taken. +.Pp +The cursor +visibility can be set by calling +.Fn curs_set . +The following visibility settings are valid for +.Fn curs_set : +.Pp +.Bl -column -offset indent "Visibility" +.It Visibility Ta Effect +.It 0 Ta cursor is invisible. +.It 1 Ta cursor is normal visibility +.It 2 Ta cursor is high visibility +.El +.Pp +A successful call to +.Fn curs_set +will return the previous visibility setting for the cursor. +.Pp +The +.Fn delay_output +function pauses the output to the terminal by sending the appropriate +number of terminal pad characters such that the transmission time of +the pad characters will take +.Fa ms +milliseconds. +.Pp +Calling +.Fn def_prog_mode +will cause the current terminal curses setting to be saved. +A subsequent call to +.Fn reset_prog_mode , +will restore the saved settings. +This is useful when calls to external programs are made that may +reset the terminal characteristics. +.Pp +The +.Fn def_shell_mode +function saves the current terminal line settings. +These settings are the ones that will be restored when the curses +application exits. +Conversely, +.Fn reset_shell_mode +will save the current terminal curses settings for later restoration and +restores the previously saved terminal line settings. +.Pp +The +.Fn echo +function turns on curses echo mode, characters entered will be echoed +to the terminal by curses. +The +.Fn noecho +function disables this feature. +.Pp +The current erase character for the terminal can be determined by +calling the +.Fn erasechar +function. +.Pp +The +.Fn flushinp +function discards any pending input for the current screen. +.Pp +The modes +for the current terminal can be reset by calling +.Fn gettmode , +this will perform the initialisation on the terminal that is normally +done by curses at start up. +.Pp +The +.Fn has_ic +function returns either +.Dv TRUE +or +.Dv FALSE +depending on whether or not the terminal has a insert character +capability or not. +Similarly the +.Fn has_il +function does the same test but for a insert line capability. +.Pp +The use of the insert character capability in curses operations can be +enabled or disabled by calling +.Fn idcok +on the desired window. +Similarly, the use of the insert line capability can be controlled using the +.Fn idlok +function. +.Pp +The +.Fn intrflush +function controls whether or not a flush of the input buffer is +performed when an interrupt key (kill, suspend or quit) is pressed. +The +.Fa win +parameter is ignored. +The +.Fn noqiflush +function is equivalent to +.Fn intrflush stdscr FALSE . +The +.Fn qiflush +function is equivalent to +.Fn intrflush stdscr TRUE . +.Pp +The character that performs the line kill function can be determined +by calling the +.Fn killchar +function. +.Pp +The +.Fn meta +function turns on and off the generation of 8 bit characters by the +terminal, if +.Fa flag +is +.Dv FALSE +then only 7 bit characters will be returned, if +.Fa flag +is +.Dv TRUE +then 8 bit characters will be returned by the terminal. +.Pp +The +.Fn napms +causes the application to sleep for the number of milliseconds +specified by +.Fa ms . +.Pp +Calling +.Fn nl +will cause curses to map all carriage returns to newlines on input, +this functionality is enabled by default. +The +.Fn nonl +function disables this behaviour. +.Pp +The +.Fn cbreak +function will put the terminal into cbreak mode, which means that +characters will be returned one at a time instead of waiting for a +newline character, line discipline processing will be performed. +The +.Fn nocbreak +function disables this mode. +.Pp +Calling +.Fn halfdelay +puts the terminal into the same mode as +.Fn cbreak +with the exception that if no character is received within the specified +number of tenths of a second then the input routine will return +.Dv ERR . +This mode can be cancelled by calling +.Fn nocbreak . +The valid range for the timeout is from 1 to 255 tenths of a second. +.Pp +The +.Fn noraw +function sets the input mode for the current terminal into Cooked mode, +that is input character translation and signal character processing is +performed. +The +.Fn raw +function puts the terminal into Raw mode, no input character +translation is done nor is signal character processing. +.Pp +The +.Fn typeahead +function controls the detection of typeahead during a refresh based on the +value of +.Ar filedes\^ : +.Bl -bullet +.It +If +.Ar filedes +is a valid file descriptor, typeahead is enabled during refresh; +Curses periodically checks +.Ar filedes +for input and aborts the refresh if any character is available. +The value of +.Ar filedes +need not be the file descriptor on which the refresh is occurring. +.It +If +.Ar filedes +is \-1, Curses does not check for typeahead during refresh. +.El +.Pp +The terminal +tty flags can be saved by calling +.Fn savetty +and may be restored by calling +.Fn resetty , +the use of these functions is discouraged as they may cause the +terminal to be put into a state that is incompatible with curses +operation. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width Dv -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr getch 3 , +.Xr termios 4 +.Sh NOTES +The +.Fn idcok +and +.Fn idlok +currently have no effect on the curses code at all, currently curses +will always use the terminal insert character and insert line +capabilities if available. +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/curses_underscore.3 b/static/netbsd/man3/curses_underscore.3 new file mode 100644 index 00000000..6a8725de --- /dev/null +++ b/static/netbsd/man3/curses_underscore.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: curses_underscore.3,v 1.7 2025/04/11 23:57:21 uwe Exp $ +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julian Coleman. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 29, 2018 +.Dt CURSES_UNDERSCORE 3 +.Os +.Sh NAME +.Nm curses_underscore , +.Nm underscore , +.Nm underend , +.Nm wunderscore , +.Nm wunderend +.Nd curses underscore attribute manipulation routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn underscore void +.Ft int +.Fn underend void +.Ft int +.Fn wunderscore "WINDOW *" +.Ft int +.Fn wunderend "WINDOW *" +.Sh DESCRIPTION +These functions manipulate the underscore attribute on +.Va stdscr +or on the specified window. +.Pp +The +.Fn underscore +function turns on the underscore attribute +on +.Va stdscr . +The +.Fn underend +function turns off the underscore attribute on +.Va stdscr . +.Pp +The +.Fn wunderscore +and +.Fn wunderend +functions +are equivalent to +.Fn underscore +and +.Fn underend , +respectively, excepting that the attribute is manipulated on the +window specified by +.Fa win . +.Pp +The +.Fn underscore +and +.Fn underend +functions +are equivalent to +.Fn wattron A_UNDERLINE +and +.Fn wattroff A_UNDERLINE , +respectively. +.Sh RETURN VALUES +These functions always return 1. +.Sh SEE ALSO +.Xr curses_attributes 3 , +.Xr curses_standout 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +These functions first appeared in +.Nx 1.5 . diff --git a/static/netbsd/man3/curses_version.3 b/static/netbsd/man3/curses_version.3 new file mode 100644 index 00000000..a0d01e86 --- /dev/null +++ b/static/netbsd/man3/curses_version.3 @@ -0,0 +1,60 @@ +.\" $NetBSD: curses_version.3,v 1.1 2019/09/02 09:08:29 roy Exp $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd August 29, 2019 +.Dt CURSES_VERSION 3 +.Os +.Sh NAME +.Nm curses_version +.Nd Curses version information +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft const char * +.Fn curses_version "void" +.Sh DESCRIPTION +The +.Fn curses_version +function returns a read-only string representing the version of the +.Nx +curses library. +This has no relation to the +.Nx +release it might have been taken from. +.Sh SEE ALSO +.Xr curses 3 +.Sh HISTORY +The +.Fn curses_version +function is a +.Em ncurses +extension to the Curses library and was added in +.Nx 10.0 . diff --git a/static/netbsd/man3/curses_window.3 b/static/netbsd/man3/curses_window.3 new file mode 100644 index 00000000..cbbf4b7b --- /dev/null +++ b/static/netbsd/man3/curses_window.3 @@ -0,0 +1,274 @@ +.\" $NetBSD: curses_window.3,v 1.18 2025/04/11 23:57:21 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd October 13, 2024 +.Dt CURSES_WINDOW 3 +.Os +.Sh NAME +.Nm curses_window , +.Nm copywin , +.Nm dupwin , +.Nm delwin , +.Nm derwin , +.Nm mvwin , +.Nm mvderwin , +.Nm newwin , +.Nm overlay , +.Nm overwrite , +.Nm subwin , +.Nm wresize +.Nd curses window routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fo copywin +.Fa "const WINDOW *source" +.Fa "WINDOW *dest" +.Fa "int sminrow" +.Fa "int smincol" +.Fa "int dminrow" +.Fa "int dmincol" +.Fa "int dmaxrow" +.Fa "int dmaxcol" +.Fa "int overlay" +.Fc +.Ft WINDOW * +.Fn dupwin "WINDOW *win" +.Ft WINDOW * +.Fn derwin "WINDOW *win" "int lines" "int cols" "int y" "int x" +.Ft int +.Fn delwin "WINDOW *win" +.Ft int +.Fn mvwin "WINDOW *win" "int y" "int x" +.Ft int +.Fn mvderwin "WINDOW *win" "int y" "int x" +.Ft WINDOW * +.Fn newwin "int lines" "int cols" "int begin_y" "int begin_x" +.Ft WINDOW * +.Fn subwin "WINDOW *win" "int lines" "int cols" "int begin_y" "int begin_x" +.Ft int +.Fn overlay "WINDOW *source" "WINDOW *dest" +.Ft int +.Fn overwrite "WINDOW *source" "WINDOW *dest" +.Ft int +.Fn wresize "WINDOW *win" "int lines" "int cols" +.Sh DESCRIPTION +These functions create, modify and delete windows on the current screen. +.Pp +The contents of a window may be copied to another window by using the +.Fn copywin +function, a section of the destination window +.Fa dest +bounded by +.Fa (dminrow , +.Fa dmincol ) +and +.Fa (dmaxrow , +.Fa dmaxcol ) +will be overwritten with the contents of the window +.Fa source +starting at the coordinates +.Fa (sminrow , +.Fa smincol ) . +If the +.Fa overlay +flag is +.Dv TRUE +then only non-blank characters from +.Fa source +will be copied to +.Fa dest , +if +.Fa overlay +is +.Dv FALSE +then all characters from +.Fa source +will be copied to +.Fa dest . +If the bounding rectangles of either the source or the destination +windows lay outside the maximum size of the respective windows then +the size of the window copied will be adjusted to be within the bounds +of both the source and destination windows. +.Pp +The +.Fn dupwin +function creates an exact duplicate of +.Fa win +and returns a pointer to it. +.Pp +Calling +.Fn derwin +will create a subwindow of +.Fa win +in the same manner as +.Fn subwin +excepting that the starting column and row +.Fa y , +.Fa x +are relative to the parent window origin. +.Pp +A window may deleted and all resources freed by calling the +.Fn delwin +function with the pointer to the window to be deleted in +.Fa win . +If +.Fa win +is +.Dv NULL , +then no action occurs. +.Pp +A window can be moved to a new position by calling the +.Fn mvwin +function. +The +.Fa y +and +.Fa x +positions are the new origin of the window on the screen. +If the new position would cause the any part of the window to lie outside +the screen, it is an error and the window is not moved. +.Pp +A mapping of a region relative to the parent window may be created by +calling the +.Fn mvderwin +function, the +.Fa y +and +.Fa x +positions are relative to the origin of the parent window. +The screen offset of +.Fa win +is not updated, the characters beginning at +.Fa y , +.Fa x +for the area the size of +.Fa win +will be displayed at the screen offset of +.Fa win . +If the given window in +.Fa win +is not a subwindow then an error will be returned. +If the new position would cause the any part of the window to lie outside +the parent window, it is an error and the mapping is not updated. +.Pp +The +.Fn newwin +function creates a new window of size +.Fa lines , +.Fa cols +with an origin at +.Fa begin_y , +.Fa begin_x . +If +.Fa lines +is less than or equal to zero then the number of rows +for the window is set to +.Dv LINES - +.Fa begin_x ++ +.Fa lines . +Similarly if +.Fa cols +is less than or equal to zero then the number of columns +for the window is set to +.Dv COLS - +.Fa begin_y ++ +.Fa cols . +.Pp +.Fn subwin +is similar to +.Fn newwin +excepting that the size of the subwindow is bounded by the parent +window +.Fa win . +The subwindow shares internal data structures with the parent window +and will be refreshed when the parent window is refreshed. +The subwindow inherits the background character and attributes of the +parent window. +.Pp +The +.Fn overlay +function copies the contents of the source window +.Fa source +to the destination window +.Fa dest , +only the characters that are not the background character in the +source window are copied to the destination. +The windows need not be the same size, only the overlapping portion of both +windows will be copied. +The +.Fn overwrite +function performs the same functions as +.Fn overlay +excepting that characters from the source window are copied to the +destination without exception. +.Pp +.Fn wresize +resizes the specified window to the new number of lines and columns +given, all internal curses structures are resized. +Any subwindows of the specified window will also be resized if any part +of them falls outside the new parent window size. +The application must redraw the window after it has been resized. +Note that +.Dv curscr +and +.Va stdscr +can not be resized to be larger than the size of the screen. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr curses_fileio 3 , +.Xr curses_pad 3 , +.Xr curses_screen 3 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/cuserid.3 b/static/netbsd/man3/cuserid.3 new file mode 100644 index 00000000..97bc3040 --- /dev/null +++ b/static/netbsd/man3/cuserid.3 @@ -0,0 +1,120 @@ +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)ctermid.3 5.2 (Berkeley) 4/19/91 +.\" $NetBSD: cuserid.3,v 1.13 2010/03/22 21:55:39 joerg Exp $ +.\" +.Dd November 28, 1993 +.Dt CUSERID 3 +.Os +.Sh NAME +.Nm cuserid +.Nd get user name +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn cuserid "char *buf" +.Sh DESCRIPTION +.Bf -symbolic +This interface is available from the compatibility library, libcompat and +has been obsoleted by +.Xr getlogin 2 . +.Ef +.Pp +The +.Fn cuserid +function returns a character string representation of the user name +associated with the effective user ID of the calling process. +.Pp +If +.Fa buf +is not the +.Dv NULL +pointer, the user name is copied into the memory referenced by +.Fa buf . +The argument +.Fa buf +is assumed to point to an array at least +.Dv L_cuserid +(as defined in the include +file +.In stdio.h ) +bytes long. +Otherwise, the user name is copied to a static buffer. +.Sh RETURN VALUES +If +.Fa buf +is not the +.Dv NULL +pointer, +.Fa buf +is returned; +otherwise the address of the static buffer is returned. +.Pp +If the user name could not be determined, if +.Fa buf +is not the +.Dv NULL +pointer, the null character +.Sq \e0 +will be stored at +.Fa *buf ; +otherwise +the +.Dv NULL +pointer is returned. +.Sh SEE ALSO +.Xr getlogin 2 , +.Xr getpwent 3 +.Sh STANDARDS +The +.Fn cuserid +function conforms to +.St -p1003.1-88 . +.Sh BUGS +Due to irreconcilable differences in historic implementations, +.Fn cuserid +was removed from the +.St -p1003.1-90 +standard. +This implementation exists purely for compatibility with existing programs. +New programs should use one of the following three alternatives to +obtain the user name: +.Pp +.Bl -enum -offset indent -compact +.It +.Fn getlogin +to return the user's login name. +.It +.Nm getpwuid Ns Pq Fn geteuid +to return the user name associated with the calling process' effective user ID. +.It +.Nm getpwuid Ns Pq Fn getuid +to return the user name associated with the calling process' real user ID. +.El diff --git a/static/netbsd/man3/d2i_ASN1_OBJECT.3 b/static/netbsd/man3/d2i_ASN1_OBJECT.3 new file mode 100644 index 00000000..5eb1d43c --- /dev/null +++ b/static/netbsd/man3/d2i_ASN1_OBJECT.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: d2i_ASN1_OBJECT.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_ASN1_OBJECT 3" +.TH d2i_ASN1_OBJECT 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_ASN1_OBJECT, i2d_ASN1_OBJECT \- ASN1 OBJECT IDENTIFIER functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length); +\& int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an \s-1ASN1 OBJECT IDENTIFIER.\s0 +.PP +Othewise these behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_CMS_ContentInfo.3 b/static/netbsd/man3/d2i_CMS_ContentInfo.3 new file mode 100644 index 00000000..3649d408 --- /dev/null +++ b/static/netbsd/man3/d2i_CMS_ContentInfo.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: d2i_CMS_ContentInfo.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_CMS_ContentInfo 3" +.TH d2i_CMS_ContentInfo 3 "2015-03-23" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_CMS_ContentInfo, i2d_CMS_ContentInfo \- CMS ContentInfo functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length); +\& int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an \s-1CMS\s0 ContentInfo structure. +.PP +Otherwise they behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +These functions were first added to OpenSSL 0.9.8 diff --git a/static/netbsd/man3/d2i_DHparams.3 b/static/netbsd/man3/d2i_DHparams.3 new file mode 100644 index 00000000..e5749191 --- /dev/null +++ b/static/netbsd/man3/d2i_DHparams.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: d2i_DHparams.3,v 1.20 2020/12/10 00:33:13 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_DHparams 3" +.TH d2i_DHparams 3 "2020-12-10" "1.1.1i" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_DHparams, i2d_DHparams \- PKCS#3 DH parameter functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& DH *d2i_DHparams(DH **a, const unsigned char **pp, long length); +\& int i2d_DHparams(DH *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode PKCS#3 \s-1DH\s0 parameters using the +DHparameter structure described in PKCS#3. +.PP +Otherwise these behave in a similar way to \fBd2i_X509()\fR and \fBi2d_X509()\fR +described in the \fBd2i_X509\fR\|(3) manual page. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_DHparams()\fR returns a valid \fB\s-1DH\s0\fR structure or \s-1NULL\s0 if an error occurred. +.PP +\&\fBi2d_DHparams()\fR returns the length of encoded data on success or a value which +is less than or equal to 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBd2i_X509\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_DSAPublicKey.3 b/static/netbsd/man3/d2i_DSAPublicKey.3 new file mode 100644 index 00000000..f8b02ea5 --- /dev/null +++ b/static/netbsd/man3/d2i_DSAPublicKey.3 @@ -0,0 +1,215 @@ +.\" $NetBSD: d2i_DSAPublicKey.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_DSAPublicKey 3" +.TH d2i_DSAPublicKey 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, +d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG \- DSA key encoding +and parsing functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); +\& +\& int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); +\& +\& DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); +\& +\& int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); +\& +\& DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); +\& +\& int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); +\& +\& DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); +\& +\& int i2d_DSAparams(const DSA *a, unsigned char **pp); +\& +\& DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); +\& +\& int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fId2i_DSAPublicKey()\fR and \fIi2d_DSAPublicKey()\fR decode and encode the \s-1DSA\s0 public key +components structure. +.PP +\&\fId2i_DSA_PUBKEY()\fR and \fIi2d_DSA_PUBKEY()\fR decode and encode an \s-1DSA\s0 public key using +a SubjectPublicKeyInfo (certificate public key) structure. +.PP +\&\fId2i_DSAPrivateKey()\fR, \fIi2d_DSAPrivateKey()\fR decode and encode the \s-1DSA\s0 private key +components. +.PP +\&\fId2i_DSAparams()\fR, \fIi2d_DSAparams()\fR decode and encode the \s-1DSA\s0 parameters using +a \fBDss-Parms\fR structure as defined in \s-1RFC2459.\s0 +.PP +\&\fId2i_DSA_SIG()\fR, \fIi2d_DSA_SIG()\fR decode and encode a \s-1DSA\s0 signature using a +\&\fBDss-Sig-Value\fR structure as defined in \s-1RFC2459.\s0 +.PP +The usage of all of these functions is similar to the \fId2i_X509()\fR and +\&\fIi2d_X509()\fR described in the \fId2i_X509\fR\|(3) manual page. +.SH "NOTES" +.IX Header "NOTES" +The \fB\s-1DSA\s0\fR structure passed to the private key encoding functions should have +all the private key components present. +.PP +The data encoded by the private key functions is unencrypted and therefore +offers no private key security. +.PP +The \fB\s-1DSA_PUBKEY\s0\fR functions should be used in preference to the \fBDSAPublicKey\fR +functions when encoding public keys because they use a standard format. +.PP +The \fBDSAPublicKey\fR functions use an non standard format the actual data encoded +depends on the value of the \fBwrite_params\fR field of the \fBa\fR key parameter. +If \fBwrite_params\fR is zero then only the \fBpub_key\fR field is encoded as an +\&\fB\s-1INTEGER\s0\fR. If \fBwrite_params\fR is 1 then a \fB\s-1SEQUENCE\s0\fR consisting of the +\&\fBp\fR, \fBq\fR, \fBg\fR and \fBpub_key\fR respectively fields are encoded. +.PP +The \fBDSAPrivateKey\fR functions also use a non standard structure consiting +consisting of a \s-1SEQUENCE\s0 containing the \fBp\fR, \fBq\fR, \fBg\fR and \fBpub_key\fR and +\&\fBpriv_key\fR fields respectively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_ECPKParameters.3 b/static/netbsd/man3/d2i_ECPKParameters.3 new file mode 100644 index 00000000..7594ab26 --- /dev/null +++ b/static/netbsd/man3/d2i_ECPKParameters.3 @@ -0,0 +1,216 @@ +.\" $NetBSD: d2i_ECPKParameters.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_ECPKParameters 3" +.TH d2i_ECPKParameters 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp \- Functions for decoding and encoding ASN1 representations of elliptic curve entities +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); +\& int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); +\& #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) +\& #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) +\& #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \e +\& (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) +\& #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \e +\& (unsigned char *)(x)) +\& int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); +\& int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The ECPKParameters encode and decode routines encode and parse the public parameters for an +\&\fB\s-1EC_GROUP\s0\fR structure, which represents a curve. +.PP +\&\fId2i_ECPKParameters()\fR attempts to decode \fBlen\fR bytes at \fB*in\fR. If +successful a pointer to the \fB\s-1EC_GROUP\s0\fR structure is returned. If an error +occurred then \fB\s-1NULL\s0\fR is returned. If \fBpx\fR is not \fB\s-1NULL\s0\fR then the +returned structure is written to \fB*px\fR. If \fB*px\fR is not \fB\s-1NULL\s0\fR +then it is assumed that \fB*px\fR contains a valid \fB\s-1EC_GROUP\s0\fR +structure and an attempt is made to reuse it. If the call is +successful \fB*in\fR is incremented to the byte following the +parsed data. +.PP +\&\fIi2d_ECPKParameters()\fR encodes the structure pointed to by \fBx\fR into \s-1DER\s0 format. +If \fBout\fR is not \fB\s-1NULL\s0\fR is writes the \s-1DER\s0 encoded data to the buffer +at \fB*out\fR, and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it +returns the length of the encoded data. +.PP +If \fB*out\fR is \fB\s-1NULL\s0\fR memory will be allocated for a buffer and the encoded +data written to it. In this case \fB*out\fR is not incremented and it points to +the start of the data just written. +.PP +\&\fId2i_ECPKParameters_bio()\fR is similar to \fId2i_ECPKParameters()\fR except it attempts +to parse data from \s-1BIO \s0\fBbp\fR. +.PP +\&\fId2i_ECPKParameters_fp()\fR is similar to \fId2i_ECPKParameters()\fR except it attempts +to parse data from \s-1FILE\s0 pointer \fBfp\fR. +.PP +\&\fIi2d_ECPKParameters_bio()\fR is similar to \fIi2d_ECPKParameters()\fR except it writes +the encoding of the structure \fBx\fR to \s-1BIO \s0\fBbp\fR and it +returns 1 for success and 0 for failure. +.PP +\&\fIi2d_ECPKParameters_fp()\fR is similar to \fIi2d_ECPKParameters()\fR except it writes +the encoding of the structure \fBx\fR to \s-1BIO \s0\fBbp\fR and it +returns 1 for success and 0 for failure. +.PP +These functions are very similar to the X509 functions described in \fId2i_X509\fR\|(3), +where further notes and examples are available. +.PP +The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output +of the public parameters of the \s-1EC_GROUP\s0 to \fBbp\fR or \fBfp\fR. The output lines are indented by \fBoff\fR spaces. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fId2i_ECPKParameters()\fR, \fId2i_ECPKParameters_bio()\fR and \fId2i_ECPKParameters_fp()\fR return a valid \fB\s-1EC_GROUP\s0\fR structure +or \fB\s-1NULL\s0\fR if an error occurs. +.PP +\&\fIi2d_ECPKParameters()\fR returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fIi2d_ECPKParameters_bio()\fR, \fIi2d_ECPKParameters_fp()\fR, ECPKParameters_print and ECPKParameters_print_fp +return 1 for success and 0 if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypto\fR\|(3), \fIec\fR\|(3), \fIEC_GROUP_new\fR\|(3), \fIEC_GROUP_copy\fR\|(3), +\&\fIEC_POINT_new\fR\|(3), \fIEC_POINT_add\fR\|(3), \fIEC_KEY_new\fR\|(3), +\&\fIEC_GFp_simple_method\fR\|(3), \fId2i_X509\fR\|(3) diff --git a/static/netbsd/man3/d2i_ECPrivateKey.3 b/static/netbsd/man3/d2i_ECPrivateKey.3 new file mode 100644 index 00000000..3a0a1e37 --- /dev/null +++ b/static/netbsd/man3/d2i_ECPrivateKey.3 @@ -0,0 +1,200 @@ +.\" $NetBSD: d2i_ECPrivateKey.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_ECPrivateKey 3" +.TH d2i_ECPrivateKey 3 "2015-03-23" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +i2d_ECPrivateKey, d2i_ECPrivate_key \- Encode and decode functions for saving and +reading EC_KEY structures +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); +\& int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); +\& +\& unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); +\& void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The ECPrivateKey encode and decode routines encode and parse an +\&\fB\s-1EC_KEY\s0\fR structure into a binary format (\s-1ASN.1 DER\s0) and back again. +.PP +These functions are similar to the \fId2i_X509()\fR functions, and you should refer to +that page for a detailed description (see \fId2i_X509\fR\|(3)). +.PP +The format of the external representation of the public key written by +i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is +described by the point_conversion_form. See \fIEC_GROUP_copy\fR\|(3) +for a description of point_conversion_form. +.PP +When reading a private key encoded without an associated public key (e.g. if +\&\s-1EC_PKEY_NO_PUBKEY\s0 has been used \- see below), then d2i_ECPrivateKey generates +the missing public key automatically. Private keys encoded without parameters +(e.g. if \s-1EC_PKEY_NO_PARAMETERS\s0 has been used \- see below) cannot be loaded using +d2i_ECPrivateKey. +.PP +The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the +value of the encoding flags for the \fBkey\fR. There are two encoding flags +currently defined \- \s-1EC_PKEY_NO_PARAMETERS\s0 and \s-1EC_PKEY_NO_PUBKEY. \s0 These flags +define the behaviour of how the \fBkey\fR is converted into \s-1ASN1\s0 in a call to +i2d_ECPrivateKey. If \s-1EC_PKEY_NO_PARAMETERS\s0 is set then the public parameters for +the curve are not encoded along with the private key. If \s-1EC_PKEY_NO_PUBKEY\s0 is +set then the public key is not encoded along with the private key. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fId2i_ECPrivateKey()\fR returns a valid \fB\s-1EC_KEY\s0\fR structure or \fB\s-1NULL\s0\fR if an error +occurs. The error code that can be obtained by +\&\fIERR_get_error\fR\|(3). +.PP +\&\fIi2d_ECPrivateKey()\fR returns the number of bytes successfully encoded or a +negative value if an error occurs. The error code can be obtained by +\&\fIERR_get_error\fR\|(3). +.PP +EC_KEY_get_enc_flags returns the value of the current encoding flags for the +\&\s-1EC_KEY.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypto\fR\|(3), \fIec\fR\|(3), \fIEC_GROUP_new\fR\|(3), +\&\fIEC_GROUP_copy\fR\|(3), \fIEC_POINT_new\fR\|(3), +\&\fIEC_POINT_add\fR\|(3), +\&\fIEC_GFp_simple_method\fR\|(3), +\&\fId2i_ECPKParameters\fR\|(3), +\&\fId2i_ECPrivateKey\fR\|(3) diff --git a/static/netbsd/man3/d2i_PKCS8PrivateKey.3 b/static/netbsd/man3/d2i_PKCS8PrivateKey.3 new file mode 100644 index 00000000..c1898b90 --- /dev/null +++ b/static/netbsd/man3/d2i_PKCS8PrivateKey.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: d2i_PKCS8PrivateKey.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_PKCS8PrivateKey 3" +.TH d2i_PKCS8PrivateKey 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp \- PKCS#8 format private key functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); +\& EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The PKCS#8 functions encode and decode private keys in PKCS#8 format using both +PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. +.PP +Other than the use of \s-1DER\s0 as opposed to \s-1PEM\s0 these functions are identical to the +corresponding \fB\s-1PEM\s0\fR function as described in the \fIpem\fR\|(3) manual page. +.SH "NOTES" +.IX Header "NOTES" +Before using these functions \fIOpenSSL_add_all_algorithms\fR\|(3) +should be called to initialize the internal algorithm lookup tables otherwise errors about +unknown algorithms will occur if an attempt is made to decrypt a private key. +.PP +These functions are currently the only way to store encrypted private keys using \s-1DER\s0 format. +.PP +Currently all the functions use BIOs or \s-1FILE\s0 pointers, there are no functions which +work directly on memory: this can be readily worked around by converting the buffers +to memory BIOs, see \fIBIO_s_mem\fR\|(3) for details. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIpem\fR\|(3) diff --git a/static/netbsd/man3/d2i_PKCS8PrivateKey_bio.3 b/static/netbsd/man3/d2i_PKCS8PrivateKey_bio.3 new file mode 100644 index 00000000..d4758850 --- /dev/null +++ b/static/netbsd/man3/d2i_PKCS8PrivateKey_bio.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: d2i_PKCS8PrivateKey_bio.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "d2i_PKCS8PrivateKey_bio 3" +.TH d2i_PKCS8PrivateKey_bio 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp \- PKCS#8 format private key functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); +\& EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_bio(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_fp(FILE *fp, const EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, const EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, const EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The PKCS#8 functions encode and decode private keys in PKCS#8 format using both +PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. +.PP +Other than the use of DER as opposed to PEM these functions are identical to the +corresponding \fBPEM\fR function as described in \fBPEM_read_PrivateKey\fR\|(3). +.SH NOTES +.IX Header "NOTES" +These functions are currently the only way to store encrypted private keys using DER format. +.PP +Currently all the functions use BIOs or FILE pointers, there are no functions which +work directly on memory: this can be readily worked around by converting the buffers +to memory BIOs, see \fBBIO_s_mem\fR\|(3) for details. +.PP +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_PKCS8PrivateKey_bio()\fR and \fBd2i_PKCS8PrivateKey_fp()\fR return a valid \fBEVP_PKEY\fR +structure or NULL if an error occurred. +.PP +\&\fBi2d_PKCS8PrivateKey_bio()\fR, \fBi2d_PKCS8PrivateKey_fp()\fR, \fBi2d_PKCS8PrivateKey_nid_bio()\fR +and \fBi2d_PKCS8PrivateKey_nid_fp()\fR return 1 on success or 0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBPEM_read_PrivateKey\fR\|(3), +\&\fBpassphrase\-encoding\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_PrivateKey.3 b/static/netbsd/man3/d2i_PrivateKey.3 new file mode 100644 index 00000000..fc313d28 --- /dev/null +++ b/static/netbsd/man3/d2i_PrivateKey.3 @@ -0,0 +1,192 @@ +.\" $NetBSD: d2i_PrivateKey.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "d2i_PrivateKey 3" +.TH d2i_PrivateKey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_PrivateKey_ex, d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams, +d2i_AutoPrivateKey_ex, d2i_AutoPrivateKey, i2d_PrivateKey, i2d_PublicKey, +i2d_KeyParams, i2d_KeyParams_bio, d2i_PrivateKey_ex_bio, d2i_PrivateKey_bio, +d2i_PrivateKey_ex_fp, d2i_PrivateKey_fp, d2i_KeyParams_bio, i2d_PrivateKey_bio, +i2d_PrivateKey_fp +\&\- decode and encode functions for reading and saving EVP_PKEY structures +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& EVP_PKEY *d2i_PrivateKey_ex(int type, EVP_PKEY **a, const unsigned char **pp, +\& long length, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, +\& long length); +\& EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp, +\& long length); +\& EVP_PKEY *d2i_KeyParams(int type, EVP_PKEY **a, const unsigned char **pp, +\& long length); +\& EVP_PKEY *d2i_AutoPrivateKey_ex(EVP_PKEY **a, const unsigned char **pp, +\& long length, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, +\& long length); +\& +\& int i2d_PrivateKey(const EVP_PKEY *a, unsigned char **pp); +\& int i2d_PublicKey(const EVP_PKEY *a, unsigned char **pp); +\& int i2d_KeyParams(const EVP_PKEY *a, unsigned char **pp); +\& int i2d_KeyParams_bio(BIO *bp, const EVP_PKEY *pkey); +\& EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in); +\& +\& +\& #include +\& +\& EVP_PKEY *d2i_PrivateKey_ex_bio(BIO *bp, EVP_PKEY **a, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); +\& EVP_PKEY *d2i_PrivateKey_ex_fp(FILE *fp, EVP_PKEY **a, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a); +\& +\& int i2d_PrivateKey_bio(BIO *bp, const EVP_PKEY *pkey); +\& int i2d_PrivateKey_fp(FILE *fp, const EVP_PKEY *pkey); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBd2i_PrivateKey_ex()\fR decodes a private key using algorithm \fItype\fR. It attempts +to use any key\-specific format or PKCS#8 unencrypted PrivateKeyInfo format. +The \fItype\fR parameter should be a public key algorithm constant such as +\&\fBEVP_PKEY_RSA\fR. An error occurs if the decoded key does not match \fItype\fR. Some +private key decoding implementations may use cryptographic algorithms (for +example to automatically derive the public key if it is not explicitly +included in the encoding). In this case the supplied library context \fIlibctx\fR +and property query string \fIpropq\fR are used. +If successful and the \fIa\fR parameter is not NULL the function assigns the +returned \fBEVP_PKEY\fR structure pointer to \fI*a\fR, overwriting any previous value. +.PP +\&\fBd2i_PrivateKey()\fR does the same as \fBd2i_PrivateKey_ex()\fR except that the default +library context and property query string are used. +\&\fBd2i_PublicKey()\fR does the same for public keys. +\&\fBd2i_KeyParams()\fR does the same for key parameters. +.PP +The \fBd2i_PrivateKey_ex_bio()\fR and \fBd2i_PrivateKey_bio()\fR functions are similar to +\&\fBd2i_PrivateKey_ex()\fR and \fBd2i_PrivateKey()\fR respectively except that they decode +the data read from the given BIO. The \fBd2i_PrivateKey_ex_fp()\fR and +\&\fBd2i_PrivateKey_fp()\fR functions are the same except that they read the data from +the given FILE. +.PP +\&\fBd2i_AutoPrivateKey_ex()\fR and \fBd2i_AutoPrivateKey()\fR are similar to +\&\fBd2i_PrivateKey_ex()\fR and \fBd2i_PrivateKey()\fR respectively except that they attempt +to automatically detect the private key format. +.PP +\&\fBi2d_PrivateKey()\fR encodes \fIa\fR. It uses a key specific format or, if none is +defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. +\&\fBi2d_PublicKey()\fR does the same for public keys. +\&\fBi2d_KeyParams()\fR does the same for key parameters. +These functions are similar to the \fBd2i_X509()\fR functions; see \fBd2i_X509\fR\|(3). +\&\fBi2d_PrivateKey_bio()\fR and \fBi2d_PrivateKey_fp()\fR do the same thing except that they +encode to a \fBBIO\fR or \fBFILE\fR respectively. Again, these work similarly to the +functions described in \fBd2i_X509\fR\|(3). +.SH NOTES +.IX Header "NOTES" +All the functions that operate on data in memory update the data pointer \fI*pp\fR +after a successful operation, just like the other d2i and i2d functions; +see \fBd2i_X509\fR\|(3). +.PP +All these functions use DER format and unencrypted keys. Applications wishing +to encrypt or decrypt private keys should use other functions such as +\&\fBd2i_PKCS8PrivateKey()\fR instead. +.PP +To decode a key with type \fBEVP_PKEY_EC\fR, \fBd2i_PublicKey()\fR requires \fI*a\fR to be +a non\-NULL EVP_PKEY structure assigned an EC_KEY structure referencing the proper +EC_GROUP. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +The \fBd2i_PrivateKey_ex()\fR, \fBd2i_PrivateKey()\fR, \fBd2i_AutoPrivateKey_ex()\fR, +\&\fBd2i_AutoPrivateKey()\fR, \fBd2i_PrivateKey_ex_bio()\fR, \fBd2i_PrivateKey_bio()\fR, +\&\fBd2i_PrivateKey_ex_fp()\fR, \fBd2i_PrivateKey_fp()\fR, \fBd2i_PublicKey()\fR, \fBd2i_KeyParams()\fR +and \fBd2i_KeyParams_bio()\fR functions return a valid \fBEVP_PKEY\fR structure or NULL if +an error occurs. The error code can be obtained by calling \fBERR_get_error\fR\|(3). +.PP +\&\fBi2d_PrivateKey()\fR, \fBi2d_PublicKey()\fR and \fBi2d_KeyParams()\fR return the number of +bytes successfully encoded or a negative value if an error occurs. The error +code can be obtained by calling \fBERR_get_error\fR\|(3). +.PP +\&\fBi2d_PrivateKey_bio()\fR, \fBi2d_PrivateKey_fp()\fR and \fBi2d_KeyParams_bio()\fR return 1 if +successfully encoded or zero if an error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBcrypto\fR\|(7), +\&\fBd2i_PKCS8PrivateKey_bio\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBd2i_PrivateKey_ex()\fR, \fBd2i_PrivateKey_ex_bio()\fR, \fBd2i_PrivateKey_ex_fp()\fR, and +\&\fBd2i_AutoPrivateKey_ex()\fR were added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_RSAPrivateKey.3 b/static/netbsd/man3/d2i_RSAPrivateKey.3 new file mode 100644 index 00000000..9d389d6a --- /dev/null +++ b/static/netbsd/man3/d2i_RSAPrivateKey.3 @@ -0,0 +1,353 @@ +.\" $NetBSD: d2i_RSAPrivateKey.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "d2i_RSAPrivateKey 3" +.TH d2i_RSAPrivateKey 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_DSAPrivateKey, +d2i_DSAPrivateKey_bio, +d2i_DSAPrivateKey_fp, +d2i_DSAPublicKey, +d2i_DSA_PUBKEY, +d2i_DSA_PUBKEY_bio, +d2i_DSA_PUBKEY_fp, +d2i_DSAparams, +d2i_RSAPrivateKey, +d2i_RSAPrivateKey_bio, +d2i_RSAPrivateKey_fp, +d2i_RSAPublicKey, +d2i_RSAPublicKey_bio, +d2i_RSAPublicKey_fp, +d2i_RSA_PUBKEY, +d2i_RSA_PUBKEY_bio, +d2i_RSA_PUBKEY_fp, +d2i_DHparams, +d2i_DHparams_bio, +d2i_DHparams_fp, +d2i_ECParameters, +d2i_ECPrivateKey, +d2i_ECPrivateKey_bio, +d2i_ECPrivateKey_fp, +d2i_EC_PUBKEY, +d2i_EC_PUBKEY_bio, +d2i_EC_PUBKEY_fp, +i2d_RSAPrivateKey, +i2d_RSAPrivateKey_bio, +i2d_RSAPrivateKey_fp, +i2d_RSAPublicKey, +i2d_RSAPublicKey_bio, +i2d_RSAPublicKey_fp, +i2d_RSA_PUBKEY, +i2d_RSA_PUBKEY_bio, +i2d_RSA_PUBKEY_fp, +i2d_DHparams, +i2d_DHparams_bio, +i2d_DHparams_fp, +i2d_DSAPrivateKey, +i2d_DSAPrivateKey_bio, +i2d_DSAPrivateKey_fp, +i2d_DSAPublicKey, +i2d_DSA_PUBKEY, +i2d_DSA_PUBKEY_bio, +i2d_DSA_PUBKEY_fp, +i2d_DSAparams, +i2d_ECParameters, +i2d_ECPrivateKey, +i2d_ECPrivateKey_bio, +i2d_ECPrivateKey_fp, +i2d_EC_PUBKEY, +i2d_EC_PUBKEY_bio, +i2d_EC_PUBKEY_fp +\&\- DEPRECATED +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 12 +\& TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length); +\& TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a); +\& TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length); +\& TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a); +\& TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length); +\& TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a); +\& TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length); +\& TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a); +\& +\& int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout); +\& int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout); +\& int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a); +\& int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a); +\& int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a); +\& int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a); +\& int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout); +\& int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout); +\& int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a); +\& int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a); +\& int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a); +\& int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a); +\& int i2d_TYPEparams(const TYPE *a, unsigned char **ppout); +\& int i2d_TYPEparams(TYPE *a, unsigned char **ppout); +\& int i2d_TYPEparams_fp(FILE *fp, const TYPE *a); +\& int i2d_TYPEparams_fp(FILE *fp, TYPE *a); +\& int i2d_TYPEparams_bio(BIO *bp, const TYPE *a); +\& int i2d_TYPEparams_bio(BIO *bp, TYPE *a); +\& int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout); +\& int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout); +\& int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a); +\& int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a); +\& int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a); +\& int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All functions described here are deprecated. Please use \fBOSSL_DECODER\fR\|(3) +instead of the \fBd2i\fR functions and \fBOSSL_ENCODER\fR\|(3) instead of the \fBi2d\fR +functions. See "Migration" below. +.PP +In the description here, \fR\f(BITYPE\fR\fB\fR is used a placeholder for any of the +OpenSSL datatypes, such as \fBRSA\fR. +The function parameters \fIppin\fR and \fIppout\fR are generally either both named +\&\fIpp\fR in the headers, or \fIin\fR and \fIout\fR. +.PP +All the functions here behave the way that\*(Aqs described in \fBd2i_X509\fR\|(3). +.PP +Please note that not all functions in the synopsis are available for all key +types. For example, there are no \fBd2i_RSAparams()\fR or \fBi2d_RSAparams()\fR, +because the PKCS#1 \fBRSA\fR structure doesn\*(Aqt include any key parameters. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fBPrivateKey\fR() and derivates thereof decode DER encoded +\&\fR\f(BITYPE\fR\fB\fR private key data organized in a type specific structure. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fBPublicKey\fR() and derivates thereof decode DER encoded +\&\fR\f(BITYPE\fR\fB\fR public key data organized in a type specific structure. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fBparams\fR() and derivates thereof decode DER encoded \fR\f(BITYPE\fR\fB\fR +key parameters organized in a type specific structure. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fB_PUBKEY\fR() and derivates thereof decode DER encoded \fR\f(BITYPE\fR\fB\fR +public key data organized in a \fBSubjectPublicKeyInfo\fR structure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fBPrivateKey\fR() and derivates thereof encode the private key +\&\fR\f(BITYPE\fR\fB\fR data into a type specific DER encoded structure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fBPublicKey\fR() and derivates thereof encode the public key +\&\fR\f(BITYPE\fR\fB\fR data into a type specific DER encoded structure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fBparams\fR() and derivates thereof encode the \fR\f(BITYPE\fR\fB\fR key +parameters data into a type specific DER encoded structure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_PUBKEY\fR() and derivates thereof encode the public key +\&\fR\f(BITYPE\fR\fB\fR data into a DER encoded \fBSubjectPublicKeyInfo\fR structure. +.PP +For example, \fBd2i_RSAPrivateKey()\fR and \fBd2i_RSAPublicKey()\fR expects the +structure defined by PKCS#1. +Similarly, \fBi2d_RSAPrivateKey()\fR and \fBi2d_RSAPublicKey()\fR produce DER encoded +string organized according to PKCS#1. +.SS Migration +.IX Subsection "Migration" +Migration from the diverse \fR\f(BITYPE\fR\fB\fRs requires using corresponding new +OpenSSL types. For all \fB\fR\f(BITYPE\fR\fB\fRs described here, the corresponding new +type is \fBEVP_PKEY\fR. The rest of this section assumes that this has been +done, exactly how to do that is described elsewhere. +.PP +There are two migration paths: +.IP \(bu 4 +Replace +b with \fBd2i_PrivateKey\fR\|(3), +b with \fBd2i_PublicKey\fR\|(3), +b with \fBd2i_KeyParams\fR\|(3), +b with \fBd2i_PUBKEY\fR\|(3), +b with \fBi2d_PrivateKey\fR\|(3), +b with \fBi2d_PublicKey\fR\|(3), +b with \fBi2d_KeyParams\fR\|(3), +b with \fBi2d_PUBKEY\fR\|(3). +A caveat is that \fBi2d_PrivateKey\fR\|(3) may output a DER encoded PKCS#8 +outermost structure instead of the type specific structure, and that +\&\fBd2i_PrivateKey\fR\|(3) recognises and unpacks a PKCS#8 structures. +.IP \(bu 4 +Use \fBOSSL_DECODER\fR\|(3) and \fBOSSL_ENCODER\fR\|(3). How to migrate is described +below. All those descriptions assume that the key to be encoded is in the +variable \fIpkey\fR. +.PP +\fIMigrating \fR\f(BIi2d\fR\fI functions to \fR\f(BIOSSL_ENCODER\fR +.IX Subsection "Migrating i2d functions to OSSL_ENCODER" +.PP +The exact \fBOSSL_ENCODER\fR\|(3) output is driven by arguments rather than by +function names. The sample code to get DER encoded output in a type +specific structure is uniform, the only things that vary are the selection +of what part of the \fBEVP_PKEY\fR should be output, and the structure. The +\&\fBi2d\fR functions names can therefore be translated into two variables, +\&\fIselection\fR and \fIstructure\fR as follows: +.IP "\fBi2d_\fR\f(BITYPE\fR\fBPrivateKey\fR() translates into:" 4 +.IX Item "i2d_TYPEPrivateKey() translates into:" +.Vb 2 +\& int selection = EVP_PKEY_KEYPAIR; +\& const char *structure = "type\-specific"; +.Ve +.IP "\fBi2d_\fR\f(BITYPE\fR\fBPublicKey\fR() translates into:" 4 +.IX Item "i2d_TYPEPublicKey() translates into:" +.Vb 2 +\& int selection = EVP_PKEY_PUBLIC_KEY; +\& const char *structure = "type\-specific"; +.Ve +.IP "\fBi2d_\fR\f(BITYPE\fR\fBparams\fR() translates into:" 4 +.IX Item "i2d_TYPEparams() translates into:" +.Vb 2 +\& int selection = EVP_PKEY_PARAMETERS; +\& const char *structure = "type\-specific"; +.Ve +.IP "\fBi2d_\fR\f(BITYPE\fR\fB_PUBKEY\fR() translates into:" 4 +.IX Item "i2d_TYPE_PUBKEY() translates into:" +.Vb 2 +\& int selection = EVP_PKEY_PUBLIC_KEY; +\& const char *structure = "SubjectPublicKeyInfo"; +.Ve +.PP +The following sample code does the rest of the work: +.PP +.Vb 10 +\& unsigned char *p = buffer; /* |buffer| is supplied by the caller */ +\& size_t len = buffer_size; /* assumed be the size of |buffer| */ +\& OSSL_ENCODER_CTX *ctx = +\& OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure, +\& NULL, NULL); +\& if (ctx == NULL) { +\& /* fatal error handling */ +\& } +\& if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) { +\& OSSL_ENCODER_CTX_free(ctx); +\& /* non\-fatal error handling */ +\& } +\& if (!OSSL_ENCODER_to_data(ctx, &p, &len)) { +\& OSSL_ENCODER_CTX_free(ctx); +\& /* error handling */ +\& } +\& OSSL_ENCODER_CTX_free(ctx); +.Ve +.SH NOTES +.IX Header "NOTES" +The letters \fBi\fR and \fBd\fR in \fBi2d_\fR\f(BITYPE\fR() stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So \fBi2d_\fR\f(BITYPE\fR\fB\fR() converts from internal to DER. +.PP +The functions can also understand \fBBER\fR forms. +.PP +The actual TYPE structure passed to \fBi2d_\fR\f(BITYPE\fR() must be a valid +populated \fB\fR\f(BITYPE\fR\fB\fR structure \-\- it \fBcannot\fR simply be fed with an +empty structure such as that returned by \fBTYPE_new()\fR. +.PP +The encoded data is in binary form and may contain embedded zeros. +Therefore, any FILE pointers or BIOs should be opened in binary mode. +Functions such as \fBstrlen()\fR will \fBnot\fR return the correct length +of the encoded structure. +.PP +The ways that \fI*ppin\fR and \fI*ppout\fR are incremented after the operation +can trap the unwary. See the \fBWARNINGS\fR section in \fBd2i_X509\fR\|(3) for some +common errors. +The reason for this\-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. +.PP +The following points about the data types might be useful: +.IP \fBDSA_PUBKEY\fR 4 +.IX Item "DSA_PUBKEY" +Represents a DSA public key using a \fBSubjectPublicKeyInfo\fR structure. +.IP "\fBDSAPublicKey\fR, \fBDSAPrivateKey\fR" 4 +.IX Item "DSAPublicKey, DSAPrivateKey" +Use a non\-standard OpenSSL format and should be avoided; use \fBDSA_PUBKEY\fR, +\&\fBPEM_write_PrivateKey\fR\|(3), or similar instead. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_\fR\f(BITYPE\fR(), \fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() and \fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() return a valid +\&\fB\fR\f(BITYPE\fR\fB\fR structure or NULL if an error occurs. If the "reuse" capability has +been used with a valid structure being passed in via \fIa\fR, then the object is +freed in the event of error and \fI*a\fR is set to NULL. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() and \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR() return 1 for success and 0 if an +error occurs. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_ENCODER\fR\|(3), \fBOSSL_DECODER\fR\|(3), +\&\fBd2i_PrivateKey\fR\|(3), \fBd2i_PublicKey\fR\|(3), \fBd2i_KeyParams\fR\|(3), +\&\fBd2i_PUBKEY\fR\|(3), +\&\fBi2d_PrivateKey\fR\|(3), \fBi2d_PublicKey\fR\|(3), \fBi2d_KeyParams\fR\|(3), +\&\fBi2d_PUBKEY\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_RSAPublicKey.3 b/static/netbsd/man3/d2i_RSAPublicKey.3 new file mode 100644 index 00000000..4bc9b1d5 --- /dev/null +++ b/static/netbsd/man3/d2i_RSAPublicKey.3 @@ -0,0 +1,199 @@ +.\" $NetBSD: d2i_RSAPublicKey.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_RSAPublicKey 3" +.TH d2i_RSAPublicKey 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, +d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, +d2i_Netscape_RSA \- RSA public and private key encoding functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); +\& +\& int i2d_RSAPublicKey(RSA *a, unsigned char **pp); +\& +\& RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); +\& +\& int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); +\& +\& RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length); +\& +\& int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); +\& +\& int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); +\& +\& RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fId2i_RSAPublicKey()\fR and \fIi2d_RSAPublicKey()\fR decode and encode a PKCS#1 RSAPublicKey +structure. +.PP +\&\fId2i_RSA_PUBKEY()\fR and \fIi2d_RSA_PUBKEY()\fR decode and encode an \s-1RSA\s0 public key using +a SubjectPublicKeyInfo (certificate public key) structure. +.PP +\&\fId2i_RSAPrivateKey()\fR, \fIi2d_RSAPrivateKey()\fR decode and encode a PKCS#1 RSAPrivateKey +structure. +.PP +\&\fId2i_Netscape_RSA()\fR, \fIi2d_Netscape_RSA()\fR decode and encode an \s-1RSA\s0 private key in +\&\s-1NET\s0 format. +.PP +The usage of all of these functions is similar to the \fId2i_X509()\fR and +\&\fIi2d_X509()\fR described in the \fId2i_X509\fR\|(3) manual page. +.SH "NOTES" +.IX Header "NOTES" +The \fB\s-1RSA\s0\fR structure passed to the private key encoding functions should have +all the PKCS#1 private key components present. +.PP +The data encoded by the private key functions is unencrypted and therefore +offers no private key security. +.PP +The \s-1NET\s0 format functions are present to provide compatibility with certain very +old software. This format has some severe security weaknesses and should be +avoided if possible. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_SSL_SESSION.3 b/static/netbsd/man3/d2i_SSL_SESSION.3 new file mode 100644 index 00000000..247c3c5e --- /dev/null +++ b/static/netbsd/man3/d2i_SSL_SESSION.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: d2i_SSL_SESSION.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "d2i_SSL_SESSION 3" +.TH d2i_SSL_SESSION 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_SSL_SESSION, d2i_SSL_SESSION_ex, i2d_SSL_SESSION \- convert SSL_SESSION object from/to ASN1 representation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, +\& long length); +\& SSL_SESSION *d2i_SSL_SESSION_ex(SSL_SESSION **a, const unsigned char **pp, +\& long length, OSSL_LIB_CTX *libctx, +\& const char *propq); +\& int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions decode and encode an SSL_SESSION object. +For encoding details see \fBd2i_X509\fR\|(3). +.PP +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object\*(Aqs session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_SSL_SESSION()\fR and \fBd2i_SSL_SESSION_ex()\fR return a pointer to the newly +allocated SSL_SESSION object. +In case of failure the NULL\-pointer is returned and the error message +can be retrieved from the error stack. +.PP +\&\fBi2d_SSL_SESSION()\fR returns the size of the ASN1 representation in bytes. +When the session is not valid, \fB0\fR is returned and no operation is performed. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBssl\fR\|(7), \fBSSL_SESSION_free\fR\|(3), +\&\fBSSL_CTX_sess_set_get_cb\fR\|(3), +\&\fBd2i_X509\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The function \fBd2i_SSL_SESSION_ex()\fR was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2001\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_X509.3 b/static/netbsd/man3/d2i_X509.3 new file mode 100644 index 00000000..8e11e3b2 --- /dev/null +++ b/static/netbsd/man3/d2i_X509.3 @@ -0,0 +1,816 @@ +.\" $NetBSD: d2i_X509.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "d2i_X509 3" +.TH d2i_X509 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_ACCESS_DESCRIPTION, +d2i_ADMISSIONS, +d2i_ADMISSION_SYNTAX, +d2i_ASIdOrRange, +d2i_ASIdentifierChoice, +d2i_ASIdentifiers, +d2i_ASN1_BIT_STRING, +d2i_ASN1_BMPSTRING, +d2i_ASN1_ENUMERATED, +d2i_ASN1_GENERALIZEDTIME, +d2i_ASN1_GENERALSTRING, +d2i_ASN1_IA5STRING, +d2i_ASN1_INTEGER, +d2i_ASN1_NULL, +d2i_ASN1_OBJECT, +d2i_ASN1_OCTET_STRING, +d2i_ASN1_PRINTABLE, +d2i_ASN1_PRINTABLESTRING, +d2i_ASN1_SEQUENCE_ANY, +d2i_ASN1_SET_ANY, +d2i_ASN1_T61STRING, +d2i_ASN1_TIME, +d2i_ASN1_TYPE, +d2i_ASN1_UINTEGER, +d2i_ASN1_UNIVERSALSTRING, +d2i_ASN1_UTCTIME, +d2i_ASN1_UTF8STRING, +d2i_ASN1_VISIBLESTRING, +d2i_ASRange, +d2i_AUTHORITY_INFO_ACCESS, +d2i_AUTHORITY_KEYID, +d2i_BASIC_CONSTRAINTS, +d2i_CERTIFICATEPOLICIES, +d2i_CMS_ContentInfo, +d2i_CMS_ReceiptRequest, +d2i_CMS_bio, +d2i_CRL_DIST_POINTS, +d2i_DHxparams, +d2i_DIRECTORYSTRING, +d2i_DISPLAYTEXT, +d2i_DIST_POINT, +d2i_DIST_POINT_NAME, +d2i_DSA_SIG, +d2i_ECDSA_SIG, +d2i_ECPKParameters, +d2i_EDIPARTYNAME, +d2i_ESS_CERT_ID, +d2i_ESS_CERT_ID_V2, +d2i_ESS_ISSUER_SERIAL, +d2i_ESS_SIGNING_CERT, +d2i_ESS_SIGNING_CERT_V2, +d2i_EXTENDED_KEY_USAGE, +d2i_GENERAL_NAME, +d2i_GENERAL_NAMES, +d2i_IPAddressChoice, +d2i_IPAddressFamily, +d2i_IPAddressOrRange, +d2i_IPAddressRange, +d2i_ISSUER_SIGN_TOOL, +d2i_ISSUING_DIST_POINT, +d2i_NAMING_AUTHORITY, +d2i_NETSCAPE_CERT_SEQUENCE, +d2i_NETSCAPE_SPKAC, +d2i_NETSCAPE_SPKI, +d2i_NOTICEREF, +d2i_OCSP_BASICRESP, +d2i_OCSP_CERTID, +d2i_OCSP_CERTSTATUS, +d2i_OCSP_CRLID, +d2i_OCSP_ONEREQ, +d2i_OCSP_REQINFO, +d2i_OCSP_REQUEST, +d2i_OCSP_RESPBYTES, +d2i_OCSP_RESPDATA, +d2i_OCSP_RESPID, +d2i_OCSP_RESPONSE, +d2i_OCSP_REVOKEDINFO, +d2i_OCSP_SERVICELOC, +d2i_OCSP_SIGNATURE, +d2i_OCSP_SINGLERESP, +d2i_OSSL_AA_DIST_POINT, +d2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE, +d2i_OSSL_ALLOWED_ATTRIBUTES_ITEM, +d2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, +d2i_OSSL_ATAV, +d2i_OSSL_ATTRIBUTE_DESCRIPTOR, +d2i_OSSL_ATTRIBUTE_MAPPING, +d2i_OSSL_ATTRIBUTE_MAPPINGS, +d2i_OSSL_ATTRIBUTE_TYPE_MAPPING, +d2i_OSSL_ATTRIBUTE_VALUE_MAPPING, +d2i_OSSL_ATTRIBUTES_SYNTAX, +d2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, +d2i_OSSL_BASIC_ATTR_CONSTRAINTS, +d2i_OSSL_CMP_ATAVS, +d2i_OSSL_CMP_MSG, +d2i_OSSL_CMP_PKIHEADER, +d2i_OSSL_CMP_PKISI, +d2i_OSSL_CRMF_CERTID, +d2i_OSSL_CRMF_CERTTEMPLATE, +d2i_OSSL_CRMF_ENCRYPTEDKEY, +d2i_OSSL_CRMF_ENCRYPTEDVALUE, +d2i_OSSL_CRMF_MSG, +d2i_OSSL_CRMF_MSGS, +d2i_OSSL_CRMF_PBMPARAMETER, +d2i_OSSL_CRMF_PKIPUBLICATIONINFO, +d2i_OSSL_CRMF_SINGLEPUBINFO, +d2i_OSSL_DAY_TIME, +d2i_OSSL_DAY_TIME_BAND, +d2i_OSSL_HASH, +d2i_OSSL_IETF_ATTR_SYNTAX, +d2i_OSSL_INFO_SYNTAX, +d2i_OSSL_INFO_SYNTAX_POINTER, +d2i_OSSL_ISSUER_SERIAL, +d2i_OSSL_NAMED_DAY, +d2i_OSSL_OBJECT_DIGEST_INFO, +d2i_OSSL_PRIVILEGE_POLICY_ID, +d2i_OSSL_ROLE_SPEC_CERT_ID, +d2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, +d2i_OSSL_TARGET_CERT, +d2i_OSSL_TARGET, +d2i_OSSL_TARGETING_INFORMATION, +d2i_OSSL_TARGETS, +d2i_OSSL_TIME_PERIOD, +d2i_OSSL_TIME_SPEC, +d2i_OSSL_TIME_SPEC_ABSOLUTE, +d2i_OSSL_TIME_SPEC_DAY, +d2i_OSSL_TIME_SPEC_MONTH, +d2i_OSSL_TIME_SPEC_TIME, +d2i_OSSL_TIME_SPEC_WEEKS, +d2i_OSSL_TIME_SPEC_X_DAY_OF, +d2i_OSSL_USER_NOTICE_SYNTAX, +d2i_OTHERNAME, +d2i_PBE2PARAM, +d2i_PBEPARAM, +d2i_PBKDF2PARAM, +d2i_PBMAC1PARAM, +d2i_PKCS12, +d2i_PKCS12_BAGS, +d2i_PKCS12_MAC_DATA, +d2i_PKCS12_SAFEBAG, +d2i_PKCS12_bio, +d2i_PKCS12_fp, +d2i_PKCS7, +d2i_PKCS7_DIGEST, +d2i_PKCS7_ENCRYPT, +d2i_PKCS7_ENC_CONTENT, +d2i_PKCS7_ENVELOPE, +d2i_PKCS7_ISSUER_AND_SERIAL, +d2i_PKCS7_RECIP_INFO, +d2i_PKCS7_SIGNED, +d2i_PKCS7_SIGNER_INFO, +d2i_PKCS7_SIGN_ENVELOPE, +d2i_PKCS7_bio, +d2i_PKCS7_fp, +d2i_PKCS8_PRIV_KEY_INFO, +d2i_PKCS8_PRIV_KEY_INFO_bio, +d2i_PKCS8_PRIV_KEY_INFO_fp, +d2i_PKCS8_bio, +d2i_PKCS8_fp, +d2i_PKEY_USAGE_PERIOD, +d2i_POLICYINFO, +d2i_POLICYQUALINFO, +d2i_PROFESSION_INFO, +d2i_PROXY_CERT_INFO_EXTENSION, +d2i_PROXY_POLICY, +d2i_RSA_OAEP_PARAMS, +d2i_RSA_PSS_PARAMS, +d2i_SCRYPT_PARAMS, +d2i_SCT_LIST, +d2i_SXNET, +d2i_SXNETID, +d2i_TS_ACCURACY, +d2i_TS_MSG_IMPRINT, +d2i_TS_MSG_IMPRINT_bio, +d2i_TS_MSG_IMPRINT_fp, +d2i_TS_REQ, +d2i_TS_REQ_bio, +d2i_TS_REQ_fp, +d2i_TS_RESP, +d2i_TS_RESP_bio, +d2i_TS_RESP_fp, +d2i_TS_STATUS_INFO, +d2i_TS_TST_INFO, +d2i_TS_TST_INFO_bio, +d2i_TS_TST_INFO_fp, +d2i_USERNOTICE, +d2i_X509, +d2i_X509_bio, +d2i_X509_fp, +d2i_X509_ACERT, +d2i_X509_ACERT_bio, +d2i_X509_ACERT_fp, +d2i_X509_ALGOR, +d2i_X509_ALGORS, +d2i_X509_ATTRIBUTE, +d2i_X509_CERT_AUX, +d2i_X509_CINF, +d2i_X509_CRL, +d2i_X509_CRL_INFO, +d2i_X509_CRL_bio, +d2i_X509_CRL_fp, +d2i_X509_EXTENSION, +d2i_X509_EXTENSIONS, +d2i_X509_NAME, +d2i_X509_NAME_ENTRY, +d2i_X509_PUBKEY, +d2i_X509_PUBKEY_bio, +d2i_X509_PUBKEY_fp, +d2i_X509_REQ, +d2i_X509_REQ_INFO, +d2i_X509_REQ_bio, +d2i_X509_REQ_fp, +d2i_X509_REVOKED, +d2i_X509_SIG, +d2i_X509_VAL, +i2d_ACCESS_DESCRIPTION, +i2d_ADMISSIONS, +i2d_ADMISSION_SYNTAX, +i2d_ASIdOrRange, +i2d_ASIdentifierChoice, +i2d_ASIdentifiers, +i2d_ASN1_BIT_STRING, +i2d_ASN1_BMPSTRING, +i2d_ASN1_ENUMERATED, +i2d_ASN1_GENERALIZEDTIME, +i2d_ASN1_GENERALSTRING, +i2d_ASN1_IA5STRING, +i2d_ASN1_INTEGER, +i2d_ASN1_NULL, +i2d_ASN1_OBJECT, +i2d_ASN1_OCTET_STRING, +i2d_ASN1_PRINTABLE, +i2d_ASN1_PRINTABLESTRING, +i2d_ASN1_SEQUENCE_ANY, +i2d_ASN1_SET_ANY, +i2d_ASN1_T61STRING, +i2d_ASN1_TIME, +i2d_ASN1_TYPE, +i2d_ASN1_UNIVERSALSTRING, +i2d_ASN1_UTCTIME, +i2d_ASN1_UTF8STRING, +i2d_ASN1_VISIBLESTRING, +i2d_ASN1_bio_stream, +i2d_ASRange, +i2d_AUTHORITY_INFO_ACCESS, +i2d_AUTHORITY_KEYID, +i2d_BASIC_CONSTRAINTS, +i2d_CERTIFICATEPOLICIES, +i2d_CMS_ContentInfo, +i2d_CMS_ReceiptRequest, +i2d_CMS_bio, +i2d_CRL_DIST_POINTS, +i2d_DHxparams, +i2d_DIRECTORYSTRING, +i2d_DISPLAYTEXT, +i2d_DIST_POINT, +i2d_DIST_POINT_NAME, +i2d_DSA_SIG, +i2d_ECDSA_SIG, +i2d_ECPKParameters, +i2d_EDIPARTYNAME, +i2d_ESS_CERT_ID, +i2d_ESS_CERT_ID_V2, +i2d_ESS_ISSUER_SERIAL, +i2d_ESS_SIGNING_CERT, +i2d_ESS_SIGNING_CERT_V2, +i2d_EXTENDED_KEY_USAGE, +i2d_GENERAL_NAME, +i2d_GENERAL_NAMES, +i2d_IPAddressChoice, +i2d_IPAddressFamily, +i2d_IPAddressOrRange, +i2d_IPAddressRange, +i2d_ISSUER_SIGN_TOOL, +i2d_ISSUING_DIST_POINT, +i2d_NAMING_AUTHORITY, +i2d_NETSCAPE_CERT_SEQUENCE, +i2d_NETSCAPE_SPKAC, +i2d_NETSCAPE_SPKI, +i2d_NOTICEREF, +i2d_OCSP_BASICRESP, +i2d_OCSP_CERTID, +i2d_OCSP_CERTSTATUS, +i2d_OCSP_CRLID, +i2d_OCSP_ONEREQ, +i2d_OCSP_REQINFO, +i2d_OCSP_REQUEST, +i2d_OCSP_RESPBYTES, +i2d_OCSP_RESPDATA, +i2d_OCSP_RESPID, +i2d_OCSP_RESPONSE, +i2d_OCSP_REVOKEDINFO, +i2d_OCSP_SERVICELOC, +i2d_OCSP_SIGNATURE, +i2d_OCSP_SINGLERESP, +i2d_OSSL_AA_DIST_POINT, +i2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE, +i2d_OSSL_ALLOWED_ATTRIBUTES_ITEM, +i2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX, +i2d_OSSL_ATAV, +i2d_OSSL_ATTRIBUTE_DESCRIPTOR, +i2d_OSSL_ATTRIBUTE_MAPPING, +i2d_OSSL_ATTRIBUTE_MAPPINGS, +i2d_OSSL_ATTRIBUTE_TYPE_MAPPING, +i2d_OSSL_ATTRIBUTE_VALUE_MAPPING, +i2d_OSSL_ATTRIBUTES_SYNTAX, +i2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX, +i2d_OSSL_BASIC_ATTR_CONSTRAINTS, +i2d_OSSL_CMP_ATAVS, +i2d_OSSL_CMP_MSG, +i2d_OSSL_CMP_PKIHEADER, +i2d_OSSL_CMP_PKISI, +i2d_OSSL_CRMF_CERTID, +i2d_OSSL_CRMF_CERTTEMPLATE, +i2d_OSSL_CRMF_ENCRYPTEDKEY, +i2d_OSSL_CRMF_ENCRYPTEDVALUE, +i2d_OSSL_CRMF_MSG, +i2d_OSSL_CRMF_MSGS, +i2d_OSSL_CRMF_PBMPARAMETER, +i2d_OSSL_CRMF_PKIPUBLICATIONINFO, +i2d_OSSL_CRMF_SINGLEPUBINFO, +i2d_OSSL_HASH, +i2d_OSSL_DAY_TIME, +i2d_OSSL_DAY_TIME_BAND, +i2d_OSSL_IETF_ATTR_SYNTAX, +i2d_OSSL_INFO_SYNTAX, +i2d_OSSL_INFO_SYNTAX_POINTER, +i2d_OSSL_ISSUER_SERIAL, +i2d_OSSL_NAMED_DAY, +i2d_OSSL_OBJECT_DIGEST_INFO, +i2d_OSSL_PRIVILEGE_POLICY_ID, +i2d_OSSL_ROLE_SPEC_CERT_ID, +i2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX, +i2d_OSSL_TARGET_CERT, +i2d_OSSL_TARGET, +i2d_OSSL_TARGETING_INFORMATION, +i2d_OSSL_TARGETS, +i2d_OSSL_TIME_PERIOD, +i2d_OSSL_TIME_SPEC, +i2d_OSSL_TIME_SPEC_ABSOLUTE, +i2d_OSSL_TIME_SPEC_DAY, +i2d_OSSL_TIME_SPEC_MONTH, +i2d_OSSL_TIME_SPEC_TIME, +i2d_OSSL_TIME_SPEC_WEEKS, +i2d_OSSL_TIME_SPEC_X_DAY_OF, +i2d_OSSL_USER_NOTICE_SYNTAX, +i2d_OTHERNAME, +i2d_PBE2PARAM, +i2d_PBEPARAM, +i2d_PBKDF2PARAM, +i2d_PBMAC1PARAM, +i2d_PKCS12, +i2d_PKCS12_BAGS, +i2d_PKCS12_MAC_DATA, +i2d_PKCS12_SAFEBAG, +i2d_PKCS12_bio, +i2d_PKCS12_fp, +i2d_PKCS7, +i2d_PKCS7_DIGEST, +i2d_PKCS7_ENCRYPT, +i2d_PKCS7_ENC_CONTENT, +i2d_PKCS7_ENVELOPE, +i2d_PKCS7_ISSUER_AND_SERIAL, +i2d_PKCS7_NDEF, +i2d_PKCS7_RECIP_INFO, +i2d_PKCS7_SIGNED, +i2d_PKCS7_SIGNER_INFO, +i2d_PKCS7_SIGN_ENVELOPE, +i2d_PKCS7_bio, +i2d_PKCS7_fp, +i2d_PKCS8PrivateKeyInfo_bio, +i2d_PKCS8PrivateKeyInfo_fp, +i2d_PKCS8_PRIV_KEY_INFO, +i2d_PKCS8_PRIV_KEY_INFO_bio, +i2d_PKCS8_PRIV_KEY_INFO_fp, +i2d_PKCS8_bio, +i2d_PKCS8_fp, +i2d_PKEY_USAGE_PERIOD, +i2d_POLICYINFO, +i2d_POLICYQUALINFO, +i2d_PROFESSION_INFO, +i2d_PROXY_CERT_INFO_EXTENSION, +i2d_PROXY_POLICY, +i2d_RSA_OAEP_PARAMS, +i2d_RSA_PSS_PARAMS, +i2d_SCRYPT_PARAMS, +i2d_SCT_LIST, +i2d_SXNET, +i2d_SXNETID, +i2d_TS_ACCURACY, +i2d_TS_MSG_IMPRINT, +i2d_TS_MSG_IMPRINT_bio, +i2d_TS_MSG_IMPRINT_fp, +i2d_TS_REQ, +i2d_TS_REQ_bio, +i2d_TS_REQ_fp, +i2d_TS_RESP, +i2d_TS_RESP_bio, +i2d_TS_RESP_fp, +i2d_TS_STATUS_INFO, +i2d_TS_TST_INFO, +i2d_TS_TST_INFO_bio, +i2d_TS_TST_INFO_fp, +i2d_USERNOTICE, +i2d_X509, +i2d_X509_bio, +i2d_X509_fp, +i2d_X509_ACERT, +i2d_X509_ACERT_bio, +i2d_X509_ACERT_fp, +i2d_X509_ALGOR, +i2d_X509_ALGORS, +i2d_X509_ATTRIBUTE, +i2d_X509_CERT_AUX, +i2d_X509_CINF, +i2d_X509_CRL, +i2d_X509_CRL_INFO, +i2d_X509_CRL_bio, +i2d_X509_CRL_fp, +i2d_X509_EXTENSION, +i2d_X509_EXTENSIONS, +i2d_X509_NAME, +i2d_X509_NAME_ENTRY, +i2d_X509_PUBKEY, +i2d_X509_PUBKEY_bio, +i2d_X509_PUBKEY_fp, +i2d_X509_REQ, +i2d_X509_REQ_INFO, +i2d_X509_REQ_bio, +i2d_X509_REQ_fp, +i2d_X509_REVOKED, +i2d_X509_SIG, +i2d_X509_VAL, +\&\- convert objects from/to ASN.1/DER representation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 3 +\& TYPE *d2i_TYPE(TYPE **a, const unsigned char **ppin, long length); +\& TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); +\& +\& int i2d_TYPE(const TYPE *a, unsigned char **ppout); +\& int i2d_TYPE(TYPE *a, unsigned char **ppout); +\& int i2d_TYPE_fp(FILE *fp, const TYPE *a); +\& int i2d_TYPE_fp(FILE *fp, TYPE *a); +\& int i2d_TYPE_bio(BIO *bp, const TYPE *a); +\& int i2d_TYPE_bio(BIO *bp, TYPE *a); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +In the description here, \fR\f(BITYPE\fR\fB\fR is used a placeholder +for any of the OpenSSL datatypes, such as \fBX509_CRL\fR. +The function parameters \fIppin\fR and \fIppout\fR are generally +either both named \fIpp\fR in the headers, or \fIin\fR and \fIout\fR. +.PP +These functions convert OpenSSL objects to and from their ASN.1/DER +encoding. Unlike the C structures which can have pointers to sub\-objects +within, the DER is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. +.PP +\&\fBd2i_\fR\f(BITYPE\fR() attempts to decode \fIlen\fR bytes at \fI*ppin\fR. If successful a +pointer to the \fB\fR\f(BITYPE\fR\fB\fR structure is returned and \fI*ppin\fR is incremented to +the byte following the parsed data. If \fIa\fR is not NULL then a pointer +to the returned structure is also written to \fI*a\fR. If an error occurred +then NULL is returned. The caller retains ownership of the +returned object and needs to free it when it is no longer needed, e.g. +using \fBX509_free()\fR for X509 objects or \fBDSA_SIG_free()\fR for DSA_SIG objects. +.PP +On a successful return, if \fI*a\fR is not NULL then it is assumed that \fI*a\fR +contains a valid \fR\f(BITYPE\fR\fB\fR structure and an attempt is made to reuse it. +For \fB\fR\f(BITYPE\fR\fB\fR structures where it matters it is possible to set up a library +context on the decoded structure this way (see the \fBEXAMPLES\fR section). +However using the "reuse" capability for other purposes is \fBstrongly +discouraged\fR (see \fBBUGS\fR below, and the discussion in the \fBRETURN VALUES\fR +section). +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() is similar to \fBd2i_\fR\f(BITYPE\fR() except it attempts +to parse data from BIO \fIbp\fR. +.PP +\&\fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() is similar to \fBd2i_\fR\f(BITYPE\fR() except it attempts +to parse data from FILE pointer \fIfp\fR. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() encodes the structure pointed to by \fIa\fR into DER format. +If \fIppout\fR is not NULL, it writes the DER encoded data to the buffer +at \fI*ppout\fR, and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it +returns the length of the encoded data. +.PP +If \fI*ppout\fR is NULL memory will be allocated for a buffer and the encoded +data written to it. In this case \fI*ppout\fR is not incremented and it points +to the start of the data just written. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() is similar to \fBi2d_\fR\f(BITYPE\fR() except it writes +the encoding of the structure \fIa\fR to BIO \fIbp\fR and it +returns 1 for success and 0 for failure. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_fp\fR() is similar to \fBi2d_\fR\f(BITYPE\fR() except it writes +the encoding of the structure \fIa\fR to FILE pointer \fIfp\fR and it +returns 1 for success and 0 for failure. +.PP +These routines do not encrypt private keys and therefore offer no +security; use \fBPEM_write_PrivateKey\fR\|(3) or similar for writing to files. +.SH NOTES +.IX Header "NOTES" +The letters \fBi\fR and \fBd\fR in \fBi2d_\fR\f(BITYPE\fR() stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So \fBi2d_\fR\f(BITYPE\fR\fB\fR() converts from internal to DER. +.PP +The functions can also understand \fBBER\fR forms. +.PP +The actual TYPE structure passed to \fBi2d_\fR\f(BITYPE\fR() must be a valid +populated \fB\fR\f(BITYPE\fR\fB\fR structure \-\- it \fBcannot\fR simply be fed with an +empty structure such as that returned by \fBTYPE_new()\fR. +.PP +The encoded data is in binary form and may contain embedded zeros. +Therefore, any FILE pointers or BIOs should be opened in binary mode. +Functions such as \fBstrlen()\fR will \fBnot\fR return the correct length +of the encoded structure. +.PP +The ways that \fI*ppin\fR and \fI*ppout\fR are incremented after the operation +can trap the unwary. See the \fBWARNINGS\fR section for some common +errors. +The reason for this\-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. +.PP +The following points about the data types might be useful: +.IP \fBASN1_OBJECT\fR 4 +.IX Item "ASN1_OBJECT" +Represents an ASN1 OBJECT IDENTIFIER. +.IP \fBDHparams\fR 4 +.IX Item "DHparams" +Represents a PKCS#3 DH parameters structure. +.IP \fBDHxparams\fR 4 +.IX Item "DHxparams" +Represents an ANSI X9.42 DH parameters structure. +.IP \fBECDSA_SIG\fR 4 +.IX Item "ECDSA_SIG" +Represents an ECDSA signature. +.IP \fBX509_ALGOR\fR 4 +.IX Item "X509_ALGOR" +Represents an \fBAlgorithmIdentifier\fR structure as used in IETF RFC 6960 and +elsewhere. +.IP \fBX509_NAME\fR 4 +.IX Item "X509_NAME" +Represents a \fBName\fR type as used for subject and issuer names in +IETF RFC 6960 and elsewhere. +.IP \fBX509_REQ\fR 4 +.IX Item "X509_REQ" +Represents a PKCS#10 certificate request. +.IP \fBX509_SIG\fR 4 +.IX Item "X509_SIG" +Represents the \fBDigestInfo\fR structure defined in PKCS#1 and PKCS#7. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_\fR\f(BITYPE\fR(), \fBd2i_\fR\f(BITYPE\fR\fB_bio\fR() and \fBd2i_\fR\f(BITYPE\fR\fB_fp\fR() return a valid +\&\fB\fR\f(BITYPE\fR\fB\fR structure or NULL if an error occurs. If the "reuse" capability has +been used with a valid structure being passed in via \fIa\fR, then the object is +freed in the event of error and \fI*a\fR is set to NULL. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() and \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR(), +as well as \fBi2d_ASN1_bio_stream()\fR, +return 1 for success and 0 if an error occurs. +.PP +On error, these functions may record the error in the OpenSSL error queue. +That error queue can be inspected with the \fBERR\fR family of functions, such as +\&\fBERR_print_errors\fR\|(3) and \fBERR_peek_last_error_all\fR\|(3). +.SH EXAMPLES +.IX Header "EXAMPLES" +Allocate and encode the DER encoding of an X509 structure: +.PP +.Vb 2 +\& int len; +\& unsigned char *buf; +\& +\& buf = NULL; +\& len = i2d_X509(x, &buf); +\& if (len < 0) +\& /* error */ +.Ve +.PP +Attempt to decode a buffer: +.PP +.Vb 4 +\& X509 *x; +\& unsigned char *buf; +\& const unsigned char *p; +\& int len; +\& +\& /* Set up buf and len to point to the input buffer. */ +\& p = buf; +\& x = d2i_X509(NULL, &p, len); +\& if (x == NULL) +\& /* error */ +.Ve +.PP +Alternative technique: +.PP +.Vb 4 +\& X509 *x; +\& unsigned char *buf; +\& const unsigned char *p; +\& int len; +\& +\& /* Set up buf and len to point to the input buffer. */ +\& p = buf; +\& x = NULL; +\& +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error */ +.Ve +.PP +Setting up a library context and property query: +.PP +.Vb 6 +\& X509 *x; +\& unsigned char *buf; +\& const unsigned char *p; +\& int len; +\& OSSL_LIB_CTX *libctx = ....; +\& const char *propq = ....; +\& +\& /* Set up buf and len to point to the input buffer. */ +\& p = buf; +\& x = X509_new_ex(libctx, propq); +\& +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error, x was freed and NULL assigned to it (see RETURN VALUES) */ +.Ve +.SH WARNINGS +.IX Header "WARNINGS" +Using a temporary variable is mandatory. A common +mistake is to attempt to use a buffer directly as follows: +.PP +.Vb 2 +\& int len; +\& unsigned char *buf; +\& +\& len = i2d_X509(x, NULL); +\& buf = OPENSSL_malloc(len); +\& ... +\& i2d_X509(x, &buf); +\& ... +\& OPENSSL_free(buf); +.Ve +.PP +This code will result in \fIbuf\fR apparently containing garbage because +it was incremented after the call to point after the data just written. +Also \fIbuf\fR will no longer contain the pointer allocated by \fBOPENSSL_malloc()\fR +and the subsequent call to \fBOPENSSL_free()\fR is likely to crash. +.PP +Another trap to avoid is misuse of the \fIa\fR argument to \fBd2i_\fR\f(BITYPE\fR(): +.PP +.Vb 1 +\& X509 *x; +\& +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error */ +.Ve +.PP +This will probably crash somewhere in \fBd2i_X509()\fR. The reason for this +is that the variable \fIx\fR is uninitialized and an attempt will be made to +interpret its (invalid) value as an \fBX509\fR structure, typically causing +a segmentation violation. If \fIx\fR is set to NULL first then this will not +happen. +.SH BUGS +.IX Header "BUGS" +In some versions of OpenSSL the "reuse" behaviour of \fBd2i_\fR\f(BITYPE\fR() when +\&\fI*a\fR is valid is broken and some parts of the reused structure may +persist if they are not present in the new one. Additionally, in versions of +OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs +the behaviour is inconsistent. Some functions behaved as described here, while +some did not free \fI*a\fR on error and did not set \fI*a\fR to NULL. +.PP +As a result of the above issues the "reuse" behaviour is strongly discouraged. +.PP +\&\fBi2d_\fR\f(BITYPE\fR() will not return an error in many versions of OpenSSL, +if mandatory fields are not initialized due to a programming error +then the encoded structure may contain invalid data or omit the +fields entirely and will not be parsed by \fBd2i_\fR\f(BITYPE\fR\fB\fR(). This may be +fixed in future so code should not assume that \fBi2d_\fR\f(BITYPE\fR\fB\fR() will +always succeed. +.PP +Any function which encodes a structure (\fBi2d_\fR\f(BITYPE\fR(), +\&\fBi2d_\fR\f(BITYPE\fR\fB_bio\fR() or \fBi2d_\fR\f(BITYPE\fR\fB_fp\fR()) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_print_errors\fR\|(3), \fBERR_peek_last_error_all\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBd2i_OSSL_ATTRIBUTES_SYNTAX()\fR, \fBd2i_OSSL_BASIC_ATTR_CONSTRAINTS()\fR, +\&\fBd2i_OSSL_CMP_ATAVS()\fR, \fBd2i_OSSL_IETF_ATTR_SYNTAX()\fR, +\&\fBd2i_OSSL_TARGET()\fR, \fBd2i_OSSL_TARGETING_INFORMATION()\fR, +\&\fBd2i_OSSL_TARGETS()\fR, \fBd2i_OSSL_USER_NOTICE_SYNTAX()\fR, +\&\fBd2i_PBMAC1PARAM()\fR, \fBd2i_X509_ACERT()\fR, \fBd2i_X509_ACERT_bio()\fR, +\&\fBd2i_X509_ACERT_fp()\fR, \fBi2d_OSSL_ATTRIBUTES_SYNTAX()\fR, +\&\fBi2d_OSSL_BASIC_ATTR_CONSTRAINTS()\fR, \fBi2d_OSSL_CMP_ATAVS()\fR, +\&\fBi2d_OSSL_IETF_ATTR_SYNTAX()\fR, \fBi2d_OSSL_TARGET()\fR, +\&\fBi2d_OSSL_TARGETING_INFORMATION()\fR, \fBi2d_OSSL_TARGETS()\fR, +\&\fBi2d_OSSL_USER_NOTICE_SYNTAX()\fR, \fBi2d_PBMAC1PARAM()\fR, \fBi2d_X509_ACERT()\fR, +\&\fBi2d_X509_ACERT_bio()\fR, \fBi2d_X509_ACERT_fp()\fR +were added in OpenSSL 3.4. +.PP +\&\fBd2i_OSSL_AA_DIST_POINT()\fR, +\&\fBd2i_OSSL_ALLOWED_ATTRIBUTES_CHOICE()\fR, \fBd2i_OSSL_ALLOWED_ATTRIBUTES_ITEM()\fR, +\&\fBd2i_OSSL_ALLOWED_ATTRIBUTES_SYNTAX()\fR, +\&\fBd2i_OSSL_ATAV()\fR, \fBd2i_OSSL_ATTRIBUTE_DESCRIPTOR()\fR, \fBd2i_OSSL_ATTRIBUTE_MAPPING()\fR, +\&\fBd2i_OSSL_ATTRIBUTE_MAPPINGS()\fR, \fBd2i_OSSL_ATTRIBUTE_TYPE_MAPPING()\fR, +\&\fBd2i_OSSL_ATTRIBUTE_VALUE_MAPPING()\fR, \fBd2i_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX()\fR, +\&\fBd2i_OSSL_HASH()\fR, \fBd2i_OSSL_INFO_SYNTAX()\fR, +\&\fBd2i_OSSL_INFO_SYNTAX_POINTER()\fR, \fBd2i_OSSL_PRIVILEGE_POLICY_ID()\fR, +\&\fBd2i_OSSL_ROLE_SPEC_CERT_ID()\fR, \fBd2i_OSSL_ROLE_SPEC_CERT_ID_SYNTAX()\fR, +\&\fBi2d_OSSL_AA_DIST_POINT()\fR, +\&\fBi2d_OSSL_ALLOWED_ATTRIBUTES_CHOICE()\fR, \fBi2d_OSSL_ALLOWED_ATTRIBUTES_ITEM()\fR, +\&\fBi2d_OSSL_ALLOWED_ATTRIBUTES_SYNTAX()\fR, +\&\fBi2d_OSSL_ATAV()\fR, \fBi2d_OSSL_ATTRIBUTE_DESCRIPTOR()\fR, \fBi2d_OSSL_ATTRIBUTE_MAPPING()\fR, +\&\fBi2d_OSSL_ATTRIBUTE_MAPPINGS()\fR, \fBi2d_OSSL_ATTRIBUTE_TYPE_MAPPING()\fR, +\&\fBi2d_OSSL_ATTRIBUTE_VALUE_MAPPING()\fR, \fBi2d_OSSL_AUTHORITY_ATTRIBUTE_ID_SYNTAX()\fR, +\&\fBi2d_OSSL_HASH()\fR, \fBi2d_OSSL_INFO_SYNTAX()\fR, +\&\fBi2d_OSSL_INFO_SYNTAX_POINTER()\fR, \fBi2d_OSSL_PRIVILEGE_POLICY_ID()\fR, +\&\fBi2d_OSSL_ROLE_SPEC_CERT_ID()\fR, \fBi2d_OSSL_ROLE_SPEC_CERT_ID_SYNTAX()\fR, +\&\fBd2i_OSSL_CRMF_ENCRYPTEDKEY()\fR, \fBi2d_OSSL_CRMF_ENCRYPTEDKEY()\fR, +\&\fBd2i_OSSL_DAY_TIME()\fR, \fBd2i_OSSL_DAY_TIME_BAND()\fR, \fBd2i_OSSL_NAMED_DAY()\fR, +\&\fBd2i_OSSL_TIME_PERIOD()\fR, \fBd2i_OSSL_TIME_SPEC()\fR, +\&\fBd2i_OSSL_TIME_SPEC_ABSOLUTE()\fR, \fBd2i_OSSL_TIME_SPEC_DAY()\fR, +\&\fBd2i_OSSL_TIME_SPEC_MONTH()\fR, \fBd2i_OSSL_TIME_SPEC_TIME()\fR, +\&\fBd2i_OSSL_TIME_SPEC_WEEKS()\fR, \fBd2i_OSSL_TIME_SPEC_X_DAY_OF()\fR, +\&\fBi2d_OSSL_DAY_TIME()\fR, \fBi2d_OSSL_DAY_TIME_BAND()\fR, +\&\fBi2d_OSSL_NAMED_DAY()\fR, \fBi2d_OSSL_TIME_PERIOD()\fR, +\&\fBi2d_OSSL_TIME_SPEC()\fR, \fBi2d_OSSL_TIME_SPEC_ABSOLUTE()\fR, +\&\fBi2d_OSSL_TIME_SPEC_DAY()\fR, \fBi2d_OSSL_TIME_SPEC_MONTH()\fR, +\&\fBi2d_OSSL_TIME_SPEC_TIME()\fR, \fBi2d_OSSL_TIME_SPEC_WEEKS()\fR, +\&\fBi2d_OSSL_TIME_SPEC_X_DAY_OF()\fR +were added in OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 1998\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/d2i_X509_ALGOR.3 b/static/netbsd/man3/d2i_X509_ALGOR.3 new file mode 100644 index 00000000..3cce32ac --- /dev/null +++ b/static/netbsd/man3/d2i_X509_ALGOR.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: d2i_X509_ALGOR.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_X509_ALGOR 3" +.TH d2i_X509_ALGOR 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_X509_ALGOR, i2d_X509_ALGOR \- AlgorithmIdentifier functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length); +\& int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an \fBX509_ALGOR\fR structure which is +equivalent to the \fBAlgorithmIdentifier\fR structure. +.PP +Othewise these behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_X509_CRL.3 b/static/netbsd/man3/d2i_X509_CRL.3 new file mode 100644 index 00000000..73adee44 --- /dev/null +++ b/static/netbsd/man3/d2i_X509_CRL.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: d2i_X509_CRL.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_X509_CRL 3" +.TH d2i_X509_CRL 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp, +i2d_X509_CRL_bio, i2d_X509_CRL_fp \- PKCS#10 certificate request functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length); +\& int i2d_X509_CRL(X509_CRL *a, unsigned char **pp); +\& +\& X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x); +\& X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); +\& +\& int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); +\& int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an X509 \s-1CRL \s0(certificate revocation +list). +.PP +Othewise the functions behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_X509_NAME.3 b/static/netbsd/man3/d2i_X509_NAME.3 new file mode 100644 index 00000000..6b26111b --- /dev/null +++ b/static/netbsd/man3/d2i_X509_NAME.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: d2i_X509_NAME.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_X509_NAME 3" +.TH d2i_X509_NAME 3 "2015-12-06" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_X509_NAME, i2d_X509_NAME \- X509_NAME encoding functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); +\& int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an \fBX509_NAME\fR structure which is the +same as the \fBName\fR type defined in \s-1RFC2459 \s0(and elsewhere) and used +for example in certificate subject and issuer names. +.PP +Othewise the functions behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_X509_REQ.3 b/static/netbsd/man3/d2i_X509_REQ.3 new file mode 100644 index 00000000..cbe663f8 --- /dev/null +++ b/static/netbsd/man3/d2i_X509_REQ.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: d2i_X509_REQ.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_X509_REQ 3" +.TH d2i_X509_REQ 3 "2009-12-26" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, +i2d_X509_REQ_bio, i2d_X509_REQ_fp \- PKCS#10 certificate request functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length); +\& int i2d_X509_REQ(X509_REQ *a, unsigned char **pp); +\& +\& X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x); +\& X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); +\& +\& int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); +\& int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode a PKCS#10 certificate request. +.PP +Othewise these behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/d2i_X509_SIG.3 b/static/netbsd/man3/d2i_X509_SIG.3 new file mode 100644 index 00000000..1c6e4a0a --- /dev/null +++ b/static/netbsd/man3/d2i_X509_SIG.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: d2i_X509_SIG.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "d2i_X509_SIG 3" +.TH d2i_X509_SIG 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +d2i_X509_SIG, i2d_X509_SIG \- DigestInfo functions. +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length); +\& int i2d_X509_SIG(X509_SIG *a, unsigned char **pp); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions decode and encode an X509_SIG structure which is +equivalent to the \fBDigestInfo\fR structure defined in PKCS#1 and PKCS#7. +.PP +Othewise these behave in a similar way to \fId2i_X509()\fR and \fIi2d_X509()\fR +described in the \fId2i_X509\fR\|(3) manual page. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fId2i_X509\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1TBA\s0 diff --git a/static/netbsd/man3/daemon.3 b/static/netbsd/man3/daemon.3 new file mode 100644 index 00000000..47f3f579 --- /dev/null +++ b/static/netbsd/man3/daemon.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: daemon.3,v 1.15 2003/08/07 16:42:46 agc Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd September 3, 1999 +.Dt DAEMON 3 +.Os +.Sh NAME +.Nm daemon +.Nd run in the background +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn daemon "int nochdir" "int noclose" +.Sh DESCRIPTION +The +.Fn daemon +function is for programs wishing to detach themselves from the +controlling terminal and run in the background as system daemons. +.Pp +Unless the argument +.Fa nochdir +is non-zero, +.Fn daemon +changes the current working directory to the root +.Pq Pa / . +.Pp +Unless the argument +.Fa noclose +is non-zero, +.Fn daemon +will redirect standard input, standard output and standard error +to +.Pa /dev/null . +.Sh RETURN VALUES +On return 0 indicates success with \-1 indicating error. +.Sh ERRORS +The function +.Fn daemon +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr fork 2 +and +.Xr setsid 2 . +.Sh SEE ALSO +.Xr fork 2 , +.Xr setsid 2 +.Sh HISTORY +The +.Fn daemon +function first appeared in +.Bx 4.4 . +.Sh CAVEATS +Unless the +.Ar noclose +argument is non-zero, +.Fn daemon +will close the first three file descriptors and redirect them to +.Pa /dev/null . +Normally, these correspond to standard input, standard output and +standard error. +However, if any of those file descriptors refer to something else they +will still be closed, resulting in incorrect behavior of the calling program. +This can happen if any of standard input, standard output or standard error +have been closed before the program was run. +Programs using +.Fn daemon +should therefore make sure to either call +.Fn daemon +before opening any files or sockets or, alternately, verifying that +any file descriptors obtained have a value greater than 2. +.Sh BUGS +.Fn daemon +uses +.Fn fork +as part of its tty detachment mechanism. +Consequently the process id changes when +.Fn daemon +is invoked. +Processes employing +.Fn daemon +can not be reliably waited upon until +.Fn daemon +has been invoked. diff --git a/static/netbsd/man3/data.3 b/static/netbsd/man3/data.3 new file mode 100644 index 00000000..3ad94416 --- /dev/null +++ b/static/netbsd/man3/data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: data.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_buf.3 diff --git a/static/netbsd/man3/dbm_clearerr.3 b/static/netbsd/man3/dbm_clearerr.3 new file mode 100644 index 00000000..f5a677fa --- /dev/null +++ b/static/netbsd/man3/dbm_clearerr.3 @@ -0,0 +1,306 @@ +.\" $NetBSD: dbm_clearerr.3,v 1.7 2021/12/10 20:36:02 andvar Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 5, 2010 +.Dt DBM_CLEARERR 3 +.Os +.Sh NAME +.Nm dbm_clearerr , +.Nm dbm_close , +.Nm dbm_delete , +.Nm dbm_dirfno , +.Nm dbm_error , +.Nm dbm_fetch , +.Nm dbm_firstkey , +.Nm dbm_nextkey , +.Nm dbm_open , +.Nm dbm_store , +.Nm ndbm +.Nd database functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ndbm.h +.Ft int +.Fn dbm_clearerr "DBM *db" +.Ft void +.Fn dbm_close "DBM *db" +.Ft int +.Fn dbm_delete "DBM *db" "datum key" +.Ft int +.Fn dbm_dirfno "DBM *db" +.Ft int +.Fn dbm_error "DBM *db" +.Ft datum +.Fn dbm_fetch "DBM *db" "datum key" +.Ft datum +.Fn dbm_firstkey "DBM *db" +.Ft datum +.Fn dbm_nextkey "DBM *db" +.Ft DBM * +.Fn dbm_open "const char *file" "int open_flags" "mode_t file_mode" +.Ft int +.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode" +.Sh DESCRIPTION +The +.Nm ndbm +facility provides access to hash database files. +.Pp +Two data types are fundamental to the +.Nm ndbm +facility. +.Fa DBM +serves as a handle to a database. +It is an opaque type. +.Pp +The other data type is +.Fa datum , +which is a structure type which includes the following members: +.Bd -literal -offset indent +void * dptr +size_t dsize +.Ed +.Pp +A +.Fa datum +is thus given by +.Fa dptr +pointing at an object of +.Fa dsize +bytes in length. +.Pp +The +.Fn dbm_open +function opens a database. +The +.Fa file +argument is the pathname which the actual database file pathname +is based on. +This implementation uses a single file with the suffix +.Pa .db +appended to +.Fa file . +The +.Fa open_flags +argument has the same meaning as the +.Fa flags +argument to +.Xr open 2 +except that when opening a database for write-only access the file +is opened for read/write access, and the +.Dv O_APPEND +flag must not be specified. +The +.Fa file_mode +argument has the same meaning as the +.Fa mode +argument to +.Xr open 2 . +.Pp +For the following functions, the +.Fa db +argument is a handle previously returned by a call to +.Fn dbm_open . +.Pp +The +.Fn dbm_close +function closes a database. +.Pp +The +.Fn dbm_fetch +function retrieves a record from the database. +The +.Fa key +argument is a +.Fa datum +that identifies the record to be fetched. +.Pp +The +.Fn dbm_store +function stores a record into the database. +The +.Fa key +argument is a +.Fa datum +that identifies the record to be stored. +The +.Fa content +argument is a +.Fa datum +that specifies the value of the record to be stored. +The +.Fa store_mode +argument specifies the behavior of +.Fn dbm_store +if a record matching +.Fa key +is already present in the database, +.Fa db . +.Fa store_mode +must be one of the following: +.Bl -tag -width DBM_REPLACEXX -offset indent +.It Dv DBM_INSERT +If a record matching +.Fa key +is already present, it is left unchanged. +.It Dv DBM_REPLACE +If a record matching +.Fa key +is already present, its value is replaced by +.Fa content . +.El +.Pp +If no record matching +.Fa key +is present, a new record is inserted regardless of +.Fa store_mode . +.Pp +The +.Fn dbm_delete +function deletes a record from the database. +The +.Fa key +argument is a +.Fa datum +that identifies the record to be deleted. +.Pp +The +.Fn dbm_firstkey +function returns the first key in the database. +.Pp +The +.Fn dbm_nextkey +function returns the next key in the database. +In order to be meaningful, it must be preceded by a call to +.Fn dbm_firstkey . +.Pp +The +.Fn dbm_error +function returns the error indicator of the database. +.Pp +The +.Fn dbm_clearerr +function clears the error indicator of the database. +.Pp +The +.Fn dbm_dirfno +function returns the file descriptor of the underlying database file. +.Sh IMPLEMENTATION NOTES +The +.Nm ndbm +facility is implemented on top of the +.Xr hash 3 +access method of the +.Xr db 3 +database facility. +.Sh RETURN VALUES +The +.Fn dbm_open +function returns a pointer to a +.Fa DBM +when successful; otherwise a null pointer is returned. +.Pp +The +.Fn dbm_close +function returns no value. +.Pp +The +.Fn dbm_fetch +function returns a content +.Fa datum ; +if no record matching +.Fa key +was found or if an error occurred, its +.Fa dptr +member is a null pointer. +.Pp +The +.Fn dbm_store +function returns 0 when the record was successfully inserted; +it returns 1 when called with +.Fa store_mode +being +.Dv DBM_INSERT +and a record matching +.Fa key +is already present; +otherwise a negative value is returned. +.Pp +The +.Fn dbm_delete +function returns 0 when the record was successfully deleted; +otherwise a negative value is returned. +.Pp +The +.Fn dbm_firstkey +and +.Fn dbm_nextkey +functions return a key +.Fa datum . +When the end of the database is reached or if an error occurred, its +.Fa dptr +member is a null pointer. +.Pp +The +.Fn dbm_error +function returns 0 if the error indicator is clear; +if the error indicator is set a non-zero value is returned. +.Pp +The +.Fn dbm_clearerr +function always returns 0. +.Pp +The +.Fn dbm_dirfno +function returns the file descriptor of the underlying database file. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr open 2 , +.Xr db 3 , +.Xr hash 3 +.Sh STANDARDS +The +.Fn dbm_clearerr , +.Fn dbm_close , +.Fn dbm_delete , +.Fn dbm_error , +.Fn dbm_fetch , +.Fn dbm_firstkey , +.Fn dbm_nextkey , +.Fn dbm_open , +and +.Fn dbm_store +functions conform to +.St -xpg4.2 +and +.St -susv2 . +The +.Fn dbm_dirfno +function is an extension. diff --git a/static/netbsd/man3/dbopen.3 b/static/netbsd/man3/dbopen.3 new file mode 100644 index 00000000..1db9a25f --- /dev/null +++ b/static/netbsd/man3/dbopen.3 @@ -0,0 +1,538 @@ +.\" $NetBSD: dbopen.3,v 1.19 2010/12/16 12:08:16 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 +.\" +.Dd December 16, 2010 +.Dt DBOPEN 3 +.Os +.Sh NAME +.Nm dbopen , +.Nm db +.Nd database access methods +.Sh SYNOPSIS +.In sys/types.h +.In limits.h +.In db.h +.In fcntl.h +.Ft DB * +.Fn dbopen "const char *file" "int flags" "mode_t mode" \ +"DBTYPE type" "const void *openinfo" +.Sh DESCRIPTION +.Nm +is the library interface to database files. +The supported file formats are btree, hashed, and UNIX file oriented. +The btree format is a representation of a sorted, balanced tree +structure. +The hashed format is an extensible, dynamic hashing scheme. +The flat-file format is a byte stream file with fixed or variable +length records. +The formats and file format specific information are described in +detail in their respective manual pages +.Xr btree 3 , +.Xr hash 3 , +and +.Xr recno 3 . +.Pp +The +.Fn dbopen +function opens +.Fa file +for reading and/or writing. +Files never intended to be preserved on disk may be created by setting +the file parameter to +.Dv NULL . +.Pp +The +.Fa flags +and +.Fa mode +arguments are as specified to the +.Xr open 2 +routine, however, only the +.Dv O_CREAT , +.Dv O_EXCL , +.Dv O_EXLOCK , +.Dv O_NONBLOCK , +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_SHLOCK , +and +.Dv O_TRUNC +flags are meaningful. +(Note, opening a database file +.Dv O_WRONLY +is not possible.) +.\"Three additional options may be specified by or'ing +.\"them into the +.\".Fa flags +.\"argument. +.\".Pp +.\".Dv DB_LOCK +.\"Do the necessary locking in the database to support concurrent access. +.\"If concurrent access isn't needed or the database is read-only this +.\"flag should not be set, as it tends to have an associated performance +.\"penalty. +.\".Pp +.\".Dv DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".Pp +.\".Dv DB_TXN +.\"Support transactions in the database. +.\"The +.\".Dv DB_LOCK +.\"and +.\".Dv DB_SHMEM +.\"flags must be set as well. +.Pp +The +.Fa type +argument is of type +.Vt DBTYPE +(as defined in the +.In db.h +include file) and may be set to +.Dv DB_BTREE , +.Dv DB_HASH , +or +.Dv DB_RECNO . +.Pp +The +.Fa openinfo +argument is a pointer to an access method specific structure described +in the access method's manual page. +If +.Fa openinfo +is +.Dv NULL , +each access method will use defaults appropriate for the system and +the access method. +.Ss The DB Structure +The +.Fn dbopen +function returns a pointer to a DB structure on success and +.Dv NULL +on error. +The DB structure is defined in the +.In db.h +include file, and contains at least the following fields: +.Bd -literal -offset indent +typedef struct { + DBTYPE type; + int (*close)(const DB *db); + int (*del)(const DB *db, const DBT *key, u_int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); + int (*put)(const DB *db, DBT *key, const DBT *data, + u_int flags); + int (*sync)(const DB *db, u_int flags); + int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); +} DB; +.Ed +.Pp +These elements describe a database type and a set of functions +performing various actions. +These functions take a pointer to a structure as returned by +.Nm , +and sometimes one or more pointers to key/data structures and a flag +value. +.Bl -tag -width closex -offset indent +.It Fa type +The type of the underlying access method (and file format). +.It Fa close +A pointer to a routine to flush any cached information to disk, free +any allocated resources, and close the underlying file(s). +Since key/data pairs may be cached in memory, failing to sync the file +with a +.Fa close +or +.Fa sync +function may result in inconsistent or lost information. +.Fa close +routines return \-1 on error (setting +.Va errno ) +and 0 on success. +.It Fa del +A pointer to a routine to remove key/data pairs from the database. +.Pp +The parameter +.Fa flag +may be set to the following value: +.Bl -tag -width R_CURSORX +.It Dv R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.El +.Pp +.Fa delete +routines return \-1 on error (setting +.Va errno ) , +0 on success, and 1 if the specified +.Fa key +was not in the file. +.It Fa fd +A pointer to a routine which returns a file descriptor representative +of the underlying database. +A file descriptor referencing the same file will be returned to all +processes which call +.Nm +with the same +.Fa file +name. +This file descriptor may be safely used as an argument to the +.Xr fcntl 2 +and +.Xr flock 2 +locking functions. +The file descriptor is not necessarily associated with any of the +underlying files used by the access method. +No file descriptor is available for in memory databases. +.Fa fd +routines return \-1 on error (setting +.Va errno ) , +and the file descriptor on success. +.It Fa get +A pointer to a routine which is the interface for keyed retrieval from +the database. +The address and length of the data associated with the specified +.Fa key +are returned in the structure referenced by +.Fa data . +.Fa get +routines return \-1 on error (setting +.Va errno ) , +0 on success, and 1 if the +.Fa key +was not in the file. +.It Fa put +A pointer to a routine to store key/data pairs in the database. +.Pp +The parameter +.Fa flag +may be set to one of the following values: +.Bl -tag -width R_NOOVERWRITEX +.It Dv R_CURSOR +Replace the key/data pair referenced by the cursor. +The cursor must have previously been initialized. +.It Dv R_IAFTER +Append the data immediately after the data referenced by +.Fa key , +creating a new key/data pair. +The record number of the appended key/data pair is returned in the +.Fa key +structure. +(Applicable only to the +.Dv DB_RECNO +access method.) +.It Dv R_IBEFORE +Insert the data immediately before the data referenced by +.Fa key , +creating a new key/data pair. +The record number of the inserted key/data pair is returned in the +.Fa key +structure. +(Applicable only to the +.Dv DB_RECNO +access method.) +.It Dv R_NOOVERWRITE +Enter the new key/data pair only if the key does not previously +exist. +.It Dv R_SETCURSOR +Store the key/data pair, setting or initializing the position of the +cursor to reference it. +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) +.El +.Pp +.Dv R_SETCURSOR +is available only for the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods because it implies that the keys have an inherent order +which does not change. +.Pp +.Dv R_IAFTER +and +.Dv R_IBEFORE +are available only for the +.Dv DB_RECNO +access method because they each imply that the access method is able +to create new keys. +This is only true if the keys are ordered and independent, record +numbers for example. +.Pp +The default behavior of the +.Fa put +routines is to enter the new key/data pair, replacing any previously +existing key. +.Pp +.Fa put +routines return \-1 on error (setting +.Va errno ) , +0 on success, and 1 if the +.Dv R_NOOVERWRITE +.Fa flag +was set and the key already exists in the file. +.It Fa seq +A pointer to a routine which is the interface for sequential +retrieval from the database. +The address and length of the key are returned in the structure +referenced by +.Fa key , +and the address and length of the data are returned in the +structure referenced by +.Fa data . +.Pp +Sequential key/data pair retrieval may begin at any time, and the +position of the +.Dq cursor +is not affected by calls to the +.Fa del , +.Fa get , +.Fa put , +or +.Fa sync +routines. +Modifications to the database during a sequential scan will be +reflected in the scan, i.e., records inserted behind the cursor will +not be returned while records inserted in front of the cursor will be +returned. +.Pp +The flag value +.Em must +be set to one of the following values: +.Bl -tag -width R_CURSORX +.It Dv R_CURSOR +The data associated with the specified key is returned. +This differs from the +.Fa get +routines in that it sets or initializes the cursor to the location of +the key as well. +(Note, for the +.Dv DB_BTREE +access method, the returned key is not necessarily an exact match for +the specified key. +The returned key is the smallest key greater than or equal to the +specified key, permitting partial key matches and range searches.) +.It Dv R_FIRST +The first key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +.It Dv R_LAST +The last key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) +.It Dv R_NEXT +Retrieve the key/data pair immediately after the cursor. +If the cursor is not yet set, this is the same as the +.Dv R_FIRST +flag. +.It Dv R_PREV +Retrieve the key/data pair immediately before the cursor. +If the cursor is not yet set, this is the same as the +.Dv R_LAST +flag. +(Applicable only to the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods.) +.El +.Pp +.Dv R_LAST +and +.Dv R_PREV +are available only for the +.Dv DB_BTREE +and +.Dv DB_RECNO +access methods because they each imply that the keys have an inherent +order which does not change. +.Pp +.Fa seq +routines return \-1 on error (setting +.Va errno ) , +0 on success and 1 if there are no key/data pairs less than or greater +than the specified or current key. +If the +.Dv DB_RECNO +access method is being used, and if the database file is a character +special file and no complete key/data pairs are currently available, +the +.Fa seq +routines return 2. +.It Fa sync +A pointer to a routine to flush any cached information to disk. +If the database is in memory only, the +.Fa sync +routine has no effect and will always succeed. +.Pp +The flag value may be set to the following value: +.Bl -tag -width ".Dv R_RECNOSYNC" +.It Dv R_RECNOSYNC +If the +.Dv DB_RECNO +access method is being used, this flag causes the sync routine to +apply to the btree file which underlies the recno file, not the recno +file itself. +(See the +.Fa bfname +field of the +.Xr recno 3 +manual page for more information.) +.El +.Pp +.Fa sync +routines return \-1 on error (setting +.Va errno ) +and 0 on success. +.El +.Ss Key/data Pairs +Access to all file types is based on key/data pairs. +Both keys and data are represented by the following data structure: +.Bd -literal -offset indent +typedef struct { + void *data; + size_t size; +} DBT; +.Ed +.Pp +The elements of the DBT structure are defined as follows: +.Bl -tag -width datax -offset indent +.It Fa data +A pointer to a byte string. +.It Fa size +The length of the byte string. +.El +.Pp +Key and data byte strings may reference strings of essentially +unlimited length although any two of them must fit into available +memory at the same time. +It should be noted that the access methods provide no guarantees about +byte string alignment. +.Sh ERRORS +The +.Nm +routine may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr open 2 +and +.Xr malloc 3 +or the following: +.Bl -tag -width Er +.It Er EFTYPE +A file is incorrectly formatted. +.It Er EINVAL +A parameter has been specified (hash function, pad byte, etc.) that is +incompatible with the current file specification or which is not +meaningful for the function (for example, use of the cursor without +prior initialization) or there is a mismatch between the version +number of file and the software. +.It Er EFBIG +The key could not be inserted due to limitations in the DB file format +(e.g., a hash database was out of overflow pages). +.El +.Pp +The +.Fa close +routines may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr close 2 , +.Xr read 2 , +.Xr write 2 , +.Xr free 3 , +or +.Xr fsync 2 . +.Pp +The +.Fa del , +.Fa get , +.Fa put , +and +.Fa seq +routines may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr read 2 , +.Xr write 2 , +.Xr free 3 , +or +.Xr malloc 3 . +.Pp +The +.Fa fd +routines will fail and set +.Va errno +to +.Er ENOENT +for in memory databases. +.Pp +The +.Fa sync +routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr fsync 2 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr hash 3 , +.Xr mpool 3 , +.Xr recno 3 +.Pp +.Rs +.%T LIBTP: Portable, Modular Transactions for UNIX +.%A Margo Seltzer +.%A Michael Olson +.%I USENIX Association +.%B Proceedings of the 1992 Winter USENIX Technical Conference +.%D 1992 +.%P 9-25 +.Re +.Sh BUGS +The typedef DBT is a mnemonic for +.Dq data base thang , +and was used because no one could think of a reasonable name that +wasn't already used. +.Pp +The file descriptor interface is a kludge and will be deleted in a +future version of the interface. +.Pp +None of the access methods provide any form of concurrent access, +locking, or transactions. diff --git a/static/netbsd/man3/dcgettext.3 b/static/netbsd/man3/dcgettext.3 new file mode 100644 index 00000000..9082c86b --- /dev/null +++ b/static/netbsd/man3/dcgettext.3 @@ -0,0 +1 @@ +.so man3/gettext.3 diff --git a/static/netbsd/man3/dcngettext.3 b/static/netbsd/man3/dcngettext.3 new file mode 100644 index 00000000..5fcf629c --- /dev/null +++ b/static/netbsd/man3/dcngettext.3 @@ -0,0 +1 @@ +.so man3/ngettext.3 diff --git a/static/netbsd/man3/deprecated.3 b/static/netbsd/man3/deprecated.3 new file mode 100644 index 00000000..fa69d17d --- /dev/null +++ b/static/netbsd/man3/deprecated.3 @@ -0,0 +1,82 @@ +.TH "deprecated" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +deprecated \- Deprecated List + +.IP "\fBGlobal \fBevbuffer_readline\fP (struct evbuffer *buffer)\fP" 1c +This function is deprecated because its behavior is not correct for almost any protocol, and also because it's wholly subsumed by \fBevbuffer_readln()\fP\&. +.IP "\fBGlobal \fBevbuffer_setcb\fP (struct evbuffer *buffer, evbuffer_cb cb, void *cbarg)\fP" 1c +This function is deprecated because it clears all previous callbacks set on the evbuffer, which can cause confusing behavior if multiple parts of the code all want to add their own callbacks on a buffer\&. Instead, use \fBevbuffer_add()\fP, evbuffer_del(), and evbuffer_setflags() to manage your own evbuffer callbacks without interfering with callbacks set by others\&. +.IP "\fBGlobal \fBevdns_add_server_port\fP (evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data)\fP" 1c +This function is deprecated because it does not allow the caller to specify which even_base it uses\&. The recommended function is \fBevdns_add_server_port_with_base()\fP\&. +.IP "\fBGlobal \fBevdns_clear_nameservers_and_suspend\fP (void)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_clear_nameservers_and_suspend()\fP\&. +.IP "\fBGlobal \fBevdns_count_nameservers\fP (void)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_count_nameservers()\fP\&. +.IP "\fBGlobal \fBevdns_get_global_base\fP (void)\fP" 1c +This function is deprecated because use of the global evdns_base is error-prone\&. +.IP "\fBGlobal \fBevdns_init\fP (void)\fP" 1c +This function is deprecated because it always uses the current event base, and is easily confused by multiple calls to \fBevent_init()\fP, and so is not safe for multithreaded use\&. Additionally, it allocates a global structure that only one thread can use\&. The replacement is \fBevdns_base_new()\fP\&. +.IP "\fBGlobal \fBevdns_nameserver_add\fP (unsigned long int address)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_add()\fP\&. +.IP "\fBGlobal \fBevdns_nameserver_ip_add\fP (const char *ip_as_string)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_ip_add()\fP\&. +.IP "\fBGlobal \fBevdns_resolv_conf_parse\fP (int flags, const char *const filename)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolv_conf_parse()\fP\&. +.IP "\fBGlobal \fBevdns_resolve_ipv4\fP (const char *name, int flags, evdns_callback_type callback, void *ptr)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_ipv4()\fP\&. +.IP "\fBGlobal \fBevdns_resolve_reverse\fP (const struct in_addr *in, int flags, evdns_callback_type callback, void *ptr)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse()\fP\&. +.IP "\fBGlobal \fBevdns_resolve_reverse_ipv6\fP (const struct in6_addr *in, int flags, evdns_callback_type callback, void *ptr)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse_ipv6()\fP\&. +.IP "\fBGlobal \fBevdns_resume\fP (void)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resume()\fP\&. +.IP "\fBGlobal \fBevdns_search_add\fP (const char *domain)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_add()\fP\&. +.IP "\fBGlobal \fBevdns_search_clear\fP (void)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_clear()\fP\&. +.IP "\fBGlobal \fBevdns_search_ndots_set\fP (const int ndots)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_ndots_set()\fP\&. +.IP "\fBGlobal \fBevdns_set_option\fP (const char *option, const char *val, int flags)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_set_option()\fP\&. +.IP "\fBGlobal \fBevdns_shutdown\fP (int fail_requests)\fP" 1c +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is evdns_base_shutdown()\&. +.IP "\fBFile \fBevent_compat\&.h\fP \fP" 1c +All functions in this file are by definition deprecated\&. +.IP "\fBGlobal \fBevent_dispatch\fP (void)\fP" 1c +This function is deprecated because it is easily confused by multiple calls to \fBevent_init()\fP, and because it is not safe for multithreaded use\&. The replacement is \fBevent_base_dispatch()\fP\&. +.IP "\fBGlobal \fBevent_get_method\fP (void)\fP" 1c +This function is obsolete, and has been replaced by \fBevent_base_get_method()\fP\&. Its use is deprecated because it relies on the 'current' base configured by \fBevent_init()\fP\&. +.IP "\fBGlobal \fBevent_init\fP (void)\fP" 1c +This function is deprecated because it replaces the 'current' \fBevent_base\fP, and is totally unsafe for multithreaded use\&. The replacement is \fBevent_base_new()\fP\&. +.IP "\fBGlobal \fBevent_loop\fP (int)\fP" 1c +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loop()\fP\&. +.IP "\fBGlobal \fBevent_loopbreak\fP (void)\fP" 1c +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loopbreak()\fP\&. +.IP "\fBGlobal \fBevent_loopexit\fP (const struct timeval *)\fP" 1c +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loopexit()\fP\&. +.IP "\fBGlobal \fBevent_once\fP (evutil_socket_t, short, void(*)(evutil_socket_t, short, void *), void *, const struct timeval *)\fP" 1c +This function is obsolete, and has been replaced by \fBevent_base_once()\fP\&. Its use is deprecated because it relies on the 'current' base configured by \fBevent_init()\fP\&. +.IP "\fBGlobal \fBevent_priority_init\fP (int)\fP" 1c +This function is deprecated because it is easily confused by multiple calls to \fBevent_init()\fP, and because it is not safe for multithreaded use\&. The replacement is \fBevent_base_priority_init()\fP\&. +.IP "\fBGlobal \fBevent_set\fP (struct event *, evutil_socket_t, short, void(*)(evutil_socket_t, short, void *), void *)\fP" 1c +\fBevent_set()\fP is not recommended for new code, because it requires a subsequent call to \fBevent_base_set()\fP to be safe under most circumstances\&. Use \fBevent_assign()\fP or \fBevent_new()\fP instead\&. +.IP "\fBGlobal \fBevhttp_connection_new\fP (const char *address, ev_uint16_t port)\fP" 1c +It does not allow an event base to be specified +.IP "\fBGlobal \fBevhttp_connection_set_base\fP (struct evhttp_connection *evcon, struct \fBevent_base\fP *base)\fP" 1c +XXXX Why? +.IP "\fBGlobal \fBevhttp_decode_uri\fP (const char *uri)\fP" 1c +This function is deprecated; you probably want to use evhttp_get_decoded_uri instead\&. +.IP "\fBGlobal \fBevhttp_parse_query\fP (const char *uri, struct evkeyvalq *headers)\fP" 1c +This function is deprecated as of Libevent 2\&.0\&.9\&. Use evhttp_uri_parse and evhttp_parse_query_str instead\&. +.IP "\fBGlobal \fBevhttp_start\fP (const char *address, ev_uint16_t port)\fP" 1c +It does not allow an event base to be specified +.IP "\fBModule \fBMisnamed functions\fP \fP" 1c +These macros are deprecated because their names don't follow Libevent's naming conventions\&. +.IP "\fBModule \fBsignal_* macros\fP \fP" 1c +These macros are deprecated because their naming is inconsistent with the rest of Libevent\&. +.IP "\fBModule \fBtimeout_* macros\fP \fP" 1c +These macros are deprecated because their naming is inconsistent with the rest of Libevent\&. +.PP + diff --git a/static/netbsd/man3/des.3 b/static/netbsd/man3/des.3 new file mode 100644 index 00000000..320eac89 --- /dev/null +++ b/static/netbsd/man3/des.3 @@ -0,0 +1,496 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "des 3" +.TH des 3 "2009-07-20" "0.9.6j" "libdes" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +des_random_key, des_set_key, des_key_sched, des_set_key_checked, +des_set_key_unchecked, des_set_odd_parity, des_is_weak_key, +des_ecb_encrypt, des_ecb2_encrypt, des_ecb3_encrypt, des_ncbc_encrypt, +des_cfb_encrypt, des_ofb_encrypt, des_pcbc_encrypt, des_cfb64_encrypt, +des_ofb64_encrypt, des_xcbc_encrypt, des_ede2_cbc_encrypt, +des_ede2_cfb64_encrypt, des_ede2_ofb64_encrypt, des_ede3_cbc_encrypt, +des_ede3_cbcm_encrypt, des_ede3_cfb64_encrypt, des_ede3_ofb64_encrypt, +des_read_password, des_read_2passwords, des_read_pw_string, +des_cbc_cksum, des_quad_cksum, des_string_to_key, des_string_to_2keys, +des_fcrypt, des_crypt, des_enc_read, des_enc_write \- DES encryption +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void des_random_key(des_cblock *ret); +\& +\& int des_set_key(const_des_cblock *key, des_key_schedule schedule); +\& int des_key_sched(const_des_cblock *key, des_key_schedule schedule); +\& int des_set_key_checked(const_des_cblock *key, +\& des_key_schedule schedule); +\& void des_set_key_unchecked(const_des_cblock *key, +\& des_key_schedule schedule); +\& +\& void des_set_odd_parity(des_cblock *key); +\& int des_is_weak_key(const_des_cblock *key); +\& +\& void des_ecb_encrypt(const_des_cblock *input, des_cblock *output, +\& des_key_schedule ks, int enc); +\& void des_ecb2_encrypt(const_des_cblock *input, des_cblock *output, +\& des_key_schedule ks1, des_key_schedule ks2, int enc); +\& void des_ecb3_encrypt(const_des_cblock *input, des_cblock *output, +\& des_key_schedule ks1, des_key_schedule ks2, +\& des_key_schedule ks3, int enc); +\& +\& void des_ncbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, des_key_schedule schedule, des_cblock *ivec, +\& int enc); +\& void des_cfb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, des_key_schedule schedule, +\& des_cblock *ivec, int enc); +\& void des_ofb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, des_key_schedule schedule, +\& des_cblock *ivec); +\& void des_pcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, des_key_schedule schedule, des_cblock *ivec, +\& int enc); +\& void des_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, des_key_schedule schedule, des_cblock *ivec, +\& int *num, int enc); +\& void des_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, des_key_schedule schedule, des_cblock *ivec, +\& int *num); +\& +\& void des_xcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, des_key_schedule schedule, des_cblock *ivec, +\& const_des_cblock *inw, const_des_cblock *outw, int enc); +\& +\& void des_ede2_cbc_encrypt(const unsigned char *input, +\& unsigned char *output, long length, des_key_schedule ks1, +\& des_key_schedule ks2, des_cblock *ivec, int enc); +\& void des_ede2_cfb64_encrypt(const unsigned char *in, +\& unsigned char *out, long length, des_key_schedule ks1, +\& des_key_schedule ks2, des_cblock *ivec, int *num, int enc); +\& void des_ede2_ofb64_encrypt(const unsigned char *in, +\& unsigned char *out, long length, des_key_schedule ks1, +\& des_key_schedule ks2, des_cblock *ivec, int *num); +\& +\& void des_ede3_cbc_encrypt(const unsigned char *input, +\& unsigned char *output, long length, des_key_schedule ks1, +\& des_key_schedule ks2, des_key_schedule ks3, des_cblock *ivec, +\& int enc); +\& void des_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, +\& long length, des_key_schedule ks1, des_key_schedule ks2, +\& des_key_schedule ks3, des_cblock *ivec1, des_cblock *ivec2, +\& int enc); +\& void des_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, des_key_schedule ks1, des_key_schedule ks2, +\& des_key_schedule ks3, des_cblock *ivec, int *num, int enc); +\& void des_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, des_key_schedule ks1, +\& des_key_schedule ks2, des_key_schedule ks3, +\& des_cblock *ivec, int *num); +\& +\& int des_read_password(des_cblock *key, const char *prompt, int verify); +\& int des_read_2passwords(des_cblock *key1, des_cblock *key2, +\& const char *prompt, int verify); +\& int des_read_pw_string(char *buf, int length, const char *prompt, +\& int verify); +\& +\& DES_LONG des_cbc_cksum(const unsigned char *input, des_cblock *output, +\& long length, des_key_schedule schedule, +\& const_des_cblock *ivec); +\& DES_LONG des_quad_cksum(const unsigned char *input, des_cblock output[], +\& long length, int out_count, des_cblock *seed); +\& void des_string_to_key(const char *str, des_cblock *key); +\& void des_string_to_2keys(const char *str, des_cblock *key1, +\& des_cblock *key2); +\& +\& char *des_fcrypt(const char *buf, const char *salt, char *ret); +\& char *des_crypt(const char *buf, const char *salt); +\& char *crypt(const char *buf, const char *salt); +\& +\& int des_enc_read(int fd, void *buf, int len, des_key_schedule sched, +\& des_cblock *iv); +\& int des_enc_write(int fd, const void *buf, int len, +\& des_key_schedule sched, des_cblock *iv); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library contains a fast implementation of the \s-1DES\s0 encryption +algorithm. +.PP +There are two phases to the use of \s-1DES\s0 encryption. The first is the +generation of a \fIdes_key_schedule\fR from a key, the second is the +actual encryption. A \s-1DES\s0 key is of type \fIdes_cblock\fR. This type is +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. +.PP +\&\fIdes_random_key()\fR generates a random key. The \s-1PRNG\s0 must be seeded +prior to using this function (see \fIrand\fR\|(3); for backward +compatibility the function \fIdes_random_seed()\fR is available as well). +If the \s-1PRNG\s0 could not generate a secure key, 0 is returned. In +earlier versions of the library, \fIdes_random_key()\fR did not generate +secure keys. +.PP +Before a \s-1DES\s0 key can be used, it must be converted into the +architecture dependent \fIdes_key_schedule\fR via the +\&\fIdes_set_key_checked()\fR or \fIdes_set_key_unchecked()\fR function. +.PP +\&\fIdes_set_key_checked()\fR will check that the key passed is of odd parity +and is not a week or semi-weak key. If the parity is wrong, then \-1 +is returned. If the key is a weak key, then \-2 is returned. If an +error is returned, the key schedule is not generated. +.PP +\&\fIdes_set_key()\fR (called \fIdes_key_sched()\fR in the \s-1MIT\s0 library) works like +\&\fIdes_set_key_checked()\fR if the \fIdes_check_key\fR flag is non-zero, +otherwise like \fIdes_set_key_unchecked()\fR. These functions are available +for compatibility; it is recommended to use a function that does not +depend on a global variable. +.PP +\&\fIdes_set_odd_parity()\fR (called \fIdes_fixup_key_parity()\fR in the \s-1MIT\s0 +library) sets the parity of the passed \fIkey\fR to odd. +.PP +\&\fIdes_is_weak_key()\fR returns 1 is the passed key is a weak key, 0 if it +is ok. The probability that a randomly generated key is weak is +1/2^52, so it is not really worth checking for them. +.PP +The following routines mostly operate on an input and output stream of +\&\fIdes_cblock\fRs. +.PP +\&\fIdes_ecb_encrypt()\fR is the basic \s-1DES\s0 encryption routine that encrypts or +decrypts a single 8\-byte \fIdes_cblock\fR in \fIelectronic code book\fR +(\s-1ECB\s0) mode. It always transforms the input data, pointed to by +\&\fIinput\fR, into the output data, pointed to by the \fIoutput\fR argument. +If the \fIencrypt\fR argument is non-zero (\s-1DES_ENCRYPT\s0), the \fIinput\fR +(cleartext) is encrypted in to the \fIoutput\fR (ciphertext) using the +key_schedule specified by the \fIschedule\fR argument, previously set via +\&\fIdes_set_key\fR. If \fIencrypt\fR is zero (\s-1DES_DECRYPT\s0), the \fIinput\fR (now +ciphertext) is decrypted into the \fIoutput\fR (now cleartext). Input +and output may overlap. \fIdes_ecb_encrypt()\fR does not return a value. +.PP +\&\fIdes_ecb3_encrypt()\fR encrypts/decrypts the \fIinput\fR block by using +three-key Triple-DES encryption in \s-1ECB\s0 mode. This involves encrypting +the input with \fIks1\fR, decrypting with the key schedule \fIks2\fR, and +then encrypting with \fIks3\fR. This routine greatly reduces the chances +of brute force breaking of \s-1DES\s0 and has the advantage of if \fIks1\fR, +\&\fIks2\fR and \fIks3\fR are the same, it is equivalent to just encryption +using \s-1ECB\s0 mode and \fIks1\fR as the key. +.PP +The macro \fIdes_ecb2_encrypt()\fR is provided to perform two-key Triple-DES +encryption by using \fIks1\fR for the final encryption. +.PP +\&\fIdes_ncbc_encrypt()\fR encrypts/decrypts using the \fIcipher-block-chaining\fR +(\s-1CBC\s0) mode of \s-1DES\s0. If the \fIencrypt\fR argument is non-zero, the +routine cipher-block-chain encrypts the cleartext data pointed to by +the \fIinput\fR argument into the ciphertext pointed to by the \fIoutput\fR +argument, using the key schedule provided by the \fIschedule\fR argument, +and initialization vector provided by the \fIivec\fR argument. If the +\&\fIlength\fR argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. +.PP +\&\fIdes_xcbc_encrypt()\fR is \s-1RSA\s0's \s-1DESX\s0 mode of \s-1DES\s0. It uses \fIinw\fR and +\&\fIoutw\fR to 'whiten' the encryption. \fIinw\fR and \fIoutw\fR are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than \s-1CBC\s0 \s-1DES\s0. +.PP +\&\fIdes_ede3_cbc_encrypt()\fR implements outer triple \s-1CBC\s0 \s-1DES\s0 encryption with +three keys. This means that each \s-1DES\s0 operation inside the \s-1CBC\s0 mode is +really an \f(CW\*(C`C=E(ks3,D(ks2,E(ks1,M)))\*(C'\fR. This mode is used by \s-1SSL\s0. +.PP +The \fIdes_ede2_cbc_encrypt()\fR macro implements two-key Triple-DES by +reusing \fIks1\fR for the final encryption. \f(CW\*(C`C=E(ks1,D(ks2,E(ks1,M)))\*(C'\fR. +This form of Triple-DES is used by the \s-1RSAREF\s0 library. +.PP +\&\fIdes_pcbc_encrypt()\fR encrypt/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +\&\fIdes_ncbc_encrypt()\fR. +.PP +\&\fIdes_cfb_encrypt()\fR encrypt/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete \s-1DES\s0 \s-1ECB\s0 encryption per \fInumbits\fR, this function is only +suggested for use when sending small numbers of characters. +.PP +\&\fIdes_cfb64_encrypt()\fR +implements \s-1CFB\s0 mode of \s-1DES\s0 with 64bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, no 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains 'how far' we are though ivec. If this does +not make much sense, read more about cfb mode of \s-1DES\s0 :\-). +.PP +\&\fIdes_ede3_cfb64_encrypt()\fR and \fIdes_ede2_cfb64_encrypt()\fR is the same as +\&\fIdes_cfb64_encrypt()\fR except that Triple-DES is used. +.PP +\&\fIdes_ofb_encrypt()\fR encrypts using output feedback mode. This method +takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete \s-1DES\s0 \s-1ECB\s0 encryption per numbits, this function is only +suggested for use when sending small numbers of characters. +.PP +\&\fIdes_ofb64_encrypt()\fR is the same as \fIdes_cfb64_encrypt()\fR using Output +Feed Back mode. +.PP +\&\fIdes_ede3_ofb64_encrypt()\fR and \fIdes_ede2_ofb64_encrypt()\fR is the same as +\&\fIdes_ofb64_encrypt()\fR, using Triple-DES. +.PP +The following functions are included in the \s-1DES\s0 library for +compatibility with the \s-1MIT\s0 Kerberos library. \fIdes_read_pw_string()\fR +is also available under the name \fIEVP_read_pw_string()\fR. +.PP +\&\fIdes_read_pw_string()\fR writes the string specified by \fIprompt\fR to +standard output, turns echo off and reads in input string from the +terminal. The string is returned in \fIbuf\fR, which must have space for +at least \fIlength\fR bytes. If \fIverify\fR is set, the user is asked for +the password twice and unless the two copies match, an error is +returned. A return code of \-1 indicates a system error, 1 failure due +to use interaction, and 0 is success. +.PP +\&\fIdes_read_password()\fR does the same and converts the password to a \s-1DES\s0 +key by calling \fIdes_string_to_key()\fR; \fIdes_read_2password()\fR operates in +the same way as \fIdes_read_password()\fR except that it generates two keys +by using the \fIdes_string_to_2key()\fR function. \fIdes_string_to_key()\fR is +available for backward compatibility with the \s-1MIT\s0 library. New +applications should use a cryptographic hash function. The same +applies for \fIdes_string_to_2key()\fR. +.PP +\&\fIdes_cbc_cksum()\fR produces an 8 byte checksum based on the input stream +(via \s-1CBC\s0 encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in \fIoutput\fR. This function is +used by Kerberos v4. Other applications should use +\&\fIEVP_DigestInit\fR\|(3) etc. instead. +.PP +\&\fIdes_quad_cksum()\fR is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on \fIout_count\fR, 1, 2, 3 or 4 times. If \fIoutput\fR is +non-NULL, the 8 bytes generated by each pass are written into +\&\fIoutput\fR. +.PP +The following are DES-based transformations: +.PP +\&\fIdes_fcrypt()\fR is a fast version of the Unix \fIcrypt\fR\|(3) function. This +version takes only a small amount of space relative to other fast +\&\fIcrypt()\fR implementations. This is different to the normal crypt in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal crypt. +.PP +\&\fIdes_crypt()\fR is a faster replacement for the normal system \fIcrypt()\fR. +This function calls \fIdes_fcrypt()\fR with a static array passed as the +third parameter. This emulates the normal non-thread safe semantics +of \fIcrypt\fR\|(3). +.PP +\&\fIdes_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from +buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default) +using \fIsched\fR for the key and \fIiv\fR as a starting vector. The actual +data send down \fIfd\fR consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. +.PP +\&\fIdes_enc_read()\fR is used to read \fIlen\fR bytes from file descriptor +\&\fIfd\fR into buffer \fIbuf\fR. The data being read from \fIfd\fR is assumed to +have come from \fIdes_enc_write()\fR and is decrypted using \fIsched\fR for +the key schedule and \fIiv\fR for the initial vector. +.PP +\&\fBWarning:\fR The data format used by \fIdes_enc_write()\fR and \fIdes_enc_read()\fR +has a cryptographic weakness: When asked to write more than \s-1MAXWRITE\s0 +bytes, \fIdes_enc_write()\fR will split the data into several chunks that +are all encrypted using the same \s-1IV\s0. So don't use these functions +unless you are sure you know what you do (in which case you might not +want to use them anyway). They cannot handle non-blocking sockets. +\&\fIdes_enc_read()\fR uses an internal state and thus cannot be used on +multiple files. +.PP +\&\fIdes_rw_mode\fR is used to specify the encryption mode to use with +\&\fIdes_enc_read()\fR and \fIdes_end_write()\fR. If set to \fI\s-1DES_PCBC_MODE\s0\fR (the +default), des_pcbc_encrypt is used. If set to \fI\s-1DES_CBC_MODE\s0\fR +des_cbc_encrypt is used. +.SH "NOTES" +.IX Header "NOTES" +Single-key \s-1DES\s0 is insecure due to its short key size. \s-1ECB\s0 mode is +not suitable for most applications; see \fIdes_modes\fR\|(7). +.PP +The \fIevp\fR\|(3) library provides higher-level encryption functions. +.SH "BUGS" +.IX Header "BUGS" +\&\fIdes_3cbc_encrypt()\fR is flawed and must not be used in applications. +.PP +\&\fIdes_cbc_encrypt()\fR does not modify \fBivec\fR; use \fIdes_ncbc_encrypt()\fR +instead. +.PP +\&\fIdes_cfb_encrypt()\fR and \fIdes_ofb_encrypt()\fR operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! +.PP +\&\fIdes_read_pw_string()\fR is the most machine/OS dependent function and +normally generates the most problems when porting this code. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ANSI\s0 X3.106 +.PP +The \fBdes\fR library was written to be source code compatible with +the \s-1MIT\s0 Kerberos library. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypt\fR\|(3), \fIdes_modes\fR\|(7), \fIevp\fR\|(3), \fIrand\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIdes_cbc_cksum()\fR, \fIdes_cbc_encrypt()\fR, \fIdes_ecb_encrypt()\fR, +\&\fIdes_is_weak_key()\fR, \fIdes_key_sched()\fR, \fIdes_pcbc_encrypt()\fR, +\&\fIdes_quad_cksum()\fR, \fIdes_random_key()\fR, \fIdes_read_password()\fR and +\&\fIdes_string_to_key()\fR are available in the \s-1MIT\s0 Kerberos library; +\&\fIdes_check_key_parity()\fR, \fIdes_fixup_key_parity()\fR and \fIdes_is_weak_key()\fR +are available in newer versions of that library. +.PP +\&\fIdes_set_key_checked()\fR and \fIdes_set_key_unchecked()\fR were added in +OpenSSL 0.9.5. +.PP +\&\fIdes_generate_random_block()\fR, \fIdes_init_random_number_generator()\fR, +\&\fIdes_new_random_key()\fR, \fIdes_set_random_generator_seed()\fR and +\&\fIdes_set_sequence_number()\fR and \fIdes_rand_data()\fR are used in newer +versions of Kerberos but are not implemented here. +.PP +\&\fIdes_random_key()\fR generated cryptographically weak random data in +SSLeay and in OpenSSL prior version 0.9.5, as well as in the original +\&\s-1MIT\s0 library. +.SH "AUTHOR" +.IX Header "AUTHOR" +Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project +(http://www.openssl.org). diff --git a/static/netbsd/man3/devname.3 b/static/netbsd/man3/devname.3 new file mode 100644 index 00000000..e287d8b0 --- /dev/null +++ b/static/netbsd/man3/devname.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: devname.3,v 1.17 2017/09/10 10:12:43 wiz Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)devname.3 8.2 (Berkeley) 4/29/95 +.\" +.Dd September 9, 2017 +.Dt DEVNAME 3 +.Os +.Sh NAME +.Nm devname , +.Nm devname_r +.Nd get device name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.In sys/stat.h +.Ft char * +.Fn devname "dev_t dev" "mode_t type" +.Ft int +.Fn devname_r "dev_t dev" "mode_t type" "char *path" "size_t len" +.Sh DESCRIPTION +The +.Fn devname +function returns a pointer to the static buffer with the name of the +block or character device in +.Dq Pa /dev +with a device number of +.Fa dev , +and a file type matching the one encoded in +.Fa type +which must be one of S_IFBLK or S_IFCHR. +If no device matches the specified values, or no information is +available, +.Dv NULL +is returned. +.Pp +The +.Fn devname_r +function is a reentrant and thread-safe version of +.Fn devname . +This function returns the device name by copying it into the +.Fa path +argument with up to +.Fa len +characters. +The +.Fa path +argument is always nul-terminated. +.Pp +The traditional display for applications when no device is +found is the string +.Dq ?? . +.Sh RETURN VALUES +If successful, +.Fn devname +returns a pointer to a nul-terminated string containing the name of the device. +If an error occurs +.Fa devname +will return +.Dv NULL . +.Pp +If successful, +.Fn devname_r +places a nul-terminated string containing the name of the device in +the buffer pointed to by +.Ar path +and returns 0. +If an error occurs +.Fn devname_r +will return an error number from +.In sys/errno.h +indicating what went wrong. +.Sh FILES +.Bl -tag -width /var/run/dev.cdb -compact +.It Pa /var/run/dev.cdb +Device database file. +.El +.Sh ERRORS +The +.Fn devname_r +function may fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The corresponding device does not exist. +.It Bq Er ERANGE +The passed buffer length is too short. +.El +.Sh SEE ALSO +.Xr stat 2 , +.Xr dev_mkdb 8 +.Sh HISTORY +The +.Nm devname +function call appeared in +.Bx 4.4 . +.Pp +The +.Fn devname_r +function first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/dgettext.3 b/static/netbsd/man3/dgettext.3 new file mode 100644 index 00000000..9082c86b --- /dev/null +++ b/static/netbsd/man3/dgettext.3 @@ -0,0 +1 @@ +.so man3/gettext.3 diff --git a/static/netbsd/man3/dhcpctl.3 b/static/netbsd/man3/dhcpctl.3 new file mode 100644 index 00000000..9598b05f --- /dev/null +++ b/static/netbsd/man3/dhcpctl.3 @@ -0,0 +1,607 @@ +.\" $NetBSD: dhcpctl.3,v 1.3 2022/04/03 01:10:58 christos Exp $ +.\" +.\" -*- nroff -*- +.\" +.\" Project: DHCP +.\" File: dhcpctl.3 +.\" RCSId: Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp +.\" +.\" Copyright (c) 2004-2022 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 2000-2003 by Internet Software Consortium +.\" Copyright (c) 2000 Nominum, Inc. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" PO Box 360 +.\" Newmarket, NH 03857 USA +.\" +.\" https://www.isc.org/ +.\" +.\" Description: dhcpctl man page. +.\" +.\" +.Dd Nov 15, 2000 +.Dt DHCPCTL 3 +.Os DHCP 3 +.ds vT DHCP Programmer's Manual +.\" +.\" +.\" +.Sh NAME +.Nm dhcpctl_initialize +.Nd dhcpctl library initialization. +.\" +.\" +.\" +.Sh SYNOPSIS +.Fd #include +.Ft dhcpctl_status +.Fo dhcpctl_initialize +.Fa void +.Fc +.\" +.Ft dhcpctl_status +.Fo dhcpctl_connect +.Fa "dhcpctl_handle *cxn" +.Fa "const char *host" +.Fa "int port" +.Fa "dhcpctl_handle auth" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_timed_connect +.Fa "dhcpctl_handle *cxn" +.Fa "const char *host" +.Fa "int port" +.Fa "dhcpctl_handle auth" +.Fa "dhcpctl_status *status" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_disconnect +.Fa "dhcpctl_handle *cxn" +.Fa "int force" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_wait_for_completion +.Fa "dhcpctl_handle object" +.Fa "dhcpctl_status *status" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_timed_wait_for_completion +.Fa "dhcpctl_handle object" +.Fa "dhcpctl_status *status" +.Fa "struct timeval *timeout" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_get_value +.Fa "dhcpctl_data_string *value" +.Fa "dhcpctl_handle object" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_get_boolean +.Fa "int *value" +.Fa "dhcpctl_handle object" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_set_value +.Fa "dhcpctl_handle object" +.Fa "dhcpctl_data_string value" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_set_string_value +.Fa "dhcpctl_handle object" +.Fa "const char *value" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_set_boolean_value +.Fa "dhcpctl_handle object" +.Fa "int value" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_set_int_value +.Fa "dhcpctl_handle object" +.Fa "int value" +.Fa "const char *name" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_object_update +.Fa "dhcpctl_handle connection" +.Fa "dhcpctl_handle object" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_object_refresh +.Fa "dhcpctl_handle connection" +.Fa "dhcpctl_handle object" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_object_remove +.Fa "dhcpctl_handle connection" +.Fa "dhcpctl_handle object" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_set_callback +.Fa "dhcpctl_handle object" +.Fa "void *data" +.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_new_authenticator +.Fa "dhcpctl_handle *object" +.Fa "const char *name" +.Fa "const char *algorithm" +.Fa "const char *secret" +.Fa "unsigned secret_len" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_new_object +.Fa "dhcpctl_handle *object" +.Fa "dhcpctl_handle connection" +.Fa "const char *object_type" +.Fc +.\" +.\" +.\" +.Ft dhcpctl_status +.Fo dhcpctl_open_object +.Fa "dhcpctl_handle object" +.Fa "dhcpctl_handle connection" +.Fa "int flags" +.Fc +.\" +.\" +.\" +.Ft isc_result_t +.Fo omapi_data_string_new +.Fa dhcpctl_data_string *data +.Fa unsigned int length +.Fa const char *filename, +.Fa int lineno +.Fc +.\" +.\" +.\" +.Ft isc_result_t +.Fo dhcpctl_data_string_dereference +.Fa "dhcpctl_data_string *" +.Fa "const char *" +.Fa "int" +.Fc +.Sh DESCRIPTION +The dhcpctl set of functions provide an API that can be used to communicate +with and manipulate a running ISC DHCP server. All functions return a value of +.Dv isc_result_t . +The return values reflects the result of operations to local data +structures. If an operation fails on the server for any reason, then the error +result will be returned through the +second parameter of the +.Fn dhcpctl_wait_for_completion +call. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_initialize +sets up the data structures the library needs to do its work. This function +must be called once before any other. +.Pp +.Fn dhcpctl_connect +opens a connection to the DHCP server at the given host and port. If an +authenticator has been created for the connection, then it is given as the 4th +argument. On a successful return the address pointed at by the first +argument will have a new connection object assigned to it. +.Pp +For example: +.Bd -literal -offset indent +s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL); +.Ed +.Pp +connects to the DHCP server on the localhost via port 7911 (the standard +OMAPI port). No authentication is used for the connection. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_timed_connect +opens a connection to the DHCP server at the given host and port. If an +authenticator has been created for the connection, then it is given as the 4th +argument. On a successful return the address pointed at by the first +argument will have a new connection object assigned to it. +How long the function waits for complete the connection is dictated by the value +of the parameter, \fBtimeout\fR. If the value is null, it will wait indefinitely +Otherwise it will wait for the amount of time specified by \fBtimeout\fR +(tv_sec:tv_usec). Values of zero for both fields are valid but not recommended. +An example is shown below: +.Pp +For example: +.Bd -literal -offset indent +struct timeval timeout; +timeout.tv_sec = 5; /* wait for 5 seconds */ +timeout.tv_usec = 0; + +s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL, &timeout); +.Ed +.Pp +connects to the DHCP server on the localhost via port 7911 (the standard +OMAPI port). No authentication is used for the connection. It allows +5 seconds for the connect to complete. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_disconnect +closes the open connection specified by the first parameter, \fBcxn\fR. Note +that this call will free the connection object and \fBcxn\fR will be set to + nul. If the second parameter,\fBforce\fR, is nonzero, the connection will be +closed immediately. Otherwise the receiving end will be shut down but any +unsent data will be sent before actually closing the socket. Note that +disconnecting only destroys the connection object, any other objects previously +created will still exist. +.Pp +For example: +.Bd -literal -offset indent +s = dhcpctl_disconnect(&cxn, 1); +.Ed +.Pp +will close the connection immediately. This funcion should be considered +\fBEXPERIMENTAL\fR. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_wait_for_completion +flushes a pending message to the server and waits for the response. The result +of the request as processed on the server is returned via the second +parameter. +.Bd -literal -offset indent +s = dhcpctl_wait_for_completion(cxn, &wv); +if (s != ISC_R_SUCCESS) + local_failure(s); +else if (wv != ISC_R_SUCCESS) + server_failure(wc); +.Ed +.Pp +The call to +.Fn dhcpctl_wait_for_completion +won't return until the remote message processing completes or the connection +to the server is lost. +.\" +.\" +.\" +.Pp + +.Fn dhcpctl_timed_wait_for_completion +flushes a pending message to the server and waits for the response. How long +the function waits for a response is dictated by the value of the third +parameter, \fBtimeout\fR. If the value is null, it will wait indefinitely or +until the connection is lost. Otherwise it will wait for the amount of time +specified by \fBtimeout\fR (tv_sec:tv_usec). Values of zero for both fields +are valid but not recommended. The result of the request as processed on the +server is returned via the second parameter. An example is shown below: +.Bd -literal -offset indent + +struct timeval timeout; +timeout.tv_sec = 5; /* wait for 5 seconds */ +timeout.tv_usec = 0; + +s = dhcpctl_wait_for_completion(cxn, &wv, &timeout); +if (s != ISC_R_SUCCESS) { + local_failure(s); +} else if (wv != ISC_R_SUCCESS) { + server_failure(wc); +} +.Ed +.Pp +If the function times out, the status returned will be ISC_R_TIMEDOUT. Please +note that even though the function is no longer waiting for a response, the +server does not abandon the request and may still respond by writing the +response to the socket. A subsequent call to either this function or +\fBdhcpctl_wait_for_completion()\fR will see that data and read it. Depending +on the application logic flow this may or may not be desired. Currently though +only mechanism for "flushing" this data is to close the connection by calling +\fBdisconnet()\fR, and then reconnecting via \fBconnect()\fR. Please note +this function should be considered \fBEXPERIMENTAL\fR. + +.\" +.\" +.\" +.Pp +.Fn dhcpctl_get_value +extracts a value of an attribute from the handle. The value can be of any +length and is treated as a sequence of bytes. The handle must have been +created first with +.Fn dhcpctl_new_object +and opened with +.Fn dhcpctl_open_object . +The value is returned via the parameter named +.Dq value . +The last parameter is the name of attribute to retrieve. +.Bd -literal -offset indent +dhcpctl_data_string value = NULL; +dhcpctl_handle lease; +time_t thetime; + +s = dhcpctl_get_value (&value, lease, "ends"); +assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime)); +memcpy(&thetime, value->value, value->len); +.Ed +.\" +.\" +.\" +.Pp +.Fn dhcpctl_get_boolean +extracts a boolean valued attribute from the object handle. +.\" +.\" +.\" +.Pp +The +.Fn dhcpctl_set_value , +.Fn dhcpctl_set_string_value , +.Fn dhcpctl_set_boolean_value , +and +.Fn dhcpctl_set_int_value +functions all set a value on the object handle. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_object_update +function queues a request for +all the changes made to the object handle be sent to the remote +for processing. The changes made to the attributes on the handle will be +applied to remote object if permitted. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_object_refresh +queues up a request for a fresh copy of all the attribute values to be sent +from the remote to +refresh the values in the local object handle. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_object_remove +queues a request for the removal on the server of the object referenced by the +handle. +.\" +.\" +.\" +.Pp +The +.Fn dhcpctl_set_callback +function sets up a user-defined function to be called when an event completes +on the given object handle. This is needed for asynchronous handling of +events, versus the synchronous handling given by +.Fn dhcpctl_wait_for_completion . +When the function is called the first parameter is the object the event +arrived for, the second is the status of the message that was processed, the +third is the same value as the second parameter given to +.Fn dhcpctl_set_callback . +.\" +.\" +.\" +.Pp +The +.Fn dhcpctl_new_authenticator +creates a new authenticator object to be used for signing the messages +that cross over the network. The +.Dq name , +.Dq algorithm , +and +.Dq secret +values must all match what the server uses and are defined in its +configuration file. The created object is returned through the first parameter +and must be used as the 4th parameter to +.Fn dhcpctl_connect . +Note that the 'secret' value must not be base64 encoded, which is different +from how the value appears in the dhcpd.conf file. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_new_object +creates a local handle for an object on the server. The +.Dq object_type +parameter is the ascii name of the type of object being accessed. e.g. +.Qq lease . +This function only sets up local data structures, it does not queue any +messages +to be sent to the remote side, +.Fn dhcpctl_open_object +does that. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_open_object +builds and queues the request to the remote side. This function is used with +handle created via +.Fn dhcpctl_new_object . +The flags argument is a bit mask with the following values available for +setting: +.Bl -tag -offset indent -width 20 +.It DHCPCTL_CREATE +if the object does not exist then the remote will create it +.It DHCPCTL_UPDATE +update the object on the remote side using the +attributes already set in the handle. +.It DHCPCTL_EXCL +return and error if the object exists and DHCPCTL_CREATE +was also specified +.El +.\" +.\" +.\" +.Pp +The +.Fn omapi_data_string_new +function allocates a new +.Ft dhcpctl_data_string +object. The data string will be large enough to hold +.Dq length +bytes of data. The +.Dq file +and +.Dq lineno +arguments are the source file location the call is made from, typically by +using the +.Dv __FILE__ +and +.Dv __LINE__ +macros or the +.Dv MDL +macro defined in +. +.\" +.\" +.\" +.Pp +.Fn dhcpctl_data_string_dereference +deallocates a data string created by +.Fn omapi_data_string_new . +The memory for the object won't be freed until the last reference is +released. +.Sh EXAMPLES +.Pp +The following program will connect to the DHCP server running on the local +host and will get the details of the existing lease for IP address +10.0.0.101. It will then print out the time the lease is due to expire. Note +that most error checking has been omitted for brevity. +.Bd -literal -offset indent +#include +#include +#include +#include +#include + +#include +#include +#include + +#include "omapip/result.h" +#include "dhcpctl.h" + +int main (int argc, char **argv) { + dhcpctl_data_string ipaddrstring = NULL; + dhcpctl_data_string value = NULL; + dhcpctl_handle connection = NULL; + dhcpctl_handle lease = NULL; + isc_result_t waitstatus; + struct in_addr convaddr; + time_t thetime; + + dhcpctl_initialize (); + + dhcpctl_connect (&connection, "127.0.0.1", + 7911, 0); + + dhcpctl_new_object (&lease, connection, + "lease"); + + memset (&ipaddrstring, 0, sizeof + ipaddrstring); + + inet_pton(AF_INET, "10.0.0.101", + &convaddr); + + omapi_data_string_new (&ipaddrstring, + 4, MDL); + memcpy(ipaddrstring->value, &convaddr.s_addr, 4); + + dhcpctl_set_value (lease, ipaddrstring, + "ip-address"); + + dhcpctl_open_object (lease, connection, 0); + + dhcpctl_wait_for_completion (lease, + &waitstatus); + if (waitstatus != ISC_R_SUCCESS) { + /* server not authoritative */ + exit (0); + } + + dhcpctl_data_string_dereference(&ipaddrstring, + MDL); + + dhcpctl_get_value (&value, lease, "ends"); + + memcpy(&thetime, value->value, value->len); + + dhcpctl_data_string_dereference(&value, MDL); + + fprintf (stdout, "ending time is %s", + ctime(&thetime)); +} +.Ed +.Sh SEE ALSO +omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5). +.Sh AUTHOR +.Em dhcpctl +is maintained by ISC. To learn more about Internet Systems Consortium, +see +.B https://www.isc.org diff --git a/static/netbsd/man3/directory.3 b/static/netbsd/man3/directory.3 new file mode 100644 index 00000000..ad0ac070 --- /dev/null +++ b/static/netbsd/man3/directory.3 @@ -0,0 +1,462 @@ +.\" $NetBSD: directory.3,v 1.45 2026/01/22 10:34:30 uwe Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd January 21, 2026 +.Dt DIRECTORY 3 +.Os +. +.Sh NAME +.Nm fdopendir , +.Nm opendir , +.Nm readdir , +.Nm readdir_r , +.Nm telldir , +.Nm seekdir , +.Nm rewinddir , +.Nm closedir , +.Nm dirfd +.Nd directory operations +. +.Sh LIBRARY +.Lb libc +. +.Sh SYNOPSIS +. +.In dirent.h +. +.Ft DIR * +.Fn opendir "const char *filename" +. +.Ft DIR * +.Fn fdopendir "int fd" +. +.Ft struct dirent * +.Fn readdir "DIR *dirp" +. +.Ft int +.Fo readdir_r +.Fa "DIR * restrict dirp" +.Fa "struct dirent * restrict entry" +.Fa "struct dirent ** restrict result" +.Fc +. +.Ft long +.Fn telldir "DIR *dirp" +. +.Ft void +.Fn seekdir "DIR *dirp" "long loc" +. +.Ft void +.Fn rewinddir "DIR *dirp" +. +.Ft int +.Fn closedir "DIR *dirp" +. +.Ft int +.Fn dirfd "DIR *dirp" +. +.Sh DESCRIPTION +The type +.Vt DIR +represents a directory stream; +an ordered sequence of all directory entries in a particular directory. +The purpose of the +.Vt DIR +structure is similar to that of the +.Vt FILE +structure maintained by the +.Xr stdio 3 +library functions. +. +.Sh FUNCTIONS +The following standard directory operations are defined. +.Bl -tag -width Fn +. +.It Fn opendir "filename" +The +.Fn opendir +function opens the directory named by +.Fa filename +and associates a directory stream with it. +The directory stream is positioned at the first entry. +Upon successful completion, a pointer to +.Vt DIR +type is returned. +Otherwise, +.Fn opendir +returns +.Dv NULL . +. +.It Fn fdopendir "fd" +The +.Fn fdopendir +function associates a directory stream with the directory file descriptor +.Fa fd . +The file offset associated with +.Fa fd +at the time of the call determines which entries are returned. +.Pp +Upon failure, +.Fn fdopendir +returns +.Dv NULL . +Otherwise the file descriptor is under the control of the system, +and if any attempt is made to close the file descriptor, +or to modify the state of the associated description, +other than by means of +.Fn closedir , +.Fn readdir , +.Fn readdir_r , +.Fn rewinddir , +the behavior is undefined. +The file descriptor can be closed by calling +.Fn closedir . +. +.It Fn readdir "dirp" +The +.Fn readdir +function returns a pointer to the directory entry at the current position +in the directory stream specified by +.Fa dirp , +and positions the directory stream at the next entry. +It returns +.Dv NULL +upon reaching the end of the directory or detecting an invalid +.Fn seekdir +operation. +The returned structure is described in +.Xr dirent 3 . +.Pp +The returned pointer to the +.Vt dirent +structure points to data which may be overwritten by another call to +.Fn readdir +on the same directory stream. +This data is not however overwritten by another call to +.Fn readdir +on a different directory stream. +. +.It Fn readdir_r "dirp" "entry" "result" +The +.Fn readdir_r +function +provides the same functionality as +.Fn readdir , +but the caller must provide a directory +.Fa entry +buffer to store the results in. +If the read succeeds, +.Fa result +is pointed at the +.Fa entry ; +upon reaching the end of the directory +.Fa result +is set to +.Dv NULL . +The +.Fn readdir_r +function +returns 0 on success or an error number to indicate failure. +.Pp +Like +.Fn readdir , +the +.Fn readdir_r +function may buffer several directory entries per actual read operation. +Both functions mark for update the +.Fa st_atime +field +.Po +see +.Xr stat 2 +.Pc +of the directory each time the directory is actually read. +. +.It Fn telldir "dirp" +The +.Fn telldir +function returns the current location associated +with the directory stream specified by +.Fa dirp . +.Pp +If the most recent operation on the particular directory stream was a +.Fn seekdir , +the directory position returned from +.Fn telldir +is the same as +.Fa loc +supplied as an argument to the +.Fn seekdir +call. +. +.It Fn seekdir "dirp" "loc" +The +.Fn seekdir +function sets the position of the next +.Fn readdir +operation on the directory stream specified by +.Fa dirp . +The value of +.Fa loc +should come from a previous call to +.Fn telldir +using the same directory stream. +.Pp +The new position reverts to the one associated +with the directory stream when the +.Fn telldir +operation was performed. +Values returned by +.Fn telldir +are good only for the lifetime of the +.Vt DIR +pointer, +.Fa dirp , +from which they are derived. +If the directory is closed and then reopened, the +.Fn telldir +value cannot be re-used. +If the directory is altered from the same or another process, the +.Fn telldir +value becomes invalid. +.Pp +.Fn seekdir +returns no value. +There is no supported way to detect if the operation succeeded. +. +.It Fn rewinddir "dirp" +The +.Fn rewinddir +function resets the position of the named directory +stream to the beginning of the directory. +It also causes the directory stream to refer to the +current state of the corresponding directory, as if a call to +.Fn opendir +was made. +It is not specified whether this refers to the +.Dq corresponding directory +by name or by underlying object. +.Po +These can differ if +.Xr rename 2 +has been used +.Pc . +.\" Note: currently the underlying fd is reopened if and only if +.\" __DTF_READALL is in effect, which is true for union mounts and +.\" nfs; documenting that exactly seems inadvisable since it might +.\" change. -- dholland 20210217 +.Pp +If +.Fa dirp +does not refer to a valid directory stream, the behavior is undefined. +. +.It Fn closedir "dirp" +The +.Fn closedir +function closes the directory stream +and frees the structure associated with the +.Fa dirp +pointer, +returning 0 on success and \-1 on failure. +. +.It Fn dirfd "dirp" +The +.Fn dirfd +function returns the integer file descriptor +associated with the directory stream specified by +.Fa dirp . +Upon failure, +.Fn dirfd +returns \-1. +The returned file descriptor should not be closed by +.Xr close 2 , +it will be released when +.Fa dirp +is closed with +.Fn closedir . +.Pp +The rationale of +.Fn dirfd +is to provide a mechanism by which a file descriptor +can be obtained for the use of the +.Xr fchdir 2 +function. +.El +.Sh EXAMPLES +Sample code which searches a directory for entry +.Dq name +is: +.Bd -literal -offset indent +len = strlen(name); +dirp = opendir("."); +if (dirp != NULL) { + while ((dp = readdir(dirp)) != NULL) + if (dp->d_namlen == len && + !strcmp(dp->d_name, name)) { + (void)closedir(dirp); + return (FOUND); + } + (void)closedir(dirp); +} +return (NOT_FOUND); +.Ed +. +.Sh COMPATIBILITY +The described directory operations have traditionally been problematic +in terms of portability. +A good example is the semantics of +.Sq Li \&. +(dot) and +.Sq Li \&.. +(dot-dot). +Based on historical implementations, +the rules about file descriptors apply to directory streams as well. +The +.St -p1003.1-2008 +standard no longer mandates that directory streams be +implemented by using file descriptors. +.Pp +The following additional remarks can be noted from the +.St -p1003.1-2008 +standard. +.Bl -bullet +. +.It +If the type +.Vt DIR +is implemented using a file descriptor, +like in +.Nx , +applications should be able to open only +.Dv OPEN_MAX +files and directories. +Otherwise the limit is left as unspecified. +. +.It +When a file descriptor is used to implement the directory stream, the +.Fn closedir +function behaves as if the +.Dv FD_CLOEXEC +flag had been set for the file descriptor. +In other words, it is mandatory that +.Fn closedir +deallocates the file descriptor. +. +.It +If directory streams are not implemented by using file descriptors, +functions such as +.Fn dirfd +may fail with +.Er ENOTSUP . +. +.It +If a file is removed from or added to the directory +after the most recent call to +.Fn opendir +or +.Fn rewinddir , +it is unspecified whether a subsequent call to +.Fn readdir +returns an entry for that file. +. +.It +When using the function +.Fn seekdir , +note that if the value of +.Fa loc +was not obtained from an earlier call to +.Fn telldir , +or if a call to +.Fn rewinddir +occurred between the calls to +.Fn telldir +and +.Fn seekdir , +the results of any subsequent call to +.Fn readdir +are unspecified, possibly resulting in undefined behavior. +. +.It +After a call to +.Xr fork 2 , +either the parent or child (but not both) can continue processing the +directory stream using +.Fn readdir , +.Fn rewinddir , +or +.Fn seekdir . +However, if both the parent and child processes use these functions, +the result is undefined. +.El +. +.Sh ERRORS +.\" +.\" XXX: The errors should be enumerated. +.\" +All described functions may set +.Vt errno +to indicate the error. +. +.Sh SEE ALSO +.Xr close 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr read 2 , +.Xr dirent 3 +. +.Sh STANDARDS +The +.Fn opendir , +.Fn readdir , +.Fn rewinddir +and +.Fn closedir +functions conform to +.St -p1003.1-90 . +The other functions conform to +.St -p1003.1-2008 . +. +.Sh HISTORY +The +.Fn opendir , +.Fn readdir , +.Fn telldir , +.Fn seekdir , +.Fn rewinddir , +.Fn closedir , +and +.Fn dirfd +functions appeared in +.Bx 4.2 . +The +.Fn fdopendir +function appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/dirname.3 b/static/netbsd/man3/dirname.3 new file mode 100644 index 00000000..21663183 --- /dev/null +++ b/static/netbsd/man3/dirname.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: dirname.3,v 1.14 2008/05/10 22:39:40 christos Exp $ +.\" +.\" Copyright (c) 1997, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein and Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 10, 2008 +.Dt DIRNAME 3 +.Os +.Sh NAME +.Nm dirname +.Nd report the parent directory name of a file pathname +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In libgen.h +.Ft char * +.Fn dirname "char *path" +.Sh DESCRIPTION +The +.Fn dirname +function takes a pointer to a character string that contains a pathname, +.Ar path , +and returns a pointer to a string that is a pathname of the parent directory of +.Ar path . +Trailing +.Sq / +characters in +.Ar path +are not counted as part of the path. +.Pp +If +.Ar path +does not contain a +.Sq / , +then +.Fn dirname +returns a pointer to the string +.Dq \&. . +.Pp +If +.Ar path +is a null pointer or points to an empty string, +.Fn dirname +returns a pointer to the string +.Dq \&. . +.Sh RETURN VALUES +The +.Fn dirname +function returns a pointer to a string that is the parent directory of +.Ar path . +.Sh SEE ALSO +.Xr dirname 1 , +.Xr basename 3 +.Sh STANDARDS +.Bl -bullet -compact +.It +.St -xpg4.2 +.It +.St -p1003.1-2001 +.El +.Sh BUGS +If the length of the result is longer than +.Dv PATH_MAX +bytes +.Pq including the terminating nul , +the result will be truncated. +.Pp +The +.Fn dirname +function returns a pointer to static storage that may be overwritten +by subsequent calls to +.Fn dirname . +This is not strictly a bug; it is explicitly allowed by +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/disklabel_dkcksum.3 b/static/netbsd/man3/disklabel_dkcksum.3 new file mode 100644 index 00000000..de9c4816 --- /dev/null +++ b/static/netbsd/man3/disklabel_dkcksum.3 @@ -0,0 +1,56 @@ +.\" $NetBSD: disklabel_dkcksum.3,v 1.8 2010/05/04 06:41:27 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roland C. Dowdeswell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt DISKLABEL_DKCKSUM 3 +.Os +.Sh NAME +.Nm disklabel_dkcksum +.Nd compute the checksum for a disklabel +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft uint16_t +.Fo disklabel_dkcksum +.Fa "struct disklabel *lp" +.Fc +.Sh DESCRIPTION +.Fn disklabel_dkcksum +computes the checksum for the disklabel passed in as +.Fa lp . +.Sh RETURN VALUES +The +.Fn disklabel_dkcksum +returns the computed checksum. +.Sh HISTORY +The +.Fn disklabel_dkcksum +function call appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/disklabel_scan.3 b/static/netbsd/man3/disklabel_scan.3 new file mode 100644 index 00000000..53c08885 --- /dev/null +++ b/static/netbsd/man3/disklabel_scan.3 @@ -0,0 +1,59 @@ +.\" $NetBSD: disklabel_scan.3,v 1.6 2010/05/04 06:41:27 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roland C. Dowdeswell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt DISKLABEL_SCAN 3 +.Os +.Sh NAME +.Nm disklabel_scan +.Nd scan a buffer for a valid disklabel +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn disklabel_scan "struct disklabel *lp" "char *buf" "size_t buflen" +.Sh DESCRIPTION +.Fn disklabel_scan +scans the memory region specified by +.Fa buf +and +.Fa buflen +for a valid disklabel. +If such a label is found, it is copied into +.Fa lp . +.Sh RETURN VALUES +The +.Fn disklabel_scan +function returns 0 if a valid disklabel was found and 1 if not. +.Sh HISTORY +The +.Fn disklabel_scan +function call appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/div.3 b/static/netbsd/man3/div.3 new file mode 100644 index 00000000..6b0229c3 --- /dev/null +++ b/static/netbsd/man3/div.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: div.3,v 1.16 2022/05/24 20:50:17 andvar Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)div.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 13, 2011 +.Dt DIV 3 +.Os +.Sh NAME +.Nm div , +.Nm ldiv , +.Nm lldiv , +.Nm imaxdiv +.Nd quotient and remainder from division +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft div_t +.Fn div "int num" "int denom" +.Ft ldiv_t +.Fn ldiv "long int num" "long int denom" +.Ft lldiv_t +.Fn lldiv "long long int num" "long long int denom" +.In inttypes.h +.Ft imaxdiv_t +.Fn imaxdiv "intmax_t num" "intmax_t denom" +.Sh DESCRIPTION +These functions compute the value of +.Fa num / denom +and return the quotient and remainder in a specific division structure. +The functions differ only with respect to the type of the return value and +the parameters. +.Pp +The returned structure always contains two members named +.Vt quot +and +.Vt rem , +denoting the quotient and the remainder. +The type of these correspond with the underlying type of the function. +.Sh EXAMPLES +The following example demonstrates the basic usage of the functions. +.Bd -literal -offset indent +div_t d; + +int a = 4321; +int b = 1234; + +d = div(a, b); + +(void)printf("%d %d\en", d.quot, d.rem); +.Ed +.Sh SEE ALSO +.Xr fast_divide32 3 , +.Xr math 3 , +.Xr qdiv 3 +.Sh STANDARDS +All described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/dm.3 b/static/netbsd/man3/dm.3 new file mode 100644 index 00000000..d3ba16b1 --- /dev/null +++ b/static/netbsd/man3/dm.3 @@ -0,0 +1,396 @@ +.\" $NetBSD: dm.3,v 1.7 2022/09/10 12:14:17 rillig Exp $ +.\" +.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Adam Hamsik. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.Dd January 22, 2016 +.Dt DM 3 +.Os +.Sh NAME +.Nm dm +.Nd device-mapper access manipulation library +.Sh LIBRARY +.Lb libdm +.Sh SYNOPSIS +.In dm.h +.Ft void +.Fn libdm_iter_destroy "libdm_iter_t libdm_iter" +.Ft int +.Fn libdm_task_run "libdm_task_t *libdm_task" +.Ft libdm_task_t +.Fn libdm_task_create "const char *command" +.Ft void +.Fn libdm_task_destroy "libdm_task_t libdm_task" +.Ft int +.Fn libdm_task_set_name "const char *name" "libdm_task_t libdm_task" +.Ft char * +.Fn libdm_task_get_name "libdm_task_t libdm_task" +.Ft int +.Fn libdm_task_set_uuid "const char *uuid" "libdm_task_t libdm_task" +.Ft char * +.Fn libdm_task_get_uuid "libdm_task_t libdm_task" +.Ft char * +.Fn libdm_task_get_command "libdm_task_t libdm_task" +.Ft int32_t +.Fn libdm_task_get_cmd_version "libdm_task_t libdm_task" "uint32_t *ver" "size_t size" +.Ft int +.Fn libdm_task_set_minor "uint32_t minor" "libdm_task_t libdm_task" +.Ft uint32_t +.Fn libdm_task_get_minor "libdm_task_t libdm_task" +.Ft int +.Fn libdm_task_set_flags "uint32_t flags" "libdm_task_t libdm_task" +.Ft uint32_t +.Fn libdm_task_get_flags "libdm_task_t libdm_task" +.Ft uint32_t +.Fn libdm_task_get_target_num "libdm_task_t libdm_task" +.Ft int32_t +.Fn libdm_task_get_open_num "libdm_task_t libdm_task" +.Ft uint32_t +.Fn libdm_task_get_event_num "libdm_task_t libdm_task" +.Ft int +.Fn libdm_task_set_cmd "libdm_cmd_t libdm_cmd" "libdm_task_t libdm_task" +.Ft libdm_cmd_t +.Fn libdm_task_get_cmd "libdm_task_t libdm_task" +.Ft libdm_cmd_t +.Fn libdm_cmd_create "void" +.Ft void +.Fn libdm_cmd_destroy "libdm_cmd_t libdm_cmd" +.Ft libdm_iter_t +.Fn libdm_cmd_iter_create "libdm_cmd_t libdm_cmd" +.Ft int +.Fn libdm_cmd_set_table "libdm_table_t libdm_table" "libdm_cmd_t libdm_cmd" +.Ft libdm_table_t +.Fn libdm_cmd_get_table "libdm_iter_t iter" +.Ft libdm_target_t +.Fn libdm_cmd_get_target "libdm_iter_t iter" +.Ft libdm_dev_t +.Fn libdm_cmd_get_dev "libdm_iter_t iter" +.Ft uint64_t +.Fn libdm_cmd_get_deps "libdm_iter_t libdm_iter" +.Ft libdm_table_t +.Fn libdm_table_create "void" +.Ft void +.Fn libdm_table_destroy "libdm_table_t libdm_table" +.Ft int +.Fn libdm_table_set_start "uint64_t start" "libdm_table_t libdm_table" +.Ft uint64_t +.Fn libdm_table_get_start "libdm_table_t libdm_table" +.Ft int +.Fn libdm_table_set_length "uint64_t length" "libdm_table_t libdm_table" +.Ft uint64_t +.Fn libdm_table_get_length "libdm_table_t libdm_table" +.Ft int +.Fn libdm_table_set_target "const char *name" "libdm_table_t libdm_table" +.Ft char * +.Fn libdm_table_get_target "libdm_table_t libdm_table" +.Ft int +.Fn libdm_table_set_params "const char *params" "libdm_table_t libdm_table" +.Ft char * +.Fn libdm_table_get_params "libdm_table_t libdm_table" +.Ft int32_t +.Fn libdm_table_get_status "libdm_table_t libdm_table" +.Ft void +.Fn libdm_target_destroy "libdm_target_t libdm_target" +.Ft char * +.Fn libdm_target_get_name "libdm_target_t libdm_target" +.Ft int32_t +.Fn libdm_target_get_version "libdm_target_t libdm_target" "uint32_t *ver" "size_t size" +.Ft void +.Fn libdm_dev_destroy "libdm_dev_t libdm_dev" +.Ft char * +.Fn libdm_dev_get_name "libdm_dev_t libdm_dev" +.Ft uint32_t +.Fn libdm_dev_get_minor "libdm_dev_t libdm_dev" +.Ft int +.Fn libdm_dev_set_newname "const char *newname" "libdm_cmd_t libdm_cmd" +.Sh DESCRIPTION +Every object in libdm has its own create and destroy routine. +.Bl -bullet -offset indent -compact +.It +libdm_task_t +.It +libdm_cmd_t +.It +libdm_table_t +.El +.Pp +Except +.Vt libdm_dev_t +which is received from kernel as list of physical devices on which +the logical device depends. +.Vt libdm_target_t +which is received from kernel as list of available targets to use. +.Vt libdm_iter_t +which is used as iteration counter for array entries in the task structure. +.Pp +Every object attribute in libdm can be set and gotten by appropriate routines, +therefore there always are set and get routines. +.Ss LIBDM TASK +The +.Fn libdm_task_create +function creates a libdm task dictionary with command string set to +.Fa command . +If +.Fa command +is +.Dv NULL , +libdm_task_t is not created and the function returns +.Dv NULL . +.Pp +.Fn libdm_task_destroy +free all memory allocated to +.Fa libdm_task +by +.Fn libdm_task_create . +.Pp +.Fn libdm_task_run +Sends created +.Fa libdm_task +to kernel and receives new one as reply. +.Pp +List of attributes available in +.Vt libdm_task_t : +.Bl -column -offset indent "DM_IOCTL_TARGET_COUNT" "Number of table entries" "XXX" +.It Sy Attribute Ta Sy Description Ta Sy Mode +.It Li DM_IOCTL_OPEN Ta Device open-count Ta Read-Only +.It Li DM_IOCTL_MINOR Ta Device minor number Ta Read-Write +.It Li DM_IOCTL_NAME Ta Device name Ta Read-Write +.It Li DM_IOCTL_UUID Ta Device uuid Ta Read-Write +.It Li DM_IOCTL_TARGET_COUNT Ta Number of table entries Ta Read-Only +.\".It Li DM_IOCTL_EVENT Ta Not implemented Ta not imp +.It Li DM_IOCTL_FLAGS Ta Device status flags Ta Read-Write +.El +.Pp +.Fn libdm_task_set_name +and +.Fn libdm_task_get_name +Set name of the device for commands which need to have a dm device +identifier. +The device-mapper later uses the device name to look up the device +from the list of all devices. +The get routine will fetch the device name from the task dictionary. +.Pp +.Fn libdm_task_set_uuid +and +.Fn libdm_task_get_uuid +Set uuid of device for commands which need to have a dm device +identifier. +The device-mapper later uses the device uuid to look up the device +from the list of all devices. +The get routine will fetch the device uuid from the task dictionary. +.Pp +.Fn libdm_task_set_minor +and +.Fn libdm_task_get_minor +Set minor device number of device for commands which need to have +a dm device identifier. +The device-mapper later uses the device minor number to look up +the device from the list of all devices. +The get routine will fetch the device minor number from the task +dictionary. +.Pp +.Fn libdm_task_set_flags +and +.Fn libdm_task_get_flags +Set/fetch device status flags from the task dictionary. +.Pp +.Fn libdm_task_get_open_num +Fetch number of opened devices from the kernel and return them as count. +.Pp +.Fn libdm_task_get_target_num +Fetch number of opened devices from the kernel and return them as count. +.Pp +.Fn libdm_task_get_cmd_version +Get the version of the dm driver in the kernel as array +.Fa uint32_t *ver +of size +.Fa size . +.Fn libdm_task_set_cmd +and +.Fn libdm_task_get_cmd +Add and fetch cmd structure from +.Vt libdm_task_t . +.Vt libdm_cmd_t +is the container used to carry information specific for the particular +command. +cmd is usually set before libdm_task_run is used and is taken from +the task structure after the task run was called. +.Ss LIBDM TASK CMD +The +.Fn libdm_cmd_create +function will allocate a cmd structure which can later be put in +to the task. +.Pp +.Fn libdm_cmd_destroy +will deallocate a previously allocated cmd structure. +.Pp +.Fn libdm_cmd_set_table +Will load and fetch the device mapping table from the dm device. +The table is usually loaded to the device during initial device +creation or device resizing. +.Pp +Because libdm_cmd is an array of structures, all _get routines need an +iterator to work. +For every entry we can have more than one. +.Fn libdm_cmd_get_table +When the user creates a task with the "status" command, the kernel +sends cmd with a table in it. +.Pp +.Fn libdm_cmd_get_target +Get mapping target description from cmd. +Target contains target_name and target_version. +.Pp +.Fn libdm_cmd_get_dev +When user creates a task with the "info" command, the kernel sends +cmd with information about dm device to user. +.Pp +.Fn libdm_cmd_get_deps +When user creates a task with the "deps" command, the kernel sends +cmd with an array of physical devices attached to the dm device. +.Pp +Usually the device has more than one table entry in the device command. +Therefore cmd iterators are needed for +.Vt libdm_cmd_t ; +they can be created by the +.Fn libdm_cmd_iter_create +function. +.Ss LIBDM CMD TABLE +A device table describes the logical mapping between the dm device and +physical devices. +Every table has the logical block start, the table length (in disk +blocks), the target used by table, the physical device, and the +offset on it. +The physical device and the offset on it are parameters which are +target specific and are passed down to the target as param string. +.Pp +Example device table entry +.Dl 0 1024 linear /dev/wd1a 384 +.Bl -column -offset indent "DM_TABLE_LENGTH" "Number of table entries" +.It Sy Attribute Ta Sy Description +.It Li DM_TABLE_TYPE Ta Used device mapper target +.It Li DM_TABLE_START Ta Device Logical start block +.It Li DM_TABLE_STAT Ta Is 1 if this is current active table +.It Li DM_TABLE_LENGTH Ta Logical length described by table +.It Li DM_TABLE_PARAMS Ta Params passed down to target +.El +.Pp +.Fn libdm_table_set_start +and +.Fn libdm_table_get_start +Set start table from +.Fa start +value to +.Fa libdm_table +argument. +Get routine will get the table start from kernel as +.Vt libdm_table . +.Pp +.Fn libdm_table_set_length +and +.Fn libdm_table_get_length +Set table length from +.Fa length +value to +.Fa libdm_table +argument. +Get routine will get the table length from kernel as +.Vt libdm_table . +.Pp +.Fn libdm_table_set_target +and +.Fn libdm_table_get_target +Set target name from +.Fa target +value to +.Fa libdm_table +argument. +The target must be actually present in the kernel, otherwise +.Fn libdm_task_run +will fail. +Get routine will get the table entry target from kernel as +.Vt libdm_table . +.Pp +.Fn libdm_table_set_params +and +.Fn libdm_table_get_params +Set table target parameter string from +.Fa params +argument to +.Fa libdm_table . +This is later in the kernel passed to the target init routine. +Get routine will get the table parameter string from kernel as +.Vt libdm_table . +.Pp +.Fn libdm_table_get_status +Get table status which can be Active/Inactive. +This tells if this table is actually used or not. +.Ss LIBDM_TARGET +.Fn libdm_target_destroy +Destroy target received from +.Vt libdm_cmd +with libdm_cmd_iter iterator. +.Pp +.Fn libdm_target_get_name +returns pointer to a string with available target name. +.Pp +.Fn libdm_target_get_version +Sets argument +.Fa ver[3] +to a in-kernel loaded target version. +.Ss LIBDM_DEV +.Fn libdm_dev_destroy +Destroy device received from +.Vt libdm_cmd +with libdm_cmd_iter iterator. +.Pp +.Fn libdm_dev_get_name +Return pointer to a string with underlying device name from +.Vt libdm_dev_t +.Pp +.Fn libdm_dev_get_minor +Return underlying device minor number. +.Ss MISC +.Fn libdm_dev_set_newname +This routine will set new dm device name attribute to +.Fa newname . +User must then called libdm_task_run on this task to +change the device name. +.Sh RETURN VALUES +Upon success, all described functions return zero or +.Pf non- Dv NULL +pointer. +Otherwise, an error number will be returned to indicate the error. +.Sh SEE ALSO +.Xr dm 4 +.Sh HISTORY +The +.Nm +was written and contributed to +.Nx +by +.An Adam Hamsik +and first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/dngettext.3 b/static/netbsd/man3/dngettext.3 new file mode 100644 index 00000000..5fcf629c --- /dev/null +++ b/static/netbsd/man3/dngettext.3 @@ -0,0 +1 @@ +.so man3/ngettext.3 diff --git a/static/netbsd/man3/dns.h.3 b/static/netbsd/man3/dns.h.3 new file mode 100644 index 00000000..be5dbb30 --- /dev/null +++ b/static/netbsd/man3/dns.h.3 @@ -0,0 +1,961 @@ +.TH "event2/dns.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/dns.h \- Welcome, gentle reader\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBDNS_ERR_CANCEL\fP 69" +.br +.RI "\fIThe request was canceled via a call to evdns_cancel_request\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_FORMAT\fP 1" +.br +.RI "\fIThe name server was unable to interpret the query\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_NODATA\fP 70" +.br +.RI "\fIThere were no answers and no error condition in the DNS packet\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_NONE\fP 0" +.br +.RI "\fIError codes 0-5 are as described in RFC 1035\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_NOTEXIST\fP 3" +.br +.RI "\fIThe domain name does not exist\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_NOTIMPL\fP 4" +.br +.RI "\fIThe name server does not support the requested kind of query\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_REFUSED\fP 5" +.br +.RI "\fIThe name server refuses to reform the specified operation for policy reasons\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_SERVERFAILED\fP 2" +.br +.RI "\fIThe name server was unable to process this query due to a problem with the name server\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_SHUTDOWN\fP 68" +.br +.RI "\fIThe request was canceled because the DNS subsystem was shut down\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_TIMEOUT\fP 67" +.br +.RI "\fICommunication with the server timed out\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_TRUNCATED\fP 65" +.br +.RI "\fIThe reply was truncated or ill-formatted\&. \fP" +.ti -1c +.RI "#define \fBDNS_ERR_UNKNOWN\fP 66" +.br +.RI "\fIAn unknown error occurred\&. \fP" +.ti -1c +.RI "#define \fBDNS_IPv4_A\fP 1" +.br +.ti -1c +.RI "#define \fBDNS_IPv6_AAAA\fP 3" +.br +.ti -1c +.RI "#define \fBDNS_NO_SEARCH\fP DNS_QUERY_NO_SEARCH" +.br +.ti -1c +.RI "#define \fBDNS_OPTION_HOSTSFILE\fP 8" +.br +.ti -1c +.RI "#define \fBDNS_OPTION_MISC\fP 4" +.br +.ti -1c +.RI "#define \fBDNS_OPTION_NAMESERVERS\fP 2" +.br +.ti -1c +.RI "#define \fBDNS_OPTION_SEARCH\fP 1" +.br +.ti -1c +.RI "#define \fBDNS_OPTIONS_ALL\fP 15" +.br +.ti -1c +.RI "#define \fBDNS_PTR\fP 2" +.br +.ti -1c +.RI "#define \fBDNS_QUERY_NO_SEARCH\fP 1" +.br +.ti -1c +.RI "#define \fBEVDNS_ADDITIONAL_SECTION\fP 2" +.br +.ti -1c +.RI "#define \fBEVDNS_ANSWER_SECTION\fP 0" +.br +.ti -1c +.RI "#define \fBEVDNS_AUTHORITY_SECTION\fP 1" +.br +.ti -1c +.RI "#define \fBEVDNS_BASE_DISABLE_WHEN_INACTIVE\fP 0x8000" +.br +.RI "\fIFlag for evdns_base_new: Do not prevent the libevent event loop from exiting when we have no active dns requests\&. \fP" +.ti -1c +.RI "#define \fBEVDNS_BASE_INITIALIZE_NAMESERVERS\fP 1" +.br +.RI "\fIFlag for evdns_base_new: process resolv\&.conf\&. \fP" +.ti -1c +.RI "#define \fBEVDNS_CLASS_INET\fP 1" +.br +.ti -1c +.RI "#define \fBEVDNS_FLAGS_AA\fP 0x400" +.br +.ti -1c +.RI "#define \fBEVDNS_FLAGS_RD\fP 0x080" +.br +.ti -1c +.RI "#define \fBEVDNS_QTYPE_ALL\fP 255" +.br +.ti -1c +.RI "#define \fBEVDNS_QTYPE_AXFR\fP 252" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_A\fP 1" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_AAAA\fP 28" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_CNAME\fP 5" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_MX\fP 15" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_NS\fP 2" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_PTR\fP 12" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_SOA\fP 6" +.br +.ti -1c +.RI "#define \fBEVDNS_TYPE_TXT\fP 16" +.br +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void(* \fBevdns_callback_type\fP) (int result, char type, int count, int ttl, void *addresses, void *arg)" +.br +.RI "\fIThe callback that contains the results from a lookup\&. \fP" +.ti -1c +.RI "typedef void(* \fBevdns_debug_log_fn_type\fP) (int is_warning, const char *msg)" +.br +.RI "\fIA callback that is invoked when a log message is generated\&. \fP" +.ti -1c +.RI "typedef void(* \fBevdns_getaddrinfo_cb\fP) (int result, struct \fBevutil_addrinfo\fP *res, void *arg)" +.br +.RI "\fICallback for evdns_getaddrinfo\&. \fP" +.ti -1c +.RI "typedef void(* \fBevdns_request_callback_fn_type\fP) (struct evdns_server_request *, void *)" +.br +.RI "\fIA callback to implement a DNS server\&. \fP" +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_server_port * \fBevdns_add_server_port_with_base\fP (struct \fBevent_base\fP *base, \fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void *user_data)" +.br +.RI "\fICreate a new DNS server port\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_clear_host_addresses\fP (struct evdns_base *base)" +.br +.RI "\fIRemove all hosts entries that have been loaded into the \fBevent_base\fP via evdns_base_load_hosts or via event_base_resolv_conf_parse\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_clear_nameservers_and_suspend\fP (struct evdns_base *base)" +.br +.RI "\fIRemove all configured nameservers, and suspend all pending resolves\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_count_nameservers\fP (struct evdns_base *base)" +.br +.RI "\fIGet the number of configured nameservers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_free\fP (struct evdns_base *base, int fail_requests)" +.br +.RI "\fIShut down the asynchronous DNS resolver and terminate all active requests\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_get_nameserver_addr\fP (struct evdns_base *base, int idx, struct sockaddr *sa, ev_socklen_t len)" +.br +.RI "\fIRetrieve the address of the 'idx'th configured nameserver\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_load_hosts\fP (struct evdns_base *base, const char *hosts_fname)" +.br +.RI "\fILoad an /etc/hosts-style file from 'hosts_fname' into 'base'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_add\fP (struct evdns_base *base, unsigned long int address)" +.br +.RI "\fIAdd a nameserver\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_ip_add\fP (struct evdns_base *base, const char *ip_as_string)" +.br +.RI "\fIAdd a nameserver by string address\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_sockaddr_add\fP (struct evdns_base *base, const struct sockaddr *sa, ev_socklen_t len, unsigned flags)" +.br +.RI "\fIAdd a nameserver by sockaddr\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_base * \fBevdns_base_new\fP (struct \fBevent_base\fP *\fBevent_base\fP, int initialize_nameservers)" +.br +.RI "\fIInitialize the asynchronous DNS library\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_resolv_conf_parse\fP (struct evdns_base *base, int flags, const char *const filename)" +.br +.RI "\fIParse a resolv\&.conf file\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_ipv4\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup an A record for a given name\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_ipv6\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup an AAAA record for a given name\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_reverse\fP (struct evdns_base *base, const struct in_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup a PTR record for a given IP address\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_reverse_ipv6\fP (struct evdns_base *base, const struct in6_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup a PTR record for a given IPv6 address\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_resume\fP (struct evdns_base *base)" +.br +.RI "\fIResume normal operation and continue any suspended resolve requests\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_add\fP (struct evdns_base *base, const char *domain)" +.br +.RI "\fIAdd a domain to the list of search domains\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_clear\fP (struct evdns_base *base)" +.br +.RI "\fIObtain nameserver information using the Windows API\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_ndots_set\fP (struct evdns_base *base, const int ndots)" +.br +.RI "\fISet the 'ndots' parameter for searches\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_set_option\fP (struct evdns_base *base, const char *option, const char *val)" +.br +.RI "\fISet the value of a configuration option\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_cancel_request\fP (struct evdns_base *base, struct evdns_request *req)" +.br +.RI "\fICancels a pending DNS resolution request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_close_server_port\fP (struct evdns_server_port *port)" +.br +.RI "\fIClose down a DNS server port, and free associated structures\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevdns_err_to_string\fP (int err)" +.br +.RI "\fIConvert a DNS error code to a string\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evdns_getaddrinfo_request * \fBevdns_getaddrinfo\fP (struct evdns_base *dns_base, const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, \fBevdns_getaddrinfo_cb\fP cb, void *arg)" +.br +.RI "\fIMake a non-blocking getaddrinfo request using the dns_base in 'dns_base'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_getaddrinfo_cancel\fP (struct evdns_getaddrinfo_request *req)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_a_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_aaaa_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_cname_reply\fP (struct evdns_server_request *req, const char *name, const char *cname, int ttl)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_ptr_reply\fP (struct evdns_server_request *req, struct in_addr *in, const char *inaddr_name, const char *hostname, int ttl)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_reply\fP (struct evdns_server_request *req, int section, const char *name, int type, int dns_class, int ttl, int datalen, int is_name, const char *data)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_drop\fP (struct evdns_server_request *req)" +.br +.RI "\fIFree a DNS request without sending back a reply\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_get_requesting_addr\fP (struct evdns_server_request *req, struct sockaddr *sa, int addr_len)" +.br +.RI "\fIGet the address that made a DNS request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_respond\fP (struct evdns_server_request *req, int err)" +.br +.RI "\fISend back a response to a DNS request, and free the request structure\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_server_request_set_flags\fP (struct evdns_server_request *req, int flags)" +.br +.RI "\fISets some flags in a reply we're building\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_log_fn\fP (\fBevdns_debug_log_fn_type\fP fn)" +.br +.RI "\fISet the callback function to handle DNS log messages\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_random_bytes_fn\fP (void(*fn)(char *, size_t))" +.br +.RI "\fISet a callback used to generate random bytes\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_transaction_id_fn\fP (ev_uint16_t(*fn)(void))" +.br +.RI "\fISet a callback that will be invoked to generate transaction IDs\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Welcome, gentle reader\&. + +Async DNS lookups are really a whole lot harder than they should be, mostly stemming from the fact that the libc resolver has never been very good at them\&. Before you use this library you should see if libc can do the job for you with the modern async call getaddrinfo_a (see http://www.imperialviolet.org/page25.html#e498)\&. Otherwise, please continue\&. +.PP +The library keeps track of the state of nameservers and will avoid them when they go down\&. Otherwise it will round robin between them\&. +.PP +Quick start guide: #include 'evdns\&.h' void callback(int result, char type, int count, int ttl, void *addresses, void *arg); evdns_resolv_conf_parse(DNS_OPTIONS_ALL, '/etc/resolv\&.conf'); evdns_resolve('www\&.hostname\&.com', 0, callback, NULL); +.PP +When the lookup is complete the callback function is called\&. The first argument will be one of the DNS_ERR_* defines in evdns\&.h\&. Hopefully it will be DNS_ERR_NONE, in which case type will be DNS_IPv4_A, count will be the number of IP addresses, ttl is the time which the data can be cached for (in seconds), addresses will point to an array of uint32_t's and arg will be whatever you passed to evdns_resolve\&. +.PP +Searching: +.PP +In order for this library to be a good replacement for glibc's resolver it supports searching\&. This involves setting a list of default domains, in which names will be queried for\&. The number of dots in the query name determines the order in which this list is used\&. +.PP +Searching appears to be a single lookup from the point of view of the API, although many DNS queries may be generated from a single call to evdns_resolve\&. Searching can also drastically slow down the resolution of names\&. +.PP +To disable searching: +.IP "1." 4 +Never set it up\&. If you never call evdns_resolv_conf_parse or evdns_search_add then no searching will occur\&. +.IP "2." 4 +If you do call evdns_resolv_conf_parse then don't pass DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it)\&. +.IP "3." 4 +When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag\&. +.PP +.PP +The order of searches depends on the number of dots in the name\&. If the number is greater than the ndots setting then the names is first tried globally\&. Otherwise each search domain is appended in turn\&. +.PP +The ndots setting can either be set from a resolv\&.conf, or by calling evdns_search_ndots_set\&. +.PP +For example, with ndots set to 1 (the default) and a search domain list of ['myhome\&.net']: Query: www Order: www\&.myhome\&.net, www\&. +.PP +Query: www\&.abc Order: www\&.abc\&., www\&.abc\&.myhome\&.net +.PP +Internals: +.PP +Requests are kept in two queues\&. The first is the inflight queue\&. In this queue requests have an allocated transaction id and nameserver\&. They will soon be transmitted if they haven't already been\&. +.PP +The second is the waiting queue\&. The size of the inflight ring is limited and all other requests wait in waiting queue for space\&. This bounds the number of concurrent requests so that we don't flood the nameserver\&. Several algorithms require a full walk of the inflight queue and so bounding its size keeps thing going nicely under huge (many thousands of requests) loads\&. +.PP +If a nameserver loses too many requests it is considered down and we try not to use it\&. After a while we send a probe to that nameserver (a lookup for google\&.com) and, if it replies, we consider it working again\&. If the nameserver fails a probe we wait longer to try again with the next probe\&. +.SH "Macro Definition Documentation" +.PP +.SS "#define DNS_ERR_NODATA 70" + +.PP +There were no answers and no error condition in the DNS packet\&. This can happen when you ask for an address that exists, but a record type that doesn't\&. +.SS "#define DNS_ERR_NONE 0" + +.PP +Error codes 0-5 are as described in RFC 1035\&. +.SS "#define DNS_ERR_SHUTDOWN 68" + +.PP +The request was canceled because the DNS subsystem was shut down\&. +.SS "#define EVDNS_BASE_DISABLE_WHEN_INACTIVE 0x8000" + +.PP +Flag for evdns_base_new: Do not prevent the libevent event loop from exiting when we have no active dns requests\&. +.SS "#define EVDNS_BASE_INITIALIZE_NAMESERVERS 1" + +.PP +Flag for evdns_base_new: process resolv\&.conf\&. +.SH "Typedef Documentation" +.PP +.SS "typedef void(* evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg)" + +.PP +The callback that contains the results from a lookup\&. +.IP "\(bu" 2 +result is one of the DNS_ERR_* values (DNS_ERR_NONE for success) +.IP "\(bu" 2 +type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA +.IP "\(bu" 2 +count contains the number of addresses of form type +.IP "\(bu" 2 +ttl is the number of seconds the resolution may be cached for\&. +.IP "\(bu" 2 +addresses needs to be cast according to type\&. It will be an array of 4-byte sequences for ipv4, or an array of 16-byte sequences for ipv6, or a nul-terminated string for PTR\&. +.PP + +.SS "typedef void(* evdns_debug_log_fn_type) (int is_warning, const char *msg)" + +.PP +A callback that is invoked when a log message is generated\&. +.PP +\fBParameters:\fP +.RS 4 +\fIis_warning\fP indicates if the log message is a 'warning' +.br +\fImsg\fP the content of the log message +.RE +.PP + +.SS "typedef void(* evdns_getaddrinfo_cb) (int result, struct \fBevutil_addrinfo\fP *res, void *arg)" + +.PP +Callback for evdns_getaddrinfo\&. +.SS "typedef void(* evdns_request_callback_fn_type) (struct evdns_server_request *, void *)" + +.PP +A callback to implement a DNS server\&. The callback function receives a DNS request\&. It should then optionally add a number of answers to the reply using the evdns_server_request_add_*_reply functions, before calling either evdns_server_request_respond to send the reply back, or evdns_server_request_drop to decline to answer the request\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP A newly received request +.br +\fIuser_data\fP A pointer that was passed to \fBevdns_add_server_port_with_base()\fP\&. +.RE +.PP + +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL struct evdns_server_port* evdns_add_server_port_with_base (struct \fBevent_base\fP * base, \fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void * user_data)" + +.PP +Create a new DNS server port\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP The event base to handle events for the server port\&. +.br +\fIsocket\fP A UDP socket to accept DNS requests\&. +.br +\fIflags\fP Always 0 for now\&. +.br +\fIcallback\fP A function to invoke whenever we get a DNS request on the socket\&. +.br +\fIuser_data\fP Data to pass to the callback\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +an evdns_server_port structure for this server port\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_base_clear_host_addresses (struct evdns_base * base)" + +.PP +Remove all hosts entries that have been loaded into the \fBevent_base\fP via evdns_base_load_hosts or via event_base_resolv_conf_parse\&. +.PP +\fBParameters:\fP +.RS 4 +\fIevdns_base\fP the evdns base to remove outdated host addresses from +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_clear_nameservers_and_suspend (struct evdns_base * base)" + +.PP +Remove all configured nameservers, and suspend all pending resolves\&. Resolves will not necessarily be re-attempted until \fBevdns_base_resume()\fP is called\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_resume()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_count_nameservers (struct evdns_base * base)" + +.PP +Get the number of configured nameservers\&. This returns the number of configured nameservers (not necessarily the number of running nameservers)\&. This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of configured nameservers +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_nameserver_add()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_base_free (struct evdns_base * base, int fail_requests)" + +.PP +Shut down the asynchronous DNS resolver and terminate all active requests\&. If the 'fail_requests' option is enabled, all active requests will return an empty result with the error flag set to DNS_ERR_SHUTDOWN\&. Otherwise, the requests will be silently discarded\&. +.PP +\fBParameters:\fP +.RS 4 +\fIevdns_base\fP the evdns base to free +.br +\fIfail_requests\fP if zero, active requests will be aborted; if non-zero, active requests will return DNS_ERR_SHUTDOWN\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_new()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_get_nameserver_addr (struct evdns_base * base, int idx, struct sockaddr * sa, ev_socklen_t len)" + +.PP +Retrieve the address of the 'idx'th configured nameserver\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP The evdns_base to examine\&. +.br +\fIidx\fP The index of the nameserver to get the address of\&. +.br +\fIsa\fP A location to receive the server's address\&. +.br +\fIlen\fP The number of bytes available at sa\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of bytes written into sa on success\&. On failure, returns -1 if idx is greater than the number of configured nameservers, or a value greater than 'len' if len was not high enough\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_load_hosts (struct evdns_base * base, const char * hosts_fname)" + +.PP +Load an /etc/hosts-style file from 'hosts_fname' into 'base'\&. If hosts_fname is NULL, add minimal entries for localhost, and nothing else\&. +.PP +Note that only evdns_getaddrinfo uses the /etc/hosts entries\&. +.PP +This function does not replace previously loaded hosts entries; to do that, call evdns_base_clear_host_addresses first\&. +.PP +Return 0 on success, negative on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_add (struct evdns_base * base, unsigned long int address)" + +.PP +Add a nameserver\&. The address should be an IPv4 address in network byte order\&. The type of address is chosen so that it matches in_addr\&.s_addr\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to add the name server +.br +\fIaddress\fP an IP address in network byte order +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_nameserver_ip_add()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_ip_add (struct evdns_base * base, const char * ip_as_string)" + +.PP +Add a nameserver by string address\&. This function parses a n IPv4 or IPv6 address from a string and adds it as a nameserver\&. It supports the following formats: +.IP "\(bu" 2 +[IPv6Address]:port +.IP "\(bu" 2 +[IPv6Address] +.IP "\(bu" 2 +IPv6Address +.IP "\(bu" 2 +IPv4Address:port +.IP "\(bu" 2 +IPv4Address +.PP +.PP +If no port is specified, it defaults to 53\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_nameserver_add()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_base* evdns_base_new (struct \fBevent_base\fP * event_base, int initialize_nameservers)" + +.PP +Initialize the asynchronous DNS library\&. This function initializes support for non-blocking name resolution by calling \fBevdns_resolv_conf_parse()\fP on UNIX and evdns_config_windows_nameservers() on Windows\&. +.PP +\fBParameters:\fP +.RS 4 +\fI\fBevent_base\fP\fP the event base to associate the dns client with +.br +\fIflags\fP any of EVDNS_BASE_INITIALIZE_NAMESERVERS| EVDNS_BASE_DISABLE_WHEN_INACTIVE +.RE +.PP +\fBReturns:\fP +.RS 4 +evdns_base object if successful, or NULL if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_free()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_resolv_conf_parse (struct evdns_base * base, int flags, const char *const filename)" + +.PP +Parse a resolv\&.conf file\&. The 'flags' parameter determines what information is parsed from the resolv\&.conf file\&. See the man page for resolv\&.conf for the format of this file\&. +.PP +The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug\&. +.PP +If this function encounters an error, the possible return values are: 1 = failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of memory, 5 = short read from file, 6 = no nameservers listed in the file +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIflags\fP any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| DNS_OPTION_HOSTSFILE|DNS_OPTIONS_ALL +.br +\fIfilename\fP the path to the resolv\&.conf file +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or various positive error codes if an error occurred (see above) +.RE +.PP +\fBSee also:\fP +.RS 4 +resolv\&.conf(3), evdns_config_windows_nameservers() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_request* evdns_base_resolve_ipv4 (struct evdns_base * base, const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup an A record for a given name\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIname\fP a DNS hostname +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +an evdns_request object if successful, or NULL if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_ipv6()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_request* evdns_base_resolve_ipv6 (struct evdns_base * base, const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup an AAAA record for a given name\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIname\fP a DNS hostname +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +an evdns_request object if successful, or NULL if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_ipv4()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_request* evdns_base_resolve_reverse (struct evdns_base * base, const struct in_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup a PTR record for a given IP address\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIin\fP an IPv4 address +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +an evdns_request object if successful, or NULL if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_request* evdns_base_resolve_reverse_ipv6 (struct evdns_base * base, const struct in6_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup a PTR record for a given IPv6 address\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIin\fP an IPv6 address +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +an evdns_request object if successful, or NULL if an error occurred\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_resume (struct evdns_base * base)" + +.PP +Resume normal operation and continue any suspended resolve requests\&. Re-attempt resolves left in limbo after an earlier call to \fBevdns_base_clear_nameservers_and_suspend()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_clear_nameservers_and_suspend()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_base_search_add (struct evdns_base * base, const char * domain)" + +.PP +Add a domain to the list of search domains\&. +.PP +\fBParameters:\fP +.RS 4 +\fIdomain\fP the domain to be added to the search list +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_base_search_clear (struct evdns_base * base)" + +.PP +Obtain nameserver information using the Windows API\&. Attempt to configure a set of nameservers based on platform settings on a win32 host\&. Preferentially tries to use GetNetworkParams; if that fails, looks in the registry\&. +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolv_conf_parse()\fP Clear the list of search domains\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_base_search_ndots_set (struct evdns_base * base, const int ndots)" + +.PP +Set the 'ndots' parameter for searches\&. Sets the number of dots which, when found in a name, causes the first query to be without any search domain\&. +.PP +\fBParameters:\fP +.RS 4 +\fIndots\fP the new ndots parameter +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evdns_base_set_option (struct evdns_base * base, const char * option, const char * val)" + +.PP +Set the value of a configuration option\&. The currently available configuration options are: +.PP +ndots, timeout, max-timeouts, max-inflight, attempts, randomize-case, bind-to, initial-probe-timeout, getaddrinfo-allow-skew\&. +.PP +In versions before Libevent 2\&.0\&.3-alpha, the option name needed to end with a colon\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base to which to apply this operation +.br +\fIoption\fP the name of the configuration option to be modified +.br +\fIval\fP the value to be set +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_cancel_request (struct evdns_base * base, struct evdns_request * req)" + +.PP +Cancels a pending DNS resolution request\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evdns_base that was used to make the request +.br +\fIreq\fP the evdns_request that was returned by calling a resolve function +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_base_resolve_ipv4()\fP, \fBevdns_base_resolve_ipv6\fP, \fBevdns_base_resolve_reverse\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_close_server_port (struct evdns_server_port * port)" + +.PP +Close down a DNS server port, and free associated structures\&. +.SS "EVENT2_EXPORT_SYMBOL const char* evdns_err_to_string (int err)" + +.PP +Convert a DNS error code to a string\&. +.PP +\fBParameters:\fP +.RS 4 +\fIerr\fP the DNS error code +.RE +.PP +\fBReturns:\fP +.RS 4 +a string containing an explanation of the error code +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evdns_getaddrinfo_request* evdns_getaddrinfo (struct evdns_base * dns_base, const char * nodename, const char * servname, const struct \fBevutil_addrinfo\fP * hints_in, \fBevdns_getaddrinfo_cb\fP cb, void * arg)" + +.PP +Make a non-blocking getaddrinfo request using the dns_base in 'dns_base'\&. If we can answer the request immediately (with an error or not!), then we invoke cb immediately and return NULL\&. Otherwise we return an evdns_getaddrinfo_request and invoke cb later\&. +.PP +When the callback is invoked, we pass as its first argument the error code that getaddrinfo would return (or 0 for no error)\&. As its second argument, we pass the \fBevutil_addrinfo\fP structures we found (or NULL on error)\&. We pass 'arg' as the third argument\&. +.PP +Limitations: +.PP +.IP "\(bu" 2 +The AI_V4MAPPED and AI_ALL flags are not currently implemented\&. +.IP "\(bu" 2 +For ai_socktype, we only handle SOCKTYPE_STREAM, SOCKTYPE_UDP, and 0\&. +.IP "\(bu" 2 +For ai_protocol, we only handle IPPROTO_TCP, IPPROTO_UDP, and 0\&. +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_server_request_set_flags (struct evdns_server_request * req, int flags)" + +.PP +Sets some flags in a reply we're building\&. Allows setting of the AA or RD flags +.SS "EVENT2_EXPORT_SYMBOL void evdns_set_log_fn (\fBevdns_debug_log_fn_type\fP fn)" + +.PP +Set the callback function to handle DNS log messages\&. If this callback is not set, evdns log messages are handled with the regular Libevent logging system\&. +.PP +\fBParameters:\fP +.RS 4 +\fIfn\fP the callback to be invoked when a log message is generated +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evdns_set_random_bytes_fn (void(*)(char *, size_t) fn)" + +.PP +Set a callback used to generate random bytes\&. By default, we use the same function as passed to evdns_set_transaction_id_fn to generate bytes two at a time\&. If a function is provided here, it's also used to generate transaction IDs\&. +.PP +NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&. +.SS "EVENT2_EXPORT_SYMBOL void evdns_set_transaction_id_fn (ev_uint16_t(*)(void) fn)" + +.PP +Set a callback that will be invoked to generate transaction IDs\&. By default, we pick transaction IDs based on the current clock time, which is bad for security\&. +.PP +\fBParameters:\fP +.RS 4 +\fIfn\fP the new callback, or NULL to use the default\&. +.RE +.PP +NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&. +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/dns_compat.h.3 b/static/netbsd/man3/dns_compat.h.3 new file mode 100644 index 00000000..cbf50173 --- /dev/null +++ b/static/netbsd/man3/dns_compat.h.3 @@ -0,0 +1,513 @@ +.TH "event2/dns_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/dns_compat.h \- Potentially non-threadsafe versions of the functions in \fBdns\&.h\fP: provided only for backwards compatibility\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Functions" + +.in +1c +.ti -1c +.RI "struct evdns_server_port * \fBevdns_add_server_port\fP (\fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void *user_data)" +.br +.RI "\fIAs evdns_server_new_with_base\&. \fP" +.ti -1c +.RI "int \fBevdns_clear_nameservers_and_suspend\fP (void)" +.br +.RI "\fIRemove all configured nameservers, and suspend all pending resolves\&. \fP" +.ti -1c +.RI "int \fBevdns_count_nameservers\fP (void)" +.br +.RI "\fIGet the number of configured nameservers\&. \fP" +.ti -1c +.RI "struct evdns_base * \fBevdns_get_global_base\fP (void)" +.br +.RI "\fIReturn the global evdns_base created by \fBevent_init()\fP and used by the other deprecated functions\&. \fP" +.ti -1c +.RI "int \fBevdns_init\fP (void)" +.br +.RI "\fIInitialize the asynchronous DNS library\&. \fP" +.ti -1c +.RI "int \fBevdns_nameserver_add\fP (unsigned long int address)" +.br +.RI "\fIAdd a nameserver\&. \fP" +.ti -1c +.RI "int \fBevdns_nameserver_ip_add\fP (const char *ip_as_string)" +.br +.RI "\fIAdd a nameserver\&. \fP" +.ti -1c +.RI "int \fBevdns_resolv_conf_parse\fP (int flags, const char *const filename)" +.br +.RI "\fIParse a resolv\&.conf file\&. \fP" +.ti -1c +.RI "int \fBevdns_resolve_ipv4\fP (const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup an A record for a given name\&. \fP" +.ti -1c +.RI "int \fBevdns_resolve_ipv6\fP (const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup an AAAA record for a given name\&. \fP" +.ti -1c +.RI "int \fBevdns_resolve_reverse\fP (const struct in_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup a PTR record for a given IP address\&. \fP" +.ti -1c +.RI "int \fBevdns_resolve_reverse_ipv6\fP (const struct in6_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)" +.br +.RI "\fILookup a PTR record for a given IPv6 address\&. \fP" +.ti -1c +.RI "int \fBevdns_resume\fP (void)" +.br +.RI "\fIResume normal operation and continue any suspended resolve requests\&. \fP" +.ti -1c +.RI "void \fBevdns_search_add\fP (const char *domain)" +.br +.RI "\fIAdd a domain to the list of search domains\&. \fP" +.ti -1c +.RI "void \fBevdns_search_clear\fP (void)" +.br +.RI "\fIClear the list of search domains\&. \fP" +.ti -1c +.RI "void \fBevdns_search_ndots_set\fP (const int ndots)" +.br +.RI "\fISet the 'ndots' parameter for searches\&. \fP" +.ti -1c +.RI "int \fBevdns_set_option\fP (const char *option, const char *val, int flags)" +.br +.RI "\fISet the value of a configuration option\&. \fP" +.ti -1c +.RI "void \fBevdns_shutdown\fP (int fail_requests)" +.br +.RI "\fIShut down the asynchronous DNS resolver and terminate all active requests\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Potentially non-threadsafe versions of the functions in \fBdns\&.h\fP: provided only for backwards compatibility\&. + + +.SH "Function Documentation" +.PP +.SS "struct evdns_server_port* evdns_add_server_port (\fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void * user_data)" + +.PP +As evdns_server_new_with_base\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which even_base it uses\&. The recommended function is \fBevdns_add_server_port_with_base()\fP\&. +.RE +.PP + +.SS "int evdns_clear_nameservers_and_suspend (void)" + +.PP +Remove all configured nameservers, and suspend all pending resolves\&. Resolves will not necessarily be re-attempted until \fBevdns_resume()\fP is called\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_clear_nameservers_and_suspend()\fP\&. +.RE +.PP +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resume()\fP +.RE +.PP + +.SS "int evdns_count_nameservers (void)" + +.PP +Get the number of configured nameservers\&. This returns the number of configured nameservers (not necessarily the number of running nameservers)\&. This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_count_nameservers()\fP\&. +.RE +.PP +.PP +\fBReturns:\fP +.RS 4 +the number of configured nameservers +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_nameserver_add()\fP +.RE +.PP + +.SS "struct evdns_base* evdns_get_global_base (void)" + +.PP +Return the global evdns_base created by \fBevent_init()\fP and used by the other deprecated functions\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because use of the global evdns_base is error-prone\&. +.RE +.PP + +.SS "int evdns_init (void)" + +.PP +Initialize the asynchronous DNS library\&. This function initializes support for non-blocking name resolution by calling \fBevdns_resolv_conf_parse()\fP on UNIX and evdns_config_windows_nameservers() on Windows\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it always uses the current event base, and is easily confused by multiple calls to \fBevent_init()\fP, and so is not safe for multithreaded use\&. Additionally, it allocates a global structure that only one thread can use\&. The replacement is \fBevdns_base_new()\fP\&. +.RE +.PP +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_shutdown()\fP +.RE +.PP + +.SS "int evdns_nameserver_add (unsigned long int address)" + +.PP +Add a nameserver\&. The address should be an IPv4 address in network byte order\&. The type of address is chosen so that it matches in_addr\&.s_addr\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_add()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIaddress\fP an IP address in network byte order +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_nameserver_ip_add()\fP +.RE +.PP + +.SS "int evdns_nameserver_ip_add (const char * ip_as_string)" + +.PP +Add a nameserver\&. This wraps the \fBevdns_nameserver_add()\fP function by parsing a string as an IP address and adds it as a nameserver\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_nameserver_ip_add()\fP\&. +.RE +.PP +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_nameserver_add()\fP +.RE +.PP + +.SS "int evdns_resolv_conf_parse (int flags, const char *const filename)" + +.PP +Parse a resolv\&.conf file\&. The 'flags' parameter determines what information is parsed from the resolv\&.conf file\&. See the man page for resolv\&.conf for the format of this file\&. +.PP +The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug\&. +.PP +If this function encounters an error, the possible return values are: 1 = failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of memory, 5 = short read from file, 6 = no nameservers listed in the file +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolv_conf_parse()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIflags\fP any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| DNS_OPTIONS_ALL +.br +\fIfilename\fP the path to the resolv\&.conf file +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or various positive error codes if an error occurred (see above) +.RE +.PP +\fBSee also:\fP +.RS 4 +resolv\&.conf(3), evdns_config_windows_nameservers() +.RE +.PP + +.SS "int evdns_resolve_ipv4 (const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup an A record for a given name\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_ipv4()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIname\fP a DNS hostname +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_ipv6()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP +.RE +.PP + +.SS "int evdns_resolve_ipv6 (const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup an AAAA record for a given name\&. +.PP +\fBParameters:\fP +.RS 4 +\fIname\fP a DNS hostname +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_ipv4()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP +.RE +.PP + +.SS "int evdns_resolve_reverse (const struct in_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup a PTR record for a given IP address\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIin\fP an IPv4 address +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_reverse_ipv6()\fP +.RE +.PP + +.SS "int evdns_resolve_reverse_ipv6 (const struct in6_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" + +.PP +Lookup a PTR record for a given IPv6 address\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resolve_reverse_ipv6()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIin\fP an IPv6 address +.br +\fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. +.br +\fIcallback\fP a callback function to invoke when the request is completed +.br +\fIptr\fP an argument to pass to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_resolve_reverse_ipv6()\fP +.RE +.PP + +.SS "int evdns_resume (void)" + +.PP +Resume normal operation and continue any suspended resolve requests\&. Re-attempt resolves left in limbo after an earlier call to \fBevdns_clear_nameservers_and_suspend()\fP\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_resume()\fP\&. +.RE +.PP +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_clear_nameservers_and_suspend()\fP +.RE +.PP + +.SS "void evdns_search_add (const char * domain)" + +.PP +Add a domain to the list of search domains\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_add()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIdomain\fP the domain to be added to the search list +.RE +.PP + +.SS "void evdns_search_clear (void)" + +.PP +Clear the list of search domains\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_clear()\fP\&. +.RE +.PP + +.SS "void evdns_search_ndots_set (const int ndots)" + +.PP +Set the 'ndots' parameter for searches\&. Sets the number of dots which, when found in a name, causes the first query to be without any search domain\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_search_ndots_set()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIndots\fP the new ndots parameter +.RE +.PP + +.SS "int evdns_set_option (const char * option, const char * val, int flags)" + +.PP +Set the value of a configuration option\&. The currently available configuration options are: +.PP +ndots, timeout, max-timeouts, max-inflight, and attempts +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is \fBevdns_base_set_option()\fP\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIoption\fP the name of the configuration option to be modified +.br +\fIval\fP the value to be set +.br +\fIflags\fP Ignored\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "void evdns_shutdown (int fail_requests)" + +.PP +Shut down the asynchronous DNS resolver and terminate all active requests\&. If the 'fail_requests' option is enabled, all active requests will return an empty result with the error flag set to DNS_ERR_SHUTDOWN\&. Otherwise, the requests will be silently discarded\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it does not allow the caller to specify which evdns_base it applies to\&. The recommended function is evdns_base_shutdown()\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIfail_requests\fP if zero, active requests will be aborted; if non-zero, active requests will return DNS_ERR_SHUTDOWN\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevdns_init()\fP +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/do_add.3 b/static/netbsd/man3/do_add.3 new file mode 100644 index 00000000..2a1c59a0 --- /dev/null +++ b/static/netbsd/man3/do_add.3 @@ -0,0 +1,18 @@ +dn: cn=James A Jones 4,ou=People,dc=example,dc=com +objectClass: OpenLDAPperson +cn: James A Jones 4 +cn: James Jones +cn: Jim Jones +sn: Jones +uid: jaj +postalAddress: Alumni Association $ 111 Maple St $ Anytown, MI 48109 +seeAlso: cn=All Staff, ou=Groups, dc=example,dc=com +userpassword:: amFq +homePostalAddress: 3882 Beverly Rd. $ Anytown, MI 48105 +homePhone: +1 313 555 4772 +description: Outstanding +title: Mad Cow Researcher, UM Alumni Association +pager: +1 313 555 3923 +mail: jaj@mail.alumni.example.com +facsimileTelephoneNumber: +1 313 555 4332 +telephoneNumber: +1 313 555 0895 diff --git a/static/netbsd/man3/duplocale.3 b/static/netbsd/man3/duplocale.3 new file mode 100644 index 00000000..04b73ba9 --- /dev/null +++ b/static/netbsd/man3/duplocale.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: duplocale.3,v 1.4 2024/08/21 18:42:34 rillig Exp $ +.\" +.\" Copyright (c) 2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by David Chisnall under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/locale/duplocale.3 281925 2015-04-24 10:17:55Z theraven $ +.\" +.Dd February 15, 2021 +.Dt DUPLOCALE 3 +.Os +.Sh NAME +.Nm duplocale +.Nd duplicate a locale +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In locale.h +.Ft locale_t +.Fn duplocale "locale_t locale" +.Sh DESCRIPTION +Duplicates an existing +.Fa locale_t +returning a new +.Fa locale_t +that refers to the same locale values but has an independent internal state. +The locale returned by this call must be freed with +.Xr freelocale 3 . +.Sh SEE ALSO +.Xr freelocale 3 , +.Xr localeconv 3 , +.Xr newlocale 3 +.\" .Xr querylocale 3 , +.\" .Xr uselocale 3 , +.\" .Xr xlocale 3 +.Sh STANDARDS +This function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/dwarf.3 b/static/netbsd/man3/dwarf.3 new file mode 100644 index 00000000..8a0ef1c3 --- /dev/null +++ b/static/netbsd/man3/dwarf.3 @@ -0,0 +1,755 @@ +.\" $NetBSD: dwarf.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf.3 3929 2021-03-07 21:43:46Z jkoshy +.\" +.Dd December 21, 2014 +.Dt DWARF 3 +.Os +.Sh NAME +.Nm dwarf +.Nd access debugging information in object files +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Sh DESCRIPTION +The +.Lb libdwarf +provides functions that allow an application to read and write debugging +information in object files. +The format of debugging information accessible through this API +is defined by the DWARF standard, see +.Xr dwarf 4 . +.Pp +The +.Xr DWARF 3 +API has two parts: +.Bl -bullet +.It +A consumer API set allows applications to read existing debug information +in a program object. +The functions that comprise the DWARF consumer API are described in +the section +.Sx "DWARF Consumer API" +below. +.It +A producer API set that allows applications to add debug information +to a program object. +The functions that comprise the DWARF producer API are described in +the section +.Sx "DWARF Producer API" +below. +.El +.Pp +Each function referenced below is further described in its own manual page. +.Ss Namespace use +The DWARF library uses the following prefixes: +.Pp +.Bl -tag -width ".Li Dwarf_*" -compact +.It Li DWARF_* +Used for error numbers and constants. +.It Li DW_* +Used for constants. +.It Li Dwarf_* +Used for types. +.It Li dwarf_* +Used for functions and macros that make up the API. +.El +.Ss Data Types +The DWARF(3) API uses the following data types: +.Pp +.Bl -tag -width ".Vt Dwarf_Unsigned" -compact +.It Vt Dwarf_Abbrev +Describes DWARF abbreviations. +.It Vt Dwarf_Addr +A program address in the target object. +.It Vt Dwarf_Arange +Describes address ranges. +.It Vt Dwarf_Attribute , Vt Dwarf_P_Attribute +Describes attributes of debugging information entries. +.It Vt Dwarf_Bool +Used for boolean states. +.It Vt Dwarf_Cie , Vt Dwarf_P_Cie +Describes call information that is common to several frames. +.It Vt Dwarf_Debug , Vt Dwarf_P_Debug +An opaque type describing a debug context. +.It Vt Dwarf_Die , Vt Dwarf_P_Die +A debugging information entry. +.It Vt Dwarf_Fde , Vt Dwarf_P_Fde +A frame descriptor. +.It Vt Dwarf_Func +A descriptor representing a function. +.It Vt Dwarf_Global +A descriptor representing a global name. +.It Vt Dwarf_Half +A 16-bit wide unsigned numeric type. +.It Vt Dwarf_Handler +A pointer to an error handling function. +.It Vt Dwarf_Line +A descriptor for a source line. +.It Vt Dwarf_Off +An unsigned file offset. +.It Vt Dwarf_P_Expr +A descriptor for a location expression. +.It Vt Dwarf_Ptr +A virtual address used by an application. +.It Vt Dwarf_Signed +A 64-bit wide signed numeric type. +.It Vt Dwarf_Small +An 8-bit wide unsigned numeric type. +.It Vt Dwarf_Type +A descriptor representing a user-specified type. +.It Vt Dwarf_Unsigned +A 64-bit wide unsigned numeric type. +.It Vt Dwarf_Var +A descriptor representing a static variable. +.It Vt Dwarf_Weak +A descriptor representing a weak name. +.El +.Ss Error Handling +Library functions that encounter an error will return with a value +other than +.Dv DW_DLV_OK . +.Pp +The +.Lb libdwarf +allows applications to specify three levels of error handling: +.Bl -enum -compact +.It +Most library functions take a parameter of type +.Vt Dwarf_Error +that specifies a location to store an error descriptor in +case of an error. +If an error occurs during the execution on an API, and if this +parameter is +.No non- Ns Dv NULL , +then an error descriptor is written to the location specified. +.It +Otherwise, if the error parameter was +.Dv NULL , +but if an error handler was defined for the debug context in use using +.Xr dwarf_init 3 +or +.Xr dwarf_seterrhand 3 , +then the library will invoke the specified error handler with an error +descriptor as argument. +.It +Otherwise, if a library wide error handler was specified using +.Xr dwarf_seterrhand 3 , +it is called. +.El +.Pp +Error descriptors may be used with +.Xr dwarf_errmsg 3 +or +.Xr dwarf_errno 3 . +.Sh The DWARF Consumer API +The DWARF consumer API permits applications to read DWARF information in +an object file. +.Pp +The major functional groups of functions in the consumer API are listed +below. +.Pp +.Bl -tag -compact -width "CCCC" +.It Abbreviations +.Bl -tag -compact -width indent +.It Fn dwarf_get_abbrev +Retrieve abbreviation information at a given offset. +.It Fn dwarf_get_abbrev_children_flag +Check if an abbreviation has child elements. +.It Fn dwarf_get_abbrev_code +Retrieve the abbreviation code for an abbreviation entry descriptor. +.It Fn dwarf_get_abbrev_entry +Retrieve abbreviation information for an abbreviation entry +descriptor. +.It Fn dwarf_get_abbrev_tag +Retrieve the tag for an abbreviation entry. +.El +.It Addresses +.Bl -tag -compact -width indent +.It Fn dwarf_get_address_size +Return the number of bytes needed to represent an address. +.It Fn dwarf_get_arange +Search for an address range descriptor covering an address. +.It Fn dwarf_get_arange_cu_header_offset +Retrieve the offsets associated with an address range descriptor. +.It Fn dwarf_get_arange_info +Extract address range information from a descriptor. +.It Fn dwarf_get_aranges +Retrieve program address space mappings. +.It Fn dwarf_get_cu_die_offset +Retrieve the offset associated with a compilation unit for an address +range descriptor. +.It Fn dwarf_get_ranges , Fn dwarf_get_ranges_a +Retrieve information about non-contiguous address ranges for +a debugging information entry. +.El +.It Attributes +.Bl -tag -compact -width indent +.It Fn dwarf_arrayorder +Retrieve the value of a +.Dv DW_AT_ordering +attribute. +.It Fn dwarf_attr +Retrieve an attribute descriptor. +.It Fn dwarf_attrlist +Retrieve attribute descriptors for a debugging information entry. +.It Fn dwarf_attroffset +Retrieve the section-relative offset of an attribute descriptor. +.It Fn dwarf_attrval_flag +Retrieve a +.Dv DW_AT_FORM_flag +value. +.It Fn dwarf_attrval_signed +Retrieve an attribute's value as a signed integral quantity. +.It Fn dwarf_attrval_string +Retrieve an attribute's value as a NUL-terminated string. +.It Fn dwarf_attrval_unsigned +Retrieve an attribute's value as an unsigned integral quantity. +.It Fn dwarf_bitoffset , +Retrieve the value of a +.Dv DW_AT_bit_offset +attribute. +.It Fn dwarf_bitsize , +Retrieve the value of a +.Dv DW_AT_bit_size +attribute. +.It Fn dwarf_bytesize +Retrieve the value of a +.Dv DW_AT_byte_size +attribute. +.It Fn dwarf_formaddr +Return the value of an +.Dv ADDRESS Ns - Ns +class attribute. +.It Fn dwarf_formblock +Return the value of a +.Dv BLOCK Ns - Ns +class attribute +.It Fn dwarf_formexprloc +Return information about a location expression. +.It Fn dwarf_formflag +Retrieve information about a +.Dv BOOLEAN Ns - Ns +class attribute. +.It Fn dwarf_formref , Fn dwarf_global_formref +Retrieve offsets for +.Dv REFERENCE Ns - Ns +class attributes. +.It Fn dwarf_formsdata , Fn dwarf_formudata +Retrieve the value of a +.Dv CONSTANT Ns - Ns +class attribute. +.It Fn dwarf_formsig8 +Return the type signature for a DWARF type. +.It Fn dwarf_formstring +Retrieve information about a +.Dv STRING Ns - Ns +class attribute. +.It Fn dwarf_get_form_class +Retrieve the form class for an attribute. +.It Fn dwarf_hasattr +Check for the presence of an attribute. +.It Fn dwarf_hasform +Check if an attribute has the given form. +.It Fn dwarf_whatattr +Retrieve the attribute code for an attribute. +.It Fn dwarf_whatform , Fn dwarf_whatform_direct +Retrieve the form of an attribute. +.El +.It Call Information Entries and Frame Descriptor Entries +.Bl -tag -compact -width indent +.It Fn dwarf_get_cie_index +Retrieve the index for a CIE descriptor. +.It Fn dwarf_get_cie_info +Retrieve information from a CIE descriptor. +.It Fn dwarf_get_cie_of_fde +Retrieve a CIE descriptor. +.It Fn dwarf_get_fde_at_pc +Retrieve an FDE descriptor for an address. +.It Fn dwarf_get_fde_info_for_all_regs +Retrieve register rule row. +.It Fn dwarf_get_fde_info_for_all_regs3 +Retrieve register rule row (revised API). +.It Fn dwarf_get_fde_info_for_cfa_reg3 +Retrieve a CFA register rule. +.It Fn dwarf_get_fde_info_for_reg +Retrieve a register rule. +.It Fn dwarf_get_fde_info_for_reg3 +Retrieve a register rule (revised API). +.It Fn dwarf_get_fde_instr_bytes +Retrieve instructions from an FDE descriptor. +.It Fn dwarf_get_fde_list , Fn dwarf_get_fde_list_eh +Retrieve frame information. +.It Fn dwarf_get_fde_n +Retrieve an FDE descriptor. +.It Fn dwarf_get_fde_range +Retrieve range information from an FDE descriptor. +.El +.It Compilation Units +.Bl -tag -compact -width indent +.It Xo +.Fn dwarf_get_cu_die_offset_given_cu_header_offset , +.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b +.Xc +Retrieve the offset of the debugging information entry for a +compilation or type unit. +.It Xo +.Fn dwarf_next_cu_header , +.Fn dwarf_next_cu_header_b , +.Fn dwarf_next_cu_header_c +.Xc +Step through compilation units in a debug context. +.El +.It Debugging Information Entries +.Bl -tag -compact -width indent +.It Fn dwarf_child +Returns the child of a debugging information entry. +.It Fn dwarf_die_abbrev_code +Returns the abbreviation code for a debugging information entry. +.It Fn dwarf_die_CU_offset , Fn dwarf_die_CU_offset_range +Retrieve offsets and lengths for a compilation unit. +.It Fn dwarf_diename +Returns the +.Dv DW_AT_name +attribute for a debugging information entry. +.It Fn dwarf_dieoffset +Retrieves the offset for a debugging information entry. +.It Fn dwarf_get_die_infotypes_flag +Indicate the originating section for a debugging information entry. +.It Fn dwarf_highpc , Fn dwarf_highpc_b +Return the highest PC value for a debugging information entry. +.It Fn dwarf_lowpc +Return the lowest PC value for a debugging information entry. +.It Fn dwarf_offdie , Fn dwarf_offdie_b +Retrieve a debugging information entry given an offset. +.It Fn dwarf_siblingof , Fn dwarf_siblingof_b +Retrieve the sibling descriptor for a debugging information entry. +.It Fn dwarf_srclang +Retrieve the source language attribute for a debugging information +entry. +.It Fn dwarf_tag +Retrieve the tag for a debugging information entry. +.El +.It Functions +.Bl -tag -compact -width indent +.It Fn dwarf_func_cu_offset +Retrieves the offset for the compilation unit for a function. +.It Fn dwarf_func_die_offset +Retrieves the offset for the debugging information entry for a +function. +.It Fn dwarf_funcname +Retrieves the name of a function. +.It Fn dwarf_func_name_offsets +Retrieve both the name and offsets for a function. +.It Fn dwarf_get_funcs +Retrieve information about static functions. +.El +.It Globals +.Bl -tag -compact -width indent +.It Fn dwarf_get_globals +Retrieve a list of globals. +.It Fn dwarf_global_cu_offset +Return the offset for compilation unit for a global. +.It Fn dwarf_global_die_offset +Return the offset for the debugging information entry for a global. +.It Fn dwarf_global_name_offsets +Return the name and offsets for a global. +.It Fn dwarf_globname +Return the name for a global. +.El +.It Initialization and Finalization +Functions +.Fn dwarf_elf_init +and +.Fn dwarf_init +may be used for initialization. +The function +.Fn dwarf_finish +may be used to release resources. +.Pp +The functions +.Fn dwarf_object_init +and +.Fn dwarf_object_finish +allow an application to specify alternate low-level file access +routines. +.It Line Numbers +.Bl -tag -compact -width indent +.It Fn dwarf_lineaddr +Retrieve the program address for a source line. +.It Fn dwarf_linebeginstatement +Check if a source line corresponds to the beginning of a statement. +.It Fn dwarf_lineblock +Check if a source line corresponds to the start of a basic block. +.It Fn dwarf_lineendsequence +Check if the source line corresponds to the end of a sequence of +instructions. +.It Fn dwarf_lineno +Retrieve the line number for a line descriptor. +.It Fn dwarf_lineoff +Retrieve the column number for a line descriptor. +.It Fn dwarf_linesrc +Retrieve the source file for a line descriptor. +.It Fn dwarf_line_srcfileno +Retrieve the index of the source file for a line descriptor. +.It Fn dwarf_srcfiles +Retrieve source files for a compilation unit. +.It Fn dwarf_srclines +Return line number information for a compilation unit. +.El +.It Location Lists +.Bl -tag -compact -width indent +.It Fn dwarf_get_loclist_entry +Retrieve a location list entry. +.It Fn dwarf_loclist , Fn dwarf_loclist_n +Retrieve location expressions. +.It Xo +.Fn dwarf_loclist_from_expr , +.Fn dwarf_loclist_from_expr_a , +.Fn dwarf_loclist_from_expr_b +.Xc +Translate a location expression into a location descriptor. +.El +.It Error Handling +.Bl -tag -compact -width indent +.It Fn dwarf_errmsg +Retrieve a human-readable error message. +.It Fn dwarf_errno +Retrieve an error number from an error descriptor. +.It Fn dwarf_seterrarg +Set the argument passed to a callback error handler. +.It Fn dwarf_seterrhand +Set the callback handler to be called in case of an error. +.El +.It Frame Handling +.Bl -tag -compact -width indent +.It Fn dwarf_expand_frame_instructions +Translate frame instruction bytes. +.It Fn dwarf_set_frame_cfa_value +Set the CFA parameter for the internal register rule table. +.It Fn dwarf_set_frame_rule_initial_value +Set the initial value of the register rules in the internal register +rule table. +.It Fn dwarf_set_frame_rule_table_size +Set the maximum number of columns in the register rule table. +.It Fn dwarf_set_frame_same_value +Set the register number representing the +.Dq "same value" +rule. +.It Fn dwarf_set_frame_undefined_value +Set the register number representing the +.Dq "undefined" +rule. +.El +.It Macros +.Bl -tag -compact -width indent +.It Fn dwarf_find_macro_value_start +Return the macro value part of a macro string. +.It Fn dwarf_get_macro_details +Retrieve macro information. +.El +.It Memory Management +In the DWARF consumer API, the rules for memory management differ +between functions. +In some cases, the memory areas returned to the application by the +library are freed by calling specific API functions. +In others, the deallocation function +.Fn dwarf_dealloc +suffices. +The individual manual pages for the API's functions document the +specific memory management rules to be followed. +.Pp +The function +.Fn dwarf_dealloc +is used to mark memory arenas as unused. +Additionally, the following functions release specific types of +DWARF resources: +.Fn dwarf_fde_cie_list_dealloc , +.Fn dwarf_funcs_dealloc , +.Fn dwarf_globals_dealloc , +.Fn dwarf_pubtypes_dealloc , +.Fn dwarf_ranges_dealloc , +.Fn dwarf_srclines_dealloc , +.Fn dwarf_types_dealloc , +.Fn dwarf_vars_dealloc , +and +.Fn dwarf_weaks_dealloc . +.It Symbol Constants +The following functions may be used to return symbolic names +for DWARF constants: +.Fn dwarf_get_ACCESS_name , +.Fn dwarf_get_AT_name , +.Fn dwarf_get_ATE_name , +.Fn dwarf_get_CC_name , +.Fn dwarf_get_CFA_name , +.Fn dwarf_get_CHILDREN_name , +.Fn dwarf_get_DS_name , +.Fn dwarf_get_DSC_name , +.Fn dwarf_get_EH_name , +.Fn dwarf_get_END_name , +.Fn dwarf_get_FORM_name , +.Fn dwarf_get_ID_name , +.Fn dwarf_get_INL_name , +.Fn dwarf_get_LANG_name , +.Fn dwarf_get_LNE_name , +.Fn dwarf_get_LNS_name , +.Fn dwarf_get_MACINFO_name , +.Fn dwarf_get_OP_name , +.Fn dwarf_get_ORD_name , +.Fn dwarf_get_TAG_name , +.Fn dwarf_get_VIRTUALITY_name , +and +.Fn dwarf_get_VIS_name . +.It Types +.Bl -tag -compact -width indent +.It Fn dwarf_get_pubtypes , Fn dwarf_get_types +Retrieve descriptors for user-defined types. +.It Fn dwarf_next_types_section +Step through +.Dq \&.debug_types +sections in a debug context. +.It Fn dwarf_pubtype_cu_offset , Fn dwarf_type_cu_offset +Return the offset for the compilation unit for a type. +.It Fn dwarf_pubtype_die_offset , Fn dwarf_type_die_offset +Return the offset for the debugging information entry for a type. +.It Fn dwarf_pubtypename , Fn dwarf_typename +Retrieve the name of a type. +.It Fn dwarf_pubtype_name_offsets , Fn dwarf_type_name_offsets +Retrieve the name and offsets for a type. +.El +.It Variables +.Bl -tag -compact -width indent +.It Fn dwarf_get_vars +Retrieve descriptors for static variables. +.It Fn dwarf_var_cu_offset +Return the offset for the compilation unit for a variable. +.It Fn dwarf_var_die_offset +Return the offset for the debugging information entry for a variable. +.It Fn dwarf_varname +Retrieve the name of a variable. +.It Fn dwarf_var_name_offsets +Retrieve the name and offsets for a variable. +.El +.It Weak Symbols +.Bl -tag -compact -width indent +.It Fn dwarf_get_weaks +Retrieve information about weak symbols. +.It Fn dwarf_weak_cu_offset +Return the offset for the compilation unit for a weak symbol. +.It Fn dwarf_weak_die_offset +Return the offset for the debugging information entry for a weak symbol. +.It Fn dwarf_weakname +Retrieve the name of a weak symbol. +.It Fn dwarf_weak_name_offsets +Retrieve the name and offsets for a weak symbol. +.El +.It Miscellaneous +.Bl -tag -compact -width indent +.It Fn dwarf_get_elf +Retrieve the ELF descriptor for a debug context, see +.Xr elf 3 . +.It Fn dwarf_get_str +Retrieve a NUL-terminated string from the DWARF string section. +.It Fn dwarf_set_reloc_application +Control whether relocations are to be handled by +.Lb libdwarf . +.El +.El +.Sh The DWARF Producer API +The DWARF producer API permits applications to add DWARF information to +an object file. +.Pp +The major functional groups of functions in the producer API are listed +below. +.Bl -tag -width "CCCC" +.It Attribute Management +The following functions are used to attach attributes to a debugging +information entry: +.Fn dwarf_add_AT_comp_dir , +.Fn dwarf_add_AT_const_value_signedint , +.Fn dwarf_add_AT_const_value_string , +.Fn dwarf_add_AT_const_value_unsignedint , +.Fn dwarf_add_AT_dataref , +.Fn dwarf_add_AT_flag , +.Fn dwarf_add_AT_location_expr , +.Fn dwarf_add_AT_name , +.Fn dwarf_add_AT_producer , +.Fn dwarf_add_AT_ref_address , +.Fn dwarf_add_AT_reference , +.Fn dwarf_add_AT_signed_const , +.Fn dwarf_add_AT_string , +.Fn dwarf_add_AT_targ_address , +.Fn dwarf_add_AT_targ_address_b +and +.Fn dwarf_add_AT_unsigned_const . +.It Debugging Information Entry Management +.Bl -tag -compact -width indent +.It Fn dwarf_add_die_to_debug +Set the root debugging information entry for a DWARF producer instance. +.It Fn dwarf_die_link +Links debugging information entries. +.It Fn dwarf_new_die +Allocate a new debugging information entry. +.El +.It Initialization and Finalization +The functions +.Fn dwarf_producer_init +and +.Fn dwarf_producer_init_b +are used to initialize a producer instance. +.Pp +When done, applications release resources using the function +.Fn dwarf_producer_finish . +.It Relocations and Sections +.Bl -tag -compact -width indent +.It Fn dwarf_get_relocation_info +Retrieve a relocation array from a producer instance. +.It Fn dwarf_get_relocation_info_count +Return the number of relocation arrays for a producer instance. +.It Fn dwarf_get_section_bytes +Retrieve the ELF byte stream for a section. +.It Fn dwarf_reset_section_bytes +Reset internal state for a producer instance. +.It Fn dwarf_transform_to_disk_form +Prepare byte streams for writing out. +.El +.It Macros +.Bl -tag -compact -width indent +.It Fn dwarf_def_macro +Add a macro definition. +.It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file +Record macro file related information. +.It Fn dwarf_undef_macro +Note the removal of a macro definition. +.It Fn dwarf_vendor_ext +Enables storing macro information as specified in the DWARF standard. +.El +.It Symbols, Expressions, Addresses and Offsets +.Bl -tag -compact -width indent +.It Fn dwarf_add_arange , Fn dwarf_add_arange_b +Add address range information. +.It Fn dwarf_add_directory_decl +Add information about an include directory to a producer instance. +.It Fn dwarf_add_fde_inst +Add an operation to a frame descriptor entry. +.It Fn dwarf_add_file_decl +Add information about a source file to a producer instance. +.It Fn dwarf_add_frame_cie +Add call information to a frame descriptor. +.It Fn dwarf_add_frame_fde , Fn dwarf_add_frame_fde_b +Link a frame descriptor to a producer instance. +.It Fn dwarf_add_funcname +Add information about a function to a producer instance. +.It Fn dwarf_add_line_entry +Record mapping information between machine addresses and a source line. +.It Fn dwarf_add_expr_addr , Fn dwarf_add_expr_addr_b +Add a +.Dv DW_OP_addr +opcode to a location expression. +.It Fn dwarf_add_expr_gen +Add an operator to a location expression. +.It Fn dwarf_add_pubname +Add information about a global name to a producer instance. +.It Fn dwarf_add_typename +Add information about a type to a producer instance. +.It Fn dwarf_add_varname +Add information about a static variable to a producer instance. +.It Fn dwarf_add_weakname +Add information about a weak symbol to a producer instance. +.It Fn dwarf_expr_current_offset +Retrieve the current size of a location expression. +.It Fn dwarf_expr_into_block +Convert a location expression into a byte stream. +.It Fn dwarf_fde_cfa_offset +Append a +.Dv DW_CFA_offset +operation to a frame descriptor. +.It Fn dwarf_lne_end_sequence , Fn dwarf_lne_set_address +Note address ranges for source lines. +.It Fn dwarf_new_expr +Allocate a location expression descriptor. +.It Fn dwarf_new_fde +Allocate a frame descriptor. +.El +.It Miscellaneous +The function +.Fn dwarf_producer_set_isa +sets the instruction set architecture for the producer instance. +.El +.Sh COMPATIBILITY +This implementation is believed to be source compatible with the +SGI/GNU DWARF(3) library, version 20110113. +.Pp +Known differences with the SGI/GNU library include: +.Bl -bullet -compact +.It +The memory management scheme used differs, in a backward-compatible +way. +See +.Sx Memory Management +above, for coding guidelines for portable applications. +.It +There is provision for setting a library-wide error handler in +addition to the per-debug context handlers supported by the SGI/GNU +API, see the subsection +.Sx Error Handling +above. +.El +.Ss Extensions +The following APIs are extensions specific to this implementation: +.Bl -bullet -compact +.It +.Fn dwarf_attroffset +.It +.Fn dwarf_next_types_section +.It +.Fn dwarf_producer_set_isa +.El +.Sh SEE ALSO +.Xr elf 3 +.Sh STANDARDS +The DWARF standard is defined by +.Rs +.%T "The DWARF Debugging Information Format" +.%V "Version 4" +.%O "http://www.dwarfstd.org/" +.Re +.Sh HISTORY +The DWARF(3) API originated at Silicon Graphics Inc. +.Pp +A BSD-licensed implementation of a subset of the API was written by +.An John Birrell Aq Mt jb@FreeBSD.org +for the +.Fx +project. +The implementation was subsequently revised and completed by +.An Kai Wang Aq Mt kaiwang27@users.sourceforge.net . +.Pp +Manual pages for this implementation were written by +.An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net +and +.An Kai Wang Aq Mt kaiwang27@users.sourceforge.net . diff --git a/static/netbsd/man3/dwarf_add_AT_comp_dir.3 b/static/netbsd/man3/dwarf_add_AT_comp_dir.3 new file mode 100644 index 00000000..054c410f --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_comp_dir.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_add_AT_comp_dir.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_comp_dir.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_COMP_DIR 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_comp_dir +.Nd create and attach a DW_AT_comp_dir attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_comp_dir +.Fa "Dwarf_P_Die die" +.Fa "char *dir" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_comp_dir +creates a +.Dv DW_AT_comp_dir +attribute descriptor and attaches it to the debugging information +entry referenced by argument +.Fa die . +The created attribute will have DWARF form +.Dv DW_FORM_strp . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa dir +should point to a NUL-terminated string which will become the value of +the created attribute. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_comp_dir +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_comp_dir +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_comp_dir +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa die +or +.Fa dir +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_const_value_string 3 , +.Xr dwarf_add_AT_name 3 , +.Xr dwarf_add_AT_producer 3 , +.Xr dwarf_add_AT_string 3 , +.Xr dwarf_new_die 3 diff --git a/static/netbsd/man3/dwarf_add_AT_const_value_string.3 b/static/netbsd/man3/dwarf_add_AT_const_value_string.3 new file mode 100644 index 00000000..322c7c86 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_const_value_string.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: dwarf_add_AT_const_value_string.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_const_value_string.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_CONST_VALUE_STRING 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_const_value_signedint , +.Nm dwarf_add_AT_const_value_string , +.Nm dwarf_add_AT_const_value_unsignedint +.Nd create and attach a DW_AT_const_value attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_const_value_signedint +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Signed value" +.Fa "Dwarf_Error *err" +.Fc +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_const_value_string +.Fa "Dwarf_P_Die die" +.Fa "char *str" +.Fa "Dwarf_Error *err" +.Fc +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_const_value_unsignedint +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Unsigned value" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions create a +.Dv DW_AT_const_value +attribute descriptor and attach it to the debugging information entry +referenced by argument +.Fa die . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Function +.Fn dwarf_add_AT_const_value_signedint +creates a +.Dv DW_AT_const_value +attribute descriptor containing the signed value specified by argument +.Fa value . +The created attribute descriptor will have DWARF form +.Dv DW_FORM_sdata . +.Pp +Function +.Fn dwarf_add_AT_const_value_unsignedint +creates a +.Dv DW_AT_const_value +attribute descriptor containing the unsigned value specified by +argument +.Fa value . +The created attribute descriptor will have DWARF form +.Dv DW_FORM_udata . +.Pp +Function +.Fn dwarf_add_AT_const_value_string +creates a +.Dv DW_AT_const_value +attribute descriptor containing the string pointed to by the +NUL-terminated argument +.Fa str . +The created attribute descriptor will have DWARF form +.Dv DW_FORM_strp . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used by these functions to store error +information in case of an error. +.Sh RETURN VALUES +On success, these functions return the created attribute descriptor. +In case of an error, these functions return +.Dv DW_DLV_BADADDR +and set the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa die +or +.Fa str +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during execution. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_name 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_string 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 diff --git a/static/netbsd/man3/dwarf_add_AT_dataref.3 b/static/netbsd/man3/dwarf_add_AT_dataref.3 new file mode 100644 index 00000000..c851baa0 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_dataref.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: dwarf_add_AT_dataref.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_dataref.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_DATAREF 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_dataref +.Nd create an attribute descriptor for a relocatable address +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Attribute" +.Fo dwarf_add_AT_dataref +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned pc_value" +.Fa "Dwarf_Unsigned sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_dataref +creates an attribute descriptor for a relocatable address and attaches +it to the debugging information entry referenced by argument +.Fa die . +.Pp +If flag +.Dv DW_DLC_SIZE_64 +is set, the address value will be 8 bytes in size and of the DWARF form +.Dv DW_FORM_data8 . +Otherwise, the address value will be 4 bytes in size and of the DWARF form +.Dv DW_FORM_data4 . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +specifies the attribute code of the created attribute descriptor. +.Pp +Argument +.Fa pc_value +specifies the value of the relocatable address. +.Pp +Argument +.Fa sym_index +specifies the ELF symbol index of the symbol to be used for +relocation. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case +of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_dataref +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_dataref +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_dataref +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_ref_address 3 , +.Xr dwarf_add_AT_reference 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_flag.3 b/static/netbsd/man3/dwarf_add_AT_flag.3 new file mode 100644 index 00000000..ca24e235 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_flag.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: dwarf_add_AT_flag.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_flag.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_FLAG 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_flag +.Nd create and attach a flag attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_flag +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Small flag" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_flag +creates an attribute descriptor belonging to the +.Sq flag +class, and attaches it to the debugging information entry referenced +by argument +.Fa die . +The created attribute descriptor will have DWARF form +.Dv DW_FORM_flag . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +should specify the attribute code for the new attribute descriptor. +.Pp +Argument +.Fa flag +should specify the value of the new attribute descriptor. +A zero value is treated as +.Sq false +and a non-zero value as +.Sq true . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_flag +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_flag +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_flag +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_location_expr.3 b/static/netbsd/man3/dwarf_add_AT_location_expr.3 new file mode 100644 index 00000000..9e42ae6b --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_location_expr.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: dwarf_add_AT_location_expr.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_location_expr.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 5, 2011 +.Dt DWARF_ADD_AT_LOCATION_EXPR 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_location_expr +.Nd create an attribute descriptor for a location expression +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Attribute" +.Fo dwarf_add_AT_location_expr +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_P_Expr loc_expr" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_location_expr +creates an attribute descriptor for a location expression and attaches +it to the debugging information entry referenced by argument +.Fa die . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +specifies the attribute code of the created attribute descriptor. +.Pp +Argument +.Fa loc_expr +should reference a location expression descriptor allocated using +.Xr dwarf_new_expr 3 . +.Pp +The attribute created by function +.Fn dwarf_add_AT_location_expr +will have one of the DWARF forms +.Dv DW_FORM_block , +.Dv DW_FORM_block1 , +.Dv DW_FORM_block2 +or +.Dv DW_FORM_block4 , +depending on the size of the byte stream generated by the location +expression descriptor referenced by argument +.Fa loc_expr . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used by to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_location_expr +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_location_expr +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_location_expr +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa loc_expr +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_new_expr 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_name.3 b/static/netbsd/man3/dwarf_add_AT_name.3 new file mode 100644 index 00000000..0c138359 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_name.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_add_AT_name.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_name.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_NAME 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_name +.Nd create and attach a DW_AT_name attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_name +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_name +creates a +.Dv DW_AT_name +attribute descriptor and attaches it to the debugging information +entry referenced by argument +.Fa die . +The created attribute will have DWARF form +.Dv DW_FORM_strp . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa name +should point to a NUL-terminated string which will become the value of +the created attribute. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_name +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_name +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_name +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_comp_dir 3 , +.Xr dwarf_add_AT_const_value_string 3 , +.Xr dwarf_add_AT_producer 3 , +.Xr dwarf_add_AT_string 3 , +.Xr dwarf_new_die 3 diff --git a/static/netbsd/man3/dwarf_add_AT_producer.3 b/static/netbsd/man3/dwarf_add_AT_producer.3 new file mode 100644 index 00000000..8704013b --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_producer.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_add_AT_producer.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_producer.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_PRODUCER 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_producer +.Nd create and attach a DW_AT_producer attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_producer +.Fa "Dwarf_P_Die die" +.Fa "char *producer" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_producer +creates a +.Dv DW_AT_producer +attribute descriptor and attaches it to the debugging information +entry referenced by argument +.Fa die . +The created attribute will have DWARF form +.Dv DW_FORM_strp . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa producer +should point to a NUL-terminated string which will become the value of +the created attribute. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_producer +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_producer +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_producer +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa die +or +.Fa producer +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_comp_dir 3 , +.Xr dwarf_add_AT_const_value_string 3 , +.Xr dwarf_add_AT_name 3 , +.Xr dwarf_add_AT_string 3 , +.Xr dwarf_new_die 3 diff --git a/static/netbsd/man3/dwarf_add_AT_ref_address.3 b/static/netbsd/man3/dwarf_add_AT_ref_address.3 new file mode 100644 index 00000000..8a0bfedb --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_ref_address.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: dwarf_add_AT_ref_address.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_ref_address.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 7, 2011 +.Dt DWARF_ADD_AT_REF_ADDRESS 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_ref_address +.Nd create a reference class attribute descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Attribute" +.Fo dwarf_add_AT_ref_address +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned pc_value" +.Fa "Dwarf_Unsigned sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_ref_address +creates a +.Sq reference +class attribute descriptor containing a relocatable address value. +The created attribute will use DWARF form +.Dv DW_FORM_ref_addr . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +specifies the attribute code of the created attribute. +.Pp +Argument +.Fa pc_value +contains a relocatable address which will become the value of the +created attribute. +.Pp +Argument +.Fa sym_index +should specify the ELF symbol index of the symbol to be used when +relocating the address value. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_ref_address +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_ref_address +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_ref_address +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during execution. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_dataref 3 , +.Xr dwarf_add_AT_reference 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_reference.3 b/static/netbsd/man3/dwarf_add_AT_reference.3 new file mode 100644 index 00000000..bd3f8090 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_reference.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: dwarf_add_AT_reference.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_reference.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_REFERENCE 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_reference +.Nd create and attach an attribute that references another DIE +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Attribute" +.Fo dwarf_add_AT_reference +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_P_Die ref_die" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_reference +creates an attribute descriptor that references another debugging +information entry in the same compilation unit. +The attribute will be of DWARF form +.Dv DW_FORM_ref4 +or +.Dv DW_FORM_ref8 +depending on the target address size, and will contain the +section-relative offset of the referenced debugging information entry +as its value. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +should specify the attribute code of the created attribute descriptor. +.Pp +Argument +.Fa ref_die +should hold the debugging information entry descriptor that +the attribute should refer to. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_reference +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_reference +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_reference +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa ref_die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_dataref 3 , +.Xr dwarf_add_AT_ref_address 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_signed_const.3 b/static/netbsd/man3/dwarf_add_AT_signed_const.3 new file mode 100644 index 00000000..76c480da --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_signed_const.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: dwarf_add_AT_signed_const.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_signed_const.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_SIGNED_CONST 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_signed_const , +.Nm dwarf_add_AT_unsigned_const +.Nd create and attach constant class attributes +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_signed_const +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Signed value" +.Fa "Dwarf_Error *err" +.Fc +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_unsigned_const +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned value" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions create attribute descriptors belonging to the +.Sq constant +class +and attach them to the debugging information entry referenced by +argument +.Fa die . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +specifies the attribute code of the created attribute descriptor. +.Pp +Function +.Fn dwarf_add_AT_signed_const +creates an attribute descriptor with the signed value specified in +argument +.Fa value . +.Pp +Function +.Fn dwarf_add_AT_unsigned_const +creates an attribute descriptor with the unsigned value specified in +argument +.Fa value . +.Pp +The attribute created by these function will have one of the +DWARF forms +.Dv DW_FORM_data1 , +.Dv DW_FORM_data2 , +.Dv DW_FORM_data4 +or +.Dv DW_FORM_data8 , +depending on the size of the value specified in argument +.Fa value . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used by these functions to store error +information in case of an error. +.Sh RETURN VALUES +On success, these functions return the created attribute descriptor. +In case of an error, these functions return +.Dv DW_DLV_BADADDR +and set the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during execution. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_const_value_signedint 3 , +.Xr dwarf_add_AT_const_value_unsignedint 3 , +.Xr dwarf_add_AT_dataref 3 , +.Xr dwarf_add_AT_ref_address 3 , +.Xr dwarf_add_AT_targ_address_b 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_string.3 b/static/netbsd/man3/dwarf_add_AT_string.3 new file mode 100644 index 00000000..3618ea81 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_string.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: dwarf_add_AT_string.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_string.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_STRING 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_string +.Nd create and attach a string class attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_string +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "char *str" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_string +creates an attribute descriptor belonging to the +.Sq string +class and attaches it to the debugging information entry referenced by +argument +.Fa die . +The created attribute descriptor will have DWARF form +.Dv DW_FORM_strp . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +should specify the attribute code for the created attribute +descriptor. +.Pp +Argument +.Fa str +should hold a pointer to a NUL-terminated string which will become the +value of the created attribute descriptor. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_AT_string +returns the created attribute descriptor. +In case of an error, function +.Fn dwarf_add_AT_string +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_AT_string +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa str +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_const_value_string 3 , +.Xr dwarf_add_AT_name 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_AT_targ_address.3 b/static/netbsd/man3/dwarf_add_AT_targ_address.3 new file mode 100644 index 00000000..b2dcde54 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_AT_targ_address.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: dwarf_add_AT_targ_address.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_AT_targ_address.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_ADD_AT_TARG_ADDRESS 3 +.Os +.Sh NAME +.Nm dwarf_add_AT_targ_address , +.Nm dwarf_add_AT_targ_address_b +.Nd create and attach address class attributes +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_targ_address +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned pc_value" +.Fa "Dwarf_Signed sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Ft Dwarf_P_Attribute +.Fo dwarf_add_AT_targ_address_b +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned pc_value" +.Fa "Dwarf_Unsigned sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_AT_targ_address_b +creates an attribute descriptor belonging to the +.Sq address +class and attaches it to the debugging information entry referenced by +argument +.Fa die . +.Pp +The created attribute descriptor will have DWARF form +.Dv DW_FORM_addr . +If flag +.Dv DW_DLC_SIZE_64 +is set on the producer instance, the attribute value will be 8 bytes +in size. +Otherwise the attribute value will be 4 bytes in size. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +should reference a debugging information entry allocated using +.Xr dwarf_new_die 3 . +.Pp +Argument +.Fa attr +should specify the attribute code of the created attribute descriptor. +.Pp +Argument +.Fa pc_value +should hold a relocatable address value which will become the value of +the created attribute descriptor. +.Pp +Argument +.Fa sym_index +should specify the ELF symbol index of the symbol to be used for +relocating the address value. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_add_AT_targ_address +is deprecated. +It is similar to function +.Fn dwarf_add_AT_targ_address_b +except that it cannot handle all possible symbol index values. +.Sh RETURN VALUES +On success, these functions return the created attribute descriptor. +In case of an error, these functions return +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during execution. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_const_value_unsignedint 3 , +.Xr dwarf_add_AT_dataref 3 , +.Xr dwarf_add_AT_ref_address 3 , +.Xr dwarf_add_AT_signed_const 3 , +.Xr dwarf_add_AT_unsigned_const 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_arange.3 b/static/netbsd/man3/dwarf_add_arange.3 new file mode 100644 index 00000000..eb262207 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_arange.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: dwarf_add_arange.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_arange.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 18, 2011 +.Dt DWARF_ADD_ARANGE 3 +.Os +.Sh NAME +.Nm dwarf_add_arange , +.Nm dwarf_add_arange_b +.Nd add address range information to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_arange +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Addr start" +.Fa "Dwarf_Unsigned length" +.Fa "Dwarf_Signed symbol_index" +.Fa "Dwarf_Error *err" +.Fc +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_arange_b +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Addr start" +.Fa "Dwarf_Unsigned length" +.Fa "Dwarf_Unsigned symbol_index" +.Fa "Dwarf_Unsigned end_symbol_index" +.Fa "Dwarf_Addr offset_from_end_symbol" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_arange_b +adds an address range entry to a producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa start +specifies the relocatable start address of the address range. +.Pp +Argument +.Fa length +specifies the length of the address range. +.Pp +Argument +.Fa symbol_index +specifies the ELF symbol index of the first symbol to be used for +relocation. +.Pp +Argument +.Fa end_symbol_index +specifies the ELF symbol index of the second symbol to be used for +relocation. +.Bl -bullet +.It +If argument +.Fa end_symbol_index +is not 0, the +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag should have been set on the DWARF producer instance. +The address value specified by argument +.Fa start +will be treated as an offset value from the first symbol, +and the argument +.Fa offset_from_end_symbol +should hold an offset value from the second symbol. +Application code can retrieve the relocation entries for the +symbol pair by calling function +.Xr dwarf_get_relocation_info 3 . +The relocation entry for the first symbol will have type +.Dv dwarf_drt_first_of_length_pair +and the relocation entry for the second symbol will have type +.Dv dwarf_drt_second_of_length_pair . +.It +If argument +.Fa end_symbol_index +is 0, argument +.Fa offset_from_end_symbol +will be ignored and only one symbol is used for relocation. +.El +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_add_arange +is deprecated. +It is similar to function +.Fn dwarf_add_arange_b +except that it cannot handle all possible symbol index values +and supports only one relocation symbol. +.Sh RETURN VALUES +On success, these functions return a non-zero value. +In case of an error, these functions return 0 and set +the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa end_symbol_index +was non-zero, but the flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was not set on the producer instance. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_relocation_info 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_die_to_debug.3 b/static/netbsd/man3/dwarf_add_die_to_debug.3 new file mode 100644 index 00000000..78bae96f --- /dev/null +++ b/static/netbsd/man3/dwarf_add_die_to_debug.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: dwarf_add_die_to_debug.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_die_to_debug.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd August 21, 2011 +.Dt DWARF_ADD_DIE_TO_DEBUG 3 +.Os +.Sh NAME +.Nm dwarf_add_die_to_debug +.Nd set the root debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Unsigned +.Fo dwarf_add_die_to_debug +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die first_die" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_die_to_debug +sets the root debugging information entry of a DWARF producer +instance. +All debugging information entries linked to the root entry will also +be added to the producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa first_die +should hold the debugging information entry which will become +the root DIE. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_die_to_debug +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_add_die_to_debug +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_die_to_debug +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa first_die +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_die_link 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_directory_decl.3 b/static/netbsd/man3/dwarf_add_directory_decl.3 new file mode 100644 index 00000000..1b81b42a --- /dev/null +++ b/static/netbsd/man3/dwarf_add_directory_decl.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: dwarf_add_directory_decl.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_directory_decl.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 17, 2011 +.Dt DWARF_ADD_DIRECTORY_DECL 3 +.Os +.Sh NAME +.Nm dwarf_add_directory_decl +.Nd add a directory name to a producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_directory_decl +.Fa "Dwarf_P_Debug dbg" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_directory_decl +adds a source directory name to a producer instance and returns the +index value generated for the directory name. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa name +should point a NUL-terminated string containing the name of +the directory. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_directory_decl +returns the index value generated for the directory. +In case of an error, function +.Fn dwarf_add_directory_decl +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_directory_decl +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa dbg +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_file_decl 3 , +.Xr dwarf_add_line_entry 3 , +.Xr dwarf_lne_end_sequence 3 , +.Xr dwarf_lne_set_address 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_expr_addr.3 b/static/netbsd/man3/dwarf_add_expr_addr.3 new file mode 100644 index 00000000..39a4e420 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_expr_addr.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: dwarf_add_expr_addr.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_expr_addr.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 9, 2011 +.Dt DWARF_ADD_EXPR_ADDR 3 +.Os +.Sh NAME +.Nm dwarf_add_expr_addr , +.Nm dwarf_add_expr_addr_b +.Nd add a DW_OP_addr location expression +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_expr_addr +.Fa "Dwarf_P_Expr expr" +.Fa "Dwarf_Unsigned address" +.Fa "Dwarf_Signed sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_expr_addr_b +.Fa "Dwarf_P_Expr expr" +.Fa "Dwarf_Unsigned address" +.Fa "Dwarf_Unsigned sym_index" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_expr_addr_b +adds a +.Dv DW_OP_addr +location expression to the location expression descriptor referenced +by argument +.Fa expr . +.Pp +Argument +.Fa expr +should reference a location expression descriptor allocated using +the function +.Xr dwarf_new_expr 3 . +.Pp +Argument +.Fa address +specifies the operand, a relocatable address value. +.Pp +Argument +.Fa sym_index +specifies the ELF symbol index of the symbol to be used for +relocation. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_add_expr_addr +is deprecated. +It is similar to function +.Fn dwarf_add_expr_addr_b +except that it cannot handle all possible symbol index values. +.Sh RETURN VALUES +On success, these functions return the size in bytes of the location +expression byte stream generated. +In case of an error, these functions return +.Dv DW_DLV_NOCOUNT +and set the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa expr +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_location_expr 3 , +.Xr dwarf_add_expr_gen 3 , +.Xr dwarf_expr_current_offset 3 , +.Xr dwarf_expr_into_block 3 , +.Xr dwarf_new_expr 3 diff --git a/static/netbsd/man3/dwarf_add_expr_gen.3 b/static/netbsd/man3/dwarf_add_expr_gen.3 new file mode 100644 index 00000000..3cd6e1ec --- /dev/null +++ b/static/netbsd/man3/dwarf_add_expr_gen.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: dwarf_add_expr_gen.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_expr_gen.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 9, 2011 +.Dt DWARF_ADD_EXPR_GEN 3 +.Os +.Sh NAME +.Nm dwarf_add_expr_gen +.Nd add an operator to a location expression descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_expr_gen +.Fa "Dwarf_P_Expr expr" +.Fa "Dwarf_Small opcode" +.Fa "Dwarf_Unsigned val1" +.Fa "Dwarf_Unsigned val2" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_expr_gen +adds a location expression operator to the location expression +descriptor referenced by argument +.Fa expr . +.Pp +Argument +.Fa expr +should reference a location expression descriptor allocated using +the function +.Xr dwarf_new_expr 3 . +.Pp +Argument +.Fa opcode +specifies the operation code of the location expression operator. +Valid values for this argument are those denoted by the +.Dv DW_OP_ Ns * +constants defined in +.In libdwarf.h . +.Pp +To generate a +.Dv DW_OP_addr +operation, application code should instead use +.Xr dwarf_add_expr_addr_b 3 . +.Pp +Argument +.Fa val1 +specifies the first operand of the location expression operator. +.Pp +Argument +.Fa val2 +specifies the second operand of the location expression operator. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_expr_gen +returns the size in bytes of the location expression byte stream +generated. +In case of an error, function +.Fn dwarf_add_expr_gen +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_expr_gen +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_LOC_EXPR_BAD" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa expr +was +.Dv NULL . +.It Bq Er DW_DLE_LOC_EXPR_BAD +The operation code specified in argument +.Fa opcode +was invalid. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_location_expr 3 , +.Xr dwarf_add_expr_addr 3 , +.Xr dwarf_add_expr_addr_b 3 , +.Xr dwarf_expr_current_offset 3 , +.Xr dwarf_expr_into_block 3 , +.Xr dwarf_new_expr 3 diff --git a/static/netbsd/man3/dwarf_add_fde_inst.3 b/static/netbsd/man3/dwarf_add_fde_inst.3 new file mode 100644 index 00000000..8deedd10 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_fde_inst.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: dwarf_add_fde_inst.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_fde_inst.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 26, 2011 +.Dt DWARF_ADD_FDE_INST 3 +.Os +.Sh NAME +.Nm dwarf_add_fde_inst +.Nd add a call frame instruction to a DWARF frame descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Fde" +.Fo dwarf_add_fde_inst +.Fa "Dwarf_P_Fde fde" +.Fa "Dwarf_Small op" +.Fa "Dwarf_Unsigned val1" +.Fa "Dwarf_Unsigned val2" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_fde_inst +adds a call frame instruction to the DWARF frame descriptor +referenced by argument +.Fa fde . +.Pp +Argument +.Fa fde +should reference a frame descriptor allocated using +.Xr dwarf_new_fde 3 . +.Pp +Argument +.Fa op +specifies the operator for the frame instruction. +The DWARF standard defines the set of legal values for this argument. +.Pp +Argument +.Fa val1 +specifies the first operand of the frame instruction. +.Pp +Argument +.Fa val2 +specifies the second operand of the frame instruction. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_fde_inst +returns the frame descriptor given in argument +.Fa fde . +In case of an error, function +.Fn dwarf_add_fde_inst +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_fde_inst +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa fde +was +.Dv NULL . +.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR +The frame instruction operator specified in argument +.Fa op +was invalid. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_frame_cie 3 , +.Xr dwarf_add_frame_fde 3 , +.Xr dwarf_add_frame_fde_b 3 , +.Xr dwarf_fde_cfa_offset 3 , +.Xr dwarf_new_fde 3 +.Rs +.%T "The DWARF Debugging Information Format" +.%V "Version 4" +.%O "http://www.dwarfstd.org/" +.Re diff --git a/static/netbsd/man3/dwarf_add_file_decl.3 b/static/netbsd/man3/dwarf_add_file_decl.3 new file mode 100644 index 00000000..dae42347 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_file_decl.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: dwarf_add_file_decl.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_file_decl.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 17, 2011 +.Dt DWARF_ADD_FILE_DECL 3 +.Os +.Sh NAME +.Nm dwarf_add_file_decl +.Nd add a source file entry to a producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_file_decl +.Fa "Dwarf_P_Debug dbg" +.Fa "char *name" +.Fa "Dwarf_Unsigned dirndx" +.Fa "Dwarf_Unsigned mtime" +.Fa "Dwarf_Unsigned size" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_file_decl +adds a source file entry to a producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name of +the source file. +.Pp +If the file name in argument +.Fa name +is not a fully qualified pathname, argument +.Fa dirndx +should specify the index of the directory where the source file resides. +Otherwise, argument +.Fa dirndx +should be 0. +Valid directory indices are those returned by the function +.Xr dwarf_add_directory_decl 3 . +.Pp +Argument +.Fa mtime +specifies the time when the file was last modified. +.Pp +Argument +.Fa size +specifies the size of the file in bytes. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_file_decl +returns the index value generated for the source file. +In case of an error, function +.Fn dwarf_add_file_decl +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_file_decl +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either arguments +.Fa dbg +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The length of the NUL-teminated string pointed to by argument +.Fa name +was 0. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_directory_decl 3 , +.Xr dwarf_add_line_entry 3 , +.Xr dwarf_lne_end_sequence 3 , +.Xr dwarf_lne_set_address 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_frame_cie.3 b/static/netbsd/man3/dwarf_add_frame_cie.3 new file mode 100644 index 00000000..f8508bb2 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_frame_cie.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: dwarf_add_frame_cie.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_frame_cie.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 26, 2011 +.Dt DWARF_ADD_FRAME_CIE 3 +.Os +.Sh NAME +.Nm dwarf_add_frame_cie +.Nd add a call frame common information entry to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_frame_cie +.Fa "Dwarf_P_Debug dbg" +.Fa "char *augmenter" +.Fa "Dwarf_Small caf" +.Fa "Dwarf_Small daf" +.Fa "Dwarf_Small ra" +.Fa "Dwarf_Ptr initinst" +.Fa "Dwarf_Unsigned initlen" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_frame_cie +adds a DWARF call frame common information entry (CIE) to a producer +instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa augmenter +should point to a NUL-terminated augmentation string for the common +information entry. +.Pp +Argument +.Fa caf +specifies the code alignment factor. +.Pp +Argument +.Fa daf +specifies the data alignment factor. +.Pp +Argument +.Fa ra +specifies the column number used for the return address register. +.Pp +Argument +.Fa initinst +should point to a byte stream containing the initial instructions +for the common information entry. +.Pp +Argument +.Fa initlen +should hold the length in bytes of the byte stream pointed to by +argument +.Fa initinst . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_frame_cie +returns the index value of the created common information entry. +In case of an error, function +.Fn dwarf_add_frame_cie +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_frame_cie +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_fde 3 , +.Xr dwarf_add_frame_fde_b 3 , +.Xr dwarf_fde_cfa_offset 3 , +.Xr dwarf_new_fde 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_frame_fde.3 b/static/netbsd/man3/dwarf_add_frame_fde.3 new file mode 100644 index 00000000..ce8ef990 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_frame_fde.3 @@ -0,0 +1,205 @@ +.\" $NetBSD: dwarf_add_frame_fde.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_frame_fde.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 26, 2011 +.Dt DWARF_ADD_FRAME_FDE 3 +.Os +.Sh NAME +.Nm dwarf_add_frame_fde +.Nd add a call frame descriptor to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_frame_fde +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Fde fde" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Unsigned cie" +.Fa "Dwarf_Addr virt_addr" +.Fa "Dwarf_Unsigned code_len" +.Fa "Dwarf_Unsigned symbol_index" +.Fa "Dwarf_Error *err" +.Fc +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_frame_fde_b +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Fde fde" +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_Unsigned cie" +.Fa "Dwarf_Addr virt_addr" +.Fa "Dwarf_Unsigned code_len" +.Fa "Dwarf_Unsigned symbol_index" +.Fa "Dwarf_Unsigned end_symbol_index" +.Fa "Dwarf_Addr offset_from_end_sym" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_frame_fde_b +adds the call frame descriptor referenced by argument +.Fa fde +to a producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa fde +should reference a frame descriptor allocated using +.Xr dwarf_new_fde 3 . +.Pp +Argument +.Fa die +is ignored by this implementation of the +.Lb libdwarf . +.Pp +Argument +.Fa cie +specifies the index of call frame common information entry for +the frame descriptor. +Valid indices are those returned by the function +.Xr dwarf_add_frame_cie 3 . +.Pp +Argument +.Fa symbol_index +specifies the ELF symbol index of the first symbol to be used for +relocation. +.Pp +The meaning of the arguments +.Fa virt_addr , +.Fa code_len +and +.Fa offset_from_end_sym +depend on the value of argument +.Fa end_symbol_index : +.Bl -bullet +.It +If the argument +.Fa end_symbol_index +is zero, the argument +.Fa virt_addr +specifies the relocatable address of the start of the function +associated with the frame descriptor, the argument +.Fa code_len +specifies the size in bytes of the machine instructions for this +function, the argument +.Fa symbol_index +specifies the ELF symbol to be used for relocating the address in +argument +.Fa virt_addr , +and the argument +.Fa offset_from_end_symbol +is ignored. +.It +If the argument +.Fa end_symbol_index +is non-zero, it specifies the ELF symbol index of the second symbol to +be used for relocation. +In this case, the argument +.Fa virt_addr +specifies an offset from the relocatable symbol specified by argument +.Fa symbol_index , +the argument +.Fa offset_from_end_symbol +should specify an offset from the symbol named by the argument +.Fa end_symbol_index , +and the argument +.Fa code_len +will be ignored. +The +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag should also have been set on the DWARF producer instance. +.Pp +Application code can retrieve the relocation entries for the symbol +pair by calling function +.Xr dwarf_get_relocation_info 3 . +The relocation entry for the first symbol will have type +.Dv dwarf_drt_first_of_length_pair +and the relocation entry for the second symbol will have type +.Dv dwarf_drt_second_of_length_pair . +.El +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_add_frame_fde +is similar to function +.Fn dwarf_add_frame_fde_b +except that it supports only one relocation symbol. +.Sh RETURN VALUES +On success, these functions return the index value for +the added frame descriptor. +In case of an error, these functions return +.Dv DW_DLV_NOCOUNT +and set the argument +.Fa err . +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg +or +.Fa fde +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The frame descriptor referenced by argument +.Fa fde +did not belong to the producer instance referenced by argument +.Fa dbg . +.It Bq Er DW_DLE_ARGUMENT +The common information entry index specified by argument +.Fa cie +was invalid. +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa end_symbol_index +was non-zero, but the flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was not set on the producer instance. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_cie 3 , +.Xr dwarf_fde_cfa_offset 3 , +.Xr dwarf_get_relocation_info 3 , +.Xr dwarf_new_fde 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_funcname.3 b/static/netbsd/man3/dwarf_add_funcname.3 new file mode 100644 index 00000000..5a845965 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_funcname.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: dwarf_add_funcname.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_funcname.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_ADD_FUNCNAME 3 +.Os +.Sh NAME +.Nm dwarf_add_funcname +.Nd add information about a static function to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_funcname +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_funcname +adds information about a static function to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +specifies the debugging information entry associated with the static +function. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the static function. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_funcname +returns a non-zero value. +In case of an error, function +.Fn dwarf_add_funcname +returns 0 and sets +the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_funcname +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_pubname 3 , +.Xr dwarf_add_typename 3 , +.Xr dwarf_add_varname 3 , +.Xr dwarf_add_weakname 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_line_entry.3 b/static/netbsd/man3/dwarf_add_line_entry.3 new file mode 100644 index 00000000..848f7ed2 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_line_entry.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: dwarf_add_line_entry.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_line_entry.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd June 30, 2013 +.Dt DWARF_ADD_LINE_ENTRY 3 +.Os +.Sh NAME +.Nm dwarf_add_line_entry +.Nd add a line number information entry to a producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_line_entry +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned filendx" +.Fa "Dwarf_Addr off" +.Fa "Dwarf_Unsigned lineno" +.Fa "Dwarf_Signed column" +.Fa "Dwarf_Bool is_stmt" +.Fa "Dwarf_Bool basic_block" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_line_entry +adds a line number information entry to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa filendx +specifies the index of the source file that contains the source line +in question. +Valid source file indices are those returned by the function +.Xr dwarf_add_file_decl 3 . +.Pp +Argument +.Fa off +specifies a relocatable program address. +The ELF symbol to be used +for relocation is set by a prior call to the function +.Xr dwarf_lne_set_address 3 . +.Pp +Argument +.Fa lineno +specifies the line number of the source line. +.Pp +Argument +.Fa column +specifies the column number within the source line. +.Pp +If the argument +.Fa is_stmt +is set to true, it indicates that the instruction at the address +specified by argument +.Fa off +is a recommended breakpoint location, i.e., the first instruction in +the instruction sequence generated by the source line. +.Pp +If the argument +.Fa basic_block +is set to true, it indicates that the instruction at the address +specified by argument +.Fa off +is the first instruction of a basic block. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_line_entry +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_add_line_entry +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh EXAMPLES +To add line number information to the producer instance, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Error de; +Dwarf_Unsigned dir, filendx; + +/* ... assume dbg refers to a DWARF producer instance ... */ + +dir = dwarf_add_directory_decl(dbg, "/home/foo", &de); +if (dir == DW_DLV_NOCOUNT) + errx(EXIT_FAILURE, "dwarf_add_directory_decl failed: %s", + dwarf_errmsg(-1)); + +filendx = dwarf_add_file_decl(dbg, "bar.c", dir, 0, 1234, &de); +if (filendx == DW_DLV_NOCOUNT) + errx(EXIT_FAILURE, "dwarf_add_file_decl failed: %s", + dwarf_errmsg(-1)); + +if (dwarf_lne_set_address(dbg, 0x4012b0, 12, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_lne_set_address failed: %s", + dwarf_errmsg(-1)); + +if (dwarf_add_line_entry(dbg, filendx, 10, 258, 0, 1, 1, &de) != + DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_add_line_entry failed: %s", + dwarf_errmsg(-1)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_add_line_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The function +.Xr dwarf_lne_set_address 3 +was not called before calling this function. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_directory_decl 3 , +.Xr dwarf_add_file_decl 3 , +.Xr dwarf_lne_end_sequence 3 , +.Xr dwarf_lne_set_address 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_pubname.3 b/static/netbsd/man3/dwarf_add_pubname.3 new file mode 100644 index 00000000..e7698bb4 --- /dev/null +++ b/static/netbsd/man3/dwarf_add_pubname.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: dwarf_add_pubname.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_pubname.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_ADD_PUBNAME 3 +.Os +.Sh NAME +.Nm dwarf_add_pubname +.Nd add information about a global object to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_pubname +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_pubname +adds information about a global object to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +specifies the debugging information entry associated with the global +object. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the global object. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_pubname +returns a non-zero value. +In case of an error, function +.Fn dwarf_add_pubname +returns 0 and sets +the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_pubname +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_funcname 3 , +.Xr dwarf_add_typename 3 , +.Xr dwarf_add_varname 3 , +.Xr dwarf_add_weakname 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_typename.3 b/static/netbsd/man3/dwarf_add_typename.3 new file mode 100644 index 00000000..a30889bd --- /dev/null +++ b/static/netbsd/man3/dwarf_add_typename.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: dwarf_add_typename.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_typename.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_ADD_TYPENAME 3 +.Os +.Sh NAME +.Nm dwarf_add_typename +.Nd add information about a user-defined type to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_typename +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_typename +adds information about a user-defined type to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +specifies the debugging information entry associated with the +user-defined type. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the user-defined type. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_typename +returns a non-zero value. +In case of an error, function +.Fn dwarf_add_typename +returns 0 and sets +the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_typename +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_funcname 3 , +.Xr dwarf_add_pubname 3 , +.Xr dwarf_add_varname 3 , +.Xr dwarf_add_weakname 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_varname.3 b/static/netbsd/man3/dwarf_add_varname.3 new file mode 100644 index 00000000..441b137e --- /dev/null +++ b/static/netbsd/man3/dwarf_add_varname.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: dwarf_add_varname.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_varname.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_ADD_VARNAME 3 +.Os +.Sh NAME +.Nm dwarf_add_varname +.Nd add information about a static variable to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_varname +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_varname +adds information about a static variable to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +specifies the debugging information entry associated with the static +variable. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the static variable. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_varname +returns a non-zero value. +In case of an error, function +.Fn dwarf_add_varname +returns 0 and sets +the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_varname +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_funcname 3 , +.Xr dwarf_add_pubname 3 , +.Xr dwarf_add_typename 3 , +.Xr dwarf_add_weakname 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_add_weakname.3 b/static/netbsd/man3/dwarf_add_weakname.3 new file mode 100644 index 00000000..8bb74fba --- /dev/null +++ b/static/netbsd/man3/dwarf_add_weakname.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: dwarf_add_weakname.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_add_weakname.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_ADD_WEAKNAME 3 +.Os +.Sh NAME +.Nm dwarf_add_weakname +.Nd add information about a weak object to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_add_weakname +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_P_Die die" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_add_weakname +adds information about a weak object to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa die +specifies the debugging information entry associated with the weak +object. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the weak object. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_add_weakname +returns a non-zero value. +In case of an error, function +.Fn dwarf_add_weakname +returns 0 and sets +the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_add_weakname +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa die +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_funcname 3 , +.Xr dwarf_add_pubname 3 , +.Xr dwarf_add_typename 3 , +.Xr dwarf_add_varname 3 , +.Xr dwarf_new_die 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_attr.3 b/static/netbsd/man3/dwarf_attr.3 new file mode 100644 index 00000000..2d645b22 --- /dev/null +++ b/static/netbsd/man3/dwarf_attr.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: dwarf_attr.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_attr.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd April 8, 2010 +.Dt DWARF_ATTR 3 +.Os +.Sh NAME +.Nm dwarf_attr +.Nd retrieve an attribute descriptor associated with a DWARF debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_attr +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Attribute *atp" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_attr +retrieves the attribute descriptor for an attribute associated +with the DWARF debugging information entry descriptor in +argument +.Fa die . +.Pp +DWARF attribute descriptors are represented by value of the opaque +type +.Vt Dwarf_Attribute , +see +.Xr dwarf 3 . +.Pp +Argument +.Fa attr +names the desired DWARF attribute. +Legal values for argument +.Fa attr +are those denoted by the +.Dv DW_AT_* +constants in the DWARF specification. +.Pp +Argument +.Fa atp +points to a location into which the returned attribute descriptor +will be written. +The returned descriptor may then be passed to the form query functions in the +.Xr dwarf 3 +API set to access the data associated with the attribute. +.Pp +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_attr +returns +.Dv DW_DLV_OK +on success. +.Pp +If the debugging information entry descriptor denoted by argument +.Fa die +does not contain the named attribute, the function returns +.Dv DW_DLV_NO_ENTRY +and sets argument +.Fa err . +For other errors, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_attr +can fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa die +or +.Fa atp +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa die +had no attribute corresponding to the value +in argument +.Fa attr . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attrlist 3 , +.Xr dwarf_attroffset 3 , +.Xr dwarf_hasattr 3 , +.Xr dwarf_hasform 3 , +.Xr dwarf_whatattr 3 , +.Xr dwarf_whatform 3 diff --git a/static/netbsd/man3/dwarf_attrlist.3 b/static/netbsd/man3/dwarf_attrlist.3 new file mode 100644 index 00000000..0165cfb5 --- /dev/null +++ b/static/netbsd/man3/dwarf_attrlist.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: dwarf_attrlist.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_attrlist.3 3964 2022-03-13 21:41:26Z jkoshy +.\" +.Dd March 13, 2022 +.Dt DWARF_ATTRLIST 3 +.Os +.Sh NAME +.Nm dwarf_attrlist +.Nd retrieve DWARF attribute descriptors +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_attrlist +.Fa "Dwarf_Die die" +.Fa "Dwarf_Attribute **attrbuf" +.Fa "Dwarf_Signed *attrcount" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_attrlist +retrieves the DWARF attribute descriptors associated with a +debugging information entry descriptor in argument +.Fa die . +The descriptors are returned as an array of values of the opaque type +.Vt Dwarf_Attribute . +The data associated with each returned attribute descriptor may be +queried using the form query functions in the +.Xr dwarf 3 +API set. +.Pp +Argument +.Fa attrbuf +points to a location that will hold a pointer to the returned +array of DWARF attribute descriptors. +Argument +.Fa attrcount +points to a location that will hold the number of descriptors in +the returned array. +.Pp +If argument +.Fa err +is +.No non- Ns Dv NULL , +it is used to return an error descriptor in case of an error. +.Ss Memory Management +In the current implementation, the memory allocated for each DWARF +attribute descriptor and for the returned array of descriptors is +managed by the library and the application does not need to explicitly +free the returned pointers. +However, for compatibility with other implementations of the +.Xr dwarf 3 +API, the application is permitted to pass the pointers returned by to +the +.Fn dwarf_dealloc +function. +.Sh RETURN VALUES +Function +.Fn dwarf_attrlist +returns +.Dv DW_DLV_OK +on success. +.Pp +If the debugging information entry descriptor denoted by argument +.Fa die +does not contain any attribute, the function returns +.Dv DW_DLV_NO_ENTRY +and sets argument +.Fa err . +For other errors, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh EXAMPLES +To retrieve the attribute list for a DWARF debugging information +entry use: +.Bd -literal -offset indent +Dwarf_Die dw_die; +Dwarf_Error dw_e; +Dwarf_Unsigned dw_count; +Dwarf_Attribute *dw_attributes; +int error, i; + +\&... variable dw_die contains a reference to the DIE of interest ... + +/* Retrieve the attribute list from the DIE. */ +if ((error = dwarf_attrlist(dw_die, &dw_attributes, &dw_count, + &dw_e)) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_attrlist: %s", dwarf_errmsg(dw_e)); + +/* Process the attribute list. */ +for (i = 0; i < dw_count; ++i) { + /* Use the returned pointers in dw_attributes[i] here. */ +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_attrlist +can fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Arguments +.Fa die , +.Fa attrbuf , +or +.Fa attrcount +were +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa die +had no attributes. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_hasattr 3 , +.Xr dwarf_hasform 3 , +.Xr dwarf_whatattr 3 , +.Xr dwarf_whatform 3 diff --git a/static/netbsd/man3/dwarf_attroffset.3 b/static/netbsd/man3/dwarf_attroffset.3 new file mode 100644 index 00000000..4f4b9ac9 --- /dev/null +++ b/static/netbsd/man3/dwarf_attroffset.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: dwarf_attroffset.3,v 1.5 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_attroffset.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd December 20, 2014 +.Dt DWARF_ATTROFFSET 3 +.Os +.Sh NAME +.Nm dwarf_attroffset +.Nd retrieve the section-relative offset of an attribute descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_attroffset +.Fa "Dwarf_Attribute at" +.Fa "Dwarf_Off *ret_off" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_attroffset +retrieves the section-relative offset of the attribute descriptor +referenced by argument +.Fa at . +.Pp +Argument +.Fa ret_off +should point to a location that is to hold the returned +section-relative offset. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it is used to return an error descriptor in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_attroffset +returns +.Dv DW_DLV_OK . +.Pp +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh COMPATIBILITY +This function is an extension to the +.Xr DWARF 3 +API. +.Sh ERRORS +The +.Fn dwarf_attroffset +function may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa at +or +.Fa ret_off +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 diff --git a/static/netbsd/man3/dwarf_attrval_signed.3 b/static/netbsd/man3/dwarf_attrval_signed.3 new file mode 100644 index 00000000..4f464408 --- /dev/null +++ b/static/netbsd/man3/dwarf_attrval_signed.3 @@ -0,0 +1,229 @@ +.\" $NetBSD: dwarf_attrval_signed.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_attrval_signed.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd December 26, 2016 +.Dt DWARF_ATTRVAL_SIGNED 3 +.Os +.Sh NAME +.Nm dwarf_attrval_flag , +.Nm dwarf_attrval_signed , +.Nm dwarf_attrval_string , +.Nm dwarf_attrval_unsigned +.Nd retrieve the value of an attribute within a DWARF debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_attrval_flag +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_attrval_signed +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Signed *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_attrval_string +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "const char **ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_attrval_unsigned +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Unsigned *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions search the debugging information entry referenced +by argument +.Fa die +for the attribute named by argument +.Fa attr . +If the named attribute is found, the functions set the location +pointed to by argument +.Fa ret +to the value of the attribute. +The argument +.Fa err , +if +.No non- Ns Dv NULL , +will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_attrval_flag +sets the location pointed to by argument +.Fa ret +to either 0 or 1. If the form of the attribute named by argument +.Fa attr +is +.Dv DW_FORM_flag , +function +.Fn dwarf_attrval_flag +sets the location pointed to by argument +.Fa ret +to 1 if the attribute has a non-zero value, or to 0 otherwise. +If the form of the attribute named by argument +.Fa attr +is +.Dv DW_FORM_flag_present , +function +.Fn dwarf_attrval_flag +unconditionally sets the location pointed to by argument +.Fa ret +to 1. +The form of the attribute must be one of +.Dv DW_FORM_flag +or +.Dv DW_FORM_flag_present . +.Pp +Function +.Fn dwarf_attrval_signed +stores the value for the attribute named by argument +.Fa attr , +into the location pointed to by argument +.Fa ret . +The attribute's value is treated as a signed integral quantity and is +sign-extended as needed. +The attribute named by the argument +.Fa attr +must belong to the +.Dv CONSTANT +class and must have one of the following forms: +.Dv DW_FORM_data1 , +.Dv DW_FORM_data2 , +.Dv DW_FORM_data4 , +.Dv DW_FORM_data8 +or +.Dv DW_FORM_sdata . +.Pp +Function +.Fn dwarf_attrval_string +sets the location pointed to by argument +.Fa ret +to a pointer to a NUL-terminated string that is the value of the +attribute named by argument +.Fa attr . +The form of the attribute must be one of +.Dv DW_FORM_string +or +.Dv DW_FORM_strp . +.Pp +Function +.Fn dwarf_attrval_unsigned +stores the value for the attribute named by argument +.Fa attr +into the location pointed to by argument +.Fa ret . +The attribute's value is treated as an unsigned integral quantity, and +is zero-extended as needed. +The named attribute must belong to one of the +.Dv CONSTANT , +.Dv ADDRESS +or +.Dv REFERENCE +classes and must have one of the following forms: +.Dv DW_FORM_addr , +.Dv DW_FORM_data1 , +.Dv DW_FORM_data2 , +.Dv DW_FORM_data4 , +.Dv DW_FORM_data8 , +.Dv DW_FORM_udata , +.Dv DW_FORM_ref1 , +.Dv DW_FORM_ref2 , +.Dv DW_FORM_ref4 , +.Dv DW_FORM_ref8 , +or +.Dv DW_FORM_ref_udata . +.Pp +If the attribute named by argument +.Fa attr +is +.Dv DW_AT_type +and is not present in the debugging information entry referenced by argument +.Fa die , +and if a +.Dv DW_AT_abstract_origin +or +.Dv DW_AT_specification +attribute is present in the debugging information entry, +function +.Fn dwarf_attrval_unsigned +will search for the named attribute in the debugging information entry +referenced by the +.Dv DW_AT_abstract_origin +or +.Dv DW_AT_specification +attribute. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +If the named attribute was not found in the specified debugging +information entry descriptor these functions return +.Dv DW_DLV_NO_ENTRY +and set argument +.Fa err . +For other errors, these functions return +.Dv DW_DLV_ERROR +and set argument +.Fa err . +.Sh COMPATIBILITY +These functions are extensions added by this implementation of the +DWARF(3) API. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Va die +or +.Va ret +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa die +did not contain an attribute corresponding to the value in argument +.Fa attr . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute named by argument +.Fa attr +was not of a permitted form. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_child.3 b/static/netbsd/man3/dwarf_child.3 new file mode 100644 index 00000000..45aba757 --- /dev/null +++ b/static/netbsd/man3/dwarf_child.3 @@ -0,0 +1,284 @@ +.\" $NetBSD: dwarf_child.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010,2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_child.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd December 21, 2014 +.Dt DWARF_CHILD 3 +.Os +.Sh NAME +.Nm dwarf_child , +.Nm dwarf_offdie , +.Nm dwarf_offdie_b , +.Nm dwarf_siblingof , +.Nm dwarf_siblingof_b +.Nd retrieve DWARF Debugging Information Entry descriptors +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_child "Dwarf_Die die" "Dwarf_Die *ret_die" "Dwarf_Error *err" +.Ft int +.Fo dwarf_offdie +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Die *ret_die" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_offdie_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Die *ret_die" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_siblingof +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Die die" +.Fa "Dwarf_Die *ret_die" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_siblingof_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Die die" +.Fa "Dwarf_Die *ret_die" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions are used to retrieve and traverse DWARF +Debugging Information Entry (DIE) descriptors associated with +a compilation unit. +These descriptors are arranged in the form of a tree, traversable +using +.Dq child +and +.Dq sibling +links; see +.Xr dwarf 3 +for more information. +DWARF Debugging Information Entry descriptors are represented +by the +.Vt Dwarf_Die +opaque type. +.Pp +Function +.Fn dwarf_child +retrieves the child of descriptor denoted by argument +.Fa die , +and stores it in the location pointed to by argument +.Fa ret_die . +.Pp +Function +.Fn dwarf_siblingof +retrieves the sibling of the descriptor denoted by argument +.Fa die , +and stores it in the location pointed to by argument +.Fa ret_die . +If argument +.Fa die +is +.Dv NULL , +the first debugging information entry descriptor for the +current compilation unit will be returned. +This function and function +.Fn dwarf_child +may be used together to traverse the tree of debugging information +entry descriptors for a compilation unit. +.Pp +Function +.Fn dwarf_siblingof_b +is identical to the function +.Fn dwarf_siblingof +except that it can retrieve the sibling descriptor from either the +current compilation unit or type unit. +If argument +.Fa is_info +is non-zero, the function behaves identically to function +.Fn dwarf_siblingof . +If argument +.Fa is_info +is zero, the descriptor referred by argument +.Fa die +should be associated with a debugging information entry in the +type unit. +The function will store the sibling of the descriptor in the location +pointed to by argument +.Fa ret_die . +If argument +.Fa is_info +is zero and argument +.Fa die +is +.Dv NULL , +the first debugging information entry descriptor for the +current type unit will be returned. +.Pp +Function +.Fn dwarf_offdie +retrieves the debugging information entry descriptor at global offset +.Fa offset +in the +.Dq .debug_info +section of the object associated with argument +.Fa dbg . +The returned descriptor is written to the location pointed to by argument +.Fa ret_die . +.Pp +Function +.Fn dwarf_offdie_b +is identical to the function +.Fn dwarf_offdie +except that it can retrieve the debugging information entry descriptor at +global offset +.Fa offset +from either of the +.Dq .debug_info +and +.Dq .debug_types +sections of the object associated with argument +.Fa dbg . +If argument +.Fa is_info +is non-zero, the function will retrieve the debugging information +entry from the +.Dq .debug_info +section, otherwise the function will retrieve the debugging +information entry from the +.Dq .debug_types +section. +The returned descriptor is written to the location pointed to by argument +.Fa ret_die . +.Ss Memory Management +The memory area used for the +.Vt Dwarf_Die +descriptor returned in argument +.Fa ret_die +is allocated by the +.Lb libdwarf . +Application code should use function +.Fn dwarf_dealloc +with the allocation type +.Dv DW_DLA_DIE +to free the memory area when the +.Vt Dwarf_Die +descriptor is no longer needed. +.Sh RETURN VALUES +These functions return the following values: +.Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY" +.It Bq Er DW_DLV_OK +The call succeeded. +.It Bq Er DW_DLV_ERROR +The requested operation failed. +Additional information about the error encountered will be recorded in +argument +.Fa err , +if it is not +.Dv NULL . +.It Bq Er DW_DLV_NO_ENTRY +For functions +.Fn dwarf_child , +.Fn dwarf_siblingof +and +.Fn dwarf_siblingof_b , +the descriptor denoted by argument +.Fa die +did not have a child or sibling. +.Pp +For functions +.Fn dwarf_offdie +and +.Fn dwarf_offdie_b , +there was no debugging information entry at the offset specified by +argument +.Fa offset . +.El +.Sh EXAMPLES +To retrieve the first DWARF Debugging Information Entry descriptor for +the first compilation unit associated with a +.Vt Dwarf_Debug +instance, and to traverse all its children, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Die die, die0; +Dwarf_Error de; + +\&... allocate dbg using dwarf_init() etc ... + +if (dwarf_next_cu_header(dbg, NULL, NULL, NULL, NULL, NULL, &de) != + DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_next_cu_header: %s", + dwarf_errmsg(de)); + +/* Get the first DIE for the current compilation unit. */ +die = NULL; +if (dwarf_siblingof(dbg, die, &die0, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_siblingof: %s", dwarf_errmsg(de)); + +/* Get the first child of this DIE. */ +die = die0; +if (dwarf_child(die, &die0, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_child: %s", dwarf_errmsg(de)); + +/* Get the rest of children. */ +do { + die = die0; + if (dwarf_siblingof(dbg, die, &die0, &de) == DW_DLV_ERROR) + errx(EXIT_FAILURE, "dwarf_siblingof: %s", + dwarf_errmsg(de)); +} while (die0 != NULL); +.Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT" +.It Bq Er DW_DLE_ARGUMENT +Arguments +.Fa dbg , +.Fa die +or +.Fa ret_die +were +.Dv NULL . +.It Bq Er DW_DLE_DIE_NO_CU_CONTEXT +Argument +.Fa dbg +was not associated with a compilation unit. +.It Bq Er DW_DLE_NO_ENTRY +The descriptor denoted by argument +.Fa die +had no child or sibling, or there was no DWARF debugging information +entry at the offset specified by argument +.Va offset . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errmsg 3 , +.Xr dwarf_get_die_infotypes_flag 3 , +.Xr dwarf_next_cu_header 3 diff --git a/static/netbsd/man3/dwarf_dealloc.3 b/static/netbsd/man3/dwarf_dealloc.3 new file mode 100644 index 00000000..f511689b --- /dev/null +++ b/static/netbsd/man3/dwarf_dealloc.3 @@ -0,0 +1,205 @@ +.\" $NetBSD: dwarf_dealloc.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2009-2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_dealloc.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd July 23, 2011 +.Dt DWARF_DEALLOC 3 +.Os +.Sh NAME +.Nm dwarf_dealloc , +.Nm dwarf_fde_cie_list_dealloc , +.Nm dwarf_funcs_dealloc , +.Nm dwarf_globals_dealloc , +.Nm dwarf_pubtypes_dealloc , +.Nm dwarf_ranges_dealloc , +.Nm dwarf_srclines_dealloc , +.Nm dwarf_types_dealloc , +.Nm dwarf_vars_dealloc , +.Nm dwarf_weaks_dealloc +.Nd release resources +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft void +.Fo dwarf_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Ptr ptr" +.Fa "Dwarf_Unsigned type" +.Fc +.Fo dwarf_fde_cie_list_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Cie *cie_list" +.Fa "Dwarf_Signed cie_count" +.Fa "Dwarf_Fde *fde_list" +.Fa "Dwarf_Signed fde_count" +.Fc +.Ft void +.Fo dwarf_funcs_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Func *funcs" +.Fa "Dwarf_Signed funccount" +.Fc +.Ft void +.Fo dwarf_globals_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Global *globals" +.Fa "Dwarf_Signed globalcount" +.Fc +.Ft void +.Fo dwarf_pubtypes_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Type *pubtypes" +.Fa "Dwarf_Signed pubtypecount" +.Fc +.Ft void +.Fo dwarf_ranges_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Ranges *ranges" +.Fa "Dwarf_Signed rangecount" +.Fc +.Ft void +.Fo dwarf_srclines_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Line *lines" +.Fa "Dwarf_Signed linecount" +.Fc +.Ft void +.Fo dwarf_types_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Type *types" +.Fa "Dwarf_Signed typecount" +.Fc +.Ft void +.Fo dwarf_vars_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Var *vars" +.Fa "Dwarf_Signed varcount" +.Fc +.Ft void +.Fo dwarf_weaks_dealloc +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Weak *weaks" +.Fa "Dwarf_Signed weakcount" +.Fc +.Sh DESCRIPTION +The function +.Fn dwarf_dealloc +is used by applications to indicate that memory areas returned by +.Lb libdwarf +may be safely disposed off. +Due to the way memory is managed in the current implementation, the +use of +.Fn dwarf_dealloc +is only necessary for a small set of DWARF types. +.Pp +Argument +.Fa dbg +should reference a valid debugging context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa ptr +should point to an object or memory area obtained by a prior call +to a DWARF(3) function. +.Pp +Argument +.Fa type +indicates the type of object being deallocated. +The indicated type must match that of the object being passed in +argument +.Fa ptr . +Valid values for the +.Fa type +argument are: +.Bl -tag -width ".Dv DW_DLA_FRAME_BLOCK" +.It Dv DW_DLA_ABBREV +An object of type +.Vt Dwarf_Abbrev , +as returned by a call to the function +.Xr dwarf_get_abbrev 3 . +.It Dv DW_DLA_DIE +An object of type +.Vt Dwarf_Die , +as returned by calls to the functions +.Xr dwarf_child 3 , +.Xr dwarf_offdie 3 +or +.Xr dwarf_siblingof 3 . +.It Dv DW_DLA_FRAME_BLOCK +An array of objects of type +.Vt Dwarf_Frame_op , +as returned by a call to the function +.Xr dwarf_expand_frame_instructions 3 . +.El +.Pp +Calls to +.Fn dwarf_dealloc +with other values for argument +.Fa type +are no-ops in this implementation. +.Pp +The functions +.Fn dwarf_fde_cie_list_dealloc , +.Fn dwarf_funcs_dealloc , +.Fn dwarf_globals_dealloc , +.Fn dwarf_pubtypes_dealloc , +.Fn dwarf_ranges_dealloc , +.Fn dwarf_srclines_dealloc , +.Fn dwarf_types_dealloc , +.Fn dwarf_vars_dealloc +and +.Fn dwarf_weaks_dealloc +are provided for compatibility with other implementations of the +DWARF(3) API. +Due to the way memory is managed in the current implementation, these +functions are effectively no-ops. +.Pp +See +.Xr dwarf 3 +for more information about the memory management scheme in this +implementation of the DWARF(3) API. +.Sh RETURN VALUES +Functions +.Fn dwarf_dealloc , +.Fn dwarf_fde_cie_list_dealloc , +.Fn dwarf_funcs_dealloc , +.Fn dwarf_globals_dealloc , +.Fn dwarf_pubtypes_dealloc , +.Fn dwarf_ranges_dealloc , +.Fn dwarf_srclines_dealloc , +.Fn dwarf_types_dealloc , +.Fn dwarf_vars_dealloc +and +.Fn dwarf_weaks_dealloc +have no return value. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_child 3 , +.Xr dwarf_expand_frame_instructions 3 , +.Xr dwarf_get_abbrev 3 , +.Xr dwarf_offdie 3 , +.Xr dwarf_siblingof 3 diff --git a/static/netbsd/man3/dwarf_def_macro.3 b/static/netbsd/man3/dwarf_def_macro.3 new file mode 100644 index 00000000..67a63061 --- /dev/null +++ b/static/netbsd/man3/dwarf_def_macro.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: dwarf_def_macro.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_def_macro.3 3961 2022-03-12 15:13:22Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_DEF_MACRO 3 +.Os +.Sh NAME +.Nm dwarf_def_macro +.Nd add a macro definition to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "int" +.Fo dwarf_def_macro +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned lineno" +.Fa "char *name" +.Fa "char *value" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_def_macro +adds a macro definition to a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa lineno +specifies the line number of the source line where the macro is +defined. +A line number of zero is used for macros that are defined +before any source file is read. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the macro. +For function-like macros this parameter should also include +parentheses and parameter names if any. +.Pp +Argument +.Fa value +should point to a NUL-terminated string containing the value +of the macro. +If the macro does not have a value, argument +.Fa value +should be set to +.Dv NULL . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_def_macro +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_def_macro +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To record the fact that a macro named +.Dv _STDIO_H_ +was defined at line 20 of the current macro file, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Error de; + +/* ... Assume 'dbg' refers to a DWARF producer instance... */ +if (dwarf_def_macro(dbg, 20, "_STDIO_H_", NULL, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_def_macro failed: %s", + dwarf_errmsg(-1)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_def_macro +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either arguments +.Fa dbg +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_end_macro_file 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_start_macro_file 3 , +.Xr dwarf_undef_macro 3 , +.Xr dwarf_vendor_ext 3 diff --git a/static/netbsd/man3/dwarf_die_abbrev_code.3 b/static/netbsd/man3/dwarf_die_abbrev_code.3 new file mode 100644 index 00000000..5eb11753 --- /dev/null +++ b/static/netbsd/man3/dwarf_die_abbrev_code.3 @@ -0,0 +1,57 @@ +.\" $NetBSD: dwarf_die_abbrev_code.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_die_abbrev_code.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 14, 2010 +.Dt DWARF_DIE_ABBREV_CODE 3 +.Os +.Sh NAME +.Nm dwarf_die_abbrev_code +.Nd retrieve the abbreviation code for a DWARF debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_die_abbrev_code "Dwarf_Die die" +.Sh DESCRIPTION +Function +.Fn dwarf_die_abbrev_code +returns the abbreviation code for the debugging information entry descriptor +referenced by argument +.Fa die . +Argument +.Fa die +should be a valid pointer to a value of type +.Vt Dwarf_Die . +.Sh RETURN VALUES +The function returns an integral value. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_diename 3 , +.Xr dwarf_dieoffset 3 , +.Xr dwarf_tag 3 diff --git a/static/netbsd/man3/dwarf_die_link.3 b/static/netbsd/man3/dwarf_die_link.3 new file mode 100644 index 00000000..795a31cb --- /dev/null +++ b/static/netbsd/man3/dwarf_die_link.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: dwarf_die_link.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_die_link.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_DIE_LINK 3 +.Os +.Sh NAME +.Nm dwarf_die_link +.Nd link a debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Die +.Fo dwarf_die_link +.Fa "Dwarf_P_Die die" +.Fa "Dwarf_P_Die parent" +.Fa "Dwarf_P_Die child" +.Fa "Dwarf_P_Die left" +.Fa "Dwarf_P_Die right" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_die_link +links debugging information entries together. +.Pp +Argument +.Fa die +should specify the debugging information entry to be updated. +.Pp +Argument +.Fa parent +specifies the new parent link for the debugging information entry. +.Pp +Argument +.Fa child +specifies the new first child link for the debugging information entry. +.Pp +Argument +.Fa left +specifies the new left sibling link for the debugging information entry. +.Pp +Argument +.Fa right +specifies the new right sibling link for the debugging information entry. +.Pp +Only one of arguments +.Fa parent , +.Fa child , +.Fa left +and +.Fa right +is allowed to be +.No non- Ns Dv NULL . +Existing links to parent, child, left or right debugging information +entries, if any, will be unlinked before the specified link is +established. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_die_link +returns the debugging information entry provided in argument +.Fa die . +In case of an error, function +.Fn dwarf_die_link +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +The function +.Fn dwarf_die_link +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa die +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +More than one of the arguments +.Fa parent , +.Fa child , +.Fa left +and +.Fa right +were +.No non- Ns Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_die_to_debug 3 , +.Xr dwarf_new_die 3 diff --git a/static/netbsd/man3/dwarf_diename.3 b/static/netbsd/man3/dwarf_diename.3 new file mode 100644 index 00000000..da4d5e9e --- /dev/null +++ b/static/netbsd/man3/dwarf_diename.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: dwarf_diename.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_diename.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 31, 2010 +.Dt DWARF_DIENAME 3 +.Os +.Sh NAME +.Nm dwarf_diename +.Nd retrieve the name associated with a debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_diename "Dwarf_Die die" "char **ret_name" "Dwarf_Error *err" +.Sh DESCRIPTION +Function +.Fn dwarf_diename +retrieves a pointer to the NUL-terminated string associated with the +.Dv DW_AT_name +attribute of the debugging information entry descriptor referenced by +argument +.Fa die . +If the pointer was successfully retrieved, it is stored in the location +pointed to by argument +.Fa ret_name . +.Sh RETURN VALUES +Function +.Fn dwarf_diename +returns +.Dv DW_DLV_OK +on success. +.Pp +If the debugging information entry descriptor denoted by argument +.Fa die +does not contain a +.Dv DW_AT_name +attribute, the function returns +.Dv DW_DLV_NO_ENTRY +and sets argument +.Fa err . +For other errors, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_diename +can fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa die +or +.Fa ret_name +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa die +had no +.Dv DW_AT_name +attribute. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_die_abbrev_code 3 , +.Xr dwarf_dieoffset 3 , +.Xr dwarf_tag 3 diff --git a/static/netbsd/man3/dwarf_dieoffset.3 b/static/netbsd/man3/dwarf_dieoffset.3 new file mode 100644 index 00000000..0aa0f8ab --- /dev/null +++ b/static/netbsd/man3/dwarf_dieoffset.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: dwarf_dieoffset.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010,2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_dieoffset.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd December 21, 2014 +.Dt DWARF_DIEOFFSET 3 +.Os +.Sh NAME +.Nm dwarf_die_CU_offset , +.Nm dwarf_die_CU_offset_range , +.Nm dwarf_dieoffset , +.Nm dwarf_get_cu_die_offset_given_cu_header_offset , +.Nm dwarf_get_cu_die_offset_given_cu_header_offset_b +.Nd return offsets of DWARF debugging information entries +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_die_CU_offset +.Fa "Dwarf_Die die" +.Fa "Dwarf_Off *ret_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_die_CU_offset_range +.Fa "Dwarf_Die die" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Off *cu_length" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_dieoffset +.Fa "Dwarf_Die die" +.Fa "Dwarf_Off *ret_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_cu_die_offset_given_cu_header_offset +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off in_cu_header_offset" +.Fa "Dwarf_Off *out_cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_cu_die_offset_given_cu_header_offset_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off in_cu_header_offset" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Off *out_cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions are used to retrieve offsets for DWARF debugging +information entries. +.Pp +Function +.Fn dwarf_die_CU_offset +returns the offset of the debugging information entry referenced by +argument +.Fa die +relative to the start of its containing compilation unit. +Argument +.Fa ret_offset +should point to the location that is to hold the returned offset. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_die_CU_offset_range +returns the section-relative offset and length of the compilation unit +containing the debugging information entry referenced by argument +.Fa die . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +Argument +.Fa cu_length +should point to a location that will hold the returned length of the +compilation unit. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_dieoffset +retrieves the section-relative offset of the debugging information +entry referenced by argument +.Fa die . +Argument +.Fa ret_offset +should point to a location that is to hold the returned +section-relative offset. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_get_cu_die_offset_given_cu_header_offset +returns the offset for the first debugging information entry for a +compilation unit, given an offset to the header of the compilation +unit. +Argument +.Fa dbg +should reference a valid debugging context allocated using +.Xr dwarf_init 3 . +Argument +.Fa in_cu_header_offset +contains the offset to the start of a compilation unit. +Argument +.Fa out_cu_die_offset +points to a location that will hold the returned offset. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b +behaves identically to the function +.Fn dwarf_get_cu_die_offset_given_cu_header_offset +when the argument +.Fa is_info +is non-zero. +When the argument +.Fa is_info +is zero, function +.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b +returns the offset for the first debugging information entry for a +type unit, given an offset to the header of the type unit in argument +.Fa in_cu_header_offset . +Argument +.Fa out_cu_die_offset +points to a location that will hold the returned offset. +If the argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +On success, these functions return +.Dv DW_DLV_OK . +In case of an error, these functions return +.Dv DW_DLV_ERROR +and set argument +.Fa err . +.Pp +Function +.Fn dwarf_get_cu_die_offset_given_cu_header_offset +and +.Fn dwarf_get_cu_die_offset_given_cu_header_offset_b +returns +.Dv DW_DLV_NO_ENTRY +and sets argument +.Fa err +if there is no compilation or type unit located at the +offset specified in argument +.Fa in_cu_header_offset . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_length , +.Va cu_offset , +.Va dbg , +.Va die , +.Va out_cu_die_offset +or +.Va ret_offset +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa in_cu_header_offset +specified an unknown offset. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_next_cu_header 3 , +.Xr dwarf_offdie 3 , +.Xr dwarf_offdie_b 3 diff --git a/static/netbsd/man3/dwarf_end_macro_file.3 b/static/netbsd/man3/dwarf_end_macro_file.3 new file mode 100644 index 00000000..64371939 --- /dev/null +++ b/static/netbsd/man3/dwarf_end_macro_file.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: dwarf_end_macro_file.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_end_macro_file.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd September 25, 2011 +.Dt DWARF_END_MACRO_FILE 3 +.Os +.Sh NAME +.Nm dwarf_end_macro_file +.Nd mark the end of the current source file inclusion +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "int" +.Fo dwarf_end_macro_file +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_end_macro_file +marks the end of the current source file inclusion. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_end_macro_file +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_end_macro_file +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_end_macro_file +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_def_macro 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_start_macro_file 3 , +.Xr dwarf_undef_macro 3 , +.Xr dwarf_vendor_ext 3 diff --git a/static/netbsd/man3/dwarf_errmsg.3 b/static/netbsd/man3/dwarf_errmsg.3 new file mode 100644 index 00000000..051c6e85 --- /dev/null +++ b/static/netbsd/man3/dwarf_errmsg.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: dwarf_errmsg.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2009 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_errmsg.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd December 12, 2009 +.Dt DWARF_ERRMSG 3 +.Os +.Sh NAME +.Nm dwarf_errmsg +.Nd retrieve a human-readable string corresponding to a +.Vt Dwarf_Error +instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "const char *" +.Fn dwarf_errmsg "Dwarf_Error err" +.Sh DESCRIPTION +Function +.Fn dwarf_errmsg +returns a +.Dv NUL Ns - Ns +terminated string for the error denoted by +argument +.Fa err . +.Pp +Argument +.Fa err +should be a valid handle to a +.Vt Dwarf_Error +instance. +.Sh Memory Management +The returned pointer should not be freed using +.Xr free 3 +or +.Xr dwarf_dealloc 3 . +.Sh RETURN VALUES +Function +.Fn dwarf_errmsg +returns a pointer to a +.Dv NUL Ns - Ns +terminated string. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errno 3 diff --git a/static/netbsd/man3/dwarf_errno.3 b/static/netbsd/man3/dwarf_errno.3 new file mode 100644 index 00000000..a8076c11 --- /dev/null +++ b/static/netbsd/man3/dwarf_errno.3 @@ -0,0 +1,60 @@ +.\" $NetBSD: dwarf_errno.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2009,2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_errno.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 25, 2010 +.Dt DWARF_ERRNO 3 +.Os +.Sh NAME +.Nm dwarf_errno +.Nd retrieve the error number corresponding to a +.Vt Dwarf_Error +instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_errno "Dwarf_Error err" +.Sh DESCRIPTION +Function +.Fn dwarf_errno +returns the error number associated with a +.Vt Dwarf_Error +instance. +.Pp +Argument +.Fa err +should be a valid handle to a +.Vt Dwarf_Error +instance. +.Sh RETURN VALUES +Function +.Fn dwarf_errno +returns an integral value. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errmsg 3 diff --git a/static/netbsd/man3/dwarf_expand_frame_instructions.3 b/static/netbsd/man3/dwarf_expand_frame_instructions.3 new file mode 100644 index 00000000..d5bfea39 --- /dev/null +++ b/static/netbsd/man3/dwarf_expand_frame_instructions.3 @@ -0,0 +1,186 @@ +.\" $NetBSD: dwarf_expand_frame_instructions.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_expand_frame_instructions.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3 +.Os +.Sh NAME +.Nm dwarf_expand_frame_instructions +.Nd expand frame instructions +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_expand_frame_instructions +.Fa "Dwarf_Cie cie" +.Fa "Dwarf_Ptr instructions" +.Fa "Dwarf_Unsigned len" +.Fa "Dwarf_Frame_Op **ret_ops" +.Fa "Dwarf_Signed *ret_opcnt" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_expand_frame_instructions +translates DWARF frame instruction bytes into an array of +.Vt Dwarf_Frame_Op +descriptors. +.Pp +Argument +.Fa cie +should reference the CIE descriptor associated with the instructions +to be translated. +.Pp +Arugment +.Fa instructions +should point to an array of frame instruction bytes, as +returned by the functions +.Xr dwarf_get_cie_info 3 +or +.Xr dwarf_get_fde_instr_bytes 3 . +.Pp +Argument +.Fa len +should specify the number of the frame instruction bytes to be +translated. +.Pp +Argument +.Fa ret_ops +should point to a location that will be set to a pointer to +an array of translated +.Vt Dwarf_Frame_Op +descriptors. +.Pp +Argument +.Fa ret_opcnt +should point to a location that will hold the total number of the +returned descriptors. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory area used for the descriptor array returned in argument +.Fa ret_ops +is allocated by +.Lb libdwarf . +Application code should use function +.Xr dwarf_dealloc 3 +with type +.Dv DW_DLA_FRAME_BLOCK +to free the memory area when the descriptor array is no longer needed. +.Sh RETURN VALUES +Function +.Fn dwarf_expand_frame_instructions +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To retrieve and expand the frame instructions for a given FDE +descriptor, use: +.Bd -literal -offset indent +Dwarf_Dbg dbg; +Dwarf_Cie cie; +Dwarf_Fde fde; +Dwarf_Ptr fde_inst; +Dwarf_Unsigned fde_instlen; +Dwarf_Frame_Op *ops; +Dwarf_Signed opcnt; +Dwarf_Error de; + +/* ... assuming `dbg` references a valid DWARF debugging context, + `fde` references a valid FDE descriptor and `cie` holds the CIE + descriptor associated with the FDE descriptor ... */ + +if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, + &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s", + dwarf_errmsg(de)); + +if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen, + &ops, &opcnt, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, + "dwarf_expand_frame_instructions failed: %s", + dwarf_errmsg(de)); + +for (i = 0; i < opcnt; i++) { + /* ... use ops[i] ... */ +} + +/* Free the memory area when no longer needed. */ +dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK); +.Ed +.Sh ERRORS +Function +.Fn dwarf_expand_frame_instructions +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa cie , +.Fa instructions , +.Fa ret_ops +or +.Fa ret_opcnt +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa len +was 0. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR +An unknown instruction was found in the instruction bytes provided +in argument +.Fa instructions . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_frame_instructions_dealloc 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_n 3 diff --git a/static/netbsd/man3/dwarf_expr_current_offset.3 b/static/netbsd/man3/dwarf_expr_current_offset.3 new file mode 100644 index 00000000..2ebd79dd --- /dev/null +++ b/static/netbsd/man3/dwarf_expr_current_offset.3 @@ -0,0 +1,88 @@ +.\" $NetBSD: dwarf_expr_current_offset.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_expr_current_offset.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd September 13, 2011 +.Dt DWARF_EXPR_CURRENT_OFFSET 3 +.Os +.Sh NAME +.Nm dwarf_expr_current_offset +.Nd retrieve the number of bytes in a location expression stream +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_expr_current_offset +.Fa "Dwarf_P_Expr expr" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_expr_current_offset +returns the size in bytes of the stream representation of a location +expression. +.Pp +Argument +.Fa expr +should reference a location expression descriptor allocated using +.Xr dwarf_new_expr 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_expr_current_offset +returns the size in bytes of the location descriptor's stream +representation. +In case of an error, function +.Fn dwarf_expr_current_offset +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_expr_current_offset +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa expr +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_expr_addr 3 , +.Xr dwarf_add_expr_addr_b 3 , +.Xr dwarf_add_expr_gen 3 , +.Xr dwarf_expr_into_block 3 , +.Xr dwarf_new_expr 3 diff --git a/static/netbsd/man3/dwarf_expr_into_block.3 b/static/netbsd/man3/dwarf_expr_into_block.3 new file mode 100644 index 00000000..5dc65dc3 --- /dev/null +++ b/static/netbsd/man3/dwarf_expr_into_block.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: dwarf_expr_into_block.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_expr_into_block.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd September 13, 2011 +.Dt DWARF_EXPR_INTO_BLOCK 3 +.Os +.Sh NAME +.Nm dwarf_expr_into_block +.Nd retrieve the byte stream for a location expression +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Addr" +.Fo dwarf_expr_into_block +.Fa "Dwarf_P_Expr expr" +.Fa "Dwarf_Unsigned *length" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_expr_into_block +retrieves the byte stream representation of a location expression. +.Pp +Argument +.Fa expr +should reference a location expression descriptor allocated using +.Xr dwarf_new_expr 3 . +.Pp +Argument +.Fa length +should point to a location which will hold the size in bytes of +the retrieved byte stream. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_expr_into_block +returns the address of the first byte of the generated byte stream. +In case of an error, function +.Fn dwarf_expr_into_block +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_expr_into_block +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa expr +or +.Fa length +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_location_expr 3 , +.Xr dwarf_add_expr_addr 3 , +.Xr dwarf_add_expr_addr_b 3 , +.Xr dwarf_add_expr_gen 3 , +.Xr dwarf_expr_current_offset 3 , +.Xr dwarf_new_expr 3 diff --git a/static/netbsd/man3/dwarf_fde_cfa_offset.3 b/static/netbsd/man3/dwarf_fde_cfa_offset.3 new file mode 100644 index 00000000..20756029 --- /dev/null +++ b/static/netbsd/man3/dwarf_fde_cfa_offset.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_fde_cfa_offset.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_fde_cfa_offset.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd September 26, 2011 +.Dt DWARF_FDE_CFA_OFFSET 3 +.Os +.Sh NAME +.Nm dwarf_fde_cfa_offset +.Nd add a DW_CFA_offset frame instruction to a DWARF frame descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Fde" +.Fo dwarf_fde_cfa_offset +.Fa "Dwarf_P_Fde fde" +.Fa "Dwarf_Unsigned reg" +.Fa "Dwarf_Signed offset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_fde_cfa_offset +appends a +.Dv DW_CFA_offset +frame instruction to the frame descriptor referenced by argument +.Fa fde . +.Pp +Argument +.Fa fde +should reference a frame descriptor allocated using +.Xr dwarf_new_fde 3 . +.Pp +Argument +.Fa reg +specifies the register operand for the frame instruction. +.Pp +Argument +.Fa offset +specifies the offset operand for the frame instruction. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_fde_cfa_offset +returns the frame descriptor given in argument +.Fa fde . +In case of an error, function +.Fn dwarf_fde_cfa_offset +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_fde_cfa_offset +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa fde +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_cie 3 , +.Xr dwarf_add_frame_fde 3 , +.Xr dwarf_add_frame_fde_b 3 , +.Xr dwarf_new_fde 3 diff --git a/static/netbsd/man3/dwarf_find_macro_value_start.3 b/static/netbsd/man3/dwarf_find_macro_value_start.3 new file mode 100644 index 00000000..d8d2552a --- /dev/null +++ b/static/netbsd/man3/dwarf_find_macro_value_start.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: dwarf_find_macro_value_start.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_find_macro_value_start.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 26, 2011 +.Dt DWARF_FIND_MACRO_VALUE_START 3 +.Os +.Sh NAME +.Nm dwarf_find_macro_value_start +.Nd return the address of the first byte of a macro value +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft char * +.Fo dwarf_find_macro_value_start +.Fa "char *macro_string" +.Fc +.Sh DESCRIPTION +Given a DWARF macro string, function +.Fn dwarf_find_macro_value_start +returns a pointer to the first byte of the macro value part of the +macro string. +.Pp +Argument +.Fa macro_string +should be a NUL-terminated string conforming to the macro format +defined in the DWARF standard; see +.Xr dwarf 4 . +.Sh RETURN VALUES +On success, function +.Fn dwarf_find_macro_value_start +returns a pointer to the first byte of the macro value. +If the macro value part was not found, function +.Fn dwarf_find_macro_value_start +returns a pointer to the NUL-byte terminating argument +.Fa macro_string . +.Pp +Function +.Fn dwarf_find_macro_value_start +returns +.Dv NULL +if argument +.Fa macro_string +was +.Dv NULL . +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_macro_details 3 diff --git a/static/netbsd/man3/dwarf_finish.3 b/static/netbsd/man3/dwarf_finish.3 new file mode 100644 index 00000000..36974ffe --- /dev/null +++ b/static/netbsd/man3/dwarf_finish.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: dwarf_finish.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2009,2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_finish.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_FINISH 3 +.Os +.Sh NAME +.Nm dwarf_finish , +.Nm dwarf_object_finish +.Nd free resources associated with a debug descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_finish "Dwarf_Debug dbg" "Dwarf_Error *err" +.Ft int +.Fn dwarf_object_finish "Dwarf_Debug dbg" "Dwarf_Error *err" +.Sh DESCRIPTION +The +.Fn dwarf_finish +and +.Fn dwarf_object_finish +functions are used to release the resources associated with a debug +descriptor allocated by a prior call to +.Xr dwarf_init 3 +and +.Xr dwarf_object_init 3 +respectively. +.Pp +Argument +.Fa dbg +denotes a valid +.Vt Dwarf_Debug +instance. +Argument +.Fa err +will be used to record error information in case of an error. +.Pp +After a call to +.Fn dwarf_finish +or +.Fn dwarf_object_finish , +the argument +.Fa dbg +will be invalid and should not be used further. +.Pp +For +.Vt Dwarf_Debug +descriptors opened using +.Xr dwarf_init 3 , +the application would need to explicitly release the +.Vt Elf +instance associated with the descriptor by first retrieving +the instance using +.Xr dwarf_get_elf 3 +and closing it using +.Xr elf_end 3 . +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +if successful. +In case of an error, the functions return +.Dv DW_DLV_ERROR +and record additional information in argument +.Fa err . +.Sh EXAMPLES +To deallocate a +.Vt Dwarf_Debug +instance allocated using +.Xr dwarf_elf_init 3 +use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Error de; + +if (dwarf_finish(dbg, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de)); +.Ed +.Pp +To deallocate a +.Vt Dwarf_Debug +instance allocated using +.Xr dwarf_object_init 3 +use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Error de; + +if (dwarf_object_finish(dbg, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_object_finish: %s", + dwarf_errmsg(de)); +.Ed +.Pp +To deallocate a +.Vt Dwarf_Debug +instance allocated using +.Xr dwarf_init 3 +use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dward_Error de; +Elf *e; + +if (dwarf_get_elf(dbg, &e, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_elf: %s", dwarf_errmsg(&de)); + +if (dwarf_finish(dbg, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de)); + +(void) elf_end(e); +.Ed +.Sh SEE ALSO +.Xr dwarf_elf_init 3 , +.Xr dwarf_get_elf 3 , +.Xr dwarf_init 3 , +.Xr dwarf_object_init 3 , +.Xr elf_end 3 diff --git a/static/netbsd/man3/dwarf_formaddr.3 b/static/netbsd/man3/dwarf_formaddr.3 new file mode 100644 index 00000000..9df65b55 --- /dev/null +++ b/static/netbsd/man3/dwarf_formaddr.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: dwarf_formaddr.3,v 1.6 2024/03/03 17:37:30 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formaddr.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd July 23, 2010 +.Dt DWARF_FORMADDR 3 +.Os +.Sh NAME +.Nm dwarf_formaddr +.Nd return the value of an ADDRESS class attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formaddr +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Addr *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formaddr +sets the location pointed to by argument +.Fa ret +to the address represented by the attribute referenced +by argument +.Fa attr . +The form of argument +.Fa attr +must be +.Dv DW_FORM_addr . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_formaddr +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formblock +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of form +.Dv DW_FORM_addr . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formblock.3 b/static/netbsd/man3/dwarf_formblock.3 new file mode 100644 index 00000000..c525f914 --- /dev/null +++ b/static/netbsd/man3/dwarf_formblock.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: dwarf_formblock.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formblock.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd July 23, 2010 +.Dt DWARF_FORMBLOCK 3 +.Os +.Sh NAME +.Nm dwarf_formblock +.Nd return the value of a BLOCK attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formblock +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Block **ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formblock +sets the location pointed to by argument +.Fa ret +to a pointer to a +.Vt Dwarf_Block +structure containing the value of the attribute referenced +by argument +.Fa attr . +The form of argument +.Fa attr +must be one of +.Dv DW_FORM_block , +.Dv DW_FORM_block1 , +.Dv DW_FORM_block2 +or +.Dv DW_FORM_block4 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Ss Memory Management +The memory area referenced by the returned pointer is managed by +the DWARF(3) library. +The application should not attempt to free this memory +area. +Portable code may indicate that the memory area is to be freed by +using +.Xr dwarf_dealloc 3 . +.Sh RETURN VALUES +Function +.Fn dwarf_formblock +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formblock +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formexprloc.3 b/static/netbsd/man3/dwarf_formexprloc.3 new file mode 100644 index 00000000..eacb3837 --- /dev/null +++ b/static/netbsd/man3/dwarf_formexprloc.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: dwarf_formexprloc.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formexprloc.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd July 25, 2010 +.Dt DWARF_FORMEXPRLOC 3 +.Os +.Sh NAME +.Nm dwarf_formexprloc +.Nd return information about a location expression +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formexprloc +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Unsigned *retlen" +.Fa "Dwarf_Ptr *retexpr" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formexprloc +allows an application to retrieve the length and the bytes of a +DWARF location expression. +.Pp +Argument +.Fa attr +should reference a DWARF attribute of the form +.Dv DW_FORM_exprloc . +Argument +.Fa retlen +should point to a location that will be set to the length of the +location expression. +Argument +.Fa retexpr +should point to a location that will be set to a pointer to the +content of the location expression itself. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Ss Memory Management +The application should not attempt to free the memory +area referenced by the pointer returned in argument +.Fa retexpr . +.Sh RETURN VALUES +Function +.Fn dwarf_formexprloc +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formexprloc +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +One of arguments +.Fa attr , +.Fa retlen +or +.Fa retexpr +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of form +.Dv DW_FORM_exprloc . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formflag.3 b/static/netbsd/man3/dwarf_formflag.3 new file mode 100644 index 00000000..af841229 --- /dev/null +++ b/static/netbsd/man3/dwarf_formflag.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: dwarf_formflag.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formflag.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 21, 2010 +.Dt DWARF_FORMFLAG 3 +.Os +.Sh NAME +.Nm dwarf_formflag +.Nd return the value of a BOOLEAN class attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formflag +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formflag +sets the location pointed to by argument +.Fa ret +to 1 if the attribute referenced by argument +.Fa attr +has a non-zero value, or 0 otherwise. +The form of argument +.Fa attr +must be one of +.Dv DW_FORM_flag +or +.Dv DW_FORM_flag_present . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_formflag +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formflag +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formref.3 b/static/netbsd/man3/dwarf_formref.3 new file mode 100644 index 00000000..3299e4a5 --- /dev/null +++ b/static/netbsd/man3/dwarf_formref.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: dwarf_formref.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formref.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 21, 2010 +.Dt DWARF_FORMREF 3 +.Os +.Sh NAME +.Nm dwarf_formref , +.Nm dwarf_global_formref +.Nd retrieve offsets for REFERENCE class attributes +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formref +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Off *retoffset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_global_formref +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Off *retoffset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions return the offsets associated with a DWARF attribute +descriptor. +.Pp +Function +.Fn dwarf_formref +returns the compilation unit relative offset of the descriptor +referenced by argument +.Fa attr +in the location pointed to by argument +.Fa retoffset . +Argument +.Fa attr +must be a reference that is local to a compilation unit. +Permitted forms for argument +.Fa attr +are +.Dv DW_FORM_ref1 , +.Dv DW_FORM_ref2 , +.Dv DW_FORM_ref4 , +.Dv DW_FORM_ref8 +and +.Dv DW_FORM_ref_udata . +.Pp +Function +.Fn dwarf_global_formref +returns the section-relative offset of the descriptor referenced by +argument +.Fa attr +in the location pointed to by argument +.Fa retoffset . +Argument +.Fa attr +should be a legal +.Sy REFERENCE +class form. +Permitted forms for argument +.Fa attr +are: +.Dv DW_FORM_ref_addr , +.Dv DW_FORM_ref_udata , +.Dv DW_FORM_ref1 , +.Dv DW_FORM_ref2 , +.Dv DW_FORM_ref4 , +.Dv DW_FORM_ref8 +and +.Dv DW_FORM_sec_offset . +The returned offset is relative to the start of the +.Dq .debug_info +ELF section. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +on success. +In case of an error, these functions return +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa retoffset +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formsig8.3 b/static/netbsd/man3/dwarf_formsig8.3 new file mode 100644 index 00000000..87c2fe06 --- /dev/null +++ b/static/netbsd/man3/dwarf_formsig8.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: dwarf_formsig8.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formsig8.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd July 24, 2010 +.Dt DWARF_FORMSIG8 3 +.Os +.Sh NAME +.Nm dwarf_formsig8 +.Nd return the 64-bit type signature for a DWARF type +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formsig8 +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Sig8 *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formsig8 +sets the location pointed to by argument +.Fa ret +to the 64-bit type signature that is the value of +the attribute referenced by argument +.Fa attr . +The form of argument +.Fa attr +must be +.Dv DW_FORM_ref_sig8 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_formsig8 +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formsig8 +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 +.Sh HISTORY +Type signatures were added in version 4 of the DWARF specification. diff --git a/static/netbsd/man3/dwarf_formstring.3 b/static/netbsd/man3/dwarf_formstring.3 new file mode 100644 index 00000000..300be2ef --- /dev/null +++ b/static/netbsd/man3/dwarf_formstring.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: dwarf_formstring.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formstring.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd July 24, 2010 +.Dt DWARF_FORMSTRING 3 +.Os +.Sh NAME +.Nm dwarf_formstring +.Nd return the value of a STRING class attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formstring +.Fa "Dwarf_Attribute attr" +.Fa "char **ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_formstring +sets the location pointed to by argument +.Fa ret +to a pointer to a NUL-terminated string containing +the value of the attribute referenced by argument +.Fa attr . +The form of argument +.Fa attr +must be one of +.Dv DW_FORM_string +or +.Dv DW_FORM_strp . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Ss Memory Management +The memory area referenced by the returned pointer is managed by +the DWARF(3) library. +The application should not attempt to directly free this memory +area. +.Sh RETURN VALUES +Function +.Fn dwarf_formstring +returns +.Dv DW_DLV_OK +on success. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_formstring +may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsdata 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formudata 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_formudata.3 b/static/netbsd/man3/dwarf_formudata.3 new file mode 100644 index 00000000..2e3b3639 --- /dev/null +++ b/static/netbsd/man3/dwarf_formudata.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: dwarf_formudata.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_formudata.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 21, 2010 +.Dt DWARF_FORMUDATA 3 +.Os +.Sh NAME +.Nm dwarf_formudata , +.Nm dwarf_formsdata +.Nd return the value of a CONSTANT class attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_formudata +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Unsigned *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_formsdata +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Signed *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions return the value associated with a DWARF attribute +describing a constant. +.Pp +Function +.Fn dwarf_formudata +sets the location pointed to by argument +.Fa ret +to the value of the attribute referenced by argument +.Fa attr , +treating the value as an unsigned quantity. +Argument +.Fa attr +must have one of the following forms: +.Dv DW_FORM_data1 , +.Dv DW_FORM_data2 , +.Dv DW_FORM_data4 , +.Dv DW_FORM_data8 +and +.Dv DW_FORM_udata . +.Pp +Function +.Fn dwarf_formsdata +sets the location pointed to by argument +.Fa ret +to the value of the attribute referenced by argument +.Fa attr , +appropriately sign extended. +Argument +.Fa attr +must have one of the following forms: +.Dv DW_FORM_data1 , +.Dv DW_FORM_data2 , +.Dv DW_FORM_data4 , +.Dv DW_FORM_data8 +and +.Dv DW_FORM_sdata . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +on success. +In case of an error, they return +.Dv DW_DLV_ERROR +and set argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ATTR_FORM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa attr +or +.Fa ret +was +.Dv NULL . +.It Bq Er DW_DLE_ATTR_FORM_BAD +The attribute referenced by argument +.Fa attr +was not of a permitted kind. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_formblock 3 , +.Xr dwarf_formflag 3 , +.Xr dwarf_formref 3 , +.Xr dwarf_formsig8 3 , +.Xr dwarf_formstring 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_get_AT_name.3 b/static/netbsd/man3/dwarf_get_AT_name.3 new file mode 100644 index 00000000..3e059025 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_AT_name.3 @@ -0,0 +1,262 @@ +.\" $NetBSD: dwarf_get_AT_name.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_AT_name.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 22, 2011 +.Dt DWARF_GET_AT_NAME 3 +.Os +.Sh NAME +.Nm dwarf_get_ACCESS_name , +.Nm dwarf_get_AT_name , +.Nm dwarf_get_ATE_name , +.Nm dwarf_get_CC_name , +.Nm dwarf_get_CFA_name , +.Nm dwarf_get_CHILDREN_name , +.Nm dwarf_get_DS_name , +.Nm dwarf_get_DSC_name , +.Nm dwarf_get_EH_name , +.Nm dwarf_get_END_name , +.Nm dwarf_get_FORM_name , +.Nm dwarf_get_ID_name , +.Nm dwarf_get_INL_name , +.Nm dwarf_get_LANG_name , +.Nm dwarf_get_LNE_name , +.Nm dwarf_get_LNS_name , +.Nm dwarf_get_MACINFO_name , +.Nm dwarf_get_OP_name , +.Nm dwarf_get_ORD_name , +.Nm dwarf_get_TAG_name , +.Nm dwarf_get_VIRTUALITY_name , +.Nm dwarf_get_VIS_name +.Nd retrieve the symbolic names of DWARF constants +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_ACCESS_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_AT_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_ATE_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_CC_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_CFA_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_CHILDREN_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_DS_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_DSC_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_EH_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_END_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_FORM_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_ID_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_INL_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_LANG_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_LNE_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_LNS_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_MACINFO_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_OP_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_ORD_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_TAG_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_VIRTUALITY_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Ft int +.Fo dwarf_get_VIS_name +.Fa "unsigned val" +.Fa "char **str" +.Fc +.Sh DESCRIPTION +These functions return the symbolic name of a numeric DWARF constant. +.Pp +Argument +.Fa val +specifies the numeric value whose symbolic name is desired. +.Pp +Argument +.Fa str +should point to a location which will hold the returned +NUL-terminated string containing the symbolic name of the +specified value. +.Pp +The list of functions and the DWARF constants that they accept are: +.Pp +.Bl -tag -width ".Fn dwarf_get_VIRTUALITY_name" -compact +.It Fn dwarf_get_ACCESS_name +.Dv DW_ACCESS_* +constants. +.It Fn dwarf_get_AT_name +.Dv DW_AT_* +constants. +.It Fn dwarf_get_ATE_name +.Dv DW_ATE_* +constants. +.It Fn dwarf_get_CC_name +.Dv DW_CC_* +constants. +.It Fn dwarf_get_CFA_name +.Dv DW_CFA_* +constants. +.It Fn dwarf_get_CHILDREN_name +.Dv DW_CHILDREN_* +constants. +.It Fn dwarf_get_DS_name +.Dv DW_DS_* +constants. +.It Fn dwarf_get_DSC_name +.Dv DW_DSC_* +constants. +.It Fn dwarf_get_EH_name +.Dv DW_EH_PE_* +constants. +.It Fn dwarf_get_END_name +.Dv DW_END_* +constants. +.It Fn dwarf_get_FORM_name +.Dv DW_FORM_* +constants. +.It Fn dwarf_get_ID_name +.Dv DW_ID_* +constants. +.It Fn dwarf_get_INL_name +.Dv DW_INL_* +constants. +.It Fn dwarf_get_LANG_name +.Dv DW_LANG_* +constants. +.It Fn dwarf_get_LNE_name +.Dv DW_LNE_* +constants. +.It Fn dwarf_get_LNS_name +.Dv DW_LNS_* +constants. +.It Fn dwarf_get_MACINFO_name +.Dv DW_MACINFO_* +constants. +.It Fn dwarf_get_OP_name +.Dv DW_OP_* +constants. +.It Fn dwarf_get_ORD_name +.Dv DW_ORD_* +constants. +.It Fn dwarf_get_TAG_name +.Dv DW_TAG_* +constants. +.It Fn dwarf_get_VIRTUALITY_name +.Dv DW_VIRTUALITY_* +constants. +.It Fn dwarf_get_VIS_name +.Dv DW_VIS_* +constants. +.El +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +on success. +If the DWARF constant denoted by argument +.Fa val +is not recognized, these function return +.Dv DW_DLV_NO_ENTRY . +.Sh SEE ALSO +.Xr dwarf 3 diff --git a/static/netbsd/man3/dwarf_get_abbrev.3 b/static/netbsd/man3/dwarf_get_abbrev.3 new file mode 100644 index 00000000..f74bdadd --- /dev/null +++ b/static/netbsd/man3/dwarf_get_abbrev.3 @@ -0,0 +1,183 @@ +.\" $NetBSD: dwarf_get_abbrev.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_abbrev.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 27, 2011 +.Dt DWARF_GET_ABBREV 3 +.Os +.Sh NAME +.Nm dwarf_get_abbrev +.Nd retrieve abbreviation information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_abbrev +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned offset" +.Fa "Dwarf_Abbrev *ret_abbrev" +.Fa "Dwarf_Unsigned *length" +.Fa "Dwarf_Unsigned *attr_count" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_abbrev +retrieves information about an abbreviation from the DWARF abbreviations +section, +.Dq ".debug_abbrev" . +Abbreviation information is returned using an opaque descriptor +of type +.Vt Dwarf_Abbrev . +The returned +.Vt Dwarf_Abbrev +descriptor may then be passed to the other abbreviation related APIs +in the DWARF(3) API to retrieve specific information about the +abbreviation. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa offset +should be an offset, relative to the +.Dq ".debug_abbrev" +section, to the start of an abbreviation entry. +.Pp +Argument +.Fa ret_abbrev +should point to a location that will hold a pointer to the +returned +.Vt Dwarf_Abbrev +descriptor. +.Pp +Argument +.Fa length +should point to a location that will hold the number of bytes used +by the abbrevation in the DWARF +.Dq ".debug_abbrev" +section. +.Pp +Argument +.Fa attr_count +should point to a location that will hold the number of +attributes in the abbrevation. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory area used for the +.Vt Dwarf_Abbrev +descriptor returned in argument +.Fa ret_abbrev +is allocated by the +.Lb libdwarf . +Application code should use function +.Fn dwarf_dealloc +with the allocation type +.Dv DW_DLA_ABBREV +to free the memory area when the +.Vt Dwarf_Abbrev +descriptor is no longer needed. +.Ss Application Programming Notes +The last abbreviation entry in a standard DWARF abbreviation section +will have a special length value of 1. +.Sh RETURN VALUES +Function +.Fn dwarf_get_abbrev +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no abbreviation information at offset +.Fa offset . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To loop through all the abbreviation information associated with +a DWARF debug context, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Abbrev ab; +Dwarf_Off aboff; +Dwarf_Unsigned length, attr_count; +Dwarf_Half tag; +Dwarf_Error de; +int ret; + +while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, + NULL, NULL, &de)) == DW_DLV_OK) { + while ((ret = dwarf_get_abbrev(re->dbg, aboff, &ab, &length, + &attr_count, &de)) == DW_DLV_OK) { + if (length == 1) /* Last entry. */ + break; + aboff += length; + if (dwarf_get_abbrev_tag(ab, &tag, &de) != DW_DLV_OK) { + warnx("dwarf_get_abbrev_tag failed: %s", + dwarf_errmsg(de)); + continue; + } + if (ret != DW_DLV_OK) + warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de)); +} +if (ret == DW_DLV_ERROR) + warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_abbrev +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa ret_abbrev , +.Fa length +or +.Fa attr_count +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There is no abbreviation information at offset +.Fa offset . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_abbrev_children_flag 3 , +.Xr dwarf_get_abbrev_code 3 , +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/static/netbsd/man3/dwarf_get_abbrev_children_flag.3 b/static/netbsd/man3/dwarf_get_abbrev_children_flag.3 new file mode 100644 index 00000000..998fa1d1 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_abbrev_children_flag.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_get_abbrev_children_flag.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_abbrev_children_flag.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 14, 2011 +.Dt DWARF_GET_ABBREV_CHILDREN_FLAG 3 +.Os +.Sh NAME +.Nm dwarf_get_abbrev_children_flag +.Nd return a flag indicating the presence of children +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_abbrev_children_flag +.Fa "Dwarf_Abbrev abbrev" +.Fa "Dwarf_Signed *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_abbrev_children_flag +retrieves a flag indicating whether the DWARF debug information entry +associated with a DWARF abbreviation descriptor has child entries. +.Pp +Argument +.Fa abbrev +should be a valid DWARF abbreviation descriptor, as returned by +.Xr dwarf_get_abbrev 3 . +.Pp +Argument +.Fa ret +should point to a location which will hold the returned +flag. +The value returned will be one of the following: +.Bl -tag -width ".Dv DW_CHILDREN_yes" -compact +.It Dv DW_CHILDREN_yes +The debugging information entry associated with the +specified abbreviation descriptor has children. +.It Dv DW_CHILDREN_no +The debugging information entry associated with the +specified abbreviation descriptor has no children. +.El +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_abbrev_children_flag +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_abbrev_children_flag +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa abbrev +or +.Fa ret +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_abbrev 3 , +.Xr dwarf_get_abbrev_code 3 , +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/static/netbsd/man3/dwarf_get_abbrev_code.3 b/static/netbsd/man3/dwarf_get_abbrev_code.3 new file mode 100644 index 00000000..775ea911 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_abbrev_code.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: dwarf_get_abbrev_code.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_abbrev_code.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 13, 2011 +.Dt DWARF_GET_ABBREV_CODE 3 +.Os +.Sh NAME +.Nm dwarf_get_abbrev_code +.Nd retrieve the abbreviation code for an abbreviation +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_abbrev_code +.Fa "Dwarf_Abbrev abbrev" +.Fa "Dwarf_Unsigned *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_abbrev_code +retrieves the abbreviation code for the abbreviation entry descriptor +referenced by argument +.Fa abbrev . +.Pp +Argument +.Fa ret +should point to a location which will hold the returned +abbreviation code. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_abbrev_code +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_abbrev_code +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa abbrev +or +.Fa ret +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_abbrev 3 , +.Xr dwarf_get_abbrev_children_flag 3 , +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/static/netbsd/man3/dwarf_get_abbrev_entry.3 b/static/netbsd/man3/dwarf_get_abbrev_entry.3 new file mode 100644 index 00000000..0ed2a9aa --- /dev/null +++ b/static/netbsd/man3/dwarf_get_abbrev_entry.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: dwarf_get_abbrev_entry.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_abbrev_entry.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 02, 2011 +.Dt DWARF_GET_ABBREV_ENTRY 3 +.Os +.Sh NAME +.Nm dwarf_get_abbrev_entry +.Nd retrieve attribute information from an abbreviation descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_abbrev_entry +.Fa "Dwarf_Abbrev abbrev" +.Fa "Dwarf_Signed ndx" +.Fa "Dwarf_Half *code" +.Fa "Dwarf_Signed *form" +.Fa "Dwarf_Off *offset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_abbrev_entry +retrieves attribute information from a DWARF abbreviation descriptor. +.Pp +Argument +.Fa abbrev +should be a valid abbreviation descriptor, as returned by function +.Xr dwarf_get_abbrev 3 . +.Pp +Argument +.Fa ndx +specifies the 0-based index of the attribute. +The total count of the attributes contained in the abbreviation +entry can be retrieved using the function +.Xr dwarf_get_abbrev 3 . +.Pp +Argument +.Fa code +should point to a location which will hold a returned +attribute code. +.Pp +Argument +.Fa form +should point to a location which will hold the returned +form of the attribute. +.Pp +Argument +.Fa offset +should point to a location which will hold a returned offset, relative +to the +.Dq ".debug_abbrev" +section, for the specified attribute. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_abbrev_entry +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if the attribute index specified by argument +.Fa ndx +is out of range. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To loop through all the attribute entries contained in the +abbreviation section, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Abbrev ab; +Dwarf_Off aboff, atoff; +Dwarf_Signed form; +Dwarf_Half attr; +Dwarf_Unsigned length, attr_count; +Dwarf_Error de; +int i, ret; + +/* ...allocate 'dbg' using dwarf_init(3) ... */ + +while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, + NULL, NULL, &de)) == DW_DLV_OK) { + while ((ret = dwarf_get_abbrev(dbg, aboff, &ab, &length, + &attr_count, &de)) == DW_DLV_OK) { + if (length == 1) /* Last entry. */ + break; + aboff += length; + for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { + if (dwarf_get_abbrev_entry(ab, i, + &attr, &form, &atoff, &de) != DW_DLV_OK) { + warnx("dwarf_get_abbrev_entry failed:" + " %s", dwarf_errmsg(de)); + continue; + } + /* .. use the retrieved information ... */ + } + } + + if (ret != DW_DLV_OK) + warnx("dwarf_get_abbrev: %s", dwarf_errmsg(de)); +} + +if (ret == DW_DLV_ERROR) + warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_abbrev_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa abbrev , +.Fa code , +.Fa form +or +.Fa offset +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The attribute index specified by argument +.Fa ndx +was out of range. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_abbrev 3 diff --git a/static/netbsd/man3/dwarf_get_abbrev_tag.3 b/static/netbsd/man3/dwarf_get_abbrev_tag.3 new file mode 100644 index 00000000..bccc09f2 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_abbrev_tag.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: dwarf_get_abbrev_tag.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_abbrev_tag.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd March 13, 2011 +.Dt DWARF_GET_ABBREV_TAG 3 +.Os +.Sh NAME +.Nm dwarf_get_abbrev_tag +.Nd retrieve the tag for an abbreviation +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_abbrev_tag +.Fa "Dwarf_Abbrev abbrev" +.Fa "Dwarf_Half *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_abbrev_tag +retrieves the tag for the abbreviation entry descriptor referenced by +argument +.Fa abbrev . +.Pp +Argument +.Fa ret +should point to a location which will hold the returned +abbreviation tag. +.Pp +If argument +.Fa err +is not +.Dv NULL, +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_abbrev_tag +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_abbrev_tag +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa abbrev +or +.Fa ret +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_abbrev 3 , +.Xr dwarf_get_abbrev_children_flag 3 , +.Xr dwarf_get_abbrev_code 3 , +.Xr dwarf_get_abbrev_entry 3 diff --git a/static/netbsd/man3/dwarf_get_address_size.3 b/static/netbsd/man3/dwarf_get_address_size.3 new file mode 100644 index 00000000..90244a5f --- /dev/null +++ b/static/netbsd/man3/dwarf_get_address_size.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: dwarf_get_address_size.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_address_size.3 3964 2022-03-13 21:41:26Z jkoshy +.\" +.Dd March 13, 2022 +.Dt DWARF_GET_ADDRESS_SIZE 3 +.Os +.Sh NAME +.Nm dwarf_get_address_size +.Nd return the number of bytes needed to represent an address +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_address_size +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half *addr_size" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_address_size +returns the size in bytes of a native address for a program object. +.Pp +Argument +.Fa dbg +should denote a DWARF debug context created from a program object using +.Xr dwarf_init 3 . +Argument +.Fa addr_size +should point to a location that will hold the returned size. +Argument +.Fa err , +if +.No non- Ns Dv NULL , +it will be used to return error information. +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_address_size +returns +.Dv DW_DLV_OK . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_address_size +can fail with the following error: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arguments +.Fa dbg +or +.Fa addr_size +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_finish 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_get_arange.3 b/static/netbsd/man3/dwarf_get_arange.3 new file mode 100644 index 00000000..0bfe0ad4 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_arange.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: dwarf_get_arange.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_arange.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 16, 2011 +.Dt DWARF_GET_ARANGE 3 +.Os +.Sh NAME +.Nm dwarf_get_arange +.Nd retrieve the address range descriptor for an address +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_arange +.Fa "Dwarf_Arange *ar_list" +.Fa "Dwarf_Unsigned ar_cnt" +.Fa "Dwarf_Addr addr" +.Fa "Dwarf_Arange *ret_ar" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_arange +searches an array of +.Vt Dwarf_Arange +descriptors for one that covers a given address. +.Pp +Argument +.Fa ar_list +should point to an array of +.Vt Dwarf_Arange +descriptors. +.Pp +Argument +.Fa ar_cnt +specifies the number of +.Vt Dwarf_Arange +descriptors in the array pointed to by argument +.Fa ar_list . +.Pp +Argument +.Fa addr +specifies the address being looked up. +.Pp +Argument +.Fa ret_ar +will be used to store the +.Vt Dwarf_Arange +descriptor that covers the given address. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_arange +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no +.Vt Dwarf_Arange +descriptor that covers the provided address. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_arange +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa ar_list +or +.Fa ret_ar +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +Value of argument +.Fa ar_cnt +equals to 0. +.It Bq Er DW_DLE_NO_ENTRY +A +.Vt Dwarf_Arange +descriptor that covers the given address +was not found. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_arange_cu_header_offset 3 , +.Xr dwarf_get_arange_info 3 , +.Xr dwarf_get_aranges 3 , +.Xr dwarf_get_cu_die_offset 3 diff --git a/static/netbsd/man3/dwarf_get_arange_info.3 b/static/netbsd/man3/dwarf_get_arange_info.3 new file mode 100644 index 00000000..166b48dd --- /dev/null +++ b/static/netbsd/man3/dwarf_get_arange_info.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: dwarf_get_arange_info.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_arange_info.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 16, 2011 +.Dt DWARF_GET_ARANGE_INFO 3 +.Os +.Sh NAME +.Nm dwarf_get_arange_info +.Nd extract address range information from a descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_arange_info +.Fa "Dwarf_Arange ar" +.Fa "Dwarf_Addr *start" +.Fa "Dwarf_Unsigned *length" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_arange_info +extracts address range information from a +.Vt Dwarf_Arange +descriptor. +.Pp +Argument +.Fa ar +should reference a valid +.Vt Dwarf_Arange +descriptor returned by function +.Xr dwarf_get_aranges 3 . +.Pp +Argument +.Fa start +should point to a location which will hold the start value of the +address range associated with the descriptor. +.Pp +Argument +.Fa length +should point to a location which will hold the length in bytes of the +address range associated with the descriptor. +.Pp +Argument +.Fa cu_die_offset +should point to a location which will be set to an offset, relative to +the +.Dq ".debug_info" +section, of the first debugging information entry in the compilation +unit associated with argument +.Fa ar . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_arange_info +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To loop through all the address lookup table entries, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Addr start; +Dwarf_Arange *aranges; +Dwarf_Off die_off; +Dwarf_Signed i, cnt; +Dwarf_Unsigned length; +Dwarf_Error de; + +if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_aranges: %s", + dwarf_errmsg(de)); +for (i = 0; i < cnt; i++) { + if (dwarf_get_arange_info(aranges[i], &start, &length, + &die_off, &de) != DW_DLV_OK) { + warnx("dwarf_get_arange_info: %s", + dwarf_errmsg(de)); + continue; + } + /* Do something with the returned information. */ +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_arange_info +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa ar , +.Fa start , +.Fa length +or +.Fa cu_die_offset +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_arange 3 , +.Xr dwarf_get_arange_cu_header_offset 3 , +.Xr dwarf_get_aranges 3 , +.Xr dwarf_get_cu_die_offset 3 diff --git a/static/netbsd/man3/dwarf_get_aranges.3 b/static/netbsd/man3/dwarf_get_aranges.3 new file mode 100644 index 00000000..4f174f21 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_aranges.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: dwarf_get_aranges.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_aranges.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_GET_ARANGES 3 +.Os +.Sh NAME +.Nm dwarf_get_aranges +.Nd retrieve program address space mappings +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_aranges +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Arange **ar_list" +.Fa "Dwarf_Signed *ar_cnt" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +The function +.Fn dwarf_get_aranges +retrieves address range information from the +.Dq ".debug_aranges" +DWARF section. +Information about address ranges is returned using opaque descriptors +of type +.Vt Dwarf_Arange , +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa ar_list +should point to a location which will be set to a pointer to an array +of +.Vt Dwarf_Arange +descriptors. +.Pp +Argument +.Fa ar_cnt +should point to a location which will be set to the number of +descriptors returned. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory area used for the array returned in argument +.Fa ar_list +is owned by +.Lb libdwarf . +Application code should not attempt to directly free this area. +Portable applications should instead use +.Xr dwarf_dealloc 3 +to indicate that the memory area may be freed. +.Sh RETURN VALUES +Function +.Fn dwarf_get_aranges +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no +.Dq ".debug_aranges" +section associated with the specified debugging context. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To loop through all the address lookup table entries, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Addr start; +Dwarf_Arange *aranges; +Dwarf_Off die_off; +Dwarf_Signed i, cnt; +Dwarf_Unsigned length; +Dwarf_Error de; + +if (dwarf_get_aranges(dbg, &aranges, &cnt, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_aranges: %s", + dwarf_errmsg(de)); + +for (i = 0; i < cnt; i++) { + if (dwarf_get_arange_info(aranges[i], &start, &length, + &die_off, &de) != DW_DLV_OK) { + warnx("dwarf_get_arange_info: %s", + dwarf_errmsg(de)); + continue; + } + /* Do something with the returned information. */ +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_aranges +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa ar_list +or +.Fa ar_cnt +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The debugging context +.Fa dbg +did not contain a +.Dq ".debug_aranges" +string section. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_arange 3 , +.Xr dwarf_get_arange_cu_header_offset 3 , +.Xr dwarf_get_arange_info 3 , +.Xr dwarf_get_cu_die_offset 3 diff --git a/static/netbsd/man3/dwarf_get_cie_index.3 b/static/netbsd/man3/dwarf_get_cie_index.3 new file mode 100644 index 00000000..e2938313 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_cie_index.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: dwarf_get_cie_index.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_cie_index.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 22, 2011 +.Dt DWARF_GET_CIE_INDEX 3 +.Os +.Sh NAME +.Nm dwarf_get_cie_index +.Nd retrieve the index of a CIE descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_cie_index +.Fa "Dwarf_Cie cie" +.Fa "Dwarf_Signed *cie_index" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_cie_index +retrieves the zero-based index of a given CIE descriptor in the array +of CIE descriptors returned by the functions +.Xr dwarf_get_fde_list 3 +and +.Xr dwarf_get_fde_list_eh 3 . +.Pp +Argument +.Fa cie +should reference a valid DWARF CIE descriptor. +.Pp +Argument +.Fa cie_index +should point to a location that will hold the returned index. +.Sh RETURN VALUES +Function +.Fn dwarf_get_cie_index +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_cie_index +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arugments +.Fa cie +or +.Fa cie_index +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 diff --git a/static/netbsd/man3/dwarf_get_cie_info.3 b/static/netbsd/man3/dwarf_get_cie_info.3 new file mode 100644 index 00000000..e28015b7 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_cie_info.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: dwarf_get_cie_info.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_cie_info.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 29, 2011 +.Dt DWARF_GET_CIE_INFO 3 +.Os +.Sh NAME +.Nm dwarf_get_cie_info +.Nd retrieve information associated with a CIE descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_cie_info +.Fa "Dwarf_Cie cie" +.Fa "Dwarf_Unsigned *cie_byte_len" +.Fa "Dwarf_Small *version" +.Fa "char **augmentation" +.Fa "Dwarf_Unsigned *caf" +.Fa "Dwarf_Unsigned *daf" +.Fa "Dwarf_Half *ra" +.Fa "Dwarf_Ptr *init_inst" +.Fa "Dwarf_Unsigned *inst_len" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_cie_info +retrieves the information associated with a given CIE descriptor. +.Pp +Argument +.Fa cie +should reference a valid DWARF CIE descriptor, such as would be +returned by function +.Xr dwarf_get_cie_of_fde 3 . +.Pp +Argument +.Fa cie_byte_len +should point to a location that will hold the length in bytes of +the CIE descriptor itself. +.Pp +Argument +.Fa version +should point to a location that will hold the version number of +the CIE descriptor. +.Pp +Arugment +.Fa augmentation +should point to a location that will be set to a pointer to a +NUL-terminated string containing augmentation data encoded as UTF-8. +.Pp +Argument +.Fa caf +should point to a location that will hold the code alignment +factor recorded in the CIE descriptor. +.Pp +Arugment +.Fa daf +should point to a location that will hold the data alignment +factor recorded in the CIE descriptor. +.Pp +Argument +.Fa ra +should point to a location that will hold the return address +recorded in the CIE descriptor. +.Pp +Argument +.Fa init_inst +should point to a location that will be set to a pointer to an array +of bytes containing the initial instructions associated with the CIE +descriptor. +.Pp +Argument +.Fa inst_len +should point to a location that will hold the length in bytes +of the initial instructions returned in argument +.Fa init_inst . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_cie_info +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_cie_info +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa cie , +.Fa cie_byte_len , +.Fa version , +.Fa augmentation , +.Fa caf , +.Fa daf , +.Fa ra , +.Fa init_inst +or +.Fa inst_len +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_get_fde_range 3 diff --git a/static/netbsd/man3/dwarf_get_cie_of_fde.3 b/static/netbsd/man3/dwarf_get_cie_of_fde.3 new file mode 100644 index 00000000..0c42e26f --- /dev/null +++ b/static/netbsd/man3/dwarf_get_cie_of_fde.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: dwarf_get_cie_of_fde.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_cie_of_fde.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 22, 2011 +.Dt DWARF_GET_CIE_OF_FDE 3 +.Os +.Sh NAME +.Nm dwarf_get_cie_of_fde +.Nd retrieve CIE descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_cie_of_fde +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Cie *ret_cie" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_cie_of_fde +retrieves the CIE descriptor associated with a given FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid FDE descriptor. +.Pp +Argument +.Fa ret_cie +should point to a location that will hold the returned CIE +descriptor. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_cie_of_fde +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_cie_of_fde +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of arugments +.Fa fde +or +.Fa ret_cie +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_n 3 diff --git a/static/netbsd/man3/dwarf_get_cu_die_offset.3 b/static/netbsd/man3/dwarf_get_cu_die_offset.3 new file mode 100644 index 00000000..f0946303 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_cu_die_offset.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: dwarf_get_cu_die_offset.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_cu_die_offset.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd April 10, 2011 +.Dt DWARF_GET_CU_DIE_OFFSET 3 +.Os +.Sh NAME +.Nm dwarf_get_arange_cu_header_offset , +.Nm dwarf_get_cu_die_offset +.Nd retrieve compilation unit offsets +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_arange_cu_header_offset +.Fa "Dwarf_Arange ar" +.Fa "Dwarf_Off *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_cu_die_offset +.Fa "Dwarf_Arange ar" +.Fa "Dwarf_Off *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve the offsets, relative to the +.Dq ".debug_info" +DWARF section, of the debugging information entries describing the +compilation unit associated with a +.Vt Dwarf_Arange +descriptor. +.Pp +Function +.Fn dwarf_get_arange_cu_header_offset +retrieves the offset of the compilation unit header associated with +argument +.Fa ar , +and stores it in the location pointed to by argument +.Fa ret . +.Pp +Function +.Fn dwarf_get_cu_die_offset +retrieves the offset of the debugging information entry for the +compilation unit associated with argument +.Fa ar , +and stores it in the location pointed to by argument +.Fa ret . +.Pp +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa ar +was not a valid +.Vt Dwarf_Arange +descriptor. +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa ret +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_arange 3 , +.Xr dwarf_get_arange_info 3 , +.Xr dwarf_get_aranges 3 diff --git a/static/netbsd/man3/dwarf_get_die_infotypes_flag.3 b/static/netbsd/man3/dwarf_get_die_infotypes_flag.3 new file mode 100644 index 00000000..6784cc81 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_die_infotypes_flag.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: dwarf_get_die_infotypes_flag.3,v 1.5 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_die_infotypes_flag.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd December 20, 2014 +.Dt DWARF_GET_DIE_INFOTYPES_FLAG 3 +.Os +.Sh NAME +.Nm dwarf_get_die_infotypes_flag +.Nd indicate the originating DWARF section for a DIE +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Bool +.Fo dwarf_get_die_infotypes_flag +.Fa "Dwarf_Die die" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_die_infotypes_flag +returns a flag indicating the originating DWARF section for the +debugging information entry referenced by argument +.Fa die . +.Pp +Argument +.Fa die +should reference a valid debugging information entry descriptor. +.Sh RETURN VALUES +Function +.Fn dwarf_get_die_infotypes_flag +returns a non-zero value if argument +.Fa die +originates in the +.Dq .debug_info +section. +.Pp +It returns zero if argument +.Fa die +originates in the +.Dq .debug_types +section. +.Sh ERRORS +Function +.Fn dwarf_get_die_infotypes_flag +always succeeds. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_next_cu_header_c 3 , +.Xr dwarf_offdie_b 3 , +.Xr dwarf_siblingof_b 3 diff --git a/static/netbsd/man3/dwarf_get_elf.3 b/static/netbsd/man3/dwarf_get_elf.3 new file mode 100644 index 00000000..b17d8033 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_elf.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: dwarf_get_elf.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2009 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_get_elf.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_GET_ELF 3 +.Os +.Sh NAME +.Nm dwarf_get_elf +.Nd retrieve the +.Vt Elf +descriptor associated with a +.Vt Dwarf_Debug +instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_elf +.Fa "Dwarf_Debug dbg" +.Fa "Elf **elf" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_elf +returns the +.Vt Elf +descriptor associated with a +.Vt Dwarf_Debug +instance. +.Pp +Argument +.Fa dbg +should be a handle to a valid +.Vt Dwarf_Debug +instance returned by a prior call to +.Xr dwarf_init 3 +or +.Xr dwarf_elf_init 3 . +.Pp +Argument +.Fa elf +points a location into which a handle to an +.Vt Elf +descriptor will be written. +.Pp +Argument +.Fa err +is used to record error information in case of failure. +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_elf +returns +.Dv DW_DLV_OK . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh EXAMPLES +To retrieve the +.Vt Elf +instance associated with a +.Vt Dwarf_Debug +instance use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Error de; +Elf *elf; + +\&... allocate dbg using dwarf_init() etc ... + +if (dwarf_get_elf(dbg, &elf, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_elf: %s", dwarf_errmsg(de)); +.Ed +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errmsg 3 , +.Xr dwarf_finish 3 , +.Xr dwarf_init 3 , +.Xr elf 3 diff --git a/static/netbsd/man3/dwarf_get_fde_at_pc.3 b/static/netbsd/man3/dwarf_get_fde_at_pc.3 new file mode 100644 index 00000000..728e8788 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_at_pc.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: dwarf_get_fde_at_pc.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_at_pc.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 22, 2011 +.Dt DWARF_GET_FDE_AT_PC 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_at_pc +.Nd retrieve the FDE descriptor for an address +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_at_pc +.Fa "Dwarf_Fde *fdelist" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Fde *ret_fde" +.Fa "Dwarf_Addr *lopc" +.Fa "Dwarf_Addr *hipc" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_at_pc +searches the provided array of DWARF FDE descriptors for a descriptor +covering a given program counter address. +.Pp +Argument +.Fa fdelist +should point to an array of FDE descriptors, as returned by the functions +.Xr dwarf_get_fde_list 3 +or +.Xr dwarf_get_fde_list_eh 3 . +.Pp +Argument +.Fa pc +should contain the program counter address being looked up. +.Pp +Argument +.Fa ret_fde +should point to a location that will hold the returned FDE descriptor. +.Pp +Argument +.Fa lopc +should point to a location that will be set to the lowest address +covered by the returned FDE descriptor. +.Pp +Argument +.Fa hipc +should point to a location that will be set to the highest address +covered by the returned FDE descriptor. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_at_pc +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if a FDE descriptor that covers the address specified by argument +.Fa pc +is not found. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_at_pc +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va fdelist , +.Va ret_fde , +.Va lopc , +or +.Va hipc +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +These was no FDE descriptor covering the address specified by argument +.Fa pc . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_get_fde_range 3 diff --git a/static/netbsd/man3/dwarf_get_fde_info_for_all_regs.3 b/static/netbsd/man3/dwarf_get_fde_info_for_all_regs.3 new file mode 100644 index 00000000..7bf9cb5f --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_info_for_all_regs.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: dwarf_get_fde_info_for_all_regs.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_info_for_all_regs.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 4, 2011 +.Dt DWARF_GET_FDE_INFO_FOR_ALL_REGS 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_info_for_all_regs +.Nd retrieve register rule row +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_info_for_all_regs +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Regtable *reg_table" +.Fa "Dwarf_Addr *row_pc" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_info_for_all_regs +retrieves a row from the register rule table associated with the given +FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Argument +.Fa pc +should hold the program counter address to be used to locate the +desired table row. +.Pp +Argument +.Fa reg_table +should point to a +.Vt Dwarf_Regtable +descriptor which will hold the returned table row of register rules. +.Pp +Argument +.Fa row_pc +should point to a location which will be set to the lowest program +counter address associated with the table row. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +The +.Vt Dwarf_Regtable +descriptor is defined in the header file +.In libdwarf.h : +.Bd -literal -offset indent +typedef struct { + struct { + Dwarf_Small dw_offset_relevant; + Dwarf_Half dw_regnum; + Dwarf_Addr dw_offset; + } rules[DW_REG_TABLE_SIZE]; +} Dwarf_Regtable; +.Ed +.Pp +For each of the register rules returned, +the +.Va dw_offset_relevant +field is set to 1 if the register rule has a offset value. +The +.Va dw_regnum +field is set to the register number associated with the regsiter rule. +The +.Va dw_offset +field is set to the offset value associated with the register rule. +.Pp +The number of register columns returned is either the constant +value +.Dv DW_REG_TABLE_SIZE as defined +in the header file +.In libdwarf.h , +or the value set by function +.Xr dwarf_set_frame_rule_table_size 3 , +whichever is smaller. +.Ss COMPATIBILITY +Function +.Fn dwarf_get_fde_info_for_all_regs +is deprecated since it only supports DWARF2 frame sections. +Applications should instead use function +.Xr dwarf_get_fde_info_for_all_regs3 3 +which supports both DWARF2 and DWARF3 frame sections. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_info_for_all_regs +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_all_regs +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa fde , +.Fa reg_table +or +.Fa row_pc +was +.Dv NULL . +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Fa pc +did not fall in the range covered by argument +.Fa fde . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_info_for_all_regs3.3 b/static/netbsd/man3/dwarf_get_fde_info_for_all_regs3.3 new file mode 100644 index 00000000..ec9b4e7b --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_info_for_all_regs3.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: dwarf_get_fde_info_for_all_regs3.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_info_for_all_regs3.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 26, 2011 +.Dt DWARF_GET_FDE_INFO_FOR_ALL_REGS3 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_info_for_all_regs3 +.Nd retrieve register rule row +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_info_for_all_regs3 +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Regtable3 *reg_table" +.Fa "Dwarf_Addr *row_pc" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_info_for_all_regs3 +retrieves a row from the register rule table associated with the given +FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Argument +.Fa pc +should hold the program counter address to be used to locate the +desired table row. +.Pp +Argument +.Fa reg_table +should point to a +.Vt Dwarf_Regtable3 +descriptor which will hold the returned table row of register rules. +The +.Vt Dwarf_Regtable3 +descriptor is defined in the header file +.In libdwarf.h : +.Bd -literal -offset indent +typedef struct { + Dwarf_Small dw_offset_relevant; + Dwarf_Small dw_value_type; + Dwarf_Half dw_regnum; + Dwarf_Unsigned dw_offset_or_block_len; + Dwarf_Ptr dw_block_ptr; +} Dwarf_Regtable_Entry3; + +typedef struct { + Dwarf_Regtable_Entry3 rt3_cfa_rule; + Dwarf_Half rt3_reg_table_size; + Dwarf_Regtable_Entry3 *rt3_rules; +} Dwarf_Regtable3; +.Ed +.Pp +The +.Va rt3_reg_table_size +field specifies the maximum number of register rule columns to be +returned, and should be set by the application before calling the +function. +The +.Va rt3_rules +field should point to a memory arena allocated by the application with +space for at least +.Vt rt3_reg_table_size +descriptors of type +.Vt Dwarf_Regtable_Entry3 . +.Pp +On a successful execution of this function, the +.Va rt3_cfa_rule +field will be set to the CFA register rule associated with the table +row, and the +.Va rt3_rules +array will hold the returned register rules contained in the table row. +.Pp +For each register rule descriptor returned, +the +.Va dw_offset_relevant +field will be set to 1 if the register rule has a offset value, +the +.Va dw_value_type +field will be set to the type code of the register rule and the +.Va dw_regnum +field will be set to the register number associated with the register rule. +If the register rule is of type +.Dv DW_EXPR_OFFSET +or +.Dv DW_EXPR_VAL_OFFSET , +the +.Va dw_offset_or_block_len +field will be set to the offset value associated with the register rule. +If the type is +.Dv DW_EXPR_EXPRESSION +or +.Dv DW_EXPR_VAL_EXPRESSION , +the +.Va dw_offset_or_block_len +field will be set to the length in bytes of the DWARF expression block +associated with the register rule. +The +.Va dw_block_ptr +field will be set to a pointer to the content of the DWARF expression block +associated with the register rule. +.Pp +Argument +.Fa row_pc +should point to a location which will be set to the lowest program +counter address associated with the table row. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_info_for_all_regs3 +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_all_regs3 +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa fde , +.Fa reg_table +or +.Fa row_pc +was +.Dv NULL . +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Fa pc +did not fall in the range covered by argument +.Fa fde . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_info_for_cfa_reg3.3 b/static/netbsd/man3/dwarf_get_fde_info_for_cfa_reg3.3 new file mode 100644 index 00000000..e0294a5f --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_info_for_cfa_reg3.3 @@ -0,0 +1,175 @@ +.\" $NetBSD: dwarf_get_fde_info_for_cfa_reg3.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_info_for_cfa_reg3.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 12, 2011 +.Dt DWARF_GET_FDE_INFO_FOR_CFA_REGS3 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_info_for_cfa_regs3 +.Nd retrieve a CFA register rule +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_info_for_cfa_regs3 +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Small *type" +.Fa "Dwarf_Signed *offset_relevant" +.Fa "Dwarf_Signed *register_num" +.Fa "Dwarf_Signed *offset_or_block_len" +.Fa "Dwarf_Ptr *block_ptr" +.Fa "Dwarf_Addr *row_pc" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_info_for_cfa_reg3 +retrieves the CFA register rule for a given program counter address +from the register rule table associated with an FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Argument +.Fa pc +should hold the program counter address to be used to locate the +desired register rule row. +.Pp +On successful execution, +.Fn dwarf_get_fde_info_for_cfa_reg3 +stores information about the CFA register rule found into the locations +pointed to by the arguments +.Fa type , +.Fa offset_relevant , +.Fa register_num , +.Fa offset_or_block_len , +.Fa block_ptr +and +.Fa row_pc . +.Pp +Argument +.Fa type +should point to a location which will hold the type code of the +register rule found. +The returned value is one of the +.Dv DW_EXPR_* +contants defined in the header file +.In libdwarf.h . +.Pp +If there is an offset value associated with the CFA register rule, +the location pointed to by argument +.Fa offset_relevant +will be set to 1. +.Pp +Argument +.Fa register_num +should point to a location which will hold the register number associated +with the CFA register rule. +.Pp +If the CFA register rule is of type +.Dv DW_EXPR_OFFSET +or +.Dv DW_EXPR_VAL_OFFSET , +the location pointed to by argument +.Fa offset_or_block_len +will be set to the offset value associated with the register rule, +or to 0 if the register rule does not have an offset value. +If the type code is +.Dv DW_EXPR_EXPRESSION +or +.Dv DW_EXPR_VAL_EXPRESSION , +the location pointed to by argument +.Fa offset_or_block_len +will be set to the length in bytes of the DWARF expression block +associated with the register rule. +.Pp +Argument +.Fa block_ptr +should point to a location which will be set to a pointer to the +content of the DWARF expression block associated with the CFA register +rule. +.Pp +Argument +.Fa row_pc +should point to a location which will be set to the lowest program +counter address associated with the register rule found. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_info_for_cfa_reg3 +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_cfa_reg3 +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa block_ptr , +.Fa fde , +.Fa offset_or_block_len , +.Fa offset_relevant , +.Fa register_num , +.Fa row_pc , +or +.Fa type +was +.Dv NULL . +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Fa pc +did not fall in the range covered by argument +.Fa fde . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_info_for_reg.3 b/static/netbsd/man3/dwarf_get_fde_info_for_reg.3 new file mode 100644 index 00000000..abdbb161 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_info_for_reg.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: dwarf_get_fde_info_for_reg.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_info_for_reg.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd June 4, 2011 +.Dt DWARF_GET_FDE_INFO_FOR_REG 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_info_for_reg +.Nd retrieve register rule +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_info_for_reg +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Half table_column" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Signed *offset_relevant" +.Fa "Dwarf_Signed *register_num" +.Fa "Dwarf_Signed *offset" +.Fa "Dwarf_Addr *row_pc" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_info_for_reg +retrieves a register rule from the register rule table associated with +a given FDE descriptor, given a program counter address and rule +column number. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Arugment +.Fa table_column +should hold the column number of the register rule desired. +.Pp +Argument +.Fa pc +should hold the program counter address to be used to locate the +desired register rule row. +.Pp +On successful execution, +.Fn dwarf_get_fde_info_for_reg +stores information about the register rule found into the locations +pointed to by the arguments +.Fa offset_relevant , +.Fa register_num , +.Fa offset +and +.Fa row_pc . +.Pp +If there is an offset value associated with the register rule, +the location pointed to by argument +.Fa offset_relevant +will be set to 1. +.Pp +Argument +.Fa register_num +should point to a location which will hold the register number associated +with the register rule. +.Pp +Argument +.Fa offset +should point to a location which will be set to the offset value +associated with the register rule, or to 0 if the register rule +does not have an offset value. +.Pp +Argument +.Fa row_pc +should point to a location which will be set to the lowest program +counter address associated with the register rule found. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Ss COMPATIBILITY +Function +.Fn dwarf_get_fde_info_for_reg +is deprecated since it only supports DWARF2 frame sections. +Applications should instead use function +.Xr dwarf_get_fde_info_for_reg3 3 +which supports both DWARF2 and DWARF3 frame sections. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_info_for_reg +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_reg +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa fde , +.Fa offset_relevant , +.Fa register_num , +.Fa offset +or +.Fa row_pc +was +.Dv NULL . +.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD +The column number provided in argument +.Fa table_column +was too large. +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Fa pc +did not fall in the range covered by argument +.Fa fde . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_info_for_reg3.3 b/static/netbsd/man3/dwarf_get_fde_info_for_reg3.3 new file mode 100644 index 00000000..7e3396b3 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_info_for_reg3.3 @@ -0,0 +1,218 @@ +.\" $NetBSD: dwarf_get_fde_info_for_reg3.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_info_for_reg3.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_GET_FDE_INFO_FOR_REG3 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_info_for_reg3 +.Nd retrieve register rule +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_info_for_reg3 +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Half table_column" +.Fa "Dwarf_Addr pc" +.Fa "Dwarf_Small *type" +.Fa "Dwarf_Signed *offset_relevant" +.Fa "Dwarf_Signed *register_num" +.Fa "Dwarf_Signed *offset_or_block_len" +.Fa "Dwarf_Ptr *block_ptr" +.Fa "Dwarf_Addr *row_pc" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_info_for_reg3 +retrieves a register rule from the register rule table associated with +a given FDE descriptor, given a program counter address and rule +column number. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Arugment +.Fa table_column +should hold the column number of the register rule desired. +.Pp +Argument +.Fa pc +should hold the program counter address to be used to locate the +desired register rule row. +.Pp +On successful execution, +.Fn dwarf_get_fde_info_for_reg3 +stores information about the register rule found into the locations +pointed to by the arguments +.Fa type , +.Fa offset_relevant , +.Fa register_num , +.Fa offset_or_block_len , +.Fa block_ptr +and +.Fa row_pc . +.Pp +Argument +.Fa type +should point to a location which will hold the type code of the +register rule found. +The returned value is one of the +.Dv DW_EXPR_* +contants defined in the header file +.In libdwarf.h . +.Pp +If there is an offset value associated with the register rule, +the location pointed to by argument +.Fa offset_relevant +will be set to 1. +.Pp +Argument +.Fa register_num +should point to a location which will hold the register number associated +with the register rule. +.Pp +If the register rule is of type +.Dv DW_EXPR_OFFSET +or +.Dv DW_EXPR_VAL_OFFSET , +the location pointed to by argument +.Fa offset_or_block_len +will be set to the offset value associated with the register rule, +or to 0 if the register rule does not have an offset value. +If the type code is +.Dv DW_EXPR_EXPRESSION +or +.Dv DW_EXPR_VAL_EXPRESSION , +the location pointed to by argument +.Fa offset_or_block_len +will be set to the length in bytes of the DWARF expression block +associated with the register rule. +.Pp +Argument +.Fa block_ptr +should point to a location which will be set to a pointer to the +content of the DWARF expression block associated with the register +rule. +.Pp +Argument +.Fa row_pc +should point to a location which will be set to the lowest program +counter address associated with the register rule found. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_info_for_reg3 +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To retrieve the register rules at column 3 from a rule table +associated with a FDE descriptor: +.Bd -literal -offset indent +Dwarf_Fde fde; +Dwarf_Off fde_offset, cie_offset; +Dwarf_Unsigned func_len, fde_length; +Dwarf_Signed cie_index, offset_relevant, register_num; +Dwarf_Signed offset_or_block_len; +Dwarf_Addr low_pc, row_pc; +Dwarf_Ptr fde_addr, block_ptr; +Dwarf_Small type; +Dwarf_Error de; + +/* ... assuming `fde` references a valid FDE descriptor... */ +if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, + &fde_length, &cie_offset, &cie_index, &fde_offset, + &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_get_fde_range failed: %s", + dwarf_errmsg(de)); + +/* Iterate all the table rows. */ +for (pc = low_pc; pc < low_pc + func_len; pc++) { + if (dwarf_get_fde_info_for_reg3(fde, 3, pc, &type, + &offset_relevant, ®ister_num, &offset_or_block_len, + &block_ptr, &row_pc, &de) != DW_DLV_OK) { + warnx("dwarf_get_fde_info_for_reg3 failed: %s", + dwarf_errmsg(de)); + continue; + } + /* ... use the retrieved register rule ... */ +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_reg3 +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa block_ptr , +.Fa fde , +.Fa offset_or_block_len , +.Fa offset_relevant , +.Fa register_num , +.Fa row_pc , +or +.Fa type +was +.Dv NULL . +.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD +The column number provided in argument +.Fa table_column +was too large. +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Fa pc +did not fall in the range covered by argument +.Fa fde . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_instr_bytes.3 b/static/netbsd/man3/dwarf_get_fde_instr_bytes.3 new file mode 100644 index 00000000..9af796a9 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_instr_bytes.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: dwarf_get_fde_instr_bytes.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_instr_bytes.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 23, 2011 +.Dt DWARF_GET_FDE_INSTR_BYTES 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_instr_bytes +.Nd retrieve instructions from FDE descritpor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_instr_bytes +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Ptr *ret_inst" +.Fa "Dwarf_Unsigned *ret_len" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_instr_bytes +retrieves instruction bytes from a given FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Argument +.Fa ret_inst +should point to a location that will be set to a pointer +to an array of bytes containing the instructions of the +FDE descriptor. +.Pp +Argument +.Fa ret_len +should point to a location that will hold the length in +bytes of the instructions returned in argument +.Fa ret_inst . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Applications can use the function +.Xr dwarf_expand_frame_instructions 3 +to parse and expand the returned instruction bytes into an array of +.Vt Dwarf_Frame_Op +descriptors. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_instr_bytes +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_instr_bytes +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa fde , +.Fa ret_inst +or +.Fa ret_len +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_expand_frame_instructions 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_get_fde_range 3 diff --git a/static/netbsd/man3/dwarf_get_fde_list.3 b/static/netbsd/man3/dwarf_get_fde_list.3 new file mode 100644 index 00000000..38c31352 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_list.3 @@ -0,0 +1,222 @@ +.\" $NetBSD: dwarf_get_fde_list.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_list.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_GET_FDE_LIST 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_list +.Nd retrieve frame information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_list +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Cie **cie_list" +.Fa "Dwarf_Signed *cie_count" +.Fa "Dwarf_Fde **fde_list" +.Fa "Dwarf_Signed *fde_count" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_fde_list_eh +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Cie **cie_list" +.Fa "Dwarf_Signed *cie_count" +.Fa "Dwarf_Fde **fde_list" +.Fa "Dwarf_Signed *fde_count" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve frame related information for the specified +DWARF debug context. +.Pp +Function +.Fn dwarf_get_fde_list +retrieves frame information from the DWARF section named +.Dq ".debug_frame" . +For objects containing GNU style C++ exception handling +information, the function +.Fn dwarf_get_fde_list_eh +retrieves frame information from the section named +.Dq ".eh_frame" . +.Pp +Frame information is returned using opaque descriptors +of type +.Vt Dwarf_Cie +and +.Vt Dwarf_Fde . +Applications need to use the other frame related functions in the +DWARF(3) API set to retrieve the information contained in these +descriptors. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa cie_list +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Cie +descriptors. +.Pp +Argument +.Fa cie_count +should point to a location that will be set to the number of +.Vt Dwarf_Cie +descriptors returned. +.Pp +Argument +.Fa fde_list +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Fde +descriptors. +.Pp +Argument +.Fa fde_count +should point to a location that will be set to the number of +.Vt Dwarf_Fde +descriptors returned. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory areas used for the arrays returned in arguments +.Fa cie_list +and +.Fa fde_list +are owned by the +.Lb libdwarf . +Application code should not attempt to directly free these areas. +Portable applications should instead use the +.Xr dwarf_fde_cie_list_dealloc 3 +function to indicate that these memory areas may be freed. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +They return +.Dv DW_DLV_NO_ENTRY +if there is no frame information associated with the given DWARF +debug context. +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh EXAMPLES +To obtain frame information from the +.Dq ".debug_frame" +section, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Cie *cie_list, cie; +Dwarf_Fde *fde_list, fde; +Dwarf_Off fde_offset, cie_offset; +Dwarf_Unsigned func_len, fde_length, fde_instlen; +Dwarf_Signed cie_count, fde_count, cie_index; +Dwarf_Addr low_pc; +Dwarf_Ptr fde_addr, fde_inst, cie_inst; +Dwarf_Error de; +int i; + +if (dwarf_get_fde_list(dbg, &cie_list, &cie_count, + &fde_list, &fde_count, &de) != DW_DLV_OK) { + errx(EXIT_FAILURE, "dwarf_get_fde_list failed: %s", + dwarf_errmsg(de)); +} + +for (i = 0; i < fde_count; i++) { + if (dwarf_get_fde_n(fde_list, i, &fde, &de) != DW_DLV_OK) { + warnx("dwarf_get_fde_n failed: %s", + dwarf_errmsg(de)); + continue; + } + if (dwarf_get_cie_of_fde(fde, &cie, &de) != DW_DLV_OK) { + warnx("dwarf_get_fde_n failed: %s", + dwarf_errmsg(de)); + continue; + } + if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, + &fde_length, &cie_offset, &cie_index, &fde_offset, + &de) != DW_DLV_OK) { + warnx("dwarf_get_fde_range failed: %s", + dwarf_errmsg(de)); + continue; + } + if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, + &de) != DW_DLV_OK) { + warnx("dwarf_get_fde_instr_bytes failed: %s", + dwarf_errmsg(de)); + continue; + } + + /* ... Use the retrieved frame information ... */ +} + +/* Indicate that the returned arrays may be freed. */ +dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list, + fde_count); +.Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va dbg , +.Va cie_list , +.Va cie_count , +.Va fde_list +or +.Va fde_count +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There is no frame information associated with the giving DWARF debug +context. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_fde_cie_list_dealloc 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_n 3 , +.Xr dwarf_get_fde_range 3 , +.Xr dwarf_set_frame_cfa_value 3 , +.Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , +.Xr dwarf_set_frame_same_value 3 , +.Xr dwarf_set_frame_undefined_value 3 diff --git a/static/netbsd/man3/dwarf_get_fde_n.3 b/static/netbsd/man3/dwarf_get_fde_n.3 new file mode 100644 index 00000000..a26794a2 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_n.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: dwarf_get_fde_n.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_n.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 14, 2011 +.Dt DWARF_GET_FDE_N 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_n +.Nd retrieve FDE descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_n +.Fa "Dwarf_Fde *fdelist" +.Fa "Dwarf_Unsigned fde_index" +.Fa "Dwarf_Fde *ret_fde" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_n +retrieves an FDE descriptor from an array of FDE descriptors. +.Pp +Argument +.Fa fdelist +should point to an array of FDE descriptors, as returned by the functions +.Xr dwarf_get_fde_list 3 +or +.Xr dwarf_get_fde_list_eh 3 . +.Pp +Argument +.Fa fde_index +specifies the 0-based index of the desired FDE descriptor. +.Pp +Argument +.Fa ret_fde +should point to a location that will hold the returned FDE descriptor. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_n +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if the FDE descriptor index specified by argument +.Fa fde_index +is out of range. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_n +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Fa fdelist +or +.Fa ret_fde +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The FDE descriptor index specified by argument +.Fa fde_index +was out of range. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_range 3 diff --git a/static/netbsd/man3/dwarf_get_fde_range.3 b/static/netbsd/man3/dwarf_get_fde_range.3 new file mode 100644 index 00000000..02629220 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_fde_range.3 @@ -0,0 +1,153 @@ +.\" $NetBSD: dwarf_get_fde_range.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_fde_range.3 3962 2022-03-12 15:56:10Z jkoshy +.\" +.Dd May 22, 2011 +.Dt DWARF_GET_FDE_RANGE 3 +.Os +.Sh NAME +.Nm dwarf_get_fde_range +.Nd retrieve range information from an FDE descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_fde_range +.Fa "Dwarf_Fde fde" +.Fa "Dwarf_Addr *low_pc" +.Fa "Dwarf_Unsigned *func_len" +.Fa "Dwarf_Ptr *fde_bytes" +.Fa "Dwarf_Unsigned *fde_byte_len" +.Fa "Dwarf_Off *cie_offset" +.Fa "Dwarf_Signed *cie_index" +.Fa "Dwarf_Off *fde_offset" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_fde_range +retrieves range and offset information from a given FDE descriptor. +.Pp +Argument +.Fa fde +should reference a valid DWARF FDE descriptor. +.Pp +Argument +.Fa low_pc +should point to a location that will be set to the lowest +program counter address covered by the FDE descriptor. +.Pp +Argument +.Fa func_len +should point to a location that will hold the length in bytes of +the address range covered by the FDE descriptor. +.Pp +Argument +.Fa fde_bytes +should point to a location that will be set to a pointer to the +content of the FDE descriptor itself. +.Pp +Argument +.Fa fde_byte_len +should point to a location that will hold the length in bytes of +the FDE descriptor itself. +.Pp +Argument +.Fa cie_offset +should point to a location that will be set to the offset, relative to +the DWARF +.Dq ".debug_frame" +section, of the CIE descriptor associated with the given FDE +descriptor. +.Pp +Argument +.Fa cie_index +should point to a location that will hold the index of the CIE +descriptor associated with the FDE descriptor. +The returned value is a zero-based index into the array of CIE +descriptors returned by a prior call to functions +.Xr dwarf_get_fde_list 3 +or +.Xr dwarf_get_fde_list_eh 3 . +.Pp +Argument +.Fa fde_offset +should point to a location that will be set to the offset, relative to +the DWARF +.Dq ".debug_frame" +section, of the FDE descriptor. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_fde_range +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_fde_range +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa fde , +.Fa low_pc , +.Fa func_len , +.Fa fde_bytes , +.Fa fde_byte_len , +.Fa cie_offset , +.Fa cie_index +or +.Fa fde_offset +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_instr_bytes 3 , +.Xr dwarf_get_fde_list 3 , +.Xr dwarf_get_fde_list_eh 3 , +.Xr dwarf_get_fde_n 3 diff --git a/static/netbsd/man3/dwarf_get_form_class.3 b/static/netbsd/man3/dwarf_get_form_class.3 new file mode 100644 index 00000000..f78d7b9c --- /dev/null +++ b/static/netbsd/man3/dwarf_get_form_class.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: dwarf_get_form_class.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_form_class.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd June 26, 2011 +.Dt DWARF_GET_FORM_CLASS 3 +.Os +.Sh NAME +.Nm dwarf_get_form_class +.Nd retrieve the form class of an attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft enum Dwarf_Form_Class +.Fo dwarf_get_form_class +.Fa "Dwarf_Half dwversion" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Half offset_size" +.Fa "Dwarf_Half form" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_form_class +returns the class of the form of a DWARF attribute. +.Pp +Argument +.Fa dwversion +should specify the version number of DWARF specification +to use: 2 for DWARF2, 3 for DWARF3 and 4 for DWARF4. +.Pp +Argument +.Fa attr +should hold the attribute code of the attribute, i.e., one of the +.Li DW_AT_* +values defined in +.In libdwarf.h . +.Pp +Argument +.Fa offset_size +should hold the size of a DWARF offset for the relevant compilation +unit. +.Pp +Argument +.Fa form +should hold the form code of the attribute. +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_form_class +returns the form class code, which is one of the +.Dv DW_FORM_CLASS_* +contants defined in header file +.In libdwarf.h . +If the function was not able to determine the form class of the +attribute, it returns the special form class code +.Dv DW_FORM_CLASS_UNKNOWN . +.Sh ERRORS +Function +.Fn dwarf_get_form_class +does not return an error. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_whatattr 3 , +.Xr dwarf_whatform 3 diff --git a/static/netbsd/man3/dwarf_get_funcs.3 b/static/netbsd/man3/dwarf_get_funcs.3 new file mode 100644 index 00000000..472715f2 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_funcs.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: dwarf_get_funcs.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_funcs.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 10, 2011 +.Dt DWARF_GET_FUNCS 3 +.Os +.Sh NAME +.Nm dwarf_get_funcs , +.Nm dwarf_func_cu_offset , +.Nm dwarf_func_die_offset , +.Nm dwarf_func_name_offsets , +.Nm dwarf_funcname +.Nd retrieve information about static functions +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_funcs +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Func **funcs" +.Fa "Dwarf_Signed *nfuncs" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_func_cu_offset +.Fa "Dwarf_Func func" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_func_die_offset +.Fa "Dwarf_Func func" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_func_name_offsets +.Fa "Dwarf_Func func" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_funcname +.Fa "Dwarf_Func func" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve information about static functions from the +lookup tables in the (SGI-specific) +.Dq ".debug_funcnames" +section. +Information about these functions is returned using opaque descriptors +of type +.Vt Dwarf_Func . +Applications need to use the functions described below to retrieve +the name and offset information contained in these descriptors. +.Pp +Function +.Fn dwarf_get_funcs +retrieves descriptors for all the static functions associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa funcs +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Func +descriptors. +The argument +.Fa nfuncs +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_func_cu_offset +returns the offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that contains the debugging +information entry associated with the argument +.Fa func . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_func_die_offset +retrieves the offset, relative to the +.Dq ".debug_info" +section, of the debugging information entry associated with the +argument +.Fa func , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_func_name_offsets +retrieves the name and offsets for the debugging information entry for +argument +.Fa func . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to the offset, relative +to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to the offset, relative +to the +.Dq ".debug_info" +section, of the first debugging information entry in the compilation +unit associated with argument +.Fa func . +.Pp +Function +.Fn dwarf_funcname +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa func . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Func +descriptors returned in argument +.Fa funcs +by function +.Fn dwarf_get_funcs +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_funcs_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_func_name_offsets +and +.Fn dwarf_funcname +is owned by the +.Lb libdwarf . +Portable code should indicate that the memory area can +be freed using the +.Xr dwarf_dealloc 3 +function. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va func , +.Va funcs , +.Va name , +or +.Va nfuncs +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The DWARF debugging context referenced by argument +.Fa dbg +did not contain information about static functions. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_funcs_dealloc 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 diff --git a/static/netbsd/man3/dwarf_get_globals.3 b/static/netbsd/man3/dwarf_get_globals.3 new file mode 100644 index 00000000..0d24b3f1 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_globals.3 @@ -0,0 +1,216 @@ +.\" $NetBSD: dwarf_get_globals.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_globals.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 2, 2011 +.Dt DWARF_GET_GLOBALS 3 +.Os +.Sh NAME +.Nm dwarf_get_globals , +.Nm dwarf_global_cu_offset , +.Nm dwarf_global_die_offset , +.Nm dwarf_global_name_offsets , +.Nm dwarf_globname +.Nd retrieve information about global objects +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_globals +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Global **globals" +.Fa "Dwarf_Signed *nglobals" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_global_cu_offset +.Fa "Dwarf_Global global" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_global_die_offset +.Fa "Dwarf_Global global" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_global_name_offsets +.Fa "Dwarf_Global global" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_globname +.Fa "Dwarf_Global global" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve information about global symbols from the +lookup tables in the +.Dq ".debug_pubnames" +DWARF section. +Information about these global symbols is returned using opaque descriptors +of type +.Vt Dwarf_Global . +Applications need to use the functions described below to retrieve the +name and the offsets for these descriptors. +.Pp +Function +.Fn dwarf_get_globals +retrieves descriptors for all the global symbols associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa globals +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Global +descriptors. +The argument +.Fa nglobals +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_global_cu_offset +returns the section-relative offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that contains the debugging +information entry associated with the argument +.Fa global . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_global_die_offset +retrieves the section-relative offset, relative to the +.Dq ".debug_info" +section, of the debugging information entry associated with the +argument +.Fa global , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_global_name_offsets +retrieves the name and the offsets for the debugging information +entry for argument +.Fa global . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to a section-relative +offset, relative to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to a +section-relative offset, relative to the +.Dq ".debug_info" +section, of the first debugging information entry in +the compilation unit associated with argument +.Fa global . +.Pp +Function +.Fn dwarf_globname +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa global . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Global +descriptors returned in argument +.Fa globals +by function +.Fn dwarf_get_globals +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_globals_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_globname +and +.Fn dwarf_global_name_offsets +is owned by the +.Lb libdwarf . +Portable code should use the +.Xr dwarf_dealloc 3 +function to indicate that the memory area may be freed. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va global , +.Va globals , +.Va name , +or +.Va nglobals +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_globals_dealloc 3 diff --git a/static/netbsd/man3/dwarf_get_loclist_entry.3 b/static/netbsd/man3/dwarf_get_loclist_entry.3 new file mode 100644 index 00000000..94d6737e --- /dev/null +++ b/static/netbsd/man3/dwarf_get_loclist_entry.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: dwarf_get_loclist_entry.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_loclist_entry.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd July 6, 2011 +.Dt DWARF_GET_LOCLIST_ENTRY 3 +.Os +.Sh NAME +.Nm dwarf_get_loclist_entry +.Nd retrieve DWARF location list entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_loclist_entry +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned offset" +.Fa "Dwarf_Addr *hipc" +.Fa "Dwarf_Addr *lopc" +.Fa "Dwarf_Ptr *data" +.Fa "Dwarf_Unsigned *entry_len" +.Fa "Dwarf_Unsigned *next_entry" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_loclist_entry +retrieves a location list entry from the DWARF section +.Dq ".debug_loc" . +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa offset +is an offset, relative to the +.Dq ".debug_loc" +section, to the start of the desired location list entry. +.Pp +Argument +.Fa hipc +should point to a location which will hold the offset, relative to the +base address of the location list entry, of the highest program +counter value for the entry. +.Pp +Argument +.Fa lowpc +should point to a location which will hold the offset, relative to the +base address of the location list entry, of the lowest program counter +value for the entry. +.Pp +Argument +.Fa data +should point to a location which will be set to a pointer to the location +list data. +.Pp +Argument +.Fa entry_len +should point to a location which will hold the length in bytes of the +location list data returned in argument +.Fa data . +.Pp +Argument +.Fa next_entry +should point to a location which will hold the offset of the next +location list entry. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_loclist_entry +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no location list at the specified offset +.Fa offset . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To iterate through all the location list entries in the +.Dq ".debug_loc" +section, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Unsigned off, len, next; +Dwarf_Addr hipc, lopc; +Dwarf_Ptr data; +Dwarf_Error de; +int ret; + +off = 0; +while ((ret = dwarf_get_loclist_entry(dbg, off, &hipc, &lopc, &data, + &len, &next, &de)) == DW_DLV_OK) { + /* ... use loclist entry ... */ + off = next; +} +if (ret == DW_DLV_ERROR) + warnx("dwarf_get_loclist_entry failed: %s", dwarf_errmsg(de)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_loclist_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa hipc , +.Fa lopc , +.Fa data , +.Fa entry_len +or +.Fa next_entry +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There is no location list at the specified offset +.Fa offset . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_loclist 3 , +.Xr dwarf_loclist_from_expr 3 , +.Xr dwarf_loclist_from_expr_a 3 , +.Xr dwarf_loclist_n 3 diff --git a/static/netbsd/man3/dwarf_get_macro_details.3 b/static/netbsd/man3/dwarf_get_macro_details.3 new file mode 100644 index 00000000..27825c56 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_macro_details.3 @@ -0,0 +1,198 @@ +.\" $NetBSD: dwarf_get_macro_details.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_macro_details.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd March 20, 2011 +.Dt DWARF_GET_MACRO_DETAILS 3 +.Os +.Sh NAME +.Nm dwarf_get_macro_details +.Nd retrieve macro information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_macro_details +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Unsigned max_count" +.Fa "Dwarf_Signed *entry_cnt" +.Fa "Dwarf_Macro_Details **details" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_macro_details +retrieves information about macros associated with a DWARF debug +context. +Information about macro entries are returned as an array of +descriptors of type +.Vt Dwarf_Macro_Details , +with each +.Vt Dwarf_Macro_Details +descriptor describing one macro information entry. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +Argument +.Fa offset +is an offset, relative to the +.Dq ".debug_macinfo" +section, to the start of the desired macro information. +Argument +.Fa max_count +specifies the maximum number of macro information entries +to be returned, or 0 if all entries are to be returned. +Argument +.Fa entry_cnt +should point to a location that will be set to the number +of entries actually returned. +Argument +.Fa details +should point to a location that will be set to a pointer to +an array of +.Vt Dwarf_Macro_Details +descriptors. +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +.Vt Dwarf_Macro_Details +descriptors are defined in the header file +.In libdwarf.h , +and consist of the following fields: +.Bl -tag -width ".Va dmd_fileindex" -compact +.It Va dmd_offset +The section-relative offset within the +.Dq ".debug_macinfo" +section of the macro information entry being described. +.It Va dmd_type +The type code of this macro information entry; one of the +.Dv DW_MACINFO_* +constants defined by the DWARF specification. +.It Va dmd_lineno +The line number associated with the macro information +entry, or 0 if there is no applicable line number. +.It Va dmd_fileindex +The source file index for the macro information entry. +This field is only meaningful when +.Va dmd_type +field is set to +.Dv DW_MACINFO_start_file . +.It Va dmd_macro +The contents of this field is a pointer to a NUL-terminated string +whose meaning depends on the value of the +.Va dmd_type +field: +.Bl -tag -width ".Dv DW_MACINFO_vendor_ext" -compact +.It Dv DW_MACINFO_define +The returned string contains the macro name and value. +.It Dv DW_MACINFO_undef +The string holds the macro name. +.It Dv DW_MACINFO_vendor_ext +The +.Va dmd_macro +field points to a vendor defined string. +.El +The field is +.Dv NULL +for other values of +.Va dmd_type . +.El +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Macro_Details +descriptors returned in argument +.Fa details +is owned by the +.Lb libdwarf . +The application should not attempt to directly free this pointer. +Portable code should instead use +.Fn dwarf_dealloc +with the allocation type +.Dv DW_DLA_STRING +to indicate that the memory may be freed. +.Sh RETURN VALUES +Function +.Fn dwarf_get_macro_details +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no more macro information at the specified offset +.Fa offset . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To loop through all the macro information entries associated with +a DWARF debug context: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Unsigned offset; +Dwarf_Signed cnt; +Dwarf_Macro_Details *md; +Dwarf_Error de; + +offset = 0; +while (dwarf_get_macro_details(dbg, offset, 0, + &cnt, &md, &de) == DW_DLV_OK) { + for (i = 0; i < cnt; i++) { + /* Access fields of md[i] ... */ + } + offset = md[cnt - 1].dmd_offset + 1; +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_macro_details +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa entry_cnt +or +.Fa details +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There is no more macro information at the specified offset +.Fa offset . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_find_macro_value_start 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_get_pubtypes.3 b/static/netbsd/man3/dwarf_get_pubtypes.3 new file mode 100644 index 00000000..19b4d804 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_pubtypes.3 @@ -0,0 +1,248 @@ +.\" $NetBSD: dwarf_get_pubtypes.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_pubtypes.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 4, 2011 +.Dt DWARF_GET_PUBTYPES 3 +.Os +.Sh NAME +.Nm dwarf_get_pubtypes , +.Nm dwarf_pubtype_cu_offset , +.Nm dwarf_pubtype_die_offset , +.Nm dwarf_pubtype_name_offsets , +.Nm dwarf_pubtypename +.Nd retrieve information about user-defined types +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_pubtypes +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Type **types" +.Fa "Dwarf_Signed *ntypes" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_pubtype_cu_offset +.Fa "Dwarf_Type type" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_pubtype_die_offset +.Fa "Dwarf_Type type" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_pubtype_name_offsets +.Fa "Dwarf_Type type" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_pubtypename +.Fa "Dwarf_Type type" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve information about file-scope, user-defined +types recorded in lookup tables in the +.Dq ".debug_pubtypes" +DWARF section. +Information about these types is returned using opaque descriptors +of type +.Vt Dwarf_Type . +Applications need to use the functions described below to retrieve +the name and offset information contained in these descriptors. +.Pp +Function +.Fn dwarf_get_pubtypes +retrieves descriptors for all the user-defined types associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa types +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Type +descriptors. +The argument +.Fa ntypes +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_pubtype_cu_offset +returns the offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that contains the debugging +information entry associated with the argument +.Fa type . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_pubtype_die_offset +retrieves the offset, relative to the +.Dq ".debug_info" +section, of the debugging information entry associated with the +argument +.Fa type , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_pubtype_name_offsets +retrieves the name and offsets for the debugging information entry for +argument +.Fa type . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to the +offset, relative to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to the +offset, relative to the +.Dq ".debug_info" +section, of the first debugging information entry in the compilation +unit associated with argument +.Fa type . +.Pp +Function +.Fn dwarf_pubtypename +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa type . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Type +descriptors returned in argument +.Fa types +by function +.Fn dwarf_get_pubtypes +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_types_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_pubtype_name_offsets +and +.Fn dwarf_pubtypename +is owned by the +.Lb libdwarf . +Portable code should indicate that the memory area can +be freed using the +.Xr dwarf_dealloc 3 +function. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh EXAMPLES +To retrieve the list of file scope user-defined types and print +their names, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Signed ntypes; +Dwarf_Type *types; +Dwarf_Error err; +int n, result; +char *typename; + +/* Initialize dbg etc. */; +result = dwarf_get_pubtypes(dbg, &types, &ntypes, &err); +if (result != DW_DLV_OK) /* Handle the error. */ + ; + +/* Iterate over the returned array of descriptors. */ +for (n = 0; n < ntypes; n++) { + result = dwarf_pubtypename(types[n], &typename, &err); + if (result != DW_DLV_OK) /* Handle the error. */ + ; + printf("%s\en", typename); +} + +/* Deallocate the returned array. */ +dwarf_types_dealloc(dbg, types, ntypes); +.Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va type , +.Va types , +.Va name , +or +.Va ntypes +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The DWARF debugging context referenced by argument +.Fa dbg +did not contain information about user-defined types. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_pubtypes_dealloc 3 diff --git a/static/netbsd/man3/dwarf_get_ranges.3 b/static/netbsd/man3/dwarf_get_ranges.3 new file mode 100644 index 00000000..1e180c7b --- /dev/null +++ b/static/netbsd/man3/dwarf_get_ranges.3 @@ -0,0 +1,264 @@ +.\" $NetBSD: dwarf_get_ranges.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_ranges.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_GET_RANGES 3 +.Os +.Sh NAME +.Nm dwarf_get_ranges +.Nd retrieve non-contiguous address ranges +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_ranges +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Ranges **ranges" +.Fa "Dwarf_Signed *cnt" +.Fa "Dwarf_Unsigned *byte_cnt" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_ranges_a +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Die die" +.Fa "Dwarf_Ranges **ranges" +.Fa "Dwarf_Signed *cnt" +.Fa "Dwarf_Unsigned *byte_cnt" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_ranges +retrieves information about the non-contiguous address ranges associated +with a DWARF debugging information entry. +Information about address ranges is returned as an array of +descriptors of type +.Vt Dwarf_Ranges , +with each +.Vt Dwarf_Ranges +descriptor describing one address range entry. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa offset +is an offset, relative to the +.Dq ".debug_ranges" +section, to the start of the desired list of address ranges. +The offset of an address ranges list is indicated by the +.Dv DW_AT_ranges +attribute of a debugging information entry. +.Pp +Argument +.Fa die +(function +.Fn dwarf_get_ranges_a +only) is ignored in this implementation; see the section +.Sx "Compatibility Notes" +below. +.Pp +Argument +.Fa ranges +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Ranges +descriptors. +.Pp +Argument +.Fa cnt +should point to a location that will be set to the number of entries +returned. +If argument +.Fa byte_cnt +is not +.Dv NULL , +it will be set to the number of bytes occupied by the +returned entries in the +.Dq ".debug_ranges" +section. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +.Vt Dwarf_Ranges +descriptors are defined in the header file +.In libdwarf.h , +and consists of the following fields: +.Bl -tag -width ".Va dwr_addr1" +.It Va dwr_addr1 +The first address offset, whose meaning depends on the type of the +entry. +.It Va dwr_addr2 +The second address offset, whose meaning depends on the type of the +entry. +.It Va dwr_type +The type of this address range entry: +.Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact +.It Dv DW_RANGES_ENTRY +A range list entry. +For this type of entry, the fields +.Va dwr_addr1 +and +.Va dwr_addr2 +hold the beginning and ending offsets of the address range, respectively. +.It Dv DW_RANGES_ADDRESS_SELECTION +A base address selection entry. +For this type of entry, the field +.Va dwr_addr1 +is the value of the largest representable address offset, and +.Va dwr_addr2 +is a base address for the beginning and ending address offsets of +subsequent address range entries in the list. +.It Dv DW_RANGES_END +An end of list mark. +Both +.Va dwr_addr1 +and +.Va dwr_addr2 +are set to 0. +.El +.El +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Ranges +descriptors returned in argument +.Fa ranges +is owned by the +.Lb libdwarf . +The application should not attempt to directly free this pointer. +Portable code should instead use +.Fn dwarf_ranges_dealloc +to indicate that the memory may be freed. +.Sh RETURN VALUES +These functions +return +.Dv DW_DLV_OK +when they succeed. +They return +.Dv DW_DLV_NO_ENTRY +if there is no address range list at the specified offset +.Fa offset . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh EXAMPLES +To retrieve the address range list associated with a debugging +information entry, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Die die; +Dwarf_Error de; +Dwarf_Addr base; +Dwarf_Attribute *attr_list; +Dwarf_Ranges *ranges; +Dwarf_Signed cnt; +Dwarf_Unsigned off, attr_count, bytecnt; +int i, j; + +if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) != + DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_attrlist failed: %s", + dwarf_errmsg(de)); + +for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { + if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) { + warnx("dwarf_whatattr failed: %s", + dwarf_errmsg(de)); + continue; + } + if (attr != DW_AT_ranges) + continue; + if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) { + warnx("dwarf_formudata failed: %s", + dwarf_errmsg(de)); + continue; + } + if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt, + &bytecnt, &de) != DW_DLV_OK) + continue; + for (j = 0; j < cnt; j++) { + if (ranges[j].dwr_type == DW_RANGES_END) + break; + else if (ranges[j].dwr_type == + DW_RANGES_ADDRESS_SELECTION) + base = ranges[j].dwr_addr2; + else { + /* + * DW_RANGES_ENTRY entry. + * .. Use dwr_addr1 and dwr_addr2 .. + */ + } + } +} +.Ed +.Sh COMPATIBILITY +Function +.Fn dwarf_get_ranges_a +is identical to +.Fn dwarf_get_ranges , +except that it requires one additional argument +.Fa die +denoting the debugging information entry associated with +the address range list. +In this implementation of the +.Lb libdwarf , +the argument +.Fa die +is ignored, and function +.Fn dwarf_get_ranges_a +is only provided for compatibility with other implementations of the +DWARF(3) API. +.Sh ERRORS +These function can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa ranges +or +.Fa cnt +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There is no address range list at the specified offset +.Fa offset . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_ranges_dealloc 3 diff --git a/static/netbsd/man3/dwarf_get_relocation_info.3 b/static/netbsd/man3/dwarf_get_relocation_info.3 new file mode 100644 index 00000000..5ef8145b --- /dev/null +++ b/static/netbsd/man3/dwarf_get_relocation_info.3 @@ -0,0 +1,232 @@ +.\" $NetBSD: dwarf_get_relocation_info.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_relocation_info.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 3, 2011 +.Dt DWARF_GET_RELOCATION_INFO 3 +.Os +.Sh NAME +.Nm dwarf_get_relocation_info +.Nd retrieve generated relocation arrays +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_relocation_info +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Signed *elf_section_index" +.Fa "Dwarf_Signed *elf_section_link" +.Fa "Dwarf_Unsigned *reloc_entry_count" +.Fa "Dwarf_Relocation_Data *reloc_buf" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +The function +.Fn dwarf_get_relocation_info +is used to retrieve the relocation arrays generated by a prior call to +.Xr dwarf_transform_to_disk_form 3 . +.Pp +Each call to this function retrieves the next available relocation +array. +Application code should call this function repeatly to retrieve all +the relocation arrays. +The total number of generated relocation arrays retrievable +by this function may be obtained by calling function +.Xr dwarf_get_relocation_info_count 3 . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 in sequence. +or +.Xr dwarf_producer_init_b 3 . +The +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag should have been set on the DWARF producer instance. +.Pp +Argument +.Fa elf_section_index +should point to a location which will be set to the ELF section index +of the relocation section to which the retrieved relocation array +belongs. +.Pp +Argument +.Fa elf_section_link +should point to a location which will be set to the section index of +the ELF section to which the retrieved relocation array applies. +.Pp +Argument +.Fa reloc_entry_count +should point to a location which will be set to the total number of +relocation entries contained in the relocation array. +.Pp +Argument +.Fa reloc_buf +should point to a location which will be set to a pointer to the +retrieved array of relocation entries. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +The retrieved relocation entries are described using structure +.Vt Dwarf_Relocation_Data_s , +defined in the header file +.In libdwarf.h : +.Bd -literal -offset indent +typedef struct Dwarf_Relocation_Data_s { + unsigned char drd_type; + unsigned char drd_length; + Dwarf_Unsigned drd_offset; + Dwarf_Unsigned drd_symbol_index; +} *Dwarf_Relocation_Data; +.Ed +.Pp +Struct +.Vt Dwarf_Relocation_Data_s +consists of following fields: +.Bl -tag -width ".Va drd_symbol_index" -compact -offset indent +.It Va drd_type +The type code of the relocation entry. +The +.Vt Dwarf_Rel_Type +enumeration defined in the header file +.In libdwarf.h +specifies legal values for this field. +.It Va drd_length +The size in bytes of the field to be relocated. +.It Va drd_offset +The section-relative offset of the field to be relocated. +.It Va drd_symbol_index +The symbol index associated with the relocation entry. +.El +.Ss Memory Management +The memory area used for the relocation arrays is managed by the +.Lb libdwarf . +The function +.Fn dwarf_producer_finish +may be used to release it, along with other resources associated +with the producer instance. +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_relocation_info +returns +.Dv DW_DLV_OK . +It returns +.Dv DW_DLV_NO_ENTRY +if there were no more relocation arrays to retrieve, or if the flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was not set on the producer instance. +In case of an error, function +.Fn dwarf_get_relocation_info +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To generate relocation entries and retrieve them, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Relocation_Data buf; +Dwarf_Signed count, index, link; +Dwarf_Unsigned reloc_cnt, entry_cnt; +Dwarf_Error de; +int version, i, j; + +/* + * Assume that dbg refers to a DWARF producer instance created + * created with DW_DLC_SYMBOLIC_RELOCATIONS flag set and that + * application code has added DWARF debugging information + * to the producer instance. + */ +if ((count = dwarf_transform_to_disk_form(dbg, &de)) == + DW_DLV_NOCOUNT) { + warnx("dwarf_transform_to_disk_form failed: %s", + dwarf_errmsg(-1)); + return; +} + +/* ... process generated section byte streams ... */ +if (dwarf_get_relocation_info_count(dbg, &reloc_cnt, &version, &de) != + DW_DLV_OK) { + warnx("dwarf_get_relocation_info_count failed: %s", + dwarf_errmsg(-1)); + return; +} + +for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) { + if (dwarf_get_relocation_info(dbg, &index, &link, &entry_cnt, + &buf, &de) != DW_DLV_OK) { + warnx("dwarf_get_relocation_info failed: %s", + dwarf_errmsg(-1)); + continue; + } + for (j = 0; (Dwarf_Unsigned) j < entry_cnt; j++) { + /* ...use each reloc data in buf[j]... */ + } +} + +dwarf_producer_finish(dbg, &de); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_relocation_info +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa elf_section_index , +.Fa elf_section_link , +.Fa reloc_entry_count +or +.Fa reloc_buf +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There were no more ELF relocation arrays to retrieve. +.It Bq Er DW_DLE_NO_ENTRY +The flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was not set on the producer instance. +.It Bq Er DW_DLE_NO_ENTRY +Function +.Xr dwarf_transform_to_disk_form 3 +was not called prior to calling function +.Fn dwarf_get_relocation_info . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_relocation_info_count 3 , +.Xr dwarf_producer_finish 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_reset_section_bytes 3 , +.Xr dwarf_transform_to_disk_form 3 diff --git a/static/netbsd/man3/dwarf_get_relocation_info_count.3 b/static/netbsd/man3/dwarf_get_relocation_info_count.3 new file mode 100644 index 00000000..39f38705 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_relocation_info_count.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: dwarf_get_relocation_info_count.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_relocation_info_count.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 3, 2011 +.Dt DWARF_GET_RELOCATION_INFO_COUNT 3 +.Os +.Sh NAME +.Nm dwarf_get_relocation_info_count +.Nd return the number of relocation arrays +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_relocation_info_count +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned *reloc_cnt" +.Fa "int *drd_buffer_version" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_relocation_info_count +retrieves the total number of relocation arrays generated by a prior +call to +.Xr dwarf_transform_to_disk_form 3 . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +The +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag should have been set on the producer instance. +.Pp +Argument +.Fa reloc_cnt +should point to a location which will be set to the total number of +relocation arrays generated. +.Pp +Argument +.Fa drd_buffer_version +should point to a location which will be set to the version number +of the relocation structures returned (see the symbol +.Dv DWARF_DRD_BUFFER_VERSION , +defined in the header file +.In libdwarf.h ) . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_relocation_info_count +returns +.Dv DW_DLV_OK . +It returns +.Dv DW_DLV_NO_ENTRY +if the +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag is not set on the producer instance. +In case of an error, function +.Fn dwarf_get_relocation_info_count +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_get_relocation_info_count +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa reloc_cnt +or +.Fa drd_buffer_version +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +flag was not set. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_relocation_info 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_transform_to_disk_form 3 diff --git a/static/netbsd/man3/dwarf_get_section_bytes.3 b/static/netbsd/man3/dwarf_get_section_bytes.3 new file mode 100644 index 00000000..2e506621 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_section_bytes.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: dwarf_get_section_bytes.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_section_bytes.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd August 26, 2011 +.Dt DWARF_GET_SECTION_BYTES 3 +.Os +.Sh NAME +.Nm dwarf_get_section_bytes +.Nd retrieve ELF section byte streams +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Ptr +.Fo dwarf_get_section_bytes +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Signed dwarf_section" +.Fa "Dwarf_Signed *elf_section_index" +.Fa "Dwarf_Unsigned *length" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_section_bytes +returns the ELF section byte streams generated by a prior call +to function +.Xr dwarf_transform_to_disk_form 3 . +.Pp +Each call to function +.Fn dwarf_get_section_bytes +will return the byte stream for one ELF section. +The first call to this function will always return the first ELF +section, and the subsequent calls will return the rest of sections +in the order when they were generated, until the last one. +The total number of sections generated is returned by the function +.Xr dwarf_transform_to_disk_form 3 . +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using the +functions +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa dwarf_section +is currently ignored. +.Pp +Argument +.Fa elf_section_index +should point to a location which will be set to the section index value +of the returned ELF section. +.Pp +Argument +.Fa length +should point to a location which will hold the length in bytes of the +returned ELF section. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory areas used for the returned ELF section byte streams should +be freed using the function +.Fn dwarf_producer_finish . +.Sh RETURN VALUES +On success, function +.Fn dwarf_get_section_bytes +returns a pointer to a ELF section byte stream. +In case of an error, function +.Fn dwarf_get_section_bytes +will return +.Dv NULL +and set the argument +.Fa err . +.Sh EXAMPLES +To generate and retrieve ELF section byte streams, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Signed count, i, sec_index; +Dwarf_Unsigned len; +Dwarf_Ptr bytes; +Dwarf_Error de; + +/* ... Assume that `dbg' refers to a DWARF producer instance, + * and that application code has added DWARF debugging + * information to the producer instance. ... + */ +if ((count = dwarf_transform_to_disk_form(dbg, &de)) == + DW_DLV_NOCOUNT) { + warnx("dwarf_transform_to_disk_form failed: %s", + dwarf_errmsg(-1)); + return; +} + +/* Retrieve section data. */ +for (i = 0; i < count; i++) { + bytes = dwarf_get_section_bytes(dbg, i, &sec_index, &len, + &de); + if (bytes == NULL) { + warnx("dwarf_get_section_bytes failed: %s", + dwarf_errmsg(-1)); + continue; + } + /* ... use the returned byte stream ... */ +} + +/* Release resources. */ +dwarf_producer_finish(dbg, &de); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_section_bytes +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa elf_section_index , +or +.Fa length +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +There were no more ELF sections to retrieve, or the function was +called before a call to +.Xr dwarf_transform_to_disk_form 3 . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_producer_finish 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_reset_section_bytes 3 , +.Xr dwarf_transform_to_disk_form 3 diff --git a/static/netbsd/man3/dwarf_get_section_max_offsets.3 b/static/netbsd/man3/dwarf_get_section_max_offsets.3 new file mode 100644 index 00000000..dbb0ce47 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_section_max_offsets.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: dwarf_get_section_max_offsets.3,v 1.5 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_section_max_offsets.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd December 21, 2014 +.Dt DWARF_GET_SECTION_MAX_OFFSETS 3 +.Os +.Sh NAME +.Nm dwarf_get_section_max_offsets , +.Nm dwarf_get_section_max_offsets_b +.Nd return the size of DWARF sections +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_section_max_offsets +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned *debug_info" +.Fa "Dwarf_Unsigned *debug_abbrev" +.Fa "Dwarf_Unsigned *debug_line" +.Fa "Dwarf_Unsigned *debug_loc" +.Fa "Dwarf_Unsigned *debug_aranges" +.Fa "Dwarf_Unsigned *debug_macinfo" +.Fa "Dwarf_Unsigned *debug_pubnames" +.Fa "Dwarf_Unsigned *debug_str" +.Fa "Dwarf_Unsigned *debug_frame" +.Fa "Dwarf_Unsigned *debug_ranges" +.Fa "Dwarf_Unsigned *debug_pubtypes" +.Fc +.Ft int +.Fo dwarf_get_section_max_offsets_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned *debug_info" +.Fa "Dwarf_Unsigned *debug_abbrev" +.Fa "Dwarf_Unsigned *debug_line" +.Fa "Dwarf_Unsigned *debug_loc" +.Fa "Dwarf_Unsigned *debug_aranges" +.Fa "Dwarf_Unsigned *debug_macinfo" +.Fa "Dwarf_Unsigned *debug_pubnames" +.Fa "Dwarf_Unsigned *debug_str" +.Fa "Dwarf_Unsigned *debug_frame" +.Fa "Dwarf_Unsigned *debug_ranges" +.Fa "Dwarf_Unsigned *debug_pubtypes" +.Fa "Dwarf_Unsigned *debug_types" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_section_max_offsets_b +retrieves the sizes of the DWARF sections in a DWARF debug context. +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +The function stores the size of each DWARF section to the location +pointed to by the argument corresponding to the section name. +If a DWARF section does not exist, the location pointed to by the +argument corresponding to that section will be set to zero. +.Pp +A value of +.Dv NULL +may be used for any of the arguments +.Fa debug_info , +.Fa debug_abbrev , +.Fa debug_line , +.Fa debug_loc , +.Fa debug_aranges , +.Fa debug_macinfo , +.Fa debug_pubnames , +.Fa debug_str , +.Fa debug_frame , +.Fa debug_ranges , +.Fa debug_pubtypes +and +.Fa debug_types +if the caller is not interested in the respective section size. +.Pp +Function +.Fn dwarf_get_section_max_offsets +is identical to function +.Fn dwarf_get_section_max_offsets_b +except that it does not provide argument +.Fa debug_types , +and thus cannot return the size of the +.Dq \&.debug_types +section. +.Sh RETURN VALUES +On success, these functions return +.Dv DW_DLV_OK . +If argument +.Fa dbg +is +.Dv NULL , +they return +.Dv DW_DLV_ERROR . +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_get_str.3 b/static/netbsd/man3/dwarf_get_str.3 new file mode 100644 index 00000000..d5cc1e95 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_str.3 @@ -0,0 +1,153 @@ +.\" $NetBSD: dwarf_get_str.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_str.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 3, 2011 +.Dt DWARF_GET_STR 3 +.Os +.Sh NAME +.Nm dwarf_get_str +.Nd retrieve a string from the DWARF string section +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_str +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "char **string" +.Fa "Dwarf_Signed *len" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_str +retrieves a NUL-terminated string from the DWARF string section +.Dq ".debug_str" . +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa offset +should be an offset, relative to the +.Dq ".debug_str" +section, specifying the start of the desired string. +.Pp +Argument +.Fa string +should point to a location which will hold a returned +pointer to a NUL-terminated string. +.Pp +Argument +.Fa len +should point to a location which will hold the length +of the returned string. +The returned length does not include the space needed for +the NUL-terminator. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +Function +.Fn dwarf_get_str +returns +.Dv DW_DLV_OK +when it succeeds. +It returns +.Dv DW_DLV_NO_ENTRY +if there is no +.Dq ".debug_str" +section associated with the specified debugging context, +or if the provided offset +.Fa offset +is at the very end of +.Dq ".debug_str" +section. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To retrieve all the strings in the DWARF string section, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Off offset; +Dwarf_Signed len; +Dwarf_Error de; +char *str; +int ret + +offset = 0; +while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) == + DW_DLV_OK) { + /* .. Use the retrieved string. .. */ + offset += len + 1; /* Account for the terminating NUL. */ +} + +if (ret == DW_DLV_ERROR) + warnx("dwarf_get_str: %s", dwarf_errmsg(de)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_get_str +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa dbg , +.Fa string +or +.Fa len +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa offset +was out of range. +.It Bq Er DW_DLE_NO_ENTRY +The debugging context +.Fa dbg +did not contain a +.Dq ".debug_str" +string section. +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa offset +was at the very end of the +.Dq ".debug_str" +section. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_get_types.3 b/static/netbsd/man3/dwarf_get_types.3 new file mode 100644 index 00000000..8424db0c --- /dev/null +++ b/static/netbsd/man3/dwarf_get_types.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: dwarf_get_types.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_types.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 10, 2011 +.Dt DWARF_GET_TYPES 3 +.Os +.Sh NAME +.Nm dwarf_get_types , +.Nm dwarf_type_cu_offset , +.Nm dwarf_type_die_offset , +.Nm dwarf_type_name_offsets , +.Nm dwarf_typename +.Nd retrieve information about user-defined types +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_types +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Type **types" +.Fa "Dwarf_Signed *ntypes" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_type_cu_offset +.Fa "Dwarf_Type type" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_type_die_offset +.Fa "Dwarf_Type type" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_type_name_offsets +.Fa "Dwarf_Type type" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_typename +.Fa "Dwarf_Type type" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These APIs retrieve information about user-defined types from the +SGI-specific +.Dq ".debug_typenames" +section. +.Pp +Standards-conformant applications should use the functions +.Xr dwarf_get_pubtypes 3 , +.Xr dwarf_pubtype_cu_offset 3 , +.Xr dwarf_pubtype_die_offset 3 , +.Xr dwarf_pubtype_name_offsets 3 +and +.Xr dwarf_pubtypename 3 , +which operate on the equivalent +.Dq ".debug_pubtypes" +section defined by the DWARF3 standard. +.Pp +Information about user-defined types is returned using opaque descriptors +of type +.Vt Dwarf_Type . +Applications need to use the functions described below to retrieve +the name and offset information contained in these descriptors. +.Pp +Function +.Fn dwarf_get_types +retrieves descriptors for all user-defined types associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa types +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Type +descriptors. +The argument +.Fa ntypes +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_type_cu_offset +returns the offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that contains the debugging +information entry associated with the argument +.Fa type . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_type_die_offset +retrieves the offset, relative to the +.Dq ".debug_info" +section, of the debugging information entry associated with the +argument +.Fa type , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_type_name_offsets +retrieves the name and offsets for the debugging information +entry for argument +.Fa type . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to the offset, relative +to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to a offset, relative to +the +.Dq ".debug_info" +section, of the first debugging information entry in the compilation +unit associated with argument +.Fa type . +.Pp +Function +.Fn dwarf_typename +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa type . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Type +descriptors returned in argument +.Fa types +by function +.Fn dwarf_get_types +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_types_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_type_name_offsets +and +.Fn dwarf_typename +is owned by the +.Lb libdwarf . +Portable code should indicate that the memory area can +be freed using the +.Xr dwarf_dealloc 3 +function. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va type , +.Va types , +.Va name , +or +.Va ntypes +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The DWARF debugging context referenced by argument +.Fa dbg +did not contain information about user-defined types. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_get_pubtypes 3 , +.Xr dwarf_pubtype_cu_offset 3 , +.Xr dwarf_pubtype_die_offset 3 , +.Xr dwarf_pubtype_name_offsets 3 , +.Xr dwarf_pubtypename 3 , +.Xr dwarf_types_dealloc 3 diff --git a/static/netbsd/man3/dwarf_get_vars.3 b/static/netbsd/man3/dwarf_get_vars.3 new file mode 100644 index 00000000..b69d45e7 --- /dev/null +++ b/static/netbsd/man3/dwarf_get_vars.3 @@ -0,0 +1,215 @@ +.\" $NetBSD: dwarf_get_vars.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_vars.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 2, 2011 +.Dt DWARF_GET_VARS 3 +.Os +.Sh NAME +.Nm dwarf_get_vars , +.Nm dwarf_var_cu_offset , +.Nm dwarf_var_die_offset , +.Nm dwarf_var_name_offsets , +.Nm dwarf_varname +.Nd retrieve information about static variables +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_vars +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Var **vars" +.Fa "Dwarf_Signed *nvars" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_var_cu_offset +.Fa "Dwarf_Var var" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_var_die_offset +.Fa "Dwarf_Var var" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_var_name_offsets +.Fa "Dwarf_Var var" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_varname +.Fa "Dwarf_Var var" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve information about the file scope static +variables associated with a DWARF debug context. +Information about these static variables is returned using opaque +descriptors of type +.Vt Dwarf_Var . +Applications need to use the functions described below to retrieve +the name and offset information contained in these descriptors. +.Pp +Function +.Fn dwarf_get_vars +retrieves descriptors for all the static variables associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa vars +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Var +descriptors. +The argument +.Fa nvars +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_var_cu_offset +returns the section-relative offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that +contains the debugging information entry associated with the argument +.Fa var . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_var_die_offset +retrieves the section-relative offset, relative to the +.Dq ".debug_info" +section, of the debugging information +entry associated with the argument +.Fa var , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_var_name_offsets +retrieves both the name and the associated offsets for the debugging +information entry for argument +.Fa var . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to a section-relative +offset, relative to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to a +section-relative offset, relative to the +.Dq ".debug_info" +section, of the first debugging information entry in +the compilation unit associated with argument +.Fa var . +.Pp +Function +.Fn dwarf_varname +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa var . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Var +descriptors returned in argument +.Fa vars +by function +.Fn dwarf_get_vars +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_vars_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_var_name_offsets +and +.Fn dwarf_varname +is owned by the +.Lb libdwarf . +Portable code should indicate that the memory area can +be freed using the +.Xr dwarf_dealloc 3 +function. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va var , +.Va vars , +.Va name , +or +.Va nvars +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_vars_dealloc 3 diff --git a/static/netbsd/man3/dwarf_get_weaks.3 b/static/netbsd/man3/dwarf_get_weaks.3 new file mode 100644 index 00000000..fe5dbb7a --- /dev/null +++ b/static/netbsd/man3/dwarf_get_weaks.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: dwarf_get_weaks.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_get_weaks.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 10, 2011 +.Dt DWARF_GET_WEAKS 3 +.Os +.Sh NAME +.Nm dwarf_get_weaks , +.Nm dwarf_weak_cu_offset , +.Nm dwarf_weak_die_offset , +.Nm dwarf_weak_name_offsets , +.Nm dwarf_weakname +.Nd retrieve information about weak symbols +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_weaks +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Weak **weaks" +.Fa "Dwarf_Signed *nweaks" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_weak_cu_offset +.Fa "Dwarf_Weak weak" +.Fa "Dwarf_Off *cu_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_weak_die_offset +.Fa "Dwarf_Weak weak" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_weak_name_offsets +.Fa "Dwarf_Weak weak" +.Fa "char **name" +.Fa "Dwarf_Off *die_offset" +.Fa "Dwarf_Off *cu_die_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_weakname +.Fa "Dwarf_Weak weak" +.Fa "char **name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve information about weak symbols from the +lookup tables in the (SGI-specific) +.Dq ".debug_weaknames" +section. +Information about weak symbols is returned using opaque descriptors +of type +.Vt Dwarf_Weak . +Applications need to use the functions described below to retrieve +the name and offset information contained in these descriptors. +.Pp +Function +.Fn dwarf_get_weaks +retrieves descriptors for all the weak symbols associated with the +DWARF debug context specified by argument +.Fa dbg . +The argument +.Fa weaks +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Weak +descriptors. +The argument +.Fa nweaks +should point to a location that will be set to the number of +descriptors returned. +.Pp +Function +.Fn dwarf_weak_cu_offset +returns the offset, relative to the +.Dq ".debug_info" +section, of the compilation unit that contains the debugging +information entry associated with the argument +.Fa weak . +Argument +.Fa cu_offset +should point to a location that will hold the returned offset. +.Pp +Function +.Fn dwarf_weak_die_offset +retrieves the offset, relative to the +.Dq ".debug_info" +section, of the debugging information entry associated with the +argument +.Fa weak , +and stores it into the location pointed to by the argument +.Fa die_offset . +.Pp +Function +.Fn dwarf_weak_name_offsets +retrieves the name and offsets for the debugging information +entry for argument +.Fa weak . +Argument +.Fa name +should point to a location which will be set to a pointer to a +NUL-terminated string containing the name of the associated debugging +information entry. +Argument +.Fa die_offset +should point to a location which will be set to the offset, relative +to the +.Dq ".debug_info" +section, of the associated debugging information entry. +Argument +.Fa cu_die_offset +should point to a location which will be set to the +offset, relative to the +.Dq ".debug_info" +section, of the first debugging information entry in the compilation +unit associated with argument +.Fa weak . +.Pp +Function +.Fn dwarf_weakname +sets the location pointed to by argument +.Fa name +to a pointer to a NUL-terminated string holding the name of the +debugging information entry associated with the argument +.Fa weak . +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Weak +descriptors returned in argument +.Fa weaks +by function +.Fn dwarf_get_weaks +is owned by the +.Lb libdwarf . +Application code should not attempt to directly free this pointer. +Portable code should instead use the function +.Xr dwarf_weaks_dealloc 3 +to indicate that the memory area may be freed. +.Pp +The memory area used for the string returned in the +.Fa name +argument to functions +.Fn dwarf_weak_name_offsets +and +.Fn dwarf_weakname +is owned by the +.Lb libdwarf . +Portable code should indicate that the memory area can +be freed using the +.Xr dwarf_dealloc 3 +function. +.Ss Error Returns +If argument +.Fa err +is not +.Dv NULL , +these functions will use it to store error information, +in case of an error. +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va cu_die_offset , +.Va cu_offset , +.Va dbg , +.Va die_offset , +.Va weak , +.Va weaks , +.Va name , +or +.Va nweaks +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The DWARF debugging context referenced by argument +.Fa dbg +did not contain information about weak symbols. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_weaks_dealloc 3 diff --git a/static/netbsd/man3/dwarf_hasattr.3 b/static/netbsd/man3/dwarf_hasattr.3 new file mode 100644 index 00000000..58faca4e --- /dev/null +++ b/static/netbsd/man3/dwarf_hasattr.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: dwarf_hasattr.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_hasattr.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 17, 2010 +.Dt DWARF_HASATTR 3 +.Os +.Sh NAME +.Nm dwarf_hasattr +.Nd check for the presence of an attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_hasattr +.Fa "Dwarf_Die die" +.Fa "Dwarf_Half attr" +.Fa "Dwarf_Bool *ret_bool" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_hasattr +tests whether the debugging information entry referenced in argument +.Fa die +contains the attribute named by argument +.Fa attr . +Legal values for argument +.Fa attr +are those denoted by the +.Dv DW_AT_* +constants in the DWARF specification. +.Pp +If the named attribute is present in the debugging information entry, +function +.Fn dwarf_hasattr +returns a non-zero value in the location pointed to by argument +.Fa ret_bool . +If the named attribute is not present, a zero is written instead. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_hasattr +returns +.Dv DW_DLV_OK . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_hasattr +can fail with the following error: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of argument +.Va die +or +.Va ret_bool +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_whatattr 3 diff --git a/static/netbsd/man3/dwarf_hasform.3 b/static/netbsd/man3/dwarf_hasform.3 new file mode 100644 index 00000000..292c6b6b --- /dev/null +++ b/static/netbsd/man3/dwarf_hasform.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: dwarf_hasform.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_hasform.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd May 22, 2010 +.Dt DWARF_HASFORM 3 +.Os +.Sh NAME +.Nm dwarf_hasform , +.Nm dwarf_whatform , +.Nm dwarf_whatform_direct +.Nd query attribute forms +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_hasform +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Half form" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_whatform +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Half *retform" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_whatform_direct +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Half *retform" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_hasform +indicates whether the DWARF attribute denoted by argument +.Fa attr +has the attribute form specified by argument +.Fa form . +If the attribute has the specified form, then +argument +.Fa ret +is set to a non-zero value, otherwise it is set to zero. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_whatform +sets the location specified by argument +.Fa retform +to the attribute form code for the DWARF attribute referenced +by argument +.Fa attr . +If the attribute referenced by argument +.Fa attr +has an indirect form attribute, this function will return the final +form for the attribute. +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Pp +Function +.Fn dwarf_whatform_direct +sets the location specified by argument +.Fa retform +to the attribute form code for the DWARF attribute referenced +by argument +.Fa attr . +If the form is an indirect form, the function sets the location +specified by argument +.Fa retform +to +.Dv DW_FORM_indirect . +If argument +.Fa err +is +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +on success. +In case of an error, these functions return +.Dv DW_DLV_ERR +and set argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Any of the arguments +.Fa attr , +.Fa ret , +or +.Fa retform +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_highpc.3 b/static/netbsd/man3/dwarf_highpc.3 new file mode 100644 index 00000000..35c96f20 --- /dev/null +++ b/static/netbsd/man3/dwarf_highpc.3 @@ -0,0 +1,199 @@ +.\" $NetBSD: dwarf_highpc.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010,2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_highpc.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd July 22, 2014 +.Dt DWARF_HIGHPC 3 +.Os +.Sh NAME +.Nm dwarf_arrayorder , +.Nm dwarf_bitoffset , +.Nm dwarf_bitsize , +.Nm dwarf_bytesize , +.Nm dwarf_highpc , +.Nm dwarf_highpc_b , +.Nm dwarf_lowpc , +.Nm dwarf_srclang +.Nd retrieve the value of a DWARF attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_arrayorder +.Fa "Dwarf_Die die" +.Fa "Dwarf_Unsigned *ret_order" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_bitoffset +.Fa "Dwarf_Die die" +.Fa "Dwarf_Unsigned *ret_size" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_bitsize +.Fa "Dwarf_Die die" +.Fa "Dwarf_Unsigned *ret_size" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_bytesize +.Fa "Dwarf_Die die" +.Fa "Dwarf_Unsigned *ret_size" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_highpc +.Fa "Dwarf_Die die" +.Fa "Dwarf_Addr *ret_highpc" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_highpc_b +.Fa "Dwarf_Die die" +.Fa "Dwarf_Addr *ret_highpc" +.Fa "Dwarf_Half *ret_form" +.Fa "enum Dwarf_Form_Class *ret_class" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_lowpc +.Fa "Dwarf_Die die" +.Fa "Dwarf_Addr *ret_lowpc" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_srclang +.Fa "Dwarf_Die die" +.Fa "Dwarf_Unsigned *ret_lang" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These convenience functions are used to retrieve DWARF attribute +values associated with a Debugging Information Entry (DIE) descriptor +denoted by argument +.Fa die . +These functions store the value of the requested attribute into the +location pointed to by their second argument, provided that the requested +attribute exists in the debugging information entry. +.Pp +The list of functions and the DWARF attribute that they retrieve are: +.Pp +.Bl -tag -width ".Fn dwarf_arrayorder" -compact +.It Fn dwarf_arrayorder +Retrieve the +.Dv DW_AT_ordering +attribute value. +.It Fn dwarf_bitoffset +Retrieve the +.Dv DW_AT_bit_offset +attribute value. +.It Fn dwarf_bitsize +Retrieve the +.Dv DW_AT_bit_size +attribute value. +.It Fn dwarf_bytesize +Retrieve the +.Dv DW_AT_byte_size +attribute value. +.It Fn dwarf_highpc +Retrieve the +.Dv DW_AT_high_pc +attribute value. +.It Fn dwarf_highpc_b +Retrieve the +.Dv DW_AT_high_pc +attribute value. +.It Fn dwarf_lowpc +Retrieve the +.Dv DW_AT_low_pc +attribute value. +.It Fn dwarf_srclang +Retrieve the +.Dv DW_AT_language +attribute value. +.El +.Pp +Function +.Fn dwarf_highpc_b +is an enhanced version of function +.Fn dwarf_highpc . +It sets the location specified by argument +.Fa ret_form +to the form code of the attribute +.Dv DW_AT_high_pc , +and sets the location specified by argument +.Fa ret_class +to the class of that form. +A value of +.Dv NULL +may be used for either of the arguments +.Fa ret_form +or +.Fa ret_class +if the caller is not interested in the respective value. +.Sh RETURN VALUES +These functions return +.Dv DW_DLV_OK +on success. +.Pp +If the debugging information entry descriptor denoted by argument +.Fa die +does not contain the requested attribute, these functions return +.Dv DW_DLV_NO_ENTRY +and set argument +.Fa err . +For other errors, they return +.Dv DW_DLV_ERROR +and set argument +.Fa err . +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Arguments +.Fa die , +.Fa ret_highpc , +.Fa ret_lowpc , +.Fa ret_size , +.Fa ret_lang +or +.Fa ret_order +were +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +Argument +.Fa die +had no requested attribute. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_attrlist 3 , +.Xr dwarf_get_form_class 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/dwarf_init.3 b/static/netbsd/man3/dwarf_init.3 new file mode 100644 index 00000000..04b39595 --- /dev/null +++ b/static/netbsd/man3/dwarf_init.3 @@ -0,0 +1,180 @@ +.\" $NetBSD: dwarf_init.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2009 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_init.3 3964 2022-03-13 21:41:26Z jkoshy +.\" +.Dd March 13, 2022 +.Dt DWARF_INIT 3 +.Os +.Sh NAME +.Nm dwarf_init , +.Nm dwarf_elf_init +.Nd allocate a DWARF debug descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_init +.Fa "int fd" +.Fa "int mode" +.Fa "Dwarf_Handler errhand" +.Fa "Dwarf_Ptr errarg" +.Fa "Dwarf_Debug *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_elf_init +.Fa "Elf *elf" +.Fa "int mode" +.Fa "Dwarf_Handler errhand" +.Fa "Dwarf_Ptr errarg" +.Fa "Dwarf_Debug *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions allocate and return a +.Vt Dwarf_Debug +instance for the object denoted by argument +.Fa fd +or +.Fa elf . +This instance would be used for subsequent access to debugging information in the object by other functions in the DWARF(3) library. +.Pp +For function +.Fn dwarf_init , +argument +.Fa fd +denotes an open file descriptor referencing a compilation object. +Function +.Fn dwarf_init +implicitly allocates an +.Vt Elf +descriptor for argument +.Fa fd . +.Pp +For function +.Fn dwarf_elf_init , +argument +.Fa elf +denotes a descriptor returned by +.Xr elf_begin 3 +or +.Xr elf_memory 3 . +.Pp +Argument +.Fa mode +specifies the access mode desired. +It should be at least as permissive as the mode with which +the file descriptor +.Fa fd +or the ELF descriptor +.Fa elf +was created with. +Legal values for argument +.Fa mode +are: +.Pp +.Bl -tag -width "DW_DLC_WRITE" -compact +.It DW_DLC_RDWR +Permit reading and writing of DWARF information. +.It DW_DLC_READ +Operate in read-only mode. +.It DW_DLC_WRITE +Permit writing of DWARF information. +.El +.Pp +Argument +.Fa errhand +denotes a function to be called in case of an error. +If this argument is +.Dv NULL +then a default error handling scheme is used. +See +.Xr dwarf 3 +for a description of the error handling scheme used by the +DWARF(3) library. +.Pp +Argument +.Fa errarg +is passed to the error handler function denoted by argument +.Fa errhand +when it is invoked. +.Pp +Argument +.Fa ret +points to the memory location that will hold a +.Vt Dwarf_Debug +reference on a successful call these functions. +.Pp +Argument +.Fa err +references a memory location that would hold a +.Vt Dwarf_Error +descriptor in case of an error. +.Ss Memory Management +The +.Vt Dwarf_Debug +instance returned by these functions should be freed using +.Fn dwarf_finish . +.Sh IMPLEMENTATION NOTES +The current implementation does not support access modes +.Dv DW_DLC_RDWR +and +.Dv DW_DLC_WRITE . +.Sh RETURN VALUES +These functions return the following values: +.Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY" +.It Bq Er DW_DLV_OK +This return value indicates a successful return. +.It Bq Er DW_DLV_ERROR +The operation failed. +.It Bq Er DW_DLV_NO_ENTRY +The object specified by arguments +.Fa "fd" +or +.Fa "elf" +did not contain debug information. +.El +.Sh EXAMPLES +To initialize a +.Vt Dwarf_Debug +instance from a open file descriptor referencing an ELF object, and +with the default error handler, use: +.Bd -literal -offset indent +Dwarf_Error err; +Dwarf_Debug dbg; + +if (dwarf_init(fd, DW_DLC_READ, NULL, NULL, &dbg, &err) != + DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_init: %s", dwarf_errmsg(err)); +.Ed +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errmsg 3 , +.Xr dwarf_finish 3 , +.Xr dwarf_get_elf 3 , +.Xr elf_begin 3 , +.Xr elf_memory 3 diff --git a/static/netbsd/man3/dwarf_lineno.3 b/static/netbsd/man3/dwarf_lineno.3 new file mode 100644 index 00000000..1bec951a --- /dev/null +++ b/static/netbsd/man3/dwarf_lineno.3 @@ -0,0 +1,206 @@ +.\" $NetBSD: dwarf_lineno.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_lineno.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd February 5, 2011 +.Dt DWARF_LINENO 3 +.Os +.Sh NAME +.Nm dwarf_lineaddr , +.Nm dwarf_linebeginstatement , +.Nm dwarf_lineblock , +.Nm dwarf_lineendsequence , +.Nm dwarf_lineno , +.Nm dwarf_lineoff , +.Nm dwarf_linesrc , +.Nm dwarf_line_srcfileno +.Nd retrieve information associated with a DWARF line descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_lineaddr +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Addr *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_linebeginstatement +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_lineblock +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_lineendsequence +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Bool *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_lineno +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Unsigned *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_lineoff +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Signed *ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_linesrc +.Fa "Dwarf_Line ln" +.Fa "char **ret" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_line_srcfileno +.Fa "Dwarf_Line ln" +.Fa "Dwarf_Unsigned *ret" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions retrieve specific line information associated with +the line descriptor specified by argument +.Fa ln , +and stores it in the location pointed to by argument +.Fa ret . +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_lineaddr +stores the program address corresponding to the source line specified +in argument +.Fa ln +into the location pointed to by argument +.Fa ret . +.Pp +Function +.Fn dwarf_linebeginstatement +sets the location pointed to by argument +.Fa ret +to 1 if the source line specified by the line descriptor +.Fa ln +is the beginning of a statement, or to 0 otherwise. +.Pp +Function +.Fn dwarf_lineblock +sets the location pointed to by argument +.Fa ret +to 1 if the source line specified by the line descriptor +.Fa ln +is the beginning of a basic block, or to 0 otherwise. +.Pp +Function +.Fn dwarf_lineendsequence +sets the location pointed to by argument +.Fa ret +to 1 if the program address associated with the line descriptor +.Fa ln +is the address immediately following the end of a sequence of target +machine instructions, or to 0 otherwise. +.Pp +Function +.Fn dwarf_lineno +stores the line number of the source line associated with the line +descriptor +.Fa ln +into the location pointed to by argument +.Fa ret . +.Pp +Function +.Fn dwarf_lineoff +stores the column number within a line associated with descriptor +.Fa ln +into the location pointed to by argument +.Fa ret . +The retrieved column numbers are 1-based, with the value -1 indicating +that column number information was not available. +.Pp +Function +.Fn dwarf_linesrc +stores a pointer to a NUL-terminated string containing the source file +name associated with line descriptor +.Fa ln +into the location pointed to by argument +.Fa ret . +The full path of the source file is returned if possible. +The memory used for the source file name string is managed by the DWARF(3) +library and should not be directly freed by application code. +Instead, portable code should use +.Xr dwarf_dealloc 3 +to indicate that the string should be freed. +.Pp +Function +.Fn dwarf_line_srcfileno +stores the index of the source file associated with the line descriptor +.Fa ln +in the location pointed to by argument +.Fa ret . +The returned value is 1-based index into the array of source file +names returned by +.Xr dwarf_srcfiles 3 . +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_LINE_FILE_NUM_BAD" +.It Bq Er DW_DLE_ARGUMENT +Either of the arguments +.Va ln +or +.Va ret +was +.Dv NULL . +.It Bq Er DW_DLE_LINE_FILE_NUM_BAD +The source file name associated with the line descriptor +.Fa ln +could not be retrieved by function +.Fn dwarf_linesrc . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_srcfiles 3 , +.Xr dwarf_srclines 3 diff --git a/static/netbsd/man3/dwarf_lne_end_sequence.3 b/static/netbsd/man3/dwarf_lne_end_sequence.3 new file mode 100644 index 00000000..cfeca060 --- /dev/null +++ b/static/netbsd/man3/dwarf_lne_end_sequence.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: dwarf_lne_end_sequence.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_lne_end_sequence.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 15, 2011 +.Dt DWARF_LNE_END_SEQUENCE 3 +.Os +.Sh NAME +.Nm dwarf_lne_end_sequence +.Nd set the end of instruction sequence +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_lne_end_sequence +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Addr addr" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_lne_end_sequence +sets the address that indicates the end of a sequence of target machine +instructions. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa addr +specifies an address value which is the first byte after the end of a +instruction sequence. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_lne_end_sequence +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_lne_end_sequence +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_lne_end_sequence +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The value in argument +.Fa addr +overlapped an existing line information entry. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_directory_decl 3 , +.Xr dwarf_add_file_decl 3 , +.Xr dwarf_add_line_entry 3 , +.Xr dwarf_lne_set_address 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_lne_set_address.3 b/static/netbsd/man3/dwarf_lne_set_address.3 new file mode 100644 index 00000000..6d8e65e3 --- /dev/null +++ b/static/netbsd/man3/dwarf_lne_set_address.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: dwarf_lne_set_address.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_lne_set_address.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 14, 2011 +.Dt DWARF_LNE_SET_ADDRESS 3 +.Os +.Sh NAME +.Nm dwarf_lne_set_address +.Nd set the base address for line number information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_Unsigned" +.Fo dwarf_lne_set_address +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Addr off" +.Fa "Dwarf_Unsigned symndx" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_lne_set_address +sets the base address used by subsequent invocations of the +.Xr dwarf_add_line_entry 3 +function. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa off +specifies a relocatable program address. +.Pp +Argument +.Fa symndx +specifies the index of the ELF symbol to be used for relocation. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_lne_set_address +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_lne_set_address +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_lne_set_address +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The argument +.Fa symndx +had an illegal value. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_directory_decl 3 , +.Xr dwarf_add_file_decl 3 , +.Xr dwarf_add_line_entry 3 , +.Xr dwarf_lne_end_sequence 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_loclist.3 b/static/netbsd/man3/dwarf_loclist.3 new file mode 100644 index 00000000..fb63d2ee --- /dev/null +++ b/static/netbsd/man3/dwarf_loclist.3 @@ -0,0 +1,235 @@ +.\" $NetBSD: dwarf_loclist.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_loclist.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_LOCLIST 3 +.Os +.Sh NAME +.Nm dwarf_loclist , +.Nm dwarf_loclist_n +.Nd retrieve DWARF location expression information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_loclist +.Fa "Dwarf_Attribute at" +.Fa "Dwarf_Locdesc **llbuf" +.Fa "Dwarf_Signed *listlen" +.Fa "Dwarf_Error *error" +.Fc +.Ft int +.Fo dwarf_loclist_n +.Fa "Dwarf_Attribute at" +.Fa "Dwarf_Locdesc ***llbuf" +.Fa "Dwarf_Signed *listlen" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +These functions retrieve the location expressions +associated with a DWARF attribute. +.Pp +Note: function +.Fn dwarf_loclist +is deprecated. +New application code should instead use function +.Fn dwarf_loclist_n +.Pp +Function +.Fn dwarf_loclist_n +retrieves the list of location expressions associated with a DWARF +attribute. +Argument +.Fa at +should reference a valid DWARF attribute. +Argument +.Fa llbuf +should point to a location which will hold a returned array of +pointers to +.Vt Dwarf_Locdesc +descriptors. +Argument +.Fa listlen +should point to a location which will be set to the number of +elements contained in the returned array. +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_loclist +retrieves the first location expression associated with an attribute. +Argument +.Fa at +should reference a valid DWARF attribute. +Argument +.Fa llbuf +should point to a location which will hold the returned pointer +to a +.Vt Dwarf_Locdesc +descriptor. +Argument +.Fa listlen +should point to a location which will be always set to 1. +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +.Vt Dwarf_Locdesc +descriptors are defined in the header file +.In libdwarf.h , +and consist of following fields: +.Pp +.Bl -tag -width ".Va ld_cents" -compact +.It Va ld_lopc +The lowest program counter address covered by the descriptor. +This field will be set to 0 if the descriptor is not associated with +an address range. +.It Va ld_hipc +The highest program counter address covered by the descriptor. +This field will be set to 0 if the descriptor is not associated with +an address range. +.It Va ld_cents +The number of entries returned in +.Va ld_s +field. +.It Va ld_s +Pointer to an array of +.Vt Dwarf_Loc +descriptors. +.El +.Pp +Each +.Vt Dwarf_Loc +descriptor represents one operation of a location expression. +These descriptors are defined in the header file +.In libdwarf.h , +and consist of following fields: +.Pp +.Bl -tag -width ".Va lr_number2" -compact +.It Va lr_atom +The operator name, one of the +.Dv DW_OP_* +constants defined in the header file +.In dwarf.h . +.It Va lr_number +The first operand of this operation. +.It Va lr_number2 +The second operand of this operation. +.It Va lr_offset +The byte offset of this operation within the containing location +expression. +.El +.Ss Memory Management +The memory area used for the descriptor array returned in argument +.Fa llbuf +is allocated by the +.Lb libdwarf . +When the descriptor array is no longer needed, application code should +use function +.Xr dwarf_dealloc 3 +to free the memory area in the following manner: +.Bl -enum +.It +First, the +.Fa ld_s +field of each +.Vt Dwarf_Locdesc +descriptor should be deallocated using the allocation type +.Dv DW_DLA_LOC_BLOCK . +.It +Then, the application should free each +.Vt Dwarf_Locdesc +descriptor using the allocation type +.Dv DW_DLA_LOCDESC . +.It +Finally, the +.Va llbuf +pointer should be deallocated using the allocation type +.Dv DW_DLA_LIST . +.El +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh EXAMPLES +To retrieve the location list associated with an attribute, use: +.Bd -literal -offset indent +Dwarf_Attribute at; +Dwarf_Locdesc **llbuf; +Dwarf_Signed lcnt; +Dwarf_Loc *lr; +Dwarf_Error de; +int i; + +if (dwarf_loclist_n(at, &llbuf, &lcnt, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_loclist_n failed: %s", + dwarf_errmsg(de)); + +for (i = 0; i < lcnt; i++) { + /* ... Use llbuf[i] ... */ + for (j = 0; (Dwarf_Half) j < llbuf[i]->ld_cents; j++) { + lr = &llbuf[i]->ld_s[j]; + /* ... Use each Dwarf_Loc descriptor ... */ + } + dwarf_dealloc(dbg, llbuf[i]->ld_s, DW_DLA_LOC_BLOCK); + dwarf_dealloc(dbg, llbuf[i], DW_DLA_LOCDESC); +} +dwarf_dealloc(dbg, llbuf, DW_DLA_LIST); +.Ed +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa at , +.Fa llbuf +or +.Fa listlen +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The attribute provided by argument +.Fa at +does not contain a location expression or is not associated with a +location expression list. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_loclist_entry 3 , +.Xr dwarf_loclist_from_expr 3 , +.Xr dwarf_loclist_from_expr_a 3 diff --git a/static/netbsd/man3/dwarf_loclist_from_expr.3 b/static/netbsd/man3/dwarf_loclist_from_expr.3 new file mode 100644 index 00000000..7cd4c784 --- /dev/null +++ b/static/netbsd/man3/dwarf_loclist_from_expr.3 @@ -0,0 +1,205 @@ +.\" $NetBSD: dwarf_loclist_from_expr.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011,2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_loclist_from_expr.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd December 21, 2014 +.Dt DWARF_LOCLIST_FROM_EXPR 3 +.Os +.Sh NAME +.Nm dwarf_loclist_from_expr , +.Nm dwarf_loclist_from_expr_a , +.Nm dwarf_loclist_from_expr_b +.Nd translate DWARF location expression bytes +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_loclist_from_expr +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Ptr bytes_in" +.Fa "Dwarf_Unsigned bytes_len" +.Fa "Dwarf_Locdesc **llbuf" +.Fa "Dwarf_Signed *listlen" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_loclist_from_expr_a +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Ptr bytes_in" +.Fa "Dwarf_Unsigned bytes_len" +.Fa "Dwarf_Half addr_size" +.Fa "Dwarf_Locdesc **llbuf" +.Fa "Dwarf_Signed *listlen" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_loclist_from_expr_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Ptr bytes_in" +.Fa "Dwarf_Unsigned bytes_len" +.Fa "Dwarf_Half addr_size" +.Fa "Dwarf_Half offset_size" +.Fa "Dwarf_Small version" +.Fa "Dwarf_Locdesc **llbuf" +.Fa "Dwarf_Signed *listlen" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_loclist_from_expr +translates DWARF location expression bytes into a +.Vt Dwarf_Locdesc +descriptor. +The size for address related data is taken to be the default address +size for the object being read. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa bytes_in +should point to an array of DWARF location expression bytes. +.Pp +Argument +.Fa bytes_len +should specify the number of the location expression bytes to be +translated. +.Pp +Argument +.Fa llbuf +should point to a location which will be set to a pointer +to a returned +.Vt Dwarf_Locdesc +descriptor. +.Pp +Argument +.Fa listlen +should point to a location which will hold the number of the +.Vt Dwarf_Locdesc +descriptors returned. +In this case it is always set to 1. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +Function +.Fn dwarf_loclist_from_expr_a +is identical to function +.Fn dwarf_loclist_from_expr , +except that it requires one additional argument +.Fa addr_size , +which specifies the address size to use when translating the location +expression bytes. +.Pp +Function +.Fn dwarf_loclist_from_expr_b +is identical to function +.Fn dwarf_loclist_from_expr_a +except that it requires two additional arguments for translating the +location expression bytes. +Argument +.Fa offset_size +specifies the offset size, and argument +.Fa version +specifies the DWARF version. +These values are required to correctly translate the +.Dv DW_OP_GNU_implicit_pointer +opcode. +.Ss Memory Management +The memory area used for the descriptor returned in argument +.Fa llbuf +is allocated by +.Lb libdwarf . +When the descriptor is no longer needed, application code should use +function +.Xr dwarf_dealloc 3 +to free the memory area in two steps: +.Bl -enum -compact +.It +First, the array of +.Vt Dwarf_Loc +descriptors pointed to by the +.Fa ld_s +field of the +.Vt Dwarf_Locdesc +descriptor should be deallocated using the allocation type +.Dv DW_DLA_LOC_BLOCK . +.It +Next, the application should free the +.Fa llbuf +pointer using the allocation type +.Dv DW_DLA_LOCDESC . +.El +.Sh RETURN VALUES +On success, these functions returns +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Fa err . +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_LOC_EXPR_BAD" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va dbg , +.Va bytes_in , +.Va llbuf +or +.Va listlen +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa bytes_len +was 0. +.It Bq Er DW_DLE_ARGUMENT +The value of argument +.Fa addr_size +was invalid. +.It Bq Er DW_DLE_LOC_EXPR_BAD +An unknown or invalid operation was found in the location expression +bytes provided in argument +.Fa bytes_in . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_loclist_entry 3 , +.Xr dwarf_loclist_n 3 diff --git a/static/netbsd/man3/dwarf_new_die.3 b/static/netbsd/man3/dwarf_new_die.3 new file mode 100644 index 00000000..7977799f --- /dev/null +++ b/static/netbsd/man3/dwarf_new_die.3 @@ -0,0 +1,170 @@ +.\" $NetBSD: dwarf_new_die.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_new_die.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 4, 2011 +.Dt DWARF_NEW_DIE 3 +.Os +.Sh NAME +.Nm dwarf_new_die +.Nd allocate a new debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Die +.Fo dwarf_new_die +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Tag tag" +.Fa "Dwarf_P_Die parent" +.Fa "Dwarf_P_Die child" +.Fa "Dwarf_P_Die left" +.Fa "Dwarf_P_Die right" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_new_die +allocates a new DWARF debugging information entry and links it +to another debugging information entry. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa tag +should specify the tag of the newly created debugging information entry. +Valid values for this argument are those for the +.Dv DW_TAG_ Ns * +symbols defined in +.In libdwarf.h . +.Pp +Argument +.Fa parent +specifies the parent link of the debugging information entry. +.Pp +Argument +.Fa child +specifies the first child link of the debugging information entry. +.Pp +Argument +.Fa left +specifies the left sibling link of the debugging information entry. +.Pp +Argument +.Fa right +specifies the right sibling link of the debugging information entry. +.Pp +Only one of arguments +.Fa parent , +.Fa child , +.Fa left +and +.Fa right +is allowed to be +.No non- Ns Dv NULL . +Application code can subsequently call the function +.Xr dwarf_die_link 3 +to change the links for the created debugging information entry. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_new_die +returns the newly created debugging information entry. +In case of an error, function +.Fn dwarf_new_die +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh EXAMPLES +To create debugging information entries and add them to the producer +instance, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_P_Die die1, die2; +Dwarf_Error de; + +/* ... assume dbg refers to a DWARF producer instance ... */ + +die1 = dwarf_new_die(dbg, DW_TAG_compilation_unit, NULL, NULL, NULL, + NULL, &de); +if (die1 == NULL) { + warnx("dwarf_new_die failed: %s", dwarf_errmsg(-1)); + return; +} + +die2 = dwarf_new_die(dbg, DW_TAG_base_type, die1, NULL, NULL, + NULL, &de); +if (die1 == NULL) { + warnx("dwarf_new_die failed: %s", dwarf_errmsg(-1)); + return; +} + +if (dwarf_add_die_to_debug(dbg, die1, &de) != DW_DLV_OK) { + warnx("dwarf_add_die_to_debug failed: %s", dwarf_errmsg(-1)); + return; +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_new_die +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +More than one of the arguments +.Fa parent , +.Fa child , +.Fa left +and +.Fa right +were +.No non- Ns Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_die_to_debug 3 , +.Xr dwarf_die_link 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_new_expr.3 b/static/netbsd/man3/dwarf_new_expr.3 new file mode 100644 index 00000000..a1a49ca0 --- /dev/null +++ b/static/netbsd/man3/dwarf_new_expr.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: dwarf_new_expr.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_new_expr.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 8, 2011 +.Dt DWARF_NEW_EXPR 3 +.Os +.Sh NAME +.Nm dwarf_new_expr +.Nd create a location expression descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Expr" +.Fo dwarf_new_expr +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_new_expr +allocates a DWARF location expression descriptor used to build up a +location expression stream. +.Pp +The application can use the functions +.Xr dwarf_add_expr_gen 3 +and +.Xr dwarf_add_expr_addr_b 3 +to add location expression operators to the created descriptor. +When done, the application can call the function +.Xr dwarf_expr_into_block 3 +to retrieve the generated byte stream for the location expression, +or call the function +.Xr dwarf_add_AT_location_expr 3 +to create an attribute with the location expression stream as its +value. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_new_expr +returns the created location expression descriptor. +In case of an error, function +.Fn dwarf_new_expr +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh EXAMPLES +To create a location expression descriptor, add location expression +operators to it and to retrieve the generated byte stream, +use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Error de; +Dwarf_P_Expr pe; +Dwarf_Addr buf; +Dwarf_Unsigned len; + +/* ...Assume that `dbg' refers to a DWARF producer instance... */ + +if ((pe = dwarf_new_expr(dbg, &de)) == DW_DLV_BADADDR) { + warnx("dwarf_new_expr failed: %s", dwarf_errmsg(-1)); + return; +} + +if (dwarf_add_expr_gen(pe, DW_OP_regx, 55, 0, &de) == + DW_DLV_NOCOUNT) { + warnx("dwarf_add_expr_gen failed: %s", dwarf_errmsg(-1)); + return; +} + +if ((buf = dwarf_expr_into_block(pe, &len, &de)) == + DW_DLV_BADADDR) { + warnx("dwarf_expr_into_block failed: %s", + dwarf_errmsg(-1)); + return; +} +.Ed +.Sh ERRORS +Function +.Fn dwarf_new_expr +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_AT_location_expr 3 , +.Xr dwarf_add_expr_addr 3 , +.Xr dwarf_add_expr_addr_b 3 , +.Xr dwarf_add_expr_gen 3 , +.Xr dwarf_expr_current_offset 3 , +.Xr dwarf_expr_into_block 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_new_fde.3 b/static/netbsd/man3/dwarf_new_fde.3 new file mode 100644 index 00000000..838d25bb --- /dev/null +++ b/static/netbsd/man3/dwarf_new_fde.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: dwarf_new_fde.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_new_fde.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 24, 2011 +.Dt DWARF_NEW_FDE 3 +.Os +.Sh NAME +.Nm dwarf_new_fde +.Nd allocate a DWARF frame descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "Dwarf_P_Fde" +.Fo dwarf_new_fde +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_new_fde +allocates a new DWARF frame descriptor. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_new_fde +returns the newly created frame descriptor. +In case of an error, function +.Fn dwarf_new_fde +returns +.Dv DW_DLV_BADADDR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_new_fde +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_cie 3 , +.Xr dwarf_add_frame_fde 3 , +.Xr dwarf_add_frame_fde_b 3 , +.Xr dwarf_fde_cfa_offset 3 diff --git a/static/netbsd/man3/dwarf_next_cu_header.3 b/static/netbsd/man3/dwarf_next_cu_header.3 new file mode 100644 index 00000000..64e946d0 --- /dev/null +++ b/static/netbsd/man3/dwarf_next_cu_header.3 @@ -0,0 +1,324 @@ +.\" $NetBSD: dwarf_next_cu_header.3,v 1.6 2024/03/03 17:37:31 christos Exp $ +.\" +.\" Copyright (c) 2010,2014,2023 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_next_cu_header.3 4013 2023-10-14 22:40:50Z kaiwang27 +.\" +.Dd October 15, 2023 +.Dt DWARF_NEXT_CU_HEADER 3 +.Os +.Sh NAME +.Nm dwarf_next_cu_header , +.Nm dwarf_next_cu_header_b , +.Nm dwarf_next_cu_header_c , +.Nm dwarf_next_cu_header_d +.Nd step through compilation units in a DWARF debug context +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_next_cu_header +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned *cu_length" +.Fa "Dwarf_Half *cu_version" +.Fa "Dwarf_Off *cu_abbrev_offset" +.Fa "Dwarf_Half *cu_pointer_size" +.Fa "Dwarf_Unsigned *cu_next_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_next_cu_header_b +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Unsigned *cu_length" +.Fa "Dwarf_Half *cu_version" +.Fa "Dwarf_Off *cu_abbrev_offset" +.Fa "Dwarf_Half *cu_pointer_size" +.Fa "Dwarf_Half *cu_offset_size" +.Fa "Dwarf_Half *cu_extension_size" +.Fa "Dwarf_Unsigned *cu_next_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_next_cu_header_c +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Unsigned *cu_length" +.Fa "Dwarf_Half *cu_version" +.Fa "Dwarf_Off *cu_abbrev_offset" +.Fa "Dwarf_Half *cu_pointer_size" +.Fa "Dwarf_Half *cu_offset_size" +.Fa "Dwarf_Half *cu_extension_size" +.Fa "Dwarf_Sig8 *type_signature" +.Fa "Dwarf_Unsigned *type_offset" +.Fa "Dwarf_Unsigned *cu_next_offset" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_next_cu_header_d +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Unsigned *cu_length" +.Fa "Dwarf_Half *cu_version" +.Fa "Dwarf_Off *cu_abbrev_offset" +.Fa "Dwarf_Half *cu_pointer_size" +.Fa "Dwarf_Half *cu_offset_size" +.Fa "Dwarf_Half *cu_extension_size" +.Fa "Dwarf_Sig8 *type_signature" +.Fa "Dwarf_Unsigned *type_offset" +.Fa "Dwarf_Unsigned *cu_next_offset" +.Fa "Dwarf_Half *cu_type" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +These functions are used to step through compilation or type units +associated with a DWARF debug context, optionally returning information +about the unit. +.Pp +Function +.Fn dwarf_next_cu_header_d +is the API recommended for new application code. +Function +.Fn dwarf_next_cu_header_c +can not return the unit type defined by the DWARF5 standard. +Function +.Fn dwarf_next_cu_header +and +.Fn dwarf_next_cu_header_b +can only operate on compilation units associated with the +.Dq \&.debug_info +section. +The earlier revisions are less general than function +.Fn dwarf_next_cu_header_d , +and are deprecated for use by new application code. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +If argument +.Fa is_info +is set to 1, +the function returns information for compilation units found in the +.Dq \&.debug_info +section. +If argument +.Fa is_info +is set to 0, +the function returns information for type units found in the +.Dq \&.debug_types +sections. +Argument +.Fa cu_length +should point to a location that will be set to the +length of the compilation or type unit. +Argument +.Fa cu_version +should point to a location that will be set to the +version number for the compilation or type unit. +Argument +.Fa cu_abbrev_offset +should point to a location that will be set to the +starting offset (in the +.Dq .debug_abbrev +section) of the set of debugging information entry abbreviations +associated with this compilation or type unit. +Argument +.Fa cu_pointer_size +should point to a location that will be set to the +size in bytes of an address for the machine architecture of the +underlying object being debugged. +Argument +.Fa cu_offset_size +should point to a location that will be set to the +size in bytes for a DWARF offset in the compilation or type unit. +Argument +.Fa cu_extension_size +is only needed for processing MIPS/IRIX objects that use +a non-standard DWARF format. +It should point to a location that will be set to 4 for normal +objects and to 0 for non-standard ones. +Argument +.Fa type_signature +and +.Fa type_offset +is only needed for processing type units. +Argument +.Fa type_signature +should point to a location that will be set to the 64-bit unique signature +of the type described in the type unit. +Argument +.Fa type_offset +should point to a location that will be set to the offset of the debugging +information entry that describes the type. +Argument +.Fa cu_next_offset +should point to a location that will be set to the +offset of the next compilation unit header in the +.Dq \&.debug_info +section, +or the offset of the next type unit header in the +.Dq \&.debug_types +section. +Argument +.Fa cu_type +should point to a location that will be set to the +type of the compilation unit. +Argument +.Fa err +should point to a location that will hold an error descriptor in case +of an error. +.Pp +Function +.Fn dwarf_next_cu_header_c +is identical to function +.Fn dwarf_next_cu_header_d +except that it does not provide argument +.Fa cu_type . +.Pp +Function +.Fn dwarf_next_cu_header_b +is identical to function +.Fn dwarf_next_cu_header_c +except that it does not provide arguments +.Fa is_info , +.Fa type_signature +and +.Fa type_offset . +.Pp +Function +.Fn dwarf_next_cu_header +is identical to function +.Fn dwarf_next_cu_header_b +except that it does not provide arguments +.Fa cu_offset_size +and +.Fa cu_extension_size . +.Pp +A value of +.Dv NULL +may be used for any of the arguments +.Fa cu_length , +.Fa cu_version , +.Fa cu_abbrev_offset , +.Fa cu_pointer_size , +.Fa cu_offset_size , +.Fa cu_extension_size , +.Fa type_signature , +.Fa type_offset , +.Fa cu_next_offset , +.Fa cu_type +and +.Fa err +if the caller is not interested in the respective value. +.Ss Iterating Through Compilation Units in a Debug Context +The first call to function +.Fn dwarf_next_cu_header_c +for a given debug context with argument +.Fa is_info +set to 1 will return information about the first +compilation unit in the +.Dq \&.debug_info +section. +Subsequent calls to the function will iterate through the remaining +compilation units in the section. +On stepping past the last compilation unit in the section, +function +.Fn dwarf_next_cu_header_d +returns +.Dv DW_DLV_NO_ENTRY +and resets its internal state. +The next call to the function will restart from the first compilation +unit in the section. +.Ss Iterating Through Type Units in a Debug Context +When a DWARF debug context is allocated using +.Xr dwarf_init 3 , +an internal pointer associated with the context will point to the first +.Dq \&.debug_types +section found in the debug object. +The first call to function +.Fn dwarf_next_cu_header_d +for the debug context with argument +.Fa is_info +set to 0 will return information about the first +type unit in that +.Dq \&.debug_types +section. +Subsequent calls to the function will iterate through the remaining +type units in the section. +On stepping past the last type unit in the debug context, +function +.Fn dwarf_next_cu_header_d +returns +.Dv DW_DLV_NO_ENTRY +and resets its internal state. +The next call to the function will restart from the first type +unit in the +.Dq \&.debug_types +section. +.Pp +If the debug object contains multiple +.Dq \&.debug_types +sections, the function +.Fn dwarf_next_types_section +can be called to move the internal pointer to the next +.Dq \&.debug_types +section. +As a result, subsequent calls of the function +.Fn dwarf_next_cu_header_d +will operate on the new +.Dq \&.debug_types +section. +Function +.Fn dwarf_next_types_section +returns +.Dv DW_DLV_NO_ENTRY +when there are no more +.Dq \&.debug_types +sections left in the debug object. +.Sh RETURN VALUES +On success, these functions return +.Dv DW_DLV_OK . +In case of an error, they return +.Dv DW_DLV_ERROR +and set argument +.Fa err . +When there are no more compilation units left to traverse, they return +.Dv DW_DLV_NO_ENTRY . +.Sh ERRORS +These functions can fail with the following error: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Va dbg +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , +.Xr dwarf_init 3 , +.Xr dwarf_next_types_section 3 , +.Xr dwarf_siblingof 3 diff --git a/static/netbsd/man3/dwarf_next_types_section.3 b/static/netbsd/man3/dwarf_next_types_section.3 new file mode 100644 index 00000000..9d7e053f --- /dev/null +++ b/static/netbsd/man3/dwarf_next_types_section.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: dwarf_next_types_section.3,v 1.5 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2014 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_next_types_section.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd December 20, 2014 +.Dt DWARF_NEXT_TYPES_SECTION 3 +.Os +.Sh NAME +.Nm dwarf_next_types_section +.Nd step through .debug_types sections in a debug context +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_next_types_section +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_next_types_section +steps through the +.Dq \&.debug_types +sections found in a debug context. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +Argument +.Fa err +should point to a location that will hold an error descriptor in case +of an error. +.Pp +When a DWARF debug context is allocated using +.Xr dwarf_init 3 , +an internal pointer associated with the context will point to the +first +.Dq \&.debug_types +section present in the debug object. +When the application calls function +.Fn dwarf_next_types_section , +this internal pointer will move to the next +.Dq \&.debug_types +section present. +On stepping past the last +.Dq \&.debug_types +section left in the debug context, function +.Fn dwarf_next_types_section +returns +.Dv DW_DLV_NO_ENTRY . +The next call to the function will restart from the first +.Dq \&.debug_types +section in the debug context. +.Pp +Application code should call function +.Xr dwarf_next_cu_header_c 3 +to iterate though the type units associated with the current +.Dq \&.debug_types +section. +.Sh RETURN VALUES +On success, function +.Fn dwarf_next_types_section +returns +.Dv DW_DLV_OK . +.Pp +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +When there are no more +.Dq \&.debug_types +sections left to traverse, it returns +.Dv DW_DLV_NO_ENTRY . +.Sh EXAMPLES +To iterate though every type unit in all the +.Dq \&.debug_types +sections found in a debug context: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Sig8 sig8; +Dwarf_Unsigned typeoff; +Dwarf_Error de; + +\&... allocate dbg using dwarf_init() etc ... + +do { + while ((ret = dwarf_next_cu_header_c(dbg, 0, NULL, NULL, NULL, + NULL, NULL, NULL, &sig8, &typeoff, NULL, &de)) == DW_DLV_OK) { + /* Access DIEs etc ... */ + } +} while (dwarf_next_types_section(dbg, &de) == DW_DLV_OK); +.Ed +.Sh COMPATIBILITY +This function is an extension to the +.Xr DWARF 3 +API. +.Sh ERRORS +The +.Fn dwarf_next_types_section +function may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Va dbg +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_init 3 , +.Xr dwarf_next_cu_header_c 3 diff --git a/static/netbsd/man3/dwarf_object_init.3 b/static/netbsd/man3/dwarf_object_init.3 new file mode 100644 index 00000000..ffd002ad --- /dev/null +++ b/static/netbsd/man3/dwarf_object_init.3 @@ -0,0 +1,229 @@ +.\" $NetBSD: dwarf_object_init.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_object_init.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 29, 2011 +.Dt DWARF_OBJECT_INIT 3 +.Os +.Sh NAME +.Nm dwarf_object_init +.Nd allocate a DWARF debug descriptor with application-specific file \ +access methods +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_object_init +.Fa "Dwarf_Obj_Access_Interface *iface" +.Fa "Dwarf_Handler errhand" +.Fa "Dwarf_Ptr errarg" +.Fa "Dwarf_Debug *dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +The +.Fn dwarf_object_init +function allocates and returns a +.Vt Dwarf_Debug +instance that uses application-supplied access methods to read file +content. +.Pp +The argument +.Fa iface +should point to a populated +.Vt Dwarf_Obj_Access_Interface +structure. +The contents of the +.Vt Dwarf_Obj_Access_Interface +structure are described in the section +.Sx "Object Access Functions" +below. +.Pp +The argument +.Fa errhand +should point to a function to be called in case of an error. +If this argument is +.Dv NULL +then a default error handling scheme is used. +See +.Xr dwarf 3 +for a description of the error handling schemes available. +.Pp +The argument +.Fa errarg +will be passed to the error handler function pointed to by argument +.Fa errhand . +.Pp +The argument +.Fa dbg +should point to a memory location that will be set to a reference to +the returned +.Vt Dwarf_Debug +descriptor. +.Pp +The argument +.Fa err +will be used to return a +.Vt Dwarf_Error +descriptor in case of an error. +.Ss Object Access Functions +The data structures used to specify object access methods are defined +in +.In libdwarf.h . +.Bl -tag -width indent +.It Vt "Dwarf_Obj_Access_Interface" +This structure bundles together a set of file access methods along +with a pointer to application-private state. +.Bd -literal -offset indent +typedef struct { + void *object; + const Dwarf_Obj_Access_Methods *methods; +} Dwarf_Obj_Access_Interface; +.Ed +.Pp +.Bl -tag -width ".Ar methods" -compact +.It Ar object +This field points to application-specific state that will be passed as +the first parameter to the actual access object methods. +.It Ar methods +This structure contains pointers to the functions implementing the +access methods, as described below. +.El +.It Vt Dwarf_Obj_Access_Methods +This structure specifies the functions implementing low-level access. +.Bd -literal -offset indent +typedef struct { + int (*get_section_info)(void *obj, Dwarf_Half index, + Dwarf_Obj_Access_Section *ret, int *error); + Dwarf_Endianness (*get_byte_order)(void *obj); + Dwarf_Small (*get_length_size)(void *obj); + Dwarf_Small (*get_pointer_size)(void *obj); + Dwarf_Unsigned (*get_section_count)(void *obj); + int (*load_section)(void *obj, Dwarf_Half ndx, + Dwarf_Small **ret_data, int *error); +} Dwarf_Obj_Access_Methods; +.Ed +.Pp +.Bl -tag -width ".Ar get_section_count" -compact +.It Ar get_byte_order +This function should return the endianness of the DWARF object by +returning one of the constants +.Dv DW_OBJECT_MSB +or +.Dv DW_OBJECT_LSB . +.It Ar get_length_size +This function should return the number of bytes needed to represent a +DWARF offset in the object being debugged. +.It Ar get_pointer_size +This function should return the size in bytes, in the object being +debugged, of a memory address. +.It Ar get_section_count +This function should return the number of sections in the object being +debugged. +.It Ar get_section_info +This function should return information about the section at the +index +.Fa ndx +by filling in the structure of type +.Vt Dwarf_Obj_Access_Section +pointed to by argument +.Fa ret . +The +.Vt Dwarf_Obj_Access_Section +structure is described below. +.It Ar load_section +This function should load the section specified by argument +.Fa ndx +into memory and place a pointer to the section's data into +the location pointed to by argument +.Fa ret_data . +.El +.Pp +The argument +.Fa obj +passed to these functions will be set to the pointer value in the +.Fa object +field of the associated +.Vt Dwarf_Obj_Access_Interface +structure. +.Pp +The argument +.Fa error +is used to return an error code in case of an error. +.It Vt Dwarf_Obj_Access_Section +This structure describes the layout of a section in the DWARF object. +.Bd -literal -offset indent +typedef struct { + Dwarf_Addr addr; + Dwarf_Unsigned size; + const char *name; +} Dwarf_Obj_Access_Section; +.Ed +.Pp +.Bl -tag -width ".Ar name" -compact +.It Ar addr +A pointer to the start of the section's data. +.It Ar size +The size of the section in bytes. +.It Ar name +A pointer to a NUL-terminated string containing the name of the +section. +.El +.El +.Sh RETURN VALUES +On success, the +.Fn dwarf_object_init +function returns +.Dv DW_DLV_OK . +In case of an error, the function returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +The +.Fn dwarf_object_init +function may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_DEBUG_INFO_NULL" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa iface +or +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_DEBUG_INFO_NULL +The underlying object did not contain debugging information. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_init 3 , +.Xr dwarf_init_elf 3 , +.Xr dwarf_object_finish 3 diff --git a/static/netbsd/man3/dwarf_producer_init.3 b/static/netbsd/man3/dwarf_producer_init.3 new file mode 100644 index 00000000..5fe35623 --- /dev/null +++ b/static/netbsd/man3/dwarf_producer_init.3 @@ -0,0 +1,299 @@ +.\" $NetBSD: dwarf_producer_init.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_producer_init.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd August 20, 2011 +.Dt DWARF_PRODUCER_INIT 3 +.Os +.Sh NAME +.Nm dwarf_producer_init , +.Nm dwarf_producer_init_b +.Nd allocate a DWARF producer descriptor +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_P_Debug +.Fo dwarf_producer_init +.Fa "Dwarf_Unsigned flags" +.Fa "Dwarf_Callback_Func func" +.Fa "Dwarf_Handler errhand" +.Fa "Dwarf_Ptr errarg" +.Fa "Dwarf_Error *err" +.Fc +.Ft Dwarf_P_Debug +.Fo dwarf_producer_init_b +.Fa "Dwarf_Unsigned flags" +.Fa "Dwarf_Callback_Func_b func" +.Fa "Dwarf_Handler errhand" +.Fa "Dwarf_Ptr errarg" +.Fa "Dwarf_Error *error" +.Fc +.Sh DESCRIPTION +These functions allocate and return a +.Vt Dwarf_P_Debug +descriptor representing a DWARF producer instance. +.Pp +The argument +.Fa errhand +should contain the address of a function to be called in case of an +error. +If this argument is +.Dv NULL , +the default error handling scheme is used, see +.Xr dwarf 3 . +.Pp +The argument +.Fa errarg +will be passed to the error handler function when it is invoked. +.Pp +The argument +.Fa err +references a memory location that would hold a +.Vt Dwarf_Error +descriptor in case of an error. +.Pp +The argument +.Fa flags +specifies additional characteristics of the DWARF producer instance. +The following flags are recognized: +.Bl -tag -width "Dv DW_DLC_ISA_MIPS" +.It Dv DW_DLC_ISA_IA64 +.Pq Deprecated +The target instruction set architecture is IA64. +This flag is deprecated. +Application code should use the +.Xr dwarf_producer_set_isa 3 +function to specify target instruction set architecture. +.It Dv DW_DLC_ISA_MIPS +.Pq Deprecated +The target instruction set architecture is MIPS. +This flag is deprecated. +Application code should use the +.Xr dwarf_producer_set_isa 3 +function to specify target instruction set architecture. +.It Dv DW_DLC_SIZE_32 +.Pq Default +The target address size is 32-bit. +.It Dv DW_DLC_SIZE_64 +The target address size is 64-bit. +.It Dv DW_DLC_STREAM_RELOCATIONS +.Pq Default +Generate stream relocations. +.It Dv DW_DLC_SYMBOLIC_RELOCATIONS +Generate symbolic relocations. +.It Dv DW_DLC_TARGET_BIGENDIAN +The target is big endian. +.It Dv DW_DLC_TARGET_LITTLEENDIAN +The target is little endian. +.It Dv DW_DLC_WRITE +.Pq Required +Permit writing of DWARF information. +.El +.Pp +The following flags are mutually exclusive. +.Bl -bullet -compact +.It +Flags +.Dv DW_DLC_ISA_IA64 +and +.Dv DW_DLC_ISA_MIPS . +.It +Flags +.Dv DW_DLC_SIZE_32 +and +.Dv DW_DLC_SIZE_64 . +.It +Flags +.Dv DW_DLC_STREAM_RELOCATIONS +and +.Dv DW_DLC_SYMBOLIC_RELOCATIONS . +.It +Flags +.Dv DW_DLC_TARGET_BIGENDIAN +and +.Dv DW_DLC_TARGET_LITTLEENDIAN . +.El +If neither of the flags +.Dv DW_DLC_TARGET_BIGENDIAN +and +.Dv DW_DLC_TARGET_LITTLEENDIAN +is set, the target's endianness is assumed to be the same as the host's +endianness. +.Pp +Argument +.Fa func +should point to an application-provided callback function of type +.Vt Dwarf_Callback_Func_b . +The type +.Vt Dwarf_Callback_Func_b +is defined in the header file +.In libdwarf.h +as: +.Bd -literal -offset indent +typedef int (*Dwarf_Callback_Func_b)(char *name, int size, + Dwarf_Unsigned type, Dwarf_Unsigned flags, Dwarf_Unsigned link, + Dwarf_Unsigned info, Dwarf_Unsigned *index, int *error); +.Ed +.Pp +This function is called by the +.Lb libdwarf +once for each section in the object file that the library needs to +create. +The arguments to this callback function specify the values in the ELF +section header for the section being created: +.Pp +.Bl -tag -width indent -compact -offset indent +.It Ar name +The name of the section being created. +.It Ar size +The +.Va sh_size +value in the section header. +.It Ar type +The +.Va sh_type +value in the section header. +.It Ar flags +The +.Va sh_flags +value in the section header. +.It Ar link +The +.Va sh_link +value in the section header. +.It Ar info +The +.Va sh_info +value in the section header. +.El +.Pp +On success, the callback function should return the section index +value of the created section, and set the location pointed to by +argument +.Fa index +to the symbol table index of the symbol that associated with the newly +created section. +This symbol table index will be used in relocation entries +referring to the created section. +.Pp +In case of failure, the callback function should return -1 and set the +location pointed to by argument +.Fa error +to an application-defined error code. +This application returned error code is currently ignored by the +library. +.Pp +Function +.Fn dwarf_producer_init +is deprecated. +Function +.Fn dwarf_producer_init +is identical to function +.Fn dwarf_producer_init_b +except that the callback function it expects can not properly handle +arbitrary section symbol index values. +.Ss Memory Management +The +.Vt Dwarf_P_Debug +instance returned by these functions should be freed using the +function +.Fn dwarf_producer_finish . +.Sh RETURN VALUES +On success, these functions return the created DWARF producer +descriptor. +In case of an error, they return +.Dv DW_DLV_BADADDR +and set the argument +.Fa err . +.Sh EXAMPLES +To initialize a +.Vt Dwarf_P_Debug +instance for a MIPS32 big endian object, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Unsigned flags; +Dwarf_Error de; + +/* ... assume cb_func points to the callback function ... */ + +flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS | + DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN; +if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) == + DW_DLV_BADADDR) + warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1)); +.Ed +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa func +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The flag +.Dv DW_DLC_WRITE +was not set in argument +.Fa flags . +.It Bq Er DW_DLE_ARGUMENT +The flags +.Dv DW_DLC_SIZE_32 +and +.Dv DW_DLC_SIZE_64 +were both set in argument +.Fa flags . +.It Bq Er DW_DLE_ARGUMENT +The flags +.Dv DW_DLC_ISA_IA64 +and +.Dv DW_DLC_ISA_MIPS +were both set in argument +.Fa flags . +.It Bq Er DW_DLE_ARGUMENT +The flags +.Dv DW_DLC_TARGET_BIGENDIAN +and +.Dv DW_DLC_TARGET_LITTLEENDIAN +were both set in argument +.Fa flags . +.It Bq Er DW_DLE_ARGUMENT +The flags +.Dv DW_DLC_STREAM_RELOCATIONS +and +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +were both set in argument +.Fa flags . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_errmsg 3 , +.Xr dwarf_producer_finish 3 , +.Xr dwarf_producer_set_isa 3 , +.Xr dwarf_transform_to_disk_form 3 diff --git a/static/netbsd/man3/dwarf_producer_set_isa.3 b/static/netbsd/man3/dwarf_producer_set_isa.3 new file mode 100644 index 00000000..d87b2db0 --- /dev/null +++ b/static/netbsd/man3/dwarf_producer_set_isa.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: dwarf_producer_set_isa.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_producer_set_isa.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 29, 2011 +.Dt DWARF_PRODUCER_SET_ISA 3 +.Os +.Sh NAME +.Nm dwarf_producer_set_isa +.Nd specify the instruction set architecture for a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_producer_set_isa +.Fa "Dwarf_P_Debug dbg" +.Fa "enum Dwarf_ISA isa" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +The function +.Fn dwarf_producer_set_isa +sets the instruction set architecture for a DWARF producer instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using one of +the functions +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa isa +specifies the desired instruction set architecture. +Legal values for this argument are those defined by the +.Vt "enum Dwarf_ISA" +enumeration defined in the header file +.In libdwarf.h . +.Pp +If the argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, the function +.Fn dwarf_producer_set_isa +returns +.Dv DW_DLV_OK . +In case of an error, this function returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh COMPATIBILITY +The +.Fn dwarf_producer_set_isa +function is a local extension. +.Sh ERRORS +The +.Fn dwarf_producer_set_isa +function can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +The argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_ARGUMENT +The argument +.Fa isa +was invalid. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_reset_section_bytes.3 b/static/netbsd/man3/dwarf_reset_section_bytes.3 new file mode 100644 index 00000000..b877636d --- /dev/null +++ b/static/netbsd/man3/dwarf_reset_section_bytes.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: dwarf_reset_section_bytes.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_reset_section_bytes.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 3, 2011 +.Dt DWARF_RESET_SECTION_BYTES 3 +.Os +.Sh NAME +.Nm dwarf_reset_section_bytes +.Nd reset the internal state of a producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft void +.Fo dwarf_reset_section_bytes +.Fa "Dwarf_P_Debug dbg" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_reset_section_bytes +resets the internal state of a DWARF producer instance, so that the +next call to the function +.Xr dwarf_get_section_bytes 3 +will return the byte stream for the first generated section, and +the next call to the function +.Xr dwarf_get_relocation_info 3 +will return the first relocation array for the DWARF producer +instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Sh RETURN VALUES +Function +.Fn dwarf_reset_section_bytes +has no return value. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_relocation_info 3 , +.Xr dwarf_get_section_bytes 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_transform_to_disk_form 3 diff --git a/static/netbsd/man3/dwarf_set_frame_cfa_value.3 b/static/netbsd/man3/dwarf_set_frame_cfa_value.3 new file mode 100644 index 00000000..881273f9 --- /dev/null +++ b/static/netbsd/man3/dwarf_set_frame_cfa_value.3 @@ -0,0 +1,142 @@ +.\" $NetBSD: dwarf_set_frame_cfa_value.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_set_frame_cfa_value.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd June 18, 2011 +.Dt DWARF_SET_FRAME_CFA_VALUE 3 +.Os +.Sh NAME +.Nm dwarf_set_frame_cfa_value , +.Nm dwarf_set_frame_rule_initial_value , +.Nm dwarf_set_frame_rule_table_size , +.Nm dwarf_set_frame_same_value , +.Nm dwarf_set_frame_undefined_value +.Nd set internal register rule table parameters +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Half +.Fo dwarf_set_frame_cfa_value +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half value" +.Fc +.Ft Dwarf_Half +.Fo dwarf_set_frame_rule_initial_value +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half value" +.Fc +.Ft Dwarf_Half +.Fo dwarf_set_frame_rule_table_size +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half value" +.Fc +.Ft Dwarf_Half +.Fo dwarf_set_frame_same_value +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half value" +.Fc +.Ft Dwarf_Half +.Fo dwarf_set_frame_undefined_value +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Half value" +.Fc +.Sh DESCRIPTION +These functions set the parameters of the internal register +rule table. +.Pp +Argument +.Fa dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Fa value +should hold the parameter value to set. +.Pp +Function +.Fn dwarf_set_frame_cfa_value +sets the column number for the CFA register rule in the internal +register rule table. +The constant +.Dv DW_FRAME_CFA_COL +is the default CFA register column number for DWARF2-only +interfaces, and the constant +.Dv DW_FRAME_CFA_COL3 +is the default CFA column number for DWARF3-compatible interfaces. +.Pp +Function +.Fn dwarf_set_frame_rule_initial_value +sets the initial value of the register rules in the internal register +rule table. +The default initial value is the constant +.Dv DW_FRAME_REG_INITIAL_VALUE , +defined in the header file +.In libdwarf.h . +.Pp +Function +.Fn dwarf_set_frame_rule_table_size +sets the maxmium number of columns of the internal register rule table. +Argument +.Fa value +should be at least as large as the number of real registers in the ABI. +.Pp +Function +.Fn dwarf_set_frame_same_value +sets the register number representing the +.Dq "same value" +register rule. +The default register number for the +.Dq "same value" +rule is the constant +.Dv DW_FRAME_SAME_VAL , +defined in the header file +.In libdwarf.h . +.Pp +Function +.Fn dwarf_set_frame_undefined_value +sets the register number representing the +.Dq undefined +register rule. +The default register number for the +.Dq undefined +rule is the constant +.Dv DW_FRAME_UNDEFINED_VAL , +defined in the header file +.In libdwarf.h . +.Sh RETURN VALUES +These functions return the previous value of the parameter being +set. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_fde_at_pc 3 , +.Xr dwarf_get_fde_info_for_all_regs 3 , +.Xr dwarf_get_fde_info_for_all_regs3 3 , +.Xr dwarf_get_fde_info_for_cfa_reg3 3 , +.Xr dwarf_get_fde_info_for_reg 3 , +.Xr dwarf_get_fde_info_for_reg3 3 , +.Xr dwarf_get_fde_n 3 diff --git a/static/netbsd/man3/dwarf_set_reloc_application.3 b/static/netbsd/man3/dwarf_set_reloc_application.3 new file mode 100644 index 00000000..97681d5a --- /dev/null +++ b/static/netbsd/man3/dwarf_set_reloc_application.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: dwarf_set_reloc_application.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_set_reloc_application.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd February 11, 2015 +.Dt DWARF_SET_RELOC_APPLICATION 3 +.Os +.Sh NAME +.Nm dwarf_set_reloc_application +.Nd set a library-wide relocation flag +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_set_reloc_application +.Fa "int apply" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_set_reloc_application +allows applications to specify how relocation information is to be +handled by the DWARF(3) library. +.Pp +If the argument +.Fa apply +holds a non-zero value, the library will process all the relevant +.Dq ".rel" +and +.Dq ".rela" +relocation sections and will apply the relocation records found to +their corresponding DWARF sections. +.Pp +If the argument +.Fa apply +is zero, the library will not attempt to apply any relocations. +.Pp +The default behaviour of the library is to process relocation records. +.Sh NOTES +Function +.Fn dwarf_set_reloc_application +should be called before initialising a dwarf debugging context, i.e, +it should be called by the application before calling either of the +functions +.Xr dwarf_init 3 +or +.Xr dwarf_elf_init 3 . +.Sh RETURN VALUES +Function +.Fn dwarf_set_reloc_application +returns the previous value of the library-wide relocation application +flag. +.Sh ERRORS +Function +.Fn dwarf_set_reloc_application +does not return an error. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_elf_init 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_seterrarg.3 b/static/netbsd/man3/dwarf_seterrarg.3 new file mode 100644 index 00000000..155ed410 --- /dev/null +++ b/static/netbsd/man3/dwarf_seterrarg.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: dwarf_seterrarg.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_seterrarg.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd May 01, 2010 +.Dt DWARF_SETERRARG 3 +.Os +.Sh NAME +.Nm dwarf_seterrarg , +.Nm dwarf_seterrhand +.Nd configure error handling +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Ptr +.Fn dwarf_seterrarg "Dwarf_Debug dbg" "Dwarf_Ptr arg" +.Ft Dwarf_Handler +.Fn dwarf_seterrhand "Dwarf_Debug dbg" "Dwarf_Handler handler" +.Sh DESCRIPTION +These functions may be used by applications to configure error handling +callbacks. +The error handling scheme used by the library is described in +.Xr dwarf 3 . +.Pp +Function +.Fn dwarf_seterrarg +may be used to set the callback argument passed to a configured +error handler at the time it is invoked. +Argument +.Fa arg +is the callback argument being set. +Argument +.Fa dbg +can be a debug context allocated by a prior call to +.Xr dwarf_init 3 , +or can be +.Dv NULL +to indicate that the library-wide callback argument +is to be set. +.Pp +Function +.Fn dwarf_seterrhand +may be used to associate an error handler denoted by argument +.Fa handler +with the DWARF debug context descriptor denoted by argument +.Fa dbg . +Argument +.Fa dbg +should be a debug context allocated by a prior call to +.Xr dwarf_init 3 , +or may be +.Dv NULL +to indicate that the library-wide error handler +is to be set. +.Sh RETURN VALUES +Function +.Fn dwarf_seterrhand +returns the previous error handler associated with argument +.Fa dbg . +If argument +.Fa dbg +is +.Dv NULL , +function +.Fn dwarf_seterrhand +returns the previous library-wide error handler. +.Pp +Function +.Fn dwarf_seterrarg +returns the previous callback argument associated with argument +.Fa dbg . +If argument +.Fa dbg +is +.Dv NULL , +function +.Fn dwarf_seterrarg +returns the previous library-wide callback argument. +.Sh COMPATIBILITY +The behavior of these functions when argument +.Fa dbg +is +.Dv NULL +is a local extension. +.Sh ERRORS +These functions do not set an error code. +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_init 3 diff --git a/static/netbsd/man3/dwarf_srcfiles.3 b/static/netbsd/man3/dwarf_srcfiles.3 new file mode 100644 index 00000000..5662aef2 --- /dev/null +++ b/static/netbsd/man3/dwarf_srcfiles.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: dwarf_srcfiles.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_srcfiles.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 28, 2010 +.Dt DWARF_SRCFILES 3 +.Os +.Sh NAME +.Nm dwarf_srcfiles +.Nd retrieve source file information +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_srcfiles +.Fa "Dwarf_Die die" +.Fa "char ***filenames" +.Fa "Dwarf_Signed *filenamecount" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_srcfiles +returns the source file names associated with a compilation unit. +Source file names are returned as an array of NUL-terminated strings. +.Pp +Argument +.Fa die +should reference a DWARF debugging information entry descriptor with +source file information, see +.Xr dwarf 3 . +Argument +.Fa filenames +should point to a location that will hold a pointer to the returned array +of file names. +Argument +.Fa filenamecount +should point to a location that will hold the number of file names returned. +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Ss Memory Management +The memory areas used for the file names and for array of pointers +being returned are managed by the DWARF(3) library. +The application should not attempt to directly free these memory areas. +Portable code should indicate that the memory areas are to be freed +by using +.Xr dwarf_dealloc 3 . +.Sh RETURN VALUES +Function +.Fn dwarf_srcfiles +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_srcfiles +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa die , +.Fa filenames +or +.Fa filenamecount +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The compilation unit referenced by argument +.Fa die +does not have associated source file information. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_dealloc 3 , +.Xr dwarf_srclines 3 diff --git a/static/netbsd/man3/dwarf_srclines.3 b/static/netbsd/man3/dwarf_srclines.3 new file mode 100644 index 00000000..222efdb7 --- /dev/null +++ b/static/netbsd/man3/dwarf_srclines.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: dwarf_srclines.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: dwarf_srclines.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_SRCLINES 3 +.Os +.Sh NAME +.Nm dwarf_srclines +.Nd retrieve line number information for a debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_srclines +.Fa "Dwarf_Die die" +.Fa "Dwarf_Line **lines" +.Fa "Dwarf_Signed *nlines" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_srclines +returns line number information associated with a compilation unit. +Line number information is returned as an array of +.Vt Dwarf_Line +descriptors. +.Pp +Argument +.Fa die +should reference a DWARF debugging information entry descriptor +with line number information, see +.Xr dwarf 3 . +Argument +.Fa lines +should point to a location that will hold a pointer to the returned array +of +.Vt Dwarf_Line +descriptors. +Argument +.Fa nlines +should point to a location that will hold the number of descriptors +returned. +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +The returned +.Vt Dwarf_Line +descriptors may be passed to the other line number functions in the +API set to retrieve specific information about each source line. +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Line +descriptors returned in argument +.Fa lines +is owned by the +.Lb libdwarf . +The application should not attempt to free this pointer. +Portable code should instead use +.Fn dwarf_srclines_dealloc +to indicate that the memory may be freed. +.Sh RETURN VALUES +Function +.Fn dwarf_srclines +returns +.Dv DW_DLV_OK +when it succeeds. +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To obtain an array of +.Vt Dwarf_Line +descriptors and to retrieve the source file, line number, and virtual address +associated with each descriptor: +.Bd -literal -offset indent +int n; +Dwarf_Die die; +Dwarf_Error de; +char *filename; +Dwarf_Line *lines; +Dwarf_Signed nlines; +Dwarf_Addr lineaddr; +Dwarf_Unsigned lineno; + +/* variable "die" should reference a DIE for a compilation unit */ + +if (dwarf_srclines(die, &lines, &nlines, &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_srclines: %s", dwarf_errmsg(de)); + +for (n = 0; n < nlines; n++) { + /* Retrieve the file name for this descriptor. */ + if (dwarf_linesrc(lines[n], &filename, &de)) + errx(EXIT_FAILURE, "dwarf_linesrc: %s", + dwarf_errmsg(de)); + + /* Retrieve the line number in the source file. */ + if (dwarf_lineno(lines[n], &lineno, &de)) + errx(EXIT_FAILURE, "dwarf_lineno: %s", + dwarf_errmsg(de)); + /* Retrieve the virtual address for this line. */ + if (dwarf_lineaddr(lines[n], &lineaddr, &de)) + errx(EXIT_FAILURE, "dwarf_lineaddr: %s", + dwarf_errmsg(de)); + } +.Ed +.Sh ERRORS +Function +.Fn dwarf_srclines +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Fa die , +.Fa lines +or +.Fa nlines +was +.Dv NULL . +.It Bq Er DW_DLE_NO_ENTRY +The compilation unit referenced by argument +.Fa die +does not have associated line number information. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_line_srcfileno 3 , +.Xr dwarf_lineaddr 3 , +.Xr dwarf_linebeginstatement 3 , +.Xr dwarf_lineblock 3 , +.Xr dwarf_lineendsequence 3 , +.Xr dwarf_lineno 3 , +.Xr dwarf_lineoff 3 , +.Xr dwarf_linesrc 3 , +.Xr dwarf_srcfiles 3 , +.Xr dwarf_srclines_dealloc 3 diff --git a/static/netbsd/man3/dwarf_start_macro_file.3 b/static/netbsd/man3/dwarf_start_macro_file.3 new file mode 100644 index 00000000..0b54285e --- /dev/null +++ b/static/netbsd/man3/dwarf_start_macro_file.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: dwarf_start_macro_file.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_start_macro_file.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 25, 2011 +.Dt DWARF_START_MACRO_FILE 3 +.Os +.Sh NAME +.Nm dwarf_start_macro_file +.Nd mark the start of a source file inclusion +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "int" +.Fo dwarf_start_macro_file +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned lineno" +.Fa "Dwarf_Unsigned fileindex" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_start_macro_file +marks the start of a new source file inclusion. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa lineno +specifies the line number of the source line where the source +file inclusion occurs. +A value of zero is used to indicate the file for the compilation unit +source itself. +.Pp +Argument +.Fa fileindex +specifies the index of the source file that is being included. +Valid source file indices are those returned by +.Xr dwarf_add_file_decl 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_start_macro_file +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_start_macro_file +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_start_macro_file +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_add_file_decl 3 , +.Xr dwarf_def_macro 3 , +.Xr dwarf_end_macro_file 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_undef_macro 3 , +.Xr dwarf_vendor_ext 3 diff --git a/static/netbsd/man3/dwarf_tag.3 b/static/netbsd/man3/dwarf_tag.3 new file mode 100644 index 00000000..5b9bde53 --- /dev/null +++ b/static/netbsd/man3/dwarf_tag.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: dwarf_tag.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2010 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_tag.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd April 14, 2010 +.Dt DWARF_TAG 3 +.Os +.Sh NAME +.Nm dwarf_tag +.Nd retrieve the tag associated with a DWARF debugging information entry +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fn dwarf_tag "Dwarf_Die die" "Dwarf_Half *tag" "Dwarf_Error *err" +.Sh DESCRIPTION +Function +.Fn dwarf_tag +retrieves the tag associated with the debugging information entry +referenced by argument +.Fa die , +and stores it into the location pointed to by argument +.Fa tag . +.Pp +If argument +.Fa err +if +.No non- Ns Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_tag +returns +.Dv DW_DLV_OK . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_tag +can fail with the following error: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Va die +or +.Va tag +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_die_abbrev_code 3 , +.Xr dwarf_diename 3 , +.Xr dwarf_dieoffset 3 diff --git a/static/netbsd/man3/dwarf_transform_to_disk_form.3 b/static/netbsd/man3/dwarf_transform_to_disk_form.3 new file mode 100644 index 00000000..3b7f4a3a --- /dev/null +++ b/static/netbsd/man3/dwarf_transform_to_disk_form.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: dwarf_transform_to_disk_form.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_transform_to_disk_form.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd August 25, 2011 +.Dt DWARF_TRANSFORM_TO_DISK_FORM 3 +.Os +.Sh NAME +.Nm dwarf_transform_to_disk_form +.Nd transform DWARF information into byte streams +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft Dwarf_Signed +.Fo dwarf_transform_to_disk_form +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_transform_to_disk_form +transforms the DWARF information gathered by the producer into +byte streams for the application to write out as ELF sections. +If the flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +is set on the producer, the function will also generate the associated +relocation arrays. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +After a call to this function, the application can call the function +.Xr dwarf_get_section_bytes 3 +to retrieve the byte streams for each ELF section. +If the flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was set on the descriptor, the application can also call the function +.Xr dwarf_get_relocation_info 3 +to retrieve the generated relocation arrays. +.Sh RETURN VALUES +On success, function +.Fn dwarf_transform_to_disk_form +returns the total number of ELF sections generated. +In case of an error, function +.Fn dwarf_transform_to_disk_form +returns +.Dv DW_DLV_NOCOUNT +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_transform_to_disk_form +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Fa dbg +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during execution. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_get_relocation_info 3 , +.Xr dwarf_get_section_bytes 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 diff --git a/static/netbsd/man3/dwarf_undef_macro.3 b/static/netbsd/man3/dwarf_undef_macro.3 new file mode 100644 index 00000000..1f803a29 --- /dev/null +++ b/static/netbsd/man3/dwarf_undef_macro.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: dwarf_undef_macro.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_undef_macro.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd November 9, 2011 +.Dt DWARF_UNDEF_MACRO 3 +.Os +.Sh NAME +.Nm dwarf_undef_macro +.Nd record the removal of a macro definition +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "int" +.Fo dwarf_undef_macro +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned lineno" +.Fa "char *name" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_undef_macro +records the removal of a macro definition in a DWARF producer +instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa lineno +specifies the line number of the source line where the macro +definition was removed. +A value of zero indicates that the macro definition was removed before +any source files were read. +.Pp +Argument +.Fa name +should point to a NUL-terminated string containing the name +of the macro. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_undef_macro +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_undef_macro +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh EXAMPLES +To record the fact that the macro named +.Dv _STDIO_H_ +was removed at line 220 of the current macro file, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Error de; + +/* ... Assume 'dbg' refers to a DWARF producer instance... */ +if (dwarf_undef_macro(dbg, 220, "_STDIO_H_", &de) != DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_def_macro failed: %s", + dwarf_errmsg(-1)); +.Ed +.Sh ERRORS +Function +.Fn dwarf_undef_macro +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either arguments +.Fa dbg +or +.Fa name +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_def_macro 3 , +.Xr dwarf_end_macro_file 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_start_macro_file 3 , +.Xr dwarf_vendor_ext 3 diff --git a/static/netbsd/man3/dwarf_vendor_ext.3 b/static/netbsd/man3/dwarf_vendor_ext.3 new file mode 100644 index 00000000..a4d39791 --- /dev/null +++ b/static/netbsd/man3/dwarf_vendor_ext.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: dwarf_vendor_ext.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_vendor_ext.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd September 25, 2011 +.Dt DWARF_VENDOR_EXT 3 +.Os +.Sh NAME +.Nm dwarf_vendor_ext +.Nd add vendor-specific macro information to a DWARF producer instance +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft "int" +.Fo dwarf_vendor_ext +.Fa "Dwarf_P_Debug dbg" +.Fa "Dwarf_Unsigned constant" +.Fa "char *string" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_vendor_ext +adds a vendor-specific macro information entry to a DWARF producer +instance. +.Pp +Argument +.Fa dbg +should reference a DWARF producer instance allocated using +.Xr dwarf_producer_init 3 +or +.Xr dwarf_producer_init_b 3 . +.Pp +Argument +.Fa constant +specifies a constant value for the macro information entry. +.Pp +Argument +.Fa string +point to a NUL-terminated string containing the string value +for the macro information entry. +.Pp +If argument +.Fa err +is not +.Dv NULL , +it will be used to store error information in case of an error. +.Pp +The meaning of the arguments +.Fa constant +and +.Fa string +are not defined by the DWARF specification, but are instead governed +by application and vendor conventions. +.Sh RETURN VALUES +On success, function +.Fn dwarf_vendor_ext +returns +.Dv DW_DLV_OK . +In case of an error, function +.Fn dwarf_vendor_ext +returns +.Dv DW_DLV_ERROR +and sets the argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_vendor_ext +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either arguments +.Fa dbg +or +.Fa string +was +.Dv NULL . +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_def_macro 3 , +.Xr dwarf_end_macro_file 3 , +.Xr dwarf_producer_init 3 , +.Xr dwarf_producer_init_b 3 , +.Xr dwarf_start_macro_file 3 , +.Xr dwarf_undef_macro 3 diff --git a/static/netbsd/man3/dwarf_whatattr.3 b/static/netbsd/man3/dwarf_whatattr.3 new file mode 100644 index 00000000..2cc2cabb --- /dev/null +++ b/static/netbsd/man3/dwarf_whatattr.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: dwarf_whatattr.3,v 1.6 2024/03/03 17:37:32 christos Exp $ +.\" +.\" Copyright (c) 2010 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id: dwarf_whatattr.3 3963 2022-03-12 16:07:32Z jkoshy +.\" +.Dd May 22, 2010 +.Dt DWARF_WHATATTR 3 +.Os +.Sh NAME +.Nm dwarf_whatattr +.Nd retrieve the attribute code for a DWARF attribute +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_whatattr +.Fa "Dwarf_Attribute attr" +.Fa "Dwarf_Half *retcode" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_whatattr +retrieves the attribute code for the DWARF attribute referenced +by argument +.Fa attr , +and writes it to the location pointed to by argument +.Fa retcode . +If argument +.Fa err +is not +.Dv NULL , +it will be used to return an error descriptor in case of an error. +.Sh RETURN VALUES +On success, function +.Fn dwarf_whatattr +returns +.Dv DW_DLV_OK . +In case of an error, it returns +.Dv DW_DLV_ERROR +and sets argument +.Fa err . +.Sh ERRORS +Function +.Fn dwarf_whatattr +can fail with the following error: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Either of argument +.Va attr +or +.Va retcode +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_attr 3 , +.Xr dwarf_hasattr 3 diff --git a/static/netbsd/man3/ec.3 b/static/netbsd/man3/ec.3 new file mode 100644 index 00000000..f5db3d25 --- /dev/null +++ b/static/netbsd/man3/ec.3 @@ -0,0 +1,333 @@ +.\" $NetBSD: ec.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ec 3" +.TH ec 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ec \- Elliptic Curve functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include +\& #include +\& +\& const EC_METHOD *EC_GFp_simple_method(void); +\& const EC_METHOD *EC_GFp_mont_method(void); +\& const EC_METHOD *EC_GFp_nist_method(void); +\& const EC_METHOD *EC_GFp_nistp224_method(void); +\& const EC_METHOD *EC_GFp_nistp256_method(void); +\& const EC_METHOD *EC_GFp_nistp521_method(void); +\& +\& const EC_METHOD *EC_GF2m_simple_method(void); +\& +\& EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); +\& void EC_GROUP_free(EC_GROUP *group); +\& void EC_GROUP_clear_free(EC_GROUP *group); +\& int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); +\& EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); +\& const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); +\& int EC_METHOD_get_field_type(const EC_METHOD *meth); +\& int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); +\& const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); +\& int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); +\& int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); +\& void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); +\& int EC_GROUP_get_curve_name(const EC_GROUP *group); +\& void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); +\& int EC_GROUP_get_asn1_flag(const EC_GROUP *group); +\& void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); +\& point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); +\& unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); +\& size_t EC_GROUP_get_seed_len(const EC_GROUP *); +\& size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); +\& int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +\& int EC_GROUP_get_degree(const EC_GROUP *group); +\& int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); +\& int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); +\& int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); +\& EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); +\& EC_GROUP *EC_GROUP_new_by_curve_name(int nid); +\& +\& size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); +\& +\& EC_POINT *EC_POINT_new(const EC_GROUP *group); +\& void EC_POINT_free(EC_POINT *point); +\& void EC_POINT_clear_free(EC_POINT *point); +\& int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); +\& EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); +\& const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); +\& int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); +\& int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); +\& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, +\& const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); +\& int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, +\& const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, int y_bit, BN_CTX *ctx); +\& int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, +\& const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, +\& const BIGNUM *x, int y_bit, BN_CTX *ctx); +\& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, +\& unsigned char *buf, size_t len, BN_CTX *ctx); +\& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, +\& const unsigned char *buf, size_t len, BN_CTX *ctx); +\& BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, +\& point_conversion_form_t form, BIGNUM *, BN_CTX *); +\& EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, +\& EC_POINT *, BN_CTX *); +\& char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, +\& point_conversion_form_t form, BN_CTX *); +\& EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, +\& EC_POINT *, BN_CTX *); +\& +\& int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); +\& int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); +\& int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); +\& int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); +\& int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); +\& int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); +\& int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); +\& int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); +\& int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); +\& int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); +\& int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); +\& int EC_GROUP_have_precompute_mult(const EC_GROUP *group); +\& +\& int EC_GROUP_get_basis_type(const EC_GROUP *); +\& int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); +\& int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, +\& unsigned int *k2, unsigned int *k3); +\& EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); +\& int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); +\& #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) +\& #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) +\& #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \e +\& (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) +\& #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \e +\& (unsigned char *)(x)) +\& int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); +\& int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); +\& +\& EC_KEY *EC_KEY_new(void); +\& int EC_KEY_get_flags(const EC_KEY *key); +\& void EC_KEY_set_flags(EC_KEY *key, int flags); +\& void EC_KEY_clear_flags(EC_KEY *key, int flags); +\& EC_KEY *EC_KEY_new_by_curve_name(int nid); +\& void EC_KEY_free(EC_KEY *key); +\& EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); +\& EC_KEY *EC_KEY_dup(const EC_KEY *src); +\& int EC_KEY_up_ref(EC_KEY *key); +\& const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); +\& int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); +\& const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); +\& int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); +\& const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); +\& int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); +\& unsigned EC_KEY_get_enc_flags(const EC_KEY *key); +\& void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); +\& point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); +\& void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); +\& void *EC_KEY_get_key_method_data(EC_KEY *key, +\& void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); +\& void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, +\& void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); +\& void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); +\& int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); +\& int EC_KEY_generate_key(EC_KEY *key); +\& int EC_KEY_check_key(const EC_KEY *key); +\& int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); +\& +\& EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); +\& int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); +\& +\& EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); +\& int i2d_ECParameters(EC_KEY *key, unsigned char **out); +\& +\& EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); +\& int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); +\& int ECParameters_print(BIO *bp, const EC_KEY *key); +\& int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); +\& int ECParameters_print_fp(FILE *fp, const EC_KEY *key); +\& int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); +\& #define ECParameters_dup(x) ASN1_dup_of(EC_KEY,i2d_ECParameters,d2i_ECParameters,x) +\& #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \e +\& EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \e +\& EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. +In general an elliptic curve is one with an equation of the form: +.PP +y^2 = x^3 + ax + b +.PP +An \fB\s-1EC_GROUP\s0\fR structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an +\&\fB\s-1EC_POINT\s0\fR structure. An \fB\s-1EC_KEY\s0\fR is used to hold a private/public key pair, where a private key is simply a \s-1BIGNUM\s0 and a +public key is a point on a curve (represented by an \fB\s-1EC_POINT\s0\fR). +.PP +The library contains a number of alternative implementations of the different functions. Each implementation is optimised +for different scenarios. No matter which implementation is being used, the interface remains the same. The library +handles calling the correct implementation when an interface function is invoked. An implementation is represented by +an \fB\s-1EC_METHOD\s0\fR structure. +.PP +The creation and destruction of \fB\s-1EC_GROUP\s0\fR objects is described in \fIEC_GROUP_new\fR\|(3). Functions for +manipulating \fB\s-1EC_GROUP\s0\fR objects are described in \fIEC_GROUP_copy\fR\|(3). +.PP +Functions for creating, destroying and manipulating \fB\s-1EC_POINT\s0\fR objects are explained in \fIEC_POINT_new\fR\|(3), +whilst functions for performing mathematical operations and tests on \fBEC_POINTs\fR are coverd in \fIEC_POINT_add\fR\|(3). +.PP +For working with private and public keys refer to \fIEC_KEY_new\fR\|(3). Implementations are covered in +\&\fIEC_GFp_simple_method\fR\|(3). +.PP +For information on encoding and decoding curve parameters to and from \s-1ASN1\s0 see \fId2i_ECPKParameters\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypto\fR\|(3), \fIEC_GROUP_new\fR\|(3), \fIEC_GROUP_copy\fR\|(3), +\&\fIEC_POINT_new\fR\|(3), \fIEC_POINT_add\fR\|(3), \fIEC_KEY_new\fR\|(3), +\&\fIEC_GFp_simple_method\fR\|(3), \fId2i_ECPKParameters\fR\|(3) diff --git a/static/netbsd/man3/ecalloc.3 b/static/netbsd/man3/ecalloc.3 new file mode 100644 index 00000000..4217b366 --- /dev/null +++ b/static/netbsd/man3/ecalloc.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: ecalloc.3,v 1.2 2017/01/28 21:31:50 christos Exp $ +.\" +.\" Copyright (c) 2001, 2003 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" Id +.\" +.Dd August 14, 2003 +.Dt ECALLOC 3 +.Os +.Sh NAME +.Nm ecalloc , +.Nm emalloc , +.Nm eread , +.Nm erealloc , +.Nm esetenv , +.Nm estrdup , +.Nm ewrite +.Nd exit-on-failure wrapper functions +.Sh LIBRARY +The roken library (libroken, -lroken) +.Sh SYNOPSIS +.Fd #include +.Ft "void *" +.Fn ecalloc "size_t number" "size_t size" +.Ft "void *" +.Fn emalloc "size_t sz" +.Ft ssize_t +.Fn eread "int fd" "void *buf" "size_t nbytes" +.Ft "void *" +.Fn erealloc "void *ptr" "size_t sz" +.Ft void +.Fn esetenv "const char *var" "const char *val" "int rewrite" +.Ft "char *" +.Fn estrdup "const char *str" +.Ft ssize_t +.Fn ewrite "int fd" "const void *buf" "size_t nbytes" +.Sh DESCRIPTION +These functions do the same as the ones without the +.Dq e +prefix, but if there is an error they will print a message with +.Xr errx 3 , +and exit. For +.Nm eread +and +.Nm ewrite +this is also true for partial data. +.Pp +This is useful in applications when there is no need for a more +advanced failure mode. +.Sh SEE ALSO +.Xr read 2 , +.Xr write 2 , +.Xr calloc 3 , +.Xr errx 3 , +.Xr malloc 3 , +.Xr realloc 3 , +.Xr setenv 3 , +.Xr strdup 3 diff --git a/static/netbsd/man3/eddsa_pk_new.3 b/static/netbsd/man3/eddsa_pk_new.3 new file mode 100644 index 00000000..428d724a --- /dev/null +++ b/static/netbsd/man3/eddsa_pk_new.3 @@ -0,0 +1,146 @@ +.\" Copyright (c) 2019-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt EDDSA_PK_NEW 3 +.Os +.Sh NAME +.Nm eddsa_pk_new , +.Nm eddsa_pk_free , +.Nm eddsa_pk_from_EVP_PKEY , +.Nm eddsa_pk_from_ptr , +.Nm eddsa_pk_to_EVP_PKEY +.Nd FIDO2 COSE EDDSA API +.Sh SYNOPSIS +.In openssl/evp.h +.In fido/eddsa.h +.Ft eddsa_pk_t * +.Fn eddsa_pk_new "void" +.Ft void +.Fn eddsa_pk_free "eddsa_pk_t **pkp" +.Ft int +.Fn eddsa_pk_from_EVP_PKEY "eddsa_pk_t *pk" "const EVP_PKEY *pkey" +.Ft int +.Fn eddsa_pk_from_ptr "eddsa_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn eddsa_pk_to_EVP_PKEY "const eddsa_pk_t *pk" +.Sh DESCRIPTION +EDDSA is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to EDDSA over Curve25519 with SHA-512. +The COSE EDDSA API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +EDDSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +EDDSA public keys are abstracted by the +.Vt eddsa_pk_t +type. +.Pp +The +.Fn eddsa_pk_new +function returns a pointer to a newly allocated, empty +.Vt eddsa_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn eddsa_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn eddsa_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn eddsa_pk_free +is a NOP. +.Pp +The +.Fn eddsa_pk_from_EVP_PKEY +function fills +.Fa pk +with the contents of +.Fa pkey . +No references to +.Fa pkey +are kept. +.Pp +The +.Fn eddsa_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn eddsa_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn eddsa_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn eddsa_pk_from_EVP_PKEY +and +.Fn eddsa_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr es256_pk_new 3 , +.Xr es384_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/static/netbsd/man3/editline.3 b/static/netbsd/man3/editline.3 new file mode 100644 index 00000000..f2e3e5a6 --- /dev/null +++ b/static/netbsd/man3/editline.3 @@ -0,0 +1,1054 @@ +.\" $NetBSD: editline.3,v 1.104 2025/12/16 02:40:48 kre Exp $ +.\" +.\" Copyright (c) 1997-2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 16, 2025 +.Dt EDITLINE 3 +.Os +.Sh NAME +.Nm editline , +.Nm el_init , +.Nm el_init_fd , +.Nm el_end , +.Nm el_reset , +.Nm el_gets , +.Nm el_wgets , +.Nm el_getc , +.Nm el_wgetc , +.Nm el_push , +.Nm el_wpush , +.Nm el_parse , +.Nm el_wparse , +.Nm el_set , +.Nm el_wset , +.Nm el_get , +.Nm el_wget , +.Nm el_source , +.Nm el_resize , +.Nm el_cursor , +.Nm el_line , +.Nm el_wline , +.Nm el_insertstr , +.Nm el_winsertstr , +.Nm el_deletestr , +.Nm el_wdeletestr , +.Nm history_init , +.Nm history_winit , +.Nm history_end , +.Nm history_wend , +.Nm history , +.Nm history_w , +.Nm tok_init , +.Nm tok_winit , +.Nm tok_end , +.Nm tok_wend , +.Nm tok_reset , +.Nm tok_wreset , +.Nm tok_line , +.Nm tok_wline , +.Nm tok_str , +.Nm tok_wstr +.Nd line editor, history and tokenization functions +.Sh LIBRARY +.Lb libedit +.Sh SYNOPSIS +.In histedit.h +.Ft EditLine * +.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" +.Ft EditLine * +.Fn el_init_fd "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" "int fdin" "int fdout" "int fderr" +.Ft void +.Fn el_end "EditLine *e" +.Ft void +.Fn el_reset "EditLine *e" +.Ft const char * +.Fn el_gets "EditLine *e" "int *count" +.Ft const wchar_t * +.Fn el_wgets "EditLine *e" "int *count" +.Ft int +.Fn el_getc "EditLine *e" "char *ch" +.Ft int +.Fn el_wgetc "EditLine *e" "wchar_t *wc" +.Ft void +.Fn el_push "EditLine *e" "const char *mbs" +.Ft void +.Fn el_wpush "EditLine *e" "const wchar_t *wcs" +.Ft int +.Fn el_parse "EditLine *e" "int argc" "const char *argv[]" +.Ft int +.Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]" +.Ft int +.Fn el_set "EditLine *e" "int op" "..." +.Ft int +.Fn el_wset "EditLine *e" "int op" "..." +.Ft int +.Fn el_get "EditLine *e" "int op" "..." +.Ft int +.Fn el_wget "EditLine *e" "int op" "..." +.Ft int +.Fn el_source "EditLine *e" "const char *file" +.Ft void +.Fn el_resize "EditLine *e" +.Ft int +.Fn el_cursor "EditLine *e" "int count" +.Ft const LineInfo * +.Fn el_line "EditLine *e" +.Ft const LineInfoW * +.Fn el_wline "EditLine *e" +.Ft int +.Fn el_insertstr "EditLine *e" "const char *str" +.Ft int +.Fn el_winsertstr "EditLine *e" "const wchar_t *str" +.Ft void +.Fn el_deletestr "EditLine *e" "int count" +.Ft void +.Fn el_wdeletestr "EditLine *e" "int count" +.Ft History * +.Fn history_init void +.Ft HistoryW * +.Fn history_winit void +.Ft void +.Fn history_end "History *h" +.Ft void +.Fn history_wend "HistoryW *h" +.Ft int +.Fn history "History *h" "HistEvent *ev" "int op" "..." +.Ft int +.Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..." +.Ft Tokenizer * +.Fn tok_init "const char *IFS" +.Ft TokenizerW * +.Fn tok_winit "const wchar_t *IFS" +.Ft void +.Fn tok_end "Tokenizer *t" +.Ft void +.Fn tok_wend "TokenizerW *t" +.Ft void +.Fn tok_reset "Tokenizer *t" +.Ft void +.Fn tok_wreset "TokenizerW *t" +.Ft int +.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" +.Ft int +.Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro" +.Ft int +.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]" +.Ft int +.Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]" +.Sh DESCRIPTION +The +.Nm +library provides generic line editing, history and tokenization functions, +similar to those found in +.Xr sh 1 . +.Pp +These functions are available in the +.Nm libedit +library (which needs the +.Nm libtermcap +library). +Programs should be linked with +.Fl ledit ltermcap . +.Pp +The +.Nm +library respects the +.Ev LC_CTYPE +locale set by the application program and never uses +.Xr setlocale 3 +to change the locale. +.Sh LINE EDITING FUNCTIONS +The line editing functions use a common data structure, +.Fa EditLine , +which is created by +.Fn el_init +or +.Fn el_init_fd +and freed by +.Fn el_end . +.Pp +The wide-character functions behave the same way as their narrow +counterparts. +.Pp +The following functions are available: +.Bl -tag -width 4n +.It Fn el_init +Initialize the line editor, and return a data structure +to be used by all other line editing functions, or +.Dv NULL +on failure. +.Fa prog +is the name of the invoking program, used when reading the +.Xr editrc 5 +file to determine which settings to use. +.Fa fin , +.Fa fout +and +.Fa ferr +are the input, output, and error streams (respectively) to use. +In this documentation, references to +.Dq the tty +are actually to this input/output stream combination. +.It Fn el_init_fd +Like +.Fn el_init +but allows specifying file descriptors for the +.Xr stdio 3 +corresponding streams, in case those were created with +.Xr funopen 3 . +.It Fn el_end +Clean up and finish with +.Fa e , +assumed to have been created with +.Fn el_init +or +.Fn el_init_fd . +.It Fn el_reset +Reset the tty and the parser. +This should be called after an error which may have upset the tty's +state. +.It Fn el_gets +Read a line from the tty. +.Fa count +is modified to contain the number of characters read. +Returns the line read if successful, or +.Dv NULL +if no characters were read or if an error occurred. +If an error occurred, +.Fa count +is set to \-1 and +.Dv errno +contains the error code that caused it. +The return value may not remain valid across calls to +.Fn el_gets +and must be copied if the data is to be retained. +.It Fn el_wgetc +Read a wide character from the tty, respecting the current locale, +or from the input queue described in +.Xr editline 7 +if that is not empty, and store it in +.Fa wc . +If an invalid or incomplete character is found, it is discarded, +.Va errno +is set to +.Er EILSEQ , +and the next character is read and stored in +.Fa wc . +Returns 1 if a valid character was read, 0 on end of file, or \-1 on +.Xr read 2 +failure. +In the latter case, +.Va errno +is set to indicate the error. +.It Fn el_getc +Read a wide character as described for +.Fn el_wgetc +and return 0 on end of file or \-1 on failure. +If the wide character can be represented as a single-byte character, +convert it with +.Xr wctob 3 , +store the result in +.Fa ch , +and return 1; otherwise, set +.Va errno +to +.Er ERANGE +and return \-1. +In the C or POSIX locale, this simply reads a byte, but for any other +locale, including UTF-8, this is rarely useful. +.It Fn el_wpush +Push the wide character string +.Fa wcs +back onto the input queue described in +.Xr editline 7 . +If the queue overflows, for example due to a recursive macro, +or if an error occurs, for example because +.Fa wcs +is +.Dv NULL +or memory allocation fails, the function beeps at the user, +but does not report the problem to the caller. +.It Fn el_push +Use the current locale to convert the multibyte string +.Fa mbs +to a wide character string, and pass the result to +.Fn el_wpush . +.It Fn el_parse +Parses the +.Fa argv +array (which is +.Fa argc +elements in size) +to execute builtin +.Nm +commands. +If the command is prefixed with +.Dq prog : +then +.Fn el_parse +will only execute the command if +.Dq prog +matches the +.Fa prog +argument supplied to +.Fn el_init . +The return value is +\-1 if the command is unknown, +0 if there was no error or +.Dq prog +didn't match, or +1 if the command returned an error. +Refer to +.Xr editrc 5 +for more information. +.It Fn el_set +Set +.Nm +parameters. +.Fa op +determines which parameter to set, and each operation has its +own parameter list. +Returns 0 on success, \-1 on failure. +.Pp +The following values for +.Fa op +are supported, along with the required argument list: +.Bl -tag -width 4n +.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" +Define prompt printing function as +.Fa f , +which is to return a string that contains the prompt. +.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" +Same as +.Dv EL_PROMPT , +but the +.Fa c +argument indicates the start/stop literal prompt character. +.Pp +If a start/stop literal character is found in the prompt, the +character itself +is not printed, but characters after it are printed directly to the +terminal without affecting the state of the current line. +A subsequent second start/stop literal character ends this behavior. +This is typically used to embed literal escape sequences that change the +color/style of the terminal in the prompt. +Note that the literal escape character cannot be the last character in the +prompt, as the escape sequence is attached to the next character in the prompt. +.Dv 0 +unsets it. +.It Dv EL_REFRESH +Re-display the current line on the next terminal line. +.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" +Define right side prompt printing function as +.Fa f , +which is to return a string that contains the prompt. +.It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" +Define the right prompt printing function but with a literal escape character. +.It Dv EL_TERMINAL , Fa "const char *type" +Define terminal type of the tty to be +.Fa type , +or to +.Ev TERM +if +.Fa type +is +.Dv NULL . +.It Dv EL_EDITOR , Fa "const char *mode" +Set editing mode to +.Fa mode , +which must be one of +.Dq emacs +or +.Dq vi . +.It Dv EL_SIGNAL , Fa "int flag" +If +.Fa flag +is non-zero, +.Nm +will install its own signal handler for the following signals when +reading command input: +.Dv SIGCONT , +.Dv SIGHUP , +.Dv SIGINT , +.Dv SIGQUIT , +.Dv SIGSTOP , +.Dv SIGTERM , +.Dv SIGTSTP , +and +.Dv SIGWINCH . +Otherwise, the current signal handlers will be used. +.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL +Perform the +.Ic bind +builtin command. +Refer to +.Xr editrc 5 +for more information. +.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL +Perform the +.Ic echotc +builtin command. +Refer to +.Xr editrc 5 +for more information. +.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL +Perform the +.Ic settc +builtin command. +Refer to +.Xr editrc 5 +for more information. +.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL +Perform the +.Ic setty +builtin command. +Refer to +.Xr editrc 5 +for more information. +.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL +Perform the +.Ic telltc +builtin command. +Refer to +.Xr editrc 5 +for more information. +.It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \ +Fa "unsigned char (*func)(EditLine *e, int ch)" +Add a user defined function, +.Fn func , +referred to as +.Fa name +which is invoked when a key which is bound to +.Fa name +is entered. +.Fa help +is a description of +.Fa name . +At invocation time, +.Fa ch +is the key which caused the invocation. +The return value of +.Fn func +should be one of: +.Bl -tag -width "CC_REDISPLAY" +.It Dv CC_NORM +Add a normal character. +.It Dv CC_NEWLINE +End of line was entered. +.It Dv CC_EOF +EOF was entered. +.It Dv CC_ARGHACK +Expecting further command input as arguments, do nothing visually. +.It Dv CC_REFRESH +Refresh display. +.It Dv CC_REFRESH_BEEP +Refresh display, and beep. +.It Dv CC_CURSOR +Cursor moved, so update and perform +.Dv CC_REFRESH . +.It Dv CC_REDISPLAY +Redisplay entire input line. +This is useful if a key binding outputs extra information. +.It Dv CC_ERROR +An error occurred. +Beep, and flush tty. +.It Dv CC_FATAL +Fatal error, reset tty to known state. +.El +.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \ +Fa "const char *ptr" +Defines which history function to use, which is usually +.Fn history . +.Fa ptr +should be the value returned by +.Fn history_init . +.It Dv EL_EDITMODE , Fa "int flag" +If +.Fa flag +is non-zero, +editing is enabled (the default). +Note that this is only an indication, and does not +affect the operation of +.Nm . +At this time, it is the caller's responsibility to +check this +(using +.Fn el_get ) +to determine if editing should be enabled or not. +.It Dv EL_UNBUFFERED , Fa "int flag" +If +.Fa flag +is zero, +unbuffered mode is disabled (the default). +In unbuffered mode, +.Fn el_gets +will return immediately after processing a single character. +.It Dv EL_SAFEREAD , Fa "int flag" +If the +.Fa flag +argument is non-zero, then +.Nm editline +attempts to recover from read errors, ignoring the first interrupted +error, and trying to reset the input file descriptor to reset non-blocking I/O. +This is disabled by default, and desirable only when +.Nm editline +is used in shell-like applications. +.It Dv EL_GETCFN , Fa "el_rfunc_t f" +Whenever reading a character, use the function +.Bd -ragged -offset indent -compact +.Ft int +.Fo f +.Fa "EditLine *e" +.Fa "wchar_t *wc" +.Fc +.Ed +which stores the character in +.Fa wc +and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding +errors. +Functions internally using it include +.Fn el_wgets , +.Fn el_wgetc , +.Fn el_gets , +and +.Fn el_getc . +Initially, a builtin function is installed, and replacing it +is discouraged because writing such a function is very error prone. +The builtin function can be restored at any time by passing the +special value +.Dv EL_BUILTIN_GETCFN +instead of a function pointer. +.It Dv EL_CLIENTDATA , Fa "void *data" +Register +.Fa data +to be associated with this EditLine structure. +It can be retrieved with the corresponding +.Fn el_get +call. +.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp" +Set the current +.Nm editline +file pointer for +.Dq input +.Fa fd += +.Dv 0 , +.Dq output +.Fa fd += +.Dv 1 , +or +.Dq error +.Fa fd += +.Dv 2 +from +.Fa fp . +.It Dv EL_GETENV , Fa "char * (*funcp)(const char *)" +Cause the function +.Nm editline +uses to obtain the value of an environment variable +to be the one provided as the parameter +.Fa funcp , +a pointer to a function taking a +.Fa "const char *" +as its parameter, and returning +.Fa "char *" . +The default is +.Xr getenv 3 . +.El +.It Fn el_get +Get +.Nm +parameters. +.Fa op +determines which parameter to retrieve into +.Fa result . +Returns 0 if successful, \-1 otherwise. +.Pp +The following values for +.Fa op +are supported, along with actual type of +.Fa result : +.Bl -tag -width 4n +.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" +Set +.Fa f +to a pointer to the function that displays the prompt. +If +.Fa c +is not +.Dv NULL , +set it to the start/stop literal prompt character. +.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" +Set +.Fa f +to a pointer to the function that displays the prompt. +If +.Fa c +is not +.Dv NULL , +set it to the start/stop literal prompt character. +.It Dv EL_EDITOR , Fa "const char **n" +Set the name of the editor in +.Fa n , +which will be one of +.Dq emacs +or +.Dq vi . +.It Dv EL_GETTC , Fa "const char *name" , Fa "void *value" +If +.Fa name +is a valid +.Xr termcap 5 +capability set +.Fa value +to the current value of that capability. +.It Dv EL_SIGNAL , Fa "int *s" +Set +.Fa s +to non-zero if +.Nm +has installed private signal handlers (see +.Fn el_get +above). +.It Dv EL_EDITMODE , Fa "int *c" +Set +.Fa c +to non-zero if editing is enabled. +.It Dv EL_GETCFN , Fa "el_rfunc_t *f" +Set +.Fa f +to a pointer to the function that reads characters, or to +.Dv EL_BUILTIN_GETCFN +if the builtin function is in use. +.It Dv EL_CLIENTDATA , Fa "void **data" +Set +.Fa data +to the previously registered client data set by an +.Fn el_set +call. +.It Dv EL_UNBUFFERED , Fa "int *c" +Set +.Fa c +to non-zero if unbuffered mode is enabled. +.It Dv EL_SAFEREAD , Fa "int *c" +Set +.Fa c +to non-zero if safe read is set. +.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp" +Set +.Fa fp +to the current +.Nm editline +file pointer for +.Dq input +.Fa fd += +.Dv 0 , +.Dq output +.Fa fd += +.Dv 1 , +or +.Dq error +.Fa fd += +.Dv 2 . +.It Dv EL_WORDCHARS , Fa "Char *wordchars" +Define the list of characters that and be part of a word, in addition +to alphanumeric characters. +This list is +.Dq *?_-.[]~= +for +.Dv emacs +mode and +.Dq _ +for +.Dv vi +mode. +Resetting the editor binding to either +.Dv emacs or +.Dv vi +also resets the wordchars to their default value. +.It Dv EL_GETENV , Fa "char * (**funcp)(const char *)" +Return, via the pointer to a pointer to a function, +.Fa funcp , +the function being used by +.Nm editline +to obtain the values of environment variables. +.El +.It Fn el_source +Initialize +.Nm +by reading the contents of +.Fa file . +.Fn el_parse +is called for each line in +.Fa file . +If +.Fa file +is +.Dv NULL , +try +.Pa $EDITRC +and if that is not set +.Pa $HOME/.editrc . +Refer to +.Xr editrc 5 +for details on the format of +.Fa file . +.Fn el_source +returns 0 on success and \-1 on error. +.It Fn el_resize +Must be called if the terminal size changes. +If +.Dv EL_SIGNAL +has been set with +.Fn el_set , +then this is done automatically. +Otherwise, it's the responsibility of the application to call +.Fn el_resize +on the appropriate occasions. +.It Fn el_cursor +Move the cursor to the right (if positive) or to the left (if negative) +.Fa count +characters. +Returns the resulting offset of the cursor from the beginning of the line. +.It Fn el_line +Return the editing information for the current line in a +.Fa LineInfo +structure, which is defined as follows: +.Bd -literal +typedef struct lineinfo { + const char *buffer; /* address of buffer */ + const char *cursor; /* address of cursor */ + const char *lastchar; /* address of last character */ +} LineInfo; +.Ed +.Pp +.Fa buffer +is not NUL terminated. +This function may be called after +.Fn el_gets +to obtain the +.Fa LineInfo +structure pertaining to line returned by that function, +and from within user defined functions added with +.Dv EL_ADDFN . +.It Fn el_insertstr +Insert +.Fa str +into the line at the cursor. +Returns \-1 if +.Fa str +is empty or won't fit, and 0 otherwise. +.It Fn el_deletestr +Delete +.Fa count +characters before the cursor. +.El +.Sh HISTORY LIST FUNCTIONS +The history functions use a common data structure, +.Fa History , +which is created by +.Fn history_init +and freed by +.Fn history_end . +.Pp +The following functions are available: +.Bl -tag -width 4n +.It Fn history_init +Initialize the history list, and return a data structure +to be used by all other history list functions, or +.Dv NULL +on failure. +.It Fn history_end +Clean up and finish with +.Fa h , +assumed to have been created with +.Fn history_init . +.It Fn history +Perform operation +.Fa op +on the history list, with optional arguments as needed by the +operation. +.Fa ev +is changed accordingly to operation. +The following values for +.Fa op +are supported, along with the required argument list: +.Bl -tag -width 4n +.It Dv H_SETSIZE , Fa "int size" +Set size of history to +.Fa size +elements. +.It Dv H_GETSIZE +Get number of events currently in history. +.It Dv H_END +Cleans up and finishes with +.Fa h , +assumed to be created with +.Fn history_init . +.It Dv H_CLEAR +Clear the history. +.It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \ +Fa "history_gfun_t next" , Fa "history_gfun_t last" , \ +Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \ +Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \ +Fa "history_efun_t enter" , Fa "history_efun_t add" +Define functions to perform various history operations. +.Fa ptr +is the argument given to a function when it's invoked. +.It Dv H_FIRST +Return the first element in the history. +.It Dv H_LAST +Return the last element in the history. +.It Dv H_PREV +Return the previous element in the history. +It is newer than the current one. +.It Dv H_NEXT +Return the next element in the history. +It is older than the current one. +.It Dv H_CURR +Return the current element in the history. +.It Dv H_SET , Fa "int position" +Set the cursor to point to the requested element. +.It Dv H_ADD , Fa "const char *str" +Append +.Fa str +to the current element of the history, or perform the +.Dv H_ENTER +operation with argument +.Fa str +if there is no current element. +.It Dv H_APPEND , Fa "const char *str" +Append +.Fa str +to the last new element of the history. +.It Dv H_ENTER , Fa "const char *str" +Add +.Fa str +as a new element to the history and, if necessary, +removing the oldest entry to keep the list to the created size. +If +.Dv H_SETUNIQUE +has been called with a non-zero argument, the element +will not be entered into the history if its contents match +the ones of the current history element. +If the element is entered +.Fn history +returns 1; if it is ignored as a duplicate returns 0. +Finally +.Fn history +returns \-1 if an error occurred. +.It Dv H_PREV_STR , Fa "const char *str" +Return the closest previous event that starts with +.Fa str . +.It Dv H_NEXT_STR , Fa "const char *str" +Return the closest next event that starts with +.Fa str . +.It Dv H_PREV_EVENT , Fa "int e" +Return the previous event numbered +.Fa e . +.It Dv H_NEXT_EVENT , Fa "int e" +Return the next event numbered +.Fa e . +.It Dv H_LOAD , Fa "const char *file" +Load the history list stored in +.Fa file . +.It Dv H_SAVE , Fa "const char *file" +Save the history list to +.Fa file . +.It Dv H_SAVE_FP , Fa "FILE *fp" +Save the history list to the opened +.Ft FILE +pointer +.Fa fp . +.It Dv H_NSAVE_FP , Fa "size_t n" , Fa "FILE *fp" +Save the last +.Ft n +history entries to the opened +.Ft FILE +pointer +.Fa fp . +.It Dv H_SETUNIQUE , Fa "int unique" +Set flag that adjacent identical event strings should not be entered +into the history. +.It Dv H_GETUNIQUE +Retrieve the current setting if adjacent identical elements should +be entered into the history. +.It Dv H_DEL , Fa "int e" +Delete the event numbered +.Fa e . +This function is only provided for +.Nm readline +compatibility. +The caller is responsible for free'ing the string in the returned +.Fa HistEvent . +.El +.Pp +.Fn history +returns >= 0 if the operation +.Fa op +succeeds. +Otherwise, \-1 is returned and +.Fa ev +is updated to contain more details about the error. +.El +.Sh TOKENIZATION FUNCTIONS +The tokenization functions use a common data structure, +.Fa Tokenizer , +which is created by +.Fn tok_init +and freed by +.Fn tok_end . +.Pp +The following functions are available: +.Bl -tag -width 4n +.It Fn tok_init +Initialize the tokenizer, and return a data structure +to be used by all other tokenizer functions. +.Fa IFS +contains the Input Field Separators, which defaults to +.Aq space , +.Aq tab , +and +.Aq newline +if +.Dv NULL . +.It Fn tok_end +Clean up and finish with +.Fa t , +assumed to have been created with +.Fn tok_init . +.It Fn tok_reset +Reset the tokenizer state. +Use after a line has been successfully tokenized +by +.Fn tok_line +or +.Fn tok_str +and before a new line is to be tokenized. +.It Fn tok_line +Tokenize +.Fa li , +If successful, modify: +.Fa argv +to contain the words, +.Fa argc +to contain the number of words, +.Fa cursorc +(if not +.Dv NULL ) +to contain the index of the word containing the cursor, +and +.Fa cursoro +(if not +.Dv NULL ) +to contain the offset within +.Fa argv[cursorc] +of the cursor. +.Pp +Returns +0 if successful, +\-1 for an internal error, +1 for an unmatched single quote, +2 for an unmatched double quote, +and +3 for a backslash quoted +.Aq newline . +A positive exit code indicates that another line should be read +and tokenization attempted again. +. +.It Fn tok_str +A simpler form of +.Fn tok_line ; +.Fa str +is a NUL terminated string to tokenize. +.El +. +.\"XXX.Sh EXAMPLES +.\"XXX: provide some examples +.Sh SEE ALSO +.Xr sh 1 , +.Xr signal 3 , +.Xr termcap 3 , +.Xr editrc 5 , +.Xr termcap 5 , +.Xr editline 7 +.Sh HISTORY +The +.Nm +library first appeared in +.Bx 4.4 . +.Dv CC_REDISPLAY +appeared in +.Nx 1.3 . +.Dv CC_REFRESH_BEEP , +.Dv EL_EDITMODE +and the readline emulation appeared in +.Nx 1.4 . +.Dv EL_RPROMPT +appeared in +.Nx 1.5 . +.Sh AUTHORS +.An -nosplit +The +.Nm +library was written by +.An Christos Zoulas . +.An Luke Mewburn +wrote this manual and implemented +.Dv CC_REDISPLAY , +.Dv CC_REFRESH_BEEP , +.Dv EL_EDITMODE , +and +.Dv EL_RPROMPT . +.An Jaromir Dolecek +implemented the readline emulation. +.An Johny Mattsson +implemented wide-character support. +.Sh BUGS +At this time, it is the responsibility of the caller to +check the result of the +.Dv EL_EDITMODE +operation of +.Fn el_get +(after an +.Fn el_source +or +.Fn el_parse ) +to determine if +.Nm +should be used for further input. +I.e., +.Dv EL_EDITMODE +is purely an indication of the result of the most recent +.Xr editrc 5 +.Ic edit +command. diff --git a/static/netbsd/man3/efun.3 b/static/netbsd/man3/efun.3 new file mode 100644 index 00000000..231e3394 --- /dev/null +++ b/static/netbsd/man3/efun.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: efun.3,v 1.14 2015/07/26 17:37:38 kamil Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 26, 2015 +.Dt EFUN 3 +.Os +.Sh NAME +.Nm esetfunc , +.Nm easprintf , +.Nm efopen , +.Nm emalloc , +.Nm ecalloc , +.Nm erealloc , +.Nm ereallocarr , +.Nm estrdup , +.Nm estrndup , +.Nm estrlcat , +.Nm estrlcpy , +.Nm estrtoi , +.Nm estrtou , +.Nm evasprintf +.Nd error-checked utility functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft void (*)(int, const char *, ...) +.Fn esetfunc "void (*)(int, const char *, ...)" +.Ft int +.Fn easprintf "char ** restrict str" "const char * restrict fmt" "..." +.Ft FILE * +.Fn efopen "const char *p" "const char *m" +.Ft void * +.Fn ecalloc "size_t n" "size_t s" +.Ft void * +.Fn emalloc "size_t n" +.Ft void * +.Fn erealloc "void *p" "size_t n" +.Ft void +.Fn ereallocarr "void *p" "size_t n" "size_t s" +.Ft char * +.Fn estrdup "const char *s" +.Ft char * +.Fn estrndup "const char *s" "size_t len" +.Ft size_t +.Fn estrlcat "char *dst" "const char *src" "size_t len" +.Ft size_t +.Fn estrlcpy "char *dst" "const char *src" "size_t len" +.Ft intmax_t +.Fn estrtoi "const char * nptr" "int base" "intmax_t lo" "intmax_t hi" +.Ft uintmax_t +.Fn estrtou "const char * nptr" "int base" "uintmax_t lo" "uintmax_t hi" +.Ft int +.Fn evasprintf "char ** restrict str" "const char * restrict fmt" "..." +.Sh DESCRIPTION +The +.Fn easprintf , +.Fn efopen , +.Fn ecalloc , +.Fn emalloc , +.Fn erealloc , +.Fn ereallocarr , +.Fn estrdup , +.Fn estrndup , +.Fn estrlcat , +.Fn estrlcpy , +.Fn estrtoi , +.Fn estrtou , +and +.Fn evasprintf +functions +operate exactly as the corresponding functions that do not start with an +.Sq e +except that in case of an error, they call +the installed error handler that can be configured with +.Fn esetfunc . +.Pp +For the string handling functions, it is an error when the destination +buffer is not large enough to hold the complete string. +For functions that allocate memory or open a file, it is an error when +they would return a null pointer. +The default error handler is +.Xr err 3 . +The function +.Fn esetfunc +returns the previous error handler function. +A +.Dv NULL +error handler will just call +.Xr exit 3 . +.Sh SEE ALSO +.Xr asprintf 3 , +.Xr calloc 3 , +.Xr err 3 , +.Xr exit 3 , +.Xr fopen 3 , +.Xr malloc 3 , +.Xr realloc 3 , +.Xr reallocarr 3 , +.Xr strdup 3 , +.Xr strlcat 3 , +.Xr strlcpy 3 , +.Xr strndup 3 , +.Xr strtoi 3 , +.Xr strtou 3 , +.Xr vasprintf 3 +.Sh HISTORY +The +.Fn estrtoi , +.Fn estrtou +and +.Fn ereallocarr +functions were added in +.Nx 8 . diff --git a/static/netbsd/man3/elf.3 b/static/netbsd/man3/elf.3 new file mode 100644 index 00000000..05b27dd4 --- /dev/null +++ b/static/netbsd/man3/elf.3 @@ -0,0 +1,630 @@ +.\" $NetBSD: elf.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006-2008,2011,2019 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf.3 3927 2021-03-07 17:22:22Z jkoshy +.\" +.Dd March 7, 2021 +.Dt ELF 3 +.Os +.Sh NAME +.Nm elf +.Nd API for manipulating ELF objects +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Sh DESCRIPTION +The +.Lb libelf +provides functions that allow an application to read and manipulate +ELF object files, and to read +.Xr ar 1 +archives. +The library allows the manipulation of ELF objects in a byte ordering +and word-size independent way, allowing an application to read and +create ELF objects for 32 and 64 bit architectures and for little- +and big-endian machines. +The library is capable of processing ELF objects that use extended +section numbering. +.Pp +This manual page serves to provide an overview of the functionality in +the ELF library. +Further information may found in the manual pages for individual +.Xr ELF 3 +functions that comprise the library. +.Ss ELF Concepts +As described in +.Xr elf 5 , +ELF files contain several data structures that are laid out in a +specific way. +ELF files begin with an +.Dq Executable Header , +and may contain an optional +.Dq Program Header Table , +and optional data in the form of ELF +.Dq sections . +A +.Dq Section Header Table +describes the content of the data in these sections. +.Pp +ELF objects have an associated +.Dq "ELF class" +which denotes the natural machine word size for the architecture +the object is associated with. +Objects for 32 bit architectures have an ELF class of +.Dv ELFCLASS32 . +Objects for 64 bit architectures have an ELF class of +.Dv ELFCLASS64 . +.Pp +ELF objects also have an associated +.Dq endianness +which denotes the endianness of the machine architecture associated +with the object. +This may be +.Dv ELFDATA2LSB +for little-endian architectures and +.Dv ELFDATA2MSB +for big-endian architectures. +.Pp +ELF objects are also associated with an API version number. +This version number determines the layout of the individual components +of an ELF file and the semantics associated with these. +.Ss Data Representation And Translation +The +.Xr ELF 3 +library distinguishes between +.Dq native +representations of ELF data structures and their +.Dq file +representations. +.Pp +An application would work with ELF data in its +.Dq native +representation, i.e., using the native byteorder and alignment mandated +by the processor the application is running on. +The +.Dq file +representation of the same data could use a different byte ordering +and follow different constraints on object alignment than these native +constraints. +.Pp +Accordingly, the +.Xr ELF 3 +library offers translation facilities +.Xr ( elf32_xlatetof 3 , +.Xr elf32_xlatetom 3 , +.Xr elf64_xlatetof 3 +and +.Xr elf64_xlatetom 3 ) +to and from these representations. +It also provides higher-level APIs +.Xr ( gelf_xlatetof 3 , +.Xr gelf_xlatetom 3 ) +that retrieve and store data from the ELF object in a class-agnostic +manner. +.Ss Library Working Version +Conceptually, there are three version numbers associated with an +application using the ELF library to manipulate ELF objects: +.Bl -bullet -compact -offset indent +.It +The ELF version that the application was compiled against. +This version determines the ABI expected by the application. +.It +The ELF version of the ELF object being manipulated by the +application through the ELF library. +.It +The ELF version (or set of versions) supported by the ELF library itself. +.El +.Pp +In order to facilitate working with ELF objects of differing versions, +the ELF library requires the application to call the +.Fn elf_version +function before invoking many of its operations, in order to inform +the library of the application's desired working version. +.Pp +In the current implementation, all three versions have to be +.Dv EV_CURRENT . +.Ss Namespace use +The ELF library uses the following prefixes: +.Bl -tag -width "ELF_F_*" +.It Dv elf_ +Used for class-independent functions. +.It Dv elf32_ +Used for functions working with 32 bit ELF objects. +.It Dv elf64_ +Used for functions working with 64 bit ELF objects. +.It Dv Elf_ +Used for class-independent data types. +.It Dv ELF_C_ +Used for command values used in a few functions. +These symbols are defined as members of the +.Vt Elf_Cmd +enumeration. +.It Dv ELF_E_ +Used for error numbers. +.It Dv ELF_F_ +Used for flags. +.It Dv ELF_K_ +These constants define the kind of file associated with an ELF +descriptor. +See +.Xr elf_kind 3 . +The symbols are defined by the +.Vt Elf_Kind +enumeration. +.It Dv ELF_T_ +These values are defined by the +.Vt Elf_Type +enumeration, and denote the types of ELF data structures +that can be present in an ELF object. +.El +.Pp +In addition, the library uses symbols with prefixes +.Dv _ELF +and +.Dv _libelf +for its internal use. +.Ss Descriptors +Applications communicate with the library using descriptors. +These are: +.Bl -tag -width ".Vt Elf_Data" +.It Vt Elf +An +.Vt Elf +descriptor represents an ELF object or an +.Xr ar 1 +archive. +It is allocated using one of the +.Fn elf_begin +or +.Fn elf_memory +functions. +An +.Vt Elf +descriptor can be used to read and write data to an ELF file. +An +.Vt Elf +descriptor can be associated with zero or more +.Vt Elf_Scn +section descriptors. +.Pp +Given an ELF descriptor, the application may retrieve the ELF +object's class-dependent +.Dq "Executable Header" +structures using the +.Fn elf32_getehdr +or +.Fn elf64_getehdr +functions. +A new Ehdr structure may be allocated using the +.Fn elf64_newehdr +or +.Fn elf64_newehdr +functions. +.Pp +The +.Dq "Program Header Table" +associated with an ELF descriptor may be allocated using the +.Fn elf32_getphdr +or +.Fn elf64_getphdr +functions. +A new program header table may be allocated or an existing table +resized using the +.Fn elf32_newphdr +or +.Fn elf64_newphdr +functions. +.Pp +The +.Vt Elf +structure is opaque and has no members visible to the +application. +.It Vt Elf_Data +An +.Vt Elf_Data +data structure describes an individual chunk of a ELF file as +represented in memory. +It has the following application-visible members: +.Bl -tag -width ".Vt unsigned int d_version" -compact +.It Vt "uint64_t d_align" +The in-file alignment of the data buffer within its containing ELF section. +This value must be non-zero and a power of two. +.It Vt "void *d_buf" +A pointer to data in memory. +.It Vt "uint64_t d_off" +The offset within the containing section where this descriptor's data +would be placed. +This field will be computed by the library unless the application +requests full control of the ELF object's layout. +.It Vt "uint64_t d_size" +The number of bytes of data in this descriptor. +.It Vt "Elf_Type d_type" +The ELF type (see below) of the data in this descriptor. +.It Vt "unsigned int d_version" +The operating version for the data in this buffer. +.El +.Pp +.Vt Elf_Data +descriptors are usually used in conjunction with +.Vt Elf_Scn +descriptors. +.It Vt Elf_Scn +.Vt Elf_Scn +descriptors represent sections in an ELF object. +These descriptors are opaque and contain no application modifiable +fields. +.Pp +The +.Vt Elf_Scn +descriptor for a specific section in an ELF object can be +retrieved using the +.Fn elf_getscn +function. +The sections contained in an ELF object can be traversed using the +.Fn elf_nextscn +function. +New sections are allocated using the +.Fn elf_newscn +function. +.Pp +The +.Vt Elf_Data +descriptors associated with a given section can be retrieved +using the +.Fn elf_getdata +function. +New data descriptors can be added to a section +descriptor using the +.Fn elf_newdata +function. +The untranslated +.Dq file +representation of data in a section can be retrieved using the +.Fn elf_rawdata +function. +.El +.Ss Supported Elf Types +The following ELF datatypes are supported by the library. +.Pp +.Bl -tag -width ".Dv ELF_T_SYMINFO" -compact +.It Dv ELF_T_ADDR +Machine addresses. +.It Dv ELF_T_BYTE +Byte data. +The library will not attempt to translate byte data. +.It Dv ELF_T_CAP +Software and hardware capability records. +.It Dv ELF_T_DYN +Records used in a section of type +.Dv SHT_DYNAMIC . +.It Dv ELF_T_EHDR +ELF executable header. +.It Dv ELF_T_GNUHASH +GNU-style hash tables. +.It Dv ELF_T_HALF +16-bit unsigned words. +.It Dv ELF_T_LWORD +64 bit unsigned words. +.It Dv ELF_T_MOVE +ELF Move records. +.\".It Dv ELF_T_MOVEP +.\" As yet unsupported. +.It Dv ELF_T_NOTE +ELF Note structures. +.It Dv ELF_T_OFF +File offsets. +.It Dv ELF_T_PHDR +ELF program header table entries. +.It Dv ELF_T_REL +ELF relocation entries. +.It Dv ELF_T_RELA +ELF relocation entries with addends. +.It Dv ELF_T_SHDR +ELF section header entries. +.It Dv ELF_T_SWORD +Signed 32-bit words. +.It Dv ELF_T_SXWORD +Signed 64-bit words. +.It Dv ELF_T_SYMINFO +ELF symbol information. +.It Dv ELF_T_SYM +ELF symbol table entries. +.It Dv ELF_T_VDEF +Symbol version definition records. +.It Dv ELF_T_VNEED +Symbol version requirement records. +.It Dv ELF_T_WORD +Unsigned 32-bit words. +.It Dv ELF_T_XWORD +Unsigned 64-bit words. +.El +.Pp +The symbol +.Dv ELF_T_NUM +denotes the number of Elf types known to the library. +.Pp +The following table shows the mapping between ELF section types +defined in +.Xr elf 5 +and the types supported by the library. +.Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO" +.It Em Section Type Ta Em "Library Type" Ta Em Description +.It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo +.Sq .dynamic +section entries. +.Xc +.It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking. +.It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers. +.It Dv SHT_GNU_HASH Ta Dv ELF_T_GNUHASH Ta GNU hash sections. +.It Dv SHT_GNU_LIBLIST Ta Dv ELF_T_WORD Ta List of libraries to be pre-linked. +.It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions. +.It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements. +.It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols. +.It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker. +.It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes. +.It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers. +.It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo +Empty sections. +See +.Xr elf 5 . +.Xc +.It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records. +.It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers. +.It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code. +.It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records. +.It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends. +.It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables. +.It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables. +.It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering. +.It Dv SHT_SUNW_dof Ta Dv ELF_T_BYTE Ta Xo +Used by +.Xr dtrace 1 . +.Xc +.It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records. +.It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags. +.It Dv SHT_SUNW_verdef Ta Dv ELF_T_VDEF Ta Xo +Same as +.Dv SHT_GNU_verdef . +.Xc +.It Dv SHT_SUNW_verneed Ta Dv ELF_T_VNEED Ta Xo +Same as +.Dv SHT_GNU_verneed . +.Xc +.It Dv SHT_SUNW_versym Ta Dv ELF_T_HALF Ta Xo +Same as +.Dv SHT_GNU_versym . +.Xc +.El +.Pp +Section types in the range +.Dv [ SHT_LOOS , +.Dv SHT_HIUSER ] +are otherwise considered to be of type +.Dv ELF_T_BYTE . +.Ss Functional Grouping +This section contains a brief overview of the available functionality +in the ELF library. +Each function listed here is described further in its own manual page. +.Bl -tag -width indent +.It "Archive Access" +.Bl -tag -compact -width indent +.It Fn elf_getarsym +Retrieve the archive symbol table. +.It Fn elf_getarhdr +Retrieve the archive header for an object. +.It Fn elf_getbase +Retrieve the offset of a member inside an archive. +.It Fn elf_next +Iterate through an +.Xr ar 1 +archive. +.It Fn elf_rand +Random access inside an +.Xr ar 1 +archive. +.El +.It "Data Structures" +.Bl -tag -compact -width indent +.It Fn elf_getdata +Retrieve translated data for an ELF section. +.It Fn elf_getscn +Retrieve the section descriptor for a named section. +.It Fn elf_ndxscn +Retrieve the index for a section. +.It Fn elf_newdata +Add a new +.Vt Elf_Data +descriptor to an ELF section. +.It Fn elf_newscn +Add a new section descriptor to an ELF descriptor. +.It Fn elf_nextscn +Iterate through the sections in an ELF object. +.It Fn elf_rawdata +Retrieve untranslated data for an ELF section. +.It Fn elf_rawfile +Return a pointer to the untranslated file contents for an ELF object. +.It Fn elf32_getehdr , Fn elf64_getehdr +Retrieve the Executable Header in an ELF object. +.It Fn elf32_getphdr , Fn elf64_getphdr +Retrieve the Program Header Table in an ELF object. +.It Fn elf32_getshdr , Fn elf64_getshdr +Retrieve the ELF section header associated with an +.Vt Elf_Scn +descriptor. +.It Fn elf32_newehdr , Fn elf64_newehdr +Allocate an Executable Header in an ELF object. +.It Fn elf32_newphdr , Fn elf64_newphdr +Allocate or resize the Program Header Table in an ELF object. +.El +.It "Data Translation" +.Bl -tag -compact -width indent +.It Fn elf32_xlatetof , Fn elf64_xlatetof +Translate an ELF data structure from its native representation to its +file representation. +.It Fn elf32_xlatetom , Fn elf64_xlatetom +Translate an ELF data structure from its file representation to a +native representation. +.El +.It "Error Reporting" +.Bl -tag -compact -width indent +.It Fn elf_errno +Retrieve the current error. +.It Fn elf_errmsg +Retrieve a human readable description of the current error. +.El +.It "Initialization" +.Bl -tag -compact -width indent +.It Fn elf_begin +Opens an +.Xr ar 1 +archive or ELF object given a file descriptor. +.It Fn elf_end +Close an ELF descriptor and release all its resources. +.It Fn elf_memory +Opens an +.Xr ar 1 +archive or ELF object present in a memory arena. +.It Fn elf_version +Sets the operating version. +.El +.It "IO Control" +.Bl -tag -width ".Fn elf_setshstrndx" -compact +.It Fn elf_cntl +Manage the association between and ELF descriptor and its underlying file. +.It Fn elf_flagdata +Mark an +.Vt Elf_Data +descriptor as dirty. +.It Fn elf_flagehdr +Mark the ELF Executable Header in an ELF descriptor as dirty. +.It Fn elf_flagphdr +Mark the ELF Program Header Table in an ELF descriptor as dirty. +.It Fn elf_flagscn +Mark an +.Vt Elf_Scn +descriptor as dirty. +.It Fn elf_flagshdr +Mark an ELF Section Header as dirty. +.It Fn elf_setshstrndx +Set the index of the section name string table for the ELF object. +.It Fn elf_update +Recompute ELF object layout and optionally write the modified object +back to the underlying file. +.El +.It "Queries" +.Bl -tag -width ".Fn elf_getshstrndx" -compact +.It Fn elf32_checksum , Fn elf64_checkum +Compute checksum of an ELF object. +.It Fn elf_getident +Retrieve the identification bytes for an ELF object. +.It Fn elf_getphdrnum +Retrieve the number of program headers in an ELF object. +.It Fn elf_getshdrnum +Retrieve the number of sections in an ELF object. +.It Fn elf_getshdrstrndx +Retrieve the section index of the section name string table in +an ELF object. +.It Fn elf_hash +Compute the ELF hash value of a string. +.It Fn elf_kind +Query the kind of object associated with an ELF descriptor. +.It Fn elf32_fsize , Fn elf64_fsize +Return the size of the file representation of an ELF type. +.El +.El +.Ss Controlling ELF Object Layout +In the usual mode of operation, library will compute section +offsets and alignments based on the contents of an ELF descriptor's +sections without need for further intervention by the +application. +.Pp +However, if the application wishes to take complete charge of the +layout of the ELF file, it may set the +.Dv ELF_F_LAYOUT +flag on an ELF descriptor using +.Xr elf_flagelf 3 , +following which the library will use the data offsets and alignments +specified by the application when laying out the file. +Application control of file layout is described further in the +.Xr elf_update 3 +manual page. +.Pp +Gaps in between sections will be filled with the fill character +set by function +.Fn elf_fill . +.Ss Error Handling +In case an error is encountered, these library functions set an +internal error number and signal the presence of the error by +returning a special return value. +The application can check the +current error number by calling +.Xr elf_errno 3 . +A human readable description of the recorded error is available by +calling +.Xr elf_errmsg 3 . +.Ss Memory Management Rules +The library keeps track of all +.Vt Elf_Scn +and +.Vt Elf_Data +descriptors associated with an ELF descriptor and recovers them +when the descriptor is closed using +.Xr elf_end 3 . +Thus the application must not call +.Xr free 3 +on data structures allocated by the ELF library. +.Pp +Conversely the library will not +free data that it has not allocated. +As an example, an application may call +.Xr elf_newdata 3 +to allocate a new +.Vt Elf_Data +descriptor and can set the +.Va d_off +member of the descriptor to point to a region of memory allocated +using +.Xr malloc 3 . +It is the applications responsibility to free this arena, though the +library will reclaim the space used by the +.Vt Elf_Data +descriptor itself. +.Sh SEE ALSO +.Xr gelf 3 , +.Xr ar 5 , +.Xr elf 5 +.Sh HISTORY +The original +.Nm +API was developed for +.At V . +The current implementation of the API appeared in +.Fx 7.0 +and +.Nx 6.0 . +.Sh AUTHORS +The ELF library was written by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . diff --git a/static/netbsd/man3/elf_begin.3 b/static/netbsd/man3/elf_begin.3 new file mode 100644 index 00000000..14cbc630 --- /dev/null +++ b/static/netbsd/man3/elf_begin.3 @@ -0,0 +1,329 @@ +.\" $NetBSD: elf_begin.3,v 1.7 2025/12/25 11:10:48 jkoshy Exp $ +.\" +.\" Copyright (c) 2006,2008-2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_begin.3 4321 2025-12-22 20:48:10Z jkoshy +.\" +.Dd December 22, 2025 +.Dt ELF_BEGIN 3 +.Os +.Sh NAME +.Nm elf_begin +.Nd open an ELF file or ar(1) archive +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf *" +.Fn elf_begin "int fd" "Elf_Cmd cmd" "Elf *elf" +.Sh DESCRIPTION +Function +.Fn elf_begin +is used to open ELF files and +.Xr ar 1 +archives for further processing by other APIs in the +.Xr elf 3 +library. +It is also used to access individual ELF members of an +.Xr ar 1 +archive in combination with the +.Xr elf_next 3 +and +.Xr elf_rand 3 +APIs. +.Pp +Argument +.Fa fd +is an open file descriptor returned from an +.Xr open 2 +system call. +Function +.Fn elf_begin +uses argument +.Fa fd +for reading or writing depending on the value of argument +.Fa cmd . +Argument +.Fa elf +is primarily used for iterating through archives. +.Pp +The argument +.Fa cmd +can have the following values: +.Bl -tag -width "ELF_C_WRITE" +.It ELF_C_NULL +Causes +.Fn elf_begin +to return +.Dv NULL . +Arguments +.Fa fd +and +.Fa elf +are ignored, and no additional error is signalled. +.It ELF_C_READ +This value is to be when the application wishes to examine (but not +modify) the contents of the file specified by the arguments +.Fa fd +and +.Fa elf . +It can be used for both +.Xr ar 1 +archives and for ELF objects. +.Pp +If argument +.Fa elf +is +.Dv NULL , +the library will allocate a new ELF descriptor for the file +being processed. +The argument +.Fa fd +should have been opened for reading. +.Pp +If argument +.Fa elf +is not +.Dv NULL , +and references a regular ELF file previously opened with +.Fn elf_begin , +then the activation count for the descriptor referenced by argument +.Fa elf +is incremented. +The value in argument +.Fa fd +should match that used to open the descriptor argument +.Fa elf . +.Pp +If argument +.Fa elf +is not +.Dv NULL , +and references a descriptor for an +.Xr ar 1 +archive opened earlier with +.Fn elf_begin , +a descriptor for an element in the archive is returned as +described in the section +.Sx "Processing ar(1) archives" +below. +The value for argument +.Fa fd +should match that used to open the archive earlier. +.Pp +If argument +.Fa elf +is not +.Dv NULL , +and references an +.Xr ar 1 +archive opened earlier with +.Fn elf_memory , +then the value of the argument +.Fa fd +is ignored. +.It Dv ELF_C_RDWR +This command is used to prepare an ELF file for reading and writing. +This command is not supported for +.Xr ar 1 +archives. +.Pp +Argument +.Fa fd +should have been opened for reading and writing. +If argument +.Fa elf +is +.Dv NULL , +the library will allocate a new ELF descriptor for +the file being processed. +If the argument +.Fa elf +is non-null, it should point to a descriptor previously +allocated with +.Fn elf_begin +with the same values for arguments +.Fa fd +and +.Fa cmd ; +in this case the library will increment the activation count for descriptor +.Fa elf +and return the same descriptor. +.Pp +Changes to the in-memory image of the ELF file may be written back to +disk using the +.Xr elf_update 3 +function. +.It Dv ELF_C_WRITE +This command is used when the application wishes to create a new ELF +file. +Argument +.Fa fd +should have been opened for writing. +Argument +.Fa elf +is ignored, and the previous contents of file referenced by argument +.Fa fd +are overwritten. +.El +.Ss Processing ar(1) archives +An +.Xr ar 1 +archive may be opened in read mode (with argument +.Fa cmd +set to +.Dv ELF_C_READ ) +using +.Fn elf_begin +or +.Fn elf_memory . +The returned ELF descriptor can be passed into to +subsequent calls to +.Fn elf_begin +to access individual members of the archive. +.Pp +Random access within an opened archive is possible using +the +.Xr elf_next 3 +and +.Xr elf_rand 3 +functions. +.Pp +The symbol table of the archive may be retrieved +using +.Xr elf_getarsym 3 . +.Sh RETURN VALUES +The function returns a pointer to a ELF descriptor if successful, or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +To iterate through the members of an +.Xr ar 1 +archive, use: +.Bd -literal -offset indent +Elf_Cmd c; +Elf *ar_e, *elf_e; +\&... +c = ELF_C_READ; +if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) { + \&... handle error in opening the archive ... +} +while ((elf_e = elf_begin(fd, c, ar_e)) != 0) { + \&... process member referenced by elf_e here ... + c = elf_next(elf_e); + elf_end(elf_e); +} +.Ed +.Pp +To create a new ELF file, use: +.Bd -literal -offset indent +int fd; +Elf *e; +\&... +if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) { + \&... handle the error from open(2) ... +} +if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) { + \&... handle the error from elf_begin() ... +} +\&... create the ELF image using other elf(3) APIs ... +elf_update(e, ELF_C_WRITE); +elf_end(e); +.Ed +.Sh ERRORS +Function +.Fn elf_begin +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARCHIVE +The archive denoted by argument +.Fa elf +could not be parsed. +.It Bq Er ELF_E_ARGUMENT +The value in argument +.Fa cmd +was unrecognized. +.It Bq Er ELF_E_ARGUMENT +A non-null value for argument +.Fa elf +was specified when +.Fa cmd +was set to +.Dv ELF_C_RDWR . +.It Bq Er ELF_E_ARGUMENT +The value of argument +.Fa fd +differs from the one the ELF descriptor +.Fa elf +was created with. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa cmd +differs from the value specified when ELF descriptor +.Fa elf +was created. +.It Bq Er ELF_E_ARGUMENT +An +.Xr ar 1 +archive was opened with +.Fa cmd +set to +.Dv ELF_C_RDWR . +.It Bq Er ELF_E_ARGUMENT +The file referenced by argument +.Fa fd +was empty. +.It Bq Er ELF_E_ARGUMENT +The underlying file for argument +.Fa fd +was of an unsupported type. +.It Bq Er ELF_E_ARGUMENT +An invalid file descriptor value was used for argument +.Fa fd . +.It Bq Er ELF_E_IO +An IO error occurred when attempting to use the file +descriptor value in argument +.Fa fd . +.It Bq Er ELF_E_RESOURCE +An out of memory condition was encountered. +.It Bq Er ELF_E_SEQUENCE +Function +.Fn elf_begin +was called before a working version was established with +.Xr elf_version 3 . +.It Bq Er ELF_E_VERSION +The ELF object referenced by argument +.Fa fd +was of an unsupported ELF version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_end 3 , +.Xr elf_errno 3 , +.Xr elf_memory 3 , +.Xr elf_next 3 , +.Xr elf_open 3 , +.Xr elf_rand 3 , +.Xr elf_update 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_cntl.3 b/static/netbsd/man3/elf_cntl.3 new file mode 100644 index 00000000..bc9a23f3 --- /dev/null +++ b/static/netbsd/man3/elf_cntl.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: elf_cntl.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_cntl.3 3953 2022-03-12 09:57:05Z jkoshy +.\" +.Dd August 9, 2006 +.Dt ELF_CNTL 3 +.Os +.Sh NAME +.Nm elf_cntl +.Nd control an elf file descriptor +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_cntl "Elf *elf" "Elf_Cmd cmd" +.Sh DESCRIPTION +Function +.Fn elf_cntl +controls the ELF library's subsequent use of the file descriptor +used to create ELF descriptor +.Fa elf . +.Pp +Argument +.Fa cmd +informs the library of the action to be taken: +.Bl -tag -width "ELF_C_FDDONE" +.It Dv ELF_C_FDDONE +This value instructs the ELF library not to perform any further +I/O on the file descriptor associated with argument +.Fa elf . +For ELF descriptors opened with mode +.Dv ELF_C_WRITE +or +.Dv ELF_C_RDWR +subsequent +.Fn elf_update +operations on the descriptor will fail. +.It Dv ELF_C_FDREAD +This value instructs the ELF library to read in all necessary +data associated with ELF descriptor +.Fa elf +into memory so that the underlying file descriptor can be +safely closed with command +.Dv ELF_C_FDDONE . +.El +.Pp +Argument +.Fa elf +must be an ELF descriptor associated with a file system object +(e.g., an +.Xr ar 1 +archive, an ELF file, or other data file). +.Sh IMPLEMENTATION NOTES +Due to use of +.Xr mmap 2 +internally, this function is a no-op for ELF objects opened in +.Dv ELF_C_READ +mode. +.Sh RETURN VALUES +Function +.Fn elf_cntl +returns 0 on success, or -1 if an error was detected. +.Sh ERRORS +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARCHIVE +Argument +.Fa elf +is a descriptor for an archive member. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa cmd +was not recognized. +.It Bq Er ELF_E_MODE +An +.Dv ELF_C_FDREAD +operation was requested on an ELF descriptor opened +for writing. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_end 3 , +.Xr elf_next 3 , +.Xr elf_update 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_end.3 b/static/netbsd/man3/elf_end.3 new file mode 100644 index 00000000..f1110f43 --- /dev/null +++ b/static/netbsd/man3/elf_end.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: elf_end.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_end.3 3954 2022-03-12 12:07:16Z jkoshy +.\" +.Dd June 29, 2006 +.Dt ELF_END 3 +.Os +.Sh NAME +.Nm elf_end +.Nd release an ELF descriptor +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_end "Elf *elf" +.Sh DESCRIPTION +Function +.Fn elf_end +is used to release the resources associated with an ELF descriptor +pointed to by argument +.Fa elf . +This descriptor must have been allocated by a previous call to +.Xr elf_begin 3 +or +.Xr elf_memory 3 . +For programming convenience, a +.Dv NULL +value is permitted for argument +.Fa elf . +.Pp +A call to +.Fn elf_end +decrements the activation count for descriptor +.Fa elf +by one. +The resources associated with the descriptor are only released +with its activation count goes to zero. +.Pp +Once function +.Fn elf_end +returns zero, the ELF descriptor +.Fa elf +will no longer be valid and should not be used further. +.Sh RETURN VALUES +Function +.Fn elf_end +returns the current value of the ELF descriptor +.Fa elf Ap s +activation count, or zero if argument +.Fa elf +was +.Dv NULL . +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_memory 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_errmsg.3 b/static/netbsd/man3/elf_errmsg.3 new file mode 100644 index 00000000..908c6865 --- /dev/null +++ b/static/netbsd/man3/elf_errmsg.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: elf_errmsg.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_errmsg.3 3954 2022-03-12 12:07:16Z jkoshy +.\" +.Dd June 11, 2006 +.Dt ELF_ERRMSG 3 +.Os +.Sh NAME +.Nm elf_errmsg , +.Nm elf_errno +.Nd ELF library error message handling +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_errno "void" +.Ft "const char *" +.Fn elf_errmsg "int error" +.Sh DESCRIPTION +When an error occurs during an ELF library API call, the library +encodes the error using an error number and stores the error number +internally for retrieval by the application at a later point of time. +Error numbers may contain an OS supplied error code in addition to +an ELF API specific error code. +An error number value of zero indicates no error. +.Pp +Function +.Fn elf_errno +is used to retrieve the last error recorded by the ELF library. +Invoking this function has the side-effect of resetting the +ELF library's recorded error number to zero. +.Pp +The function +.Fn elf_errmsg +returns a null-terminated string with a human readable +description of the error specified in argument +.Fa error . +A zero value for argument +.Fa error +retrieves the most recent error encountered by the ELF +library. +An argument value of -1 behaves identically, except that +it guarantees a +.No non- Ns Dv NULL +return from +.Fn elf_errmsg . +.Sh RETURN VALUES +Function +.Fn elf_errno +returns a non-zero value encoding the last error encountered +by the ELF library, or zero if no error was encountered. +.Pp +Function +.Fn elf_errmsg +returns a pointer to library local storage for non-zero values +of argument +.Fa error . +With a zero argument, the function will return a +.Dv NULL +pointer if no +error had been encountered by the library, or will return a pointer to +library local storage containing an appropriate message otherwise. +.Sh EXAMPLES +Clearing the ELF library's recorded error number can be accomplished +by invoking +.Fn elf_errno +and discarding its return value. +.Bd -literal -offset indent +/* clear error */ +(void) elf_errno(); +.Ed +.Pp +Retrieving a human-readable description of the current error number +can be done with the following snippet: +.Bd -literal -offset indent +int err; +const char *errmsg; +\&... +err = elf_errno(); +if (err != 0) + errmsg = elf_errmsg(err); +.Ed +.Sh SEE ALSO +.Xr elf 3 , +.Xr gelf 3 +.Sh BUGS +Function +.Fn elf_errmsg +is not localized. diff --git a/static/netbsd/man3/elf_fill.3 b/static/netbsd/man3/elf_fill.3 new file mode 100644 index 00000000..73abf56f --- /dev/null +++ b/static/netbsd/man3/elf_fill.3 @@ -0,0 +1,54 @@ +.\" $NetBSD: elf_fill.3,v 1.5 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_fill.3 3639 2018-10-14 14:07:02Z jkoshy +.\" +.Dd June 11, 2006 +.Dt ELF_FILL 3 +.Os +.Sh NAME +.Nm elf_fill +.Nd set fill byte for inter-section padding +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft void +.Fn elf_fill "int fill" +.Sh DESCRIPTION +Function +.Fn elf_fill +allows an application to specify a fill value for the padding inserted +between two sections of an ELF file to meet section alignment +constraints. +By default the ELF library uses zero bytes for padding. +.Pp +The ELF library will only pad bytes if the +.Dv ELF_F_LAYOUT +flag is not set for the ELF file. +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_flagelf 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_flagdata.3 b/static/netbsd/man3/elf_flagdata.3 new file mode 100644 index 00000000..dad1aba5 --- /dev/null +++ b/static/netbsd/man3/elf_flagdata.3 @@ -0,0 +1,230 @@ +.\" $NetBSD: elf_flagdata.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006-2008,2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_flagdata.3 3954 2022-03-12 12:07:16Z jkoshy +.\" +.Dd June 12, 2019 +.Dt ELF_FLAGDATA 3 +.Os +.Sh NAME +.Nm elf_flagarhdr , +.Nm elf_flagdata , +.Nm elf_flagehdr , +.Nm elf_flagelf , +.Nm elf_flagphdr , +.Nm elf_flagscn , +.Nm elf_flagshdr +.Nd manipulate flags associated with ELF data structures +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "unsigned int" +.Fn elf_flagarhdr "Elf_Arhdr *arhdr" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagdata "Elf_Data *data" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagehdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagelf "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagphdr "Elf *elf" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagscn "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" +.Ft "unsigned int" +.Fn elf_flagshdr "Elf_Scn *scn" "Elf_Cmd cmd" "unsigned int flags" +.Sh DESCRIPTION +These functions are used to query, set or reset flags on data +structures associated with an ELF file. +.Pp +Arguments +.Fa arhdr , +.Fa data , +.Fa elf +and +.Fa scn +denote the data structures whose flags need to be changed. +These values should have been returned by prior calls to +functions in the +.Xr elf 3 +API set: +.Bl -bullet -compact +.It +Argument +.Fa arhdr +should have been returned by a prior call to +.Xr elf_getarhdr 3 . +.It +Argument +.Fa data +should have been returned by a prior call to one of +.Xr elf_newdata 3 , +.Xr elf_getdata 3 +or +.Xr elf_rawdata 3 . +.It +Argument +.Fa elf +should have been allocated by a prior call to one of +.Xr elf_begin 3 +or +.Xr elf_memory 3 . +.It +Argument +.Fa scn +should have been returned by a prior call to one of +.Xr elf_getscn 3 , +.Xr elf_newscn 3 +or +.Xr elf_nextscn 3 . +.El +These values are allowed to be +.Dv NULL +to simplify error handling in application code. +.Pp +Argument +.Fa cmd +may have the following values: +.Bl -tag -width ELF_C_SET +.It Dv ELF_C_CLR +The argument +.Fa flags +specifies the flags to be cleared. +.It Dv ELF_C_SET +The argument +.Fa flags +specifies the flags to be set. +.El +.Pp +The argument +.Fa flags +is allowed to have the following flags set: +.Bl -tag -width ELF_F_ARCHIVE_SYSV +.It Dv ELF_F_ARCHIVE +This flag is only valid with the +.Fn elf_flagelf +API. +It informs the library that the application desires to create an +.Xr ar 1 +archive. +Argument +.Fa elf +should have been opened for writing using the +.Dv ELF_C_WRITE +command to function +.Fn elf_begin . +.It Dv ELF_F_ARCHIVE_SYSV +This flag is used in conjunction with the +.Dv ELF_F_ARCHIVE +flag to indicate that library should create archives that conform +to System V layout rules. +The default is to create BSD style archives. +.It Dv ELF_F_DIRTY +Mark the associated data structure as needing to be written back +to the underlying file. +A subsequent call to +.Xr elf_update 3 +will resynchronize the library's internal data structures. +.It Dv ELF_F_LAYOUT +This flag is only valid with the +.Fn elf_flagelf +API. +It informs the library that the application will take +responsibility for the layout of the file and that the library is +not to insert any padding in between sections. +.El +.Pp +Marking a given data structure as +.Dq dirty +affects all of its contained elements. +Thus marking an ELF descriptor +.Fa elf +with +.Fn elf_flagelf "elf" "ELF_C_SET" "ELF_F_DIRTY" +means that the entire contents of the descriptor are +.Dq dirty . +.Pp +Using a value of zero for argument +.Fa flags +will return the current set of flags for the data structure being +queried. +.Sh RETURN VALUES +These functions return the updated flags if successful, or zero if +an error is detected. +.Sh COMPATIBILITY +The +.Fn elf_flagarhdr +function and the +.Dv ELF_F_ARCHIVE +and +.Dv ELF_F_ARCHIVE_SYSV +flags are an extension to the +.Xr elf 3 +API. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +An unsupported value was used for the +.Fa cmd +argument. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa flags +had unsupported flags set. +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_MODE +The +.Dv ELF_F_ARCHIVE +flag was used with an ELF descriptor that had not been opened for writing. +.It Bq Er ELF_E_SEQUENCE +Function +.Fn elf_flagehdr +was called without an executable header being allocated. +.It Bq Er ELF_E_SEQUENCE +Function +.Fn elf_flagphdr +was called without a program header being allocated. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_newehdr 3 , +.Xr elf32_newphdr 3 , +.Xr elf64_newehdr 3 , +.Xr elf64_newphdr 3 , +.Xr elf_newdata 3 , +.Xr elf_update 3 , +.Xr gelf 3 , +.Xr gelf_newehdr 3 , +.Xr gelf_newphdr 3 , +.Xr gelf_update_dyn 3 , +.Xr gelf_update_move 3 , +.Xr gelf_update_rel 3 , +.Xr gelf_update_rela 3 , +.Xr gelf_update_sym 3 , +.Xr gelf_update_syminfo 3 diff --git a/static/netbsd/man3/elf_getarhdr.3 b/static/netbsd/man3/elf_getarhdr.3 new file mode 100644 index 00000000..f5ccce63 --- /dev/null +++ b/static/netbsd/man3/elf_getarhdr.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: elf_getarhdr.3,v 1.8 2025/12/25 11:10:48 jkoshy Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getarhdr.3 4254 2025-10-20 17:44:18Z jkoshy +.\" +.Dd October 20, 2025 +.Dt ELF_GETARHDR 3 +.Os +.Sh NAME +.Nm elf_getarhdr +.Nd retrieve ar(1) header for an archive member +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf_Arhdr *" +.Fn elf_getarhdr "Elf *elf" +.Sh DESCRIPTION +The +.Fn elf_getarhdr +function returns a pointer to an archive member header for +a descriptor +.Fa elf . +This descriptor must have been returned by a prior call to +.Xr elf_begin 3 , +and must be a descriptor for a member inside an +.Xr ar 1 +archive. +.Pp +Structure +.Vt Elf_Arhdr +includes the following members: +.Bl -tag -width indent +.It Vt "char *" Va ar_name +A pointer to a null terminated string containing the translated +name of the archive member. +.It Vt "char *" Va ar_rawname +A pointer to a null terminated string containing the untranslated +name for the archive member, including all +.Xr ar 1 +formatting characters and trailing white space. +.It Vt time_t Va ar_date +The timestamp associated with the member. +.It Vt uid_t Va ar_uid +The uid of the creator of the member. +.It Vt gid_t Va ar_gid +The gid of the creator of the member. +.It Vt mode_t Va ar_mode +The file mode of the member. +.It Vt size_t Va ar_size +The size of the member in bytes. +.El +.Sh RETURN VALUES +This function returns a valid pointer to an +.Vt Elf_Arhdr +structure if successful, or +.Dv NULL +if an error is encountered. +.Sh ERRORS +Function +.Fn elf_getarhdr +may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARCHIVE +The archive member header for argument +.Fa elf +was invalid. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for a member of an +.Xr ar 1 +archive. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_getarsym 3 , +.Xr elf_memory 3 diff --git a/static/netbsd/man3/elf_getarsym.3 b/static/netbsd/man3/elf_getarsym.3 new file mode 100644 index 00000000..677f6dbb --- /dev/null +++ b/static/netbsd/man3/elf_getarsym.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: elf_getarsym.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getarsym.3 3955 2022-03-12 12:24:36Z jkoshy +.\" +.Dd August 15, 2006 +.Dt ELF_GETARSYM 3 +.Os +.Sh NAME +.Nm elf_getarsym +.Nd retrieve the symbol table of an archive +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf_Arsym *" +.Fn elf_getarsym "Elf *elf" "size_t *ptr" +.Sh DESCRIPTION +The function +.Fn elf_getarsym +retrieves the symbol table for an +.Xr ar 1 +archive, if one is available. +.Pp +Argument +.Fa elf +should be a descriptor for an +.Xr ar 1 +archive opened using +.Fn elf_begin +or +.Fn elf_memory . +.Pp +If the archive +.Fa elf +contains a symbol table with n entries, this function returns a +pointer to an array of n+1 +.Vt Elf_Arsym +structures. +An +.Vt Elf_Arsym +structure has the following elements: +.Bl -tag -width indent -compact +.It Vt "char *" Va as_name +This structure member is a pointer to a null-terminated symbol name. +.It Vt "off_t" Va as_off +This structure member contains the byte offset from the beginning of the archive to +the header for the archive member. +This value is suitable for use with +.Xr elf_rand 3 . +.It Vt "unsigned long" Va as_hash +This structure member contains a portable hash value for the symbol +name, as computed by +.Xr elf_hash 3 . +.El +.Pp +The last entry of the returned array will have a +.Dv NULL +value for member +.Va as_name , +a zero value for member +.Va as_off +and an illegal value of ~0UL for +.Va as_hash . +.Pp +If argument +.Fa ptr +is non-null, the +.Fn elf_getarsym +function will store the number of table entries returned (including the +sentinel entry at the end) into the location it points to. +.Sh RETURN VALUES +Function +.Fn elf_getarsym +returns a pointer to an array of +.Vt Elf_Arsym +structures if successful, or a +.Dv NULL +pointer if an error was encountered. +.Pp +If argument +.Fa ptr +is non-null and there was no error, the library will store the +number of archive symbol entries returned into the location it +points to. +If argument +.Fa ptr +is non-null and an error was encountered, the library will +set the location pointed to by it to zero. +.Sh ERRORS +Function +.Fn elf_getarsym +may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an +.Xr ar 1 +archive. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_getarhdr 3 , +.Xr elf_hash 3 , +.Xr elf_memory 3 , +.Xr elf_next 3 , +.Xr elf_rand 3 diff --git a/static/netbsd/man3/elf_getbase.3 b/static/netbsd/man3/elf_getbase.3 new file mode 100644 index 00000000..a6c67e78 --- /dev/null +++ b/static/netbsd/man3/elf_getbase.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: elf_getbase.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008,2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getbase.3 3955 2022-03-12 12:24:36Z jkoshy +.\" +.Dd June 6, 2010 +.Dt ELF_GETBASE 3 +.Os +.Sh NAME +.Nm elf_getbase +.Nd get the base offset for an object file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft off_t +.Fn elf_getbase "Elf *elf" +.Sh DESCRIPTION +Function +.Fn elf_getbase +returns the file offset to the first byte of the object referenced by ELF +descriptor +.Fa elf . +.Pp +For descriptors referencing members of archives, the returned offset is +the file offset of the member in its containing archive. +For descriptors to regular objects, the returned offset is (vacuously) +zero. +.Sh RETURN VALUES +Function +.Fn elf_getbase +returns a valid file offset if successful, or +.Pq Vt off_t +.Li -1 +in case of an error. +.Sh ERRORS +Function +.Fn elf_getbase +may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getarhdr 3 , +.Xr elf_getident 3 , +.Xr elf_rawfile 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_getdata.3 b/static/netbsd/man3/elf_getdata.3 new file mode 100644 index 00000000..14aa1328 --- /dev/null +++ b/static/netbsd/man3/elf_getdata.3 @@ -0,0 +1,254 @@ +.\" $NetBSD: elf_getdata.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008,2010-2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getdata.3 3955 2022-03-12 12:24:36Z jkoshy +.\" +.Dd April 22, 2019 +.Dt ELF_GETDATA 3 +.Os +.Sh NAME +.Nm elf_getdata , +.Nm elf_newdata , +.Nm elf_rawdata +.Nd iterate through or allocate section data +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf_Data *" +.Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data" +.Ft "Elf_Data *" +.Fn elf_newdata "Elf_Scn *scn" +.Ft "Elf_Data *" +.Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data" +.Sh DESCRIPTION +These functions are used to access and manipulate data descriptors +associated with section descriptors. +Data descriptors used by the ELF library are described in +.Xr elf 3 . +.Pp +Function +.Fn elf_getdata +will return the next data descriptor associated with section descriptor +.Fa scn . +The returned data descriptor will be setup to contain translated data. +Argument +.Fa data +may be +.Dv NULL , +in which case the function returns the first data descriptor +associated with section +.Fa scn . +If argument +.Fa data +is not +.Dv NULL , +it must be a pointer to a data descriptor associated with +section descriptor +.Fa scn , +and function +.Fn elf_getdata +will return a pointer to the next data descriptor for the section, +or +.Dv NULL +when the end of the section's descriptor list is reached. +.Pp +Function +.Fn elf_newdata +will allocate a new data descriptor and append it to the list of data +descriptors associated with section descriptor +.Fa scn . +The new data descriptor will be initialized as follows: +.Bl -tag -width "d_version" -compact -offset indent +.It Va d_align +Set to 1. +.It Va d_buf +Initialized to +.Dv NULL . +.It Va d_off +Set to (off_t) -1. +This field is under application control if the +.Dv ELF_F_LAYOUT +flag was set on the ELF descriptor. +.It Va d_size +Set to zero. +.It Va d_type +Initialized to +.Dv ELF_T_BYTE . +.It Va d_version +Set to the current working version of the library, as set by +.Xr elf_version 3 . +.El +The application must set these values as appropriate before +calling +.Xr elf_update 3 . +Section +.Fa scn +must be associated with an ELF file opened for writing. +If the application has not requested full control of layout by +setting the +.Dv ELF_F_LAYOUT +flag on descriptor +.Fa elf , +then the data referenced by the returned descriptor will be positioned +after the existing content of the section, honoring the file alignment +specified in member +.Va d_align . +On successful completion of a call to +.Fn elf_newdata , +the ELF library will mark the section +.Fa scn +as +.Dq dirty . +.Pp +Function +.Fn elf_rawdata +is used to step through the data descriptors associated with +section +.Fa scn . +In contrast to function +.Fn elf_getdata , +this function returns untranslated data. +If argument +.Fa data +is +.Dv NULL , +the first data descriptor associated with section +.Fa scn +is returned. +If argument +.Fa data +is not +.Dv NULL , +is must be a data descriptor associated with +section +.Fa scn , +and function +.Fn elf_rawdata +will return the next data descriptor in the list, or +.Dv NULL +if no further descriptors are present. +Function +.Fn elf_rawdata +always returns +.Vt Elf_Data +structures of type +.Dv ELF_T_BYTE . +.Ss Special handling of zero-sized and SHT_NOBITS sections +For sections of type +.Dv SHT_NOBITS , +and for zero-sized sections, +the functions +.Fn elf_getdata +and +.Fn elf_rawdata +return a pointer to a valid +.Vt Elf_Data +structure that has its +.Va d_buf +member set to +.Dv NULL +and its +.Va d_size +member set to the size of the section. +.Pp +If an application wishes to create a section of type +.Dv SHT_NOBITS , +it should add a data buffer to the section using function +.Fn elf_newdata . +It should then set the +.Va d_buf +and +.Va d_size +members of the returned +.Vt Elf_Data +structure to +.Dv NULL +and the desired size of the section respectively. +.Sh RETURN VALUES +These functions return a valid pointer to a data descriptor if successful, or +.Dv NULL +if an error occurs. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Either of the arguments +.Fa scn +or +.Fa data +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +The data descriptor referenced by argument +.Fa data +is not associated with section descriptor +.Fa scn . +.It Bq Er ELF_E_ARGUMENT +The section denoted by argument +.Fa scn +had no data associated with it. +.It Bq Er ELF_E_DATA +Retrieval of data from the underlying object failed. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.It Bq Er ELF_E_SECTION +Section +.Fa scn +had type +.Dv SHT_NULL . +.It Bq Er ELF_E_SECTION +The type of the section +.Fa scn +was not recognized by the library. +.It Bq Er ELF_E_SECTION +The size of the section +.Fa scn +is not a multiple of the file size for its section type. +.It Bq Er ELF_E_SECTION +The file offset for section +.Fa scn +is incorrect. +.It Bq Er ELF_E_UNIMPL +The section type associated with section +.Fa scn +is not supported. +.It Bq Er ELF_E_VERSION +Section +.Fa scn +was associated with an ELF object with an unsupported +version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_flagdata 3 , +.Xr elf_flagscn 3 , +.Xr elf_getscn 3 , +.Xr elf_getshdr 3 , +.Xr elf_newscn 3 , +.Xr elf_rawfile 3 , +.Xr elf_update 3 , +.Xr elf_version 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_getident.3 b/static/netbsd/man3/elf_getident.3 new file mode 100644 index 00000000..0814f248 --- /dev/null +++ b/static/netbsd/man3/elf_getident.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: elf_getident.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getident.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd July 3, 2006 +.Dt ELF_GETIDENT 3 +.Os +.Sh NAME +.Nm elf_getident +.Nd return the initial bytes of a file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft char * +.Fn elf_getident "Elf *elf" "size_t *sz" +.Sh DESCRIPTION +Function +.Fn elf_getident +returns a pointer to the initial bytes of the file for descriptor +.Fa elf . +.Pp +If argument +.Fa sz +is non-null, the size of the identification area returned is written +to the location pointed to by +.Fa sz . +This location is set to zero on errors. +.Sh RETURN VALUES +Function +.Fn elf_getident +will return a +.No non- Ns Dv NULL +pointer to the initial bytes of the file if successful, or +.Dv NULL +if an error condition is detected. +.Sh ERRORS +Function +.Fn elf_getident +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_SEQUENCE +ELF descriptor +.Fa elf +was opened for writing and function +.Fn elf_getident +was called before a call to +.Xr elf_update 3 . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getarhdr 3 , +.Xr elf_getbase 3 , +.Xr elf_getflags 3 , +.Xr elf_kind 3 , +.Xr elf_rawfile 3 , +.Xr elf_update 3 , +.Xr gelf 3 , +.Xr gelf_getclass 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getphdrnum.3 b/static/netbsd/man3/elf_getphdrnum.3 new file mode 100644 index 00000000..7d8464f6 --- /dev/null +++ b/static/netbsd/man3/elf_getphdrnum.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: elf_getphdrnum.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getphdrnum.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd July 25, 2018 +.Dt ELF_GETPHDRNUM 3 +.Os +.Sh NAME +.Nm elf_getphdrnum +.Nd return the number of program headers in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getphdrnum "Elf *elf" "size_t *phnum" +.Sh DESCRIPTION +Function +.Fn elf_getphdrnum +retrieves the number of ELF program headers associated with descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa phnum . +.Pp +This routine allows applications to uniformly process both normal ELF +objects and ELF objects that use extended numbering. +.Sh RETURN VALUES +Function +.Fn elf_getphdrnum +returns a zero value if successful, or -1 in case of an error. +.Sh ERRORS +Function +.Fn elf_getphdrnum +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable Header. +.It Bq Er ELF_E_HEADER +The ELF Executable Header associated with argument +.Fa elf +was corrupt. +.It Bq Er ELF_E_SECTION +The section header at index +.Dv SHN_UNDEF +was corrupt. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getshdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getphnum.3 b/static/netbsd/man3/elf_getphnum.3 new file mode 100644 index 00000000..96e5dd6a --- /dev/null +++ b/static/netbsd/man3/elf_getphnum.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: elf_getphnum.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getphnum.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd August 5, 2009 +.Dt ELF_GETPHNUM 3 +.Os +.Sh NAME +.Nm elf_getphnum +.Nd return the number of program headers in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getphnum "Elf *elf" "size_t *phnum" +.Sh DESCRIPTION +This function is deprecated. +Please use function +.Xr elf_getphdrnum 3 +instead. +.Pp +Function +.Fn elf_getphnum +retrieves the number of ELF program headers associated with descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa phnum . +.Pp +This routine allows applications to uniformly process both normal ELF +objects and ELF objects that use extended numbering. +.Sh RETURN VALUES +Function +.Fn elf_getphnum +returns a non-zero value if successful, or zero in case of an +error. +.Sh ERRORS +Function +.Fn elf_getphnum +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable Header. +.It Bq Er ELF_E_HEADER +The ELF Executable Header associated with argument +.Fa elf +was corrupt. +.It Bq Er ELF_E_SECTION +The section header at index +.Dv SHN_UNDEF +was corrupt. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getscn.3 b/static/netbsd/man3/elf_getscn.3 new file mode 100644 index 00000000..201336b6 --- /dev/null +++ b/static/netbsd/man3/elf_getscn.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: elf_getscn.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006-2008,2018 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getscn.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd September 24, 2018 +.Dt ELF_GETSCN 3 +.Os +.Sh NAME +.Nm elf_getscn , +.Nm elf_ndxscn , +.Nm elf_newscn , +.Nm elf_nextscn +.Nd get/allocate section information for an ELF object +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf_Scn *" +.Fn elf_getscn "Elf *elf" "size_t index" +.Ft size_t +.Fn elf_ndxscn "Elf_Scn *scn" +.Ft "Elf_Scn *" +.Fn elf_newscn "Elf *elf" +.Ft "Elf_Scn *" +.Fn elf_nextscn "Elf *elf" "Elf_Scn *scn" +.Sh DESCRIPTION +These functions are used to iterate through the sections associated +with an ELF descriptor. +.Pp +Function +.Fn elf_getscn +will return a section descriptor for the section at index +.Fa index +in the object denoted by ELF descriptor +.Fa elf . +An error will be signalled if the specified section does not +exist. +.Pp +Function +.Fn elf_ndxscn +returns the section table index associated with section descriptor +.Fa scn . +.Pp +Function +.Fn elf_newscn +creates a new section and appends it to the list of sections +associated with descriptor +.Fa elf . +The library will automatically increment the +.Va e_shnum +field of the ELF header associated with descriptor +.Fa elf , +and will set the +.Dv ELF_F_DIRTY +flag on the returned section descriptor. +For ELF descriptors opened for writing, the ELF library will +automatically create an empty section at index zero +.Dv ( SHN_UNDEF ) +on the first call to +.Fn elf_newscn . +.Pp +Function +.Fn elf_nextscn +takes a section descriptor +.Fa scn +and returns a pointer to the section descriptor at the next higher +index. +As a consequence, +.Fn elf_nextscn +will never return a pointer to the empty section at index zero +.Dv ( SHN_UNDEF ) . +Argument +.Fa scn +is allowed to be +.Dv NULL , +in which case this function will return a pointer to the section +descriptor at index 1. +If no further sections are present, function +.Fn elf_nextscn +will return a +.Dv NULL +pointer. +.Sh RETURN VALUES +Functions +.Fn elf_getscn , +.Fn elf_newscn +and +.Fn elf_nextscn +return a valid pointer to a section descriptor if successful, or +.Dv NULL +if an error occurs. +.Pp +Function +.Fn elf_ndxscn +returns a valid section table index if successful, or +.Dv SHN_UNDEF +if an error occurs. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa elf +or +.Fa scn +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa index +exceeded the current number of sections in the ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Section descriptor +.Fa scn +was not associated with ELF descriptor +.Fa elf . +.It Bq Er ELF_E_CLASS +Descriptor +.Fa elf +was of an unknown ELF class. +.It Bq Er ELF_E_SECTION +Argument +.Fa elf +specified extended section numbering in the ELF header with the section header at +index +.Dv SHN_UNDEF +not being of type +.Dv SHT_NULL . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_flagdata 3 , +.Xr elf_flagscn 3 , +.Xr elf_getdata 3 , +.Xr elf_getshdr 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_getshdrnum.3 b/static/netbsd/man3/elf_getshdrnum.3 new file mode 100644 index 00000000..3c1b7715 --- /dev/null +++ b/static/netbsd/man3/elf_getshdrnum.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: elf_getshdrnum.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getshdrnum.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd August 4, 2009 +.Dt ELF_GETSHDRNUM 3 +.Os +.Sh NAME +.Nm elf_getshdrnum +.Nd return the number of sections in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshdrnum "Elf *elf" "size_t *shnum" +.Sh DESCRIPTION +Function +.Fn elf_getshdrnum +retrieves the number of ELF sections associated with descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa shnum . +.Pp +This routine allows applications to uniformly process both normal ELF +objects, and ELF objects that use extended section numbering. +.Sh RETURN VALUES +Function +.Fn elf_getshdrnum +returns zero value if successful, or -1 in case of an error. +.Sh ERRORS +Function +.Fn elf_getshdrnum +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable header. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getshdrstrndx.3 b/static/netbsd/man3/elf_getshdrstrndx.3 new file mode 100644 index 00000000..2fa5ca1f --- /dev/null +++ b/static/netbsd/man3/elf_getshdrstrndx.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: elf_getshdrstrndx.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getshdrstrndx.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd August 5, 2009 +.Dt ELF_GETSHDRSTRNDX 3 +.Os +.Sh NAME +.Nm elf_getshdrstrndx +.Nd retrieve the index of the section name string table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshdrstrndx "Elf *elf" "size_t *ndxptr" +.Sh DESCRIPTION +Function +.Fn elf_getshdrstrndx +retrieves the section index of the string table containing section +names from descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa ndxptr . +.Pp +This function allow applications to process both normal ELF +objects and ELF objects that use extended section numbering uniformly. +.Sh RETURN VALUES +These functions return zero if successful, or -1 in case of an error. +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable header. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +contained a value in the reserved range of section indices. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getshnum.3 b/static/netbsd/man3/elf_getshnum.3 new file mode 100644 index 00000000..2e08e8b7 --- /dev/null +++ b/static/netbsd/man3/elf_getshnum.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: elf_getshnum.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getshnum.3 3956 2022-03-12 12:39:30Z jkoshy +.\" +.Dd August 5, 2009 +.Dt ELF_GETSHNUM 3 +.Os +.Sh NAME +.Nm elf_getshnum +.Nd return the number of sections in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshnum "Elf *elf" "size_t *shnum" +.Sh DESCRIPTION +This function is deprecated. +Please use +.Xr elf_getshdrnum 3 +instead. +.Pp +Function +.Fn elf_getshnum +retrieves the number of ELF sections associated with descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa shnum . +.Pp +This routine allows applications to uniformly process both normal ELF +objects, and ELF objects that use extended section numbering. +.Sh RETURN VALUES +Function +.Fn elf_getshnum +returns a non-zero value if successful, or zero in case of an +error. +.Sh ERRORS +Function +.Fn elf_getshnum +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable header. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getshstrndx.3 b/static/netbsd/man3/elf_getshstrndx.3 new file mode 100644 index 00000000..25548628 --- /dev/null +++ b/static/netbsd/man3/elf_getshstrndx.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: elf_getshstrndx.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_getshstrndx.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd July 25, 2018 +.Dt ELF_GETSHSTRNDX 3 +.Os +.Sh NAME +.Nm elf_getshstrndx , +.Nm elf_setshstrndx +.Nd retrieve/update the index of the section name string table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshstrndx "Elf *elf" "size_t *ndxptr" +.Ft int +.Fn elf_setshstrndx "Elf *elf" "size_t ndx" +.Sh DESCRIPTION +Function +.Fn elf_getshstrndx +is deprecated. +Please use +.Xr elf_getshdrstrndx 3 +instead. +.Pp +Function +.Fn elf_getshstrndx +retrieves the section index of the string table containing section +names from descriptor +.Fa elf +and stores it into the location pointed to by argument +.Fa ndxptr . +.Pp +Function +.Fn elf_setshstrndx +sets the index of the section name string table to argument +.Fa ndx . +.Pp +These routines allow applications to process both normal ELF +objects and ELF objects that use extended section numbering uniformly. +.Sh RETURN VALUES +These functions return a non-zero value if successful, or zero in case +of an error. +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was passed in for argument +.Fa elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +lacks an ELF Executable header. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +contained a value in the reserved range of section indices. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/static/netbsd/man3/elf_getversion.3 b/static/netbsd/man3/elf_getversion.3 new file mode 100644 index 00000000..46d1afbc --- /dev/null +++ b/static/netbsd/man3/elf_getversion.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: elf_getversion.3,v 1.2 2025/12/25 11:10:48 jkoshy Exp $ +.\" +.\" Copyright (c) 2021 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Id: elf_getversion.3 4319 2025-12-22 17:36:41Z jkoshy +.\" +.Dd December 22, 2025 +.Dt ELF_GETVERSION 3 +.Os +.Sh NAME +.Nm elf_getversion +.Nd retrieve the operating version for an ELF object +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft unsigned int +.Fn elf_getversion "Elf *elf" +.Sh DESCRIPTION +The function +.Fn elf_getversion +returns the operating version for the ELF descriptor pointed to by +argument +.Fa elf . +.Sh RETURN VALUES +The function returns the operating version for the ELF object if +successful, or +.Dv EV_NONE +if an error occurred. +.Sh COMPATIBILITY +This function is an extension to the +.Xr ELF 3 +API set. +.Sh ERRORS +This function can fail with the following errors: +.Bl -tag -width "[ELF_E_ARGUMENT]" +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +The underlying object referenced by the descriptor +.Fa elf +was not an ELF object. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_errno 3 , +.Xr elf_version 3 diff --git a/static/netbsd/man3/elf_hash.3 b/static/netbsd/man3/elf_hash.3 new file mode 100644 index 00000000..0035fe54 --- /dev/null +++ b/static/netbsd/man3/elf_hash.3 @@ -0,0 +1,59 @@ +.\" $NetBSD: elf_hash.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_hash.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd August 15, 2006 +.Dt ELF_HASH 3 +.Os +.Sh NAME +.Nm elf_hash +.Nd compute a hash value for a string +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "unsigned long" +.Fn elf_hash "const char *name" +.Sh DESCRIPTION +Function +.Fn elf_hash +computes a portable hash value for the null terminated string +pointed to by argument +.Fa name . +.Pp +The hash value returned is will be identical across +machines of different architectures. +This allows hash tables to be built on one machine and +correctly used on another of a different architecture. +The hash value returned is also guaranteed +.Em not +to be the bit pattern of all ones (~0UL). +.Sh IMPLEMENTATION NOTES +The library internally uses unsigned 32 bit arithmetic to compute +the hash value. +.Sh SEE ALSO +.Xr elf 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_kind.3 b/static/netbsd/man3/elf_kind.3 new file mode 100644 index 00000000..e188a4f5 --- /dev/null +++ b/static/netbsd/man3/elf_kind.3 @@ -0,0 +1,76 @@ +.\" $NetBSD: elf_kind.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_kind.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd June 1, 2006 +.Dt ELF_KIND 3 +.Os +.Sh NAME +.Nm elf_kind +.Nd determine ELF file type +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft Elf_Kind +.Fn elf_kind "Elf *elf" +.Sh DESCRIPTION +The +.Fn elf_kind +function identifies the kind of file associated with its argument +.Fa elf . +The argument +.Fa elf +is allowed to be +.Dv NULL . +.Sh RETURN VALUES +The +.Fn elf_kind +function returns one of the following values: +.Bl -tag -width indent +.It Dv ELF_K_AR +The file associated with argument +.Fa elf +is an archive. +.It Dv ELF_K_ELF +The file associated with argument +.Fa elf +is an ELF file. +.It Dv ELF_K_NONE +The argument +.Fa elf +was +.Dv NULL , +or the ELF library could not determine the type of the file +associated with argument +.Fa elf , +or an error occurred when processing. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_getident 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_memory.3 b/static/netbsd/man3/elf_memory.3 new file mode 100644 index 00000000..e8f63fc9 --- /dev/null +++ b/static/netbsd/man3/elf_memory.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: elf_memory.3,v 1.7 2025/12/25 11:10:48 jkoshy Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_memory.3 4322 2025-12-22 20:48:40Z jkoshy +.\" +.Dd June 28, 2006 +.Dt ELF_MEMORY 3 +.Os +.Sh NAME +.Nm elf_memory +.Nd process an ELF or ar(1) archive mapped into memory +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf *" +.Fn elf_memory "char *image" "size_t size" +.Sh DESCRIPTION +Function +.Fn elf_memory +is used to process an ELF file or +.Xr ar 1 +archive whose image is present in memory. +.Pp +Argument +.Fa image +points to the start of the memory image of the file or archive. +Argument +.Fa size +contains the size in bytes of the memory image. +.Pp +The ELF descriptor is created for reading (i.e., analogous to the +use of +.Xr elf_begin 3 +with a command argument value of +.Dv ELF_C_READ Ns ). +.Sh RETURN VALUES +Function +.Fn elf_memory +returns a pointer to a new ELF descriptor if successful, or +.Dv NULL +if an +error occurred. +.Pp +The return value may be queried for the file type using +.Xr elf_kind 3 . +.Sh EXAMPLES +To read parse an elf file, use: +.Bd -literal -offset indent +int fd; +void *p; +struct stat sb; +Elf *e; +\&... +if ((fd = open("./elf-file", O_RDONLY)) < 0 || + fstat(fd, &sb) < 0 || + (p = mmap(NULL, sb.st_size, PROT_READ, MAP_PRIVATE, fd, (off_t) 0)) == + MAP_FAILED) { + ... handle system error ... +} + +if ((e = elf_memory(p, sb.st_size)) == NULL) { + ... handle elf(3) error ... +} +\&... use ELF descriptor "e" here ... +.Ed +.Sh ERRORS +Function +.Fn elf_memory +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A +.Dv NULL +value was used for argument +.Fa image +or the value of argument +.Fa sz +was zero. +.It Bq Er ELF_E_HEADER +The header of the ELF object contained an unsupported value in its +.Va e_ident[EI_CLASS] +field. +.It Bq Er ELF_E_HEADER +The header of the ELF object contained an unsupported value in its +.Va e_ident[EI_DATA] +field. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.It Bq Er ELF_E_SEQUENCE +Function +.Fn elf_memory +was called before a working version was set using +.Xr elf_version 3 . +.It Bq Er ELF_E_VERSION +The ELF object referenced by argument +.Fa image +was of an unsupported ELF version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_end 3 , +.Xr elf_errno 3 , +.Xr elf_kind 3 , +.Xr elf_openmemory 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_next.3 b/static/netbsd/man3/elf_next.3 new file mode 100644 index 00000000..2890e901 --- /dev/null +++ b/static/netbsd/man3/elf_next.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: elf_next.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_next.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd February 27, 2019 +.Dt ELF_NEXT 3 +.Os +.Sh NAME +.Nm elf_next +.Nd provide sequential access to the next archive member +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft Elf_Cmd +.Fn elf_next "Elf *elf" +.Sh DESCRIPTION +The +.Fn elf_next +function causes the ELF archive descriptor corresponding to argument +.Fa elf +to be adjusted to provide access to the next member in +the archive on a subsequent call to +.Fn elf_begin . +.Pp +The return value of +.Fn elf_next +is suitable for use in a loop invoking +.Fn elf_begin . +.Sh RETURN VALUES +If successful, function +.Fn elf_next +returns the value +.Dv ELF_C_READ . +Otherwise, if argument +.Fa elf +was not associated with an archive, or if it was +.Dv NULL , +or if any other error occurred, the value +.Dv ELF_C_NULL +is returned. +.Sh EXAMPLES +To process all the members of an archive use: +.Bd -literal -offset indent +Elf_Cmd cmd; +Elf *archive, *e; +\&... +cmd = ELF_C_READ; +archive = elf_begin(fd, cmd, NULL); +while ((e = elf_begin(fd, cmd, archive)) != (Elf *) 0) +{ + ... process `e' here ... + + cmd = elf_next(e); + elf_end(e); +} +elf_end(archive); +.Ed +.Sh ERRORS +Function +.Fn elf_next +may fail with the following error: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not associated with a containing +.Xr ar 1 +archive. +.It Bq Er ELF_E_ARGUMENT +An error was encountered while parsing the archive containing argument +.Fa elf . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_end 3 , +.Xr elf_rand 3 diff --git a/static/netbsd/man3/elf_open.3 b/static/netbsd/man3/elf_open.3 new file mode 100644 index 00000000..2ecad5c0 --- /dev/null +++ b/static/netbsd/man3/elf_open.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: elf_open.3,v 1.8 2025/12/25 11:10:48 jkoshy Exp $ +.\" +.\" Copyright (c) 2012 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_open.3 4320 2025-12-22 20:47:09Z jkoshy +.\" +.Dd December 22, 2025 +.Dt ELF_OPEN 3 +.Os +.Sh NAME +.Nm elf_open , +.Nm elf_openmemory +.Nd open ELF objects and ar(1) archives +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf *" +.Fn elf_open "int fd" +.Ft "Elf *" +.Fn elf_openmemory "char *image" "size_t sz" +.Sh DESCRIPTION +The function +.Fn elf_open +returns an Elf descriptor opened with mode +.Dv ELF_C_READ +for the ELF object or +.Xr ar 1 +archive referenced by the file descriptor in argument +.Fa fd . +.Pp +The function +.Fn elf_openmemory +returns an ELF descriptor opened with mode +.Dv ELF_C_READ +for the ELF object or +.Xr ar 1 +archive contained in the memory area pointed to by the argument +.Fa image . +The argument +.Fa sz +specifies the size of the memory area in bytes. +.Pp +The behavior of these functions differs from their counterparts +.Xr elf_begin 3 +and +.Xr elf_memory 3 +in that these functions will successfully open malformed ELF objects +and +.Xr ar 1 +archives, returning an Elf descriptor of type +.Dv ELF_K_NONE . +.Sh RETURN VALUES +The function returns a pointer to a ELF descriptor if successful, or +.Dv NULL +if an error occurred. +.Sh COMPATIBILITY +These functions are non-standard extensions to the +.Xr ELF 3 +API set. +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa fd +was of an unsupported file type. +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa sz +was zero, or the argument +.Fa image +was +.Dv NULL . +.It Bq Er ELF_E_IO +The file descriptor in argument +.Fa fd +was invalid. +.It Bq Er ELF_E_IO +The file descriptor in argument +.Fa fd +could not be read. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was encountered. +.It Bq Er ELF_E_SEQUENCE +Functions +.Fn elf_open +or +.Fn elf_openmemory +was called before a working version was established with +.Xr elf_version 3 . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_errno 3 , +.Xr elf_memory 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_rand.3 b/static/netbsd/man3/elf_rand.3 new file mode 100644 index 00000000..118aa01a --- /dev/null +++ b/static/netbsd/man3/elf_rand.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: elf_rand.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_rand.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd June 17, 2006 +.Dt ELF_RAND 3 +.Os +.Sh NAME +.Nm elf_rand +.Nd provide sequential access to the next archive member +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft off_t +.Fn elf_rand "Elf *archive" "off_t offset" +.Sh DESCRIPTION +The +.Fn elf_rand +function causes the ELF descriptor +.Fa archive +to be adjusted so that the next call to +.Xr elf_begin 3 +will provide access to the archive member at byte offset +.Fa offset +in the archive. +Argument +.Fa offset +is the byte offset from the start of the archive to the beginning of +the archive header for the desired member. +.Pp +Archive member offsets may be retrieved using the +.Xr elf_getarsym 3 +function. +.Sh RETURN VALUES +Function +.Fn elf_rand +returns +.Fa offset +if successful or zero in case of an error. +.Sh EXAMPLES +To process all the members of an archive use: +.Bd -literal -offset indent +off_t off; +Elf *archive, *e; +\&... +cmd = ELF_C_READ; +archive = elf_begin(fd, cmd, NULL); +while ((e = elf_begin(fd, cmd, archive)) != (Elf *) 0) +{ + ... process `e' here ... + elf_end(e); + + off = ...new value...; + if (elf_rand(archive, off) != off) { + ... process error ... + } +} +elf_end(archive); +.Ed +.Pp +To rewind an archive, use: +.Bd -literal -offset indent +Elf *archive; +\&... +if (elf_rand(archive, SARMAG) != SARMAG) { + ... error ... +} +.Ed +.Sh ERRORS +Function +.Fn elf_rand +may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa archive +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa archive +was not a descriptor for an +.Xr ar 1 +archive. +.It Bq Er ELF_E_ARCHIVE +Argument +.Fa offset +did not correspond to the start of an archive member header. +.El +.Sh SEE ALSO +.Xr ar 1 , +.Xr elf 3 , +.Xr elf_begin 3 , +.Xr elf_end 3 , +.Xr elf_getarsym 3 , +.Xr elf_next 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/elf_rawfile.3 b/static/netbsd/man3/elf_rawfile.3 new file mode 100644 index 00000000..44eb708e --- /dev/null +++ b/static/netbsd/man3/elf_rawfile.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: elf_rawfile.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_rawfile.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd July 3, 2006 +.Dt ELF_RAWFILE 3 +.Os +.Sh NAME +.Nm elf_rawfile +.Nd return uninterpreted contents of an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft char * +.Fn elf_rawfile "Elf *elf" "size_t *sz" +.Sh DESCRIPTION +Function +.Fn elf_rawfile +returns the uninterpreted contents of the file referenced by ELF descriptor +.Fa elf . +.Pp +If argument +.Fa sz +is non-null, the function stores the file's size in bytes +in the location to which it points. +A value of zero is written to this location if an error is +encountered. +.Sh RETURN VALUES +Function +.Fn elf_rawfile +returns a valid pointer if successful or +.Dv NULL +if an error occurs. +.Sh ERRORS +Function +.Fn elf_rawfile +may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_SEQUENCE +Argument +.Fa elf +was opened for writing and function +.Fn elf_rawfile +was invoked before +.Xr elf_update 3 . +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getident 3 , +.Xr elf_kind 3 , +.Xr elf_update 3 diff --git a/static/netbsd/man3/elf_strptr.3 b/static/netbsd/man3/elf_strptr.3 new file mode 100644 index 00000000..c0afea5b --- /dev/null +++ b/static/netbsd/man3/elf_strptr.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: elf_strptr.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_strptr.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd December 16, 2006 +.Dt ELF_STRPTR 3 +.Os +.Sh NAME +.Nm elf_strptr +.Nd retrieve a string pointer in a string table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "char *" +.Fn elf_strptr "Elf *elf" "size_t scndx" "size_t stroffset" +.Sh DESCRIPTION +Function +.Fn elf_strptr +allows an application to convert a string table offset to a string +pointer, correctly translating the offset in the presence +of multiple +.Vt Elf_Data +descriptors covering the contents of the section. +.Pp +Argument +.Fa elf +is a descriptor for an ELF object. +Argument +.Fa scndx +is the section index for an ELF string table. +Argument +.Fa stroffset +is the index of the desired string in the string +table. +.Sh RETURN VALUES +Function +.Fn elf_strptr +returns a valid pointer on success or +.Dv NULL +in case an error was encountered. +.Sh ERRORS +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa scndx +was not the section index for a string table. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa stroffset +exceeded the size of the string table. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa stroffset +index an unallocated region of the string table. +.It Bq Er ELF_E_DATA +Offset +.Fa stroffset +indexed a region that was not covered by any Elf_Data +descriptor. +.It Bq Er ELF_E_DATA +An erroneous +.Vt Elf_Data +descriptor was part of the section specified by argument +.Fa scndx . +.It Bq Er ELF_E_HEADER +ELF descriptor +.Fa elf +contained an invalid section header. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.It Bq Er ELF_E_SECTION +Section +.Fa scndx +contained a malformed section header. +.It Bq Er ELF_E_SECTION +The ELF descriptor in argument +.Fa elf +did not adhere to the conventions used for extended numbering. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getshdr 3 , +.Xr elf64_getshdr 3 , +.Xr elf_getdata 3 , +.Xr elf_rawdata 3 , +.Xr gelf 3 , +.Xr gelf_getshdr 3 diff --git a/static/netbsd/man3/elf_update.3 b/static/netbsd/man3/elf_update.3 new file mode 100644 index 00000000..448522fc --- /dev/null +++ b/static/netbsd/man3/elf_update.3 @@ -0,0 +1,384 @@ +.\" $NetBSD: elf_update.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006-2011 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_update.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd April 22, 2019 +.Dt ELF_UPDATE 3 +.Os +.Sh NAME +.Nm elf_update +.Nd update an ELF descriptor +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft off_t +.Fn elf_update "Elf *elf" "Elf_Cmd cmd" +.Sh DESCRIPTION +Function +.Fn elf_update +causes the library to recalculate the structure of an ELF +object and optionally write out the image of the object +to file. +.Pp +Argument +.Fa elf +should reference a valid ELF descriptor. +.Pp +Argument +.Fa cmd +can be one of the following values: +.Bl -tag -width "Dv ELF_C_WRITE" +.It Dv ELF_C_NULL +The library will recalculate structural information flagging +modified structures with the +.Dv ELF_F_DIRTY +flag, but will not write data to the underlying file image. +.It Dv ELF_C_WRITE +The library will recalculate structural information and will +also write the new image to the underlying file. +The ELF descriptor referenced by argument +.Fa elf +should permit the underlying ELF object to be written or updated +(see +.Xr elf_begin 3 ) . +.El +.Pp +All pointers to +.Vt Elf_Scn +and +.Vt Elf_Data +descriptors associated with descriptor +.Fa elf +should be considered invalid after a call to +.Fn elf_update . +.Ss Specifying Object Layout +The +.Lb libelf +supports two layout modes. +.Bl -tag -width indent +.It "Library Layout" +If the +.Dv ELF_F_LAYOUT +flag is not set on the ELF descriptor, the ELF library will lay out +the ELF object according to the following scheme: +.Bl -tag -compact -width "Section Data" +.It Em EHDR +The ELF executable header will be placed at the start of the object. +.It Em PHDR +If the ELF descriptor contains a program header table, it will be +placed after the Executable Header. +.It Em Section Data +ELF section data, if any, will be placed next, keeping each section's +alignment requirements in mind. +.It Em SHDR +The ELF section header table, if any, will be placed last. +.El +.It "Application Controlled Layout" +The application can take full control of the layout of the ELF object +by setting the +.Dv ELF_F_LAYOUT +flag on the ELF descriptor (see +.Xr elf_flagelf 3 ) . +In this case the library will lay out the ELF object using +application-supplied information as below: +.Pp +.Bl -tag -compact -width "Section Data" +.It Em EHDR +The ELF executable header will be placed at the start of the object. +.It Em PHDR +The ELF program header table, if any, it will be placed at the offset +specified in the +.Va e_phoff +field of the ELF executable header. +.It Em Section Data +The data for each ELF section will be placed at the offset specified +by the +.Va sh_offset +field of the section's header. +The size of the section will be taken from the +.Va sh_size +field of the section header. +.It Em SHDR +The ELF section header table, if any, will be placed at the offset +specified by the +.Va e_shoff +field of the executable header. +.El +.El +.Pp +Gaps in the coverage of the file's contents will be set to the fill value +specified by +.Xr elf_fill 3 . +.Ss Application Supplied Information +The application needs to set the following fields in the data +structures associated with the ELF descriptor prior to calling +.Fn elf_update . +.Bl -tag -width indent +.It "Executable Header" +The fields of the ELF executable header that need to be set by the +application are: +.Pp +.Bl -tag -width "e_ident[EI_OSABI]" -compact +.It Va e_entry +To be set to the desired entry address for executables. +.It Va e_flags +To be set to the desired processor specific flags. +.It Va "e_ident[EI_DATA]" +Must be set to one of +.Dv ELFDATA2LSB +or +.Dv ELFDATA2MSB . +.It Va "e_ident[EI_OSABI]" +To be set to the OS ABI desired. +For example, for +.Fx +executables, this field should be set to +.Dv ELFOSABI_FREEBSD . +.It Va e_machine +To be set to the desired machine architecture, one of the +.Dv EM_* +values in the header file +.In elfdefinitions.h . +.It Va e_phoff +If the application is managing the object's layout, it must +set this field to the file offset of the ELF program header table. +.It Va e_shoff +If the application is managing the object's layout, it must +set this field to the file offset of the ELF section header table. +.It Va e_shstrndx +To be set to the index of the string table containing +section names. +.It Va e_type +To be set to the type of the ELF object, one of the +.Dv ET_* +values in the header file +.In elfdefinitions.h . +.It Va e_version +To be set to the desired version of the ELF object. +.El +.It "Program Header" +All fields of the entries in the program header table need to be +set by the application. +.It "Section Header" +The fields of ELF section headers that need to be set by the +application are: +.Pp +.Bl -tag -width "sh_addralign" -compact +.It Va sh_addr +To be set to the memory address where the section should reside. +.It Va sh_addralign +If the application is managing the file layout, it must set this +field to the desired alignment for the section's contents. +This value must be a power of two and must be at least as large as the +largest alignment needed by any +.Vt Elf_Data +descriptor associated with the section. +.It Va sh_entsize +To be set to the size of each entry, for sections containing fixed size +elements, or set to zero for sections without fixed size elements. +If the application is not managing file layout, it may leave this +field as zero for those sections whose types are known to the library. +.It Va sh_flags +To be set to the desired section flags. +.It Va sh_info +To be set as described in +.Xr elf 5 . +.It Va sh_link +To be set as described in +.Xr elf 5 . +.It Va sh_name +To be set to the index of the section's name in the string table +containing section names. +.It Va sh_offset +If the application is managing the file layout, it must set this +field to the file offset of the section's contents. +.It Va sh_size +If the application is managing the file layout, it must set this +field to the file size of the section's contents. +.It Va sh_type +To be set to the type of the section. +.El +.It "Section Data" +The +.Vt Elf_Data +descriptors associated with each section specify its contents +(see +.Xr elf_getdata 3 ) . +While all the fields in these descriptors are under application +control, the following fields influence object layout: +.Bl -tag -width "Va d_align" -compact +.It Va d_align +To be set to the desired alignment, within the containing section, of +the descriptor's data. +.It Va d_off +If the application is managing object layout, it must set this field +to the file offset, within the section, at which the descriptor's data +should be placed. +.It Va d_size +To be set to the size in bytes of the memory representation of the +descriptor's data. +.El +.El +.Sh RETURN VALUES +Function +.Fn elf_update +returns the total size of the file image if successful, or -1 if an +error occurred. +.Sh ERRORS +This function may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa cmd +was not recognized. +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_CLASS +The +.Va e_ident[EI_CLASS] +field of the executable header of argument +.Fa elf +did not match the class of the file. +.It Bq Er ELF_E_DATA +An +.Vt Elf_Data +descriptor contained in argument +.Fa elf +specified an unsupported type. +.It Bq Er ELF_E_DATA +An +.Vt Elf_Data +descriptor specified an alignment that was zero or was not a power of +two. +.It Bq Er ELF_E_HEADER +The ELF header in argument +.Fa elf +requested a different byte order from the byte order already +associated with the file. +.It Bq Er ELF_E_IO +An I/O error was encountered. +.It Bq Er ELF_E_LAYOUT +An +.Vt Elf_Data +descriptor contained in argument +.Fa elf +specified an alignment incompatible with its containing section. +.It Bq Er ELF_E_LAYOUT +Argument +.Fa elf +contained section descriptors that overlapped in extent. +.It Bq Er ELF_E_LAYOUT +Argument +.Fa elf +contained section descriptors that were incorrectly aligned or were +too small for their data. +.It Bq Er ELF_E_LAYOUT +The flag +.Dv ELF_F_LAYOUT +was set on the Elf descriptor and the executable header overlapped +with the program header table. +.It Bq Er ELF_E_LAYOUT +The flag +.Dv ELF_F_LAYOUT +was set on the Elf descriptor and the program header table was placed +at a misaligned file offset. +.It Bq Er ELF_E_LAYOUT +The flag +.Dv ELF_F_LAYOUT +was set on the Elf descriptor and the section header table overlapped +an extent mapped by a section descriptor. +.It Bq Er ELF_E_LAYOUT +The +.Dv ELF_F_LAYOUT +flag was set on the Elf descriptor, and the +.Va d_offset +field in an +.Vt Elf_Data +descriptor contained a value that was not a multiple of the +descriptor's specified alignment. +.It Bq Er ELF_E_MODE +An +.Dv ELF_C_WRITE +operation was requested with an ELF descriptor that was not opened for +writing or updating. +.It Bq Er ELF_E_SECTION +Argument +.Fa elf +contained a section with an unrecognized type. +.It Bq Er ELF_E_SECTION +The section header at index +.Dv SHN_UNDEF +had an illegal section type. +.It Bq Er ELF_E_SEQUENCE +An +.Dv ELF_C_WRITE +operation was requested after a prior call to +.Fn elf_cntl elf ELF_C_FDDONE +disassociated the ELF descriptor +.Fa elf +from its underlying file. +.It Bq Er ELF_E_UNIMPL +Argument +.Fa elf +contained a section with an unsupported ELF type. +.It Bq Er ELF_E_VERSION +Argument +.Fa elf +had an unsupported version or contained an +.Vt Elf_Data +descriptor with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf32_getphdr 3 , +.Xr elf32_newehdr 3 , +.Xr elf32_newphdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf64_getphdr 3 , +.Xr elf64_newehdr 3 , +.Xr elf64_newphdr 3 , +.Xr elf_begin 3 , +.Xr elf_cntl 3 , +.Xr elf_fill 3 , +.Xr elf_flagehdr 3 , +.Xr elf_flagelf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr elf_newdata 3 , +.Xr elf_newscn 3 , +.Xr elf_rawdata 3 , +.Xr gelf 3 , +.Xr gelf_newehdr 3 , +.Xr gelf_newphdr 3 , +.Xr elf 5 diff --git a/static/netbsd/man3/elf_version.3 b/static/netbsd/man3/elf_version.3 new file mode 100644 index 00000000..8eb48c4e --- /dev/null +++ b/static/netbsd/man3/elf_version.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: elf_version.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: elf_version.3 3957 2022-03-12 14:11:52Z jkoshy +.\" +.Dd November 9, 2011 +.Dt ELF_VERSION 3 +.Os +.Sh NAME +.Nm elf_version +.Nd retrieve or set ELF library operating version +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft unsigned int +.Fn elf_version "unsigned int version" +.Sh DESCRIPTION +The +.Fn elf_version +function is used to query the current operating version of the ELF +library, and to inform the ELF library about the application's desired +operating version. +.Pp +If the argument +.Fa version +is +.Dv EV_NONE , +the +.Fn elf_version +function returns the currently configured operating version for the +ELF library. +.Pp +If the argument +.Fa version +is not +.Dv EV_NONE , +and if argument +.Fa version +is supported by the ELF library, function +.Fn elf_version +sets the library's operating version to +.Fa version , +and returns the previous value of the operating version. +If argument +.Fa version +cannot be supported, then the +.Fn elf_version +function returns +.Dv EV_NONE . +.Sh RETURN VALUES +The +.Fn elf_version +function returns the currently configured ELF library version, or +.Dv EV_NONE +if an unsupported version is requested. +.Sh EXAMPLES +An application program would inform the ELF library about its desired +operating version and check for an error using the following code +snippet: +.Bd -literal -offset indent +if (elf_version(EV_CURRENT) == EV_NONE) + err(EXIT_FAILURE, "ELF library too old"); +.Ed +.Sh ERRORS +Function +.Fn elf_version +may fail with the following error: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er "ELF_E_VERSION" +An unsupported library version number was requested. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/endutent.3 b/static/netbsd/man3/endutent.3 new file mode 100644 index 00000000..42784e1f --- /dev/null +++ b/static/netbsd/man3/endutent.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: endutent.3,v 1.2 2021/02/26 06:39:14 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 25, 2021 +.Dt ENDUTENT 3 +.Os +.Sh NAME +.Nm endutent , +.Nm getutent , +.Nm getutline , +.Nm pututline , +.Nm setutent +.Nd user accounting database functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In utmp.h +.Ft void +.Fn endutent void +.Ft struct utmp * +.Fn getutent void +.Ft struct utmpx * +.Fn getutline "const struct utmp *" +.Ft struct utmp * +.Fn pututline "const struct utmp *" +.Ft void +.Fn setutent void +.Sh DESCRIPTION +These functions provide access to the +.Xr utmp 5 +user accounting database. +.Pp +These interfaces are only provided for compatibility purpuses and +have been superseeded by +.Xr endutxent 3 , +.Xr utmpx 5 . +.Pp +.Fn getutent +reads the next entry from the database; +if the database was not yet open, it also opens it. +.Fn setutent +resets the database, so that the next +.Fn getutent +call will get the first entry. +.Fn endutent +closes the database. +.Pp +.Fn getutline +returns the next +entry which has the same name as specified in the +.Va ut_line +field, or +.Dv NULL +if no match is found. +.Pp +.Fn pututline +adds the argument +.Xr utmp 5 +entry line to the accounting database, replacing a previous entry for +the same user if it exists. +.Ss The utmp structure +The +.Nm utmp +structure has the following definition: +.Bd -literal +struct utmp { + char ut_line[UT_LINESIZE]; /* tty name */ + char ut_name[UT_USERSIZE]; /* login name */ + char ut_host[UT_HOSTSIZE]; /* host name */ + time_t ut_time; /* time entry was created */ +}; +.Ed +.Sh RETURN VALUES +.Fn getutent +returns the next entry, or +.Dv NULL +on failure (end of database or problems reading from the database). +.Fn getutline +returns the matching structure on success, or +.Dv NULL +if no match was found. +.Fn pututline +returns the structure that was successfully written, or +.Dv NULL . +.Sh SEE ALSO +.Xr logwtmp 3 , +.Xr utmp 5 +.Sh STANDARDS +The +.Fn endutent , +.Fn getutent , +.Fn getutline , +.Fn pututline , +.Fn setutent +functions all conform to +.St -xpg4.2 . diff --git a/static/netbsd/man3/endutxent.3 b/static/netbsd/man3/endutxent.3 new file mode 100644 index 00000000..9adaff17 --- /dev/null +++ b/static/netbsd/man3/endutxent.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: endutxent.3,v 1.7 2020/07/05 01:09:48 christos Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 26, 2002 +.Dt ENDUTXENT 3 +.Os +.Sh NAME +.Nm endutxent , +.Nm getutxent , +.Nm getutxid , +.Nm getutxline , +.Nm pututxline , +.Nm setutxent +.Nd user accounting database functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In utmpx.h +.Ft void +.Fn endutxent void +.Ft struct utmpx * +.Fn getutxent void +.Ft struct utmpx * +.Fn getutxid "const struct utmpx *" +.Ft struct utmpx * +.Fn getutxline "const struct utmpx *" +.Ft struct utmpx * +.Fn pututxline "const struct utmpx *" +.Ft void +.Fn setutxent void +.Sh DESCRIPTION +These functions provide access to the +.Xr utmpx 5 +user accounting database. +.Pp +.Fn getutxent +reads the next entry from the database; +if the database was not yet open, it also opens it. +.Fn setutxent +resets the database, so that the next +.Fn getutxent +call will get the first entry. +.Fn endutxent +closes the database. +.Pp +.Fn getutxid +returns the next entry of the type specified in its argument's +.Va ut_type +field, or +.Dv NULL +if none is found. +.Fn getutxline +returns the next +.Dv LOGIN_PROCESS +or +.Dv USER_PROCESS +entry which has the same name as specified in the +.Va ut_line +field, or +.Dv NULL +if no match is found. +.Pp +.Fn pututxline +adds the argument +.Xr utmpx 5 +entry line to the accounting database, replacing a previous entry for +the same user if it exists. +.Ss The utmpx structure +The +.Nm utmpx +structure has the following definition: +.Pp +.Bd -literal +struct utmpx { + char ut_name[_UTX_USERSIZE]; /* login name */ + char ut_id[_UTX_IDSIZE]; /* inittab id */ + char ut_line[_UTX_LINESIZE]; /* tty name */ + char ut_host[_UTX_HOSTSIZE]; /* host name */ + uint16_t ut_session; /* session id used for windowing */ + uint16_t ut_type; /* type of this entry */ + pid_t ut_pid; /* process id creating the entry */ + struct { + uint16_t e_termination; /* process termination signal */ + uint16_t e_exit; /* process exit status */ + } ut_exit; + struct sockaddr_storage ut_ss; /* address where entry was made from */ + struct timeval ut_tv; /* time entry was created */ + uint32_t ut_pad[10]; /* reserved for future use */ +}; +.Ed +.Pp +Valid entries for +.Fa ut_type +are: +.Bl -tag -width LOGIN_PROCESSXX -compact -offset indent +.It Dv BOOT_TIME +Time of a system boot. +.It Dv DEAD_PROCESS +A session leader exited. +.It Dv EMPTY +No valid user accounting information. +.It Dv INIT_PROCESS +A process spawned by +.Xr init 8 . +.It Dv LOGIN_PROCESS +The session leader of a logged-in user. +.It Dv NEW_TIME +Time after system clock change. +.It Dv OLD_TIME +Time before system clock change. +.It Dv RUN_LVL +Run level. +Provided for compatibility, not used on +.Nx . +.It Dv USER_PROCESS +A user process. +.El +.Sh RETURN VALUES +.Fn getutxent +returns the next entry, or +.Dv NULL +on failure (end of database or problems reading from the database). +.Fn getutxid +and +.Fn getutxline +return the matching structure on success, or +.Dv NULL +if no match was found. +.Fn pututxline +returns the structure that was successfully written, or +.Dv NULL . +.Sh SEE ALSO +.Xr logwtmpx 3 , +.Xr utmpx 5 +.Sh STANDARDS +The +.Fn endutxent , +.Fn getutxent , +.Fn getutxid , +.Fn getutxline , +.Fn pututxline , +.Fn setutxent +all conform to +.St -p1003.1-2001 +(XSI extension), and previously to +.St -xpg4.2 . +The fields +.Fa ut_user , +.Fa ut_id , +.Fa ut_line , +.Fa ut_pid , +.Fa ut_type , +and +.Fa ut_tv +conform to +.St -p1003.1-2001 +(XSI extension), and previously to +.St -xpg4.2 . +.\" .Fa ut_host , +.\" .Fa ut_session , +.\" .Fa ut_exit , +.\" and +.\" .Fa ut_ss +.\" are from +.\" SVR3/4? +.\" .Dv RUN_LVL +.\" is for compatibility with +.\" what exactly? +.\" .Sh HISTORY +.\" The +.\" .Nm utmpx , +.\" .Nm wtmpx , +.\" and +.\" .Nm lastlogx +.\" files first appeared in +.\" SVR3? 4? diff --git a/static/netbsd/man3/erf.3 b/static/netbsd/man3/erf.3 new file mode 100644 index 00000000..37cff571 --- /dev/null +++ b/static/netbsd/man3/erf.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)erf.3 6.4 (Berkeley) 4/20/91 +.\" $NetBSD: erf.3,v 1.14 2015/11/07 18:17:51 nros Exp $ +.\" +.Dd November 7, 2015 +.Dt ERF 3 +.Os +.Sh NAME +.Nm erf , +.Nm erff , +.Nm erfl , +.Nm erfc , +.Nm erfcf , +.Nm erfcl +.Nd error function operators +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn erf "double x" +.Ft float +.Fn erff "float x" +.Ft long double +.Fn erfl "long double x" +.Ft double +.Fn erfc "double x" +.Ft float +.Fn erfcf "float x" +.Ft long double +.Fn erfcl "long double x" +.Sh DESCRIPTION +These functions calculate the error function of +.Fa x . +.Pp +The +.Fn erf +calculates the error function of x; where +.Bd -filled -offset indent +.if n \{\ +erf(x) = 2/sqrt(pi)\(**\|integral from 0 to x of exp(\-t\(**t) dt. \} +.if t \{\ +erf\|(x) := +(2/\(sr\(*p)\|\(is\d\s8\z0\s10\u\u\s8x\s10\d\|exp(\-t\u\s82\s10\d)\|dt. \} +.Ed +.Pp +The +.Fn erfc +function calculates the complementary error function of +.Fa x ; +that is +.Fn erfc +subtracts the result of the error function +.Fn erf x +from 1.0. +This is useful, since for large +.Fa x +places disappear. +.Sh SEE ALSO +.Xr math 3 +.Sh HISTORY +The +.Fn erf +and +.Fn erfc +functions appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/err.3 b/static/netbsd/man3/err.3 new file mode 100644 index 00000000..e48d2856 --- /dev/null +++ b/static/netbsd/man3/err.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: err.3,v 1.24 2024/02/02 21:16:41 jkoshy Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)err.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd February 2, 2024 +.Dt ERR 3 +.Os +.Sh NAME +.Nm err , +.Nm verr , +.Nm errx , +.Nm verrx , +.Nm errc , +.Nm verrc , +.Nm warn , +.Nm vwarn , +.Nm warnx , +.Nm vwarnx , +.Nm warnc , +.Nm vwarnc +.Nd formatted error messages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In err.h +.Ft void +.Fn err "int status" "const char *fmt" "..." +.Ft void +.Fn verr "int status" "const char *fmt" "va_list args" +.Ft void +.Fn errx "int status" "const char *fmt" "..." +.Ft void +.Fn verrx "int status" "const char *fmt" "va_list args" +.Ft void +.Fn errc "int status" "int code" "const char *fmt" "..." +.Ft void +.Fn verrc "int status" "int code" "const char *fmt" "va_list args" +.Ft void +.Fn warn "const char *fmt" "..." +.Ft void +.Fn vwarn "const char *fmt" "va_list args" +.Ft void +.Fn warnx "const char *fmt" "..." +.Ft void +.Fn vwarnx "const char *fmt" "va_list args" +.Ft void +.Fn warnc "int code" "const char *fmt" "..." +.Ft void +.Fn vwarnc "int code" "const char *fmt" "va_list args" +.Sh DESCRIPTION +The +.Fn err +and +.Fn warn +family of functions display a formatted error message on the standard +error output. +.Pp +In all cases these functions output the last component of the program name, +a colon character, and a space. +If the +.Fa fmt +argument is not +.Dv NULL , +it is used as a +.Xr printf 3 Ns +-like format specification for the error message. +.Pp +In the case of the +.Fn err , +.Fn verr , +.Fn warn , +and +.Fn vwarn +functions, an additional error message string affiliated with the current +value of the global variable +.Va errno +is output next, preceded by a colon character and a space if +.Fa fmt +is not +.Dv NULL . +The +.Fn errc , +.Fn verrc , +.Fn warnc , +and +.Fn vwarnc +functions take an additional +.Ar code +argument to be used as the error number instead of using the global +.Va errno +variable. +The +.Fn errx , +.Fn verrx , +.Fn warnx , +and +.Fn vwarnx +functions will not output an additional error message string. +.Pp +In all cases, the output is terminated by a newline character. +.Pp +The +.Fn err , +.Fn verr , +.Fn errc , +.Fn verrc , +.Fn errx , +and +.Fn verrx +functions do not return, but instead cause the program to terminate +with the status value given by the argument +.Fa status . +It is often appropriate to use the value +.Dv EXIT_FAILURE , +defined in +.In stdlib.h , +as the +.Fa status +argument given to these functions. +.Sh EXAMPLES +Display the current +.Va errno +information string and terminate with status indicating failure: +.Bd -literal -offset indent +if ((p = malloc(size)) == NULL) + err(EXIT_FAILURE, NULL); +if ((fd = open(file_name, O_RDONLY, 0)) == -1) + err(EXIT_FAILURE, "%s", file_name); +.Ed +.Pp +Display an error message and terminate with status indicating failure: +.Bd -literal -offset indent +if (tm.tm_hour < START_TIME) + errx(EXIT_FAILURE, "too early, wait until %s", + start_time_string); +.Ed +.Pp +Warn of an error: +.Bd -literal -offset indent +if ((fd = open(raw_device, O_RDONLY, 0)) == -1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +if ((fd = open(block_device, O_RDONLY, 0)) == -1) + warn("%s", block_device); +.Ed +.Sh SEE ALSO +.Xr exit 3 , +.Xr getprogname 3 , +.Xr printf 3 , +.Xr strerror 3 +.Sh HISTORY +The +.Fn err +and +.Fn warn +functions first appeared in +.Bx 4.4 . +The +.Fn errc +and +.Fn warnc +functions first appeared in +.Fx 3.0 +and +.Nx 7.0 . +.Sh CAVEATS +It is important never to pass a string with user-supplied data as a +format without using +.Ql %s . +An attacker can put format specifiers in the string to mangle your stack, +leading to a possible security hole. +This holds true even if you have built the string +.Dq by hand +using a function like +.Fn snprintf , +as the resulting string may still contain user-supplied conversion specifiers +for later interpolation by the +.Fn err +and +.Fn warn +functions. +.Pp +Always be sure to use the proper secure idiom: +.Bd -literal -offset indent +err(1, "%s", string); +.Ed diff --git a/static/netbsd/man3/es256_pk_new.3 b/static/netbsd/man3/es256_pk_new.3 new file mode 100644 index 00000000..7d6be4d6 --- /dev/null +++ b/static/netbsd/man3/es256_pk_new.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt ES256_PK_NEW 3 +.Os +.Sh NAME +.Nm es256_pk_new , +.Nm es256_pk_free , +.Nm es256_pk_from_EC_KEY , +.Nm es256_pk_from_EVP_PKEY , +.Nm es256_pk_from_ptr , +.Nm es256_pk_to_EVP_PKEY +.Nd FIDO2 COSE ES256 API +.Sh SYNOPSIS +.In openssl/ec.h +.In fido/es256.h +.Ft es256_pk_t * +.Fn es256_pk_new "void" +.Ft void +.Fn es256_pk_free "es256_pk_t **pkp" +.Ft int +.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec" +.Ft int +.Fn es256_pk_from_EVP_PKEY "es256_pk_t *pk" "const EVP_PKEY *pkey" +.Ft int +.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk" +.Sh DESCRIPTION +ES256 is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to ECDSA over P-256 with SHA-256. +The COSE ES256 API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +ECDSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +ES256 public keys are abstracted by the +.Vt es256_pk_t +type. +.Pp +The +.Fn es256_pk_new +function returns a pointer to a newly allocated, empty +.Vt es256_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn es256_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn es256_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn es256_pk_free +is a NOP. +.Pp +The +.Fn es256_pk_from_EC_KEY +function fills +.Fa pk +with the contents of +.Fa ec . +No references to +.Fa ec +are kept. +.Pp +The +.Fn es256_pk_from_EVP_PKEY +function fills +.Fa pk +with the contents of +.Fa pkey . +No references to +.Fa pkey +are kept. +.Pp +The +.Fn es256_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +The +.Fa ptr +pointer may point to an uncompressed point, or to the +concatenation of the x and y coordinates. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn es256_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn es256_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn es256_pk_from_EC_KEY , +.Fn es256_pk_from_EVP_PKEY , +and +.Fn es256_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr eddsa_pk_new 3 , +.Xr es384_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/static/netbsd/man3/es384_pk_new.3 b/static/netbsd/man3/es384_pk_new.3 new file mode 100644 index 00000000..e865913b --- /dev/null +++ b/static/netbsd/man3/es384_pk_new.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt ES384_PK_NEW 3 +.Os +.Sh NAME +.Nm es384_pk_new , +.Nm es384_pk_free , +.Nm es384_pk_from_EC_KEY , +.Nm es384_pk_from_EVP_PKEY , +.Nm es384_pk_from_ptr , +.Nm es384_pk_to_EVP_PKEY +.Nd FIDO2 COSE ES384 API +.Sh SYNOPSIS +.In openssl/ec.h +.In fido/es384.h +.Ft es384_pk_t * +.Fn es384_pk_new "void" +.Ft void +.Fn es384_pk_free "es384_pk_t **pkp" +.Ft int +.Fn es384_pk_from_EC_KEY "es384_pk_t *pk" "const EC_KEY *ec" +.Ft int +.Fn es384_pk_from_EVP_PKEY "es384_pk_t *pk" "const EVP_PKEY *pkey" +.Ft int +.Fn es384_pk_from_ptr "es384_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn es384_pk_to_EVP_PKEY "const es384_pk_t *pk" +.Sh DESCRIPTION +ES384 is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to ECDSA over P-384 with SHA-384. +The COSE ES384 API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +ECDSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +ES384 public keys are abstracted by the +.Vt es384_pk_t +type. +.Pp +The +.Fn es384_pk_new +function returns a pointer to a newly allocated, empty +.Vt es384_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn es384_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn es384_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn es384_pk_free +is a NOP. +.Pp +The +.Fn es384_pk_from_EC_KEY +function fills +.Fa pk +with the contents of +.Fa ec . +No references to +.Fa ec +are kept. +.Pp +The +.Fn es384_pk_from_EVP_PKEY +function fills +.Fa pk +with the contents of +.Fa pkey . +No references to +.Fa pkey +are kept. +.Pp +The +.Fn es384_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +The +.Fa ptr +pointer may point to an uncompressed point, or to the +concatenation of the x and y coordinates. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn es384_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn es384_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn es384_pk_from_EC_KEY , +.Fn es384_pk_from_EVP_PKEY , +and +.Fn es384_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr eddsa_pk_new 3 , +.Xr es256_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/static/netbsd/man3/ethers.3 b/static/netbsd/man3/ethers.3 new file mode 100644 index 00000000..204cffb0 --- /dev/null +++ b/static/netbsd/man3/ethers.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: ethers.3,v 1.15 2017/10/30 15:46:38 wiz Exp $ +.\" +.\" Written by roland@frob.com. Public domain. +.\" +.Dd November 2, 1997 +.Dt ETHERS 3 +.Os +.Sh NAME +.Nm ether_ntoa , +.Nm ether_aton , +.Nm ether_ntohost , +.Nm ether_hostton , +.Nm ether_line +.Nd get ethers entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/if_ether.h +.Ft char * +.Fn ether_ntoa "const struct ether_addr *e" +.Ft struct ether_addr * +.Fn ether_aton "const char *s" +.Ft int +.Fn ether_ntohost "char *hostname" "const struct ether_addr *e" +.Ft int +.Fn ether_hostton "const char *hostname" "struct ether_addr *e" +.Ft int +.Fn ether_line "const char *line" "struct ether_addr *e" "char *hostname" +.Sh DESCRIPTION +Ethernet addresses are represented by the +following structure: +.Bd -literal -offset indent +struct ether_addr { + u_char ether_addr_octet[6]; +}; +.Ed +.Pp +The +.Fn ether_ntoa +function converts this structure into an ASCII string of the form +``xx:xx:xx:xx:xx:xx'', consisting of 6 hexadecimal numbers separated +by colons. +It returns a pointer to a static buffer that is reused for +each call. +The +.Fn ether_aton +converts an ASCII string of the same form and to a structure +containing the 6 octets of the address. +It returns a pointer to a +static structure that is reused for each call. +.Pp +The +.Fn ether_ntohost +and +.Fn ether_hostton +functions interrogate the data base mapping host names to Ethernet +addresses, +.Pa /etc/ethers . +The +.Fn ether_ntohost +function looks up the given Ethernet address and writes the associated +host name into the character buffer passed. +The +.Fn ether_hostton +function looks up the given host name and writes the associated +Ethernet address into the structure passed. +Both functions return +zero if they find the requested host name or address, and -1 if not. +Each call reads +.Pa /etc/ethers +from the beginning; if a + appears alone on a line in the file, then +.Fn ether_hostton +will consult the +.Pa ethers.byname +YP map, and +.Fn ether_ntohost +will consult the +.Pa ethers.byaddr +YP map. +.Pp +The +.Fn ether_line +function parses a line from the +.Pa /etc/ethers +file and fills in the passed ``struct ether_addr'' and character +buffer with the Ethernet address and host name on the line. +It returns zero if the line was successfully parsed and -1 if not. +.Pp +The +.Fa hostname +buffer for +.Fn ether_line +and +.Fn ether_ntohost +should be at least +.Dv MAXHOSTNAMELEN ++ 1 +characters long, to prevent a buffer overflow during parsing. +.Sh FILES +.Bl -tag -width /etc/ethers -compact +.It Pa /etc/ethers +.El +.Sh SEE ALSO +.Xr ethers 5 +.Sh HISTORY +The +.Fn ether_ntoa , +.Fn ether_aton , +.Fn ether_ntohost , +.Fn ether_hostton , +and +.Fn ether_line +functions were adopted from SunOS and appeared in +.Nx 1.0 . +.Sh BUGS +The data space used by these functions is static; if future use +requires the data, it should be copied before any subsequent calls to +these functions overwrite it. diff --git a/static/netbsd/man3/evbuffer.3 b/static/netbsd/man3/evbuffer.3 new file mode 100644 index 00000000..3505aaee --- /dev/null +++ b/static/netbsd/man3/evbuffer.3 @@ -0,0 +1,27 @@ +.TH "evbuffer" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evbuffer \- An evbuffer is an opaque data type for efficiently buffering data to be sent or received on the network\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +An evbuffer is an opaque data type for efficiently buffering data to be sent or received on the network\&. + + +.PP +\fBSee also:\fP +.RS 4 +\fBevent2/event\&.h\fP for more information +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evbuffer_cb_info.3 b/static/netbsd/man3/evbuffer_cb_info.3 new file mode 100644 index 00000000..9ce4ef61 --- /dev/null +++ b/static/netbsd/man3/evbuffer_cb_info.3 @@ -0,0 +1,57 @@ +.TH "evbuffer_cb_info" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evbuffer_cb_info \- Structure passed to an evbuffer_cb_func evbuffer callback\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "size_t \fBn_added\fP" +.br +.RI "\fIThe number of bytes added since callbacks were last invoked\&. \fP" +.ti -1c +.RI "size_t \fBn_deleted\fP" +.br +.RI "\fIThe number of bytes removed since callbacks were last invoked\&. \fP" +.ti -1c +.RI "size_t \fBorig_size\fP" +.br +.RI "\fIThe number of bytes in this evbuffer when callbacks were last invoked\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Structure passed to an evbuffer_cb_func evbuffer callback\&. + + +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_cb_func\fP, \fBevbuffer_add_cb()\fP +.RE +.PP + +.SH "Field Documentation" +.PP +.SS "size_t evbuffer_cb_info::n_added" + +.PP +The number of bytes added since callbacks were last invoked\&. +.SS "size_t evbuffer_cb_info::n_deleted" + +.PP +The number of bytes removed since callbacks were last invoked\&. +.SS "size_t evbuffer_cb_info::orig_size" + +.PP +The number of bytes in this evbuffer when callbacks were last invoked\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evbuffer_iovec.3 b/static/netbsd/man3/evbuffer_iovec.3 new file mode 100644 index 00000000..969dc9e0 --- /dev/null +++ b/static/netbsd/man3/evbuffer_iovec.3 @@ -0,0 +1,49 @@ +.TH "evbuffer_iovec" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evbuffer_iovec \- Describes a single extent of memory inside an evbuffer\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "void * \fBiov_base\fP" +.br +.RI "\fIThe start of the extent of memory\&. \fP" +.ti -1c +.RI "size_t \fBiov_len\fP" +.br +.RI "\fIThe length of the extent of memory\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Describes a single extent of memory inside an evbuffer\&. + +Used for direct-access functions\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_reserve_space\fP, \fBevbuffer_commit_space\fP, \fBevbuffer_peek\fP +.RE +.PP + +.SH "Field Documentation" +.PP +.SS "void* evbuffer_iovec::iov_base" + +.PP +The start of the extent of memory\&. +.SS "size_t evbuffer_iovec::iov_len" + +.PP +The length of the extent of memory\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evbuffer_ptr.3 b/static/netbsd/man3/evbuffer_ptr.3 new file mode 100644 index 00000000..39ee75fc --- /dev/null +++ b/static/netbsd/man3/evbuffer_ptr.3 @@ -0,0 +1,48 @@ +.TH "evbuffer_ptr" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evbuffer_ptr \- Pointer to a position within an evbuffer\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "struct {" +.br +.ti -1c +.RI " void * \fBchain\fP" +.br +.ti -1c +.RI " size_t \fBpos_in_chain\fP" +.br +.ti -1c +.RI "} \fBinternal_\fP" +.br +.ti -1c +.RI "ev_ssize_t \fBpos\fP" +.br +.in -1c +.SH "Detailed Description" +.PP +Pointer to a position within an evbuffer\&. + +Used when repeatedly searching through a buffer\&. Calling any function that modifies or re-packs the buffer contents may invalidate all evbuffer_ptrs for that buffer\&. Do not modify or contruct these values except with evbuffer_ptr_set\&. +.PP +An \fBevbuffer_ptr\fP can represent any position from the start of a buffer up to a position immediately after the end of a buffer\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevbuffer_ptr_set()\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/event.3 b/static/netbsd/man3/event.3 new file mode 100644 index 00000000..d4fa3d65 --- /dev/null +++ b/static/netbsd/man3/event.3 @@ -0,0 +1,43 @@ +.TH "event" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event \- Structure to represent a single event\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Structure to represent a single event\&. + +An event can have some underlying condition it represents: a socket becoming readable or writeable (or both), or a signal becoming raised\&. (An event that represents no underlying condition is still useful: you can use one to implement a timer, or to communicate between threads\&.) +.PP +Generally, you can create events with \fBevent_new()\fP, then make them pending with \fBevent_add()\fP\&. As your \fBevent_base\fP runs, it will run the callbacks of an events whose conditions are triggered\&. When you longer want the event, free it with \fBevent_free()\fP\&. +.PP +In more depth: +.PP +An event may be 'pending' (one whose condition we are watching), 'active' (one whose condition has triggered and whose callback is about to run), neither, or both\&. Events come into existence via \fBevent_assign()\fP or \fBevent_new()\fP, and are then neither active nor pending\&. +.PP +To make an event pending, pass it to \fBevent_add()\fP\&. When doing so, you can also set a timeout for the event\&. +.PP +Events become active during an \fBevent_base_loop()\fP call when either their condition has triggered, or when their timeout has elapsed\&. You can also activate an event manually using \fBevent_active()\fP\&. The even_base loop will run the callbacks of active events; after it has done so, it marks them as no longer active\&. +.PP +You can make an event non-pending by passing it to \fBevent_del()\fP\&. This also makes the event non-active\&. +.PP +Events can be 'persistent' or 'non-persistent'\&. A non-persistent event becomes non-pending as soon as it is triggered: thus, it only runs at most once per call to \fBevent_add()\fP\&. A persistent event remains pending even when it becomes active: you'll need to \fBevent_del()\fP it manually in order to make it non-pending\&. When a persistent event with a timeout becomes active, its timeout is reset: this means you can use persistent events to implement periodic timeouts\&. +.PP +This should be treated as an opaque structure; you should never read or write any of its fields directly\&. For backward compatibility with old code, it is defined in the event2/event_struct\&.h header; including this header may make your code incompatible with other versions of Libevent\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_new()\fP, \fBevent_free()\fP, \fBevent_assign()\fP, \fBevent_get_assignment()\fP, \fBevent_add()\fP, \fBevent_del()\fP, \fBevent_active()\fP, \fBevent_pending()\fP, \fBevent_get_fd()\fP, \fBevent_get_base()\fP, \fBevent_get_events()\fP, \fBevent_get_callback()\fP, \fBevent_get_callback_arg()\fP, \fBevent_priority_set()\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/event.h.3 b/static/netbsd/man3/event.h.3 new file mode 100644 index 00000000..2c2870e2 --- /dev/null +++ b/static/netbsd/man3/event.h.3 @@ -0,0 +1,1778 @@ +.TH "event2/event.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/event.h \- Core functions for waiting for and receiving events, and using event bases\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBevent\fP" +.br +.RI "\fIStructure to represent a single event\&. \fP" +.ti -1c +.RI "struct \fBevent_base\fP" +.br +.RI "\fIStructure to hold information and state for a Libevent dispatch loop\&. \fP" +.ti -1c +.RI "struct \fBevent_config\fP" +.br +.RI "\fIConfiguration for an \fBevent_base\fP\&. \fP" +.in -1c +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fB_EVENT_LOG_DEBUG\fP EVENT_LOG_DEBUG" +.br +.ti -1c +.RI "#define \fB_EVENT_LOG_ERR\fP EVENT_LOG_ERR" +.br +.ti -1c +.RI "#define \fB_EVENT_LOG_MSG\fP EVENT_LOG_MSG" +.br +.ti -1c +.RI "#define \fB_EVENT_LOG_WARN\fP EVENT_LOG_WARN" +.br +.ti -1c +.RI "#define \fBEVENT_DBG_ALL\fP 0xffffffffu" +.br +.ti -1c +.RI "#define \fBEVENT_DBG_NONE\fP 0" +.br +.ti -1c +.RI "#define \fBevent_get_signal\fP(ev) ((int)\fBevent_get_fd\fP(ev))" +.br +.RI "\fIGet the signal number assigned to a signal event\&. \fP" +.ti -1c +.RI "#define \fBEVENT_MAX_PRIORITIES\fP 256" +.br +.RI "\fILargest number of priorities that Libevent can support\&. \fP" +.ti -1c +.RI "#define \fBEVENT_SET_MEM_FUNCTIONS_IMPLEMENTED\fP" +.br +.RI "\fIThis definition is present if Libevent was built with support for \fBevent_set_mem_functions()\fP \fP" +.ti -1c +.RI "#define \fBLIBEVENT_VERSION\fP EVENT__VERSION" +.br +.RI "\fIAs event_get_version, but gives the version of Libevent's headers\&. \fP" +.ti -1c +.RI "#define \fBLIBEVENT_VERSION_NUMBER\fP EVENT__NUMERIC_VERSION" +.br +.RI "\fIAs event_get_version_number, but gives the version number of Libevent's headers\&. \fP" +.in -1c +.PP +.RI "\fBevent type flag\fP" +.br +Flags to pass to \fBevent_base_get_num_events()\fP to specify the kinds of events we want to aggregate counts for +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVENT_BASE_COUNT_ACTIVE\fP 1U" +.br +.RI "\fIcount the number of active events, which have been triggered\&. \fP" +.ti -1c +.RI "#define \fBEVENT_BASE_COUNT_VIRTUAL\fP 2U" +.br +.RI "\fIcount the number of virtual events, which is used to represent an internal condition, other than a pending event, that keeps the loop from exiting\&. \fP" +.ti -1c +.RI "#define \fBEVENT_BASE_COUNT_ADDED\fP 4U" +.br +.RI "\fIcount the number of events which have been added to event base, including internal events\&. \fP" +.in -1c +.in -1c +.PP +.RI "\fBLog severities\fP" +.br + +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVENT_LOG_DEBUG\fP 0" +.br +.ti -1c +.RI "#define \fBEVENT_LOG_MSG\fP 1" +.br +.ti -1c +.RI "#define \fBEVENT_LOG_WARN\fP 2" +.br +.ti -1c +.RI "#define \fBEVENT_LOG_ERR\fP 3" +.br +.in -1c +.in -1c +.PP +.RI "\fBLoop flags\fP" +.br +These flags control the behavior of \fBevent_base_loop()\fP\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVLOOP_ONCE\fP 0x01" +.br +.RI "\fIBlock until we have an active event, then exit once all active events have had their callbacks run\&. \fP" +.ti -1c +.RI "#define \fBEVLOOP_NONBLOCK\fP 0x02" +.br +.RI "\fIDo not block: see which events are ready now, run the callbacks of the highest-priority ones, then exit\&. \fP" +.ti -1c +.RI "#define \fBEVLOOP_NO_EXIT_ON_EMPTY\fP 0x04" +.br +.RI "\fIDo not exit the loop because we have no pending events\&. \fP" +.in -1c +.in -1c +.PP +.RI "\fBevent flags\fP" +.br +Flags to pass to \fBevent_new()\fP, \fBevent_assign()\fP, \fBevent_pending()\fP, and anything else with an argument of the form 'short events' +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEV_TIMEOUT\fP 0x01" +.br +.RI "\fIIndicates that a timeout has occurred\&. \fP" +.ti -1c +.RI "#define \fBEV_READ\fP 0x02" +.br +.RI "\fIWait for a socket or FD to become readable\&. \fP" +.ti -1c +.RI "#define \fBEV_WRITE\fP 0x04" +.br +.RI "\fIWait for a socket or FD to become writeable\&. \fP" +.ti -1c +.RI "#define \fBEV_SIGNAL\fP 0x08" +.br +.RI "\fIWait for a POSIX signal to be raised\&. \fP" +.ti -1c +.RI "#define \fBEV_PERSIST\fP 0x10" +.br +.RI "\fIPersistent event: won't get removed automatically when activated\&. \fP" +.ti -1c +.RI "#define \fBEV_ET\fP 0x20" +.br +.RI "\fISelect edge-triggered behavior, if supported by the backend\&. \fP" +.ti -1c +.RI "#define \fBEV_FINALIZE\fP 0x40" +.br +.RI "\fIIf this option is provided, then \fBevent_del()\fP will not block in one thread while waiting for the event callback to complete in another thread\&. \fP" +.ti -1c +.RI "#define \fBEV_CLOSED\fP 0x80" +.br +.RI "\fIDetects connection close events\&. \fP" +.in -1c +.in -1c +.PP +.RI "\fBevtimer_* macros\fP" +.br +Aliases for working with one-shot timer events +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBevtimer_assign\fP(ev, b, cb, arg) \fBevent_assign\fP((ev), (b), \-1, 0, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBevtimer_new\fP(b, cb, arg) \fBevent_new\fP((b), \-1, 0, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBevtimer_add\fP(ev, tv) \fBevent_add\fP((ev), (tv))" +.br +.ti -1c +.RI "#define \fBevtimer_del\fP(ev) \fBevent_del\fP(ev)" +.br +.ti -1c +.RI "#define \fBevtimer_pending\fP(ev, tv) \fBevent_pending\fP((ev), \fBEV_TIMEOUT\fP, (tv))" +.br +.ti -1c +.RI "#define \fBevtimer_initialized\fP(ev) \fBevent_initialized\fP(ev)" +.br +.in -1c +.in -1c +.PP +.RI "\fBevsignal_* macros\fP" +.br +Aliases for working with signal events +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBevsignal_add\fP(ev, tv) \fBevent_add\fP((ev), (tv))" +.br +.ti -1c +.RI "#define \fBevsignal_assign\fP(ev, b, x, cb, arg) \fBevent_assign\fP((ev), (b), (x), \fBEV_SIGNAL\fP|\fBEV_PERSIST\fP, cb, (arg))" +.br +.ti -1c +.RI "#define \fBevsignal_new\fP(b, x, cb, arg) \fBevent_new\fP((b), (x), \fBEV_SIGNAL\fP|\fBEV_PERSIST\fP, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBevsignal_del\fP(ev) \fBevent_del\fP(ev)" +.br +.ti -1c +.RI "#define \fBevsignal_pending\fP(ev, tv) \fBevent_pending\fP((ev), \fBEV_SIGNAL\fP, (tv))" +.br +.ti -1c +.RI "#define \fBevsignal_initialized\fP(ev) \fBevent_initialized\fP(ev)" +.br +.in -1c +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef int(* \fBevent_base_foreach_event_cb\fP) (const struct \fBevent_base\fP *, const struct \fBevent\fP *, void *)" +.br +.RI "\fICallback for iterating events in an event base via event_base_foreach_event\&. \fP" +.ti -1c +.RI "typedef void(* \fBevent_callback_fn\fP) (\fBevutil_socket_t\fP, short, void *)" +.br +.RI "\fIA callback function for an event\&. \fP" +.ti -1c +.RI "typedef void(* \fBevent_fatal_cb\fP) (int err)" +.br +.RI "\fIA function to be called if Libevent encounters a fatal internal error\&. \fP" +.ti -1c +.RI "typedef void(* \fBevent_finalize_callback_fn\fP) (struct \fBevent\fP *, void *)" +.br +.RI "\fICallback type for event_finalize and event_free_finalize()\&. \fP" +.ti -1c +.RI "typedef void(* \fBevent_log_cb\fP) (int severity, const char *msg)" +.br +.RI "\fIA callback function used to intercept Libevent's log messages\&. \fP" +.in -1c +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBevent_base_config_flag\fP { \fBEVENT_BASE_FLAG_NOLOCK\fP = 0x01, \fBEVENT_BASE_FLAG_IGNORE_ENV\fP = 0x02, \fBEVENT_BASE_FLAG_STARTUP_IOCP\fP = 0x04, \fBEVENT_BASE_FLAG_NO_CACHE_TIME\fP = 0x08, \fBEVENT_BASE_FLAG_EPOLL_USE_CHANGELIST\fP = 0x10, \fBEVENT_BASE_FLAG_PRECISE_TIMER\fP = 0x20 } +.RI "\fIA flag passed to \fBevent_config_set_flag()\fP\&. \fP"" +.br +.ti -1c +.RI "enum \fBevent_method_feature\fP { \fBEV_FEATURE_ET\fP = 0x01, \fBEV_FEATURE_O1\fP = 0x02, \fBEV_FEATURE_FDS\fP = 0x04, \fBEV_FEATURE_EARLY_CLOSE\fP = 0x08 } +.RI "\fIA flag used to describe which features an \fBevent_base\fP (must) provide\&. \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_active\fP (struct \fBevent\fP *ev, int res, short ncalls)" +.br +.RI "\fIMake an event active\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_add\fP (struct \fBevent\fP *ev, const struct timeval *timeout)" +.br +.RI "\fIAdd an event to the set of pending events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_assign\fP (struct \fBevent\fP *, struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *)" +.br +.RI "\fIPrepare a new, already-allocated event structure to be added\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_base_active_by_fd\fP (struct \fBevent_base\fP *base, \fBevutil_socket_t\fP fd, short events)" +.br +.RI "\fIActivates all pending events for the given fd and event mask\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_base_active_by_signal\fP (struct \fBevent_base\fP *base, int sig)" +.br +.RI "\fIActivates all pending signals with a given signal number\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_dispatch\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIEvent dispatching loop\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_base_dump_events\fP (struct \fBevent_base\fP *, FILE *)" +.br +.RI "\fIWrites a human-readable description of all inserted and/or active events to a provided stdio stream\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_foreach_event\fP (struct \fBevent_base\fP *base, \fBevent_base_foreach_event_cb\fP fn, void *arg)" +.br +.RI "\fIIterate over all added or active events events in an event loop, and invoke a given callback on each one\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_base_free\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIDeallocate all memory associated with an \fBevent_base\fP, and free the base\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_base_free_nofinalize\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIAs event_free, but do not run finalizers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_get_features\fP (const struct \fBevent_base\fP *base)" +.br +.RI "\fIReturn a bitmask of the features implemented by an event base\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_get_max_events\fP (struct \fBevent_base\fP *, unsigned int, int)" +.br +.RI "\fIGet the maximum number of events in a given \fBevent_base\fP as specified in the flags\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevent_base_get_method\fP (const struct \fBevent_base\fP *)" +.br +.RI "\fIGet the kernel event notification mechanism used by Libevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_get_npriorities\fP (struct \fBevent_base\fP *eb)" +.br +.RI "\fIGet the number of different event priorities\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_get_num_events\fP (struct \fBevent_base\fP *, unsigned int)" +.br +.RI "\fIGets the number of events in \fBevent_base\fP, as specified in the flags\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent\fP * \fBevent_base_get_running_event\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fIIf called from within the callback for an event, returns that event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_gettimeofday_cached\fP (struct \fBevent_base\fP *base, struct timeval *tv)" +.br +.RI "\fISets 'tv' to the current time (as returned by gettimeofday()), looking at the cached value in 'base' if possible, and calling gettimeofday() or clock_gettime() as appropriate if there is no cached time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_got_break\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIChecks if the event loop was told to abort immediately by \fBevent_base_loopbreak()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_got_exit\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIChecks if the event loop was told to exit by \fBevent_base_loopexit()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const struct timeval * \fBevent_base_init_common_timeout\fP (struct \fBevent_base\fP *base, const struct timeval *duration)" +.br +.RI "\fIPrepare an \fBevent_base\fP to use a large number of timeouts with the same duration\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_loop\fP (struct \fBevent_base\fP *, int)" +.br +.RI "\fIWait for events to become active, and run their callbacks\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_loopbreak\fP (struct \fBevent_base\fP *)" +.br +.RI "\fIAbort the active \fBevent_base_loop()\fP immediately\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_loopcontinue\fP (struct \fBevent_base\fP *)" +.br +.RI "\fITell the active \fBevent_base_loop()\fP to scan for new events immediately\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_loopexit\fP (struct \fBevent_base\fP *, const struct timeval *)" +.br +.RI "\fIExit the event loop after the specified time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBevent_base_new\fP (void)" +.br +.RI "\fICreate and return a new \fBevent_base\fP to use with the rest of Libevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBevent_base_new_with_config\fP (const struct \fBevent_config\fP *)" +.br +.RI "\fIInitialize the event API\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_once\fP (struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *, const struct timeval *)" +.br +.RI "\fISchedule a one-time event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_priority_init\fP (struct \fBevent_base\fP *, int)" +.br +.RI "\fISet the number of different event priorities\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_set\fP (struct \fBevent_base\fP *, struct \fBevent\fP *)" +.br +.RI "\fIAssociate a different event base with an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_base_update_cache_time\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fIUpdate cached_tv in the 'base' to the current time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_config_avoid_method\fP (struct \fBevent_config\fP *cfg, const char *method)" +.br +.RI "\fIEnters an event method that should be avoided into the configuration\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_config_free\fP (struct \fBevent_config\fP *cfg)" +.br +.RI "\fIDeallocates all memory associated with an event configuration object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_config\fP * \fBevent_config_new\fP (void)" +.br +.RI "\fIAllocates a new event configuration object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_config_require_features\fP (struct \fBevent_config\fP *cfg, int feature)" +.br +.RI "\fIEnters a required event method feature that the application demands\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_config_set_flag\fP (struct \fBevent_config\fP *cfg, int flag)" +.br +.RI "\fISets one or more flags to configure what parts of the eventual \fBevent_base\fP will be initialized, and how they'll work\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_config_set_max_dispatch_interval\fP (struct \fBevent_config\fP *cfg, const struct timeval *max_interval, int max_callbacks, int min_priority)" +.br +.RI "\fIRecord an interval and/or a number of callbacks after which the event base should check for new events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_config_set_num_cpus_hint\fP (struct \fBevent_config\fP *cfg, int cpus)" +.br +.RI "\fIRecords a hint for the number of CPUs in the system\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_debug_unassign\fP (struct \fBevent\fP *)" +.br +.RI "\fIWhen debugging mode is enabled, informs Libevent that an event should no longer be considered as assigned\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_del\fP (struct \fBevent\fP *)" +.br +.RI "\fIRemove an event from the set of monitored events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_del_block\fP (struct \fBevent\fP *ev)" +.br +.RI "\fIAs \fBevent_del()\fP, but always blocks while the event's callback is running in another thread, even if the event was constructed with the EV_FINALIZE flag\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_del_noblock\fP (struct \fBevent\fP *ev)" +.br +.RI "\fIAs \fBevent_del()\fP, but never blocks while the event's callback is running in another thread, even if the event was constructed without the EV_FINALIZE flag\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_enable_debug_logging\fP (ev_uint32_t which)" +.br +.RI "\fITurn on debugging logs and have them sent to the default log handler\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_enable_debug_mode\fP (void)" +.br +.RI "\fIEnable some relatively expensive debugging checks in Libevent that would normally be turned off\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_free\fP (struct \fBevent\fP *)" +.br +.RI "\fIDeallocate a struct event * returned by \fBevent_new()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_get_assignment\fP (const struct \fBevent\fP *\fBevent\fP, struct \fBevent_base\fP **base_out, \fBevutil_socket_t\fP *fd_out, short *events_out, \fBevent_callback_fn\fP *callback_out, void **arg_out)" +.br +.RI "\fIExtract \fIall\fP of arguments given to construct a given event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBevent_get_base\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIGet the \fBevent_base\fP associated with an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL \fBevent_callback_fn\fP \fBevent_get_callback\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIReturn the callback assigned to an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void * \fBevent_get_callback_arg\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIReturn the callback argument assigned to an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL short \fBevent_get_events\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIReturn the events (EV_READ, EV_WRITE, etc) assigned to an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL \fBevutil_socket_t\fP \fBevent_get_fd\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIGet the socket or signal assigned to an event, or -1 if the event has no socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_get_priority\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fIReturn the priority of an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL size_t \fBevent_get_struct_event_size\fP (void)" +.br +.RI "\fIReturn the size of struct event that the Libevent library was compiled with\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char ** \fBevent_get_supported_methods\fP (void)" +.br +.RI "\fIGets all event notification mechanisms supported by Libevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevent_get_version\fP (void)" +.br +.RI "\fIGet the Libevent version\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_uint32_t \fBevent_get_version_number\fP (void)" +.br +.RI "\fIReturn a numeric representation of Libevent's version\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_gettime_monotonic\fP (struct \fBevent_base\fP *base, struct timeval *tp)" +.br +.RI "\fIQuery the current monotonic time from a the timer for a struct \fBevent_base\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_initialized\fP (const struct \fBevent\fP *ev)" +.br +.RI "\fITest if an event structure might be initialized\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent\fP * \fBevent_new\fP (struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *)" +.br +.RI "\fIAllocate and asssign a new event structure, ready to be added\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_pending\fP (const struct \fBevent\fP *ev, short events, struct timeval *tv)" +.br +.RI "\fIChecks if a specific event is pending or scheduled\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_priority_set\fP (struct \fBevent\fP *, int)" +.br +.RI "\fIAssign a priority to an event\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_reinit\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fIReinitialize the event base after a fork\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_remove_timer\fP (struct \fBevent\fP *ev)" +.br +.RI "\fIRemove a timer from a pending event without removing the event itself\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void * \fBevent_self_cbarg\fP (void)" +.br +.RI "\fIReturn a value used to specify that the event itself must be used as the callback argument\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_set_fatal_callback\fP (\fBevent_fatal_cb\fP cb)" +.br +.RI "\fIOverride Libevent's behavior in the event of a fatal internal error\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_set_log_callback\fP (\fBevent_log_cb\fP cb)" +.br +.RI "\fIRedirect Libevent's log messages\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_set_mem_functions\fP (void *(*malloc_fn)(size_t sz), void *(*realloc_fn)(void *ptr, size_t sz), void(*free_fn)(void *ptr))" +.br +.RI "\fIOverride the functions that Libevent uses for memory management\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBlibevent_global_shutdown\fP (void)" +.br +.RI "\fIRelease up all globally-allocated resources allocated by Libevent\&. \fP" +.in -1c +.PP +.RI "\fBFinalization functions\fP" +.br +These functions are used to safely tear down an event in a multithreaded application\&. +.PP +If you construct your events with EV_FINALIZE to avoid deadlocks, you will need a way to remove an event in the certainty that it will definitely not be running its callback when you deallocate it and its callback argument\&. +.PP +To do this, call one of event_finalize() or event_free_finalize with 0 for its first argument, the event to tear down as its second argument, and a callback function as its third argument\&. The callback will be invoked as part of the event loop, with the event's priority\&. +.PP +After you call a finalizer function, \fBevent_add()\fP and \fBevent_active()\fP will no longer work on the event, and \fBevent_del()\fP will produce a no-op\&. You must not try to change the event's fields with \fBevent_assign()\fP or \fBevent_set()\fP while the finalize callback is in progress\&. Once the callback has been invoked, you should treat the event structure as containing uninitialized memory\&. +.PP +The event_free_finalize() function frees the event after it's finalized; event_finalize() does not\&. +.PP +A finalizer callback must not make events pending or active\&. It must not add events, activate events, or attempt to 'resucitate' the event being finalized in any way\&. +.PP +THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.PP +\fBReturns:\fP +.RS 4 +0 on succes, -1 on failure\&. +.RE +.PP + +.PP +.in +1c +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_finalize\fP (unsigned, struct \fBevent\fP *, \fBevent_finalize_callback_fn\fP)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_free_finalize\fP (unsigned, struct \fBevent\fP *, \fBevent_finalize_callback_fn\fP)" +.br +.in -1c +.in -1c +.SH "Detailed Description" +.PP +Core functions for waiting for and receiving events, and using event bases\&. + + +.SH "Macro Definition Documentation" +.PP +.SS "#define EV_CLOSED 0x80" + +.PP +Detects connection close events\&. You can use this to detect when a connection has been closed, without having to read all the pending data from a connection\&. +.PP +Not all backends support EV_CLOSED\&. To detect or require it, use the feature flag EV_FEATURE_EARLY_CLOSE\&. +.SS "#define EV_ET 0x20" + +.PP +Select edge-triggered behavior, if supported by the backend\&. +.SS "#define EV_FINALIZE 0x40" + +.PP +If this option is provided, then \fBevent_del()\fP will not block in one thread while waiting for the event callback to complete in another thread\&. To use this option safely, you may need to use event_finalize() or event_free_finalize() in order to safely tear down an event in a multithreaded application\&. See those functions for more information\&. +.PP +THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.SS "#define EV_PERSIST 0x10" + +.PP +Persistent event: won't get removed automatically when activated\&. When a persistent event with a timeout becomes activated, its timeout is reset to 0\&. +.SS "#define EV_TIMEOUT 0x01" + +.PP +Indicates that a timeout has occurred\&. It's not necessary to pass this flag to event_for new()/event_assign() to get a timeout\&. +.SS "#define EVENT_BASE_COUNT_ACTIVE 1U" + +.PP +count the number of active events, which have been triggered\&. +.SS "#define EVENT_BASE_COUNT_ADDED 4U" + +.PP +count the number of events which have been added to event base, including internal events\&. +.SS "#define EVENT_BASE_COUNT_VIRTUAL 2U" + +.PP +count the number of virtual events, which is used to represent an internal condition, other than a pending event, that keeps the loop from exiting\&. +.SS "#define EVENT_MAX_PRIORITIES 256" + +.PP +Largest number of priorities that Libevent can support\&. +.SS "#define EVLOOP_NO_EXIT_ON_EMPTY 0x04" + +.PP +Do not exit the loop because we have no pending events\&. Instead, keep running until \fBevent_base_loopexit()\fP or \fBevent_base_loopbreak()\fP makes us stop\&. +.SS "#define EVLOOP_NONBLOCK 0x02" + +.PP +Do not block: see which events are ready now, run the callbacks of the highest-priority ones, then exit\&. +.SS "#define EVLOOP_ONCE 0x01" + +.PP +Block until we have an active event, then exit once all active events have had their callbacks run\&. +.SS "#define LIBEVENT_VERSION EVENT__VERSION" + +.PP +As event_get_version, but gives the version of Libevent's headers\&. +.SS "#define LIBEVENT_VERSION_NUMBER EVENT__NUMERIC_VERSION" + +.PP +As event_get_version_number, but gives the version number of Libevent's headers\&. +.SH "Typedef Documentation" +.PP +.SS "typedef void(* event_callback_fn) (\fBevutil_socket_t\fP, short, void *)" + +.PP +A callback function for an event\&. It receives three arguments: +.PP +\fBParameters:\fP +.RS 4 +\fIfd\fP An fd or signal +.br +\fIevents\fP One or more EV_* flags +.br +\fIarg\fP A user-supplied argument\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_new()\fP +.RE +.PP + +.SS "typedef void(* event_fatal_cb) (int err)" + +.PP +A function to be called if Libevent encounters a fatal internal error\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_set_fatal_callback\fP +.RE +.PP + +.SS "typedef void(* event_finalize_callback_fn) (struct \fBevent\fP *, void *)" + +.PP +Callback type for event_finalize and event_free_finalize()\&. THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.SS "typedef void(* event_log_cb) (int severity, const char *msg)" + +.PP +A callback function used to intercept Libevent's log messages\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_set_log_callback\fP +.RE +.PP + +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBevent_base_config_flag\fP" + +.PP +A flag passed to \fBevent_config_set_flag()\fP\&. These flags change the behavior of an allocated \fBevent_base\fP\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_config_set_flag()\fP, \fBevent_base_new_with_config()\fP, \fBevent_method_feature\fP +.RE +.PP + +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVENT_BASE_FLAG_NOLOCK \fP\fP +Do not allocate a lock for the event base, even if we have locking set up\&. Setting this option will make it unsafe and nonfunctional to call functions on the base concurrently from multiple threads\&. +.TP +\fB\fIEVENT_BASE_FLAG_IGNORE_ENV \fP\fP +Do not check the EVENT_* environment variables when configuring an \fBevent_base\fP\&. +.TP +\fB\fIEVENT_BASE_FLAG_STARTUP_IOCP \fP\fP +Windows only: enable the IOCP dispatcher at startup\&. If this flag is set then \fBbufferevent_socket_new()\fP and evconn_listener_new() will use IOCP-backed implementations instead of the usual select-based one on Windows\&. +.TP +\fB\fIEVENT_BASE_FLAG_NO_CACHE_TIME \fP\fP +Instead of checking the current time every time the event loop is ready to run timeout callbacks, check after each timeout callback\&. +.TP +\fB\fIEVENT_BASE_FLAG_EPOLL_USE_CHANGELIST \fP\fP +If we are using the epoll backend, this flag says that it is safe to use Libevent's internal change-list code to batch up adds and deletes in order to try to do as few syscalls as possible\&. Setting this flag can make your code run faster, but it may trigger a Linux bug: it is not safe to use this flag if you have any fds cloned by dup() or its variants\&. Doing so will produce strange and hard-to-diagnose bugs\&. +.PP +This flag can also be activated by setting the EVENT_EPOLL_USE_CHANGELIST environment variable\&. +.PP +This flag has no effect if you wind up using a backend other than epoll\&. +.TP +\fB\fIEVENT_BASE_FLAG_PRECISE_TIMER \fP\fP +Ordinarily, Libevent implements its time and timeout code using the fastest monotonic timer that we have\&. If this flag is set, however, we use less efficient more precise timer, assuming one is present\&. +.SS "enum \fBevent_method_feature\fP" + +.PP +A flag used to describe which features an \fBevent_base\fP (must) provide\&. Because of OS limitations, not every Libevent backend supports every possible feature\&. You can use this type with \fBevent_config_require_features()\fP to tell Libevent to only proceed if your \fBevent_base\fP implements a given feature, and you can receive this type from \fBevent_base_get_features()\fP to see which features are available\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEV_FEATURE_ET \fP\fP +Require an event method that allows edge-triggered events with EV_ET\&. +.TP +\fB\fIEV_FEATURE_O1 \fP\fP +Require an event method where having one event triggered among many is [approximately] an O(1) operation\&. This excludes (for example) select and poll, which are approximately O(N) for N equal to the total number of possible events\&. +.TP +\fB\fIEV_FEATURE_FDS \fP\fP +Require an event method that allows file descriptors as well as sockets\&. +.TP +\fB\fIEV_FEATURE_EARLY_CLOSE \fP\fP +Require an event method that allows you to use EV_CLOSED to detect connection close without the necessity of reading all the pending data\&. Methods that do support EV_CLOSED may not be able to provide support on all kernel versions\&. +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL void event_active (struct \fBevent\fP * ev, int res, short ncalls)" + +.PP +Make an event active\&. You can use this function on a pending or a non-pending event to make it active, so that its callback will be run by \fBevent_base_dispatch()\fP or \fBevent_base_loop()\fP\&. +.PP +One common use in multithreaded programs is to wake the thread running \fBevent_base_loop()\fP from another thread\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event to make active\&. +.br +\fIres\fP a set of flags to pass to the event's callback\&. +.br +\fIncalls\fP an obsolete argument: this is ignored\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_add (struct \fBevent\fP * ev, const struct timeval * timeout)" + +.PP +Add an event to the set of pending events\&. The function \fBevent_add()\fP schedules the execution of the event 'ev' when the condition specified by \fBevent_assign()\fP or \fBevent_new()\fP occurs, or when the time specified in timeout has elapesed\&. If atimeout is NULL, no timeout occurs and the function will only be called if a matching event occurs\&. The event in the ev argument must be already initialized by \fBevent_assign()\fP or \fBevent_new()\fP and may not be used in calls to \fBevent_assign()\fP until it is no longer pending\&. +.PP +If the event in the ev argument already has a scheduled timeout, calling \fBevent_add()\fP replaces the old timeout with the new one if tv is non-NULL\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct initialized via \fBevent_assign()\fP or \fBevent_new()\fP +.br +\fItimeout\fP the maximum amount of time to wait for the event, or NULL to wait forever +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_del()\fP, \fBevent_assign()\fP, \fBevent_new()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_assign (struct \fBevent\fP *, struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *)" + +.PP +Prepare a new, already-allocated event structure to be added\&. The function \fBevent_assign()\fP prepares the event structure ev to be used in future calls to \fBevent_add()\fP and \fBevent_del()\fP\&. Unlike \fBevent_new()\fP, it doesn't allocate memory itself: it requires that you have already allocated a struct event, probably on the heap\&. Doing this will typically make your code depend on the size of the event structure, and thereby create incompatibility with future versions of Libevent\&. +.PP +The easiest way to avoid this problem is just to use \fBevent_new()\fP and \fBevent_free()\fP instead\&. +.PP +A slightly harder way to future-proof your code is to use \fBevent_get_struct_event_size()\fP to determine the required size of an event at runtime\&. +.PP +Note that it is NOT safe to call this function on an event that is active or pending\&. Doing so WILL corrupt internal data structures in Libevent, and lead to strange, hard-to-diagnose bugs\&. You \fIcan\fP use event_assign to change an existing event, but only if it is not active or pending! +.PP +The arguments for this function, and the behavior of the events that it makes, are as for \fBevent_new()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct to be modified +.br +\fIbase\fP the event base to which ev should be attached\&. +.br +\fIfd\fP the file descriptor to be monitored +.br +\fIevents\fP desired events to monitor; can be EV_READ and/or EV_WRITE +.br +\fIcallback\fP callback function to be invoked when the event occurs +.br +\fIcallback_arg\fP an argument to be passed to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if success, or -1 on invalid arguments\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_new()\fP, \fBevent_add()\fP, \fBevent_del()\fP, \fBevent_base_once()\fP, \fBevent_get_struct_event_size()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_base_active_by_fd (struct \fBevent_base\fP * base, \fBevutil_socket_t\fP fd, short events)" + +.PP +Activates all pending events for the given fd and event mask\&. This function activates pending events only\&. Events which have not been added will not become active\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the \fBevent_base\fP on which to activate the events\&. +.br +\fIfd\fP An fd to active events on\&. +.br +\fIevents\fP One or more of EV_{READ,WRITE}\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_base_active_by_signal (struct \fBevent_base\fP * base, int sig)" + +.PP +Activates all pending signals with a given signal number\&. This function activates pending events only\&. Events which have not been added will not become active\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the \fBevent_base\fP on which to activate the events\&. +.br +\fIfd\fP The signal to active events on\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_dispatch (struct \fBevent_base\fP *)" + +.PP +Event dispatching loop\&. This loop will run the event base until either there are no more pending or active, or until something calls \fBevent_base_loopbreak()\fP or \fBevent_base_loopexit()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP or \fBevent_base_new_with_config()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, -1 if an error occurred, or 1 if we exited because no events were pending or active\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loop()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_base_dump_events (struct \fBevent_base\fP *, FILE *)" + +.PP +Writes a human-readable description of all inserted and/or active events to a provided stdio stream\&. This is intended for debugging; its format is not guaranteed to be the same between libevent versions\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP An \fBevent_base\fP on which to scan the events\&. +.br +\fIoutput\fP A stdio file to write on\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_foreach_event (struct \fBevent_base\fP * base, \fBevent_base_foreach_event_cb\fP fn, void * arg)" + +.PP +Iterate over all added or active events events in an event loop, and invoke a given callback on each one\&. The callback must not call any function that modifies the event base, that modifies any event in the event base, or that adds or removes any event to the event base\&. Doing so is unsupported and will lead to undefined behavior -- likely, to crashes\&. +.PP +\fBevent_base_foreach_event()\fP holds a lock on the \fBevent_base()\fP for the whole time it's running: slow callbacks are not advisable\&. +.PP +Note that Libevent adds some events of its own to make pieces of its functionality work\&. You must not assume that the only events you'll encounter will be the ones you added yourself\&. +.PP +The callback function must return 0 to continue iteration, or some other integer to stop iterating\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP An \fBevent_base\fP on which to scan the events\&. +.br +\fIfn\fP A callback function to receive the events\&. +.br +\fIarg\fP An argument passed to the callback function\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if we iterated over every event, or the value returned by the callback function if the loop exited early\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_base_free (struct \fBevent_base\fP *)" + +.PP +Deallocate all memory associated with an \fBevent_base\fP, and free the base\&. Note that this function will not close any fds or free any memory passed to event_new as the argument to callback\&. +.PP +If there are any pending finalizer callbacks, this function will invoke them\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP an \fBevent_base\fP to be freed +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_base_free_nofinalize (struct \fBevent_base\fP *)" + +.PP +As event_free, but do not run finalizers\&. THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.SS "EVENT2_EXPORT_SYMBOL int event_base_get_features (const struct \fBevent_base\fP * base)" + +.PP +Return a bitmask of the features implemented by an event base\&. This will be a bitwise OR of one or more of the values of event_method_feature +.PP +\fBSee also:\fP +.RS 4 +\fBevent_method_feature\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_get_max_events (struct \fBevent_base\fP *, unsigned int, int)" + +.PP +Get the maximum number of events in a given \fBevent_base\fP as specified in the flags\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP +.br +\fIflags\fP a bitwise combination of the kinds of events to aggregate counts for +.br +\fIclear\fP option used to reset the maximum count\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of events specified in the flags +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const char* event_base_get_method (const struct \fBevent_base\fP *)" + +.PP +Get the kernel event notification mechanism used by Libevent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +a string identifying the kernel event mechanism (kqueue, epoll, etc\&.) +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_get_npriorities (struct \fBevent_base\fP * eb)" + +.PP +Get the number of different event priorities\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +Number of different event priorities +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_priority_init()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_get_num_events (struct \fBevent_base\fP *, unsigned int)" + +.PP +Gets the number of events in \fBevent_base\fP, as specified in the flags\&. Since event base has some internal events added to make some of its functionalities work, EVENT_BASE_COUNT_ADDED may return more than the number of events you added using \fBevent_add()\fP\&. +.PP +If you pass EVENT_BASE_COUNT_ACTIVE and EVENT_BASE_COUNT_ADDED together, an active event will be counted twice\&. However, this might not be the case in future libevent versions\&. The return value is an indication of the work load, but the user shouldn't rely on the exact value as this may change in the future\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP +.br +\fIflags\fP a bitwise combination of the kinds of events to aggregate counts for +.RE +.PP +\fBReturns:\fP +.RS 4 +the number of events specified in the flags +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent\fP* event_base_get_running_event (struct \fBevent_base\fP * base)" + +.PP +If called from within the callback for an event, returns that event\&. The behavior of this function is not defined when called from outside the callback function for an event\&. +.SS "EVENT2_EXPORT_SYMBOL int event_base_gettimeofday_cached (struct \fBevent_base\fP * base, struct timeval * tv)" + +.PP +Sets 'tv' to the current time (as returned by gettimeofday()), looking at the cached value in 'base' if possible, and calling gettimeofday() or clock_gettime() as appropriate if there is no cached time\&. Generally, this value will only be cached while actually processing event callbacks, and may be very inaccuate if your callbacks take a long time to execute\&. +.PP +Returns 0 on success, negative on failure\&. +.SS "EVENT2_EXPORT_SYMBOL int event_base_got_break (struct \fBevent_base\fP *)" + +.PP +Checks if the event loop was told to abort immediately by \fBevent_base_loopbreak()\fP\&. This function will return true for an \fBevent_base\fP at every point after \fBevent_base_loopbreak()\fP is called, until the event loop is next entered\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_init()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +true if \fBevent_base_loopbreak()\fP was called on this event base, or 0 otherwise +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopbreak()\fP +.PP +\fBevent_base_got_exit()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_got_exit (struct \fBevent_base\fP *)" + +.PP +Checks if the event loop was told to exit by \fBevent_base_loopexit()\fP\&. This function will return true for an \fBevent_base\fP at every point after \fBevent_loopexit()\fP is called, until the event loop is next entered\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_init()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +true if \fBevent_base_loopexit()\fP was called on this event base, or 0 otherwise +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopexit()\fP +.PP +\fBevent_base_got_break()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const struct timeval* event_base_init_common_timeout (struct \fBevent_base\fP * base, const struct timeval * duration)" + +.PP +Prepare an \fBevent_base\fP to use a large number of timeouts with the same duration\&. Libevent's default scheduling algorithm is optimized for having a large number of timeouts with their durations more or less randomly distributed\&. But if you have a large number of timeouts that all have the same duration (for example, if you have a large number of connections that all have a 10-second timeout), then you can improve Libevent's performance by telling Libevent about it\&. +.PP +To do this, call this function with the common duration\&. It will return a pointer to a different, opaque timeout value\&. (Don't depend on its actual contents!) When you use this timeout value in \fBevent_add()\fP, Libevent will schedule the event more efficiently\&. +.PP +(This optimization probably will not be worthwhile until you have thousands or tens of thousands of events with the same timeout\&.) +.SS "EVENT2_EXPORT_SYMBOL int event_base_loop (struct \fBevent_base\fP *, int)" + +.PP +Wait for events to become active, and run their callbacks\&. This is a more flexible version of \fBevent_base_dispatch()\fP\&. +.PP +By default, this loop will run the event base until either there are no more pending or active events, or until something calls \fBevent_base_loopbreak()\fP or \fBevent_base_loopexit()\fP\&. You can override this behavior with the 'flags' argument\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP or \fBevent_base_new_with_config()\fP +.br +\fIflags\fP any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, -1 if an error occurred, or 1 if we exited because no events were pending or active\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopexit()\fP, \fBevent_base_dispatch()\fP, \fBEVLOOP_ONCE\fP, \fBEVLOOP_NONBLOCK\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_loopbreak (struct \fBevent_base\fP *)" + +.PP +Abort the active \fBevent_base_loop()\fP immediately\&. \fBevent_base_loop()\fP will abort the loop after the next event is completed; \fBevent_base_loopbreak()\fP is typically invoked from this event's callback\&. This behavior is analogous to the 'break;' statement\&. +.PP +Subsequent invocations of \fBevent_base_loop()\fP will proceed normally\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_init()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopexit()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_loopcontinue (struct \fBevent_base\fP *)" + +.PP +Tell the active \fBevent_base_loop()\fP to scan for new events immediately\&. Calling this function makes the currently active \fBevent_base_loop()\fP start the loop over again (scanning for new events) after the current event callback finishes\&. If the event loop is not running, this function has no effect\&. +.PP +\fBevent_base_loopbreak()\fP is typically invoked from this event's callback\&. This behavior is analogous to the 'continue;' statement\&. +.PP +Subsequent invocations of event loop will proceed normally\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_init()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopbreak()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_loopexit (struct \fBevent_base\fP *, const struct timeval *)" + +.PP +Exit the event loop after the specified time\&. The next \fBevent_base_loop()\fP iteration after the given timer expires will complete normally (handling all queued events) then exit without blocking for events again\&. +.PP +Subsequent invocations of \fBevent_base_loop()\fP will proceed normally\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_init()\fP +.br +\fItv\fP the amount of time after which the loop should terminate, or NULL to exit after running all currently active events\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopbreak()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP* event_base_new (void)" + +.PP +Create and return a new \fBevent_base\fP to use with the rest of Libevent\&. +.PP +\fBReturns:\fP +.RS 4 +a new \fBevent_base\fP on success, or NULL on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_free()\fP, \fBevent_base_new_with_config()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP* event_base_new_with_config (const struct \fBevent_config\fP *)" + +.PP +Initialize the event API\&. Use \fBevent_base_new_with_config()\fP to initialize a new event base, taking the specified configuration under consideration\&. The configuration object can currently be used to avoid certain event notification mechanisms\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP the event configuration object +.RE +.PP +\fBReturns:\fP +.RS 4 +an initialized \fBevent_base\fP that can be used to registering events, or NULL if no event base can be created with the requested \fBevent_config\fP\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_new()\fP, \fBevent_base_free()\fP, \fBevent_init()\fP, \fBevent_assign()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_once (struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *, const struct timeval *)" + +.PP +Schedule a one-time event\&. The function \fBevent_base_once()\fP is similar to \fBevent_new()\fP\&. However, it schedules a callback to be called exactly once, and does not require the caller to prepare an event structure\&. +.PP +Note that in Libevent 2\&.0 and earlier, if the event is never triggered, the internal memory used to hold it will never be freed\&. In Libevent 2\&.1, the internal memory will get freed by \fBevent_base_free()\fP if the event is never triggered\&. The 'arg' value, however, will not get freed in either case--you'll need to free that on your own if you want it to go away\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP an \fBevent_base\fP +.br +\fIfd\fP a file descriptor to monitor, or -1 for no fd\&. +.br +\fIevents\fP \fBevent(s)\fP to monitor; can be any of EV_READ | EV_WRITE, or EV_TIMEOUT +.br +\fIcallback\fP callback function to be invoked when the event occurs +.br +\fIarg\fP an argument to be passed to the callback function +.br +\fItimeout\fP the maximum amount of time to wait for the event\&. NULL makes an EV_READ/EV_WRITE event make forever; NULL makes an EV_TIMEOUT event succees immediately\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_priority_init (struct \fBevent_base\fP *, int)" + +.PP +Set the number of different event priorities\&. By default Libevent schedules all active events with the same priority\&. However, some time it is desirable to process some events with a higher priority than others\&. For that reason, Libevent supports strict priority queues\&. Active events with a lower priority are always processed before events with a higher priority\&. +.PP +The number of different priorities can be set initially with the \fBevent_base_priority_init()\fP function\&. This function should be called before the first call to \fBevent_base_dispatch()\fP\&. The \fBevent_priority_set()\fP function can be used to assign a priority to an event\&. By default, Libevent assigns the middle priority to all events unless their priority is explicitly set\&. +.PP +Note that urgent-priority events can starve less-urgent events: after running all urgent-priority callbacks, Libevent checks for more urgent events again, before running less-urgent events\&. Less-urgent events will not have their callbacks run until there are no events more urgent than them that want to be active\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the \fBevent_base\fP structure returned by \fBevent_base_new()\fP +.br +\fInpriorities\fP the maximum number of priorities +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_priority_set()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_set (struct \fBevent_base\fP *, struct \fBevent\fP *)" + +.PP +Associate a different event base with an event\&. The event to be associated must not be currently active or pending\&. +.PP +\fBParameters:\fP +.RS 4 +\fIeb\fP the event base +.br +\fIev\fP the event +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_base_update_cache_time (struct \fBevent_base\fP * base)" + +.PP +Update cached_tv in the 'base' to the current time\&. You can use this function is useful for selectively increasing the accuracy of the cached time value in 'base' during callbacks that take a long time to execute\&. +.PP +This function has no effect if the base is currently not in its event loop, or if timeval caching is disabled via EVENT_BASE_FLAG_NO_CACHE_TIME\&. +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_config_avoid_method (struct \fBevent_config\fP * cfg, const char * method)" + +.PP +Enters an event method that should be avoided into the configuration\&. This can be used to avoid event mechanisms that do not support certain file descriptor types, or for debugging to avoid certain event mechanisms\&. An application can make use of multiple event bases to accommodate incompatible file descriptor types\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP the event configuration object +.br +\fImethod\fP the name of the event method to avoid +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_config_free (struct \fBevent_config\fP * cfg)" + +.PP +Deallocates all memory associated with an event configuration object\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP the event configuration object to be freed\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent_config\fP* event_config_new (void)" + +.PP +Allocates a new event configuration object\&. The event configuration object can be used to change the behavior of an event base\&. +.PP +\fBReturns:\fP +.RS 4 +an \fBevent_config\fP object that can be used to store configuration, or NULL if an error is encountered\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_new_with_config()\fP, \fBevent_config_free()\fP, \fBevent_config\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_config_require_features (struct \fBevent_config\fP * cfg, int feature)" + +.PP +Enters a required event method feature that the application demands\&. Note that not every feature or combination of features is supported on every platform\&. Code that requests features should be prepared to handle the case where \fBevent_base_new_with_config()\fP returns NULL, as in: +.PP +.nf + + event_config_require_features(cfg, EV_FEATURE_ET); + base = event_base_new_with_config(cfg); + if (base == NULL) { + // We can't get edge-triggered behavior here\&. + event_config_require_features(cfg, 0); + base = event_base_new_with_config(cfg); + } +.fi +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP the event configuration object +.br +\fIfeature\fP a bitfield of one or more event_method_feature values\&. Replaces values from previous calls to this function\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_method_feature\fP, \fBevent_base_new_with_config()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_config_set_flag (struct \fBevent_config\fP * cfg, int flag)" + +.PP +Sets one or more flags to configure what parts of the eventual \fBevent_base\fP will be initialized, and how they'll work\&. +.PP +\fBSee also:\fP +.RS 4 +event_base_config_flags, \fBevent_base_new_with_config()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_config_set_max_dispatch_interval (struct \fBevent_config\fP * cfg, const struct timeval * max_interval, int max_callbacks, int min_priority)" + +.PP +Record an interval and/or a number of callbacks after which the event base should check for new events\&. By default, the event base will run as many events are as activated at the higest activated priority before checking for new events\&. If you configure it by setting max_interval, it will check the time after each callback, and not allow more than max_interval to elapse before checking for new events\&. If you configure it by setting max_callbacks to a value >= 0, it will run no more than max_callbacks callbacks before checking for new events\&. +.PP +This option can decrease the latency of high-priority events, and avoid priority inversions where multiple low-priority events keep us from polling for high-priority events, but at the expense of slightly decreasing the throughput\&. Use it with caution! +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP The \fBevent_base\fP configuration object\&. +.br +\fImax_interval\fP An interval after which Libevent should stop running callbacks and check for more events, or NULL if there should be no such interval\&. +.br +\fImax_callbacks\fP A number of callbacks after which Libevent should stop running callbacks and check for more events, or -1 if there should be no such limit\&. +.br +\fImin_priority\fP A priority below which max_interval and max_callbacks should not be enforced\&. If this is set to 0, they are enforced for events of every priority; if it's set to 1, they're enforced for events of priority 1 and above, and so on\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_config_set_num_cpus_hint (struct \fBevent_config\fP * cfg, int cpus)" + +.PP +Records a hint for the number of CPUs in the system\&. This is used for tuning thread pools, etc, for optimal performance\&. In Libevent 2\&.0, it is only on Windows, and only when IOCP is in use\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcfg\fP the event configuration object +.br +\fIcpus\fP the number of cpus +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_debug_unassign (struct \fBevent\fP *)" + +.PP +When debugging mode is enabled, informs Libevent that an event should no longer be considered as assigned\&. When debugging mode is not enabled, does nothing\&. +.PP +This function must only be called on a non-added event\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_enable_debug_mode()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_del (struct \fBevent\fP *)" + +.PP +Remove an event from the set of monitored events\&. The function \fBevent_del()\fP will cancel the event in the argument ev\&. If the event has already executed or has never been added the call will have no effect\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct to be removed from the working set +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_add()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_del_block (struct \fBevent\fP * ev)" + +.PP +As \fBevent_del()\fP, but always blocks while the event's callback is running in another thread, even if the event was constructed with the EV_FINALIZE flag\&. THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.SS "EVENT2_EXPORT_SYMBOL int event_del_noblock (struct \fBevent\fP * ev)" + +.PP +As \fBevent_del()\fP, but never blocks while the event's callback is running in another thread, even if the event was constructed without the EV_FINALIZE flag\&. THIS IS AN EXPERIMENTAL API\&. IT MIGHT CHANGE BEFORE THE LIBEVENT 2\&.1 SERIES BECOMES STABLE\&. +.SS "EVENT2_EXPORT_SYMBOL void event_enable_debug_logging (ev_uint32_t which)" + +.PP +Turn on debugging logs and have them sent to the default log handler\&. This is a global setting; if you are going to call it, you must call this before any calls that create an event-base\&. You must call it before any multithreaded use of Libevent\&. +.PP +Debug logs are verbose\&. +.PP +\fBParameters:\fP +.RS 4 +\fIwhich\fP Controls which debug messages are turned on\&. This option is unused for now; for forward compatibility, you must pass in the constant 'EVENT_DBG_ALL' to turn debugging logs on, or 'EVENT_DBG_NONE' to turn debugging logs off\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_enable_debug_mode (void)" + +.PP +Enable some relatively expensive debugging checks in Libevent that would normally be turned off\&. Generally, these checks cause code that would otherwise crash mysteriously to fail earlier with an assertion failure\&. Note that this method MUST be called before any events or event_bases have been created\&. +.PP +Debug mode can currently catch the following errors: An event is re-assigned while it is added Any function is called on a non-assigned event +.PP +Note that debugging mode uses memory to track every event that has been initialized (via event_assign, event_set, or event_new) but not yet released (via event_free or event_debug_unassign)\&. If you want to use debug mode, and you find yourself running out of memory, you will need to use event_debug_unassign to explicitly stop tracking events that are no longer considered set-up\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_debug_unassign()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_free (struct \fBevent\fP *)" + +.PP +Deallocate a struct event * returned by \fBevent_new()\fP\&. If the event is pending or active, first make it non-pending and non-active\&. +.SS "EVENT2_EXPORT_SYMBOL void event_get_assignment (const struct \fBevent\fP * event, struct \fBevent_base\fP ** base_out, \fBevutil_socket_t\fP * fd_out, short * events_out, \fBevent_callback_fn\fP * callback_out, void ** arg_out)" + +.PP +Extract \fIall\fP of arguments given to construct a given event\&. The \fBevent_base\fP is copied into *base_out, the fd is copied into *fd_out, and so on\&. +.PP +If any of the '_out' arguments is NULL, it will be ignored\&. +.SS "EVENT2_EXPORT_SYMBOL int event_get_priority (const struct \fBevent\fP * ev)" + +.PP +Return the priority of an event\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_priority_init()\fP, \fBevent_get_priority()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL size_t event_get_struct_event_size (void)" + +.PP +Return the size of struct event that the Libevent library was compiled with\&. This will be NO GREATER than sizeof(struct event) if you're running with the same version of Libevent that your application was built with, but otherwise might not\&. +.PP +Note that it might be SMALLER than sizeof(struct event) if some future version of Libevent adds extra padding to the end of struct event\&. We might do this to help ensure ABI-compatibility between different versions of Libevent\&. +.SS "EVENT2_EXPORT_SYMBOL const char** event_get_supported_methods (void)" + +.PP +Gets all event notification mechanisms supported by Libevent\&. This functions returns the event mechanism in order preferred by Libevent\&. Note that this list will include all backends that Libevent has compiled-in support for, and will not necessarily check your OS to see whether it has the required resources\&. +.PP +\fBReturns:\fP +.RS 4 +an array with pointers to the names of support methods\&. The end of the array is indicated by a NULL pointer\&. If an error is encountered NULL is returned\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const char* event_get_version (void)" + +.PP +Get the Libevent version\&. Note that this will give you the version of the library that you're currently linked against, not the version of the headers that you've compiled against\&. +.PP +\fBReturns:\fP +.RS 4 +a string containing the version number of Libevent +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL ev_uint32_t event_get_version_number (void)" + +.PP +Return a numeric representation of Libevent's version\&. Note that this will give you the version of the library that you're currently linked against, not the version of the headers you've used to compile\&. +.PP +The format uses one byte each for the major, minor, and patchlevel parts of the version number\&. The low-order byte is unused\&. For example, version 2\&.0\&.1-alpha has a numeric representation of 0x02000100 +.SS "EVENT2_EXPORT_SYMBOL int event_initialized (const struct \fBevent\fP * ev)" + +.PP +Test if an event structure might be initialized\&. The \fBevent_initialized()\fP function can be used to check if an event has been initialized\&. +.PP +Warning: This function is only useful for distinguishing a a zeroed-out piece of memory from an initialized event, it can easily be confused by uninitialized memory\&. Thus, it should ONLY be used to distinguish an initialized event from zero\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event structure to be tested +.RE +.PP +\fBReturns:\fP +.RS 4 +1 if the structure might be initialized, or 0 if it has not been initialized +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent\fP* event_new (struct \fBevent_base\fP *, \fBevutil_socket_t\fP, short, \fBevent_callback_fn\fP, void *)" + +.PP +Allocate and asssign a new event structure, ready to be added\&. The function \fBevent_new()\fP returns a new event that can be used in future calls to \fBevent_add()\fP and \fBevent_del()\fP\&. The fd and events arguments determine which conditions will trigger the event; the callback and callback_arg arguments tell Libevent what to do when the event becomes active\&. +.PP +If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then fd is a file descriptor or socket that should get monitored for readiness to read, readiness to write, or readiness for either operation (respectively)\&. If events contains EV_SIGNAL, then fd is a signal number to wait for\&. If events contains none of those flags, then the event can be triggered only by a timeout or by manual activation with \fBevent_active()\fP: In this case, fd must be -1\&. +.PP +The EV_PERSIST flag can also be passed in the events argument: it makes \fBevent_add()\fP persistent until \fBevent_del()\fP is called\&. +.PP +The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported only by certain backends\&. It tells Libevent to use edge-triggered events\&. +.PP +The EV_TIMEOUT flag has no effect here\&. +.PP +It is okay to have multiple events all listening on the same fds; but they must either all be edge-triggered, or all not be edge triggerd\&. +.PP +When the event becomes active, the event loop will run the provided callbuck function, with three arguments\&. The first will be the provided fd value\&. The second will be a bitfield of the events that triggered: EV_READ, EV_WRITE, or EV_SIGNAL\&. Here the EV_TIMEOUT flag indicates that a timeout occurred, and EV_ET indicates that an edge-triggered event occurred\&. The third event will be the callback_arg pointer that you provide\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the event base to which the event should be attached\&. +.br +\fIfd\fP the file descriptor or signal to be monitored, or -1\&. +.br +\fIevents\fP desired events to monitor: bitfield of EV_READ, EV_WRITE, EV_SIGNAL, EV_PERSIST, EV_ET\&. +.br +\fIcallback\fP callback function to be invoked when the event occurs +.br +\fIcallback_arg\fP an argument to be passed to the callback function +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated struct event that must later be freed with \fBevent_free()\fP\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_free()\fP, \fBevent_add()\fP, \fBevent_del()\fP, \fBevent_assign()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_pending (const struct \fBevent\fP * ev, short events, struct timeval * tv)" + +.PP +Checks if a specific event is pending or scheduled\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct previously passed to \fBevent_add()\fP +.br +\fIevents\fP the requested event type; any of EV_TIMEOUT|EV_READ| EV_WRITE|EV_SIGNAL +.br +\fItv\fP if this field is not NULL, and the event has a timeout, this field is set to hold the time at which the timeout will expire\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +true if the event is pending on any of the events in 'what', (that is to say, it has been added), or 0 if the event is not added\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_priority_set (struct \fBevent\fP *, int)" + +.PP +Assign a priority to an event\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct +.br +\fIpriority\fP the new priority to be assigned +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if an error occurred +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_priority_init()\fP, \fBevent_get_priority()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_reinit (struct \fBevent_base\fP * base)" + +.PP +Reinitialize the event base after a fork\&. Some event mechanisms do not survive across fork\&. The event base needs to be reinitialized with the \fBevent_reinit()\fP function\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the event base that needs to be re-initialized +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if successful, or -1 if some events could not be re-added\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_new()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_remove_timer (struct \fBevent\fP * ev)" + +.PP +Remove a timer from a pending event without removing the event itself\&. If the event has a scheduled timeout, this function unschedules it but leaves the event otherwise pending\&. +.PP +\fBParameters:\fP +.RS 4 +\fIev\fP an event struct initialized via \fBevent_assign()\fP or \fBevent_new()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, or -1 if an error occurrect\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void* event_self_cbarg (void)" + +.PP +Return a value used to specify that the event itself must be used as the callback argument\&. The function \fBevent_new()\fP takes a callback argument which is passed to the event's callback function\&. To specify that the argument to be passed to the callback function is the event that \fBevent_new()\fP returns, pass in the return value of \fBevent_self_cbarg()\fP as the callback argument for \fBevent_new()\fP\&. +.PP +For example: +.PP +.nf + + struct event *ev = event_new(base, sock, events, callback, event_self_cbarg()); +.fi +.PP +.PP +For consistency with \fBevent_new()\fP, it is possible to pass the return value of this function as the callback argument for \fBevent_assign()\fP -- this achieves the same result as passing the event in directly\&. +.PP +\fBReturns:\fP +.RS 4 +a value to be passed as the callback argument to \fBevent_new()\fP or \fBevent_assign()\fP\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevent_new()\fP, \fBevent_assign()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_set_fatal_callback (\fBevent_fatal_cb\fP cb)" + +.PP +Override Libevent's behavior in the event of a fatal internal error\&. By default, Libevent will call exit(1) if a programming error makes it impossible to continue correct operation\&. This function allows you to supply another callback instead\&. Note that if the function is ever invoked, something is wrong with your program, or with Libevent: any subsequent calls to Libevent may result in undefined behavior\&. +.PP +Libevent will (almost) always log an EVENT_LOG_ERR message before calling this function; look at the last log message to see why Libevent has died\&. +.SS "EVENT2_EXPORT_SYMBOL void event_set_log_callback (\fBevent_log_cb\fP cb)" + +.PP +Redirect Libevent's log messages\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcb\fP a function taking two arguments: an integer severity between EVENT_LOG_DEBUG and EVENT_LOG_ERR, and a string\&. If cb is NULL, then the default log is used\&. +.RE +.PP +NOTE: The function you provide \fImust not\fP call any other libevent functionality\&. Doing so can produce undefined behavior\&. +.SS "EVENT2_EXPORT_SYMBOL void event_set_mem_functions (void *(*)(size_t sz) malloc_fn, void *(*)(void *ptr, size_t sz) realloc_fn, void(*)(void *ptr) free_fn)" + +.PP +Override the functions that Libevent uses for memory management\&. Usually, Libevent uses the standard libc functions malloc, realloc, and free to allocate memory\&. Passing replacements for those functions to \fBevent_set_mem_functions()\fP overrides this behavior\&. +.PP +Note that all memory returned from Libevent will be allocated by the replacement functions rather than by malloc() and realloc()\&. Thus, if you have replaced those functions, it will not be appropriate to free() memory that you get from Libevent\&. Instead, you must use the free_fn replacement that you provided\&. +.PP +Note also that if you are going to call this function, you should do so before any call to any Libevent function that does allocation\&. Otherwise, those funtions will allocate their memory using malloc(), but then later free it using your provided free_fn\&. +.PP +\fBParameters:\fP +.RS 4 +\fImalloc_fn\fP A replacement for malloc\&. +.br +\fIrealloc_fn\fP A replacement for realloc +.br +\fIfree_fn\fP A replacement for free\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void libevent_global_shutdown (void)" + +.PP +Release up all globally-allocated resources allocated by Libevent\&. This function does not free developer-controlled resources like event_bases, events, bufferevents, listeners, and so on\&. It only releases resources like global locks that there is no other way to free\&. +.PP +It is not actually necessary to call this function before exit: every resource that it frees would be released anyway on exit\&. It mainly exists so that resource-leak debugging tools don't see Libevent as holding resources at exit\&. +.PP +You should only call this function when no other Libevent functions will be invoked -- e\&.g\&., when cleanly exiting a program\&. +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/event_base.3 b/static/netbsd/man3/event_base.3 new file mode 100644 index 00000000..d607f1b8 --- /dev/null +++ b/static/netbsd/man3/event_base.3 @@ -0,0 +1,29 @@ +.TH "event_base" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event_base \- Structure to hold information and state for a Libevent dispatch loop\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Structure to hold information and state for a Libevent dispatch loop\&. + +The \fBevent_base\fP lies at the center of Libevent; every application will have one\&. It keeps track of all pending and active events, and notifies your application of the active ones\&. +.PP +This is an opaque structure; you can allocate one using \fBevent_base_new()\fP or \fBevent_base_new_with_config()\fP\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_new()\fP, \fBevent_base_free()\fP, \fBevent_base_loop()\fP, \fBevent_base_new_with_config()\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/event_compat.h.3 b/static/netbsd/man3/event_compat.h.3 new file mode 100644 index 00000000..4dcdcb0f --- /dev/null +++ b/static/netbsd/man3/event_compat.h.3 @@ -0,0 +1,298 @@ +.TH "event2/event_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/event_compat.h \- Potentially non-threadsafe versions of the functions in \fBevent\&.h\fP: provided only for backwards compatibility\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVENT_FD\fP(ev) ((int)\fBevent_get_fd\fP(ev))" +.br +.ti -1c +.RI "#define \fBEVENT_SIGNAL\fP(ev) \fBevent_get_signal\fP(ev)" +.br +.ti -1c +.RI "#define \fBevsignal_set\fP(ev, x, cb, arg) \fBevent_set\fP((ev), (x), \fBEV_SIGNAL\fP|\fBEV_PERSIST\fP, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBevtimer_set\fP(ev, cb, arg) \fBevent_set\fP((ev), \-1, 0, (cb), (arg))" +.br +.in -1c +.PP +.RI "\fBtimeout_* macros\fP" +.br + +.PP +\fBDeprecated\fP +.RS 4 +These macros are deprecated because their naming is inconsistent with the rest of Libevent\&. +.RE +.PP +Use the evtimer_* macros instead\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBtimeout_add\fP(ev, tv) \fBevent_add\fP((ev), (tv))" +.br +.ti -1c +.RI "#define \fBtimeout_set\fP(ev, cb, arg) \fBevent_set\fP((ev), \-1, 0, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBtimeout_del\fP(ev) \fBevent_del\fP(ev)" +.br +.ti -1c +.RI "#define \fBtimeout_pending\fP(ev, tv) \fBevent_pending\fP((ev), \fBEV_TIMEOUT\fP, (tv))" +.br +.ti -1c +.RI "#define \fBtimeout_initialized\fP(ev) \fBevent_initialized\fP(ev)" +.br +.in -1c +.in -1c +.PP +.RI "\fBsignal_* macros\fP" +.br + +.PP +\fBDeprecated\fP +.RS 4 +These macros are deprecated because their naming is inconsistent with the rest of Libevent\&. +.RE +.PP +Use the evsignal_* macros instead\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBsignal_add\fP(ev, tv) \fBevent_add\fP((ev), (tv))" +.br +.ti -1c +.RI "#define \fBsignal_set\fP(ev, x, cb, arg) \fBevent_set\fP((ev), (x), \fBEV_SIGNAL\fP|\fBEV_PERSIST\fP, (cb), (arg))" +.br +.ti -1c +.RI "#define \fBsignal_del\fP(ev) \fBevent_del\fP(ev)" +.br +.ti -1c +.RI "#define \fBsignal_pending\fP(ev, tv) \fBevent_pending\fP((ev), \fBEV_SIGNAL\fP, (tv))" +.br +.ti -1c +.RI "#define \fBsignal_initialized\fP(ev) \fBevent_initialized\fP(ev)" +.br +.in -1c +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_dispatch\fP (void)" +.br +.RI "\fILoop to process events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevent_get_method\fP (void)" +.br +.RI "\fIGet the kernel event notification mechanism used by Libevent\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBevent_init\fP (void)" +.br +.RI "\fIInitialize the event API\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_loop\fP (int)" +.br +.RI "\fIHandle events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_loopbreak\fP (void)" +.br +.RI "\fIAbort the active \fBevent_loop()\fP immediately\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_loopexit\fP (const struct timeval *)" +.br +.RI "\fIExit the event loop after the specified time\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_once\fP (\fBevutil_socket_t\fP, short, void(*)(\fBevutil_socket_t\fP, short, void *), void *, const struct timeval *)" +.br +.RI "\fISchedule a one-time event to occur\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevent_priority_init\fP (int)" +.br +.RI "\fISet the number of different event priorities\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevent_set\fP (struct \fBevent\fP *, \fBevutil_socket_t\fP, short, void(*)(\fBevutil_socket_t\fP, short, void *), void *)" +.br +.RI "\fIPrepare an event structure to be added\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Potentially non-threadsafe versions of the functions in \fBevent\&.h\fP: provided only for backwards compatibility\&. + +In the oldest versions of Libevent, \fBevent_base\fP was not a first-class structure\&. Instead, there was a single event base that every function manipulated\&. Later, when separate event bases were added, the old functions that didn't take an \fBevent_base\fP argument needed to work by manipulating the 'current' event base\&. This could lead to thread-safety issues, and obscure, hard-to-diagnose bugs\&. +.PP +\fBDeprecated\fP +.RS 4 +All functions in this file are by definition deprecated\&. +.RE +.PP + +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL int event_dispatch (void)" + +.PP +Loop to process events\&. Like \fBevent_base_dispatch()\fP, but uses the 'current' base\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it is easily confused by multiple calls to \fBevent_init()\fP, and because it is not safe for multithreaded use\&. The replacement is \fBevent_base_dispatch()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_dispatch()\fP, \fBevent_init()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const char* event_get_method (void)" + +.PP +Get the kernel event notification mechanism used by Libevent\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is obsolete, and has been replaced by \fBevent_base_get_method()\fP\&. Its use is deprecated because it relies on the 'current' base configured by \fBevent_init()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_get_method()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP* event_init (void)" + +.PP +Initialize the event API\&. The event API needs to be initialized with \fBevent_init()\fP before it can be used\&. Sets the global current base that gets used for events that have no base associated with them\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it replaces the 'current' \fBevent_base\fP, and is totally unsafe for multithreaded use\&. The replacement is \fBevent_base_new()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_set()\fP, \fBevent_base_new()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_loop (int)" + +.PP +Handle events\&. This function behaves like \fBevent_base_loop()\fP, but uses the 'current' base +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loop()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loop()\fP, \fBevent_init()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_loopbreak (void)" + +.PP +Abort the active \fBevent_loop()\fP immediately\&. This function behaves like event_base_loopbreakt(), except that it uses the 'current' base\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loopbreak()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_loopbreak()\fP, \fBevent_init()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_loopexit (const struct timeval *)" + +.PP +Exit the event loop after the specified time\&. This function behaves like \fBevent_base_loopexit()\fP, except that it uses the 'current' base\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it uses the event base from the last call to event_init, and is therefore not safe for multithreaded use\&. The replacement is \fBevent_base_loopexit()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_init\fP, \fBevent_base_loopexit()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_once (\fBevutil_socket_t\fP, short, void(*)(\fBevutil_socket_t\fP, short, void *), void *, const struct timeval *)" + +.PP +Schedule a one-time event to occur\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is obsolete, and has been replaced by \fBevent_base_once()\fP\&. Its use is deprecated because it relies on the 'current' base configured by \fBevent_init()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_once()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int event_priority_init (int)" + +.PP +Set the number of different event priorities\&. +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated because it is easily confused by multiple calls to \fBevent_init()\fP, and because it is not safe for multithreaded use\&. The replacement is \fBevent_base_priority_init()\fP\&. +.RE +.PP +.PP +\fBSee also:\fP +.RS 4 +\fBevent_base_priority_init()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void event_set (struct \fBevent\fP *, \fBevutil_socket_t\fP, short, void(*)(\fBevutil_socket_t\fP, short, void *), void *)" + +.PP +Prepare an event structure to be added\&. +.PP +\fBDeprecated\fP +.RS 4 +\fBevent_set()\fP is not recommended for new code, because it requires a subsequent call to \fBevent_base_set()\fP to be safe under most circumstances\&. Use \fBevent_assign()\fP or \fBevent_new()\fP instead\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/event_config.3 b/static/netbsd/man3/event_config.3 new file mode 100644 index 00000000..e723bacf --- /dev/null +++ b/static/netbsd/man3/event_config.3 @@ -0,0 +1,27 @@ +.TH "event_config" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event_config \- Configuration for an \fBevent_base\fP\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Configuration for an \fBevent_base\fP\&. + +There are many options that can be used to alter the behavior and implementation of an \fBevent_base\fP\&. To avoid having to pass them all in a complex many-argument constructor, we provide an abstract data type wrhere you set up configation information before passing it to \fBevent_base_new_with_config()\fP\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevent_config_new()\fP, \fBevent_config_free()\fP, \fBevent_base_new_with_config()\fP, \fBevent_config_avoid_method()\fP, \fBevent_config_require_features()\fP, \fBevent_config_set_flag()\fP, \fBevent_config_set_num_cpus_hint()\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evthread_condition_callbacks.3 b/static/netbsd/man3/evthread_condition_callbacks.3 new file mode 100644 index 00000000..c6e7632c --- /dev/null +++ b/static/netbsd/man3/evthread_condition_callbacks.3 @@ -0,0 +1,68 @@ +.TH "evthread_condition_callbacks" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evthread_condition_callbacks \- This structure describes the interface a threading library uses for condition variables\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "void *(* \fBalloc_condition\fP )(unsigned condtype)" +.br +.RI "\fIFunction to allocate and initialize a new condition variable\&. \fP" +.ti -1c +.RI "int \fBcondition_api_version\fP" +.br +.RI "\fIThe current version of the conditions API\&. \fP" +.ti -1c +.RI "void(* \fBfree_condition\fP )(void *cond)" +.br +.RI "\fIFunction to free a condition variable\&. \fP" +.ti -1c +.RI "int(* \fBsignal_condition\fP )(void *cond, int broadcast)" +.br +.RI "\fIFunction to signal a condition variable\&. \fP" +.ti -1c +.RI "int(* \fBwait_condition\fP )(void *cond, void *lock, const struct timeval *timeout)" +.br +.RI "\fIFunction to wait for a condition variable\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +This structure describes the interface a threading library uses for condition variables\&. + +It's used to tell evthread_set_condition_callbacks how to use locking on this platform\&. +.SH "Field Documentation" +.PP +.SS "void*(* evthread_condition_callbacks::alloc_condition) (unsigned condtype)" + +.PP +Function to allocate and initialize a new condition variable\&. Returns the condition variable on success, and NULL on failure\&. The 'condtype' argument will be 0 with this API version\&. +.SS "int evthread_condition_callbacks::condition_api_version" + +.PP +The current version of the conditions API\&. Set this to EVTHREAD_CONDITION_API_VERSION +.SS "void(* evthread_condition_callbacks::free_condition) (void *cond)" + +.PP +Function to free a condition variable\&. +.SS "int(* evthread_condition_callbacks::signal_condition) (void *cond, int broadcast)" + +.PP +Function to signal a condition variable\&. If 'broadcast' is 1, all threads waiting on 'cond' should be woken; otherwise, only on one thread is worken\&. Should return 0 on success, -1 on failure\&. This function will only be called while holding the associated lock for the condition\&. +.SS "int(* evthread_condition_callbacks::wait_condition) (void *cond, void *lock, const struct timeval *timeout)" + +.PP +Function to wait for a condition variable\&. The lock 'lock' will be held when this function is called; should be released while waiting for the condition to be come signalled, and should be held again when this function returns\&. If timeout is provided, it is interval of seconds to wait for the event to become signalled; if it is NULL, the function should wait indefinitely\&. +.PP +The function should return -1 on error; 0 if the condition was signalled, or 1 on a timeout\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evthread_lock_callbacks.3 b/static/netbsd/man3/evthread_lock_callbacks.3 new file mode 100644 index 00000000..a31f978a --- /dev/null +++ b/static/netbsd/man3/evthread_lock_callbacks.3 @@ -0,0 +1,74 @@ +.TH "evthread_lock_callbacks" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evthread_lock_callbacks \- This structure describes the interface a threading library uses for locking\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "void *(* \fBalloc\fP )(unsigned locktype)" +.br +.RI "\fIFunction to allocate and initialize new lock of type 'locktype'\&. \fP" +.ti -1c +.RI "void(* \fBfree\fP )(void *\fBlock\fP, unsigned locktype)" +.br +.RI "\fIFuntion to release all storage held in 'lock', which was created with type 'locktype'\&. \fP" +.ti -1c +.RI "int(* \fBlock\fP )(unsigned mode, void *lock)" +.br +.RI "\fIAcquire an already-allocated lock at 'lock' with mode 'mode'\&. \fP" +.ti -1c +.RI "int \fBlock_api_version\fP" +.br +.RI "\fIThe current version of the locking API\&. \fP" +.ti -1c +.RI "unsigned \fBsupported_locktypes\fP" +.br +.RI "\fIWhich kinds of locks does this version of the locking API support? A bitfield of EVTHREAD_LOCKTYPE_RECURSIVE and EVTHREAD_LOCKTYPE_READWRITE\&. \fP" +.ti -1c +.RI "int(* \fBunlock\fP )(unsigned mode, void *\fBlock\fP)" +.br +.RI "\fIRelease a lock at 'lock' using mode 'mode'\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +This structure describes the interface a threading library uses for locking\&. + +It's used to tell \fBevthread_set_lock_callbacks()\fP how to use locking on this platform\&. +.SH "Field Documentation" +.PP +.SS "void*(* evthread_lock_callbacks::alloc) (unsigned locktype)" + +.PP +Function to allocate and initialize new lock of type 'locktype'\&. Returns NULL on failure\&. +.SS "void(* evthread_lock_callbacks::free) (void *\fBlock\fP, unsigned locktype)" + +.PP +Funtion to release all storage held in 'lock', which was created with type 'locktype'\&. +.SS "int(* evthread_lock_callbacks::lock) (unsigned mode, void *lock)" + +.PP +Acquire an already-allocated lock at 'lock' with mode 'mode'\&. Returns 0 on success, and nonzero on failure\&. +.SS "int evthread_lock_callbacks::lock_api_version" + +.PP +The current version of the locking API\&. Set this to EVTHREAD_LOCK_API_VERSION +.SS "unsigned evthread_lock_callbacks::supported_locktypes" + +.PP +Which kinds of locks does this version of the locking API support? A bitfield of EVTHREAD_LOCKTYPE_RECURSIVE and EVTHREAD_LOCKTYPE_READWRITE\&. (Note that RECURSIVE locks are currently mandatory, and READWRITE locks are not currently used\&.) +.SS "int(* evthread_lock_callbacks::unlock) (unsigned mode, void *\fBlock\fP)" + +.PP +Release a lock at 'lock' using mode 'mode'\&. Returns 0 on success, and nonzero on failure\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evutil_addrinfo.3 b/static/netbsd/man3/evutil_addrinfo.3 new file mode 100644 index 00000000..b8427087 --- /dev/null +++ b/static/netbsd/man3/evutil_addrinfo.3 @@ -0,0 +1,48 @@ +.TH "evutil_addrinfo" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evutil_addrinfo \- A definition of struct addrinfo for systems that lack it\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "struct sockaddr * \fBai_addr\fP" +.br +.ti -1c +.RI "size_t \fBai_addrlen\fP" +.br +.ti -1c +.RI "char * \fBai_canonname\fP" +.br +.ti -1c +.RI "int \fBai_family\fP" +.br +.ti -1c +.RI "int \fBai_flags\fP" +.br +.ti -1c +.RI "struct \fBevutil_addrinfo\fP * \fBai_next\fP" +.br +.ti -1c +.RI "int \fBai_protocol\fP" +.br +.ti -1c +.RI "int \fBai_socktype\fP" +.br +.in -1c +.SH "Detailed Description" +.PP +A definition of struct addrinfo for systems that lack it\&. + +(This is just an alias for struct addrinfo if the system defines struct addrinfo\&.) + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/evutil_monotonic_timer.3 b/static/netbsd/man3/evutil_monotonic_timer.3 new file mode 100644 index 00000000..d08a499c --- /dev/null +++ b/static/netbsd/man3/evutil_monotonic_timer.3 @@ -0,0 +1,29 @@ +.TH "evutil_monotonic_timer" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +evutil_monotonic_timer \- Structure to hold information about a monotonic timer\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Structure to hold information about a monotonic timer\&. + +Use this with \fBevutil_configure_monotonic_time()\fP and \fBevutil_gettime_monotonic()\fP\&. +.PP +This is an opaque structure; you can allocate one using \fBevutil_monotonic_timer_new()\fP\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevutil_monotonic_timer_new()\fP, \fBevutil_monotonic_timer_free()\fP, \fBevutil_configure_monotonic_time()\fP, \fBevutil_gettime_monotonic()\fP +.RE +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/example.3 b/static/netbsd/man3/example.3 new file mode 100644 index 00000000..c0637992 --- /dev/null +++ b/static/netbsd/man3/example.3 @@ -0,0 +1,41 @@ +# $NetBSD: example.3,v 1.1.1.1 2012/03/23 21:20:15 christos Exp $ +# +# block all inbound packets. +# +block in from any to any +# +# pass through packets to and from localhost. +# +pass in from 127.0.0.1/32 to 127.0.0.1/32 +# +# allow a variety of individual hosts to send any type of IP packet to any +# other host. +# +pass in from 10.1.3.1/32 to any +pass in from 10.1.3.2/32 to any +pass in from 10.1.3.3/32 to any +pass in from 10.1.3.4/32 to any +pass in from 10.1.3.5/32 to any +pass in from 10.1.0.13/32 to any +pass in from 10.1.1.1/32 to any +pass in from 10.1.2.1/32 to any +# +# +# block all outbound packets. +# +block out from any to any +# +# allow any packets destined for localhost out. +# +pass out from any to 127.0.0.1/32 +# +# allow any host to send any IP packet out to a limited number of hosts. +# +pass out from any to 10.1.3.1/32 +pass out from any to 10.1.3.2/32 +pass out from any to 10.1.3.3/32 +pass out from any to 10.1.3.4/32 +pass out from any to 10.1.3.5/32 +pass out from any to 10.1.0.13/32 +pass out from any to 10.1.1.1/32 +pass out from any to 10.1.2.1/32 diff --git a/static/netbsd/man3/exec.3 b/static/netbsd/man3/exec.3 new file mode 100644 index 00000000..a30ca33d --- /dev/null +++ b/static/netbsd/man3/exec.3 @@ -0,0 +1,292 @@ +.\" $NetBSD: exec.3,v 1.32 2022/01/04 20:01:52 uwe Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 +.\" +.Dd September 1, 2019 +.Dt EXEC 3 +.Os +.Sh NAME +.Nm execl , +.Nm execlp , +.Nm execlpe , +.Nm execle , +.Nm exect , +.Nm execv , +.Nm execvp , +.Nm execvpe +.Nd execute a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Vt extern char **environ; +.Ft int +.Fn execl "const char *path" "const char *arg" ... +.Ft int +.Fn execlp "const char *file" "const char *arg" ... +.Ft int +.Fn execlpe "const char *file" "const char *arg" ... "char *const envp[]" +.Ft int +.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" +.Ft int +.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn execv "const char *path" "char *const argv[]" +.Ft int +.Fn execvp "const char *file" "char *const argv[]" +.Ft int +.Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" +.Sh DESCRIPTION +The +.Fn exec +family of functions replaces the current process image with a +new process image. +The functions described in this manual page are front-ends for the function +.Xr execve 2 . +(See the manual page for +.Xr execve 2 +for detailed information about the replacement of the current process. +The +.Xr script 7 +manual page provides detailed information about the execution of +interpreter scripts.) +.Pp +The initial argument for these functions is the pathname of a file which +is to be executed. +.Pp +The +.Fa "const char *arg" +and subsequent ellipses in the +.Fn execl , +.Fn execlp , +.Fn execlpe , +and +.Fn execle +functions can be thought of as +.Em arg0 , +.Em arg1 , +\&..., +.Em argn . +Together they describe a list of one or more pointers to NUL-terminated +strings that represent the argument list available to the executed program. +The first argument, by convention, should point to the file name associated +with the file being executed. +The list of arguments +.Em must +be terminated by a +.Dv NULL +pointer. +.Pp +The +.Fn exect , +.Fn execv , +.Fn execvp , +and +.Fn execvpe +functions provide an array of pointers to NUL-terminated strings that +represent the argument list available to the new program. +The first argument, by convention, should point to the file name associated +with the file being executed. +The array of pointers +.Sy must +be terminated by a +.Dv NULL +pointer. +.Pp +The +.Fn execle , +.Fn execlpe , +.Fn exect , +and +.Fn execvpe +functions also specify the environment of the executed process by following +the +.Dv NULL +pointer that terminates the list of arguments in the parameter list +or the pointer to the argv array with an additional parameter. +This additional parameter is an array of pointers to NUL-terminated strings +and +.Em must +be terminated by a +.Dv NULL +pointer. +The other functions take the environment for the new process image from the +external variable +.Va environ +in the current process. +.Pp +Some of these functions have special semantics. +.Pp +The functions +.Fn execlp , +.Fn execlpe , +.Fn execvp , +and +.Fn execvpe +will duplicate the actions of the shell in searching for an executable file +if the specified file name does not contain a slash +.Dq Li \&/ +character. +The search path is the path specified in the environment by the +.Ev PATH +variable. +If this variable isn't specified, +.Va _PATH_DEFPATH +from +.In paths.h +is used instead, its value being: +.Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . +In addition, certain errors are treated specially. +.Pp +If permission is denied for a file (the attempted +.Xr execve 2 +returned +.Er EACCES ) , +these functions will continue searching the rest of +the search path. +If no other file is found, however, they will return with the global variable +.Va errno +set to +.Er EACCES . +.Pp +If the header of a file isn't recognized (the attempted +.Xr execve 2 +returned +.Er ENOEXEC ) , +these functions will execute the shell with the path of +the file as its first argument. +(If this attempt fails, no further searching is done.) +.Pp +If the file is currently busy (the attempted +.Xr execve 2 +returned +.Er ETXTBUSY ) , +these functions will sleep for several seconds, +periodically re-attempting to execute the file. +.Pp +The function +.Fn exect +executes a file with the program tracing facilities enabled (see +.Xr ptrace 2 ) . +.Sh RETURN VALUES +If any of the +.Fn exec +functions returns, an error will have occurred. +The return value is \-1, and the global variable +.Va errno +will be set to indicate the error. +.Sh FILES +.Bl -tag -width /bin/sh -compact +.It Pa /bin/sh +The shell. +.El +.Sh COMPATIBILITY +Historically, the default path for the +.Fn execlp +.Fn execlpe , +.Fn execvp , +and +.Fn execvpe +functions was +.Dq Pa :/bin:/usr/bin . +This was changed to improve security and behaviour. +.Pp +The behavior of +.Fn execlp , +.Fn execlpe , +.Fn execvp , +and +.Fn execvpe +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified +by the POSIX standard. +.Pp +Traditionally, the functions +.Fn execlp , +.Fn execlpe , +.Fn execvp , +and +.Fn execvpe +ignored all errors except for the ones described above and +.Er ENOMEM +and +.Er E2BIG , +upon which they returned. +They now return if any error other than the ones described above occurs. +.Sh ERRORS +.Fn execl , +.Fn execle , +.Fn execlp , +.Fn execlpe , +.Fn execvp , +and +.Fn execvpe +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr execve 2 +and +.Xr malloc 3 . +.Pp +.Fn exect +and +.Fn execv +may fail and set +.Va errno +for any of the errors specified for the library function +.Xr execve 2 . +.Sh SEE ALSO +.Xr sh 1 , +.Xr execve 2 , +.Xr fork 2 , +.Xr ptrace 2 , +.Xr environ 7 , +.Xr script 7 +.Sh STANDARDS +.Fn execl , +.Fn execv , +.Fn execle , +.Fn execlp , +and +.Fn execvp +conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn exec +function appeared in +.At v1 . +The +.Fn execlpe +function appeared first in QNX and the +.Fn execvpe +function exists on both +.Nx +and QNX. diff --git a/static/netbsd/man3/exit.3 b/static/netbsd/man3/exit.3 new file mode 100644 index 00000000..bd15f568 --- /dev/null +++ b/static/netbsd/man3/exit.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: exit.3,v 1.17 2019/09/01 19:37:21 sevan Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)exit.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 1, 2019 +.Dt EXIT 3 +.Os +.Sh NAME +.Nm exit +.Nd perform normal program termination +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn exit "int status" +.Sh DESCRIPTION +.Fn exit +terminates a process. +The +.Fa status +values +.Dv EXIT_SUCCESS +and +.Dv EXIT_FAILURE +can be used to indicate successful and unsuccessful +termination, respectively. +.Pp +Before termination it performs the following functions in the +order listed: +.Bl -enum -offset indent +.It +Call the functions registered with the +.Xr atexit 3 +function, in the reverse order of their registration. +.It +Flush all open output streams. +.It +Close all open streams. +.It +Unlink all files created with the +.Xr tmpfile 3 +function. +.El +.Pp +Following this, +.Fn exit +calls +.Xr _exit 2 . +.Sh RESTRICTIONS +Standard C guarantees only that the values zero, +.Dv EXIT_SUCCESS , +and +.Dv EXIT_FAILURE +produce meaningful results. +POSIX extends this to guarantee that the +least significant 8 bits of +.Fa status +are preserved and returned to the parent via +.Xr wait 2 . +Values outside the supported range 0-255 are bitwise-truncated; therefore, +negative values should not be used. +.Sh RETURN VALUES +The +.Fn exit +function +never returns. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr at_quick_exit 3 , +.Xr atexit 3 , +.Xr intro 3 , +.Xr quick_exit 3 , +.Xr tmpfile 3 +.Sh STANDARDS +The +.Fn exit +function +conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn exit +function appeared in +.At v1 . diff --git a/static/netbsd/man3/exp.3 b/static/netbsd/man3/exp.3 new file mode 100644 index 00000000..a871e157 --- /dev/null +++ b/static/netbsd/man3/exp.3 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)exp.3 6.12 (Berkeley) 7/31/91 +.\" $FreeBSD: src/lib/msun/man/exp.3,v 1.24 2008/01/18 21:43:00 das Exp $ +.\" $NetBSD: exp.3,v 1.33 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd January 24, 2024 +.Dt EXP 3 +.Os +.Sh NAME +.Nm exp , +.Nm expf , +.Nm expl , +.\" The sorting error is intentional. exp and expf should be adjacent. +.Nm exp2 , +.Nm exp2f , +.Nm exp2l , +.Nm expm1 , +.Nm expm1f +.Nm expm1l +.Nd exponential functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn exp "double x" +.Ft float +.Fn expf "float x" +.Ft long double +.Fn expf "long double x" +.Ft double +.Fn exp2 "double x" +.Ft float +.Fn exp2f "float x" +.Ft long double +.Fn exp2l "long double x" +.Ft double +.Fn expm1 "double x" +.Ft float +.Fn expm1f "float x" +.Ft long double +.Fn expm1l "long double x" +.Sh DESCRIPTION +The +.Fn exp , +.Fn expf , +and +.Fn expl +functions compute the base +.Ms e +exponential value of the given argument +.Fa x . +.Pp +The +.Fn exp2 , +.Fn exp2f , +and +.Fn exp2l +functions compute the base 2 exponential of the given argument +.Fa x . +.Pp +The +.Fn expm1 , +.Fn expm1f +and +.Fn expm1l +functions compute the value exp(x)\-1 accurately even for tiny argument +.Fa x . +.Sh RETURN VALUES +These functions will return the appropriate computation unless an error +occurs or an argument is out of range. +The functions +.Fn exp +and +.Fn expm1 +detect if the computed value will overflow, +set the global variable +.Va errno +to +.Er ERANGE +and cause a reserved operand fault on a +.Tn VAX . +.Sh SEE ALSO +.Xr math 3 +.Sh STANDARDS +The +.Fn exp +function conforms to +.St -ansiC . +The +.Fn exp2 , +.Fn exp2f , +.Fn exp2l , +.Fn expf , +.Fn expl , +.Fn expm1 , +.Fn expm1f , +and +.Fn expm1l +functions conform to +.St -isoC-99 . +.Sh HISTORY +The +.Fn exp +functions appeared in +.At v1 . +The +.Fn expm1 +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/explicit_memset.3 b/static/netbsd/man3/explicit_memset.3 new file mode 100644 index 00000000..744a810f --- /dev/null +++ b/static/netbsd/man3/explicit_memset.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: explicit_memset.3,v 1.3 2024/11/02 02:43:48 riastradh Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 1, 2024 +.Dt EXPLICIT_MEMSET 3 +.Os +.Sh NAME +.Nm explicit_memset +.Nm memset_explicit +.Nd guarantee writing a byte to a byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn explicit_memset "void *b" "int c" "size_t len" +.Ft void * +.Fn memset_explicit "void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn explicit_memset +and +.Fn memset_explicit +functions write +.Fa len +bytes of value +.Fa c +(converted to an unsigned char) to the string +.Fa b . +They are guaranteed not to be optimized away by the compiler even if +.Fa b +is no longer used and is about to be freed or go out of scope. +.Sh RETURN VALUES +The +.Fn explicit_memset +function returns the original value of +.Fa b . +.Sh EXAMPLES +Create a buffer on the stack for a secret key, use it, and then zero it +in memory before throwing it away. +.Bd -literal -offset indent +void +f(void) +{ + uint8_t key[32]; + + crypto_random(key, sizeof(key)); + do_crypto_stuff(key, sizeof(key)); + \&... + + explicit_memset(key, 0, sizeof(key)); +} +.Ed +.Sh SEE ALSO +.Xr consttime_memequal 3 , +.Xr memset 3 +.Sh STANDARDS +The +.Fn memset_explicit +function conforms to +.St -isoC-2023 . +.Sh HISTORY +The +.Fn explicit_memset +function appeared in +.Nx 7.0 . +The +.Fn memset_explicit +alias was added in +.Nx 11.0 . diff --git a/static/netbsd/man3/extattr.3 b/static/netbsd/man3/extattr.3 new file mode 100644 index 00000000..933b2b85 --- /dev/null +++ b/static/netbsd/man3/extattr.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: extattr.3,v 1.7 2025/03/09 16:33:35 christos Exp $ +.\" +.\" Copyright (c) 2001 Dima Dorfman +.\" Copyright (c) 2011 Emmanuel Dreyfus +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" FreeBSD: src/lib/libc/posix1e/extattr.3,v 1.5 2002/12/12 17:25:53 ru Exp +.\" +.Dd March 9, 2025 +.Dt EXTATTR 3 +.Os +.Sh NAME +.Nm extattr_namespace_to_string , +.Nm extattr_string_to_namespace +.Nd convert an extended attribute namespace identifier to a string and vice versa +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/extattr.h +.Ft int +.Fn extattr_namespace_to_string "int attrnamespace" "char **string" +.Ft int +.Fn extattr_string_to_namespace "const char *string" "int *attrnamespace" +.Sh DESCRIPTION +The +.Fn extattr_namespace_to_string +function converts a VFS extended attribute identifier to a human-readable +string. +The +.Fn extattr_string_to_namespace +converts a human-readable string representing a namespace to a +namespace identifier. +Although a file system may implement arbitrary namespaces, +these functions only support the +.Dv EXTATTR_NAMESPACE_USER +.Pq Dq user +and +.Dv EXTATTR_NAMESPACE_SYSTEM +.Pq Dq system +namespaces, +which are defined in +.Xr extattr 9 . +.Pp +These functions are meant to be used in error reporting and other +interactive tasks. +For example, +instead of printing the integer identifying an extended attribute in +an error message, +a program might use +.Fn extattr_namespace_to_string +to obtain a human-readable representation. +Likewise, +instead of requiring a user to enter the integer representing a namespace, +an interactive program might ask for a name and use +.Fn extattr_string_to_namespace +to get the desired identifier. +.Sh RETURN VALUES +If any of the calls are unsuccessful, the value \-1 is returned +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The requested namespace could not be identified. +.El +.Sh SEE ALSO +.Xr getextattr 1 , +.Xr extattr_get_file 2 , +.Xr extattr_copy_file 3 , +.Xr extattr 9 +.Sh HISTORY +Extended attribute support was developed as part of the +.Tn TrustedBSD +Project, and introduced in +.Fx 5.0 +and +.Nx 3.0 . +It was developed to support security extensions requiring additional labels +to be associated with each file or directory. diff --git a/static/netbsd/man3/extattr_copy_file.3 b/static/netbsd/man3/extattr_copy_file.3 new file mode 100644 index 00000000..30bbab13 --- /dev/null +++ b/static/netbsd/man3/extattr_copy_file.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: extattr_copy_file.3,v 1.4 2021/12/10 19:30:05 andvar Exp $ +.\" +.\" Copyright (c) 2001 Dima Dorfman +.\" Copyright (c) 2011 Emmanuel Dreyfus +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" FreeBSD: src/lib/libc/posix1e/extattr.3,v 1.5 2002/12/12 17:25:53 ru Exp +.\" +.Dd December 16, 2011 +.Dt EXTATTR_COPY_FILE 3 +.Os +.Sh NAME +.Nm extattr_copy_file , +.Nm extattr_copy_fd , +.Nm extattr_copy_link , +.Nm cpxattr , +.Nm fcpxattr , +.Nm lcpxattr +.Nd copy extended attributes from a file to another one +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/extattr.h +.Ft int +.Fn extattr_copy_file "const char *from" "const char *to" "int namespace" +.Ft int +.Fn extattr_copy_fd "int from_fd" "int to_fd" "int namespace" +.Ft int +.Fn extattr_copy_link "const char *from" "const char *to" "int namespace" +.Ft int +.Fn cpxattr "const char *from" "const char *to" +.Ft int +.Fn fcpxattr "int from_fd" "int to_fd" +.Ft int +.Fn lcpxattr "const char *from" "const char *to" +.Sh DESCRIPTION +.Fn extattr_copy_file +copies extended attributes of namespace +.Ar namespace +from a file to another one. +.Fn extattr_copy_fd +does the same using open file descriptors, and +.Fn extattr_copy_link +does the same as +.Fn extattr_copy_file +but operates on symbolic links themselves instead of their targets. +.Pp +.Fn cpxattr , +.Fn fcpxattr , +and +.Fn lcpxattr +respectively work the same was as +.Fn extattr_copy_file , +.Fn extattr_copy_fd , +and +.Fn extattr_copy_link , +but will copy extended attributes from all namespaces accessible to the user, +silently skipping inaccessible namespaces. +.Pp +Please note that none of the extended attribute copying functions are atomic. +.Sh RETURN VALUES +If any of the calls are unsuccessful, the value \-1 is returned +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +Extended attribute copying functions may raise errors produced by +.Xr extattr_list_file 2 +and +.Xr extattr_get_file 2 . +.Sh SEE ALSO +.Xr getextattr 1 , +.Xr extattr_get_file 2 , +.Xr extattr_namespace_to_string 3 , +.Xr extattr 9 +.Sh HISTORY +Extended attribute support was developed as part of the +.Tn TrustedBSD +Project, and introduced in +.Fx 5.0 +and +.Nx 3.0 . +It was developed to support security extensions requiring additional labels +to be associated with each file or directory. diff --git a/static/netbsd/man3/fabs.3 b/static/netbsd/man3/fabs.3 new file mode 100644 index 00000000..d322f427 --- /dev/null +++ b/static/netbsd/man3/fabs.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)fabs.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: fabs.3,v 1.17 2016/03/17 09:44:56 wiz Exp $ +.\" +.Dd March 17, 2016 +.Dt FABS 3 +.Os +.Sh NAME +.Nm fabs , +.Nm fabsf , +.Nm fabsl +.Nd floating-point absolute value functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn fabs "double x" +.Ft float +.Fn fabsf "float x" +.Ft long double +.Fn fabsl "long double x" +.Sh DESCRIPTION +The +.Fn fabs , +.Fn fabsf +and +.Fn fabsl +functions compute the absolute value of a floating-point number +.Fa x . +.Sh RETURN VALUES +Functions of the +.Fn fabs +family return the absolute value of +.Fa x . +.Sh SEE ALSO +.Xr abs 3 , +.Xr ceil 3 , +.Xr floor 3 , +.Xr math 3 , +.Xr rint 3 +.Sh STANDARDS +The +.Fn fabs +function conforms to +.St -ansiC . +The +.Fn fabsf +and +.Fn fabsl +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/fclose.3 b/static/netbsd/man3/fclose.3 new file mode 100644 index 00000000..a6c88980 --- /dev/null +++ b/static/netbsd/man3/fclose.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: fclose.3,v 1.9 2003/08/07 16:43:21 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fclose.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt FCLOSE 3 +.Os +.Sh NAME +.Nm fclose +.Nd close a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fclose "FILE *stream" +.Sh DESCRIPTION +The +.Fn fclose +function +dissociates the named +.Fa stream +from its underlying file or set of functions. +If the stream was being used for output, any buffered data is written +first, using +.Xr fflush 3 . +.Sh RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, +.Dv EOF +is returned and the global variable +.Va errno +is set to indicate the error. +In either case no further access to the stream is possible. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa stream +is not an open stream. +.El +.Pp +The +.Fn fclose +function +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr close 2 +or +.Xr fflush 3 . +.Sh SEE ALSO +.Xr close 2 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr setbuf 3 +.Sh STANDARDS +The +.Fn fclose +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/fdim.3 b/static/netbsd/man3/fdim.3 new file mode 100644 index 00000000..0b10c9b1 --- /dev/null +++ b/static/netbsd/man3/fdim.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/msun/man/fdim.3,v 1.1 2004/06/30 07:04:01 das Exp $ +.\" $NetBSD: fdim.3,v 1.3 2010/03/08 02:35:50 snj Exp $ +.\" +.Dd June 29, 2004 +.Dt FDIM 3 +.Os +.Sh NAME +.Nm fdim , +.Nm fdimf , +.Nm fdiml +.Nd positive difference functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn fdim "double x" "double y" +.Ft float +.Fn fdimf "float x" "float y" +.Ft long double +.Fn fdiml "long double x" "long double y" +.Sh DESCRIPTION +The +.Fn fdim , +.Fn fdimf , +and +.Fn fdiml +functions return the positive difference between +.Fa x +and +.Fa y . +That is, if +.Fa x\- Ns Fa y +is positive, then +.Fa x\- Ns Fa y +is returned. +If either +.Fa x +or +.Fa y +is an \*(Na, then an \*(Na is returned. +Otherwise, the result is +.Li +0.0 . +.Pp +Overflow or underflow may occur iff the exact result is not +representable in the return type. +No other exceptions are raised. +.Sh SEE ALSO +.Xr fabs 3 , +.Xr fmax 3 , +.Xr fmin 3 , +.Xr math 3 +.Sh STANDARDS +The +.Fn fdim , +.Fn fdimf , +and +.Fn fdiml +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 +and +.Nx 5.1 . diff --git a/static/netbsd/man3/feclearexcept.3 b/static/netbsd/man3/feclearexcept.3 new file mode 100644 index 00000000..5e2a6041 --- /dev/null +++ b/static/netbsd/man3/feclearexcept.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: feclearexcept.3,v 1.2 2010/08/07 18:13:12 wiz Exp $ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 8, 2004 +.Dt FECLEAREXCEPT 3 +.Os +.Sh NAME +.Nm feclearexcept , +.Nm fegetexceptflag , +.Nm feraiseexcept , +.Nm fesetexceptflag , +.Nm fetestexcept +.Nd floating-point exception flag manipulation +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn feclearexcept "int excepts" +.Ft int +.Fn fegetexceptflag "fexcept_t *flagp" "int excepts" +.Ft int +.Fn feraiseexcept "int excepts" +.Ft int +.Fn fesetexceptflag "const fexcept_t *flagp" "int excepts" +.Ft int +.Fn fetestexcept "int excepts" +.Sh DESCRIPTION +The +.Fn feclearexcept +routine clears the floating-point exception flags specified by +.Fa excepts , +whereas +.Fn feraiseexcept +raises the specified exceptions. +Raising an exception causes the corresponding flag to be set, +and a +.Dv SIGFPE +is delivered to the process if the exception is unmasked. +.Pp +The +.Fn fetestexcept +function determines which flags are currently set, of those specified by +.Fa excepts . +.Pp +The +.Fn fegetexceptflag +function stores the state of the exception flags specified in +.Fa excepts +in the opaque object pointed to by +.Fa flagp . +Similarly, +.Fn fesetexceptflag +changes the specified exception flags to reflect the state stored in +the object pointed to by +.Fa flagp . +Note that the flags restored with +.Fn fesetexceptflag +must be a (not necessarily proper) subset of the flags recorded by +a prior call to +.Fn fegetexceptflag . +.Pp +For all of these functions, the possible types of exceptions +include those described in +.Xr fenv 3 . +Some architectures may define other types of floating-point exceptions. +.Sh IMPLEMENTATION NOTES +On some architectures, raising an overflow or underflow exception +also causes an inexact exception to be raised. +In these cases, the overflow or underflow will be raised first. +.Pp +The +.Fn fegetexceptflag +and +.Fn fesetexceptflag +routines are preferred to +.Fn fetestexcept +and +.Fn feraiseexcept , +respectively, for saving and restoring exception flags. +The latter do not re-raise exceptions and may preserve +architecture-specific information such as addresses where +exceptions occurred. +.Sh RETURN VALUES +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +and +.Fn fesetexceptflag +functions return 0 upon success, and non-zero otherwise. +The +.Fn fetestexcept +function returns the bitwise OR of the values of the current exception +flags that were requested. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr feholdexcept 3 , +.Xr fenv 3 , +.Xr feupdateenv 3 , +.Xr fpgetsticky 3 +.Sh STANDARDS +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +.Fn fesetexceptflag , +and +.Fn fetestexcept +routines conform to +.St -isoC-99 . +.Sh HISTORY +These functions first appeared in +.Fx 5.3 +and +.Nx 6.0 . diff --git a/static/netbsd/man3/feenableexcept.3 b/static/netbsd/man3/feenableexcept.3 new file mode 100644 index 00000000..06bb28b2 --- /dev/null +++ b/static/netbsd/man3/feenableexcept.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: feenableexcept.3,v 1.1 2010/07/31 21:47:53 joerg Exp $ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 16, 2005 +.Dt FEENABLEEXCEPT 3 +.Os +.Sh NAME +.Nm feenableexcept , +.Nm fedisableexcept , +.Nm fegetexcept +.Nd floating-point exception masking +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn feenableexcept "int excepts" +.Ft int +.Fn fedisableexcept "int excepts" +.Ft int +.Fn fegetexcept "void" +.Sh DESCRIPTION +The +.Fn feenableexcept +and +.Fn fedisableexcept +functions +unmask and mask (respectively) exceptions specified in +.Fa excepts . +The +.Fn fegetexcept +function +returns the current exception mask. +All exceptions are masked by default. +.Pp +Floating-point operations that produce unmasked exceptions will trap, and a +.Dv SIGFPE +will be delivered to the process. +By installing a signal handler for +.Dv SIGFPE , +applications can take appropriate action immediately without +testing the exception flags after every operation. +Note that the trap may not be immediate, but it should occur +before the next floating-point instruction is executed. +.Pp +For all of these functions, the possible types of exceptions +include those described in +.Xr fenv 3 . +Some architectures may define other types of floating-point exceptions. +.Sh RETURN VALUES +The +.Fn feenableexcept , +.Fn fedisableexcept , +and +.Fn fegetexcept +functions return a bitmap of the exceptions that were unmasked +prior to the call. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr feclearexcept 3 , +.Xr feholdexcept 3 , +.Xr fenv 3 , +.Xr feupdateenv 3 +.Sh BUGS +Functions in the standard library may trigger exceptions multiple +times as a result of intermediate computations; +however, they generally do not trigger spurious exceptions. +.Pp +No interface is provided to permit exceptions to be handled in +nontrivial ways. +There is no uniform way for an exception handler to access +information about the exception-causing instruction, or +to determine whether that instruction should be reexecuted +after returning from the handler. diff --git a/static/netbsd/man3/fegetenv.3 b/static/netbsd/man3/fegetenv.3 new file mode 100644 index 00000000..c163b72c --- /dev/null +++ b/static/netbsd/man3/fegetenv.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: fegetenv.3,v 1.2 2010/08/04 18:58:18 wiz Exp $ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 8, 2004 +.Dt FEGETENV 3 +.Os +.Sh NAME +.Nm fegetenv , +.Nm feholdexcept , +.Nm fesetenv , +.Nm feupdateenv +.Nd floating-point environment save and restore +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn fegetenv "fenv_t *envp" +.Ft int +.Fn feholdexcept "fenv_t *envp" +.Ft int +.Fn fesetenv "const fenv_t *envp" +.Ft int +.Fn feupdateenv "const fenv_t *envp" +.Sh DESCRIPTION +The floating-point environment includes exception flags and masks, the +current rounding mode, and other architecture-specific settings. +However, it does not include the floating-point register file. +.Pp +The +.Fn fegetenv +function stores the current floating-point environment in the object +pointed to by +.Fa envp , +whereas +.Fn feholdexcept +saves the current environment, then clears all exception flags +and masks all floating-point exceptions. +.Pp +The +.Fn fesetenv +function restores a previously saved environment. +The +.Fn feupdateenv +function restores a saved environment as well, but it also +raises any exceptions that were set in the environment it +replaces. +.Pp +The +.Fn feholdexcept +function is often used with +.Fn feupdateenv +or +.Fn fesetenv +to suppress spurious exceptions that occur as a result of +intermediate computations. +An example in +.Xr fenv 3 +demonstrates how to do this. +.Sh RETURN VALUES +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions return 0 if they succeed, and non-zero otherwise. +.Sh SEE ALSO +.Xr feclearexcept 3 , +.Xr fenv 3 , +.Xr feraiseexcept 3 , +.Xr fesetenv 3 , +.Xr fetestexcept 3 , +.Xr fpgetmask 3 , +.\"Xr fpgetprec 3 , +.Xr fpsetmask 3 +.\"Xr fpsetprec 3 +.Sh STANDARDS +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 +and +.Nx 6.0 . diff --git a/static/netbsd/man3/fegetround.3 b/static/netbsd/man3/fegetround.3 new file mode 100644 index 00000000..6fd9d779 --- /dev/null +++ b/static/netbsd/man3/fegetround.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: fegetround.3,v 1.1 2010/07/31 21:47:53 joerg Exp $ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 8, 2004 +.Dt FEGETROUND 3 +.Os +.Sh NAME +.Nm fegetround , +.Nm fesetround +.Nd floating-point rounding control +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn fegetround void +.Ft int +.Fn fesetround "int round" +.Sh DESCRIPTION +The +.Fn fegetround +function determines the current floating-point rounding mode, +and the +.Fn fesetround +function sets the current rounding mode to +.Fa round . +The rounding mode is one of +.Dv FE_TONEAREST , FE_DOWNWARD , FE_UPWARD , +or +.Dv FE_TOWARDZERO , +as described in +.Xr fenv 3 . +.Sh RETURN VALUES +The +.Fn fegetround +routine returns the current rounding mode. +The +.Fn fesetround +function returns 0 on success and non-zero otherwise; +however, the present implementation always succeeds. +.Sh SEE ALSO +.Xr fenv 3 , +.Xr fpgetround 3 , +.Xr fpsetround 3 +.Sh STANDARDS +The +.Fn fegetround +and +.Fn fesetround +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 +and +.Nx 6.0 . +They supersede the non-standard +.Xr fpgetround 3 +and +.Xr fpsetround 3 +functions. diff --git a/static/netbsd/man3/fenv.3 b/static/netbsd/man3/fenv.3 new file mode 100644 index 00000000..ea19a535 --- /dev/null +++ b/static/netbsd/man3/fenv.3 @@ -0,0 +1,283 @@ +.\" $NetBSD: fenv.3,v 1.3 2017/07/03 21:32:50 wiz Exp $ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 16, 2005 +.Dt FENV 3 +.Os +.Sh NAME +.Nm feclearexcept , +.Nm fegetexceptflag , +.Nm feraiseexcept , +.Nm fesetexceptflag , +.Nm fetestexcept , +.Nm fegetround , +.Nm fesetround , +.Nm fegetenv , +.Nm feholdexcept , +.Nm fesetenv , +.Nm feupdateenv , +.Nm feenableexcept , +.Nm fedisableexcept , +.Nm fegetexcept +.Nd floating-point environment control +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn feclearexcept "int excepts" +.Ft int +.Fn fegetexceptflag "fexcept_t *flagp" "int excepts" +.Ft int +.Fn feraiseexcept "int excepts" +.Ft int +.Fn fesetexceptflag "const fexcept_t *flagp" "int excepts" +.Ft int +.Fn fetestexcept "int excepts" +.Ft int +.Fn fegetround void +.Ft int +.Fn fesetround "int round" +.Ft int +.Fn fegetenv "fenv_t *envp" +.Ft int +.Fn feholdexcept "fenv_t *envp" +.Ft int +.Fn fesetenv "const fenv_t *envp" +.Ft int +.Fn feupdateenv "const fenv_t *envp" +.Ft int +.Fn feenableexcept "int excepts" +.Ft int +.Fn fedisableexcept "int excepts" +.Ft int +.Fn fegetexcept void +.Sh DESCRIPTION +The +.In fenv.h +routines manipulate the floating-point environment, +which includes the exception flags and rounding modes defined in +.St -ieee754 . +.Ss Exceptions +Exception flags are set as side-effects of floating-point arithmetic +operations and math library routines, and they remain set until +explicitly cleared. +The following macros expand to bit flags of type +.Vt int +representing the five standard floating-point exceptions. +.Bl -tag -width ".Dv FE_DIVBYZERO" +.It Dv FE_DIVBYZERO +A divide-by-zero exception occurs when the program attempts to +divide a finite non-zero number by zero. +.It Dv FE_INEXACT +An inexact exception is raised whenever there is a loss of precision +due to rounding. +.It Dv FE_INVALID +Invalid operation exceptions occur when a program attempts to +perform calculations for which there is no reasonable representable +answer. +For instance, subtraction of infinities, division of zero by zero, +ordered comparison involving \*(Nas, and taking the square root of a +negative number are all invalid operations. +.It Dv FE_OVERFLOW +An overflow exception occurs when the magnitude of the result of a +computation is too large to fit in the destination type. +.It Dv FE_UNDERFLOW +Underflow occurs when the result of a computation is too close to zero +to be represented as a non-zero value in the destination type. +.El +.Pp +Additionally, the +.Dv FE_ALL_EXCEPT +macro expands to the bitwise OR of the above flags and any +architecture-specific flags. +Combinations of these flags are passed to the +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +.Fn fesetexceptflag , +and +.Fn fetestexcept +functions to clear, save, raise, restore, and examine the +processor's floating-point exception flags, respectively. +.Pp +Exceptions may be +.Em unmasked +with +.Fn feenableexcept +and masked with +.Fn fedisableexcept . +Unmasked exceptions cause a trap when they are produced, and +all exceptions are masked by default. +The current mask can be tested with +.Fn fegetexcept . +.Ss Rounding Modes +.St -ieee754 +specifies four rounding modes. +These modes control the direction in which results are rounded +from their exact values in order to fit them into binary +floating-point variables. +The four modes correspond with the following symbolic constants. +.Bl -tag -width ".Dv FE_TOWARDZERO" +.It Dv FE_TONEAREST +Results are rounded to the closest representable value. +If the exact result is exactly half way between two representable +values, the value whose last binary digit is even (zero) is chosen. +This is the default mode. +.It Dv FE_DOWNWARD +Results are rounded towards negative \*[If]. +.It Dv FE_UPWARD +Results are rounded towards positive \*[If]. +.It Dv FE_TOWARDZERO +Results are rounded towards zero. +.El +.Pp +The +.Fn fegetround +and +.Fn fesetround +functions query and set the rounding mode. +.Ss Environment Control +The +.Fn fegetenv +and +.Fn fesetenv +functions save and restore the floating-point environment, +which includes exception flags, the current exception mask, +the rounding mode, and possibly other implementation-specific +state. +The +.Fn feholdexcept +function behaves like +.Fn fegetenv , +but with the additional effect of clearing the exception flags and +installing a +.Em non-stop +mode. +In non-stop mode, floating-point operations will set exception flags +as usual, but no +.Dv SIGFPE +signals will be generated as a result. +Non-stop mode is the default, but it may be altered by +non-standard mechanisms. +.\" XXX Mention fe[gs]etmask() here after the interface is finalized +.\" XXX and ready to be officially documented. +The +.Fn feupdateenv +function restores a saved environment similarly to +.Fn fesetenv , +but it also re-raises any floating-point exceptions from the old +environment. +.Pp +The macro +.Dv FE_DFL_ENV +expands to a pointer to the default environment. +.Sh EXAMPLES +The following routine computes the square root function. +It explicitly raises an invalid exception on appropriate inputs using +.Fn feraiseexcept . +It also defers inexact exceptions while it computes intermediate +values, and then it allows an inexact exception to be raised only if +the final answer is inexact. +.Bd -literal -offset indent +#pragma STDC FENV_ACCESS ON +double sqrt(double n) { + double x = 1.0; + fenv_t env; + + if (isnan(n) || n < 0.0) { + feraiseexcept(FE_INVALID); + return (NAN); + } + if (isinf(n) || n == 0.0) + return (n); + feholdexcept(&env); + while (fabs((x * x) - n) > DBL_EPSILON * 2 * x) + x = (x / 2) + (n / (2 * x)); + if (x * x == n) + feclearexcept(FE_INEXACT); + feupdateenv(&env); + return (x); +} +.Ed +.Sh SEE ALSO +.Xr c99 1 , +.Xr feclearexcept 3 , +.Xr fedisableexcept 3 , +.Xr feenableexcept 3 , +.Xr fegetenv 3 , +.Xr fegetexcept 3 , +.Xr fegetexceptflag 3 , +.Xr fegetround 3 , +.Xr feholdexcept 3 , +.Xr feraiseexcept 3 , +.Xr fesetenv 3 , +.Xr fesetexceptflag 3 , +.Xr fesetround 3 , +.Xr fetestexcept 3 , +.Xr feupdateenv 3 +.\"Xr fpgetprec 3 , +.\"Xr fpsetprec 3 +.Sh STANDARDS +Except as noted below, +.In fenv.h +conforms to +.St -isoC-99 . +The +.Fn feenableexcept , +.Fn fedisableexcept , +and +.Fn fegetexcept +routines are extensions. +.Sh HISTORY +The +.In fenv.h +header first appeared in +.Fx 5.3 +and +.Nx 6.0 . +It supersedes the non-standard routines defined in +.In ieeefp.h +and documented in +.Xr fpgetround 3 . +.Sh CAVEATS +The FENV_ACCESS pragma can be enabled with +.Dl "#pragma STDC FENV_ACCESS ON" +and disabled with the +.Dl "#pragma STDC FENV_ACCESS OFF" +directive. +This lexically-scoped annotation tells the compiler that the program +may access the floating-point environment, so optimizations that would +violate strict IEEE-754 semantics are disabled. +If execution reaches a block of code for which +.Dv FENV_ACCESS +is off, the floating-point environment will become undefined. +.Sh BUGS +The +.Dv FENV_ACCESS +pragma is unimplemented in the system compiler. +However, non-constant expressions generally produce the correct +side-effects at low optimization levels. diff --git a/static/netbsd/man3/ferror.3 b/static/netbsd/man3/ferror.3 new file mode 100644 index 00000000..270a7660 --- /dev/null +++ b/static/netbsd/man3/ferror.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: ferror.3,v 1.14 2010/05/08 11:35:14 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ferror.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd May 6, 2010 +.Dt FERROR 3 +.Os +.Sh NAME +.Nm clearerr , +.Nm feof , +.Nm ferror , +.Nm fileno +.Nd check and reset stream status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn clearerr "FILE *stream" +.Ft int +.Fn feof "FILE *stream" +.Ft int +.Fn ferror "FILE *stream" +.Ft int +.Fn fileno "FILE *stream" +.Sh DESCRIPTION +The function +.Fn clearerr +clears the end-of-file and error indicators for the stream pointed +to by +.Fa stream . +.Pp +The function +.Fn feof +tests the end-of-file indicator for the stream pointed to by +.Fa stream , +returning non-zero if it is set. +The end-of-file indicator can only be cleared by the function +.Fn clearerr . +.Pp +The function +.Fn ferror +tests the error indicator for the stream pointed to by +.Fa stream , +returning non-zero if it is set. +The error indicator can only be reset by the +.Fn clearerr +function. +.Pp +The function +.Fn fileno +examines the argument +.Fa stream +and returns its integer descriptor. +.Sh ERRORS +The functions +.Fn clearerr , +.Fn feof , +and +.Fn ferror +should neither fail nor set the external variable +.Va errno . +However, the function +.Fn fileno +may fail and return \-1 in case the argument +.Fa stream +is not associated with a valid file descriptor. +(In this case the +.Nx +implementation does not follow the optional +.Tn POSIX +recommendation to set the +.Va errno +variable to +.Er EBADF . ) +.Sh SEE ALSO +.Xr open 2 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn clearerr , +.Fn feof , +and +.Fn ferror +conform to +.St -ansiC . +The function +.Fn fileno +conforms to +.St -p1003.1-90 . diff --git a/static/netbsd/man3/fetch.3 b/static/netbsd/man3/fetch.3 new file mode 100644 index 00000000..2152600f --- /dev/null +++ b/static/netbsd/man3/fetch.3 @@ -0,0 +1,668 @@ +.\"- +.\" Copyright (c) 1998-2004 Dag-Erling Coïdan Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libfetch/fetch.3,v 1.63 2007/05/24 20:28:14 des Exp $ +.\" +.Dd April 22, 2007 +.Dt FETCH 3 +.Os +.Sh NAME +.Nm fetchMakeURL , +.Nm fetchParseURL , +.Nm fetchFreeURL , +.Nm fetchXGetURL , +.Nm fetchGetURL , +.Nm fetchPutURL , +.Nm fetchStatURL , +.Nm fetchListURL , +.Nm fetchXGet , +.Nm fetchGet , +.Nm fetchPut , +.Nm fetchStat , +.Nm fetchList , +.Nm fetchXGetFile , +.Nm fetchGetFile , +.Nm fetchPutFile , +.Nm fetchStatFile , +.Nm fetchListFile , +.Nm fetchXGetHTTP , +.Nm fetchGetHTTP , +.Nm fetchPutHTTP , +.Nm fetchStatHTTP , +.Nm fetchListHTTP , +.Nm fetchXGetFTP , +.Nm fetchGetFTP , +.Nm fetchPutFTP , +.Nm fetchStatFTP , +.Nm fetchListFTP +.Nd file transfer functions +.Sh LIBRARY +.Lb libfetch +.Sh SYNOPSIS +.In sys/param.h +.In stdio.h +.In fetch.h +.Ft struct url * +.Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd" +.Ft struct url * +.Fn fetchParseURL "const char *URL" +.Ft void +.Fn fetchFreeURL "struct url *u" +.Ft FILE * +.Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags" +.Ft FILE * +.Fn fetchGetURL "const char *URL" "const char *flags" +.Ft FILE * +.Fn fetchPutURL "const char *URL" "const char *flags" +.Ft int +.Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags" +.Ft struct url_ent * +.Fn fetchListURL "const char *URL" "const char *flags" +.Ft FILE * +.Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags" +.Ft FILE * +.Fn fetchGet "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchPut "struct url *u" "const char *flags" +.Ft int +.Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags" +.Ft struct url_ent * +.Fn fetchList "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags" +.Ft FILE * +.Fn fetchGetFile "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchPutFile "struct url *u" "const char *flags" +.Ft int +.Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags" +.Ft struct url_ent * +.Fn fetchListFile "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags" +.Ft FILE * +.Fn fetchGetHTTP "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchPutHTTP "struct url *u" "const char *flags" +.Ft int +.Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags" +.Ft struct url_ent * +.Fn fetchListHTTP "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags" +.Ft FILE * +.Fn fetchGetFTP "struct url *u" "const char *flags" +.Ft FILE * +.Fn fetchPutFTP "struct url *u" "const char *flags" +.Ft int +.Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags" +.Ft struct url_ent * +.Fn fetchListFTP "struct url *u" "const char *flags" +.Sh DESCRIPTION +These functions implement a high-level library for retrieving and +uploading files using Uniform Resource Locators (URLs). +.Pp +.Fn fetchParseURL +takes a URL in the form of a null-terminated string and splits it into +its components function according to the Common Internet Scheme Syntax +detailed in RFC1738. +A regular expression which produces this syntax is: +.Bd -literal + :(//((:)?@)?(:)?)?/()? +.Ed +.Pp +If the URL does not seem to begin with a scheme name, the following +syntax is assumed: +.Bd -literal + (((:)?@)?(:)?)?/()? +.Ed +.Pp +Note that some components of the URL are not necessarily relevant to +all URL schemes. +For instance, the file scheme only needs the and +components. +.Pp +.Fn fetchMakeURL +and +.Fn fetchParseURL +return a pointer to a +.Vt url +structure, which is defined as follows in +.In fetch.h : +.Bd -literal +#define URL_SCHEMELEN 16 +#define URL_USERLEN 256 +#define URL_PWDLEN 256 + +struct url { + char scheme[URL_SCHEMELEN+1]; + char user[URL_USERLEN+1]; + char pwd[URL_PWDLEN+1]; + char host[MAXHOSTNAMELEN+1]; + int port; + char *doc; + off_t offset; + size_t length; +}; +.Ed +.Pp +The pointer returned by +.Fn fetchMakeURL +or +.Fn fetchParseURL +should be freed using +.Fn fetchFreeURL . +.Pp +.Fn fetchXGetURL , +.Fn fetchGetURL , +and +.Fn fetchPutURL +constitute the recommended interface to the +.Nm fetch +library. +They examine the URL passed to them to determine the transfer +method, and call the appropriate lower-level functions to perform the +actual transfer. +.Fn fetchXGetURL +also returns the remote document's metadata in the +.Vt url_stat +structure pointed to by the +.Fa us +argument. +.Pp +The +.Fa flags +argument is a string of characters which specify transfer options. +The +meaning of the individual flags is scheme-dependent, and is detailed +in the appropriate section below. +.Pp +.Fn fetchStatURL +attempts to obtain the requested document's metadata and fill in the +structure pointed to by its second argument. +The +.Vt url_stat +structure is defined as follows in +.In fetch.h : +.Bd -literal +struct url_stat { + off_t size; + time_t atime; + time_t mtime; +}; +.Ed +.Pp +If the size could not be obtained from the server, the +.Fa size +field is set to -1. +If the modification time could not be obtained from the server, the +.Fa mtime +field is set to the epoch. +If the access time could not be obtained from the server, the +.Fa atime +field is set to the modification time. +.Pp +.Fn fetchListURL +attempts to list the contents of the directory pointed to by the URL +provided. +If successful, it returns a malloced array of +.Vt url_ent +structures. +The +.Vt url_ent +structure is defined as follows in +.In fetch.h : +.Bd -literal +struct url_ent { + char name[MAXPATHLEN]; + struct url_stat stat; +}; +.Ed +.Pp +The list is terminated by an entry with an empty name. +.Pp +The pointer returned by +.Fn fetchListURL +should be freed using +.Fn free . +.Pp +.Fn fetchXGet , +.Fn fetchGet , +.Fn fetchPut +and +.Fn fetchStat +are similar to +.Fn fetchXGetURL , +.Fn fetchGetURL , +.Fn fetchPutURL +and +.Fn fetchStatURL , +except that they expect a pre-parsed URL in the form of a pointer to +a +.Vt struct url +rather than a string. +.Pp +All of the +.Fn fetchXGetXXX , +.Fn fetchGetXXX +and +.Fn fetchPutXXX +functions return a pointer to a stream which can be used to read or +write data from or to the requested document, respectively. +Note that +although the implementation details of the individual access methods +vary, it can generally be assumed that a stream returned by one of the +.Fn fetchXGetXXX +or +.Fn fetchGetXXX +functions is read-only, and that a stream returned by one of the +.Fn fetchPutXXX +functions is write-only. +.Sh FILE SCHEME +.Fn fetchXGetFile , +.Fn fetchGetFile +and +.Fn fetchPutFile +provide access to documents which are files in a locally mounted file +system. +Only the component of the URL is used. +.Pp +.Fn fetchXGetFile +and +.Fn fetchGetFile +do not accept any flags. +.Pp +.Fn fetchPutFile +accepts the +.Ql a +(append to file) flag. +If that flag is specified, the data written to +the stream returned by +.Fn fetchPutFile +will be appended to the previous contents of the file, instead of +replacing them. +.Sh FTP SCHEME +.Fn fetchXGetFTP , +.Fn fetchGetFTP +and +.Fn fetchPutFTP +implement the FTP protocol as described in RFC959. +.Pp +If the +.Ql p +(passive) flag is specified, a passive (rather than active) connection +will be attempted. +.Pp +If the +.Ql l +(low) flag is specified, data sockets will be allocated in the low (or +default) port range instead of the high port range (see +.Xr ip 4 ) . +.Pp +If the +.Ql d +(direct) flag is specified, +.Fn fetchXGetFTP , +.Fn fetchGetFTP +and +.Fn fetchPutFTP +will use a direct connection even if a proxy server is defined. +.Pp +If no user name or password is given, the +.Nm fetch +library will attempt an anonymous login, with user name "anonymous" +and password "anonymous@". +.Sh HTTP SCHEME +The +.Fn fetchXGetHTTP , +.Fn fetchGetHTTP +and +.Fn fetchPutHTTP +functions implement the HTTP/1.1 protocol. +With a little luck, there is +even a chance that they comply with RFC2616 and RFC2617. +.Pp +If the +.Ql d +(direct) flag is specified, +.Fn fetchXGetHTTP , +.Fn fetchGetHTTP +and +.Fn fetchPutHTTP +will use a direct connection even if a proxy server is defined. +.Pp +Since there seems to be no good way of implementing the HTTP PUT +method in a manner consistent with the rest of the +.Nm fetch +library, +.Fn fetchPutHTTP +is currently unimplemented. +.Sh AUTHENTICATION +Apart from setting the appropriate environment variables and +specifying the user name and password in the URL or the +.Vt struct url , +the calling program has the option of defining an authentication +function with the following prototype: +.Pp +.Ft int +.Fn myAuthMethod "struct url *u" +.Pp +The callback function should fill in the +.Fa user +and +.Fa pwd +fields in the provided +.Vt struct url +and return 0 on success, or any other value to indicate failure. +.Pp +To register the authentication callback, simply set +.Va fetchAuthMethod +to point at it. +The callback will be used whenever a site requires authentication and +the appropriate environment variables are not set. +.Pp +This interface is experimental and may be subject to change. +.Sh RETURN VALUES +.Fn fetchParseURL +returns a pointer to a +.Vt struct url +containing the individual components of the URL. +If it is +unable to allocate memory, or the URL is syntactically incorrect, +.Fn fetchParseURL +returns a NULL pointer. +.Pp +The +.Fn fetchStat +functions return 0 on success and -1 on failure. +.Pp +All other functions return a stream pointer which may be used to +access the requested document, or NULL if an error occurred. +.Pp +The following error codes are defined in +.In fetch.h : +.Bl -tag -width 18n +.It Bq Er FETCH_ABORT +Operation aborted +.It Bq Er FETCH_AUTH +Authentication failed +.It Bq Er FETCH_DOWN +Service unavailable +.It Bq Er FETCH_EXISTS +File exists +.It Bq Er FETCH_FULL +File system full +.It Bq Er FETCH_INFO +Informational response +.It Bq Er FETCH_MEMORY +Insufficient memory +.It Bq Er FETCH_MOVED +File has moved +.It Bq Er FETCH_NETWORK +Network error +.It Bq Er FETCH_OK +No error +.It Bq Er FETCH_PROTO +Protocol error +.It Bq Er FETCH_RESOLV +Resolver error +.It Bq Er FETCH_SERVER +Server error +.It Bq Er FETCH_TEMP +Temporary error +.It Bq Er FETCH_TIMEOUT +Operation timed out +.It Bq Er FETCH_UNAVAIL +File is not available +.It Bq Er FETCH_UNKNOWN +Unknown error +.It Bq Er FETCH_URL +Invalid URL +.El +.Pp +The accompanying error message includes a protocol-specific error code +and message, e.g.\& "File is not available (404 Not Found)" +.Sh ENVIRONMENT +.Bl -tag -width ".Ev FETCH_BIND_ADDRESS" +.It Ev FETCH_BIND_ADDRESS +Specifies a hostname or IP address to which sockets used for outgoing +connections will be bound. +.It Ev FTP_LOGIN +Default FTP login if none was provided in the URL. +.It Ev FTP_PASSIVE_MODE +If set to anything but +.Ql no , +forces the FTP code to use passive mode. +.It Ev FTP_PASSWORD +Default FTP password if the remote server requests one and none was +provided in the URL. +.It Ev FTP_PROXY +URL of the proxy to use for FTP requests. +The document part is ignored. +FTP and HTTP proxies are supported; if no scheme is specified, FTP is +assumed. +If the proxy is an FTP proxy, +.Nm libfetch +will send +.Ql user@host +as user name to the proxy, where +.Ql user +is the real user name, and +.Ql host +is the name of the FTP server. +.Pp +If this variable is set to an empty string, no proxy will be used for +FTP requests, even if the +.Ev HTTP_PROXY +variable is set. +.It Ev ftp_proxy +Same as +.Ev FTP_PROXY , +for compatibility. +.It Ev HTTP_AUTH +Specifies HTTP authorization parameters as a colon-separated list of +items. +The first and second item are the authorization scheme and realm +respectively; further items are scheme-dependent. +Currently, only basic authorization is supported. +.Pp +Basic authorization requires two parameters: the user name and +password, in that order. +.Pp +This variable is only used if the server requires authorization and +no user name or password was specified in the URL. +.It Ev HTTP_PROXY +URL of the proxy to use for HTTP requests. +The document part is ignored. +Only HTTP proxies are supported for HTTP requests. +If no port number is specified, the default is 3128. +.Pp +Note that this proxy will also be used for FTP documents, unless the +.Ev FTP_PROXY +variable is set. +.It Ev http_proxy +Same as +.Ev HTTP_PROXY , +for compatibility. +.It Ev HTTP_PROXY_AUTH +Specifies authorization parameters for the HTTP proxy in the same +format as the +.Ev HTTP_AUTH +variable. +.Pp +This variable is used if and only if connected to an HTTP proxy, and +is ignored if a user and/or a password were specified in the proxy +URL. +.It Ev HTTP_REFERER +Specifies the referrer URL to use for HTTP requests. +If set to +.Dq auto , +the document URL will be used as referrer URL. +.It Ev HTTP_USER_AGENT +Specifies the User-Agent string to use for HTTP requests. +This can be useful when working with HTTP origin or proxy servers that +differentiate between user agents. +.It Ev NETRC +Specifies a file to use instead of +.Pa ~/.netrc +to look up login names and passwords for FTP sites. +See +.Xr ftp 1 +for a description of the file format. +This feature is experimental. +.El +.Sh EXAMPLES +To access a proxy server on +.Pa proxy.example.com +port 8080, set the +.Ev HTTP_PROXY +environment variable in a manner similar to this: +.Pp +.Dl HTTP_PROXY=http://proxy.example.com:8080 +.Pp +If the proxy server requires authentication, there are +two options available for passing the authentication data. +The first method is by using the proxy URL: +.Pp +.Dl HTTP_PROXY=http://:@proxy.example.com:8080 +.Pp +The second method is by using the +.Ev HTTP_PROXY_AUTH +environment variable: +.Bd -literal -offset indent +HTTP_PROXY=http://proxy.example.com:8080 +HTTP_PROXY_AUTH=basic:*:: +.Ed +.Sh SEE ALSO +.Xr fetch 1 , +.Xr ftpio 3 , +.Xr ip 4 +.Rs +.%A J. Postel +.%A J. K. Reynolds +.%D October 1985 +.%B File Transfer Protocol +.%O RFC959 +.Re +.Rs +.%A P. Deutsch +.%A A. Emtage +.%A A. Marine. +.%D May 1994 +.%T How to Use Anonymous FTP +.%O RFC1635 +.Re +.Rs +.%A T. Berners-Lee +.%A L. Masinter +.%A M. McCahill +.%D December 1994 +.%T Uniform Resource Locators (URL) +.%O RFC1738 +.Re +.Rs +.%A R. Fielding +.%A J. Gettys +.%A J. Mogul +.%A H. Frystyk +.%A L. Masinter +.%A P. Leach +.%A T. Berners-Lee +.%D January 1999 +.%B Hypertext Transfer Protocol -- HTTP/1.1 +.%O RFC2616 +.Re +.Rs +.%A J. Franks +.%A P. Hallam-Baker +.%A J. Hostetler +.%A S. Lawrence +.%A P. Leach +.%A A. Luotonen +.%A L. Stewart +.%D June 1999 +.%B HTTP Authentication: Basic and Digest Access Authentication +.%O RFC2617 +.Re +.Sh HISTORY +The +.Nm fetch +library first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm fetch +library was mostly written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org +with numerous suggestions from +.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , +.An Eugene Skepner Aq Mt eu@qub.com +and other +.Fx +developers. +It replaces the older +.Nm ftpio +library written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org +and +.An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . +.Pp +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +.Sh BUGS +Some parts of the library are not yet implemented. +The most notable +examples of this are +.Fn fetchPutHTTP , +.Fn fetchListHTTP , +.Fn fetchListFTP +and FTP proxy support. +.Pp +There is no way to select a proxy at run-time other than setting the +.Ev HTTP_PROXY +or +.Ev FTP_PROXY +environment variables as appropriate. +.Pp +.Nm libfetch +does not understand or obey 305 (Use Proxy) replies. +.Pp +Error numbers are unique only within a certain context; the error +codes used for FTP and HTTP overlap, as do those used for resolver and +system errors. +For instance, error code 202 means "Command not +implemented, superfluous at this site" in an FTP context and +"Accepted" in an HTTP context. +.Pp +.Fn fetchStatFTP +does not check that the result of an MDTM command is a valid date. +.Pp +The man page is incomplete, poorly written and produces badly +formatted text. +.Pp +The error reporting mechanism is unsatisfactory. +.Pp +Some parts of the code are not fully reentrant. diff --git a/static/netbsd/man3/fflush.3 b/static/netbsd/man3/fflush.3 new file mode 100644 index 00000000..c4b0d2f7 --- /dev/null +++ b/static/netbsd/man3/fflush.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: fflush.3,v 1.15 2025/12/18 23:09:20 nia Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fflush.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd December 18, 2025 +.Dt FFLUSH 3 +.Os +.Sh NAME +.Nm fflush , +.Nm fpurge +.Nd flush a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fflush "FILE *stream" +.Ft int +.Fn fpurge "FILE *stream" +.Sh DESCRIPTION +The function +.Fn fflush +forces a write of all buffered data for the given output or update +.Fa stream +via the stream's underlying write function. +The open status of the stream is unaffected. +.Pp +If the file is opened only for reading and not for writing, nothing is done. +.Pp +If the +.Fa stream +argument is +.Dv NULL , +.Fn fflush +flushes +.Em all +open output streams. +.Pp +The function +.Fn fpurge +erases any input or output buffered in the given +.Fa stream . +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.Xr getc 3 ; +this includes any text pushed back via +.Xr ungetc 3 . +.Sh RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, +.Dv EOF +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +.Fa stream +is not an open stream. +.El +.Pp +The function +.Fn fflush +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr write 2 . +.Sh SEE ALSO +.Xr write 2 , +.Xr fclose 3 , +.Xr fopen 3 , +.Xr setbuf 3 +.Sh STANDARDS +The +.Fn fflush +function +conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn fflush +function first appeared in +.At v4 . +The +.Fn fpurge +function first appeared in +.Bx 4.4 . +.Sh BUGS +According to +.St -p1003.1-2024 , +calling +.Fn fflush +on a readonly stream that is not at EOF and is seekable, the file offset +of the +.Ft FILE +pointer should be set to the file position of the underlying file descriptor +and any characters that have been pushed back via +.Xr ungetc 3 +or +.Xr ungetwc 3 +should be discarded. +This is currently not implemented. diff --git a/static/netbsd/man3/ffs.3 b/static/netbsd/man3/ffs.3 new file mode 100644 index 00000000..1d31a355 --- /dev/null +++ b/static/netbsd/man3/ffs.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)ffs.3 8.2 (Berkeley) 4/19/94 +.\" $NetBSD: ffs.3,v 1.14 2024/11/01 18:42:30 riastradh Exp $ +.\" +.Dd November 1, 2024 +.Dt FFS 3 +.Os +.Sh NAME +.Nm ffs +.Nm ffsl +.Nm ffsll +.Nd find first bit set in a bit string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fn ffs "int value" +.Fn ffsl "long value" +.Fn ffsll "long long value" +.Sh DESCRIPTION +The +.Fn ffs , +.Fn ffsl , +and +.Fn ffsll +functions find the first bit set in +.Fa value +and return the index of that bit. +Bits are numbered starting from 1, starting at the right-most +bit. +A return value of 0 means that the argument was zero. +.Sh SEE ALSO +.Xr bitstring 3 , +.Xr ffs32 3 , +.Xr ffs64 3 , +.Xr popcount 3 +.Sh STANDARDS +The +.Fn ffs +function conforms to +.St -p1003.1-2001 . +The +.Fn ffsl +and +.Fn ffsll +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn ffs +function appeared in +.Bx 4.3 . +The prototype for it existed previously in the +.In string.h +header before it was moved to +.In strings.h +for +.Tn POSIX +compliance. diff --git a/static/netbsd/man3/fgetln.3 b/static/netbsd/man3/fgetln.3 new file mode 100644 index 00000000..3c67787b --- /dev/null +++ b/static/netbsd/man3/fgetln.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: fgetln.3,v 1.17 2025/12/20 14:42:43 christos Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd December 20, 2025 +.Dt FGETLN 3 +.Os +.Sh NAME +.Nm fgetln +.Nd get a line from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn fgetln "FILE * restrict stream" "size_t * restrict len" +.Sh DESCRIPTION +The +.Fn fgetln +function +returns a pointer to the next line from the stream referenced by +.Fa stream . +This line is +.Em not +a C string as it does not end with a terminating +.Dv NUL +character. +The length of the line, including the final newline, +is stored in the memory location to which +.Fa len +points. +(Note, however, that if the line is the last +in a file that does not end in a newline, +the returned text will not contain a newline.) +.Sh RETURN VALUES +Upon successful completion a pointer is returned; +this pointer becomes invalid after the next +.Tn I/O +operation on +.Fa stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.Dv NULL +is returned. +The +.Fn fgetln +function +does not distinguish between end-of-file and error; the routines +.Xr feof 3 +and +.Xr ferror 3 +must be used +to determine which occurred. +If an error occurs, the global variable +.Va errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.Dv NULL +until the condition is +cleared with +.Xr clearerr 3 . +.Pp +The text to which the returned pointer points may be modified, +provided that no changes are made beyond the returned size. +These changes are lost as soon as the pointer becomes invalid. +.Sh ERRORS +.Bl -tag -width [EBADF] +.It Bq Er EBADF +The argument +.Fa stream +is not a stream open for reading. +.El +.Pp +The +.Fn fgetln +function +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fflush 3 , +.Xr malloc 3 , +.Xr read 2 , +.Xr stat 2 , +or +.Xr realloc 3 . +.Sh SEE ALSO +.Xr getline 3 , +.Xr ferror 3 , +.Xr fgets 3 , +.Xr fopen 3 , +.Xr fparseln 3, +.Xr putc 3 +.Sh HISTORY +The +.Fn fgetln +function first appeared in +.Bx 4.4 . +.Sh CAVEATS +Since the returned buffer is not a C string (it is not null terminated), a +common practice is to replace the newline character with +.Sq \e0 . +However, if the last line in a file does not contain a newline, +the returned text won't contain a newline either. +The following code demonstrates how to deal with this problem by allocating a +temporary buffer: +.Bd -literal + char *buf, *lbuf; + size_t len; + + while ((lbuf = buf = fgetln(fp, &len)) != NULL) { + if (len > 0 && buf[len - 1] == '\en') + buf[len - 1] = '\e0'; + else if ((lbuf = strndup(buf, len + 1)) == NULL) + err(1, NULL); + printf("%s\en", lbuf); + + if (lbuf != buf) + free(lbuf); + } +.Ed diff --git a/static/netbsd/man3/fgets.3 b/static/netbsd/man3/fgets.3 new file mode 100644 index 00000000..2c521526 --- /dev/null +++ b/static/netbsd/man3/fgets.3 @@ -0,0 +1,201 @@ +.\" $NetBSD: fgets.3,v 1.22 2010/05/13 18:38:24 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 13, 2010 +.Dt FGETS 3 +.Os +.Sh NAME +.Nm fgets , +.Nm gets +.Nd get a line from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft char * +.Fn fgets "char * restrict str" "int size" "FILE * restrict stream" +.Ft char * +.Fn gets "char *str" +.Sh DESCRIPTION +The +.Fn fgets +function +reads at most one less than the number of characters specified by +.Fa size +from the given +.Fa stream +and stores them in the string +.Fa str . +Reading stops when a newline character is found, +at end-of-file or error. +The newline, if any, is retained, and a +.Ql \e0 +character is appended to end the string. +.Pp +The +.Fn gets +function +is equivalent to +.Fn fgets +with an infinite +.Fa size +and a +.Fa stream +of +.Em stdin , +except that the newline character (if any) is not stored in the string. +It is the caller's responsibility to ensure that the input line, +if any, is sufficiently short to fit in the string. +.Sh RETURN VALUES +Upon successful completion, +.Fn fgets +and +.Fn gets +return +a pointer to the string. +If end-of-file or an error occurs before any characters are read, +they return +.Dv NULL . +The +.Fn fgets +and +.Fn gets +functions +do not distinguish between end-of-file and error, and callers must use +.Xr feof 3 +and +.Xr ferror 3 +to determine which occurred. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The given +.Fa stream +is not a readable stream. +.El +.Pp +The function +.Fn fgets +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fflush 3 , +.Xr fstat 2 , +.Xr read 2 , +or +.Xr malloc 3 . +.Pp +The function +.Fn gets +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr getchar 3 . +.Sh SEE ALSO +.Xr feof 3 , +.Xr ferror 3 , +.Xr fgetln 3 +.Sh STANDARDS +The functions +.Fn fgets +and +.Fn gets +conform to +.St -ansiC +and +.St -p1003.1-2001 . +The +.St -p1003.1-2008 +revision marked +.Fn gets +as obsolescent. +.Sh CAVEATS +The following bit of code illustrates a case where the programmer assumes a +string is too long if it does not contain a newline: +.Bd -literal + char buf[1024], *p; + + while (fgets(buf, sizeof(buf), fp) != NULL) { + if ((p = strchr(buf, '\en')) == NULL) { + fprintf(stderr, "input line too long.\en"); + exit(1); + } + *p = '\e0'; + printf("%s\en", buf); + } +.Ed +.Pp +While the error would be true if a line longer than 1023 characters +were read, it would be false in two other cases: +.Bl -enum -offset indent +.It +If the last line in a file does not contain a newline, the string returned by +.Fn fgets +will not contain a newline either. +Thus +.Fn strchr +will return +.Dv NULL +and the program will terminate, even if the line was valid. +.It +All C string functions, including +.Fn strchr , +correctly assume the end of the string is represented by a null +.Pq Sq \e0 +character. +If the first character of a line returned by +.Fn fgets +were null, +.Fn strchr +would immediately return without considering the rest of the returned text +which may indeed include a newline. +.El +.Pp +Consider using +.Xr fgetln 3 +instead when dealing with untrusted input. +.Sh SECURITY CONSIDERATIONS +Since it is usually impossible to ensure that the next input line +is less than some arbitrary length, and because overflowing the +input buffer is almost invariably a security violation, programs +should +.Em NEVER +use +.Fn gets . +The +.Fn gets +function +exists purely to conform to +.St -ansiC . diff --git a/static/netbsd/man3/fgetwln.3 b/static/netbsd/man3/fgetwln.3 new file mode 100644 index 00000000..a17e5959 --- /dev/null +++ b/static/netbsd/man3/fgetwln.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: fgetwln.3,v 1.2 2010/12/16 17:42:27 wiz Exp $ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94 +.\" $FreeBSD: src/lib/libc/stdio/fgetwln.3,v 1.1 2004/07/16 06:06:09 tjr Exp $ +.\" +.Dd July 16, 2004 +.Dt FGETWLN 3 +.Os +.Sh NAME +.Nm fgetwln +.Nd get a line of wide characters from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft wchar_t * +.Fn fgetwln "FILE * restrict stream" "size_t * restrict len" +.Sh DESCRIPTION +The +.Fn fgetwln +function +returns a pointer to the next line from the stream referenced by +.Fa stream . +This line is +.Em not +a standard wide-character string as it does not end with a terminating +null wide character. +The length of the line, including the final newline, +is stored in the memory location to which +.Fa len +points. +(Note, however, that if the line is the last +in a file that does not end in a newline, +the returned text will not contain a newline.) +.Sh RETURN VALUES +Upon successful completion a pointer is returned; +this pointer becomes invalid after the next +.Tn I/O +operation on +.Fa stream +(whether successful or not) +or as soon as the stream is closed. +Otherwise, +.Dv NULL +is returned. +The +.Fn fgetwln +function +does not distinguish between end-of-file and error; the routines +.Xr feof 3 +and +.Xr ferror 3 +must be used +to determine which occurred. +If an error occurs, the global variable +.Va errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.Dv NULL +until the condition is +cleared with +.Xr clearerr 3 . +.Pp +The text to which the returned pointer points may be modified, +provided that no changes are made beyond the returned size. +These changes are lost as soon as the pointer becomes invalid. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa stream +is not a stream open for reading. +.El +.Pp +The +.Fn fgetwln +function +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr mbrtowc 3 , +.Xr realloc 3 , +or +.Xr read 2 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgetln 3 , +.Xr fgetws 3 , +.Xr fopen 3 diff --git a/static/netbsd/man3/fgetws.3 b/static/netbsd/man3/fgetws.3 new file mode 100644 index 00000000..e0cc0000 --- /dev/null +++ b/static/netbsd/man3/fgetws.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: fgetws.3,v 1.3 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Original version ID: +.\" FreeBSD: src/lib/libc/stdio/fgets.3,v 1.16 2002/05/31 05:01:17 archie Exp +.\" FreeBSD: src/lib/libc/stdio/fgetws.3,v 1.2 2002/09/06 11:23:55 tjr Exp +.\" +.Dd August 6, 2002 +.Dt FGETWS 3 +.Os +.Sh NAME +.Nm fgetws +.Nd get a line of wide characters from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft "wchar_t *" +.Fn fgetws "wchar_t * restrict ws" "int n" "FILE * restrict fp" +.Sh DESCRIPTION +The +.Fn fgetws +function +reads at most one less than the number of characters specified by +.Fa n +from the given +.Fa fp +and stores them in the wide-character string +.Fa ws . +Reading stops when a newline character is found, +at end-of-file or error. +The newline, if any, is retained. +If any characters are read and there is no error, a +.Ql \e0 +character is appended to end the string. +.Sh RETURN VALUES +Upon successful completion, +.Fn fgetws +returns +.Fa ws . +If end-of-file occurs before any characters are read, +.Fn fgetws +returns +.Dv NULL +and the buffer contents remain unchanged. +If an error occurs, +.Fn fgetws +returns +.Dv NULL +and the buffer contents are indeterminate. +The +.Fn fgetws +function +does not distinguish between end-of-file and error, and callers must use +.Xr feof 3 +and +.Xr ferror 3 +to determine which occurred. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The given +.Fa fp +argument is not a readable stream. +.It Bq Er EILSEQ +The data obtained from the input stream does not form a valid +multibyte character. +.El +.Pp +The function +.Fn fgetws +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fflush 3 , +.Xr fstat 2 , +.Xr read 2 , +or +.Xr malloc 3 . +.Sh SEE ALSO +.Xr feof 3 , +.Xr ferror 3 , +.Xr fgets 3 +.Sh STANDARDS +The +.Fn fgetws +function +conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/fido_assert_allow_cred.3 b/static/netbsd/man3/fido_assert_allow_cred.3 new file mode 100644 index 00000000..65201373 --- /dev/null +++ b/static/netbsd/man3/fido_assert_allow_cred.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: December 1 2022 $ +.Dt FIDO_ASSERT_ALLOW_CRED 3 +.Os +.Sh NAME +.Nm fido_assert_allow_cred , +.Nm fido_assert_empty_allow_list +.Nd manage allow lists in a FIDO2 assertion +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_assert_allow_cred "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_empty_allow_list "fido_assert_t *assert" +.Sh DESCRIPTION +The +.Fn fido_assert_allow_cred +function adds +.Fa ptr +to the list of credentials allowed in +.Fa assert , +where +.Fa ptr +points to a credential ID of +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +If +.Fn fido_assert_allow_cred +fails, the existing list of allowed credentials is preserved. +.Pp +For the format of a FIDO2 credential ID, please refer to the +Web Authentication (webauthn) standard. +.Pp +The +.Fn fido_assert_empty_allow_list +function empties the list of credentials allowed in +.Fa assert . +.Sh RETURN VALUES +The error codes returned by +.Fn fido_assert_allow_cred +and +.Fn fido_assert_empty_allow_list +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 , +.Xr fido_dev_get_assert 3 diff --git a/static/netbsd/man3/fido_assert_new.3 b/static/netbsd/man3/fido_assert_new.3 new file mode 100644 index 00000000..fdc74a90 --- /dev/null +++ b/static/netbsd/man3/fido_assert_new.3 @@ -0,0 +1,293 @@ +.\" Copyright (c) 2018-2023 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: June 19 2023 $ +.Dt FIDO_ASSERT_NEW 3 +.Os +.Sh NAME +.Nm fido_assert_new , +.Nm fido_assert_free , +.Nm fido_assert_count , +.Nm fido_assert_rp_id , +.Nm fido_assert_user_display_name , +.Nm fido_assert_user_icon , +.Nm fido_assert_user_name , +.Nm fido_assert_authdata_ptr , +.Nm fido_assert_authdata_raw_ptr , +.Nm fido_assert_blob_ptr , +.Nm fido_assert_clientdata_hash_ptr , +.Nm fido_assert_hmac_secret_ptr , +.Nm fido_assert_largeblob_key_ptr , +.Nm fido_assert_user_id_ptr , +.Nm fido_assert_sig_ptr , +.Nm fido_assert_id_ptr , +.Nm fido_assert_authdata_len , +.Nm fido_assert_authdata_raw_len , +.Nm fido_assert_blob_len , +.Nm fido_assert_clientdata_hash_len , +.Nm fido_assert_hmac_secret_len , +.Nm fido_assert_largeblob_key_len , +.Nm fido_assert_user_id_len , +.Nm fido_assert_sig_len , +.Nm fido_assert_id_len , +.Nm fido_assert_sigcount , +.Nm fido_assert_flags +.Nd FIDO2 assertion API +.Sh SYNOPSIS +.In fido.h +.Ft fido_assert_t * +.Fn fido_assert_new "void" +.Ft void +.Fn fido_assert_free "fido_assert_t **assert_p" +.Ft size_t +.Fn fido_assert_count "const fido_assert_t *assert" +.Ft const char * +.Fn fido_assert_rp_id "const fido_assert_t *assert" +.Ft const char * +.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" +.Ft const char * +.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" +.Ft const char * +.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_authdata_raw_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" +.Ft const unsigned char * +.Fn fido_assert_blob_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_largeblob_key_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_authdata_raw_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" +.Ft size_t +.Fn fido_assert_blob_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_largeblob_key_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx" +.Ft uint32_t +.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" +.Ft uint8_t +.Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx" +.Sh DESCRIPTION +A FIDO2 assertion is a collection of statements, each statement a +map between a challenge, a credential, a signature, and ancillary +attributes. +In +.Em libfido2 , +a FIDO2 assertion is abstracted by the +.Vt fido_assert_t +type. +The functions described in this page allow a +.Vt fido_assert_t +type to be allocated, deallocated, and inspected. +For other operations on +.Vt fido_assert_t , +please refer to +.Xr fido_assert_set_authdata 3 , +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_verify 3 , +and +.Xr fido_dev_get_assert 3 . +.Pp +The +.Fn fido_assert_new +function returns a pointer to a newly allocated, empty +.Vt fido_assert_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_assert_free +function releases the memory backing +.Fa *assert_p , +where +.Fa *assert_p +must have been previously allocated by +.Fn fido_assert_new . +On return, +.Fa *assert_p +is set to NULL. +Either +.Fa assert_p +or +.Fa *assert_p +may be NULL, in which case +.Fn fido_assert_free +is a NOP. +.Pp +The +.Fn fido_assert_count +function returns the number of statements in +.Fa assert . +.Pp +The +.Fn fido_assert_rp_id +function returns a pointer to a NUL-terminated string holding the +relying party ID of +.Fa assert . +.Pp +The +.Fn fido_assert_user_display_name , +.Fn fido_assert_user_icon , +and +.Fn fido_assert_user_name , +functions return pointers to the user display name, icon, and +name attributes of statement +.Fa idx +in +.Fa assert . +If not NULL, the values returned by these functions point to +NUL-terminated UTF-8 strings. +The user display name, icon, and name attributes will typically +only be returned by the authenticator if user verification was +performed by the authenticator and multiple resident/discoverable +credentials were involved in the assertion. +.Pp +The +.Fn fido_assert_authdata_ptr , +.Fn fido_assert_authdata_raw_ptr , +.Fn fido_assert_clientdata_hash_ptr , +.Fn fido_assert_id_ptr , +.Fn fido_assert_user_id_ptr , +.Fn fido_assert_sig_ptr , +.Fn fido_assert_sigcount , +and +.Fn fido_assert_flags +functions return pointers to the CBOR-encoded and raw authenticator data, +client data hash, credential ID, user ID, signature, signature +count, and authenticator data flags of statement +.Fa idx +in +.Fa assert . +.Pp +The +.Fn fido_assert_hmac_secret_ptr +function returns a pointer to the hmac-secret attribute of statement +.Fa idx +in +.Fa assert . +The HMAC Secret Extension +.Pq hmac-secret +is a CTAP 2.0 extension. +Note that the resulting hmac-secret varies according to whether +user verification was performed by the authenticator. +.Pp +The +.Fn fido_assert_blob_ptr +and +.Fn fido_assert_largeblob_key_ptr +functions return pointers to the +.Dq credBlob +and +.Dq largeBlobKey +attributes of statement +.Fa idx +in +.Fa assert . +Credential Blob +.Pq credBlob +and +Large Blob Key +.Pq largeBlobKey +are CTAP 2.1 extensions. +.Pp +The +.Fn fido_assert_authdata_len , +.Fn fido_assert_authdata_raw_len , +.Fn fido_assert_clientdata_hash_len , +.Fn fido_assert_id_len , +.Fn fido_assert_user_id_len , +.Fn fido_assert_sig_len , +.Fn fido_assert_hmac_secret_len , +.Fn fido_assert_blob_len , +and +.Fn fido_assert_largeblob_key_len +functions return the length of a given attribute. +.Pp +Please note that the first statement in +.Fa assert +has an +.Fa idx +(index) value of 0. +.Pp +The authenticator data and signature parts of an assertion +statement are typically passed to a FIDO2 server for verification. +.Sh RETURN VALUES +The authenticator data returned by +.Fn fido_assert_authdata_ptr +is a CBOR-encoded byte string, as obtained from the authenticator. +.Pp +The +.Fn fido_assert_rp_id , +.Fn fido_assert_user_display_name , +.Fn fido_assert_user_icon , +.Fn fido_assert_user_name , +.Fn fido_assert_authdata_ptr , +.Fn fido_assert_clientdata_hash_ptr , +.Fn fido_assert_id_ptr , +.Fn fido_assert_user_id_ptr , +.Fn fido_assert_sig_ptr , +.Fn fido_assert_hmac_secret_ptr , +.Fn fido_assert_blob_ptr , +and +.Fn fido_assert_largeblob_key_ptr +functions may return NULL if the respective field in +.Fa assert +is not set. +If not NULL, returned pointers are guaranteed to exist until any API +function that takes +.Fa assert +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_set_authdata 3 , +.Xr fido_assert_verify 3 , +.Xr fido_dev_get_assert 3 , +.Xr fido_dev_largeblob_get 3 diff --git a/static/netbsd/man3/fido_assert_set_authdata.3 b/static/netbsd/man3/fido_assert_set_authdata.3 new file mode 100644 index 00000000..503e2bfb --- /dev/null +++ b/static/netbsd/man3/fido_assert_set_authdata.3 @@ -0,0 +1,314 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: April 8 2023 $ +.Dt FIDO_ASSERT_SET_AUTHDATA 3 +.Os +.Sh NAME +.Nm fido_assert_set_authdata , +.Nm fido_assert_set_authdata_raw , +.Nm fido_assert_set_clientdata , +.Nm fido_assert_set_clientdata_hash , +.Nm fido_assert_set_count , +.Nm fido_assert_set_extensions , +.Nm fido_assert_set_hmac_salt , +.Nm fido_assert_set_hmac_secret , +.Nm fido_assert_set_up , +.Nm fido_assert_set_uv , +.Nm fido_assert_set_rp , +.Nm fido_assert_set_sig , +.Nm fido_assert_set_winhello_appid +.Nd set parameters of a FIDO2 assertion +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef enum { + FIDO_OPT_OMIT = 0, /* use authenticator's default */ + FIDO_OPT_FALSE, /* explicitly set option to false */ + FIDO_OPT_TRUE, /* explicitly set option to true */ +} fido_opt_t; +.Ed +.Ft int +.Fn fido_assert_set_authdata "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_authdata_raw "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_clientdata "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_clientdata_hash "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_count "fido_assert_t *assert" "size_t n" +.Ft int +.Fn fido_assert_set_extensions "fido_assert_t *assert" "int flags" +.Ft int +.Fn fido_assert_set_hmac_salt "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_hmac_secret "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_up "fido_assert_t *assert" "fido_opt_t up" +.Ft int +.Fn fido_assert_set_uv "fido_assert_t *assert" "fido_opt_t uv" +.Ft int +.Fn fido_assert_set_rp "fido_assert_t *assert" "const char *id" +.Ft int +.Fn fido_assert_set_sig "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_winhello_appid "fido_assert_t *assert" "const char *id" +.Sh DESCRIPTION +The +.Nm +set of functions define the various parameters of a FIDO2 +assertion, allowing a +.Fa fido_assert_t +type to be prepared for a subsequent call to +.Xr fido_dev_get_assert 3 +or +.Xr fido_assert_verify 3 . +For the complete specification of a FIDO2 assertion and the format +of its constituent parts, please refer to the Web Authentication +(webauthn) standard. +.Pp +The +.Fn fido_assert_set_count +function sets the number of assertion statements in +.Fa assert +to +.Fa n . +.Pp +The +.Fn fido_assert_set_authdata +and +.Fn fido_assert_set_sig +functions set the authenticator data and signature parts of the +statement with index +.Fa idx +of +.Fa assert +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +Please note that the first assertion statement of +.Fa assert +has an +.Fa idx +of +.Em 0 . +The authenticator data passed to +.Fn fido_assert_set_authdata +must be a CBOR-encoded byte string, as obtained from +.Fn fido_assert_authdata_ptr . +Alternatively, a raw binary blob may be passed to +.Fn fido_assert_set_authdata_raw . +.Pp +The +.Fn fido_assert_set_clientdata_hash +function sets the client data hash of +.Fa assert +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +.Pp +The +.Fn fido_assert_set_clientdata +function allows an application to set the client data hash of +.Fa assert +by specifying the assertion's unhashed client data. +This is required by Windows Hello, which calculates the client data +hash internally. +For compatibility with Windows Hello, applications should use +.Fn fido_assert_set_clientdata +instead of +.Fn fido_assert_set_clientdata_hash . +.Pp +The +.Fn fido_assert_set_rp +function sets the relying party +.Fa id +of +.Fa assert , +where +.Fa id +is a NUL-terminated UTF-8 string. +The content of +.Fa id +is copied, and no references to the passed pointer are kept. +.Pp +The +.Fn fido_assert_set_extensions +function sets the extensions of +.Fa assert +to the bitmask +.Fa flags . +At the moment, only the +.Dv FIDO_EXT_CRED_BLOB , +.Dv FIDO_EXT_HMAC_SECRET , +and +.Dv FIDO_EXT_LARGEBLOB_KEY +extensions are supported. +If +.Fa flags +is zero, the extensions of +.Fa assert +are cleared. +.Pp +The +.Fn fido_assert_set_hmac_salt +and +.Fn fido_assert_set_hmac_secret +functions set the hmac-salt and hmac-secret parts of +.Fa assert +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +The HMAC Secret +.Pq hmac-secret +Extension is a CTAP 2.0 extension. +Note that the resulting hmac-secret varies according to whether +user verification was performed by the authenticator. +The +.Fn fido_assert_set_hmac_secret +function is normally only useful when writing tests. +.Pp +The +.Fn fido_assert_set_up +and +.Fn fido_assert_set_uv +functions set the +.Fa up +(user presence) and +.Fa uv +(user verification) +attributes of +.Fa assert . +Both are +.Dv FIDO_OPT_OMIT +by default, allowing the authenticator to use its default settings. +.Pp +The +.Fn fido_assert_set_winhello_appid +function sets the U2F application +.Fa id +.Pq Dq U2F AppID +of +.Fa assert , +where +.Fa id +is a NUL-terminated UTF-8 string. +The content of +.Fa id +is copied, and no references to the passed pointer are kept. +The +.Fn fido_assert_set_winhello_appid +function is a no-op unless +.Fa assert +is passed to +.Xr fido_dev_get_assert 3 +with a device +.Fa dev +on which +.Xr fido_dev_is_winhello 3 +holds true. +In this case, +.Em libfido2 +will instruct Windows Hello to try the assertion twice, +first with the +.Fa id +passed to +.Fn fido_assert_set_rp , +and a second time with the +.Fa id +passed to +.Fn fido_assert_set_winhello_appid . +If the second assertion succeeds, +.Xr fido_assert_rp_id 3 +will point to the U2F AppID once +.Xr fido_dev_get_assert 3 +completes. +This mechanism exists in Windows Hello to ensure U2F backwards +compatibility without the application inadvertently prompting the +user twice. +Note that +.Fn fido_assert_set_winhello_appid +is not needed on platforms offering CTAP primitives, since the +authenticator can be silently probed for the existence of U2F +credentials. +.Pp +Use of the +.Nm +set of functions may happen in two distinct situations: +when asking a FIDO2 device to produce a series of assertion +statements, prior to +.Xr fido_dev_get_assert 3 +(i.e, in the context of a FIDO2 client), or when verifying assertion +statements using +.Xr fido_assert_verify 3 +(i.e, in the context of a FIDO2 server). +.Pp +For a complete description of the generation of a FIDO2 assertion +and its verification, please refer to the FIDO2 specification. +An example of how to use the +.Nm +set of functions can be found in the +.Pa examples/assert.c +file shipped with +.Em libfido2 . +.Sh RETURN VALUES +The +.Nm +functions return +.Dv FIDO_OK +on success. +The error codes returned by the +.Nm +set of functions are defined in +.In fido/err.h . +.Sh SEE ALSO +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_verify 3 , +.Xr fido_dev_get_assert 3 , +.Xr fido_dev_is_winhello 3 diff --git a/static/netbsd/man3/fido_assert_verify.3 b/static/netbsd/man3/fido_assert_verify.3 new file mode 100644 index 00000000..1b79448b --- /dev/null +++ b/static/netbsd/man3/fido_assert_verify.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt FIDO_ASSERT_VERIFY 3 +.Os +.Sh NAME +.Nm fido_assert_verify +.Nd verifies the signature of a FIDO2 assertion statement +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_assert_verify "const fido_assert_t *assert" "size_t idx" "int cose_alg" "const void *pk" +.Sh DESCRIPTION +The +.Fn fido_assert_verify +function verifies whether the signature contained in statement index +.Fa idx +of +.Fa assert +matches the parameters of the assertion. +Before using +.Fn fido_assert_verify +in a sensitive context, the reader is strongly encouraged to make +herself familiar with the FIDO2 assertion statement process +as defined in the Web Authentication (webauthn) standard. +.Pp +A brief description follows: +.Pp +The +.Fn fido_assert_verify +function verifies whether the client data hash, relying party ID, +user presence and user verification attributes of +.Fa assert +have been attested by the holder of the private counterpart of +the public key +.Fa pk +of COSE type +.Fa cose_alg , +where +.Fa cose_alg +is +.Dv COSE_ES256 , +.Dv COSE_ES384 , +.Dv COSE_RS256 , +or +.Dv COSE_EDDSA , +and +.Fa pk +points to a +.Vt es256_pk_t , +.Vt es384_pk_t , +.Vt rs256_pk_t , +or +.Vt eddsa_pk_t +type accordingly. +.Pp +Please note that the first statement in +.Fa assert +has an +.Fa idx +of 0. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_assert_verify +are defined in +.In fido/err.h . +If +statement +.Fa idx +of +.Fa assert +passes verification with +.Fa pk , +then +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 diff --git a/static/netbsd/man3/fido_bio_dev_get_info.3 b/static/netbsd/man3/fido_bio_dev_get_info.3 new file mode 100644 index 00000000..b8fc1043 --- /dev/null +++ b/static/netbsd/man3/fido_bio_dev_get_info.3 @@ -0,0 +1,145 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_DEV_GET_INFO 3 +.Os +.Sh NAME +.Nm fido_bio_dev_get_info , +.Nm fido_bio_dev_enroll_begin , +.Nm fido_bio_dev_enroll_continue , +.Nm fido_bio_dev_enroll_cancel , +.Nm fido_bio_dev_enroll_remove , +.Nm fido_bio_dev_get_template_array , +.Nm fido_bio_dev_set_template_name +.Nd FIDO2 biometric authenticator API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft int +.Fn fido_bio_dev_get_info "fido_dev_t *dev" "fido_bio_info_t *info" +.Ft int +.Fn fido_bio_dev_enroll_begin "fido_dev_t *dev" "fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms" "const char *pin" +.Ft int +.Fn fido_bio_dev_enroll_continue "fido_dev_t *dev" "const fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms" +.Ft int +.Fn fido_bio_dev_enroll_cancel "fido_dev_t *dev" +.Ft int +.Fn fido_bio_dev_enroll_remove "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin" +.Ft int +.Fn fido_bio_dev_get_template_array "fido_dev_t *dev" "fido_bio_template_array_t *template_array" "const char *pin" +.Ft int +.Fn fido_bio_dev_set_template_name "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin" +.Sh DESCRIPTION +The functions described in this page allow biometric +templates on a FIDO2 authenticator to be listed, created, +removed, and customised. +Please note that not all FIDO2 authenticators support biometric +enrollment. +For a description of the types involved, please refer to +.Xr fido_bio_info_new 3 , +.Xr fido_bio_enroll_new 3 , +and +.Xr fido_bio_template 3 . +.Pp +The +.Fn fido_bio_dev_get_info +function populates +.Fa info +with sensor information from +.Fa dev . +.Pp +The +.Fn fido_bio_dev_enroll_begin +function initiates a biometric enrollment on +.Fa dev , +instructing the authenticator to wait +.Fa timeout_ms +milliseconds. +On success, +.Fa template +and +.Fa enroll +will be populated with the newly created template's +information and enrollment status, respectively. +.Pp +The +.Fn fido_bio_dev_enroll_continue +function continues an ongoing enrollment on +.Fa dev , +instructing the authenticator to wait +.Fa timeout_ms +milliseconds. +On success, +.Fa enroll +will be updated to reflect the status of the biometric +enrollment. +.Pp +The +.Fn fido_bio_dev_enroll_cancel +function cancels an ongoing enrollment on +.Fa dev . +.Pp +The +.Fn fido_bio_dev_enroll_remove +function removes +.Fa template +from +.Fa dev . +.Pp +The +.Fn fido_bio_dev_get_template_array +function populates +.Fa template_array +with the templates currently enrolled on +.Fa dev . +.Pp +The +.Fn fido_bio_dev_set_template_name +function sets the friendly name of +.Fa template +on +.Fa dev . +.Sh RETURN VALUES +The error codes returned by +.Fn fido_bio_dev_get_info , +.Fn fido_bio_dev_enroll_begin , +.Fn fido_bio_dev_enroll_continue , +.Fn fido_bio_dev_enroll_cancel , +.Fn fido_bio_dev_enroll_remove , +.Fn fido_bio_dev_get_template_array , +and +.Fn fido_bio_dev_set_template_name +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_bio_enroll_new 3 , +.Xr fido_bio_info_new 3 , +.Xr fido_bio_template 3 diff --git a/static/netbsd/man3/fido_bio_enroll_new.3 b/static/netbsd/man3/fido_bio_enroll_new.3 new file mode 100644 index 00000000..536ba9af --- /dev/null +++ b/static/netbsd/man3/fido_bio_enroll_new.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_ENROLL_NEW 3 +.Os +.Sh NAME +.Nm fido_bio_enroll_new , +.Nm fido_bio_enroll_free , +.Nm fido_bio_enroll_last_status , +.Nm fido_bio_enroll_remaining_samples +.Nd FIDO2 biometric enrollment API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Bd -literal +#define FIDO_BIO_ENROLL_FP_GOOD 0x00 +#define FIDO_BIO_ENROLL_FP_TOO_HIGH 0x01 +#define FIDO_BIO_ENROLL_FP_TOO_LOW 0x02 +#define FIDO_BIO_ENROLL_FP_TOO_LEFT 0x03 +#define FIDO_BIO_ENROLL_FP_TOO_RIGHT 0x04 +#define FIDO_BIO_ENROLL_FP_TOO_FAST 0x05 +#define FIDO_BIO_ENROLL_FP_TOO_SLOW 0x06 +#define FIDO_BIO_ENROLL_FP_POOR_QUALITY 0x07 +#define FIDO_BIO_ENROLL_FP_TOO_SKEWED 0x08 +#define FIDO_BIO_ENROLL_FP_TOO_SHORT 0x09 +#define FIDO_BIO_ENROLL_FP_MERGE_FAILURE 0x0a +#define FIDO_BIO_ENROLL_FP_EXISTS 0x0b +#define FIDO_BIO_ENROLL_FP_DATABASE_FULL 0x0c +#define FIDO_BIO_ENROLL_NO_USER_ACTIVITY 0x0d +#define FIDO_BIO_ENROLL_NO_USER_PRESENCE_TRANSITION 0x0e +.Ed +.Ft fido_bio_enroll_t * +.Fn fido_bio_enroll_new "void" +.Ft void +.Fn fido_bio_enroll_free "fido_bio_enroll_t **enroll_p" +.Ft uint8_t +.Fn fido_bio_enroll_last_status "const fido_bio_enroll_t *enroll" +.Ft uint8_t +.Fn fido_bio_enroll_remaining_samples "const fido_bio_enroll_t *enroll" +.Sh DESCRIPTION +Ongoing FIDO2 biometric enrollments are abstracted in +.Em libfido2 +by the +.Vt fido_bio_enroll_t +type. +.Pp +The functions described in this page allow a +.Vt fido_bio_enroll_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_enroll_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_enroll_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_enroll_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_enroll_free +function releases the memory backing +.Fa *enroll_p , +where +.Fa *enroll_p +must have been previously allocated by +.Fn fido_bio_enroll_new . +On return, +.Fa *enroll_p +is set to NULL. +Either +.Fa enroll_p +or +.Fa *enroll_p +may be NULL, in which case +.Fn fido_bio_enroll_free +is a NOP. +.Pp +The +.Fn fido_bio_enroll_last_status +function returns the enrollment status of +.Fa enroll . +.Pp +The +.Fn fido_bio_enroll_remaining_samples +function returns the number of samples left for +.Fa enroll +to complete. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_template 3 diff --git a/static/netbsd/man3/fido_bio_info_new.3 b/static/netbsd/man3/fido_bio_info_new.3 new file mode 100644 index 00000000..41343068 --- /dev/null +++ b/static/netbsd/man3/fido_bio_info_new.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_INFO_NEW 3 +.Os +.Sh NAME +.Nm fido_bio_info_new , +.Nm fido_bio_info_free , +.Nm fido_bio_info_type , +.Nm fido_bio_info_max_samples +.Nd FIDO2 biometric sensor information API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft fido_bio_info_t * +.Fn fido_bio_info_new "void" +.Ft void +.Fn fido_bio_info_free "fido_bio_info_t **info_p" +.Ft uint8_t +.Fn fido_bio_info_type "const fido_bio_info_t *info" +.Ft uint8_t +.Fn fido_bio_info_max_samples "const fido_bio_info_t *info" +.Sh DESCRIPTION +Biometric sensor metadata is abstracted in +.Em libfido2 +by the +.Vt fido_bio_info_t +type. +.Pp +The functions described in this page allow a +.Vt fido_bio_info_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_info_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_info_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_info_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_info_free +function releases the memory backing +.Fa *info_p , +where +.Fa *info_p +must have been previously allocated by +.Fn fido_bio_info_new . +On return, +.Fa *info_p +is set to NULL. +Either +.Fa info_p +or +.Fa *info_p +may be NULL, in which case +.Fn fido_bio_info_free +is a NOP. +.Pp +The +.Fn fido_bio_info_type +function returns the fingerprint sensor type, which is +.Dv 1 +for touch sensors, and +.Dv 2 +for swipe sensors. +.Pp +The +.Fn fido_bio_info_max_samples +function returns the maximum number of successful samples +required for enrollment. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_enroll_new 3 , +.Xr fido_bio_template 3 diff --git a/static/netbsd/man3/fido_bio_template.3 b/static/netbsd/man3/fido_bio_template.3 new file mode 100644 index 00000000..a8ff8bc3 --- /dev/null +++ b/static/netbsd/man3/fido_bio_template.3 @@ -0,0 +1,202 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_TEMPLATE 3 +.Os +.Sh NAME +.Nm fido_bio_template , +.Nm fido_bio_template_array_count , +.Nm fido_bio_template_array_free , +.Nm fido_bio_template_array_new , +.Nm fido_bio_template_free , +.Nm fido_bio_template_id_len , +.Nm fido_bio_template_id_ptr , +.Nm fido_bio_template_name , +.Nm fido_bio_template_new , +.Nm fido_bio_template_set_id , +.Nm fido_bio_template_set_name +.Nd FIDO2 biometric template API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft fido_bio_template_t * +.Fn fido_bio_template_new "void" +.Ft void +.Fn fido_bio_template_free "fido_bio_template_t **template_p" +.Ft const char * +.Fn fido_bio_template_name "const fido_bio_template_t *template" +.Ft const unsigned char * +.Fn fido_bio_template_id_ptr "const fido_bio_template_t *template" +.Ft size_t +.Fn fido_bio_template_id_len "const fido_bio_template_t *template" +.Ft int +.Fn fido_bio_template_set_id "fido_bio_template_t *template" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_bio_template_set_name "fido_bio_template_t *template" "const char *name" +.Ft fido_bio_template_array_t * +.Fn fido_bio_template_array_new "void" +.Ft void +.Fn fido_bio_template_array_free "fido_bio_template_array_t **array_p" +.Ft size_t +.Fn fido_bio_template_array_count "const fido_bio_template_array_t *array" +.Ft const fido_bio_template_t * +.Fn fido_bio_template "const fido_bio_template_array_t *array" "size_t idx" +.Sh DESCRIPTION +Existing FIDO2 biometric enrollments are abstracted in +.Em libfido2 +by the +.Vt fido_bio_template_t +and +.Vt fido_bio_template_array_t +types. +.Pp +The functions described in this page allow a +.Vt fido_bio_template_t +type to be allocated, deallocated, changed, and inspected, +and a +.Vt fido_bio_template_array_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_template_t +and +.Vt fido_bio_template_array_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_template_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_template_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_template_free +function releases the memory backing +.Fa *template_p , +where +.Fa *template_p +must have been previously allocated by +.Fn fido_bio_template_new . +On return, +.Fa *template_p +is set to NULL. +Either +.Fa template_p +or +.Fa *template_p +may be NULL, in which case +.Fn fido_bio_template_free +is a NOP. +.Pp +The +.Fn fido_bio_template_name +function returns a pointer to a NUL-terminated string containing +the friendly name of +.Fa template , +or NULL if +.Fa template +does not have a friendly name set. +.Pp +The +.Fn fido_bio_template_id_ptr +function returns a pointer to the template id of +.Fa template , +or NULL if +.Fa template +does not have an id. +The corresponding length can be obtained by +.Fn fido_bio_template_id_len . +.Pp +The +.Fn fido_bio_template_set_name +function sets the friendly name of +.Fa template +to +.Fa name . +If +.Fa name +is NULL, the friendly name of +.Fa template +is unset. +.Pp +The +.Fn fido_bio_template_array_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_template_array_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_template_array_free +function releases the memory backing +.Fa *array_p , +where +.Fa *array_p +must have been previously allocated by +.Fn fido_bio_template_array_new . +On return, +.Fa *array_p +is set to NULL. +Either +.Fa array_p +or +.Fa *array_p +may be NULL, in which case +.Fn fido_bio_template_array_free +is a NOP. +.Pp +The +.Fn fido_bio_template_array_count +function returns the number of templates in +.Fa array . +.Pp +The +.Fn fido_bio_template +function returns a pointer to the template at index +.Fa idx +in +.Fa array . +Please note that the first template in +.Fa array +has an +.Fa idx +(index) value of 0. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_bio_template_set_id +and +.Fn fido_bio_template_set_name +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_enroll_new 3 diff --git a/static/netbsd/man3/fido_cbor_info_new.3 b/static/netbsd/man3/fido_cbor_info_new.3 new file mode 100644 index 00000000..a8168c05 --- /dev/null +++ b/static/netbsd/man3/fido_cbor_info_new.3 @@ -0,0 +1,389 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: April 22 2022 $ +.Dt FIDO_CBOR_INFO_NEW 3 +.Os +.Sh NAME +.Nm fido_cbor_info_new , +.Nm fido_cbor_info_free , +.Nm fido_dev_get_cbor_info , +.Nm fido_cbor_info_aaguid_ptr , +.Nm fido_cbor_info_extensions_ptr , +.Nm fido_cbor_info_protocols_ptr , +.Nm fido_cbor_info_transports_ptr , +.Nm fido_cbor_info_versions_ptr , +.Nm fido_cbor_info_options_name_ptr , +.Nm fido_cbor_info_options_value_ptr , +.Nm fido_cbor_info_algorithm_type , +.Nm fido_cbor_info_algorithm_cose , +.Nm fido_cbor_info_algorithm_count , +.Nm fido_cbor_info_certs_name_ptr , +.Nm fido_cbor_info_certs_value_ptr , +.Nm fido_cbor_info_certs_len , +.Nm fido_cbor_info_aaguid_len , +.Nm fido_cbor_info_extensions_len , +.Nm fido_cbor_info_protocols_len , +.Nm fido_cbor_info_transports_len , +.Nm fido_cbor_info_versions_len , +.Nm fido_cbor_info_options_len , +.Nm fido_cbor_info_maxmsgsiz , +.Nm fido_cbor_info_maxcredbloblen , +.Nm fido_cbor_info_maxcredcntlst , +.Nm fido_cbor_info_maxcredidlen , +.Nm fido_cbor_info_maxlargeblob , +.Nm fido_cbor_info_maxrpid_minpinlen , +.Nm fido_cbor_info_minpinlen , +.Nm fido_cbor_info_fwversion , +.Nm fido_cbor_info_uv_attempts , +.Nm fido_cbor_info_uv_modality , +.Nm fido_cbor_info_rk_remaining , +.Nm fido_cbor_info_new_pin_required +.Nd FIDO2 CBOR Info API +.Sh SYNOPSIS +.In fido.h +.Ft fido_cbor_info_t * +.Fn fido_cbor_info_new "void" +.Ft void +.Fn fido_cbor_info_free "fido_cbor_info_t **ci_p" +.Ft int +.Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci" +.Ft const unsigned char * +.Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci" +.Ft const uint8_t * +.Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_transports_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci" +.Ft const bool * +.Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci" +.Ft const char * +.Fn fido_cbor_info_algorithm_type "const fido_cbor_info_t *ci" "size_t idx" +.Ft int +.Fn fido_cbor_info_algorithm_cose "const fido_cbor_info_t *ci" "size_t idx" +.Ft size_t +.Fn fido_cbor_info_algorithm_count "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_certs_name_ptr "const fido_cbor_info_t *ci" +.Ft const uint64_t * +.Fn fido_cbor_info_certs_value_ptr "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_certs_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_transports_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxcredbloblen "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxcredcntlst "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxcredidlen "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxlargeblob "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_maxrpid_minpinlen "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_minpinlen "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_fwversion "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_uv_attempts "const fido_cbor_info_t *ci" +.Ft uint64_t +.Fn fido_cbor_info_uv_modality "const fido_cbor_info_t *ci" +.Ft int64_t +.Fn fido_cbor_info_rk_remaining "const fido_cbor_info_t *ci" +.Ft bool +.Fn fido_cbor_info_new_pin_required "const fido_cbor_info_t *ci" +.Sh DESCRIPTION +The +.Fn fido_cbor_info_new +function returns a pointer to a newly allocated, empty +.Vt fido_cbor_info_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_cbor_info_free +function releases the memory backing +.Fa *ci_p , +where +.Fa *ci_p +must have been previously allocated by +.Fn fido_cbor_info_new . +On return, +.Fa *ci_p +is set to NULL. +Either +.Fa ci_p +or +.Fa *ci_p +may be NULL, in which case +.Fn fido_cbor_info_free +is a NOP. +.Pp +The +.Fn fido_dev_get_cbor_info +function transmits a +.Dv CTAP_CBOR_GETINFO +command to +.Fa dev +and fills +.Fa ci +with attributes retrieved from the command's response. +The +.Fn fido_dev_get_cbor_info +function may block. +.Pp +The +.Fn fido_cbor_info_aaguid_ptr , +.Fn fido_cbor_info_extensions_ptr , +.Fn fido_cbor_info_protocols_ptr , +.Fn fido_cbor_info_transports_ptr , +and +.Fn fido_cbor_info_versions_ptr +functions return pointers to the authenticator attestation GUID, +supported extensions, PIN protocol, transports, and CTAP version +strings of +.Fa ci . +The corresponding length of a given attribute can be +obtained by +.Fn fido_cbor_info_aaguid_len , +.Fn fido_cbor_info_extensions_len , +.Fn fido_cbor_info_protocols_len , +.Fn fido_cbor_info_transports_len , +or +.Fn fido_cbor_info_versions_len . +.Pp +The +.Fn fido_cbor_info_options_name_ptr +and +.Fn fido_cbor_info_options_value_ptr +functions return pointers to the array of option names and their +respective values +in +.Fa ci . +The length of the options array is returned by +.Fn fido_cbor_info_options_len . +.Pp +The +.Fn fido_cbor_info_algorithm_count +function returns the number of supported algorithms in +.Fa ci . +The +.Fn fido_cbor_info_algorithm_cose +function returns the COSE identifier of algorithm +.Fa idx +in +.Fa ci , +or 0 if the COSE identifier is unknown or unset. +The +.Fn fido_cbor_info_algorithm_type +function returns the type of algorithm +.Fa idx +in +.Fa ci , +or NULL if the type is unset. +Please note that the first algorithm in +.Fa ci +has an +.Fa idx +(index) value of 0. +.Pp +The +.Fn fido_cbor_info_certs_name_ptr +and +.Fn fido_cbor_info_certs_value_ptr +functions return pointers to the array of certification names and their +respective values +in +.Fa ci . +The length of the certifications array is returned by +.Fn fido_cbor_info_certs_len . +.Pp +The +.Fn fido_cbor_info_maxmsgsiz +function returns the maximum message size attribute of +.Fa ci . +.Pp +The +.Fn fido_cbor_info_maxcredbloblen +function returns the maximum +.Dq credBlob +length in bytes supported by the authenticator as reported in +.Fa ci . +.Pp +The +.Fn fido_cbor_info_maxcredcntlst +function returns the maximum supported number of credentials in +a single credential ID list as reported in +.Fa ci . +.Pp +The +.Fn fido_cbor_info_maxcredidlen +function returns the maximum supported length of a credential ID +as reported in +.Fa ci . +.Pp +The +.Fn fido_cbor_info_maxrpid_minpinlen +function returns the maximum number of RP IDs that may be passed to +.Xr fido_dev_set_pin_minlen_rpid 3 , +as reported in +.Fa ci . +The minimum PIN length attribute is a CTAP 2.1 addition. +If the attribute is not advertised by the authenticator, the +.Fn fido_cbor_info_maxrpid_minpinlen +function returns zero. +.Pp +The +.Fn fido_cbor_info_maxlargeblob +function returns the maximum length in bytes of an authenticator's +serialized largeBlob array as reported in +.Fa ci . +.Pp +The +.Fn fido_cbor_info_minpinlen +function returns the minimum PIN length enforced by the +authenticator as reported in +.Fa ci . +The minimum PIN length attribute is a CTAP 2.1 addition. +If the attribute is not advertised by the authenticator, the +.Fn fido_cbor_info_minpinlen +function returns zero. +.Pp +The +.Fn fido_cbor_info_fwversion +function returns the firmware version attribute of +.Fa ci . +.Pp +The +.Fn fido_cbor_info_uv_attempts +function returns the number of UV attempts that the platform may +attempt before falling back to PIN authentication. +If 1, then all +.Xr fido_dev_get_uv_retry_count 3 +retries are handled internally by the authenticator and the +platform may only attempt non-PIN UV once. +The UV attempts attribute is a CTAP 2.1 addition. +If the attribute is not advertised by the authenticator, +the +.Fn fido_cbor_info_uv_attempts +function returns zero. +.Pp +The +.Fn fido_cbor_info_uv_modality +function returns a bitmask representing different UV modes +supported by the authenticator, as defined in the FIDO Registry of +Predefined Values and reported in +.Fa ci . +See the +.Em FIDO_UV_MODE_* +definitions in +.In fido/param.h +for the set of values defined by libfido2 and a brief description +of each. +The UV modality attribute is a CTAP 2.1 addition. +If the attribute is not advertised by the authenticator, the +.Fn fido_cbor_info_uv_modality +function returns zero. +.Pp +The +.Fn fido_cbor_info_rk_remaining +function returns the estimated number of additional +resident/discoverable credentials that can be stored on the +authenticator as reported in +.Fa ci . +The estimated number of remaining resident credentials is a +CTAP 2.1 addition. +If the attribute is not advertised by the authenticator, the +.Fn fido_cbor_info_rk_remaining +function returns -1. +.Pp +The +.Fn fido_cbor_info_new_pin_required +function returns whether a new PIN is required by the authenticator +as reported in +.Fa ci . +If +.Fn fido_cbor_info_new_pin_required +returns true, operations requiring PIN authentication will fail +until a new PIN is set on the authenticator. +The +.Xr fido_dev_set_pin 3 +function can be used to set a new PIN. +.Pp +A complete example of how to use these functions can be found in the +.Pa example/info.c +file shipped with +.Em libfido2 . +.Sh RETURN VALUES +The +.Fn fido_cbor_info_aaguid_ptr , +.Fn fido_cbor_info_extensions_ptr , +.Fn fido_cbor_info_protocols_ptr , +.Fn fido_cbor_info_transports_ptr , +.Fn fido_cbor_info_versions_ptr , +.Fn fido_cbor_info_options_name_ptr , +and +.Fn fido_cbor_info_options_value_ptr +functions return NULL if the respective field in +.Fa ci +is absent. +If not NULL, returned pointers are guaranteed to exist until any +API function that takes +.Fa ci +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_dev_get_uv_retry_count 3 , +.Xr fido_dev_open 3 , +.Xr fido_dev_set_pin 3 , +.Xr fido_dev_set_pin_minlen_rpid 3 +.Rs +.%D 2021-05-25 +.%O Review Draft, Version 2.2 +.%Q FIDO Alliance +.%R FIDO Registry of Predefined Values +.%U https://fidoalliance.org/specs/common-specs/fido-registry-v2.2-rd-20210525.html +.Re diff --git a/static/netbsd/man3/fido_cred_exclude.3 b/static/netbsd/man3/fido_cred_exclude.3 new file mode 100644 index 00000000..d5e840d5 --- /dev/null +++ b/static/netbsd/man3/fido_cred_exclude.3 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: December 2 2022 $ +.Dt FIDO_CRED_EXCLUDE 3 +.Os +.Sh NAME +.Nm fido_cred_exclude , +.Nm fido_cred_empty_exclude_list +.Nd manage exclude lists in a FIDO2 credential +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_cred_exclude "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_empty_exclude_list "fido_cred_t *cred" +.Sh DESCRIPTION +The +.Fn fido_cred_exclude +function adds +.Fa ptr +to the list of credentials excluded by +.Fa cred , +where +.Fa ptr +points to a credential ID of +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +If +.Fn fido_cred_exclude +fails, the existing list of excluded credentials is preserved. +.Pp +If +.Nm +returns success and +.Fa cred +is later passed to +.Xr fido_dev_make_cred 3 +on a device that contains the credential +denoted by +.Fa ptr , +then +.Xr fido_dev_make_cred 3 +will fail. +.Pp +For the format of a FIDO2 credential ID, please refer to the +Web Authentication (webauthn) standard. +.Pp +The +.Fn fido_cred_empty_exclude_list +function empties the list of credentials excluded by +.Fa cred . +.Sh RETURN VALUES +The error codes returned by +.Fn fido_cred_exclude +and +.Fn fido_cred_empty_exclude_list +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 , +.Xr fido_dev_make_cred 3 diff --git a/static/netbsd/man3/fido_cred_new.3 b/static/netbsd/man3/fido_cred_new.3 new file mode 100644 index 00000000..79eb06a5 --- /dev/null +++ b/static/netbsd/man3/fido_cred_new.3 @@ -0,0 +1,366 @@ +.\" Copyright (c) 2018-2024 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_NEW 3 +.Os +.Sh NAME +.Nm fido_cred_new , +.Nm fido_cred_free , +.Nm fido_cred_pin_minlen , +.Nm fido_cred_prot , +.Nm fido_cred_fmt , +.Nm fido_cred_rp_id , +.Nm fido_cred_rp_name , +.Nm fido_cred_user_name , +.Nm fido_cred_display_name , +.Nm fido_cred_authdata_ptr , +.Nm fido_cred_authdata_raw_ptr , +.Nm fido_cred_clientdata_hash_ptr , +.Nm fido_cred_id_ptr , +.Nm fido_cred_aaguid_ptr , +.Nm fido_cred_largeblob_key_ptr , +.Nm fido_cred_pubkey_ptr , +.Nm fido_cred_sig_ptr , +.Nm fido_cred_user_id_ptr , +.Nm fido_cred_x5c_list_count , +.Nm fido_cred_x5c_list_ptr , +.Nm fido_cred_x5c_ptr , +.Nm fido_cred_attstmt_ptr , +.Nm fido_cred_authdata_len , +.Nm fido_cred_authdata_raw_len , +.Nm fido_cred_clientdata_hash_len , +.Nm fido_cred_id_len , +.Nm fido_cred_aaguid_len , +.Nm fido_cred_largeblob_key_len , +.Nm fido_cred_pubkey_len , +.Nm fido_cred_sig_len , +.Nm fido_cred_user_id_len , +.Nm fido_cred_x5c_list_len , +.Nm fido_cred_x5c_len , +.Nm fido_cred_attstmt_len , +.Nm fido_cred_entattest , +.Nm fido_cred_type , +.Nm fido_cred_flags , +.Nm fido_cred_sigcount +.Nd FIDO2 credential API +.Sh SYNOPSIS +.In fido.h +.Ft fido_cred_t * +.Fn fido_cred_new "void" +.Ft void +.Fn fido_cred_free "fido_cred_t **cred_p" +.Ft size_t +.Fn fido_cred_pin_minlen "const fido_cred_t *cred" +.Ft int +.Fn fido_cred_prot "const fido_cred_t *cred" +.Ft const char * +.Fn fido_cred_fmt "const fido_cred_t *cred" +.Ft const char * +.Fn fido_cred_rp_id "const fido_cred_t *cred" +.Ft const char * +.Fn fido_cred_rp_name "const fido_cred_t *cred" +.Ft const char * +.Fn fido_cred_user_name "const fido_cred_t *cred" +.Ft const char * +.Fn fido_cred_display_name "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_authdata_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_authdata_raw_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_id_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_aaguid_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_largeblob_key_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_sig_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_user_id_ptr "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_x5c_list_count "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_x5c_list_ptr "const fido_cred_t *cred" "size_t idx" +.Ft const unsigned char * +.Fn fido_cred_x5c_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_attstmt_ptr "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_authdata_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_authdata_raw_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_id_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_aaguid_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_largeblob_key_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_pubkey_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_sig_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_user_id_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_x5c_list_len "const fido_cred_t *cred" "size_t idx" +.Ft size_t +.Fn fido_cred_x5c_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_attstmt_len "const fido_cred_t *cred" +.Ft bool +.Fn fido_cred_entattest "const fido_cred_t *cred" +.Ft int +.Fn fido_cred_type "const fido_cred_t *cred" +.Ft uint8_t +.Fn fido_cred_flags "const fido_cred_t *cred" +.Ft uint32_t +.Fn fido_cred_sigcount "const fido_cred_t *cred" +.Sh DESCRIPTION +FIDO2 credentials are abstracted in +.Em libfido2 +by the +.Vt fido_cred_t +type. +The functions described in this page allow a +.Vt fido_cred_t +type to be allocated, deallocated, and inspected. +For other operations on +.Vt fido_cred_t , +please refer to +.Xr fido_cred_set_authdata 3 , +.Xr fido_cred_exclude 3 , +.Xr fido_cred_verify 3 , +and +.Xr fido_dev_make_cred 3 . +.Pp +The +.Fn fido_cred_new +function returns a pointer to a newly allocated, empty +.Vt fido_cred_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_cred_free +function releases the memory backing +.Fa *cred_p , +where +.Fa *cred_p +must have been previously allocated by +.Fn fido_cred_new . +On return, +.Fa *cred_p +is set to NULL. +Either +.Fa cred_p +or +.Fa *cred_p +may be NULL, in which case +.Fn fido_cred_free +is a NOP. +.Pp +If the CTAP 2.1 +.Dv FIDO_EXT_MINPINLEN +extension is enabled on +.Fa cred , +then the +.Fn fido_cred_pin_minlen +function returns the minimum PIN length of +.Fa cred . +Otherwise, +.Fn fido_cred_pin_minlen +returns zero. +See +.Xr fido_cred_set_pin_minlen 3 +on how to enable this extension. +.Pp +If the CTAP 2.1 +.Dv FIDO_EXT_CRED_PROTECT +extension is enabled on +.Fa cred , +then the +.Fn fido_cred_prot +function returns the protection of +.Fa cred . +Otherwise, +.Fn fido_cred_prot +returns zero. +See +.Xr fido_cred_set_prot 3 +for the protection policies understood by +.Em libfido2 . +.Pp +The +.Fn fido_cred_fmt +function returns a pointer to a NUL-terminated string containing +the attestation statement format identifier of +.Fa cred , +or NULL if +.Fa cred +does not have a format set. +.Pp +The +.Fn fido_cred_rp_id , +.Fn fido_cred_rp_name , +.Fn fido_cred_user_name , +and +.Fn fido_cred_display_name +functions return pointers to NUL-terminated strings holding the +relying party ID, relying party name, user name, and user display +name attributes of +.Fa cred , +or NULL if the respective entry is not set. +.Pp +The +.Fn fido_cred_authdata_ptr , +.Fn fido_cred_authdata_raw_ptr , +.Fn fido_cred_clientdata_hash_ptr , +.Fn fido_cred_id_ptr , +.Fn fido_cred_aaguid_ptr , +.Fn fido_cred_largeblob_key_ptr , +.Fn fido_cred_pubkey_ptr , +.Fn fido_cred_sig_ptr , +.Fn fido_cred_user_id_ptr , +.Fn fido_cred_x5c_ptr , +and +.Fn fido_cred_attstmt_ptr +functions return pointers to the CBOR-encoded and raw authenticator +data, client data hash, ID, authenticator attestation GUID, +.Dq largeBlobKey , +public key, signature, user ID, x509 leaf certificate, and attestation +statement parts of +.Fa cred , +or NULL if the respective entry is not set. +.Pp +The corresponding length can be obtained by +.Fn fido_cred_authdata_len , +.Fn fido_cred_authdata_raw_len , +.Fn fido_cred_clientdata_hash_len , +.Fn fido_cred_id_len , +.Fn fido_cred_aaguid_len , +.Fn fido_cred_largeblob_key_len , +.Fn fido_cred_pubkey_len , +.Fn fido_cred_sig_len , +.Fn fido_cred_user_id_len , +.Fn fido_cred_x5c_len , +and +.Fn fido_cred_attstmt_len . +.Pp +The +.Fn fido_cred_x5c_list_count +function returns the length of the x509 certificate chain in +.Fa cred +and the +.Fn fido_cred_x5c_list_ptr +and +.Fn fido_cred_x5c_list_len +functions return a pointer to and length of the x509 certificate at index +.Fa idx +respectively. +Please note that the leaf certificate has an +.Fa idx +(index) value of 0 and calling +.Fn fido_cred_x5c_list_ptr cred 0 +and +.Fn fido_cred_x5c_list_len cred 0 +is equivalent to +.Fn fido_cred_x5c_ptr cred +and +.Fn fido_cred_x5c_len cred +respectively. +If +.Fa idx +exceeds the return value of +.Fn fido_cred_x5c_list_count , +.Fn fido_cred_x5c_list_ptr +returns NULL and +.Fn fido_cred_x5c_list_len +returns 0. +.Pp +The authenticator data, x509 certificate, and signature parts of a +credential are typically passed to a FIDO2 server for verification. +.Pp +The +.Fn fido_cred_entattest +function returns +.Dv true +if an enterprise attestation was returned for +.Fa cred . +.Pp +The +.Fn fido_cred_type +function returns the COSE algorithm of +.Fa cred . +.Pp +The +.Fn fido_cred_flags +function returns the authenticator data flags of +.Fa cred . +.Pp +The +.Fn fido_cred_sigcount +function returns the authenticator data signature counter of +.Fa cred . +.Sh RETURN VALUES +The authenticator data returned by +.Fn fido_cred_authdata_ptr +is a CBOR-encoded byte string, as obtained from the authenticator. +To obtain the decoded byte string, use +.Fn fido_cred_authdata_raw_ptr . +.Pp +If not NULL, pointers returned by +.Fn fido_cred_fmt , +.Fn fido_cred_authdata_ptr , +.Fn fido_cred_clientdata_hash_ptr , +.Fn fido_cred_id_ptr , +.Fn fido_cred_aaguid_ptr , +.Fn fido_cred_largeblob_key_ptr , +.Fn fido_cred_pubkey_ptr , +.Fn fido_cred_sig_ptr , +and +.Fn fido_cred_x5c_ptr +are guaranteed to exist until any API function that takes +.Fa cred +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_cred_exclude 3 , +.Xr fido_cred_set_authdata 3 , +.Xr fido_cred_set_pin_minlen 3 , +.Xr fido_cred_set_prot 3 , +.Xr fido_cred_verify 3 , +.Xr fido_credman_metadata_new 3 , +.Xr fido_dev_largeblob_get 3 , +.Xr fido_dev_make_cred 3 diff --git a/static/netbsd/man3/fido_cred_set_authdata.3 b/static/netbsd/man3/fido_cred_set_authdata.3 new file mode 100644 index 00000000..a5898774 --- /dev/null +++ b/static/netbsd/man3/fido_cred_set_authdata.3 @@ -0,0 +1,424 @@ +.\" Copyright (c) 2018-2024 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt FIDO_CRED_SET_AUTHDATA 3 +.Os +.Sh NAME +.Nm fido_cred_set_authdata , +.Nm fido_cred_set_authdata_raw , +.Nm fido_cred_set_attstmt , +.Nm fido_cred_set_attobj , +.Nm fido_cred_set_x509 , +.Nm fido_cred_set_sig , +.Nm fido_cred_set_id , +.Nm fido_cred_set_clientdata , +.Nm fido_cred_set_clientdata_hash , +.Nm fido_cred_set_rp , +.Nm fido_cred_set_user , +.Nm fido_cred_set_entattest , +.Nm fido_cred_set_extensions , +.Nm fido_cred_set_blob , +.Nm fido_cred_set_pin_minlen , +.Nm fido_cred_set_prot , +.Nm fido_cred_set_rk , +.Nm fido_cred_set_uv , +.Nm fido_cred_set_fmt , +.Nm fido_cred_set_type +.Nd set parameters of a FIDO2 credential +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef enum { + FIDO_OPT_OMIT = 0, /* use authenticator's default */ + FIDO_OPT_FALSE, /* explicitly set option to false */ + FIDO_OPT_TRUE, /* explicitly set option to true */ +} fido_opt_t; +.Ed +.Ft int +.Fn fido_cred_set_authdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_authdata_raw "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_attstmt "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_attobj "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_x509 "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_sig "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_id "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_clientdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_clientdata_hash "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_rp "fido_cred_t *cred" "const char *id" "const char *name" +.Ft int +.Fn fido_cred_set_user "fido_cred_t *cred" "const unsigned char *user_id" "size_t user_id_len" "const char *name" "const char *display_name" "const char *icon" +.Ft int +.Fn fido_cred_set_entattest "fido_cred_t *cred" "int ea" +.Ft int +.Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags" +.Ft int +.Fn fido_cred_set_blob "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_pin_minlen "fido_cred_t *cred" "size_t len" +.Ft int +.Fn fido_cred_set_prot "fido_cred_t *cred" "int prot" +.Ft int +.Fn fido_cred_set_rk "fido_cred_t *cred" "fido_opt_t rk" +.Ft int +.Fn fido_cred_set_uv "fido_cred_t *cred" "fido_opt_t uv" +.Ft int +.Fn fido_cred_set_fmt "fido_cred_t *cred" "const char *ptr" +.Ft int +.Fn fido_cred_set_type "fido_cred_t *cred" "int cose_alg" +.Sh DESCRIPTION +The +.Nm +set of functions define the various parameters of a FIDO2 +credential, allowing a +.Fa fido_cred_t +type to be prepared for a subsequent call to +.Xr fido_dev_make_cred 3 +or +.Xr fido_cred_verify 3 . +For the complete specification of a FIDO2 credential and the format +of its constituent parts, please refer to the Web Authentication +(webauthn) standard. +.Pp +The +.Fn fido_cred_set_authdata , +.Fn fido_cred_set_attstmt , +.Fn fido_cred_set_attobj , +.Fn fido_cred_set_x509 , +.Fn fido_cred_set_sig , +.Fn fido_cred_set_id , +and +.Fn fido_cred_set_clientdata_hash +functions set the authenticator data, attestation statement, +attestation object, attestation certificate, attestation signature, +id, and client data hash parts of +.Fa cred +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +.Pp +The authenticator data passed to +.Fn fido_cred_set_authdata +must be a CBOR-encoded byte string, as obtained from +.Fn fido_cred_authdata_ptr . +Alternatively, a raw binary blob may be passed to +.Fn fido_cred_set_authdata_raw . +An application calling +.Fn fido_cred_set_authdata +does not need to call +.Fn fido_cred_set_id . +The latter is meant to be used in contexts where the +credential's authenticator data is not available. +.Pp +The attestation statement passed to +.Fn fido_cred_set_attstmt +must be a CBOR-encoded map, as obtained from +.Fn fido_cred_attstmt_ptr . +An application calling +.Fn fido_cred_set_attstmt +does not need to call +.Fn fido_cred_set_x509 +or +.Fn fido_cred_set_sig . +The latter two are meant to be used in contexts where the +credential's complete attestation statement is not available or +required. +.Pp +The attestation object passed to +.Fn fido_cred_set_attobj +must be a CBOR-encoded map containing +.Dq authData , +.Dq fmt , +and +.Dq attStmt . +An application calling +.Fn fido_cred_set_attobj +does not need to call +.Fn fido_cred_set_fmt , +.Fn fido_cred_set_attstmt , +.Fn fido_cred_set_authdata , +or +.Fn fido_cred_set_authdata_raw . +.Fn fido_cred_set_attobj +may be useful in applications interfacing with the WebAuthn API, +removing the need to first parse the attestation object to verify the +credential. +.Pp +The +.Fn fido_cred_set_clientdata +function allows an application to set the client data hash of +.Fa cred +by specifying the credential's unhashed client data. +This is required by Windows Hello, which calculates the client data +hash internally. +For compatibility with Windows Hello, applications should use +.Fn fido_cred_set_clientdata +instead of +.Fn fido_cred_set_clientdata_hash . +.Pp +The +.Fn fido_cred_set_rp +function sets the relying party +.Fa id +and +.Fa name +parameters of +.Fa cred , +where +.Fa id +and +.Fa name +are NUL-terminated UTF-8 strings. +The contents of +.Fa id +and +.Fa name +are copied, and no references to the passed pointers are kept. +.Pp +The +.Fn fido_cred_set_user +function sets the user attributes of +.Fa cred , +where +.Fa user_id +points to +.Fa user_id_len +bytes and +.Fa name , +.Fa display_name , +and +.Fa icon +are NUL-terminated UTF-8 strings. +The contents of +.Fa user_id , +.Fa name , +.Fa display_name , +and +.Fa icon +are copied, and no references to the passed pointers are kept. +Previously set user attributes are flushed. +The +.Fa user_id , +.Fa name , +.Fa display_name , +and +.Fa icon +parameters may be NULL. +.Pp +The +.Fn fido_cred_set_entattest +function sets the enterprise attestation mode of +.Fa cred +to +.Fa ea . +At the moment, only the +.Dv FIDO_ENTATTEST_VENDOR +and +.Dv FIDO_ENTATTEST_PLATFORM +modes are supported. +By default, or if +.Fa ea +is zero, no enterprise attestation is requested. +.Pp +The +.Fn fido_cred_set_extensions +function sets the extensions of +.Fa cred +to the bitmask +.Fa flags . +At the moment, only the +.Dv FIDO_EXT_CRED_BLOB , +.Dv FIDO_EXT_CRED_PROTECT , +.Dv FIDO_EXT_HMAC_SECRET , +.Dv FIDO_EXT_MINPINLEN , +and +.Dv FIDO_EXT_LARGEBLOB_KEY +extensions are supported. +If +.Fa flags +is zero, the extensions of +.Fa cred +are cleared. +.Pp +The +.Fn fido_cred_set_blob +function sets the +.Dq credBlob +to be stored with +.Fa cred +to the data pointed to by +.Fa ptr , +which must be +.Fa len +bytes long. +.Pp +The +.Fn fido_cred_set_pin_minlen +function enables the CTAP 2.1 +.Dv FIDO_EXT_MINPINLEN +extension on +.Fa cred +and sets the expected minimum PIN length of +.Fa cred +to +.Fa len , +where +.Fa len +is greater than zero. +If +.Fa len +is zero, the +.Dv FIDO_EXT_MINPINLEN +extension is disabled on +.Fa cred . +.Pp +The +.Fn fido_cred_set_prot +function enables the CTAP 2.1 +.Dv FIDO_EXT_CRED_PROTECT +extension on +.Fa cred +and sets the protection of +.Fa cred +to the scalar +.Fa prot . +At the moment, only the +.Dv FIDO_CRED_PROT_UV_OPTIONAL , +.Dv FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID , +and +.Dv FIDO_CRED_PROT_UV_REQUIRED +protections are supported. +If +.Fa prot +is zero, the protection of +.Fa cred +is cleared. +.Pp +The +.Fn fido_cred_set_rk +and +.Fn fido_cred_set_uv +functions set the +.Em rk +.Pq resident/discoverable key +and +.Em uv +.Pq user verification +attributes of +.Fa cred . +Both are +.Dv FIDO_OPT_OMIT +by default, allowing the authenticator to use its default settings. +.Pp +The +.Fn fido_cred_set_fmt +function sets the attestation statement format identifier of +.Fa cred +to +.Fa fmt , +where +.Fa fmt +must be +.Vt "packed" +.Pq the format used in FIDO2 , +.Vt "fido-u2f" +.Pq the format used in U2F , +.Vt "tpm" +.Pq the format used by TPM-based authenticators , +or +.Vt "none" . +A copy of +.Fa fmt +is made, and no references to the passed pointer are kept. +Note that not all authenticators support FIDO2 and therefore may only +be able to generate +.Vt fido-u2f +attestation statements. +.Pp +The +.Fn fido_cred_set_type +function sets the type of +.Fa cred to +.Fa cose_alg , +where +.Fa cose_alg +is +.Dv COSE_ES256 , +.Dv COSE_ES384 , +.Dv COSE_RS256 , +or +.Dv COSE_EDDSA . +The type of a credential may only be set once. +Note that not all authenticators support COSE_RS256, COSE_ES384, or +COSE_EDDSA. +.Pp +Use of the +.Nm +set of functions may happen in two distinct situations: +when generating a new credential on a FIDO2 device, prior to +.Xr fido_dev_make_cred 3 +(i.e, in the context of a FIDO2 client), or when validating +a generated credential using +.Xr fido_cred_verify 3 +(i.e, in the context of a FIDO2 server). +.Pp +For a complete description of the generation of a FIDO2 credential +and its verification, please refer to the FIDO2 specification. +A concrete utilisation example of the +.Nm +set of functions can be found in the +.Pa cred.c +example shipped with +.Em libfido2 . +.Sh RETURN VALUES +The error codes returned by the +.Nm +set of functions are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_exclude 3 , +.Xr fido_cred_verify 3 , +.Xr fido_dev_make_cred 3 diff --git a/static/netbsd/man3/fido_cred_verify.3 b/static/netbsd/man3/fido_cred_verify.3 new file mode 100644 index 00000000..95488702 --- /dev/null +++ b/static/netbsd/man3/fido_cred_verify.3 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_VERIFY 3 +.Os +.Sh NAME +.Nm fido_cred_verify , +.Nm fido_cred_verify_self +.Nd verify the attestation signature of a FIDO2 credential +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_cred_verify "const fido_cred_t *cred" +.Ft int +.Fn fido_cred_verify_self "const fido_cred_t *cred" +.Sh DESCRIPTION +The +.Fn fido_cred_verify +and +.Fn fido_cred_verify_self +functions verify whether the attestation signature contained in +.Fa cred +matches the attributes of the credential. +Before using +.Fn fido_cred_verify +or +.Fn fido_cred_verify_self +in a sensitive context, the reader is strongly encouraged to make +herself familiar with the FIDO2 credential attestation process +as defined in the Web Authentication (webauthn) standard. +.Pp +The +.Fn fido_cred_verify +function verifies whether the client data hash, relying party ID, +credential ID, type, protection policy, minimum PIN length, and +resident/discoverable key and user verification attributes of +.Fa cred +have been attested by the holder of the private counterpart of +the public key contained in the credential's x509 certificate. +.Pp +Please note that the x509 certificate itself is not verified. +.Pp +The attestation statement formats supported by +.Fn fido_cred_verify +are +.Em packed , +.Em fido-u2f , +and +.Em tpm . +The attestation type implemented by +.Fn fido_cred_verify +is +.Em Basic Attestation . +.Pp +The +.Fn fido_cred_verify_self +function verifies whether the client data hash, relying party ID, +credential ID, type, protection policy, minimum PIN length, and +resident/discoverable key and user verification attributes of +.Fa cred +have been attested by the holder of the credential's private key. +.Pp +The attestation statement formats supported by +.Fn fido_cred_verify_self +are +.Em packed +and +.Em fido-u2f . +The attestation type implemented by +.Fn fido_cred_verify_self +is +.Em Self Attestation . +.Pp +Other attestation formats and types are not supported. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_cred_verify +and +.Fn fido_cred_verify_self +are defined in +.In fido/err.h . +If +.Fa cred +passes verification, then +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 diff --git a/static/netbsd/man3/fido_credman_metadata_new.3 b/static/netbsd/man3/fido_credman_metadata_new.3 new file mode 100644 index 00000000..122020bd --- /dev/null +++ b/static/netbsd/man3/fido_credman_metadata_new.3 @@ -0,0 +1,349 @@ +.\" Copyright (c) 2019-2021 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: June 28 2019 $ +.Dt FIDO_CREDMAN_METADATA_NEW 3 +.Os +.Sh NAME +.Nm fido_credman_metadata_new , +.Nm fido_credman_rk_new , +.Nm fido_credman_rp_new , +.Nm fido_credman_metadata_free , +.Nm fido_credman_rk_free , +.Nm fido_credman_rp_free , +.Nm fido_credman_rk_existing , +.Nm fido_credman_rk_remaining , +.Nm fido_credman_rk , +.Nm fido_credman_rk_count , +.Nm fido_credman_rp_id , +.Nm fido_credman_rp_name , +.Nm fido_credman_rp_count , +.Nm fido_credman_rp_id_hash_ptr , +.Nm fido_credman_rp_id_hash_len , +.Nm fido_credman_get_dev_metadata , +.Nm fido_credman_get_dev_rk , +.Nm fido_credman_set_dev_rk , +.Nm fido_credman_del_dev_rk , +.Nm fido_credman_get_dev_rp +.Nd FIDO2 credential management API +.Sh SYNOPSIS +.In fido.h +.In fido/credman.h +.Ft fido_credman_metadata_t * +.Fn fido_credman_metadata_new "void" +.Ft fido_credman_rk_t * +.Fn fido_credman_rk_new "void" +.Ft fido_credman_rp_t * +.Fn fido_credman_rp_new "void" +.Ft void +.Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p" +.Ft void +.Fn fido_credman_rk_free "fido_credman_rk_t **rk_p" +.Ft void +.Fn fido_credman_rp_free "fido_credman_rp_t **rp_p" +.Ft uint64_t +.Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata" +.Ft uint64_t +.Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata" +.Ft const fido_cred_t * +.Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx" +.Ft size_t +.Fn fido_credman_rk_count "const fido_credman_rk_t *rk" +.Ft const char * +.Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx" +.Ft const char * +.Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx" +.Ft size_t +.Fn fido_credman_rp_count "const fido_credman_rp_t *rp" +.Ft const unsigned char * +.Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx" +.Ft size_t +.Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx" +.Ft int +.Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin" +.Ft int +.Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin" +.Ft int +.Fn fido_credman_set_dev_rk "fido_dev_t *dev" "fido_cred_t *cred" "const char *pin" +.Ft int +.Fn fido_credman_del_dev_rk "fido_dev_t *dev" "const unsigned char *cred_id" "size_t cred_id_len" "const char *pin" +.Ft int +.Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin" +.Sh DESCRIPTION +The credential management API of +.Em libfido2 +allows resident credentials on a FIDO2 authenticator to be listed, +inspected, modified, and removed. +Please note that not all FIDO2 authenticators support credential +management. +To obtain information on what an authenticator supports, please +refer to +.Xr fido_cbor_info_new 3 . +.Pp +The +.Vt fido_credman_metadata_t +type abstracts credential management metadata. +.Pp +The +.Fn fido_credman_metadata_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_metadata_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_metadata_free +function releases the memory backing +.Fa *metadata_p , +where +.Fa *metadata_p +must have been previously allocated by +.Fn fido_credman_metadata_new . +On return, +.Fa *metadata_p +is set to NULL. +Either +.Fa metadata_p +or +.Fa *metadata_p +may be NULL, in which case +.Fn fido_credman_metadata_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_metadata +function populates +.Fa metadata +with information retrieved from +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rk_existing +function inspects +.Fa metadata +and returns the number of resident credentials on the +authenticator. +The +.Fn fido_credman_rk_remaining +function inspects +.Fa metadata +and returns the estimated number of resident credentials that can +be created on the authenticator. +.Pp +The +.Vt fido_credman_rk_t +type abstracts the set of resident credentials belonging to a +given relying party. +.Pp +The +.Fn fido_credman_rk_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_rk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_rk_free +function releases the memory backing +.Fa *rk_p , +where +.Fa *rk_p +must have been previously allocated by +.Fn fido_credman_rk_new . +On return, +.Fa *rk_p +is set to NULL. +Either +.Fa rk_p +or +.Fa *rk_p +may be NULL, in which case +.Fn fido_credman_rk_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_rk +function populates +.Fa rk +with the set of resident credentials belonging to +.Fa rp_id +in +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rk_count +function returns the number of resident credentials in +.Fa rk . +The +.Fn fido_credman_rk +function returns a pointer to the credential at index +.Fa idx +in +.Fa rk . +Please note that the first credential in +.Fa rk +has an +.Fa idx +(index) value of 0. +.Pp +The +.Fn fido_credman_set_dev_rk +function updates the credential pointed to by +.Fa cred +in +.Fa dev . +The credential id and user id attributes of +.Fa cred +must be set. +See +.Xr fido_cred_set_id 3 +and +.Xr fido_cred_set_user 3 +for details. +Only a credential's user attributes (name, display name) +may be updated at this time. +.Pp +The +.Fn fido_credman_del_dev_rk +function deletes the resident credential identified by +.Fa cred_id +from +.Fa dev , +where +.Fa cred_id +points to +.Fa cred_id_len +bytes. +A valid +.Fa pin +must be provided. +.Pp +The +.Vt fido_credman_rp_t +type abstracts information about a relying party. +.Pp +The +.Fn fido_credman_rp_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_rp_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_rp_free +function releases the memory backing +.Fa *rp_p , +where +.Fa *rp_p +must have been previously allocated by +.Fn fido_credman_rp_new . +On return, +.Fa *rp_p +is set to NULL. +Either +.Fa rp_p +or +.Fa *rp_p +may be NULL, in which case +.Fn fido_credman_rp_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_rp +function populates +.Fa rp +with information about relying parties with resident credentials +in +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rp_count +function returns the number of relying parties in +.Fa rp . +.Pp +The +.Fn fido_credman_rp_id +and +.Fn fido_credman_rp_name +functions return pointers to the id and name of relying party +.Fa idx +in +.Fa rp . +If not NULL, the values returned by these functions point to +NUL-terminated UTF-8 strings. +Please note that the first relying party in +.Fa rp +has an +.Fa idx +(index) value of 0. +.Pp +The +.Fn fido_credman_rp_id_hash_ptr +function returns a pointer to the hashed id of relying party +.Fa idx +in +.Fa rp . +The corresponding length can be obtained by +.Fn fido_credman_rp_id_hash_len . +Please note that the first relying party in +.Fa rp +has an +.Fa idx +(index) value of 0. +.Sh RETURN VALUES +The +.Fn fido_credman_get_dev_metadata , +.Fn fido_credman_get_dev_rk , +.Fn fido_credman_set_dev_rk , +.Fn fido_credman_del_dev_rk , +and +.Fn fido_credman_get_dev_rp +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +Functions returning pointers are not guaranteed to succeed, and +should have their return values checked for NULL. +.Sh SEE ALSO +.Xr fido_cbor_info_new 3 , +.Xr fido_cred_new 3 , +.Xr fido_dev_supports_credman 3 +.Sh CAVEATS +Resident credentials are called +.Dq discoverable credentials +in CTAP 2.1. diff --git a/static/netbsd/man3/fido_dev_enable_entattest.3 b/static/netbsd/man3/fido_dev_enable_entattest.3 new file mode 100644 index 00000000..7617f223 --- /dev/null +++ b/static/netbsd/man3/fido_dev_enable_entattest.3 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2020-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: March 30 2022 $ +.Dt FIDO_DEV_ENABLE_ENTATTEST 3 +.Os +.Sh NAME +.Nm fido_dev_enable_entattest , +.Nm fido_dev_toggle_always_uv , +.Nm fido_dev_force_pin_change , +.Nm fido_dev_set_pin_minlen , +.Nm fido_dev_set_pin_minlen_rpid +.Nd CTAP 2.1 configuration authenticator API +.Sh SYNOPSIS +.In fido.h +.In fido/config.h +.Ft int +.Fn fido_dev_enable_entattest "fido_dev_t *dev" "const char *pin" +.Ft int +.Fn fido_dev_toggle_always_uv "fido_dev_t *dev" "const char *pin" +.Ft int +.Fn fido_dev_force_pin_change "fido_dev_t *dev" "const char *pin" +.Ft int +.Fn fido_dev_set_pin_minlen "fido_dev_t *dev" "size_t len" "const char *pin" +.Ft int +.Fn fido_dev_set_pin_minlen_rpid "fido_dev_t *dev" "const char * const *rpid" "size_t n" "const char *pin" +.Sh DESCRIPTION +The functions described in this page allow configuration of a +CTAP 2.1 authenticator. +.Pp +The +.Fn fido_dev_enable_entattest +function enables the +.Em Enterprise Attestation +feature on +.Fa dev . +.Em Enterprise Attestation +instructs the authenticator to include uniquely identifying +information in subsequent attestation statements. +The +.Fa pin +parameter may be NULL if +.Fa dev +does not have a PIN set. +.Pp +The +.Fn fido_dev_toggle_always_uv +function toggles the +.Dq user verification always +feature on +.Fa dev . +When set, this toggle enforces user verification at the +authenticator level for all known credentials. +If +.Fa dev +supports U2F (CTAP1) and the user verification methods supported by +the authenticator do not allow protection of U2F credentials, the +U2F subsystem will be disabled by the authenticator. +The +.Fa pin +parameter may be NULL if +.Fa dev +does not have a PIN set. +.Pp +The +.Fn fido_dev_force_pin_change +function instructs +.Fa dev +to require a PIN change. +Subsequent PIN authentication attempts against +.Fa dev +will fail until its PIN is changed. +.Pp +The +.Fn fido_dev_set_pin_minlen +function sets the minimum PIN length of +.Fa dev +to +.Fa len . +Minimum PIN lengths may only be increased. +.Pp +The +.Fn fido_dev_set_pin_minlen_rpid +function sets the list of relying party identifiers +.Pq RP IDs +that are allowed to obtain the minimum PIN length of +.Fa dev +through the CTAP 2.1 +.Dv FIDO_EXT_MINPINLEN +extension. +The list of RP identifiers is denoted by +.Fa rpid , +a vector of +.Fa n +NUL-terminated UTF-8 strings. +A copy of +.Fa rpid +is made, and no reference to it or its contents is kept. +The maximum value of +.Fa n +supported by the authenticator can be obtained using +.Xr fido_cbor_info_maxrpid_minpinlen 3 . +.Pp +Configuration settings are reflected in the payload returned by the +authenticator in response to a +.Xr fido_dev_get_cbor_info 3 +call. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_enable_entattest , +.Fn fido_dev_toggle_always_uv , +.Fn fido_dev_force_pin_change , +.Fn fido_dev_set_pin_minlen , +and +.Fn fido_dev_set_pin_minlen_rpid +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cbor_info_maxrpid_minpinlen 3 , +.Xr fido_cred_pin_minlen 3 , +.Xr fido_dev_get_cbor_info 3 , +.Xr fido_dev_reset 3 diff --git a/static/netbsd/man3/fido_dev_get_assert.3 b/static/netbsd/man3/fido_dev_get_assert.3 new file mode 100644 index 00000000..bb2fc43b --- /dev/null +++ b/static/netbsd/man3/fido_dev_get_assert.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt FIDO_DEV_GET_ASSERT 3 +.Os +.Sh NAME +.Nm fido_dev_get_assert +.Nd obtains an assertion from a FIDO2 device +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_get_assert "fido_dev_t *dev" "fido_assert_t *assert" "const char *pin" +.Sh DESCRIPTION +The +.Fn fido_dev_get_assert +function asks the FIDO2 device represented by +.Fa dev +for an assertion according to the following parameters defined in +.Fa assert : +.Pp +.Bl -dash -compact +.It +.Nm relying party ID ; +.It +.Nm client data hash ; +.It +.Nm list of allowed credential IDs ; +.It +.Nm user presence and user verification attributes . +.El +.Pp +See +.Xr fido_assert_set_authdata 3 +for information on how these values are set. +.Pp +If a PIN is not needed to authenticate the request against +.Fa dev , +then +.Fa pin +may be NULL. +Otherwise +.Fa pin +must point to a NUL-terminated UTF-8 string. +.Pp +After a successful call to +.Fn fido_dev_get_assert , +the +.Xr fido_assert_count 3 , +.Xr fido_assert_user_display_name 3 , +.Xr fido_assert_user_icon 3 , +.Xr fido_assert_user_name 3 , +.Xr fido_assert_authdata_ptr 3 , +.Xr fido_assert_user_id_ptr 3 , +.Xr fido_assert_sig_ptr 3 , +and +.Xr fido_assert_sigcount 3 +functions may be invoked on +.Fa assert +to retrieve the various attributes of the generated assertion. +.Pp +Please note that +.Fn fido_dev_get_assert +is synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_get_assert +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 diff --git a/static/netbsd/man3/fido_dev_get_touch_begin.3 b/static/netbsd/man3/fido_dev_get_touch_begin.3 new file mode 100644 index 00000000..f015eff2 --- /dev/null +++ b/static/netbsd/man3/fido_dev_get_touch_begin.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2020 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: August 5 2020 $ +.Dt FIDO_DEV_GET_TOUCH_BEGIN 3 +.Os +.Sh NAME +.Nm fido_dev_get_touch_begin , +.Nm fido_dev_get_touch_status +.Nd asynchronously wait for touch on a FIDO2 authenticator +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_get_touch_begin "fido_dev_t *dev" +.Ft int +.Fn fido_dev_get_touch_status "fido_dev_t *dev" "int *touched" "int ms" +.Sh DESCRIPTION +The functions described in this page allow an application to +asynchronously wait for touch on a FIDO2 authenticator. +This is useful when multiple authenticators are present and +the application needs to know which one to use. +.Pp +The +.Fn fido_dev_get_touch_begin +function initiates a touch request on +.Fa dev . +.Pp +The +.Fn fido_dev_get_touch_status +function continues an ongoing touch request on +.Fa dev , +blocking up to +.Fa ms +milliseconds. +On success, +.Fa touched +will be updated to reflect the touch request status. +If +.Fa touched +is 1, the device was touched, and the touch request is +terminated. +If +.Fa touched +is 0, the application may call +.Fn fido_dev_get_touch_status +to continue the touch request, or +.Fn fido_dev_cancel +to terminate it. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_get_touch_begin +and +.Fn fido_dev_get_touch_status +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh EXAMPLES +Please refer to +.Em examples/select.c +in +.Em libfido2's +source tree. +.Sh SEE ALSO +.Xr fido_dev_cancel 3 +.Sh CAVEATS +The +.Fn fido_dev_get_touch_status +function will cause a command to be transmitted to U2F +authenticators. +These transmissions should not exceed a frequency of 5Hz. diff --git a/static/netbsd/man3/fido_dev_info_manifest.3 b/static/netbsd/man3/fido_dev_info_manifest.3 new file mode 100644 index 00000000..a70a3cb2 --- /dev/null +++ b/static/netbsd/man3/fido_dev_info_manifest.3 @@ -0,0 +1,211 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: March 30 2022 $ +.Dt FIDO_DEV_INFO_MANIFEST 3 +.Os +.Sh NAME +.Nm fido_dev_info_manifest , +.Nm fido_dev_info_new , +.Nm fido_dev_info_free , +.Nm fido_dev_info_ptr , +.Nm fido_dev_info_path , +.Nm fido_dev_info_product , +.Nm fido_dev_info_vendor , +.Nm fido_dev_info_manufacturer_string , +.Nm fido_dev_info_product_string , +.Nm fido_dev_info_set +.Nd FIDO2 device discovery functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen" +.Ft fido_dev_info_t * +.Fn fido_dev_info_new "size_t n" +.Ft void +.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n" +.Ft const fido_dev_info_t * +.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i" +.Ft const char * +.Fn fido_dev_info_path "const fido_dev_info_t *di" +.Ft int16_t +.Fn fido_dev_info_product "const fido_dev_info_t *di" +.Ft int16_t +.Fn fido_dev_info_vendor "const fido_dev_info_t *di" +.Ft const char * +.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di" +.Ft const char * +.Fn fido_dev_info_product_string "const fido_dev_info_t *di" +.Ft int +.Fn fido_dev_info_set "fido_dev_info_t *devlist" "size_t i" "const char *path" "const char *manufacturer" "const char *product" "const fido_dev_io_t *io" "const fido_dev_transport_t *transport" +.Sh DESCRIPTION +The +.Fn fido_dev_info_manifest +function fills +.Fa devlist +with up to +.Fa ilen +FIDO2 devices found by the underlying operating system. +Currently only USB HID devices are supported. +The number of discovered devices is returned in +.Fa olen , +where +.Fa olen +is an addressable pointer. +.Pp +The +.Fn fido_dev_info_new +function returns a pointer to a newly allocated, empty device list +with +.Fa n +available slots. +If memory is not available, NULL is returned. +.Pp +The +.Fn fido_dev_info_free +function releases the memory backing +.Fa *devlist_p , +where +.Fa *devlist_p +must have been previously allocated by +.Fn fido_dev_info_new . +The number +.Fa n +of allocated slots must also be provided. +On return, +.Fa *devlist_p +is set to NULL. +Either +.Fa devlist_p +or +.Fa *devlist_p +may be NULL, in which case +.Fn fido_dev_info_free +is a NOP. +.Pp +The +.Fn fido_dev_info_ptr +function returns a pointer to slot number +.Fa i +of +.Fa devlist . +It is the caller's responsibility to ensure that +.Fa i +is bounded. +Please note that the first slot has index 0. +.Pp +The +.Fn fido_dev_info_path +function returns the filesystem path or subsystem-specific identification +string of +.Fa di . +.Pp +The +.Fn fido_dev_info_product +function returns the product ID of +.Fa di . +.Pp +The +.Fn fido_dev_info_vendor +function returns the vendor ID of +.Fa di . +.Pp +The +.Fn fido_dev_info_manufacturer_string +function returns the manufacturer string of +.Fa di . +If +.Fa di +does not have an associated manufacturer string, +.Fn fido_dev_info_manufacturer_string +returns an empty string. +.Pp +The +.Fn fido_dev_info_product_string +function returns the product string of +.Fa di . +If +.Fa di +does not have an associated product string, +.Fn fido_dev_info_product_string +returns an empty string. +.Pp +An example of how to use the functions described in this document +can be found in the +.Pa examples/manifest.c +file shipped with +.Em libfido2 . +.Pp +The +.Fn fido_dev_info_set +function initializes an entry in a device list allocated by +.Fn fido_dev_info_new +with the specified path, manufacturer, and product strings, and with +the specified I/O handlers and, optionally, transport functions, as +described in +.Xr fido_dev_set_io_functions 3 . +The +.Fa io +argument must be specified; the +.Fa transport +argument may be +.Dv NULL . +The path, I/O handlers, and transport functions will be used +automatically by +.Xr fido_dev_new_with_info 3 +and +.Xr fido_dev_open_with_info 3 . +An application can use this, for example, to substitute mock FIDO2 +devices in testing for the real ones that +.Fn fido_dev_info_manifest +would discover. +.Sh RETURN VALUES +The +.Fn fido_dev_info_manifest +function always returns +.Dv FIDO_OK . +If a discovery error occurs, the +.Fa olen +pointer is set to 0. +.Pp +On success, the +.Fn fido_dev_info_set +function returns +.Dv FIDO_OK . +On error, a different error code defined in +.In fido/err.h +is returned. +.Pp +The pointers returned by +.Fn fido_dev_info_ptr , +.Fn fido_dev_info_path , +.Fn fido_dev_info_manufacturer_string , +and +.Fn fido_dev_info_product_string +are guaranteed to exist until +.Fn fido_dev_info_free +is called on the corresponding device list. diff --git a/static/netbsd/man3/fido_dev_largeblob_get.3 b/static/netbsd/man3/fido_dev_largeblob_get.3 new file mode 100644 index 00000000..12dd3194 --- /dev/null +++ b/static/netbsd/man3/fido_dev_largeblob_get.3 @@ -0,0 +1,216 @@ +.\" Copyright (c) 2020 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: October 26 2020 $ +.Dt FIDO_LARGEBLOB_GET 3 +.Os +.Sh NAME +.Nm fido_dev_largeblob_get , +.Nm fido_dev_largeblob_set , +.Nm fido_dev_largeblob_remove , +.Nm fido_dev_largeblob_get_array , +.Nm fido_dev_largeblob_set_array +.Nd FIDO2 large blob API +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_largeblob_get "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "unsigned char **blob_ptr" "size_t *blob_len" +.Ft int +.Fn fido_dev_largeblob_set "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const unsigned char *blob_ptr" "size_t blob_len" "const char *pin" +.Ft int +.Fn fido_dev_largeblob_remove "fido_dev_t *dev" "const unsigned char *key_ptr" "size_t key_len" "const char *pin" +.Ft int +.Fn fido_dev_largeblob_get_array "fido_dev_t *dev" "unsigned char **cbor_ptr" "size_t *cbor_len" +.Ft int +.Fn fido_dev_largeblob_set_array "fido_dev_t *dev" "const unsigned char *cbor_ptr" "size_t cbor_len" "const char *pin" +.Sh DESCRIPTION +The +.Dq largeBlobs +API of +.Em libfido2 +allows binary blobs residing on a CTAP 2.1 authenticator to be +read, written, and inspected. +.Dq largeBlobs +is a CTAP 2.1 extension. +.Pp +.Dq largeBlobs +are stored as elements of a CBOR array. +Confidentiality is ensured by encrypting each element with a +distinct, credential-bound 256-bit AES-GCM key. +The array is otherwise shared between different credentials and +FIDO2 relying parties. +.Pp +Retrieval of a credential's encryption key is possible during +enrollment with +.Xr fido_cred_set_extensions 3 +and +.Xr fido_cred_largeblob_key_ptr 3 , +during assertion with +.Xr fido_assert_set_extensions 3 +and +.Xr fido_assert_largeblob_key_ptr 3 , +or, in the case of a resident credential, via +.Em libfido2's +credential management API. +.Pp +The +.Dq largeBlobs +CBOR array is opaque to the authenticator. +Management of the array is left at the discretion of FIDO2 clients. +For further details on CTAP 2.1's +.Dq largeBlobs +extension, please refer to the CTAP 2.1 spec. +.Pp +The +.Fn fido_dev_largeblob_get +function retrieves the authenticator's +.Dq largeBlobs +CBOR array and, on success, returns the first blob +.Pq iterating from array index zero +that can be decrypted by +.Fa key_ptr , +where +.Fa key_ptr +points to +.Fa key_len +bytes. +On success, +.Fn fido_dev_largeblob_get +sets +.Fa blob_ptr +to the body of the decrypted blob, and +.Fa blob_len +to the length of the decrypted blob in bytes. +It is the caller's responsibility to free +.Fa blob_ptr . +.Pp +The +.Fn fido_dev_largeblob_set +function uses +.Fa key_ptr +to encrypt +.Fa blob_ptr +and inserts the result in the authenticator's +.Dq largeBlobs +CBOR array. +Insertion happens at the end of the array if no existing element +can be decrypted by +.Fa key_ptr , +or at the position of the first element +.Pq iterating from array index zero +that can be decrypted by +.Fa key_ptr . +.Fa key_len +holds the length of +.Fa key_ptr +in bytes, and +.Fa blob_len +the length of +.Fa blob_ptr +in bytes. +A +.Fa pin +or equivalent user-verification gesture is required. +.Pp +The +.Fn fido_dev_largeblob_remove +function retrieves the authenticator's +.Dq largeBlobs +CBOR array and, on success, drops the first blob +.Pq iterating from array index zero +that can be decrypted by +.Fa key_ptr , +where +.Fa key_ptr +points to +.Fa key_len +bytes. +A +.Fa pin +or equivalent user-verification gesture is required. +.Pp +The +.Fn fido_dev_largeblob_get_array +function retrieves the authenticator's +.Dq largeBlobs +CBOR array and, on success, +sets +.Fa cbor_ptr +to the body of the CBOR array, and +.Fa cbor_len +to its corresponding length in bytes. +It is the caller's responsibility to free +.Fa cbor_ptr . +.Pp +Finally, the +.Fn fido_dev_largeblob_set_array +function sets the authenticator's +.Dq largeBlobs +CBOR array to the data pointed to by +.Fa cbor_ptr , +where +.Fa cbor_ptr +points to +.Fa cbor_len +bytes. +A +.Fa pin +or equivalent user-verification gesture is required. +.Sh RETURN VALUES +The functions +.Fn fido_dev_largeblob_set , +.Fn fido_dev_largeblob_get , +.Fn fido_dev_largeblob_remove , +.Fn fido_dev_largeblob_get_array , +and +.Fn fido_dev_largeblob_set_array +return +.Dv FIDO_OK +on success. +On error, an error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr fido_assert_largeblob_key_len 3 , +.Xr fido_assert_largeblob_key_ptr 3 , +.Xr fido_assert_set_extensions 3 , +.Xr fido_cred_largeblob_key_len 3 , +.Xr fido_cred_largeblob_key_ptr 3 , +.Xr fido_cred_set_extensions 3 , +.Xr fido_credman_get_dev_rk 3 , +.Xr fido_credman_get_dev_rp 3 , +.Xr fido_dev_get_assert 3 , +.Xr fido_dev_make_cred 3 +.Sh CAVEATS +The +.Dq largeBlobs +extension is not meant to be used to store sensitive data. +When retrieved, a credential's +.Dq largeBlobs +encryption key is transmitted in the clear, and an authenticator's +.Dq largeBlobs +CBOR array can be read without user interaction or verification. diff --git a/static/netbsd/man3/fido_dev_make_cred.3 b/static/netbsd/man3/fido_dev_make_cred.3 new file mode 100644 index 00000000..b13f9a14 --- /dev/null +++ b/static/netbsd/man3/fido_dev_make_cred.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_DEV_MAKE_CRED 3 +.Os +.Sh NAME +.Nm fido_dev_make_cred +.Nd generates a new credential on a FIDO2 device +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_make_cred "fido_dev_t *dev" "fido_cred_t *cred" "const char *pin" +.Sh DESCRIPTION +The +.Fn fido_dev_make_cred +function asks the FIDO2 device represented by +.Fa dev +to generate a new credential according to the following parameters +defined in +.Fa cred : +.Pp +.Bl -dash -compact +.It +.Nm type ; +.It +.Nm client data hash ; +.It +.Nm relying party ; +.It +.Nm user attributes ; +.It +.Nm list of excluded credential IDs ; +.It +.Nm resident/discoverable key and user verification attributes . +.El +.Pp +See +.Xr fido_cred_set_authdata 3 +for information on how these values are set. +.Pp +If a PIN is not needed to authenticate the request against +.Fa dev , +then +.Fa pin +may be NULL. +Otherwise +.Fa pin +must point to a NUL-terminated UTF-8 string. +.Pp +After a successful call to +.Fn fido_dev_make_cred , +the +.Xr fido_cred_authdata_ptr 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr fido_cred_x5c_ptr 3 , +and +.Xr fido_cred_sig_ptr 3 +functions may be invoked on +.Fa cred +to retrieve the various parts of the generated credential. +.Pp +Please note that +.Fn fido_dev_make_cred +is synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_make_cred +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 diff --git a/static/netbsd/man3/fido_dev_open.3 b/static/netbsd/man3/fido_dev_open.3 new file mode 100644 index 00000000..f839e267 --- /dev/null +++ b/static/netbsd/man3/fido_dev_open.3 @@ -0,0 +1,316 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_OPEN 3 +.Os +.Sh NAME +.Nm fido_dev_open , +.Nm fido_dev_open_with_info , +.Nm fido_dev_close , +.Nm fido_dev_cancel , +.Nm fido_dev_new , +.Nm fido_dev_new_with_info , +.Nm fido_dev_free , +.Nm fido_dev_force_fido2 , +.Nm fido_dev_force_u2f , +.Nm fido_dev_is_fido2 , +.Nm fido_dev_is_winhello , +.Nm fido_dev_supports_credman , +.Nm fido_dev_supports_cred_prot , +.Nm fido_dev_supports_permissions , +.Nm fido_dev_supports_pin , +.Nm fido_dev_supports_uv , +.Nm fido_dev_has_pin , +.Nm fido_dev_has_uv , +.Nm fido_dev_protocol , +.Nm fido_dev_build , +.Nm fido_dev_flags , +.Nm fido_dev_major , +.Nm fido_dev_minor +.Nd FIDO2 device open/close and related functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_open "fido_dev_t *dev" "const char *path" +.Ft int +.Fn fido_dev_open_with_info "fido_dev_t *dev" +.Ft int +.Fn fido_dev_close "fido_dev_t *dev" +.Ft int +.Fn fido_dev_cancel "fido_dev_t *dev" +.Ft fido_dev_t * +.Fn fido_dev_new "void" +.Ft fido_dev_t * +.Fn fido_dev_new_with_info "const fido_dev_info_t *" +.Ft void +.Fn fido_dev_free "fido_dev_t **dev_p" +.Ft void +.Fn fido_dev_force_fido2 "fido_dev_t *dev" +.Ft void +.Fn fido_dev_force_u2f "fido_dev_t *dev" +.Ft bool +.Fn fido_dev_is_fido2 "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_is_winhello "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_supports_credman "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_supports_cred_prot "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_supports_permissions "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_supports_pin "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_supports_uv "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_has_pin "const fido_dev_t *dev" +.Ft bool +.Fn fido_dev_has_uv "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_protocol "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_build "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_flags "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_major "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_minor "const fido_dev_t *dev" +.Sh DESCRIPTION +The +.Fn fido_dev_open +function opens the device pointed to by +.Fa path , +where +.Fa dev +is a freshly allocated or otherwise closed +.Vt fido_dev_t . +If +.Fa dev +claims to be FIDO2, +.Em libfido2 +will attempt to speak FIDO2 to +.Fa dev . +If that fails, +.Em libfido2 +will fallback to U2F unless the +.Dv FIDO_DISABLE_U2F_FALLBACK +flag was set in +.Xr fido_init 3 . +.Pp +The +.Fn fido_dev_open_with_info +function opens +.Fa dev +as previously allocated using +.Fn fido_dev_new_with_info . +.Pp +The +.Fn fido_dev_close +function closes the device represented by +.Fa dev . +If +.Fa dev +is already closed, +.Fn fido_dev_close +is a NOP. +.Pp +The +.Fn fido_dev_cancel +function cancels any pending requests on +.Fa dev . +.Pp +The +.Fn fido_dev_new +function returns a pointer to a newly allocated, empty +.Vt fido_dev_t . +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_dev_new_with_info +function returns a pointer to a newly allocated +.Vt fido_dev_t +with +.Vt fido_dev_info_t +parameters, for use with +.Xr fido_dev_info_manifest 3 +and +.Fn fido_dev_open_with_info . +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_dev_free +function releases the memory backing +.Fa *dev_p , +where +.Fa *dev_p +must have been previously allocated by +.Fn fido_dev_new . +On return, +.Fa *dev_p +is set to NULL. +Either +.Fa dev_p +or +.Fa *dev_p +may be NULL, in which case +.Fn fido_dev_free +is a NOP. +.Pp +The +.Fn fido_dev_force_fido2 +function can be used to force CTAP2 communication with +.Fa dev , +where +.Fa dev +is an open device. +.Pp +The +.Fn fido_dev_force_u2f +function can be used to force CTAP1 (U2F) communication with +.Fa dev , +where +.Fa dev +is an open device. +.Pp +The +.Fn fido_dev_is_fido2 +function returns +.Dv true +if +.Fa dev +is a FIDO2 device. +.Pp +The +.Fn fido_dev_is_winhello +function returns +.Dv true +if +.Fa dev +is a Windows Hello device. +.Pp +The +.Fn fido_dev_supports_credman +function returns +.Dv true +if +.Fa dev +supports CTAP 2.1 Credential Management. +.Pp +The +.Fn fido_dev_supports_cred_prot +function returns +.Dv true +if +.Fa dev +supports CTAP 2.1 Credential Protection. +.Pp +The +.Fn fido_dev_supports_permissions +function returns +.Dv true +if +.Fa dev +supports CTAP 2.1 UV token permissions. +.Pp +The +.Fn fido_dev_supports_pin +function returns +.Dv true +if +.Fa dev +supports CTAP 2.0 Client PINs. +.Pp +The +.Fn fido_dev_supports_uv +function returns +.Dv true +if +.Fa dev +supports a built-in user verification method. +.Pp +The +.Fn fido_dev_has_pin +function returns +.Dv true +if +.Fa dev +has a CTAP 2.0 Client PIN set. +.Pp +The +.Fn fido_dev_has_uv +function returns +.Dv true +if +.Fa dev +supports built-in user verification and its user verification +feature is configured. +.Pp +The +.Fn fido_dev_protocol +function returns the CTAPHID protocol version identifier of +.Fa dev . +.Pp +The +.Fn fido_dev_build +function returns the CTAPHID build version number of +.Fa dev . +.Pp +The +.Fn fido_dev_flags +function returns the CTAPHID capabilities flags of +.Fa dev . +.Pp +The +.Fn fido_dev_major +function returns the CTAPHID major version number of +.Fa dev . +.Pp +The +.Fn fido_dev_minor +function returns the CTAPHID minor version number of +.Fa dev . +.Pp +For the format and meaning of the CTAPHID parameters returned by +functions above, please refer to the FIDO Client to Authenticator +Protocol (CTAP) specification. +.Sh RETURN VALUES +On success, +.Fn fido_dev_open , +.Fn fido_dev_open_with_info , +and +.Fn fido_dev_close +return +.Dv FIDO_OK . +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr fido_dev_info_manifest 3 , +.Xr fido_dev_set_io_functions 3 , +.Xr fido_init 3 diff --git a/static/netbsd/man3/fido_dev_set_io_functions.3 b/static/netbsd/man3/fido_dev_set_io_functions.3 new file mode 100644 index 00000000..e3e10bae --- /dev/null +++ b/static/netbsd/man3/fido_dev_set_io_functions.3 @@ -0,0 +1,261 @@ +.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_SET_IO_FUNCTIONS 3 +.Os +.Sh NAME +.Nm fido_dev_set_io_functions , +.Nm fido_dev_set_sigmask , +.Nm fido_dev_set_timeout , +.Nm fido_dev_set_transport_functions , +.Nm fido_dev_io_handle +.Nd FIDO2 device I/O interface +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef void *fido_dev_io_open_t(const char *); +typedef void fido_dev_io_close_t(void *); +typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int); +typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t); + +typedef struct fido_dev_io { + fido_dev_io_open_t *open; + fido_dev_io_close_t *close; + fido_dev_io_read_t *read; + fido_dev_io_write_t *write; +} fido_dev_io_t; + +#ifdef _WIN32 +typedef int fido_sigset_t; +#else +typedef sigset_t fido_sigset_t; +#endif + +typedef int fido_dev_rx_t(struct fido_dev *, + uint8_t, unsigned char *, size_t, int); +typedef int fido_dev_tx_t(struct fido_dev *, + uint8_t, const unsigned char *, size_t); + +typedef struct fido_dev_transport { + fido_dev_rx_t *rx; + fido_dev_tx_t *tx; +} fido_dev_transport_t; +.Ed +.Pp +.Ft int +.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io" +.Ft int +.Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask" +.Ft int +.Fn fido_dev_set_timeout "fido_dev_t *dev" "int ms" +.Ft int +.Fn fido_dev_set_transport_functions "fido_dev_t *dev" "const fido_dev_transport_t *t" +.Ft void * +.Fn fido_dev_io_handle "const fido_dev_t *dev" +.Sh DESCRIPTION +The +.Fn fido_dev_set_io_functions +function sets the I/O handlers used by +.Em libfido2 +to talk to +.Fa dev . +By default, these handlers are set to the operating system's native HID or NFC +interfaces. +They are defined as follows: +.Bl -tag -width Ds +.It Vt fido_dev_open_t +Receives a +.Vt const char * +holding a path and opens the corresponding device, returning a +non-NULL opaque pointer on success and NULL on error. +.It Vt fido_dev_close_t +Receives the opaque pointer returned by +.Vt fido_dev_open_t +and closes the device. +.It Vt fido_dev_read_t +Reads a single transmission unit (HID report, APDU) from a device. +The first parameter is the opaque pointer returned by +.Vt fido_dev_open_t . +The second parameter is the read buffer, and the third parameter +is the read buffer size. +The fourth parameter is the number of milliseconds the caller is +willing to sleep, should the call need to block. +If this value holds -1, +.Vt fido_dev_read_t +may block indefinitely. +On success, the number of bytes read is returned. +On error, -1 is returned. +.It Vt fido_dev_write_t +Writes a single transmission unit (HID report, APDU) to +.Fa dev . +The first parameter is the opaque pointer returned by +.Vt fido_dev_open_t . +The second parameter is the write buffer, and the third parameter +is the number of bytes to be written. +A +.Vt fido_dev_write_t +may block. +On success, the number of bytes written is returned. +On error, -1 is returned. +.El +.Pp +When calling +.Fn fido_dev_set_io_functions , +the +.Fa open , +.Fa close , +.Fa read , +and +.Fa write +fields of +.Fa io +may not be NULL. +.Pp +No references to +.Fa io +are held by +.Fn fido_dev_set_io_functions . +.Pp +The +.Fn fido_dev_set_sigmask +function may be used to specify a non-NULL signal mask +.Fa sigmask +to be used while +.Em libfido2's +default I/O handlers wait on +.Fa dev . +On UNIX-like operating systems, +.Vt fido_sigset_t +is defined as +.Vt sigset_t . +On Windows, +.Vt fido_sigset_t +is defined as +.Vt int +and +.Fn fido_dev_set_sigmask +is a no-op. +.Pp +No references to +.Fa sigmask +are held by +.Fn fido_dev_set_sigmask . +.Pp +The +.Fn fido_dev_set_timeout +function informs +.Em libfido2 +not to block for more than +.Fa ms +milliseconds while communicating with +.Fa dev . +If a timeout occurs, the corresponding +.Em fido_dev_* +function will fail with +.Dv FIDO_ERR_RX . +If +.Fa ms +is -1, +then +.Em libfido2 +may block indefinitely. +This is the default behaviour. +When using the Windows Hello backend, +.Fa ms +is used as a guidance and may be overwritten by the platform. +.Pp +The +.Fn fido_dev_set_transport_functions +function sets the transport functions used by +.Em libfido2 +to talk to +.Fa dev . +While the I/O handlers are responsible for sending and receiving +transmission units of initialization and continuation packets already +formatted by +.Em libfido2 , +the transport handlers are responsible for sending and receiving +the CTAPHID commands and data directly, as defined in the FIDO Client +to Authenticator Protocol (CTAP) standard. +They are defined as follows: +.Bl -tag -width Ds +.It Vt fido_dev_tx_t +Receives a device, a CTAPHID command to transmit, a data buffer to +transmit, and the length of the data buffer. +On success, 0 is returned. +On error, -1 is returned. +.It Vt fido_dev_rx_t +Receives a device, a CTAPHID command whose response the caller expects +to receive, a data buffer to receive into, the size of the data buffer +determining the maximum length of a response, and the maximum number of +milliseconds to wait for a response. +On success, the number of bytes read into the data buffer is returned. +On error, -1 is returned. +.El +.Pp +When transport functions are specified, +.Em libfido2 +will use them instead of the +.Dv read +and +.Dv write +functions of the I/O handlers. +However, the I/O handlers must still be specified to open and close the +device. +.Pp +The +.Fn fido_dev_io_handle +function returns the opaque pointer returned by the +.Dv open +function of the I/O handlers. +This is useful mainly for the transport functions, which unlike the I/O +handlers are passed the +.Vt fido_dev_t +pointer instead of the opaque I/O handle. +.Sh RETURN VALUES +On success, +.Fn fido_dev_set_io_functions , +.Fn fido_dev_set_transport_functions , +.Fn fido_dev_set_sigmask , +and +.Fn fido_dev_set_timeout +return +.Dv FIDO_OK . +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr fido_dev_info_manifest 3 , +.Xr fido_dev_open 3 +.Rs +.%D 2021-06-15 +.%O Proposed Standard, Version 2.1 +.%Q FIDO Alliance +.%R Client to Authenticator Protocol (CTAP) +.%U https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html +.Re diff --git a/static/netbsd/man3/fido_dev_set_pin.3 b/static/netbsd/man3/fido_dev_set_pin.3 new file mode 100644 index 00000000..eec062dd --- /dev/null +++ b/static/netbsd/man3/fido_dev_set_pin.3 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_SET_PIN 3 +.Os +.Sh NAME +.Nm fido_dev_set_pin , +.Nm fido_dev_get_retry_count , +.Nm fido_dev_get_uv_retry_count , +.Nm fido_dev_reset +.Nd FIDO2 device management functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_set_pin "fido_dev_t *dev" "const char *pin" "const char *oldpin" +.Ft int +.Fn fido_dev_get_retry_count "fido_dev_t *dev" "int *retries" +.Ft int +.Fn fido_dev_get_uv_retry_count "fido_dev_t *dev" "int *retries" +.Ft int +.Fn fido_dev_reset "fido_dev_t *dev" +.Sh DESCRIPTION +The +.Fn fido_dev_set_pin +function sets the PIN of device +.Fa dev +to +.Fa pin , +where +.Fa pin +is a NUL-terminated UTF-8 string. +If +.Fa oldpin +is not NULL, the device's PIN is changed from +.Fa oldpin +to +.Fa pin , +where +.Fa pin +and +.Fa oldpin +are NUL-terminated UTF-8 strings. +.Pp +The +.Fn fido_dev_get_retry_count +function fills +.Fa retries +with the number of PIN retries left in +.Fa dev +before lock-out, where +.Fa retries +is an addressable pointer. +.Pp +The +.Fn fido_dev_get_uv_retry_count +function fills +.Fa retries +with the number of built-in UV retries left in +.Fa dev +before built-in UV is disabled, where +.Fa retries +is an addressable pointer. +.Pp +The +.Fn fido_dev_reset +function performs a reset on +.Fa dev , +resetting the device's PIN and erasing credentials stored on the +device. +.Pp +Please note that +.Fn fido_dev_set_pin , +.Fn fido_dev_get_retry_count , +.Fn fido_dev_get_uv_retry_count , +and +.Fn fido_dev_reset +are synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_set_pin , +.Fn fido_dev_get_retry_count , +.Fn fido_dev_get_uv_retry_count , +and +.Fn fido_dev_reset +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cbor_info_uv_attempts 3 +.Sh CAVEATS +Regarding +.Fn fido_dev_reset , +the actual user-flow to perform a reset is outside the scope of the +FIDO2 specification, and may therefore vary depending on the +authenticator. +Yubico authenticators will return +.Dv FIDO_ERR_NOT_ALLOWED +if a reset is issued later than 5 seconds after power-up, and +.Dv FIDO_ERR_ACTION_TIMEOUT +if the user fails to confirm the reset by touching the key +within 30 seconds. diff --git a/static/netbsd/man3/fido_init.3 b/static/netbsd/man3/fido_init.3 new file mode 100644 index 00000000..12437e1b --- /dev/null +++ b/static/netbsd/man3/fido_init.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_INIT 3 +.Os +.Sh NAME +.Nm fido_init , +.Nm fido_set_log_handler +.Nd initialise the FIDO2 library +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef void fido_log_handler_t(const char *); +.Ed +.Pp +.Ft void +.Fn fido_init "int flags" +.Ft void +.Fn fido_set_log_handler "fido_log_handler_t *handler" +.Sh DESCRIPTION +The +.Fn fido_init +function initialises the +.Em libfido2 +library. +Its invocation must precede that of any other +.Em libfido2 +function in the context of the executing thread. +.Pp +If +.Dv FIDO_DEBUG +is set in +.Fa flags , +then +debug output will be emitted by +.Em libfido2 +on +.Em stderr . +Alternatively, the +.Ev FIDO_DEBUG +environment variable may be set. +.Pp +If +.Dv FIDO_DISABLE_U2F_FALLBACK +is set in +.Fa flags , +then +.Em libfido2 +will not fallback to U2F in +.Xr fido_dev_open 3 +if a device claims to support FIDO2 but fails to respond to +a CTAP 2.0 greeting. +.Pp +The +.Fn fido_set_log_handler +function causes +.Fa handler +to be called for each log line generated in the context of the +executing thread. +Lines passed to +.Fa handler +include a trailing newline character and are not printed by +.Em libfido2 +on +.Em stderr . +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_cred_new 3 , +.Xr fido_dev_info_manifest 3 , +.Xr fido_dev_open 3 diff --git a/static/netbsd/man3/fido_strerr.3 b/static/netbsd/man3/fido_strerr.3 new file mode 100644 index 00000000..94b48bd6 --- /dev/null +++ b/static/netbsd/man3/fido_strerr.3 @@ -0,0 +1,50 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_STRERR 3 +.Os +.Sh NAME +.Nm fido_strerr +.Nd FIDO2 error codes +.Sh SYNOPSIS +.In fido.h +.Ft const char * +.Fn fido_strerr "int n" +.Sh DESCRIPTION +The +.Fn fido_strerr +function translates the error code +.Fa n +into a readable string, +where +.Fa n +is an error code defined in +.In fido/err.h . +.Fn fido_strerr +never returns NULL. +Returned pointers point to static strings. diff --git a/static/netbsd/man3/finite.3 b/static/netbsd/man3/finite.3 new file mode 100644 index 00000000..6b122374 --- /dev/null +++ b/static/netbsd/man3/finite.3 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91 +.\" $NetBSD: finite.3,v 1.2 2011/08/06 11:09:22 wiz Exp $ +.\" +.Dd July 28, 2011 +.Dt FINITE 3 +.Os +.Sh NAME +.Nm finite , +.Nm finitef +.Nd tests for finite values +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn finite "double x" +.Ft int +.Fn finitef "float x" +.Sh DESCRIPTION +The +.Fn finite +function returns the value 1 when +.Bd -ragged -offset indent +\-\*(If \*(Lt +.Fa x +\*(Lt +\*(If. +.Ed +.Pp +Otherwise a zero is returned +(that is, +.Pf \*(Ba Ns Fa x Ns \*(Ba += \*(If or +.Fa x +is \*(Na). +.Sh SEE ALSO +.Xr isfinite 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -ieee754 . +Note that unlike +.Xr isfinite 3 , +neither function is present in the +.Dv ISO +C-language standards or in the +.Dv IEEE +.Dv POSIX +standards. +.Sh HISTORY +The +.Nm finite +and +.Fn finitef +functions first appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/flockfile.3 b/static/netbsd/man3/flockfile.3 new file mode 100644 index 00000000..1a3ef629 --- /dev/null +++ b/static/netbsd/man3/flockfile.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: flockfile.3,v 1.6 2011/10/15 21:43:19 wiz Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 15, 2011 +.Dt FLOCKFILE 3 +.Os +.Sh NAME +.Nm flockfile , +.Nm ftrylockfile , +.Nm funlockfile +.Nd stdio stream locking functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn flockfile "FILE *file" +.Ft int +.Fn ftrylockfile "FILE *file" +.Ft void +.Fn funlockfile "FILE *file" +.Sh DESCRIPTION +The +.Fn flockfile , +.Fn ftrylockfile , +and +.Fn funlockfile +functions provide applications with explicit control of locking of +stdio stream objects. +They can be used by a thread to execute a sequence of I/O operations +as a unit, without interference from another thread. +.Pp +Locks on stdio streams are recursive, and a lock count is maintained. +stdio streams are created unlocked, with a lock count of zero. +After successful acquisition of the lock, its count is incremented +to one, indicating locked state of the stdio stream. +Each subsequent relock operation performed by the owner thread +increments the lock count by one, and each subsequent unlock +operation performed by the owner thread decrements the lock count by one, +allowing matching lock and unlock operations to be nested. +After its lock count is decremented to zero, the stdio stream returns +to unlocked state, and ownership of the stdio stream is relinquished. +.Pp +The +.Fn flockfile +function acquires the ownership of +.Fa file +for the calling thread. +If +.Fa file +is already owned by another thread, the calling thread is suspended +until the acquisition is possible (i.e., +.Fa file +is relinquished again and the calling thread is scheduled to acquire it). +.Pp +The +.Fn ftrylockfile +function acquires the ownership of +.Fa file +for the calling thread only if +.Fa file +is available. +.Pp +The +.Fn funlockfile +function relinquishes the ownership of +.Fa file +previously granted to the calling thread. +Only the current owner of +.Fa file +may +.Fn funlockfile +it. +.Sh RETURN VALUES +If successful, the +.Fn ftrylockfile +function returns 0. +Otherwise, it returns non-zero to indicate that the lock cannot be acquired. +.Sh SEE ALSO +.Xr flock 2 , +.Xr getc_unlocked 3 , +.Xr getchar_unlocked 3 , +.Xr lockf 3 , +.Xr putc_unlocked 3 , +.Xr putchar_unlocked 3 +.Sh STANDARDS +The +.Fn flockfile , +.Fn ftrylockfile +and +.Fn funlockfile +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn flockfile +function first appeared in +.Fx 2.0 . +.Sh BUGS +The design of these interfaces does not allow for addressing the +problem of priority inversion. diff --git a/static/netbsd/man3/fma.3 b/static/netbsd/man3/fma.3 new file mode 100644 index 00000000..1be8dc75 --- /dev/null +++ b/static/netbsd/man3/fma.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: fma.3,v 1.3 2017/09/27 10:12:47 maya Exp $ +.\" Copyright (c) 2005 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/msun/man/fma.3 152755 2005-11-24 09:25:10Z joel $ +.\" +.Dd September 27, 2017 +.Dt FMA 3 +.Os +.Sh NAME +.Nm fma , +.Nm fmaf , +.Nm fmal +.Nd fused multiply-add +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn fma "double x" "double y" "double z" +.Ft float +.Fn fmaf "float x" "float y" "float z" +.Ft long double +.Fn fmal "long double x" "long double y" "long double z" +.Sh DESCRIPTION +The +.Fn fma , +.Fn fmaf , +and +.Fn fmal +functions return +.No "(x * y) + z" , +computed with only one rounding error. +Using the ordinary multiplication and addition operators, by contrast, +results in two roundings: one for the intermediate product and one for +the final result. +.Pp +For instance, the expression +.No "1.2e100 * 2.0e208 - 1.4e308" +produces \*(If due to overflow in the intermediate product, whereas +.No "fma(1.2e100, 2.0e208, -1.4e308)" +returns approximately 1.0e308. +.Pp +The fused multiply-add operation is often used to improve the +accuracy of calculations such as dot products. +It may also be used to improve performance on machines that implement +it natively. +The macros +.Dv FP_FAST_FMA , +.Dv FP_FAST_FMAF +and +.Dv FP_FAST_FMAL +may be defined in +.In math.h +to indicate that +.Fn fma , +.Fn fmaf , +and +.Fn fmal +(respectively) have comparable or faster speed than a multiply +operation followed by an add operation. +.Sh IMPLEMENTATION NOTES +In general, these routines will behave as one would expect if +.No "x * y + z" +were computed with unbounded precision and range, +then rounded to the precision of the return type. +However, on some platforms, if +.Fa z +is \*(Na, these functions may not raise an exception even +when the computation of +.No "x * y" +would have otherwise generated an invalid exception. +.Sh SEE ALSO +.Xr fenv 3 , +.Xr math 3 +.Sh STANDARDS +The +.Fn fma , +.Fn fmaf , +and +.Fn fmal +functions conform to +.St -isoC-99 . +A fused multiply-add operation with virtually identical +characteristics appears in IEEE draft standard 754R. +.Sh HISTORY +The +.Fn fma +and +.Fn fmaf +routines first appeared in +.Fx 5.4 , +and +.Fn fmal +appeared in +.Fx 6.0 . +The +.Fn fma , +.Fn fmaf +and +.Fn fmal +routines were imported into +.Nx +in +.Nx 7.0 . diff --git a/static/netbsd/man3/fmax.3 b/static/netbsd/man3/fmax.3 new file mode 100644 index 00000000..0eefc9be --- /dev/null +++ b/static/netbsd/man3/fmax.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2004 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/msun/man/fmax.3,v 1.2 2005/01/14 09:12:05 ru Exp $ +.\" $NetBSD: fmax.3,v 1.2 2010/03/08 02:35:50 snj Exp $ +.\" +.Dd June 29, 2004 +.Dt FMAX 3 +.Os +.Sh NAME +.Nm fmax , +.Nm fmaxf , +.Nm fmaxl , +.Nm fmin , +.Nm fminf , +.Nm fminl +.Nd floating-point maximum and minimum functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn fmax "double x" "double y" +.Ft float +.Fn fmaxf "float x" "float y" +.Ft "long double" +.Fn fmaxl "long double x" "long double y" +.Ft double +.Fn fmin "double x" "double y" +.Ft float +.Fn fminf "float x" "float y" +.Ft "long double" +.Fn fminl "long double x" "long double y" +.Sh DESCRIPTION +The +.Fn fmax , +.Fn fmaxf , +and +.Fn fmaxl +functions return the larger of +.Fa x +and +.Fa y , +and likewise, the +.Fn fmin , +.Fn fminf , +and +.Fn fminl +functions return the smaller of +.Fa x +and +.Fa y . +They treat +.Li +0.0 +as being larger than +.Li -0.0 . +If one argument is an \*(Na, then the other argument is returned. +If both arguments are \*(Nas, then the result is an \*(Na. +These routines do not raise any floating-point exceptions. +.Sh SEE ALSO +.Xr fabs 3 , +.Xr fdim 3 , +.Xr math 3 +.Sh STANDARDS +The +.Fn fmax , +.Fn fmaxf , +.Fn fmaxl , +.Fn fmin , +.Fn fminf , +and +.Fn fminl +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 +and +.Nx 5.1 . diff --git a/static/netbsd/man3/fmemopen.3 b/static/netbsd/man3/fmemopen.3 new file mode 100644 index 00000000..b2dff192 --- /dev/null +++ b/static/netbsd/man3/fmemopen.3 @@ -0,0 +1,194 @@ +.\" $NetBSD: fmemopen.3,v 1.9 2015/09/06 03:10:50 pgoyette Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 5, 2015 +.Dt FMEMOPEN 3 +.Os +.Sh NAME +.Nm fmemopen +.Nd open a stream that points to a memory buffer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode" +.Sh DESCRIPTION +The +.Fn fmemopen +function +associates a stream with the given +.Fa buffer +and +.Fa size . +The +.Fa buffer +can be either +.Dv NULL , +or must be of the given +.Fa size . +If the +.Fa buffer +is +.Dv NULL , +a +.Fa buffer +of the given +.Fa size +will be dynamically allocated using +.Xr malloc 3 +and freed when +.Xr fclose 3 +is called. +.Pp +The +.Fa mode +argument has the same meaning as in +.Xr fopen 3 . +.Pp +The stream treats the buffer as it would treat a file tracking the current +position to perform I/O operations. +For example, in the beginning the stream points to the beginning of the buffer, +unless +.Dv a +was specified in the +.Fa mode +argument, and then it points to the first +.Dv NUL +byte. +If a +.Dv NULL +.Fa buffer +was specified, then the stream will always point at the first byte of the +.Fa buffer . +.Pp +The stream also keeps track of the +.Fa size +of the +.Fa buffer . +The +.Fa size +is initialized depending on the mode: +.Bl -tag -width r/w+ +.It Dv r/r+ +Set to the +.Fa size +argument. +.It Dv w/w+ +Set to +.Dv 0 . +.It Dv a/a+ +Set to the first +.Dv NUL +byte, or the +.Fa size +argument if one is not found. +.El +.Pp +Read or write operations advance the buffer, but not to exceed the given +.Fa size +of the +.Fa buffer . +Trying to read beyond the +.Fa size +of the +.Fa buffer +results in +.Dv EOF +returned. +.Dv NUL +bytes are read normally. +Trying to write beyond the +.Fa size +of the +.Fa buffer +has no effect. +.Pp +When a stream open for writing is either flushed or closed, a +.Dv NUL +byte is written at the current position or at the end of the current +.Fa size +as kept internally, if there is room. +.Sh RETURN VALUES +Upon successful completion, +.Fn fmemopen +returns a +.Dv FILE +pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa size +was +.Dv 0 ; +or the +.Fa mode +argument is invalid; +or the +.Fa buffer +argument is +.Dv NULL +and the +.Fa mode +argument does not specify a +.Dv + . +.El +.Pp +The +.Fn fmemopen +function +may also fail and set +.Va errno +for any of the errors +specified for the routine +.Xr malloc 3 . +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr malloc 3 +.Sh STANDARDS +The +.Fn fmemopen +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn fmemopen +function first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/fmod.3 b/static/netbsd/man3/fmod.3 new file mode 100644 index 00000000..ba2aeeec --- /dev/null +++ b/static/netbsd/man3/fmod.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)fmod.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: fmod.3,v 1.12 2013/11/12 16:48:39 joerg Exp $ +.\" +.Dd November 12, 2013 +.Dt FMOD 3 +.Os +.Sh NAME +.Nm fmod , +.Nm fmodf , +.Nm fmodl +.Nd floating-point remainder function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn fmod "double x" "double y" +.Ft float +.Fn fmodf "float x" "float y" +.Ft long double +.Fn fmodl "long double x" "long double y" +.Sh DESCRIPTION +The +.Fn fmod +function computes the floating-point remainder of +.Fa x Ns / Fa y . +.Sh RETURN VALUES +The +.Fn fmod , +.Fn fmodf , +and +.Fn fmodl +functions return the value +.Sm off +.Fa x - Em i * Fa y , +.Sm on +for some integer +.Em i +such that, if +.Fa y +is non-zero, the result has the same sign as +.Fa x +and magnitude less than the magnitude of +.Fa y . +If +.Fa y +is zero, whether a domain error occurs or the +.Fn fmod +function returns zero is implementation-defined. +.Sh SEE ALSO +.Xr math 3 +.Sh STANDARDS +The +.Fn fmod +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/fmtcheck.3 b/static/netbsd/man3/fmtcheck.3 new file mode 100644 index 00000000..8907521c --- /dev/null +++ b/static/netbsd/man3/fmtcheck.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: fmtcheck.3,v 1.8 2014/06/14 08:18:24 apb Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This file was contributed to The NetBSD Foundation by Allen Briggs. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 14, 2014 +.Dt FMTCHECK 3 +.Os +.Sh NAME +.Nm fmtcheck +.Nd sanitizes user-supplied printf(3)-style format string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft const char * +.Fn fmtcheck "const char *fmt_suspect" "const char *fmt_default" +.Sh DESCRIPTION +The +.Nm +function scans +.Fa fmt_suspect +and +.Fa fmt_default +to determine if +.Fa fmt_suspect +will consume the same argument types as +.Fa fmt_default +and to ensure that +.Fa fmt_suspect +is a valid format string. +.Pp +The +.Xr printf 3 +family of functions can not verify the types of arguments that they are +passed at run-time. +In some cases, like +.Xr catgets 3 , +it is useful or necessary to use a user-supplied format string with no +guarantee that the format string matches the specified parameters. +.Pp +The +.Nm +function was designed to be used in these cases, as in: +.Bd -literal -offset indent +printf(fmtcheck(user_format, standard_format), arg1, arg2); +.Ed +.Pp +In the check, field widths, fillers, precisions, etc. are ignored (unless +the field width or precision is an asterisk +.Ql * +instead of a digit string). +Also, any text other than the format specifiers is completely ignored. +.Pp +Note that the formats may be quite different as long as they accept the +same parameters. +For example, "%ld %o %30s %#llx %-10.*e %n" is +compatible with "This number %lu %d%% and string %s has %qd numbers +and %.*g floats (%n)." +However, "%o" is not equivalent to "%lx" because +the first requires an integer and the second requires a long, +and "%p" is not equivalent to "%lu" because +the first requires a pointer and the second requires a long. +.Sh RETURN VALUES +If +.Fa fmt_suspect +is a valid format and consumes the same argument types as +.Fa fmt_default , +then the +.Nm +function will return +.Fa fmt_suspect . +Otherwise, it will return +.Fa fmt_default . +.Sh SEE ALSO +.Xr printf 3 diff --git a/static/netbsd/man3/fmtmsg.3 b/static/netbsd/man3/fmtmsg.3 new file mode 100644 index 00000000..d07a796a --- /dev/null +++ b/static/netbsd/man3/fmtmsg.3 @@ -0,0 +1,220 @@ +.\" $NetBSD: fmtmsg.3,v 1.8 2023/01/22 13:38:48 rillig Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2011 +.Dt FMTMSG 3 +.Os +.Sh NAME +.Nm fmtmsg +.Nd format and display a message +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fmtmsg.h +.Ft int +.Fn fmtmsg "long classification" "const char *label" "int severity" "const char *text" "const char *action" "const char *tag" +.Sh DESCRIPTION +The +.Fn fmtmsg +function can be used to display messages in the specified format. +Messages may be written either to standard error, to the console, or both. +.Pp +A formatted message consists of up to five components specified in +.Fa label , +.Fa severity , +.Fa text , +.Fa action +and +.Fa tag . +Further information such as the origin of the message, the recoverability +from the condition causing the message and where to display the message +is specified in +.Fa classification . +.Ss Classification +The +.Fa classification +argument consists of a major classification and several sub-classifications. +It has no effect on the content of the message displayed. +With the exception of the display sub-classification, only a single identifier +may be specified for each (sub-)classification. +The following classifications +are available: +.Bl -tag -width "XXX" +.It Em Major classifications +The source of the condition. +Available identifiers are: +.Dv MM_HARD +(hardware), +.Dv MM_SOFT +(software), and +.Dv MM_FIRM +(firmware). +.It Em Message source sub-classifications +The type of software detecting the condition. +Available identifiers are: +.Dv MM_APPL +(application), +.Dv MM_UTIL +(utility), and +.Dv MM_OPSYS +(operating system). +.It Em Display sub-classifications +The displays the formatted messages is to be written to. +Available identifiers are: +.Dv MM_PRINT +(standard error stream) and +.Dv MM_CONSOLE +(system console). +.It Em Status sub-classifications +The capability of the calling software to recover from the condition. +Available identifiers are: +.Dv MM_RECOVER +(recoverable) and +.Dv MM_NRECOV +(non-recoverable). +.El +.Pp +If no +.Fa classification +is to be supplied, +.Dv MM_NULLMC +must be specified. +.Ss Label +The +.Fa label +argument identifies the source of the message. +It consists of two fields separated by a colon (:). +The first field is up to 10 characters, the second is up to 14 characters. +.Pp +If no +.Fa label +is to be supplied, +.Dv MM_NULLLBL +must be specified. +.Ss Severity +The seriousness of the condition causing the message. +The following +.Fa severity +levels are available: +.Bl -tag -width MM_WARNING -offset indent +.It Dv MM_HALT +The software has encountered a severe fault and is halting. +.It Dv MM_ERROR +The software has encountered a fault. +.It Dv MM_WARNING +The software has encountered an unusual non-fault condition. +.It Dv MM_INFO +The software informs about a non-error condition. +.El +.Pp +If no +.Fa severity +level is to be supplied, +.Dv MM_NOSEV +must be specified. +.Ss Text +The description of the condition the software encountered. +The character +string is not limited to a specific size. +.Pp +If no +.Fa text +is to be supplied, +.Dv MM_NOTXT +must be specified. +.Ss Action +The first step to be taken to recover from the condition the software +encountered; it will be preceded by the prefix +.Dq TO FIX: . +The character string is not limited to a specific size. +.Pp +If no +.Fa action +is to be supplied, +.Dv MM_NOACT +must be specified. +.Ss Tag +The on-line documentation which provides further information about the +condition and the message, such as +.Dq Xr fmtmsg 3 . +The character string is not limited to a specific size. +.Pp +If no +.Fa tag +is to be supplied, +.Dv MM_NOTAG +must be specified. +.Pp +Further effect on the formatting of the message as displayed on the +standard error stream (but not on the system console!) may be taken by +setting the +.Ev MSGVERB +environment variable, which selects the subset of message components +to be printed. +It consists of a colon-separated list of the optional keywords +.Fa label , +.Fa severity , +.Fa text , +.Fa action , +and +.Fa tag , +which correspond to the arguments to +.Fn fmtmsg +with the same names. +If +.Ev MSGVERB +is either not set or malformed (containing empty or unknown keywords), +its content is ignored and all message components will be selected. +.Pp +Note that displaying a message on the system console may fail due to +inappropriate privileges or a non-permissive file mode of the console device. +.Sh RETURN VALUES +The +.Fn fmtmsg +function returns one of the following values: +.Bl -tag -width MM_NOTOKXXX +.It Dv MM_OK +The function succeeded. +.It Dv MM_NOTOK +The function failed completely. +.It Dv MM_NOMSG +The function was unable to generate a message on standard error, +but otherwise succeeded. +.It Dv MM_NOCOM +The function was unable to generate a message on the console, +but otherwise succeeded. +.El +.Sh SEE ALSO +.Xr printf 3 , +.Xr syslog 3 +.Sh STANDARDS +The +.Fn fmtmsg +function conforms to +.St -xsh5 . diff --git a/static/netbsd/man3/fnmatch.3 b/static/netbsd/man3/fnmatch.3 new file mode 100644 index 00000000..e1468869 --- /dev/null +++ b/static/netbsd/man3/fnmatch.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: fnmatch.3,v 1.22 2010/11/30 21:03:07 jruoho Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Guido van Rossum. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fnmatch.3 8.3 (Berkeley) 4/28/95 +.\" +.Dd November 30, 2010 +.Dt FNMATCH 3 +.Os +.Sh NAME +.Nm fnmatch +.Nd match filename or pathname using shell glob rules +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fnmatch.h +.Ft int +.Fn fnmatch "const char *pattern" "const char *string" "int flags" +.Sh DESCRIPTION +The +.Fn fnmatch +function +matches patterns according to the globbing rules used by the shell. +It checks the string specified by the +.Fa string +argument to see if it matches the pattern specified by the +.Fa pattern +argument. +.Pp +The +.Fa flags +argument modifies the interpretation of +.Fa pattern +and +.Fa string . +The value of +.Fa flags +is the bitwise inclusive +.Tn OR +of any of the following +constants, which are defined in the include file +.Pa fnmatch.h . +.Bl -tag -width FNM_LEADING_DIRXX +.It Dv FNM_NOESCAPE +Normally, every occurrence of a backslash +.Pq Ql \e +followed by a character in +.Fa pattern +is replaced by that character. +This is done to negate any special meaning for the character. +If the +.Dv FNM_NOESCAPE +flag is set, a backslash character is treated as an ordinary character. +.It Dv FNM_PATHNAME +Slash characters in +.Fa string +must be explicitly matched by slashes in +.Fa pattern . +If this flag is not set, then slashes are treated as regular characters. +.It Dv FNM_PERIOD +Leading periods in strings match periods in patterns. +The definition of ``leading'' is related to the specification of +.Dv FNM_PATHNAME . +A period is always ``leading'' if it is the first character in +.Ar string . +Additionally, if +.Dv FNM_PATHNAME +is set, +a period is ``leading'' if it immediately follows a slash. +.It Dv FNM_LEADING_DIR +Ignore +.Dq /* +rest after successful +.Fa pattern +matching. +.It Dv FNM_CASEFOLD +The pattern is matched in a case-insensitive fashion. +.El +.Sh RETURN VALUES +The +.Fn fnmatch +function returns zero if +.Fa string +matches the pattern specified by +.Fa pattern , +otherwise, it returns the value +.Dv FNM_NOMATCH . +.Sh SEE ALSO +.Xr sh 1 , +.Xr glob 3 , +.Xr regex 3 , +.Xr glob 7 +.Sh STANDARDS +The +.Fn fnmatch +function conforms to +.St -p1003.2-92 . +The +.Dv FNM_CASEFOLD +flag is a +.Nx +extension. +.Sh HISTORY +The +.Fn fnmatch +function first appeared in +.Bx 4.4 . +.Sh BUGS +The pattern +.Ql * +matches the empty string, even if +.Dv FNM_PATHNAME +is specified. diff --git a/static/netbsd/man3/fopen.3 b/static/netbsd/man3/fopen.3 new file mode 100644 index 00000000..71fd3cf2 --- /dev/null +++ b/static/netbsd/man3/fopen.3 @@ -0,0 +1,326 @@ +.\" $NetBSD: fopen.3,v 1.36 2019/09/02 00:32:55 sevan Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 2, 2019 +.Dt FOPEN 3 +.Os +.Sh NAME +.Nm fopen , +.Nm fdopen , +.Nm freopen +.Nd stream open functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn fopen "const char * restrict path" "const char * restrict mode" +.Ft FILE * +.Fn fdopen "int fildes" "const char *mode" +.Ft FILE * +.Fn freopen "const char * restrict path" "const char * restrict mode" "FILE * restrict stream" +.Sh DESCRIPTION +The +.Fn fopen +function +opens the file whose name is the string pointed to by +.Fa path +and associates a stream with it. +.Pp +The argument +.Fa mode +points to a string beginning with one of the following +sequences, which may be followed by additional modifiers +as indicated below: +.Bl -tag -width 4n +.It Dq Li a +Append; open an existing or new file for writing in append mode. +The file is created if it does not exist. +.It Dq Li a+ +Open for reading and writing in append mode. +The file is created if it does not exist. +.It Dq Li r +Read; open an existing file for reading. +.It Dq Li r+ +Open an existing file for reading and writing. +.It Dq Li w +Write; open an empty file for writing. +Truncate an existing file to zero length or create a new file. +.It Dq Li w+ +Open an empty file for reading and writing. +Truncate file to zero length or create file. +.El +.Pp +After one of those, the +.Fa mode +string can also include one or more of the following modifier letters: +.Bl -tag -width 4n +.It Sq b +The letter +.Sq b +may appear either as a last character or as a character between the +characters in any of the two-character strings described above. +This is strictly for compatibility with +.St -ansiC , +where it means open in +.Dq binary +mode which is identical to text mode here, +so has no effect; the +.Sq b +is ignored. +.It Sq e +The letter +.Sq e +in the mode string sets the close-on-exec +.Pq Dv O_CLOEXEC +flag of the file descriptor, which means that it will not be available +after an +.Xr exec 3 +system call. +This is a non +.St -ansiC +extension. +.It Sq f +The letter +.Sq f +in the mode string restricts +.Fn fopen +to regular files; if the file opened is not a regular file, +.Fn fopen +will close it, and fail. +This is a non +.St -ansiC +extension. +.It Sq l +The letter +.Sq l +in the mode string turns the don't-follow-symlinks +.Pq Dv O_NOFOLLOW +flag of the file descriptor, which means that if the last path component +is a symbolic link, it will not be followed. +This is a non +.St -ansiC +extension. +.It Sq x +The letter +.Sq x +in the mode turns on exclusive open mode to the file +.Pq Dv O_EXCL +which means that the file will not be created if it already exists. +In that case +.Fn fopen +will fail. +.El +.Pp +Any created files will have mode +.Pf \*q Dv S_IRUSR +\&| +.Dv S_IWUSR +\&| +.Dv S_IRGRP +\&| +.Dv S_IWGRP +\&| +.Dv S_IROTH +\&| +.Dv S_IWOTH Ns \*q +.Pq Li 0666 , +as modified by the process' +.Xr umask 2 +value. +.Pp +Opening a file with append mode causes all subsequent writes to it +to be forced to the then current end of file, regardless of intervening +repositioning of the stream. +.Pp +The +.Fn fopen +and +.Fn freopen +functions initially position the stream at the start of the file +unless the file is opened with append mode, +in which case the stream is initially positioned at the end of the file. +.\" PR 6072 claims this paragraph is not correct. +.\" .Pp +.\" Reads and writes may be intermixed on read/write streams in any order, +.\" and do not require an intermediate seek as in previous versions of +.\" .Em stdio . +.\" This is not portable to other systems, however; +.\" .Tn ANSI C +.\" requires that +.\" a file positioning function intervene between output and input, unless +.\" an input operation encounters end-of-file. +.Pp +The +.Fn fdopen +function associates a stream with the existing file descriptor, +.Fa fildes . +The +.Fa mode +of the stream must be compatible with the mode of the file descriptor. +The stream is positioned at the file offset of the file descriptor. +.Pp +The +.Fn freopen +function +opens the file whose name is the string pointed to by +.Fa path +and associates the stream pointed to by +.Fa stream +with it. +The original stream (if it exists) is closed. +The +.Fa mode +argument is used just as in the +.Fn fopen +function. +The primary use of the +.Fn freopen +function +is to change the file associated with a +standard text stream +.Pf ( Em stderr , +.Em stdin , +or +.Em stdout ) . +.Pp +Input and output against the opened stream will be fully buffered, unless +it refers to an interactive terminal device, or a different kind of buffering +is specified in the environment. +See +.Xr setvbuf 3 +for additional details. +.Sh RETURN VALUES +Upon successful completion +.Fn fopen , +.Fn fdopen +and +.Fn freopen +return a FILE pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The functions may fail if: +.Bl -tag -width Er +.It Bq Er EFTYPE +The file is not a regular file and the character ``f'' is specified +in the mode. +.It Bq Er EINVAL +The specified +.Fa mode +was invalid. +.El +.Pp +The +.Fn fopen , +.Fn fdopen +and +.Fn freopen +functions +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr malloc 3 . +.Pp +The +.Fn fopen +function +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr open 2 . +.Pp +The +.Fn fdopen +function +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr fcntl 2 . +.Pp +The +.Fn freopen +function +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr open 2 , +.Xr fclose 3 +and +.Xr fflush 3 . +.Sh SEE ALSO +.Xr open 2 , +.Xr fclose 3 , +.Xr fileno 3 , +.Xr fseek 3 , +.Xr funopen 3 +.Sh STANDARDS +The +.Fn fopen +and +.Fn freopen +functions conform to +.St -ansiC . +All three functions are specified in +.St -p1003.1-2008 . +.Sh HISTORY +An +.Fn fopen +function appeared in +.At v1 . +.Sh CAVEATS +Proper code using +.Fn fdopen +with error checking should +.Xr close 2 +.Fa fildes +in case of failure, and +.Xr fclose 3 +the resulting FILE * in case of success. +.Bd -literal + FILE *file; + int fd; + + if ((file = fdopen(fd, "r")) != NULL) { + /* perform operations on the FILE * */ + fclose(file); + } else { + /* failure, report the error */ + close(fd); + } +.Ed diff --git a/static/netbsd/man3/form_cursor.3 b/static/netbsd/man3/form_cursor.3 new file mode 100644 index 00000000..dbb6a39d --- /dev/null +++ b/static/netbsd/man3/form_cursor.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: form_cursor.3,v 1.9 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm pos_form_cursor +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn pos_form_cursor "FORM *form" +.Sh DESCRIPTION +The function +.Fn pos_form_cursor +positions the screen cursor at the correct position for the form. +This function can be used to restore the cursor state after using +other curses routines. +.Sh RETURN VALUES +.Fn pos_form_cursor +will return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the function. +.It Er E_NOT_POSTED +The form is not posted to the screen. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_data.3 b/static/netbsd/man3/form_data.3 new file mode 100644 index 00000000..c69d2361 --- /dev/null +++ b/static/netbsd/man3/form_data.3 @@ -0,0 +1,76 @@ +.\" $NetBSD: form_data.3,v 1.10 2017/10/23 15:23:55 abhinav Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORM_DATA 3 +.Os +.Sh NAME +.Nm data_ahead , +.Nm data_behind +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn data_ahead "FORM *form" +.Ft int +.Fn data_behind "FORM *form" +.Sh DESCRIPTION +If there is data offscreen to the right of the current field of the +given form then +.Fn data_ahead +will return +.Dv TRUE , +otherwise +.Dv FALSE +is returned. +Similarly, if there is +data offscreen to the left of the current field of the given form then +.Fn data_behind +will return +.Dv TRUE . +.Sh RETURN VALUES +If the condition is met then the functions will return +.Dv TRUE , +if there +is an error or there is no data offscreen the functions will return +.Dv FALSE . +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_driver.3 b/static/netbsd/man3/form_driver.3 new file mode 100644 index 00000000..3c18991a --- /dev/null +++ b/static/netbsd/man3/form_driver.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: form_driver.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm form_driver +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn form_driver "FORM *form" "int request" +.Sh DESCRIPTION +The +.Fn form_driver +is the heart of the forms library, it takes commands in the +.Fa request +parameter that is either a request to the driver to perform some +action or is a character to be inserted into the current field. +The form driver will attempt to insert any printable character passed to +it into the current field. +This may or may not succeed depending on the state of the current field. +If the character passed is not +printable then the driver attempts to process it as a driver request. +If the character passed is not a valid request then the driver will +return an unknown command error. +.Sh PARAMETERS +The forms driver recognizes the following requests: +.Pp +.Bl -tag -width REQ_SFIRST_FIELD -compact +.It REQ_NEXT_PAGE +Change to the next page in the form. +.It REQ_PREV_PAGE +Change to the previous page in the form. +.It REQ_FIRST_PAGE +Select the first page in the form. +.It REQ_LAST_PAGE +Go to the last page in the form. +.It REQ_NEXT_FIELD +Move to the next field in the form field array. +.It REQ_PREV_FIELD +Move to the previous field in the form field array. +.It REQ_FIRST_FIELD +Go to the first field in the form field array. +.It REQ_LAST_FIELD +Go to the last field in the form field array. +.It REQ_SNEXT_FIELD +Move to the next sorted field on the form. +.It REQ_SPREV_FIELD +Move to the previous sorted field on the form. +.It REQ_SFIRST_FIELD +Go to the first field in the sorted list. +.It REQ_SLAST_FIELD +Move to the last field in the sorted list. +.It REQ_LEFT_FIELD +Go one field to the left on the form page. +.It REQ_RIGHT_FIELD +Go one field to the right on the form page. +.It REQ_UP_FIELD +Go up one field on the form page. +.It REQ_DOWN_FIELD +Go down one field on the form page. +.It REQ_NEXT_CHAR +Move one char to the right within the field +.It REQ_PREV_CHAR +Move one char to the left within the current field. +.It REQ_NEXT_LINE +Go down one line in the current field. +.It REQ_PREV_LINE +Go up one line in the current field. +.It REQ_NEXT_WORD +Go forward one word in the current field +.It REQ_PREV_WORD +Go backward one word in the current field. +.It REQ_BEG_FIELD +Move the cursor to the beginning of the current field. +.It REQ_END_FIELD +Move the cursor to the end of the current field. +.It REQ_BEG_LINE +Move the cursor to the beginning of the line in the current field. +.It REQ_END_LINE +Move the cursor to the end of the line. +.It REQ_LEFT_CHAR +Move the cursor left one character +.It REQ_RIGHT_CHAR +Move the cursor right one character +.It REQ_UP_CHAR +Move the cursor up one line. +.It REQ_DOWN_CHAR +Move the cursor down one line. +.It REQ_NEW_LINE +Insert a new line at the current cursor position. +.It REQ_INS_CHAR +Insert a blank character at the current cursor position +.It REQ_INS_LINE +Open a blank line at the current cursor position. +.It REQ_DEL_CHAR +Delete the character at the current cursor position. +.It REQ_DEL_PREV +Delete the character to the left of the current cursor position. +.It REQ_DEL_LINE +Delete the current line. +.It REQ_DEL_WORD +Delete the word at the current cursor position. +.It REQ_CLR_EOL +Clear the field from the current cursor position to the end of the +current line. +.It REQ_CLR_EOF +Clear the field from the current cursor position to the end of the field. +.It REQ_CLR_FIELD +Clear the field. +.It REQ_OVL_MODE +Enter overlay mode, characters added to the field will replace the +ones already there. +.It REQ_INS_MODE +Enter insert mode, characters will be inserted at the current cursor +position. +Any characters to the right of the cursor will be moved +right to accommodate the new characters. +.It REQ_SCR_FLINE +Scroll the field forward one line. +.It REQ_SCR_BLINE +Scroll the field backward one line. +.It REQ_SCR_FPAGE +Scroll the field forward one field page. +.It REQ_SCR_BPAGE +Scroll the field backward one field page. +.It REQ_SCR_FHPAGE +Scroll the field forward half one field page. +.It REQ_SCR_BHPAGE +Scroll the field backward half one field page. +.It REQ_SCR_FCHAR +Scroll the field horizontally forward one character +.It REQ_SCR_BCHAR +Scroll the field horizontally backward one character +.It REQ_SCR_HFLINE +Scroll the field horizontally forward one field line. +.It REQ_SCR_HBLINE +Scroll the field horizontally backward one field line. +.It REQ_SCR_HFHALF +Scroll the field horizontally forward half a field line. +.It REQ_SCR_HBHALF +Scroll the field horizontally backward half a field line. +.It REQ_VALIDATION +Request the contents of the current field be validated using any field +validation function that has been set for the field. +Normally, the field is validated before the current field changes. +This request allows the current field to be validated. +.It REQ_PREV_CHOICE +Select the previous choice in an enumerated type field. +.It REQ_NEXT_CHOICE +Select the next choice in an enumerated type field. +.El +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_REQUEST_DENIED +The forms driver request could not be fulfilled +.It Er E_UNKNOWN_COMMAND +The passed character is not a printable character and is not a valid +forms driver request. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the forms driver. +.It Er E_INVALID_FIELD +The form passed to the driver has no valid attached fields. +.It Er E_NOT_POSTED +The given form is not currently posted to the screen. +.It Er E_BAD_STATE +The forms driver was called from within an init or term function. +.It Er E_INVALID_FIELD +The character passed to the forms driver fails the character +validation for the current field. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +Field sorting is done by location of the field on the form page, the +fields are sorted by position starting with the top-most, left-most +field and progressing left to right. +For the purposes of sorting, the +fields top left corner is used as the sort criteria. +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field.3 b/static/netbsd/man3/form_field.3 new file mode 100644 index 00000000..4432bb2e --- /dev/null +++ b/static/netbsd/man3/form_field.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: form_field.3,v 1.12 2012/10/08 18:15:09 njoly Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_count , +.Nm form_fields , +.Nm move_field , +.Nm set_form_fields +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn field_count "FORM *form" +.Ft FIELD ** +.Fn form_fields "FORM *form" +.Ft int +.Fn move_field "FIELD *field" "int frow" "int fcol" +.Ft int +.Fn set_form_fields "FORM *form" "FIELD **fields" +.Sh DESCRIPTION +The +.Fn field_count +function returns the number of fields that are attached to the given +form, if the form argument passed is +.Dv NULL +then +.Fn field_count +will return \-1. +The function +.Fn form_fields +will return a pointer to array of attach fields for the given form, +this array is not +.Dv NULL +terminated, fields may be attached to the given +form by calling +.Fn set_form_fields . +The +.Fa fields +argument in this function is a pointer to a +.Dv NULL +terminated array of +fields that will be attached to the form. +If there are already fields attached to the form then they will be +detached before the new fields are attached. +The new fields given must not be attached to any other form. +The +.Fn move_field +function will move the given field to the location specified by +.Fa frow +and +.Fa fcol . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_CONNECTED +The field is connected to a form. +.It Er E_POSTED +The form is currently posted to the screen. +.It Er E_BAD_ARGUMENT +The function was passed a bad argument. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_attributes.3 b/static/netbsd/man3/form_field_attributes.3 new file mode 100644 index 00000000..11b1bab4 --- /dev/null +++ b/static/netbsd/man3/form_field_attributes.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: form_field_attributes.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_back , +.Nm field_fore , +.Nm field_pad , +.Nm set_field_back , +.Nm set_field_fore , +.Nm set_field_pad +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft chtype +.Fn field_back "FIELD *field" +.Ft chtype +.Fn field_fore "FIELD *field" +.Ft int +.Fn field_pad "FIELD *field" +.Ft int +.Fn set_field_back "FIELD *field" "chtype attribute" +.Ft int +.Fn set_field_fore "FIELD *field" "chtype attribute" +.Ft int +.Fn set_field_pad "FIELD *field" "int pad" +.Sh DESCRIPTION +Calling the function +.Fn field_back +will return the character attributes that will be applied to a field +that is not the current field, these attributes can be set by the +.Fn set_field_back +function. +The +.Fn field_fore +function returns the character attributes that will be used to +indicate that a field is the currently active one on the form, this +attribute may be set by using the +.Fn set_field_fore +function. +The pad character for a field is the character that will be printed in all +field locations not occupied with actual field contents. +The pad character can be retrieved by calling the +.Fn field_pad +function, the pad character is set by using the +.Fn set_field_pad +function. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_buffer.3 b/static/netbsd/man3/form_field_buffer.3 new file mode 100644 index 00000000..7b17104f --- /dev/null +++ b/static/netbsd/man3/form_field_buffer.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: form_field_buffer.3,v 1.13 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 15, 2005 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_buffer , +.Nm field_status , +.Nm set_field_buffer , +.Nm set_field_printf , +.Nm set_field_status , +.Nm set_max_field +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft char * +.Fn field_buffer "FIELD *field" "int buffer" +.Ft int +.Fn field_status "FIELD *field" +.Ft int +.Fn set_field_buffer "FIELD *field" "int buffer" "char *value" +.Ft int +.Fn set_field_printf "FIELD *field" "int buffer" "char *fmt" "..." +.Ft int +.Fn set_field_status "FIELD *field" "int status" +.Ft int +.Fn set_max_field "FIELD *field" "int max" +.Sh DESCRIPTION +The +.Fn field_buffer +function returns the contents of the buffer number specified by +.Fa buffer +for the given field. +If the requested buffer number exceeds the +number of buffers attached to the field then +.Dv NULL +will be returned. +If the field option +.Dv O_REFORMAT +is enabled on the given field then +storage will be allocated to hold the reformatted buffer. +This storage must be release by calling +.Xr free 3 +when it is no longer required. +If the +.Dv O_REFORMAT +field option is not set then no extra storage is allocated. +The field buffer may be set by calling +.Fn set_field_buffer +which will set the given buffer number to the contents of the string +passed. +A buffer may also be set by calling +.Fn set_field_printf +which sets the buffer using the format arg +.Fa fmt +after being expanded using the subsequent arguments in the same manner +as +.Xr sprintf 3 +does. +Calling +.Fn field_status +will return the status of the first buffer attached to the field. +If the field has been modified then the function will return +.Dv TRUE +otherwise +.Dv FALSE +is returned, the status of the first buffer may be +programmatically set by calling +.Fn set_field_status . +The maximum growth of a dynamic field can be set by calling +.Fn set_max_field +which limits the fields rows if the field is a multiline field or the +fields columns if the field only has a single row. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +A bad parameter was passed to the function. +.It Er E_SYSTEM_ERROR +A system error occurred performing the function. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . +The function +.Fn set_field_printf +is a +.Nx +extension and must not be used in portable code. diff --git a/static/netbsd/man3/form_field_info.3 b/static/netbsd/man3/form_field_info.3 new file mode 100644 index 00000000..f299cf3b --- /dev/null +++ b/static/netbsd/man3/form_field_info.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: form_field_info.3,v 1.9 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm dynamic_field_info , +.Nm field_info +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn dynamic_field_info "FIELD *field" "int *drows" "int *dcols" "int *max" +.Ft int +.Fn field_info "FIELD *field" "int *rows" "int *cols" "int *frow" "int *fcol" \ +"int *nrow" "int *nbuf" +.Sh DESCRIPTION +The function +.Fn dynamic_field_info +returns the sizing information for the field given. +The function will return the number of rows, columns and the maximum +growth of the field in the storage pointed to by the drows, dcols and max +parameters respectively. +Dynamic field information cannot be requested for the default field. +If the field given is not dynamic then +.Fn dynamic_field_info +will simply return the size of the actual field. +The +.Fn field_info +will return the number or rows, columns, field starting row, field +starting column, number of off screen rows and number of buffers in +.Fa rows , +.Fa cols , +.Fa frow , +.Fa fcol , +.Fa nrow +and +.Fa nbuf +respectively. +.Sh RETURN VALUES +The functions will return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the function. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_just.3 b/static/netbsd/man3/form_field_just.3 new file mode 100644 index 00000000..e0e0dfbf --- /dev/null +++ b/static/netbsd/man3/form_field_just.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: form_field_just.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_just , +.Nm set_field_just +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn field_just "FIELD *field" +.Ft int +.Fn set_field_just "FIELD *field" "int justification" +.Sh DESCRIPTION +Field justification is only applied to static fields, a dynamic field +will not be justified. +The default justification for a field is +NO_JUSTIFICATION. +The +.Fn field_just +will return the current justification value of the given field and the +justification may be set by calling the +.Fn set_field_just +function. +.Sh PARAMETERS +The following are the valid justifications for a field: +.Pp +.Bl -tag -width NO_JUSTIFICATION -compact +.It NO_JUSTIFICATION +No justification is to be applied to the field. +In practice, this is the same as JUSTIFY_LEFT. +.It JUSTIFY_RIGHT +The field will be right justified. +That is, the end of each line will +be butted up against the right hand side of the field. +.It JUSTIFY_LEFT +The field will be left justified. +That is, the start of each line +will be butted up against the left hand side of the field. +.It JUSTIFY_CENTER +The field will be centre justified, padding will be applied to either +end of the line to make the line centred in the field. +.El +.Sh RETURN VALUES +The functions will return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_CURRENT +The field specified is the currently active one on the form. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the function. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_new.3 b/static/netbsd/man3/form_field_new.3 new file mode 100644 index 00000000..f3e4a1c8 --- /dev/null +++ b/static/netbsd/man3/form_field_new.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: form_field_new.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm dup_field , +.Nm free_field , +.Nm link_field , +.Nm new_field +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft FIELD * +.Fn dup_field "FIELD *field" "int frow" "int fcol" +.Ft int +.Fn free_field "FIELD *field" +.Ft FIELD * +.Fn link_field "FIELD *field" "int frow" "int fcol" +.Ft FIELD * +.Fo new_field +.Fa "int rows" +.Fa "int cols" +.Fa "int frow" +.Fa "int fcol" +.Fa "int nrows" +.Fa "int nbuf" +.Fc +.Sh DESCRIPTION +The +.Fn dup_field +function duplicates the given field, including any buffers associated +with the field and returns the pointer to the newly created field. +.Fn free_field +destroys the field and frees any allocated resources associated with +the field. +The function +.Fn link_field +copies the given field to a new field at the location +.Fa frow +and +.Fa fcol +but shares the buffers with the original field. +.Fn new_field +creates a new field of size +.Fa rows +by +.Fa cols +at location +.Fa frow , +.Fa fcol +on the page, the argument +.Fa nrows +specified the number of off screen rows the field has and the +.Fa nbuf +parameter specifies the number of extra buffers attached to the +field. +There will always be one buffer associated with a field. +.Sh RETURN VALUES +On error +.Fn dup_field +and +.Fn new_field +will return +.Dv NULL . +The functions will one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the function. +.It Er E_CONNECTED +The field is connected to a form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_opts.3 b/static/netbsd/man3/form_field_opts.3 new file mode 100644 index 00000000..1de3e2ad --- /dev/null +++ b/static/netbsd/man3/form_field_opts.3 @@ -0,0 +1,157 @@ +.\" $NetBSD: form_field_opts.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 24, 2004 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_opts , +.Nm field_opts_off , +.Nm field_opts_on , +.Nm set_field_opts +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft Form_Options +.Fn field_opts "FIELD *field" +.Ft int +.Fn field_opts_off "FIELD *field" "Form_Options options" +.Ft int +.Fn field_opts_on "FIELD *field" "Form_Options options" +.Ft int +.Fn set_field_opts "FIELD *field" "Form_Options options" +.Sh DESCRIPTION +The function +.Fn field_opts +returns the current options settings for the given field. +The +.Fn field_opts_off +will turn the options given in +.Fa options +off for the given field, options not specified in +.Fa options +will remain unchanged. +Conversely, the function +.Fn field_opts_on +will turn on the options given in +.Fa options +for the specified field, again, any options not specified will remain +unchanged. +The options for a field may be set to a specific set of +options by calling the +.Fn set_field_opts +function. +Options may only be changed if the field given is not the +currently active one. +.Sh PARAMETERS +The following options are available for a field: +.Pp +.Bl -tag -width O_REFORMAT -compact +.It Dv O_VISIBLE +The field is visible, hence is displayed when the form is posted. +.It Dv O_ACTIVE +The field is active in the form, meaning that it can be visited during +form processing. +.It Dv O_PUBLIC +The contents of the field are echoed to the screen. +.It Dv O_EDIT +The contents of the field can be modified +.It Dv O_WRAP +The contents of the field are wrapped on a word boundary, if this +option is off then the field will be wrapped on a character boundary. +.It Dv O_BLANK +Blank the field on new data being entered if and only if the field +cursor is at the left hand side of the field. +.It Dv O_AUTOSKIP +Skip to the next field when the current field reaches its maximum +size. +.It Dv O_NULLOK +The field is allowed to contain no data +.It Dv O_STATIC +The field is not dynamic, it has a fixed size. +.It Dv O_PASSOK +An unmodified field is allowed. +.It Dv O_REFORMAT +Retain the formatting of a field when the buffer is retrieved. +If this option is not set then the buffer returned will be a single string +with no line breaks. +When this option is set newline characters will be inserted at the point +where the string has been wrapped in a multiline field. +This option is an extension to the forms library and must not be used +in portable code. +See the +.Xr field_buffer 3 +man page for how this option modifies the behaviour of +.Fn field_buffer . +.El +.Pp +The following options are on by default for a field: +.Dv O_VISIBLE , +.Dv O_ACTIVE , +.Dv O_PUBLIC , +.Dv O_EDIT , +.Dv O_WRAP , +.Dv O_BLANK , +.Dv O_AUTOSKIP , +.Dv O_NULLOK , +.Dv O_PASSOK , +and +.Dv O_STATIC . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_CURRENT +The field specified is the currently active one in the form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . +The option +.Dv O_REFORMAT +is a +.Nx + extension and must not be used in portable code. diff --git a/static/netbsd/man3/form_field_userptr.3 b/static/netbsd/man3/form_field_userptr.3 new file mode 100644 index 00000000..4aff31cb --- /dev/null +++ b/static/netbsd/man3/form_field_userptr.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: form_field_userptr.3,v 1.9 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_userptr , +.Nm set_field_userptr +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft void * +.Fn field_userptr "FIELD *field" +.Ft int +.Fn set_field_userptr "FIELD *field" "void *ptr" +.Sh DESCRIPTION +The +.Fn field_userptr +function returns the pointer to the user defined data for the field, +this pointer may be set by calling the +.Fn set_field_userptr +function. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_field_validation.3 b/static/netbsd/man3/form_field_validation.3 new file mode 100644 index 00000000..928896e2 --- /dev/null +++ b/static/netbsd/man3/form_field_validation.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: form_field_validation.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_arg , +.Nm field_type , +.Nm set_field_type +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft char * +.Fn field_arg "FIELD *field" +.Ft FIELDTYPE * +.Fn field_type "FIELD *field" +.Ft int +.Fn set_field_type "FIELD *field" "FIELDTYPE *type" "..." +.Sh DESCRIPTION +The +.Fn field_arg +function returns the field type arguments that are associated with the +given field. +The +.Fn field_type +function returns the field type structure associated with the given +field, this type can be set by calling the +.Fn set_field_type +function which associates the given field type with the field, the +third and subsequent parameters are field dependent arguments. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_fieldtype.3 b/static/netbsd/man3/form_fieldtype.3 new file mode 100644 index 00000000..c4faa0b0 --- /dev/null +++ b/static/netbsd/man3/form_fieldtype.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: form_fieldtype.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm free_fieldtype , +.Nm link_fieldtype , +.Nm new_fieldtype , +.Nm set_fieldtype_arg , +.Nm set_fieldtype_choice +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn free_fieldtype "FIELDTYPE *fieldtype" +.Ft FIELDTYPE * +.Fn link_fieldtype "FIELDTYPE *type1" "FIELDTYPE *type2" +.Ft FIELDTYPE * +.Fo new_fieldtype +.Fa "int (*field_check)(FIELD *, char *)" +.Fa "int (*char_check)(int, char *)" +.Fc +.Ft int +.Fo "set_fieldtype_arg" +.Fa "FIELDTYPE *fieldtype" +.Fa "char * (*make_args)(va_list *)" +.Fa "char * (*copy_args)(char *)" +.Fa "void (*free_args)(char *)" +.Fc +.Ft int +.Fo set_fieldtype_choice +.Fa "FIELDTYPE *fieldtype" +.Fa "int (*next_choice)(FIELD *, char *)" +.Fa "int (*prev_choice)(FIELD *, char *)" +.Fc +.Sh DESCRIPTION +The function +.Fn free_fieldtype +frees the storage associated with the field type and destroys it. +The function +.Fn link_fieldtype +links together the two given field types to produce a new field type. +A new field type can be created by calling +.Fn new_fieldtype +which requires pointers to two functions which perform validation, the +.Fa field_check +function must validate the field contents and return +.Dv TRUE +if they are acceptable and +.Dv FALSE +if they are not. +The +.Fa char_check +validates the character input into the field, this function will be +called for each character entered, if the character can be entered +into the field then +.Fa char_check +must return +.Dv TRUE . +Neither +.Fa field_check +nor +.Fa char_check +may be +.Dv NULL . +The functions for handling the field type arguments can +be defined by using the +.Fn set_fieldtype_arg +function, the +.Fa make_args +function is used to create new arguments for the fieldtype, the +.Fa copy_args +is used to copy the fieldtype arguments to a new arguments structure +and +.Fa free_args +is used to destroy the fieldtype arguments and release any associated +storage, none of these function pointers may be +.Dv NULL . +The field type choice functions can be set by calling +.Fn set_fieldtype_choice , +the +.Fa next_choice +and +.Fa prev_choice +specify the next and previous choice functions for the field type. +These functions must perform the necessary actions to select the next +or previous choice for the field, updating the field buffer if +necessary. +The choice functions must return +.Dv TRUE +if the function succeeded and +.Dv FALSE +otherwise. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +The function was passed a bad argument. +.It Er E_CONNECTED +The field is connected to a form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_hook.3 b/static/netbsd/man3/form_hook.3 new file mode 100644 index 00000000..2c704550 --- /dev/null +++ b/static/netbsd/man3/form_hook.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: form_hook.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm field_init , +.Nm field_term , +.Nm form_init , +.Nm form_term , +.Nm set_field_init , +.Nm set_field_term , +.Nm set_form_init , +.Nm set_form_term +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft void (*)(FORM *) +.Fn field_init "FORM *form" +.Ft void (*)(FORM *) +.Fn field_term "FORM *form" +.Ft void (*)(FORM *) +.Fn form_init "FORM *form" +.Ft void (*)(FORM *) +.Fn form_term "FORM *form" +.Ft int +.Fn set_field_init "FORM *form" "void (*function)(FORM *)" +.Ft int +.Fn set_field_term "FORM *form" "void (*function)(FORM *)" +.Ft int +.Fn set_form_init "FORM *form" "void (*function)(FORM *)" +.Ft int +.Fn set_form_term "FORM *form" "void (*function)(FORM *)" +.Sh DESCRIPTION +The +.Fn field_init +function returns a pointer to the function that will be called just +after the current field changes and just before the form is posted, +this function may be set by using the +.Fn set_field_init +function. +Similarly, the function +.Fn field_term +will return a pointer to the function that will be called just before +the current field changes and just after the form is unposted, this +function pointer may be set by using the +.Fn set_field_term +function. +The +.Fn form_init +function will return a pointer to the function that will be called +just before the form is posted to the screen, this function can be set +by calling the +.Fn set_form_init +function. +The +.Fn form_term +function will return a pointer to the function that will be called +just after the form is unposted from the screen, this function may be +set by using the +.Fn set_form_term +function. +By default, the init and term function pointers are +.Dv NULL . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_new.3 b/static/netbsd/man3/form_new.3 new file mode 100644 index 00000000..7d4b8412 --- /dev/null +++ b/static/netbsd/man3/form_new.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: form_new.3,v 1.9 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm free_form , +.Nm new_form +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn free_form "FORM *form" +.Ft FORM * +.Fn new_form "FIELD **fields" +.Sh DESCRIPTION +The function +.Fn free_form +frees all the resources associated with the form and destroys the +form. +Calling +.Fn new_form +will create a new form, set the form parameters to the current +defaults and attach the passed fields to the form. +The array of fields passed to +.Fn new_form +must be terminated with a +.Dv NULL +pointer to indicate the end of the fields. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +The function was passed a bad argument. +.It Er E_POSTED +The form is posted to the screen. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_new_page.3 b/static/netbsd/man3/form_new_page.3 new file mode 100644 index 00000000..0a1ae42f --- /dev/null +++ b/static/netbsd/man3/form_new_page.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: form_new_page.3,v 1.11 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm new_page , +.Nm set_new_page +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn new_page "FIELD *field" +.Ft int +.Fn set_new_page "FIELD *field" "int page" +.Sh DESCRIPTION +The +.Fn new_page +function returns +.Dv TRUE +if the given field is the start of a new page, otherwise it returns +.Dv FALSE , +the new page status of a field can be set or unset using the +.Fn set_new_page +function. +.Sh RETURN VALUES +The functions will return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_CONNECTED +The field is connected to a form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_opts.3 b/static/netbsd/man3/form_opts.3 new file mode 100644 index 00000000..180d1607 --- /dev/null +++ b/static/netbsd/man3/form_opts.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: form_opts.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm form_opts , +.Nm form_opts_off , +.Nm form_opts_on , +.Nm set_form_opts +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft Form_Options +.Fn form_opts "FORM *form" +.Ft int +.Fn form_opts_off "FORM *form" "Form_Options options" +.Ft int +.Fn form_opts_on "FORM *form" "Form_Options options" +.Ft int +.Fn set_form_opts "FORM *form" "Form_Options options" +.Sh DESCRIPTION +The function +.Fn form_opts +returns the current options that are set on the given form. +The +.Fn form_opts_off +will turn off the form options given in +.Fa options +for the form, similarly, +.Fn form_opts_on +will turn on the options specified in +.Fa options +for the given form. +The form options can be set to an explicit set by calling +.Fn set_form_opts . +.Sh PARAMETERS +The following form options are valid: +.Pp +.Bl -tag -width O_BS_OVERLOAD -compact +.It O_BS_OVERLOAD +If this option is set and the cursor is at the first character in the +field then the backspace character will perform the same function as a +REQ_PREV_FIELD driver request, moving to the previous field in the +form. +.It O_NL_OVERLOAD +If this option is set and the cursor is at the end of the field then +the new line character will perform the same function as a +REQ_NEXT_FIELD driver request, moving to the next field in the form. +.El +.Pp +By default no form options are set. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_page.3 b/static/netbsd/man3/form_page.3 new file mode 100644 index 00000000..39a59e3b --- /dev/null +++ b/static/netbsd/man3/form_page.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: form_page.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORM_PAGE 3 +.Os +.Sh NAME +.Nm current_field , +.Nm field_index , +.Nm form_page , +.Nm form_max_page , +.Nm set_current_field , +.Nm set_form_page +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft FIELD * +.Fn current_field "FORM *form" +.Ft int +.Fn field_index "FIELD *field" +.Ft int +.Fn form_page "FORM *form" +.Ft int +.Fn form_max_page "FORM *form" +.Ft int +.Fn set_current_field "FORM *form" "FIELD *field" +.Ft int +.Fn set_form_page "FORM *form" "int page" +.Sh DESCRIPTION +The +.Fn current_field +returns a pointer to the structure for the field that is currently +active on the page. +If there is an error, +.Fn current_field +will return +.Dv NULL . +Calling +.Fn field_index +will return the index of the given field in the form field array. +The +current page the form is on can be determined by using +.Fn form_page , +the current page of a form can be programmatically set by calling +.Fn set_form_page . +The maximum page number for a form can be found by +calling the function +.Fn form_max_page +but note that this function is a +.Nx +extension and must not be used in portable forms library programs. +The current field on the form may be set by calling +.Fn set_current_field +which will set the current field to the one given. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +The function was passed a bad argument. +.It Er E_NOT_CONNECTED +The given field is not associated with a form. +.It Er E_BAD_STATE +The function was called from within an init or term function. +.It Er E_INVALID_FIELD +The field given is not part of the given form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . +.Pp +The +.Nm form_max_page +is a +.Nx +extension and should not be used in portable applications. diff --git a/static/netbsd/man3/form_post.3 b/static/netbsd/man3/form_post.3 new file mode 100644 index 00000000..ed71b5f3 --- /dev/null +++ b/static/netbsd/man3/form_post.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: form_post.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm post_form , +.Nm unpost_form +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft int +.Fn post_form "FORM *form" +.Ft int +.Fn unpost_form "FORM *form" +.Sh DESCRIPTION +The +.Fn post_form +function performs the actions necessary to present the form on the +curses screen. +If there are any init functions that need to be called +then they will be called prior to the form being posted and the cursor +will be positioned on the first active field that can be visited. +Conversely, the function +.Fn unpost_form +removes the form from the screen and calls any termination functions +that were specified. +.Sh RETURN VALUES +The functions will return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +A bad argument was passed to the function. +.It Er E_POSTED +The form is already posted to the screen. +.It Er E_NOT_POSTED +The form was not posted to the screen. +.It Er E_NOT_CONNECTED +There are no fields associated with the form. +.It Er E_BAD_STATE +The function was called from within a init or term function. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_userptr.3 b/static/netbsd/man3/form_userptr.3 new file mode 100644 index 00000000..0fc42120 --- /dev/null +++ b/static/netbsd/man3/form_userptr.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: form_userptr.3,v 1.9 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm form_userptr , +.Nm set_form_userptr +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft void * +.Fn form_userptr "FORM *form" +.Ft int +.Fn set_form_userptr "FORM *form" "void *ptr" +.Sh DESCRIPTION +The +.Fn form_userptr +function returns the pointer to the user defined data associated with +the form, this pointer may be set using the +.Fn set_form_userptr +call. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/form_win.3 b/static/netbsd/man3/form_win.3 new file mode 100644 index 00000000..0d065f20 --- /dev/null +++ b/static/netbsd/man3/form_win.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: form_win.3,v 1.10 2010/03/22 21:58:31 joerg Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2001 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm form_sub , +.Nm form_win , +.Nm scale_form , +.Nm set_form_sub , +.Nm set_form_win +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Ft WINDOW * +.Fn form_sub "FORM *form" +.Ft WINDOW * +.Fn form_win "FORM *form" +.Ft int +.Fn scale_form "FORM *form" "int *rows" "int *cols" +.Ft int +.Fn set_form_sub "FORM *form" "WINDOW *window" +.Ft int +.Fn set_form_win "FORM *form" "WINDOW *window" +.Sh DESCRIPTION +All output to the screen done by the forms library is handled by the +curses library routines. +By default, the forms library will output to the curses +.Fa stdscr , +but if the forms window has been set via +.Fn set_form_win +then output will be sent to the window specified by +.Fn set_form_win , +unless the forms subwindow has been set using +.Fn set_form_sub . +If a subwindow has been specified using +.Fn set_form_sub +then it will be used by the forms library to for screen output. +The current setting for the form window can be retrieved by calling +.Fn form_win . +If the forms window has not been set then +.Dv NULL +will be returned. +Similarly, the forms subwindow can be found by calling the +.Fn form_sub +function, again, if the subwindow has not been set then +.Dv NULL +will be +returned. +The +.Fn scale_form +function will return the minimum number of rows and columns that will +entirely contain the given form. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following error +values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_NOT_CONNECTED +The form has no fields connected to it. +.It Er E_POSTED +The form is posted to the screen. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr forms 3 +.Sh NOTES +The header +.In form.h +automatically includes both +.In curses.h +and +.In eti.h . diff --git a/static/netbsd/man3/forms.3 b/static/netbsd/man3/forms.3 new file mode 100644 index 00000000..e715110f --- /dev/null +++ b/static/netbsd/man3/forms.3 @@ -0,0 +1,235 @@ +.\" $NetBSD: forms.3,v 1.17 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 2001 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 24, 2004 +.Dt FORMS 3 +.Os +.Sh NAME +.Nm form +.Nd form library +.Sh LIBRARY +.Lb libform +.Sh SYNOPSIS +.In form.h +.Sh DESCRIPTION +The +.Nm +library provides a terminal independent form system using the +.Xr curses 3 +library. +Before using the +.Nm +functions the terminal must be set up by +.Xr curses 3 +using the +.Fn initscr +function or similar. +Programs using +.Nm +functions must be linked with the +.Xr curses 3 +library +.Fl lcurses . +.Pp +The +.Nm +library provides facilities for defining form fields, placing a form on the +terminal screen, assign pre and post change operations and setting the +attributes of both the form and its fields. +.Ss Defining default attributes for forms and fields +The +.Nm +library allows any settable attribute or option of both the form and field +objects to be defined such that any new form or field automatically inherits +the value as default. +Setting the default value will not affect any field or +form that has already been created but will be applied to subsequent objects. +To set the default attribute or option the set routine is passed a +.Dv NULL +pointer in the field or form parameter when calling the set routine. +The current default value can be retrieved by calling the get routine with a +.Dv NULL +pointer for the field or form parameter. +.Pp +.Bl -column set_fieldtype_choiceXX +.It Sy "Form Routine Name" Ta Sy "Manual Page Name" +.It current_field Ta Xr form_page 3 +.It data_ahead Ta Xr form_data 3 +.It data_behind Ta Xr form_data 3 +.It dup_field Ta Xr form_field_new 3 +.It dynamic_field_info Ta Xr form_field_info 3 +.It field_arg Ta Xr form_field_validation 3 +.It field_back Ta Xr form_field_attributes 3 +.It field_buffer Ta Xr form_field_buffer 3 +.It field_count Ta Xr form_field 3 +.It field_fore Ta Xr form_field_attributes 3 +.It field_index Ta Xr form_page 3 +.It field_info Ta Xr form_field_info 3 +.It field_init Ta Xr form_hook 3 +.It field_just Ta Xr form_field_just 3 +.It field_opts Ta Xr form_field_opts 3 +.It field_opts_off Ta Xr form_field_opts 3 +.It field_opts_on Ta Xr form_field_opts 3 +.It field_pad Ta Xr form_field_attributes 3 +.It field_status Ta Xr form_field_buffer 3 +.It field_term Ta Xr form_hook 3 +.It field_type Ta Xr form_field_validation 3 +.It field_userptr Ta Xr form_field_userptr 3 +.It form_driver Ta Xr form_driver 3 +.It form_fields Ta Xr form_field 3 +.It form_init Ta Xr form_hook 3 +.It form_max_page Ta Xr form_page 3 +.It form_opts Ta Xr form_opts 3 +.It form_opts_off Ta Xr form_opts 3 +.It form_opts_on Ta Xr form_opts 3 +.It form_page Ta Xr form_page 3 +.It form_sub Ta Xr form_win 3 +.It form_term Ta Xr form_hook 3 +.It form_userptr Ta Xr form_userptr 3 +.It form_win Ta Xr form_win 3 +.It free_field Ta Xr form_field_new 3 +.It free_fieldtype Ta Xr form_fieldtype 3 +.It free_form Ta Xr form_new 3 +.It link_field Ta Xr form_field_new 3 +.It link_fieldtype Ta Xr form_fieldtype 3 +.It move_field Ta Xr form_field 3 +.It new_field Ta Xr form_field_new 3 +.It new_fieldtype Ta Xr form_fieldtype 3 +.It new_form Ta Xr form_new 3 +.It new_page Ta Xr form_new_page 3 +.It pos_form_cursor Ta Xr form_cursor 3 +.It post_form Ta Xr form_post 3 +.It scale_form Ta Xr form_win 3 +.It set_current_field Ta Xr form_page 3 +.It set_field_back Ta Xr form_field_attributes 3 +.It set_field_buffer Ta Xr form_field_buffer 3 +.It set_field_fore Ta Xr form_field_attributes 3 +.It set_field_init Ta Xr form_hook 3 +.It set_field_just Ta Xr form_field_just 3 +.It set_field_opts Ta Xr form_field_opts 3 +.It set_field_pad Ta Xr form_field_attributes 3 +.It set_field_printf Ta Xr form_field_buffer 3 +.It set_field_status Ta Xr form_field_buffer 3 +.It set_field_term Ta Xr form_hook 3 +.It set_field_type Ta Xr form_field_validation 3 +.It set_field_userptr Ta Xr form_field_userptr 3 +.It set_fieldtype_arg Ta Xr form_fieldtype 3 +.It set_fieldtype_choice Ta Xr form_fieldtype 3 +.It set_form_fields Ta Xr form_field 3 +.It set_form_init Ta Xr form_hook 3 +.It set_form_opts Ta Xr form_opts 3 +.It set_form_page Ta Xr form_page 3 +.It set_form_sub Ta Xr form_win 3 +.It set_form_term Ta Xr form_hook 3 +.It set_form_userptr Ta Xr form_userptr 3 +.It set_form_win Ta Xr form_win 3 +.It set_max_field Ta Xr form_field_buffer 3 +.It set_new_page Ta Xr form_new_page 3 +.It unpost_form Ta Xr form_post 3 +.El +.Sh RETURN VALUES +Any function returning a string pointer will return +.Dv NULL +if an error occurs. +Functions returning an integer will return one of the following: +.Bl -column set_fieldtype_choiceXX +.It Dv E_OK Ta No The function was successful. +.It Dv E_SYSTEM_ERROR Ta No There was a system error during the call. +.It Dv E_BAD_ARGUMENT Ta No One or more of the arguments passed to \ +the function was incorrect. +.It Dv E_POSTED Ta No The form is already posted. +.It Dv E_CONNECTED Ta No A field was already connected to a form. +.It Dv E_BAD_STATE Ta No The function was called from within an \ +initialization or termination routine. +.It Dv E_NO_ROOM Ta No The form does not fit within the subwindow. +.It Dv E_NOT_POSTED Ta No The form is not posted. +.It Dv E_UNKNOWN_COMMAND Ta No The form driver does not recognize the \ +request passed to it. +.It Dv E_NOT_SELECTABLE Ta No The field could not be selected. +.It Dv E_NOT_CONNECTED Ta No The field is not connected to a form. +.It Dv E_REQUEST_DENIED Ta No The form driver could not process the request. +.It Dv E_INVALID_FIELD Ta No The field is invalid. +.It Dv E_CURRENT Ta No The field is the active one on the form. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +This implementation of the forms library does depart in behavior +subtly from the original AT&T implementation. +Some of the more notable departures are: +.Pp +.Bl -tag -width "The TAB character" -compact +.It field wrapping +For multi-line fields the data will be wrapped as it is entered, this +does not happen in the AT&T implementation. +.It buffer 0 +In this implementation, the contents of buffer 0 are always current +regardless of whether the field has been validated or not. +.It circular fields +In the AT&T implementation fields are circular on a page, that is, a +next field from the last field will go to the first field on the +current page. +In this implementation a next field request on the last +field of a page will result in the forms library positioning the +cursor on the first field of the next page. +If the field is the last +field in the form then going to the next field will be denied, in the +AT&T it would result in the cursor being placed on the first field of +the first page. +.It buffer returns +In this implementation only the data entered by the user in the form +field will be returned, unlike the AT&T library which would return the +contents of the field padded to the size of the field with the pad +character. +.It The TAB character +The handling of the TAB character in fields varies between +implementations. +In ncurses attempting to set a field contents with a +string containing a TAB will result in an error and will not allow a +TAB to be entered into a field. +The AT&T library statically +converts tabs to the equivalent number of spaces when the field buffer +is set but the form driver will not allow a TAB to be inserted into +the field buffer. +This implementation allows TAB when setting the +field buffer and also will allow TAB to be inserted into a field +buffer via the form driver and correctly calculates the cursor +position allowing for expansion of the TAB character. +.It set_field_printf +This function is a +.Nx +extension and must not be used in portable code. +.It Dv O_REFORMAT +This field option is a +.Nx +extension and must not be used in portable code. +.El diff --git a/static/netbsd/man3/fparseln.3 b/static/netbsd/man3/fparseln.3 new file mode 100644 index 00000000..a65a3879 --- /dev/null +++ b/static/netbsd/man3/fparseln.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: fparseln.3,v 1.6 2025/12/20 14:42:43 christos Exp $ +.\" +.\" Copyright (c) 1997 Christos Zoulas. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 20, 2025 +.Dt FPARSELN 3 +.Os +.Sh NAME +.Nm fparseln +.Nd return the next logical line from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft "char *" +.Fo "fparseln" +.Fa "FILE *stream" "size_t *len" "size_t *lineno" +.Fa "const char delim[3]" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn fparseln +function +returns a pointer to the next logical line from the stream referenced by +.Fa stream . +This string is +.Dv NUL +terminated and it is dynamically allocated on each invocation. +It is the responsibility of the caller to free the pointer. +.Pp +By default, if a character is escaped, both it and the preceding escape +character will be present in the returned string. +Various +.Fa flags +alter this behaviour. +.Pp +The meaning of the arguments is as follows: +.Bl -tag -width "lineno" +.It Fa stream +The stream to read from. +.It Fa len +If not +.Dv NULL , +the length of the string is stored in the memory location to which it +points. +.It Fa lineno +If not +.Dv NULL , +the value of the memory location to which is pointed to, is incremented +by the number of lines actually read from the file. +.It Fa delim +Contains the escape, continuation, and comment characters. +If a character is +.Dv NUL +then processing for that character is disabled. +If +.Dv NULL , +all characters default to values specified below. +The contents of +.Fa delim +is as follows: +.Bl -tag -width "delim[0]" +.It Fa delim[0] +The escape character, which defaults to +.Cm \e , +is used to remove any special meaning from the next character. +.It Fa delim[1] +The continuation character, which defaults to +.Cm \e , +is used to indicate that the next line should be concatenated with the +current one if this character is the last character on the current line +and is not escaped. +.It Fa delim[2] +The comment character, which defaults to +.Cm # , +if not escaped indicates the beginning of a comment that extends until the +end of the current line. +.El +.It Fa flags +If non-zero, alter the operation of +.Fn fparseln . +The various flags, which may be +.Em or Ns -ed +together, are: +.Bl -tag -width "FPARSELN_UNESCCOMM" +.It Dv FPARSELN_UNESCCOMM +Remove escape preceding an escaped comment. +.It Dv FPARSELN_UNESCCONT +Remove escape preceding an escaped continuation. +.It Dv FPARSELN_UNESCESC +Remove escape preceding an escaped escape. +.It Dv FPARSELN_UNESCREST +Remove escape preceding any other character. +.It Dv FPARSELN_UNESCALL +All of the above. +.El +.El +.Sh RETURN VALUES +Upon successful completion a pointer to the parsed line is returned; +otherwise, +.Dv NULL +is returned. +.Pp +The +.Fn fparseln +function uses internally +.Xr fgetln 3 , +so all error conditions that apply to +.Xr fgetln 3 , +apply to +.Fn fparseln . +In addition +.Fn fparseln +may set +.Va errno +to +.Bq Er ENOMEM +and return +.Dv NULL +if it runs out of memory. +.Sh SEE ALSO +.Xr getline 3 +.Xr fgetln 3 +.Sh HISTORY +The +.Fn fparseln +function first appeared in +.Nx 1.4 . diff --git a/static/netbsd/man3/fpclassify.3 b/static/netbsd/man3/fpclassify.3 new file mode 100644 index 00000000..c8dcc1ba --- /dev/null +++ b/static/netbsd/man3/fpclassify.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: fpclassify.3,v 1.3 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 14, 2004 +.Dt FPCLASSIFY 3 +.Os +.Sh NAME +.Nm fpclassify +.Nd classify real floating type +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn fpclassify "real-floating x" +.Sh DESCRIPTION +The +.Fn fpclassify +macro performs classification of its argument +.Fa x . +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The classification is then based on the type of the argument. +.Ss IEEE 754 +.Bl -tag -width "FP_SUBNORMALXXX" -compact -offset indent +.It Dv FP_INFINITE +infinity, either positive or negative +.It Dv FP_NAN +not-a-number +.Pq Dq NaN +.It Dv FP_NORMAL +normal +.It Dv FP_SUBNORMAL +subnormal +.It Dv FP_ZERO +zero +.El +.Ss VAX +.Bl -tag -width "FP_DIRTYZEROXXX" -compact -offset indent +.It Dv FP_ROP +reserved operand +.Pq Dq ROP +.It Dv FP_DIRTYZERO +dirty zero +.It Dv FP_NORMAL +finite +.It Dv FP_ZERO +true zero +.El +.Sh RETURN VALUES +The +.Fn fpclassify +macro returns the value of the number classification macro appropriate +to its argument +.Fa x +as described above. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr isfinite 3 , +.Xr isnormal 3 , +.Xr math 3 , +.Xr signbit 3 +.Sh STANDARDS +The +.Fn fpclassify +macro conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/fpgetmask.3 b/static/netbsd/man3/fpgetmask.3 new file mode 100644 index 00000000..9ca8aa6b --- /dev/null +++ b/static/netbsd/man3/fpgetmask.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: fpgetmask.3,v 1.12 2011/03/27 22:55:07 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Ross Harvey. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 26, 2011 +.Dt FPGETMASK 3 +.Os +.Sh NAME +.Nm fpgetmask , +.Nm fpgetprec , +.Nm fpgetround , +.Nm fpgetsticky , +.Nm fpsetmask , +.Nm fpsetprec , +.Nm fpsetround , +.Nm fpsetsticky +.Nd IEEE FP mode control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ieeefp.h +.Ft fp_except_t +.Fn fpgetmask void +.Ft fp_prec_t +.Fn fpgetprec void +.Ft fp_rnd_t +.Fn fpgetround void +.Ft fp_except_t +.Fn fpgetsticky void +.Ft fp_except_t +.Fn fpsetmask "fp_except_t mask" +.Ft fp_prec_t +.Fn fpsetprec "fp_prec_t prec" +.Ft fp_rnd_t +.Fn fpsetround "fp_rnd_t rnd_dir" +.Ft fp_except_t +.Fn fpsetsticky "fp_except_t sticky" +.Sh DESCRIPTION +A rounding mode +.Ft fp_rnd_t +is one of: +.Bl -column -offset indent FP_RZ +.It Dv FP_RZ Ta rounding towards Em zero +.It Dv FP_RM Ta rounding down to Pq Em Minus infinity +.It Dv FP_RN Ta rounding to Em nearest +.It Dv FP_RP Ta rounding down to Pq Em Plus infinity +.El +The default mode is +.Dv FP_RN . +.Pp +An +.Ft fp_except_t +value is a bitmask specifying an exception type and containing any of +the values listed below. +.Bl -column -offset indent FP_X_UFLxx +.It Dv FP_X_INV Ta Invalid\ Operation +.It Dv FP_X_DZ Ta Division\ by\ zero +.It Dv FP_X_OFL Ta Overflow +.It Dv FP_X_UFL Ta Underflow +.It Dv FP_X_IMP Ta Imprecision (inexact) +.It Dv FP_X_IOV Ta Integer\ Overflow +.El +.Pp +An +.Ft fp_prec_t +specifies the precision of the floating point operations listed below. +.Bl -column -offset indent FP_RPS +.It Dv FP_PS Ta Dv 24 bit (single-precision) +.It Dv FP_PRS Ta reserved +.It Dv FP_PD Ta Dv 53 bit (double-precision) +.It Dv FP_PE Ta Dv 64 bit (extended-precision) +.El +.Pp +The +.Fn fpsetmask +function will set the current exception mask, i.e., it will cause +future operations with the specified result status to raise the +.Dv SIGFPE +exception. +The +.Fn fpgetmask +function will return the current exception mask. +.Pp +The +.Fn fpgetprec +function will return the current floating point precision. +The +.Fn fpsetprec +function will set the floating point precision and will return +the previous precision. +.Pp +The +.Fn fpsetround +function will cause future operations to use the specified dynamic +rounding mode. +The +.Fn fpgetround +function will return the current rounding mode. +.Bl -tag -width Note:x +.It Em Note : +On some architectures, instructions can optionally specify static +rounding modes and exception enables that will supersede the specified +dynamic mode. +On other architectures, these features may not be fully supported. +.El +.Pp +A +.Dq sticky +status word may be maintained in which a bit is set every time an +exceptional floating point condition is encountered, whether or not a +.Dv SIGFPE +is generated. +The +.Fn fpsetsticky +function will set or clear the specified exception history bits. +The +.Fn fpgetsticky +function will return the exception history bits. +.Sh RETURN VALUES +The +.Fn fpgetround +and +.Fn fpsetround +functions return the +.Pq previous +rounding mode. +The +.Fn fpgetmask , +.Fn fpsetmask , +.Fn fpgetsticky , +and +.Fn fpsetsticky +functions return the +.Pq previous +exception mask and exception history bits. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr fenv 3 +.Sh BUGS +There is no way to return an unsupported value. +Not all processors support all the modes. +These interfaces are deprecated and the ones +in +.Xr fenv 3 +should be used, although the interfaces in +.Xr fenv 3 +don't support getting or setting the precision. diff --git a/static/netbsd/man3/fputs.3 b/static/netbsd/man3/fputs.3 new file mode 100644 index 00000000..b478264f --- /dev/null +++ b/static/netbsd/man3/fputs.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: fputs.3,v 1.14 2017/07/30 23:13:24 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fputs.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 30, 2017 +.Dt FPUTS 3 +.Os +.Sh NAME +.Nm fputs , +.Nm puts +.Nd output a line to a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fputs "const char * restrict str" "FILE * restrict stream" +.Ft int +.Fn puts "const char *str" +.Sh DESCRIPTION +The function +.Fn fputs +writes the string pointed to by +.Fa str +to the stream pointed to by +.Fa stream . +.\" The terminating +.\" .Dv NUL +.\" character is not written. +.Pp +The function +.Fn puts +writes the string +.Fa str , +and a terminating newline character, +to the stream +.Em stdout . +.Sh RETURN VALUES +The functions +.Fn fputs +and +.Fn puts +return a nonnegative integer on success and +.Dv EOF +on error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa stream +supplied +is not a writable stream. +.El +.Pp +The functions +.Fn fputs +and +.Fn puts +may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr write 2 . +.Sh SEE ALSO +.Xr write 2 , +.Xr ferror 3 , +.Xr putc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputs +and +.Fn puts +conform to +.St -ansiC . diff --git a/static/netbsd/man3/fputws.3 b/static/netbsd/man3/fputws.3 new file mode 100644 index 00000000..858a7af3 --- /dev/null +++ b/static/netbsd/man3/fputws.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: fputws.3,v 1.3 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fputs.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Original version ID: +.\" FreeBSD: src/lib/libc/stdio/fputs.3,v 1.8 2001/10/01 16:08:59 ru Exp +.\" FreeBSD: src/lib/libc/stdio/fputws.c,v 1.4 2002/09/20 13:25:40 tjr Exp +.\" +.Dd August 6, 2002 +.Dt FPUTWS 3 +.Os +.Sh NAME +.Nm fputws +.Nd output a line of wide characters to a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft int +.Fn fputws "const wchar_t * restrict ws" "FILE * restrict fp" +.Sh DESCRIPTION +The +.Fn fputws +function writes the wide-character string pointed to by +.Fa ws +to the stream pointed to by +.Fa fp . +.Sh RETURN VALUES +The +.Fn fputws +function +returns 0 on success and \-1 on error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fp +argument supplied +is not a writable stream. +.El +.Pp +The +.Fn fputws +function may also fail and set +.Va errno +for any of the errors specified for the routine +.Xr write 2 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fputs 3 , +.Xr putwc 3 , +.Xr stdio 3 +.Sh STANDARDS +The +.Fn fputws +function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/fread.3 b/static/netbsd/man3/fread.3 new file mode 100644 index 00000000..c5f48766 --- /dev/null +++ b/static/netbsd/man3/fread.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: fread.3,v 1.16 2021/02/01 17:50:53 jdolecek Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fread.3 8.2 (Berkeley) 3/8/94 +.\" +.Dd February 1, 2020 +.Dt FREAD 3 +.Os +.Sh NAME +.Nm fread , +.Nm fwrite +.Nd binary stream input/output +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft size_t +.Fn fread "void * restrict ptr" "size_t size" "size_t nmemb" "FILE * restrict stream" +.Ft size_t +.Fn fwrite "const void * restrict ptr" "size_t size" "size_t nmemb" "FILE * restrict stream" +.Sh DESCRIPTION +The function +.Fn fread +reads +.Fa nmemb +objects, each +.Fa size +bytes long, from the stream pointed to by +.Fa stream , +storing them at the location given by +.Fa ptr . +.Pp +The function +.Fn fwrite +writes +.Fa nmemb +objects, each +.Fa size +bytes long, to the stream pointed to by +.Fa stream , +obtaining them from the location given by +.Fa ptr . +.Pp +Mixing +.Fn fread +and +.Fn fwrite +calls without setting the file position explicitly using +.Xr fsetpos 3 +between read and write or write and read operations will lead to unexpected +results because of buffering the file pointer not being set to the +expected position after each operation completes. +This behavior is allowed by ANSI C for efficiency and it will not be changed. +.Sh RETURN VALUES +The functions +.Fn fread +and +.Fn fwrite +advance the file position indicator for the stream +by the number of bytes read or written. +They return the number of objects read or written. +If +.Fa size +or +.Fa nmemb +is 0, the functions return 0 and the state of +.Fa stream +remains unchanged. +.Pp +If the product of +.Fa size +and +.Fa nmemb +results in size_t overflow, 0 is returned and errno +is set to +.Er EOVERFLOW . + +If an error occurs, or the end-of-file is reached, +the return value is a short object count (or zero). +.Pp +The function +.Fn fread +does not distinguish between end-of-file and error, and callers +must use +.Xr feof 3 +and +.Xr ferror 3 +to determine which occurred. +The function +.Fn fwrite +returns a value less than +.Fa nmemb +only if a write error has occurred. +.Sh SEE ALSO +.Xr read 2 , +.Xr write 2 +.Sh STANDARDS +The functions +.Fn fread +and +.Fn fwrite +conform to +.St -ansiC . diff --git a/static/netbsd/man3/freelocale.3 b/static/netbsd/man3/freelocale.3 new file mode 100644 index 00000000..794c6a10 --- /dev/null +++ b/static/netbsd/man3/freelocale.3 @@ -0,0 +1,58 @@ +.\" $NetBSD: freelocale.3,v 1.3 2021/02/15 15:38:43 wiz Exp $ +.\" Copyright (c) 2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by David Chisnall under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/locale/freelocale.3 303495 2016-07-29 17:18:47Z ed $ +.Dd February 15, 2021 +.Dt FREELOCALE 3 +.Os +.Sh NAME +.Nm freelocale +.Nd Frees a locale created with +.Xr duplocale 3 +or +.Xr newlocale 3 +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In locale.h +.Ft void +.Fn freelocale "locale_t locale" +.Sh DESCRIPTION +Frees a +.Fa locale_t . +This relinquishes any resources held exclusively by this locale. +.Sh SEE ALSO +.Xr duplocale 3 , +.Xr localeconv 3 , +.Xr newlocale 3 +.\" .Xr querylocale 3 , +.\" .Xr uselocale 3 , +.\" .Xr xlocale 3 +.Sh STANDARDS +This function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/frexp.3 b/static/netbsd/man3/frexp.3 new file mode 100644 index 00000000..d9a6cda2 --- /dev/null +++ b/static/netbsd/man3/frexp.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: frexp.3,v 1.4 2015/09/10 12:30:08 wiz Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)frexp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 10, 2015 +.Dt FREXP 3 +.Os +.Sh NAME +.Nm frexp +.Nd convert floating-point number to fractional and integral components +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn frexp "double value" "int *exp" +.Ft float +.Fn frexpf "float value" "int *exp" +.Ft long double +.Fn frexpl "long double value" "int *exp" +.Sh DESCRIPTION +The +.Fn frexp +function breaks a floating-point number into a normalized +fraction and an integral power of 2. +It stores the integer in the +.Em int +object pointed to by +.Fa exp . +.Sh RETURN VALUES +The +.Fn frexp +function returns the value +.Em x , +such that +.Em x +is a +.Em double +with magnitude in the interval [1/2, 1) or zero, and +.Fa value +equals +.Em x +times 2 raised to the power +.Fa *exp . +If +.Fa value +is zero, both parts of the result are zero. +.Sh SEE ALSO +.Xr ldexp 3 , +.Xr math 3 , +.Xr modf 3 +.Sh STANDARDS +The +.Fn frexp +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/fseek.3 b/static/netbsd/man3/fseek.3 new file mode 100644 index 00000000..33b0c076 --- /dev/null +++ b/static/netbsd/man3/fseek.3 @@ -0,0 +1,247 @@ +.\" $NetBSD: fseek.3,v 1.29 2021/09/11 18:46:22 rillig Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 11, 2021 +.Dt FSEEK 3 +.Os +.Sh NAME +.Nm fgetpos , +.Nm fseek , +.Nm fseeko , +.Nm fsetpos , +.Nm ftell , +.Nm ftello , +.Nm rewind +.Nd reposition a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fseek "FILE *stream" "long int offset" "int whence" +.Ft int +.Fn fseeko "FILE *stream" "off_t offset" "int whence" +.Ft long int +.Fn ftell "FILE *stream" +.Ft off_t +.Fn ftello "FILE *stream" +.Ft void +.Fn rewind "FILE *stream" +.Ft int +.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" +.Ft int +.Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos" +.Sh DESCRIPTION +The +.Fn fseek +function sets the file position indicator for the stream pointed +to by +.Fa stream . +The new position, measured in bytes, is obtained by adding +.Fa offset +bytes to the position specified by +.Fa whence . +If +.Fa whence +is set to +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END , +the offset is relative to the +start of the file, the current position indicator, or end-of-file, +respectively. +A successful call to the +.Fn fseek +function clears the end-of-file indicator for the stream and undoes +any effects of the +.Xr ungetc 3 +function on the same stream. +.Pp +The +.Fn fseeko +function is identical to the +.Fn fseek +function except that the +.Fa offset +argument is of type +.Fa off_t . +.Pp +The +.Fn ftell +function +obtains the current value of the file position indicator for the +stream pointed to by +.Fa stream . +.Pp +The +.Fn ftello +function is identical to the +.Fn ftell +function except that the return value is of type +.Fa off_t . +.Pp +The +.Fn rewind +function sets the file position indicator for the stream pointed +to by +.Fa stream +to the beginning of the file. +It is equivalent to: +.Pp +.Dl (void)fseek(stream, 0L, SEEK_SET) +.Pp +except that the error indicator for the stream is also cleared +(see +.Xr clearerr 3 ) . +.Pp +In this implementations, +.Dq Fa fpos_t +is a complex object that represents both the position and the parse +state of the stream, making these routines the only way to portably +reposition a text stream. +The +.Ar pos +argument of +.Fn fsetpos +must always be initialized by +a call to +.Fn fgetpos . +.Sh RETURN VALUES +The +.Fn rewind +function +returns no value. +.Pp +Upon successful completion, +.Fn fgetpos , +.Fn fseek , +.Fn fseeko , +and +.Fn fsetpos +return 0, +whereas the functions +.Fn ftell +and +.Fn ftello +return the current offset. +On failure, +.Fn fseek , +.Fn fseeko , +.Fn ftell , +and +.Fn ftello +return \-1, while +.Fn fgetpos +and +.Fn fsetpos +return a nonzero value. +.Pp +On error all functions set the global variable +.Va errno +to indicate the error. +Since the +.Fn rewind +function does not return an error code, applications need to clear +.Va errno +before calling it in order to detect errors. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa stream +specified +is not a seekable stream. +.It Bq Er EINVAL +The +.Fa whence +argument to +.Fn fseek +was not +.Dv SEEK_SET , +.Dv SEEK_END , +or +.Dv SEEK_CUR . +.It Bq Er EOVERFLOW +For +.Fn ftell , +the current file offset cannot be represented correctly in an object of type +.Fa long . +.El +.Pp +The function +.Fn fgetpos , +.Fn fseek , +.Fn fseeko , +.Fn fsetpos , +.Fn ftell , +.Fn ftello , +and +.Fn rewind +may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fflush 3 , +.Xr fstat 2 , +.Xr lseek 2 , +and +.Xr malloc 3 . +.Sh SEE ALSO +.Xr lseek 2 , +.Xr clearerr 3 , +.Xr ungetc 3 +.Sh STANDARDS +The +.Fn fgetpos , +.Fn fsetpos , +.Fn fseek , +.Fn ftell , +and +.Fn rewind +functions +conform to +.St -ansiC . +The +.Fn fseeko +and +.Fn ftello +functions conform to +.St -xsh5 . +.Sh BUGS +The +.Fn fgetpos +and +.Fn fsetpos +functions don't store/set shift states of the stream in this implementation. diff --git a/static/netbsd/man3/fstab.nfs.3 b/static/netbsd/man3/fstab.nfs.3 new file mode 100644 index 00000000..8e824feb --- /dev/null +++ b/static/netbsd/man3/fstab.nfs.3 @@ -0,0 +1,16 @@ +# $NetBSD: fstab.nfs.3,v 1.2 2005/04/03 14:12:14 hubertf Exp $ +# +# Sample fstab for NFS based system +# see fstab(5) for details on what the fields mean +# Notes: +# All swap devices are now configured by swapctl(8), so a swap entry +# is now needed for all swap partitions so that the "swapctl -A" in +# /etc/rc will find them, or you will have no swap space. +# +nfs-server:/export/root/arch / nfs rw,auto 0 0 +nfs-server:/export/swap/mynext none swap sw,nfsmntpt=/swap 0 0 +# +# Possibly include data from the following files here: +# fstab.cdrom +# fstab.pseudo +# fstab.ramdisk diff --git a/static/netbsd/man3/fstab.wd0.3 b/static/netbsd/man3/fstab.wd0.3 new file mode 100644 index 00000000..11eb9070 --- /dev/null +++ b/static/netbsd/man3/fstab.wd0.3 @@ -0,0 +1,18 @@ +# $NetBSD: fstab.wd0.3,v 1.4 2005/05/06 08:41:00 hubertf Exp $ +# +# Sample fstab for IDE disk based system +# see fstab(5) for details on what the fields mean +# Notes: +# All swap devices are now configured by swapctl(8), so a swap entry +# is now needed for all swap partitions so that the "swapctl -A" in +# /etc/rc will find them, or you will have no swap space. +# +/dev/wd0a / ffs rw 1 1 +/dev/wd0b none swap sw 0 0 +/dev/wd0f /usr ffs rw 1 2 +/dev/wd0g /var ffs rw 1 2 +# +# Possibly include data from the following files here: +# fstab.cdrom +# fstab.pseudo +# fstab.ramdisk diff --git a/static/netbsd/man3/ftime.3 b/static/netbsd/man3/ftime.3 new file mode 100644 index 00000000..145152d2 --- /dev/null +++ b/static/netbsd/man3/ftime.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: ftime.3,v 1.15 2010/03/22 21:55:39 joerg Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ftime.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt FTIME 3 +.Os +.Sh NAME +.Nm ftime +.Nd get date and time +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.In sys/types.h +.In sys/timeb.h +.Ft int +.Fn ftime "struct timeb *tp" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr gettimeofday 2 . +It is available from the compatibility library, libcompat. +.Ef +.Pp +.Bf -symbolic +Note: time zone information is no longer provided by this interface. +See +.Xr localtime 3 +for information on how to retrieve it. +.Ef +.Pp +The +.Fn ftime +routine fills in a structure pointed to by its argument, +as defined by +.In sys/timeb.h : +.Bd -literal -offset indent +struct timeb { + time_t time; + unsigned short millitm; + short timezone; + short dstflag; +}; +.Ed +.Pp +The structure contains the time since the epoch in seconds, +up to 1000 milliseconds of more-precise interval. +The +.Em timezone +and +.Em dstflag +fields are provided for source compatibility, but are always zero. +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr settimeofday 2 , +.Xr ctime 3 , +.Xr localtime 3 , +.Xr time 3 +.Sh HISTORY +The +.Fn ftime +function appeared in +.Bx 4.1 . diff --git a/static/netbsd/man3/ftok.3 b/static/netbsd/man3/ftok.3 new file mode 100644 index 00000000..f465707b --- /dev/null +++ b/static/netbsd/man3/ftok.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: ftok.3,v 1.18 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 1994 SigmaSoft, Th. Lockert +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 27, 2010 +.Dt FTOK 3 +.Os +.Sh NAME +.Nm ftok +.Nd create IPC identifier from path name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.Ft key_t +.Fn ftok "const char *path" "int id" +.Sh DESCRIPTION +The +.Fn ftok +function attempts to create a unique key suitable for use with the +.Xr msgget 2 , +.Xr semget 2 +and +.Xr shmget 2 +functions given the +.Fa path +of an existing file and a user-selectable +.Fa id . +.Pp +The specified +.Fa path +must specify an existing file that is accessible to the calling process +or the call will fail. +Also, note that links to files will return the same key, given the same +.Fa id . +.Pp +Only the 8 least significant bits of +.Fa id +are used in the key generation; the rest of the bits are ignored. +.Sh RETURN VALUES +The +.Fn ftok +function will return ((key_t)-1) if +.Fa path +does not exist or if it cannot be accessed by the calling process. +.Sh SEE ALSO +.Xr msgget 2 , +.Xr semget 2 , +.Xr shmget 2 +.Sh STANDARDS +The +.Fn ftok +function conforms to +.St -p1003.1 . +.Sh HISTORY +The +.Fn ftok +function originated with System V and is typically used by programs +that use the System V IPC routines. +.Sh AUTHORS +.An Thorsten Lockert Aq Mt tholo@sigmasoft.com +.Sh BUGS +The returned key is computed based on the device and inode of the +specified +.Fa path +in combination with the given +.Fa id . +Thus it is quite possible for the routine to return duplicate keys +given that those fields are not 8- and 16-bit quantities like they +were on System V based systems where this library routine's ancestor +were originally created. diff --git a/static/netbsd/man3/fts.3 b/static/netbsd/man3/fts.3 new file mode 100644 index 00000000..f7a4f6af --- /dev/null +++ b/static/netbsd/man3/fts.3 @@ -0,0 +1,793 @@ +.\" $NetBSD: fts.3,v 1.38 2024/10/29 00:18:54 uwe Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 +.\" +.Dd October 27, 2024 +.Dt FTS 3 +.Os +.Sh NAME +.Nm fts , +.Nm fts_open , +.Nm fts_read , +.Nm fts_children , +.Nm fts_set , +.Nm fts_close +.Nd traverse a file hierarchy +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.In fts.h +.Ft FTS * +.Fo fts_open +.Fa "char * const *path_argv" +.Fa "int options" +.Fa "int (*compar)(const FTSENT **, const FTSENT **)" +.Fc +.Ft FTSENT * +.Fn fts_read "FTS *ftsp" +.Ft FTSENT * +.Fn fts_children "FTS *ftsp" "int options" +.Ft int +.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" +.Ft int +.Fn fts_close "FTS *ftsp" +.Sh DESCRIPTION +The +.Nm +functions are provided for traversing +.Ux +file hierarchies. +A simple overview is that the +.Fn fts_open +function returns a +.Dq handle +on a file hierarchy, which is then supplied to +the other +.Nm +functions. +The function +.Fn fts_read +returns a pointer to a structure describing one of the files in the file +hierarchy. +The function +.Fn fts_children +returns a pointer to a linked list of structures, each of which describes +one of the files contained in a directory in the hierarchy. +In general, directories are visited two distinguishable times; in pre-order +.Pq before any of their descendants are visited +and in post-order +.Pq after all of their descendants have been visited . +Files are visited once. +It is possible to walk the hierarchy +.Dq logically +.Pq ignoring symbolic links +or physically +.Pq visiting symbolic links , +order the walk of the hierarchy or prune and/or re-visit portions of +the hierarchy. +.Pp +Two structures are defined +.Pq and Li typedef Ap ed +in the include file +.In fts.h . +The first is +.Vt FTS , +the structure that represents the file hierarchy itself. +The second is +.Vt FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.Vt FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, +.Dq file +and +.Dq Vt FTSENT No structure +are generally +interchangeable. +The +.Vt FTSENT +structure contains at least the following fields, which are +described in greater detail below: +.Bd -literal -offset indent +typedef struct _ftsent { + u_short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + short fts_pathlen; /* strlen(fts_path) */ + char *fts_name; /* file name */ + short fts_namelen; /* strlen(fts_name) */ + short fts_level; /* depth (\-1 to N) */ + int fts_errno; /* file errno */ + long fts_number; /* local numeric value */ + void *fts_pointer; /* local address value */ + struct ftsent *fts_parent; /* parent directory */ + struct ftsent *fts_link; /* next file structure */ + struct ftsent *fts_cycle; /* cycle structure */ + struct stat *fts_statp; /* stat(2) information */ +} FTSENT; +.Ed +.Pp +These fields are defined as follows: +.Bl -tag -width Fa +.It Fa fts_info +One of the following flags describing the returned +.Vt FTSENT +structure and +the file it represents. +With the exception of directories without errors +.Pq Dv FTS_D , +all of these +entries are terminal, that is, they will not be revisited, nor will any +of their descendants be visited. +.Bl -tag -width Dv +.It Dv FTS_D +A directory being visited in pre-order. +.It Dv FTS_DC +A directory that causes a cycle in the tree. +The +.Fa fts_cycle +field of the +.Vt FTSENT +structure will be filled in as well. +.It Dv FTS_DEFAULT +Any +.Vt FTSENT +structure that represents a file type not explicitly described +by one of the other +.Fa fts_info +values. +.It Dv FTS_DNR +A directory which cannot be read. +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_DOT +A file named +.Ql \&. +or +.Ql .. +which was not specified as a file name to +.Fn fts_open +(see +.Dv FTS_SEEDOT ) . +.It Dv FTS_DP +A directory being visited in post-order. +The contents of the +.Vt FTSENT +structure will be unchanged from when +it was returned in pre-order, i.e., with the +.Fa fts_info +field set to +.Dv FTS_D . +.It Dv FTS_ERR +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_F +A regular file. +.It Dv FTS_NS +A file for which no +.Xr stat 2 +information was available. +The contents of the +.Fa fts_statp +field are undefined. +This is an error return, and the +.Fa fts_errno +field will be set to indicate what caused the error. +.It Dv FTS_NSOK +A file for which no +.Xr stat 2 +information was requested. +The contents of the +.Fa fts_statp +field are undefined. +.It Dv FTS_SL +A symbolic link. +.It Dv FTS_SLNONE +A symbolic link with a non-existent target. +The contents of the +.Fa fts_statp +field reference the file characteristic information for the symbolic link +itself. +.It Dv FTS_W +A whiteout object. +.El +.It Fa fts_accpath +A path for accessing the file from the current directory. +.It Fa fts_path +The path for the file relative to the root of the traversal. +This path contains the path specified to +.Fn fts_open +as a prefix. +.It Fa fts_pathlen +The length of the string referenced by +.Fa fts_path . +.It Fa fts_name +The name of the file. +.It Fa fts_namelen +The length of the string referenced by +.Fa fts_name . +.It Fa fts_level +The depth of the traversal, numbered from \-1 to N, where this file +was found. +The +.Vt FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered \-1, and the +.Vt FTSENT +structure for the root +itself is numbered 0. +.It Fa fts_errno +Upon return of a +.Vt FTSENT +structure from the +.Fn fts_children +or +.Fn fts_read +functions, with its +.Fa fts_info +field set to +.Dv FTS_DNR , +.Dv FTS_ERR +or +.Dv FTS_NS , +the +.Fa fts_errno +field contains the value of the external variable +.Va errno +specifying the cause of the error. +Otherwise, the contents of the +.Fa fts_errno +field are undefined. +.It Fa fts_number +This field is provided for the use of the application program and is +not modified by the +.Nm +functions. +It is initialized to 0. +.It Fa fts_pointer +This field is provided for the use of the application program and is +not modified by the +.Nm +functions. +It is initialized to +.Dv NULL . +.It Fa fts_parent +A pointer to the +.Vt FTSENT +structure referencing the file in the hierarchy +immediately above the current file, i.e., the directory of which this +file is a member. +A parent structure for the initial entry point is provided as well, +however, only the +.Fa fts_level , +.Fa fts_number +and +.Fa fts_pointer +fields are guaranteed to be initialized. +.It Fa fts_link +Upon return from the +.Fn fts_children +function, the +.Fa fts_link +field points to the next structure in the +.Dv NULL Ns -terminated +linked list of directory members. +Otherwise, the contents of the +.Fa fts_link +field are undefined. +.It Fa fts_cycle +If a directory causes a cycle in the hierarchy (see +.Dv FTS_DC ) , +either because +of a hard link between two directories, or a symbolic link pointing to a +directory, the +.Fa fts_cycle +field of the structure will point to the +.Vt FTSENT +structure in the hierarchy that references the same file as the current +.Vt FTSENT +structure. +Otherwise, the contents of the +.Fa fts_cycle +field are undefined. +.It Fa fts_statp +A pointer to +.Xr stat 2 +information for the file. +.El +.Pp +A single buffer is used for all of the paths of all of the files in the +file hierarchy. +Therefore, the +.Fa fts_path +and +.Fa fts_accpath +fields are guaranteed to be +.Tn NUL Ns -terminated +.Em only +for the file most recently returned by +.Fn fts_read . +To use these fields to reference any files represented by other +.Vt FTSENT +structures will require that the path buffer be modified using the +information contained in that +.Vt FTSENT +structure's +.Fa fts_pathlen +field. +Any such modifications should be undone before further calls to +.Fn fts_read +are attempted. +The +.Fa fts_name +field is always +.Tn NUL Ns -terminated . +.Ss FTS_OPEN +The +.Fn fts_open +function takes a pointer to an array of character pointers naming one +or more paths which make up a logical file hierarchy to be traversed. +The array must be terminated by a +.Dv NULL +pointer. +.Pp +There are +a number of options, at least one of which +.Po +either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL +.Pc +must be specified. +The options are selected by +.Em or Ns 'ing +the following values: +.Bl -tag -width Dv +.It Dv FTS_COMFOLLOW +This option causes any symbolic link specified as a root path to be +followed immediately whether or not +.Dv FTS_LOGICAL +is also specified. +.It Dv FTS_LOGICAL +This option causes the +.Nm +routines to return +.Vt FTSENT +structures for the targets of symbolic links +instead of the symbolic links themselves. +If this option is set, the only symbolic links for which +.Vt FTSENT +structures +are returned to the application are those referencing non-existent files. +Either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL +.Em must +be provided to the +.Fn fts_open +function. +.It Dv FTS_NOCHDIR +As a performance optimization, the +.Nm +functions change directories as they walk the file hierarchy. +This has the side-effect that an application cannot rely on being +in any particular directory during the traversal. +The +.Dv FTS_NOCHDIR +option turns off this optimization, and the +.Nm +functions will not change the current directory. +Note that applications should not themselves change their current directory +and try to access files unless +.Dv FTS_NOCHDIR +is specified and absolute +pathnames were provided as arguments to +.Fn fts_open . +.It Dv FTS_NOSTAT +By default, returned +.Vt FTSENT +structures reference file characteristic information +.Pq the Fa fts_statp No field +for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the +.Nm +functions to set the +.Fa fts_info +field to +.Dv FTS_NSOK +and leave the contents of the +.Fa fts_statp +field undefined. +.It Dv FTS_PHYSICAL +This option causes the +.Nm +routines to return +.Vt FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.Vt FTSENT +structures for all symbolic links in the +hierarchy are returned to the application. +Either +.Dv FTS_LOGICAL +or +.Dv FTS_PHYSICAL +.Em must +be provided to the +.Fn fts_open +function. +.It Dv FTS_SEEDOT +By default, unless they are specified as path arguments to +.Fn fts_open , +any files named +.Ql \&. +or +.Ql .. +encountered in the file hierarchy are ignored. +This option causes the +.Nm +routines to return +.Vt FTSENT +structures for them. +.It Dv FTS_WHITEOUT +Return whiteout entries, which are normally hidden. +.It Dv FTS_XDEV +This option prevents +.Nm +from descending into directories that have a different device number +than the file from which the descent began. +.El +.Pp +The argument +.Fn compar +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.Vt FTSENT +structures as arguments and +should return a negative value, zero, or a positive value to indicate +if the file referenced by its first argument comes before, in any order +with respect to, or after, the file referenced by its second argument. +The +.Fa fts_accpath , +.Fa fts_path +and +.Fa fts_pathlen +fields of the +.Vt FTSENT +structures may +.Em never +be used in this comparison. +If the +.Fa fts_info +field is set to +.Dv FTS_NS +or +.Dv FTS_NSOK , +the +.Fa fts_statp +field may not either. +If the +.Fn compar +argument is +.Dv NULL , +the directory traversal order is in the order listed in +.Fa path_argv +for the root paths, and in the order listed in the directory for +everything else. +.Pp +If an error occurs, +.Fn fts_open +returns +.Dv NULL +and sets +.Va errno +appropriately. +.Ss FTS_READ +The +.Fn fts_read +function returns a pointer to an +.Vt FTSENT +structure describing a file in +the hierarchy. +Directories +.Pq that are readable and do not cause cycles +are visited at least twice, once in pre-order and once in post-order. +All other files are visited at least once. +.Po +Hard links between directories that do not cause cycles or symbolic +links to symbolic links may cause files to be visited more than once, +or directories more than twice +.Pc . +.Pp +If all the members of the hierarchy have been returned, +.Fn fts_read +returns +.Dv NULL +and sets the external variable +.Va errno +to 0. +If an error unrelated to a file in the hierarchy occurs, +.Fn fts_read +returns +.Dv NULL +and sets +.Va errno +appropriately. +If an error related to a returned file occurs, a pointer to an +.Vt FTSENT +structure is returned, and +.Va errno +may or may not have been set (see +.Fa fts_info ) . +.Pp +The +.Vt FTSENT +structures returned by +.Fn fts_read +may be overwritten after a call to +.Fn fts_close +on the same file hierarchy stream, or, after a call to +.Fn fts_read +on the same file hierarchy stream unless they represent a file of type +directory, in which case they will not be overwritten until after a call to +.Fn fts_read +after the +.Vt FTSENT +structure has been returned by the function +.Fn fts_read +in post-order. +.Ss FTS_CHILDREN +The +.Fn fts_children +function returns a pointer to an +.Vt FTSENT +structure describing the first entry in a +.Dv NULL Ns -terminated +linked list of the files in the directory represented by the +.Vt FTSENT +structure most recently returned by +.Fn fts_read . +The list is linked through the +.Fa fts_link +field of the +.Vt FTSENT +structure, and is ordered by the user-specified comparison function, if any. +Repeated calls to +.Fn fts_children +will recreate this linked list. +.Pp +As a special case, if +.Fn fts_read +has not yet been called for a hierarchy, +.Fn fts_children +will return a pointer to the files in the logical directory specified to +.Fn fts_open , +i.e., the arguments specified to +.Fn fts_open . +Otherwise, if the +.Vt FTSENT +structure most recently returned by +.Fn fts_read +is not a directory being visited in pre-order, +or the directory does not contain any files, +.Fn fts_children +returns +.Dv NULL +and sets +.Va errno +to zero. +If an error occurs, +.Fn fts_children +returns +.Dv NULL +and sets +.Va errno +appropriately. +.Pp +The +.Vt FTSENT +structures returned by +.Fn fts_children +may be overwritten after a call to +.Fn fts_children , +.Fn fts_close +or +.Fn fts_read +on the same file hierarchy stream. +.Pp +.Em Option +may be set to the following value: +.Bl -tag -width Dv +.It Dv FTS_NAMEONLY +Only the names of the files are needed. +The contents of all the fields in the returned linked list of structures +are undefined with the exception of the +.Fa fts_name +and +.Fa fts_namelen +fields. +.El +.Ss FTS_SET +The function +.Fn fts_set +allows the user application to determine further processing for the +file +.Fa f +of the stream +.Fa ftsp . +The +.Fn fts_set +function +returns 0 on success, and \-1 if an error occurs. +.Em Option +must be set to one of the following values: +.Bl -tag -width Dv +.It Dv FTS_AGAIN +Re-visit the file; any file type may be re-visited. +The next call to +.Fn fts_read +will return the referenced file. +The +.Fa fts_stat +and +.Fa fts_info +fields of the structure will be reinitialized at that time, +but no other fields will have been changed. +This option is meaningful only for the most recently returned +file from +.Fn fts_read . +Normal use is for post-order directory visits, where it causes the +directory to be re-visited +.Pq in both pre- and post-order +as well as all of its descendants. +.It Dv FTS_FOLLOW +The referenced file must be a symbolic link. +If the referenced file is the one most recently returned by +.Fn fts_read , +the next call to +.Fn fts_read +returns the file with the +.Fa fts_info +and +.Fa fts_statp +fields reinitialized to reflect the target of the symbolic link instead +of the symbolic link itself. +If the file is one of those most recently returned by +.Fn fts_children , +the +.Fa fts_info +and +.Fa fts_statp +fields of the structure, when returned by +.Fn fts_read , +will reflect the target of the symbolic link instead of the symbolic link +itself. +In either case, if the target of the symbolic link does not exist the +fields of the returned structure will be unchanged and the +.Fa fts_info +field will be set to +.Dv FTS_SLNONE . +.Pp +If the target of the link is a directory, the pre-order return, followed +by the return of all of its descendants, followed by a post-order return, +is done. +.It Dv FTS_SKIP +No descendants of this file are visited. +The file may be one of those most recently returned by either +.Fn fts_children +or +.Fn fts_read . +.El +.Ss FTS_CLOSE +The +.Fn fts_close +function closes a file hierarchy stream +.Fa ftsp +and restores the current directory to the directory from which +.Fn fts_open +was called to open +.Fa ftsp . +The +.Fn fts_close +function +returns 0 on success, and \-1 if an error occurs. +.Sh ERRORS +The function +.Fn fts_open +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr open 2 +and +.Xr malloc 3 . +.Pp +The function +.Fn fts_close +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr chdir 2 +and +.Xr close 2 . +.Pp +The functions +.Fn fts_read +and +.Fn fts_children +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr chdir 2 , +.Xr malloc 3 , +.Xr opendir 3 , +.Xr readdir 3 +and +.Xr stat 2 . +.Pp +In addition, +.Fn fts_children , +.Fn fts_open +and +.Fn fts_set +may fail and set +.Va errno +as follows: +.Bl -tag -width Er +.It Bq Er EINVAL +The options were invalid. +.El +.Sh SEE ALSO +.Xr find 1 , +.Xr chdir 2 , +.Xr stat 2 , +.Xr qsort 3 , +.Xr symlink 7 +.Sh STANDARDS +The +.Nm +utility was expected to be included in the +.St -p1003.1-88 +revision. +But twenty years later, it still was not included in the +.St -p1003.1-2008 +revision. diff --git a/static/netbsd/man3/ftw.3 b/static/netbsd/man3/ftw.3 new file mode 100644 index 00000000..4343823a --- /dev/null +++ b/static/netbsd/man3/ftw.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: ftw.3,v 1.5 2010/04/30 04:39:16 jruoho Exp $ +.\" +.\" From OpenBSD: ftw.3,v 1.4 2003/10/30 18:52:58 jmc Exp +.\" +.\" Copyright (c) 2003 Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.Dd April 30, 2010 +.Dt FTW 3 +.Os +.Sh NAME +.Nm ftw, nftw +.Nd traverse (walk) a file tree +.Sh SYNOPSIS +.In ftw.h +.Ft int +.Fo ftw +.Fa "const char *path" +.Fa "int (*fn)(const char *, const struct stat *, int)" +.Fa "int maxfds" +.Fc +.Ft int +.Fo nftw +.Fa "const char *path" +.Fa "int (*fn)(const\ char\ *, const\ struct\ stat\ *, int, struct\ FTW\ *)" +.Fa "int maxfds" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Bf -symbolic +These functions are provided for compatibility with legacy code. +New code should use the +.Xr fts 3 +functions. +.Ef +.Pp +The +.Fn ftw +and +.Fn nftw +functions traverse (walk) the directory hierarchy rooted in +.Fa path . +For each object in the hierarchy, these functions call the function +pointed to by +.Fa fn . +The +.Fn ftw +function passes this function a pointer to a NUL-terminated string containing +the name of the object, a pointer to a stat structure corresponding to the +object, and an integer flag. +The +.Fn nftw +function passes the aforementioned arguments plus a pointer to a +.Dv FTW +structure as defined by +.In ftw.h +(shown below): +.Bd -literal +struct FTW { + int base; /* offset of basename into pathname */ + int level; /* directory depth relative to starting point */ +}; +.Ed +.Pp +Possible values for the flag passed to +.Fa fn +are: +.Bl -tag -width FTW_DNR +.It Dv FTW_F +A regular file. +.It Dv FTW_D +A directory being visited in pre-order. +.It Dv FTW_DNR +A directory which cannot be read. +The directory will not be descended into. +.It Dv FTW_DP +A directory being visited in post-order +.Pq Fn nftw No only . +.It Dv FTW_NS +A file for which no +.Xr stat 2 +information was available. +The contents of the stat structure are undefined. +.It Dv FTW_SL +A symbolic link. +.It Dv FTW_SLN +A symbolic link with a non-existent target +.Pq Fn nftw No only . +.El +.Pp +The +.Fn ftw +function traverses the tree in pre-order. +That is, it processes the directory before the directory's contents. +.Pp +The +.Fa maxfds +argument specifies the maximum number of file descriptors +to keep open while traversing the tree. +It has no effect in this implementation. +.Pp +The +.Fn nftw +function has an additional +.Fa flags +argument with the following possible values: +.Bl -tag -width FTW_MOUNT +.It Dv FTW_PHYS +Physical walk, don't follow symbolic links. +.It Dv FTW_MOUNT +The walk will not cross a mount point. +.It FTW_DEPTH +Process directories in post-order. +Contents of a directory are visited before the directory itself. +By default, +.Fn nftw +traverses the tree in pre-order. +.It FTW_CHDIR +Change to a directory before reading it. +By default, +.Fn nftw +will change its starting directory. +The current working directory will be restored to its original value before +.Fn nftw +returns. +.El +.Sh RETURN VALUES +If the tree was traversed successfully, the +.Fn ftw +and +.Fn nftw +functions return 0. +If the function pointed to by +.Fa fn +returns a non-zero value, +.Fn ftw +and +.Fn nftw +will stop processing the tree and return the value from +.Fa fn . +Both functions return \-1 if an error is detected. +.Sh ERRORS +The +.Fn ftw +and +.Fn nftw +functions may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr close 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr malloc 3 , +.Xr opendir 3 , +and +.Xr readdir 3 . +If the +.Dv FGTW_CHDIR +flag is set, the +.Fn nftw +function may fail and set +.Va errno +for any of the errors specified for +.Xr chdir 2 . +In addition, either function may fail and set +.Va errno +as follows: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa maxfds +argument is less than 1 or greater than +.Dv OPEN_MAX . +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr close 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr fts 3 , +.Xr malloc 3 , +.Xr opendir 3 , +.Xr readdir 3 +.Sh STANDARDS +The +.Fn ftw +and +.Fn nftw +functions conform to +.St -p1003.1-2001 . +The +.St -p1003.1-2008 +revision marked the function +.Fn ftw +as obsolete. +.Sh BUGS +The +.Fa maxfds +argument is currently ignored. diff --git a/static/netbsd/man3/funopen.3 b/static/netbsd/man3/funopen.3 new file mode 100644 index 00000000..7510ff32 --- /dev/null +++ b/static/netbsd/man3/funopen.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: funopen.3,v 1.27 2025/02/24 22:10:51 andvar Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)funopen.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd October 13, 2024 +.Dt FUNOPEN 3 +.Os +.Sh NAME +.Nm funopen , +.Nm funopen2 , +.Nm fropen , +.Nm fropen2 , +.Nm fwopen , +.Nm fwopen2 +.Nd open a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fo funopen +.Fa "const void *cookie" +.Fa "int (*readfn)(void *, char *, int)" +.Fa "int (*writefn)(void *, const char *, int)" +.Fa "off_t (*seekfn)(void *, off_t, int)" +.Fa "int (*closefn)(void *)" +.Fc +.Ft FILE * +.Fo funopen2 +.Fa "const void *cookie" +.Fa "ssize_t (*readfn)(void *, void *, size_t)" +.Fa "ssize_t (*writefn)(void *, const void *, size_t)" +.Fa "off_t (*seekfn)(void *, off_t, int)" +.Fa "int (*flushfn)(void *)" +.Fa "int (*closefn)(void *)" +.Fc +.Ft FILE * +.Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)" +.Ft FILE * +.Fn fropen2 "void *cookie" "ssize_t (*readfn)(void *, void *, size_t)" +.Ft FILE * +.Fn fwopen "void *cookie" "int (*writefn)(void *, const char *, int)" +.Ft FILE * +.Fn fwopen2 "void *cookie" "ssize_t (*writefn)(void *, const void *, size_t)" +.Sh DESCRIPTION +The +.Fn funopen +function +associates a stream with up to four +.Dq Tn I/O No functions . +Either +.Fa readfn +or +.Fa writefn +must be specified; +the others can be given as an appropriately-typed +.Dv NULL +pointer. +These +.Tn I/O +functions will be used to read, write, seek and +close the new stream. +.Pp +The +.Fn funopen2 +function provides slightly different read and write signatures, which match +the corresponding system calls better, plus the ability to augment the +stream's default flushing function. +If a flushing function is provided, it is called after all data has +been written to the stream. +.Pp +In general, omitting a function means that any attempt to perform the +associated operation on the resulting stream will fail. +If the close function is omitted, closing the stream will flush +any buffered output and then succeed. +.Pp +The calling conventions of +.Fa readfn , +.Fa writefn , +.Fa seekfn +and +.Fa closefn +must match those, respectively, of +.Xr read 2 , +.Xr write 2 , +.Xr lseek 2 , +and +.Xr close 2 ; +except that they are passed the +.Fa cookie +argument specified to +.Fn funopen +in place of the traditional file descriptor argument. +.Pp +Read and write +.Tn I/O +functions are allowed to change the underlying buffer +on fully buffered or line buffered streams by calling +.Xr setvbuf 3 . +They are also not required to completely fill or empty the buffer. +They are not, however, allowed to change streams from unbuffered to buffered +or to change the state of the line buffering flag. +They must also be prepared to have read or write calls occur on buffers other +than the one most recently specified. +.Pp +All user +.Tn I/O +functions can report an error by returning \-1. +Additionally, all of the functions should set the external variable +.Va errno +appropriately if an error occurs. +.Pp +An error on +.Fa closefn +does not keep the stream open. +.Pp +As a convenience, the include file +.In stdio.h +defines the macros +.Fn fropen +and +.Fn fwopen +as calls to +.Fn funopen +with only a read or write function specified. +.Sh RETURN VALUES +Upon successful completion, +.Fn funopen +returns a +.Dv FILE +pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fn funopen +function +was called without either a read or write function. +The +.Fn funopen +function +may also fail and set +.Va errno +for any of the errors +specified for the routine +.Xr malloc 3 . +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr open 2 , +.Xr fclose 3 , +.Xr fmemopen 3 , +.Xr fopen 3 , +.Xr fseek 3 , +.Xr setbuf 3 +.Sh HISTORY +The +.Fn funopen +functions first appeared in +.Bx 4.4 . +The +.Fn funopen2 +functions first appeared in +.Nx 7.0 . +.Sh CAVEATS +All these functions are specific to +.Nx +and thus unportable. diff --git a/static/netbsd/man3/fwide.3 b/static/netbsd/man3/fwide.3 new file mode 100644 index 00000000..62bc368c --- /dev/null +++ b/static/netbsd/man3/fwide.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: fwide.3,v 1.6 2003/09/08 17:54:32 wiz Exp $ +.\" +.\" Copyright (c)2001 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Citrus: xpg4dl/FreeBSD/lib/libc/stdio/fwide.3,v 1.2 2001/12/07 04:47:08 yamt Exp $ +.\" +.Dd October 24, 2001 +.Dt FWIDE 3 +.Os +.Sh NAME +.Nm fwide +.Nd get/set orientation of a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft int +.Fn fwide "FILE *stream" "int mode" +.Sh DESCRIPTION +The +.Fn fwide +function +determines the orientation of the stream pointed at by +.Fa stream . +.Pp +If the orientation of +.Fa stream +has already been determined, +.Fn fwide +leaves it unchanged. +Otherwise, +.Fn fwide +sets the orientation of +.Fa stream +according to +.Fa mode . +.Pp +If +.Fa mode +is less than zero, +.Fa stream +is set to byte-oriented. +If it is greater than zero, +.Fa stream +is set to wide-oriented. +Otherwise, +.Fa mode +is zero, and +.Fa stream +is unchanged. +.Sh RETURN VALUES +.Fn fwide +returns a value according to orientation after the call of +.Fn fwide ; +a value less than zero if byte-oriented, a value greater than zero +if wide-oriented, and zero if the stream has no orientation. +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgetc 3 , +.Xr fgetwc 3 , +.Xr fopen 3 , +.Xr fputc 3 , +.Xr fputwc 3 , +.Xr freopen 3 , +.Xr stdio 3 +.Sh STANDARDS +The +.Fn fwide +function +conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/gai_strerror.3 b/static/netbsd/man3/gai_strerror.3 new file mode 100644 index 00000000..d3e90593 --- /dev/null +++ b/static/netbsd/man3/gai_strerror.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: gai_strerror.3,v 1.5 2010/03/22 19:30:54 joerg Exp $ +.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $ +.\" $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $ +.\" +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd February 22, 2006 +.Dt GAI_STRERROR 3 +.Os +.Sh NAME +.Nm gai_strerror +.Nd get error message string from EAI_xxx error code +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netdb.h +.Ft const char * +.Fn gai_strerror "int ecode" +.Sh DESCRIPTION +The +.Fn gai_strerror +function returns an error message string corresponding to the error code +returned by +.Xr getaddrinfo 3 +or +.Xr getnameinfo 3 . +.Pp +The following error codes and their meaning are defined in +.In netdb.h : +.Pp +.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact +.It Dv EAI_ADDRFAMILY +address family for +.Fa hostname +not supported +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for +.Fa ai_flags +.It Dv EAI_BADHINTS +invalid value for +.Fa hints +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +.Fa ai_family +not supported. +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with +.Fa hostname +.It Dv EAI_NONAME +.Fa hostname +or +.Fa servname +not provided, or not known +.It Dv EAI_OVERFLOW +argument buffer overflow +.It Dv EAI_PROTOCOL +resolved protocol is unknown +.It Dv EAI_SERVICE +.Fa servname +not supported for +.Fa ai_socktype +.It Dv EAI_SOCKTYPE +.Fa ai_socktype +not supported +.It Dv EAI_SYSTEM +system error returned in +.Va errno +.El +.Sh RETURN VALUES +.Fn gai_strerror +returns a pointer to the error message string corresponding to +.Fa ecode . +If +.Fa ecode +is out of range, an implementation-specific error message string is returned. +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 diff --git a/static/netbsd/man3/gelf.3 b/static/netbsd/man3/gelf.3 new file mode 100644 index 00000000..4bf90de3 --- /dev/null +++ b/static/netbsd/man3/gelf.3 @@ -0,0 +1,205 @@ +.\" $NetBSD: gelf.3,v 1.5 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf.3 3743 2019-06-12 19:36:30Z jkoshy +.\" +.Dd June 12, 2019 +.Dt GELF 3 +.Os +.Sh NAME +.Nm gelf +.Nd class-independent API for ELF manipulation +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Sh DESCRIPTION +This manual page describes a class independent API for manipulating +ELF objects. +This API allows an application to operate on ELF descriptors without +needing to the know the ELF class of the descriptor. +.Pp +The GElf API may be used alongside the ELF API without restriction. +.Ss GElf Data Structures +The GElf API defines the following class-independent data structures: +.Bl -tag -width GElf_Sxword +.It Vt GElf_Addr +A representation of ELF addresses. +.It Vt GElf_Dyn +A class-independent representation of ELF +.Sy .dynamic +section entries. +.It Vt GElf_Ehdr +A class-independent representation of an ELF Executable Header. +.It Vt GElf_Half +An unsigned 16 bit quantity. +.It Vt GElf_Off +A class-independent representation of a ELF offset. +.It Vt GElf_Phdr +A class-independent representation of an ELF Program Header Table +entry. +.It Vt GElf_Rel +A class-independent representation of an ELF relocation entry. +.It Vt GElf_Rela +A class-independent representation of an ELF relocation entry with +addend. +.It Vt GElf_Shdr +A class-independent representation of an ELF Section Header Table +entry. +.It Vt GElf_Sword +A signed 32 bit quantity. +.It Vt GElf_Sxword +A signed 64 bit quantity. +.It Vt GElf_Sym +A class-independent representation of an ELF symbol table entry. +.It Vt GElf_Word +An unsigned 32 bit quantity. +.It Vt GElf_Xword +An unsigned 64 bit quantity. +.El +.Pp +These data structures are sized to be compatible with the +corresponding 64 bit ELF structures, and have the same internal +structure as their 64 bit class-dependent counterparts. +Class-dependent ELF structures are described in +.Xr elf 5 . +.Ss GElf Programming Model +GElf functions always return a +.Em copy +of the underlying (class-dependent) ELF data structure. +The programming model with GElf is as follows: +.Bl -enum +.It +An application will retrieve data from an ELF descriptor using a +.Fn gelf_get_* +function. +This will copy out data into a private +.Vt GElf_* +data structure. +.It +The application will work with its private copy of the GElf +structure. +.It +Once done, the application copies the new values back to the +underlying ELF data structure using the +.Fn gelf_update_* +functions. +.It +The application will then use the +.Fn elf_flag* +APIs to indicate to the ELF library that an ELF data structure is dirty. +.El +.Pp +When updating an underlying 32 bit ELF data structure, the GElf +routines will signal an error if a GElf value is out of range +for the underlying ELF data type. +.Ss Namespace use +The GElf interface uses the following symbols: +.Bl -tag -width indent +.It GElf_* +Class-independent data types. +.It gelf_* +For functions defined in the API set. +.El +.Ss GElf Programming APIs +This section provides an overview of the GElf programming APIs. +Further information is provided in the manual page of each function +listed here. +.Bl -tag -width indent +.It "Allocating ELF Data Structures" +.Bl -tag -compact -width indent +.It Fn gelf_newehdr +Allocate a new ELF Executable Header. +.It Fn gelf_newphdr +Allocate a new ELF Program Header Table. +.El +.It "Data Translation" +.Bl -tag -compact -width indent +.It Fn gelf_xlatetof +Translate the native representation of an ELF data structure to its +file representation. +.It Fn gelf_xlatetom +Translate from the file representation of an ELF data structure to a +native representation. +.El +.It "Retrieving ELF Data" +.Bl -tag -compact -width indent +.It Fn gelf_getdyn +Retrieve an ELF +.Sy .dynamic +table entry. +.It Fn gelf_getehdr +Retrieve an ELF Executable Header from the underlying ELF descriptor. +.It Fn gelf_getphdr +Retrieve an ELF Program Header Table entry from the underlying ELF descriptor. +.It Fn gelf_getrel +Retrieve an ELF relocation entry. +.It Fn gelf_getrela +Retrieve an ELF relocation entry with addend. +.It Fn gelf_getshdr +Retrieve an ELF Section Header Table entry from the underlying ELF descriptor. +.It Fn gelf_getsym +Retrieve an ELF symbol table entry. +.El +.It Queries +.Bl -tag -compact -width indent +.It Fn gelf_checksum +Retrieves the ELF checksum for an ELF descriptor. +.It Fn gelf_fsize +Retrieves the size of the file representation of an ELF type. +.It Fn gelf_getclass +Retrieves the ELF class of an ELF descriptor. +.El +.It "Updating ELF Data" +.Bl -tag -compact -width ".Fn gelf_update_shdr" +.It Fn gelf_update_dyn +Copy back an ELF +.Sy .dynamic +Table entry. +.It Fn gelf_update_phdr +Copy back an ELF Program Header Table entry. +.It Fn gelf_update_rel +Copy back an ELF relocation entry. +.It Fn gelf_update_rela +Copy back an ELF relocation with addend entry. +.It Fn gelf_update_shdr +Copy back an ELF Section Header Table entry. +.It Fn gelf_update_sym +Copy back an ELF symbol table entry. +.El +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf 5 +.Sh HISTORY +The +.Nm +API first appeared in +.At V.4 . +This implementation of the API first appeared in +.Fx 7.0 . +.Sh AUTHORS +The GElf API was implemented by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . diff --git a/static/netbsd/man3/gelf_checksum.3 b/static/netbsd/man3/gelf_checksum.3 new file mode 100644 index 00000000..60d5d3cc --- /dev/null +++ b/static/netbsd/man3/gelf_checksum.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: gelf_checksum.3,v 1.6 2024/03/03 17:37:33 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_checksum.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd August 29, 2006 +.Dt GELF_CHECKSUM 3 +.Os +.Sh NAME +.Nm elf32_checksum , +.Nm elf64_checksum , +.Nm gelf_checksum +.Nd return the checksum of an ELF object +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft long +.Fn elf32_checksum "Elf *elf" +.Ft long +.Fn elf64_checksum "Elf *elf" +.In gelf.h +.Ft long +.Fn gelf_checksum "Elf *elf" +.Sh DESCRIPTION +These functions return a simple checksum of the ELF object described +by their argument +.Fa elf . +The checksum is computed in way that allows its value to remain +unchanged in presence of modifications to the ELF object by utilities +like +.Xr strip 1 . +.Pp +Function +.Fn elf32_checksum +returns a checksum for an ELF descriptor +.Fa elf +of class +.Dv ELFCLASS32 . +.Pp +Function +.Fn elf64_checksum +returns a checksum for an ELF descriptor +.Fa elf +of class +.Dv ELFCLASS64 . +.Pp +Function +.Fn gelf_checksum +provides a class-independent way retrieving the checksum +for ELF object +.Fa elf . +.Sh RETURN VALUES +These functions return the checksum of the ELF object, or zero in case +an error was encountered. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +The ELF descriptor +.Fa elf +was not opened for reading or updating. +.It Bq Er ELF_E_CLASS +For functions +.Fn elf32_checksum +and +.Fn elf64_checksum , +ELF descriptor +.Fa elf +did not match the class of the called function. +.It Bq Er ELF_E_HEADER +The ELF object specified by argument +.Fa elf +had a malformed executable header. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected during processing. +.It Bq Er ELF_E_SECTION +The ELF object specified by argument +.Fa elf +contained a section with a malformed section header. +.It Bq Er ELF_E_VERSION +The ELF object was of an unsupported version. +.El +.Sh SEE ALSO +.Xr strip 1 , +.Xr elf 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_fsize.3 b/static/netbsd/man3/gelf_fsize.3 new file mode 100644 index 00000000..46a2bf81 --- /dev/null +++ b/static/netbsd/man3/gelf_fsize.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: gelf_fsize.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_fsize.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd February 5, 2008 +.Dt GELF_FSIZE 3 +.Os +.Sh NAME +.Nm gelf_fsize , +.Nm elf32_fsize , +.Nm elf64_fsize +.Nd return the size of a file type +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft size_t +.Fn elf32_fsize "Elf_Type type" "size_t count" "unsigned int version" +.Ft size_t +.Fn elf64_fsize "Elf_Type type" "size_t count" "unsigned int version" +.In gelf.h +.Ft size_t +.Fn gelf_fsize "Elf *elf" "Elf_Type type" "size_t count" "unsigned int version" +.Sh DESCRIPTION +These functions return the size in bytes of the file representation of +.Fa count +numbers of objects of ELF type +.Fa type . +For ELF types that are of variable length, these functions return a +size of one byte. +.Pp +Functions +.Fn elf32_fsize +and +.Fn elf64_fsize +return sizes for files of class +.Dv ELFCLASS32 +and +.Dv ELFCLASS64 +respectively. +Function +.Fn gelf_fsize +returns the size for the class of ELF descriptor +.Fa elf . +.Sh RETURN VALUES +These functions return a non-zero value in case of success, or zero in +case of an error. +.Sh ERRORS +These functions may fail with: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL +in a call to +.Fn gelf_fsize . +.It Bq Er ELF_E_ARGUMENT +ELF descriptor +.Fa elf +had an unknown ELF class. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa type +contained an illegal value. +.It Bq Er ELF_E_UNIMPL +Support for ELF type +.Fa type +has not been implemented. +.It Bq Er ELF_E_VERSION +Argument +.Fa version +is not a supported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getcap.3 b/static/netbsd/man3/gelf_getcap.3 new file mode 100644 index 00000000..f3974118 --- /dev/null +++ b/static/netbsd/man3/gelf_getcap.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: gelf_getcap.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getcap.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETCAP 3 +.Os +.Sh NAME +.Nm gelf_getcap , +.Nm gelf_update_cap +.Nd read and update ELF capability information +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Cap *" +.Fn gelf_getcap "Elf_Data *data" "int ndx" "GElf_Cap *cap" +.Ft int +.Fn gelf_update_cap "Elf_Data *data" "int ndx" "GElf_Cap *cap" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Cap +or +.Vt Elf64_Cap +information. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_cap . +Argument +.Fa ndx +is the index of the entry being retrieved or updated. +The class-independent +.Vt GElf_Cap +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getcap +retrieves the class-dependent entry at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa cap +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_cap +converts the class-independent entry pointed to +by argument +.Fa cap +to class-dependent form, and writes it to the entry at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_cap +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getcap +returns the value of argument +.Fa cap +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_cap +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa cap +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section of type +.Dv SHT_SUNW_cap . +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getclass.3 b/static/netbsd/man3/gelf_getclass.3 new file mode 100644 index 00000000..1c6dd137 --- /dev/null +++ b/static/netbsd/man3/gelf_getclass.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: gelf_getclass.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getclass.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd July 3, 2006 +.Dt GELF_GETCLASS 3 +.Os +.Sh NAME +.Nm gelf_getclass +.Nd retrieve the class of an ELF descriptor +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft int +.Fn gelf_getclass "Elf *elf" +.Sh DESCRIPTION +Function +.Fn gelf_getclass +returns the ELF class of the descriptor supplied in argument +.Fa elf . +.Sh RETURN VALUES +Function +.Fn gelf_getclass +will return one of +.Dv ELFCLASS32 +or +.Dv ELFCLASS64 +if the argument +.Fa elf +is a descriptor for an ELF file. +The value +.Dv ELFCLASSNONE +is returned if argument +.Fa elf +was null, or if it was not a descriptor for an ELF file. +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_kind 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getdyn.3 b/static/netbsd/man3/gelf_getdyn.3 new file mode 100644 index 00000000..1d376379 --- /dev/null +++ b/static/netbsd/man3/gelf_getdyn.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: gelf_getdyn.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getdyn.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETDYN 3 +.Os +.Sh NAME +.Nm gelf_getdyn , +.Nm gelf_update_dyn +.Nd read and update ELF dynamic entries +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Dyn *" +.Fn gelf_getdyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn" +.Ft int +.Fn gelf_update_dyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Dyn +or +.Vt Elf64_Dyn +information in the +.Sy dynamic +table of an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_DYNAMIC . +Argument +.Fa ndx +is the index of the entry being retrieved or updated. +The class-independent +.Vt GElf_Dyn +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getdyn +retrieves the class-dependent entry at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa dyn +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_dyn +converts the class-independent entry pointed to +by argument +.Fa dyn +to class-dependent form, and writes it to the entry at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_dyn +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getdyn +returns the value of argument +.Fa dyn +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_dyn +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa dyn +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section of type +.Dv SHT_DYNAMIC . +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getehdr.3 b/static/netbsd/man3/gelf_getehdr.3 new file mode 100644 index 00000000..67f4189e --- /dev/null +++ b/static/netbsd/man3/gelf_getehdr.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: gelf_getehdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getehdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd December 16, 2006 +.Dt GELF_GETEHDR 3 +.Os +.Sh NAME +.Nm elf32_getehdr , +.Nm elf64_getehdr , +.Nm gelf_getehdr +.Nd retrieve the object file header +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf32_Ehdr *" +.Fn elf32_getehdr "Elf *elf" +.Ft "Elf64_Ehdr *" +.Fn elf64_getehdr "Elf *elf" +.In gelf.h +.Ft "GElf_Ehdr *" +.Fn gelf_getehdr "Elf *elf" "GElf_Ehdr *dst" +.Sh DESCRIPTION +These functions retrieve the ELF object file +header from the ELF descriptor +.Fa elf +and return a translated header descriptor to their callers. +.Pp +Functions +.Fn elf32_getehdr +and +.Fn elf64_getehdr +return a pointer to the appropriate class-specific header descriptor +if it exists in the file referenced by descriptor +.Fa elf . +These functions return +.Dv NULL +if an ELF header was not found in file +.Fa elf . +.Pp +Function +.Fn gelf_getehdr +stores a translated copy of the header for ELF file +.Fa elf +into the descriptor pointed to by argument +.Fa dst . +It returns argument +.Fa dst +if successful or +.Dv NULL +in case of failure. +.Sh RETURN VALUES +These functions return a pointer to a translated header descriptor +if successful, or +.Dv NULL +on failure. +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF file. +.It Bq Er ELF_E_ARGUMENT +The elf class of descriptor +.Fa elf +was not recognized. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa dst +was null. +.It Bq Er ELF_E_CLASS +The ELF class of descriptor +.Fa elf +did not match that of the API function being called. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Fa elf +does not have an associated header. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected during execution. +.It Bq Er ELF_E_SECTION +The ELF descriptor in argument +.Fa elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_E_VERSION +The ELF descriptor +.Fa elf +had an unsupported ELF version number. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_newehdr 3 , +.Xr elf64_newehdr 3 , +.Xr elf_flagehdr 3 , +.Xr elf_getident 3 , +.Xr gelf 3 , +.Xr gelf_newehdr 3 , +.Xr elf 5 diff --git a/static/netbsd/man3/gelf_getmove.3 b/static/netbsd/man3/gelf_getmove.3 new file mode 100644 index 00000000..7f528c76 --- /dev/null +++ b/static/netbsd/man3/gelf_getmove.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: gelf_getmove.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getmove.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETMOVE 3 +.Os +.Sh NAME +.Nm gelf_getmove , +.Nm gelf_update_move +.Nd read and update Elf Move information +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Move *" +.Fn gelf_getmove "Elf_Data *data" "int ndx" "GElf_Move *move" +.Ft int +.Fn gelf_update_move "Elf_Data *data" "int ndx" "GElf_Move *move" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Move +and +.Vt Elf64_Move +structures in an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_move . +Argument +.Fa ndx +is the index of the move record being retrieved or updated. +The class-independent +.Vt GElf_Move +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getmove +retrieves class-dependent move record at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa move +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_move +converts the class-independent move information pointed to +by argument +.Fa move +to class-dependent form, and writes it to the move record at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_move +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getmove +returns the value of argument +.Fa move +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_move +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa move +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of records in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section containing move information. +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getphdr.3 b/static/netbsd/man3/gelf_getphdr.3 new file mode 100644 index 00000000..e457a045 --- /dev/null +++ b/static/netbsd/man3/gelf_getphdr.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: gelf_getphdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006-2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getphdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd October 21, 2007 +.Dt GELF_GETPHDR 3 +.Os +.Sh NAME +.Nm elf32_getphdr , +.Nm elf64_getphdr , +.Nm gelf_getphdr +.Nd retrieve an ELF program header table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf32_Phdr *" +.Fn elf32_getphdr "Elf *elf" +.Ft "Elf64_Phdr *" +.Fn elf64_getphdr "Elf *elf" +.In gelf.h +.Ft "GElf_Phdr *" +.Fn gelf_getphdr "Elf *elf" "int index" "GElf_Phdr *dst" +.Sh DESCRIPTION +These functions retrieve and translate ELF program header information +from an ELF descriptor, if this information exists. +.Pp +Functions +.Fn elf32_getphdr +and +.Fn elf64_getphdr +return a pointer to an array of translated +.Vt Elf32_Phdr +and +.Vt Elf64_Phdr +descriptors respectively. +These descriptors are described in +.Xr elf 5 . +The number of entries in this array may be determined using the +.Xr elf_getphnum 3 +function. +.Pp +Function +.Fn gelf_getphdr +will retrieve the program header table entry at index +.Fa index +from ELF descriptor +.Fa elf . +The translated program header table entry will be written to the +address pointed to be argument +.Fa dst . +.Pp +Applications may inform the library of modifications to a program header table entry +by using the +.Xr elf_flagphdr 3 +API. +Applications using the +.Xr gelf 3 +interface need to use the +.Xr gelf_update_phdr 3 +API to copy modifications to a program header entry back to the underlying +ELF descriptor. +.Sh RETURN VALUES +The functions a valid pointer if successful, or +.Dv NULL +in case an error was encountered. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa dst +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Index +.Fa index +was out of range. +.It Bq Er ELF_E_CLASS +The class of ELF descriptor +.Fa elf +did not match the expected class of the function being called. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Fa elf +did not possess an executable header. +.It Bq Er ELF_E_HEADER +ELF descriptor +.Fa elf +had a corrupt executable header. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.It Bq Er ELF_E_SECTION +The ELF descriptor in argument +.Fa elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_VERSION +ELF descriptor +.Fa elf +was of an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf32_newphdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf64_newphdr 3 , +.Xr elf_flagphdr 3 , +.Xr elf_getphnum 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 , +.Xr gelf_newphdr 3 , +.Xr gelf_update_phdr 3 , +.Xr elf 5 diff --git a/static/netbsd/man3/gelf_getrel.3 b/static/netbsd/man3/gelf_getrel.3 new file mode 100644 index 00000000..6103b467 --- /dev/null +++ b/static/netbsd/man3/gelf_getrel.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: gelf_getrel.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getrel.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETREL 3 +.Os +.Sh NAME +.Nm gelf_getrel , +.Nm gelf_update_rel +.Nd read and update ELF relocation entries +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Rel *" +.Fn gelf_getrel "Elf_Data *data" "int ndx" "GElf_Rel *rel" +.Ft int +.Fn gelf_update_rel "Elf_Data *data" "int ndx" "GElf_Rel *rel" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Rel +or +.Vt Elf64_Rel +structures in an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_REL . +Argument +.Fa ndx +is the index of the entry being retrieved or updated. +The class-independent +.Vt GElf_Rel +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getrel +retrieves the class-dependent entry at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa rel +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_rel +converts the class-independent entry pointed to +by argument +.Fa rel +to class-dependent form, and writes it to the entry at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_rel +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getrel +returns the value of argument +.Fa rel +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_rel +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa rel +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section of type +.Dv SHT_REL . +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getrela.3 b/static/netbsd/man3/gelf_getrela.3 new file mode 100644 index 00000000..af9f903f --- /dev/null +++ b/static/netbsd/man3/gelf_getrela.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: gelf_getrela.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getrela.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETRELA 3 +.Os +.Sh NAME +.Nm gelf_getrela , +.Nm gelf_update_rela +.Nd read and update ELF relocation entries with addends +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Rela *" +.Fn gelf_getrela "Elf_Data *data" "int ndx" "GElf_Rela *rela" +.Ft int +.Fn gelf_update_rela "Elf_Data *data" "int ndx" "GElf_Rela *rela" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Rela +or +.Vt Elf64_Rela +structures in an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_RELA . +Argument +.Fa ndx +is the index of the entry being retrieved or updated. +The class-independent +.Vt GElf_Rela +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getrela +retrieves the class-dependent entry at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa rela +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_rela +converts the class-independent entry pointed to +by argument +.Fa rela +to class-dependent form, and writes it to the entry at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_rela +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getrela +returns the value of argument +.Fa rela +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_rela +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa rela +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of entries in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section of type +.Dv SHT_RELA . +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/gelf_getshdr.3 b/static/netbsd/man3/gelf_getshdr.3 new file mode 100644 index 00000000..c8e327e1 --- /dev/null +++ b/static/netbsd/man3/gelf_getshdr.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: gelf_getshdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getshdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd August 27, 2006 +.Dt GELF_GETSHDR 3 +.Os +.Sh NAME +.Nm elf32_getshdr , +.Nm elf64_getshdr , +.Nm gelf_getshdr +.Nd retrieve the class-dependent section header +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf32_Shdr *" +.Fn elf32_getshdr "Elf_Scn *scn" +.Ft "Elf64_Shdr *" +.Fn elf64_getshdr "Elf_Scn *scn" +.In gelf.h +.Ft "GElf_Shdr *" +.Fn gelf_getshdr "Elf_Scn *scn" "GElf_Shdr *shdr" +.Sh DESCRIPTION +These functions return a pointer to the ELF Section Header data +structure associated with section descriptor +.Fa scn . +.Pp +Function +.Fn elf32_getshdr +retrieves a pointer to an +.Vt Elf32_Shdr +structure. +Section descriptor +.Fa scn +must be associated with an ELF descriptor of class +.Dv ELFCLASS32 . +.Pp +Function +.Fn elf64_getshdr +retrieves a pointer to an +.Vt Elf64_Shdr +structure. +Section descriptor +.Fa scn +must be associated with an ELF descriptor of class +.Dv ELFCLASS64 . +.Pp +Function +.Fn gelf_getshdr +copies the values in the section header associated with argument +.Fa scn +to the structure pointed to be argument +.Fa dst . +The +.Vt GElf_Shdr +data structure is described in +.Xr gelf 3 . +.Sh RETURN VALUES +Functions +.Fn elf32_getshdr +and +.Fn elf64_getshdr +return a valid pointer to the appropriate section header on success +or +.Dv NULL +if an error was encountered. +.Pp +Function +.Fn gelf_getshdr +returns argument +.Fa dst +if successful, or +.Dv NULL +if an error was encountered. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa scn +or +.Fa shdr +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa scn +was not associated a descriptor for an ELF object. +.It Bq Er ELF_E_CLASS +The ELF class associated with the section descriptor +.Fa scn +did not match the class expected by the API. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 , +.Xr gelf_update_shdr 3 diff --git a/static/netbsd/man3/gelf_getsym.3 b/static/netbsd/man3/gelf_getsym.3 new file mode 100644 index 00000000..bbd1a18a --- /dev/null +++ b/static/netbsd/man3/gelf_getsym.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: gelf_getsym.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getsym.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETSYM 3 +.Os +.Sh NAME +.Nm gelf_getsym , +.Nm gelf_update_sym +.Nd read and update symbol information +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Sym *" +.Fn gelf_getsym "Elf_Data *data" "int ndx" "GElf_Sym *sym" +.Ft int +.Fn gelf_update_sym "Elf_Data *data" "int ndx" "GElf_Sym *sym" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Sym +and +.Vt Elf64_Sym +structures in an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SYMTAB , +.Dv SHT_DYNSYM +or +.Dv SHT_GNU_versym . +Argument +.Fa ndx +is the index of the symbol being retrieved or updated. +The class-independent +.Vt GElf_Sym +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getsym +retrieves class-dependent symbol information at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa sym +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_sym +converts the class-independent symbol information pointed to +by argument +.Fa sym +to class-dependent form, and writes it to the symbol entry at index +.Fa ndx +in the data buffer described by argument +.Fa data . +Function +.Fn gelf_update_sym +signals an error if any of the values in the class-independent +representation exceeds the representable limits of the target +type. +.Sh RETURN VALUES +Function +.Fn gelf_getsym +returns the value of argument +.Fa sym +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_sym +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa sym +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of symbols in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section containing symbol information. +.It Bq Er ELF_E_RANGE +A value was not representable in the target type. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 , +.Xr gelf_getsyminfo 3 , +.Xr gelf_update_syminfo 3 diff --git a/static/netbsd/man3/gelf_getsyminfo.3 b/static/netbsd/man3/gelf_getsyminfo.3 new file mode 100644 index 00000000..9daeb3c0 --- /dev/null +++ b/static/netbsd/man3/gelf_getsyminfo.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: gelf_getsyminfo.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getsyminfo.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd April 22, 2019 +.Dt GELF_GETSYMINFO 3 +.Os +.Sh NAME +.Nm gelf_getsyminfo , +.Nm gelf_update_syminfo +.Nd read and update symbol information +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Syminfo *" +.Fn gelf_getsyminfo "Elf_Data *data" "int ndx" "GElf_Syminfo *syminfo" +.Ft int +.Fn gelf_update_syminfo "Elf_Data *data" "int ndx" "GElf_Syminfo *syminfo" +.Sh DESCRIPTION +These convenience functions are used to retrieve and update class-dependent +.Vt Elf32_Syminfo +and +.Vt Elf64_Syminfo +records in an ELF object. +.Pp +Argument +.Fa data +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SUNW_syminfo . +Argument +.Fa ndx +is the index of the record being retrieved or updated. +The class-independent +.Vt GElf_Syminfo +structure is described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getsyminfo +retrieves class-dependent record at index +.Fa ndx +in data buffer +.Fa data +and copies it to the destination pointed to by argument +.Fa syminfo +after translation to class-independent form. +.Pp +Function +.Fn gelf_update_syminfo +converts the class-independent record pointed to +by argument +.Fa syminfo +to class-dependent form, and writes it to the record at index +.Fa ndx +in the data buffer described by argument +.Fa data . +.Sh RETURN VALUES +Function +.Fn gelf_getsyminfo +returns the value of argument +.Fa syminfo +if successful, or +.Dv NULL +in case of an error. +Function +.Fn gelf_update_syminfo +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa data +or +.Fa syminfo +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero or larger than the number of symbols in the data +descriptor. +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa data +was not associated with a section containing symbol information. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptor denoted by argument +.Fa data +is associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 , +.Xr gelf_getsym 3 , +.Xr gelf_update_sym 3 diff --git a/static/netbsd/man3/gelf_getsymshndx.3 b/static/netbsd/man3/gelf_getsymshndx.3 new file mode 100644 index 00000000..d79855ce --- /dev/null +++ b/static/netbsd/man3/gelf_getsymshndx.3 @@ -0,0 +1,194 @@ +.\" $NetBSD: gelf_getsymshndx.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008,2020 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_getsymshndx.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd September 26, 2020 +.Dt GELF_GETSYMSHNDX 3 +.Os +.Sh NAME +.Nm gelf_getsymshndx , +.Nm gelf_update_symshndx +.Nd read and update symbol information using extended section indices +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft "GElf_Sym *" +.Fo gelf_getsymshndx +.Fa "Elf_Data *symdata" +.Fa "Elf_Data *xndxdata" +.Fa "int ndx" +.Fa "GElf_Sym *sym" +.Fa "Elf32_Word *xndxptr" +.Fc +.Ft int +.Fo gelf_update_symshndx +.Fa "Elf_Data *symdata" +.Fa "Elf_Data *xndxdata" +.Fa "int ndx" +.Fa "GElf_Sym *sym" +.Fa "Elf32_Word xndx" +.Fc +.Sh DESCRIPTION +These functions are analogous to +.Fn gelf_getsym +and +.Fn gelf_update_sym +respectively, but are capable of handling symbol tables using extended +section numbering. +.Pp +Argument +.Fa symdata +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SYMTAB . +Argument +.Fa xndxdata +is an +.Vt Elf_Data +descriptor associated with a section of type +.Dv SHT_SYMTAB_SHNDX . +Argument +.Fa ndx +is the index of the symbol table entry being retrieved or updated. +Argument +.Fa sym +is a pointer to a class-independent +.Vt GElf_Sym +structure. +.Vt GElf_Sym +structures are described in detail in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_getsymshndx +retrieves symbol information at index +.Fa ndx +from the data descriptor specified by argument +.Fa symdata +and stores it in class-independent form in argument +.Fa sym . +Additionally: +.Bl -bullet +.It +If the arguments +.Ad xndxdata +and +.Fa xndxptr +are both not +.Dv NULL , +it retrieves the extended section index for the +symbol from the data buffer pointed to by the +argument +.Fa xndxdata +and stores it into the location pointed to by argument +.Fa xndxptr . +.It +Otherwise, if the argument +.Fa xndxptr +is not +.Dv NULL , +a value of zero is stored into the location pointed to by +argument +.Fa xndxptr . +.El +.Pp +Function +.Fn gelf_update_symshndx +updates the underlying symbol table entry in the data +descriptor +.Fa symdata +with the information in argument +.Fa sym . +In addition it sets the extended section index in +data buffer +.Fa xndxdata +to the value of argument +.Fa xndx . +.Sh RETURN VALUES +Function +.Fn gelf_getsymshndx +returns the value of argument +.Fa sym +if successful, or +.Dv NULL +in case of an error. +.Pp +Function +.Fn gelf_update_symshndx +returns a non-zero value if successful, or zero in case of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa symdata , +.Fa xndxdata , +.Fa xndxptr +or +.Fa sym +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +was less than zero, or too large for either of descriptors +.Fa symdata +or +.Fa xndxdata . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa symdata +was not associated with a section of type +.Dv SHT_SYMTAB . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa xndxdata +was not associated with a section of type +.Dv SHT_SYMTAB_SHNDX . +.It Bq Er ELF_E_ARGUMENT +Data descriptor +.Fa symdata +and +.Fa xndxdata +were associated with different ELF objects. +.It Bq Er ELF_E_VERSION +The +.Vt Elf_Data +descriptors denoted by arguments +.Fa symdata +and +.Fa xndxdata +are associated with an ELF object with an unsupported version. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr elf_getscn 3 , +.Xr gelf 3 , +.Xr gelf_getsym 3 , +.Xr gelf_update_sym 3 diff --git a/static/netbsd/man3/gelf_newehdr.3 b/static/netbsd/man3/gelf_newehdr.3 new file mode 100644 index 00000000..817466c2 --- /dev/null +++ b/static/netbsd/man3/gelf_newehdr.3 @@ -0,0 +1,201 @@ +.\" $NetBSD: gelf_newehdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006-2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_newehdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd June 12, 2019 +.Dt GELF_NEWEHDR 3 +.Os +.Sh NAME +.Nm elf32_newehdr , +.Nm elf64_newehdr , +.Nm gelf_newehdr +.Nd retrieve or allocate the object file header +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf32_Ehdr *" +.Fn elf32_newehdr "Elf *elf" +.Ft "Elf64_Ehdr *" +.Fn elf64_newehdr "Elf *elf" +.In gelf.h +.Ft "void *" +.Fn gelf_newehdr "Elf *elf" "int elfclass" +.Sh DESCRIPTION +These functions retrieve the ELF header from the ELF descriptor +.Fa elf , +allocating a new header if needed. +File data structures are translated to their in-memory representations +as described in +.Xr elf 3 . +.Pp +Function +.Fn elf32_newehdr +returns a pointer to a 32 bit +.Vt Elf32_Ehdr +structure. +Function +.Fn elf64_newehdr +returns a pointer to a 64 bit +.Vt Elf64_Ehdr +structure. +.Pp +When argument +.Fa elfclass +has value +.Dv ELFCLASS32 , +function +.Fn gelf_newehdr +returns the value returned by +.Fn elf32_newehdr "elf" . +When argument +.Fa elfclass +has value +.Dv ELFCLASS64 +it returns the value returned by +.Fn elf64_newehdr "elf" . +.Pp +If a fresh header structure is allocated, the members of the +structure are initialized as follows: +.Bl -tag -width indent +.It Va "e_ident[EI_MAG0..EI_MAG3]" +Identification bytes at offsets +.Dv EI_MAG0 , +.Dv EI_MAG1 , +.Dv EI_MAG2 +and +.Dv EI_MAG3 +are set to the ELF signature. +.It Va "e_ident[EI_CLASS]" +The identification byte at offset +.Dv EI_CLASS +is set to the ELF class associated with the function being called +or to argument +.Fa elfclass +for function +.Fn gelf_newehdr . +.It Va "e_ident[EI_DATA]" +The identification byte at offset +.Dv EI_DATA +is set to +.Dv ELFDATANONE . +.It Va "e_ident[EI_VERSION]" +The identification byte at offset +.Dv EI_VERSION +is set to the ELF library's operating version set by a prior call to +.Xr elf_version 3 . +.It Va e_machine +is set to +.Dv EM_NONE . +.It Va e_type +is set to +.Dv ELF_K_NONE . +.It Va e_version +is set to the ELF library's operating version set by a prior call to +.Xr elf_version 3 . +.El +.Pp +Other members of the header are set to zero. +The application is responsible for changing these values +as needed before calling +.Fn elf_update . +.Pp +If successful, these three functions set the +.Dv ELF_F_DIRTY +flag on ELF descriptor +.Fa elf . +.Sh RETURN VALUES +These functions return a pointer to a translated header descriptor +if successful, or +.Dv NULL +on failure. +.Sh COMPATIBILITY +The +.Fn gelf_newehdr +function uses a type of +.Ft "void *" +for its returned value. +This differs from some other implementations of the +.Xr elf 3 +API, which use an +.Ft "unsigned long" +return type. +.Sh ERRORS +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +The argument +.Fa elf +was null. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elfclass +had an unsupported value. +.It Bq Er ELF_E_ARGUMENT +The class of the ELF descriptor +.Fa elf +did not match that of the requested operation. +.It Bq Er ELF_E_ARGUMENT +For function +.Fn gelf_newehdr , +the class of argument +.Fa elf +was not +.Dv ELFCLASSNONE +and did not match the argument +.Fa elfclass . +.It Bq Er ELF_E_CLASS +The ELF class of descriptor +.Fa elf +did not match that of the API function being called. +.It Bq Er ELF_E_HEADER +A malformed ELF header was detected. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected during execution. +.It Bq Er ELF_E_SECTION +The ELF descriptor in argument +.Fa elf +did not adhere to the conventions used for extended numbering. +.It Bq Er ELF_E_VERSION +The ELF descriptor +.Fa elf +had an unsupported ELF version number. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_flagdata 3 , +.Xr elf_getident 3 , +.Xr elf_update 3 , +.Xr elf_version 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 , +.Xr elf 5 diff --git a/static/netbsd/man3/gelf_newphdr.3 b/static/netbsd/man3/gelf_newphdr.3 new file mode 100644 index 00000000..a621a6a5 --- /dev/null +++ b/static/netbsd/man3/gelf_newphdr.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: gelf_newphdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006-2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_newphdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd June 12, 2019 +.Dt GELF_NEWPHDR 3 +.Os +.Sh NAME +.Nm elf32_newphdr , +.Nm elf64_newphdr , +.Nm gelf_newphdr +.Nd allocate an ELF program header table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf32_Phdr *" +.Fn elf32_newphdr "Elf *elf" "size_t count" +.Ft "Elf64_Phdr *" +.Fn elf64_newphdr "Elf *elf" "size_t count" +.In gelf.h +.Ft "void *" +.Fn gelf_newphdr "Elf *elf" "size_t count" +.Sh DESCRIPTION +These functions allocate an ELF Program Header table +for an ELF descriptor. +.Vt Elf32_Phdr +and +.Vt Elf64_Phdr +descriptors are described further in +.Xr elf 5 . +.Pp +Functions +.Fn elf32_newphdr +and +.Fn elf64_newphdr +allocate a table of +.Fa count +.Vt Elf32_Phdr +and +.Vt Elf64_Phdr +descriptors respectively, +discarding any existing program header table +already present in the ELF descriptor +.Fa elf . +A value of zero for argument +.Fa count +may be used to delete an existing program header table +from an ELF descriptor. +.Pp +Function +.Fn gelf_newphdr +will return a table of +.Vt Elf32_Phdr +or +.Vt Elf64_Phdr +with +.Fa count +elements depending on the ELF class of ELF descriptor +.Fa elf . +.Pp +The functions set the +.Dv ELF_F_DIRTY +flag on the program header table. +All members of the returned array of Phdr structures +will be initialized to zero. +.Pp +After a successful call to these functions, the pointer returned +by a prior call to +.Fn elf32_getphdr +or +.Fn elf64_getphdr +on the same descriptor +.Fa elf +will no longer be valid. +.Sh RETURN VALUES +The functions a valid pointer if successful, or +.Dv NULL +in case an error was encountered. +.Sh COMPATIBILITY +The +.Fn gelf_newphdr +function uses a type of +.Ft "void *" +for its returned value. +This differs from some other implementations of the +.Xr elf 3 +API, which use an +.Ft "unsigned long" +return type. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_CLASS +ELF descriptor +.Fa elf +was of an unrecognized class. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.It Bq Er ELF_E_SEQUENCE +An executable header was not allocated for ELF descriptor +.Fa elf +before using these APIs. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getphdr 3 , +.Xr elf32_newehdr 3 , +.Xr elf64_getphdr 3 , +.Xr elf64_newehdr 3 , +.Xr elf_flagphdr 3 , +.Xr elf_getphnum 3 , +.Xr gelf 3 , +.Xr gelf_getphdr 3 , +.Xr gelf_newehdr 3 , +.Xr elf 5 diff --git a/static/netbsd/man3/gelf_update_ehdr.3 b/static/netbsd/man3/gelf_update_ehdr.3 new file mode 100644 index 00000000..b94c5372 --- /dev/null +++ b/static/netbsd/man3/gelf_update_ehdr.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: gelf_update_ehdr.3,v 1.6 2024/03/03 17:37:34 christos Exp $ +.\" +.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_update_ehdr.3 3958 2022-03-12 14:31:32Z jkoshy +.\" +.Dd August 27, 2006 +.Dt GELF_UPDATE_EHDR 3 +.Os +.Sh NAME +.Nm gelf_update_ehdr , +.Nm gelf_update_phdr , +.Nm gelf_update_shdr +.Nd update underlying ELF data structures +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In gelf.h +.Ft int +.Fn gelf_update_ehdr "Elf *elf" "GElf_Ehdr *ehdr" +.Ft int +.Fn gelf_update_phdr "Elf *elf" "int ndx" "GElf_Phdr *phdr" +.Ft int +.Fn gelf_update_shdr "Elf_Scn *scn" "GElf_Shdr *shdr" +.Sh DESCRIPTION +These functions are used to update ELF data structures on the underlying +ELF descriptor. +Class-dependent data structures in the underlying ELF descriptor +are updated using the data in the class-independent GElf descriptors +and the underlying ELF data structures are marked +.Dq dirty . +The conversion process signals an error if the values being copied +to the target ELF data structure would exceed representation +limits. +GElf descriptors are described in +.Xr gelf 3 . +.Pp +Function +.Fn gelf_update_ehdr +updates the ELF Executable Header with the values in the +class-independent executable header +.Fa ehdr . +.Pp +Function +.Fn gelf_update_phdr +updates the ELF Program Header structure at index +.Fa ndx +with the values in the class-independent program header +.Fa phdr . +.Pp +Function +.Fn gelf_update_shdr +updates the ELF Section Header structure associated with section +descriptor +.Fa scn +with the values in argument +.Fa shdr . +.Sh RETURN VALUES +These functions return a non-zero integer on success, or zero in case +of an error. +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa elf , +.Fa ehdr , +.Fa phdr , +.Fa scn , +or +.Fa shdr +were +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +was not a descriptor for an ELF object. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa elf +had an unsupported ELF class. +.It Bq Er ELF_E_ARGUMENT +Argument +.Fa ndx +exceeded the number of entries in the program header table. +.It Bq Er ELF_E_ARGUMENT +Section descriptor +.Fa scn +was not associated with an ELF descriptor. +.It Bq Er ELF_E_MODE +ELF descriptor +.Fa elf +was not opened for writing or updating. +.It Bq Er ELF_E_RESOURCE +An out of memory condition was detected. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_flagelf 3 , +.Xr elf_flagphdr 3 , +.Xr elf_flagshdr 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 , +.Xr gelf_getphdr 3 , +.Xr gelf_getshdr 3 diff --git a/static/netbsd/man3/gelf_xlatetof.3 b/static/netbsd/man3/gelf_xlatetof.3 new file mode 100644 index 00000000..cf401b92 --- /dev/null +++ b/static/netbsd/man3/gelf_xlatetof.3 @@ -0,0 +1,285 @@ +.\" $NetBSD: gelf_xlatetof.3,v 1.7 2025/07/17 11:18:27 jkoshy Exp $ +.\" +.\" Copyright (c) 2006,2008,2018 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" Id: gelf_xlatetof.3 4192 2025-07-15 16:39:34Z jkoshy +.\" +.Dd July 15, 2025 +.Dt GELF_XLATETOF 3 +.Os +.Sh NAME +.Nm elf32_xlatetof , +.Nm elf32_xlatetom , +.Nm elf64_xlatetof , +.Nm elf64_xlatetom , +.Nm gelf_xlatetof , +.Nm gelf_xlatetom +.Nd translate data between files and memory +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft "Elf_Data *" +.Fn elf32_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" +.Ft "Elf_Data *" +.Fn elf32_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" +.Ft "Elf_Data *" +.Fn elf64_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" +.Ft "Elf_Data *" +.Fn elf64_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" +.In gelf.h +.Ft "Elf_Data *" +.Fo gelf_xlatetof +.Fa "Elf *elf" +.Fa "Elf_Data *dst" +.Fa "Elf_Data *src" +.Fa "unsigned int file_encoding" +.Fc +.Ft "Elf_Data *" +.Fo gelf_xlatetom +.Fa "Elf *elf" +.Fa "Elf_Data *dst" +.Fa "Elf_Data *src" +.Fa "unsigned int file_encoding" +.Fc +.Sh DESCRIPTION +These functions translate between the file and memory representations +of ELF data structures. +The in-memory representation of an ELF data structure would conform to +the byte ordering and data alignment restrictions dictated by the host +processor. +As described in +.Xr elf 3 , +the file representation of this data structure could use a different byte +ordering from that of the host, or could use a different layout within +the file. +.Pp +Functions +.Fn elf32_xlatetom , +.Fn elf64_xlatetom , +and +.Fn gelf_xlatetom +translate data from file representations to native, in-memory representations. +Functions +.Fn elf32_xlatetof , +.Fn elf64_xlatetof , +and +.Fn gelf_xlatetof +translate data from in-memory representations to file representations. +.Pp +Argument +.Fa src +denotes an +.Vt Elf_Data +descriptor describing the source to be translated. +The following elements of the descriptor need to be set before +invoking these functions: +.Bl -hang -offset indent +.It Va d_buf +Set to a valid pointer value denoting the beginning of the data area +to be translated. +.It Va d_size +Set to the total size in bytes of the source data area to be +translated. +.It Va d_type +Set to the type of the source data being translated. +This value is one of the values defined in the +.Vt Elf_Type +enumeration. +The +.Vt Elf_Type +enumeration is described in +.Xr elf 3 . +.It Va d_version +Set to the version number of the ELF data structures being +translated. +Currently only version +.Dv EV_CURRENT +is supported. +.El +.Pp +Argument +.Fa dst +describes the destination buffer. +The following elements of the +.Vt Elf_Data +descriptor need to be set before invoking these functions: +.Bl -hang -offset indent +.It Va d_buf +Set to a valid pointer value that denotes the start of the destination +buffer that will hold translated data. +This value may be the same as that of the source buffer, in which case +an in-place conversion will be attempted. +.It Va d_size +Set to the size of the destination buffer in bytes. +This value will be modified if the function call succeeds. +.It Va d_version +Set to the desired version number of the destination. +Currently only version +.Dv EV_CURRENT +is supported. +.El +.Pp +These translations routines allow the source and destination buffers +to coincide, in which case an in-place translation will be done +if the destination is large enough to hold the translated data. +Other kinds of overlap between the source and destination buffers +are not permitted. +.Pp +On successful completion of the translation request the following +fields of the +.Fa dst +descriptor would be modified: +.Bl -hang -offset indent +.It Va d_size +Set to the size in bytes of the translated data. +.It Va d_type +Set to the +.Va d_type +value of the source data descriptor. +.El +.Pp +Argument +.Fa file_encoding +specifies the encoding in which the file objects are represented. +It must be one of: +.Bl -hang -offset indent +.It Dv ELFDATANONE +File objects use the library's native byte ordering. +.It Dv ELFDATA2LSB +File objects use a little-endian ordering. +.It Dv ELFDATA2MSB +File objects use a big-endian ordering. +.El +.Pp +The functions +.Fn gelf_xlatetof +and +.Fn gelf_xlatetom +select the appropriate translation scheme based on the properties of +argument +.Fa elf . +.Sh RETURN VALUES +These functions return argument +.Fa dst +if successful, or +.Dv NULL +in case of an error. +.Sh EXAMPLES +To translate a +.Vt GElf_Rel +structure to its LSB file representation use: +.Bd -literal -offset indent +Elf_Data dst, src; +GElf_Rel rel; +Elf *e; + +e = ...; /* See elf_begin(3). */ + +/* Set up the 'src' descriptor. */ +memset(&src, 0, sizeof src); +src.d_buf = &rel; +src.d_size = sizeof(rel); +src.d_type = ELF_T_REL; +src.d_version = EV_CURRENT; + +/* Set up the 'dst' descriptor. */ +memset(&dst, 0, sizeof dst); +dst.d_buf = filebuf; +dst.d_size = gelf_fsize(e, ELF_T_REL, 1, EV_CURRENT); +dst.d_version = EV_CURRENT; + +if (gelf_xlatetof(e, &dst, &src, ELFDATA2LSB) == NULL) { + printf("error: %s", elf_errmsg(0)); +} +.Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +One of arguments +.Fa src , +.Fa dst +or +.Fa elf +was +.Dv NULL . +.It Bq Er ELF_E_ARGUMENT +Arguments +.Fa src +and +.Fa dst +were equal. +.It Bq Er ELF_E_ARGUMENT +The desired encoding parameter was not one of +.Dv ELFDATANONE , +.Dv ELFDATA2LSB +or +.Dv ELFDATA2MSB . +.It Bq Er ELF_E_ARGUMENT +The +.Fa d_type +field of argument +.Fa src +specified an unsupported type. +.It Bq Er ELF_E_DATA +The +.Fa src +argument specified a buffer size that was not an integral multiple of +its underlying type. +.It Bq Er ELF_E_DATA +The +.Fa dst +argument specified a buffer size that was too small. +.It Bq Er ELF_E_DATA +Argument +.Fa dst +specified a destination buffer that overlaps with the source +buffer. +.It Bq Er ELF_E_DATA +The destination buffer for a conversion to memory had an alignment +inappropriate for the underlying ELF type. +.It Bq Er ELF_E_DATA +The source buffer for a conversion to file had an alignment +inappropriate for the underlying ELF type. +.It Bq Er ELF_E_UNIMPL +The version numbers for arguments +.Fa dst +and +.Fa src +were not identical. +.It Bq Er ELF_E_UNIMPL +The argument +.Fa src +requested conversion for a type which is not currently +supported. +.It Bq Er ELF_E_VERSION +Argument +.Fa src +specified an unsupported version number. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf_getdata 3 , +.Xr gelf 3 diff --git a/static/netbsd/man3/getaddrinfo.3 b/static/netbsd/man3/getaddrinfo.3 new file mode 100644 index 00000000..c9f2e133 --- /dev/null +++ b/static/netbsd/man3/getaddrinfo.3 @@ -0,0 +1,343 @@ +.\" $NetBSD: getaddrinfo.3,v 1.1.1.2 2012/09/09 16:07:46 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: getaddrinfo.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd May 25, 1995 +.Dt GETADDRINFO @LIB_NETWORK_EXT@ +.Os KAME +.Sh NAME +.Nm getaddrinfo +.Nm freeaddrinfo , +.Nm gai_strerror +.Nd nodename-to-address translation in protocol-independent manner +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft int +.Fn getaddrinfo "const char *nodename" "const char *servname" \ +"const struct addrinfo *hints" "struct addrinfo **res" +.Ft void +.Fn freeaddrinfo "struct addrinfo *ai" +.Ft "char *" +.Fn gai_strerror "int ecode" +.Sh DESCRIPTION +The +.Fn getaddrinfo +function is defined for protocol-independent nodename-to-address translation. +It performs functionality of +.Xr gethostbyname @LIB_NETWORK_EXT@ +and +.Xr getservbyname @LIB_NETWORK_EXT@ , +in more sophisticated manner. +.Pp +The addrinfo structure is defined as a result of including the +.Li +header: +.Bd -literal -offset +struct addrinfo { * + int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ + int ai_family; /* PF_xxx */ + int ai_socktype; /* SOCK_xxx */ + int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + size_t ai_addrlen; /* length of ai_addr */ + char *ai_canonname; /* canonical name for nodename */ + struct sockaddr *ai_addr; /* binary address */ + struct addrinfo *ai_next; /* next structure in linked list */ +}; +.Ed +.Pp +The +.Fa nodename +and +.Fa servname +arguments are pointers to null-terminated strings or +.Dv NULL . +One or both of these two arguments must be a +.Pf non Dv -NULL +pointer. +In the normal client scenario, both the +.Fa nodename +and +.Fa servname +are specified. +In the normal server scenario, only the +.Fa servname +is specified. +A +.Pf non Dv -NULL +.Fa nodename +string can be either a node name or a numeric host address string +(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). +A +.Pf non Dv -NULL +.Fa servname +string can be either a service name or a decimal port number. +.Pp +The caller can optionally pass an +.Li addrinfo +structure, pointed to by the third argument, +to provide hints concerning the type of socket that the caller supports. +In this +.Fa hints +structure all members other than +.Fa ai_flags , +.Fa ai_family , +.Fa ai_socktype , +and +.Fa ai_protocol +must be zero or a +.Dv NULL +pointer. +A value of +.Dv PF_UNSPEC +for +.Fa ai_family +means the caller will accept any protocol family. +A value of 0 for +.Fa ai_socktype +means the caller will accept any socket type. +A value of 0 for +.Fa ai_protocol +means the caller will accept any protocol. +For example, if the caller handles only TCP and not UDP, then the +.Fa ai_socktype +member of the hints structure should be set to +.Dv SOCK_STREAM +when +.Fn getaddrinfo +is called. +If the caller handles only IPv4 and not IPv6, then the +.Fa ai_family +member of the +.Fa hints +structure should be set to +.Dv PF_INET +when +.Fn getaddrinfo +is called. +If the third argument to +.Fn getaddrinfo +is a +.Dv NULL +pointer, this is the same as if the caller had filled in an +.Li addrinfo +structure initialized to zero with +.Fa ai_family +set to PF_UNSPEC. +.Pp +Upon successful return a pointer to a linked list of one or more +.Li addrinfo +structures is returned through the final argument. +The caller can process each +.Li addrinfo +structure in this list by following the +.Fa ai_next +pointer, until a +.Dv NULL +pointer is encountered. +In each returned +.Li addrinfo +structure the three members +.Fa ai_family , +.Fa ai_socktype , +and +.Fa ai_protocol +are the corresponding arguments for a call to the +.Fn socket +function. +In each +.Li addrinfo +structure the +.Fa ai_addr +member points to a filled-in socket address structure whose length is +specified by the +.Fa ai_addrlen +member. +.Pp +If the +.Dv AI_PASSIVE +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then the caller plans to use the returned socket address +structure in a call to +.Fn bind . +In this case, if the +.Fa nodename +argument is a +.Dv NULL +pointer, then the IP address portion of the socket +address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +If the +.Dv AI_PASSIVE +bit is not set in the +.Fa ai_flags +member of the +.Fa hints +structure, then the returned socket address structure will be ready for a +call to +.Fn connect +.Pq for a connection-oriented protocol +or either +.Fn connect , +.Fn sendto , +or +.Fn sendmsg +.Pq for a connectionless protocol . +In this case, if the +.Fa nodename +argument is a +.Dv NULL +pointer, then the IP address portion of the +socket address structure will be set to the loopback address. +.Pp +If the +.Dv AI_CANONNAME +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then upon successful return the +.Fa ai_canonname +member of the first +.Li addrinfo +structure in the linked list will point to a null-terminated string +containing the canonical name of the specified +.Fa nodename . +.Pp +If the +.Dv AI_NUMERICHOST +bit is set in the +.Fa ai_flags +member of the +.Fa hints +structure, then a +.Pf non Dv -NULL +.Fa nodename +string must be a numeric host address string. +Otherwise an error of +.Dv EAI_NONAME +is returned. +This flag prevents any type of name resolution service (e.g., the DNS) +from being called. +.Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: +the +.Li addrinfo +structures, and the socket address structures and canonical node name +strings pointed to by the addrinfo structures. +To return this information to the system the function +Fn freeaddrinfo +is called. +The +.Fa addrinfo +structure pointed to by the +.Fa ai argument +is freed, along with any dynamic storage pointed to by the structure. +This operation is repeated until a +.Dv NULL +.Fa ai_next +pointer is encountered. +.Pp +To aid applications in printing error messages based on the +.Dv EAI_xxx +codes returned by +.Fn getaddrinfo , +.Fn gai_strerror +is defined. +The argument is one of the +.Dv EAI_xxx +values defined earlier and the return value points to a string describing +the error. +If the argument is not one of the +.Dv EAI_xxx +values, the function still returns a pointer to a string whose contents +indicate an unknown error. +.Sh FILES +.Bl -tag -width /etc/resolv.conf -compact +.It Pa /etc/hosts +.It Pa /etc/host.conf +.It Pa /etc/resolv.conf +.El +.Sh DIAGNOSTICS +Error return status from +.Fn getaddrinfo +is zero on success and non-zero on errors. +Non-zero error codes are defined in +.Li , +and as follows: +.Pp +.Bl -tag -width EAI_ADDRFAMILY -compact +.It Dv EAI_ADDRFAMILY +address family for nodename not supported +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for ai_flags +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +ai_family not supported +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with nodename +.It Dv EAI_NONAME +nodename nor servname provided, or not known +.It Dv EAI_SERVICE +servname not supported for ai_socktype +.It Dv EAI_SOCKTYPE +ai_socktype not supported +.It Dv EAI_SYSTEM +system error returned in errno +.El +.Pp +If called with proper argument, +.Fn gai_strerror +returns a pointer to a string describing the given error code. +If the argument is not one of the +.Dv EAI_xxx +values, the function still returns a pointer to a string whose contents +indicate an unknown error. +.Sh SEE ALSO +.Xr getnameinfo @LIB_NETWORK_EXT@ , +.Xr gethostbyname @LIB_NETWORK_EXT@ , +.Xr getservbyname @LIB_NETWORK_EXT@ , +.Xr hosts @FORMAT_EXT@ , +.Xr services @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ +.Pp +R. Gilligan, S. Thomson, J. Bound, and W. Stevens, +``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. +.Sh HISTORY +The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined IEEE POSIX 1003.1g draft specification, +and documented in ``Basic Socket Interface Extensions for IPv6'' +(RFC2133). +.Sh BUGS +The text was shamelessly copied from RFC2133. diff --git a/static/netbsd/man3/getarg.3 b/static/netbsd/man3/getarg.3 new file mode 100644 index 00000000..7ded8d9f --- /dev/null +++ b/static/netbsd/man3/getarg.3 @@ -0,0 +1,343 @@ +.\" $NetBSD: getarg.3,v 1.2 2017/01/28 21:31:50 christos Exp $ +.\" +.\" Copyright (c) 1999 - 2002 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.Dd September 24, 1999 +.Dt GETARG 3 +.Os ROKEN +.Sh NAME +.Nm getarg , +.Nm arg_printusage +.Nd collect command line options +.Sh SYNOPSIS +.In getarg.h +.Ft int +.Fn getarg "struct getargs *args" "size_t num_args" "int argc" "char **argv" "int *optind" +.Ft void +.Fn arg_printusage "struct getargs *args" "size_t num_args" "const char *progname" "const char *extra_string" +.Sh DESCRIPTION +.Fn getarg +collects any command line options given to a program in an easily used way. +.Fn arg_printusage +pretty-prints the available options, with a short help text. +.Pp +.Fa args +is the option specification to use, and it's an array of +.Fa struct getargs +elements. +.Fa num_args +is the size of +.Fa args +(in elements). +.Fa argc +and +.Fa argv +are the argument count and argument vector to extract option from. +.Fa optind +is a pointer to an integer where the index to the last processed +argument is stored, it must be initialised to the first index (minus +one) to process (normally 0) before the first call. +.Pp +.Fa arg_printusage +take the same +.Fa args +and +.Fa num_args +as getarg; +.Fa progname +is the name of the program (to be used in the help text), and +.Fa extra_string +is a string to print after the actual options to indicate more +arguments. The usefulness of this function is realised only be people +who has used programs that has help strings that doesn't match what +the code does. +.Pp +The +.Fa getargs +struct has the following elements. +.Bd -literal +struct getargs{ + const char *long_name; + char short_name; + enum { arg_integer, + arg_string, + arg_flag, + arg_negative_flag, + arg_strings, + arg_double, + arg_collect + } type; + void *value; + const char *help; + const char *arg_help; +}; +.Ed +.Pp +.Fa long_name +is the long name of the option, it can be +.Dv NULL , +if you don't want a long name. +.Fa short_name +is the characted to use as short option, it can be zero. If the option +has a value the +.Fa value +field gets filled in with that value interpreted as specified by the +.Fa type +field. +.Fa help +is a longer help string for the option as a whole, if it's +.Dv NULL +the help text for the option is omitted (but it's still displayed in +the synopsis). +.Fa arg_help +is a description of the argument, if +.Dv NULL +a default value will be used, depending on the type of the option: +.Pp +.Bl -hang -width arg_negative_flag +.It arg_integer +the argument is a signed integer, and +.Fa value +should point to an +.Fa int . +.It Fa arg_string +the argument is a string, and +.Fa value +should point to a +.Fa char* . +.It Fa arg_flag +the argument is a flag, and +.Fa value +should point to a +.Fa int . +It gets filled in with either zero or one, depending on how the option +is given, the normal case being one. Note that if the option isn't +given, the value isn't altered, so it should be initialised to some +useful default. +.It Fa arg_negative_flag +this is the same as +.Fa arg_flag +but it reverses the meaning of the flag (a given short option clears +the flag), and the synopsis of a long option is negated. +.It Fa arg_strings +the argument can be given multiple times, and the values are collected +in an array; +.Fa value +should be a pointer to a +.Fa struct getarg_strings +structure, which holds a length and a string pointer. +.It Fa arg_double +argument is a double precision floating point value, and +.Fa value +should point to a +.Fa double . +.It Fa arg_collect +allows more fine-grained control of the option parsing process. +.Fa value +should be a pointer to a +.Fa getarg_collect_info +structure: +.Bd -literal +typedef int (*getarg_collect_func)(int short_opt, + int argc, + char **argv, + int *optind, + int *optarg, + void *data); + +typedef struct getarg_collect_info { + getarg_collect_func func; + void *data; +} getarg_collect_info; +.Ed +.Pp +With the +.Fa func +member set to a function to call, and +.Fa data +to some application specific data. The parameters to the collect function are: +.Bl -inset +.It Fa short_flag +non-zero if this call is via a short option flag, zero otherwise +.It Fa argc , argv +the whole argument list +.It Fa optind +pointer to the index in argv where the flag is +.It Fa optarg +pointer to the index in argv[*optind] where the flag name starts +.It Fa data +application specific data +.El +.Pp +You can modify +.Fa *optind , +and +.Fa *optarg , +but to do this correct you (more or less) have to know about the inner +workings of getarg. +.Pp +You can skip parts of arguments by increasing +.Fa *optarg +(you could +implement the +.Fl z Ns Ar 3 +set of flags from +.Nm gzip +with this), or whole argument strings by increasing +.Fa *optind +(let's say you want a flag +.Fl c Ar x y z +to specify a coordinate); if you also have to set +.Fa *optarg +to a sane value. +.Pp +The collect function should return one of +.Dv ARG_ERR_NO_MATCH , ARG_ERR_BAD_ARG , ARG_ERR_NO_ARG, ENOMEM +on error, zero otherwise. +.Pp +For your convenience there is a function, +.Fn getarg_optarg , +that returns the traditional argument string, and you pass it all +arguments, sans data, that where given to the collection function. +.Pp +Don't use this more this unless you absolutely have to. +.El +.Pp +Option parsing is similar to what +.Xr getopt +uses. Short options without arguments can be compressed +.Pf ( Fl xyz +is the same as +.Fl x y z ) , +and short +options with arguments take these as either the rest of the +argv-string or as the next option +.Pf ( Fl o Ns Ar foo , +or +.Fl o Ar foo ) . +.Pp +Long option names are prefixed with -- (double dash), and the value +with a = (equal), +.Fl Fl foo= Ns Ar bar . +Long option flags can either be specified as they are +.Pf ( Fl Fl help ) , +or with an (boolean parsable) option +.Pf ( Fl Fl help= Ns Ar yes , +.Fl Fl help= Ns Ar true , +or similar), or they can also be negated +.Pf ( Fl Fl no-help +is the same as +.Fl Fl help= Ns no ) , +and if you're really confused you can do it multiple times +.Pf ( Fl Fl no-no-help= Ns Ar false , +or even +.Fl Fl no-no-help= Ns Ar maybe ) . +.Sh EXAMPLE +.Bd -literal +#include +#include +#include + +char *source = "Ouagadougou"; +char *destination; +int weight; +int include_catalog = 1; +int help_flag; + +struct getargs args[] = { + { "source", 's', arg_string, &source, + "source of shippment", "city" }, + { "destination", 'd', arg_string, &destination, + "destination of shippment", "city" }, + { "weight", 'w', arg_integer, &weight, + "weight of shippment", "tons" }, + { "catalog", 'c', arg_negative_flag, &include_catalog, + "include product catalog" }, + { "help", 'h', arg_flag, &help_flag } +}; + +int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */ + +const char *progname = "ship++"; + +int +main(int argc, char **argv) +{ + int optind = 0; + if (getarg(args, num_args, argc, argv, &optind)) { + arg_printusage(args, num_args, progname, "stuff..."); + exit (1); + } + if (help_flag) { + arg_printusage(args, num_args, progname, "stuff..."); + exit (0); + } + if (destination == NULL) { + fprintf(stderr, "%s: must specify destination\en", progname); + exit(1); + } + if (strcmp(source, destination) == 0) { + fprintf(stderr, "%s: destination must be different from source\en"); + exit(1); + } + /* include more stuff here ... */ + exit(2); +} +.Ed +.Pp +The output help output from this program looks like this: +.Bd -literal +$ ship++ --help +Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city] + [--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff... +-s city, --source=city source of shippment +-d city, --destination=city destination of shippment +-w tons, --weight=tons weight of shippment +-c, --no-catalog include product catalog +.Ed +.Sh BUGS +It should be more flexible, so it would be possible to use other more +complicated option syntaxes, such as what +.Xr ps 1 , +and +.Xr tar 1 , +uses, or the AFS model where you can skip the flag names as long as +the options come in the correct order. +.Pp +Options with multiple arguments should be handled better. +.Pp +Should be integrated with SL. +.Pp +It's very confusing that the struct you pass in is called getargS. +.Sh SEE ALSO +.Xr getopt 3 diff --git a/static/netbsd/man3/getbootfile.3 b/static/netbsd/man3/getbootfile.3 new file mode 100644 index 00000000..a4714976 --- /dev/null +++ b/static/netbsd/man3/getbootfile.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: getbootfile.3,v 1.9 2010/05/04 06:41:27 jruoho Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt GETBOOTFILE 3 +.Os +.Sh NAME +.Nm getbootfile +.Nd get the name of the booted kernel file +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft const char * +.Fn getbootfile void +.Sh DESCRIPTION +.Fn getbootfile +returns a static pointer to the full path name of the file from which +the current kernel was loaded. +If it can not be determined, or the file is not ``secure'' (see +.Xr secure_path 3 ) , +.Dv _PATH_UNIX +from +.In paths.h +is returned instead. +.Sh SEE ALSO +.Xr secure_path 3 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn getbootfile +function call appeared in +.Fx 2.0 +and +.Nx 1.6 . diff --git a/static/netbsd/man3/getbsize.3 b/static/netbsd/man3/getbsize.3 new file mode 100644 index 00000000..db80672c --- /dev/null +++ b/static/netbsd/man3/getbsize.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: getbsize.3,v 1.10 2022/12/06 00:13:17 uwe Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getbsize.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 30, 2003 +.Dt GETBSIZE 3 +.Os +.Sh NAME +.Nm getbsize +.Nd get user block size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn getbsize "int *headerlenp" "long *blocksizep" +.Sh DESCRIPTION +The +.Nm getbsize +function determines the user's preferred block size based on the value of the +.Ev BLOCKSIZE +environment variable; see +.Xr environ 7 +for details on its use and format. +.Pp +The +.Nm getbsize +function returns a pointer to a +.Dv NUL +terminated string describing +the block size, something like +.Dq 1K-blocks . +If the +.Fa headerlenp +parameter is not +.Dv NULL +the memory referenced by +.Fa headerlenp +is filled in with the length of the string (not including the +terminating +.Dv NUL ) . +If the +.Fa blocksizep +parameter is not +.Dv NULL +the memory referenced by +.Fa blocksizep +is filled in with block size, in bytes. +.Pp +If the user's block size is unreasonable, a warning message is +written to standard error and the returned information reflects +a block size of 512 bytes. +.Sh SEE ALSO +.Xr df 1 , +.Xr du 1 , +.Xr ls 1 , +.Xr systat 1 , +.Xr environ 7 +.Sh HISTORY +The +.Nm getbsize +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/getbyteorder.3 b/static/netbsd/man3/getbyteorder.3 new file mode 100644 index 00000000..21661cbf --- /dev/null +++ b/static/netbsd/man3/getbyteorder.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: getbyteorder.3,v 1.4 2014/03/18 18:20:38 riastradh Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 1, 2013 +.Dt GETBYTEORDER 3 +.Os +.Sh NAME +.Nm getbyteorder +.Nd get the current byte order +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.In sys/endian.h +.Ft int +.Fn getbyteorder void +.Sh DESCRIPTION +.Fn getbyteorder +returns +.Dv LITTLE_ENDIAN , +.Dv BIG_ENDIAN , +or \-1 in case of an error, setting the global +.Va errno +variable. +The possible values for +.Va errno +are the same as in +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr sysctl 3 +.Sh HISTORY +The +.Fn getbyteorder +function call appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/getc.3 b/static/netbsd/man3/getc.3 new file mode 100644 index 00000000..7f74c1d3 --- /dev/null +++ b/static/netbsd/man3/getc.3 @@ -0,0 +1,177 @@ +.\" $NetBSD: getc.3,v 1.13 2019/09/02 00:30:58 sevan Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 2, 2019 +.Dt GETC 3 +.Os +.Sh NAME +.Nm fgetc , +.Nm getc , +.Nm getchar , +.Nm getc_unlocked , +.Nm getchar_unlocked , +.Nm getw +.Nd get next character or word from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fgetc "FILE *stream" +.Ft int +.Fn getc "FILE *stream" +.Ft int +.Fn getchar +.Ft int +.Fn getc_unlocked "FILE *stream" +.Ft int +.Fn getchar_unlocked +.Ft int +.Fn getw "FILE *stream" +.Sh DESCRIPTION +The +.Fn fgetc +function +obtains the next input character (if present) from the stream pointed at by +.Fa stream , +or the next character pushed back on the stream via +.Xr ungetc 3 . +.Pp +The +.Fn getc +function +acts essentially identically to +.Fn fgetc , +but is a macro that expands in-line. +.Pp +The +.Fn getchar +function +is equivalent to: +getc with the argument stdin. +.Pp +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions provide functionality identical to that of +.Fn getc +and +.Fn getchar , +respectively, but do not perform implicit locking of the streams they +operate on. +In multi-threaded programs they may be used +.Em only +within a scope in which the stream +has been successfully locked by the calling thread using either +.Xr flockfile 3 +or +.Xr ftrylockfile 3 , +and may later be released using +.Xr funlockfile 3 . +.Pp +The +.Fn getw +function +obtains the next +.Em int +(if present) +from the stream pointed at by +.Fa stream . +.Sh RETURN VALUES +If successful, these routines return the next requested object +from the +.Fa stream . +If the stream is at end-of-file or a read error occurs, +the routines return +.Dv EOF . +The routines +.Xr feof 3 +and +.Xr ferror 3 +must be used to distinguish between end-of-file and error. +If an error occurs, the global variable +.Va errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.Dv EOF +until the condition is cleared with +.Xr clearerr 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr flockfile 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr ftrylockfile 3 , +.Xr funlockfile 3 , +.Xr putc 3 , +.Xr ungetc 3 +.Sh STANDARDS +The +.Fn fgetc , +.Fn getc +and +.Fn getchar +functions +conform to +.St -ansiC . +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn getc +and +.Fn getw +functions appeared in +.At v1 . +.Sh BUGS +Since +.Dv EOF +is a valid integer value, +.Xr feof 3 +and +.Xr ferror 3 +must be used to check for failure after calling +.Fn getw . +The size and byte order of an +.Em int +varies from one machine to another, and +.Fn getw +is not recommended for portable applications. diff --git a/static/netbsd/man3/getcwd.3 b/static/netbsd/man3/getcwd.3 new file mode 100644 index 00000000..712d5a94 --- /dev/null +++ b/static/netbsd/man3/getcwd.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: getcwd.3,v 1.18 2010/04/29 06:54:26 jruoho Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getcwd.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd April 29, 2010 +.Dt GETCWD 3 +.Os +.Sh NAME +.Nm getcwd , +.Nm getwd +.Nd get working directory pathname +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn getcwd "char *buf" "size_t size" +.Ft char * +.Fn getwd "char *buf" +.Sh DESCRIPTION +The +.Fn getcwd +function copies the absolute pathname of the current working directory +into the memory referenced by +.Fa buf +and returns a pointer to +.Fa buf . +The +.Fa size +argument is the size, in bytes, of the array referenced by +.Fa buf . +.Pp +If +.Fa buf +is +.Dv NULL , +space is allocated as necessary to store the pathname. +This space may later be +.Xr free 3 Ns 'd . +.Pp +The function +.Fn getwd +is a compatibility routine which calls +.Fn getcwd +with its +.Fa buf +argument and a size of +.Dv MAXPATHLEN +(as defined in the include +file +.In sys/param.h ) . +Obviously, +.Fa buf +should be at least +.Dv MAXPATHLEN +bytes in length. +.Pp +These routines have traditionally been used by programs to save the +name of a working directory for the purpose of returning to it. +A much faster and less error-prone method of accomplishing this is to +open the current directory +.Pq Ql \&. +and use the +.Xr fchdir 2 +function to return. +.Sh RETURN VALUES +Upon successful completion, a pointer to the pathname is returned. +Otherwise a +.Dv NULL +pointer is returned and the global variable +.Va errno +is set to indicate the error. +In addition, +.Fn getwd +copies the error message associated with +.Va errno +into the memory referenced by +.Fa buf . +.Sh ERRORS +The +.Fn getcwd +function +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Read or search permission was denied for a component of the pathname. +.It Bq Er EINVAL +The +.Fa size +argument is zero. +.It Bq Er ENOENT +A component of the pathname no longer exists. +.It Bq Er ENOMEM +Insufficient memory is available. +.It Bq Er ERANGE +The +.Fa size +argument is greater than zero but smaller than the length of the pathname +plus 1. +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr fchdir 2 , +.Xr malloc 3 , +.Xr strerror 3 +.Sh STANDARDS +The +.Fn getwd +and +.Fn getcwd +functions conform to +.St -p1003.1-90 . +The +.St -p1003.1-2004 +revision marked +.Fn getwd +as legacy and recommended the use of +.Fn getcwd +instead. +The +.St -p1003.1-2008 +revision removed +.Fn getwd +from the specification. +.Pp +The ability to specify a +.Dv NULL +pointer and have +.Fn getcwd +allocate memory as necessary is an extension. +.Sh HISTORY +The +.Fn getwd +function appeared in +.Bx 4.0 . +.Sh SECURITY CONSIDERATIONS +As +.Fn getwd +does not know the length of the supplied buffer, it is possible +for a long (but valid) path to overflow the buffer and provide +a means for an attacker to exploit the caller. +.Fn getcwd +should be used in place of +.Fn getwd +(the latter is only provided for compatibility purposes). diff --git a/static/netbsd/man3/getdate.3 b/static/netbsd/man3/getdate.3 new file mode 100644 index 00000000..f2c9fac9 --- /dev/null +++ b/static/netbsd/man3/getdate.3 @@ -0,0 +1,232 @@ +.\" $NetBSD: getdate.3,v 1.10 2018/02/11 13:28:49 wiz Exp $ +.\" +.\" Copyright (c) 2009, 2011, 2012, The NetBSD Foundation. +.\" All Rights Reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Brian Ginsbach. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 7, 2018 +.Dt GETDATE 3 +.Os +.Sh NAME +.Nm getdate , +.Nm getdate_err +.Nd convert user format date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft "struct tm *" +.Fo "getdate" +.Fa "const char *str" +.Fc +.Vt extern int getdate_err ; +.Sh DESCRIPTION +The +.Fn getdate +function converts a date or time character string pointed to by +.Fa str +into a static +.Vt tm +structure described in +.Xr tm 3 . +.Pp +The input string is parsed and interpreted using templates. +A text file containing templates is specified by the +environment variable +.Ev DATEMSK . +This should contain the full path to the template file. +Lines in the template file represent acceptable date and/or time +conversion specifications. +These specifications are similar to those given for +.Xr strptime 3 . +The first line in the template file that matches the input string +is used to interpret and convert to internal time format. +.Ss Internal Format Conversion +The following rules apply to converting the input into the internal format. +.Bl -bullet -offset indent +.It +If only the weekday is given, the conversion assumes today when the +weekday matches today or the first future matching weekday. +.It +If only the month and no year is given, the conversion assumes the +current month when the month matches or the first future matching month. +The first day of the month is assumed if no day is given. +.It +If only the year is given, the values of the +.Fa tm_mon , +.Fa tm_mday , +.Fa tm_wday , +.Fa tm_yday , +and +.Fa tm_isdst +members of the returned +.Vt "struct tm" +are unspecified. +.It +If the century is given, but the year within the century is not given, +the conversion assumes the current year. +.It +If no hour, minute, and second are given, the conversion assumes +the current hour, minute, and second. +.It +If no date is given, the conversion assumes today when the given hour +is greater than the current hour and tomorrow when the given hour is less. +.It +If +.Cm \&%Z +is being scanned, then the broken-down time is based on the +current time of the matched timezone and not the current runtime +environment timezone. +.El +.Sh RETURN VALUES +If successful, the +.Fn getdate +function returns a pointer to a static +.Vt tm +structure containing the broken-down time. +Otherwise, a null pointer is returned and +.Va getdate_err +is set to indicate the error. +.Pp +The variable +.Va getdate_err +can have the following values: +.Bl -tag -width NNN +.It 1 +.Ev DATEMSK +environment variable is null or undefined. +.It 2 +Cannot open the template file for reading. +.It 3 +Get file status failed for template file. +.It 4 +Template file is not a regular file. +.It 5 +Encountered an error while reading the template file. +.It 6 +Cannot allocate memory. +.It 7 +Input string does not match any line in the template file. +.It 8 +Input string is invalid (for example, February 31) +or could not be represented in a +.Vt time_t . +.El +.Sh ENVIRONMENT +.Bl -tag -width DATEMSK +.It Ev DATEMSK +The full path to the text file containing the templates +for acceptable date and/or time conversions. +.El +.Sh FILES +.Bl -tag -width DATEMSK +.It Pa /usr/share/examples/getdate/datemsk.template +An example template file that could be specified via the +.Ev DATEMSK +environment variable. +.El +.Sh EXAMPLES +The following example shows the possible contents of a template file: +.Pp +.Bd -literal -offset indent -compact +%m +%A %B %d, %Y, %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p, %B %dnd +%A den %d. %B %Y %H.%M Uhr +.Ed +.Pp +The following are examples of valid input for the above template: +.Pp +.Bd -literal -offset indent -compact +10/1/87 4 PM +Friday +Friday September 18, 1987, 10:30:30 +24,9,1986 10:30 +at monday the 1st of december in 1986 +run job at 3 PM, december 2nd +.Ed +.Pp +The following examples show how local data and time specification can be +defined in the template. +.Bl -column -offset indent ".Li Friday 12:00:00" ".Sy Line in Template" +.It Sy "Input String" Ta Sy "Line in Template" +.It Li 11/27/86 Ta Li \&%m/\&%d/\&%y +.It Li 27.11.86 Ta Li \&%d.\&%m.\&%y +.It Li 86-11-27 Ta Li \&%y-\&%m-\&%d +.It Li "Friday 12:00:00" Ta Li "\&%A \&%H:\&%M:\&%S" +.El +.Pp +The following examples illustrate the Internal Format Conversion rules +given that the current date is +.Li "Mon Sep 22 12:19:47 EDT 1986" +and the +.Ev LC_TIME +environment variable is set to the default C locale. +.Bl -column -offset indent ".Li Jan Wed 1989" ".Sy Line in Template" ".Sy Date" +.It Sy Input String Ta Sy Line in Template Ta Sy Date +.It Li Mon Ta Li \&%a Ta Li "Mon Sep 22 12:19:47 EDT 1986" +.It Li Sun Ta Li \&%a Ta Li "Sun Sep 28 12:19:47 EDT 1986" +.It Li Fri Ta Li \&%a Ta Li "Fri Sep 26 12:19:47 EDT 1986" +.It Li September Ta Li \&%B Ta Li "Mon Sep 1 12:19:47 EDT 1986" +.It Li January Ta Li \&%B Ta Li "Thu Jan 1 12:19:47 EST 1987" +.It Li December Ta Li \&%B Ta Li "Mon Dec 1 12:19:47 EST 1986" +.It Li "Sep Mon" Ta Li "\&%b %a" Ta Li "Mon Sep 1 12:19:47 EDT 1986" +.It Li "Jan Fri" Ta Li "\&%b %a" Ta Li "Fri Jan 2 12:19:47 EST 1987" +.It Li "Dec Mon" Ta Li "\&%b %a" Ta Li "Mon Dec 1 12:19:47 EST 1986" +.It Li "Jan Wed 1989" Ta Li "\&%b \&%a \&%Y" Ta Li "Wed Jan 4 12:19:47 EST 1989" +.It Li "Fri 9" Ta Li "\&%a \&%H" Ta Li "Fri Sep 26 09:00:00 EDT 1986" +.It Li "Feb 10:30" Ta Li "\&%b \&%H:\&%S" Ta Li "Sun Feb 1 10:00:30 EST 1987" +.It Li 10:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 23 10:30:00 EDT 1986" +.It Li 13:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 22 13:30:00 EDT 1986" +.El +.Sh SEE ALSO +.Xr ctime 3 , +.Xr localtime 3 , +.Xr mktime 3 , +.Xr strftime 3 , +.Xr strptime 3 , +.Xr time 3 +.Sh STANDARDS +The +.Fn getdate +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Nm +function appeared in +.At V.4 . +.Sh BUGS +The +.Nm +interface is inherently unsafe for multi-threaded programs or libraries, +since it returns a pointer to a static variable and uses a global state +variable. diff --git a/static/netbsd/man3/getdelim.3 b/static/netbsd/man3/getdelim.3 new file mode 100644 index 00000000..a3ae8eed --- /dev/null +++ b/static/netbsd/man3/getdelim.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: getdelim.3,v 1.16 2025/12/20 14:42:43 christos Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 20, 2025 +.Dt GETDELIM 3 +.Os +.Sh NAME +.Nm getdelim , +.Nm getline +.Nd read a delimited record from a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft ssize_t +.Fn getdelim "char ** restrict lineptr" "size_t * restrict n" "int delimiter" "FILE * restrict stream" +.Ft ssize_t +.Fn getline "char ** restrict lineptr" "size_t * restrict n" "FILE * restrict stream" +.Sh DESCRIPTION +The +.Fn getdelim +function reads from the +.Fa stream +until it encounters a character matching +.Fa delimiter +or +.Dv EOF , +storing the input in +.Fa *lineptr . +The buffer is +.Dv NUL Ns No -terminated +and includes the delimiter, if one was found. +The +.Fa delimiter +character must be representable as an unsigned char. +.Pp +If +.Fa *n +is non-zero, then +.Fa *lineptr +must be pre-allocated to at least +.Fa *n +bytes. +The buffer should be allocated dynamically; +it must be possible to +.Xr free 3 +.Fa *lineptr . +.Fn getdelim +ensures that +.Fa *lineptr +is large enough to hold the input, updating +.Fa *n +to reflect the new size. +.Pp +The +.Fn getline +function is equivalent to +.Fn getdelim +with +.Fa delimiter +set to the newline character. +.Sh RETURN VALUES +The +.Fn getdelim +and +.Fn getline +functions return the number of characters read, including the delimiter if +one was found. +If no characters were read and the stream is at end-of-file, the functions +return \-1. +If an error occurs, the functions return \-1 and the global variable +.Va errno +is set to indicate the error. +.Pp +The functions do not distinguish between end-of-file and error, +and callers must use +.Xr feof 3 +and +.Xr ferror 3 +to determine which occurred. +.Sh EXAMPLES +The following code fragment reads lines from a file and writes them to +standard output. +.Bd -literal -offset indent +char *line = NULL; +size_t linesize = 0; +ssize_t linelen; + +while ((linelen = getline(&line, &linesize, fp)) != -1) + fwrite(line, linelen, 1, stdout); + +if (ferror(fp)) + perror("getline"); +.Ed +.Sh ERRORS +.Bl -tag -width [EOVERFLOW] +.It Bq Er EINVAL +.Fa lineptr +or +.Fa n +is a +.Dv NULL +pointer. +.It Bq Er EOVERFLOW +More than SSIZE_MAX characters were read without encountering the delimiter. +.El +.Pp +The +.Fn getdelim +and +.Fn getline +functions may also fail and set +.Va errno +for any of the errors specified in the routines +.Xr fflush 3 , +.Xr malloc 3 , +.Xr read 2 , +.Xr stat 2 , +or +.Xr realloc 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgetln 3 , +.Xr fgets 3 , +.Xr fopen 3 , +.Xr fparseln 3 , +.Xr strlen 3 +.Sh STANDARDS +The +.Fn getdelim +and +.Fn getline +functions conform to +.St -p1003.1-2008 . +.Sh NOTES +The +.Fn getdelim +and +.Fn getline +functions can return results that include +.Dv NUL +characters, which can cause the apparent length reported by +.Xr strlen 3 +to be less than the true length reported by the +return values of the functions. diff --git a/static/netbsd/man3/getdevmajor.3 b/static/netbsd/man3/getdevmajor.3 new file mode 100644 index 00000000..4b7629c7 --- /dev/null +++ b/static/netbsd/man3/getdevmajor.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: getdevmajor.3,v 1.6 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Andrew Brown. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 20, 2009 +.Dt GETDEVMAJOR 3 +.Os +.Sh NAME +.Nm getdevmajor +.Nd get block or character device major number +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.In sys/stat.h +.Ft devmajor_t +.Fn getdevmajor "const char *name" "mode_t type" +.Sh DESCRIPTION +The +.Fn getdevmajor +function returns the major device number of the block or character +device specified by +.Ar name +and a file type matching the one encoded in +.Fa type +which must be one of +.Dv S_IFBLK +or +.Dv S_IFCHR . +.Sh RETURN VALUES +If no device matches the specified values, no information is +available, or an error occurs, +.Dv NODEVMAJOR +is returned and +.Va errno +is set to indicate the error. +.Sh EXAMPLES +To retrieve the major number for +.Xr pty 4 +slave devices (aka pts devices): +.Bd -literal -offset indent +#include +#include +.sp +devmajor_t pts; +pts = getdevmajor("pts", S_IFCHR); +.Ed +.Pp +To retrieve the major numbers for the block and character +.Xr wd 4 +devices: +.Bd -literal -offset indent +#include +#include +.sp +devmajor_t c, b; +c = getdevmajor("wd", S_IFCHR); +b = getdevmajor("wd", S_IFBLK); +.Ed +.Sh ERRORS +The +.Fn getdevmajor +function may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr malloc 3 +and +.Xr sysctlbyname 3 . +In addition, the following errors may be reported: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa type +argument is not +.Dv S_IFCHR +or +.Dv S_IFBLK . +.It Bq Er ENOENT +The named device is not found. +.El +.Sh SEE ALSO +.Xr stat 2 , +.Xr devname 3 , +.Xr malloc 3 , +.Xr sysctlbyname 3 +.Sh HISTORY +The +.Fn getdevmajor +function call appeared in +.Nx 3.0 . diff --git a/static/netbsd/man3/getdirentries.3 b/static/netbsd/man3/getdirentries.3 new file mode 100644 index 00000000..b1f4b6e5 --- /dev/null +++ b/static/netbsd/man3/getdirentries.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: getdirentries.3,v 1.1 2005/09/13 01:44:09 christos Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getdirentries.2 8.1 (Berkeley) 6/9/93 +.\" +.Dd June 9, 1993 +.Dt GETDIRENTRIES 3 +.Os +.Sh NAME +.Nm getdirentries +.Nd "get directory entries in a filesystem independent format" +.Sh SYNOPSIS +.In dirent.h +.Ft int +.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" +.Sh DESCRIPTION +.Bf -symbolic +.\" This interface is available from the compatibility library, libcompat and +This interface is provided for compatibility only and +has been obsoleted by +.Xr getdents 2 . +.Ef +.Pp +.Fn getdirentries +reads directory entries from the directory +referenced by the file descriptor +.Fa fd +into the buffer pointed to by +.Fa buf , +in a filesystem independent format. +Up to +.Fa nbytes +of data will be transferred. +.Fa nbytes +must be greater than or equal to the +block size associated with the file, +see +.Xr stat 2 . +Some filesystems may not support +.Fn getdirentries +with buffers smaller than this size. +.Pp +The data in the buffer is a series of +.Em dirent +structures each containing the following entries: +.Bd -literal -offset indent +unsigned long d_fileno; +unsigned short d_reclen; +unsigned short d_namlen; +char d_name[MAXNAMELEN + 1]; /* see below */ +.Ed +.Pp +The +.Fa d_fileno +entry is a number which is unique for each +distinct file in the filesystem. +Files that are linked by hard links (see +.Xr link 2 ) +have the same +.Fa d_fileno . +If +.Fa d_fileno +is zero, the entry refers to a deleted file. +.Pp +The +.Fa d_reclen +entry is the length, in bytes, of the directory record. +.Pp +The +.Fa d_namlen +entry specifies the length of the file name excluding the null byte. +Thus the actual size of +.Fa d_name +may vary from 1 to +.Dv MAXNAMELEN +\&+ 1. +.Pp +The +.Fa d_name +entry contains a null terminated file name. +.Pp +Entries may be separated by extra space. +The +.Fa d_reclen +entry may be used as an offset from the start of a +.Fa dirent +structure to the next structure, if any. +.Pp +The actual number of bytes transferred is returned. +The current position pointer associated with +.Fa fd +is set to point to the next block of entries. +The pointer may not advance by the number of bytes returned by +.Fn getdirentries . +A value of zero is returned when +the end of the directory has been reached. +.Pp +.Fn getdirentries +writes the position of the block read into the location pointed to by +.Fa basep . +Alternatively, the current position pointer may be set and retrieved by +.Xr lseek 2 . +The current position pointer should only be set to a value returned by +.Xr lseek 2 , +a value returned in the location pointed to by +.Fa basep , +or zero. +.Sh RETURN VALUES +If successful, the number of bytes actually transferred is returned. +Otherwise, \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn getdirentries +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fd +is not a valid file descriptor open for reading. +.It Bq Er EFAULT +Either +.Fa buf +or +.Fa basep +point outside the allocated address space. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr lseek 2 , +.Xr open 2 +.Sh HISTORY +The +.Fn getdirentries +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/getdiskbyname.3 b/static/netbsd/man3/getdiskbyname.3 new file mode 100644 index 00000000..93c01e42 --- /dev/null +++ b/static/netbsd/man3/getdiskbyname.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: getdiskbyname.3,v 1.13 2009/08/19 15:47:39 joerg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getdiskbyname.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt GETDISKBYNAME 3 +.Os +.Sh NAME +.Nm getdiskbyname , +.Nm setdisktab +.Nd get generic disk description by its name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/disklabel.h +.In disktab.h +.Ft int +.Fn setdisktab "char *name" +.Ft struct disklabel * +.Fn getdiskbyname "const char *name" +.Sh DESCRIPTION +The +.Fn getdiskbyname +function +takes a disk name (e.g. +.Ql rm03 ) +and returns a prototype disk label +describing its geometry information and the standard +disk partition tables. +All information is obtained from the +.Xr disktab 5 +file. +.Pp +The +.Fn setdisktab +function changes the default +.Sy disktab +file name from +.Pa /etc/disktab +.Pq aka Dv _PATH_DISKTAB +to +.Fa name . +.Sh RETURN VALUES +.Fn getdiskbyname +returns a null pointer if the entry is not found in the current +.Pa disktab +file. +.Pp +.Fn setdisktab +returns 0 on success and \-1 if +.Fa name +is a null pointer or points to an empty string. +.Sh FILES +.Bl -tag -width /etc/disktab -compact +.It Pa /etc/disktab +the default database of disk types. +.El +.Sh SEE ALSO +.Xr disklabel 5 , +.Xr disktab 5 , +.Xr disklabel 8 +.Sh HISTORY +The +.Fn getdiskbyname +function appeared in +.Bx 4.3 . +.Pp +The +.Fn setdisktab +function appeared in +.Nx 1.4 . +.Sh BUGS +The +.Fn getdiskbyname +function leaves its results in an internal static object and returns a +pointer to that object. +Subsequent calls will modify the same object. diff --git a/static/netbsd/man3/getdiskrawname.3 b/static/netbsd/man3/getdiskrawname.3 new file mode 100644 index 00000000..2dc37d8e --- /dev/null +++ b/static/netbsd/man3/getdiskrawname.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: getdiskrawname.3,v 1.4 2019/03/08 08:12:39 msaitoh Exp $ +.\" +.\" Copyright (c) 2012 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd March 7, 2012 +.Dt GETDISKRAWNAME 3 +.Os +.Sh NAME +.Nm getdiskrawname , +.Nm getdiskcookedname +.Nd get the block/character device name for a disk +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft const char * +.Fn getdiskrawname "char *buf" "size_t buflen" "const char *name" +.Ft const char * +.Fn getdiskcookedname "char *buf" "size_t buflen" "const char *name" +.Sh DESCRIPTION +The +.Fn getdiskrawname +function converts the +.Fa name +argument that contains a path to a disk block device node to the +path that contains the corresponding character device node. +The +.Fn getdiskcookedname +function converts the +.Fa name +argument that contains a path to a disk character device node to the +path that contains the corresponding block device node. +.Sh RETURN VALUES +On success the absolute pathname of the underlying device node is returned. +On failure +.Dv NULL +is returned and +.Va errno +contains the reason for the error. +.Sh HISTORY +The +.Fn getdiskrawname +and +.Fn getdiskcookedname +functions appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/getdomainname.3 b/static/netbsd/man3/getdomainname.3 new file mode 100644 index 00000000..44f6244f --- /dev/null +++ b/static/netbsd/man3/getdomainname.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: getdomainname.3,v 1.16 2015/02/06 17:35:46 ginsbach Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gethostname.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 6, 1994 +.Dt GETDOMAINNAME 3 +.Os +.Sh NAME +.Nm getdomainname , +.Nm setdomainname +.Nd get/set domain name of current host +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdomainname "char *name" "size_t namelen" +.Ft int +.Fn setdomainname "const char *name" "size_t namelen" +.Sh DESCRIPTION +.Fn getdomainname +returns the standard domain name for the current host, as +previously set by +.Fn setdomainname . +The parameter +.Fa namelen +specifies the size of the +.Fa name +array. +The returned name is null-terminated unless insufficient +space is provided. +.Pp +.Fn setdomainname +sets the domain name of the host machine to be +.Fa name , +which has length +.Fa namelen . +This call is restricted to the super-user and +is normally used only when the system is bootstrapped. +.Sh RETURN VALUES +If the call succeeds a value of 0 is returned. +If the call fails, a value of \-1 is returned and an error code is +placed in the global location +.Va errno . +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +or +.Fa namelen +parameter gave an +invalid address. +.It Bq Er EPERM +The caller tried to set the domain name and was not the super-user. +.El +.Sh SEE ALSO +.Xr gethostid 3 , +.Xr gethostname 3 , +.Xr sysctl 3 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . +.Sh BUGS +Domain names are limited to +.Dv MAXHOSTNAMELEN +(from +.Ao Pa sys/param.h Ac ) +characters including null-termination, currently 256. diff --git a/static/netbsd/man3/getdtablesize.3 b/static/netbsd/man3/getdtablesize.3 new file mode 100644 index 00000000..e6ec1fba --- /dev/null +++ b/static/netbsd/man3/getdtablesize.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)getdtablesize.2 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: getdtablesize.3,v 1.14 2012/01/05 07:05:59 yamt Exp $ +.\" +.Dd January 5, 2012 +.Dt GETDTABLESIZE 3 +.Os +.Sh NAME +.Nm getdtablesize +.Nd get descriptor table size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdtablesize void +.Sh DESCRIPTION +The +.Nm +function is an equivalent of +.Fn sysconf +with +.Dv _SC_OPEN_MAX . +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr getrlimit 2 , +.Xr open 2 , +.Xr select 2 , +.Xr sysconf 3 +.Sh HISTORY +The +.Fn getdtablesize +function call appeared in +.Bx 4.2 . +.Pp +Historically, each process had a fixed size descriptor table, +which is guaranteed to have at least 20 slots. +The entries in +the descriptor table are numbered with small integers starting at 0. +The call +.Fn getdtablesize +used to return the size of this table. +It doesn't make much sense these days because the size of the table is dynamic. diff --git a/static/netbsd/man3/getentropy.3 b/static/netbsd/man3/getentropy.3 new file mode 100644 index 00000000..856f6881 --- /dev/null +++ b/static/netbsd/man3/getentropy.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: getentropy.3,v 1.8 2024/08/28 14:08:48 riastradh Exp $ $ +.\" +.\" Copyright (c) 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Nia Alarie. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 28, 2024 +.Dt GETENTROPY 3 +.Os +.Sh NAME +.Nm getentropy +.Nd generate uniform random seeds from system entropy for cryptography +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getentropy "void *buf" "size_t buflen" +.In limits.h +.Pp +.Li #define GETENTROPY_MAX 256 +.Sh DESCRIPTION +The +.Nm +function fills +.Fa buf +with exactly +.Fa buflen +independent uniform random bytes derived from the system's entropy +pool. +.Pp +The output of +.Nm +is meant to be unpredictable to an adversary and fit for use in +cryptography. +See +.Sx CAVEATS +below. +.Pp +.Nm +is meant for seeding random number generators, not for direct use by +applications; most applications should use +.Xr arc4random 3 . +.Pp +.Fa buflen +must be at most 256. +.Sh RETURN VALUES +.Rv -std getentropy +.Sh ERRORS +.Nm +will succeed unless: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa buf +argument points to an invalid memory address. +.It Bq Er EINVAL +More than 256 bytes were requested. +.El +.Sh CAVEATS +Security can only be guaranteed relative to whatever unpredictable +physical processes or secret seed material are available to the system; +see +.Xr entropy 7 . +.Pp +On systems which have no hardware random number generator and which +have not had secret seed material loaded, +.Nx +makes a reasonable effort to incorporate samples from various physical +processes available to it that might be unpredictable from random +jitter in timing. +.Pp +However, the +.Nm +interface alone can make no security guarantees without a physical +system configuration that includes random number generation hardware or +secret seed material from such hardware on another machine. +.Pp +.Nx +attempts to reseed the system entropy pool when it has detected the +system has been cloned as a guest in a virtual machine, so that +subsequent calls to +.Nm +in the clones yield independent outputs. +However, this relies on the virtual machine host to notify the guest, +e.g. through the +.Xr acpivmgenid 4 +device, and even so there is an unavoidable small window of time +between when the virtual machine is actually cloned and when the system +is reseeded during which +.Nm +may yield identical outputs in the clones. +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr rnd 4 , +.Xr entropy 7 +.Sh STANDARDS +The +.Nm +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Nm +function first appeared in +.Ox 5.6 , +then in +.Fx 12.0 , +and in +.Nx 10.0 . diff --git a/static/netbsd/man3/getenv.3 b/static/netbsd/man3/getenv.3 new file mode 100644 index 00000000..ada3e6f6 --- /dev/null +++ b/static/netbsd/man3/getenv.3 @@ -0,0 +1,231 @@ +.\" $NetBSD: getenv.3,v 1.26 2025/05/25 05:44:10 rillig Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)getenv.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd May 25, 2025 +.Dt GETENV 3 +.Os +.Sh NAME +.Nm getenv , +.Nm getenv_r , +.Nm putenv , +.Nm setenv , +.Nm unsetenv +.Nd environment variable functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn getenv "const char *name" +.Ft int +.Fn getenv_r "const char *name" "char *buf" "size_t len" +.Ft int +.Fn setenv "const char *name" "const char *value" "int overwrite" +.Ft int +.Fn putenv "char *string" +.Ft int +.Fn unsetenv "const char *name" +.Sh DESCRIPTION +These functions set, unset and fetch environment variables from the +host +.Em environment list . +For compatibility with differing environment conventions, +the +.Fn getenv +or +.Fn getenv_r +given argument +.Ar name +may be appended with an equal sign +.Dq Li \&= . +.Pp +The +.Fn getenv +function obtains the current value of the environment variable +.Ar name . +If the variable +.Ar name +is not in the current environment, a +.Dv NULL +pointer is returned. +.Pp +The +.Fn getenv_r +function obtains the current value of the environment variable +.Fa name +and copies it to +.Fa buf . +If +.Fa name +is not in the current environment, or the string length of the value of +.Fa name +is longer than +.Fa len +characters, then \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn setenv +function inserts or resets the environment variable +.Ar name +in the current environment list. +If the variable +.Ar name +does not exist in the list, +it is inserted with the given +.Ar value . +If the variable does exist, the argument +.Ar overwrite +is tested; if +.Ar overwrite is +zero, the +variable is not reset, otherwise it is reset +to the given +.Ar value . +.Pp +The +.Fn putenv +function takes an argument of the form +.Dq name=value +and it will set the environment variable +.Dq name +equal to +.Dq value +by altering an existing entry, or creating a new one if an existing +one does not exist. +The actual string argument passed to +.Fn putenv +will become part of the environment. +If one changes the string, the environment will also change. +.Pp +The +.Fn unsetenv +function +deletes all instances of the variable name pointed to by +.Fa name +from the list. +.Sh RETURN VALUES +The functions +.Fn getenv_r , +.Fn setenv , +.Fn putenv , +and +.Fn unsetenv +return zero if successful; otherwise the global variable +.Va errno +is set to indicate the error and a +\-1 is returned. +.Pp +If +.Fn getenv +is successful, the string returned should be considered read-only. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa name +argument to +.Fn setenv +or +.Fn unsetenv +is a null pointer, points to an empty string, or points to a string +containing an +.Dq Li \&= +character. +The +.Fa value +argument to +.Fn setenv +is a null pointer. +The +.Fa string +argument to +.Fn putenv +is a null pointer, or points to a string that either starts with a +.Dq Li \&= +character or does not contain one at all. +.It Bq Er ENOMEM +The function +.Fn setenv +or +.Fn putenv +failed because they were unable to allocate memory for the environment. +.El +.Pp +The function +.Fn getenv_r +can return the following errors: +.Bl -tag -width Er +.It Bq Er ENOENT +The variable +.Fa name +was not found in the environment. +.It Bq Er ERANGE +The value of the named variable is too long to fit in the supplied buffer. +.El +.Sh SEE ALSO +.Xr csh 1 , +.Xr sh 1 , +.Xr execve 2 , +.Xr environ 7 +.Sh STANDARDS +The +.Fn getenv +function conforms to +.St -ansiC . +.Pp +The +.Fn putenv +function conforms to +.St -xpg4 . +.Pp +The +.Fn setenv +and +.Fn unsetenv +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The functions +.Fn setenv +and +.Fn unsetenv +appeared in +.At v7 . +The +.Fn putenv +function appeared in +.Bx 4.3 Reno . diff --git a/static/netbsd/man3/getfsent.3 b/static/netbsd/man3/getfsent.3 new file mode 100644 index 00000000..abfecfef --- /dev/null +++ b/static/netbsd/man3/getfsent.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: getfsent.3,v 1.12 2012/04/07 03:47:30 christos Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getfsent.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd March 6, 2012 +.Dt GETFSENT 3 +.Os +.Sh NAME +.Nm getfsent , +.Nm getfsspec , +.Nm getfsfile , +.Nm setfsent , +.Nm endfsent +.Nd get file system descriptor file entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fstab.h +.Ft struct fstab * +.Fn getfsent void +.Ft struct fstab * +.Fn getfsspec "const char *spec" +.Ft struct fstab * +.Fn getfsfile "const char *file" +.Ft int +.Fn setfsent void +.Ft void +.Fn endfsent void +.Sh DESCRIPTION +The +.Fn getfsent , +.Fn getfsspec , +and +.Fn getfsfile +functions +each return a pointer to an object with the following structure +containing the broken-out fields of a line in the file system +description file, +.In fstab.h . +.Bd -literal -offset indent +struct fstab { + char *fs_spec; /* block special device name */ + char *fs_file; /* file system path prefix */ + char *fs_vfstype; /* type of file system */ + char *fs_mntops; /* comma separated mount options */ + char *fs_type; /* rw, ro, sw, or xx */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel dump */ +}; +.Ed +.Pp +The fields have meanings described in +.Xr fstab 5 . +.Pp +The +.Fn setfsent +function +opens the file (closing any previously opened file) or rewinds it +if it is already open. +.Pp +The +.Fn endfsent +function +closes the file. +.Pp +The +.Fn getfsspec +and +.Fn getfsfile +functions +search the entire file (opening it if necessary) for a matching special +file name or file system file name. +.Pp +For programs wishing to read the entire database, +.Fn getfsent +reads the next entry (opening the file if necessary). +.Pp +All entries in the file with a type field equivalent to +.Dv FSTAB_XX +are ignored. +.Sh RETURN VALUES +The +.Fn getfsent , +.Fn getfsspec , +and +.Fn getfsfile +functions +return a null pointer (0) on +.Dv EOF +or error. +The +.Fn setfsent +function +returns 0 on failure, 1 on success. +The +.Fn endfsent +function +returns nothing. +.Sh FILES +.Bl -tag -width /etc/fstab -compact +.It Pa /etc/fstab +.El +.Sh SEE ALSO +.Xr getfsspecname 3 , +.Xr fstab 5 +.Sh HISTORY +The +.Fn getfsent +function appeared in +.Bx 4.0 ; +the +.Fn endfsent , +.Fn getfsfile , +.Fn getfsspec , +and +.Fn setfsent +functions appeared in +.Bx 4.3 . +.Sh BUGS +These functions use static data storage; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. diff --git a/static/netbsd/man3/getfsspecname.3 b/static/netbsd/man3/getfsspecname.3 new file mode 100644 index 00000000..0dceb8c7 --- /dev/null +++ b/static/netbsd/man3/getfsspecname.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: getfsspecname.3,v 1.7 2018/12/28 18:44:11 alnsn Exp $ +.\" +.\" Copyright (c) 2012 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd December 28, 2018 +.Dt GETFSSPECNAME 3 +.Os +.Sh NAME +.Nm getfsspecname +.Nd get the underlying wedge name from a label +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft const char * +.Fn getfsspecname "char *buf" "size_t buflen" "const char *spec" +.Sh DESCRIPTION +The +.Fn getfsspecname +function translates an +.Ft fs_spec +field in the +.Fa spec +argument of the form +.Dq NAME=wedgename +to the underlying +.Xr dk 4 +device node, and places the resulting pathname in +.Fa buf +up to len +.Fa buflen . +.Pp +If the +.Fa spec +argument starts with +.Dq ROOT. , +a path in the form +.Dq /dev/[root_device][suffix] +is copied to +.Fa buf , +where +.Bq root_device +is the value of the +.Dq kern.root_device +sysctl and +.Bq suffix +is the characters following +.Dq ROOT. +in the +.Fa spec +argument. +.Pp +If the +.Fa spec +argument is not of the form +.Dq NAME=wedgename +and it doesn't start with +.Dq ROOT. , +.Fa spec +is copied +to +.Fa buf +and returned. +.Sh RETURN VALUES +On success the absolute pathname of the underlying wedge device is returned, +or the original +.Fa spec +argument. +On failure +.Dv NULL +is returned and +.Fa buf +contains the reason for the error. +.Sh SEE ALSO +.Xr fstab 5 +.Sh HISTORY +The +.Fn getfsspecname +function appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/getfstypename.3 b/static/netbsd/man3/getfstypename.3 new file mode 100644 index 00000000..77982e36 --- /dev/null +++ b/static/netbsd/man3/getfstypename.3 @@ -0,0 +1,55 @@ +.\" $NetBSD: getfstypename.3,v 1.4 2025/07/17 12:05:58 andvar Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 13, 2011 +.Dt GETFSTYPENAME 3 +.Os +.Sh NAME +.Nm getfstypename +.Nd convert a partition file system type integer to a wedge partition type name +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft const char * +.Fn getfstypename "int fstype" +.Sh DESCRIPTION +.Fn getfstypename +returns the disk wedge partition type name corresponding to the +.Ar fstype +argument as specified in +.In sys/disk.h +or +.Dv DKW_PTYPE_UNKNOWN +if none is found. +.Sh HISTORY +The +.Fn getfstypename +function call appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/getgrent.3 b/static/netbsd/man3/getgrent.3 new file mode 100644 index 00000000..ebf1aad0 --- /dev/null +++ b/static/netbsd/man3/getgrent.3 @@ -0,0 +1,344 @@ +.\" $NetBSD: getgrent.3,v 1.32 2018/02/07 11:16:05 pgoyette Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getgrent.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd February 7, 2018 +.Dt GETGRENT 3 +.Os +.Sh NAME +.Nm getgrent , +.Nm getgrent_r , +.Nm getgrgid , +.Nm getgrgid_r , +.Nm getgrnam , +.Nm getgrnam_r , +.Nm setgroupent , +.\" .Nm setgrfile , +.Nm setgrent , +.Nm endgrent +.Nd group database operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In grp.h +.Ft struct group * +.Fn getgrent void +.Ft int +.Fo getgrent_r +.Fa "struct group *grp" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct group **result" +.Fc +.Ft struct group * +.Fn getgrgid "gid_t gid" +.Ft int +.Fo getgrgid_r +.Fa "gid_t gid" +.Fa "struct group *grp" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct group **result" +.Fc +.Ft struct group * +.Fn getgrnam "const char *name" +.Ft int +.Fo getgrnam_r +.Fa "const char *name" +.Fa "struct group *grp" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct group **result" +.Fc +.Ft int +.Fn setgroupent "int stayopen" +.\" .Ft void +.\" .Fn setgrfile "const char *name" +.Ft void +.Fn setgrent void +.Ft void +.Fn endgrent void +.Sh DESCRIPTION +These functions operate on the group database which is described in +.Xr group 5 . +Each line of the database is defined by the structure +.Ar group +found in the include +file +.In grp.h : +.Bd -literal -offset indent +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group id */ + char **gr_mem; /* group members */ +}; +.Ed +.Pp +The functions +.Fn getgrnam +and +.Fn getgrgid +search the group database for the given group name pointed to by +.Ar name +or the group id pointed to by +.Ar gid , +respectively, returning the first one encountered. +Identical group names or group ids may result in undefined behavior. +.Pp +The +.Fn getgrent +function sequentially reads the group database and is intended for programs +that wish to step through the complete list of groups. +.Pp +All three functions will open the group file for reading, if necessary. +.Pp +The functions +.Fn getgrnam_r , +.Fn getgrgid_r , +and +.Fn getgrent_r +act like their non re-entrant counterparts +respectively, updating the contents of +.Ar grp +and storing a pointer to that in +.Ar result , +and returning +.Dv 0 . +Storage used by +.Ar grp +is allocated from +.Ar buffer , +which is +.Ar buflen +bytes in size. +If the requested entry cannot be found, +.Ar result +will point to +.Dv NULL +and +.Dv 0 +will be returned. +If an error occurs, +a non-zero error number will be returned and +.Ar result +will point to +.Dv NULL . +Calling +.Fn getgrent_r +from multiple threads will result in each thread reading a disjoint portion +of the group database. +.Pp +The +.Fn setgroupent +function opens the file, or rewinds it if it is already open. +If +.Fa stayopen +is non-zero, file descriptors are left open, significantly speeding +functions subsequent calls. +This functionality is unnecessary for +.Fn getgrent +as it doesn't close its file descriptors by default. +It should also be noted that it is dangerous for long-running +programs to use this functionality as the group file may be updated. +.Pp +The +.Fn setgrent +function is equivalent to +.Fn setgroupent +with an argument of zero. +.Pp +The +.Fn endgrent +function closes any open files. +.Sh RETURN VALUES +The functions +.Fn getgrgid , +.Fn getgrnam , +and +.Fn getgrent +return a valid pointer to a group structure on success +and a +.Dv NULL +pointer if the entry was not found or an error occurred. +If an error occurred, the global variable +.Dv errno +is set to indicate the nature of the failure. +.Pp +The functions +.Fn getgrgid_r , +.Fn getgrnam_r , +and +.Fn getgrent_r +return +.Dv 0 +on success or entry not found, and non-zero on failure, setting the global +variable +.Dv errno +to indicate the nature of the failure. +.Pp +The +.Fn setgroupent +function returns the value 1 if successful, otherwise the value +0 is returned, setting the global variable +.Dv errno +to indicate the nature of the failure. +.Pp +The +.Fn endgrent +and +.Fn setgrent +functions have no return value. +.Sh FILES +.Bl -tag -width /etc/group -compact +.It Pa /etc/group +group database file +.El +.Sh COMPATIBILITY +The historic function +.Fn setgrfile , +which allowed the specification of alternative group databases, has +been deprecated and is no longer available. +.Sh ERRORS +The following error codes may be set in +.Va errno +for +.Nm getgrent , +.Nm getgrent_r , +.Nm getgrnam , +.Nm getgrnam_r , +.Nm getgrgid , +.Nm getgrgid_r , +and +.Nm setgroupent : +.Bl -tag -width Er +.It Bq Er EINTR +A signal was caught during the database search. +.It Bq Er EIO +An I/O error has occurred. +.It Bq Er EMFILE +The limit on open files for this process has been reached. +.It Bq Er ENFILE +The system limit on open files has been reached. +.El +.Pp +The following error code may be set in +.Va errno +for +.Nm getgrent_r , +.Nm getgrnam_r , +and +.Nm getgrgid_r : +.Bl -tag -width Er +.It Bq Er ERANGE +The resulting +.Ft struct group +does not fit in the space defined by +.Dv buffer +and +.Dv buflen +.El +.Pp +Other +.Dv errno +values may be set depending on the specific database backends. +.Sh SEE ALSO +.Xr getpwent 3 , +.Xr group 5 , +.Xr nsswitch.conf 5 +.Sh STANDARDS +The +.Fn getgrgid +and +.Fn getgrnam +functions conform to +.St -p1003.1-90 . +The +.Fn getgrgid_r +and +.Fn getgrnam_r +functions conform to +.St -p1003.1c-95 . +The +.Fn endgrent , +.Fn getgrent , +and +.Fn setgrent +functions conform to +.St -xpg4.2 +and +.St -p1003.1-2004 +(XSI extension). +.Sh HISTORY +The functions +.Fn endgrent , +.Fn getgrent , +.Fn getgrgid , +.Fn getgrnam , +and +.Fn setgrent +appeared in +.At v7 . +The functions +.Fn setgrfile +and +.Fn setgroupent +appeared in +.Bx 4.3 Reno . +The functions +.Fn getgrgid_r +and +.Fn getgrnam_r +appeared in +.Nx 3.0 . +.Sh BUGS +The functions +.Fn getgrent , +.Fn getgrgid , +.Fn getgrnam , +.Fn setgroupent +and +.Fn setgrent +leave their results in an internal static object and return +a pointer to that object. +Subsequent calls to the same function will modify the same object. +.Pp +The functions +.Fn getgrent , +.Fn endgrent , +.Fn setgroupent , +and +.Fn setgrent +are fairly useless in a networked environment and should be +avoided, if possible. +.Fn getgrent +makes no attempt to suppress duplicate information if multiple +sources are specified in +.Xr nsswitch.conf 5 diff --git a/static/netbsd/man3/getgrouplist.3 b/static/netbsd/man3/getgrouplist.3 new file mode 100644 index 00000000..fe43cd2e --- /dev/null +++ b/static/netbsd/man3/getgrouplist.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: getgrouplist.3,v 1.15 2017/10/24 18:54:03 abhinav Exp $ +.\" +.\" Copyright (c) 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getgrouplist.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd January 6, 2005 +.Dt GETGROUPLIST 3 +.Os +.Sh NAME +.Nm getgrouplist , +.Nm getgroupmembership +.Nd calculate group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getgrouplist "const char *name" "gid_t basegid" "gid_t *groups" "int *ngroups" +.Ft int +.Fn getgroupmembership "const char *name" "gid_t basegid" "gid_t *groups" "int maxgrp" "int *ngroups" +.Sh DESCRIPTION +The +.Fn getgrouplist +and +.Fn getgroupmembership +functions read through the group database and calculate +the group access list for the user specified in +.Fa name . +The +.Fa basegid +is automatically included in the groups list. +Typically this value is given as +the group number from the password database. +.Pp +The resulting group list is returned in the integer array pointed to by +.Fa groups . +.Pp +For +.Fn getgrouplist , +the caller specifies the size of the +.Fa groups +array in the integer pointed to by +.Fa ngroups . +.Pp +For +.Fn getgroupmembership , +the caller specifies the size of the +.Fa groups +array in +.Fa maxgrp . +.Pp +The actual number of groups found is returned in +.Fa ngroups . +.Pp +Duplicate group ids will be suppressed from the result. +.Sh RETURN VALUES +The +.Fn getgrouplist +and +.Fn getgroupmembership +functions +return 0 if successful, and +return \-1 if the size of the group list is too small to +hold all the user's groups. +In the latter case, the +.Fa groups +array will be filled with as many groups as will fit and +.Fa ngroups +will contain the total number of groups found. +.Sh FILES +.Bl -tag -width /etc/group -compact +.It Pa /etc/group +group membership list +.El +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr initgroups 3 , +.Xr group 5 +.Sh HISTORY +The +.Fn getgrouplist +function first appeared in +.Bx 4.4 . +The +.Fn getgroupmembership +function first appeared in +.Nx 3.0 +to address an API deficiency in +.Fn getgrouplist . +.Sh BUGS +The +.Fn getgrouplist +function +uses the routines based on +.Xr getgrent 3 . +If the invoking program uses any of these routines, +the group structure will +be overwritten in the call to +.Fn getgrouplist . diff --git a/static/netbsd/man3/gethostbyname.3 b/static/netbsd/man3/gethostbyname.3 new file mode 100644 index 00000000..2066e63c --- /dev/null +++ b/static/netbsd/man3/gethostbyname.3 @@ -0,0 +1,239 @@ +.\" $NetBSD: gethostbyname.3,v 1.1.1.2 2012/09/09 16:07:45 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: gethostbyname.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd June 23, 1990 +.Dt GETHOSTBYNAME @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm gethostbyname , +.Nm gethostbyaddr , +.Nm gethostent , +.Nm sethostent , +.Nm endhostent , +.Nm herror +.Nd get network host entry +.Sh SYNOPSIS +.Fd #include +.Ft extern int +.Fa h_errno ; +.Pp +.Ft struct hostent * +.Fn gethostbyname "char *name" +.Ft struct hostent * +.Fn gethostbyname2 "char *name" "int af" +.Ft struct hostent * +.Fn gethostbyaddr "char *addr" "int len, type" +.Ft struct hostent * +.Fn gethostent +.Fn sethostent "int stayopen" +.Fn endhostent +.Fn herror "char *string" +.Sh DESCRIPTION +.Fn Gethostbyname , +.Fn gethostbyname2 , +and +.Fn gethostbyaddr +each return a pointer to a +.Ft hostent +structure (see below) describing an internet host +referenced by name or by address, as the function names indicate. +This structure contains either the information obtained from the name server, +or broken-out fields from a line in +.Pa /etc/hosts . +If the local name server is not running, these routines do a lookup in +.Pa /etc/hosts . +.Bd -literal -offset indent +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; + +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width "h_addr_list" +.It h_name +Official name of the host. +.It h_aliases +A zero-terminated array of alternate names for the host. +.It h_addrtype +The type of address being returned; usually +.Dv AF_INET . +.It h_length +The length, in bytes, of the address. +.It h_addr_list +A zero-terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.It h_addr +The first address in +.Li h_addr_list ; +this is for backward compatibility. +.El +.Pp +When using the nameserver, +.Fn gethostbyname +will search for the named host in each parent domain given in the +.Dq Li search +directive of +.Xr resolv.conf @FORMAT_EXT@ +unless the name contains a dot +.Pq Dq \&. . +If the name contains no dot, and if the environment variable +.Ev HOSTALIASES +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.Xr hostname @DESC_EXT@ +for the domain search procedure and the alias file format. +.Pp +.Fn Gethostbyname2 +is an evolution of +.Fn gethostbyname +intended to allow lookups in address families other than +.Dv AF_INET , +for example, +.Dv AF_INET6 . +Currently, the +.Fa af +argument must be specified as +.Dv AF_INET +else the function will return +.Dv NULL +after having set +.Ft h_errno +to +.Dv NETDB_INTERNAL . +.Pp +.Fn Sethostent +may be used to request the use of a connected TCP socket for queries. +If the +.Fa stayopen +flag is non-zero, +this sets the option to send all queries to the name server using TCP +and to retain the connection after each call to +.Fn gethostbyname +or +.Fn gethostbyaddr . +Otherwise, queries are performed using UDP datagrams. +.Pp +.Fn Endhostent +closes the TCP connection. +.Sh ENVIRONMENT +.Bl -tag -width "HOSTALIASES " -compact +.It Ev HOSTALIASES +Name of file containing +.Pq Ar host alias , full hostname +pairs. +.El +.Sh FILES +.Bl -tag -width "HOSTALIASES " -compact +.It Pa /etc/hosts +See +.Xr hosts @FORMAT_EXT@ . +.El +.Sh DIAGNOSTICS +.Pp +Error return status from +.Fn gethostbyname +and +.Fn gethostbyaddr +is indicated by return of a null pointer. +The external integer +.Ft h_errno +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +The routine +.Fn herror +can be used to print an error message describing the failure. +If its argument +.Fa string +is non-NULL, it is printed, followed by a colon and a space. +The error message is printed with a trailing newline. +.Pp +.Ft h_errno +can have the following values: +.Bl -tag -width "HOST_NOT_FOUND " -offset indent +.It Dv NETDB_INTERNAL +This indicates an internal error in the library, unrelated to the network +or name service. +.Ft errno +will be valid in this case; see +.Xr perror @SYSCALL_EXT@ . +.It Dv HOST_NOT_FOUND +No such host is known. +.It Dv TRY_AGAIN +This is usually a temporary error +and means that the local server did not receive +a response from an authoritative server. +A retry at some later time may succeed. +.It Dv NO_RECOVERY +Some unexpected server failure was encountered. +This is a non-recoverable error, as one might expect. +.It Dv NO_DATA +The requested name is valid but does not have an IP address; +this is not a temporary error. +This means that the name is known to the name server but there is no address +associated with this name. +Another type of request to the name server using this domain name +will result in an answer; +for example, a mail-forwarder may be registered for this domain. +.El +.Sh SEE ALSO +.Xr hosts @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr resolver @LIB_NETWORK_EXT@ , +.Xr resolver @FORMAT_EXT@ . +.Sh CAVEAT +.Pp +.Fn Gethostent +is defined, and +.Fn sethostent +and +.Fn endhostent +are redefined, +when +.Pa libc +is built to use only the routines to lookup in +.Pa /etc/hosts +and not the name server: +.Bd -ragged -offset indent +.Pp +.Fn Gethostent +reads the next line of +.Pa /etc/hosts , +opening the file if necessary. +.Pp +.Fn Sethostent +is redefined to open and rewind the file. If the +.Fa stayopen +argument is non-zero, +the hosts data base will not be closed after each call to +.Fn gethostbyname +or +.Fn gethostbyaddr . +.Pp +.Fn Endhostent +is redefined to close the file. +.Ed +.Sh BUGS +All information is contained in a static area so it must be copied if it is +to be saved. Only the Internet address format is currently understood. diff --git a/static/netbsd/man3/gethostid.3 b/static/netbsd/man3/gethostid.3 new file mode 100644 index 00000000..9a5d00e2 --- /dev/null +++ b/static/netbsd/man3/gethostid.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: gethostid.3,v 1.13 2019/03/03 20:34:43 maya Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gethostid.3 8.1 (Berkeley) 6/2/93 +.\" +.Dd March 3, 2019 +.Dt GETHOSTID 3 +.Os +.Sh NAME +.Nm gethostid , +.Nm sethostid +.Nd get/set unique identifier of current host +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn gethostid void +.Ft int +.Fn sethostid "long hostid" +.Sh DESCRIPTION +.Fn sethostid +establishes a 32-bit identifier for the current processor that is +intended to be unique among all +.Ux +systems in existence. +This is normally an Internet address for the local machine. +This call is allowed only to the super-user and is normally performed +at boot time. +.Pp +.Fn gethostid +returns the 32-bit identifier for the current processor. +.Pp +This function has been deprecated. +The hostid should be set or retrieved by use of +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr gethostname 3 , +.Xr sysctl 3 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn gethostid +and +.Fn sethostid +syscalls appeared in +.Bx 4.2 +and were dropped in +.Bx 4.4 . +.Sh BUGS +32 bits for the identifier is too small. diff --git a/static/netbsd/man3/gethostname.3 b/static/netbsd/man3/gethostname.3 new file mode 100644 index 00000000..610b1a8a --- /dev/null +++ b/static/netbsd/man3/gethostname.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: gethostname.3,v 1.18 2015/09/03 04:05:38 jnemeth Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gethostname.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 2, 2015 +.Dt GETHOSTNAME 3 +.Os +.Sh NAME +.Nm gethostname , +.Nm sethostname +.Nd get/set name of current host +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn gethostname "char *name" "size_t namelen" +.Ft int +.Fn sethostname "const char *name" "size_t namelen" +.Sh DESCRIPTION +.Fn gethostname +returns the standard host name for the current machine, as +previously set by +.Fn sethostname . +The parameter +.Fa namelen +specifies the size of the +.Fa name +array. +The returned name is null-terminated unless insufficient +space is provided. +.Pp +.Fn sethostname +sets the name of the host machine to be +.Fa name , +which has length +.Fa namelen . +This call is restricted to the super-user and +is normally used only when the system is bootstrapped. +.Sh RETURN VALUES +If the call succeeds a value of 0 is returned. +If the call fails, a value of \-1 is returned and an error code is +placed in the global location +.Va errno . +.Sh ERRORS +If the +.Fn gethostname +or +.Fn sethostname +functions fail, +they will set +.Va errno +for any of the errors specified for the routine +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr gethostid 3 , +.Xr sysctl 3 , +.Xr sysctl 8 +.Sh STANDARDS +The +.Fn gethostname +function conforms to +.St -xpg4.2 . +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . +.Sh BUGS +Host names are limited to +.Dv MAXHOSTNAMELEN +(from +.Ao Pa sys/param.h Ac ) +characters including null-termination, currently 256. diff --git a/static/netbsd/man3/getifaddrs.3 b/static/netbsd/man3/getifaddrs.3 new file mode 100644 index 00000000..9518a217 --- /dev/null +++ b/static/netbsd/man3/getifaddrs.3 @@ -0,0 +1,207 @@ +.\" $NetBSD: getifaddrs.3,v 1.19 2017/10/25 16:29:20 abhinav Exp $ +.\" BSDI getifaddrs.3,v 2.5 2000/02/23 14:51:59 dab Exp +.\" +.\" Copyright (c) 1995, 1999 +.\" Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd September 15, 2016 +.Dt GETIFADDRS 3 +.Os +.Sh NAME +.Nm getifaddrs , +.Nm freeifaddrs +.Nd get interface addresses +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In ifaddrs.h +.Ft int +.Fn getifaddrs "struct ifaddrs **ifap" +.Ft void +.Fn freeifaddrs "struct ifaddrs *ifp" +.Sh DESCRIPTION +The +.Fn getifaddrs +function stores a reference to a linked list of the network interfaces +on the local machine in the memory referenced by +.Fa ifap . +The list consists of +.Nm ifaddrs +structures, as defined in the include file +.In ifaddrs.h . +The +.Nm ifaddrs +structure contains at least the following entries: +.Bd -literal + struct ifaddrs *ifa_next; /* Pointer to next struct */ + char *ifa_name; /* Interface name */ + unsigned int ifa_flags; /* Interface flags */ + struct sockaddr *ifa_addr; /* Interface address */ + struct sockaddr *ifa_netmask; /* Interface netmask */ + struct sockaddr *ifa_broadaddr; /* Interface broadcast address */ + struct sockaddr *ifa_dstaddr; /* P2P interface destination */ + void *ifa_data; /* Address specific data */ + unsigned int ifa_addrflags; /* Address flags */ +.Ed +.Pp +The +.Li ifa_next +field contains a pointer to the next structure on the list. +This field is +.Dv NULL +in last structure on the list. +.Pp +The +.Li ifa_name +field contains the interface name. +.Pp +The +.Li ifa_flags +field contains the interface flags, as set by +.Xr ifconfig 8 +utility. +.Pp +The +.Li ifa_addr +field references either the address of the interface or the link level +address of the interface, if one exists, otherwise it is +.Dv NULL . +(The +.Li sa_family +field of the +.Li ifa_addr +field should be consulted to determine the format of the +.Li ifa_addr +address.) +.Pp +The +.Li ifa_netmask +field references the netmask associated with +.Li ifa_addr , +if one is set, otherwise it is +.Dv NULL . +.Pp +The +.Li ifa_broadaddr +field, +which should only be referenced for non-P2P interfaces, +references the broadcast address associated with +.Li ifa_addr , +if one exists, otherwise it is +.Dv NULL . +.Pp +The +.Li ifa_dstaddr +field references the destination address on a P2P interface, +if one exists, otherwise it is +.Dv NULL . +.Pp +The +.Li ifa_data +field references address family specific data. +For +.Dv AF_LINK +addresses it contains a pointer to the +.Fa struct if_data +.Pq as defined in include file Aq Pa net/if.h +which contains various interface attributes and statistics. +For all other address families, it is +.Dv NULL . +.Pp +The +.Li ifa_addrflags +field contains the address flags, which are specific to the address family. +.Pp +The data returned by +.Fn getifaddrs +is dynamically allocated and should be freed using +.Fn freeifaddrs +when no longer needed. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh EXAMPLES +The following example program prints a list of all addresses configured +on the system. +.Bd -literal -offset indent +#include +#include +#include +#include +#include +#include +#include + +int +main(int argc, char *argv[]) +{ + struct ifaddrs *ifa, *a; + + if (getifaddrs(&ifa) == -1) + err(EXIT_FAILURE, "getifaddrs"); + + for (a = ifa; a; a = a->ifa_next) { + char buf[1024]; + sockaddr_snprintf(buf, sizeof(buf), "%f %a", + a->ifa_addr); + printf("%s %x %s\\n", a->ifa_name, a->ifa_flags, buf); + } + freeifaddrs(ifa); + return EXIT_SUCCESS; +} +.Ed +.Sh ERRORS +The +.Fn getifaddrs +may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr ioctl 2 , +.Xr socket 2 , +.Xr malloc 3 +or +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr networking 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +implementation first appeared in +.Bsx . +.Pp +.Li ifa_addrflags +was added in +.Nx 8.0 . +.Sh BUGS +If both +.In net/if.h +and +.In ifaddrs.h +are being included, +.In net/if.h +.Em must +be included before +.In ifaddrs.h . diff --git a/static/netbsd/man3/getipnodebyname.3 b/static/netbsd/man3/getipnodebyname.3 new file mode 100644 index 00000000..ab67284c --- /dev/null +++ b/static/netbsd/man3/getipnodebyname.3 @@ -0,0 +1,212 @@ +.\" $NetBSD: getipnodebyname.3,v 1.1.1.2 2012/09/09 16:07:43 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: getipnodebyname.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd September 17, 1999 +.Dt GETIPNODEBYNAME @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm getipnodebyname , +.Nm getipnodebyaddr +.Nd get network host entry +.br +.Nm freehostent +.Nd free network host entry +.Sh SYNOPSIS +.Fd #include +.Pp +.Ft struct hostent * +.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error" +.Ft struct hostent * +.Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error" +.Ft void +.Fn freehostent "struct hostent *he" +.Sh DESCRIPTION +.Fn Getipnodebyname , +and +.Fn getipnodebyaddr +each return a pointer to a +.Ft hostent +structure (see below) describing an internet host +referenced by name or by address, as the function names indicate. +This structure contains either the information obtained from the name server, +or broken-out fields from a line in +.Pa /etc/hosts . +If the local name server is not running, these routines do a lookup in +.Pa /etc/hosts . +.Bd -literal -offset indent +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; + +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width "h_addr_list" +.It h_name +Official name of the host. +.It h_aliases +A zero-terminated array of alternate names for the host. +.It h_addrtype +The type of address being returned. +.It h_length +The length, in bytes, of the address. +.It h_addr_list +A zero-terminated array of network addresses for the host. +Host addresses are returned in network byte order. +.It h_addr +The first address in +.Li h_addr_list ; +this is for backward compatibility. +.El +.Pp +This structure should be freed after use by calling +.Fn freehostent . +.Pp +When using the nameserver, +.Fn getiphostbyaddr +will search for the named host in each parent domain given in the +.Dq Li search +directive of +.Xr resolv.conf @FORMAT_EXT@ +unless the name contains a dot +.Pq Dq \&. . +If the name contains no dot, and if the environment variable +.Ev HOSTALIASES +contains the name of an alias file, the alias file will first be searched +for an alias matching the input name. +See +.Xr hostname @DESC_EXT@ +for the domain search procedure and the alias file format. +.Pp +.Fn Getiphostbyaddr +can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6. +If IPv4 addresses only are to be looked up then +.Fa af +should be set to +.Dv AF_INET , +otherwise it should be set to +.Dv AF_INET6 . +.Pp +There are three flags that can be set +.Bl -tag -width "AI_ADDRCONFIG" +.It Dv AI_V4MAPPED +Return IPv4 addresses if no IPv6 addresses are found. +This flag is ignored unless +.Fa af +is +.Dv AF_INET6 . +.It Dv AI_ALL +Return IPv4 addresses as well IPv6 addresses if +.Dv AI_V4MAPPED +is set. +This flag is ignored unless +.Fa af +is +.Dv AF_INET6 . +.It Dv AI_ADDRCONFIG +Only return addresses of a given type if the system has an active interface +with that type. +.El +.Pp +Also +.Dv AI_DEFAULT +is defined to be +.Dv (AI_V4MAPPED|AI_ADDRCONFIG) . +.Pp +.Fn Getipnodebyaddr +will lookup IPv4 mapped and compatible addresses in the IPv4 name +space and IPv6 name space +.Pp +.Fn Freehostent +frees the hostent structure allocated be +.Fn getipnodebyname +and +.Fn getipnodebyaddr . +The structures returned by +.Fn gethostbyname , +.Fn gethostbyname2 , +.Fn gethostbyaddr +and +.Fn gethostent +should not be passed to +.Fn freehostent +as they are pointers to static areas. +.Sh ENVIRONMENT +.Bl -tag -width "HOSTALIASES " -compact +.It Ev HOSTALIASES +Name of file containing +.Pq Ar host alias , full hostname +pairs. +.El +.Sh FILES +.Bl -tag -width "HOSTALIASES " -compact +.It Pa /etc/hosts +See +.Xr hosts @FORMAT_EXT@ . +.El +.Sh DIAGNOSTICS +.Pp +Error return status from +.Fn getipnodebyname +and +.Fn getipnodebyaddr +is indicated by return of a null pointer. +In this case +.Ft error +may then be checked to see whether this is a temporary failure +or an invalid or unknown host. +.Ft errno +can have the following values: +.Bl -tag -width "HOST_NOT_FOUND " -offset indent +.It Dv NETDB_INTERNAL +This indicates an internal error in the library, unrelated to the network +or name service. +.Ft errno +will be valid in this case; see +.Xr perror @SYSCALL_EXT@ . +.It Dv HOST_NOT_FOUND +No such host is known. +.It Dv TRY_AGAIN +This is usually a temporary error +and means that the local server did not receive +a response from an authoritative server. +A retry at some later time may succeed. +.It Dv NO_RECOVERY +Some unexpected server failure was encountered. +This is a non-recoverable error, as one might expect. +.It Dv NO_ADDRESS +The requested name is valid but does not have an IP address; +this is not a temporary error. +This means that the name is known to the name server but there is no address +associated with this name. +Another type of request to the name server using this domain name +will result in an answer; +for example, a mail-forwarder may be registered for this domain. +.El +.Sh SEE ALSO +.Xr hosts @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr resolver @LIB_NETWORK_EXT@ , +.Xr resolver @FORMAT_EXT@ , +.Xr gethostbyname @LIB_NETWORK_EXT@ , +.Xr RFC2553 . diff --git a/static/netbsd/man3/getlabelsector.3 b/static/netbsd/man3/getlabelsector.3 new file mode 100644 index 00000000..ed2a722c --- /dev/null +++ b/static/netbsd/man3/getlabelsector.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: getlabelsector.3,v 1.8 2011/09/14 11:43:29 njoly Exp $ +.\" +.\" +.\" Copyright 2002 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Steve C. Woodford for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 25, 2011 +.Dt GETLABELSECTOR 3 +.Os +.Sh NAME +.Nm getlabelsector , +.Nm getlabeloffset , +.Nm getlabelusesmbr +.Nd get disklabel location informations +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft daddr_t +.Fn getlabelsector void +.Ft off_t +.Fn getlabeloffset void +.Ft int +.Fn getlabelusesmbr void +.Sh DESCRIPTION +The +.Fn getlabelsector +and +.Fn getlabeloffset +functions return values which describe the exact on-disk location of the +.Xr disklabel 5 +on the current system, or \-1 on error. +These functions supersede the hardcoded +.Dv LABELSECTOR +and +.Dv LABELOFFSET +definitions previously used to derive the location of the +.Xr disklabel 5 . +.Pp +The +.Fn getlabelusesmbr +returns 1 if the disklabel is located inside a MBR partition, 0 if it's stored +relative to the start of the disk, or \-1 on error. +.Sh SEE ALSO +.Xr sysctl 3 , +.Xr disklabel 5 +.Sh HISTORY +The +.Fn getlabelsector +and +.Fn getlabeloffset +functions appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/getlastlogx.3 b/static/netbsd/man3/getlastlogx.3 new file mode 100644 index 00000000..cb7404c3 --- /dev/null +++ b/static/netbsd/man3/getlastlogx.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: getlastlogx.3,v 1.2 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 26, 2003 +.Dt GETLASTLOGX 3 +.Os +.Sh NAME +.Nm getlastlogx , +.Nm getutmp , +.Nm getutmpx , +.Nm updlastlogx , +.Nm updwtmpx , +.Nm utmpxname +.Nd user accounting database functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In utmpx.h +.Ft struct lastlogx * +.Fn getlastlogx "const char *fname" "uid_t uid" "struct lastlogx *ll" +.Ft void +.Fn getutmp "const struct utmpx *ux" "struct utmp *u" +.Ft void +.Fn getutmpx "const struct utmp *u" "struct utmpx *ux" +.Ft int +.Fn updlastlogx "const char *fname" "uid_t uid" "struct lastlogx *ll" +.Ft int +.Fn updwtmpx "const char *file" "const struct utmpx *utx" +.Ft int +.Fn utmpxname "const char *fname" +.Sh DESCRIPTION +The +.Fn getlastlogx +function looks up the entry for the user with user id +.Fa uid +in the +.Xr lastlogx 5 +file given by +.Fa fname +and returns it in +.Fa \&ll . +If the provided +.Fa \&ll +is +.Dv NULL , +the necessary space will be allocated by +.Fn getlastlogx +and should be +.Fn free Ns d +by the caller. +.Pp +The +.Fn getutmp +function fills out the entries in the struct utmp +.Fa u +with the data provided in the struct utmpx +.Fa ux . +.Fn getutmpx +does the opposite, filling out the entries in the struct utmpx +.Fa ux +with the data provided in the struct utmp +.Fa u , +and initializing all the unknown fields to 0. +The sole exception is the +.Fa ut_type +field, which will be initialized to +.Dv USER_PROCESS . +.Pp +The +.Fn updlastlogx +function tries to update the information for the user with the user id +.Fa uid +in the +.Xr lastlogx 5 +file given by +.Fa fname +with the data supplied in +.Fa \&ll . +A +.Ft struct lastlogx +is defined like this: +.Bd -literal +struct lastlogx { + struct timeval ll_tv; /* time entry was created */ + char ll_line[_UTX_LINESIZE]; /* tty name */ + char ll_host[_UTX_HOSTSIZE]; /* host name */ + struct sockaddr_storage ll_ss; /* address where entry was made from */ +}; +.Ed +All the fields should be filled out by the caller. +.Pp +The +.Fn updwtmpx +function updates the +.Xr wtmpx 5 +file +.Fa file +with the +.Xr utmpx 5 +entry +.Fa utx . +.Pp +The +.Fn utmpxname +function sets the default +.Xr utmpx 5 +database file name to +.Fa fname . +.Sh RETURN VALUES +.Fn getlastlogx +returns the found entry on success, or +.Dv NULL +if it could not open the database, could not find an entry matching +.Fa uid +in there, or could not allocate the necessary space (in case +.Fa \&ll +was +.Dv NULL ) . +.Pp +.Fn utmpxname +returns 1 on success, or 0 if the supplied file name was too long or +did not end with +.Sq x . +.Pp +.Fn updlastlogx +and +.Fn updwtmpx +return 0 on success, or \-1 in case the database or file respectively +could not be opened or the data not written into it. +.Sh SEE ALSO +.Xr endutxent 3 , +.Xr loginx 3 , +.Xr utmpx 5 +.Sh HISTORY +The functions +.Fn getutmp , +.Fn getutmpx , +.Fn updwtmpx , +and +.Fn utmpxname +first appeared in +.Tn Solaris . +.Nm getlastlogx +and +.Nm updlastlogx +first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/getloadavg.3 b/static/netbsd/man3/getloadavg.3 new file mode 100644 index 00000000..7f879b00 --- /dev/null +++ b/static/netbsd/man3/getloadavg.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: getloadavg.3,v 1.15 2011/04/12 04:55:05 jruoho Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 12, 2011 +.Dt GETLOADAVG 3 +.Os +.Sh NAME +.Nm getloadavg +.Nd get system load averages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn getloadavg "double loadavg[]" "int nelem" +.Sh DESCRIPTION +The +.Fn getloadavg +function returns the number of processes in the system run queue +averaged over various periods of time. +Up to +.Fa nelem +samples are retrieved and assigned to successive elements of +.Fa loadavg Ns Bq . +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +.Sh RETURN VALUES +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.Sh SEE ALSO +.Xr uptime 1 , +.Xr kvm_getloadavg 3 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn getloadavg +function appeared in +.Bx 4.3 Reno . diff --git a/static/netbsd/man3/getmaxpartitions.3 b/static/netbsd/man3/getmaxpartitions.3 new file mode 100644 index 00000000..9a439e25 --- /dev/null +++ b/static/netbsd/man3/getmaxpartitions.3 @@ -0,0 +1,59 @@ +.\" $NetBSD: getmaxpartitions.3,v 1.10 2010/05/04 06:41:27 jruoho Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt GETMAXPARTITIONS 3 +.Os +.Sh NAME +.Nm getmaxpartitions +.Nd get the maximum number of partitions allowed per disk +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn getmaxpartitions void +.Sh DESCRIPTION +.Fn getmaxpartitions +returns the number of partitions that are allowed per disk on the +system, or \-1 in case of an error, setting the global +.Va errno +variable. +The possible values for +.Va errno +are the same as in +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr getrawpartition 3 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn getmaxpartitions +function call appeared in +.Nx 1.2 . diff --git a/static/netbsd/man3/getmntinfo.3 b/static/netbsd/man3/getmntinfo.3 new file mode 100644 index 00000000..28e031b6 --- /dev/null +++ b/static/netbsd/man3/getmntinfo.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: getmntinfo.3,v 1.16 2016/06/12 09:42:41 abhinav Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getmntinfo.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd June 2, 2016 +.Dt GETMNTINFO 3 +.Os +.Sh NAME +.Nm getmntinfo +.Nd get information about mounted file systems +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/statvfs.h +.Ft int +.Fn getmntinfo "struct statvfs **mntbufp" "int flags" +.Sh DESCRIPTION +The +.Fn getmntinfo +function returns an array of +.Em statvfs +structures describing each currently mounted file system (see +.Xr statvfs 2 ) . +.Pp +The +.Fn getmntinfo +function +passes its +.Fa flags +parameter transparently to +.Xr getvfsstat 2 . +.Sh RETURN VALUES +On successful completion, +.Fn getmntinfo +returns a count of the number of elements in the array. +The pointer to the array is stored into +.Fa mntbufp . +.Pp +If an error occurs, zero is returned and the external variable +.Va errno +is set to indicate the error. +Although the pointer +.Fa mntbufp +will be unmodified, any information previously returned by +.Fn getmntinfo +will be lost. +.Sh ERRORS +The +.Fn getmntinfo +function +may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr getvfsstat 2 +or +.Xr malloc 3 . +.Sh SEE ALSO +.Xr getvfsstat 2 , +.Xr mount 2 , +.Xr statvfs 2 , +.Xr mount 8 +.Sh HISTORY +The +.Fn getmntinfo +function first appeared in +.Bx 4.4 . +It was converted from using +.Fn getfsstat +to +.Xr getvfsstat 2 +in +.Nx 3.0 . +.Sh BUGS +The +.Fn getmntinfo +function writes the array of structures to an internal static object +and returns +a pointer to that object. +Subsequent calls to +.Fn getmntinfo +will modify the same object. +.Pp +The memory allocated by +.Fn getmntinfo +cannot be +.Xr free 3 Ns 'd +by the application. diff --git a/static/netbsd/man3/getmntopts.3 b/static/netbsd/man3/getmntopts.3 new file mode 100644 index 00000000..5e0f67ae --- /dev/null +++ b/static/netbsd/man3/getmntopts.3 @@ -0,0 +1,280 @@ +.\" $NetBSD: getmntopts.3,v 1.15 2022/12/04 01:29:33 uwe Exp $ +.\" +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getmntopts.3 8.3 (Berkeley) 3/30/95 +.\" +.Dd May 4, 2010 +.Dt GETMNTOPTS 3 +.Os +.Sh NAME +.Nm getmntopts , +.Nm getmntoptstr , +.Nm getmntoptnum , +.Nm freemntopts +.Nd scan mount options +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In mntopts.h +.Ft mntoptparse_t +.Fn getmntopts "const char *options" "const struct mntopt *mopts" "int *flagp" "int *altflagp" +.Ft const char * +.Fn getmntoptstr "mntoptparse_t mp" "const char *opt" +.Ft long +.Fn getmntoptnum "mntoptparse_t mp" "const char *opt" +.Ft void +.Fn freemntopts "mntoptparse_t mp" +.Sh DESCRIPTION +The +.Fn getmntopts +function takes a comma separated option list and a list +of valid option names, and computes the bitmasks +corresponding to the requested set of options. +.Pp +The string +.Ar options +is broken down into a sequence of comma separated tokens. +Each token is looked up in the table described by +.Ar mopts +and the bits in +the word referenced by either +.Ar flagp +or +.Ar altflagp +(depending on the +.Dv m_altloc +field of the option's table entry) +are updated. +The flag words are not initialized by +.Fn getmntopts . +The table, +.Ar mopts , +has the following format: +.Bd -literal +struct mntopt { + const char *m_option; /* option name */ + int m_inverse; /* negative option, e.g., "dev" */ + int m_flag; /* bit to set, e.g., MNT_RDONLY */ + int m_altloc; /* use altflagp rather than flagp */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width m_inverse +.It Fa m_option +the option name, +for example +.Dq suid . +.It Fa m_inverse +tells +.Fn getmntopts +that the name has the inverse meaning of the bit. +For example, +.Dq suid +is the string, whereas the mount flag is +.Dv MNT_NOSUID . +In this case, the sense of the string and the flag +are inverted, so the +.Fa m_inverse +flag should be set. +.It Fa m_flag +the value of the bit to be set or cleared in +the flag word when the option is recognized. +The bit is set when the option is discovered, +but cleared if the option name was preceded +by the letters +.Dq no . +The +.Fa m_inverse +flag causes these two operations to be reversed. +.It Fa m_altloc +the bit should be set or cleared in +.Ar altflagp +rather than +.Ar flagp . +.El +.Pp +Each of the user visible +.Dv MNT_ +flags has a corresponding +.Dv MOPT_ +macro which defines an appropriate +.Li "struct mntopt" +entry. +To simplify the program interface and ensure consistency across all +programs, a general purpose macro, +.Dv MOPT_STDOPTS , +is defined which contains an entry for all the generic VFS options. +In addition, the macros +.Dv MOPT_FORCE +and +.Dv MOPT_UPDATE +exist to enable the +.Dv MNT_FORCE +and +.Dv MNT_UPDATE +flags to be set. +Finally, the table must be terminated by an entry with a +.Dv NULL +first element. +.Pp +.Fn getmntopts +returns a +.Li "mntoptparse_t" +handle that can be used in subsequent +.Fn getmntoptstr +and +.Fn getmntoptnum +calls to fetch a value for an option and that must be freed with a call +to +.Fn freemntopts . +If an error occurred, then if the external integer value +.Va getmnt_silent +is zero then +.Fn getmntopts +prints an error message and exits; +if +.Va getmnt_silent +is non-zero then +.Fn getmntopts +returns +.Dv NULL . +.Pp +The +.Fn getmntoptstr +function returns the string value of the named option, if such a value +was set in the option string. +If the value was not set, then if the external integer value +.Va getmnt_silent +is zero then +.Fn getmntoptstr +prints an error message and exits; +if +.Va getmnt_silent +is non-zero then +.Fn getmntoptstr +returns +.Dv NULL . +.Pp +The +.Fn getmntoptnum +function returns the long value of the named option, if such a value was set in the +option string. +If the value was not set, or could not be converted from a string to a +long, then if the external integer value +.Va getmnt_silent +is zero then +.Fn getmntoptnum +prints an error message and exits; +if +.Va getmnt_silent +is non-zero then +.Fn getmntoptnum +returns \-1. +.Pp +The +.Fn freemntopts +function frees the storage used by +.Fn getmntopts . +.Sh RETURN VALUES +.Fn getmntopts +returns +.Dv NULL +if an error occurred. +Note that some bits may already have been set in +.Va flagp +and +.Va altflagp +even if +.Dv NULL +is returned. +.Fn getmntoptstr +returns +.Dv NULL +if an error occurred. +.Fn getmntoptnum +returns \-1 if an error occurred. +.Sh EXAMPLES +Most commands will use the standard option set. +Local filesystems which support the +.Dv MNT_UPDATE +flag, would also have an +.Dv MOPT_UPDATE +entry. +This can be declared and used as follows: +.Bd -literal -offset indent +#include + +static const struct mntopt mopts[] = { + MOPT_STDOPTS, + MOPT_UPDATE, + { NULL } +}; + +\&... + +long val; +mntoptparse_t mp; +mntflags = mntaltflags = 0; + +\&... + +mp = getmntopts(options, mopts, &mntflags, &mntaltflags); + +if (mp == NULL) + err(EXIT_FAILURE, "getmntopts"); + +\&... + +val = getmntoptnum(mp, "rsize"); +freemntopts(mp); +.Ed +.Sh RETURN VALUES +If the external integer variable +.Va getmnt_silent +is zero then the +.Fn getmntopts , +.Fn getmntoptstr , +and +.Fn getmntoptnum +functions display an error message and exit if an error occurred. +By default +.Va getmnt_silent +is zero. +.Sh SEE ALSO +.Xr err 3 , +.Xr mount 8 +.Sh HISTORY +The +.Fn getmntopts +function appeared in +.Bx 4.4 . +It was moved to the utilities library and enhanced to retrieve option +values in +.Nx 2.0 . diff --git a/static/netbsd/man3/getnameinfo.3 b/static/netbsd/man3/getnameinfo.3 new file mode 100644 index 00000000..e11c1838 --- /dev/null +++ b/static/netbsd/man3/getnameinfo.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: getnameinfo.3,v 1.1.1.2 2012/09/09 16:07:45 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: getnameinfo.3,v 1.4 2009/02/21 01:31:39 jreed Exp +.\" +.Dd January 11, 1999 +.Dt GETNAMEINFO @LIB_NETWORK_EXT@ +.Sh NAME +.Nm getnameinfo +.Nd address-to-name translation in protocol-independent manner +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft int +.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ +"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" +.Sh DESCRIPTION +The +.Fn getnameinfo +function is defined for protocol-independent address-to-nodename translation. +It performs functionality of +.Xr gethostbyaddr @LIB_NETWORK_EXT@ +and +.Xr getservbyport @LIB_NETWORK_EXT@ +in more sophisticated manner. +.Pp +The +.Fa sa +arguement is a pointer to a generic socket address structure of size +.Fa salen . +The arguements +.Fa host +and +.Fa serv +are pointers to buffers to hold the return values. +Their sizes are specified by +.Fa hostlen +and +.Fa servlen +repectively. +Either +.Fa host +or +.Fa serv +may be +.Dv NULL +if the hostname or service name is not required. +.Pp +The +.Fa flags +arguement modifies the behaviour of +.Fn getnameinfo +as follows: +.Pp +If +.Dv NI_NOFQDN +is set only the unqualified hostname is returned for local fully +qualified names. +.Pp +If +.Dv NI_NUMERICHOST +is set then the numeric form of the hostname is returned. +.Pp +If +.Dv NI_NAMEREQD +is set, then a error is returned if the hostname cannot be looked up. +.Pp +If +.Dv NI_NUMERICSERV +is set then the service is returned in numeric form. +.Pp +If +.Dv NI_DGRAM +is set then the service is UDP based rather than TCP based. +.Sh SEE ALSO +.Xr getaddrinfo @LIB_NETWORK_EXT@ , +.Xr gethostbyaddr @LIB_NETWORK_EXT@ , +.Xr getservbyport @LIB_NETWORK_EXT@ , +.Xr hosts @FORMAT_EXT@ , +.Xr services @FORMAT_EXT@ , +.Xr hostname @DESC_EXT@ , +.Pp +R. Gilligan, S. Thomson, J. Bound, and W. Stevens, +``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined IEEE POSIX 1003.1g draft specification, +and documented in ``Basic Socket Interface Extensions for IPv6'' +(RFC2133). diff --git a/static/netbsd/man3/getnetconfig.3 b/static/netbsd/man3/getnetconfig.3 new file mode 100644 index 00000000..cd3c30e4 --- /dev/null +++ b/static/netbsd/man3/getnetconfig.3 @@ -0,0 +1,183 @@ +.\" @(#)getnetconfig.3n 1.28 93/06/02 SMI; from SVr4 +.\" $NetBSD: getnetconfig.3,v 1.7 2003/04/16 13:34:43 wiz Exp $ +.\" Copyright 1989 AT&T +.Dd April 22, 2000 +.Dt GETNETCONFIG 3 +.Os +.Sh NAME +.Nm getnetconfig , +.Nm setnetconfig , +.Nm endnetconfig , +.Nm getnetconfigent , +.Nm freenetconfigent , +.Nm nc_perror , +.Nm nc_sperror +.Nd get network configuration database entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netconfig.h +.Ft struct netconfig * +.Fn getnetconfig "void *handlep" +.Ft void * +.Fn setnetconfig "void" +.Ft int +.Fn endnetconfig "void *handlep" +.Ft struct netconfig * +.Fn getnetconfigent "const char *netid" +.Ft void +.Fn freenetconfigent "struct netconfig *netconfigp" +.Ft void +.Fn nc_perror "const char *msg" +.Ft char * +.Fn nc_sperror "void" +.Sh DESCRIPTION +The library routines described on this page +provide the application access to +the system network configuration database, +.Pa /etc/netconfig . +.Bd -literal +struct netconfig { + char *nc_netid; /* Network ID */ + unsigned long nc_semantics; /* Semantics */ + unsigned long nc_flag; /* Flags */ + char *nc_protofmly; /* Protocol family */ + char *nc_proto; /* Protocol name */ + char *nc_device; /* Network device pathname */ + unsigned long nc_nlookups; /* Number of directory lookup libs */ + char **nc_lookups; /* Names of the libraries */ +}; +.Ed +.Pp +.Fn getnetconfig +returns a pointer to the +current entry in the +.Pa netconfig +database, formatted as a struct netconfig. +Successive calls will return successive netconfig +entries in the netconfig database. +.Fn getnetconfig +can be used to search the entire netconfig +file. +.Fn getnetconfig +returns +.Dv NULL +at the end of the file. +.Fa handlep +is the handle obtained through +.Fn setnetconfig . +.Pp +A call to +.Fn setnetconfig +has the effect of ``binding'' to or +``rewinding'' the netconfig database. +.Fn setnetconfig +must be called before the first call to +.Fn getnetconfig +and may be called at any other time. +.Fn setnetconfig +need not be called before a call to +.Fn getnetconfigent . +.Fn setnetconfig +returns a unique handle to be used by +.Fn getnetconfig . +.Pp +.Fn endnetconfig +should be called when processing is complete to release resources for reuse. +.Fa handlep +is the handle obtained through +.Fn setnetconfig . +Programmers should be aware, however, that the last call to +.Fn endnetconfig +frees all memory allocated by +.Fn getnetconfig +for the +struct netconfig data structure. +.Fn endnetconfig +may not be called before +.Fn setnetconfig . +.Pp +.Fn getnetconfigent +returns a pointer +to the netconfig structure corresponding +to +.Fa netid . +It returns +.Dv NULL +if +.Fa netid +is invalid +(that is, does not name an entry in the netconfig database). +.Pp +.Fn freenetconfigent +frees the netconfig structure pointed to by +.Fa netconfigp +(previously returned by +.Fn getnetconfigent ) . +.Pp +.Fn nc_perror +prints a message to the standard error indicating why any of the +above routines failed. +The message is prepended with the string +.Fa msg +and a colon. +A newline character is appended at the end of the message. +.Pp +.Fn nc_sperror +is similar to +.Fn nc_perror +but instead of sending the message +to the standard error, will return a pointer to a string that +contains the error message. +.Pp +.Fn nc_perror +and +.Fn nc_sperror +can also be used with the +.Va NETPATH +access routines defined in +.Xr getnetpath 3 . +.Sh RETURN VALUES +.Fn setnetconfig +returns a unique handle to be used by +.Fn getnetconfig . +In the case of an error, +.Fn setnetconfig +returns NULL and +.Fn nc_perror +or +.Fn nc_sperror +can be used to print the reason for failure. +.Pp +.Fn getnetconfig +returns a pointer to the current entry in the netconfig +database, formatted as a struct netconfig. +.Fn getnetconfig +returns NULL +at the end of the file, or upon failure. +.Pp +.Fn endnetconfig +returns 0 on success and -1 on failure +(for example, if +.Fn setnetconfig +was not called previously). +.Pp +On success, +.Fn getnetconfigent +returns a pointer to the +.Li struct netconfig +structure corresponding to +.Ar netid ; +otherwise it returns +.Dv NULL . +.Pp +.Fn nc_sperror +returns a pointer to a buffer which contains the error message string. +This buffer is overwritten on each call. +In multithreaded applications, this buffer is +implemented as thread-specific data. +.Sh FILES +.Pa /etc/netconfig +.Sh SEE ALSO +.Xr getnetpath 3 , +.Xr netconfig 5 diff --git a/static/netbsd/man3/getnetent.3 b/static/netbsd/man3/getnetent.3 new file mode 100644 index 00000000..de344010 --- /dev/null +++ b/static/netbsd/man3/getnetent.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: getnetent.3,v 1.1.1.2 2012/09/09 16:07:43 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: getnetent.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd May 20, 1996 +.Dt GETNETENT @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm getnetent , +.Nm getnetbyaddr , +.Nm getnetbyname , +.Nm setnetent , +.Nm endnetent +.Nd get networks entry +.Sh SYNOPSIS +.Fd #include +.Ft struct netent * +.Fn getnetent +.Ft struct netent * +.Fn getnetbyname "char name" +.Ft struct netent * +.Fn getnetbyaddr "unsigned long net" "int type" +.Ft void +.Fn setnetent "int stayopen" +.Ft void +.Fn endnetent +.Sh DESCRIPTION +The +.Fn getnetent , +.Fn getnetbyname , +and +.Fn getnetbyaddr +subroutines +each return a pointer to an object with the following structure +containing the broken-out fields of a line in the +.Pa networks +database. +.Bd -literal -offset indent +struct netent { + char *n_name; /* official name of net */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net number type */ + long n_net; /* net number */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width "n_addrtype" +.It n_name +The official name of the network. +.It n_aliases +A zero-terminated list of alternate names for the network. +.It n_addrtype +The type of the network number returned: +.Dv AF_INET . +.It n_net +The network number. Network numbers are returned in machine byte +order. +.El +.Pp +If the +.Fa stayopen +flag on a +.Fn setnetent +subroutine is NULL, the +.Pa networks +database is opened. Otherwise, the +.Fn setnetent +has the effect of rewinding the +.Pa networks +database. +The +.Fn endnetent +subroutine may be called to +close the +.Pa networks +database when processing is complete. +.Pp +The +.Fn getnetent +subroutine simply reads the next +line while +.Fn getnetbyname +and +.Fn getnetbyaddr +search until a matching +.Fa name +or +.Fa net +number is found +(or until +.Dv EOF +is encountered). The +.Fa type must be +.Dv AF_INET . +The +.Fn getnetent +subroutine keeps a pointer in the database, allowing +successive calls to be used to search the entire file. +.Pp +Before a +.Ic while +loop using +.Fn getnetent , +a call to +.Fn setnetent +must be made +in order to perform initialization; a call to +.Fn endnetent +must be used after the loop. Both +.Fn getnetbyname +and +.Fn getnetbyaddr +make calls to +.Fn setnetent +and +.Fn endnetent . +.Sh FILES +.Pa /etc/networks +.Sh DIAGNOSTICS +Null pointer (0) returned on +.Dv EOF +or error. +.Sh SEE ALSO +.Xr networks @FORMAT_EXT@ , +RFC 1101. +.Sh HISTORY +The +.Fn "getnetent" , +.Fn "getnetbyaddr" , +.Fn "getnetbyname" , +.Fn "setnetent" , +and +.Fn "endnetent" +functions appeared in +.Bx 4.2 . +.Sh BUGS +The data space used by these functions is static; if future use requires the +data, it should be copied before any subsequent calls to these functions +overwrite it. Only Internet network numbers are currently understood. +Expecting network numbers to fit in no more than 32 bits is probably naive. diff --git a/static/netbsd/man3/getnetgrent.3 b/static/netbsd/man3/getnetgrent.3 new file mode 100644 index 00000000..7e456937 --- /dev/null +++ b/static/netbsd/man3/getnetgrent.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: getnetgrent.3,v 1.12 2003/08/07 16:42:50 agc Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getnetgrent.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd January 16, 1999 +.Dt GETNETGRENT 3 +.Os +.Sh NAME +.Nm getnetgrent , +.Nm innetgr , +.Nm setnetgrent , +.Nm endnetgrent +.Nd netgroup database operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netgroup.h +.Ft int +.Fn getnetgrent "const char **host" "const char **user" "const char **domain" +.Ft int +.Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain" +.Ft void +.Fn setnetgrent "const char *netgroup" +.Ft void +.Fn endnetgrent void +.Sh DESCRIPTION +These functions operate on the netgroup database file which is described in +.Xr netgroup 5 . +.Pp +The database defines a set of netgroups, each made up of one or more triples: +.Bd -literal -offset indent +(host, user, domain) +.Ed +.Pp +that defines a combination of host, user and domain. +Any of the three fields may be specified as ``wildcards'' that match any +string. +.Pp +The function +.Fn getnetgrent +sets the three pointer arguments to the strings of the next member of the +current netgroup. +If any of the string pointers are +.Dv NULL +that field is considered a wildcard. +.Pp +The functions +.Fn setnetgrent +and +.Fn endnetgrent +set the current netgroup and terminate the current netgroup respectively. +If +.Fn setnetgrent +is called with a different netgroup than the previous call, an implicit +.Fn endnetgrent +is implied. +.Fn setnetgrent +also sets the offset to the first member of the netgroup. +.Pp +The function +.Fn innetgr +searches for a match of all fields within the specified group. +If any of the +.Sy host , +.Sy user , +or +.Sy domain +arguments are +.Dv NULL +those fields will match any string value in the netgroup member. +.Sh RETURN VALUES +The function +.Fn getnetgrent +returns 0 for ``no more netgroup members'' and 1 otherwise. +The function +.Fn innetgr +returns 1 for a successful match and 0 otherwise. +The functions +.Fn setnetgrent +and +.Fn endnetgrent +have no return value. +.Sh FILES +.Bl -tag -width /etc/netgroup -compact +.It Pa /etc/netgroup +netgroup database file +.El +.Sh SEE ALSO +.Xr netgroup 5 , +.Xr nsswitch.conf 5 +.Sh BUGS +The function +.Fn getnetgrent +returns pointers to dynamically allocated data areas that are free'd when +the function +.Fn endnetgrent +is called. diff --git a/static/netbsd/man3/getnetpath.3 b/static/netbsd/man3/getnetpath.3 new file mode 100644 index 00000000..f2283e3b --- /dev/null +++ b/static/netbsd/man3/getnetpath.3 @@ -0,0 +1,155 @@ +.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4 +.\" $NetBSD: getnetpath.3,v 1.7 2022/12/04 23:02:57 uwe Exp $ +.\" Copyright 1989 AT&T +.Dd April 22, 2000 +.Dt GETNETPATH 3 +.Os +.Sh NAME +.Nm getnetpath , +.Nm setnetpath , +.Nm endnetpath +.Nd get /etc/netconfig entry corresponding to NETPATH component +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netconfig.h +.Ft struct netconfig * +.Fn getnetpath "void *handlep" +.Ft void * +.Fn setnetpath "void" +.Ft int +.Fn endnetpath "void *handlep" +.Sh DESCRIPTION +The routines described in this page provide the application access to the system +network configuration database, +.Pa /etc/netconfig , +as it is +.Dq filtered +by the +.Ev NETPATH +environment variable +.Po see +.Xr environ 7 +.Pc . +See +.Xr getnetconfig 3 +for other routines that also access the +network configuration database directly. +The +.Ev NETPATH +variable is a list of colon-separated network identifiers. +.Pp +.Fn getnetpath +returns a pointer to the +netconfig database entry corresponding to the first valid +.Ev NETPATH +component. +The netconfig entry is formatted as a +.Vt struct netconfig . +On each subsequent call, +.Fn getnetpath +returns a pointer to the netconfig entry that corresponds to the next +valid +.Ev NETPATH +component. +.Fn getnetpath +can thus be used to search the netconfig database for all networks +included in the +.Ev NETPATH +variable. +When +.Ev NETPATH +has been exhausted, +.Fn getnetpath +returns +.Dv NULL . +.Pp +A call to +.Fn setnetpath +.Dq binds +to or +.Dq rewinds +.Ev NETPATH . +.Fn setnetpath +must be called before the first call to +.Fn getnetpath +and may be called at any other time. +It returns a handle that is used by +.Fn getnetpath . +.Pp +.Fn getnetpath +silently ignores invalid +.Ev NETPATH +components. +A +.Ev NETPATH +component is invalid if there is no corresponding +entry in the netconfig database. +.Pp +If the +.Ev NETPATH +variable is unset, +.Fn getnetpath +behaves as if +.Ev NETPATH +were set to the sequence of +.Dq default +or +.Dq visible +networks in the netconfig database, in the +order in which they are listed. +.\"This proviso holds also for this +.\"whole manpage. +.Pp +.Fn endnetpath +may be called to +.Dq unbind +from +.Ev NETPATH +when processing is complete, releasing resources for reuse. +Programmers should be aware, however, that +.Fn endnetpath +frees all memory allocated by +.Fn getnetpath +for the +.Vt struct netconfig +data structure. +.Sh RETURN VALUES +.Fn setnetpath +returns a handle that is used by +.Fn getnetpath . +In case of an error, +.Fn setnetpath +returns +.Dv NULL . +.Pp +.Fn endnetpath +returns 0 on success and \-1 on failure +.Po +for example, if +.Fn setnetpath +was not called previously +.Pc . +.Fn nc_perror +or +.Fn nc_sperror +can be used to print out the reason for failure. +See +.Xr getnetconfig 3 . +.Pp +When first called, +.Fn getnetpath +returns a pointer to the netconfig database entry corresponding to the first +valid +.Ev NETPATH +component. +When +.Ev NETPATH +has been exhausted, +.Fn getnetpath +returns +.Dv NULL . +.Sh SEE ALSO +.Xr getnetconfig 3 , +.Xr netconfig 5 , +.Xr environ 7 diff --git a/static/netbsd/man3/getopt.3 b/static/netbsd/man3/getopt.3 new file mode 100644 index 00000000..28dbfa65 --- /dev/null +++ b/static/netbsd/man3/getopt.3 @@ -0,0 +1,329 @@ +.\" $NetBSD: getopt.3,v 1.37 2025/12/11 14:07:23 uwe Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 +.\" +.Dd June 5, 2014 +.Dt GETOPT 3 +.Os +.Sh NAME +.Nm getopt +.Nd get option character from command line argument list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Vt extern char *optarg; +.Vt extern int optind; +.Vt extern int optopt; +.Vt extern int opterr; +.Vt extern int optreset; +.Ft int +.Fn getopt "int argc" "char * const argv[]" "const char *optstring" +.Sh DESCRIPTION +The +.Fn getopt +function incrementally parses a command line argument list +.Fa argv +and returns the next +.Em known +option character. +An option character is +.Em known +if it has been specified in the string of accepted option characters, +.Fa optstring . +.Pp +The option string +.Fa optstring +may contain the following elements: individual characters, and +characters followed by a colon +.Pq Ql \&: +to indicate an option argument is to follow. +If an individual character is followed by two colons +.Pq Ql \&:: , +then the option argument is optional; +.Va optarg +is set to the rest of the current +.Fa argv +word, or +.Dv NULL +if there were no more characters in the current word. +This is an extension not covered by POSIX. +.Pp +For example, an option string +.Li \*qx\*q +recognizes an option +.Dq Fl x . +.Pp +An option string +.Li \*qx:\*q +recognizes an option with an argument, both +.Dq Fl x Ns Ar arg\^ , +and +.Dq Fl x Ar arg\^ . +It does not matter to +.Fn getopt +if the option's argument is a separate word or not. +.Pp +An option string +.Li \*qx::\*q +recognizes the option both without an argument +.Dq Fl x , +and with an argument +.Dq Fl x Ns Ar arg\^ . +In the latter case the argument must be part of the same +.Fa argv +word. +The +.Dq Fl x +and +.Dq Ar arg\^ +must not be separated by a whitespace on the command line. +.Pp +On return from +.Fn getopt , +.Va optarg +points to an option argument, if it is anticipated, +and the variable +.Va optind +contains the index to the next +.Fa argv +argument for a subsequent call +to +.Fn getopt . +The variable +.Va optopt +saves the last +.Em known +option character returned by +.Fn getopt . +.Pp +The variables +.Va opterr +and +.Va optind +are both initialized to 1. +The +.Va optind +variable may be set to another value before a set of calls to +.Fn getopt +in order to skip over more or less argv entries. +.Pp +In order to use +.Fn getopt +to evaluate multiple sets of arguments, or to evaluate a single set of +arguments multiple times, +the variable +.Va optreset +must be set to 1 before the second and each additional set of calls to +.Fn getopt , +and the variable +.Va optind +must be reinitialized. +.Pp +The +.Fn getopt +function returns \-1 when the argument list is exhausted. +The interpretation of options in the argument list may be cancelled +by the option +.Dq -- +(double dash) which causes +.Fn getopt +to signal the end of argument processing and return \-1. +When all options have been processed (i.e., up to the first non-option +argument), +.Fn getopt +returns \-1. +.Sh RETURN VALUES +The +.Fn getopt +function returns the next known option character in +.Fa optstring . +If +.Fn getopt +encounters a character not found in +.Fa optstring +or if it detects a missing option argument, +it returns +.Sq \&? +(question mark). +If +.Fa optstring +has a leading +.Sq \&: +then a missing option argument causes +.Sq \&: +to be returned instead of +.Sq \&? . +In either case, the variable +.Va optopt +is set to the character that caused the error. +The +.Fn getopt +function returns \-1 when the argument list is exhausted. +.Sh EXAMPLES +.Bd -literal -compact +extern char *optarg; +extern int optind; +int bflag, ch, fd; + +bflag = 0; +while ((ch = getopt(argc, argv, "bf:")) != -1) { + switch (ch) { + case 'b': + bflag = 1; + break; + case 'f': + if ((fd = open(optarg, O_RDONLY, 0)) < 0) { + (void)fprintf(stderr, + "myname: %s: %s\en", optarg, strerror(errno)); + exit(1); + } + break; + case '?': + default: + usage(); + } +} +argc -= optind; +argv += optind; +.Ed +.Sh RETURN VALUES +If the +.Fn getopt +function encounters a character not found in the string +.Fa optstring +or detects +a missing option argument it writes an error message to +.Em stderr +and returns +.Sq \&? . +Setting +.Va opterr +to a zero will disable these error messages. +If +.Fa optstring +has a leading +.Sq \&: +then a missing option argument causes a +.Sq \&: +to be returned in addition to suppressing any error messages. +.Pp +Option arguments are allowed to begin with +.Sq - ; +this is reasonable but reduces the amount of error checking possible. +.Sh SEE ALSO +.Xr getopt 1 , +.Xr getopt_long 3 , +.Xr getsubopt 3 +.Sh STANDARDS +The +.Va optreset +variable was added to make it possible to call the +.Fn getopt +function multiple times. +This is an extension to the +.St -p1003.2 +specification. +.Sh HISTORY +The +.Fn getopt +function appeared in +.Bx 4.3 . +.Sh BUGS +The +.Fn getopt +function was once specified to return +.Dv EOF +instead of \-1. +This was changed by +.St -p1003.2-92 +to decouple +.Fn getopt +from +.In stdio.h . +.Pp +A single dash +.Pq Sq - +may be specified as a character in +.Fa optstring , +however it should +.Em never +have an argument associated with it. +This allows +.Fn getopt +to be used with programs that expect +.Sq - +as an option flag. +This practice is wrong, and should not be used in any current development. +It is provided for backward compatibility +.Em only . +Care should be taken not to use +.Sq - +as the first character in +.Fa optstring +to avoid a semantic conflict with +.Tn GNU +.Fn getopt , +which assigns different meaning to an +.Fa optstring +that begins with a +.Sq - . +By default, a single dash causes +.Fn getopt +to return \-1. +.Pp +It is also possible to handle digits as option letters. +This allows +.Fn getopt +to be used with programs that expect a number +.Pq Dq Li \-3 +as an option. +This practice is wrong, and should not be used in any current development. +It is provided for backward compatibility +.Em only . +The following code fragment works in most cases. +.Bd -literal -offset indent +int ch; +long length; +char *p; + +while ((ch = getopt(argc, argv, "0123456789")) != -1) { + switch (ch) { + case '0': case '1': case '2': case '3': case '4': + case '5': case '6': case '7': case '8': case '9': + p = argv[optind - 1]; + if (p[0] == '-' && p[1] == ch && !p[2]) + length = ch - '0'; + else + length = strtol(argv[optind] + 1, NULL, 10); + break; + } +} +.Ed diff --git a/static/netbsd/man3/getopt_long.3 b/static/netbsd/man3/getopt_long.3 new file mode 100644 index 00000000..4fc6fce6 --- /dev/null +++ b/static/netbsd/man3/getopt_long.3 @@ -0,0 +1,310 @@ +.\" $NetBSD: getopt_long.3,v 1.22 2022/01/04 19:36:16 uwe Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 +.\" +.Dd December 9, 2018 +.Dt GETOPT_LONG 3 +.Os +.Sh NAME +.Nm getopt_long +.Nd get long options from command line argument list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In getopt.h +.Ft int +.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index" +.Sh DESCRIPTION +The +.Fn getopt_long +function is similar to +.Xr getopt 3 +but it accepts options in two forms: words and characters. +The +.Fn getopt_long +function provides a superset of the functionality of +.Xr getopt 3 . +.Fn getopt_long +can be used in two ways. +In the first way, every long option understood by the program has a +corresponding short option, and the option structure is only used to +translate from long options to short options. +When used in this fashion, +.Fn getopt_long +behaves identically to +.Xr getopt 3 . +This is a good way to add long option processing to an existing program +with the minimum of rewriting. +.Pp +In the second mechanism, a long option sets a flag in the +.Fa option +structure passed, or will store a pointer to the command line argument +in the +.Fa option +structure passed to it for options that take arguments. +Additionally, the long option's argument may be specified as a single +argument with an equal sign, e.g. +.Bd -literal +myprogram --myoption=somevalue +.Ed +.Pp +When a long option is processed the call to +.Fn getopt_long +will return 0. +For this reason, long option processing without +shortcuts is not backwards compatible with +.Xr getopt 3 . +.Pp +It is possible to combine these methods, providing for long options +processing with short option equivalents for some options. +Less frequently used options would be processed as long options only. +.Pp +Abbreviated long option names are accepted when +.Fn getopt_long +processes long options if the abbreviation is unique. +An exact match is always preferred for a defined long option. +.Pp +The +.Fn getopt_long +call requires a structure to be initialized describing the long options. +The structure is: +.Bd -literal +struct option { + char *name; + int has_arg; + int *flag; + int val; +}; +.Ed +.Pp +The +.Fa name +field should contain the option name without the leading double dash. +.Pp +The +.Fa has_arg +field should be one of: +.Bl -tag -width "optional_argument" +.It Li no_argument +no argument to the option is expected. +.It Li required_argument +an argument to the option is required. +.It Li optional_argument +an argument to the option may be presented. +.El +.Pp +If +.Fa flag +is not +.Dv NULL , +then the integer pointed to by it will be set to the value in the +.Fa val +field. +If the +.Fa flag +field is +.Dv NULL , +then the +.Fa val +field will be returned. +Setting +.Fa flag +to +.Dv NULL +and setting +.Fa val +to the corresponding short option will make this function act just +like +.Xr getopt 3 . +.Pp +If the +.Fa index +argument is not +.Dv NULL , +the integer it points to will be set to the index of the long option +in the +.Fa long_options +array. +.Pp +The last element of the +.Fa long_options +array has to be filled with zeroes (see +.Sx EXAMPLES +section). +.Sh EXAMPLES +.Bd -literal -compact +extern char *optarg; +extern int optind; +int bflag, ch, fd; +int daggerset; + +/* options descriptor */ +static struct option longopts[] = { + { "buffy", no_argument, NULL, 'b' }, + { "fluoride", required_argument, NULL, 'f' }, + { "daggerset", no_argument, &daggerset, 1 }, + { NULL, 0, NULL, 0 } +}; + +bflag = 0; +while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) + switch (ch) { + case 'b': + bflag = 1; + break; + case 'f': + if ((fd = open(optarg, O_RDONLY, 0)) < 0) { + (void)fprintf(stderr, + "myname: %s: %s\en", optarg, strerror(errno)); + exit(1); + } + break; + case 0: + if(daggerset) { + fprintf(stderr,"Buffy will use her dagger to " + "apply fluoride to dracula's teeth\en"); + } + break; + case '?': + default: + usage(); +} +argc -= optind; +argv += optind; +.Ed +.Sh IMPLEMENTATION DIFFERENCES +This section describes differences to the GNU implementation +found in glibc-2.1.3: +.Bl -tag -width "xxx" +.It Li o +handling of - as first char of option string in presence of +environment variable POSIXLY_CORRECT: +.Bl -tag -width "NetBSD" +.It Li GNU +ignores POSIXLY_CORRECT and returns non-options as +arguments to option '\e1'. +.It Li NetBSD +honors POSIXLY_CORRECT and stops at the first non-option. +.El +.It Li o +handling of :: in options string in presence of POSIXLY_CORRECT: +.Bl -tag -width "NetBSD" +.It Li Both +GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to +mean the preceding option takes an optional argument. +.El +.It Li o +return value in case of missing argument if first character +(after + or -) in option string is not ':': +.Bl -tag -width "NetBSD" +.It Li GNU +returns '?' +.It NetBSD +returns ':' (since NetBSD's getopt does). +.El +.It Li o +handling of --a in getopt: +.Bl -tag -width "NetBSD" +.It Li GNU +parses this as option '-', option 'a'. +.It Li NetBSD +parses this as '--', and returns \-1 (ignoring the a). +(Because the original getopt does.) +.El +.It Li o +setting of optopt for long options with flag != +.Dv NULL : +.Bl -tag -width "NetBSD" +.It Li GNU +sets optopt to val. +.It Li NetBSD +sets optopt to 0 (since val would never be returned). +.El +.It Li o +handling of -W with W; in option string in getopt (not getopt_long): +.Bl -tag -width "NetBSD" +.It Li GNU +causes a segfault. +.It Li NetBSD +returns \-1, with optind pointing past the argument of -W +(as if `-W arg' were `--arg', and thus '--' had been found). +.\" How should we treat W; in the option string when called via +.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? +.El +.It Li o +setting of optarg for long options without an argument that are +invoked via -W (W; in option string): +.Bl -tag -width "NetBSD" +.It Li GNU +sets optarg to the option name (the argument of -W). +.It Li NetBSD +sets optarg to +.Dv NULL +(the argument of the long option). +.El +.It Li o +handling of -W with an argument that is not (a prefix to) a known +long option (W; in option string): +.Bl -tag -width "NetBSD" +.It Li GNU +returns -W with optarg set to the unknown option. +.It Li NetBSD +treats this as an error (unknown option) and returns '?' with +optopt set to 0 and optarg set to +.Dv NULL +(as GNU's man page documents). +.El +.It Li o +The error messages are different. +.It Li o +NetBSD does not permute the argument vector at the same points in +the calling sequence as GNU does. +The aspects normally used by the caller +(ordering after \-1 is returned, value of optind relative +to current positions) are the same, though. +(We do fewer variable swaps.) +.El +.Sh SEE ALSO +.Xr getopt 3 +.Sh HISTORY +The +.Fn getopt_long +function first appeared in GNU libiberty. +The first +.Nx +implementation appeared in 1.5. +.Sh BUGS +The implementation can completely replace +.Xr getopt 3 , +but right now we are using separate code. +.Pp +The +.Fa argv +argument is not really const. diff --git a/static/netbsd/man3/getpagesize.3 b/static/netbsd/man3/getpagesize.3 new file mode 100644 index 00000000..51b68e66 --- /dev/null +++ b/static/netbsd/man3/getpagesize.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: getpagesize.3,v 1.12 2003/08/07 16:42:50 agc Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpagesize.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt GETPAGESIZE 3 +.Os +.Sh NAME +.Nm getpagesize +.Nd get system page size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getpagesize void +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr sysconf 3 . +.Ef +.Pp +.Fn getpagesize +returns the number of bytes in a page. +Page granularity is the granularity of many of the memory management calls. +.Pp +The page size is a +.Em system +page size and may not be the same as the underlying +hardware page size. +.Sh SEE ALSO +.Xr pagesize 1 , +.Xr sbrk 2 , +.Xr sysconf 3 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/getpass.3 b/static/netbsd/man3/getpass.3 new file mode 100644 index 00000000..2c170900 --- /dev/null +++ b/static/netbsd/man3/getpass.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: getpass.3,v 1.23 2017/10/24 18:50:46 abhinav Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpass.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 13, 2012 +.Dt GETPASS 3 +.Os +.Sh NAME +.Nm getpass , +.Nm getpass_r , +.Nm getpassfd +.Nd get a password +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn getpass "const char *prompt" +.Ft char * +.Fn getpass_r "const char *prompt" "char *buf" "size_t buflen" +.Ft char * +.Fn getpassfd "const char *prompt" "char *buf" "size_t buflen" "int *fd" "int flags" "int timeout" +.Sh DESCRIPTION +The +.Fn getpass +function displays a prompt to, and reads in a password from, +.Pa /dev/tty . +If this file is not accessible, +.Fn getpass +displays the prompt on the standard error output and reads from the standard +input. +.Pp +The password may be up to +.Xr sysconf 3 +.Dv _SC_PASS_MAX +characters in length. +Any additional +characters and the terminating newline character are discarded. +.Pp +.Fn getpass +turns off character echoing while reading the password. +.Pp +.Fn getpass_r +is similar to +.Fn getpass +only it puts its result in +.Fa buf +for up to +.Fa buflen +characters. +If the +.Fa buf +argument is +.Dv NULL , +then a buffer will be dynamically allocated. +.Pp +The +.Fn getpassfd +function allows one to specify the three file descriptors corresponding to +.Dv stdin , +.Dv stdout , +and +.Dv stderr +in the +.Fa fd +argument, or if +.Fa fd +is +.Dv NULL , +.Fn getpassfd +first attempts to open +.Pa /dev/tty +and if that fails, defaults to +.Dv STDIN_FILENO +for input and +.Dv STDERR_FILENO +for output. +.Pp +The behavior of +.Fn getpassfd +is controlled by the +.Fa flags +argument: +.Bl -tag -width GETPASS_FORCE_UPPER +.It Dv GETPASS_NEED_TTY +Fail if we are unable to set the tty modes like we want. +.It Dv GETPASS_FAIL_EOF +Fail if we get the end-of-file character instead of returning the result so far. +.It Dv GETPASS_BUF_LIMIT +Beep when the buffer limit is reached, instead of silently absorbing it. +.It Dv GETPASS_NO_SIGNAL +Don't make ttychars send signals. +.It Dv GETPASS_NO_BEEP +Don't beep if we erase past the beginning of the buffer or we try to enter past +the end. +.It Dv GETPASS_ECHO_STAR +Echo a +.Sq * +for each character entered. +.It Dv GETPASS_ECHO +Echo characters as they are typed. +.It Dv GETPASS_ECHO_NL +Echoes a newline if successful. +.It Dv GETPASS_7BIT +Mask the high bit for each entered character. +.It Dv GETPASS_FORCE_LOWER +Lowercase each entered character. +.It Dv GETPASS_FORCE_UPPER +Uppercase each entered character. +.El +.Pp +Finally if the +.Fa timeout +argument is non zero, +.Fn getpassfd +will wait for +.Fa timeout +seconds for input after each character before returning an error, instead of +waiting forever. +.Sh RETURN VALUES +The +.Fn getpass +function returns a pointer to the NUL terminated password, or an empty +string on error. +The +.Fn getpass_r +and +.Fn getpassfd +functions return a pointer to the NUL terminated password, or +.Dv NULL +on error. +.Sh FILES +.Bl -tag -width /dev/tty -compact +.It Pa /dev/tty +.El +.Sh SEE ALSO +.Xr crypt 3 +.Sh STANDARDS +The +.Fn getpass +function appeared in +.St -susv2 , +but it was already marked as legacy. +The function was removed in the +.St -p1003.1-2001 +standard. +.Sh HISTORY +A +.Fn getpass +function appeared in +.At v7 . +The +.Fn getpass_r +and +.Fn getpassfd +functions appeared in +.Nx 7.0 . +.Sh BUGS +The +.Fn getpass +function leaves its result in an internal static object and returns +a pointer to that object. +Subsequent calls to +.Fn getpass +will modify the same object. +.Sh SECURITY CONSIDERATIONS +The calling process should zero the password as soon as possible to +avoid leaving the cleartext password visible in the process's address +space. +.Pp +Historically +.Nm +accepted and returned a password if it could not modify the terminal +settings to turn echo off (or if the input was not a terminal). +In this implementation, only terminal input is accepted. diff --git a/static/netbsd/man3/getpeereid.3 b/static/netbsd/man3/getpeereid.3 new file mode 100644 index 00000000..77df2b30 --- /dev/null +++ b/static/netbsd/man3/getpeereid.3 @@ -0,0 +1,142 @@ +.\" +.\" Copyright (c) 2001 Dima Dorfman. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libc/gen/getpeereid.3,v 1.6 2002/12/18 10:13:54 ru Exp $ +.\" +.\" $NetBSD: getpeereid.3,v 1.2 2008/01/29 13:55:27 abs Exp $ +.\" +.Dd August 8, 2007 +.Dt GETPEEREID 3 +.Os +.Sh NAME +.Nm getpeereid +.Nd get the effective credentials of a UNIX-domain peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In unistd.h +.Ft int +.Fn getpeereid "int s" "uid_t *euid" "gid_t *egid" +.Sh DESCRIPTION +The +.Fn getpeereid +function returns the effective user and group IDs of the +peer connected to a +.Ux Ns -domain +socket. +The argument +.Fa s +must be a +.Ux Ns -domain +socket +.Pq Xr unix 4 +of type +.Dv SOCK_STREAM +on which either +.Xr connect 2 +has been called, or one returned from +.Xr accept 2 +after +.Xr bind 2 +and +.Xr listen 2 +have been called. +If non-NULL, the effective used ID is placed in +.Fa euid , +and the effective group ID in +.Fa egid . +.Pp +The credentials returned to the +.Xr accept 2 +caller are those of its peer at the time it called +.Xr connect 2 ; +the credentials returned to the +.Xr connect 2 +caller are those of its peer at the time it called +.Xr bind 2 . +This mechanism is reliable; there is no way for either side to influence +the credentials returned to its peer except by calling the appropriate +system call (i.e., either +.Xr connect 2 +or +.Xr bind 2 ) +under different effective credentials. +.Pp +One common use of this routine is for a +.Ux Ns -domain +server +to verify the credentials of its client. +Likewise, the client can verify the credentials of the server. +.Sh IMPLEMENTATION NOTES +On +.Nx , +.Fn getpeereid +is implemented in terms of the +.Dv LOCAL_PEEREID +.Xr unix 4 +socket option. +.Sh RETURN VALUES +.Rv -std getpeereid +.Sh ERRORS +The +.Fn getpeereid +function +fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOTCONN +The argument +.Fa s +does not refer to a socket on which +.Xr connect 2 +have been called nor one returned from +.Xr listen 2 . +.It Bq Er EINVAL +The argument +.Fa s +does not refer to a socket of type +.Dv SOCK_STREAM , +or the kernel returned invalid data. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr listen 2 , +.Xr unix 4 +.Sh HISTORY +The +.Fn getpeereid +function appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/getprogname.3 b/static/netbsd/man3/getprogname.3 new file mode 100644 index 00000000..3dfc4248 --- /dev/null +++ b/static/netbsd/man3/getprogname.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: getprogname.3,v 1.8 2011/05/21 19:06:44 dholland Exp $ +.\" +.\" Copyright (c) 2001 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See http://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <> +.\" +.Dd May 21, 2011 +.Dt GETPROGNAME 3 +.Os +.Sh NAME +.Nm getprogname , +.Nm setprogname +.Nd get/set the name of the current program +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft const char * +.Fn getprogname "void" +.Ft void +.Fn setprogname "const char *name" +.Sh DESCRIPTION +These utility functions get and set the current program's name +as used by various error-reporting functions. +.Pp +.Fn getprogname +returns the name of the current program. +This function is typically useful when generating error messages +or other diagnostic output. +If the program name has not been set, +.Fn getprogname +will return +.Dv NULL . +.Pp +.Fn setprogname +sets the name of the current program to be the last pathname +component of the +.Fa name +argument. +It should be invoked at the start of the program, using the +.Fa argv[0] +passed into the program's +.Fn main +function. +A pointer into the string pointed to by the +.Fa name +argument is kept as the program name. +Therefore, the string pointed to by +.Fa name +should not be modified during the rest of the program's operation. +.Pp +A program's name can only be set once, and in +.Nx +that is actually +done by program start-up code that is run before +.Fn main +is called. +Therefore, in +.Nx , +calling +.Fn setprogname +explicitly has no effect. +However, portable programs that wish to use +.Fn getprogname +should call +.Fn setprogname +from +.Fn main . +On operating systems where +.Fn getprogname +and +.Fn setprogname +are implemented via a portability library, this call is needed to +make the name available. +.Sh SEE ALSO +.Xr err 3 , +.Xr setproctitle 3 +.Sh HISTORY +The +.Nm getprogname +and +.Nm setprogname +function calls appeared in +.Nx 1.6 . +.Sh RESTRICTIONS +The string returned by +.Fn getprogname +is supplied by the invoking process and should not be trusted by +setuid or setgid programs. diff --git a/static/netbsd/man3/getprotoent.3 b/static/netbsd/man3/getprotoent.3 new file mode 100644 index 00000000..44a3d575 --- /dev/null +++ b/static/netbsd/man3/getprotoent.3 @@ -0,0 +1,156 @@ +.\" $NetBSD: getprotoent.3,v 1.13 2011/07/14 22:12:30 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getprotoent.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 15, 2011 +.Dt GETPROTOENT 3 +.Os +.Sh NAME +.Nm getprotoent , +.Nm getprotobynumber , +.Nm getprotobyname , +.Nm setprotoent , +.Nm endprotoent +.Nd get protocol entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netdb.h +.Ft struct protoent * +.Fn getprotoent +.Ft struct protoent * +.Fn getprotobyname "const char *name" +.Ft struct protoent * +.Fn getprotobynumber "int proto" +.Ft void +.Fn setprotoent "int stayopen" +.Ft void +.Fn endprotoent "void" +.Sh DESCRIPTION +The +.Fn getprotoent , +.Fn getprotobyname , +and +.Fn getprotobynumber +functions +each return a pointer to an object with the +following structure +containing the broken-out +fields of a line in the network protocol data base, +.Pa /etc/protocols . +.Bd -literal -offset indent +.Pp +struct protoent { + char *p_name; /* official name of protocol */ + char **p_aliases; /* alias list */ + int p_proto; /* protocol number */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width p_aliases -offset indent +.It Fa p_name +The official name of the protocol. +.It Fa p_aliases +A zero terminated list of alternative names for the protocol. +.It Fa p_proto +The protocol number. +.El +.Pp +The +.Fn getprotoent +function +reads the next line of the file, opening the file if necessary. +.Pp +The +.Fn setprotoent +function +opens and rewinds the file. +If the +.Fa stayopen +flag is non-zero, +the net data base will not be closed after each call to +.Fn getprotobyname +or +.Fn getprotobynumber . +.Pp +The +.Fn endprotoent +function +closes the file. +.Pp +The +.Fn getprotobyname +function +and +.Fn getprotobynumber +sequentially search from the beginning +of the file until a matching +protocol name or +protocol number is found, +or until +.Dv EOF +is encountered. +.Sh RETURN VALUES +Upon success, +.Fn getprotoent , +.Fn getprotobyname , +and +.Fn getprotobynumber +return a pointer to the +.Vt protoent +structure as described above. +A +.Dv NULL +pointer is returned on +.Dv EOF +or error. +.Sh FILES +.Bl -tag -width /etc/protocols -compact +.It Pa /etc/protocols +.El +.Sh SEE ALSO +.Xr protocols 5 +.Sh HISTORY +The +.Fn getprotoent , +.Fn getprotobynumber , +.Fn getprotobyname , +.Fn setprotoent , +and +.Fn endprotoent +functions appeared in +.Bx 4.2 . +.Sh BUGS +These functions use a static data space; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. +Only the Internet +protocols are currently understood. diff --git a/static/netbsd/man3/getpwent.3 b/static/netbsd/man3/getpwent.3 new file mode 100644 index 00000000..0fe8a2d5 --- /dev/null +++ b/static/netbsd/man3/getpwent.3 @@ -0,0 +1,370 @@ +.\" $NetBSD: getpwent.3,v 1.40 2018/02/07 11:16:05 pgoyette Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd February 7, 2018 +.Dt GETPWENT 3 +.Os +.Sh NAME +.Nm getpwent , +.Nm getpwent_r , +.Nm getpwnam , +.Nm getpwnam_r , +.Nm getpwuid , +.Nm getpwuid_r , +.Nm setpassent , +.Nm setpwent , +.Nm endpwent +.Nd password database operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In pwd.h +.Ft struct passwd * +.Fn getpwent void +.Ft int +.Fo getpwent_r +.Fa "struct passwd *pw" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct passwd **result" +.Fc +.Ft struct passwd * +.Fn getpwnam "const char *name" +.Ft int +.Fo getpwnam_r +.Fa "const char *name" +.Fa "struct passwd *pw" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct passwd **result" +.Fc +.Ft struct passwd * +.Fn getpwuid "uid_t uid" +.Ft int +.Fo getpwuid_r +.Fa "uid_t uid" +.Fa "struct passwd *pw" +.Fa "char *buffer" +.Fa "size_t buflen" +.Fa "struct passwd **result" +.Fc +.Ft int +.Fn setpassent "int stayopen" +.Ft void +.Fn setpwent void +.Ft void +.Fn endpwent void +.Sh DESCRIPTION +These functions +operate on the password database +which is described +in +.Xr passwd 5 . +Each entry in the database is defined by the structure +.Ar passwd +found in the include +file +.In pwd.h : +.Bd -literal -offset indent +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* encrypted password */ + uid_t pw_uid; /* user uid */ + gid_t pw_gid; /* user gid */ + time_t pw_change; /* password change time */ + char *pw_class; /* user login class */ + char *pw_gecos; /* general information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* default shell */ + time_t pw_expire; /* account expiration */ +}; +.Ed +.Pp +The functions +.Fn getpwnam +and +.Fn getpwuid +search the password database for the given user name pointed to by +.Ar name +or user id pointed to by +.Ar uid +respectively, always returning the first one encountered. +Identical user names or user ids may result in undefined behavior. +.Pp +The +.Fn getpwent +function +sequentially reads the password database and is intended for programs +that wish to process the complete list of users. +.Pp +The functions +.Fn getpwnam_r , +.Fn getpwuid_r , +and +.Fn getpwent_r +act like their non re-entrant counterparts, updating the contents of +.Ar pw +and storing a pointer to that in +.Ar result , +and returning +.Dv 0 . +Storage used by +.Ar pw +is allocated from +.Ar buffer , +which is +.Ar buflen +bytes in size. +If the requested entry cannot be found, +.Ar result +will point to +.Dv NULL +and +.Dv 0 +will be returned. +If an error occurs, +a non-zero error number will be returned and +.Ar result +will point to +.Dv NULL . +Calling +.Fn getpwent_r +from multiple threads will result in each thread reading a disjoint portion +of the password database. +.Pp +The +.Fn setpassent +function +accomplishes two purposes. +First, it causes +.Fn getpwent +to +.Dq rewind +to the beginning of the database. +Additionally, if +.Fa stayopen +is non-zero, file descriptors are left open, significantly speeding +up subsequent accesses for all of the functions. +(This latter functionality is unnecessary for +.Fn getpwent +as it doesn't close its file descriptors by default.) +.Pp +It is dangerous for long-running programs to keep the file descriptors +open as the database will become out of date if it is updated while the +program is running. +.Pp +The +.Fn setpwent +function +is equivalent to +.Fn setpassent +with an argument of zero. +.Pp +The +.Fn endpwent +function +closes any open files. +.Pp +These functions have been written to +.Dq shadow +the password file, e.g. allow only certain programs to have access +to the encrypted password. +If the process which calls them has an effective uid of 0, the encrypted +password will be returned, otherwise, the password field of the returned +structure will point to the string +.Ql * . +.Sh RETURN VALUES +The functions +.Fn getpwent , +.Fn getpwnam , +and +.Fn getpwuid , +return a valid pointer to a passwd structure on success +and a +.Dv NULL +pointer if the entry was not found or an error occurred. +If an error occurred, the global variable +.Dv errno +is set to indicate the nature of the failure. +The +.Fn setpassent +function returns 0 on failure, setting the global variable +.Dv errno +to indicate the nature of the failure, and 1 on success. +The +.Fn endpwent +and +.Fn setpwent +functions +have no return value. +The functions +.Fn getpwnam_r , +.Fn getpwuid_r , +and +.Fn getpwent_r +return +.Dv 0 +on success or entry not found, and non-zero on failure, setting the global +variable +.Dv errno +to indicate the nature of the failure. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/pwd.db +The insecure password database file +.It Pa /etc/spwd.db +The secure password database file +.It Pa /etc/master.passwd +The current password file +.It Pa /etc/passwd +A Version 7 format password file +.El +.Sh COMPATIBILITY +The historic function +.Fn setpwfile +which allowed the specification of alternative password databases, +has been deprecated and is no longer available. +.Sh ERRORS +The following error codes may be set in +.Va errno +for +.Nm getpwent , +.Nm getpwent_r , +.Nm getpwnam , +.Nm getpwnam_r , +.Nm getpwuid , +.Nm getpwuid_r , +and +.Nm setpassent : +.Bl -tag -width Er +.It Bq Er EINTR +A signal was caught during the database search. +.It Bq Er EIO +An I/O error has occurred. +.It Bq Er EMFILE +The limit on open files for this process has been reached. +.It Bq Er ENFILE +The system limit on open files has been reached. +.El +.Pp +The following error code may be set in +.Va errno +for +.Nm getpwent_r , +.Nm getpwnam_r , +and +.Nm getpwuid_r : +.Bl -tag -width Er +.It Bq Er ERANGE +The resulting +.Ft struct passwd +does not fit in the space defined by +.Dv buffer +and +.Dv buflen . +.El +.Pp +Other +.Dv errno +values may be set depending on the specific database backends. +.Sh SEE ALSO +.Xr getlogin 2 , +.Xr getgrent 3 , +.Xr nsswitch.conf 5 , +.Xr passwd 5 , +.Xr passwd.conf 5 , +.Xr pwd_mkdb 8 , +.Xr vipw 8 +.Sh STANDARDS +The +.Fn getpwnam +and +.Fn getpwuid , +functions conform to +.St -p1003.1-90 . +The +.Fn getpwnam_r +and +.Fn getpwuid_r +functions conform to +.St -p1003.1c-95 . +The +.Fn endpwent , +.Fn getpwent , +and +.Fn setpwent +functions conform to +.St -xpg4.2 +and +.St -p1003.1-2004 +(XSI extension). +.Sh HISTORY +The +.Nm getpwent , +.Nm getpwnam , +.Nm getpwuid , +.Nm setpwent , +and +.Nm endpwent +functions appeared in +.At v7 . +The +.Nm setpassent +function appeared in +.Bx 4.3 Reno . +The functions +.Fn getpwnam_r +and +.Fn getpwuid_r +appeared in +.Nx 3.0 . +.Sh BUGS +The functions +.Fn getpwent , +.Fn getpwnam , +and +.Fn getpwuid , +leave their results in an internal static object and return +a pointer to that object. +Subsequent calls to any of these functions will modify the same object. +.Pp +The functions +.Fn getpwent , +.Fn endpwent , +.Fn setpassent , +and +.Fn setpwent +are fairly useless in a networked environment and should be +avoided, if possible. +.Fn getpwent +makes no attempt to suppress duplicate information if multiple +sources are specified in +.Xr nsswitch.conf 5 . diff --git a/static/netbsd/man3/getrawpartition.3 b/static/netbsd/man3/getrawpartition.3 new file mode 100644 index 00000000..2a94db0d --- /dev/null +++ b/static/netbsd/man3/getrawpartition.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: getrawpartition.3,v 1.12 2024/02/04 18:44:54 uwe Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt GETRAWPARTITION 3 +.Os +.Sh NAME +.Nm getrawpartition +.Nd get the system +.Dq raw +partition +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn getrawpartition void +.Sh DESCRIPTION +.Fn getrawpartition +returns the partition number +.Po +0 for +.Ql a , +1 for +.Ql b , +etc +.Pc +of the +.Dq raw +partition of the system's disks, +or \-1 in case of an error, setting the global +.Va errno +variable. +The possible values for +.Va errno +are the same as in +.Xr sysctl 3 . +The +.Dq raw +partition is defined as the partition which provides access to the entire +disk, regardless of the disk's partition map. +.Sh SEE ALSO +.Xr getmaxpartitions 3 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn getrawpartition +function call appeared in +.Nx 1.2 . diff --git a/static/netbsd/man3/getrpcent.3 b/static/netbsd/man3/getrpcent.3 new file mode 100644 index 00000000..5c03158c --- /dev/null +++ b/static/netbsd/man3/getrpcent.3 @@ -0,0 +1,96 @@ +.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI +.\" $NetBSD: getrpcent.3,v 1.15 2022/12/04 01:29:32 uwe Exp $ +.\" +.Dd August 16, 2004 +.Dt GETRPCENT 3 +.Os +.Sh NAME +.Nm getrpcent , +.Nm getrpcbyname , +.Nm getrpcbynumber , +.Nm endrpcent , +.Nm setrpcent +.Nd get RPC entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft struct rpcent * +.Fn getrpcent void +.Ft struct rpcent * +.Fn getrpcbyname "const char *name" +.Ft struct rpcent * +.Fn getrpcbynumber "int number" +.Ft void +.Fn setrpcent "int stayopen" +.Ft void +.Fn endrpcent void +.Sh DESCRIPTION +.Fn getrpcent , +.Fn getrpcbyname , +and +.Fn getrpcbynumber , +each return a pointer to an object with the +following structure +containing the broken-out +fields of a line in the rpc program number data base, +.Pa /etc/rpc : +.Bd -literal -offset indent +struct rpcent { + char *r_name; /* name of server for this rpc program */ + char **r_aliases; /* alias list */ + long r_number; /* rpc program number */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width r_aliases -offset indent +.It r_name +The name of the server for this rpc program. +.It r_aliases +A zero terminated list of alternative names for the rpc program. +.It r_number +The rpc program number for this service. +.El +.Pp +.Fn getrpcent +reads the next line of the file, opening the file if necessary. +.Pp +.Fn setrpcent +opens and rewinds the file. +If the +.Fa stayopen +flag is non-zero, +the net data base will not be closed after each call to +.Fn getrpcent +(either directly, or indirectly through one of +the other +.Dq getrpc +calls). +.Pp +.Fn endrpcent +closes the file. +.Pp +.Fn getrpcbyname +and +.Fn getrpcbynumber +sequentially search from the beginning +of the file until a matching rpc program name or +program number is found, or until end-of-file is encountered. +.Sh FILES +.Pa /etc/rpc +.Sh RETURN VALUES +A +.Dv NULL +pointer is returned on +.Dv EOF +or error. +.Sh SEE ALSO +.Xr rpc 5 , +.Xr rpcinfo 8 , +.Xr ypserv 8 +.Sh BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. diff --git a/static/netbsd/man3/getrpcport.3 b/static/netbsd/man3/getrpcport.3 new file mode 100644 index 00000000..1ac3a53d --- /dev/null +++ b/static/netbsd/man3/getrpcport.3 @@ -0,0 +1,34 @@ +.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI +.\" $NetBSD: getrpcport.3,v 1.5 2003/01/18 11:29:04 thorpej Exp $ +.\" +.Dd October 6, 1987 +.Dt GETRPCPORT 3 +.Os +.Sh NAME +.Nm getrpcport +.Nd get RPC port number +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Ft int +.Fn getrpcport "char *host" "int prognum" "int versnum" "int proto" +.Sh DESCRIPTION +.Fn getrpcport +returns the port number for version +.Fa versnum +of the RPC program +.Fa prognum +running on +.Fa host +and using protocol +.Fa proto . +It returns 0 if it cannot contact the portmapper, or if +.Fa prognum +is not registered. +If +.Fa prognum +is registered but not with version +.Fa versnum , +it will still return a port number (for some version of the program) +indicating that the program is indeed registered. +The version mismatch will be detected upon the first call to the service. diff --git a/static/netbsd/man3/getservent.3 b/static/netbsd/man3/getservent.3 new file mode 100644 index 00000000..337fd7de --- /dev/null +++ b/static/netbsd/man3/getservent.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: getservent.3,v 1.17 2024/09/07 21:04:43 rillig Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getservent.3 8.4 (Berkeley) 5/25/95 +.\" +.Dd December 3, 2022 +.Dt GETSERVENT 3 +.Os +.Sh NAME +.Nm getservent , +.Nm getservbyport , +.Nm getservbyname , +.Nm setservent , +.Nm endservent +.Nd get service entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In netdb.h +.Ft struct servent * +.Fn getservent +.Ft struct servent * +.Fn getservbyname "const char *name" "const char *proto" +.Ft struct servent * +.Fn getservbyport "int port" "const char *proto" +.Ft void +.Fn setservent "int stayopen" +.Ft void +.Fn endservent void +.Sh DESCRIPTION +The +.Fn getservent , +.Fn getservbyname , +and +.Fn getservbyport +functions +each return a pointer to an object with the +following structure +containing the broken-out +fields of a line in the network services data base, +.Pa /etc/services . +.Bd -literal -offset indent +struct servent { + char *s_name; /* official name of service */ + char **s_aliases; /* alias list */ + int s_port; /* port service resides at */ + char *s_proto; /* protocol to use */ +}; +.Ed +.Pp +The members of this structure are: +.Bl -tag -width s_aliases +.It Fa s_name +The official name of the service. +.It Fa s_aliases +A NULL terminated list of alternative names for the service. +.It Fa s_port +The port number at which the service resides. +Port numbers must be given and are returned in network byte order. +.It Fa s_proto +The name of the protocol to use when contacting the +service. +.El +.Pp +The +.Fn getservent +function +reads the next line of the file, opening the file if necessary. +.Pp +The +.Fn setservent +function +opens and rewinds the file. If the +.Fa stayopen +flag is non-zero, +the net data base will not be closed after each call to +.Fn getservbyname +or +.Fn getservbyport . +.Pp +The +.Fn endservent +function +closes the file. +.Pp +The +.Fn getservbyname +and +.Fn getservbyport +functions +sequentially search from the beginning +of the file until a matching +protocol name or +port number is found, +or until +.Dv EOF +is encountered. +If a protocol name is also supplied (non-\c +.Dv NULL ) , +searches must also match the protocol. +.Sh FILES +.Bl -tag -width /etc/services -compact +.It Pa /etc/services +.It Pa /var/db/services.cdb +.El +.Sh RETURN VALUES +Null pointer is returned on +.Dv EOF +or error. +.Sh SEE ALSO +.Xr getprotoent 3 , +.Xr services 5 , +.Xr services_mkdb 8 +.Sh HISTORY +The +.Fn getservent , +.Fn getservbyport , +.Fn getservbyname , +.Fn setservent , +and +.Fn endservent +functions appeared in +.Bx 4.2 . +.Sh BUGS +These functions use static data storage; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. +Expecting port numbers to fit in a 32 bit +quantity is probably naive. diff --git a/static/netbsd/man3/getsubopt.3 b/static/netbsd/man3/getsubopt.3 new file mode 100644 index 00000000..b6ec9a07 --- /dev/null +++ b/static/netbsd/man3/getsubopt.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: getsubopt.3,v 1.16 2018/08/15 10:49:47 martin Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getsubopt.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd August 15, 2018 +.Dt GETSUBOPT 3 +.Os +.Sh NAME +.Nm getsubopt +.Nd get sub options from an argument +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Vt extern char *suboptarg +.Ft int +.Fn getsubopt "char **optionp" "char * const *tokens" "char **valuep" +.Sh DESCRIPTION +The +.Fn getsubopt +function +parses a string containing tokens delimited by one or more tab, space or +comma +.Pq Ql \&, +characters. +It is intended for use in parsing groups of option arguments provided +as part of a utility command line. +.Pp +The argument +.Fa optionp +is a pointer to a pointer to the string. +The argument +.Fa tokens +is a pointer to a +.Dv NULL Ns -terminated +array of pointers to strings. +.Pp +The +.Fn getsubopt +function +returns the zero-based offset of the pointer in the +.Fa tokens +array referencing a string which matches the first token +in the string, or \-1 if the string contains no tokens or +.Fa tokens +does not contain a matching string. +.Pp +If the token is of the form ``name=value'', the location referenced by +.Fa valuep +will be set to point to the start of the ``value'' portion of the token. +.Pp +On return from +.Fn getsubopt , +.Fa optionp +will be set to point to the start of the next token in the string, +or the null at the end of the string if no more tokens are present. +The external variable +.Fa suboptarg +will be set to point to the start of the current token, or +.Dv NULL +if no +tokens were present. +The argument +.Fa valuep +will be set to point to the ``value'' portion of the token, or +.Dv NULL +if no ``value'' portion was present. +.Sh EXAMPLES +.Bd -literal -compact +char *tokens[] = { + #define ONE 0 + "one", + #define TWO 1 + "two", + NULL +}; + +\&... + +extern char *optarg, *suboptarg; +char *options, *value; + +while ((ch = getopt(argc, argv, "ab:")) != \-1) { + switch(ch) { + case 'a': + /* process ``a'' option */ + break; + case 'b': + options = optarg; + while (*options) { + switch(getsubopt(&options, tokens, &value)) { + case ONE: + /* process ``one'' sub option */ + break; + case TWO: + /* process ``two'' sub option */ + if (!value) + error("no value for two"); + i = atoi(value); + break; + case \-1: + if (suboptarg) + error("unknown sub option %s", + suboptarg); + else + error("missing sub option"); + break; + } + break; + } +.Ed +.Sh SEE ALSO +.Xr getopt 3 , +.Xr strsep 3 +.Sh HISTORY +The +.Fn getsubopt +function first appeared in +.Bx 4.4 , +and is included in +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/gettext.3 b/static/netbsd/man3/gettext.3 new file mode 100644 index 00000000..4d3fa0bf --- /dev/null +++ b/static/netbsd/man3/gettext.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" This is free documentation; 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 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" GNU gettext source code and manual +.\" LI18NUX 2000 Globalization Specification +.\" +.TH GETTEXT 3 "May 2001" "GNU gettext 0.16.1" +.SH NAME +gettext, dgettext, dcgettext \- translate message +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char * gettext (const char * " msgid ); +.BI "char * dgettext (const char * " domainname ", const char * " msgid ); +.BI "char * dcgettext (const char * " domainname ", const char * " msgid , +.BI " int " category ); +.fi +.SH DESCRIPTION +The \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions attempt to +translate a text string into the user's native language, by looking up the +translation in a message catalog. +.PP +The \fImsgid\fP argument identifies the message to be translated. By +convention, it is the English version of the message, with non-ASCII +characters replaced by ASCII approximations. This choice allows the +translators to work with message catalogs, called PO files, that contain +both the English and the translated versions of each message, and can be +installed using the \fBmsgfmt\fP utility. +.PP +A message domain is a set of translatable \fImsgid\fP messages. Usually, +every software package has its own message domain. The domain name is used +to determine the message catalog where the translation is looked up; it must +be a non-empty string. For the \fBgettext\fP function, it is specified through +a preceding \fBtextdomain\fP call. For the \fBdgettext\fP and \fBdcgettext\fP +functions, it is passed as the \fIdomainname\fP argument; if this argument is +NULL, the domain name specified through a preceding \fBtextdomain\fP call is +used instead. +.PP +Translation lookup operates in the context of the current locale. For the +\fBgettext\fP and \fBdgettext\fP functions, the \fBLC_MESSAGES\fP locale +facet is used. It is determined by a preceding call to the \fBsetlocale\fP +function. \fBsetlocale(LC_ALL,"")\fP initializes the \fBLC_MESSAGES\fP locale +based on the first nonempty value of the three environment variables +\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP; see \fBsetlocale\fP(3). For the +\fBdcgettext\fP function, the locale facet is determined by the \fIcategory\fP +argument, which should be one of the \fBLC_xxx\fP constants defined in the + header, excluding \fBLC_ALL\fP. In both cases, the functions also +use the \fBLC_CTYPE\fP locale facet in order to convert the translated message +from the translator's codeset to the current locale's codeset, unless +overridden by a prior call to the \fBbind_textdomain_codeset\fP function. +.PP +The message catalog used by the functions is at the pathname +\fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo. Here +\fIdirname\fP is the directory specified through \fBbindtextdomain\fP. Its +default is system and configuration dependent; typically it is +\fIprefix\fP/share/locale, where \fIprefix\fP is the installation prefix of the +package. \fIlocale\fP is the name of the current locale facet; the GNU +implementation also tries generalizations, such as the language name without +the territory name. \fIcategory\fP is \fBLC_MESSAGES\fP for the \fBgettext\fP +and \fBdgettext\fP functions, or the argument passed to the \fBdcgettext\fP +function. +.PP +If the \fBLANGUAGE\fP environment variable is set to a nonempty value, and the +locale is not the "C" locale, the value of \fBLANGUAGE\fP is assumed to contain +a colon separated list of locale names. The functions will attempt to look up +a translation of \fImsgid\fP in each of the locales in turn. This is a GNU +extension. +.PP +In the "C" locale, or if none of the used catalogs contain a translation for +\fImsgid\fP, the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions +return \fImsgid\fP. +.SH "RETURN VALUE" +If a translation was found in one of the specified catalogs, it is converted +to the locale's codeset and returned. The resulting string is statically +allocated and must not be modified or freed. Otherwise \fImsgid\fP is returned. +.SH ERRORS +\fBerrno\fP is not modified. +.SH BUGS +The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid +warnings in C code predating ANSI C. +.PP +When an empty string is used for \fImsgid\fP, the functions may return a +nonempty string. +.SH "SEE ALSO" +.BR ngettext (3), +.BR dngettext (3), +.BR dcngettext (3), +.BR setlocale (3), +.BR textdomain (3), +.BR bindtextdomain (3), +.BR bind_textdomain_codeset (3), +.BR msgfmt (1) diff --git a/static/netbsd/man3/getttyent.3 b/static/netbsd/man3/getttyent.3 new file mode 100644 index 00000000..bb7aacda --- /dev/null +++ b/static/netbsd/man3/getttyent.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: getttyent.3,v 1.21 2014/02/07 20:20:56 christos Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getttyent.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd February 7, 2014 +.Dt GETTTYENT 3 +.Os +.Sh NAME +.Nm getttyent , +.Nm getttynam , +.Nm setttyent , +.Nm setttyentpath , +.Nm endttyent +.Nd get ttys file entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ttyent.h +.Ft struct ttyent * +.Fn getttyent void +.Ft struct ttyent * +.Fn getttynam "const char *name" +.Ft int +.Fn setttyent void +.Ft int +.Fn setttyentpath "const char *path" +.Ft int +.Fn endttyent void +.Sh DESCRIPTION +The +.Fn getttyent , +and +.Fn getttynam +functions +each return a pointer to an object, with the following structure, +containing the broken-out fields of a line from the tty description +file. +.Bd -literal +struct ttyent { + char *ty_name; /* terminal device name */ + char *ty_getty; /* command to execute */ + char *ty_type; /* terminal type */ +#define TTY_ON 0x01 /* enable logins */ +#define TTY_SECURE 0x02 /* allow uid of 0 to login */ +#define TTY_LOCAL 0x04 /* set 'CLOCAL' on open (dev. specific) */ +#define TTY_RTSCTS 0x08 /* set 'CRTSCTS' on open (dev. specific) */ +#define TTY_SOFTCAR 0x10 /* ignore hardware carrier (dev. spec.) */ +#define TTY_MDMBUF 0x20 /* set 'MDMBUF' on open (dev. specific) */ +#define TTY_DTRCTS 0x40 /* set 'CDTRCTS' on open (dev. specific) */ + int ty_status; /* flag values */ + char *ty_window; /* command for window manager */ + char *ty_comment; /* comment field */ + char *ty_class; /* category of tty usage */ +}; +.Ed +.Pp +The fields are as follows: +.Bl -tag -width ty_comment +.It Fa ty_name +The name of the character-special file. +.It Fa ty_getty +The name of the command invoked by +.Xr init 8 +to initialize tty line characteristics. +.It Fa ty_type +The name of the default terminal type connected to this tty line. +.It Fa ty_status +A mask of bit fields which indicate various actions allowed on this +tty line. +The possible flags are as follows: +.Bl -tag -width TTY_SOFTCAR +.It Dv TTY_ON +Enables logins (i.e., +.Xr init 8 +will start the command referenced by +.Fa ty_getty +on this entry). +.It Dv TTY_SECURE +Allow users with a uid of 0 to login on this terminal. +.It Dv TTY_LOCAL +If the terminal port's driver supports it, cause the line +to be treated as ``local.'' +.It Dv TTY_MDMBUF +If the terminal port's driver supports it, use +DTR/DCD hardware flow control on the line by default. +.It Dv TTY_RTSCTS +If the terminal port's driver supports it, use +full-duplex RTS/CTS hardware flow control on the line +by default. +.It Dv TTY_SOFTCAR +If the terminal port's driver supports it, ignore hardware +carrier on the line. +.El +.It Fa ty_window +The command to execute for a window system associated with the line. +.It Fa ty_comment +Any trailing comment field, with any leading hash marks (``#'') or +whitespace removed. +.It Fa ty_class +A key indexing into a capfile style database (/etc/ttyclasses) +of attributes for this class of tty. +No attributes are currently defined or used, +so there are currently no functions to retrieve them. +.El +.Pp +If any of the fields pointing to character strings are unspecified, +they are returned as null pointers. +The field +.Fa ty_status +will be zero if no flag values are specified. +.Pp +See +.Xr ttys 5 +for a more complete discussion of the meaning and usage of the +fields. +.Pp +The +.Fn getttyent +function +reads the next line from the ttys file, opening the file if necessary. +The +.Fn setttyent +function +rewinds the file if open, or opens the file if it is unopened. +The +.Fn setttyentpath +function +is equivalent to +.Fn setttyent +but accepts an additional argument to read the ttys information from +an alternate file instead of the default location +.Pq defined in Dv _PATH_TTYS . +The +.Fn endttyent +function +closes any open files. +.Pp +The +.Fn getttynam +function +searches from the beginning of the file until a matching +.Fa name +is found +(or until +.Dv EOF +is encountered). +.Sh RETURN VALUES +The routines +.Fn getttyent +and +.Fn getttynam +return a null pointer on +.Dv EOF +or error. +The +.Fn setttyent +and +.Fn setttyentpath +functions +and +.Fn endttyent +return 0 on failure and 1 on success. +.Sh FILES +.Bl -tag -width /etc/ttys -compact +.It Pa /etc/ttys +.El +.Sh SEE ALSO +.Xr login 1 , +.Xr ttyslot 3 , +.Xr capfile 5 , +.Xr gettytab 5 , +.Xr ttys 5 , +.Xr getty 8 , +.Xr init 8 , +.Xr ttyflags 8 +.Sh HISTORY +The +.Fn getttyent , +.Fn getttynam , +.Fn setttyent , +and +.Fn endttyent +functions appeared in +.Bx 4.3 . +The +.Fn setttyentpath +function appeared in +.Nx 4.0 . +.Sh BUGS +These functions use static data storage; +if the data is needed for future use, it should be +copied before any subsequent calls overwrite it. diff --git a/static/netbsd/man3/getusershell.3 b/static/netbsd/man3/getusershell.3 new file mode 100644 index 00000000..77efbd77 --- /dev/null +++ b/static/netbsd/man3/getusershell.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: getusershell.3,v 1.11 2022/12/04 01:29:32 uwe Exp $ +.\" +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getusershell.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd November 23, 2004 +.Dt GETUSERSHELL 3 +.Os +.Sh NAME +.Nm getusershell , +.Nm setusershell , +.Nm endusershell +.Nd get valid user shells +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn getusershell void +.Ft void +.Fn setusershell void +.Ft void +.Fn endusershell void +.Sh DESCRIPTION +The +.Fn getusershell +function +returns a pointer to a valid user shell as defined by the +system manager in the shells database as described in +.Xr shells 5 . +If the shells database is not available, +.Fn getusershell +behaves as if +.Pa /bin/sh +and +.Pa /bin/csh +were listed. +.Pp +The +.Fn getusershell +function +reads the next +line (opening the file if necessary); +.Fn setusershell +rewinds the file; +.Fn endusershell +closes it. +.Sh FILES +.Bl -tag -width /etc/shells -compact +.It Pa /etc/shells +.El +.Sh RETURN VALUES +The routine +.Fn getusershell +returns a null pointer (0) on +.Dv EOF . +.Sh SEE ALSO +.Xr nsswitch.conf 5 , +.Xr shells 5 +.Sh HISTORY +The +.Fn getusershell +function appeared in +.Bx 4.3 . +.Sh BUGS +The +.Fn getusershell +function leaves its result in an internal static object and returns +a pointer to that object. +Subsequent calls to +.Fn getusershell +will modify the same object. diff --git a/static/netbsd/man3/getwc.3 b/static/netbsd/man3/getwc.3 new file mode 100644 index 00000000..f8db49e0 --- /dev/null +++ b/static/netbsd/man3/getwc.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: getwc.3,v 1.10 2017/10/25 17:03:30 abhinav Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 6, 2010 +.Dt GETWC 3 +.Os +.Sh NAME +.Nm fgetwc , +.Nm getwc , +.Nm getwchar +.Nd get next wide character from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft wint_t +.Fn fgetwc "FILE *stream" +.Ft wint_t +.Fn getwc "FILE *stream" +.Ft wint_t +.Fn getwchar +.Sh DESCRIPTION +The +.Fn fgetwc +function +obtains the next input wide character (if present) from the stream pointed at by +.Fa stream , +or the next character pushed back on the stream via +.Xr ungetwc 3 . +.Pp +The +.Fn getwc +function +acts essentially identically to +.Fn fgetwc , +but is a macro that expands in-line. +.Pp +The +.Fn getwchar +function +is equivalent to +.Fn getwc +with the argument stdin. +.Sh RETURN VALUES +If successful, these routines return the next wide character +from the +.Fa stream . +If the stream is at end-of-file or a read error occurs, +the routines return +.Dv WEOF . +The routines +.Xr feof 3 +and +.Xr ferror 3 +must be used to distinguish between end-of-file and error. +If an error occurs, the global variable +.Va errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.Dv WEOF +until the condition is cleared with +.Xr clearerr 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr putwc 3 , +.Xr stdio 3 , +.Xr ungetwc 3 +.Sh STANDARDS +The +.Fn fgetwc , +.Fn getwc +and +.Fn getwchar +functions +conform to +.St -isoC-99 +and +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/glob.3 b/static/netbsd/man3/glob.3 new file mode 100644 index 00000000..b5861a7d --- /dev/null +++ b/static/netbsd/man3/glob.3 @@ -0,0 +1,541 @@ +.\" $NetBSD: glob.3,v 1.45 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Guido van Rossum. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)glob.3 8.3 (Berkeley) 4/16/94 +.\" +.Dd May 28, 2019 +.Dt GLOB 3 +.Os +.Sh NAME +.Nm glob , +.Nm globfree , +.Nm glob_pattern_p +.Nd generate pathnames matching a pattern +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In glob.h +.Ft int +.Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob" +.Ft void +.Fn globfree "glob_t *pglob" +.Ft int +.Fn glob_pattern_p "const char *pattern" "int quote" +.Sh DESCRIPTION +The +.Fn glob +function +is a pathname generator that implements the rules for file name pattern +matching used by the shell. +.Pp +The include file +.Pa glob.h +defines the structure type +.Fa glob_t , +which contains at least the following fields: +.Bd -literal +typedef struct { + size_t gl_pathc; /* count of total paths so far */ + size_t gl_matchc; /* count of paths matching pattern */ + size_t gl_offs; /* reserved at beginning of gl_pathv */ + int gl_flags; /* returned flags */ + char **gl_pathv; /* list of paths matching pattern */ +} glob_t; +.Ed +.Pp +The argument +.Fa pattern +is a pointer to a pathname pattern to be expanded. +The +.Fn glob +argument +matches all accessible pathnames against the pattern and creates +a list of the pathnames that match. +In order to have access to a pathname, +.Fn glob +requires search permission on every component of a path except the last +and read permission on each directory of any filename component of +.Fa pattern +that contains any of the special characters +.Ql * , +.Ql \&? +or +.Ql \&[ . +.Pp +The +.Fn glob +argument +stores the number of matched pathnames into the +.Fa gl_pathc +field, and a pointer to a list of pointers to pathnames into the +.Fa gl_pathv +field. +The first pointer after the last pathname is +.Dv NULL . +If the pattern does not match any pathnames, the returned number of +matched paths is set to zero. +.Pp +It is the caller's responsibility to create the structure pointed to by +.Fa pglob . +The +.Fn glob +function allocates other space as needed, including the memory pointed +to by +.Fa gl_pathv . +.Pp +The argument +.Fa flags +is used to modify the behavior of +.Fn glob . +The value of +.Fa flags +is the bitwise inclusive +.Tn OR +of any of the following +values defined in +.Pa glob.h : +.Bl -tag -width GLOB_ALTDIRFUNC +.It Dv GLOB_APPEND +Append pathnames generated to the ones from a previous call (or calls) +to +.Fn glob . +The value of +.Fa gl_pathc +will be the total matches found by this call and the previous call(s). +The pathnames are appended to, not merged with the pathnames returned by +the previous call(s). +Between calls, the caller must not change the setting of the +.Dv GLOB_DOOFFS +flag, nor change the value of +.Fa gl_offs +when +.Dv GLOB_DOOFFS +is set, nor (obviously) call +.Fn globfree +for +.Fa pglob . +.It Dv GLOB_DOOFFS +Make use of the +.Fa gl_offs +field. +If this flag is set, +.Fa gl_offs +is used to specify how many +.Dv NULL +pointers to prepend to the beginning +of the +.Fa gl_pathv +field. +In other words, +.Fa gl_pathv +will point to +.Fa gl_offs +.Dv NULL +pointers, +followed by +.Fa gl_pathc +pathname pointers, followed by a +.Dv NULL +pointer. +.It Dv GLOB_ERR +Causes +.Fn glob +to return when it encounters a directory that it cannot open or read. +Ordinarily, +.Fn glob +continues to find matches. +.It Dv GLOB_MARK +Each pathname that is a directory that matches +.Fa pattern +has a slash +appended. +.It Dv GLOB_NOCHECK +If +.Fa pattern +does not match any pathname, then +.Fn glob +returns a list +consisting of only +.Fa pattern , +with one level of backslash escapes removed, +the number of total pathnames set to 1, and the number of matched +pathnames set to 0. +.It Dv GLOB_NOSORT +By default, the pathnames are sorted in ascending +.Tn ASCII +order; +this flag prevents that sorting (speeding up +.Fn glob ) . +.El +.Pp +The following values may also be included in +.Fa flags , +however, they are non-standard extensions to +.St -p1003.2 . +.Bl -tag -width GLOB_TILDE_CHECK +.It Dv GLOB_ALTDIRFUNC +The following additional fields in the pglob structure have been +initialized with alternate functions for glob to use to open, read, +and close directories and to get stat information on names found +in those directories. +.Bd -literal + void *(*gl_opendir)(const char * name); + struct dirent *(*gl_readdir)(void *); + void (*gl_closedir)(void *); + int (*gl_lstat)(const char *name, struct stat *st); + int (*gl_stat)(const char *name, struct stat *st); +.Ed +.Pp +This extension is provided to allow programs such as +.Xr restore 8 +to provide globbing from directories stored on tape. +.It Dv GLOB_BRACE +Pre-process the pattern string to expand +.Ql {pat,pat,...} +strings like +.Xr csh 1 . +The pattern +.Ql {} +is left unexpanded for historical reasons +.Po +.Xr csh 1 +does the same thing to ease typing of +.Xr find 1 +patterns +.Pc . +.It Dv GLOB_LIMIT +Limit the amount of memory used to store matched strings to +.Li 64K , +the number of +.Xr stat 2 +calls to 128, and the number of +.Xr readdir 3 +calls to 16K. +This option should be set for programs that can be coerced to a denial of +service attack via patterns that expand to a very large number of matches, +such as a long string of +.Li */../*/.. +.It Dv GLOB_MAGCHAR +Set by the +.Fn glob +function if the pattern included globbing characters. +See the description of the usage of the +.Fa gl_matchc +structure member for more details. +.It Dv GLOB_NOESCAPE +Disable the use of the backslash +.Pq Ql \e +character for quoting. +.It Dv GLOB_NOMAGIC +Is the same as +.Dv GLOB_NOCHECK +but it only appends the +.Fa pattern +if it does not contain any of the special characters ``*'', ``?'' or ``[''. +.Dv GLOB_NOMAGIC +is provided to simplify implementing the historic +.Xr csh 1 +globbing behavior and should probably not be used anywhere else. +.It Dv GLOB_NO_DOTDIRS +Hide +.Sq Li \&. +and +.Sq Li \&.. +from metacharacter matches, regardless of whether +.Dv GLOB_PERIOD +is set and whether the pattern component begins with a literal period. +.It Dv GLOB_PERIOD +Allow metacharacters to match a leading period in a filename. +.It Dv GLOB_STAR +Indicates that two adjacent +.Li * +characters will do a recursive match in all subdirs, without following +symbolic links and three adjacent +.Li * +characters will also follow symbolic links. +.It Dv GLOB_TILDE +Expand patterns that start with +.Ql ~ +to user name home directories. +If the user with the given user name (or the user id of the current user +in the case of +.Dq ~/ ) +is not found, the original pattern is returned. +.It Dv GLOB_TILDE_CHECK +When used with +.Dv GLOB_TILDE +and the user name or the user id is not found, then +.Dv GLOB_NOMATCH +is returned instead of the original pattern. +.El +.Pp +If, during the search, a directory is encountered that cannot be opened +or read and +.Fa errfunc +is +.Pf non- Dv NULL , +.Fn glob +calls +.Fa (*errfunc)(path, errno) . +This may be unintuitive: a pattern like +.Ql */Makefile +will try to +.Xr stat 2 +.Ql foo/Makefile +even if +.Ql foo +is not a directory, resulting in a +call to +.Fa errfunc . +The error routine can suppress this action by testing for +.Er ENOENT +and +.Er ENOTDIR ; +however, the +.Dv GLOB_ERR +flag will still cause an immediate +return when this happens. +.Pp +If +.Fa errfunc +returns non-zero, +.Fn glob +stops the scan and returns +.Dv GLOB_ABORTED +after setting +.Fa gl_pathc +and +.Fa gl_pathv +to reflect any paths already matched. +This also happens if an error is encountered and +.Dv GLOB_ERR +is set in +.Fa flags , +regardless of the return value of +.Fa errfunc , +if called. +If +.Dv GLOB_ERR +is not set and either +.Fa errfunc +is +.Dv NULL +or +.Fa errfunc +returns zero, the error is ignored. +.Pp +The +.Fn globfree +function frees any space associated with +.Fa pglob +from a previous call(s) to +.Fn glob . +.Pp +The +.Fn glob_pattern_p +returns +.Dv 1 +if the +.Fa pattern +has any special characters that +.Fn glob +will interpret and +.Dv 0 +otherwise. +If the +.Fa quote +argument is non-zero, then backslash quoted characters are ignored. +.Pp +The historical +.Dv GLOB_QUOTE +flag is no longer supported. +Per +.St -p1003.2-92 , +backslash escaping of special characters is the default behaviour; +it may be disabled by specifying the +.Dv GLOB_NOESCAPE +flag. +.Sh RETURN VALUES +On successful completion, +.Fn glob +returns zero. +In addition the fields of +.Fa pglob +contain the values described below: +.Bl -tag -width GLOB_NOCHECK +.It Fa gl_pathc +contains the total number of matched pathnames so far. +This includes other matches from previous invocations of +.Fn glob +if +.Dv GLOB_APPEND +was specified. +.It Fa gl_matchc +contains the number of matched pathnames in the current invocation of +.Fn glob . +.It Fa gl_flags +contains a copy of the +.Fa flags +parameter with the bit +.Dv GLOB_MAGCHAR +set if +.Fa pattern +contained any of the special characters ``*'', ``?'' or ``['', cleared +if not. +.It Fa gl_pathv +contains a pointer to a +.Dv NULL Ns -terminated +list of matched pathnames. +However, if +.Fa gl_pathc +is zero, the contents of +.Fa gl_pathv +are undefined. +.El +.Pp +If +.Fn glob +terminates due to an error, it sets +.Va errno +and returns one of the following non-zero constants, which are defined +in the include file +.In glob.h : +.Bl -tag -width GLOB_ABORTEDXXX +.It Dv GLOB_ABORTED +The scan was stopped because an error was encountered and either +.Dv GLOB_ERR +was set or +.Fa (*errfunc)() +returned non-zero. +.It Dv GLOB_NOMATCH +The pattern does not match any existing pathname, and +.Dv GLOB_NOCHECK +was not set in +.Dv flags . +.It Dv GLOB_NOSPACE +An attempt to allocate memory failed, or if +.Va errno +was 0 +.Li GLOB_LIMIT +was specified in the flags and +.Li ARG_MAX +patterns were matched. +.El +.Pp +The historical +.Dv GLOB_ABEND +return constant is no longer supported. +Portable applications should use the +.Dv GLOB_ABORTED +constant instead. +.Pp +The arguments +.Fa pglob\->gl_pathc +and +.Fa pglob\->gl_pathv +are still set as specified above. +.Sh ENVIRONMENT +.Bl -tag -width HOME -compact +.It Ev HOME +If defined, used as the home directory of the current user in +tilde expansions. +.El +.Sh EXAMPLES +A rough equivalent of +.Ql "ls -l *.c *.h" +can be obtained with the +following code: +.Bd -literal -offset indent +glob_t g; + +g.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &g); +glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); +g.gl_pathv[0] = "ls"; +g.gl_pathv[1] = "-l"; +execvp("ls", g.gl_pathv); +.Ed +.Sh SEE ALSO +.Xr sh 1 , +.Xr fnmatch 3 , +.Xr regexp 3 , +.Xr glob 7 +.Sh STANDARDS +The +.Fn glob +function is expected to be +.St -p1003.2 +compatible with the exception +that the flags +.Dv GLOB_ALTDIRFUNC , +.Dv GLOB_BRACE , +.Dv GLOB_LIMIT , +.Dv GLOB_MAGCHAR , +.Dv GLOB_NOESCAPE , +.Dv GLOB_NOMAGIC , +.Dv GLOB_NO_DOTDIRS , +.Dv GLOB_PERIOD , +.Dv GLOB_STAR , +.Dv GLOB_TILDE , +and the fields +.Fa gl_matchc +and +.Fa gl_flags +should not be used by applications striving for strict +.Tn POSIX +conformance. +.Sh HISTORY +The +.Fn glob +and +.Fn globfree +functions first appeared in +.Bx 4.4 . +The +.Fn glob_pattern_p +function is modelled after the one found in glibc. +.Sh BUGS +Patterns longer than +.Dv MAXPATHLEN +may cause unchecked errors. +.Pp +The +.Fn glob +function may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr stat 2 , +.Xr closedir 3 , +.Xr opendir 3 , +.Xr readdir 3 , +.Xr malloc 3 , +and +.Xr free 3 . diff --git a/static/netbsd/man3/grantpt.3 b/static/netbsd/man3/grantpt.3 new file mode 100644 index 00000000..6da0e906 --- /dev/null +++ b/static/netbsd/man3/grantpt.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: grantpt.3,v 1.4 2008/04/30 13:10:51 martin Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 25, 2004 +.Dt GRANTPT 3 +.Os +.Sh NAME +.Nm grantpt +.Nd grant access to a slave pseudo-terminal device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn grantpt "int fildes" +.Sh DESCRIPTION +The +.Fn grantpt +function changes the mode and ownership of the slave pseudo-terminal device +that corresponds to the master pseudo-terminal device associated with +.Fa fildes +to be owned by the real user id of the calling process, group id of +.Dv tty . +The permissions are set to readable and writable by owner, and writable by +group. +If the slave pseudo-terminal device was being accessed by other file +descriptors at the time, all such access will be revoked. +.Sh RETURN VALUES +If successful, +.Fn grantpt +returns 0; otherwise a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn grantpt +function will fail if: +.Bl -tag -width Er +.It Bq Er EACCESS +the corresponding pseudo-terminal device could not be accessed. +.It Bq Er EBADF +.Fa fildes +is not a valid descriptor. +.It Bq Er EINVAL +.Fa fildes +is not associated with a master pseudo-terminal device. +.El +.Sh NOTES +Setting the group to +.Dv tty +and revoking accesses by other file descriptors are +.Nx +extensions. +Calling +.Fn grantpt +is equivalent to: +.Bd -literal + ioctl(fildes, TIOCGRANTPT, 0); +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr posix_openpt 3 , +.Xr ptsname 3 , +.Xr unlockpt 3 +.Sh STANDARDS +The +.Fn grantpt +function conforms to +.St -p1003.1-2001 . +Its first release was in +.St -xpg4.2 . diff --git a/static/netbsd/man3/gss_acquire_cred.3 b/static/netbsd/man3/gss_acquire_cred.3 new file mode 100644 index 00000000..60b5641f --- /dev/null +++ b/static/netbsd/man3/gss_acquire_cred.3 @@ -0,0 +1,690 @@ +.\" $NetBSD: gss_acquire_cred.3,v 1.5 2023/06/19 21:41:42 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2007 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd October 26, 2005 +.Dt GSS_ACQUIRE_CRED 3 +.Os +.Sh NAME +.Nm gss_accept_sec_context , +.Nm gss_acquire_cred , +.Nm gss_add_cred , +.Nm gss_add_oid_set_member , +.Nm gss_canonicalize_name , +.Nm gss_compare_name , +.Nm gss_context_time , +.Nm gss_create_empty_oid_set , +.Nm gss_delete_sec_context , +.Nm gss_display_name , +.Nm gss_display_status , +.Nm gss_duplicate_name , +.Nm gss_export_name , +.Nm gss_export_sec_context , +.Nm gss_get_mic , +.Nm gss_import_name , +.Nm gss_import_sec_context , +.Nm gss_indicate_mechs , +.Nm gss_init_sec_context , +.Nm gss_inquire_context , +.Nm gss_inquire_cred , +.Nm gss_inquire_cred_by_mech , +.Nm gss_inquire_mechs_for_name , +.Nm gss_inquire_names_for_mech , +.Nm gss_krb5_ccache_name , +.Nm gss_krb5_compat_des3_mic , +.Nm gss_krb5_copy_ccache , +.Nm gss_krb5_import_cred +.Nm gsskrb5_extract_authz_data_from_sec_context , +.Nm gsskrb5_register_acceptor_identity , +.Nm gss_krb5_import_ccache , +.Nm gss_krb5_get_tkt_flags , +.Nm gss_process_context_token , +.Nm gss_release_buffer , +.Nm gss_release_cred , +.Nm gss_release_name , +.Nm gss_release_oid_set , +.Nm gss_seal , +.Nm gss_sign , +.Nm gss_test_oid_set_member , +.Nm gss_unseal , +.Nm gss_unwrap , +.Nm gss_verify , +.Nm gss_verify_mic , +.Nm gss_wrap , +.Nm gss_wrap_size_limit +.Nd Generic Security Service Application Program Interface library +.Sh LIBRARY +GSS-API library (libgssapi, -lgssapi) +.Sh SYNOPSIS +.In gssapi/gssapi.h +.Pp +.Ft OM_uint32 +.Fo gss_accept_sec_context +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t * context_handle" +.Fa "gss_const_cred_id_t acceptor_cred_handle" +.Fa "const gss_buffer_t input_token_buffer" +.Fa "const gss_channel_bindings_t input_chan_bindings" +.Fa "gss_name_t * src_name" +.Fa "gss_OID * mech_type" +.Fa "gss_buffer_t output_token" +.Fa "OM_uint32 * ret_flags" +.Fa "OM_uint32 * time_rec" +.Fa "gss_cred_id_t * delegated_cred_handle" +.Fc +.Pp +.Ft OM_uint32 +.Fo gss_acquire_cred +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t desired_name" +.Fa "OM_uint32 time_req" +.Fa "const gss_OID_set desired_mechs" +.Fa "gss_cred_usage_t cred_usage" +.Fa "gss_cred_id_t * output_cred_handle" +.Fa "gss_OID_set * actual_mechs" +.Fa "OM_uint32 * time_rec" +.Fc +.Ft OM_uint32 +.Fo gss_add_cred +.Fa "OM_uint32 *minor_status" +.Fa "gss_const_cred_id_t input_cred_handle" +.Fa "gss_const_name_t desired_name" +.Fa "const gss_OID desired_mech" +.Fa "gss_cred_usage_t cred_usage" +.Fa "OM_uint32 initiator_time_req" +.Fa "OM_uint32 acceptor_time_req" +.Fa "gss_cred_id_t *output_cred_handle" +.Fa "gss_OID_set *actual_mechs" +.Fa "OM_uint32 *initiator_time_rec" +.Fa "OM_uint32 *acceptor_time_rec" +.Fc +.Ft OM_uint32 +.Fo gss_add_oid_set_member +.Fa "OM_uint32 * minor_status" +.Fa "const gss_OID member_oid" +.Fa "gss_OID_set * oid_set" +.Fc +.Ft OM_uint32 +.Fo gss_canonicalize_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t input_name" +.Fa "const gss_OID mech_type" +.Fa "gss_name_t * output_name" +.Fc +.Ft OM_uint32 +.Fo gss_compare_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t name1" +.Fa "gss_const_name_t name2" +.Fa "int * name_equal" +.Fc +.Ft OM_uint32 +.Fo gss_context_time +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "OM_uint32 * time_rec" +.Fc +.Ft OM_uint32 +.Fo gss_create_empty_oid_set +.Fa "OM_uint32 * minor_status" +.Fa "gss_OID_set * oid_set" +.Fc +.Ft OM_uint32 +.Fo gss_delete_sec_context +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t * context_handle" +.Fa "gss_buffer_t output_token" +.Fc +.Ft OM_uint32 +.Fo gss_display_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t input_name" +.Fa "gss_buffer_t output_name_buffer" +.Fa "gss_OID * output_name_type" +.Fc +.Ft OM_uint32 +.Fo gss_display_status +.Fa "OM_uint32 *minor_status" +.Fa "OM_uint32 status_value" +.Fa "int status_type" +.Fa "const gss_OID mech_type" +.Fa "OM_uint32 *message_context" +.Fa "gss_buffer_t status_string" +.Fc +.Ft OM_uint32 +.Fo gss_duplicate_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t src_name" +.Fa "gss_name_t * dest_name" +.Fc +.Ft OM_uint32 +.Fo gss_export_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t input_name" +.Fa "gss_buffer_t exported_name" +.Fc +.Ft OM_uint32 +.Fo gss_export_sec_context +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t * context_handle" +.Fa "gss_buffer_t interprocess_token" +.Fc +.Ft OM_uint32 +.Fo gss_get_mic +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "gss_qop_t qop_req" +.Fa "const gss_buffer_t message_buffer" +.Fa "gss_buffer_t message_token" +.Fc +.Ft OM_uint32 +.Fo gss_import_name +.Fa "OM_uint32 * minor_status" +.Fa "const gss_buffer_t input_name_buffer" +.Fa "const gss_OID input_name_type" +.Fa "gss_name_t * output_name" +.Fc +.Ft OM_uint32 +.Fo gss_import_sec_context +.Fa "OM_uint32 * minor_status" +.Fa "const gss_buffer_t interprocess_token" +.Fa "gss_ctx_id_t * context_handle" +.Fc +.Ft OM_uint32 +.Fo gss_indicate_mechs +.Fa "OM_uint32 * minor_status" +.Fa "gss_OID_set * mech_set" +.Fc +.Ft OM_uint32 +.Fo gss_init_sec_context +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_cred_id_t initiator_cred_handle" +.Fa "gss_ctx_id_t * context_handle" +.Fa "gss_const_name_t target_name" +.Fa "const gss_OID mech_type" +.Fa "OM_uint32 req_flags" +.Fa "OM_uint32 time_req" +.Fa "const gss_channel_bindings_t input_chan_bindings" +.Fa "const gss_buffer_t input_token" +.Fa "gss_OID * actual_mech_type" +.Fa "gss_buffer_t output_token" +.Fa "OM_uint32 * ret_flags" +.Fa "OM_uint32 * time_rec" +.Fc +.Ft OM_uint32 +.Fo gss_inquire_context +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "gss_name_t * src_name" +.Fa "gss_name_t * targ_name" +.Fa "OM_uint32 * lifetime_rec" +.Fa "gss_OID * mech_type" +.Fa "OM_uint32 * ctx_flags" +.Fa "int * locally_initiated" +.Fa "int * open_context" +.Fc +.Ft OM_uint32 +.Fo gss_inquire_cred +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_cred_id_t cred_handle" +.Fa "gss_name_t * name" +.Fa "OM_uint32 * lifetime" +.Fa "gss_cred_usage_t * cred_usage" +.Fa "gss_OID_set * mechanisms" +.Fc +.Ft OM_uint32 +.Fo gss_inquire_cred_by_mech +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_cred_id_t cred_handle" +.Fa "const gss_OID mech_type" +.Fa "gss_name_t * name" +.Fa "OM_uint32 * initiator_lifetime" +.Fa "OM_uint32 * acceptor_lifetime" +.Fa "gss_cred_usage_t * cred_usage" +.Fc +.Ft OM_uint32 +.Fo gss_inquire_mechs_for_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_name_t input_name" +.Fa "gss_OID_set * mech_types" +.Fc +.Ft OM_uint32 +.Fo gss_inquire_names_for_mech +.Fa "OM_uint32 * minor_status" +.Fa "const gss_OID mechanism" +.Fa "gss_OID_set * name_types" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_ccache_name +.Fa "OM_uint32 *minor" +.Fa "const char *name" +.Fa "const char **old_name" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_copy_ccache +.Fa "OM_uint32 *minor" +.Fa "gss_cred_id_t cred" +.Fa "krb5_ccache out" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_import_cred +.Fa "OM_uint32 *minor_status" +.Fa "krb5_ccache id" +.Fa "krb5_principal keytab_principal" +.Fa "krb5_keytab keytab" +.Fa "gss_cred_id_t *cred" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_compat_des3_mic +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "int onoff" +.Fc +.Ft OM_uint32 +.Fo gsskrb5_extract_authz_data_from_sec_context +.Fa "OM_uint32 *minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "int ad_type" +.Fa "gss_buffer_t ad_data" +.Fc +.Ft OM_uint32 +.Fo gsskrb5_register_acceptor_identity +.Fa "const char *identity" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_import_cache +.Fa "OM_uint32 *minor" +.Fa "krb5_ccache id" +.Fa "krb5_keytab keytab" +.Fa "gss_cred_id_t *cred" +.Fc +.Ft OM_uint32 +.Fo gss_krb5_get_tkt_flags +.Fa "OM_uint32 *minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "OM_uint32 *tkt_flags" +.Fc +.Ft OM_uint32 +.Fo gss_process_context_token +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "const gss_buffer_t token_buffer" +.Fc +.Ft OM_uint32 +.Fo gss_release_buffer +.Fa "OM_uint32 * minor_status" +.Fa "gss_buffer_t buffer" +.Fc +.Ft OM_uint32 +.Fo gss_release_cred +.Fa "OM_uint32 * minor_status" +.Fa "gss_cred_id_t * cred_handle" +.Fc +.Ft OM_uint32 +.Fo gss_release_name +.Fa "OM_uint32 * minor_status" +.Fa "gss_name_t * input_name" +.Fc +.Ft OM_uint32 +.Fo gss_release_oid_set +.Fa "OM_uint32 * minor_status" +.Fa "gss_OID_set * set" +.Fc +.Ft OM_uint32 +.Fo gss_seal +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "int conf_req_flag" +.Fa "int qop_req" +.Fa "gss_buffer_t input_message_buffer" +.Fa "int * conf_state" +.Fa "gss_buffer_t output_message_buffer" +.Fc +.Ft OM_uint32 +.Fo gss_sign +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "int qop_req" +.Fa "gss_buffer_t message_buffer" +.Fa "gss_buffer_t message_token" +.Fc +.Ft OM_uint32 +.Fo gss_test_oid_set_member +.Fa "OM_uint32 * minor_status" +.Fa "const gss_OID member" +.Fa "const gss_OID_set set" +.Fa "int * present" +.Fc +.Ft OM_uint32 +.Fo gss_unseal +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "gss_buffer_t input_message_buffer" +.Fa "gss_buffer_t output_message_buffer" +.Fa "int * conf_state" +.Fa "int * qop_state" +.Fc +.Ft OM_uint32 +.Fo gss_unwrap +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "const gss_buffer_t input_message_buffer" +.Fa "gss_buffer_t output_message_buffer" +.Fa "int * conf_state" +.Fa "gss_qop_t * qop_state" +.Fc +.Ft OM_uint32 +.Fo gss_verify +.Fa "OM_uint32 * minor_status" +.Fa "gss_ctx_id_t context_handle" +.Fa "gss_buffer_t message_buffer" +.Fa "gss_buffer_t token_buffer" +.Fa "int * qop_state" +.Fc +.Ft OM_uint32 +.Fo gss_verify_mic +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "const gss_buffer_t message_buffer" +.Fa "const gss_buffer_t token_buffer" +.Fa "gss_qop_t * qop_state" +.Fc +.Ft OM_uint32 +.Fo gss_wrap +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "int conf_req_flag" +.Fa "gss_qop_t qop_req" +.Fa "const gss_buffer_t input_message_buffer" +.Fa "int * conf_state" +.Fa "gss_buffer_t output_message_buffer" +.Fc +.Ft OM_uint32 +.Fo gss_wrap_size_limit +.Fa "OM_uint32 * minor_status" +.Fa "gss_const_ctx_id_t context_handle" +.Fa "int conf_req_flag" +.Fa "gss_qop_t qop_req" +.Fa "OM_uint32 req_output_size" +.Fa "OM_uint32 * max_input_size" +.Fc +.Sh DESCRIPTION +Generic Security Service API (GSS-API) version 2, and its C binding, +is described in +.Li RFC2743 +and +.Li RFC2744 . +Version 1 (deprecated) of the C binding is described in +.Li RFC1509 . +.Pp +Heimdals GSS-API implementation supports the following mechanisms +.Bl -bullet +.It +.Li GSS_KRB5_MECHANISM +.It +.Li GSS_SPNEGO_MECHANISM +.El +.Pp +GSS-API have generic name types that all mechanism are supposed to +implement (if possible): +.Bl -bullet +.It +.Li GSS_C_NT_USER_NAME +.It +.Li GSS_C_NT_MACHINE_UID_NAME +.It +.Li GSS_C_NT_STRING_UID_NAME +.It +.Li GSS_C_NT_HOSTBASED_SERVICE +.It +.Li GSS_C_NT_ANONYMOUS +.It +.Li GSS_C_NT_EXPORT_NAME +.El +.Pp +GSS-API implementations that supports Kerberos 5 have some additional +name types: +.Bl -bullet +.It +.Li GSS_KRB5_NT_PRINCIPAL_NAME +.It +.Li GSS_KRB5_NT_USER_NAME +.It +.Li GSS_KRB5_NT_MACHINE_UID_NAME +.It +.Li GSS_KRB5_NT_STRING_UID_NAME +.El +.Pp +In GSS-API, names have two forms, internal names and contiguous string +names. +.Bl -bullet +.It +.Li Internal name and mechanism name +.Pp +Internal names are implementation specific representation of +a GSS-API name. +.Li Mechanism names +special form of internal names corresponds to one and only one mechanism. +.Pp +In GSS-API an internal name is stored in a +.Dv gss_name_t . +.It +.Li Contiguous string name and exported name +.Pp +Contiguous string names are gssapi names stored in a +.Dv OCTET STRING +that together with a name type identifier (OID) uniquely specifies a +gss-name. +A special form of the contiguous string name is the exported name that +have a OID embedded in the string to make it unique. +Exported name have the nametype +.Dv GSS_C_NT_EXPORT_NAME . +.Pp +In GSS-API an contiguous string name is stored in a +.Dv gss_buffer_t . +.Pp +Exported names also have the property that they are specified by the +mechanism itself and compatible between different GSS-API +implementations. +.El +.Sh ACCESS CONTROL +There are two ways of comparing GSS-API names, either comparing two +internal names with each other or two contiguous string names with +either other. +.Pp +To compare two internal names with each other, import (if needed) the +names with +.Fn gss_import_name +into the GSS-API implementation and the compare the imported name with +.Fn gss_compare_name . +.Pp +Importing names can be slow, so when its possible to store exported +names in the access control list, comparing contiguous string name +might be better. +.Pp +when comparing contiguous string name, first export them into a +.Dv GSS_C_NT_EXPORT_NAME +name with +.Fn gss_export_name +and then compare with +.Xr memcmp 3 . +.Pp +Note that there are might be a difference between the two methods of +comparing names. +The first (using +.Fn gss_compare_name ) +will compare to (unauthenticated) names are the same. +The second will compare if a mechanism will authenticate them as the +same principal. +.Pp +For example, if +.Fn gss_import_name +name was used with +.Dv GSS_C_NO_OID +the default syntax is used for all mechanism the GSS-API +implementation supports. +When compare the imported name of +.Dv GSS_C_NO_OID +it may match several mechanism names (MN). +.Pp +The resulting name from +.Fn gss_display_name +must not be used for acccess control. +.Sh FUNCTIONS +.Fn gss_display_name +takes the gss name in +.Fa input_name +and puts a printable form in +.Fa output_name_buffer . +.Fa output_name_buffer +should be freed when done using +.Fn gss_release_buffer . +.Fa output_name_type +can either be +.Dv NULL +or a pointer to a +.Li gss_OID +and will in the latter case contain the OID type of the name. +The name must only be used for printing. +If access control is needed, see section +.Sx ACCESS CONTROL . +.Pp +.Fn gss_inquire_context +returns information about the context. +Information is available even after the context have expired. +.Fa lifetime_rec +argument is set to +.Dv GSS_C_INDEFINITE +(don't expire) or the number of seconds that the context is still valid. +A value of 0 means that the context is expired. +.Fa mech_type +argument should be considered readonly and must not be released. +.Fa src_name +and +.Fn dest_name +are both mechanims names and must be released with +.Fn gss_release_name +when no longer used. +.Pp +.Nm gss_context_time +will return the amount of time (in seconds) of the context is still +valid. +If its expired +.Fa time_rec +will be set to 0 and +.Dv GSS_S_CONTEXT_EXPIRED +returned. +.Pp +.Fn gss_sign , +.Fn gss_verify , +.Fn gss_seal , +and +.Fn gss_unseal +are part of the GSS-API V1 interface and are obsolete. +The functions should not be used for new applications. +They are provided so that version 1 applications can link against the +library. +.Sh EXTENSIONS +.Fn gss_krb5_ccache_name +sets the internal kerberos 5 credential cache name to +.Fa name . +The old name is returned in +.Fa old_name , +and must not be freed. +The data allocated for +.Fa old_name +is free upon next call to +.Fn gss_krb5_ccache_name . +This function is not threadsafe if +.Fa old_name +argument is used. +.Pp +.Fn gss_krb5_copy_ccache +will extract the krb5 credentials that are transferred from the +initiator to the acceptor when using token delegation in the Kerberos +mechanism. +The acceptor receives the delegated token in the last argument to +.Fn gss_accept_sec_context . +.Pp +.Fn gss_krb5_import_cred +will import the krb5 credentials (both keytab and/or credential cache) +into gss credential so it can be used withing GSS-API. +The +.Fa ccache +is copied by reference and thus shared, so if the credential is destroyed +with +.Fa krb5_cc_destroy , +all users of thep +.Fa gss_cred_id_t +returned by +.Fn gss_krb5_import_ccache +will fail. +.Pp +.Fn gsskrb5_register_acceptor_identity +sets the Kerberos 5 filebased keytab that the acceptor will use. The +.Fa identifier +is the file name. +.Pp +.Fn gsskrb5_extract_authz_data_from_sec_context +extracts the Kerberos authorizationdata that may be stored within the +context. +Tha caller must free the returned buffer +.Fa ad_data +with +.Fn gss_release_buffer +upon success. +.Pp +.Fn gss_krb5_get_tkt_flags +return the ticket flags for the kerberos ticket receive when +authenticating the initiator. +Only valid on the acceptor context. +.Pp +.Fn gss_krb5_compat_des3_mic +turns on or off the compatibility with older version of Heimdal using +des3 get and verify mic, this is way to programmatically set the +[gssapi]broken_des3_mic and [gssapi]correct_des3_mic flags (see +COMPATIBILITY section in +.Xr gssapi 3 ) . +If the CPP symbol +.Dv GSS_C_KRB5_COMPAT_DES3_MIC +is present, +.Fn gss_krb5_compat_des3_mic +exists. +.Fn gss_krb5_compat_des3_mic +will be removed in a later version of the GSS-API library. +.Sh SEE ALSO +.Xr gssapi 3 , +.Xr krb5 3 , +.Xr krb5_ccache 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/gss_add_oid_set_member.3 b/static/netbsd/man3/gss_add_oid_set_member.3 new file mode 100644 index 00000000..97ff91e5 --- /dev/null +++ b/static/netbsd/man3/gss_add_oid_set_member.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_add_oid_set_member.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_canonicalize_name.3 b/static/netbsd/man3/gss_canonicalize_name.3 new file mode 100644 index 00000000..34dab710 --- /dev/null +++ b/static/netbsd/man3/gss_canonicalize_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_canonicalize_name.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_display_status.3 b/static/netbsd/man3/gss_display_status.3 new file mode 100644 index 00000000..32548189 --- /dev/null +++ b/static/netbsd/man3/gss_display_status.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_display_status.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_export_name.3 b/static/netbsd/man3/gss_export_name.3 new file mode 100644 index 00000000..3dfbe044 --- /dev/null +++ b/static/netbsd/man3/gss_export_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_export_name.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_import_name.3 b/static/netbsd/man3/gss_import_name.3 new file mode 100644 index 00000000..9b599c01 --- /dev/null +++ b/static/netbsd/man3/gss_import_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_import_name.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_init_sec_context.3 b/static/netbsd/man3/gss_init_sec_context.3 new file mode 100644 index 00000000..d9c1aa5c --- /dev/null +++ b/static/netbsd/man3/gss_init_sec_context.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_init_sec_context.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_inquire_attrs_for_mech.3 b/static/netbsd/man3/gss_inquire_attrs_for_mech.3 new file mode 100644 index 00000000..b6a3d99f --- /dev/null +++ b/static/netbsd/man3/gss_inquire_attrs_for_mech.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_inquire_attrs_for_mech.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_inquire_saslname_for_mech.3 b/static/netbsd/man3/gss_inquire_saslname_for_mech.3 new file mode 100644 index 00000000..06d71c87 --- /dev/null +++ b/static/netbsd/man3/gss_inquire_saslname_for_mech.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_inquire_saslname_for_mech.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_oid_equal.3 b/static/netbsd/man3/gss_oid_equal.3 new file mode 100644 index 00000000..0611390e --- /dev/null +++ b/static/netbsd/man3/gss_oid_equal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_oid_equal.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_release_cred.3 b/static/netbsd/man3/gss_release_cred.3 new file mode 100644 index 00000000..9e45c1c8 --- /dev/null +++ b/static/netbsd/man3/gss_release_cred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_release_cred.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_release_iov_buffer.3 b/static/netbsd/man3/gss_release_iov_buffer.3 new file mode 100644 index 00000000..f5ae5722 --- /dev/null +++ b/static/netbsd/man3/gss_release_iov_buffer.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_release_iov_buffer.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_release_name.3 b/static/netbsd/man3/gss_release_name.3 new file mode 100644 index 00000000..65674621 --- /dev/null +++ b/static/netbsd/man3/gss_release_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_release_name.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_unwrap_iov.3 b/static/netbsd/man3/gss_unwrap_iov.3 new file mode 100644 index 00000000..b209a2d0 --- /dev/null +++ b/static/netbsd/man3/gss_unwrap_iov.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_unwrap_iov.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_wrap.3 b/static/netbsd/man3/gss_wrap.3 new file mode 100644 index 00000000..537e1fe5 --- /dev/null +++ b/static/netbsd/man3/gss_wrap.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_wrap.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_wrap_iov.3 b/static/netbsd/man3/gss_wrap_iov.3 new file mode 100644 index 00000000..bd3b6b7c --- /dev/null +++ b/static/netbsd/man3/gss_wrap_iov.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_wrap_iov.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gss_wrap_iov_length.3 b/static/netbsd/man3/gss_wrap_iov_length.3 new file mode 100644 index 00000000..5641c5e1 --- /dev/null +++ b/static/netbsd/man3/gss_wrap_iov_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: gss_wrap_iov_length.3,v 1.2 2019/12/15 22:50:43 christos Exp $ +.\" +.so man3/gssapi.3 diff --git a/static/netbsd/man3/gssapi.3 b/static/netbsd/man3/gssapi.3 new file mode 100644 index 00000000..66c7fa37 --- /dev/null +++ b/static/netbsd/man3/gssapi.3 @@ -0,0 +1,436 @@ +.\" $NetBSD: gssapi.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "gssapi" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal GSS-API library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +gssapi \- Heimdal GSS-API functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_add_oid_set_member\fP (OM_uint32 *minor_status, const gss_OID member_oid, gss_OID_set *oid_set)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap_iov\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int *conf_state, gss_iov_buffer_desc *iov, int iov_count)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_unwrap_iov\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int *conf_state, gss_qop_t *qop_state, gss_iov_buffer_desc *iov, int iov_count)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap_iov_length\fP (OM_uint32 *minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int *conf_state, gss_iov_buffer_desc *iov, int iov_count)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_iov_buffer\fP (OM_uint32 *minor_status, gss_iov_buffer_desc *iov, int iov_count)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_canonicalize_name\fP (OM_uint32 *minor_status, gss_const_name_t input_name, const gss_OID mech_type, gss_name_t *output_name)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_display_status\fP (OM_uint32 *minor_status, OM_uint32 status_value, int status_type, const gss_OID mech_type, OM_uint32 *message_context, gss_buffer_t status_string)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_export_name\fP (OM_uint32 *minor_status, gss_const_name_t input_name, gss_buffer_t exported_name)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_import_name\fP (OM_uint32 *minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t *output_name)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_init_sec_context\fP (OM_uint32 *minor_status, gss_const_cred_id_t initiator_cred_handle, gss_ctx_id_t *context_handle, gss_const_name_t target_name, const gss_OID input_mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID *actual_mech_type, gss_buffer_t output_token, OM_uint32 *ret_flags, OM_uint32 *time_rec)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_inquire_saslname_for_mech\fP (OM_uint32 *minor_status, const gss_OID desired_mech, gss_buffer_t sasl_mech_name, gss_buffer_t mech_name, gss_buffer_t mech_description)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_inquire_attrs_for_mech\fP (OM_uint32 *minor_status, gss_const_OID mech, gss_OID_set *mech_attr, gss_OID_set *known_mech_attrs)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL \fBgss_oid_equal\fP (gss_const_OID a, gss_const_OID b)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_cred\fP (OM_uint32 *minor_status, gss_cred_id_t *cred_handle)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_release_name\fP (OM_uint32 *minor_status, gss_name_t *input_name)" +.br +.ti -1c +.RI "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL \fBgss_wrap\fP (OM_uint32 *minor_status, gss_const_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int *conf_state, gss_buffer_t output_message_buffer)" +.br +.in -1c +.SS "Variables" + +.in +1c +.ti -1c +.RI "gss_OID_desc GSSAPI_LIB_FUNCTION \fB__gss_c_attr_stream_sizes_oid_desc\fP" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_add_oid_set_member (OM_uint32 * minor_status, const gss_OID member_oid, gss_OID_set * oid_set)" +Add a oid to the oid set, function does not make a copy of the oid, so the pointer to member_oid needs to be stable for the whole time oid_set is used\&. +.PP +If there is a duplicate member of the oid, the new member is not added to to the set\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code\&. +.br +\fImember_oid\fP member to add to the oid set +.br +\fIoid_set\fP oid set to add the member too +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_canonicalize_name (OM_uint32 * minor_status, gss_const_name_t input_name, const gss_OID mech_type, gss_name_t * output_name)" +gss_canonicalize_name takes a Internal Name (IN) and converts in into a mechanism specific Mechanism Name (MN)\&. +.PP +The input name may multiple name, or generic name types\&. +.PP +If the input_name if of the GSS_C_NT_USER_NAME, and the Kerberos mechanism is specified, the resulting MN type is a GSS_KRB5_NT_PRINCIPAL_NAME\&. +.PP +For more information about \fBInternal names and mechanism names\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code\&. +.br +\fIinput_name\fP name to covert, unchanged by \fBgss_canonicalize_name()\fP\&. +.br +\fImech_type\fP the type to convert Name too\&. +.br +\fIoutput_name\fP the resulting type, release with \fBgss_release_name()\fP, independent of input_name\&. +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_display_status (OM_uint32 * minor_status, OM_uint32 status_value, int status_type, const gss_OID mech_type, OM_uint32 * message_context, gss_buffer_t status_string)" +Convert a GSS-API status code to text +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fIstatus_value\fP status value to convert +.br +\fIstatus_type\fP One of: GSS_C_GSS_CODE - status_value is a GSS status code, GSS_C_MECH_CODE - status_value is a mechanism status code +.br +\fImech_type\fP underlying mechanism\&. Use GSS_C_NO_OID to obtain the system default\&. +.br +\fImessage_context\fP state information to extract further messages from the status_value +.br +\fIstatus_string\fP the allocated text representation\&. Release with gss_release_buffer() +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_export_name (OM_uint32 * minor_status, gss_const_name_t input_name, gss_buffer_t exported_name)" +Convert a GGS-API name from internal form to contiguous string\&. +.PP +\fBSee also\fP +.RS 4 +\fBgss_import_name()\fP, \fBInternal names and mechanism names\fP\&. +.RE +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fIinput_name\fP input name in internal name form +.br +\fIexported_name\fP output name in contiguos string form +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_import_name (OM_uint32 * minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t * output_name)" +Convert a GGS-API name from contiguous string to internal form\&. +.PP +Type of name and their format: +.IP "\(bu" 2 +GSS_C_NO_OID +.IP "\(bu" 2 +GSS_C_NT_USER_NAME +.IP "\(bu" 2 +GSS_C_NT_HOSTBASED_SERVICE +.IP "\(bu" 2 +GSS_C_NT_EXPORT_NAME +.IP "\(bu" 2 +GSS_C_NT_ANONYMOUS +.IP "\(bu" 2 +GSS_KRB5_NT_PRINCIPAL_NAME +.PP +.PP +\fBSee also\fP +.RS 4 +\fBgss_export_name()\fP, \fBInternal names and mechanism names\fP\&. +.RE +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fIinput_name_buffer\fP import name buffer +.br +\fIinput_name_type\fP type of the import name buffer +.br +\fIoutput_name\fP the resulting type, release with \fBgss_release_name()\fP, independent of input_name +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_init_sec_context (OM_uint32 * minor_status, gss_const_cred_id_t initiator_cred_handle, gss_ctx_id_t * context_handle, gss_const_name_t target_name, const gss_OID input_mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID * actual_mech_type, gss_buffer_t output_token, OM_uint32 * ret_flags, OM_uint32 * time_rec)" +As the initiator build a context with an acceptor\&. +.PP +Returns in the major +.IP "\(bu" 2 +GSS_S_COMPLETE - if the context if build +.IP "\(bu" 2 +GSS_S_CONTINUE_NEEDED - if the caller needs to continue another round of gss_i nit_sec_context +.IP "\(bu" 2 +error code - any other error code +.PP +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code\&. +.br +\fIinitiator_cred_handle\fP the credential to use when building the context, if GSS_C_NO_CREDENTIAL is passed, the default credential for the mechanism will be used\&. +.br +\fIcontext_handle\fP a pointer to a context handle, will be returned as long as there is not an error\&. +.br +\fItarget_name\fP the target name of acceptor, created using \fBgss_import_name()\fP\&. The name is can be of any name types the mechanism supports, check supported name types with gss_inquire_names_for_mech()\&. +.br +\fIinput_mech_type\fP mechanism type to use, if GSS_C_NO_OID is used, Kerberos (GSS_KRB5_MECHANISM) will be tried\&. Other available mechanism are listed in the \fBGSS-API mechanisms\fP section\&. +.br +\fIreq_flags\fP flags using when building the context, see \fBContext creation flags\fP +.br +\fItime_req\fP time requested this context should be valid in seconds, common used value is GSS_C_INDEFINITE +.br +\fIinput_chan_bindings\fP Channel bindings used, if not exepected otherwise, used GSS_C_NO_CHANNEL_BINDINGS +.br +\fIinput_token\fP input token sent from the acceptor, for the initial packet the buffer of { NULL, 0 } should be used\&. +.br +\fIactual_mech_type\fP the actual mech used, MUST NOT be freed since it pointing to static memory\&. +.br +\fIoutput_token\fP if there is an output token, regardless of complete, continue_needed, or error it should be sent to the acceptor +.br +\fIret_flags\fP return what flags was negotitated, caller should check if they are accetable\&. For example, if GSS_C_MUTUAL_FLAG was negotiated with the acceptor or not\&. +.br +\fItime_rec\fP amount of time this context is valid for +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_attrs_for_mech (OM_uint32 * minor_status, gss_const_OID mech, gss_OID_set * mech_attr, gss_OID_set * known_mech_attrs)" +List support attributes for a mech and/or all mechanisms\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fImech\fP given together with mech_attr will return the list of attributes for mechanism, can optionally be GSS_C_NO_OID\&. +.br +\fImech_attr\fP see mech parameter, can optionally be NULL, release with gss_release_oid_set()\&. +.br +\fIknown_mech_attrs\fP all attributes for mechanisms supported, release with gss_release_oid_set()\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_saslname_for_mech (OM_uint32 * minor_status, const gss_OID desired_mech, gss_buffer_t sasl_mech_name, gss_buffer_t mech_name, gss_buffer_t mech_description)" +Returns different protocol names and description of the mechanism\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fIdesired_mech\fP mech list query +.br +\fIsasl_mech_name\fP SASL GS2 protocol name +.br +\fImech_name\fP gssapi protocol name +.br +\fImech_description\fP description of gssapi mech +.RE +.PP +\fBReturns\fP +.RS 4 +returns GSS_S_COMPLETE or a error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL gss_oid_equal (gss_const_OID a, gss_const_OID b)" +Compare two GSS-API OIDs with each other\&. +.PP +GSS_C_NO_OID matches nothing, not even it-self\&. +.PP +\fBParameters\fP +.RS 4 +\fIa\fP first oid to compare +.br +\fIb\fP second oid to compare +.RE +.PP +\fBReturns\fP +.RS 4 +non-zero when both oid are the same OID, zero when they are not the same\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_cred (OM_uint32 * minor_status, gss_cred_id_t * cred_handle)" +Release a credentials +.PP +Its ok to release the GSS_C_NO_CREDENTIAL/NULL credential, it will return a GSS_S_COMPLETE error code\&. On return cred_handle is set ot GSS_C_NO_CREDENTIAL\&. +.PP +Example: +.PP +.PP +.nf +gss_cred_id_t cred = GSS_C_NO_CREDENTIAL; +major = gss_release_cred(&minor, &cred); +.fi +.PP +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status return code, mech specific +.br +\fIcred_handle\fP a pointer to the credential too release +.RE +.PP +\fBReturns\fP +.RS 4 +an gssapi error code +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_iov_buffer (OM_uint32 * minor_status, gss_iov_buffer_desc * iov, int iov_count)" +Free all buffer allocated by \fBgss_wrap_iov()\fP or \fBgss_unwrap_iov()\fP by looking at the GSS_IOV_BUFFER_FLAG_ALLOCATED flag\&. +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_name (OM_uint32 * minor_status, gss_name_t * input_name)" +Free a name +.PP +import_name can point to NULL or be NULL, or a pointer to a gss_name_t structure\&. If it was a pointer to gss_name_t, the pointer will be set to NULL on success and failure\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code +.br +\fIinput_name\fP name to free +.RE +.PP +\fBReturns\fP +.RS 4 +a gss_error code, see \fBgss_display_status()\fP about printing the error code\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_unwrap_iov (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int * conf_state, gss_qop_t * qop_state, gss_iov_buffer_desc * iov, int iov_count)" +Decrypt or verifies the signature on the data\&. +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap (OM_uint32 * minor_status, gss_const_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int * conf_state, gss_buffer_t output_message_buffer)" +Wrap a message using either confidentiality (encryption + signature) or sealing (signature)\&. +.PP +\fBParameters\fP +.RS 4 +\fIminor_status\fP minor status code\&. +.br +\fIcontext_handle\fP context handle\&. +.br +\fIconf_req_flag\fP if non zero, confidentiality is requestd\&. +.br +\fIqop_req\fP type of protection needed, in most cases it GSS_C_QOP_DEFAULT should be passed in\&. +.br +\fIinput_message_buffer\fP messages to wrap +.br +\fIconf_state\fP returns non zero if confidentiality was honoured\&. +.br +\fIoutput_message_buffer\fP the resulting buffer, release with gss_release_buffer()\&. +.RE +.PP + +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int * conf_state, gss_iov_buffer_desc * iov, int iov_count)" +Encrypts or sign the data\&. +.PP +This is a more complicated version of \fBgss_wrap()\fP, it allows the caller to use AEAD data (signed header/trailer) and allow greater controll over where the encrypted data is placed\&. +.PP +The maximum packet size is gss_context_stream_sizes\&.max_msg_size\&. +.PP +The caller needs provide the folloing buffers when using in conf_req_flag=1 mode: +.PP +.IP "\(bu" 2 +HEADER (of size gss_context_stream_sizes\&.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes\&.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes\&.trailer) +.IP "\(bu" 2 +on DCE-RPC mode, the caller can skip PADDING and TRAILER if the DATA elements is padded to a block bountry and header is of at least size gss_context_stream_sizes\&.header + gss_context_stream_sizes\&.trailer\&. +.PP +.PP +HEADER, PADDING, TRAILER will be shrunken to the size required to transmit any of them too large\&. +.PP +To generate \fBgss_wrap()\fP compatible packets, use: HEADER | DATA | PADDING | TRAILER +.PP +When used in conf_req_flag=0, +.PP +.IP "\(bu" 2 +HEADER (of size gss_context_stream_sizes\&.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes\&.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes\&.trailer) +.PP +.PP +The input sizes of HEADER, PADDING and TRAILER can be fetched using \fBgss_wrap_iov_length()\fP or gss_context_query_attributes()\&. +.SS "GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov_length (OM_uint32 * minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int * conf_state, gss_iov_buffer_desc * iov, int iov_count)" +Update the length fields in iov buffer for the types: +.IP "\(bu" 2 +GSS_IOV_BUFFER_TYPE_HEADER +.IP "\(bu" 2 +GSS_IOV_BUFFER_TYPE_PADDING +.IP "\(bu" 2 +GSS_IOV_BUFFER_TYPE_TRAILER +.PP +.PP +Consider using gss_context_query_attributes() to fetch the data instead\&. +.SH "Variable Documentation" +.PP +.SS "gss_OID_desc GSSAPI_LIB_FUNCTION __gss_c_attr_stream_sizes_oid_desc" +\fBInitial value:\fP +.PP +.nf += + {10, rk_UNCONST("\x2a\x86\x48\x86\xf7\x12\x01\x02\x01\x03")} +.fi +Query the context for parameters\&. +.PP +SSPI equivalent if this function is QueryContextAttributes\&. +.PP +.IP "\(bu" 2 +GSS_C_ATTR_STREAM_SIZES data is a gss_context_stream_sizes\&. +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal GSS-API library from the source code\&. diff --git a/static/netbsd/man3/gssapi_mechs_intro.3 b/static/netbsd/man3/gssapi_mechs_intro.3 new file mode 100644 index 00000000..119a46e1 --- /dev/null +++ b/static/netbsd/man3/gssapi_mechs_intro.3 @@ -0,0 +1,18 @@ +.\" $NetBSD: gssapi_mechs_intro.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "gssapi_mechs_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal GSS-API library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +gssapi_mechs_intro \- GSS-API mechanisms + +.SH "GSS-API mechanisms" +.PP +.IP "\(bu" 2 +Kerberos 5 - GSS_KRB5_MECHANISM +.IP "\(bu" 2 +SPNEGO - GSS_SPNEGO_MECHANISM +.IP "\(bu" 2 +NTLM - GSS_NTLM_MECHANISM +.PP + diff --git a/static/netbsd/man3/gssapi_services_intro.3 b/static/netbsd/man3/gssapi_services_intro.3 new file mode 100644 index 00000000..e80566a9 --- /dev/null +++ b/static/netbsd/man3/gssapi_services_intro.3 @@ -0,0 +1,68 @@ +.\" $NetBSD: gssapi_services_intro.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "gssapi_services_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal GSS-API library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +gssapi_services_intro \- Introduction to GSS-API services + +.SH "GSS-API services" +.PP +.SS "Context creation" +.IP "\(bu" 2 +delegation +.IP "\(bu" 2 +mutual authentication +.IP "\(bu" 2 +anonymous +.IP "\(bu" 2 +use per message before context creation has completed +.PP +.PP +return status: +.IP "\(bu" 2 +support conf +.IP "\(bu" 2 +support int +.PP +.SS "Context creation flags" +.IP "\(bu" 2 +GSS_C_DELEG_FLAG +.IP "\(bu" 2 +GSS_C_MUTUAL_FLAG +.IP "\(bu" 2 +GSS_C_REPLAY_FLAG +.IP "\(bu" 2 +GSS_C_SEQUENCE_FLAG +.IP "\(bu" 2 +GSS_C_CONF_FLAG +.IP "\(bu" 2 +GSS_C_INTEG_FLAG +.IP "\(bu" 2 +GSS_C_ANON_FLAG +.IP "\(bu" 2 +GSS_C_PROT_READY_FLAG +.IP "\(bu" 2 +GSS_C_TRANS_FLAG +.IP "\(bu" 2 +GSS_C_DCE_STYLE +.IP "\(bu" 2 +GSS_C_IDENTIFY_FLAG +.IP "\(bu" 2 +GSS_C_EXTENDED_ERROR_FLAG +.IP "\(bu" 2 +GSS_C_DELEG_POLICY_FLAG +.PP +.SS "Per-message services" +.IP "\(bu" 2 +conf +.IP "\(bu" 2 +int +.IP "\(bu" 2 +message integrity +.IP "\(bu" 2 +replay detection +.IP "\(bu" 2 +out of sequence +.PP + diff --git a/static/netbsd/man3/hash.3 b/static/netbsd/man3/hash.3 new file mode 100644 index 00000000..eaac286c --- /dev/null +++ b/static/netbsd/man3/hash.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: hash.3,v 1.14 2010/12/16 11:57:20 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" +.Dd December 16, 2010 +.Dt HASH 3 +.Os +.Sh NAME +.Nm hash +.Nd hash database access method +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is hash files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the hash specific information. +.Pp +The hash data structure is an extensible, dynamic hashing scheme. +.Pp +The access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +header as follows: +.Bd -literal -offset indent +typedef struct { + u_int bsize; + u_int ffactor; + u_int nelem; + u_int cachesize; + uint32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.Ed +.Pp +The elements of this structure are as follows: +.Bl -tag -width cachesizex +.It Fa bsize +.Fa bsize +defines the hash table bucket size, and defaults to 4096 for in-memory tables. +If +.Fa bsize +is 0 (no bucket size is specified) a bucket size is chosen based on the +underlying file system I/O block size. +It may be preferable to increase the page size for disk-resident +tables and tables with large data items. +.It Fa ffactor +.Fa ffactor +indicates a desired density within the hash table. +It is an approximation of the number of keys allowed to accumulate in +any one bucket, determining when the hash table grows or shrinks. +The default value is 8. +.It Fa nelem +.Fa nelem +is an estimate of the final size of the hash table. +If not set or set too low, hash tables will expand gracefully as keys +are entered, although a slight performance degradation may be +noticed. +The default value is 1. +.It Fa cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather +than fail. +.It Fa hash +.Fa hash +is a user defined hash function. +Since no hash function performs equally well on all possible data, the +user may find that the built-in hash function does poorly on a +particular data set. +User specified hash functions must take two arguments (a pointer to a +byte string and a length) and return a 32-bit quantity to be used as +the hash value. +.It Fa lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Fa lorder +is 0 (no order is specified) the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.El +.Pp +If the file already exists (and the +.Dv O_TRUNC +flag is not specified), the values specified for the parameters +.Fa bsize , +.Fa ffactor , +.Fa lorder , +and +.Fa nelem +are ignored and the values specified when the tree was created are +used. +.Pp +If a hash function is specified, +.Fn hash_open +will attempt to determine if the hash function specified is the same +as the one with which the database was created, and will fail if it is +not. +.\".Pp +.\"Backward compatible interfaces to the routines described in +.\".Xr dbm 3 , +.\"and +.\".Xr ndbm 3 +.\"are provided, however these interfaces are not compatible with +.\"previous file formats. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr mpool 3 , +.Xr recno 3 +.Pp +.Rs +.%T Dynamic Hash Tables +.%A Per-Ake Larson +.%J Communications of the ACM +.%D April 1988 +.%N Issue 4 +.%V Volume 31 +.Re +.Rs +.%T A New Hash Package for UNIX +.%A Margo Seltzer +.%I USENIX Association +.%B Proceedings of the 1991 Winter USENIX Technical Conference +.%D January 1991 +.%P 173-184 +.%U http://www.usenix.org/publications/library/proceedings/seltzer2.pdf +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/static/netbsd/man3/hcreate.3 b/static/netbsd/man3/hcreate.3 new file mode 100644 index 00000000..e846a482 --- /dev/null +++ b/static/netbsd/man3/hcreate.3 @@ -0,0 +1,333 @@ +.\" $NetBSD: hcreate.3,v 1.15 2023/02/21 19:27:14 rillig Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 7, 2017 +.Dt HCREATE 3 +.Os +.Sh NAME +.Nm hcreate , +.Nm hcreate_r , +.Nm hdestroy , +.Nm hdestroy1 , +.Nm hdestroy_r , +.Nm hdestroy1_r , +.Nm hsearch , +.Nm hsearch_r +.Nd manage hash search table +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In search.h +.Ft int +.Fn hcreate "size_t nel" +.Ft int +.Fn hcreate_r "size_t nel" "struct hsearch_data *table" +.Ft void +.Fn hdestroy "void" +.Ft void +.Fn hdestroy1 "void (*freekey)(void *)" "void (*freedata)(void *)" +.Ft void +.Fn hdestroy_r "struct hsearch_data *table" +.Ft void +.Fn hdestroy1_r "struct hsearch_data *table" "void (*freekey)(void *)" "void (*freedata)(void *)" +.Ft ENTRY * +.Fn hsearch "ENTRY item" "ACTION action" +.Ft int +.Fn hsearch_r "ENTRY item" "ACTION action" "ENTRY ** itemp" "struct hsearch_data *table" +.Sh DESCRIPTION +The +.Fn hcreate , +.Fn hcreate_r , +.Fn hdestroy , +.Fn hdestroy_r +.Fn hdestroy1 , +.Fn hdestroy1_r +.Fn hsearch , +and +.Fn hsearch_r +functions manage hash search tables. +.Pp +The +.Fn hcreate +function allocates and initializes the table. +The +.Fa nel +argument specifies an estimate of the maximum number of entries to be held +by the table. +Unless further memory allocation fails, supplying an insufficient +.Fa nel +value will not result in functional harm, although a performance degradation +may occur. +Initialization using the +.Fn hcreate +function is mandatory prior to any access operations using +.Fn hsearch . +.Pp +The +.Fn hdestroy +function destroys a table previously created using +.Fn hcreate . +After a call to +.Fn hdestroy , +the data can no longer be accessed. +.Pp +The +.Fn hsearch +function is used to search the hash table. +It returns a pointer into the +hash table indicating the address of an item. +The +.Fa item +argument is of type +.Vt ENTRY , +defined in the +.In search.h +header. +This is a structure type that contains two pointers: +.Pp +.Bl -tag -compact -offset indent -width "void *data " +.It Fa char *key +comparison key +.It Fa void *data +pointer to data associated with +.Fa key +.El +.Pp +The key comparison function used by +.Fn hsearch +is +.Xr strcmp 3 . +.Pp +The +.Fa action +argument is of type +.Vt ACTION , +an enumeration type which defines the following values: +.Bl -tag -offset indent -width ENTERXX +.It Dv ENTER +Insert +.Fa item +into the hash table. +If an existing item with the same key is found, it is not replaced. +Note that the +.Fa key +and +.Fa data +elements of +.Fa item +are used directly by the new table entry. +The storage for the +key must not be modified during the lifetime of the hash table. +.It Dv FIND +Search the hash table without inserting +.Fa item . +.El +.Pp +The traditional +.Fn hdestroy +and +.Fn hdestroy_r +functions don't +.Xr free 3 +the data associated with the +.Fa key +and +.Fa value +of each entry, because they did not allocate them. +Since there is no +.Dq iterator +function provided, the +.Fn hdestroy1 +and +.Fn hdestroy1_r +allow controlling how the +.Fa key +or +.Fa value +will be freed using the +provided functions in the +.Fa freekey +and +.Fa freedata +arguments. +If they are +.Dv NULL , +then +.Fa key +and +.Fa value +are not freed. +.Pp +The +.Fn hcreate_r , +.Fn hdestroy_r , +.Fn hdestroy1_r , +and +.Fn hsearch_r +functions are re-entrant versions of the above functions that can +operate on a table supplied by the user. +The +.Fn hsearch_r +function returns +.Dv 0 +if the action is +.Dv ENTER +and the element cannot be created, +.Dv 1 +otherwise. +If the element exists or can be created, it will be placed in +.Fa itemp , +otherwise +.Fa itemp +will be set to +.Dv NULL . +.Sh RETURN VALUES +If successful, the +.Fn hcreate +and +.Fn hcreate_r +functions return a non-zero value. +Otherwise, a value of +.Dv 0 +is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn hdestroy +and +.Fn hdestroy_r +functions return no value. +.Pp +If successful, the +.Fn hsearch +function returns a pointer to hash table entry matching +the provided key. +If the action is +.Dv FIND +and the item was not found, or if the action is +.Dv ENTER +and the insertion failed, +.Dv NULL +is returned and +.Va errno +is set to indicate the error. +If the action is +.Dv ENTER +and an entry already existed in the table matching the given +key, the existing entry is returned and is not replaced. +.Pp +The +.Fn hsearch_r +function returns +.Dv 1 +unless the table is full, when it returns +.Dv 0 . +If +.Fn hsearch +returns +.Dv 0 +or the element is not found, +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn hcreate , +.Fn hcreate_r , +.Fn hsearch +and +.Fn hsearch_r +functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory is available. +.El +.Pp +The +.Fn hsearch +and +.Fn hsearch_r +functions will also fail if the action is +.Dv FIND +and the element is not found: +.Bl -tag -width Er +.It Bq Er ESRCH +The +.Fa item +given is not found. +.El +.Sh SEE ALSO +.Xr bsearch 3 , +.Xr free 3 , +.Xr lsearch 3 , +.Xr malloc 3 , +.Xr strcmp 3 +.Sh STANDARDS +The +.Fn hcreate , +.Fn hdestroy +and +.Fn hsearch +functions conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn hcreate , +.Fn hdestroy +and +.Fn hsearch +functions first appeared in +.At V . +The +.Fn hcreate_r , +.Fn hdestroy_r , +and +.Fn hsearch_r +functions are +.Tn GNU +extensions. +The +.Fn hdestroy1 +and +.Fn hdestroy1_r +are +.Nx +extensions. +.Sh CAVEATS +At least the following limitations can be mentioned: +.Bl -bullet +.It +The original, +.Pf non- Tn GNU +interface permits the use of only one hash table at a time. +.It +Individual hash table entries can be added, but not deleted. +.It +There is no iterator to scan for all entries in the table. +.El diff --git a/static/netbsd/man3/hcrypto_core.3 b/static/netbsd/man3/hcrypto_core.3 new file mode 100644 index 00000000..cbd00747 --- /dev/null +++ b/static/netbsd/man3/hcrypto_core.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: hcrypto_core.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_core" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_core \- hcrypto function controlling behavior +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBEVP_CIPHER_CTX_rand_key\fP (EVP_CIPHER_CTX *ctx, void *key)" +.br +.ti -1c +.RI "int \fBEVP_CIPHER_CTX_ctrl\fP (EVP_CIPHER_CTX *ctx, int type, int arg, void *data)" +.br +.ti -1c +.RI "void \fBOpenSSL_add_all_algorithms\fP (void)" +.br +.ti -1c +.RI "void \fBOpenSSL_add_all_algorithms_conf\fP (void)" +.br +.ti -1c +.RI "void \fBOpenSSL_add_all_algorithms_noconf\fP (void)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int EVP_CIPHER_CTX_ctrl (EVP_CIPHER_CTX * ctx, int type, int arg, void * data)" +Perform a operation on a ctx +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP context to perform operation on\&. +.br +\fItype\fP type of operation\&. +.br +\fIarg\fP argument to operation\&. +.br +\fIdata\fP addition data to operation\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 for success, 0 for failure\&. +.RE +.PP + +.SS "int EVP_CIPHER_CTX_rand_key (EVP_CIPHER_CTX * ctx, void * key)" +Generate a random key for the specificed EVP_CIPHER\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP EVP_CIPHER_CTX type to build the key for\&. +.br +\fIkey\fP return key, must be at least \fBEVP_CIPHER_key_length()\fP byte long\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 for success, 0 for failure\&. +.RE +.PP + +.SS "void OpenSSL_add_all_algorithms (void)" +Add all algorithms to the crypto core\&. +.SS "void OpenSSL_add_all_algorithms_conf (void)" +Add all algorithms to the crypto core using configuration file\&. +.SS "void OpenSSL_add_all_algorithms_noconf (void)" +Add all algorithms to the crypto core, but don't use the configuration file\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_des.3 b/static/netbsd/man3/hcrypto_des.3 new file mode 100644 index 00000000..9e7533f4 --- /dev/null +++ b/static/netbsd/man3/hcrypto_des.3 @@ -0,0 +1,381 @@ +.\" $NetBSD: hcrypto_des.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_des" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_des \- DES crypto functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBDES_set_odd_parity\fP (DES_cblock *key)" +.br +.ti -1c +.RI "int HC_DEPRECATED \fBDES_check_key_parity\fP (DES_cblock *key)" +.br +.ti -1c +.RI "int \fBDES_is_weak_key\fP (DES_cblock *key)" +.br +.ti -1c +.RI "int HC_DEPRECATED \fBDES_set_key\fP (DES_cblock *key, DES_key_schedule *ks)" +.br +.ti -1c +.RI "int \fBDES_set_key_unchecked\fP (DES_cblock *key, DES_key_schedule *ks)" +.br +.ti -1c +.RI "int \fBDES_set_key_checked\fP (DES_cblock *key, DES_key_schedule *ks)" +.br +.ti -1c +.RI "int \fBDES_key_sched\fP (DES_cblock *key, DES_key_schedule *ks)" +.br +.ti -1c +.RI "void \fBDES_encrypt\fP (uint32_t u[2], DES_key_schedule *ks, int encp)" +.br +.ti -1c +.RI "void \fBDES_ecb_encrypt\fP (DES_cblock *input, DES_cblock *output, DES_key_schedule *ks, int encp)" +.br +.ti -1c +.RI "void \fBDES_cbc_encrypt\fP (const void *in, void *out, long length, DES_key_schedule *ks, DES_cblock *iv, int encp)" +.br +.ti -1c +.RI "void \fBDES_pcbc_encrypt\fP (const void *in, void *out, long length, DES_key_schedule *ks, DES_cblock *iv, int encp)" +.br +.ti -1c +.RI "void \fBDES_ecb3_encrypt\fP (DES_cblock *input, DES_cblock *output, DES_key_schedule *ks1, DES_key_schedule *ks2, DES_key_schedule *ks3, int encp)" +.br +.ti -1c +.RI "void \fBDES_ede3_cbc_encrypt\fP (const void *in, void *out, long length, DES_key_schedule *ks1, DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *iv, int encp)" +.br +.ti -1c +.RI "void \fBDES_cfb64_encrypt\fP (const void *in, void *out, long length, DES_key_schedule *ks, DES_cblock *iv, int *num, int encp)" +.br +.ti -1c +.RI "uint32_t \fBDES_cbc_cksum\fP (const void *in, DES_cblock *output, long length, DES_key_schedule *ks, DES_cblock *iv)" +.br +.ti -1c +.RI "void \fBDES_string_to_key\fP (const char *str, DES_cblock *key)" +.br +.ti -1c +.RI "int HC_DEPRECATED \fBDES_new_random_key\fP (DES_cblock *key)" +.br +.ti -1c +.RI "void HC_DEPRECATED \fBDES_init_random_number_generator\fP (DES_cblock *seed)" +.br +.ti -1c +.RI "void HC_DEPRECATED \fBDES_random_key\fP (DES_cblock *key)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBDES - Data Encryption Standard crypto interface\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "uint32_t DES_cbc_cksum (const void * in, DES_cblock * output, long length, DES_key_schedule * ks, DES_cblock * iv)" +Crete a checksum using DES in CBC encryption mode\&. This mode is only used for Kerberos 4, and it should stay that way\&. +.PP +The IV must always be diffrent for diffrent input data blocks\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP data to checksum +.br +\fIoutput\fP the checksum +.br +\fIlength\fP length of data +.br +\fIks\fP key schedule to use +.br +\fIiv\fP initial vector to use +.RE +.PP + +.SS "void DES_cbc_encrypt (const void * in, void * out, long length, DES_key_schedule * ks, DES_cblock * iv, int encp)" +Encrypt/decrypt a block using DES in Chain Block Cipher mode (cbc)\&. +.PP +The IV must always be diffrent for diffrent input data blocks\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP data to encrypt +.br +\fIout\fP data to encrypt +.br +\fIlength\fP length of data +.br +\fIks\fP key schedule to use +.br +\fIiv\fP initial vector to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void DES_cfb64_encrypt (const void * in, void * out, long length, DES_key_schedule * ks, DES_cblock * iv, int * num, int encp)" +Encrypt/decrypt using DES in cipher feedback mode with 64 bit feedback\&. +.PP +The IV must always be diffrent for diffrent input data blocks\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP data to encrypt +.br +\fIout\fP data to encrypt +.br +\fIlength\fP length of data +.br +\fIks\fP key schedule to use +.br +\fIiv\fP initial vector to use +.br +\fInum\fP offset into in cipher block encryption/decryption stop last time\&. +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "int HC_DEPRECATED DES_check_key_parity (DES_cblock * key)" +Check if the key have correct parity\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP key to check the parity\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, 0 on failure\&. +.RE +.PP + +.SS "void DES_ecb3_encrypt (DES_cblock * input, DES_cblock * output, DES_key_schedule * ks1, DES_key_schedule * ks2, DES_key_schedule * ks3, int encp)" +Encrypt/decrypt a block using triple DES using EDE mode, encrypt/decrypt/encrypt\&. +.PP +\fBParameters\fP +.RS 4 +\fIinput\fP data to encrypt +.br +\fIoutput\fP data to encrypt +.br +\fIks1\fP key schedule to use +.br +\fIks2\fP key schedule to use +.br +\fIks3\fP key schedule to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void DES_ecb_encrypt (DES_cblock * input, DES_cblock * output, DES_key_schedule * ks, int encp)" +Encrypt/decrypt a block using DES\&. +.PP +\fBParameters\fP +.RS 4 +\fIinput\fP data to encrypt +.br +\fIoutput\fP data to encrypt +.br +\fIks\fP key schedule to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void DES_ede3_cbc_encrypt (const void * in, void * out, long length, DES_key_schedule * ks1, DES_key_schedule * ks2, DES_key_schedule * ks3, DES_cblock * iv, int encp)" +Encrypt/decrypt using Triple DES in Chain Block Cipher mode (cbc)\&. +.PP +The IV must always be diffrent for diffrent input data blocks\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP data to encrypt +.br +\fIout\fP data to encrypt +.br +\fIlength\fP length of data +.br +\fIks1\fP key schedule to use +.br +\fIks2\fP key schedule to use +.br +\fIks3\fP key schedule to use +.br +\fIiv\fP initial vector to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void DES_encrypt (uint32_t u[2], DES_key_schedule * ks, int encp)" +Encrypt/decrypt a block using DES\&. Also called ECB mode +.PP +\fBParameters\fP +.RS 4 +\fIu\fP data to encrypt +.br +\fIks\fP key schedule to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void HC_DEPRECATED DES_init_random_number_generator (DES_cblock * seed)" +Seed the random number generator\&. Deprecated, use \fBRAND - random number\fP +.PP +\fBParameters\fP +.RS 4 +\fIseed\fP a seed to seed that random number generate with\&. +.RE +.PP + +.SS "int DES_is_weak_key (DES_cblock * key)" +Checks if the key is any of the weaks keys that makes DES attacks trival\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP key to check\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 if the key is weak, 0 otherwise\&. +.RE +.PP + +.SS "int DES_key_sched (DES_cblock * key, DES_key_schedule * ks)" +Compatibility function for eay libdes, works just like \fBDES_set_key_checked()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP a key to initialize the key schedule with\&. +.br +\fIks\fP a key schedule to initialize\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, -1 on invalid parity, -2 on weak key\&. +.RE +.PP + +.SS "int HC_DEPRECATED DES_new_random_key (DES_cblock * key)" +Generate a random des key using a random block, fixup parity and skip weak keys\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP is set to a random key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, non zero on random number generator failure\&. +.RE +.PP + +.SS "void DES_pcbc_encrypt (const void * in, void * out, long length, DES_key_schedule * ks, DES_cblock * iv, int encp)" +Encrypt/decrypt a block using DES in Propagating Cipher Block Chaining mode\&. This mode is only used for Kerberos 4, and it should stay that way\&. +.PP +The IV must always be diffrent for diffrent input data blocks\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP data to encrypt +.br +\fIout\fP data to encrypt +.br +\fIlength\fP length of data +.br +\fIks\fP key schedule to use +.br +\fIiv\fP initial vector to use +.br +\fIencp\fP if non zero, encrypt\&. if zero, decrypt\&. +.RE +.PP + +.SS "void HC_DEPRECATED DES_random_key (DES_cblock * key)" +Generate a random key, deprecated since it doesn't return an error code, use \fBDES_new_random_key()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP is set to a random key\&. +.RE +.PP + +.SS "int HC_DEPRECATED DES_set_key (DES_cblock * key, DES_key_schedule * ks)" +Setup a des key schedule from a key\&. Deprecated function, use \fBDES_set_key_unchecked()\fP or \fBDES_set_key_checked()\fP instead\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP a key to initialize the key schedule with\&. +.br +\fIks\fP a key schedule to initialize\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success +.RE +.PP + +.SS "int DES_set_key_checked (DES_cblock * key, DES_key_schedule * ks)" +Just like \fBDES_set_key_unchecked()\fP except checking that the key is not weak for or have correct parity\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP a key to initialize the key schedule with\&. +.br +\fIks\fP a key schedule to initialize\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, -1 on invalid parity, -2 on weak key\&. +.RE +.PP + +.SS "int DES_set_key_unchecked (DES_cblock * key, DES_key_schedule * ks)" +Setup a des key schedule from a key\&. The key is no longer needed after this transaction and can cleared\&. +.PP +Does NOT check that the key is weak for or have wrong parity\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP a key to initialize the key schedule with\&. +.br +\fIks\fP a key schedule to initialize\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success +.RE +.PP + +.SS "void DES_set_odd_parity (DES_cblock * key)" +Set the parity of the key block, used to generate a des key from a random key\&. See \fBDES key generation\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP key to fixup the parity for\&. +.RE +.PP + +.SS "void DES_string_to_key (const char * str, DES_cblock * key)" +Convert a string to a DES key\&. Use something like \fBPKCS5_PBKDF2_HMAC_SHA1()\fP to create key from passwords\&. +.PP +\fBParameters\fP +.RS 4 +\fIstr\fP The string to convert to a key +.br +\fIkey\fP the resulting key +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_dh.3 b/static/netbsd/man3/hcrypto_dh.3 new file mode 100644 index 00000000..6017ee7a --- /dev/null +++ b/static/netbsd/man3/hcrypto_dh.3 @@ -0,0 +1,294 @@ +.\" $NetBSD: hcrypto_dh.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_dh" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_dh \- Diffie-Hellman functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "const DH_METHOD * \fBDH_ltm_method\fP (void)" +.br +.ti -1c +.RI "DH * \fBDH_new\fP (void)" +.br +.ti -1c +.RI "DH * \fBDH_new_method\fP (ENGINE *engine)" +.br +.ti -1c +.RI "void \fBDH_free\fP (DH *dh)" +.br +.ti -1c +.RI "int \fBDH_up_ref\fP (DH *dh)" +.br +.ti -1c +.RI "int \fBDH_size\fP (const DH *dh)" +.br +.ti -1c +.RI "int \fBDH_set_ex_data\fP (DH *dh, int idx, void *data)" +.br +.ti -1c +.RI "void * \fBDH_get_ex_data\fP (DH *dh, int idx)" +.br +.ti -1c +.RI "int \fBDH_generate_parameters_ex\fP (DH *dh, int prime_len, int generator, BN_GENCB *cb)" +.br +.ti -1c +.RI "int \fBDH_check_pubkey\fP (const DH *dh, const BIGNUM *pub_key, int *codes)" +.br +.ti -1c +.RI "int \fBDH_generate_key\fP (DH *dh)" +.br +.ti -1c +.RI "int \fBDH_compute_key\fP (unsigned char *shared_key, const BIGNUM *peer_pub_key, DH *dh)" +.br +.ti -1c +.RI "int \fBDH_set_method\fP (DH *dh, const DH_METHOD *method)" +.br +.ti -1c +.RI "const DH_METHOD * \fBDH_null_method\fP (void)" +.br +.ti -1c +.RI "void \fBDH_set_default_method\fP (const DH_METHOD *meth)" +.br +.ti -1c +.RI "const DH_METHOD * \fBDH_get_default_method\fP (void)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBDH - Diffie-Hellman key exchange\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int DH_check_pubkey (const DH * dh, const BIGNUM * pub_key, int * codes)" +Check that the public key is sane\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP the local peer DH parameters\&. +.br +\fIpub_key\fP the remote peer public key parameters\&. +.br +\fIcodes\fP return that the failures of the pub_key are\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, 0 on failure and *codes is set the the combined fail check for the public key +.RE +.PP +Checks that the function performs are: +.IP "\(bu" 2 +pub_key is not negative +.IP "\(bu" 2 +pub_key > 1 and pub_key < p - 1, to avoid small subgroups attack\&. +.IP "\(bu" 2 +if g == 2, pub_key have more then one bit set, if bits set is 1, log_2(pub_key) is trival +.PP + +.SS "int DH_compute_key (unsigned char * shared_key, const BIGNUM * peer_pub_key, DH * dh)" +Complute the shared secret key\&. +.PP +\fBParameters\fP +.RS 4 +\fIshared_key\fP the resulting shared key, need to be at least \fBDH_size()\fP large\&. +.br +\fIpeer_pub_key\fP the peer's public key\&. +.br +\fIdh\fP the dh key pair\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP +Checks that the pubkey passed in is valid using \fBDH_check_pubkey()\fP\&. +.SS "void DH_free (DH * dh)" +Free a DH object and release related resources, like ENGINE, that the object was using\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP object to be freed\&. +.RE +.PP + +.SS "int DH_generate_key (DH * dh)" +Generate a new DH private-public key pair\&. The dh parameter must be allocted first with \fBDH_new()\fP\&. dh->p and dp->g must be set\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP dh parameter\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int DH_generate_parameters_ex (DH * dh, int prime_len, int generator, BN_GENCB * cb)" +Generate DH parameters for the DH object give parameters\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP The DH object to generate parameters for\&. +.br +\fIprime_len\fP length of the prime +.br +\fIgenerator\fP generator, g +.br +\fIcb\fP Callback parameters to show progress, can be NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the maximum size in bytes of the out data\&. +.RE +.PP + +.SS "const DH_METHOD* DH_get_default_method (void)" +Return the default DH implementation\&. +.PP +\fBReturns\fP +.RS 4 +pointer to a DH_METHOD\&. +.RE +.PP + +.SS "void* DH_get_ex_data (DH * dh, int idx)" +Get the data for index idx in the DH object\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP DH object\&. +.br +\fIidx\fP index to get the data for\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the object store in index idx +.RE +.PP + +.SS "const DH_METHOD* DH_ltm_method (void)" +DH implementation using libtommath\&. +.PP +\fBReturns\fP +.RS 4 +the DH_METHOD for the DH implementation using libtommath\&. +.RE +.PP + +.SS "DH* DH_new (void)" +Create a new DH object using DH_new_method(NULL), see \fBDH_new_method()\fP\&. +.PP +\fBReturns\fP +.RS 4 +a newly allocated DH object\&. +.RE +.PP + +.SS "DH* DH_new_method (ENGINE * engine)" +Create a new DH object from the given engine, if the NULL is used, the default engine is used\&. Free the DH object with \fBDH_free()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIengine\fP The engine to use to allocate the DH object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +a newly allocated DH object\&. +.RE +.PP + +.SS "const DH_METHOD* DH_null_method (void)" +Return the dummy DH implementation\&. +.PP +\fBReturns\fP +.RS 4 +pointer to a DH_METHOD\&. +.RE +.PP + +.SS "void DH_set_default_method (const DH_METHOD * meth)" +Set the default DH implementation\&. +.PP +\fBParameters\fP +.RS 4 +\fImeth\fP pointer to a DH_METHOD\&. +.RE +.PP + +.SS "int DH_set_ex_data (DH * dh, int idx, void * data)" +Set the data index idx in the DH object to data\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP DH object\&. +.br +\fIidx\fP index to set the data for\&. +.br +\fIdata\fP data to store for the index idx\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int DH_set_method (DH * dh, const DH_METHOD * method)" +Set a new method for the DH keypair\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP dh parameter\&. +.br +\fImethod\fP the new method for the DH parameter\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int DH_size (const DH * dh)" +The maximum output size of the \fBDH_compute_key()\fP function\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP The DH object to get the size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the maximum size in bytes of the out data\&. +.RE +.PP + +.SS "int DH_up_ref (DH * dh)" +Add a reference to the DH object\&. The object should be free with \fBDH_free()\fP to drop the reference\&. +.PP +\fBParameters\fP +.RS 4 +\fIdh\fP the object to increase the reference count too\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the updated reference count, can't safely be used except for debug printing\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_evp.3 b/static/netbsd/man3/hcrypto_evp.3 new file mode 100644 index 00000000..0cd2842a --- /dev/null +++ b/static/netbsd/man3/hcrypto_evp.3 @@ -0,0 +1,1443 @@ +.\" $NetBSD: hcrypto_evp.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_evp" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_evp \- EVP generic crypto functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_wincrypt_des_ede3_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_128_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_192_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_256_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_128_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_192_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_aes_256_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_sha256\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_sha384\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_sha512\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_sha1\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_md5\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_hcrypto_md4\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_des_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_des_ede3_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_rc2_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_rc2_40_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_rc2_64_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_camellia_128_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_camellia_192_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_hcrypto_camellia_256_cbc\fP (void)" +.br +.ti -1c +.RI "\fBOSSL_CIPHER_ALGORITHM\fP (rc2_cbc, hc_EVP_CIPH_CBC_MODE|hc_EVP_CIPH_VARIABLE_LENGTH) OSSL_CIPHER_ALGORITHM(rc2_40_cbc" +.br +.ti -1c +.RI "hc_EVP_CIPH_CBC_MODE \fBOSSL_CIPHER_ALGORITHM\fP (rc2_64_cbc, hc_EVP_CIPH_CBC_MODE|hc_EVP_CIPH_VARIABLE_LENGTH) OSSL_CIPHER_ALGORITHM(rc4" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (des_ede3_cbc, BCRYPT_3DES_ALGORITHM, 8, 24, 8, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (des_cbc, BCRYPT_DES_ALGORITHM, 8, 8, 8, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_128_cbc, BCRYPT_AES_ALGORITHM, 16, 16, 16, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_192_cbc, BCRYPT_AES_ALGORITHM, 16, 24, 16, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_256_cbc, BCRYPT_AES_ALGORITHM, 16, 32, 16, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_128_cfb8, BCRYPT_AES_ALGORITHM, 16, 16, 16, EVP_CIPH_CFB8_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_192_cfb8, BCRYPT_AES_ALGORITHM, 16, 24, 16, EVP_CIPH_CFB8_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (aes_256_cfb8, BCRYPT_AES_ALGORITHM, 16, 32, 16, EVP_CIPH_CFB8_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (rc2_cbc, BCRYPT_RC2_ALGORITHM, 8, 16, 8, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (rc2_40_cbc, BCRYPT_RC2_ALGORITHM, 8, 5, 8, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (rc2_64_cbc, BCRYPT_RC2_ALGORITHM, 8, 8, 8, EVP_CIPH_CBC_MODE)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM_UNAVAILABLE\fP (camellia_128_cbc)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM_UNAVAILABLE\fP (camellia_192_cbc)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM_UNAVAILABLE\fP (camellia_256_cbc)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (rc4, BCRYPT_RC4_ALGORITHM, 1, 16, 0, EVP_CIPH_STREAM_CIPHER|EVP_CIPH_VARIABLE_LENGTH)" +.br +.ti -1c +.RI "\fBWINCNG_CIPHER_ALGORITHM\fP (rc4_40, BCRYPT_RC4_ALGORITHM, 1, 5, 0, EVP_CIPH_STREAM_CIPHER|EVP_CIPH_VARIABLE_LENGTH)" +.br +.ti -1c +.RI "size_t \fBEVP_MD_size\fP (const EVP_MD *md)" +.br +.ti -1c +.RI "size_t \fBEVP_MD_block_size\fP (const EVP_MD *md)" +.br +.ti -1c +.RI "EVP_MD_CTX * \fBEVP_MD_CTX_create\fP (void)" +.br +.ti -1c +.RI "void \fBEVP_MD_CTX_init\fP (EVP_MD_CTX *ctx) HC_DEPRECATED" +.br +.ti -1c +.RI "void \fBEVP_MD_CTX_destroy\fP (EVP_MD_CTX *ctx)" +.br +.ti -1c +.RI "int \fBEVP_MD_CTX_cleanup\fP (EVP_MD_CTX *ctx) HC_DEPRECATED" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_MD_CTX_md\fP (EVP_MD_CTX *ctx)" +.br +.ti -1c +.RI "size_t \fBEVP_MD_CTX_size\fP (EVP_MD_CTX *ctx)" +.br +.ti -1c +.RI "size_t \fBEVP_MD_CTX_block_size\fP (EVP_MD_CTX *ctx)" +.br +.ti -1c +.RI "int \fBEVP_DigestInit_ex\fP (EVP_MD_CTX *ctx, const EVP_MD *md, ENGINE *engine)" +.br +.ti -1c +.RI "int \fBEVP_DigestUpdate\fP (EVP_MD_CTX *ctx, const void *data, size_t size)" +.br +.ti -1c +.RI "int \fBEVP_DigestFinal_ex\fP (EVP_MD_CTX *ctx, void *hash, unsigned int *size)" +.br +.ti -1c +.RI "int \fBEVP_Digest\fP (const void *data, size_t dsize, void *hash, unsigned int *hsize, const EVP_MD *md, ENGINE *engine)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_sha256\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_sha384\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_sha512\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_sha1\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_sha\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_md5\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_md4\fP (void)" +.br +.ti -1c +.RI "const EVP_MD * \fBEVP_md_null\fP (void)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_block_size\fP (const EVP_CIPHER *c)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_key_length\fP (const EVP_CIPHER *c)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_iv_length\fP (const EVP_CIPHER *c)" +.br +.ti -1c +.RI "void \fBEVP_CIPHER_CTX_init\fP (EVP_CIPHER_CTX *c)" +.br +.ti -1c +.RI "int \fBEVP_CIPHER_CTX_cleanup\fP (EVP_CIPHER_CTX *c)" +.br +.ti -1c +.RI "int \fBEVP_CIPHER_CTX_set_key_length\fP (EVP_CIPHER_CTX *c, int length)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_CIPHER_CTX_cipher\fP (EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_CTX_block_size\fP (const EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_CTX_key_length\fP (const EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "size_t \fBEVP_CIPHER_CTX_iv_length\fP (const EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "unsigned long \fBEVP_CIPHER_CTX_flags\fP (const EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "int \fBEVP_CIPHER_CTX_mode\fP (const EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "void * \fBEVP_CIPHER_CTX_get_app_data\fP (EVP_CIPHER_CTX *ctx)" +.br +.ti -1c +.RI "void \fBEVP_CIPHER_CTX_set_app_data\fP (EVP_CIPHER_CTX *ctx, void *data)" +.br +.ti -1c +.RI "int \fBEVP_CipherInit_ex\fP (EVP_CIPHER_CTX *ctx, const EVP_CIPHER *c, ENGINE *engine, const void *key, const void *iv, int encp)" +.br +.ti -1c +.RI "int \fBEVP_CipherUpdate\fP (EVP_CIPHER_CTX *ctx, void *out, int *outlen, void *in, size_t inlen)" +.br +.ti -1c +.RI "int \fBEVP_CipherFinal_ex\fP (EVP_CIPHER_CTX *ctx, void *out, int *outlen)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_enc_null\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_rc2_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_rc2_40_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_rc2_64_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_rc4\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_rc4_40\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_des_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_des_ede3_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_128_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_192_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_256_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_128_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_192_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_aes_256_cfb8\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_camellia_128_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_camellia_192_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_camellia_256_cbc\fP (void)" +.br +.ti -1c +.RI "const EVP_CIPHER * \fBEVP_get_cipherbyname\fP (const char *name)" +.br +.ti -1c +.RI "int \fBEVP_BytesToKey\fP (const EVP_CIPHER *type, const EVP_MD *md, const void *salt, const void *data, size_t datalen, unsigned int count, void *keydata, void *ivdata)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBEVP - generic crypto interface\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "const EVP_CIPHER* EVP_aes_128_cbc (void)" +The AES-128 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-128 EVP_CIPHER pointer\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "const EVP_CIPHER* EVP_aes_128_cfb8 (void)" +The AES-128 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_aes_192_cbc (void)" +The AES-192 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-192 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_aes_192_cfb8 (void)" +The AES-192 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-192 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_aes_256_cbc (void)" +The AES-256 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_aes_256_cfb8 (void)" +The AES-256 cipher type +.PP +\fBReturns\fP +.RS 4 +the AES-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "int EVP_BytesToKey (const EVP_CIPHER * type, const EVP_MD * md, const void * salt, const void * data, size_t datalen, unsigned int count, void * keydata, void * ivdata)" +Provides a legancy string to key function, used in PEM files\&. +.PP +New protocols should use new string to key functions like NIST SP56-800A or PKCS#5 v2\&.0 (see \fBPKCS5_PBKDF2_HMAC_SHA1()\fP)\&. +.PP +\fBParameters\fP +.RS 4 +\fItype\fP type of cipher to use +.br +\fImd\fP message digest to use +.br +\fIsalt\fP salt salt string, should be an binary 8 byte buffer\&. +.br +\fIdata\fP the password/input key string\&. +.br +\fIdatalen\fP length of data parameter\&. +.br +\fIcount\fP iteration counter\&. +.br +\fIkeydata\fP output keydata, needs to of the size \fBEVP_CIPHER_key_length()\fP\&. +.br +\fIivdata\fP output ivdata, needs to of the size \fBEVP_CIPHER_block_size()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the size of derived key\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_camellia_128_cbc (void)" +The Camellia-128 cipher type +.PP +\fBReturns\fP +.RS 4 +the Camellia-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_camellia_192_cbc (void)" +The Camellia-198 cipher type +.PP +\fBReturns\fP +.RS 4 +the Camellia-198 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_camellia_256_cbc (void)" +The Camellia-256 cipher type +.PP +\fBReturns\fP +.RS 4 +the Camellia-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "size_t EVP_CIPHER_block_size (const EVP_CIPHER * c)" +Return the block size of the cipher\&. +.PP +\fBParameters\fP +.RS 4 +\fIc\fP cipher to get the block size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the block size of the cipher\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "size_t EVP_CIPHER_CTX_block_size (const EVP_CIPHER_CTX * ctx)" +Return the block size of the cipher context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP cipher context to get the block size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the block size of the cipher context\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_CIPHER_CTX_cipher (EVP_CIPHER_CTX * ctx)" +Return the EVP_CIPHER for a EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to get the cipher type from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the EVP_CIPHER pointer\&. +.RE +.PP + +.SS "int EVP_CIPHER_CTX_cleanup (EVP_CIPHER_CTX * c)" +Clean up the EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIc\fP the cipher to clean up\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "unsigned long EVP_CIPHER_CTX_flags (const EVP_CIPHER_CTX * ctx)" +Get the flags for an EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the EVP_CIPHER_CTX to get the flags from +.RE +.PP +\fBReturns\fP +.RS 4 +the flags for an EVP_CIPHER_CTX\&. +.RE +.PP + +.SS "void* EVP_CIPHER_CTX_get_app_data (EVP_CIPHER_CTX * ctx)" +Get the app data for an EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the EVP_CIPHER_CTX to get the app data from +.RE +.PP +\fBReturns\fP +.RS 4 +the app data for an EVP_CIPHER_CTX\&. +.RE +.PP + +.SS "void EVP_CIPHER_CTX_init (EVP_CIPHER_CTX * c)" +Initiate a EVP_CIPHER_CTX context\&. Clean up with \fBEVP_CIPHER_CTX_cleanup()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIc\fP the cipher initiate\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "size_t EVP_CIPHER_CTX_iv_length (const EVP_CIPHER_CTX * ctx)" +Return the IV size of the cipher context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP cipher context to get the IV size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the IV size of the cipher context\&. +.RE +.PP + +.SS "size_t EVP_CIPHER_CTX_key_length (const EVP_CIPHER_CTX * ctx)" +Return the key size of the cipher context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP cipher context to get the key size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the key size of the cipher context\&. +.RE +.PP + +.SS "int EVP_CIPHER_CTX_mode (const EVP_CIPHER_CTX * ctx)" +Get the mode for an EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the EVP_CIPHER_CTX to get the mode from +.RE +.PP +\fBReturns\fP +.RS 4 +the mode for an EVP_CIPHER_CTX\&. +.RE +.PP + +.SS "void EVP_CIPHER_CTX_set_app_data (EVP_CIPHER_CTX * ctx, void * data)" +Set the app data for an EVP_CIPHER_CTX context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the EVP_CIPHER_CTX to set the app data for +.br +\fIdata\fP the app data to set for an EVP_CIPHER_CTX\&. +.RE +.PP + +.SS "int EVP_CIPHER_CTX_set_key_length (EVP_CIPHER_CTX * c, int length)" +If the cipher type supports it, change the key length +.PP +\fBParameters\fP +.RS 4 +\fIc\fP the cipher context to change the key length for +.br +\fIlength\fP new key length +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "size_t EVP_CIPHER_iv_length (const EVP_CIPHER * c)" +Return the IV size of the cipher\&. +.PP +\fBParameters\fP +.RS 4 +\fIc\fP cipher to get the IV size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the IV size of the cipher\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "size_t EVP_CIPHER_key_length (const EVP_CIPHER * c)" +Return the key size of the cipher\&. +.PP +\fBParameters\fP +.RS 4 +\fIc\fP cipher to get the key size from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the key size of the cipher\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "int EVP_CipherFinal_ex (EVP_CIPHER_CTX * ctx, void * out, int * outlen)" +Encipher/decipher final data +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the cipher context\&. +.br +\fIout\fP output data from the operation\&. +.br +\fIoutlen\fP output length +.RE +.PP +The input length needs to be at least \fBEVP_CIPHER_block_size()\fP bytes long\&. +.PP +See \fBEVP Cipher\fP for an example how to use this function\&. +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "int EVP_CipherInit_ex (EVP_CIPHER_CTX * ctx, const EVP_CIPHER * c, ENGINE * engine, const void * key, const void * iv, int encp)" +Initiate the EVP_CIPHER_CTX context to encrypt or decrypt data\&. Clean up with \fBEVP_CIPHER_CTX_cleanup()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP context to initiate +.br +\fIc\fP cipher to use\&. +.br +\fIengine\fP crypto engine to use, NULL to select default\&. +.br +\fIkey\fP the crypto key to use, NULL will use the previous value\&. +.br +\fIiv\fP the IV to use, NULL will use the previous value\&. +.br +\fIencp\fP non zero will encrypt, -1 use the previous value\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "int EVP_CipherUpdate (EVP_CIPHER_CTX * ctx, void * out, int * outlen, void * in, size_t inlen)" +Encipher/decipher partial data +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the cipher context\&. +.br +\fIout\fP output data from the operation\&. +.br +\fIoutlen\fP output length +.br +\fIin\fP input data to the operation\&. +.br +\fIinlen\fP length of data\&. +.RE +.PP +The output buffer length should at least be \fBEVP_CIPHER_block_size()\fP byte longer then the input length\&. +.PP +See \fBEVP Cipher\fP for an example how to use this function\&. +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP +If there in no spare bytes in the left from last Update and the input length is on the block boundery, the \fBEVP_CipherUpdate()\fP function can take a shortcut (and preformance gain) and directly encrypt the data, otherwise we hav to fix it up and store extra it the EVP_CIPHER_CTX\&. +.PP +\fBExamples\fP +.in +1c +\fBexample_evp_cipher\&.c\fP\&. +.SS "const EVP_CIPHER* EVP_des_cbc (void)" +The DES cipher type +.PP +\fBReturns\fP +.RS 4 +the DES-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_des_ede3_cbc (void)" +The triple DES cipher type +.PP +\fBReturns\fP +.RS 4 +the DES-EDE3-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "int EVP_Digest (const void * data, size_t dsize, void * hash, unsigned int * hsize, const EVP_MD * md, ENGINE * engine)" +Do the whole \fBEVP_MD_CTX_create()\fP, \fBEVP_DigestInit_ex()\fP, \fBEVP_DigestUpdate()\fP, \fBEVP_DigestFinal_ex()\fP, \fBEVP_MD_CTX_destroy()\fP dance in one call\&. +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP the data to update the context with +.br +\fIdsize\fP length of data +.br +\fIhash\fP output data of at least \fBEVP_MD_size()\fP length\&. +.br +\fIhsize\fP output length of hash\&. +.br +\fImd\fP message digest to use +.br +\fIengine\fP engine to use, NULL for default engine\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int EVP_DigestFinal_ex (EVP_MD_CTX * ctx, void * hash, unsigned int * size)" +Complete the message digest\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to complete\&. +.br +\fIhash\fP the output of the message digest function\&. At least \fBEVP_MD_size()\fP\&. +.br +\fIsize\fP the output size of hash\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int EVP_DigestInit_ex (EVP_MD_CTX * ctx, const EVP_MD * md, ENGINE * engine)" +Init a EVP_MD_CTX for use a specific message digest and engine\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the message digest context to init\&. +.br +\fImd\fP the message digest to use\&. +.br +\fIengine\fP the engine to use, NULL to use the default engine\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int EVP_DigestUpdate (EVP_MD_CTX * ctx, const void * data, size_t size)" +Update the digest with some data\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to update +.br +\fIdata\fP the data to update the context with +.br +\fIsize\fP length of data +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_enc_null (void)" +The NULL cipher type, does no encryption/decryption\&. +.PP +\fBReturns\fP +.RS 4 +the null EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_get_cipherbyname (const char * name)" +Get the cipher type using their name\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP the name of the cipher\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the selected EVP_CIPHER pointer or NULL if not found\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_128_cbc (void)" +The AES-128 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_128_cfb8 (void)" +The AES-128 CFB8 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_192_cbc (void)" +The AES-192 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-192 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_192_cfb8 (void)" +The AES-192 CFB8 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-192 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_256_cbc (void)" +The AES-256 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_aes_256_cfb8 (void)" +The AES-256 CFB8 cipher type (hcrypto) +.PP +\fBReturns\fP +.RS 4 +the AES-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_camellia_128_cbc (void)" +The Camellia-128 cipher type - hcrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_camellia_192_cbc (void)" +The Camellia-198 cipher type - hcrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-198 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_camellia_256_cbc (void)" +The Camellia-256 cipher type - hcrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_des_cbc (void)" +The DES cipher type +.PP +\fBReturns\fP +.RS 4 +the DES-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_des_ede3_cbc (void)" +The triple DES cipher type - hcrypto +.PP +\fBReturns\fP +.RS 4 +the DES-EDE3-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_md4 (void)" +The message digest MD4 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_md5 (void)" +The message digest MD5 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_rc2_40_cbc (void)" +The RC2-40 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC2-40 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_rc2_64_cbc (void)" +The RC2-64 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC2-64 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_hcrypto_rc2_cbc (void)" +The RC2 cipher type - hcrypto +.PP +\fBReturns\fP +.RS 4 +the RC2 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_sha1 (void)" +The message digest SHA1 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_sha256 (void)" +The message digest SHA256 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_sha384 (void)" +The message digest SHA384 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_hcrypto_sha512 (void)" +The message digest SHA512 - hcrypto +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_md4 (void)" +The message digest MD4 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_md5 (void)" +The message digest MD5 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "size_t EVP_MD_block_size (const EVP_MD * md)" +Return the blocksize of the message digest function\&. +.PP +\fBParameters\fP +.RS 4 +\fImd\fP the evp message +.RE +.PP +\fBReturns\fP +.RS 4 +size size of the message digest block size +.RE +.PP + +.SS "size_t EVP_MD_CTX_block_size (EVP_MD_CTX * ctx)" +Return the blocksize of the message digest function\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the evp message digest context +.RE +.PP +\fBReturns\fP +.RS 4 +size size of the message digest block size +.RE +.PP + +.SS "int EVP_MD_CTX_cleanup (EVP_MD_CTX * ctx)" +Free the resources used by the EVP_MD context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to free the resources from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "EVP_MD_CTX* EVP_MD_CTX_create (void)" +Allocate a messsage digest context object\&. Free with \fBEVP_MD_CTX_destroy()\fP\&. +.PP +\fBReturns\fP +.RS 4 +a newly allocated message digest context object\&. +.RE +.PP + +.SS "void EVP_MD_CTX_destroy (EVP_MD_CTX * ctx)" +Free a messsage digest context object\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP context to free\&. +.RE +.PP + +.SS "void EVP_MD_CTX_init (EVP_MD_CTX * ctx)" +Initiate a messsage digest context object\&. Deallocate with \fBEVP_MD_CTX_cleanup()\fP\&. Please use \fBEVP_MD_CTX_create()\fP instead\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP variable to initiate\&. +.RE +.PP + +.SS "const EVP_MD* EVP_MD_CTX_md (EVP_MD_CTX * ctx)" +Get the EVP_MD use for a specified context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the EVP_MD context to get the EVP_MD for\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the EVP_MD used for the context\&. +.RE +.PP + +.SS "size_t EVP_MD_CTX_size (EVP_MD_CTX * ctx)" +Return the output size of the message digest function\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the evp message digest context +.RE +.PP +\fBReturns\fP +.RS 4 +size output size of the message digest function\&. +.RE +.PP + +.SS "const EVP_MD* EVP_md_null (void)" +The null message digest +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "size_t EVP_MD_size (const EVP_MD * md)" +Return the output size of the message digest function\&. +.PP +\fBParameters\fP +.RS 4 +\fImd\fP the evp message +.RE +.PP +\fBReturns\fP +.RS 4 +size output size of the message digest function\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_rc2_40_cbc (void)" +The RC2 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC2 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_rc2_64_cbc (void)" +The RC2 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC2 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_rc2_cbc (void)" +The RC2 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC2 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_rc4 (void)" +The RC4 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC4 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_rc4_40 (void)" +The RC4-40 cipher type +.PP +\fBReturns\fP +.RS 4 +the RC4-40 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "const EVP_MD* EVP_sha (void)" +The message digest SHA1 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_sha1 (void)" +The message digest SHA1 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_sha256 (void)" +The message digest SHA256 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_sha384 (void)" +The message digest SHA384 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_MD* EVP_sha512 (void)" +The message digest SHA512 +.PP +\fBReturns\fP +.RS 4 +the message digest type\&. +.RE +.PP + +.SS "const EVP_CIPHER* EVP_wincrypt_des_ede3_cbc (void)" +The triple DES cipher type (Micrsoft crypt provider) +.PP +\fBReturns\fP +.RS 4 +the DES-EDE3-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "hc_EVP_CIPH_CBC_MODE OSSL_CIPHER_ALGORITHM (rc2_64_cbc, hc_EVP_CIPH_CBC_MODE| hc_EVP_CIPH_VARIABLE_LENGTH)" +The RC2-64 cipher type - OpenSSL +.PP +\fBReturns\fP +.RS 4 +the RC2-64 EVP_CIPHER pointer\&. The Camellia-128 cipher type - OpenSSL +.PP +the Camellia-128 EVP_CIPHER pointer\&. The Camellia-198 cipher type - OpenSSL +.PP +the Camellia-198 EVP_CIPHER pointer\&. The Camellia-256 cipher type - OpenSSL +.PP +the Camellia-256 EVP_CIPHER pointer\&. The RC4 cipher type (OpenSSL provider) +.PP +the RC4 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "OSSL_CIPHER_ALGORITHM (rc2_cbc, hc_EVP_CIPH_CBC_MODE| hc_EVP_CIPH_VARIABLE_LENGTH)" +The triple DES cipher type (OpenSSL provider) +.PP +\fBReturns\fP +.RS 4 +the DES-EDE3-CBC EVP_CIPHER pointer\&. The DES cipher type (OpenSSL provider) +.PP +the DES-CBC EVP_CIPHER pointer\&. The AES-128 cipher type (OpenSSL provider) +.PP +the AES-128-CBC EVP_CIPHER pointer\&. The AES-192 cipher type (OpenSSL provider) +.PP +the AES-192-CBC EVP_CIPHER pointer\&. The AES-256 cipher type (OpenSSL provider) +.PP +the AES-256-CBC EVP_CIPHER pointer\&. The AES-128 CFB8 cipher type (OpenSSL provider) +.PP +the AES-128-CFB8 EVP_CIPHER pointer\&. The AES-192 CFB8 cipher type (OpenSSL provider) +.PP +the AES-192-CFB8 EVP_CIPHER pointer\&. The AES-256 CFB8 cipher type (OpenSSL provider) +.PP +the AES-256-CFB8 EVP_CIPHER pointer\&. The RC2 cipher type - OpenSSL +.PP +the RC2 EVP_CIPHER pointer\&. The RC2-40 cipher type - OpenSSL +.PP +the RC2-40 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_128_cbc, BCRYPT_AES_ALGORITHM, 16, 16, 16, EVP_CIPH_CBC_MODE)" +The AES-128 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-128-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_128_cfb8, BCRYPT_AES_ALGORITHM, 16, 16, 16, EVP_CIPH_CFB8_MODE)" +The AES-128 CFB8 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-128-CFB8 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_192_cbc, BCRYPT_AES_ALGORITHM, 16, 24, 16, EVP_CIPH_CBC_MODE)" +The AES-192 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-192-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_192_cfb8, BCRYPT_AES_ALGORITHM, 16, 24, 16, EVP_CIPH_CFB8_MODE)" +The AES-192 CFB8 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-192-CFB8 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_256_cbc, BCRYPT_AES_ALGORITHM, 16, 32, 16, EVP_CIPH_CBC_MODE)" +The AES-256 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-256-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (aes_256_cfb8, BCRYPT_AES_ALGORITHM, 16, 32, 16, EVP_CIPH_CFB8_MODE)" +The AES-256 CFB8 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the AES-256-CFB8 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (des_cbc, BCRYPT_DES_ALGORITHM, 8, 8, 8, EVP_CIPH_CBC_MODE)" +The DES cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the DES-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (des_ede3_cbc, BCRYPT_3DES_ALGORITHM, 8, 24, 8, EVP_CIPH_CBC_MODE)" +The triple DES cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the DES-EDE3-CBC EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (rc2_40_cbc, BCRYPT_RC2_ALGORITHM, 8, 5, 8, EVP_CIPH_CBC_MODE)" +The RC2-40 cipher type - Windows CNG +.PP +\fBReturns\fP +.RS 4 +the RC2-40 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (rc2_64_cbc, BCRYPT_RC2_ALGORITHM, 8, 8, 8, EVP_CIPH_CBC_MODE)" +The RC2-64 cipher type - Windows CNG +.PP +\fBReturns\fP +.RS 4 +the RC2-64 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (rc2_cbc, BCRYPT_RC2_ALGORITHM, 8, 16, 8, EVP_CIPH_CBC_MODE)" +The RC2 cipher type - Windows CNG +.PP +\fBReturns\fP +.RS 4 +the RC2 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (rc4, BCRYPT_RC4_ALGORITHM, 1, 16, 0, EVP_CIPH_STREAM_CIPHER| EVP_CIPH_VARIABLE_LENGTH)" +The RC4 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the RC4 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM (rc4_40, BCRYPT_RC4_ALGORITHM, 1, 5, 0, EVP_CIPH_STREAM_CIPHER| EVP_CIPH_VARIABLE_LENGTH)" +The RC4-40 cipher type (Windows CNG provider) +.PP +\fBReturns\fP +.RS 4 +the RC4 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM_UNAVAILABLE (camellia_128_cbc)" +The Camellia-128 cipher type - CommonCrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-128 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM_UNAVAILABLE (camellia_192_cbc)" +The Camellia-198 cipher type - CommonCrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-198 EVP_CIPHER pointer\&. +.RE +.PP + +.SS "WINCNG_CIPHER_ALGORITHM_UNAVAILABLE (camellia_256_cbc)" +The Camellia-256 cipher type - CommonCrypto +.PP +\fBReturns\fP +.RS 4 +the Camellia-256 EVP_CIPHER pointer\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_misc.3 b/static/netbsd/man3/hcrypto_misc.3 new file mode 100644 index 00000000..1d46742e --- /dev/null +++ b/static/netbsd/man3/hcrypto_misc.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: hcrypto_misc.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_misc" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_misc \- hcrypto miscellaneous functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBPKCS5_PBKDF2_HMAC\fP (const void *password, size_t password_len, const void *salt, size_t salt_len, unsigned long iter, const EVP_MD *md, size_t keylen, void *key)" +.br +.ti -1c +.RI "int \fBPKCS5_PBKDF2_HMAC_SHA1\fP (const void *password, size_t password_len, const void *salt, size_t salt_len, unsigned long iter, size_t keylen, void *key)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int PKCS5_PBKDF2_HMAC (const void * password, size_t password_len, const void * salt, size_t salt_len, unsigned long iter, const EVP_MD * md, size_t keylen, void * key)" +As descriped in PKCS5, convert a password, salt, and iteration counter into a crypto key\&. +.PP +\fBParameters\fP +.RS 4 +\fIpassword\fP Password\&. +.br +\fIpassword_len\fP Length of password\&. +.br +\fIsalt\fP Salt +.br +\fIsalt_len\fP Length of salt\&. +.br +\fIiter\fP iteration counter\&. +.br +\fImd\fP the digest function\&. +.br +\fIkeylen\fP the output key length\&. +.br +\fIkey\fP the output key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, non 1 on failure\&. +.RE +.PP + +.SS "int PKCS5_PBKDF2_HMAC_SHA1 (const void * password, size_t password_len, const void * salt, size_t salt_len, unsigned long iter, size_t keylen, void * key)" +As descriped in PKCS5, convert a password, salt, and iteration counter into a crypto key\&. +.PP +\fBParameters\fP +.RS 4 +\fIpassword\fP Password\&. +.br +\fIpassword_len\fP Length of password\&. +.br +\fIsalt\fP Salt +.br +\fIsalt_len\fP Length of salt\&. +.br +\fIiter\fP iteration counter\&. +.br +\fIkeylen\fP the output key length\&. +.br +\fIkey\fP the output key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, non 1 on failure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_rand.3 b/static/netbsd/man3/hcrypto_rand.3 new file mode 100644 index 00000000..8ee50534 --- /dev/null +++ b/static/netbsd/man3/hcrypto_rand.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: hcrypto_rand.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_rand" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_rand \- RAND crypto functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBRAND_seed\fP (const void *indata, size_t size)" +.br +.ti -1c +.RI "int \fBRAND_bytes\fP (void *outdata, size_t size)" +.br +.ti -1c +.RI "void \fBRAND_cleanup\fP (void)" +.br +.ti -1c +.RI "void \fBRAND_add\fP (const void *indata, size_t size, double entropi)" +.br +.ti -1c +.RI "int \fBRAND_pseudo_bytes\fP (void *outdata, size_t size)" +.br +.ti -1c +.RI "int \fBRAND_status\fP (void)" +.br +.ti -1c +.RI "int \fBRAND_set_rand_method\fP (const RAND_METHOD *meth)" +.br +.ti -1c +.RI "const RAND_METHOD * \fBRAND_get_rand_method\fP (void)" +.br +.ti -1c +.RI "int \fBRAND_set_rand_engine\fP (ENGINE *engine)" +.br +.ti -1c +.RI "int \fBRAND_load_file\fP (const char *filename, size_t size)" +.br +.ti -1c +.RI "int \fBRAND_write_file\fP (const char *filename)" +.br +.ti -1c +.RI "const char * \fBRAND_file_name\fP (char *filename, size_t size)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBRAND - random number\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "void RAND_add (const void * indata, size_t size, double entropi)" +Seed that random number generator\&. Secret material can securely be feed into the function, they will never be returned\&. +.PP +\fBParameters\fP +.RS 4 +\fIindata\fP the input data\&. +.br +\fIsize\fP size of in data\&. +.br +\fIentropi\fP entropi in data\&. +.RE +.PP + +.SS "int RAND_bytes (void * outdata, size_t size)" +Get a random block from the random generator, can be used for key material\&. +.PP +\fBParameters\fP +.RS 4 +\fIoutdata\fP random data +.br +\fIsize\fP length random data +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, 0 on failure\&. +.RE +.PP + +.SS "void RAND_cleanup (void)" +Reset and free memory used by the random generator\&. +.SS "const char* RAND_file_name (char * filename, size_t size)" +Return the default random state filename for a user to use for \fBRAND_load_file()\fP, and \fBRAND_write_file()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIfilename\fP buffer to hold file name\&. +.br +\fIsize\fP size of buffer filename\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the buffer filename or NULL on failure\&. +.RE +.PP + +.SS "const RAND_METHOD* RAND_get_rand_method (void)" +Get the default random method\&. +.PP +\fBReturns\fP +.RS 4 +Returns a RAND_METHOD +.RE +.PP + +.SS "int RAND_load_file (const char * filename, size_t size)" +Load a a file and feed it into \fBRAND_seed()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIfilename\fP name of file to read\&. +.br +\fIsize\fP minimum size to read\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns the number of seed bytes loaded (0 indicates failure) +.RE +.PP + +.SS "int RAND_pseudo_bytes (void * outdata, size_t size)" +Get a random block from the random generator, should NOT be used for key material\&. +.PP +\fBParameters\fP +.RS 4 +\fIoutdata\fP random data +.br +\fIsize\fP length random data +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, 0 on failure\&. +.RE +.PP + +.SS "void RAND_seed (const void * indata, size_t size)" +Seed that random number generator\&. Secret material can securely be feed into the function, they will never be returned\&. +.PP +\fBParameters\fP +.RS 4 +\fIindata\fP seed data +.br +\fIsize\fP length seed data +.RE +.PP + +.SS "int RAND_set_rand_engine (ENGINE * engine)" +Set the default random method from engine\&. +.PP +\fBParameters\fP +.RS 4 +\fIengine\fP use engine, if NULL is passed it, old method and engine is cleared\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success, 0 on failure\&. +.RE +.PP + +.SS "int RAND_set_rand_method (const RAND_METHOD * meth)" +Set the default random method\&. +.PP +\fBParameters\fP +.RS 4 +\fImeth\fP set the new default method\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int RAND_status (void)" +Return status of the random generator +.PP +\fBReturns\fP +.RS 4 +1 if the random generator can deliver random data\&. +.RE +.PP + +.SS "int RAND_write_file (const char * filename)" +Write of random numbers to a file to store for later initiation with \fBRAND_load_file()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIfilename\fP name of file to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success and non-one on failure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hcrypto_rsa.3 b/static/netbsd/man3/hcrypto_rsa.3 new file mode 100644 index 00000000..067623af --- /dev/null +++ b/static/netbsd/man3/hcrypto_rsa.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: hcrypto_rsa.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hcrypto_rsa" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hcrypto_rsa \- RSA functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "RSA * \fBRSA_new\fP (void)" +.br +.ti -1c +.RI "RSA * \fBRSA_new_method\fP (ENGINE *engine)" +.br +.ti -1c +.RI "void \fBRSA_free\fP (RSA *rsa)" +.br +.ti -1c +.RI "int \fBRSA_up_ref\fP (RSA *rsa)" +.br +.ti -1c +.RI "const RSA_METHOD * \fBRSA_get_method\fP (const RSA *rsa)" +.br +.ti -1c +.RI "int \fBRSA_set_method\fP (RSA *rsa, const RSA_METHOD *method)" +.br +.ti -1c +.RI "int \fBRSA_set_app_data\fP (RSA *rsa, void *arg)" +.br +.ti -1c +.RI "void * \fBRSA_get_app_data\fP (const RSA *rsa)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBRSA - public-key cryptography\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "void RSA_free (RSA * rsa)" +Free an allocation RSA object\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP the RSA object to free\&. +.RE +.PP + +.SS "void* RSA_get_app_data (const RSA * rsa)" +Get the application data for the RSA object\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP the rsa object to get the parameter for +.RE +.PP +\fBReturns\fP +.RS 4 +the data object +.RE +.PP + +.SS "const RSA_METHOD* RSA_get_method (const RSA * rsa)" +Return the RSA_METHOD used for this RSA object\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP the object to get the method from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the method used for this RSA object\&. +.RE +.PP + +.SS "RSA* RSA_new (void)" +Same as \fBRSA_new_method()\fP using NULL as engine\&. +.PP +\fBReturns\fP +.RS 4 +a newly allocated RSA object\&. Free with \fBRSA_free()\fP\&. +.RE +.PP + +.SS "RSA* RSA_new_method (ENGINE * engine)" +Allocate a new RSA object using the engine, if NULL is specified as the engine, use the default RSA engine as returned by ENGINE_get_default_RSA()\&. +.PP +\fBParameters\fP +.RS 4 +\fIengine\fP Specific what ENGINE RSA provider should be used\&. +.RE +.PP +\fBReturns\fP +.RS 4 +a newly allocated RSA object\&. Free with \fBRSA_free()\fP\&. +.RE +.PP + +.SS "int RSA_set_app_data (RSA * rsa, void * arg)" +Set the application data for the RSA object\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP the rsa object to set the parameter for +.br +\fIarg\fP the data object to store +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int RSA_set_method (RSA * rsa, const RSA_METHOD * method)" +Set a new method for the RSA keypair\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP rsa parameter\&. +.br +\fImethod\fP the new method for the RSA parameter\&. +.RE +.PP +\fBReturns\fP +.RS 4 +1 on success\&. +.RE +.PP + +.SS "int RSA_up_ref (RSA * rsa)" +Add an extra reference to the RSA object\&. The object should be free with \fBRSA_free()\fP to drop the reference\&. +.PP +\fBParameters\fP +.RS 4 +\fIrsa\fP the object to add reference counting too\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the current reference count, can't safely be used except for debug printing\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal crypto library from the source code\&. diff --git a/static/netbsd/man3/hdb__del.3 b/static/netbsd/man3/hdb__del.3 new file mode 100644 index 00000000..084e6bf1 --- /dev/null +++ b/static/netbsd/man3/hdb__del.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb__del.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb__get.3 b/static/netbsd/man3/hdb__get.3 new file mode 100644 index 00000000..f2d695b4 --- /dev/null +++ b/static/netbsd/man3/hdb__get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb__get.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb__put.3 b/static/netbsd/man3/hdb__put.3 new file mode 100644 index 00000000..63cce451 --- /dev/null +++ b/static/netbsd/man3/hdb__put.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb__put.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_auth_status.3 b/static/netbsd/man3/hdb_auth_status.3 new file mode 100644 index 00000000..77e2b620 --- /dev/null +++ b/static/netbsd/man3/hdb_auth_status.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_auth_status.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_check_constrained_delegation.3 b/static/netbsd/man3/hdb_check_constrained_delegation.3 new file mode 100644 index 00000000..c3cba75e --- /dev/null +++ b/static/netbsd/man3/hdb_check_constrained_delegation.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_check_constrained_delegation.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_check_pkinit_ms_upn_match.3 b/static/netbsd/man3/hdb_check_pkinit_ms_upn_match.3 new file mode 100644 index 00000000..7e6ab949 --- /dev/null +++ b/static/netbsd/man3/hdb_check_pkinit_ms_upn_match.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_check_pkinit_ms_upn_match.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_check_s4u2self.3 b/static/netbsd/man3/hdb_check_s4u2self.3 new file mode 100644 index 00000000..add34406 --- /dev/null +++ b/static/netbsd/man3/hdb_check_s4u2self.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_check_s4u2self.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_close.3 b/static/netbsd/man3/hdb_close.3 new file mode 100644 index 00000000..c72e3b97 --- /dev/null +++ b/static/netbsd/man3/hdb_close.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_close.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_destroy.3 b/static/netbsd/man3/hdb_destroy.3 new file mode 100644 index 00000000..074daa06 --- /dev/null +++ b/static/netbsd/man3/hdb_destroy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_destroy.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_entry_ex.3 b/static/netbsd/man3/hdb_entry_ex.3 new file mode 100644 index 00000000..6a12c8a7 --- /dev/null +++ b/static/netbsd/man3/hdb_entry_ex.3 @@ -0,0 +1,19 @@ +.\" $NetBSD: hdb_entry_ex.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "hdb_entry_ex" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal hdb library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hdb_entry_ex +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +\fBhdb_entry_ex\fP is a wrapper structure around the hdb_entry structure that allows backends to keep a pointer to the backing store, ie in ->hdb_fetch_kvno(), so that we the kadmin/kpasswd backend gets around to ->hdb_store(), the backend doesn't need to lookup the entry again\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal hdb library from the source code\&. diff --git a/static/netbsd/man3/hdb_fetch_kvno.3 b/static/netbsd/man3/hdb_fetch_kvno.3 new file mode 100644 index 00000000..101e3d18 --- /dev/null +++ b/static/netbsd/man3/hdb_fetch_kvno.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_fetch_kvno.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_firstkey.3 b/static/netbsd/man3/hdb_firstkey.3 new file mode 100644 index 00000000..c2cc2e1a --- /dev/null +++ b/static/netbsd/man3/hdb_firstkey.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_firstkey.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_free.3 b/static/netbsd/man3/hdb_free.3 new file mode 100644 index 00000000..64d06fd7 --- /dev/null +++ b/static/netbsd/man3/hdb_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_get_realms.3 b/static/netbsd/man3/hdb_get_realms.3 new file mode 100644 index 00000000..d54b0a0d --- /dev/null +++ b/static/netbsd/man3/hdb_get_realms.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_get_realms.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_lock.3 b/static/netbsd/man3/hdb_lock.3 new file mode 100644 index 00000000..c03537ad --- /dev/null +++ b/static/netbsd/man3/hdb_lock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_lock.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_name.3 b/static/netbsd/man3/hdb_name.3 new file mode 100644 index 00000000..6a2f0e39 --- /dev/null +++ b/static/netbsd/man3/hdb_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_nextkey.3 b/static/netbsd/man3/hdb_nextkey.3 new file mode 100644 index 00000000..f0d889fd --- /dev/null +++ b/static/netbsd/man3/hdb_nextkey.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_nextkey.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_open.3 b/static/netbsd/man3/hdb_open.3 new file mode 100644 index 00000000..ea0a4c1b --- /dev/null +++ b/static/netbsd/man3/hdb_open.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_open.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_password.3 b/static/netbsd/man3/hdb_password.3 new file mode 100644 index 00000000..00cde156 --- /dev/null +++ b/static/netbsd/man3/hdb_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_password.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_remove.3 b/static/netbsd/man3/hdb_remove.3 new file mode 100644 index 00000000..7b95766f --- /dev/null +++ b/static/netbsd/man3/hdb_remove.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_remove.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_rename.3 b/static/netbsd/man3/hdb_rename.3 new file mode 100644 index 00000000..1136608b --- /dev/null +++ b/static/netbsd/man3/hdb_rename.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_rename.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_set_sync.3 b/static/netbsd/man3/hdb_set_sync.3 new file mode 100644 index 00000000..b8379847 --- /dev/null +++ b/static/netbsd/man3/hdb_set_sync.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_set_sync.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_store.3 b/static/netbsd/man3/hdb_store.3 new file mode 100644 index 00000000..b25d424b --- /dev/null +++ b/static/netbsd/man3/hdb_store.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_store.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/hdb_unlock.3 b/static/netbsd/man3/hdb_unlock.3 new file mode 100644 index 00000000..662bac8c --- /dev/null +++ b/static/netbsd/man3/hdb_unlock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hdb_unlock.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/HDB.3 diff --git a/static/netbsd/man3/heim_ntlm_build_ntlm1_master.3 b/static/netbsd/man3/heim_ntlm_build_ntlm1_master.3 new file mode 100644 index 00000000..1ada9226 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_build_ntlm1_master.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_build_ntlm1_master.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_build_ntlm2_master.3 b/static/netbsd/man3/heim_ntlm_build_ntlm2_master.3 new file mode 100644 index 00000000..f73b7ae9 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_build_ntlm2_master.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_build_ntlm2_master.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_calculate_lm2.3 b/static/netbsd/man3/heim_ntlm_calculate_lm2.3 new file mode 100644 index 00000000..ae562d4a --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_calculate_lm2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_calculate_lm2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_calculate_ntlm1.3 b/static/netbsd/man3/heim_ntlm_calculate_ntlm1.3 new file mode 100644 index 00000000..f917f05a --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_calculate_ntlm1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_calculate_ntlm1.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_calculate_ntlm2.3 b/static/netbsd/man3/heim_ntlm_calculate_ntlm2.3 new file mode 100644 index 00000000..269797b9 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_calculate_ntlm2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_calculate_ntlm2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_decode_targetinfo.3 b/static/netbsd/man3/heim_ntlm_decode_targetinfo.3 new file mode 100644 index 00000000..8e03883b --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_decode_targetinfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_decode_targetinfo.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_encode_targetinfo.3 b/static/netbsd/man3/heim_ntlm_encode_targetinfo.3 new file mode 100644 index 00000000..db102700 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_encode_targetinfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_encode_targetinfo.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_encode_type1.3 b/static/netbsd/man3/heim_ntlm_encode_type1.3 new file mode 100644 index 00000000..8f4820b3 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_encode_type1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_encode_type1.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_encode_type2.3 b/static/netbsd/man3/heim_ntlm_encode_type2.3 new file mode 100644 index 00000000..0e245b61 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_encode_type2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_encode_type2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_encode_type3.3 b/static/netbsd/man3/heim_ntlm_encode_type3.3 new file mode 100644 index 00000000..3f15021d --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_encode_type3.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_encode_type3.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_free_buf.3 b/static/netbsd/man3/heim_ntlm_free_buf.3 new file mode 100644 index 00000000..bce71a24 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_free_buf.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_free_buf.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_free_targetinfo.3 b/static/netbsd/man3/heim_ntlm_free_targetinfo.3 new file mode 100644 index 00000000..4f55c4c5 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_free_targetinfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_free_targetinfo.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_free_type1.3 b/static/netbsd/man3/heim_ntlm_free_type1.3 new file mode 100644 index 00000000..bfffd19f --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_free_type1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_free_type1.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_free_type2.3 b/static/netbsd/man3/heim_ntlm_free_type2.3 new file mode 100644 index 00000000..7d13d732 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_free_type2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_free_type2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_free_type3.3 b/static/netbsd/man3/heim_ntlm_free_type3.3 new file mode 100644 index 00000000..ee30ee13 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_free_type3.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_free_type3.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_keyex_unwrap.3 b/static/netbsd/man3/heim_ntlm_keyex_unwrap.3 new file mode 100644 index 00000000..1a31d47f --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_keyex_unwrap.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_keyex_unwrap.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_nt_key.3 b/static/netbsd/man3/heim_ntlm_nt_key.3 new file mode 100644 index 00000000..ea53e768 --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_nt_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_nt_key.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_ntlmv2_key.3 b/static/netbsd/man3/heim_ntlm_ntlmv2_key.3 new file mode 100644 index 00000000..ef96c96b --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_ntlmv2_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_ntlmv2_key.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heim_ntlm_verify_ntlm2.3 b/static/netbsd/man3/heim_ntlm_verify_ntlm2.3 new file mode 100644 index 00000000..1802903d --- /dev/null +++ b/static/netbsd/man3/heim_ntlm_verify_ntlm2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: heim_ntlm_verify_ntlm2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_core.3 diff --git a/static/netbsd/man3/heimbase.3 b/static/netbsd/man3/heimbase.3 new file mode 100644 index 00000000..eb1e1c12 --- /dev/null +++ b/static/netbsd/man3/heimbase.3 @@ -0,0 +1,334 @@ +.\" $NetBSD: heimbase.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "heimbase" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal base library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +heimbase \- Heimbase +.PP + \- Registers a DB type for use with heim_db_create()\&. + +.SH SYNOPSIS +.br +.PP +.SH "Detailed Description" +.PP +Registers a DB type for use with heim_db_create()\&. + +heim_db_register +.PP +\fBParameters\fP +.RS 4 +\fIdbtype\fP Name of DB type +.br +\fIdata\fP Private data argument to the dbtype's openf method +.br +\fIplugin\fP Structure with DB type methods (function pointers) +.RE +.PP +Backends that provide begin/commit/rollback methods must provide ACID semantics\&. +.PP +The registered DB type will have ACID semantics for backends that do not provide begin/commit/rollback methods but do provide lock/unlock and rdjournal/wrjournal methods (using a replay log journalling scheme)\&. +.PP +If the registered DB type does not natively provide read vs\&. write transaction isolation but does provide a lock method then the DB will provide read/write transaction isolation\&. +.PP +\fBReturns\fP +.RS 4 +ENOMEM on failure, else 0\&. +.RE +.PP +Open a database of the given dbtype\&. +.PP +Database type names can be composed of one or more pseudo-DB types and one concrete DB type joined with a '+' between each\&. For example: 'transaction+bdb' might be a Berkeley DB with a layer above that provides transactions\&. +.PP +Options may be provided via a dict (an associative array)\&. Existing options include: +.PP +.IP "\(bu" 2 +'create', with any value (create if DB doesn't exist) +.IP "\(bu" 2 +'exclusive', with any value (exclusive create) +.IP "\(bu" 2 +'truncate', with any value (truncate the DB) +.IP "\(bu" 2 +'read-only', with any value (disallow writes) +.IP "\(bu" 2 +'sync', with any value (make transactions durable) +.IP "\(bu" 2 +'journal-name', with a string value naming a journal file name +.PP +.PP +\fBParameters\fP +.RS 4 +\fIdbtype\fP Name of DB type +.br +\fIdbname\fP Name of DB (likely a file path) +.br +\fIoptions\fP Options dict +.br +\fIdb\fP Output open DB handle +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +a DB handle +.RE +.PP +Clone (duplicate) an open DB handle\&. +.PP +This is useful for multi-threaded applications\&. Applications must synchronize access to any given DB handle\&. +.PP +Returns EBUSY if there is an open transaction for the input db\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +a DB handle +.RE +.PP +Open a transaction on the given db\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, system error otherwise +.RE +.PP +Commit an open transaction on the given db\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, system error otherwise +.RE +.PP +Rollback an open transaction on the given db\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, system error otherwise +.RE +.PP +Get type ID of heim_db_t objects\&. +.PP +Lookup a key's value in the DB\&. +.PP +Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIkey\fP Key +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +the value (retained), if there is one for the given key +.RE +.PP +Set a key's value in the DB\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIkey\fP Key +.br +\fIvalue\fP Value (if NULL the key will be deleted, but empty is OK) +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, system error otherwise +.RE +.PP +Delete a key and its value from the DB +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIkey\fP Key +.br +\fIerror\fP Output error object +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, system error otherwise +.RE +.PP +Iterate a callback function over keys and values from a DB\&. +.PP +\fBParameters\fP +.RS 4 +\fIdb\fP Open DB handle +.br +\fIiter_data\fP Callback function's private data +.br +\fIiter_f\fP Callback function, called once per-key/value pair +.br +\fIerror\fP Output error object +.RE +.PP +Get a node in a heim_object tree by path +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP tree +.br +\fIerror\fP error (output) +.br +\fIap\fP NULL-terminated va_list of heim_object_ts that form a path +.RE +.PP +\fBReturns\fP +.RS 4 +object (not retained) if found +.RE +.PP +Get a node in a tree by path, with retained reference +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP tree +.br +\fIerror\fP error (output) +.br +\fIap\fP NULL-terminated va_list of heim_object_ts that form a path +.RE +.PP +\fBReturns\fP +.RS 4 +retained object if found +.RE +.PP +Get a node in a tree by path +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP tree +.br +\fIerror\fP error (output) +.br +\fI\&.\&.\&.\fP NULL-terminated va_list of heim_object_ts that form a path +.RE +.PP +\fBReturns\fP +.RS 4 +object (not retained) if found +.RE +.PP +Get a node in a tree by path, with retained reference +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP tree +.br +\fIerror\fP error (output) +.br +\fI\&.\&.\&.\fP NULL-terminated va_list of heim_object_ts that form a path +.RE +.PP +\fBReturns\fP +.RS 4 +retained object if found +.RE +.PP +Create a path in a heim_object_t tree +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP the tree +.br +\fIsize\fP the size of the heim_dict_t nodes to be created +.br +\fIleaf\fP leaf node to be added, if any +.br +\fIerror\fP error (output) +.br +\fIap\fP NULL-terminated of path component objects +.RE +.PP +Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted)\&. +.PP +\fBReturns\fP +.RS 4 +0 on success, else a system error +.RE +.PP +Create a path in a heim_object_t tree +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP the tree +.br +\fIsize\fP the size of the heim_dict_t nodes to be created +.br +\fIleaf\fP leaf node to be added, if any +.br +\fIerror\fP error (output) +.br +\fI\&.\&.\&.\fP NULL-terminated list of path component objects +.RE +.PP +Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted)\&. +.PP +\fBReturns\fP +.RS 4 +0 on success, else a system error +.RE +.PP +Delete leaf node named by a path in a heim_object_t tree +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP the tree +.br +\fIerror\fP error (output) +.br +\fIap\fP NULL-terminated list of path component objects +.RE +.PP +Dump a heimbase object to stderr (useful from the debugger!) +.PP +\fBParameters\fP +.RS 4 +\fIobj\fP object to dump using JSON or JSON-like format +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal base library from the source code\&. diff --git a/static/netbsd/man3/hesiod.3 b/static/netbsd/man3/hesiod.3 new file mode 100644 index 00000000..4c56107f --- /dev/null +++ b/static/netbsd/man3/hesiod.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: hesiod.3,v 1.1.1.2 2012/09/09 16:07:44 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: hesiod.3,v 1.4 2009/03/09 23:49:06 tbox Exp +.\" +.TH HESIOD 3 "30 November 1996" +.SH NAME +hesiod, hesiod_init, hesiod_resolve, hesiod_free_list, hesiod_to_bind, hesiod_end \- Hesiod name server interface library +.SH SYNOPSIS +.nf +.B #include +.PP +.B int hesiod_init(void **\fIcontext\fP) +.B char **hesiod_resolve(void *\fIcontext\fP, const char *\fIname\fP, +.B const char *\fItype\fP) +.B void hesiod_free_list(void *\fIcontext\fP, char **\fIlist\fP); +.B char *hesiod_to_bind(void *\fIcontext\fP, const char *\fIname\fP, +.B const char *\fItype\fP) +.B void hesiod_end(void *\fIcontext\fP) +.fi +.SH DESCRIPTION +This family of functions allows you to perform lookups of Hesiod +information, which is stored as text records in the Domain Name +Service. To perform lookups, you must first initialize a +.IR context , +an opaque object which stores information used internally by the +library between calls. +.I hesiod_init +initializes a context, storing a pointer to the context in the +location pointed to by the +.I context +argument. +.I hesiod_end +frees the resources used by a context. +.PP +.I hesiod_resolve +is the primary interface to the library. If successful, it returns a +list of one or more strings giving the records matching +.I name +and +.IR type . +The last element of the list is followed by a NULL pointer. It is the +caller's responsibility to call +.I hesiod_free_list +to free the resources used by the returned list. +.PP +.I hesiod_to_bind +converts +.I name +and +.I type +into the DNS name used by +.IR hesiod_resolve . +It is the caller's responsibility to free the returned string using +.IR free . +.SH RETURN VALUES +If successful, +.I hesiod_init +returns 0; otherwise it returns \-1 and sets +.I errno +to indicate the error. On failure, +.I hesiod_resolve +and +.I hesiod_to_bind +return NULL and set the global variable +.I errno +to indicate the error. +.SH ENVIRONMENT +If the environment variable +.B HES_DOMAIN +is set, it will override the domain in the Hesiod configuration file. +If the environment variable +.B HESIOD_CONFIG +is set, it specifies the location of the Hesiod configuration file. +.SH SEE ALSO +`Hesiod - Project Athena Technical Plan -- Name Service' +.SH ERRORS +Hesiod calls may fail because of: +.IP ENOMEM +Insufficient memory was available to carry out the requested +operation. +.IP ENOEXEC +.I hesiod_init +failed because the Hesiod configuration file was invalid. +.IP ECONNREFUSED +.I hesiod_resolve +failed because no name server could be contacted to answer the query. +.IP EMSGSIZE +.I hesiod_resolve +failed because the query or response was too big to fit into the +packet buffers. +.IP ENOENT +.I hesiod_resolve +failed because the name server had no text records matching +.I name +and +.IR type , +or +.I hesiod_to_bind +failed because the +.I name +argument had a domain extension which could not be resolved with type +``rhs-extension'' in the local Hesiod domain. +.SH AUTHOR +Steve Dyer, IBM/Project Athena +.br +Greg Hudson, MIT Team Athena +.br +Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology. +.SH BUGS +The strings corresponding to the +.I errno +values set by the Hesiod functions are not particularly indicative of +what went wrong, especially for +.I ENOEXEC +and +.IR ENOENT . diff --git a/static/netbsd/man3/history.3 b/static/netbsd/man3/history.3 new file mode 100644 index 00000000..06419cff --- /dev/null +++ b/static/netbsd/man3/history.3 @@ -0,0 +1,687 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet.ramey@case.edu +.\" +.\" Last Change: Fri Jul 17 09:43:01 EDT 2020 +.\" +.TH HISTORY 3 "2020 July 17" "GNU History 8.1" +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.ds lp \fR\|(\fP +.ds rp \fR\|)\fP +.\" FnN return-value fun-name N arguments +.de Fn1 +\fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp +.br +.. +.de Fn2 +.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp +.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp +.br +.. +.de Fn3 +.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp +.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp +.br +.. +.de Vb +\fI\\$1\fP \fB\\$2\fP +.br +.. +.SH NAME +history \- GNU History Library +.SH COPYRIGHT +.if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc. +.if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. +.SH DESCRIPTION +Many programs read input from the user a line at a time. The GNU +History library is able to keep track of those lines, associate arbitrary +data with each line, and utilize information from previous lines in +composing new ones. +.PP +.SH "HISTORY EXPANSION" +The history library supports a history expansion feature that +is identical to the history expansion in +.BR bash. +This section describes what syntax features are available. +.PP +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +.PP +History expansion is usually performed immediately after a complete line +is read. +It takes place in two parts. +The first is to determine which line from the history list +to use during substitution. +The second is to select portions of that line for inclusion into +the current one. +The line selected from the history is the \fIevent\fP, +and the portions of that line that are acted upon are \fIwords\fP. +Various \fImodifiers\fP are available to manipulate the selected words. +The line is broken into words in the same fashion as \fBbash\fP +does when reading input, +so that several words that would otherwise be separated +are considered one word when surrounded by quotes (see the +description of \fBhistory_tokenize()\fP below). +History expansions are introduced by the appearance of the +history expansion character, which is \^\fB!\fP\^ by default. +Only backslash (\^\fB\e\fP\^) and single quotes can quote +the history expansion character. +.SS Event Designators +An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +.PP +.PD 0 +.TP +.B ! +Start a history substitution, except when followed by a +.BR blank , +newline, = or (. +.TP +.B !\fIn\fR +Refer to command line +.IR n . +.TP +.B !\-\fIn\fR +Refer to the current command minus +.IR n . +.TP +.B !! +Refer to the previous command. This is a synonym for `!\-1'. +.TP +.B !\fIstring\fR +Refer to the most recent command +preceding the current position in the history list +starting with +.IR string . +.TP +.B !?\fIstring\fR\fB[?]\fR +Refer to the most recent command +preceding the current position in the history list +containing +.IR string . +The trailing \fB?\fP may be omitted if +.I string +is followed immediately by a newline. +If \fIstring\fP is missing, the string from the most recent search is used; +it is an error if there is no previous search string. +.TP +.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u +Quick substitution. Repeat the last command, replacing +.I string1 +with +.IR string2 . +Equivalent to +``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' +(see \fBModifiers\fP below). +.TP +.B !# +The entire command line typed so far. +.PD +.SS Word Designators +Word designators are used to select desired words from the event. +A +.B : +separates the event specification from the word designator. +It may be omitted if the word designator begins with a +.BR ^ , +.BR $ , +.BR * , +.BR \- , +or +.BR % . +Words are numbered from the beginning of the line, +with the first word being denoted by 0 (zero). +Words are inserted into the current line separated by single spaces. +.PP +.PD 0 +.TP +.B 0 (zero) +The zeroth word. For the shell, this is the command +word. +.TP +.I n +The \fIn\fRth word. +.TP +.B ^ +The first argument. That is, word 1. +.TP +.B $ +The last word. This is usually the last argument, but will expand to the +zeroth word if there is only one word in the line. +.TP +.B % +The first word matched by the most recent `?\fIstring\fR?' search, +if the search string begins with a character that is part of a word. +.TP +.I x\fB\-\fPy +A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. +.TP +.B * +All of the words but the zeroth. This is a synonym +for `\fI1\-$\fP'. It is not an error to use +.B * +if there is just one +word in the event; the empty string is returned in that case. +.TP +.B x* +Abbreviates \fIx\-$\fP. +.TP +.B x\- +Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. +If \fBx\fP is missing, it defaults to 0. +.PD +.PP +If a word designator is supplied without an event specification, the +previous command is used as the event. +.SS Modifiers +After the optional word designator, there may appear a sequence of +one or more of the following modifiers, each preceded by a `:'. +These modify, or edit, the word or words selected from the history event. +.PP +.PD 0 +.PP +.TP +.B h +Remove a trailing file name component, leaving only the head. +.TP +.B t +Remove all leading file name components, leaving the tail. +.TP +.B r +Remove a trailing suffix of the form \fI.xxx\fP, leaving the +basename. +.TP +.B e +Remove all but the trailing suffix. +.TP +.B p +Print the new command but do not execute it. +.TP +.B q +Quote the substituted words, escaping further substitutions. +.TP +.B x +Quote the substituted words as with +.BR q , +but break into words at +.B blanks +and newlines. +The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one +supplied is used. +.TP +.B s/\fIold\fP/\fInew\fP/ +Substitute +.I new +for the first occurrence of +.I old +in the event line. +Any character may be used as the delimiter in place of /. +The final delimiter is optional if it is the last character of the +event line. +The delimiter may be quoted in +.I old +and +.I new +with a single backslash. If & appears in +.IR new , +it is replaced by +.IR old . +A single backslash will quote the &. +If +.I old +is null, it is set to the last +.I old +substituted, or, if no previous history substitutions took place, +the last +.I string +in a +.B !?\fIstring\fR\fB[?]\fR +search. +If +.I new +is null, each matching +.I old +is deleted. +.TP +.B & +Repeat the previous substitution. +.TP +.B g +Cause changes to be applied over the entire event line. This is +used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') +or `\fB:&\fP'. If used with +`\fB:s\fP', any delimiter can be used +in place of /, and the final delimiter is optional +if it is the last character of the event line. +An \fBa\fP may be used as a synonym for \fBg\fP. +.TP +.B G +Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word +in the event line. +.PD +.SH "PROGRAMMING WITH HISTORY FUNCTIONS" +This section describes how to use the History library in other programs. +.SS Introduction to History +A programmer using the History library has available functions +for remembering lines on a history list, associating arbitrary data +with a line, removing lines from the list, searching through the list +for a line containing an arbitrary text string, and referencing any line +in the list directly. In addition, a history \fIexpansion\fP function +is available which provides for a consistent user interface across +different programs. +.PP +The user using programs written with the History library has the +benefit of a consistent user interface with a set of well-known +commands for manipulating the text of previous lines and using that text +in new commands. The basic history manipulation commands are +identical to +the history substitution provided by \fBbash\fP. +.PP +The programmer can also use the readline library, which +includes some history manipulation by default, and has the added +advantage of command line editing. +.PP +Before declaring any functions using any functionality the History +library provides in other code, an application writer should include +the file +.FN +in any file that uses the +History library's features. It supplies extern declarations for all +of the library's public functions and variables, and declares all of +the public data structures. +.SS History Storage +The history list is an array of history entries. A history entry is +declared as follows: +.PP +.Vb "typedef void *" histdata_t; +.PP +.nf +typedef struct _hist_entry { + char *line; + char *timestamp; + histdata_t data; +} HIST_ENTRY; +.fi +.PP +The history list itself might therefore be declared as +.PP +.Vb "HIST_ENTRY **" the_history_list; +.PP +The state of the History library is encapsulated into a single structure: +.PP +.nf +/* + * A structure used to pass around the current state of the history. + */ +typedef struct _hist_state { + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; +} HISTORY_STATE; +.fi +.PP +If the flags member includes \fBHS_STIFLED\fP, the history has been +stifled. +.SH "History Functions" +This section describes the calling sequence for the various functions +exported by the GNU History library. +.SS Initializing History and State Management +This section describes functions used to initialize and manage +the state of the History library when you want to use the history +functions in your program. + +.Fn1 void using_history void +Begin a session in which the history functions might be used. This +initializes the interactive variables. + +.Fn1 "HISTORY_STATE *" history_get_history_state void +Return a structure describing the current state of the input history. + +.Fn1 void history_set_history_state "HISTORY_STATE *state" +Set the state of the history list according to \fIstate\fP. + +.SS History List Management +These functions manage individual entries on the history list, or set +parameters managing the list itself. + +.Fn1 void add_history "const char *string" +Place \fIstring\fP at the end of the history list. The associated data +field (if any) is set to \fBNULL\fP. +If the maximum number of history entries has been set using +\fBstifle_history()\fP, and the new number of history entries would exceed +that maximum, the oldest history entry is removed. + +.Fn1 void add_history_time "const char *string" +Change the time stamp associated with the most recent history entry to +\fIstring\fP. + +.Fn1 "HIST_ENTRY *" remove_history "int which" +Remove history entry at offset \fIwhich\fP from the history. The +removed element is returned so you can free the line, data, +and containing structure. + +.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent" +Free the history entry \fIhistent\fP and any history library private +data associated with it. Returns the application-specific data +so the caller can dispose of it. + +.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" +Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP. +This returns the old entry so the caller can dispose of any +application-specific data. In the case +of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned. + +.Fn1 void clear_history "void" +Clear the history list by deleting all the entries. + +.Fn1 void stifle_history "int max" +Stifle the history list, remembering only the last \fImax\fP entries. +The history list will contain only \fImax\fP entries at a time. + +.Fn1 int unstifle_history "void" +Stop stifling the history. This returns the previously-set +maximum number of history entries (as set by \fBstifle_history()\fP). +history was stifled. The value is positive if the history was +stifled, negative if it wasn't. + +.Fn1 int history_is_stifled "void" +Returns non-zero if the history is stifled, zero if it is not. + +.SS Information About the History List + +These functions return information about the entire history list or +individual list entries. + +.Fn1 "HIST_ENTRY **" history_list "void" +Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the +current input history. Element 0 of this list is the beginning of time. +If there is no history, return \fBNULL\fP. + +.Fn1 int where_history "void" +Returns the offset of the current history element. + +.Fn1 "HIST_ENTRY *" current_history "void" +Return the history entry at the current position, as determined by +\fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP +pointer. + +.Fn1 "HIST_ENTRY *" history_get "int offset" +Return the history entry at position \fIoffset\fP. +The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP +and ends at \fBhistory_length\fP \- 1. +If there is no entry there, or if \fIoffset\fP is outside the valid +range, return a \fBNULL\fP pointer. + +.Fn1 "time_t" history_get_time "HIST_ENTRY *" +Return the time stamp associated with the history entry passed as the argument. + +.Fn1 int history_total_bytes "void" +Return the number of bytes that the primary history entries are using. +This function returns the sum of the lengths of all the lines in the +history. + +.SS Moving Around the History List + +These functions allow the current index into the history list to be +set or changed. + +.Fn1 int history_set_pos "int pos" +Set the current history offset to \fIpos\fP, an absolute index +into the list. +Returns 1 on success, 0 if \fIpos\fP is less than zero or greater +than the number of history entries. + +.Fn1 "HIST_ENTRY *" previous_history "void" +Back up the current history offset to the previous history entry, and +return a pointer to that entry. If there is no previous entry, return +a \fBNULL\fP pointer. + +.Fn1 "HIST_ENTRY *" next_history "void" +If the current history offset refers to a valid history entry, +increment the current history offset. +If the possibly-incremented history offset refers to a valid history +entry, return a pointer to that entry; +otherwise, return a \fBNULL\fP pointer. + +.SS Searching the History List + +These functions allow searching of the history list for entries containing +a specific string. Searching may be performed both forward and backward +from the current history position. The search may be \fIanchored\fP, +meaning that the string must match at the beginning of the history entry. + +.Fn2 int history_search "const char *string" "int direction" +Search the history for \fIstring\fP, starting at the current history offset. +If \fIdirection\fP is less than 0, then the search is through +previous entries, otherwise through subsequent entries. +If \fIstring\fP is found, then +the current history index is set to that history entry, and the value +returned is the offset in the line of the entry where +\fIstring\fP was found. Otherwise, nothing is changed, and a -1 is +returned. + +.Fn2 int history_search_prefix "const char *string" "int direction" +Search the history for \fIstring\fP, starting at the current history +offset. The search is anchored: matching lines must begin with +\fIstring\fP. If \fIdirection\fP is less than 0, then the search is +through previous entries, otherwise through subsequent entries. +If \fIstring\fP is found, then the +current history index is set to that entry, and the return value is 0. +Otherwise, nothing is changed, and a -1 is returned. + +.Fn3 int history_search_pos "const char *string" "int direction" "int pos" +Search for \fIstring\fP in the history list, starting at \fIpos\fP, an +absolute index into the list. If \fIdirection\fP is negative, the search +proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute +index of the history element where \fIstring\fP was found, or -1 otherwise. + +.SS Managing the History File +The History library can read the history from and write it to a file. +This section documents the functions for managing a history file. + +.Fn1 int read_history "const char *filename" +Add the contents of \fIfilename\fP to the history list, a line at a time. +If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP. +Returns 0 if successful, or \fBerrno\fP if not. + +.Fn3 int read_history_range "const char *filename" "int from" "int to" +Read a range of lines from \fIfilename\fP, adding them to the history list. +Start reading at line \fIfrom\fP and end at \fIto\fP. +If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than +\fIfrom\fP, then read until the end of the file. If \fIfilename\fP is +\fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful, +or \fBerrno\fP if not. + +.Fn1 int write_history "const char *filename" +Write the current history to \fIfilename\fP, overwriting \fIfilename\fP +if necessary. +If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP. +Returns 0 on success, or \fBerrno\fP on a read or write error. + + +.Fn2 int append_history "int nelements" "const char *filename" +Append the last \fInelements\fP of the history list to \fIfilename\fP. +If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP. +Returns 0 on success, or \fBerrno\fP on a read or write error. + +.Fn2 int history_truncate_file "const char *filename" "int nlines" +Truncate the history file \fIfilename\fP, leaving only the last +\fInlines\fP lines. +If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated. +Returns 0 on success, or \fBerrno\fP on failure. + +.SS History Expansion + +These functions implement history expansion. + +.Fn2 int history_expand "char *string" "char **output" +Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer +to a string. Returns: +.RS +.PD 0 +.TP +0 +If no expansions took place (or, if the only change in +the text was the removal of escape characters preceding the history expansion +character); +.TP +1 +if expansions did take place; +.TP +-1 +if there was an error in expansion; +.TP +2 +if the returned line should be displayed, but not executed, +as with the \fB:p\fP modifier. +.PD +.RE +If an error occurred in expansion, then \fIoutput\fP contains a descriptive +error message. + +.Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" +Returns the text of the history event beginning at \fIstring\fP + +\fI*cindex\fP. \fI*cindex\fP is modified to point to after the event +specifier. At function entry, \fIcindex\fP points to the index into +\fIstring\fP where the history event specification begins. \fIqchar\fP +is a character that is allowed to end the event specification in addition +to the ``normal'' terminating characters. + +.Fn1 "char **" history_tokenize "const char *string" +Return an array of tokens parsed out of \fIstring\fP, much as the +shell might. +The tokens are split on the characters in the +\fBhistory_word_delimiters\fP variable, +and shell quoting conventions are obeyed. + +.Fn3 "char *" history_arg_extract "int first" "int last" "const char *string" +Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP +arguments present in \fIstring\fP. Arguments are split using +\fBhistory_tokenize()\fP. + +.SS History Variables + +This section describes the externally-visible variables exported by +the GNU History Library. + +.Vb int history_base +The logical offset of the first entry in the history list. + +.Vb int history_length +The number of entries currently stored in the history list. + +.Vb int history_max_entries +The maximum number of history entries. This must be changed using +\fBstifle_history()\fP. + +.Vb int history_write_timestamps +If non-zero, timestamps are written to the history file, so they can be +preserved between sessions. The default value is 0, meaning that +timestamps are not saved. +The current timestamp format uses the value of \fIhistory_comment_char\fP +to delimit timestamp entries in the history file. If that variable does +not have a value (the default), timestamps will not be written. + +.Vb char history_expansion_char +The character that introduces a history event. The default is \fB!\fP. +Setting this to 0 inhibits history expansion. + +.Vb char history_subst_char +The character that invokes word substitution if found at the start of +a line. The default is \fB^\fP. + +.Vb char history_comment_char +During tokenization, if this character is seen as the first character +of a word, then it and all subsequent characters up to a newline are +ignored, suppressing history expansion for the remainder of the line. +This is disabled by default. + +.Vb "char *" history_word_delimiters +The characters that separate tokens for \fBhistory_tokenize()\fP. +The default value is \fB"\ \et\en()<>;&|"\fP. + +.Vb "char *" history_no_expand_chars +The list of characters which inhibit history expansion if found immediately +following \fBhistory_expansion_char\fP. The default is space, tab, newline, +\fB\er\fP, and \fB=\fP. + +.Vb "char *" history_search_delimiter_chars +The list of additional characters which can delimit a history search +string, in addition to space, tab, \fI:\fP and \fI?\fP in the case of +a substring search. The default is empty. + +.Vb int history_quotes_inhibit_expansion +If non-zero, double-quoted words are not scanned for the history expansion +character or the history comment character. The default value is 0. + +.Vb "rl_linebuf_func_t *" history_inhibit_expansion_function +This should be set to the address of a function that takes two arguments: +a \fBchar *\fP (\fIstring\fP) +and an \fBint\fP index into that string (\fIi\fP). +It should return a non-zero value if the history expansion starting at +\fIstring[i]\fP should not be performed; zero if the expansion should +be done. +It is intended for use by applications like \fBbash\fP that use the history +expansion character for additional purposes. +By default, this variable is set to \fBNULL\fP. +.SH FILES +.PD 0 +.TP +.FN ~/.history +Default filename for reading and writing saved history +.PD +.SH "SEE ALSO" +.PD 0 +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIbash\fP(1) +.TP +\fIreadline\fP(3) +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet.ramey@case.edu +.SH BUG REPORTS +If you find a bug in the +.B history +library, you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of the +.B history +library that you have. +.PP +Once you have determined that a bug actually exists, mail a +bug report to \fIbug\-readline\fP@\fIgnu.org\fP. +If you have a fix, you are welcome to mail that +as well! Suggestions and `philosophical' bug reports may be mailed +to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet.ramey@case.edu . diff --git a/static/netbsd/man3/hosts_access.3 b/static/netbsd/man3/hosts_access.3 new file mode 100644 index 00000000..684a7377 --- /dev/null +++ b/static/netbsd/man3/hosts_access.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: hosts_access.3,v 1.7 2002/10/01 19:38:46 wiz Exp $ +.\" +.TH HOSTS_ACCESS 3 +.SH NAME +hosts_access, hosts_ctl, request_init, request_set \- access control library +.SH SYNOPSIS +.nf +#include "tcpd.h" + +extern int allow_severity; +extern int deny_severity; + +struct request_info *request_init(request, key, value, ..., 0) +struct request_info *request; + +struct request_info *request_set(request, key, value, ..., 0) +struct request_info *request; + +int hosts_access(request) +struct request_info *request; + +int hosts_ctl(daemon, client_name, client_addr, client_user) +char *daemon; +char *client_name; +char *client_addr; +char *client_user; +.fi +.SH DESCRIPTION +The routines described in this document are part +of the \fIlibwrap.a\fR library. +They implement a rule-based access control language with +optional shell commands that are executed when a rule fires. +.PP +request_init() initializes a structure with +information about a client request. +request_set() updates an already initialized request structure. +Both functions take a variable-length list of key-value +pairs and return their first argument. +The argument lists are terminated with a zero key value. +All string-valued arguments are copied. +The expected keys (and corresponding value types) are: +.IP "RQ_FILE (int)" +The file descriptor associated with the request. +.IP "RQ_CLIENT_NAME (char *)" +The client host name. +.IP "RQ_CLIENT_ADDR (char *)" +A printable representation of the client network address. +.IP "RQ_CLIENT_SIN (struct sockaddr_in *)" +An internal representation of the client network address and port. +The contents of the structure are not copied. +.IP "RQ_SERVER_NAME (char *)" +The hostname associated with the server endpoint address. +.IP "RQ_SERVER_ADDR (char *)" +A printable representation of the server endpoint address. +.IP "RQ_SERVER_SIN (struct sockaddr_in *)" +An internal representation of the server endpoint address and port. +The contents of the structure are not copied. +.IP "RQ_DAEMON (char *)" +The name of the daemon process running on the server host. +.IP "RQ_USER (char *)" +The name of the user on whose behalf the client host makes the request. +.PP +hosts_access() consults the access control tables described in the +\fIhosts_access(5)\fR manual page. +When internal endpoint information is available, host names +and client user names are looked up on demand, +using the request structure as a cache. +hosts_access() returns zero if access should be denied. +.PP +hosts_ctl() is a wrapper around the request_init() and hosts_access() +routines with a perhaps more convenient interface (though it does not +pass on enough information to support automated client username lookups). +The client host address, client host name and username +arguments should contain valid data or STRING_UNKNOWN. +hosts_ctl() returns zero if access should be denied. +.PP +The \fIallow_severity\fR and \fIdeny_severity\fR variables determine +how accepted and rejected requests may be logged. +They must be provided by the caller and may be modified +by rules in the access control tables. +.SH DIAGNOSTICS +Problems are reported via the syslog daemon. +.SH SEE ALSO +hosts_access(5), format of the access control tables. +hosts_options(5), optional extensions to the base language. +.SH FILES +/etc/hosts.allow, /etc/hosts.deny, access control tables. +.SH AUTHOR +.na +.nf +Wietse Venema (wietse@wzv.win.tue.nl) +Department of Mathematics and Computing Science +Eindhoven University of Technology +Den Dolech 2, P.O. Box 513, +5600 MB Eindhoven, The Netherlands +\" @(#) hosts_access.3 1.8 96/02/11 17:01:26 diff --git a/static/netbsd/man3/http.h.3 b/static/netbsd/man3/http.h.3 new file mode 100644 index 00000000..d05f22a6 --- /dev/null +++ b/static/netbsd/man3/http.h.3 @@ -0,0 +1,1668 @@ +.TH "event2/http.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/http.h \- Basic support for HTTP serving\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVHTTP_CON_LINGERING_CLOSE\fP 0x0020" +.br +.ti -1c +.RI "#define \fBEVHTTP_CON_PUBLIC_FLAGS_END\fP 0x100000" +.br +.ti -1c +.RI "#define \fBEVHTTP_CON_READ_ON_WRITE_ERROR\fP 0x0010" +.br +.ti -1c +.RI "#define \fBEVHTTP_CON_REUSE_CONNECTED_ADDR\fP 0x0008" +.br +.ti -1c +.RI "#define \fBEVHTTP_SERVER_LINGERING_CLOSE\fP 0x0001" +.br +.ti -1c +.RI "#define \fBEVHTTP_URI_NONCONFORMANT\fP 0x01" +.br +.RI "\fITolerate URIs that do not conform to RFC3986\&. \fP" +.ti -1c +.RI "#define \fBHTTP_BADMETHOD\fP 405" +.br +.RI "\fImethod not allowed for this uri \fP" +.ti -1c +.RI "#define \fBHTTP_BADREQUEST\fP 400" +.br +.RI "\fIinvalid http request was made \fP" +.ti -1c +.RI "#define \fBHTTP_ENTITYTOOLARGE\fP 413" +.br +.ti -1c +.RI "#define \fBHTTP_EXPECTATIONFAILED\fP 417" +.br +.RI "\fIwe can't handle this expectation \fP" +.ti -1c +.RI "#define \fBHTTP_INTERNAL\fP 500" +.br +.RI "\fIinternal error \fP" +.ti -1c +.RI "#define \fBHTTP_MOVEPERM\fP 301" +.br +.RI "\fIthe uri moved permanently \fP" +.ti -1c +.RI "#define \fBHTTP_MOVETEMP\fP 302" +.br +.RI "\fIthe uri moved temporarily \fP" +.ti -1c +.RI "#define \fBHTTP_NOCONTENT\fP 204" +.br +.RI "\fIrequest does not have content \fP" +.ti -1c +.RI "#define \fBHTTP_NOTFOUND\fP 404" +.br +.RI "\fIcould not find content for uri \fP" +.ti -1c +.RI "#define \fBHTTP_NOTIMPLEMENTED\fP 501" +.br +.RI "\fInot implemented \fP" +.ti -1c +.RI "#define \fBHTTP_NOTMODIFIED\fP 304" +.br +.RI "\fIpage was not modified from last \fP" +.ti -1c +.RI "#define \fBHTTP_OK\fP 200" +.br +.RI "\fIrequest completed ok \fP" +.ti -1c +.RI "#define \fBHTTP_SERVUNAVAIL\fP 503" +.br +.RI "\fIthe server is not available \fP" +.in -1c +.SS "Typedefs" + +.in +1c +.ti -1c +.RI "typedef void \fBevhttp_bound_socket_foreach_fn\fP(struct evhttp_bound_socket *, void *)" +.br +.in -1c +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBevhttp_cmd_type\fP { \fBEVHTTP_REQ_GET\fP = 1 << 0, \fBEVHTTP_REQ_POST\fP = 1 << 1, \fBEVHTTP_REQ_HEAD\fP = 1 << 2, \fBEVHTTP_REQ_PUT\fP = 1 << 3, \fBEVHTTP_REQ_DELETE\fP = 1 << 4, \fBEVHTTP_REQ_OPTIONS\fP = 1 << 5, \fBEVHTTP_REQ_TRACE\fP = 1 << 6, \fBEVHTTP_REQ_CONNECT\fP = 1 << 7, \fBEVHTTP_REQ_PATCH\fP = 1 << 8 } +.RI "\fIThe different request types supported by evhttp\&. \fP"" +.br +.ti -1c +.RI "enum \fBevhttp_request_error\fP { \fBEVREQ_HTTP_TIMEOUT\fP, \fBEVREQ_HTTP_EOF\fP, \fBEVREQ_HTTP_INVALID_HEADER\fP, \fBEVREQ_HTTP_BUFFER_ERROR\fP, \fBEVREQ_HTTP_REQUEST_CANCEL\fP, \fBEVREQ_HTTP_DATA_TOO_LONG\fP } +.RI "\fIThe different error types supported by evhttp\&. \fP"" +.br +.ti -1c +.RI "enum \fBevhttp_request_kind\fP { \fBEVHTTP_REQUEST\fP, \fBEVHTTP_RESPONSE\fP } +.RI "\fIa request object can represent either a request or a reply \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_accept_socket\fP (struct evhttp *http, \fBevutil_socket_t\fP fd)" +.br +.RI "\fIMakes an HTTP server accept connections on the specified socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket * \fBevhttp_accept_socket_with_handle\fP (struct evhttp *http, \fBevutil_socket_t\fP fd)" +.br +.RI "\fILike \fBevhttp_accept_socket()\fP, but returns a handle for referencing the socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_add_header\fP (struct evkeyvalq *headers, const char *key, const char *value)" +.br +.RI "\fIAdds a header to a list of existing headers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_add_server_alias\fP (struct evhttp *http, const char *alias)" +.br +.RI "\fIAdd a server alias to an http object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_add_virtual_host\fP (struct evhttp *http, const char *pattern, struct evhttp *vhost)" +.br +.RI "\fIAdds a virtual host to the http server\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket * \fBevhttp_bind_listener\fP (struct evhttp *http, struct evconnlistener *listener)" +.br +.RI "\fIThe most low-level evhttp_bind/accept method: takes an evconnlistener, and returns an evhttp_bound_socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_bind_socket\fP (struct evhttp *http, const char *address, ev_uint16_t port)" +.br +.RI "\fIBinds an HTTP server on the specified address and port\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket * \fBevhttp_bind_socket_with_handle\fP (struct evhttp *http, const char *address, ev_uint16_t port)" +.br +.RI "\fILike \fBevhttp_bind_socket()\fP, but returns a handle for referencing the socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL \fBevutil_socket_t\fP \fBevhttp_bound_socket_get_fd\fP (struct evhttp_bound_socket *bound_socket)" +.br +.RI "\fIGet the raw file descriptor referenced by an evhttp_bound_socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evconnlistener * \fBevhttp_bound_socket_get_listener\fP (struct evhttp_bound_socket *bound)" +.br +.RI "\fIReturn the listener used to implement a bound socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_cancel_request\fP (struct evhttp_request *req)" +.br +.RI "\fICancels a pending HTTP request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_clear_headers\fP (struct evkeyvalq *headers)" +.br +.RI "\fIRemoves all headers from the header list\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_connection * \fBevhttp_connection_base_bufferevent_new\fP (struct \fBevent_base\fP *base, struct evdns_base *dnsbase, struct \fBbufferevent\fP *bev, const char *address, ev_uint16_t port)" +.br +.RI "\fICreate and return a connection object that can be used to for making HTTP requests\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_connection * \fBevhttp_connection_base_new\fP (struct \fBevent_base\fP *base, struct evdns_base *dnsbase, const char *address, ev_uint16_t port)" +.br +.RI "\fICreate and return a connection object that can be used to for making HTTP requests\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_free\fP (struct evhttp_connection *evcon)" +.br +.RI "\fIFrees an http connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_free_on_completion\fP (struct evhttp_connection *evcon)" +.br +.RI "\fIDisowns a given connection object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const struct sockaddr * \fBevhttp_connection_get_addr\fP (struct evhttp_connection *evcon)" +.br +.RI "\fIGet the remote address associated with this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevent_base\fP * \fBevhttp_connection_get_base\fP (struct evhttp_connection *req)" +.br +.RI "\fIReturns the underlying \fBevent_base\fP for this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBbufferevent\fP * \fBevhttp_connection_get_bufferevent\fP (struct evhttp_connection *evcon)" +.br +.RI "\fIReturn the bufferevent that an evhttp_connection is using\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_get_peer\fP (struct evhttp_connection *evcon, char **address, ev_uint16_t *port)" +.br +.RI "\fIGet the remote address and port associated with this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp * \fBevhttp_connection_get_server\fP (struct evhttp_connection *evcon)" +.br +.RI "\fIReturn the HTTP server associated with this connection, or NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_closecb\fP (struct evhttp_connection *evcon, void(*)(struct evhttp_connection *, void *), void *)" +.br +.RI "\fISet a callback for connection close\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_family\fP (struct evhttp_connection *evcon, int family)" +.br +.RI "\fISet family hint for DNS requests\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_connection_set_flags\fP (struct evhttp_connection *evcon, int flags)" +.br +.RI "\fISet connection flags\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_initial_retry_tv\fP (struct evhttp_connection *evcon, const struct timeval *tv)" +.br +.RI "\fISets the delay before retrying requests on this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_local_address\fP (struct evhttp_connection *evcon, const char *address)" +.br +.RI "\fIsets the ip address from which http connections are made \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_local_port\fP (struct evhttp_connection *evcon, ev_uint16_t port)" +.br +.RI "\fIsets the local port from which http connections are made \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_max_body_size\fP (struct evhttp_connection *evcon, ev_ssize_t new_max_body_size)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_max_headers_size\fP (struct evhttp_connection *evcon, ev_ssize_t new_max_headers_size)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_retries\fP (struct evhttp_connection *evcon, int retry_max)" +.br +.RI "\fISets the retry limit for this connection - -1 repeats indefinitely\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_timeout\fP (struct evhttp_connection *evcon, int timeout_in_secs)" +.br +.RI "\fISets the timeout in seconds for events related to this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_connection_set_timeout_tv\fP (struct evhttp_connection *evcon, const struct timeval *tv)" +.br +.RI "\fISets the timeout for events related to this connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_decode_uri\fP (const char *uri)" +.br +.RI "\fIHelper function to sort of decode a URI-encoded string\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_del_accept_socket\fP (struct evhttp *http, struct evhttp_bound_socket *bound_socket)" +.br +.RI "\fIMakes an HTTP server stop accepting connections on the specified socket\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_del_cb\fP (struct evhttp *, const char *)" +.br +.RI "\fIRemoves the callback for a specified URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_encode_uri\fP (const char *str)" +.br +.RI "\fIHelper function to encode a string for inclusion in a URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_find_header\fP (const struct evkeyvalq *headers, const char *key)" +.br +.RI "\fIFinds the value belonging to a header\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_foreach_bound_socket\fP (struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument)" +.br +.RI "\fIApplies the function specified in the first argument to all evhttp_bound_sockets associated with 'http'\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_free\fP (struct evhttp *http)" +.br +.RI "\fIFree the previously created HTTP server\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_htmlescape\fP (const char *html)" +.br +.RI "\fIEscape HTML character entities in a string\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_make_request\fP (struct evhttp_connection *evcon, struct evhttp_request *req, enum \fBevhttp_cmd_type\fP type, const char *uri)" +.br +.RI "\fIMake an HTTP request over the specified connection\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp * \fBevhttp_new\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fICreate a new HTTP server\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_parse_query\fP (const char *uri, struct evkeyvalq *headers)" +.br +.RI "\fIHelper function to parse out arguments in a query\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_parse_query_str\fP (const char *uri, struct evkeyvalq *headers)" +.br +.RI "\fIHelper function to parse out arguments from the query portion of an HTTP URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_remove_header\fP (struct evkeyvalq *headers, const char *key)" +.br +.RI "\fIRemoves a header from a list of existing headers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_remove_server_alias\fP (struct evhttp *http, const char *alias)" +.br +.RI "\fIRemove a server alias from an http object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_remove_virtual_host\fP (struct evhttp *http, struct evhttp *vhost)" +.br +.RI "\fIRemoves a virtual host from the http server\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_free\fP (struct evhttp_request *req)" +.br +.RI "\fIFrees the request object and removes associated events\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL enum \fBevhttp_cmd_type\fP \fBevhttp_request_get_command\fP (const struct evhttp_request *req)" +.br +.RI "\fIReturns the request command\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_connection * \fBevhttp_request_get_connection\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the connection object associated with the request or NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const struct evhttp_uri * \fBevhttp_request_get_evhttp_uri\fP (const struct evhttp_request *req)" +.br +.RI "\fIReturns the request URI (parsed) \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_request_get_host\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the host associated with the request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP * \fBevhttp_request_get_input_buffer\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the input buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evkeyvalq * \fBevhttp_request_get_input_headers\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the input headers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevbuffer\fP * \fBevhttp_request_get_output_buffer\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the output buffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evkeyvalq * \fBevhttp_request_get_output_headers\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns the output headers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_request_get_response_code\fP (const struct evhttp_request *req)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_request_get_response_code_line\fP (const struct evhttp_request *req)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_request_get_uri\fP (const struct evhttp_request *req)" +.br +.RI "\fIReturns the request URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_request_is_owned\fP (struct evhttp_request *req)" +.br +.RI "\fIReturns 1 if the request is owned by the user\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_request * \fBevhttp_request_new\fP (void(*cb)(struct evhttp_request *, void *), void *arg)" +.br +.RI "\fICreates a new request object that needs to be filled in with the request parameters\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_own\fP (struct evhttp_request *req)" +.br +.RI "\fITakes ownership of the request object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_set_chunked_cb\fP (struct evhttp_request *, void(*cb)(struct evhttp_request *, void *))" +.br +.RI "\fIEnable delivery of chunks to requestor\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_set_error_cb\fP (struct evhttp_request *, void(*)(enum \fBevhttp_request_error\fP, void *))" +.br +.RI "\fISet a callback for errors\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_set_header_cb\fP (struct evhttp_request *, int(*cb)(struct evhttp_request *, void *))" +.br +.RI "\fIRegister callback for additional parsing of request headers\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_request_set_on_complete_cb\fP (struct evhttp_request *req, void(*cb)(struct evhttp_request *, void *), void *cb_arg)" +.br +.RI "\fISet a callback to be called on request completion of evhttp_send_* function\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_error\fP (struct evhttp_request *req, int error, const char *reason)" +.br +.RI "\fISend an HTML error message to the client\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_reply\fP (struct evhttp_request *req, int code, const char *reason, struct \fBevbuffer\fP *databuf)" +.br +.RI "\fISend an HTML reply to the client\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_reply_chunk\fP (struct evhttp_request *req, struct \fBevbuffer\fP *databuf)" +.br +.RI "\fISend another data chunk as part of an ongoing chunked reply\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_reply_chunk_with_cb\fP (struct evhttp_request *, struct \fBevbuffer\fP *, void(*cb)(struct evhttp_connection *, void *), void *arg)" +.br +.RI "\fISend another data chunk as part of an ongoing chunked reply\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_reply_end\fP (struct evhttp_request *req)" +.br +.RI "\fIComplete a chunked reply, freeing the request as appropriate\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_send_reply_start\fP (struct evhttp_request *req, int code, const char *reason)" +.br +.RI "\fIInitiate a reply that uses Transfer-Encoding chunked\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_allowed_methods\fP (struct evhttp *http, ev_uint16_t methods)" +.br +.RI "\fISets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_bevcb\fP (struct evhttp *http, struct \fBbufferevent\fP *(*cb)(struct \fBevent_base\fP *, void *), void *arg)" +.br +.RI "\fISet a callback used to create new bufferevents for connections to a given evhttp object\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_set_cb\fP (struct evhttp *http, const char *path, void(*cb)(struct evhttp_request *, void *), void *cb_arg)" +.br +.RI "\fISet a callback for a specified URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_default_content_type\fP (struct evhttp *http, const char *content_type)" +.br +.RI "\fISet the value to use for the Content-Type header when none was provided\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_set_flags\fP (struct evhttp *http, int flags)" +.br +.RI "\fISet connection flags for HTTP server\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_gencb\fP (struct evhttp *http, void(*cb)(struct evhttp_request *, void *), void *arg)" +.br +.RI "\fISet a callback for all requests that are not caught by specific callbacks\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_max_body_size\fP (struct evhttp *http, ev_ssize_t max_body_size)" +.br +.RI "\fIXXX Document\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_max_headers_size\fP (struct evhttp *http, ev_ssize_t max_headers_size)" +.br +.RI "\fIXXX Document\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_timeout\fP (struct evhttp *http, int timeout_in_secs)" +.br +.RI "\fISet the timeout for an HTTP request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_set_timeout_tv\fP (struct evhttp *http, const struct timeval *tv)" +.br +.RI "\fISet the timeout for an HTTP request\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_uri_free\fP (struct evhttp_uri *uri)" +.br +.RI "\fIFree all memory allocated for a parsed uri\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_fragment\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the fragment part of an evhttp_uri (excluding the leading '#'), or NULL if it has no fragment set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_host\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the host part of an evhttp_uri, or NULL if it has no host set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_path\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the path part of an evhttp_uri, or NULL if it has no path set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_get_port\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the port part of an evhttp_uri, or -1 if there is no port set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_query\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the query part of an evhttp_uri (excluding the leading '?'), or NULL if it has no query set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_scheme\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the scheme of an evhttp_uri, or NULL if there is no scheme has been set and the evhttp_uri contains a Relative-Ref\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevhttp_uri_get_userinfo\fP (const struct evhttp_uri *uri)" +.br +.RI "\fIReturn the userinfo part of an evhttp_uri, or NULL if it has no userinfo set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_uri_join\fP (struct evhttp_uri *uri, char *buf, size_t limit)" +.br +.RI "\fIJoin together the uri parts from parsed data to form a URI-Reference\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_uri * \fBevhttp_uri_new\fP (void)" +.br +.RI "\fIReturn a new empty evhttp_uri with no fields set\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_uri * \fBevhttp_uri_parse\fP (const char *source_uri)" +.br +.RI "\fIAlias for evhttp_uri_parse_with_flags(source_uri, 0) \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct evhttp_uri * \fBevhttp_uri_parse_with_flags\fP (const char *source_uri, unsigned flags)" +.br +.RI "\fIHelper function to parse a URI-Reference as specified by RFC3986\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevhttp_uri_set_flags\fP (struct evhttp_uri *uri, unsigned flags)" +.br +.RI "\fIChanges the flags set on a given URI\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_fragment\fP (struct evhttp_uri *uri, const char *fragment)" +.br +.RI "\fISet the fragment of an evhttp_uri, or clear the fragment if fragment==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_host\fP (struct evhttp_uri *uri, const char *host)" +.br +.RI "\fISet the host of an evhttp_uri, or clear the host if host==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_path\fP (struct evhttp_uri *uri, const char *path)" +.br +.RI "\fISet the path of an evhttp_uri, or clear the path if path==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_port\fP (struct evhttp_uri *uri, int port)" +.br +.RI "\fISet the port of an evhttp_uri, or clear the port if port==-1\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_query\fP (struct evhttp_uri *uri, const char *query)" +.br +.RI "\fISet the query of an evhttp_uri, or clear the query if query==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_scheme\fP (struct evhttp_uri *uri, const char *scheme)" +.br +.RI "\fISet the scheme of an evhttp_uri, or clear the scheme if scheme==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevhttp_uri_set_userinfo\fP (struct evhttp_uri *uri, const char *userinfo)" +.br +.RI "\fISet the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_uridecode\fP (const char *uri, int decode_plus, size_t *size_out)" +.br +.RI "\fIHelper function to decode a URI-escaped string or HTTP parameter\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL char * \fBevhttp_uriencode\fP (const char *str, ev_ssize_t size, int space_to_plus)" +.br +.RI "\fIAs evhttp_encode_uri, but if 'size' is nonnegative, treat the string as being 'size' bytes long\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Basic support for HTTP serving\&. + +As Libevent is a library for dealing with event notification and most interesting applications are networked today, I have often found the need to write HTTP code\&. The following prototypes and definitions provide an application with a minimal interface for making HTTP requests and for creating a very simple HTTP server\&. +.SH "Macro Definition Documentation" +.PP +.SS "#define EVHTTP_URI_NONCONFORMANT 0x01" + +.PP +Tolerate URIs that do not conform to RFC3986\&. Unfortunately, some HTTP clients generate URIs that, according to RFC3986, are not conformant URIs\&. If you need to support these URIs, you can do so by passing this flag to evhttp_uri_parse_with_flags\&. +.PP +Currently, these changes are: +.PD 0 + +.IP "\(bu" 2 +Nonconformant URIs are allowed to contain otherwise unreasonable characters in their path, query, and fragment components\&. +.PP + +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBevhttp_cmd_type\fP" + +.PP +The different request types supported by evhttp\&. These are as specified in RFC2616, except for PATCH which is specified by RFC5789\&. +.PP +By default, only some of these methods are accepted and passed to user callbacks; use \fBevhttp_set_allowed_methods()\fP to change which methods are allowed\&. +.SS "enum \fBevhttp_request_error\fP" + +.PP +The different error types supported by evhttp\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_request_set_error_cb()\fP +.RE +.PP + +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVREQ_HTTP_TIMEOUT \fP\fP +Timeout reached, also\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_connection_set_timeout()\fP +.RE +.PP + +.TP +\fB\fIEVREQ_HTTP_EOF \fP\fP +EOF reached\&. +.TP +\fB\fIEVREQ_HTTP_INVALID_HEADER \fP\fP +Error while reading header, or invalid header\&. +.TP +\fB\fIEVREQ_HTTP_BUFFER_ERROR \fP\fP +Error encountered while reading or writing\&. +.TP +\fB\fIEVREQ_HTTP_REQUEST_CANCEL \fP\fP +The \fBevhttp_cancel_request()\fP called on this request\&. +.TP +\fB\fIEVREQ_HTTP_DATA_TOO_LONG \fP\fP +Body is greater then evhttp_connection_set_max_body_size() +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL int evhttp_accept_socket (struct evhttp * http, \fBevutil_socket_t\fP fd)" + +.PP +Makes an HTTP server accept connections on the specified socket\&. This may be useful to create a socket and then fork multiple instances of an http server, or when a socket has been communicated via file descriptor passing in situations where an http servers does not have permissions to bind to a low-numbered port\&. +.PP +Can be called multiple times to have the http server listen to multiple different sockets\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP a pointer to an evhttp object +.br +\fIfd\fP a socket fd that is ready for accepting connections +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_bind_socket()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket* evhttp_accept_socket_with_handle (struct evhttp * http, \fBevutil_socket_t\fP fd)" + +.PP +Like \fBevhttp_accept_socket()\fP, but returns a handle for referencing the socket\&. The returned pointer is not valid after \fIhttp\fP is freed\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP a pointer to an evhttp object +.br +\fIfd\fP a socket fd that is ready for accepting connections +.RE +.PP +\fBReturns:\fP +.RS 4 +Handle for the socket on success, NULL on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_accept_socket()\fP, \fBevhttp_del_accept_socket()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_add_header (struct evkeyvalq * headers, const char * key, const char * value)" + +.PP +Adds a header to a list of existing headers\&. +.PP +\fBParameters:\fP +.RS 4 +\fIheaders\fP the evkeyvalq object to which to add a header +.br +\fIkey\fP the name of the header +.br +\fIvalue\fP the value belonging to the header +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 otherwise\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_find_header()\fP, \fBevhttp_clear_headers()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_add_server_alias (struct evhttp * http, const char * alias)" + +.PP +Add a server alias to an http object\&. The http object can be a virtual host or the main server\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp object +.br +\fIalias\fP the alias to add +.RE +.PP +\fBSee also:\fP +.RS 4 +evhttp_add_remove_alias() +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_add_virtual_host (struct evhttp * http, const char * pattern, struct evhttp * vhost)" + +.PP +Adds a virtual host to the http server\&. A virtual host is a newly initialized evhttp object that has request callbacks set on it via \fBevhttp_set_cb()\fP or \fBevhttp_set_gencb()\fP\&. It most not have any listing sockets associated with it\&. +.PP +If the virtual host has not been removed by the time that \fBevhttp_free()\fP is called on the main http server, it will be automatically freed, too\&. +.PP +It is possible to have hierarchical vhosts\&. For example: A vhost with the pattern *\&.example\&.com may have other vhosts with patterns foo\&.example\&.com and bar\&.example\&.com associated with it\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp object to which to add a virtual host +.br +\fIpattern\fP the glob pattern against which the hostname is matched\&. The match is case insensitive and follows otherwise regular shell matching\&. +.br +\fIvhost\fP the virtual host to add the regular http server\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_remove_virtual_host()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket* evhttp_bind_listener (struct evhttp * http, struct evconnlistener * listener)" + +.PP +The most low-level evhttp_bind/accept method: takes an evconnlistener, and returns an evhttp_bound_socket\&. The listener will be freed when the bound socket is freed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_bind_socket (struct evhttp * http, const char * address, ev_uint16_t port)" + +.PP +Binds an HTTP server on the specified address and port\&. Can be called multiple times to bind the same http server to multiple different ports\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP a pointer to an evhttp object +.br +\fIaddress\fP a string containing the IP address to listen(2) on +.br +\fIport\fP the port number to listen on +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_accept_socket()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_bound_socket* evhttp_bind_socket_with_handle (struct evhttp * http, const char * address, ev_uint16_t port)" + +.PP +Like \fBevhttp_bind_socket()\fP, but returns a handle for referencing the socket\&. The returned pointer is not valid after \fIhttp\fP is freed\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP a pointer to an evhttp object +.br +\fIaddress\fP a string containing the IP address to listen(2) on +.br +\fIport\fP the port number to listen on +.RE +.PP +\fBReturns:\fP +.RS 4 +Handle for the socket on success, NULL on failure\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_bind_socket()\fP, \fBevhttp_del_accept_socket()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL \fBevutil_socket_t\fP evhttp_bound_socket_get_fd (struct evhttp_bound_socket * bound_socket)" + +.PP +Get the raw file descriptor referenced by an evhttp_bound_socket\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbound_socket\fP a handle returned by evhttp_{bind,accept}_socket_with_handle +.RE +.PP +\fBReturns:\fP +.RS 4 +the file descriptor used by the bound socket +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_bind_socket_with_handle()\fP, \fBevhttp_accept_socket_with_handle()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_cancel_request (struct evhttp_request * req)" + +.PP +Cancels a pending HTTP request\&. Cancels an ongoing HTTP request\&. The callback associated with this request is not executed and the request object is freed\&. If the request is currently being processed, e\&.g\&. it is ongoing, the corresponding evhttp_connection object is going to get reset\&. +.PP +A request cannot be canceled if its callback has executed already\&. A request may be canceled reentrantly from its chunked callback\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP the evhttp_request to cancel; req becomes invalid after this call\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_clear_headers (struct evkeyvalq * headers)" + +.PP +Removes all headers from the header list\&. +.PP +\fBParameters:\fP +.RS 4 +\fIheaders\fP the evkeyvalq object from which to remove all headers +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_connection* evhttp_connection_base_bufferevent_new (struct \fBevent_base\fP * base, struct evdns_base * dnsbase, struct \fBbufferevent\fP * bev, const char * address, ev_uint16_t port)" + +.PP +Create and return a connection object that can be used to for making HTTP requests\&. The connection object tries to resolve address and establish the connection when it is given an http request object\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the \fBevent_base\fP to use for handling the connection +.br +\fIdnsbase\fP the dns_base to use for resolving host names; if not specified host name resolution will block\&. +.br +\fIbev\fP a bufferevent to use for connecting to the server; if NULL, a socket-based bufferevent will be created\&. This buffrevent will be freed when the connection closes\&. It must have no fd set on it\&. +.br +\fIaddress\fP the address to which to connect +.br +\fIport\fP the port to connect to +.RE +.PP +\fBReturns:\fP +.RS 4 +an evhttp_connection object that can be used for making requests +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_connection* evhttp_connection_base_new (struct \fBevent_base\fP * base, struct evdns_base * dnsbase, const char * address, ev_uint16_t port)" + +.PP +Create and return a connection object that can be used to for making HTTP requests\&. The connection object tries to resolve address and establish the connection when it is given an http request object\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the \fBevent_base\fP to use for handling the connection +.br +\fIdnsbase\fP the dns_base to use for resolving host names; if not specified host name resolution will block\&. +.br +\fIaddress\fP the address to which to connect +.br +\fIport\fP the port to connect to +.RE +.PP +\fBReturns:\fP +.RS 4 +an evhttp_connection object that can be used for making requests +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_connection_free_on_completion (struct evhttp_connection * evcon)" + +.PP +Disowns a given connection object\&. Can be used to tell libevent to free the connection object after the last request has completed or failed\&. +.SS "EVENT2_EXPORT_SYMBOL const struct sockaddr* evhttp_connection_get_addr (struct evhttp_connection * evcon)" + +.PP +Get the remote address associated with this connection\&. extracted from getpeername() OR from nameserver\&. +.PP +\fBReturns:\fP +.RS 4 +NULL if getpeername() return non success, or connection is not connected, otherwise it return pointer to struct sockaddr_storage +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_connection_get_peer (struct evhttp_connection * evcon, char ** address, ev_uint16_t * port)" + +.PP +Get the remote address and port associated with this connection\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_connection_set_closecb (struct evhttp_connection * evcon, void(*)(struct evhttp_connection *, void *), void *)" + +.PP +Set a callback for connection close\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_connection_set_flags (struct evhttp_connection * evcon, int flags)" + +.PP +Set connection flags\&. +.PP +\fBSee also:\fP +.RS 4 +EVHTTP_CON_* +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, otherwise non zero (for example if flag doesn't supported)\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_connection_set_initial_retry_tv (struct evhttp_connection * evcon, const struct timeval * tv)" + +.PP +Sets the delay before retrying requests on this connection\&. This is only used if evhttp_connection_set_retries is used to make the number of retries at least one\&. Each retry after the first is twice as long as the one before it\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_connection_set_timeout_tv (struct evhttp_connection * evcon, const struct timeval * tv)" + +.PP +Sets the timeout for events related to this connection\&. Takes a struct timeval\&. +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_decode_uri (const char * uri)" + +.PP +Helper function to sort of decode a URI-encoded string\&. Unlike evhttp_get_decoded_uri, it decodes all plus characters that appear \fIafter\fP the first question mark character, but no plusses that occur before\&. This is not a good way to decode URIs in whole or in part\&. +.PP +The returned string must be freed by the caller +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated; you probably want to use evhttp_get_decoded_uri instead\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIuri\fP an encoded URI +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated unencoded URI or NULL on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_del_accept_socket (struct evhttp * http, struct evhttp_bound_socket * bound_socket)" + +.PP +Makes an HTTP server stop accepting connections on the specified socket\&. This may be useful when a socket has been sent via file descriptor passing and is no longer needed by the current process\&. +.PP +If you created this bound socket with evhttp_bind_socket_with_handle or evhttp_accept_socket_with_handle, this function closes the fd you provided\&. If you created this bound socket with evhttp_bind_listener, this function frees the listener you provided\&. +.PP +\fIbound_socket\fP is an invalid pointer after this call returns\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP a pointer to an evhttp object +.br +\fIbound_socket\fP a handle returned by evhttp_{bind,accept}_socket_with_handle +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_bind_socket_with_handle()\fP, \fBevhttp_accept_socket_with_handle()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_encode_uri (const char * str)" + +.PP +Helper function to encode a string for inclusion in a URI\&. All characters are replaced by their hex-escaped (%22) equivalents, except for characters explicitly unreserved by RFC3986 -- that is, ASCII alphanumeric characters, hyphen, dot, underscore, and tilde\&. +.PP +The returned string must be freed by the caller\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstr\fP an unencoded string +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated URI-encoded string or NULL on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const char* evhttp_find_header (const struct evkeyvalq * headers, const char * key)" + +.PP +Finds the value belonging to a header\&. +.PP +\fBParameters:\fP +.RS 4 +\fIheaders\fP the evkeyvalq object in which to find the header +.br +\fIkey\fP the name of the header to find +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to the value for the header or NULL if the header could not be found\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_add_header()\fP, \fBevhttp_remove_header()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_foreach_bound_socket (struct evhttp * http, evhttp_bound_socket_foreach_fn * function, void * argument)" + +.PP +Applies the function specified in the first argument to all evhttp_bound_sockets associated with 'http'\&. The user must not attempt to free or remove any connections, sockets or listeners in the callback 'function'\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP pointer to an evhttp object +.br +\fIfunction\fP function to apply to every bound socket +.br +\fIargument\fP pointer value passed to function for every socket iterated +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_free (struct evhttp * http)" + +.PP +Free the previously created HTTP server\&. Works only if no requests are currently being served\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp server object to be freed +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_start()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_htmlescape (const char * html)" + +.PP +Escape HTML character entities in a string\&. Replaces <, >, ", ' and & with <, >, ", ' and & correspondingly\&. +.PP +The returned string needs to be freed by the caller\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhtml\fP an unescaped HTML string +.RE +.PP +\fBReturns:\fP +.RS 4 +an escaped HTML string or NULL on error +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_make_request (struct evhttp_connection * evcon, struct evhttp_request * req, enum \fBevhttp_cmd_type\fP type, const char * uri)" + +.PP +Make an HTTP request over the specified connection\&. The connection gets ownership of the request\&. On failure, the request object is no longer valid as it has been freed\&. +.PP +\fBParameters:\fP +.RS 4 +\fIevcon\fP the evhttp_connection object over which to send the request +.br +\fIreq\fP the previously created and configured request object +.br +\fItype\fP the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc\&. +.br +\fIuri\fP the URI associated with the request +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_cancel_request()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp* evhttp_new (struct \fBevent_base\fP * base)" + +.PP +Create a new HTTP server\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP (optional) the event base to receive the HTTP events +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to a newly initialized evhttp server structure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_free()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_parse_query (const char * uri, struct evkeyvalq * headers)" + +.PP +Helper function to parse out arguments in a query\&. Parsing a URI like +.PP +http://foo.com/?q=test&s=some+thing +.PP +will result in two entries in the key value queue\&. +.PP +The first entry is: key='q', value='test' The second entry is: key='s', value='some thing' +.PP +\fBDeprecated\fP +.RS 4 +This function is deprecated as of Libevent 2\&.0\&.9\&. Use evhttp_uri_parse and evhttp_parse_query_str instead\&. +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIuri\fP the request URI +.br +\fIheaders\fP the head of the evkeyval queue +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_parse_query_str (const char * uri, struct evkeyvalq * headers)" + +.PP +Helper function to parse out arguments from the query portion of an HTTP URI\&. Parsing a query string like +.PP +q=test&s=some+thing +.PP +will result in two entries in the key value queue\&. +.PP +The first entry is: key='q', value='test' The second entry is: key='s', value='some thing' +.PP +\fBParameters:\fP +.RS 4 +\fIquery_parse\fP the query portion of the URI +.br +\fIheaders\fP the head of the evkeyval queue +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_remove_header (struct evkeyvalq * headers, const char * key)" + +.PP +Removes a header from a list of existing headers\&. +.PP +\fBParameters:\fP +.RS 4 +\fIheaders\fP the evkeyvalq object from which to remove a header +.br +\fIkey\fP the name of the header to remove +.RE +.PP +\fBReturns:\fP +.RS 4 +0 if the header was removed, -1 otherwise\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_find_header()\fP, \fBevhttp_add_header()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_remove_server_alias (struct evhttp * http, const char * alias)" + +.PP +Remove a server alias from an http object\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp object +.br +\fIalias\fP the alias to remove +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_add_server_alias()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_remove_virtual_host (struct evhttp * http, struct evhttp * vhost)" + +.PP +Removes a virtual host from the http server\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp object from which to remove the virtual host +.br +\fIvhost\fP the virtual host to remove from the regular http server\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_add_virtual_host()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_free (struct evhttp_request * req)" + +.PP +Frees the request object and removes associated events\&. +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_connection* evhttp_request_get_connection (struct evhttp_request * req)" + +.PP +Returns the connection object associated with the request or NULL\&. The user needs to either free the request explicitly or call \fBevhttp_send_reply_end()\fP\&. +.SS "EVENT2_EXPORT_SYMBOL const char* evhttp_request_get_host (struct evhttp_request * req)" + +.PP +Returns the host associated with the request\&. If a client sends an absolute URI, the host part of that is preferred\&. Otherwise, the input headers are searched for a Host: header\&. NULL is returned if no absolute URI or Host: header is provided\&. +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_request* evhttp_request_new (void(*)(struct evhttp_request *, void *) cb, void * arg)" + +.PP +Creates a new request object that needs to be filled in with the request parameters\&. The callback is executed when the request completed or an error occurred\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_own (struct evhttp_request * req)" + +.PP +Takes ownership of the request object\&. Can be used in a request callback to keep onto the request until \fBevhttp_request_free()\fP is explicitly called by the user\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_set_chunked_cb (struct evhttp_request *, void(*)(struct evhttp_request *, void *) cb)" + +.PP +Enable delivery of chunks to requestor\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcb\fP will be called after every read of data with the same argument as the completion callback\&. Will never be called on an empty response\&. May drain the input buffer; it will be drained automatically on return\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_set_error_cb (struct evhttp_request *, void(*)(enum \fBevhttp_request_error\fP, void *))" + +.PP +Set a callback for errors\&. +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_request_error\fP for error types\&. +.RE +.PP +On error, both the error callback and the regular callback will be called, error callback is called before the regular callback\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_set_header_cb (struct evhttp_request *, int(*)(struct evhttp_request *, void *) cb)" + +.PP +Register callback for additional parsing of request headers\&. +.PP +\fBParameters:\fP +.RS 4 +\fIcb\fP will be called after receiving and parsing the full header\&. It allows analyzing the header and possibly closing the connection by returning a value < 0\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_request_set_on_complete_cb (struct evhttp_request * req, void(*)(struct evhttp_request *, void *) cb, void * cb_arg)" + +.PP +Set a callback to be called on request completion of evhttp_send_* function\&. The callback function will be called on the completion of the request after the output data has been written and before the evhttp_request object is destroyed\&. This can be useful for tracking resources associated with a request (ex: timing metrics)\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIcb\fP callback function that will be called on request completion +.br +\fIcb_arg\fP an additional context argument for the callback +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_error (struct evhttp_request * req, int error, const char * reason)" + +.PP +Send an HTML error message to the client\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIerror\fP the HTTP error code +.br +\fIreason\fP a brief explanation of the error\&. If this is NULL, we'll just use the standard meaning of the error code\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_reply (struct evhttp_request * req, int code, const char * reason, struct \fBevbuffer\fP * databuf)" + +.PP +Send an HTML reply to the client\&. The body of the reply consists of the data in databuf\&. After calling \fBevhttp_send_reply()\fP databuf will be empty, but the buffer is still owned by the caller and needs to be deallocated by the caller if necessary\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIcode\fP the HTTP response code to send +.br +\fIreason\fP a brief message to send with the response code +.br +\fIdatabuf\fP the body of the response +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_reply_chunk (struct evhttp_request * req, struct \fBevbuffer\fP * databuf)" + +.PP +Send another data chunk as part of an ongoing chunked reply\&. The reply chunk consists of the data in databuf\&. After calling \fBevhttp_send_reply_chunk()\fP databuf will be empty, but the buffer is still owned by the caller and needs to be deallocated by the caller if necessary\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIdatabuf\fP the data chunk to send as part of the reply\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_reply_chunk_with_cb (struct evhttp_request *, struct \fBevbuffer\fP *, void(*)(struct evhttp_connection *, void *) cb, void * arg)" + +.PP +Send another data chunk as part of an ongoing chunked reply\&. The reply chunk consists of the data in databuf\&. After calling \fBevhttp_send_reply_chunk()\fP databuf will be empty, but the buffer is still owned by the caller and needs to be deallocated by the caller if necessary\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIdatabuf\fP the data chunk to send as part of the reply\&. +.br +\fIcb\fP callback funcion +.br +\fIcall\fP back's argument\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_reply_end (struct evhttp_request * req)" + +.PP +Complete a chunked reply, freeing the request as appropriate\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_send_reply_start (struct evhttp_request * req, int code, const char * reason)" + +.PP +Initiate a reply that uses Transfer-Encoding chunked\&. This allows the caller to stream the reply back to the client and is useful when either not all of the reply data is immediately available or when sending very large replies\&. +.PP +The caller needs to supply data chunks with \fBevhttp_send_reply_chunk()\fP and complete the reply by calling \fBevhttp_send_reply_end()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIreq\fP a request object +.br +\fIcode\fP the HTTP response code to send +.br +\fIreason\fP a brief message to send with the response code +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_allowed_methods (struct evhttp * http, ev_uint16_t methods)" + +.PP +Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks\&. If not supported they will generate a '405 Method not allowed' response\&. +.PP +By default this includes the following methods: GET, POST, HEAD, PUT, DELETE +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the http server on which to set the methods +.br +\fImethods\fP bit mask constructed from evhttp_cmd_type values +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_bevcb (struct evhttp * http, struct \fBbufferevent\fP *(*)(struct \fBevent_base\fP *, void *) cb, void * arg)" + +.PP +Set a callback used to create new bufferevents for connections to a given evhttp object\&. You can use this to override the default bufferevent type -- for example, to make this evhttp object use SSL bufferevents rather than unencrypted ones\&. +.PP +New bufferevents must be allocated with no fd set on them\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp server object for which to set the callback +.br +\fIcb\fP the callback to invoke for incoming connections +.br +\fIarg\fP a context argument for the callback +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_set_cb (struct evhttp * http, const char * path, void(*)(struct evhttp_request *, void *) cb, void * cb_arg)" + +.PP +Set a callback for a specified URI\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the http sever on which to set the callback +.br +\fIpath\fP the path for which to invoke the callback +.br +\fIcb\fP the callback function that gets invoked on requesting path +.br +\fIcb_arg\fP an additional context argument for the callback +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 if the callback existed already, -2 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_default_content_type (struct evhttp * http, const char * content_type)" + +.PP +Set the value to use for the Content-Type header when none was provided\&. If the content type string is NULL, the Content-Type header will not be automatically added\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the http server on which to set the default content type +.br +\fIcontent_type\fP the value for the Content-Type header +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evhttp_set_flags (struct evhttp * http, int flags)" + +.PP +Set connection flags for HTTP server\&. +.PP +\fBSee also:\fP +.RS 4 +EVHTTP_SERVER_* +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, otherwise non zero (for example if flag doesn't supported)\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_gencb (struct evhttp * http, void(*)(struct evhttp_request *, void *) cb, void * arg)" + +.PP +Set a callback for all requests that are not caught by specific callbacks\&. Invokes the specified callback for all requests that do not match any of the previously specified request paths\&. This is catchall for requests not specifically configured with \fBevhttp_set_cb()\fP\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP the evhttp server object for which to set the callback +.br +\fIcb\fP the callback to invoke for any unmatched requests +.br +\fIarg\fP a context argument for the callback +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_max_body_size (struct evhttp * http, ev_ssize_t max_body_size)" + +.PP +XXX Document\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_max_headers_size (struct evhttp * http, ev_ssize_t max_headers_size)" + +.PP +XXX Document\&. +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_timeout (struct evhttp * http, int timeout_in_secs)" + +.PP +Set the timeout for an HTTP request\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP an evhttp object +.br +\fItimeout_in_secs\fP the timeout, in seconds +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_set_timeout_tv (struct evhttp * http, const struct timeval * tv)" + +.PP +Set the timeout for an HTTP request\&. +.PP +\fBParameters:\fP +.RS 4 +\fIhttp\fP an evhttp object +.br +\fItv\fP the timeout, or NULL +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_uri_free (struct evhttp_uri * uri)" + +.PP +Free all memory allocated for a parsed uri\&. Only use this for URIs generated by evhttp_uri_parse\&. +.PP +\fBParameters:\fP +.RS 4 +\fIuri\fP container with parsed data +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_uri_parse()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL const char* evhttp_uri_get_host (const struct evhttp_uri * uri)" + +.PP +Return the host part of an evhttp_uri, or NULL if it has no host set\&. The host may either be a regular hostname (conforming to the RFC 3986 'regname' production), or an IPv4 address, or the empty string, or a bracketed IPv6 address, or a bracketed 'IP-Future' address\&. +.PP +Note that having a NULL host means that the URI has no authority section, but having an empty-string host means that the URI has an authority section with no host part\&. For example, 'mailto:user@example\&.com' has a host of NULL, but 'file:///etc/motd' has a host of ''\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_get_port (const struct evhttp_uri * uri)" + +.PP +Return the port part of an evhttp_uri, or -1 if there is no port set\&. +.SS "EVENT2_EXPORT_SYMBOL const char* evhttp_uri_get_scheme (const struct evhttp_uri * uri)" + +.PP +Return the scheme of an evhttp_uri, or NULL if there is no scheme has been set and the evhttp_uri contains a Relative-Ref\&. +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_uri_join (struct evhttp_uri * uri, char * buf, size_t limit)" + +.PP +Join together the uri parts from parsed data to form a URI-Reference\&. Note that no escaping of reserved characters is done on the members of the evhttp_uri, so the generated string might not be a valid URI unless the members of evhttp_uri are themselves valid\&. +.PP +\fBParameters:\fP +.RS 4 +\fIuri\fP container with parsed data +.br +\fIbuf\fP destination buffer +.br +\fIlimit\fP destination buffer size +.RE +.PP +\fBReturns:\fP +.RS 4 +a joined uri as string or NULL on error +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_uri_parse()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct evhttp_uri* evhttp_uri_parse_with_flags (const char * source_uri, unsigned flags)" + +.PP +Helper function to parse a URI-Reference as specified by RFC3986\&. This function matches the URI-Reference production from RFC3986, which includes both URIs like +.PP +scheme://[[userinfo]@]foo\&.com[:port]]/[path][?query][#fragment] +.PP +and relative-refs like +.PP +[path][?query][#fragment] +.PP +Any optional elements portions not present in the original URI are left set to NULL in the resulting evhttp_uri\&. If no port is specified, the port is set to -1\&. +.PP +Note that no decoding is performed on percent-escaped characters in the string; if you want to parse them, use evhttp_uridecode or evhttp_parse_query_str as appropriate\&. +.PP +Note also that most URI schemes will have additional constraints that this function does not know about, and cannot check\&. For example, mailto://www\&.example\&.com/cgi-bin/fortune\&.pl is not a reasonable mailto url, http://www.example.com:99999/ is not a reasonable HTTP URL, and ftp:username@example.com is not a reasonable FTP URL\&. Nevertheless, all of these URLs conform to RFC3986, and this function accepts all of them as valid\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsource_uri\fP the request URI +.br +\fIflags\fP Zero or more EVHTTP_URI_* flags to affect the behavior of the parser\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +uri container to hold parsed data, or NULL if there is error +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevhttp_uri_free()\fP +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evhttp_uri_set_flags (struct evhttp_uri * uri, unsigned flags)" + +.PP +Changes the flags set on a given URI\&. See EVHTTP_URI_* for a list of flags\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_fragment (struct evhttp_uri * uri, const char * fragment)" + +.PP +Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL\&. The fragment should not include a leading '#'\&. Returns 0 on success, -1 if fragment is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_host (struct evhttp_uri * uri, const char * host)" + +.PP +Set the host of an evhttp_uri, or clear the host if host==NULL\&. Returns 0 on success, -1 if host is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_path (struct evhttp_uri * uri, const char * path)" + +.PP +Set the path of an evhttp_uri, or clear the path if path==NULL\&. Returns 0 on success, -1 if path is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_port (struct evhttp_uri * uri, int port)" + +.PP +Set the port of an evhttp_uri, or clear the port if port==-1\&. Returns 0 on success, -1 if port is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_query (struct evhttp_uri * uri, const char * query)" + +.PP +Set the query of an evhttp_uri, or clear the query if query==NULL\&. The query should not include a leading '?'\&. Returns 0 on success, -1 if query is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_scheme (struct evhttp_uri * uri, const char * scheme)" + +.PP +Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL\&. Returns 0 on success, -1 if scheme is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL int evhttp_uri_set_userinfo (struct evhttp_uri * uri, const char * userinfo)" + +.PP +Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL\&. Returns 0 on success, -1 if userinfo is not well-formed\&. +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_uridecode (const char * uri, int decode_plus, size_t * size_out)" + +.PP +Helper function to decode a URI-escaped string or HTTP parameter\&. If 'decode_plus' is 1, then we decode the string as an HTTP parameter value, and convert all plus ('+') characters to spaces\&. If 'decode_plus' is 0, we leave all plus characters unchanged\&. +.PP +The returned string must be freed by the caller\&. +.PP +\fBParameters:\fP +.RS 4 +\fIuri\fP a URI-encode encoded URI +.br +\fIdecode_plus\fP determines whether we convert '+' to space\&. +.br +\fIsize_out\fP if size_out is not NULL, *size_out is set to the size of the returned string +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated unencoded URI or NULL on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL char* evhttp_uriencode (const char * str, ev_ssize_t size, int space_to_plus)" + +.PP +As evhttp_encode_uri, but if 'size' is nonnegative, treat the string as being 'size' bytes long\&. This allows you to encode strings that may contain 0-valued bytes\&. +.PP +The returned string must be freed by the caller\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstr\fP an unencoded string +.br +\fIsize\fP the length of the string to encode, or -1 if the string is NUL-terminated +.br +\fIspace_to_plus\fP if true, space characters in 'str' are encoded as +, not %20\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocate URI-encoded string, or NULL on failure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/http_compat.h.3 b/static/netbsd/man3/http_compat.h.3 new file mode 100644 index 00000000..e5defa51 --- /dev/null +++ b/static/netbsd/man3/http_compat.h.3 @@ -0,0 +1,94 @@ +.TH "event2/http_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/http_compat.h \- Potentially non-threadsafe versions of the functions in \fBhttp\&.h\fP: provided only for backwards compatibility\&. + +.SH SYNOPSIS +.br +.PP +\fC#include \fP +.br +\fC#include \fP +.br + +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBevhttp_request_uri\fP \fBevhttp_request_get_uri\fP" +.br +.RI "\fIReturns the request URI\&. \fP" +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "struct evhttp_connection * \fBevhttp_connection_new\fP (const char *address, ev_uint16_t port)" +.br +.RI "\fIA connection object that can be used to for making HTTP requests\&. \fP" +.ti -1c +.RI "void \fBevhttp_connection_set_base\fP (struct evhttp_connection *evcon, struct \fBevent_base\fP *base)" +.br +.RI "\fIAssociates an event base with the connection - can only be called on a freshly created connection object that has not been used yet\&. \fP" +.ti -1c +.RI "struct evhttp * \fBevhttp_start\fP (const char *address, ev_uint16_t port)" +.br +.RI "\fIStart an HTTP server on the specified address and port\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Potentially non-threadsafe versions of the functions in \fBhttp\&.h\fP: provided only for backwards compatibility\&. + + +.SH "Function Documentation" +.PP +.SS "struct evhttp_connection* evhttp_connection_new (const char * address, ev_uint16_t port)" + +.PP +A connection object that can be used to for making HTTP requests\&. The connection object tries to establish the connection when it is given an http request object\&. +.PP +\fBDeprecated\fP +.RS 4 +It does not allow an event base to be specified +.RE +.PP + +.SS "void evhttp_connection_set_base (struct evhttp_connection * evcon, struct \fBevent_base\fP * base)" + +.PP +Associates an event base with the connection - can only be called on a freshly created connection object that has not been used yet\&. +.PP +\fBDeprecated\fP +.RS 4 +XXXX Why? +.RE +.PP + +.SS "struct evhttp* evhttp_start (const char * address, ev_uint16_t port)" + +.PP +Start an HTTP server on the specified address and port\&. +.PP +\fBDeprecated\fP +.RS 4 +It does not allow an event base to be specified +.RE +.PP +.PP +\fBParameters:\fP +.RS 4 +\fIaddress\fP the address to which the HTTP server should be bound +.br +\fIport\fP the port number on which the HTTP server should listen +.RE +.PP +\fBReturns:\fP +.RS 4 +an struct evhttp object +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/humanize_number.3 b/static/netbsd/man3/humanize_number.3 new file mode 100644 index 00000000..2d95fe5b --- /dev/null +++ b/static/netbsd/man3/humanize_number.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: humanize_number.3,v 1.13 2019/03/12 22:21:53 wiz Exp $ +.\" +.\" Copyright (c) 1999, 2002, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn and by Tomas Svensson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 11, 2019 +.Dt HUMANIZE_NUMBER 3 +.Os +.Sh NAME +.Nm dehumanize_number , +.Nm humanize_number +.Nd format a number into a human readable form and vice versa +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn dehumanize_number "const char *str" "int64_t *result" +.Ft int +.Fn humanize_number "char *buffer" "size_t len" "int64_t number" "const char *suffix" "int scale" "int flags" +.Sh DESCRIPTION +The +.Fn humanize_number +function formats the signed 64 bit quantity given in +.Fa number +into +.Fa buffer . +A space and then the +.Fa suffix +.Pq "if not null" +is appended to the end. +.Fa len +gives the size of the +.Fa buffer . +.Pp +If the formatted number (including +.Fa suffix ) +would be too long to fit into +.Fa buffer , +then repeatedly divide +.Fa number +by 1024 until it will fit. +In this case, prefix +.Fa suffix +with the appropriate SI designator. +.Pp +The prefixes are: +.Bl -column "Prefix" "Description" "Multiplier" -offset indent +.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" +.It k kilo 1024 +.It M mega 1048576 +.It G giga 1073741824 +.It T tera 1099511627776 +.It P peta 1125899906842624 +.It E exa 1152921504606846976 +.El +.Pp +.Fa len +must be at least 4 plus the length of +.Fa suffix , +in order to ensure a useful result is generated into +.Fa buffer . +To use a specific prefix, specify this as +.Fa scale +(Multiplier = 1024 ^ scale). +The +.Fa scale +must be at least 0 and no more than 6. +.Pp +Alternatively, one of the following special values may be given as +.Pa scale : +.Bl -tag -width Dv -offset indent +.It Dv HN_AUTOSCALE +Format the buffer using the lowest multiplier possible. +.It Dv HN_GETSCALE +Return the prefix index number (the number of times +.Fa number +must be divided to fit) instead of formatting it to the buffer. +That is, the +.Fa scale +that would have been used if +.Dv HN_AUTOSCALE +had been used. +.El +.Pp +The following flags may be passed in +.Pa flags : +.Bl -tag -width Dv -offset indent +.It Dv HN_DECIMAL +If the final numeric result is less than 10, +and is not the same as the original value (that is, it has been scaled) +display it using a decimal radix character, and one following digit. +.It Dv HN_NOSPACE +Do not put a space between +.Fa number +and the prefix. +.It Dv HN_B +Use 'B' (bytes) as prefix if the original result does not have a prefix. +.It Dv HN_DIVISOR_1000 +Divide +.Fa number +with 1000 instead of 1024. +That is, use decimal scaling instead of binary. +.El +.Pp +To generate the shortest meaningful value, +a buffer length +.Pq Fa len +that is 6 greater the length of the +.Fa suffix +along with +.Dv HN_AUTOSCALE +will ensure the highest meaningful scale is used. +Allow one extra byte for the sign if the number is negative, +and one less if the +.Dv HN_NOSPACE +flag is used. +.Pp +The +.Fn dehumanize_number +function parses the string representing an integral value given in +.Fa str +and stores the numerical value in the integer pointed to by +.Fa result . +The provided string may hold one of the suffixes, which will be interpreted +and used to scale up its accompanying numerical value. +.Sh RETURN VALUES +.Fn humanize_number +returns the number of characters stored in +.Fa buffer +(excluding the terminating NUL) upon success, or \-1 upon failure. +If +.Dv HN_GETSCALE +is specified, the prefix index number will be returned instead. +.Pp +.Fn dehumanize_number +returns 0 if the string was parsed correctly. +A \-1 is returned to indicate failure and an error code is stored in +.Va errno . +.Sh ERRORS +.Fn dehumanize_number +will fail and no number will be stored in +.Fa result +if: +.Bl -tag -width Er +.It Bq Er EINVAL +The string in +.Fa str +was empty or carried an unknown suffix. +.It Bq Er ERANGE +The string in +.Fa str +represented a number that does not fit in +.Fa result . +.El +.Sh SEE ALSO +.Xr strsuftoll 3 , +.Xr orders 7 , +.Xr humanize_number 9 +.Sh HISTORY +.Fn humanize_number +first appeared in +.Nx 2.0 . +.Pp +.Fn dehumanize_number +first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/hx509.3 b/static/netbsd/man3/hx509.3 new file mode 100644 index 00000000..84479195 --- /dev/null +++ b/static/netbsd/man3/hx509.3 @@ -0,0 +1,51 @@ +.\" $NetBSD: hx509.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509 \- hx509 library +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_context_init\fP (hx509_context *context)" +.br +.ti -1c +.RI "void \fBhx509_context_free\fP (hx509_context *context)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "void hx509_context_free (hx509_context * context)" +Free the context allocated by \fBhx509_context_init()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP context to be freed\&. +.RE +.PP + +.SS "int hx509_context_init (hx509_context * context)" +Creates a hx509 context that most functions in the library uses\&. The context is only allowed to be used by one thread at each moment\&. Free the context with \fBhx509_context_free()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Returns a pointer to new hx509 context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_bitstring_print.3 b/static/netbsd/man3/hx509_bitstring_print.3 new file mode 100644 index 00000000..fb3bde16 --- /dev/null +++ b/static/netbsd/man3/hx509_bitstring_print.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_bitstring_print.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_ca.3 b/static/netbsd/man3/hx509_ca.3 new file mode 100644 index 00000000..9f80734f --- /dev/null +++ b/static/netbsd/man3/hx509_ca.3 @@ -0,0 +1,575 @@ +.\" $NetBSD: hx509_ca.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_ca" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_ca \- hx509 CA functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_ca_tbs_init\fP (hx509_context context, hx509_ca_tbs *tbs)" +.br +.ti -1c +.RI "void \fBhx509_ca_tbs_free\fP (hx509_ca_tbs *tbs)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_notBefore\fP (hx509_context context, hx509_ca_tbs tbs, time_t t)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_notAfter\fP (hx509_context context, hx509_ca_tbs tbs, time_t t)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_notAfter_lifetime\fP (hx509_context context, hx509_ca_tbs tbs, time_t delta)" +.br +.ti -1c +.RI "const struct units * \fBhx509_ca_tbs_template_units\fP (void)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_template\fP (hx509_context context, hx509_ca_tbs tbs, int flags, hx509_cert cert)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_ca\fP (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_proxy\fP (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_domaincontroller\fP (hx509_context context, hx509_ca_tbs tbs)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_spki\fP (hx509_context context, hx509_ca_tbs tbs, const SubjectPublicKeyInfo *spki)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_serialnumber\fP (hx509_context context, hx509_ca_tbs tbs, const heim_integer *serialNumber)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_eku\fP (hx509_context context, hx509_ca_tbs tbs, const heim_oid *oid)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_crl_dp_uri\fP (hx509_context context, hx509_ca_tbs tbs, const char *uri, hx509_name issuername)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_otherName\fP (hx509_context context, hx509_ca_tbs tbs, const heim_oid *oid, const heim_octet_string *os)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_pkinit\fP (hx509_context context, hx509_ca_tbs tbs, const char *principal)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_ms_upn\fP (hx509_context context, hx509_ca_tbs tbs, const char *principal)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_jid\fP (hx509_context context, hx509_ca_tbs tbs, const char *jid)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_hostname\fP (hx509_context context, hx509_ca_tbs tbs, const char *dnsname)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_add_san_rfc822name\fP (hx509_context context, hx509_ca_tbs tbs, const char *rfc822Name)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_subject\fP (hx509_context context, hx509_ca_tbs tbs, hx509_name subject)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_unique\fP (hx509_context context, hx509_ca_tbs tbs, const heim_bit_string *subjectUniqueID, const heim_bit_string *issuerUniqueID)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_subject_expand\fP (hx509_context context, hx509_ca_tbs tbs, hx509_env env)" +.br +.ti -1c +.RI "int \fBhx509_ca_tbs_set_signature_algorithm\fP (hx509_context context, hx509_ca_tbs tbs, const AlgorithmIdentifier *sigalg)" +.br +.ti -1c +.RI "int \fBhx509_ca_sign\fP (hx509_context context, hx509_ca_tbs tbs, hx509_cert signer, hx509_cert *certificate)" +.br +.ti -1c +.RI "int \fBhx509_ca_sign_self\fP (hx509_context context, hx509_ca_tbs tbs, hx509_private_key signer, hx509_cert *certificate)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBHx509 CA functions\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_ca_sign (hx509_context context, hx509_ca_tbs tbs, hx509_cert signer, hx509_cert * certificate)" +Sign a to-be-signed certificate object with a issuer certificate\&. +.PP +The caller needs to at least have called the following functions on the to-be-signed certificate object: +.IP "\(bu" 2 +\fBhx509_ca_tbs_init()\fP +.IP "\(bu" 2 +\fBhx509_ca_tbs_set_subject()\fP +.IP "\(bu" 2 +\fBhx509_ca_tbs_set_spki()\fP +.PP +.PP +When done the to-be-signed certificate object should be freed with \fBhx509_ca_tbs_free()\fP\&. +.PP +When creating self-signed certificate use \fBhx509_ca_sign_self()\fP instead\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIsigner\fP the CA certificate object to sign with (need private key)\&. +.br +\fIcertificate\fP return cerificate, free with \fBhx509_cert_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_sign_self (hx509_context context, hx509_ca_tbs tbs, hx509_private_key signer, hx509_cert * certificate)" +Work just like \fBhx509_ca_sign()\fP but signs it-self\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIsigner\fP private key to sign with\&. +.br +\fIcertificate\fP return cerificate, free with \fBhx509_cert_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_crl_dp_uri (hx509_context context, hx509_ca_tbs tbs, const char * uri, hx509_name issuername)" +Add CRL distribution point URI to the to-be-signed certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIuri\fP uri to the CRL\&. +.br +\fIissuername\fP name of the issuer\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP +issuername not supported +.SS "int hx509_ca_tbs_add_eku (hx509_context context, hx509_ca_tbs tbs, const heim_oid * oid)" +An an extended key usage to the to-be-signed certificate object\&. Duplicates will detected and not added\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIoid\fP extended key usage to add\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_hostname (hx509_context context, hx509_ca_tbs tbs, const char * dnsname)" +Add a Subject Alternative Name hostname to to-be-signed certificate object\&. A domain match starts with \&., an exact match does not\&. +.PP +Example of a an domain match: \&.domain\&.se matches the hostname host\&.domain\&.se\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIdnsname\fP a hostame\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_jid (hx509_context context, hx509_ca_tbs tbs, const char * jid)" +Add a Jabber/XMPP jid Subject Alternative Name to the to-be-signed certificate object\&. The jid is an UTF8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIjid\fP string of an a jabber id in UTF8\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_ms_upn (hx509_context context, hx509_ca_tbs tbs, const char * principal)" +Add Microsoft UPN Subject Alternative Name to the to-be-signed certificate object\&. The principal string is a UTF8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIprincipal\fP Microsoft UPN string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_otherName (hx509_context context, hx509_ca_tbs tbs, const heim_oid * oid, const heim_octet_string * os)" +Add Subject Alternative Name otherName to the to-be-signed certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIoid\fP the oid of the OtherName\&. +.br +\fIos\fP data in the other name\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_pkinit (hx509_context context, hx509_ca_tbs tbs, const char * principal)" +Add Kerberos Subject Alternative Name to the to-be-signed certificate object\&. The principal string is a UTF8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIprincipal\fP Kerberos principal to add to the certificate\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_add_san_rfc822name (hx509_context context, hx509_ca_tbs tbs, const char * rfc822Name)" +Add a Subject Alternative Name rfc822 (email address) to to-be-signed certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIrfc822Name\fP a string to a email address\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_ca_tbs_free (hx509_ca_tbs * tbs)" +Free an To Be Signed object\&. +.PP +\fBParameters\fP +.RS 4 +\fItbs\fP object to free\&. +.RE +.PP + +.SS "int hx509_ca_tbs_init (hx509_context context, hx509_ca_tbs * tbs)" +Allocate an to-be-signed certificate object that will be converted into an certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP returned to-be-signed certicate object, free with \fBhx509_ca_tbs_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_ca (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)" +Make the to-be-signed certificate object a CA certificate\&. If the pathLenConstraint is negative path length constraint is used\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIpathLenConstraint\fP path length constraint, negative, no constraint\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_domaincontroller (hx509_context context, hx509_ca_tbs tbs)" +Make the to-be-signed certificate object a windows domain controller certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_notAfter (hx509_context context, hx509_ca_tbs tbs, time_t t)" +Set the absolute time when the certificate is valid to\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIt\fP time when the certificate will expire +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_notAfter_lifetime (hx509_context context, hx509_ca_tbs tbs, time_t delta)" +Set the relative time when the certificiate is going to expire\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIdelta\fP seconds to the certificate is going to expire\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_notBefore (hx509_context context, hx509_ca_tbs tbs, time_t t)" +Set the absolute time when the certificate is valid from\&. If not set the current time will be used\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIt\fP time the certificated will start to be valid +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_proxy (hx509_context context, hx509_ca_tbs tbs, int pathLenConstraint)" +Make the to-be-signed certificate object a proxy certificate\&. If the pathLenConstraint is negative path length constraint is used\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIpathLenConstraint\fP path length constraint, negative, no constraint\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_serialnumber (hx509_context context, hx509_ca_tbs tbs, const heim_integer * serialNumber)" +Set the serial number to use for to-be-signed certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIserialNumber\fP serial number to use for the to-be-signed certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_signature_algorithm (hx509_context context, hx509_ca_tbs tbs, const AlgorithmIdentifier * sigalg)" +Set signature algorithm on the to be signed certificate +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIsigalg\fP signature algorithm to use +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_spki (hx509_context context, hx509_ca_tbs tbs, const SubjectPublicKeyInfo * spki)" +Set the subject public key info (SPKI) in the to-be-signed certificate object\&. SPKI is the public key and key related parameters in the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIspki\fP subject public key info to use for the to-be-signed certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_subject (hx509_context context, hx509_ca_tbs tbs, hx509_name subject)" +Set the subject name of a to-be-signed certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIsubject\fP the name to set a subject\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_template (hx509_context context, hx509_ca_tbs tbs, int flags, hx509_cert cert)" +Initialize the to-be-signed certificate object from a template certifiate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIflags\fP bit field selecting what to copy from the template certifiate\&. +.br +\fIcert\fP template certificate\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_set_unique (hx509_context context, hx509_ca_tbs tbs, const heim_bit_string * subjectUniqueID, const heim_bit_string * issuerUniqueID)" +Set the issuerUniqueID and subjectUniqueID +.PP +These are only supposed to be used considered with version 2 certificates, replaced by the two extensions SubjectKeyIdentifier and IssuerKeyIdentifier\&. This function is to allow application using legacy protocol to issue them\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIissuerUniqueID\fP to be set +.br +\fIsubjectUniqueID\fP to be set +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ca_tbs_subject_expand (hx509_context context, hx509_ca_tbs tbs, hx509_env env)" +Expand the the subject name in the to-be-signed certificate object using \fBhx509_name_expand()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fItbs\fP object to be signed\&. +.br +\fIenv\fP environment variable to expand variables in the subject name, see hx509_env_init()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "const struct units* hx509_ca_tbs_template_units (void)" +Make of template units, use to build flags argument to \fBhx509_ca_tbs_set_template()\fP with parse_units()\&. +.PP +\fBReturns\fP +.RS 4 +an units structure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_ca_sign.3 b/static/netbsd/man3/hx509_ca_sign.3 new file mode 100644 index 00000000..bf2bfc04 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_sign.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_sign.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_sign_self.3 b/static/netbsd/man3/hx509_ca_sign_self.3 new file mode 100644 index 00000000..c0b42131 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_sign_self.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_sign_self.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_crl_dp_uri.3 b/static/netbsd/man3/hx509_ca_tbs_add_crl_dp_uri.3 new file mode 100644 index 00000000..fb55bd24 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_crl_dp_uri.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_crl_dp_uri.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_eku.3 b/static/netbsd/man3/hx509_ca_tbs_add_eku.3 new file mode 100644 index 00000000..955828c3 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_eku.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_eku.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_hostname.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_hostname.3 new file mode 100644 index 00000000..9a744463 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_hostname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_hostname.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_jid.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_jid.3 new file mode 100644 index 00000000..c45ceb60 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_jid.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_jid.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_ms_upn.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_ms_upn.3 new file mode 100644 index 00000000..c27d3ba6 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_ms_upn.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_ms_upn.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_otherName.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_otherName.3 new file mode 100644 index 00000000..1d0e4dcb --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_otherName.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_otherName.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_pkinit.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_pkinit.3 new file mode 100644 index 00000000..7a98a178 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_pkinit.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_pkinit.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_add_san_rfc822name.3 b/static/netbsd/man3/hx509_ca_tbs_add_san_rfc822name.3 new file mode 100644 index 00000000..77aaeedc --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_add_san_rfc822name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_add_san_rfc822name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_free.3 b/static/netbsd/man3/hx509_ca_tbs_free.3 new file mode 100644 index 00000000..1288fe5b --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_init.3 b/static/netbsd/man3/hx509_ca_tbs_init.3 new file mode 100644 index 00000000..4e154dfa --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_ca.3 b/static/netbsd/man3/hx509_ca_tbs_set_ca.3 new file mode 100644 index 00000000..c9fd806a --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_ca.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_ca.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_domaincontroller.3 b/static/netbsd/man3/hx509_ca_tbs_set_domaincontroller.3 new file mode 100644 index 00000000..21941543 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_domaincontroller.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_domaincontroller.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_notAfter.3 b/static/netbsd/man3/hx509_ca_tbs_set_notAfter.3 new file mode 100644 index 00000000..745ce715 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_notAfter.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_notAfter.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_notAfter_lifetime.3 b/static/netbsd/man3/hx509_ca_tbs_set_notAfter_lifetime.3 new file mode 100644 index 00000000..02addda7 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_notAfter_lifetime.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_notAfter_lifetime.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_notBefore.3 b/static/netbsd/man3/hx509_ca_tbs_set_notBefore.3 new file mode 100644 index 00000000..83106701 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_notBefore.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_notBefore.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_proxy.3 b/static/netbsd/man3/hx509_ca_tbs_set_proxy.3 new file mode 100644 index 00000000..32b759ec --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_proxy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_proxy.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_serialnumber.3 b/static/netbsd/man3/hx509_ca_tbs_set_serialnumber.3 new file mode 100644 index 00000000..a220ec33 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_serialnumber.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_serialnumber.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_signature_algorithm.3 b/static/netbsd/man3/hx509_ca_tbs_set_signature_algorithm.3 new file mode 100644 index 00000000..bdf9b8a9 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_signature_algorithm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_signature_algorithm.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_spki.3 b/static/netbsd/man3/hx509_ca_tbs_set_spki.3 new file mode 100644 index 00000000..3b264c15 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_spki.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_spki.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_subject.3 b/static/netbsd/man3/hx509_ca_tbs_set_subject.3 new file mode 100644 index 00000000..3b6bc452 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_subject.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_subject.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_template.3 b/static/netbsd/man3/hx509_ca_tbs_set_template.3 new file mode 100644 index 00000000..bf562ea2 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_template.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_template.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_set_unique.3 b/static/netbsd/man3/hx509_ca_tbs_set_unique.3 new file mode 100644 index 00000000..f10081b8 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_set_unique.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_set_unique.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_subject_expand.3 b/static/netbsd/man3/hx509_ca_tbs_subject_expand.3 new file mode 100644 index 00000000..566e9f68 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_subject_expand.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_subject_expand.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_ca_tbs_template_units.3 b/static/netbsd/man3/hx509_ca_tbs_template_units.3 new file mode 100644 index 00000000..01e9a8a8 --- /dev/null +++ b/static/netbsd/man3/hx509_ca_tbs_template_units.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ca_tbs_template_units.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_ca.3 diff --git a/static/netbsd/man3/hx509_cert.3 b/static/netbsd/man3/hx509_cert.3 new file mode 100644 index 00000000..90006d8d --- /dev/null +++ b/static/netbsd/man3/hx509_cert.3 @@ -0,0 +1,675 @@ +.\" $NetBSD: hx509_cert.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_cert" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_cert \- hx509 certificate functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "hx509_cert \fBhx509_cert_init\fP (hx509_context context, const Certificate *c, heim_error_t *error)" +.br +.ti -1c +.RI "hx509_cert \fBhx509_cert_init_data\fP (hx509_context context, const void *ptr, size_t len, heim_error_t *error)" +.br +.ti -1c +.RI "void \fBhx509_cert_free\fP (hx509_cert cert)" +.br +.ti -1c +.RI "hx509_cert \fBhx509_cert_ref\fP (hx509_cert cert)" +.br +.ti -1c +.RI "void \fBhx509_verify_ctx_f_allow_default_trustanchors\fP (hx509_verify_ctx ctx, int boolean)" +.br +.ti -1c +.RI "int \fBhx509_cert_find_subjectAltName_otherName\fP (hx509_context context, hx509_cert cert, const heim_oid *oid, hx509_octet_string_list *list)" +.br +.ti -1c +.RI "int \fBhx509_cert_cmp\fP (hx509_cert p, hx509_cert q)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_issuer\fP (hx509_cert p, hx509_name *name)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_subject\fP (hx509_cert p, hx509_name *name)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_base_subject\fP (hx509_context context, hx509_cert c, hx509_name *name)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_serialnumber\fP (hx509_cert p, heim_integer *i)" +.br +.ti -1c +.RI "time_t \fBhx509_cert_get_notBefore\fP (hx509_cert p)" +.br +.ti -1c +.RI "time_t \fBhx509_cert_get_notAfter\fP (hx509_cert p)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_SPKI\fP (hx509_context context, hx509_cert p, SubjectPublicKeyInfo *spki)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_SPKI_AlgorithmIdentifier\fP (hx509_context context, hx509_cert p, AlgorithmIdentifier *alg)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_issuer_unique_id\fP (hx509_context context, hx509_cert p, heim_bit_string *issuer)" +.br +.ti -1c +.RI "int \fBhx509_cert_get_subject_unique_id\fP (hx509_context context, hx509_cert p, heim_bit_string *subject)" +.br +.ti -1c +.RI "int \fBhx509_verify_hostname\fP (hx509_context context, const hx509_cert cert, int flags, hx509_hostname_type type, const char *hostname, const struct sockaddr *sa, int sa_size)" +.br +.ti -1c +.RI "hx509_cert_attribute \fBhx509_cert_get_attribute\fP (hx509_cert cert, const heim_oid *oid)" +.br +.ti -1c +.RI "int \fBhx509_cert_set_friendly_name\fP (hx509_cert cert, const char *name)" +.br +.ti -1c +.RI "const char * \fBhx509_cert_get_friendly_name\fP (hx509_cert cert)" +.br +.ti -1c +.RI "int \fBhx509_query_alloc\fP (hx509_context context, hx509_query **q)" +.br +.ti -1c +.RI "void \fBhx509_query_match_option\fP (hx509_query *q, hx509_query_option option)" +.br +.ti -1c +.RI "int \fBhx509_query_match_issuer_serial\fP (hx509_query *q, const Name *issuer, const heim_integer *serialNumber)" +.br +.ti -1c +.RI "int \fBhx509_query_match_friendly_name\fP (hx509_query *q, const char *name)" +.br +.ti -1c +.RI "int \fBhx509_query_match_eku\fP (hx509_query *q, const heim_oid *eku)" +.br +.ti -1c +.RI "int \fBhx509_query_match_cmp_func\fP (hx509_query *q, int(*func)(hx509_context, hx509_cert, void *), void *ctx)" +.br +.ti -1c +.RI "void \fBhx509_query_free\fP (hx509_context context, hx509_query *q)" +.br +.ti -1c +.RI "void \fBhx509_query_statistic_file\fP (hx509_context context, const char *fn)" +.br +.ti -1c +.RI "void \fBhx509_query_unparse_stats\fP (hx509_context context, int printtype, FILE *out)" +.br +.ti -1c +.RI "int \fBhx509_cert_check_eku\fP (hx509_context context, hx509_cert cert, const heim_oid *eku, int allow_any_eku)" +.br +.ti -1c +.RI "int \fBhx509_cert_binary\fP (hx509_context context, hx509_cert c, heim_octet_string *os)" +.br +.ti -1c +.RI "int \fBhx509_print_cert\fP (hx509_context context, hx509_cert cert, FILE *out)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBThe basic certificate\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_cert_binary (hx509_context context, hx509_cert c, heim_octet_string * os)" +Encodes the hx509 certificate as a DER encode binary\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIc\fP the certificate to encode\&. +.br +\fIos\fP the encode certificate, set to NULL, 0 on case of error\&. Free the os->data with \fBhx509_xfree()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_check_eku (hx509_context context, hx509_cert cert, const heim_oid * eku, int allow_any_eku)" +Check the extended key usage on the hx509 certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIcert\fP A hx509 context\&. +.br +\fIeku\fP the EKU to check for +.br +\fIallow_any_eku\fP if the any EKU is set, allow that to be a substitute\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_cmp (hx509_cert p, hx509_cert q)" +Compare to hx509 certificate object, useful for sorting\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.br +\fIq\fP a hx509 certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 the objects are the same, returns > 0 is p is 'larger' then q, < 0 if p is 'smaller' then q\&. +.RE +.PP + +.SS "int hx509_cert_find_subjectAltName_otherName (hx509_context context, hx509_cert cert, const heim_oid * oid, hx509_octet_string_list * list)" +Return a list of subjectAltNames specified by oid in the certificate\&. On error the +.PP +The returned list of octet string should be freed with \fBhx509_free_octet_string_list()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIcert\fP a hx509 certificate object\&. +.br +\fIoid\fP an oid to for SubjectAltName\&. +.br +\fIlist\fP list of matching SubjectAltName\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_cert_free (hx509_cert cert)" +Free reference to the hx509 certificate object, if the refcounter reaches 0, the object if freed\&. Its allowed to pass in NULL\&. +.PP +\fBParameters\fP +.RS 4 +\fIcert\fP the cert to free\&. +.RE +.PP + +.SS "hx509_cert_attribute hx509_cert_get_attribute (hx509_cert cert, const heim_oid * oid)" +Get an external attribute for the certificate, examples are friendly name and id\&. +.PP +\fBParameters\fP +.RS 4 +\fIcert\fP hx509 certificate object to search +.br +\fIoid\fP an oid to search for\&. +.RE +.PP +\fBReturns\fP +.RS 4 +an hx509_cert_attribute, only valid as long as the certificate is referenced\&. +.RE +.PP + +.SS "int hx509_cert_get_base_subject (hx509_context context, hx509_cert c, hx509_name * name)" +Return the name of the base subject of the hx509 certificate\&. If the certiicate is a verified proxy certificate, the this function return the base certificate (root of the proxy chain)\&. If the proxy certificate is not verified with the base certificate HX509_PROXY_CERTIFICATE_NOT_CANONICALIZED is returned\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIc\fP a hx509 certificate object\&. +.br +\fIname\fP a pointer to a hx509 name, should be freed by \fBhx509_name_free()\fP\&. See also \fBhx509_cert_get_subject()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "const char* hx509_cert_get_friendly_name (hx509_cert cert)" +Get friendly name of the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcert\fP cert to get the friendly name from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +an friendly name or NULL if there is\&. The friendly name is only valid as long as the certificate is referenced\&. +.RE +.PP + +.SS "int hx509_cert_get_issuer (hx509_cert p, hx509_name * name)" +Return the name of the issuer of the hx509 certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.br +\fIname\fP a pointer to a hx509 name, should be freed by \fBhx509_name_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_get_issuer_unique_id (hx509_context context, hx509_cert p, heim_bit_string * issuer)" +Get a copy of the Issuer Unique ID +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509_context +.br +\fIp\fP a hx509 certificate +.br +\fIissuer\fP the issuer id returned, free with der_free_bit_string() +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. The error code HX509_EXTENSION_NOT_FOUND is returned if the certificate doesn't have a issuerUniqueID +.RE +.PP + +.SS "time_t hx509_cert_get_notAfter (hx509_cert p)" +Get notAfter time of the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +return not after time\&. +.RE +.PP + +.SS "time_t hx509_cert_get_notBefore (hx509_cert p)" +Get notBefore time of the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +return not before time +.RE +.PP + +.SS "int hx509_cert_get_serialnumber (hx509_cert p, heim_integer * i)" +Get serial number of the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.br +\fIi\fP serial number, should be freed ith der_free_heim_integer()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_get_SPKI (hx509_context context, hx509_cert p, SubjectPublicKeyInfo * spki)" +Get the SubjectPublicKeyInfo structure from the hx509 certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIp\fP a hx509 certificate object\&. +.br +\fIspki\fP SubjectPublicKeyInfo, should be freed with free_SubjectPublicKeyInfo()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_get_SPKI_AlgorithmIdentifier (hx509_context context, hx509_cert p, AlgorithmIdentifier * alg)" +Get the AlgorithmIdentifier from the hx509 certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIp\fP a hx509 certificate object\&. +.br +\fIalg\fP AlgorithmIdentifier, should be freed with free_AlgorithmIdentifier()\&. The algorithmidentifier is typicly rsaEncryption, or id-ecPublicKey, or some other public key mechanism\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_get_subject (hx509_cert p, hx509_name * name)" +Return the name of the subject of the hx509 certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP a hx509 certificate object\&. +.br +\fIname\fP a pointer to a hx509 name, should be freed by \fBhx509_name_free()\fP\&. See also \fBhx509_cert_get_base_subject()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_cert_get_subject_unique_id (hx509_context context, hx509_cert p, heim_bit_string * subject)" +Get a copy of the Subect Unique ID +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509_context +.br +\fIp\fP a hx509 certificate +.br +\fIsubject\fP the subject id returned, free with der_free_bit_string() +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. The error code HX509_EXTENSION_NOT_FOUND is returned if the certificate doesn't have a subjectUniqueID +.RE +.PP + +.SS "hx509_cert hx509_cert_init (hx509_context context, const Certificate * c, heim_error_t * error)" +Allocate and init an hx509 certificate object from the decoded certificate `c´\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIc\fP +.br +\fIerror\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 certificate +.RE +.PP + +.SS "hx509_cert hx509_cert_init_data (hx509_context context, const void * ptr, size_t len, heim_error_t * error)" +Just like \fBhx509_cert_init()\fP, but instead of a decode certificate takes an pointer and length to a memory region that contains a DER/BER encoded certificate\&. +.PP +If the memory region doesn't contain just the certificate and nothing more the function will fail with HX509_EXTRA_DATA_AFTER_STRUCTURE\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIptr\fP pointer to memory region containing encoded certificate\&. +.br +\fIlen\fP length of memory region\&. +.br +\fIerror\fP possibly returns an error +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 certificate +.RE +.PP + +.SS "hx509_cert hx509_cert_ref (hx509_cert cert)" +Add a reference to a hx509 certificate object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcert\fP a pointer to an hx509 certificate object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the same object as is passed in\&. +.RE +.PP + +.SS "int hx509_cert_set_friendly_name (hx509_cert cert, const char * name)" +Set the friendly name on the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcert\fP The certificate to set the friendly name on +.br +\fIname\fP Friendly name\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_print_cert (hx509_context context, hx509_cert cert, FILE * out)" +Print a simple representation of a certificate +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context, can be NULL +.br +\fIcert\fP certificate to print +.br +\fIout\fP the stdio output stream, if NULL, stdout is used +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code +.RE +.PP + +.SS "int hx509_query_alloc (hx509_context context, hx509_query ** q)" +Allocate an query controller\&. Free using \fBhx509_query_free()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIq\fP return pointer to a hx509_query\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_query_free (hx509_context context, hx509_query * q)" +Free the query controller\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIq\fP a pointer to the query controller\&. +.RE +.PP + +.SS "int hx509_query_match_cmp_func (hx509_query * q, int(*)(hx509_context, hx509_cert, void *) func, void * ctx)" +Set the query controller to match using a specific match function\&. +.PP +\fBParameters\fP +.RS 4 +\fIq\fP a hx509 query controller\&. +.br +\fIfunc\fP function to use for matching, if the argument is NULL, the match function is removed\&. +.br +\fIctx\fP context passed to the function\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_query_match_eku (hx509_query * q, const heim_oid * eku)" +Set the query controller to require an one specific EKU (extended key usage)\&. Any previous EKU matching is overwitten\&. If NULL is passed in as the eku, the EKU requirement is reset\&. +.PP +\fBParameters\fP +.RS 4 +\fIq\fP a hx509 query controller\&. +.br +\fIeku\fP an EKU to match on\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_query_match_friendly_name (hx509_query * q, const char * name)" +Set the query controller to match on a friendly name +.PP +\fBParameters\fP +.RS 4 +\fIq\fP a hx509 query controller\&. +.br +\fIname\fP a friendly name to match on +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_query_match_issuer_serial (hx509_query * q, const Name * issuer, const heim_integer * serialNumber)" +Set the issuer and serial number of match in the query controller\&. The function make copies of the isser and serial number\&. +.PP +\fBParameters\fP +.RS 4 +\fIq\fP a hx509 query controller +.br +\fIissuer\fP issuer to search for +.br +\fIserialNumber\fP the serialNumber of the issuer\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_query_match_option (hx509_query * q, hx509_query_option option)" +Set match options for the hx509 query controller\&. +.PP +\fBParameters\fP +.RS 4 +\fIq\fP query controller\&. +.br +\fIoption\fP options to control the query controller\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_query_statistic_file (hx509_context context, const char * fn)" +Set a statistic file for the query statistics\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIfn\fP statistics file name +.RE +.PP + +.SS "void hx509_query_unparse_stats (hx509_context context, int printtype, FILE * out)" +Unparse the statistics file and print the result on a FILE descriptor\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIprinttype\fP tyep to print +.br +\fIout\fP the FILE to write the data on\&. +.RE +.PP + +.SS "void hx509_verify_ctx_f_allow_default_trustanchors (hx509_verify_ctx ctx, int boolean)" +Allow using the operating system builtin trust anchors if no other trust anchors are configured\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context +.br +\fIboolean\fP if non zero, useing the operating systems builtin trust anchors\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_verify_hostname (hx509_context context, const hx509_cert cert, int flags, hx509_hostname_type type, const char * hostname, const struct sockaddr * sa, int sa_size)" +Verify that the certificate is allowed to be used for the hostname and address\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIcert\fP the certificate to match with +.br +\fIflags\fP Flags to modify the behavior: +.IP "\(bu" 2 +HX509_VHN_F_ALLOW_NO_MATCH no match is ok +.PP +.br +\fItype\fP type of hostname: +.IP "\(bu" 2 +HX509_HN_HOSTNAME for plain hostname\&. +.IP "\(bu" 2 +HX509_HN_DNSSRV for DNS SRV names\&. +.PP +.br +\fIhostname\fP the hostname to check +.br +\fIsa\fP address of the host +.br +\fIsa_size\fP length of address +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_cert_binary.3 b/static/netbsd/man3/hx509_cert_binary.3 new file mode 100644 index 00000000..484c822d --- /dev/null +++ b/static/netbsd/man3/hx509_cert_binary.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_binary.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_check_eku.3 b/static/netbsd/man3/hx509_cert_check_eku.3 new file mode 100644 index 00000000..8bd6d8da --- /dev/null +++ b/static/netbsd/man3/hx509_cert_check_eku.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_check_eku.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_cmp.3 b/static/netbsd/man3/hx509_cert_cmp.3 new file mode 100644 index 00000000..096a21cd --- /dev/null +++ b/static/netbsd/man3/hx509_cert_cmp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_cmp.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_find_subjectAltName_otherName.3 b/static/netbsd/man3/hx509_cert_find_subjectAltName_otherName.3 new file mode 100644 index 00000000..54dceb93 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_find_subjectAltName_otherName.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_find_subjectAltName_otherName.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_free.3 b/static/netbsd/man3/hx509_cert_free.3 new file mode 100644 index 00000000..d59ed0d4 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_SPKI.3 b/static/netbsd/man3/hx509_cert_get_SPKI.3 new file mode 100644 index 00000000..b89c5b0a --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_SPKI.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_SPKI.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_SPKI_AlgorithmIdentifier.3 b/static/netbsd/man3/hx509_cert_get_SPKI_AlgorithmIdentifier.3 new file mode 100644 index 00000000..7047b97b --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_SPKI_AlgorithmIdentifier.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_SPKI_AlgorithmIdentifier.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_attribute.3 b/static/netbsd/man3/hx509_cert_get_attribute.3 new file mode 100644 index 00000000..8c9e30db --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_attribute.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_attribute.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_base_subject.3 b/static/netbsd/man3/hx509_cert_get_base_subject.3 new file mode 100644 index 00000000..9370fccb --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_base_subject.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_base_subject.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_friendly_name.3 b/static/netbsd/man3/hx509_cert_get_friendly_name.3 new file mode 100644 index 00000000..fe29803e --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_friendly_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_friendly_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_issuer.3 b/static/netbsd/man3/hx509_cert_get_issuer.3 new file mode 100644 index 00000000..d485c955 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_issuer.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_issuer.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_issuer_unique_id.3 b/static/netbsd/man3/hx509_cert_get_issuer_unique_id.3 new file mode 100644 index 00000000..ce8cc559 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_issuer_unique_id.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_issuer_unique_id.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_notAfter.3 b/static/netbsd/man3/hx509_cert_get_notAfter.3 new file mode 100644 index 00000000..047c745f --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_notAfter.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_notAfter.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_notBefore.3 b/static/netbsd/man3/hx509_cert_get_notBefore.3 new file mode 100644 index 00000000..112ae84c --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_notBefore.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_notBefore.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_serialnumber.3 b/static/netbsd/man3/hx509_cert_get_serialnumber.3 new file mode 100644 index 00000000..1fb722f8 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_serialnumber.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_serialnumber.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_subject.3 b/static/netbsd/man3/hx509_cert_get_subject.3 new file mode 100644 index 00000000..d3ce2247 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_subject.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_subject.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_get_subject_unique_id.3 b/static/netbsd/man3/hx509_cert_get_subject_unique_id.3 new file mode 100644 index 00000000..6a2c7187 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_get_subject_unique_id.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_get_subject_unique_id.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_init.3 b/static/netbsd/man3/hx509_cert_init.3 new file mode 100644 index 00000000..149b8568 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_init_data.3 b/static/netbsd/man3/hx509_cert_init_data.3 new file mode 100644 index 00000000..6260135f --- /dev/null +++ b/static/netbsd/man3/hx509_cert_init_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_init_data.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_keyusage_print.3 b/static/netbsd/man3/hx509_cert_keyusage_print.3 new file mode 100644 index 00000000..efea9c7b --- /dev/null +++ b/static/netbsd/man3/hx509_cert_keyusage_print.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_keyusage_print.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_cert_ref.3 b/static/netbsd/man3/hx509_cert_ref.3 new file mode 100644 index 00000000..faa7d3f4 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_ref.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_ref.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_cert_set_friendly_name.3 b/static/netbsd/man3/hx509_cert_set_friendly_name.3 new file mode 100644 index 00000000..70790bc4 --- /dev/null +++ b/static/netbsd/man3/hx509_cert_set_friendly_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cert_set_friendly_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_certs_add.3 b/static/netbsd/man3/hx509_certs_add.3 new file mode 100644 index 00000000..6920a9dd --- /dev/null +++ b/static/netbsd/man3/hx509_certs_add.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_add.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_append.3 b/static/netbsd/man3/hx509_certs_append.3 new file mode 100644 index 00000000..5acc5f8f --- /dev/null +++ b/static/netbsd/man3/hx509_certs_append.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_append.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_end_seq.3 b/static/netbsd/man3/hx509_certs_end_seq.3 new file mode 100644 index 00000000..5ab7a4e6 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_end_seq.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_end_seq.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_filter.3 b/static/netbsd/man3/hx509_certs_filter.3 new file mode 100644 index 00000000..f2336e64 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_filter.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_filter.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_find.3 b/static/netbsd/man3/hx509_certs_find.3 new file mode 100644 index 00000000..e3f210db --- /dev/null +++ b/static/netbsd/man3/hx509_certs_find.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_find.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_free.3 b/static/netbsd/man3/hx509_certs_free.3 new file mode 100644 index 00000000..c4d17cb9 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_info.3 b/static/netbsd/man3/hx509_certs_info.3 new file mode 100644 index 00000000..dbdac15a --- /dev/null +++ b/static/netbsd/man3/hx509_certs_info.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_info.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_init.3 b/static/netbsd/man3/hx509_certs_init.3 new file mode 100644 index 00000000..6e2521c2 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_iter_f.3 b/static/netbsd/man3/hx509_certs_iter_f.3 new file mode 100644 index 00000000..4181386d --- /dev/null +++ b/static/netbsd/man3/hx509_certs_iter_f.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_iter_f.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_merge.3 b/static/netbsd/man3/hx509_certs_merge.3 new file mode 100644 index 00000000..222506b5 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_merge.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_merge.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_next_cert.3 b/static/netbsd/man3/hx509_certs_next_cert.3 new file mode 100644 index 00000000..029e439e --- /dev/null +++ b/static/netbsd/man3/hx509_certs_next_cert.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_next_cert.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_start_seq.3 b/static/netbsd/man3/hx509_certs_start_seq.3 new file mode 100644 index 00000000..9baf3919 --- /dev/null +++ b/static/netbsd/man3/hx509_certs_start_seq.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_start_seq.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_certs_store.3 b/static/netbsd/man3/hx509_certs_store.3 new file mode 100644 index 00000000..3bbbcbea --- /dev/null +++ b/static/netbsd/man3/hx509_certs_store.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_certs_store.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_ci_print_names.3 b/static/netbsd/man3/hx509_ci_print_names.3 new file mode 100644 index 00000000..f65d7ddd --- /dev/null +++ b/static/netbsd/man3/hx509_ci_print_names.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ci_print_names.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_clear_error_string.3 b/static/netbsd/man3/hx509_clear_error_string.3 new file mode 100644 index 00000000..7a648305 --- /dev/null +++ b/static/netbsd/man3/hx509_clear_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_clear_error_string.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_cms.3 b/static/netbsd/man3/hx509_cms.3 new file mode 100644 index 00000000..9680e0a1 --- /dev/null +++ b/static/netbsd/man3/hx509_cms.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: hx509_cms.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_cms" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_cms \- hx509 CMS/pkcs7 functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_cms_wrap_ContentInfo\fP (const heim_oid *oid, const heim_octet_string *buf, heim_octet_string *res)" +.br +.ti -1c +.RI "int \fBhx509_cms_unwrap_ContentInfo\fP (const heim_octet_string *in, heim_oid *oid, heim_octet_string *out, int *have_data)" +.br +.ti -1c +.RI "int \fBhx509_cms_unenvelope\fP (hx509_context context, hx509_certs certs, int flags, const void *data, size_t length, const heim_octet_string *encryptedContent, time_t time_now, heim_oid *contentType, heim_octet_string *content)" +.br +.ti -1c +.RI "int \fBhx509_cms_envelope_1\fP (hx509_context context, int flags, hx509_cert cert, const void *data, size_t length, const heim_oid *encryption_type, const heim_oid *contentType, heim_octet_string *content)" +.br +.ti -1c +.RI "int \fBhx509_cms_verify_signed\fP (hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void *data, size_t length, const heim_octet_string *signedContent, hx509_certs pool, heim_oid *contentType, heim_octet_string *content, hx509_certs *signer_certs)" +.br +.ti -1c +.RI "int \fBhx509_cms_create_signed_1\fP (hx509_context context, int flags, const heim_oid *eContentType, const void *data, size_t length, const AlgorithmIdentifier *digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string *signed_data)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBCMS/PKCS7 message functions\&.\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_cms_create_signed_1 (hx509_context context, int flags, const heim_oid * eContentType, const void * data, size_t length, const AlgorithmIdentifier * digest_alg, hx509_cert cert, hx509_peer_info peer, hx509_certs anchors, hx509_certs pool, heim_octet_string * signed_data)" +Decode SignedData and verify that the signature is correct\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIflags\fP +.br +\fIeContentType\fP the type of the data\&. +.br +\fIdata\fP data to sign +.br +\fIlength\fP length of the data that data point to\&. +.br +\fIdigest_alg\fP digest algorithm to use, use NULL to get the default or the peer determined algorithm\&. +.br +\fIcert\fP certificate to use for sign the data\&. +.br +\fIpeer\fP info about the peer the message to send the message to, like what digest algorithm to use\&. +.br +\fIanchors\fP trust anchors that the client will use, used to polulate the certificates included in the message +.br +\fIpool\fP certificates to use in try to build the path to the trust anchors\&. +.br +\fIsigned_data\fP the output of the function, free with der_free_octet_string()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_cms_envelope_1 (hx509_context context, int flags, hx509_cert cert, const void * data, size_t length, const heim_oid * encryption_type, const heim_oid * contentType, heim_octet_string * content)" +Encrypt end encode EnvelopedData\&. +.PP +Encrypt and encode EnvelopedData\&. The data is encrypted with a random key and the the random key is encrypted with the certificates private key\&. This limits what private key type can be used to RSA\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIflags\fP flags to control the behavior\&. +.IP "\(bu" 2 +HX509_CMS_EV_NO_KU_CHECK - Don't check KU on certificate +.IP "\(bu" 2 +HX509_CMS_EV_ALLOW_WEAK - Allow weak crytpo +.IP "\(bu" 2 +HX509_CMS_EV_ID_NAME - prefer issuer name and serial number +.PP +.br +\fIcert\fP Certificate to encrypt the EnvelopedData encryption key with\&. +.br +\fIdata\fP pointer the data to encrypt\&. +.br +\fIlength\fP length of the data that data point to\&. +.br +\fIencryption_type\fP Encryption cipher to use for the bulk data, use NULL to get default\&. +.br +\fIcontentType\fP type of the data that is encrypted +.br +\fIcontent\fP the output of the function, free with der_free_octet_string()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +an hx509 error code\&. +.RE +.PP + +.SS "int hx509_cms_unenvelope (hx509_context context, hx509_certs certs, int flags, const void * data, size_t length, const heim_octet_string * encryptedContent, time_t time_now, heim_oid * contentType, heim_octet_string * content)" +Decode and unencrypt EnvelopedData\&. +.PP +Extract data and parameteres from from the EnvelopedData\&. Also supports using detached EnvelopedData\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIcerts\fP Certificate that can decrypt the EnvelopedData encryption key\&. +.br +\fIflags\fP HX509_CMS_UE flags to control the behavior\&. +.br +\fIdata\fP pointer the structure the contains the DER/BER encoded EnvelopedData stucture\&. +.br +\fIlength\fP length of the data that data point to\&. +.br +\fIencryptedContent\fP in case of detached signature, this contains the actual encrypted data, othersize its should be NULL\&. +.br +\fItime_now\fP set the current time, if zero the library uses now as the date\&. +.br +\fIcontentType\fP output type oid, should be freed with der_free_oid()\&. +.br +\fIcontent\fP the data, free with der_free_octet_string()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +an hx509 error code\&. +.RE +.PP + +.SS "int hx509_cms_unwrap_ContentInfo (const heim_octet_string * in, heim_oid * oid, heim_octet_string * out, int * have_data)" +Decode an ContentInfo and unwrap data and oid it\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP the encoded buffer\&. +.br +\fIoid\fP type of the content\&. +.br +\fIout\fP data to be wrapped\&. +.br +\fIhave_data\fP since the data is optional, this flags show dthe diffrence between no data and the zero length data\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_cms_verify_signed (hx509_context context, hx509_verify_ctx ctx, unsigned int flags, const void * data, size_t length, const heim_octet_string * signedContent, hx509_certs pool, heim_oid * contentType, heim_octet_string * content, hx509_certs * signer_certs)" +Decode SignedData and verify that the signature is correct\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP a hx509 verify context\&. +.br +\fIflags\fP to control the behaivor of the function\&. +.IP "\(bu" 2 +HX509_CMS_VS_NO_KU_CHECK - Don't check KeyUsage +.IP "\(bu" 2 +HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH - allow oid mismatch +.IP "\(bu" 2 +HX509_CMS_VS_ALLOW_ZERO_SIGNER - no signer, see below\&. +.PP +.br +\fIdata\fP pointer to CMS SignedData encoded data\&. +.br +\fIlength\fP length of the data that data point to\&. +.br +\fIsignedContent\fP external data used for signature\&. +.br +\fIpool\fP certificate pool to build certificates paths\&. +.br +\fIcontentType\fP free with der_free_oid()\&. +.br +\fIcontent\fP the output of the function, free with der_free_octet_string()\&. +.br +\fIsigner_certs\fP list of the cerficates used to sign this request, free with \fBhx509_certs_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +an hx509 error code\&. +.RE +.PP +If HX509_CMS_VS_NO_KU_CHECK is set, allow more liberal search for matching certificates by not considering KeyUsage bits on the certificates\&. +.PP +If HX509_CMS_VS_ALLOW_DATA_OID_MISMATCH, allow encapContentInfo mismatch with the oid in signedAttributes (or if no signedAttributes where use, pkcs7-data oid)\&. This is only needed to work with broken CMS implementations that doesn't follow CMS signedAttributes rules\&. +.PP +If HX509_CMS_VS_NO_VALIDATE flags is set, do not verify the signing certificates and leave that up to the caller\&. +.PP +If HX509_CMS_VS_ALLOW_ZERO_SIGNER is set, allow empty SignerInfo (no signatures)\&. If SignedData have no signatures, the function will return 0 with signer_certs set to NULL\&. Zero signers is allowed by the standard, but since its only useful in corner cases, it make into a flag that the caller have to turn on\&. +.SS "int hx509_cms_wrap_ContentInfo (const heim_oid * oid, const heim_octet_string * buf, heim_octet_string * res)" +Wrap data and oid in a ContentInfo and encode it\&. +.PP +\fBParameters\fP +.RS 4 +\fIoid\fP type of the content\&. +.br +\fIbuf\fP data to be wrapped\&. If a NULL pointer is passed in, the optional content field in the ContentInfo is not going be filled in\&. +.br +\fIres\fP the encoded buffer, the result should be freed with der_free_octet_string()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_cms_create_signed_1.3 b/static/netbsd/man3/hx509_cms_create_signed_1.3 new file mode 100644 index 00000000..0c5636c8 --- /dev/null +++ b/static/netbsd/man3/hx509_cms_create_signed_1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_create_signed_1.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_cms_envelope_1.3 b/static/netbsd/man3/hx509_cms_envelope_1.3 new file mode 100644 index 00000000..2cbd546d --- /dev/null +++ b/static/netbsd/man3/hx509_cms_envelope_1.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_envelope_1.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_cms_unenvelope.3 b/static/netbsd/man3/hx509_cms_unenvelope.3 new file mode 100644 index 00000000..0568a2f2 --- /dev/null +++ b/static/netbsd/man3/hx509_cms_unenvelope.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_unenvelope.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_cms_unwrap_ContentInfo.3 b/static/netbsd/man3/hx509_cms_unwrap_ContentInfo.3 new file mode 100644 index 00000000..62be049a --- /dev/null +++ b/static/netbsd/man3/hx509_cms_unwrap_ContentInfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_unwrap_ContentInfo.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_cms_verify_signed.3 b/static/netbsd/man3/hx509_cms_verify_signed.3 new file mode 100644 index 00000000..6f6e5bd1 --- /dev/null +++ b/static/netbsd/man3/hx509_cms_verify_signed.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_verify_signed.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_cms_wrap_ContentInfo.3 b/static/netbsd/man3/hx509_cms_wrap_ContentInfo.3 new file mode 100644 index 00000000..e6e8eb85 --- /dev/null +++ b/static/netbsd/man3/hx509_cms_wrap_ContentInfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_cms_wrap_ContentInfo.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cms.3 diff --git a/static/netbsd/man3/hx509_context_free.3 b/static/netbsd/man3/hx509_context_free.3 new file mode 100644 index 00000000..8accb3a3 --- /dev/null +++ b/static/netbsd/man3/hx509_context_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_context_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509.3 diff --git a/static/netbsd/man3/hx509_context_init.3 b/static/netbsd/man3/hx509_context_init.3 new file mode 100644 index 00000000..cfd892ce --- /dev/null +++ b/static/netbsd/man3/hx509_context_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_context_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509.3 diff --git a/static/netbsd/man3/hx509_context_set_missing_revoke.3 b/static/netbsd/man3/hx509_context_set_missing_revoke.3 new file mode 100644 index 00000000..d4e6dc79 --- /dev/null +++ b/static/netbsd/man3/hx509_context_set_missing_revoke.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_context_set_missing_revoke.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crl_add_revoked_certs.3 b/static/netbsd/man3/hx509_crl_add_revoked_certs.3 new file mode 100644 index 00000000..9d298f70 --- /dev/null +++ b/static/netbsd/man3/hx509_crl_add_revoked_certs.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_crl_add_revoked_certs.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crl_alloc.3 b/static/netbsd/man3/hx509_crl_alloc.3 new file mode 100644 index 00000000..f4bc5882 --- /dev/null +++ b/static/netbsd/man3/hx509_crl_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_crl_alloc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crl_free.3 b/static/netbsd/man3/hx509_crl_free.3 new file mode 100644 index 00000000..cd00fa9c --- /dev/null +++ b/static/netbsd/man3/hx509_crl_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_crl_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crl_lifetime.3 b/static/netbsd/man3/hx509_crl_lifetime.3 new file mode 100644 index 00000000..5fb5c9d4 --- /dev/null +++ b/static/netbsd/man3/hx509_crl_lifetime.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_crl_lifetime.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crl_sign.3 b/static/netbsd/man3/hx509_crl_sign.3 new file mode 100644 index 00000000..4d9e3590 --- /dev/null +++ b/static/netbsd/man3/hx509_crl_sign.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_crl_sign.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_crypto.3 b/static/netbsd/man3/hx509_crypto.3 new file mode 100644 index 00000000..4993259c --- /dev/null +++ b/static/netbsd/man3/hx509_crypto.3 @@ -0,0 +1,47 @@ +.\" $NetBSD: hx509_crypto.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_crypto" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_crypto \- hx509 crypto functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_verify_signature\fP (hx509_context context, const hx509_cert signer, const AlgorithmIdentifier *alg, const heim_octet_string *data, const heim_octet_string *sig)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int hx509_verify_signature (hx509_context context, const hx509_cert signer, const AlgorithmIdentifier * alg, const heim_octet_string * data, const heim_octet_string * sig)" +Verify a signature made using the private key of an certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIsigner\fP the certificate that made the signature\&. +.br +\fIalg\fP algorthm that was used to sign the data\&. +.br +\fIdata\fP the data that was signed\&. +.br +\fIsig\fP the sigature to verify\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_env.3 b/static/netbsd/man3/hx509_env.3 new file mode 100644 index 00000000..97fb16a7 --- /dev/null +++ b/static/netbsd/man3/hx509_env.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: hx509_env.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_env" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_env \- hx509 environment functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_env_add\fP (hx509_context context, hx509_env *env, const char *key, const char *value)" +.br +.ti -1c +.RI "int \fBhx509_env_add_binding\fP (hx509_context context, hx509_env *env, const char *key, hx509_env list)" +.br +.ti -1c +.RI "const char * \fBhx509_env_lfind\fP (hx509_context context, hx509_env env, const char *key, size_t len)" +.br +.ti -1c +.RI "const char * \fBhx509_env_find\fP (hx509_context context, hx509_env env, const char *key)" +.br +.ti -1c +.RI "hx509_env \fBhx509_env_find_binding\fP (hx509_context context, hx509_env env, const char *key)" +.br +.ti -1c +.RI "void \fBhx509_env_free\fP (hx509_env *env)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int hx509_env_add (hx509_context context, hx509_env * env, const char * key, const char * value)" +Add a new key/value pair to the hx509_env\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIenv\fP environment to add the environment variable too\&. +.br +\fIkey\fP key to add +.br +\fIvalue\fP value to add +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_env_add_binding (hx509_context context, hx509_env * env, const char * key, hx509_env list)" +Add a new key/binding pair to the hx509_env\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIenv\fP environment to add the environment variable too\&. +.br +\fIkey\fP key to add +.br +\fIlist\fP binding list to add +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "const char* hx509_env_find (hx509_context context, hx509_env env, const char * key)" +Search the hx509_env for a key\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIenv\fP environment to add the environment variable too\&. +.br +\fIkey\fP key to search for\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the value if the key is found, NULL otherwise\&. +.RE +.PP + +.SS "hx509_env hx509_env_find_binding (hx509_context context, hx509_env env, const char * key)" +Search the hx509_env for a binding\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIenv\fP environment to add the environment variable too\&. +.br +\fIkey\fP key to search for\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the binding if the key is found, NULL if not found\&. +.RE +.PP + +.SS "void hx509_env_free (hx509_env * env)" +Free an hx509_env environment context\&. +.PP +\fBParameters\fP +.RS 4 +\fIenv\fP the environment to free\&. +.RE +.PP + +.SS "const char* hx509_env_lfind (hx509_context context, hx509_env env, const char * key, size_t len)" +Search the hx509_env for a length based key\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIenv\fP environment to add the environment variable too\&. +.br +\fIkey\fP key to search for\&. +.br +\fIlen\fP length of key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the value if the key is found, NULL otherwise\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_env_add.3 b/static/netbsd/man3/hx509_env_add.3 new file mode 100644 index 00000000..30add965 --- /dev/null +++ b/static/netbsd/man3/hx509_env_add.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_add.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_env_add_binding.3 b/static/netbsd/man3/hx509_env_add_binding.3 new file mode 100644 index 00000000..7cddb820 --- /dev/null +++ b/static/netbsd/man3/hx509_env_add_binding.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_add_binding.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_env_find.3 b/static/netbsd/man3/hx509_env_find.3 new file mode 100644 index 00000000..b27a14b7 --- /dev/null +++ b/static/netbsd/man3/hx509_env_find.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_find.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_env_find_binding.3 b/static/netbsd/man3/hx509_env_find_binding.3 new file mode 100644 index 00000000..41087e59 --- /dev/null +++ b/static/netbsd/man3/hx509_env_find_binding.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_find_binding.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_env_free.3 b/static/netbsd/man3/hx509_env_free.3 new file mode 100644 index 00000000..9a5f96fc --- /dev/null +++ b/static/netbsd/man3/hx509_env_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_env_lfind.3 b/static/netbsd/man3/hx509_env_lfind.3 new file mode 100644 index 00000000..270bb406 --- /dev/null +++ b/static/netbsd/man3/hx509_env_lfind.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_env_lfind.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_env.3 diff --git a/static/netbsd/man3/hx509_err.3 b/static/netbsd/man3/hx509_err.3 new file mode 100644 index 00000000..74a690a4 --- /dev/null +++ b/static/netbsd/man3/hx509_err.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_err.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_error.3 b/static/netbsd/man3/hx509_error.3 new file mode 100644 index 00000000..e3defca1 --- /dev/null +++ b/static/netbsd/man3/hx509_error.3 @@ -0,0 +1,131 @@ +.\" $NetBSD: hx509_error.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_error" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_error \- hx509 error functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBhx509_clear_error_string\fP (hx509_context context)" +.br +.ti -1c +.RI "void \fBhx509_set_error_stringv\fP (hx509_context context, int flags, int code, const char *fmt, va_list ap)" +.br +.ti -1c +.RI "void \fBhx509_set_error_string\fP (hx509_context context, int flags, int code, const char *fmt,\&.\&.\&.)" +.br +.ti -1c +.RI "char * \fBhx509_get_error_string\fP (hx509_context context, int error_code)" +.br +.ti -1c +.RI "void \fBhx509_free_error_string\fP (char *str)" +.br +.ti -1c +.RI "void \fBhx509_err\fP (hx509_context context, int exit_code, int error_code, const char *fmt,\&.\&.\&.)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBHx509 error reporting functions\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "void hx509_clear_error_string (hx509_context context)" +Resets the error strings the hx509 context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.RE +.PP + +.SS "void hx509_err (hx509_context context, int exit_code, int error_code, const char * fmt, \&.\&.\&.)" +Print error message and fatally exit from error code +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIexit_code\fP exit() code from process\&. +.br +\fIerror_code\fP Error code for the reason to exit\&. +.br +\fIfmt\fP format string with the exit message\&. +.br +\fI\&.\&.\&.\fP argument to format string\&. +.RE +.PP + +.SS "void hx509_free_error_string (char * str)" +Free error string returned by \fBhx509_get_error_string()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIstr\fP error string to free\&. +.RE +.PP + +.SS "char* hx509_get_error_string (hx509_context context, int error_code)" +Get an error string from context associated with error_code\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIerror_code\fP Get error message for this error code\&. +.RE +.PP +\fBReturns\fP +.RS 4 +error string, free with \fBhx509_free_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_set_error_string (hx509_context context, int flags, int code, const char * fmt, \&.\&.\&.)" +See \fBhx509_set_error_stringv()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIflags\fP +.IP "\(bu" 2 +HX509_ERROR_APPEND appends the error string to the old messages (code is updated)\&. +.PP +.br +\fIcode\fP error code related to error message +.br +\fIfmt\fP error message format +.br +\fI\&.\&.\&.\fP arguments to error message format +.RE +.PP + +.SS "void hx509_set_error_stringv (hx509_context context, int flags, int code, const char * fmt, va_list ap)" +Add an error message to the hx509 context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIflags\fP +.IP "\(bu" 2 +HX509_ERROR_APPEND appends the error string to the old messages (code is updated)\&. +.PP +.br +\fIcode\fP error code related to error message +.br +\fIfmt\fP error message format +.br +\fIap\fP arguments to error message format +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_free_error_string.3 b/static/netbsd/man3/hx509_free_error_string.3 new file mode 100644 index 00000000..83f07610 --- /dev/null +++ b/static/netbsd/man3/hx509_free_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_free_error_string.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_free_octet_string_list.3 b/static/netbsd/man3/hx509_free_octet_string_list.3 new file mode 100644 index 00000000..a56fbe44 --- /dev/null +++ b/static/netbsd/man3/hx509_free_octet_string_list.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_free_octet_string_list.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_misc.3 diff --git a/static/netbsd/man3/hx509_general_name_unparse.3 b/static/netbsd/man3/hx509_general_name_unparse.3 new file mode 100644 index 00000000..cfc250ad --- /dev/null +++ b/static/netbsd/man3/hx509_general_name_unparse.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_general_name_unparse.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_get_error_string.3 b/static/netbsd/man3/hx509_get_error_string.3 new file mode 100644 index 00000000..39931f38 --- /dev/null +++ b/static/netbsd/man3/hx509_get_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_get_error_string.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_get_one_cert.3 b/static/netbsd/man3/hx509_get_one_cert.3 new file mode 100644 index 00000000..ee42b86a --- /dev/null +++ b/static/netbsd/man3/hx509_get_one_cert.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_get_one_cert.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_keyset.3 diff --git a/static/netbsd/man3/hx509_keyset.3 b/static/netbsd/man3/hx509_keyset.3 new file mode 100644 index 00000000..5234b0f3 --- /dev/null +++ b/static/netbsd/man3/hx509_keyset.3 @@ -0,0 +1,353 @@ +.\" $NetBSD: hx509_keyset.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_keyset" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_keyset \- hx509 certificate store functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_certs_init\fP (hx509_context context, const char *name, int flags, hx509_lock lock, hx509_certs *certs)" +.br +.ti -1c +.RI "int \fBhx509_certs_store\fP (hx509_context context, hx509_certs certs, int flags, hx509_lock lock)" +.br +.ti -1c +.RI "void \fBhx509_certs_free\fP (hx509_certs *certs)" +.br +.ti -1c +.RI "int \fBhx509_certs_start_seq\fP (hx509_context context, hx509_certs certs, hx509_cursor *cursor)" +.br +.ti -1c +.RI "int \fBhx509_certs_next_cert\fP (hx509_context context, hx509_certs certs, hx509_cursor cursor, hx509_cert *cert)" +.br +.ti -1c +.RI "int \fBhx509_certs_end_seq\fP (hx509_context context, hx509_certs certs, hx509_cursor cursor)" +.br +.ti -1c +.RI "int \fBhx509_certs_iter_f\fP (hx509_context context, hx509_certs certs, int(*func)(hx509_context, void *, hx509_cert), void *ctx)" +.br +.ti -1c +.RI "int \fBhx509_ci_print_names\fP (hx509_context context, void *ctx, hx509_cert c)" +.br +.ti -1c +.RI "int \fBhx509_certs_add\fP (hx509_context context, hx509_certs certs, hx509_cert cert)" +.br +.ti -1c +.RI "int \fBhx509_certs_find\fP (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_cert *r)" +.br +.ti -1c +.RI "int \fBhx509_certs_filter\fP (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_certs *result)" +.br +.ti -1c +.RI "int \fBhx509_certs_merge\fP (hx509_context context, hx509_certs to, hx509_certs from)" +.br +.ti -1c +.RI "int \fBhx509_certs_append\fP (hx509_context context, hx509_certs to, hx509_lock lock, const char *name)" +.br +.ti -1c +.RI "int \fBhx509_get_one_cert\fP (hx509_context context, hx509_certs certs, hx509_cert *c)" +.br +.ti -1c +.RI "int \fBhx509_certs_info\fP (hx509_context context, hx509_certs certs, int(*func)(void *, const char *), void *ctx)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBCertificate store operations\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_certs_add (hx509_context context, hx509_certs certs, hx509_cert cert)" +Add a certificate to the certificiate store\&. +.PP +The receiving keyset certs will either increase reference counter of the cert or make a deep copy, either way, the caller needs to free the cert itself\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to add the certificate to\&. +.br +\fIcert\fP certificate to add\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_append (hx509_context context, hx509_certs to, hx509_lock lock, const char * name)" +Same a \fBhx509_certs_merge()\fP but use a lock and name to describe the from source\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIto\fP the store to merge into\&. +.br +\fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data\&.\fP)\&. +.br +\fIname\fP name of the source store +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_end_seq (hx509_context context, hx509_certs certs, hx509_cursor cursor)" +End the iteration over certificates\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to iterate over\&. +.br +\fIcursor\fP cursor that will keep track of progress, freed\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_filter (hx509_context context, hx509_certs certs, const hx509_query * q, hx509_certs * result)" +Filter certificate matching the query\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to search\&. +.br +\fIq\fP query allocated with \fBhx509 query functions\fP functions\&. +.br +\fIresult\fP the filtered certificate store, caller must free with \fBhx509_certs_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP +Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query\&. +.SS "int hx509_certs_find (hx509_context context, hx509_certs certs, const hx509_query * q, hx509_cert * r)" +Find a certificate matching the query\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to search\&. +.br +\fIq\fP query allocated with \fBhx509 query functions\fP functions\&. +.br +\fIr\fP return certificate (or NULL on error), should be freed with \fBhx509_cert_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP +Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query\&. +.SS "void hx509_certs_free (hx509_certs * certs)" +Free a certificate store\&. +.PP +\fBParameters\fP +.RS 4 +\fIcerts\fP certificate store to free\&. +.RE +.PP + +.SS "int hx509_certs_info (hx509_context context, hx509_certs certs, int(*)(void *, const char *) func, void * ctx)" +Print some info about the certificate store\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to print information about\&. +.br +\fIfunc\fP function that will get each line of the information, if NULL is used the data is printed on a FILE descriptor that should be passed in ctx, if ctx also is NULL, stdout is used\&. +.br +\fIctx\fP parameter to func\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_init (hx509_context context, const char * name, int flags, hx509_lock lock, hx509_certs * certs)" +Open or creates a new hx509 certificate store\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context +.br +\fIname\fP name of the store, format is TYPE:type-specific-string, if NULL is used the MEMORY store is used\&. +.br +\fIflags\fP list of flags: +.IP "\(bu" 2 +HX509_CERTS_CREATE create a new keystore of the specific TYPE\&. +.IP "\(bu" 2 +HX509_CERTS_UNPROTECT_ALL fails if any private key failed to be extracted\&. +.PP +.br +\fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data\&.\fP)\&. +.br +\fIcerts\fP return pointer, free with \fBhx509_certs_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_iter_f (hx509_context context, hx509_certs certs, int(*)(hx509_context, void *, hx509_cert) func, void * ctx)" +Iterate over all certificates in a keystore and call a function for each of them\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to iterate over\&. +.br +\fIfunc\fP function to call for each certificate\&. The function should return non-zero to abort the iteration, that value is passed back to the caller of \fBhx509_certs_iter_f()\fP\&. +.br +\fIctx\fP context variable that will passed to the function\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_merge (hx509_context context, hx509_certs to, hx509_certs from)" +Merge a certificate store into another\&. The from store is keep intact\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIto\fP the store to merge into\&. +.br +\fIfrom\fP the store to copy the object from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_next_cert (hx509_context context, hx509_certs certs, hx509_cursor cursor, hx509_cert * cert)" +Get next ceritificate from the certificate keystore pointed out by cursor\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to iterate over\&. +.br +\fIcursor\fP cursor that keeps track of progress\&. +.br +\fIcert\fP return certificate next in store, NULL if the store contains no more certificates\&. Free with \fBhx509_cert_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_certs_start_seq (hx509_context context, hx509_certs certs, hx509_cursor * cursor)" +Start the integration +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP certificate store to iterate over +.br +\fIcursor\fP cursor that will keep track of progress, free with \fBhx509_certs_end_seq()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. HX509_UNSUPPORTED_OPERATION is returned if the certificate store doesn't support the iteration operation\&. +.RE +.PP + +.SS "int hx509_certs_store (hx509_context context, hx509_certs certs, int flags, hx509_lock lock)" +Write the certificate store to stable storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIcerts\fP a certificate store to store\&. +.br +\fIflags\fP currently unused, use 0\&. +.br +\fIlock\fP a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see \fBLocking and unlocking certificates and encrypted data\&.\fP)\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. HX509_UNSUPPORTED_OPERATION if the certificate store doesn't support the store operation\&. +.RE +.PP + +.SS "int hx509_ci_print_names (hx509_context context, void * ctx, hx509_cert c)" +Function to use to \fBhx509_certs_iter_f()\fP as a function argument, the ctx variable to \fBhx509_certs_iter_f()\fP should be a FILE file descriptor\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIctx\fP used by \fBhx509_certs_iter_f()\fP\&. +.br +\fIc\fP a certificate +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SS "int hx509_get_one_cert (hx509_context context, hx509_certs certs, hx509_cert * c)" +Get one random certificate from the certificate store\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcerts\fP a certificate store to get the certificate from\&. +.br +\fIc\fP return certificate, should be freed with \fBhx509_cert_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns an hx509 error code\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_lock.3 b/static/netbsd/man3/hx509_lock.3 new file mode 100644 index 00000000..43adbee7 --- /dev/null +++ b/static/netbsd/man3/hx509_lock.3 @@ -0,0 +1,16 @@ +.\" $NetBSD: hx509_lock.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_lock" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_lock \- hx509 lock functions +.SH SYNOPSIS +.br +.PP +.SH "Detailed Description" +.PP +See the \fBLocking and unlocking certificates and encrypted data\&.\fP for description and examples\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_misc.3 b/static/netbsd/man3/hx509_misc.3 new file mode 100644 index 00000000..ddb2c138 --- /dev/null +++ b/static/netbsd/man3/hx509_misc.3 @@ -0,0 +1,46 @@ +.\" $NetBSD: hx509_misc.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_misc" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_misc \- hx509 misc functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBhx509_free_octet_string_list\fP (hx509_octet_string_list *list)" +.br +.ti -1c +.RI "void \fBhx509_xfree\fP (void *ptr)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "void hx509_free_octet_string_list (hx509_octet_string_list * list)" +Free a list of octet strings returned by another hx509 library function\&. +.PP +\fBParameters\fP +.RS 4 +\fIlist\fP list to be freed\&. +.RE +.PP + +.SS "void hx509_xfree (void * ptr)" +Free a data element allocated in the library\&. +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP data to be freed\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_name.3 b/static/netbsd/man3/hx509_name.3 new file mode 100644 index 00000000..a145c7b6 --- /dev/null +++ b/static/netbsd/man3/hx509_name.3 @@ -0,0 +1,230 @@ +.\" $NetBSD: hx509_name.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_name" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_name \- hx509 name functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_name_to_string\fP (const hx509_name name, char **str)" +.br +.ti -1c +.RI "int \fBhx509_name_cmp\fP (hx509_name n1, hx509_name n2)" +.br +.ti -1c +.RI "int \fBhx509_parse_name\fP (hx509_context context, const char *str, hx509_name *name)" +.br +.ti -1c +.RI "int \fBhx509_name_copy\fP (hx509_context context, const hx509_name from, hx509_name *to)" +.br +.ti -1c +.RI "int \fBhx509_name_to_Name\fP (const hx509_name from, Name *to)" +.br +.ti -1c +.RI "int \fBhx509_name_expand\fP (hx509_context context, hx509_name name, hx509_env env)" +.br +.ti -1c +.RI "void \fBhx509_name_free\fP (hx509_name *name)" +.br +.ti -1c +.RI "int \fBhx509_unparse_der_name\fP (const void *data, size_t length, char **str)" +.br +.ti -1c +.RI "int \fBhx509_name_binary\fP (const hx509_name name, heim_octet_string *os)" +.br +.ti -1c +.RI "int \fBhx509_name_is_null_p\fP (const hx509_name name)" +.br +.ti -1c +.RI "int \fBhx509_general_name_unparse\fP (GeneralName *name, char **str)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBPKIX/X\&.509 Names\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_general_name_unparse (GeneralName * name, char ** str)" +Unparse the hx509 name in name into a string\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP the name to print +.br +\fIstr\fP an allocated string returns the name in string form +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_name_binary (const hx509_name name, heim_octet_string * os)" +Convert a hx509_name object to DER encoded name\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP name to concert +.br +\fIos\fP data to a DER encoded name, free the resulting octet string with hx509_xfree(os->data)\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_name_cmp (hx509_name n1, hx509_name n2)" +Compare to hx509 name object, useful for sorting\&. +.PP +\fBParameters\fP +.RS 4 +\fIn1\fP a hx509 name object\&. +.br +\fIn2\fP a hx509 name object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 the objects are the same, returns > 0 is n2 is 'larger' then n2, < 0 if n1 is 'smaller' then n2\&. +.RE +.PP + +.SS "int hx509_name_copy (hx509_context context, const hx509_name from, hx509_name * to)" +Copy a hx509 name object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 cotext\&. +.br +\fIfrom\fP the name to copy from +.br +\fIto\fP the name to copy to +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_name_expand (hx509_context context, hx509_name name, hx509_env env)" +Expands variables in the name using env\&. Variables are on the form ${name}\&. Useful when dealing with certificate templates\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 cotext\&. +.br +\fIname\fP the name to expand\&. +.br +\fIenv\fP environment variable to expand\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP +Only UTF8String rdnSequence names are allowed +.SS "void hx509_name_free (hx509_name * name)" +Free a hx509 name object, upond return *name will be NULL\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP a hx509 name object to be freed\&. +.RE +.PP + +.SS "int hx509_name_is_null_p (const hx509_name name)" +Unparse the hx509 name in name into a string\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP the name to check if its empty/null\&. +.RE +.PP +\fBReturns\fP +.RS 4 +non zero if the name is empty/null\&. +.RE +.PP + +.SS "int hx509_name_to_Name (const hx509_name from, Name * to)" +Convert a hx509_name into a Name\&. +.PP +\fBParameters\fP +.RS 4 +\fIfrom\fP the name to copy from +.br +\fIto\fP the name to copy to +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_name_to_string (const hx509_name name, char ** str)" +Convert the hx509 name object into a printable string\&. The resulting string should be freed with free()\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP name to print +.br +\fIstr\fP the string to return +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_parse_name (hx509_context context, const char * str, hx509_name * name)" +Parse a string into a hx509 name object\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIstr\fP a string to parse\&. +.br +\fIname\fP the resulting object, NULL in case of error\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_unparse_der_name (const void * data, size_t length, char ** str)" +Convert a DER encoded name info a string\&. +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP data to a DER/BER encoded name +.br +\fIlength\fP length of data +.br +\fIstr\fP the resulting string, is NULL on failure\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_name_binary.3 b/static/netbsd/man3/hx509_name_binary.3 new file mode 100644 index 00000000..c4dbb4f1 --- /dev/null +++ b/static/netbsd/man3/hx509_name_binary.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_binary.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_cmp.3 b/static/netbsd/man3/hx509_name_cmp.3 new file mode 100644 index 00000000..4c510bf6 --- /dev/null +++ b/static/netbsd/man3/hx509_name_cmp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_cmp.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_copy.3 b/static/netbsd/man3/hx509_name_copy.3 new file mode 100644 index 00000000..83a4c359 --- /dev/null +++ b/static/netbsd/man3/hx509_name_copy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_copy.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_expand.3 b/static/netbsd/man3/hx509_name_expand.3 new file mode 100644 index 00000000..4580a342 --- /dev/null +++ b/static/netbsd/man3/hx509_name_expand.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_expand.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_free.3 b/static/netbsd/man3/hx509_name_free.3 new file mode 100644 index 00000000..b1a2aa72 --- /dev/null +++ b/static/netbsd/man3/hx509_name_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_is_null_p.3 b/static/netbsd/man3/hx509_name_is_null_p.3 new file mode 100644 index 00000000..875dfca9 --- /dev/null +++ b/static/netbsd/man3/hx509_name_is_null_p.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_is_null_p.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_to_Name.3 b/static/netbsd/man3/hx509_name_to_Name.3 new file mode 100644 index 00000000..ff02d296 --- /dev/null +++ b/static/netbsd/man3/hx509_name_to_Name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_to_Name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_name_to_string.3 b/static/netbsd/man3/hx509_name_to_string.3 new file mode 100644 index 00000000..f198ad52 --- /dev/null +++ b/static/netbsd/man3/hx509_name_to_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_name_to_string.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_ocsp_request.3 b/static/netbsd/man3/hx509_ocsp_request.3 new file mode 100644 index 00000000..17e3b03e --- /dev/null +++ b/static/netbsd/man3/hx509_ocsp_request.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ocsp_request.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_ocsp_verify.3 b/static/netbsd/man3/hx509_ocsp_verify.3 new file mode 100644 index 00000000..61ddca29 --- /dev/null +++ b/static/netbsd/man3/hx509_ocsp_verify.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_ocsp_verify.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_oid_print.3 b/static/netbsd/man3/hx509_oid_print.3 new file mode 100644 index 00000000..bcec6c9a --- /dev/null +++ b/static/netbsd/man3/hx509_oid_print.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_oid_print.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_oid_sprint.3 b/static/netbsd/man3/hx509_oid_sprint.3 new file mode 100644 index 00000000..f208faa1 --- /dev/null +++ b/static/netbsd/man3/hx509_oid_sprint.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_oid_sprint.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_parse_name.3 b/static/netbsd/man3/hx509_parse_name.3 new file mode 100644 index 00000000..f3939ad7 --- /dev/null +++ b/static/netbsd/man3/hx509_parse_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_parse_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_peer.3 b/static/netbsd/man3/hx509_peer.3 new file mode 100644 index 00000000..2db58d84 --- /dev/null +++ b/static/netbsd/man3/hx509_peer.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: hx509_peer.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_peer" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_peer \- hx509 certificate selecting functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_peer_info_alloc\fP (hx509_context context, hx509_peer_info *peer)" +.br +.ti -1c +.RI "void \fBhx509_peer_info_free\fP (hx509_peer_info peer)" +.br +.ti -1c +.RI "int \fBhx509_peer_info_set_cert\fP (hx509_peer_info peer, hx509_cert cert)" +.br +.ti -1c +.RI "int \fBhx509_peer_info_add_cms_alg\fP (hx509_context context, hx509_peer_info peer, const AlgorithmIdentifier *val)" +.br +.ti -1c +.RI "int \fBhx509_peer_info_set_cms_algs\fP (hx509_context context, hx509_peer_info peer, const AlgorithmIdentifier *val, size_t len)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int hx509_peer_info_add_cms_alg (hx509_context context, hx509_peer_info peer, const AlgorithmIdentifier * val)" +Add an additional algorithm that the peer supports\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIpeer\fP the peer to set the new algorithms for +.br +\fIval\fP an AlgorithmsIdentier to add +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_peer_info_alloc (hx509_context context, hx509_peer_info * peer)" +Allocate a new peer info structure an init it to default values\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIpeer\fP return an allocated peer, free with \fBhx509_peer_info_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_peer_info_free (hx509_peer_info peer)" +Free a peer info structure\&. +.PP +\fBParameters\fP +.RS 4 +\fIpeer\fP peer info to be freed\&. +.RE +.PP + +.SS "int hx509_peer_info_set_cert (hx509_peer_info peer, hx509_cert cert)" +Set the certificate that remote peer is using\&. +.PP +\fBParameters\fP +.RS 4 +\fIpeer\fP peer info to update +.br +\fIcert\fP cerificate of the remote peer\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_peer_info_set_cms_algs (hx509_context context, hx509_peer_info peer, const AlgorithmIdentifier * val, size_t len)" +Set the algorithms that the peer supports\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIpeer\fP the peer to set the new algorithms for +.br +\fIval\fP array of supported AlgorithmsIdentiers +.br +\fIlen\fP length of array val\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_peer_info_add_cms_alg.3 b/static/netbsd/man3/hx509_peer_info_add_cms_alg.3 new file mode 100644 index 00000000..bfaee837 --- /dev/null +++ b/static/netbsd/man3/hx509_peer_info_add_cms_alg.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_peer_info_add_cms_alg.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_peer.3 diff --git a/static/netbsd/man3/hx509_peer_info_alloc.3 b/static/netbsd/man3/hx509_peer_info_alloc.3 new file mode 100644 index 00000000..bc513b9d --- /dev/null +++ b/static/netbsd/man3/hx509_peer_info_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_peer_info_alloc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_peer.3 diff --git a/static/netbsd/man3/hx509_peer_info_free.3 b/static/netbsd/man3/hx509_peer_info_free.3 new file mode 100644 index 00000000..a89b05d6 --- /dev/null +++ b/static/netbsd/man3/hx509_peer_info_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_peer_info_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_peer.3 diff --git a/static/netbsd/man3/hx509_peer_info_set_cert.3 b/static/netbsd/man3/hx509_peer_info_set_cert.3 new file mode 100644 index 00000000..a794f228 --- /dev/null +++ b/static/netbsd/man3/hx509_peer_info_set_cert.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_peer_info_set_cert.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_peer.3 diff --git a/static/netbsd/man3/hx509_peer_info_set_cms_algs.3 b/static/netbsd/man3/hx509_peer_info_set_cms_algs.3 new file mode 100644 index 00000000..1eed1c7b --- /dev/null +++ b/static/netbsd/man3/hx509_peer_info_set_cms_algs.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_peer_info_set_cms_algs.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_peer.3 diff --git a/static/netbsd/man3/hx509_print.3 b/static/netbsd/man3/hx509_print.3 new file mode 100644 index 00000000..44ada9bd --- /dev/null +++ b/static/netbsd/man3/hx509_print.3 @@ -0,0 +1,209 @@ +.\" $NetBSD: hx509_print.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_print" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_print \- hx509 printing functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBhx509_print_stdout\fP (void *ctx, const char *fmt, va_list va)" +.br +.ti -1c +.RI "int \fBhx509_oid_sprint\fP (const heim_oid *oid, char **str)" +.br +.ti -1c +.RI "void \fBhx509_oid_print\fP (const heim_oid *oid, hx509_vprint_func func, void *ctx)" +.br +.ti -1c +.RI "void \fBhx509_bitstring_print\fP (const heim_bit_string *b, hx509_vprint_func func, void *ctx)" +.br +.ti -1c +.RI "int \fBhx509_cert_keyusage_print\fP (hx509_context context, hx509_cert c, char **s)" +.br +.ti -1c +.RI "int \fBhx509_validate_ctx_init\fP (hx509_context context, hx509_validate_ctx *ctx)" +.br +.ti -1c +.RI "void \fBhx509_validate_ctx_set_print\fP (hx509_validate_ctx ctx, hx509_vprint_func func, void *c)" +.br +.ti -1c +.RI "void \fBhx509_validate_ctx_add_flags\fP (hx509_validate_ctx ctx, int flags)" +.br +.ti -1c +.RI "void \fBhx509_validate_ctx_free\fP (hx509_validate_ctx ctx)" +.br +.ti -1c +.RI "int \fBhx509_validate_cert\fP (hx509_context context, hx509_validate_ctx ctx, hx509_cert cert)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "void hx509_bitstring_print (const heim_bit_string * b, hx509_vprint_func func, void * ctx)" +Print a bitstring using a hx509_vprint_func function\&. To print to stdout use \fBhx509_print_stdout()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIb\fP bit string to print\&. +.br +\fIfunc\fP hx509_vprint_func to print with\&. +.br +\fIctx\fP context variable to hx509_vprint_func function\&. +.RE +.PP + +.SS "int hx509_cert_keyusage_print (hx509_context context, hx509_cert c, char ** s)" +Print certificate usage for a certificate to a string\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIc\fP a certificate print the keyusage for\&. +.br +\fIs\fP the return string with the keysage printed in to, free with \fBhx509_xfree()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_oid_print (const heim_oid * oid, hx509_vprint_func func, void * ctx)" +Print a oid using a hx509_vprint_func function\&. To print to stdout use \fBhx509_print_stdout()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIoid\fP oid to print +.br +\fIfunc\fP hx509_vprint_func to print with\&. +.br +\fIctx\fP context variable to hx509_vprint_func function\&. +.RE +.PP + +.SS "int hx509_oid_sprint (const heim_oid * oid, char ** str)" +Print a oid to a string\&. +.PP +\fBParameters\fP +.RS 4 +\fIoid\fP oid to print +.br +\fIstr\fP allocated string, free with \fBhx509_xfree()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_print_stdout (void * ctx, const char * fmt, va_list va)" +Helper function to print on stdout for: +.IP "\(bu" 2 +\fBhx509_oid_print()\fP, +.IP "\(bu" 2 +\fBhx509_bitstring_print()\fP, +.IP "\(bu" 2 +\fBhx509_validate_ctx_set_print()\fP\&. +.PP +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to the print function\&. If the ctx is NULL, stdout is used\&. +.br +\fIfmt\fP the printing format\&. +.br +\fIva\fP the argumet list\&. +.RE +.PP + +.SS "int hx509_validate_cert (hx509_context context, hx509_validate_ctx ctx, hx509_cert cert)" +Validate/Print the status of the certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP A hx509 validation context\&. +.br +\fIcert\fP the cerificate to validate/print\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_validate_ctx_add_flags (hx509_validate_ctx ctx, int flags)" +Add flags to control the behaivor of the \fBhx509_validate_cert()\fP function\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP A hx509 validation context\&. +.br +\fIflags\fP flags to add to the validation context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_validate_ctx_free (hx509_validate_ctx ctx)" +Free an hx509 validate context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the hx509 validate context to free\&. +.RE +.PP + +.SS "int hx509_validate_ctx_init (hx509_context context, hx509_validate_ctx * ctx)" +Allocate a hx509 validation/printing context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP a new allocated hx509 validation context, free with \fBhx509_validate_ctx_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_validate_ctx_set_print (hx509_validate_ctx ctx, hx509_vprint_func func, void * c)" +Set the printing functions for the validation context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a hx509 valication context\&. +.br +\fIfunc\fP the printing function to usea\&. +.br +\fIc\fP the context variable to the printing function\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_print_cert.3 b/static/netbsd/man3/hx509_print_cert.3 new file mode 100644 index 00000000..4cd74055 --- /dev/null +++ b/static/netbsd/man3/hx509_print_cert.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_print_cert.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_print_stdout.3 b/static/netbsd/man3/hx509_print_stdout.3 new file mode 100644 index 00000000..22c4d2c8 --- /dev/null +++ b/static/netbsd/man3/hx509_print_stdout.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_print_stdout.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_query.3 b/static/netbsd/man3/hx509_query.3 new file mode 100644 index 00000000..b7a6e179 --- /dev/null +++ b/static/netbsd/man3/hx509_query.3 @@ -0,0 +1,16 @@ +.\" $NetBSD: hx509_query.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_query" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_query \- hx509 query functions +.SH SYNOPSIS +.br +.PP +.SH "Detailed Description" +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_query_alloc.3 b/static/netbsd/man3/hx509_query_alloc.3 new file mode 100644 index 00000000..c3546b9a --- /dev/null +++ b/static/netbsd/man3/hx509_query_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_alloc.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_free.3 b/static/netbsd/man3/hx509_query_free.3 new file mode 100644 index 00000000..dba59af2 --- /dev/null +++ b/static/netbsd/man3/hx509_query_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_match_cmp_func.3 b/static/netbsd/man3/hx509_query_match_cmp_func.3 new file mode 100644 index 00000000..6757841b --- /dev/null +++ b/static/netbsd/man3/hx509_query_match_cmp_func.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_match_cmp_func.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_match_eku.3 b/static/netbsd/man3/hx509_query_match_eku.3 new file mode 100644 index 00000000..a5543702 --- /dev/null +++ b/static/netbsd/man3/hx509_query_match_eku.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_match_eku.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_match_friendly_name.3 b/static/netbsd/man3/hx509_query_match_friendly_name.3 new file mode 100644 index 00000000..75b90dd6 --- /dev/null +++ b/static/netbsd/man3/hx509_query_match_friendly_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_match_friendly_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_match_issuer_serial.3 b/static/netbsd/man3/hx509_query_match_issuer_serial.3 new file mode 100644 index 00000000..b4798366 --- /dev/null +++ b/static/netbsd/man3/hx509_query_match_issuer_serial.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_match_issuer_serial.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_match_option.3 b/static/netbsd/man3/hx509_query_match_option.3 new file mode 100644 index 00000000..17166aa0 --- /dev/null +++ b/static/netbsd/man3/hx509_query_match_option.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_match_option.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_statistic_file.3 b/static/netbsd/man3/hx509_query_statistic_file.3 new file mode 100644 index 00000000..15812c6e --- /dev/null +++ b/static/netbsd/man3/hx509_query_statistic_file.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_statistic_file.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_query_unparse_stats.3 b/static/netbsd/man3/hx509_query_unparse_stats.3 new file mode 100644 index 00000000..c17a087b --- /dev/null +++ b/static/netbsd/man3/hx509_query_unparse_stats.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_query_unparse_stats.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_revoke.3 b/static/netbsd/man3/hx509_revoke.3 new file mode 100644 index 00000000..172ce98a --- /dev/null +++ b/static/netbsd/man3/hx509_revoke.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: hx509_revoke.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_revoke" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_revoke \- hx509 revokation checking functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBhx509_revoke_init\fP (hx509_context context, hx509_revoke_ctx *ctx)" +.br +.ti -1c +.RI "void \fBhx509_revoke_free\fP (hx509_revoke_ctx *ctx)" +.br +.ti -1c +.RI "int \fBhx509_revoke_add_ocsp\fP (hx509_context context, hx509_revoke_ctx ctx, const char *path)" +.br +.ti -1c +.RI "int \fBhx509_revoke_add_crl\fP (hx509_context context, hx509_revoke_ctx ctx, const char *path)" +.br +.ti -1c +.RI "int \fBhx509_revoke_verify\fP (hx509_context context, hx509_revoke_ctx ctx, hx509_certs certs, time_t now, hx509_cert cert, hx509_cert parent_cert)" +.br +.ti -1c +.RI "int \fBhx509_ocsp_request\fP (hx509_context context, hx509_certs reqcerts, hx509_certs pool, hx509_cert signer, const AlgorithmIdentifier *digest, heim_octet_string *request, heim_octet_string *nonce)" +.br +.ti -1c +.RI "int \fBhx509_revoke_ocsp_print\fP (hx509_context context, const char *path, FILE *out)" +.br +.in -1c +.SH "Detailed Description" +.PP +See the \fBRevocation methods\fP for description and examples\&. +.SH "Function Documentation" +.PP +.SS "int hx509_ocsp_request (hx509_context context, hx509_certs reqcerts, hx509_certs pool, hx509_cert signer, const AlgorithmIdentifier * digest, heim_octet_string * request, heim_octet_string * nonce)" +Create an OCSP request for a set of certificates\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context +.br +\fIreqcerts\fP list of certificates to request ocsp data for +.br +\fIpool\fP certificate pool to use when signing +.br +\fIsigner\fP certificate to use to sign the request +.br +\fIdigest\fP the signing algorithm in the request, if NULL use the default signature algorithm, +.br +\fIrequest\fP the encoded request, free with free_heim_octet_string()\&. +.br +\fInonce\fP nonce in the request, free with free_heim_octet_string()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_revoke_add_crl (hx509_context context, hx509_revoke_ctx ctx, const char * path)" +Add a CRL file to the revokation context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP hx509 context +.br +\fIctx\fP hx509 revokation context +.br +\fIpath\fP path to file that is going to be added to the context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_revoke_add_ocsp (hx509_context context, hx509_revoke_ctx ctx, const char * path)" +Add a OCSP file to the revokation context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP hx509 context +.br +\fIctx\fP hx509 revokation context +.br +\fIpath\fP path to file that is going to be added to the context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_revoke_free (hx509_revoke_ctx * ctx)" +Free a hx509 revokation context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP context to be freed +.RE +.PP + +.SS "int hx509_revoke_init (hx509_context context, hx509_revoke_ctx * ctx)" +Allocate a revokation context\&. Free with \fBhx509_revoke_free()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP returns a newly allocated revokation context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_revoke_ocsp_print (hx509_context context, const char * path, FILE * out)" +Print the OCSP reply stored in a file\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context +.br +\fIpath\fP path to a file with a OCSP reply +.br +\fIout\fP the out FILE descriptor to print the reply on +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_revoke_verify (hx509_context context, hx509_revoke_ctx ctx, hx509_certs certs, time_t now, hx509_cert cert, hx509_cert parent_cert)" +Check that a certificate is not expired according to a revokation context\&. Also need the parent certificte to the check OCSP parent identifier\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP hx509 context +.br +\fIctx\fP hx509 revokation context +.br +\fIcerts\fP +.br +\fInow\fP +.br +\fIcert\fP +.br +\fIparent_cert\fP +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_revoke_add_crl.3 b/static/netbsd/man3/hx509_revoke_add_crl.3 new file mode 100644 index 00000000..4a542429 --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_add_crl.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_add_crl.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_revoke_add_ocsp.3 b/static/netbsd/man3/hx509_revoke_add_ocsp.3 new file mode 100644 index 00000000..5253e8bc --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_add_ocsp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_add_ocsp.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_revoke_free.3 b/static/netbsd/man3/hx509_revoke_free.3 new file mode 100644 index 00000000..71f8d2c6 --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_revoke_init.3 b/static/netbsd/man3/hx509_revoke_init.3 new file mode 100644 index 00000000..147aa105 --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_revoke_ocsp_print.3 b/static/netbsd/man3/hx509_revoke_ocsp_print.3 new file mode 100644 index 00000000..173e3e65 --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_ocsp_print.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_ocsp_print.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_revoke_verify.3 b/static/netbsd/man3/hx509_revoke_verify.3 new file mode 100644 index 00000000..64b68edd --- /dev/null +++ b/static/netbsd/man3/hx509_revoke_verify.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_revoke_verify.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_revoke.3 diff --git a/static/netbsd/man3/hx509_set_error_string.3 b/static/netbsd/man3/hx509_set_error_string.3 new file mode 100644 index 00000000..af360cd7 --- /dev/null +++ b/static/netbsd/man3/hx509_set_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_set_error_string.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_set_error_stringv.3 b/static/netbsd/man3/hx509_set_error_stringv.3 new file mode 100644 index 00000000..15fa81b6 --- /dev/null +++ b/static/netbsd/man3/hx509_set_error_stringv.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_set_error_stringv.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_error.3 diff --git a/static/netbsd/man3/hx509_unparse_der_name.3 b/static/netbsd/man3/hx509_unparse_der_name.3 new file mode 100644 index 00000000..bfcd7052 --- /dev/null +++ b/static/netbsd/man3/hx509_unparse_der_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_unparse_der_name.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_name.3 diff --git a/static/netbsd/man3/hx509_validate_cert.3 b/static/netbsd/man3/hx509_validate_cert.3 new file mode 100644 index 00000000..0c61667e --- /dev/null +++ b/static/netbsd/man3/hx509_validate_cert.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_validate_cert.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_validate_ctx_add_flags.3 b/static/netbsd/man3/hx509_validate_ctx_add_flags.3 new file mode 100644 index 00000000..03c6da4d --- /dev/null +++ b/static/netbsd/man3/hx509_validate_ctx_add_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_validate_ctx_add_flags.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_validate_ctx_free.3 b/static/netbsd/man3/hx509_validate_ctx_free.3 new file mode 100644 index 00000000..c27a62aa --- /dev/null +++ b/static/netbsd/man3/hx509_validate_ctx_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_validate_ctx_free.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_validate_ctx_init.3 b/static/netbsd/man3/hx509_validate_ctx_init.3 new file mode 100644 index 00000000..8eb63eed --- /dev/null +++ b/static/netbsd/man3/hx509_validate_ctx_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_validate_ctx_init.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_validate_ctx_set_print.3 b/static/netbsd/man3/hx509_validate_ctx_set_print.3 new file mode 100644 index 00000000..b8703d89 --- /dev/null +++ b/static/netbsd/man3/hx509_validate_ctx_set_print.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_validate_ctx_set_print.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_print.3 diff --git a/static/netbsd/man3/hx509_verify.3 b/static/netbsd/man3/hx509_verify.3 new file mode 100644 index 00000000..9be95b94 --- /dev/null +++ b/static/netbsd/man3/hx509_verify.3 @@ -0,0 +1,301 @@ +.\" $NetBSD: hx509_verify.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "hx509_verify" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +hx509_verify \- hx509 verification functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBhx509_context_set_missing_revoke\fP (hx509_context context, int flag)" +.br +.ti -1c +.RI "int \fBhx509_verify_init_ctx\fP (hx509_context context, hx509_verify_ctx *ctx)" +.br +.ti -1c +.RI "void \fBhx509_verify_destroy_ctx\fP (hx509_verify_ctx ctx)" +.br +.ti -1c +.RI "void \fBhx509_verify_attach_anchors\fP (hx509_verify_ctx ctx, hx509_certs set)" +.br +.ti -1c +.RI "void \fBhx509_verify_attach_revoke\fP (hx509_verify_ctx ctx, hx509_revoke_ctx revoke_ctx)" +.br +.ti -1c +.RI "void \fBhx509_verify_set_time\fP (hx509_verify_ctx ctx, time_t t)" +.br +.ti -1c +.RI "void \fBhx509_verify_set_max_depth\fP (hx509_verify_ctx ctx, unsigned int max_depth)" +.br +.ti -1c +.RI "void \fBhx509_verify_set_proxy_certificate\fP (hx509_verify_ctx ctx, int boolean)" +.br +.ti -1c +.RI "void \fBhx509_verify_set_strict_rfc3280_verification\fP (hx509_verify_ctx ctx, int boolean)" +.br +.ti -1c +.RI "int \fBhx509_verify_path\fP (hx509_context context, hx509_verify_ctx ctx, hx509_cert cert, hx509_certs pool)" +.br +.ti -1c +.RI "int \fBhx509_ocsp_verify\fP (hx509_context context, time_t now, hx509_cert cert, int flags, const void *data, size_t length, time_t *expiration)" +.br +.ti -1c +.RI "int \fBhx509_crl_alloc\fP (hx509_context context, hx509_crl *crl)" +.br +.ti -1c +.RI "int \fBhx509_crl_add_revoked_certs\fP (hx509_context context, hx509_crl crl, hx509_certs certs)" +.br +.ti -1c +.RI "int \fBhx509_crl_lifetime\fP (hx509_context context, hx509_crl crl, int delta)" +.br +.ti -1c +.RI "void \fBhx509_crl_free\fP (hx509_context context, hx509_crl *crl)" +.br +.ti -1c +.RI "int \fBhx509_crl_sign\fP (hx509_context context, hx509_cert signer, hx509_crl crl, heim_octet_string *os)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "void hx509_context_set_missing_revoke (hx509_context context, int flag)" +Selects if the \fBhx509_revoke_verify()\fP function is going to require the existans of a revokation method (OCSP, CRL) or not\&. Note that \fBhx509_verify_path()\fP, \fBhx509_cms_verify_signed()\fP, and other function call \fBhx509_revoke_verify()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP hx509 context to change the flag for\&. +.br +\fIflag\fP zero, revokation method required, non zero missing revokation method ok +.RE +.PP + +.SS "int hx509_crl_add_revoked_certs (hx509_context context, hx509_crl crl, hx509_certs certs)" +Add revoked certificate to an CRL context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcrl\fP the CRL to add the revoked certificate to\&. +.br +\fIcerts\fP keyset of certificate to revoke\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_crl_alloc (hx509_context context, hx509_crl * crl)" +Create a CRL context\&. Use \fBhx509_crl_free()\fP to free the CRL context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcrl\fP return pointer to a newly allocated CRL context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_crl_free (hx509_context context, hx509_crl * crl)" +Free a CRL context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcrl\fP a CRL context to free\&. +.RE +.PP + +.SS "int hx509_crl_lifetime (hx509_context context, hx509_crl crl, int delta)" +Set the lifetime of a CRL context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIcrl\fP a CRL context +.br +\fIdelta\fP delta time the certificate is valid, library adds the current time to this\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_crl_sign (hx509_context context, hx509_cert signer, hx509_crl crl, heim_octet_string * os)" +Sign a CRL and return an encode certificate\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context\&. +.br +\fIsigner\fP certificate to sign the CRL with +.br +\fIcrl\fP the CRL to sign +.br +\fIos\fP return the signed and encoded CRL, free with free_heim_octet_string() +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_ocsp_verify (hx509_context context, time_t now, hx509_cert cert, int flags, const void * data, size_t length, time_t * expiration)" +Verify that the certificate is part of the OCSP reply and it's not expired\&. Doesn't verify signature the OCSP reply or it's done by a authorized sender, that is assumed to be already done\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a hx509 context +.br +\fInow\fP the time right now, if 0, use the current time\&. +.br +\fIcert\fP the certificate to verify +.br +\fIflags\fP flags control the behavior +.br +\fIdata\fP pointer to the encode ocsp reply +.br +\fIlength\fP the length of the encode ocsp reply +.br +\fIexpiration\fP return the time the OCSP will expire and need to be rechecked\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_verify_attach_anchors (hx509_verify_ctx ctx, hx509_certs set)" +Set the trust anchors in the verification context, makes an reference to the keyset, so the consumer can free the keyset independent of the destruction of the verification context (ctx)\&. If there already is a keyset attached, it's released\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context +.br +\fIset\fP a keyset containing the trust anchors\&. +.RE +.PP + +.SS "void hx509_verify_attach_revoke (hx509_verify_ctx ctx, hx509_revoke_ctx revoke_ctx)" +Attach an revocation context to the verfication context, , makes an reference to the revoke context, so the consumer can free the revoke context independent of the destruction of the verification context\&. If there is no revoke context, the verification process is NOT going to check any verification status\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context\&. +.br +\fIrevoke_ctx\fP a revoke context\&. +.RE +.PP + +.SS "void hx509_verify_destroy_ctx (hx509_verify_ctx ctx)" +Free an hx509 verification context\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP the context to be freed\&. +.RE +.PP + +.SS "int hx509_verify_init_ctx (hx509_context context, hx509_verify_ctx * ctx)" +Allocate an verification context that is used fo control the verification process\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP returns a pointer to a hx509_verify_ctx object\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "int hx509_verify_path (hx509_context context, hx509_verify_ctx ctx, hx509_cert cert, hx509_certs pool)" +Build and verify the path for the certificate to the trust anchor specified in the verify context\&. The path is constructed from the certificate, the pool and the trust anchors\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A hx509 context\&. +.br +\fIctx\fP A hx509 verification context\&. +.br +\fIcert\fP the certificate to build the path from\&. +.br +\fIpool\fP A keyset of certificates to build the chain from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An hx509 error code, see \fBhx509_get_error_string()\fP\&. +.RE +.PP + +.SS "void hx509_verify_set_max_depth (hx509_verify_ctx ctx, unsigned int max_depth)" +Set the maximum depth of the certificate chain that the path builder is going to try\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context +.br +\fImax_depth\fP maxium depth of the certificate chain, include trust anchor\&. +.RE +.PP + +.SS "void hx509_verify_set_proxy_certificate (hx509_verify_ctx ctx, int boolean)" +Allow or deny the use of proxy certificates +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context +.br +\fIboolean\fP if non zero, allow proxy certificates\&. +.RE +.PP + +.SS "void hx509_verify_set_strict_rfc3280_verification (hx509_verify_ctx ctx, int boolean)" +Select strict RFC3280 verification of certificiates\&. This means checking key usage on CA certificates, this will make version 1 certificiates unuseable\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context +.br +\fIboolean\fP if non zero, use strict verification\&. +.RE +.PP + +.SS "void hx509_verify_set_time (hx509_verify_ctx ctx, time_t t)" +Set the clock time the the verification process is going to use\&. Used to check certificate in the past and future time\&. If not set the current time will be used\&. +.PP +\fBParameters\fP +.RS 4 +\fIctx\fP a verification context\&. +.br +\fIt\fP the time the verifiation is using\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal x509 library from the source code\&. diff --git a/static/netbsd/man3/hx509_verify_attach_anchors.3 b/static/netbsd/man3/hx509_verify_attach_anchors.3 new file mode 100644 index 00000000..509fa1c3 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_attach_anchors.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_attach_anchors.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_attach_revoke.3 b/static/netbsd/man3/hx509_verify_attach_revoke.3 new file mode 100644 index 00000000..5e22f828 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_attach_revoke.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_attach_revoke.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_ctx_f_allow_default_trustanchors.3 b/static/netbsd/man3/hx509_verify_ctx_f_allow_default_trustanchors.3 new file mode 100644 index 00000000..d257a23a --- /dev/null +++ b/static/netbsd/man3/hx509_verify_ctx_f_allow_default_trustanchors.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_ctx_f_allow_default_trustanchors.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_verify_destroy_ctx.3 b/static/netbsd/man3/hx509_verify_destroy_ctx.3 new file mode 100644 index 00000000..9ccc9eef --- /dev/null +++ b/static/netbsd/man3/hx509_verify_destroy_ctx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_destroy_ctx.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_hostname.3 b/static/netbsd/man3/hx509_verify_hostname.3 new file mode 100644 index 00000000..632fa70e --- /dev/null +++ b/static/netbsd/man3/hx509_verify_hostname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_hostname.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_cert.3 diff --git a/static/netbsd/man3/hx509_verify_init_ctx.3 b/static/netbsd/man3/hx509_verify_init_ctx.3 new file mode 100644 index 00000000..7f75af52 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_init_ctx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_init_ctx.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_path.3 b/static/netbsd/man3/hx509_verify_path.3 new file mode 100644 index 00000000..f0cc5c41 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_path.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_path.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_set_max_depth.3 b/static/netbsd/man3/hx509_verify_set_max_depth.3 new file mode 100644 index 00000000..b760b8be --- /dev/null +++ b/static/netbsd/man3/hx509_verify_set_max_depth.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_set_max_depth.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_set_proxy_certificate.3 b/static/netbsd/man3/hx509_verify_set_proxy_certificate.3 new file mode 100644 index 00000000..47321eee --- /dev/null +++ b/static/netbsd/man3/hx509_verify_set_proxy_certificate.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_set_proxy_certificate.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_set_strict_rfc3280_verification.3 b/static/netbsd/man3/hx509_verify_set_strict_rfc3280_verification.3 new file mode 100644 index 00000000..237338e2 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_set_strict_rfc3280_verification.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_set_strict_rfc3280_verification.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_set_time.3 b/static/netbsd/man3/hx509_verify_set_time.3 new file mode 100644 index 00000000..e0c4539f --- /dev/null +++ b/static/netbsd/man3/hx509_verify_set_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_set_time.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_verify.3 diff --git a/static/netbsd/man3/hx509_verify_signature.3 b/static/netbsd/man3/hx509_verify_signature.3 new file mode 100644 index 00000000..23a19a31 --- /dev/null +++ b/static/netbsd/man3/hx509_verify_signature.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_verify_signature.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_crypto.3 diff --git a/static/netbsd/man3/hx509_xfree.3 b/static/netbsd/man3/hx509_xfree.3 new file mode 100644 index 00000000..81104379 --- /dev/null +++ b/static/netbsd/man3/hx509_xfree.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: hx509_xfree.3,v 1.2 2019/12/15 22:50:44 christos Exp $ +.\" +.so man3/hx509_misc.3 diff --git a/static/netbsd/man3/hypot.3 b/static/netbsd/man3/hypot.3 new file mode 100644 index 00000000..1cffb10b --- /dev/null +++ b/static/netbsd/man3/hypot.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)hypot.3 6.7 (Berkeley) 5/6/91 +.\" $NetBSD: hypot.3,v 1.19 2017/09/28 05:51:26 wiz Exp $ +.\" +.Dd September 26, 2017 +.Dt HYPOT 3 +.Os +.Sh NAME +.Nm hypot , +.Nm hypotf , +.Nm hypotl +.Nd Euclidean distance and complex absolute value functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn hypot "double x" "double y" +.Ft float +.Fn hypotf "float x" "float y" +.Ft long double +.Fn hypotl "long double x" "long double y" +.In tgmath.h +.Ft real-floating +.Fn hypot "real-floating" "real-floating" +.Sh DESCRIPTION +The +.Fn hypot +functions +compute the +sqrt(x*x+y*y) +in such a way that underflow will not happen, and overflow +occurs only if the final result deserves it. +.Pp +.Fn hypot "\*(If" "v" += +.Fn hypot "v" "\*(If" += +\*(If for all +.Ar v , +including \*(Na. +.Sh ERRORS +Below 0.97 +.Em ulps . +Consequently +.Fn hypot "5.0" "12.0" += 13.0 +exactly; +in general, hypot returns an integer whenever an +integer might be expected. +.Pp +The same cannot be said for the shorter and faster version of hypot +that is provided in the comments in cabs.c; its error can +exceed 1.2 +.Em ulps . +.Sh NOTES +As might be expected, +.Fn hypot "v" "\*(Na" +and +.Fn hypot "\*(Na" "v" +are \*(Na for all +.Em finite +.Ar v ; +with "reserved operand" in place of "\*(Na", the +same is true on a VAX. +But programmers on machines other than a VAX +(it has no \*(If) +might be surprised at first to discover that +.Fn hypot "\(+-\*(If" "\*(Na" += +\*(If. +This is intentional; it happens because +.Fn hypot "\*(If" "v" += +\*(If +for +.Em all +.Ar v , +finite or infinite. +Hence +.Fn hypot "\*(If" "v" +is independent of +.Ar v . +Unlike the reserved operand fault on a VAX, the IEEE +\*(Na is designed to +disappear when it turns out to be irrelevant, as it does in +.Fn hypot "\*(If" "\*(Na" . +.Sh SEE ALSO +.Xr math 3 , +.Xr sqrt 3 +.Sh HISTORY +The +.Fn hypot +appeared in +.At v7 . diff --git a/static/netbsd/man3/i2d_CMS_bio_stream.3 b/static/netbsd/man3/i2d_CMS_bio_stream.3 new file mode 100644 index 00000000..20ff988a --- /dev/null +++ b/static/netbsd/man3/i2d_CMS_bio_stream.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: i2d_CMS_bio_stream.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "i2d_CMS_bio_stream 3" +.TH i2d_CMS_bio_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +i2d_CMS_bio_stream \- output CMS_ContentInfo structure in BER format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBi2d_CMS_bio_stream()\fR outputs a CMS_ContentInfo structure in BER format. +.PP +It is otherwise identical to the function \fBSMIME_write_CMS()\fR. +.SH NOTES +.IX Header "NOTES" +This function is effectively a version of the \fBi2d_CMS_bio()\fR supporting +streaming. +.SH BUGS +.IX Header "BUGS" +The prefix "i2d" is arguably wrong because the function outputs BER format. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBi2d_CMS_bio_stream()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBCMS_sign\fR\|(3), +\&\fBCMS_verify\fR\|(3), \fBCMS_encrypt\fR\|(3) +\&\fBCMS_decrypt\fR\|(3), +\&\fBSMIME_write_CMS\fR\|(3), +\&\fBPEM_write_bio_CMS_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBi2d_CMS_bio_stream()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/i2d_PKCS7_bio_stream.3 b/static/netbsd/man3/i2d_PKCS7_bio_stream.3 new file mode 100644 index 00000000..b518ccf0 --- /dev/null +++ b/static/netbsd/man3/i2d_PKCS7_bio_stream.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: i2d_PKCS7_bio_stream.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "i2d_PKCS7_bio_stream 3" +.TH i2d_PKCS7_bio_stream 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +i2d_PKCS7_bio_stream \- output PKCS7 structure in BER format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBi2d_PKCS7_bio_stream()\fR outputs a PKCS7 structure in BER format. +.PP +It is otherwise identical to the function \fBSMIME_write_PKCS7()\fR. +.SH NOTES +.IX Header "NOTES" +This function is effectively a version of the \fBd2i_PKCS7_bio()\fR supporting +streaming. +.SH BUGS +.IX Header "BUGS" +The prefix "i2d" is arguably wrong because the function outputs BER format. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBi2d_PKCS7_bio_stream()\fR returns 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3), \fBPKCS7_sign\fR\|(3), +\&\fBPKCS7_verify\fR\|(3), \fBPKCS7_encrypt\fR\|(3) +\&\fBPKCS7_decrypt\fR\|(3), +\&\fBSMIME_write_PKCS7\fR\|(3), +\&\fBPEM_write_bio_PKCS7_stream\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBi2d_PKCS7_bio_stream()\fR function was added in OpenSSL 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2008\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/i2d_re_X509_tbs.3 b/static/netbsd/man3/i2d_re_X509_tbs.3 new file mode 100644 index 00000000..64e469e4 --- /dev/null +++ b/static/netbsd/man3/i2d_re_X509_tbs.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: i2d_re_X509_tbs.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "i2d_re_X509_tbs 3" +.TH i2d_re_X509_tbs 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +d2i_X509_AUX, i2d_X509_AUX, +i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs +\&\- X509 encode and decode functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); +\& int i2d_X509_AUX(const X509 *x, unsigned char **out); +\& int i2d_re_X509_tbs(X509 *x, unsigned char **out); +\& int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp); +\& int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The X509 encode and decode routines encode and parse an +\&\fBX509\fR structure, which represents an X509 certificate. +.PP +\&\fBd2i_X509_AUX()\fR is similar to \fBd2i_X509\fR\|(3) but the input is expected to +consist of an X509 certificate followed by auxiliary trust information. +This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. +This function should not be called on untrusted input. +.PP +\&\fBi2d_X509_AUX()\fR is similar to \fBi2d_X509\fR\|(3), but the encoded output +contains both the certificate and any auxiliary trust information. +This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. +Note that this is a non\-standard OpenSSL\-specific data format. +.PP +\&\fBi2d_re_X509_tbs()\fR is similar to \fBi2d_X509\fR\|(3) except it encodes only +the TBSCertificate portion of the certificate. \fBi2d_re_X509_CRL_tbs()\fR +and \fBi2d_re_X509_REQ_tbs()\fR are analogous for CRL and certificate request, +respectively. The "re" in \fBi2d_re_X509_tbs\fR stands for "re\-encode", +and ensures that a fresh encoding is generated in case the object has been +modified after creation (see the BUGS section). +.PP +The encoding of the TBSCertificate portion of a certificate is cached +in the \fBX509\fR structure internally to improve encoding performance +and to ensure certificate signatures are verified correctly in some +certificates with broken (non\-DER) encodings. +.PP +If, after modification, the \fBX509\fR object is re\-signed with \fBX509_sign()\fR, +the encoding is automatically renewed. Otherwise, the encoding of the +TBSCertificate portion of the \fBX509\fR can be manually renewed by calling +\&\fBi2d_re_X509_tbs()\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBd2i_X509_AUX()\fR returns a valid \fBX509\fR structure or NULL if an error occurred. +.PP +\&\fBi2d_X509_AUX()\fR returns the length of encoded data or \-1 on error. +.PP +\&\fBi2d_re_X509_tbs()\fR, \fBi2d_re_X509_CRL_tbs()\fR and \fBi2d_re_X509_REQ_tbs()\fR return the +length of encoded data or <=0 on error. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBERR_get_error\fR\|(3) +\&\fBX509_CRL_get0_by_serial\fR\|(3), +\&\fBX509_get0_signature\fR\|(3), +\&\fBX509_get_ext_d2i\fR\|(3), +\&\fBX509_get_extension_flags\fR\|(3), +\&\fBX509_get_pubkey\fR\|(3), +\&\fBX509_get_subject_name\fR\|(3), +\&\fBX509_get_version\fR\|(3), +\&\fBX509_NAME_add_entry_by_txt\fR\|(3), +\&\fBX509_NAME_ENTRY_get_object\fR\|(3), +\&\fBX509_NAME_get_index_by_NID\fR\|(3), +\&\fBX509_NAME_print_ex\fR\|(3), +\&\fBX509_new\fR\|(3), +\&\fBX509_sign\fR\|(3), +\&\fBX509V3_get_d2i\fR\|(3), +\&\fBX509_verify_cert\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +. diff --git a/static/netbsd/man3/iconv.3 b/static/netbsd/man3/iconv.3 new file mode 100644 index 00000000..b22efacb --- /dev/null +++ b/static/netbsd/man3/iconv.3 @@ -0,0 +1,279 @@ +.\" $NetBSD: iconv.3,v 1.24 2019/10/24 18:17:59 kamil Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 24, 2019 +.Dt ICONV 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm iconv_open , +.Nm iconv_close , +.Nm iconv +.Nd codeset conversion functions +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In iconv.h +.Ft iconv_t +.Fn iconv_open "const char *dstname" "const char *srcname" +.Ft int +.Fn iconv_close "iconv_t cd" +.Ft size_t +.Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn iconv_open +function opens a converter from the codeset +.Fa srcname +to the codeset +.Fa dstname +and returns its descriptor. +.Pp +The +.Fn iconv_close +function closes the specified converter +.Fa cd . +.Pp +The +.Fn iconv +function converts the string in the buffer +.Fa *src +of length +.Fa *srcleft +bytes and stores the converted string in the buffer +.Fa *dst +of size +.Fa *dstleft +bytes. +After calling +.Fn iconv , +the values pointed to by +.Fa src , +.Fa srcleft , +.Fa dst , +and +.Fa dstleft +are updated as follows: +.Bl -tag -width 01234567 -offset indent +.It Fa *src +Pointer to the byte just after the last character fetched. +.It Fa *srcleft +Number of remaining bytes in the source buffer. +.It Fa *dst +Pointer to the byte just after the last character stored. +.It Fa *dstleft +Number of remainder bytes in the destination buffer. +.El +.Pp +If the string pointed to by +.Fa *src +contains a byte sequence which is not a valid character in the source +codeset, the conversion stops just after the last successful conversion. +If the output buffer is too small to store the converted +character, the conversion also stops in the same way. +In these cases, the values pointed to by +.Fa src , +.Fa srcleft , +.Fa dst , +and +.Fa dstleft +are updated to the state just after the last successful conversion. +.Pp +If the string pointed to by +.Fa *src +contains a character which is valid under the source codeset but +can not be converted to the destination codeset, +the character is replaced by an +.Dq invalid character +which depends on the destination codeset, e.g., +.Sq \&? , +and the conversion is continued. +.Fn iconv +returns the number of such +.Dq invalid conversions . +.Pp +If +.Fa src +or +.Fa *src +is +.Dv NULL +and the source and/or destination codesets are stateful, +.Fn iconv +places these into their initial state. +.Bl -enum -offset indent +.It +If both +.Fa dst +and +.Fa *dst +are +.No non- Ns Dv NULL , +.Fn iconv +stores the shift sequence for the destination switching to the initial state +in the buffer pointed to by +.Fa *dst . +The buffer size is specified by the value pointed to by +.Fa dstleft +as above. +.Fn iconv +will fail if the buffer is too small to store the shift sequence. +.It +On the other hand, +.Fa dst +or +.Fa *dst +may be +.Dv NULL . +In this case, the shift sequence for the destination switching +to the initial state is discarded. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +Upon successful completion of +.Fn iconv_open , +it returns a conversion descriptor. +Otherwise, +.Fn iconv_open +returns (iconv_t)\-1 and sets +.Va errno +to indicate the error. +.Pp +Upon successful completion of +.Fn iconv_close , +it returns 0. +Otherwise, +.Fn iconv_close +returns \-1 and sets errno to indicate the error. +.Pp +Upon successful completion of +.Fn iconv , +it returns the number of +.Dq invalid +conversions. +Otherwise, +.Fn iconv +returns (size_t)\-1 and sets errno to indicate the error. +.\" ---------------------------------------------------------------------- +.Sh ERRORS +The +.Fn iconv_open +function may cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er EINVAL +There is no converter specified by +.Fa srcname +and +.Fa dstname . +.It Bq Er ENOMEM +Memory is exhausted. +.El +.Pp +The +.Fn iconv_close +function may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EBADF +The conversion descriptor specified by +.Fa cd +is invalid. +.El +.Pp +The +.Fn iconv +function may cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er E2BIG +The output buffer pointed to by +.Fa *dst +is too small to store the result string. +.It Bq Er EBADF +The conversion descriptor specified by +.Fa cd +is invalid. +.It Bq Er EILSEQ +The string pointed to by +.Fa *src +contains a byte sequence which does not describe a valid character of +the source codeset. +.It Bq Er EINVAL +The string pointed to by +.Fa *src +terminates with an incomplete character or shift sequence. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr iconv 1 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +.Fn iconv_open , +.Fn iconv_close , +and +.Fn iconv +conform to +.St -p1003.1-2001 . +.Pp +Historically, the definition of +.Ft iconv +has not been consistent across operating systems. +This is due to an unfortunate historical mistake, documented in +.Lk https://www5.opengroup.org/sophocles2/show_mail.tpl?&source=L&listname=austin-group-l&id=7404 "this e-mail". +The standards page for the header file +.In iconv.h +defined the second argument of +.Fn iconv +as +.Ft char ** , +but the standards page for the +.Fn iconv +implementation defined it as +.Ft const char ** . +The standards committee later chose to change the function definition to +follow the header file definition +.Pq without const , +even though the version with const is arguably more correct. +.Nx +used initially the const form. +It was decided to reject the committee's regression and become +.Pq technically +incompatible. +.Pp +This decision was changed in +.Nx 10 +and the +.Fn iconv +prototype was synchronized with the standard. +.\" ---------------------------------------------------------------------- +.Sh BUGS +If +.Fn iconv +is aborted due to the occurrence of some error, +the +.Dq invalid conversion +count mentioned above is unfortunately lost. diff --git a/static/netbsd/man3/ieee_test.3 b/static/netbsd/man3/ieee_test.3 new file mode 100644 index 00000000..4f5a2933 --- /dev/null +++ b/static/netbsd/man3/ieee_test.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91 +.\" $NetBSD: ieee_test.3,v 1.14 2017/07/03 21:32:50 wiz Exp $ +.\" +.Dd August 3, 2011 +.Dt IEEE_TEST 3 +.Os +.Sh NAME +.Nm logb , +.Nm logbf , +.Nm logbl , +.Nm scalb , +.Nm scalbf , +.Nm significand , +.Nm significandf +.Nd IEEE test functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn logb "double x" +.Ft float +.Fn logbf "float x" +.Ft long double +.Fn logbl "long double x" +.Ft double +.Fn scalb "double x" "double n" +.Ft float +.Fn scalbf "float x" "float n" +.Ft double +.Fn significand "double x" +.Ft float +.Fn significandf "float x" +.Sh DESCRIPTION +These functions allow users to test conformance to +.St -ieee754 . +Their use is otherwise not recommended. +.Pp +.Fn logb x +returns +.Fa x Ns 's exponent +.Fa n , +a signed integer converted to double\-precision floating\-point. +.Fn logb \*(Pm\*(If += +\*(If; +.Fn logb 0 += -\*(If with a division by zero exception. +.Pp +.Fn scalb x n +returns +.Fa x Ns \(**(2** Ns Fa n ) +computed by exponent manipulation. +.Pp +.Fn significand x +returns +.Fa sig , +where +.Fa x +:= +.Fa sig No \(** 2** Ns Fa n +with 1 \*[Le] +.Fa sig +< 2. +.Fn significand x +is not defined when +.Fa x +is 0, \*(Pm\*(If, or \*(Na. +.Sh SEE ALSO +.Xr math 3 +.Sh STANDARDS +.St -ieee754 diff --git a/static/netbsd/man3/if_indextoname.3 b/static/netbsd/man3/if_indextoname.3 new file mode 100644 index 00000000..6b27d194 --- /dev/null +++ b/static/netbsd/man3/if_indextoname.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: if_indextoname.3,v 1.12 2010/03/22 19:30:54 joerg Exp $ +.\" $KAME: if_indextoname.3,v 1.10 2000/11/24 08:13:51 itojun Exp $ +.\" BSDI Id: if_indextoname.3,v 2.2 2000/04/17 22:38:05 dab Exp +.\" +.\" Copyright (c) 1997, 2000 +.\" Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 11, 2005 +.Dt IF_NAMETOINDEX 3 +.Os +.Sh NAME +.Nm if_nametoindex , +.Nm if_indextoname , +.Nm if_nameindex , +.Nm if_freenameindex +.Nd provide mappings between interface names and indexes +.Sh SYNOPSIS +.In net/if.h +.Ft unsigned int +.Fn if_nametoindex "const char *ifname" +.Ft char * +.Fn if_indextoname "unsigned int ifindex" "char *ifname" +.Ft struct if_nameindex * +.Fn if_nameindex "void" +.Ft void +.Fn if_freenameindex "struct if_nameindex *ptr" +.Sh DESCRIPTION +The +.Fn if_nametoindex +function maps the interface name specified in +.Ar ifname +to its corresponding index. +If the specified interface does not exist, it returns 0. +.Pp +The +.Fn if_indextoname +function maps the interface index specified in +.Ar ifindex +to it corresponding name, which is copied into the +buffer pointed to by +.Ar ifname , +which must be of at least IFNAMSIZ bytes. +This pointer is also the return value of the function. +If there is no interface corresponding to the specified +index, NULL is returned. +.Pp +The +.Fn if_nameindex +function returns an array of +.Nm if_nameindex +structures, one structure per interface, as +defined in the include file +.In net/if.h . +The +.Nm if_nameindex +structure contains at least the following entries: +.Bd -literal + unsigned int if_index; /* 1, 2, ... */ + char *if_name; /* null terminated name: "le0", ... */ +.Ed +.Pp +The end of the array of structures is indicated by a structure with an +.Nm if_index +of 0 and an +.Nm if_name +of NULL. +A NULL pointer is returned upon an error. +.Pp +The +.Fn if_freenameindex +function frees the dynamic memory that was +allocated by +.Fn if_nameindex . +.Sh RETURN VALUES +Upon successful completion, +.Fn if_nametoindex +returns the index number of the interface. +If the interface is not found, a value of 0 is returned and +.Va errno +is set to +.Er ENXIO . +A value of 0 is also returned if an error +occurs while retrieving the list of interfaces via +.Xr getifaddrs 3 . +.Pp +Upon successful completion, +.Fn if_indextoname +returns +.Ar ifname . +If the interface is not found, a NULL pointer is returned and +.Va errno +is set to +.Er ENXIO . +A NULL pointer is also returned if an error +occurs while retrieving the list of interfaces via +.Xr getifaddrs 3 . +.Pp +The +.Fn if_nameindex +returns a NULL pointer if an error +occurs while retrieving the list of interfaces via +.Xr getifaddrs 3 , +or if sufficient memory cannot be allocated. +.Sh SEE ALSO +.Xr getifaddrs 3 , +.Xr networking 4 +.Sh STANDARDS +The +.Fn if_nametoindex , +.Fn if_indextoname , +.Fn if_nameindex , +and +.Fn if_freenameindex +functions conform to +.St -p1003.1-2001 , +.St -xns5.2 , +and RFC 3493. +.Sh HISTORY +The implementation first appeared in +.Bsx . diff --git a/static/netbsd/man3/ilogb.3 b/static/netbsd/man3/ilogb.3 new file mode 100644 index 00000000..545be078 --- /dev/null +++ b/static/netbsd/man3/ilogb.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: ilogb.3,v 1.4 2016/08/22 07:33:30 maya Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 22, 2016 +.Dt ILOGB 3 +.Os +.Sh NAME +.Nm ilogb , +.Nm ilogbf , +.Nm ilogbl +.Nd an unbiased exponent +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn ilogb "double x" +.Ft int +.Fn ilogbf "float x" +.Ft int +.Fn ilogbl "long double x" +.Sh DESCRIPTION +The +.Fn ilogb , +.Fn ilogbf , +and +.Fn ilogbl +functions return the exponent of the non-zero real floating-point number +.Fa x +as a signed integer value. +Formally the return value is the integral part of +.Bd -ragged -offset indent +log_r | +.Va x | , +.Ed +.Pp +where +.Fa r +is the radix of the machine's floating-point arithmetic defined by the +.Dv FLT_RADIX +constant in +.In float.h . +.Sh RETURN VALUES +As described above, upon successful completion, +the functions return the exponent. +Functionally this is the same as calling the corresponding +.Xr logb 3 +function and casting the return value to +.Vt int . +.Pp +The following special cases may occur: +.Bl -enum -offset indent +.It +If +.Fa x +is zero, the value of +.Dv FP_ILOGB0 +is returned and a domain error occurs. +.It +If +.Fa x +is infinite, a domain error occurs and the value of +.Dv INT_MAX +is returned. +.It +If +.Fa x +is \*(Na, a domain error is raised and the value of +.Dv FP_ILOGBNAN +is returned. +.It +If the correct value is outside the range of the return type, +a domain error occurs but an unspecified value is returned. +.El +.Sh SEE ALSO +.Xr ilog2 3 , +.Xr logb 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/include.include.withclauses.3 b/static/netbsd/man3/include.include.withclauses.3 new file mode 100644 index 00000000..49c88fe8 --- /dev/null +++ b/static/netbsd/man3/include.include.withclauses.3 @@ -0,0 +1 @@ +include: include.withclauses.* diff --git a/static/netbsd/man3/include.include.withoutclauses.3 b/static/netbsd/man3/include.include.withoutclauses.3 new file mode 100644 index 00000000..3552d769 --- /dev/null +++ b/static/netbsd/man3/include.include.withoutclauses.3 @@ -0,0 +1 @@ +include: include.withoutclauses.* diff --git a/static/netbsd/man3/include.includetop.withclauses.3 b/static/netbsd/man3/include.includetop.withclauses.3 new file mode 100644 index 00000000..5e296548 --- /dev/null +++ b/static/netbsd/man3/include.includetop.withclauses.3 @@ -0,0 +1 @@ +include-toplevel: include.withclauses.* diff --git a/static/netbsd/man3/include.includetop.withoutclauses.3 b/static/netbsd/man3/include.includetop.withoutclauses.3 new file mode 100644 index 00000000..a411f7b5 --- /dev/null +++ b/static/netbsd/man3/include.includetop.withoutclauses.3 @@ -0,0 +1 @@ +include-toplevel: include.withoutclauses.* diff --git a/static/netbsd/man3/include.withclauses.3 b/static/netbsd/man3/include.withclauses.3 new file mode 100644 index 00000000..5e19c54e --- /dev/null +++ b/static/netbsd/man3/include.withclauses.3 @@ -0,0 +1 @@ +server: identity: "withclauses3" diff --git a/static/netbsd/man3/include.withoutclauses.3 b/static/netbsd/man3/include.withoutclauses.3 new file mode 100644 index 00000000..e34a4b12 --- /dev/null +++ b/static/netbsd/man3/include.withoutclauses.3 @@ -0,0 +1 @@ +identity: "withoutclauses3" diff --git a/static/netbsd/man3/include.withsomeclauses.3 b/static/netbsd/man3/include.withsomeclauses.3 new file mode 100644 index 00000000..dbb696ee --- /dev/null +++ b/static/netbsd/man3/include.withsomeclauses.3 @@ -0,0 +1 @@ +identity: "withsomeclauses3" diff --git a/static/netbsd/man3/index.3 b/static/netbsd/man3/index.3 new file mode 100644 index 00000000..a1a0f41e --- /dev/null +++ b/static/netbsd/man3/index.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)index.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: index.3,v 1.15 2012/05/05 21:18:43 dholland Exp $ +.\" +.Dd May 5, 2012 +.Dt INDEX 3 +.Os +.Sh NAME +.Nm index +.Nd locate character in string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft char * +.Fn index "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn index +function +locates the first character matching +.Fa c +(converted to a +.Em char ) +in the nul-terminated string +.Fa s . +.Pp +This function is obsolete. +The equivalent function +.Xr strchr 3 +should be used instead. +.Sh RETURN VALUES +A pointer to the character is returned if it is found; otherwise +.Dv NULL +is returned. +If +.Fa c +is '\e0', +.Fn index +locates the terminating '\e0'. +.Sh SEE ALSO +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn index +function conforms to +.St -p1003.1-2001 . +The +.St -p1003.1-2004 +revision marked it as legacy and recommended the use of +.Xr strchr 3 +instead. +The +.St -p1003.1-2008 +revision removed +.Fn index +from the specification. +.Sh HISTORY +An +.Fn index +function appeared in +.At v6 . diff --git a/static/netbsd/man3/inet.3 b/static/netbsd/man3/inet.3 new file mode 100644 index 00000000..506dd098 --- /dev/null +++ b/static/netbsd/man3/inet.3 @@ -0,0 +1,410 @@ +.\" $NetBSD: inet.3,v 1.7 2023/01/18 23:16:05 riastradh Exp $ +.\" +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)inet.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 25, 2012 +.Dt INET 3 +.Os +.Sh NAME +.Nm inet_addr , +.Nm inet_aton , +.Nm inet_lnaof , +.Nm inet_makeaddr , +.Nm inet_netof , +.Nm inet_network , +.Nm inet_ntoa , +.Nm inet_ntop , +.Nm inet_pton , +.Nm addr , +.Nm ntoa , +.Nm network +.Nd Internet address manipulation routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In arpa/inet.h +.Ft in_addr_t +.Fn inet_addr "const char *cp" +.Ft int +.Fn inet_aton "const char *cp" "struct in_addr *addr" +.Ft in_addr_t +.Fn inet_lnaof "struct in_addr in" +.Ft struct in_addr +.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" +.Ft in_addr_t +.Fn inet_netof "struct in_addr in" +.Ft in_addr_t +.Fn inet_network "const char *cp" +.Ft char * +.Fn inet_ntoa "struct in_addr in" +.Ft const char * +.Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size" +.Ft int +.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" +.Sh DESCRIPTION +The routines +.Fn inet_aton , +.Fn inet_addr +and +.Fn inet_network +interpret character strings representing +numbers expressed in the Internet standard +.Qq dotted quad +notation. +.Pp +The +.Fn inet_pton +function converts a presentation format address (that is, printable form +as held in a character string) to network format (usually a +.Ft struct in_addr +or some other internal binary representation, in network byte order). +It returns 1 if the address was valid for the specified address family, or +0 if the address wasn't parsable in the specified address family, or -1 +if some system error occurred (in which case +.Va errno +will have been set). +This function is presently valid for +.Dv AF_INET +and +.Dv AF_INET6 . +.Pp +The +.Fn inet_aton +routine interprets the specified character string as an Internet address, +placing the address into the structure provided. +It returns 1 if the string was successfully interpreted, +or 0 if the string is invalid. +.Pp +The +.Fn inet_addr +and +.Fn inet_network +functions return numbers suitable for use +as Internet addresses and Internet network +numbers, respectively. +.Pp +The function +.Fn inet_ntop +converts an address from network format (usually a +.Ft struct in_addr +or some other binary form, in network byte order) to presentation format +(suitable for external display purposes). +It returns NULL if a system error occurs (in which case, +.Va errno +will have been set), or it returns a pointer to the destination string. +The +.Fa size +parameter is the size of the +.Fa dst +buffer. +For +.Dv AF_INET , +this must have space for +.Dv INET_ADDRSTRLEN Pq 16 +bytes; for +.Dv AF_INET6 , +this must have space for +.Dv INET6_ADDRSTRLEN Pq 46 +bytes. +.Pp +The routine +.Fn inet_ntoa +takes an Internet address and returns an +.Tn ASCII +string representing the address in +.Qq dotted quad +notation. +.Pp +The routine +.Fn inet_makeaddr +takes an Internet network number and a local network address (both in +host order) and constructs an Internet address from it. +Note that to convert only a single value to a +.Ft struct in_addr +form that value should be passed as the first parameter and +.Ql 0L +should be given for the second parameter. +.Pp +The routines +.Fn inet_netof +and +.Fn inet_lnaof +break apart Internet host addresses, returning the network number and +local network address part, respectively (both in host order). +.Pp +All Internet addresses are returned in network +order (bytes ordered from left to right). +All network numbers and local address parts are +returned as machine format integer values. +.Sh INTERNET ADDRESSES (IP VERSION 4) +Values specified using the +.Qq dotted quad +notation take one +of the following forms: +.Bd -literal -offset indent +a.b.c.d +a.b.c +a.b +a +.Ed +.Pp +When four parts are specified, each is interpreted +as a byte of data and assigned, from left to right, +to the four bytes of an Internet address. +Note that when an Internet address is viewed as a 32-bit +integer quantity on a system that uses little-endian +byte order (e.g. +.Tn Intel i386, i486 +and +.Tn Pentium +processors) the bytes referred to above appear as +.Dq Li d.c.b.a . +That is, little-endian bytes are ordered from right to left. +.Pp +When a three part address is specified, the last +part is interpreted as a 16-bit quantity and placed +in the right-most two bytes of the network address. +This makes the three part address format convenient +for specifying Class B network addresses as +.Dq Li 128.net.host . +.Pp +When a two part address is supplied, the last part +is interpreted as a 24-bit quantity and placed in +the right most three bytes of the network address. +This makes the two part address format convenient +for specifying Class A network addresses as +.Dq Li net.host . +.Pp +When only one part is given, the value is stored +directly in the network address without any byte +rearrangement. +.Pp +All numbers supplied as +.Dq parts +in a +.Qq dotted quad +notation +may be decimal, octal, or hexadecimal, as specified +in the C language (i.e., a leading 0x or 0X implies +hexadecimal; otherwise, a leading 0 implies octal; +otherwise, the number is interpreted as decimal). +.Sh INTERNET ADDRESSES (IP VERSION 6) +In order to support scoped IPv6 addresses, +the use of +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 +is recommended rather than the functions presented here. +.Pp +The presentation format of an IPv6 address is given in RFC 2373: +.Pp +There are three conventional forms for representing IPv6 addresses as +text strings: +.Bl -enum +.It +The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the +hexadecimal values of the eight 16-bit pieces of the address. +Examples: +.Bd -literal -offset indent +FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 +1080:0:0:0:8:800:200C:417A +.Ed +.Pp +Note that it is not necessary to write the leading zeros in an +individual field, but there must be at least one numeral in +every field (except for the case described in 2). +.It +Due to the method of allocating certain styles of IPv6 +addresses, it will be common for addresses to contain long +strings of zero bits. +In order to make writing addresses +containing zero bits easier, a special syntax is available to +compress the zeros. +The use of ``::'' indicates multiple groups of 16-bits of zeros. +The ``::'' can only appear once in an address. +The ``::'' can also be used to compress the leading +and/or trailing zeros in an address. +.Pp +For example the following addresses: +.Bd -literal -offset indent +1080:0:0:0:8:800:200C:417A a unicast address +FF01:0:0:0:0:0:0:43 a multicast address +0:0:0:0:0:0:0:1 the loopback address +0:0:0:0:0:0:0:0 the unspecified addresses +.Ed +.Pp +may be represented as: +.Bd -literal -offset indent +1080::8:800:200C:417A a unicast address +FF01::43 a multicast address +::1 the loopback address +:: the unspecified addresses +.Ed +.It +An alternative form that is sometimes more convenient when +dealing with a mixed environment of IPv4 and IPv6 nodes is +x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values +of the six high-order 16-bit pieces of the address, and the 'd's +are the decimal values of the four low-order 8-bit pieces of the +address (standard IPv4 representation). +Examples: +.Bd -literal -offset indent +0:0:0:0:0:0:13.1.68.3 +0:0:0:0:0:FFFF:129.144.52.38 +.Ed +.Pp +or in compressed form: +.Bd -literal -offset indent +::13.1.68.3 +::FFFF:129.144.52.38 +.Ed +.El +.Sh RETURN VALUES +The constant +.Dv INADDR_NONE +is returned by +.Fn inet_addr +and +.Fn inet_network +for malformed requests. +.Sh ERRORS +The +.Fn inet_ntop +and +.Fn inet_pton +functions may fail with +.Bl -tag -width Er +.It Bq Er EAFNOSUPPORT +The value of +.Fa af +was not +.Dv AF_INET +or +.Dv AF_INET6 . +.El +.Pp +The +.Fn inet_ntop +function may fail with +.Bl -tag -width Er +.It Bq Er ENOSPC +The +.Fa size +indicated for +.Fa dst +was too small to store the presentation form of the network address. +.El +.Sh SEE ALSO +.Xr byteorder 3 , +.Xr gethostbyname 3 , +.Xr getnetent 3 , +.Xr inet_net 3 , +.Xr hosts 5 , +.Xr networks 5 +.Rs +.%R RFC 2373 +.%D July 1998 +.%T "IP Version 6 Addressing Architecture" +.Re +.Rs +.%R RFC 3493 +.%D February 2003 +.%T "Basic Socket Interface Extensions for IPv6" +.Re +.Sh STANDARDS +The +.Fn inet_ntop +and +.Fn inet_pton +functions conform to +.St -p1003.1-2001 . +Note that +.Fn inet_pton +does not accept 1-, 2-, or 3-part dotted addresses; all four parts +must be specified. +Additionally all four parts of a dotted address must be decimal. +This is a narrower input set than that accepted by +.Fn inet_aton . +.Sh HISTORY +The +.Fn inet_addr , +.Fn inet_network , +.Fn inet_makeaddr , +.Fn inet_lnaof +and +.Fn inet_netof +functions appeared in +.Bx 4.2 . +They were changed to use +.Vt in_addr_t +in place of +.Vt unsigned long +in +.Nx 2.0 . +The +.Fn inet_aton +and +.Fn inet_ntoa +functions appeared in +.Bx 4.3 . +The +.Fn inet_pton +and +.Fn inet_ntop +functions appeared in BIND 4.9.4 and thence +.Nx 1.3 ; +they were also in +.St -xns5.2 . +.Sh BUGS +The value +.Dv INADDR_NONE +(0xffffffff) is a valid broadcast address, but +.Fn inet_addr +cannot return that value without indicating failure. +The newer +.Fn inet_aton +function does not share this problem. +.Pp +The problem of host byte ordering versus network byte ordering is +confusing. +.Pp +The string returned by +.Fn inet_ntoa +resides in a static memory area. +.Pp +The function +.Fn inet_addr +should return a +.Vt struct in_addr . +.Pp +The function +.Fn inet_network +does not support byte rearrangement for one, two, and three +part addresses. diff --git a/static/netbsd/man3/inet6_getscopeid.3 b/static/netbsd/man3/inet6_getscopeid.3 new file mode 100644 index 00000000..4195019c --- /dev/null +++ b/static/netbsd/man3/inet6_getscopeid.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: inet6_getscopeid.3,v 1.3 2013/10/31 00:30:14 wiz Exp $ +.\"- +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd October 31, 2013 +.Dt INET6_GETSCOPEID 3 +.Os +.\" +.Sh NAME +.Nm inet6_getscopeid , +.Nm inet6_putscopeid +.Nd IPv6 scope id encoding and decoding functions +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft void +.Fn inet6_getscopeid "struct sockaddr_in6 *sin6" "int flags" +.Ft void +.Fn inet6_putscopeid "struct sockaddr_in6 *sin6" "int flags" +.\" +.Sh DESCRIPTION +These functions implement a KAME-specific extension that encodes and +decodes the scope id inside in the 3rd and 4th byte of the address, +for link-local, site-local, and multicast-link-local addresses. +The scope id helps deciding which interface is used for packets of +that type. +.Pp +Typically those two bytes are +.Dv 0 +for these kinds of addresses. +The scope id is stored in network byte order. +.Pp +The +.Fn inet6_getscopeid +function retrieves the scope id from the 3rd and the 4th address bytes +(from the +.Va sin6_addr +member of +.Fa sin6 ) , +and sets the +.Ft sin6_scope_id +from them. +It then clears the two address bytes. +.Pp +The +.Fn inet6putscopeid +function stores the scope id found in +.Ft sin6_scope_id +into the 3rd and 4th byte of the address +(into the +.Va sin6_addr +member of +.Fa sin6 ) . +It then clears the +.Va sin6_scope_id +member of +.Fa sin6 . +.Pp +The +.Fa flags +argument controls for which addresses this action is performed. +It +can be a combination of: +.Bl -bullet +.It +.Dv INET6_IS_ADDR_LINKLOCAL +.It +.Dv INET6_IS_ADDR_MC_LINKLOCAL +.It +.Dv INET6_IS_ADDR_SITELOCAL +.El +.Sh HISTORY +These functions first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/inet6_opt_init.3 b/static/netbsd/man3/inet6_opt_init.3 new file mode 100644 index 00000000..424c0054 --- /dev/null +++ b/static/netbsd/man3/inet6_opt_init.3 @@ -0,0 +1,337 @@ +.\" $NetBSD: inet6_opt_init.3,v 1.3 2022/12/04 01:29:32 uwe Exp $ +.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $ +.\" +.\" Copyright (C) 2004 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 23, 2004 +.Dt INET6_OPT_INIT 3 +.Os +.\" +.Sh NAME +.Nm inet6_opt_init , +.Nm inet6_opt_append , +.Nm inet6_opt_finish , +.Nm inet6_opt_set_val , +.Nm inet6_opt_next , +.Nm inet6_opt_find , +.Nm inet6_opt_get_val +.Nd IPv6 Hop-by-Hop and Destination Options manipulation +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft "int" +.Fn inet6_opt_init "void *extbuf" "socklen_t extlen" +.Ft "int" +.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp" +.Ft "int" +.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset" +.Ft "int" +.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen" +.Ft "int" +.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp" +.Ft "int" +.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp" +.Ft "int" +.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen" +.\" +.Sh DESCRIPTION +Building and parsing the Hop-by-Hop and Destination options is +complicated. +The advanced sockets API defines a set of functions to +help applications create and manipulate Hop-by-Hope and Destination +options. +.\"This man page describes the functions specified in +.\"IETF Draft RFC3542 while the +.\".Xr inet6_options_space 3 +.\"man page documents the functions defined in RFC 2292. +.\"It is expected +.\"that this set of functions will supersede those in RFC 2292 but for +.\"the time being both APIs are retained. +These functions use the +formatting rules specified in Appendix B in RFC2460, i.e., that the +largest field is placed last in the option. +The function prototypes +for these functions are all contained in the +.In netinet/in.h +header file. +.\" +.Ss inet6_opt_init +The +.Fn inet6_opt_init +function +returns the number of bytes needed for an empty +extension header, one without any options. +If the +.Va extbuf +argument points to a valid section of memory +then the +.Fn inet6_opt_init +function also initializes the extension header's length field. +When attempting to initialize an extension buffer passed in the +.Va extbuf argument +.Fa extlen +must be a positive multiple of 8 or else the function fails and +returns \-1 to the caller. +.\" +.Ss inet6_opt_append +The +.Fn inet6_opt_append +function can perform to different jobs. +When a valid +.Fa extbuf +argument is supplied it appends an option to the extension buffer and +returns the updated total length as well as a pointer to the newly +created option in +.Fa databufp . +If the value +of +.Fa extbuf +is +.Dv NULL +then the +.Fn inet6_opt_append function only reports what the total length would +be if the option were actually appended. +The +.Fa len +and +.Fa align +arguments specify the length of the option and the required data +alignment which must be used when appending the option. +The +.Fa offset +argument should be the length returned by the +.Fn inet6_opt_init +function or a previous call to +.Fn inet6_opt_append . +.Pp +The +.Fa type +argument is the 8-bit option type. +.Pp +After +.Fn inet6_opt_append +has been called, the application can use the buffer pointed to by +.Fa databufp +directly, or use +.Fn inet6_opt_set_val +to specify the data to be contained in the option. +.Pp +Option types of +.Li 0 +and +.Li 1 +are reserved for the +.Li Pad1 +and +.Li PadN +options. +All other values from 2 through 255 may be used by applications. +.Pp +The length of the option data is contained in an 8-bit value and so +may contain any value from 0 through 255. +.Pp +The +.Fa align +parameter must have a value of 1, 2, 4, or 8 and cannot exceed the +value of +.Fa len . +The alignment values represent no alignment, 16 bit, 32 bit and 64 bit +alignments respectively. +.\" +.Ss inet6_opt_finish +The +.Fn inet6_opt_finish +calculates the final padding necessary to make the extension header a +multiple of 8 bytes, as required by the IPv6 extension header +specification, and returns the extension header's updated total +length. +The +.Fa offset +argument should be the length returned by +.Fn inet6_opt_init +or +.Fn inet6_opt_append . +When +.Fa extbuf +is not +.Dv NULL +the function also sets up the appropriate padding bytes by inserting a +Pad1 or PadN option of the proper length. +.Pp +If the extension header is too small to contain the proper padding +then an error of \-1 is returned to the caller. +.\" +.Ss inet6_opt_set_val +The +.Fn inet6_opt_set_val +function inserts data items of various sizes into the data portion of +the option. +The +.Fa databuf +argument is a pointer to memory that was returned by the +.Fn inet6_opt_append +call and the +.Fa offset argument specifies where the option should be placed in the +data buffer. +The +.Fa val +argument points to an area of memory containing the data to be +inserted into the extension header, and the +.Fa vallen +argument indicates how much data to copy. +.Pp +The caller should ensure that each field is aligned on its natural +boundaries as described in Appendix B of RFC2460. +.Pp +The function returns the offset for the next field which is calculated as +.Fa offset ++ +.Fa vallen +and is used when composing options with multiple fields. +.\" +.Ss inet6_opt_next +The +.Fn inet6_opt_next +function parses received extension headers. +The +.Fa extbuf +and +.Fa extlen +arguments specify the location and length of the extension header +being parsed. +The +.Fa offset +argument should either be zero, for the first option, or the length value +returned by a previous call to +.Fn inet6_opt_next +or +.Fn inet6_opt_find . +The return value specifies the position where to continue scanning the +extension buffer. +The option is returned in the arguments +.Fa typep , lenp , +and +.Fa databufp . +.Fa typep , lenp , +and +.Fa databufp +point to the 8-bit option type, the 8-bit option length and the option +data respectively. +This function does not return any PAD1 or PADN options. +When an error occurs or there are no more options the return +value is \-1. +.\" +.Ss inet6_opt_find +The +.Fn inet6_opt_find +function searches the extension buffer for a particular option type, +passed in through the +.Fa type +argument. +If the option is found then the +.Fa lenp +and +.Fa databufp +arguments are updated to point to the option's length and data +respectively. +.Fa extbuf +and +.Fa extlen +must point to a valid extension buffer and give its length. +The +.Fa offset +argument can be used to search from a location anywhere in the +extension header. +.Ss inet6_opt_get_val +The +.Fn inet6_opt_get_val +function extracts data items of various sizes in the data portion of +the option. +The +.Fa databuf +is a pointer returned by the +.Fn inet6_opt_next +or +.Fn inet6_opt_find +functions. +The +.Fa val +argument points where the data will be extracted. +The +.Fa offset +argument specifies from where in the data portion of the option the +value should be extracted; the first byte of option data is specified +by an offset of zero. +.Pp +It is expected that each field is aligned on its natural boundaries as +described in Appendix B of RFC2460. +.Pp +The function returns the offset for the next field +by calculating +.Fa offset ++ +.Fa vallen +which can be used when extracting option content with multiple fields. +Robust receivers must verify alignment before calling this function. +.\" +.Sh EXAMPLES +RFC3542 gives comprehensive examples in Section 23. +.Pp +KAME also provides examples in the +.Pa advapitest +directory of its kit. +.\" +.Sh RETURN VALUES +All the functions return +\-1 +on an error. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets API for IPv6" +.%N RFC3542 +.%D October 2002 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC2460 +.%D December 1998 +.Re +.Sh STANDARDS +The functions are documented in +.Dq Advanced Sockets API for IPv6 +.Pq RFC3542 . +.\" +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. diff --git a/static/netbsd/man3/inet6_option_space.3 b/static/netbsd/man3/inet6_option_space.3 new file mode 100644 index 00000000..f9106ee9 --- /dev/null +++ b/static/netbsd/man3/inet6_option_space.3 @@ -0,0 +1,448 @@ +.\" $NetBSD: inet6_option_space.3,v 1.4 2022/12/04 01:29:32 uwe Exp $ +.\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun Exp $ +.\" +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 10, 1999 +.Dt INET6_OPTION_SPACE 3 +.Os +.\" +.Sh NAME +.Nm inet6_option_space , +.Nm inet6_option_init , +.Nm inet6_option_append , +.Nm inet6_option_alloc , +.Nm inet6_option_next , +.Nm inet6_option_find +.Nd IPv6 Hop-by-Hop and Destination Options manipulation +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft "int" +.Fn inet6_option_space "int nbytes" +.Ft "int" +.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type" +.Ft "int" +.Fn inet6_option_append "struct cmsghdr *cmsg" "const uint8_t *typep" "int multx" "int plusy" +.Ft "uint8_t *" +.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy" +.Ft "int" +.Fn inet6_option_next "const struct cmsghdr *cmsg" "uint8_t **tptrp" +.Ft "int" +.Fn inet6_option_find "const struct cmsghdr *cmsg" "uint8_t **tptrp" "int type" +.\" +.Sh DESCRIPTION +.\" +Building and parsing the Hop-by-Hop and Destination options is +complicated due to alignment constraints, padding and +ancillary data manipulation. +RFC 2292 defines a set of functions to help the application. +The function prototypes for +these functions are all in the +.In netinet/in.h +header. +.\" +.Ss inet6_option_space +.Fn inet6_option_space +returns the number of bytes required to hold an option when it is stored as +ancillary data, including the +.Li cmsghdr +structure at the beginning, +and any padding at the end +.Po +to make its size a multiple of 8 bytes +.Pc . +The argument is the size of the structure defining the option, +which must include any pad bytes at the beginning +.Po +the value +.Li y +in the alignment term +.Dq Li xn + y +.Pc , +the type byte, the length byte, and the option data. +.Pp +Note: If multiple options are stored in a single ancillary data +object, which is the recommended technique, this function +overestimates the amount of space required by the size of +.Li N-1 +.Li cmsghdr +structures, +where +.Li N +is the number of options to be stored in the object. +This is of little consequence, since it is assumed that most +Hop-by-Hop option headers and Destination option headers carry only +one option +.Pq appendix B of [RFC 2460] . +.\" +.Ss inet6_option_init +.Fn inet6_option_init +is called once per ancillary data object that will +contain either Hop-by-Hop or Destination options. +It returns +.Li 0 +on success or +.Li -1 +on an error. +.Pp +.Fa bp +is a pointer to previously allocated space that will contain the +ancillary data object. +It must be large enough to contain all the +individual options to be added by later calls to +.Fn inet6_option_append +and +.Fn inet6_option_alloc . +.Pp +.Fa cmsgp +is a pointer to a pointer to a +.Li cmsghdr +structure. +.Fa *cmsgp +is initialized by this function to point to the +.Li cmsghdr +structure constructed by this function in the buffer pointed to by +.Fa bp . +.Pp +.Fa type +is either +.Dv IPV6_HOPOPTS +or +.Dv IPV6_DSTOPTS . +This +.Fa type +is stored in the +.Li cmsg_type +member of the +.Li cmsghdr +structure pointed to by +.Fa *cmsgp . +.\" +.Ss inet6_option_append +This function appends a Hop-by-Hop option or a Destination option +into an ancillary data object that has been initialized by +.Fn inet6_option_init . +This function returns +.Li 0 +if it succeeds or +.Li -1 +on an error. +.Pp +.Fa cmsg +is a pointer to the +.Li cmsghdr +structure that must have been +initialized by +.Fn inet6_option_init . +.Pp +.Fa typep +is a pointer to the 8-bit option type. +It is assumed that this +field is immediately followed by the 8-bit option data length field, +which is then followed immediately by the option data. +The caller +initializes these three fields +.Pq the type-length-value, or TLV +before calling this function. +.Pp +The option type must have a value from +.Li 2 +to +.Li 255 , +inclusive. +.Po +.Li 0 +and +.Li 1 +are reserved for the +.Li Pad1 +and +.Li PadN +options, respectively. +.Pc +.Pp +The option data length must have a value between +.Li 0 +and +.Li 255 , +inclusive, and is the length of the option data that follows. +.Pp +.Fa multx +is the value +.Li x +in the alignment term +.Dq Li xn + y . +It must have a value of +.Li 1 , +.Li 2 , +.Li 4 , +or +.Li 8 . +.Pp +.Fa plusy +is the value +.Li y +in the alignment term +.Dq Li xn + y . +It must have a value between +.Li 0 +and +.Li 7 , +inclusive. +.\" +.Ss inet6_option_alloc +This function appends a Hop-by-Hop option or a Destination option +into an ancillary data object that has been initialized by +.Fn inet6_option_init . +This function returns a pointer to the 8-bit +option type field that starts the option on success, or +.Dv NULL +on an error. +.Pp +The difference between this function and +.Fn inet6_option_append +is that the latter copies the contents of a previously built option into +the ancillary data object while the current function returns a +pointer to the space in the data object where the option's TLV must +then be built by the caller. +.Pp +.Fa cmsg +is a pointer to the +.Li cmsghdr +structure that must have been +initialized by +.Fn inet6_option_init . +.Pp +.Fa datalen +is the value of the option data length byte for this option. +This value is required as an argument to allow the function to +determine if padding must be appended at the end of the option. +.Po +The +.Fn inet6_option_append +function does not need a data length argument +since the option data length must already be stored by the caller. +.Pc +.Pp +.Fa multx +is the value +.Li x +in the alignment term +.Dq Li xn + y . +It must have a value of +.Li 1 , +.Li 2 , +.Li 4 , +or +.Li 8 . +.Pp +.Fa plusy +is the value +.Li y +in the alignment term +.Dq Li xn + y . +It must have a value between +.Li 0 +and +.Li 7 , +inclusive. +.\" +.Ss inet6_option_next +This function processes the next Hop-by-Hop option or Destination +option in an ancillary data object. +If another option remains to be +processed, the return value of the function is +.Li 0 +and +.Fa *tptrp +points to +the 8-bit option type field +.Po +which is followed by the 8-bit option +data length, followed by the option data +.Pc . +If no more options remain +to be processed, the return value is +.Li -1 +and +.Fa *tptrp +is +.Dv NULL . +If an error occurs, the return value is +.Li -1 +and +.Fa *tptrp +is not +.Dv NULL . +.Pp +.Fa cmsg +is a pointer to +.Li cmsghdr +structure of which +.Li cmsg_level +equals +.Dv IPPROTO_IPV6 +and +.Li cmsg_type +equals either +.Dv IPV6_HOPOPTS +or +.Dv IPV6_DSTOPTS . +.Pp +.Fa tptrp +is a pointer to a pointer to an 8-bit byte and +.Fa *tptrp +is used +by the function to remember its place in the ancillary data object +each time the function is called. +The first time this function is +called for a given ancillary data object, +.Fa *tptrp +must be set to +.Dv NULL . +.Pp +Each time this function returns success, +.Fa *tptrp +points to the 8-bit +option type field for the next option to be processed. +.\" +.Ss inet6_option_find +This function is similar to the previously described +.Fn inet6_option_next +function, except this function lets the caller +specify the option type to be searched for, instead of always +returning the next option in the ancillary data object. +.Fa cmsg +is a +pointer to +.Li cmsghdr +structure of which +.Li cmsg_level +equals +.Dv IPPROTO_IPV6 +and +.Li cmsg_type +equals either +.Dv IPV6_HOPOPTS +or +.Dv IPV6_DSTOPTS . +.Pp +.Fa tptrp +is a pointer to a pointer to an 8-bit byte and +.Fa *tptrp +is used +by the function to remember its place in the ancillary data object +each time the function is called. +The first time this function is +called for a given ancillary data object, +.Fa *tptrp +must be set to +.Dv NULL . +.Pa +This function starts searching for an option of the specified type +beginning after the value of +.Fa *tptrp . +If an option of the specified +type is located, this function returns +.Li 0 +and +.Fa *tptrp +points to the 8- +bit option type field for the option of the specified type. +If an +option of the specified type is not located, the return value is +.Li -1 +and +.Fa *tptrp +is +.Dv NULL . +If an error occurs, the return value is +.Li -1 +and +.Fa *tptrp +is not +.Dv NULL . +.\" +.Sh EXAMPLES +RFC 2292 gives comprehensive examples in chapter 6. +.\" +.Sh RETURN VALUES +.Fn inet6_option_init +and +.Fn inet6_option_append +return +.Li 0 +on success or +.Li -1 +on an error. +.Pp +.Fn inet6_option_alloc +returns +.Dv NULL +on an error. +.Pp +On errors, +.Fn inet6_option_next +and +.Fn inet6_option_find +return +.Li -1 +setting +.Fa *tptrp +to non +.Dv NULL +value. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%T "Advanced Sockets API for IPv6" +.%N RFC 2292 +.%D February 1998 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC 2460 +.%D December 1998 +.Re +.\" +.Sh STANDARDS +The functions +are documented in +.Dq Advanced Sockets API for IPv6 +.Pq RFC 2292 . +.\" +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" +.Sh BUGS +The text was shamelessly copied from RFC 2292. diff --git a/static/netbsd/man3/inet6_rth_space.3 b/static/netbsd/man3/inet6_rth_space.3 new file mode 100644 index 00000000..eba76cf7 --- /dev/null +++ b/static/netbsd/man3/inet6_rth_space.3 @@ -0,0 +1,223 @@ +.\" $NetBSD: inet6_rth_space.3,v 1.4 2024/03/17 21:37:53 andvar Exp $ +.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ +.\" +.\" Copyright (C) 2004 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 24, 2004 +.Dt INET6_RTH_SPACE 3 +.Os +.\" +.Sh NAME +.Nm inet6_rth_space , +.Nm inet6_rth_init , +.Nm inet6_rth_add , +.Nm inet6_rth_reverse , +.Nm inet6_rth_segments , +.Nm inet6_rth_getaddr +.Nd IPv6 Routing Header Options manipulation +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft socklen_t +.Fn inet6_rth_space "int" "int" +.Ft "void *" +.Fn inet6_rth_init "void *" "socklen_t" "int" "int" +.Ft int +.Fn inet6_rth_add "void *" "const struct in6_addr *" +.Ft int +.Fn inet6_rth_reverse "const void *" "void *" +.Ft int +.Fn inet6_rth_segments "const void *" +.Ft "struct in6_addr *" +.Fn inet6_rth_getaddr "const void *" "int" +.\" +.Sh DESCRIPTION +The IPv6 Advanced API, RFC 3542, defines the functions that an +application calls to build and examine IPv6 Routing headers. +Routing headers are used to perform source routing in IPv6 networks. +The RFC uses the word +.Dq segments +to describe addresses and that is the term used here as well. +All of the functions are defined in the +.In netinet/in.h +header file. +The functions described in this manual page all operate +on routing header structures which are defined in +.In netinet/ip6.h +but which should not need to be modified outside the use of this API. +The size and shape of the route header structures may change, so using +the APIs is a more portable, long term, solution. +.Pp +The functions in the API are split into two groups, those that build a +routing header and those that parse a received routing header. +We will describe the builder functions followed by the parser functions. +.Ss inet6_rth_space +The +.Fn inet6_rth_space +function returns the number of bytes required to hold a Routing Header +of the type, specified in the +.Fa type +argument and containing the number of addresses specified in the +.Fa segments +argument. +When the type is +.Dv IPV6_RTHDR_TYPE_0 +the number of segments must be from 0 through 127. +Routing headers of type +.Dv IPV6_RTHDR_TYPE_2 +contain only one segment, and are only used with Mobile IPv6. +The return value from this function is the number of bytes required to +store the routing header. +If the value 0 is returned then either the +route header type was not recognized or another error occurred. +.Ss inet6_rth_init +The +.Fn inet6_rth_init +function initializes the pre-allocated buffer pointed to by +.Fa bp +to contain a routing header of the specified type The +.Fa bp_len +argument is used to verify that the buffer is large enough. +The caller must allocate the buffer pointed to by bp. +The necessary buffer size should be determined by calling +.Fn inet6_rth_space +described in the previous sections. +.Pp +The +.Fn inet6_rth_init +function returns a pointer to +.Fa bp +on success and +.Dv NULL +when there is an error. +.Ss inet6_rth_add +The +.Fn inet6_rth_add +function adds the IPv6 address pointed to by +.Fa addr +to the end of the routing header being constructed. +.Pp +A successful addition results in the function returning 0, otherwise +\-1 is returned. +.Ss inet6_rth_reverse +The +.Fn inet6_rth_reverse +function takes a routing header, pointed to by the +argument +.Fa in , +and writes a new routing header into the argument pointed to by +.Fa out . +The routing header at that sends datagrams along the reverse of that +route. +Both arguments are allowed to point to the same buffer meaning +that the reversal can occur in place. +.Pp +The return value of the function is 0 on success, or \-1 when +there is an error. +.\" +.Pp +The next set of functions operate on a routing header that the +application wants to parse. +In the usual case such a routing header +is received from the network, although these functions can also be +used with routing headers that the application itself created. +.Ss inet6_rth_segments +The +.Fn inet6_rth_segments +function returns the number of segments contained in the +routing header pointed to by +.Fa bp . +The return value is the number of segments contained in the routing +header, or \-1 if an error occurred. +It is not an error for 0 to be +returned as a routing header may contain 0 segments. +.\" +.Ss inet6_rth_getaddr +The +.Fn inet6_rth_getaddr +function is used to retrieve a single address from a routing header. +The +.Fa index +is the location in the routing header from which the application wants +to retrieve an address. +The +.Fa index +parameter must have a value between 0 and one less than the number of +segments present in the routing header. +The +.Fn inet6_rth_segments +function, described in the last section, should be used to determine +the total number of segments in the routing header. +The +.Fn inet6_rth_getaddr +function returns a pointer to an IPv6 address on success or +.Dv NULL +when an error has occurred. +.\" +.Sh EXAMPLES +RFC 3542 gives extensive examples in Section 21, Appendix B. +.Pp +KAME also provides examples in the advapitest directory of its kit. +.\" +.Sh RETURN VALUES +The +.Fn inet6_rth_space +and +.Fn inet6_rth_getaddr +functions return 0 on errors. +.Pp +The +.Fn inet6_rthdr_init +function returns +.Dv NULL +on error. +The +.Fn inet6_rth_add +and +.Fn inet6_rth_reverse +functions return 0 on success, or \-1 upon an error. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets API for IPv6" +.%N RFC 3542 +.%D May 2003 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC2460 +.%D December 1998 +.Re +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. diff --git a/static/netbsd/man3/inet6_rthdr_space.3 b/static/netbsd/man3/inet6_rthdr_space.3 new file mode 100644 index 00000000..8c7e0c3a --- /dev/null +++ b/static/netbsd/man3/inet6_rthdr_space.3 @@ -0,0 +1,321 @@ +.\" $NetBSD: inet6_rthdr_space.3,v 1.4 2022/12/04 01:29:32 uwe Exp $ +.\" $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun Exp $ +.\" +.\" Copyright (c) 1983, 1987, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 10, 1999 +.Dt INET6_RTHDR_SPACE 3 +.Os +.\" +.Sh NAME +.Nm inet6_rthdr_space , +.Nm inet6_rthdr_init , +.Nm inet6_rthdr_add , +.Nm inet6_rthdr_lasthop , +.Nm inet6_rthdr_reverse , +.Nm inet6_rthdr_segments , +.Nm inet6_rthdr_getaddr , +.Nm inet6_rthdr_getflags +.Nd IPv6 Routing Header Options manipulation +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft size_t +.Fn inet6_rthdr_space "int type" "int segments" +.Ft "struct cmsghdr *" +.Fn inet6_rthdr_init "void *bp" "int type" +.Ft int +.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" +.Ft int +.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" +.Ft int +.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" +.Ft int +.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" +.Ft "struct in6_addr *" +.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" +.Ft int +.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" +.\" +.Sh DESCRIPTION +RFC 2292 IPv6 advanced API defines eight +functions that the application calls to build and examine a Routing +header. +Four functions build a Routing header: +.Bl -hang +.It Fn inet6_rthdr_space +return #bytes required for ancillary data +.It Fn inet6_rthdr_init +initialize ancillary data for Routing header +.It Fn inet6_rthdr_add +add IPv6 address & flags to Routing header +.It Fn inet6_rthdr_lasthop +specify the flags for the final hop +.El +.Pp +Four functions deal with a returned Routing header: +.Bl -hang +.It Fn inet6_rthdr_reverse +reverse a Routing header +.It Fn inet6_rthdr_segments +return #segments in a Routing header +.It Fn inet6_rthdr_getaddr +fetch one address from a Routing header +.It Fn inet6_rthdr_getflags +fetch one flag from a Routing header +.El +.Pp +The function prototypes for these functions are all in the +.In netinet/in.h +header. +.\" +.Ss inet6_rthdr_space +This function returns the number of bytes required to hold a Routing +header of the specified +.Fa type +containing the specified number of +.Fa segments +.Pq addresses . +For an IPv6 Type 0 Routing header, the number +of segments must be between 1 and 23, inclusive. +The return value +includes the size of the cmsghdr structure that precedes the Routing +header, and any required padding. +.Pp +If the return value is 0, then either the type of the Routing header +is not supported by this implementation or the number of segments is +invalid for this type of Routing header. +.Pp +Note: This function returns the size but does not allocate the space +required for the ancillary data. +This allows an application to +allocate a larger buffer, if other ancillary data objects are +desired, since all the ancillary data objects must be specified to +.Xr sendmsg 2 +as a single +.Li msg_control +buffer. +.\" +.Ss inet6_rthdr_init +This function initializes the buffer pointed to by +.Fa bp +to contain a +.Li cmsghdr +structure followed by a Routing header of the specified +.Fa type . +The +.Li cmsg_len +member of the +.Li cmsghdr +structure is initialized to the +size of the structure plus the amount of space required by the +Routing header. +The +.Li cmsg_level +and +.Li cmsg_type +members are also initialized as required. +.Pp +The caller must allocate the buffer and its size can be determined by +calling +.Fn inet6_rthdr_space . +.Pp +Upon success the return value is the pointer to the +.Li cmsghdr +structure, and this is then used as the first argument to the next +two functions. +Upon an error the return value is +.Dv NULL . +.\" +.Ss inet6_rthdr_add +This function adds the address pointed to by +.Fa addr +to the end of the +Routing header being constructed and sets the type of this hop to the +value of +.Fa flags . +For an IPv6 Type 0 Routing header, +.Fa flags +must be +either +.Dv IPV6_RTHDR_LOOSE +or +.Dv IPV6_RTHDR_STRICT . +.Pp +If successful, the +.Li cmsg_len +member of the +.Li cmsghdr +structure is +updated to account for the new address in the Routing header and the +return value of the function is 0. +Upon an error the return value of +the function is -1. +.\" +.Ss inet6_rthdr_lasthop +This function specifies the Strict/Loose flag for the final hop of a +Routing header. +For an IPv6 Type 0 Routing header, +.Fa flags +must be either +.Dv IPV6_RTHDR_LOOSE +or +.Dv IPV6_RTHDR_STRICT . +.Pp +The return value of the function is 0 upon success, or -1 upon an error. +.Pp +Notice that a Routing header specifying +.Li N +intermediate nodes requires +.Li N+1 +Strict/Loose flags. +This requires +.Li N +calls to +.Fn inet6_rthdr_add +followed by one call to +.Fn inet6_rthdr_lasthop . +.\" +.Ss inet6_rthdr_reverse +This function takes a Routing header that was received as ancillary +data +.Po +pointed to by the first argument, +.Fa in +.Pc +and writes a new Routing +header that sends datagrams along the reverse of that route. +Both +arguments are allowed to point to the same buffer +.Pq that is, the reversal can occur in place . +.Pp +The return value of the function is 0 on success, or -1 upon an +error. +.\" +.Ss inet6_rthdr_segments +This function returns the number of segments +.Pq addresses +contained in +the Routing header described by +.Fa cmsg . +On success the return value is +between 1 and 23, inclusive. +The return value of the function is -1 upon an error. +.\" +.Ss inet6_rthdr_getaddr +This function returns a pointer to the IPv6 address specified by +.Fa index +.Po +which must have a value between 1 and the value returned by +.Fn inet6_rthdr_segments +.Pc +in the Routing header described by +.Fa cmsg . +An +application should first call +.Fn inet6_rthdr_segments +to obtain the number of segments in the Routing header. +.Pp +Upon an error the return value of the function is +.Dv NULL . +.\" +.Ss inet6_rthdr_getflags +This function returns the flags value specified by +.Fa index +.Po +which must +have a value between 0 and the value returned by +.Fn inet6_rthdr_segments +.Pc +in the Routing header described by +.Fa cmsg . +For an IPv6 Type 0 Routing header the return value will be either +.Dv IPV6_RTHDR_LOOSE +or +.Dv IPV6_RTHDR_STRICT . +.Pp +Upon an error the return value of the function is -1. +.Pp +Note: Addresses are indexed starting at 1, and flags starting at 0, +to maintain consistency with the terminology and figures in RFC 2460. +.\" +.Sh EXAMPLES +RFC 2292 gives comprehensive examples in chapter 8. +.\" +.Sh RETURN VALUES +.Fn inet6_rthdr_space +returns 0 on errors. +.Pp +.Fn inet6_rthdr_add , +.Fn inet6_rthdr_lasthop +and +.Fn inet6_rthdr_reverse +return 0 on success, and returns -1 on error. +.Pp +.Fn inet6_rthdr_init +and +.Fn inet6_rthdr_getaddr +return +.Dv NULL +on error. +.Pp +.Fn inet6_rthdr_segments +and +.Fn inet6_rthdr_getflags +return -1 on error. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%T "Advanced Sockets API for IPv6" +.%N RFC 2292 +.%D February 1998 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC 2460 +.%D December 1998 +.Re +.\" +.Sh STANDARDS +The functions +are documented in +.Dq Advanced Sockets API for IPv6 +.Pq RFC 2292 . +.\" +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. +.\" +.Sh BUGS +The text was shamelessly copied from RFC 2292. +.Pp +.Fn inet6_rthdr_reverse +is not implemented yet. diff --git a/static/netbsd/man3/inet_cidr.3 b/static/netbsd/man3/inet_cidr.3 new file mode 100644 index 00000000..f8bbf866 --- /dev/null +++ b/static/netbsd/man3/inet_cidr.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: inet_cidr.3,v 1.1.1.2 2012/09/09 16:07:46 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: inet_cidr.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd October 19, 1998 +.Dt INET_CIDR @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm inet_cidr_ntop , +.Nm inet_cidr_pton +.Nd network translation routines +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fn inet_cidr_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size" +.Fn inet_cidr_pton "int af" "const char *src" "void *dst" "int *bits" +.Sh DESCRIPTION +These routines are used for converting addresses to and from network and +presentation forms with CIDR (Classless Inter-Domain Routing) representation, +embedded net mask. +.Pp +.Bd -literal + 130.155.16.1/20 +.Ed +.\" ::ffff:130.155.16.1/116 +.Pp +.Fn inet_cidr_ntop +converts an address from network to presentation format. +.Pp +.Ft af +describes the type of address that is being passed in +.Ft src . +.\"Currently defined types are AF_INET and AF_INET6. +Currently only AF_INET is supported. +.Pp +.Ft src +is an address in network byte order, its length is determined from +.Ft af . +.Pp +.Ft bits +specifies the number of bits in the netmask unless it is -1 in which case +the CIDR representation is omitted. +.Pp +.Ft dst +is a caller supplied buffer of at least +.Ft size +bytes. +.Pp +.Fn inet_cidr_ntop +returns +.Ft dst +on success or NULL. +Check errno for reason. +.Pp +.Fn inet_cidr_pton +converts and address from presentation format, with optional CIDR +reperesentation, to network format. +The resulting address is zero filled if there were insufficint bits in +.Ft src . +.Pp +.Ft af +describes the type of address that is being passed in via +.Ft src +and determines the size of +.Ft dst . +.Pp +.Ft src +is an address in presentation format. +.Pp +.Ft bits +returns the number of bits in the netmask or -1 if a CIDR representation was +not supplied. +.Pp +.Fn inet_cidr_pton +returns 0 on succces or -1 on error. +Check errno for reason. +ENOENT indicates an invalid netmask. +.Sh SEE ALSO +.Xr intro 2 diff --git a/static/netbsd/man3/inet_net.3 b/static/netbsd/man3/inet_net.3 new file mode 100644 index 00000000..3d9b6ef5 --- /dev/null +++ b/static/netbsd/man3/inet_net.3 @@ -0,0 +1,198 @@ +.\" $NetBSD: inet_net.3,v 1.5 2012/07/20 20:48:59 wiz Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 20, 2012 +.Dt INET_NET 3 +.Os +.Sh NAME +.Nm inet_net_ntop , +.Nm inet_net_pton +.Nd Internet network number manipulation routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.In arpa/inet.h +.Ft char * +.Fn inet_net_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size" +.Ft int +.Fn inet_net_pton "int af" "const char *src" "void *dst" "size_t size" +.Sh DESCRIPTION +The +.Fn inet_net_ntop +function converts an Internet network number from network format (usually a +.Vt struct in_addr +or some other binary form, in network byte order) to CIDR presentation format +(suitable for external display purposes). +The +.Fa bits +argument is the number of bits in +.Fa src +that are the network number. +It returns +.Dv NULL +if an error occurs (in which case +.Va errno +will have been set), or it returns a pointer to the destination string. +.Pp +The +.Fn inet_net_pton +function converts a presentation format Internet network number (that is, +printable form as held in a character string) to network format (usually a +.Vt struct in_addr +or some other internal binary representation, in network byte order). +It returns the number of bits (either computed based on the class, or +specified with /CIDR), or \-1 if a failure occurred +(in which case +.Va errno +will have been set). +.Pp +The currently supported values for +.Fa af +are +.Dv AF_INET +and +.Dv AF_INET6 . +The +.Fa size +argument is the size of the result buffer +.Fa dst . +.Sh NETWORK NUMBERS (IP VERSION 4) +Internet network numbers may be specified in one of the following forms: +.Bd -literal -offset indent +a.b.c.d/bits +a.b.c.d +a.b.c +a.b +a +.Ed +.Pp +When four parts are specified, each is interpreted +as a byte of data and assigned, from left to right, +to the four bytes of an Internet network number. +Note that when an Internet network number is viewed as a 32-bit +integer quantity on a system that uses little-endian +byte order (such as the +.Tn Intel 386 , 486 , +and +.Tn Pentium +processors) the bytes referred to above appear as +.Dq Li d.c.b.a . +That is, little-endian bytes are ordered from right to left. +.Pp +When a three part number is specified, the last +part is interpreted as a 16-bit quantity and placed +in the rightmost two bytes of the Internet network number. +This makes the three part number format convenient +for specifying Class B network numbers as +.Dq Li 128.net.host . +.Pp +When a two part number is supplied, the last part +is interpreted as a 24-bit quantity and placed in +the rightmost three bytes of the Internet network number. +This makes the two part number format convenient +for specifying Class A network numbers as +.Dq Li net.host . +.Pp +When only one part is given, the value is stored +directly in the Internet network number without any byte +rearrangement. +.Pp +All numbers supplied as +.Dq parts +in a +.Ql \&. +notation +may be decimal, octal, or hexadecimal, as specified +in the C language (i.e., a leading 0x or 0X implies +hexadecimal; otherwise, a leading 0 implies octal; +otherwise, the number is interpreted as decimal). +.\" +.\" .Sh NETWORK NUMBERS (IP VERSION 6) +.\" XXX - document this! +.\" +.Sh ERRORS +The +.Fn inet_net_ntop +and +.Fn inet_net_pton +functions may fail with +.Bl -tag -width Er +.It Bq Er EAFNOSUPPORT +The value of +.Fa af +was not +.Dv AF_INET +or +.Dv AF_INET6 . +.It Bq Er EMSGSIZE +The conversion of +.Fa src +overflows +.Fa size +of +.Fa dst . +.El +.Pp +The +.Fn inet_net_ntop +function may fail with +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa bits +argument contains an invalid number of bits +for the requested address family. +.El +.Pp +The +.Fn inet_net_pton +function may fail with +.Bl -tag -width Er +.It Bq Er ENOENT +The +.Fa src +was not a valid Internet network number. +.El +.Sh SEE ALSO +.Xr byteorder 3 , +.Xr inet 3 , +.Xr networks 5 +.Sh HISTORY +The +.Fn inet_net_ntop +and +.Fn inet_net_pton +functions appeared in BIND 4.9.4 and thence +.Nx 1.3 . +Support for +.Dv AF_INET6 +appeared in +.Nx 1.6 . diff --git a/static/netbsd/man3/init_db.3 b/static/netbsd/man3/init_db.3 new file mode 100644 index 00000000..92243200 --- /dev/null +++ b/static/netbsd/man3/init_db.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: init_db.3,v 1.4 2022/09/11 20:32:37 gutteridge Exp $ +.\" +.\" Copyright (c) 2011 Abhinav Upadhyay +.\" All rights reserved. +.\" +.\" This code was developed as part of Google's Summer of Code 2011 program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 22, 2016 +.Dt INIT_DB 3 +.Os +.Sh NAME +.Nm init_db +.Nd open apropos database connection +.Sh SYNOPSIS +.In apropos-utils.h +.Ft sqlite3 * +.Fn init_db "mandb_access_mode db_flag" "const char *manconf" +.Sh DESCRIPTION +The +.Fn init_db +function will try to initialize a connection to +.Pa man.db +which is an +SQLite database and return a pointer to a sqlite3 structure. +The connection should subsequentially be closed by calling +.Fn close_db +which will also release any resources being used by it. +.Pp +The argument +.Fa db_flag +can be one of the following: +.Bl -hang -width -compact +.It Dv MANDB_READONLY +This will open the database in read-only mode. +Use this when you only want to query the database. +.It Dv MANDB_WRITE +This will open the database in read/write mode. +.It Dv MANDB_CREATE +This will open the database in read/write mode, and will also create +the database schema if it does not exist already. +.El +.Pp +The second argument +.Fa manconf +specifies the location of the man.conf configuration file. +By default it is stored at +.Pa /etc/man.conf . +The location of the man.db database is configured in the configuration file +using the +.Cd _mandb +tag. +.Sh RETURN VALUES +On successful execution the +.Fn init_db +function will return a pointer to a sqlite3 structure which represents +a connection to the database. +.Pp +In case the man.db file does not exist and +.Dv DB_CREATE +is not used as a value of +.Fa db_flag , +.Dv NULL +will be returned. +.Sh FILES +.Bl -hang -width /etc/man.conf -compact +.It Pa /etc/man.conf +The location of the SQLite FTS database can be configured using the +.Cd _mandb +tag. +.El +.Sh SEE ALSO +.Xr apropos-utils 3 , +.Xr close_db 3 , +.Xr run_query 3 +.Sh AUTHORS +.An Abhinav Upadhyay diff --git a/static/netbsd/man3/initgroups.3 b/static/netbsd/man3/initgroups.3 new file mode 100644 index 00000000..56e52a4f --- /dev/null +++ b/static/netbsd/man3/initgroups.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: initgroups.3,v 1.15 2003/08/07 16:42:51 agc Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)initgroups.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd August 10, 2002 +.Dt INITGROUPS 3 +.Os +.Sh NAME +.Nm initgroups +.Nd initialize supplementary group IDs +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn initgroups "const char *name" "gid_t basegid" +.Sh DESCRIPTION +The +.Fn initgroups +function +uses the +.Xr getgrouplist 3 +function to calculate the supplementary group IDs for the user +specified in +.Fa name . +This group list is then set up for the current process using +.Xr setgroups 2 . +The +.Fa basegid +is automatically included in the group list. +Typically this value is given as +the group number from the password file. +.Pp +If the groups database lists more than +.Ev NGROUPS +groups for +.Fa name +(including one for +.Fa basegid ) , +the later groups are ignored. +.Sh RETURN VALUES +The +.Fn initgroups +function +returns \-1 if it was not invoked by the super-user. +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr getgrouplist 3 +.Sh HISTORY +The +.Fn initgroups +function appeared in +.Bx 4.2 . +.Sh BUGS +The +.Fn getgrouplist +function called by +.Fn initgroups +uses the routines based on +.Xr getgrent 3 . +If the invoking program uses any of these routines, +the group structure will +be overwritten in the call to +.Fn initgroups . diff --git a/static/netbsd/man3/insque.3 b/static/netbsd/man3/insque.3 new file mode 100644 index 00000000..fdb86b7d --- /dev/null +++ b/static/netbsd/man3/insque.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1993 John Brezak +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR `AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $NetBSD: insque.3,v 1.5 2010/04/30 10:24:02 jruoho Exp $ +.\" +.Dd April 30, 2010 +.Dt INSQUE 3 +.Os +.Sh NAME +.Nm insque , +.Nm remque +.Nd insert/remove element from a queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In search.h +.Ft void +.Fn insque "void *elem" "void *pred" +.Ft void +.Fn remque "void *elem" +.Sh DESCRIPTION +.Fn insque +and +.Fn remque +manipulate queues built from doubly linked lists. +The queue can be either circular or linear. +The functions expect their +arguments to point to a structure whose first and second members are +pointers to the next and previous element, respectively. +The +.Fn insque +function also allows the +.Fa pred +argument to be a +.Dv NULL +pointer for the initialization of a new linear list's +head element. +.Sh STANDARDS +The +.Fn insque +and +.Fn remque +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn insque +and +.Fn remque +are derived from the +.Sq insque +and +.Sq remque +instructions on the +.Tn VAX . +They first appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/internal_v_smechname.3 b/static/netbsd/man3/internal_v_smechname.3 new file mode 100644 index 00000000..8446bd54 --- /dev/null +++ b/static/netbsd/man3/internal_v_smechname.3 @@ -0,0 +1,22 @@ +.\" $NetBSD: internal_v_smechname.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "internal_v_smechname" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal GSS-API library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +internal_v_smechname \- Internal names and mechanism names + +.SH "Name forms" +.PP +There are two name representations in GSS-API: Internal form and Contiguous string ('flat') form\&. Functions \fBgss_export_name()\fP and \fBgss_import_name()\fP can be used to convert between the two forms\&. +.PP +.IP "\(bu" 2 +The contiguous string form is described by an oid specificing the type and an octet string\&. A special form of the contiguous string form is the exported name object\&. The exported name defined for each mechanism, is something that can be stored and compared later\&. The exported name is what should be used for ACLs comparisons\&. +.IP "\(bu" 2 +The Internal form is opaque to the application programmer and is implementation-dependent\&. +.IP "\(bu" 2 +There is also a special form of the Internal Name (IN), and that is the Mechanism Name (MN)\&. In the mechanism name all the generic information is stripped of and only contain the information for one mechanism\&. In GSS-API some function return MN and some require MN as input\&. Each of these function is marked up as such\&. +.PP +.PP +@FIXME Describe relationship between import_name, canonicalize_name, export_name and friends\&. Also, update for RFC2743 language ('contiguous' and 'flat' are gone, leaving just 'exported name +token', 'internal', and 'MN')\&. diff --git a/static/netbsd/man3/ipsec_set_policy.3 b/static/netbsd/man3/ipsec_set_policy.3 new file mode 100644 index 00000000..574b3100 --- /dev/null +++ b/static/netbsd/man3/ipsec_set_policy.3 @@ -0,0 +1,310 @@ +.\" $NetBSD: ipsec_set_policy.3,v 1.18 2012/01/04 16:30:50 wiz Exp $ +.\" +.\" $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 4, 2012 +.Dt IPSEC_SET_POLICY 3 +.Os +.Sh NAME +.Nm ipsec_set_policy , +.Nm ipsec_get_policylen , +.Nm ipsec_dump_policy +.Nd manipulate IPsec policy specification structure from human-readable policy string +.\" +.Sh LIBRARY +.Lb libipsec +.Sh SYNOPSIS +.In netipsec/ipsec.h +.Ft "char *" +.Fn ipsec_set_policy "const char *policy" "int len" +.Ft int +.Fn ipsec_get_policylen "char *buf" +.Ft "char *" +.Fn ipsec_dump_policy "char *buf" "const char *delim" +.Sh DESCRIPTION +.Fn ipsec_set_policy +generates an IPsec policy specification structure, namely +.Li struct sadb_x_policy +and/or +.Li struct sadb_x_ipsecrequest +from a human-readable policy specification. +The policy specification must be given as a C string +.Fa policy +and its length +.Fa len . +.Fn ipsec_set_policy +will return a buffer with the corresponding IPsec policy specification structure. +The buffer is dynamically allocated, and must be +.Xr free 3 Ap d +by the caller. +.Pp +You can get the length of the generated buffer with +.Fn ipsec_get_policylen +(i.e. for calling +.Xr setsockopt 2 ) . +.Pp +.Fn ipsec_dump_policy +converts an IPsec policy structure into human-readable form. +Therefore, +.Fn ipsec_dump_policy +can be regarded as the inverse function to +.Fn ipsec_set_policy . +.Fa buf +points to an IPsec policy structure, +.Li struct sadb_x_policy . +.Fa delim +is a delimiter string, which is usually a blank character. +If you set +.Fa delim +to +.Dv NULL , +a single whitespace is assumed. +.Fn ipsec_dump_policy +returns a pointer to a dynamically allocated string. +It is the caller's responsibility to +.Xr free 3 +it. +.Pp +.Fa policy +is formatted as either of the following: +.Bl -tag -width "discard" +.It Ar direction [priority specification] Li discard +.Ar direction +must be +.Li in , +.Li out , +or +.Li fwd . +.Ar direction +specifies in which direction the policy needs to be applied. +The non-standard direction +.Li fwd +is substituted with +.Li in +on platforms which do not support forward policies. +.Pp +.Ar priority specification +is used to control the placement of the policy within the SPD. +The policy position is determined by +a signed integer where higher priorities indicate the policy is placed +closer to the beginning of the list and lower priorities indicate the +policy is placed closer to the end of the list. +Policies with equal +priorities are added at the end of the group of such policies. +.Pp +Priority can only +be specified when libipsec has been compiled against kernel headers that +support policy priorities (Linux \*[Gt]= 2.6.6). +It takes one of the following formats: +.Bl -tag -width "discard" +.It Ar {priority,prio} offset +.Ar offset +is an integer in the range \-2147483647..214783648. +.It Ar {priority,prio} base {+,-} offset +.Ar base +is either +.Li low (-1073741824) , +.Li def (0) , +or +.Li high (1073741824) . +.Pp +.Ar offset +is an unsigned integer. +It can be up to 1073741824 for +positive offsets, and up to 1073741823 for negative offsets. +.El +.Pp +The interpretation of policy priority in these functions and the +kernel DOES differ. +The relationship between the two can be described as +p(kernel) = 0x80000000 - p(func) +.Pp +With +.Li discard +policy, packets will be dropped if they match the policy. +.It Ar direction [priority specification] Li entrust +.Li entrust +means to consult the SPD defined by +.Xr setkey 8 . +.It Ar direction [priority specification] Li bypass +.Li bypass +means to bypass the IPsec processing. +.Pq the packet will be transmitted in clear . +This is for privileged sockets. +.It Ar direction Bo Ar priority specification Bc Li ipsec Ar request ... +.Li ipsec +means that the matching packets are subject to IPsec processing. +.Li ipsec +can be followed by one or more +.Ar request +strings, which are formatted as below: +.Bl -tag -width "discard" +.It Ar protocol Li / Ar mode Li / Ar src Li - Ar dst Op Ar /level +.Ar protocol +is either +.Li ah , +.Li esp , +or +.Li ipcomp . +.Pp +.Ar mode +is either +.Li transport +or +.Li tunnel . +.Pp +.Ar src +and +.Ar dst +specifies the IPsec endpoint. +.Ar src +always means the +.Dq sending node +and +.Ar dst +always means the +.Dq receiving node . +Therefore, when +.Ar direction +is +.Li in , +.Ar dst +is this node +and +.Ar src +is the other node +.Pq peer . +If +.Ar mode +is +.Li transport , +Both +.Ar src +and +.Ar dst +can be omitted. +.Pp +.Ar level +must be set to one of the following: +.Li default , use , require , +or +.Li unique . +.Li default +means that the kernel should consult the system default policy +defined by +.Xr sysctl 8 , +such as +.Li net.inet.ipsec.esp_trans_deflev . +See +.Xr ipsec 4 +regarding the system default. +.Li use +means that a relevant SA can be used when available, +since the kernel may perform IPsec operation against packets when possible. +In this case, packets can be transmitted in clear +.Pq when SA is not available , +or encrypted +.Pq when SA is available . +.Li require +means that a relevant SA is required, +since the kernel must perform IPsec operation against packets. +.Li unique +is the same as +.Li require , +but adds the restriction that the SA for outbound traffic is used +only for this policy. +You may need the identifier in order to relate the policy and the SA +when you define the SA by manual keying. +You can put the decimal number as the identifier after +.Li unique +like +.Li unique : number . +.Li number +must be between 1 and 32767 . +If the +.Ar request +string is kept unambiguous, +.Ar level +and slash prior to +.Ar level +can be omitted. +However, it is encouraged to specify them explicitly +to avoid unintended behavior. +If +.Ar level +is omitted, it will be interpreted as +.Li default . +.El +.Pp +Note that there are slight differences to the specification of +.Xr setkey 8 . +In the specification of +.Xr setkey 8 , +both +.Li entrust +and +.Li bypass +are not used. +Refer to +.Xr setkey 8 +for details. +.Pp +Here are several examples +.Pq long lines are wrapped for readability : +.Bd -literal -offset indent +in discard +out ipsec esp/transport//require +in ipsec ah/transport//require +out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use +in ipsec ipcomp/transport//use + esp/transport//use +.Ed +.El +.Sh RETURN VALUES +.Fn ipsec_set_policy +returns a pointer to the allocated buffer with the policy specification +if successful; otherwise a +.Dv NULL +pointer is returned. +.Fn ipsec_get_policylen +returns a positive value +.Pq meaning the buffer size +on success, and a negative value on errors. +.Fn ipsec_dump_policy +returns a pointer to a dynamically allocated region on success, +and +.Dv NULL +on errors. +.Sh SEE ALSO +.Xr ipsec_strerror 3 , +.Xr ipsec 4 , +.Xr setkey 8 +.Sh HISTORY +The functions first appeared in the WIDE/KAME IPv6 protocol stack kit. diff --git a/static/netbsd/man3/ipsec_strerror.3 b/static/netbsd/man3/ipsec_strerror.3 new file mode 100644 index 00000000..774f27c7 --- /dev/null +++ b/static/netbsd/man3/ipsec_strerror.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: ipsec_strerror.3,v 1.13 2018/09/06 09:38:05 maxv Exp $ +.\" +.\" $KAME: ipsec_strerror.3,v 1.9 2001/08/17 07:21:36 itojun Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 6, 2018 +.Dt IPSEC_STRERROR 3 +.Os +.\" +.Sh NAME +.Nm ipsec_strerror +.Nd error messages for the IPsec policy manipulation library +.\" +.Sh LIBRARY +.Lb libipsec +.Sh SYNOPSIS +.In netipsec/ipsec.h +.Ft "const char *" +.Fn ipsec_strerror void +.\" +.Sh DESCRIPTION +.Fn ipsec_strerror +can be used to obtain the error message string for the error code. +.Pp +Since +.Fn ipsec_strerror +uses +.Xr strerror 3 +as underlying function, calling +.Xr strerror 3 +after +.Fn ipsec_strerror +will make the return value from +.Fn ipsec_strerror +invalid or overwritten. +.\" +.Sh RETURN VALUES +.Fn ipsec_strerror +always returns a pointer to a C string. +The C string must not be overwritten by the calling program. +.\" +.Sh SEE ALSO +.Xr ipsec_set_policy 3 +.\" +.Sh HISTORY +.Fn ipsec_strerror +first appeared in the WIDE/KAME IPv6 protocol stack kit. +.\" +.Sh BUGS +.Fn ipsec_strerror +will return its result which may be overwritten by subsequent calls. +.Pp +.Va ipsec_errcode +is not thread safe. diff --git a/static/netbsd/man3/ipv6.3 b/static/netbsd/man3/ipv6.3 new file mode 100644 index 00000000..3b2ef4d3 --- /dev/null +++ b/static/netbsd/man3/ipv6.3 @@ -0,0 +1,30 @@ +[out,gif0] +6000 0000 0010 3a40 3ffe 8280 0000 2001 +0000 0000 0000 4395 3ffe 8280 0000 2001 +0000 0000 0000 4394 8000 3f77 085c 0038 +0c06 b73d 1b3d 0d00 + +[in,gif0] +6000 0000 0010 3a40 3ffe 8280 0000 2001 +0000 0000 0000 4393 3ffe 8280 0000 2001 +0000 0000 0000 4395 8100 3e78 085c 0038 +0c06 b73d 1b3d 0d00 + +[in,gif0] +6000 0000 0010 3a40 3ffe 8280 0000 2001 +0000 0000 0000 4394 3ffe 8280 0000 2001 +0000 0000 0000 4395 8300 3c77 085c 0038 +0c06 b73d 1b3d 0d00 + +[in,gif0] +6000 0000 0010 3a40 3ffe 8280 0000 2001 +0000 0000 0000 4394 3ffe 8280 0000 2001 +0000 0000 0000 4395 8000 3f77 085c 0038 +0c06 b73d 1b3d 0d00 + +[in,gif0] +6000 0000 0010 3a40 3ffe 8280 0000 2001 +0000 0000 0000 4394 3ffe 8280 0000 2001 +0000 0000 0000 4395 8100 3e77 085c 0038 +0c06 b73d 1b3d 0d00 + diff --git a/static/netbsd/man3/isalnum.3 b/static/netbsd/man3/isalnum.3 new file mode 100644 index 00000000..53d6ec08 --- /dev/null +++ b/static/netbsd/man3/isalnum.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: isalnum.3,v 1.15 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isalnum.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISALNUM 3 +.Os +.Sh NAME +.Nm isalnum +.Nd alphanumeric character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isalnum "int c" +.Sh DESCRIPTION +The +.Fn isalnum +function tests for any character for which +.Xr isalpha 3 +or +.Xr isdigit 3 +is true. +.Sh RETURN VALUES +The +.Fn isalnum +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isalnum +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isalnum +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isalpha.3 b/static/netbsd/man3/isalpha.3 new file mode 100644 index 00000000..51c9022a --- /dev/null +++ b/static/netbsd/man3/isalpha.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: isalpha.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isalpha.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISALPHA 3 +.Os +.Sh NAME +.Nm isalpha +.Nd alphabetic character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isalpha "int c" +.Sh DESCRIPTION +The +.Fn isalpha +function tests for any character for which +.Xr isupper 3 +or +.Xr islower 3 +is true and +.\" , or any of an implementation-defined set of characters +for which none of +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +In the +.Em ``C'' +locale, +.Fn isalpha +returns true only for the characters for which +.Xr isupper 3 +or +.Xr islower 3 +is true. +.Sh RETURN VALUES +The +.Fn isalpha +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isalpha +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isalpha +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isascii.3 b/static/netbsd/man3/isascii.3 new file mode 100644 index 00000000..7f0f714b --- /dev/null +++ b/static/netbsd/man3/isascii.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: isascii.3,v 1.19 2021/02/21 16:33:22 rillig Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isascii.3 5.1 (Berkeley) 5/2/91 +.\" +.Dd February 21, 2021 +.Dt ISASCII 3 +.Os +.Sh NAME +.Nm isascii +.Nd test for ASCII character +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isascii "int c" +.Sh DESCRIPTION +The +.Fn isascii +function tests for an +.Tn ASCII +character, which is any character with a value in the +range from 0 to 127, inclusive. +.Pp +The +.Fn isascii +function is defined on all integer values. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isascii +function conforms to +.St -xpg4 +and +.St -p1003.1-2001 . +The +.St -p1003.1-2008 +revision however marked it as obsolete, noting that +.Fn isascii +cannot be used portably in a localized application. diff --git a/static/netbsd/man3/isblank.3 b/static/netbsd/man3/isblank.3 new file mode 100644 index 00000000..59a5ca16 --- /dev/null +++ b/static/netbsd/man3/isblank.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: isblank.3,v 1.13 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isspace.3 5.3 (Berkeley) 7/31/91 +.\" +.Dd April 17, 2008 +.Dt ISBLANK 3 +.Os +.Sh NAME +.Nm isblank +.Nd blank-space character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isblank "int c" +.Sh DESCRIPTION +The +.Fn isblank +function tests for the standard blank-space characters. +The standard blank-space characters are the following: +.Pp +.Bl -tag -width xxxxx -offset indent -compact +.It Sq \0 +Space character. +.It Li \et +Horizontal tab. +.El +.Pp +In the +.Em ``C'' +locale, +.Fn isblank +returns true only for the standard blank-space characters. +.Sh RETURN VALUES +The +.Fn isblank +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh CAVEATS +The argument to +.Fn isblank +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/iscntrl.3 b/static/netbsd/man3/iscntrl.3 new file mode 100644 index 00000000..efea8f8b --- /dev/null +++ b/static/netbsd/man3/iscntrl.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: iscntrl.3,v 1.13 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)iscntrl.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISCNTRL 3 +.Os +.Sh NAME +.Nm iscntrl +.Nd control character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn iscntrl "int c" +.Sh DESCRIPTION +The +.Fn iscntrl +function tests for any control character. +.Sh RETURN VALUES +The +.Fn iscntrl +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn iscntrl +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn iscntrl +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isdigit.3 b/static/netbsd/man3/isdigit.3 new file mode 100644 index 00000000..80e297c3 --- /dev/null +++ b/static/netbsd/man3/isdigit.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: isdigit.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isdigit.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISDIGIT 3 +.Os +.Sh NAME +.Nm isdigit +.Nd decimal-digit character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isdigit "int c" +.Sh DESCRIPTION +The +.Fn isdigit +function tests for any decimal-digit character. +.Sh RETURN VALUES +The +.Fn isdigit +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isdigit +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isdigit +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isfinite.3 b/static/netbsd/man3/isfinite.3 new file mode 100644 index 00000000..dd7eb1ba --- /dev/null +++ b/static/netbsd/man3/isfinite.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: isfinite.3,v 1.4 2011/08/06 11:02:41 jruoho Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 6, 2011 +.Dt ISFINITE 3 +.Os +.Sh NAME +.Nm isfinite +.Nd test for finite value +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isfinite "real-floating x" +.Sh DESCRIPTION +The +.Fn isfinite +determines whether its argument +.Fa x +has a finite value. +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The determination is then based on the type of the argument. +.Ss IEEE 754 +It is determined whether the value of +.Fa x +is zero, subnormal, or normal, and neither infinite nor NaN. +.Ss VAX +It is determined whether the value of +.Fa x +is true zero or finite, and neither dirty zero nor ROP. +.Sh RETURN VALUES +The +.Fn isfinite +macro returns a non-zero value if the value of +.Fa x +is finite. +Otherwise 0 is returned. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr finite 3 , +.Xr fpclassify 3 , +.Xr isnormal 3 , +.Xr math 3 , +.Xr signbit 3 +.Sh STANDARDS +The +.Fn isfinite +macro conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/isgraph.3 b/static/netbsd/man3/isgraph.3 new file mode 100644 index 00000000..083e82c4 --- /dev/null +++ b/static/netbsd/man3/isgraph.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: isgraph.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isgraph.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISGRAPH 3 +.Os +.Sh NAME +.Nm isgraph +.Nd printing character test (space character exclusive) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isgraph "int c" +.Sh DESCRIPTION +The +.Fn isgraph +function tests for any printing character except space ('\ '). +.Sh RETURN VALUES +The +.Fn isgraph +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isgraph +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isgraph +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isgreater.3 b/static/netbsd/man3/isgreater.3 new file mode 100644 index 00000000..e6fed54a --- /dev/null +++ b/static/netbsd/man3/isgreater.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: isgreater.3,v 1.1 2007/02/22 22:08:20 drochner Exp $ +.\" +.\" Copyright (c) 2003 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/isgreater.3,v 1.3 2005/02/06 03:23:31 das Exp +.\" +.Dd February 12, 2003 +.Dt ISGREATER 3 +.Os +.Sh NAME +.Nm isgreater , isgreaterequal , isless , islessequal , +.Nm islessgreater , isunordered +.Nd "compare two floating-point numbers" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isgreater "real-floating x" "real-floating y" +.Ft int +.Fn isgreaterequal "real-floating x" "real-floating y" +.Ft int +.Fn isless "real-floating x" "real-floating y" +.Ft int +.Fn islessequal "real-floating x" "real-floating y" +.Ft int +.Fn islessgreater "real-floating x" "real-floating y" +.Ft int +.Fn isunordered "real-floating x" "real-floating y" +.Sh DESCRIPTION +Each of the macros +.Fn isgreater , +.Fn isgreaterequal , +.Fn isless , +.Fn islessequal , +and +.Fn islessgreater +take arguments +.Fa x +and +.Fa y +and return a non-zero value if and only if its nominal +relation on +.Fa x +and +.Fa y +is true. +These macros always return zero if either +argument is not a number (NaN), but unlike the corresponding C +operators, they never raise a floating point exception. +.Pp +The +.Fn isunordered +macro takes arguments +.Fa x +and +.Fa y +and returns non-zero if and only if neither +.Fa x +nor +.Fa y +are NaNs. +For any pair of floating-point values, one +of the relationships (less, greater, equal, unordered) holds. +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr math 3 , +.Xr signbit 3 +.Sh STANDARDS +The +.Fn isgreater , +.Fn isgreaterequal , +.Fn isless , +.Fn islessequal , +.Fn islessgreater , +and +.Fn isunordered +macros conform to +.St -isoC-99 . +.Sh HISTORY +The relational macros described above first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/isinf.3 b/static/netbsd/man3/isinf.3 new file mode 100644 index 00000000..24d376ef --- /dev/null +++ b/static/netbsd/man3/isinf.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: isinf.3,v 1.13 2017/09/27 09:04:30 maya Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isinf.3 8.2 (Berkeley) 1/29/94 +.\" +.Dd September 27, 2017 +.Dt ISINF 3 +.Os +.Sh NAME +.Nm isinf +.Nd test for infinity +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isinf "real-floating x" +.Sh DESCRIPTION +The +.Fn isinf +macro determines whether its argument +.Fa x +is an infinity (positive or negative). +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The determination is then based on the type of the argument. +.Sh RETURN VALUES +The +.Fn isinf +macro returns a non-zero value if the value of +.Fa x +is an infinity. +Otherwise 0 is returned. +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr isfinite 3 , +.Xr isinff 3 , +.Xr isnan 3 , +.Xr isnanf 3 , +.Xr isnormal 3 , +.Xr math 3 , +.Xr signbit 3 +.Rs +.%T "IEEE Standard for Binary Floating-Point Arithmetic" +.%Q ANSI +.%R Std 754-1985 +.Re +.Sh STANDARDS +The +.Fn isinf +macro conforms to +.St -isoC-99 . +.Sh CAVEATS +On VAX the +.Fn isinf +function always returns 0, +as the architecture doesn't have a representation for infinity. diff --git a/static/netbsd/man3/isinff.3 b/static/netbsd/man3/isinff.3 new file mode 100644 index 00000000..189bda2e --- /dev/null +++ b/static/netbsd/man3/isinff.3 @@ -0,0 +1,76 @@ +.\" $NetBSD: isinff.3,v 1.6 2010/05/14 03:10:24 joerg Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)isinf.3 8.2 (Berkeley) 1/29/94 +.\" from: NetBSD: isinf.3,v 1.5 1998/08/02 04:52:54 mycroft Exp +.\" +.Dd August 16, 1999 +.Dt ISINFF 3 +.Os +.Sh NAME +.Nm isinff , +.Nm isnanf +.Nd test for infinity or not-a-number +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isinff float +.Ft int +.Fn isnanf float +.Sh DESCRIPTION +The +.Fn isinff +function +returns 1 if the number is +.Dq \*(If , +otherwise 0. +.Pp +The +.Fn isnanf +function +returns 1 if the number is +.Dq not-a-number , +otherwise 0. +.Sh SEE ALSO +.Xr isinf 3 , +.Xr isnan 3 , +.Xr math 3 +.Rs +.%T "IEEE Standard for Binary Floating-Point Arithmetic" +.%Q ANSI +.%R Std 754-1985 +.Re +.Sh BUGS +Neither the +.Tn VAX +nor the Tahoe floating point have distinguished values +for either infinity or not-a-number. +These routines always return 0 on those architectures. diff --git a/static/netbsd/man3/islower.3 b/static/netbsd/man3/islower.3 new file mode 100644 index 00000000..1322e36e --- /dev/null +++ b/static/netbsd/man3/islower.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: islower.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)islower.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISLOWER 3 +.Os +.Sh NAME +.Nm islower +.Nd lower-case character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn islower "int c" +.Sh DESCRIPTION +The +.Fn islower +function tests for any lower-case letter +.\" or any of an +.\" implementation-defined set of characters +for which none of +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +In the +.Em ``C'' +locale, +.Fn islower +returns true only for the characters defined as lower-case letters. +.Sh RETURN VALUES +The +.Fn islower +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn islower +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn islower +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isnan.3 b/static/netbsd/man3/isnan.3 new file mode 100644 index 00000000..01b51da7 --- /dev/null +++ b/static/netbsd/man3/isnan.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: isnan.3,v 1.3 2017/09/27 18:55:50 maya Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)isinf.3 8.2 (Berkeley) 1/29/94 +.\" from: NetBSD: isinf.3,v 1.10 2003/08/07 16:42:52 agc Exp +.\" +.Dd September 27, 2017 +.Dt ISNAN 3 +.Os +.Sh NAME +.Nm isnan +.Nd test for not-a-number +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isnan "real-floating x" +.Sh DESCRIPTION +The +.Fn isnan +macro determines whether its argument +.Fa x +is not-a-number +.Pq Dq NaN . +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The determination is then based on the type of the argument. +.Sh RETURN VALUES +The +.Fn isnan +macro returns a non-zero value if the value of +.Fa x +is a NaN. +Otherwise 0 is returned. +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr isfinite 3 , +.Xr isinf 3 , +.Xr isinff 3 , +.Xr isnanf 3 , +.Xr isnormal 3 , +.Xr math 3 , +.Xr signbit 3 +.Rs +.%T "IEEE Standard for Binary Floating-Point Arithmetic" +.%Q ANSI +.%R Std 754-1985 +.Re +.Sh STANDARDS +The +.Fn isnan +macro conforms to +.St -isoC-99 . +.Sh CAVEATS +On VAX the +.Fn isnan +function always returns 0, +as the architecture doesn't support NaN. diff --git a/static/netbsd/man3/isnormal.3 b/static/netbsd/man3/isnormal.3 new file mode 100644 index 00000000..7ccda97f --- /dev/null +++ b/static/netbsd/man3/isnormal.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: isnormal.3,v 1.3 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 29, 2003 +.Dt ISNORMAL 3 +.Os +.Sh NAME +.Nm isnormal +.Nd test for normal value +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn isnormal "real-floating x" +.Sh DESCRIPTION +The +.Fn isnormal +macro determines whether its argument +.Fa x +has a normal value. +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The determination is then based on the type of the argument. +.Ss IEEE 754 +It is determined whether the value of +.Fa x +is normal, and neither zero, subnormal, infinite nor NaN. +.Ss VAX +It is determined whether the value of +.Fa x +is finite, and neither true zero, dirty zero nor ROP. +.Sh RETURN VALUES +The +.Fn isnormal +macro returns a non-zero value if the value of +.Fa x +is finite. +Otherwise 0 is returned. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr isfinite 3 , +.Xr math 3 , +.Xr signbit 3 +.Sh STANDARDS +The +.Fn isnormal +macro conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/isns.3 b/static/netbsd/man3/isns.3 new file mode 100644 index 00000000..c0dbbdae --- /dev/null +++ b/static/netbsd/man3/isns.3 @@ -0,0 +1,245 @@ +.\" $NetBSD: isns.3,v 1.2 2011/01/16 08:00:01 wiz Exp $ +.\" +.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.Dd October 1, 2009 +.Dt ISNS 3 +.Os +.Sh NAME +.Nm isns +.Nd iSNS protocol support library +.Sh LIBRARY +.Lb libisns +.Sh SYNOPSIS +.In isns.h +.Ft int +.Fn isns_init "ISNS_HANDLE *h" "int is_server" +.Ft void +.Fn isns_stop "ISNS_HANDLE h" +.Ft int +.Fn isns_add_servercon "ISNS_HANDLE h" "int fd" "struct addrinfo *ai" +.Ft int +.Fn isns_init_reg_refresh "ISNS_HANDLE h" "const char *node" "int interval" +.Ft ISNS_TRANS +.Fn isns_new_trans "ISNS_HANDLE h" "uint16_t func_id" "uint16_t pdu_flags" +.Ft int +.Fn isns_add_tlv "ISNS_TRANS t" "uint32_t tag" "int data_len" "const void *data_p" +.Ft int +.Fn isns_add_string "ISNS_TRANS t" "uint32_t tag" "const char *s" +.Ft int +.Fn isns_send_trans "ISNS_TRANS t" "const struct timespec *timeout_p" "uint32_t *status_p" +.Ft int +.Fn isns_get_tlv "ISNS_TRANS t" "int which_tlv" "uint32_t *tag_p" "int data_len_p" "void **data_pp" +.Ft void +.Fn isns_free_trans "ISNS_TRANS t" +.Sh DESCRIPTION +The +.Nm +library exports an API that simplifies Internet Storage Name +Service (iSNS) client implementations. +The API defines a transactional model in support of: +.Pp +.Bl -bullet -width 3n -offset indent -compact +.It +generating iSNS messages composed of iSNS attributes expressed in +Tag-Length-Value (TLV) data format +.It +submitting iSNS Protocol (iSNSP) messages +.It +optionally waiting for iSNSP responses +.El +.Pp +.Nm +does not currently support receipt of iSNS Heartbeat messages, State Change +Notification (SCN) messages, or Entity Status Inquiry (ESI) messages. +.Sh INITIALIZATION +An iSNS client that uses +.Nm +must call +.Fn isns_init +to initialize the iSNS environment. +This call will create a thread to handle client-server communication, and +as such should only be called when thread creation is appropriate (such +as after a daemonized program forks). +.Pp +The value passed as +.Ar is_server +is used to set iSNSP message format Flags +"Sender is the iSNS client" (bit position 16) and "Sender is the iSNS server" +(bit position 17). +For now the value 0 (zero) should be passed for +.Ar is_server . +The value returned in +.Ar h +should be considered opaque by the caller. +This value is passed unchanged to +.Fn isns_add_servercon , +.Fn isns_init_reg_refresh , +.Fn isns_stop , +and +.Fn isns_new_trans . +.Pp +.Fn isns_stop +should be called when the iSNS environment is no longer needed. +This call will kill any threads created by +.Fn isns_init . +.Sh CONFIGURATION +Following initialization, +.Fn isns_add_servercon +should be used to make the iSNS environment aware of the iSNS +server to which iSNSP queries and requests are to be sent. +This routine should not be called by a program acting as an iSNS server. +.Pp +A connected TCP socket descriptor is passed as parameter +.Ar fd . +Parameter +.Ar ai +is the address of the remote TCP endpoint. +It is included so that reconnection may be attempted by +.Nm +in the event that the TCP connection is broken. +.Pp +Certain iSNS servers will limit registration lifetimes, and will +refresh registrations after any request from a given iSNS entity. +The +.Fn isns_init_reg_refresh +function offers a way for +.Nm +to refresh registrations on behalf of the iSNS client. +.Pp +Parameter +.Ar node +is the +.Dq iSCSI Name +attribute used for the periodic queries. +It should be the name of an iSCSI node within the registered iSNS entity. +The desired refresh interval, in seconds, is passed in parameter +.Ar interval . +.Sh TRANSACTIONS +.Fn isns_new_trans +creates new iSNS transactions. +.Pp +Parameter +.Ar func_id +is used as the iSNSP message id. +Parameter +.Ar pdu_flags +is used to set iSNSP message format Flags and is +exposed to allow callers to set flag "Replace flag" (bit position 19). +This provides callers with a way +to specify whether a Device Attribute Registration Request is intended to +update or replace an existing registration. +This is currently the only use defined for parameter +.Ar pdu_flags . +.Pp +Once a new transaction has been created, callers can specify iSNS attributes +used for registration and query requests. +TLV data may be added using either +.Fn isns_add_tlv +or +.Fn isns_add_string . +.Pp +Parameter +.Ar tag +is the iSNS Tag corresponding to the attribute being added. +Parameter +.Ar data_len +is the length of the attribute value. +Parameter +.Ar data_p +references the attribute value. +The caller does not need to handle iSNS attribute 4-byte alignment requirements. +This is handled by the iSNS environment on behalf of the caller. +.Fn isns_add_string +may be used if the attribute value is a NUL terminated C string. +.Pp +Once a transaction has been populated with any required TLV data, +.Fn isns_send_trans +can be used to submit an iSNSP registration or query message. +.Pp +Callers that submit iSNSP query messages may need to wait for returned data. +.Fn isns_send_trans +supports bounded waits. +Successful waits, those that do not time out, return the iSNSP response +status code received in the iSNSP response message. +If a wait does time out, the value of +.Ar status_p +is undefined. +Callers that do not need to wait for returned data can simply +pass +.Dv NULL +for parameter +.Ar timeout_p . +Callers should set parameter +.Ar status_p +to +.Dv NULL +if not waiting. +.Pp +.Fn isns_get_tlv +is used to retrieve TLV data returned in a transaction. +The first call to +.Fn isns_get_tlv +should pass the value +.Dv ISNS_TLV_FIRST +for parameter +.Ar which_tlv . +Each subsequent TLV can be retrieved by passing in +.Dv ISNS_TLV_NEXT +in place of +.Dv ISNS_TLV_FIRST . +.Pp +When a caller is done with a transaction, having submitted either a +registration or a query message and retrieved any returned TLV data, +.Fn isns_free_trans +should be used to release resources used by the transaction. +.Sh RETURN VALUES +.Fn isns_init , +.Fn isns_add_servercon , +.Fn isns_init_reg_refresh , +.Fn isns_add_tlv , +.Fn isns_add_string , +and +.Fn isns_send_trans +return 0 on success, or \-1 on failure. +.Fn isns_new_trans +returns 0 on success, or +.Dv ISNS_INVALID_TRANS +on failure. +.Fn isns_get_tlv +returns 0 on success, or +.Er ENOENT +if there are no TLVs to retrieve. +.Sh HISTORY +.Nm +first appeared in +.Nx 6.0 . +The +.Nm +implementation was contributed to the +.Nx +Foundation by Wasabi Systems, Inc. diff --git a/static/netbsd/man3/isprint.3 b/static/netbsd/man3/isprint.3 new file mode 100644 index 00000000..e2091097 --- /dev/null +++ b/static/netbsd/man3/isprint.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: isprint.3,v 1.13 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isprint.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISPRINT 3 +.Os +.Sh NAME +.Nm isprint +.Nd printing character test (space character inclusive) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isprint "int c" +.Sh DESCRIPTION +The +.Fn isprint +function tests for any printing character including space (' '). +.Sh RETURN VALUES +The +.Fn isprint +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isprint +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isprint +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/ispunct.3 b/static/netbsd/man3/ispunct.3 new file mode 100644 index 00000000..8d32ac67 --- /dev/null +++ b/static/netbsd/man3/ispunct.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: ispunct.3,v 1.13 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ispunct.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISPUNCT 3 +.Os +.Sh NAME +.Nm ispunct +.Nd punctuation character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn ispunct "int c" +.Sh DESCRIPTION +The +.Fn ispunct +function tests for any printing character except space (' ') or a +character for which +.Xr isalnum 3 +is true. +.Sh RETURN VALUES +The +.Fn ispunct +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn ispunct +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn ispunct +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isspace.3 b/static/netbsd/man3/isspace.3 new file mode 100644 index 00000000..4c6d1306 --- /dev/null +++ b/static/netbsd/man3/isspace.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: isspace.3,v 1.15 2012/10/03 19:28:44 wiz Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isspace.3 5.3 (Berkeley) 7/31/91 +.\" +.Dd April 17, 2008 +.Dt ISSPACE 3 +.Os +.Sh NAME +.Nm isspace +.Nd white-space character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isspace "int c" +.Sh DESCRIPTION +The +.Fn isspace +function tests for the standard white-space characters +.\" or for any +.\" of an implementation-defined set of characters +for which +.Xr isalnum 3 +is false. +The standard white-space characters are the following: +.Pp +.Bl -tag -width xxxxx -offset indent -compact +.It Sq \0 +Space character. +.It Li \ef +Form feed. +.It Li \en +New-line. +.It Li \er +Carriage return. +.It Li \et +Horizontal tab. +.It Li \ev +Vertical tab. +.El +.Pp +In the +.Em ``C'' +locale, +.Fn isspace +returns true only for the standard white-space characters. +.Sh RETURN VALUES +The +.Fn isspace +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isspace +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isspace +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/isupper.3 b/static/netbsd/man3/isupper.3 new file mode 100644 index 00000000..d969eca5 --- /dev/null +++ b/static/netbsd/man3/isupper.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: isupper.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isupper.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISUPPER 3 +.Os +.Sh NAME +.Nm isupper +.Nd upper-case character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isupper "int c" +.Sh DESCRIPTION +The +.Fn isupper +function tests for any upper-case letter or any of an +implementation-defined set of characters for which none of +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr ispunct 3 , +or +.Xr isspace 3 +is true. +In the +.Em ``C'' +locale, +.Fn isupper +returns true only for the characters defined as upper-case letters. +.Sh RETURN VALUES +The +.Fn isupper +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isupper +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isupper +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/iswalnum.3 b/static/netbsd/man3/iswalnum.3 new file mode 100644 index 00000000..d986995a --- /dev/null +++ b/static/netbsd/man3/iswalnum.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: iswalnum.3,v 1.9 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isalnum.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd December 22, 2000 +.Dt ISWALNUM 3 +.Os +.Sh NAME +.Nm iswalnum , +.Nm iswalpha , +.Nm iswblank , +.Nm iswcntrl , +.Nm iswdigit , +.Nm iswgraph , +.Nm iswlower , +.Nm iswprint , +.Nm iswpunct , +.Nm iswspace , +.Nm iswupper , +.Nm iswxdigit +.Nd wide character classification utilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wctype.h +.Ft int +.Fn iswalnum "wint_t wc" +.Ft int +.Fn iswalpha "wint_t wc" +.Ft int +.Fn iswblank "wint_t wc" +.Ft int +.Fn iswcntrl "wint_t wc" +.Ft int +.Fn iswdigit "wint_t wc" +.Ft int +.Fn iswgraph "wint_t wc" +.Ft int +.Fn iswlower "wint_t wc" +.Ft int +.Fn iswprint "wint_t wc" +.Ft int +.Fn iswpunct "wint_t wc" +.Ft int +.Fn iswspace "wint_t wc" +.Ft int +.Fn iswupper "wint_t wc" +.Ft int +.Fn iswxdigit "wint_t wc" +.Sh DESCRIPTION +The functions are character classification utility functions, +for use with wide characters +.Po +.Fa wchar_t +or +.Fa wint_t +.Pc . +See the description of singlebyte classification functions, like +.Xr isalnum 3 , +for details. +.Sh RETURN VALUES +The functions return zero if the character tests false and +return non-zero if the character tests true. +.Sh SEE ALSO +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 +.Sh STANDARDS +The functions conform to +.St -isoC-99 . +.Sh CAVEATS +The argument to these functions must be +.Dv WEOF +or a valid +.Fa wchar_t +value with the current locale; otherwise, the result is undefined. diff --git a/static/netbsd/man3/iswctype.3 b/static/netbsd/man3/iswctype.3 new file mode 100644 index 00000000..6225844a --- /dev/null +++ b/static/netbsd/man3/iswctype.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: iswctype.3,v 1.7 2007/05/21 15:20:40 tnozaki Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 4, 2003 +.Dt ISWCTYPE 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm iswctype +.Nd test a character for character class identifier +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wctype.h +.Ft int +.Fn iswctype "wint_t wc" "wctype_t charclass" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn iswctype +function returns a boolean value that indicates whether a wide character +.Fa wc +is in +.Fa charclass . +.Pp +The behaviour of +.Fn iswctype +is undefined if the +.Fn iswctype +function is called with an invalid +.Fa charclass +(changes of +.Dv LC_CTYPE +category invalidate +.Fa charclass ) +or invalid wide character +.Fa wc . +.Pp +The behaviour of +.Fn iswctype +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn iswctype +returns: +.Bl -tag -width 012345678901 +.It 0 +.Fa wc +is not in +.Fa charclass . +.It non-zero +.Fa wc +is in +.Fa charclass . +.El +.Pp +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr towctrans 3 , +.Xr wctrans 3 , +.Xr wctype 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn iswctype +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/isxdigit.3 b/static/netbsd/man3/isxdigit.3 new file mode 100644 index 00000000..7777af03 --- /dev/null +++ b/static/netbsd/man3/isxdigit.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: isxdigit.3,v 1.13 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)isxdigit.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt ISXDIGIT 3 +.Os +.Sh NAME +.Nm isxdigit +.Nd hexadecimal-digit character test +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn isxdigit "int c" +.Sh DESCRIPTION +The +.Fn isxdigit +function tests for any hexadecimal-digit character. +.Sh RETURN VALUES +The +.Fn isxdigit +function returns zero if the character tests false and +returns non-zero if the character tests true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr isblank 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn isxdigit +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn isxdigit +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/j0.3 b/static/netbsd/man3/j0.3 new file mode 100644 index 00000000..85604ed7 --- /dev/null +++ b/static/netbsd/man3/j0.3 @@ -0,0 +1,153 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)j0.3 6.7 (Berkeley) 4/19/91 +.\" $NetBSD: j0.3,v 1.16 2003/08/07 16:44:48 agc Exp $ +.\" +.Dd April 19, 1991 +.Dt J0 3 +.Os +.Sh NAME +.Nm j0 , +.Nm j0f , +.Nm j1 , +.Nm j1f , +.Nm jn , +.Nm jnf , +.Nm y0 , +.Nm y0f , +.Nm y1 , +.Nm y1f , +.Nm yn , +.Nm ynf +.Nd Bessel functions of first and second kind +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn j0 "double x" +.Ft float +.Fn j0f "float x" +.Ft double +.Fn j1 "double x" +.Ft float +.Fn j1f "float x" +.Ft double +.Fn jn "int n" "double x" +.Ft float +.Fn jnf "int n" "float x" +.Ft double +.Fn y0 "double x" +.Ft float +.Fn y0f "float x" +.Ft double +.Fn y1 "double x" +.Ft float +.Fn y1f "float x" +.Ft double +.Fn yn "int n" "double x" +.Ft float +.Fn ynf "int n" "float x" +.Sh DESCRIPTION +The functions +.Fn j0 , +.Fn j0f , +.Fn j1 +and +.Fn j1f +compute the +.Em Bessel function of the first kind of the order +0 and the +.Em order +1, respectively, +for the +real value +.Fa x ; +the functions +.Fn jn +and +.Fn jnf +compute the +.Em Bessel function of the first kind of the integer order +.Fa n +for the real value +.Fa x . +.Pp +The functions +.Fn y0 , +.Fn y0f , +.Fn y1 +and +.Fn y1f +compute the linearly independent +.Em Bessel function of the second kind of the order +0 and the +.Em order +1, respectively, +for the +positive +.Em integer +value +.Fa x +(expressed as a double); +the functions +.Fn yn +and +.Fn ynf +compute the +.Em Bessel function of the second kind for the integer order +.Fa n +for the positive +.Em integer +value +.Fa x +(expressed as a double). +.Sh RETURN VALUES +If these functions are successful, +the computed value is returned, otherwise +the global +variable +.Va errno +is set to +.Er EDOM +and a reserve operand fault is generated. +.\" On the +.\" .Tn VAX +.\" and +.\" .Tn Tahoe +.\" architectures, a negative +.\" .Fa x +.\" value +.\" results in an error. +.Sh SEE ALSO +.Xr math 3 +.\" .Xr matherr 3 +.Sh HISTORY +This set of functions +appeared in +.At v7 . diff --git a/static/netbsd/man3/jemalloc.3 b/static/netbsd/man3/jemalloc.3 new file mode 100644 index 00000000..6d905c81 --- /dev/null +++ b/static/netbsd/man3/jemalloc.3 @@ -0,0 +1,2688 @@ +'\" t +.\" Title: JEMALLOC +.\" Author: Jason Evans +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" Date: 05/06/2022 +.\" Manual: User Manual +.\" Source: jemalloc 5.3.0-0-g54eaed1d8b56b1aa528be3bdd1877e59c56fa90c +.\" Language: English +.\" +.TH "JEMALLOC" "3" "05/06/2022" "jemalloc 5.3.0-0-g54eaed1d8b56" "User Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +jemalloc \- general purpose memory allocation functions +.SH "LIBRARY" +.PP +This manual describes jemalloc 5\&.3\&.0\-0\-g54eaed1d8b56b1aa528be3bdd1877e59c56fa90c\&. More information can be found at the +\m[blue]\fBjemalloc website\fR\m[]\&\s-2\u[1]\d\s+2\&. +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include +.fi +.ft +.SS "Standard API" +.HP \w'void\ *malloc('u +.BI "void *malloc(size_t\ " "size" ");" +.HP \w'void\ *calloc('u +.BI "void *calloc(size_t\ " "number" ", size_t\ " "size" ");" +.HP \w'int\ posix_memalign('u +.BI "int posix_memalign(void\ **" "ptr" ", size_t\ " "alignment" ", size_t\ " "size" ");" +.HP \w'void\ *aligned_alloc('u +.BI "void *aligned_alloc(size_t\ " "alignment" ", size_t\ " "size" ");" +.HP \w'void\ *realloc('u +.BI "void *realloc(void\ *" "ptr" ", size_t\ " "size" ");" +.HP \w'void\ free('u +.BI "void free(void\ *" "ptr" ");" +.SS "Non\-standard API" +.HP \w'void\ *mallocx('u +.BI "void *mallocx(size_t\ " "size" ", int\ " "flags" ");" +.HP \w'void\ *rallocx('u +.BI "void *rallocx(void\ *" "ptr" ", size_t\ " "size" ", int\ " "flags" ");" +.HP \w'size_t\ xallocx('u +.BI "size_t xallocx(void\ *" "ptr" ", size_t\ " "size" ", size_t\ " "extra" ", int\ " "flags" ");" +.HP \w'size_t\ sallocx('u +.BI "size_t sallocx(void\ *" "ptr" ", int\ " "flags" ");" +.HP \w'void\ dallocx('u +.BI "void dallocx(void\ *" "ptr" ", int\ " "flags" ");" +.HP \w'void\ sdallocx('u +.BI "void sdallocx(void\ *" "ptr" ", size_t\ " "size" ", int\ " "flags" ");" +.HP \w'size_t\ nallocx('u +.BI "size_t nallocx(size_t\ " "size" ", int\ " "flags" ");" +.HP \w'int\ mallctl('u +.BI "int mallctl(const\ char\ *" "name" ", void\ *" "oldp" ", size_t\ *" "oldlenp" ", void\ *" "newp" ", size_t\ " "newlen" ");" +.HP \w'int\ mallctlnametomib('u +.BI "int mallctlnametomib(const\ char\ *" "name" ", size_t\ *" "mibp" ", size_t\ *" "miblenp" ");" +.HP \w'int\ mallctlbymib('u +.BI "int mallctlbymib(const\ size_t\ *" "mib" ", size_t\ " "miblen" ", void\ *" "oldp" ", size_t\ *" "oldlenp" ", void\ *" "newp" ", size_t\ " "newlen" ");" +.HP \w'void\ malloc_stats_print('u +.BI "void malloc_stats_print(void\ " "(*write_cb)" "\ (void\ *,\ const\ char\ *), void\ *" "cbopaque" ", const\ char\ *" "opts" ");" +.HP \w'size_t\ malloc_usable_size('u +.BI "size_t malloc_usable_size(const\ void\ *" "ptr" ");" +.HP \w'void\ (*malloc_message)('u +.BI "void (*malloc_message)(void\ *" "cbopaque" ", const\ char\ *" "s" ");" +.PP +const char *\fImalloc_conf\fR; +.SH "DESCRIPTION" +.SS "Standard API" +.PP +The +malloc() +function allocates +\fIsize\fR +bytes of uninitialized memory\&. The allocated space is suitably aligned (after possible pointer coercion) for storage of any type of object\&. +.PP +The +calloc() +function allocates space for +\fInumber\fR +objects, each +\fIsize\fR +bytes in length\&. The result is identical to calling +malloc() +with an argument of +\fInumber\fR +* +\fIsize\fR, with the exception that the allocated memory is explicitly initialized to zero bytes\&. +.PP +The +posix_memalign() +function allocates +\fIsize\fR +bytes of memory such that the allocation\*(Aqs base address is a multiple of +\fIalignment\fR, and returns the allocation in the value pointed to by +\fIptr\fR\&. The requested +\fIalignment\fR +must be a power of 2 at least as large as +sizeof(\fBvoid *\fR)\&. +.PP +The +aligned_alloc() +function allocates +\fIsize\fR +bytes of memory such that the allocation\*(Aqs base address is a multiple of +\fIalignment\fR\&. The requested +\fIalignment\fR +must be a power of 2\&. Behavior is undefined if +\fIsize\fR +is not an integral multiple of +\fIalignment\fR\&. +.PP +The +realloc() +function changes the size of the previously allocated memory referenced by +\fIptr\fR +to +\fIsize\fR +bytes\&. The contents of the memory are unchanged up to the lesser of the new and old sizes\&. If the new size is larger, the contents of the newly allocated portion of the memory are undefined\&. Upon success, the memory referenced by +\fIptr\fR +is freed and a pointer to the newly allocated memory is returned\&. Note that +realloc() +may move the memory allocation, resulting in a different return value than +\fIptr\fR\&. If +\fIptr\fR +is +\fBNULL\fR, the +realloc() +function behaves identically to +malloc() +for the specified size\&. +.PP +The +free() +function causes the allocated memory referenced by +\fIptr\fR +to be made available for future allocations\&. If +\fIptr\fR +is +\fBNULL\fR, no action occurs\&. +.SS "Non\-standard API" +.PP +The +mallocx(), +rallocx(), +xallocx(), +sallocx(), +dallocx(), +sdallocx(), and +nallocx() +functions all have a +\fIflags\fR +argument that can be used to specify options\&. The functions only check the options that are contextually relevant\&. Use bitwise or (|) operations to specify one or more of the following: +.PP +\fBMALLOCX_LG_ALIGN(\fR\fB\fIla\fR\fR\fB) \fR +.RS 4 +Align the memory allocation to start at an address that is a multiple of +(1 << \fIla\fR)\&. This macro does not validate that +\fIla\fR +is within the valid range\&. +.RE +.PP +\fBMALLOCX_ALIGN(\fR\fB\fIa\fR\fR\fB) \fR +.RS 4 +Align the memory allocation to start at an address that is a multiple of +\fIa\fR, where +\fIa\fR +is a power of two\&. This macro does not validate that +\fIa\fR +is a power of 2\&. +.RE +.PP +\fBMALLOCX_ZERO\fR +.RS 4 +Initialize newly allocated memory to contain zero bytes\&. In the growing reallocation case, the real size prior to reallocation defines the boundary between untouched bytes and those that are initialized to contain zero bytes\&. If this macro is absent, newly allocated memory is uninitialized\&. +.RE +.PP +\fBMALLOCX_TCACHE(\fR\fB\fItc\fR\fR\fB) \fR +.RS 4 +Use the thread\-specific cache (tcache) specified by the identifier +\fItc\fR, which must have been acquired via the +tcache\&.create +mallctl\&. This macro does not validate that +\fItc\fR +specifies a valid identifier\&. +.RE +.PP +\fBMALLOCX_TCACHE_NONE\fR +.RS 4 +Do not use a thread\-specific cache (tcache)\&. Unless +\fBMALLOCX_TCACHE(\fR\fB\fItc\fR\fR\fB)\fR +or +\fBMALLOCX_TCACHE_NONE\fR +is specified, an automatically managed tcache will be used under many circumstances\&. This macro cannot be used in the same +\fIflags\fR +argument as +\fBMALLOCX_TCACHE(\fR\fB\fItc\fR\fR\fB)\fR\&. +.RE +.PP +\fBMALLOCX_ARENA(\fR\fB\fIa\fR\fR\fB) \fR +.RS 4 +Use the arena specified by the index +\fIa\fR\&. This macro has no effect for regions that were allocated via an arena other than the one specified\&. This macro does not validate that +\fIa\fR +specifies an arena index in the valid range\&. +.RE +.PP +The +mallocx() +function allocates at least +\fIsize\fR +bytes of memory, and returns a pointer to the base address of the allocation\&. Behavior is undefined if +\fIsize\fR +is +\fB0\fR\&. +.PP +The +rallocx() +function resizes the allocation at +\fIptr\fR +to be at least +\fIsize\fR +bytes, and returns a pointer to the base address of the resulting allocation, which may or may not have moved from its original location\&. Behavior is undefined if +\fIsize\fR +is +\fB0\fR\&. +.PP +The +xallocx() +function resizes the allocation at +\fIptr\fR +in place to be at least +\fIsize\fR +bytes, and returns the real size of the allocation\&. If +\fIextra\fR +is non\-zero, an attempt is made to resize the allocation to be at least +(\fIsize\fR + \fIextra\fR) +bytes, though inability to allocate the extra byte(s) will not by itself result in failure to resize\&. Behavior is undefined if +\fIsize\fR +is +\fB0\fR, or if +(\fIsize\fR + \fIextra\fR > \fBSIZE_T_MAX\fR)\&. +.PP +The +sallocx() +function returns the real size of the allocation at +\fIptr\fR\&. +.PP +The +dallocx() +function causes the memory referenced by +\fIptr\fR +to be made available for future allocations\&. +.PP +The +sdallocx() +function is an extension of +dallocx() +with a +\fIsize\fR +parameter to allow the caller to pass in the allocation size as an optimization\&. The minimum valid input size is the original requested size of the allocation, and the maximum valid input size is the corresponding value returned by +nallocx() +or +sallocx()\&. +.PP +The +nallocx() +function allocates no memory, but it performs the same size computation as the +mallocx() +function, and returns the real size of the allocation that would result from the equivalent +mallocx() +function call, or +\fB0\fR +if the inputs exceed the maximum supported size class and/or alignment\&. Behavior is undefined if +\fIsize\fR +is +\fB0\fR\&. +.PP +The +mallctl() +function provides a general interface for introspecting the memory allocator, as well as setting modifiable parameters and triggering actions\&. The period\-separated +\fIname\fR +argument specifies a location in a tree\-structured namespace; see the +MALLCTL NAMESPACE +section for documentation on the tree contents\&. To read a value, pass a pointer via +\fIoldp\fR +to adequate space to contain the value, and a pointer to its length via +\fIoldlenp\fR; otherwise pass +\fBNULL\fR +and +\fBNULL\fR\&. Similarly, to write a value, pass a pointer to the value via +\fInewp\fR, and its length via +\fInewlen\fR; otherwise pass +\fBNULL\fR +and +\fB0\fR\&. +.PP +The +mallctlnametomib() +function provides a way to avoid repeated name lookups for applications that repeatedly query the same portion of the namespace, by translating a name to a +\(lqManagement Information Base\(rq +(MIB) that can be passed repeatedly to +mallctlbymib()\&. Upon successful return from +mallctlnametomib(), +\fImibp\fR +contains an array of +\fI*miblenp\fR +integers, where +\fI*miblenp\fR +is the lesser of the number of components in +\fIname\fR +and the input value of +\fI*miblenp\fR\&. Thus it is possible to pass a +\fI*miblenp\fR +that is smaller than the number of period\-separated name components, which results in a partial MIB that can be used as the basis for constructing a complete MIB\&. For name components that are integers (e\&.g\&. the 2 in +arenas\&.bin\&.2\&.size), the corresponding MIB component will always be that integer\&. Therefore, it is legitimate to construct code like the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +unsigned nbins, i; +size_t mib[4]; +size_t len, miblen; + +len = sizeof(nbins); +mallctl("arenas\&.nbins", &nbins, &len, NULL, 0); + +miblen = 4; +mallctlnametomib("arenas\&.bin\&.0\&.size", mib, &miblen); +for (i = 0; i < nbins; i++) { + size_t bin_size; + + mib[2] = i; + len = sizeof(bin_size); + mallctlbymib(mib, miblen, (void *)&bin_size, &len, NULL, 0); + /* Do something with bin_size\&.\&.\&. */ +} +.fi +.if n \{\ +.RE +.\} +.PP +.RS 4 +.RE +.PP +The +malloc_stats_print() +function writes summary statistics via the +\fIwrite_cb\fR +callback function pointer and +\fIcbopaque\fR +data passed to +\fIwrite_cb\fR, or +malloc_message() +if +\fIwrite_cb\fR +is +\fBNULL\fR\&. The statistics are presented in human\-readable form unless +\(lqJ\(rq +is specified as a character within the +\fIopts\fR +string, in which case the statistics are presented in +\m[blue]\fBJSON format\fR\m[]\&\s-2\u[2]\d\s+2\&. This function can be called repeatedly\&. General information that never changes during execution can be omitted by specifying +\(lqg\(rq +as a character within the +\fIopts\fR +string\&. Note that +malloc_stats_print() +uses the +mallctl*() +functions internally, so inconsistent statistics can be reported if multiple threads use these functions simultaneously\&. If +\fB\-\-enable\-stats\fR +is specified during configuration, +\(lqm\(rq, +\(lqd\(rq, and +\(lqa\(rq +can be specified to omit merged arena, destroyed merged arena, and per arena statistics, respectively; +\(lqb\(rq +and +\(lql\(rq +can be specified to omit per size class statistics for bins and large objects, respectively; +\(lqx\(rq +can be specified to omit all mutex statistics; +\(lqe\(rq +can be used to omit extent statistics\&. Unrecognized characters are silently ignored\&. Note that thread caching may prevent some statistics from being completely up to date, since extra locking would be required to merge counters that track thread cache operations\&. +.PP +The +malloc_usable_size() +function returns the usable size of the allocation pointed to by +\fIptr\fR\&. The return value may be larger than the size that was requested during allocation\&. The +malloc_usable_size() +function is not a mechanism for in\-place +realloc(); rather it is provided solely as a tool for introspection purposes\&. Any discrepancy between the requested allocation size and the size reported by +malloc_usable_size() +should not be depended on, since such behavior is entirely implementation\-dependent\&. +.SH "TUNING" +.PP +Once, when the first call is made to one of the memory allocation routines, the allocator initializes its internals based in part on various options that can be specified at compile\- or run\-time\&. +.PP +The string specified via +\fB\-\-with\-malloc\-conf\fR, the string pointed to by the global variable +\fImalloc_conf\fR, the +\(lqname\(rq +of the file referenced by the symbolic link named +/etc/malloc\&.conf, and the value of the environment variable +\fBMALLOC_CONF\fR, will be interpreted, in that order, from left to right as options\&. Note that +\fImalloc_conf\fR +may be read before +main() +is entered, so the declaration of +\fImalloc_conf\fR +should specify an initializer that contains the final value to be read by jemalloc\&. +\fB\-\-with\-malloc\-conf\fR +and +\fImalloc_conf\fR +are compile\-time mechanisms, whereas +/etc/malloc\&.conf +and +\fBMALLOC_CONF\fR +can be safely set any time prior to program invocation\&. +.PP +An options string is a comma\-separated list of option:value pairs\&. There is one key corresponding to each +opt\&.* +mallctl (see the +MALLCTL NAMESPACE +section for options documentation)\&. For example, +abort:true,narenas:1 +sets the +opt\&.abort +and +opt\&.narenas +options\&. Some options have boolean values (true/false), others have integer values (base 8, 10, or 16, depending on prefix), and yet others have raw string values\&. +.SH "IMPLEMENTATION NOTES" +.PP +Traditionally, allocators have used +\fBsbrk\fR(2) +to obtain memory, which is suboptimal for several reasons, including race conditions, increased fragmentation, and artificial limitations on maximum usable memory\&. If +\fBsbrk\fR(2) +is supported by the operating system, this allocator uses both +\fBmmap\fR(2) +and +\fBsbrk\fR(2), in that order of preference; otherwise only +\fBmmap\fR(2) +is used\&. +.PP +This allocator uses multiple arenas in order to reduce lock contention for threaded programs on multi\-processor systems\&. This works well with regard to threading scalability, but incurs some costs\&. There is a small fixed per\-arena overhead, and additionally, arenas manage memory completely independently of each other, which means a small fixed increase in overall memory fragmentation\&. These overheads are not generally an issue, given the number of arenas normally used\&. Note that using substantially more arenas than the default is not likely to improve performance, mainly due to reduced cache performance\&. However, it may make sense to reduce the number of arenas if an application does not make much use of the allocation functions\&. +.PP +In addition to multiple arenas, this allocator supports thread\-specific caching, in order to make it possible to completely avoid synchronization for most allocation requests\&. Such caching allows very fast allocation in the common case, but it increases memory usage and fragmentation, since a bounded number of objects can remain allocated in each thread cache\&. +.PP +Memory is conceptually broken into extents\&. Extents are always aligned to multiples of the page size\&. This alignment makes it possible to find metadata for user objects quickly\&. User objects are broken into two categories according to size: small and large\&. Contiguous small objects comprise a slab, which resides within a single extent, whereas large objects each have their own extents backing them\&. +.PP +Small objects are managed in groups by slabs\&. Each slab maintains a bitmap to track which regions are in use\&. Allocation requests that are no more than half the quantum (8 or 16, depending on architecture) are rounded up to the nearest power of two that is at least +sizeof(\fBdouble\fR)\&. All other object size classes are multiples of the quantum, spaced such that there are four size classes for each doubling in size, which limits internal fragmentation to approximately 20% for all but the smallest size classes\&. Small size classes are smaller than four times the page size, and large size classes extend from four times the page size up to the largest size class that does not exceed +\fBPTRDIFF_MAX\fR\&. +.PP +Allocations are packed tightly together, which can be an issue for multi\-threaded applications\&. If you need to assure that allocations do not suffer from cacheline sharing, round your allocation requests up to the nearest multiple of the cacheline size, or specify cacheline alignment when allocating\&. +.PP +The +realloc(), +rallocx(), and +xallocx() +functions may resize allocations without moving them under limited circumstances\&. Unlike the +*allocx() +API, the standard API does not officially round up the usable size of an allocation to the nearest size class, so technically it is necessary to call +realloc() +to grow e\&.g\&. a 9\-byte allocation to 16 bytes, or shrink a 16\-byte allocation to 9 bytes\&. Growth and shrinkage trivially succeeds in place as long as the pre\-size and post\-size both round up to the same size class\&. No other API guarantees are made regarding in\-place resizing, but the current implementation also tries to resize large allocations in place, as long as the pre\-size and post\-size are both large\&. For shrinkage to succeed, the extent allocator must support splitting (see +arena\&.\&.extent_hooks)\&. Growth only succeeds if the trailing memory is currently available, and the extent allocator supports merging\&. +.PP +Assuming 4 KiB pages and a 16\-byte quantum on a 64\-bit system, the size classes in each category are as shown in +Table 1\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Size classes +.TS +allbox tab(:); +lB rB lB. +T{ +Category +T}:T{ +Spacing +T}:T{ +Size +T} +.T& +l r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +l r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l +^ r l. +T{ +Small +T}:T{ +lg +T}:T{ +[8] +T} +:T{ +16 +T}:T{ +[16, 32, 48, 64, 80, 96, 112, 128] +T} +:T{ +32 +T}:T{ +[160, 192, 224, 256] +T} +:T{ +64 +T}:T{ +[320, 384, 448, 512] +T} +:T{ +128 +T}:T{ +[640, 768, 896, 1024] +T} +:T{ +256 +T}:T{ +[1280, 1536, 1792, 2048] +T} +:T{ +512 +T}:T{ +[2560, 3072, 3584, 4096] +T} +:T{ +1 KiB +T}:T{ +[5 KiB, 6 KiB, 7 KiB, 8 KiB] +T} +:T{ +2 KiB +T}:T{ +[10 KiB, 12 KiB, 14 KiB] +T} +T{ +Large +T}:T{ +2 KiB +T}:T{ +[16 KiB] +T} +:T{ +4 KiB +T}:T{ +[20 KiB, 24 KiB, 28 KiB, 32 KiB] +T} +:T{ +8 KiB +T}:T{ +[40 KiB, 48 KiB, 56 KiB, 64 KiB] +T} +:T{ +16 KiB +T}:T{ +[80 KiB, 96 KiB, 112 KiB, 128 KiB] +T} +:T{ +32 KiB +T}:T{ +[160 KiB, 192 KiB, 224 KiB, 256 KiB] +T} +:T{ +64 KiB +T}:T{ +[320 KiB, 384 KiB, 448 KiB, 512 KiB] +T} +:T{ +128 KiB +T}:T{ +[640 KiB, 768 KiB, 896 KiB, 1 MiB] +T} +:T{ +256 KiB +T}:T{ +[1280 KiB, 1536 KiB, 1792 KiB, 2 MiB] +T} +:T{ +512 KiB +T}:T{ +[2560 KiB, 3 MiB, 3584 KiB, 4 MiB] +T} +:T{ +1 MiB +T}:T{ +[5 MiB, 6 MiB, 7 MiB, 8 MiB] +T} +:T{ +2 MiB +T}:T{ +[10 MiB, 12 MiB, 14 MiB, 16 MiB] +T} +:T{ +4 MiB +T}:T{ +[20 MiB, 24 MiB, 28 MiB, 32 MiB] +T} +:T{ +8 MiB +T}:T{ +[40 MiB, 48 MiB, 56 MiB, 64 MiB] +T} +:T{ +\&.\&.\&. +T}:T{ +\&.\&.\&. +T} +:T{ +512 PiB +T}:T{ +[2560 PiB, 3 EiB, 3584 PiB, 4 EiB] +T} +:T{ +1 EiB +T}:T{ +[5 EiB, 6 EiB, 7 EiB] +T} +.TE +.sp 1 +.SH "MALLCTL NAMESPACE" +.PP +The following names are defined in the namespace accessible via the +mallctl*() +functions\&. Value types are specified in parentheses, their readable/writable statuses are encoded as +rw, +r\-, +\-w, or +\-\-, and required build configuration flags follow, if any\&. A name element encoded as + +or + +indicates an integer component, where the integer varies from 0 to some upper value that must be determined via introspection\&. In the case of +stats\&.arenas\&.\&.* +and +arena\&.\&.{initialized,purge,decay,dss}, + +equal to +\fBMALLCTL_ARENAS_ALL\fR +can be used to operate on all arenas or access the summation of statistics from all arenas; similarly + +equal to +\fBMALLCTL_ARENAS_DESTROYED\fR +can be used to access the summation of statistics from all destroyed arenas\&. These constants can be utilized either via +mallctlnametomib() +followed by +mallctlbymib(), or via code such as the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#define STRINGIFY_HELPER(x) #x +#define STRINGIFY(x) STRINGIFY_HELPER(x) + +mallctl("arena\&." STRINGIFY(MALLCTL_ARENAS_ALL) "\&.decay", + NULL, NULL, NULL, 0); +.fi +.if n \{\ +.RE +.\} +.sp +Take special note of the +epoch +mallctl, which controls refreshing of cached dynamic statistics\&. +.PP +version (\fBconst char *\fR) r\- +.RS 4 +Return the jemalloc version string\&. +.RE +.PP +epoch (\fBuint64_t\fR) rw +.RS 4 +If a value is passed in, refresh the data from which the +mallctl*() +functions report values, and increment the epoch\&. Return the current epoch\&. This is useful for detecting whether another thread caused a refresh\&. +.RE +.PP +background_thread (\fBbool\fR) rw +.RS 4 +Enable/disable internal background worker threads\&. When set to true, background threads are created on demand (the number of background threads will be no more than the number of CPUs or active arenas)\&. Threads run periodically, and handle +purging +asynchronously\&. When switching off, background threads are terminated synchronously\&. Note that after +\fBfork\fR(2) +function, the state in the child process will be disabled regardless the state in parent process\&. See +stats\&.background_thread +for related stats\&. +opt\&.background_thread +can be used to set the default option\&. This option is only available on selected pthread\-based platforms\&. +.RE +.PP +max_background_threads (\fBsize_t\fR) rw +.RS 4 +Maximum number of background worker threads that will be created\&. This value is capped at +opt\&.max_background_threads +at startup\&. +.RE +.PP +config\&.cache_oblivious (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-cache\-oblivious\fR +was specified during build configuration\&. +.RE +.PP +config\&.debug (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-debug\fR +was specified during build configuration\&. +.RE +.PP +config\&.fill (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-fill\fR +was specified during build configuration\&. +.RE +.PP +config\&.lazy_lock (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-lazy\-lock\fR +was specified during build configuration\&. +.RE +.PP +config\&.malloc_conf (\fBconst char *\fR) r\- +.RS 4 +Embedded configure\-time\-specified run\-time options string, empty unless +\fB\-\-with\-malloc\-conf\fR +was specified during build configuration\&. +.RE +.PP +config\&.prof (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-prof\fR +was specified during build configuration\&. +.RE +.PP +config\&.prof_libgcc (\fBbool\fR) r\- +.RS 4 +\fB\-\-disable\-prof\-libgcc\fR +was not specified during build configuration\&. +.RE +.PP +config\&.prof_libunwind (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-prof\-libunwind\fR +was specified during build configuration\&. +.RE +.PP +config\&.stats (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-stats\fR +was specified during build configuration\&. +.RE +.PP +config\&.utrace (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-utrace\fR +was specified during build configuration\&. +.RE +.PP +config\&.xmalloc (\fBbool\fR) r\- +.RS 4 +\fB\-\-enable\-xmalloc\fR +was specified during build configuration\&. +.RE +.PP +opt\&.abort (\fBbool\fR) r\- +.RS 4 +Abort\-on\-warning enabled/disabled\&. If true, most warnings are fatal\&. Note that runtime option warnings are not included (see +opt\&.abort_conf +for that)\&. The process will call +\fBabort\fR(3) +in these cases\&. This option is disabled by default unless +\fB\-\-enable\-debug\fR +is specified during configuration, in which case it is enabled by default\&. +.RE +.PP +opt\&.confirm_conf (\fBbool\fR) r\- +.RS 4 +Confirm\-runtime\-options\-when\-program\-starts enabled/disabled\&. If true, the string specified via +\fB\-\-with\-malloc\-conf\fR, the string pointed to by the global variable +\fImalloc_conf\fR, the +\(lqname\(rq +of the file referenced by the symbolic link named +/etc/malloc\&.conf, and the value of the environment variable +\fBMALLOC_CONF\fR, will be printed in order\&. Then, each option being set will be individually printed\&. This option is disabled by default\&. +.RE +.PP +opt\&.abort_conf (\fBbool\fR) r\- +.RS 4 +Abort\-on\-invalid\-configuration enabled/disabled\&. If true, invalid runtime options are fatal\&. The process will call +\fBabort\fR(3) +in these cases\&. This option is disabled by default unless +\fB\-\-enable\-debug\fR +is specified during configuration, in which case it is enabled by default\&. +.RE +.PP +opt\&.cache_oblivious (\fBbool\fR) r\- +.RS 4 +Enable / Disable cache\-oblivious large allocation alignment, for large requests with no alignment constraints\&. If this feature is disabled, all large allocations are page\-aligned as an implementation artifact, which can severely harm CPU cache utilization\&. However, the cache\-oblivious layout comes at the cost of one extra page per large allocation, which in the most extreme case increases physical memory usage for the 16 KiB size class to 20 KiB\&. This option is enabled by default\&. +.RE +.PP +opt\&.metadata_thp (\fBconst char *\fR) r\- +.RS 4 +Controls whether to allow jemalloc to use transparent huge page (THP) for internal metadata (see +stats\&.metadata)\&. +\(lqalways\(rq +allows such usage\&. +\(lqauto\(rq +uses no THP initially, but may begin to do so when metadata usage reaches certain level\&. The default is +\(lqdisabled\(rq\&. +.RE +.PP +opt\&.trust_madvise (\fBbool\fR) r\- +.RS 4 +If true, do not perform runtime check for MADV_DONTNEED, to check that it actually zeros pages\&. The default is disabled on Linux and enabled elsewhere\&. +.RE +.PP +opt\&.retain (\fBbool\fR) r\- +.RS 4 +If true, retain unused virtual memory for later reuse rather than discarding it by calling +\fBmunmap\fR(2) +or equivalent (see +stats\&.retained +for related details)\&. It also makes jemalloc use +\fBmmap\fR(2) +or equivalent in a more greedy way, mapping larger chunks in one go\&. This option is disabled by default unless discarding virtual memory is known to trigger platform\-specific performance problems, namely 1) for [64\-bit] Linux, which has a quirk in its virtual memory allocation algorithm that causes semi\-permanent VM map holes under normal jemalloc operation; and 2) for [64\-bit] Windows, which disallows split / merged regions with +\fI\fBMEM_RELEASE\fR\fR\&. Although the same issues may present on 32\-bit platforms as well, retaining virtual memory for 32\-bit Linux and Windows is disabled by default due to the practical possibility of address space exhaustion\&. +.RE +.PP +opt\&.dss (\fBconst char *\fR) r\- +.RS 4 +dss (\fBsbrk\fR(2)) allocation precedence as related to +\fBmmap\fR(2) +allocation\&. The following settings are supported if +\fBsbrk\fR(2) +is supported by the operating system: +\(lqdisabled\(rq, +\(lqprimary\(rq, and +\(lqsecondary\(rq; otherwise only +\(lqdisabled\(rq +is supported\&. The default is +\(lqsecondary\(rq +if +\fBsbrk\fR(2) +is supported by the operating system; +\(lqdisabled\(rq +otherwise\&. +.RE +.PP +opt\&.narenas (\fBunsigned\fR) r\- +.RS 4 +Maximum number of arenas to use for automatic multiplexing of threads and arenas\&. The default is four times the number of CPUs, or one if there is a single CPU\&. +.RE +.PP +opt\&.oversize_threshold (\fBsize_t\fR) r\- +.RS 4 +The threshold in bytes of which requests are considered oversize\&. Allocation requests with greater sizes are fulfilled from a dedicated arena (automatically managed, however not within +narenas), in order to reduce fragmentation by not mixing huge allocations with small ones\&. In addition, the decay API guarantees on the extents greater than the specified threshold may be overridden\&. Note that requests with arena index specified via +\fBMALLOCX_ARENA\fR, or threads associated with explicit arenas will not be considered\&. The default threshold is 8MiB\&. Values not within large size classes disables this feature\&. +.RE +.PP +opt\&.percpu_arena (\fBconst char *\fR) r\- +.RS 4 +Per CPU arena mode\&. Use the +\(lqpercpu\(rq +setting to enable this feature, which uses number of CPUs to determine number of arenas, and bind threads to arenas dynamically based on the CPU the thread runs on currently\&. +\(lqphycpu\(rq +setting uses one arena per physical CPU, which means the two hyper threads on the same CPU share one arena\&. Note that no runtime checking regarding the availability of hyper threading is done at the moment\&. When set to +\(lqdisabled\(rq, narenas and thread to arena association will not be impacted by this option\&. The default is +\(lqdisabled\(rq\&. +.RE +.PP +opt\&.background_thread (\fBbool\fR) r\- +.RS 4 +Internal background worker threads enabled/disabled\&. Because of potential circular dependencies, enabling background thread using this option may cause crash or deadlock during initialization\&. For a reliable way to use this feature, see +background_thread +for dynamic control options and details\&. This option is disabled by default\&. +.RE +.PP +opt\&.max_background_threads (\fBsize_t\fR) r\- +.RS 4 +Maximum number of background threads that will be created if +background_thread +is set\&. Defaults to number of cpus\&. +.RE +.PP +opt\&.dirty_decay_ms (\fBssize_t\fR) r\- +.RS 4 +Approximate time in milliseconds from the creation of a set of unused dirty pages until an equivalent set of unused dirty pages is purged (i\&.e\&. converted to muzzy via e\&.g\&. +madvise(\fI\&.\&.\&.\fR\fI\fBMADV_FREE\fR\fR) +if supported by the operating system, or converted to clean otherwise) and/or reused\&. Dirty pages are defined as previously having been potentially written to by the application, and therefore consuming physical memory, yet having no current use\&. The pages are incrementally purged according to a sigmoidal decay curve that starts and ends with zero purge rate\&. A decay time of 0 causes all unused dirty pages to be purged immediately upon creation\&. A decay time of \-1 disables purging\&. The default decay time is 10 seconds\&. See +arenas\&.dirty_decay_ms +and +arena\&.\&.dirty_decay_ms +for related dynamic control options\&. See +opt\&.muzzy_decay_ms +for a description of muzzy pages\&.for a description of muzzy pages\&. Note that when the +oversize_threshold +feature is enabled, the arenas reserved for oversize requests may have its own default decay settings\&. +.RE +.PP +opt\&.muzzy_decay_ms (\fBssize_t\fR) r\- +.RS 4 +Approximate time in milliseconds from the creation of a set of unused muzzy pages until an equivalent set of unused muzzy pages is purged (i\&.e\&. converted to clean) and/or reused\&. Muzzy pages are defined as previously having been unused dirty pages that were subsequently purged in a manner that left them subject to the reclamation whims of the operating system (e\&.g\&. +madvise(\fI\&.\&.\&.\fR\fI\fBMADV_FREE\fR\fR)), and therefore in an indeterminate state\&. The pages are incrementally purged according to a sigmoidal decay curve that starts and ends with zero purge rate\&. A decay time of 0 causes all unused muzzy pages to be purged immediately upon creation\&. A decay time of \-1 disables purging\&. The default decay time is 10 seconds\&. See +arenas\&.muzzy_decay_ms +and +arena\&.\&.muzzy_decay_ms +for related dynamic control options\&. +.RE +.PP +opt\&.lg_extent_max_active_fit (\fBsize_t\fR) r\- +.RS 4 +When reusing dirty extents, this determines the (log base 2 of the) maximum ratio between the size of the active extent selected (to split off from) and the size of the requested allocation\&. This prevents the splitting of large active extents for smaller allocations, which can reduce fragmentation over the long run (especially for non\-active extents)\&. Lower value may reduce fragmentation, at the cost of extra active extents\&. The default value is 6, which gives a maximum ratio of 64 (2^6)\&. +.RE +.PP +opt\&.stats_print (\fBbool\fR) r\- +.RS 4 +Enable/disable statistics printing at exit\&. If enabled, the +malloc_stats_print() +function is called at program exit via an +\fBatexit\fR(3) +function\&. +opt\&.stats_print_opts +can be combined to specify output options\&. If +\fB\-\-enable\-stats\fR +is specified during configuration, this has the potential to cause deadlock for a multi\-threaded process that exits while one or more threads are executing in the memory allocation functions\&. Furthermore, +atexit() +may allocate memory during application initialization and then deadlock internally when jemalloc in turn calls +atexit(), so this option is not universally usable (though the application can register its own +atexit() +function with equivalent functionality)\&. Therefore, this option should only be used with care; it is primarily intended as a performance tuning aid during application development\&. This option is disabled by default\&. +.RE +.PP +opt\&.stats_print_opts (\fBconst char *\fR) r\- +.RS 4 +Options (the +\fIopts\fR +string) to pass to the +malloc_stats_print() +at exit (enabled through +opt\&.stats_print)\&. See available options in +malloc_stats_print()\&. Has no effect unless +opt\&.stats_print +is enabled\&. The default is +\(lq\(rq\&. +.RE +.PP +opt\&.stats_interval (\fBint64_t\fR) r\- +.RS 4 +Average interval between statistics outputs, as measured in bytes of allocation activity\&. The actual interval may be sporadic because decentralized event counters are used to avoid synchronization bottlenecks\&. The output may be triggered on any thread, which then calls +malloc_stats_print()\&. +opt\&.stats_interval_opts +can be combined to specify output options\&. By default, interval\-triggered stats output is disabled (encoded as \-1)\&. +.RE +.PP +opt\&.stats_interval_opts (\fBconst char *\fR) r\- +.RS 4 +Options (the +\fIopts\fR +string) to pass to the +malloc_stats_print() +for interval based statistics printing (enabled through +opt\&.stats_interval)\&. See available options in +malloc_stats_print()\&. Has no effect unless +opt\&.stats_interval +is enabled\&. The default is +\(lq\(rq\&. +.RE +.PP +opt\&.junk (\fBconst char *\fR) r\- [\fB\-\-enable\-fill\fR] +.RS 4 +Junk filling\&. If set to +\(lqalloc\(rq, each byte of uninitialized allocated memory will be initialized to +0xa5\&. If set to +\(lqfree\(rq, all deallocated memory will be initialized to +0x5a\&. If set to +\(lqtrue\(rq, both allocated and deallocated memory will be initialized, and if set to +\(lqfalse\(rq, junk filling be disabled entirely\&. This is intended for debugging and will impact performance negatively\&. This option is +\(lqfalse\(rq +by default unless +\fB\-\-enable\-debug\fR +is specified during configuration, in which case it is +\(lqtrue\(rq +by default\&. +.RE +.PP +opt\&.zero (\fBbool\fR) r\- [\fB\-\-enable\-fill\fR] +.RS 4 +Zero filling enabled/disabled\&. If enabled, each byte of uninitialized allocated memory will be initialized to 0\&. Note that this initialization only happens once for each byte, so +realloc() +and +rallocx() +calls do not zero memory that was previously allocated\&. This is intended for debugging and will impact performance negatively\&. This option is disabled by default\&. +.RE +.PP +opt\&.utrace (\fBbool\fR) r\- [\fB\-\-enable\-utrace\fR] +.RS 4 +Allocation tracing based on +\fButrace\fR(2) +enabled/disabled\&. This option is disabled by default\&. +.RE +.PP +opt\&.xmalloc (\fBbool\fR) r\- [\fB\-\-enable\-xmalloc\fR] +.RS 4 +Abort\-on\-out\-of\-memory enabled/disabled\&. If enabled, rather than returning failure for any allocation function, display a diagnostic message on +\fBSTDERR_FILENO\fR +and cause the program to drop core (using +\fBabort\fR(3))\&. If an application is designed to depend on this behavior, set the option at compile time by including the following in the source code: +.sp +.if n \{\ +.RS 4 +.\} +.nf +malloc_conf = "xmalloc:true"; +.fi +.if n \{\ +.RE +.\} +.sp +This option is disabled by default\&. +.RE +.PP +opt\&.tcache (\fBbool\fR) r\- +.RS 4 +Thread\-specific caching (tcache) enabled/disabled\&. When there are multiple threads, each thread uses a tcache for objects up to a certain size\&. Thread\-specific caching allows many allocations to be satisfied without performing any thread synchronization, at the cost of increased memory use\&. See the +opt\&.tcache_max +option for related tuning information\&. This option is enabled by default\&. +.RE +.PP +opt\&.tcache_max (\fBsize_t\fR) r\- +.RS 4 +Maximum size class to cache in the thread\-specific cache (tcache)\&. At a minimum, the first size class is cached; and at a maximum, size classes up to 8 MiB can be cached\&. The default maximum is 32 KiB (2^15)\&. As a convenience, this may also be set by specifying lg_tcache_max, which will be taken to be the base\-2 logarithm of the setting of tcache_max\&. +.RE +.PP +opt\&.thp (\fBconst char *\fR) r\- +.RS 4 +Transparent hugepage (THP) mode\&. Settings "always", "never" and "default" are available if THP is supported by the operating system\&. The "always" setting enables transparent hugepage for all user memory mappings with +\fI\fBMADV_HUGEPAGE\fR\fR; "never" ensures no transparent hugepage with +\fI\fBMADV_NOHUGEPAGE\fR\fR; the default setting "default" makes no changes\&. Note that: this option does not affect THP for jemalloc internal metadata (see +opt\&.metadata_thp); in addition, for arenas with customized +extent_hooks, this option is bypassed as it is implemented as part of the default extent hooks\&. +.RE +.PP +opt\&.prof (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Memory profiling enabled/disabled\&. If enabled, profile memory allocation activity\&. See the +opt\&.prof_active +option for on\-the\-fly activation/deactivation\&. See the +opt\&.lg_prof_sample +option for probabilistic sampling control\&. See the +opt\&.prof_accum +option for control of cumulative sample reporting\&. See the +opt\&.lg_prof_interval +option for information on interval\-triggered profile dumping, the +opt\&.prof_gdump +option for information on high\-water\-triggered profile dumping, and the +opt\&.prof_final +option for final profile dumping\&. Profile output is compatible with the +\fBjeprof\fR +command, which is based on the +\fBpprof\fR +that is developed as part of the +\m[blue]\fBgperftools package\fR\m[]\&\s-2\u[3]\d\s+2\&. See +HEAP PROFILE FORMAT +for heap profile format documentation\&. +.RE +.PP +opt\&.prof_prefix (\fBconst char *\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Filename prefix for profile dumps\&. If the prefix is set to the empty string, no automatic dumps will occur; this is primarily useful for disabling the automatic final heap dump (which also disables leak reporting, if enabled)\&. The default prefix is +jeprof\&. This prefix value can be overridden by +prof\&.prefix\&. +.RE +.PP +opt\&.prof_active (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Profiling activated/deactivated\&. This is a secondary control mechanism that makes it possible to start the application with profiling enabled (see the +opt\&.prof +option) but inactive, then toggle profiling at any time during program execution with the +prof\&.active +mallctl\&. This option is enabled by default\&. +.RE +.PP +opt\&.prof_thread_active_init (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Initial setting for +thread\&.prof\&.active +in newly created threads\&. The initial setting for newly created threads can also be changed during execution via the +prof\&.thread_active_init +mallctl\&. This option is enabled by default\&. +.RE +.PP +opt\&.lg_prof_sample (\fBsize_t\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Average interval (log base 2) between allocation samples, as measured in bytes of allocation activity\&. Increasing the sampling interval decreases profile fidelity, but also decreases the computational overhead\&. The default sample interval is 512 KiB (2^19 B)\&. +.RE +.PP +opt\&.prof_accum (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Reporting of cumulative object/byte counts in profile dumps enabled/disabled\&. If this option is enabled, every unique backtrace must be stored for the duration of execution\&. Depending on the application, this can impose a large memory overhead, and the cumulative counts are not always of interest\&. This option is disabled by default\&. +.RE +.PP +opt\&.lg_prof_interval (\fBssize_t\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Average interval (log base 2) between memory profile dumps, as measured in bytes of allocation activity\&. The actual interval between dumps may be sporadic because decentralized allocation counters are used to avoid synchronization bottlenecks\&. Profiles are dumped to files named according to the pattern +\&.\&.\&.i\&.heap, where + +is controlled by the +opt\&.prof_prefix +and +prof\&.prefix +options\&. By default, interval\-triggered profile dumping is disabled (encoded as \-1)\&. +.RE +.PP +opt\&.prof_gdump (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Set the initial state of +prof\&.gdump, which when enabled triggers a memory profile dump every time the total virtual memory exceeds the previous maximum\&. This option is disabled by default\&. +.RE +.PP +opt\&.prof_final (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Use an +\fBatexit\fR(3) +function to dump final memory usage to a file named according to the pattern +\&.\&.\&.f\&.heap, where + +is controlled by the +opt\&.prof_prefix +and +prof\&.prefix +options\&. Note that +atexit() +may allocate memory during application initialization and then deadlock internally when jemalloc in turn calls +atexit(), so this option is not universally usable (though the application can register its own +atexit() +function with equivalent functionality)\&. This option is disabled by default\&. +.RE +.PP +opt\&.prof_leak (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Leak reporting enabled/disabled\&. If enabled, use an +\fBatexit\fR(3) +function to report memory leaks detected by allocation sampling\&. See the +opt\&.prof +option for information on analyzing heap profile output\&. Works only when combined with +opt\&.prof_final, otherwise does nothing\&. This option is disabled by default\&. +.RE +.PP +opt\&.prof_leak_error (\fBbool\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Similar to +opt\&.prof_leak, but makes the process exit with error code 1 if a memory leak is detected\&. This option supersedes +opt\&.prof_leak, meaning that if both are specified, this option takes precedence\&. When enabled, also enables +opt\&.prof_leak\&. Works only when combined with +opt\&.prof_final, otherwise does nothing\&. This option is disabled by default\&. +.RE +.PP +opt\&.zero_realloc (\fBconst char *\fR) r\- +.RS 4 +Determines the behavior of +realloc() +when passed a value of zero for the new size\&. +\(lqalloc\(rq +treats this as an allocation of size zero (and returns a non\-null result except in case of resource exhaustion)\&. +\(lqfree\(rq +treats this as a deallocation of the pointer, and returns +\fBNULL\fR +without setting +\fIerrno\fR\&. +\(lqabort\(rq +aborts the process if zero is passed\&. The default is +\(lqfree\(rq +on Linux and Windows, and +\(lqalloc\(rq +elsewhere\&. +.sp +There is considerable divergence of behaviors across implementations in handling this case\&. Many have the behavior of +\(lqfree\(rq\&. This can introduce security vulnerabilities, since a +\fBNULL\fR +return value indicates failure, and the continued validity of the passed\-in pointer (per POSIX and C11)\&. +\(lqalloc\(rq +is safe, but can cause leaks in programs that expect the common behavior\&. Programs intended to be portable and leak\-free cannot assume either behavior, and must therefore never call realloc with a size of 0\&. The +\(lqabort\(rq +option enables these testing this behavior\&. +.RE +.PP +thread\&.arena (\fBunsigned\fR) rw +.RS 4 +Get or set the arena associated with the calling thread\&. If the specified arena was not initialized beforehand (see the +arena\&.i\&.initialized +mallctl), it will be automatically initialized as a side effect of calling this interface\&. +.RE +.PP +thread\&.allocated (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Get the total number of bytes ever allocated by the calling thread\&. This counter has the potential to wrap around; it is up to the application to appropriately interpret the counter in such cases\&. +.RE +.PP +thread\&.allocatedp (\fBuint64_t *\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Get a pointer to the the value that is returned by the +thread\&.allocated +mallctl\&. This is useful for avoiding the overhead of repeated +mallctl*() +calls\&. Note that the underlying counter should not be modified by the application\&. +.RE +.PP +thread\&.deallocated (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Get the total number of bytes ever deallocated by the calling thread\&. This counter has the potential to wrap around; it is up to the application to appropriately interpret the counter in such cases\&. +.RE +.PP +thread\&.deallocatedp (\fBuint64_t *\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Get a pointer to the the value that is returned by the +thread\&.deallocated +mallctl\&. This is useful for avoiding the overhead of repeated +mallctl*() +calls\&. Note that the underlying counter should not be modified by the application\&. +.RE +.PP +thread\&.peak\&.read (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Get an approximation of the maximum value of the difference between the number of bytes allocated and the number of bytes deallocated by the calling thread since the last call to +thread\&.peak\&.reset, or since the thread\*(Aqs creation if it has not called +thread\&.peak\&.reset\&. No guarantees are made about the quality of the approximation, but jemalloc currently endeavors to maintain accuracy to within one hundred kilobytes\&. +.RE +.PP +thread\&.peak\&.reset (\fBvoid\fR) \-\- [\fB\-\-enable\-stats\fR] +.RS 4 +Resets the counter for net bytes allocated in the calling thread to zero\&. This affects subsequent calls to +thread\&.peak\&.read, but not the values returned by +thread\&.allocated +or +thread\&.deallocated\&. +.RE +.PP +thread\&.tcache\&.enabled (\fBbool\fR) rw +.RS 4 +Enable/disable calling thread\*(Aqs tcache\&. The tcache is implicitly flushed as a side effect of becoming disabled (see +thread\&.tcache\&.flush)\&. +.RE +.PP +thread\&.tcache\&.flush (\fBvoid\fR) \-\- +.RS 4 +Flush calling thread\*(Aqs thread\-specific cache (tcache)\&. This interface releases all cached objects and internal data structures associated with the calling thread\*(Aqs tcache\&. Ordinarily, this interface need not be called, since automatic periodic incremental garbage collection occurs, and the thread cache is automatically discarded when a thread exits\&. However, garbage collection is triggered by allocation activity, so it is possible for a thread that stops allocating/deallocating to retain its cache indefinitely, in which case the developer may find manual flushing useful\&. +.RE +.PP +thread\&.prof\&.name (\fBconst char *\fR) r\- or \-w [\fB\-\-enable\-prof\fR] +.RS 4 +Get/set the descriptive name associated with the calling thread in memory profile dumps\&. An internal copy of the name string is created, so the input string need not be maintained after this interface completes execution\&. The output string of this interface should be copied for non\-ephemeral uses, because multiple implementation details can cause asynchronous string deallocation\&. Furthermore, each invocation of this interface can only read or write; simultaneous read/write is not supported due to string lifetime limitations\&. The name string must be nil\-terminated and comprised only of characters in the sets recognized by +\fBisgraph\fR(3) +and +\fBisblank\fR(3)\&. +.RE +.PP +thread\&.prof\&.active (\fBbool\fR) rw [\fB\-\-enable\-prof\fR] +.RS 4 +Control whether sampling is currently active for the calling thread\&. This is an activation mechanism in addition to +prof\&.active; both must be active for the calling thread to sample\&. This flag is enabled by default\&. +.RE +.PP +thread\&.idle (\fBvoid\fR) \-\- +.RS 4 +Hints to jemalloc that the calling thread will be idle for some nontrivial period of time (say, on the order of seconds), and that doing some cleanup operations may be beneficial\&. There are no guarantees as to what specific operations will be performed; currently this flushes the caller\*(Aqs tcache and may (according to some heuristic) purge its associated arena\&. +.sp +This is not intended to be a general\-purpose background activity mechanism, and threads should not wake up multiple times solely to call it\&. Rather, a thread waiting for a task should do a timed wait first, call +thread\&.idle +if no task appears in the timeout interval, and then do an untimed wait\&. For such a background activity mechanism, see +background_thread\&. +.RE +.PP +tcache\&.create (\fBunsigned\fR) r\- +.RS 4 +Create an explicit thread\-specific cache (tcache) and return an identifier that can be passed to the +\fBMALLOCX_TCACHE(\fR\fB\fItc\fR\fR\fB)\fR +macro to explicitly use the specified cache rather than the automatically managed one that is used by default\&. Each explicit cache can be used by only one thread at a time; the application must assure that this constraint holds\&. +.sp +If the amount of space supplied for storing the thread\-specific cache identifier does not equal +sizeof(\fBunsigned\fR), no thread\-specific cache will be created, no data will be written to the space pointed by +\fIoldp\fR, and +\fI*oldlenp\fR +will be set to 0\&. +.RE +.PP +tcache\&.flush (\fBunsigned\fR) \-w +.RS 4 +Flush the specified thread\-specific cache (tcache)\&. The same considerations apply to this interface as to +thread\&.tcache\&.flush, except that the tcache will never be automatically discarded\&. +.RE +.PP +tcache\&.destroy (\fBunsigned\fR) \-w +.RS 4 +Flush the specified thread\-specific cache (tcache) and make the identifier available for use during a future tcache creation\&. +.RE +.PP +arena\&.\&.initialized (\fBbool\fR) r\- +.RS 4 +Get whether the specified arena\*(Aqs statistics are initialized (i\&.e\&. the arena was initialized prior to the current epoch)\&. This interface can also be nominally used to query whether the merged statistics corresponding to +\fBMALLCTL_ARENAS_ALL\fR +are initialized (always true)\&. +.RE +.PP +arena\&.\&.decay (\fBvoid\fR) \-\- +.RS 4 +Trigger decay\-based purging of unused dirty/muzzy pages for arena , or for all arenas if equals +\fBMALLCTL_ARENAS_ALL\fR\&. The proportion of unused dirty/muzzy pages to be purged depends on the current time; see +opt\&.dirty_decay_ms +and +opt\&.muzy_decay_ms +for details\&. +.RE +.PP +arena\&.\&.purge (\fBvoid\fR) \-\- +.RS 4 +Purge all unused dirty pages for arena , or for all arenas if equals +\fBMALLCTL_ARENAS_ALL\fR\&. +.RE +.PP +arena\&.\&.reset (\fBvoid\fR) \-\- +.RS 4 +Discard all of the arena\*(Aqs extant allocations\&. This interface can only be used with arenas explicitly created via +arenas\&.create\&. None of the arena\*(Aqs discarded/cached allocations may accessed afterward\&. As part of this requirement, all thread caches which were used to allocate/deallocate in conjunction with the arena must be flushed beforehand\&. +.RE +.PP +arena\&.\&.destroy (\fBvoid\fR) \-\- +.RS 4 +Destroy the arena\&. Discard all of the arena\*(Aqs extant allocations using the same mechanism as for +arena\&.\&.reset +(with all the same constraints and side effects), merge the arena stats into those accessible at arena index +\fBMALLCTL_ARENAS_DESTROYED\fR, and then completely discard all metadata associated with the arena\&. Future calls to +arenas\&.create +may recycle the arena index\&. Destruction will fail if any threads are currently associated with the arena as a result of calls to +thread\&.arena\&. +.RE +.PP +arena\&.\&.dss (\fBconst char *\fR) rw +.RS 4 +Set the precedence of dss allocation as related to mmap allocation for arena , or for all arenas if equals +\fBMALLCTL_ARENAS_ALL\fR\&. See +opt\&.dss +for supported settings\&. +.RE +.PP +arena\&.\&.dirty_decay_ms (\fBssize_t\fR) rw +.RS 4 +Current per\-arena approximate time in milliseconds from the creation of a set of unused dirty pages until an equivalent set of unused dirty pages is purged and/or reused\&. Each time this interface is set, all currently unused dirty pages are considered to have fully decayed, which causes immediate purging of all unused dirty pages unless the decay time is set to \-1 (i\&.e\&. purging disabled)\&. See +opt\&.dirty_decay_ms +for additional information\&. +.RE +.PP +arena\&.\&.muzzy_decay_ms (\fBssize_t\fR) rw +.RS 4 +Current per\-arena approximate time in milliseconds from the creation of a set of unused muzzy pages until an equivalent set of unused muzzy pages is purged and/or reused\&. Each time this interface is set, all currently unused muzzy pages are considered to have fully decayed, which causes immediate purging of all unused muzzy pages unless the decay time is set to \-1 (i\&.e\&. purging disabled)\&. See +opt\&.muzzy_decay_ms +for additional information\&. +.RE +.PP +arena\&.\&.retain_grow_limit (\fBsize_t\fR) rw +.RS 4 +Maximum size to grow retained region (only relevant when +opt\&.retain +is enabled)\&. This controls the maximum increment to expand virtual memory, or allocation through +arena\&.extent_hooks\&. In particular, if customized extent hooks reserve physical memory (e\&.g\&. 1G huge pages), this is useful to control the allocation hook\*(Aqs input size\&. The default is no limit\&. +.RE +.PP +arena\&.\&.extent_hooks (\fBextent_hooks_t *\fR) rw +.RS 4 +Get or set the extent management hook functions for arena \&. The functions must be capable of operating on all extant extents associated with arena , usually by passing unknown extents to the replaced functions\&. In practice, it is feasible to control allocation for arenas explicitly created via +arenas\&.create +such that all extents originate from an application\-supplied extent allocator (by specifying the custom extent hook functions during arena creation)\&. However, the API guarantees for the automatically created arenas may be relaxed \-\- hooks set there may be called in a "best effort" fashion; in addition there may be extents created prior to the application having an opportunity to take over extent allocation\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +typedef extent_hooks_s extent_hooks_t; +struct extent_hooks_s { + extent_alloc_t *alloc; + extent_dalloc_t *dalloc; + extent_destroy_t *destroy; + extent_commit_t *commit; + extent_decommit_t *decommit; + extent_purge_t *purge_lazy; + extent_purge_t *purge_forced; + extent_split_t *split; + extent_merge_t *merge; +}; +.fi +.if n \{\ +.RE +.\} +.sp +The +\fBextent_hooks_t\fR +structure comprises function pointers which are described individually below\&. jemalloc uses these functions to manage extent lifetime, which starts off with allocation of mapped committed memory, in the simplest case followed by deallocation\&. However, there are performance and platform reasons to retain extents for later reuse\&. Cleanup attempts cascade from deallocation to decommit to forced purging to lazy purging, which gives the extent management functions opportunities to reject the most permanent cleanup operations in favor of less permanent (and often less costly) operations\&. All operations except allocation can be universally opted out of by setting the hook pointers to +\fBNULL\fR, or selectively opted out of by returning failure\&. Note that once the extent hook is set, the structure is accessed directly by the associated arenas, so it must remain valid for the entire lifetime of the arenas\&. +.HP \w'typedef\ void\ *(extent_alloc_t)('u +.BI "typedef void *(extent_alloc_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "new_addr" ", size_t\ " "size" ", size_t\ " "alignment" ", bool\ *" "zero" ", bool\ *" "commit" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent allocation function conforms to the +\fBextent_alloc_t\fR +type and upon success returns a pointer to +\fIsize\fR +bytes of mapped memory on behalf of arena +\fIarena_ind\fR +such that the extent\*(Aqs base address is a multiple of +\fIalignment\fR, as well as setting +\fI*zero\fR +to indicate whether the extent is zeroed and +\fI*commit\fR +to indicate whether the extent is committed\&. Upon error the function returns +\fBNULL\fR +and leaves +\fI*zero\fR +and +\fI*commit\fR +unmodified\&. The +\fIsize\fR +parameter is always a multiple of the page size\&. The +\fIalignment\fR +parameter is always a power of two at least as large as the page size\&. Zeroing is mandatory if +\fI*zero\fR +is true upon function entry\&. Committing is mandatory if +\fI*commit\fR +is true upon function entry\&. If +\fInew_addr\fR +is not +\fBNULL\fR, the returned pointer must be +\fInew_addr\fR +on success or +\fBNULL\fR +on error\&. Committed memory may be committed in absolute terms as on a system that does not overcommit, or in implicit terms as on a system that overcommits and satisfies physical memory needs on demand via soft page faults\&. Note that replacing the default extent allocation function makes the arena\*(Aqs +arena\&.\&.dss +setting irrelevant\&. +.HP \w'typedef\ bool\ (extent_dalloc_t)('u +.BI "typedef bool (extent_dalloc_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", bool\ " "committed" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent deallocation function conforms to the +\fBextent_dalloc_t\fR +type and deallocates an extent at given +\fIaddr\fR +and +\fIsize\fR +with +\fIcommitted\fR/decommited memory as indicated, on behalf of arena +\fIarena_ind\fR, returning false upon success\&. If the function returns true, this indicates opt\-out from deallocation; the virtual memory mapping associated with the extent remains mapped, in the same commit state, and available for future use, in which case it will be automatically retained for later reuse\&. +.HP \w'typedef\ void\ (extent_destroy_t)('u +.BI "typedef void (extent_destroy_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", bool\ " "committed" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent destruction function conforms to the +\fBextent_destroy_t\fR +type and unconditionally destroys an extent at given +\fIaddr\fR +and +\fIsize\fR +with +\fIcommitted\fR/decommited memory as indicated, on behalf of arena +\fIarena_ind\fR\&. This function may be called to destroy retained extents during arena destruction (see +arena\&.\&.destroy)\&. +.HP \w'typedef\ bool\ (extent_commit_t)('u +.BI "typedef bool (extent_commit_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", size_t\ " "offset" ", size_t\ " "length" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent commit function conforms to the +\fBextent_commit_t\fR +type and commits zeroed physical memory to back pages within an extent at given +\fIaddr\fR +and +\fIsize\fR +at +\fIoffset\fR +bytes, extending for +\fIlength\fR +on behalf of arena +\fIarena_ind\fR, returning false upon success\&. Committed memory may be committed in absolute terms as on a system that does not overcommit, or in implicit terms as on a system that overcommits and satisfies physical memory needs on demand via soft page faults\&. If the function returns true, this indicates insufficient physical memory to satisfy the request\&. +.HP \w'typedef\ bool\ (extent_decommit_t)('u +.BI "typedef bool (extent_decommit_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", size_t\ " "offset" ", size_t\ " "length" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent decommit function conforms to the +\fBextent_decommit_t\fR +type and decommits any physical memory that is backing pages within an extent at given +\fIaddr\fR +and +\fIsize\fR +at +\fIoffset\fR +bytes, extending for +\fIlength\fR +on behalf of arena +\fIarena_ind\fR, returning false upon success, in which case the pages will be committed via the extent commit function before being reused\&. If the function returns true, this indicates opt\-out from decommit; the memory remains committed and available for future use, in which case it will be automatically retained for later reuse\&. +.HP \w'typedef\ bool\ (extent_purge_t)('u +.BI "typedef bool (extent_purge_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", size_t\ " "offset" ", size_t\ " "length" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent purge function conforms to the +\fBextent_purge_t\fR +type and discards physical pages within the virtual memory mapping associated with an extent at given +\fIaddr\fR +and +\fIsize\fR +at +\fIoffset\fR +bytes, extending for +\fIlength\fR +on behalf of arena +\fIarena_ind\fR\&. A lazy extent purge function (e\&.g\&. implemented via +madvise(\fI\&.\&.\&.\fR\fI\fBMADV_FREE\fR\fR)) can delay purging indefinitely and leave the pages within the purged virtual memory range in an indeterminite state, whereas a forced extent purge function immediately purges, and the pages within the virtual memory range will be zero\-filled the next time they are accessed\&. If the function returns true, this indicates failure to purge\&. +.HP \w'typedef\ bool\ (extent_split_t)('u +.BI "typedef bool (extent_split_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr" ", size_t\ " "size" ", size_t\ " "size_a" ", size_t\ " "size_b" ", bool\ " "committed" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent split function conforms to the +\fBextent_split_t\fR +type and optionally splits an extent at given +\fIaddr\fR +and +\fIsize\fR +into two adjacent extents, the first of +\fIsize_a\fR +bytes, and the second of +\fIsize_b\fR +bytes, operating on +\fIcommitted\fR/decommitted memory as indicated, on behalf of arena +\fIarena_ind\fR, returning false upon success\&. If the function returns true, this indicates that the extent remains unsplit and therefore should continue to be operated on as a whole\&. +.HP \w'typedef\ bool\ (extent_merge_t)('u +.BI "typedef bool (extent_merge_t)(extent_hooks_t\ *" "extent_hooks" ", void\ *" "addr_a" ", size_t\ " "size_a" ", void\ *" "addr_b" ", size_t\ " "size_b" ", bool\ " "committed" ", unsigned\ " "arena_ind" ");" +.sp +.if n \{\ +.RS 4 +.\} +.nf +.fi +.if n \{\ +.RE +.\} +.sp +An extent merge function conforms to the +\fBextent_merge_t\fR +type and optionally merges adjacent extents, at given +\fIaddr_a\fR +and +\fIsize_a\fR +with given +\fIaddr_b\fR +and +\fIsize_b\fR +into one contiguous extent, operating on +\fIcommitted\fR/decommitted memory as indicated, on behalf of arena +\fIarena_ind\fR, returning false upon success\&. If the function returns true, this indicates that the extents remain distinct mappings and therefore should continue to be operated on independently\&. +.RE +.PP +arenas\&.narenas (\fBunsigned\fR) r\- +.RS 4 +Current limit on number of arenas\&. +.RE +.PP +arenas\&.dirty_decay_ms (\fBssize_t\fR) rw +.RS 4 +Current default per\-arena approximate time in milliseconds from the creation of a set of unused dirty pages until an equivalent set of unused dirty pages is purged and/or reused, used to initialize +arena\&.\&.dirty_decay_ms +during arena creation\&. See +opt\&.dirty_decay_ms +for additional information\&. +.RE +.PP +arenas\&.muzzy_decay_ms (\fBssize_t\fR) rw +.RS 4 +Current default per\-arena approximate time in milliseconds from the creation of a set of unused muzzy pages until an equivalent set of unused muzzy pages is purged and/or reused, used to initialize +arena\&.\&.muzzy_decay_ms +during arena creation\&. See +opt\&.muzzy_decay_ms +for additional information\&. +.RE +.PP +arenas\&.quantum (\fBsize_t\fR) r\- +.RS 4 +Quantum size\&. +.RE +.PP +arenas\&.page (\fBsize_t\fR) r\- +.RS 4 +Page size\&. +.RE +.PP +arenas\&.tcache_max (\fBsize_t\fR) r\- +.RS 4 +Maximum thread\-cached size class\&. +.RE +.PP +arenas\&.nbins (\fBunsigned\fR) r\- +.RS 4 +Number of bin size classes\&. +.RE +.PP +arenas\&.nhbins (\fBunsigned\fR) r\- +.RS 4 +Total number of thread cache bin size classes\&. +.RE +.PP +arenas\&.bin\&.\&.size (\fBsize_t\fR) r\- +.RS 4 +Maximum size supported by size class\&. +.RE +.PP +arenas\&.bin\&.\&.nregs (\fBuint32_t\fR) r\- +.RS 4 +Number of regions per slab\&. +.RE +.PP +arenas\&.bin\&.\&.slab_size (\fBsize_t\fR) r\- +.RS 4 +Number of bytes per slab\&. +.RE +.PP +arenas\&.nlextents (\fBunsigned\fR) r\- +.RS 4 +Total number of large size classes\&. +.RE +.PP +arenas\&.lextent\&.\&.size (\fBsize_t\fR) r\- +.RS 4 +Maximum size supported by this large size class\&. +.RE +.PP +arenas\&.create (\fBunsigned\fR, \fBextent_hooks_t *\fR) rw +.RS 4 +Explicitly create a new arena outside the range of automatically managed arenas, with optionally specified extent hooks, and return the new arena index\&. +.sp +If the amount of space supplied for storing the arena index does not equal +sizeof(\fBunsigned\fR), no arena will be created, no data will be written to the space pointed by +\fIoldp\fR, and +\fI*oldlenp\fR +will be set to 0\&. +.RE +.PP +arenas\&.lookup (\fBunsigned\fR, \fBvoid*\fR) rw +.RS 4 +Index of the arena to which an allocation belongs to\&. +.RE +.PP +prof\&.thread_active_init (\fBbool\fR) rw [\fB\-\-enable\-prof\fR] +.RS 4 +Control the initial setting for +thread\&.prof\&.active +in newly created threads\&. See the +opt\&.prof_thread_active_init +option for additional information\&. +.RE +.PP +prof\&.active (\fBbool\fR) rw [\fB\-\-enable\-prof\fR] +.RS 4 +Control whether sampling is currently active\&. See the +opt\&.prof_active +option for additional information, as well as the interrelated +thread\&.prof\&.active +mallctl\&. +.RE +.PP +prof\&.dump (\fBconst char *\fR) \-w [\fB\-\-enable\-prof\fR] +.RS 4 +Dump a memory profile to the specified file, or if NULL is specified, to a file according to the pattern +\&.\&.\&.m\&.heap, where + +is controlled by the +opt\&.prof_prefix +and +prof\&.prefix +options\&. +.RE +.PP +prof\&.prefix (\fBconst char *\fR) \-w [\fB\-\-enable\-prof\fR] +.RS 4 +Set the filename prefix for profile dumps\&. See +opt\&.prof_prefix +for the default setting\&. This can be useful to differentiate profile dumps such as from forked processes\&. +.RE +.PP +prof\&.gdump (\fBbool\fR) rw [\fB\-\-enable\-prof\fR] +.RS 4 +When enabled, trigger a memory profile dump every time the total virtual memory exceeds the previous maximum\&. Profiles are dumped to files named according to the pattern +\&.\&.\&.u\&.heap, where + +is controlled by the +opt\&.prof_prefix +and +prof\&.prefix +options\&. +.RE +.PP +prof\&.reset (\fBsize_t\fR) \-w [\fB\-\-enable\-prof\fR] +.RS 4 +Reset all memory profile statistics, and optionally update the sample rate (see +opt\&.lg_prof_sample +and +prof\&.lg_sample)\&. +.RE +.PP +prof\&.lg_sample (\fBsize_t\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Get the current sample rate (see +opt\&.lg_prof_sample)\&. +.RE +.PP +prof\&.interval (\fBuint64_t\fR) r\- [\fB\-\-enable\-prof\fR] +.RS 4 +Average number of bytes allocated between interval\-based profile dumps\&. See the +opt\&.lg_prof_interval +option for additional information\&. +.RE +.PP +stats\&.allocated (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of bytes allocated by the application\&. +.RE +.PP +stats\&.active (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of bytes in active pages allocated by the application\&. This is a multiple of the page size, and greater than or equal to +stats\&.allocated\&. This does not include +stats\&.arenas\&.\&.pdirty, +stats\&.arenas\&.\&.pmuzzy, nor pages entirely devoted to allocator metadata\&. +.RE +.PP +stats\&.metadata (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of bytes dedicated to metadata, which comprise base allocations used for bootstrap\-sensitive allocator metadata structures (see +stats\&.arenas\&.\&.base) and internal allocations (see +stats\&.arenas\&.\&.internal)\&. Transparent huge page (enabled with +opt\&.metadata_thp) usage is not considered\&. +.RE +.PP +stats\&.metadata_thp (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of transparent huge pages (THP) used for metadata\&. See +stats\&.metadata +and +opt\&.metadata_thp) for details\&. +.RE +.PP +stats\&.resident (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Maximum number of bytes in physically resident data pages mapped by the allocator, comprising all pages dedicated to allocator metadata, pages backing active allocations, and unused dirty pages\&. This is a maximum rather than precise because pages may not actually be physically resident if they correspond to demand\-zeroed virtual memory that has not yet been touched\&. This is a multiple of the page size, and is larger than +stats\&.active\&. +.RE +.PP +stats\&.mapped (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of bytes in active extents mapped by the allocator\&. This is larger than +stats\&.active\&. This does not include inactive extents, even those that contain unused dirty pages, which means that there is no strict ordering between this and +stats\&.resident\&. +.RE +.PP +stats\&.retained (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of bytes in virtual memory mappings that were retained rather than being returned to the operating system via e\&.g\&. +\fBmunmap\fR(2) +or similar\&. Retained virtual memory is typically untouched, decommitted, or purged, so it has no strongly associated physical memory (see +extent hooks +for details)\&. Retained memory is excluded from mapped memory statistics, e\&.g\&. +stats\&.mapped\&. +.RE +.PP +stats\&.zero_reallocs (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of times that the +realloc() +was called with a non\-\fBNULL\fR +pointer argument and a +\fB0\fR +size argument\&. This is a fundamentally unsafe pattern in portable programs; see +opt\&.zero_realloc +for details\&. +.RE +.PP +stats\&.background_thread\&.num_threads (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of +background threads +running currently\&. +.RE +.PP +stats\&.background_thread\&.num_runs (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Total number of runs from all +background threads\&. +.RE +.PP +stats\&.background_thread\&.run_interval (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Average run interval in nanoseconds of +background threads\&. +.RE +.PP +stats\&.mutexes\&.ctl\&.{counter}; (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIctl\fR +mutex (global scope; mallctl related)\&. +{counter} +is one of the counters below: +.PP +.RS 4 +\fInum_ops\fR +(\fBuint64_t\fR): Total number of lock acquisition operations on this mutex\&. +.sp +\fInum_spin_acq\fR +(\fBuint64_t\fR): Number of times the mutex was spin\-acquired\&. When the mutex is currently locked and cannot be acquired immediately, a short period of spin\-retry within jemalloc will be performed\&. Acquired through spin generally means the contention was lightweight and not causing context switches\&. +.sp +\fInum_wait\fR +(\fBuint64_t\fR): Number of times the mutex was wait\-acquired, which means the mutex contention was not solved by spin\-retry, and blocking operation was likely involved in order to acquire the mutex\&. This event generally implies higher cost / longer delay, and should be investigated if it happens often\&. +.sp +\fImax_wait_time\fR +(\fBuint64_t\fR): Maximum length of time in nanoseconds spent on a single wait\-acquired lock operation\&. Note that to avoid profiling overhead on the common path, this does not consider spin\-acquired cases\&. +.sp +\fItotal_wait_time\fR +(\fBuint64_t\fR): Cumulative time in nanoseconds spent on wait\-acquired lock operations\&. Similarly, spin\-acquired cases are not considered\&. +.sp +\fImax_num_thds\fR +(\fBuint32_t\fR): Maximum number of threads waiting on this mutex simultaneously\&. Similarly, spin\-acquired cases are not considered\&. +.sp +\fInum_owner_switch\fR +(\fBuint64_t\fR): Number of times the current mutex owner is different from the previous one\&. This event does not generally imply an issue; rather it is an indicator of how often the protected data are accessed by different threads\&. +.RE +.RE +.PP +stats\&.mutexes\&.background_thread\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIbackground_thread\fR +mutex (global scope; +background_thread +related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.mutexes\&.prof\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIprof\fR +mutex (global scope; profiling related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.mutexes\&.prof_thds_data\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIprof\fR +threads data mutex (global scope; profiling related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.mutexes\&.prof_dump\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIprof\fR +dumping mutex (global scope; profiling related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.mutexes\&.reset (\fBvoid\fR) \-\- [\fB\-\-enable\-stats\fR] +.RS 4 +Reset all mutex profile statistics, including global mutexes, arena mutexes and bin mutexes\&. +.RE +.PP +stats\&.arenas\&.\&.dss (\fBconst char *\fR) r\- +.RS 4 +dss (\fBsbrk\fR(2)) allocation precedence as related to +\fBmmap\fR(2) +allocation\&. See +opt\&.dss +for details\&. +.RE +.PP +stats\&.arenas\&.\&.dirty_decay_ms (\fBssize_t\fR) r\- +.RS 4 +Approximate time in milliseconds from the creation of a set of unused dirty pages until an equivalent set of unused dirty pages is purged and/or reused\&. See +opt\&.dirty_decay_ms +for details\&. +.RE +.PP +stats\&.arenas\&.\&.muzzy_decay_ms (\fBssize_t\fR) r\- +.RS 4 +Approximate time in milliseconds from the creation of a set of unused muzzy pages until an equivalent set of unused muzzy pages is purged and/or reused\&. See +opt\&.muzzy_decay_ms +for details\&. +.RE +.PP +stats\&.arenas\&.\&.nthreads (\fBunsigned\fR) r\- +.RS 4 +Number of threads currently assigned to arena\&. +.RE +.PP +stats\&.arenas\&.\&.uptime (\fBuint64_t\fR) r\- +.RS 4 +Time elapsed (in nanoseconds) since the arena was created\&. If equals +\fB0\fR +or +\fBMALLCTL_ARENAS_ALL\fR, this is the uptime since malloc initialization\&. +.RE +.PP +stats\&.arenas\&.\&.pactive (\fBsize_t\fR) r\- +.RS 4 +Number of pages in active extents\&. +.RE +.PP +stats\&.arenas\&.\&.pdirty (\fBsize_t\fR) r\- +.RS 4 +Number of pages within unused extents that are potentially dirty, and for which +madvise() +or similar has not been called\&. See +opt\&.dirty_decay_ms +for a description of dirty pages\&. +.RE +.PP +stats\&.arenas\&.\&.pmuzzy (\fBsize_t\fR) r\- +.RS 4 +Number of pages within unused extents that are muzzy\&. See +opt\&.muzzy_decay_ms +for a description of muzzy pages\&. +.RE +.PP +stats\&.arenas\&.\&.mapped (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of mapped bytes\&. +.RE +.PP +stats\&.arenas\&.\&.retained (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of retained bytes\&. See +stats\&.retained +for details\&. +.RE +.PP +stats\&.arenas\&.\&.extent_avail (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of allocated (but unused) extent structs in this arena\&. +.RE +.PP +stats\&.arenas\&.\&.base (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of bytes dedicated to bootstrap\-sensitive allocator metadata structures\&. +.RE +.PP +stats\&.arenas\&.\&.internal (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of bytes dedicated to internal allocations\&. Internal allocations differ from application\-originated allocations in that they are for internal use, and that they are omitted from heap profiles\&. +.RE +.PP +stats\&.arenas\&.\&.metadata_thp (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of transparent huge pages (THP) used for metadata\&. See +opt\&.metadata_thp +for details\&. +.RE +.PP +stats\&.arenas\&.\&.resident (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Maximum number of bytes in physically resident data pages mapped by the arena, comprising all pages dedicated to allocator metadata, pages backing active allocations, and unused dirty pages\&. This is a maximum rather than precise because pages may not actually be physically resident if they correspond to demand\-zeroed virtual memory that has not yet been touched\&. This is a multiple of the page size\&. +.RE +.PP +stats\&.arenas\&.\&.dirty_npurge (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of dirty page purge sweeps performed\&. +.RE +.PP +stats\&.arenas\&.\&.dirty_nmadvise (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of +madvise() +or similar calls made to purge dirty pages\&. +.RE +.PP +stats\&.arenas\&.\&.dirty_purged (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of dirty pages purged\&. +.RE +.PP +stats\&.arenas\&.\&.muzzy_npurge (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of muzzy page purge sweeps performed\&. +.RE +.PP +stats\&.arenas\&.\&.muzzy_nmadvise (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of +madvise() +or similar calls made to purge muzzy pages\&. +.RE +.PP +stats\&.arenas\&.\&.muzzy_purged (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of muzzy pages purged\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.allocated (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of bytes currently allocated by small objects\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.nmalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a small allocation was requested from the arena\*(Aqs bins, whether to fill the relevant tcache if +opt\&.tcache +is enabled, or to directly satisfy an allocation request otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.ndalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a small allocation was returned to the arena\*(Aqs bins, whether to flush the relevant tcache if +opt\&.tcache +is enabled, or to directly deallocate an allocation otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.nrequests (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of allocation requests satisfied by all bin size classes\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.nfills (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of tcache fills by all small size classes\&. +.RE +.PP +stats\&.arenas\&.\&.small\&.nflushes (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of tcache flushes by all small size classes\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.allocated (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of bytes currently allocated by large objects\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.nmalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a large extent was allocated from the arena, whether to fill the relevant tcache if +opt\&.tcache +is enabled and the size class is within the range being cached, or to directly satisfy an allocation request otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.ndalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a large extent was returned to the arena, whether to flush the relevant tcache if +opt\&.tcache +is enabled and the size class is within the range being cached, or to directly deallocate an allocation otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.nrequests (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of allocation requests satisfied by all large size classes\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.nfills (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of tcache fills by all large size classes\&. +.RE +.PP +stats\&.arenas\&.\&.large\&.nflushes (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of tcache flushes by all large size classes\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nmalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a bin region of the corresponding size class was allocated from the arena, whether to fill the relevant tcache if +opt\&.tcache +is enabled, or to directly satisfy an allocation request otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.ndalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a bin region of the corresponding size class was returned to the arena, whether to flush the relevant tcache if +opt\&.tcache +is enabled, or to directly deallocate an allocation otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nrequests (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of allocation requests satisfied by bin regions of the corresponding size class\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.curregs (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Current number of regions for this size class\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nfills (\fBuint64_t\fR) r\- +.RS 4 +Cumulative number of tcache fills\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nflushes (\fBuint64_t\fR) r\- +.RS 4 +Cumulative number of tcache flushes\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nslabs (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of slabs created\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nreslabs (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times the current slab from which to allocate changed\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.curslabs (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Current number of slabs\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.nonfull_slabs (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Current number of nonfull slabs\&. +.RE +.PP +stats\&.arenas\&.\&.bins\&.\&.mutex\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.bins\&.\fR +mutex (arena bin scope; bin operation related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.extents\&.\&.n{extent_type} (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Number of extents of the given type in this arena in the bucket corresponding to page size index \&. The extent type is one of dirty, muzzy, or retained\&. +.RE +.PP +stats\&.arenas\&.\&.extents\&.\&.{extent_type}_bytes (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Sum of the bytes managed by extents of the given type in this arena in the bucket corresponding to page size index \&. The extent type is one of dirty, muzzy, or retained\&. +.RE +.PP +stats\&.arenas\&.\&.lextents\&.\&.nmalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a large extent of the corresponding size class was allocated from the arena, whether to fill the relevant tcache if +opt\&.tcache +is enabled and the size class is within the range being cached, or to directly satisfy an allocation request otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.lextents\&.\&.ndalloc (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of times a large extent of the corresponding size class was returned to the arena, whether to flush the relevant tcache if +opt\&.tcache +is enabled and the size class is within the range being cached, or to directly deallocate an allocation otherwise\&. +.RE +.PP +stats\&.arenas\&.\&.lextents\&.\&.nrequests (\fBuint64_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Cumulative number of allocation requests satisfied by large extents of the corresponding size class\&. +.RE +.PP +stats\&.arenas\&.\&.lextents\&.\&.curlextents (\fBsize_t\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Current number of large allocations for this size class\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.large\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.large\fR +mutex (arena scope; large allocation related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.extent_avail\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.extent_avail \fR +mutex (arena scope; extent avail related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.extents_dirty\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.extents_dirty \fR +mutex (arena scope; dirty extents related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.extents_muzzy\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.extents_muzzy \fR +mutex (arena scope; muzzy extents related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.extents_retained\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.extents_retained \fR +mutex (arena scope; retained extents related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.decay_dirty\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.decay_dirty \fR +mutex (arena scope; decay for dirty pages related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.decay_muzzy\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.decay_muzzy \fR +mutex (arena scope; decay for muzzy pages related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.base\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.base\fR +mutex (arena scope; base allocator related)\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.PP +stats\&.arenas\&.\&.mutexes\&.tcache_list\&.{counter} (\fBcounter specific type\fR) r\- [\fB\-\-enable\-stats\fR] +.RS 4 +Statistics on +\fIarena\&.\&.tcache_list\fR +mutex (arena scope; tcache to arena association related)\&. This mutex is expected to be accessed less often\&. +{counter} +is one of the counters in +mutex profiling counters\&. +.RE +.SH "HEAP PROFILE FORMAT" +.PP +Although the heap profiling functionality was originally designed to be compatible with the +\fBpprof\fR +command that is developed as part of the +\m[blue]\fBgperftools package\fR\m[]\&\s-2\u[3]\d\s+2, the addition of per thread heap profiling functionality required a different heap profile format\&. The +\fBjeprof\fR +command is derived from +\fBpprof\fR, with enhancements to support the heap profile format described here\&. +.PP +In the following hypothetical heap profile, +\fB[\&.\&.\&.]\fR +indicates elision for the sake of compactness\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +heap_v2/524288 + t*: 28106: 56637512 [0: 0] + [\&.\&.\&.] + t3: 352: 16777344 [0: 0] + [\&.\&.\&.] + t99: 17754: 29341640 [0: 0] + [\&.\&.\&.] +@ 0x5f86da8 0x5f5a1dc [\&.\&.\&.] 0x29e4d4e 0xa200316 0xabb2988 [\&.\&.\&.] + t*: 13: 6688 [0: 0] + t3: 12: 6496 [0: 0] + t99: 1: 192 [0: 0] +[\&.\&.\&.] + +MAPPED_LIBRARIES: +[\&.\&.\&.] +.fi +.if n \{\ +.RE +.\} +.sp +The following matches the above heap profile, but most tokens are replaced with +\fB\fR +to indicate descriptions of the corresponding fields\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +/ + : : [: ] + [\&.\&.\&.] + : : [: ] + [\&.\&.\&.] + : : [: ] + [\&.\&.\&.] +@ [\&.\&.\&.] [\&.\&.\&.] + : : [: ] + : : [: ] + : : [: ] +[\&.\&.\&.] + +MAPPED_LIBRARIES: +/maps> +.fi +.if n \{\ +.RE +.\} +.SH "DEBUGGING MALLOC PROBLEMS" +.PP +When debugging, it is a good idea to configure/build jemalloc with the +\fB\-\-enable\-debug\fR +and +\fB\-\-enable\-fill\fR +options, and recompile the program with suitable options and symbols for debugger support\&. When so configured, jemalloc incorporates a wide variety of run\-time assertions that catch application errors such as double\-free, write\-after\-free, etc\&. +.PP +Programs often accidentally depend on +\(lquninitialized\(rq +memory actually being filled with zero bytes\&. Junk filling (see the +opt\&.junk +option) tends to expose such bugs in the form of obviously incorrect results and/or coredumps\&. Conversely, zero filling (see the +opt\&.zero +option) eliminates the symptoms of such bugs\&. Between these two options, it is usually possible to quickly detect, diagnose, and eliminate such bugs\&. +.PP +This implementation does not provide much detail about the problems it detects, because the performance impact for storing such information would be prohibitive\&. +.SH "DIAGNOSTIC MESSAGES" +.PP +If any of the memory allocation/deallocation functions detect an error or warning condition, a message will be printed to file descriptor +\fBSTDERR_FILENO\fR\&. Errors will result in the process dumping core\&. If the +opt\&.abort +option is set, most warnings are treated as errors\&. +.PP +The +\fImalloc_message\fR +variable allows the programmer to override the function which emits the text strings forming the errors and warnings if for some reason the +\fBSTDERR_FILENO\fR +file descriptor is not suitable for this\&. +malloc_message() +takes the +\fIcbopaque\fR +pointer argument that is +\fBNULL\fR +unless overridden by the arguments in a call to +malloc_stats_print(), followed by a string pointer\&. Please note that doing anything which tries to allocate memory in this function is likely to result in a crash or deadlock\&. +.PP +All messages are prefixed by +\(lq: \(rq\&. +.SH "RETURN VALUES" +.SS "Standard API" +.PP +The +malloc() +and +calloc() +functions return a pointer to the allocated memory if successful; otherwise a +\fBNULL\fR +pointer is returned and +\fIerrno\fR +is set to +ENOMEM\&. +.PP +The +posix_memalign() +function returns the value 0 if successful; otherwise it returns an error value\&. The +posix_memalign() +function will fail if: +.PP +EINVAL +.RS 4 +The +\fIalignment\fR +parameter is not a power of 2 at least as large as +sizeof(\fBvoid *\fR)\&. +.RE +.PP +ENOMEM +.RS 4 +Memory allocation error\&. +.RE +.PP +The +aligned_alloc() +function returns a pointer to the allocated memory if successful; otherwise a +\fBNULL\fR +pointer is returned and +\fIerrno\fR +is set\&. The +aligned_alloc() +function will fail if: +.PP +EINVAL +.RS 4 +The +\fIalignment\fR +parameter is not a power of 2\&. +.RE +.PP +ENOMEM +.RS 4 +Memory allocation error\&. +.RE +.PP +The +realloc() +function returns a pointer, possibly identical to +\fIptr\fR, to the allocated memory if successful; otherwise a +\fBNULL\fR +pointer is returned, and +\fIerrno\fR +is set to +ENOMEM +if the error was the result of an allocation failure\&. The +realloc() +function always leaves the original buffer intact when an error occurs\&. +.PP +The +free() +function returns no value\&. +.SS "Non\-standard API" +.PP +The +mallocx() +and +rallocx() +functions return a pointer to the allocated memory if successful; otherwise a +\fBNULL\fR +pointer is returned to indicate insufficient contiguous memory was available to service the allocation request\&. +.PP +The +xallocx() +function returns the real size of the resulting resized allocation pointed to by +\fIptr\fR, which is a value less than +\fIsize\fR +if the allocation could not be adequately grown in place\&. +.PP +The +sallocx() +function returns the real size of the allocation pointed to by +\fIptr\fR\&. +.PP +The +nallocx() +returns the real size that would result from a successful equivalent +mallocx() +function call, or zero if insufficient memory is available to perform the size computation\&. +.PP +The +mallctl(), +mallctlnametomib(), and +mallctlbymib() +functions return 0 on success; otherwise they return an error value\&. The functions will fail if: +.PP +EINVAL +.RS 4 +\fInewp\fR +is not +\fBNULL\fR, and +\fInewlen\fR +is too large or too small\&. Alternatively, +\fI*oldlenp\fR +is too large or too small; when it happens, except for a very few cases explicitly documented otherwise, as much data as possible are read despite the error, with the amount of data read being recorded in +\fI*oldlenp\fR\&. +.RE +.PP +ENOENT +.RS 4 +\fIname\fR +or +\fImib\fR +specifies an unknown/invalid value\&. +.RE +.PP +EPERM +.RS 4 +Attempt to read or write void value, or attempt to write read\-only value\&. +.RE +.PP +EAGAIN +.RS 4 +A memory allocation failure occurred\&. +.RE +.PP +EFAULT +.RS 4 +An interface with side effects failed in some way not directly related to +mallctl*() +read/write processing\&. +.RE +.PP +The +malloc_usable_size() +function returns the usable size of the allocation pointed to by +\fIptr\fR\&. +.SH "ENVIRONMENT" +.PP +The following environment variable affects the execution of the allocation functions: +.PP +\fBMALLOC_CONF\fR +.RS 4 +If the environment variable +\fBMALLOC_CONF\fR +is set, the characters it contains will be interpreted as options\&. +.RE +.SH "EXAMPLES" +.PP +To dump core whenever a problem occurs: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ln \-s \*(Aqabort:true\*(Aq /etc/malloc\&.conf +.fi +.if n \{\ +.RE +.\} +.PP +To specify in the source that only one arena should be automatically created: +.sp +.if n \{\ +.RS 4 +.\} +.nf +malloc_conf = "narenas:1"; +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBmadvise\fR(2), +\fBmmap\fR(2), +\fBsbrk\fR(2), +\fButrace\fR(2), +\fBalloca\fR(3), +\fBatexit\fR(3), +\fBgetpagesize\fR(3) +.SH "STANDARDS" +.PP +The +malloc(), +calloc(), +realloc(), and +free() +functions conform to ISO/IEC 9899:1990 (\(lqISO C90\(rq)\&. +.PP +The +posix_memalign() +function conforms to IEEE Std 1003\&.1\-2001 (\(lqPOSIX\&.1\(rq)\&. +.SH "AUTHOR" +.PP +\fBJason Evans\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +jemalloc website +.RS 4 +\%http://jemalloc.net/ +.RE +.IP " 2." 4 +JSON format +.RS 4 +\%http://www.json.org/ +.RE +.IP " 3." 4 +gperftools package +.RS 4 +\%http://code.google.com/p/gperftools/ +.RE diff --git a/static/netbsd/man3/kadm5_pwcheck.3 b/static/netbsd/man3/kadm5_pwcheck.3 new file mode 100644 index 00000000..8b7495e0 --- /dev/null +++ b/static/netbsd/man3/kadm5_pwcheck.3 @@ -0,0 +1,161 @@ +.\" $NetBSD: kadm5_pwcheck.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd February 29, 2004 +.Dt KADM5_PWCHECK 3 +.Os +.Sh NAME +.Nm krb5_pwcheck , +.Nm kadm5_setup_passwd_quality_check , +.Nm kadm5_add_passwd_quality_verifier , +.Nm kadm5_check_password_quality +.Nd Heimdal warning and error functions +.Sh LIBRARY +Kerberos 5 Library (libkadm5srv, -lkadm5srv) +.Sh SYNOPSIS +.In kadm5-protos.h +.In kadm5-pwcheck.h +.Ft void +.Fo kadm5_setup_passwd_quality_check +.Fa "krb5_context context" +.Fa "const char *check_library" +.Fa "const char *check_function" +.Fc +.Ft "krb5_error_code" +.Fo kadm5_add_passwd_quality_verifier +.Fa "krb5_context context" +.Fa "const char *check_library" +.Fc +.Ft "const char *" +.Fo kadm5_check_password_quality +.Fa "krb5_context context" +.Fa "krb5_principal principal" +.Fa "krb5_data *pwd_data" +.Fc +.Ft int +.Fo "(*kadm5_passwd_quality_check_func)" +.Fa "krb5_context context" +.Fa "krb5_principal principal" +.Fa "krb5_data *password" +.Fa "const char *tuning" +.Fa "char *message" +.Fa "size_t length" +.Fc +.Sh DESCRIPTION +These functions perform the quality check for the heimdal database +library. +.Pp +There are two versions of the shared object API; the old version (0) +is deprecated, but still supported. The new version (1) supports +multiple password quality checking policies in the same shared object. +See below for details. +.Pp +The password quality checker will run all policies that are +configured by the user. If any policy rejects the password, the password +will be rejected. +.Pp +Policy names are of the form +.Ql module-name:policy-name +or, if the the policy name is unique enough, just +.Ql policy-name . +.Sh IMPLEMENTING A PASSWORD QUALITY CHECKING SHARED OBJECT +(This refers to the version 1 API only.) +.Pp +Module shared objects may conveniently be compiled and linked with +.Xr libtool 1 . +An object needs to export a symbol called +.Ql kadm5_password_verifier +of the type +.Ft "struct kadm5_pw_policy_verifier" . +.Pp +Its +.Ft name +and +.Ft vendor +fields should contain the obvious information. +.Ft name +must match the +.Ql module-name +portion of the policy name (the part before the colon), if the policy name +contains a colon, or the policy will not be run. +.Ft version +should be +.Dv KADM5_PASSWD_VERSION_V1 . +.Pp +.Ft funcs +contains an array of +.Ft "struct kadm5_pw_policy_check_func" +structures that is terminated with an entry whose +.Ft name +component is +.Dv NULL . +The +.Ft name +field of the array must match the +.Ql policy-name +portion of a policy name (the part after the colon, or the complete policy +name if there is no colon) specified by the user or the policy will not be +run. The +.Ft func +fields of the array elements are functions that are exported by the +module to be called to check the password. They get the following +arguments: the Kerberos context, principal, password, a tuning parameter, and +a pointer to a message buffer and its length. The tuning parameter +for the quality check function is currently always +.Dv NULL . +If the password is acceptable, the function returns zero. Otherwise +it returns non-zero and fills in the message buffer with an +appropriate explanation. +.Sh RUNNING THE CHECKS +.Nm kadm5_setup_passwd_quality_check +sets up type 0 checks. It sets up all type 0 checks defined in +.Xr krb5.conf 5 +if called with the last two arguments null. +.Pp +.Nm kadm5_add_passwd_quality_verifier +sets up type 1 checks. It sets up all type 1 tests defined in +.Xr krb5.conf 5 +if called with a null second argument. +.Nm kadm5_check_password_quality +runs the checks in the order in which they are defined in +.Xr krb5.conf 5 +and the order in which they occur in a +module's +.Ft funcs +array until one returns non-zero. +.Sh SEE ALSO +.Xr libtool 1 , +.Xr krb5 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/kafs.3 b/static/netbsd/man3/kafs.3 new file mode 100644 index 00000000..4793f78b --- /dev/null +++ b/static/netbsd/man3/kafs.3 @@ -0,0 +1,298 @@ +.\" $NetBSD: kafs.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 1998 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Os +.Dt KAFS 3 +.Sh NAME +.Nm k_hasafs , +.Nm k_hasafs_recheck , +.Nm k_pioctl , +.Nm k_unlog , +.Nm k_setpag , +.Nm k_afs_cell_of_file , +.Nm kafs_set_verbose , +.Nm kafs_settoken_rxkad , +.Nm kafs_settoken , +.Nm krb_afslog , +.Nm krb_afslog_uid , +.Nm kafs_settoken5 , +.Nm krb5_afslog , +.Nm krb5_afslog_uid +.Nd AFS library +.Sh LIBRARY +AFS cache manager access library (libkafs, -lkafs) +.Sh SYNOPSIS +.In kafs.h +.Ft int +.Fn k_afs_cell_of_file "const char *path" "char *cell" "int len" +.Ft int +.Fn k_hasafs "void" +.Ft int +.Fn k_hasafs_recheck "void" +.Ft int +.Fn k_pioctl "char *a_path" "int o_opcode" "struct ViceIoctl *a_paramsP" "int a_followSymlinks" +.Ft int +.Fn k_setpag "void" +.Ft int +.Fn k_unlog "void" +.Ft void +.Fn kafs_set_verbose "void (*func)(void *, const char *, int)" "void *" +.Ft int +.Fn kafs_settoken_rxkad "const char *cell" "struct ClearToken *token" "void *ticket" "size_t ticket_len" +.Ft int +.Fn kafs_settoken "const char *cell" "uid_t uid" "CREDENTIALS *c" +.Fn krb_afslog "char *cell" "char *realm" +.Ft int +.Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid" +.Ft krb5_error_code +.Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid" +.Ft int +.Fn kafs_settoken5 "const char *cell" "uid_t uid" "krb5_creds *c" +.Ft krb5_error_code +.Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" +.Sh DESCRIPTION +.Fn k_hasafs +initializes some library internal structures, and tests for the +presence of AFS in the kernel, none of the other functions should be +called before +.Fn k_hasafs +is called, or if it fails. +.Pp +.Fn k_hasafs_recheck +forces a recheck if a AFS client has started since last time +.Fn k_hasafs +or +.Fn k_hasafs_recheck +was called. +.Pp +.Fn kafs_set_verbose +set a log function that will be called each time the kafs library does +something important so that the application using libkafs can output +verbose logging. +Calling the function +.Fa kafs_set_verbose +with the function argument set to +.Dv NULL +will stop libkafs from calling the logging function (if set). +.Pp +.Fn kafs_settoken_rxkad +set +.Li rxkad +with the +.Fa token +and +.Fa ticket +(that have the length +.Fa ticket_len ) +for a given +.Fa cell . +.Pp +.Fn kafs_settoken +and +.Fn kafs_settoken5 +work the same way as +.Fn kafs_settoken_rxkad +but internally converts the Kerberos 4 or 5 credential to a afs +cleartoken and ticket. +.Pp +.Fn krb_afslog , +and +.Fn krb_afslog_uid +obtains new tokens (and possibly tickets) for the specified +.Fa cell +and +.Fa realm . +If +.Fa cell +is +.Dv NULL , +the local cell is used. If +.Fa realm +is +.Dv NULL , +the function tries to guess what realm to use. Unless you have some good knowledge of what cell or realm to use, you should pass +.Dv NULL . +.Fn krb_afslog +will use the real user-id for the +.Dv ViceId +field in the token, +.Fn krb_afslog_uid +will use +.Fa uid . +.Pp +.Fn krb5_afslog , +and +.Fn krb5_afslog_uid +are the Kerberos 5 equivalents of +.Fn krb_afslog , +and +.Fn krb_afslog_uid . +.Pp +.Fn krb5_afslog , +.Fn kafs_settoken5 +can be configured to behave differently via a +.Nm krb5_appdefault +option +.Li afs-use-524 +in +.Pa krb5.conf . +Possible values for +.Li afs-use-524 +are: +.Bl -tag -width local +.It yes +use the 524 server in the realm to convert the ticket +.It no +use the Kerberos 5 ticket directly, can be used with if the afs cell +support 2b token. +.It local, 2b +convert the Kerberos 5 credential to a 2b token locally (the same work +as a 2b 524 server should have done). +.El +.Pp +Example: +.Pp +.Bd -literal +[appdefaults] + SU.SE = { afs-use-524 = local } + PDC.KTH.SE = { afs-use-524 = yes } + afs-use-524 = yes +.Ed +.Pp +libkafs will use the +.Li libkafs +as application name when running the +.Nm krb5_appdefault +function call. +.Pp +The (uppercased) cell name is used as the realm to the +.Nm krb5_appdefault function. +.Pp +.\" The extra arguments are the ubiquitous context, and the cache id where +.\" to store any obtained tickets. Since AFS servers normally can't handle +.\" Kerberos 5 tickets directly, these functions will first obtain version +.\" 5 tickets for the requested cells, and then convert them to version 4 +.\" tickets, that can be stashed in the kernel. To convert tickets the +.\" .Fn krb524_convert_creds_kdc +.\" function will be used. +.\" .Pp +.Fn k_afs_cell_of_file +will in +.Fa cell +return the cell of a specified file, no more than +.Fa len +characters is put in +.Fa cell . +.Pp +.Fn k_pioctl +does a +.Fn pioctl +system call with the specified arguments. This function is equivalent to +.Fn lpioctl . +.Pp +.Fn k_setpag +initializes a new PAG. +.Pp +.Fn k_unlog +removes destroys all tokens in the current PAG. +.Sh RETURN VALUES +.Fn k_hasafs +returns 1 if AFS is present in the kernel, 0 otherwise. +.Fn krb_afslog +and +.Fn krb_afslog_uid +returns 0 on success, or a Kerberos error number on failure. +.Fn k_afs_cell_of_file , +.Fn k_pioctl , +.Fn k_setpag , +and +.Fn k_unlog +all return the value of the underlaying system call, 0 on success. +.Sh ENVIRONMENT +The following environment variable affect the mode of operation of +.Nm kafs : +.Bl -tag -width AFS_SYSCALL +.It Ev AFS_SYSCALL +Normally, +.Nm kafs +will try to figure out the correct system call(s) that are used by AFS +by itself. If it does not manage to do that, or does it incorrectly, +you can set this variable to the system call number or list of system +call numbers that should be used. +.El +.Sh EXAMPLES +The following code from +.Nm login +will obtain a new PAG and tokens for the local cell and the cell of +the users home directory. +.Bd -literal +if (k_hasafs()) { + char cell[64]; + k_setpag(); + if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0) + krb_afslog(cell, NULL); + krb_afslog(NULL, NULL); +} +.Ed +.Sh ERRORS +If any of these functions (apart from +.Fn k_hasafs ) +is called without AFS being present in the kernel, the process will +usually (depending on the operating system) receive a SIGSYS signal. +.Sh SEE ALSO +.Xr krb5_appdefault 3 , +.Xr krb5.conf 5 +.Rs +.%A Transarc Corporation +.%J AFS-3 Programmer's Reference +.%T File Server/Cache Manager Interface +.%D 1991 +.Re +.Sh FILES +libkafs will search for +.Pa ThisCell and +.Pa TheseCells +in the following locations: +.Pa /usr/vice/etc , +.Pa /etc/openafs , +.Pa /var/db/openafs/etc , +.Pa /usr/arla/etc , +.Pa /etc/arla , +and +.Pa /etc/afs +.Sh BUGS +.Ev AFS_SYSCALL +has no effect under AIX. diff --git a/static/netbsd/man3/keccak.3 b/static/netbsd/man3/keccak.3 new file mode 100644 index 00000000..6e6f80b5 --- /dev/null +++ b/static/netbsd/man3/keccak.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: keccak.3,v 1.1 2017/11/30 16:00:48 wiz Exp $ +.\" +.\" Copyright (c) 2015 Taylor R. Campbell +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 14, 2015 +.Dt KECCAK 3 +.Os +.Sh NAME +.Nm Keccak +.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.Sh SYNOPSIS +.In keccak.h +.Ft void +.Fn keccakf1600 "uint64_t A[25]" +.Sh DESCRIPTION +The +.Nm +functions implement the core Keccak permutation of the NIST SHA-3 +standard, FIPS PUB 202. +.Pp +Before using the +.Nm +functions, applications should first call +.Xr SHA3_Selftest 3 +and confirm that it succeeded. +.Pp +The +.Fn keccakf1600 +function implements the 24-round Keccak-f[1600] permutation on a state +of twenty-five 64-bit words, to be loaded from or stored to octets in +little-endian order. +.Pp +This function scrambles a 1600-bit state, and is conjectured to look +like a random permutation. +It lies at the core of all the SHA-3 hash and extendable-output +functions, and can be used for other cryptographic constructions, +e.g. a sponge duplex. +.Pp +The permutation Keccak-f[1600] is also known as Keccak-p[1600, 24]. +.Sh SEE ALSO +.Xr sha3 3 , +.Xr SHA3_Selftest 3 , +.Xr SHAKE 3 +.Sh STANDARDS +.Rs +.%A National Institute of Standards and Technology +.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.%O FIPS PUB 202 +.%D August 2015 +.Re +.Sh AUTHORS +.An Taylor R Campbell Aq campbell+sha3@mumble.net diff --git a/static/netbsd/man3/killpg.3 b/static/netbsd/man3/killpg.3 new file mode 100644 index 00000000..d3afef03 --- /dev/null +++ b/static/netbsd/man3/killpg.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)killpg.2 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: killpg.3,v 1.16 2003/08/07 16:42:39 agc Exp $ +.\" +.Dd June 2, 1993 +.Dt KILLPG 3 +.Os +.Sh NAME +.Nm killpg +.Nd send signal to a process group +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn killpg "pid_t pgrp" "int sig" +.Sh DESCRIPTION +.Fn killpg +sends the signal +.Fa sig +to the process group +.Fa pgrp . +See +.Xr sigaction 2 +for a list of signals. +If +.Fa pgrp +is 0, +.Fn killpg +sends the signal to the sending process's process group. +.Pp +The sending process and members of the process group must +have the same effective user ID, or +the sender must be the super-user. +As a single special case the continue signal SIGCONT may be sent +to any process that is a descendant of the current process. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn killpg +will fail and no signal will be sent if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sig +is not a valid signal number. +.It Bq Er ESRCH +No process can be found in the process group specified by +.Fa pgrp . +.It Bq Er ESRCH +The process group was given as 0 +but the sending process does not have a process group. +.It Bq Er EPERM +The sending process is not the super-user and one or more +of the target processes has an effective user ID different from that +of the sending process. +.El +.Sh SEE ALSO +.Xr getpgrp 2 , +.Xr kill 2 , +.Xr sigaction 2 +.Sh HISTORY +The +.Fn killpg +function call appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/kinfo_getvmmap.3 b/static/netbsd/man3/kinfo_getvmmap.3 new file mode 100644 index 00000000..e0851c70 --- /dev/null +++ b/static/netbsd/man3/kinfo_getvmmap.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: kinfo_getvmmap.3,v 1.1 2015/09/24 14:39:20 christos Exp $ +.\" +.\" Copyright (c) 2008 Peter Wemm +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libutil/kinfo_getvmmap.3 283622 2015-05-27 17:51:06Z jhb $ +.\" +.Dd September 16, 2015 +.Dt KINFO_GETVMMAP 3 +.Os +.Sh NAME +.Nm kinfo_getvmmap +.Nd function for getting per-process memory map information +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.In util.h +.Ft struct kinfo_vmentry * +.Fn kinfo_getvmmap "pid_t pid" "size_t *cntp" +.Sh DESCRIPTION +This function is used for obtaining virtual memory mapping information +of a particular process. +.Pp +The +.Ar pid +field contains the process identifier. +This should be the a process that you have privilege to access. +The +.Ar cntp +field is allows the caller to know how many records are returned. +.Pp +This function is a wrapper around +.Xr sysctl 3 +with the +.Dv KERN_PROC_VMMAP +mib. +While the kernel returns a packed structure, this function expands the +data into a fixed record format. +.Sh RETURN VALUES +On success the +.Fn kinfo_getvmmap +function returns a pointer to an array of +.Vt struct kinfo_vmentry +structures as defined by +.In sys/sysctl.h . +The array was obtained by an internal call to +.Xr malloc 3 +and must be freed by the caller with a call to +.Xr free 3 . +On failure the +.Fn kinfo_getvmmap +function returns +.Dv NULL . +.Sh SEE ALSO +.Xr free 3 , +.\" .Xr kinfo_getfile 3 , +.Xr malloc 3 diff --git a/static/netbsd/man3/krb5.3 b/static/netbsd/man3/krb5.3 new file mode 100644 index 00000000..5c03c59f --- /dev/null +++ b/static/netbsd/man3/krb5.3 @@ -0,0 +1,1062 @@ +.\" $NetBSD: krb5.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5 \- Heimdal Kerberos 5 library +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_add_et_list\fP (krb5_context context, void(*func)(struct et_list **))" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_password\fP (krb5_context context, krb5_creds *creds, const char *newpw, krb5_principal targprinc, int *result_code, krb5_data *result_code_string, krb5_data *result_string)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_context\fP (krb5_context *context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_context\fP (krb5_context context, krb5_context *out)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_context\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_config_files\fP (krb5_context context, char **filenames)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_prepend_config_files_default\fP (const char *filelist, char ***pfilenames)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_default_config_files\fP (char ***pfilenames)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_config_files\fP (char **filenames)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const krb5_enctype *KRB5_LIB_CALL \fBkrb5_kerberos_enctypes\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_default_in_tkt_etypes\fP (krb5_context context, const krb5_enctype *etypes)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_default_in_tkt_etypes\fP (krb5_context context, krb5_pdu pdu_type, krb5_enctype **etypes)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_init_ets\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_set_use_admin_kdc\fP (krb5_context context, krb5_boolean flag)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_get_use_admin_kdc\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_add_extra_addresses\fP (krb5_context context, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_extra_addresses\fP (krb5_context context, const krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_extra_addresses\fP (krb5_context context, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_add_ignore_addresses\fP (krb5_context context, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_ignore_addresses\fP (krb5_context context, const krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_ignore_addresses\fP (krb5_context context, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_fcache_version\fP (krb5_context context, int version)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_fcache_version\fP (krb5_context context, int *version)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_is_thread_safe\fP (void)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_set_dns_canonicalize_hostname\fP (krb5_context context, krb5_boolean flag)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_get_dns_canonicalize_hostname\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_kdc_sec_offset\fP (krb5_context context, int32_t *sec, int32_t *usec)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_kdc_sec_offset\fP (krb5_context context, int32_t sec, int32_t usec)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL \fBkrb5_get_max_time_skew\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_set_max_time_skew\fP (krb5_context context, time_t t)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_set_home_dir_access\fP (krb5_context context, krb5_boolean allow)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_host_realm\fP (krb5_context context, const krb5_realm *from, krb5_realm **to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_cred_contents\fP (krb5_context context, krb5_creds *c)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_creds_contents\fP (krb5_context context, const krb5_creds *incred, krb5_creds *c)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_creds\fP (krb5_context context, const krb5_creds *incred, krb5_creds **outcred)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_creds\fP (krb5_context context, krb5_creds *c)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_compare_creds\fP (krb5_context context, krb5_flags whichfields, const krb5_creds *mcreds, const krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL \fBkrb5_creds_get_ticket_flags\fP (krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_data_zero\fP (krb5_data *p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_data_free\fP (krb5_data *p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_data\fP (krb5_context context, krb5_data *p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_data_alloc\fP (krb5_data *p, int len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_data_realloc\fP (krb5_data *p, int len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_data_copy\fP (krb5_data *p, const void *data, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_data\fP (krb5_context context, const krb5_data *indata, krb5_data **outdata)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_data_cmp\fP (const krb5_data *data1, const krb5_data *data2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_data_ct_cmp\fP (const krb5_data *data1, const krb5_data *data2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_get_err_text\fP (krb5_context context, krb5_error_code code) KRB5_DEPRECATED_FUNCTION('Use \fBkrb5_get_error_message\fP instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_krbhst_get_addrinfo\fP (krb5_context context, krb5_krbhst_info *host, struct addrinfo **ai)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_ticket\fP (krb5_context context, krb5_ticket *ticket)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_ticket\fP (krb5_context context, const krb5_ticket *from, krb5_ticket **to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ticket_get_client\fP (krb5_context context, const krb5_ticket *ticket, krb5_principal *client)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ticket_get_server\fP (krb5_context context, const krb5_ticket *ticket, krb5_principal *server)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL \fBkrb5_ticket_get_endtime\fP (krb5_context context, const krb5_ticket *ticket)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ticket_get_authorization_data_type\fP (krb5_context context, krb5_ticket *ticket, int type, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_real_time\fP (krb5_context context, krb5_timestamp sec, int32_t usec)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_et_list (krb5_context context, void(*)(struct et_list **) func)" +Add a specified list of error messages to the et list in context\&. Call func (probably a comerr-generated function) with a pointer to the current et_list\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A kerberos context\&. +.br +\fIfunc\fP The generated com_err et function\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_extra_addresses (krb5_context context, krb5_addresses * addresses)" +Add extra address to the address list that the library will add to the client's address list when communicating with the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP addreses to add +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_add_ignore_addresses (krb5_context context, krb5_addresses * addresses)" +Add extra addresses to ignore when fetching addresses from the underlaying operating system\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP addreses to ignore +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_compare_creds (krb5_context context, krb5_flags whichfields, const krb5_creds * mcreds, const krb5_creds * creds)" +Return TRUE if `mcreds' and `creds' are equal (`whichfields' determines what equal means)\&. +.PP +The following flags, set in whichfields affects the comparison: +.IP "\(bu" 2 +KRB5_TC_MATCH_SRV_NAMEONLY Consider all realms equal when comparing the service principal\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_KEYTYPE Compare enctypes\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_FLAGS_EXACT Make sure that the ticket flags are identical\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_FLAGS Make sure that all ticket flags set in mcreds are also present in creds \&. +.IP "\(bu" 2 +KRB5_TC_MATCH_TIMES_EXACT Compares the ticket times exactly\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_TIMES Compares only the expiration times of the creds\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_AUTHDATA Compares the authdata fields\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_2ND_TKT Compares the second tickets (used by user-to-user authentication)\&. +.IP "\(bu" 2 +KRB5_TC_MATCH_IS_SKEY Compares the existance of the second ticket\&. +.PP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIwhichfields\fP which fields to compare\&. +.br +\fImcreds\fP cred to compare with\&. +.br +\fIcreds\fP cred to compare with\&. +.RE +.PP +\fBReturns\fP +.RS 4 +return TRUE if mcred and creds are equal, FALSE if not\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_context (krb5_context context, krb5_context * out)" +Make a copy for the Kerberos 5 context, the new krb5_context shoud be freed with \fBkrb5_free_context()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP the Kerberos context to copy +.br +\fIout\fP the copy of the Kerberos, set to NULL error\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_creds (krb5_context context, const krb5_creds * incred, krb5_creds ** outcred)" +Copy krb5_creds\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIincred\fP source credential +.br +\fIoutcred\fP destination credential, free with \fBkrb5_free_creds()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_creds_contents (krb5_context context, const krb5_creds * incred, krb5_creds * c)" +Copy content of krb5_creds\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIincred\fP source credential +.br +\fIc\fP destination credential, free with \fBkrb5_free_cred_contents()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_data (krb5_context context, const krb5_data * indata, krb5_data ** outdata)" +Copy the data into a newly allocated krb5_data\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIindata\fP the krb5_data data to copy +.br +\fIoutdata\fP new krb5_date to copy too\&. Free with \fBkrb5_free_data()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_host_realm (krb5_context context, const krb5_realm * from, krb5_realm ** to)" +Copy the list of realms from `from' to `to'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIfrom\fP list of realms to copy from\&. +.br +\fIto\fP list of realms to copy to, free list of \fBkrb5_free_host_realm()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_ticket (krb5_context context, const krb5_ticket * from, krb5_ticket ** to)" +Copy ticket and content +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIfrom\fP ticket to copy +.br +\fIto\fP new copy of ticket, free with \fBkrb5_free_ticket()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL krb5_creds_get_ticket_flags (krb5_creds * creds)" +Returns the ticket flags for the credentials in creds\&. See also \fBkrb5_ticket_get_flags()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcreds\fP credential to get ticket flags from +.RE +.PP +\fBReturns\fP +.RS 4 +ticket flags +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_alloc (krb5_data * p, int len)" +Allocate data of and krb5_data\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP krb5_data to allocate\&. +.br +\fIlen\fP size to allocate\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_data_cmp (const krb5_data * data1, const krb5_data * data2)" +Compare to data\&. +.PP +\fBParameters\fP +.RS 4 +\fIdata1\fP krb5_data to compare +.br +\fIdata2\fP krb5_data to compare +.RE +.PP +\fBReturns\fP +.RS 4 +return the same way as memcmp(), useful when sorting\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_copy (krb5_data * p, const void * data, size_t len)" +Copy the data of len into the krb5_data\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP krb5_data to copy into\&. +.br +\fIdata\fP data to copy\&.\&. +.br +\fIlen\fP new size\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_data_ct_cmp (const krb5_data * data1, const krb5_data * data2)" +Compare to data not exposing timing information from the checksum data +.PP +\fBParameters\fP +.RS 4 +\fIdata1\fP krb5_data to compare +.br +\fIdata2\fP krb5_data to compare +.RE +.PP +\fBReturns\fP +.RS 4 +returns zero for same data, otherwise non zero\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_data_free (krb5_data * p)" +Free the content of krb5_data structure, its ok to free a zeroed structure (with memset() or \fBkrb5_data_zero()\fP)\&. When done, the structure will be zeroed\&. The same function is called \fBkrb5_free_data_contents()\fP in MIT Kerberos\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP krb5_data to free\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_data_realloc (krb5_data * p, int len)" +Grow (or shrink) the content of krb5_data to a new size\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP krb5_data to free\&. +.br +\fIlen\fP new size\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_data_zero (krb5_data * p)" +Reset the (potentially uninitalized) krb5_data structure\&. +.PP +\fBParameters\fP +.RS 4 +\fIp\fP krb5_data to reset\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_config_files (char ** filenames)" +Free a list of configuration files\&. +.PP +\fBParameters\fP +.RS 4 +\fIfilenames\fP list, terminated with a NULL pointer, to be freed\&. NULL is an valid argument\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_context (krb5_context context)" +Frees the krb5_context allocated by \fBkrb5_init_context()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP context to be freed\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_cred_contents (krb5_context context, krb5_creds * c)" +Free content of krb5_creds\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIc\fP krb5_creds to free\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_creds (krb5_context context, krb5_creds * c)" +Free krb5_creds\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIc\fP krb5_creds to free\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_data (krb5_context context, krb5_data * p)" +Free krb5_data (and its content)\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIp\fP krb5_data to free\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_ticket (krb5_context context, krb5_ticket * ticket)" +Free ticket and content +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIticket\fP ticket to free +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_default_config_files (char *** pfilenames)" +Get the global configuration list\&. +.PP +\fBParameters\fP +.RS 4 +\fIpfilenames\fP return array of filenames, should be freed with \fBkrb5_free_config_files()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_default_in_tkt_etypes (krb5_context context, krb5_pdu pdu_type, krb5_enctype ** etypes)" +Get the default encryption types that will be use in communcation with the KDC, clients and servers\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIpdu_type\fP request type (AS, TGS or none) +.br +\fIetypes\fP Encryption types, array terminated with ETYPE_NULL(0), caller should free array with krb5_xfree(): +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_get_dns_canonicalize_hostname (krb5_context context)" +Get if the library uses DNS to canonicalize hostnames\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +return non zero if the library uses DNS to canonicalize hostnames\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_get_err_text (krb5_context context, krb5_error_code code)" +Return the error string for the error code\&. The caller must not free the string\&. +.PP +This function is deprecated since its not threadsafe\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIcode\fP Kerberos error code\&. +.RE +.PP +\fBReturns\fP +.RS 4 +the error message matching code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_extra_addresses (krb5_context context, krb5_addresses * addresses)" +Get extra address to the address list that the library will add to the client's address list when communicating with the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP addreses to set +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_fcache_version (krb5_context context, int * version)" +Get version of fcache that the library should use\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIversion\fP version number\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_ignore_addresses (krb5_context context, krb5_addresses * addresses)" +Get extra addresses to ignore when fetching addresses from the underlaying operating system\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP list addreses ignored +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_kdc_sec_offset (krb5_context context, int32_t * sec, int32_t * usec)" +Get current offset in time to the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIsec\fP seconds part of offset\&. +.br +\fIusec\fP micro seconds part of offset\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns zero +.RE +.PP + +.SS "KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL krb5_get_max_time_skew (krb5_context context)" +Get max time skew allowed\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +timeskew in seconds\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_get_use_admin_kdc (krb5_context context)" +Make the kerberos library default to the admin KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.RE +.PP +\fBReturns\fP +.RS 4 +boolean flag to telling the context will use admin KDC as the default KDC\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_context (krb5_context * context)" +Initializes the context structure and reads the configuration file /etc/krb5\&.conf\&. The structure should be freed by calling \fBkrb5_free_context()\fP when it is no longer being used\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP pointer to returned context +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an errno code is returned\&. Failure means either that something bad happened during initialization (typically ENOMEM) or that Kerberos should not be used ENXIO\&. If the function returns HEIM_ERR_RANDOM_OFFLINE, the random source is not available and later Kerberos calls might fail\&. +.RE +.PP +\fBkrb5_init_context()\fP will get one random byte to make sure our random is alive\&. Assumption is that once the non blocking source allows us to pull bytes, its all seeded and allows us to pull more bytes\&. +.PP +Most Kerberos users calls \fBkrb5_init_context()\fP, so this is useful point where we can do the checking\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_ets (krb5_context context)" +Init the built-in ets in the Kerberos library\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP kerberos context to add the ets too +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_is_thread_safe (void)" +Runtime check if the Kerberos library was complied with thread support\&. +.PP +\fBReturns\fP +.RS 4 +TRUE if the library was compiled with thread support, FALSE if not\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const krb5_enctype* KRB5_LIB_CALL krb5_kerberos_enctypes (krb5_context context)" +Returns the list of Kerberos encryption types sorted in order of most preferred to least preferred encryption type\&. Note that some encryption types might be disabled, so you need to check with \fBkrb5_enctype_valid()\fP before using the encryption type\&. +.PP +\fBReturns\fP +.RS 4 +list of enctypes, terminated with ETYPE_NULL\&. Its a static array completed into the Kerberos library so the content doesn't need to be freed\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_krbhst_get_addrinfo (krb5_context context, krb5_krbhst_info * host, struct addrinfo ** ai)" +Return an `struct addrinfo *' for a KDC host\&. +.PP +Returns an the struct addrinfo in in that corresponds to the information in `host'\&. free:ing is handled by krb5_krbhst_free, so the returned ai must not be released\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_prepend_config_files_default (const char * filelist, char *** pfilenames)" +Prepend the filename to the global configuration list\&. +.PP +\fBParameters\fP +.RS 4 +\fIfilelist\fP a filename to add to the default list of filename +.br +\fIpfilenames\fP return array of filenames, should be freed with \fBkrb5_free_config_files()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_config_files (krb5_context context, char ** filenames)" +Reinit the context from a new set of filenames\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP context to add configuration too\&. +.br +\fIfilenames\fP array of filenames, end of list is indicated with a NULL filename\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_default_in_tkt_etypes (krb5_context context, const krb5_enctype * etypes)" +Set the default encryption types that will be use in communcation with the KDC, clients and servers\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIetypes\fP Encryption types, array terminated with ETYPE_NULL (0)\&. A value of NULL resets the encryption types to the defaults set in the configuration file\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_dns_canonicalize_hostname (krb5_context context, krb5_boolean flag)" +Set if the library should use DNS to canonicalize hostnames\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIflag\fP if its dns canonicalizion is used or not\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_extra_addresses (krb5_context context, const krb5_addresses * addresses)" +Set extra address to the address list that the library will add to the client's address list when communicating with the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP addreses to set +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_fcache_version (krb5_context context, int version)" +Set version of fcache that the library should use\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIversion\fP version number\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_set_home_dir_access (krb5_context context, krb5_boolean allow)" +Enable and disable home directory access on either the global state or the krb5_context state\&. By calling \fBkrb5_set_home_dir_access()\fP with context set to NULL, the global state is configured otherwise the state for the krb5_context is modified\&. +.PP +For home directory access to be allowed, both the global state and the krb5_context state have to be allowed\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context or NULL +.br +\fIallow\fP allow if TRUE home directory +.RE +.PP +\fBReturns\fP +.RS 4 +the old value +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_ignore_addresses (krb5_context context, const krb5_addresses * addresses)" +Set extra addresses to ignore when fetching addresses from the underlaying operating system\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIaddresses\fP addreses to ignore +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_kdc_sec_offset (krb5_context context, int32_t sec, int32_t usec)" +Set current offset in time to the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIsec\fP seconds part of offset\&. +.br +\fIusec\fP micro seconds part of offset\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns zero +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_max_time_skew (krb5_context context, time_t t)" +Set max time skew allowed\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIt\fP timeskew in seconds\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_password (krb5_context context, krb5_creds * creds, const char * newpw, krb5_principal targprinc, int * result_code, krb5_data * result_code_string, krb5_data * result_string)" +Change password using creds\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIcreds\fP The initial kadmin/passwd for the principal or an admin principal +.br +\fInewpw\fP The new password to set +.br +\fItargprinc\fP if unset, the default principal is used\&. +.br +\fIresult_code\fP Result code, KRB5_KPASSWD_SUCCESS is when password is changed\&. +.br +\fIresult_code_string\fP binary message from the server, contains at least the result_code\&. +.br +\fIresult_string\fP A message from the kpasswd service or the library in human printable form\&. The string is NUL terminated\&. +.RE +.PP +\fBReturns\fP +.RS 4 +On sucess and *result_code is KRB5_KPASSWD_SUCCESS, the password is changed\&. +.RE +.PP +@ +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_real_time (krb5_context context, krb5_timestamp sec, int32_t usec)" +Set the absolute time that the caller knows the kdc has so the kerberos library can calculate the relative diffrence beteen the KDC time and local system time\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIsec\fP The applications new of 'now' in seconds +.br +\fIusec\fP The applications new of 'now' in micro seconds +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP +If the caller passes in a negative usec, its assumed to be unknown and the function will use the current time usec\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_use_admin_kdc (krb5_context context, krb5_boolean flag)" +Make the kerberos library default to the admin KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIflag\fP boolean flag to select if the use the admin KDC or not\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_authorization_data_type (krb5_context context, krb5_ticket * ticket, int type, krb5_data * data)" +Extract the authorization data type of type from the ticket\&. Store the field in data\&. This function is to use for kerberos applications\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIticket\fP Kerberos ticket +.br +\fItype\fP type to fetch +.br +\fIdata\fP returned data, free with \fBkrb5_data_free()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_client (krb5_context context, const krb5_ticket * ticket, krb5_principal * client)" +Return client principal in ticket +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIticket\fP ticket to copy +.br +\fIclient\fP client principal, free with \fBkrb5_free_principal()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION time_t KRB5_LIB_CALL krb5_ticket_get_endtime (krb5_context context, const krb5_ticket * ticket)" +Return end time of ticket +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIticket\fP ticket to copy +.RE +.PP +\fBReturns\fP +.RS 4 +end time of ticket +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ticket_get_server (krb5_context context, const krb5_ticket * ticket, krb5_principal * server)" +Return server principal in ticket +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIticket\fP ticket to copy +.br +\fIserver\fP server principal, free with \fBkrb5_free_principal()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb524_convert_creds_kdc.3 b/static/netbsd/man3/krb524_convert_creds_kdc.3 new file mode 100644 index 00000000..0894c91f --- /dev/null +++ b/static/netbsd/man3/krb524_convert_creds_kdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb524_convert_creds_kdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_v4compat.3 diff --git a/static/netbsd/man3/krb524_convert_creds_kdc_ccache.3 b/static/netbsd/man3/krb524_convert_creds_kdc_ccache.3 new file mode 100644 index 00000000..f1ada234 --- /dev/null +++ b/static/netbsd/man3/krb524_convert_creds_kdc_ccache.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb524_convert_creds_kdc_ccache.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_v4compat.3 diff --git a/static/netbsd/man3/krb5_425_conv_principal.3 b/static/netbsd/man3/krb5_425_conv_principal.3 new file mode 100644 index 00000000..fc3501c6 --- /dev/null +++ b/static/netbsd/man3/krb5_425_conv_principal.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: krb5_425_conv_principal.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 1997-2003 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd September 3, 2003 +.Dt KRB5_425_CONV_PRINCIPAL 3 +.Os +.Sh NAME +.Nm krb5_425_conv_principal , +.Nm krb5_425_conv_principal_ext , +.Nm krb5_524_conv_principal +.Nd converts to and from version 4 principals +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *principal" +.Ft krb5_error_code +.Fn krb5_425_conv_principal_ext "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_boolean (*func)(krb5_context, krb5_principal)" "krb5_boolean resolve" "krb5_principal *principal" +.Ft krb5_error_code +.Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm" +.Sh DESCRIPTION +Converting between version 4 and version 5 principals can at best be +described as a mess. +.Pp +A version 4 principal consists of a name, an instance, and a realm. A +version 5 principal consists of one or more components, and a +realm. In some cases also the first component/name will differ between +version 4 and version 5. Furthermore the second component of a host +principal will be the fully qualified domain name of the host in +question, while the instance of a version 4 principal will only +contain the first part (short hostname). Because of these problems +the conversion between principals will have to be site customized. +.Pp +.Fn krb5_425_conv_principal_ext +will try to convert a version 4 principal, given by +.Fa name , +.Fa instance , +and +.Fa realm , +to a version 5 principal. This can result in several possible +principals, and if +.Fa func +is non-NULL, it will be called for each candidate principal. +.Fa func +should return true if the principal was +.Dq good . +To accomplish this, +.Fn krb5_425_conv_principal_ext +will look up the name in +.Pa krb5.conf . +It first looks in the +.Li v4_name_convert/host +subsection, which should contain a list of version 4 names whose +instance should be treated as a hostname. This list can be specified +for each realm (in the +.Li realms +section), or in the +.Li libdefaults +section. If the name is found the resulting name of the principal +will be the value of this binding. The instance is then first looked +up in +.Li v4_instance_convert +for the specified realm. If found the resulting value will be used as +instance (this can be used for special cases), no further attempts +will be made to find a conversion if this fails (with +.Fa func ) . +If the +.Fa resolve +parameter is true, the instance will be looked up with +.Fn gethostbyname . +This can be a time consuming, error prone, and unsafe operation. Next +a list of hostnames will be created from the instance and the +.Li v4_domains +variable, which should contain a list of possible domains for the +specific realm. +.Pp +On the other hand, if the name is not found in a +.Li host +section, it is looked up in a +.Li v4_name_convert/plain +binding. If found here the name will be converted, but the instance +will be untouched. +.Pp +This list of default host-type conversions is compiled-in: +.Bd -literal -offset indent +v4_name_convert = { + host = { + ftp = ftp + hprop = hprop + imap = imap + pop = pop + rcmd = host + smtp = smtp + } +} +.Ed +.Pp +It will only be used if there isn't an entry for these names in the +config file, so you can override these defaults. +.Pp +.Fn krb5_425_conv_principal +will call +.Fn krb5_425_conv_principal_ext +with +.Dv NULL +as +.Fa func , +and the value of +.Li v4_instance_resolve +(from the +.Li libdefaults +section) as +.Fa resolve . +.Pp +.Fn krb5_524_conv_principal +basically does the opposite of +.Fn krb5_425_conv_principal , +it just doesn't have to look up any names, but will instead truncate +instances found to belong to a host principal. The +.Fa name , +.Fa instance , +and +.Fa realm +should be at least 40 characters long. +.Sh EXAMPLES +Since this is confusing an example is in place. +.Pp +Assume that we have the +.Dq foo.com , +and +.Dq bar.com +domains that have shared a single version 4 realm, FOO.COM. The version 4 +.Pa krb.realms +file looked like: +.Bd -literal -offset indent +foo.com FOO.COM +\&.foo.com FOO.COM +\&.bar.com FOO.COM +.Ed +.Pp +A +.Pa krb5.conf +file that covers this case might look like: +.Bd -literal -offset indent +[libdefaults] + v4_instance_resolve = yes +[realms] + FOO.COM = { + kdc = kerberos.foo.com + v4_instance_convert = { + foo = foo.com + } + v4_domains = foo.com + } +.Ed +.Pp +With this setup and the following host table: +.Bd -literal -offset indent +foo.com +a-host.foo.com +b-host.bar.com +.Ed +the following conversions will be made: +.Bd -literal -offset indent +rcmd.a-host -\*(Gt host/a-host.foo.com +ftp.b-host -\*(Gt ftp/b-host.bar.com +pop.foo -\*(Gt pop/foo.com +ftp.other -\*(Gt ftp/other.foo.com +other.a-host -\*(Gt other/a-host +.Ed +.Pp +The first three are what you expect. If you remove the +.Dq v4_domains , +the fourth entry will result in an error (since the host +.Dq other +can't be found). Even if +.Dq a-host +is a valid host name, the last entry will not be converted, since the +.Dq other +name is not known to represent a host-type principal. +If you turn off +.Dq v4_instance_resolve +the second example will result in +.Dq ftp/b-host.foo.com +(because of the default domain). And all of this is of course only +valid if you have working name resolving. +.Sh SEE ALSO +.Xr krb5_build_principal 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_parse_name 3 , +.Xr krb5_sname_to_principal 3 , +.Xr krb5_unparse_name 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_abort.3 b/static/netbsd/man3/krb5_abort.3 new file mode 100644 index 00000000..17ccaf54 --- /dev/null +++ b/static/netbsd/man3/krb5_abort.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_abort.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_abortx.3 b/static/netbsd/man3/krb5_abortx.3 new file mode 100644 index 00000000..be73b3a2 --- /dev/null +++ b/static/netbsd/man3/krb5_abortx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_abortx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_acc_ops.3 b/static/netbsd/man3/krb5_acc_ops.3 new file mode 100644 index 00000000..ae622b44 --- /dev/null +++ b/static/netbsd/man3/krb5_acc_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_acc_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_acl_match_file.3 b/static/netbsd/man3/krb5_acl_match_file.3 new file mode 100644 index 00000000..62cfe094 --- /dev/null +++ b/static/netbsd/man3/krb5_acl_match_file.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_acl_match_file.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_acl_match_string.3 b/static/netbsd/man3/krb5_acl_match_string.3 new file mode 100644 index 00000000..1e15871a --- /dev/null +++ b/static/netbsd/man3/krb5_acl_match_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_acl_match_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_add_et_list.3 b/static/netbsd/man3/krb5_add_et_list.3 new file mode 100644 index 00000000..e64641e9 --- /dev/null +++ b/static/netbsd/man3/krb5_add_et_list.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_add_et_list.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_add_extra_addresses.3 b/static/netbsd/man3/krb5_add_extra_addresses.3 new file mode 100644 index 00000000..75952f60 --- /dev/null +++ b/static/netbsd/man3/krb5_add_extra_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_add_extra_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_add_ignore_addresses.3 b/static/netbsd/man3/krb5_add_ignore_addresses.3 new file mode 100644 index 00000000..369cb8de --- /dev/null +++ b/static/netbsd/man3/krb5_add_ignore_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_add_ignore_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_addr2sockaddr.3 b/static/netbsd/man3/krb5_addr2sockaddr.3 new file mode 100644 index 00000000..2f695420 --- /dev/null +++ b/static/netbsd/man3/krb5_addr2sockaddr.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_addr2sockaddr.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_address.3 b/static/netbsd/man3/krb5_address.3 new file mode 100644 index 00000000..41e8b155 --- /dev/null +++ b/static/netbsd/man3/krb5_address.3 @@ -0,0 +1,449 @@ +.\" $NetBSD: krb5_address.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_address" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_address \- Heimdal Kerberos 5 address functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_sockaddr2address\fP (krb5_context context, const struct sockaddr *sa, krb5_address *addr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_sockaddr2port\fP (krb5_context context, const struct sockaddr *sa, int16_t *port)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_addr2sockaddr\fP (krb5_context context, const krb5_address *addr, struct sockaddr *sa, krb5_socklen_t *sa_size, int port)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION size_t KRB5_LIB_CALL \fBkrb5_max_sockaddr_size\fP (void)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_sockaddr_uninteresting\fP (const struct sockaddr *sa)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_h_addr2sockaddr\fP (krb5_context context, int af, const char *addr, struct sockaddr *sa, krb5_socklen_t *sa_size, int port)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_h_addr2addr\fP (krb5_context context, int af, const char *haddr, krb5_address *addr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_anyaddr\fP (krb5_context context, int af, struct sockaddr *sa, krb5_socklen_t *sa_size, int port)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_print_address\fP (const krb5_address *addr, char *str, size_t len, size_t *ret_len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_address\fP (krb5_context context, const char *string, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_address_order\fP (krb5_context context, const krb5_address *addr1, const krb5_address *addr2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_address_compare\fP (krb5_context context, const krb5_address *addr1, const krb5_address *addr2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_address_search\fP (krb5_context context, const krb5_address *addr, const krb5_addresses *addrlist)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_address\fP (krb5_context context, krb5_address *address)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_addresses\fP (krb5_context context, krb5_addresses *addresses)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_address\fP (krb5_context context, const krb5_address *inaddr, krb5_address *outaddr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_addresses\fP (krb5_context context, const krb5_addresses *inaddr, krb5_addresses *outaddr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_append_addresses\fP (krb5_context context, krb5_addresses *dest, const krb5_addresses *source)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_make_addrport\fP (krb5_context context, krb5_address **res, const krb5_address *addr, int16_t port)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_address_prefixlen_boundary\fP (krb5_context context, const krb5_address *inaddr, unsigned long prefixlen, krb5_address *low, krb5_address *high)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_addr2sockaddr (krb5_context context, const krb5_address * addr, struct sockaddr * sa, krb5_socklen_t * sa_size, int port)" +krb5_addr2sockaddr sets the 'struct sockaddr sockaddr' from addr and port\&. The argument sa_size should initially contain the size of the sa and after the call, it will contain the actual length of the address\&. In case of the sa is too small to fit the whole address, the up to *sa_size will be stored, and then *sa_size will be set to the required length\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaddr\fP the address to copy the from +.br +\fIsa\fP the struct sockaddr that will be filled in +.br +\fIsa_size\fP pointer to length of sa, and after the call, it will contain the actual length of the address\&. +.br +\fIport\fP set port in sa\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. Will return KRB5_PROG_ATYPE_NOSUPP in case address type is not supported\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_address_compare (krb5_context context, const krb5_address * addr1, const krb5_address * addr2)" +krb5_address_compare compares the addresses addr1 and addr2\&. Returns TRUE if the two addresses are the same\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaddr1\fP address to compare +.br +\fIaddr2\fP address to compare +.RE +.PP +\fBReturns\fP +.RS 4 +Return an TRUE is the address are the same FALSE if not +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_address_order (krb5_context context, const krb5_address * addr1, const krb5_address * addr2)" +krb5_address_order compares the addresses addr1 and addr2 so that it can be used for sorting addresses\&. If the addresses are the same address krb5_address_order will return 0\&. Behavies like memcmp(2)\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaddr1\fP krb5_address to compare +.br +\fIaddr2\fP krb5_address to compare +.RE +.PP +\fBReturns\fP +.RS 4 +< 0 if address addr1 in 'less' then addr2\&. 0 if addr1 and addr2 is the same address, > 0 if addr2 is 'less' then addr1\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_address_prefixlen_boundary (krb5_context context, const krb5_address * inaddr, unsigned long prefixlen, krb5_address * low, krb5_address * high)" +Calculate the boundary addresses of `inaddr'/`prefixlen' and store them in `low' and `high'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIinaddr\fP address in prefixlen that the bondery searched +.br +\fIprefixlen\fP width of boundery +.br +\fIlow\fP lowest address +.br +\fIhigh\fP highest address +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_address_search (krb5_context context, const krb5_address * addr, const krb5_addresses * addrlist)" +krb5_address_search checks if the address addr is a member of the address set list addrlist \&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIaddr\fP address to search for\&. +.br +\fIaddrlist\fP list of addresses to look in for addr\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_anyaddr (krb5_context context, int af, struct sockaddr * sa, krb5_socklen_t * sa_size, int port)" +krb5_anyaddr fills in a 'struct sockaddr sa' that can be used to bind(2) to\&. The argument sa_size should initially contain the size of the sa, and after the call, it will contain the actual length of the address\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaf\fP address family +.br +\fIsa\fP sockaddr +.br +\fIsa_size\fP lenght of sa\&. +.br +\fIport\fP for to fill into sa\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_append_addresses (krb5_context context, krb5_addresses * dest, const krb5_addresses * source)" +krb5_append_addresses adds the set of addresses in source to dest\&. While copying the addresses, duplicates are also sorted out\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIdest\fP destination of copy operation +.br +\fIsource\fP adresses that are going to be added to dest +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_address (krb5_context context, const krb5_address * inaddr, krb5_address * outaddr)" +krb5_copy_address copies the content of address inaddr to outaddr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIinaddr\fP pointer to source address +.br +\fIoutaddr\fP pointer to destination address +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_addresses (krb5_context context, const krb5_addresses * inaddr, krb5_addresses * outaddr)" +krb5_copy_addresses copies the content of addresses inaddr to outaddr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIinaddr\fP pointer to source addresses +.br +\fIoutaddr\fP pointer to destination addresses +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_address (krb5_context context, krb5_address * address)" +krb5_free_address frees the data stored in the address that is alloced with any of the krb5_address functions\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaddress\fP addresss to be freed\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_addresses (krb5_context context, krb5_addresses * addresses)" +krb5_free_addresses frees the data stored in the address that is alloced with any of the krb5_address functions\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaddresses\fP addressses to be freed\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_addr2addr (krb5_context context, int af, const char * haddr, krb5_address * addr)" +krb5_h_addr2addr works like krb5_h_addr2sockaddr with the exception that it operates on a krb5_address instead of a struct sockaddr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaf\fP address family +.br +\fIhaddr\fP host address from struct hostent\&. +.br +\fIaddr\fP returned krb5_address\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_addr2sockaddr (krb5_context context, int af, const char * addr, struct sockaddr * sa, krb5_socklen_t * sa_size, int port)" +krb5_h_addr2sockaddr initializes a 'struct sockaddr sa' from af and the 'struct hostent' (see gethostbyname(3) ) h_addr_list component\&. The argument sa_size should initially contain the size of the sa, and after the call, it will contain the actual length of the address\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIaf\fP addresses +.br +\fIaddr\fP address +.br +\fIsa\fP returned struct sockaddr +.br +\fIsa_size\fP size of sa +.br +\fIport\fP port to set in sa\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_addrport (krb5_context context, krb5_address ** res, const krb5_address * addr, int16_t port)" +Create an address of type KRB5_ADDRESS_ADDRPORT from (addr, port) +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIres\fP built address from addr/port +.br +\fIaddr\fP address to use +.br +\fIport\fP port to use +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION size_t KRB5_LIB_CALL krb5_max_sockaddr_size (void)" +krb5_max_sockaddr_size returns the max size of the \&.Li struct sockaddr that the Kerberos library will return\&. +.PP +\fBReturns\fP +.RS 4 +Return an size_t of the maximum struct sockaddr\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_address (krb5_context context, const char * string, krb5_addresses * addresses)" +krb5_parse_address returns the resolved hostname in string to the krb5_addresses addresses \&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIstring\fP +.br +\fIaddresses\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_print_address (const krb5_address * addr, char * str, size_t len, size_t * ret_len)" +krb5_print_address prints the address in addr to the string string that have the length len\&. If ret_len is not NULL, it will be filled with the length of the string if size were unlimited (not including the final NUL) \&. +.PP +\fBParameters\fP +.RS 4 +\fIaddr\fP address to be printed +.br +\fIstr\fP pointer string to print the address into +.br +\fIlen\fP length that will fit into area pointed to by 'str'\&. +.br +\fIret_len\fP return length the str\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sockaddr2address (krb5_context context, const struct sockaddr * sa, krb5_address * addr)" +krb5_sockaddr2address stores a address a 'struct sockaddr' sa in the krb5_address addr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIsa\fP a struct sockaddr to extract the address from +.br +\fIaddr\fP an Kerberos 5 address to store the address in\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sockaddr2port (krb5_context context, const struct sockaddr * sa, int16_t * port)" +krb5_sockaddr2port extracts a port (if possible) from a "struct sockaddr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIsa\fP a struct sockaddr to extract the port from +.br +\fIport\fP a pointer to an int16_t store the port in\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. Will return KRB5_PROG_ATYPE_NOSUPP in case address type is not supported\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_sockaddr_uninteresting (const struct sockaddr * sa)" +krb5_sockaddr_uninteresting returns TRUE for all \&.Fa sa that the kerberos library thinks are uninteresting\&. One example are link local addresses\&. +.PP +\fBParameters\fP +.RS 4 +\fIsa\fP pointer to struct sockaddr that might be interesting\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return a non zero for uninteresting addresses\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_address_compare.3 b/static/netbsd/man3/krb5_address_compare.3 new file mode 100644 index 00000000..f1847742 --- /dev/null +++ b/static/netbsd/man3/krb5_address_compare.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_address_compare.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_address_order.3 b/static/netbsd/man3/krb5_address_order.3 new file mode 100644 index 00000000..5445f68e --- /dev/null +++ b/static/netbsd/man3/krb5_address_order.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_address_order.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_address_prefixlen_boundary.3 b/static/netbsd/man3/krb5_address_prefixlen_boundary.3 new file mode 100644 index 00000000..439618cd --- /dev/null +++ b/static/netbsd/man3/krb5_address_prefixlen_boundary.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_address_prefixlen_boundary.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_address_search.3 b/static/netbsd/man3/krb5_address_search.3 new file mode 100644 index 00000000..4332cbaa --- /dev/null +++ b/static/netbsd/man3/krb5_address_search.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_address_search.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_allow_weak_crypto.3 b/static/netbsd/man3/krb5_allow_weak_crypto.3 new file mode 100644 index 00000000..de95ccd6 --- /dev/null +++ b/static/netbsd/man3/krb5_allow_weak_crypto.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_allow_weak_crypto.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_aname_to_localname.3 b/static/netbsd/man3/krb5_aname_to_localname.3 new file mode 100644 index 00000000..2ae297ca --- /dev/null +++ b/static/netbsd/man3/krb5_aname_to_localname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_aname_to_localname.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_anyaddr.3 b/static/netbsd/man3/krb5_anyaddr.3 new file mode 100644 index 00000000..2e34b176 --- /dev/null +++ b/static/netbsd/man3/krb5_anyaddr.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_anyaddr.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_appdefault.3 b/static/netbsd/man3/krb5_appdefault.3 new file mode 100644 index 00000000..ac0fb0ed --- /dev/null +++ b/static/netbsd/man3/krb5_appdefault.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: krb5_appdefault.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2000 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd July 25, 2000 +.Dt KRB5_APPDEFAULT 3 +.Os +.Sh NAME +.Nm krb5_appdefault_boolean , +.Nm krb5_appdefault_string , +.Nm krb5_appdefault_time +.Nd get application configuration value +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft void +.Fn krb5_appdefault_boolean "krb5_context context" "const char *appname" "krb5_realm realm" "const char *option" "krb5_boolean def_val" "krb5_boolean *ret_val" +.Ft void +.Fn krb5_appdefault_string "krb5_context context" "const char *appname" "krb5_realm realm" "const char *option" "const char *def_val" "char **ret_val" +.Ft void +.Fn krb5_appdefault_time "krb5_context context" "const char *appname" "krb5_realm realm" "const char *option" "time_t def_val" "time_t *ret_val" +.Sh DESCRIPTION +These functions get application defaults from the +.Dv appdefaults +section of the +.Xr krb5.conf 5 +configuration file. These defaults can be specified per application, +and/or per realm. +.Pp +These values will be looked for in +.Xr krb5.conf 5 , +in order of descending importance. +.Bd -literal -offset indent +[appdefaults] + appname = { + realm = { + option = value + } + } + appname = { + option = value + } + realm = { + option = value + } + option = value +.Ed +.Fa appname +is the name of the application, and +.Fa realm +is the realm name. If the realm is omitted it will not be used for +resolving values. +.Fa def_val +is the value to return if no value is found in +.Xr krb5.conf 5 . +.Sh SEE ALSO +.Xr krb5_config 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_append_addresses.3 b/static/netbsd/man3/krb5_append_addresses.3 new file mode 100644 index 00000000..9f74a000 --- /dev/null +++ b/static/netbsd/man3/krb5_append_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_append_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_auth.3 b/static/netbsd/man3/krb5_auth.3 new file mode 100644 index 00000000..6cd2d858 --- /dev/null +++ b/static/netbsd/man3/krb5_auth.3 @@ -0,0 +1,140 @@ +.\" $NetBSD: krb5_auth.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_auth" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_auth \- Heimdal Kerberos 5 authentication functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_rd_req_in_ctx_alloc\fP (krb5_context context, krb5_rd_req_in_ctx *ctx)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_rd_req_in_set_keytab\fP (krb5_context context, krb5_rd_req_in_ctx in, krb5_keytab keytab)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_rd_req_in_set_pac_check\fP (krb5_context context, krb5_rd_req_in_ctx in, krb5_boolean flag)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_rd_req_out_get_server\fP (krb5_context context, krb5_rd_req_out_ctx out, krb5_principal *principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_rd_req_out_ctx_free\fP (krb5_context context, krb5_rd_req_out_ctx ctx)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_rd_req_ctx\fP (krb5_context context, krb5_auth_context *auth_context, const krb5_data *inbuf, krb5_const_principal server, krb5_rd_req_in_ctx inctx, krb5_rd_req_out_ctx *outctx)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_ctx (krb5_context context, krb5_auth_context * auth_context, const krb5_data * inbuf, krb5_const_principal server, krb5_rd_req_in_ctx inctx, krb5_rd_req_out_ctx * outctx)" +The core server function that verify application authentication requests from clients\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIauth_context\fP the authentication context, can be NULL, then default values for the authentication context will used\&. +.br +\fIinbuf\fP the (AP-REQ) authentication buffer +.br +\fIserver\fP the server to authenticate to\&. If NULL the function will try to find any available credential in the keytab that will verify the reply\&. The function will prefer the server specified in the AP-REQ, but if there is no mach, it will try all keytab entries for a match\&. This has serious performance issues for large keytabs\&. +.br +\fIinctx\fP control the behavior of the function, if NULL, the default behavior is used\&. +.br +\fIoutctx\fP the return outctx, free with \fBkrb5_rd_req_out_ctx_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_ctx_alloc (krb5_context context, krb5_rd_req_in_ctx * ctx)" +Allocate a krb5_rd_req_in_ctx as an input parameter to \fBkrb5_rd_req_ctx()\fP\&. The caller should free the context with krb5_rd_req_in_ctx_free() when done with the context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIctx\fP in ctx to \fBkrb5_rd_req_ctx()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_set_keytab (krb5_context context, krb5_rd_req_in_ctx in, krb5_keytab keytab)" +Set the keytab that \fBkrb5_rd_req_ctx()\fP will use\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIin\fP in ctx to \fBkrb5_rd_req_ctx()\fP\&. +.br +\fIkeytab\fP keytab that \fBkrb5_rd_req_ctx()\fP will use, only copy the pointer, so the caller must free they keytab after krb5_rd_req_in_ctx_free() is called\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_in_set_pac_check (krb5_context context, krb5_rd_req_in_ctx in, krb5_boolean flag)" +Set if krb5_rq_red() is going to check the Windows PAC or not +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIin\fP krb5_rd_req_in_ctx to check the option on\&. +.br +\fIflag\fP flag to select if to check the pac (TRUE) or not (FALSE)\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_rd_req_out_ctx_free (krb5_context context, krb5_rd_req_out_ctx ctx)" +Free the krb5_rd_req_out_ctx\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Keberos 5 context\&. +.br +\fIctx\fP krb5_rd_req_out_ctx context to free\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_rd_req_out_get_server (krb5_context context, krb5_rd_req_out_ctx out, krb5_principal * principal)" +Get the principal that was used in the request from the client\&. Might not match whats in the ticket if \fBkrb5_rd_req_ctx()\fP searched in the keytab for a matching key\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIout\fP a krb5_rd_req_out_ctx from \fBkrb5_rd_req_ctx()\fP\&. +.br +\fIprincipal\fP return principal, free with \fBkrb5_free_principal()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_auth_context.3 b/static/netbsd/man3/krb5_auth_context.3 new file mode 100644 index 00000000..7733dfca --- /dev/null +++ b/static/netbsd/man3/krb5_auth_context.3 @@ -0,0 +1,397 @@ +.\" $NetBSD: krb5_auth_context.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2001 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 17, 2005 +.Dt KRB5_AUTH_CONTEXT 3 +.Os +.Sh NAME +.Nm krb5_auth_con_addflags , +.Nm krb5_auth_con_free , +.Nm krb5_auth_con_genaddrs , +.Nm krb5_auth_con_generatelocalsubkey , +.Nm krb5_auth_con_getaddrs , +.Nm krb5_auth_con_getauthenticator , +.Nm krb5_auth_con_getflags , +.Nm krb5_auth_con_getkey , +.Nm krb5_auth_con_getlocalsubkey , +.Nm krb5_auth_con_getrcache , +.Nm krb5_auth_con_getremotesubkey , +.Nm krb5_auth_con_getuserkey , +.Nm krb5_auth_con_init , +.Nm krb5_auth_con_initivector , +.Nm krb5_auth_con_removeflags , +.Nm krb5_auth_con_setaddrs , +.Nm krb5_auth_con_setaddrs_from_fd , +.Nm krb5_auth_con_setflags , +.Nm krb5_auth_con_setivector , +.Nm krb5_auth_con_setkey , +.Nm krb5_auth_con_setlocalsubkey , +.Nm krb5_auth_con_setrcache , +.Nm krb5_auth_con_setremotesubkey , +.Nm krb5_auth_con_setuserkey , +.Nm krb5_auth_context , +.Nm krb5_auth_getcksumtype , +.Nm krb5_auth_getkeytype , +.Nm krb5_auth_getlocalseqnumber , +.Nm krb5_auth_getremoteseqnumber , +.Nm krb5_auth_setcksumtype , +.Nm krb5_auth_setkeytype , +.Nm krb5_auth_setlocalseqnumber , +.Nm krb5_auth_setremoteseqnumber , +.Nm krb5_free_authenticator +.Nd manage authentication on connection level +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_auth_con_init +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fc +.Ft void +.Fo krb5_auth_con_free +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_addflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t addflags" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_removeflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t removelags" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_address *local_addr" +.Fa "krb5_address *remote_addr" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_address **local_addr" +.Fa "krb5_address **remote_addr" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_genaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int fd" +.Fa "int flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setaddrs_from_fd +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "void *p_fd" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getlocalsubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getremotesubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_generatelocalsubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_initivector +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setivector +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "krb5_pointer ivector" +.Fc +.Ft void +.Fo krb5_free_authenticator +.Fa "krb5_context context" +.Fa "krb5_authenticator *authenticator" +.Fc +.Sh DESCRIPTION +The +.Nm krb5_auth_context +structure holds all context related to an authenticated connection, in +a similar way to +.Nm krb5_context +that holds the context for the thread or process. +.Nm krb5_auth_context +is used by various functions that are directly related to +authentication between the server/client. Example of data that this +structure contains are various flags, addresses of client and server, +port numbers, keyblocks (and subkeys), sequence numbers, replay cache, +and checksum-type. +.Pp +.Fn krb5_auth_con_init +allocates and initializes the +.Nm krb5_auth_context +structure. Default values can be changed with +.Fn krb5_auth_con_setcksumtype +and +.Fn krb5_auth_con_setflags . +The +.Nm auth_context +structure must be freed by +.Fn krb5_auth_con_free . +.Pp +.Fn krb5_auth_con_getflags , +.Fn krb5_auth_con_setflags , +.Fn krb5_auth_con_addflags +and +.Fn krb5_auth_con_removeflags +gets and modifies the flags for a +.Nm krb5_auth_context +structure. Possible flags to set are: +.Bl -tag -width Ds +.It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE +Generate and check sequence-number on each packet. +.It Dv KRB5_AUTH_CONTEXT_DO_TIME +Check timestamp on incoming packets. +.It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE , Dv KRB5_AUTH_CONTEXT_RET_TIME +Return sequence numbers and time stamps in the outdata parameters. +.It Dv KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED +will force +.Fn krb5_get_forwarded_creds +and +.Fn krb5_fwd_tgt_creds +to create unencrypted ) +.Dv KRB5_ENCTYPE_NULL ) +credentials. +This is for use with old MIT server and JAVA based servers as +they can't handle encrypted +.Dv KRB-CRED . +Note that sending such +.Dv KRB-CRED +is clear exposes crypto keys and tickets and is insecure, +make sure the packet is encrypted in the protocol. +.Xr krb5_rd_cred 3 , +.Xr krb5_rd_priv 3 , +.Xr krb5_rd_safe 3 , +.Xr krb5_mk_priv 3 +and +.Xr krb5_mk_safe 3 . +Setting this flag requires that parameter to be passed to these +functions. +.Pp +The flags +.Dv KRB5_AUTH_CONTEXT_DO_TIME +also modifies the behavior the function +.Fn krb5_get_forwarded_creds +by removing the timestamp in the forward credential message, this have +backward compatibility problems since not all versions of the heimdal +supports timeless credentional messages. +Is very useful since it always the sender of the message to cache +forward message and thus avoiding a round trip to the KDC for each +time a credential is forwarded. +The same functionality can be obtained by using address-less tickets. +.\".It Dv KRB5_AUTH_CONTEXT_PERMIT_ALL +.El +.Pp +.Fn krb5_auth_con_setaddrs , +.Fn krb5_auth_con_setaddrs_from_fd +and +.Fn krb5_auth_con_getaddrs +gets and sets the addresses that are checked when a packet is received. +It is mandatory to set an address for the remote +host. If the local address is not set, it iss deduced from the underlaying +operating system. +.Fn krb5_auth_con_getaddrs +will call +.Fn krb5_free_address +on any address that is passed in +.Fa local_addr +or +.Fa remote_addr . +.Fn krb5_auth_con_setaddr +allows passing in a +.Dv NULL +pointer as +.Fa local_addr +and +.Fa remote_addr , +in that case it will just not set that address. +.Pp +.Fn krb5_auth_con_setaddrs_from_fd +fetches the addresses from a file descriptor. +.Pp +.Fn krb5_auth_con_genaddrs +fetches the address information from the given file descriptor +.Fa fd +depending on the bitmap argument +.Fa flags . +.Pp +Possible values on +.Fa flags +are: +.Bl -tag -width Ds +.It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR +fetches the local address from +.Fa fd . +.It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR +fetches the remote address from +.Fa fd . +.El +.Pp +.Fn krb5_auth_con_setkey , +.Fn krb5_auth_con_setuserkey +and +.Fn krb5_auth_con_getkey +gets and sets the key used for this auth context. The keyblock returned by +.Fn krb5_auth_con_getkey +should be freed with +.Fn krb5_free_keyblock . +The keyblock send into +.Fn krb5_auth_con_setkey +is copied into the +.Nm krb5_auth_context , +and thus no special handling is needed. +.Dv NULL +is not a valid keyblock to +.Fn krb5_auth_con_setkey . +.Pp +.Fn krb5_auth_con_setuserkey +is only useful when doing user to user authentication. +.Fn krb5_auth_con_setkey +is equivalent to +.Fn krb5_auth_con_setuserkey . +.Pp +.Fn krb5_auth_con_getlocalsubkey , +.Fn krb5_auth_con_setlocalsubkey , +.Fn krb5_auth_con_getremotesubkey +and +.Fn krb5_auth_con_setremotesubkey +gets and sets the keyblock for the local and remote subkey. +The keyblock returned by +.Fn krb5_auth_con_getlocalsubkey +and +.Fn krb5_auth_con_getremotesubkey +must be freed with +.Fn krb5_free_keyblock . +.Pp +.Fn krb5_auth_setcksumtype +and +.Fn krb5_auth_getcksumtype +sets and gets the checksum type that should be used for this +connection. +.Pp +.Fn krb5_auth_con_generatelocalsubkey +generates a local subkey that have the same encryption type as +.Fa key . +.Pp +.Fn krb5_auth_getremoteseqnumber +.Fn krb5_auth_setremoteseqnumber , +.Fn krb5_auth_getlocalseqnumber +and +.Fn krb5_auth_setlocalseqnumber +gets and sets the sequence-number for the local and remote +sequence-number counter. +.Pp +.Fn krb5_auth_setkeytype +and +.Fn krb5_auth_getkeytype +gets and gets the keytype of the keyblock in +.Nm krb5_auth_context . +.Pp +.Fn krb5_auth_con_getauthenticator +Retrieves the authenticator that was used during mutual +authentication. The +.Dv authenticator +returned should be freed by calling +.Fn krb5_free_authenticator . +.Pp +.Fn krb5_auth_con_getrcache +and +.Fn krb5_auth_con_setrcache +gets and sets the replay-cache. +.Pp +.Fn krb5_auth_con_initivector +allocates memory for and zeros the initial vector in the +.Fa auth_context +keyblock. +.Pp +.Fn krb5_auth_con_setivector +sets the i_vector portion of +.Fa auth_context +to +.Fa ivector . +.Pp +.Fn krb5_free_authenticator +free the content of +.Fa authenticator +and +.Fa authenticator +itself. +.Sh SEE ALSO +.Xr krb5_context 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_auth_getremoteseqnumber.3 b/static/netbsd/man3/krb5_auth_getremoteseqnumber.3 new file mode 100644 index 00000000..aaf3ce39 --- /dev/null +++ b/static/netbsd/man3/krb5_auth_getremoteseqnumber.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_auth_getremoteseqnumber.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_build_principal.3 b/static/netbsd/man3/krb5_build_principal.3 new file mode 100644 index 00000000..983a80bc --- /dev/null +++ b/static/netbsd/man3/krb5_build_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_build_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_c_enctype_compare.3 b/static/netbsd/man3/krb5_c_enctype_compare.3 new file mode 100644 index 00000000..66178982 --- /dev/null +++ b/static/netbsd/man3/krb5_c_enctype_compare.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_c_enctype_compare.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_c_make_checksum.3 b/static/netbsd/man3/krb5_c_make_checksum.3 new file mode 100644 index 00000000..1c6dcbf7 --- /dev/null +++ b/static/netbsd/man3/krb5_c_make_checksum.3 @@ -0,0 +1,299 @@ +.\" $NetBSD: krb5_c_make_checksum.3,v 1.5 2023/06/19 21:41:44 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd Nov 17, 2006 +.Dt KRB5_C_MAKE_CHECKSUM 3 +.Os +.Sh NAME +.Nm krb5_c_block_size , +.Nm krb5_c_decrypt , +.Nm krb5_c_encrypt , +.Nm krb5_c_encrypt_length , +.Nm krb5_c_enctype_compare , +.Nm krb5_c_get_checksum , +.Nm krb5_c_is_coll_proof_cksum , +.Nm krb5_c_is_keyed_cksum , +.Nm krb5_c_keylength , +.Nm krb5_c_make_checksum , +.Nm krb5_c_make_random_key , +.Nm krb5_c_set_checksum , +.Nm krb5_c_valid_cksumtype , +.Nm krb5_c_valid_enctype , +.Nm krb5_c_verify_checksum , +.Nm krb5_c_checksum_length +.Nd Kerberos 5 crypto API +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft krb5_error_code +.Fo krb5_c_block_size +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "size_t *blocksize" +.Fc +.Ft krb5_error_code +.Fo krb5_c_decrypt +.Fa "krb5_context context" +.Fa "const krb5_keyblock key" +.Fa "krb5_keyusage usage" +.Fa "const krb5_data *ivec" +.Fa "krb5_enc_data *input" +.Fa "krb5_data *output" +.Fc +.Ft krb5_error_code +.Fo krb5_c_encrypt +.Fa "krb5_context context" +.Fa "const krb5_keyblock *key" +.Fa "krb5_keyusage usage" +.Fa "const krb5_data *ivec" +.Fa "const krb5_data *input" +.Fa "krb5_enc_data *output" +.Fc +.Ft krb5_error_code +.Fo krb5_c_encrypt_length +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "size_t inputlen" +.Fa "size_t *length" +.Fc +.Ft krb5_error_code +.Fo krb5_c_enctype_compare +.Fa "krb5_context context" +.Fa "krb5_enctype e1" +.Fa "krb5_enctype e2" +.Fa "krb5_boolean *similar" +.Fc +.Ft krb5_error_code +.Fo krb5_c_make_random_key +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "krb5_keyblock *random_key" +.Fc +.Ft krb5_error_code +.Fo krb5_c_make_checksum +.Fa "krb5_context context" +.Fa "krb5_cksumtype cksumtype" +.Fa "const krb5_keyblock *key" +.Fa "krb5_keyusage usage" +.Fa "const krb5_data *input" +.Fa "krb5_checksum *cksum" +.Fc +.Ft krb5_error_code +.Fo krb5_c_verify_checksum +.Fa "krb5_context context" +.Fa "const krb5_keyblock *key" +.Fa "krb5_keyusage usage" +.Fa "const krb5_data *data" +.Fa "const krb5_checksum *cksum" +.Fa "krb5_boolean *valid" +.Fc +.Ft krb5_error_code +.Fo krb5_c_checksum_length +.Fa "krb5_context context" +.Fa "krb5_cksumtype cksumtype" +.Fa "size_t *length" +.Fc +.Ft krb5_error_code +.Fo krb5_c_get_checksum +.Fa "krb5_context context" +.Fa "const krb5_checksum *cksum" +.Fa "krb5_cksumtype *type" +.Fa "krb5_data **data" +.Fc +.Ft krb5_error_code +.Fo krb5_c_set_checksum +.Fa "krb5_context context" +.Fa "krb5_checksum *cksum" +.Fa "krb5_cksumtype type" +.Fa "const krb5_data *data" +.Fc +.Ft krb5_boolean +.Fo krb5_c_valid_enctype +.Fa krb5_enctype etype" +.Fc +.Ft krb5_boolean +.Fo krb5_c_valid_cksumtype +.Fa "krb5_cksumtype ctype" +.Fc +.Ft krb5_boolean +.Fo krb5_c_is_coll_proof_cksum +.Fa "krb5_cksumtype ctype" +.Fc +.Ft krb5_boolean +.Fo krb5_c_is_keyed_cksum +.Fa "krb5_cksumtype ctype" +.Fc +.Ft krb5_error_code +.Fo krb5_c_keylengths +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "size_t *inlength" +.Fa "size_t *keylength" +.Fc +.Sh DESCRIPTION +The functions starting with krb5_c are compat functions with MIT kerberos. +.Pp +The +.Li krb5_enc_data +structure holds and encrypted data. +There are two public accessible members of +.Li krb5_enc_data . +.Li enctype +that holds the encryption type of the data encrypted and +.Li ciphertext +that is a +.Ft krb5_data +that might contain the encrypted data. +.Pp +.Fn krb5_c_block_size +returns the blocksize of the encryption type. +.Pp +.Fn krb5_c_decrypt +decrypts +.Fa input +and store the data in +.Fa output. +If +.Fa ivec +is +.Dv NULL +the default initialization vector for that encryption type will be used. +.Pp +.Fn krb5_c_encrypt +encrypts the plaintext in +.Fa input +and store the ciphertext in +.Fa output . +.Pp +.Fn krb5_c_encrypt_length +returns the length the encrypted data given the plaintext length. +.Pp +.Fn krb5_c_enctype_compare +compares to encryption types and returns if they use compatible +encryption key types. +.Pp +.Fn krb5_c_make_checksum +creates a checksum +.Fa cksum +with the checksum type +.Fa cksumtype +of the data in +.Fa data . +.Fa key +and +.Fa usage +are used if the checksum is a keyed checksum type. +Returns 0 or an error code. +.Pp +.Fn krb5_c_verify_checksum +verifies the checksum +of +.Fa data +in +.Fa cksum +that was created with +.Fa key +using the key usage +.Fa usage . +.Fa verify +is set to non-zero if the checksum verifies correctly and zero if not. +Returns 0 or an error code. +.Pp +.Fn krb5_c_checksum_length +returns the length of the checksum. +.Pp +.Fn krb5_c_set_checksum +sets the +.Li krb5_checksum +structure given +.Fa type +and +.Fa data . +The content of +.Fa cksum +should be freeed with +.Fn krb5_c_free_checksum_contents . +.Pp +.Fn krb5_c_get_checksum +retrieves the components of the +.Li krb5_checksum . +structure. +.Fa data +should be free with +.Fn krb5_free_data . +If some either of +.Fa data +or +.Fa checksum +is not needed for the application, +.Dv NULL +can be passed in. +.Pp +.Fn krb5_c_valid_enctype +returns true if +.Fa etype +is a valid encryption type. +.Pp +.Fn krb5_c_valid_cksumtype +returns true if +.Fa ctype +is a valid checksum type. +.Pp +.Fn krb5_c_is_keyed_cksum +return true if +.Fa ctype +is a keyed checksum type. +.Pp +.Fn krb5_c_is_coll_proof_cksum +returns true if +.Fa ctype +is a collision proof checksum type. +.Pp +.Fn krb5_c_keylengths +return the minimum length +.Fa ( inlength ) +bytes needed to create a key and the +length +.Fa ( keylength ) +of the resulting key +for the +.Fa enctype . +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_create_checksum 3 , +.Xr krb5_free_data 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_cc_cache_end_seq_get.3 b/static/netbsd/man3/krb5_cc_cache_end_seq_get.3 new file mode 100644 index 00000000..d03ac559 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_cache_end_seq_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_cache_end_seq_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_cache_get_first.3 b/static/netbsd/man3/krb5_cc_cache_get_first.3 new file mode 100644 index 00000000..e978d54a --- /dev/null +++ b/static/netbsd/man3/krb5_cc_cache_get_first.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_cache_get_first.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_cache_match.3 b/static/netbsd/man3/krb5_cc_cache_match.3 new file mode 100644 index 00000000..2eb5757e --- /dev/null +++ b/static/netbsd/man3/krb5_cc_cache_match.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_cache_match.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_cache_next.3 b/static/netbsd/man3/krb5_cc_cache_next.3 new file mode 100644 index 00000000..0154b1dd --- /dev/null +++ b/static/netbsd/man3/krb5_cc_cache_next.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_cache_next.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_clear_mcred.3 b/static/netbsd/man3/krb5_cc_clear_mcred.3 new file mode 100644 index 00000000..ec7a8fe5 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_clear_mcred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_clear_mcred.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_close.3 b/static/netbsd/man3/krb5_cc_close.3 new file mode 100644 index 00000000..5583274c --- /dev/null +++ b/static/netbsd/man3/krb5_cc_close.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_close.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_copy_cache.3 b/static/netbsd/man3/krb5_cc_copy_cache.3 new file mode 100644 index 00000000..5fb80519 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_copy_cache.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_copy_cache.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_copy_creds.3 b/static/netbsd/man3/krb5_cc_copy_creds.3 new file mode 100644 index 00000000..3dd0638b --- /dev/null +++ b/static/netbsd/man3/krb5_cc_copy_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_copy_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_copy_match_f.3 b/static/netbsd/man3/krb5_cc_copy_match_f.3 new file mode 100644 index 00000000..7592b359 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_copy_match_f.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_copy_match_f.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_default.3 b/static/netbsd/man3/krb5_cc_default.3 new file mode 100644 index 00000000..3ac5a3d7 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_default_name.3 b/static/netbsd/man3/krb5_cc_default_name.3 new file mode 100644 index 00000000..a0efb3d8 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_default_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_default_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_destroy.3 b/static/netbsd/man3/krb5_cc_destroy.3 new file mode 100644 index 00000000..78e84bc0 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_destroy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_destroy.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_end_seq_get.3 b/static/netbsd/man3/krb5_cc_end_seq_get.3 new file mode 100644 index 00000000..313407d2 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_end_seq_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_end_seq_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_gen_new.3 b/static/netbsd/man3/krb5_cc_gen_new.3 new file mode 100644 index 00000000..fcdadf36 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_gen_new.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_gen_new.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_config.3 b/static/netbsd/man3/krb5_cc_get_config.3 new file mode 100644 index 00000000..129b1b39 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_config.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_config.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_flags.3 b/static/netbsd/man3/krb5_cc_get_flags.3 new file mode 100644 index 00000000..41b12f61 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_friendly_name.3 b/static/netbsd/man3/krb5_cc_get_friendly_name.3 new file mode 100644 index 00000000..afca0f8f --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_friendly_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_friendly_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_full_name.3 b/static/netbsd/man3/krb5_cc_get_full_name.3 new file mode 100644 index 00000000..dbbf3a79 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_full_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_full_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_kdc_offset.3 b/static/netbsd/man3/krb5_cc_get_kdc_offset.3 new file mode 100644 index 00000000..effdb40e --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_kdc_offset.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_kdc_offset.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_lifetime.3 b/static/netbsd/man3/krb5_cc_get_lifetime.3 new file mode 100644 index 00000000..5d41ee2d --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_lifetime.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_lifetime.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_name.3 b/static/netbsd/man3/krb5_cc_get_name.3 new file mode 100644 index 00000000..02fdc778 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_ops.3 b/static/netbsd/man3/krb5_cc_get_ops.3 new file mode 100644 index 00000000..483d65f5 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_prefix_ops.3 b/static/netbsd/man3/krb5_cc_get_prefix_ops.3 new file mode 100644 index 00000000..2cb2b0f5 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_prefix_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_prefix_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_principal.3 b/static/netbsd/man3/krb5_cc_get_principal.3 new file mode 100644 index 00000000..3c7d1b6b --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_type.3 b/static/netbsd/man3/krb5_cc_get_type.3 new file mode 100644 index 00000000..0a487c42 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_type.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_type.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_get_version.3 b/static/netbsd/man3/krb5_cc_get_version.3 new file mode 100644 index 00000000..04e67a7c --- /dev/null +++ b/static/netbsd/man3/krb5_cc_get_version.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_get_version.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_initialize.3 b/static/netbsd/man3/krb5_cc_initialize.3 new file mode 100644 index 00000000..e20da7aa --- /dev/null +++ b/static/netbsd/man3/krb5_cc_initialize.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_initialize.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_last_change_time.3 b/static/netbsd/man3/krb5_cc_last_change_time.3 new file mode 100644 index 00000000..b5a58bc1 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_last_change_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_last_change_time.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_move.3 b/static/netbsd/man3/krb5_cc_move.3 new file mode 100644 index 00000000..77d9dac1 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_move.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_move.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_new_unique.3 b/static/netbsd/man3/krb5_cc_new_unique.3 new file mode 100644 index 00000000..b31d8b30 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_new_unique.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_new_unique.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_next_cred.3 b/static/netbsd/man3/krb5_cc_next_cred.3 new file mode 100644 index 00000000..ed322483 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_next_cred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_next_cred.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_register.3 b/static/netbsd/man3/krb5_cc_register.3 new file mode 100644 index 00000000..7584b9df --- /dev/null +++ b/static/netbsd/man3/krb5_cc_register.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_register.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_remove_cred.3 b/static/netbsd/man3/krb5_cc_remove_cred.3 new file mode 100644 index 00000000..27a5f460 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_remove_cred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_remove_cred.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_resolve.3 b/static/netbsd/man3/krb5_cc_resolve.3 new file mode 100644 index 00000000..8b68d3c3 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_resolve.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_resolve.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_retrieve_cred.3 b/static/netbsd/man3/krb5_cc_retrieve_cred.3 new file mode 100644 index 00000000..b7a066b4 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_retrieve_cred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_retrieve_cred.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_set_config.3 b/static/netbsd/man3/krb5_cc_set_config.3 new file mode 100644 index 00000000..b8c5c3d1 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_set_config.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_set_config.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_set_default_name.3 b/static/netbsd/man3/krb5_cc_set_default_name.3 new file mode 100644 index 00000000..2a7c268a --- /dev/null +++ b/static/netbsd/man3/krb5_cc_set_default_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_set_default_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_set_flags.3 b/static/netbsd/man3/krb5_cc_set_flags.3 new file mode 100644 index 00000000..1f9d09ec --- /dev/null +++ b/static/netbsd/man3/krb5_cc_set_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_set_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_set_friendly_name.3 b/static/netbsd/man3/krb5_cc_set_friendly_name.3 new file mode 100644 index 00000000..9f0efdab --- /dev/null +++ b/static/netbsd/man3/krb5_cc_set_friendly_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_set_friendly_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_set_kdc_offset.3 b/static/netbsd/man3/krb5_cc_set_kdc_offset.3 new file mode 100644 index 00000000..25769e2a --- /dev/null +++ b/static/netbsd/man3/krb5_cc_set_kdc_offset.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_set_kdc_offset.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_start_seq_get.3 b/static/netbsd/man3/krb5_cc_start_seq_get.3 new file mode 100644 index 00000000..e3b84a82 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_start_seq_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_start_seq_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_store_cred.3 b/static/netbsd/man3/krb5_cc_store_cred.3 new file mode 100644 index 00000000..d13a9b0a --- /dev/null +++ b/static/netbsd/man3/krb5_cc_store_cred.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_store_cred.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_support_switch.3 b/static/netbsd/man3/krb5_cc_support_switch.3 new file mode 100644 index 00000000..4bdff93c --- /dev/null +++ b/static/netbsd/man3/krb5_cc_support_switch.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_support_switch.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cc_switch.3 b/static/netbsd/man3/krb5_cc_switch.3 new file mode 100644 index 00000000..340c4217 --- /dev/null +++ b/static/netbsd/man3/krb5_cc_switch.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cc_switch.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_ccache.3 b/static/netbsd/man3/krb5_ccache.3 new file mode 100644 index 00000000..9b87e636 --- /dev/null +++ b/static/netbsd/man3/krb5_ccache.3 @@ -0,0 +1,882 @@ +.\" $NetBSD: krb5_ccache.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_ccache" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_ccache \- Heimdal Kerberos 5 credential cache functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_register\fP (krb5_context context, const krb5_cc_ops *ops, krb5_boolean override)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_resolve\fP (krb5_context context, const char *name, krb5_ccache *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_new_unique\fP (krb5_context context, const char *type, const char *hint, krb5_ccache *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_cc_get_name\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_cc_get_type\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_full_name\fP (krb5_context context, krb5_ccache id, char **str)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const krb5_cc_ops *KRB5_LIB_CALL \fBkrb5_cc_get_ops\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_switch\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_cc_support_switch\fP (krb5_context context, const char *type)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_set_default_name\fP (krb5_context context, const char *name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_cc_default_name\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_default\fP (krb5_context context, krb5_ccache *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_initialize\fP (krb5_context context, krb5_ccache id, krb5_principal primary_principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_destroy\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_close\fP (krb5_context context, krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_store_cred\fP (krb5_context context, krb5_ccache id, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_retrieve_cred\fP (krb5_context context, krb5_ccache id, krb5_flags whichfields, const krb5_creds *mcreds, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_principal\fP (krb5_context context, krb5_ccache id, krb5_principal *principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_start_seq_get\fP (krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_next_cred\fP (krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_end_seq_get\fP (krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_remove_cred\fP (krb5_context context, krb5_ccache id, krb5_flags which, krb5_creds *cred)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_set_flags\fP (krb5_context context, krb5_ccache id, krb5_flags flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_flags\fP (krb5_context context, krb5_ccache id, krb5_flags *flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_copy_match_f\fP (krb5_context context, const krb5_ccache from, krb5_ccache to, krb5_boolean(*match)(krb5_context, void *, const krb5_creds *), void *matchctx, unsigned int *matched)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_copy_cache\fP (krb5_context context, const krb5_ccache from, krb5_ccache to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_version\fP (krb5_context context, const krb5_ccache id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_cc_clear_mcred\fP (krb5_creds *mcred)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const krb5_cc_ops *KRB5_LIB_CALL \fBkrb5_cc_get_prefix_ops\fP (krb5_context context, const char *prefix)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_cache_get_first\fP (krb5_context context, const char *type, krb5_cc_cache_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_cache_next\fP (krb5_context context, krb5_cc_cache_cursor cursor, krb5_ccache *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_cache_end_seq_get\fP (krb5_context context, krb5_cc_cache_cursor cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_cache_match\fP (krb5_context context, krb5_principal client, krb5_ccache *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_move\fP (krb5_context context, krb5_ccache from, krb5_ccache to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_is_config_principal\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_set_config\fP (krb5_context context, krb5_ccache id, krb5_const_principal principal, const char *name, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_config\fP (krb5_context context, krb5_ccache id, krb5_const_principal principal, const char *name, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cccol_cursor_new\fP (krb5_context context, krb5_cccol_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cccol_cursor_next\fP (krb5_context context, krb5_cccol_cursor cursor, krb5_ccache *cache)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cccol_cursor_free\fP (krb5_context context, krb5_cccol_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_last_change_time\fP (krb5_context context, krb5_ccache id, krb5_timestamp *mtime)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cccol_last_change_time\fP (krb5_context context, const char *type, krb5_timestamp *mtime)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_friendly_name\fP (krb5_context context, krb5_ccache id, char **name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_set_friendly_name\fP (krb5_context context, krb5_ccache id, const char *name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_lifetime\fP (krb5_context context, krb5_ccache id, time_t *t)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_set_kdc_offset\fP (krb5_context context, krb5_ccache id, krb5_deltat offset)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_get_kdc_offset\fP (krb5_context context, krb5_ccache id, krb5_deltat *offset)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_gen_new\fP (krb5_context context, const krb5_cc_ops *ops, krb5_ccache *id) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cc_copy_creds\fP (krb5_context context, const krb5_ccache from, krb5_ccache to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_validated_creds\fP (krb5_context context, krb5_creds *creds, krb5_principal client, krb5_ccache ccache, char *service)" +.br +.in -1c +.SS "Variables" + +.in +1c +.ti -1c +.RI "KRB5_LIB_VARIABLE const krb5_cc_ops \fBkrb5_acc_ops\fP" +.br +.ti -1c +.RI "KRB5_LIB_VARIABLE const krb5_cc_ops \fBkrb5_dcc_ops\fP" +.br +.ti -1c +.RI "KRB5_LIB_VARIABLE const krb5_cc_ops \fBkrb5_fcc_ops\fP" +.br +.ti -1c +.RI "KRB5_LIB_VARIABLE const krb5_cc_ops \fBkrb5_mcc_ops\fP" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_end_seq_get (krb5_context context, krb5_cc_cache_cursor cursor)" +Destroy the cursor `cursor'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_get_first (krb5_context context, const char * type, krb5_cc_cache_cursor * cursor)" +Start iterating over all caches of specified type\&. See also \fBkrb5_cccol_cursor_new()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fItype\fP optional type to iterate over, if NULL, the default cache is used\&. +.br +\fIcursor\fP cursor should be freed with \fBkrb5_cc_cache_end_seq_get()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_match (krb5_context context, krb5_principal client, krb5_ccache * id)" +Search for a matching credential cache that have the `principal' as the default principal\&. On success, `id' needs to be freed with \fBkrb5_cc_close()\fP or \fBkrb5_cc_destroy()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIclient\fP The principal to search for +.br +\fIid\fP the returned credential cache +.RE +.PP +\fBReturns\fP +.RS 4 +On failure, error code is returned and `id' is set to NULL\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_cache_next (krb5_context context, krb5_cc_cache_cursor cursor, krb5_ccache * id)" +Retrieve the next cache pointed to by (`cursor') in `id' and advance `cursor'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIcursor\fP the iterator cursor, returned by \fBkrb5_cc_cache_get_first()\fP +.br +\fIid\fP next ccache +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or an error code\&. Returns KRB5_CC_END when the end of caches is reached, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_cc_clear_mcred (krb5_creds * mcred)" +Clear `mcreds' so it can be used with krb5_cc_retrieve_cred +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_close (krb5_context context, krb5_ccache id)" +Stop using the ccache `id' and free the related resources\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_cache (krb5_context context, const krb5_ccache from, krb5_ccache to)" +Just like \fBkrb5_cc_copy_match_f()\fP, but copy everything\&. +.PP +@ +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_creds (krb5_context context, const krb5_ccache from, krb5_ccache to)" +MIT compat glue +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_copy_match_f (krb5_context context, const krb5_ccache from, krb5_ccache to, krb5_boolean(*)(krb5_context, void *, const krb5_creds *) match, void * matchctx, unsigned int * matched)" +Copy the contents of `from' to `to' if the given match function return true\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIfrom\fP the cache to copy data from\&. +.br +\fIto\fP the cache to copy data to\&. +.br +\fImatch\fP a match function that should return TRUE if cred argument should be copied, if NULL, all credentials are copied\&. +.br +\fImatchctx\fP context passed to match function\&. +.br +\fImatched\fP set to true if there was a credential that matched, may be NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_default (krb5_context context, krb5_ccache * id)" +Open the default ccache in `id'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_default_name (krb5_context context)" +Return a pointer to a context static string containing the default ccache name\&. +.PP +\fBReturns\fP +.RS 4 +String to the default credential cache name\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_destroy (krb5_context context, krb5_ccache id)" +Remove the ccache `id'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_end_seq_get (krb5_context context, const krb5_ccache id, krb5_cc_cursor * cursor)" +Destroy the cursor `cursor'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_gen_new (krb5_context context, const krb5_cc_ops * ops, krb5_ccache * id)" +Generate a new ccache of type `ops' in `id'\&. +.PP +Deprecated: use \fBkrb5_cc_new_unique()\fP instead\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_config (krb5_context context, krb5_ccache id, krb5_const_principal principal, const char * name, krb5_data * data)" +Get some configuration for the credential cache in the cache\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIid\fP the credential cache to store the data for +.br +\fIprincipal\fP configuration for a specific principal, if NULL, global for the whole cache\&. +.br +\fIname\fP name under which the configuraion is stored\&. +.br +\fIdata\fP data to fetched, free with \fBkrb5_data_free()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_flags (krb5_context context, krb5_ccache id, krb5_flags * flags)" +Get the flags of `id', store them in `flags'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_friendly_name (krb5_context context, krb5_ccache id, char ** name)" +Return a friendly name on credential cache\&. Free the result with krb5_xfree()\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_full_name (krb5_context context, krb5_ccache id, char ** str)" +Return the complete resolvable name the cache +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIid\fP return pointer to a found credential cache +.br +\fIstr\fP the returned name of a credential cache, free with krb5_xfree() +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 or an error (and then *str is set to NULL)\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_kdc_offset (krb5_context context, krb5_ccache id, krb5_deltat * offset)" +Get the time offset betwen the client and the KDC +.PP +If the backend doesn't support KDC offset, use the context global setting\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIid\fP a credential cache +.br +\fIoffset\fP the offset in seconds +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_lifetime (krb5_context context, krb5_ccache id, time_t * t)" +Get the lifetime of the initial ticket in the cache +.PP +Get the lifetime of the initial ticket in the cache, if the initial ticket was not found, the error code KRB5_CC_END is returned\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIid\fP a credential cache +.br +\fIt\fP the relative lifetime of the initial ticket +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP +If we find the start krbtgt in the cache, use that as the lifespan\&. +.PP +If there was no krbtgt, use the shortest lifetime of service tickets that have yet to expire\&. If all credentials are expired, \fBkrb5_cc_get_lifetime()\fP will fail\&. +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_get_name (krb5_context context, krb5_ccache id)" +Return the name of the ccache `id' +.SS "KRB5_LIB_FUNCTION const krb5_cc_ops* KRB5_LIB_CALL krb5_cc_get_ops (krb5_context context, krb5_ccache id)" +Return krb5_cc_ops of a the ccache `id'\&. +.SS "KRB5_LIB_FUNCTION const krb5_cc_ops* KRB5_LIB_CALL krb5_cc_get_prefix_ops (krb5_context context, const char * prefix)" +Get the cc ops that is registered in `context' to handle the prefix\&. prefix can be a complete credential cache name or a prefix, the function will only use part up to the first colon (:) if there is one\&. If prefix the argument is NULL, the default ccache implemtation is returned\&. +.PP +\fBReturns\fP +.RS 4 +Returns NULL if ops not found\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_principal (krb5_context context, krb5_ccache id, krb5_principal * principal)" +Return the principal of `id' in `principal'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_cc_get_type (krb5_context context, krb5_ccache id)" +Return the type of the ccache `id'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_get_version (krb5_context context, const krb5_ccache id)" +Return the version of `id'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_initialize (krb5_context context, krb5_ccache id, krb5_principal primary_principal)" +Create a new ccache in `id' for `primary_principal'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_last_change_time (krb5_context context, krb5_ccache id, krb5_timestamp * mtime)" +Return the last time the credential cache was modified\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIid\fP The credential cache to probe +.br +\fImtime\fP the last modification time, set to 0 on error\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or and error\&. See \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_move (krb5_context context, krb5_ccache from, krb5_ccache to)" +Move the content from one credential cache to another\&. The operation is an atomic switch\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIfrom\fP the credential cache to move the content from +.br +\fIto\fP the credential cache to move the content to +.RE +.PP +\fBReturns\fP +.RS 4 +On sucess, from is freed\&. On failure, error code is returned and from and to are both still allocated, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_new_unique (krb5_context context, const char * type, const char * hint, krb5_ccache * id)" +Generates a new unique ccache of \fCtype\fP in `id'\&. If `type' is NULL, the library chooses the default credential cache type\&. The supplied `hint' (that can be NULL) is a string that the credential cache type can use to base the name of the credential on, this is to make it easier for the user to differentiate the credentials\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_next_cred (krb5_context context, const krb5_ccache id, krb5_cc_cursor * cursor, krb5_creds * creds)" +Retrieve the next cred pointed to by (`id', `cursor') in `creds' and advance `cursor'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_register (krb5_context context, const krb5_cc_ops * ops, krb5_boolean override)" +Add a new ccache type with operations `ops', overwriting any existing one if `override'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIops\fP type of plugin symbol +.br +\fIoverride\fP flag to select if the registration is to overide an existing ops with the same name\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_remove_cred (krb5_context context, krb5_ccache id, krb5_flags which, krb5_creds * cred)" +Remove the credential identified by `cred', `which' from `id'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_resolve (krb5_context context, const char * name, krb5_ccache * id)" +Find and allocate a ccache in `id' from the specification in `residual'\&. If the ccache name doesn't contain any colon, interpret it as a file name\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIname\fP string name of a credential cache\&. +.br +\fIid\fP return pointer to a found credential cache\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or an error code\&. In case of an error, id is set to NULL, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_retrieve_cred (krb5_context context, krb5_ccache id, krb5_flags whichfields, const krb5_creds * mcreds, krb5_creds * creds)" +Retrieve the credential identified by `mcreds' (and `whichfields') from `id' in `creds'\&. 'creds' must be free by the caller using krb5_free_cred_contents\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIid\fP a Kerberos 5 credential cache +.br +\fIwhichfields\fP what fields to use for matching credentials, same flags as whichfields in \fBkrb5_compare_creds()\fP +.br +\fImcreds\fP template credential to use for comparing +.br +\fIcreds\fP returned credential, free with \fBkrb5_free_cred_contents()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_config (krb5_context context, krb5_ccache id, krb5_const_principal principal, const char * name, krb5_data * data)" +Store some configuration for the credential cache in the cache\&. Existing configuration under the same name is over-written\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIid\fP the credential cache to store the data for +.br +\fIprincipal\fP configuration for a specific principal, if NULL, global for the whole cache\&. +.br +\fIname\fP name under which the configuraion is stored\&. +.br +\fIdata\fP data to store, if NULL, configure is removed\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_default_name (krb5_context context, const char * name)" +Set the default cc name for `context' to `name'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_flags (krb5_context context, krb5_ccache id, krb5_flags flags)" +Set the flags of `id' to `flags'\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_friendly_name (krb5_context context, krb5_ccache id, const char * name)" +Set the friendly name on credential cache\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_set_kdc_offset (krb5_context context, krb5_ccache id, krb5_deltat offset)" +Set the time offset betwen the client and the KDC +.PP +If the backend doesn't support KDC offset, use the context global setting\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIid\fP a credential cache +.br +\fIoffset\fP the offset in seconds +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_start_seq_get (krb5_context context, const krb5_ccache id, krb5_cc_cursor * cursor)" +Start iterating over `id', `cursor' is initialized to the beginning\&. Caller must free the cursor with \fBkrb5_cc_end_seq_get()\fP\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_store_cred (krb5_context context, krb5_ccache id, krb5_creds * creds)" +Store `creds' in the ccache `id'\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_cc_support_switch (krb5_context context, const char * type)" +Return true if the default credential cache support switch +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cc_switch (krb5_context context, krb5_ccache id)" +Switch the default default credential cache for a specific credcache type (and name for some implementations)\&. +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_free (krb5_context context, krb5_cccol_cursor * cursor)" +End an iteration and free all resources, can be done before end is reached\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIcursor\fP the iteration cursor to be freed\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or and error, KRB5_CC_END is returned at the end of iteration\&. See \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_new (krb5_context context, krb5_cccol_cursor * cursor)" +Get a new cache interation cursor that will interate over all credentials caches independent of type\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIcursor\fP passed into \fBkrb5_cccol_cursor_next()\fP and free with \fBkrb5_cccol_cursor_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 or and error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_cursor_next (krb5_context context, krb5_cccol_cursor cursor, krb5_ccache * cache)" +Get next credential cache from the iteration\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIcursor\fP the iteration cursor +.br +\fIcache\fP the returned cursor, pointer is set to NULL on failure and a cache on success\&. The returned cache needs to be freed with \fBkrb5_cc_close()\fP or destroyed with \fBkrb5_cc_destroy()\fP\&. MIT Kerberos behavies slightly diffrent and sets cache to NULL when all caches are iterated over and return 0\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or and error, KRB5_CC_END is returned at the end of iteration\&. See \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cccol_last_change_time (krb5_context context, const char * type, krb5_timestamp * mtime)" +Return the last modfication time for a cache collection\&. The query can be limited to a specific cache type\&. If the function return 0 and mtime is 0, there was no credentials in the caches\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fItype\fP The credential cache to probe, if NULL, all type are traversed\&. +.br +\fImtime\fP the last modification time, set to 0 on error\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return 0 or and error\&. See \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_validated_creds (krb5_context context, krb5_creds * creds, krb5_principal client, krb5_ccache ccache, char * service)" +Validate the newly fetch credential, see also krb5_verify_init_creds()\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIcreds\fP the credentials to verify +.br +\fIclient\fP the client name to match up +.br +\fIccache\fP the credential cache to use +.br +\fIservice\fP a service name to use, used with \fBkrb5_sname_to_principal()\fP to build a hostname to use to verify\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_is_config_principal (krb5_context context, krb5_const_principal principal)" +Return TRUE (non zero) if the principal is a configuration principal (generated part of \fBkrb5_cc_set_config()\fP)\&. Returns FALSE (zero) if not a configuration principal\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIprincipal\fP principal to check if it a configuration principal +.RE +.PP + +.SH "Variable Documentation" +.PP +.SS "KRB5_LIB_VARIABLE const krb5_cc_ops krb5_acc_ops" +\fBInitial value:\fP +.PP +.nf += { + KRB5_CC_OPS_VERSION, + "API", + acc_get_name, + acc_resolve, + acc_gen_new, + acc_initialize, + acc_destroy, + acc_close, + acc_store_cred, + NULL, + acc_get_principal, + acc_get_first, + acc_get_next, + acc_end_get, + acc_remove_cred, + acc_set_flags, + acc_get_version, + acc_get_cache_first, + acc_get_cache_next, + acc_end_cache_get, + acc_move, + acc_get_default_name, + acc_set_default, + acc_lastchange, + NULL, + NULL, +} +.fi +Variable containing the API based credential cache implemention\&. +.SS "KRB5_LIB_VARIABLE const krb5_cc_ops krb5_dcc_ops" +\fBInitial value:\fP +.PP +.nf += { + KRB5_CC_OPS_VERSION, + "DIR", + dcc_get_name, + dcc_resolve, + dcc_gen_new, + dcc_initialize, + dcc_destroy, + dcc_close, + dcc_store_cred, + NULL, + dcc_get_principal, + dcc_get_first, + dcc_get_next, + dcc_end_get, + dcc_remove_cred, + dcc_set_flags, + dcc_get_version, + dcc_get_cache_first, + dcc_get_cache_next, + dcc_end_cache_get, + dcc_move, + dcc_get_default_name, + dcc_set_default, + dcc_lastchange, + dcc_set_kdc_offset, + dcc_get_kdc_offset +} +.fi +Variable containing the DIR based credential cache implemention\&. +.SS "KRB5_LIB_VARIABLE const krb5_cc_ops krb5_fcc_ops" +\fBInitial value:\fP +.PP +.nf += { + KRB5_CC_OPS_VERSION, + "FILE", + fcc_get_name, + fcc_resolve, + fcc_gen_new, + fcc_initialize, + fcc_destroy, + fcc_close, + fcc_store_cred, + NULL, + fcc_get_principal, + fcc_get_first, + fcc_get_next, + fcc_end_get, + fcc_remove_cred, + fcc_set_flags, + fcc_get_version, + fcc_get_cache_first, + fcc_get_cache_next, + fcc_end_cache_get, + fcc_move, + fcc_get_default_name, + NULL, + fcc_lastchange, + fcc_set_kdc_offset, + fcc_get_kdc_offset +} +.fi +Variable containing the FILE based credential cache implemention\&. +.SS "KRB5_LIB_VARIABLE const krb5_cc_ops krb5_mcc_ops" +\fBInitial value:\fP +.PP +.nf += { + KRB5_CC_OPS_VERSION, + "MEMORY", + mcc_get_name, + mcc_resolve, + mcc_gen_new, + mcc_initialize, + mcc_destroy, + mcc_close, + mcc_store_cred, + NULL, + mcc_get_principal, + mcc_get_first, + mcc_get_next, + mcc_end_get, + mcc_remove_cred, + mcc_set_flags, + NULL, + mcc_get_cache_first, + mcc_get_cache_next, + mcc_end_cache_get, + mcc_move, + mcc_default_name, + NULL, + mcc_lastchange, + mcc_set_kdc_offset, + mcc_get_kdc_offset +} +.fi +Variable containing the MEMORY based credential cache implemention\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_ccache_intro.3 b/static/netbsd/man3/krb5_ccache_intro.3 new file mode 100644 index 00000000..ecc090dd --- /dev/null +++ b/static/netbsd/man3/krb5_ccache_intro.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: krb5_ccache_intro.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_ccache_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_ccache_intro \- The credential cache functions + +.SH "Kerberos credential caches" +.PP +krb5_ccache structure holds a Kerberos credential cache\&. +.PP +Heimdal support the follow types of credential caches: +.PP +.IP "\(bu" 2 +SCC Store the credential in a database +.IP "\(bu" 2 +FILE Store the credential in memory +.IP "\(bu" 2 +MEMORY Store the credential in memory +.IP "\(bu" 2 +API A credential cache server based solution for Mac OS X +.IP "\(bu" 2 +KCM A credential cache server based solution for all platforms +.PP +.SS "Example" +This is a minimalistic version of klist: +.PP +.nf +#include + +int +main (int argc, char **argv) +{ + krb5_context context; + krb5_cc_cursor cursor; + krb5_error_code ret; + krb5_ccache id; + krb5_creds creds; + + if (krb5_init_context (&context) != 0) + errx(1, "krb5_context"); + + ret = krb5_cc_default (context, &id); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_default"); + + ret = krb5_cc_start_seq_get(context, id, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_start_seq_get"); + + while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){ + char *principal; + + krb5_unparse_name(context, creds\&.server, &principal); + printf("principal: %s\\n", principal); + free(principal); + krb5_free_cred_contents (context, &creds); + } + ret = krb5_cc_end_seq_get(context, id, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_end_seq_get"); + + krb5_cc_close(context, id); + + krb5_free_context(context); + return 0; +} + +.fi +.PP + diff --git a/static/netbsd/man3/krb5_cccol_cursor_free.3 b/static/netbsd/man3/krb5_cccol_cursor_free.3 new file mode 100644 index 00000000..206392f4 --- /dev/null +++ b/static/netbsd/man3/krb5_cccol_cursor_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cccol_cursor_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cccol_cursor_new.3 b/static/netbsd/man3/krb5_cccol_cursor_new.3 new file mode 100644 index 00000000..b9239141 --- /dev/null +++ b/static/netbsd/man3/krb5_cccol_cursor_new.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cccol_cursor_new.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cccol_cursor_next.3 b/static/netbsd/man3/krb5_cccol_cursor_next.3 new file mode 100644 index 00000000..f3d36c14 --- /dev/null +++ b/static/netbsd/man3/krb5_cccol_cursor_next.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cccol_cursor_next.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_cccol_last_change_time.3 b/static/netbsd/man3/krb5_cccol_last_change_time.3 new file mode 100644 index 00000000..f7eff077 --- /dev/null +++ b/static/netbsd/man3/krb5_cccol_last_change_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cccol_last_change_time.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_change_password.3 b/static/netbsd/man3/krb5_change_password.3 new file mode 100644 index 00000000..41f14872 --- /dev/null +++ b/static/netbsd/man3/krb5_change_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_change_password.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_check_transited.3 b/static/netbsd/man3/krb5_check_transited.3 new file mode 100644 index 00000000..e029b722 --- /dev/null +++ b/static/netbsd/man3/krb5_check_transited.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: krb5_check_transited.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004, 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_CHECK_TRANSITED 3 +.Os +.Sh NAME +.Nm krb5_check_transited , +.Nm krb5_check_transited_realms , +.Nm krb5_domain_x500_decode , +.Nm krb5_domain_x500_encode +.Nd realm transit verification and encoding/decoding functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_check_transited +.Fa "krb5_context context" +.Fa "krb5_const_realm client_realm" +.Fa "krb5_const_realm server_realm" +.Fa "krb5_realm *realms" +.Fa "int num_realms" +.Fa "int *bad_realm" +.Fc +.Ft krb5_error_code +.Fo krb5_check_transited_realms +.Fa "krb5_context context" +.Fa "const char *const *realms" +.Fa "int num_realms" +.Fa "int *bad_realm" +.Fc +.Ft krb5_error_code +.Fo krb5_domain_x500_decode +.Fa "krb5_context context" +.Fa "krb5_data tr" +.Fa "char ***realms" +.Fa "int *num_realms" +.Fa "const char *client_realm" +.Fa "const char *server_realm" +.Fc +.Ft krb5_error_code +.Fo krb5_domain_x500_encode +.Fa "char **realms" +.Fa "int num_realms" +.Fa "krb5_data *encoding" +.Fc +.Sh DESCRIPTION +.Fn krb5_check_transited +checks the path from +.Fa client_realm +to +.Fa server_realm +where +.Fa realms +and +.Fa num_realms +is the realms between them. +If the function returns an error value, +.Fa bad_realm +will be set to the realm in the list causing the error. +.Fn krb5_check_transited +is used internally by the KDC and libkrb5 and should not be called by +client applications. +.Pp +.Fn krb5_check_transited_realms +is deprecated. +.Pp +.Fn krb5_domain_x500_encode +and +.Fn krb5_domain_x500_decode +encodes and decodes the realm names in the X500 format that Kerberos +uses to describe the transited realms in krbtgts. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_cksumtype_to_enctype.3 b/static/netbsd/man3/krb5_cksumtype_to_enctype.3 new file mode 100644 index 00000000..50ad1875 --- /dev/null +++ b/static/netbsd/man3/krb5_cksumtype_to_enctype.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_cksumtype_to_enctype.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_clear_error_message.3 b/static/netbsd/man3/krb5_clear_error_message.3 new file mode 100644 index 00000000..c52cb227 --- /dev/null +++ b/static/netbsd/man3/krb5_clear_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_clear_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_clear_error_string.3 b/static/netbsd/man3/krb5_clear_error_string.3 new file mode 100644 index 00000000..a7e2253d --- /dev/null +++ b/static/netbsd/man3/krb5_clear_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_clear_error_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_compare_creds.3 b/static/netbsd/man3/krb5_compare_creds.3 new file mode 100644 index 00000000..c950f2c2 --- /dev/null +++ b/static/netbsd/man3/krb5_compare_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_compare_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_config_file_free.3 b/static/netbsd/man3/krb5_config_file_free.3 new file mode 100644 index 00000000..991e6a42 --- /dev/null +++ b/static/netbsd/man3/krb5_config_file_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_file_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_free_strings.3 b/static/netbsd/man3/krb5_config_free_strings.3 new file mode 100644 index 00000000..db776088 --- /dev/null +++ b/static/netbsd/man3/krb5_config_free_strings.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_free_strings.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_bool.3 b/static/netbsd/man3/krb5_config_get_bool.3 new file mode 100644 index 00000000..ca860b16 --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_bool.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_bool.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_bool_default.3 b/static/netbsd/man3/krb5_config_get_bool_default.3 new file mode 100644 index 00000000..8378fd95 --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_bool_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_bool_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_list.3 b/static/netbsd/man3/krb5_config_get_list.3 new file mode 100644 index 00000000..8d7e0758 --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_list.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_list.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_string.3 b/static/netbsd/man3/krb5_config_get_string.3 new file mode 100644 index 00000000..99c9e7dd --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_string_default.3 b/static/netbsd/man3/krb5_config_get_string_default.3 new file mode 100644 index 00000000..09e072f8 --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_string_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_string_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_strings.3 b/static/netbsd/man3/krb5_config_get_strings.3 new file mode 100644 index 00000000..0534e77d --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_strings.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_strings.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_time.3 b/static/netbsd/man3/krb5_config_get_time.3 new file mode 100644 index 00000000..44e34dbf --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_time.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_get_time_default.3 b/static/netbsd/man3/krb5_config_get_time_default.3 new file mode 100644 index 00000000..5abda805 --- /dev/null +++ b/static/netbsd/man3/krb5_config_get_time_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_get_time_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_parse_file_multi.3 b/static/netbsd/man3/krb5_config_parse_file_multi.3 new file mode 100644 index 00000000..ff08c3b4 --- /dev/null +++ b/static/netbsd/man3/krb5_config_parse_file_multi.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_parse_file_multi.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_parse_string_multi.3 b/static/netbsd/man3/krb5_config_parse_string_multi.3 new file mode 100644 index 00000000..4e101d51 --- /dev/null +++ b/static/netbsd/man3/krb5_config_parse_string_multi.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_parse_string_multi.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_config_vget_bool.3 b/static/netbsd/man3/krb5_config_vget_bool.3 new file mode 100644 index 00000000..149faffd --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_bool.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_bool.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_bool_default.3 b/static/netbsd/man3/krb5_config_vget_bool_default.3 new file mode 100644 index 00000000..81fb5cc2 --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_bool_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_bool_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_list.3 b/static/netbsd/man3/krb5_config_vget_list.3 new file mode 100644 index 00000000..7e3abf8c --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_list.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_list.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_string.3 b/static/netbsd/man3/krb5_config_vget_string.3 new file mode 100644 index 00000000..d994fc4c --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_string_default.3 b/static/netbsd/man3/krb5_config_vget_string_default.3 new file mode 100644 index 00000000..44493b9c --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_string_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_string_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_strings.3 b/static/netbsd/man3/krb5_config_vget_strings.3 new file mode 100644 index 00000000..d77c4749 --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_strings.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_strings.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_time.3 b/static/netbsd/man3/krb5_config_vget_time.3 new file mode 100644 index 00000000..642f3ad2 --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_time.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_config_vget_time_default.3 b/static/netbsd/man3/krb5_config_vget_time_default.3 new file mode 100644 index 00000000..96f11726 --- /dev/null +++ b/static/netbsd/man3/krb5_config_vget_time_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_config_vget_time_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_copy_address.3 b/static/netbsd/man3/krb5_copy_address.3 new file mode 100644 index 00000000..46e2a2f2 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_copy_addresses.3 b/static/netbsd/man3/krb5_copy_addresses.3 new file mode 100644 index 00000000..c0bbf215 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_copy_context.3 b/static/netbsd/man3/krb5_copy_context.3 new file mode 100644 index 00000000..33362297 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_context.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_context.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_copy_creds.3 b/static/netbsd/man3/krb5_copy_creds.3 new file mode 100644 index 00000000..051e026a --- /dev/null +++ b/static/netbsd/man3/krb5_copy_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_copy_creds_contents.3 b/static/netbsd/man3/krb5_copy_creds_contents.3 new file mode 100644 index 00000000..929d661c --- /dev/null +++ b/static/netbsd/man3/krb5_copy_creds_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_creds_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_copy_data.3 b/static/netbsd/man3/krb5_copy_data.3 new file mode 100644 index 00000000..87b4307a --- /dev/null +++ b/static/netbsd/man3/krb5_copy_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_copy_host_realm.3 b/static/netbsd/man3/krb5_copy_host_realm.3 new file mode 100644 index 00000000..e64a845f --- /dev/null +++ b/static/netbsd/man3/krb5_copy_host_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_host_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_copy_keyblock.3 b/static/netbsd/man3/krb5_copy_keyblock.3 new file mode 100644 index 00000000..9cdba4d0 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_keyblock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_keyblock.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_copy_keyblock_contents.3 b/static/netbsd/man3/krb5_copy_keyblock_contents.3 new file mode 100644 index 00000000..cef3fc39 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_keyblock_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_keyblock_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_copy_principal.3 b/static/netbsd/man3/krb5_copy_principal.3 new file mode 100644 index 00000000..cf3fc447 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_copy_ticket.3 b/static/netbsd/man3/krb5_copy_ticket.3 new file mode 100644 index 00000000..fb6feb35 --- /dev/null +++ b/static/netbsd/man3/krb5_copy_ticket.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_copy_ticket.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_create_checksum.3 b/static/netbsd/man3/krb5_create_checksum.3 new file mode 100644 index 00000000..6bf9a3aa --- /dev/null +++ b/static/netbsd/man3/krb5_create_checksum.3 @@ -0,0 +1,228 @@ +.\" $NetBSD: krb5_create_checksum.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 1999-2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd August 12, 2005 +.Dt NAME 3 +.Os +.Sh NAME +.Nm krb5_checksum , +.Nm krb5_checksum_disable , +.Nm krb5_checksum_is_collision_proof , +.Nm krb5_checksum_is_keyed , +.Nm krb5_checksumsize , +.Nm krb5_cksumtype_valid , +.Nm krb5_copy_checksum , +.Nm krb5_create_checksum , +.Nm krb5_crypto_get_checksum_type +.Nm krb5_free_checksum , +.Nm krb5_free_checksum_contents , +.Nm krb5_hmac , +.Nm krb5_verify_checksum +.Nd creates, handles and verifies checksums +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Li "typedef Checksum krb5_checksum;" +.Ft void +.Fo krb5_checksum_disable +.Fa "krb5_context context" +.Fa "krb5_cksumtype type" +.Fc +.Ft krb5_boolean +.Fo krb5_checksum_is_collision_proof +.Fa "krb5_context context" +.Fa "krb5_cksumtype type" +.Fc +.Ft krb5_boolean +.Fo krb5_checksum_is_keyed +.Fa "krb5_context context" +.Fa "krb5_cksumtype type" +.Fc +.Ft krb5_error_code +.Fo krb5_cksumtype_valid +.Fa "krb5_context context" +.Fa "krb5_cksumtype ctype" +.Fc +.Ft krb5_error_code +.Fo krb5_checksumsize +.Fa "krb5_context context" +.Fa "krb5_cksumtype type" +.Fa "size_t *size" +.Fc +.Ft krb5_error_code +.Fo krb5_create_checksum +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "krb5_key_usage usage" +.Fa "int type" +.Fa "void *data" +.Fa "size_t len" +.Fa "Checksum *result" +.Fc +.Ft krb5_error_code +.Fo krb5_verify_checksum +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "krb5_key_usage usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "Checksum *cksum" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_get_checksum_type +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "krb5_cksumtype *type" +.Fc +.Ft void +.Fo krb5_free_checksum +.Fa "krb5_context context" +.Fa "krb5_checksum *cksum" +.Fc +.Ft void +.Fo krb5_free_checksum_contents +.Fa "krb5_context context" +.Fa "krb5_checksum *cksum" +.Fc +.Ft krb5_error_code +.Fo krb5_hmac +.Fa "krb5_context context" +.Fa "krb5_cksumtype cktype" +.Fa "const void *data" +.Fa "size_t len" +.Fa "unsigned usage" +.Fa "krb5_keyblock *key" +.Fa "Checksum *result" +.Fc +.Ft krb5_error_code +.Fo krb5_copy_checksum +.Fa "krb5_context context" +.Fa "const krb5_checksum *old" +.Fa "krb5_checksum **new" +.Fc +.Sh DESCRIPTION +The +.Li krb5_checksum +structure holds a Kerberos checksum. +There is no component inside +.Li krb5_checksum +that is directly referable. +.Pp +The functions are used to create and verify checksums. +.Fn krb5_create_checksum +creates a checksum of the specified data, and puts it in +.Fa result . +If +.Fa crypto +is +.Dv NULL , +.Fa usage_or_type +specifies the checksum type to use; it must not be keyed. Otherwise +.Fa crypto +is an encryption context created by +.Fn krb5_crypto_init , +and +.Fa usage_or_type +specifies a key-usage. +.Pp +.Fn krb5_verify_checksum +verifies the +.Fa checksum +against the provided data. +.Pp +.Fn krb5_checksum_is_collision_proof +returns true is the specified checksum is collision proof (that it's +very unlikely that two strings has the same hash value, and that it's +hard to find two strings that has the same hash). Examples of +collision proof checksums are MD5, and SHA1, while CRC32 is not. +.Pp +.Fn krb5_checksum_is_keyed +returns true if the specified checksum type is keyed (that the hash +value is a function of both the data, and a separate key). Examples of +keyed hash algorithms are HMAC-SHA1-DES3, and RSA-MD5-DES. The +.Dq plain +hash functions MD5, and SHA1 are not keyed. +.Pp +.Fn krb5_crypto_get_checksum_type +returns the checksum type that will be used when creating a checksum for the given +.Fa crypto +context. +This function is useful in combination with +.Fn krb5_checksumsize +when you want to know the size a checksum will +use when you create it. +.Pp +.Fn krb5_cksumtype_valid +returns 0 or an error if the checksumtype is implemented and not +currently disabled in this kerberos library. +.Pp +.Fn krb5_checksumsize +returns the size of the outdata of checksum function. +.Pp +.Fn krb5_copy_checksum +returns a copy of the checksum +.Fn krb5_free_checksum +should use used to free the +.Fa new +checksum. +.Pp +.Fn krb5_free_checksum +free the checksum and the content of the checksum. +.Pp +.Fn krb5_free_checksum_contents +frees the content of checksum in +.Fa cksum . +.Pp +.Fn krb5_hmac +calculates the HMAC over +.Fa data +(with length +.Fa len ) +using the keyusage +.Fa usage +and keyblock +.Fa key . +Note that keyusage is not always used in checksums. +.Pp +.Nm krb5_checksum_disable +globally disables the checksum type. +.\" .Sh EXAMPLE +.\" .Sh BUGS +.Sh SEE ALSO +.Xr krb5_crypto_init 3 , +.Xr krb5_c_encrypt 3 , +.Xr krb5_encrypt 3 diff --git a/static/netbsd/man3/krb5_create_checksum_iov.3 b/static/netbsd/man3/krb5_create_checksum_iov.3 new file mode 100644 index 00000000..8ff1db89 --- /dev/null +++ b/static/netbsd/man3/krb5_create_checksum_iov.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_create_checksum_iov.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_credential.3 b/static/netbsd/man3/krb5_credential.3 new file mode 100644 index 00000000..097bf162 --- /dev/null +++ b/static/netbsd/man3/krb5_credential.3 @@ -0,0 +1,270 @@ +.\" $NetBSD: krb5_credential.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_credential" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_credential \- Heimdal Kerberos 5 credential handing functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_fwd_tgt_creds\fP (krb5_context context, krb5_auth_context auth_context, const char *hostname, krb5_principal client, krb5_principal server, krb5_ccache ccache, int forwardable, krb5_data *out_data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_forwarded_creds\fP (krb5_context context, krb5_auth_context auth_context, krb5_ccache ccache, krb5_flags flags, const char *hostname, krb5_creds *in_creds, krb5_data *out_data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_init_creds_opt_alloc\fP (krb5_context context, krb5_get_init_creds_opt **opt)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_get_init_creds_opt_free\fP (krb5_context context, krb5_get_init_creds_opt *opt)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_init\fP (krb5_context context, krb5_principal client, krb5_prompter_fct prompter, void *prompter_data, krb5_deltat start_time, krb5_get_init_creds_opt *options, krb5_init_creds_context *rctx)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_set_service\fP (krb5_context context, krb5_init_creds_context ctx, const char *service)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_set_password\fP (krb5_context context, krb5_init_creds_context ctx, const char *password)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_set_keytab\fP (krb5_context context, krb5_init_creds_context ctx, krb5_keytab keytab)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_step\fP (krb5_context context, krb5_init_creds_context ctx, krb5_data *in, krb5_data *out, krb5_krbhst_info *hostinfo, unsigned int *flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_get_error\fP (krb5_context context, krb5_init_creds_context ctx, KRB_ERROR *error)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_init_creds_free\fP (krb5_context context, krb5_init_creds_context ctx)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_init_creds_get\fP (krb5_context context, krb5_init_creds_context ctx)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_init_creds_password\fP (krb5_context context, krb5_creds *creds, krb5_principal client, const char *password, krb5_prompter_fct prompter, void *data, krb5_deltat start_time, const char *in_tkt_service, krb5_get_init_creds_opt *options)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_init_creds_keyblock\fP (krb5_context context, krb5_creds *creds, krb5_principal client, krb5_keyblock *keyblock, krb5_deltat start_time, const char *in_tkt_service, krb5_get_init_creds_opt *options)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_init_creds_keytab\fP (krb5_context context, krb5_creds *creds, krb5_principal client, krb5_keytab keytab, krb5_deltat start_time, const char *in_tkt_service, krb5_get_init_creds_opt *options)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_fwd_tgt_creds (krb5_context context, krb5_auth_context auth_context, const char * hostname, krb5_principal client, krb5_principal server, krb5_ccache ccache, int forwardable, krb5_data * out_data)" +Forward credentials for client to host hostname , making them forwardable if forwardable, and returning the blob of data to sent in out_data\&. If hostname == NULL, pick it from server\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A kerberos 5 context\&. +.br +\fIauth_context\fP the auth context with the key to encrypt the out_data\&. +.br +\fIhostname\fP the host to forward the tickets too\&. +.br +\fIclient\fP the client to delegate from\&. +.br +\fIserver\fP the server to delegate the credential too\&. +.br +\fIccache\fP credential cache to use\&. +.br +\fIforwardable\fP make the forwarded ticket forwabledable\&. +.br +\fIout_data\fP the resulting credential\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_forwarded_creds (krb5_context context, krb5_auth_context auth_context, krb5_ccache ccache, krb5_flags flags, const char * hostname, krb5_creds * in_creds, krb5_data * out_data)" +Gets tickets forwarded to hostname\&. If the tickets that are forwarded are address-less, the forwarded tickets will also be address-less\&. +.PP +If the ticket have any address, hostname will be used for figure out the address to forward the ticket too\&. This since this might use DNS, its insecure and also doesn't represent configured all addresses of the host\&. For example, the host might have two adresses, one IPv4 and one IPv6 address where the later is not published in DNS\&. This IPv6 address might be used communications and thus the resulting ticket useless\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A kerberos 5 context\&. +.br +\fIauth_context\fP the auth context with the key to encrypt the out_data\&. +.br +\fIccache\fP credential cache to use +.br +\fIflags\fP the flags to control the resulting ticket flags +.br +\fIhostname\fP the host to forward the tickets too\&. +.br +\fIin_creds\fP the in client and server ticket names\&. The client and server components forwarded to the remote host\&. +.br +\fIout_data\fP the resulting credential\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP +Some older of the MIT gssapi library used clear-text tickets (warped inside AP-REQ encryption), use the krb5_auth_context flag KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED to support those tickets\&. The session key is used otherwise to encrypt the forwarded ticket\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keyblock (krb5_context context, krb5_creds * creds, krb5_principal client, krb5_keyblock * keyblock, krb5_deltat start_time, const char * in_tkt_service, krb5_get_init_creds_opt * options)" +Get new credentials using keyblock\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keytab (krb5_context context, krb5_creds * creds, krb5_principal client, krb5_keytab keytab, krb5_deltat start_time, const char * in_tkt_service, krb5_get_init_creds_opt * options)" +Get new credentials using keytab\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_opt_alloc (krb5_context context, krb5_get_init_creds_opt ** opt)" +Allocate a new krb5_get_init_creds_opt structure, free with \fBkrb5_get_init_creds_opt_free()\fP\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_free (krb5_context context, krb5_get_init_creds_opt * opt)" +Free krb5_get_init_creds_opt structure\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_password (krb5_context context, krb5_creds * creds, krb5_principal client, const char * password, krb5_prompter_fct prompter, void * data, krb5_deltat start_time, const char * in_tkt_service, krb5_get_init_creds_opt * options)" +Get new credentials using password\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_creds_free (krb5_context context, krb5_init_creds_context ctx)" +Free the krb5_init_creds_context allocated by \fBkrb5_init_creds_init()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIctx\fP The krb5_init_creds_context to free\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get (krb5_context context, krb5_init_creds_context ctx)" +Get new credentials as setup by the krb5_init_creds_context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIctx\fP The krb5_init_creds_context to process\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get_error (krb5_context context, krb5_init_creds_context ctx, KRB_ERROR * error)" +Get the last error from the transaction\&. +.PP +\fBReturns\fP +.RS 4 +Returns 0 or an error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_init (krb5_context context, krb5_principal client, krb5_prompter_fct prompter, void * prompter_data, krb5_deltat start_time, krb5_get_init_creds_opt * options, krb5_init_creds_context * rctx)" +Start a new context to get a new initial credential\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIclient\fP The Kerberos principal to get the credential for, if NULL is given, the default principal is used as determined by krb5_get_default_principal()\&. +.br +\fIprompter\fP +.br +\fIprompter_data\fP +.br +\fIstart_time\fP the time the ticket should start to be valid or 0 for now\&. +.br +\fIoptions\fP a options structure, can be NULL for default options\&. +.br +\fIrctx\fP A new allocated free with \fBkrb5_init_creds_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success or an Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_keytab (krb5_context context, krb5_init_creds_context ctx, krb5_keytab keytab)" +Set the keytab to use for authentication\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIctx\fP ctx krb5_init_creds_context context\&. +.br +\fIkeytab\fP the keytab to read the key from\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or an Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_password (krb5_context context, krb5_init_creds_context ctx, const char * password)" +Sets the password that will use for the request\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIctx\fP ctx krb5_init_creds_context context\&. +.br +\fIpassword\fP the password to use\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or an Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_service (krb5_context context, krb5_init_creds_context ctx, const char * service)" +Sets the service that the is requested\&. This call is only neede for special initial tickets, by default the a krbtgt is fetched in the default realm\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIctx\fP a krb5_init_creds_context context\&. +.br +\fIservice\fP the service given as a string, for example 'kadmind/admin'\&. If NULL, the default krbtgt in the clients realm is set\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or an Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_step (krb5_context context, krb5_init_creds_context ctx, krb5_data * in, krb5_data * out, krb5_krbhst_info * hostinfo, unsigned int * flags)" +The core loop if krb5_get_init_creds() function family\&. Create the packets and have the caller send them off to the KDC\&. +.PP +If the caller want all work been done for them, use \fBkrb5_init_creds_get()\fP instead\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIctx\fP ctx krb5_init_creds_context context\&. +.br +\fIin\fP input data from KDC, first round it should be reset by krb5_data_zer()\&. +.br +\fIout\fP reply to KDC\&. +.br +\fIhostinfo\fP KDC address info, first round it can be NULL\&. +.br +\fIflags\fP status of the round, if KRB5_INIT_CREDS_STEP_FLAG_CONTINUE is set, continue one more round\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or an Kerberos 5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_creds.3 b/static/netbsd/man3/krb5_creds.3 new file mode 100644 index 00000000..688e2887 --- /dev/null +++ b/static/netbsd/man3/krb5_creds.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: krb5_creds.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004, 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_CREDS 3 +.Os +.Sh NAME +.Nm krb5_creds , +.Nm krb5_copy_creds , +.Nm krb5_copy_creds_contents , +.Nm krb5_free_creds , +.Nm krb5_free_cred_contents +.Nd Kerberos 5 credential handling functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_copy_creds +.Fa "krb5_context context" +.Fa "const krb5_creds *incred" +.Fa "krb5_creds **outcred" +.Fc +.Ft krb5_error_code +.Fo krb5_copy_creds_contents +.Fa "krb5_context context" +.Fa "const krb5_creds *incred" +.Fa "krb5_creds *outcred" +.Fc +.Ft krb5_error_code +.Fo krb5_free_creds +.Fa "krb5_context context" +.Fa "krb5_creds *outcred" +.Fc +.Ft krb5_error_code +.Fo krb5_free_cred_contents +.Fa "krb5_context context" +.Fa "krb5_creds *cred" +.Fc +.Sh DESCRIPTION +.Vt krb5_creds +holds Kerberos credentials: +.Bd -literal -offset +typedef struct krb5_creds { + krb5_principal client; + krb5_principal server; + krb5_keyblock session; + krb5_times times; + krb5_data ticket; + krb5_data second_ticket; + krb5_authdata authdata; + krb5_addresses addresses; + krb5_ticket_flags flags; +} krb5_creds; +.Ed +.Pp +.Fn krb5_copy_creds +makes a copy of +.Fa incred +to +.Fa outcred . +.Fa outcred +should be freed with +.Fn krb5_free_creds +by the caller. +.Pp +.Fn krb5_copy_creds_contents +makes a copy of the content of +.Fa incred +to +.Fa outcreds . +.Fa outcreds +should be freed by the called with +.Fn krb5_free_creds_contents . +.Pp +.Fn krb5_free_creds +frees the content of the +.Fa cred +structure and the structure itself. +.Pp +.Fn krb5_free_cred_contents +frees the content of the +.Fa cred +structure. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_compare_creds 3 , +.Xr krb5_get_init_creds 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_creds_get_ticket_flags.3 b/static/netbsd/man3/krb5_creds_get_ticket_flags.3 new file mode 100644 index 00000000..caecd108 --- /dev/null +++ b/static/netbsd/man3/krb5_creds_get_ticket_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_creds_get_ticket_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_crypto.3 b/static/netbsd/man3/krb5_crypto.3 new file mode 100644 index 00000000..a79086cb --- /dev/null +++ b/static/netbsd/man3/krb5_crypto.3 @@ -0,0 +1,651 @@ +.\" $NetBSD: krb5_crypto.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_crypto" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_crypto \- Heimdal Kerberos 5 cryptography functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "HEIMDAL_WARN_UNUSED_RESULT_ATTRIBUTE KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_generate_random\fP (void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_generate_random_block\fP (void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_enctype_valid\fP (krb5_context context, krb5_enctype etype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_cksumtype_to_enctype\fP (krb5_context context, krb5_cksumtype ctype, krb5_enctype *etype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_encrypt_iov_ivec\fP (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP *data, int num_data, void *ivec)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_decrypt_iov_ivec\fP (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP *data, unsigned int num_data, void *ivec)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_create_checksum_iov\fP (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP *data, unsigned int num_data, krb5_cksumtype *type)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_verify_checksum_iov\fP (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP *data, unsigned int num_data, krb5_cksumtype *type)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_init\fP (krb5_context context, const krb5_keyblock *key, krb5_enctype etype, krb5_crypto *crypto)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_destroy\fP (krb5_context context, krb5_crypto crypto)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_getblocksize\fP (krb5_context context, krb5_crypto crypto, size_t *blocksize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_getenctype\fP (krb5_context context, krb5_crypto crypto, krb5_enctype *enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_getpadsize\fP (krb5_context context, krb5_crypto crypto, size_t *padsize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_getconfoundersize\fP (krb5_context context, krb5_crypto crypto, size_t *confoundersize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_enctype_disable\fP (krb5_context context, krb5_enctype enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_enctype_enable\fP (krb5_context context, krb5_enctype enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_allow_weak_crypto\fP (krb5_context context, krb5_boolean enable)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_is_enctype_weak\fP (krb5_context context, krb5_enctype enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fB_krb5_enctype_requires_random_salt\fP (krb5_context context, krb5_enctype enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_random_to_key\fP (krb5_context context, krb5_enctype type, const void *data, size_t size, krb5_keyblock *key)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_crypto_fx_cf2\fP (krb5_context context, const krb5_crypto crypto1, const krb5_crypto crypto2, krb5_data *pepper1, krb5_data *pepper2, krb5_enctype enctype, krb5_keyblock *res)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_generate_subkey_extended\fP (krb5_context context, const krb5_keyblock *key, krb5_enctype etype, krb5_keyblock **subkey)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_keyblock_zero\fP (krb5_keyblock *keyblock)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_keyblock_contents\fP (krb5_context context, krb5_keyblock *keyblock)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_keyblock\fP (krb5_context context, krb5_keyblock *keyblock)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_keyblock_contents\fP (krb5_context context, const krb5_keyblock *inblock, krb5_keyblock *to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_keyblock\fP (krb5_context context, const krb5_keyblock *inblock, krb5_keyblock **to)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_enctype KRB5_LIB_CALL \fBkrb5_keyblock_get_enctype\fP (const krb5_keyblock *block)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_keyblock_init\fP (krb5_context context, krb5_enctype type, const void *data, size_t size, krb5_keyblock *key)" +.br +.ti -1c +.RI "krb5_error_code \fB_krb5_SP800_108_HMAC_KDF\fP (krb5_context context, const krb5_data *kdf_K1, const krb5_data *kdf_label, const krb5_data *kdf_context, const EVP_MD *md, krb5_data *kdf_K0)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL _krb5_enctype_requires_random_salt (krb5_context context, krb5_enctype enctype)" +Returns whether the encryption type should use randomly generated salts +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIenctype\fP encryption type to probe +.RE +.PP +\fBReturns\fP +.RS 4 +Returns true if generated salts should have random component +.RE +.PP + +.SS "krb5_error_code _krb5_SP800_108_HMAC_KDF (krb5_context context, const krb5_data * kdf_K1, const krb5_data * kdf_label, const krb5_data * kdf_context, const EVP_MD * md, krb5_data * kdf_K0)" +As described in SP800-108 5\&.1 (for HMAC) +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIkdf_K1\fP Base key material\&. +.br +\fIkdf_label\fP A string that identifies the purpose for the derived key\&. +.br +\fIkdf_context\fP A binary string containing parties, nonce, etc\&. +.br +\fImd\fP Message digest function to use for PRF\&. +.br +\fIkdf_K0\fP Derived key data\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code for an failure or 0 on success\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_allow_weak_crypto (krb5_context context, krb5_boolean enable)" +Enable or disable all weak encryption types +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIenable\fP true to enable, false to disable +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_cksumtype_to_enctype (krb5_context context, krb5_cksumtype ctype, krb5_enctype * etype)" +Return the coresponding encryption type for a checksum type\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIctype\fP The checksum type to get the result enctype for +.br +\fIetype\fP The returned encryption, when the matching etype is not found, etype is set to ETYPE_NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code for an failure or 0 on success\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_keyblock (krb5_context context, const krb5_keyblock * inblock, krb5_keyblock ** to)" +Copy a keyblock, free the output keyblock with \fBkrb5_free_keyblock()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIinblock\fP the key to copy +.br +\fIto\fP the output key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success or a Kerberos 5 error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_keyblock_contents (krb5_context context, const krb5_keyblock * inblock, krb5_keyblock * to)" +Copy a keyblock, free the output keyblock with \fBkrb5_free_keyblock_contents()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIinblock\fP the key to copy +.br +\fIto\fP the output key\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success or a Kerberos 5 error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_create_checksum_iov (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP * data, unsigned int num_data, krb5_cksumtype * type)" +Create a Kerberos message checksum\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP Kerberos crypto context +.br +\fIusage\fP Key usage for this buffer +.br +\fIdata\fP array of buffers to process +.br +\fInum_data\fP length of array +.br +\fItype\fP output data +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_destroy (krb5_context context, krb5_crypto crypto)" +Free a crypto context created by \fBkrb5_crypto_init()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP crypto context to free +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_fx_cf2 (krb5_context context, const krb5_crypto crypto1, const krb5_crypto crypto2, krb5_data * pepper1, krb5_data * pepper2, krb5_enctype enctype, krb5_keyblock * res)" +The FX-CF2 key derivation function, used in FAST and preauth framework\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIcrypto1\fP first key to combine +.br +\fIcrypto2\fP second key to combine +.br +\fIpepper1\fP factor to combine with first key to garante uniqueness +.br +\fIpepper2\fP factor to combine with second key to garante uniqueness +.br +\fIenctype\fP the encryption type of the resulting key +.br +\fIres\fP allocated key, free with \fBkrb5_free_keyblock_contents()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getblocksize (krb5_context context, krb5_crypto crypto, size_t * blocksize)" +Return the blocksize used algorithm referenced by the crypto context +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP crypto context to query +.br +\fIblocksize\fP the resulting blocksize +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getconfoundersize (krb5_context context, krb5_crypto crypto, size_t * confoundersize)" +Return the confounder size used by the crypto context +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP crypto context to query +.br +\fIconfoundersize\fP the returned confounder size +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getenctype (krb5_context context, krb5_crypto crypto, krb5_enctype * enctype)" +Return the encryption type used by the crypto context +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP crypto context to query +.br +\fIenctype\fP the resulting encryption type +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_getpadsize (krb5_context context, krb5_crypto crypto, size_t * padsize)" +Return the padding size used by the crypto context +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP crypto context to query +.br +\fIpadsize\fP the return padding size +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_crypto_init (krb5_context context, const krb5_keyblock * key, krb5_enctype etype, krb5_crypto * crypto)" +Create a crypto context used for all encryption and signature operation\&. The encryption type to use is taken from the key, but can be overridden with the enctype parameter\&. This can be useful for encryptions types which is compatiable (DES for example)\&. +.PP +To free the crypto context, use \fBkrb5_crypto_destroy()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIkey\fP the key block information with all key data +.br +\fIetype\fP the encryption type +.br +\fIcrypto\fP the resulting crypto context +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_decrypt_iov_ivec (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP * data, unsigned int num_data, void * ivec)" +Inline decrypt a Kerberos message\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP Kerberos crypto context +.br +\fIusage\fP Key usage for this buffer +.br +\fIdata\fP array of buffers to process +.br +\fInum_data\fP length of array +.br +\fIivec\fP initial cbc/cts vector +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP +.IP "1." 4 +KRB5_CRYPTO_TYPE_HEADER +.IP "2." 4 +one KRB5_CRYPTO_TYPE_DATA and array [0,\&.\&.\&.] of KRB5_CRYPTO_TYPE_SIGN_ONLY in any order, however the receiver have to aware of the order\&. KRB5_CRYPTO_TYPE_SIGN_ONLY is commonly used unencrypoted protocol headers and trailers\&. The output data will be of same size as the input data or shorter\&. +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_encrypt_iov_ivec (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP * data, int num_data, void * ivec)" +Inline encrypt a kerberos message +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP Kerberos crypto context +.br +\fIusage\fP Key usage for this buffer +.br +\fIdata\fP array of buffers to process +.br +\fInum_data\fP length of array +.br +\fIivec\fP initial cbc/cts vector +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP +Kerberos encrypted data look like this: +.PP +.IP "1." 4 +KRB5_CRYPTO_TYPE_HEADER +.IP "2." 4 +array [1,\&.\&.\&.] KRB5_CRYPTO_TYPE_DATA and array [0,\&.\&.\&.] KRB5_CRYPTO_TYPE_SIGN_ONLY in any order, however the receiver have to aware of the order\&. KRB5_CRYPTO_TYPE_SIGN_ONLY is commonly used headers and trailers\&. +.IP "3." 4 +KRB5_CRYPTO_TYPE_PADDING, at least on padsize long if padsize > 1 +.IP "4." 4 +KRB5_CRYPTO_TYPE_TRAILER +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_disable (krb5_context context, krb5_enctype enctype)" +Disable encryption type +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIenctype\fP encryption type to disable +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_enable (krb5_context context, krb5_enctype enctype)" +Enable encryption type +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIenctype\fP encryption type to enable +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_enctype_valid (krb5_context context, krb5_enctype etype)" +Check if a enctype is valid, return 0 if it is\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIetype\fP enctype to check if its valid or not +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code for an failure or 0 on success (enctype valid)\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_keyblock (krb5_context context, krb5_keyblock * keyblock)" +Free a keyblock, also zero out the content of the keyblock, uses \fBkrb5_free_keyblock_contents()\fP to free the content\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIkeyblock\fP keyblock to free, NULL is valid argument +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_keyblock_contents (krb5_context context, krb5_keyblock * keyblock)" +Free a keyblock's content, also zero out the content of the keyblock\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context +.br +\fIkeyblock\fP keyblock content to free, NULL is valid argument +.RE +.PP + +.SS "HEIMDAL_WARN_UNUSED_RESULT_ATTRIBUTE KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_generate_random (void * buf, size_t len)" +Fill buffer buf with len bytes of PRNG randomness that is ok to use for key generation, padding and public diclosing the randomness w/o disclosing the randomness source\&. +.PP +This function can fail, and callers must check the return value\&. +.PP +\fBParameters\fP +.RS 4 +\fIbuf\fP a buffer to fill with randomness +.br +\fIlen\fP length of memory that buf points to\&. +.RE +.PP +\fBReturns\fP +.RS 4 +return 0 on success or HEIM_ERR_RANDOM_OFFLINE if the funcation failed to initialize the randomness source\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_generate_random_block (void * buf, size_t len)" +Fill buffer buf with len bytes of PRNG randomness that is ok to use for key generation, padding and public diclosing the randomness w/o disclosing the randomness source\&. +.PP +This function can NOT fail, instead it will abort() and program will crash\&. +.PP +If this function is called after a successful \fBkrb5_init_context()\fP, the chance of it failing is low due to that \fBkrb5_init_context()\fP pulls out some random, and quite commonly the randomness sources will not fail once it have started to produce good output, /dev/urandom behavies that way\&. +.PP +\fBParameters\fP +.RS 4 +\fIbuf\fP a buffer to fill with randomness +.br +\fIlen\fP length of memory that buf points to\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_generate_subkey_extended (krb5_context context, const krb5_keyblock * key, krb5_enctype etype, krb5_keyblock ** subkey)" +Generate subkey, from keyblock +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP kerberos context +.br +\fIkey\fP session key +.br +\fIetype\fP encryption type of subkey, if ETYPE_NULL, use key's enctype +.br +\fIsubkey\fP returned new, free with \fBkrb5_free_keyblock()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success or a Kerberos 5 error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_is_enctype_weak (krb5_context context, krb5_enctype enctype)" +Returns is the encryption is strong or weak +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIenctype\fP encryption type to probe +.RE +.PP +\fBReturns\fP +.RS 4 +Returns true if encryption type is weak or is not supported\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_enctype KRB5_LIB_CALL krb5_keyblock_get_enctype (const krb5_keyblock * block)" +Get encryption type of a keyblock\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keyblock_init (krb5_context context, krb5_enctype type, const void * data, size_t size, krb5_keyblock * key)" +Fill in `key' with key data of type `enctype' from `data' of length `size'\&. Key should be freed using \fBkrb5_free_keyblock_contents()\fP\&. +.PP +\fBReturns\fP +.RS 4 +0 on success or a Kerberos 5 error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_keyblock_zero (krb5_keyblock * keyblock)" +Zero out a keyblock +.PP +\fBParameters\fP +.RS 4 +\fIkeyblock\fP keyblock to zero out +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_random_to_key (krb5_context context, krb5_enctype type, const void * data, size_t size, krb5_keyblock * key)" +Converts the random bytestring to a protocol key according to Kerberos crypto frame work\&. It may be assumed that all the bits of the input string are equally random, even though the entropy present in the random source may be limited\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fItype\fP the enctype resulting key will be of +.br +\fIdata\fP input random data to convert to a key +.br +\fIsize\fP size of input random data, at least krb5_enctype_keysize() long +.br +\fIkey\fP key, output key, free with \fBkrb5_free_keyblock_contents()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verify_checksum_iov (krb5_context context, krb5_crypto crypto, unsigned usage, \fBkrb5_crypto_iov\fP * data, unsigned int num_data, krb5_cksumtype * type)" +Verify a Kerberos message checksum\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIcrypto\fP Kerberos crypto context +.br +\fIusage\fP Key usage for this buffer +.br +\fIdata\fP array of buffers to process +.br +\fInum_data\fP length of array +.br +\fItype\fP return checksum type if not NULL +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_crypto_destroy.3 b/static/netbsd/man3/krb5_crypto_destroy.3 new file mode 100644 index 00000000..0ba9f88e --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_destroy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_destroy.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_fx_cf2.3 b/static/netbsd/man3/krb5_crypto_fx_cf2.3 new file mode 100644 index 00000000..4dee940c --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_fx_cf2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_fx_cf2.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_getblocksize.3 b/static/netbsd/man3/krb5_crypto_getblocksize.3 new file mode 100644 index 00000000..fb913050 --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_getblocksize.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_getblocksize.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_getconfoundersize.3 b/static/netbsd/man3/krb5_crypto_getconfoundersize.3 new file mode 100644 index 00000000..39a4a26f --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_getconfoundersize.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_getconfoundersize.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_getenctype.3 b/static/netbsd/man3/krb5_crypto_getenctype.3 new file mode 100644 index 00000000..ef452138 --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_getenctype.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_getenctype.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_getpadsize.3 b/static/netbsd/man3/krb5_crypto_getpadsize.3 new file mode 100644 index 00000000..db98b913 --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_getpadsize.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_getpadsize.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_init.3 b/static/netbsd/man3/krb5_crypto_init.3 new file mode 100644 index 00000000..e6e4530a --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_crypto_init.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_crypto_iov.3 b/static/netbsd/man3/krb5_crypto_iov.3 new file mode 100644 index 00000000..62a4be3f --- /dev/null +++ b/static/netbsd/man3/krb5_crypto_iov.3 @@ -0,0 +1,19 @@ +.\" $NetBSD: krb5_crypto_iov.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_crypto_iov" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_crypto_iov +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Semi private, not stable yet + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_data_alloc.3 b/static/netbsd/man3/krb5_data_alloc.3 new file mode 100644 index 00000000..33e2f823 --- /dev/null +++ b/static/netbsd/man3/krb5_data_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_alloc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_cmp.3 b/static/netbsd/man3/krb5_data_cmp.3 new file mode 100644 index 00000000..54699e69 --- /dev/null +++ b/static/netbsd/man3/krb5_data_cmp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_cmp.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_copy.3 b/static/netbsd/man3/krb5_data_copy.3 new file mode 100644 index 00000000..3e8aec7b --- /dev/null +++ b/static/netbsd/man3/krb5_data_copy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_copy.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_ct_cmp.3 b/static/netbsd/man3/krb5_data_ct_cmp.3 new file mode 100644 index 00000000..52d4694a --- /dev/null +++ b/static/netbsd/man3/krb5_data_ct_cmp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_ct_cmp.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_free.3 b/static/netbsd/man3/krb5_data_free.3 new file mode 100644 index 00000000..9336f8d1 --- /dev/null +++ b/static/netbsd/man3/krb5_data_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_realloc.3 b/static/netbsd/man3/krb5_data_realloc.3 new file mode 100644 index 00000000..2fd140fd --- /dev/null +++ b/static/netbsd/man3/krb5_data_realloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_realloc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_data_zero.3 b/static/netbsd/man3/krb5_data_zero.3 new file mode 100644 index 00000000..e21846ee --- /dev/null +++ b/static/netbsd/man3/krb5_data_zero.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_data_zero.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_dcc_ops.3 b/static/netbsd/man3/krb5_dcc_ops.3 new file mode 100644 index 00000000..b320eeab --- /dev/null +++ b/static/netbsd/man3/krb5_dcc_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_dcc_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_decrypt_iov_ivec.3 b/static/netbsd/man3/krb5_decrypt_iov_ivec.3 new file mode 100644 index 00000000..fb1c3d92 --- /dev/null +++ b/static/netbsd/man3/krb5_decrypt_iov_ivec.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_decrypt_iov_ivec.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_deprecated.3 b/static/netbsd/man3/krb5_deprecated.3 new file mode 100644 index 00000000..a898b3d7 --- /dev/null +++ b/static/netbsd/man3/krb5_deprecated.3 @@ -0,0 +1,251 @@ +.\" $NetBSD: krb5_deprecated.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_deprecated" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_deprecated \- Heimdal Kerberos 5 deprecated functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_change_password\fP (krb5_context context, krb5_creds *creds, const char *newpw, int *result_code, krb5_data *result_code_string, krb5_data *result_string) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_config_parse_string_multi\fP (krb5_context context, const char *string, krb5_config_section **res) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_keytype_to_enctypes\fP (krb5_context context, krb5_keytype keytype, unsigned *len, krb5_enctype **val) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_enctypes_compatible_keys\fP (krb5_context context, krb5_enctype etype1, krb5_enctype etype2) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_data_contents\fP (krb5_context context, krb5_data *data) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_keytype_to_enctypes_default\fP (krb5_context context, krb5_keytype keytype, unsigned *len, krb5_enctype **val) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_keytype_to_string\fP (krb5_context context, krb5_keytype keytype, char **string) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_string_to_keytype\fP (krb5_context context, const char *string, krb5_keytype *keytype) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV \fBkrb5_password_key_proc\fP (krb5_context context, krb5_enctype type, krb5_salt salt, krb5_const_pointer keyseed, krb5_keyblock **key) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_in_tkt_with_password\fP (krb5_context context, krb5_flags options, krb5_addresses *addrs, const krb5_enctype *etypes, const krb5_preauthtype *pre_auth_types, const char *password, krb5_ccache ccache, krb5_creds *creds, krb5_kdc_rep *ret_as_reply) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_in_tkt_with_skey\fP (krb5_context context, krb5_flags options, krb5_addresses *addrs, const krb5_enctype *etypes, const krb5_preauthtype *pre_auth_types, const krb5_keyblock *key, krb5_ccache ccache, krb5_creds *creds, krb5_kdc_rep *ret_as_reply) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV \fBkrb5_keytab_key_proc\fP (krb5_context context, krb5_enctype enctype, krb5_salt salt, krb5_const_pointer keyseed, krb5_keyblock **key) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_in_tkt_with_keytab\fP (krb5_context context, krb5_flags options, krb5_addresses *addrs, const krb5_enctype *etypes, const krb5_preauthtype *pre_auth_types, krb5_keytab keytab, krb5_ccache ccache, krb5_creds *creds, krb5_kdc_rep *ret_as_reply) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_realm *KRB5_LIB_CALL \fBkrb5_princ_realm\fP (krb5_context context, krb5_principal principal) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_princ_set_realm\fP (krb5_context context, krb5_principal principal, krb5_realm *realm) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_creds_contents\fP (krb5_context context, krb5_creds *c) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_error_string\fP (krb5_context context, char *str) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_error_string\fP (krb5_context context, const char *fmt,\&.\&.\&.) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_vset_error_string\fP (krb5_context context, const char *fmt, va_list args) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_clear_error_string\fP (krb5_context context) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_cred_from_kdc_opt\fP (krb5_context context, krb5_ccache ccache, krb5_creds *in_creds, krb5_creds **out_creds, krb5_creds ***ret_tgts, krb5_flags flags) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_cred_from_kdc\fP (krb5_context context, krb5_ccache ccache, krb5_creds *in_creds, krb5_creds **out_creds, krb5_creds ***ret_tgts) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_unparsed_name\fP (krb5_context context, char *str) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_generate_subkey\fP (krb5_context context, const krb5_keyblock *key, krb5_keyblock **subkey) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_auth_getremoteseqnumber\fP (krb5_context context, krb5_auth_context auth_context, int32_t *seqnumber) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_get_init_creds_opt_init\fP (krb5_get_init_creds_opt *opt) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_get_init_creds_opt_get_error\fP (krb5_context context, krb5_get_init_creds_opt *opt, KRB_ERROR **error) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_c_enctype_compare\fP (krb5_context context, krb5_enctype e1, krb5_enctype e2, krb5_boolean *similar) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_auth_getremoteseqnumber (krb5_context context, krb5_auth_context auth_context, int32_t * seqnumber)" +Deprecated: use krb5_auth_con_getremoteseqnumber() +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_c_enctype_compare (krb5_context context, krb5_enctype e1, krb5_enctype e2, krb5_boolean * similar)" +Deprecated: keytypes doesn't exists, they are really enctypes\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_change_password (krb5_context context, krb5_creds * creds, const char * newpw, int * result_code, krb5_data * result_code_string, krb5_data * result_string)" +Deprecated: \fBkrb5_change_password()\fP is deprecated, use \fBkrb5_set_password()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIcreds\fP +.br +\fInewpw\fP +.br +\fIresult_code\fP +.br +\fIresult_code_string\fP +.br +\fIresult_string\fP +.RE +.PP +\fBReturns\fP +.RS 4 +On sucess password is changed\&. +.RE +.PP +@ +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_clear_error_string (krb5_context context)" +Clear the error message returned by \fBkrb5_get_error_string()\fP\&. +.PP +Deprecated: use \fBkrb5_clear_error_message()\fP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_parse_string_multi (krb5_context context, const char * string, krb5_config_section ** res)" +Deprecated: configuration files are not strings +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_enctypes_compatible_keys (krb5_context context, krb5_enctype etype1, krb5_enctype etype2)" +Deprecated: keytypes doesn't exists, they are really enctypes\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_creds_contents (krb5_context context, krb5_creds * c)" +Deprecated: use \fBkrb5_free_cred_contents()\fP +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_data_contents (krb5_context context, krb5_data * data)" +Same as \fBkrb5_data_free()\fP\&. MIT compat\&. +.PP +Deprecated: use \fBkrb5_data_free()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIdata\fP krb5_data to free\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_error_string (krb5_context context, char * str)" +Free the error message returned by \fBkrb5_get_error_string()\fP\&. +.PP +Deprecated: use \fBkrb5_free_error_message()\fP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIstr\fP error message to free +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_unparsed_name (krb5_context context, char * str)" +Deprecated: use krb5_xfree()\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_generate_subkey (krb5_context context, const krb5_keyblock * key, krb5_keyblock ** subkey)" +Deprecated: use \fBkrb5_generate_subkey_extended()\fP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_cred_from_kdc (krb5_context context, krb5_ccache ccache, krb5_creds * in_creds, krb5_creds ** out_creds, krb5_creds *** ret_tgts)" +Deprecated: use krb5_get_credentials_with_flags()\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_cred_from_kdc_opt (krb5_context context, krb5_ccache ccache, krb5_creds * in_creds, krb5_creds ** out_creds, krb5_creds *** ret_tgts, krb5_flags flags)" +Deprecated: use krb5_get_credentials_with_flags()\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_keytab (krb5_context context, krb5_flags options, krb5_addresses * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, krb5_keytab keytab, krb5_ccache ccache, krb5_creds * creds, krb5_kdc_rep * ret_as_reply)" +Deprecated: use krb5_get_init_creds() and friends\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_password (krb5_context context, krb5_flags options, krb5_addresses * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, const char * password, krb5_ccache ccache, krb5_creds * creds, krb5_kdc_rep * ret_as_reply)" +Deprecated: use krb5_get_init_creds() and friends\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_in_tkt_with_skey (krb5_context context, krb5_flags options, krb5_addresses * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, const krb5_keyblock * key, krb5_ccache ccache, krb5_creds * creds, krb5_kdc_rep * ret_as_reply)" +Deprecated: use krb5_get_init_creds() and friends\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_opt_get_error (krb5_context context, krb5_get_init_creds_opt * opt, KRB_ERROR ** error)" +Deprecated: use the new \fBkrb5_init_creds_init()\fP and \fBkrb5_init_creds_get_error()\fP\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_init (krb5_get_init_creds_opt * opt)" +Deprecated: use \fBkrb5_get_init_creds_opt_alloc()\fP\&. +.PP +The reason \fBkrb5_get_init_creds_opt_init()\fP is deprecated is that krb5_get_init_creds_opt is a static structure and for ABI reason it can't grow, ie can't add new functionality\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV krb5_keytab_key_proc (krb5_context context, krb5_enctype enctype, krb5_salt salt, krb5_const_pointer keyseed, krb5_keyblock ** key)" +Deprecated: use krb5_get_init_creds() and friends\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_enctypes (krb5_context context, krb5_keytype keytype, unsigned * len, krb5_enctype ** val)" +Deprecated: keytypes doesn't exists, they are really enctypes\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_enctypes_default (krb5_context context, krb5_keytype keytype, unsigned * len, krb5_enctype ** val)" +Deprecated: keytypes doesn't exists, they are really enctypes\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_keytype_to_string (krb5_context context, krb5_keytype keytype, char ** string)" +Deprecated: keytypes doesn't exists, they are really enctypes in most cases, use krb5_enctype_to_string()\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_CALLCONV krb5_password_key_proc (krb5_context context, krb5_enctype type, krb5_salt salt, krb5_const_pointer keyseed, krb5_keyblock ** key)" +Deprecated: use krb5_get_init_creds() and friends\&. +.SS "KRB5_LIB_FUNCTION krb5_realm* KRB5_LIB_CALL krb5_princ_realm (krb5_context context, krb5_principal principal)" +Deprecated: use \fBkrb5_principal_get_realm()\fP +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_princ_set_realm (krb5_context context, krb5_principal principal, krb5_realm * realm)" +Deprecated: use \fBkrb5_principal_set_realm()\fP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_error_string (krb5_context context, const char * fmt, \&.\&.\&.)" +Set the error message returned by \fBkrb5_get_error_string()\fP\&. +.PP +Deprecated: use \fBkrb5_get_error_message()\fP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIfmt\fP error message to free +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_string_to_keytype (krb5_context context, const char * string, krb5_keytype * keytype)" +Deprecated: keytypes doesn't exists, they are really enctypes in most cases, use krb5_string_to_enctype()\&. +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vset_error_string (krb5_context context, const char * fmt, va_list args)" +Set the error message returned by \fBkrb5_get_error_string()\fP, deprecated, use \fBkrb5_set_error_message()\fP\&. +.PP +Deprecated: use \fBkrb5_vset_error_message()\fP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIfmt\fP error message to free +.br +\fIargs\fP variable argument list vector +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_digest.3 b/static/netbsd/man3/krb5_digest.3 new file mode 100644 index 00000000..b5d39c3d --- /dev/null +++ b/static/netbsd/man3/krb5_digest.3 @@ -0,0 +1,45 @@ +.\" $NetBSD: krb5_digest.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_digest" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_digest \- Heimdal Kerberos 5 digest service +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_digest_probe\fP (krb5_context context, krb5_realm realm, krb5_ccache ccache, unsigned *flags)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_digest_probe (krb5_context context, krb5_realm realm, krb5_ccache ccache, unsigned * flags)" +Get the supported/allowed mechanism for this principal\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Keberos context\&. +.br +\fIrealm\fP The realm of the KDC\&. +.br +\fIccache\fP The credential cache to use when talking to the KDC\&. +.br +\fIflags\fP The supported mechanism\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_digest_probe.3 b/static/netbsd/man3/krb5_digest_probe.3 new file mode 100644 index 00000000..1c5b968d --- /dev/null +++ b/static/netbsd/man3/krb5_digest_probe.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_digest_probe.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_digest.3 diff --git a/static/netbsd/man3/krb5_eai_to_heim_errno.3 b/static/netbsd/man3/krb5_eai_to_heim_errno.3 new file mode 100644 index 00000000..65eb4a95 --- /dev/null +++ b/static/netbsd/man3/krb5_eai_to_heim_errno.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_eai_to_heim_errno.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_encrypt.3 b/static/netbsd/man3/krb5_encrypt.3 new file mode 100644 index 00000000..72dedb78 --- /dev/null +++ b/static/netbsd/man3/krb5_encrypt.3 @@ -0,0 +1,280 @@ +.\" $NetBSD: krb5_encrypt.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 1999 - 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd March 20, 2004 +.Dt KRB5_ENCRYPT 3 +.Os +.Sh NAME +.Nm krb5_crypto_getblocksize , +.Nm krb5_crypto_getconfoundersize +.Nm krb5_crypto_getenctype , +.Nm krb5_crypto_getpadsize , +.Nm krb5_crypto_overhead , +.Nm krb5_decrypt , +.Nm krb5_decrypt_EncryptedData , +.Nm krb5_decrypt_ivec , +.Nm krb5_decrypt_ticket , +.Nm krb5_encrypt , +.Nm krb5_encrypt_EncryptedData , +.Nm krb5_encrypt_ivec , +.Nm krb5_enctype_disable , +.Nm krb5_enctype_keysize , +.Nm krb5_enctype_to_string , +.Nm krb5_enctype_valid , +.Nm krb5_get_wrapped_length , +.Nm krb5_string_to_enctype +.Nd "encrypt and decrypt data, set and get encryption type parameters" +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_encrypt +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "krb5_data *result" +.Fc +.Ft krb5_error_code +.Fo krb5_encrypt_EncryptedData +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "int kvno" +.Fa "EncryptedData *result" +.Fc +.Ft krb5_error_code +.Fo krb5_encrypt_ivec +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "krb5_data *result" +.Fa "void *ivec" +.Fc +.Ft krb5_error_code +.Fo krb5_decrypt +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "krb5_data *result" +.Fc +.Ft krb5_error_code +.Fo krb5_decrypt_EncryptedData +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "EncryptedData *e" +.Fa "krb5_data *result" +.Fc +.Ft krb5_error_code +.Fo krb5_decrypt_ivec +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "unsigned usage" +.Fa "void *data" +.Fa "size_t len" +.Fa "krb5_data *result" +.Fa "void *ivec" +.Fc +.Ft krb5_error_code +.Fo krb5_decrypt_ticket +.Fa "krb5_context context" +.Fa "Ticket *ticket" +.Fa "krb5_keyblock *key" +.Fa "EncTicketPart *out" +.Fa "krb5_flags flags" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_getblocksize +.Fa "krb5_context context" +.Fa "size_t *blocksize" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_getenctype +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "krb5_enctype *enctype" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_getpadsize +.Fa "krb5_context context" +.Fa size_t *padsize" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_getconfoundersize +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa size_t *confoundersize" +.Fc +.Ft krb5_error_code +.Fo krb5_enctype_keysize +.Fa "krb5_context context" +.Fa "krb5_enctype type" +.Fa "size_t *keysize" +.Fc +.Ft krb5_error_code +.Fo krb5_crypto_overhead +.Fa "krb5_context context" +.Fa size_t *padsize" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_enctype +.Fa "krb5_context context" +.Fa "const char *string" +.Fa "krb5_enctype *etype" +.Fc +.Ft krb5_error_code +.Fo krb5_enctype_to_string +.Fa "krb5_context context" +.Fa "krb5_enctype etype" +.Fa "char **string" +.Fc +.Ft krb5_error_code +.Fo krb5_enctype_valid +.Fa "krb5_context context" +.Fa "krb5_enctype etype" +.Fc +.Ft void +.Fo krb5_enctype_disable +.Fa "krb5_context context" +.Fa "krb5_enctype etype" +.Fc +.Ft size_t +.Fo krb5_get_wrapped_length +.Fa "krb5_context context" +.Fa "krb5_crypto crypto" +.Fa "size_t data_len" +.Fc +.Sh DESCRIPTION +These functions are used to encrypt and decrypt data. +.Pp +.Fn krb5_encrypt_ivec +puts the encrypted version of +.Fa data +(of size +.Fa len ) +in +.Fa result . +If the encryption type supports using derived keys, +.Fa usage +should be the appropriate key-usage. +.Fa ivec +is a pointer to a initial IV, it is modified to the end IV at the end of +the round. +Ivec should be the size of +If +.Dv NULL +is passed in, the default IV is used. +.Fn krb5_encrypt +does the same as +.Fn krb5_encrypt_ivec +but with +.Fa ivec +being +.Dv NULL . +.Fn krb5_encrypt_EncryptedData +does the same as +.Fn krb5_encrypt , +but it puts the encrypted data in a +.Fa EncryptedData +structure instead. If +.Fa kvno +is not zero, it will be put in the (optional) +.Fa kvno +field in the +.Fa EncryptedData . +.Pp +.Fn krb5_decrypt_ivec , +.Fn krb5_decrypt , +and +.Fn krb5_decrypt_EncryptedData +works similarly. +.Pp +.Fn krb5_decrypt_ticket +decrypts the encrypted part of +.Fa ticket +with +.Fa key . +.Fn krb5_decrypt_ticket +also verifies the timestamp in the ticket, invalid flag and if the KDC +haven't verified the transited path, the transit path. +.Pp +.Fn krb5_enctype_keysize , +.Fn krb5_crypto_getconfoundersize , +.Fn krb5_crypto_getblocksize , +.Fn krb5_crypto_getenctype , +.Fn krb5_crypto_getpadsize , +.Fn krb5_crypto_overhead +all returns various (sometimes) useful information from a crypto context. +.Fn krb5_crypto_overhead +is the combination of krb5_crypto_getconfoundersize, +krb5_crypto_getblocksize and krb5_crypto_getpadsize and return the +maximum overhead size. +.Pp +.Fn krb5_enctype_to_string +converts a encryption type number to a string that can be printable +and stored. The strings returned should be freed with +.Xr free 3 . +.Pp +.Fn krb5_string_to_enctype +converts a encryption type strings to a encryption type number that +can use used for other Kerberos crypto functions. +.Pp +.Fn krb5_enctype_valid +returns 0 if the encrypt is supported and not disabled, otherwise and +error code is returned. +.Pp +.Fn krb5_enctype_disable +(globally, for all contextes) disables the +.Fa enctype . +.Pp +.Fn krb5_get_wrapped_length +returns the size of an encrypted packet by +.Fa crypto +of length +.Fa data_len . +.\" .Sh EXAMPLE +.\" .Sh BUGS +.Sh SEE ALSO +.Xr krb5_create_checksum 3 , +.Xr krb5_crypto_init 3 diff --git a/static/netbsd/man3/krb5_encrypt_iov_ivec.3 b/static/netbsd/man3/krb5_encrypt_iov_ivec.3 new file mode 100644 index 00000000..2560005e --- /dev/null +++ b/static/netbsd/man3/krb5_encrypt_iov_ivec.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_encrypt_iov_ivec.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_enctype_disable.3 b/static/netbsd/man3/krb5_enctype_disable.3 new file mode 100644 index 00000000..0bb55e97 --- /dev/null +++ b/static/netbsd/man3/krb5_enctype_disable.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_enctype_disable.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_enctype_enable.3 b/static/netbsd/man3/krb5_enctype_enable.3 new file mode 100644 index 00000000..6925652d --- /dev/null +++ b/static/netbsd/man3/krb5_enctype_enable.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_enctype_enable.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_enctype_valid.3 b/static/netbsd/man3/krb5_enctype_valid.3 new file mode 100644 index 00000000..945d31a5 --- /dev/null +++ b/static/netbsd/man3/krb5_enctype_valid.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_enctype_valid.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_enctypes_compatible_keys.3 b/static/netbsd/man3/krb5_enctypes_compatible_keys.3 new file mode 100644 index 00000000..34fbf6ba --- /dev/null +++ b/static/netbsd/man3/krb5_enctypes_compatible_keys.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_enctypes_compatible_keys.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_err.3 b/static/netbsd/man3/krb5_err.3 new file mode 100644 index 00000000..b3446bef --- /dev/null +++ b/static/netbsd/man3/krb5_err.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_err.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_error.3 b/static/netbsd/man3/krb5_error.3 new file mode 100644 index 00000000..fe943a78 --- /dev/null +++ b/static/netbsd/man3/krb5_error.3 @@ -0,0 +1,414 @@ +.\" $NetBSD: krb5_error.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_error" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_error \- Heimdal Kerberos 5 error reporting functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION char *KRB5_LIB_CALL \fBkrb5_get_error_string\fP (krb5_context context) KRB5_DEPRECATED_FUNCTION('Use \fBkrb5_get_error_message\fP instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_eai_to_heim_errno\fP (int eai_errno, int system_error)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_h_errno_to_heim_errno\fP (int eai_errno)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_clear_error_message\fP (krb5_context context)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_set_error_message\fP (krb5_context context, krb5_error_code ret, const char *fmt,\&.\&.\&.) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_vset_error_message\fP (krb5_context context, krb5_error_code ret, const char *fmt, va_list args) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_prepend_error_message\fP (krb5_context context, krb5_error_code ret, const char *fmt,\&.\&.\&.) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_vprepend_error_message\fP (krb5_context context, krb5_error_code ret, const char *fmt, va_list args) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_get_error_message\fP (krb5_context context, krb5_error_code code)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_error_message\fP (krb5_context context, const char *msg)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_vwarn\fP (krb5_context context, krb5_error_code code, const char *fmt, va_list ap) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_warn\fP (krb5_context context, krb5_error_code code, const char *fmt,\&.\&.\&.) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_vwarnx\fP (krb5_context context, const char *fmt, va_list ap) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_warnx\fP (krb5_context context, const char *fmt,\&.\&.\&.) __attribute__((__format__(__printf__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_verr\fP (krb5_context context, int eval, krb5_error_code code, const char *fmt, va_list ap) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_err\fP (krb5_context context, int eval, krb5_error_code code, const char *fmt,\&.\&.\&.) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_verrx\fP (krb5_context context, int eval, const char *fmt, va_list ap) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_errx\fP (krb5_context context, int eval, const char *fmt,\&.\&.\&.) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_vabort\fP (krb5_context context, krb5_error_code code, const char *fmt, va_list ap) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_abort\fP (krb5_context context, krb5_error_code code, const char *fmt,\&.\&.\&.) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_abortx\fP (krb5_context context, const char *fmt,\&.\&.\&.) __attribute__((__noreturn__" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_set_warn_dest\fP (krb5_context context, krb5_log_facility *fac)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_log_facility *KRB5_LIB_CALL \fBkrb5_get_warn_dest\fP (krb5_context context)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_abort (krb5_context context, krb5_error_code code, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr, include the error from the last failure and then abort\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.br +\fI\&.\&.\&.\fP arguments for format string +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_abortx (krb5_context context, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr, and then abort\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIfmt\fP printf format string of message to print +.br +\fI\&.\&.\&.\fP arguments for format string +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_clear_error_message (krb5_context context)" +Clears the error message from the Kerberos 5 context\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP The Kerberos 5 context to clear +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_eai_to_heim_errno (int eai_errno, int system_error)" +Convert the getaddrinfo() error code to a Kerberos et error code\&. +.PP +\fBParameters\fP +.RS 4 +\fIeai_errno\fP contains the error code from getaddrinfo()\&. +.br +\fIsystem_error\fP should have the value of errno after the failed getaddrinfo()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos error code representing the EAI errors\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_err (krb5_context context, int eval, krb5_error_code code, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr, include bthe error from the last failure and then exit\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIeval\fP the exit code to exit with +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_errx (krb5_context context, int eval, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr, and then exit\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIeval\fP the exit code to exit with +.br +\fIfmt\fP message to print +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_error_message (krb5_context context, const char * msg)" +Free the error message returned by \fBkrb5_get_error_message()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fImsg\fP error message to free, returned byg \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_get_error_message (krb5_context context, krb5_error_code code)" +Return the error message for `code' in context\&. On memory allocation error the function returns NULL\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIcode\fP Error code related to the error +.RE +.PP +\fBReturns\fP +.RS 4 +an error string, needs to be freed with \fBkrb5_free_error_message()\fP\&. The functions return NULL on error\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION char* KRB5_LIB_CALL krb5_get_error_string (krb5_context context)" +Return the error message in context\&. On error or no error string, the function returns NULL\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.RE +.PP +\fBReturns\fP +.RS 4 +an error string, needs to be freed with \fBkrb5_free_error_message()\fP\&. The functions return NULL on error\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_log_facility* KRB5_LIB_CALL krb5_get_warn_dest (krb5_context context)" +Get the default logging facility\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_h_errno_to_heim_errno (int eai_errno)" +Convert the gethostname() error code (h_error) to a Kerberos et error code\&. +.PP +\fBParameters\fP +.RS 4 +\fIeai_errno\fP contains the error code from gethostname()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Kerberos error code representing the gethostname errors\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_prepend_error_message (krb5_context context, krb5_error_code ret, const char * fmt, \&.\&.\&.)" +Prepend the context full error string for a specific error code\&. The error that is stored should be internationalized\&. +.PP +The if context is NULL, no error string is stored\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIret\fP The error code +.br +\fIfmt\fP Error string for the error code +.br +\fI\&.\&.\&.\fP printf(3) style parameters\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_set_error_message (krb5_context context, krb5_error_code ret, const char * fmt, \&.\&.\&.)" +Set the context full error string for a specific error code\&. The error that is stored should be internationalized\&. +.PP +The if context is NULL, no error string is stored\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIret\fP The error code +.br +\fIfmt\fP Error string for the error code +.br +\fI\&.\&.\&.\fP printf(3) style parameters\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_set_warn_dest (krb5_context context, krb5_log_facility * fac)" +Set the default logging facility\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIfac\fP Facility to use for logging\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vabort (krb5_context context, krb5_error_code code, const char * fmt, va_list ap)" +Log a warning to the log, default stderr, include bthe error from the last failure and then abort\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.br +\fIap\fP arguments +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verr (krb5_context context, int eval, krb5_error_code code, const char * fmt, va_list ap)" +Log a warning to the log, default stderr, include bthe error from the last failure and then exit\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIeval\fP the exit code to exit with +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.br +\fIap\fP arguments +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_verrx (krb5_context context, int eval, const char * fmt, va_list ap)" +Log a warning to the log, default stderr, and then exit\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIeval\fP the exit code to exit with +.br +\fIfmt\fP message to print +.br +\fIap\fP arguments +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_vprepend_error_message (krb5_context context, krb5_error_code ret, const char * fmt, va_list args)" +Prepend the contexts's full error string for a specific error code\&. +.PP +The if context is NULL, no error string is stored\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIret\fP The error code +.br +\fIfmt\fP Error string for the error code +.br +\fIargs\fP printf(3) style parameters\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_vset_error_message (krb5_context context, krb5_error_code ret, const char * fmt, va_list args)" +Set the context full error string for a specific error code\&. +.PP +The if context is NULL, no error string is stored\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIret\fP The error code +.br +\fIfmt\fP Error string for the error code +.br +\fIargs\fP printf(3) style parameters\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vwarn (krb5_context context, krb5_error_code code, const char * fmt, va_list ap)" +Log a warning to the log, default stderr, include the error from the last failure\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.br +\fIap\fP arguments +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_vwarnx (krb5_context context, const char * fmt, va_list ap)" +Log a warning to the log, default stderr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIfmt\fP message to print +.br +\fIap\fP arguments +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_warn (krb5_context context, krb5_error_code code, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr, include the error from the last failure\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIcode\fP error code of the last error +.br +\fIfmt\fP message to print +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_warnx (krb5_context context, const char * fmt, \&.\&.\&.)" +Log a warning to the log, default stderr\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIfmt\fP message to print +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_errx.3 b/static/netbsd/man3/krb5_errx.3 new file mode 100644 index 00000000..8223826f --- /dev/null +++ b/static/netbsd/man3/krb5_errx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_errx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_expand_hostname.3 b/static/netbsd/man3/krb5_expand_hostname.3 new file mode 100644 index 00000000..8cc02861 --- /dev/null +++ b/static/netbsd/man3/krb5_expand_hostname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_expand_hostname.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_expand_hostname_realms.3 b/static/netbsd/man3/krb5_expand_hostname_realms.3 new file mode 100644 index 00000000..7b0f1f49 --- /dev/null +++ b/static/netbsd/man3/krb5_expand_hostname_realms.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_expand_hostname_realms.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_fcc_ops.3 b/static/netbsd/man3/krb5_fcc_ops.3 new file mode 100644 index 00000000..327172a6 --- /dev/null +++ b/static/netbsd/man3/krb5_fcc_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_fcc_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_fileformats.3 b/static/netbsd/man3/krb5_fileformats.3 new file mode 100644 index 00000000..44657c89 --- /dev/null +++ b/static/netbsd/man3/krb5_fileformats.3 @@ -0,0 +1,236 @@ +.\" $NetBSD: krb5_fileformats.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_fileformats" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_fileformats \- File formats + +.SH "File formats" +.PP +This section documents the diffrent file formats that are used in Heimdal and other Kerberos implementations\&. +.SS "keytab" +The keytab binary format is not a standard format\&. The format has evolved and may continue to\&. It is however understood by several Kerberos implementations including Heimdal, MIT, Sun's Java ktab and are created by the ktpass\&.exe utility from Windows\&. So it has established itself as the defacto format for storing Kerberos keys\&. +.PP +The following C-like structure definitions illustrate the MIT keytab file format\&. All values are in network byte order\&. All text is ASCII\&. +.PP +.PP +.nf +keytab { + uint16_t file_format_version; # 0x502 + keytab_entry entries[*]; +}; + +keytab_entry { + int32_t size; + uint16_t num_components; # subtract 1 if version 0x501 + counted_octet_string realm; + counted_octet_string components[num_components]; + uint32_t name_type; # not present if version 0x501 + uint32_t timestamp; + uint8_t vno8; + keyblock key; + uint32_t vno; #only present if >= 4 bytes left in entry + uint32_t flags; #only present if >= 4 bytes left in entry +}; + +counted_octet_string { + uint16_t length; + uint8_t data[length]; +}; + +keyblock { + uint16_t type; + counted_octet_string; +}; +.fi +.PP +.PP +All numbers are stored in network byteorder (big endian) format\&. +.PP +The keytab file format begins with the 16 bit file_format_version which at the time this document was authored is 0x502\&. The format of older keytabs is described at the end of this document\&. +.PP +The file_format_version is immediately followed by an array of keytab_entry structures which are prefixed with a 32 bit size indicating the number of bytes that follow in the entry\&. Note that the size should be evaluated as signed\&. This is because a negative value indicates that the entry is in fact empty (e\&.g\&. it has been deleted) and that the negative value of that negative value (which is of course a positive value) is the offset to the next keytab_entry\&. Based on these size values alone the entire keytab file can be traversed\&. +.PP +The size is followed by a 16 bit num_components field indicating the number of counted_octet_string components in the components array\&. +.PP +The num_components field is followed by a counted_octet_string representing the realm of the principal\&. +.PP +A counted_octet_string is simply an array of bytes prefixed with a 16 bit length\&. For the realm and name components, the counted_octet_string bytes are ASCII encoded text with no zero terminator\&. +.PP +Following the realm is the components array that represents the name of the principal\&. The text of these components may be joined with slashs to construct the typical SPN representation\&. For example, the service principal HTTP/www\&.foo\&.net@FOO\&.NET would consist of name components 'HTTP' followed by 'www\&.foo\&.net'\&. +.PP +Following the components array is the 32 bit name_type (e\&.g\&. 1 is KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc)\&. In practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL\&. +.PP +The 32 bit timestamp indicates the time the key was established for that principal\&. The value represents the number of seconds since Jan 1, 1970\&. +.PP +The 8 bit vno8 field is the version number of the key\&. This value is overridden by the 32 bit vno field if it is present\&. The vno8 field is filled with the lower 8 bits of the 32 bit protocol kvno field\&. +.PP +The keyblock structure consists of a 16 bit value indicating the encryption type and is a counted_octet_string containing the key\&. The encryption type is the same as the Kerberos standard (e\&.g\&. 3 is des-cbc-md5, 23 is arcfour-hmac-md5, etc)\&. +.PP +The last field of the keytab_entry structure is optional\&. If the size of the keytab_entry indicates that there are at least 4 bytes remaining, a 32 bit value representing the key version number is present\&. This value supersedes the 8 bit vno8 value preceeding the keyblock\&. +.PP +Older keytabs with a file_format_version of 0x501 are different in three ways: +.PP +.IP "\(bu" 2 +All integers are in host byte order [1]\&. +.IP "\(bu" 2 +The num_components field is 1 too large (i\&.e\&. after decoding, decrement by 1)\&. +.IP "\(bu" 2 +The 32 bit name_type field is not present\&. +.PP +.PP +[1] The file_format_version field should really be treated as two separate 8 bit quantities representing the major and minor version number respectively\&. +.SS "Heimdal database dump file" +Format of the Heimdal text dump file as of Heimdal 0\&.6\&.3: +.PP +Each line in the dump file is one entry in the database\&. +.PP +Each field of a line is separated by one or more spaces, with the exception of fields consisting of principals containing spaces, where space can be quoted with \\ and \\ is quoted by . +.PP +Fields and their types are: +.PP +.PP +.nf +Quoted princial (quote character is \) [string] +Keys [keys] +Created by [event] +Modified by [event optional] +Valid start time [time optional] +Valid end time [time optional] +Password end valid time [time optional] +Max lifetime of ticket [time optional] +Max renew time of ticket [integer optional] +Flags [hdb flags] +Generation number [generation optional] +Extensions [extentions optional] +.fi +.PP +.PP +Fields following these silently are ignored\&. +.PP +All optional fields will be skipped if they fail to parse (or comprise the optional field marker of '-', w/o quotes)\&. +.PP +Example: +.PP +.PP +.nf +fred\@CODE\&.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin\@CODE\&.COM 20041221112428:fred\@CODE\&.COM - - - 86400 604800 126 20020415130120:793707:28 - +.fi +.PP +.PP +Encoding of types are as follows: +.PP +.IP "\(bu" 2 +keys +.PP +.PP +.PP +.nf +kvno:[masterkvno:keytype:keydata:salt]{zero or more separated by :} +.fi +.PP +.PP +kvno is the key version number\&. +.PP +keydata is hex-encoded +.PP +masterkvno is the kvno of the database master key\&. If this field is empty, the kadmin load and merge operations will encrypt the key data with the master key if there is one\&. Otherwise the key data will be imported asis\&. +.PP +salt is encoded as '-' (no/default salt) or +.PP +.PP +.nf +salt-type / +salt-type / "string" +salt-type / hex-encoded-data +.fi +.PP +.PP +keytype is the protocol enctype number; see enum ENCTYPE in include/krb5_asn1\&.h for values\&. +.PP +Example: +.PP +.nf +27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- + +.fi +.PP +.PP +.PP +.nf +kvno=27,{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=\&.\&.\&., default salt}\&.\&.\&. +.fi +.PP +.PP +.IP "\(bu" 2 +time +.PP +.PP +Format of the time is: YYYYmmddHHMMSS, corresponding to strftime format '%Y%m%d%k%M%S'\&. +.PP +Time is expressed in UTC\&. +.PP +Time can be optional (using -), when the time 0 is used\&. +.PP +Example: +.PP +.PP +.nf +20041221112428 +.fi +.PP +.PP +.IP "\(bu" 2 +event +.PP +.PP +.PP +.nf +time:principal +.fi +.PP +.PP +time is as given in format time +.PP +principal is a string\&. Not quoting it may not work in earlier versions of Heimdal\&. +.PP +Example: +.PP +.nf +20041221112428:bloggs\@CODE\&.COM + +.fi +.PP +.PP +.IP "\(bu" 2 +hdb flags +.PP +.PP +Integer encoding of HDB flags, see HDBFlags in lib/hdb/hdb\&.asn1\&. Each bit in the integer is the same as the bit in the specification\&. +.PP +.IP "\(bu" 2 +generation: +.PP +.PP +.PP +.nf +time:usec:gen +.fi +.PP +.PP +usec is a the microsecond, integer\&. gen is generation number, integer\&. +.PP +The generation can be defaulted (using '-') or the empty string +.PP +.IP "\(bu" 2 +extensions: +.PP +.PP +.PP +.nf +first-hex-encoded-HDB-Extension[:second-\&.\&.\&.] +.fi +.PP +.PP +HDB-extension is encoded the DER encoded HDB-Extension from lib/hdb/hdb\&.asn1\&. Consumers HDB extensions should be aware that unknown entires needs to be preserved even thought the ASN\&.1 data content might be unknown\&. There is a critical flag in the data to show to the KDC that the entry MUST be understod if the entry is to be used\&. diff --git a/static/netbsd/man3/krb5_find_padata.3 b/static/netbsd/man3/krb5_find_padata.3 new file mode 100644 index 00000000..03d898c5 --- /dev/null +++ b/static/netbsd/man3/krb5_find_padata.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: krb5_find_padata.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd March 21, 2004 +.Dt KRB5_FIND_PADATA 3 +.Os +.Sh NAME +.Nm krb5_find_padata , +.Nm krb5_padata_add +.Nd Kerberos 5 pre-authentication data handling functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft "PA_DATA *" +.Fo krb5_find_padata +.Fa "PA_DATA *val" +.Fa "unsigned len" +.Fa "int type" +.Fa "int *index" +.Fc +.Ft int +.Fo krb5_padata_add +.Fa "krb5_context context" +.Fa "METHOD_DATA *md" +.Fa "int type" +.Fa "void *buf" +.Fa "size_t len" +.Fc +.Sh DESCRIPTION +.Fn krb5_find_padata +tries to find the pre-authentication data entry of type +.Fa type +in the array +.Fa val +of length +.Fa len . +The search is started at entry pointed out by +.Fa *index +(zero based indexing). +If the type isn't found, +.Dv NULL +is returned. +.Pp +.Fn krb5_padata_add +adds a pre-authentication data entry of type +.Fa type +pointed out by +.Fa buf +and +.Fa len +to +.Fa md . +.Sh SEE ALSO +.Xr krb5 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_free_address.3 b/static/netbsd/man3/krb5_free_address.3 new file mode 100644 index 00000000..c2061485 --- /dev/null +++ b/static/netbsd/man3/krb5_free_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_free_addresses.3 b/static/netbsd/man3/krb5_free_addresses.3 new file mode 100644 index 00000000..3d0139e7 --- /dev/null +++ b/static/netbsd/man3/krb5_free_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_free_config_files.3 b/static/netbsd/man3/krb5_free_config_files.3 new file mode 100644 index 00000000..e753394e --- /dev/null +++ b/static/netbsd/man3/krb5_free_config_files.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_config_files.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_context.3 b/static/netbsd/man3/krb5_free_context.3 new file mode 100644 index 00000000..4431daf3 --- /dev/null +++ b/static/netbsd/man3/krb5_free_context.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_context.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_cred_contents.3 b/static/netbsd/man3/krb5_free_cred_contents.3 new file mode 100644 index 00000000..5e576a6f --- /dev/null +++ b/static/netbsd/man3/krb5_free_cred_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_cred_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_creds.3 b/static/netbsd/man3/krb5_free_creds.3 new file mode 100644 index 00000000..77485262 --- /dev/null +++ b/static/netbsd/man3/krb5_free_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_creds_contents.3 b/static/netbsd/man3/krb5_free_creds_contents.3 new file mode 100644 index 00000000..e5cbe859 --- /dev/null +++ b/static/netbsd/man3/krb5_free_creds_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_creds_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_free_data.3 b/static/netbsd/man3/krb5_free_data.3 new file mode 100644 index 00000000..26bcc794 --- /dev/null +++ b/static/netbsd/man3/krb5_free_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_data_contents.3 b/static/netbsd/man3/krb5_free_data_contents.3 new file mode 100644 index 00000000..746adfb1 --- /dev/null +++ b/static/netbsd/man3/krb5_free_data_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_data_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_free_error_message.3 b/static/netbsd/man3/krb5_free_error_message.3 new file mode 100644 index 00000000..50edc361 --- /dev/null +++ b/static/netbsd/man3/krb5_free_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_free_error_string.3 b/static/netbsd/man3/krb5_free_error_string.3 new file mode 100644 index 00000000..d508f562 --- /dev/null +++ b/static/netbsd/man3/krb5_free_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_error_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_free_host_realm.3 b/static/netbsd/man3/krb5_free_host_realm.3 new file mode 100644 index 00000000..e3cf7f42 --- /dev/null +++ b/static/netbsd/man3/krb5_free_host_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_host_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_free_keyblock.3 b/static/netbsd/man3/krb5_free_keyblock.3 new file mode 100644 index 00000000..5fba1759 --- /dev/null +++ b/static/netbsd/man3/krb5_free_keyblock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_keyblock.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_free_keyblock_contents.3 b/static/netbsd/man3/krb5_free_keyblock_contents.3 new file mode 100644 index 00000000..1572d059 --- /dev/null +++ b/static/netbsd/man3/krb5_free_keyblock_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_keyblock_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_free_principal.3 b/static/netbsd/man3/krb5_free_principal.3 new file mode 100644 index 00000000..8a627586 --- /dev/null +++ b/static/netbsd/man3/krb5_free_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_free_ticket.3 b/static/netbsd/man3/krb5_free_ticket.3 new file mode 100644 index 00000000..f07abd8a --- /dev/null +++ b/static/netbsd/man3/krb5_free_ticket.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_ticket.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_free_unparsed_name.3 b/static/netbsd/man3/krb5_free_unparsed_name.3 new file mode 100644 index 00000000..a8b68809 --- /dev/null +++ b/static/netbsd/man3/krb5_free_unparsed_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_free_unparsed_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_fwd_tgt_creds.3 b/static/netbsd/man3/krb5_fwd_tgt_creds.3 new file mode 100644 index 00000000..4facee85 --- /dev/null +++ b/static/netbsd/man3/krb5_fwd_tgt_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_fwd_tgt_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_generate_random.3 b/static/netbsd/man3/krb5_generate_random.3 new file mode 100644 index 00000000..d9ab1547 --- /dev/null +++ b/static/netbsd/man3/krb5_generate_random.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_generate_random.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_generate_random_block.3 b/static/netbsd/man3/krb5_generate_random_block.3 new file mode 100644 index 00000000..60ae9635 --- /dev/null +++ b/static/netbsd/man3/krb5_generate_random_block.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_generate_random_block.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_generate_subkey.3 b/static/netbsd/man3/krb5_generate_subkey.3 new file mode 100644 index 00000000..79d7f7fd --- /dev/null +++ b/static/netbsd/man3/krb5_generate_subkey.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_generate_subkey.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_generate_subkey_extended.3 b/static/netbsd/man3/krb5_generate_subkey_extended.3 new file mode 100644 index 00000000..9aa3beb9 --- /dev/null +++ b/static/netbsd/man3/krb5_generate_subkey_extended.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_generate_subkey_extended.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_get_all_client_addrs.3 b/static/netbsd/man3/krb5_get_all_client_addrs.3 new file mode 100644 index 00000000..f32b90fd --- /dev/null +++ b/static/netbsd/man3/krb5_get_all_client_addrs.3 @@ -0,0 +1,76 @@ +.\" $NetBSD: krb5_get_all_client_addrs.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2001 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd July 1, 2001 +.Dt KRB5_GET_ADDRS 3 +.Os +.Sh NAME +.Nm krb5_get_all_client_addrs , +.Nm krb5_get_all_server_addrs +.Nd return local addresses +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft "krb5_error_code" +.Fn krb5_get_all_client_addrs "krb5_context context" "krb5_addresses *addrs" +.Ft "krb5_error_code" +.Fn krb5_get_all_server_addrs "krb5_context context" "krb5_addresses *addrs" +.Sh DESCRIPTION +These functions return in +.Fa addrs +a list of addresses associated with the local +host. +.Pp +The server variant returns all configured interface addresses (if +possible), including loop-back addresses. This is useful if you want +to create sockets to listen to. +.Pp +The client version will also scan local interfaces (can be turned off +by setting +.Li libdefaults/scan_interfaces +to false in +.Pa krb5.conf ) , +but will not include loop-back addresses, unless there are no other +addresses found. It will remove all addresses included in +.Li libdefaults/ignore_addresses +but will unconditionally include addresses in +.Li libdefaults/extra_addresses . +.Pp +The returned addresses should be freed by calling +.Fn krb5_free_addresses . +.\".Sh EXAMPLE +.Sh SEE ALSO +.Xr krb5_free_addresses 3 diff --git a/static/netbsd/man3/krb5_get_cred_from_kdc.3 b/static/netbsd/man3/krb5_get_cred_from_kdc.3 new file mode 100644 index 00000000..186b4f36 --- /dev/null +++ b/static/netbsd/man3/krb5_get_cred_from_kdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_cred_from_kdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_cred_from_kdc_opt.3 b/static/netbsd/man3/krb5_get_cred_from_kdc_opt.3 new file mode 100644 index 00000000..7a33fa9e --- /dev/null +++ b/static/netbsd/man3/krb5_get_cred_from_kdc_opt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_cred_from_kdc_opt.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_credentials.3 b/static/netbsd/man3/krb5_get_credentials.3 new file mode 100644 index 00000000..fb08ad43 --- /dev/null +++ b/static/netbsd/man3/krb5_get_credentials.3 @@ -0,0 +1,183 @@ +.\" $NetBSD: krb5_get_credentials.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd July 26, 2004 +.Dt KRB5_GET_CREDENTIALS 3 +.Os +.Sh NAME +.Nm krb5_get_credentials , +.Nm krb5_get_credentials_with_flags , +.Nm krb5_get_kdc_cred , +.Nm krb5_get_renewed_creds +.Nd get credentials from the KDC using krbtgt +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_get_credentials +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_credentials_with_flags +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_kdc_flags flags" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_kdc_cred +.Fa "krb5_context context" +.Fa "krb5_ccache id" +.Fa "krb5_kdc_flags flags" +.Fa "krb5_addresses *addresses" +.Fa "Ticket *second_ticket" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_renewed_creds +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_const_principal client" +.Fa "krb5_ccache ccache" +.Fa "const char *in_tkt_service" +.Fc +.Sh DESCRIPTION +.Fn krb5_get_credentials_with_flags +get credentials specified by +.Fa in_creds->server +and +.Fa in_creds->client +(the rest of the +.Fa in_creds +structure is ignored) +by first looking in the +.Fa ccache +and if doesn't exists or is expired, fetch the credential from the KDC +using the krbtgt in +.Fa ccache . +The credential is returned in +.Fa out_creds +and should be freed using the function +.Fn krb5_free_creds . +.Pp +Valid flags to pass into +.Fa options +argument are: +.Pp +.Bl -tag -width "KRB5_GC_EXPIRED_OK" -compact +.It KRB5_GC_CACHED +Only check the +.Fa ccache , +don't got out on network to fetch credential. +.It KRB5_GC_USER_USER +Request a user to user ticket. +This option doesn't store the resulting user to user credential in +the +.Fa ccache . +.It KRB5_GC_EXPIRED_OK +returns the credential even if it is expired, default behavior is trying +to refetch the credential from the KDC. +.El +.Pp +.Fa Flags +are KDCOptions, note the caller must fill in the bit-field and not +use the integer associated structure. +.Pp +.Fn krb5_get_credentials +works the same way as +.Fn krb5_get_credentials_with_flags +except that the +.Fa flags +field is missing. +.Pp +.Fn krb5_get_kdc_cred +does the same as the functions above, but the caller must fill in all +the information andits closer to the wire protocol. +.Pp +.Fn krb5_get_renewed_creds +renews a credential given by +.Fa in_tkt_service +(if +.Dv NULL +the default +.Li krbtgt ) +using the credential cache +.Fa ccache . +The result is stored in +.Fa creds +and should be freed using +.Fa krb5_free_creds . +.Sh EXAMPLES +Here is a example function that get a credential from a credential cache +.Fa id +or the KDC and returns it to the caller. +.Bd -literal +#include + +int +getcred(krb5_context context, krb5_ccache id, krb5_creds **creds) +{ + krb5_error_code ret; + krb5_creds in; + + ret = krb5_parse_name(context, "client@EXAMPLE.COM", + &in.client); + if (ret) + krb5_err(context, 1, ret, "krb5_parse_name"); + + ret = krb5_parse_name(context, "host/server.example.com@EXAMPLE.COM", + &in.server); + if (ret) + krb5_err(context, 1, ret, "krb5_parse_name"); + + ret = krb5_get_credentials(context, 0, id, &in, creds); + if (ret) + krb5_err(context, 1, ret, "krb5_get_credentials"); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_get_forwarded_creds 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_get_creds.3 b/static/netbsd/man3/krb5_get_creds.3 new file mode 100644 index 00000000..e84c4e68 --- /dev/null +++ b/static/netbsd/man3/krb5_get_creds.3 @@ -0,0 +1,175 @@ +.\" $NetBSD: krb5_get_creds.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd June 15, 2006 +.Dt KRB5_GET_CREDS 3 +.Os +.Sh NAME +.Nm krb5_get_creds , +.Nm krb5_get_creds_opt_add_options , +.Nm krb5_get_creds_opt_alloc , +.Nm krb5_get_creds_opt_free , +.Nm krb5_get_creds_opt_set_enctype , +.Nm krb5_get_creds_opt_set_impersonate , +.Nm krb5_get_creds_opt_set_options , +.Nm krb5_get_creds_opt_set_ticket +.Nd get credentials from the KDC +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_get_creds +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "krb5_ccache ccache" +.Fa "krb5_const_principal inprinc" +.Fa "krb5_creds **out_creds" +.Fc +.Ft void +.Fo krb5_get_creds_opt_add_options +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "krb5_flags options" +.Fc +.Ft krb5_error_code +.Fo krb5_get_creds_opt_alloc +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt *opt" +.Fc +.Ft void +.Fo krb5_get_creds_opt_free +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fc +.Ft void +.Fo krb5_get_creds_opt_set_enctype +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "krb5_enctype enctype" +.Fc +.Ft krb5_error_code +.Fo krb5_get_creds_opt_set_impersonate +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "krb5_const_principal self" +.Fc +.Ft void +.Fo krb5_get_creds_opt_set_options +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "krb5_flags options" +.Fc +.Ft krb5_error_code +.Fo krb5_get_creds_opt_set_ticket +.Fa "krb5_context context" +.Fa "krb5_get_creds_opt opt" +.Fa "const Ticket *ticket" +.Fc +.Sh DESCRIPTION +.Fn krb5_get_creds +fetches credentials specified by +.Fa opt +by first looking in the +.Fa ccache , +and then it doesn't exists, fetch the credential from the KDC +using the krbtgts in +.Fa ccache . +The credential is returned in +.Fa out_creds +and should be freed using the function +.Fn krb5_free_creds . +.Pp +The structure +.Li krb5_get_creds_opt +controls the behavior of +.Fn krb5_get_creds . +The structure is opaque to consumers that can set the content of the +structure with accessors functions. All accessor functions make copies +of the data that is passed into accessor functions, so external +consumers free the memory before calling +.Fn krb5_get_creds . +.Pp +The structure +.Li krb5_get_creds_opt +is allocated with +.Fn krb5_get_creds_opt_alloc +and freed with +.Fn krb5_get_creds_opt_free . +The free function also frees the content of the structure set by the +accessor functions. +.Pp +.Fn krb5_get_creds_opt_add_options +and +.Fn krb5_get_creds_opt_set_options +adds and sets options to the +.Li krb5_get_creds_opt +structure . +The possible options to set are +.Bl -tag -width "KRB5_GC_USER_USER" -compact +.It KRB5_GC_CACHED +Only check the +.Fa ccache , +don't got out on network to fetch credential. +.It KRB5_GC_USER_USER +request a user to user ticket. +This options doesn't store the resulting user to user credential in +the +.Fa ccache . +.It KRB5_GC_EXPIRED_OK +returns the credential even if it is expired, default behavior is trying +to refetch the credential from the KDC. +.It KRB5_GC_NO_STORE +Do not store the resulting credentials in the +.Fa ccache . +.El +.Pp +.Fn krb5_get_creds_opt_set_enctype +sets the preferred encryption type of the application. Don't set this +unless you have to since if there is no match in the KDC, the function +call will fail. +.Pp +.Fn krb5_get_creds_opt_set_impersonate +sets the principal to impersonate., Returns a ticket that have the +impersonation principal as a client and the requestor as the +service. Note that the requested principal have to be the same as the +client principal in the krbtgt. +.Pp +.Fn krb5_get_creds_opt_set_ticket +sets the extra ticket used in user-to-user or contrained delegation use case. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_get_credentials 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_get_default_config_files.3 b/static/netbsd/man3/krb5_get_default_config_files.3 new file mode 100644 index 00000000..de10f93f --- /dev/null +++ b/static/netbsd/man3/krb5_get_default_config_files.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_default_config_files.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_default_in_tkt_etypes.3 b/static/netbsd/man3/krb5_get_default_in_tkt_etypes.3 new file mode 100644 index 00000000..f868630d --- /dev/null +++ b/static/netbsd/man3/krb5_get_default_in_tkt_etypes.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_default_in_tkt_etypes.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_dns_canonicalize_hostname.3 b/static/netbsd/man3/krb5_get_dns_canonicalize_hostname.3 new file mode 100644 index 00000000..93713d47 --- /dev/null +++ b/static/netbsd/man3/krb5_get_dns_canonicalize_hostname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_dns_canonicalize_hostname.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_err_text.3 b/static/netbsd/man3/krb5_get_err_text.3 new file mode 100644 index 00000000..fc664083 --- /dev/null +++ b/static/netbsd/man3/krb5_get_err_text.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_err_text.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_error_message.3 b/static/netbsd/man3/krb5_get_error_message.3 new file mode 100644 index 00000000..1cf18232 --- /dev/null +++ b/static/netbsd/man3/krb5_get_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_get_error_string.3 b/static/netbsd/man3/krb5_get_error_string.3 new file mode 100644 index 00000000..2495a43d --- /dev/null +++ b/static/netbsd/man3/krb5_get_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_error_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_get_extra_addresses.3 b/static/netbsd/man3/krb5_get_extra_addresses.3 new file mode 100644 index 00000000..9fc48d07 --- /dev/null +++ b/static/netbsd/man3/krb5_get_extra_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_extra_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_fcache_version.3 b/static/netbsd/man3/krb5_get_fcache_version.3 new file mode 100644 index 00000000..4a20ff08 --- /dev/null +++ b/static/netbsd/man3/krb5_get_fcache_version.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_fcache_version.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_forwarded_creds.3 b/static/netbsd/man3/krb5_get_forwarded_creds.3 new file mode 100644 index 00000000..17a706f5 --- /dev/null +++ b/static/netbsd/man3/krb5_get_forwarded_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_forwarded_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_ignore_addresses.3 b/static/netbsd/man3/krb5_get_ignore_addresses.3 new file mode 100644 index 00000000..bb149ebe --- /dev/null +++ b/static/netbsd/man3/krb5_get_ignore_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_ignore_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_in_cred.3 b/static/netbsd/man3/krb5_get_in_cred.3 new file mode 100644 index 00000000..80f793d9 --- /dev/null +++ b/static/netbsd/man3/krb5_get_in_cred.3 @@ -0,0 +1,276 @@ +.\" $NetBSD: krb5_get_in_cred.3,v 1.5 2023/06/19 21:41:44 christos Exp $ +.\" +.\" Copyright (c) 2003 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 31, 2003 +.Dt KRB5_GET_IN_TKT 3 +.Os +.Sh NAME +.Nm krb5_get_in_tkt , +.Nm krb5_get_in_cred , +.Nm krb5_get_in_tkt_with_password , +.Nm krb5_get_in_tkt_with_keytab , +.Nm krb5_get_in_tkt_with_skey , +.Nm krb5_free_kdc_rep , +.Nm krb5_password_key_proc +.Nd deprecated initial authentication functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft krb5_error_code +.Fo krb5_get_in_tkt +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "const krb5_addresses *addrs" +.Fa "const krb5_enctype *etypes" +.Fa "const krb5_preauthtype *ptypes" +.Fa "krb5_key_proc key_proc" +.Fa "krb5_const_pointer keyseed" +.Fa "krb5_decrypt_proc decrypt_proc" +.Fa "krb5_const_pointer decryptarg" +.Fa "krb5_creds *creds" +.Fa "krb5_ccache ccache" +.Fa "krb5_kdc_rep *ret_as_reply" +.Fc +.Ft krb5_error_code +.Fo krb5_get_in_cred +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "const krb5_addresses *addrs" +.Fa "const krb5_enctype *etypes" +.Fa "const krb5_preauthtype *ptypes" +.Fa "const krb5_preauthdata *preauth" +.Fa "krb5_key_proc key_proc" +.Fa "krb5_const_pointer keyseed" +.Fa "krb5_decrypt_proc decrypt_proc" +.Fa "krb5_const_pointer decryptarg" +.Fa "krb5_creds *creds" +.Fa "krb5_kdc_rep *ret_as_reply" +.Fc +.Ft krb5_error_code +.Fo krb5_get_in_tkt_with_password +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_addresses *addrs" +.Fa "const krb5_enctype *etypes" +.Fa "const krb5_preauthtype *pre_auth_types" +.Fa "const char *password" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *creds" +.Fa "krb5_kdc_rep *ret_as_reply" +.Fc +.Ft krb5_error_code +.Fo krb5_get_in_tkt_with_keytab +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_addresses *addrs" +.Fa "const krb5_enctype *etypes" +.Fa "const krb5_preauthtype *pre_auth_types" +.Fa "krb5_keytab keytab" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *creds" +.Fa "krb5_kdc_rep *ret_as_reply" +.Fc +.Ft krb5_error_code +.Fo krb5_get_in_tkt_with_skey +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_addresses *addrs" +.Fa "const krb5_enctype *etypes" +.Fa "const krb5_preauthtype *pre_auth_types" +.Fa "const krb5_keyblock *key" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *creds" +.Fa "krb5_kdc_rep *ret_as_reply" +.Fc +.Ft krb5_error_code +.Fo krb5_free_kdc_rep +.Fa "krb5_context context" +.Fa "krb5_kdc_rep *rep" +.Fc +.Ft krb5_error_code +.Fo krb5_password_key_proc +.Fa "krb5_context context" +.Fa "krb5_enctype type" +.Fa "krb5_salt salt" +.Fa "krb5_const_pointer keyseed" +.Fa "krb5_keyblock **key" +.Fc +.Sh DESCRIPTION +.Bf Em +All the functions in this manual page are deprecated in the MIT +implementation, and will soon be deprecated in Heimdal too, don't use them. +.Ef +.Pp +Getting initial credential ticket for a principal. +.Nm krb5_get_in_cred +is the function all other krb5_get_in function uses to fetch tickets. +The other krb5_get_in function are more specialized and therefor +somewhat easier to use. +.Pp +If your need is only to verify a user and password, consider using +.Xr krb5_verify_user 3 +instead, it have a much simpler interface. +.Pp +.Nm krb5_get_in_tkt +and +.Nm krb5_get_in_cred +fetches initial credential, queries after key using the +.Fa key_proc +argument. +The differences between the two function is that +.Nm krb5_get_in_tkt +stores the credential in a +.Li krb5_creds +while +.Nm krb5_get_in_cred +stores the credential in a +.Li krb5_ccache . +.Pp +.Nm krb5_get_in_tkt_with_password , +.Nm krb5_get_in_tkt_with_keytab , +and +.Nm krb5_get_in_tkt_with_skey +does the same work as +.Nm krb5_get_in_cred +but are more specialized. +.Pp +.Nm krb5_get_in_tkt_with_password +uses the clients password to authenticate. +If the password argument is +.Dv NULL +the user user queried with the default password query function. +.Pp +.Nm krb5_get_in_tkt_with_keytab +searches the given keytab for a service entry for the client principal. +If the keytab is +.Dv NULL +the default keytab is used. +.Pp +.Nm krb5_get_in_tkt_with_skey +uses a key to get the initial credential. +.Pp +There are some common arguments to the krb5_get_in functions, these are: +.Pp +.Fa options +are the +.Dv KDC_OPT +flags. +.Pp +.Fa etypes +is a +.Dv NULL +terminated array of encryption types that the client approves. +.Pp +.Fa addrs +a list of the addresses that the initial ticket. +If it is +.Dv NULL +the list will be generated by the library. +.Pp +.Fa pre_auth_types +a +.Dv NULL +terminated array of pre-authentication types. +If +.Fa pre_auth_types +is +.Dv NULL +the function will try without pre-authentication and return those +pre-authentication that the KDC returned. +.Pp +.Fa ret_as_reply +will (if not +.Dv NULL ) +be filled in with the response of the KDC and should be free with +.Fn krb5_free_kdc_rep . +.Pp +.Fa key_proc +is a pointer to a function that should return a key salted appropriately. +Using +.Dv NULL +will use the default password query function. +.Pp +.Fa decrypt_proc +Using +.Dv NULL +will use the default decryption function. +.Pp +.Fa decryptarg +will be passed to the decryption function +.Fa decrypt_proc . +.Pp +.Fa creds +creds should be filled in with the template for a credential that +should be requested. +The client and server elements of the creds structure must be filled in. +Upon return of the function it will be contain the content of the +requested credential +.Fa ( krb5_get_in_cred ) , +or it will be freed with +.Xr krb5_free_creds 3 +(all the other krb5_get_in functions). +.Pp +.Fa ccache +will store the credential in the credential cache +.Fa ccache . +The credential cache will not be initialized, thats up the the caller. +.Pp +.Nm krb5_password_key_proc +is a library function that is suitable using as the +.Fa krb5_key_proc +argument to +.Nm krb5_get_in_cred +or +.Nm krb5_get_in_tkt . +.Fa keyseed +should be a pointer to a +.Dv NUL +terminated string or +.Dv NULL . +.Nm krb5_password_key_proc +will query the user for the pass on the console if the password isn't +given as the argument +.Fa keyseed . +.Pp +.Fn krb5_free_kdc_rep +frees the content of +.Fa rep . +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_verify_user 3 , +.Xr krb5.conf 5 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_get_in_tkt_with_keytab.3 b/static/netbsd/man3/krb5_get_in_tkt_with_keytab.3 new file mode 100644 index 00000000..70549de5 --- /dev/null +++ b/static/netbsd/man3/krb5_get_in_tkt_with_keytab.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_in_tkt_with_keytab.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_in_tkt_with_password.3 b/static/netbsd/man3/krb5_get_in_tkt_with_password.3 new file mode 100644 index 00000000..1a891a7a --- /dev/null +++ b/static/netbsd/man3/krb5_get_in_tkt_with_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_in_tkt_with_password.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_in_tkt_with_skey.3 b/static/netbsd/man3/krb5_get_in_tkt_with_skey.3 new file mode 100644 index 00000000..d0da136b --- /dev/null +++ b/static/netbsd/man3/krb5_get_in_tkt_with_skey.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_in_tkt_with_skey.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_init_creds.3 b/static/netbsd/man3/krb5_get_init_creds.3 new file mode 100644 index 00000000..2f1078dc --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds.3 @@ -0,0 +1,405 @@ +.\" $NetBSD: krb5_get_init_creds.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2007 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd Sep 16, 2006 +.Dt KRB5_GET_INIT_CREDS 3 +.Os +.Sh NAME +.Nm krb5_get_init_creds , +.Nm krb5_get_init_creds_keytab , +.Nm krb5_get_init_creds_opt , +.Nm krb5_get_init_creds_opt_alloc , +.Nm krb5_get_init_creds_opt_free , +.Nm krb5_get_init_creds_opt_init , +.Nm krb5_get_init_creds_opt_set_address_list , +.Nm krb5_get_init_creds_opt_set_addressless , +.Nm krb5_get_init_creds_opt_set_anonymous , +.Nm krb5_get_init_creds_opt_set_default_flags , +.Nm krb5_get_init_creds_opt_set_etype_list , +.Nm krb5_get_init_creds_opt_set_forwardable , +.Nm krb5_get_init_creds_opt_set_pa_password , +.Nm krb5_get_init_creds_opt_set_paq_request , +.Nm krb5_get_init_creds_opt_set_preauth_list , +.Nm krb5_get_init_creds_opt_set_proxiable , +.Nm krb5_get_init_creds_opt_set_renew_life , +.Nm krb5_get_init_creds_opt_set_salt , +.Nm krb5_get_init_creds_opt_set_tkt_life , +.Nm krb5_get_init_creds_opt_set_canonicalize , +.Nm krb5_get_init_creds_opt_set_win2k , +.Nm krb5_get_init_creds_password , +.Nm krb5_prompt , +.Nm krb5_prompter_posix +.Nd Kerberos 5 initial authentication functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft krb5_get_init_creds_opt; +.Pp +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_alloc +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt **opt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_free +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_init +.Fa "krb5_get_init_creds_opt *opt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_address_list +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_addresses *addresses" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_addressless +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_boolean addressless" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_anonymous +.Fa "krb5_get_init_creds_opt *opt" +.Fa "int anonymous" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_change_password_prompt +.Fa "krb5_get_init_creds_opt *opt" +.Fa "int change_password_prompt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_default_flags +.Fa "krb5_context context" +.Fa "const char *appname" +.Fa "krb5_const_realm realm" +.Fa "krb5_get_init_creds_opt *opt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_etype_list +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_enctype *etype_list" +.Fa "int etype_list_length" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_forwardable +.Fa "krb5_get_init_creds_opt *opt" +.Fa "int forwardable" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_set_pa_password +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fa "const char *password" +.Fa "krb5_s2k_proc key_proc" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_set_paq_request +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_boolean req_pac" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_set_pkinit +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fa "const char *x509_anchors" +.Fa "int flags" +.Fa "char *password" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_preauth_list +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_preauthtype *preauth_list" +.Fa "int preauth_list_length" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_proxiable +.Fa "krb5_get_init_creds_opt *opt" +.Fa "int proxiable" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_renew_life +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_deltat renew_life" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_salt +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_data *salt" +.Fc +.Ft void +.Fo krb5_get_init_creds_opt_set_tkt_life +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_deltat tkt_life" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_set_canonicalize +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_boolean req" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_opt_set_win2k +.Fa "krb5_context context" +.Fa "krb5_get_init_creds_opt *opt" +.Fa "krb5_boolean req" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_principal client" +.Fa "krb5_prompter_fct prompter" +.Fa "void *prompter_data" +.Fa "krb5_deltat start_time" +.Fa "const char *in_tkt_service" +.Fa "krb5_get_init_creds_opt *options" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_password +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_principal client" +.Fa "const char *password" +.Fa "krb5_prompter_fct prompter" +.Fa "void *prompter_data" +.Fa "krb5_deltat start_time" +.Fa "const char *in_tkt_service" +.Fa "krb5_get_init_creds_opt *in_options" +.Fc +.Ft krb5_error_code +.Fo krb5_get_init_creds_keytab +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_principal client" +.Fa "krb5_keytab keytab" +.Fa "krb5_deltat start_time" +.Fa "const char *in_tkt_service" +.Fa "krb5_get_init_creds_opt *options" +.Fc +.Ft int +.Fo krb5_prompter_posix +.Fa "krb5_context context" +.Fa "void *data" +.Fa "const char *name" +.Fa "const char *banner" +.Fa "int num_prompts" +.Fa "krb5_prompt prompts[]" +.Fc +.Sh DESCRIPTION +Getting initial credential ticket for a principal. +That may include changing an expired password, and doing preauthentication. +This interface that replaces the deprecated +.Fa krb5_in_tkt +and +.Fa krb5_in_cred +functions. +.Pp +If you only want to verify a username and password, consider using +.Xr krb5_verify_user 3 +instead, since it also verifies that initial credentials with using a +keytab to make sure the response was from the KDC. +.Pp +First a +.Li krb5_get_init_creds_opt +structure is initialized +with +.Fn krb5_get_init_creds_opt_alloc +or +.Fn krb5_get_init_creds_opt_init . +.Fn krb5_get_init_creds_opt_alloc +allocates a extendible structures that needs to be freed with +.Fn krb5_get_init_creds_opt_free . +The structure may be modified by any of the +.Fn krb5_get_init_creds_opt_set +functions to change request parameters and authentication information. +.Pp +If the caller want to use the default options, +.Dv NULL +can be passed instead. +.Pp +The the actual request to the KDC is done by any of the +.Fn krb5_get_init_creds , +.Fn krb5_get_init_creds_password , +or +.Fn krb5_get_init_creds_keytab +functions. +.Fn krb5_get_init_creds +is the least specialized function and can, with the right in data, +behave like the latter two. +The latter two are there for compatibility with older releases and +they are slightly easier to use. +.Pp +.Li krb5_prompt +is a structure containing the following elements: +.Bd -literal +typedef struct { + const char *prompt; + int hidden; + krb5_data *reply; + krb5_prompt_type type +} krb5_prompt; +.Ed +.Pp +.Fa prompt +is the prompt that should shown to the user +If +.Fa hidden +is set, the prompter function shouldn't echo the output to the display +device. +.Fa reply +must be preallocated; it will not be allocated by the prompter +function. +Possible values for the +.Fa type +element are: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It KRB5_PROMPT_TYPE_PASSWORD +.It KRB5_PROMPT_TYPE_NEW_PASSWORD +.It KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN +.It KRB5_PROMPT_TYPE_PREAUTH +.It KRB5_PROMPT_TYPE_INFO +.El +.Pp +.Fn krb5_prompter_posix +is the default prompter function in a POSIX environment. +It matches the +.Fa krb5_prompter_fct +and can be used in the +.Fa krb5_get_init_creds +functions. +.Fn krb5_prompter_posix +doesn't require +.Fa prompter_data. +.Pp +If the +.Fa start_time +is zero, then the requested ticket will be valid +beginning immediately. +Otherwise, the +.Fa start_time +indicates how far in the future the ticket should be postdated. +.Pp +If the +.Fa in_tkt_service +name is +.Dv non-NULL , +that principal name will be +used as the server name for the initial ticket request. +The realm of the name specified will be ignored and will be set to the +realm of the client name. +If no in_tkt_service name is specified, +krbtgt/CLIENT-REALM@CLIENT-REALM will be used. +.Pp +For the rest of arguments, a configuration or library default will be +used if no value is specified in the options structure. +.Pp +.Fn krb5_get_init_creds_opt_set_address_list +sets the list of +.Fa addresses +that is should be stored in the ticket. +.Pp +.Fn krb5_get_init_creds_opt_set_addressless +controls if the ticket is requested with addresses or not, +.Fn krb5_get_init_creds_opt_set_address_list +overrides this option. +.Pp +.Fn krb5_get_init_creds_opt_set_anonymous +make the request anonymous if the +.Fa anonymous +parameter is non-zero. +.Pp +.Fn krb5_get_init_creds_opt_set_default_flags +sets the default flags using the configuration file. +.Pp +.Fn krb5_get_init_creds_opt_set_etype_list +set a list of enctypes that the client is willing to support in the +request. +.Pp +.Fn krb5_get_init_creds_opt_set_forwardable +request a forwardable ticket. +.Pp +.Fn krb5_get_init_creds_opt_set_pa_password +set the +.Fa password +and +.Fa key_proc +that is going to be used to get a new ticket. +.Fa password +or +.Fa key_proc +can be +.Dv NULL +if the caller wants to use the default values. +If the +.Fa password +is unset and needed, the user will be prompted for it. +.Pp +.Fn krb5_get_init_creds_opt_set_paq_request +sets the password that is going to be used to get a new ticket. +.Pp +.Fn krb5_get_init_creds_opt_set_preauth_list +sets the list of client-supported preauth types. +.Pp +.Fn krb5_get_init_creds_opt_set_proxiable +makes the request proxiable. +.Pp +.Fn krb5_get_init_creds_opt_set_renew_life +sets the requested renewable lifetime. +.Pp +.Fn krb5_get_init_creds_opt_set_salt +sets the salt that is going to be used in the request. +.Pp +.Fn krb5_get_init_creds_opt_set_tkt_life +sets requested ticket lifetime. +.Pp +.Fn krb5_get_init_creds_opt_set_canonicalize +requests that the KDC canonicalize the client principal if possible. +.Pp +.Fn krb5_get_init_creds_opt_set_win2k +turns on compatibility with Windows 2000. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_creds 3 , +.Xr krb5_verify_user 3 , +.Xr krb5.conf 5 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_get_init_creds_keyblock.3 b/static/netbsd/man3/krb5_get_init_creds_keyblock.3 new file mode 100644 index 00000000..b6a3162b --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_keyblock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_keyblock.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_keytab.3 b/static/netbsd/man3/krb5_get_init_creds_keytab.3 new file mode 100644 index 00000000..ab061a02 --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_keytab.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_keytab.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_opt_alloc.3 b/static/netbsd/man3/krb5_get_init_creds_opt_alloc.3 new file mode 100644 index 00000000..47ad50df --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_opt_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_opt_alloc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_opt_free.3 b/static/netbsd/man3/krb5_get_init_creds_opt_free.3 new file mode 100644 index 00000000..e4a6008c --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_opt_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_opt_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_opt_get_error.3 b/static/netbsd/man3/krb5_get_init_creds_opt_get_error.3 new file mode 100644 index 00000000..ada18fb2 --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_opt_get_error.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_opt_get_error.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_opt_init.3 b/static/netbsd/man3/krb5_get_init_creds_opt_init.3 new file mode 100644 index 00000000..ac9d1368 --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_opt_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_opt_init.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_get_init_creds_password.3 b/static/netbsd/man3/krb5_get_init_creds_password.3 new file mode 100644 index 00000000..b3e552fb --- /dev/null +++ b/static/netbsd/man3/krb5_get_init_creds_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_init_creds_password.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_get_kdc_sec_offset.3 b/static/netbsd/man3/krb5_get_kdc_sec_offset.3 new file mode 100644 index 00000000..3e2d3f0f --- /dev/null +++ b/static/netbsd/man3/krb5_get_kdc_sec_offset.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_kdc_sec_offset.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_krbhst.3 b/static/netbsd/man3/krb5_get_krbhst.3 new file mode 100644 index 00000000..ce029738 --- /dev/null +++ b/static/netbsd/man3/krb5_get_krbhst.3 @@ -0,0 +1,88 @@ +.\" $NetBSD: krb5_get_krbhst.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2001 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd April 24, 2005 +.Dt KRB5_GET_KRBHST 3 +.Os +.Sh NAME +.Nm krb5_get_krbhst , +.Nm krb5_get_krb_admin_hst , +.Nm krb5_get_krb_changepw_hst , +.Nm krb5_get_krb524hst , +.Nm krb5_free_krbhst +.Nd lookup Kerberos KDC hosts +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fn krb5_get_krbhst "krb5_context context" "const krb5_realm *realm" "char ***hostlist" +.Ft krb5_error_code +.Fn krb5_get_krb_admin_hst "krb5_context context" "const krb5_realm *realm" "char ***hostlist" +.Ft krb5_error_code +.Fn krb5_get_krb_changepw_hst "krb5_context context" "const krb5_realm *realm" "char ***hostlist" +.Ft krb5_error_code +.Fn krb5_get_krb524hst "krb5_context context" "const krb5_realm *realm" "char ***hostlist" +.Ft krb5_error_code +.Fn krb5_free_krbhst "krb5_context context" "char **hostlist" +.Sh DESCRIPTION +These functions implement the old API to get a list of Kerberos hosts, +and are thus similar to the +.Fn krb5_krbhst_init +functions. However, since these functions returns +.Em all +hosts in one go, they potentially have to do more lookups than +necessary. These functions remain for compatibility reasons. +.Pp +After a call to one of these functions, +.Fa hostlist +is a +.Dv NULL +terminated list of strings, pointing to the requested Kerberos hosts. These should be freed with +.Fn krb5_free_krbhst +when done with. +.Sh EXAMPLES +The following code will print the KDCs of the realm +.Dq MY.REALM . +.Bd -literal -offset indent +char **hosts, **p; +krb5_get_krbhst(context, "MY.REALM", &hosts); +for(p = hosts; *p; p++) + printf("%s\\n", *p); +krb5_free_krbhst(context, hosts); +.Ed +.\" .Sh BUGS +.Sh SEE ALSO +.Xr krb5_krbhst_init 3 diff --git a/static/netbsd/man3/krb5_get_max_time_skew.3 b/static/netbsd/man3/krb5_get_max_time_skew.3 new file mode 100644 index 00000000..77acf917 --- /dev/null +++ b/static/netbsd/man3/krb5_get_max_time_skew.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_max_time_skew.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_use_admin_kdc.3 b/static/netbsd/man3/krb5_get_use_admin_kdc.3 new file mode 100644 index 00000000..16d40892 --- /dev/null +++ b/static/netbsd/man3/krb5_get_use_admin_kdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_use_admin_kdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_get_validated_creds.3 b/static/netbsd/man3/krb5_get_validated_creds.3 new file mode 100644 index 00000000..cc284d39 --- /dev/null +++ b/static/netbsd/man3/krb5_get_validated_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_validated_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_get_warn_dest.3 b/static/netbsd/man3/krb5_get_warn_dest.3 new file mode 100644 index 00000000..53ac6fa7 --- /dev/null +++ b/static/netbsd/man3/krb5_get_warn_dest.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_get_warn_dest.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_getportbyname.3 b/static/netbsd/man3/krb5_getportbyname.3 new file mode 100644 index 00000000..b6035889 --- /dev/null +++ b/static/netbsd/man3/krb5_getportbyname.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: krb5_getportbyname.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd August 15, 2004 +.Dt NAME 3 +.Os +.Sh NAME +.Nm krb5_getportbyname +.Nd get port number by name +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft int +.Fo krb5_getportbyname +.Fa "krb5_context context" +.Fa "const char *service" +.Fa "const char *proto" +.Fa "int default_port" +.Fc +.Sh DESCRIPTION +.Fn krb5_getportbyname +gets the port number for +.Fa service / +.Fa proto +pair from the global service table for and returns it in network order. +If it isn't found in the global table, the +.Fa default_port +(given in host order) +is returned. +.Sh EXAMPLE +.Bd -literal +int port = krb5_getportbyname(context, "kerberos", "tcp", 88); +.Ed +.\" .Sh BUGS +.Sh SEE ALSO +.Xr krb5 3 diff --git a/static/netbsd/man3/krb5_h_addr2addr.3 b/static/netbsd/man3/krb5_h_addr2addr.3 new file mode 100644 index 00000000..8af9e696 --- /dev/null +++ b/static/netbsd/man3/krb5_h_addr2addr.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_h_addr2addr.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_h_addr2sockaddr.3 b/static/netbsd/man3/krb5_h_addr2sockaddr.3 new file mode 100644 index 00000000..07d94f39 --- /dev/null +++ b/static/netbsd/man3/krb5_h_addr2sockaddr.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_h_addr2sockaddr.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_h_errno_to_heim_errno.3 b/static/netbsd/man3/krb5_h_errno_to_heim_errno.3 new file mode 100644 index 00000000..a3061ad9 --- /dev/null +++ b/static/netbsd/man3/krb5_h_errno_to_heim_errno.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_h_errno_to_heim_errno.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_init_context.3 b/static/netbsd/man3/krb5_init_context.3 new file mode 100644 index 00000000..5b012dc1 --- /dev/null +++ b/static/netbsd/man3/krb5_init_context.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_context.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_init_creds_free.3 b/static/netbsd/man3/krb5_init_creds_free.3 new file mode 100644 index 00000000..110c4576 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_get.3 b/static/netbsd/man3/krb5_init_creds_get.3 new file mode 100644 index 00000000..12d05e83 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_get_error.3 b/static/netbsd/man3/krb5_init_creds_get_error.3 new file mode 100644 index 00000000..028aad6c --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_get_error.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_get_error.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_init.3 b/static/netbsd/man3/krb5_init_creds_init.3 new file mode 100644 index 00000000..3c398b98 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_init.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_intro.3 b/static/netbsd/man3/krb5_init_creds_intro.3 new file mode 100644 index 00000000..0970f477 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_intro.3 @@ -0,0 +1,11 @@ +.\" $NetBSD: krb5_init_creds_intro.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_init_creds_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_init_creds_intro \- The initial credential handing functions + +.SH "Initial credential" +.PP +Functions to get initial credentials: \fBHeimdal Kerberos 5 credential handing functions\fP \&. diff --git a/static/netbsd/man3/krb5_init_creds_set_keytab.3 b/static/netbsd/man3/krb5_init_creds_set_keytab.3 new file mode 100644 index 00000000..1e696ff0 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_set_keytab.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_set_keytab.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_set_password.3 b/static/netbsd/man3/krb5_init_creds_set_password.3 new file mode 100644 index 00000000..fc706bb8 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_set_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_set_password.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_set_service.3 b/static/netbsd/man3/krb5_init_creds_set_service.3 new file mode 100644 index 00000000..bfb4fa25 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_set_service.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_set_service.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_creds_step.3 b/static/netbsd/man3/krb5_init_creds_step.3 new file mode 100644 index 00000000..1c24b3d8 --- /dev/null +++ b/static/netbsd/man3/krb5_init_creds_step.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_creds_step.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_credential.3 diff --git a/static/netbsd/man3/krb5_init_ets.3 b/static/netbsd/man3/krb5_init_ets.3 new file mode 100644 index 00000000..a41f7eea --- /dev/null +++ b/static/netbsd/man3/krb5_init_ets.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_init_ets.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_introduction.3 b/static/netbsd/man3/krb5_introduction.3 new file mode 100644 index 00000000..f3234efe --- /dev/null +++ b/static/netbsd/man3/krb5_introduction.3 @@ -0,0 +1,262 @@ +.\" $NetBSD: krb5_introduction.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_introduction" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_introduction \- Introduction to the Kerberos 5 API + +.SH "Kerberos 5 API Overview" +.PP +All functions are documented in manual pages\&. This section tries to give an overview of the major components used in Kerberos library, and point to where to look for a specific function\&. +.SS "Kerberos context" +A kerberos context (krb5_context) holds all per thread state\&. All global variables that are context specific are stored in this structure, including default encryption types, credential cache (for example, a ticket file), and default realms\&. +.PP +The internals of the structure should never be accessed directly, functions exist for extracting information\&. +.PP +See the manual page for \fBkrb5_init_context()\fP how to create a context and module \fBHeimdal Kerberos 5 library\fP for more information about the functions\&. +.SS "Kerberos authentication context" +Kerberos authentication context (krb5_auth_context) holds all context related to an authenticated connection, in a similar way to the kerberos context that holds the context for the thread or process\&. +.PP +The krb5_auth_context is used by various functions that are directly related to authentication between the server/client\&. Example of data that this structure contains are various flags, addresses of client and server, port numbers, keyblocks (and subkeys), sequence numbers, replay cache, and checksum types\&. +.SS "Kerberos principal" +The Kerberos principal is the structure that identifies a user or service in Kerberos\&. The structure that holds the principal is the krb5_principal\&. There are function to extract the realm and elements of the principal, but most applications have no reason to inspect the content of the structure\&. +.PP +The are several ways to create a principal (with different degree of portability), and one way to free it\&. +.PP +See also the page \fBThe principal handing functions\&.\fP for more information and also module \fBHeimdal Kerberos 5 principal functions\fP\&. +.SS "Credential cache" +A credential cache holds the tickets for a user\&. A given user can have several credential caches, one for each realm where the user have the initial tickets (the first krbtgt)\&. +.PP +The credential cache data can be stored internally in different way, each of them for different proposes\&. File credential (FILE) caches and processes based (KCM) caches are for permanent storage\&. While memory caches (MEMORY) are local caches to the local process\&. +.PP +Caches are opened with \fBkrb5_cc_resolve()\fP or created with \fBkrb5_cc_new_unique()\fP\&. +.PP +If the cache needs to be opened again (using \fBkrb5_cc_resolve()\fP) \fBkrb5_cc_close()\fP will close the handle, but not the remove the cache\&. \fBkrb5_cc_destroy()\fP will zero out the cache, remove the cache so it can no longer be referenced\&. +.PP +See also \fBThe credential cache functions\fP and \fBHeimdal Kerberos 5 credential cache functions\fP \&. +.SS "Kerberos errors" +Kerberos errors are based on the com_err library\&. All error codes are 32-bit signed numbers, the first 24 bits define what subsystem the error originates from, and last 8 bits are 255 error codes within the library\&. Each error code have fixed string associated with it\&. For example, the error-code -1765328383 have the symbolic name KRB5KDC_ERR_NAME_EXP, and associated error string ``Client's entry in database has expired''\&. +.PP +This is a great improvement compared to just getting one of the unix error-codes back\&. However, Heimdal have an extention to pass back customised errors messages\&. Instead of getting \fCKey table entry not found'', the user might back\fPfailed to find host/host\&.example\&.com@EXAMLE\&.COM(kvno 3) in keytab /etc/krb5\&.keytab (des-cbc-crc)''\&. This improves the chance that the user find the cause of the error so you should use the customised error message whenever it's available\&. +.PP +See also module \fBHeimdal Kerberos 5 error reporting functions\fP \&. +.SS "Keytab management" +A keytab is a storage for locally stored keys\&. Heimdal includes keytab support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, and for storing keys in memory\&. +.PP +Keytabs are used for servers and long-running services\&. +.PP +See also \fBThe keytab handing functions\fP and \fBHeimdal Kerberos 5 keytab handling functions\fP \&. +.SS "Kerberos crypto" +Heimdal includes a implementation of the Kerberos crypto framework, all crypto operations\&. To create a crypto context call \fBkrb5_crypto_init()\fP\&. +.PP +See also module \fBHeimdal Kerberos 5 cryptography functions\fP \&. +.SH "Walkthrough of a sample Kerberos 5 client" +.PP +This example contains parts of a sample TCP Kerberos 5 clients, if you want a real working client, please look in appl/test directory in the Heimdal distribution\&. +.PP +All Kerberos error-codes that are returned from kerberos functions in this program are passed to krb5_err, that will print a descriptive text of the error code and exit\&. Graphical programs can convert error-code to a human readable error-string with the \fBkrb5_get_error_message()\fP function\&. +.PP +Note that you should not use any Kerberos function before \fBkrb5_init_context()\fP have completed successfully\&. That is the reason err() is used when \fBkrb5_init_context()\fP fails\&. +.PP +First the client needs to call krb5_init_context to initialise the Kerberos 5 library\&. This is only needed once per thread in the program\&. If the function returns a non-zero value it indicates that either the Kerberos implementation is failing or it's disabled on this host\&. +.PP +.PP +.nf +#include + +int +main(int argc, char **argv) +{ + krb5_context context; + + if (krb5_init_context(&context)) + errx (1, "krb5_context"); +.fi +.PP +.PP +Now the client wants to connect to the host at the other end\&. The preferred way of doing this is using getaddrinfo (for operating system that have this function implemented), since getaddrinfo is neutral to the address type and can use any protocol that is available\&. +.PP +.PP +.nf +struct addrinfo *ai, *a; +struct addrinfo hints; +int error; + +memset (&hints, 0, sizeof(hints)); +hints\&.ai_socktype = SOCK_STREAM; +hints\&.ai_protocol = IPPROTO_TCP; + +error = getaddrinfo (hostname, "pop3", &hints, &ai); +if (error) + errx (1, "%s: %s", hostname, gai_strerror(error)); + +for (a = ai; a != NULL; a = a->ai_next) { + int s; + + s = socket (a->ai_family, a->ai_socktype, a->ai_protocol); + if (s < 0) + continue; + if (connect (s, a->ai_addr, a->ai_addrlen) < 0) { + warn ("connect(%s)", hostname); + close (s); + continue; + } + freeaddrinfo (ai); + ai = NULL; +} +if (ai) { + freeaddrinfo (ai); + errx ("failed to contact %s", hostname); +} +.fi +.PP +.PP +Before authenticating, an authentication context needs to be created\&. This context keeps all information for one (to be) authenticated connection (see krb5_auth_context)\&. +.PP +.PP +.nf +status = krb5_auth_con_init (context, &auth_context); +if (status) + krb5_err (context, 1, status, "krb5_auth_con_init"); +.fi +.PP +.PP +For setting the address in the authentication there is a help function krb5_auth_con_setaddrs_from_fd() that does everything that is needed when given a connected file descriptor to the socket\&. +.PP +.PP +.nf +status = krb5_auth_con_setaddrs_from_fd (context, + auth_context, + &sock); +if (status) + krb5_err (context, 1, status, + "krb5_auth_con_setaddrs_from_fd"); +.fi +.PP +.PP +The next step is to build a server principal for the service we want to connect to\&. (See also \fBkrb5_sname_to_principal()\fP\&.) +.PP +.PP +.nf +status = krb5_sname_to_principal (context, + hostname, + service, + KRB5_NT_SRV_HST, + &server); +if (status) + krb5_err (context, 1, status, "krb5_sname_to_principal"); +.fi +.PP +.PP +The client principal is not passed to krb5_sendauth() function, this causes the krb5_sendauth() function to try to figure it out itself\&. +.PP +The server program is using the function krb5_recvauth() to receive the Kerberos 5 authenticator\&. +.PP +In this case, mutual authentication will be tried\&. That means that the server will authenticate to the client\&. Using mutual authentication is required to avoid man-in-the-middle attacks, since it enables the user to verify that they are talking to the right server (a server that knows the key)\&. +.PP +If you are using a non-blocking socket you will need to do all work of krb5_sendauth() yourself\&. Basically you need to send over the authenticator from krb5_mk_req() and, in case of mutual authentication, verifying the result from the server with krb5_rd_rep()\&. +.PP +.PP +.nf +status = krb5_sendauth (context, + &auth_context, + &sock, + VERSION, + NULL, + server, + AP_OPTS_MUTUAL_REQUIRED, + NULL, + NULL, + NULL, + NULL, + NULL, + NULL); +if (status) + krb5_err (context, 1, status, "krb5_sendauth"); +.fi +.PP +.PP +Once authentication has been performed, it is time to send some data\&. First we create a krb5_data structure, then we sign it with krb5_mk_safe() using the auth_context that contains the session-key that was exchanged in the krb5_sendauth()/krb5_recvauth() authentication sequence\&. +.PP +.PP +.nf +data\&.data = "hej"; +data\&.length = 3; + +krb5_data_zero (&packet); + +status = krb5_mk_safe (context, + auth_context, + &data, + &packet, + NULL); +if (status) + krb5_err (context, 1, status, "krb5_mk_safe"); +.fi +.PP +.PP +And send it over the network\&. +.PP +.PP +.nf +len = packet\&.length; +net_len = htonl(len); + +if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); +if (krb5_net_write (context, &sock, packet\&.data, len) != len) + err (1, "krb5_net_write"); +.fi +.PP +.PP +To send encrypted (and signed) data krb5_mk_priv() should be used instead\&. krb5_mk_priv() works the same way as krb5_mk_safe(), with the exception that it encrypts the data in addition to signing it\&. +.PP +.PP +.nf +data\&.data = "hemligt"; +data\&.length = 7; + +krb5_data_free (&packet); + +status = krb5_mk_priv (context, + auth_context, + &data, + &packet, + NULL); +if (status) + krb5_err (context, 1, status, "krb5_mk_priv"); +.fi +.PP +.PP +And send it over the network\&. +.PP +.PP +.nf +len = packet\&.length; +net_len = htonl(len); + +if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); +if (krb5_net_write (context, &sock, packet\&.data, len) != len) + err (1, "krb5_net_write"); +.fi +.PP +.PP +The server is using krb5_rd_safe() and krb5_rd_priv() to verify the signature and decrypt the packet\&. +.SH "Validating a password in an application" +.PP +See the manual page for krb5_verify_user()\&. +.SH "API differences to MIT Kerberos" +.PP +This section is somewhat disorganised, but so far there is no overall structure to the differences, though some of the have their root in that Heimdal uses an ASN\&.1 compiler and MIT doesn't\&. +.SS "Principal and realms" +Heimdal stores the realm as a krb5_realm, that is a char *\&. MIT Kerberos uses a krb5_data to store a realm\&. +.PP +In Heimdal krb5_principal doesn't contain the component name_type; it's instead stored in component name\&.name_type\&. To get and set the nametype in Heimdal, use \fBkrb5_principal_get_type()\fP and \fBkrb5_principal_set_type()\fP\&. +.PP +For more information about principal and realms, see krb5_principal\&. +.SS "Error messages" +To get the error string, Heimdal uses \fBkrb5_get_error_message()\fP\&. This is to return custom error messages (like \fCCan't find host/datan\&.example\&.com\\@CODE\&.COM in /etc/krb5\&.conf\&.'' instead of a\fPKey table entry not found'' that error_message returns\&. +.PP +Heimdal uses a threadsafe(r) version of the com_err interface; the global com_err table isn't initialised\&. Then error_message returns quite a boring error string (just the error code itself)\&. diff --git a/static/netbsd/man3/krb5_is_config_principal.3 b/static/netbsd/man3/krb5_is_config_principal.3 new file mode 100644 index 00000000..80d54083 --- /dev/null +++ b/static/netbsd/man3/krb5_is_config_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_is_config_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_is_enctype_weak.3 b/static/netbsd/man3/krb5_is_enctype_weak.3 new file mode 100644 index 00000000..9b5fc7b6 --- /dev/null +++ b/static/netbsd/man3/krb5_is_enctype_weak.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_is_enctype_weak.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_is_thread_safe.3 b/static/netbsd/man3/krb5_is_thread_safe.3 new file mode 100644 index 00000000..26100ab8 --- /dev/null +++ b/static/netbsd/man3/krb5_is_thread_safe.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_is_thread_safe.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_kerberos_enctypes.3 b/static/netbsd/man3/krb5_kerberos_enctypes.3 new file mode 100644 index 00000000..bbad7a96 --- /dev/null +++ b/static/netbsd/man3/krb5_kerberos_enctypes.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kerberos_enctypes.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_keyblock_get_enctype.3 b/static/netbsd/man3/krb5_keyblock_get_enctype.3 new file mode 100644 index 00000000..d231c8b2 --- /dev/null +++ b/static/netbsd/man3/krb5_keyblock_get_enctype.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keyblock_get_enctype.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_keyblock_init.3 b/static/netbsd/man3/krb5_keyblock_init.3 new file mode 100644 index 00000000..c89a9a0a --- /dev/null +++ b/static/netbsd/man3/krb5_keyblock_init.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keyblock_init.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_keyblock_zero.3 b/static/netbsd/man3/krb5_keyblock_zero.3 new file mode 100644 index 00000000..339c9190 --- /dev/null +++ b/static/netbsd/man3/krb5_keyblock_zero.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keyblock_zero.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_keytab.3 b/static/netbsd/man3/krb5_keytab.3 new file mode 100644 index 00000000..d1fa1d5b --- /dev/null +++ b/static/netbsd/man3/krb5_keytab.3 @@ -0,0 +1,473 @@ +.\" $NetBSD: krb5_keytab.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_keytab" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_keytab \- Heimdal Kerberos 5 keytab handling functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_register\fP (krb5_context context, const krb5_kt_ops *ops)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_resolve\fP (krb5_context context, const char *name, krb5_keytab *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_default_name\fP (krb5_context context, char *name, size_t namesize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_default_modify_name\fP (krb5_context context, char *name, size_t namesize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_default\fP (krb5_context context, krb5_keytab *id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_read_service_key\fP (krb5_context context, krb5_pointer keyprocarg, krb5_principal principal, krb5_kvno vno, krb5_enctype enctype, krb5_keyblock **key)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_get_type\fP (krb5_context context, krb5_keytab keytab, char *prefix, size_t prefixsize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_get_name\fP (krb5_context context, krb5_keytab keytab, char *name, size_t namesize)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_get_full_name\fP (krb5_context context, krb5_keytab keytab, char **str)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_close\fP (krb5_context context, krb5_keytab id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_destroy\fP (krb5_context context, krb5_keytab id)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_kt_compare\fP (krb5_context context, krb5_keytab_entry *entry, krb5_const_principal principal, krb5_kvno vno, krb5_enctype enctype)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_get_entry\fP (krb5_context context, krb5_keytab id, krb5_const_principal principal, krb5_kvno kvno, krb5_enctype enctype, krb5_keytab_entry *entry)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_copy_entry_contents\fP (krb5_context context, const krb5_keytab_entry *in, krb5_keytab_entry *out)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_free_entry\fP (krb5_context context, krb5_keytab_entry *entry)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_start_seq_get\fP (krb5_context context, krb5_keytab id, krb5_kt_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_next_entry\fP (krb5_context context, krb5_keytab id, krb5_keytab_entry *entry, krb5_kt_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_end_seq_get\fP (krb5_context context, krb5_keytab id, krb5_kt_cursor *cursor)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_add_entry\fP (krb5_context context, krb5_keytab id, krb5_keytab_entry *entry)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_remove_entry\fP (krb5_context context, krb5_keytab id, krb5_keytab_entry *entry)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_kt_have_content\fP (krb5_context context, krb5_keytab id)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_add_entry (krb5_context context, krb5_keytab id, krb5_keytab_entry * entry)" +Add the entry in `entry' to the keytab `id'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIentry\fP the entry to add +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_close (krb5_context context, krb5_keytab id)" +Finish using the keytab in `id'\&. All resources will be released, even on errors\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP keytab to close\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_kt_compare (krb5_context context, krb5_keytab_entry * entry, krb5_const_principal principal, krb5_kvno vno, krb5_enctype enctype)" +Compare `entry' against `principal, vno, enctype'\&. Any of `principal, vno, enctype' might be 0 which acts as a wildcard\&. Return TRUE if they compare the same, FALSE otherwise\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIentry\fP an entry to match with\&. +.br +\fIprincipal\fP principal to match, NULL matches all principals\&. +.br +\fIvno\fP key version to match, 0 matches all key version numbers\&. +.br +\fIenctype\fP encryption type to match, 0 matches all encryption types\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return TRUE or match, FALSE if not matched\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_copy_entry_contents (krb5_context context, const krb5_keytab_entry * in, krb5_keytab_entry * out)" +Copy the contents of `in' into `out'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIin\fP the keytab entry to copy\&. +.br +\fIout\fP the copy of the keytab entry, free with \fBkrb5_kt_free_entry()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default (krb5_context context, krb5_keytab * id)" +Set `id' to the default keytab\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP the new default keytab\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default_modify_name (krb5_context context, char * name, size_t namesize)" +Copy the name of the default modify keytab into `name'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIname\fP buffer where the name will be written +.br +\fInamesize\fP length of name +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_default_name (krb5_context context, char * name, size_t namesize)" +copy the name of the default keytab into `name'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIname\fP buffer where the name will be written +.br +\fInamesize\fP length of name +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_destroy (krb5_context context, krb5_keytab id)" +Destroy (remove) the keytab in `id'\&. All resources will be released, even on errors, does the equvalment of \fBkrb5_kt_close()\fP on the resources\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP keytab to destroy\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_end_seq_get (krb5_context context, krb5_keytab id, krb5_kt_cursor * cursor)" +Release all resources associated with `cursor'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIcursor\fP the cursor to free\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_free_entry (krb5_context context, krb5_keytab_entry * entry)" +Free the contents of `entry'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIentry\fP the entry to free +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_entry (krb5_context context, krb5_keytab id, krb5_const_principal principal, krb5_kvno kvno, krb5_enctype enctype, krb5_keytab_entry * entry)" +Retrieve the keytab entry for `principal, kvno, enctype' into `entry' from the keytab `id'\&. Matching is done like \fBkrb5_kt_compare()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIprincipal\fP principal to match, NULL matches all principals\&. +.br +\fIkvno\fP key version to match, 0 matches all key version numbers\&. +.br +\fIenctype\fP encryption type to match, 0 matches all encryption types\&. +.br +\fIentry\fP the returned entry, free with \fBkrb5_kt_free_entry()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_full_name (krb5_context context, krb5_keytab keytab, char ** str)" +Retrieve the full name of the keytab `keytab' and store the name in `str'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIkeytab\fP keytab to get name for\&. +.br +\fIstr\fP the name of the keytab name, usee krb5_xfree() to free the string\&. On error, *str is set to NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_name (krb5_context context, krb5_keytab keytab, char * name, size_t namesize)" +Retrieve the name of the keytab `keytab' into `name', `namesize' +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIkeytab\fP the keytab to get the name for\&. +.br +\fIname\fP name buffer\&. +.br +\fInamesize\fP size of name buffer\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_get_type (krb5_context context, krb5_keytab keytab, char * prefix, size_t prefixsize)" +Return the type of the `keytab' in the string \fCprefix of length \fPprefixsize'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIkeytab\fP the keytab to get the prefix for +.br +\fIprefix\fP prefix buffer +.br +\fIprefixsize\fP length of prefix buffer +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_have_content (krb5_context context, krb5_keytab id)" +Return true if the keytab exists and have entries +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_next_entry (krb5_context context, krb5_keytab id, krb5_keytab_entry * entry, krb5_kt_cursor * cursor)" +Get the next entry from keytab, advance the cursor\&. On last entry the function will return KRB5_KT_END\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIentry\fP the returned entry, free with \fBkrb5_kt_free_entry()\fP\&. +.br +\fIcursor\fP the cursor of the iteration\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_read_service_key (krb5_context context, krb5_pointer keyprocarg, krb5_principal principal, krb5_kvno vno, krb5_enctype enctype, krb5_keyblock ** key)" +Read the key identified by `(principal, vno, enctype)' from the keytab in `keyprocarg' (the default if == NULL) into `*key'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIkeyprocarg\fP +.br +\fIprincipal\fP +.br +\fIvno\fP +.br +\fIenctype\fP +.br +\fIkey\fP +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_register (krb5_context context, const krb5_kt_ops * ops)" +Register a new keytab backend\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIops\fP a backend to register\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_remove_entry (krb5_context context, krb5_keytab id, krb5_keytab_entry * entry)" +Remove an entry from the keytab, matching is done using \fBkrb5_kt_compare()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIentry\fP the entry to remove +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_resolve (krb5_context context, const char * name, krb5_keytab * id)" +Resolve the keytab name (of the form `type:residual') in `name' into a keytab in `id'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIname\fP name to resolve +.br +\fIid\fP resulting keytab, free with \fBkrb5_kt_close()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_kt_start_seq_get (krb5_context context, krb5_keytab id, krb5_kt_cursor * cursor)" +Set `cursor' to point at the beginning of `id'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context\&. +.br +\fIid\fP a keytab\&. +.br +\fIcursor\fP a newly allocated cursor, free with \fBkrb5_kt_end_seq_get()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_keytab_intro.3 b/static/netbsd/man3/krb5_keytab_intro.3 new file mode 100644 index 00000000..fef41880 --- /dev/null +++ b/static/netbsd/man3/krb5_keytab_intro.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: krb5_keytab_intro.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_keytab_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_keytab_intro \- The keytab handing functions + +.SH "Kerberos Keytabs" +.PP +See the library functions here: \fBHeimdal Kerberos 5 keytab handling functions\fP +.PP +Keytabs are long term key storage for servers, their equvalment of password files\&. +.PP +Normally the only function that useful for server are to specify what keytab to use to other core functions like krb5_rd_req() \fBkrb5_kt_resolve()\fP, and \fBkrb5_kt_close()\fP\&. +.SS "Keytab names" +A keytab name is on the form type:residual\&. The residual part is specific to each keytab-type\&. +.PP +When a keytab-name is resolved, the type is matched with an internal list of keytab types\&. If there is no matching keytab type, the default keytab is used\&. The current default type is FILE\&. +.PP +The default value can be changed in the configuration file /etc/krb5\&.conf by setting the variable [defaults]default_keytab_name\&. +.PP +The keytab types that are implemented in Heimdal are: +.IP "\(bu" 2 +file store the keytab in a file, the type's name is FILE \&. The residual part is a filename\&. For compatibility with other Kerberos implemtation WRFILE and JAVA14 is also accepted\&. WRFILE has the same format as FILE\&. JAVA14 have a format that is compatible with older versions of MIT kerberos and SUN's Java based installation\&. They store a truncted kvno, so when the knvo excess 255, they are truncted in this format\&. +.IP "\(bu" 2 +keytab store the keytab in a AFS keyfile (usually /usr/afs/etc/KeyFile ), the type's name is AFSKEYFILE\&. The residual part is a filename\&. +.IP "\(bu" 2 +memory The keytab is stored in a memory segment\&. This allows sensitive and/or temporary data not to be stored on disk\&. The type's name is MEMORY\&. Each MEMORY keytab is referenced counted by and opened by the residual name, so two handles can point to the same memory area\&. When the last user closes using \fBkrb5_kt_close()\fP the keytab, the keys in they keytab is memset() to zero and freed and can no longer be looked up by name\&. +.PP +.SS "Keytab example" +This is a minimalistic version of ktutil\&. +.PP +.PP +.nf +int +main (int argc, char **argv) +{ + krb5_context context; + krb5_keytab keytab; + krb5_kt_cursor cursor; + krb5_keytab_entry entry; + krb5_error_code ret; + char *principal; + + if (krb5_init_context (&context) != 0) + errx(1, "krb5_context"); + + ret = krb5_kt_default (context, &keytab); + if (ret) + krb5_err(context, 1, ret, "krb5_kt_default"); + + ret = krb5_kt_start_seq_get(context, keytab, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_kt_start_seq_get"); + while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){ + krb5_unparse_name(context, entry\&.principal, &principal); + printf("principal: %s\n", principal); + free(principal); + krb5_kt_free_entry(context, &entry); + } + ret = krb5_kt_end_seq_get(context, keytab, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_kt_end_seq_get"); + ret = krb5_kt_close(context, keytab); + if (ret) + krb5_err(context, 1, ret, "krb5_kt_close"); + krb5_free_context(context); + return 0; +} +.fi +.PP + diff --git a/static/netbsd/man3/krb5_keytab_key_proc.3 b/static/netbsd/man3/krb5_keytab_key_proc.3 new file mode 100644 index 00000000..02a62bb4 --- /dev/null +++ b/static/netbsd/man3/krb5_keytab_key_proc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keytab_key_proc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_keytype_to_enctypes.3 b/static/netbsd/man3/krb5_keytype_to_enctypes.3 new file mode 100644 index 00000000..24b22dcf --- /dev/null +++ b/static/netbsd/man3/krb5_keytype_to_enctypes.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keytype_to_enctypes.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_keytype_to_enctypes_default.3 b/static/netbsd/man3/krb5_keytype_to_enctypes_default.3 new file mode 100644 index 00000000..5bd5e618 --- /dev/null +++ b/static/netbsd/man3/krb5_keytype_to_enctypes_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keytype_to_enctypes_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_keytype_to_string.3 b/static/netbsd/man3/krb5_keytype_to_string.3 new file mode 100644 index 00000000..89d4b8ef --- /dev/null +++ b/static/netbsd/man3/krb5_keytype_to_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_keytype_to_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_krbhst_get_addrinfo.3 b/static/netbsd/man3/krb5_krbhst_get_addrinfo.3 new file mode 100644 index 00000000..513cf96c --- /dev/null +++ b/static/netbsd/man3/krb5_krbhst_get_addrinfo.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_krbhst_get_addrinfo.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_krbhst_init.3 b/static/netbsd/man3/krb5_krbhst_init.3 new file mode 100644 index 00000000..82b0d25f --- /dev/null +++ b/static/netbsd/man3/krb5_krbhst_init.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: krb5_krbhst_init.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2001-2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 10, 2005 +.Dt KRB5_KRBHST_INIT 3 +.Os +.Sh NAME +.Nm krb5_krbhst_init , +.Nm krb5_krbhst_init_flags , +.Nm krb5_krbhst_next , +.Nm krb5_krbhst_next_as_string , +.Nm krb5_krbhst_reset , +.Nm krb5_krbhst_free , +.Nm krb5_krbhst_format_string , +.Nm krb5_krbhst_get_addrinfo +.Nd lookup Kerberos KDC hosts +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fn krb5_krbhst_init "krb5_context context" "const char *realm" "unsigned int type" "krb5_krbhst_handle *handle" +.Ft krb5_error_code +.Fn krb5_krbhst_init_flags "krb5_context context" "const char *realm" "unsigned int type" "int flags" "krb5_krbhst_handle *handle" +.Ft krb5_error_code +.Fn "krb5_krbhst_next" "krb5_context context" "krb5_krbhst_handle handle" "krb5_krbhst_info **host" +.Ft krb5_error_code +.Fn krb5_krbhst_next_as_string "krb5_context context" "krb5_krbhst_handle handle" "char *hostname" "size_t hostlen" +.Ft void +.Fn krb5_krbhst_reset "krb5_context context" "krb5_krbhst_handle handle" +.Ft void +.Fn krb5_krbhst_free "krb5_context context" "krb5_krbhst_handle handle" +.Ft krb5_error_code +.Fn krb5_krbhst_format_string "krb5_context context" "const krb5_krbhst_info *host" "char *hostname" "size_t hostlen" +.Ft krb5_error_code +.Fn krb5_krbhst_get_addrinfo "krb5_context context" "krb5_krbhst_info *host" "struct addrinfo **ai" +.Sh DESCRIPTION +These functions are used to sequence through all Kerberos hosts of a +particular realm and service. The service type can be the KDCs, the +administrative servers, the password changing servers, or the servers +for Kerberos 4 ticket conversion. +.Pp +First a handle to a particular service is obtained by calling +.Fn krb5_krbhst_init +(or +.Fn krb5_krbhst_init_flags ) +with the +.Fa realm +of interest and the type of service to lookup. The +.Fa type +can be one of: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It KRB5_KRBHST_KDC +.It KRB5_KRBHST_ADMIN +.It KRB5_KRBHST_CHANGEPW +.It KRB5_KRBHST_KRB524 +.El +.Pp +The +.Fa handle +is returned to the caller, and should be passed to the other +functions. +.Pp +The +.Fa flag +argument to +.Nm krb5_krbhst_init_flags +is the same flags as +.Fn krb5_send_to_kdc_flags +uses. +Possible values are: +.Pp +.Bl -tag -width KRB5_KRBHST_FLAGS_LARGE_MSG -compact -offset indent +.It KRB5_KRBHST_FLAGS_MASTER +only talk to master (readwrite) KDC +.It KRB5_KRBHST_FLAGS_LARGE_MSG +this is a large message, so use transport that can handle that. +.El +.Pp +For each call to +.Fn krb5_krbhst_next +information on a new host is returned. The former function returns in +.Fa host +a pointer to a structure containing information about the host, such +as protocol, hostname, and port: +.Bd -literal -offset indent +typedef struct krb5_krbhst_info { + enum { KRB5_KRBHST_UDP, + KRB5_KRBHST_TCP, + KRB5_KRBHST_HTTP } proto; + unsigned short port; + struct addrinfo *ai; + struct krb5_krbhst_info *next; + char hostname[1]; +} krb5_krbhst_info; +.Ed +.Pp +The related function, +.Fn krb5_krbhst_next_as_string , +return the same information as a URL-like string. +.Pp +When there are no more hosts, these functions return +.Dv KRB5_KDC_UNREACH . +.Pp +To re-iterate over all hosts, call +.Fn krb5_krbhst_reset +and the next call to +.Fn krb5_krbhst_next +will return the first host. +.Pp +When done with the handle, +.Fn krb5_krbhst_free +should be called. +.Pp +To use a +.Va krb5_krbhst_info , +there are two functions: +.Fn krb5_krbhst_format_string +that will return a printable representation of that struct +and +.Fn krb5_krbhst_get_addrinfo +that will return a +.Va struct addrinfo +that can then be used for communicating with the server mentioned. +.Sh EXAMPLES +The following code will print the KDCs of the realm +.Dq MY.REALM : +.Bd -literal -offset indent +krb5_krbhst_handle handle; +char host[MAXHOSTNAMELEN]; +krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle); +while(krb5_krbhst_next_as_string(context, handle, + host, sizeof(host)) == 0) + printf("%s\\n", host); +krb5_krbhst_free(context, handle); +.Ed +.\" .Sh BUGS +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr krb5_get_krbhst 3 , +.Xr krb5_send_to_kdc_flags 3 +.Sh HISTORY +These functions first appeared in Heimdal 0.3g. diff --git a/static/netbsd/man3/krb5_kt_add_entry.3 b/static/netbsd/man3/krb5_kt_add_entry.3 new file mode 100644 index 00000000..0bb1cffa --- /dev/null +++ b/static/netbsd/man3/krb5_kt_add_entry.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_add_entry.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_close.3 b/static/netbsd/man3/krb5_kt_close.3 new file mode 100644 index 00000000..35b79830 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_close.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_close.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_compare.3 b/static/netbsd/man3/krb5_kt_compare.3 new file mode 100644 index 00000000..d7abaeaa --- /dev/null +++ b/static/netbsd/man3/krb5_kt_compare.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_compare.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_copy_entry_contents.3 b/static/netbsd/man3/krb5_kt_copy_entry_contents.3 new file mode 100644 index 00000000..390d1a74 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_copy_entry_contents.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_copy_entry_contents.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_default.3 b/static/netbsd/man3/krb5_kt_default.3 new file mode 100644 index 00000000..2315d44a --- /dev/null +++ b/static/netbsd/man3/krb5_kt_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_default_modify_name.3 b/static/netbsd/man3/krb5_kt_default_modify_name.3 new file mode 100644 index 00000000..f3c65e52 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_default_modify_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_default_modify_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_default_name.3 b/static/netbsd/man3/krb5_kt_default_name.3 new file mode 100644 index 00000000..c0826e14 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_default_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_default_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_destroy.3 b/static/netbsd/man3/krb5_kt_destroy.3 new file mode 100644 index 00000000..b3e3ffa0 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_destroy.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_destroy.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_end_seq_get.3 b/static/netbsd/man3/krb5_kt_end_seq_get.3 new file mode 100644 index 00000000..a8c9f1bc --- /dev/null +++ b/static/netbsd/man3/krb5_kt_end_seq_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_end_seq_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_free_entry.3 b/static/netbsd/man3/krb5_kt_free_entry.3 new file mode 100644 index 00000000..70aedc2b --- /dev/null +++ b/static/netbsd/man3/krb5_kt_free_entry.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_free_entry.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_get_entry.3 b/static/netbsd/man3/krb5_kt_get_entry.3 new file mode 100644 index 00000000..118fe1ca --- /dev/null +++ b/static/netbsd/man3/krb5_kt_get_entry.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_get_entry.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_get_full_name.3 b/static/netbsd/man3/krb5_kt_get_full_name.3 new file mode 100644 index 00000000..20e374c6 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_get_full_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_get_full_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_get_name.3 b/static/netbsd/man3/krb5_kt_get_name.3 new file mode 100644 index 00000000..bbb808c0 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_get_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_get_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_get_type.3 b/static/netbsd/man3/krb5_kt_get_type.3 new file mode 100644 index 00000000..87fb95f2 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_get_type.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_get_type.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_have_content.3 b/static/netbsd/man3/krb5_kt_have_content.3 new file mode 100644 index 00000000..553da883 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_have_content.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_have_content.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_next_entry.3 b/static/netbsd/man3/krb5_kt_next_entry.3 new file mode 100644 index 00000000..71e69347 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_next_entry.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_next_entry.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_read_service_key.3 b/static/netbsd/man3/krb5_kt_read_service_key.3 new file mode 100644 index 00000000..d44090f0 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_read_service_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_read_service_key.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_register.3 b/static/netbsd/man3/krb5_kt_register.3 new file mode 100644 index 00000000..a346b673 --- /dev/null +++ b/static/netbsd/man3/krb5_kt_register.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_register.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_remove_entry.3 b/static/netbsd/man3/krb5_kt_remove_entry.3 new file mode 100644 index 00000000..deed794e --- /dev/null +++ b/static/netbsd/man3/krb5_kt_remove_entry.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_remove_entry.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_resolve.3 b/static/netbsd/man3/krb5_kt_resolve.3 new file mode 100644 index 00000000..3f855a1b --- /dev/null +++ b/static/netbsd/man3/krb5_kt_resolve.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_resolve.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kt_start_seq_get.3 b/static/netbsd/man3/krb5_kt_start_seq_get.3 new file mode 100644 index 00000000..d5d3c1dd --- /dev/null +++ b/static/netbsd/man3/krb5_kt_start_seq_get.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kt_start_seq_get.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_keytab.3 diff --git a/static/netbsd/man3/krb5_kuserok.3 b/static/netbsd/man3/krb5_kuserok.3 new file mode 100644 index 00000000..588e9546 --- /dev/null +++ b/static/netbsd/man3/krb5_kuserok.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_kuserok.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_make_addrport.3 b/static/netbsd/man3/krb5_make_addrport.3 new file mode 100644 index 00000000..5a363747 --- /dev/null +++ b/static/netbsd/man3/krb5_make_addrport.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_make_addrport.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_make_principal.3 b/static/netbsd/man3/krb5_make_principal.3 new file mode 100644 index 00000000..b2cfeb91 --- /dev/null +++ b/static/netbsd/man3/krb5_make_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_make_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_max_sockaddr_size.3 b/static/netbsd/man3/krb5_max_sockaddr_size.3 new file mode 100644 index 00000000..a7764160 --- /dev/null +++ b/static/netbsd/man3/krb5_max_sockaddr_size.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_max_sockaddr_size.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_mcc_ops.3 b/static/netbsd/man3/krb5_mcc_ops.3 new file mode 100644 index 00000000..90d5e433 --- /dev/null +++ b/static/netbsd/man3/krb5_mcc_ops.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_mcc_ops.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ccache.3 diff --git a/static/netbsd/man3/krb5_mk_req.3 b/static/netbsd/man3/krb5_mk_req.3 new file mode 100644 index 00000000..5b89717e --- /dev/null +++ b/static/netbsd/man3/krb5_mk_req.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: krb5_mk_req.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd August 27, 2005 +.Dt KRB5_MK_REQ 3 +.Os +.Sh NAME +.Nm krb5_mk_req , +.Nm krb5_mk_req_exact , +.Nm krb5_mk_req_extended , +.Nm krb5_rd_req , +.Nm krb5_rd_req_with_keyblock , +.Nm krb5_mk_rep , +.Nm krb5_mk_rep_exact , +.Nm krb5_mk_rep_extended , +.Nm krb5_rd_rep , +.Nm krb5_build_ap_req , +.Nm krb5_verify_ap_req +.Nd create and read application authentication request +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_mk_req +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "const krb5_flags ap_req_options" +.Fa "const char *service" +.Fa "const char *hostname" +.Fa "krb5_data *in_data" +.Fa "krb5_ccache ccache" +.Fa "krb5_data *outbuf" +.Fc +.Ft krb5_error_code +.Fo krb5_mk_req_extended +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "const krb5_flags ap_req_options" +.Fa "krb5_data *in_data" +.Fa "krb5_creds *in_creds" +.Fa "krb5_data *outbuf" +.Fc +.Ft krb5_error_code +.Fo krb5_rd_req +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "const krb5_data *inbuf" +.Fa "krb5_const_principal server" +.Fa "krb5_keytab keytab" +.Fa "krb5_flags *ap_req_options" +.Fa "krb5_ticket **ticket" +.Fc +.Ft krb5_error_code +.Fo krb5_build_ap_req +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "krb5_creds *cred" +.Fa "krb5_flags ap_options" +.Fa "krb5_data authenticator" +.Fa "krb5_data *retdata" +.Fc +.Ft krb5_error_code +.Fo krb5_verify_ap_req +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "krb5_ap_req *ap_req" +.Fa "krb5_const_principal server" +.Fa "krb5_keyblock *keyblock" +.Fa "krb5_flags flags" +.Fa "krb5_flags *ap_req_options" +.Fa "krb5_ticket **ticket" +.Fc +.Sh DESCRIPTION +The functions documented in this manual page document the functions +that facilitates the exchange between a Kerberos client and server. +They are the core functions used in the authentication exchange +between the client and the server. +.Pp +The +.Nm krb5_mk_req +and +.Nm krb5_mk_req_extended +creates the Kerberos message +.Dv KRB_AP_REQ +that is sent from the client to the server as the first packet in a client/server exchange. The result that should be sent to server is stored in +.Fa outbuf . +.Pp +.Fa auth_context +should be allocated with +.Fn krb5_auth_con_init +or +.Dv NULL +passed in, in that case, it will be allocated and freed internally. +.Pp +The input data +.Fa in_data +will have a checksum calculated over it and checksum will be +transported in the message to the server. +.Pp +.Fa ap_req_options +can be set to one or more of the following flags: +.Pp +.Bl -tag -width indent +.It Dv AP_OPTS_USE_SESSION_KEY +Use the session key when creating the request, used for user to user +authentication. +.It Dv AP_OPTS_MUTUAL_REQUIRED +Mark the request as mutual authenticate required so that the receiver +returns a mutual authentication packet. +.El +.Pp +The +.Nm krb5_rd_req +read the AP_REQ in +.Fa inbuf +and verify and extract the content. +If +.Fa server +is specified, that server will be fetched from the +.Fa keytab +and used unconditionally. +If +.Fa server +is +.Dv NULL , +the +.Fa keytab +will be search for a matching principal. +.Pp +The +.Fa keytab +argument specifies what keytab to search for receiving principals. +The arguments +.Fa ap_req_options +and +.Fa ticket +returns the content. +.Pp +When the AS-REQ is a user to user request, neither of +.Fa keytab +or +.Fa principal +are used, instead +.Fn krb5_rd_req +expects the session key to be set in +.Fa auth_context . +.Pp +The +.Nm krb5_verify_ap_req +and +.Nm krb5_build_ap_req +both constructs and verify the AP_REQ message, should not be used by +external code. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_mk_safe.3 b/static/netbsd/man3/krb5_mk_safe.3 new file mode 100644 index 00000000..f1e06ab2 --- /dev/null +++ b/static/netbsd/man3/krb5_mk_safe.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: krb5_mk_safe.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_MK_SAFE 3 +.Os +.Sh NAME +.Nm krb5_mk_safe , +.Nm krb5_mk_priv +.Nd generates integrity protected and/or encrypted messages +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft krb5_error_code +.Fn krb5_mk_priv "krb5_context context" "krb5_auth_context auth_context" "const krb5_data *userdata" "krb5_data *outbuf" "krb5_replay_data *outdata" +.Ft krb5_error_code +.Fn krb5_mk_safe "krb5_context context" "krb5_auth_context auth_context" "const krb5_data *userdata" "krb5_data *outbuf" "krb5_replay_data *outdata" +.Sh DESCRIPTION +.Fn krb5_mk_safe +and +.Fn krb5_mk_priv +formats +.Li KRB-SAFE +(integrity protected) +and +.Li KRB-PRIV +(also encrypted) +messages into +.Fa outbuf . +The actual message data is taken from +.Fa userdata . +If the +.Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE +or +.Dv KRB5_AUTH_CONTEXT_DO_TIME +flags are set in the +.Fa auth_context , +sequence numbers and time stamps are generated. +If the +.Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE +or +.Dv KRB5_AUTH_CONTEXT_RET_TIME +flags are set +they are also returned in the +.Fa outdata +parameter. +.Sh SEE ALSO +.Xr krb5_auth_con_init 3 , +.Xr krb5_rd_priv 3 , +.Xr krb5_rd_safe 3 diff --git a/static/netbsd/man3/krb5_openlog.3 b/static/netbsd/man3/krb5_openlog.3 new file mode 100644 index 00000000..af9cf18a --- /dev/null +++ b/static/netbsd/man3/krb5_openlog.3 @@ -0,0 +1,244 @@ +.\" $NetBSD: krb5_openlog.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.Dd August 6, 1997 +.Dt KRB5_OPENLOG 3 +.Os +.Sh NAME +.Nm krb5_initlog , +.Nm krb5_openlog , +.Nm krb5_closelog , +.Nm krb5_addlog_dest , +.Nm krb5_addlog_func , +.Nm krb5_log , +.Nm krb5_vlog , +.Nm krb5_log_msg , +.Nm krb5_vlog_msg +.Nd Heimdal logging functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft "typedef void" +.Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data" +.Ft "typedef void" +.Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data" +.Ft krb5_error_code +.Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination" +.Ft krb5_error_code +.Fn krb5_addlog_func "krb5_context context" "krb5_log_facility *facility" "int min" "int max" "krb5_log_log_func_t log" "krb5_log_close_func_t close" "void *data" +.Ft krb5_error_code +.Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility" +.Ft krb5_error_code +.Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility" +.Ft krb5_error_code +.Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..." +.Ft krb5_error_code +.Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..." +.Ft krb5_error_code +.Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility" +.Ft krb5_error_code +.Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist" +.Ft krb5_error_code +.Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist" +.Sh DESCRIPTION +These functions logs messages to one or more destinations. +.Pp +The +.Fn krb5_openlog +function creates a logging +.Fa facility , +that is used to log messages. A facility consists of one or more +destinations (which can be files or syslog or some other device). The +.Fa program +parameter should be the generic name of the program that is doing the +logging. This name is used to lookup which destinations to use. This +information is contained in the +.Li logging +section of the +.Pa krb5.conf +configuration file. If no entry is found for +.Fa program , +the entry for +.Li default +is used, or if that is missing too, +.Li SYSLOG +will be used as destination. +.Pp +To close a logging facility, use the +.Fn krb5_closelog +function. +.Pp +To log a message to a facility use one of the functions +.Fn krb5_log , +.Fn krb5_log_msg , +.Fn krb5_vlog , +or +.Fn krb5_vlog_msg . +The functions ending in +.Li _msg +return in +.Fa reply +a pointer to the message that just got logged. This string is allocated, +and should be freed with +.Fn free . +The +.Fa format +is a standard +.Fn printf +style format string (but see the BUGS section). +.Pp +If you want better control of where things gets logged, you can instead of using +.Fn krb5_openlog +call +.Fn krb5_initlog , +which just initializes a facility, but doesn't define any actual logging +destinations. You can then add destinations with the +.Fn krb5_addlog_dest +and +.Fn krb5_addlog_func +functions. The first of these takes a string specifying a logging +destination, and adds this to the facility. If you want to do some +non-standard logging you can use the +.Fn krb5_addlog_func +function, which takes a function to use when logging. +The +.Fa log +function is called for each message with +.Fa time +being a string specifying the current time, and +.Fa message +the message to log. +.Fa close +is called when the facility is closed. You can pass application specific data in the +.Fa data +parameter. The +.Fa min +and +.Fa max +parameter are the same as in a destination (defined below). To specify a +max of infinity, pass -1. +.Pp +.Fn krb5_openlog +calls +.Fn krb5_initlog +and then calls +.Fn krb5_addlog_dest +for each destination found. +.Ss Destinations +The defined destinations (as specified in +.Pa krb5.conf ) +follows: +.Bl -tag -width "xxx" -offset indent +.It Li STDERR +This logs to the program's stderr. +.It Li FILE: Ns Pa /file +.It Li FILE= Ns Pa /file +Log to the specified file. The form using a colon appends to the file, the +form with an equal truncates the file. The truncating form keeps the file +open, while the appending form closes it after each log message (which +makes it possible to rotate logs). The truncating form is mainly for +compatibility with the MIT libkrb5. +.It Li DEVICE= Ns Pa /device +This logs to the specified device, at present this is the same as +.Li FILE:/device . +.It Li CONSOLE +Log to the console, this is the same as +.Li DEVICE=/dev/console . +.It Li SYSLOG Ns Op :priority Ns Op :facility +Send messages to the syslog system, using priority, and facility. To +get the name for one of these, you take the name of the macro passed +to +.Xr syslog 3 , +and remove the leading +.Li LOG_ +.No ( Li LOG_NOTICE +becomes +.Li NOTICE ) . +The default values (as well as the values used for unrecognised +values), are +.Li ERR , +and +.Li AUTH , +respectively. See +.Xr syslog 3 +for a list of priorities and facilities. +.El +.Pp +Each destination may optionally be prepended with a range of logging +levels, specified as +.Li min-max/ . +If the +.Fa level +parameter to +.Fn krb5_log +is within this range (inclusive) the message gets logged to this +destination, otherwise not. Either of the min and max valued may be +omitted, in this case min is assumed to be zero, and max is assumed to be +infinity. If you don't include a dash, both min and max gets set to the +specified value. If no range is specified, all messages gets logged. +.Sh EXAMPLES +.Bd -literal -offset indent +[logging] + kdc = 0/FILE:/var/log/kdc.log + kdc = 1-/SYSLOG:INFO:USER + default = STDERR +.Ed +.Pp +This will log all messages from the +.Nm kdc +program with level 0 to +.Pa /var/log/kdc.log , +other messages will be logged to syslog with priority +.Li LOG_INFO , +and facility +.Li LOG_USER . +All other programs will log all messages to their stderr. +.Sh SEE ALSO +.Xr syslog 3 , +.Xr krb5.conf 5 +.Sh BUGS +These functions use +.Fn asprintf +to format the message. If your operating system does not have a working +.Fn asprintf , +a replacement will be used. At present this replacement does not handle +some correct conversion specifications (like floating point numbers). Until +this is fixed, the use of these conversions should be avoided. +.Pp +If logging is done to the syslog facility, these functions might not be +thread-safe, depending on the implementation of +.Fn openlog , +and +.Fn syslog . diff --git a/static/netbsd/man3/krb5_pac.3 b/static/netbsd/man3/krb5_pac.3 new file mode 100644 index 00000000..c73e62e8 --- /dev/null +++ b/static/netbsd/man3/krb5_pac.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: krb5_pac.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_pac" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_pac \- Heimdal Kerberos 5 PAC handling functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_pac_get_buffer\fP (krb5_context context, krb5_pac p, uint32_t type, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_pac_verify\fP (krb5_context context, const krb5_pac pac, time_t authtime, krb5_const_principal principal, const krb5_keyblock *server, const krb5_keyblock *privsvr)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_pac_get_buffer (krb5_context context, krb5_pac p, uint32_t type, krb5_data * data)" +Get the PAC buffer of specific type from the pac\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIp\fP the pac structure returned by krb5_pac_parse()\&. +.br +\fItype\fP type of buffer to get +.br +\fIdata\fP return data, free with \fBkrb5_data_free()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_pac_verify (krb5_context context, const krb5_pac pac, time_t authtime, krb5_const_principal principal, const krb5_keyblock * server, const krb5_keyblock * privsvr)" +Verify the PAC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIpac\fP the pac structure returned by krb5_pac_parse()\&. +.br +\fIauthtime\fP The time of the ticket the PAC belongs to\&. +.br +\fIprincipal\fP the principal to verify\&. +.br +\fIserver\fP The service key, most always be given\&. +.br +\fIprivsvr\fP The KDC key, may be given\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_pac_get_buffer.3 b/static/netbsd/man3/krb5_pac_get_buffer.3 new file mode 100644 index 00000000..ddca7324 --- /dev/null +++ b/static/netbsd/man3/krb5_pac_get_buffer.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_pac_get_buffer.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_pac.3 diff --git a/static/netbsd/man3/krb5_pac_verify.3 b/static/netbsd/man3/krb5_pac_verify.3 new file mode 100644 index 00000000..e323fee4 --- /dev/null +++ b/static/netbsd/man3/krb5_pac_verify.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_pac_verify.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_pac.3 diff --git a/static/netbsd/man3/krb5_parse_address.3 b/static/netbsd/man3/krb5_parse_address.3 new file mode 100644 index 00000000..9011f82b --- /dev/null +++ b/static/netbsd/man3/krb5_parse_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_parse_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_parse_name.3 b/static/netbsd/man3/krb5_parse_name.3 new file mode 100644 index 00000000..12238cb5 --- /dev/null +++ b/static/netbsd/man3/krb5_parse_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_parse_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_parse_name_flags.3 b/static/netbsd/man3/krb5_parse_name_flags.3 new file mode 100644 index 00000000..0b7fedf2 --- /dev/null +++ b/static/netbsd/man3/krb5_parse_name_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_parse_name_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_parse_nametype.3 b/static/netbsd/man3/krb5_parse_nametype.3 new file mode 100644 index 00000000..d4861117 --- /dev/null +++ b/static/netbsd/man3/krb5_parse_nametype.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_parse_nametype.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_password_key_proc.3 b/static/netbsd/man3/krb5_password_key_proc.3 new file mode 100644 index 00000000..6f9fb49a --- /dev/null +++ b/static/netbsd/man3/krb5_password_key_proc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_password_key_proc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_plugin_register.3 b/static/netbsd/man3/krb5_plugin_register.3 new file mode 100644 index 00000000..49a0a838 --- /dev/null +++ b/static/netbsd/man3/krb5_plugin_register.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_plugin_register.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_support.3 diff --git a/static/netbsd/man3/krb5_prepend_config_files_default.3 b/static/netbsd/man3/krb5_prepend_config_files_default.3 new file mode 100644 index 00000000..760bdf06 --- /dev/null +++ b/static/netbsd/man3/krb5_prepend_config_files_default.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_prepend_config_files_default.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_prepend_error_message.3 b/static/netbsd/man3/krb5_prepend_error_message.3 new file mode 100644 index 00000000..c3166db0 --- /dev/null +++ b/static/netbsd/man3/krb5_prepend_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_prepend_error_message.3,v 1.2 2023/06/19 21:41:40 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_princ_realm.3 b/static/netbsd/man3/krb5_princ_realm.3 new file mode 100644 index 00000000..9b5de335 --- /dev/null +++ b/static/netbsd/man3/krb5_princ_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_princ_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_princ_set_realm.3 b/static/netbsd/man3/krb5_princ_set_realm.3 new file mode 100644 index 00000000..8eccabd0 --- /dev/null +++ b/static/netbsd/man3/krb5_princ_set_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_princ_set_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_principal.3 b/static/netbsd/man3/krb5_principal.3 new file mode 100644 index 00000000..3a4c2980 --- /dev/null +++ b/static/netbsd/man3/krb5_principal.3 @@ -0,0 +1,540 @@ +.\" $NetBSD: krb5_principal.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_principal" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_principal \- Heimdal Kerberos 5 principal functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_principal\fP (krb5_context context, krb5_principal p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_principal_set_type\fP (krb5_context context, krb5_principal principal, int type)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_principal_get_type\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_principal_get_realm\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL \fBkrb5_principal_get_num_comp\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_name_flags\fP (krb5_context context, const char *name, int flags, krb5_principal *principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_name\fP (krb5_context context, const char *name, krb5_principal *principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed\fP (krb5_context context, krb5_const_principal principal, char *name, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed_short\fP (krb5_context context, krb5_const_principal principal, char *name, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed_flags\fP (krb5_context context, krb5_const_principal principal, int flags, char *name, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name\fP (krb5_context context, krb5_const_principal principal, char **name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_flags\fP (krb5_context context, krb5_const_principal principal, int flags, char **name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_short\fP (krb5_context context, krb5_const_principal principal, char **name)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_principal_set_realm\fP (krb5_context context, krb5_principal principal, krb5_const_realm realm)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_build_principal\fP (krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_make_principal\fP (krb5_context context, krb5_principal *principal, krb5_const_realm realm,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_principal\fP (krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_compare_any_realm\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_realm_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_match\fP (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_nametype\fP (krb5_context context, const char *str, int32_t *nametype)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_principal_is_null\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_realm_is_lkdc\fP (const char *realm)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_principal_is_lkdc\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_principal_is_pku2u\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_is_krbtgt\fP (krb5_context context, krb5_const_principal p)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_principal_is_gss_hostbased_service\fP (krb5_context context, krb5_const_principal principal)" +.br +.ti -1c +.RI "krb5_boolean KRB5_LIB_FUNCTION \fBkrb5_principal_is_root_krbtgt\fP (krb5_context context, krb5_const_principal p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_is_anonymous\fP (krb5_context context, krb5_const_principal p, unsigned int flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_sname_to_principal\fP (krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal (krb5_context context, krb5_principal * principal, int rlen, krb5_const_realm realm, \&.\&.\&.)" +Build a principal using vararg style building +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP returned principal +.br +\fIrlen\fP length of realm +.br +\fIrealm\fP realm name +.br +\fI\&.\&.\&.\fP a list of components ended with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal (krb5_context context, krb5_const_principal inprinc, krb5_principal * outprinc)" +Copy a principal +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIinprinc\fP principal to copy +.br +\fIoutprinc\fP copied principal, free with \fBkrb5_free_principal()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal (krb5_context context, krb5_principal p)" +Frees a Kerberos principal allocated by the library with \fBkrb5_parse_name()\fP, \fBkrb5_make_principal()\fP or any other related principal functions\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIp\fP a principal to free\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal (krb5_context context, krb5_principal * principal, krb5_const_realm realm, \&.\&.\&.)" +Build a principal using vararg style building +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP returned principal +.br +\fIrealm\fP realm name +.br +\fI\&.\&.\&.\fP a list of components ended with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name (krb5_context context, const char * name, krb5_principal * principal)" +Parse a name into a krb5_principal structure +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIname\fP name to parse into a Kerberos principal +.br +\fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags (krb5_context context, const char * name, int flags, krb5_principal * principal)" +Parse a name into a krb5_principal structure, flags controls the behavior\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIname\fP name to parse into a Kerberos principal +.br +\fIflags\fP flags to control the behavior +.br +\fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype (krb5_context context, const char * str, int32_t * nametype)" +Parse nametype string and return a nametype integer +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +Compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprinc1\fP first principal to compare +.br +\fIprinc2\fP second principal to compare +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_principal_compare_any_realm()\fP +.PP +\fBkrb5_realm_compare()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare_any_realm (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +Return TRUE iff princ1 == princ2 (without considering the realm) +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprinc1\fP first principal to compare +.br +\fIprinc2\fP second principal to compare +.RE +.PP +\fBReturns\fP +.RS 4 +non zero if equal, 0 if not +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_principal_compare()\fP +.PP +\fBkrb5_realm_compare()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp (krb5_context context, krb5_const_principal principal)" +Get number of component is principal\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprincipal\fP principal to query +.RE +.PP +\fBReturns\fP +.RS 4 +number of components in string +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm (krb5_context context, krb5_const_principal principal)" +Get the realm of the principal +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to get the realm for +.RE +.PP +\fBReturns\fP +.RS 4 +realm of the principal, don't free or use after krb5_principal is freed +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type (krb5_context context, krb5_const_principal principal)" +Get the type of the principal +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to get the type for +.RE +.PP +\fBReturns\fP +.RS 4 +the type of principal +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_anonymous (krb5_context context, krb5_const_principal p, unsigned int flags)" +Returns true iff name is WELLKNOWN/ANONYMOUS +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_gss_hostbased_service (krb5_context context, krb5_const_principal principal)" +Returns true iff name is an WELLKNOWN:ORG\&.H5L\&.HOSTBASED-SERVICE +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)" +Check if the cname part of the principal is a krbtgt principal +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_lkdc (krb5_context context, krb5_const_principal principal)" +Returns true if name is Kerberos an LKDC realm +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_null (krb5_context context, krb5_const_principal principal)" +Returns true if name is Kerberos NULL name +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_pku2u (krb5_context context, krb5_const_principal principal)" +Returns true if name is Kerberos an LKDC realm +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_root_krbtgt (krb5_context context, krb5_const_principal p)" +Check if the cname part of the principal is a initial or renewed krbtgt principal +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)" +return TRUE iff princ matches pattern +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)" +Set a new realm for a principal, and as a side-effect free the previous realm\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal set the realm for +.br +\fIrealm\fP the new realm to set +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)" +Set the type of the principal +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to set the type for +.br +\fItype\fP the new type +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)" +return TRUE iff realm(princ1) == realm(princ2) +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprinc1\fP first principal to compare +.br +\fIprinc2\fP second principal to compare +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_principal_compare_any_realm()\fP +.PP +\fBkrb5_principal_compare()\fP +.RE +.PP + +.SS "krb5_boolean KRB5_LIB_FUNCTION krb5_realm_is_lkdc (const char * realm)" +Returns true if name is Kerberos an LKDC realm +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sname_to_principal (krb5_context context, const char * hostname, const char * sname, int32_t type, krb5_principal * ret_princ)" +Create a principal for the given service running on the given hostname\&. If KRB5_NT_SRV_HST is used, the hostname is canonicalized according the configured name canonicalization rules, with canonicalization delayed in some cases\&. One rule involves DNS, which is insecure unless DNSSEC is used, but we don't use DNSSEC-capable resolver APIs here, so that if DNSSEC is used we wouldn't know it\&. +.PP +Canonicalization is immediate (not delayed) only when there is only one canonicalization rule and that rule indicates that we should do a host lookup by name (i\&.e\&., DNS)\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIhostname\fP hostname to use +.br +\fIsname\fP Service name to use +.br +\fItype\fP name type of principal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN\&. +.br +\fIret_princ\fP return principal, free with \fBkrb5_free_principal()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name (krb5_context context, krb5_const_principal principal, char ** name)" +Unparse the Kerberos name into a string +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprincipal\fP principal to query +.br +\fIname\fP resulting string, free with krb5_xfree() +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed (krb5_context context, krb5_const_principal principal, char * name, size_t len)" +Unparse the principal name to a fixed buffer +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to unparse +.br +\fIname\fP buffer to write name to +.br +\fIlen\fP length of buffer +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_flags (krb5_context context, krb5_const_principal principal, int flags, char * name, size_t len)" +Unparse the principal name with unparse flags to a fixed buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to unparse +.br +\fIflags\fP unparse flags +.br +\fIname\fP buffer to write name to +.br +\fIlen\fP length of buffer +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_short (krb5_context context, krb5_const_principal principal, char * name, size_t len)" +Unparse the principal name to a fixed buffer\&. The realm is skipped if its a default realm\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to unparse +.br +\fIname\fP buffer to write name to +.br +\fIlen\fP length of buffer +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags (krb5_context context, krb5_const_principal principal, int flags, char ** name)" +Unparse the Kerberos name into a string +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIprincipal\fP principal to query +.br +\fIflags\fP flag to determine the behavior +.br +\fIname\fP resulting string, free with krb5_xfree() +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char ** name)" +Unparse the principal name to a allocated buffer\&. The realm is skipped if its a default realm\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos context\&. +.br +\fIprincipal\fP principal to unparse +.br +\fIname\fP returned buffer, free with krb5_xfree() +.RE +.PP +\fBReturns\fP +.RS 4 +An krb5 error code, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_principal_compare.3 b/static/netbsd/man3/krb5_principal_compare.3 new file mode 100644 index 00000000..b876acac --- /dev/null +++ b/static/netbsd/man3/krb5_principal_compare.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_compare.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_compare_any_realm.3 b/static/netbsd/man3/krb5_principal_compare_any_realm.3 new file mode 100644 index 00000000..6b380949 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_compare_any_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_compare_any_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_get_num_comp.3 b/static/netbsd/man3/krb5_principal_get_num_comp.3 new file mode 100644 index 00000000..2279f1fc --- /dev/null +++ b/static/netbsd/man3/krb5_principal_get_num_comp.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_get_num_comp.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_get_realm.3 b/static/netbsd/man3/krb5_principal_get_realm.3 new file mode 100644 index 00000000..9977e24f --- /dev/null +++ b/static/netbsd/man3/krb5_principal_get_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_get_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_get_type.3 b/static/netbsd/man3/krb5_principal_get_type.3 new file mode 100644 index 00000000..d47d1acf --- /dev/null +++ b/static/netbsd/man3/krb5_principal_get_type.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_get_type.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_intro.3 b/static/netbsd/man3/krb5_principal_intro.3 new file mode 100644 index 00000000..dba668e4 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_intro.3 @@ -0,0 +1,18 @@ +.\" $NetBSD: krb5_principal_intro.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_principal_intro" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_principal_intro \- The principal handing functions\&. +A Kerberos principal is a email address looking string that contains two parts separated by . The second part is the kerberos realm the principal belongs to and the first is a list of 0 or more components\&. For example +.PP +.nf +lha@SU.SE +host/hummel.it.su.se@SU.SE +host/admin@H5L.ORG + +.fi +.PP +.PP +See the library functions here: \fBHeimdal Kerberos 5 principal functions\fP diff --git a/static/netbsd/man3/krb5_principal_is_anonymous.3 b/static/netbsd/man3/krb5_principal_is_anonymous.3 new file mode 100644 index 00000000..27705c4a --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_anonymous.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_anonymous.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_gss_hostbased_service.3 b/static/netbsd/man3/krb5_principal_is_gss_hostbased_service.3 new file mode 100644 index 00000000..6d648e8d --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_gss_hostbased_service.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_gss_hostbased_service.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_krbtgt.3 b/static/netbsd/man3/krb5_principal_is_krbtgt.3 new file mode 100644 index 00000000..e3b4044c --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_krbtgt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_krbtgt.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_lkdc.3 b/static/netbsd/man3/krb5_principal_is_lkdc.3 new file mode 100644 index 00000000..17a76d96 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_lkdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_lkdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_null.3 b/static/netbsd/man3/krb5_principal_is_null.3 new file mode 100644 index 00000000..1f9df9d5 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_null.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_null.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_pku2u.3 b/static/netbsd/man3/krb5_principal_is_pku2u.3 new file mode 100644 index 00000000..d624cfe4 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_pku2u.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_pku2u.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_is_root_krbtgt.3 b/static/netbsd/man3/krb5_principal_is_root_krbtgt.3 new file mode 100644 index 00000000..9548f2e1 --- /dev/null +++ b/static/netbsd/man3/krb5_principal_is_root_krbtgt.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_is_root_krbtgt.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_match.3 b/static/netbsd/man3/krb5_principal_match.3 new file mode 100644 index 00000000..364a31dd --- /dev/null +++ b/static/netbsd/man3/krb5_principal_match.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_match.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_set_realm.3 b/static/netbsd/man3/krb5_principal_set_realm.3 new file mode 100644 index 00000000..66eab2af --- /dev/null +++ b/static/netbsd/man3/krb5_principal_set_realm.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_set_realm.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_principal_set_type.3 b/static/netbsd/man3/krb5_principal_set_type.3 new file mode 100644 index 00000000..763a054c --- /dev/null +++ b/static/netbsd/man3/krb5_principal_set_type.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_principal_set_type.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_print_address.3 b/static/netbsd/man3/krb5_print_address.3 new file mode 100644 index 00000000..ca8d110f --- /dev/null +++ b/static/netbsd/man3/krb5_print_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_print_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_random_to_key.3 b/static/netbsd/man3/krb5_random_to_key.3 new file mode 100644 index 00000000..bc7b751c --- /dev/null +++ b/static/netbsd/man3/krb5_random_to_key.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_random_to_key.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_rcache.3 b/static/netbsd/man3/krb5_rcache.3 new file mode 100644 index 00000000..5ea38a41 --- /dev/null +++ b/static/netbsd/man3/krb5_rcache.3 @@ -0,0 +1,165 @@ +.\" $NetBSD: krb5_rcache.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_RCACHE 3 +.Os +.Sh NAME +.Nm krb5_rcache , +.Nm krb5_rc_close , +.Nm krb5_rc_default , +.Nm krb5_rc_default_name , +.Nm krb5_rc_default_type , +.Nm krb5_rc_destroy , +.Nm krb5_rc_expunge , +.Nm krb5_rc_get_lifespan , +.Nm krb5_rc_get_name , +.Nm krb5_rc_get_type , +.Nm krb5_rc_initialize , +.Nm krb5_rc_recover , +.Nm krb5_rc_resolve , +.Nm krb5_rc_resolve_full , +.Nm krb5_rc_resolve_type , +.Nm krb5_rc_store , +.Nm krb5_get_server_rcache +.Nd Kerberos 5 replay cache +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Li "struct krb5_rcache;" +.Pp +.Ft krb5_error_code +.Fo krb5_rc_close +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_default +.Fa "krb5_context context" +.Fa "krb5_rcache *id" +.Fc +.Ft "const char *" +.Fo krb5_rc_default_name +.Fa "krb5_context context" +.Fc +.Ft "const char *" +.Fo krb5_rc_default_type +.Fa "krb5_context context" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_destroy +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_expunge +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_get_lifespan +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fa "krb5_deltat *auth_lifespan" +.Fc +.Ft "const char*" +.Fo krb5_rc_get_name +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft "const char*" +.Fo "krb5_rc_get_type" +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_initialize +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fa "krb5_deltat auth_lifespan" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_recover +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_resolve +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fa "const char *name" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_resolve_full +.Fa "krb5_context context" +.Fa "krb5_rcache *id" +.Fa "const char *string_name" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_resolve_type +.Fa "krb5_context context" +.Fa "krb5_rcache *id" +.Fa "const char *type" +.Fc +.Ft krb5_error_code +.Fo krb5_rc_store +.Fa "krb5_context context" +.Fa "krb5_rcache id" +.Fa "krb5_donot_replay *rep" +.Fc +.Ft krb5_error_code +.Fo krb5_get_server_rcache +.Fa "krb5_context context" +.Fa "const krb5_data *piece" +.Fa "krb5_rcache *id" +.Fc +.Sh DESCRIPTION +The +.Li krb5_rcache +structure holds a storage element that is used for data manipulation. +The structure contains no public accessible elements. +.Pp +.Fn krb5_rc_initialize +Creates the reply cache +.Fa id +and sets it lifespan to +.Fa auth_lifespan . +If the cache already exists, the content is destroyed. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_data 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_rd_error.3 b/static/netbsd/man3/krb5_rd_error.3 new file mode 100644 index 00000000..f7968253 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_error.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: krb5_rd_error.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd July 26, 2004 +.Dt KRB5_RD_ERROR 3 +.Os +.Sh NAME +.Nm krb5_rd_error , +.Nm krb5_free_error , +.Nm krb5_free_error_contents , +.Nm krb5_error_from_rd_error +.Nd parse, free and read error from KRB-ERROR message +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_rd_error +.Fa "krb5_context context" +.Fa "const krb5_data *msg" +.Fa "KRB_ERROR *result" +.Fc +.Ft void +.Fo krb5_free_error +.Fa "krb5_context context" +.Fa "krb5_error *error" +.Fc +.Ft void +.Fo krb5_free_error_contents +.Fa "krb5_context context" +.Fa "krb5_error *error" +.Fc +.Ft krb5_error_code +.Fo krb5_error_from_rd_error +.Fa "krb5_context context" +.Fa "const krb5_error *error" +.Fa "const krb5_creds *creds" +.Fc +.Sh DESCRIPTION +Usually applications never needs to parse and understand Kerberos +error messages since higher level functions will parse and push up the +error in the krb5_context. +These functions are described for completeness. +.Pp +.Fn krb5_rd_error +parses and returns the kerboeros error message, the structure should be freed with +.Fn krb5_free_error_contents +when the caller is done with the structure. +.Pp +.Fn krb5_free_error +frees the content and the memory region holding the structure iself. +.Pp +.Fn krb5_free_error_contents +free the content of the KRB-ERROR message. +.Pp +.Fn krb5_error_from_rd_error +will parse the error message and set the error buffer in krb5_context +to the error string passed back or the matching error code in the +KRB-ERROR message. +Caller should pick up the message with +.Fn krb5_get_error_string 3 +(don't forget to free the returned string with +.Fn krb5_free_error_string ) . +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_set_error_string 3 , +.Xr krb5_get_error_string 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_rd_req_ctx.3 b/static/netbsd/man3/krb5_rd_req_ctx.3 new file mode 100644 index 00000000..48a16102 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_ctx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_ctx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_req_in_ctx_alloc.3 b/static/netbsd/man3/krb5_rd_req_in_ctx_alloc.3 new file mode 100644 index 00000000..6a385553 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_in_ctx_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_in_ctx_alloc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_req_in_set_keytab.3 b/static/netbsd/man3/krb5_rd_req_in_set_keytab.3 new file mode 100644 index 00000000..45889635 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_in_set_keytab.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_in_set_keytab.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_req_in_set_pac_check.3 b/static/netbsd/man3/krb5_rd_req_in_set_pac_check.3 new file mode 100644 index 00000000..069d7db0 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_in_set_pac_check.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_in_set_pac_check.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_req_out_ctx_free.3 b/static/netbsd/man3/krb5_rd_req_out_ctx_free.3 new file mode 100644 index 00000000..fe5f84f2 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_out_ctx_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_out_ctx_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_req_out_get_server.3 b/static/netbsd/man3/krb5_rd_req_out_get_server.3 new file mode 100644 index 00000000..d5e65cb3 --- /dev/null +++ b/static/netbsd/man3/krb5_rd_req_out_get_server.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_rd_req_out_get_server.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_auth.3 diff --git a/static/netbsd/man3/krb5_rd_safe.3 b/static/netbsd/man3/krb5_rd_safe.3 new file mode 100644 index 00000000..33647b1f --- /dev/null +++ b/static/netbsd/man3/krb5_rd_safe.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: krb5_rd_safe.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_RD_SAFE 3 +.Os +.Sh NAME +.Nm krb5_rd_safe , +.Nm krb5_rd_priv +.Nd verifies authenticity of messages +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Ft krb5_error_code +.Fn krb5_rd_priv "krb5_context context" "krb5_auth_context auth_context" "const krb5_data *inbuf" "krb5_data *outbuf" "krb5_replay_data *outdata" +.Ft krb5_error_code +.Fn krb5_rd_safe "krb5_context context" "krb5_auth_context auth_context" "const krb5_data *inbuf" "krb5_data *outbuf" "krb5_replay_data *outdata" +.Sh DESCRIPTION +.Fn krb5_rd_safe +and +.Fn krb5_rd_priv +parses +.Li KRB-SAFE +and +.Li KRB-PRIV +messages (as generated by +.Xr krb5_mk_safe 3 +and +.Xr krb5_mk_priv 3 ) +from +.Fa inbuf +and verifies its integrity. The user data part of the message in put +in +.Fa outbuf . +The encryption state, including keyblocks and addresses, is taken from +.Fa auth_context . +If the +.Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE +or +.Dv KRB5_AUTH_CONTEXT_RET_TIME +flags are set in the +.Fa auth_context +the sequence number and time are returned in the +.Fa outdata +parameter. +.Sh SEE ALSO +.Xr krb5_auth_con_init 3 , +.Xr krb5_mk_priv 3 , +.Xr krb5_mk_safe 3 diff --git a/static/netbsd/man3/krb5_realm_compare.3 b/static/netbsd/man3/krb5_realm_compare.3 new file mode 100644 index 00000000..232244e3 --- /dev/null +++ b/static/netbsd/man3/krb5_realm_compare.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_realm_compare.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_realm_is_lkdc.3 b/static/netbsd/man3/krb5_realm_is_lkdc.3 new file mode 100644 index 00000000..eff17ce1 --- /dev/null +++ b/static/netbsd/man3/krb5_realm_is_lkdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_realm_is_lkdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_ret_address.3 b/static/netbsd/man3/krb5_ret_address.3 new file mode 100644 index 00000000..62ad07e9 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_addrs.3 b/static/netbsd/man3/krb5_ret_addrs.3 new file mode 100644 index 00000000..422d4a72 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_addrs.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_addrs.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_authdata.3 b/static/netbsd/man3/krb5_ret_authdata.3 new file mode 100644 index 00000000..d475dab7 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_authdata.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_authdata.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_creds.3 b/static/netbsd/man3/krb5_ret_creds.3 new file mode 100644 index 00000000..9b77495b --- /dev/null +++ b/static/netbsd/man3/krb5_ret_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_creds_tag.3 b/static/netbsd/man3/krb5_ret_creds_tag.3 new file mode 100644 index 00000000..ebb6d774 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_creds_tag.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_creds_tag.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_data.3 b/static/netbsd/man3/krb5_ret_data.3 new file mode 100644 index 00000000..7d202ea4 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_int16.3 b/static/netbsd/man3/krb5_ret_int16.3 new file mode 100644 index 00000000..c7f3753c --- /dev/null +++ b/static/netbsd/man3/krb5_ret_int16.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_int16.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_int32.3 b/static/netbsd/man3/krb5_ret_int32.3 new file mode 100644 index 00000000..298a1450 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_int32.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_int32.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_int64.3 b/static/netbsd/man3/krb5_ret_int64.3 new file mode 100644 index 00000000..06be8a6b --- /dev/null +++ b/static/netbsd/man3/krb5_ret_int64.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_int64.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_int8.3 b/static/netbsd/man3/krb5_ret_int8.3 new file mode 100644 index 00000000..27127488 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_int8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_int8.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_keyblock.3 b/static/netbsd/man3/krb5_ret_keyblock.3 new file mode 100644 index 00000000..e9f5364c --- /dev/null +++ b/static/netbsd/man3/krb5_ret_keyblock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_keyblock.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_principal.3 b/static/netbsd/man3/krb5_ret_principal.3 new file mode 100644 index 00000000..8323ad1c --- /dev/null +++ b/static/netbsd/man3/krb5_ret_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_string.3 b/static/netbsd/man3/krb5_ret_string.3 new file mode 100644 index 00000000..b4cb31f8 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_stringz.3 b/static/netbsd/man3/krb5_ret_stringz.3 new file mode 100644 index 00000000..66b4681d --- /dev/null +++ b/static/netbsd/man3/krb5_ret_stringz.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_stringz.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_times.3 b/static/netbsd/man3/krb5_ret_times.3 new file mode 100644 index 00000000..3c6ad894 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_times.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_times.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_uint16.3 b/static/netbsd/man3/krb5_ret_uint16.3 new file mode 100644 index 00000000..1437e49e --- /dev/null +++ b/static/netbsd/man3/krb5_ret_uint16.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_uint16.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_uint32.3 b/static/netbsd/man3/krb5_ret_uint32.3 new file mode 100644 index 00000000..652b5f01 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_uint32.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_uint32.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_uint64.3 b/static/netbsd/man3/krb5_ret_uint64.3 new file mode 100644 index 00000000..570637bc --- /dev/null +++ b/static/netbsd/man3/krb5_ret_uint64.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_uint64.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_ret_uint8.3 b/static/netbsd/man3/krb5_ret_uint8.3 new file mode 100644 index 00000000..4a94b0c3 --- /dev/null +++ b/static/netbsd/man3/krb5_ret_uint8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ret_uint8.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_set_config_files.3 b/static/netbsd/man3/krb5_set_config_files.3 new file mode 100644 index 00000000..9758a6df --- /dev/null +++ b/static/netbsd/man3/krb5_set_config_files.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_config_files.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_default_in_tkt_etypes.3 b/static/netbsd/man3/krb5_set_default_in_tkt_etypes.3 new file mode 100644 index 00000000..d5b5d93b --- /dev/null +++ b/static/netbsd/man3/krb5_set_default_in_tkt_etypes.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_default_in_tkt_etypes.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_default_realm.3 b/static/netbsd/man3/krb5_set_default_realm.3 new file mode 100644 index 00000000..085c48c7 --- /dev/null +++ b/static/netbsd/man3/krb5_set_default_realm.3 @@ -0,0 +1,166 @@ +.\" $NetBSD: krb5_set_default_realm.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd April 24, 2005 +.Dt KRB5_SET_DEFAULT_REALM 3 +.Os +.Sh NAME +.Nm krb5_copy_host_realm , +.Nm krb5_free_host_realm , +.Nm krb5_get_default_realm , +.Nm krb5_get_default_realms , +.Nm krb5_get_host_realm , +.Nm krb5_set_default_realm +.Nd default and host realm read and manipulation routines +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_copy_host_realm +.Fa "krb5_context context" +.Fa "const krb5_realm *from" +.Fa "krb5_realm **to" +.Fc +.Ft krb5_error_code +.Fo krb5_free_host_realm +.Fa "krb5_context context" +.Fa "krb5_realm *realmlist" +.Fc +.Ft krb5_error_code +.Fo krb5_get_default_realm +.Fa "krb5_context context" +.Fa "krb5_realm *realm" +.Fc +.Ft krb5_error_code +.Fo krb5_get_default_realms +.Fa "krb5_context context" +.Fa "krb5_realm **realm" +.Fc +.Ft krb5_error_code +.Fo krb5_get_host_realm +.Fa "krb5_context context" +.Fa "const char *host" +.Fa "krb5_realm **realms" +.Fc +.Ft krb5_error_code +.Fo krb5_set_default_realm +.Fa "krb5_context context" +.Fa "const char *realm" +.Fc +.Sh DESCRIPTION +.Fn krb5_copy_host_realm +copies the list of realms from +.Fa from +to +.Fa to . +.Fa to +should be freed by the caller using +.Fa krb5_free_host_realm . +.Pp +.Fn krb5_free_host_realm +frees all memory allocated by +.Fa realmlist . +.Pp +.Fn krb5_get_default_realm +returns the first default realm for this host. +The realm returned should be freed with +.Fn krb5_xfree . +.Pp +.Fn krb5_get_default_realms +returns a +.Dv NULL +terminated list of default realms for this context. +Realms returned by +.Fn krb5_get_default_realms +should be freed with +.Fn krb5_free_host_realm . +.Pp +.Fn krb5_get_host_realm +returns a +.Dv NULL +terminated list of realms for +.Fa host +by looking up the information in the +.Li [domain_realm] +in +.Pa krb5.conf +or in +.Li DNS . +If the mapping in +.Li [domain_realm] +results in the string +.Li dns_locate , +DNS is used to lookup the realm. +.Pp +When using +.Li DNS +to a resolve the domain for the host a.b.c, +.Fn krb5_get_host_realm +looks for a +.Dv TXT +resource record named +.Li _kerberos.a.b.c , +and if not found, it strips off the first component and tries a again +(_kerberos.b.c) until it reaches the root. +.Pp +If there is no configuration or DNS information found, +.Fn krb5_get_host_realm +assumes it can use the domain part of the +.Fa host +to form a realm. +Caller must free +.Fa realmlist +with +.Fn krb5_free_host_realm . +.Pp +.Fn krb5_set_default_realm +sets the default realm for the +.Fa context . +If +.Dv NULL +is used as a +.Fa realm , +the +.Li [libdefaults]default_realm +stanza in +.Pa krb5.conf +is used. +If there is no such stanza in the configuration file, the +.Fn krb5_get_host_realm +function is used to form a default realm. +.Sh SEE ALSO +.Xr free 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_set_dns_canonicalize_hostname.3 b/static/netbsd/man3/krb5_set_dns_canonicalize_hostname.3 new file mode 100644 index 00000000..af73045b --- /dev/null +++ b/static/netbsd/man3/krb5_set_dns_canonicalize_hostname.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_dns_canonicalize_hostname.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_error_message.3 b/static/netbsd/man3/krb5_set_error_message.3 new file mode 100644 index 00000000..fba01fae --- /dev/null +++ b/static/netbsd/man3/krb5_set_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_set_error_string.3 b/static/netbsd/man3/krb5_set_error_string.3 new file mode 100644 index 00000000..4c851144 --- /dev/null +++ b/static/netbsd/man3/krb5_set_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_error_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_set_extra_addresses.3 b/static/netbsd/man3/krb5_set_extra_addresses.3 new file mode 100644 index 00000000..0785919c --- /dev/null +++ b/static/netbsd/man3/krb5_set_extra_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_extra_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_fcache_version.3 b/static/netbsd/man3/krb5_set_fcache_version.3 new file mode 100644 index 00000000..d55c8210 --- /dev/null +++ b/static/netbsd/man3/krb5_set_fcache_version.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_fcache_version.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_home_dir_access.3 b/static/netbsd/man3/krb5_set_home_dir_access.3 new file mode 100644 index 00000000..bacf8e16 --- /dev/null +++ b/static/netbsd/man3/krb5_set_home_dir_access.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_home_dir_access.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_ignore_addresses.3 b/static/netbsd/man3/krb5_set_ignore_addresses.3 new file mode 100644 index 00000000..18bc975a --- /dev/null +++ b/static/netbsd/man3/krb5_set_ignore_addresses.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_ignore_addresses.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_kdc_sec_offset.3 b/static/netbsd/man3/krb5_set_kdc_sec_offset.3 new file mode 100644 index 00000000..be2a78ba --- /dev/null +++ b/static/netbsd/man3/krb5_set_kdc_sec_offset.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_kdc_sec_offset.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_max_time_skew.3 b/static/netbsd/man3/krb5_set_max_time_skew.3 new file mode 100644 index 00000000..b6301fe1 --- /dev/null +++ b/static/netbsd/man3/krb5_set_max_time_skew.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_max_time_skew.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_password.3 b/static/netbsd/man3/krb5_set_password.3 new file mode 100644 index 00000000..7afb7273 --- /dev/null +++ b/static/netbsd/man3/krb5_set_password.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_password.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_real_time.3 b/static/netbsd/man3/krb5_set_real_time.3 new file mode 100644 index 00000000..0abda681 --- /dev/null +++ b/static/netbsd/man3/krb5_set_real_time.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_real_time.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_use_admin_kdc.3 b/static/netbsd/man3/krb5_set_use_admin_kdc.3 new file mode 100644 index 00000000..c8e1d4b0 --- /dev/null +++ b/static/netbsd/man3/krb5_set_use_admin_kdc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_use_admin_kdc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_set_warn_dest.3 b/static/netbsd/man3/krb5_set_warn_dest.3 new file mode 100644 index 00000000..4466551a --- /dev/null +++ b/static/netbsd/man3/krb5_set_warn_dest.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_set_warn_dest.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_sname_to_principal.3 b/static/netbsd/man3/krb5_sname_to_principal.3 new file mode 100644 index 00000000..31d9c04f --- /dev/null +++ b/static/netbsd/man3/krb5_sname_to_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_sname_to_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_sockaddr2address.3 b/static/netbsd/man3/krb5_sockaddr2address.3 new file mode 100644 index 00000000..66da7d36 --- /dev/null +++ b/static/netbsd/man3/krb5_sockaddr2address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_sockaddr2address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_sockaddr2port.3 b/static/netbsd/man3/krb5_sockaddr2port.3 new file mode 100644 index 00000000..6c9c64c7 --- /dev/null +++ b/static/netbsd/man3/krb5_sockaddr2port.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_sockaddr2port.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_sockaddr_uninteresting.3 b/static/netbsd/man3/krb5_sockaddr_uninteresting.3 new file mode 100644 index 00000000..3b9867e1 --- /dev/null +++ b/static/netbsd/man3/krb5_sockaddr_uninteresting.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_sockaddr_uninteresting.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_address.3 diff --git a/static/netbsd/man3/krb5_storage.3 b/static/netbsd/man3/krb5_storage.3 new file mode 100644 index 00000000..ca83d26b --- /dev/null +++ b/static/netbsd/man3/krb5_storage.3 @@ -0,0 +1,1136 @@ +.\" $NetBSD: krb5_storage.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_storage" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_storage \- Heimdal Kerberos 5 storage functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_storage_set_flags\fP (krb5_storage *sp, krb5_flags flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_storage_clear_flags\fP (krb5_storage *sp, krb5_flags flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_storage_is_flags\fP (krb5_storage *sp, krb5_flags flags)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_storage_set_byteorder\fP (krb5_storage *sp, krb5_flags byteorder)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_flags KRB5_LIB_CALL \fBkrb5_storage_get_byteorder\fP (krb5_storage *sp)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_storage_set_max_alloc\fP (krb5_storage *sp, size_t size)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION off_t KRB5_LIB_CALL \fBkrb5_storage_seek\fP (krb5_storage *sp, off_t offset, int whence)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_storage_truncate\fP (krb5_storage *sp, off_t offset)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_storage_fsync\fP (krb5_storage *sp)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL \fBkrb5_storage_read\fP (krb5_storage *sp, void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL \fBkrb5_storage_write\fP (krb5_storage *sp, const void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_storage_set_eof_code\fP (krb5_storage *sp, int code)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_storage_get_eof_code\fP (krb5_storage *sp)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_storage_free\fP (krb5_storage *sp)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_storage_to_data\fP (krb5_storage *sp, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_int32\fP (krb5_storage *sp, int32_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_int64\fP (krb5_storage *sp, int64_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_uint32\fP (krb5_storage *sp, uint32_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_uint64\fP (krb5_storage *sp, uint64_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_int64\fP (krb5_storage *sp, int64_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_uint64\fP (krb5_storage *sp, uint64_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_int32\fP (krb5_storage *sp, int32_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_uint32\fP (krb5_storage *sp, uint32_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_int16\fP (krb5_storage *sp, int16_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_uint16\fP (krb5_storage *sp, uint16_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_int16\fP (krb5_storage *sp, int16_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_uint16\fP (krb5_storage *sp, uint16_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_int8\fP (krb5_storage *sp, int8_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_uint8\fP (krb5_storage *sp, uint8_t value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_int8\fP (krb5_storage *sp, int8_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_uint8\fP (krb5_storage *sp, uint8_t *value)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_data\fP (krb5_storage *sp, krb5_data data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_data\fP (krb5_storage *sp, krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_string\fP (krb5_storage *sp, const char *s)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_string\fP (krb5_storage *sp, char **string)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_stringz\fP (krb5_storage *sp, const char *s)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_stringz\fP (krb5_storage *sp, char **string)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_principal\fP (krb5_storage *sp, krb5_const_principal p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_principal\fP (krb5_storage *sp, krb5_principal *princ)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_keyblock\fP (krb5_storage *sp, krb5_keyblock p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_keyblock\fP (krb5_storage *sp, krb5_keyblock *p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_times\fP (krb5_storage *sp, krb5_times times)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_times\fP (krb5_storage *sp, krb5_times *times)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_address\fP (krb5_storage *sp, krb5_address p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_address\fP (krb5_storage *sp, krb5_address *adr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_addrs\fP (krb5_storage *sp, krb5_addresses p)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_addrs\fP (krb5_storage *sp, krb5_addresses *adr)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_authdata\fP (krb5_storage *sp, krb5_authdata auth)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_authdata\fP (krb5_storage *sp, krb5_authdata *auth)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_creds\fP (krb5_storage *sp, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_creds\fP (krb5_storage *sp, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_store_creds_tag\fP (krb5_storage *sp, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_ret_creds_tag\fP (krb5_storage *sp, krb5_creds *creds)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_emem\fP (void)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_from_fd\fP (int fd_in)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_from_mem\fP (void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_from_data\fP (krb5_data *data)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_from_readonly_mem\fP (const void *buf, size_t len)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_storage *KRB5_LIB_CALL \fBkrb5_storage_from_socket\fP (krb5_socket_t sock_in)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_address (krb5_storage * sp, krb5_address * adr)" +Read a address block from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIadr\fP the address block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_addrs (krb5_storage * sp, krb5_addresses * adr)" +Read a addresses block from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIadr\fP the addresses block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_authdata (krb5_storage * sp, krb5_authdata * auth)" +Read a auth data from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIauth\fP the auth data block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_creds (krb5_storage * sp, krb5_creds * creds)" +Read a credentials block from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIcreds\fP the credentials block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_creds_tag (krb5_storage * sp, krb5_creds * creds)" +Read a tagged credentials block from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIcreds\fP the credentials block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_data (krb5_storage * sp, krb5_data * data)" +Parse a data from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to read from +.br +\fIdata\fP the parsed data +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int16 (krb5_storage * sp, int16_t * value)" +Read a int16 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int32 (krb5_storage * sp, int32_t * value)" +Read a int32 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int64 (krb5_storage * sp, int64_t * value)" +Read a int64 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_int8 (krb5_storage * sp, int8_t * value)" +Read a int8 from storage +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_keyblock (krb5_storage * sp, krb5_keyblock * p)" +Read a keyblock from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIp\fP the keyblock read from storage, free using \fBkrb5_free_keyblock()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_principal (krb5_storage * sp, krb5_principal * princ)" +Parse principal from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to read from +.br +\fIprinc\fP the parsed principal +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_string (krb5_storage * sp, char ** string)" +Parse a string from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to read from +.br +\fIstring\fP the parsed string +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_stringz (krb5_storage * sp, char ** string)" +Parse zero terminated string from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to read from +.br +\fIstring\fP the parsed string +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_times (krb5_storage * sp, krb5_times * times)" +Read a times block from the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fItimes\fP the times block read from storage +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint16 (krb5_storage * sp, uint16_t * value)" +Read a int16 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint32 (krb5_storage * sp, uint32_t * value)" +Read a uint32 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint64 (krb5_storage * sp, uint64_t * value)" +Read a uint64 from storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_ret_uint8 (krb5_storage * sp, uint8_t * value)" +Read a uint8 from storage +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value read from the buffer +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_clear_flags (krb5_storage * sp, krb5_flags flags)" +Clear the flags on a storage buffer +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to clear the flags on +.br +\fIflags\fP the flags to clear +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_emem (void)" +Create a elastic (allocating) memory storage backend\&. Memory is allocated on demand\&. Free returned krb5_storage with \fBkrb5_storage_free()\fP\&. +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_storage_from_mem()\fP +.PP +\fBkrb5_storage_from_readonly_mem()\fP +.PP +\fBkrb5_storage_from_fd()\fP +.PP +\fBkrb5_storage_from_data()\fP +.PP +\fBkrb5_storage_from_socket()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_storage_free (krb5_storage * sp)" +Free a krb5 storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to free\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An Kerberos 5 error code\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_from_data (krb5_data * data)" +Create a fixed size memory storage block +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +krb5_storage_mem() +.PP +\fBkrb5_storage_from_mem()\fP +.PP +\fBkrb5_storage_from_readonly_mem()\fP +.PP +\fBkrb5_storage_from_fd()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_from_fd (int fd_in)" + +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_storage_emem()\fP +.PP +\fBkrb5_storage_from_mem()\fP +.PP +\fBkrb5_storage_from_readonly_mem()\fP +.PP +\fBkrb5_storage_from_data()\fP +.PP +\fBkrb5_storage_from_socket()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_from_mem (void * buf, size_t len)" +Create a fixed size memory storage block +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +krb5_storage_mem() +.PP +\fBkrb5_storage_from_readonly_mem()\fP +.PP +\fBkrb5_storage_from_data()\fP +.PP +\fBkrb5_storage_from_fd()\fP +.PP +\fBkrb5_storage_from_socket()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_from_readonly_mem (const void * buf, size_t len)" +Create a fixed size memory storage block that is read only +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +krb5_storage_mem() +.PP +\fBkrb5_storage_from_mem()\fP +.PP +\fBkrb5_storage_from_data()\fP +.PP +\fBkrb5_storage_from_fd()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_storage* KRB5_LIB_CALL krb5_storage_from_socket (krb5_socket_t sock_in)" + +.PP +\fBReturns\fP +.RS 4 +A krb5_storage on success, or NULL on out of memory error\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_storage_emem()\fP +.PP +\fBkrb5_storage_from_mem()\fP +.PP +\fBkrb5_storage_from_readonly_mem()\fP +.PP +\fBkrb5_storage_from_data()\fP +.PP +\fBkrb5_storage_from_fd()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_storage_fsync (krb5_storage * sp)" +Sync the storage buffer to its backing store\&. If there is no backing store this function will return success\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to sync +.RE +.PP +\fBReturns\fP +.RS 4 +A Kerberos 5 error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_flags KRB5_LIB_CALL krb5_storage_get_byteorder (krb5_storage * sp)" +Return the current byteorder for the buffer\&. See \fBkrb5_storage_set_byteorder()\fP for the list or byte order contants\&. +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_storage_get_eof_code (krb5_storage * sp)" +Get the return code that will be used when end of storage is reached\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage +.RE +.PP +\fBReturns\fP +.RS 4 +storage error code +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_storage_is_flags (krb5_storage * sp, krb5_flags flags)" +Return true or false depending on if the storage flags is set or not\&. NB testing for the flag 0 always return true\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to check flags on +.br +\fIflags\fP The flags to test for +.RE +.PP +\fBReturns\fP +.RS 4 +true if all the flags are set, false if not\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL krb5_storage_read (krb5_storage * sp, void * buf, size_t len)" +Read to the storage buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to read from +.br +\fIbuf\fP the buffer to store the data in +.br +\fIlen\fP the length to read +.RE +.PP +\fBReturns\fP +.RS 4 +The length of data read (can be shorter then len), or negative on error\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION off_t KRB5_LIB_CALL krb5_storage_seek (krb5_storage * sp, off_t offset, int whence)" +Seek to a new offset\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to seek in\&. +.br +\fIoffset\fP the offset to seek +.br +\fIwhence\fP relateive searching, SEEK_CUR from the current position, SEEK_END from the end, SEEK_SET absolute from the start\&. +.RE +.PP +\fBReturns\fP +.RS 4 +The new current offset +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_byteorder (krb5_storage * sp, krb5_flags byteorder)" +Set the new byte order of the storage buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to set the byte order for\&. +.br +\fIbyteorder\fP the new byte order\&. +.RE +.PP +The byte order are: KRB5_STORAGE_BYTEORDER_BE, KRB5_STORAGE_BYTEORDER_LE and KRB5_STORAGE_BYTEORDER_HOST\&. +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_eof_code (krb5_storage * sp, int code)" +Set the return code that will be used when end of storage is reached\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage +.br +\fIcode\fP the error code to return on end of storage +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_flags (krb5_storage * sp, krb5_flags flags)" +Add the flags on a storage buffer by or-ing in the flags to the buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to set the flags on +.br +\fIflags\fP the flags to set +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_storage_set_max_alloc (krb5_storage * sp, size_t size)" +Set the max alloc value +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer set the max allow for +.br +\fIsize\fP maximum size to allocate, use 0 to remove limit +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_storage_to_data (krb5_storage * sp, krb5_data * data)" +Copy the contnent of storage +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to copy to a data +.br +\fIdata\fP the copied data, free with \fBkrb5_data_free()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_storage_truncate (krb5_storage * sp, off_t offset)" +Truncate the storage buffer in sp to offset\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to truncate\&. +.br +\fIoffset\fP the offset to truncate too\&. +.RE +.PP +\fBReturns\fP +.RS 4 +An Kerberos 5 error code\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_ssize_t KRB5_LIB_CALL krb5_storage_write (krb5_storage * sp, const void * buf, size_t len)" +Write to the storage buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIbuf\fP the buffer to write to the storage buffer +.br +\fIlen\fP the length to write +.RE +.PP +\fBReturns\fP +.RS 4 +The length of data written (can be shorter then len), or negative on error\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_address (krb5_storage * sp, krb5_address p)" +Write a address block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIp\fP the address block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_addrs (krb5_storage * sp, krb5_addresses p)" +Write a addresses block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIp\fP the addresses block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_authdata (krb5_storage * sp, krb5_authdata auth)" +Write a auth data block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIauth\fP the auth data block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_creds (krb5_storage * sp, krb5_creds * creds)" +Write a credentials block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIcreds\fP the creds block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_creds_tag (krb5_storage * sp, krb5_creds * creds)" +Write a tagged credentials block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIcreds\fP the creds block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_data (krb5_storage * sp, krb5_data data)" +Store a data to the storage\&. The data is stored with an int32 as lenght plus the data (not padded)\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIdata\fP the buffer to store\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int16 (krb5_storage * sp, int16_t value)" +Store a int16 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int32 (krb5_storage * sp, int32_t value)" +Store a int32 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int64 (krb5_storage * sp, int64_t value)" +Store a int64 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_int8 (krb5_storage * sp, int8_t value)" +Store a int8 to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_keyblock (krb5_storage * sp, krb5_keyblock p)" +Store a keyblock to the storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIp\fP the keyblock to write +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_principal (krb5_storage * sp, krb5_const_principal p)" +Write a principal block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIp\fP the principal block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_string (krb5_storage * sp, const char * s)" +Store a string to the buffer\&. The data is formated as an len:uint32 plus the string itself (not padded)\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIs\fP the string to store\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_stringz (krb5_storage * sp, const char * s)" +Store a zero terminated string to the buffer\&. The data is stored one character at a time until a NUL is stored\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fIs\fP the string to store\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_times (krb5_storage * sp, krb5_times times)" +Write a times block to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage buffer to write to +.br +\fItimes\fP the times block to write\&. +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint16 (krb5_storage * sp, uint16_t value)" +Store a uint16 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint32 (krb5_storage * sp, uint32_t value)" +Store a uint32 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint64 (krb5_storage * sp, uint64_t value)" +Store a uint64 to storage, byte order is controlled by the settings on the storage, see \fBkrb5_storage_set_byteorder()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_store_uint8 (krb5_storage * sp, uint8_t value)" +Store a uint8 to storage\&. +.PP +\fBParameters\fP +.RS 4 +\fIsp\fP the storage to write too +.br +\fIvalue\fP the value to store +.RE +.PP +\fBReturns\fP +.RS 4 +0 for success, or a Kerberos 5 error code on failure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_storage_clear_flags.3 b/static/netbsd/man3/krb5_storage_clear_flags.3 new file mode 100644 index 00000000..82664ff3 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_clear_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_clear_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_emem.3 b/static/netbsd/man3/krb5_storage_emem.3 new file mode 100644 index 00000000..171bf6c2 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_emem.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_emem.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_free.3 b/static/netbsd/man3/krb5_storage_free.3 new file mode 100644 index 00000000..01265d37 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_free.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_free.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_from_data.3 b/static/netbsd/man3/krb5_storage_from_data.3 new file mode 100644 index 00000000..94688dd5 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_from_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_from_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_from_fd.3 b/static/netbsd/man3/krb5_storage_from_fd.3 new file mode 100644 index 00000000..279b382c --- /dev/null +++ b/static/netbsd/man3/krb5_storage_from_fd.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_from_fd.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_from_mem.3 b/static/netbsd/man3/krb5_storage_from_mem.3 new file mode 100644 index 00000000..57932dd7 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_from_mem.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_from_mem.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_from_readonly_mem.3 b/static/netbsd/man3/krb5_storage_from_readonly_mem.3 new file mode 100644 index 00000000..2084137b --- /dev/null +++ b/static/netbsd/man3/krb5_storage_from_readonly_mem.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_from_readonly_mem.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_from_socket.3 b/static/netbsd/man3/krb5_storage_from_socket.3 new file mode 100644 index 00000000..a66e6a46 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_from_socket.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_from_socket.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_fsync.3 b/static/netbsd/man3/krb5_storage_fsync.3 new file mode 100644 index 00000000..35f125c8 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_fsync.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_fsync.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_get_byteorder.3 b/static/netbsd/man3/krb5_storage_get_byteorder.3 new file mode 100644 index 00000000..1b483251 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_get_byteorder.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_get_byteorder.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_get_eof_code.3 b/static/netbsd/man3/krb5_storage_get_eof_code.3 new file mode 100644 index 00000000..dbaaa3dc --- /dev/null +++ b/static/netbsd/man3/krb5_storage_get_eof_code.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_get_eof_code.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_is_flags.3 b/static/netbsd/man3/krb5_storage_is_flags.3 new file mode 100644 index 00000000..466174ec --- /dev/null +++ b/static/netbsd/man3/krb5_storage_is_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_is_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_read.3 b/static/netbsd/man3/krb5_storage_read.3 new file mode 100644 index 00000000..6533dbe1 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_read.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_read.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_seek.3 b/static/netbsd/man3/krb5_storage_seek.3 new file mode 100644 index 00000000..a2a79e67 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_seek.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_seek.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_set_byteorder.3 b/static/netbsd/man3/krb5_storage_set_byteorder.3 new file mode 100644 index 00000000..2fe20bde --- /dev/null +++ b/static/netbsd/man3/krb5_storage_set_byteorder.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_set_byteorder.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_set_eof_code.3 b/static/netbsd/man3/krb5_storage_set_eof_code.3 new file mode 100644 index 00000000..88a367b7 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_set_eof_code.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_set_eof_code.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_set_flags.3 b/static/netbsd/man3/krb5_storage_set_flags.3 new file mode 100644 index 00000000..a380d46d --- /dev/null +++ b/static/netbsd/man3/krb5_storage_set_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_set_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_set_max_alloc.3 b/static/netbsd/man3/krb5_storage_set_max_alloc.3 new file mode 100644 index 00000000..a61c34b0 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_set_max_alloc.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_set_max_alloc.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_to_data.3 b/static/netbsd/man3/krb5_storage_to_data.3 new file mode 100644 index 00000000..172da1c2 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_to_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_to_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_truncate.3 b/static/netbsd/man3/krb5_storage_truncate.3 new file mode 100644 index 00000000..b85433ae --- /dev/null +++ b/static/netbsd/man3/krb5_storage_truncate.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_truncate.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_storage_write.3 b/static/netbsd/man3/krb5_storage_write.3 new file mode 100644 index 00000000..5db5c7f9 --- /dev/null +++ b/static/netbsd/man3/krb5_storage_write.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_storage_write.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_address.3 b/static/netbsd/man3/krb5_store_address.3 new file mode 100644 index 00000000..ec281e35 --- /dev/null +++ b/static/netbsd/man3/krb5_store_address.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_address.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_addrs.3 b/static/netbsd/man3/krb5_store_addrs.3 new file mode 100644 index 00000000..7654e2ba --- /dev/null +++ b/static/netbsd/man3/krb5_store_addrs.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_addrs.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_authdata.3 b/static/netbsd/man3/krb5_store_authdata.3 new file mode 100644 index 00000000..2879d64f --- /dev/null +++ b/static/netbsd/man3/krb5_store_authdata.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_authdata.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_creds.3 b/static/netbsd/man3/krb5_store_creds.3 new file mode 100644 index 00000000..18db24af --- /dev/null +++ b/static/netbsd/man3/krb5_store_creds.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_creds.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_creds_tag.3 b/static/netbsd/man3/krb5_store_creds_tag.3 new file mode 100644 index 00000000..5735defd --- /dev/null +++ b/static/netbsd/man3/krb5_store_creds_tag.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_creds_tag.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_data.3 b/static/netbsd/man3/krb5_store_data.3 new file mode 100644 index 00000000..f15fd6a1 --- /dev/null +++ b/static/netbsd/man3/krb5_store_data.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_data.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_int16.3 b/static/netbsd/man3/krb5_store_int16.3 new file mode 100644 index 00000000..5898e917 --- /dev/null +++ b/static/netbsd/man3/krb5_store_int16.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_int16.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_int32.3 b/static/netbsd/man3/krb5_store_int32.3 new file mode 100644 index 00000000..984cc607 --- /dev/null +++ b/static/netbsd/man3/krb5_store_int32.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_int32.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_int64.3 b/static/netbsd/man3/krb5_store_int64.3 new file mode 100644 index 00000000..9b3174d7 --- /dev/null +++ b/static/netbsd/man3/krb5_store_int64.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_int64.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_int8.3 b/static/netbsd/man3/krb5_store_int8.3 new file mode 100644 index 00000000..175941c7 --- /dev/null +++ b/static/netbsd/man3/krb5_store_int8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_int8.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_keyblock.3 b/static/netbsd/man3/krb5_store_keyblock.3 new file mode 100644 index 00000000..94612570 --- /dev/null +++ b/static/netbsd/man3/krb5_store_keyblock.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_keyblock.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_principal.3 b/static/netbsd/man3/krb5_store_principal.3 new file mode 100644 index 00000000..1afb7bc4 --- /dev/null +++ b/static/netbsd/man3/krb5_store_principal.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_principal.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_string.3 b/static/netbsd/man3/krb5_store_string.3 new file mode 100644 index 00000000..d3c7072f --- /dev/null +++ b/static/netbsd/man3/krb5_store_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_stringz.3 b/static/netbsd/man3/krb5_store_stringz.3 new file mode 100644 index 00000000..0b28a922 --- /dev/null +++ b/static/netbsd/man3/krb5_store_stringz.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_stringz.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_times.3 b/static/netbsd/man3/krb5_store_times.3 new file mode 100644 index 00000000..620797dc --- /dev/null +++ b/static/netbsd/man3/krb5_store_times.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_times.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_uint16.3 b/static/netbsd/man3/krb5_store_uint16.3 new file mode 100644 index 00000000..285bddc0 --- /dev/null +++ b/static/netbsd/man3/krb5_store_uint16.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_uint16.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_uint32.3 b/static/netbsd/man3/krb5_store_uint32.3 new file mode 100644 index 00000000..efcb254a --- /dev/null +++ b/static/netbsd/man3/krb5_store_uint32.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_uint32.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_uint64.3 b/static/netbsd/man3/krb5_store_uint64.3 new file mode 100644 index 00000000..62d6acd3 --- /dev/null +++ b/static/netbsd/man3/krb5_store_uint64.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_uint64.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_store_uint8.3 b/static/netbsd/man3/krb5_store_uint8.3 new file mode 100644 index 00000000..b02d8fe3 --- /dev/null +++ b/static/netbsd/man3/krb5_store_uint8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_store_uint8.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_storage.3 diff --git a/static/netbsd/man3/krb5_string_to_key.3 b/static/netbsd/man3/krb5_string_to_key.3 new file mode 100644 index 00000000..1b5a774c --- /dev/null +++ b/static/netbsd/man3/krb5_string_to_key.3 @@ -0,0 +1,158 @@ +.\" $NetBSD: krb5_string_to_key.3,v 1.5 2023/06/19 21:41:44 christos Exp $ +.\" +.\" Copyright (c) 2004 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd July 10, 2006 +.Dt KRB5_STRING_TO_KEY 3 +.Os +.Sh NAME +.Nm krb5_string_to_key , +.Nm krb5_string_to_key_data , +.Nm krb5_string_to_key_data_salt , +.Nm krb5_string_to_key_data_salt_opaque , +.Nm krb5_string_to_key_salt , +.Nm krb5_string_to_key_salt_opaque , +.Nm krb5_get_pw_salt , +.Nm krb5_free_salt +.Nd turns a string to a Kerberos key +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fo krb5_string_to_key +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "const char *password" +.Fa "krb5_principal principal" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_key_data +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "krb5_data password" +.Fa "krb5_principal principal" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_key_data_salt +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "krb5_data password" +.Fa "krb5_salt salt" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_key_data_salt_opaque +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "krb5_data password" +.Fa "krb5_salt salt" +.Fa "krb5_data opaque" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_key_salt +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "const char *password" +.Fa "krb5_salt salt" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_key_salt_opaque +.Fa "krb5_context context" +.Fa "krb5_enctype enctype" +.Fa "const char *password" +.Fa "krb5_salt salt" +.Fa "krb5_data opaque" +.Fa "krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_get_pw_salt +.Fa "krb5_context context" +.Fa "krb5_const_principal principal" +.Fa "krb5_salt *salt" +.Fc +.Ft krb5_error_code +.Fo krb5_free_salt +.Fa "krb5_context context" +.Fa "krb5_salt salt" +.Fc +.Sh DESCRIPTION +The string to key functions convert a string to a kerberos key. +.Pp +.Fn krb5_string_to_key_data_salt_opaque +is the function that does all the work, the rest of the functions are +just wrappers around +.Fn krb5_string_to_key_data_salt_opaque +that calls it with default values. +.Pp +.Fn krb5_string_to_key_data_salt_opaque +transforms the +.Fa password +with the given salt-string +.Fa salt +and the opaque, encryption type specific parameter +.Fa opaque +to a encryption key +.Fa key +according to the string to key function associated with +.Fa enctype . +.Pp +The +.Fa key +should be freed with +.Fn krb5_free_keyblock_contents . +.Pp +If one of the functions that doesn't take a +.Li krb5_salt +as it argument +.Fn krb5_get_pw_salt +is used to get the salt value. +.Pp +.Fn krb5_get_pw_salt +get the default password salt for a principal, use +.Fn krb5_free_salt +to free the salt when done. +.Pp +.Fn krb5_free_salt +frees the content of +.Fa salt . +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_data 3 , +.Xr krb5_keyblock 3 , +.Xr kerberos 8 diff --git a/static/netbsd/man3/krb5_string_to_keytype.3 b/static/netbsd/man3/krb5_string_to_keytype.3 new file mode 100644 index 00000000..ecde1793 --- /dev/null +++ b/static/netbsd/man3/krb5_string_to_keytype.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_string_to_keytype.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_support.3 b/static/netbsd/man3/krb5_support.3 new file mode 100644 index 00000000..ed749fd7 --- /dev/null +++ b/static/netbsd/man3/krb5_support.3 @@ -0,0 +1,668 @@ +.\" $NetBSD: krb5_support.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_support" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_support \- Heimdal Kerberos 5 support functions +.SH SYNOPSIS +.br +.PP +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBkrb5plugin_an2ln_ftable_desc\fP" +.br +.RI "Description of the krb5_aname_to_lname(3) plugin facility\&. " +.ti -1c +.RI "struct \fBkrb5plugin_db_ftable_desc\fP" +.br +.RI "Description of the krb5 DB plugin facility\&. " +.ti -1c +.RI "struct \fBkrb5plugin_kuserok_ftable_desc\fP" +.br +.RI "Description of the krb5_kuserok(3) plugin facility\&. " +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_acl_match_string\fP (krb5_context context, const char *string, const char *format,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_acl_match_file\fP (krb5_context context, const char *file, const char *format,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_aname_to_localname\fP (krb5_context context, krb5_const_principal aname, size_t lnsize, char *lname)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_config_parse_file_multi\fP (krb5_context context, const char *fname, krb5_config_section **res)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_config_file_free\fP (krb5_context context, krb5_config_section *s)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const krb5_config_binding *KRB5_LIB_CALL \fBkrb5_config_get_list\fP (krb5_context context, const krb5_config_section *c,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const krb5_config_binding *KRB5_LIB_CALL \fBkrb5_config_vget_list\fP (krb5_context context, const krb5_config_section *c, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_config_get_string\fP (krb5_context context, const krb5_config_section *c,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_config_vget_string\fP (krb5_context context, const krb5_config_section *c, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_config_vget_string_default\fP (krb5_context context, const krb5_config_section *c, const char *def_value, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_config_get_string_default\fP (krb5_context context, const krb5_config_section *c, const char *def_value,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION char **KRB5_LIB_CALL \fBkrb5_config_vget_strings\fP (krb5_context context, const krb5_config_section *c, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION char **KRB5_LIB_CALL \fBkrb5_config_get_strings\fP (krb5_context context, const krb5_config_section *c,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_config_free_strings\fP (char **strings)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_config_vget_bool_default\fP (krb5_context context, const krb5_config_section *c, krb5_boolean def_value, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_config_vget_bool\fP (krb5_context context, const krb5_config_section *c, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_config_get_bool_default\fP (krb5_context context, const krb5_config_section *c, krb5_boolean def_value,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_config_get_bool\fP (krb5_context context, const krb5_config_section *c,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_config_vget_time_default\fP (krb5_context context, const krb5_config_section *c, int def_value, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_config_vget_time\fP (krb5_context context, const krb5_config_section *c, va_list args)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_config_get_time_default\fP (krb5_context context, const krb5_config_section *c, int def_value,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_config_get_time\fP (krb5_context context, const krb5_config_section *c,\&.\&.\&.)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_expand_hostname\fP (krb5_context context, const char *orig_hostname, char **new_hostname)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_expand_hostname_realms\fP (krb5_context context, const char *orig_hostname, char **new_hostname, char ***realms)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_free_host_realm\fP (krb5_context context, krb5_realm *realmlist)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_kuserok\fP (krb5_context context, krb5_principal principal, const char *luser)" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_plugin_register\fP (krb5_context context, enum krb5_plugin_type type, const char *name, void *symbol)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_acl_match_file (krb5_context context, const char * file, const char * format, \&.\&.\&.)" +krb5_acl_match_file matches ACL format against each line in a file using \fBkrb5_acl_match_string()\fP\&. Lines starting with # are treated like comments and ignored\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIfile\fP file with acl listed in the file\&. +.br +\fIformat\fP format to match\&. +.br +\fI\&.\&.\&.\fP parameter to format string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_acl_match_string\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_acl_match_string (krb5_context context, const char * string, const char * format, \&.\&.\&.)" +krb5_acl_match_string matches ACL format against a string\&. +.PP +The ACL format has three format specifiers: s, f, and r\&. Each specifier will retrieve one argument from the variable arguments for either matching or storing data\&. The input string is split up using ' ' (space) and '\\t' (tab) as a delimiter; multiple and '\\t' in a row are considered to be the same\&. +.PP +List of format specifiers: +.IP "\(bu" 2 +s Matches a string using strcmp(3) (case sensitive)\&. +.IP "\(bu" 2 +f Matches the string with fnmatch(3)\&. Theflags argument (the last argument) passed to the fnmatch function is 0\&. +.IP "\(bu" 2 +r Returns a copy of the string in the char ** passed in; the copy must be freed with free(3)\&. There is no need to free(3) the string on error: the function will clean up and set the pointer to NULL\&. +.PP +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context +.br +\fIstring\fP string to match with +.br +\fIformat\fP format to match +.br +\fI\&.\&.\&.\fP parameter to format string +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0\&. +.RE +.PP +.PP +.nf +char *s; + +ret = krb5_acl_match_string(context, "foo", "s", "foo"); +if (ret) + krb5_errx(context, 1, "acl didn't match"); +ret = krb5_acl_match_string(context, "foo foo baz/kaka", + "ss", "foo", &s, "foo/\\*"); +if (ret) { + // no need to free(s) on error + assert(s == NULL); + krb5_errx(context, 1, "acl didn't match"); +} +free(s); +.fi +.PP +.PP +\fBSee also\fP +.RS 4 +\fBkrb5_acl_match_file\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_aname_to_localname (krb5_context context, krb5_const_principal aname, size_t lnsize, char * lname)" +Map a principal name to a local username\&. +.PP +Returns 0 on success, KRB5_NO_LOCALNAME if no mapping was found, or some Kerberos or system error\&. +.PP +Inputs: +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A krb5_context +.br +\fIaname\fP A principal name +.br +\fIlnsize\fP The size of the buffer into which the username will be written +.br +\fIlname\fP The buffer into which the username will be written +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_file_free (krb5_context context, krb5_config_section * s)" +Free configuration file section, the result of krb5_config_parse_file() and \fBkrb5_config_parse_file_multi()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context +.br +\fIs\fP the configuration section to free +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on successes, otherwise an error code, see \fBkrb5_get_error_message()\fP +.RE +.PP + +.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_config_free_strings (char ** strings)" +Free the resulting strings from krb5_config-get_strings() and \fBkrb5_config_vget_strings()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIstrings\fP strings to free +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_get_bool (krb5_context context, const krb5_config_section * c, \&.\&.\&.)" +Like \fBkrb5_config_get_bool()\fP but with a va_list list of configuration selection\&. +.PP +Configuration value to a boolean value, where yes/true and any non-zero number means TRUE and other value is FALSE\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_get_bool_default (krb5_context context, const krb5_config_section * c, krb5_boolean def_value, \&.\&.\&.)" +\fBkrb5_config_get_bool_default()\fP will convert the configuration option value to a boolean value, where yes/true and any non-zero number means TRUE and other value is FALSE\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const krb5_config_binding* KRB5_LIB_CALL krb5_config_get_list (krb5_context context, const krb5_config_section * c, \&.\&.\&.)" +Get a list of configuration binding list for more processing +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +NULL if configuration list is not found, a list otherwise +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_get_string (krb5_context context, const krb5_config_section * c, \&.\&.\&.)" +Returns a 'const char *' to a string in the configuration database\&. The string may not be valid after a reload of the configuration database so a caller should make a local copy if it needs to keep the string\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +NULL if configuration string not found, a string otherwise +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_get_string_default (krb5_context context, const krb5_config_section * c, const char * def_value, \&.\&.\&.)" +Like \fBkrb5_config_get_string()\fP, but instead of returning NULL, instead return a default value\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +a configuration string +.RE +.PP + +.SS "KRB5_LIB_FUNCTION char** KRB5_LIB_CALL krb5_config_get_strings (krb5_context context, const krb5_config_section * c, \&.\&.\&.)" +Get a list of configuration strings, free the result with \fBkrb5_config_free_strings()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_get_time (krb5_context context, const krb5_config_section * c, \&.\&.\&.)" +Get the time from the configuration file using a relative time, for example: 1h30s +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +parsed the time or -1 on error +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_get_time_default (krb5_context context, const krb5_config_section * c, int def_value, \&.\&.\&.)" +Get the time from the configuration file using a relative time, for example: 1h30s +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fI\&.\&.\&.\fP a list of names, terminated with NULL\&. +.RE +.PP +\fBReturns\fP +.RS 4 +parsed the time (or def_value on parse error) +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_config_parse_file_multi (krb5_context context, const char * fname, krb5_config_section ** res)" +Parse a configuration file and add the result into res\&. This interface can be used to parse several configuration files into one resulting krb5_config_section by calling it repeatably\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Kerberos 5 context\&. +.br +\fIfname\fP a file name to a Kerberos configuration file +.br +\fIres\fP the returned result, must be free with \fBkrb5_free_config_files()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP +If the fname starts with '~/' parse configuration file in the current users home directory\&. The behavior can be disabled and enabled by calling \fBkrb5_set_home_dir_access()\fP\&. +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_vget_bool (krb5_context context, const krb5_config_section * c, va_list args)" +\fBkrb5_config_get_bool()\fP will convert the configuration option value to a boolean value, where yes/true and any non-zero number means TRUE and other value is FALSE\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_config_vget_bool_default (krb5_context context, const krb5_config_section * c, krb5_boolean def_value, va_list args)" +Like \fBkrb5_config_get_bool_default()\fP but with a va_list list of configuration selection\&. +.PP +Configuration value to a boolean value, where yes/true and any non-zero number means TRUE and other value is FALSE\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const krb5_config_binding* KRB5_LIB_CALL krb5_config_vget_list (krb5_context context, const krb5_config_section * c, va_list args)" +Get a list of configuration binding list for more processing +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +NULL if configuration list is not found, a list otherwise +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_vget_string (krb5_context context, const krb5_config_section * c, va_list args)" +Like \fBkrb5_config_get_string()\fP, but uses a va_list instead of \&.\&.\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +NULL if configuration string not found, a string otherwise +.RE +.PP + +.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_config_vget_string_default (krb5_context context, const krb5_config_section * c, const char * def_value, va_list args)" +Like \fBkrb5_config_vget_string()\fP, but instead of returning NULL, instead return a default value\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +a configuration string +.RE +.PP + +.SS "KRB5_LIB_FUNCTION char** KRB5_LIB_CALL krb5_config_vget_strings (krb5_context context, const krb5_config_section * c, va_list args)" +Get a list of configuration strings, free the result with \fBkrb5_config_free_strings()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +TRUE or FALSE +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_vget_time (krb5_context context, const krb5_config_section * c, va_list args)" +Get the time from the configuration file using a relative time, for example: 1h30s +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +parsed the time or -1 on error +.RE +.PP + +.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_config_vget_time_default (krb5_context context, const krb5_config_section * c, int def_value, va_list args)" +Get the time from the configuration file using a relative time\&. +.PP +Like \fBkrb5_config_get_time_default()\fP but with a va_list list of configuration selection\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIc\fP a configuration section, or NULL to use the section from context +.br +\fIdef_value\fP the default value to return if no configuration found in the database\&. +.br +\fIargs\fP a va_list of arguments +.RE +.PP +\fBReturns\fP +.RS 4 +parsed the time (or def_value on parse error) +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_expand_hostname (krb5_context context, const char * orig_hostname, char ** new_hostname)" +\fBkrb5_expand_hostname()\fP tries to make orig_hostname into a more canonical one in the newly allocated space returned in new_hostname\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIorig_hostname\fP hostname to canonicalise\&. +.br +\fInew_hostname\fP output hostname, caller must free hostname with krb5_xfree()\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_expand_hostname_realms (krb5_context context, const char * orig_hostname, char ** new_hostname, char *** realms)" +\fBkrb5_expand_hostname_realms()\fP expands orig_hostname to a name we believe to be a hostname in newly allocated space in new_hostname and return the realms new_hostname is believed to belong to in realms\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fIorig_hostname\fP hostname to canonicalise\&. +.br +\fInew_hostname\fP output hostname, caller must free hostname with krb5_xfree()\&. +.br +\fIrealms\fP output possible realms, is an array that is terminated with NULL\&. Caller must free with \fBkrb5_free_host_realm()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +Return an error code or 0, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_free_host_realm (krb5_context context, krb5_realm * realmlist)" +Free all memory allocated by `realmlist' +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP A Kerberos 5 context\&. +.br +\fIrealmlist\fP realmlist to free, NULL is ok +.RE +.PP +\fBReturns\fP +.RS 4 +a Kerberos error code, always 0\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_kuserok (krb5_context context, krb5_principal principal, const char * luser)" +This function takes the name of a local user and checks if principal is allowed to log in as that user\&. +.PP +The user may have a ~/\&.k5login file listing principals that are allowed to login as that user\&. If that file does not exist, all principals with a only one component that is identical to the username, and a realm considered local, are allowed access\&. +.PP +The \&.k5login file must contain one principal per line, be owned by user and not be writable by group or other (but must be readable by anyone)\&. +.PP +Note that if the file exists, no implicit access rights are given to user@LOCALREALM\&. +.PP +Optionally, a set of files may be put in ~/\&.k5login\&.d (a directory), in which case they will all be checked in the same manner as \&.k5login\&. The files may be called anything, but files starting with a hash (#) , or ending with a tilde (~) are ignored\&. Subdirectories are not traversed\&. Note that this directory may not be checked by other Kerberos implementations\&. +.PP +If no configuration file exists, match user against local domains, ie luser@LOCAL-REALMS-IN-CONFIGURATION-FILES\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIprincipal\fP principal to check if allowed to login +.br +\fIluser\fP local user id +.RE +.PP +\fBReturns\fP +.RS 4 +returns TRUE if access should be granted, FALSE otherwise\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_plugin_register (krb5_context context, enum krb5_plugin_type type, const char * name, void * symbol)" +Register a plugin symbol name of specific type\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP a Keberos context +.br +\fItype\fP type of plugin symbol +.br +\fIname\fP name of plugin symbol +.br +\fIsymbol\fP a pointer to the named symbol +.RE +.PP +\fBReturns\fP +.RS 4 +In case of error a non zero error com_err error is returned and the Kerberos error string is set\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_ticket.3 b/static/netbsd/man3/krb5_ticket.3 new file mode 100644 index 00000000..5fea5ad7 --- /dev/null +++ b/static/netbsd/man3/krb5_ticket.3 @@ -0,0 +1,41 @@ +.\" $NetBSD: krb5_ticket.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_ticket" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_ticket \- Heimdal Kerberos 5 ticket functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL \fBkrb5_ticket_get_flags\fP (krb5_context context, const krb5_ticket *ticket)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION unsigned long KRB5_LIB_CALL krb5_ticket_get_flags (krb5_context context, const krb5_ticket * ticket)" +Get the flags from the Kerberos ticket +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos context +.br +\fIticket\fP Kerberos ticket +.RE +.PP +\fBReturns\fP +.RS 4 +ticket flags +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_ticket_get_authorization_data_type.3 b/static/netbsd/man3/krb5_ticket_get_authorization_data_type.3 new file mode 100644 index 00000000..3aec6aaa --- /dev/null +++ b/static/netbsd/man3/krb5_ticket_get_authorization_data_type.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ticket_get_authorization_data_type.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_ticket_get_client.3 b/static/netbsd/man3/krb5_ticket_get_client.3 new file mode 100644 index 00000000..fc78a8f1 --- /dev/null +++ b/static/netbsd/man3/krb5_ticket_get_client.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ticket_get_client.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_ticket_get_endtime.3 b/static/netbsd/man3/krb5_ticket_get_endtime.3 new file mode 100644 index 00000000..eb1d3ed5 --- /dev/null +++ b/static/netbsd/man3/krb5_ticket_get_endtime.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ticket_get_endtime.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_ticket_get_flags.3 b/static/netbsd/man3/krb5_ticket_get_flags.3 new file mode 100644 index 00000000..b87d0e7c --- /dev/null +++ b/static/netbsd/man3/krb5_ticket_get_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ticket_get_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_ticket.3 diff --git a/static/netbsd/man3/krb5_ticket_get_server.3 b/static/netbsd/man3/krb5_ticket_get_server.3 new file mode 100644 index 00000000..e1822b8c --- /dev/null +++ b/static/netbsd/man3/krb5_ticket_get_server.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_ticket_get_server.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5.3 diff --git a/static/netbsd/man3/krb5_timeofday.3 b/static/netbsd/man3/krb5_timeofday.3 new file mode 100644 index 00000000..5b5f9d31 --- /dev/null +++ b/static/netbsd/man3/krb5_timeofday.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: krb5_timeofday.3,v 1.4 2023/06/19 21:41:44 christos Exp $ +.\" +.\" Id +.\" +.\" Copyright (c) 2001, 2003, 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd September 16, 2006 +.Dt KRB5_TIMEOFDAY 3 +.Os +.Sh NAME +.Nm krb5_timeofday , +.Nm krb5_set_real_time , +.Nm krb5_us_timeofday , +.Nm krb5_format_time , +.Nm krb5_string_to_deltat +.Nd Kerberos 5 time handling functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Li krb5_timestamp ; +.Pp +.Li krb5_deltat ; +.Ft krb5_error_code +.Fo krb5_set_real_time +.Fa "krb5_context context" +.Fa "krb5_timestamp sec" +.Fa "int32_t usec" +.Fc +.Ft krb5_error_code +.Fo krb5_timeofday +.Fa "krb5_context context" +.Fa "krb5_timestamp *timeret" +.Fc +.Ft krb5_error_code +.Fo krb5_us_timeofday +.Fa "krb5_context context" +.Fa "krb5_timestamp *sec" +.Fa "int32_t *usec" +.Fc +.Ft krb5_error_code +.Fo krb5_format_time +.Fa "krb5_context context" +.Fa "time_t t" +.Fa "char *s" +.Fa "size_t len" +.Fa "krb5_boolean include_time" +.Fc +.Ft krb5_error_code +.Fo krb5_string_to_deltat +.Fa "const char *string" +.Fa "krb5_deltat *deltat" +.Fc +.Sh DESCRIPTION +.Nm krb5_set_real_time +sets the absolute time that the caller knows the KDC has. +With this the Kerberos library can calculate the relative +difference between the KDC time and the local system time and store it +in the +.Fa context . +With this information the Kerberos library can adjust all time stamps +in Kerberos packages. +.Pp +.Fn krb5_timeofday +returns the current time, but adjusted with the time difference +between the local host and the KDC. +.Fn krb5_us_timeofday +also returns microseconds. +.Pp +.Nm krb5_format_time +formats the time +.Fa t +into the string +.Fa s +of length +.Fa len . +If +.Fa include_time +is set, the time is set include_time. +.Pp +.Nm krb5_string_to_deltat +parses delta time +.Fa string +into +.Fa deltat . +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr krb5 3 diff --git a/static/netbsd/man3/krb5_unparse_name.3 b/static/netbsd/man3/krb5_unparse_name.3 new file mode 100644 index 00000000..23a4fd9a --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_unparse_name_fixed.3 b/static/netbsd/man3/krb5_unparse_name_fixed.3 new file mode 100644 index 00000000..efa407fe --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name_fixed.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name_fixed.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_unparse_name_fixed_flags.3 b/static/netbsd/man3/krb5_unparse_name_fixed_flags.3 new file mode 100644 index 00000000..b48c6335 --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name_fixed_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name_fixed_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_unparse_name_fixed_short.3 b/static/netbsd/man3/krb5_unparse_name_fixed_short.3 new file mode 100644 index 00000000..fd569d39 --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name_fixed_short.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name_fixed_short.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_unparse_name_flags.3 b/static/netbsd/man3/krb5_unparse_name_flags.3 new file mode 100644 index 00000000..45fd4db3 --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name_flags.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name_flags.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_unparse_name_short.3 b/static/netbsd/man3/krb5_unparse_name_short.3 new file mode 100644 index 00000000..2fee6c21 --- /dev/null +++ b/static/netbsd/man3/krb5_unparse_name_short.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_unparse_name_short.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_principal.3 diff --git a/static/netbsd/man3/krb5_v4compat.3 b/static/netbsd/man3/krb5_v4compat.3 new file mode 100644 index 00000000..73386118 --- /dev/null +++ b/static/netbsd/man3/krb5_v4compat.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: krb5_v4compat.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5_v4compat" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5_v4compat \- Heimdal Kerberos 4 compatiblity functions +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb524_convert_creds_kdc\fP (krb5_context context, krb5_creds *in_cred, struct credentials *v4creds) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.ti -1c +.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb524_convert_creds_kdc_ccache\fP (krb5_context context, krb5_ccache ccache, krb5_creds *in_cred, struct credentials *v4creds) KRB5_DEPRECATED_FUNCTION('Use X instead')" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb524_convert_creds_kdc (krb5_context context, krb5_creds * in_cred, struct credentials * v4creds)" +Convert the v5 credentials in in_cred to v4-dito in v4creds\&. This is done by sending them to the 524 function in the KDC\&. If `in_cred' doesn't contain a DES session key, then a new one is gotten from the KDC and stored in the cred cache `ccache'\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIin_cred\fP the credential to convert +.br +\fIv4creds\fP the converted credential +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb524_convert_creds_kdc_ccache (krb5_context context, krb5_ccache ccache, krb5_creds * in_cred, struct credentials * v4creds)" +Convert the v5 credentials in in_cred to v4-dito in v4creds, check the credential cache ccache before checking with the KDC\&. +.PP +\fBParameters\fP +.RS 4 +\fIcontext\fP Kerberos 5 context\&. +.br +\fIccache\fP credential cache used to check for des-ticket\&. +.br +\fIin_cred\fP the credential to convert +.br +\fIv4creds\fP the converted credential +.RE +.PP +\fBReturns\fP +.RS 4 +Returns 0 to indicate success\&. Otherwise an kerberos et error code is returned, see \fBkrb5_get_error_message()\fP\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5_vabort.3 b/static/netbsd/man3/krb5_vabort.3 new file mode 100644 index 00000000..f25a11cd --- /dev/null +++ b/static/netbsd/man3/krb5_vabort.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vabort.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_verify_checksum_iov.3 b/static/netbsd/man3/krb5_verify_checksum_iov.3 new file mode 100644 index 00000000..16607e94 --- /dev/null +++ b/static/netbsd/man3/krb5_verify_checksum_iov.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_verify_checksum_iov.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_crypto.3 diff --git a/static/netbsd/man3/krb5_verify_init_creds.3 b/static/netbsd/man3/krb5_verify_init_creds.3 new file mode 100644 index 00000000..7393427a --- /dev/null +++ b/static/netbsd/man3/krb5_verify_init_creds.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: krb5_verify_init_creds.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2003 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_VERIFY_INIT_CREDS 3 +.Os +.Sh NAME +.Nm krb5_verify_init_creds_opt_init , +.Nm krb5_verify_init_creds_opt_set_ap_req_nofail , +.Nm krb5_verify_init_creds +.Nd "verifies a credential cache is correct by using a local keytab" +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Pp +.Li "struct krb5_verify_init_creds_opt;" +.Ft void +.Fo krb5_verify_init_creds_opt_init +.Fa "krb5_verify_init_creds_opt *options" +.Fc +.Ft void +.Fo krb5_verify_init_creds_opt_set_ap_req_nofail +.Fa "krb5_verify_init_creds_opt *options" +.Fa "int ap_req_nofail" +.Fc +.Ft krb5_error_code +.Fo krb5_verify_init_creds +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_principal ap_req_server" +.Fa "krb5_ccache *ccache" +.Fa "krb5_verify_init_creds_opt *options" +.Fc +.Sh DESCRIPTION +The +.Nm krb5_verify_init_creds +function verifies the initial tickets with the local keytab to make +sure the response of the KDC was spoof-ed. +.Pp +.Nm krb5_verify_init_creds +will use principal +.Fa ap_req_server +from the local keytab, if +.Dv NULL +is passed in, the code will guess the local hostname and use that to +form host/hostname/GUESSED-REALM-FOR-HOSTNAME. +.Fa creds +is the credential that +.Nm krb5_verify_init_creds +should verify. +If +.Fa ccache +is given +.Fn krb5_verify_init_creds +stores all credentials it fetched from the KDC there, otherwise it +will use a memory credential cache that is destroyed when done. +.Pp +.Fn krb5_verify_init_creds_opt_init +cleans the the structure, must be used before trying to pass it in to +.Fn krb5_verify_init_creds . +.Pp +.Fn krb5_verify_init_creds_opt_set_ap_req_nofail +controls controls the behavior if +.Fa ap_req_server +doesn't exists in the local keytab or in the KDC's database, if it's +true, the error will be ignored. Note that this use is possible +insecure. +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_get_init_creds 3 , +.Xr krb5_verify_user 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_verify_user.3 b/static/netbsd/man3/krb5_verify_user.3 new file mode 100644 index 00000000..90646d67 --- /dev/null +++ b/static/netbsd/man3/krb5_verify_user.3 @@ -0,0 +1,243 @@ +.\" $NetBSD: krb5_verify_user.3,v 1.2 2017/01/28 21:31:49 christos Exp $ +.\" +.\" Copyright (c) 2001 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Id +.\" +.Dd May 1, 2006 +.Dt KRB5_VERIFY_USER 3 +.Os +.Sh NAME +.Nm krb5_verify_user , +.Nm krb5_verify_user_lrealm , +.Nm krb5_verify_user_opt , +.Nm krb5_verify_opt_init , +.Nm krb5_verify_opt_alloc , +.Nm krb5_verify_opt_free , +.Nm krb5_verify_opt_set_ccache , +.Nm krb5_verify_opt_set_flags , +.Nm krb5_verify_opt_set_service , +.Nm krb5_verify_opt_set_secure , +.Nm krb5_verify_opt_set_keytab +.Nd Heimdal password verifying functions +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5/krb5.h +.Ft krb5_error_code +.Fn "krb5_verify_user" "krb5_context context" " krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service" +.Ft krb5_error_code +.Fn "krb5_verify_user_lrealm" "krb5_context context" "krb5_principal principal" "krb5_ccache ccache" "const char *password" "krb5_boolean secure" "const char *service" +.Ft void +.Fn krb5_verify_opt_init "krb5_verify_opt *opt" +.Ft void +.Fn krb5_verify_opt_alloc "krb5_verify_opt **opt" +.Ft void +.Fn krb5_verify_opt_free "krb5_verify_opt *opt" +.Ft void +.Fn krb5_verify_opt_set_ccache "krb5_verify_opt *opt" "krb5_ccache ccache" +.Ft void +.Fn krb5_verify_opt_set_keytab "krb5_verify_opt *opt" "krb5_keytab keytab" +.Ft void +.Fn krb5_verify_opt_set_secure "krb5_verify_opt *opt" "krb5_boolean secure" +.Ft void +.Fn krb5_verify_opt_set_service "krb5_verify_opt *opt" "const char *service" +.Ft void +.Fn krb5_verify_opt_set_flags "krb5_verify_opt *opt" "unsigned int flags" +.Ft krb5_error_code +.Fo krb5_verify_user_opt +.Fa "krb5_context context" +.Fa "krb5_principal principal" +.Fa "const char *password" +.Fa "krb5_verify_opt *opt" +.Fc +.Sh DESCRIPTION +The +.Nm krb5_verify_user +function verifies the password supplied by a user. +The principal whose password will be verified is specified in +.Fa principal . +New tickets will be obtained as a side-effect and stored in +.Fa ccache +(if +.Dv NULL , +the default ccache is used). +.Fn krb5_verify_user +will call +.Fn krb5_cc_initialize +on the given +.Fa ccache , +so +.Fa ccache +must only initialized with +.Fn krb5_cc_resolve +or +.Fn krb5_cc_gen_new . +If the password is not supplied in +.Fa password +(and is given as +.Dv NULL ) +the user will be prompted for it. +If +.Fa secure +the ticket will be verified against the locally stored service key +.Fa service +(by default +.Ql host +if given as +.Dv NULL +). +.Pp +The +.Fn krb5_verify_user_lrealm +function does the same, except that it ignores the realm in +.Fa principal +and tries all the local realms (see +.Xr krb5.conf 5 ) . +After a successful return, the principal is set to the authenticated +realm. If the call fails, the principal will not be meaningful, and +should only be freed with +.Xr krb5_free_principal 3 . +.Pp +.Fn krb5_verify_opt_alloc +and +.Fn krb5_verify_opt_free +allocates and frees a +.Li krb5_verify_opt . +You should use the the alloc and free function instead of allocation +the structure yourself, this is because in a future release the +structure wont be exported. +.Pp +.Fn krb5_verify_opt_init +resets all opt to default values. +.Pp +None of the krb5_verify_opt_set function makes a copy of the data +structure that they are called with. It's up the caller to free them +after the +.Fn krb5_verify_user_opt +is called. +.Pp +.Fn krb5_verify_opt_set_ccache +sets the +.Fa ccache +that user of +.Fa opt +will use. If not set, the default credential cache will be used. +.Pp +.Fn krb5_verify_opt_set_keytab +sets the +.Fa keytab +that user of +.Fa opt +will use. If not set, the default keytab will be used. +.Pp +.Fn krb5_verify_opt_set_secure +if +.Fa secure +if true, the password verification will require that the ticket will +be verified against the locally stored service key. If not set, +default value is true. +.Pp +.Fn krb5_verify_opt_set_service +sets the +.Fa service +principal that user of +.Fa opt +will use. If not set, the +.Ql host +service will be used. +.Pp +.Fn krb5_verify_opt_set_flags +sets +.Fa flags +that user of +.Fa opt +will use. +If the flag +.Dv KRB5_VERIFY_LREALMS +is used, the +.Fa principal +will be modified like +.Fn krb5_verify_user_lrealm +modifies it. +.Pp +.Fn krb5_verify_user_opt +function verifies the +.Fa password +supplied by a user. +The principal whose password will be verified is specified in +.Fa principal . +Options the to the verification process is pass in in +.Fa opt . +.Sh EXAMPLES +Here is a example program that verifies a password. it uses the +.Ql host/`hostname` +service principal in +.Pa krb5.keytab . +.Bd -literal +#include + +int +main(int argc, char **argv) +{ + char *user; + krb5_error_code error; + krb5_principal princ; + krb5_context context; + + if (argc != 2) + errx(1, "usage: verify_passwd "); + + user = argv[1]; + + if (krb5_init_context(&context) < 0) + errx(1, "krb5_init_context"); + + if ((error = krb5_parse_name(context, user, &princ)) != 0) + krb5_err(context, 1, error, "krb5_parse_name"); + + error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL); + if (error) + krb5_err(context, 1, error, "krb5_verify_user"); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr krb5_cc_gen_new 3 , +.Xr krb5_cc_initialize 3 , +.Xr krb5_cc_resolve 3 , +.Xr krb5_err 3 , +.Xr krb5_free_principal 3 , +.Xr krb5_init_context 3 , +.Xr krb5_kt_default 3 , +.Xr krb5.conf 5 diff --git a/static/netbsd/man3/krb5_verr.3 b/static/netbsd/man3/krb5_verr.3 new file mode 100644 index 00000000..e37601cb --- /dev/null +++ b/static/netbsd/man3/krb5_verr.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_verr.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_verrx.3 b/static/netbsd/man3/krb5_verrx.3 new file mode 100644 index 00000000..4183a295 --- /dev/null +++ b/static/netbsd/man3/krb5_verrx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_verrx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_vprepend_error_message.3 b/static/netbsd/man3/krb5_vprepend_error_message.3 new file mode 100644 index 00000000..17050bca --- /dev/null +++ b/static/netbsd/man3/krb5_vprepend_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vprepend_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_vset_error_message.3 b/static/netbsd/man3/krb5_vset_error_message.3 new file mode 100644 index 00000000..cd6cd002 --- /dev/null +++ b/static/netbsd/man3/krb5_vset_error_message.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vset_error_message.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_vset_error_string.3 b/static/netbsd/man3/krb5_vset_error_string.3 new file mode 100644 index 00000000..b0ca0d20 --- /dev/null +++ b/static/netbsd/man3/krb5_vset_error_string.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vset_error_string.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_deprecated.3 diff --git a/static/netbsd/man3/krb5_vwarn.3 b/static/netbsd/man3/krb5_vwarn.3 new file mode 100644 index 00000000..74851f39 --- /dev/null +++ b/static/netbsd/man3/krb5_vwarn.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vwarn.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_vwarnx.3 b/static/netbsd/man3/krb5_vwarnx.3 new file mode 100644 index 00000000..230bf1fb --- /dev/null +++ b/static/netbsd/man3/krb5_vwarnx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_vwarnx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_warn.3 b/static/netbsd/man3/krb5_warn.3 new file mode 100644 index 00000000..25716824 --- /dev/null +++ b/static/netbsd/man3/krb5_warn.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_warn.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5_warnx.3 b/static/netbsd/man3/krb5_warnx.3 new file mode 100644 index 00000000..926cc8d6 --- /dev/null +++ b/static/netbsd/man3/krb5_warnx.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: krb5_warnx.3,v 1.2 2019/12/15 22:50:45 christos Exp $ +.\" +.so man3/krb5_error.3 diff --git a/static/netbsd/man3/krb5plugin_an2ln_ftable_desc.3 b/static/netbsd/man3/krb5plugin_an2ln_ftable_desc.3 new file mode 100644 index 00000000..62c88742 --- /dev/null +++ b/static/netbsd/man3/krb5plugin_an2ln_ftable_desc.3 @@ -0,0 +1,54 @@ +.\" $NetBSD: krb5plugin_an2ln_ftable_desc.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5plugin_an2ln_ftable_desc" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5plugin_an2ln_ftable_desc \- Description of the krb5_aname_to_lname(3) plugin facility\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Description of the krb5_aname_to_lname(3) plugin facility\&. + +The krb5_aname_to_lname(3) function is pluggable\&. The plugin is named KRB5_PLUGIN_AN2LN ('an2ln'), with a single minor version, KRB5_PLUGIN_AN2LN_VERSION_0 (0)\&. +.PP +The plugin for krb5_aname_to_lname(3) consists of a data symbol referencing a structure of type krb5plugin_an2ln_ftable, with four fields: +.PP +\fBParameters\fP +.RS 4 +\fIinit\fP Plugin initialization function (see krb5-plugin(7)) +.br +\fIminor_version\fP The plugin minor version number (0) +.br +\fIfini\fP Plugin finalization function +.br +\fIan2ln\fP Plugin aname_to_lname function +.RE +.PP +The an2ln field is the plugin entry point that performs the traditional aname_to_lname operation however the plugin desires\&. It is invoked in no particular order relative to other an2ln plugins, but it has a 'rule' argument that indicates which plugin is intended to act on the rule\&. The plugin an2ln function must return KRB5_PLUGIN_NO_HANDLE if the rule is not applicable to it\&. +.PP +The plugin an2ln function has the following arguments, in this order: +.PP +.IP "1." 4 +plug_ctx, the context value output by the plugin's init function +.IP "2." 4 +context, a krb5_context +.IP "3." 4 +rule, the aname_to_lname rule being evaluated (from krb5\&.conf(5)) +.IP "4." 4 +aname, the krb5_principal to be mapped to an lname +.IP "5." 4 +set_res_f, a function the plugin must call to set its result +.IP "6." 4 +set_res_ctx, the first argument to set_res_f (the second is the result lname string) +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5plugin_db_ftable_desc.3 b/static/netbsd/man3/krb5plugin_db_ftable_desc.3 new file mode 100644 index 00000000..b8b3b894 --- /dev/null +++ b/static/netbsd/man3/krb5plugin_db_ftable_desc.3 @@ -0,0 +1,35 @@ +.\" $NetBSD: krb5plugin_db_ftable_desc.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5plugin_db_ftable_desc" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5plugin_db_ftable_desc \- Description of the krb5 DB plugin facility\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Description of the krb5 DB plugin facility\&. + +The krb5_aname_to_lname(3) function's DB rule is pluggable\&. The plugin is named KRB5_PLUGIN_DB ('krb5_db_plug'), with a single minor version, KRB5_PLUGIN_DB_VERSION_0 (0)\&. +.PP +The plugin consists of a data symbol referencing a structure of type \fBkrb5plugin_db_ftable_desc\fP, with three fields: +.PP +\fBParameters\fP +.RS 4 +\fIinit\fP Plugin initialization function (see krb5-plugin(7)) +.br +\fIminor_version\fP The plugin minor version number (0) +.br +\fIfini\fP Plugin finalization function +.RE +.PP +The init entry point is expected to call heim_db_register()\&. The fini entry point is expected to do nothing\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/krb5plugin_kuserok_ftable_desc.3 b/static/netbsd/man3/krb5plugin_kuserok_ftable_desc.3 new file mode 100644 index 00000000..762ed95e --- /dev/null +++ b/static/netbsd/man3/krb5plugin_kuserok_ftable_desc.3 @@ -0,0 +1,58 @@ +.\" $NetBSD: krb5plugin_kuserok_ftable_desc.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "krb5plugin_kuserok_ftable_desc" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal Kerberos 5 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +krb5plugin_kuserok_ftable_desc \- Description of the krb5_kuserok(3) plugin facility\&. + +.SH SYNOPSIS +.br +.PP +.PP +\fC#include \fP +.SH "Detailed Description" +.PP +Description of the krb5_kuserok(3) plugin facility\&. + +The krb5_kuserok(3) function is pluggable\&. The plugin is named KRB5_PLUGIN_KUSEROK ('krb5_plugin_kuserok'), with a single minor version, KRB5_PLUGIN_KUSEROK_VERSION_0 (0)\&. +.PP +The plugin for krb5_kuserok(3) consists of a data symbol referencing a structure of type krb5plugin_kuserok_ftable, with four fields: +.PP +\fBParameters\fP +.RS 4 +\fIinit\fP Plugin initialization function (see krb5-plugin(7)) +.br +\fIminor_version\fP The plugin minor version number (0) +.br +\fIfini\fP Plugin finalization function +.br +\fIkuserok\fP Plugin kuserok function +.RE +.PP +The kuserok field is the plugin entry point that performs the traditional kuserok operation however the plugin desires\&. It is invoked in no particular order relative to other kuserok plugins, but it has a 'rule' argument that indicates which plugin is intended to act on the rule\&. The plugin kuserok function must return KRB5_PLUGIN_NO_HANDLE if the rule is not applicable to it\&. +.PP +The plugin kuserok function has the following arguments, in this order: +.PP +.IP "1." 4 +plug_ctx, the context value output by the plugin's init function +.IP "2." 4 +context, a krb5_context +.IP "3." 4 +rule, the kuserok rule being evaluated (from krb5\&.conf(5)) +.IP "4." 4 +flags +.IP "5." 4 +k5login_dir, configured location of k5login per-user files if any +.IP "6." 4 +luser, name of the local user account to which principal is attempting to access\&. +.IP "7." 4 +principal, the krb5_principal trying to access the luser account +.IP "8." 4 +result, a krb5_boolean pointer where the plugin will output its result +.PP + + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code\&. diff --git a/static/netbsd/man3/kvm.3 b/static/netbsd/man3/kvm.3 new file mode 100644 index 00000000..acf2f4a4 --- /dev/null +++ b/static/netbsd/man3/kvm.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: kvm.3,v 1.13 2011/09/13 08:53:15 wiz Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 14, 2011 +.Dt KVM 3 +.Os +.Sh NAME +.Nm kvm +.Nd kernel memory interface +.Sh LIBRARY +.Lb libkvm +.Sh DESCRIPTION +The +.Nm +library provides a uniform interface for accessing kernel virtual memory +images, including live systems and crash dumps. +Access to live systems is via +.Pa /dev/mem +while crash dumps can be examined via the core file generated by +.Xr savecore 8 . +The interface behaves identically in both cases. +Memory can be read and written, kernel symbol addresses can be +looked up efficiently, and information about user processes can +be gathered. +.Pp +.Fn kvm_open +is first called to obtain a descriptor for all subsequent calls. +.Sh FILES +.Bl -tag -width /dev/mem -compact +.It Pa /dev/mem +interface to physical memory +.El +.Sh COMPATIBILITY +The kvm interface was first introduced in SunOS. +A considerable number of programs have been developed that use this +interface, making backward compatibility highly desirable. +In most respects, the Sun kvm interface is consistent and clean. +Accordingly, the generic portion of the interface (i.e., +.Fn kvm_open , +.Fn kvm_close , +.Fn kvm_read , +.Fn kvm_write , +and +.Fn kvm_nlist ) +has been incorporated into the +.Bx +interface. +Indeed, many kvm applications (i.e., debuggers and statistical monitors) +use only this subset of the interface. +.Pp +The process interface was not kept. +This is not a portability issue since any code that manipulates +processes is inherently machine dependent. +.Pp +Finally, the Sun kvm error reporting semantics are poorly defined. +The library can be configured either to print errors to stderr automatically, +or to print no error messages at all. +In the latter case, the nature of the error cannot be determined. +To overcome this, the +.Bx +interface includes a routine, +.Xr kvm_geterr 3 , +to return (not print out) the error message corresponding to the most +recent error condition on the given descriptor. +.Sh SEE ALSO +.Xr kvm_close 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getkernelname 3 , +.Xr kvm_getloadavg 3 , +.Xr kvm_getlwps 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 diff --git a/static/netbsd/man3/kvm_dump.3 b/static/netbsd/man3/kvm_dump.3 new file mode 100644 index 00000000..7309fa97 --- /dev/null +++ b/static/netbsd/man3/kvm_dump.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: kvm_dump.3,v 1.15 2009/10/20 19:10:09 snj Exp $ +.\" +.\" Copyright (c) 1996 Leo Weppelman +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd March 17, 1996 +.Dt KVM_DUMP 3 +.Os +.Sh NAME +.Nm kvm_dump_mkheader , +.Nm kvm_dump_wrtheader , +.Nm kvm_dump_inval +.Nd crash dump support functions +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.Ft int +.Fn kvm_dump_mkheader "kvm_t *kd" "off_t dump_off" +.Ft int +.Fn kvm_dump_wrtheader "kvm_t *kd" "FILE *fp" "int dumpsize" +.Ft int +.Fn kvm_dump_inval "kvm_t *kd" +.Sh DESCRIPTION +First note that the functions described here were designed to be used by +.Xr savecore 8 . +.Pp +The function +.Fn kvm_dump_mkheader +checks if the physical memory file associated with +.Fa kd +contains a valid crash dump header as generated by a dumping kernel. +When a valid header is found, +.Fn kvm_dump_mkheader +initializes the internal kvm data structures as if a crash dump generated by +the +.Xr savecore 8 +program was opened. +This has the intentional side effect of enabling the +address translation machinery. +.Pp +A call to +.Fn kvm_dump_mkheader +will most likely be followed by a call to +.Fn kvm_dump_wrtheader . +This function takes care of generating the generic header, the CORE_CPU +section and the section header of the CORE_DATA section. +The data is written to the file pointed at by +.Fa fp . +The +.Fa dumpsize +argument is only used to properly the set the segment size of the CORE_DATA +section. +Note that this function assumes that +.Fa fp +is positioned at file location 0. +This function will not seek and therefore allows +.Fa fp +to be a file pointer obtained by +.Fn zopen . +.Pp +The +.Fn kvm_dump_inval +function clears the magic number in the physical memory file associated with +.Fa kd . +The address translations must be enabled for this to work (thus assuming +that +.Fn kvm_dump_mkheader +was called earlier in the sequence). +.Sh RETURN VALUES +All functions except +.Fn kvm_dump_mkheader +return 0 on success, -1 on failure. +The function +.Fn kvm_dump_mkheader +returns the size of the headers present before the actual dumpdata starts. +If no valid headers were found but no fatal errors occurred, 0 is returned. +On fatal errors the return value is -1. +.Pp +In the case of failure, +.Xr kvm_geterr 3 +can be used to retrieve the cause of the error. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_open 3 +.Sh HISTORY +These functions first appeared in +.Nx 1.2 . diff --git a/static/netbsd/man3/kvm_geterr.3 b/static/netbsd/man3/kvm_geterr.3 new file mode 100644 index 00000000..6f646c07 --- /dev/null +++ b/static/netbsd/man3/kvm_geterr.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: kvm_geterr.3,v 1.9 2009/03/10 23:49:07 joerg Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_geterr.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt KVM_GETERR 3 +.Os +.Sh NAME +.Nm kvm_geterr +.Nd get error message on kvm descriptor +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.Ft char * +.Fn kvm_geterr "kvm_t *kd" +.Sh DESCRIPTION +This function returns a string describing the most recent error condition +on the descriptor +.Fa kd . +The results are undefined if the most recent +.Xr kvm 3 +library call did not produce an error. +The string returned is stored in memory owned by +.Xr kvm 3 +so the message should be copied out and saved elsewhere if necessary. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 +.Sh BUGS +This routine cannot be used to access error conditions due to a failed +.Fn kvm_openfiles +call, since failure is indicated by returning a +.Dv NULL +descriptor. +Therefore, errors on open are output to the special error buffer +passed to +.Fn kvm_openfiles . +This option is not available to +.Fn kvm_open . diff --git a/static/netbsd/man3/kvm_getfiles.3 b/static/netbsd/man3/kvm_getfiles.3 new file mode 100644 index 00000000..c6a33629 --- /dev/null +++ b/static/netbsd/man3/kvm_getfiles.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: kvm_getfiles.3,v 1.11 2009/03/10 23:49:07 joerg Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_getfiles.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd April 19, 1994 +.Dt KVM_GETFILES 3 +.Os +.Sh NAME +.Nm kvm_getfiles +.Nd survey open files +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.In sys/kinfo.h +.Fd #define _KERNEL +.In sys/file.h +.Fd #undef _KERNEL +.\" .Fa kvm_t *kd +.Ft char * +.Fn kvm_getfiles "kvm_t *kd" "int op" "int arg" "int *cnt" +.Sh DESCRIPTION +.Fn kvm_getfiles +returns a (sub-)set of the open files in the kernel indicated by +.Fa kd . +The +.Fa op +and +.Fa arg +arguments constitute a predicate which limits the set of files +returned. +No predicates are currently defined. +.Pp +The number of processes found is returned in the reference parameter +.Fa cnt . +The files are returned as a contiguous array of file structures, +preceded by the address of the first file entry in the kernel. +This memory is owned by kvm and is not guaranteed to be persistent across +subsequent kvm library calls. +Data should be copied out if it needs to be saved. +.Sh RETURN VALUES +.Fn kvm_getfiles +will return +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_geterr 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 +.Sh BUGS +This routine does not belong in the kvm interface. diff --git a/static/netbsd/man3/kvm_getkernelname.3 b/static/netbsd/man3/kvm_getkernelname.3 new file mode 100644 index 00000000..f83d7ecb --- /dev/null +++ b/static/netbsd/man3/kvm_getkernelname.3 @@ -0,0 +1,67 @@ +.\" $NetBSD: kvm_getkernelname.3,v 1.2 2011/09/13 08:53:10 wiz Exp $ +.\" +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 14, 2011 +.Dt KVM_GETKERNELNAME 3 +.Os +.Sh NAME +.Nm kvm_getkernelname +.Nd get kernel name of opened kvm descriptor +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.Ft const char * +.Fn kvm_getkernelname "kvm_t *kd" +.Sh DESCRIPTION +This function returns a string containing the kernel name used from the kvm +descriptor obtained by a previous +.Xr kvm_open 3 +or +.Xr kvm_openfiles 3 +call. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 diff --git a/static/netbsd/man3/kvm_getloadavg.3 b/static/netbsd/man3/kvm_getloadavg.3 new file mode 100644 index 00000000..0406e590 --- /dev/null +++ b/static/netbsd/man3/kvm_getloadavg.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: kvm_getloadavg.3,v 1.13 2018/12/11 23:02:19 sevan Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd December 11, 2018 +.Dt KVM_GETLOADAVG 3 +.Os +.Sh NAME +.Nm kvm_getloadavg +.Nd get system load averages, from live or dead kernels +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In sys/resource.h +.In kvm.h +.Ft int +.Fn kvm_getloadavg "kvm_t *kd" "double loadavg[]" "int nelem" +.Sh DESCRIPTION +The +.Fn kvm_getloadavg +function returns the number of processes in the system run queue +of the kernel or core file, indicated by +.Fa kd . +Up to +.Fa nelem +samples are retrieved and assigned to successive elements of +.Fa loadavg Ns Bq . +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +On a live system, the load average is obtained by calling +.Xr getloadavg 3 . +If performing post mortem on a kernel core file, +.Nm +is able to extract the system load averages at the time of death from the core +file directly. +.Sh RETURN VALUES +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.Sh SEE ALSO +.Xr uptime 1 , +.Xr getloadavg 3 , +.Xr kvm 3 , +.Xr kvm_open 3 , +.Xr sysctl 3 diff --git a/static/netbsd/man3/kvm_getlwps.3 b/static/netbsd/man3/kvm_getlwps.3 new file mode 100644 index 00000000..447e8b79 --- /dev/null +++ b/static/netbsd/man3/kvm_getlwps.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: kvm_getlwps.3,v 1.8 2018/01/09 21:13:59 kamil Exp $ +.\" +.\"Copyright (c) 2002 The NetBSD Foundation, Inc. +.\"All rights reserved. +.\" +.\"This code is derived from software contributed to The NetBSD Foundation +.\"by Nathan J. Williams. +.\" +.\"Redistribution and use in source and binary forms, with or without +.\"modification, are permitted provided that the following conditions +.\"are met: +.\"1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\"2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\"THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\"``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\"TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\"PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\"BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\"CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\"SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\"INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\"CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\"ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\"POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 9, 2018 +.Dt KVM_GETLWPS 3 +.Os +.Sh NAME +.Nm kvm_getlwps +.Nd access state of LWPs belonging to a user process +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.In sys/param.h +.In sys/sysctl.h +.\" .Fa kvm_t *kd +.Ft struct kinfo_lwp * +.Fn kvm_getlwps "kvm_t *kd" "int pid" "unsigned long procaddr" "size_t elemsize" "int *cnt" +.Sh DESCRIPTION +.Fn kvm_getlwps +returns the set of LWPs belonging to the process specified by +.Fa pid +or +.Fa procaddr +in the kernel indicated by +.Fa kd . +The number of LWPs found is returned in the reference parameter +.Fa cnt . +The LWPs are returned as a contiguous array of +.Sy kinfo_lwp +structures. +This memory is locally allocated, and subsequent calls to +.Fn kvm_getlwps +and +.Fn kvm_close +will overwrite this storage. +.Pp +Only the first +.Fa elemsize +bytes of each array entry are returned. +If the size of the +.Sy kinfo_lwp +structure increases in size in a future release of +.Nx +the kernel will only return the requested amount of data for +each array entry and programs that use +.Fn kvm_getlwps +will continue to function without the need for recompilation. +.Pp +If called against an active kernel, the +.Fn kvm_getlwps +function will use the +.Xr sysctl 3 +interface and return information about the process identified by +.Fa pid ; +otherwise the kernel memory device file or swap device will be +accessed and the process is identified by the location passed in +.Fa paddr . +.Sh RETURN VALUES +.Fn kvm_getlwps +returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getproc2 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 +.Sh BUGS +These routines do not belong in the kvm interface. diff --git a/static/netbsd/man3/kvm_getprocs.3 b/static/netbsd/man3/kvm_getprocs.3 new file mode 100644 index 00000000..c202995d --- /dev/null +++ b/static/netbsd/man3/kvm_getprocs.3 @@ -0,0 +1,239 @@ +.\" $NetBSD: kvm_getprocs.3,v 1.17 2018/01/09 21:17:45 kamil Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_getprocs.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd January 9, 2018 +.Dt KVM_GETPROCS 3 +.Os +.Sh NAME +.Nm kvm_getprocs , +.Nm kvm_getargv , +.Nm kvm_getenvv , +.Nm kvm_getproc2 , +.Nm kvm_getargv2 , +.Nm kvm_getenvv2 +.Nd access user process state +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.In sys/param.h +.In sys/sysctl.h +.\" .Fa kvm_t *kd +.Ft struct kinfo_proc * +.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt" +.Ft char ** +.Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr" +.Ft char ** +.Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr" +.Ft struct kinfo_proc2 * +.Fn kvm_getproc2 "kvm_t *kd" "int op" "int arg" "size_t elemsize" "int *cnt" +.Ft char ** +.Fn kvm_getargv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr" +.Ft char ** +.Fn kvm_getenvv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr" +.Sh DESCRIPTION +.Fn kvm_getprocs +returns a (sub-)set of active processes in the kernel indicated by +.Fa kd . +The +.Fa op +and +.Fa arg +arguments constitute a predicate +which limits the set of processes returned. +The value of +.Fa op +describes the filtering predicate as follows: +.Pp +.Bl -tag -width 20n -offset indent -compact +.It Sy KERN_PROC_ALL +all processes +.It Sy KERN_PROC_PID +processes with process id +.Fa arg +.It Sy KERN_PROC_PGRP +processes with process group +.Fa arg +.It Sy KERN_PROC_SESSION +processes with session id +.Fa arg +.It Sy KERN_PROC_TTY +processes with tty device +.Fa arg +.It Sy KERN_PROC_UID +processes with effective user id +.Fa arg +.It Sy KERN_PROC_RUID +processes with real user id +.Fa arg +.It Sy KERN_PROC_GID +processes with effective group id +.Fa arg +.It Sy KERN_PROC_RGID +processes with real group id +.Fa arg +.El +.Pp +The number of processes found is returned in the reference parameter +.Fa cnt . +The processes are returned as a contiguous array of +.Sy kinfo_proc +structures. +This memory is locally allocated, and subsequent calls to +.Fn kvm_getprocs +and +.Fn kvm_close +will overwrite this storage. +.Pp +If the +.Fa op +argument for +.Fn kvm_getprocs +is +.Sy KERN_PROC_TTY , +.Fa arg +can also be +.Sy KERN_PROC_TTY_NODEV +to select processes with no controlling tty and +.Sy KERN_PROC_TTY_REVOKE +to select processes which have had their controlling tty +revoked. +.Pp +.Fn kvm_getargv +returns a null-terminated argument vector that corresponds to the +command line arguments passed to process indicated by +.Fa p . +Most likely, these arguments correspond to the values passed to +.Xr exec 3 +on process creation. +This information is, however, +deliberately under control of the process itself. +Note that the original command name can be found, unaltered, +in the p_comm field of the process structure returned by +.Fn kvm_getprocs . +.Pp +The +.Fa nchr +argument indicates the maximum number of characters, including null bytes, +to use in building the strings. +If this amount is exceeded, the string +causing the overflow is truncated and the partial result is returned. +This is handy for programs like +.Xr ps 1 +and +.Xr w 1 +that print only a one line summary of a command and should not copy +out large amounts of text only to ignore it. +If +.Fa nchr +is zero, no limit is imposed and all argument strings are returned in +their entirety. +.Pp +The memory allocated to the argv pointers and string storage +is owned by the kvm library. +Subsequent +.Fn kvm_getprocs +and +.Xr kvm_close 3 +calls will clobber this storage. +.Pp +The +.Fn kvm_getenvv +function is similar to +.Fn kvm_getargv +but returns the vector of environment strings. +This data is also alterable by the process. +.Pp +.Fn kvm_getproc2 +is similar to +.Fn kvm_getprocs +but returns an array of +.Sy kinfo_proc2 +structures. +Additionally, only the first +.Fa elemsize +bytes of each array entry are returned. +If the size of the +.Sy kinfo_proc2 +structure increases in size in a future release of +.Nx +the kernel will only return the requested amount of data for +each array entry and programs that use +.Fn kvm_getproc2 +will continue to function without the need for recompilation. +.Pp +The +.Fn kvm_getargv2 +and +.Fn kvm_getenvv2 +are equivalents to the +.Fn kvm_getargv +and +.Fn kvm_getenvv +functions but use a +.Sy kinfo_proc2 +structure to specify the process. +.Pp +If called against an active kernel, the +.Fn kvm_getproc2 , +.Fn kvm_getargv2 , +and +.Fn kvm_getenvv2 +functions will use the +.Xr sysctl 3 +interface and do not require access to the kernel memory device +file or swap device. +.Sh RETURN VALUES +.Fn kvm_getprocs , +.Fn kvm_getargv , +.Fn kvm_getenvv , +.Fn kvm_getproc2 , +.Fn kvm_getargv2 , +and +.Fn kvm_getenvv2 +all return +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_geterr 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 +.Sh BUGS +These routines do not belong in the kvm interface. diff --git a/static/netbsd/man3/kvm_nlist.3 b/static/netbsd/man3/kvm_nlist.3 new file mode 100644 index 00000000..4ff4ae0f --- /dev/null +++ b/static/netbsd/man3/kvm_nlist.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: kvm_nlist.3,v 1.11 2003/08/07 16:44:37 agc Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_nlist.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 11, 2003 +.Dt KVM_NLIST 3 +.Os +.Sh NAME +.Nm kvm_nlist +.Nd retrieve symbol table names from a kernel image +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.In nlist.h +.Ft int +.Fn kvm_nlist "kvm_t *kd" "struct nlist *nl" +.Sh DESCRIPTION +.Fn kvm_nlist +retrieves the symbol table entries indicated by the name list argument +.Fa \&nl . +This argument points to an array of nlist structures, terminated by +an entry whose n_name field is +.Dv NULL +(see +.Xr nlist 3 ) . +Each symbol is looked up using the n_name field, and if found, the +corresponding n_type and n_value fields are filled in. +These fields are set to 0 if the symbol is not found. +.Pp +If +.Fa \&kd +was created by a call to +.Fn kvm_open +with a +.Dv NULL +executable image name, +.Fn kvm_nlist +will use +.Pa /dev/ksyms +to retrieve the kernel symbol table. +.Sh RETURN VALUES +The +.Fn kvm_nlist +function returns the number of invalid entries found. +If the kernel symbol table was unreadable, -1 is returned. +.Sh FILES +.Bl -tag -width /dev/ksyms -compact +.It Pa /dev/ksyms +.El +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 , +.Xr ksyms 4 diff --git a/static/netbsd/man3/kvm_open.3 b/static/netbsd/man3/kvm_open.3 new file mode 100644 index 00000000..55f4a673 --- /dev/null +++ b/static/netbsd/man3/kvm_open.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: kvm_open.3,v 1.18 2011/09/12 21:11:32 christos Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd September 14, 2011 +.Dt KVM_OPEN 3 +.Os +.Sh NAME +.Nm kvm_open , +.Nm kvm_openfiles , +.Nm kvm_close +.Nd initialize kernel virtual memory access +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In fcntl.h +.In kvm.h +.Ft kvm_t * +.Fn kvm_open "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "const char *errstr" +.Ft kvm_t * +.Fn kvm_openfiles "const char *execfile" "const char *corefile" "char *swapfile" "int flags" "char *errbuf" +.Ft int +.Fn kvm_close "kvm_t *kd" +.Sh DESCRIPTION +The functions +.Fn kvm_open +and +.Fn kvm_openfiles +return a descriptor used to access kernel virtual memory +via the +.Xr kvm 3 +library routines. +Both active kernels and crash dumps are accessible +through this interface. +.Pp +.Fa execfile +is the executable image of the kernel being examined. +This file must contain a symbol table. +If this argument is +.Dv NULL , +the currently running system is assumed; in this case, the functions will +attempt to use the +.Xr ksyms 4 +device indicated by +.Dv _PATH_KSYMS +in +.In paths.h ; +if that fails, then they will use the file indicated by the +.Xr sysctl 3 +variable +.Va machdep.booted_kernel , +or (if the sysctl information is not available) +the default kernel path indicated by +.Dv _PATH_UNIX +in +.In paths.h . +.Pp +.Fa corefile +is the kernel memory device file. +It can be either +.Pa /dev/mem +or a crash dump core generated by +.Xr savecore 8 . +If +.Fa corefile +is +.Dv NULL , +the default indicated by +.Dv _PATH_MEM +from +.In paths.h +is used. +.Pp +.Fa swapfile +should indicate the swap device. +If +.Dv NULL , +.Dv _PATH_DRUM +from +.In paths.h +is used. +.Pp +The +.Fa flags +argument indicates read/write access as in +.Xr open 2 +and applies only to the core file. +The only permitted flags from +.Xr open 2 +are +.Dv O_RDONLY , +.Dv O_WRONLY , +and +.Dv O_RDWR . +.Pp +As a special case, a +.Fa flags +argument of +.Dv KVM_NO_FILES +will initialize the +.Xr kvm 3 +library for use on active kernels only using +.Xr sysctl 3 +for retrieving kernel data and ignores the +.Fa execfile , +.Fa corefile +and +.Fa swapfile +arguments. +Only a small subset of the +.Xr kvm 3 +library functions are available using this method. +These are currently +.Xr kvm_getproc2 3 , +.Xr kvm_getargv2 3 +and +.Xr kvm_getenvv2 3 . +.Pp +There are two open routines which differ only with respect to +the error mechanism. +One provides backward compatibility with the SunOS kvm library, while the +other provides an improved error reporting framework. +.Pp +The +.Fn kvm_open +function is the Sun kvm compatible open call. +Here, the +.Fa errstr +argument indicates how errors should be handled. +If it is +.Dv NULL , +no errors are reported and the application cannot know the +specific nature of the failed kvm call. +If it is not +.Dv NULL , +errors are printed to stderr with +.Fa errstr +prepended to the message, as in +.Xr perror 3 . +Normally, the name of the program is used here. +The string is assumed to persist at least until the corresponding +.Fn kvm_close +call. +.Pp +The +.Fn kvm_openfiles +function provides +.Bx +style error reporting. +Here, error messages are not printed out by the library. +Instead, the application obtains the error message +corresponding to the most recent kvm library call using +.Fn kvm_geterr +(see +.Xr kvm_geterr 3 ) . +The results are undefined if the most recent kvm call did not produce +an error. +Since +.Fn kvm_geterr +requires a kvm descriptor, but the open routines return +.Dv NULL +on failure, +.Fn kvm_geterr +cannot be used to get the error message if open fails. +Thus, +.Fn kvm_openfiles +will place any error message in the +.Fa errbuf +argument. +This buffer should be _POSIX2_LINE_MAX characters large (from +.In limits.h ) . +.Sh RETURN VALUES +The +.Fn kvm_open +and +.Fn kvm_openfiles +functions both return a descriptor to be used +in all subsequent kvm library calls. +The library is fully re-entrant. +On failure, +.Dv NULL +is returned, in which case +.Fn kvm_openfiles +writes the error message into +.Fa errbuf . +.Pp +The +.Fn kvm_close +function returns 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr open 2 , +.Xr kvm 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getkernelname 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_read 3 , +.Xr kvm_write 3 +.Sh BUGS +There should not be two open calls. +The ill-defined error semantics of the Sun library +and the desire to have a backward-compatible library for +.Bx +left little choice. diff --git a/static/netbsd/man3/kvm_read.3 b/static/netbsd/man3/kvm_read.3 new file mode 100644 index 00000000..133477a4 --- /dev/null +++ b/static/netbsd/man3/kvm_read.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: kvm_read.3,v 1.9 2016/01/23 00:43:43 dholland Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kvm_read.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt KVM_READ 3 +.Os +.Sh NAME +.Nm kvm_read , +.Nm kvm_write +.Nd read or write kernel virtual memory +.Sh LIBRARY +.Lb libkvm +.Sh SYNOPSIS +.In kvm.h +.Ft ssize_t +.Fn kvm_read "kvm_t *kd" "unsigned long addr" "void *buf" "size_t nbytes" +.Ft ssize_t +.Fn kvm_write "kvm_t *kd" "unsigned long addr" "const void *buf" "size_t nbytes" +.Sh DESCRIPTION +The +.Fn kvm_read +and +.Fn kvm_write +functions are used to read and write kernel virtual memory (or a crash +dump file). +See +.Fn kvm_open 3 +or +.Fn kvm_openfiles 3 +for information regarding opening kernel virtual memory and crash dumps. +.Pp +The +.Fn kvm_read +function transfers +.Fa nbytes +bytes of data from +the kernel space address +.Fa addr +to +.Fa buf . +Conversely, +.Fn kvm_write +transfers data from +.Fa buf +to +.Fa addr . +Unlike their SunOS counterparts, these functions cannot be used to +read or write process address spaces. +.Sh RETURN VALUES +Upon success, the number of bytes actually transferred is returned. +Otherwise, -1 is returned. +.Sh SEE ALSO +.Xr kvm 3 , +.Xr kvm_close 3 , +.Xr kvm_getargv 3 , +.Xr kvm_getenvv 3 , +.Xr kvm_geterr 3 , +.Xr kvm_getprocs 3 , +.Xr kvm_nlist 3 , +.Xr kvm_open 3 , +.Xr kvm_openfiles 3 diff --git a/static/netbsd/man3/lber-decode.3 b/static/netbsd/man3/lber-decode.3 new file mode 100644 index 00000000..9115b42c --- /dev/null +++ b/static/netbsd/man3/lber-decode.3 @@ -0,0 +1,357 @@ +.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include +.LP +.BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" +.LP +.BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" +.LP +.BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" +.LP +.BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" +.LP +.BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" +.LP +.BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" +.LP +.BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" +.LP +.BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" +.LP +.BI "ber_tag_t ber_get_null(BerElement *" ber ");" +.LP +.BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" +.LP +.BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" +.LP +.BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" +.LP +.BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" +.SH DESCRIPTION +.LP +These routines provide a subroutine interface to a simplified +implementation of the Basic Encoding Rules of ASN.1. The version +of BER these routines support is the one defined for the LDAP +protocol. The encoding rules are the same as BER, except that +only definite form lengths are used, and bitstrings and octet strings +are always encoded in primitive form. This man page +describes the decoding routines in the lber library. See +.BR lber-encode (3) +for details on the corresponding encoding routines. +Consult +.BR lber-types (3) +for information about types, allocators, and deallocators. +.LP +Normally, the only routines that need to be called by an application +are +.BR ber_get_next () +to get the next BER element and +.BR ber_scanf () +to do the actual decoding. In some cases, +.BR ber_peek_tag () +may also need to be called in normal usage. The other routines are +provided for those applications that need more control than +.BR ber_scanf () +provides. In +general, these routines return the tag of the element decoded, or +LBER_ERROR if an error occurred. +.LP +The +.BR ber_get_next () +routine is used to read the next BER element from the given Sockbuf, +\fIsb\fP. It strips off and returns the leading tag, strips off and +returns the length of the entire element in \fIlen\fP, and sets up +\fIber\fP for subsequent calls to +.BR ber_scanf () +et al to decode the element. See +.BR lber-sockbuf (3) +for details of the Sockbuf implementation of the \fIsb\fP parameter. +.LP +The +.BR ber_scanf () +routine is used to decode a BER element in much the same way that +.BR scanf (3) +works. It reads from \fIber\fP, a pointer to a BerElement +such as returned by +.BR ber_get_next (), +interprets the bytes according to the format string \fIfmt\fP, and stores the +results in its additional arguments. The format string contains +conversion specifications which are used to direct the interpretation +of the BER element. The format string can contain the following +characters. +.RS +.LP +.TP 3 +.B a +Octet string. A char ** should be supplied. Memory is allocated, +filled with the contents of the octet string, null-terminated, and +returned in the parameter. The caller should free the returned +string using +.BR ber_memfree (). +.TP +.B A +Octet string. A variant of "\fBa\fP". A char ** should be supplied. +Memory is allocated, filled with the contents of the octet string, +null-terminated, and returned in the parameter, unless a zero-length +string would result; in that case, the arg is set to NULL. +The caller should free the returned string using +.BR ber_memfree (). +.TP +.B s +Octet string. A char * buffer should be supplied, followed by a pointer to a +ber_len_t initialized to the size of the buffer. Upon return, the +null-terminated octet string is put into the buffer, and the +ber_len_t is set to the actual size of the octet string. +.TP +.B O +Octet string. A struct ber_val ** should be supplied, which upon +return points to a dynamically allocated struct berval +containing the octet string and its length. +The caller should free the returned structure using +.BR ber_bvfree (). +.TP +.B o +Octet string. A struct ber_val * should be supplied, which upon +return contains the dynamically allocated +octet string and its length. The caller should free the returned octet +string using +.BR ber_memfree (). +.TP +.B m +Octet string. A struct ber_val * should be supplied, which upon return +contains the octet string and its length. The string resides in memory +assigned to the BerElement, and must not be freed by the caller. +.TP +.B b +Boolean. A pointer to a ber_int_t should be supplied. +.TP +.B e +Enumeration. A pointer to a ber_int_t should be supplied. +.TP +.B i +Integer. A pointer to a ber_int_t should be supplied. +.TP +.B B +Bitstring. A char ** should be supplied which will point to the +dynamically allocated +bits, followed by a ber_len_t *, which will point to the length +(in bits) of the bitstring returned. +.TP +.B n +Null. No parameter is required. The element is simply skipped if +it is recognized. +.TP +.B v +Sequence of octet strings. A char *** should be supplied, which upon +return points to a dynamically allocated null-terminated array of char *'s +containing the octet strings. NULL is returned if the sequence is empty. +The caller should free the returned array and octet strings using +.BR ber_memvfree (). +.TP +.B V +Sequence of octet strings with lengths. +A struct berval *** should be supplied, which upon +return points to a dynamically allocated null-terminated array of +struct berval *'s +containing the octet strings and their lengths. +NULL is returned if the sequence is empty. +The caller should free the returned structures using +.BR ber_bvecfree (). +.TP +.B W +Sequence of octet strings with lengths. +A BerVarray * should be supplied, which upon +return points to a dynamically allocated array of +struct berval's +containing the octet strings and their lengths. The array is terminated +by a struct berval with a NULL bv_val string pointer. +NULL is returned if the sequence is empty. +The caller should free the returned structures using +.BR ber_bvarray_free (). +.TP +.B M +Sequence of octet strings with lengths. This is a generalized form +of the previous three formats. +A void ** (ptr) should be supplied, followed by a ber_len_t * (len) +and a ber_len_t (off). +Upon return (ptr) will point to a dynamically allocated array +whose elements are all of size (*len). A struct berval will be filled +starting at offset (off) in each element. The strings in each struct +berval reside in memory assigned to the BerElement and must not be +freed by the caller. The array is terminated by a struct berval +with a NULL bv_val string pointer. NULL is returned if the sequence +is empty. The number of elements in the array is also stored +in (*len) on return. The caller should free the returned array using +.BR ber_memfree (). +.TP +.B l +Length of the next element. A pointer to a ber_len_t should be supplied. +.TP +.B t +Tag of the next element. A pointer to a ber_tag_t should be supplied. +.TP +.B T +Skip element and return its tag. A pointer to a ber_tag_t should be supplied. +.TP +.B x +Skip element. The next element is skipped. +.TP +.B { +Begin sequence. No parameter is required. The initial sequence tag +and length are skipped. +.TP +.B } +End sequence. No parameter is required and no action is taken. +.TP +.B [ +Begin set. No parameter is required. The initial set tag +and length are skipped. +.TP +.B ] +End set. No parameter is required and no action is taken. +.RE +.LP +The +.BR ber_get_int () +routine tries to interpret the next element as an integer, +returning the result in \fInum\fP. The tag of whatever it finds is returned +on success, LBER_ERROR (\-1) on failure. +.LP +The +.BR ber_get_stringb () +routine is used to read an octet string into a +preallocated buffer. The \fIlen\fP parameter should be initialized to +the size of the buffer, and will contain the length of the octet string +read upon return. The buffer should be big enough to take the octet +string value plus a terminating NULL byte. +.LP +The +.BR ber_get_stringa () +routine is used to dynamically allocate space into +which an octet string is read. +The caller should free the returned string using +.BR ber_memfree(). +.LP +The +.BR ber_get_stringal () +routine is used to dynamically allocate space +into which an octet string and its length are read. It takes a +struct berval **, and returns the result in this parameter. +The caller should free the returned structure using +.BR ber_bvfree(). +.LP +The +.BR ber_get_stringbv () +routine is used to read an octet string and its length into the +provided struct berval *. If the \fIalloc\fP parameter is zero, the string +will reside in memory assigned to the BerElement, and must not be freed +by the caller. If the \fIalloc\fP parameter is non-zero, the string will be +copied into dynamically allocated space which should be returned using +.BR ber_memfree (). +.LP +The +.BR ber_get_null () +routine is used to read a NULL element. It returns +the tag of the element it skips over. +.LP +The +.BR ber_get_boolean () +routine is used to read a boolean value. It is called the same way that +.BR ber_get_int () +is called. +.LP +The +.BR ber_get_enum () +routine is used to read a enumeration value. It is called the same way that +.BR ber_get_int () +is called. +.LP +The +.BR ber_get_bitstringa () +routine is used to read a bitstring value. It +takes a char ** which will hold the dynamically allocated bits, followed by an +ber_len_t *, which will point to the length (in bits) of the bitstring returned. +The caller should free the returned string using +.BR ber_memfree (). +.LP +The +.BR ber_first_element () +routine is used to return the tag and length +of the first element in a set or sequence. It also returns in \fIcookie\fP +a magic cookie parameter that should be passed to subsequent calls to +ber_next_element(), which returns similar information. +.SH EXAMPLES +Assume the variable \fIber\fP contains a lightweight BER encoding of +the following ASN.1 object: +.LP +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.LP +The element can be decoded using +.BR ber_scanf () +as follows. +.LP +.nf + ber_int_t scope, deref, size, time, attrsonly; + char *dn, **attrs; + ber_tag_t tag; + + tag = ber_scanf( ber, "{aeeiib{v}}", + &dn, &scope, &deref, + &size, &time, &attrsonly, &attrs ); + + if( tag == LBER_ERROR ) { + /* error */ + } else { + /* success */ + } + + ber_memfree( dn ); + ber_memvfree( attrs ); +.fi +.SH ERRORS +If an error occurs during decoding, generally these routines return +LBER_ERROR ((ber_tag_t)\-1). +.LP +.SH NOTES +.LP +The return values for all of these functions are declared in the +.B +header file. Some routines may dynamically allocate memory +which must be freed by the caller using supplied deallocation routines. +.SH SEE ALSO +.BR lber-encode (3), +.BR lber-memory (3), +.BR lber-sockbuf (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/lber-encode.3 b/static/netbsd/man3/lber-encode.3 new file mode 100644 index 00000000..2bc59352 --- /dev/null +++ b/static/netbsd/man3/lber-encode.3 @@ -0,0 +1,288 @@ +.TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include +.LP +.BI "BerElement *ber_alloc_t(int " options ");" +.LP +.BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" +.LP +.BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" +.LP +.BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" +.LP +.BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" +.LP +.BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" +.LP +.BI "int ber_put_seq(BerElement *" ber ");" +.LP +.BI "int ber_put_set(BerElement *" ber ");" +.SH DESCRIPTION +.LP +These routines provide a subroutine interface to a simplified +implementation of the Basic Encoding Rules of ASN.1. The version +of BER these routines support is the one defined for the LDAP +protocol. The encoding rules are the same as BER, except that +only definite form lengths are used, and bitstrings and octet strings +are always encoded in primitive form. This +man page describes the encoding routines in the lber library. See +.BR lber-decode (3) +for details on the corresponding decoding routines. Consult +.BR lber-types (3) +for information about types, allocators, and deallocators. +.LP +Normally, the only routines that need to be called by an application +are +.BR ber_alloc_t () +to allocate a BER element for encoding, +.BR ber_printf () +to do the actual encoding, and +.BR ber_flush2 () +to actually write the element. The other routines are provided for those +applications that need more control than +.BR ber_printf () +provides. In +general, these routines return the length of the element encoded, or +\-1 if an error occurred. +.LP +The +.BR ber_alloc_t () +routine is used to allocate a new BER element. It +should be called with an argument of LBER_USE_DER. +.LP +The +.BR ber_flush2 () +routine is used to actually write the element to a socket +(or file) descriptor, once it has been fully encoded (using +.BR ber_printf () +and friends). See +.BR lber-sockbuf (3) +for more details on the Sockbuf implementation of the \fIsb\fP parameter. +If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will +be freed. +If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed +when successfully flushed, otherwise it is left intact; +if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed +when an error occurs, otherwise it is left intact; +if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. +This function differs from the original +.BR ber_flush (3) +function, whose behavior corresponds to that indicated +for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. +Note that in the future, the behavior of +.BR ber_flush (3) +with \fIfreeit\fP non-zero might change into that of +.BR ber_flush2 (3) +with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. +.LP +The +.BR ber_printf () +routine is used to encode a BER element in much the same way that +.BR sprintf (3) +works. One important difference, though, is +that some state information is kept with the \fIber\fP parameter so +that multiple calls can be made to +.BR ber_printf () +to append things to the end of the BER element. +.BR Ber_printf () +writes to \fIber\fP, a pointer to a BerElement such as returned by +.BR ber_alloc_t (). +It interprets and +formats its arguments according to the format string \fIfmt\fP. +The format string can contain the following characters: +.RS +.LP +.TP 3 +.B b +Boolean. An ber_int_t parameter should be supplied. A boolean element +is output. +.TP +.B e +Enumeration. An ber_int_t parameter should be supplied. An +enumeration element is output. +.TP +.B i +Integer. An ber_int_t parameter should be supplied. An integer element +is output. +.TP +.B B +Bitstring. A char * pointer to the start of the bitstring is supplied, +followed by the number of bits in the bitstring. A bitstring element +is output. +.TP +.B n +Null. No parameter is required. A null element is output. +.TP +.B o +Octet string. A char * is supplied, followed by the length of the +string pointed to. An octet string element is output. +.TP +.B O +Octet string. A struct berval * is supplied. +An octet string element is output. +.TP +.B s +Octet string. A null-terminated string is supplied. An octet string +element is output, not including the trailing NULL octet. +.TP +.B t +Tag. A ber_tag_t specifying the tag to give the next element +is provided. This works across calls. +.TP +.B v +Several octet strings. A null-terminated array of char *'s is +supplied. Note that a construct like '{v}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B V +Several octet strings. A null-terminated array of struct berval *'s +is supplied. Note that a construct like '{V}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B W +Several octet strings. An array of struct berval's is supplied. The +array is terminated by a struct berval with a NULL bv_val. +Note that a construct like '{W}' is required to get +an actual SEQUENCE OF octet strings. +.TP +.B { +Begin sequence. No parameter is required. +.TP +.B } +End sequence. No parameter is required. +.TP +.B [ +Begin set. No parameter is required. +.TP +.B ] +End set. No parameter is required. +.RE +.LP +The +.BR ber_put_int () +routine writes the integer element \fInum\fP to the BER element \fIber\fP. +.LP +The +.BR ber_put_enum () +routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. +.LP +The +.BR ber_put_boolean () +routine writes the boolean value given by \fIbool\fP to the BER element. +.LP +The +.BR ber_put_bitstring () +routine writes \fIblen\fP bits starting +at \fIstr\fP as a bitstring value to the given BER element. Note +that \fIblen\fP is the length \fIin bits\fP of the bitstring. +.LP +The +.BR ber_put_ostring () +routine writes \fIlen\fP bytes starting at +\fIstr\fP to the BER element as an octet string. +.LP +The +.BR ber_put_string () +routine writes the null-terminated string (minus +the terminating '\0') to the BER element as an octet string. +.LP +The +.BR ber_put_null () +routine writes a NULL element to the BER element. +.LP +The +.BR ber_start_seq () +routine is used to start a sequence in the BER element. The +.BR ber_start_set () +routine works similarly. +The end of the sequence or set is marked by the nearest matching call to +.BR ber_put_seq () +or +.BR ber_put_set (), +respectively. +.SH EXAMPLES +Assuming the following variable declarations, and that the variables +have been assigned appropriately, an lber encoding of +the following ASN.1 object: +.LP +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.LP +can be achieved like so: +.LP +.nf + int rc; + ber_int_t scope, ali, size, time, attrsonly; + char *dn, **attrs; + BerElement *ber; + + /* ... fill in values ... */ + + ber = ber_alloc_t( LBER_USE_DER ); + + if ( ber == NULL ) { + /* error */ + } + + rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, + size, time, attrsonly, attrs ); + + if( rc == \-1 ) { + /* error */ + } else { + /* success */ + } +.fi +.SH ERRORS +If an error occurs during encoding, generally these routines return \-1. +.LP +.SH NOTES +.LP +The return values for all of these functions are declared in the + header file. +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-memory (3), +.BR lber-sockbuf (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/lber-memory.3 b/static/netbsd/man3/lber-memory.3 new file mode 100644 index 00000000..6ab1ae38 --- /dev/null +++ b/static/netbsd/man3/lber-memory.3 @@ -0,0 +1,49 @@ +.TH LBER_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_memalloc, ber_memcalloc, ber_memrealloc, ber_memfree, ber_memvfree \- OpenLDAP LBER memory allocators +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include +.LP +.BI "void *ber_memalloc(ber_len_t " bytes ");" +.LP +.BI "void *ber_memcalloc(ber_len_t " nelems ", ber_len_t " bytes ");" +.LP +.BI "void *ber_memrealloc(void *" ptr ", ber_len_t " bytes ");" +.LP +.BI "void ber_memfree(void *" ptr ");" +.LP +.BI "void ber_memvfree(void **" vec ");" +.SH DESCRIPTION +.LP +These routines are used to allocate/deallocate memory used/returned +by the Lightweight BER library as required by +.BR lber-encode (3) +and +.BR lber-decode (3). +.BR ber_memalloc (), +.BR ber_memcalloc (), +.BR ber_memrealloc (), +and +.BR ber_memfree () +are used exactly like the standard +.BR malloc (3), +.BR calloc (3), +.BR realloc (3), +and +.BR free (3) +routines, respectively. The +.BR ber_memvfree () +routine is used to free a dynamically allocated array of pointers to +arbitrary dynamically allocated objects. +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-encode (3), +.BR lber-types (3) +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/lber-sockbuf.3 b/static/netbsd/man3/lber-sockbuf.3 new file mode 100644 index 00000000..2ab2303a --- /dev/null +++ b/static/netbsd/man3/lber-sockbuf.3 @@ -0,0 +1,199 @@ +.TH LBER_SOCKBUF 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO \- OpenLDAP LBER I/O infrastructure +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include +.LP +.B Sockbuf *ber_sockbuf_alloc( void ); +.LP +.BI "void ber_sockbuf_free(Sockbuf *" sb ");" +.LP +.BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");" +.LP +.BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");" +.LP +.BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");" +.LP +.nf +.B typedef struct sockbuf_io_desc { +.BI "int " sbiod_level ";" +.BI "Sockbuf *" sbiod_sb ";" +.BI "Sockbuf_IO *" sbiod_io ";" +.BI "void *" sbiod_pvt ";" +.BI "struct sockbuf_io_desc *" sbiod_next ";" +.B } Sockbuf_IO_Desc; +.LP +.B typedef struct sockbuf_io { +.BI "int (*" sbi_setup ")(Sockbuf_IO_Desc *" sbiod ", void *" arg ");" +.BI "int (*" sbi_remove ")(Sockbuf_IO_Desc *" sbiod ");" +.BI "int (*" sbi_ctrl ")(Sockbuf_IO_Desc *" sbiod ", int " opt ", void *" arg ");" +.BI "ber_slen_t (*" sbi_read ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" +.BI "ber_slen_t (*" sbi_write ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" +.BI "int (*" sbi_close ")(Sockbuf_IO_Desc *" sbiod ");" +.B } Sockbuf_IO; + +.SH DESCRIPTION +.LP +These routines are used to manage the low level I/O operations performed +by the Lightweight BER library. They are called implicitly by the other +libraries and usually do not need to be called directly from applications. +The I/O framework is modularized and new transport layers can be supported +by appropriately defining a +.B Sockbuf_IO +structure and installing it onto an existing +.BR Sockbuf . +.B Sockbuf +structures are allocated and freed by +.BR ber_sockbuf_alloc () +and +.BR ber_sockbuf_free (), +respectively. The +.BR ber_sockbuf_ctrl () +function is used to get and set options related to a +.B Sockbuf +or to a specific I/O layer of the +.BR Sockbuf . +The +.BR ber_sockbuf_add_io () +and +.BR ber_sockbuf_remove_io () +functions are used to add and remove specific I/O layers on a +.BR Sockbuf . + +Options for +.BR ber_sockbuf_ctrl () +include: +.TP +.B LBER_SB_OPT_HAS_IO +Takes a +.B Sockbuf_IO * +argument and returns 1 if the given handler is installed +on the +.BR Sockbuf , +otherwise returns 0. +.TP +.B LBER_SB_OPT_GET_FD +Retrieves the file descriptor associated to the +.BR Sockbuf ; +.B arg +must be a +.BR "ber_socket_t *" . +The return value will be 1 if a valid descriptor was present, \-1 otherwise. +.TP +.B LBER_SB_OPT_SET_FD +Sets the file descriptor of the +.B Sockbuf +to the descriptor pointed to by +.BR arg ; +.B arg +must be a +.BR "ber_socket_t *" . +The return value will always be 1. +.TP +.B LBER_SB_OPT_SET_NONBLOCK +Toggles the non-blocking state of the file descriptor associated to +the +.BR Sockbuf . +.B arg +should be NULL to disable and non-NULL to enable the non-blocking state. +The return value will be 1 for success, \-1 otherwise. +.TP +.B LBER_SB_OPT_DRAIN +Flush (read and discard) all available input on the +.BR Sockbuf . +The return value will be 1. +.TP +.B LBER_SB_OPT_NEEDS_READ +Returns non-zero if input is waiting to be read. +.TP +.B LBER_SB_OPT_NEEDS_WRITE +Returns non-zero if the +.B Sockbuf +is ready to be written. +.TP +.B LBER_SB_OPT_GET_MAX_INCOMING +Returns the maximum allowed size of an incoming message; +.B arg +must be a +.BR "ber_len_t *" . +The return value will be 1. +.TP +.B LBER_SB_OPT_SET_MAX_INCOMING +Sets the maximum allowed size of an incoming message; +.B arg +must be a +.BR "ber_len_t *" . +The return value will be 1. + +.LP +Options not in this list will be passed down to each +.B Sockbuf_IO +handler in turn until one of them processes it. If the option is not handled +.BR ber_sockbuf_ctrl () +will return 0. + +.LP +Multiple +.B Sockbuf_IO +handlers can be stacked in multiple layers to provide various functionality. +Currently defined layers include +.TP +.B LBER_SBIOD_LEVEL_PROVIDER +the lowest layer, talking directly to a network +.TP +.B LBER_SBIOD_LEVEL_TRANSPORT +an intermediate layer +.TP +.B LBER_SBIOD_LEVEL_APPLICATION +a higher layer +.LP +Currently defined +.B Sockbuf_IO +handlers in liblber include +.TP +.B ber_sockbuf_io_tcp +The default stream-oriented provider +.TP +.B ber_sockbuf_io_fd +A stream-oriented provider for local IPC sockets +.TP +.B ber_sockbuf_io_dgram +A datagram-oriented provider. This handler is only present if the liblber +library was built with LDAP_CONNECTIONLESS defined. +.TP +.B ber_sockbuf_io_readahead +A buffering layer, usually used with a datagram provider to hide the +datagram semantics from upper layers. +.TP +.B ber_sockbuf_io_debug +A generic handler that outputs hex dumps of all traffic. This handler +may be inserted multiple times at arbitrary layers to show the flow +of data between other handlers. +.LP +Additional handlers may be present in libldap if support for them was +enabled: +.TP +.B ldap_pvt_sockbuf_io_sasl +An application layer handler for SASL encoding/decoding. +.TP +.B sb_tls_sbio +A transport layer handler for SSL/TLS encoding/decoding. Note that this +handler is private to the library and is not exposed in the API. +.LP +The provided handlers are all instantiated implicitly by libldap, and +applications generally will not need to directly manipulate them. + +.SH SEE ALSO +.BR lber-decode (3), +.BR lber-encode (3), +.BR lber-types (3), +.BR ldap_get_option (3) + +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/lber-types.3 b/static/netbsd/man3/lber-types.3 new file mode 100644 index 00000000..576564a0 --- /dev/null +++ b/static/netbsd/man3/lber-types.3 @@ -0,0 +1,188 @@ +.TH LBER_TYPES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions +.SH LIBRARY +OpenLDAP LBER (liblber, \-llber) +.SH SYNOPSIS +.B #include +.LP +.nf +.ft B +typedef impl_tag_t ber_tag_t; +typedef impl_int_t ber_int_t; +typedef impl_uint_t ber_uint_t; +typedef impl_len_t ber_len_t; +typedef impl_slen_t ber_slen_t; + +typedef struct berval { + ber_len_t bv_len; + char *bv_val; +} BerValue, *BerVarray; + +typedef struct berelement BerElement; +.ft +.fi +.LP +.BI "void ber_bvfree(struct berval *" bv ");" +.LP +.BI "void ber_bvecfree(struct berval **" bvec ");" +.LP +.BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" +.LP +.BI "void ber_bvarray_free(struct berval *" bvarray ");" +.LP +.BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" +.LP +.BI "struct berval *ber_bvdup(const struct berval *" bv ");" +.LP +.BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" +.LP +.BI "struct berval *ber_bvstr(const char *" str ");" +.LP +.BI "struct berval *ber_bvstrdup(const char *" str ");" +.LP +.BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" +.LP +.BI "BerElement *ber_alloc_t(int " options ");" +.LP +.BI "BerElement *ber_init(struct berval *" bv ");" +.LP +.BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" +.LP +.BI "void ber_free(BerElement *" ber ", int " freebuf ");" +.SH DESCRIPTION +.LP +The following are the basic types and structures defined for use +with the Lightweight BER library. +.LP +.B ber_int_t +is a signed integer of at least 32 bits. It is commonly equivalent to +.BR int . +.B ber_uint_t +is the unsigned variant of +.BR ber_int_t . +.LP +.B ber_len_t +is an unsigned integer of at least 32 bits used to represent a length. +It is commonly equivalent to a +.BR size_t . +.B ber_slen_t +is the signed variant to +.BR ber_len_t . +.LP +.B ber_tag_t +is an unsigned integer of at least 32 bits used to represent a +BER tag. It is commonly equivalent to a +.BR unsigned\ long . +.LP +The actual definitions of the integral impl_TYPE_t types are platform +specific. +.LP +.BR BerValue , +commonly used as +.BR struct\ berval , +is used to hold an arbitrary sequence of octets. +.B bv_val +points to +.B bv_len +octets. +.B bv_val +is not necessarily terminated by a NULL (zero) octet. +.BR ber_bvfree () +frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP +is NULL, the routine does nothing. +.LP +.BR ber_bvecfree () +frees an array of BerValues (and the array), pointed to by \fIbvec\fP, +returned from this API. If \fIbvec\fP is NULL, the routine does nothing. +.BR ber_bvecadd () +appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array +is allocated as needed. The end of the array is marked by a NULL pointer. +.LP +.BR ber_bvarray_free () +frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, +returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. +.BR ber_bvarray_add () +appends the contents of the BerValue pointed to by \fIbv\fP to the +\fIbvarray\fP array. Space for the new element is allocated as needed. +The end of the array is marked by a BerValue with a NULL bv_val field. +.LP +.BR ber_bvdup () +returns a copy of a BerValue. The routine returns NULL upon error +(e.g. out of memory). The caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue. +.BR ber_dupbv () +copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a +new BerValue will be allocated to hold the copy. The routine returns NULL +upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is +NULL the caller should use +.BR ber_bvfree () +to deallocate the resulting BerValue, otherwise +.BR ber_memfree () +should be used to deallocate the \fIdst->bv_val\fP. (The +.BR ber_bvdup () +function is internally implemented as ber_dupbv(NULL, bv). +.BR ber_bvdup () +is provided only for compatibility with an expired draft of the LDAP C API; +.BR ber_dupbv () +is the preferred interface.) +.LP +.BR ber_bvstr () +returns a BerValue containing the string pointed to by \fIstr\fP. +.BR ber_bvstrdup () +returns a BerValue containing a copy of the string pointed to by \fIstr\fP. +.BR ber_str2bv () +returns a BerValue containing the string pointed to by \fIstr\fP, whose +length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, +the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the +number of bytes to copy will be determined by +.BR strlen (3), +otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result +will be stored in the given BerValue, otherwise a new BerValue will be +allocated to store the result. NOTE: Both +.BR ber_bvstr () +and +.BR ber_bvstrdup () +are implemented as macros using +.BR ber_str2bv () +in this version of the library. +.LP +.B BerElement +is an opaque structure used to maintain state information used in +encoding and decoding. +.BR ber_alloc_t () +is used to create an empty BerElement structure. If +.B LBER_USE_DER +is specified for the +.I options +parameter then data lengths for data written to the BerElement will be +encoded in the minimal number of octets required, otherwise they will +always be written as four byte values. +.BR ber_init () +creates a BerElement structure that is initialized with a copy of the +data in its +.I bv +parameter. +.BR ber_init2 () +initializes an existing BerElement +.I ber +using the data in the +.I bv +parameter. The data is referenced directly, not copied. The +.I options +parameter is the same as for +.BR ber_alloc_t (). +.BR ber_free () +frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine +does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. +.SH SEE ALSO +.BR lber-encode (3), +.BR lber-decode (3), +.BR lber-memory (3) +.LP +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap.3 b/static/netbsd/man3/ldap.3 new file mode 100644 index 00000000..1c118b3e --- /dev/null +++ b/static/netbsd/man3/ldap.3 @@ -0,0 +1,278 @@ +.TH LDAP 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap \- OpenLDAP Lightweight Directory Access Protocol API +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.ft +.fi +.SH DESCRIPTION +.LP +The Lightweight Directory Access Protocol (LDAP) (RFC 4510) provides +access to X.500 directory services. These services may be stand\-alone +or part of a distributed directory service. This client API supports +LDAP over TCP (RFC 4511), LDAP over TLS/SSL, and LDAP over IPC (UNIX +domain sockets). This API supports SASL (RFC 4513) and Start TLS +(RFC 4513) as well as a number of protocol extensions. This API is +loosely based upon IETF/LDAPEXT C LDAP API draft specification, a (orphaned) +work in progress. +.LP +The OpenLDAP Software package includes a stand\-alone server in +.BR slapd (8), +various LDAP clients, and an LDAP client library used to provide +programmatic access to the LDAP protocol. This man page gives an +overview of the LDAP library routines. +.LP +Both synchronous and asynchronous APIs are provided. Also included are +various routines to parse the results returned from these routines. +These routines are found in the \-lldap library. +.LP +The basic interaction is as follows. A session handle is +created using +.BR ldap_initialize (3) +and set the protocol version to 3 by calling +.BR ldap_set_option (3). +The underlying session is established first operation is +issued. This would generally be a Start TLS or Bind operation, +or a Search operation to read attributes of the Root DSE. +A Start TLS operation is performed by calling +.BR ldap_start_tls_s (3). +A LDAP bind operation is performed by calling +.BR ldap_sasl_bind (3) +or one of its friends. +A Search operation is performed by calling ldap_search_ext_s(3) +or one of its friends. + +Subsequently, additional operations are performed +by calling one of the synchronous or asynchronous routines (e.g., +.BR ldap_compare_ext_s (3) +or +.BR ldap_compare_ext (3) +followed by +.BR ldap_result (3)). +Results returned from these routines are interpreted by calling the +LDAP parsing routines such as +.BR ldap_parse_result (3). +The LDAP association and underlying connection is terminated by calling +.BR ldap_unbind_ext (3). +Errors can be interpreted by calling +.BR ldap_err2string (3). +.SH LDAP versions +This library supports version 3 of the Lightweight Directory Access +Protocol (LDAPv3) as defined in RFC 4510. It also supports a variant +of version 2 of LDAP as defined by U-Mich LDAP and, to some degree, +RFC 1777. Version 2 (all variants) are considered obsolete. +Version 3 should be used instead. +.LP +For backwards compatibility reasons, the library defaults to version 2. +Hence, all new applications (and all actively maintained applications) +should use +.BR ldap_set_option (3) +to select version 3. The library manual pages assume version 3 +has been selected. +.SH INPUT and OUTPUT PARAMETERS +All character string input/output is expected to be/is UTF-8 +encoded Unicode (version 3.2). +.LP +Distinguished names (DN) (and relative distinguished names (RDN) to +be passed to the LDAP routines should conform to RFC 4514 UTF-8 +string representation. +.LP +Search filters to be passed to the search routines are to be +constructed by hand and should conform to RFC 4515 UTF-8 +string representation. +.LP +LDAP URLs to be passed to routines are expected to conform +to RFC 4516 format. The +.BR ldap_url (3) +routines can be used to work with LDAP URLs. +.LP +LDAP controls to be passed to routines can be manipulated using the +.BR ldap_controls (3) +routines. +.SH DISPLAYING RESULTS +Results obtained from the search routines can be output by hand, +by calling +.BR ldap_first_entry (3) +and +.BR ldap_next_entry (3) +to step through +the entries returned, +.BR ldap_first_attribute (3) +and +.BR ldap_next_attribute (3) +to step through an entry's attributes, and +.BR ldap_get_values (3) +to retrieve a given attribute's values. Attribute values +may or may not be displayable. +.SH UTILITY ROUTINES +Also provided are various utility routines. The +.BR ldap_sort (3) +routines are used to sort the entries and values returned via +the ldap search routines. +.SH DEPRECATED INTERFACES +A number of interfaces are now considered deprecated. For instance, +ldap_add(3) is deprecated in favor of ldap_add_ext(3). +.so Deprecated +.SH BER LIBRARY +Also included in the distribution is a set of lightweight Basic +Encoding Rules routines. These routines are used by the LDAP library +routines to encode and decode LDAP protocol elements using the +(slightly simplified) Basic Encoding Rules defined by LDAP. They are +not normally used directly by an LDAP application program except +in the handling of controls and extended operations. The +routines provide a printf and scanf\-like interface, as well as +lower\-level access. These routines are discussed in +.BR lber\-decode (3), +.BR lber\-encode (3), +.BR lber\-memory (3), +and +.BR lber\-types (3). +.SH INDEX +.TP 20 +.SM ldap_initialize(3) +initialize the LDAP library without opening a connection to a server +.TP +.SM ldap_result(3) +wait for the result from an asynchronous operation +.TP +.SM ldap_abandon_ext(3) +abandon (abort) an asynchronous operation +.TP +.SM ldap_add_ext(3) +asynchronously add an entry +.TP +.SM ldap_add_ext_s(3) +synchronously add an entry +.TP +.SM ldap_sasl_bind(3) +asynchronously bind to the directory +.TP +.SM ldap_sasl_bind_s(3) +synchronously bind to the directory +.TP +.SM ldap_unbind_ext(3) +synchronously unbind from the LDAP server and close the connection +.TP +.SM ldap_unbind(3) and ldap_unbind_s(3) are +equivalent to +.BR ldap_unbind_ext (3) +.TP +.SM ldap_memfree(3) +dispose of memory allocated by LDAP routines. +.TP +.SM ldap_compare_ext(3) +asynchronously compare to a directory entry +.TP +.SM ldap_compare_ext_s(3) +synchronously compare to a directory entry +.TP +.SM ldap_delete_ext(3) +asynchronously delete an entry +.TP +.SM ldap_delete_ext_s(3) +synchronously delete an entry +.TP +.SM ld_errno(3) +LDAP error indication +.TP +.SM ldap_errlist(3) +list of LDAP errors and their meanings +.TP +.SM ldap_err2string(3) +convert LDAP error indication to a string +.TP +.SM ldap_extended_operation(3) +asynchronously perform an arbitrary extended operation +.TP +.SM ldap_extended_operation_s(3) +synchronously perform an arbitrary extended operation +.TP +.SM ldap_first_attribute(3) +return first attribute name in an entry +.TP +.SM ldap_next_attribute(3) +return next attribute name in an entry +.TP +.SM ldap_first_entry(3) +return first entry in a chain of search results +.TP +.SM ldap_next_entry(3) +return next entry in a chain of search results +.TP +.SM ldap_count_entries(3) +return number of entries in a search result +.TP +.SM ldap_get_dn(3) +extract the DN from an entry +.TP +.SM ldap_get_values_len(3) +return an attribute's values with lengths +.TP +.SM ldap_value_free_len(3) +free memory allocated by ldap_get_values_len(3) +.TP +.SM ldap_count_values_len(3) +return number of values +.TP +.SM ldap_modify_ext(3) +asynchronously modify an entry +.TP +.SM ldap_modify_ext_s(3) +synchronously modify an entry +.TP +.SM ldap_mods_free(3) +free array of pointers to mod structures used by ldap_modify_ext(3) +.TP +.SM ldap_rename(3) +asynchronously rename an entry +.TP +.SM ldap_rename_s(3) +synchronously rename an entry +.TP +.SM ldap_msgfree(3) +free results allocated by ldap_result(3) +.TP +.SM ldap_msgtype(3) +return the message type of a message from ldap_result(3) +.TP +.SM ldap_msgid(3) +return the message id of a message from ldap_result(3) +.TP +.SM ldap_search_ext(3) +asynchronously search the directory +.TP +.SM ldap_search_ext_s(3) +synchronously search the directory +.TP +.SM ldap_is_ldap_url(3) +check a URL string to see if it is an LDAP URL +.TP +.SM ldap_url_parse(3) +break up an LDAP URL string into its components +.TP +.SM ldap_sort_entries(3) +sort a list of search results +.TP +.SM ldap_sort_values(3) +sort a list of attribute values +.TP +.SM ldap_sort_strcasecmp(3) +case insensitive string comparison +.SH SEE ALSO +.BR ldap.conf (5), +.BR slapd (8), +.BR draft-ietf-ldapext-ldap-c-api-xx.txt \ +.SH ACKNOWLEDGEMENTS +.so ../Project +.LP +These API manual pages are loosely based upon descriptions provided +in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work +in progress. + diff --git a/static/netbsd/man3/ldap_abandon.3 b/static/netbsd/man3/ldap_abandon.3 new file mode 100644 index 00000000..f6ae0c27 --- /dev/null +++ b/static/netbsd/man3/ldap_abandon.3 @@ -0,0 +1,69 @@ +.TH LDAP_ABANDON 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_abandon_ext \- Abandon an LDAP operation in progress +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B +#include +.LP +.ft B +int ldap_abandon_ext( +.RS +.ft B +LDAP *\fIld\fB, +Bint \fImsgid\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB ); +.RE +.fi +.SH DESCRIPTION +The +.B ldap_abandon_ext() +routine is used to send a LDAP Abandon request for an +operation in progress. The \fImsgid\fP passed should be the +message id of an outstanding LDAP operation, such as returned by +.BR ldap_search_ext (3). +.LP +.BR ldap_abandon_ext () +checks to see if the result of the operation has already come in. If it +has, it deletes it from the queue of pending messages. If not, +it sends an LDAP abandon request to the LDAP server. +.LP +The caller can expect that the result of an abandoned operation +will not be returned from a future call to +.BR ldap_result (3). +.LP +.B ldap_abandon_ext() +allows server and client controls to be passed in via the +.I sctrls +and +.I cctrls +parameters, respectively. +.LP +.B ldap_abandon_ext() +returns a code indicating success or, in the case of failure, the +nature of the failure. See +.BR ldap_error (3) +for details. +.SH DEPRECATED INTERFACES +The +.B ldap_abandon() +routine is deprecated in favor of the +.B ldap_abandon_ext() +routine. +.LP +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_result (3), +.BR ldap_search_ext (3) +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/static/netbsd/man3/ldap_add.3 b/static/netbsd/man3/ldap_add.3 new file mode 100644 index 00000000..c15a55ef --- /dev/null +++ b/static/netbsd/man3/ldap_add.3 @@ -0,0 +1,81 @@ +.TH LDAP_ADD 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.ft B +#include +.LP +.ft B +.nf +int ldap_add_ext( +.RS +.ft B +LDAP *\fIld, +const char *\fIdn\fB, +LDAPMod **\fIattrs\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +.nf +int ldap_add_ext_s( +.RS +LDAP *\fIld\fB, +const char *\fIdn\fB, +LDAPMod **\fIattrs\fB, +LDAPControl *\fIsctrls\fB, +LDAPControl *\fIcctrls\fB ); +.RE +.fi +.SH DESCRIPTION +The +.B ldap_add_ext_s() +routine is used to perform an LDAP add operation. +It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a +null-terminated array of the entry's attributes. The LDAPMod structure +is used to represent attributes, with the \fImod_type\fP and +\fImod_values\fP fields being used as described under +.BR ldap_modify_ext (3), +and the \fIldap_op\fP field being used only if you need to specify +the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. +.LP +Note that all entries except that +specified by the last component in the given DN must already exist. +.B ldap_add_ext_s() +returns an code indicating success or, in the case of failure, +indicating the nature of failure of the operation. See +.BR ldap_error (3) +for more details. +.LP +The +.B ldap_add_ext() +routine works just like +.BR ldap_add_ext_s() , +but it is asynchronous. It returns the message id of the request it +initiated. The result of this operation can be obtained by calling +.BR ldap_result (3). +.SH DEPRECATED INTERFACES +The +.BR ldap_add () +and +.BR ldap_add_s () +routines are deprecated in favor of the +.BR ldap_add_ext () +and +.BR ldap_add_ext_s () +routines, respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_modify (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_bind.3 b/static/netbsd/man3/ldap_bind.3 new file mode 100644 index 00000000..7182f232 --- /dev/null +++ b/static/netbsd/man3/ldap_bind.3 @@ -0,0 +1,337 @@ +.TH LDAP_BIND 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include +.LP +.BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," +.RS +.BI "int " method ");" +.RE +.LP +.BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," +.RS +.BI "int " method ");" +.RE +.LP +.BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" +.LP +.BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" +.LP +.BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," +.RS +.BI "struct berval *" cred ", LDAPControl *" sctrls "[]," +.BI "LDAPControl *" cctrls "[], int *" msgidp ");" +.RE +.LP +.BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," +.RS +.BI "struct berval *" cred ", LDAPControl *" sctrls "[]," +.BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" +.RE +.LP +.BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," +.RS +.BI "struct berval **" servercredp ", int " freeit ");" +.RE +.LP +.BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," +.RS +.BI "const char *" mechs "," +.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," +.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," +.BI "void *" defaults ");" +.RE +.LP +.BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," +.RS +.BI "const char *" mechs "," +.BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," +.BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," +.BI "void *" defaults ", LDAPMessage *" result "," +.BI "const char **" rmechp ", int *" msgidp ");" +.RE +.LP +.BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" +.LP +.BI "int ldap_unbind(LDAP *" ld ");" +.LP +.BI "int ldap_unbind_s(LDAP *" ld ");" +.LP +.BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," +.RS +.BI "LDAPControl *" cctrls "[]);" +.RE +.LP +.BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," +.RS +.BI "LDAPControl *" cctrls "[]);" +.RE +.LP +.BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" +.LP +.BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" +.SH DESCRIPTION +.LP +These routines provide various interfaces to the LDAP bind operation. +After an association with an LDAP server is made using +.BR ldap_init (3), +an LDAP bind operation should be performed before other operations are +attempted over the connection. An LDAP bind is required when using +Version 2 of the LDAP protocol; it is optional for Version 3 but is +usually needed due to security considerations. +.LP +There are three types of bind calls, ones providing simple authentication, +ones providing SASL authentication, and general routines capable of doing +either simple or SASL authentication. +.LP +.B SASL +(Simple Authentication and Security Layer) +can negotiate one of many different kinds of authentication. +Both synchronous and asynchronous versions of each variant of the bind +call are provided. All routines +take \fIld\fP as their first parameter, as returned from +.BR ldap_init (3). +.SH SIMPLE AUTHENTICATION +The simplest form of the bind call is +.BR ldap_simple_bind_s() . +It takes the DN to bind as in \fIwho\fP, and the userPassword associated +with the entry in \fIpasswd\fP. It returns an LDAP error indication +(see +.BR ldap_error (3)). +The +.B ldap_simple_bind() +call is asynchronous, +taking the same parameters but only initiating the bind operation and +returning the message id of the request it sent. The result of the +operation can be obtained by a subsequent call to +.BR ldap_result (3). +The +.B ldap_sasl_bind_s() +and asynchronous +.B ldap_sasl_bind() +functions can also be used to make a simple bind by using +LDAP_SASL_SIMPLE as the SASL mechanism. +.SH GENERAL AUTHENTICATION +The +.B ldap_bind() +and +.B ldap_bind_s() +routines can be used when the +authentication method to use needs to be selected at runtime. They +both take an extra \fImethod\fP parameter selecting the authentication +method to use. It should be set to LDAP_AUTH_SIMPLE +to select simple authentication. +.B ldap_bind() +returns the message id of the request it initiates. +.B ldap_bind_s() +returns an LDAP error indication. +.SH SASL AUTHENTICATION +For SASL binds the server always ignores any provided DN, so the +.I dn +parameter should always be NULL. +.BR ldap_sasl_bind_s () +sends a single SASL bind request with the given SASL +.I mechanism +and credentials in the +.I cred +parameter. The format of the credentials depends on the particular +SASL mechanism in use. For mechanisms that provide mutual authentication +the server's credentials will be returned in the +.I servercredp +parameter. +The routine returns an LDAP error indication (see +.BR ldap_error (3)). +The +.BR ldap_sasl_bind () +call is asynchronous, taking the same parameters but only sending the +request and returning the message id of the request it sent. The result of +the operation can be obtained by a subsequent +call to +.BR ldap_result (3). +The result must be additionally parsed by +.BR ldap_parse_sasl_bind_result () +to obtain any server credentials sent from the server. + +Any returned server credentials should be freed using +.BR ber_bvfree (). +.LP +Many SASL mechanisms require multiple message exchanges to perform a +complete authentication. Applications should generally use +.BR ldap_sasl_interactive_bind_s () +rather than calling the basic +.BR ldap_sasl_bind () +functions directly. The +.I mechs +parameter should contain a space-separated list of candidate mechanisms +to use. If this parameter is NULL or empty the library will query +the supportedSASLMechanisms attribute from the server's rootDSE +for the list of SASL mechanisms the server supports. The +.I flags +parameter controls the interaction used to retrieve any necessary +SASL authentication parameters and should be one of: +.TP +LDAP_SASL_AUTOMATIC +use defaults if available, prompt otherwise +.TP +LDAP_SASL_INTERACTIVE +always prompt +.TP +LDAP_SASL_QUIET +never prompt +.LP +The +.I interact +function uses the provided +.I defaults +to handle requests from the SASL library for particular authentication +parameters. There is no defined format for the +.I defaults +information; +it is up to the caller to use whatever format is appropriate for the +supplied +.I interact +function. +The +.I sasl_interact +parameter comes from the underlying SASL library. When used with Cyrus SASL +this is an array of +.B sasl_interact_t +structures. The Cyrus SASL library will prompt for a variety of inputs, +including: +.TP +SASL_CB_GETREALM +the realm for the authentication attempt +.TP +SASL_CB_AUTHNAME +the username to authenticate +.TP +SASL_CB_PASS +the password for the provided username +.TP +SASL_CB_USER +the username to use for proxy authorization +.TP +SASL_CB_NOECHOPROMPT +generic prompt for input with input echoing disabled +.TP +SASL_CB_ECHOPROMPT +generic prompt for input with input echoing enabled +.TP +SASL_CB_LIST_END +indicates the end of the array of prompts +.LP +See the Cyrus SASL documentation for more details. +.LP +Applications which need to manage connections asynchronously may use +.BR ldap_sasl_interactive_bind () +instead of the synchronous version. +A valid mechs parameter must be supplied, otherwise the library will +be forced to query the server for a list of supported mechanisms, +and this query will be performed synchronously. +The other parameters are the same as +for the synchronous function, with three additional parameters. +The actual SASL mechanism that was used, and the message ID for use +with +.BR ldap_result () +will be returned in rmechp and msgidp, respectively. +The value in rmechp must not be modified by the caller and must be +passed back on each subsequent call. The message obtained from +.BR ldap_result () +must be passed in the result parameter. +This parameter must be NULL when initiating a new Bind. The caller +must free the result message after each call using +.BR ldap_msgfree (). +The +.BR ldap_sasl_interactive_bind () +function returns an LDAP result code. If the code is +LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and +this function must be called again with the next result from the server. +.SH REBINDING +.LP +The +.B ldap_set_rebind_proc +function() sets the process to use for binding when an operation returns a +referral. This function is used when an application needs to bind to another server +in order to follow a referral or search continuation reference. +.LP +The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, +the arbitrary data like state information which the client might need to properly rebind. +The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries +to use the rebind function. Use the +.BR ldap_set_option +function to set the value. +.LP +The rebind function parameters are as follows: +.LP +The \fIld\fP parameter must be used by the application when binding to the +referred server if the application wants the libraries to follow the referral. +.LP +The \fIurl\fP parameter points to the URL referral string received from the LDAP server. +The LDAP application can use the +.BR ldap_url_parse (3) +function to parse the string into its components. +.LP +The \fIrequest\fP parameter specifies the type of request that generated the referral. +.LP +The \fImsgid\fP parameter specifies the message ID of the request generating the referral. +.LP +The \fIparams\fP parameter is the same value as passed originally to the +.BR ldap_set_rebind_proc () +function. +.LP +The LDAP libraries set all the parameters when they call the rebind function. The application +should not attempt to free either the ld or the url structures in the rebind function. +.LP +The application must supply to the rebind function the required authentication information such as, +user name, password, and certificates. The rebind function must use a synchronous bind method. +.SH UNBINDING +The +.B ldap_unbind() +call is used to unbind from the directory, +terminate the current association, and free the resources contained +in the \fIld\fP structure. Once it is called, the connection to +the LDAP server is closed, and the \fIld\fP structure is invalid. +The +.B ldap_unbind_s() +call is just another name for +.BR ldap_unbind() ; +both of these calls are synchronous in nature. +.LP +The +.B ldap_unbind_ext() +and +.B ldap_unbind_ext_s() +allows the operations to specify controls. +.SH ERRORS +Asynchronous routines will return \-1 in case of error, setting the +\fIld_errno\fP parameter of the \fIld\fP structure. Synchronous +routines return whatever \fIld_errno\fP is set to. See +.BR ldap_error (3) +for more information. +.SH NOTES +If an anonymous bind is sufficient for the application, the rebind process +need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option +set to ON (default value) will automatically follow referrals using an anonymous bind. +.LP +If the application needs stronger authentication than an anonymous bind, +you need to provide a rebind process for that authentication method. +The bind method must be synchronous. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_open (3), +.BR ldap_set_option (3), +.BR ldap_url_parse (3) +.B RFC 4422 +(http://www.rfc-editor.org), +.B Cyrus SASL +(http://asg.web.cmu.edu/sasl/) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_compare.3 b/static/netbsd/man3/ldap_compare.3 new file mode 100644 index 00000000..3fd4a6cf --- /dev/null +++ b/static/netbsd/man3/ldap_compare.3 @@ -0,0 +1,79 @@ +.TH LDAP_COMPARE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_compare_ext( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +char *\fIattr\fB, +const struct berval *\fIbvalue\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_compare_ext_s( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +char *\fIattr\fB, +const struct berval *\fIbvalue\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB ); +.RE +.SH DESCRIPTION +The +.B ldap_compare_ext_s() +routine is used to perform an LDAP compare operation synchronously. +It takes \fIdn\fP, the DN of the entry upon which to perform the +compare, and \fIattr\fP and \fIvalue\fP, the attribute description and +value to compare to those found in the entry. It returns a code, which +will be LDAP_COMPARE_TRUE if the entry contains the attribute value and +LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is +returned that indicates the nature of the problem. See +.BR ldap (3) +for details. +.LP +The +.B ldap_compare_ext() +routine is used to perform an LDAP compare operation +asynchronously. It takes the same parameters as +.BR ldap_compare_ext_s() , +but provides the message id of the request it initiated in the +integer pointed to \fImsgidp\fP. The result of +the compare can be obtained by a subsequent call to +.BR ldap_result (3). +.LP +Both routines allow server and client controls to be specified to +extend the compare request. +.SH DEPRECATED INTERFACES +The routines +.BR ldap_compare () +and +.BR ldap_compare_s () +are deprecated in favor of +.BR ldap_compare_ext () +and +.BR ldap_compare_ext_s (), +respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_controls.3 b/static/netbsd/man3/ldap_controls.3 new file mode 100644 index 00000000..29d068ab --- /dev/null +++ b/static/netbsd/man3/ldap_controls.3 @@ -0,0 +1,84 @@ +.TH LDAP_CONTROLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_control_create, ldap_control_find, ldap_control_dup, +ldap_controls_dup, ldap_control_free, ldap_controls_free +\- LDAP control manipulation routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include +.LP +.BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" +.LP +.BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" +.LP +.BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" +.LP +.BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" +.LP +.BI "void ldap_control_free(LDAPControl *" ctrl ");" +.LP +.BI "void ldap_controls_free(LDAPControl **" ctrls ");" +.SH DESCRIPTION +These routines are used to manipulate structures used for LDAP controls. + +.BR ldap_control_create () +creates a control with the specified +.I OID +using the contents of the +.I value +parameter for the control value, if any. The content of +.I value +is duplicated if +.I dupval +is non-zero. The +.I iscritical +parameter must be non-zero for a critical control. The created control +is returned in the +.I ctrlp +parameter. The routine returns +.B LDAP_SUCCESS +on success or some other error code on failure. +The content of +.IR value , +for supported control types, can be prepared using helpers provided +by this implementation of libldap, usually in the form +.BR "ldap_create__control_value" (). +Otherwise, it can be BER-encoded using the functionalities of liblber. + +.BR ldap_control_find () +searches the NULL-terminated +.I ctrls +array for a control whose OID matches the +.I oid +parameter. The routine returns a pointer to the control if found, +NULL otherwise. +If the parameter +.I nextctrlp +is not NULL, on return it will point to the next control +in the array, and can be passed to the +.BR ldap_control_find () +routine for subsequent calls, to find further occurrences of the same +control type. +The use of this function is discouraged; the recommended way of handling +controls in responses consists in going through the array of controls, +dealing with each of them in the returned order, since it could matter. + +.BR ldap_control_dup () +duplicates an individual control structure, and +.BR ldap_controls_dup () +duplicates a NULL-terminated array of controls. + +.BR ldap_control_free () +frees an individual control structure, and +.BR ldap_controls_free () +frees a NULL-terminated array of controls. + +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_delete.3 b/static/netbsd/man3/ldap_delete.3 new file mode 100644 index 00000000..42e38475 --- /dev/null +++ b/static/netbsd/man3/ldap_delete.3 @@ -0,0 +1,89 @@ +.TH LDAP_DELETE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_delete_s(ld, dn) +.ft +LDAP *ld; +char *dn; +.LP +.ft B +int ldap_delete(ld, dn) +.ft +LDAP *ld; +char *dn; +.LP +.ft B +int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) +.ft +LDAP *ld; +char *dn; +LDAPControl **serverctrls, **clientctrls; +int *msgidp; +.LP +.ft B +int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) +.ft +LDAP *ld; +char *dn; +LDAPControl **serverctrls, **clientctrls; +.SH DESCRIPTION +The +.B ldap_delete_s() +routine is used to perform an LDAP delete operation +synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. +It returns an LDAP error code, indicating the success or failure of the +operation. +.LP +The +.B ldap_delete() +routine is used to perform an LDAP delete operation +asynchronously. It takes the same parameters as +.BR ldap_delete_s(), +but returns the message id of the request it initiated. The result of +the delete can be obtained by a subsequent call to +.BR ldap_result (3). +.LP +The +.B ldap_delete_ext() +routine allows server and client controls to be +specified to extend the delete request. This routine is asynchronous like +ldap_delete(), but its return value is an LDAP error code. It stores the +message id of the request in the integer pointed to by msgidp. +.LP +The +.B ldap_delete_ext_s() +routine is the synchronous version of +.BR ldap_delete_ext(). +It also returns an LDAP error code indicating success +or failure of the operation. +.SH ERRORS +.B ldap_delete_s() +returns an LDAP error code which can be interpreted +by calling one of +.BR ldap_perror (3) +and friends. +.B ldap_delete() +returns \-1 if something went wrong initiating the request. It returns the +non-negative message id of the request if things went ok. +.LP +.B ldap_delete_ext() +and +.B ldap_delete_ext_s() +return some Non-zero value if +something went wrong initiating the request, else return 0. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_dup.3 b/static/netbsd/man3/ldap_dup.3 new file mode 100644 index 00000000..d2432c64 --- /dev/null +++ b/static/netbsd/man3/ldap_dup.3 @@ -0,0 +1,125 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +LDAP *ldap_dup( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.LP +.ft B +int ldap_destroy( +.RS +.ft B +LDAP *\fIold\fB ); +.RE +.SH DESCRIPTION +.LP +.B ldap_dup() +duplicates an existing LDAP +.RB ( "LDAP *" ) +session handle. +The new session handle may be used concurrently with the +original session handle. +In a threaded environment, different threads may execute concurrent +requests on the same connection/session without fear of contamination. +Each session handle manages its own private error results. +.LP +.B ldap_destroy() +destroys an existing session handle. +.LP +The +.B ldap_dup() +and +.B ldap_destroy() +functions are used in conjunction with a "thread safe" version +of +.B libldap +to enable operation thread safe API calls, so that a single session +may be simultaneously used across multiple threads with consistent +error handling. +.LP +When a session is created through the use of one of the session creation +functions including +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3) +or +.BR ldap_init_fd (3) +an +.B "LDAP *" +session handle is returned to the application. +The session handle may be shared amongst threads, however the +error codes are unique to a session handle. +Multiple threads performing different operations using the same +session handle will result in inconsistent error codes and +return values. +.LP +To prevent this confusion, +.B ldap_dup() +is used duplicate an existing session handle so that multiple threads +can share the session, and maintain consistent error information +and results. +.LP +The message queues for a session are shared between sibling session handles. +Results of operations on a sibling session handles are accessible +to all the sibling session handles. +Applications desiring results associated with a specific operation +should provide the appropriate msgid to +.BR ldap_result() . +Applications should avoid calling +.B ldap_result() +with +.B LDAP_RES_ANY +as that may "steal" and return results in the calling thread +that another operation in a different thread, using a +different session handle, may require to complete. +.LP +When +.B ldap_unbind() +is called on a session handle with siblings, all the +siblings become invalid. +.LP +Siblings must be destroyed using +.BR ldap_destroy() . +Session handle resources associated with the original +.RB ( "LDAP *" ) +will be freed when the last session handle is destroyed or when +.B ldap_unbind() +is called, if no other session handles currently exist. +.SH ERRORS +If an error occurs, +.B ldap_dup() +will return NULL and +.I errno +should be set appropriately. +.B ldap_destroy() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +.I errno +should be set as well whenever appropriate. +.SH SEE ALSO +.BR ldap_open (3), +.BR ldap_init (3), +.BR ldap_initialize (3), +.BR ldap_init_fd (3), +.BR errno (3) +.SH ACKNOWLEDGEMENTS +This work is based on the previously proposed +.B LDAP C API Concurrency Extensions +draft +.BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) +effort. +.so ../Project diff --git a/static/netbsd/man3/ldap_error.3 b/static/netbsd/man3/ldap_error.3 new file mode 100644 index 00000000..a4e8b845 --- /dev/null +++ b/static/netbsd/man3/ldap_error.3 @@ -0,0 +1,224 @@ +.TH LDAP_ERROR 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +char *ldap_err2string( int \fIerr\fB ); +.SH DESCRIPTION +The +.B ldap_err2string() +routine provides short description of the various codes returned by +routines in this library. The returned string is a pointer to a +static area that should not be modified. + +These codes are either negative, +indicating an API error code; positive, indicating an LDAP resultCode +other than \'success' (0), or - zero, indicating both successful use +of the API and the LDAP resultCode \'success' (0). + +The code associated with an LDAP session is accessible using +.BR ldap_get_option (3) +and +.BR ldap_set_option (3) +with the +.B LDAP_OPT_RESULT_CODE +option (previously called +.BR LDAP_OPT_ERROR_NUMBER ). + +.SH PROTOCOL RESULT CODES + +This section provides a partial list of protocol codes recognized +by the library. As LDAP is extensible, additional values may be +returned. A complete listing of \fIregistered\fP LDAP result codes +can be obtained from the \fIInternet Assigned Numbers Authority\fP +. + +.LP +.TP 20 +.SM LDAP_SUCCESS +The request was successful. +.TP +.SM LDAP_OPERATIONS_ERROR +An operations error occurred. +.TP +.SM LDAP_PROTOCOL_ERROR +A protocol violation was detected. +.TP +.SM LDAP_TIMELIMIT_EXCEEDED +An LDAP time limit was exceeded. +.TP +.SM LDAP_SIZELIMIT_EXCEEDED +An LDAP size limit was exceeded. +.TP +.SM LDAP_COMPARE_FALSE +A compare operation returned false. +.TP +.SM LDAP_COMPARE_TRUE +A compare operation returned true. +.TP +.SM LDAP_STRONG_AUTH_NOT_SUPPORTED +The LDAP server does not support strong authentication. +.TP +.SM LDAP_STRONG_AUTH_REQUIRED +Strong authentication is required for the operation. +.TP +.SM LDAP_PARTIAL_RESULTS +Partial results only returned. +.TP +.SM LDAP_NO_SUCH_ATTRIBUTE +The attribute type specified does not exist in the entry. +.TP +.SM LDAP_UNDEFINED_TYPE +The attribute type specified is invalid. +.TP +.SM LDAP_INAPPROPRIATE_MATCHING +Filter type not supported for the specified attribute. +.TP +.SM LDAP_CONSTRAINT_VIOLATION +An attribute value specified violates some constraint (e.g., a postalAddress +has too many lines, or a line that is too long). +.TP +.SM LDAP_TYPE_OR_VALUE_EXISTS +An attribute type or attribute value specified already exists in the entry. +.TP +.SM LDAP_INVALID_SYNTAX +An invalid attribute value was specified. +.TP +.SM LDAP_NO_SUCH_OBJECT +The specified object does not exist in The Directory. +.TP +.SM LDAP_ALIAS_PROBLEM +An alias in The Directory points to a nonexistent entry. +.TP +.SM LDAP_INVALID_DN_SYNTAX +A syntactically invalid DN was specified. +.TP +.SM LDAP_IS_LEAF +The object specified is a leaf. +.TP +.SM LDAP_ALIAS_DEREF_PROBLEM +A problem was encountered when dereferencing an alias. +.TP +.SM LDAP_INAPPROPRIATE_AUTH +Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was +specified and the entry does not have a userPassword attribute). +.TP +.SM LDAP_INVALID_CREDENTIALS +Invalid credentials were presented (e.g., the wrong password). +.TP +.SM LDAP_INSUFFICIENT_ACCESS +The user has insufficient access to perform the operation. +.TP +.SM LDAP_BUSY +The DSA is busy. +.TP +.SM LDAP_UNAVAILABLE +The DSA is unavailable. +.TP +.SM LDAP_UNWILLING_TO_PERFORM +The DSA is unwilling to perform the operation. +.TP +.SM LDAP_LOOP_DETECT +A loop was detected. +.TP +.SM LDAP_NAMING_VIOLATION +A naming violation occurred. +.TP +.SM LDAP_OBJECT_CLASS_VIOLATION +An object class violation occurred (e.g., a "must" attribute was missing +from the entry). +.TP +.SM LDAP_NOT_ALLOWED_ON_NONLEAF +The operation is not allowed on a nonleaf object. +.TP +.SM LDAP_NOT_ALLOWED_ON_RDN +The operation is not allowed on an RDN. +.TP +.SM LDAP_ALREADY_EXISTS +The entry already exists. +.TP +.SM LDAP_NO_OBJECT_CLASS_MODS +Object class modifications are not allowed. +.TP +.SM LDAP_OTHER +An unknown error occurred. + +.SH API ERROR CODES + +This section provides a complete list of API error codes recognized +by the library. Note that LDAP_SUCCESS indicates success of an +API call in addition to representing the return of the LDAP +\'success' resultCode. + + +.LP +.TP 20 +.SM LDAP_SERVER_DOWN +The LDAP library can't contact the LDAP server. +.TP +.SM LDAP_LOCAL_ERROR +Some local error occurred. This is usually a failed dynamic memory allocation. +.TP +.SM LDAP_ENCODING_ERROR +An error was encountered encoding parameters to send to the LDAP server. +.TP +.SM LDAP_DECODING_ERROR +An error was encountered decoding a result from the LDAP server. +.TP +.SM LDAP_TIMEOUT +A timelimit was exceeded while waiting for a result. +.TP +.SM LDAP_AUTH_UNKNOWN +The authentication method specified to ldap_bind() is not known. +.TP +.SM LDAP_FILTER_ERROR +An invalid filter was supplied to ldap_search() (e.g., unbalanced +parentheses). +.TP +.SM LDAP_PARAM_ERROR +An ldap routine was called with a bad parameter. +.TP +.SM LDAP_NO_MEMORY +An memory allocation (e.g., malloc(3) or other dynamic memory +allocator) call failed in an ldap library routine. +.TP +.SM LDAP_USER_CANCELED +Indicates the user cancelled the operation. +.TP +.SM LDAP_CONNECT_ERROR +Indicates a connection problem. +.TP +.SM LDAP_NOT_SUPPORTED +Indicates the routine was called in a manner not supported by the library. +.TP +.SM LDAP_CONTROL_NOT_FOUND +Indicates the control provided is unknown to the client library. +.TP +.SM LDAP_NO_RESULTS_RETURNED +Indicates no results returned. +.TP +.SM LDAP_MORE_RESULTS_TO_RETURN +Indicates more results could be returned. +.TP +.SM LDAP_CLIENT_LOOP +Indicates the library has detected a loop in its processing. +.TP +.SM LDAP_REFERRAL_LIMIT_EXCEEDED +Indicates the referral limit has been exceeded. + +.SH DEPRECATED +.so Deprecated + +.SH SEE ALSO +.BR ldap (3), +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_extended_operation.3 b/static/netbsd/man3/ldap_extended_operation.3 new file mode 100644 index 00000000..c55fe876 --- /dev/null +++ b/static/netbsd/man3/ldap_extended_operation.3 @@ -0,0 +1,75 @@ +.TH LDAP_EXTENDED_OPERATION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_extended_operation( +.RS +.ft B +LDAP *\fIld\fB, +const char *\fIrequestoid\fB, +const struct berval *\fIrequestdata\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_extended_operation_s( +.RS +.ft B +LDAP *\fIld\fB, +const char *\fIrequestoid\fB, +const struct berval *\fIrequestdata\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +char **\fIretoidp\fB, +struct berval **\fIretdatap\fB ); +.RE +.SH DESCRIPTION +The +.B ldap_extended_operation_s() +routine is used to synchronously perform an LDAP extended operation. +It takes \fIrequestoid\fP, which points to a dotted-decimal OID string +identifying the extended operation to perform. \fIrequestdata\fP is the +data required for the request, \fIsctrls\fP is an array of LDAPControl +structures to use with this extended operation, \fIcctrls\fP is an array +of LDAPControl structures that list the client controls to use with +this extended operation. +.LP +The output parameter \fIretoidp\fP points to a dotted-decimal OID +string returned by the LDAP server. The memory used by the string +should be freed with the +.BR ldap_memfree (3) +function. +The output parameter \fIretdatap\fP points to a pointer to a berval +structure that contains the returned data. If no data is returned +by the server, the pointer is set this to NULL. The memory used by +this structure should be freed with the +.BR ber_bvfree (3) +function. +.LP +The +.B ldap_extended_operation() +works just like +.BR ldap_extended_operation_s() , +but the operation is asynchronous. It provides the message id of +the request it initiated in the integer pointed to be \fImsgidp\fP. +The result of this operation can be obtained by calling +.BR ldap_result(3). +.SH SEE ALSO +.BR ber_bvfree (3), +.BR ldap_memfree (3), +.BR ldap_parse_extended_result (3), +.BR ldap_result (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_first_attribute.3 b/static/netbsd/man3/ldap_first_attribute.3 new file mode 100644 index 00000000..fd452ae7 --- /dev/null +++ b/static/netbsd/man3/ldap_first_attribute.3 @@ -0,0 +1,97 @@ +.TH LDAP_FIRST_ATTRIBUTE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +char *ldap_first_attribute( + LDAP *ld, LDAPMessage *entry, BerElement **berptr ) +.LP +.ft B +char *ldap_next_attribute( + LDAP *ld, LDAPMessage *entry, BerElement *ber ) +.LP +.ft B +int ldap_get_attribute_ber( + LDAP *ld, LDAPMessage *entry, BerElement *ber, + BerValue *attr, BerVarray *vals ) +.SH DESCRIPTION +The +.BR ldap_first_attribute() , +.B ldap_next_attribute() +and +.B ldap_get_attribute_ber() +routines are used +to step through the attributes in an LDAP entry. +.B ldap_first_attribute() +takes an \fIentry\fP as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3) +and returns a pointer to character string +containing the first attribute description in the entry. +.B ldap_next_attribute() +returns the next attribute description in the entry. +.LP +It also returns, in \fIberptr\fP, a pointer to a BerElement it has +allocated to keep track of its current position. This pointer should +be passed to subsequent calls to +.B ldap_next_attribute() +and is used +to effectively step through the entry's attributes. The caller is +solely responsible for freeing the BerElement pointed to by \fIberptr\fP +when it is no longer needed by calling +.BR ber_free (3). +When calling +.BR ber_free (3) +in this instance, be sure the second argument is 0. +.LP +The attribute names returned are suitable for inclusion in a call +to +.BR ldap_get_values (3) +to retrieve the attribute's values. +.LP +The +.B ldap_get_attribute_ber() +routine allows one to iterate over all attributes in-place, without +allocating memory to hold text for the attribute name or its values, +if requested. The use case is similar to +.B ldap_next_attribute() +except that the attribute name is returned into \fIattr\fP and, if +\fIvals\fP is non-NULL, the list of values is stored there. Both point +into the LDAP message and remain valid only while the entry is valid. +The caller is still responsible for freeing \fIvals\fP with +.BR ldap_memfree (3), +if used. +.SH ERRORS +If an error occurs, NULL is returned and the ld_errno field in the +\fIld\fP parameter is set to indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.SH NOTES +The +.B ldap_first_attribute() +and +.B ldap_next_attribute() +return dynamically allocated memory that must be freed by the caller via +.BR ldap_memfree (3). +For +.BR ldap_get_attribute_ber() , +only the actual \fIvals\fP pointer needs to be freed with +.BR ldap_memfree (3), +other data is accounted for as part of \fIber\fP. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_entry (3), +.BR ldap_get_values (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_first_entry.3 b/static/netbsd/man3/ldap_first_entry.3 new file mode 100644 index 00000000..d1c9cf8f --- /dev/null +++ b/static/netbsd/man3/ldap_first_entry.3 @@ -0,0 +1,80 @@ +.TH LDAP_FIRST_ENTRY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_count_entries( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) +.SH DESCRIPTION +.LP +These routines are used to parse results received from +.BR ldap_result (3) +or the synchronous LDAP search operation routines +.BR ldap_search_s (3) +and +.BR ldap_search_st (3). +.LP +The +.B ldap_first_entry() +routine is used to retrieve the first entry in a chain +of search results. It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) +or +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first entry in the result. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_entry() +to get the next entry, the result of which should be +supplied to the next call to +.BR ldap_next_entry() , +etc. +.B ldap_next_entry() +will return NULL when there are no more entries. The entries returned +from these calls are used in calls to the routines described in +.BR ldap_get_dn (3), +.BR ldap_first_attribute (3), +.BR ldap_get_values (3), +etc. +.LP +A count of the number of entries in the search result can be obtained +by calling +.BR ldap_count_entries() . +.SH ERRORS +If an error occurs in +.B ldap_first_entry() +or +.BR ldap_next_entry() , +NULL is returned and the ld_errno field in the \fIld\fP parameter +is set to indicate the error. If an error occurs in +.BR ldap_count_entries() , +-1 is returned, and +.B ld_errno +is set appropriately. See +.BR ldap_error (3) +for a description of possible error codes. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_first_attribute (3), +.BR ldap_get_values (3), +.BR ldap_get_dn (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_first_message.3 b/static/netbsd/man3/ldap_first_message.3 new file mode 100644 index 00000000..e14490e0 --- /dev/null +++ b/static/netbsd/man3/ldap_first_message.3 @@ -0,0 +1,82 @@ +.TH LDAP_FIRST_MESSAGE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_count_messages( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) +.SH DESCRIPTION +.LP +These routines are used to step through the messages in a result chain +received from +.BR ldap_result (3) . +For search operations, the result chain can contain referral, entry +and result messages. The +.BR ldap_msgtype (3) +function can be used to distinguish between the different message types. +.LP +The +.B ldap_first_message() +routine is used to retrieve the first message in a result chain. +It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) , +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first message in the result chain. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_message() +to get the next message, the result of which should be +supplied to the next call to +.BR ldap_next_message() , +etc. +.B ldap_next_message() +will return NULL when there are no more messages. +.LP +These functions are useful when using routines like +.BR ldap_parse_result (3) +that only operate on the first result in the chain. +.LP +A count of the number of messages in the result chain can be obtained +by calling +.BR ldap_count_messages() . +It can also be used to count the number of remaining messages in a chain +if called with a message, entry or reference returned by +.B ldap_first_message() , +.B ldap_next_message() , +.BR ldap_first_entry (3) , +.BR ldap_next_entry (3) , +.BR ldap_first_reference (3) , +.BR ldap_next_reference (3) . +.SH ERRORS +If an error occurs in +.B ldap_first_message() +or +.BR ldap_next_message() , +NULL is returned. If an error occurs in +.BR ldap_count_messages() , +-1 is returned. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_search (3), +.BR ldap_result (3), +.BR ldap_parse_result (3), +.BR ldap_first_entry (3), +.BR ldap_first_reference (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_first_reference.3 b/static/netbsd/man3/ldap_first_reference.3 new file mode 100644 index 00000000..ee27e7d2 --- /dev/null +++ b/static/netbsd/man3/ldap_first_reference.3 @@ -0,0 +1,71 @@ +.TH LDAP_FIRST_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_count_references( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) +.LP +.ft B +LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) +.SH DESCRIPTION +.LP +These routines are used to step through the continuation references in a +result chain received from +.BR ldap_result (3) +or the synchronous LDAP search operation routines. +.LP +The +.B ldap_first_reference() +routine is used to retrieve the first reference message in a +result chain. It takes the \fIresult\fP as returned by a call to +.BR ldap_result (3) , +.BR ldap_search_s (3) +or +.BR ldap_search_st (3) +and returns a pointer to the first reference message in the +result chain. +.LP +This pointer should be supplied on a subsequent call to +.B ldap_next_reference() +to get the next reference message, the result of which should be +supplied to the next call to +.BR ldap_next_reference() , +etc. +.B ldap_next_reference() +will return NULL when there are no more reference messages. +The reference messages returned from these calls are used by +.BR ldap_parse_reference (3) +to extract referrals and controls. +.LP +A count of the number of reference messages in the search result can be +obtained by calling +.BR ldap_count_references() . +It can also be used to count the number of reference messages remaining +in a result chain. +.SH ERRORS +If an error occurs in +.B ldap_first_reference() +or +.BR ldap_next_reference() , +NULL is returned. If an error occurs in +.BR ldap_count_references() , +-1 is returned. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_parse_reference (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_get_dn.3 b/static/netbsd/man3/ldap_get_dn.3 new file mode 100644 index 00000000..549a84ec --- /dev/null +++ b/static/netbsd/man3/ldap_get_dn.3 @@ -0,0 +1,246 @@ +.TH LDAP_GET_DN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) +.LP +.ft B +int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) +.LP +.ft B +void ldap_dnfree( LDAPDN dn ) +.LP +.ft B +int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) +.LP +.ft B +char **ldap_explode_dn( const char *dn, int notypes ) +.LP +.ft B +char **ldap_explode_rdn( const char *rdn, int notypes ) +.LP +.ft B +char *ldap_dn2ufn( const char * dn ) +.LP +.ft B +char *ldap_dn2dcedn( const char * dn ) +.LP +.ft B +char *ldap_dcedn2dn( const char * dn ) +.LP +.ft B +char *ldap_dn2ad_canonical( const char * dn ) +.SH DESCRIPTION +These routines allow LDAP entry names (Distinguished Names, or DNs) +to be obtained, parsed, converted to a user-friendly form, and tested. +A DN has the form described in +RFC 4414 "Lightweight Directory Access Protocol (LDAP): +String Representation of Distinguished Names". +.LP +The +.B ldap_get_dn() +routine takes an \fIentry\fP as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3) +and returns a copy of +the entry's DN. Space for the DN will be obtained dynamically +and should be freed by the caller using +.BR ldap_memfree (3). +.LP +.B ldap_str2dn() +parses a string representation of a distinguished name contained in +.B str +into its components, +which are stored in +.B dn +as +.B ldap_ava +structures, arranged in +.B LDAPAVA, +.B LDAPRDN, +and +.B LDAPDN +terms. Space for +.B dn +will be obtained dynamically and should be freed by the caller using +.BR ldap_dnfree (3). +The +.B LDAPDN +is defined as: +.nf +.ft B + +typedef struct ldap_ava { + struct berval la_attr; + struct berval la_value; + unsigned la_flags; +} LDAPAVA; + +typedef LDAPAVA** LDAPRDN; +typedef LDAPRDN* LDAPDN; + +.ft +.fi +The attribute types and the attribute values are not normalized. +The +.B la_flags +can be either +.B LDAP_AVA_STRING +or +.B LDAP_AVA_BINARY, +the latter meaning that the value is BER/DER encoded and thus must +be represented as, quoting from RFC 4514, " ... an +octothorpe character ('#' ASCII 35) followed by the hexadecimal +representation of each of the bytes of the BER encoding of the X.500 +AttributeValue." +The +.B flags +parameter to +.B ldap_str2dn() +can be +.LP +.nf + LDAP_DN_FORMAT_LDAPV3 + LDAP_DN_FORMAT_LDAPV2 + LDAP_DN_FORMAT_DCE + +.fi +which defines what DN syntax is expected (according to RFC 4514, +RFC 1779 and DCE, respectively). +The format can be \fIOR\fPed to the flags +.LP +.nf + LDAP_DN_P_NO_SPACES + LDAP_DN_P_NO_SPACE_AFTER_RDN + ... + LDAP_DN_PEDANTIC + +.fi +The latter is a shortcut for all the previous limitations. +.LP +.B LDAP_DN_P_NO_SPACES +does not allow extra spaces in the dn; the default is to silently +eliminate spaces around AVA separators ('='), RDN component separators +('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators +(',' LDAPv3/LDAPv2 or '/' for DCE). +.LP +.B LDAP_DN_P_NO_SPACE_AFTER_RDN +does not allow a single space after RDN separators. +.LP +.B ldap_dn2str() +performs the inverse operation, yielding in +.B str +a string representation of +.B dn. +It allows the same values for +.B flags +as +.B ldap_str2dn(), +plus +.LP +.nf + LDAP_DN_FORMAT_UFN + LDAP_DN_FORMAT_AD_CANONICAL + +.fi +for user-friendly naming (RFC 1781) and AD canonical. +.LP +The following routines are viewed as deprecated in favor of +.B ldap_str2dn() +and +.BR ldap_dn2str(). +They are provided to support legacy applications. +.LP +The +.B ldap_explode_dn() +routine takes a DN as returned by +.B ldap_get_dn() +and breaks it up into its component parts. Each part is known as a +Relative Distinguished Name, or RDN. +.B ldap_explode_dn() +returns a +NULL-terminated array, each component of which contains an RDN from the +DN. The \fInotypes\fP parameter is used to request that only the RDN +values be returned, not their types. For example, the DN "cn=Bob, +c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", +"US", NULL }, depending on whether notypes was 0 or 1, respectively. +Assertion values in RDN strings may included escaped characters. +The result can be freed by calling +.BR ldap_value_free (3). +.LP +Similarly, the +.B ldap_explode_rdn() +routine takes an RDN as returned by +.B ldap_explode_dn(dn,0) +and breaks it up into its "type=value" component parts (or just "value", +if the \fInotypes\fP parameter is set). Note the value is not +unescaped. The result can be freed by calling +.BR ldap_value_free (3). +.LP +.B ldap_dn2ufn() +is used to turn a DN as returned by +.BR ldap_get_dn (3) +into a more user-friendly form, stripping off all type names. See +"Using the Directory to Achieve User Friendly Naming" (RFC 1781) +for more details on the UFN format. Due to the ambiguous nature +of the format, it is generally only used for display purposes. +The space for the UFN returned is obtained dynamically and the user +is responsible for freeing it via a call to +.BR ldap_memfree (3). +.LP +.B ldap_dn2dcedn() +is used to turn a DN as returned by +.BR ldap_get_dn (3) +into a DCE-style DN, e.g. a string with most-significant to least +significant rdns separated by slashes ('/'); rdn components +are separated by commas (','). +Only printable chars (e.g. LDAPv2 printable string) are allowed, +at least in this implementation. +.B ldap_dcedn2dn() +performs the opposite operation. +.B ldap_dn2ad_canonical() +turns a DN into a AD canonical name, which is basically a DCE dn +with attribute types omitted. +The trailing domain, if present, is turned in a DNS-like domain. +The space for the returned value is obtained dynamically and the user +is responsible for freeing it via a call to +.BR ldap_memfree (3). +.SH ERRORS +If an error occurs in +.BR ldap_get_dn() , +NULL is returned and the +.B ld_errno +field in the \fIld\fP parameter is set to indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.BR ldap_explode_dn() , +.BR ldap_explode_rdn() , +.B ldap_dn2ufn(), +.B ldap_dn2dcedn(), +.B ldap_dcedn2dn(), +and +.B ldap_dn2ad_canonical() +will return NULL with +.BR errno (3) +set appropriately in case of trouble. +.SH NOTES +These routines dynamically allocate memory that the caller must free. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.BR ldap_first_entry (3), +.BR ldap_memfree (3), +.BR ldap_value_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_get_option.3 b/static/netbsd/man3/ldap_get_option.3 new file mode 100644 index 00000000..2973bfde --- /dev/null +++ b/static/netbsd/man3/ldap_get_option.3 @@ -0,0 +1,933 @@ +.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_option, ldap_set_option \- LDAP option handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include +.LP +.BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" +.LP +.BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" +.SH DESCRIPTION +.LP +These routines provide access to options stored either in a LDAP handle +or as global options, where applicable. +They make use of a neutral interface, where the type of the value +either retrieved by +.BR ldap_get_option (3) +or set by +.BR ldap_set_option (3) +is cast to +.BR "void *" . +The actual type is determined based on the value of the +.B option +argument. +Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles +inherit their default settings from the global options in effect at the time +the handle is created. +.TP +.B LDAP_OPT_API_FEATURE_INFO +Fills-in a +.BR "LDAPAPIFeatureInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIFeatureInfo *" , +pointing to an already allocated struct. +The +.B ldapaif_info_version +field of the struct must be initialized to +.B LDAP_FEATURE_INFO_VERSION +before making the call. The +.B ldapaif_name +field must be set to the name of a feature to query. +This is a read-only option. +.TP +.B LDAP_OPT_API_INFO +Fills-in a +.BR "LDAPAPIInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIInfo *" , +pointing to an already allocated struct. The +.B ldapai_info_version +field of the struct must be initialized to +.B LDAP_API_INFO_VERSION +before making the call. +If the version passed in does not match the current library +version, the expected version number will be stored in the +struct and the call will fail. +The caller is responsible for freeing the elements of the +.B ldapai_extensions +array and the array itself using +.BR ldap_memfree (3). +The caller must also free the +.BR ldapi_vendor_name . +This is a read-only option. +.TP +.B LDAP_OPT_CLIENT_CONTROLS +Sets/gets the client-side controls to be used for all operations. +This is now deprecated as modern LDAP C API provides replacements +for all main operations which accepts client-side controls as +explicit arguments; see for example +.BR ldap_search_ext (3), +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3) +and so on. +.BR outvalue +must be +.BR "LDAPControl ***" , +and the caller is responsible of freeing the returned controls, if any, +by calling +.BR ldap_controls_free (3), +while +.BR invalue +must be +.BR "LDAPControl *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_CONNECT_ASYNC +Sets/gets the status of the asynchronous connect flag. +.BR invalue +should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON ; +.BR outvalue +must be +.BR "int *" . +When set, the library will call +.BR connect (2) +and return, without waiting for response. +This leaves the handle in a connecting state. +Subsequent calls to library routines will poll for completion +of the connect before performing further operations. +As a consequence, library calls that need to establish a connection +with a DSA do not block even for the network timeout +(option +.BR LDAP_OPT_NETWORK_TIMEOUT ). +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_CONNECT_CB +This option allows to set a connect callback. +.B invalue +must be a +.BR "const struct ldap_conncb *" . +Callbacks are executed in last in-first served order. +Handle-specific callbacks are executed first, followed by global ones. +Right before freeing the callback structure, the +.B lc_del +callback handler is passed a +.B NULL +.BR Sockbuf . +Calling +.BR ldap_get_option (3) +for this option removes the callback whose pointer matches +.BR outvalue . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEBUG_LEVEL +Sets/gets the debug level of the client library. +.BR invalue +must be a +.BR "const int *" ; +.BR outvalue +must be a +.BR "int *" . +Valid debug levels are +.BR LDAP_DEBUG_ANY , +.BR LDAP_DEBUG_ARGS , +.BR LDAP_DEBUG_BER , +.BR LDAP_DEBUG_CONNS , +.BR LDAP_DEBUG_NONE , +.BR LDAP_DEBUG_PACKETS , +.BR LDAP_DEBUG_PARSE , +and +.BR LDAP_DEBUG_TRACE . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEFBASE +Sets/gets a string containing the DN to be used as default base +for search operations. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEREF +Sets/gets the value that defines when alias dereferencing must occur. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +They cannot be NULL. +The value of +.BR *invalue +should be one of +.BR LDAP_DEREF_NEVER +(the default), +.BR LDAP_DEREF_SEARCHING , +.BR LDAP_DEREF_FINDING , +or +.BR LDAP_DEREF_ALWAYS . +Note that this has ever been the only means to determine alias dereferencing +within search operations. +.TP +.B LDAP_OPT_DESC +Returns the file descriptor associated to the socket buffer +of the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "int *" . +This is a read-only, handle-specific option. +.TP +.B LDAP_OPT_DIAGNOSTIC_MESSAGE +Sets/gets a string containing the error string associated to the LDAP handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_STRING . +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_HOST_NAME +Sets/gets a space-separated list of hosts to be contacted by the library +when trying to establish a connection. +This is now deprecated in favor of +.BR LDAP_OPT_URI . +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the resulting string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_MATCHED_DN +Sets/gets a string containing the matched DN associated to the LDAP handle. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_NETWORK_TIMEOUT +Sets/gets the network timeout value after which +.BR poll (2)/ select (2) +following a +.BR connect (2) +returns in case of no activity. +.B outvalue +must be a +.BR "struct timeval **" +(the caller has to free +.BR *outvalue +using +.BR ldap_memfree (3)), +and +.B invalue +must be a +.BR "const struct timeval *" . +They cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_PROTOCOL_VERSION +Sets/gets the protocol version. +.BR outvalue +and +.BR invalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_REFERRAL_URLS +Sets/gets an array containing the referral URIs associated to the LDAP handle. +.BR outvalue +must be a +.BR "char ***" , +and the caller is responsible of freeing the returned string by calling +.BR ldap_memvfree (3), +while +.BR invalue +must be a NULL-terminated +.BR "char *const *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_REFERRALS +Determines whether the library should implicitly chase referrals or not. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.\".TP +.\".B LDAP_OPT_REFHOPLIMIT +.\"This option is OpenLDAP specific. +.\"It is not currently implemented. +.TP +.B LDAP_OPT_RESTART +Determines whether the library should implicitly restart connections (FIXME). +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_RESULT_CODE +Sets/gets the LDAP result code associated to the handle. +This option was formerly known as +.BR LDAP_OPT_ERROR_NUMBER . +.BR invalue +must be a +.BR "const int *" . +.BR outvalue +must be a +.BR "int *" . +.TP +.B LDAP_OPT_SERVER_CONTROLS +Sets/gets the server-side controls to be used for all operations. +This is now deprecated as modern LDAP C API provides replacements +for all main operations which accepts server-side controls as +explicit arguments; see for example +.BR ldap_search_ext (3), +.BR ldap_add_ext (3), +.BR ldap_modify_ext (3) +and so on. +.BR outvalue +must be +.BR "LDAPControl ***" , +and the caller is responsible of freeing the returned controls, if any, +by calling +.BR ldap_controls_free (3), +while +.BR invalue +must be +.BR "LDAPControl *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_SESSION_REFCNT +Returns the reference count associated with the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "int *" . +This is a read-only, handle-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_SIZELIMIT +Sets/gets the value that defines the maximum number of entries +to be returned by a search operation. +.BR invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" ; +They cannot be NULL. +.TP +.B LDAP_OPT_SOCKBUF +Returns a pointer to the socket buffer of the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "Sockbuf **" . +This is a read-only, handle-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_SOCKET_BIND_ADDRESSES +Sets/gets a space-separated list of IP Addresses used as binding interface +to remote server when trying to establish a connection. Only one valid IPv4 +address and/or one valid IPv6 address are allowed in the list. +.BR outvalue +must be a +.BR "char **", +and the caller is responsible of freeing the returned string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library duplicates the corresponding string. +.TP +.B LDAP_OPT_TIMELIMIT +Sets/gets the value that defines the time limit after which +a search operation should be terminated by the server. +.BR invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" , +and they cannot be NULL. +.TP +.B LDAP_OPT_TIMEOUT +Sets/gets a timeout value for the synchronous API calls. +.B outvalue +must be a +.BR "struct timeval **" +(the caller has to free +.BR *outvalue +using +.BR ldap_memfree (3)), +and +.B invalue +must be a +.BR "struct timeval *" , +and they cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_URI +Sets/gets a comma- or space-separated list of URIs to be contacted by the library +when trying to establish a connection. +.BR outvalue +must be a +.BR "char **" , +and the caller is responsible of freeing the resulting string by calling +.BR ldap_memfree (3), +while +.BR invalue +must be a +.BR "const char *" ; +the library parses the string into a list of +.BR LDAPURLDesc +structures, so the invocation of +.BR ldap_set_option (3) +may fail if URL parsing fails. +URIs may only contain the +.BR schema , +the +.BR host , +and the +.BR port +fields. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_KEEPCONN +Instructs +.BR ldap_result (3) +to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the connection should be closed by the caller. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_TCP_USER_TIMEOUT +Allows to configure TCP_USER_TIMEOUT in milliseconds on the connection, overriding the operating system setting. +This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher. +.B invalue +must be a +.BR "const unsigned int *" ; +.BR outvalue +must be an +.BR "unsigned int *" . + +.SH SASL OPTIONS +The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed. +.TP +.B LDAP_OPT_X_SASL_AUTHCID +Gets the SASL authentication identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_AUTHZID +Gets the SASL authorization identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MAXBUFSIZE +Gets/sets SASL maximum buffer size; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_MECH +Gets the SASL mechanism; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MECHLIST +Gets the list of the available mechanisms, +in form of a NULL-terminated array of strings; +.BR outvalue +must be +.BR "char ***" . +The caller must not free or otherwise muck with it. This option can be used globally. +.TP +.B LDAP_OPT_X_SASL_NOCANON +Sets/gets the NOCANON flag. +When unset, the hostname is canonicalized. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_SASL_REALM +Gets the SASL realm; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_SECPROPS +Sets the SASL secprops; +.BR invalue +must be a +.BR "char *" , +containing a comma-separated list of properties. +Legal values are: +.BR none , +.BR nodict , +.BR noplain , +.BR noactive , +.BR passcred , +.BR forwardsec , +.BR noanonymous , +.BR minssf= , +.BR maxssf= , +.BR maxbufsize= . +.TP +.B LDAP_OPT_X_SASL_SSF +Gets the SASL SSF; +.BR outvalue +must be a +.BR "ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_EXTERNAL +Sets the SASL SSF value related to an authentication +performed using an EXTERNAL mechanism; +.BR invalue +must be a +.BR "const ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_MAX +Gets/sets SASL maximum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_SSF_MIN +Gets/sets SASL minimum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_USERNAME +Gets the SASL username; +.BR outvalue +must be a +.BR "char **" . +Its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_CBINDING +Sets/gets the channel-binding type to use in SASL, +one of +.BR LDAP_OPT_X_SASL_CBINDING_NONE +(the default), +.BR LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE +the "tls-unique" type from RFC 5929. +.BR LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT +the "tls-server-end-point" from RFC 5929, compatible with Windows. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.SH TCP OPTIONS +The TCP options are OpenLDAP specific. +Mainly intended for use with Linux, they may not be portable. +.TP +.B LDAP_OPT_X_KEEPALIVE_IDLE +Sets/gets the number of seconds a connection needs to remain idle +before TCP starts sending keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_PROBES +Sets/gets the maximum number of keepalive probes TCP should send +before dropping the connection. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_INTERVAL +Sets/gets the interval in seconds between individual keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.SH TLS OPTIONS +The TLS options are OpenLDAP specific. +.\".TP +.\".B LDAP_OPT_X_TLS +.\"Sets/gets the TLS mode. +.TP +.B LDAP_OPT_X_TLS_CACERTDIR +Sets/gets the path of the directories containing CA certificates. +Multiple directories may be specified, separated by a semi-colon. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CACERTFILE +Sets/gets the full-path of the CA certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CERTFILE +Sets/gets the full-path of the certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CIPHER +Gets the cipher being used on an established TLS session. +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CIPHER_SUITE +Sets/gets the allowed cipher suite. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CONNECT_ARG +Sets/gets the connection callback argument. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +.TP +.B LDAP_OPT_X_TLS_CONNECT_CB +Sets/gets the connection callback handle. +.BR invalue +must be +.BR "const LDAP_TLS_CONNECT_CB *" ; +.BR outvalue +must be +.BR "LDAP_TLS_CONNECT_CB **" . +.TP +.B LDAP_OPT_X_TLS_CRLCHECK +Sets/gets the CRL evaluation strategy, one of +.BR LDAP_OPT_X_TLS_CRL_NONE , +.BR LDAP_OPT_X_TLS_CRL_PEER , +or +.BR LDAP_OPT_X_TLS_CRL_ALL . +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +Requires OpenSSL. +.TP +.B LDAP_OPT_X_TLS_CRLFILE +Sets/gets the full-path of the CRL file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +This option is only valid for GnuTLS. +.TP +.B LDAP_OPT_X_TLS_CTX +Sets/gets the TLS library context. New TLS sessions will inherit their +default settings from this library context. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL_CTX*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option or attempt to +manipulate this structure. +.TP +.B LDAP_OPT_X_TLS_DHFILE +Gets/sets the full-path of the file containing the parameters +for Diffie-Hellman ephemeral key exchange. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_ECNAME +Gets/sets the name of the curve(s) used for +elliptic curve key exchanges. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS. In GnuTLS a curve may be selected +in the cipher suite specification. +.TP +.B LDAP_OPT_X_TLS_KEYFILE +Sets/gets the full-path of the certificate key file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_NEWCTX +Instructs the library to create a new TLS library context. +.BR invalue +must be +.BR "const int *" . +A non-zero value pointed to by +.BR invalue +tells the library to create a context for a server. +.TP +.B LDAP_OPT_X_TLS_PEERCERT +Gets the peer's certificate in DER format from an established TLS session. +.BR outvalue +must be +.BR "struct berval *" , +and the data it returns needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MAX +Sets/gets the maximum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MIN +Sets/gets the minimum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_TLS_RANDOM_FILE +Sets/gets the random file when +.B /dev/random +and +.B /dev/urandom +are not available. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS older than version 2.2. +.TP +.B LDAP_OPT_X_TLS_REQUIRE_CERT +Sets/gets the peer certificate checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_REQUIRE_SAN +Sets/gets the peer certificate subjectAlternativeName checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_SSL_CTX +Gets the TLS session context associated with this handle. +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option. +.TP +.B LDAP_OPT_X_TLS_VERSION +Gets the TLS version being used on an established TLS session. +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_PEERKEY_HASH +Sets the (public) key that the application expects the peer to be using. +.B invalue +must be +.BR "const char *" +containing the base64 encoding of the expected peer's key or in the format +.B ":" +where as a TLS session is established, the library will hash the peer's key +with the provided hash algorithm and compare it with value provided and will +only allow the session to continue if they match. This happens regardless of +certificate checking strategy. The list of supported +.B hashalg +values depends on the crypto library used, check its documentation to get +a list. +.SH ERRORS +On success, the functions return +.BR LDAP_OPT_SUCCESS , +while they may return +.B LDAP_OPT_ERROR +to indicate a generic option handling error. +Occasionally, more specific errors can be returned, like +.B LDAP_NO_MEMORY +to indicate a failure in memory allocation. +.SH NOTES +The LDAP libraries with the +.B LDAP_OPT_REFERRALS +option set to +.B LDAP_OPT_ON +(default value) automatically follow referrals using an anonymous bind. +Application developers are encouraged to either implement consistent +referral chasing features, or explicitly disable referral chasing +by setting that option to +.BR LDAP_OPT_OFF . +.P +The protocol version used by the library defaults to LDAPv2 (now historic), +which corresponds to the +.B LDAP_VERSION2 +macro. +Application developers are encouraged to explicitly set +.B LDAP_OPT_PROTOCOL_VERSION +to LDAPv3, using the +.B LDAP_VERSION3 +macro, or to allow users to select the protocol version. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.B RFC 4422 +(http://www.rfc-editor.org), +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_get_values.3 b/static/netbsd/man3/ldap_get_values.3 new file mode 100644 index 00000000..0d48abdb --- /dev/null +++ b/static/netbsd/man3/ldap_get_values.3 @@ -0,0 +1,102 @@ +.TH LDAP_GET_VALUES 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include + +.LP +.ft B +char **ldap_get_values(ld, entry, attr) +.ft +LDAP *ld; +LDAPMessage *entry; +char *attr; +.LP +.ft B +struct berval **ldap_get_values_len(ld, entry, attr) +.ft +LDAP *ld; +LDAPMessage *entry; +char *attr; +.LP +.ft B +int ldap_count_values(vals) +.ft +char **vals; +.LP +.ft B +int ldap_count_values_len(vals) +.ft +struct berval **vals; +.LP +.ft B +void ldap_value_free(vals) +.ft +char **vals; +.LP +.ft B +void ldap_value_free_len(vals) +.ft +struct berval **vals; +.SH DESCRIPTION +These routines are used to retrieve and manipulate attribute values +from an LDAP entry as returned by +.BR ldap_first_entry (3) +or +.BR ldap_next_entry (3). +.B ldap_get_values() +takes the \fIentry\fP and the attribute \fIattr\fP +whose values are desired and returns a NULL-terminated array of the +attribute's values. \fIattr\fP may be an attribute type as returned +from +.BR ldap_first_attribute (3) +or +.BR ldap_next_attribute (3), +or if the attribute type is known it can simply be given. +.LP +The number of values in the array can be counted by calling +.BR ldap_count_values() . +The array of values returned can be freed by calling +.BR ldap_value_free() . +.LP +If the attribute values are binary in nature, and thus not suitable +to be returned as an array of char *'s, the +.B ldap_get_values_len() +routine can be used instead. It takes the same parameters as +.BR ldap_get_values() , +but returns a NULL-terminated array of pointers +to berval structures, each containing the length of and a pointer +to a value. +.LP +The number of values in the array can be counted by calling +.BR ldap_count_values_len() . +The array of values returned can be freed by calling +.BR ldap_value_free_len() . +.SH ERRORS +If an error occurs in +.B ldap_get_values() +or +.BR ldap_get_values_len() , +NULL is returned and the +.B ld_errno +field in the \fIld\fP parameter is set to +indicate the error. See +.BR ldap_error (3) +for a description of possible error codes. +.SH NOTES +These routines dynamically allocate memory which the caller must free +using the supplied routines. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_entry (3), +.BR ldap_first_attribute (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_memory.3 b/static/netbsd/man3/ldap_memory.3 new file mode 100644 index 00000000..3c29a3f5 --- /dev/null +++ b/static/netbsd/man3/ldap_memory.3 @@ -0,0 +1,50 @@ +.TH LDAP_MEMORY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include +.LP +.BI "void ldap_memfree(void *" p ");" +.LP +.BI "void ldap_memvfree(void **" v ");" +.LP +.BI "void *ldap_memalloc(ber_len_t " s ");" +.LP +.BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" +.LP +.BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" +.LP +.BI "char *ldap_strdup(LDAP_CONST char *" p ");" +.SH DESCRIPTION +These routines are used to allocate/deallocate memory used/returned +by the LDAP library. +.BR ldap_memalloc (), +.BR ldap_memcalloc (), +.BR ldap_memrealloc (), +and +.BR ldap_memfree () +are used exactly like the standard +.BR malloc (3), +.BR calloc (3), +.BR realloc (3), +and +.BR free (3) +routines, respectively. +The +.BR ldap_memvfree () +routine is used to free a dynamically allocated array of pointers to +arbitrary dynamically allocated objects. +The +.BR ldap_strdup () +routine is used exactly like the standard +.BR strdup (3) +routine. +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_modify.3 b/static/netbsd/man3/ldap_modify.3 new file mode 100644 index 00000000..9911cf98 --- /dev/null +++ b/static/netbsd/man3/ldap_modify.3 @@ -0,0 +1,134 @@ +.TH LDAP_MODIFY 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_modify_ext( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +LDAPMod *\fImods[]\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB, +int *\fImsgidp\fB ); +.RE +.LP +.nf +.ft B +int ldap_modify_ext_s( +.RS +.ft B +LDAP *\fIld\fB, +char *\fIdn\fB, +LDAPMod *\fImods[]\fB, +LDAPControl **\fIsctrls\fB, +LDAPControl **\fIcctrls\fB ); +.RE +.LP +.nf +.ft B +void ldap_mods_free( +.RS +.ft B +LDAPMod **\fImods\fB, +int \fIfreemods\fB ); +.RE +.SH DESCRIPTION +The routine +.B ldap_modify_ext_s() +is used to perform an LDAP modify operation. +\fIdn\fP is the DN of the entry to modify, and \fImods\fP is a +null-terminated array of modifications to make to the entry. Each element +of the \fImods\fP array is a pointer to an LDAPMod structure, which is +defined below. +.LP +.nf + typedef struct ldapmod { + int mod_op; + char *mod_type; + union { + char **modv_strvals; + struct berval **modv_bvals; + } mod_vals; + } LDAPMod; + #define mod_values mod_vals.modv_strvals + #define mod_bvalues mod_vals.modv_bvals +.ft +.fi +.LP +The \fImod_op\fP field is used to specify the type of modification to +perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or +LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields +specify the attribute type to modify and a null-terminated array of +values to add, delete, or replace respectively. +.LP +If you need to specify a non-string value (e.g., to add a +photo or audio attribute value), you should set \fImod_op\fP to the +logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) +and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP +should be used instead of \fImod_values\fP, and it should point to +a null-terminated array of struct bervals, as defined in . +.LP +For LDAP_MOD_ADD modifications, the given values are added to the +entry, creating the attribute if necessary. For LDAP_MOD_DELETE +modifications, the given values are deleted from the entry, removing +the attribute if no values remain. If the entire attribute is to be deleted, +the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE +modifications, the attribute will have the listed values after the +modification, having been created if necessary. All modifications are +performed in the order in which they are listed. +.LP +.B ldap_mods_free() +can be used to free each element of a NULL-terminated +array of mod structures. If \fIfreemods\fP is non-zero, the +\fImods\fP pointer itself is freed as well. +.LP +.B ldap_modify_ext_s() +returns a code indicating success or, in the case of failure, +indicating the nature of the failure. See +.BR ldap_error (3) +for details +.LP +The +.B ldap_modify_ext() +operation works the same way as +.BR ldap_modify_ext_s() , +except that it is asynchronous. The integer that \fImsgidp\fP points +to is set to the message id of the modify request. The result of +the operation can be obtained by calling +.BR ldap_result (3). +.LP +Both +.B ldap_modify_ext() +and +.B ldap_modify_ext_s() +allows server and client controls to be passed in +via the sctrls and cctrls parameters, respectively. +.SH DEPRECATED INTERFACES +The +.B ldap_modify() +and +.B ldap_modify_s() +routines are deprecated in favor of the +.B ldap_modify_ext() +and +.B ldap_modify_ext_s() +routines, respectively. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.SH ACKNOWLEDGEMENTS +.so ../Project + diff --git a/static/netbsd/man3/ldap_modrdn.3 b/static/netbsd/man3/ldap_modrdn.3 new file mode 100644 index 00000000..1dc0cd82 --- /dev/null +++ b/static/netbsd/man3/ldap_modrdn.3 @@ -0,0 +1,81 @@ +.TH LDAP_MODRDN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_modrdn(ld, dn, newrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +.LP +.ft B +.LP +.ft B +int ldap_modrdn_s(ld, dn, newrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +.LP +.ft B +int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +int deleteoldrdn; +.LP +.ft B +int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) +.ft +LDAP \(**ld; +char \(**dn, \(**newrdn; +int deleteoldrdn; +.SH DESCRIPTION +The +.B ldap_modrdn() +and +.B ldap_modrdn_s() +routines perform an LDAP modify +RDN operation. They both take \fIdn\fP, the DN of the entry whose +RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. +The old RDN of the entry is never kept as an attribute of the entry. +.B ldap_modrdn() +is asynchronous, returning the message id of the operation +it initiates. +.B ldap_modrdn_s() +is synchronous, returning the LDAP error +code indicating the success or failure of the operation. Use of +these routines is deprecated. Use the versions described below +instead. +.LP +The +.B ldap_modrdn2() +and +.B ldap_modrdn2_s() +routines also perform an LDAP +modify RDN operation, taking the same parameters as above. In addition, +they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean +value to indicate whether the old RDN values should be deleted from +the entry or not. +.SH ERRORS +The synchronous (_s) versions of these routines return an LDAP error +code, either LDAP_SUCCESS or an error if there was trouble. +The asynchronous versions return \-1 in case +of trouble, setting the +.B ld_errno +field of \fIld\fP. See +.BR ldap_error (3) +for more details. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_open.3 b/static/netbsd/man3/ldap_open.3 new file mode 100644 index 00000000..822d4570 --- /dev/null +++ b/static/netbsd/man3/ldap_open.3 @@ -0,0 +1,236 @@ +.TH LDAP_OPEN 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +LDAP *ldap_open(host, port) +.ft +char *host; +int port; +.LP +.ft B +LDAP *ldap_init(host, port) +.ft +char *host; +int port; +.LP +.ft B +int ldap_initialize(ldp, uri) +.ft +LDAP **ldp; +char *uri; +.LP +.ft B +int ldap_connect(ldp) +.ft +LDAP *ldp; +.LP +.ft B +int ldap_set_urllist_proc(ld, proc, params) +.ft +LDAP *ld; +LDAP_URLLIST_PROC *proc; +void *params; +.LP +.ft B +int (LDAP_URLLIST_PROC)(ld, urllist, url, params); +.ft +LDAP *ld; +LDAPURLDesc **urllist; +LDAPURLDesc **url; +void *params; +.LP +.ft B +#include +.LP +.ft B +int ldap_init_fd(fd, proto, uri, ldp) +.ft +ber_socket_t fd; +int proto; +char *uri; +LDAP **ldp; +.SH DESCRIPTION +.LP +.B ldap_open() +opens a connection to an LDAP server and allocates an LDAP +structure which is used to identify +the connection and to maintain per-connection information. +.B ldap_init() +allocates an LDAP structure but does not open an initial connection. +.B ldap_initialize() +allocates an LDAP structure but does not open an initial connection. +.B ldap_init_fd() +allocates an LDAP structure using an existing connection on the +provided socket. +One +of these routines must be called before any operations are attempted. +.LP +.B ldap_open() +takes \fIhost\fP, the hostname on which the LDAP server is +running, and \fIport\fP, the port number to which to connect. If the default +IANA-assigned port of 389 is desired, LDAP_PORT should be specified for +\fIport\fP. The \fIhost\fP parameter may contain a blank-separated list +of hosts to try to connect to, and each host may optionally by of the form +\fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP +parameter to +.BR ldap_open() . +Upon successfully making a connection to an +LDAP server, +.B ldap_open() +returns a pointer to an opaque LDAP structure, which should be passed +to subsequent calls to +.BR ldap_bind() , +.BR ldap_search() , +etc. Certain fields in the LDAP structure can be set to indicate size limit, +time limit, and how aliases are handled during operations; read and write access +to those fields must occur by calling +.BR ldap_get_option (3) +and +.BR ldap_set_option (3) +respectively, whenever possible. +.LP +.B +ldap_init() +acts just like +.BR ldap_open() , +but does not open a connection +to the LDAP server. The actual connection open will occur when the +first operation is attempted. +.LP +.B ldap_initialize() +acts like +.BR ldap_init() , +but it returns an integer indicating either success or the failure reason, +and it allows to specify details for the connection in the schema portion +of the URI. +The +.I uri +parameter may be a comma- or whitespace-separated list of URIs +containing only the +.IR schema , +the +.IR host , +and the +.I port +fields. +Apart from +.BR ldap , +other (non-standard) recognized values of the +.I schema +field are +.B ldaps +(LDAP over TLS), +.B ldapi +(LDAP over IPC), +and +.B cldap +(connectionless LDAP). +If other fields are present, the behavior is undefined. +.LP +At this time, +.B ldap_open() +and +.B ldap_init() +are deprecated in favor of +.BR ldap_initialize() , +essentially because the latter allows to specify a schema in the URI +and it explicitly returns an error code. +.LP +.B ldap_connect() +causes a handle created by +.B ldap_initialize() +to connect to the server. This is useful in situations where a file +descriptor is required before a request is performed. +.LP +.B ldap_init_fd() +allows an LDAP structure to be initialized using an already-opened +connection. The +.I proto +parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, +or LDAP_PROTO_IPC +for a connection using TCP, UDP, or IPC, respectively. The value +LDAP_PROTO_EXT +may also be specified if user-supplied sockbuf handlers are going to +be used. Note that support for UDP is not implemented unless libldap +was built with LDAP_CONNECTIONLESS defined. +The +.I uri +parameter may optionally be provided for informational purposes. +.LP +.B ldap_set_urllist_proc() +allows to set a function +.I proc +of type +.I LDAP_URLLIST_PROC +that is called when a successful connection can be established. +This function receives the list of URIs parsed from the +.I uri +string originally passed to +.BR ldap_initialize() , +and the one that successfully connected. +The function may manipulate the URI list; the typical use consists +in moving the successful URI to the head of the list, +so that subsequent attempts to connect to one of the URIs using the same LDAP handle +will try it first. +If +.I ld +is null, +.I proc +is set as a global parameter that is inherited by all handlers +within the process that are created after the call to +.BR ldap_set_urllist_proc() . +By default, no +.I LDAP_URLLIST_PROC +is set. +In a multithreaded environment, +.B ldap_set_urllist_proc() +must be called before any concurrent operation using the LDAP handle is started. + +Note: the first call into the LDAP library also initializes the global +options for the library. As such the first call should be single-threaded +or otherwise protected to insure that only one call is active. It is +recommended that +.BR ldap_get_option () +or +.BR ldap_set_option () +be used in the program's main thread before any additional threads are created. +See +.BR ldap_get_option (3). + +.SH ERRORS +If an error occurs, +.B ldap_open() +and +.B ldap_init() +will return NULL and +.I errno +should be set appropriately. +.B ldap_initialize() +and +.B ldap_init_fd() +will directly return the LDAP code associated to the error (or +.I LDAP_SUCCESS +in case of success); +.I errno +should be set as well whenever appropriate. +.B ldap_set_urllist_proc() +returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_bind (3), +.BR ldap_get_option (3), +.BR ldap_set_option (3), +.BR lber-sockbuf (3), +.BR errno (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_parse_reference.3 b/static/netbsd/man3/ldap_parse_reference.3 new file mode 100644 index 00000000..08493bca --- /dev/null +++ b/static/netbsd/man3/ldap_parse_reference.3 @@ -0,0 +1,61 @@ +.TH LDAP_PARSE_REFERENCE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_reference \- Extract referrals and controls from a reference message +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_parse_reference( LDAP *ld, LDAPMessage *reference, + char ***referralsp, LDAPControl ***serverctrlsp, + int freeit ) +.SH DESCRIPTION +.LP +The +.B ldap_parse_reference() +routine is used to extract referrals and controls from a reference message. +The \fIreference\fP parameter is a reference message as returned by a +call to +.BR ldap_first_reference (3) , +.BR ldap_next_reference (3) , +.BR ldap_first_message (3) , +.BR ldap_next_message (3) , +or +.BR ldap_result (3) . +.LP +The \fIreferralsp\fP parameter will be filled in with an allocated array of +character strings. The strings are copies of the referrals contained in +the parsed message. The array should be freed by calling +.BR ldap_value_free (3) . +If \fIreferralsp\fP is NULL, no referrals are returned. +If no referrals were returned, \fI*referralsp\fP is set to NULL. +.LP +The \fIserverctrlsp\fP parameter will be filled in with an allocated array of +controls copied from the parsed message. The array should be freed by calling +.BR ldap_controls_free (3). +If \fIserverctrlsp\fP is NULL, no controls are returned. +If no controls were returned, \fI*serverctrlsp\fP is set to NULL. +.LP +The \fIfreeit\fP parameter determines whether the parsed message is +freed or not after the extraction. Any non-zero value will make it +free the message. The +.BR ldap_msgfree (3) +routine can also be used to free the message later. +.SH ERRORS +Upon success LDAP_SUCCESS is returned. Otherwise the values of the +\fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_reference (3), +.BR ldap_first_message (3), +.BR ldap_result (3), +.BR ldap_get_values (3), +.BR ldap_controls_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_parse_result.3 b/static/netbsd/man3/ldap_parse_result.3 new file mode 100644 index 00000000..ee89ecb3 --- /dev/null +++ b/static/netbsd/man3/ldap_parse_result.3 @@ -0,0 +1,114 @@ +.TH LDAP_PARSE_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_result \- Parsing results +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_parse_result( LDAP *ld, LDAPMessage *result, + int *errcodep, char **matcheddnp, char **errmsgp, + char ***referralsp, LDAPControl ***serverctrlsp, + int freeit ) +.LP +.ft B +int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, + struct berval **servercredp, int freeit ) +.LP +.ft B +int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, + char **retoidp, struct berval **retdatap, int freeit ) +.LP +.ft B +int ldap_parse_intermediate( LDAP *ld, LDAPMessage *result, + char **retoidp, struct berval **retdatap, + LDAPControl ***serverctrlsp, int freeit ) +.SH DESCRIPTION +.LP +These routines are used to extract information from a result message. +They will operate on the first result message in a chain of search +results (skipping past other message types). They take the \fIresult\fP +as returned by a call to +.BR ldap_result (3), +.BR ldap_search_s (3) +or +.BR ldap_search_st (3). +In addition to +.BR ldap_parse_result() , +the routines +.B ldap_parse_sasl_bind_result() +and +.B ldap_parse_extended_result() +are used to get all the result information from SASL bind and extended +operations. To extract information from intermediate responses, +.B ldap_parse_intermediate() +can be used. +.LP +The \fIerrcodep\fP parameter will be filled in with the result code from +the result message. +.LP +The server might supply a matched DN string in the message indicating +how much of a name in a request was recognized. The \fImatcheddnp\fP +parameter will be filled in with this string if supplied, else it will +be NULL. If a string is returned, it should be freed using +.BR ldap_memfree (3). +.LP +The \fIerrmsgp\fP parameter will be filled in with the error message +field from the parsed message. This string should be freed using +.BR ldap_memfree (3). +.LP +The \fIreferralsp\fP parameter will be filled in with an allocated array of +referral strings from the parsed message. This array should be freed using +.BR ldap_memvfree (3). +If no referrals were returned, \fI*referralsp\fP is set to NULL. +.LP +The \fIserverctrlsp\fP parameter will be filled in with an allocated array of +controls copied from the parsed message. The array should be freed using +.BR ldap_controls_free (3). +If no controls were returned, \fI*serverctrlsp\fP is set to NULL. +.LP +The \fIfreeit\fP parameter determines whether the parsed message is +freed or not after the extraction. Any non-zero value will make it +free the message. The +.BR ldap_msgfree (3) +routine can also be used to free the message later. +.LP +For SASL bind results, the \fIservercredp\fP parameter will be filled in +with an allocated berval structure containing the credentials from the +server if present. The structure should be freed using +.BR ber_bvfree (3). +.LP +For extended results and intermediate responses, the \fIretoidp\fP parameter will be filled in +with the dotted-OID text representation of the name of the extended +operation response. The string should be freed using +.BR ldap_memfree (3). +If no OID was returned, \fI*retoidp\fP is set to NULL. +.LP +For extended results and intermediate responses, the \fIretdatap\fP parameter will be filled in +with a pointer to a berval structure containing the data from the +extended operation response. The structure should be freed using +.BR ber_bvfree (3). +If no data were returned, \fI*retdatap\fP is set to NULL. +.LP +For all the above result parameters, NULL values can be used in calls +in order to ignore certain fields. +.SH ERRORS +Upon success LDAP_SUCCESS is returned. Otherwise the values of the +result parameters are undefined. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_search (3), +.BR ldap_memfree (3), +.BR ldap_memvfree (3), +.BR ldap_get_values (3), +.BR ldap_controls_free (3), +.BR lber-types (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_parse_sort_control.3 b/static/netbsd/man3/ldap_parse_sort_control.3 new file mode 100644 index 00000000..ac06ea04 --- /dev/null +++ b/static/netbsd/man3/ldap_parse_sort_control.3 @@ -0,0 +1,40 @@ +.TH LDAP_PARSE_SORT-CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_sort_control \- Decode the information returned from a search operation that used a server-side sort control +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_parse_sort_control(ld, ctrls, returnCode, attribute) +.ft +LDAP *ld; +LDAPControl **ctrls; +unsigned long *returnCode; +char **attribute; +.SH DESCRIPTION +This function is used to parse the results returned in a search operation +that uses a server-side sort control. +.LP +It takes a null terminated array of LDAPControl structures usually obtained +by a call to the +.BR ldap_parse_result +function. A returncode which points to the sort control result code,and an array +of LDAPControl structures that list the client controls to use with the search. +The function also takes an out parameter \fIattribute\fP and if the sort operation +fails, the server may return a string that indicates the first attribute in the +sortKey list that caused the failure. If this parameter is NULL, no string is +returned. If a string is returned, the memory should be freed by calling the +ldap_memfree function. +.SH NOTES +.SH SEE ALSO +.BR ldap_result (3), +.BR ldap_controls_free (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_parse_vlv_control.3 b/static/netbsd/man3/ldap_parse_vlv_control.3 new file mode 100644 index 00000000..84dd2cdb --- /dev/null +++ b/static/netbsd/man3/ldap_parse_vlv_control.3 @@ -0,0 +1,49 @@ +.TH LDAP_PARSE_VLV_CONTROL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_parse_vlv_control \- Decode the information returned from a search operation that used a VLV (virtual list view) control +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_parse_vlv_control( ld, ctrlp, target_posp, list_countp, contextp, errcodep ) +.ft +LDAP *ld; +LDAPControl **ctrlp; +unsigned long *target_posp, *list_countp; +struct berval **contextp; +int *errcodep; +.SH DESCRIPTION +The +.B ldap_parse_vlv_control +is used to decode the information returned from a search operation that used a +VLV (virtual list view)control. It takes a null terminated array of LDAPControl +structures, usually obtained by a call to the +.BR ldap_parse_result function, +a \fItarget_pos\fP which points to the list index of the target entry. If +this parameter is NULL, the target position is not returned. The index returned +is an approximation of the position of the target entry. It is +not guaranteed to be exact. The parameter \fIlist_countp\fP points to +the server's estimate of the size of the list. If this parameter is NULL, the +size is not returned. \fIcontextp\fP is a pointer to the address of a berval +structure that contains a server-generated context identifier if server returns +one. If server does not return a context identifier, the server returns a NULL +in this parameter. If this parameter is set to NULL, the context identifier is +not returned. You should use this returned context in the next call to +create a VLV control. When the berval structure is no longer needed, you should +free the memory by calling the \fIber_bvfree function.e\fP +\fIerrcodep\fP is an output parameter, which points to the result code returned +by the server. If this parameter is NULL, the result code is not returned. +.LP +See +ldap.h for a list of possible return codes. +.SH SEE ALSO +.BR ldap_search (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_rename.3 b/static/netbsd/man3/ldap_rename.3 new file mode 100644 index 00000000..db431cf8 --- /dev/null +++ b/static/netbsd/man3/ldap_rename.3 @@ -0,0 +1,66 @@ +.TH LDAP_RENAME 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_rename, ldap_rename_s \- Renames the specified entry. +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); +.ft +LDAP *ld; +const char *dn, *newrdn, *newparent; +int deleteoldrdn; +LDAPControl *sctrls[], *cctrls[]; +int *msgidp); +.LP +.ft B +int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); +.ft +LDAP *ld; +const char *dn, *newrdn, *newparent; +int deleteoldrdn; +LDAPControl *sctrls[], *cctrls[]; +.SH DESCRIPTION +These routines are used to perform a LDAP rename operation. +The function changes the leaf component of an entry's distinguished +name and optionally moves the entry to a new parent container. The +.B ldap_rename_s +performs a rename operation synchronously. +The method takes \fIdn\fP, which points to the distinguished name of +the entry whose attribute is being compared, \fInewparent\fP,the distinguished +name of the entry's new parent. If this parameter is NULL, only the RDN is changed. +The root DN is specified by passing a zero length string, "". +\fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. +Zero indicates that the old RDN should be retained. If you choose this option, +the attribute will contain both names (the old and the new). +Non-zero indicates that the old RDN should be deleted. +\fIserverctrls\fP points to an array of LDAPControl structures that list the +client controls to use with this extended operation. Use NULL to specify +no client controls. \fIclientctrls\fP points to an array of LDAPControl +structures that list the client controls to use with the search. +.LP +.B ldap_rename +works just like +.B ldap_rename_s, +but the operation is asynchronous. It returns the message id of the request +it initiated. The result of this operation can be obtained by calling +.BR ldap_result(3). +.SH ERRORS +.B ldap_rename() +returns \-1 in case of error initiating the request, and +will set the \fIld_errno\fP field in the \fIld\fP parameter to +indicate the error. +.BR ldap_rename_s() +returns the LDAP error code resulting from the rename operation. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_modify (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_result.3 b/static/netbsd/man3/ldap_result.3 new file mode 100644 index 00000000..c97410ea --- /dev/null +++ b/static/netbsd/man3/ldap_result.3 @@ -0,0 +1,136 @@ +.TH LDAP_RESULT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_result \- Wait for the result of an LDAP operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_result( LDAP *ld, int msgid, int all, + struct timeval *timeout, LDAPMessage **result ); + +int ldap_msgfree( LDAPMessage *msg ); + +int ldap_msgtype( LDAPMessage *msg ); + +int ldap_msgid( LDAPMessage *msg ); +.ft +.SH DESCRIPTION +The +.B ldap_result() +routine is used to wait for and return the result of +an operation previously initiated by one of the LDAP asynchronous +operation routines (e.g., +.BR ldap_search_ext (3), +.BR ldap_modify_ext (3), +etc.). Those routines all return \-1 in case of error, and an +invocation identifier upon successful initiation of the operation. The +invocation identifier is picked by the library and is guaranteed to be +unique across the LDAP session. It can be used to request the result +of a specific operation from +.B ldap_result() +through the \fImsgid\fP parameter. +.LP +The +.B ldap_result() +routine will block or not, depending upon the setting +of the \fItimeout\fP parameter. +If timeout is not a NULL pointer, it specifies a maximum +interval to wait for the selection to complete. If timeout +is a NULL pointer, the LDAP_OPT_TIMEOUT value set by +.BR ldap_set_option (3) +is used. With the default setting, +the select blocks indefinitely. To +effect a poll, the timeout argument should be a non-NULL +pointer, pointing to a zero-valued timeval structure. +To obtain the behavior of the default setting, bypassing any value set by +.BR ldap_set_option (3), +set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. +See +.BR select (2) +for further details. +.LP +If the result of a specific operation is required, \fImsgid\fP should +be set to the invocation identifier returned when the operation was +initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be +supplied to wait for any or unsolicited response. +.LP +The \fIall\fP parameter, if non-zero, causes +.B ldap_result() +to return all responses with msgid, otherwise only the +next response is returned. This is commonly used to obtain all +the responses of a search operation. +.LP +A search response is made up of zero or +more search entries, zero or more search references, and zero or +more extended partial responses followed by a search result. If +\fIall\fP is set to 0, search entries will be returned one at a +time as they come in, via separate calls to +.BR ldap_result() . +If it's set to 1, the search +response will only be returned in its entirety, i.e., after all entries, +all references, all extended partial responses, and the final search +result have been received. +.SH RETURN VALUE +Upon success, the type of the result received is returned and the +\fIresult\fP parameter will contain the result of the operation; +otherwise, the \fIresult\fP parameter is undefined. This +result should be passed to the LDAP parsing routines, +.BR ldap_first_message (3) +and friends, for interpretation. +.LP +The possible result types returned are: +.LP +.nf + LDAP_RES_BIND (0x61) + LDAP_RES_SEARCH_ENTRY (0x64) + LDAP_RES_SEARCH_REFERENCE (0x73) + LDAP_RES_SEARCH_RESULT (0x65) + LDAP_RES_MODIFY (0x67) + LDAP_RES_ADD (0x69) + LDAP_RES_DELETE (0x6b) + LDAP_RES_MODDN (0x6d) + LDAP_RES_COMPARE (0x6f) + LDAP_RES_EXTENDED (0x78) + LDAP_RES_INTERMEDIATE (0x79) +.fi +.LP +The +.B ldap_msgfree() +routine is used to free the memory allocated for +result(s) by +.B ldap_result() +or +.BR ldap_search_ext_s (3) +and friends. +It takes a pointer to the result or result chain to be freed and returns +the type of the last message in the chain. +If the parameter is NULL, the function does nothing and returns zero. +.LP +The +.B ldap_msgtype() +routine returns the type of a message. +.LP +The +.B ldap_msgid() +routine returns the message id of a message. +.SH ERRORS +.B ldap_result() +returns \-1 if something bad happens, and zero if the +timeout specified was exceeded. +.B ldap_msgtype() +and +.B ldap_msgid() +return \-1 on error. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_first_message (3), +.BR select (2) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_schema.3 b/static/netbsd/man3/ldap_schema.3 new file mode 100644 index 00000000..8751b5bd --- /dev/null +++ b/static/netbsd/man3/ldap_schema.3 @@ -0,0 +1,320 @@ +.TH LDAP_SCHEMA 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2000-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +#include +.LP +.ft B +LDAPSyntax * ldap_str2syntax(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_syntax2str(syn) +.ft +const LDAPSyntax * syn; +.LP +.ft B +const char * ldap_syntax2name(syn) +.ft +LDAPSyntax * syn; +.LP +.ft B +ldap_syntax_free(syn) +.ft +LDAPSyntax * syn; +.LP +.ft B +LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_matchingrule2str(mr); +.ft +const LDAPMatchingRule * mr; +.LP +.ft B +const char * ldap_matchingrule2name(mr) +.ft +LDAPMatchingRule * mr; +.LP +.ft B +ldap_matchingrule_free(mr) +.ft +LDAPMatchingRule * mr; +.LP +.ft B +LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_attributetype2str(at) +.ft +const LDAPAttributeType * at; +.LP +.ft B +const char * ldap_attributetype2name(at) +.ft +LDAPAttributeType * at; +.LP +.ft B +ldap_attributetype_free(at) +.ft +LDAPAttributeType * at; +.LP +.ft B +LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) +.ft +const char * s; +int * code; +const char ** errp; +const int flags; +.LP +.ft B +char * ldap_objectclass2str(oc) +.ft +const LDAPObjectClass * oc; +.LP +.ft B +const char * ldap_objectclass2name(oc) +.ft +LDAPObjectClass * oc; +.LP +.ft B +ldap_objectclass_free(oc) +.ft +LDAPObjectClass * oc; +.LP +.ft B +char * ldap_scherr2str(code) +.ft +int code; +.SH DESCRIPTION +These routines are used to parse schema definitions in the syntax +defined in RFC 4512 into structs and handle these structs. These +routines handle four kinds of definitions: syntaxes, matching rules, +attribute types and object classes. For each definition kind, four +routines are provided. +.LP +.B ldap_str2xxx() +takes a definition in RFC 4512 format in argument +.IR s +as a NUL-terminated string and returns, if possible, a pointer to a +newly allocated struct of the appropriate kind. The caller is +responsible for freeing the struct by calling +.B ldap_xxx_free() +when not needed any longer. The routine returns NULL if some problem +happened. In this case, the integer pointed at by argument +.IR code +will receive an error code (see below the description of +.B ldap_scherr2str() +for an explanation of the values) and a pointer to a NUL-terminated +string will be placed where requested by argument +.IR errp +, indicating where in argument +.IR s +the error happened, so it must not be freed by the caller. Argument +.IR flags +is a bit mask of parsing options controlling the relaxation of the +syntax recognized. The following values are defined: +.TP +.B LDAP_SCHEMA_ALLOW_NONE +strict parsing according to RFC 4512. +.TP +.B LDAP_SCHEMA_ALLOW_NO_OID +permit definitions that do not contain an initial OID. +.TP +.B LDAP_SCHEMA_ALLOW_QUOTED +permit quotes around some items that should not have them. +.TP +.B LDAP_SCHEMA_ALLOW_DESCR +permit a +.B descr +instead of a numeric OID in places where the syntax expect the latter. +.TP +.B LDAP_SCHEMA_ALLOW_DESCR_PREFIX +permit that the initial numeric OID contains a prefix in +.B descr +format. +.TP +.B LDAP_SCHEMA_ALLOW_ALL +be very liberal, include all options. +.LP +The structures returned are as follows: +.sp +.RS +.nf +.ne 7 +.ta 8n 16n 32n +typedef struct ldap_schema_extension_item { + char *lsei_name; /* Extension name */ + char **lsei_values; /* Extension values */ +} LDAPSchemaExtensionItem; + +typedef struct ldap_syntax { + char *syn_oid; /* OID */ + char **syn_names; /* Names */ + char *syn_desc; /* Description */ + LDAPSchemaExtensionItem **syn_extensions; /* Extension */ +} LDAPSyntax; + +typedef struct ldap_matchingrule { + char *mr_oid; /* OID */ + char **mr_names; /* Names */ + char *mr_desc; /* Description */ + int mr_obsolete; /* Is obsolete? */ + char *mr_syntax_oid; /* Syntax of asserted values */ + LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ +} LDAPMatchingRule; + +typedef struct ldap_attributetype { + char *at_oid; /* OID */ + char **at_names; /* Names */ + char *at_desc; /* Description */ + int at_obsolete; /* Is obsolete? */ + char *at_sup_oid; /* OID of superior type */ + char *at_equality_oid; /* OID of equality matching rule */ + char *at_ordering_oid; /* OID of ordering matching rule */ + char *at_substr_oid; /* OID of substrings matching rule */ + char *at_syntax_oid; /* OID of syntax of values */ + int at_syntax_len; /* Suggested minimum maximum length */ + int at_single_value; /* Is single-valued? */ + int at_collective; /* Is collective? */ + int at_no_user_mod; /* Are changes forbidden through LDAP? */ + int at_usage; /* Usage, see below */ + LDAPSchemaExtensionItem **at_extensions; /* Extensions */ +} LDAPAttributeType; + +typedef struct ldap_objectclass { + char *oc_oid; /* OID */ + char **oc_names; /* Names */ + char *oc_desc; /* Description */ + int oc_obsolete; /* Is obsolete? */ + char **oc_sup_oids; /* OIDs of superior classes */ + int oc_kind; /* Kind, see below */ + char **oc_at_oids_must; /* OIDs of required attribute types */ + char **oc_at_oids_may; /* OIDs of optional attribute types */ + LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ +} LDAPObjectClass; +.ta +.fi +.RE +.PP +Some integer fields (those described with a question mark) have a +truth value, for these fields the possible values are: +.TP +.B LDAP_SCHEMA_NO +The answer to the question is no. +.TP +.B LDAP_SCHEMA_YES +The answer to the question is yes. +.LP +For attribute types, the following usages are possible: +.TP +.B LDAP_SCHEMA_USER_APPLICATIONS +the attribute type is non-operational. +.TP +.B LDAP_SCHEMA_DIRECTORY_OPERATION +the attribute type is operational and is pertinent to the directory +itself, i.e. it has the same value on all servers that provide the +entry containing this attribute type. +.TP +.B LDAP_SCHEMA_DISTRIBUTED_OPERATION +the attribute type is operational and is pertinent to replication, +shadowing or other distributed directory aspect. TBC. +.TP +.B LDAP_SCHEMA_DSA_OPERATION +the attribute type is operational and is pertinent to the directory +server itself, i.e. it may have different values for the same entry +when retrieved from different servers that provide the entry. +.LP +Object classes can be of three kinds: +.TP +.B LDAP_SCHEMA_ABSTRACT +the object class is abstract, i.e. there cannot be entries of this +class alone. +.TP +.B LDAP_SCHEMA_STRUCTURAL +the object class is structural, i.e. it describes the main role of the +entry. On some servers, once the entry is created the set of +structural object classes assigned cannot be changed: none of those +present can be removed and none other can be added. +.TP +.B LDAP_SCHEMA_AUXILIARY +the object class is auxiliary, i.e. it is intended to go with other, +structural, object classes. These can be added or removed at any time +if attribute types are added or removed at the same time as needed by +the set of object classes resulting from the operation. +.LP +Routines +.B ldap_xxx2name() +return a canonical name for the definition. +.LP +Routines +.B ldap_xxx2str() +return a string representation in the format described by RFC 4512 of +the struct passed in the argument. The string is a newly allocated +string that must be freed by the caller. These routines may return +NULL if no memory can be allocated for the string. +.LP +.B ldap_scherr2str() +returns a NUL-terminated string with a text description of the error +found. This is a pointer to a static area, so it must not be freed by +the caller. The argument +.IR code +comes from one of the parsing routines and can adopt the following +values: +.TP +.B LDAP_SCHERR_OUTOFMEM +Out of memory. +.TP +.B LDAP_SCHERR_UNEXPTOKEN +Unexpected token. +.TP +.B LDAP_SCHERR_NOLEFTPAREN +Missing opening parenthesis. +.TP +.B LDAP_SCHERR_NORIGHTPAREN +Missing closing parenthesis. +.TP +.B LDAP_SCHERR_NODIGIT +Expecting digit. +.TP +.B LDAP_SCHERR_BADNAME +Expecting a name. +.TP +.B LDAP_SCHERR_BADDESC +Bad description. +.TP +.B LDAP_SCHERR_BADSUP +Bad superiors. +.TP +.B LDAP_SCHERR_DUPOPT +Duplicate option. +.TP +.B LDAP_SCHERR_EMPTY +Unexpected end of data. + +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_search.3 b/static/netbsd/man3/ldap_search.3 new file mode 100644 index 00000000..9fa78ae7 --- /dev/null +++ b/static/netbsd/man3/ldap_search.3 @@ -0,0 +1,144 @@ +.TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +#include +.LP +.ft B +int ldap_search_ext( +.RS +LDAP *\fIld\fB, +char *\fIbase\fB, +int \fIscope\fB, +char *\fIfilter\fB, +char *\fIattrs\fB[], +int \fIattrsonly\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +struct timeval *\fItimeout\fB, +int \fIsizelimit\fB, +int *\fImsgidp\fB ); +.RE +.LP +.ft B +int ldap_search_ext_s( +.RS +LDAP *\fIld\fB, +char *\fIbase\fB, +int \fIscope\fB, +char *\fIfilter\fB, +char *\fIattrs\fB[], +int \fIattrsonly\fB, +LDAPControl **\fIserverctrls\fB, +LDAPControl **\fIclientctrls\fB, +struct timeval *\fItimeout\fB, +int \fIsizelimit\fB, +LDAPMessage **\fIres\fB ); +.RE +.SH DESCRIPTION +These routines are used to perform LDAP search operations. +The +.B ldap_search_ext_s() +routine +does the search synchronously (i.e., not +returning until the operation completes), providing a pointer +to the resulting LDAP messages at the location pointed to by +the \fIres\fP parameter. +.LP +The +.B ldap_search_ext() +routine is the asynchronous version, initiating the search and returning +the message id of the operation it initiated in the integer +pointed to by the \fImsgidp\fP parameter. +.LP +The \fIbase\fP parameter is the DN of the entry at which to start the search. +.LP +The \fIscope\fP parameter is the scope of the search and should be one +of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, +to search the object's immediate children, LDAP_SCOPE_SUBTREE, to +search the object and all its descendants, or LDAP_SCOPE_CHILDREN, +to search all of the descendants. Note that the latter requires +the server support the LDAP Subordinates Search Scope extension. +.LP +The \fIfilter\fP is a string representation of the filter to +apply in the search. The string should conform to the format +specified in RFC 4515 as extended by RFC 4526. For instance, +"(cn=Jane Doe)". Note that use of the extension requires the +server to support the LDAP Absolute True/False Filter extension. +NULL may be specified to indicate the library should send the +filter (objectClass=*). +.LP +The \fIattrs\fP parameter is a null-terminated array of attribute +descriptions to return from matching entries. +If NULL is specified, the return of all user attributes is requested. +The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request +all user attributes to be returned. +The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to +request all operational attributes to be returned. Note that this +requires the server to support the LDAP All Operational Attribute +extension. +To request no attributes, the description "1.1" (LDAP_NO_ATTRS) +should be listed by itself. +.LP +The \fIattrsonly\fP parameter should be set to a non-zero value +if only attribute descriptions are wanted. It should be set to zero (0) +if both attributes descriptions and attribute values are wanted. +.LP +The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used +to specify server and client controls, respectively. +.LP +The +.B ldap_search_ext_s() +routine is the synchronous version of +.BR ldap_search_ext(). +.LP +It also returns a code indicating success or, in the +case of failure, indicating the nature of the failure +of the operation. See +.BR ldap_error (3) +for details. +.SH NOTES +Note that both read +and list functionality are subsumed by these routines, +by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to +emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). +.LP +These routines may dynamically allocate memory. The caller is +responsible for freeing such memory using supplied deallocation +routines. Return values are contained in . +.LP +Note that \fIres\fR parameter of +.B ldap_search_ext_s() +and +.B ldap_search_s() +should be freed with +.B ldap_msgfree() +regardless of return value of these functions. +.SH DEPRECATED INTERFACES +The +.B ldap_search() +routine is deprecated in favor of the +.B ldap_search_ext() +routine. The +.B ldap_search_s() +and +.B ldap_search_st() +routines are deprecated in favor of the +.B ldap_search_ext_s() +routine. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3), +.BR ldap_result (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_sort.3 b/static/netbsd/man3/ldap_sort.3 new file mode 100644 index 00000000..a8881e50 --- /dev/null +++ b/static/netbsd/man3/ldap_sort.3 @@ -0,0 +1,21 @@ +.TH LDAP_SORT 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH DESCRIPTION +The +.BR ldap_sort_entries (), +.BR ldap_sort_values (), +and +.BR ldap_sort_strcasecmp () +are deprecated. +.LP +.so Deprecated +.SH SEE ALSO +.BR ldap (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_sync.3 b/static/netbsd/man3/ldap_sync.3 new file mode 100644 index 00000000..13517066 --- /dev/null +++ b/static/netbsd/man3/ldap_sync.3 @@ -0,0 +1,326 @@ +.TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 2006-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.B #include +.LP +.BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ");" +.LP +.BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");" +.LP +.BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ");" +.LP +.BI "int ldap_sync_poll(ldap_sync_t *" ls ");" +.LP +.BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");" +.LP +.BI "void ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");" +.LP +.BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", struct berval *" entryUUID "," +.BI "ldap_sync_refresh_t " phase ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", BerVarray " syncUUIDs "," +.BI "ldap_sync_refresh_t " phase ");" +.RE +.LP +.BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls "," +.RS +.BI "LDAPMessage *" msg ", int " refreshDeletes ");" +.RE +.SH DESCRIPTION +.LP +These routines provide an interface to the LDAP Content Synchronization +operation (RFC 4533). +They require an +.BR ldap_sync_t +structure to be set up with parameters required for various phases +of the operation; this includes setting some handlers for special events. +All handlers take a pointer to the \fBldap_sync_t\fP structure as the first +argument, and a pointer to the \fBLDAPMessage\fP structure as received +from the server by the client library, plus, occasionally, other specific +arguments. + +The members of the \fBldap_sync_t\fP structure are: +.TP +.BI "char *" ls_base +The search base; by default, the +.B BASE +option in +.BR ldap.conf (5). +.TP +.BI "int " ls_scope +The search scope (one of +.BR LDAP_SCOPE_BASE , +.BR LDAP_SCOPE_ONELEVEL , +.BR LDAP_SCOPE_SUBORDINATE +or +.BR LDAP_SCOPE_SUBTREE ; +see +.B ldap.h +for details). +.TP +.BI "char *" ls_filter +The filter (RFC 4515); by default, +.BR (objectClass=*) . +.TP +.BI "char **" ls_attrs +The requested attributes; by default +.BR NULL , +indicating all user attributes. +.TP +.BI "int " ls_timelimit +The requested time limit (in seconds); by default +.BR 0 , +to indicate no limit. +.TP +.BI "int " ls_sizelimit +The requested size limit (in entries); by default +.BR 0 , +to indicate no limit. +.TP +.BI "int " ls_timeout +The desired timeout during polling with +.BR ldap_sync_poll (3). +A value of +.BR \-1 +means that polling is blocking, so +.BR ldap_sync_poll (3) +will not return until a message is received; a value of +.BR 0 +means that polling returns immediately, no matter if any response +is available or not; a positive value represents the timeout the +.BR ldap_sync_poll (3) +function will wait for response before returning, unless a message +is received; in that case, +.BR ldap_sync_poll (3) +returns as soon as the message is available. +.TP +.BI "ldap_sync_search_entry_f " ls_search_entry +A function that is called whenever an entry is returned. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the searchResultEntry; it can be parsed using the regular +client API routines, like +.BR ldap_get_dn (3), +.BR ldap_first_attribute (3), +and so on. +The +.BR entryUUID +argument contains the entryUUID of the entry. +The +.BR phase +argument indicates the type of operation: one of +.BR LDAP_SYNC_CAPI_PRESENT , +.BR LDAP_SYNC_CAPI_ADD , +.BR LDAP_SYNC_CAPI_MODIFY , +.BR LDAP_SYNC_CAPI_DELETE ; +in case of +.BR LDAP_SYNC_CAPI_PRESENT +or +.BR LDAP_SYNC_CAPI_DELETE , +only the DN is contained in the +.IR LDAPMessage ; +in case of +.BR LDAP_SYNC_CAPI_MODIFY , +the whole entry is contained in the +.IR LDAPMessage , +and the application is responsible of determining the differences +between the new view of the entry provided by the caller and the data +already known. +.TP +.BI "ldap_sync_search_reference_f " ls_search_reference +A function that is called whenever a search reference is returned. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the searchResultReference; it can be parsed using +the regular client API routines, like +.BR ldap_parse_reference (3). +.TP +.BI "ldap_sync_intermediate_f " ls_intermediate +A function that is called whenever something relevant occurs during +the refresh phase of the search, which is marked by +an \fIintermediateResponse\fP message type. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the intermediate response; it can be parsed using +the regular client API routines, like +.BR ldap_parse_intermediate (3). +The +.BR syncUUIDs +argument contains an array of UUIDs of the entries that depends +on the value of the +.BR phase +argument. +In case of +.BR LDAP_SYNC_CAPI_PRESENTS , +the "present" phase is being entered; +this means that the following sequence of results will consist +in entries in "present" sync state. +In case of +.BR LDAP_SYNC_CAPI_DELETES , +the "deletes" phase is being entered; +this means that the following sequence of results will consist +in entries in "delete" sync state. +In case of +.BR LDAP_SYNC_CAPI_PRESENTS_IDSET , +the message contains a set of UUIDs of entries that are present; +it replaces a "presents" phase. +In case of +.BR LDAP_SYNC_CAPI_DELETES_IDSET , +the message contains a set of UUIDs of entries that have been deleted; +it replaces a "deletes" phase. +In case of +.BR LDAP_SYNC_CAPI_DONE, +a "presents" phase with "refreshDone" set to "TRUE" has been returned +to indicate that the refresh phase of refreshAndPersist is over, and +the client should start polling. +Except for the +.BR LDAP_SYNC_CAPI_PRESENTS_IDSET +and +.BR LDAP_SYNC_CAPI_DELETES_IDSET +cases, +.BR syncUUIDs +is NULL. +.BR +.TP +.BI "ldap_sync_search_result_f " ls_search_result +A function that is called whenever a searchResultDone is returned. +In refreshAndPersist this can only occur when the server decides +that the search must be interrupted. +The +.BR msg +argument is the +.BR LDAPMessage +that contains the response; it can be parsed using +the regular client API routines, like +.BR ldap_parse_result (3). +The +.BR refreshDeletes +argument is not relevant in this case; it should always be \-1. +.TP +.BI "void *" ls_private +A pointer to private data. The client may register here +a pointer to data the handlers above may need. +.TP +.BI "LDAP *" ls_ld +A pointer to a LDAP structure that is used to connect to the server. +It is the responsibility of the client to initialize the structure +and to provide appropriate authentication and security in place. + +.SH "GENERAL USE" +A +.B ldap_sync_t +structure is initialized by calling +.BR ldap_sync_initialize(3). +This simply clears out the contents of an already existing +.B ldap_sync_t +structure, and sets appropriate values for some members. +After that, the caller is responsible for setting up the +connection (member +.BR ls_ld ), +eventually setting up transport security (TLS), +for binding and any other initialization. +The caller must also fill all the documented search-related fields +of the +.B ldap_sync_t +structure. + +At the end of a session, the structure can be cleaned up by calling +.BR ldap_sync_destroy (3), +which takes care of freeing all data assuming it was allocated by +.BR ldap_mem* (3) +routines. +Otherwise, the caller should take care of destroying and zeroing out +the documented search-related fields, and call +.BR ldap_sync_destroy (3) +to free undocumented members set by the API. + +.SH "REFRESH ONLY" +The +.BR refreshOnly +functionality is obtained by periodically calling +.BR ldap_sync_init (3) +with mode set to +.BR LDAP_SYNC_REFRESH_ONLY , +or, which is equivalent, by directly calling +.BR ldap_sync_init_refresh_only (3). +The state of the search, and the consistency of the search parameters, +is preserved across calls by passing the +.B ldap_sync_t +structure as left by the previous call. + +.SH "REFRESH AND PERSIST" +The +.BR refreshAndPersist +functionality is obtained by calling +.BR ldap_sync_init (3) +with mode set to +.BR LDAP_SYNC_REFRESH_AND_PERSIST , +or, which is equivalent, by directly calling +.BR ldap_sync_init_refresh_and_persist (3) +and, after a successful return, by repeatedly polling with +.BR ldap_sync_poll (3) +according to the desired pattern. + +A client may insert a call to +.BR ldap_sync_poll (3) +into an external loop to check if any modification was returned; +in this case, it might be appropriate to set +.BR ls_timeout +to 0, or to set it to a finite, small value. +Otherwise, if the client's main purpose consists in waiting for +responses, a timeout of \-1 is most suitable, so that the function +only returns after some data has been received and handled. + +.SH ERRORS +All routines return any LDAP error resulting from a lower-level error +in the API calls they are based on, or LDAP_SUCCESS in case of success. +.BR ldap_sync_poll (3) +may return +.BR LDAP_SYNC_REFRESH_REQUIRED +if a full refresh is requested by the server. +In this case, it is appropriate to call +.BR ldap_sync_init (3) +again, passing the same +.B ldap_sync_t +structure as resulted from any previous call. +.SH NOTES +.SH SEE ALSO +.BR ldap (3), +.BR ldap_search_ext (3), +.BR ldap_result (3) ; +.B RFC 4533 +(http://www.rfc-editor.org), +.SH AUTHOR +Designed and implemented by Pierangelo Masarati, based on RFC 4533 +and loosely inspired by syncrepl code in +.BR slapd (8). +.SH ACKNOWLEDGEMENTS +Initially developed by +.BR "SysNet s.n.c." +.B OpenLDAP +is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). +.B OpenLDAP +is derived from University of Michigan LDAP 3.3 Release. diff --git a/static/netbsd/man3/ldap_tls.3 b/static/netbsd/man3/ldap_tls.3 new file mode 100644 index 00000000..f4df106e --- /dev/null +++ b/static/netbsd/man3/ldap_tls.3 @@ -0,0 +1,41 @@ +.TH LDAP_TLS 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.B #include +.LP +.BI "int ldap_start_tls(LDAP *" ld ");" +.LP +.BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" +.LP +.BI "int ldap_tls_inplace(LDAP *" ld ");" +.LP +.BI "int ldap_install_tls(LDAP *" ld ");" +.SH DESCRIPTION +These routines are used to initiate TLS processing on an LDAP session. +.BR ldap_start_tls_s () +sends a StartTLS request to a server, waits for the reply, and then installs +TLS handlers on the session if the request succeeded. The routine returns +.B LDAP_SUCCESS +if everything succeeded, otherwise it returns an LDAP error code. +.BR ldap_start_tls () +sends a StartTLS request to a server and does nothing else. It returns +.B LDAP_SUCCESS +if the request was sent successfully. +.BR ldap_tls_inplace () +returns 1 if TLS handlers have been installed on the specified session, 0 +otherwise. +.BR ldap_install_tls () +installs the TLS handlers on the given session. It returns +.B LDAP_LOCAL_ERROR +if TLS is already installed. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3) +.SH ACKNOWLEDGEMENTS +.so ../Project diff --git a/static/netbsd/man3/ldap_url.3 b/static/netbsd/man3/ldap_url.3 new file mode 100644 index 00000000..b6509bc6 --- /dev/null +++ b/static/netbsd/man3/ldap_url.3 @@ -0,0 +1,83 @@ +.TH LDAP_URL 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.SH NAME +ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines +.SH LIBRARY +OpenLDAP LDAP (libldap, \-lldap) +.SH SYNOPSIS +.nf +.ft B +#include +.LP +.ft B +int ldap_is_ldap_url( const char *url ) +.LP +.ft B +int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) +.LP +typedef struct ldap_url_desc { + char * lud_scheme; /* URI scheme */ + char * lud_host; /* LDAP host to contact */ + int lud_port; /* port on host */ + char * lud_dn; /* base for search */ + char ** lud_attrs; /* list of attributes */ + int lud_scope; /* a LDAP_SCOPE_... value */ + char * lud_filter; /* LDAP search filter */ + char ** lud_exts; /* LDAP extensions */ + int lud_crit_exts; /* true if any extension is critical */ + /* may contain additional fields for internal use */ +} LDAPURLDesc; +.LP +.ft B +void ldap_free_urldesc( LDAPURLDesc *ludp ); +.SH DESCRIPTION +These routines support the use of LDAP URLs (Uniform Resource Locators) +as detailed in RFC 4516. LDAP URLs look like this: +.nf + + \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] + +where: + \fIhostport\fP is a host name with an optional ":portnumber" + \fIdn\fP is the search base + \fIattrs\fP is a comma separated list of attributes to request + \fIscope\fP is one of these three strings: + base one sub (default=base) + \fIfilter\fP is filter + \fIexts\fP are recognized set of LDAP and/or API extensions. + +Example: + ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) + +.fi +.LP +URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also +tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be +parsed using the below routines as well. +.LP +.B ldap_is_ldap_url() +returns a non-zero value if \fIurl\fP looks like an LDAP URL (as +opposed to some other kind of URL). It can be used as a quick check +for an LDAP URL; the +.B ldap_url_parse() +routine should be used if a more thorough check is needed. +.LP +.B ldap_url_parse() +breaks down an LDAP URL passed in \fIurl\fP into its component pieces. +If successful, zero is returned, an LDAP URL description is +allocated, filled in, and \fIludpp\fP is set to point to it. If an +error occurs, a non-zero URL error code is returned. +.LP +.B ldap_free_urldesc() +should be called to free an LDAP URL description that was obtained from +a call to +.B ldap_url_parse(). +.SH SEE ALSO +.nf +.BR ldap (3) +.BR "RFC 4516" " " +.SH ACKNOWLEDGEMENTS +.fi +.so ../Project diff --git a/static/netbsd/man3/ldexp.3 b/static/netbsd/man3/ldexp.3 new file mode 100644 index 00000000..8d4515b6 --- /dev/null +++ b/static/netbsd/man3/ldexp.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: ldexp.3,v 1.5 2016/03/17 18:29:59 nros Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ldexp.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd March 17, 2016 +.Dt LDEXP 3 +.Os +.Sh NAME +.Nm ldexp , +.Nm ldexpf , +.Nm ldexpl +.Nd multiply floating-point number by integral power of 2 +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn ldexp "double x" "int exp" +.Ft float +.Fn ldexpf "float x" "int exp" +.Ft long double +.Fn ldexpl "long double x" "int exp" +.Sh DESCRIPTION +The +.Fn ldexp +family of functions compute +.Bd -ragged -offset indent +.Va x +* +2^\fIexp\fR +.Ed +.Pp +for a real floating-point number +.Fa x . +.Sh RETURN VALUES +The functions return the value of +.Fa x +times 2 raised to the power +.Fa exp . +Otherwise the following may occur: +.Bl -enum -offset indent +.It +If +.Fa x +is \*(Na, a \*(Na is returned. +.It +If +.Fa exp +is zero or +.Fa x +is either \*(Pm 0 or \*(Pm\[if], +.Fa x +is returned. +.It +If the call would cause an overflow, a range error occurs and either +.Dv \*(Pm\*HHUGE_VAL , +.Dv \*(Pm\*HHUGE_VALF , +or +.Dv \*(Pm\*HHUGE_VALL +is returned, depending on the sign of +.Fa x +and the type of the return value. +.It +If an underflow would be caused by the correct value, +and the value is not representable, either 0.0 or +an implementation-defined value is returned. +.El +.Sh SEE ALSO +.Xr frexp 3 , +.Xr math 3 , +.Xr modf 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/length.3 b/static/netbsd/man3/length.3 new file mode 100644 index 00000000..4af26c60 --- /dev/null +++ b/static/netbsd/man3/length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: length.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/ntlm_buf.3 diff --git a/static/netbsd/man3/lgamma.3 b/static/netbsd/man3/lgamma.3 new file mode 100644 index 00000000..5c0efb74 --- /dev/null +++ b/static/netbsd/man3/lgamma.3 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)lgamma.3 6.6 (Berkeley) 12/3/92 +.\" $NetBSD: lgamma.3,v 1.24 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd January 24, 2024 +.Dt LGAMMA 3 +.Os +.Sh NAME +.Nm lgamma , +.Nm lgammaf , +.Nm lgammal , +.Nm lgamma_r , +.Nm lgammaf_r , +.Nm lgammal_r , +.Nm gamma , +.Nm gammaf , +.Nm gamma_r , +.Nm gammaf_r , +.Nm tgamma , +.Nm tgammaf , +.Nm tgammal +.Nd log gamma function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft extern int +.Fa signgam ; +.sp +.Ft double +.Fn lgamma "double x" +.Ft float +.Fn lgammaf "float x" +.Ft long double +.Fn lgammal "long double x" +.Ft double +.Fn lgamma_r "double x" "int *sign" +.Ft float +.Fn lgammaf_r "float x" "int *sign" +.Ft long double +.Fn lgammal_r "long double x" "int *sign" +.Ft double +.Fn gamma "double x" +.Ft float +.Fn gammaf "float x" +.Ft double +.Fn gamma_r "double x" "int *sign" +.Ft float +.Fn gammaf_r "float x" "int *sign" +.Ft double +.Fn tgamma "double x" +.Ft float +.Fn tgammaf "float x" +.Ft long double +.Fn tgammal "long double x" +.Sh DESCRIPTION +.Fn lgamma x +.if t \{\ +returns ln\||\(*G(x)| where +.Bd -unfilled -offset indent +\(*G(x) = \(is\d\s8\z0\s10\u\u\s8\(if\s10\d t\u\s8x\-1\s10\d e\u\s8\-t\s10\d dt for x > 0 and +.br +\(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px)) for x < 1. +.Ed +.\} +.if n \ +returns ln\||\(*G(x)|. +.Pp +The external integer +.Fa signgam +returns the sign of \(*G(x). +.Pp +.Fn lgamma_r +is a reentrant interface that performs identically to +.Fn lgamma , +differing in that the sign of \(*G(x) is stored in the location +pointed to by the +.Fa sign +argument and +.Fa signgam +is not modified. +.Pp +The +.Fn tgamma x +and +.Fn tgammaf x +functions return \(*G(x), with no effect on +.Fa signgam . +.Pp +.Fn gamma , +.Fn gammaf , +.Fn gamma_r , +and +.Fn gammaf_r +are deprecated aliases for +.Fn lgamma , +.Fn lgammaf , +.Fn lgamma_r , +and +.Fn lgammaf_r , +respectively. +.Sh IDIOSYNCRASIES +Do not use the expression +.Dq Li signgam\(**exp(lgamma(x)) +to compute g := \(*G(x). +Instead use a program like this (in C): +.Bd -literal -offset indent +lg = lgamma(x); g = signgam\(**exp(lg); +.Ed +.Pp +Only after +.Fn lgamma +has returned can signgam be correct. +.Sh RETURN VALUES +.Fn lgamma +returns appropriate values unless an argument is out of range. +Overflow will occur for sufficiently large positive values, and +non-positive integers. +For large non-integer negative values, +.Fn tgamma +will underflow. +On the +.Tn VAX , +the reserved operator is returned, +and +.Va errno +is set to +.Er ERANGE . +.Sh SEE ALSO +.Xr math 3 +.Sh HISTORY +The +.Nm lgamma +function appeared in +.Bx 4.3 . +The +.Fn tgamma +function appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/lh_stats.3 b/static/netbsd/man3/lh_stats.3 new file mode 100644 index 00000000..68cb9e3a --- /dev/null +++ b/static/netbsd/man3/lh_stats.3 @@ -0,0 +1,192 @@ +.\" $NetBSD: lh_stats.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "lh_stats 3" +.TH lh_stats 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, +lh_node_stats_bio, lh_node_usage_stats_bio \- LHASH statistics +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include +\& +\& void lh_stats(LHASH *table, FILE *out); +\& void lh_node_stats(LHASH *table, FILE *out); +\& void lh_node_usage_stats(LHASH *table, FILE *out); +\& +\& void lh_stats_bio(LHASH *table, BIO *out); +\& void lh_node_stats_bio(LHASH *table, BIO *out); +\& void lh_node_usage_stats_bio(LHASH *table, BIO *out); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1LHASH\s0\fR structure records statistics about most aspects of +accessing the hash table. This is mostly a legacy of Eric Young +writing this library for the reasons of implementing what looked like +a nice algorithm rather than for a particular software product. +.PP +\&\fIlh_stats()\fR prints out statistics on the size of the hash table, how +many entries are in it, and the number and result of calls to the +routines in this library. +.PP +\&\fIlh_node_stats()\fR prints the number of entries for each 'bucket' in the +hash table. +.PP +\&\fIlh_node_usage_stats()\fR prints out a short summary of the state of the +hash table. It prints the 'load' and the 'actual load'. The load is +the average number of data items per 'bucket' in the hash table. The +\&'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. So the 'actual load' is the +average number of searches that will need to find an item in the hash +table, while the 'load' is the average number that will be done to +record a miss. +.PP +\&\fIlh_stats_bio()\fR, \fIlh_node_stats_bio()\fR and \fIlh_node_usage_stats_bio()\fR +are the same as the above, except that the output goes to a \fB\s-1BIO\s0\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +These functions do not return values. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_bio\fR\|(3), \fIopenssl_lhash\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +These functions are available in all versions of SSLeay and OpenSSL. +.PP +This manpage is derived from the SSLeay documentation. diff --git a/static/netbsd/man3/libarchive.3 b/static/netbsd/man3/libarchive.3 new file mode 100644 index 00000000..c67172bf --- /dev/null +++ b/static/netbsd/man3/libarchive.3 @@ -0,0 +1,297 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 18, 2012 +.Dt LIBARCHIVE 3 +.Os +.Sh NAME +.Nm libarchive +.Nd functions for reading and writing streaming archives +.Sh OVERVIEW +The +.Nm +library provides a flexible interface for reading and writing +archives in various formats such as tar and cpio. +.Nm +also supports reading and writing archives compressed using +various compression filters such as gzip and bzip2. +The library is inherently stream-oriented; readers serially iterate through +the archive, writers serially add things to the archive. +In particular, note that there is currently no built-in support for +random access nor for in-place modification. +.Pp +When reading an archive, the library automatically detects the +format and the compression. +The library currently has read support for: +.Bl -bullet -compact +.It +old-style tar archives, +.It +most variants of the POSIX +.Dq ustar +format, +.It +the POSIX +.Dq pax interchange +format, +.It +GNU-format tar archives, +.It +most common cpio archive formats, +.It +7-Zip archives, +.It +ar archives (including GNU/SysV and BSD extensions), +.It +Microsoft CAB archives, +.It +ISO9660 CD images (including RockRidge and Joliet extensions), +.It +LHA archives, +.It +mtree file tree descriptions, +.It +RAR and most RAR5 archives, +.It +WARC archives, +.It +XAR archives, +.It +Zip archives. +.El +The library automatically detects archives compressed with +.Xr compress 1 , +.Xr bzip2 1 , +.Xr grzip 1 , +.Xr gzip 1 , +.Xr lrzip 1 , +.Xr lz4 1 , +.Xr lzip 1 , +.Xr lzop 1 , +.Xr xz 1 , +or +.Xr zstd 1 +and decompresses them transparently. Decompression of some formats +requires external decompressor utilities. +It can similarly detect and decode archives processed with +.Xr uuencode 1 +or which have an +.Xr rpm 1 +header. +.Pp +When writing an archive, you can specify the compression +to be used and the format to use. +The library can write +.Bl -bullet -compact +.It +POSIX-standard +.Dq ustar +archives, +.It +POSIX +.Dq pax interchange format +archives, +.It +cpio archives, +.It +7-Zip archives, +.It +ar archives, +.It +two different variants of shar archives, +.It +ISO9660 CD images, +.It +mtree file tree descriptions, +.It +XAR archives, +.It +Zip archive. +.El +Pax interchange format is an extension of the tar archive format that +eliminates essentially all of the limitations of historic tar formats +in a standard fashion that is supported +by POSIX-compliant +.Xr pax 1 +implementations on many systems as well as several newer implementations of +.Xr tar 1 . +Note that the default write format will suppress the pax extended +attributes for most entries; explicitly requesting pax format will +enable those attributes for all entries. +.Pp +The read and write APIs are accessed through the +.Fn archive_read_XXX +functions and the +.Fn archive_write_XXX +functions, respectively, and either can be used independently +of the other. +.Pp +The rest of this manual page provides an overview of the library +operation. +More detailed information can be found in the individual manual +pages for each API or utility function. +.\" +.Sh READING AN ARCHIVE +See +.Xr archive_read 3 . +.\" +.Sh WRITING AN ARCHIVE +See +.Xr archive_write 3 . +.\" +.Sh WRITING ENTRIES TO DISK +The +.Xr archive_write_disk 3 +API allows you to write +.Xr archive_entry 3 +objects to disk using the same API used by +.Xr archive_write 3 . +The +.Xr archive_write_disk 3 +API is used internally by +.Fn archive_read_extract ; +using it directly can provide greater control over how entries +get written to disk. +This API also makes it possible to share code between +archive-to-archive copy and archive-to-disk extraction +operations. +.Sh READING ENTRIES FROM DISK +The +.Xr archive_read_disk 3 +supports for populating +.Xr archive_entry 3 +objects from information in the filesystem. +This includes the information accessible from the +.Xr stat 2 +system call as well as ACLs, extended attributes, +and other metadata. +The +.Xr archive_read_disk 3 +API also supports iterating over directory trees, +which allows directories of files to be read using +an API compatible with +the +.Xr archive_read 3 +API. +.Sh DESCRIPTION +Detailed descriptions of each function are provided by the +corresponding manual pages. +.Pp +All of the functions utilize an opaque +.Tn struct archive +datatype that provides access to the archive contents. +.Pp +The +.Tn struct archive_entry +structure contains a complete description of a single archive +entry. +It uses an opaque interface that is fully documented in +.Xr archive_entry 3 . +.Pp +Users familiar with historic formats should be aware that the newer +variants have eliminated most restrictions on the length of textual fields. +Clients should not assume that filenames, link names, user names, or +group names are limited in length. +In particular, pax interchange format can easily accommodate pathnames +in arbitrary character sets that exceed +.Va PATH_MAX . +.Sh RETURN VALUES +Most functions return +.Cm ARCHIVE_OK +(zero) on success, non-zero on error. +The return value indicates the general severity of the error, ranging +from +.Cm ARCHIVE_WARN , +which indicates a minor problem that should probably be reported +to the user, to +.Cm ARCHIVE_FATAL , +which indicates a serious problem that will prevent any further +operations on this archive. +On error, the +.Fn archive_errno +function can be used to retrieve a numeric error code (see +.Xr errno 2 ) . +The +.Fn archive_error_string +returns a textual error message suitable for display. +.Pp +.Fn archive_read_new +and +.Fn archive_write_new +return pointers to an allocated and initialized +.Tn struct archive +object. +.Pp +.Fn archive_read_data +and +.Fn archive_write_data +return a count of the number of bytes actually read or written. +A value of zero indicates the end of the data for this entry. +A negative value indicates an error, in which case the +.Fn archive_errno +and +.Fn archive_error_string +functions can be used to obtain more information. +.Sh ENVIRONMENT +There are character set conversions within the +.Xr archive_entry 3 +functions that are impacted by the currently-selected locale. +.Sh SEE ALSO +.Xr tar 1 , +.Xr archive_entry 3 , +.Xr archive_read 3 , +.Xr archive_util 3 , +.Xr archive_write 3 , +.Xr tar 5 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was originally written by +.An Tim Kientzle Aq kientzle@acm.org . +.Sh BUGS +Some archive formats support information that is not supported by +.Tn struct archive_entry . +Such information cannot be fully archived or restored using this library. +This includes, for example, comments, character sets, +or the arbitrary key/value pairs that can appear in +pax interchange format archives. +.Pp +Conversely, of course, not all of the information that can be +stored in an +.Tn struct archive_entry +is supported by all formats. +For example, cpio formats do not support nanosecond timestamps; +old tar formats do not support large device numbers. +.Pp +The ISO9660 reader cannot yet read all ISO9660 images; +it should learn how to seek. +.Pp +The AR writer requires the client program to use +two passes, unlike all other libarchive writers. diff --git a/static/netbsd/man3/libarchive_changes.3 b/static/netbsd/man3/libarchive_changes.3 new file mode 100644 index 00000000..fd0e7210 --- /dev/null +++ b/static/netbsd/man3/libarchive_changes.3 @@ -0,0 +1,339 @@ +.\" Copyright (c) 2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 23, 2011 +.Dt LIBARCHIVE_CHANGES 3 +.Os +.Sh NAME +.Nm libarchive_changes +.Nd changes in libarchive interface +.\" +.Sh CHANGES IN LIBARCHIVE 3 +This page describes user-visible changes in libarchive3, and lists +public functions and other symbols changed, deprecated or removed +in libarchive3, along with their replacements if any. +.\" +.Ss Multiple Filters +.\" +Libarchive2 permitted a single (input or output) filter active +on an archive. +Libarchive3 extends this into a variable-length stack. +Where +.Fn archive_write_set_compression_XXX +would replace any existing filter, +.Fn archive_write_add_filter_XXX +extends the write pipeline with another filter. +.\" +.Ss Character Set Handling +.\" +Libarchive2 assumed that the local platform uses +.Tn Unicode +as the native +.Tn wchar_t +encoding, which is true on +.Tn Windows , +modern +.Tn Linux , +and a few other systems, but is certainly not universal. +As a result, pax format archives were written incorrectly on some +systems, since pax format requires +.Tn UTF-8 +and libarchive 2 incorrectly +assumed that +.Tn wchar_t +strings can be easily converted to +.Tn UTF-8 . +.Pp +Libarchive3 uses the standard iconv library to convert between character +sets and is introducing the notion of a +.Dq default character set for the archive . +To support this, +.Tn archive_entry +objects can now be bound to a particular archive when they are created. +The automatic character set conversions performed by +.Tn archive_entry +objects when reading and writing filenames, usernames, and other strings +will now use an appropriate default character set: +.Pp +If the +.Tn archive_entry +object is bound to an archive, it will use the +default character set for that archive. +.Pp +The platform default character encoding (as returned by +.Fn nl_langinfo CHARSET ) +will be used if nothing else is specified. +.Pp +Libarchive3 also introduces charset options to many of the archive +readers and writers to control the character set that will be used for +filenames written in those archives. +When possible, this will be set automatically based on information in +the archive itself. +Combining this with the notion of a default character set for the +archive should allow you to configure libarchive to read archives from +other platforms and have the filenames and other information +transparently converted to the character encoding suitable for your +application. +.\" +.Ss Prototype Changes +.\" +These changes break binary compatibility; libarchive3 has a new shared +library version to reflect these changes. +The library now uses portable wide types such as +.Tn int64_t +instead of less-portable types such as +.Tn off_t , +.Tn gid_t , +.Tn uid_t , +and +.Tn ino_t . +.Pp +There are a few cases where these changes will affect your source code: +.Bl -bullet -width ind +.It +In some cases, libarchive's wider types will introduce the possibility +of truncation: for example, on a system with a 16-bit +.Tn uid_t , you risk having uid +.Li 65536 +be truncated to uid +.Li 0 , +which can cause serious security problems. +.It +Typedef function pointer types will be incompatible. +For example, if you define custom skip callbacks, you may have to use +code similar to the following if you want to support building against +libarchive2 and libarchive3: +.Bd -literal +#if ARCHIVE_VERSION_NUMBER < 3000000 +typedef off_t myoff_t; +#else +typedef int64_t myoff_t; +#endif + +myoff_t +my_skip_function(struct archive *a, void *v, myoff_t o) +{ + ... implementation ... +} +.Ed +.El +.Pp +Affected functions: +.Pp +.Bl -bullet -compact +.It +.Xo +.Fn archive_entry_gid , +.Fn archive_entry_set_gid +.Xc +.It +.Xo +.Fn archive_entry_uid , +.Fn archive_entry_set_uid +.Xc +.It +.Xo +.Fn archive_entry_ino , +.Fn archive_entry_set_ino +.Xc +.It +.Xo +.Fn archive_read_data_block , +.Fn archive_write_data_block +.Xc +.It +.Xo +.Fn archive_read_disk_gname , +.Fn archive_read_disk_uname +.Xc +.It +.Xo +.Fn archive_read_disk_set_gname_lookup , +.Fn archive_read_disk_set_group_lookup , +.Fn archive_read_disk_set_uname_lookup , +.Fn archive_read_disk_set_user_lookup +.Xc +.It +.Fn archive_skip_callback +.It +.Xo +.Fn archive_read_extract_set_skip_file , +.Fn archive_write_disk_set_skip_file , +.Fn archive_write_set_skip_file +.Xc +.It +.Xo +.Fn archive_write_disk_set_group_lookup , +.Fn archive_write_disk_set_user_lookup +.Xc +.El +.Pp +Where these functions or their arguments took or returned +.Tn gid_t , +.Tn ino_t , +.Tn off_t , +or +.Tn uid_t +they now take or return +.Tn int64_t +or equivalent. +.\" +.Ss Deprecated Symbols +.\" +Symbols deprecated in libarchive3 will be removed in libarchive4. +These symbols, along with their replacements if any, are listed below: +.\" +.Bl -tag -width ind +.It Fn archive_position_compressed , Fn archive_position_uncompressed +.Fn archive_filter_bytes +.It Fn archive_compression +.Fn archive_filter_code +.It Fn archive_compression_name +.Fn archive_filter_name +.It Fn archive_read_finish , Fn archive_write_finish +.Fn archive_read_free , +.Fn archive_write_free +.It Fn archive_read_open_file , Fn archive_write_open_file +.Fn archive_read_open_filename , +.Fn archive_write_open_filename +.It Fn archive_read_support_compression_all +.\" archive_read_support_compression_* -> archive_read_support_filter_* +.Fn archive_read_support_filter_all +.It Fn archive_read_support_compression_bzip2 +.Fn archive_read_support_filter_bzip2 +.It Fn archive_read_support_compression_compress +.Fn archive_read_support_filter_compress +.It Fn archive_read_support_compression_gzip +.Fn archive_read_support_filter_gzip +.It Fn archive_read_support_compression_lzip +.Fn archive_read_support_filter_lzip +.It Fn archive_read_support_compression_lzma +.Fn archive_read_support_filter_lzma +.It Fn archive_read_support_compression_none +.Fn archive_read_support_filter_none +.It Fn archive_read_support_compression_program +.Fn archive_read_support_filter_program +.It Fn archive_read_support_compression_program_signature +.Fn archive_read_support_filter_program_signature +.It Fn archive_read_support_compression_rpm +.Fn archive_read_support_filter_rpm +.It Fn archive_read_support_compression_uu +.Fn archive_read_support_filter_uu +.It Fn archive_read_support_compression_xz +.Fn archive_read_support_filter_xz +.\" archive_write_set_compression_* -> archive_write_add_filter_* +.It Fn archive_write_set_compression_bzip2 +.Fn archive_write_add_filter_bzip2 +.It Fn archive_write_set_compression_compress +.Fn archive_write_add_filter_compress +.It Fn archive_write_set_compression_gzip +.Fn archive_write_add_filter_gzip +.It Fn archive_write_set_compression_lzip +.Fn archive_write_add_filter_lzip +.It Fn archive_write_set_compression_lzma +.Fn archive_write_add_filter_lzma +.It Fn archive_write_set_compression_none +.Fn archive_write_add_filter_none +.It Fn archive_write_set_compression_program +.Fn archive_write_add_filter_program +.It Fn archive_write_set_compression_filter +.Fn archive_write_add_filter_filter +.El +.\" +.Ss Removed Symbols +.\" +These symbols, listed below along with their replacements if any, +were deprecated in libarchive2, and are not part of libarchive3. +.\" +.Bl -tag -width ind +.It Fn archive_api_feature +.Fn archive_version_number +.It Fn archive_api_version +.Fn archive_version_number +.It Fn archive_version +.Fn archive_version_string +.It Fn archive_version_stamp +.Fn archive_version_number +.It Fn archive_read_set_filter_options +.Fn archive_read_set_options +or +.Fn archive_read_set_filter_option +.It Fn archive_read_set_format_options +.Fn archive_read_set_options +or +.Fn archive_read_set_format_option +.It Fn archive_write_set_filter_options +.Fn archive_write_set_options +or +.Fn archive_write_set_filter_option +.It Fn archive_write_set_format_options +.Fn archive_write_set_options +or +.Fn archive_write_set_format_option +.It Dv ARCHIVE_API_FEATURE +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_API_VERSION +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_VERSION_STAMP +.Dv ARCHIVE_VERSION_NUMBER +.It Dv ARCHIVE_LIBRARY_VERSION +.Dv ARCHIVE_VERSION_STRING +.\" +.It Dv ARCHIVE_COMPRESSION_NONE +.Dv ARCHIVE_FILTER_NONE +.It Dv ARCHIVE_COMPRESSION_GZIP +.Dv ARCHIVE_FILTER_GZIP +.It Dv ARCHIVE_COMPRESSION_BZIP2 +.Dv ARCHIVE_FILTER_BZIP2 +.It Dv ARCHIVE_COMPRESSION_COMPRESS +.Dv ARCHIVE_FILTER_COMPRESS +.It Dv ARCHIVE_COMPRESSION_PROGRAM +.Dv ARCHIVE_FILTER_PROGRAM +.It Dv ARCHIVE_COMPRESSION_LZMA +.Dv ARCHIVE_FILTER_LZMA +.It Dv ARCHIVE_COMPRESSION_XZ +.Dv ARCHIVE_FILTER_XZ +.It Dv ARCHIVE_COMPRESSION_UU +.Dv ARCHIVE_FILTER_UU +.It Dv ARCHIVE_COMPRESSION_RPM +.Dv ARCHIVE_FILTER_RPM +.It Dv ARCHIVE_COMPRESSION_LZIP +.Dv ARCHIVE_FILTER_LZIP +.\" +.It Dv ARCHIVE_BYTES_PER_RECORD +.Li 512 +.It Dv ARCHIVE_DEFAULT_BYTES_PER_BLOCK +.Li 10240 +.El +.Sh SEE ALSO +.Xr archive_read 3 , +.Xr archive_read_filter 3 , +.Xr archive_read_format 3 , +.Xr archive_read_set_options 3 , +.Xr archive_util 3 , +.Xr archive_write 3 , +.Xr archive_write_filter 3 , +.Xr archive_write_format 3 , +.Xr archive_write_set_options 3 , +.Xr libarchive 3 diff --git a/static/netbsd/man3/libarchive_internals.3 b/static/netbsd/man3/libarchive_internals.3 new file mode 100644 index 00000000..2978b48c --- /dev/null +++ b/static/netbsd/man3/libarchive_internals.3 @@ -0,0 +1,363 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 26, 2011 +.Dt LIBARCHIVE_INTERNALS 3 +.Os +.Sh NAME +.Nm libarchive_internals +.Nd description of libarchive internal interfaces +.Sh OVERVIEW +The +.Nm libarchive +library provides a flexible interface for reading and writing +streaming archive files such as tar and cpio. +Internally, it follows a modular layered design that should +make it easy to add new archive and compression formats. +.Sh GENERAL ARCHITECTURE +Externally, libarchive exposes most operations through an +opaque, object-style interface. +The +.Xr archive_entry 3 +objects store information about a single filesystem object. +The rest of the library provides facilities to write +.Xr archive_entry 3 +objects to archive files, +read them from archive files, +and write them to disk. +(There are plans to add a facility to read +.Xr archive_entry 3 +objects from disk as well.) +.Pp +The read and write APIs each have four layers: a public API +layer, a format layer that understands the archive file format, +a compression layer, and an I/O layer. +The I/O layer is completely exposed to clients who can replace +it entirely with their own functions. +.Pp +In order to provide as much consistency as possible for clients, +some public functions are virtualized. +Eventually, it should be possible for clients to open +an archive or disk writer, and then use a single set of +code to select and write entries, regardless of the target. +.Sh READ ARCHITECTURE +From the outside, clients use the +.Xr archive_read 3 +API to manipulate an +.Nm archive +object to read entries and bodies from an archive stream. +Internally, the +.Nm archive +object is cast to an +.Nm archive_read +object, which holds all read-specific data. +The API has four layers: +The lowest layer is the I/O layer. +This layer can be overridden by clients, but most clients use +the packaged I/O callbacks provided, for example, by +.Xr archive_read_open_memory 3 , +and +.Xr archive_read_open_fd 3 . +The compression layer calls the I/O layer to +read bytes and decompresses them for the format layer. +The format layer unpacks a stream of uncompressed bytes and +creates +.Nm archive_entry +objects from the incoming data. +The API layer tracks overall state +(for example, it prevents clients from reading data before reading a header) +and invokes the format and compression layer operations +through registered function pointers. +In particular, the API layer drives the format-detection process: +When opening the archive, it reads an initial block of data +and offers it to each registered compression handler. +The one with the highest bid is initialized with the first block. +Similarly, the format handlers are polled to see which handler +is the best for each archive. +(Prior to 2.4.0, the format bidders were invoked for each +entry, but this design hindered error recovery.) +.Ss I/O Layer and Client Callbacks +The read API goes to some lengths to be nice to clients. +As a result, there are few restrictions on the behavior of +the client callbacks. +.Pp +The client read callback is expected to provide a block +of data on each call. +A zero-length return does indicate end of file, but otherwise +blocks may be as small as one byte or as large as the entire file. +In particular, blocks may be of different sizes. +.Pp +The client skip callback returns the number of bytes actually +skipped, which may be much smaller than the skip requested. +The only requirement is that the skip not be larger. +In particular, clients are allowed to return zero for any +skip that they don't want to handle. +The skip callback must never be invoked with a negative value. +.Pp +Keep in mind that not all clients are reading from disk: +clients reading from networks may provide different-sized +blocks on every request and cannot skip at all; +advanced clients may use +.Xr mmap 2 +to read the entire file into memory at once and return the +entire file to libarchive as a single block; +other clients may begin asynchronous I/O operations for the +next block on each request. +.Ss Decompression Layer +The decompression layer not only handles decompression, +it also buffers data so that the format handlers see a +much nicer I/O model. +The decompression API is a two stage peek/consume model. +A read_ahead request specifies a minimum read amount; +the decompression layer must provide a pointer to at least +that much data. +If more data is immediately available, it should return more: +the format layer handles bulk data reads by asking for a minimum +of one byte and then copying as much data as is available. +.Pp +A subsequent call to the +.Fn consume +function advances the read pointer. +Note that data returned from a +.Fn read_ahead +call is guaranteed to remain in place until +the next call to +.Fn read_ahead . +Intervening calls to +.Fn consume +should not cause the data to move. +.Pp +Skip requests must always be handled exactly. +Decompression handlers that cannot seek forward should +not register a skip handler; +the API layer fills in a generic skip handler that reads and discards data. +.Pp +A decompression handler has a specific lifecycle: +.Bl -tag -compact -width indent +.It Registration/Configuration +When the client invokes the public support function, +the decompression handler invokes the internal +.Fn __archive_read_register_compression +function to provide bid and initialization functions. +This function returns +.Cm NULL +on error or else a pointer to a +.Cm struct decompressor_t . +This structure contains a +.Va void * config +slot that can be used for storing any customization information. +.It Bid +The bid function is invoked with a pointer and size of a block of data. +The decompressor can access its config data +through the +.Va decompressor +element of the +.Cm archive_read +object. +The bid function is otherwise stateless. +In particular, it must not perform any I/O operations. +.Pp +The value returned by the bid function indicates its suitability +for handling this data stream. +A bid of zero will ensure that this decompressor is never invoked. +Return zero if magic number checks fail. +Otherwise, your initial implementation should return the number of bits +actually checked. +For example, if you verify two full bytes and three bits of another +byte, bid 19. +Note that the initial block may be very short; +be careful to only inspect the data you are given. +(The current decompressors require two bytes for correct bidding.) +.It Initialize +The winning bidder will have its init function called. +This function should initialize the remaining slots of the +.Va struct decompressor_t +object pointed to by the +.Va decompressor +element of the +.Va archive_read +object. +In particular, it should allocate any working data it needs +in the +.Va data +slot of that structure. +The init function is called with the block of data that +was used for tasting. +At this point, the decompressor is responsible for all I/O +requests to the client callbacks. +The decompressor is free to read more data as and when +necessary. +.It Satisfy I/O requests +The format handler will invoke the +.Va read_ahead , +.Va consume , +and +.Va skip +functions as needed. +.It Finish +The finish method is called only once when the archive is closed. +It should release anything stored in the +.Va data +and +.Va config +slots of the +.Va decompressor +object. +It should not invoke the client close callback. +.El +.Ss Format Layer +The read formats have a similar lifecycle to the decompression handlers: +.Bl -tag -compact -width indent +.It Registration +Allocate your private data and initialize your pointers. +.It Bid +Formats bid by invoking the +.Fn read_ahead +decompression method but not calling the +.Fn consume +method. +This allows each bidder to look ahead in the input stream. +Bidders should not look further ahead than necessary, as long +look aheads put pressure on the decompression layer to buffer +lots of data. +Most formats only require a few hundred bytes of look ahead; +look aheads of a few kilobytes are reasonable. +(The ISO9660 reader sometimes looks ahead by 48k, which +should be considered an upper limit.) +.It Read header +The header read is usually the most complex part of any format. +There are a few strategies worth mentioning: +For formats such as tar or cpio, reading and parsing the header is +straightforward since headers alternate with data. +For formats that store all header data at the beginning of the file, +the first header read request may have to read all headers into +memory and store that data, sorted by the location of the file +data. +Subsequent header read requests will skip forward to the +beginning of the file data and return the corresponding header. +.It Read Data +The read data interface supports sparse files; this requires that +each call return a block of data specifying the file offset and +size. +This may require you to carefully track the location so that you +can return accurate file offsets for each read. +Remember that the decompressor will return as much data as it has. +Generally, you will want to request one byte, +examine the return value to see how much data is available, and +possibly trim that to the amount you can use. +You should invoke consume for each block just before you return it. +.It Skip All Data +The skip data call should skip over all file data and trailing padding. +This is called automatically by the API layer just before each +header read. +It is also called in response to the client calling the public +.Fn data_skip +function. +.It Cleanup +On cleanup, the format should release all of its allocated memory. +.El +.Ss API Layer +XXX to do XXX +.Sh WRITE ARCHITECTURE +The write API has a similar set of four layers: +an API layer, a format layer, a compression layer, and an I/O layer. +The registration here is much simpler because only +one format and one compression can be registered at a time. +.Ss I/O Layer and Client Callbacks +XXX To be written XXX +.Ss Compression Layer +XXX To be written XXX +.Ss Format Layer +XXX To be written XXX +.Ss API Layer +XXX To be written XXX +.Sh WRITE_DISK ARCHITECTURE +The write_disk API is intended to look just like the write API +to clients. +Since it does not handle multiple formats or compression, it +is not layered internally. +.Sh GENERAL SERVICES +The +.Nm archive_read , +.Nm archive_write , +and +.Nm archive_write_disk +objects all contain an initial +.Nm archive +object which provides common support for a set of standard services. +(Recall that ANSI/ISO C90 guarantees that you can cast freely between +a pointer to a structure and a pointer to the first element of that +structure.) +The +.Nm archive +object has a magic value that indicates which API this object +is associated with, +slots for storing error information, +and function pointers for virtualized API functions. +.Sh MISCELLANEOUS NOTES +Connecting existing archiving libraries into libarchive is generally +quite difficult. +In particular, many existing libraries strongly assume that you +are reading from a file; they seek forwards and backwards as necessary +to locate various pieces of information. +In contrast, libarchive never seeks backwards in its input, which +sometimes requires very different approaches. +.Pp +For example, libarchive's ISO9660 support operates very differently +from most ISO9660 readers. +The libarchive support utilizes a work-queue design that +keeps a list of known entries sorted by their location in the input. +Whenever libarchive's ISO9660 implementation is asked for the next +header, checks this list to find the next item on the disk. +Directories are parsed when they are encountered and new +items are added to the list. +This design relies heavily on the ISO9660 image being optimized so that +directories always occur earlier on the disk than the files they +describe. +.Pp +Depending on the specific format, such approaches may not be possible. +The ZIP format specification, for example, allows archivers to store +key information only at the end of the file. +In theory, it is possible to create ZIP archives that cannot +be read without seeking. +Fortunately, such archives are very rare, and libarchive can read +most ZIP archives, though it cannot always extract as much information +as a dedicated ZIP program. +.Sh SEE ALSO +.Xr archive_entry 3 , +.Xr archive_read 3 , +.Xr archive_write 3 , +.Xr archive_write_disk 3 , +.Xr libarchive 3 +.Sh HISTORY +The +.Nm libarchive +library first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm libarchive +library was written by +.An Tim Kientzle Aq kientzle@acm.org . diff --git a/static/netbsd/man3/libblocklist.3 b/static/netbsd/man3/libblocklist.3 new file mode 100644 index 00000000..7a016625 --- /dev/null +++ b/static/netbsd/man3/libblocklist.3 @@ -0,0 +1,177 @@ +.\" $NetBSD: libblocklist.3,v 1.7 2025/02/05 20:14:30 christos Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 5, 2025 +.Dt LIBBLOCKLIST 3 +.Os +.Sh NAME +.Nm blocklist_open , +.Nm blocklist_open2 , +.Nm blocklist_close , +.Nm blocklist_r , +.Nm blocklist , +.Nm blocklist_sa , +.Nm blocklist_sa_r +.Nd Blocklistd notification library +.Sh LIBRARY +.Lb libblocklist +.Sh SYNOPSIS +.In blocklist.h +.Ft struct blocklist * +.Fn blocklist_open "void" +.Ft struct blocklist * +.Fn blocklist_open2 "void (*logger)(int, struct syslog_data *, va_list)" +.Ft void +.Fn blocklist_close "struct blocklist *cookie" +.Ft int +.Fn blocklist "int action" "int fd" "const char *msg" +.Ft int +.Fn blocklist_r "struct blocklist *cookie" "int action" "int fd" "const char *msg" +.Ft int +.Fn blocklist_sa "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" +.Ft int +.Fn blocklist_sa_r "struct blocklist *cookie" "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" +.Sh DESCRIPTION +These functions can be used by daemons to notify +.Xr blocklistd 8 +about successful and failed remote connections so that blocklistd can +block or release port access to prevent Denial of Service attacks. +.Pp +The function +.Fn blocklist_open +creates the necessary state to communicate with +.Xr blocklistd 8 +and returns a pointer to it, or +.Dv NULL +on failure. +.Pp +The function +.Fn blocklist_open2 +is similar to +.Fn blocklist_open +but allows a +.Fa logger +to be specified. +If the +.Fa logger +is +.Dv NULL , +then no logging is performed. +.Pp +The +.Fn blocklist_close +function frees all memory and resources used. +.Pp +The +.Fn blocklist +function sends a message to +.Xr blocklistd 8 , +with an integer +.Ar action +argument specifying the type of notification, +a file descriptor +.Ar fd +specifying the accepted file descriptor connected to the client, +and an optional message in the +.Ar msg +argument. +.Pp +The +.Ar action +parameter can take these values: +.Bl -tag -width ".Dv BLOCKLIST_ABUSIVE_BEHAVIOR" +.It Va BLOCKLIST_BAD_USER +The sending daemon has determined the username presented for +authentication is invalid. +This is considered as one failure count. +.It Va BLOCKLIST_AUTH_FAIL +There was an unsuccessful authentication attempt. +This is considered as two failure counts together. +.It Va BLOCKLIST_ABUSIVE_BEHAVIOR +The sending daemon has detected abusive behavior from the remote system. +This is considered as a total immediate failure. +The remote address will be blocked as soon as possible. +.It Va BLOCKLIST_AUTH_OK +A valid user successfully authenticated. +Any entry for the remote address will be removed as soon as possible. +.El +.Pp +The +.Fn blocklist_r +function is more efficient because it keeps the blocklist state around. +.Pp +The +.Fn blocklist_sa +and +.Fn blocklist_sa_r +functions can be used with unconnected sockets, where +.Xr getpeername 2 +will not work, the server will pass the peer name in the message. +.Pp +In all cases the file descriptor passed in the +.Fa fd +argument must be pointing to a valid socket so that +.Xr blocklistd 8 +can establish ownership of the local endpoint +using +.Xr getsockname 2 . +.Pp +By default, +.Xr syslogd 8 +is used for message logging. +The internal +.Fn bl_create +function can be used to create the required internal +state and specify a custom logging function. +.Sh RETURN VALUES +The function +.Fn blocklist_open +returns a cookie on success and +.Dv NULL +on failure setting +.Dv errno +to an appropriate value. +.Pp +The functions +.Fn blocklist , +.Fn blocklist_sa , +and +.Fn blocklist_sa_r +return +.Dv 0 +on success and +.Dv \-1 +on failure setting +.Dv errno +to an appropriate value. +.Sh SEE ALSO +.Xr blocklistd.conf 5 , +.Xr blocklistd 8 +.Sh AUTHORS +.An Christos Zoulas diff --git a/static/netbsd/man3/libbozohttpd.3 b/static/netbsd/man3/libbozohttpd.3 new file mode 100644 index 00000000..9a8e8e97 --- /dev/null +++ b/static/netbsd/man3/libbozohttpd.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: libbozohttpd.3,v 1.7 2024/02/04 05:43:05 mrg Exp $ +.\" +.\" $eterna: libbozohttpd.3,v 1.2 2010/05/10 02:48:23 mrg Exp $ +.\" +.\" Copyright (c) 2009, 2021 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This manual page is derived from software contributed to The +.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 11, 2021 +.Dt LIBBOZOHTTPD 3 +.Os +.Sh NAME +.Nm libbozohttpd +.Nd embedded web server library +.Sh LIBRARY +.Lb libbozohttpd +.Sh SYNOPSIS +.In bozohttpd.h +.Ft int +.Fo bozo_set_pref +.Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs" "char *name" "char *value" +.Fc +.Ft char * +.Fo bozo_get_pref +.Fa "bozoprefs_t *prefs" "char *name" +.Fc +.Ft int +.Fo bozo_set_defaults +.Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs" +.Fc +.Ft void +.Fo bozo_setup +.Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs" "const char *vhost" "char *slash" +.Fc +.Ft bozo_httpreq_t * +.Fo bozo_read_request +.Fa "bozohttpd_t *httpd" +.Fc +.Ft void +.Fo bozo_process_request +.Fa "bozo_httpreq_t *" +.Fc +.Ft void +.Fo bozo_clean_request +.Fa "bozo_httpreq_t *" +.Fc +.Ft void +.Fo bozo_cleanup +.Fa "bozohttpd_t *httpd" "bozoprefs_t *prefs" +.Fc +.Sh DESCRIPTION +.Nm +is a library interface to the +.Xr bozohttpd 8 +web server. +The +.Nm +library can be used to embed a webserver +in your applications. +.Pp +Normal operation sees the +.Nm +process be initialised using the +.Fn bozo_set_defaults +function, which will set up the default port +and other internal settings, allocating +any necessary space as needed. +The +.Fn bozo_set_defaults +function returns 1 on sucess, 0 on failure. +.Pp +The +.Fn bozo_setup +function is used to specify the virtual host name +for the web server. +A NULL host name will mean that +.Nm +will use the local value for the host name, +as returned by +.Xr gethostname 3 . +This virtual hostname should be a fully qualified domain name. +The final argument to +.Fn bozo_setup +is the name of the directory to serve as the root +directory of the web server tree. +.Pp +Once the server has been set up, it serves +requests by using the +.Fn bozo_read_request +function, which returns a pointer to a request structure, +and +.Fn bozo_process_request , +which deals with the request, and answers the client. +The request space is de-allocated +using the +.Fn bozo_clean_request +function. +.Pp +Preferences are set +using the function +.Fn bozo_set_pref +function +and queried using the two +.Fn bozo_get_pref +function. +This is the main interface for selecting options, and for +setting preferences. +The memory allocated by +.Fn bozo_setup +for both the httpd structure and the preferences will be freed. +.Sh SEE ALSO +.Xr gethostname 3 , +.Xr ssl 3 , +.Xr services 5 , +.Xr httpd 8 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Matthew R. Green Aq Mt mrg@eterna23.net +.An Alistair Crooks Aq Mt agc@NetBSD.org +wrote this high-level interface. +.Pp +This manual page was written by +.An Alistair Crooks . diff --git a/static/netbsd/man3/libiscsi.3 b/static/netbsd/man3/libiscsi.3 new file mode 100644 index 00000000..8035274d --- /dev/null +++ b/static/netbsd/man3/libiscsi.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: libiscsi.3,v 1.8 2014/03/18 18:20:36 riastradh Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This manual page is derived from software contributed to The +.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 19, 2011 +.Dt LIBISCSI 3 +.Os +.Sh NAME +.Nm libiscsi +.Nd iSCSI network storage protocol implementation +.Sh LIBRARY +.Lb libiscsi +.Sh SYNOPSIS +.In iscsi.h +.Ft int +.Fo iscsi_target_set_defaults +.Fa "iscsi_target_t *target" +.Fc +.Ft int +.Fo iscsi_target_start +.Fa "iscsi_target_t *target" +.Fc +.Ft int +.Fo iscsi_target_listen +.Fa "iscsi_target_t *target" +.Fc +.Ft int +.Fo iscsi_target_shutdown +.Fa "iscsi_target_t *target" +.Fc +.Ft void +.Fo iscsi_target_write_pidfile +.Fa "const char *filename" +.Fc +.Ft int +.Fo iscsi_target_setvar +.Fa "iscsi_target_t *target" "const char *name" "const char *value" +.Fc +.Ft char * +.Fo iscsi_target_getvar +.Fa "iscsi_target_t *target" "const char *name" +.Fc +.Ft int +.Fo iscsi_initiator_set_defaults +.Fa "iscsi_initiator_t *initiator" +.Fc +.Ft int +.Fo iscsi_initiator_start +.Fa "iscsi_initiator_t *initiator" +.Fc +.Ft int +.Fo iscsi_initiator_discover +.Fa "iscsi_initiator_t *initiator" "char *x" "uint64_t a" "int b" +.Fc +.Ft int +.Fo iscsi_initiator_shutdown +.Fa "iscsi_initiator_t *initiator" +.Fc +.Ft int +.Fo iscsi_initiator_setvar +.Fa "iscsi_initiator_t *initiator" "const char *name" "const char *value" +.Fc +.Ft char * +.Fo iscsi_initiator_getvar +.Fa "iscsi_initiator_t *initiator" "const char *name" +.Fc +.Sh DESCRIPTION +.Nm +is a library interface to the iSCSI target and initiator. +This conforms to IETF RFC 3720. +The corresponding command line utilities for +.Nm +are +.Xr iscsi-initiator 8 +and +.Xr iscsi-target 8 . +.Pp +In normal operation, a process acting as +a target (i.e. presenting storage to the network) +will call +.Fn iscsi_target_set_defaults +and will then set various values using the +.Fn iscsi_target_setvar +function. +The value of a variable can be retrieved +at any time using the +.Fn iscsi_target_getvar +function. +When all of the variables have been set, +the +.Fn iscsi_target_start +function is called, and the block storage will be +served up by the process. +.Pp +A useful illustration of the use of these functions +can be found in the source code to the +.Xr iscsi-target 8 +utility. +.Pp +The +.Nm +library also provides an implementation of the client +end of the iSCSI subsystem, which is known as the +initiator. +The process acting as an initiator will first call the +.Fn iscsi_initiator_set_defaults +function, to set default values for the initiator variables. +Once all the values have been set to the user preferences +using the +.Fn iscsi_initiator_setvar +function, then the +.Fn iscsi_initiator_start +function is called. +.Pp +The +.Nm +library can be used to perform iSCSI device discovery +by calling the +.Fn iscsi_initiator_discovery +function. +This will return a list of all the iSCSI targets which +are serving up block storage according to the variables +which have already been set. +.Sh SEE ALSO +.Xr iscsi-initiator 8 , +.Xr iscsi-target 8 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 4.0 . +This programmatic interface to the +iSCSI subsystem +first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org . diff --git a/static/netbsd/man3/libmagic.3 b/static/netbsd/man3/libmagic.3 new file mode 100644 index 00000000..d097eb88 --- /dev/null +++ b/static/netbsd/man3/libmagic.3 @@ -0,0 +1,439 @@ +.\" $NetBSD: libmagic.3,v 1.21 2023/08/18 19:00:10 christos Exp $ +.\" +.\" $File: libmagic.man,v 1.49 2023/07/20 14:32:07 christos Exp $ +.\" +.\" Copyright (c) Christos Zoulas 2003, 2018, 2022 +.\" All Rights Reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice immediately at the beginning of the file, without modification, +.\" this list of conditions, and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 16, 2023 +.Dt LIBMAGIC 3 +.Os +.Sh NAME +.Nm magic_open , +.Nm magic_close , +.Nm magic_error , +.Nm magic_errno , +.Nm magic_descriptor , +.Nm magic_file , +.Nm magic_buffer , +.Nm magic_getflags , +.Nm magic_setflags , +.Nm magic_check , +.Nm magic_compile , +.Nm magic_list , +.Nm magic_load , +.Nm magic_load_buffers , +.Nm magic_setparam , +.Nm magic_getparam , +.Nm magic_version +.Nd Magic number recognition library +.Sh LIBRARY +.Lb libmagic +.Sh SYNOPSIS +.In magic.h +.Ft magic_t +.Fn magic_open "int flags" +.Ft void +.Fn magic_close "magic_t cookie" +.Ft const char * +.Fn magic_error "magic_t cookie" +.Ft int +.Fn magic_errno "magic_t cookie" +.Ft const char * +.Fn magic_descriptor "magic_t cookie" "int fd" +.Ft const char * +.Fn magic_file "magic_t cookie" "const char *filename" +.Ft const char * +.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length" +.Ft int +.Fn magic_getflags "magic_t cookie" +.Ft int +.Fn magic_setflags "magic_t cookie" "int flags" +.Ft int +.Fn magic_check "magic_t cookie" "const char *filename" +.Ft int +.Fn magic_compile "magic_t cookie" "const char *filename" +.Ft int +.Fn magic_list "magic_t cookie" "const char *filename" +.Ft int +.Fn magic_load "magic_t cookie" "const char *filename" +.Ft int +.Fn magic_load_buffers "magic_t cookie" "void **buffers" "size_t *sizes" "size_t nbuffers" +.Ft int +.Fn magic_getparam "magic_t cookie" "int param" "void *value" +.Ft int +.Fn magic_setparam "magic_t cookie" "int param" "const void *value" +.Ft int +.Fn magic_version "void" +.Ft const char * +.Fn magic_getpath "const char *magicfile" "int action" +.Sh DESCRIPTION +These functions +operate on the magic database file +which is described +in +.Xr magic 5 . +.Pp +The function +.Fn magic_open +creates a magic cookie pointer and returns it. +It returns +.Dv NULL +if there was an error allocating the magic cookie. +The +.Ar flags +argument specifies how the other magic functions should behave: +.Bl -tag -width MAGIC_COMPRESS +.It Dv MAGIC_NONE +No special handling. +.It Dv MAGIC_DEBUG +Print debugging messages to stderr. +.It Dv MAGIC_SYMLINK +If the file queried is a symlink, follow it. +.It Dv MAGIC_COMPRESS +If the file is compressed, unpack it and look at the contents. +.It Dv MAGIC_DEVICES +If the file is a block or character special device, then open the device +and try to look in its contents. +.It Dv MAGIC_MIME_TYPE +Return a MIME type string, instead of a textual description. +.It Dv MAGIC_MIME_ENCODING +Return a MIME encoding, instead of a textual description. +.It Dv MAGIC_MIME +A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING. +.It Dv MAGIC_CONTINUE +Return all matches, not just the first. +.It Dv MAGIC_CHECK +Check the magic database for consistency and print warnings to stderr. +.It Dv MAGIC_PRESERVE_ATIME +On systems that support +.Xr utime 3 +or +.Xr utimes 2 , +attempt to preserve the access time of files analysed. +.It Dv MAGIC_RAW +Don't translate unprintable characters to a \eooo octal representation. +.It Dv MAGIC_ERROR +Treat operating system errors while trying to open files and follow symlinks +as real errors, instead of printing them in the magic buffer. +.It Dv MAGIC_APPLE +Return the Apple creator and type. +.It Dv MAGIC_EXTENSION +Return a slash-separated list of extensions for this file type. +.It Dv MAGIC_COMPRESS_TRANSP +Don't report on compression, only report about the uncompressed data. +.It Dv MAGIC_NO_CHECK_APPTYPE +Don't check for +.Dv EMX +application type (only on EMX). +.It Dv MAGIC_NO_COMPRESS_FORK +Don't allow decompressors that use fork. +.It Dv MAGIC_NO_CHECK_CDF +Don't get extra information on MS Composite Document Files. +.It Dv MAGIC_NO_CHECK_COMPRESS +Don't look inside compressed files. +.It Dv MAGIC_NO_CHECK_ELF +Don't print ELF details. +.It Dv MAGIC_NO_CHECK_ENCODING +Don't check text encodings. +.It Dv MAGIC_NO_CHECK_SOFT +Don't consult magic files. +.It Dv MAGIC_NO_CHECK_TAR +Don't examine tar files. +.It Dv MAGIC_NO_CHECK_TEXT +Don't check for various types of text files. +.It Dv MAGIC_NO_CHECK_TOKENS +Don't look for known tokens inside ascii files. +.It Dv MAGIC_NO_CHECK_JSON +Don't examine JSON files. +.It Dv MAGIC_NO_CHECK_CSV +Don't examine CSV files. +.It Dv MAGIC_NO_CHECK_SIMH +Don't examine SIMH tape files. +.El +.Pp +The +.Fn magic_close +function closes the +.Xr magic 5 +database and deallocates any resources used. +.Pp +The +.Fn magic_error +function returns a textual explanation of the last error, or +.Dv NULL +if there was no error. +.Pp +The +.Fn magic_errno +function returns the last operating system error number +.Pq Xr errno 2 +that was encountered by a system call. +.Pp +The +.Fn magic_file +function returns a textual description of the contents of the +.Ar filename +argument, or +.Dv NULL +if an error occurred. +If the +.Ar filename +is +.Dv NULL , +then stdin is used. +.Pp +The +.Fn magic_descriptor +function returns a textual description of the contents of the +.Ar fd +argument, or +.Dv NULL +if an error occurred. +.Pp +The +.Fn magic_buffer +function returns a textual description of the contents of the +.Ar buffer +argument with +.Ar length +bytes size. +.Pp +The +.Fn magic_getflags +functions returns a value representing current +.Ar flags +set. +.Pp +The +.Fn magic_setflags +function sets the +.Ar flags +described above. +Note that using both MIME flags together can also +return extra information on the charset. +.Pp +The +.Fn magic_check +function can be used to check the validity of entries in the colon +separated database files passed in as +.Ar filename , +or +.Dv NULL +for the default database. +It returns 0 on success and \-1 on failure. +.Pp +The +.Fn magic_compile +function can be used to compile the colon +separated list of database files passed in as +.Ar filename , +or +.Dv NULL +for the default database. +It returns 0 on success and \-1 on failure. +The compiled files created are named from the +.Xr basename 1 +of each file argument with +.Dq .mgc +appended to it. +.Pp +The +.Fn magic_list +function dumps all magic entries in a human readable format, +dumping first the entries that are matched against binary files and then the +ones that match text files. +It takes and optional +.Fa filename +argument which is a colon separated list of database files, or +.Dv NULL +for the default database. +.Pp +The +.Fn magic_load +function must be used to load the colon +separated list of database files passed in as +.Ar filename , +or +.Dv NULL +for the default database file before any magic queries can performed. +.Pp +The default database file is named by the MAGIC environment variable. +If that variable is not set, the default database file name is +.Pa /usr/share/misc/magic . +.Fn magic_load +adds +.Dq .mgc +to the database filename as appropriate. +.Pp +The +.Fn magic_load_buffers +function takes an array of size +.Fa nbuffers +of +.Fa buffers +with a respective size for each in the array of +.Fa sizes +loaded with the contents of the magic databases from the filesystem. +This function can be used in environment where the magic library does +not have direct access to the filesystem, but can access the magic +database via shared memory or other IPC means. +.Pp +The +.Fn magic_getparam +and +.Fn magic_setparam +allow getting and setting various limits related to the magic +library. +.Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent +.It Sy "Parameter" Ta Sy "Type" Ta Sy "Default" +.It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15 +.It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30 +.It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256 +.It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128 +.It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768 +.It Li MAGIC_PARAM_REGEX_MAX Ta size_t Ta 8192 +.It Li MAGIC_PARAM_BYTES_MAX Ta size_t Ta 1048576 +.El +.Pp +The +.Dv MAGIC_PARAM_INDIR_RECURSION +parameter controls how many levels of recursion will be followed for +indirect magic entries. +.Pp +The +.Dv MAGIC_PARAM_NAME_RECURSION +parameter controls how many levels of recursion will be followed for +for name/use calls. +.Pp +The +.Dv MAGIC_PARAM_NAME_MAX +parameter controls the maximum number of calls for name/use. +.Pp +The +.Dv MAGIC_PARAM_NOTES_MAX +parameter controls how many ELF notes will be processed. +.Pp +The +.Dv MAGIC_PARAM_PHNUM_MAX +parameter controls how many ELF program sections will be processed. +.Pp +The +.Dv MAGIC_PARAM_SHNUM_MAX +parameter controls how many ELF sections will be processed. +.Pp +The +.Fn magic_version +command returns the version number of this library which is compiled into +the shared library using the constant +.Dv MAGIC_VERSION +from +.In magic.h . +This can be used by client programs to verify that the version they compile +against is the same as the version that they run against. +.Pp +The +.Fn magic_getpath +command returns the colon separated list of magic database locations. +If the +.Fa filename +is non-NULL, then it is returned. +Otherwise, if the +.Dv MAGIC +environment variable is defined, then it is returned. +Otherwise, if +.Fa action +is 0 (meaning "file load"), then any user-specific magic database file is included. +Otherwise, only the system default magic database path is included. +.Sh RETURN VALUES +The function +.Fn magic_open +returns a magic cookie on success and +.Dv NULL +on failure setting errno to an appropriate value. +It will set errno to +.Er EINVAL +if an unsupported value for flags was given. +The +.Fn magic_list , +.Fn magic_load , +.Fn magic_compile , +and +.Fn magic_check +functions return 0 on success and \-1 on failure. +The +.Fn magic_buffer , +.Fn magic_getpath , +and +.Fn magic_file , +functions return a string on success and +.Dv NULL +on failure. +The +.Fn magic_error +function returns a textual description of the errors of the above +functions, or +.Dv NULL +if there was no error. +The +.Fn magic_version +always returns the version number of the library. +Finally, +.Fn magic_setflags +returns \-1 on systems that don't support +.Xr utime 3 , +or +.Xr utimes 2 +when +.Dv MAGIC_PRESERVE_ATIME +is set. +.Sh FILES +.Bl -tag -width /usr/share/misc/magic.mgc -compact +.It Pa /usr/share/misc/magic +The non-compiled default magic database. +.It Pa /usr/share/misc/magic.mgc +The compiled default magic database. +.El +.Sh SEE ALSO +.Xr file 1 , +.Xr magic 5 +.Sh BUGS +The results from +.Fn magic_buffer +and +.Fn magic_file +where the buffer and the file contain the same data +can produce different results, because in the +.Fn magic_file +case, the program can +.Xr lseek 2 +and +.Xr stat 2 +the file descriptor. +.Sh AUTHORS +.An M\(oans Rullg\(oard +Initial libmagic implementation, and configuration. +.An Christos Zoulas +API cleanup, error code and allocation handling. diff --git a/static/netbsd/man3/libmj.3 b/static/netbsd/man3/libmj.3 new file mode 100644 index 00000000..cd883eb5 --- /dev/null +++ b/static/netbsd/man3/libmj.3 @@ -0,0 +1,283 @@ +.\" $NetBSD: libmj.3,v 1.10 2018/11/13 14:52:30 mlelstv Exp $ +.\" +.\" Copyright (c) 2010 Alistair Crooks +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 3, 2018 +.Dt LIBMJ 3 +.Os +.Sh NAME +.Nm libmj +.Nd minimalist JSON lightweight data interchange library +.Sh LIBRARY +.Lb libmj +.Sh SYNOPSIS +.In mj.h +.Ft int +.Fo mj_create +.Fa "mj_t *atom" "const char *text" "..." +.Fc +.Ft int +.Fo mj_parse +.Fa "mj_t *atom" "const char *text" "int *tokfrom" "int *tokto" "int *toktype" +.Fc +.Ft int +.Fo mj_append +.Fa "mj_t *atom" "const char *text" "..." +.Fc +.Ft int +.Fo mj_append_field +.Fa "mj_t *atom" "const char *fieldname" "const char *text" "..." +.Fc +.Ft int +.Fo mj_deepcopy +.Fa "mj_t *dest" "mj_t *src" +.Fc +.Ft void +.Fo mj_delete +.Fa "mj_t *atom" +.Fc +.Pp +Access to objects and array entries is made using the following functions: +.Ft int +.Fo mj_arraycount +.Fa "mj_t *atom" +.Fc +.Ft int +.Fo mj_object_find +.Fa "mj_t *atom" "const char *name" "const unsigned startpoint" +.Fa "const unsigned incr" +.Fc +.Ft mj_t * +.Fo mj_get_atom +.Fa "mj_t *atom" "..." +.Fc +.Pp +JSON object output functions: +.Ft int +.Fo mj_snprint +.Fa "char *buffer" "size_t size" "mj_t *atom" +.Fc +.Ft int +.Fo mj_asprint +.Fa "char **buffer" "mj_t *atom" +.Fc +.Ft int +.Fo mj_string_size +.Fa "mj_t *atom" +.Fc +.Ft int +.Fo mj_pretty +.Fa "mj_t *atom" "void *stream" "unsigned depth" "const char *trailer" +.Fc +.Ft const char * +.Fo mj_string_rep +.Fa "mj_t *atom" +.Fc +.Sh DESCRIPTION +.Nm +is a small library interface to allow JSON text to be created and parsed. +JSON is the Java Script Object Notation, +a lightweight data-interchange format, standardised by the ECMA. +The library name +.Nm +is derived from a further acronym of +.Dq minimalist JSON . +.\" Hey, Mary! +.Pp +The +.Nm +library can be used to create a string in memory which contains a textual +representation of a number of objects, arbitrarily structured. +The library can also be used to reconstruct the structure. +Data can thus be serialised easily and efficiently, and data structures +rebuilt to produce the original structure of the data. +.Pp +JSON contains basic units called atoms, the two +basic atoms being strings and numbers. +Three other useful atomic values are provided: +.Dq null , +.Dq false , +and +.Dq true . +Atoms can be grouped together as key/value pairs in an +.Dq object , +and as individual, ordered atoms, in an +.Dq array . +.Pp +To create a new object, the +.Fn mj_create +function is used. +It can be deleted using the +.Fn mj_delete +function. +.Pp +Atoms, objects and arrays can be appended +to arrays and objects using the +.Fn mj_append +function. +.Pp +Objects can be printed out +by using the +.Fn mj_snprint +function. +The size of a string of JSON text can be calculated +using the +.Fn mj_string_size +function. +A utility function +.Fn mj_asprint +is provided which will allocate space dynamically, +using +.Xr calloc 3 , +and the JSON serialised text is copied into it. +This memory can later be de-allocated using +.Xr free 3 . +For formatted output to a +.Vt FILE * +stream, the +.Fn mj_pretty +function is used. +The calling interface gives the ability to indent the +output to a given +.Fa depth +in characters and for the formatted output to be followed by a +.Fa trailer +string, which is usually +.Dv NULL +for external calls, but can be any valid string. +Output is sent to the +.Fa stream +file stream. +.Pp +The +.Fa type +argument given to the +.Fn mj_create , +.Fn mj_append , +and +.Fn mj_append_field +functions is taken from a list of +.Dq false +.Dq true +.Dq null +.Dq number +.Dq integer +.Dq string +.Dq array +and +.Dq object +types. +An integer differs from a number in that it cannot take on +any floating point values. +It is implemented internally using a signed 64-bit integer type. +This restriction of values for an integer type may be removed at a later date. +.Pp +Within a JSON object, the key values can be iterated over using an integer +index to access the individual JSON objects. +The index can also be found using the +.Fn mj_object_find +function. +.Pp +The way objects arrays are implemented in +.Nm +is by using varying-sized arrays internally. +Objects have the field name as the even entry in this internal array, +with the value being the odd entry. +Arrays are implemented as a simple array. +Thus, to find an object in an array using +.Fn mj_object_find , +a value of 1 should be used as the increment value. +This means that every entry in the internal array will be examined, +and the first match after the starting point will be returned. +For objects, an incremental value of 2 should be used, +and an even start value should be specified. +.Pp +String values should be created and appended using two parameters in +the stdarg fields, that of the string itself, and its length in bytes +immediately after the string. +A value of +.Dv \-1 +may be used if the string length is not known. +.Sh EXAMPLES +The following code fragment will make a JSON object +out of the string +.Dq Hello \en +in the +buffer called +.Va buf +where +.Dq USER +is the name of the user taken from the runtime environment. +The encoded text will be in an allocated buffer called +.Va s . +.Bd -literal -offset indent +mj_t atom; +char buf[BUFSIZ]; +char *s; +int cc; + +(void) memset(\*[Am]atom, 0x0, sizeof(atom)); +cc = snprintf(buf, sizeof(buf), "Hello %s\en", getenv("USER")); +mj_create(\*[Am]atom, "string", buf, cc); +cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_JSON_ENCODE); +.Ed +.Pp +Next, the following example will take the (binary) text which has been encoded into +JSON and is in the buffer +.Va buf , +such as in the previous example, and re-create the original text: +.Bd -literal -offset indent +int from, to, tok, cc; +char *s; +mj_t atom; + +(void) memset(\*[Am]atom, 0x0, sizeof(atom)); +from = to = tok = 0; +mj_parse(\*[Am]atom, buf, \*[Am]from, \*[Am]to, \*[Am]tok); +cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_HUMAN); +printf("%.*s", cc, s); +.Ed +.Pp +The +.Va s +pointer points to allocated storage with the original NUL-terminated string +in it. +.Sh SEE ALSO +.Xr calloc 3 , +.Xr free 3 +.Rs +.%Q Ecma International +.%D December 2009 +.%T ECMA-262: ECMAScript Language Specification +.%U http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf +.%O 5th Edition +.Re +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org +wrote this implementation and manual page. diff --git a/static/netbsd/man3/libnetpgp.3 b/static/netbsd/man3/libnetpgp.3 new file mode 100644 index 00000000..ccbf0ba1 --- /dev/null +++ b/static/netbsd/man3/libnetpgp.3 @@ -0,0 +1,394 @@ +.\" $NetBSD: libnetpgp.3,v 1.27 2018/05/10 15:00:36 sevan Exp $ +.\" +.\" Copyright (c) 2009,2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This manual page is derived from software contributed to The +.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 10, 2018 +.Dt LIBNETPGP 3 +.Os +.Sh NAME +.Nm libnetpgp +.Nd digital signing and verification, encryption and decryption +.Sh LIBRARY +.Lb libnetpgp +.Sh SYNOPSIS +.In netpgp.h +.Pp +The following functions relate to initialisations and finalisations: +.Ft int +.Fo netpgp_init +.Fa "netpgp_t *netpgp" +.Fc +.Ft int +.Fo netpgp_end +.Fa "netpgp_t *netpgp" +.Fc +.Pp +The following functions are for debugging, reflection and information: +.Ft int +.Fo netpgp_set_debug +.Fa "const char *filename" +.Fc +.Ft int +.Fo netpgp_get_debug +.Fa "const char *filename" +.Fc +.Ft int +.Fo netpgp_get_info +.Fa "const char *type" +.Fc +.Ft int +.Fo netpgp_list_packets +.Fa "netpgp_t *netpgp" "char *filename" "int armour" "char *pubringname" +.Fc +.Pp +The following functions are for variable management: +.Ft int +.Fo netpgp_setvar +.Fa "netpgp_t *netpgp" "const char *name" "const char *value" +.Fc +.Ft char * +.Fo netpgp_getvar +.Fa "netpgp_t *netpgp" "const char *name" +.Fc +.Ft int +.Fo netpgp_incvar +.Fa "netpgp_t *netpgp" "const char *name" "const int delta" +.Fc +.Ft int +.Fo netpgp_unsetvar +.Fa "netpgp_t *netpgp" "const char *name" +.Fc +.Pp +The following function sets the home directory: +.Ft int +.Fo netpgp_set_homedir +.Fa "netpgp_t *netpgp" "char *homedir" "char *subdir" "const int quiet" +.Fc +.Pp +The following functions are used for key management: +.Ft int +.Fo netpgp_list_keys +.Fa "netpgp_t *netpgp" "const int printsigs" +.Fc +.Ft int +.Fo netpgp_list_keys_json +.Fa "netpgp_t *netpgp" "char **json" "const int psigs" +.Fc +.Ft int +.Fo netpgp_match_keys +.Fa "netpgp_t *netpgp" "char *name" "const char *fmt" "void *vp" "const int psigs" +.Fc +.Ft int +.Fo netpgp_match_keys_json +.Fa "netpgp_t *netpgp" "char **json" "char *name" "const char *fmt" "const int psigs" +.Fc +.Ft int +.Fo netpgp_match_pubkeys +.Fa "netpgp_t *netpgp" "char *name" "void *vp" +.Fc +.Ft int +.Fo netpgp_find_key +.Fa "netpgp_t *netpgp" "char *userid" +.Fc +.Ft char * +.Fo netpgp_get_key +.Fa "netpgp_t *netpgp" "const char *name" "const char *fmt" +.Fc +.Ft int +.Fo netpgp_export_key +.Fa "netpgp_t *netpgp" "char *userid" +.Fc +.Ft int +.Fo netpgp_import_key +.Fa "netpgp_t *netpgp" "char *file" +.Fc +.Ft int +.Fo netpgp_generate_key +.Fa "netpgp_t *netpgp" "char *userid" "int numbits" +.Fc +.Ft int +.Fo netpgp_validate_sigs +.Fa "netpgp_t *netpgp" +.Fc +.Ft int +.Fo netpgp_format_json +.Fa "void *vp" "const char *json" "const int psigs" +.Fc +.Pp +The following functions are used for file management: +.Ft int +.Fo netpgp_encrypt_file +.Fa "netpgp_t *netpgp" "const char *userid" "const char *filename" "char *out" +.Fa "int armored" +.Fc +.Ft int +.Fo netpgp_decrypt_file +.Fa "netpgp_t *netpgp" "const char *filename" "char *out" "int armored" +.Fc +.Ft int +.Fo netpgp_sign_file +.Fa "netpgp_t *netpgp" "const char *userid" "const char *filename" "char *out" +.Fa "int armored" "int cleartext" "int detached" +.Fc +.Ft int +.Fo netpgp_verify_file +.Fa "netpgp_t *netpgp" "const char *in" "const char *out" "int armored" +.Fc +.Pp +The following functions are used for memory signing and encryption: +.Ft int +.Fo netpgp_encrypt_memory +.Fa "netpgp_t *netpgp" "const char *userid" "void *in" "const size_t insize" +.Fa "char *out" "size_t outsize" "int armored" +.Fc +.Ft int +.Fo netpgp_decrypt_memory +.Fa "netpgp_t *netpgp" "const void *input" "const size_t insize" +.Fa "char *out" "size_t outsize" "const int armored" +.Fc +.Ft int +.Fo netpgp_sign_memory +.Fa "netpgp_t *netpgp" "const char *userid" "char *mem" +.Fa "size_t size" "char *out" "size_t outsize" +.Fa "const unsigned armored" "const unsigned cleartext" +.Fc +.Ft int +.Fo netpgp_verify_memory +.Fa "netpgp_t *netpgp" "const void *in" "const size_t insize" +.Fa "void *out" "size_t outsize" "const int armored" +.Fc +.Sh DESCRIPTION +.Nm +is a library interface to enable digital signatures to be created and +verified, and also for files and memory to be encrypted and decrypted. +Functions are also provided for management of user keys. +.Pp +The library uses functions from the openssl library for multi-precision +integer arithmetic, and for RSA and DSA key signing and verification, +encryption and decryption. +.Pp +Normal operation sees the +.Nm +process be initialised using the +.Fn netpgp_init +function, which will set up the public and private keyrings, as well as set the +user identity in the +.Ar userid +member of the +.Dv netpgp_t +structure. +These are set using the +.Fn netpgp_setvar +function and unset using the +.Fn netpgp_unsetvar +function. +If no public key ring file is set, initial values will be taken from those +in the +.Pa .gnupg/pubring.gpg +file in the user's home directory. +Similarly, if no secret key ring file is set, +initial values will be taken from those +in the +.Pa .gnupg/secring.gpg +file in the user's home directory. +The user identity is obtained from the +.Ev userid +environment variable, or failing that, the value of the +.Dq default-key +setting from +.Pa .gnupg/gpg.conf +file in the user's home directory is used. +The +.Fn netpgp_init +function returns 1 on success, 0 on failure. +.Pp +To list all the keys in a keyring, the +.Fn netpgp_list_keys +function is used. +To list all the keys in a keyring as a JSON encoded string, the +.Fn netpgp_list_keys_json +function is used. +To find and list keys in a keyring, the +.Fn netpgp_match_keys +function is used. +To find and list keys in a keyring, output as a JSON encoded string, +the +.Fn netpgp_match_keys_json +function is used. +To find and list keys in a better suited machine-readble format, such as for +redirection to other parsing engines, the +.Fn netpgp_match_pubkeys +function is used. +The signature subkey fields can also be displayed +using this function. +.Pp +The home directory is specified as an internal variable, +and its existence is checked using the +.Fn netpgp_set_homedir +function. +This function can operate in a verbose or quiet +manner, depending on the value of the argument provided. +If the subdirectory argument is provided, this subdirectory +is appended to the home directory in order to search for +the keyrings. +.Pp +To print key information from a JSON encoded string, stored in a file, the +.Fn netpgp_format_json +function is used. +.Pp +To validate the signature of keys in a public key keyring, the +.Fn netpgp_validate_sigs +function is used. +.Pp +To export a key, the +.Fn netpgp_export_key +function is used. +Output is sent to the standard output. +.Pp +To import a key onto the public keyring, the +.Fn netpgp_import_key +function is used. +The name of the file containing the key to be imported is provided +as the filename argument. +.Pp +To generate a key, the +.Fn netpgp_generate_key +function is used. +It takes an argument of the number of bits to use in the key. +At the time that this manual page was created (April 2009), +the recommendations are that the bare minimum key size +of at least 2048 bits is used, and it would be much better +to use at least 4096 or 8192 bits. +This situation should be monitored to ensure that it does +not go out of date. +.Pp +Encryption, decryption, signing and verification of +files are the lifeblood of the +.Nm +library. +To encrypt a file, the +.Fn netpgp_encrypt_file +function is used, and the +.Fn netpgp_decrypt_file +function is used to decrypt the results of the encryption. +To sign a file, the +.Fn netpgp_sign_file +function is used, and the resulting signed file can be verified +using the +.Fn netpgp_verify_file +function. +.Pp +.Fn netpgp_sign_memory +is a function which can sign an area +of memory, and +.Fn netpgp_verify_memory +verifies the digital signature produced. +.Pp +Internally, an encrypted or signed file +is made up of +.Dq packets +which hold information pertaining to the signature, +encryption method, and the data which is being protected. +This information can be displayed in a verbose manner using +the +.Fn netpgp_list_packets +function. +.Pp +The +.Fn netpgp_setvar +and +.Fn netpgp_getvar +functions are used to manage the hash algorithm that +is used with RSA signatures. +These functions are general purpose functions, and +are used to set and retrieve values for internal variables. +For example, they +can be used to set and to retrieve the +value of the user id +which has been set, +the home directory from which to find the keyrings, +the verbosity settings, and many more. +The +.Fn netpgp_incvar +function is used to add a numeric increment to the +internal variable. +This incremental value can be negative. +It is primarily used to increase the verbosity settings. +.Pp +In +.Nm +files are encrypted using the public key of the userid. +The secret key is used to decrypt the results of that encryption. +Files are signed using the secret key of the userid. +The public key is used to verify that the file was signed, +who signed the file, and the date and time at which it was signed. +.Pp +Some utility functions are also provided for debugging, and for +finding out version and maintainer information from calling programs. +These are the +.Fn netpgp_set_debug +and the +.Fn netpgp_get_debug +functions (for getting verbose debugging information on a per-source +file basis). +.Pp +The +.Fn netpgp_get_info +function returns the version or maintainer information depending upon the +.Ar type +argument. +At the present time, two types are defined: +.Dq version +and +.Dq maintainer . +The maintainer information returned contains the name, email address, +and PGP short key id. +A failure to present a known +.Ar type +argument to +.Fn netpgp_get_info +will result in the string +.Dq [unknown] +being returned. +.Sh SEE ALSO +.Xr netpgp 1 , +.Xr ssl 3 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An -nosplit +.An Ben Laurie , +.An Rachel Willmer . +.An Alistair Crooks Aq Mt agc@NetBSD.org +wrote this high-level interface. +.Pp +This manual page was written by +.An Alistair Crooks . diff --git a/static/netbsd/man3/libnetpgpbn.3 b/static/netbsd/man3/libnetpgpbn.3 new file mode 100644 index 00000000..3b263e88 --- /dev/null +++ b/static/netbsd/man3/libnetpgpbn.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: libnetpgpbn.3,v 1.6 2018/04/04 21:39:35 sevan Exp $ +.\" +.\" Copyright (c) 2010 Alistair Crooks +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 3, 2018 +.Dt LIBNETPGPBN 3 +.Os +.Sh NAME +.Nm libnetpgpbn +.Nd BIGNUM library of multi-precision integers +.Sh LIBRARY +.Lb libnetpgpbn +.Sh SYNOPSIS +.In netpgp/bn.h +.Ft BIGNUM * +.Fo BN_new +.Fa "void" +.Fc +.Ft BIGNUM * +.Fo BN_dup +.Fa "const BIGNUM *orig" +.Fc +.Ft int +.Fo BN_copy +.Fa "BIGNUM *to" "const BIGNUM *from" +.Fc +.Ft void +.Fo BN_swap +.Fa "BIGNUM *a" "BIGNUM *b" +.Fc +.Pp +.Ft void +.Fo BN_init +.Fa "BIGNUM *bn" +.Fc +.Ft void +.Fo BN_free +.Fa "BIGNUM *bn" +.Fc +.Ft void +.Fo BN_clear +.Fa "BIGNUM *bn" +.Fc +.Ft void +.Fo BN_clear_free +.Fa "BIGNUM *bn" +.Fc +.Pp +.Ft void +.Fo BN_clear_free +.Fa "BIGNUM *bn" +.Fc +.Pp +.Ft int +.Fo BN_cmp +.Fa "BIGNUM *lhs" "BIGNUM *rhs" +.Fc +.Ft int +.Fo BN_is_negative +.Fa "BIGNUM *bn" +.Fc +.Ft int +.Fo BN_is_zero +.Fa "BIGNUM *bn" +.Fc +.Ft int +.Fo BN_is_odd +.Fa "BIGNUM *bn" +.Fc +.Ft int +.Fo BN_is_even +.Fa "BIGNUM *bn" +.Fc +.Pp +.Ft BIGNUM * +.Fo BN_bin2bn +.Fa "const uint8_t *buf" "int size" "BIGNUM *bn" +.Fc +.Ft int +.Fo BN_bn2bin +.Fa "BIGNUM *bn" "uint8_t *buf" +.Fc +.Ft int +.Fo BN_bn2bin +.Fa "BIGNUM *bn" "uint8_t *buf" +.Fc +.Ft char * +.Fo BN_bn2hex +.Fa "const BIGNUM *bn" +.Fc +.Ft char * +.Fo BN_bn2dec +.Fa "const BIGNUM *bn" +.Fc +.Ft int +.Fo BN_hex2bn +.Fa "BIGNUM **bn" "const char *str" +.Fc +.Ft int +.Fo BN_dec2bn +.Fa "BIGNUM **bn" "const char *str" +.Fc +.Ft int +.Fo BN_print_fp +.Fa "FILE *fp" "const BIGNUM *bn" +.Fc +.Pp +.Ft int +.Fo BN_add +.Fa "BIGNUM *sum" "const BIGNUM *a" "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_sub +.Fa "BIGNUM *sum" "const BIGNUM *a" "const BIGNUM *b" +.Fc +.Ft int +.Fo BN_mul +.Fa "BIGNUM *product" "const BIGNUM *a" "const BIGNUM *b" "BN_CTX *context" +.Fc +.Ft int +.Fo BN_div +.Fa "BIGNUM *quotient" "BIGNUM *remainder" "const BIGNUM *a" "const BIGNUM *b" "BN_CTX *context" +.Fc +.Pp +.Ft int +.Fo BN_lshift +.Fa "BIGNUM *result" "const BIGNUM *bn" "int n" +.Fc +.Ft int +.Fo BN_lshift1 +.Fa "BIGNUM *result" "const BIGNUM *bn" +.Fc +.Ft int +.Fo BN_rshift +.Fa "BIGNUM *result" "const BIGNUM *bn" "int n" +.Fc +.Ft int +.Fo BN_rshift1 +.Fa "BIGNUM *result" "const BIGNUM *bn" +.Fc +.Pp +.Ft int +.Fo BN_set_word +.Fa "BIGNUM *result" "unsigned long val" +.Fc +.Ft int +.Fo BN_set_negative +.Fa "BIGNUM *result" "int val" +.Fc +.Pp +.Ft int +.Fo BN_num_bytes +.Fa "const BIGNUM *bn" +.Fc +.Ft int +.Fo BN_num_bits +.Fa "const BIGNUM *bn" +.Fc +.Pp +.Ft int +.Fo BN_mod_exp +.Fa "BIGNUM *result" "BIGNUM *a" "BIGNUM *p" "BIGNUM *m" "BN_CTX *context" +.Fc +.Ft BIGNUM * +.Fo BN_mod_inverse +.Fa "BIGNUM *result" "BIGNUM *a" "BIGNUM *n" "BN_CTX *context" +.Fc +.Ft int +.Fo BN_mod_mul +.Fa "BIGNUM *result" "BIGNUM *a" "BIGNUM *b" "BIGNUM *m" "BN_CTX *context" +.Fc +.Ft int +.Fo BN_mod_sub +.Fa "BIGNUM *result" "BIGNUM *a" "BIGNUM *b" "BIGNUM *m" "BN_CTX *context" +.Fc +.Pp +.Ft BN_CTX * +.Fo BN_CTX_new +.Fa "void" +.Fc +.Ft BIGNUM * +.Fo BN_CTX_get +.Fa "BN_CTX *context" +.Fc +.Ft void +.Fo BN_CTX_start +.Fa "BN_CTX *context" +.Fc +.Ft void +.Fo BN_CTX_end +.Fa "BN_CTX *context" +.Fc +.Ft void +.Fo BN_CTX_init +.Fa "BN_CTX *context" +.Fc +.Ft void +.Fo BN_CTX_free +.Fa "BN_CTX *context" +.Fc +.Ft int +.Fo BN_rand +.Fa "BIGNUM *result" "int bits" "int top" "int bottom" +.Fc +.Ft int +.Fo BN_rand_range +.Fa "BIGNUM *result" "BIGNUM *range" +.Fc +.Ft int +.Fo BN_is_prime +.Fa "const BIGNUM *bn" "int checks" "void (*callback)(int int void)" +.Fa "BN_CTX *context" "void *callbackarg" +.Fc +.Pp +.Ft const BIGNUM * +.Fo BN_value_one +.Fa "void" +.Fc +.Ft int +.Fo BN_is_bit_set +.Fa "const BIGNUM *bn" "int n" +.Fc +.Sh DESCRIPTION +.Nm +emulates the API of the openssl +.Xr bn 3 +library. +It is implemented using Tom St Denis's +.Dq libtommath +library. +.Sh EXAMPLES +The following code fragment will make a JSON object +out of the string +.Dq Hello \en +in the +buffer called +.Va buf +where +.Dq USER +is the name of the user taken from the runtime environment. +The encoded text will be in an allocated buffer called +.Va s . +.Bd -literal -offset indent +mj_t atom; +char buf[BUFSIZ]; +char *s; +int cc; + +(void) memset(\*[Am]atom, 0x0, sizeof(atom)); +cc = snprintf(buf, sizeof(buf), "Hello %s\en", getenv("USER")); +mj_create(\*[Am]atom, "string", buf, cc); +cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_JSON_ENCODE); +.Ed +.Pp +Next, the following example will take the (binary) text which has been encoded into +JSON and is in the buffer +.Va buf , +such as in the previous example, and re-create the original text: +.Bd -literal -offset indent +int from, to, tok, cc; +char *s; +mj_t atom; + +(void) memset(\*[Am]atom, 0x0, sizeof(atom)); +from = to = tok = 0; +mj_parse(\*[Am]atom, buf, \*[Am]from, \*[Am]to, \*[Am]tok); +cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_HUMAN); +printf("%.*s", cc, s); +.Ed +.Pp +The +.Va s +pointer points to allocated storage with the original NUL-terminated string +in it. +.Sh SEE ALSO +.Xr bn 3 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 7.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org . diff --git a/static/netbsd/man3/libnetpgprsa.3 b/static/netbsd/man3/libnetpgprsa.3 new file mode 100644 index 00000000..c71f1d28 --- /dev/null +++ b/static/netbsd/man3/libnetpgprsa.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: libnetpgprsa.3,v 1.5 2014/03/18 18:20:35 riastradh Exp $ +.\" +.\" Copyright (c) 2012 Alistair Crooks +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 13, 2012 +.Dt LIBNETPGPRSA 3 +.Os +.Sh NAME +.Nm libnetpgprsa +.Nd BIGNUM library of multi-precision integers +.Sh LIBRARY +.Lb libnetpgprsa +.Sh SYNOPSIS +.In netpgp/rsa.h +.Ft RSA * +.Fo RSA_new +.Fa "void" +.Fc +.Ft int +.Fo RSA_size +.Fa "const RSA *rsa" +.Fc +.Ft void +.Fo RSA_free +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_check_key +.Fa "RSA *rsa" +.Fc +.Ft RSA * +.Fo RSA_generate_key +.Fa "int num" "unsigned long e" "void (*callback)(int, int, void *)" "void *callbackarg" +.Fc +.Ft int +.Fo RSA_public_encrypt +.Fa "int siglen" "const uint8_t *signature" "uint8_t *to" "RSA *rsa" "int padding" +.Fc +.Ft int +.Fo RSA_private_encrypt +.Fa "int siglen" "const uint8_t *signature" "uint8_t *to" "RSA *rsa" "int padding" +.Fc +.Ft int +.Fo RSA_private_decrypt +.Fa "int siglen" "const uint8_t *signature" "uint8_t *to" "RSA *rsa" "int padding" +.Fc +.Pp +.Ft DSA * +.Fo DSA_new +.Fa "void" +.Fc +.Ft int +.Fo DSA_size +.Fa "const DSA *dsa" +.Fc +.Ft void +.Fo DSA_free +.Fa "DSA *dsa" +.Fc +.Ft DSA_SIG * +.Fo DSA_SIG_new +.Fa "void" +.Fc +.Ft void +.Fo DSA_SIG_free +.Fa "DSA_SIG *sig" +.Fc +.Ft int +.Fo DSA_do_verify +.Fa "const unsigned char *digest" "int digestlen" "DSA_SIG *sig" "DSA *dsa" +.Fc +.Ft int +.Fo DSA_do_sign +.Fa "const unsigned char *digest" "int digestlen" "DSA *dsa" +.Fc +.Sh DESCRIPTION +.Nm +is a small library which provides RSA signing, +encryption and decryption, and DSA signing. +RSA and DSA verification are provided by the +.Xr libnetpgpverify 3 +library. +.Sh SEE ALSO +.Xr libnetpgpbn 3 , +.Xr libnetpgpverify 3 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 7.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org diff --git a/static/netbsd/man3/libnetpgpverify.3 b/static/netbsd/man3/libnetpgpverify.3 new file mode 100644 index 00000000..46ff5aa4 --- /dev/null +++ b/static/netbsd/man3/libnetpgpverify.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: libnetpgpverify.3,v 1.6 2014/02/17 07:23:18 agc Exp $ +.\" +.\" Copyright (c) 2012 Alistair Crooks +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 16, 2014 +.Dt LIBNETPGPVERIFY 3 +.Os +.Sh NAME +.Nm libnetpgpverify +.Nd library to verify digital signatures +.Sh LIBRARY +.Lb libnetpgpverify +.Sh SYNOPSIS +.In netpgp/verify.h +.Ft int +.Fo pgpv_read_pubring +.Fa "pgpv_t *pgp" "const void *keyring" "ssize_t size" +.Fc +.Ft size_t +.Fo pgpv_verify +.Fa "pgpv_cursor_t *cursor" "pgpv_t *pgp" "const void *ptr" "ssize_t size" +.Fc +.Ft size_t +.Fo pgpv_get_verified +.Fa "pgpv_cursor_t *cursor" "size_t cookie" "char **ret" +.Fc +.Ft size_t +.Fo pgpv_get_entry +.Fa "pgpv_t *pgp" "unsigned ent" "char **ret" +.Fc +.Ft int +.Fo pgpv_close +.Fa "pgpv_t *pgp" +.Fc +.Sh DESCRIPTION +.Nm +is a small library which will verify a digital signature on a text or +binary document. +It has been kept deliberately small and only uses compression libraries +to function. +.Pp +PGP messages, including key rings, are made up of PGP packets, defined +in RFC 4880. +To match a digital signature, the public key of the signer must be +located in a public key ring. +This library has enough functionality to parse a pubkey keyring, +using +.Fn pgpv_read_pubring +to read the public keys of trusted identities, +and to read files or memory which has already been signed. +The +.Fn pgpv_verify +function is used to verify the signature, either on data, or on memory. +To signal to +.Fn pgpv_verify +to read a file and verify it, the +.Dv size +argument should be set to +.Dv -1 +whilst a positive size signals that the pointer value should be that +of signed memory. +.Fn pgpv_verify +returns a cookie if the ignature was verified, or 0 if it did not. +This cookie can subsequently be used to retrieve the data which +was verified. +.Pp +If the signature does match, then the file or memory can be considered as being +verified as being unmodified and unchanged, integrally sound. +.Pp +Signatures have validity dates on them, and it is possible for a signature to +have expired when it is being checked. +If for any reason the signature does not match, then the reason for not +verifying the signature will be stored in the +.Dv why +buffer in the +.Dv pgpv_cursor_t +structure. +.Pp +Occasionally, the memory or contents of the file which matched the signature +will be needed, rather than a boolean value of whether it was verified. +To do this, the +.Fn pgpv_get_verified +function is used. +Arguments to +.Fn pgpv_get_verified +are the cookie returned from the verification, and a buffer +allocated for the returned data and its size. +If an error occurs, or the signature is not verified, a zero value is returned +for the size. +.Nm +stores the starts of the data of all verified matches, and so the entry +number argument is the index of the occurrence of verification. +The first match will have an entry number of 0, the second 1, and so on. +.Pp +The +.Fn pgpv_close +function is used to clean up after all matching and verification has taken place. +It frees and de-allocates all resources used in the verification of the signature. +.Pp +The program used for signing may encode into base64 encoding, and it may also +use embedded compression to make the output smaller than it would otherwise be. +This is handled automatically by +.Nm . +.Sh SEE ALSO +.Xr bn 3 , +.\" .Xr bzlib2 3 , +.Xr zlib 3 +.Sh STANDARDS +.Rs +.%A J. Callas +.%A L. Donnerhacke +.%A H. Finney +.%A D. Shaw +.%A R. Thayer +.%D November 2007 +.%R RFC 4880 +.%T OpenPGP Message Format +.Re +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 7.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org diff --git a/static/netbsd/man3/libnpf.3 b/static/netbsd/man3/libnpf.3 new file mode 100644 index 00000000..05d56f78 --- /dev/null +++ b/static/netbsd/man3/libnpf.3 @@ -0,0 +1,506 @@ +.\" $NetBSD: libnpf.3,v 1.12 2020/05/30 14:16:56 rmind Exp $ +.\" +.\" Copyright (c) 2011-2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This material is based upon work partially supported by The +.\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 30, 2020 +.Dt LIBNPF 3 +.Os +.Sh NAME +.Nm libnpf +.Nd NPF packet filter library +.Sh LIBRARY +.Lb libnpf +.Sh SYNOPSIS +.In npf.h +.\" --- +.Ft nl_config_t * +.Fn npf_config_create "void" +.Ft int +.Fn npf_config_submit "nl_config_t *ncf" "int fd" "npf_error_t *errinfo" +.Ft nl_config_t * +.Fn npf_config_retrieve "int fd" +.Ft int +.Fn npf_config_flush "int fd" +.Ft void +.Fn npf_config_export "nl_config_t *ncf" "size_t *len" +.Ft nl_config_t * +.Fn npf_config_import "const void *blob" "size_t len" +.Ft bool +.Fn npf_config_active_p "nl_config_t *ncf" +.Ft bool +.Fn npf_config_loaded_p "nl_config_t *ncf" +.Ft void +.Fn npf_config_destroy "nl_config_t *ncf" +.\" --- +.Ft nl_rule_t * +.Fn npf_rule_create "const char *name" "uint32_t attr" "const char *ifname" +.Ft int +.Fn npf_rule_setcode "nl_rule_t *rl" "int type" "const void *code" "size_t len" +.Ft int +.Fn npf_rule_setkey "nl_rule_t *rl" "const void *key" "size_t len" +.Ft int +.Fn npf_rule_setinfo "nl_rule_t *rl" "const void *info" "size_t len" +.Ft int +.Fn npf_rule_setprio "nl_rule_t *rl" "int pri" +.Ft int +.Fn npf_rule_setproc "nl_rule_t *rl" "const char *name" +.Ft int +.Fn npf_rule_insert "nl_config_t *ncf" "nl_rule_t *parent" "nl_rule_t *rl" +.Ft bool +.Fn npf_rule_exists_p "nl_config_t *ncf" "const char *name" +.Ft void * +.Fn npf_rule_export "nl_rule_t *rl" "size_t *length" +.Ft void +.Fn npf_rule_destroy "nl_rule_t *rl" +.\" --- +.Ft nl_rproc_t * +.Fn npf_rproc_create "const char *name" +.Ft int +.Fn npf_rproc_extcall "nl_rproc_t *rp" "nl_ext_t *ext" +.Ft bool +.Fn npf_rproc_exists_p "nl_config_t *ncf" "const char *name" +.Ft int +.Fn npf_rproc_insert "nl_config_t *ncf" "nl_rproc_t *rp" +.\" --- +.Ft nl_nat_t * +.Fn npf_nat_create "int type" "unsigned flags" "const char *ifname" +.Ft int +.Fn npf_nat_setaddr "nl_nat_t *nt" "int af" "npf_addr_t *addr" \ +"npf_netmask_t mask" +.Ft int +.Fn npf_nat_setport "nl_nat_t *nt" "in_port_t port" +.Ft int +.Fn npf_nat_insert "nl_config_t *ncf" "nl_nat_t *nt" +.\" --- +.Ft nl_table_t * +.Fn npf_table_create "const char *name" "unsigned id" "int type" +.Ft int +.Fn npf_table_add_entry "nl_table_t *tl" "int af" \ +"const npf_addr_t *addr" "const npf_netmask_t mask" +.Ft int +.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl" +.Ft int +.Fn npf_table_replace "int fd" "nl_table_t *tl" "npf_error_t *errinfo" +.Ft void +.Fn npf_table_destroy "nl_table_t *tl" +.\" --- +.Ft int +.Fn npf_ruleset_add "int fd" "const char *name" "nl_rule_t *rl" "uint64_t *id" +.Ft int +.Fn npf_ruleset_remove "int fd" "const char *name" "uint64_t id" +.Ft int +.Fn npf_ruleset_remkey "int fd" "const char *name" "const void *key" "size_t len" +.Ft int +.Fn npf_ruleset_flush "int fd" "const char *name" +.\" ----- +.Sh DESCRIPTION +The +.Nm +library provides an interface to create an NPF configuration having rules, +tables, procedures, or translation policies. +The configuration can be submitted to the kernel. +.\" ----- +.Sh FUNCTIONS +.Ss Configuration +.Bl -tag -width 4n +.It Fn npf_config_create +Create a new configuration object. +.It Fn npf_config_submit "ncf" "fd" "errinfo" +Submit the configuration object, specified by +.Fa ncf , +to the kernel. +On failure, the error information is written into the structure +specified by +.Fa errinfo . +.It Fn npf_config_export "ncf" "len" +Serialize the given configuration and return the binary object as +well as its length in +.Fa len +parameter. +The binary object is dynamically allocated and should be destroyed using +.Xr free 3 . +.It Fn npf_config_import "blob" "len" +Read the configuration from a binary object of the specified length, +unserialize, and return the configuration object. +.It Fn npf_config_flush "fd" +Flush the current configuration. +.It Fn npf_config_retrieve "fd" +Retrieve and return the loaded configuration from the kernel. +.It Fn npf_config_active_p "ncf" +Indicate whether the retrieved configuration is active i.e. packet +filtering is enabled (true if yes and false otherwise). +.It Fn npf_config_loaded_p "ncf" +Indicate whether the retrieved configuration is loaded i.e. has any +rules (true if yes and false otherwise). +.It Fn npf_config_destroy "ncf" +Destroy the configuration object, specified by +.Fa ncf . +.El +.\" --- +.Ss Rule interface +.Bl -tag -width 4n +.It Fn npf_rule_create "name" "attr" "ifname" +Create a rule with a given name, attributes and priority. +If the name is specified, then it should be unique within the +configuration object. +Otherwise, the name can be +.Dv NULL , +in which case the rule will have no identifier. +The following attributes, which can be ORed, are available: +.Bl -tag -width indent +.It Dv NPF_RULE_PASS +The decision of this rule shall be "pass". +If this attribute is not +specified, then "block" (drop the packet) is the default. +.It Dv NPF_RULE_IN +Match the incoming packets. +.It Dv NPF_RULE_OUT +Match the outgoing packets. +.It Dv NPF_RULE_FINAL +Indicate that on rule match, further processing of the ruleset should +be stopped and this rule should be applied instantly. +.It Dv NPF_RULE_STATEFUL +Create a state (session) on match, track the connection and pass the +backwards stream (the returning packets) without the ruleset inspection. +The state is uniquely identified by an n-tuple key. +.It Dv NPF_RULE_GSTATEFUL +Exclude the interface identifier from the state key (n-tuple). +This makes the state global with respect to the network interfaces. +The state is also picked for packets travelling in different direction +than originally. +.It Dv NPF_RULE_RETRST +Return TCP RST packet in a case of packet block. +.It Dv NPF_RULE_RETICMP +Return ICMP destination unreachable in a case of packet block. +.It Dv NPF_RULE_GROUP +Allow this rule to have sub-rules. +If this flag is used with the +.Dv NPF_RULE_DYNAMIC +flag set, then it is a dynamic group. +The sub-rules can be added dynamically to a dynamic group, also meaning +that the sub-rules must have the +.Dv NPF_RULE_DYNAMIC +flag set. +Otherwise rules must be added statically i.e. created with the configuration. +.It Dv NPF_RULE_DYNAMIC +Indicate that the rule is dynamic. +Such rules can only be added to the dynamic groups. +.El +.Pp +The interface is specified by the +.Fa ifname +string. +.Dv NULL +indicates any interface. +.\" --- +.It Fn npf_rule_setcode "rl" "type" "code" "len" +Assign the code for the rule specified by +.Fa rl . +The code is used to implement the filter criteria. +The pointer to the binary code is specified by +.Fa code , +the size of the memory area by +.Fa len , +and the type of the code is specified by +.Fa type . +Currently, only the BPF byte-code is supported and the +.Dv NPF_CODE_BPF +constant should be passed. +.\" --- +.It Fn npf_rule_setkey "rl" "key" "len" +Assign a key for the rule specified by +.Fa rl . +The binary key is specified by +.Fa key , +and its size by +.Fa len . +The size shall not exceed +.Dv NPF_RULE_MAXKEYLEN . +The kernel does not check whether key is unique, therefore it is the +responsibility of the caller. +.\" --- +.It Fn npf_rule_setinfo "rl" "info" "len" +Associate an arbitrary information blob specified by +.Fa info , +and its size by +.Fa len . +This may be used for such purposes as the byte-code annotation. +.\" --- +.It Fn npf_rule_setprio "rl" "pri" +Set priority to the rule. +Negative priorities are invalid. +.Pp +The priority is the order of the rule in the ruleset. +The lower value means first to process, the higher value - last to process. +If multiple rules are inserted with the same priority, +then the order is unspecified. +.Pp +The special constants +.Dv NPF_PRI_FIRST +and +.Dv NPF_PRI_LAST +can be passed to indicate that the rule should be inserted into the +beginning or the end of the priority level 0 in the ruleset. +All rules inserted using these constants will have the priority 0 +assigned and will share this level in the ordered way. +.\" --- +.It Fn npf_rule_setproc "rl" "name" +Set a procedure for the specified rule. +.\" --- +.It Fn npf_rule_insert "ncf" "parent" "rl" +Insert the rule into the set of the parent rule specified by +.Fa parent . +If the value of +.Fa parent +is +.Dv NULL , +then insert into the main ruleset. +The rule will be consumed (the relevant resourced will be freed) and it +must not be referenced after insertion. +.\" --- +.It Fn npf_rule_exists_p "ncf" "name" +Check whether the rule with a given name is already in the configuration. +.\" --- +.It Fn npf_rule_export "rl" "length" +Serialize the rule (including the byte-code), return a binary object +and set its +.Fa length . +The binary object is dynamically allocated and should be destroyed using +.Xr free 3 . +.\" --- +.It Fn npf_rule_destroy "rl" +Destroy the given rule object. +.El +.\" ----- +.Ss Rule procedure interface +.Bl -tag -width 4n +.It Fn npf_rproc_create "name" +Create a rule procedure with a given +.Fa name . +Thr name must be unique for each procedure. +.It Fn npf_rproc_insert "ncf" "rp" +Insert the rule procedure into the specified configuration object. +The rule procedure must not be referenced after insertion. +.El +.\" ----- +.Ss Translation interface +.Bl -tag -width 4n +.It Fn npf_nat_create "type" "flags" "ifname" +Create a NAT policy of a specified type. +There are two types: +.Bl -tag -width "NPF_NAT_PORTMAP " +.It Dv NPF_NATIN +Inbound NAT policy (rewrite destination). +.It Dv NPF_NATOUT +Outbound NAT policy (rewrite source). +.El +.Pp +A bi-directional NAT is obtained by combining two policies. +The following +.Fa flags +are supported: +.Bl -tag -width "NPF_NAT_PORTMAP " +.It Dv NPF_NAT_STATIC +Perform static (stateless) translation rather than dynamic (stateful). +.It Dv NPF_NAT_PORTS +Perform the port translation. +If this flag is not specified, then the port translation is not performed +and the +.Fa port +parameter is ignored. +.It Dv NPF_NAT_PORTMAP +Create a port map and select a random port for translation. +If enabled, then the value specified by the +.Fa port +parameter is ignored. +This flag is effective only if the +.Dv NPF_NAT_PORTS +flag is set. +.El +.Pp +The network interface on which the policy will be applicable is specified by +.Fa ifname . +.\" --- +.It Fn npf_nat_setaddr "nt" "af" "addr" "mask" +Set the translation address, as specified by +.Fa addr , +and its family by +.Fa af . +The family must be either +.Dv AF_INET +for IPv4 or +.Dv AF_INET6 +for IPv6 address. +Additionally, +.Fa mask +may be specified to indicate the translation network; +otherwise, it should be set to +.Dv NPF_NO_NETMASK . +.Pp +In order to use the translation network, a custom algorithm may need to +be specified using the +.Fn npf_nat_setalgo +function. +.\" --- +.It Fn npf_nat_setport "nt" "port" +Set the translation port, specified by +.Fa port . +.\" --- +.It Fn npf_nat_setalgo "nt" "algo" +Set a particular NAT algorithm. +Currently, the following algorithms are supported with dynamic NAT: +.Bl -tag -width "NPF_ALGO_IPHASH" +.It Dv NPF_ALGO_IPHASH +Hash of the source and destination addresses. +.It Dv NPF_ALGO_RR +Round-robin for the translation addresses. +.It Dv NPF_ALGO_NETMAP +Network-to-network map as described below, but with state tracking. +It is used when it is necessary to translate the ports. +.El +.Pp +The following are support with static NAT: +.Bl -tag -width "NPF_ALGO_NETMAP" +.It Dv NPF_ALGO_NETMAP +Network-to-network map where the translation network prefix (address +after applying the mask) is bitwise OR-ed with the host part of the +original address (zero bits of the mask). +.It Dv NPF_ALGO_NPT66 +IPv6-to-IPv6 Network Prefix Translation (NPTv6, defined in RFC 6296). +.El +.\" --- +.It Fn npf_nat_insert "ncf" "nt" +Insert the NAT policy, its rule, into the specified configuration. +The NAT rule must not be referenced after insertion. +.El +.\" ----- +.Ss Table interface +.Bl -tag -width 4n +.It Fn npf_table_create "name" "index" "type" +Create an NPF table of a specified type. +The table is identified by the +.Fa name +and +.Fa index , +which should be in the range between 1 and +.Dv NPF_MAX_TABLES . +.Pp +The following types are supported: +.Bl -tag -width "NPF_TABLE_IPSET" +.It Dv NPF_TABLE_IPSET +Indicates to use a regular associative array for storage of IP sets. +Currently implemented as a hashmap. +.It Dv NPF_TABLE_LPM +Indicates to the table can contain networks (as well as hosts) and the +longest prefix match should be performed on lookup. +.It Dv NPF_TABLE_CONST +Indicates that the table contents will be constant and the table can be +considered immutable (no inserts/removes after load). +If such constraint is acceptable, this table type will provide the best +performance. +It is currently implemented as a perfect hash table, generated on table +insertion into the configuration. +.El +.\" --- +.It Fn npf_table_add_entry "tl" "af" "addr" "mask" +Add an entry of IP address and mask, specified by +.Fa addr +and +.Fa mask , +to the table specified by +.Fa tl . +The family, specified by +.Fa af , +must be either +.Dv AF_INET +for IPv4 or +.Dv AF_INET6 +for IPv6 address. +If there is no mask, then +.Fa mask +should be set to +.Dv NPF_NO_NETMASK . +.\" --- +.It Fn npf_table_insert "ncf" "tl" +Add the table to the configuration object. +This routine performs a check for duplicate table IDs. +The table must not be referenced after insertion. +.\" --- +.It Fn npf_table_replace "fd" "tl" "errinfo" +Submit the table object, specified by +.Fa tl , +to the kernel, to replace the existing table with the +corresponding table name and ID. +On failure, the error information is written into the structure +specified by +.Fa errinfo . +.\" --- +.It Fn npf_table_destroy "tl" +Destroy the specified table. +.El +.\" ----- +.Ss Ruleset interface +.Bl -tag -width 4n +.It Fn npf_ruleset_add "fd" "name" "rl" "id" +Add a given rule, specified by +.Fa rl , +into the dynamic ruleset named +.Fa name . +On success, return 0 and a unique rule ID in the +.Fa id +parameter. +.It Fn npf_ruleset_remove "fd" "name" "id" +Remove a rule from the dynamic ruleset, specified by +.Fa name . +The rule is specified by its unique ID in the +.Fa id +parameter. +.It Fn npf_ruleset_remkey "fd" "name" "key" "len" +Remove a rule from the dynamic ruleset, specified by +.Fa name . +The rule is specified by its key, in the +.Fa key +and +.Fa len +parameters. +The key for the rule must have been set during its construction, using the +.Fn npf_rule_setkey +routine. +.It Fn npf_ruleset_flush "fd" "name" +Clear the dynamic ruleset, specified by +.Fa name , +by removing all its rules. +.El +.\" ----- +.Sh SEE ALSO +.Xr bpf 4 , +.Xr npf 7 , +.Xr npfctl 8 +.Sh HISTORY +The NPF library first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/libnvmm.3 b/static/netbsd/man3/libnvmm.3 new file mode 100644 index 00000000..903ab68c --- /dev/null +++ b/static/netbsd/man3/libnvmm.3 @@ -0,0 +1,739 @@ +.\" $NetBSD: libnvmm.3,v 1.29 2025/07/26 19:24:59 skrll Exp $ +.\" +.\" Copyright (c) 2018-2020 Maxime Villard, m00nbsd.net +.\" All rights reserved. +.\" +.\" This code is part of the NVMM hypervisor. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 26, 2025 +.Dt LIBNVMM 3 +.Os +.Sh NAME +.Nm libnvmm +.Nd NetBSD Virtualization API +.Sh LIBRARY +.Lb libnvmm +.Sh SYNOPSIS +.In nvmm.h +.Ft int +.Fn nvmm_init "void" +.Ft int +.Fn nvmm_capability "struct nvmm_capability *cap" +.Ft int +.Fn nvmm_machine_create "struct nvmm_machine *mach" +.Ft int +.Fn nvmm_machine_destroy "struct nvmm_machine *mach" +.Ft int +.Fn nvmm_machine_configure "struct nvmm_machine *mach" "uint64_t op" \ + "void *conf" +.Ft int +.Fn nvmm_vcpu_create "struct nvmm_machine *mach" "nvmm_cpuid_t cpuid" \ + "struct nvmm_vcpu *vcpu" +.Ft int +.Fn nvmm_vcpu_destroy "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" +.Ft int +.Fn nvmm_vcpu_configure "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \ + "uint64_t op" "void *conf" +.Ft int +.Fn nvmm_vcpu_getstate "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \ + "uint64_t flags" +.Ft int +.Fn nvmm_vcpu_setstate "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \ + "uint64_t flags" +.Ft int +.Fn nvmm_vcpu_inject "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" +.Ft int +.Fn nvmm_vcpu_run "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" +.Ft int +.Fn nvmm_hva_map "struct nvmm_machine *mach" "uintptr_t hva" "size_t size" +.Ft int +.Fn nvmm_hva_unmap "struct nvmm_machine *mach" "uintptr_t hva" "size_t size" +.Ft int +.Fn nvmm_gpa_map "struct nvmm_machine *mach" "uintptr_t hva" "gpaddr_t gpa" \ + "size_t size" "int prot" +.Ft int +.Fn nvmm_gpa_unmap "struct nvmm_machine *mach" "uintptr_t hva" "gpaddr_t gpa" \ + "size_t size" +.Ft int +.Fn nvmm_gva_to_gpa "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \ + "gvaddr_t gva" "gpaddr_t *gpa" "nvmm_prot_t *prot" +.Ft int +.Fn nvmm_gpa_to_hva "struct nvmm_machine *mach" "gpaddr_t gpa" \ + "uintptr_t *hva" "nvmm_prot_t *prot" +.Ft int +.Fn nvmm_assist_io "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" +.Ft int +.Fn nvmm_assist_mem "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" +.Sh DESCRIPTION +.Nm +provides a library for emulator software to handle hardware-accelerated virtual +machines in +.Nx . +A virtual machine is described by an opaque structure, +.Cd nvmm_machine . +Emulator software should not attempt to modify this structure directly, and +should use the API provided by +.Nm +to manage virtual machines. +A virtual CPU is described by a public structure, +.Cd nvmm_vcpu . +.Pp +.Fn nvmm_init +initializes NVMM. +See +.Sx NVMM Initialization +below for details. +.Pp +.Fn nvmm_capability +gets the capabilities of NVMM. +See +.Sx NVMM Capability +below for details. +.Pp +.Fn nvmm_machine_create +creates a virtual machine in the kernel. +The +.Fa mach +structure is initialized, and describes the machine. +.Pp +.Fn nvmm_machine_destroy +destroys the virtual machine described in +.Fa mach . +.Pp +.Fn nvmm_machine_configure +configures, on the machine +.Fa mach , +the parameter indicated in +.Fa op . +.Fa conf +describes the value of the parameter. +.Pp +.Fn nvmm_vcpu_create +creates a virtual CPU in the machine +.Fa mach , +giving it the CPU id +.Fa cpuid , +and initializes +.Fa vcpu . +.Pp +.Fn nvmm_vcpu_destroy +destroys the virtual CPU identified by +.Fa vcpu +in the machine +.Fa mach . +.Pp +.Fn nvmm_vcpu_configure +configures, on the VCPU +.Fa vcpu +of machine +.Fa mach , +the parameter indicated in +.Fa op . +.Fa conf +describes the value of the parameter. +.Pp +.Fn nvmm_vcpu_getstate +gets the state of the virtual CPU identified by +.Fa vcpu +in the machine +.Fa mach . +.Fa flags +is the bitmap of the components that are to be retrieved. +The components are located in +.Fa vcpu->state . +See +.Sx VCPU State Area +below for details. +.Pp +.Fn nvmm_vcpu_setstate +sets the state of the virtual CPU identified by +.Fa vcpu +in the machine +.Fa mach . +.Fa flags +is the bitmap of the components that are to be set. +The components are located in +.Fa vcpu->state . +See +.Sx VCPU State Area +below for details. +.Pp +.Fn nvmm_vcpu_inject +injects into the CPU identified by +.Fa vcpu +of the machine +.Fa mach +an event described by +.Fa vcpu->event . +See +.Sx Event Injection +below for details. +.Pp +.Fn nvmm_vcpu_run +runs the CPU identified by +.Fa vcpu +in the machine +.Fa mach , +until a VM exit is triggered. +The +.Fa vcpu->exit +structure is filled to indicate the exit reason, and the associated parameters +if any. +.Pp +.Fn nvmm_hva_map +maps at address +.Fa hva +a buffer of size +.Fa size +in the calling process' virtual address space. +This buffer is allowed to be subsequently mapped in a virtual machine. +.Pp +.Fn nvmm_hva_unmap +unmaps the buffer of size +.Fa size +at address +.Fa hva +from the calling process' virtual address space. +.Pp +.Fn nvmm_gpa_map +maps into the guest physical memory beginning on address +.Fa gpa +the buffer of size +.Fa size +located at address +.Fa hva +of the calling process' virtual address space. +The +.Fa hva +parameter must point to a buffer that was previously mapped with +.Fn nvmm_hva_map . +.Pp +.Fn nvmm_gpa_unmap +removes the guest physical memory area beginning on address +.Fa gpa +and of size +.Fa size +from the machine +.Fa mach . +.Pp +.Fn nvmm_gva_to_gpa +translates, on the CPU +.Fa vcpu +from the machine +.Fa mach , +the guest virtual address given in +.Fa gva +into a guest physical address returned in +.Fa gpa . +The associated page permissions are returned in +.Fa prot . +.Fa gva +must be page-aligned. +.Pp +.Fn nvmm_gpa_to_hva +translates, on the machine +.Fa mach , +the guest physical address indicated in +.Fa gpa +into a host virtual address returned in +.Fa hva . +The associated page permissions are returned in +.Fa prot . +.Fa gpa +must be page-aligned. +.Pp +.Fn nvmm_assist_io +emulates the I/O operation described in +.Fa vcpu->exit +on CPU +.Fa vcpu +from machine +.Fa mach . +See +.Sx I/O Assist +below for details. +.Pp +.Fn nvmm_assist_mem +emulates the Mem operation described in +.Fa vcpu->exit +on CPU +.Fa vcpu +from machine +.Fa mach . +See +.Sx Mem Assist +below for details. +.Ss NVMM Initialization +NVMM initialization is performed by the +.Fn nvmm_init +function, which must be invoked by emulator software before any other NVMM +function. +.Pp +.Fn nvmm_init +opens the NVMM device, and expects to have the proper permissions to do so. +In a default configuration, this implies being part of the "nvmm" group. +If using a special configuration, emulator software should arrange to have the +proper permissions before invoking +.Fn nvmm_init , +and can drop them after the call has completed. +.Pp +It is to be noted that +.Fn nvmm_init +may perform non-re-entrant operations, and should be called only once. +.Ss NVMM Capability +The +.Cd nvmm_capability +structure helps emulator software identify the capabilities offered by NVMM on +the host: +.Bd -literal +struct nvmm_capability { + uint64_t version; + uint64_t state_size; + uint64_t max_machines; + uint64_t max_vcpus; + uint64_t max_ram; + struct { + ... + } arch; +}; +.Ed +.Pp +For example, the +.Cd max_machines +field indicates the maximum number of virtual machines supported, while +.Cd max_vcpus +indicates the maximum number of VCPUs supported per virtual machine. +.Ss Machine Ownership +When a process creates a virtual machine via +.Fn nvmm_machine_create , +it is considered the owner of this machine. +No other processes than the owner can operate a virtual machine. +.Pp +When an owner exits, all the virtual machines associated with it are destroyed, +if they were not already destroyed by the owner itself via +.Fn nvmm_machine_destroy . +.Pp +Virtual machines are not inherited across +.Xr fork 2 +operations. +.Ss Machine Configuration +Emulator software can configure several parameters of a virtual machine by using +.Fn nvmm_machine_configure . +Currently, no parameters are implemented. +.Ss VCPU Configuration +Emulator software can configure several parameters of a VCPU by using +.Fn nvmm_vcpu_configure , +which can take the following operations: +.Bd -literal +#define NVMM_VCPU_CONF_CALLBACKS 0 + ... +.Ed +.Pp +The higher fields depend on the architecture. +.Ss Guest-Host Mappings +Each virtual machine has an associated guest physical memory. +Emulator software is allowed to modify this guest physical memory by mapping +it into some parts of its virtual address space. +.Pp +Emulator software should follow the following steps to achieve that: +.Pp +.Bl -bullet -offset indent -compact +.It +Call +.Fn nvmm_hva_map +to create in the host's virtual address space an area of memory that can +be shared with a guest. +Typically, the +.Fa hva +parameter will be a pointer to an area that was previously mapped via +.Fn mmap . +.Fn nvmm_hva_map +will replace the content of the area, and will make it read-write (but not +executable). +.It +Make available in the guest an area of guest physical memory, by calling +.Fn nvmm_gpa_map +and passing in the +.Fa hva +parameter the value that was previously given to +.Fn nvmm_hva_map . +.Fn nvmm_gpa_map +does not replace the content of any memory, it only creates a direct link +from +.Fa gpa +into +.Fa hva . +.Fn nvmm_gpa_unmap +removes this link without modifying +.Fa hva . +.El +.Pp +The guest will then be able to use the guest physical address passed in the +.Fa gpa +parameter of +.Fn nvmm_gpa_map . +Each change the guest makes in +.Fa gpa +will be reflected in the host's +.Fa hva , +and vice versa. +.Pp +It is illegal for emulator software to use +.Fn munmap +on an area that was mapped via +.Fn nvmm_hva_map . +.Ss VCPU State Area +A VCPU state area is a structure that entirely defines the content of the +registers of a VCPU. +Only one such structure exists, for x86: +.Bd -literal +struct nvmm_x64_state { + struct nvmm_x64_state_seg segs[NVMM_X64_NSEG]; + uint64_t gprs[NVMM_X64_NGPR]; + uint64_t crs[NVMM_X64_NCR]; + uint64_t drs[NVMM_X64_NDR]; + uint64_t msrs[NVMM_X64_NMSR]; + struct nvmm_x64_state_intr intr; + struct fxsave fpu; +}; +#define nvmm_vcpu_state nvmm_x64_state +.Ed +.Pp +Refer to functional examples to see precisely how to use this structure. +.Pp +A VCPU state area is divided in sub-states. +A +.Fa flags +parameter is used to set and get the VCPU state; it acts as a bitmap which +indicates which sub-states to set or get. +.Pp +During VM exits, a partial VCPU state area is provided in +.Va exitstate , +see +.Sx Exit Reasons +below for details. +.Ss VCPU Programming Model +A VCPU is described by a public structure, +.Cd nvmm_vcpu : +.Bd -literal +struct nvmm_vcpu { + nvmm_cpuid_t cpuid; + struct nvmm_vcpu_state *state; + struct nvmm_vcpu_event *event; + struct nvmm_vcpu_exit *exit; +}; +.Ed +.Pp +This structure is used both publicly by emulator software and internally by +.Nm . +Emulator software should not modify the pointers of this structure, because +they are initialized to special values by +.Nm . +.Pp +A call to +.Fn nvmm_vcpu_getstate +will fetch the desired parts of the VCPU state and put them in +.Fa vcpu->state . +A call to +.Fn nvmm_vcpu_setstate +will install in the VCPU the desired parts of +.Fa vcpu->state . +A call to +.Fn nvmm_vcpu_inject +will inject in the VCPU the event in +.Fa vcpu->event . +A call to +.Fn nvmm_vcpu_run +will fill +.Fa vcpu->exit +with the VCPU exit information. +.Pp +If emulator software uses several threads, a VCPU should be associated with +only one thread, and only this thread should perform VCPU modifications. +Emulator software should not modify the state of a VCPU with several +different threads. +.Ss Exit Reasons +The +.Cd nvmm_vcpu_exit +structure is used to handle VM exits: +.Bd -literal +/* Generic. */ +#define NVMM_VCPU_EXIT_NONE 0x0000000000000000ULL +#define NVMM_VCPU_EXIT_INVALID 0xFFFFFFFFFFFFFFFFULL +/* x86: operations. */ +#define NVMM_VCPU_EXIT_MEMORY 0x0000000000000001ULL +#define NVMM_VCPU_EXIT_IO 0x0000000000000002ULL +/* x86: changes in VCPU state. */ +#define NVMM_VCPU_EXIT_SHUTDOWN 0x0000000000001000ULL +#define NVMM_VCPU_EXIT_INT_READY 0x0000000000001001ULL +#define NVMM_VCPU_EXIT_NMI_READY 0x0000000000001002ULL +#define NVMM_VCPU_EXIT_HALTED 0x0000000000001003ULL +#define NVMM_VCPU_EXIT_TPR_CHANGED 0x0000000000001004ULL +/* x86: instructions. */ +#define NVMM_VCPU_EXIT_RDMSR 0x0000000000002000ULL +#define NVMM_VCPU_EXIT_WRMSR 0x0000000000002001ULL +#define NVMM_VCPU_EXIT_MONITOR 0x0000000000002002ULL +#define NVMM_VCPU_EXIT_MWAIT 0x0000000000002003ULL +#define NVMM_VCPU_EXIT_CPUID 0x0000000000002004ULL + +struct nvmm_vcpu_exit { + uint64_t reason; + union { + ... + } u; + struct { + ... + } exitstate; +}; +.Ed +.Pp +The +.Va reason +field indicates the reason of the VM exit. +Additional parameters describing the exit can be present in +.Va u . +.Va exitstate +contains a partial, implementation-specific VCPU state, usable as a fast-path +to retrieve certain state values. +.Pp +It is possible that a VM exit was caused by a reason internal to the host +kernel, and that emulator software should not be concerned with. +In this case, the exit reason is set to +.Cd NVMM_VCPU_EXIT_NONE . +This gives a chance for emulator software to halt the VM in its tracks. +.Pp +Refer to functional examples to see precisely how to handle VM exits. +.Ss Event Injection +It is possible to inject an event into a VCPU. +An event can be a hardware interrupt, a software interrupt, or a software +exception, defined by: +.Bd -literal +#define NVMM_VCPU_EVENT_EXCP 0 +#define NVMM_VCPU_EVENT_INTR 1 + +struct nvmm_vcpu_event { + u_int type; + uint8_t vector; + union { + struct { + uint64_t error; + } excp; + } u; +}; +.Ed +.Pp +This describes an event of type +.Va type , +to be sent to vector number +.Va vector , +with a possible additional +.Va error +code that is implementation-specific. +.Pp +It is possible that the VCPU is in a state where it cannot receive this +event, if: +.Pp +.Bl -bullet -offset indent -compact +.It +the event is a hardware interrupt, and the VCPU runs with interrupts disabled, +or +.It +the event is a non-maskable interrupt (NMI), and the VCPU is already in an +in-NMI context. +.El +.Pp +Emulator software can manage interrupt and NMI window-exiting via the +.Va intr +component of the VCPU state. +When such window-exiting is enabled, NVMM will cause a VM exit with reason +.Cd NVMM_VCPU_EXIT_INT_READY +or +.Cd NVMM_VCPU_EXIT_NMI_READY +to indicate that the guest is now able to handle the corresponding class +of interrupts. +.Ss Assist Callbacks +In order to assist emulation of certain operations, +.Nm +requires emulator software to register, via +.Fn nvmm_vcpu_configure , +a set of callbacks described in the following structure: +.Bd -literal +struct nvmm_assist_callbacks { + void (*io)(struct nvmm_io *); + void (*mem)(struct nvmm_mem *); +}; +.Ed +.Pp +These callbacks are used by +.Nm +each time +.Fn nvmm_assist_io +or +.Fn nvmm_assist_mem +are invoked. +Emulator software that does not intend to use either of these assists can put +.Dv NULL +in the callbacks. +.Ss I/O Assist +When a VM exit occurs with reason +.Cd NVMM_VCPU_EXIT_IO , +it is necessary for emulator software to emulate the associated I/O operation. +.Nm +provides an easy way for emulator software to perform that. +.Pp +.Fn nvmm_assist_io +will call the registered +.Fa io +callback function and give it a +.Cd nvmm_io +structure as argument. +This structure describes an I/O transaction: +.Bd -literal +struct nvmm_io { + struct nvmm_machine *mach; + struct nvmm_vcpu *vcpu; + uint16_t port; + bool in; + size_t size; + uint8_t *data; +}; +.Ed +.Pp +The callback can emulate the operation using this descriptor, following two +unique cases: +.Pp +.Bl -bullet -offset indent -compact +.It +The operation is an input. +In this case, the callback should fill +.Va data +with the desired value. +.It +The operation is an output. +In this case, the callback should read +.Va data +to retrieve the desired value. +.El +.Pp +In either case, +.Va port +will indicate the I/O port, +.Va in +will indicate if the operation is an input, and +.Va size +will indicate the size of the access. +.Ss Mem Assist +When a VM exit occurs with reason +.Cd NVMM_VCPU_EXIT_MEMORY , +it is necessary for emulator software to emulate the associated memory +operation. +.Nm +provides an easy way for emulator software to perform that, similar to the I/O +Assist. +.Pp +.Fn nvmm_assist_mem +will call the registered +.Fa mem +callback function and give it a +.Cd nvmm_mem +structure as argument. +This structure describes a Mem transaction: +.Bd -literal +struct nvmm_mem { + struct nvmm_machine *mach; + struct nvmm_vcpu *vcpu; + gpaddr_t gpa; + bool write; + size_t size; + uint8_t *data; +}; +.Ed +.Pp +The callback can emulate the operation using this descriptor, following two +unique cases: +.Pp +.Bl -bullet -offset indent -compact +.It +The operation is a read. +In this case, the callback should fill +.Va data +with the desired value. +.It +The operation is a write. +In this case, the callback should read +.Va data +to retrieve the desired value. +.El +.Pp +In either case, +.Va gpa +will indicate the guest physical address, +.Va write +will indicate if the access is a write, and +.Va size +will indicate the size of the access. +.Sh RETURN VALUES +Upon successful completion, each of these functions returns zero. +Otherwise, a value of \-1 is returned and the global +variable +.Va errno +is set to indicate the error. +.Sh FILES +.Bl -tag -width XXXX -compact +.It Lk https://www.netbsd.org/~skrll/nvmm/nvmm-demo.tgz +Functional example (demonstrator). +Contains an emulator that uses the +.Nm +API, and a small kernel that exercises this emulator. +.It Pa src/sys/dev/nvmm/ +Source code of the kernel NVMM driver. +.It Pa src/lib/libnvmm/ +Source code of the +.Nm +library. +.El +.Sh ERRORS +These functions will fail if: +.Bl -tag -width [ENOBUFS] +.It Bq Er EEXIST +An attempt was made to create a machine or a VCPU that already exists. +.It Bq Er EFAULT +An attempt was made to emulate a memory-based operation in a guest, and the +guest page tables did not have the permissions necessary for the operation +to complete successfully. +.It Bq Er EINVAL +An inappropriate parameter was used. +.It Bq Er ENOBUFS +The maximum number of machines or VCPUs was reached. +.It Bq Er ENOENT +A query was made on a machine or a VCPU that does not exist. +.It Bq Er EPERM +An attempt was made to access a machine that does not belong to the process. +.El +.Sh SEE ALSO +.Xr nvmm 4 , +.Xr nvmmctl 8 +.Sh AUTHORS +NVMM was designed and implemented by +.An Maxime Villard . diff --git a/static/netbsd/man3/libpaa.3 b/static/netbsd/man3/libpaa.3 new file mode 100644 index 00000000..c5a63510 --- /dev/null +++ b/static/netbsd/man3/libpaa.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: libpaa.3,v 1.4 2014/03/18 18:20:35 riastradh Exp $ +.\" +.\" Copyright (c) 2009,2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This manual page is derived from software contributed to The +.\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org) +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 9, 2010 +.Dt LIBPAA 3 +.Os +.Sh NAME +.Nm libpaa +.Nd Public key Access Authentication Library +.Sh LIBRARY +.Lb libpaa +.Sh SYNOPSIS +.In libpaa.h +.Ft int +.Fo paa_server_init +.Fa "paa_server_info_t *server" "unsigned secretsize" +.Fc +.Ft int +.Fo paa_format_challenge +.Fa "paa_challenge_t *challenge" "paa_server_info_t *server" +.Fa "char *buf" "size_t size" +.Fc +.Ft int +.Fo paa_format_response +.Fa "paa_response_t *response" "netpgp_t *netpgp" "char *in" +.Fa "char *out" "size_t outsize" +.Fc +.Ft int +.Fo paa_check_response +.Fa "paa_challenge_t *challenge" "paa_identity_t *id" +.Fa "netpgp_t *netpgp" "char *response" +.Fc +.Ft int +.Fo paa_print_identity +.Fa "FILE *fp" "paa_identity_t *id" +.Fc +.Sh DESCRIPTION +.Nm +is a library interface which provides an authentication mechanism +layered on top of +.Xr libnetpgp 3 . +This is targeted at web services, and allows authentication by +means of digitally signing a generated challenge. +By verifying the signed response from the client, the server +can verify the identity of the user receiving the challenge, +and producing the signed response. +Random seeds and blinded secrets are used to protect against +spoofed signatures. +.Pp +The main reason for writing this authentication mechanism is +so that identities can be verified across a network without +transferring any secret information across the wire. +.Pp +Binary information is transferred using internal base64 +functions. +.Pp +In the server +process, the server information is initialised using the +.Fn paa_server_init +function, which will set up the random data and secrets. +The challenge is generated using the +.Fn paa_format_challenge +function. +This will format the challenge into the buffer provided, +and can be transferred to the client using any means. +.Pp +The client reads the challenge, and produces a response +using the +.Fn paa_format_response +function to format the response in the buffer provided. +This response is given to the server. +.Pp +In the server, the response is verified using +the +.Fn paa_check_response +function. +If a positive verification has occurred, the identity of +various fields in the response can be displayed +using the +.Fn paa_print_identity +function. +.Sh SEE ALSO +.Xr libnetpgp 3 , +.Xr sha1 3 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org diff --git a/static/netbsd/man3/libperfuse.3 b/static/netbsd/man3/libperfuse.3 new file mode 100644 index 00000000..f5081fcc --- /dev/null +++ b/static/netbsd/man3/libperfuse.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: libperfuse.3,v 1.7 2019/09/08 11:34:56 uwe Exp $ +.\" +.\" Copyright (c) 2010 Emmanuel Dreyfus. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 23, 2019 +.Dt LIBPERFUSE 3 +.Os +.Sh NAME +.Nm perfuse_mount , +.Nm perfuse_open +.Nd Request a +.Xr puffs 3 +mount from +.Xr perfused 8 +.Sh LIBRARY +.Lb libperfuse +.Sh SYNOPSIS +.In perfuse.h +.Ft int +.Fn perfuse_mount "const char *source" "const char *dir" "const char *filesystemtype" "long int mountflags" "void *data" +.Ft int +.Fn perfuse_open "const char *path" "int flags" +.Sh DESCRIPTION +.Fn perfuse_mount +sends a mount request to +.Xr perfused 8 . +It is intended as a drop-in replacement for +.Xr mount 2 +for FUSE file systems daemons and libraries, so that they can work with +.Xr perfused 8 . +.Pp +The function prototype mimics Linux's +.Xr mount 2 , +with the following arguments: +.Bl -tag -width Ar +.It Ar source +The source file system that will appear in +.Xr df 1 +and +.Xr mount 8 +listings. +Defaults to +.Pa /dev/fuse +if +.Dv NULL . +.It Ar dir +The file system mount point. +.It Ar filesystemtype +The file system type, as displayed by +.Xr df 1 +and +.Xr mount 8 . +Defaults to +.Qq Li fuse +if +.Dv NULL . +.It Ar mountflags +This contains the same value as a +.Xr mount 2 +.Ar flags +argument. +.It Ar data +This contains the same value as a +.Xr mount 2 +.Ar data +argument. +.El +.Pp +.Fn perfuse_open +is a drop-in replacement for the +.Xr open 2 +system call where +.Pa /dev/fuse +is used. +If +.Ar path +is different than +.Pa /dev/fuse , +.Fn perfuse_open +handles control to the regular +.Xr open 2 . +.Sh RETURN VALUES +.Fn perfuse_mount +returns a file descriptor to the +.Pa /dev/fuse +socket on success, and causes exit on failure. +.Sh ENVIRONMENT +.Bl -tag -width Ev +.It Ev PERFUSE_OPTIONS +Comma-separated values controlling the usage of some FUSE methods. +Allowed values are +.Li enable_access , +.Li disable_access , +.Li enable_creat , +.Li disable_creat . +.It Ev PERFUSE_BUFSIZE +Set the socket buffer sizes used for communication with the filesystem. +This should be raised as operation throughput requires it. +Default is +.Li 2162688 +bytes, which is enough to queue 16 FUSE packets of maximum 132 kB length. +.El +.\".Sh ERRORS +.\".Fn perfuse_mount +.\"will fail when one of the following occurs: +.\".Bl -tag -width Er +.\".El +.Sh SEE ALSO +.Xr df 1 , +.Xr mount 2 , +.Xr open 2 , +.Xr puffs 3 , +.Xr mount 8 , +.Xr perfused 8 +.Sh AUTHORS +The program was written by +.An Emmanuel Dreyfus +.Aq manu@NetBSD.org . diff --git a/static/netbsd/man3/libquota.3 b/static/netbsd/man3/libquota.3 new file mode 100644 index 00000000..2cd50224 --- /dev/null +++ b/static/netbsd/man3/libquota.3 @@ -0,0 +1,482 @@ +.\" $NetBSD: libquota.3,v 1.5 2012/02/13 13:23:29 wiz Exp $ +.\" +.\" Copyright (c) 2012 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David A. Holland. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.Dd February 13, 2012 +.Dt LIBQUOTA 3 +.Os +.Sh NAME +.Nm libquota , +.Nm quota_open , +.Nm quota_close , +.Nm quota_getmountdevice , +.Nm quota_getmountpoint , +.Nm quota_getimplname , +.Nm quota_getrestrictions , +.Nm quota_getnumidtypes , +.Nm quota_getnumobjtypes , +.Nm quota_idtype_getname , +.Nm quota_objtype_getname , +.Nm quota_objtype_isbytes , +.Nm quota_get , +.Nm quota_put , +.Nm quota_delete , +.Nm quota_opencursor , +.Nm quotacursor_close , +.Nm quotacursor_skipidtype , +.Nm quotacursor_get , +.Nm quotacursor_getn , +.Nm quotacursor_atend , +.Nm quotacursor_rewind , +.Nm quota_quotaon , +.Nm quota_quotaoff , +.Nm quotaval_clear +.Nd disk quota access and control library +.Sh LIBRARY +.Lb libquota +.Sh SYNOPSIS +.In quota.h +.Ft struct quotahandle * +.Fn quota_open "const char *path" +.Ft void +.Fn quota_close "struct quotahandle *qh" +.Ft const char * +.Fn quota_getmountdevice "struct quotahandle *qh" +.Ft const char * +.Fn quota_getmountpoint "struct quotahandle *qh" +.Ft const char * +.Fn quota_getimplname "struct quotahandle *qh" +.Ft unsigned +.Fn quota_getrestrictions "struct quotahandle *qh" +.Ft int +.Fn quota_getnumidtypes "struct quotahandle *qh" +.Ft int +.Fn quota_getnumobjtypes "struct quotahandle *qh" +.Ft const char * +.Fn quota_idtype_getname "struct quotahandle *qh" "int idtype" +.Ft const char * +.Fn quota_objtype_getname "struct quotahandle *qh" "int objtype" +.Ft int +.Fn quota_objtype_isbytes "struct quotahandle *qh" "int objtype" +.Ft int +.Fn quota_get "struct quotahandle *qh" "const struct quotakey *key" "struct quotaval *val" +.Ft int +.Fn quota_put "struct quotahandle *qh" "const struct quotakey *key" "const struct quotaval *val" +.Ft int +.Fn quota_delete "struct quotahandle *qh" "const struct quotakey *key" +.Ft struct quotacursor * +.Fn quota_opencursor "struct quotahandle *qh" +.Ft void +.Fn quotacursor_close "struct quotacursor *qc" +.Ft int +.Fn quotacursor_skipidtype "struct quotacursor *qc" "int idtype" +.Ft int +.Fn quotacursor_get "struct quotacursor *qc" "struct quotakey *key" "const struct quotaval *val" +.Ft int +.Fn quotacursor_getn "struct quotacursor *qc" "struct quotakey *keys" "const struct quotaval *vals" "unsigned maxnum" +.Ft int +.Fn quotacursor_atend "struct quotacursor *qc" +.Ft int +.Fn quotacursor_rewind "struct quotacursor *qc" +.Ft int +.Fn quota_quotaon "struct quotahandle *qh" "int idtype" +.Ft int +.Fn quota_quotaoff "struct quotahandle *qh" "int idtype" +.Ft void +.Fn quotaval_clear "struct quotaval *qv" +.Sh DESCRIPTION +The +.Nm +library provides uniform access to disk quota functionality across all +file systems and file system types. +Programs should be linked with +.Fl lquota lrpcsvc . +.Pp +Quota information is organized as a key/value store, where the key +names a particular limit and the value contains information about that +limit. +The information includes a configured +.Em soft limit , +.Em hard limit , +and +.Em grace time , +as well as the current usage and the expire time of any pending grace +period. +The soft limit may be exceeded temporarily, but only for the length of +time specified; after that further usage is rejected. +The hard limit may not be exceeded. +.Pp +Each mounted file system that supports quotas contains its own +key/value store for quota information. +.Pq The underlying representation may vary. +The library supports get, put, and delete operations, as well as a +cursor interface for iterating an entire store. +It also provides functions for inspecting the properties of a +particular file system's quota implementation. +.Pp +All functionality is accessed by first calling +.Fn quota_open +on a particular volume to get a handle for that volume's quota +information. +Other operations can be called at this point. +The +.Fn quota_close +function should be called when done to release internal resources. +.Ss Data Structures +The key part of the key/value schema is defined as +.Dv struct quotakey , +which contains the following members: +.Bl -tag -width 4n +.It int qk_idtype +The type of principal (user, group, etc.) to retrieve quota +information for. +.It id_t qk_id +The ID number (uid, gid, etc.) to retrieve quota information for. +.It int qk_objtype +The type of file system resource (blocks, files, etc.) to retrieve +quota information for. +.El +The value part of the key/value schema is defined as +.Dv struct quotaval , +which contains the following members: +.Bl -tag -width 4n +.It uint64_t qv_softlimit +The soft limit. +.It uint64_t qv_hardlimit +The hard limit. +.It uint64_t qv_usage +The current usage. +.It int64_t qv_expiretime +The time +.Pq in time_t terms +at which the current grace period, if any, expires. +.It int64_t qv_grace +The configured length of grace period. +.El +.Ss Constants +The basic ID and object types are predefined. +.Dv QUOTA_IDTYPE_USER +is the code number for quotas on users; +.Dv QUOTA_IDTYPE_GROUP +is the code number for quotas on groups. +Similarly, +.Dv QUOTA_OBJTYPE_BLOCKS +retrieves limits on file system blocks, while +.Dv QUOTA_OBJTYPE_FILES +retrieves limits on the number of existing files. +.Pp +Some backends support a default configuration; this can be accessed by +using +.Dv QUOTA_DEFAULTID +as the ID number. +.Pp +When no limit is in place, the value +.Dv QUOTA_NOLIMIT +appears in the limit fields of struct quotaval, and if no time is +indicated the value +.Dv QUOTA_NOTIME +appears in the time fields. +.Ss Quota v1 +The historic BSD quota implementation for FFS, known as +.Dq quota v1 , +has additional restrictions and requirements. +All file systems to be mounted with v1 quotas +.Em must +be listed in +.Xr fstab 5 +with the +.Dv userquota +and/or +.Dv groupquota +mount options specified. +The tools +.Xr quotacheck 8 +and +.Xr quotaon 8 +must be used on quota v1 volumes before quotas become fully +operational, and +.Xr quotaoff 8 +must be used at system shutdown time. +The +.Nm +library provides access to quota v1 data even before +.Xr quotaon 8 +is called by direct access to the on-disk quota information. +However, this method is not recommended. +Note that the +.Dv userquota +and +.Dv groupquota +mount options are read and interpreted at quotaon time, not +.Xr mount 8 +time. +This allowed historic implementations to avoid storing the path in the +kernel. +.Ss Semantic Restrictions +Some quota implementations are restricted in their functionality or +semantics. +The following restriction codes are defined to allow +.Nm libquota +client code to adapt or to provide more helpful diagnostic messages. +.Bl -tag -width 4n +.It QUOTA_RESTRICT_NEEDSQUOTACHECK +The quota implementation is a quota v1 system and requires the +old-style quota check and mount process as described in the +previous section. +.It QUOTA_RESTRICT_UNIFORMGRACE +The grace period for how long a quota can be over the soft limit can +be specified only once, globally, for all principals. +It is set via the default +.Pq Dv QUOTA_DEFAULTID +quota entry. +.It QUOTA_RESTRICT_32BIT +The values in struct quotaval are limited to 32 bits wide. +Larger values will be treated as +.Dv QUOTA_NOLIMIT . +.It QUOTA_RESTRICT_READONLY +The quota information is read-only. +Attempts to update it using +.Fn quota_put +or other functions will fail. +.El +.Ss Function Descriptions +.Bl -tag -width 4n +.It Fn quota_open +Open a volume for access with the quota library. +The +.Fa path +may be any file or file system object on the desired volume. +On success, returns a quota handle for further use. +On failure, returns +.Dv NULL +and sets +.Dv errno . +.It Fn quota_close +Close a quota handle previously created with +.Fn quota_open . +.It Fn quota_getmountdevice +Return the path of the device the target volume is mounted from. +This is retrieved with +.Xr statvfs 2 . +.It Fn quota_getmountpoint +Return the path in the directory tree where the target volume is +mounted. +This is retrieved with +.Xr statvfs 2 . +.It Fn quota_getimplname +Return a human-readable string describing the underlying quota +implementation. +Client programs should not attempt to interpret this string. +.It Fn quota_getrestrictions +Return the semantic restriction flags for the underlying quota +implementation. +The possible flags are described above. +.It Fn quota_getnumidtypes +Return the number of ID types supported by this volume. +Will ordinarily be two; ideally code using this library should be +prepared for other values, including possibly one. +However, as of this writing it is difficult to foresee any other +likely ID types beyond users and groups. +.It Fn quota_getnumobjtypes +Return the number of object types supported by this volume. +Will ordinarily be two; ideally code using this library should be +prepared for larger values. +As of this writing there are deployed file systems +.Pq though not in Nx +that support quotas for more than two object types. +.It Fn quota_idtype_getname +Return a printable name for an ID type. +.It Fn quota_objtype_getname +Return a printable name for an object type. +.It Fn quota_objtype_isbytes +Return true if the object type refers to something measured in bytes. +.Pq This can be used for calling Xr humanize_number 3 . +.It Fn quota_get +Return, in +.Fa val , +the quota information associated with the quota key +.Fa key . +On failure, returns \-1 and sets +.Dv errno . +.It Fn quota_put +Update the quota information associated with the quota key +.Fa key +from the value +.Fa val . +Note that the current usage +.Pq which is maintained by the file system +cannot be updated via +.Nm . +If it becomes incorrect or corrupted, +.Xr quotacheck 8 +or +.Xr fsck 8 +must be used. +Also note that sufficient privilege is required. +On failure, returns \-1 and sets +.Dv errno . +.It Fn quota_delete +Remove the quota information associated with the quota key +.Fa key . +Depending on the backend implementation this might just blank it out +or might physically remove the quota record from disk. +Note that sufficient privilege is required. +On failure, returns \-1 and sets +.Dv errno . +.It Fn quota_opencursor +Prepare to iterate the store by creating a cursor. +The cursor starts at the beginning of the store. +On success, returns a pointer to a cursor object that can be used with +the quotacursor calls. +On failure, returns +.Dv NULL +and sets +.Dv errno . +.It Fn quotacursor_close +Destroy a cursor previously created with +.Fn quota_opencursor . +This releases internal storage. +.It Fn quotacursor_skipidtype +Hint to the implementation that the caller is not interested in +retrieving records with ID type +.Fa idtype . +As this is a hint, the implementation may ignore it; the caller should +still be prepared to receive and ignore such records. +On failure, returns \-1 and sets +.Dv errno . +.It Fn quotacursor_get +Retrieve the next record +.Pq key and value +from a cursor. +Note that records are not guaranteed to be returned in any particular +order. +On failure, returns \-1 and sets +.Dv errno . +.It Fn quotacursor_getn +Retrieve the next several keys and values from a cursor. +Up to +.Fa maxnum +keys and values will be stored in the arrays pointed to by the +.Fa keys +and +.Fa vals +arguments. +Returns the number of records retrieved. +On failure, returns \-1 and sets +.Dv errno . +.It Fn quotacursor_atend +Returns true if the cursor has reached the end of the quota store. +.It Fn quotacursor_rewind +Resets a cursor to point to the beginning of the quota store, allowing +another pass over the data. +.It Fn quota_quotaon +For old-style quota v1 implementations, this function enables quotas +for the specified ID type. +To ensure that the quota files are consistent with the file system +state, +.Xr quotacheck 8 +must have been run beforehand. +As described above, the file system volume must be listed in +.Xr fstab 5 +and the corresponding old-style mount option, +.Dv userquota +or +.Dv groupquota , +must be set therein. +The path name for the quota file is retrieved from +.Xr fstab 5 +and passed to the kernel. +This function will fail if used on newer quota implementations with +in-file-system quotas. +.It Fn quota_quotaoff +For old-style quotas, this function disables quotas for the specified +ID type. +This function will fail if used on newer quota implementations with +in-file-system quotas. +.It Fn quotaval_clear +A convenience function for initializing a struct quotaval instance +to the default empty state. +.El +.\" .Sh EXAMPLES +.\" XXX would be nice to have an example, particularly of iteration. +.Sh ERRORS +.\" XXX this is woefully incomplete, particularly about errors that +.\" can be generated inside file systems. +Error conditions include: +.Bl -tag -width Er +.\" .It Bq Er EBUSY +.\" .Fn quota_quotaon +.\" was attempted on a volume that is not a quota v1 volume. +.It Bq Er EDEADLK +An inconsistency was detected during +.Fn quotacursor_get +or +.Fn quotacursor_getn . +The application should discard information collected so far and use +.Fn quotacursor_rewind +to start the iteration over. +.It Bq Er ENOENT +The quota information requested from +.Fn quota_get +does not exist. +.It Bq Er ENXIO +The +.Fa path +passed to +.Fn quota_open +was on a volume whose quota support is not enabled. +.It Bq Er EOPNOTSUPP +The +.Fa path +passed to +.Fn quota_open +was on a volume that has no quota support. +Or, the iterator functions, +.Fn quota_put , +or other unsupported operations were attempted on an NFS volume, +or on some other volume type that does not support the full +semantic range of quota information. +.El +.Sh SEE ALSO +.Xr quota 1 , +.Xr edquota 8 , +.Xr mount_ffs 8 , +.Xr mount_nfs 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr repquota 8 , +.Xr rpc.rquotad 8 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 6.0 . +.Sh AUTHORS +The +.Nm +library was written by +.An David A. Holland . diff --git a/static/netbsd/man3/libradius.3 b/static/netbsd/man3/libradius.3 new file mode 100644 index 00000000..b86c0c8e --- /dev/null +++ b/static/netbsd/man3/libradius.3 @@ -0,0 +1,556 @@ +.\" Copyright 1998 Juniper Networks, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libradius/libradius.3,v 1.17 2004/04/27 15:00:29 ru Exp $ +.\" $NetBSD: libradius.3,v 1.2 2005/12/26 19:40:15 perry Exp $ +.\" +.Dd April 27, 2004 +.Dt LIBRADIUS 3 +.Os +.Sh NAME +.Nm libradius +.Nd RADIUS client library +.Sh SYNOPSIS +.In radlib.h +.Ft "struct rad_handle *" +.Fn rad_acct_open "void" +.Ft int +.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" +.Ft "struct rad_handle *" +.Fn rad_auth_open "void" +.Ft void +.Fn rad_close "struct rad_handle *h" +.Ft int +.Fn rad_config "struct rad_handle *h" "const char *file" +.Ft int +.Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv" +.Ft int +.Fn rad_create_request "struct rad_handle *h" "int code" +.Ft "struct in_addr" +.Fn rad_cvt_addr "const void *data" +.Ft uint32_t +.Fn rad_cvt_int "const void *data" +.Ft char * +.Fn rad_cvt_string "const void *data" "size_t len" +.Ft int +.Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len" +.Ft int +.Fn rad_get_vendor_attr "uint32_t *vendor" "const void **data" "size_t *len" +.Ft int +.Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv" +.Ft int +.Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr" +.Ft int +.Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len" +.Ft int +.Fn rad_put_int "struct rad_handle *h" "int type" "uint32_t value" +.Ft int +.Fn rad_put_string "struct rad_handle *h" "int type" "const char *str" +.Ft int +.Fn rad_put_message_authentic "struct rad_handle *h" +.Ft int +.Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr" +.Ft int +.Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len" +.Ft int +.Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "uint32_t value" +.Ft int +.Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str" +.Ft ssize_t +.Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len" +.Ft int +.Fn rad_send_request "struct rad_handle *h" +.Ft "const char *" +.Fn rad_server_secret "struct rad_handle *h" +.Ft u_char * +.Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen" +.Ft u_char * +.Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len" +.Ft "const char *" +.Fn rad_strerror "struct rad_handle *h" +.Sh DESCRIPTION +The +.Nm +library implements the client side of the Remote Authentication Dial +In User Service (RADIUS). +RADIUS, defined in RFCs 2865 and 2866, +allows clients to perform authentication and accounting by means of +network requests to remote servers. +.Ss Initialization +To use the library, an application must first call +.Fn rad_auth_open +or +.Fn rad_acct_open +to obtain a +.Vt "struct rad_handle *" , +which provides the context for subsequent operations. +The former function is used for RADIUS authentication and the +latter is used for RADIUS accounting. +Calls to +.Fn rad_auth_open +and +.Fn rad_acct_open +always succeed unless insufficient virtual memory is available. +If +the necessary memory cannot be allocated, the functions return +.Dv NULL . +For compatibility with earlier versions of this library, +.Fn rad_open +is provided as a synonym for +.Fn rad_auth_open . +.Pp +Before issuing any RADIUS requests, the library must be made aware +of the servers it can contact. +The easiest way to configure the +library is to call +.Fn rad_config . +.Fn rad_config +causes the library to read a configuration file whose format is +described in +.Xr radius.conf 5 . +The pathname of the configuration file is passed as the +.Fa file +argument to +.Fn rad_config . +This argument may also be given as +.Dv NULL , +in which case the standard configuration file +.Pa /etc/radius.conf +is used. +.Fn rad_config +returns 0 on success, or \-1 if an error occurs. +.Pp +The library can also be configured programmatically by calls to +.Fn rad_add_server . +The +.Fa host +parameter specifies the server host, either as a fully qualified +domain name or as a dotted-quad IP address in text form. +The +.Fa port +parameter specifies the UDP port to contact on the server. +If +.Fa port +is given as 0, the library looks up the +.Ql radius/udp +or +.Ql radacct/udp +service in the network +.Xr services 5 +database, and uses the port found +there. +If no entry is found, the library uses the standard RADIUS +ports, 1812 for authentication and 1813 for accounting. +The shared secret for the server host is passed to the +.Fa secret +parameter. +It may be any +.Dv NUL Ns -terminated +string of bytes. +The RADIUS protocol +ignores all but the leading 128 bytes of the shared secret. +The timeout for receiving replies from the server is passed to the +.Fa timeout +parameter, in units of seconds. +The maximum number of repeated +requests to make before giving up is passed into the +.Fa max_tries +parameter. +.Fn rad_add_server +returns 0 on success, or \-1 if an error occurs. +.Pp +.Fn rad_add_server +may be called multiple times, and it may be used together with +.Fn rad_config . +At most 10 servers may be specified. +When multiple servers are given, they are tried in round-robin +fashion until a valid response is received, or until each server's +.Fa max_tries +limit has been reached. +.Ss Creating a RADIUS Request +A RADIUS request consists of a code specifying the kind of request, +and zero or more attributes which provide additional information. +To +begin constructing a new request, call +.Fn rad_create_request . +In addition to the usual +.Vt "struct rad_handle *" , +this function takes a +.Fa code +parameter which specifies the type of the request. +Most often this +will be +.Dv RAD_ACCESS_REQUEST . +.Fn rad_create_request +returns 0 on success, or \-1 on if an error occurs. +.Pp +After the request has been created with +.Fn rad_create_request , +attributes can be attached to it. +This is done through calls to +.Fn rad_put_addr , +.Fn rad_put_int , +and +.Fn rad_put_string . +Each accepts a +.Fa type +parameter identifying the attribute, and a value which may be +an Internet address, an integer, or a +.Dv NUL Ns -terminated +string, +respectively. +Alternatively, +.Fn rad_put_vendor_addr , +.Fn rad_put_vendor_int +or +.Fn rad_put_vendor_string +may be used to specify vendor specific attributes. +Vendor specific +definitions may be found in +.In radlib_vs.h +.Pp +The library also provides a function +.Fn rad_put_attr +which can be used to supply a raw, uninterpreted attribute. +The +.Fa data +argument points to an array of bytes, and the +.Fa len +argument specifies its length. +.Pp +It is possible adding the Message-Authenticator to the request. +This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579). +This attribute must be present in any packet that includes an EAP-Message +attribute. +It can be added by using the +.Fn rad_put_message_authentic +function. +The +.Nm +library +calculates the HMAC-MD5 hash implicitly before sending the request. +If the Message-Authenticator was found inside the response packet, +then the packet is silently dropped, if the validation failed. +In order to get this feature, the library should be compiled with +OpenSSL support. +.Pp +The +.Fn rad_put_X +functions return 0 on success, or \-1 if an error occurs. +.Ss Sending the Request and Receiving the Response +After the RADIUS request has been constructed, it is sent either by means of +.Fn rad_send_request +or by a combination of calls to +.Fn rad_init_send_request +and +.Fn rad_continue_send_request . +.Pp +The +.Fn rad_send_request +function sends the request and waits for a valid reply, +retrying the defined servers in round-robin fashion as necessary. +If a valid response is received, +.Fn rad_send_request +returns the RADIUS code which specifies the type of the response. +This will typically be +.Dv RAD_ACCESS_ACCEPT , +.Dv RAD_ACCESS_REJECT , +or +.Dv RAD_ACCESS_CHALLENGE . +If no valid response is received, +.Fn rad_send_request +returns \-1. +.Pp +As an alternative, if you do not wish to block waiting for a response, +.Fn rad_init_send_request +and +.Fn rad_continue_send_request +may be used instead. +If a reply is received from the RADIUS server or a +timeout occurs, these functions return a value as described for +.Fn rad_send_request . +Otherwise, a value of zero is returned and the values pointed to by +.Fa fd +and +.Fa tv +are set to the descriptor and timeout that should be passed to +.Xr select 2 . +.Pp +.Fn rad_init_send_request +must be called first, followed by repeated calls to +.Fn rad_continue_send_request +as long as a return value of zero is given. +Between each call, the application should call +.Xr select 2 , +passing +.Fa *fd +as a read descriptor and timing out after the interval specified by +.Fa tv . +When +.Xr select 2 +returns, +.Fn rad_continue_send_request +should be called with +.Fa selected +set to a non-zero value if +.Xr select 2 +indicated that the descriptor is readable. +.Pp +Like RADIUS requests, each response may contain zero or more +attributes. +After a response has been received successfully by +.Fn rad_send_request +or +.Fn rad_continue_send_request , +its attributes can be extracted one by one using +.Fn rad_get_attr . +Each time +.Fn rad_get_attr +is called, it gets the next attribute from the current response, and +stores a pointer to the data and the length of the data via the +reference parameters +.Fa data +and +.Fa len , +respectively. +Note that the data resides in the response itself, +and must not be modified. +A successful call to +.Fn rad_get_attr +returns the RADIUS attribute type. +If no more attributes remain in the current response, +.Fn rad_get_attr +returns 0. +If an error such as a malformed attribute is detected, \-1 is +returned. +.Pp +If +.Fn rad_get_attr +returns +.Dv RAD_VENDOR_SPECIFIC , +.Fn rad_get_vendor_attr +may be called to determine the vendor. +The vendor specific RADIUS attribute type is returned. +The reference parameters +.Fa data +and +.Fa len +(as returned from +.Fn rad_get_attr ) +are passed to +.Fn rad_get_vendor_attr , +and are adjusted to point to the vendor specific attribute data. +.Pp +The common types of attributes can be decoded using +.Fn rad_cvt_addr , +.Fn rad_cvt_int , +and +.Fn rad_cvt_string . +These functions accept a pointer to the attribute data, which should +have been obtained using +.Fn rad_get_attr +and optionally +.Fn rad_get_vendor_attr . +In the case of +.Fn rad_cvt_string , +the length +.Fa len +must also be given. +These functions interpret the attribute as an +Internet address, an integer, or a string, respectively, and return +its value. +.Fn rad_cvt_string +returns its value as a +.Dv NUL Ns -terminated +string in dynamically +allocated memory. +The application should free the string using +.Xr free 3 +when it is no longer needed. +.Pp +If insufficient virtual memory is available, +.Fn rad_cvt_string +returns +.Dv NULL . +.Fn rad_cvt_addr +and +.Fn rad_cvt_int +cannot fail. +.Pp +The +.Fn rad_request_authenticator +function may be used to obtain the Request-Authenticator attribute value +associated with the current RADIUS server according to the supplied +rad_handle. +The target buffer +.Fa buf +of length +.Fa len +must be supplied and should be at least 16 bytes. +The return value is the number of bytes written to +.Fa buf +or \-1 to indicate that +.Fa len +was not large enough. +.Pp +The +.Fn rad_server_secret +returns the secret shared with the current RADIUS server according to the +supplied rad_handle. +.Pp +The +.Fn rad_demangle +function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys. +The return value is +.Dv NULL +on failure, or the plaintext attribute. +This value should be freed using +.Xr free 3 +when it is no longer needed. +.Pp +The +.Fn rad_demangle_mppe_key +function demangles the send- and recv-keys when using MPPE (see RFC 2548). +The return value is +.Dv NULL +on failure, or the plaintext attribute. +This value should be freed using +.Xr free 3 +when it is no longer needed. +.Ss Obtaining Error Messages +Those functions which accept a +.Vt "struct rad_handle *" +argument record an error message if they fail. +The error message +can be retrieved by calling +.Fn rad_strerror . +The message text is overwritten on each new error for the given +.Vt "struct rad_handle *" . +Thus the message must be copied if it is to be preserved through +subsequent library calls using the same handle. +.Ss Cleanup +To free the resources used by the RADIUS library, call +.Fn rad_close . +.Sh RETURN VALUES +The following functions return a non-negative value on success. +If +they detect an error, they return \-1 and record an error message +which can be retrieved using +.Fn rad_strerror . +.Pp +.Bl -item -offset indent -compact +.It +.Fn rad_add_server +.It +.Fn rad_config +.It +.Fn rad_create_request +.It +.Fn rad_get_attr +.It +.Fn rad_put_addr +.It +.Fn rad_put_attr +.It +.Fn rad_put_int +.It +.Fn rad_put_string +.It +.Fn rad_put_message_authentic +.It +.Fn rad_init_send_request +.It +.Fn rad_continue_send_request +.It +.Fn rad_send_request +.El +.Pp +The following functions return a +.No non- Ns Dv NULL +pointer on success. +If they are unable to allocate sufficient +virtual memory, they return +.Dv NULL , +without recording an error message. +.Pp +.Bl -item -offset indent -compact +.It +.Fn rad_acct_open +.It +.Fn rad_auth_open +.It +.Fn rad_cvt_string +.El +.Pp +The following functions return a +.No non- Ns Dv NULL +pointer on success. +If they fail, they return +.Dv NULL , +with recording an error message. +.Pp +.Bl -item -offset indent -compact +.It +.Fn rad_demangle +.It +.Fn rad_demangle_mppe_key +.El +.Sh FILES +.Bl -tag -width indent +.It Pa /etc/radius.conf +.El +.Sh SEE ALSO +.Xr radius.conf 5 +.Rs +.%A "C. Rigney, et al" +.%T "Remote Authentication Dial In User Service (RADIUS)" +.%O "RFC 2865" +.Re +.Rs +.%A "C. Rigney" +.%T "RADIUS Accounting" +.%O "RFC 2866" +.Re +.Rs +.%A G. Zorn +.%T "Microsoft Vendor-specific RADIUS attributes" +.%O RFC 2548 +.Re +.Rs +.%A C. Rigney, et al +.%T "RADIUS extensions" +.%O RFC 2869 +.Re +.Sh AUTHORS +.An -nosplit +This software was originally written by +.An John Polstra , +and donated to the +.Fx +project by Juniper Networks, Inc. +.An Oleg Semyonov +subsequently added the ability to perform RADIUS +accounting. +Later additions and changes by +.An Michael Bretterklieber . diff --git a/static/netbsd/man3/librtld_db.3 b/static/netbsd/man3/librtld_db.3 new file mode 100644 index 00000000..149adc71 --- /dev/null +++ b/static/netbsd/man3/librtld_db.3 @@ -0,0 +1,194 @@ +.\" $NetBSD: librtld_db.3,v 1.2 2015/09/28 21:50:48 wiz Exp $ +.\"- +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This software was developed by Rui Paulo under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/librtld_db/librtld_db.3 276294 2014-12-27 08:31:52Z joel $ +.\" +.Dd June 10, 2010 +.Dt LIBRTLD_DB 3 +.Os +.Sh NAME +.Nm librtld_db +.Nd library for run-time linker debugging +.Sh LIBRARY +.Lb librtld_db +.Sh SYNOPSIS +.In rtld_db.h +.Ft void +.Fo rd_delete +.Fa "rd_agent_t *rdap" +.Fc +.Ft char * +.Fo rd_errstr +.Fa "rd_err_e rderr" +.Fc +.Ft rd_err_e +.Fo rd_event_addr +.Fa "rd_agent_t *rdap, rd_event_e event, rd_notify_t *notify" +.Fc +.Ft rd_err_e +.Fo rd_event_enable +.Fa "rd_agent_t *rdap, int onoff" +.Fc +.Ft rd_err_e +.Fo rd_event_getmsg +.Fa "rd_agent_t *rdap, rd_event_msg_t *msg" +.Fc +.Ft rd_err_e +.Fo rd_init +.Fa "int version" +.Fc +.Ft typedef int +.Fo rl_iter_f +.Fa "const rd_loadobj_t *, void *" +.Fc +.Ft rd_err_e +.Fo rd_loadobj_iter +.Fa "rd_agent_t *rdap, rl_iter_f *cb, void *clnt_data" +.Fc +.Ft void +.Fo rd_log +.Fa "const int onoff" +.Fc +.Ft rd_agent_t * +.Fo rd_new +.Fa "struct proc_handle *php" +.Fc +.Ft rd_err_e +.Fo rd_objpad_enable +.Fa "rd_agent_t *rdap, size_t padsize" +.Fc +.Ft rd_err_e +.Fo rd_plt_resolution +.Fa "rd_agent_t *rdap, uintptr_t pc, struct proc *proc" +.Fa "uintptr_t plt_base, rd_plt_info_t *rpi" +.Fc +.Ft rd_err_e +.Fo rd_reset +.Fa "rd_agent_t *rdap" +.Fc +.Sh DESCRIPTION +The +.Nm librtld_db +library provides a debugging interface to the run-time linker (rtld). +This library must be used along with +.Xr libproc 3 . +.Pp +Most library functions take a +.Ft rd_agent_t +argument. +This argument is an opaque structure containing information associated with +the current status of the agent. +.Pp +Before you start using +.Nm +you should call +.Fn rd_init +with the +.Ft RD_VERSION +argument. +This initializes the library to the correct version your program was compiled +with and provides proper ABI stability. +.Pp +What follows is a description of what each function. +.Pp +.Fn rd_new +creates a new +.Nm +agent. +The +.Ft php +argument should be the +.Ft proc_handle +you received from +.Xr libproc 3 . +.Pp +.Fn rd_reset +resets your previously created agent. +.Pp +.Fn rd_delete +deallocates the resources associated with the agent. +.Pp +.Fn rd_errstr +returns an error string describing the error present in +.Ft rderr . +.Pp +.Fn rd_event_enable +enables reporting of events. +This function always returns RD_OK. +.Pp +.Fn rd_event_addr +returns the event address corresponding to the +.Ft event +parameter. +At the moment we only report events of type RD_NOTIFY_BPT. +.Pp +.Fn rd_event_getmsg +returns the message associated with the latest event. +At the moment only RD_POSTINIT events are supported. +.Pp +.Fn rd_loadobj_iter +allows you to iterate over the program's loaded objects. +.Ft cb +is a callback of type +.Fn rl_iter_f . +.Sh RETURN VALUES +Most functions return an +.Ft rd_err_e +type error. +The error codes are described in the header file for this library. +You can get the error string using +.Fn rd_errstr . +.Sh SEE ALSO +.Xr ld 1 , +.Xr ld.elf_so 1 , +.Xr ld.so 1 , +.Xr rtld 1 , +.Xr libproc 3 +.Sh HISTORY +The +.Nm librtld_db +library first appeared in +.Fx 9.0 +and was modeled after the same library present in the Solaris operating system. +.Sh AUTHORS +The +.Nm librtld_db +library and this manual page were written by +.An Rui Paulo Aq Mt rpaulo@FreeBSD.org +under sponsorship from the +.Fx +Foundation. +.Sh CAVEATS +The functions +.Fn rd_event_enable , +.Fn rd_log , +.Fn rd_objpad_enable , +and +.Fn rd_plt_resolution +are not yet implemented. diff --git a/static/netbsd/man3/libsaslc.3 b/static/netbsd/man3/libsaslc.3 new file mode 100644 index 00000000..3d2889cd --- /dev/null +++ b/static/netbsd/man3/libsaslc.3 @@ -0,0 +1,820 @@ +.\" $NetBSD: libsaslc.3,v 1.17 2025/12/16 12:03:39 nia Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mateusz Kocielski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 3, 2015 +.Dt LIBSASLC 3 +.Os +.Sh NAME +.Nm libsaslc , +.Nm saslc.d , +.Nm saslc_alloc , +.Nm saslc_end , +.Nm saslc_init , +.Nm saslc_sess_init , +.Nm saslc_sess_end , +.Nm saslc_sess_getprop , +.Nm saslc_sess_setprop , +.Nm saslc_sess_cont , +.Nm saslc_sess_decode , +.Nm saslc_sess_encode , +.Nm saslc_sess_getmech , +.Nm saslc_sess_strerror , +.Nm saslc_strerror +.Nd Simple Authentication and Security Layer client library +.Sh LIBRARY +.Lb libsaslc +.Sh SYNOPSIS +.In saslc.h +.Ft saslc_t * +.Fn saslc_alloc "void" +.Ft int +.Fn saslc_end "saslc_t *ctx" +.Ft int +.Fn saslc_init "saslc_t *ctx" "const char *appname" "const char *cfgpath" +.Ft saslc_sess_t * +.Fn saslc_sess_init "saslc_t *ctx" "const char *mechs" "const char *secopts" +.Ft void +.Fn saslc_sess_end "saslc_sess_t *sess" +.Ft const char * +.Fn saslc_sess_getprop "saslc_sess_t *sess" "const char *key" +.Ft int +.Fn saslc_sess_setprop "saslc_sess_t *sess" "const char *key" \ +"const char *value" +.Ft int +.Fn saslc_sess_cont "saslc_sess_t *sess" "const void *in" "size_t inlen" \ +"void* *out" "size_t *outlen" +.Ft ssize_t +.Fn saslc_sess_decode "saslc_sess_t *sess" "const void *in" "size_t inlen" \ +"void* *out" "size_t *outlen" +.Ft ssize_t +.Fn saslc_sess_encode "saslc_sess_t *sess" "const void *in" "size_t inlen" \ +"void* *out" "size_t *outlen" +.Ft const char * +.Fn saslc_sess_getmech "saslc_sess_t *sess" +.Ft const char * +.Fn saslc_sess_strerror "saslc_sess_t *sess" +.Ft const char * +.Fn saslc_strerror "saslc_t *ctx" +.Sh DESCRIPTION +The +.Nm libsaslc +library offers a client interface for the +Simple Authentication and Security Layer +.Pq Tn SASL . +The library is heavily influenced by its use with +.Xr postfix 1 . +.Sh FUNCTIONS +The following functions are available in the library. +.Bl -tag -width compact +.It Fn saslc_alloc "" +The +.Fn saslc_alloc +function allocates and returns a new saslc context. +The context is uninitialized: see +.Fn saslc_init . +Returns +.Dv NULL +on error. +.It Fn saslc_end "ctx" +The +.Fn saslc_end +function destroys and deallocate resources used by the context +.Ar ctx . +The context shouldn't have any sessions assigned to it. +Returns 0 on success and \-1 if the context has active sessions and +cannot be deallocated. +.It Fn saslc_init "ctx" "appname" "cfgpath" +The +.Fn saslc_init +function initializes the saslc context +.Ar ctx . +Based on the application name +.Ar appname , +it also parses the configuration files as indicated by +.Ar cfgpath , +sets up the context and mechanism dictionaries, and creates mechanism +list for the context. +If +.Ar cfgpath +is +.Dv NULL , +it checks the environment variable +.Ev SASLC_CONFIG +for a location and if that is not found it uses the default path +.Pa /etc/saslc.d . +Returns 0 on success and \-1 on failure. +.It Fn saslc_sess_init "ctx" "mechs" "secopts" +The +.Fn saslc_sess_init +function creates new session assigned to the +.Ar ctx +context. +The function chooses the mechanism to use for authentication from the +.Ar mechs +list taking into account the requirements from the +.Ar secopts +list. +Both lists may be space or comma delimited. +The first matching mechanism from the +.Ar mechs +list is used. +See +.Sx CONFIGURATION +below for the supported mechanisms. +The valid security options are +.Pp +.Bl -tag -width "nodictionaryxxx" -offset indent -compact +.It Qo noanonymous Qc +reject anonymous mechanisms +.It Qo noplaintext Qc +reject plaintext mechanisms +.It Qo nodictionary Qc +reject mechanisms prone to dictionary attack +.It Qo noactive Qc +reject mechanisms prone to active non-dictionary attacks +.It Qo mutual Qc +require mutual authentication mechanisms +.El +.Pp +Unknown security options are ignored. +Returns a session handle or +.Dv NULL +on error or no match. +.It Fn saslc_sess_end "sess" +The +.Fn saslc_sess_end +function ends the sasl session +.Ar sess . +It destroys and deallocates all internal resources. +This does not fail. +.It Fn saslc_sess_getprop "sess" "key" +The +.Fn saslc_sess_getprop +function gets the property indicated by the +.Ar key +from the saslc dictionaries. +Dictionaries are searched in following order: session +.Ar sess +dictionary, +context dictionary (global configuration), and mechanism dictionary. +Returns the property value or +.Dv NULL +if the property is not found. +.It Fn saslc_sess_setprop "sess" "key" "value" +The +.Fn saslc_sess_setprop +function sets the property indexed by +.Ar key +to the value +.Ar value +in the session +.Ar sess +dictionary. +If the property already exists in the session dictionary, then the +previous value is replaced by the new value. +If +.Ar value +is +.Dv NULL , +then any previous value in the session dictionary is removed. +Returns 0 on success or \-1 on failure. +.It Fn saslc_sess_cont "sess" "in" "inlen" "out" "outlen" +The +.Fn saslc_sess_cont +function performs one step of the sasl authentication. +It reads +.Ar inlen +bytes of input data +.Pq from the server +from the +.Ar in +buffer and stores +.Ar outlen +bytes of output data in +.Ar out +.Pq for the server . +The user is responsible for freeing memory allocated for +.Ar out . +It returns 0 if the authentication process is completed, 1 if another +step is required, and \-1 on error. +Note that the completion of authentication process does not mean the +client is authenticated; that is determined by the server. +.It Fn saslc_sess_decode "sess" "in" "inlen" "out" "outlen" +The +.Fn saslc_sess_encode +and +.Fn saslc_sess_decode +functions are used to provide the integrity +.Pq Qq auth-int +and confidentiality +.Pq Qq auth-conf +layers for mechanisms that provide them. +They encode and, respectively, decode +.Ar inlen +bytes of data from the +.Ar in +buffer using the method negotiated during authentication. +On error they return \-1. +Otherwise, they return the number of bytes consumed from +.Ar in +and output +.Ar outlen +bytes of data in the +.Ar out +buffer. +The user is responsible for freeing memory allocated for +.Ar out . +If +.Ar outlen +is 0, more data is needed before anything can be output. +Unused input data is stored internally for use in subsequent calls. +.Pp +When decoding, the internal buffers can only be flushed by providing +the missing packet data and it is an error to call +.Fn ssalc_sess_decode +with +.Ar inlen += 0. +The first call of +.Fn saslc_sess_decode +in a session must begin at the start of a packet. +Subsequent calls need not be aligned on packet boundaries. +.It Fn saslc_sess_encode "sess" "in" "inlen" "out" "outlen" +As described above, +.Fn saslc_sess_encode +encodes +.Ar inlen +bytes of data from the +.Ar in +buffer. +Note that unlike when decoding, +the internal buffer may be flushed through the encoder +by calling +.Fn saslc_sess_encode +with +.Ar inlen += 0. +In this case, +.Fn saslc_sess_encode +returns the number of bytes that were flushed from the internal buffer. +.It Fn saslc_sess_getmech "sess" +The +.Fn saslc_sess_getmech +function returns the name of the mechanism used in the session +.Fa sess . +The function does not fail. +.It Fn saslc_sess_strerror "sess" +The +.Fn saslc_sess_strerror +returns the error message associated with the session +.Fa sess . +.It Fn saslc_strerror "ctx" +The +.Fn saslc_strerror +function operates as +.Fn saslc_sess_strerror , +but instead returns the error message string for the last error in the context +.Fa ctx . +Neither function will ever return +.Dv NULL . +.El +.Sh CONFIGURATION +The library uses three types of dictionaries: context (or global), +session, and mechanism, and they are searched in that order by +.Fn saslc_getprop +and the first matching entry is taken. +The context and mechanism dictionaries are loaded from configuration +files, while the session dictionary is loaded by the caller via +.Fn saslc_setprop . +.Pp +The configuration file +.Pa //saslc.conf +is used for the context configuration. +The +.Pa //mech/.conf +file is used for the mechanism configuration. +The +.Pa +is +.Pa /etc/saslc.d +by default, but this may be overridden by the environment variable +.Ev SASLC_CONFIG , +which in turn may be overridden by +.Fn saslc_init . +The +.Pa +is +.Pa saslc +by default, but may also be overridden by +.Fn saslc_init . +Finally, the +.Pa +is the mechanism in use by the session as returned by +.Fn saslc_sess_getmech . +Note that this name is case sensitive. +The currently supported mechanisms are +.Bl -tag -width DIGEST-MD5 -offset indent +.It ANONYMOUS +See RFC 2245 and RFC 4505. +.It CRAM-MD5 +See RFC 2195. +.It DIGEST-MD5 +See RFC 2831. +.It EXTERNAL +See RFC 2222 section 7.4 and RFC 4422 appendix A. +.It GSSAPI +See RFC 2222 section 7.2 and RFC 4752. +This requires GSS, Heimdal, or MIT Kerberos. +.It LOGIN +Non-standard, but common. +.It PLAIN +See RFC 2595 and RFC 4616. +.El +.Pp +If any of the mechanism files are missing they are silently ignored, +unless debugging is enabled. +.Pp +The configuration files consists of lines of the form: +.Bd -literal -offset indent +\fB#\fP comment line +.Ao key Ac \~\~ Ao value Ac \~\~ Bo \fB#\fP comment Bc +.Ed +.Pp +The +.Aq key +is a string beginning with an alpha character +.Pq Xr isalpha 3 +followed by any number of alpha numeric +.Pq Xr isalnum 3 +or underscore +.Sq _ +characters; this is case sensitive. +The +.Aq value +is a number or a quoted string. +More than one +.Aq key +and +.Aq value +pair may occur on a single line, but they may not be broken across +lines. +A +.Sq \fB#\fP +character +.Pq outside a quoted string +indicates that the rest of the line is a comment. +.Pp +NOTE: Currently, no escaping is supported in strings, so they may not +contain quotes. +Numbers must be between 0 and +.Dv LLONG_MAX , +inclusive. +Any base supported by +.Xr strtoll 3 +is allowed. +.Sh PROPERTIES +Most of the control of the library +behavior is done via setting various properties in the context or +mechanism dictionaries via the configuration files or in the session +dictionary with +.Fn saslc_setprop . +The following properties are currently used, as defined in +.Pa saslc.h : +.Bl -tag -width indent +.It SASLC_PROP_AUTHCID Po Qo AUTHCID Qc Pc +The authentication name +.Pq or username +to authenticate with. +Used by all mechanisms except EXTERNAL. +.It SASLC_PROP_AUTHZID Po Qo AUTHZID Qc Pc +The authorization string to use. +By default, this string is empty. +Used by the DIGEST-MD5, EXTERNAL, and PLAIN mechanisms. +.It SASLC_PROP_BASE64IO Po Qo BASE64IO Qc Pc +If true ("true", "yes", or nonzero), then input and output strings are +base64 encoded. +Any other value is false and the input and output strings are not +base64 encoded. +By default, this is assumed true. +Used by all mechanisms. +.It SASLC_PROP_CIPHERMASK Po Qo CIPHERMASK Qc Pc +The mask of ciphers to use with the DIGEST-MD5 mechanism when using +the +.Qq auth-conf +QOP. +By default all supported ciphers are used, but they may be limited by +a comma delimited list of cipher names. +The recognized cipher names for DIGEST-MD5 are: +.Pp +.Bl -tag -offset indent -compact +.It Li "3des" +Triple-DES Cipher in CBC "two keys" mode with 112 bit key +.It Li "aes" +AES Cipher in CBC mode with 128 bit key +.It Li "des" +DES Cipher in CBC mode with 56 bit key +.It Li "rc4" +RC4 Cipher with 128 bit key +.It Li "rc4-40" +RC4 Cipher with 40 bit key +.It Li "rc4-56" +RC4 Cipher with 56 bit key +.El +.Pp +The default value is +.Qq des,3des,rc4,rc4_40,rc4_56,aes . +.Po +Note that +.Qq aes +is not part of the official standard. +.Pc +Used by the DIGEST-MD5 mechanism. +.It SASLC_PROP_DEBUG Po Qo DEBUG Qc Pc +If true, then enable debug messages. +This is implemented as a global variable so it will affect all +sessions. +If set via +.Fn saslc_sess_setprop , +it should be set before the first call to +.Fn saslc_sess_cont . +.Po +Also see the environment variable +.Ev SASLC_ENV_DEBUG +in the +.Sx ENVIRONMENT +section below. +.Pc +.It SASLC_PROP_HOSTNAME Po Qo HOSTNAME Qc Pc +The fully qualified domain name of the server host. +Used by the DIGEST-MD5 and GSSAPI mechanisms. +.It SASLC_PROP_MAXBUF Po Qo MAXBUF Qc Pc +The size of the decode buffer. +This info is sent to the server so that it doesn't send packets that +won't fit in the decode buffer when decoded. +Used by the DIGEST-MD5 and GSSAPI mechanisms. +.It SASLC_PROP_PASSWD Po Qo PASSWD Qc Pc +The password to authenticate with. +Used by the CRAM-MD5, DIGEST-MD5, LOGIN, and PLAIN mechanisms. +.It SASLC_PROP_QOPMASK Po Qo QOPMASK Qc Pc +The mask of QOP (quality of protection) to use with the DIGEST-MD5 +and GSSAPI mechanisms. +By default all supported QOP values are allowed, but they may be +limited by a comma delimited list of QOP values. +The recognized QOP values are: +.Pp +.Bl -tag -offset indent -compact +.It Li "auth" +authentication only +.It Li "auth-int" +authentication with integrity +.It Li "auth-conf" +authentication with confidentiality +.El +.Pp +so the default value of the mask is +.Qq auth,auth-int,auth-conf . +Used by the DIGEST-MD5 and GSSAPI mechanisms. +.It SASLC_PROP_REALM Po Qo REALM Qc Pc +A comma delimited list of possible realms to use for authentication. +The format of each element in the list is +.Qq Oo Ao hostname Ac : Oc Ns Ao realm Ac . +The user specified realm is the first realm in the list with a +matching hostname or, if none is found, the first realm in the list +with no hostname. +If the server provides a list of realms, the one matching the user +specified realm is selected. +If no match is found or if the user didn't provide a realm, the first +realm provided by the server is selected. +If the server doesn't provide any realms, use the user specified realm +if there is one, or the hostname if not. +This is useful when the server provides multiple realms or no realm. +Used by the DIGEST-MD5 mechanism. +.It SASLC_PROP_SECURITY Po Qo SECURITY Qc Pc +A comma delimited list of extra security option flags that will be +.Qo or Qc Ns -ed +together with those passed to +.Fn saslc_sess_init . +Since these flags are used to choose the session mechanism, they are +only effective if they are in the context configuration file. +.Po +See the +.Sx CONFIGURATION +section and the +.Fn saslc_sess_init +function. +.Pc +.It SASLC_PROP_SERVICE Po Qo SERVICE Qc Pc +The service being used, e.g., smtp, imap, etc. +Used by the DIGEST-MD5 and GSSAPI mechanisms. +.It SASLC_PROP_SERVNAME Po Qo SERVNAME Qc Pc +A comma delimited list of possible service names with elements of the +form +.Qq Oo Ao hostname Ac : Oc Ns Ao serv-name Ac +and with the same rules as for the SASLC_PROP_REALM list. +This should only be used if the client uses a DNS name for the service +that is different from the FQDN of the server. +For example, the service name +.Em example.com +might resolve +.Pq via SRV or MX records +into a set of other DNS names, one of which, +.Em mail3.example.com , +is the FQDN of the server. +.Po +See RFC 2831 section 2.1.2 +.Qq serv-name . +.Pc +Used by the DIGEST-MD5 mechanism. +.El +.Pp +The defines in +.Pa saslc.h +should be used in code, but their values need to be used in the config +files. +.Sh ENVIRONMENT +The following environment variables +.Pq defined in Pa saslc.h +affect the behavior of the library: +.Bl -tag -width indent +.It Ev SASLC_ENV_CONFIG Po Qo SASLC_CONFIG Qc Pc +If the environment variable +.Ev SASLC_CONFIG +is set it overrides the default configuration file location of +.Pa /etc/saslc.d . +This may be overridden by +.Fn saslc_init . +.It Ev SASLC_ENV_DEBUG Po Qo SASLC_DEBUG Qc Pc +If set, turn on debugging messages. +This turns on debugging as early as possible and is a global setting. +.El +.Sh GSSAPI AND KERBEROS +The following is a minimal +.Pq Heimdal +Kerberos 5 setup for use with an smtp server that has been configured +to support +.Em SASL +with the +.Em GSSAPI +mechanism. +It assumes that Kerberos and the smtp server will both run on +.Em server.my.domain +and that the client is on +.Em client.my.domain . +It also assumes that the smtp server runs as user +.Em postfix +and group +.Em mail , +and that it is not chrooted. +.Pp +On +.Em server.my.domain +run the following script as +.Em root +and then start the Kerberos server +.Xr kdc 8 . +You will be prompted for a master password for Kerberos and a password +for the +.Em postfix +principal. +.Bd -literal -offset indent +#/bin/sh +.Pp +cat <<- EOF >> /etc/krb5.conf +[libdefaults] + default_realm = MY.DOMAIN +[realms] + MY.DOMAIN = { + kdc = server.my.domain + admin_servers = server.my.domain + } +[domain_realm] + .my.domain = MY.DOMAIN +EOF +.Pp +mkdir /var/heimdal +chown root:wheel /var/heimdal +chmod 755 /var/heimdal +.Pp +kstash +kadmin -l init --realm-max-ticket-life=unlimited \\ + --realm-max-renewable-life=unlimited \\ + MY.DOMAIN +kadmin -l add --max-ticket-life="1 day" \\ + --max-renewable-life="1 week" \\ + --expiration-time=never \\ + --pw-expiration-time=never \\ + --attributes="" \\ + postfix +kadmin -l add --random-key \\ + --max-ticket-life="1 day" \\ + --max-renewable-life="1 week" \\ + --expiration-time=never \\ + --pw-expiration-time=never \\ + --attributes="" \\ + smtp/server.my.domain +kadmin -l ext -k /etc/krb5.keytab smtp/server.my.domain +chown root:mail /etc/krb5.keytab +chmod 640 /etc/krb5.keytab +.Ed +.Pp +Note that the keytab +.Pa /etc/krb5.keytab +must be readable by the smtp server or authentication will fail. +The location of this keytab file may be changed with the environment +variable +.Ev KRB5_KTNAME . +If postfix is the smtp server, note the +.Em import_environment +parameter +.Pq see Xr postconf 5 . +.Pp +On +.Em client.my.domain +copy the keytab file from +.Pa server.my.domain:/etc/krb5.keytab +to +.Pa /etc/krb5.keytab . +Setup the +.Pa /etc/saslc.d +configuration directory +.Po see Sx CONFIGURATION +above +.Pc . +Add the line +.Bd -literal -offset indent +AUTHCID "postfix" +.Ed +.Pp +to the file +.Pa /etc/saslc.d/postfix/mech/GSSAPI.conf +so that the +.Em postfix +principal will be used for authentication. +Enable +.Em SASL +in the smtp client. +Assuming the smtp client is postfix, you will need to add the +following to the +.Pa /etc/postfix/main.cf +file to do this: +.Bd -literal -offset indent +smtp_sasl_auth_enable = yes +smtp_sasl_type = saslc +smtp_sasl_mechanism_filter = GSSAPI +relayhost = [server.my.domain]:submission +.Ed +.Pp +Here we have assumed the +.Em submission +port is the port the server is listening to. +Finally, as +.Em root , +run the command +.Bd -literal -offset indent +su -m postfix -c kinit +.Ed +.Pp +to obtain a ticket for the postfix user with the postfix credential +and you should be good to go! +.Sh FILES +.Bl -tag -width /etc/saslc.d +.It Pa /etc/saslc.d +.El +.Sh EXAMPLES +The following code fragments illustrate the possible use of the +functions described above. +.Bd -literal +int +decode_stream(saslc_sess_t *sess, int fdin, int fdout) +{ + uint8_t buf[BUFSIZE]; + uint8_t *in; + void *out; + size_t inlen, outlen; + ssize_t n, rval; +.Pp + for (;;) { + if ((rval = read(fdin, buf, sizeof(buf))) == \-1) + return \-1; + if (rval == 0) + break; + in = buf; + inlen = rval; + while (inlen > 0) { + rval = saslc_sess_decode(sess, in, inlen, &out, + &outlen); + if (rval == \-1) + return \-1; + if (outlen > 0) { + n = write(fdout, out, outlen); + free(out); + if (n == \-1) + return \-1; + } + in += rval; + inlen -= rval; + } + } + return 0; +} +.Pp +int +encode_stream(saslc_sess_t *sess, int fdin, int fdout) +{ + uint8_t buf[BUFSIZE]; + uint8_t *in; + void *out; + size_t inlen, outlen; + ssize_t n, rval; +.Pp + for (;;) { + if ((rval = read(fdin, buf, sizeof(buf))) == \-1) + return \-1; + if (rval == 0) + break; + in = buf; + inlen = rval; + while (inlen > 0) { + rval = saslc_sess_encode(sess, in, inlen, &out, + &outlen); + if (rval == \-1) + return \-1; + if (outlen > 0) { + n = write(fdout, out, outlen); + free(out); + if (n == \-1) + return \-1; + } + in += rval; + inlen -= rval; + } + } + /* flush internal encoder buffer */ + if (saslc_sess_encode(sess, NULL, 0, &out, &outlen) == \-1) + return \-1; + if (outlen > 0) + if (write(fdout, out, outlen) == \-1) + return \-1; + return 0; +} +.Ed +.Sh COMPATIBILITY +There exist other SASL client library implementations including Cyrus SASL +(http://asg.web.cmu.edu/sasl/sasl-library.html) and GNU SASL +(http://www.gnu.org/software/gsasl/). +.Sh STANDARDS +RFC 2195, RFC 2222, RFC 2245, RFC 2595, RFC 2831, RFC 4422, RFC 4505, +RFC 4616, RFC 4752. +.Sh HISTORY +The +.Nm +library appeared in +.Nx 6.0 . +.Sh CAVEATS +The API was heavily influenced by its use with +.Xr postfix 1 . +.Pp +Currently the ANONYMOUS, LOGIN, PLAIN, CRAM-MD5, DIGEST-MD5, and +GSSAPI mechanisms have been tested and shown to work for +authentication with a +.Xr postfix 1 +SMTP server using the cyrus-sasl library. +LOGIN, PLAIN, CRAM-MD5, and DIGEST-MD5 have also been tested and shown +to work with a +.Xr postfix 1 +SMTP server using a dovecot backend for authentication. +The DIGEST-MD5 and GSSAPI specs also provide for integrity and +confidentiality layers via the +.Fn saslc_sess_encode +and +.Fn saslc_sess_decode +routines, but these have not yet been tested against any servers. diff --git a/static/netbsd/man3/libuv.3 b/static/netbsd/man3/libuv.3 new file mode 100644 index 00000000..811c5acc --- /dev/null +++ b/static/netbsd/man3/libuv.3 @@ -0,0 +1,10855 @@ +.\" Man page generated from reStructuredText. +. +.TH "LIBUV" "3" "May 24, 2020" "1.38.0" "libuv API documentation" +.SH NAME +libuv \- libuv documentation +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH OVERVIEW +.sp +libuv is a multi\-platform support library with a focus on asynchronous I/O. It +was primarily developed for use by \fI\%Node.js\fP, but it\(aqs also used by \fI\%Luvit\fP, +\fI\%Julia\fP, \fI\%pyuv\fP, and \fI\%others\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In case you find errors in this documentation you can help by sending +\fI\%pull requests\fP! +.UNINDENT +.UNINDENT +.SH FEATURES +.INDENT 0.0 +.IP \(bu 2 +Full\-featured event loop backed by epoll, kqueue, IOCP, event ports. +.IP \(bu 2 +Asynchronous TCP and UDP sockets +.IP \(bu 2 +Asynchronous DNS resolution +.IP \(bu 2 +Asynchronous file and file system operations +.IP \(bu 2 +File system events +.IP \(bu 2 +ANSI escape code controlled TTY +.IP \(bu 2 +IPC with socket sharing, using Unix domain sockets or named pipes (Windows) +.IP \(bu 2 +Child processes +.IP \(bu 2 +Thread pool +.IP \(bu 2 +Signal handling +.IP \(bu 2 +High resolution clock +.IP \(bu 2 +Threading and synchronization primitives +.UNINDENT +.SH DOCUMENTATION +.SS Design overview +.sp +libuv is cross\-platform support library which was originally written for \fI\%Node.js\fP\&. It\(aqs designed +around the event\-driven asynchronous I/O model. +.sp +The library provides much more than a simple abstraction over different I/O polling mechanisms: +\(aqhandles\(aq and \(aqstreams\(aq provide a high level abstraction for sockets and other entities; +cross\-platform file I/O and threading functionality is also provided, amongst other things. +.sp +Here is a diagram illustrating the different parts that compose libuv and what subsystem they +relate to: +[image] +.SS Handles and requests +.sp +libuv provides users with 2 abstractions to work with, in combination with the event loop: +handles and requests. +.sp +Handles represent long\-lived objects capable of performing certain operations while active. Some examples: +.INDENT 0.0 +.IP \(bu 2 +A prepare handle gets its callback called once every loop iteration when active. +.IP \(bu 2 +A TCP server handle that gets its connection callback called every time there is a new connection. +.UNINDENT +.sp +Requests represent (typically) short\-lived operations. These operations can be performed over a +handle: write requests are used to write data on a handle; or standalone: getaddrinfo requests +don\(aqt need a handle they run directly on the loop. +.SS The I/O loop +.sp +The I/O (or event) loop is the central part of libuv. It establishes the content for all I/O +operations, and it\(aqs meant to be tied to a single thread. One can run multiple event loops +as long as each runs in a different thread. The libuv event loop (or any other API involving +the loop or handles, for that matter) \fBis not thread\-safe\fP except where stated otherwise. +.sp +The event loop follows the rather usual single threaded asynchronous I/O approach: all (network) +I/O is performed on non\-blocking sockets which are polled using the best mechanism available +on the given platform: epoll on Linux, kqueue on OSX and other BSDs, event ports on SunOS and IOCP +on Windows. As part of a loop iteration the loop will block waiting for I/O activity on sockets +which have been added to the poller and callbacks will be fired indicating socket conditions +(readable, writable hangup) so handles can read, write or perform the desired I/O operation. +.sp +In order to better understand how the event loop operates, the following diagram illustrates all +stages of a loop iteration: +[image] +.INDENT 0.0 +.IP 1. 4 +The loop concept of \(aqnow\(aq is updated. The event loop caches the current time at the start of +the event loop tick in order to reduce the number of time\-related system calls. +.IP 2. 4 +If the loop is \fIalive\fP an iteration is started, otherwise the loop will exit immediately. So, +when is a loop considered to be \fIalive\fP? If a loop has active and ref\(aqd handles, active +requests or closing handles it\(aqs considered to be \fIalive\fP\&. +.IP 3. 4 +Due timers are run. All active timers scheduled for a time before the loop\(aqs concept of \fInow\fP +get their callbacks called. +.IP 4. 4 +Pending callbacks are called. All I/O callbacks are called right after polling for I/O, for the +most part. There are cases, however, in which calling such a callback is deferred for the next +loop iteration. If the previous iteration deferred any I/O callback it will be run at this point. +.IP 5. 4 +Idle handle callbacks are called. Despite the unfortunate name, idle handles are run on every +loop iteration, if they are active. +.IP 6. 4 +Prepare handle callbacks are called. Prepare handles get their callbacks called right before +the loop will block for I/O. +.IP 7. 4 +Poll timeout is calculated. Before blocking for I/O the loop calculates for how long it should +block. These are the rules when calculating the timeout: +.INDENT 4.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +If the loop was run with the \fBUV_RUN_NOWAIT\fP flag, the timeout is 0. +.IP \(bu 2 +If the loop is going to be stopped (\fBuv_stop()\fP was called), the timeout is 0. +.IP \(bu 2 +If there are no active handles or requests, the timeout is 0. +.IP \(bu 2 +If there are any idle handles active, the timeout is 0. +.IP \(bu 2 +If there are any handles pending to be closed, the timeout is 0. +.IP \(bu 2 +If none of the above cases matches, the timeout of the closest timer is taken, or +if there are no active timers, infinity. +.UNINDENT +.UNINDENT +.UNINDENT +.IP 8. 4 +The loop blocks for I/O. At this point the loop will block for I/O for the duration calculated +in the previous step. All I/O related handles that were monitoring a given file descriptor +for a read or write operation get their callbacks called at this point. +.IP 9. 4 +Check handle callbacks are called. Check handles get their callbacks called right after the +loop has blocked for I/O. Check handles are essentially the counterpart of prepare handles. +.IP 10. 4 +Close callbacks are called. If a handle was closed by calling \fBuv_close()\fP it will +get the close callback called. +.IP 11. 4 +Special case in case the loop was run with \fBUV_RUN_ONCE\fP, as it implies forward progress. +It\(aqs possible that no I/O callbacks were fired after blocking for I/O, but some time has passed +so there might be timers which are due, those timers get their callbacks called. +.IP 12. 4 +Iteration ends. If the loop was run with \fBUV_RUN_NOWAIT\fP or \fBUV_RUN_ONCE\fP modes the +iteration ends and \fBuv_run()\fP will return. If the loop was run with \fBUV_RUN_DEFAULT\fP +it will continue from the start if it\(aqs still \fIalive\fP, otherwise it will also end. +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +libuv uses a thread pool to make asynchronous file I/O operations possible, but +network I/O is \fBalways\fP performed in a single thread, each loop\(aqs thread. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +While the polling mechanism is different, libuv makes the execution model consistent +across Unix systems and Windows. +.UNINDENT +.UNINDENT +.SS File I/O +.sp +Unlike network I/O, there are no platform\-specific file I/O primitives libuv could rely on, +so the current approach is to run blocking file I/O operations in a thread pool. +.sp +For a thorough explanation of the cross\-platform file I/O landscape, checkout +\fI\%this post\fP\&. +.sp +libuv currently uses a global thread pool on which all loops can queue work. 3 types of +operations are currently run on this pool: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +File system operations +.IP \(bu 2 +DNS functions (getaddrinfo and getnameinfo) +.IP \(bu 2 +User specified code via \fBuv_queue_work()\fP +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +See the threadpool section for more details, but keep in mind the thread pool size +is quite limited. +.UNINDENT +.UNINDENT +.SS API documentation +.SS Error handling +.sp +In libuv errors are negative numbered constants. As a rule of thumb, whenever +there is a status parameter, or an API functions returns an integer, a negative +number will imply an error. +.sp +When a function which takes a callback returns an error, the callback will never +be called. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Implementation detail: on Unix error codes are the negated \fIerrno\fP (or \fI\-errno\fP), while on +Windows they are defined by libuv to arbitrary negative numbers. +.UNINDENT +.UNINDENT +.SS Error constants +.INDENT 0.0 +.TP +.B UV_E2BIG +argument list too long +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EACCES +permission denied +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EADDRINUSE +address already in use +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EADDRNOTAVAIL +address not available +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAFNOSUPPORT +address family not supported +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAGAIN +resource temporarily unavailable +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_ADDRFAMILY +address family not supported +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_AGAIN +temporary failure +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_BADFLAGS +bad ai_flags value +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_BADHINTS +invalid value for hints +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_CANCELED +request canceled +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_FAIL +permanent failure +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_FAMILY +ai_family not supported +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_MEMORY +out of memory +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_NODATA +no address +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_NONAME +unknown node or service +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_OVERFLOW +argument buffer overflow +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_PROTOCOL +resolved protocol is unknown +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_SERVICE +service not available for socket type +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EAI_SOCKTYPE +socket type not supported +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EALREADY +connection already in progress +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EBADF +bad file descriptor +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EBUSY +resource busy or locked +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ECANCELED +operation canceled +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ECHARSET +invalid Unicode character +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ECONNABORTED +software caused connection abort +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ECONNREFUSED +connection refused +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ECONNRESET +connection reset by peer +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EDESTADDRREQ +destination address required +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EEXIST +file already exists +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EFAULT +bad address in system call argument +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EFBIG +file too large +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EHOSTUNREACH +host is unreachable +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EINTR +interrupted system call +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EINVAL +invalid argument +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EIO +i/o error +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EISCONN +socket is already connected +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EISDIR +illegal operation on a directory +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ELOOP +too many symbolic links encountered +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EMFILE +too many open files +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EMSGSIZE +message too long +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENAMETOOLONG +name too long +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENETDOWN +network is down +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENETUNREACH +network is unreachable +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENFILE +file table overflow +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOBUFS +no buffer space available +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENODEV +no such device +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOENT +no such file or directory +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOMEM +not enough memory +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENONET +machine is not on the network +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOPROTOOPT +protocol not available +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOSPC +no space left on device +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOSYS +function not implemented +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOTCONN +socket is not connected +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOTDIR +not a directory +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOTEMPTY +directory not empty +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOTSOCK +socket operation on non\-socket +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENOTSUP +operation not supported on socket +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EPERM +operation not permitted +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EPIPE +broken pipe +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EPROTO +protocol error +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EPROTONOSUPPORT +protocol not supported +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EPROTOTYPE +protocol wrong type for socket +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ERANGE +result too large +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EROFS +read\-only file system +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ESHUTDOWN +cannot send after transport endpoint shutdown +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ESPIPE +invalid seek +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ESRCH +no such process +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ETIMEDOUT +connection timed out +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ETXTBSY +text file is busy +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EXDEV +cross\-device link not permitted +.UNINDENT +.INDENT 0.0 +.TP +.B UV_UNKNOWN +unknown error +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EOF +end of file +.UNINDENT +.INDENT 0.0 +.TP +.B UV_ENXIO +no such device or address +.UNINDENT +.INDENT 0.0 +.TP +.B UV_EMLINK +too many links +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B UV_ERRNO_MAP(iter_macro) +Macro that expands to a series of invocations of \fIiter_macro\fP for +each of the error constants above. \fIiter_macro\fP is invoked with two +arguments: the name of the error constant without the \fIUV_\fP prefix, +and the error message string literal. +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_strerror(int\fI\ err\fP) +Returns the error message for the given error code. Leaks a few bytes +of memory when you call it with an unknown error code. +.UNINDENT +.INDENT 0.0 +.TP +.B char* uv_strerror_r(int\fI\ err\fP, char*\fI\ buf\fP, size_t\fI\ buflen\fP) +Returns the error message for the given error code. The zero\-terminated +message is stored in the user\-supplied buffer \fIbuf\fP of at most \fIbuflen\fP bytes. +.sp +New in version 1.22.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_err_name(int\fI\ err\fP) +Returns the error name for the given error code. Leaks a few bytes +of memory when you call it with an unknown error code. +.UNINDENT +.INDENT 0.0 +.TP +.B char* uv_err_name_r(int\fI\ err\fP, char*\fI\ buf\fP, size_t\fI\ buflen\fP) +Returns the error name for the given error code. The zero\-terminated +name is stored in the user\-supplied buffer \fIbuf\fP of at most \fIbuflen\fP bytes. +.sp +New in version 1.22.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_translate_sys_error(int\fI\ sys_errno\fP) +Returns the libuv error code equivalent to the given platform dependent error +code: POSIX error codes on Unix (the ones stored in \fIerrno\fP), and Win32 error +codes on Windows (those returned by \fIGetLastError()\fP or \fIWSAGetLastError()\fP). +.sp +If \fIsys_errno\fP is already a libuv error, it is simply returned. +.sp +Changed in version 1.10.0: function declared public. + +.UNINDENT +.SS Version\-checking macros and functions +.sp +Starting with version 1.0.0 libuv follows the \fI\%semantic versioning\fP +scheme. This means that new APIs can be introduced throughout the lifetime of +a major release. In this section you\(aqll find all macros and functions that +will allow you to write or compile code conditionally, in order to work with +multiple libuv versions. +.SS Macros +.INDENT 0.0 +.TP +.B UV_VERSION_MAJOR +libuv version\(aqs major number. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_VERSION_MINOR +libuv version\(aqs minor number. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_VERSION_PATCH +libuv version\(aqs patch number. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_VERSION_IS_RELEASE +Set to 1 to indicate a release version of libuv, 0 for a development +snapshot. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_VERSION_SUFFIX +libuv version suffix. Certain development releases such as Release Candidates +might have a suffix such as "rc". +.UNINDENT +.INDENT 0.0 +.TP +.B UV_VERSION_HEX +Returns the libuv version packed into a single integer. 8 bits are used for +each component, with the patch number stored in the 8 least significant +bits. E.g. for libuv 1.2.3 this would be 0x010203. +.sp +New in version 1.7.0. + +.UNINDENT +.SS Functions +.INDENT 0.0 +.TP +.B unsigned int uv_version(void) +Returns \fI\%UV_VERSION_HEX\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_version_string(void) +Returns the libuv version number as a string. For non\-release versions the +version suffix is included. +.UNINDENT +.SS \fI\%uv_loop_t\fP \-\-\- Event loop +.sp +The event loop is the central part of libuv\(aqs functionality. It takes care +of polling for i/o and scheduling callbacks to be run based on different sources +of events. +.SS Data types +.INDENT 0.0 +.TP +.B uv_loop_t +Loop data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_run_mode +Mode used to run the loop with \fI\%uv_run()\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_RUN_DEFAULT = 0, + UV_RUN_ONCE, + UV_RUN_NOWAIT +} uv_run_mode; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_walk_cb)(uv_handle_t*\fI\ handle\fP, void*\fI\ arg\fP) +Type definition for callback passed to \fI\%uv_walk()\fP\&. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B void* uv_loop_t.data +Space for user\-defined arbitrary data. libuv does not use and does not +touch this field. +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_loop_init(uv_loop_t*\fI\ loop\fP) +Initializes the given \fIuv_loop_t\fP structure. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_loop_configure(uv_loop_t*\fI\ loop\fP, uv_loop_option\fI\ option\fP, \&...) +New in version 1.0.2. + +.sp +Set additional loop options. You should normally call this before the +first call to \fI\%uv_run()\fP unless mentioned otherwise. +.sp +Returns 0 on success or a UV_E* error code on failure. Be prepared to +handle UV_ENOSYS; it means the loop option is not supported by the platform. +.sp +Supported options: +.INDENT 7.0 +.IP \(bu 2 +UV_LOOP_BLOCK_SIGNAL: Block a signal when polling for new events. The +second argument to \fI\%uv_loop_configure()\fP is the signal number. +.sp +This operation is currently only implemented for SIGPROF signals, +to suppress unnecessary wakeups when using a sampling profiler. +Requesting other signals will fail with UV_EINVAL. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_loop_close(uv_loop_t*\fI\ loop\fP) +Releases all internal loop resources. Call this function only when the loop +has finished executing and all open handles and requests have been closed, +or it will return UV_EBUSY. After this function returns, the user can free +the memory allocated for the loop. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_loop_t* uv_default_loop(void) +Returns the initialized default loop. It may return NULL in case of +allocation failure. +.sp +This function is just a convenient way for having a global loop throughout +an application, the default loop is in no way different than the ones +initialized with \fI\%uv_loop_init()\fP\&. As such, the default loop can (and +should) be closed with \fI\%uv_loop_close()\fP so the resources associated +with it are freed. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not thread safe. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_run(uv_loop_t*\fI\ loop\fP, uv_run_mode\fI\ mode\fP) +This function runs the event loop. It will act differently depending on the +specified mode: +.INDENT 7.0 +.IP \(bu 2 +UV_RUN_DEFAULT: Runs the event loop until there are no more active and +referenced handles or requests. Returns non\-zero if \fI\%uv_stop()\fP +was called and there are still active handles or requests. Returns +zero in all other cases. +.IP \(bu 2 +UV_RUN_ONCE: Poll for i/o once. Note that this function blocks if +there are no pending callbacks. Returns zero when done (no active handles +or requests left), or non\-zero if more callbacks are expected (meaning +you should run the event loop again sometime in the future). +.IP \(bu 2 +UV_RUN_NOWAIT: Poll for i/o once but don\(aqt block if there are no +pending callbacks. Returns zero if done (no active handles +or requests left), or non\-zero if more callbacks are expected (meaning +you should run the event loop again sometime in the future). +.UNINDENT +.sp +\fI\%uv_run()\fP is not reentrant. It must not be called from a callback. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_loop_alive(const uv_loop_t*\fI\ loop\fP) +Returns non\-zero if there are referenced active handles, active +requests or closing handles in the loop. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_stop(uv_loop_t*\fI\ loop\fP) +Stop the event loop, causing \fI\%uv_run()\fP to end as soon as +possible. This will happen not sooner than the next loop iteration. +If this function was called before blocking for i/o, the loop won\(aqt block +for i/o on this iteration. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_loop_size(void) +Returns the size of the \fIuv_loop_t\fP structure. Useful for FFI binding +writers who don\(aqt want to know the structure layout. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_backend_fd(const uv_loop_t*\fI\ loop\fP) +Get backend file descriptor. Only kqueue, epoll and event ports are +supported. +.sp +This can be used in conjunction with \fIuv_run(loop, UV_RUN_NOWAIT)\fP to +poll in one thread and run the event loop\(aqs callbacks in another see +test/test\-embed.c for an example. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Embedding a kqueue fd in another kqueue pollset doesn\(aqt work on all platforms. It\(aqs not +an error to add the fd but it never generates events. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_backend_timeout(const uv_loop_t*\fI\ loop\fP) +Get the poll timeout. The return value is in milliseconds, or \-1 for no +timeout. +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_now(const uv_loop_t*\fI\ loop\fP) +Return the current timestamp in milliseconds. The timestamp is cached at +the start of the event loop tick, see \fI\%uv_update_time()\fP for details +and rationale. +.sp +The timestamp increases monotonically from some arbitrary point in time. +Don\(aqt make assumptions about the starting point, you will only get +disappointed. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Use \fBuv_hrtime()\fP if you need sub\-millisecond granularity. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_update_time(uv_loop_t*\fI\ loop\fP) +Update the event loop\(aqs concept of "now". Libuv caches the current time +at the start of the event loop tick in order to reduce the number of +time\-related system calls. +.sp +You won\(aqt normally need to call this function unless you have callbacks +that block the event loop for longer periods of time, where "longer" is +somewhat subjective but probably on the order of a millisecond or more. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_walk(uv_loop_t*\fI\ loop\fP, uv_walk_cb\fI\ walk_cb\fP, void*\fI\ arg\fP) +Walk the list of handles: \fIwalk_cb\fP will be executed with the given \fIarg\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_loop_fork(uv_loop_t*\fI\ loop\fP) +New in version 1.12.0. + +.sp +Reinitialize any kernel state necessary in the child process after +a \fI\%fork(2)\fP system call. +.sp +Previously started watchers will continue to be started in the +child process. +.sp +It is necessary to explicitly call this function on every event +loop created in the parent process that you plan to continue to +use in the child, including the default loop (even if you don\(aqt +continue to use it in the parent). This function must be called +before calling \fI\%uv_run()\fP or any other API function using +the loop in the child. Failure to do so will result in undefined +behaviour, possibly including duplicate events delivered to both +parent and child or aborting the child process. +.sp +When possible, it is preferred to create a new loop in the child +process instead of reusing a loop created in the parent. New loops +created in the child process after the fork should not use this +function. +.sp +This function is not implemented on Windows, where it returns \fBUV_ENOSYS\fP\&. +.sp +\fBCAUTION:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is experimental. It may contain bugs, and is subject to +change or removal. API and ABI stability is not guaranteed. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Mac OS X, if directory FS event handles were in use in the +parent process \fIfor any event loop\fP, the child process will no +longer be able to use the most efficient FSEvent +implementation. Instead, uses of directory FS event handles in +the child will fall back to the same implementation used for +files and on other kqueue\-based systems. +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 7.0 +.INDENT 3.5 +On AIX and SunOS, FS event handles that were already started in +the parent process at the time of forking will \fInot\fP deliver +events in the child process; they must be closed and restarted. +On all other platforms, they will continue to work normally +without any further intervention. +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 7.0 +.INDENT 3.5 +Any previous value returned from \fI\%uv_backend_fd()\fP is now +invalid. That function must be called again to determine the +correct backend file descriptor. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_loop_get_data(const uv_loop_t*\fI\ loop\fP) +Returns \fIloop\->data\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_loop_set_data(uv_loop_t*\fI\ loop\fP, void*\fI\ data\fP) +Sets \fIloop\->data\fP to \fIdata\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.SS \fI\%uv_handle_t\fP \-\-\- Base handle +.sp +\fIuv_handle_t\fP is the base type for all libuv handle types. +.sp +Structures are aligned so that any libuv handle can be cast to \fIuv_handle_t\fP\&. +All API functions defined here work with any handle type. +.sp +Libuv handles are not movable. Pointers to handle structures passed to +functions must remain valid for the duration of the requested operation. Take +care when using stack allocated handles. +.SS Data types +.INDENT 0.0 +.TP +.B uv_handle_t +The base libuv handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_handle_type +The kind of the libuv handle. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_UNKNOWN_HANDLE = 0, + UV_ASYNC, + UV_CHECK, + UV_FS_EVENT, + UV_FS_POLL, + UV_HANDLE, + UV_IDLE, + UV_NAMED_PIPE, + UV_POLL, + UV_PREPARE, + UV_PROCESS, + UV_STREAM, + UV_TCP, + UV_TIMER, + UV_TTY, + UV_UDP, + UV_SIGNAL, + UV_FILE, + UV_HANDLE_TYPE_MAX +} uv_handle_type; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_any_handle +Union of all handle types. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_alloc_cb)(uv_handle_t*\fI\ handle\fP, size_t\fI\ suggested_size\fP, uv_buf_t*\fI\ buf\fP) +Type definition for callback passed to \fBuv_read_start()\fP and +\fBuv_udp_recv_start()\fP\&. The user must allocate memory and fill the supplied +\fBuv_buf_t\fP structure. If NULL is assigned as the buffer\(aqs base or 0 as its length, +a \fBUV_ENOBUFS\fP error will be triggered in the \fBuv_udp_recv_cb\fP or the +\fBuv_read_cb\fP callback. +.sp +Each buffer is used only once and the user is responsible for freeing it in the +\fBuv_udp_recv_cb\fP or the \fBuv_read_cb\fP callback. +.sp +A suggested size (65536 at the moment in most cases) is provided, but it\(aqs just an indication, +not related in any way to the pending data to be read. The user is free to allocate the amount +of memory they decide. +.sp +As an example, applications with custom allocation schemes such as using freelists, allocation +pools or slab based allocators may decide to use a different size which matches the memory +chunks they already have. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +static void my_alloc_cb(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf) { + buf\->base = malloc(suggested_size); + buf\->len = suggested_size; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_close_cb)(uv_handle_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_close()\fP\&. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B uv_loop_t* uv_handle_t.loop +Pointer to the \fBuv_loop_t\fP the handle is running on. Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_handle_type uv_handle_t.type +The \fI\%uv_handle_type\fP, indicating the type of the underlying handle. Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_handle_t.data +Space for user\-defined arbitrary data. libuv does not use this field. +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B UV_HANDLE_TYPE_MAP(iter_macro) +Macro that expands to a series of invocations of \fIiter_macro\fP for +each of the handle types. \fIiter_macro\fP is invoked with two +arguments: the name of the \fIuv_handle_type\fP element without the +\fIUV_\fP prefix, and the name of the corresponding structure type +without the \fIuv_\fP prefix and \fI_t\fP suffix. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_is_active(const uv_handle_t*\fI\ handle\fP) +Returns non\-zero if the handle is active, zero if it\(aqs inactive. What +"active" means depends on the type of handle: +.INDENT 7.0 +.IP \(bu 2 +A uv_async_t handle is always active and cannot be deactivated, except +by closing it with uv_close(). +.IP \(bu 2 +A uv_pipe_t, uv_tcp_t, uv_udp_t, etc. handle \- basically any handle that +deals with i/o \- is active when it is doing something that involves i/o, +like reading, writing, connecting, accepting new connections, etc. +.IP \(bu 2 +A uv_check_t, uv_idle_t, uv_timer_t, etc. handle is active when it has +been started with a call to uv_check_start(), uv_idle_start(), etc. +.UNINDENT +.sp +Rule of thumb: if a handle of type \fIuv_foo_t\fP has a \fIuv_foo_start()\fP +function, then it\(aqs active from the moment that function is called. +Likewise, \fIuv_foo_stop()\fP deactivates the handle again. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_is_closing(const uv_handle_t*\fI\ handle\fP) +Returns non\-zero if the handle is closing or closed, zero otherwise. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function should only be used between the initialization of the handle and the +arrival of the close callback. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_close(uv_handle_t*\fI\ handle\fP, uv_close_cb\fI\ close_cb\fP) +Request handle to be closed. \fIclose_cb\fP will be called asynchronously after +this call. This MUST be called on each handle before memory is released. +Moreover, the memory can only be released in \fIclose_cb\fP or after it has +returned. +.sp +Handles that wrap file descriptors are closed immediately but +\fIclose_cb\fP will still be deferred to the next iteration of the event loop. +It gives you a chance to free up any resources associated with the handle. +.sp +In\-progress requests, like uv_connect_t or uv_write_t, are cancelled and +have their callbacks called asynchronously with status=UV_ECANCELED. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_ref(uv_handle_t*\fI\ handle\fP) +Reference the given handle. References are idempotent, that is, if a handle +is already referenced calling this function again will have no effect. +.sp +See \fI\%Reference counting\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_unref(uv_handle_t*\fI\ handle\fP) +Un\-reference the given handle. References are idempotent, that is, if a handle +is not referenced calling this function again will have no effect. +.sp +See \fI\%Reference counting\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_has_ref(const uv_handle_t*\fI\ handle\fP) +Returns non\-zero if the handle referenced, zero otherwise. +.sp +See \fI\%Reference counting\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_handle_size(uv_handle_type\fI\ type\fP) +Returns the size of the given handle type. Useful for FFI binding writers +who don\(aqt want to know the structure layout. +.UNINDENT +.SS Miscellaneous API functions +.sp +The following API functions take a \fI\%uv_handle_t\fP argument but they work +just for some handle types. +.INDENT 0.0 +.TP +.B int uv_send_buffer_size(uv_handle_t*\fI\ handle\fP, int*\fI\ value\fP) +Gets or sets the size of the send buffer that the operating +system uses for the socket. +.sp +If \fI*value\fP == 0, then it will set \fI*value\fP to the current send buffer size. +If \fI*value\fP > 0 then it will use \fI*value\fP to set the new send buffer size. +.sp +On success, zero is returned. On error, a negative result is +returned. +.sp +This function works for TCP, pipe and UDP handles on Unix and for TCP and +UDP handles on Windows. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Linux will set double the size and return double the size of the original set value. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_recv_buffer_size(uv_handle_t*\fI\ handle\fP, int*\fI\ value\fP) +Gets or sets the size of the receive buffer that the operating +system uses for the socket. +.sp +If \fI*value\fP == 0, then it will set \fI*value\fP to the current receive buffer size. +If \fI*value\fP > 0 then it will use \fI*value\fP to set the new receive buffer size. +.sp +On success, zero is returned. On error, a negative result is +returned. +.sp +This function works for TCP, pipe and UDP handles on Unix and for TCP and +UDP handles on Windows. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Linux will set double the size and return double the size of the original set value. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fileno(const uv_handle_t*\fI\ handle\fP, uv_os_fd_t*\fI\ fd\fP) +Gets the platform dependent file descriptor equivalent. +.sp +The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing +any other handle type will fail with \fIUV_EINVAL\fP\&. +.sp +If a handle doesn\(aqt have an attached file descriptor yet or the handle +itself has been closed, this function will return \fIUV_EBADF\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Be very careful when using this function. libuv assumes it\(aqs in control of the file +descriptor so any change to it may lead to malfunction. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_loop_t* uv_handle_get_loop(const uv_handle_t*\fI\ handle\fP) +Returns \fIhandle\->loop\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_handle_get_data(const uv_handle_t*\fI\ handle\fP) +Returns \fIhandle\->data\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_handle_set_data(uv_handle_t*\fI\ handle\fP, void*\fI\ data\fP) +Sets \fIhandle\->data\fP to \fIdata\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_handle_type uv_handle_get_type(const uv_handle_t*\fI\ handle\fP) +Returns \fIhandle\->type\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_handle_type_name(uv_handle_type\fI\ type\fP) +Returns the name for the equivalent struct for a given handle type, +e.g. \fI"pipe"\fP (as in \fBuv_pipe_t\fP) for \fIUV_NAMED_PIPE\fP\&. +.sp +If no such handle type exists, this returns \fINULL\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.SS Reference counting +.sp +The libuv event loop (if run in the default mode) will run until there are no +active \fIand\fP referenced handles left. The user can force the loop to exit early +by unreferencing handles which are active, for example by calling \fI\%uv_unref()\fP +after calling \fBuv_timer_start()\fP\&. +.sp +A handle can be referenced or unreferenced, the refcounting scheme doesn\(aqt use +a counter, so both operations are idempotent. +.sp +All handles are referenced when active by default, see \fI\%uv_is_active()\fP +for a more detailed explanation on what being \fIactive\fP involves. +.SS \fI\%uv_req_t\fP \-\-\- Base request +.sp +\fIuv_req_t\fP is the base type for all libuv request types. +.sp +Structures are aligned so that any libuv request can be cast to \fIuv_req_t\fP\&. +All API functions defined here work with any request type. +.SS Data types +.INDENT 0.0 +.TP +.B uv_req_t +The base libuv request structure. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_any_req +Union of all request types. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B void* uv_req_t.data +Space for user\-defined arbitrary data. libuv does not use this field. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_req_type uv_req_t.type +Indicated the type of request. Readonly. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_UNKNOWN_REQ = 0, + UV_REQ, + UV_CONNECT, + UV_WRITE, + UV_SHUTDOWN, + UV_UDP_SEND, + UV_FS, + UV_WORK, + UV_GETADDRINFO, + UV_GETNAMEINFO, + UV_REQ_TYPE_MAX, +} uv_req_type; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B UV_REQ_TYPE_MAP(iter_macro) +Macro that expands to a series of invocations of \fIiter_macro\fP for +each of the request types. \fIiter_macro\fP is invoked with two +arguments: the name of the \fIuv_req_type\fP element without the \fIUV_\fP +prefix, and the name of the corresponding structure type without the +\fIuv_\fP prefix and \fI_t\fP suffix. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_cancel(uv_req_t*\fI\ req\fP) +Cancel a pending request. Fails if the request is executing or has finished +executing. +.sp +Returns 0 on success, or an error code < 0 on failure. +.sp +Only cancellation of \fBuv_fs_t\fP, \fBuv_getaddrinfo_t\fP, +\fBuv_getnameinfo_t\fP, \fBuv_random_t\fP and \fBuv_work_t\fP +requests is currently supported. +.sp +Cancelled requests have their callbacks invoked some time in the future. +It\(aqs \fBnot\fP safe to free the memory associated with the request until the +callback is called. +.sp +Here is how cancellation is reported to the callback: +.INDENT 7.0 +.IP \(bu 2 +A \fBuv_fs_t\fP request has its req\->result field set to \fIUV_ECANCELED\fP\&. +.IP \(bu 2 +A \fBuv_work_t\fP, \fBuv_getaddrinfo_t\fP, +\fBuv_getnameinfo_t\fP or \fBuv_random_t\fP request has its +callback invoked with status == \fIUV_ECANCELED\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_req_size(uv_req_type\fI\ type\fP) +Returns the size of the given request type. Useful for FFI binding writers +who don\(aqt want to know the structure layout. +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_req_get_data(const uv_req_t*\fI\ req\fP) +Returns \fIreq\->data\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_req_set_data(uv_req_t*\fI\ req\fP, void*\fI\ data\fP) +Sets \fIreq\->data\fP to \fIdata\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_req_type uv_req_get_type(const uv_req_t*\fI\ req\fP) +Returns \fIreq\->type\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_req_type_name(uv_req_type\fI\ type\fP) +Returns the name for the equivalent struct for a given request type, +e.g. \fI"connect"\fP (as in \fBuv_connect_t\fP) for \fIUV_CONNECT\fP\&. +.sp +If no such request type exists, this returns \fINULL\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.SS \fI\%uv_timer_t\fP \-\-\- Timer handle +.sp +Timer handles are used to schedule callbacks to be called in the future. +.SS Data types +.INDENT 0.0 +.TP +.B uv_timer_t +Timer handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_timer_cb)(uv_timer_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_timer_start()\fP\&. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_timer_init(uv_loop_t*\fI\ loop\fP, uv_timer_t*\fI\ handle\fP) +Initialize the handle. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_timer_start(uv_timer_t*\fI\ handle\fP, uv_timer_cb\fI\ cb\fP, uint64_t\fI\ timeout\fP, uint64_t\fI\ repeat\fP) +Start the timer. \fItimeout\fP and \fIrepeat\fP are in milliseconds. +.sp +If \fItimeout\fP is zero, the callback fires on the next event loop iteration. +If \fIrepeat\fP is non\-zero, the callback fires first after \fItimeout\fP +milliseconds and then repeatedly after \fIrepeat\fP milliseconds. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Does not update the event loop\(aqs concept of "now". See \fBuv_update_time()\fP for more information. +.sp +If the timer is already active, it is simply updated. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_timer_stop(uv_timer_t*\fI\ handle\fP) +Stop the timer, the callback will not be called anymore. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_timer_again(uv_timer_t*\fI\ handle\fP) +Stop the timer, and if it is repeating restart it using the repeat value +as the timeout. If the timer has never been started before it returns +UV_EINVAL. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_timer_set_repeat(uv_timer_t*\fI\ handle\fP, uint64_t\fI\ repeat\fP) +Set the repeat interval value in milliseconds. The timer will be scheduled +to run on the given interval, regardless of the callback execution +duration, and will follow normal timer semantics in the case of a +time\-slice overrun. +.sp +For example, if a 50ms repeating timer first runs for 17ms, it will be +scheduled to run again 33ms later. If other tasks consume more than the +33ms following the first timer callback, then the callback will run as soon +as possible. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If the repeat value is set from a timer callback it does not immediately take effect. +If the timer was non\-repeating before, it will have been stopped. If it was repeating, +then the old repeat value will have been used to schedule the next timeout. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_timer_get_repeat(const uv_timer_t*\fI\ handle\fP) +Get the timer repeat value. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_prepare_t\fP \-\-\- Prepare handle +.sp +Prepare handles will run the given callback once per loop iteration, right +before polling for i/o. +.SS Data types +.INDENT 0.0 +.TP +.B uv_prepare_t +Prepare handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_prepare_cb)(uv_prepare_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_prepare_start()\fP\&. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_prepare_init(uv_loop_t*\fI\ loop\fP, uv_prepare_t*\fI\ prepare\fP) +Initialize the handle. This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_prepare_start(uv_prepare_t*\fI\ prepare\fP, uv_prepare_cb\fI\ cb\fP) +Start the handle with the given callback. This function always succeeds, +except when \fIcb\fP is \fINULL\fP\&. +.INDENT 7.0 +.TP +.B Returns +0 on success, or \fIUV_EINVAL\fP when \fIcb == NULL\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_prepare_stop(uv_prepare_t*\fI\ prepare\fP) +Stop the handle, the callback will no longer be called. +This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_check_t\fP \-\-\- Check handle +.sp +Check handles will run the given callback once per loop iteration, right +after polling for i/o. +.SS Data types +.INDENT 0.0 +.TP +.B uv_check_t +Check handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_check_cb)(uv_check_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_check_start()\fP\&. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_check_init(uv_loop_t*\fI\ loop\fP, uv_check_t*\fI\ check\fP) +Initialize the handle. This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_check_start(uv_check_t*\fI\ check\fP, uv_check_cb\fI\ cb\fP) +Start the handle with the given callback. This function always succeeds, +except when \fIcb\fP is \fINULL\fP\&. +.INDENT 7.0 +.TP +.B Returns +0 on success, or \fIUV_EINVAL\fP when \fIcb == NULL\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_check_stop(uv_check_t*\fI\ check\fP) +Stop the handle, the callback will no longer be called. +This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_idle_t\fP \-\-\- Idle handle +.sp +Idle handles will run the given callback once per loop iteration, right +before the \fBuv_prepare_t\fP handles. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The notable difference with prepare handles is that when there are active idle handles, +the loop will perform a zero timeout poll instead of blocking for i/o. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Despite the name, idle handles will get their callbacks called on every loop iteration, +not when the loop is actually "idle". +.UNINDENT +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_idle_t +Idle handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_idle_cb)(uv_idle_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_idle_start()\fP\&. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_idle_init(uv_loop_t*\fI\ loop\fP, uv_idle_t*\fI\ idle\fP) +Initialize the handle. This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_idle_start(uv_idle_t*\fI\ idle\fP, uv_idle_cb\fI\ cb\fP) +Start the handle with the given callback. This function always succeeds, +except when \fIcb\fP is \fINULL\fP\&. +.INDENT 7.0 +.TP +.B Returns +0 on success, or \fIUV_EINVAL\fP when \fIcb == NULL\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_idle_stop(uv_idle_t*\fI\ idle\fP) +Stop the handle, the callback will no longer be called. +This function always succeeds. +.INDENT 7.0 +.TP +.B Returns +0 +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_async_t\fP \-\-\- Async handle +.sp +Async handles allow the user to "wakeup" the event loop and get a callback +called from another thread. +.SS Data types +.INDENT 0.0 +.TP +.B uv_async_t +Async handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_async_cb)(uv_async_t*\fI\ handle\fP) +Type definition for callback passed to \fI\%uv_async_init()\fP\&. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_async_init(uv_loop_t*\fI\ loop\fP, uv_async_t*\fI\ async\fP, uv_async_cb\fI\ async_cb\fP) +Initialize the handle. A NULL callback is allowed. +.INDENT 7.0 +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Unlike other handle initialization functions, it immediately starts the handle. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_async_send(uv_async_t*\fI\ async\fP) +Wake up the event loop and call the async handle\(aqs callback. +.INDENT 7.0 +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +It\(aqs safe to call this function from any thread. The callback will be called on the +loop thread. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fI\%uv_async_send()\fP is \fI\%async\-signal\-safe\fP\&. +It\(aqs safe to call this function from a signal handler. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +libuv will coalesce calls to \fI\%uv_async_send()\fP, that is, not every call to it will +yield an execution of the callback. For example: if \fI\%uv_async_send()\fP is called 5 +times in a row before the callback is called, the callback will only be called once. If +\fI\%uv_async_send()\fP is called again after the callback was called, it will be called +again. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_poll_t\fP \-\-\- Poll handle +.sp +Poll handles are used to watch file descriptors for readability, +writability and disconnection similar to the purpose of \fI\%poll(2)\fP\&. +.sp +The purpose of poll handles is to enable integrating external libraries that +rely on the event loop to signal it about the socket status changes, like +c\-ares or libssh2. Using uv_poll_t for any other purpose is not recommended; +\fBuv_tcp_t\fP, \fBuv_udp_t\fP, etc. provide an implementation that is faster and +more scalable than what can be achieved with \fI\%uv_poll_t\fP, especially on +Windows. +.sp +It is possible that poll handles occasionally signal that a file descriptor is +readable or writable even when it isn\(aqt. The user should therefore always +be prepared to handle EAGAIN or equivalent when it attempts to read from or +write to the fd. +.sp +It is not okay to have multiple active poll handles for the same socket, this +can cause libuv to busyloop or otherwise malfunction. +.sp +The user should not close a file descriptor while it is being polled by an +active poll handle. This can cause the handle to report an error, +but it might also start polling another socket. However the fd can be safely +closed immediately after a call to \fI\%uv_poll_stop()\fP or \fBuv_close()\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +On windows only sockets can be polled with poll handles. On Unix any file +descriptor that would be accepted by \fI\%poll(2)\fP can be used. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +On AIX, watching for disconnection is not supported. +.UNINDENT +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_poll_t +Poll handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_poll_cb)(uv_poll_t*\fI\ handle\fP, int\fI\ status\fP, int\fI\ events\fP) +Type definition for callback passed to \fI\%uv_poll_start()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_poll_event +Poll event types +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +enum uv_poll_event { + UV_READABLE = 1, + UV_WRITABLE = 2, + UV_DISCONNECT = 4, + UV_PRIORITIZED = 8 +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_poll_init(uv_loop_t*\fI\ loop\fP, uv_poll_t*\fI\ handle\fP, int\fI\ fd\fP) +Initialize the handle using a file descriptor. +.sp +Changed in version 1.2.2: the file descriptor is set to non\-blocking mode. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_poll_init_socket(uv_loop_t*\fI\ loop\fP, uv_poll_t*\fI\ handle\fP, uv_os_sock_t\fI\ socket\fP) +Initialize the handle using a socket descriptor. On Unix this is identical +to \fI\%uv_poll_init()\fP\&. On windows it takes a SOCKET handle. +.sp +Changed in version 1.2.2: the socket is set to non\-blocking mode. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_poll_start(uv_poll_t*\fI\ handle\fP, int\fI\ events\fP, uv_poll_cb\fI\ cb\fP) +Starts polling the file descriptor. \fIevents\fP is a bitmask made up of +UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. As soon as an +event is detected the callback will be called with \fIstatus\fP set to 0, and the +detected events set on the \fIevents\fP field. +.sp +The UV_PRIORITIZED event is used to watch for sysfs interrupts or TCP out\-of\-band +messages. +.sp +The UV_DISCONNECT event is optional in the sense that it may not be +reported and the user is free to ignore it, but it can help optimize the shutdown +path because an extra read or write call might be avoided. +.sp +If an error happens while polling, \fIstatus\fP will be < 0 and corresponds +with one of the UV_E* error codes (see errors). The user should +not close the socket while the handle is active. If the user does that +anyway, the callback \fImay\fP be called reporting an error status, but this +is \fBnot\fP guaranteed. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Calling \fI\%uv_poll_start()\fP on a handle that is already active is fine. Doing so +will update the events mask that is being watched for. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set +on the \fIevents\fP field in the callback. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.9.0: Added the UV_DISCONNECT event. + +.sp +Changed in version 1.14.0: Added the UV_PRIORITIZED event. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_poll_stop(uv_poll_t*\fI\ poll\fP) +Stop polling the file descriptor, the callback will no longer be called. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_signal_t\fP \-\-\- Signal handle +.sp +Signal handles implement Unix style signal handling on a per\-event loop bases. +.SS Windows notes +.sp +Reception of some signals is emulated: +.INDENT 0.0 +.IP \(bu 2 +SIGINT is normally delivered when the user presses CTRL+C. However, like +on Unix, it is not generated when terminal raw mode is enabled. +.IP \(bu 2 +SIGBREAK is delivered when the user pressed CTRL + BREAK. +.IP \(bu 2 +SIGHUP is generated when the user closes the console window. On SIGHUP the +program is given approximately 10 seconds to perform cleanup. After that +Windows will unconditionally terminate it. +.IP \(bu 2 +SIGWINCH is raised whenever libuv detects that the console has been +resized. When a libuv app is running under a console emulator, or when a +32\-bit libuv app is running on 64\-bit system, SIGWINCH will be emulated. In +such cases SIGWINCH signals may not always be delivered in a timely manner. +For a writable \fBuv_tty_t\fP handle libuv will only detect size changes +when the cursor is moved. When a readable \fBuv_tty_t\fP handle is used, +resizing of the console buffer will be detected only if the handle is in raw +mode and is being read. +.IP \(bu 2 +Watchers for other signals can be successfully created, but these signals +are never received. These signals are: \fISIGILL\fP, \fISIGABRT\fP, \fISIGFPE\fP, \fISIGSEGV\fP, +\fISIGTERM\fP and \fISIGKILL.\fP +.IP \(bu 2 +Calls to raise() or abort() to programmatically raise a signal are +not detected by libuv; these will not trigger a signal watcher. +.UNINDENT +.sp +Changed in version 1.15.0: SIGWINCH support on Windows was improved. + +.sp +Changed in version 1.31.0: 32\-bit libuv SIGWINCH support on 64\-bit Windows was +rolled back to old implementation. + +.SS Unix notes +.INDENT 0.0 +.IP \(bu 2 +SIGKILL and SIGSTOP are impossible to catch. +.IP \(bu 2 +Handling SIGBUS, SIGFPE, SIGILL or SIGSEGV via libuv results into undefined behavior. +.IP \(bu 2 +SIGABRT will not be caught by libuv if generated by \fIabort()\fP, e.g. through \fIassert()\fP\&. +.IP \(bu 2 +On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL pthreads library to +manage threads. Installing watchers for those signals will lead to unpredictable behavior +and is strongly discouraged. Future versions of libuv may simply reject them. +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_signal_t +Signal handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_signal_cb)(uv_signal_t*\fI\ handle\fP, int\fI\ signum\fP) +Type definition for callback passed to \fI\%uv_signal_start()\fP\&. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B int uv_signal_t.signum +Signal being monitored by this handle. Readonly. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_signal_init(uv_loop_t*\fI\ loop\fP, uv_signal_t*\fI\ signal\fP) +Initialize the handle. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_signal_start(uv_signal_t*\fI\ signal\fP, uv_signal_cb\fI\ cb\fP, int\fI\ signum\fP) +Start the handle with the given callback, watching for the given signal. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_signal_start_oneshot(uv_signal_t*\fI\ signal\fP, uv_signal_cb\fI\ cb\fP, int\fI\ signum\fP) +New in version 1.12.0. + +.sp +Same functionality as \fI\%uv_signal_start()\fP but the signal handler is reset the moment +the signal is received. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_signal_stop(uv_signal_t*\fI\ signal\fP) +Stop the handle, the callback will no longer be called. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_process_t\fP \-\-\- Process handle +.sp +Process handles will spawn a new process and allow the user to control it and +establish communication channels with it using streams. +.SS Data types +.INDENT 0.0 +.TP +.B uv_process_t +Process handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t +Options for spawning the process (passed to \fI\%uv_spawn()\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_process_options_s { + uv_exit_cb exit_cb; + const char* file; + char** args; + char** env; + const char* cwd; + unsigned int flags; + int stdio_count; + uv_stdio_container_t* stdio; + uv_uid_t uid; + uv_gid_t gid; +} uv_process_options_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_exit_cb)(uv_process_t*, int64_t\fI\ exit_status\fP, int\fI\ term_signal\fP) +Type definition for callback passed in \fI\%uv_process_options_t\fP which +will indicate the exit status and the signal that caused the process to +terminate, if any. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_flags +Flags to be set on the flags field of \fI\%uv_process_options_t\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +enum uv_process_flags { + /* + * Set the child process\(aq user id. + */ + UV_PROCESS_SETUID = (1 << 0), + /* + * Set the child process\(aq group id. + */ + UV_PROCESS_SETGID = (1 << 1), + /* + * Do not wrap any arguments in quotes, or perform any other escaping, when + * converting the argument list into a command line string. This option is + * only meaningful on Windows systems. On Unix it is silently ignored. + */ + UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2), + /* + * Spawn the child process in a detached state \- this will make it a process + * group leader, and will effectively enable the child to keep running after + * the parent exits. Note that the child process will still keep the + * parent\(aqs event loop alive unless the parent process calls uv_unref() on + * the child\(aqs process handle. + */ + UV_PROCESS_DETACHED = (1 << 3), + /* + * Hide the subprocess window that would normally be created. This option is + * only meaningful on Windows systems. On Unix it is silently ignored. + */ + UV_PROCESS_WINDOWS_HIDE = (1 << 4), + /* + * Hide the subprocess console window that would normally be created. This + * option is only meaningful on Windows systems. On Unix it is silently + * ignored. + */ + UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5), + /* + * Hide the subprocess GUI window that would normally be created. This + * option is only meaningful on Windows systems. On Unix it is silently + * ignored. + */ + UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6) +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stdio_container_t +Container for each stdio handle or fd passed to a child process. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_stdio_container_s { + uv_stdio_flags flags; + union { + uv_stream_t* stream; + int fd; + } data; +} uv_stdio_container_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stdio_flags +Flags specifying how a stdio should be transmitted to the child process. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_IGNORE = 0x00, + UV_CREATE_PIPE = 0x01, + UV_INHERIT_FD = 0x02, + UV_INHERIT_STREAM = 0x04, + /* + * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE + * determine the direction of flow, from the child process\(aq perspective. Both + * flags may be specified to create a duplex data stream. + */ + UV_READABLE_PIPE = 0x10, + UV_WRITABLE_PIPE = 0x20 + /* + * Open the child pipe handle in overlapped mode on Windows. + * On Unix it is silently ignored. + */ + UV_OVERLAPPED_PIPE = 0x40 +} uv_stdio_flags; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B uv_process_t.pid +The PID of the spawned process. It\(aqs set after calling \fI\%uv_spawn()\fP\&. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.exit_cb +Callback called after the process exits. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.file +Path pointing to the program to be executed. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.args +Command line arguments. args[0] should be the path to the program. On +Windows this uses \fICreateProcess\fP which concatenates the arguments into a +string this can cause some strange errors. See the +\fBUV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS\fP flag on \fI\%uv_process_flags\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.env +Environment for the new process. If NULL the parents environment is used. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.cwd +Current working directory for the subprocess. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.flags +Various flags that control how \fI\%uv_spawn()\fP behaves. See +\fI\%uv_process_flags\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.stdio_count +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.stdio +The \fIstdio\fP field points to an array of \fI\%uv_stdio_container_t\fP +structs that describe the file descriptors that will be made available to +the child process. The convention is that stdio[0] points to stdin, +fd 1 is used for stdout, and fd 2 is stderr. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows file descriptors greater than 2 are available to the child process only if +the child processes uses the MSVCRT runtime. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.uid +.UNINDENT +.INDENT 0.0 +.TP +.B uv_process_options_t.gid +Libuv can change the child process\(aq user/group id. This happens only when +the appropriate bits are set in the flags fields. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is not supported on Windows, \fI\%uv_spawn()\fP will fail and set the error +to \fBUV_ENOTSUP\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stdio_container_t.flags +Flags specifying how the stdio container should be passed to the child. See +\fI\%uv_stdio_flags\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stdio_container_t.data +Union containing either the stream or fd to be passed on to the child +process. +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B void uv_disable_stdio_inheritance(void) +Disables inheritance for file descriptors / handles that this process +inherited from its parent. The effect is that child processes spawned by +this process don\(aqt accidentally inherit these handles. +.sp +It is recommended to call this function as early in your program as possible, +before the inherited file descriptors can be closed or duplicated. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function works on a best\-effort basis: there is no guarantee that libuv can discover +all file descriptors that were inherited. In general it does a better job on Windows than +it does on Unix. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_spawn(uv_loop_t*\fI\ loop\fP, uv_process_t*\fI\ handle\fP, const uv_process_options_t*\fI\ options\fP) +Initializes the process handle and starts the process. If the process is +successfully spawned, this function will return 0. Otherwise, the +negative error code corresponding to the reason it couldn\(aqt spawn is +returned. +.sp +Possible reasons for failing to spawn would include (but not be limited to) +the file to execute not existing, not having permissions to use the setuid or +setgid specified, or not having enough memory to allocate for the new +process. +.sp +Changed in version 1.24.0: Added \fIUV_PROCESS_WINDOWS_HIDE_CONSOLE\fP and +\fIUV_PROCESS_WINDOWS_HIDE_GUI\fP flags. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_process_kill(uv_process_t*\fI\ handle\fP, int\fI\ signum\fP) +Sends the specified signal to the given process handle. Check the documentation +on signal for signal support, specially on Windows. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_kill(int\fI\ pid\fP, int\fI\ signum\fP) +Sends the specified signal to the given PID. Check the documentation +on signal for signal support, specially on Windows. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_pid_t uv_process_get_pid(const uv_process_t*\fI\ handle\fP) +Returns \fIhandle\->pid\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_stream_t\fP \-\-\- Stream handle +.sp +Stream handles provide an abstraction of a duplex communication channel. +\fI\%uv_stream_t\fP is an abstract type, libuv provides 3 stream implementations +in the form of \fBuv_tcp_t\fP, \fBuv_pipe_t\fP and \fBuv_tty_t\fP\&. +.SS Data types +.INDENT 0.0 +.TP +.B uv_stream_t +Stream handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_connect_t +Connect request type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_shutdown_t +Shutdown request type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_write_t +Write request type. Careful attention must be paid when reusing objects of +this type. When a stream is in non\-blocking mode, write requests sent +with \fBuv_write\fP will be queued. Reusing objects at this point is undefined +behaviour. It is safe to reuse the \fBuv_write_t\fP object only after the +callback passed to \fBuv_write\fP is fired. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_read_cb)(uv_stream_t*\fI\ stream\fP, ssize_t\fI\ nread\fP, const uv_buf_t*\fI\ buf\fP) +Callback called when data was read on a stream. +.sp +\fInread\fP is > 0 if there is data available or < 0 on error. When we\(aqve +reached EOF, \fInread\fP will be set to \fBUV_EOF\fP\&. When \fInread\fP < 0, +the \fIbuf\fP parameter might not point to a valid buffer; in that case +\fIbuf.len\fP and \fIbuf.base\fP are both set to 0. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fInread\fP might be 0, which does \fInot\fP indicate an error or EOF. This +is equivalent to \fBEAGAIN\fP or \fBEWOULDBLOCK\fP under \fBread(2)\fP\&. +.UNINDENT +.UNINDENT +.sp +The callee is responsible for stopping/closing the stream when an error happens +by calling \fI\%uv_read_stop()\fP or \fBuv_close()\fP\&. Trying to read +from the stream again is undefined. +.sp +The callee is responsible for freeing the buffer, libuv does not reuse it. +The buffer may be a null buffer (where \fIbuf\->base\fP == NULL and \fIbuf\->len\fP == 0) +on error. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_write_cb)(uv_write_t*\fI\ req\fP, int\fI\ status\fP) +Callback called after data was written on a stream. \fIstatus\fP will be 0 in +case of success, < 0 otherwise. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_connect_cb)(uv_connect_t*\fI\ req\fP, int\fI\ status\fP) +Callback called after a connection started by \fBuv_connect()\fP is done. +\fIstatus\fP will be 0 in case of success, < 0 otherwise. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_shutdown_cb)(uv_shutdown_t*\fI\ req\fP, int\fI\ status\fP) +Callback called after a shutdown request has been completed. \fIstatus\fP will +be 0 in case of success, < 0 otherwise. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_connection_cb)(uv_stream_t*\fI\ server\fP, int\fI\ status\fP) +Callback called when a stream server has received an incoming connection. +The user can accept the connection by calling \fI\%uv_accept()\fP\&. +\fIstatus\fP will be 0 in case of success, < 0 otherwise. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B size_t uv_stream_t.write_queue_size +Contains the amount of queued bytes waiting to be sent. Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stream_t* uv_connect_t.handle +Pointer to the stream where this connection request is running. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stream_t* uv_shutdown_t.handle +Pointer to the stream where this shutdown request is running. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stream_t* uv_write_t.handle +Pointer to the stream where this write request is running. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stream_t* uv_write_t.send_handle +Pointer to the stream being sent using this write request. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_shutdown(uv_shutdown_t*\fI\ req\fP, uv_stream_t*\fI\ handle\fP, uv_shutdown_cb\fI\ cb\fP) +Shutdown the outgoing (write) side of a duplex stream. It waits for pending +write requests to complete. The \fIhandle\fP should refer to a initialized stream. +\fIreq\fP should be an uninitialized shutdown request struct. The \fIcb\fP is called +after shutdown is complete. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_listen(uv_stream_t*\fI\ stream\fP, int\fI\ backlog\fP, uv_connection_cb\fI\ cb\fP) +Start listening for incoming connections. \fIbacklog\fP indicates the number of +connections the kernel might queue, same as \fI\%listen(2)\fP\&. When a new +incoming connection is received the \fI\%uv_connection_cb\fP callback is +called. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_accept(uv_stream_t*\fI\ server\fP, uv_stream_t*\fI\ client\fP) +This call is used in conjunction with \fI\%uv_listen()\fP to accept incoming +connections. Call this function after receiving a \fI\%uv_connection_cb\fP +to accept the connection. Before calling this function the client handle must +be initialized. < 0 return value indicates an error. +.sp +When the \fI\%uv_connection_cb\fP callback is called it is guaranteed that +this function will complete successfully the first time. If you attempt to use +it more than once, it may fail. It is suggested to only call this function once +per \fI\%uv_connection_cb\fP call. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIserver\fP and \fIclient\fP must be handles running on the same loop. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_read_start(uv_stream_t*\fI\ stream\fP, uv_alloc_cb\fI\ alloc_cb\fP, uv_read_cb\fI\ read_cb\fP) +Read data from an incoming stream. The \fI\%uv_read_cb\fP callback will +be made several times until there is no more data to read or +\fI\%uv_read_stop()\fP is called. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_read_stop(uv_stream_t*) +Stop reading data from the stream. The \fI\%uv_read_cb\fP callback will +no longer be called. +.sp +This function is idempotent and may be safely called on a stopped stream. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_write(uv_write_t*\fI\ req\fP, uv_stream_t*\fI\ handle\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, uv_write_cb\fI\ cb\fP) +Write data to stream. Buffers are written in order. Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +void cb(uv_write_t* req, int status) { + /* Logic which handles the write result */ +} + +uv_buf_t a[] = { + { .base = "1", .len = 1 }, + { .base = "2", .len = 1 } +}; + +uv_buf_t b[] = { + { .base = "3", .len = 1 }, + { .base = "4", .len = 1 } +}; + +uv_write_t req1; +uv_write_t req2; + +/* writes "1234" */ +uv_write(&req1, stream, a, 2, cb); +uv_write(&req2, stream, b, 2, cb); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The memory pointed to by the buffers must remain valid until the callback gets called. +This also holds for \fI\%uv_write2()\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_write2(uv_write_t*\fI\ req\fP, uv_stream_t*\fI\ handle\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, uv_stream_t*\fI\ send_handle\fP, uv_write_cb\fI\ cb\fP) +Extended write function for sending handles over a pipe. The pipe must be +initialized with \fIipc\fP == 1. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIsend_handle\fP must be a TCP socket or pipe, which is a server or a connection (listening +or connected state). Bound sockets or pipes will be assumed to be servers. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_try_write(uv_stream_t*\fI\ handle\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP) +Same as \fI\%uv_write()\fP, but won\(aqt queue a write request if it can\(aqt be +completed immediately. +.sp +Will return either: +.INDENT 7.0 +.IP \(bu 2 +> 0: number of bytes written (can be less than the supplied buffer size). +.IP \(bu 2 +< 0: negative error code (\fBUV_EAGAIN\fP is returned if no data can be sent +immediately). +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_is_readable(const uv_stream_t*\fI\ handle\fP) +Returns 1 if the stream is readable, 0 otherwise. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_is_writable(const uv_stream_t*\fI\ handle\fP) +Returns 1 if the stream is writable, 0 otherwise. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_stream_set_blocking(uv_stream_t*\fI\ handle\fP, int\fI\ blocking\fP) +Enable or disable blocking mode for a stream. +.sp +When blocking mode is enabled all writes complete synchronously. The +interface remains unchanged otherwise, e.g. completion or failure of the +operation will still be reported through a callback which is made +asynchronously. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Relying too much on this API is not recommended. It is likely to change +significantly in the future. +.sp +Currently only works on Windows for \fBuv_pipe_t\fP handles. +On UNIX platforms, all \fI\%uv_stream_t\fP handles are supported. +.sp +Also libuv currently makes no ordering guarantee when the blocking mode +is changed after write requests have already been submitted. Therefore it is +recommended to set the blocking mode immediately after opening or creating +the stream. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.4.0: UNIX implementation added. + +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_stream_get_write_queue_size(const uv_stream_t*\fI\ stream\fP) +Returns \fIstream\->write_queue_size\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_tcp_t\fP \-\-\- TCP handle +.sp +TCP handles are used to represent both TCP streams and servers. +.sp +\fI\%uv_tcp_t\fP is a \(aqsubclass\(aq of \fBuv_stream_t\fP\&. +.SS Data types +.INDENT 0.0 +.TP +.B uv_tcp_t +TCP handle type. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_tcp_init(uv_loop_t*\fI\ loop\fP, uv_tcp_t*\fI\ handle\fP) +Initialize the handle. No socket is created as of yet. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_init_ex(uv_loop_t*\fI\ loop\fP, uv_tcp_t*\fI\ handle\fP, unsigned int\fI\ flags\fP) +Initialize the handle with the specified flags. At the moment only the lower 8 bits +of the \fIflags\fP parameter are used as the socket domain. A socket will be created +for the given domain. If the specified domain is \fBAF_UNSPEC\fP no socket is created, +just like \fI\%uv_tcp_init()\fP\&. +.sp +New in version 1.7.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_open(uv_tcp_t*\fI\ handle\fP, uv_os_sock_t\fI\ sock\fP) +Open an existing file descriptor or SOCKET as a TCP handle. +.sp +Changed in version 1.2.1: the file descriptor is set to non\-blocking mode. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The passed file descriptor or SOCKET is not checked for its type, but +it\(aqs required that it represents a valid stream socket. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_nodelay(uv_tcp_t*\fI\ handle\fP, int\fI\ enable\fP) +Enable \fITCP_NODELAY\fP, which disables Nagle\(aqs algorithm. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_keepalive(uv_tcp_t*\fI\ handle\fP, int\fI\ enable\fP, unsigned int\fI\ delay\fP) +Enable / disable TCP keep\-alive. \fIdelay\fP is the initial delay in seconds, +ignored when \fIenable\fP is zero. +.sp +After \fIdelay\fP has been reached, 10 successive probes, each spaced 1 second +from the previous one, will still happen. If the connection is still lost +at the end of this procedure, then the handle is destroyed with a +\fBUV_ETIMEDOUT\fP error passed to the corresponding callback. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_simultaneous_accepts(uv_tcp_t*\fI\ handle\fP, int\fI\ enable\fP) +Enable / disable simultaneous asynchronous accept requests that are +queued by the operating system when listening for new TCP connections. +.sp +This setting is used to tune a TCP server for the desired performance. +Having simultaneous accepts can significantly improve the rate of accepting +connections (which is why it is enabled by default) but may lead to uneven +load distribution in multi\-process setups. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_bind(uv_tcp_t*\fI\ handle\fP, const struct sockaddr*\fI\ addr\fP, unsigned int\fI\ flags\fP) +Bind the handle to an address and port. \fIaddr\fP should point to an +initialized \fBstruct sockaddr_in\fP or \fBstruct sockaddr_in6\fP\&. +.sp +When the port is already taken, you can expect to see an \fBUV_EADDRINUSE\fP +error from either \fI\%uv_tcp_bind()\fP, \fBuv_listen()\fP or +\fI\%uv_tcp_connect()\fP\&. That is, a successful call to this function does +not guarantee that the call to \fBuv_listen()\fP or \fI\%uv_tcp_connect()\fP +will succeed as well. +.sp +\fIflags\fP can contain \fBUV_TCP_IPV6ONLY\fP, in which case dual\-stack support +is disabled and only IPv6 is used. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_getsockname(const uv_tcp_t*\fI\ handle\fP, struct sockaddr*\fI\ name\fP, int*\fI\ namelen\fP) +Get the current address to which the handle is bound. \fIname\fP must point to +a valid and big enough chunk of memory, \fBstruct sockaddr_storage\fP is +recommended for IPv4 and IPv6 support. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_getpeername(const uv_tcp_t*\fI\ handle\fP, struct sockaddr*\fI\ name\fP, int*\fI\ namelen\fP) +Get the address of the peer connected to the handle. \fIname\fP must point to +a valid and big enough chunk of memory, \fBstruct sockaddr_storage\fP is +recommended for IPv4 and IPv6 support. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_connect(uv_connect_t*\fI\ req\fP, uv_tcp_t*\fI\ handle\fP, const struct sockaddr*\fI\ addr\fP, uv_connect_cb\fI\ cb\fP) +Establish an IPv4 or IPv6 TCP connection. Provide an initialized TCP handle +and an uninitialized \fBuv_connect_t\fP\&. \fIaddr\fP should point to an +initialized \fBstruct sockaddr_in\fP or \fBstruct sockaddr_in6\fP\&. +.sp +On Windows if the \fIaddr\fP is initialized to point to an unspecified address +(\fB0.0.0.0\fP or \fB::\fP) it will be changed to point to \fBlocalhost\fP\&. +This is done to match the behavior of Linux systems. +.sp +The callback is made when the connection has been established or when a +connection error happened. +.sp +Changed in version 1.19.0: added \fB0.0.0.0\fP and \fB::\fP to \fBlocalhost\fP +mapping + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tcp_close_reset(uv_tcp_t*\fI\ handle\fP, uv_close_cb\fI\ close_cb\fP) +Resets a TCP connection by sending a RST packet. This is accomplished by +setting the \fISO_LINGER\fP socket option with a linger interval of zero and +then calling \fBuv_close()\fP\&. +Due to some platform inconsistencies, mixing of \fBuv_shutdown()\fP and +\fI\%uv_tcp_close_reset()\fP calls is not allowed. +.sp +New in version 1.32.0. + +.UNINDENT +.SS \fI\%uv_pipe_t\fP \-\-\- Pipe handle +.sp +Pipe handles provide an abstraction over streaming files on Unix (including +local domain sockets, pipes, and FIFOs) and named pipes on Windows. +.sp +\fI\%uv_pipe_t\fP is a \(aqsubclass\(aq of \fBuv_stream_t\fP\&. +.SS Data types +.INDENT 0.0 +.TP +.B uv_pipe_t +Pipe handle type. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B int uv_pipe_t.ipc +Whether this pipe is suitable for handle passing between processes. +Only a connected pipe that will be passing the handles should have this flag +set, not the listening pipe that uv_accept is called on. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_pipe_init(uv_loop_t*\fI\ loop\fP, uv_pipe_t*\fI\ handle\fP, int\fI\ ipc\fP) +Initialize a pipe handle. The \fIipc\fP argument is a boolean to indicate if +this pipe will be used for handle passing between processes (which may +change the bytes on the wire). Only a connected pipe that will be +passing the handles should have this flag set, not the listening pipe +that uv_accept is called on. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_open(uv_pipe_t*\fI\ handle\fP, uv_file\fI\ file\fP) +Open an existing file descriptor or HANDLE as a pipe. +.sp +Changed in version 1.2.1: the file descriptor is set to non\-blocking mode. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The passed file descriptor or HANDLE is not checked for its type, but +it\(aqs required that it represents a valid pipe. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_bind(uv_pipe_t*\fI\ handle\fP, const char*\fI\ name\fP) +Bind the pipe to a file path (Unix) or a name (Windows). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Paths on Unix get truncated to \fBsizeof(sockaddr_un.sun_path)\fP bytes, typically between +92 and 108 bytes. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_pipe_connect(uv_connect_t*\fI\ req\fP, uv_pipe_t*\fI\ handle\fP, const char*\fI\ name\fP, uv_connect_cb\fI\ cb\fP) +Connect to the Unix domain socket or the named pipe. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Paths on Unix get truncated to \fBsizeof(sockaddr_un.sun_path)\fP bytes, typically between +92 and 108 bytes. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_getsockname(const uv_pipe_t*\fI\ handle\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Get the name of the Unix domain socket or the named pipe. +.sp +A preallocated buffer must be provided. The size parameter holds the length +of the buffer and it\(aqs set to the number of bytes written to the buffer on +output. If the buffer is not big enough \fBUV_ENOBUFS\fP will be returned and +len will contain the required size. +.sp +Changed in version 1.3.0: the returned length no longer includes the terminating null byte, +and the buffer is not null terminated. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_getpeername(const uv_pipe_t*\fI\ handle\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Get the name of the Unix domain socket or the named pipe to which the handle +is connected. +.sp +A preallocated buffer must be provided. The size parameter holds the length +of the buffer and it\(aqs set to the number of bytes written to the buffer on +output. If the buffer is not big enough \fBUV_ENOBUFS\fP will be returned and +len will contain the required size. +.sp +New in version 1.3.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_pipe_pending_instances(uv_pipe_t*\fI\ handle\fP, int\fI\ count\fP) +Set the number of pending pipe instance handles when the pipe server is +waiting for connections. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This setting applies to Windows only. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_pending_count(uv_pipe_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B uv_handle_type uv_pipe_pending_type(uv_pipe_t*\fI\ handle\fP) +Used to receive handles over IPC pipes. +.sp +First \- call \fI\%uv_pipe_pending_count()\fP, if it\(aqs > 0 then initialize +a handle of the given \fItype\fP, returned by \fI\%uv_pipe_pending_type()\fP +and call \fBuv_accept(pipe, handle)\fP\&. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_pipe_chmod(uv_pipe_t*\fI\ handle\fP, int\fI\ flags\fP) +Alters pipe permissions, allowing it to be accessed from processes run by +different users. Makes the pipe writable or readable by all users. Mode can +be \fBUV_WRITABLE\fP, \fBUV_READABLE\fP or \fBUV_WRITABLE | UV_READABLE\fP\&. This +function is blocking. +.sp +New in version 1.16.0. + +.UNINDENT +.SS \fI\%uv_tty_t\fP \-\-\- TTY handle +.sp +TTY handles represent a stream for the console. +.sp +\fI\%uv_tty_t\fP is a \(aqsubclass\(aq of \fBuv_stream_t\fP\&. +.SS Data types +.INDENT 0.0 +.TP +.B uv_tty_t +TTY handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_tty_mode_t +New in version 1.2.0. + +.sp +TTY mode type: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + /* Initial/normal terminal mode */ + UV_TTY_MODE_NORMAL, + /* Raw input mode (On Windows, ENABLE_WINDOW_INPUT is also enabled) */ + UV_TTY_MODE_RAW, + /* Binary\-safe I/O mode for IPC (Unix\-only) */ + UV_TTY_MODE_IO +} uv_tty_mode_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_tty_vtermstate_t +.TP +.B Console virtual terminal mode type: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + /* + * The console supports handling of virtual terminal sequences + * (Windows10 new console, ConEmu) + */ + UV_TTY_SUPPORTED, + /* The console cannot process virtual terminal sequences. (Legacy + * console) + */ + UV_TTY_UNSUPPORTED +} uv_tty_vtermstate_t +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_tty_init(uv_loop_t*\fI\ loop\fP, uv_tty_t*\fI\ handle\fP, uv_file\fI\ fd\fP, int\fI\ unused\fP) +Initialize a new TTY stream with the given file descriptor. Usually the +file descriptor will be: +.INDENT 7.0 +.IP \(bu 2 +0 = stdin +.IP \(bu 2 +1 = stdout +.IP \(bu 2 +2 = stderr +.UNINDENT +.sp +On Unix this function will determine the path of the fd of the terminal +using \fI\%ttyname_r(3)\fP, open it, and use it if the passed file descriptor +refers to a TTY. This lets libuv put the tty in non\-blocking mode without +affecting other processes that share the tty. +.sp +This function is not thread safe on systems that don\(aqt support +ioctl TIOCGPTN or TIOCPTYGNAME, for instance OpenBSD and Solaris. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If reopening the TTY fails, libuv falls back to blocking writes. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.23.1:: the \fIreadable\fP parameter is now unused and ignored. +The correct value will now be auto\-detected from the kernel. + +.sp +Changed in version 1.9.0:: the path of the TTY is determined by +\fI\%ttyname_r(3)\fP\&. In earlier versions libuv opened +\fI/dev/tty\fP instead. + +.sp +Changed in version 1.5.0:: trying to initialize a TTY stream with a file +descriptor that refers to a file returns \fIUV_EINVAL\fP +on UNIX. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tty_set_mode(uv_tty_t*\fI\ handle\fP, uv_tty_mode_t\fI\ mode\fP) +Changed in version 1.2.0:: the mode is specified as a +\fI\%uv_tty_mode_t\fP value. + +.sp +Set the TTY using the specified terminal mode. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tty_reset_mode(void) +To be called when the program exits. Resets TTY settings to default +values for the next process to take over. +.sp +This function is async signal\-safe on Unix platforms but can fail with error +code \fBUV_EBUSY\fP if you call it when execution is inside +\fI\%uv_tty_set_mode()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tty_get_winsize(uv_tty_t*\fI\ handle\fP, int*\fI\ width\fP, int*\fI\ height\fP) +Gets the current Window size. On success it returns 0. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_stream_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_tty_set_vterm_state(uv_tty_vtermstate_t\fI\ state\fP) +Controls whether console virtual terminal sequences are processed by libuv +or console. +Useful in particular for enabling ConEmu support of ANSI X3.64 and Xterm +256 colors. Otherwise Windows10 consoles are usually detected automatically. +.sp +This function is only meaningful on Windows systems. On Unix it is silently +ignored. +.sp +New in version 1.33.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_tty_get_vterm_state(uv_tty_vtermstate_t*\fI\ state\fP) +Get the current state of whether console virtual terminal sequences are +handled by libuv or the console. +.sp +This function is not implemented on Unix, where it returns \fBUV_ENOTSUP\fP\&. +.sp +New in version 1.33.0. + +.UNINDENT +.SS \fI\%uv_udp_t\fP \-\-\- UDP handle +.sp +UDP handles encapsulate UDP communication for both clients and servers. +.SS Data types +.INDENT 0.0 +.TP +.B uv_udp_t +UDP handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_udp_send_t +UDP send request type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_udp_flags +Flags used in \fI\%uv_udp_bind()\fP and \fI\%uv_udp_recv_cb\fP\&.. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +enum uv_udp_flags { + /* Disables dual stack mode. */ + UV_UDP_IPV6ONLY = 1, + /* + * Indicates message was truncated because read buffer was too small. The + * remainder was discarded by the OS. Used in uv_udp_recv_cb. + */ + UV_UDP_PARTIAL = 2, + /* + * Indicates if SO_REUSEADDR will be set when binding the handle in + * uv_udp_bind. + * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other + * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that + * multiple threads or processes can bind to the same address without error + * (provided they all set the flag) but only the last one to bind will receive + * any traffic, in effect "stealing" the port from the previous listener. + */ + UV_UDP_REUSEADDR = 4, + /* + * Indicates that the message was received by recvmmsg, so the buffer provided + * must not be freed by the recv_cb callback. + */ + UV_UDP_MMSG_CHUNK = 8, + /* + * Indicates that recvmmsg should be used, if available. + */ + UV_UDP_RECVMMSG = 256 +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_udp_send_cb)(uv_udp_send_t*\fI\ req\fP, int\fI\ status\fP) +Type definition for callback passed to \fI\%uv_udp_send()\fP, which is +called after the data was sent. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_udp_recv_cb)(uv_udp_t*\fI\ handle\fP, ssize_t\fI\ nread\fP, const uv_buf_t*\fI\ buf\fP, const struct sockaddr*\fI\ addr\fP, unsigned\fI\ flags\fP) +Type definition for callback passed to \fI\%uv_udp_recv_start()\fP, which +is called when the endpoint receives data. +.INDENT 7.0 +.IP \(bu 2 +\fIhandle\fP: UDP handle +.IP \(bu 2 +\fInread\fP: Number of bytes that have been received. +0 if there is no more data to read. Note that 0 may also mean that an +empty datagram was received (in this case \fIaddr\fP is not NULL). < 0 if +a transmission error was detected. +.IP \(bu 2 +\fIbuf\fP: \fBuv_buf_t\fP with the received data. +.IP \(bu 2 +\fIaddr\fP: \fBstruct sockaddr*\fP containing the address of the sender. +Can be NULL. Valid for the duration of the callback only. +.IP \(bu 2 +\fIflags\fP: One or more or\(aqed UV_UDP_* constants. +.UNINDENT +.sp +The callee is responsible for freeing the buffer, libuv does not reuse it. +The buffer may be a null buffer (where \fIbuf\->base\fP == NULL and \fIbuf\->len\fP == 0) +on error. +.sp +When using \fI\%recvmmsg(2)\fP, chunks will have the \fIUV_UDP_MMSG_CHUNK\fP flag set, +those must not be freed. There will be a final callback with \fInread\fP set to 0, +\fIaddr\fP set to NULL and the buffer pointing at the initially allocated data with +the \fIUV_UDP_MMSG_CHUNK\fP flag cleared. This is a good chance for the callee to +free the provided buffer. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The receive callback will be called with \fInread\fP == 0 and \fIaddr\fP == NULL when there is +nothing to read, and with \fInread\fP == 0 and \fIaddr\fP != NULL when an empty UDP packet is +received. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_membership +Membership type for a multicast address. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_LEAVE_GROUP = 0, + UV_JOIN_GROUP +} uv_membership; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B size_t uv_udp_t.send_queue_size +Number of bytes queued for sending. This field strictly shows how much +information is currently queued. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_udp_t.send_queue_count +Number of send requests currently in the queue awaiting to be processed. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_udp_t* uv_udp_send_t.handle +UDP handle where this send request is taking place. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_udp_init(uv_loop_t*\fI\ loop\fP, uv_udp_t*\fI\ handle\fP) +Initialize a new UDP handle. The actual socket is created lazily. +Returns 0 on success. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_init_ex(uv_loop_t*\fI\ loop\fP, uv_udp_t*\fI\ handle\fP, unsigned int\fI\ flags\fP) +Initialize the handle with the specified flags. The lower 8 bits of the \fIflags\fP +parameter are used as the socket domain. A socket will be created for the given domain. +If the specified domain is \fBAF_UNSPEC\fP no socket is created, just like \fI\%uv_udp_init()\fP\&. +.sp +The remaining bits can be used to set one of these flags: +.INDENT 7.0 +.IP \(bu 2 +\fIUV_UDP_RECVMMSG\fP: if set, and the platform supports it, \fI\%recvmmsg(2)\fP will +be used. +.UNINDENT +.sp +New in version 1.7.0. + +.sp +Changed in version 1.37.0: added the \fIUV_UDP_RECVMMSG\fP flag. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_open(uv_udp_t*\fI\ handle\fP, uv_os_sock_t\fI\ sock\fP) +Opens an existing file descriptor or Windows SOCKET as a UDP handle. +.sp +Unix only: +The only requirement of the \fIsock\fP argument is that it follows the datagram +contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc). +In other words, other datagram\-type sockets like raw sockets or netlink +sockets can also be passed to this function. +.sp +Changed in version 1.2.1: the file descriptor is set to non\-blocking mode. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The passed file descriptor or SOCKET is not checked for its type, but +it\(aqs required that it represents a valid datagram socket. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_bind(uv_udp_t*\fI\ handle\fP, const struct sockaddr*\fI\ addr\fP, unsigned int\fI\ flags\fP) +Bind the UDP handle to an IP address and port. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBaddr\fP \-\- \fIstruct sockaddr_in\fP or \fIstruct sockaddr_in6\fP +with the address and port to bind to. +.IP \(bu 2 +\fBflags\fP \-\- Indicate how the socket will be bound, +\fBUV_UDP_IPV6ONLY\fP and \fBUV_UDP_REUSEADDR\fP are supported. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_connect(uv_udp_t*\fI\ handle\fP, const struct sockaddr*\fI\ addr\fP) +Associate the UDP handle to a remote address and port, so every +message sent by this handle is automatically sent to that destination. +Calling this function with a \fINULL\fP \fIaddr\fP disconnects the handle. +Trying to call \fIuv_udp_connect()\fP on an already connected handle will result +in an \fIUV_EISCONN\fP error. Trying to disconnect a handle that is not +connected will return an \fIUV_ENOTCONN\fP error. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBaddr\fP \-\- \fIstruct sockaddr_in\fP or \fIstruct sockaddr_in6\fP +with the address and port to associate to. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +New in version 1.27.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_getpeername(const uv_udp_t*\fI\ handle\fP, struct sockaddr*\fI\ name\fP, int*\fI\ namelen\fP) +Get the remote IP and port of the UDP handle on connected UDP handles. +On unconnected handles, it returns \fIUV_ENOTCONN\fP\&. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP and bound. +.IP \(bu 2 +\fBname\fP \-\- Pointer to the structure to be filled with the address data. +In order to support IPv4 and IPv6 \fIstruct sockaddr_storage\fP should be +used. +.IP \(bu 2 +\fBnamelen\fP \-\- On input it indicates the data of the \fIname\fP field. On +output it indicates how much of it was filled. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure +.UNINDENT +.sp +New in version 1.27.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_getsockname(const uv_udp_t*\fI\ handle\fP, struct sockaddr*\fI\ name\fP, int*\fI\ namelen\fP) +Get the local IP and port of the UDP handle. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP and bound. +.IP \(bu 2 +\fBname\fP \-\- Pointer to the structure to be filled with the address data. +In order to support IPv4 and IPv6 \fIstruct sockaddr_storage\fP should be +used. +.IP \(bu 2 +\fBnamelen\fP \-\- On input it indicates the data of the \fIname\fP field. On +output it indicates how much of it was filled. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_membership(uv_udp_t*\fI\ handle\fP, const char*\fI\ multicast_addr\fP, const char*\fI\ interface_addr\fP, uv_membership\fI\ membership\fP) +Set membership for a multicast address +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBmulticast_addr\fP \-\- Multicast address to set membership for. +.IP \(bu 2 +\fBinterface_addr\fP \-\- Interface address. +.IP \(bu 2 +\fBmembership\fP \-\- Should be \fBUV_JOIN_GROUP\fP or \fBUV_LEAVE_GROUP\fP\&. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_source_membership(uv_udp_t*\fI\ handle\fP, const char*\fI\ multicast_addr\fP, const char*\fI\ interface_addr\fP, const char*\fI\ source_addr\fP, uv_membership\fI\ membership\fP) +Set membership for a source\-specific multicast group. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBmulticast_addr\fP \-\- Multicast address to set membership for. +.IP \(bu 2 +\fBinterface_addr\fP \-\- Interface address. +.IP \(bu 2 +\fBsource_addr\fP \-\- Source address. +.IP \(bu 2 +\fBmembership\fP \-\- Should be \fBUV_JOIN_GROUP\fP or \fBUV_LEAVE_GROUP\fP\&. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +New in version 1.32.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_multicast_loop(uv_udp_t*\fI\ handle\fP, int\fI\ on\fP) +Set IP multicast loop flag. Makes multicast packets loop back to +local sockets. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBon\fP \-\- 1 for on, 0 for off. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_multicast_ttl(uv_udp_t*\fI\ handle\fP, int\fI\ ttl\fP) +Set the multicast ttl. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBttl\fP \-\- 1 through 255. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_multicast_interface(uv_udp_t*\fI\ handle\fP, const char*\fI\ interface_addr\fP) +Set the multicast interface to send or receive data on. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBinterface_addr\fP \-\- interface address. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_broadcast(uv_udp_t*\fI\ handle\fP, int\fI\ on\fP) +Set broadcast on or off. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBon\fP \-\- 1 for on, 0 for off. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_set_ttl(uv_udp_t*\fI\ handle\fP, int\fI\ ttl\fP) +Set the time to live. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBttl\fP \-\- 1 through 255. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_send(uv_udp_send_t*\fI\ req\fP, uv_udp_t*\fI\ handle\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, const struct sockaddr*\fI\ addr\fP, uv_udp_send_cb\fI\ send_cb\fP) +Send data over the UDP socket. If the socket has not previously been bound +with \fI\%uv_udp_bind()\fP it will be bound to 0.0.0.0 +(the "all interfaces" IPv4 address) and a random port number. +.sp +On Windows if the \fIaddr\fP is initialized to point to an unspecified address +(\fB0.0.0.0\fP or \fB::\fP) it will be changed to point to \fBlocalhost\fP\&. +This is done to match the behavior of Linux systems. +.sp +For connected UDP handles, \fIaddr\fP must be set to \fINULL\fP, otherwise it will +return \fIUV_EISCONN\fP error. +.sp +For connectionless UDP handles, \fIaddr\fP cannot be \fINULL\fP, otherwise it will +return \fIUV_EDESTADDRREQ\fP error. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBreq\fP \-\- UDP request handle. Need not be initialized. +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBbufs\fP \-\- List of buffers to send. +.IP \(bu 2 +\fBnbufs\fP \-\- Number of buffers in \fIbufs\fP\&. +.IP \(bu 2 +\fBaddr\fP \-\- \fIstruct sockaddr_in\fP or \fIstruct sockaddr_in6\fP with the +address and port of the remote peer. +.IP \(bu 2 +\fBsend_cb\fP \-\- Callback to invoke when the data has been sent out. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +Changed in version 1.19.0: added \fB0.0.0.0\fP and \fB::\fP to \fBlocalhost\fP +mapping + +.sp +Changed in version 1.27.0: added support for connected sockets + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_try_send(uv_udp_t*\fI\ handle\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, const struct sockaddr*\fI\ addr\fP) +Same as \fI\%uv_udp_send()\fP, but won\(aqt queue a send request if it can\(aqt +be completed immediately. +.sp +For connected UDP handles, \fIaddr\fP must be set to \fINULL\fP, otherwise it will +return \fIUV_EISCONN\fP error. +.sp +For connectionless UDP handles, \fIaddr\fP cannot be \fINULL\fP, otherwise it will +return \fIUV_EDESTADDRREQ\fP error. +.INDENT 7.0 +.TP +.B Returns +>= 0: number of bytes sent (it matches the given buffer size). +< 0: negative error code (\fBUV_EAGAIN\fP is returned when the message +can\(aqt be sent immediately). +.UNINDENT +.sp +Changed in version 1.27.0: added support for connected sockets + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_recv_start(uv_udp_t*\fI\ handle\fP, uv_alloc_cb\fI\ alloc_cb\fP, uv_udp_recv_cb\fI\ recv_cb\fP) +Prepare for receiving data. If the socket has not previously been bound +with \fI\%uv_udp_bind()\fP it is bound to 0.0.0.0 (the "all interfaces" +IPv4 address) and a random port number. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.IP \(bu 2 +\fBalloc_cb\fP \-\- Callback to invoke when temporary storage is needed. +.IP \(bu 2 +\fBrecv_cb\fP \-\- Callback to invoke with received data. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.sp +Changed in version 1.35.0: added support for \fI\%recvmmsg(2)\fP on supported platforms). +The use of this feature requires a buffer larger than +2 * 64KB to be passed to \fIalloc_cb\fP\&. + +.sp +Changed in version 1.37.0: \fI\%recvmmsg(2)\fP support is no longer enabled implicitly, +it must be explicitly requested by passing the \fIUV_UDP_RECVMMSG\fP flag to +\fI\%uv_udp_init_ex()\fP\&. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_udp_recv_stop(uv_udp_t*\fI\ handle\fP) +Stop listening for incoming datagrams. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhandle\fP \-\- UDP handle. Should have been initialized with +\fI\%uv_udp_init()\fP\&. +.UNINDENT +.TP +.B Returns +0 on success, or an error code < 0 on failure. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_udp_get_send_queue_size(const uv_udp_t*\fI\ handle\fP) +Returns \fIhandle\->send_queue_size\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B size_t uv_udp_get_send_queue_count(const uv_udp_t*\fI\ handle\fP) +Returns \fIhandle\->send_queue_count\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_fs_event_t\fP \-\-\- FS Event handle +.sp +FS Event handles allow the user to monitor a given path for changes, for example, +if the file was renamed or there was a generic change in it. This handle uses +the best backend for the job on each platform. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +For AIX, the non default IBM bos.ahafs package has to be installed. +The AIX Event Infrastructure file system (ahafs) has some limitations: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +ahafs tracks monitoring per process and is not thread safe. A separate process +must be spawned for each monitor for the same event. +.IP \(bu 2 +Events for file modification (writing to a file) are not received if only the +containing folder is watched. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +See \fI\%documentation\fP for more details. +.sp +The z/OS file system events monitoring infrastructure does not notify of file +creation/deletion within a directory that is being monitored. +See the \fI\%IBM Knowledge centre\fP for more details. +.UNINDENT +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_fs_event_t +FS Event handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_fs_event_cb)(uv_fs_event_t*\fI\ handle\fP, const char*\fI\ filename\fP, int\fI\ events\fP, int\fI\ status\fP) +Callback passed to \fI\%uv_fs_event_start()\fP which will be called repeatedly +after the handle is started. If the handle was started with a directory the +\fIfilename\fP parameter will be a relative path to a file contained in the directory. +The \fIevents\fP parameter is an ORed mask of \fI\%uv_fs_event\fP elements. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_fs_event +Event types that \fI\%uv_fs_event_t\fP handles monitor. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +enum uv_fs_event { + UV_RENAME = 1, + UV_CHANGE = 2 +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_fs_event_flags +Flags that can be passed to \fI\%uv_fs_event_start()\fP to control its +behavior. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +enum uv_fs_event_flags { + /* + * By default, if the fs event watcher is given a directory name, we will + * watch for all events in that directory. This flags overrides this behavior + * and makes fs_event report only changes to the directory entry itself. This + * flag does not affect individual files watched. + * This flag is currently not implemented yet on any backend. + */ + UV_FS_EVENT_WATCH_ENTRY = 1, + /* + * By default uv_fs_event will try to use a kernel interface such as inotify + * or kqueue to detect events. This may not work on remote file systems such + * as NFS mounts. This flag makes fs_event fall back to calling stat() on a + * regular interval. + * This flag is currently not implemented yet on any backend. + */ + UV_FS_EVENT_STAT = 2, + /* + * By default, event watcher, when watching directory, is not registering + * (is ignoring) changes in its subdirectories. + * This flag will override this behaviour on platforms that support it. + */ + UV_FS_EVENT_RECURSIVE = 4 +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_fs_event_init(uv_loop_t*\fI\ loop\fP, uv_fs_event_t*\fI\ handle\fP) +Initialize the handle. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_event_start(uv_fs_event_t*\fI\ handle\fP, uv_fs_event_cb\fI\ cb\fP, const char*\fI\ path\fP, unsigned int\fI\ flags\fP) +Start the handle with the given callback, which will watch the specified +\fIpath\fP for changes. \fIflags\fP can be an ORed mask of \fI\%uv_fs_event_flags\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Currently the only supported flag is \fBUV_FS_EVENT_RECURSIVE\fP and +only on OSX and Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_event_stop(uv_fs_event_t*\fI\ handle\fP) +Stop the handle, the callback will no longer be called. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_event_getpath(uv_fs_event_t*\fI\ handle\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Get the path being monitored by the handle. The buffer must be preallocated +by the user. Returns 0 on success or an error code < 0 in case of failure. +On success, \fIbuffer\fP will contain the path and \fIsize\fP its length. If the buffer +is not big enough \fIUV_ENOBUFS\fP will be returned and \fIsize\fP will be set to +the required size, including the null terminator. +.sp +Changed in version 1.3.0: the returned length no longer includes the terminating null byte, +and the buffer is not null terminated. + +.sp +Changed in version 1.9.0: the returned length includes the terminating null +byte on \fIUV_ENOBUFS\fP, and the buffer is null terminated +on success. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS \fI\%uv_fs_poll_t\fP \-\-\- FS Poll handle +.sp +FS Poll handles allow the user to monitor a given path for changes. Unlike +\fBuv_fs_event_t\fP, fs poll handles use \fIstat\fP to detect when a file has +changed so they can work on file systems where fs event handles can\(aqt. +.SS Data types +.INDENT 0.0 +.TP +.B uv_fs_poll_t +FS Poll handle type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_fs_poll_cb)(uv_fs_poll_t*\fI\ handle\fP, int\fI\ status\fP, const uv_stat_t*\fI\ prev\fP, const uv_stat_t*\fI\ curr\fP) +Callback passed to \fI\%uv_fs_poll_start()\fP which will be called repeatedly +after the handle is started, when any change happens to the monitored path. +.sp +The callback is invoked with \fIstatus < 0\fP if \fIpath\fP does not exist +or is inaccessible. The watcher is \fInot\fP stopped but your callback is +not called again until something changes (e.g. when the file is created +or the error reason changes). +.sp +When \fIstatus == 0\fP, the callback receives pointers to the old and new +\fBuv_stat_t\fP structs. They are valid for the duration of the +callback only. +.UNINDENT +.SS Public members +.sp +N/A +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_fs_poll_init(uv_loop_t*\fI\ loop\fP, uv_fs_poll_t*\fI\ handle\fP) +Initialize the handle. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_poll_start(uv_fs_poll_t*\fI\ handle\fP, uv_fs_poll_cb\fI\ poll_cb\fP, const char*\fI\ path\fP, unsigned int\fI\ interval\fP) +Check the file at \fIpath\fP for changes every \fIinterval\fP milliseconds. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For maximum portability, use multi\-second intervals. Sub\-second intervals will not detect +all changes on many file systems. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_poll_stop(uv_fs_poll_t*\fI\ handle\fP) +Stop the handle, the callback will no longer be called. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_poll_getpath(uv_fs_poll_t*\fI\ handle\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Get the path being monitored by the handle. The buffer must be preallocated +by the user. Returns 0 on success or an error code < 0 in case of failure. +On success, \fIbuffer\fP will contain the path and \fIsize\fP its length. If the buffer +is not big enough \fIUV_ENOBUFS\fP will be returned and \fIsize\fP will be set to +the required size. +.sp +Changed in version 1.3.0: the returned length no longer includes the terminating null byte, +and the buffer is not null terminated. + +.sp +Changed in version 1.9.0: the returned length includes the terminating null +byte on \fIUV_ENOBUFS\fP, and the buffer is null terminated +on success. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_handle_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS File system operations +.sp +libuv provides a wide variety of cross\-platform sync and async file system +operations. All functions defined in this document take a callback, which is +allowed to be NULL. If the callback is NULL the request is completed synchronously, +otherwise it will be performed asynchronously. +.sp +All file operations are run on the threadpool. See threadpool for information +on the threadpool size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +On Windows \fIuv_fs_*\fP functions use utf\-8 encoding. +.UNINDENT +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_fs_t +File system request type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_timespec_t +Portable equivalent of \fBstruct timespec\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + long tv_sec; + long tv_nsec; +} uv_timespec_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stat_t +Portable equivalent of \fBstruct stat\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + uint64_t st_dev; + uint64_t st_mode; + uint64_t st_nlink; + uint64_t st_uid; + uint64_t st_gid; + uint64_t st_rdev; + uint64_t st_ino; + uint64_t st_size; + uint64_t st_blksize; + uint64_t st_blocks; + uint64_t st_flags; + uint64_t st_gen; + uv_timespec_t st_atim; + uv_timespec_t st_mtim; + uv_timespec_t st_ctim; + uv_timespec_t st_birthtim; +} uv_stat_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_fs_type +File system request type. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_FS_UNKNOWN = \-1, + UV_FS_CUSTOM, + UV_FS_OPEN, + UV_FS_CLOSE, + UV_FS_READ, + UV_FS_WRITE, + UV_FS_SENDFILE, + UV_FS_STAT, + UV_FS_LSTAT, + UV_FS_FSTAT, + UV_FS_FTRUNCATE, + UV_FS_UTIME, + UV_FS_FUTIME, + UV_FS_ACCESS, + UV_FS_CHMOD, + UV_FS_FCHMOD, + UV_FS_FSYNC, + UV_FS_FDATASYNC, + UV_FS_UNLINK, + UV_FS_RMDIR, + UV_FS_MKDIR, + UV_FS_MKDTEMP, + UV_FS_RENAME, + UV_FS_SCANDIR, + UV_FS_LINK, + UV_FS_SYMLINK, + UV_FS_READLINK, + UV_FS_CHOWN, + UV_FS_FCHOWN, + UV_FS_REALPATH, + UV_FS_COPYFILE, + UV_FS_LCHOWN, + UV_FS_OPENDIR, + UV_FS_READDIR, + UV_FS_CLOSEDIR, + UV_FS_MKSTEMP, + UV_FS_LUTIME +} uv_fs_type; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_statfs_t +Reduced cross platform equivalent of \fBstruct statfs\fP\&. +Used in \fI\%uv_fs_statfs()\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_statfs_s { + uint64_t f_type; + uint64_t f_bsize; + uint64_t f_blocks; + uint64_t f_bfree; + uint64_t f_bavail; + uint64_t f_files; + uint64_t f_ffree; + uint64_t f_spare[4]; +} uv_statfs_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_dirent_t +Cross platform (reduced) equivalent of \fBstruct dirent\fP\&. +Used in \fI\%uv_fs_scandir_next()\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef enum { + UV_DIRENT_UNKNOWN, + UV_DIRENT_FILE, + UV_DIRENT_DIR, + UV_DIRENT_LINK, + UV_DIRENT_FIFO, + UV_DIRENT_SOCKET, + UV_DIRENT_CHAR, + UV_DIRENT_BLOCK +} uv_dirent_type_t; + +typedef struct uv_dirent_s { + const char* name; + uv_dirent_type_t type; +} uv_dirent_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_dir_t +Data type used for streaming directory iteration. +Used by \fI\%uv_fs_opendir()\fP, \fI\%uv_fs_readdir()\fP, and +\fI\%uv_fs_closedir()\fP\&. \fIdirents\fP represents a user provided array of +\fIuv_dirent_t\(gas used to hold results. \(ganentries\fP is the user provided maximum +array size of \fIdirents\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_dir_s { + uv_dirent_t* dirents; + size_t nentries; +} uv_dir_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B uv_loop_t* uv_fs_t.loop +Loop that started this request and where completion will be reported. +Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_fs_type uv_fs_t.fs_type +FS request type. +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_fs_t.path +Path affecting the request. +.UNINDENT +.INDENT 0.0 +.TP +.B ssize_t uv_fs_t.result +Result of the request. < 0 means error, success otherwise. On requests such +as \fI\%uv_fs_read()\fP or \fI\%uv_fs_write()\fP it indicates the amount of +data that was read or written, respectively. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stat_t uv_fs_t.statbuf +Stores the result of \fI\%uv_fs_stat()\fP and other stat requests. +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_fs_t.ptr +Stores the result of \fI\%uv_fs_readlink()\fP and +\fI\%uv_fs_realpath()\fP and serves as an alias to \fIstatbuf\fP\&. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B void uv_fs_req_cleanup(uv_fs_t*\fI\ req\fP) +Cleanup request. Must be called after a request is finished to deallocate +any memory libuv might have allocated. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_close(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%close(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_open(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, int\fI\ flags\fP, int\fI\ mode\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%open(2)\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows libuv uses \fICreateFileW\fP and thus the file is always opened +in binary mode. Because of this the O_BINARY and O_TEXT flags are not +supported. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_read(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, int64_t\fI\ offset\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%preadv(2)\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows, under non\-MSVC environments (e.g. when GCC or Clang is used +to build libuv), files opened using \fBUV_FS_O_FILEMAP\fP may cause a fatal +crash if the memory mapped read operation fails. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_unlink(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%unlink(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_write(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, const uv_buf_t\fI\ bufs[]\fP, unsigned int\fI\ nbufs\fP, int64_t\fI\ offset\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%pwritev(2)\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows, under non\-MSVC environments (e.g. when GCC or Clang is used +to build libuv), files opened using \fBUV_FS_O_FILEMAP\fP may cause a fatal +crash if the memory mapped write operation fails. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_mkdir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, int\fI\ mode\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%mkdir(2)\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fImode\fP is currently not implemented on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_mkdtemp(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ tpl\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%mkdtemp(3)\fP\&. The result can be found as a null terminated string at \fIreq\->path\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_mkstemp(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ tpl\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%mkstemp(3)\fP\&. The created file path can be found as a null terminated string at \fIreq\->path\fP\&. +The file descriptor can be found as an integer at \fIreq\->result\fP\&. +.sp +New in version 1.34.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_rmdir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%rmdir(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_opendir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Opens \fIpath\fP as a directory stream. On success, a \fIuv_dir_t\fP is allocated +and returned via \fIreq\->ptr\fP\&. This memory is not freed by +\fIuv_fs_req_cleanup()\fP, although \fIreq\->ptr\fP is set to \fINULL\fP\&. The allocated +memory must be freed by calling \fIuv_fs_closedir()\fP\&. On failure, no memory +is allocated. +.sp +The contents of the directory can be iterated over by passing the resulting +\fIuv_dir_t\fP to \fIuv_fs_readdir()\fP\&. +.sp +New in version 1.28.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_closedir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_dir_t*\fI\ dir\fP, uv_fs_cb\fI\ cb\fP) +Closes the directory stream represented by \fIdir\fP and frees the memory +allocated by \fIuv_fs_opendir()\fP\&. +.sp +New in version 1.28.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_readdir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_dir_t*\fI\ dir\fP, uv_fs_cb\fI\ cb\fP) +Iterates over the directory stream, \fIdir\fP, returned by a successful +\fIuv_fs_opendir()\fP call. Prior to invoking \fIuv_fs_readdir()\fP, the caller +must set \fIdir\->dirents\fP and \fIdir\->nentries\fP, representing the array of +\fI\%uv_dirent_t\fP elements used to hold the read directory entries and +its size. +.sp +On success, the result is an integer >= 0 representing the number of entries +read from the stream. +.sp +New in version 1.28.0. + +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIuv_fs_readdir()\fP is not thread safe. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function does not return the "." and ".." entries. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On success this function allocates memory that must be freed using +\fIuv_fs_req_cleanup()\fP\&. \fIuv_fs_req_cleanup()\fP must be called before +closing the directory with \fIuv_fs_closedir()\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_scandir(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, int\fI\ flags\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_scandir_next(uv_fs_t*\fI\ req\fP, uv_dirent_t*\fI\ ent\fP) +Equivalent to \fI\%scandir(3)\fP, with a slightly different API. Once the callback +for the request is called, the user can use \fI\%uv_fs_scandir_next()\fP to +get \fIent\fP populated with the next directory entry data. When there are no +more entries \fBUV_EOF\fP will be returned. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Unlike \fIscandir(3)\fP, this function does not return the "." and ".." entries. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Linux, getting the type of an entry is only supported by some file systems (btrfs, ext2, +ext3 and ext4 at the time of this writing), check the \fI\%getdents(2)\fP man page. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_stat(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_fstat(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_lstat(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%stat(2)\fP, \fI\%fstat(2)\fP and \fI\%lstat(2)\fP respectively. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_statfs(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%statfs(2)\fP\&. On success, a \fIuv_statfs_t\fP is allocated +and returned via \fIreq\->ptr\fP\&. This memory is freed by \fIuv_fs_req_cleanup()\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Any fields in the resulting \fIuv_statfs_t\fP that are not supported by the +underlying operating system are set to zero. +.UNINDENT +.UNINDENT +.sp +New in version 1.31.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_rename(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, const char*\fI\ new_path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%rename(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_fsync(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%fsync(2)\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For AIX, \fIuv_fs_fsync\fP returns \fIUV_EBADF\fP on file descriptors referencing +non regular files. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_fdatasync(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%fdatasync(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_ftruncate(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, int64_t\fI\ offset\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%ftruncate(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_copyfile(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, const char*\fI\ new_path\fP, int\fI\ flags\fP, uv_fs_cb\fI\ cb\fP) +Copies a file from \fIpath\fP to \fInew_path\fP\&. Supported \fIflags\fP are described below. +.INDENT 7.0 +.IP \(bu 2 +\fIUV_FS_COPYFILE_EXCL\fP: If present, \fIuv_fs_copyfile()\fP will fail with +\fIUV_EEXIST\fP if the destination path already exists. The default behavior +is to overwrite the destination if it exists. +.IP \(bu 2 +\fIUV_FS_COPYFILE_FICLONE\fP: If present, \fIuv_fs_copyfile()\fP will attempt to +create a copy\-on\-write reflink. If the underlying platform does not +support copy\-on\-write, or an error occurs while attempting to use +copy\-on\-write, a fallback copy mechanism based on +\fI\%uv_fs_sendfile()\fP is used. +.IP \(bu 2 +\fIUV_FS_COPYFILE_FICLONE_FORCE\fP: If present, \fIuv_fs_copyfile()\fP will +attempt to create a copy\-on\-write reflink. If the underlying platform does +not support copy\-on\-write, or an error occurs while attempting to use +copy\-on\-write, then an error is returned. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +If the destination path is created, but an error occurs while copying +the data, then the destination path is removed. There is a brief window +of time between closing and removing the file where another process +could access the file. +.UNINDENT +.UNINDENT +.sp +New in version 1.14.0. + +.sp +Changed in version 1.20.0: \fIUV_FS_COPYFILE_FICLONE\fP and +\fIUV_FS_COPYFILE_FICLONE_FORCE\fP are supported. + +.sp +Changed in version 1.33.0: If an error occurs while using +\fIUV_FS_COPYFILE_FICLONE_FORCE\fP, that error is returned. Previously, +all errors were mapped to \fIUV_ENOTSUP\fP\&. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_sendfile(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ out_fd\fP, uv_file\fI\ in_fd\fP, int64_t\fI\ in_offset\fP, size_t\fI\ length\fP, uv_fs_cb\fI\ cb\fP) +Limited equivalent to \fI\%sendfile(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_access(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, int\fI\ mode\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%access(2)\fP on Unix. Windows uses \fBGetFileAttributesW()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_chmod(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, int\fI\ mode\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_fchmod(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, int\fI\ mode\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%chmod(2)\fP and \fI\%fchmod(2)\fP respectively. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_utime(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, double\fI\ atime\fP, double\fI\ mtime\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_futime(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, double\fI\ atime\fP, double\fI\ mtime\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_lutime(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, double\fI\ atime\fP, double\fI\ mtime\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%utime(2)\fP, \fI\%futimes(3)\fP and \fI\%lutimes(3)\fP respectively. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +z/OS: \fIuv_fs_lutime()\fP is not implemented for z/OS. It can still be called but will return +\fBUV_ENOSYS\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +AIX: \fIuv_fs_futime()\fP and \fIuv_fs_lutime()\fP functions only work for AIX 7.1 and newer. +They can still be called on older versions but will return \fBUV_ENOSYS\fP\&. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.10.0: sub\-second precission is supported on Windows + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_link(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, const char*\fI\ new_path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%link(2)\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_symlink(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, const char*\fI\ new_path\fP, int\fI\ flags\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%symlink(2)\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows the \fIflags\fP parameter can be specified to control how the symlink will +be created: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBUV_FS_SYMLINK_DIR\fP: indicates that \fIpath\fP points to a directory. +.IP \(bu 2 +\fBUV_FS_SYMLINK_JUNCTION\fP: request that the symlink is created +using junction points. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_readlink(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%readlink(2)\fP\&. +The resulting string is stored in \fIreq\->ptr\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_realpath(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%realpath(3)\fP on Unix. Windows uses \fI\%GetFinalPathNameByHandle\fP\&. +The resulting string is stored in \fIreq\->ptr\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function has certain platform\-specific caveats that were discovered when used in Node. +.INDENT 0.0 +.IP \(bu 2 +macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are +found while resolving the given path. This limit is hardcoded and cannot be sidestepped. +.IP \(bu 2 +Windows: while this function works in the common case, there are a number of corner cases +where it doesn\(aqt: +.INDENT 2.0 +.IP \(bu 2 +Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) +cannot be resolved. +.IP \(bu 2 +Inconsistent casing when using drive letters. +.IP \(bu 2 +Resolved path bypasses subst\(aqd drives. +.UNINDENT +.UNINDENT +.sp +While this function can still be used, it\(aqs not recommended if scenarios such as the +above need to be supported. +.sp +The background story and some more details on these issues can be checked +\fI\%here\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not implemented on Windows XP and Windows Server 2003. +On these systems, UV_ENOSYS is returned. +.UNINDENT +.UNINDENT +.sp +New in version 1.8.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_chown(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_uid_t\fI\ uid\fP, uv_gid_t\fI\ gid\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_fchown(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, uv_file\fI\ file\fP, uv_uid_t\fI\ uid\fP, uv_gid_t\fI\ gid\fP, uv_fs_cb\fI\ cb\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_lchown(uv_loop_t*\fI\ loop\fP, uv_fs_t*\fI\ req\fP, const char*\fI\ path\fP, uv_uid_t\fI\ uid\fP, uv_gid_t\fI\ gid\fP, uv_fs_cb\fI\ cb\fP) +Equivalent to \fI\%chown(2)\fP, \fI\%fchown(2)\fP and \fI\%lchown(2)\fP respectively. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +These functions are not implemented on Windows. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.21.0: implemented uv_fs_lchown + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_fs_type uv_fs_get_type(const uv_fs_t*\fI\ req\fP) +Returns \fIreq\->fs_type\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B ssize_t uv_fs_get_result(const uv_fs_t*\fI\ req\fP) +Returns \fIreq\->result\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_fs_get_system_error(const uv_fs_t*\fI\ req\fP) +Returns the platform specific error code \- \fIGetLastError()\fP value on Windows +and \fI\-(req\->result)\fP on other platforms. +.sp +New in version 1.38.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_fs_get_ptr(const uv_fs_t*\fI\ req\fP) +Returns \fIreq\->ptr\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_fs_get_path(const uv_fs_t*\fI\ req\fP) +Returns \fIreq\->path\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_stat_t* uv_fs_get_statbuf(uv_fs_t*\fI\ req\fP) +Returns \fI&req\->statbuf\fP\&. +.sp +New in version 1.19.0. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS Helper functions +.INDENT 0.0 +.TP +.B uv_os_fd_t uv_get_osfhandle(int\fI\ fd\fP) +For a file descriptor in the C runtime, get the OS\-dependent handle. +On UNIX, returns the \fBfd\fP intact. On Windows, this calls \fI\%_get_osfhandle\fP\&. +Note that the return value is still owned by the C runtime, +any attempts to close it or to use it after closing the fd may lead to malfunction. +.INDENT 7.0 +.INDENT 3.5 +New in version 1.12.0. + +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_open_osfhandle(uv_os_fd_t\fI\ os_fd\fP) +For a OS\-dependent handle, get the file descriptor in the C runtime. +On UNIX, returns the \fBos_fd\fP intact. On Windows, this calls \fI\%_open_osfhandle\fP\&. +Note that the return value is still owned by the CRT, +any attempts to close it or to use it after closing the handle may lead to malfunction. +.INDENT 7.0 +.INDENT 3.5 +New in version 1.23.0. + +.UNINDENT +.UNINDENT +.UNINDENT +.SS File open constants +.INDENT 0.0 +.TP +.B UV_FS_O_APPEND +The file is opened in append mode. Before each write, the file offset is +positioned at the end of the file. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_CREAT +The file is created if it does not already exist. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_DIRECT +File I/O is done directly to and from user\-space buffers, which must be +aligned. Buffer size and address should be a multiple of the physical sector +size of the block device. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_DIRECT\fP is supported on Linux, and on Windows via +\fI\%FILE_FLAG_NO_BUFFERING\fP\&. +\fIUV_FS_O_DIRECT\fP is not supported on macOS. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_DIRECTORY +If the path is not a directory, fail the open. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_DIRECTORY\fP is not supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_DSYNC +The file is opened for synchronous I/O. Write operations will complete once +all data and a minimum of metadata are flushed to disk. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_DSYNC\fP is supported on Windows via +\fI\%FILE_FLAG_WRITE_THROUGH\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_EXCL +If the \fIO_CREAT\fP flag is set and the file already exists, fail the open. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +In general, the behavior of \fIO_EXCL\fP is undefined if it is used without +\fIO_CREAT\fP\&. There is one exception: on Linux 2.6 and later, \fIO_EXCL\fP can +be used without \fIO_CREAT\fP if pathname refers to a block device. If the +block device is in use by the system (e.g., mounted), the open will fail +with the error \fIEBUSY\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_EXLOCK +Atomically obtain an exclusive lock. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_EXLOCK\fP is only supported on macOS and Windows. +.UNINDENT +.UNINDENT +.sp +Changed in version 1.17.0: support is added for Windows. + +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_FILEMAP +Use a memory file mapping to access the file. When using this flag, the +file cannot be open multiple times concurrently. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_FILEMAP\fP is only supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_NOATIME +Do not update the file access time when the file is read. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_NOATIME\fP is not supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_NOCTTY +If the path identifies a terminal device, opening the path will not cause +that terminal to become the controlling terminal for the process (if the +process does not already have one). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_NOCTTY\fP is not supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_NOFOLLOW +If the path is a symbolic link, fail the open. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_NOFOLLOW\fP is not supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_NONBLOCK +Open the file in nonblocking mode if possible. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_NONBLOCK\fP is not supported on Windows. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_RANDOM +Access is intended to be random. The system can use this as a hint to +optimize file caching. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_RANDOM\fP is only supported on Windows via +\fI\%FILE_FLAG_RANDOM_ACCESS\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_RDONLY +Open the file for read\-only access. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_RDWR +Open the file for read\-write access. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_SEQUENTIAL +Access is intended to be sequential from beginning to end. The system can +use this as a hint to optimize file caching. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_SEQUENTIAL\fP is only supported on Windows via +\fI\%FILE_FLAG_SEQUENTIAL_SCAN\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_SHORT_LIVED +The file is temporary and should not be flushed to disk if possible. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_SHORT_LIVED\fP is only supported on Windows via +\fI\%FILE_ATTRIBUTE_TEMPORARY\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_SYMLINK +Open the symbolic link itself rather than the resource it points to. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_SYNC +The file is opened for synchronous I/O. Write operations will complete once +all data and all metadata are flushed to disk. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_SYNC\fP is supported on Windows via +\fI\%FILE_FLAG_WRITE_THROUGH\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_TEMPORARY +The file is temporary and should not be flushed to disk if possible. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIUV_FS_O_TEMPORARY\fP is only supported on Windows via +\fI\%FILE_ATTRIBUTE_TEMPORARY\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_TRUNC +If the file exists and is a regular file, and the file is opened +successfully for write access, its length shall be truncated to zero. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_FS_O_WRONLY +Open the file for write\-only access. +.UNINDENT +.SS Thread pool work scheduling +.sp +libuv provides a threadpool which can be used to run user code and get notified +in the loop thread. This thread pool is internally used to run all file system +operations, as well as getaddrinfo and getnameinfo requests. +.sp +Its default size is 4, but it can be changed at startup time by setting the +\fBUV_THREADPOOL_SIZE\fP environment variable to any value (the absolute maximum +is 1024). +.sp +Changed in version 1.30.0: the maximum UV_THREADPOOL_SIZE allowed was increased from 128 to 1024. + +.sp +The threadpool is global and shared across all event loops. When a particular +function makes use of the threadpool (i.e. when using \fI\%uv_queue_work()\fP) +libuv preallocates and initializes the maximum number of threads allowed by +\fBUV_THREADPOOL_SIZE\fP\&. This causes a relatively minor memory overhead +(~1MB for 128 threads) but increases the performance of threading at runtime. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Note that even though a global thread pool which is shared across all events +loops is used, the functions are not thread safe. +.UNINDENT +.UNINDENT +.SS Data types +.INDENT 0.0 +.TP +.B uv_work_t +Work request type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_work_cb)(uv_work_t*\fI\ req\fP) +Callback passed to \fI\%uv_queue_work()\fP which will be run on the thread +pool. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_after_work_cb)(uv_work_t*\fI\ req\fP, int\fI\ status\fP) +Callback passed to \fI\%uv_queue_work()\fP which will be called on the loop +thread after the work on the threadpool has been completed. If the work +was cancelled using \fBuv_cancel()\fP \fIstatus\fP will be \fBUV_ECANCELED\fP\&. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B uv_loop_t* uv_work_t.loop +Loop that started this request and where completion will be reported. +Readonly. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_queue_work(uv_loop_t*\fI\ loop\fP, uv_work_t*\fI\ req\fP, uv_work_cb\fI\ work_cb\fP, uv_after_work_cb\fI\ after_work_cb\fP) +Initializes a work request which will run the given \fIwork_cb\fP in a thread +from the threadpool. Once \fIwork_cb\fP is completed, \fIafter_work_cb\fP will be +called on the loop thread. +.sp +This request can be cancelled with \fBuv_cancel()\fP\&. +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS DNS utility functions +.sp +libuv provides asynchronous variants of \fIgetaddrinfo\fP and \fIgetnameinfo\fP\&. +.SS Data types +.INDENT 0.0 +.TP +.B uv_getaddrinfo_t +\fIgetaddrinfo\fP request type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t*\fI\ req\fP, int\fI\ status\fP, struct addrinfo*\fI\ res\fP) +Callback which will be called with the getaddrinfo request result once +complete. In case it was cancelled, \fIstatus\fP will have a value of +\fBUV_ECANCELED\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_getnameinfo_t +\fIgetnameinfo\fP request type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_getnameinfo_cb)(uv_getnameinfo_t*\fI\ req\fP, int\fI\ status\fP, const char*\fI\ hostname\fP, const char*\fI\ service\fP) +Callback which will be called with the getnameinfo request result once +complete. In case it was cancelled, \fIstatus\fP will have a value of +\fBUV_ECANCELED\fP\&. +.UNINDENT +.SS Public members +.INDENT 0.0 +.TP +.B uv_loop_t* uv_getaddrinfo_t.loop +Loop that started this getaddrinfo request and where completion will be +reported. Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B struct addrinfo* uv_getaddrinfo_t.addrinfo +Pointer to a \fIstruct addrinfo\fP containing the result. Must be freed by the user +with \fI\%uv_freeaddrinfo()\fP\&. +.sp +Changed in version 1.3.0: the field is declared as public. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_loop_t* uv_getnameinfo_t.loop +Loop that started this getnameinfo request and where completion will be +reported. Readonly. +.UNINDENT +.INDENT 0.0 +.TP +.B char[NI_MAXHOST] uv_getnameinfo_t.host +Char array containing the resulting host. It\(aqs null terminated. +.sp +Changed in version 1.3.0: the field is declared as public. + +.UNINDENT +.INDENT 0.0 +.TP +.B char[NI_MAXSERV] uv_getnameinfo_t.service +Char array containing the resulting service. It\(aqs null terminated. +.sp +Changed in version 1.3.0: the field is declared as public. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP members also apply. +.UNINDENT +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B int uv_getaddrinfo(uv_loop_t*\fI\ loop\fP, uv_getaddrinfo_t*\fI\ req\fP, uv_getaddrinfo_cb\fI\ getaddrinfo_cb\fP, const char*\fI\ node\fP, const char*\fI\ service\fP, const struct addrinfo*\fI\ hints\fP) +Asynchronous \fI\%getaddrinfo(3)\fP\&. +.sp +Either node or service may be NULL but not both. +.sp +\fIhints\fP is a pointer to a struct addrinfo with additional address type +constraints, or NULL. Consult \fIman \-s 3 getaddrinfo\fP for more details. +.sp +Returns 0 on success or an error code < 0 on failure. If successful, the +callback will get called sometime in the future with the lookup result, +which is either: +.INDENT 7.0 +.IP \(bu 2 +status == 0, the res argument points to a valid \fIstruct addrinfo\fP, or +.IP \(bu 2 +status < 0, the res argument is NULL. See the UV_EAI_* constants. +.UNINDENT +.sp +Call \fI\%uv_freeaddrinfo()\fP to free the addrinfo structure. +.sp +Changed in version 1.3.0: the callback parameter is now allowed to be NULL, +in which case the request will run \fBsynchronously\fP\&. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_freeaddrinfo(struct addrinfo*\fI\ ai\fP) +Free the struct addrinfo. Passing NULL is allowed and is a no\-op. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_getnameinfo(uv_loop_t*\fI\ loop\fP, uv_getnameinfo_t*\fI\ req\fP, uv_getnameinfo_cb\fI\ getnameinfo_cb\fP, const struct sockaddr*\fI\ addr\fP, int\fI\ flags\fP) +Asynchronous \fI\%getnameinfo(3)\fP\&. +.sp +Returns 0 on success or an error code < 0 on failure. If successful, the +callback will get called sometime in the future with the lookup result. +Consult \fIman \-s 3 getnameinfo\fP for more details. +.sp +Changed in version 1.3.0: the callback parameter is now allowed to be NULL, +in which case the request will run \fBsynchronously\fP\&. + +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_req_t\fP API functions also apply. +.UNINDENT +.UNINDENT +.SS Shared library handling +.sp +libuv provides cross platform utilities for loading shared libraries and +retrieving symbols from them, using the following API. +.SS Data types +.INDENT 0.0 +.TP +.B uv_lib_t +Shared library data type. +.UNINDENT +.SS Public members +.sp +N/A +.SS API +.INDENT 0.0 +.TP +.B int uv_dlopen(const char*\fI\ filename\fP, uv_lib_t*\fI\ lib\fP) +Opens a shared library. The filename is in utf\-8. Returns 0 on success and +\-1 on error. Call \fI\%uv_dlerror()\fP to get the error message. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_dlclose(uv_lib_t*\fI\ lib\fP) +Close the shared library. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_dlsym(uv_lib_t*\fI\ lib\fP, const char*\fI\ name\fP, void**\fI\ ptr\fP) +Retrieves a data pointer from a dynamic library. It is legal for a symbol +to map to NULL. Returns 0 on success and \-1 if the symbol was not found. +.UNINDENT +.INDENT 0.0 +.TP +.B const char* uv_dlerror(const uv_lib_t*\fI\ lib\fP) +Returns the last uv_dlopen() or uv_dlsym() error message. +.UNINDENT +.SS Threading and synchronization utilities +.sp +libuv provides cross\-platform implementations for multiple threading and +synchronization primitives. The API largely follows the pthreads API. +.SS Data types +.INDENT 0.0 +.TP +.B uv_thread_t +Thread data type. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_thread_cb)(void*\fI\ arg\fP) +Callback that is invoked to initialize thread execution. \fIarg\fP is the same +value that was passed to \fI\%uv_thread_create()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_key_t +Thread\-local key data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_once_t +Once\-only initializer data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_mutex_t +Mutex data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_rwlock_t +Read\-write lock data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_sem_t +Semaphore data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_cond_t +Condition data type. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_barrier_t +Barrier data type. +.UNINDENT +.SS API +.SS Threads +.INDENT 0.0 +.TP +.B uv_thread_options_t +Options for spawning a new thread (passed to \fI\%uv_thread_create_ex()\fP). +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_thread_options_s { + enum { + UV_THREAD_NO_FLAGS = 0x00, + UV_THREAD_HAS_STACK_SIZE = 0x01 + } flags; + size_t stack_size; +} uv_thread_options_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +More fields may be added to this struct at any time, so its exact +layout and size should not be relied upon. +.sp +New in version 1.26.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_thread_create(uv_thread_t*\fI\ tid\fP, uv_thread_cb\fI\ entry\fP, void*\fI\ arg\fP) +Changed in version 1.4.1: returns a UV_E* error code on failure + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_thread_create_ex(uv_thread_t*\fI\ tid\fP, const uv_thread_options_t*\fI\ params\fP, uv_thread_cb\fI\ entry\fP, void*\fI\ arg\fP) +Like \fI\%uv_thread_create()\fP, but additionally specifies options for creating a new thread. +.sp +If \fIUV_THREAD_HAS_STACK_SIZE\fP is set, \fIstack_size\fP specifies a stack size for the new thread. +\fI0\fP indicates that the default value should be used, i.e. behaves as if the flag was not set. +Other values will be rounded up to the nearest page boundary. +.sp +New in version 1.26.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_thread_t uv_thread_self(void) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_thread_join(uv_thread_t\fI\ *tid\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_thread_equal(const uv_thread_t*\fI\ t1\fP, const uv_thread_t*\fI\ t2\fP) +.UNINDENT +.SS Thread\-local storage +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The total thread\-local storage size may be limited. That is, it may not be possible to +create many TLS keys. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_key_create(uv_key_t*\fI\ key\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_key_delete(uv_key_t*\fI\ key\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void* uv_key_get(uv_key_t*\fI\ key\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_key_set(uv_key_t*\fI\ key\fP, void*\fI\ value\fP) +.UNINDENT +.SS Once\-only initialization +.sp +Runs a function once and only once. Concurrent calls to \fI\%uv_once()\fP with the +same guard will block all callers except one (it\(aqs unspecified which one). +The guard should be initialized statically with the UV_ONCE_INIT macro. +.INDENT 0.0 +.TP +.B void uv_once(uv_once_t*\fI\ guard\fP, void (\fI*callback\fP)(void)) +.UNINDENT +.SS Mutex locks +.sp +Functions return 0 on success or an error code < 0 (unless the +return type is void, of course). +.INDENT 0.0 +.TP +.B int uv_mutex_init(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_mutex_init_recursive(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_mutex_destroy(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_mutex_lock(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_mutex_trylock(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_mutex_unlock(uv_mutex_t*\fI\ handle\fP) +.UNINDENT +.SS Read\-write locks +.sp +Functions return 0 on success or an error code < 0 (unless the +return type is void, of course). +.INDENT 0.0 +.TP +.B int uv_rwlock_init(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_rwlock_destroy(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_rwlock_rdlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_rwlock_tryrdlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_rwlock_rdunlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_rwlock_wrlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_rwlock_trywrlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_rwlock_wrunlock(uv_rwlock_t*\fI\ rwlock\fP) +.UNINDENT +.SS Semaphores +.sp +Functions return 0 on success or an error code < 0 (unless the +return type is void, of course). +.INDENT 0.0 +.TP +.B int uv_sem_init(uv_sem_t*\fI\ sem\fP, unsigned int\fI\ value\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_sem_destroy(uv_sem_t*\fI\ sem\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_sem_post(uv_sem_t*\fI\ sem\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_sem_wait(uv_sem_t*\fI\ sem\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_sem_trywait(uv_sem_t*\fI\ sem\fP) +.UNINDENT +.SS Conditions +.sp +Functions return 0 on success or an error code < 0 (unless the +return type is void, of course). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Callers should be prepared to deal with spurious wakeups on \fI\%uv_cond_wait()\fP +and \fI\%uv_cond_timedwait()\fP\&. +.IP 2. 3 +The timeout parameter for \fI\%uv_cond_timedwait()\fP is relative to the time +at which function is called. +.IP 3. 3 +On z/OS, the timeout parameter for \fI\%uv_cond_timedwait()\fP is converted to an +absolute system time at which the wait expires. If the current system clock time +passes the absolute time calculated before the condition is signaled, an ETIMEDOUT +error results. After the wait begins, the wait time is not affected by changes +to the system clock. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_cond_init(uv_cond_t*\fI\ cond\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_cond_destroy(uv_cond_t*\fI\ cond\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_cond_signal(uv_cond_t*\fI\ cond\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_cond_broadcast(uv_cond_t*\fI\ cond\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_cond_wait(uv_cond_t*\fI\ cond\fP, uv_mutex_t*\fI\ mutex\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_cond_timedwait(uv_cond_t*\fI\ cond\fP, uv_mutex_t*\fI\ mutex\fP, uint64_t\fI\ timeout\fP) +.UNINDENT +.SS Barriers +.sp +Functions return 0 on success or an error code < 0 (unless the +return type is void, of course). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fI\%uv_barrier_wait()\fP returns a value > 0 to an arbitrarily chosen "serializer" thread +to facilitate cleanup, i.e. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +if (uv_barrier_wait(&barrier) > 0) + uv_barrier_destroy(&barrier); +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_barrier_init(uv_barrier_t*\fI\ barrier\fP, unsigned int\fI\ count\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_barrier_destroy(uv_barrier_t*\fI\ barrier\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_barrier_wait(uv_barrier_t*\fI\ barrier\fP) +.UNINDENT +.SS Miscellaneous utilities +.sp +This section contains miscellaneous functions that don\(aqt really belong in any +other section. +.SS Data types +.INDENT 0.0 +.TP +.B uv_buf_t +Buffer data type. +.INDENT 7.0 +.TP +.B char* uv_buf_t.base +Pointer to the base of the buffer. +.UNINDENT +.INDENT 7.0 +.TP +.B size_t uv_buf_t.len +Total bytes in the buffer. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows this field is ULONG. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void* (*uv_malloc_func)(size_t\fI\ size\fP) +Replacement function for \fI\%malloc(3)\fP\&. +See \fI\%uv_replace_allocator()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void* (*uv_realloc_func)(void*\fI\ ptr\fP, size_t\fI\ size\fP) +Replacement function for \fI\%realloc(3)\fP\&. +See \fI\%uv_replace_allocator()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void* (*uv_calloc_func)(size_t\fI\ count\fP, size_t\fI\ size\fP) +Replacement function for \fI\%calloc(3)\fP\&. +See \fI\%uv_replace_allocator()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_free_func)(void*\fI\ ptr\fP) +Replacement function for \fI\%free(3)\fP\&. +See \fI\%uv_replace_allocator()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void (*uv_random_cb)(uv_random_t*\fI\ req\fP, int\fI\ status\fP, void*\fI\ buf\fP, size_t\fI\ buflen\fP) +Callback passed to \fI\%uv_random()\fP\&. \fIstatus\fP is non\-zero in case of +error. The \fIbuf\fP pointer is the same pointer that was passed to +\fI\%uv_random()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_file +Cross platform representation of a file handle. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_os_sock_t +Cross platform representation of a socket handle. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_os_fd_t +Abstract representation of a file descriptor. On Unix systems this is a +\fItypedef\fP of \fIint\fP and on Windows a \fIHANDLE\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B uv_pid_t +Cross platform representation of a \fIpid_t\fP\&. +.sp +New in version 1.16.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_timeval_t +Data type for storing times. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + long tv_sec; + long tv_usec; +} uv_timeval_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_timeval64_t +Alternative data type for storing times. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + int64_t tv_sec; + int32_t tv_usec; +} uv_timeval64_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_rusage_t +Data type for resource usage results. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + uv_timeval_t ru_utime; /* user CPU time used */ + uv_timeval_t ru_stime; /* system CPU time used */ + uint64_t ru_maxrss; /* maximum resident set size */ + uint64_t ru_ixrss; /* integral shared memory size (X) */ + uint64_t ru_idrss; /* integral unshared data size (X) */ + uint64_t ru_isrss; /* integral unshared stack size (X) */ + uint64_t ru_minflt; /* page reclaims (soft page faults) (X) */ + uint64_t ru_majflt; /* page faults (hard page faults) */ + uint64_t ru_nswap; /* swaps (X) */ + uint64_t ru_inblock; /* block input operations */ + uint64_t ru_oublock; /* block output operations */ + uint64_t ru_msgsnd; /* IPC messages sent (X) */ + uint64_t ru_msgrcv; /* IPC messages received (X) */ + uint64_t ru_nsignals; /* signals received (X) */ + uint64_t ru_nvcsw; /* voluntary context switches (X) */ + uint64_t ru_nivcsw; /* involuntary context switches (X) */ +} uv_rusage_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Members marked with \fI(X)\fP are unsupported on Windows. +See \fI\%getrusage(2)\fP for supported fields on Unix +.UNINDENT +.INDENT 0.0 +.TP +.B uv_cpu_info_t +Data type for CPU information. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_cpu_info_s { + char* model; + int speed; + struct uv_cpu_times_s { + uint64_t user; /* milliseconds */ + uint64_t nice; /* milliseconds */ + uint64_t sys; /* milliseconds */ + uint64_t idle; /* milliseconds */ + uint64_t irq; /* milliseconds */ + } cpu_times; +} uv_cpu_info_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_interface_address_t +Data type for interface addresses. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_interface_address_s { + char* name; + char phys_addr[6]; + int is_internal; + union { + struct sockaddr_in address4; + struct sockaddr_in6 address6; + } address; + union { + struct sockaddr_in netmask4; + struct sockaddr_in6 netmask6; + } netmask; +} uv_interface_address_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_passwd_t +Data type for password file information. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_passwd_s { + char* username; + long uid; + long gid; + char* shell; + char* homedir; +} uv_passwd_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_utsname_t +Data type for operating system name and version information. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_utsname_s { + char sysname[256]; + char release[256]; + char version[256]; + char machine[256]; +} uv_utsname_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_env_item_t +Data type for environment variable storage. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_env_item_s { + char* name; + char* value; +} uv_env_item_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_random_t +Random data request type. +.UNINDENT +.SS API +.INDENT 0.0 +.TP +.B uv_handle_type uv_guess_handle(uv_file\fI\ file\fP) +Used to detect what type of stream should be used with a given file +descriptor. Usually this will be used during initialization to guess the +type of the stdio streams. +.sp +For \fI\%isatty(3)\fP equivalent functionality use this function and test +for \fBUV_TTY\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_replace_allocator(uv_malloc_func\fI\ malloc_func\fP, uv_realloc_func\fI\ realloc_func\fP, uv_calloc_func\fI\ calloc_func\fP, uv_free_func\fI\ free_func\fP) +New in version 1.6.0. + +.sp +Override the use of the standard library\(aqs \fI\%malloc(3)\fP, +\fI\%calloc(3)\fP, \fI\%realloc(3)\fP, \fI\%free(3)\fP, memory allocation +functions. +.sp +This function must be called before any other libuv function is called or +after all resources have been freed and thus libuv doesn\(aqt reference +any allocated memory chunk. +.sp +On success, it returns 0, if any of the function pointers is NULL it +returns UV_EINVAL. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +There is no protection against changing the allocator multiple +times. If the user changes it they are responsible for making +sure the allocator is changed while no memory was allocated with +the previous allocator, or that they are compatible. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Allocator must be thread\-safe. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_library_shutdown(void); +New in version 1.38.0. + +.sp +Release any global state that libuv is holding onto. Libuv will normally +do so automatically when it is unloaded but it can be instructed to perform +cleanup manually. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Only call \fBuv_library_shutdown()\fP once. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Don\(aqt call \fBuv_library_shutdown()\fP when there are +still event loops or I/O requests active. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Don\(aqt call libuv functions after calling +\fBuv_library_shutdown()\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_buf_t uv_buf_init(char*\fI\ base\fP, unsigned int\fI\ len\fP) +Constructor for \fI\%uv_buf_t\fP\&. +.sp +Due to platform differences the user cannot rely on the ordering of the +\fIbase\fP and \fIlen\fP members of the uv_buf_t struct. The user is responsible for +freeing \fIbase\fP after the uv_buf_t is done. Return struct passed by value. +.UNINDENT +.INDENT 0.0 +.TP +.B char** uv_setup_args(int\fI\ argc\fP, char**\fI\ argv\fP) +Store the program arguments. Required for getting / setting the process title. +Libuv may take ownership of the memory that \fIargv\fP points to. This function +should be called exactly once, at program start\-up. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +argv = uv_setup_args(argc, argv); /* May return a copy of argv. */ +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_get_process_title(char*\fI\ buffer\fP, size_t\fI\ size\fP) +Gets the title of the current process. You \fImust\fP call \fIuv_setup_args\fP +before calling this function. If \fIbuffer\fP is \fINULL\fP or \fIsize\fP is zero, +\fIUV_EINVAL\fP is returned. If \fIsize\fP cannot accommodate the process title and +terminating \fINULL\fP character, the function returns \fIUV_ENOBUFS\fP\&. +.sp +Changed in version 1.18.1: now thread\-safe on all supported platforms. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_set_process_title(const char*\fI\ title\fP) +Sets the current process title. You \fImust\fP call \fIuv_setup_args\fP before +calling this function. On platforms with a fixed size buffer for the process +title the contents of \fItitle\fP will be copied to the buffer and truncated if +larger than the available space. Other platforms will return \fIUV_ENOMEM\fP if +they cannot allocate enough space to duplicate the contents of \fItitle\fP\&. +.sp +Changed in version 1.18.1: now thread\-safe on all supported platforms. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_resident_set_memory(size_t*\fI\ rss\fP) +Gets the resident set size (RSS) for the current process. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_uptime(double*\fI\ uptime\fP) +Gets the current system uptime. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_getrusage(uv_rusage_t*\fI\ rusage\fP) +Gets the resource usage measures for the current process. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows not all fields are set, the unsupported fields are filled with zeroes. +See \fI\%uv_rusage_t\fP for more details. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B uv_pid_t uv_os_getpid(void) +Returns the current process ID. +.sp +New in version 1.18.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uv_pid_t uv_os_getppid(void) +Returns the parent process ID. +.sp +New in version 1.16.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_cpu_info(uv_cpu_info_t**\fI\ cpu_infos\fP, int*\fI\ count\fP) +Gets information about the CPUs on the system. The \fIcpu_infos\fP array will +have \fIcount\fP elements and needs to be freed with \fI\%uv_free_cpu_info()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_free_cpu_info(uv_cpu_info_t*\fI\ cpu_infos\fP, int\fI\ count\fP) +Frees the \fIcpu_infos\fP array previously allocated with \fI\%uv_cpu_info()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_interface_addresses(uv_interface_address_t**\fI\ addresses\fP, int*\fI\ count\fP) +Gets address information about the network interfaces on the system. An +array of \fIcount\fP elements is allocated and returned in \fIaddresses\fP\&. It must +be freed by the user, calling \fI\%uv_free_interface_addresses()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_free_interface_addresses(uv_interface_address_t*\fI\ addresses\fP, int\fI\ count\fP) +Free an array of \fI\%uv_interface_address_t\fP which was returned by +\fI\%uv_interface_addresses()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_loadavg(double\fI\ avg[3]\fP) +Gets the load average. See: \fI\%https://en.wikipedia.org/wiki/Load_(computing)\fP +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Returns [0,0,0] on Windows (i.e., it\(aqs not implemented). +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_ip4_addr(const char*\fI\ ip\fP, int\fI\ port\fP, struct sockaddr_in*\fI\ addr\fP) +Convert a string containing an IPv4 addresses to a binary structure. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_ip6_addr(const char*\fI\ ip\fP, int\fI\ port\fP, struct sockaddr_in6*\fI\ addr\fP) +Convert a string containing an IPv6 addresses to a binary structure. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_ip4_name(const struct sockaddr_in*\fI\ src\fP, char*\fI\ dst\fP, size_t\fI\ size\fP) +Convert a binary structure containing an IPv4 address to a string. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_ip6_name(const struct sockaddr_in6*\fI\ src\fP, char*\fI\ dst\fP, size_t\fI\ size\fP) +Convert a binary structure containing an IPv6 address to a string. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_inet_ntop(int\fI\ af\fP, const void*\fI\ src\fP, char*\fI\ dst\fP, size_t\fI\ size\fP) +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_inet_pton(int\fI\ af\fP, const char*\fI\ src\fP, void*\fI\ dst\fP) +Cross\-platform IPv6\-capable implementation of \fI\%inet_ntop(3)\fP +and \fI\%inet_pton(3)\fP\&. On success they return 0. In case of error +the target \fIdst\fP pointer is unmodified. +.UNINDENT +.INDENT 0.0 +.TP +.B UV_IF_NAMESIZE +Maximum IPv6 interface identifier name length. Defined as +\fIIFNAMSIZ\fP on Unix and \fIIF_NAMESIZE\fP on Linux and Windows. +.sp +New in version 1.16.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_if_indextoname(unsigned int\fI\ ifindex\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +IPv6\-capable implementation of \fI\%if_indextoname(3)\fP\&. When called, +\fI*size\fP indicates the length of the \fIbuffer\fP, which is used to store the +result. +On success, zero is returned, \fIbuffer\fP contains the interface name, and +\fI*size\fP represents the string length of the \fIbuffer\fP, excluding the NUL +terminator byte from \fI*size\fP\&. On error, a negative result is +returned. If \fIbuffer\fP is not large enough to hold the result, +\fIUV_ENOBUFS\fP is returned, and \fI*size\fP represents the necessary size in +bytes, including the NUL terminator byte into the \fI*size\fP\&. +.sp +On Unix, the returned interface name can be used directly as an +interface identifier in scoped IPv6 addresses, e.g. +\fIfe80::abc:def1:2345%en0\fP\&. +.sp +On Windows, the returned interface cannot be used as an interface +identifier, as Windows uses numerical interface identifiers, e.g. +\fIfe80::abc:def1:2345%5\fP\&. +.sp +To get an interface identifier in a cross\-platform compatible way, +use \fIuv_if_indextoiid()\fP\&. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +char ifname[UV_IF_NAMESIZE]; +size_t size = sizeof(ifname); +uv_if_indextoname(sin6\->sin6_scope_id, ifname, &size); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 1.16.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_if_indextoiid(unsigned int\fI\ ifindex\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Retrieves a network interface identifier suitable for use in an IPv6 scoped +address. On Windows, returns the numeric \fIifindex\fP as a string. On all other +platforms, \fIuv_if_indextoname()\fP is called. The result is written to +\fIbuffer\fP, with \fI*size\fP indicating the length of \fIbuffer\fP\&. If \fIbuffer\fP is not +large enough to hold the result, then \fIUV_ENOBUFS\fP is returned, and \fI*size\fP +represents the size, including the NUL byte, required to hold the +result. +.sp +See \fIuv_if_indextoname\fP for further details. +.sp +New in version 1.16.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_exepath(char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Gets the executable path. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_cwd(char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Gets the current working directory, and stores it in \fIbuffer\fP\&. If the +current working directory is too large to fit in \fIbuffer\fP, this function +returns \fIUV_ENOBUFS\fP, and sets \fIsize\fP to the required length, including the +null terminator. +.sp +Changed in version 1.1.0: On Unix the path no longer ends in a slash. + +.sp +Changed in version 1.9.0: the returned length includes the terminating null +byte on \fIUV_ENOBUFS\fP, and the buffer is null terminated +on success. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_chdir(const char*\fI\ dir\fP) +Changes the current working directory. +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_homedir(char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Gets the current user\(aqs home directory. On Windows, \fIuv_os_homedir()\fP first +checks the \fIUSERPROFILE\fP environment variable using +\fIGetEnvironmentVariableW()\fP\&. If \fIUSERPROFILE\fP is not set, +\fIGetUserProfileDirectoryW()\fP is called. On all other operating systems, +\fIuv_os_homedir()\fP first checks the \fIHOME\fP environment variable using +\fI\%getenv(3)\fP\&. If \fIHOME\fP is not set, \fI\%getpwuid_r(3)\fP is called. The +user\(aqs home directory is stored in \fIbuffer\fP\&. When \fIuv_os_homedir()\fP is +called, \fIsize\fP indicates the maximum size of \fIbuffer\fP\&. On success \fIsize\fP is set +to the string length of \fIbuffer\fP\&. On \fIUV_ENOBUFS\fP failure \fIsize\fP is set to the +required length for \fIbuffer\fP, including the null byte. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIuv_os_homedir()\fP is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.6.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_tmpdir(char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Gets the temp directory. On Windows, \fIuv_os_tmpdir()\fP uses \fIGetTempPathW()\fP\&. +On all other operating systems, \fIuv_os_tmpdir()\fP uses the first environment +variable found in the ordered list \fITMPDIR\fP, \fITMP\fP, \fITEMP\fP, and \fITEMPDIR\fP\&. +If none of these are found, the path \fI"/tmp"\fP is used, or, on Android, +\fI"/data/local/tmp"\fP is used. The temp directory is stored in \fIbuffer\fP\&. When +\fIuv_os_tmpdir()\fP is called, \fIsize\fP indicates the maximum size of \fIbuffer\fP\&. +On success \fIsize\fP is set to the string length of \fIbuffer\fP (which does not +include the terminating null). On \fIUV_ENOBUFS\fP failure \fIsize\fP is set to the +required length for \fIbuffer\fP, including the null byte. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIuv_os_tmpdir()\fP is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.9.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_get_passwd(uv_passwd_t*\fI\ pwd\fP) +Gets a subset of the password file entry for the current effective uid (not +the real uid). The populated data includes the username, euid, gid, shell, +and home directory. On non\-Windows systems, all data comes from +\fI\%getpwuid_r(3)\fP\&. On Windows, uid and gid are set to \-1 and have no +meaning, and shell is \fINULL\fP\&. After successfully calling this function, the +memory allocated to \fIpwd\fP needs to be freed with +\fI\%uv_os_free_passwd()\fP\&. +.sp +New in version 1.9.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_os_free_passwd(uv_passwd_t*\fI\ pwd\fP) +Frees the \fIpwd\fP memory previously allocated with \fI\%uv_os_get_passwd()\fP\&. +.sp +New in version 1.9.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_get_free_memory(void) +Gets memory information (in bytes). +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_get_total_memory(void) +Gets memory information (in bytes). +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_get_constrained_memory(void) +Gets the amount of memory available to the process (in bytes) based on +limits imposed by the OS. If there is no such constraint, or the constraint +is unknown, \fI0\fP is returned. Note that it is not unusual for this value to +be less than or greater than \fI\%uv_get_total_memory()\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function currently only returns a non\-zero value on Linux, based +on cgroups if it is present. +.UNINDENT +.UNINDENT +.sp +New in version 1.29.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B uint64_t uv_hrtime(void) +Returns the current high\-resolution real time. This is expressed in +nanoseconds. It is relative to an arbitrary time in the past. It is not +related to the time of day and therefore not subject to clock drift. The +primary use is for measuring performance between intervals. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Not every platform can support nanosecond resolution; however, this value will always +be in nanoseconds. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_print_all_handles(uv_loop_t*\fI\ loop\fP, FILE*\fI\ stream\fP) +Prints all handles associated with the given \fIloop\fP to the given \fIstream\fP\&. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_print_all_handles(uv_default_loop(), stderr); +/* +[\-\-I] signal 0x1a25ea8 +[\-AI] async 0x1a25cf0 +[R\-\-] idle 0x1a7a8c8 +*/ +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The format is \fI[flags] handle\-type handle\-address\fP\&. For \fIflags\fP: +.INDENT 7.0 +.IP \(bu 2 +\fIR\fP is printed for a handle that is referenced +.IP \(bu 2 +\fIA\fP is printed for a handle that is active +.IP \(bu 2 +\fII\fP is printed for a handle that is internal +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is meant for ad hoc debugging, there is no API/ABI +stability guarantees. +.UNINDENT +.UNINDENT +.sp +New in version 1.8.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_print_active_handles(uv_loop_t*\fI\ loop\fP, FILE*\fI\ stream\fP) +This is the same as \fI\%uv_print_all_handles()\fP except only active handles +are printed. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is meant for ad hoc debugging, there is no API/ABI +stability guarantees. +.UNINDENT +.UNINDENT +.sp +New in version 1.8.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_environ(uv_env_item_t**\fI\ envitems\fP, int*\fI\ count\fP) +Retrieves all environment variables. This function will allocate memory +which must be freed by calling \fBuv_os_free_environ()\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.31.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_os_free_environ(uv_env_item_t* envitems, int count); +Frees the memory allocated for the environment variables by +\fI\%uv_os_environ()\fP\&. +.sp +New in version 1.31.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_getenv(const char*\fI\ name\fP, char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Retrieves the environment variable specified by \fIname\fP, copies its value +into \fIbuffer\fP, and sets \fIsize\fP to the string length of the value. When +calling this function, \fIsize\fP must be set to the amount of storage available +in \fIbuffer\fP, including the null terminator. If the environment variable +exceeds the storage available in \fIbuffer\fP, \fIUV_ENOBUFS\fP is returned, and +\fIsize\fP is set to the amount of storage required to hold the value. If no +matching environment variable exists, \fIUV_ENOENT\fP is returned. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.12.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_setenv(const char*\fI\ name\fP, const char*\fI\ value\fP) +Creates or updates the environment variable specified by \fIname\fP with +\fIvalue\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.12.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_unsetenv(const char*\fI\ name\fP) +Deletes the environment variable specified by \fIname\fP\&. If no such environment +variable exists, this function returns successfully. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This function is not thread safe. +.UNINDENT +.UNINDENT +.sp +New in version 1.12.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_gethostname(char*\fI\ buffer\fP, size_t*\fI\ size\fP) +Returns the hostname as a null\-terminated string in \fIbuffer\fP, and sets +\fIsize\fP to the string length of the hostname. When calling this function, +\fIsize\fP must be set to the amount of storage available in \fIbuffer\fP, including +the null terminator. If the hostname exceeds the storage available in +\fIbuffer\fP, \fIUV_ENOBUFS\fP is returned, and \fIsize\fP is set to the amount of +storage required to hold the value. +.sp +New in version 1.12.0. + +.sp +Changed in version 1.26.0: \fIUV_MAXHOSTNAMESIZE\fP is available and represents +the maximum \fIbuffer\fP size required to store a +hostname and terminating \fInul\fP character. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_getpriority(uv_pid_t\fI\ pid\fP, int*\fI\ priority\fP) +Retrieves the scheduling priority of the process specified by \fIpid\fP\&. The +returned value of \fIpriority\fP is between \-20 (high priority) and 19 (low +priority). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows, the returned priority will equal one of the \fIUV_PRIORITY\fP +constants. +.UNINDENT +.UNINDENT +.sp +New in version 1.23.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_setpriority(uv_pid_t\fI\ pid\fP, int\fI\ priority\fP) +Sets the scheduling priority of the process specified by \fIpid\fP\&. The +\fIpriority\fP value range is between \-20 (high priority) and 19 (low priority). +The constants \fIUV_PRIORITY_LOW\fP, \fIUV_PRIORITY_BELOW_NORMAL\fP, +\fIUV_PRIORITY_NORMAL\fP, \fIUV_PRIORITY_ABOVE_NORMAL\fP, \fIUV_PRIORITY_HIGH\fP, and +\fIUV_PRIORITY_HIGHEST\fP are also provided for convenience. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows, this function utilizes \fISetPriorityClass()\fP\&. The \fIpriority\fP +argument is mapped to a Windows priority class. When retrieving the +process priority, the result will equal one of the \fIUV_PRIORITY\fP +constants, and not necessarily the exact value of \fIpriority\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On Windows, setting \fIPRIORITY_HIGHEST\fP will only work for elevated user, +for others it will be silently reduced to \fIPRIORITY_HIGH\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On IBM i PASE, the highest process priority is \-10. The constant +\fIUV_PRIORITY_HIGHEST\fP is \-10, \fIUV_PRIORITY_HIGH\fP is \-7, +\fIUV_PRIORITY_ABOVE_NORMAL\fP is \-4, \fIUV_PRIORITY_NORMAL\fP is 0, +\fIUV_PRIORITY_BELOW_NORMAL\fP is 15 and \fIUV_PRIORITY_LOW\fP is 39. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On IBM i PASE, you are not allowed to change your priority unless you +have the *JOBCTL special authority (even to lower it). +.UNINDENT +.UNINDENT +.sp +New in version 1.23.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_os_uname(uv_utsname_t*\fI\ buffer\fP) +Retrieves system information in \fIbuffer\fP\&. The populated data includes the +operating system name, release, version, and machine. On non\-Windows +systems, \fIuv_os_uname()\fP is a thin wrapper around \fI\%uname(2)\fP\&. Returns +zero on success, and a non\-zero error value otherwise. +.sp +New in version 1.25.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_gettimeofday(uv_timeval64_t*\fI\ tv\fP) +Cross\-platform implementation of \fI\%gettimeofday(2)\fP\&. The timezone +argument to \fIgettimeofday()\fP is not supported, as it is considered obsolete. +.sp +New in version 1.28.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B int uv_random(uv_loop_t*\fI\ loop\fP, uv_random_t*\fI\ req\fP, void*\fI\ buf\fP, size_t\fI\ buflen\fP, unsigned int\fI\ flags\fP, uv_random_cb\fI\ cb\fP) +Fill \fIbuf\fP with exactly \fIbuflen\fP cryptographically strong random bytes +acquired from the system CSPRNG. \fIflags\fP is reserved for future extension +and must currently be 0. +.sp +Short reads are not possible. When less than \fIbuflen\fP random bytes are +available, a non\-zero error value is returned or passed to the callback. +.sp +The synchronous version may block indefinitely when not enough entropy +is available. The asynchronous version may not ever finish when the system +is low on entropy. +.sp +Sources of entropy: +.INDENT 7.0 +.IP \(bu 2 +Windows: \fIRtlGenRandom _\fP\&. +.IP \(bu 2 +Linux, Android: \fI\%getrandom(2)\fP if available, or \fI\%urandom(4)\fP +after reading from \fI/dev/random\fP once, or the \fIKERN_RANDOM\fP +\fI\%sysctl(2)\fP\&. +.IP \(bu 2 +FreeBSD: \fIgetrandom(2) _\fP, +or \fI/dev/urandom\fP after reading from \fI/dev/random\fP once. +.IP \(bu 2 +NetBSD: \fIKERN_ARND\fP \fIsysctl(3) _\fP +.IP \(bu 2 +macOS, OpenBSD: \fIgetentropy(2) _\fP +if available, or \fI/dev/urandom\fP after reading from \fI/dev/random\fP once. +.IP \(bu 2 +AIX: \fI/dev/random\fP\&. +.IP \(bu 2 +IBM i: \fI/dev/urandom\fP\&. +.IP \(bu 2 +Other UNIX: \fI/dev/urandom\fP after reading from \fI/dev/random\fP once. +.UNINDENT +.INDENT 7.0 +.TP +.B Returns +0 on success, or an error code < 0 on failure. The contents of +\fIbuf\fP is undefined after an error. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using the synchronous version, both \fIloop\fP and \fIreq\fP parameters +are not used and can be set to \fINULL\fP\&. +.UNINDENT +.UNINDENT +.sp +New in version 1.33.0. + +.UNINDENT +.INDENT 0.0 +.TP +.B void uv_sleep(unsigned int\fI\ msec\fP) +Causes the calling thread to sleep for \fImsec\fP milliseconds. +.sp +New in version 1.34.0. + +.UNINDENT +.SS User guide +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The contents of this guide have been recently incorporated into the libuv documentation +and it hasn\(aqt gone through thorough review yet. If you spot a mistake please file an +issue, or better yet, open a pull request! +.UNINDENT +.UNINDENT +.SS Introduction +.sp +This \(aqbook\(aq is a small set of tutorials about using \fI\%libuv\fP as +a high performance evented I/O library which offers the same API on Windows and Unix. +.sp +It is meant to cover the main areas of libuv, but is not a comprehensive +reference discussing every function and data structure. The \fI\%official libuv +documentation\fP may be consulted for full details. +.sp +This book is still a work in progress, so sections may be incomplete, but +I hope you will enjoy it as it grows. +.SS Who this book is for +.sp +If you are reading this book, you are either: +.INDENT 0.0 +.IP 1. 3 +a systems programmer, creating low\-level programs such as daemons or network +services and clients. You have found that the event loop approach is well +suited for your application and decided to use libuv. +.IP 2. 3 +a node.js module writer, who wants to wrap platform APIs +written in C or C++ with a set of (a)synchronous APIs that are exposed to +JavaScript. You will use libuv purely in the context of node.js. For +this you will require some other resources as the book does not cover parts +specific to v8/node.js. +.UNINDENT +.sp +This book assumes that you are comfortable with the C programming language. +.SS Background +.sp +The \fI\%node.js\fP project began in 2009 as a JavaScript environment decoupled +from the browser. Using Google\(aqs \fI\%V8\fP and Marc Lehmann\(aqs \fI\%libev\fP, node.js +combined a model of I/O \-\- evented \-\- with a language that was well suited to +the style of programming; due to the way it had been shaped by browsers. As +node.js grew in popularity, it was important to make it work on Windows, but +libev ran only on Unix. The Windows equivalent of kernel event notification +mechanisms like kqueue or (e)poll is IOCP. libuv was an abstraction around libev +or IOCP depending on the platform, providing users an API based on libev. +In the node\-v0.9.0 version of libuv \fI\%libev was removed\fP\&. +.sp +Since then libuv has continued to mature and become a high quality standalone +library for system programming. Users outside of node.js include Mozilla\(aqs +\fI\%Rust\fP programming language, and a \fI\%variety\fP of language bindings. +.sp +This book and the code is based on libuv version \fI\%v1.3.0\fP\&. +.SS Code +.sp +All the code from this book is included as part of the source of the book on +Github. \fI\%Clone\fP/\fI\%Download\fP the book, then build libuv: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cd libuv +\&./autogen.sh +\&./configure +make +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +There is no need to \fBmake install\fP\&. To build the examples run \fBmake\fP in the +\fBcode/\fP directory. +.SS Basics of libuv +.sp +libuv enforces an \fBasynchronous\fP, \fBevent\-driven\fP style of programming. Its +core job is to provide an event loop and callback based notifications of I/O +and other activities. libuv offers core utilities like timers, non\-blocking +networking support, asynchronous file system access, child processes and more. +.SS Event loops +.sp +In event\-driven programming, an application expresses interest in certain events +and respond to them when they occur. The responsibility of gathering events +from the operating system or monitoring other sources of events is handled by +libuv, and the user can register callbacks to be invoked when an event occurs. +The event\-loop usually keeps running \fIforever\fP\&. In pseudocode: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +while there are still events to process: + e = get the next event + if there is a callback associated with e: + call the callback +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Some examples of events are: +.INDENT 0.0 +.IP \(bu 2 +File is ready for writing +.IP \(bu 2 +A socket has data ready to be read +.IP \(bu 2 +A timer has timed out +.UNINDENT +.sp +This event loop is encapsulated by \fBuv_run()\fP \-\- the end\-all function when using +libuv. +.sp +The most common activity of systems programs is to deal with input and output, +rather than a lot of number\-crunching. The problem with using conventional +input/output functions (\fBread\fP, \fBfprintf\fP, etc.) is that they are +\fBblocking\fP\&. The actual write to a hard disk or reading from a network, takes +a disproportionately long time compared to the speed of the processor. The +functions don\(aqt return until the task is done, so that your program is doing +nothing. For programs which require high performance this is a major roadblock +as other activities and other I/O operations are kept waiting. +.sp +One of the standard solutions is to use threads. Each blocking I/O operation is +started in a separate thread (or in a thread pool). When the blocking function +gets invoked in the thread, the processor can schedule another thread to run, +which actually needs the CPU. +.sp +The approach followed by libuv uses another style, which is the \fBasynchronous, +non\-blocking\fP style. Most modern operating systems provide event notification +subsystems. For example, a normal \fBread\fP call on a socket would block until +the sender actually sent something. Instead, the application can request the +operating system to watch the socket and put an event notification in the +queue. The application can inspect the events at its convenience (perhaps doing +some number crunching before to use the processor to the maximum) and grab the +data. It is \fBasynchronous\fP because the application expressed interest at one +point, then used the data at another point (in time and space). It is +\fBnon\-blocking\fP because the application process was free to do other tasks. +This fits in well with libuv\(aqs event\-loop approach, since the operating system +events can be treated as just another libuv event. The non\-blocking ensures +that other events can continue to be handled as fast as they come in [1]\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +How the I/O is run in the background is not of our concern, but due to the +way our computer hardware works, with the thread as the basic unit of the +processor, libuv and OSes will usually run background/worker threads and/or +polling to perform tasks in a non\-blocking manner. +.UNINDENT +.UNINDENT +.sp +Bert Belder, one of the libuv core developers has a small video explaining the +architecture of libuv and its background. If you have no prior experience with +either libuv or libev, it is a quick, useful watch. +.sp +libuv\(aqs event loop is explained in more detail in the \fI\%documentation\fP\&. +.SS Hello World +.sp +With the basics out of the way, let\(aqs write our first libuv program. It does +nothing, except start a loop which will exit immediately. +.sp +helloworld/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include +#include + +int main() { + uv_loop_t *loop = malloc(sizeof(uv_loop_t)); + uv_loop_init(loop); + + printf("Now quitting.\en"); + uv_run(loop, UV_RUN_DEFAULT); + + uv_loop_close(loop); + free(loop); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This program quits immediately because it has no events to process. A libuv +event loop has to be told to watch out for events using the various API +functions. +.sp +Starting with libuv v1.0, users should allocate the memory for the loops before +initializing it with \fBuv_loop_init(uv_loop_t *)\fP\&. This allows you to plug in +custom memory management. Remember to de\-initialize the loop using +\fBuv_loop_close(uv_loop_t *)\fP and then delete the storage. The examples never +close loops since the program quits after the loop ends and the system will +reclaim memory. Production grade projects, especially long running systems +programs, should take care to release correctly. +.SS Default loop +.sp +A default loop is provided by libuv and can be accessed using +\fBuv_default_loop()\fP\&. You should use this loop if you only want a single +loop. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +node.js uses the default loop as its main loop. If you are writing bindings +you should be aware of this. +.UNINDENT +.UNINDENT +.SS Error handling +.sp +Initialization functions or synchronous functions which may fail return a negative number on error. Async functions that may fail will pass a status parameter to their callbacks. The error messages are defined as \fBUV_E*\fP \fI\%constants\fP\&. +.sp +You can use the \fBuv_strerror(int)\fP and \fBuv_err_name(int)\fP functions +to get a \fBconst char *\fP describing the error or the error name respectively. +.sp +I/O read callbacks (such as for files and sockets) are passed a parameter \fBnread\fP\&. If \fBnread\fP is less than 0, there was an error (UV_EOF is the end of file error, which you may want to handle differently). +.SS Handles and Requests +.sp +libuv works by the user expressing interest in particular events. This is +usually done by creating a \fBhandle\fP to an I/O device, timer or process. +Handles are opaque structs named as \fBuv_TYPE_t\fP where type signifies what the +handle is used for. +.sp +libuv watchers +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +/* Handle types. */ +typedef struct uv_loop_s uv_loop_t; +typedef struct uv_handle_s uv_handle_t; +typedef struct uv_dir_s uv_dir_t; +typedef struct uv_stream_s uv_stream_t; +typedef struct uv_tcp_s uv_tcp_t; +typedef struct uv_udp_s uv_udp_t; +typedef struct uv_pipe_s uv_pipe_t; +typedef struct uv_tty_s uv_tty_t; +typedef struct uv_poll_s uv_poll_t; +typedef struct uv_timer_s uv_timer_t; +typedef struct uv_prepare_s uv_prepare_t; +typedef struct uv_check_s uv_check_t; +typedef struct uv_idle_s uv_idle_t; +typedef struct uv_async_s uv_async_t; +typedef struct uv_process_s uv_process_t; +typedef struct uv_fs_event_s uv_fs_event_t; +typedef struct uv_fs_poll_s uv_fs_poll_t; +typedef struct uv_signal_s uv_signal_t; + +/* Request types. */ +typedef struct uv_req_s uv_req_t; +typedef struct uv_getaddrinfo_s uv_getaddrinfo_t; +typedef struct uv_getnameinfo_s uv_getnameinfo_t; +typedef struct uv_shutdown_s uv_shutdown_t; +typedef struct uv_write_s uv_write_t; +typedef struct uv_connect_s uv_connect_t; +typedef struct uv_udp_send_s uv_udp_send_t; +typedef struct uv_fs_s uv_fs_t; +typedef struct uv_work_s uv_work_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Handles represent long\-lived objects. Async operations on such handles are +identified using \fBrequests\fP\&. A request is short\-lived (usually used across +only one callback) and usually indicates one I/O operation on a handle. +Requests are used to preserve context between the initiation and the callback +of individual actions. For example, an UDP socket is represented by +a \fBuv_udp_t\fP, while individual writes to the socket use a \fBuv_udp_send_t\fP +structure that is passed to the callback after the write is done. +.sp +Handles are setup by a corresponding: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_TYPE_init(uv_loop_t *, uv_TYPE_t *) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +function. +.sp +Callbacks are functions which are called by libuv whenever an event the watcher +is interested in has taken place. Application specific logic will usually be +implemented in the callback. For example, an IO watcher\(aqs callback will receive +the data read from a file, a timer callback will be triggered on timeout and so +on. +.SS Idling +.sp +Here is an example of using an idle handle. The callback is called once on +every turn of the event loop. A use case for idle handles is discussed in +utilities\&. Let us use an idle watcher to look at the watcher life cycle +and see how \fBuv_run()\fP will now block because a watcher is present. The idle +watcher is stopped when the count is reached and \fBuv_run()\fP exits since no +event watchers are active. +.sp +idle\-basic/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include + +int64_t counter = 0; + +void wait_for_a_while(uv_idle_t* handle) { + counter++; + + if (counter >= 10e6) + uv_idle_stop(handle); +} + +int main() { + uv_idle_t idler; + + uv_idle_init(uv_default_loop(), &idler); + uv_idle_start(&idler, wait_for_a_while); + + printf("Idling...\en"); + uv_run(uv_default_loop(), UV_RUN_DEFAULT); + + uv_loop_close(uv_default_loop()); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Storing context +.sp +In callback based programming style you\(aqll often want to pass some \(aqcontext\(aq \-\- +application specific information \-\- between the call site and the callback. All +handles and requests have a \fBvoid* data\fP member which you can set to the +context and cast back in the callback. This is a common pattern used throughout +the C library ecosystem. In addition \fBuv_loop_t\fP also has a similar data +member. + +.sp +.ce +---- + +.ce 0 +.sp +.IP [1] 5 +Depending on the capacity of the hardware of course. +.SS Filesystem +.sp +Simple filesystem read/write is achieved using the \fBuv_fs_*\fP functions and the +\fBuv_fs_t\fP struct. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The libuv filesystem operations are different from socket operations\&. Socket operations use the non\-blocking operations provided +by the operating system. Filesystem operations use blocking functions +internally, but invoke these functions in a \fI\%thread pool\fP and notify +watchers registered with the event loop when application interaction is +required. +.UNINDENT +.UNINDENT +.sp +All filesystem functions have two forms \- \fIsynchronous\fP and \fIasynchronous\fP\&. +.sp +The \fIsynchronous\fP forms automatically get called (and \fBblock\fP) if the +callback is null. The return value of functions is a libuv error code\&. This is usually only useful for synchronous calls. +The \fIasynchronous\fP form is called when a callback is passed and the return +value is 0. +.SS Reading/Writing files +.sp +A file descriptor is obtained using +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBflags\fP and \fBmode\fP are standard +\fI\%Unix flags\fP\&. +libuv takes care of converting to the appropriate Windows flags. +.sp +File descriptors are closed using +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Filesystem operation callbacks have the signature: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void callback(uv_fs_t* req); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Let\(aqs see a simple implementation of \fBcat\fP\&. We start with registering +a callback for when the file is opened: +.sp +uvcat/main.c \- opening a file +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_open(uv_fs_t *req) { + // The request passed to the callback is the same as the one the call setup + // function was passed. + assert(req == &open_req); + if (req\->result >= 0) { + iov = uv_buf_init(buffer, sizeof(buffer)); + uv_fs_read(uv_default_loop(), &read_req, req\->result, + &iov, 1, \-1, on_read); + } + else { + fprintf(stderr, "error opening file: %s\en", uv_strerror((int)req\->result)); + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBresult\fP field of a \fBuv_fs_t\fP is the file descriptor in case of the +\fBuv_fs_open\fP callback. If the file is successfully opened, we start reading it. +.sp +uvcat/main.c \- read callback +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_fs_t *req) { + if (req\->result < 0) { + fprintf(stderr, "Read error: %s\en", uv_strerror(req\->result)); + } + else if (req\->result == 0) { + uv_fs_t close_req; + // synchronous + uv_fs_close(uv_default_loop(), &close_req, open_req.result, NULL); + } + else if (req\->result > 0) { + iov.len = req\->result; + uv_fs_write(uv_default_loop(), &write_req, 1, &iov, 1, \-1, on_write); + } +} + + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In the case of a read call, you should pass an \fIinitialized\fP buffer which will +be filled with data before the read callback is triggered. The \fBuv_fs_*\fP +operations map almost directly to certain POSIX functions, so EOF is indicated +in this case by \fBresult\fP being 0. In the case of streams or pipes, the +\fBUV_EOF\fP constant would have been passed as a status instead. +.sp +Here you see a common pattern when writing asynchronous programs. The +\fBuv_fs_close()\fP call is performed synchronously. \fIUsually tasks which are +one\-off, or are done as part of the startup or shutdown stage are performed +synchronously, since we are interested in fast I/O when the program is going +about its primary task and dealing with multiple I/O sources\fP\&. For solo tasks +the performance difference usually is negligible and may lead to simpler code. +.sp +Filesystem writing is similarly simple using \fBuv_fs_write()\fP\&. \fIYour callback +will be triggered after the write is complete\fP\&. In our case the callback +simply drives the next read. Thus read and write proceed in lockstep via +callbacks. +.sp +uvcat/main.c \- write callback +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void on_write(uv_fs_t *req) { + if (req\->result < 0) { + fprintf(stderr, "Write error: %s\en", uv_strerror((int)req\->result)); + } + else { + uv_fs_read(uv_default_loop(), &read_req, open_req.result, &iov, 1, \-1, on_read); + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Due to the way filesystems and disk drives are configured for performance, +a write that \(aqsucceeds\(aq may not be committed to disk yet. +.UNINDENT +.UNINDENT +.sp +We set the dominos rolling in \fBmain()\fP: +.sp +uvcat/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main(int argc, char **argv) { + uv_fs_open(uv_default_loop(), &open_req, argv[1], O_RDONLY, 0, on_open); + uv_run(uv_default_loop(), UV_RUN_DEFAULT); + + uv_fs_req_cleanup(&open_req); + uv_fs_req_cleanup(&read_req); + uv_fs_req_cleanup(&write_req); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuv_fs_req_cleanup()\fP function must always be called on filesystem +requests to free internal memory allocations in libuv. +.UNINDENT +.UNINDENT +.SS Filesystem operations +.sp +All the standard filesystem operations like \fBunlink\fP, \fBrmdir\fP, \fBstat\fP are +supported asynchronously and have intuitive argument order. They follow the +same patterns as the read/write/open calls, returning the result in the +\fBuv_fs_t.result\fP field. The full list: +.sp +Filesystem operations +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb); +int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb); +int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb); +int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb); +int uv_fs_copyfile(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb); +int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb); +int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb); +int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb); +int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent); +int uv_fs_opendir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb); +int uv_fs_closedir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb); +int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb); +int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb); +int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb); +int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb); +int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb); +int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb); +int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb); +int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb); +int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb); +int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb); +int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb); +int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb); +int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb); +int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb); +int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb); +int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb); +int uv_fs_lchown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb); +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Buffers and Streams +.sp +The basic I/O handle in libuv is the stream (\fBuv_stream_t\fP). TCP sockets, UDP +sockets, and pipes for file I/O and IPC are all treated as stream subclasses. +.sp +Streams are initialized using custom functions for each subclass, then operated +upon using +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_read_start(uv_stream_t*, uv_alloc_cb alloc_cb, uv_read_cb read_cb); +int uv_read_stop(uv_stream_t*); +int uv_write(uv_write_t* req, uv_stream_t* handle, + const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The stream based functions are simpler to use than the filesystem ones and +libuv will automatically keep reading from a stream when \fBuv_read_start()\fP is +called once, until \fBuv_read_stop()\fP is called. +.sp +The discrete unit of data is the buffer \-\- \fBuv_buf_t\fP\&. This is simply +a collection of a pointer to bytes (\fBuv_buf_t.base\fP) and the length +(\fBuv_buf_t.len\fP). The \fBuv_buf_t\fP is lightweight and passed around by value. +What does require management is the actual bytes, which have to be allocated +and freed by the application. +.sp +\fBERROR:\fP +.INDENT 0.0 +.INDENT 3.5 +THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER** +.UNINDENT +.UNINDENT +.sp +To demonstrate streams we will need to use \fBuv_pipe_t\fP\&. This allows streaming +local files [2]\&. Here is a simple tee utility using libuv. Doing all operations +asynchronously shows the power of evented I/O. The two writes won\(aqt block each +other, but we have to be careful to copy over the buffer data to ensure we don\(aqt +free a buffer until it has been written. +.sp +The program is to be executed as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\&./uvtee +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We start off opening pipes on the files we require. libuv pipes to a file are +opened as bidirectional by default. +.sp +uvtee/main.c \- read on pipes +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +int main(int argc, char **argv) { + loop = uv_default_loop(); + + uv_pipe_init(loop, &stdin_pipe, 0); + uv_pipe_open(&stdin_pipe, 0); + + uv_pipe_init(loop, &stdout_pipe, 0); + uv_pipe_open(&stdout_pipe, 1); + + uv_fs_t file_req; + int fd = uv_fs_open(loop, &file_req, argv[1], O_CREAT | O_RDWR, 0644, NULL); + uv_pipe_init(loop, &file_pipe, 0); + uv_pipe_open(&file_pipe, fd); + + uv_read_start((uv_stream_t*)&stdin_pipe, alloc_buffer, read_stdin); + + uv_run(loop, UV_RUN_DEFAULT); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The third argument of \fBuv_pipe_init()\fP should be set to 1 for IPC using named +pipes. This is covered in processes\&. The \fBuv_pipe_open()\fP call +associates the pipe with the file descriptor, in this case \fB0\fP (standard +input). +.sp +We start monitoring \fBstdin\fP\&. The \fBalloc_buffer\fP callback is invoked as new +buffers are required to hold incoming data. \fBread_stdin\fP will be called with +these buffers. +.sp +uvtee/main.c \- reading buffers +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void alloc_buffer(uv_handle_t *handle, size_t suggested_size, uv_buf_t *buf) { + *buf = uv_buf_init((char*) malloc(suggested_size), suggested_size); +} + +void read_stdin(uv_stream_t *stream, ssize_t nread, const uv_buf_t *buf) { + if (nread < 0){ + if (nread == UV_EOF){ + // end of file + uv_close((uv_handle_t *)&stdin_pipe, NULL); + uv_close((uv_handle_t *)&stdout_pipe, NULL); + uv_close((uv_handle_t *)&file_pipe, NULL); + } + } else if (nread > 0) { + write_data((uv_stream_t *)&stdout_pipe, nread, *buf, on_stdout_write); + write_data((uv_stream_t *)&file_pipe, nread, *buf, on_file_write); + } + + // OK to free buffer as write_data copies it. + if (buf\->base) + free(buf\->base); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The standard \fBmalloc\fP is sufficient here, but you can use any memory allocation +scheme. For example, node.js uses its own slab allocator which associates +buffers with V8 objects. +.sp +The read callback \fBnread\fP parameter is less than 0 on any error. This error +might be EOF, in which case we close all the streams, using the generic close +function \fBuv_close()\fP which deals with the handle based on its internal type. +Otherwise \fBnread\fP is a non\-negative number and we can attempt to write that +many bytes to the output streams. Finally remember that buffer allocation and +deallocation is application responsibility, so we free the data. +.sp +The allocation callback may return a buffer with length zero if it fails to +allocate memory. In this case, the read callback is invoked with error +UV_ENOBUFS. libuv will continue to attempt to read the stream though, so you +must explicitly call \fBuv_close()\fP if you want to stop when allocation fails. +.sp +The read callback may be called with \fBnread = 0\fP, indicating that at this +point there is nothing to be read. Most applications will just ignore this. +.sp +uvtee/main.c \- Write to pipe +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct { + uv_write_t req; + uv_buf_t buf; +} write_req_t; + +void free_write_req(uv_write_t *req) { + write_req_t *wr = (write_req_t*) req; + free(wr\->buf.base); + free(wr); +} + +void on_stdout_write(uv_write_t *req, int status) { + free_write_req(req); +} + +void on_file_write(uv_write_t *req, int status) { + free_write_req(req); +} + +void write_data(uv_stream_t *dest, size_t size, uv_buf_t buf, uv_write_cb cb) { + write_req_t *req = (write_req_t*) malloc(sizeof(write_req_t)); + req\->buf = uv_buf_init((char*) malloc(size), size); + memcpy(req\->buf.base, buf.base, size); + uv_write((uv_write_t*) req, (uv_stream_t*)dest, &req\->buf, 1, cb); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBwrite_data()\fP makes a copy of the buffer obtained from read. This buffer +does not get passed through to the write callback trigged on write completion. To +get around this we wrap a write request and a buffer in \fBwrite_req_t\fP and +unwrap it in the callbacks. We make a copy so we can free the two buffers from +the two calls to \fBwrite_data\fP independently of each other. While acceptable +for a demo program like this, you\(aqll probably want smarter memory management, +like reference counted buffers or a pool of buffers in any major application. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If your program is meant to be used with other programs it may knowingly or +unknowingly be writing to a pipe. This makes it susceptible to \fI\%aborting on +receiving a SIGPIPE\fP\&. It is a good idea to insert: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +signal(SIGPIPE, SIG_IGN) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +in the initialization stages of your application. +.UNINDENT +.UNINDENT +.SS File change events +.sp +All modern operating systems provide APIs to put watches on individual files or +directories and be informed when the files are modified. libuv wraps common +file change notification libraries [1]\&. This is one of the more +inconsistent parts of libuv. File change notification systems are themselves +extremely varied across platforms so getting everything working everywhere is +difficult. To demonstrate, I\(aqm going to build a simple utility which runs +a command whenever any of the watched files change: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\&./onchange [file2] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The file change notification is started using \fBuv_fs_event_init()\fP: +.sp +onchange/main.c \- The setup +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main(int argc, char **argv) { + if (argc <= 2) { + fprintf(stderr, "Usage: %s [file2 ...]\en", argv[0]); + return 1; + } + + loop = uv_default_loop(); + command = argv[1]; + + while (argc\-\- > 2) { + fprintf(stderr, "Adding watch on %s\en", argv[argc]); + uv_fs_event_t *fs_event_req = malloc(sizeof(uv_fs_event_t)); + uv_fs_event_init(loop, fs_event_req); + // The recursive flag watches subdirectories too. + uv_fs_event_start(fs_event_req, run_command, argv[argc], UV_FS_EVENT_RECURSIVE); + } + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The third argument is the actual file or directory to monitor. The last +argument, \fBflags\fP, can be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +/* +* Flags to be passed to uv_fs_event_start(). +*/ +enum uv_fs_event_flags { + UV_FS_EVENT_WATCH_ENTRY = 1, + UV_FS_EVENT_STAT = 2, + UV_FS_EVENT_RECURSIVE = 4 +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBUV_FS_EVENT_WATCH_ENTRY\fP and \fBUV_FS_EVENT_STAT\fP don\(aqt do anything (yet). +\fBUV_FS_EVENT_RECURSIVE\fP will start watching subdirectories as well on +supported platforms. +.sp +The callback will receive the following arguments: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +\fBuv_fs_event_t *handle\fP \- The handle. The \fBpath\fP field of the handle +is the file on which the watch was set. +.IP 2. 3 +\fBconst char *filename\fP \- If a directory is being monitored, this is the +file which was changed. Only non\-\fBnull\fP on Linux and Windows. May be \fBnull\fP +even on those platforms. +.IP 3. 3 +.INDENT 3.0 +.TP +.B \fBint flags\fP \- one of \fBUV_RENAME\fP or \fBUV_CHANGE\fP, or a bitwise OR of +both. +.UNINDENT +.IP 4. 3 +\fBint status\fP \- Currently 0. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +In our example we simply print the arguments and run the command using +\fBsystem()\fP\&. +.sp +onchange/main.c \- file change notification callback +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void run_command(uv_fs_event_t *handle, const char *filename, int events, int status) { + char path[1024]; + size_t size = 1023; + // Does not handle error if path is longer than 1023. + uv_fs_event_getpath(handle, path, &size); + path[size] = \(aq\e0\(aq; + + fprintf(stderr, "Change detected in %s: ", path); + if (events & UV_RENAME) + fprintf(stderr, "renamed"); + if (events & UV_CHANGE) + fprintf(stderr, "changed"); + + fprintf(stderr, " %s\en", filename ? filename : ""); + system(command); +} + +.ft P +.fi +.UNINDENT +.UNINDENT + +.sp +.ce +---- + +.ce 0 +.sp +.IP [1] 5 +inotify on Linux, FSEvents on Darwin, kqueue on BSDs, +ReadDirectoryChangesW on Windows, event ports on Solaris, unsupported on Cygwin +.IP [2] 5 +see pipes +.SS Networking +.sp +Networking in libuv is not much different from directly using the BSD socket +interface, some things are easier, all are non\-blocking, but the concepts stay +the same. In addition libuv offers utility functions to abstract the annoying, +repetitive and low\-level tasks like setting up sockets using the BSD socket +structures, DNS lookup, and tweaking various socket parameters. +.sp +The \fBuv_tcp_t\fP and \fBuv_udp_t\fP structures are used for network I/O. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The code samples in this chapter exist to show certain libuv APIs. They are +not examples of good quality code. They leak memory and don\(aqt always close +connections properly. +.UNINDENT +.UNINDENT +.SS TCP +.sp +TCP is a connection oriented, stream protocol and is therefore based on the +libuv streams infrastructure. +.SS Server +.sp +Server sockets proceed by: +.INDENT 0.0 +.IP 1. 3 +\fBuv_tcp_init\fP the TCP handle. +.IP 2. 3 +\fBuv_tcp_bind\fP it. +.IP 3. 3 +Call \fBuv_listen\fP on the handle to have a callback invoked whenever a new +connection is established by a client. +.IP 4. 3 +Use \fBuv_accept\fP to accept the connection. +.IP 5. 3 +Use stream operations to communicate with the +client. +.UNINDENT +.sp +Here is a simple echo server +.sp +tcp\-echo\-server/main.c \- The listen socket +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + uv_close((uv_handle_t*) client, on_close); + } +} + +int main() { + loop = uv_default_loop(); + + uv_tcp_t server; + uv_tcp_init(loop, &server); + + uv_ip4_addr("0.0.0.0", DEFAULT_PORT, &addr); + + uv_tcp_bind(&server, (const struct sockaddr*)&addr, 0); + int r = uv_listen((uv_stream_t*) &server, DEFAULT_BACKLOG, on_new_connection); + if (r) { + fprintf(stderr, "Listen error %s\en", uv_strerror(r)); + return 1; + } + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can see the utility function \fBuv_ip4_addr\fP being used to convert from +a human readable IP address, port pair to the sockaddr_in structure required by +the BSD socket APIs. The reverse can be obtained using \fBuv_ip4_name\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There are \fBuv_ip6_*\fP analogues for the ip4 functions. +.UNINDENT +.UNINDENT +.sp +Most of the setup functions are synchronous since they are CPU\-bound. +\fBuv_listen\fP is where we return to libuv\(aqs callback style. The second +arguments is the backlog queue \-\- the maximum length of queued connections. +.sp +When a connection is initiated by clients, the callback is required to set up +a handle for the client socket and associate the handle using \fBuv_accept\fP\&. +In this case we also establish interest in reading from this stream. +.sp +tcp\-echo\-server/main.c \- Accepting the client +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + free(buf\->base); +} + +void on_new_connection(uv_stream_t *server, int status) { + if (status < 0) { + fprintf(stderr, "New connection error %s\en", uv_strerror(status)); + // error! + return; + } + + uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); + uv_tcp_init(loop, client); + if (uv_accept(server, (uv_stream_t*) client) == 0) { + uv_read_start((uv_stream_t*) client, alloc_buffer, echo_read); + } + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The remaining set of functions is very similar to the streams example and can +be found in the code. Just remember to call \fBuv_close\fP when the socket isn\(aqt +required. This can be done even in the \fBuv_listen\fP callback if you are not +interested in accepting the connection. +.SS Client +.sp +Where you do bind/listen/accept on the server, on the client side it\(aqs simply +a matter of calling \fBuv_tcp_connect\fP\&. The same \fBuv_connect_cb\fP style +callback of \fBuv_listen\fP is used by \fBuv_tcp_connect\fP\&. Try: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_tcp_t* socket = (uv_tcp_t*)malloc(sizeof(uv_tcp_t)); +uv_tcp_init(loop, socket); + +uv_connect_t* connect = (uv_connect_t*)malloc(sizeof(uv_connect_t)); + +struct sockaddr_in dest; +uv_ip4_addr("127.0.0.1", 80, &dest); + +uv_tcp_connect(connect, socket, (const struct sockaddr*)&dest, on_connect); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fBon_connect\fP will be called after the connection is established. The +callback receives the \fBuv_connect_t\fP struct, which has a member \fB\&.handle\fP +pointing to the socket. +.SS UDP +.sp +The \fI\%User Datagram Protocol\fP offers connectionless, unreliable network +communication. Hence libuv doesn\(aqt offer a stream. Instead libuv provides +non\-blocking UDP support via the \fIuv_udp_t\fP handle (for receiving) and +\fIuv_udp_send_t\fP request (for sending) and related functions. That said, the +actual API for reading/writing is very similar to normal stream reads. To look +at how UDP can be used, the example shows the first stage of obtaining an IP +address from a \fI\%DHCP\fP server \-\- DHCP Discover. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +You will have to run \fIudp\-dhcp\fP as \fBroot\fP since it uses well known port +numbers below 1024. +.UNINDENT +.UNINDENT +.sp +udp\-dhcp/main.c \- Setup and send UDP packets +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +uv_loop_t *loop; +uv_udp_t send_socket; +uv_udp_t recv_socket; + +int main() { + loop = uv_default_loop(); + + uv_udp_init(loop, &recv_socket); + struct sockaddr_in recv_addr; + uv_ip4_addr("0.0.0.0", 68, &recv_addr); + uv_udp_bind(&recv_socket, (const struct sockaddr *)&recv_addr, UV_UDP_REUSEADDR); + uv_udp_recv_start(&recv_socket, alloc_buffer, on_read); + + uv_udp_init(loop, &send_socket); + struct sockaddr_in broadcast_addr; + uv_ip4_addr("0.0.0.0", 0, &broadcast_addr); + uv_udp_bind(&send_socket, (const struct sockaddr *)&broadcast_addr, 0); + uv_udp_set_broadcast(&send_socket, 1); + + uv_udp_send_t send_req; + uv_buf_t discover_msg = make_discover_msg(); + + struct sockaddr_in send_addr; + uv_ip4_addr("255.255.255.255", 67, &send_addr); + uv_udp_send(&send_req, &send_socket, &discover_msg, 1, (const struct sockaddr *)&send_addr, on_send); + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The IP address \fB0.0.0.0\fP is used to bind to all interfaces. The IP +address \fB255.255.255.255\fP is a broadcast address meaning that packets +will be sent to all interfaces on the subnet. port \fB0\fP means that the OS +randomly assigns a port. +.UNINDENT +.UNINDENT +.sp +First we setup the receiving socket to bind on all interfaces on port 68 (DHCP +client) and start a read on it. This will read back responses from any DHCP +server that replies. We use the UV_UDP_REUSEADDR flag to play nice with any +other system DHCP clients that are running on this computer on the same port. +Then we setup a similar send socket and use \fBuv_udp_send\fP to send +a \fIbroadcast message\fP on port 67 (DHCP server). +.sp +It is \fBnecessary\fP to set the broadcast flag, otherwise you will get an +\fBEACCES\fP error [1]\&. The exact message being sent is not relevant to this +book and you can study the code if you are interested. As usual the read and +write callbacks will receive a status code of < 0 if something went wrong. +.sp +Since UDP sockets are not connected to a particular peer, the read callback +receives an extra parameter about the sender of the packet. +.sp +\fBnread\fP may be zero if there is no more data to be read. If \fBaddr\fP is NULL, +it indicates there is nothing to read (the callback shouldn\(aqt do anything), if +not NULL, it indicates that an empty datagram was received from the host at +\fBaddr\fP\&. The \fBflags\fP parameter may be \fBUV_UDP_PARTIAL\fP if the buffer +provided by your allocator was not large enough to hold the data. \fIIn this case +the OS will discard the data that could not fit\fP (That\(aqs UDP for you!). +.sp +udp\-dhcp/main.c \- Reading packets +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_udp_t *req, ssize_t nread, const uv_buf_t *buf, const struct sockaddr *addr, unsigned flags) { + if (nread < 0) { + fprintf(stderr, "Read error %s\en", uv_err_name(nread)); + uv_close((uv_handle_t*) req, NULL); + free(buf\->base); + return; + } + + char sender[17] = { 0 }; + uv_ip4_name((const struct sockaddr_in*) addr, sender, 16); + fprintf(stderr, "Recv from %s\en", sender); + + // ... DHCP specific code + unsigned int *as_integer = (unsigned int*)buf\->base; + unsigned int ipbin = ntohl(as_integer[4]); + unsigned char ip[4] = {0}; + int i; + for (i = 0; i < 4; i++) + ip[i] = (ipbin >> i*8) & 0xff; + fprintf(stderr, "Offered IP %d.%d.%d.%d\en", ip[3], ip[2], ip[1], ip[0]); + + free(buf\->base); + uv_udp_recv_stop(req); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS UDP Options +.SS Time\-to\-live +.sp +The TTL of packets sent on the socket can be changed using \fBuv_udp_set_ttl\fP\&. +.SS IPv6 stack only +.sp +IPv6 sockets can be used for both IPv4 and IPv6 communication. If you want to +restrict the socket to IPv6 only, pass the \fBUV_UDP_IPV6ONLY\fP flag to +\fBuv_udp_bind\fP [2]\&. +.SS Multicast +.sp +A socket can (un)subscribe to a multicast group using: +.sp +where \fBmembership\fP is \fBUV_JOIN_GROUP\fP or \fBUV_LEAVE_GROUP\fP\&. +.sp +The concepts of multicasting are nicely explained in \fI\%this guide\fP\&. +.sp +Local loopback of multicast packets is enabled by default [3], use +\fBuv_udp_set_multicast_loop\fP to switch it off. +.sp +The packet time\-to\-live for multicast packets can be changed using +\fBuv_udp_set_multicast_ttl\fP\&. +.SS Querying DNS +.sp +libuv provides asynchronous DNS resolution. For this it provides its own +\fBgetaddrinfo\fP replacement [4]\&. In the callback you can +perform normal socket operations on the retrieved addresses. Let\(aqs connect to +Freenode to see an example of DNS resolution. +.sp +dns/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +int main() { + loop = uv_default_loop(); + + struct addrinfo hints; + hints.ai_family = PF_INET; + hints.ai_socktype = SOCK_STREAM; + hints.ai_protocol = IPPROTO_TCP; + hints.ai_flags = 0; + + uv_getaddrinfo_t resolver; + fprintf(stderr, "irc.freenode.net is... "); + int r = uv_getaddrinfo(loop, &resolver, on_resolved, "irc.freenode.net", "6667", &hints); + + if (r) { + fprintf(stderr, "getaddrinfo call error %s\en", uv_err_name(r)); + return 1; + } + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If \fBuv_getaddrinfo\fP returns non\-zero, something went wrong in the setup and +your callback won\(aqt be invoked at all. All arguments can be freed immediately +after \fBuv_getaddrinfo\fP returns. The \fIhostname\fP, \fIservname\fP and \fIhints\fP +structures are documented in \fI\%the getaddrinfo man page\fP\&. The +callback can be \fBNULL\fP in which case the function will run synchronously. +.sp +In the resolver callback, you can pick any IP from the linked list of \fBstruct +addrinfo(s)\fP\&. This also demonstrates \fBuv_tcp_connect\fP\&. It is necessary to +call \fBuv_freeaddrinfo\fP in the callback. +.sp +dns/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void on_resolved(uv_getaddrinfo_t *resolver, int status, struct addrinfo *res) { + if (status < 0) { + fprintf(stderr, "getaddrinfo callback error %s\en", uv_err_name(status)); + return; + } + + char addr[17] = {\(aq\e0\(aq}; + uv_ip4_name((struct sockaddr_in*) res\->ai_addr, addr, 16); + fprintf(stderr, "%s\en", addr); + + uv_connect_t *connect_req = (uv_connect_t*) malloc(sizeof(uv_connect_t)); + uv_tcp_t *socket = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); + uv_tcp_init(loop, socket); + + uv_tcp_connect(connect_req, socket, (const struct sockaddr*) res\->ai_addr, on_connect); + + uv_freeaddrinfo(res); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +libuv also provides the inverse \fI\%uv_getnameinfo\fP\&. +.SS Network interfaces +.sp +Information about the system\(aqs network interfaces can be obtained through libuv +using \fBuv_interface_addresses\fP\&. This simple program just prints out all the +interface details so you get an idea of the fields that are available. This is +useful to allow your service to bind to IP addresses when it starts. +.sp +interfaces/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include + +int main() { + char buf[512]; + uv_interface_address_t *info; + int count, i; + + uv_interface_addresses(&info, &count); + i = count; + + printf("Number of interfaces: %d\en", count); + while (i\-\-) { + uv_interface_address_t interface = info[i]; + + printf("Name: %s\en", interface.name); + printf("Internal? %s\en", interface.is_internal ? "Yes" : "No"); + + if (interface.address.address4.sin_family == AF_INET) { + uv_ip4_name(&interface.address.address4, buf, sizeof(buf)); + printf("IPv4 address: %s\en", buf); + } + else if (interface.address.address4.sin_family == AF_INET6) { + uv_ip6_name(&interface.address.address6, buf, sizeof(buf)); + printf("IPv6 address: %s\en", buf); + } + + printf("\en"); + } + + uv_free_interface_addresses(info, count); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBis_internal\fP is true for loopback interfaces. Note that if a physical +interface has multiple IPv4/IPv6 addresses, the name will be reported multiple +times, with each address being reported once. + +.sp +.ce +---- + +.ce 0 +.sp +.IP [1] 5 +\fI\%https://beej.us/guide/bgnet/html/#broadcast\-packetshello\-world\fP +.IP [2] 5 +on Windows only supported on Windows Vista and later. +.IP [3] 5 +\fI\%https://www.tldp.org/HOWTO/Multicast\-HOWTO\-6.html#ss6.1\fP +.IP [4] 5 +libuv use the system \fBgetaddrinfo\fP in the libuv threadpool. libuv +v0.8.0 and earlier also included \fI\%c\-ares\fP as an alternative, but this has been +removed in v0.9.0. +.SS Threads +.sp +Wait a minute? Why are we on threads? Aren\(aqt event loops supposed to be \fBthe +way\fP to do \fIweb\-scale programming\fP? Well... no. Threads are still the medium in +which processors do their jobs. Threads are therefore mighty useful sometimes, even +though you might have to wade through various synchronization primitives. +.sp +Threads are used internally to fake the asynchronous nature of all of the system +calls. libuv also uses threads to allow you, the application, to perform a task +asynchronously that is actually blocking, by spawning a thread and collecting +the result when it is done. +.sp +Today there are two predominant thread libraries: the Windows threads +implementation and POSIX\(aqs \fI\%pthreads(7)\fP\&. libuv\(aqs thread API is analogous to +the pthreads API and often has similar semantics. +.sp +A notable aspect of libuv\(aqs thread facilities is that it is a self contained +section within libuv. Whereas other features intimately depend on the event +loop and callback principles, threads are complete agnostic, they block as +required, signal errors directly via return values, and, as shown in the +\fI\%first example\fP, don\(aqt even require a running +event loop. +.sp +libuv\(aqs thread API is also very limited since the semantics and syntax of +threads are different on all platforms, with different levels of completeness. +.sp +This chapter makes the following assumption: \fBThere is only one event loop, +running in one thread (the main thread)\fP\&. No other thread interacts +with the event loop (except using \fBuv_async_send\fP). +.SS Core thread operations +.sp +There isn\(aqt much here, you just start a thread using \fBuv_thread_create()\fP and +wait for it to close using \fBuv_thread_join()\fP\&. +.sp +thread\-create/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main() { + int tracklen = 10; + uv_thread_t hare_id; + uv_thread_t tortoise_id; + uv_thread_create(&hare_id, hare, &tracklen); + uv_thread_create(&tortoise_id, tortoise, &tracklen); + + uv_thread_join(&hare_id); + uv_thread_join(&tortoise_id); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBTIP:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBuv_thread_t\fP is just an alias for \fBpthread_t\fP on Unix, but this is an +implementation detail, avoid depending on it to always be true. +.UNINDENT +.UNINDENT +.sp +The second parameter is the function which will serve as the entry point for +the thread, the last parameter is a \fBvoid *\fP argument which can be used to pass +custom parameters to the thread. The function \fBhare\fP will now run in a separate +thread, scheduled pre\-emptively by the operating system: +.sp +thread\-create/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void hare(void *arg) { + int tracklen = *((int *) arg); + while (tracklen) { + tracklen\-\-; + sleep(1); + fprintf(stderr, "Hare ran another step\en"); + } + fprintf(stderr, "Hare done running!\en"); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Unlike \fBpthread_join()\fP which allows the target thread to pass back a value to +the calling thread using a second parameter, \fBuv_thread_join()\fP does not. To +send values use \fI\%Inter\-thread communication\fP\&. +.SS Synchronization Primitives +.sp +This section is purposely spartan. This book is not about threads, so I only +catalogue any surprises in the libuv APIs here. For the rest you can look at +the \fI\%pthreads(7)\fP man pages. +.SS Mutexes +.sp +The mutex functions are a \fBdirect\fP map to the pthread equivalents. +.sp +libuv mutex functions +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_mutex_init(uv_mutex_t* handle); +int uv_mutex_init_recursive(uv_mutex_t* handle); +void uv_mutex_destroy(uv_mutex_t* handle); +void uv_mutex_lock(uv_mutex_t* handle); +int uv_mutex_trylock(uv_mutex_t* handle); +void uv_mutex_unlock(uv_mutex_t* handle); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBuv_mutex_init()\fP, \fBuv_mutex_init_recursive()\fP and \fBuv_mutex_trylock()\fP +functions will return 0 on success, and an error code otherwise. +.sp +If \fIlibuv\fP has been compiled with debugging enabled, \fBuv_mutex_destroy()\fP, +\fBuv_mutex_lock()\fP and \fBuv_mutex_unlock()\fP will \fBabort()\fP on error. +Similarly \fBuv_mutex_trylock()\fP will abort if the error is anything \fIother +than\fP \fBEAGAIN\fP or \fBEBUSY\fP\&. +.sp +Recursive mutexes are supported, but you should not rely on them. Also, they +should not be used with \fBuv_cond_t\fP variables. +.sp +The default BSD mutex implementation will raise an error if a thread which has +locked a mutex attempts to lock it again. For example, a construct like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_mutex_init(a_mutex); +uv_mutex_lock(a_mutex); +uv_thread_create(thread_id, entry, (void *)a_mutex); +uv_mutex_lock(a_mutex); +// more things here +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +can be used to wait until another thread initializes some stuff and then +unlocks \fBa_mutex\fP but will lead to your program crashing if in debug mode, or +return an error in the second call to \fBuv_mutex_lock()\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Mutexes on Windows are always recursive. +.UNINDENT +.UNINDENT +.SS Locks +.sp +Read\-write locks are a more granular access mechanism. Two readers can access +shared memory at the same time. A writer may not acquire the lock when it is +held by a reader. A reader or writer may not acquire a lock when a writer is +holding it. Read\-write locks are frequently used in databases. Here is a toy +example. +.sp +locks/main.c \- simple rwlocks +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include + +uv_barrier_t blocker; +uv_rwlock_t numlock; +int shared_num; + +void reader(void *n) +{ + int num = *(int *)n; + int i; + for (i = 0; i < 20; i++) { + uv_rwlock_rdlock(&numlock); + printf("Reader %d: acquired lock\en", num); + printf("Reader %d: shared num = %d\en", num, shared_num); + uv_rwlock_rdunlock(&numlock); + printf("Reader %d: released lock\en", num); + } + uv_barrier_wait(&blocker); +} + +void writer(void *n) +{ + int num = *(int *)n; + int i; + for (i = 0; i < 20; i++) { + uv_rwlock_wrlock(&numlock); + printf("Writer %d: acquired lock\en", num); + shared_num++; + printf("Writer %d: incremented shared num = %d\en", num, shared_num); + uv_rwlock_wrunlock(&numlock); + printf("Writer %d: released lock\en", num); + } + uv_barrier_wait(&blocker); +} + +int main() +{ + uv_barrier_init(&blocker, 4); + + shared_num = 0; + uv_rwlock_init(&numlock); + + uv_thread_t threads[3]; + + int thread_nums[] = {1, 2, 1}; + uv_thread_create(&threads[0], reader, &thread_nums[0]); + uv_thread_create(&threads[1], reader, &thread_nums[1]); + + uv_thread_create(&threads[2], writer, &thread_nums[2]); + + uv_barrier_wait(&blocker); + uv_barrier_destroy(&blocker); + + uv_rwlock_destroy(&numlock); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Run this and observe how the readers will sometimes overlap. In case of +multiple writers, schedulers will usually give them higher priority, so if you +add two writers, you\(aqll see that both writers tend to finish first before the +readers get a chance again. +.sp +We also use barriers in the above example so that the main thread can wait for +all readers and writers to indicate they have ended. +.SS Others +.sp +libuv also supports \fI\%semaphores\fP, \fI\%condition variables\fP and \fI\%barriers\fP with APIs +very similar to their pthread counterparts. +.sp +In addition, libuv provides a convenience function \fBuv_once()\fP\&. Multiple +threads can attempt to call \fBuv_once()\fP with a given guard and a function +pointer, \fBonly the first one will win, the function will be called once and +only once\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +/* Initialize guard */ +static uv_once_t once_only = UV_ONCE_INIT; + +int i = 0; + +void increment() { + i++; +} + +void thread1() { + /* ... work */ + uv_once(once_only, increment); +} + +void thread2() { + /* ... work */ + uv_once(once_only, increment); +} + +int main() { + /* ... spawn threads */ +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +After all threads are done, \fBi == 1\fP\&. +.sp +libuv v0.11.11 onwards also added a \fBuv_key_t\fP struct and \fI\%api\fP for +thread\-local storage. +.SS libuv work queue +.sp +\fBuv_queue_work()\fP is a convenience function that allows an application to run +a task in a separate thread, and have a callback that is triggered when the +task is done. A seemingly simple function, what makes \fBuv_queue_work()\fP +tempting is that it allows potentially any third\-party libraries to be used +with the event\-loop paradigm. When you use event loops, it is \fIimperative to +make sure that no function which runs periodically in the loop thread blocks +when performing I/O or is a serious CPU hog\fP, because this means that the loop +slows down and events are not being handled at full capacity. +.sp +However, a lot of existing code out there features blocking functions (for example +a routine which performs I/O under the hood) to be used with threads if you +want responsiveness (the classic \(aqone thread per client\(aq server model), and +getting them to play with an event loop library generally involves rolling your +own system of running the task in a separate thread. libuv just provides +a convenient abstraction for this. +.sp +Here is a simple example inspired by \fI\%node.js is cancer\fP\&. We are going to +calculate fibonacci numbers, sleeping a bit along the way, but run it in +a separate thread so that the blocking and CPU bound task does not prevent the +event loop from performing other activities. +.sp +queue\-work/main.c \- lazy fibonacci +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void fib(uv_work_t *req) { + int n = *(int *) req\->data; + if (random() % 2) + sleep(1); + else + sleep(3); + long fib = fib_(n); + fprintf(stderr, "%dth fibonacci is %lu\en", n, fib); +} + +void after_fib(uv_work_t *req, int status) { + fprintf(stderr, "Done calculating %dth fibonacci\en", *(int *) req\->data); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The actual task function is simple, nothing to show that it is going to be +run in a separate thread. The \fBuv_work_t\fP structure is the clue. You can pass +arbitrary data through it using the \fBvoid* data\fP field and use it to +communicate to and from the thread. But be sure you are using proper locks if +you are changing things while both threads may be running. +.sp +The trigger is \fBuv_queue_work\fP: +.sp +queue\-work/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main() { + loop = uv_default_loop(); + + int data[FIB_UNTIL]; + uv_work_t req[FIB_UNTIL]; + int i; + for (i = 0; i < FIB_UNTIL; i++) { + data[i] = i; + req[i].data = (void *) &data[i]; + uv_queue_work(loop, &req[i], fib, after_fib); + } + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The thread function will be launched in a separate thread, passed the +\fBuv_work_t\fP structure and once the function returns, the \fIafter\fP function +will be called on the thread the event loop is running in. It will be passed +the same structure. +.sp +For writing wrappers to blocking libraries, a common pattern +is to use a baton to exchange data. +.sp +Since libuv version \fI0.9.4\fP an additional function, \fBuv_cancel()\fP, is +available. This allows you to cancel tasks on the libuv work queue. Only tasks +that \fIare yet to be started\fP can be cancelled. If a task has \fIalready started +executing, or it has finished executing\fP, \fBuv_cancel()\fP \fBwill fail\fP\&. +.sp +\fBuv_cancel()\fP is useful to cleanup pending tasks if the user requests +termination. For example, a music player may queue up multiple directories to +be scanned for audio files. If the user terminates the program, it should quit +quickly and not wait until all pending requests are run. +.sp +Let\(aqs modify the fibonacci example to demonstrate \fBuv_cancel()\fP\&. We first set +up a signal handler for termination. +.sp +queue\-cancel/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main() { + loop = uv_default_loop(); + + int data[FIB_UNTIL]; + int i; + for (i = 0; i < FIB_UNTIL; i++) { + data[i] = i; + fib_reqs[i].data = (void *) &data[i]; + uv_queue_work(loop, &fib_reqs[i], fib, after_fib); + } + + uv_signal_t sig; + uv_signal_init(loop, &sig); + uv_signal_start(&sig, signal_handler, SIGINT); + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When the user triggers the signal by pressing \fBCtrl+C\fP we send +\fBuv_cancel()\fP to all the workers. \fBuv_cancel()\fP will return \fB0\fP for those that are already executing or finished. +.sp +queue\-cancel/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void signal_handler(uv_signal_t *req, int signum) +{ + printf("Signal received!\en"); + int i; + for (i = 0; i < FIB_UNTIL; i++) { + uv_cancel((uv_req_t*) &fib_reqs[i]); + } + uv_signal_stop(req); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For tasks that do get cancelled successfully, the \fIafter\fP function is called +with \fBstatus\fP set to \fBUV_ECANCELED\fP\&. +.sp +queue\-cancel/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void after_fib(uv_work_t *req, int status) { + if (status == UV_ECANCELED) + fprintf(stderr, "Calculation of %d cancelled.\en", *(int *) req\->data); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBuv_cancel()\fP can also be used with \fBuv_fs_t\fP and \fBuv_getaddrinfo_t\fP +requests. For the filesystem family of functions, \fBuv_fs_t.errorno\fP will be +set to \fBUV_ECANCELED\fP\&. +.sp +\fBTIP:\fP +.INDENT 0.0 +.INDENT 3.5 +A well designed program would have a way to terminate long running workers +that have already started executing. Such a worker could periodically check +for a variable that only the main process sets to signal termination. +.UNINDENT +.UNINDENT +.SS Inter\-thread communication +.sp +Sometimes you want various threads to actually send each other messages \fIwhile\fP +they are running. For example you might be running some long duration task in +a separate thread (perhaps using \fBuv_queue_work\fP) but want to notify progress +to the main thread. This is a simple example of having a download manager +informing the user of the status of running downloads. +.sp +progress/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t *loop; +uv_async_t async; + +int main() { + loop = uv_default_loop(); + + uv_work_t req; + int size = 10240; + req.data = (void*) &size; + + uv_async_init(loop, &async, print_progress); + uv_queue_work(loop, &req, fake_download, after); + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The async thread communication works \fIon loops\fP so although any thread can be +the message sender, only threads with libuv loops can be receivers (or rather +the loop is the receiver). libuv will invoke the callback (\fBprint_progress\fP) +with the async watcher whenever it receives a message. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +It is important to realize that since the message send is \fIasync\fP, the callback +may be invoked immediately after \fBuv_async_send\fP is called in another +thread, or it may be invoked after some time. libuv may also combine +multiple calls to \fBuv_async_send\fP and invoke your callback only once. The +only guarantee that libuv makes is \-\- The callback function is called \fIat +least once\fP after the call to \fBuv_async_send\fP\&. If you have no pending +calls to \fBuv_async_send\fP, the callback won\(aqt be called. If you make two +or more calls, and libuv hasn\(aqt had a chance to run the callback yet, it +\fImay\fP invoke your callback \fIonly once\fP for the multiple invocations of +\fBuv_async_send\fP\&. Your callback will never be called twice for just one +event. +.UNINDENT +.UNINDENT +.sp +progress/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +double percentage; + +void fake_download(uv_work_t *req) { + int size = *((int*) req\->data); + int downloaded = 0; + while (downloaded < size) { + percentage = downloaded*100.0/size; + async.data = (void*) &percentage; + uv_async_send(&async); + + sleep(1); + downloaded += (200+random())%1000; // can only download max 1000bytes/sec, + // but at least a 200; + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In the download function, we modify the progress indicator and queue the message +for delivery with \fBuv_async_send\fP\&. Remember: \fBuv_async_send\fP is also +non\-blocking and will return immediately. +.sp +progress/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void print_progress(uv_async_t *handle) { + double percentage = *((double*) handle\->data); + fprintf(stderr, "Downloaded %.2f%%\en", percentage); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The callback is a standard libuv pattern, extracting the data from the watcher. +.sp +Finally it is important to remember to clean up the watcher. +.sp +progress/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void after(uv_work_t *req, int status) { + fprintf(stderr, "Download complete\en"); + uv_close((uv_handle_t*) &async, NULL); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +After this example, which showed the abuse of the \fBdata\fP field, \fI\%bnoordhuis\fP +pointed out that using the \fBdata\fP field is not thread safe, and +\fBuv_async_send()\fP is actually only meant to wake up the event loop. Use +a mutex or rwlock to ensure accesses are performed in the right order. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +mutexes and rwlocks \fBDO NOT\fP work inside a signal handler, whereas +\fBuv_async_send\fP does. +.UNINDENT +.UNINDENT +.sp +One use case where \fBuv_async_send\fP is required is when interoperating with +libraries that require thread affinity for their functionality. For example in +node.js, a v8 engine instance, contexts and its objects are bound to the thread +that the v8 instance was started in. Interacting with v8 data structures from +another thread can lead to undefined results. Now consider some node.js module +which binds a third party library. It may go something like this: +.INDENT 0.0 +.IP 1. 3 +In node, the third party library is set up with a JavaScript callback to be +invoked for more information: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +var lib = require(\(aqlib\(aq); +lib.on_progress(function() { + console.log("Progress"); +}); + +lib.do(); + +// do other stuff +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +\fBlib.do\fP is supposed to be non\-blocking but the third party lib is +blocking, so the binding uses \fBuv_queue_work\fP\&. +.IP 3. 3 +The actual work being done in a separate thread wants to invoke the progress +callback, but cannot directly call into v8 to interact with JavaScript. So +it uses \fBuv_async_send\fP\&. +.IP 4. 3 +The async callback, invoked in the main loop thread, which is the v8 thread, +then interacts with v8 to invoke the JavaScript callback. +.UNINDENT + +.sp +.ce +---- + +.ce 0 +.sp +.SS Processes +.sp +libuv offers considerable child process management, abstracting the platform +differences and allowing communication with the child process using streams or +named pipes. +.sp +A common idiom in Unix is for every process to do one thing and do it well. In +such a case, a process often uses multiple child processes to achieve tasks +(similar to using pipes in shells). A multi\-process model with messages +may also be easier to reason about compared to one with threads and shared +memory. +.sp +A common refrain against event\-based programs is that they cannot take +advantage of multiple cores in modern computers. In a multi\-threaded program +the kernel can perform scheduling and assign different threads to different +cores, improving performance. But an event loop has only one thread. The +workaround can be to launch multiple processes instead, with each process +running an event loop, and each process getting assigned to a separate CPU +core. +.SS Spawning child processes +.sp +The simplest case is when you simply want to launch a process and know when it +exits. This is achieved using \fBuv_spawn\fP\&. +.sp +spawn/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t *loop; +uv_process_t child_req; +uv_process_options_t options; +int main() { + loop = uv_default_loop(); + + char* args[3]; + args[0] = "mkdir"; + args[1] = "test\-dir"; + args[2] = NULL; + + options.exit_cb = on_exit; + options.file = "mkdir"; + options.args = args; + + int r; + if ((r = uv_spawn(loop, &child_req, &options))) { + fprintf(stderr, "%s\en", uv_strerror(r)); + return 1; + } else { + fprintf(stderr, "Launched process with ID %d\en", child_req.pid); + } + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBoptions\fP is implicitly initialized with zeros since it is a global +variable. If you change \fBoptions\fP to a local variable, remember to +initialize it to null out all unused fields: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_process_options_t options = {0}; +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The \fBuv_process_t\fP struct only acts as the handle, all options are set via +\fBuv_process_options_t\fP\&. To simply launch a process, you need to set only the +\fBfile\fP and \fBargs\fP fields. \fBfile\fP is the program to execute. Since +\fBuv_spawn\fP uses \fI\%execvp(3)\fP internally, there is no need to supply the full +path. Finally as per underlying conventions, \fBthe arguments array has to be +one larger than the number of arguments, with the last element being NULL\fP\&. +.sp +After the call to \fBuv_spawn\fP, \fBuv_process_t.pid\fP will contain the process +ID of the child process. +.sp +The exit callback will be invoked with the \fIexit status\fP and the type of \fIsignal\fP +which caused the exit. +.sp +spawn/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void on_exit(uv_process_t *req, int64_t exit_status, int term_signal) { + fprintf(stderr, "Process exited with status %" PRId64 ", signal %d\en", exit_status, term_signal); + uv_close((uv_handle_t*) req, NULL); + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +It is \fBrequired\fP to close the process watcher after the process exits. +.SS Changing process parameters +.sp +Before the child process is launched you can control the execution environment +using fields in \fBuv_process_options_t\fP\&. +.SS Change execution directory +.sp +Set \fBuv_process_options_t.cwd\fP to the corresponding directory. +.SS Set environment variables +.sp +\fBuv_process_options_t.env\fP is a null\-terminated array of strings, each of the +form \fBVAR=VALUE\fP used to set up the environment variables for the process. Set +this to \fBNULL\fP to inherit the environment from the parent (this) process. +.SS Option flags +.sp +Setting \fBuv_process_options_t.flags\fP to a bitwise OR of the following flags, +modifies the child process behaviour: +.INDENT 0.0 +.IP \(bu 2 +\fBUV_PROCESS_SETUID\fP \- sets the child\(aqs execution user ID to \fBuv_process_options_t.uid\fP\&. +.IP \(bu 2 +\fBUV_PROCESS_SETGID\fP \- sets the child\(aqs execution group ID to \fBuv_process_options_t.gid\fP\&. +.UNINDENT +.sp +Changing the UID/GID is only supported on Unix, \fBuv_spawn\fP will fail on +Windows with \fBUV_ENOTSUP\fP\&. +.INDENT 0.0 +.IP \(bu 2 +\fBUV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS\fP \- No quoting or escaping of +\fBuv_process_options_t.args\fP is done on Windows. Ignored on Unix. +.IP \(bu 2 +\fBUV_PROCESS_DETACHED\fP \- Starts the child process in a new session, which +will keep running after the parent process exits. See example below. +.UNINDENT +.SS Detaching processes +.sp +Passing the flag \fBUV_PROCESS_DETACHED\fP can be used to launch daemons, or +child processes which are independent of the parent so that the parent exiting +does not affect it. +.sp +detach/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int main() { + loop = uv_default_loop(); + + char* args[3]; + args[0] = "sleep"; + args[1] = "100"; + args[2] = NULL; + + options.exit_cb = NULL; + options.file = "sleep"; + options.args = args; + options.flags = UV_PROCESS_DETACHED; + + int r; + if ((r = uv_spawn(loop, &child_req, &options))) { + fprintf(stderr, "%s\en", uv_strerror(r)); + return 1; + } + fprintf(stderr, "Launched sleep with PID %d\en", child_req.pid); + uv_unref((uv_handle_t*) &child_req); + + return uv_run(loop, UV_RUN_DEFAULT); + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Just remember that the handle is still monitoring the child, so your program +won\(aqt exit. Use \fBuv_unref()\fP if you want to be more \fIfire\-and\-forget\fP\&. +.SS Sending signals to processes +.sp +libuv wraps the standard \fBkill(2)\fP system call on Unix and implements one +with similar semantics on Windows, with \fIone caveat\fP: all of \fBSIGTERM\fP, +\fBSIGINT\fP and \fBSIGKILL\fP, lead to termination of the process. The signature +of \fBuv_kill\fP is: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_err_t uv_kill(int pid, int signum); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For processes started using libuv, you may use \fBuv_process_kill\fP instead, +which accepts the \fBuv_process_t\fP watcher as the first argument, rather than +the pid. In this case, \fBremember to call\fP \fBuv_close\fP on the watcher. +.SS Signals +.sp +libuv provides wrappers around Unix signals with \fI\%some Windows support\fP as well. +.sp +Use \fBuv_signal_init()\fP to initialize +a handle and associate it with a loop. To listen for particular signals on +that handler, use \fBuv_signal_start()\fP with the handler function. Each handler +can only be associated with one signal number, with subsequent calls to +\fBuv_signal_start()\fP overwriting earlier associations. Use \fBuv_signal_stop()\fP to +stop watching. Here is a small example demonstrating the various possibilities: +.sp +signal/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include +#include +#include + +uv_loop_t* create_loop() +{ + uv_loop_t *loop = malloc(sizeof(uv_loop_t)); + if (loop) { + uv_loop_init(loop); + } + return loop; +} + +void signal_handler(uv_signal_t *handle, int signum) +{ + printf("Signal received: %d\en", signum); + uv_signal_stop(handle); +} + +// two signal handlers in one loop +void thread1_worker(void *userp) +{ + uv_loop_t *loop1 = create_loop(); + + uv_signal_t sig1a, sig1b; + uv_signal_init(loop1, &sig1a); + uv_signal_start(&sig1a, signal_handler, SIGUSR1); + + uv_signal_init(loop1, &sig1b); + uv_signal_start(&sig1b, signal_handler, SIGUSR1); + + uv_run(loop1, UV_RUN_DEFAULT); +} + +// two signal handlers, each in its own loop +void thread2_worker(void *userp) +{ + uv_loop_t *loop2 = create_loop(); + uv_loop_t *loop3 = create_loop(); + + uv_signal_t sig2; + uv_signal_init(loop2, &sig2); + uv_signal_start(&sig2, signal_handler, SIGUSR1); + + uv_signal_t sig3; + uv_signal_init(loop3, &sig3); + uv_signal_start(&sig3, signal_handler, SIGUSR1); + + while (uv_run(loop2, UV_RUN_NOWAIT) || uv_run(loop3, UV_RUN_NOWAIT)) { + } +} + +int main() +{ + printf("PID %d\en", getpid()); + + uv_thread_t thread1, thread2; + + uv_thread_create(&thread1, thread1_worker, 0); + uv_thread_create(&thread2, thread2_worker, 0); + + uv_thread_join(&thread1); + uv_thread_join(&thread2); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBuv_run(loop, UV_RUN_NOWAIT)\fP is similar to \fBuv_run(loop, UV_RUN_ONCE)\fP +in that it will process only one event. UV_RUN_ONCE blocks if there are no +pending events, while UV_RUN_NOWAIT will return immediately. We use NOWAIT +so that one of the loops isn\(aqt starved because the other one has no pending +activity. +.UNINDENT +.UNINDENT +.sp +Send \fBSIGUSR1\fP to the process, and you\(aqll find the handler being invoked +4 times, one for each \fBuv_signal_t\fP\&. The handler just stops each handle, +so that the program exits. This sort of dispatch to all handlers is very +useful. A server using multiple event loops could ensure that all data was +safely saved before termination, simply by every loop adding a watcher for +\fBSIGINT\fP\&. +.SS Child Process I/O +.sp +A normal, newly spawned process has its own set of file descriptors, with 0, +1 and 2 being \fBstdin\fP, \fBstdout\fP and \fBstderr\fP respectively. Sometimes you +may want to share file descriptors with the child. For example, perhaps your +applications launches a sub\-command and you want any errors to go in the log +file, but ignore \fBstdout\fP\&. For this you\(aqd like to have \fBstderr\fP of the +child be the same as the stderr of the parent. In this case, libuv supports +\fIinheriting\fP file descriptors. In this sample, we invoke the test program, +which is: +.sp +proc\-streams/test.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include + +int main() +{ + fprintf(stderr, "This is stderr\en"); + printf("This is stdout\en"); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The actual program \fBproc\-streams\fP runs this while sharing only \fBstderr\fP\&. +The file descriptors of the child process are set using the \fBstdio\fP field in +\fBuv_process_options_t\fP\&. First set the \fBstdio_count\fP field to the number of +file descriptors being set. \fBuv_process_options_t.stdio\fP is an array of +\fBuv_stdio_container_t\fP, which is: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +typedef struct uv_stdio_container_s { + uv_stdio_flags flags; + + union { + uv_stream_t* stream; + int fd; + } data; +} uv_stdio_container_t; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where flags can have several values. Use \fBUV_IGNORE\fP if it isn\(aqt going to be +used. If the first three \fBstdio\fP fields are marked as \fBUV_IGNORE\fP they\(aqll +redirect to \fB/dev/null\fP\&. +.sp +Since we want to pass on an existing descriptor, we\(aqll use \fBUV_INHERIT_FD\fP\&. +Then we set the \fBfd\fP to \fBstderr\fP\&. +.sp +proc\-streams/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +int main() { + loop = uv_default_loop(); + + /* ... */ + + options.stdio_count = 3; + uv_stdio_container_t child_stdio[3]; + child_stdio[0].flags = UV_IGNORE; + child_stdio[1].flags = UV_IGNORE; + child_stdio[2].flags = UV_INHERIT_FD; + child_stdio[2].data.fd = 2; + options.stdio = child_stdio; + + options.exit_cb = on_exit; + options.file = args[0]; + options.args = args; + + int r; + if ((r = uv_spawn(loop, &child_req, &options))) { + fprintf(stderr, "%s\en", uv_strerror(r)); + return 1; + } + + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you run \fBproc\-stream\fP you\(aqll see that only the line "This is stderr" will +be displayed. Try marking \fBstdout\fP as being inherited and see the output. +.sp +It is dead simple to apply this redirection to streams. By setting \fBflags\fP +to \fBUV_INHERIT_STREAM\fP and setting \fBdata.stream\fP to the stream in the +parent process, the child process can treat that stream as standard I/O. This +can be used to implement something like \fI\%CGI\fP\&. +.sp +A sample CGI script/executable is: +.sp +cgi/tick.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include + +int main() { + int i; + for (i = 0; i < 10; i++) { + printf("tick\en"); + fflush(stdout); + sleep(1); + } + printf("BOOM!\en"); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The CGI server combines the concepts from this chapter and networking so +that every client is sent ten ticks after which that connection is closed. +.sp +cgi/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void on_new_connection(uv_stream_t *server, int status) { + if (status == \-1) { + // error! + return; + } + + uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); + uv_tcp_init(loop, client); + if (uv_accept(server, (uv_stream_t*) client) == 0) { + invoke_cgi_script(client); + } + else { + uv_close((uv_handle_t*) client, NULL); + } + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Here we simply accept the TCP connection and pass on the socket (\fIstream\fP) to +\fBinvoke_cgi_script\fP\&. +.sp +cgi/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + + args[1] = NULL; + + /* ... finding the executable path and setting up arguments ... */ + + options.stdio_count = 3; + uv_stdio_container_t child_stdio[3]; + child_stdio[0].flags = UV_IGNORE; + child_stdio[1].flags = UV_INHERIT_STREAM; + child_stdio[1].data.stream = (uv_stream_t*) client; + child_stdio[2].flags = UV_IGNORE; + options.stdio = child_stdio; + + options.exit_cb = cleanup_handles; + options.file = args[0]; + options.args = args; + + // Set this so we can close the socket after the child process exits. + child_req.data = (void*) client; + int r; + if ((r = uv_spawn(loop, &child_req, &options))) { + fprintf(stderr, "%s\en", uv_strerror(r)); + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBstdout\fP of the CGI script is set to the socket so that whatever our tick +script prints, gets sent to the client. By using processes, we can offload the +read/write buffering to the operating system, so in terms of convenience this +is great. Just be warned that creating processes is a costly task. +.SS Parent\-child IPC +.sp +A parent and child can have one or two way communication over a pipe created by +settings \fBuv_stdio_container_t.flags\fP to a bit\-wise combination of +\fBUV_CREATE_PIPE\fP and \fBUV_READABLE_PIPE\fP or \fBUV_WRITABLE_PIPE\fP\&. The +read/write flag is from the perspective of the child process. In this case, +the \fBuv_stream_t* stream\fP field must be set to point to an initialized, +unopened \fBuv_pipe_t\fP instance. +.SS New stdio Pipes +.sp +The \fBuv_pipe_t\fP structure represents more than just \fI\%pipe(7)\fP (or \fB|\fP), +but supports any streaming file\-like objects. On Windows, the only object of +that description is the \fI\%Named Pipe\fP\&. On Unix, this could be any of \fI\%Unix +Domain Socket\fP, or derived from \fI\%mkfifo(1)\fP, or it could actually be a +\fI\%pipe(7)\fP\&. When \fBuv_spawn\fP initializes a \fBuv_pipe_t\fP due to the +\fIUV_CREATE_PIPE\fP flag, it opts for creating a \fI\%socketpair(2)\fP\&. +.sp +This is intended for the purpose of allowing multiple libuv processes to +communicate with IPC. This is discussed below. +.SS Arbitrary process IPC +.sp +Since domain sockets [1] can have a well known name and a location in the +file\-system they can be used for IPC between unrelated processes. The \fI\%D\-BUS\fP +system used by open source desktop environments uses domain sockets for event +notification. Various applications can then react when a contact comes online +or new hardware is detected. The MySQL server also runs a domain socket on +which clients can interact with it. +.sp +When using domain sockets, a client\-server pattern is usually followed with the +creator/owner of the socket acting as the server. After the initial setup, +messaging is no different from TCP, so we\(aqll re\-use the echo server example. +.sp +pipe\-echo\-server/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void remove_sock(int sig) { + uv_fs_t req; + uv_fs_unlink(loop, &req, PIPENAME, NULL); + exit(0); +} + +int main() { + loop = uv_default_loop(); + + uv_pipe_t server; + uv_pipe_init(loop, &server, 0); + + signal(SIGINT, remove_sock); + + int r; + if ((r = uv_pipe_bind(&server, PIPENAME))) { + fprintf(stderr, "Bind error %s\en", uv_err_name(r)); + return 1; + } + if ((r = uv_listen((uv_stream_t*) &server, 128, on_new_connection))) { + fprintf(stderr, "Listen error %s\en", uv_err_name(r)); + return 2; + } + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We name the socket \fBecho.sock\fP which means it will be created in the local +directory. This socket now behaves no different from TCP sockets as far as +the stream API is concerned. You can test this server using \fI\%socat\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ socat \- /path/to/socket +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A client which wants to connect to a domain socket will use: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void uv_pipe_connect(uv_connect_t *req, uv_pipe_t *handle, const char *name, uv_connect_cb cb); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fBname\fP will be \fBecho.sock\fP or similar. On Unix systems, \fBname\fP must +point to a valid file (e.g. \fB/tmp/echo.sock\fP). On Windows, \fBname\fP follows a +\fB\e\e?\epipe\eecho.sock\fP format. +.SS Sending file descriptors over pipes +.sp +The cool thing about domain sockets is that file descriptors can be exchanged +between processes by sending them over a domain socket. This allows processes +to hand off their I/O to other processes. Applications include load\-balancing +servers, worker processes and other ways to make optimum use of CPU. libuv only +supports sending \fBTCP sockets or other pipes\fP over pipes for now. +.sp +To demonstrate, we will look at a echo server implementation that hands of +clients to worker processes in a round\-robin fashion. This program is a bit +involved, and while only snippets are included in the book, it is recommended +to read the full code to really understand it. +.sp +The worker process is quite simple, since the file\-descriptor is handed over to +it by the master. +.sp +multi\-echo\-server/worker.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +uv_loop_t *loop; +uv_pipe_t queue; +int main() { + loop = uv_default_loop(); + + uv_pipe_init(loop, &queue, 1 /* ipc */); + uv_pipe_open(&queue, 0); + uv_read_start((uv_stream_t*)&queue, alloc_buffer, on_new_connection); + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBqueue\fP is the pipe connected to the master process on the other end, along +which new file descriptors get sent. It is important to set the \fBipc\fP +argument of \fBuv_pipe_init\fP to 1 to indicate this pipe will be used for +inter\-process communication! Since the master will write the file handle to the +standard input of the worker, we connect the pipe to \fBstdin\fP using +\fBuv_pipe_open\fP\&. +.sp +multi\-echo\-server/worker.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_new_connection(uv_stream_t *q, ssize_t nread, const uv_buf_t *buf) { + if (nread < 0) { + if (nread != UV_EOF) + fprintf(stderr, "Read error %s\en", uv_err_name(nread)); + uv_close((uv_handle_t*) q, NULL); + return; + } + + uv_pipe_t *pipe = (uv_pipe_t*) q; + if (!uv_pipe_pending_count(pipe)) { + fprintf(stderr, "No pending count\en"); + return; + } + + uv_handle_type pending = uv_pipe_pending_type(pipe); + assert(pending == UV_TCP); + + uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); + uv_tcp_init(loop, client); + if (uv_accept(q, (uv_stream_t*) client) == 0) { + uv_os_fd_t fd; + uv_fileno((const uv_handle_t*) client, &fd); + fprintf(stderr, "Worker %d: Accepted fd %d\en", getpid(), fd); + uv_read_start((uv_stream_t*) client, alloc_buffer, echo_read); + } + else { + uv_close((uv_handle_t*) client, NULL); + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +First we call \fBuv_pipe_pending_count()\fP to ensure that a handle is available +to read out. If your program could deal with different types of handles, +\fBuv_pipe_pending_type()\fP can be used to determine the type. +Although \fBaccept\fP seems odd in this code, it actually makes sense. What +\fBaccept\fP traditionally does is get a file descriptor (the client) from +another file descriptor (The listening socket). Which is exactly what we do +here. Fetch the file descriptor (\fBclient\fP) from \fBqueue\fP\&. From this point +the worker does standard echo server stuff. +.sp +Turning now to the master, let\(aqs take a look at how the workers are launched to +allow load balancing. +.sp +multi\-echo\-server/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +struct child_worker { + uv_process_t req; + uv_process_options_t options; + uv_pipe_t pipe; +} *workers; + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBchild_worker\fP structure wraps the process, and the pipe between the +master and the individual process. +.sp +multi\-echo\-server/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void setup_workers() { + round_robin_counter = 0; + + // ... + + // launch same number of workers as number of CPUs + uv_cpu_info_t *info; + int cpu_count; + uv_cpu_info(&info, &cpu_count); + uv_free_cpu_info(info, cpu_count); + + child_worker_count = cpu_count; + + workers = calloc(cpu_count, sizeof(struct child_worker)); + while (cpu_count\-\-) { + struct child_worker *worker = &workers[cpu_count]; + uv_pipe_init(loop, &worker\->pipe, 1); + + uv_stdio_container_t child_stdio[3]; + child_stdio[0].flags = UV_CREATE_PIPE | UV_READABLE_PIPE; + child_stdio[0].data.stream = (uv_stream_t*) &worker\->pipe; + child_stdio[1].flags = UV_IGNORE; + child_stdio[2].flags = UV_INHERIT_FD; + child_stdio[2].data.fd = 2; + + worker\->options.stdio = child_stdio; + worker\->options.stdio_count = 3; + + worker\->options.exit_cb = close_process_handle; + worker\->options.file = args[0]; + worker\->options.args = args; + + uv_spawn(loop, &worker\->req, &worker\->options); + fprintf(stderr, "Started worker %d\en", worker\->req.pid); + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In setting up the workers, we use the nifty libuv function \fBuv_cpu_info\fP to +get the number of CPUs so we can launch an equal number of workers. Again it is +important to initialize the pipe acting as the IPC channel with the third +argument as 1. We then indicate that the child process\(aq \fBstdin\fP is to be +a readable pipe (from the point of view of the child). Everything is +straightforward till here. The workers are launched and waiting for file +descriptors to be written to their standard input. +.sp +It is in \fBon_new_connection\fP (the TCP infrastructure is initialized in +\fBmain()\fP), that we accept the client socket and pass it along to the next +worker in the round\-robin. +.sp +multi\-echo\-server/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_new_connection(uv_stream_t *server, int status) { + if (status == \-1) { + // error! + return; + } + + uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); + uv_tcp_init(loop, client); + if (uv_accept(server, (uv_stream_t*) client) == 0) { + uv_write_t *write_req = (uv_write_t*) malloc(sizeof(uv_write_t)); + dummy_buf = uv_buf_init("a", 1); + struct child_worker *worker = &workers[round_robin_counter]; + uv_write2(write_req, (uv_stream_t*) &worker\->pipe, &dummy_buf, 1, (uv_stream_t*) client, NULL); + round_robin_counter = (round_robin_counter + 1) % child_worker_count; + } + else { + uv_close((uv_handle_t*) client, NULL); + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBuv_write2\fP call handles all the abstraction and it is simply a matter of +passing in the handle (\fBclient\fP) as the right argument. With this our +multi\-process echo server is operational. +.sp +Thanks to Kyle for \fI\%pointing out\fP that \fBuv_write2()\fP requires a non\-empty +buffer even when sending handles. + +.sp +.ce +---- + +.ce 0 +.sp +.IP [1] 5 +In this section domain sockets stands in for named pipes on Windows as +well. +.SS Advanced event loops +.sp +libuv provides considerable user control over event loops, and you can achieve +interesting results by juggling multiple loops. You can also embed libuv\(aqs +event loop into another event loop based library \-\- imagine a Qt based UI, and +Qt\(aqs event loop driving a libuv backend which does intensive system level +tasks. +.SS Stopping an event loop +.sp +\fBuv_stop()\fP can be used to stop an event loop. The earliest the loop will +stop running is \fIon the next iteration\fP, possibly later. This means that events +that are ready to be processed in this iteration of the loop will still be +processed, so \fBuv_stop()\fP can\(aqt be used as a kill switch. When \fBuv_stop()\fP +is called, the loop \fBwon\(aqt\fP block for i/o on this iteration. The semantics of +these things can be a bit difficult to understand, so let\(aqs look at +\fBuv_run()\fP where all the control flow occurs. +.sp +src/unix/core.c \- uv_run +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +static void uv__run_closing_handles(uv_loop_t* loop) { + uv_handle_t* p; + uv_handle_t* q; + + p = loop\->closing_handles; + loop\->closing_handles = NULL; + + while (p) { + q = p\->next_closing; + uv__finish_close(p); + p = q; + } +} + + +int uv_is_closing(const uv_handle_t* handle) { + return uv__is_closing(handle); +} + + +int uv_backend_fd(const uv_loop_t* loop) { + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBstop_flag\fP is set by \fBuv_stop()\fP\&. Now all libuv callbacks are invoked +within the event loop, which is why invoking \fBuv_stop()\fP in them will still +lead to this iteration of the loop occurring. First libuv updates timers, then +runs pending timer, idle and prepare callbacks, and invokes any pending I/O +callbacks. If you were to call \fBuv_stop()\fP in any of them, \fBstop_flag\fP +would be set. This causes \fBuv_backend_timeout()\fP to return \fB0\fP, which is +why the loop does not block on I/O. If on the other hand, you called +\fBuv_stop()\fP in one of the check handlers, I/O has already finished and is not +affected. +.sp +\fBuv_stop()\fP is useful to shutdown a loop when a result has been computed or +there is an error, without having to ensure that all handlers are stopped one +by one. +.sp +Here is a simple example that stops the loop and demonstrates how the current +iteration of the loop still takes places. +.sp +uvstop/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include + +int64_t counter = 0; + +void idle_cb(uv_idle_t *handle) { + printf("Idle callback\en"); + counter++; + + if (counter >= 5) { + uv_stop(uv_default_loop()); + printf("uv_stop() called\en"); + } +} + +void prep_cb(uv_prepare_t *handle) { + printf("Prep callback\en"); +} + +int main() { + uv_idle_t idler; + uv_prepare_t prep; + + uv_idle_init(uv_default_loop(), &idler); + uv_idle_start(&idler, idle_cb); + + uv_prepare_init(uv_default_loop(), &prep); + uv_prepare_start(&prep, prep_cb); + + uv_run(uv_default_loop(), UV_RUN_DEFAULT); + + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Utilities +.sp +This chapter catalogues tools and techniques which are useful for common tasks. +The \fI\%libev man page\fP already covers some patterns which can be adopted to +libuv through simple API changes. It also covers parts of the libuv API that +don\(aqt require entire chapters dedicated to them. +.SS Timers +.sp +Timers invoke the callback after a certain time has elapsed since the timer was +started. libuv timers can also be set to invoke at regular intervals instead of +just once. +.sp +Simple use is to init a watcher and start it with a \fBtimeout\fP, and optional \fBrepeat\fP\&. +Timers can be stopped at any time. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_timer_t timer_req; + +uv_timer_init(loop, &timer_req); +uv_timer_start(&timer_req, callback, 5000, 2000); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +will start a repeating timer, which first starts 5 seconds (the \fBtimeout\fP) after the execution +of \fBuv_timer_start\fP, then repeats every 2 seconds (the \fBrepeat\fP). Use: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_timer_stop(&timer_req); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +to stop the timer. This can be used safely from within the callback as well. +.sp +The repeat interval can be modified at any time with: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_timer_set_repeat(uv_timer_t *timer, int64_t repeat); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +which will take effect \fBwhen possible\fP\&. If this function is called from +a timer callback, it means: +.INDENT 0.0 +.IP \(bu 2 +If the timer was non\-repeating, the timer has already been stopped. Use +\fBuv_timer_start\fP again. +.IP \(bu 2 +If the timer is repeating, the next timeout has already been scheduled, so +the old repeat interval will be used once more before the timer switches to +the new interval. +.UNINDENT +.sp +The utility function: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_timer_again(uv_timer_t *) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +applies \fBonly to repeating timers\fP and is equivalent to stopping the timer +and then starting it with both initial \fBtimeout\fP and \fBrepeat\fP set to the +old \fBrepeat\fP value. If the timer hasn\(aqt been started it fails (error code +\fBUV_EINVAL\fP) and returns \-1. +.sp +An actual timer example is in the \fI\%reference count section\fP\&. +.SS Event loop reference count +.sp +The event loop only runs as long as there are active handles. This system +works by having every handle increase the reference count of the event loop +when it is started and decreasing the reference count when stopped. It is also +possible to manually change the reference count of handles using: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void uv_ref(uv_handle_t*); +void uv_unref(uv_handle_t*); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +These functions can be used to allow a loop to exit even when a watcher is +active or to use custom objects to keep the loop alive. +.sp +The latter can be used with interval timers. You might have a garbage collector +which runs every X seconds, or your network service might send a heartbeat to +others periodically, but you don\(aqt want to have to stop them along all clean +exit paths or error scenarios. Or you want the program to exit when all your +other watchers are done. In that case just unref the timer immediately after +creation so that if it is the only watcher running then \fBuv_run\fP will still +exit. +.sp +This is also used in node.js where some libuv methods are being bubbled up to +the JS API. A \fBuv_handle_t\fP (the superclass of all watchers) is created per +JS object and can be ref/unrefed. +.sp +ref\-timer/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t *loop; +uv_timer_t gc_req; +uv_timer_t fake_job_req; + +int main() { + loop = uv_default_loop(); + + uv_timer_init(loop, &gc_req); + uv_unref((uv_handle_t*) &gc_req); + + uv_timer_start(&gc_req, gc, 0, 2000); + + // could actually be a TCP download or something + uv_timer_init(loop, &fake_job_req); + uv_timer_start(&fake_job_req, fake_job, 9000, 0); + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We initialize the garbage collector timer, then immediately \fBunref\fP it. +Observe how after 9 seconds, when the fake job is done, the program +automatically exits, even though the garbage collector is still running. +.SS Idler pattern +.sp +The callbacks of idle handles are invoked once per event loop. The idle +callback can be used to perform some very low priority activity. For example, +you could dispatch a summary of the daily application performance to the +developers for analysis during periods of idleness, or use the application\(aqs +CPU time to perform SETI calculations :) An idle watcher is also useful in +a GUI application. Say you are using an event loop for a file download. If the +TCP socket is still being established and no other events are present your +event loop will pause (\fBblock\fP), which means your progress bar will freeze +and the user will face an unresponsive application. In such a case queue up and +idle watcher to keep the UI operational. +.sp +idle\-compute/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t *loop; +uv_fs_t stdin_watcher; +uv_idle_t idler; +char buffer[1024]; + +int main() { + loop = uv_default_loop(); + + uv_idle_init(loop, &idler); + + uv_buf_t buf = uv_buf_init(buffer, 1024); + uv_fs_read(loop, &stdin_watcher, 0, &buf, 1, \-1, on_type); + uv_idle_start(&idler, crunch_away); + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Here we initialize the idle watcher and queue it up along with the actual +events we are interested in. \fBcrunch_away\fP will now be called repeatedly +until the user types something and presses Return. Then it will be interrupted +for a brief amount as the loop deals with the input data, after which it will +keep calling the idle callback again. +.sp +idle\-compute/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void crunch_away(uv_idle_t* handle) { + // Compute extra\-terrestrial life + // fold proteins + // computer another digit of PI + // or similar + fprintf(stderr, "Computing PI...\en"); + // just to avoid overwhelming your terminal emulator + uv_idle_stop(handle); +} + + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Passing data to worker thread +.sp +When using \fBuv_queue_work\fP you\(aqll usually need to pass complex data through +to the worker thread. The solution is to use a \fBstruct\fP and set +\fBuv_work_t.data\fP to point to it. A slight variation is to have the +\fBuv_work_t\fP itself as the first member of this struct (called a baton [1]). +This allows cleaning up the work request and all the data in one free call. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +struct ftp_baton { + uv_work_t req; + char *host; + int port; + char *username; + char *password; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ftp_baton *baton = (ftp_baton*) malloc(sizeof(ftp_baton)); +baton\->req.data = (void*) baton; +baton\->host = strdup("my.webhost.com"); +baton\->port = 21; +// ... + +uv_queue_work(loop, &baton\->req, ftp_session, ftp_cleanup); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Here we create the baton and queue the task. +.sp +Now the task function can extract the data it needs: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void ftp_session(uv_work_t *req) { + ftp_baton *baton = (ftp_baton*) req\->data; + + fprintf(stderr, "Connecting to %s\en", baton\->host); +} + +void ftp_cleanup(uv_work_t *req) { + ftp_baton *baton = (ftp_baton*) req\->data; + + free(baton\->host); + // ... + free(baton); +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We then free the baton which also frees the watcher. +.SS External I/O with polling +.sp +Usually third\-party libraries will handle their own I/O, and keep track of +their sockets and other files internally. In this case it isn\(aqt possible to use +the standard stream I/O operations, but the library can still be integrated +into the libuv event loop. All that is required is that the library allow you +to access the underlying file descriptors and provide functions that process +tasks in small increments as decided by your application. Some libraries though +will not allow such access, providing only a standard blocking function which +will perform the entire I/O transaction and only then return. It is unwise to +use these in the event loop thread, use the threadpool instead. Of +course, this will also mean losing granular control on the library. +.sp +The \fBuv_poll\fP section of libuv simply watches file descriptors using the +operating system notification mechanism. In some sense, all the I/O operations +that libuv implements itself are also backed by \fBuv_poll\fP like code. Whenever +the OS notices a change of state in file descriptors being polled, libuv will +invoke the associated callback. +.sp +Here we will walk through a simple download manager that will use \fI\%libcurl\fP to +download files. Rather than give all control to libcurl, we\(aqll instead be +using the libuv event loop, and use the non\-blocking, async \fI\%multi\fP interface to +progress with the download whenever libuv notifies of I/O readiness. +.sp +uvwget/main.c \- The setup +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include +#include +#include +#include + +uv_loop_t *loop; +CURLM *curl_handle; +uv_timer_t timeout; +} + +int main(int argc, char **argv) { + loop = uv_default_loop(); + + if (argc <= 1) + return 0; + + if (curl_global_init(CURL_GLOBAL_ALL)) { + fprintf(stderr, "Could not init cURL\en"); + return 1; + } + + uv_timer_init(loop, &timeout); + + curl_handle = curl_multi_init(); + curl_multi_setopt(curl_handle, CURLMOPT_SOCKETFUNCTION, handle_socket); + curl_multi_setopt(curl_handle, CURLMOPT_TIMERFUNCTION, start_timeout); + + while (argc\-\- > 1) { + add_download(argv[argc], argc); + } + + uv_run(loop, UV_RUN_DEFAULT); + curl_multi_cleanup(curl_handle); + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The way each library is integrated with libuv will vary. In the case of +libcurl, we can register two callbacks. The socket callback \fBhandle_socket\fP +is invoked whenever the state of a socket changes and we have to start polling +it. \fBstart_timeout\fP is called by libcurl to notify us of the next timeout +interval, after which we should drive libcurl forward regardless of I/O status. +This is so that libcurl can handle errors or do whatever else is required to +get the download moving. +.sp +Our downloader is to be invoked as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ./uvwget [url1] [url2] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +So we add each argument as an URL +.sp +uvwget/main.c \- Adding urls +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void add_download(const char *url, int num) { + char filename[50]; + sprintf(filename, "%d.download", num); + FILE *file; + + file = fopen(filename, "w"); + if (file == NULL) { + fprintf(stderr, "Error opening %s\en", filename); + return; + } + + CURL *handle = curl_easy_init(); + curl_easy_setopt(handle, CURLOPT_WRITEDATA, file); + curl_easy_setopt(handle, CURLOPT_URL, url); + curl_multi_add_handle(curl_handle, handle); + fprintf(stderr, "Added download %s \-> %s\en", url, filename); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We let libcurl directly write the data to a file, but much more is possible if +you so desire. +.sp +\fBstart_timeout\fP will be called immediately the first time by libcurl, so +things are set in motion. This simply starts a libuv \fI\%timer\fP which +drives \fBcurl_multi_socket_action\fP with \fBCURL_SOCKET_TIMEOUT\fP whenever it +times out. \fBcurl_multi_socket_action\fP is what drives libcurl, and what we +call whenever sockets change state. But before we go into that, we need to poll +on sockets whenever \fBhandle_socket\fP is called. +.sp +uvwget/main.c \- Setting up polling +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + +void start_timeout(CURLM *multi, long timeout_ms, void *userp) { + if (timeout_ms <= 0) + timeout_ms = 1; /* 0 means directly call socket_action, but we\(aqll do it in a bit */ + uv_timer_start(&timeout, on_timeout, timeout_ms, 0); +} + +int handle_socket(CURL *easy, curl_socket_t s, int action, void *userp, void *socketp) { + curl_context_t *curl_context; + if (action == CURL_POLL_IN || action == CURL_POLL_OUT) { + if (socketp) { + curl_context = (curl_context_t*) socketp; + } + else { + curl_context = create_curl_context(s); + curl_multi_assign(curl_handle, s, (void *) curl_context); + } + } + + switch (action) { + case CURL_POLL_IN: + uv_poll_start(&curl_context\->poll_handle, UV_READABLE, curl_perform); + break; + case CURL_POLL_OUT: + uv_poll_start(&curl_context\->poll_handle, UV_WRITABLE, curl_perform); + break; + case CURL_POLL_REMOVE: + if (socketp) { + uv_poll_stop(&((curl_context_t*)socketp)\->poll_handle); + destroy_curl_context((curl_context_t*) socketp); + curl_multi_assign(curl_handle, s, NULL); + } + break; + default: + abort(); + } + + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +We are interested in the socket fd \fBs\fP, and the \fBaction\fP\&. For every socket +we create a \fBuv_poll_t\fP handle if it doesn\(aqt exist, and associate it with the +socket using \fBcurl_multi_assign\fP\&. This way \fBsocketp\fP points to it whenever +the callback is invoked. +.sp +In the case that the download is done or fails, libcurl requests removal of the +poll. So we stop and free the poll handle. +.sp +Depending on what events libcurl wishes to watch for, we start polling with +\fBUV_READABLE\fP or \fBUV_WRITABLE\fP\&. Now libuv will invoke the poll callback +whenever the socket is ready for reading or writing. Calling \fBuv_poll_start\fP +multiple times on the same handle is acceptable, it will just update the events +mask with the new value. \fBcurl_perform\fP is the crux of this program. +.sp +uvwget/main.c \- Driving libcurl. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void curl_perform(uv_poll_t *req, int status, int events) { + uv_timer_stop(&timeout); + int running_handles; + int flags = 0; + if (status < 0) flags = CURL_CSELECT_ERR; + if (!status && events & UV_READABLE) flags |= CURL_CSELECT_IN; + if (!status && events & UV_WRITABLE) flags |= CURL_CSELECT_OUT; + + curl_context_t *context; + + context = (curl_context_t*)req; + + curl_multi_socket_action(curl_handle, context\->sockfd, flags, &running_handles); + check_multi_info(); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The first thing we do is to stop the timer, since there has been some progress +in the interval. Then depending on what event triggered the callback, we set +the correct flags. Then we call \fBcurl_multi_socket_action\fP with the socket +that progressed and the flags informing about what events happened. At this +point libcurl does all of its internal tasks in small increments, and will +attempt to return as fast as possible, which is exactly what an evented program +wants in its main thread. libcurl keeps queueing messages into its own queue +about transfer progress. In our case we are only interested in transfers that +are completed. So we extract these messages, and clean up handles whose +transfers are done. +.sp +uvwget/main.c \- Reading transfer status. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void check_multi_info(void) { + char *done_url; + CURLMsg *message; + int pending; + + while ((message = curl_multi_info_read(curl_handle, &pending))) { + switch (message\->msg) { + case CURLMSG_DONE: + curl_easy_getinfo(message\->easy_handle, CURLINFO_EFFECTIVE_URL, + &done_url); + printf("%s DONE\en", done_url); + + curl_multi_remove_handle(curl_handle, message\->easy_handle); + curl_easy_cleanup(message\->easy_handle); + break; + + default: + fprintf(stderr, "CURLMSG default\en"); + abort(); + } + } +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Check & Prepare watchers +.sp +TODO +.SS Loading libraries +.sp +libuv provides a cross platform API to dynamically load \fI\%shared libraries\fP\&. +This can be used to implement your own plugin/extension/module system and is +used by node.js to implement \fBrequire()\fP support for bindings. The usage is +quite simple as long as your library exports the right symbols. Be careful with +sanity and security checks when loading third party code, otherwise your +program will behave unpredictably. This example implements a very simple +plugin system which does nothing except print the name of the plugin. +.sp +Let us first look at the interface provided to plugin authors. +.sp +plugin/plugin.h +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#ifndef UVBOOK_PLUGIN_SYSTEM +#define UVBOOK_PLUGIN_SYSTEM + +// Plugin authors should use this to register their plugins with mfp. +void mfp_register(const char *name); + +#endif + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can similarly add more functions that plugin authors can use to do useful +things in your application [2]\&. A sample plugin using this API is: +.sp +plugin/hello.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include "plugin.h" + +void initialize() { + mfp_register("Hello World!"); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Our interface defines that all plugins should have an \fBinitialize\fP function +which will be called by the application. This plugin is compiled as a shared +library and can be loaded by running our application: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ./plugin libhello.dylib +Loading libhello.dylib +Registered plugin "Hello World!" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The shared library filename will be different depending on platforms. On +Linux it is \fBlibhello.so\fP\&. +.UNINDENT +.UNINDENT +.sp +This is done by using \fBuv_dlopen\fP to first load the shared library +\fBlibhello.dylib\fP\&. Then we get access to the \fBinitialize\fP function using +\fBuv_dlsym\fP and invoke it. +.sp +plugin/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include "plugin.h" + +typedef void (*init_plugin_function)(); + +void mfp_register(const char *name) { + fprintf(stderr, "Registered plugin \e"%s\e"\en", name); +} + +int main(int argc, char **argv) { + if (argc == 1) { + fprintf(stderr, "Usage: %s [plugin1] [plugin2] ...\en", argv[0]); + return 0; + } + + uv_lib_t *lib = (uv_lib_t*) malloc(sizeof(uv_lib_t)); + while (\-\-argc) { + fprintf(stderr, "Loading %s\en", argv[argc]); + if (uv_dlopen(argv[argc], lib)) { + fprintf(stderr, "Error: %s\en", uv_dlerror(lib)); + continue; + } + + init_plugin_function init_plugin; + if (uv_dlsym(lib, "initialize", (void **) &init_plugin)) { + fprintf(stderr, "dlsym error: %s\en", uv_dlerror(lib)); + continue; + } + + init_plugin(); + } + + return 0; +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBuv_dlopen\fP expects a path to the shared library and sets the opaque +\fBuv_lib_t\fP pointer. It returns 0 on success, \-1 on error. Use \fBuv_dlerror\fP +to get the error message. +.sp +\fBuv_dlsym\fP stores a pointer to the symbol in the second argument in the third +argument. \fBinit_plugin_function\fP is a function pointer to the sort of +function we are looking for in the application\(aqs plugins. +.SS TTY +.sp +Text terminals have supported basic formatting for a long time, with a \fI\%pretty +standardised\fP command set. This formatting is often used by programs to +improve the readability of terminal output. For example \fBgrep \-\-colour\fP\&. +libuv provides the \fBuv_tty_t\fP abstraction (a stream) and related functions to +implement the ANSI escape codes across all platforms. By this I mean that libuv +converts ANSI codes to the Windows equivalent, and provides functions to get +terminal information. +.sp +The first thing to do is to initialize a \fBuv_tty_t\fP with the file descriptor +it reads/writes from. This is achieved with: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int uv_tty_init(uv_loop_t*, uv_tty_t*, uv_file fd, int unused) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBunused\fP parameter is now auto\-detected and ignored. It previously needed +to be set to use \fBuv_read_start()\fP on the stream. +.sp +It is then best to use \fBuv_tty_set_mode\fP to set the mode to \fInormal\fP +which enables most TTY formatting, flow\-control and other settings. \fI\%Other\fP modes +are also available. +.sp +Remember to call \fBuv_tty_reset_mode\fP when your program exits to restore the +state of the terminal. Just good manners. Another set of good manners is to be +aware of redirection. If the user redirects the output of your command to +a file, control sequences should not be written as they impede readability and +\fBgrep\fP\&. To check if the file descriptor is indeed a TTY, call +\fBuv_guess_handle\fP with the file descriptor and compare the return value with +\fBUV_TTY\fP\&. +.sp +Here is a simple example which prints white text on a red background: +.sp +tty/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include +#include +#include + +uv_loop_t *loop; +uv_tty_t tty; +int main() { + loop = uv_default_loop(); + + uv_tty_init(loop, &tty, STDOUT_FILENO, 0); + uv_tty_set_mode(&tty, UV_TTY_MODE_NORMAL); + + if (uv_guess_handle(1) == UV_TTY) { + uv_write_t req; + uv_buf_t buf; + buf.base = "\e033[41;37m"; + buf.len = strlen(buf.base); + uv_write(&req, (uv_stream_t*) &tty, &buf, 1, NULL); + } + + uv_write_t req; + uv_buf_t buf; + buf.base = "Hello TTY\en"; + buf.len = strlen(buf.base); + uv_write(&req, (uv_stream_t*) &tty, &buf, 1, NULL); + uv_tty_reset_mode(); + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The final TTY helper is \fBuv_tty_get_winsize()\fP which is used to get the +width and height of the terminal and returns \fB0\fP on success. Here is a small +program which does some animation using the function and character position +escape codes. +.sp +tty\-gravity/main.c +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#include +#include +#include +#include + +uv_loop_t *loop; +uv_tty_t tty; +uv_timer_t tick; +uv_write_t write_req; +int width, height; +int pos = 0; +char *message = " Hello TTY "; + +void update(uv_timer_t *req) { + char data[500]; + + uv_buf_t buf; + buf.base = data; + buf.len = sprintf(data, "\e033[2J\e033[H\e033[%dB\e033[%luC\e033[42;37m%s", + pos, + (unsigned long) (width\-strlen(message))/2, + message); + uv_write(&write_req, (uv_stream_t*) &tty, &buf, 1, NULL); + + pos++; + if (pos > height) { + uv_tty_reset_mode(); + uv_timer_stop(&tick); + } +} + +int main() { + loop = uv_default_loop(); + + uv_tty_init(loop, &tty, STDOUT_FILENO, 0); + uv_tty_set_mode(&tty, 0); + + if (uv_tty_get_winsize(&tty, &width, &height)) { + fprintf(stderr, "Could not get TTY information\en"); + uv_tty_reset_mode(); + return 1; + } + + fprintf(stderr, "Width %d, height %d\en", width, height); + uv_timer_init(loop, &tick); + uv_timer_start(&tick, update, 200, 200); + return uv_run(loop, UV_RUN_DEFAULT); +} + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The escape codes are: +.TS +center; +|l|l|. +_ +T{ +Code +T} T{ +Meaning +T} +_ +T{ +\fI2\fP J +T} T{ +Clear part of the screen, 2 is entire screen +T} +_ +T{ +H +T} T{ +Moves cursor to certain position, default top\-left +T} +_ +T{ +\fIn\fP B +T} T{ +Moves cursor down by n lines +T} +_ +T{ +\fIn\fP C +T} T{ +Moves cursor right by n columns +T} +_ +T{ +m +T} T{ +Obeys string of display settings, in this case green background (40+2), white text (30+7) +T} +_ +.TE +.sp +As you can see this is very useful to produce nicely formatted output, or even +console based arcade games if that tickles your fancy. For fancier control you +can try \fI\%ncurses\fP\&. +.sp +Changed in version 1.23.1:: the \fIreadable\fP parameter is now unused and ignored. +The appropriate value will now be auto\-detected from the kernel. + + +.sp +.ce +---- + +.ce 0 +.sp +.IP [1] 5 +I was first introduced to the term baton in this context, in Konstantin +Käfer\(aqs excellent slides on writing node.js bindings \-\- +\fI\%https://kkaefer.com/node\-cpp\-modules/#baton\fP +.IP [2] 5 +mfp is My Fancy Plugin +.SS About +.sp +\fI\%Nikhil Marathe\fP started writing this book one +afternoon (June 16, 2012) when he didn\(aqt feel like programming. He had recently +been stung by the lack of good documentation on libuv while working on +\fI\%node\-taglib\fP\&. Although reference +documentation was present, there were no comprehensive tutorials. This book is +the output of that need and tries to be accurate. That said, the book may have +mistakes. Pull requests are encouraged. +.sp +Nikhil is indebted to Marc Lehmann\(aqs comprehensive \fI\%man page\fP about libev which +describes much of the semantics of the two libraries. +.sp +This book was made using \fI\%Sphinx\fP and \fI\%vim\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In 2017 the libuv project incorporated the Nikhil\(aqs work into the official +documentation and it\(aqs maintained there henceforth. +.UNINDENT +.UNINDENT +.SS Upgrading +.sp +Migration guides for different libuv versions, starting with 1.0. +.SS libuv 0.10 \-> 1.0.0 migration guide +.sp +Some APIs changed quite a bit throughout the 1.0.0 development process. Here +is a migration guide for the most significant changes that happened after 0.10 +was released. +.SS Loop initialization and closing +.sp +In libuv 0.10 (and previous versions), loops were created with \fIuv_loop_new\fP, which +allocated memory for a new loop and initialized it; and destroyed with \fIuv_loop_delete\fP, +which destroyed the loop and freed the memory. Starting with 1.0, those are deprecated +and the user is responsible for allocating the memory and then initializing the loop. +.sp +libuv 0.10 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t* loop = uv_loop_new(); +\&... +uv_loop_delete(loop); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +libuv 1.0 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_loop_t* loop = malloc(sizeof *loop); +uv_loop_init(loop); +\&... +uv_loop_close(loop); +free(loop); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Error handling was omitted for brevity. Check the documentation for \fBuv_loop_init()\fP +and \fBuv_loop_close()\fP\&. +.UNINDENT +.UNINDENT +.SS Error handling +.sp +Error handling had a major overhaul in libuv 1.0. In general, functions and status parameters +would get 0 for success and \-1 for failure on libuv 0.10, and the user had to use \fIuv_last_error\fP +to fetch the error code, which was a positive number. +.sp +In 1.0, functions and status parameters contain the actual error code, which is 0 for success, or +a negative number in case of error. +.sp +libuv 0.10 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\&... assume \(aqserver\(aq is a TCP server which is already listening +r = uv_listen((uv_stream_t*) server, 511, NULL); +if (r == \-1) { + uv_err_t err = uv_last_error(uv_default_loop()); + /* err.code contains UV_EADDRINUSE */ +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +libuv 1.0 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\&... assume \(aqserver\(aq is a TCP server which is already listening +r = uv_listen((uv_stream_t*) server, 511, NULL); +if (r < 0) { + /* r contains UV_EADDRINUSE */ +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Threadpool changes +.sp +In libuv 0.10 Unix used a threadpool which defaulted to 4 threads, while Windows used the +\fIQueueUserWorkItem\fP API, which uses a Windows internal threadpool, which defaults to 512 +threads per process. +.sp +In 1.0, we unified both implementations, so Windows now uses the same implementation Unix +does. The threadpool size can be set by exporting the \fBUV_THREADPOOL_SIZE\fP environment +variable. See threadpool\&. +.SS Allocation callback API change +.sp +In libuv 0.10 the callback had to return a filled \fBuv_buf_t\fP by value: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uv_buf_t alloc_cb(uv_handle_t* handle, size_t size) { + return uv_buf_init(malloc(size), size); +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In libuv 1.0 a pointer to a buffer is passed to the callback, which the user +needs to fill: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void alloc_cb(uv_handle_t* handle, size_t size, uv_buf_t* buf) { + buf\->base = malloc(size); + buf\->len = size; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Unification of IPv4 / IPv6 APIs +.sp +libuv 1.0 unified the IPv4 and IPv6 APIS. There is no longer a \fIuv_tcp_bind\fP and \fIuv_tcp_bind6\fP +duality, there is only \fBuv_tcp_bind()\fP now. +.sp +IPv4 functions took \fBstruct sockaddr_in\fP structures by value, and IPv6 functions took +\fBstruct sockaddr_in6\fP\&. Now functions take a \fBstruct sockaddr*\fP (note it\(aqs a pointer). +It can be stack allocated. +.sp +libuv 0.10 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +struct sockaddr_in addr = uv_ip4_addr("0.0.0.0", 1234); +\&... +uv_tcp_bind(&server, addr) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +libuv 1.0 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +struct sockaddr_in addr; +uv_ip4_addr("0.0.0.0", 1234, &addr) +\&... +uv_tcp_bind(&server, (const struct sockaddr*) &addr, 0); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The IPv4 and IPv6 struct creating functions (\fBuv_ip4_addr()\fP and \fBuv_ip6_addr()\fP) +have also changed, make sure you check the documentation. +.INDENT 0.0 +.TP +.B \&..note:: +This change applies to all functions that made a distinction between IPv4 and IPv6 +addresses. +.UNINDENT +.SS Streams / UDP data receive callback API change +.sp +The streams and UDP data receive callbacks now get a pointer to a \fBuv_buf_t\fP buffer, +not a structure by value. +.sp +libuv 0.10 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_stream_t* handle, + ssize_t nread, + uv_buf_t buf) { + ... +} + +void recv_cb(uv_udp_t* handle, + ssize_t nread, + uv_buf_t buf, + struct sockaddr* addr, + unsigned flags) { + ... +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +libuv 1.0 +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_stream_t* handle, + ssize_t nread, + const uv_buf_t* buf) { + ... +} + +void recv_cb(uv_udp_t* handle, + ssize_t nread, + const uv_buf_t* buf, + const struct sockaddr* addr, + unsigned flags) { + ... +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Receiving handles over pipes API change +.sp +In libuv 0.10 (and earlier versions) the \fIuv_read2_start\fP function was used to start reading +data on a pipe, which could also result in the reception of handles over it. The callback +for such function looked like this: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_pipe_t* pipe, + ssize_t nread, + uv_buf_t buf, + uv_handle_type pending) { + ... +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In libuv 1.0, \fIuv_read2_start\fP was removed, and the user needs to check if there are pending +handles using \fBuv_pipe_pending_count()\fP and \fBuv_pipe_pending_type()\fP while in +the read callback: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +void on_read(uv_stream_t* handle, + ssize_t nread, + const uv_buf_t* buf) { + ... + while (uv_pipe_pending_count((uv_pipe_t*) handle) != 0) { + pending = uv_pipe_pending_type((uv_pipe_t*) handle); + ... + } + ... +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Extracting the file descriptor out of a handle +.sp +While it wasn\(aqt supported by the API, users often accessed the libuv internals in +order to get access to the file descriptor of a TCP handle, for example. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +fd = handle\->io_watcher.fd; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This is now properly exposed through the \fBuv_fileno()\fP function. +.SS uv_fs_readdir rename and API change +.sp +\fIuv_fs_readdir\fP returned a list of strings in the \fIreq\->ptr\fP field upon completion in +libuv 0.10. In 1.0, this function got renamed to \fBuv_fs_scandir()\fP, since it\(aqs +actually implemented using \fBscandir(3)\fP\&. +.sp +In addition, instead of allocating a full list strings, the user is able to get one +result at a time by using the \fBuv_fs_scandir_next()\fP function. This function +does not need to make a roundtrip to the threadpool, because libuv will keep the +list of \fIdents\fP returned by \fBscandir(3)\fP around. +.SH DOWNLOADS +.sp +libuv can be downloaded from \fI\%here\fP\&. +.SH INSTALLATION +.sp +Installation instructions can be found in \fI\%the README\fP\&. +.SH AUTHOR +libuv contributors +.SH COPYRIGHT +2014-present, libuv contributors +.\" Generated by docutils manpage writer. +. diff --git a/static/netbsd/man3/linkaddr.3 b/static/netbsd/man3/linkaddr.3 new file mode 100644 index 00000000..c83d3109 --- /dev/null +++ b/static/netbsd/man3/linkaddr.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: linkaddr.3,v 1.13 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley at BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)linkaddr.3 8.1 (Berkeley) 7/28/93 +.\" +.Dd December 7, 2016 +.Dt LINK_ADDR 3 +.Os +.Sh NAME +.Nm link_addr , +.Nm link_ntoa +.Nd elementary address specification routines for link level access +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if_dl.h +.Ft void +.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl" +.Ft char * +.Fn link_ntoa "const struct sockaddr_dl *sdl" +.Sh DESCRIPTION +The routine +.Fn link_addr +interprets character strings representing link-level addresses, +returning binary information suitable for use in system calls. +The routine +.Fn link_ntoa +takes a link-level address and returns an +.Tn ASCII +string representing some of the information present, including the +link level address itself, and the interface name or number, if present. +This facility is experimental and is still subject to change. +.Pp +Prior to a call to +.Fn link_addr , +.Fa sdl->sdl_len +must be initialized to the size of the link-level socket structure, +typically +.Fa sizeof(struct sockaddr_dl) . +.Pp +For +.Fn link_addr , +the string +.Fa addr +may contain +an optional network interface identifier of the form +.Dq "name unit-number" , +suitable for the first argument to +.Xr ifconfig 8 , +followed in all cases by a colon and +an interface address in the form of +groups of hexadecimal digits +separated by periods. +Each group represents a byte of address; +address bytes are filled left to right from +low order bytes through high order bytes. +.Pp +.\" A regular expression may make this format clearer: +.\" .Bd -literal -offset indent +.\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)* +.\" .Ed +.\" .Pp +Thus +.Li le0:8.0.9.13.d.30 +represents an ethernet address +to be transmitted on the first Lance ethernet interface. +.Sh RETURN VALUES +.Fn link_ntoa +always returns a null terminated string. +.Fn link_addr +has no return value (See +.Sx BUGS ) . +.Sh SEE ALSO +.Xr ethers 3 , +.Xr iso 4 +.Sh HISTORY +The +.Fn link_addr +and +.Fn link_ntoa +functions appeared in +.Bx 4.3 Reno . +.Sh BUGS +The returned string for +.Fn link_ntoa +resides in a static memory area. +If it would overflow this area, +.Fn link_ntoa +silently truncates the result. +.Pp +The function +.Fn link_addr +should diagnose improperly formed input, and there should be an unambiguous +way to recognize this. +.Pp +If the +.Va sdl_len +field of the link socket address +.Fa sdl +is 0, +.Fn link_ntoa +will not insert a colon before the interface address bytes. +If this translated address is given to +.Fn link_addr +without inserting an initial colon, +the latter will not interpret it correctly. diff --git a/static/netbsd/man3/lio_listio.3 b/static/netbsd/man3/lio_listio.3 new file mode 100644 index 00000000..74dc18f6 --- /dev/null +++ b/static/netbsd/man3/lio_listio.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: lio_listio.3,v 1.5 2011/08/12 23:40:43 wiz Exp $ +.\" +.\" Copyright (c) 2003 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/lio_listio.2,v 1.6 2006/10/07 05:13:32 trhodes Exp $ +.\" +.Dd August 12, 2011 +.Dt LIO_LISTIO 3 +.Os +.Sh NAME +.Nm lio_listio +.Nd list directed I/O (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fo lio_listio +.Fa "int mode" +.Fa "struct aiocb * const list[]" +.Fa "int nent" +.Fa "struct sigevent *sig" +.Fc +.Sh DESCRIPTION +The +.Fn lio_listio +function initiates a list of I/O requests with a single function call. +The +.Fa list +argument is an array of pointers to +.Vt aiocb +structures describing each operation to perform, +with +.Fa nent +elements. +.Dv NULL +elements are ignored. +.Pp +The +.Va aio_lio_opcode +field of each +.Vt aiocb +specifies the operation to be performed. +The following operations are supported: +.Bl -tag -width ".Dv LIO_WRITE" -offset indent +.It Dv LIO_READ +Read data as if by a call to +.Xr aio_read 3 . +.It Dv LIO_NOP +No operation. +.It Dv LIO_WRITE +Write data as if by a call to +.Xr aio_write 3 . +.El +.Pp +If the +.Fa mode +argument is +.Dv LIO_WAIT , +.Fn lio_listio +does not return until all the requested operations have been completed. +If +.Fa mode +is +.Dv LIO_NOWAIT , +the requests are processed asynchronously, and the signal specified by +.Fa sig +is sent when all operations have completed. +If +.Fa sig +is +.Dv NULL , +the calling process is not notified of I/O completion. +.Pp +The order in which the requests are carried out is not specified, +and there is no guarantee that they will be executed sequentially. +.Sh RETURN VALUES +If +.Fa mode +is +.Dv LIO_WAIT , +the +.Fn lio_listio +function returns 0 if the operations completed successfully, +otherwise \-1. +.Pp +If +.Fa mode +is +.Dv LIO_NOWAIT , +the +.Fn lio_listio +function returns 0 if the operations are successfully queued, +otherwise \-1. +.Sh ERRORS +The +.Fn lio_listio +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +There are not enough resources to enqueue the requests; or +the request would cause the system-wide limit +.Dv AIO_MAX +to be exceeded. +.It Bq Er EINTR +A signal interrupted the system call before it could be completed. +.It Bq Er EINVAL +The +.Fa mode +argument is neither +.Dv LIO_WAIT +nor +.Dv LIO_NOWAIT , +or +.Fa nent +is greater than +.Dv AIO_LISTIO_MAX . +.It Bq Er EIO +One or more requests failed. +.El +.Pp +In addition, the +.Fn lio_listio +function may fail for any of the reasons listed for +.Xr aio_read 3 +and +.Xr aio_write 3 . +.Pp +If +.Fn lio_listio +succeeds, or fails with an error code of +.Er EAGAIN , EINTR , +or +.Er EIO , +some of the requests may have been initiated. +The caller should check the error status of each +.Vt aiocb +structure individually by calling +.Xr aio_error 3 . +.Sh SEE ALSO +.Xr read 2 , +.Xr siginfo 2 , +.Xr write 2 , +.Xr aio 3 , +.Xr sigevent 3 +.Sh STANDARDS +The +.Fn lio_listio +function is expected to conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/lockf.3 b/static/netbsd/man3/lockf.3 new file mode 100644 index 00000000..8a071668 --- /dev/null +++ b/static/netbsd/man3/lockf.3 @@ -0,0 +1,262 @@ +.\" $NetBSD: lockf.3,v 1.12 2011/10/15 21:35:49 rmind Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein and S.P. Zeidler. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 15, 2011 +.Dt LOCKF 3 +.Os +.Sh NAME +.Nm lockf +.Nd record locking on files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn lockf "int filedes" "int function" "off_t size" +.Sh DESCRIPTION +The +.Fn lockf +function allows sections of a file to be locked with advisory-mode locks. +Calls to +.Fn lockf +from other processes which attempt to lock the locked file section will +either return an error value or block until the section becomes unlocked. +All the locks for a process are removed when the process terminates. +.Pp +The argument +.Fa filedes +is an open file descriptor. +The file descriptor must have been opened either for write-only +.Dv ( O_WRONLY ) +or read/write +.Dv ( O_RDWR ) +operation. +.Pp +The +.Fa function +argument is a control value which specifies the action to be taken. +The permissible values for +.Fa function +are as follows: +.Pp +.Bl -tag -width F_ULOCKXX -compact -offset indent +.It Sy Function +.Sy Description +.It Dv F_ULOCK +unlock locked sections +.It Dv F_LOCK +lock a section for exclusive use +.It Dv F_TLOCK +test and lock a section for exclusive use +.It Dv F_TEST +test a section for locks by other processes +.El +.Pp +.Dv F_ULOCK +removes locks from a section of the file; +.Dv F_LOCK +and +.Dv F_TLOCK +both lock a section of a file if the section is available; +.Dv F_TEST +detects if a lock by another process is present on the specified section. +.Pp +The +.Fa size +argument is the number of contiguous bytes to be locked or +unlocked. +The section to be locked or unlocked starts at the current +offset in the file and extends forward for a positive size or backward +for a negative size (the preceding bytes up to but not including the +current offset). +However, it is not permitted to lock a section that +starts or extends before the beginning of the file. +If +.Fa size +is 0, the section from the current offset through the largest possible +file offset is locked (that is, from the current offset through the +present or any future end-of-file). +.Pp +The sections locked with +.Dv F_LOCK +or +.Dv F_TLOCK +may, in whole or in part, contain or be contained by a previously +locked section for the same process. +When this occurs, or if adjacent +locked sections would occur, the sections are combined into a single +locked section. +If the request would cause the number of locks to +exceed a system-imposed limit, the request will fail. +.Pp +.Dv F_LOCK +and +.Dv F_TLOCK +requests differ only by the action taken if the section is not +available. +.Dv F_LOCK +blocks the calling process until the section is available. +.Dv F_TLOCK +makes the function fail if the section is already locked by another +process. +.Pp +File locks are released on first close by the locking process of any +file descriptor for the file. +.Pp +.Dv F_ULOCK +requests release (wholly or in part) one or more locked sections +controlled by the process. +Locked sections will be unlocked starting +at the current file offset through +.Fa size +bytes or to the end of file if size is 0. +When all of a locked section +is not released (that is, when the beginning or end of the area to be +unlocked falls within a locked section), the remaining portions of +that section are still locked by the process. +Releasing the center +portion of a locked section will cause the remaining locked beginning +and end portions to become two separate locked sections. +If the +request would cause the number of locks in the system to exceed a +system-imposed limit, the request will fail. +.Pp +An +.Dv F_ULOCK +request in which size is non-zero and the offset of the last byte of +the requested section is the maximum value for an object of type +off_t, when the process has an existing lock in which size is 0 and +which includes the last byte of the requested section, will be treated +as a request to unlock from the start of the requested section with a +size equal to 0. +Otherwise an +.Dv F_ULOCK +request will attempt to unlock only the requested section. +.Pp +A potential for deadlock occurs if a process controlling a locked +region is put to sleep by attempting to lock the locked region of +another process. +This implementation detects that sleeping until a +locked region is unlocked would cause a deadlock and fails with an +.Er EDEADLK +error. +.Pp +.Fn lockf , +.Xr fcntl 2 +and +.Xr flock 2 +locks may be safely used concurrently. +.Pp +Blocking on a section is interrupted by any signal. +.Sh RETURN VALUES +If successful, the +.Fn lockf +function returns 0. +Otherwise, it returns \-1, sets +.Va errno +to indicate an error, and existing locks are not changed. +.Sh ERRORS +.Fn lockf +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The argument +.Fa function +is +.Dv F_TLOCK +or +.Dv F_TEST +and the section is already locked by another process. +.It Bq Er EBADF +The argument +.Fa filedes +is not a valid open file descriptor. +.Pp +The argument +.Fa function +is +.Dv F_LOCK +or +.Dv F_TLOCK , +and +.Fa filedes +is not a valid file descriptor open for writing. +.It Bq Er EDEADLK +The argument +.Fa function +is +.Dv F_LOCK +and a deadlock is detected. +.It Bq Er EINTR +The argument +.Fa function +is F_LOCK +and +.Fn lockf +was interrupted by the delivery of a signal. +.It Bq Er EINVAL +The argument +.Fa function +is not one of +.Dv F_ULOCK , +.Dv F_LOCK , +.Dv F_TLOCK +or +.Dv F_TEST . +.Pp +The argument +.Fa filedes +refers to a file that does not support locking. +.It Bq Er ENOLCK +The argument +.Fa function +is +.Dv F_ULOCK , +.Dv F_LOCK +or +.Dv F_TLOCK , +and satisfying the lock or unlock request would result in the number +of locked regions in the system exceeding a system-imposed limit. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr flock 2 , +.Xr flockfile 3 +.Sh STANDARDS +The +.Fn lockf +function conforms to +.St -xpg4.2 +and +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn lockf +function first appeared in +.Fx 1.4 . diff --git a/static/netbsd/man3/log.3 b/static/netbsd/man3/log.3 new file mode 100644 index 00000000..8a83fa0b --- /dev/null +++ b/static/netbsd/man3/log.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: log.3,v 1.8 2024/01/26 19:27:30 nros Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 24, 2024 +.Dt LOG 3 +.Os +.Sh NAME +.Nm log , +.Nm logf , +.Nm logl , +.Nm log10 , +.Nm log10f , +.Nm log10l , +.Nm log1p , +.Nm log1pf , +.Nm log1pl , +.Nm log2 , +.Nm log2f +.Nm log2l +.Nd logarithm functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn log "double x" +.Ft float +.Fn logf "float x" +.Ft long double +.Fn logl "long double x" +.Ft double +.Fn log10 "double x" +.Ft float +.Fn log10f "float x" +.Ft log double +.Fn log10l "long double x" +.Ft double +.Fn log1p "double x" +.Ft float +.Fn log1pf "float x" +.Ft long double +.Fn log1pl "long double x" +.Ft double +.Fn log2 "double x" +.Ft float +.Fn log2f "float x" +.Ft long double +.Fn log2l "long double x" +.Sh DESCRIPTION +The following functions compute logarithms: +.Bl -bullet -offset 2n +.It +The +.Fn log , +.Fn logf +and +.Fn logl +functions return the natural logarithm. +.It +The +.Fn log10 , +.Fn log10f +and +.Fn log10l +functions return the base 10 logarithm. +.It +The +.Fn log1p , +.Fn log1pf +and +.Fn log1pl +functions return the natural logarithm of (1.0 + +.Fa x ) +accurately even for very small values of +.Fa x . +.It +The +.Fn log2 , +.Fn log2f +and +.Fn log2l +functions return the base 2 logarithm. +.El +.Sh RETURN VALUES +Upon successful completion, the functions return the logarithm of +.Fa x +as described above. +Otherwise the following may occur: +.Bl -enum -offset indent +.It +If +.Fa x +is \*(Na, all functions return \*(Na. +.It +If +.Fa x +is positive infinity, all functions return +.Fa x . +If +.Fa x +is negative infinity, all functions return \*(Na. +.It +If +.Fa x +is +0.0 or -0.0, the +.Fn log , +.Fn log10 , +and +.Fn log2 +families return either +.Dv -HUGE_VAL , +.Dv -HUGE_VALF , +or +.Dv -HUGE_VALL , +whereas the +.Fn log1p +family returns +.Fa x . +.It +If +.Fa x +is +1.0, the +.Fn log , +.Fn log10 , +and +.Fn log2 +families return +0.0. +If +.Fa x +is -1.0, the +.Fn log1p +family returns +.Dv -HUGE_VAL , +.Dv -HUGE_VALF , +or +.Dv -HUGE_VALL . +.El +.Pp +In addition, on a +.Tn VAX , +.Va errno +is set to +.Er EDOM +and the reserved operand is returned +by +.Fn log +unless +.Fa x +> 0, by +.Fn log1p +unless +.Fa x +> \-1. +.Sh SEE ALSO +.Xr exp 3 , +.Xr ilogb 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . +.Sh HISTORY +A +.Fn log +function appeared in +.At v1 . diff --git a/static/netbsd/man3/login.3 b/static/netbsd/man3/login.3 new file mode 100644 index 00000000..0bcd42e1 --- /dev/null +++ b/static/netbsd/man3/login.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: login.3,v 1.6 2003/08/07 16:44:58 agc Exp $ +.\" +.\" Copyright (c) 1995 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 14, 1995 +.Dt LOGIN 3 +.Os +.Sh NAME +.Nm login , +.Nm logout , +.Nm logwtmp +.Nd login utility functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft void +.Fn login "struct utmp *ut" +.Ft int +.Fn logout "const char *line" +.Ft void +.Fn logwtmp "const char *line" "const char *name" "const char *host" +.Sh DESCRIPTION +The +.Fn login , +.Fn logout , +and +.Fn logwtmp +functions operate on the database of current users in +.Pa /var/run/utmp +and on the logfile +.Pa /var/log/wtmp +of logins and logouts. +.Pp +The +.Fn login +function updates the +.Pa /var/run/utmp +and +.Pa /var/log/wtmp +files with user information contained in +.Fa ut . +.Pp +The +.Fn logout +function removes the entry from +.Pa /var/run/utmp +corresponding to the device +.Fa line . +.Pp +The +.Fn logwtmp +function adds an entry to +.Pa /var/log/wtmp . +Since +.Fn login +will add the appropriate entry for +.Pa /var/log/wtmp +during a login, +.Fn logwtmp +is usually used for logouts. +.Sh RETURN VALUES +.Fn logout +returns non-zero if it was able to find and delete an entry for +.Fa line , +and zero if there is no entry for +.Fa line +in +.Pa /var/run/utmp . +.Sh FILES +.Bl -tag -width /var/run/wtmp -compact +.It Pa /dev/\(** +.It Pa /etc/ttys +.It Pa /var/run/utmp +.It Pa /var/log/wtmp +.El +.Sh SEE ALSO +.Xr utmp 5 diff --git a/static/netbsd/man3/login_cap.3 b/static/netbsd/man3/login_cap.3 new file mode 100644 index 00000000..3b756dd5 --- /dev/null +++ b/static/netbsd/man3/login_cap.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: login_cap.3,v 1.24 2022/12/04 22:51:43 uwe Exp $ +.\" +.\" Copyright (c) 1996,1997 Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Berkeley Software Design, +.\" Inc. +.\" 4. The name of Berkeley Software Design, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" BSDI login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp +.\" +.Dd June 20, 2013 +.Dt LOGIN_CAP 3 +.Os +.Sh NAME +.Nm login_getclass , +.Nm login_getcapbool , +.Nm login_getcapnum , +.Nm login_getcapsize , +.Nm login_getcapstr , +.Nm login_getcaptime , +.Nm login_getpwclass , +.Nm login_close , +.Nm setclasscontext , +.Nm setusercontext +.Nd query login.conf database about a user class +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In sys/types.h +.In login_cap.h +.Ft login_cap_t * +.Fn login_getclass "char *class" +.Ft int +.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "unsigned int def" +.Ft quad_t +.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" +.Ft quad_t +.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" +.Ft char * +.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *err" +.Ft quad_t +.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" +.Ft login_cap_t * +.Fn login_getpwclass "struct passwd *pwd" +.Ft void +.Fn login_close "login_cap_t *lc" +.Ft int +.Fn setclasscontext "const char *class" "unsigned int flags" +.Ft int +.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags" +.Sh DESCRIPTION +The +.Fn login_getclass +function extracts the entry specified by +.Fa class +(or +.Ql default +if +.Fa class +is +.Dv NULL +or the empty string) +from +.Pa /etc/login.conf +.Po +see +.Xr login.conf 5 +.Pc . +If the entry is found, a +.Vt login_cap_t +pointer is returned. +.Dv NULL +is returned if the user class is not found. +When the +.Vt login_cap_t +structure is no longer needed, it should be freed by the +.Fn login_close +function. +.Pp +The +.Fn login_getpwclass +function is equivalent to: +.Pp +.Dl login_getclass(pwd\ ? pwd->pw_class\ : NULL) +.Pp +Once +.Fa lc +has been returned by +.Fn login_getclass , +any of the other +.Fn login_* +functions may be called. +.Pp +The +.Fn login_getcapnum , +.Fn login_getcapsize , +.Fn login_getcapstr , +and +.Fn login_getcaptime +functions all query the database entry for a field named +.Fa cap . +If the field is found, its value is returned. +If the field is not found, the value specified by +.Fa def +is returned. +If an error is encountered while trying to find the field, +.Fa err +is returned. +See +.Xr login.conf 5 +for a discussion of the various textual forms the value may take. +The +.Fn login_getcapbool +function is slightly different. +It returns +.Fa def +if no capabilities were found for this class +.Po +typically meaning that +the default class was used and the +.Pa /etc/login.conf +file is missing +.Pc . +It returns a non-zero value if +.Fa cap , +with no value, was found, +zero otherwise. +.Pp +The +.Fn setclasscontext +function takes +.Fa class , +the name of a user class, +and sets the resources defined by that class according to +.Fa flags . +Only the +.Dv LOGIN_SETPATH , +.Dv LOGIN_SETPRIORITY , +.Dv LOGIN_SETRESOURCES , +and +.Dv LOGIN_SETUMASK +bits are used. +.Po +See +.Fn setusercontext +below +.Pc . +It returns 0 on success and \-1 on failure. +.Pp +The +.Fn setusercontext +function +sets the resources according to +.Fa flags . +The +.Fa lc +argument, if not +.Dv NULL , +contains the class information that should +be used. +The +.Fa pwd +argument, if not +.Dv NULL , +provides information about the user. +.Fa lc +and +.Fa pwd +cannot both be +.Dv NULL . +The +.Fa uid +argument is used in place of the user id contained in the +.Fa pwd +structure when calling +.Xr setuid 2 . +The various bits available to be or-ed together to make up +.Fa flags +are: +.Bl -tag -width Dv +.It Dv LOGIN_SETGID +Set the group id. +Requires the +.Fa pwd +field be specified. +.It Dv LOGIN_SETGROUPS +Set the group membership list by calling +.Xr initgroups 3 . +Requires the +.Fa pwd +field be specified. +.It Dv LOGIN_SETGROUP +Set the group id and call +.Xr initgroups 3 . +Requires the +.Fa pwd +field be specified. +.It Dv LOGIN_SETLOGIN +Sets the login name by +.Xr setlogin 2 . +Requires the +.Fa pwd +field be specified. +.It Dv LOGIN_SETPATH +Sets the +.Ev PATH +environment variable. +.It Dv LOGIN_SETPRIORITY +Sets the priority by +.Xr setpriority 2 . +.It Dv LOGIN_SETRESOURCES +Sets the various system resources by +.Xr setrlimit 2 . +.It Dv LOGIN_SETUMASK +Sets the umask by +.Xr umask 2 . +.It Ev LOGIN_SETUSER +Sets the user id to +.Fa uid +by +.Xr setuid 2 . +.It Dv LOGIN_SETENV +Sets the environment variables as defined by the setenv keyword, by +.Xr setenv 3 . +.It Dv LOGIN_SETALL +Sets all of the above. +.El +.Sh SEE ALSO +.Xr setlogin 2 , +.Xr setpriority 2 , +.Xr setrlimit 2 , +.Xr setuid 2 , +.Xr umask 2 , +.Xr initgroups 3 , +.Xr secure_path 3 , +.Xr login.conf 5 +.Sh HISTORY +The +.Nm +family of functions are largely based on the +.Bsx +implementation of same, and appeared in +.Nx 1.5 +by kind permission. +.Sh CAVEATS +The string returned by +.Fn login_getcapstr +is allocated via +.Xr malloc 3 +when the specified capability is present and thus it is the responsibility +of the caller to +.Fn free +this space. +However, if the capability was not found or an error occurred and +.Fa def +or +.Fa err +(whichever is relevant) are +.Pf non- Dv NULL +the returned value is simply what was passed in to +.Fn login_getcapstr . +Therefore it is not possible to blindly +.Fn free +the return value without first checking it against +.Fa def +and +.Fa err . +.Pp +The same warnings set forth in +.Xr setlogin 2 +apply to +.Fn setusercontext +when the +.Dv LOGIN_SETLOGIN +flag is used. +Specifically, changing the login name affects all processes in the current +session, not just the current process. +See +.Xr setlogin 2 +for more information. diff --git a/static/netbsd/man3/loginx.3 b/static/netbsd/man3/loginx.3 new file mode 100644 index 00000000..5924bdec --- /dev/null +++ b/static/netbsd/man3/loginx.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: loginx.3,v 1.3 2008/04/30 13:10:52 martin Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 26, 2002 +.Dt LOGINX 3 +.Os +.Sh NAME +.Nm loginx , +.Nm logoutx , +.Nm logwtmpx +.Nd login utility functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft void +.Fn loginx "const struct utmpx *ut" +.Ft int +.Fn logoutx "const char *line" "int status" "int type" +.Ft void +.Fn logwtmpx "const char *line" "const char *name" "const char *host" "int status" "int type" +.Sh DESCRIPTION +The +.Fn loginx , +.Fn logoutx , +and +.Fn logwtmpx +operate on the +.Xr utmpx 5 +database of currently logged in users, and the +.Xr wtmpx 5 +database of logins and logouts. +.Pp +The +.Fn loginx +function updates the +.Pa /var/run/utmpx +and +.Pa /var/log/wtmpx +databases with the information from +.Fa ut . +.Pp +.Fn logoutx +updates the entry corresponding to +.Fa line +with the type and status from +.Fa type +and +.Fa status . +.Pp +.Fn logwtmpx +writes an entry filled with data from +.Fa line , +.Fa name , +.Fa host , +.Fa status , +and +.Fa type +to the +.Xr wtmpx 5 +database. +.Sh RETURN VALUES +.Fn logoutx +returns 1 on success, and 0 if no corresponding entry was found. +.Sh SEE ALSO +.Xr endutxent 3 , +.Xr utmpx 5 diff --git a/static/netbsd/man3/lrint.3 b/static/netbsd/man3/lrint.3 new file mode 100644 index 00000000..1ef540fc --- /dev/null +++ b/static/netbsd/man3/lrint.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: lrint.3,v 1.2 2024/01/26 19:27:30 nros Exp $ +.\" +.\" Copyright (c) 2005 David Schultz +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/msun/man/lrint.3,v 1.2.2.2 2005/03/01 16:18:39 brueffer Exp $ +.\" +.Dd January 24, 2024 +.Dt LRINT 3 +.Os +.Sh NAME +.Nm llrint , +.Nm llrintf , +.Nm llrintl , +.Nm lrint , +.Nm lrintf , +.Nm lrintl +.Nd convert to integer +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft long long +.Fn llrint "double x" +.Ft long long +.Fn llrintf "float x" +.Ft long long +.Fn llrintl "long double x" +.Ft long +.Fn lrint "double x" +.Ft long +.Fn lrintf "float x" +.Ft long +.Fn lrintl "long double x" +.Sh DESCRIPTION +The +.Fn lrint +function returns the integer nearest to its argument +.Fa x +according to the current rounding mode. +.Pp +The +.Fn llrint , +.Fn llrintf , +.Fn llrintl , +.Fn lrintf , +and +.Fn lrintl +functions differ from +.Fn lrint +only in their input and output types. +.Sh RETURN VALUES +The +.Nm llrint , +.Nm llrintf , +.Nm llrintl , +.Nm lrint , +.Nm lrintf , +and +.Nm lrintl +functions return the integer nearest to their argument +.Fa x +according to the current rounding mode. +If the rounded result is too large to be represented as a +.Vt long long +or +.Vt long +value, respectively, +.\" an invalid exception is raised and +the return value is undefined. +.\" Otherwise, if +.\" .Fa x +.\" is not an integer, +.\" .Fn lrint +.\" raises an inexact exception. +.\" If +.\" .Fa x +.\" is too large, a range error may occur. +.Sh SEE ALSO +.\" .Xr lround 3 , +.Xr math 3 , +.Xr rint 3 , +.Xr round 3 +.Sh STANDARDS +The +.Fn llrint , +.Fn llrintf , +.Fn llrintl , +.Fn lrint , +.Fn lrintf , +and +.Fn lrintl +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/lsearch.3 b/static/netbsd/man3/lsearch.3 new file mode 100644 index 00000000..d34a5a8d --- /dev/null +++ b/static/netbsd/man3/lsearch.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)lsearch.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: lsearch.3,v 1.3 2005/07/12 08:28:42 wiz Exp $ +.\" +.Dd July 6, 2005 +.Dt LSEARCH 3 +.Os +.Sh NAME +.Nm lsearch , +.Nm lfind +.Nd linear searching routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In search.h +.Ft void * +.Fn lsearch "const void *key" "void *base" "size_t *nelp" "size_t width" "int (*compar)(const void *, const void *)" +.Ft void * +.Fn lfind "const void *key" "const void *base" "size_t *nelp" "size_t width" "int (*compar)(const void *, const void *)" +.Sh DESCRIPTION +The functions +.Fn lsearch , +and +.Fn lfind +provide basic linear searching functionality. +.Pp +.Fa base +is the pointer to the beginning of an array. +The argument +.Fa nelp +is the current number of elements in the array, where each element +is +.Fa width +bytes long. +The +.Fa compar +argument points to a function which compares its two arguments and returns +zero if they are matching, and non-zero otherwise. +.Pp +The +.Fn lsearch +and +.Fn lfind +functions +return a pointer into the array referenced by +.Fa base +where +.Fa key +is located. +If +.Fa key +does not exist, +.Fn lfind +will return a null pointer and +.Fn lsearch +will add it to the array. +When an element is added to the array by +.Fn lsearch +the location referenced by the argument +.Fa nelp +is incremented by one. +.Sh SEE ALSO +.Xr bsearch 3 , +.Xr db 3 +.Sh STANDARDS +The +.Fn lsearch +and +.Fn lfind +functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/makecontext.3 b/static/netbsd/man3/makecontext.3 new file mode 100644 index 00000000..0742e218 --- /dev/null +++ b/static/netbsd/man3/makecontext.3 @@ -0,0 +1,169 @@ +.\" $NetBSD: makecontext.3,v 1.10 2012/05/04 12:28:03 joerg Exp $ +.\" +.\" Copyright (c) 2001, 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2012 +.Dt MAKECONTEXT 3 +.Os +.Sh NAME +.Nm makecontext , +.Nm swapcontext +.Nd manipulate user contexts +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ucontext.h +.Ft void +.Fn makecontext "ucontext_t *ucp" "void (*func)()" "int argc" ... +.Ft int +.Fn swapcontext "ucontext_t * restrict oucp" "ucontext_t * restrict ucp" +.Sh DESCRIPTION +The +.Fn makecontext +function modifies the object pointed to by +.Fa ucp , +which has been initialized using +.Xr getcontext 2 . +When this context is resumed using +.Fn swapcontext +or +.Xr setcontext 2 , +program execution continues as if +.Fa func +had been called with the arguments specified after +.Fa argc +in the call of +.Fn makecontext . +The value of +.Fa argc +must be equal to the number of integer arguments following it, +and must be equal to the number of integer arguments expected by +.Fa func ; +otherwise, the behavior is undefined. +.Pp +Before being modified using +.Fn makecontext , +a stack must be allocated for the context (in the +.Fa uc_stack +member), and a context to resume after +.Fa func +has returned must be determined (pointed to by the +.Fa uc_link +member); +otherwise, the behavior is undefined. +If +.Fa uc_link +is a null pointer, then the context is the main context, +and the process will exit with an exit status of 0 upon return. +.Pp +The +.Fn swapcontext +function saves the current context in the object pointed to by +.Fa oucp , +sets the current context to that specified in the object pointed to by +.Fa ucp , +and resumes execution. +When a context saved by +.Fn swapcontext +is restored using +.Xr setcontext 2 , +execution will resume as if the corresponding invocation of +.Fn swapcontext +had just returned (successfully). +.Sh RETURN VALUES +The +.Fn makecontext +function returns no value. +.Pp +On success, +.Fn swapcontext +returns a value of 0, +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn swapcontext +function will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa oucp +argument or the +.Fa ucp +argument points to an invalid address. +.It Bq Er EINVAL +The contents of the datum pointed to by +.Fa ucp +are invalid. +.El +.Sh SEE ALSO +.Xr _exit 2 , +.Xr getcontext 2 , +.Xr setcontext 2 , +.Xr ucontext 2 +.Sh STANDARDS +The +.Fn makecontext +and +.Fn swapcontext +functions conform to +.St -xsh5 +and +.St -p1003.1-2001 . +.Pp +The +.St -p1003.1-2004 +revision marked the functions +.Fn makecontext +and +.Fn swapcontext +as obsolete, citing portability issues and recommending the use of +.Tn POSIX +threads instead. +The +.St -p1003.1-2008 +revision removed the functions from the specification. +.Pp +.Bf -symbolic +The standard does not clearly define the type of integer arguments +passed to +.Fa func +via +.Fn makecontext ; +portable applications should not rely on the implementation detail that +it may be possible to pass pointer arguments to functions. +.Ef +This may be clarified in a future revision of the standard. +.Sh HISTORY +The +.Fn makecontext +and +.Fn swapcontext +functions first appeared in +.At V.4 . diff --git a/static/netbsd/man3/malloc.3 b/static/netbsd/man3/malloc.3 new file mode 100644 index 00000000..0a993988 --- /dev/null +++ b/static/netbsd/man3/malloc.3 @@ -0,0 +1,319 @@ +.\" $NetBSD: malloc.3,v 1.48 2016/06/01 08:32:05 wiz Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $ +.\" +.Dd June 1, 2016 +.Dt MALLOC 3 +.Os +.Sh NAME +.Nm malloc , calloc , realloc , free +.Nd general purpose memory allocation functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn malloc "size_t size" +.Ft void * +.Fn calloc "size_t number" "size_t size" +.Ft void * +.Fn realloc "void *ptr" "size_t size" +.Ft void +.Fn free "void *ptr" +.Sh DESCRIPTION +The +.Fn malloc +function allocates +.Fa size +bytes of uninitialized memory. +The allocated space is suitably aligned (after possible pointer coercion) +for storage of any type of object. +.Pp +The +.Fn calloc +function allocates space for +.Fa number +objects, +each +.Fa size +bytes in length. +The result is identical to calling +.Fn malloc +with an argument of +.Dq "number * size" , +with the exception that the allocated memory is explicitly initialized +to zero bytes. +.Pp +The +.Fn realloc +function changes the size of the previously allocated memory referenced by +.Fa ptr +to +.Fa size +bytes. +The contents of the memory are unchanged up to the lesser of the new and +old sizes. +If the new size is larger, +the value of the newly allocated portion of the memory is undefined. +Upon success, the memory referenced by +.Fa ptr +is freed and a pointer to the newly allocated memory is returned. +.Pp +Note that +.Fn realloc +may move the memory allocation, resulting in a different return value than +.Fa ptr . +If +.Fa ptr +is +.Dv NULL , +the +.Fn realloc +function behaves identically to +.Fn malloc +for the specified size. +.Pp +The +.Fn free +function causes the allocated memory referenced by +.Fa ptr +to be made available for future allocations. +If +.Fa ptr +is +.Dv NULL , +no action occurs. +.Sh RETURN VALUES +The +.Fn malloc +and +.Fn calloc +functions return a pointer to the allocated memory if successful; otherwise +a +.Dv NULL +pointer is returned and +.Va errno +is set to +.Er ENOMEM . +.Pp +The +.Fn realloc +function returns a pointer, possibly identical to +.Fa ptr , +to the allocated memory +if successful; otherwise a +.Dv NULL +pointer is returned, and +.Va errno +is set to +.Er ENOMEM +if the error was the result of an allocation failure. +The +.Fn realloc +function always leaves the original buffer intact +when an error occurs. +If +.Ar size +is 0, either +.Dv NULL +or a pointer that can be safely passed to +.Xr free 3 +is returned. +.Pp +The +.Fn free +function returns no value. +.Sh EXAMPLES +When using +.Fn malloc , +be careful to avoid the following idiom: +.Bd -literal -offset indent +if ((p = malloc(number * size)) == NULL) + err(EXIT_FAILURE, "malloc"); +.Ed +.Pp +The multiplication may lead to an integer overflow. +To avoid this, +.Xr reallocarr 3 +is recommended. +.Pp +If +.Fn malloc +must be used, be sure to test for overflow: +.Bd -literal -offset indent +if (size && number > SIZE_MAX / size) { + errno = EOVERFLOW; + err(EXIT_FAILURE, "allocation"); +} +.Ed +.Pp +The above test is not sufficient in all cases. +For example, multiplying ints requires a different set of checks: +.Bd -literal -offset indent +int num, size; +\&.\&.\&. + +/* Avoid invalid requests */ +if (size < 0 || num < 0) + errc(1, EOVERFLOW, "overflow"); + +/* Check for signed int overflow */ +if (size && num > INT_MAX / size) + errc(1, EOVERFLOW, "overflow"); + +if ((p = malloc(size * num)) == NULL) + err(1, "malloc"); +.Ed +.Pp +Assuming the implementation checks for integer overflow as +.Nx +does, it is much easier to use +.Fn calloc +or +.Xr reallocarr 3 . +.Pp +The above examples could be simplified to: +.Bd -literal -offset indent +ptr = NULL; +if ((e = reallocarr(&ptr, num, size))) + errx(1, "reallocarr", strerror(e)); +.Ed +.Bd -literal -offset indent +or at the cost of initialization: +if ((p = calloc(num, size)) == NULL) + err(1, "calloc"); +.Ed +.Pp +When using +.Fn realloc , +one must be careful to avoid the following idiom: +.Bd -literal -offset indent +nsize += 50; + +if ((p = realloc(p, nsize)) == NULL) + return NULL; +.Ed +.Pp +Do not adjust the variable describing how much memory has been allocated +until it is known that the allocation has been successful. +This can cause aberrant program behavior if the incorrect size value is used. +In most cases, the above example will also leak memory. +As stated earlier, a return value of +.Dv NULL +indicates that the old object still remains allocated. +Better code looks like this: +.Bd -literal -offset indent +newsize = size + 50; + +if ((p2 = realloc(p, newsize)) == NULL) { + + if (p != NULL) + free(p); + + p = NULL; + return NULL; +} + +p = p2; +size = newsize; +.Ed +.Sh SEE ALSO +.\" .Xr limits 1 , +.Xr madvise 2 , +.Xr mmap 2 , +.Xr sbrk 2 , +.Xr aligned_alloc 3 , +.Xr alloca 3 , +.Xr atexit 3 , +.Xr getpagesize 3 , +.Xr memory 3 , +.Xr posix_memalign 3 , +.Xr reallocarr 3 +.Pp +For the implementation details, see +.Xr jemalloc 3 . +.Sh STANDARDS +The +.Fn malloc , +.Fn calloc , +.Fn realloc +and +.Fn free +functions conform to +.St -isoC . +.Sh HISTORY +A +.Fn free +internal kernel function and a predecessor to +.Fn malloc , +.Fn alloc , +first appeared in +.At v1 . +The C Library functions +.Fn alloc +and +.Fn free +appeared in +.At v6 . +The functions +.Fn malloc , +.Fn calloc , +and +.Fn realloc +first appeared in +.At v7 . +.Pp +A new implementation by Chris Kingsley was introduced in +.Bx 4.2 , +followed by a complete rewrite by Poul-Henning Kamp +.Dq ( phk's malloc +or +.Dq new malloc ) +which appeared in +.Fx 2.2 +and was included in +.Nx 1.5 +and +.Ox 2.0 . +These implementations were all +.Xr sbrk 2 +based. +.Pp +The +.Xr jemalloc 3 +allocator became the default system allocator first in +.Fx 7.0 +and then in +.Nx 5.0 . diff --git a/static/netbsd/man3/man.cgi.3 b/static/netbsd/man3/man.cgi.3 new file mode 100644 index 00000000..3590a171 --- /dev/null +++ b/static/netbsd/man3/man.cgi.3 @@ -0,0 +1,310 @@ +.\" Id: man.cgi.3,v 1.4 2017/03/15 13:18:53 schwarze Exp +.\" +.\" Copyright (c) 2016, 2017 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd March 15, 2017 +.Dt MAN.CGI 3 +.Os +.Sh NAME +.Nm man.cgi +.Nd internals of the CGI program to search and display manual pages +.Sh DESCRIPTION +The source code of +.Xr man.cgi 8 +is organized in four levels: +.Pp +.Bl -enum -compact +.It +.Sx Top level +.It +.Sx Page generators +.It +.Sx Result generators +.It +.Sx Utility routines +.El +.Ss Top level +The top level of +.Xr man.cgi 8 +consists of the +.Fn main +program and a few parser routines. +.Bl -tag -width 1n +.It Ft int Fn main void +The main program +.Bl -dash -compact +.It +limits execution time; +.It +changes to +.Dv MAN_DIR , +the data directory containing all the manual trees; +.It +calls +.Fn parse_manpath_conf ; +.It +if +.Ev PATH_INFO +is empty, calls +.Fn parse_query_string ; +otherwise, +calls +.Fn parse_path_info ; +.It +validates the manpath and the architecture; +.It +calls the appropriate one among the +.Sx Page generators . +.El +.It Ft void Fn parse_manpath_conf "struct req *req" +Parses and validates +.Pa manpath.conf +and fills +.Va req->p +and +.Va req->psz . +.It Ft void Fn parse_path_info "struct req *req" "const char *path" +Parses and validates +.Ev PATH_INFO , +clears +.Va req->isquery , +and fills +.Va req->q . +.It Ft void Fn parse_query_string "struct req *req" "const char *qs" +Parses and validates +.Ev QUERY_STRING , +sets +.Va req->isquery , +and fills +.Va req->q . +This function is the only user of the utility functions +.Fn http_decode +and +.Fn set_query_attr . +.El +.Ss Page generators +The purpose of each page generator is to print a complete HTML page, +starting with the HTTP headers and continuing to the page footer. +Before starting HTML output with +.Fn resp_begin_html , +some page generators do some preparatory work, for example to decide +which page to show. +Each page generator ends with a call to +.Fn resp_end_html . +.Bl -tag -width 1n +.It Ft void Fn pg_show "struct req *req" "const char *fullpath" +This page generator is used when +.Ev PATH_INFO +contains the complete path to a manual page including manpath, +section directory, optional architecture subdirectory, manual name +and section number suffix. +It validates the manpath, changes into it, validate the filename, +and then calls +.Fn resp_begin_html , +.Fn resp_searchform , +.Fn resp_show , +and +.Fn resp_end_html +in that order. +.It Ft void Fn pg_search "const struct req *req" +This page generator is used when +.Ev PATH_INFO +contains a search query in short format or when +.Ev PATH_INFO +is empty and a +.Ev QUERY_STRING +is provided. +If possible, requests using +.Ev QUERY_STRING +are redirected to URIs using +.Ev PATH_INFO +by calling +.Fn pg_redirect . +Otherwise, it changes into the manpath and calls +.Xr mansearch 3 . +Depending on the result, it calls either +.Fn pg_noresult +or +.Fn pg_searchres . +.It Ft void Fn pg_redirect "const struct req *req" "const char *name" +This function is special in so far as it does not print an HTML page, +but only an HTTP 303 response with a Location: of the form: +.Sm off +.No http:// +.Ar host Ns / +.Op Ar scriptname Ns / +.Op Ar manpath Ns / +.Op Ar arch Ns / +.Fa name +.Op Pf . Ar sec +.Sm on +.It Ft void Fn pg_noresult "const struct req *req" "const char *msg" +This function calls +.Fn resp_begin_html , +.Fn resp_searchform , +prints the +.Fa msg +passed to it, and calls +.Fn resp_end_html . +.It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\ + "size_t sz" +This function first validates the filenames found. +If +.Ev QUERY_STRING +was used and there is exactly one result, +it writes an HTTP redirect to that result. +Otherwise, it writes an HTML result page beginning with +.Fn resp_begin_html +and +.Fn resp_searchform . +If there is more than one result, it writes a list of links +to all the results. +If it was a +.Xr man 1 +rather than an +.Xr apropos 1 +query or if there is only one single result, it calls +.Fn resp_show . +Finally, it calls +.Fn resp_end_html . +.It Ft void Fn pg_index "const struct req *req" +This page generator is used when +.Ev PATH_INFO +and +.Ev QUERY_STRING +are both empty. +It calls +.Fn resp_begin_html +and +.Fn resp_searchform , +writes links to help pages, and calls +.Fn resp_end_html . +.It Ft void Fn pg_error_badrequest "const char *msg" +This page generator is used when +.Fn main +or +.Fn pg_show +detect an invalid URI. +It calls +.Fn resp_begin_html , +prints the +.Fa msg +provided, and calls +.Fn resp_end_html . +.It Ft void Fn pg_error_internal void +This page generator is used by various functions when errors are +detected in the +.Pa manpath.conf +configuration file, in +.Xr mandoc.db 5 +databases, in the +.Xr mandoc 3 +parser, in file system permissions, or when setting up timeouts. +It calls +.Fn resp_begin_html , +prints +.Qq "Internal Server Error" , +and calls +.Fn resp_end_html . +Before calling +.Fn pg_error_internal , +call +.Xr warn 3 +or +.Xr warnx 3 +to log the reason of the error to the +.Xr httpd 8 +server log file. +.El +.Ss Result generators +The purpose of result generators is to print a chunk of HTML code. +When they print untrusted strings or characters, +.Fn html_print +and +.Fn html_putchar +are used. +The highest level result generators are: +.Bl -tag -width 1n +.It Ft void Fn resp_begin_html "int code" "const char *msg" "const char *file" +This generator calls +.Fn resp_begin_http +to print the HTTP headers, then prints the HTML header up to the +opening tag of the element, then copies the file +.Pa header.html +to the output, if it exists and is readable. +If +.Fa file +is not +.Dv NULL , +it is used for the element. +.It Ft void Fn resp_searchform "const struct req *req" "enum focus focus" +This generator prints a search form, filling it with data +from the provided request object. +If the +.Fa focus +argument is +.Dv FOCUS_QUERY , +it sets the document's autofocus to the query input box. +.It Ft void Fn resp_show "const struct req *req" "const char *file" +This wrapper dispatches to either +.Fn resp_catman +or +.Fn resp_format , +depending on whether +.Ar file +starts with +.Pa cat +or +.Pa man , +respectively. +.It Ft void Fn resp_catman "const struct req *req" "const char *file" +This generator translates a preformatted, backspace-encoded manual +page to HTML and prints it to the output. +.It Ft void Fn resp_format "const struct req *req" "const char *file" +This generator formats a manual page on the standard output, +using the functions documented in +.Xr mchars_alloc 3 +and +.Xr mandoc 3 . +.It Ft void Fn resp_end_html void +This generator copies the file +.Pa footer.html +to the output, if it exists and is readable, +and closes the <body> and <html> elements. +.El +.Ss Utility routines +These functions take a string and return 1 if it is valid, or 0 otherwise. +.Bl -tag -width 1n +.It Ft int Fn validate_urifrag "const char *frag" +Checks that the string only contains alphanumeric ASCII characters, +dashes, dots, slashes, and underscores. +.It Ft int Fn validate_manpath "const struct req *req" "const char* manpath" +Checks that the string is either +.Qq mandoc +or one of the manpaths configured in +.Pa manpath.conf . +.It Ft int Fn validate_filename "const char *file" +Checks that the string starts with +.Qq man +or +.Qq cat +and does not ascend to parent directories. +.El +.Sh SEE ALSO +.Xr mandoc 3 , +.Xr mansearch 3 , +.Xr mchars_alloc 3 , +.Xr mandoc.db 5 , +.Xr man.cgi 8 diff --git a/static/netbsd/man3/mandoc.3 b/static/netbsd/man3/mandoc.3 new file mode 100644 index 00000000..b8b058bb --- /dev/null +++ b/static/netbsd/man3/mandoc.3 @@ -0,0 +1,574 @@ +.\" Id: mandoc.3,v 1.44 2018/12/30 00:49:55 schwarze Exp +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 30, 2018 +.Dt MANDOC 3 +.Os +.Sh NAME +.Nm mandoc , +.Nm deroff , +.Nm mparse_alloc , +.Nm mparse_copy , +.Nm mparse_free , +.Nm mparse_open , +.Nm mparse_readfd , +.Nm mparse_reset , +.Nm mparse_result +.Nd mandoc macro compiler library +.Sh SYNOPSIS +.In sys/types.h +.In stdio.h +.In mandoc.h +.Pp +.Fd "#define ASCII_NBRSP" +.Fd "#define ASCII_HYPH" +.Fd "#define ASCII_BREAK" +.Ft struct mparse * +.Fo mparse_alloc +.Fa "int options" +.Fa "enum mandoc_os oe_e" +.Fa "char *os_s" +.Fc +.Ft void +.Fo mparse_free +.Fa "struct mparse *parse" +.Fc +.Ft void +.Fo mparse_copy +.Fa "const struct mparse *parse" +.Fc +.Ft int +.Fo mparse_open +.Fa "struct mparse *parse" +.Fa "const char *fname" +.Fc +.Ft void +.Fo mparse_readfd +.Fa "struct mparse *parse" +.Fa "int fd" +.Fa "const char *fname" +.Fc +.Ft void +.Fo mparse_reset +.Fa "struct mparse *parse" +.Fc +.Ft struct roff_meta * +.Fo mparse_result +.Fa "struct mparse *parse" +.Fc +.In roff.h +.Ft void +.Fo deroff +.Fa "char **dest" +.Fa "const struct roff_node *node" +.Fc +.In sys/types.h +.In mandoc.h +.In mdoc.h +.Vt extern const char * const * mdoc_argnames; +.Vt extern const char * const * mdoc_macronames; +.In sys/types.h +.In mandoc.h +.In man.h +.Vt extern const char * const * man_macronames; +.Sh DESCRIPTION +The +.Nm mandoc +library parses a +.Ux +manual into an abstract syntax tree (AST). +.Ux +manuals are composed of +.Xr mdoc 7 +or +.Xr man 7 , +and may be mixed with +.Xr roff 7 , +.Xr tbl 7 , +and +.Xr eqn 7 +invocations. +.Pp +The following describes a general parse sequence: +.Bl -enum +.It +initiate a parsing sequence with +.Xr mchars_alloc 3 +and +.Fn mparse_alloc ; +.It +open a file with +.Xr open 2 +or +.Fn mparse_open ; +.It +parse it with +.Fn mparse_readfd ; +.It +close it with +.Xr close 2 ; +.It +retrieve the syntax tree with +.Fn mparse_result ; +.It +if information about the validity of the input is needed, fetch it with +.Fn mparse_updaterc ; +.It +iterate over parse nodes with starting from the +.Fa first +member of the returned +.Vt struct roff_meta ; +.It +free all allocated memory with +.Fn mparse_free +and +.Xr mchars_free 3 , +or invoke +.Fn mparse_reset +and go back to step 2 to parse new files. +.El +.Sh REFERENCE +This section documents the functions, types, and variables available +via +.In mandoc.h , +with the exception of those documented in +.Xr mandoc_escape 3 +and +.Xr mchars_alloc 3 . +.Ss Types +.Bl -ohang +.It Vt "enum mandocerr" +An error or warning message during parsing. +.It Vt "enum mandoclevel" +A classification of an +.Vt "enum mandocerr" +as regards system operation. +See the DIAGNOSTICS section in +.Xr mandoc 1 +regarding the meanings of the levels. +.It Vt "struct mparse" +An opaque pointer to a running parse sequence. +Created with +.Fn mparse_alloc +and freed with +.Fn mparse_free . +This may be used across parsed input if +.Fn mparse_reset +is called between parses. +.El +.Ss Functions +.Bl -ohang +.It Fn deroff +Obtain a text-only representation of a +.Vt struct roff_node , +including text contained in its child nodes. +To be used on children of the +.Fa first +member of +.Vt struct roff_meta . +When it is no longer needed, the pointer returned from +.Fn deroff +can be passed to +.Xr free 3 . +.It Fn mparse_alloc +Allocate a parser. +The arguments have the following effect: +.Bl -tag -offset 5n -width inttype +.It Ar options +When the +.Dv MPARSE_MDOC +or +.Dv MPARSE_MAN +bit is set, only that parser is used. +Otherwise, the document type is automatically detected. +.Pp +When the +.Dv MPARSE_SO +bit is set, +.Xr roff 7 +.Ic \&so +file inclusion requests are always honoured. +Otherwise, if the request is the only content in an input file, +only the file name is remembered, to be returned in the +.Fa sodest +field of +.Vt struct roff_meta . +.Pp +When the +.Dv MPARSE_QUICK +bit is set, parsing is aborted after the NAME section. +This is for example useful in +.Xr makewhatis 8 +.Fl Q +to quickly build minimal databases. +.Pp +When the +.Dv MARSE_VALIDATE +bit is set, +.Fn mparse_result +runs the validation functions before returning the syntax tree. +This is almost always required, except in certain debugging scenarios, +for example to dump unvalidated syntax trees. +.It Ar os_e +Operating system to check base system conventions for. +If +.Dv MANDOC_OS_OTHER , +the system is automatically detected from +.Ic \&Os , +.Fl Ios , +or +.Xr uname 3 . +.It Ar os_s +A default string for the +.Xr mdoc 7 +.Ic \&Os +macro, overriding the +.Dv OSNAME +preprocessor definition and the results of +.Xr uname 3 . +Passing +.Dv NULL +sets no default. +.El +.Pp +The same parser may be used for multiple files so long as +.Fn mparse_reset +is called between parses. +.Fn mparse_free +must be called to free the memory allocated by this function. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_free +Free all memory allocated by +.Fn mparse_alloc . +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_copy +Dump a copy of the input to the standard output; used for +.Fl man T Ns Cm man . +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_open +Open the file for reading. +If that fails and +.Fa fname +does not already end in +.Ql .gz , +try again after appending +.Ql .gz . +Save the information whether the file is zipped or not. +Return a file descriptor open for reading or -1 on failure. +It can be passed to +.Fn mparse_readfd +or used directly. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_readfd +Parse a file descriptor opened with +.Xr open 2 +or +.Fn mparse_open . +Pass the associated filename in +.Va fname . +This function may be called multiple times with different parameters; however, +.Xr close 2 +and +.Fn mparse_reset +should be invoked between parses. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_reset +Reset a parser so that +.Fn mparse_readfd +may be used again. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.It Fn mparse_result +Obtain the result of a parse. +Declared in +.In mandoc.h , +implemented in +.Pa read.c . +.El +.Ss Variables +.Bl -ohang +.It Va man_macronames +The string representation of a +.Xr man 7 +macro as indexed by +.Vt "enum mant" . +.It Va mdoc_argnames +The string representation of an +.Xr mdoc 7 +macro argument as indexed by +.Vt "enum mdocargt" . +.It Va mdoc_macronames +The string representation of an +.Xr mdoc 7 +macro as indexed by +.Vt "enum mdoct" . +.El +.Sh IMPLEMENTATION NOTES +This section consists of structural documentation for +.Xr mdoc 7 +and +.Xr man 7 +syntax trees and strings. +.Ss Man and Mdoc Strings +Strings may be extracted from mdoc and man meta-data, or from text +nodes (MDOC_TEXT and MAN_TEXT, respectively). +These strings have special non-printing formatting cues embedded in the +text itself, as well as +.Xr roff 7 +escapes preserved from input. +Implementing systems will need to handle both situations to produce +human-readable text. +In general, strings may be assumed to consist of 7-bit ASCII characters. +.Pp +The following non-printing characters may be embedded in text strings: +.Bl -tag -width Ds +.It Dv ASCII_NBRSP +A non-breaking space character. +.It Dv ASCII_HYPH +A soft hyphen. +.It Dv ASCII_BREAK +A breakable zero-width space. +.El +.Pp +Escape characters are also passed verbatim into text strings. +An escape character is a sequence of characters beginning with the +backslash +.Pq Sq \e . +To construct human-readable text, these should be intercepted with +.Xr mandoc_escape 3 +and converted with one the functions described in +.Xr mchars_alloc 3 . +.Ss Man Abstract Syntax Tree +This AST is governed by the ontological rules dictated in +.Xr man 7 +and derives its terminology accordingly. +.Pp +The AST is composed of +.Vt struct roff_node +nodes with element, root and text types as declared by the +.Va type +field. +Each node also provides its parse point (the +.Va line , +.Va pos , +and +.Va sec +fields), its position in the tree (the +.Va parent , +.Va child , +.Va next +and +.Va prev +fields) and some type-specific data. +.Pp +The tree itself is arranged according to the following normal form, +where capitalised non-terminals represent nodes. +.Pp +.Bl -tag -width "ELEMENTXX" -compact +.It ROOT +\(<- mnode+ +.It mnode +\(<- ELEMENT | TEXT | BLOCK +.It BLOCK +\(<- HEAD BODY +.It HEAD +\(<- mnode* +.It BODY +\(<- mnode* +.It ELEMENT +\(<- ELEMENT | TEXT* +.It TEXT +\(<- [[:ascii:]]* +.El +.Pp +The only elements capable of nesting other elements are those with +next-line scope as documented in +.Xr man 7 . +.Ss Mdoc Abstract Syntax Tree +This AST is governed by the ontological +rules dictated in +.Xr mdoc 7 +and derives its terminology accordingly. +.Qq In-line +elements described in +.Xr mdoc 7 +are described simply as +.Qq elements . +.Pp +The AST is composed of +.Vt struct roff_node +nodes with block, head, body, element, root and text types as declared +by the +.Va type +field. +Each node also provides its parse point (the +.Va line , +.Va pos , +and +.Va sec +fields), its position in the tree (the +.Va parent , +.Va child , +.Va last , +.Va next +and +.Va prev +fields) and some type-specific data, in particular, for nodes generated +from macros, the generating macro in the +.Va tok +field. +.Pp +The tree itself is arranged according to the following normal form, +where capitalised non-terminals represent nodes. +.Pp +.Bl -tag -width "ELEMENTXX" -compact +.It ROOT +\(<- mnode+ +.It mnode +\(<- BLOCK | ELEMENT | TEXT +.It BLOCK +\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]] +.It ELEMENT +\(<- TEXT* +.It HEAD +\(<- mnode* +.It BODY +\(<- mnode* [ENDBODY mnode*] +.It TAIL +\(<- mnode* +.It TEXT +\(<- [[:ascii:]]* +.El +.Pp +Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of +the BLOCK production: these refer to punctuation marks. +Furthermore, although a TEXT node will generally have a non-zero-length +string, in the specific case of +.Sq \&.Bd \-literal , +an empty line will produce a zero-length string. +Multiple body parts are only found in invocations of +.Sq \&Bl \-column , +where a new body introduces a new phrase. +.Pp +The +.Xr mdoc 7 +syntax tree accommodates for broken block structures as well. +The ENDBODY node is available to end the formatting associated +with a given block before the physical end of that block. +It has a non-null +.Va end +field, is of the BODY +.Va type , +has the same +.Va tok +as the BLOCK it is ending, and has a +.Va pending +field pointing to that BLOCK's BODY node. +It is an indirect child of that BODY node +and has no children of its own. +.Pp +An ENDBODY node is generated when a block ends while one of its child +blocks is still open, like in the following example: +.Bd -literal -offset indent +\&.Ao ao +\&.Bo bo ac +\&.Ac bc +\&.Bc end +.Ed +.Pp +This example results in the following block structure: +.Bd -literal -offset indent +BLOCK Ao + HEAD Ao + BODY Ao + TEXT ao + BLOCK Bo, pending -> Ao + HEAD Bo + BODY Bo + TEXT bo + TEXT ac + ENDBODY Ao, pending -> Ao + TEXT bc +TEXT end +.Ed +.Pp +Here, the formatting of the +.Ic \&Ao +block extends from TEXT ao to TEXT ac, +while the formatting of the +.Ic \&Bo +block extends from TEXT bo to TEXT bc. +It renders as follows in +.Fl T Ns Cm ascii +mode: +.Pp +.Dl <ao [bo ac> bc] end +.Pp +Support for badly-nested blocks is only provided for backward +compatibility with some older +.Xr mdoc 7 +implementations. +Using badly-nested blocks is +.Em strongly discouraged ; +for example, the +.Fl T Ns Cm html +front-end to +.Xr mandoc 1 +is unable to render them in any meaningful way. +Furthermore, behaviour when encountering badly-nested blocks is not +consistent across troff implementations, especially when using multiple +levels of badly-nested blocks. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man.cgi 3 , +.Xr mandoc_escape 3 , +.Xr mandoc_headers 3 , +.Xr mandoc_malloc 3 , +.Xr mansearch 3 , +.Xr mchars_alloc 3 , +.Xr tbl 3 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 +.Sh AUTHORS +.An -nosplit +The +.Nm +library was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/static/netbsd/man3/mandoc_escape.3 b/static/netbsd/man3/mandoc_escape.3 new file mode 100644 index 00000000..697cab7a --- /dev/null +++ b/static/netbsd/man3/mandoc_escape.3 @@ -0,0 +1,367 @@ +.\" Id: mandoc_escape.3,v 1.4 2017/07/04 23:40:01 schwarze Exp +.\" +.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd July 4, 2017 +.Dt MANDOC_ESCAPE 3 +.Os +.Sh NAME +.Nm mandoc_escape +.Nd parse roff escape sequences +.Sh SYNOPSIS +.In sys/types.h +.In mandoc.h +.Ft "enum mandoc_esc" +.Fo mandoc_escape +.Fa "const char **end" +.Fa "const char **start" +.Fa "int *sz" +.Fc +.Sh DESCRIPTION +This function scans a +.Xr roff 7 +escape sequence. +.Pp +An escape sequence consists of +.Bl -dash -compact -width 2n +.It +an initial backslash character +.Pq Sq \e , +.It +a single ASCII character called the escape sequence identifier, +.It +and, with only a few exceptions, an argument. +.El +.Pp +Arguments can be given in the following forms; some escape sequence +identifiers only accept some of these forms as specified below. +The first three forms are called the standard forms. +.Bl -tag -width 2n +.It \&In brackets: Ic \&[ Ns Ar argument Ns Ic \&] +The argument starts after the initial +.Sq \&[ , +ends before the final +.Sq \&] , +and the escape sequence ends with the final +.Sq \&] . +.It Two-character argument short form: Ic \&( Ns Ar ar +This form can only be used for arguments +consisting of exactly two characters. +It has the same effect as +.Ic \&[ Ns Ar ar Ns Ic \&] . +.It One-character argument short form: Ar a +This form can only be used for arguments +consisting of exactly one character. +It has the same effect as +.Ic \&[ Ns Ar a Ns Ic \&] . +.It Delimited form: Ar C Ns Ar argument Ns Ar C +The argument starts after the initial delimiter character +.Ar C , +ends before the next occurrence of the delimiter character +.Ar C , +and the escape sequence ends with that second +.Ar C . +Some escape sequences allow arbitrary characters +.Ar C +as quoting characters, some restrict the range of characters +that can be used as quoting characters. +.El +.Pp +Upon function entry, +.Fa end +is expected to point to the escape sequence identifier. +The values passed in as +.Fa start +and +.Fa sz +are ignored and overwritten. +.Pp +By design, this function cannot handle those +.Xr roff 7 +escape sequences that require in-place expansion, in particular +user-defined strings +.Ic \e* , +number registers +.Ic \en , +width measurements +.Ic \ew , +and numerical expression control +.Ic \eB . +These are handled by +.Fn roff_res , +a private preprocessor function called from +.Fn roff_parseln , +see the file +.Pa roff.c . +.Pp +The function +.Fn mandoc_escape +is used +.Bl -dash -compact -width 2n +.It +recursively by itself, because some escape sequence arguments can +in turn contain other escape sequences, +.It +for error detection internally by the +.Xr roff 7 +parser part of the +.Xr mandoc 3 +library, see the file +.Pa roff.c , +.It +above all externally by the +.Xr mandoc 1 +formatting modules, in particular +.Fl Tascii +and +.Fl Thtml , +for formatting purposes, see the files +.Pa term.c +and +.Pa html.c , +.It +and rarely externally by high-level utilities using the mandoc library, +for example +.Xr makewhatis 8 , +to purge escape sequences from text. +.El +.Sh RETURN VALUES +Upon function return, the pointer +.Fa end +is set to the character after the end of the escape sequence, +such that the calling higher-level parser can easily continue. +.Pp +For escape sequences taking an argument, the pointer +.Fa start +is set to the beginning of the argument and +.Fa sz +is set to the length of the argument. +For escape sequences not taking an argument, +.Fa start +is set to the character after the end of the sequence and +.Fa sz +is set to 0. +Both +.Fa start +and +.Fa sz +may be +.Dv NULL ; +in that case, the argument and the length are not returned. +.Pp +For sequences taking an argument, the function +.Fn mandoc_escape +returns one of the following values: +.Bl -tag -width 2n +.It Dv ESCAPE_FONT +The escape sequence +.Ic \ef +taking an argument in standard form: +.Ic \ef[ , \ef( , \ef Ns Ar a . +Two-character arguments starting with the character +.Sq C +are reduced to one-character arguments by skipping the +.Sq C . +More specific values are returned for the most commonly used arguments: +.Bl -column "argument" "ESCAPE_FONTITALIC" +.It argument Ta return value +.It Cm R No or Cm 1 Ta Dv ESCAPE_FONTROMAN +.It Cm I No or Cm 2 Ta Dv ESCAPE_FONTITALIC +.It Cm B No or Cm 3 Ta Dv ESCAPE_FONTBOLD +.It Cm P Ta Dv ESCAPE_FONTPREV +.It Cm BI Ta Dv ESCAPE_FONTBI +.El +.It Dv ESCAPE_SPECIAL +The escape sequence +.Ic \eC +taking an argument delimited with the single quote character +and, as a special exception, the escape sequences +.Em not +having an identifier, that is, those where the argument, in standard +form, directly follows the initial backslash: +.Ic \eC' , \e[ , \e( , \e Ns Ar a . +Note that the one-character argument short form can only be used for +argument characters that do not clash with escape sequence identifiers. +.Pp +If the argument matches one of the forms described below under +.Dv ESCAPE_UNICODE , +that value is returned instead. +.Pp +The +.Dv ESCAPE_SPECIAL +special character escape sequences can be rendered using the functions +.Fn mchars_spec2cp +and +.Fn mchars_spec2str +described in the +.Xr mchars_alloc 3 +manual. +.It Dv ESCAPE_UNICODE +Escape sequences of the same format as described above under +.Dv ESCAPE_SPECIAL , +but with an argument of the forms +.Ic u Ns Ar XXXX , +.Ic u Ns Ar YXXXX , +or +.Ic u10 Ns Ar XXXX +where +.Ar X +and +.Ar Y +are hexadecimal digits and +.Ar Y +is not zero: +.Ic \eC'u , \e[u . +As a special exception, +.Fa start +is set to the character after the +.Ic u , +and the +.Fa sz +return value does not include the +.Ic u +either. +.Pp +Such Unicode character escape sequences can be rendered using the function +.Fn mchars_num2uc +described in the +.Xr mchars_alloc 3 +manual. +.It Dv ESCAPE_NUMBERED +The escape sequence +.Ic \eN +followed by a delimited argument. +The delimiter character is arbitrary except that digits cannot be used. +If a digit is encountered instead of the opening delimiter, that +digit is considered to be the argument and the end of the sequence, and +.Dv ESCAPE_IGNORE +is returned. +.Pp +Such ASCII character escape sequences can be rendered using the function +.Fn mchars_num2char +described in the +.Xr mchars_alloc 3 +manual. +.It Dv ESCAPE_OVERSTRIKE +The escape sequence +.Ic \eo +followed by an argument delimited by an arbitrary character. +.It Dv ESCAPE_IGNORE +.Bl -bullet -width 2n +.It +The escape sequence +.Ic \es +followed by an argument in standard form or by an argument delimited +by the single quote character: +.Ic \es' , \es[ , \es( , \es Ns Ar a . +As a special exception, an optional +.Sq + +or +.Sq \- +character is allowed after the +.Sq s +for all forms. +.It +The escape sequences +.Ic \eF , +.Ic \eg , +.Ic \ek , +.Ic \eM , +.Ic \em , +.Ic \en , +.Ic \eV , +and +.Ic \eY +followed by an argument in standard form. +.It +The escape sequences +.Ic \eA , +.Ic \eb , +.Ic \eD , +.Ic \eR , +.Ic \eX , +and +.Ic \eZ +followed by an argument delimited by an arbitrary character. +.It +The escape sequences +.Ic \eH , +.Ic \eh , +.Ic \eL , +.Ic \el , +.Ic \eS , +.Ic \ev , +and +.Ic \ex +followed by an argument delimited by a character that cannot occur +in numerical expressions. +However, if any character that can occur in numerical expressions +is found instead of a delimiter, the sequence is considered to end +with that character, and +.Dv ESCAPE_ERROR +is returned. +.El +.It Dv ESCAPE_ERROR +Escape sequences taking an argument but not matching any of the above patterns. +In particular, that happens if the end of the logical input line +is reached before the end of the argument. +.El +.Pp +For sequences that do not take an argument, the function +.Fn mandoc_escape +returns one of the following values: +.Bl -tag -width 2n +.It Dv ESCAPE_SKIPCHAR +The escape sequence +.Qq \ez . +.It Dv ESCAPE_NOSPACE +The escape sequence +.Qq \ec . +.It Dv ESCAPE_IGNORE +The escape sequences +.Qq \ed +and +.Qq \eu . +.El +.Sh FILES +This function is implemented in +.Pa mandoc.c . +.Sh SEE ALSO +.Xr mchars_alloc 3 , +.Xr mandoc_char 7 , +.Xr roff 7 +.Sh HISTORY +This function has been available since mandoc 1.11.2. +.Sh AUTHORS +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +.An Ingo Schwarze Aq Mt schwarze@openbsd.org +.Sh BUGS +The function doesn't cleanly distinguish between sequences that are +valid and supported, valid and ignored, valid and unsupported, +syntactically invalid, or undefined. +For sequences that are ignored or unsupported, it doesn't tell +whether that deficiency is likely to cause major formatting problems +and/or loss of document content. +The function is already rather complicated and still parses some +sequences incorrectly. +. +.ig +For these sequences, the list given below specifies a starting string +and either the length of the argument or an ending character. +The argument starts after the starting string. +In the former case, the sequence ends with the end of the argument. +In the latter case, the argument ends before the ending character, +and the sequence ends with the ending character. +.. diff --git a/static/netbsd/man3/mandoc_headers.3 b/static/netbsd/man3/mandoc_headers.3 new file mode 100644 index 00000000..38cc0fde --- /dev/null +++ b/static/netbsd/man3/mandoc_headers.3 @@ -0,0 +1,746 @@ +.\" Id: mandoc_headers.3,v 1.34 2021/08/10 12:55:03 schwarze Exp +.\" +.\" Copyright (c) 2014-2021 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd August 10, 2021 +.Dt MANDOC_HEADERS 3 +.Os +.Sh NAME +.Nm mandoc_headers +.Nd ordering of mandoc include files +.Sh DESCRIPTION +To support a cleaner coding style, the mandoc header files do not +contain any include directives and do not guard against multiple +inclusion. +The application developer has to make sure that the headers are +included in a proper order, and that no header is included more +than once. +.Pp +The headers and functions form three major groups: +.Sx Parser interface , +.Sx Parser internals , +and +.Sx Formatter interface . +.Pp +Various rules are given below prohibiting the inclusion of certain +combinations of headers into the same file. +The intention is to keep the following functional components +separate from each other: +.Pp +.Bl -dash -offset indent -compact +.It +.Xr roff 7 +parser +.It +.Xr mdoc 7 +parser +.It +.Xr man 7 +parser +.It +.Xr tbl 7 +parser +.It +.Xr eqn 7 +parser +.It +terminal formatters +.It +HTML formatters +.It +search tools +.It +main programs +.El +.Pp +Note that mere usage of an opaque struct type does +.Em not +require inclusion of the header where that type is defined. +.Ss Parser interface +Each of the following headers can be included without including +any other mandoc header. +These headers should be included before any other mandoc headers. +.Bl -tag -width Ds +.It Qq Pa mandoc_aux.h +Memory allocation utility functions; can be used everywhere. +.Pp +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides the functions documented in +.Xr mandoc_malloc 3 . +.It Qq Pa mandoc_ohash.h +Hashing utility functions; can be used everywhere. +.Pp +Requires +.In stddef.h +for +.Vt ptrdiff_t +and +.In stdint.h +for +.Vt uint32_t . +.Pp +Includes +.In ohash.h +and provides +.Fn mandoc_ohash_init . +.It Qq Pa mandoc.h +Error handling, escape sequence, and character utilities; +can be used everywhere. +.Pp +Requires +.In sys/types.h +for +.Vt size_t +and +.In stdio.h +for +.Vt FILE . +.Pp +Provides +.Vt enum mandoc_esc , +.Vt enum mandocerr , +.Vt enum mandoclevel , +the function +.Xr mandoc_escape 3 , +the functions described in +.Xr mchars_alloc 3 , +and the +.Fn mandoc_msg* +functions. +.It Qq Pa roff.h +Common data types for all syntax trees and related functions; +can be used everywhere. +.Pp +Provides +.Vt enum mandoc_os , +.Vt enum mdoc_endbody , +.Vt enum roff_macroset , +.Vt enum roff_sec , +.Vt enum roff_tok , +.Vt enum roff_type , +.Vt struct roff_man , +.Vt struct roff_meta , +.Vt struct roff_node , +the constant array +.Va roff_name +and the function +.Fn deroff . +.Pp +Uses pointers to the types +.Vt struct ohash +from +.Qq Pa mandoc_ohash.h , +.Vt struct mdoc_arg +and +.Vt union mdoc_data +from +.Qq Pa mdoc.h , +.Vt struct tbl_span +from +.Qq Pa tbl.h , +and +.Vt struct eqn_box +from +.Qq Pa eqn.h +as opaque struct members. +.It Qq Pa tbl.h +Data structures for the +.Xr tbl 7 +parse tree; can be used everywhere. +.Pp +Requires +.In sys/types.h +for +.Vt size_t +and +.Qq Pa mandoc.h +for +.Vt enum mandoc_esc . +.Pp +Provides +.Vt enum tbl_cellt , +.Vt enum tbl_datt , +.Vt enum tbl_spant , +.Vt struct tbl_opts , +.Vt struct tbl_cell , +.Vt struct tbl_row , +.Vt struct tbl_dat , +and +.Vt struct tbl_span . +.It Qq Pa eqn.h +Data structures for the +.Xr eqn 7 +parse tree; can be used everywhere. +.Pp +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum eqn_boxt , +.Vt enum eqn_fontt , +.Vt enum eqn_post , +and +.Vt struct eqn_box . +.It Qq Pa mandoc_parse.h +Top level parser interface, for use in the main program +and in the main parser, but not in formatters. +.Pp +Requires +.Qq Pa mandoc.h +for +.Vt enum mandocerr +and +.Vt enum mandoclevel +and +.Qq Pa roff.h +for +.Vt enum mandoc_os . +.Pp +Uses the opaque type +.Vt struct mparse +from +.Pa read.c +for function prototypes. +Uses +.Vt struct roff_meta +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.It Qq Pa mandoc_xr.h +Cross reference validation; intended for use in the main program +and in parsers, but not in formatters. +.Pp +Provides +.Vt struct mandoc_xr +and the functions +.Fn mandoc_xr_reset , +.Fn mandoc_xr_add , +.Fn mandoc_xr_get , +and +.Fn mandoc_xr_free . +.It Qq Pa tag.h +Internal interfaces to tag syntax tree nodes, +for use by validation modules only. +.Pp +Requires +.In limits.h +for +.Dv INT_MAX . +.Pp +Provides the functions +.Fn tag_alloc , +.Fn tag_put , +.Fn tag_check , +and +.Fn tag_free +and some +.Dv TAG_* +constants. +.Pp +Uses the type +.Vt struct roff_node +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.El +.Pp +The following two require +.Qq Pa roff.h +but no other mandoc headers. +Afterwards, any other mandoc headers can be included as needed. +.Bl -tag -width Ds +.It Qq Pa mdoc.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum mdocargt , +.Vt enum mdoc_auth , +.Vt enum mdoc_disp , +.Vt enum mdoc_font , +.Vt enum mdoc_list , +.Vt struct mdoc_argv , +.Vt struct mdoc_arg , +.Vt struct mdoc_an , +.Vt struct mdoc_bd , +.Vt struct mdoc_bf , +.Vt struct mdoc_bl , +.Vt struct mdoc_rs , +.Vt union mdoc_data , +and the functions +.Fn mdoc_* +described in +.Xr mandoc 3 . +.Pp +Uses the types +.Vt struct roff_node +from +.Qq Pa roff.h +and +.Vt struct roff_man +from +.Qq Pa roff_int.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +internals of different parsers. +.It Qq Pa man.h +Provides the functions +.Fn man_* +described in +.Xr mandoc 3 . +.Pp +Uses the type +.Vt struct roff_man +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +internals of different parsers. +.El +.Ss Parser internals +Most of the following headers require inclusion of a parser interface header +before they can be included. +All parser interface headers should precede all parser internal headers. +When any parser internal headers are included, the same file should +not include any formatter headers. +.Bl -tag -width Ds +.It Qq Pa libmandoc.h +Requires +.In sys/types.h +for +.Vt size_t +and +.Qq Pa mandoc.h +for +.Vt enum mandocerr . +.Pp +Provides +.Vt struct buf , +utility functions needed by multiple parsers, +and the top-level functions to call the parsers. +.Pp +Uses the opaque type +.Vt struct roff +from +.Pa roff.c +for function prototypes. +Uses the type +.Vt struct roff_man +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.It Qq Pa roff_int.h +Parser internals shared by multiple parsers. +Can be used in all parsers, but not in main programs or formatters. +.Pp +Requires +.Qq Pa roff.h +for +.Vt enum roff_type +and +.Vt enum roff_tok . +.Pp +Provides +.Vt enum roff_next , +.Vt struct roff_man , +functions named +.Fn roff_* +to handle roff nodes, +.Fn roffhash_alloc , +.Fn roffhash_find , +.Fn roffhash_free , +and +.Fn roff_validate , +and the two special functions +.Fn man_breakscope +and +.Fn mdoc_argv_free +because the latter two are needed by +.Pa roff.c . +.Pp +Uses the types +.Vt struct ohash +from +.Qq Pa mandoc_ohash.h , +.Vt struct roff_node +and +.Vt struct roff_meta +from +.Qq Pa roff.h , +.Vt struct roff +from +.Pa roff.c , +and +.Vt struct mdoc_arg +from +.Qq Pa mdoc.h +as opaque types for function prototypes. +.It Qq Pa libmdoc.h +Requires +.Qq Pa roff.h +for +.Vt enum roff_tok +and +.Vt enum roff_sec . +.Pp +Provides +.Vt enum margserr , +.Vt enum mdelim , +.Vt struct mdoc_macro , +and many functions internal to the +.Xr mdoc 7 +parser. +.Pp +Uses the types +.Vt struct roff_node +from +.Qq Pa roff.h , +.Vt struct roff_man +from +.Qq Pa roff_int.h , +and +.Vt struct mdoc_arg +from +.Qq Pa mdoc.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +interfaces of different parsers. +.It Qq Pa libman.h +Requires +.Qq Pa roff.h +for +.Vt enum roff_tok . +.Pp +Provides +.Vt struct man_macro +and some functions internal to the +.Xr man 7 +parser. +.Pp +Uses the types +.Vt struct roff_node +from +.Qq Pa roff.h +and +.Vt struct roff_man +from +.Qq Pa roff_int.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +interfaces of different parsers. +.It Qq Pa eqn_parse.h +External interface of the +.Xr eqn 7 +parser, for use in the +.Xr roff 7 +and +.Xr eqn 7 +parsers only. +.Pp +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt struct eqn_node +and the functions +.Fn eqn_alloc , +.Fn eqn_box_new , +.Fn eqn_box_free , +.Fn eqn_free , +.Fn eqn_parse , +.Fn eqn_read , +and +.Fn eqn_reset . +.Pp +Uses the type +.Vt struct eqn_box +from +.Qq Pa mandoc.h +as an opaque type for function prototypes. +Uses the types +.Vt struct roff_node +from +.Qq Pa roff.h +and +.Vt struct eqn_def +from +.Pa eqn.c +as opaque struct members. +.Pp +When this header is included, the same file should not include +internals of different parsers. +.It Qq Pa tbl_parse.h +External interface of the +.Xr tbl 7 +parser, for use in the +.Xr roff 7 +and +.Xr tbl 7 +parsers only. +.Pp +Provides the functions documented in +.Xr tbl 3 . +.Pp +Uses the types +.Vt struct tbl_span +from +.Qq Pa tbl.h +and +.Vt struct tbl_node +from +.Qq Pa tbl_int.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +internals of different parsers. +.It Qq Pa tbl_int.h +Internal interfaces of the +.Xr tbl 7 +parser, for use inside the +.Xr tbl 7 +parser only. +.Pp +Requires +.Qq Pa tbl.h +for +.Vt struct tbl_opts . +.Pp +Provides +.Vt enum tbl_part , +.Vt struct tbl_node , +and the functions +.Fn tbl_option , +.Fn tbl_layout , +.Fn tbl_data , +.Fn tbl_cdata , +and +.Fn tbl_reset . +.Pp +When this header is included, the same file should not include +interfaces of different parsers. +.El +.Ss Formatter interface +These headers should be included after any parser interface headers. +No parser internal headers should be included by the same file. +.Bl -tag -width Ds +.It Qq Pa out.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum roffscale , +.Vt struct roffcol , +.Vt struct roffsu , +.Vt struct rofftbl , +.Fn a2roffsu , +and +.Fn tblcalc . +.Pp +Uses +.Vt struct tbl_span +from +.Qq Pa mandoc.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa mansearch.h . +.It Qq Pa term.h +Requires +.In sys/types.h +for +.Vt size_t +and +.Qq Pa out.h +for +.Vt struct roffsu +and +.Vt struct rofftbl . +.Pp +Provides +.Vt enum termenc , +.Vt enum termfont , +.Vt enum termtype , +.Vt struct termp_tbl , +.Vt struct termp , +.Fn roff_term_pre , +and many terminal formatting functions. +.Pp +Uses the opaque type +.Vt struct termp_ps +from +.Pa term_ps.c . +Uses +.Vt struct tbl_span +and +.Vt struct eqn_box +from +.Qq Pa mandoc.h +and +.Vt struct roff_meta +and +.Vt struct roff_node +from +.Qq Pa roff.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa html.h +or +.Qq Pa mansearch.h . +.It Qq Pa tag_term.h +Requires +.In sys/types.h +for +.Vt size_t +and +.In stdio.h +for +.Vt FILE . +.Pp +Provides an interface to generate +.Xr ctags 1 +files for the +.Ic :t +functionality mentioned in +.Xr man 1 . +.Pp +Uses the type +.Vt struct roff_node +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa html.h +or +.Qq Pa mansearch.h . +.It Qq Pa html.h +Requires +.In sys/types.h +for +.Vt size_t , +.Qq Pa mandoc.h +for +.Vt enum mandoc_esc , +.Qq Pa roff.h +for +.Vt enum roff_tok , +and +.Qq Pa out.h +for +.Vt struct roffsu +and +.Vt struct rofftbl . +.Pp +Provides +.Vt enum htmltag , +.Vt enum htmlattr , +.Vt enum htmlfont , +.Vt struct tag , +.Vt struct tagq , +.Vt struct htmlpair , +.Vt struct html , +.Fn roff_html_pre , +and many HTML formatting functions. +.Pp +Uses +.Vt struct tbl_span +and +.Vt struct eqn_box +from +.Qq Pa mandoc.h +and +.Vt struct roff_node +from +.Qq Pa roff.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa term.h , +.Qq Pa tab_term.h , +or +.Qq Pa mansearch.h . +.It Qq Pa main.h +Provides the top level steering functions for all formatters. +.Pp +Uses the type +.Vt struct roff_meta +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.It Qq Pa manconf.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt struct manconf , +.Vt struct manpaths , +.Vt struct manoutput , +and the functions +.Fn manconf_parse , +.Fn manconf_output , +.Fn manconf_free , +and +.Fn manpath_base . +.It Qq Pa mansearch.h +Requires +.In sys/types.h +for +.Vt size_t +and +.In stdint.h +for +.Vt uint64_t . +.Pp +Provides +.Vt enum argmode , +.Vt struct manpage , +.Vt struct mansearch , +and the functions +.Fn mansearch +and +.Fn mansearch_free . +.Pp +Uses +.Vt struct manpaths +from +.Qq Pa manconf.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa out.h , +.Qq Pa term.h , +.Qq Pa tab_term.h , +or +.Qq Pa html.h . +.El diff --git a/static/netbsd/man3/mandoc_html.3 b/static/netbsd/man3/mandoc_html.3 new file mode 100644 index 00000000..5a8c05fc --- /dev/null +++ b/static/netbsd/man3/mandoc_html.3 @@ -0,0 +1,552 @@ +.\" Id: mandoc_html.3,v 1.23 2020/04/24 13:13:06 schwarze Exp +.\" +.\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 24, 2020 +.Dt MANDOC_HTML 3 +.Os +.Sh NAME +.Nm mandoc_html +.Nd internals of the mandoc HTML formatter +.Sh SYNOPSIS +.In sys/types.h +.Fd #include """mandoc.h""" +.Fd #include """roff.h""" +.Fd #include """out.h""" +.Fd #include """html.h""" +.Ft void +.Fn print_gen_decls "struct html *h" +.Ft void +.Fn print_gen_comment "struct html *h" "struct roff_node *n" +.Ft void +.Fn print_gen_head "struct html *h" +.Ft struct tag * +.Fo print_otag +.Fa "struct html *h" +.Fa "enum htmltag tag" +.Fa "const char *fmt" +.Fa ... +.Fc +.Ft void +.Fo print_tagq +.Fa "struct html *h" +.Fa "const struct tag *until" +.Fc +.Ft void +.Fo print_stagq +.Fa "struct html *h" +.Fa "const struct tag *suntil" +.Fc +.Ft void +.Fn html_close_paragraph "struct html *h" +.Ft enum roff_tok +.Fo html_fillmode +.Fa "struct html *h" +.Fa "enum roff_tok tok" +.Fc +.Ft int +.Fo html_setfont +.Fa "struct html *h" +.Fa "enum mandoc_esc font" +.Fc +.Ft void +.Fo print_text +.Fa "struct html *h" +.Fa "const char *word" +.Fc +.Ft void +.Fo print_tagged_text +.Fa "struct html *h" +.Fa "const char *word" +.Fa "struct roff_node *n" +.Fc +.Ft char * +.Fo html_make_id +.Fa "const struct roff_node *n" +.Fa "int unique" +.Fc +.Ft struct tag * +.Fo print_otag_id +.Fa "struct html *h" +.Fa "enum htmltag tag" +.Fa "const char *cattr" +.Fa "struct roff_node *n" +.Fc +.Ft void +.Fn print_endline "struct html *h" +.Sh DESCRIPTION +The mandoc HTML formatter is not a formal library. +However, as it is compiled into more than one program, in particular +.Xr mandoc 1 +and +.Xr man.cgi 8 , +and because it may be security-critical in some contexts, +some documentation is useful to help to use it correctly and +to prevent XSS vulnerabilities. +.Pp +The formatter produces HTML output on the standard output. +Since proper escaping is usually required and best taken care of +at one central place, the language-specific formatters +.Po +.Pa *_html.c , +see +.Sx FILES +.Pc +are not supposed to print directly to +.Dv stdout +using functions like +.Xr printf 3 , +.Xr putc 3 , +.Xr puts 3 , +or +.Xr write 2 . +Instead, they are expected to use the output functions declared in +.Pa html.h +and implemented as part of the main HTML formatting engine in +.Pa html.c . +.Ss Data structures +These structures are declared in +.Pa html.h . +.Bl -tag -width Ds +.It Vt struct html +Internal state of the HTML formatter. +.It Vt struct tag +One entry for the LIFO stack of HTML elements. +Members include +.Fa "enum htmltag tag" +and +.Fa "struct tag *next" . +.El +.Ss Private interface functions +The function +.Fn print_gen_decls +prints the opening +.Aq Pf \&! Ic DOCTYPE +declaration. +.Pp +The function +.Fn print_gen_comment +prints the leading comments, usually containing a Copyright notice +and license, as an HTML comment. +It is intended to be called right after opening the +.Aq Ic HTML +element. +Pass the first +.Dv ROFFT_COMMENT +node in +.Fa n . +.Pp +The function +.Fn print_gen_head +prints the opening +.Aq Ic META +and +.Aq Ic LINK +elements for the document +.Aq Ic HEAD , +using the +.Fa style +member of +.Fa h +unless that is +.Dv NULL . +It uses +.Fn print_otag +which takes care of properly encoding attributes, +which is relevant for the +.Fa style +link in particular. +.Pp +The function +.Fn print_otag +prints the start tag of an HTML element with the name +.Fa tag , +optionally including the attributes specified by +.Fa fmt . +If +.Fa fmt +is the empty string, no attributes are written. +Each letter of +.Fa fmt +specifies one attribute to write. +Most attributes require one +.Va char * +argument which becomes the value of the attribute. +The arguments have to be given in the same order as the attribute letters. +If an argument is +.Dv NULL , +the respective attribute is not written. +.Bl -tag -width 1n -offset indent +.It Cm c +Print a +.Cm class +attribute. +.It Cm h +Print a +.Cm href +attribute. +This attribute letter can optionally be followed by a modifier letter. +If followed by +.Cm R , +it formats the link as a local one by prefixing a +.Sq # +character. +If followed by +.Cm I , +it interpretes the argument as a header file name +and generates a link using the +.Xr mandoc 1 +.Fl O Cm includes +option. +If followed by +.Cm M , +it takes two arguments instead of one, a manual page name and +section, and formats them as a link to a manual page using the +.Xr mandoc 1 +.Fl O Cm man +option. +.It Cm i +Print an +.Cm id +attribute. +.It Cm \&? +Print an arbitrary attribute. +This format letter requires two +.Vt char * +arguments, the attribute name and the value. +The name must not be +.Dv NULL . +.It Cm s +Print a +.Cm style +attribute. +If present, it must be the last format letter. +It requires two +.Va char * +arguments. +The first is the name of the style property, the second its value. +The name must not be +.Dv NULL . +The +.Cm s +.Ar fmt +letter can be repeated, each repetition requiring an additional pair of +.Va char * +arguments. +.El +.Pp +.Fn print_otag +uses the private function +.Fn print_encode +to take care of HTML encoding. +If required by the element type, it remembers in +.Fa h +that the element is open. +The function +.Fn print_tagq +is used to close out all open elements up to and including +.Fa until ; +.Fn print_stagq +is a variant to close out all open elements up to but excluding +.Fa suntil . +The function +.Fn html_close_paragraph +closes all open elements that establish phrasing context, +thus returning to the innermost flow context. +.Pp +The function +.Fn html_fillmode +switches to fill mode if +.Fa want +is +.Dv ROFF_fi +or to no-fill mode if +.Fa want +is +.Dv ROFF_nf . +Switching from fill mode to no-fill mode closes the current paragraph +and opens a +.Aq Ic PRE +element. +Switching in the opposite direction closes the +.Aq Ic PRE +element, but does not open a new paragraph. +If +.Fa want +matches the mode that is already active, no elements are closed nor opened. +If +.Fa want +is +.Dv TOKEN_NONE , +the mode remains as it is. +.Pp +The function +.Fn html_setfont +selects the +.Fa font , +which can be +.Dv ESCAPE_FONTROMAN , +.Dv ESCAPE_FONTBOLD , +.Dv ESCAPE_FONTITALIC , +.Dv ESCAPE_FONTBI , +or +.Dv ESCAPE_FONTCW , +for future text output and internally remembers +the font that was active before the change. +If the +.Fa font +argument is +.Dv ESCAPE_FONTPREV , +the current and the previous font are exchanged. +This function only changes the internal state of the +.Fa h +object; no HTML elements are written yet. +Subsequent text output will write font elements when needed. +.Pp +The function +.Fn print_text +prints HTML element content. +It uses the private function +.Fn print_encode +to take care of HTML encoding. +If the document has requested a non-standard font, for example using a +.Xr roff 7 +.Ic \ef +font escape sequence, +.Fn print_text +wraps +.Fa word +in an HTML font selection element using the +.Fn print_otag +and +.Fn print_tagq +functions. +.Pp +The function +.Fn print_tagged_text +is a variant of +.Fn print_text +that wraps +.Fa word +in an +.Aq Ic A +element of class +.Qq permalink +if +.Fa n +is not +.Dv NULL +and yields a segment identifier when passed to +.Fn html_make_id . +.Pp +The function +.Fn html_make_id +allocates a string to be used for the +.Cm id +attribute of an HTML element and/or as a segment identifier for a URI in an +.Aq Ic A +element. +If +.Fa n +contains a +.Fa tag +attribute, it is used; otherwise, child nodes are used. +If +.Fa n +is an +.Ic \&Sh , +.Ic \&Ss , +.Ic \&Sx , +.Ic SH , +or +.Ic SS +node, the resulting string is the concatenation of the child strings; +for other node types, only the first child is used. +Bytes not permitted in URI-fragment strings are replaced by underscores. +If any of the children to be used is not a text node, +no string is generated and +.Dv NULL +is returned instead. +If the +.Fa unique +argument is non-zero, deduplication is performed by appending an +underscore and a decimal integer, if necessary. +If the +.Fa unique +argument is 1, this is assumed to be the first call for this tag +at this location, typically for use by +.Dv NODE_ID , +so the integer is incremented before use. +If the +.Fa unique +argument is 2, this is ssumed to be the second call for this tag +at this location, typically for use by +.Dv NODE_HREF , +so the existing integer, if any, is used without incrementing it. +.Pp +The function +.Fn print_otag_id +opens a +.Fa tag +element of class +.Fa cattr +for the node +.Fa n . +If the flag +.Dv NODE_ID +is set in +.Fa n , +it attempts to generate an +.Cm id +attribute with +.Fn html_make_id . +If the flag +.Dv NODE_HREF +is set in +.Fa n , +an +.Aq Ic A +element of class +.Qq permalink +is added: +outside if +.Fa n +generates an element that can only occur in phrasing context, +or inside otherwise. +This function is a wrapper around +.Fn html_make_id +and +.Fn print_otag , +automatically chosing the +.Fa unique +argument appropriately and setting the +.Fa fmt +arguments to +.Qq chR +and +.Qq ci , +respectively. +.Pp +The function +.Fn print_endline +makes sure subsequent output starts on a new HTML output line. +If nothing was printed on the current output line yet, it has no effect. +Otherwise, it appends any buffered text to the current output line, +ends the line, and updates the internal state of the +.Fa h +object. +.Pp +The functions +.Fn print_eqn , +.Fn print_tbl , +and +.Fn print_tblclose +are not yet documented. +.Sh RETURN VALUES +The functions +.Fn print_otag +and +.Fn print_otag_id +return a pointer to a new element on the stack of HTML elements. +When +.Fn print_otag_id +opens two elements, a pointer to the outer one is returned. +The memory pointed to is owned by the library and is automatically +.Xr free 3 Ns d +when +.Fn print_tagq +is called on it or when +.Fn print_stagq +is called on a parent element. +.Pp +The function +.Fn html_fillmode +returns +.Dv ROFF_fi +if fill mode was active before the call or +.Dv ROFF_nf +otherwise. +.Pp +The function +.Fn html_make_id +returns a newly allocated string or +.Dv NULL +if +.Fa n +lacks text data to create the attribute from. +The caller is responsible for +.Xr free 3 Ns ing +the returned string after using it. +.Pp +In case of +.Xr malloc 3 +failure, these functions do not return but call +.Xr err 3 . +.Sh FILES +.Bl -tag -width mandoc_aux.c -compact +.It Pa main.h +declarations of public functions for use by the main program, +not yet documented +.It Pa html.h +declarations of data types and private functions +for use by language-specific HTML formatters +.It Pa html.c +main HTML formatting engine and utility functions +.It Pa mdoc_html.c +.Xr mdoc 7 +HTML formatter +.It Pa man_html.c +.Xr man 7 +HTML formatter +.It Pa tbl_html.c +.Xr tbl 7 +HTML formatter +.It Pa eqn_html.c +.Xr eqn 7 +HTML formatter +.It Pa roff_html.c +.Xr roff 7 +HTML formatter, handling requests like +.Ic br , +.Ic ce , +.Ic fi , +.Ic ft , +.Ic nf , +.Ic rj , +and +.Ic sp . +.It Pa out.h +declarations of data types and private functions +for shared use by all mandoc formatters, +not yet documented +.It Pa out.c +private functions for shared use by all mandoc formatters +.It Pa mandoc_aux.h +declarations of common mandoc utility functions, see +.Xr mandoc 3 +.It Pa mandoc_aux.c +implementation of common mandoc utility functions +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr mandoc 3 , +.Xr man.cgi 8 +.Sh AUTHORS +.An -nosplit +The mandoc HTML formatter was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +It is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org , +who also wrote this manual. diff --git a/static/netbsd/man3/mandoc_malloc.3 b/static/netbsd/man3/mandoc_malloc.3 new file mode 100644 index 00000000..2f3fcdbc --- /dev/null +++ b/static/netbsd/man3/mandoc_malloc.3 @@ -0,0 +1,210 @@ +.\" Id: mandoc_malloc.3,v 1.3 2021/09/17 18:50:21 schwarze Exp +.\" +.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 17, 2021 +.Dt MANDOC_MALLOC 3 +.Os +.Sh NAME +.Nm mandoc_malloc , +.Nm mandoc_realloc , +.Nm mandoc_reallocarray , +.Nm mandoc_calloc , +.Nm mandoc_recallocarray , +.Nm mandoc_strdup , +.Nm mandoc_strndup , +.Nm mandoc_asprintf +.Nd memory allocation function wrappers used in the mandoc library +.Sh SYNOPSIS +.In sys/types.h +.In mandoc_aux.h +.Ft "void *" +.Fo mandoc_malloc +.Fa "size_t size" +.Fc +.Ft "void *" +.Fo mandoc_realloc +.Fa "void *ptr" +.Fa "size_t size" +.Fc +.Ft "void *" +.Fo mandoc_reallocarray +.Fa "void *ptr" +.Fa "size_t nmemb" +.Fa "size_t size" +.Fc +.Ft "void *" +.Fo mandoc_calloc +.Fa "size_t nmemb" +.Fa "size_t size" +.Fc +.Ft "void *" +.Fo mandoc_recallocarray +.Fa "void *ptr" +.Fa "size_t oldnmemb" +.Fa "size_t nmemb" +.Fa "size_t size" +.Fc +.Ft "char *" +.Fo mandoc_strdup +.Fa "const char *s" +.Fc +.Ft "char *" +.Fo mandoc_strndup +.Fa "const char *s" +.Fa "size_t maxlen" +.Fc +.Ft int +.Fo mandoc_asprintf +.Fa "char **ret" +.Fa "const char *format" +.Fa "..." +.Fc +.Sh DESCRIPTION +These functions call the libc functions of the same names, passing +through their return values when successful. +In case of failure, they do not return, but instead call +.Xr err 3 . +They can be used both internally by any code in the mandoc libraries +and externally by programs using that library, for example +.Xr mandoc 1 , +.Xr man 1 , +.Xr apropos 1 , +.Xr makewhatis 8 , +and +.Xr man.cgi 8 . +.Pp +The function +.Fn mandoc_malloc +allocates one new object, leaving the memory uninitialized. +The functions +.Fn mandoc_realloc , +.Fn mandoc_reallocarray , +and +.Fn mandoc_recallocarray +change the size of an existing object or array, possibly moving it. +When shrinking the size, existing data is truncated; when growing, +only +.Fn mandoc_recallocarray +initializes the new elements to zero. +The function +.Fn mandoc_calloc +allocates a new array, initializing it to zero. +.Pp +The argument +.Fa size +is the size of each object. +The argument +.Fa nmemb +is the new number of objects in the array. +The argument +.Fa oldnmemb +is the number of objects in the array before the call. +The argument +.Fa ptr +is a pointer to the existing object or array to be resized; if it is +.Dv NULL , +a new object or array is allocated. +.Pp +The functions +.Fn mandoc_strdup +and +.Fn mandoc_strndup +copy a string into newly allocated memory. +For +.Fn mandoc_strdup , +the string pointed to by +.Fa s +needs to be NUL-terminated. +For +.Fn mandoc_strndup , +at most +.Fa maxlen +bytes are copied. +The function +.Fn mandoc_asprintf +writes output formatted according to +.Fa format +into newly allocated memory and returns a pointer to the result in +.Fa ret . +For all three string functions, the result is always NUL-terminated. +.Pp +When the objects and strings are no longer needed, +the pointers returned by these functions can be passed to +.Xr free 3 . +.Sh RETURN VALUES +The function +.Fn mandoc_asprintf +always returns the number of characters written, excluding the +final NUL byte. +It never returns -1. +.Pp +The other functions always return a valid pointer; they never return +.Dv NULL . +.Sh FILES +These functions are implemented in +.Pa mandoc_aux.c . +.Sh SEE ALSO +.Xr asprintf 3 , +.Xr err 3 , +.Xr malloc 3 , +.Xr strdup 3 +.Sh STANDARDS +The functions +.Fn malloc , +.Fn realloc , +and +.Fn calloc +are required by +.St -ansiC . +The functions +.Fn strdup +and +.Fn strndup +are required by +.St -p1003.1-2008 . +The function +.Fn asprintf +is a widespread extension that first appeared in the GNU C library. +.Pp +The function +.Fn reallocarray +is an extension that first appeared in +.Ox 5.6 , +and +.Fn recallocarray +in +.Ox 6.1 . +If these two are not provided by the operating system, +the mandoc build system uses bundled portable implementations. +.Sh HISTORY +The functions +.Fn mandoc_malloc , +.Fn mandoc_realloc , +.Fn mandoc_calloc , +and +.Fn mandoc_strdup +have been available since mandoc 1.9.12, +.Fn mandoc_strndup +since 1.11.5, +.Fn mandoc_asprintf +since 1.12.4, +.Fn mandoc_reallocarray +since 1.13.0, and +.Fn mandoc_recallocarray +since 1.14.2. +.Sh AUTHORS +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +.An Ingo Schwarze Aq Mt schwarze@openbsd.org diff --git a/static/netbsd/man3/mansearch.3 b/static/netbsd/man3/mansearch.3 new file mode 100644 index 00000000..1db31979 --- /dev/null +++ b/static/netbsd/man3/mansearch.3 @@ -0,0 +1,120 @@ +.\" Id: mansearch.3,v 1.5 2017/03/30 22:22:05 schwarze Exp +.\" +.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd March 30, 2017 +.Dt MANSEARCH 3 +.Os +.Sh NAME +.Nm mansearch +.Nd search manual page databases +.Sh SYNOPSIS +.In stdint.h +.In manconf.h +.In mansearch.h +.Ft int +.Fo mansearch +.Fa "const struct mansearch *search" +.Fa "const struct manpaths *paths" +.Fa "int argc" +.Fa "char *argv[]" +.Fa "struct manpage **res" +.Fa "size_t *sz" +.Fc +.Sh DESCRIPTION +The +.Fn mansearch +function returns information about manuals matching a search query from a +.Xr mandoc.db 5 +database. +.Pp +The query arguments are as follows: +.Bl -tag -width Ds +.It Fa "const struct mansearch *search" +Search options, defined in +.In mansearch.h . +.It Fa "const struct manpaths *paths" +Directories to be searched, defined in +.In manconf.h . +.It Fa "int argc" , "char *argv[]" +Search criteria, usually taken from the command line. +.El +.Pp +The output arguments are as follows: +.Bl -tag -width Ds +.It Fa "struct manpage **res" +Returns a pointer to an array of result structures defined in +.In mansearch.h . +The user is expected to call +.Xr free 3 +on the +.Va file , +.Va names , +and +.Va output +fields of all structures, as well as the +.Fa res +array itself. +.It Fa "size_t *sz" +Returns the number of result structures contained in +.Fa res . +.El +.Sh IMPLEMENTATION NOTES +For each manual page tree, the search is done in two steps. +In the first step, a list of pages matching the search criteria is built. +In the second step, the requested information about these pages is +retrieved from the database and assembled into the +.Fa res +array. +.Pp +All function mentioned here are defined in the file +.Pa mansearch.c . +.Ss Finding matches +Command line parsing is done by the function +.Fn exprcomp +building a singly linked list of +.Vt expr +structures, using the helper functions +.Fn expr_and +and +.Fn exprterm . +.Ss Assembling the results +The names, sections, and architectures of the manuals found +are assembled into the +.Va names +field of the result structure by the function +.Fn buildnames . +.Sh FILES +.Bl -tag -width mandoc.db -compact +.It Pa mandoc.db +The manual page database. +.El +.Sh SEE ALSO +.Xr apropos 1 , +.Xr mandoc.db 5 , +.Xr makewhatis 8 +.Sh HISTORY +The +.Fn mansearch +subsystem first appeared in +.Ox 5.6 . +.Sh AUTHORS +.An -nosplit +A module to search manual page databases was first written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +in 2011, at first using the Berkeley DB; +he rewrote it for SQLite3 in 2012, and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org +removed the dependency on SQLite3 in 2016. diff --git a/static/netbsd/man3/math.3 b/static/netbsd/man3/math.3 new file mode 100644 index 00000000..98f30d0e --- /dev/null +++ b/static/netbsd/man3/math.3 @@ -0,0 +1,587 @@ +.\" $NetBSD: math.3,v 1.29 2023/05/08 01:28:35 christos Exp $ +.\" +.\" Copyright (c) 1985 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)math.3 6.10 (Berkeley) 5/6/91 +.\" +.Dd May 7, 2023 +.Dt MATH 3 +.Os +.Sh NAME +.Nm math +.Nd introduction to mathematical library functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Sh DESCRIPTION +These functions constitute the C +.Lb libm . +Declarations for these functions may be obtained from the include file +.In math.h . +.\" The Fortran math library is described in ``man 3f intro''. +.Ss List of Functions +.Bl -column "copysignX" "gammaX3XX" "inverse trigonometric funcX" +.It Sy Name Ta Sy Man page Ta Sy Description Ta Sy Error Bound Dv ( ULP Ns No s) +.It acos Ta Xr acos 3 Ta inverse trigonometric function Ta 3 +.It acosh Ta Xr acosh 3 Ta inverse hyperbolic function Ta 3 +.It asin Ta Xr asin 3 Ta inverse trigonometric function Ta 3 +.It asinh Ta Xr asinh 3 Ta inverse hyperbolic function Ta 3 +.It atan Ta Xr atan 3 Ta inverse trigonometric function Ta 1 +.It atanh Ta Xr atanh 3 Ta inverse hyperbolic function Ta 3 +.It atan2 Ta Xr atan2 3 Ta inverse trigonometric function Ta 2 +.It cbrt Ta Xr sqrt 3 Ta cube root Ta 1 +.It ceil Ta Xr ceil 3 Ta integer no less than Ta 0 +.It copysign Ta Xr copysign 3 Ta copy sign bit Ta 0 +.It cos Ta Xr cos 3 Ta trigonometric function Ta 1 +.It cosh Ta Xr cosh 3 Ta hyperbolic function Ta 3 +.It erf Ta Xr erf 3 Ta error function Ta ??? +.It erfc Ta Xr erf 3 Ta complementary error function Ta ??? +.It exp Ta Xr exp 3 Ta base e exponential Ta 1 +.It exp2 Ta Xr exp2 3 Ta base 2 exponential Ta ??? +.It expm1 Ta Xr expm1 3 Ta exp(x)\-1 Ta 1 +.It fabs Ta Xr fabs 3 Ta absolute value Ta 0 +.It fdim Ta Xr fdim 3 Ta positive difference Ta ??? +.It finite Ta Xr finite 3 Ta test for finity Ta 0 +.It floor Ta Xr floor 3 Ta integer no greater than Ta 0 +.It fma Ta Xr fma 3 Ta fused multiply-add Ta ??? +.It fmax Ta Xr fmax 3 Ta maximum Ta 0 +.It fmin Ta Xr fmin 3 Ta minimum Ta 0 +.It fmod Ta Xr fmod 3 Ta remainder Ta ??? +.It hypot Ta Xr hypot 3 Ta Euclidean distance Ta 1 +.It ilogb Ta Xr ilogb 3 Ta exponent extraction Ta 0 +.It isinf Ta Xr isinf 3 Ta test for infinity Ta 0 +.It isnan Ta Xr isnan 3 Ta test for not-a-number Ta 0 +.It j0 Ta Xr j0 3 Ta Bessel function Ta ??? +.It j1 Ta Xr j0 3 Ta Bessel function Ta ??? +.It jn Ta Xr j0 3 Ta Bessel function Ta ??? +.It lgamma Ta Xr lgamma 3 Ta log gamma function Ta ??? +.It log Ta Xr log 3 Ta natural logarithm Ta 1 +.It log10 Ta Xr log 3 Ta logarithm to base 10 Ta 3 +.It log1p Ta Xr log 3 Ta log(1+x) Ta 1 +.It nan Ta Xr nan 3 Ta return quiet \*(Na Ta 0 +.It nextafter Ta Xr nextafter 3 Ta next representable number Ta 0 +.It pow Ta Xr pow 3 Ta exponential x**y Ta 60\-500 +.It remainder Ta Xr remainder 3 Ta remainder Ta 0 +.It rint Ta Xr rint 3 Ta round to nearest integer Ta 0 +.It scalbn Ta Xr scalbn 3 Ta exponent adjustment Ta 0 +.It sin Ta Xr sin 3 Ta trigonometric function Ta 1 +.It sinh Ta Xr sinh 3 Ta hyperbolic function Ta 3 +.It sqrt Ta Xr sqrt 3 Ta square root Ta 1 +.It tan Ta Xr tan 3 Ta trigonometric function Ta 3 +.It tanh Ta Xr tanh 3 Ta hyperbolic function Ta 3 +.It trunc Ta Xr trunc 3 Ta nearest integral value Ta 3 +.It y0 Ta Xr j0 3 Ta Bessel function Ta ??? +.It y1 Ta Xr j0 3 Ta Bessel function Ta ??? +.It yn Ta Xr j0 3 Ta Bessel function Ta ??? +.El +.Ss List of Defined Values +.Bl -column "M_2_SQRTPIXX" "1.12837916709551257390XX" "2/sqrt(pi)XXX" +.It Sy Name Ta Sy Value Ta Sy Description +.It M_E 2.7182818284590452354 e +.It M_LOG2E 1.4426950408889634074 log 2e +.It M_LOG10E 0.43429448190325182765 log 10e +.It M_LN2 0.69314718055994530942 log e2 +.It M_LN10 2.30258509299404568402 log e10 +.It M_PI 3.14159265358979323846 pi +.It M_PI_2 1.57079632679489661923 pi/2 +.It M_PI_4 0.78539816339744830962 pi/4 +.It M_1_PI 0.31830988618379067154 1/pi +.It M_2_PI 0.63661977236758134308 2/pi +.It M_2_SQRTPI 1.12837916709551257390 2/sqrt(pi) +.It M_SQRT2 1.41421356237309504880 sqrt(2) +.It M_SQRT1_2 0.70710678118654752440 1/sqrt(2) +.El +.Sh NOTES +In 4.3 BSD, distributed from the University of California +in late 1985, most of the foregoing functions come in two +versions, one for the double\-precision "D" format in the +DEC VAX\-11 family of computers, another for double\-precision +arithmetic conforming to the IEEE Standard 754 for Binary +Floating\-Point Arithmetic. +The two versions behave very +similarly, as should be expected from programs more accurate +and robust than was the norm when UNIX was born. +For instance, the programs are accurate to within the numbers +of +.Dv ULPs +tabulated above; an +.Dv ULP +is one Unit in the Last Place. +And the programs have been cured of anomalies that +afflicted the older math library +in which incidents like +the following had been reported: +.Bd -literal -offset indent +sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38. +cos(1.0e\-11) > cos(0.0) > 1.0. +pow(x,1.0) \(!= x when x = 2.0, 3.0, 4.0, ..., 9.0. +pow(\-1.0,1.0e10) trapped on Integer Overflow. +sqrt(1.0e30) and sqrt(1.0e\-30) were very slow. +.Ed +However the two versions do differ in ways that have to be +explained, to which end the following notes are provided. +.Ss DEC VAX\-11 D_floating\-point +This is the format for which the original math library +was developed, and to which this manual is still principally dedicated. +It is +.Em the +double\-precision format for the PDP\-11 +and the earlier VAX\-11 machines; VAX\-11s after 1983 were +provided with an optional "G" format closer to the IEEE +double\-precision format. +The earlier DEC MicroVAXs have no D format, only G double\-precision. +(Why? +Why not?) +.Pp +Properties of D_floating\-point: +.Bl -hang -offset indent +.It Wordsize : +64 bits, 8 bytes. +.It Radix : +Binary. +.It Precision : +56 significant bits, roughly like 17 significant decimals. +If x and x' are consecutive positive D_floating\-point +numbers (they differ by 1 +.Dv ULP ) , +then +.Dl 1.3e\-17 < 0.5**56 < (x'\-x)/x \*[Le] 0.5**55 < 2.8e\-17. +.It Range : +.Bl -column "Underflow thresholdX" "2.0**127X" +.It Overflow threshold = 2.0**127 = 1.7e38. +.It Underflow threshold = 0.5**128 = 2.9e\-39. +.El +.Em NOTE: THIS RANGE IS COMPARATIVELY NARROW. +.Pp +Overflow customarily stops computation. +Underflow is customarily flushed quietly to zero. +.Em CAUTION : +It is possible to have x +\(!= +y and yet x\-y = 0 because of underflow. +Similarly x > y > 0 cannot prevent either x\(**y = 0 +or y/x = 0 from happening without warning. +.It Zero is represented ambiguously : +Although 2**55 different representations of zero are accepted by +the hardware, only the obvious representation is ever produced. +There is no \-0 on a VAX. +.It \*(If is not part of the VAX architecture . +.It Reserved operands : +of the 2**55 that the hardware +recognizes, only one of them is ever produced. +Any floating\-point operation upon a reserved +operand, even a MOVF or MOVD, customarily stops +computation, so they are not much used. +.It Exceptions : +Divisions by zero and operations that +overflow are invalid operations that customarily +stop computation or, in earlier machines, produce +reserved operands that will stop computation. +.It Rounding : +Every rational operation (+, \-, \(**, /) on a +VAX (but not necessarily on a PDP\-11), if not an +over/underflow nor division by zero, is rounded to +within half an +.Dv ULP , +and when the rounding error is +exactly half an +.Dv ULP +then rounding is away from 0. +.El +.Pp +Except for its narrow range, D_floating\-point is one of the +better computer arithmetics designed in the 1960's. +Its properties are reflected fairly faithfully in the elementary +functions for a VAX distributed in 4.3 BSD. +They over/underflow only if their results have to lie out of range +or very nearly so, and then they behave much as any rational +arithmetic operation that over/underflowed would behave. +Similarly, expressions like log(0) and atanh(1) behave +like 1/0; and sqrt(\-3) and acos(3) behave like 0/0; +they all produce reserved operands and/or stop computation! +The situation is described in more detail in manual pages. +.Pp +.Em This response seems excessively punitive, so it is destined +.Em to be replaced at some time in the foreseeable future by a +.Em more flexible but still uniform scheme being developed to +.Em handle all floating\-point arithmetic exceptions neatly. +.Pp +How do the functions in 4.3 BSD's new math library for UNIX +compare with their counterparts in DEC's VAX/VMS library? +Some of the VMS functions are a little faster, some are +a little more accurate, some are more puritanical about +exceptions (like pow(0.0,0.0) and atan2(0.0,0.0)), +and most occupy much more memory than their counterparts in +libm. +The VMS codes interpolate in large table to achieve +speed and accuracy; the libm codes use tricky formulas +compact enough that all of them may some day fit into a ROM. +.Pp +More important, DEC regards the VMS codes as proprietary +and guards them zealously against unauthorized use. +But the libm codes in 4.3 BSD are intended for the public domain; +they may be copied freely provided their provenance is always +acknowledged, and provided users assist the authors in their +researches by reporting experience with the codes. +Therefore no user of UNIX on a machine whose arithmetic resembles +VAX D_floating\-point need use anything worse than the new libm. +.Ss IEEE STANDARD 754 Floating\-Point Arithmetic +This standard is on its way to becoming more widely adopted +than any other design for computer arithmetic. +VLSI chips that conform to some version of that standard have been +produced by a host of manufacturers, among them ... +.Bl -column "Intel i8070, i80287XX" +.It Intel i8087, i80287 National Semiconductor 32081 +.It 68881 Weitek WTL-1032, ... , -1165 +.It Zilog Z8070 Western Electric (AT&T) WE32106. +.El +Other implementations range from software, done thoroughly +in the Apple Macintosh, through VLSI in the Hewlett\-Packard +9000 series, to the ELXSI 6400 running ECL at 3 Megaflops. +Several other companies have adopted the formats +of IEEE 754 without, alas, adhering to the standard's way +of handling rounding and exceptions like over/underflow. +The DEC VAX G_floating\-point format is very similar to the IEEE +754 Double format, so similar that the C programs for the +IEEE versions of most of the elementary functions listed +above could easily be converted to run on a MicroVAX, though +nobody has volunteered to do that yet. +.Pp +The codes in 4.3 BSD's libm for machines that conform to +IEEE 754 are intended primarily for the National Semiconductor 32081 +and WTL 1164/65. +To use these codes with the Intel or Zilog +chips, or with the Apple Macintosh or ELXSI 6400, is to +forego the use of better codes provided (perhaps freely) by +those companies and designed by some of the authors of the +codes above. +Except for +.Fn atan , +.Fn cbrt , +.Fn erf , +.Fn erfc , +.Fn hypot , +.Fn j0-jn , +.Fn lgamma , +.Fn pow , +and +.Fn y0\-yn , +the Motorola 68881 has all the functions in libm on chip, +and faster and more accurate; +it, Apple, the i8087, Z8070 and WE32106 all use 64 significant bits. +The main virtue of 4.3 BSD's +libm codes is that they are intended for the public domain; +they may be copied freely provided their provenance is always +acknowledged, and provided users assist the authors in their +researches by reporting experience with the codes. +Therefore no user of UNIX on a machine that conforms to +IEEE 754 need use anything worse than the new libm. +.Pp +Properties of IEEE 754 Double\-Precision: +.Bl -hang -offset indent +.It Wordsize : +64 bits, 8 bytes. +.It Radix : +Binary. +.It Precision : +53 significant bits, roughly like 16 significant decimals. +If x and x' are consecutive positive Double\-Precision +numbers (they differ by 1 +.Dv ULP ) , +then +.Dl 1.1e\-16 < 0.5**53 < (x'\-x)/x \*[Le] 0.5**52 < 2.3e\-16. +.It Range : +.Bl -column "Underflow thresholdX" "2.0**1024X" +.It Overflow threshold = 2.0**1024 = 1.8e308 +.It Underflow threshold = 0.5**1022 = 2.2e\-308 +.El +Overflow goes by default to a signed \*(If. +Underflow is +.Sy Gradual , +rounding to the nearest +integer multiple of 0.5**1074 = 4.9e\-324. +.It Zero is represented ambiguously as +0 or \-0: +Its sign transforms correctly through multiplication or +division, and is preserved by addition of zeros +with like signs; but x\-x yields +0 for every +finite x. +The only operations that reveal zero's +sign are division by zero and copysign(x,\(+-0). +In particular, comparison (x > y, x \*[Ge] y, etc.) +cannot be affected by the sign of zero; but if +finite x = y then \*(If +\&= 1/(x\-y) +\(!= +\-1/(y\-x) = +\- \*(If . +.It \*(If is signed : +it persists when added to itself +or to any finite number. +Its sign transforms +correctly through multiplication and division, and +\*(If (finite)/\(+- \0=\0\(+-0 +(nonzero)/0 = +\(+- \*(If. +But +\(if\-\(if, \(if\(**0 and \(if/\(if +are, like 0/0 and sqrt(\-3), +invalid operations that produce \*(Na. +.It Reserved operands : +there are 2**53\-2 of them, all +called \*(Na (Not A Number). +Some, called Signaling \*[Na]s, trap any floating\-point operation +performed upon them; they are used to mark missing +or uninitialized values, or nonexistent elements of arrays. +The rest are Quiet \*[Na]s; they are +the default results of Invalid Operations, and +propagate through subsequent arithmetic operations. +If x +\(!= +x then x is \*(Na; every other predicate +(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved. +.Pp +.Em NOTE : +Trichotomy is violated by \*(Na. +Besides being FALSE, predicates that entail ordered +comparison, rather than mere (in)equality, +signal Invalid Operation when \*(Na is involved. +.It Rounding : +Every algebraic operation (+, \-, \(**, /, +\(sr) +is rounded by default to within half an +.Dv ULP , +and when the rounding error is exactly half an +.Dv ULP +then the rounded value's least significant bit is zero. +This kind of rounding is usually the best kind, +sometimes provably so; for instance, for every +x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find +(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ... +despite that both the quotients and the products +have been rounded. +Only rounding like IEEE 754 can do that. +But no single kind of rounding can be +proved best for every circumstance, so IEEE 754 +provides rounding towards zero or towards ++\*(If +or towards +\-\*(If +at the programmer's option. +And the same kinds of rounding are specified for +Binary\-Decimal Conversions, at least for magnitudes +between roughly 1.0e\-10 and 1.0e37. +.It Exceptions : +IEEE 754 recognizes five kinds of floating\-point exceptions, +listed below in declining order of probable importance. +.Bl -column "Invalid OperationX" "Gradual OverflowX" +.It Sy Exception Ta Sy Default Result +.It Invalid Operation \*(Na, or FALSE +.It Overflow \(+-\(if +.It Divide by Zero \(+-\(if \} +.It Underflow Gradual Underflow +.It Inexact Rounded value +.El +.Pp +.Em NOTE : +An Exception is not an Error unless handled badly. +What makes a class of exceptions exceptional +is that no single default response can be satisfactory +in every instance. +On the other hand, if a default +response will serve most instances satisfactorily, +the unsatisfactory instances cannot justify aborting +computation every time the exception occurs. +.El +.Pp +For each kind of floating\-point exception, IEEE 754 +provides a Flag that is raised each time its exception +is signaled, and stays raised until the program resets it. +Programs may also test, save and restore a flag. +Thus, IEEE 754 provides three ways by which programs +may cope with exceptions for which the default result +might be unsatisfactory: +.Bl -enum +.It +Test for a condition that might cause an exception +later, and branch to avoid the exception. +.It +Test a flag to see whether an exception has occurred +since the program last reset its flag. +.It +Test a result to see whether it is a value that only +an exception could have produced. +.Em CAUTION : +The only reliable ways to discover +whether Underflow has occurred are to test whether +products or quotients lie closer to zero than the +underflow threshold, or to test the Underflow flag. +(Sums and differences cannot underflow in +IEEE 754; if x +\(!= +y then x\-y is correct to +full precision and certainly nonzero regardless of +how tiny it may be.) +Products and quotients that +underflow gradually can lose accuracy gradually +without vanishing, so comparing them with zero +(as one might on a VAX) will not reveal the loss. +Fortunately, if a gradually underflowed value is +destined to be added to something bigger than the +underflow threshold, as is almost always the case, +digits lost to gradual underflow will not be missed +because they would have been rounded off anyway. +So gradual underflows are usually +.Em provably +ignorable. +The same cannot be said of underflows flushed to 0. +.Pp +At the option of an implementor conforming to IEEE 754, +other ways to cope with exceptions may be provided: +.It +ABORT. +This mechanism classifies an exception in +advance as an incident to be handled by means +traditionally associated with error\-handling +statements like "ON ERROR GO TO ...". +Different languages offer different forms of this statement, +but most share the following characteristics: +.Bl -dash +.It +No means is provided to substitute a value for +the offending operation's result and resume +computation from what may be the middle of an expression. +An exceptional result is abandoned. +.It +In a subprogram that lacks an error\-handling +statement, an exception causes the subprogram to +abort within whatever program called it, and so +on back up the chain of calling subprograms until +an error\-handling statement is encountered or the +whole task is aborted and memory is dumped. +.El +.It +STOP. +This mechanism, requiring an interactive +debugging environment, is more for the programmer +than the program. +It classifies an exception in +advance as a symptom of a programmer's error; the +exception suspends execution as near as it can to +the offending operation so that the programmer can +look around to see how it happened. +Quite often +the first several exceptions turn out to be quite +unexceptionable, so the programmer ought ideally +to be able to resume execution after each one as if +execution had not been stopped. +.It +\&... Other ways lie beyond the scope of this document. +.El +.Pp +The crucial problem for exception handling is the problem of +Scope, and the problem's solution is understood, but not +enough manpower was available to implement it fully in time +to be distributed in 4.3 BSD's libm. +Ideally, each elementary function should act +as if it were indivisible, or atomic, in the sense that ... +.Bl -enum +.It +No exception should be signaled that is not deserved by +the data supplied to that function. +.It +Any exception signaled should be identified with that +function rather than with one of its subroutines. +.It +The internal behavior of an atomic function should not +be disrupted when a calling program changes from +one to another of the five or so ways of handling +exceptions listed above, although the definition +of the function may be correlated intentionally +with exception handling. +.El +.Pp +Ideally, every programmer should be able +.Em conveniently +to turn a debugged subprogram into one that appears atomic to +its users. +But simulating all three characteristics of an +atomic function is still a tedious affair, entailing hosts +of tests and saves\-restores; work is under way to ameliorate +the inconvenience. +.Pp +Meanwhile, the functions in libm are only approximately atomic. +They signal no inappropriate exception except possibly ... +.Bl -ohang -offset indent +.It Over/Underflow +when a result, if properly computed, might have lain barely within range, and +.It Inexact in Fn cbrt , Fn hypot , Fn log10 No and Fn pow +when it happens to be exact, thanks to fortuitous cancellation of errors. +.El +Otherwise, ... +.Bl -ohang -offset indent +.It Invalid Operation is signaled only when +any result but \*(Na would probably be misleading. +.It Overflow is signaled only when +the exact result would be finite but beyond the overflow threshold. +.It Divide\-by\-Zero is signaled only when +a function takes exactly infinite values at finite operands. +.It Underflow is signaled only when +the exact result would be nonzero but tinier than the underflow threshold. +.It Inexact is signaled only when +greater range or precision would be needed to represent the exact result. +.El +.\" .Sh FILES +.\" .Bl -tag -width /usr/lib/libm_p.a -compact +.\" .It Pa /usr/lib/libm.a +.\" the static math library +.\" .It Pa /usr/lib/libm.so +.\" the dynamic math library +.\" .It Pa /usr/lib/libm_p.a +.\" the static math library compiled for profiling +.\" .El +.Sh SEE ALSO +An explanation of IEEE 754 and its proposed extension p854 +was published in the IEEE magazine MICRO in August 1984 under +the title "A Proposed Radix\- and Word\-length\-independent +Standard for Floating\-point Arithmetic" by W. J. Cody et al. +The manuals for Pascal, C and BASIC on the Apple Macintosh +document the features of IEEE 754 pretty well. +Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar. 1981), +and in the ACM SIGNUM Newsletter Special Issue of +Oct. 1979, may be helpful although they pertain to +superseded drafts of the standard. +.Sh BUGS +When signals are appropriate, they are emitted by certain +operations within the codes, so a subroutine\-trace may be +needed to identify the function with its signal in case +method 5) above is in use. +And the codes all take the +IEEE 754 defaults for granted; this means that a decision to +trap all divisions by zero could disrupt a code that would +otherwise get correct results despite division by zero. diff --git a/static/netbsd/man3/mblen.3 b/static/netbsd/man3/mblen.3 new file mode 100644 index 00000000..39947827 --- /dev/null +++ b/static/netbsd/man3/mblen.3 @@ -0,0 +1,181 @@ +.\" $NetBSD: mblen.3,v 1.7 2024/02/03 10:55:38 rillig Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2024 +.Dt MBLEN 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mblen +.Nd get number of bytes in a multibyte character +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mblen "const char *s" "size_t n" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mblen +function usually determines the number of bytes in +a multibyte character pointed to by +.Fa s +and returns it. +This function examines at most +.Fa n +bytes of the array beginning from +.Fa s . +.Pp +In state-dependent encodings, +.Fa s +may point to the special sequence bytes to change the shift-state. +Although such sequence bytes corresponds to no individual +wide-character code, +the +.Fn mblen +function changes its own state by them and treats them +as if they were part of the subsequent multibyte character. +.Pp +Unlike +.Xr mbrlen 3 , +the first +.Fa n +bytes pointed to by +.Fa s +need to form an entire multibyte character. +Otherwise, this function causes an error. +.Pp +.Fn mblen +is equivalent to the following call, except the internal state of the +.Xr mbtowc 3 +function is not affected: +.Bd -literal -offset indent +mbtowc(NULL, s, n); +.Ed +.Pp +Calling any other functions in +.Lb libc +never changes the internal +state of +.Fn mblen , +except for calling +.Xr setlocale 3 +with the +.Dv LC_CTYPE +category changed to that of the current locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to be indeterminate. +.Pp +The behaviour of +.Fn mblen +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 0123456789 +.It "s == NULL" +.Fn mblen +initializes its own internal state to an initial state, and +determines whether the current encoding is state-dependent. +This function returns 0 if the encoding is state-independent, +otherwise non-zero. +.It "n == 0" +The first +.Fa n +bytes of the array pointed to by +.Fa s +never form a complete character. +Thus, +.Fn mblen +always fails. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +Normally, +.Fn mblen +returns: +.Bl -tag -width 0123456789 +.It "0" +.Fa s +points to a nul byte +.Pq Sq \e0 . +.It "positive" +The value returned is +the number of bytes for the valid multibyte character pointed to by +.Fa s . +The value returned is at most +.Fa n , +and at most the value of the +.Dv MB_CUR_MAX +macro. +.It "-1" +.Fa s +points to an invalid or incomplete multibyte character. +The +.Fn mblen +function also sets +.Va errno +to indicate the error. +.El +.Pp +When +.Fa s +is equal to +.Dv NULL , +the +.Fn mblen +function returns: +.Bl -tag -width 0123456789 +.It "0" +The current encoding is state-independent. +.It "non-zero" +The current encoding is state-dependent. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mblen +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid or incomplete multibyte character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbrlen 3 , +.Xr mbtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mblen +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/mbrlen.3 b/static/netbsd/man3/mbrlen.3 new file mode 100644 index 00000000..84010128 --- /dev/null +++ b/static/netbsd/man3/mbrlen.3 @@ -0,0 +1,206 @@ +.\" $NetBSD: mbrlen.3,v 1.10 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2002 +.Dt MBRLEN 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbrlen +.Nd get number of bytes in a multibyte character (restartable) +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mbrlen +function usually determines the number of bytes in +a multibyte character pointed to by +.Fa s +and returns it. +This function shall only examine max n bytes of the array beginning from +.Fa s . +.Pp +.Fn mbrlen +is equivalent to the following call (except +.Fa ps +is evaluated only once): +.Bd -literal -offset indent +mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal); +.Ed +.Pp +Here, +.Fa internal +is an internal state object. +.Pp +In state-dependent encodings, +.Fa s +may point to the special sequence bytes to change the shift-state. +Although such sequence bytes corresponds to no individual +wide-character code, these affect the conversion state object pointed +to by +.Fa ps , +and the +.Fn mbrlen +treats the special sequence bytes +as if these are a part of the subsequent multibyte character. +.Pp +Unlike +.Xr mblen 3 , +.Fn mbrlen +may accept the byte sequence when it is not a complete character +but possibly contains part of a valid character. +In this case, this function will accept all such bytes +and save them into the conversion state object pointed to by +.Fa ps . +They will be used on subsequent calls of this function to restart +the conversion suspended. +.Pp +The behaviour of +.Fn mbrlen +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 0123456789 +.It "s == NULL" +.Fn mbrlen +sets the conversion state object pointed to by +.Fa ps +to an initial state and always returns 0. +Unlike +.Xr mblen 3 , +the value returned does not indicate whether the current encoding of +the locale is state-dependent. +.Pp +In this case, +.Fn mbrlen +ignores +.Fa n . +.It "n == 0" +In this case, +the first +.Fa n +bytes of the array pointed to by +.Fa s +never form a complete character. +Thus, +.Fn mbrlen +always returns (size_t)-2. +.It "ps == NULL" +.Fn mbrlen +uses its own internal state object to keep the conversion state, +instead of +.Fa ps +mentioned in this manual page. +.Pp +Calling any other functions in +.Lb libc +never changes the internal +state of +.Fn mbrlen , +except for calling +.Xr setlocale 3 +with a changing +.Dv LC_CTYPE +category of the current locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to be indeterminate. +This internal state is initialized at startup time of the program. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn mbrlen +returns: +.Bl -tag -width 0123456789 +.It "0" +.Fa s +points to a nul byte +.Pq Sq \e0 . +.It "positive" +The value returned is +a number of bytes for the valid multibyte character pointed to by +.Fa s . +There are no cases that this value is greater than +.Fa n +or the value of the +.Dv MB_CUR_MAX +macro. +.It "(size_t)-2" +.Fa s +points to the byte sequence which possibly contains part of a valid +multibyte character, but which is incomplete. +When +.Fa n +is at least +.Dv MB_CUR_MAX , +this case can only occur if the array pointed to by +.Fa s +contains a redundant shift sequence. +.It "(size_t)-1" +.Fa s +points to an illegal byte sequence which does not form a valid multibyte +character. +In this case, +.Fn mbrtowc +sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbrlen +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid multibyte character. +.It Bq Er EINVAL +.Fa ps +points to an invalid or uninitialized mbstate_t object. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mblen 3 , +.Xr mbrtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbrlen +function conforms to +.St -isoC-amd1 . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/mbrtoc16.3 b/static/netbsd/man3/mbrtoc16.3 new file mode 100644 index 00000000..757b0324 --- /dev/null +++ b/static/netbsd/man3/mbrtoc16.3 @@ -0,0 +1,312 @@ +.\" $NetBSD: mbrtoc16.3,v 1.10 2024/08/23 12:59:49 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 14, 2024 +.Dt MBRTOC16 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm mbrtoc16 +.Nd Restartable multibyte to UTF-16 conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo mbrtoc16 +.Fa "char16_t * restrict pc16" +.Fa "const char * restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function decodes multibyte characters in the current locale and +converts them to UTF-16, keeping state so it can restart after +incremental progress. +.Pp +Each call to +.Nm : +.Bl -enum -compact +.It +examines up to +.Fa n +bytes starting at +.Fa s , +.It +yields a UTF-16 code unit if available by storing it at +.Li * Ns Fa pc16 , +.It +saves state at +.Fa ps , +and +.It +returns either the number of bytes consumed if any or a special return +value. +.El +.Pp +Specifically: +.Bl -bullet +.It +If the multibyte sequence at +.Fa s +is invalid after any previous input saved at +.Fa ps , +or if an error occurs in decoding, +.Nm +returns +.Li (size_t)-1 +and sets +.Xr errno 2 +to indicate the error. +.It +If the multibyte sequence at +.Fa s +is still incomplete after +.Fa n +bytes, including any previous input saved in +.Fa ps , +.Nm +saves its state in +.Fa ps +after all the input so far and returns +.Li "(size_t)-2". +.Sy All +.Fa n +bytes of input are consumed in this case. +.It +If +.Nm +had previously decoded a multibyte character but has not yet yielded +all the code units of its UTF-16 encoding, it stores the next UTF-16 +code unit at +.Li * Ns Fa pc16 +and returns +.Li "(size_t)-3" . +.Sy \&No +bytes of input are consumed in this case. +.It +If +.Nm +decodes the null multibyte character, then it stores zero at +.Li * Ns Fa pc16 +and returns zero. +.It +Otherwise, +.Nm +decodes a single multibyte character, stores the first (and possibly +only) code unit in its UTF-16 encoding at +.Li * Ns Fa pc16 , +and returns the number of bytes consumed to decode the first multibyte +character. +.El +.Pp +If +.Fa pc16 +is a null pointer, nothing is stored, but the effects on +.Fa ps +and the return value are unchanged. +.Pp +If +.Fa s +is a null pointer, the +.Nm +call is equivalent to: +.Bd -ragged -offset indent +.Fo mbrtoc16 +.Li NULL , +.Li \*q\*q , +.Li 1 , +.Fa ps +.Fc +.Ed +.Pp +This always returns zero, and has the effect of resetting +.Fa ps +to the initial conversion state, without writing to +.Fa pc16 , +even if it is nonnull. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by +.Xr mbrtoc8 3 , +.Xr mbrtoc32 3 , +.Xr c8rtomb 3 , +.Xr c16rtomb 3 , +and +.Xr c32rtomb 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh IMPLEMENTATION NOTES +On well-formed input, the +.Nm +function yields either a Unicode scalar value in the Basic Multilingual +Plane (BMP), i.e., a 16-bit Unicode code point that is not a surrogate +code point, or, over two successive calls, yields the high and low +surrogate code points (in that order) of a Unicode scalar value outside +the BMP. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns: +.Bl -tag -width Li +.It Li 0 +.Bq null +if +.Nm +decoded a null multibyte character. +.It Ar i +.Bq code unit +where +.Li 1 +\*(Le +.Ar i +\*(Le +.Fa n , +if +.Nm +consumed +.Ar i +bytes of input to decode the next multibyte character, yielding a +UTF-16 code unit. +.It Li (size_t)-3 +.Bq continuation +if +.Nm +consumed no new bytes of input but yielded a UTF-16 code unit that was +pending from previous input. +.It Li (size_t)-2 +.Bq incomplete +if +.Nm +found only an incomplete multibyte sequence after all +.Fa n +bytes of input and any previous input, and saved its state to restart +in the next call with +.Fa ps . +.It Li (size_t)-1 +.Bq error +if any encoding error was detected; +.Xr errno 2 +is set to reflect the error. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +Print the UTF-16 code units of a multibyte string in hexadecimal text: +.Bd -literal -offset indent +char *s = ...; +size_t n = ...; +mbstate_t mbs = {0}; /* initial conversion state */ + +while (n) { + char16_t c16; + size_t len; + + len = mbrtoc16(&c16, s, n, &mbs); + switch (len) { + case 0: /* NUL terminator */ + assert(c16 == 0); + goto out; + default: /* scalar value or high surrogate */ + printf("U+%04"PRIx16"\en", (uint16_t)c16); + break; + case (size_t)-3: /* low surrogate */ + printf("continue U+%04"PRIx16"\en", (uint16_t)c16); + break; + case (size_t)-2: /* incomplete */ + printf("incomplete\en"); + goto readmore; + case (size_t)-1: /* error */ + printf("error: %d\en", errno); + goto out; + } + s += len; + n -= len; +} +.Ed +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +The multibyte sequence cannot be decoded in the current locale as a +Unicode scalar value. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c16rtomb 3 , +.Xr c32rtomb 3 , +.Xr c8rtomb 3 , +.Xr mbrtoc32 3 , +.Xr mbrtoc8 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.Rs +.%A P. Hoffman +.%A F. Yergeau +.%T UTF-16, an encoding of ISO 10646 +.%R RFC 2781 +.%D February 2000 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc2781 +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh STANDARDS +The +.Nm +function conforms to +.St -isoC-2011 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man3/mbrtoc32.3 b/static/netbsd/man3/mbrtoc32.3 new file mode 100644 index 00000000..ca4d7e6d --- /dev/null +++ b/static/netbsd/man3/mbrtoc32.3 @@ -0,0 +1,271 @@ +.\" $NetBSD: mbrtoc32.3,v 1.9 2024/08/23 12:59:49 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 14, 2024 +.Dt MBRTOC32 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm mbrtoc32 +.Nd Restartable multibyte to UTF-32 conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo mbrtoc32 +.Fa "char32_t * restrict pc32" +.Fa "const char * restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function decodes multibyte characters in the current locale and +converts them to Unicode scalar values (i.e., to UTF-32), keeping state +so it can restart after incremental progress. +.Pp +Each call to +.Nm : +.Bl -enum -compact +.It +examines up to +.Fa n +bytes starting at +.Fa s , +.It +yields a Unicode scalar value (i.e., a UTF-32 code unit) if available +by storing it at +.Li * Ns Fa pc32 , +.It +saves state at +.Fa ps , +and +.It +returns either the number of bytes consumed if any or a special return +value. +.El +.Pp +Specifically: +.Bl -bullet +.It +If the multibyte sequence at +.Fa s +is invalid after any previous input saved at +.Fa ps , +or if an error occurs in decoding, +.Nm +returns +.Li (size_t)-1 +and sets +.Xr errno 2 +to indicate the error. +.It +If the multibyte sequence at +.Fa s +is still incomplete after +.Fa n +bytes, including any previous input saved in +.Fa ps , +.Nm +saves its state in +.Fa ps +after all the input so far and returns +.Li "(size_t)-2". +.It +If +.Nm +decodes the null multibyte character, then it stores zero at +.Li * Ns Fa pc32 +and returns zero. +.It +Otherwise, +.Nm +decodes a single multibyte character, stores its Unicode scalar value +at +.Li * Ns Fa pc32 , +and returns the number of bytes consumed to decode the first multibyte +character. +.El +.Pp +If +.Fa pc32 +is a null pointer, nothing is stored, but the effects on +.Fa ps +and the return value are unchanged. +.Pp +If +.Fa s +is a null pointer, the +.Nm +call is equivalent to: +.Bd -ragged -offset indent +.Fo mbrtoc32 +.Li NULL , +.Li \*q\*q , +.Li 1 , +.Fa ps +.Fc +.Ed +.Pp +This always returns zero, and has the effect of resetting +.Fa ps +to the initial conversion state, without writing to +.Fa pc32 , +even if it is nonnull. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by +.Xr mbrtoc8 3 , +.Xr mbrtoc16 3 , +.Xr c8rtomb 3 , +.Xr c16rtomb 3 , +and +.Xr c32rtomb 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns: +.Bl -tag -width Li +.It Li 0 +.Bq null +if +.Nm +decoded a null multibyte character. +.It Ar i +.Bq scalar value +where +.Li 0 +\*(Le +.Ar i +\*(Le +.Fa n , +if +.Nm +consumed +.Ar i +bytes of input to decode the next multibyte character, yielding a +Unicode scalar value. +.It Li (size_t)-2 +.Bq incomplete +if +.Nm +found only an incomplete multibyte sequence after all +.Fa n +bytes of input and any previous input, and saved its state to restart +in the next call with +.Fa ps . +.It Li (size_t)-1 +.Bq error +if any encoding error was detected; +.Xr errno 2 +is set to reflect the error. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +.Bd -literal -offset indent +char *s = ...; +size_t n = ...; +mbstate_t mbs = {0}; /* initial conversion state */ + +while (n) { + char32_t c32; + size_t len; + + len = mbrtoc32(&c32, s, n, &mbs); + switch (len) { + case 0: /* NUL terminator */ + assert(c32 == 0); + goto out; + default: /* scalar value */ + printf("U+%04"PRIx32"\en", (uint32_t)c32); + break; + case (size_t)-2: /* incomplete */ + printf("incomplete\en"); + goto readmore; + case (size_t)-1: /* error */ + printf("error: %d\en", errno); + goto out; + } + s += len; + n -= len; +} +.Ed +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +The multibyte sequence cannot be decoded in the current locale as a +Unicode scalar value. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c16rtomb 3 , +.Xr c32rtomb 3 , +.Xr c8rtomb 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc8 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh STANDARDS +The +.Nm +function conforms to +.St -isoC-2011 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man3/mbrtoc8.3 b/static/netbsd/man3/mbrtoc8.3 new file mode 100644 index 00000000..cb1abba6 --- /dev/null +++ b/static/netbsd/man3/mbrtoc8.3 @@ -0,0 +1,311 @@ +.\" $NetBSD: mbrtoc8.3,v 1.7 2024/08/23 12:59:49 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 15, 2024 +.Dt MBRTOC8 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm mbrtoc8 +.Nd Restartable multibyte to UTF-8 conversion +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh LIBRARY +.Lb libc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +. +.In uchar.h +. +.Ft size_t +.Fo mbrtoc8 +.Fa "char8_t * restrict pc8" +.Fa "const char * restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.Nm +function decodes multibyte characters in the current locale and +converts them to UTF-8, keeping state so it can restart after +incremental progress. +.Pp +Each call to +.Nm : +.Bl -enum -compact +.It +examines up to +.Fa n +bytes starting at +.Fa s , +.It +yields a UTF-8 code unit if available by storing it at +.Li * Ns Fa pc8 , +.It +saves state at +.Fa ps , +and +.It +returns either the number of bytes consumed if any or a special return +value. +.El +.Pp +Specifically: +.Bl -bullet +.It +If the multibyte sequence at +.Fa s +is invalid after any previous input saved at +.Fa ps , +or if an error occurs in decoding, +.Nm +returns +.Li (size_t)-1 +and sets +.Xr errno 2 +to indicate the error. +.It +If the multibyte sequence at +.Fa s +is still incomplete after +.Fa n +bytes, including any previous input saved in +.Fa ps , +.Nm +saves its state in +.Fa ps +after all the input so far and returns +.Li "(size_t)-2". +.Sy All +.Fa n +bytes of input are consumed in this case. +.It +If +.Nm +had previously decoded a multibyte character but has not yet yielded +all the code units of its UTF-8 encoding, it stores the next UTF-8 code +unit at +.Li * Ns Fa pc8 +and returns +.Li "(size_t)-3" . +.Sy \&No +input is consumed in this case. +.It +If +.Nm +decodes the null multibyte character, then it stores zero at +.Li * Ns Fa pc8 +and returns zero. +.It +Otherwise, +.Nm +decodes a single multibyte character, stores the first (and possibly +only) code unit in its UTF-8 encoding at +.Li * Ns Fa pc8 , +and returns the number of bytes consumed to decode the first multibyte +character. +.El +.Pp +If +.Fa pc8 +is a null pointer, nothing is stored, but the effects on +.Fa ps +and the return value are unchanged. +.Pp +If +.Fa s +is a null pointer, the +.Nm +call is equivalent to: +.Bd -ragged -offset indent +.Fo mbrtoc8 +.Li NULL , +.Li \*q\*q , +.Li 1 , +.Fa ps +.Fc +.Ed +.Pp +This always returns zero, and has the effect of resetting +.Fa ps +to the initial conversion state, without writing to +.Fa pc8 , +even if it is nonnull. +.Pp +If +.Fa ps +is a null pointer, +.Nm +uses an internal +.Vt mbstate_t +object with static storage duration, distinct from all other +.Vt mbstate_t +objects +.Po +including those used by +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 , +.Xr c8rtomb 3 , +.Xr c16rtomb 3 , +and +.Xr c32rtomb 3 +.Pc , +which is initialized at program startup to the initial conversion +state. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh IMPLEMENTATION NOTES +On well-formed input, the +.Nm +function yields either a Unicode scalar value in US-ASCII range, i.e., +a 7-bit Unicode code point, or, over two to four successive calls, the +leading and trailing code units in order of the UTF-8 encoding of a +Unicode scalar value outside the US-ASCII range. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh RETURN VALUES +The +.Nm +function returns: +.Bl -tag -width Li +.It Li 0 +.Bq null +if +.Nm +decoded a null multibyte character. +.It Ar i +.Bq code unit +where +.Li 1 +\*(Le +.Ar i +\*(Le +.Fa n , +if +.Nm +consumed +.Ar i +bytes of input to decode the next multibyte character, yielding a +UTF-8 code unit. +.It Li (size_t)-3 +.Bq continuation +if +.Nm +consumed no new bytes of input but yielded a UTF-8 code unit that was +pending from previous input. +.It Li (size_t)-2 +.Bq incomplete +if +.Nm +found only an incomplete multibyte sequence after all +.Fa n +bytes of input and any previous input, and saved its state to restart +in the next call with +.Fa ps . +.It Li (size_t)-1 +.Bq error +if any encoding error was detected; +.Xr errno 2 +is set to reflect the error. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh EXAMPLES +Print the UTF-8 code units of a multibyte string in hexadecimal text: +.Bd -literal -offset indent +char *s = ...; +size_t n = ...; +mbstate_t mbs = {0}; /* initial conversion state */ + +while (n) { + char8_t c8; + size_t len; + + len = mbrtoc8(&c8, s, n, &mbs); + switch (len) { + case 0: /* NUL terminator */ + assert(c8 == 0); + goto out; + default: /* consumed input and yielded a byte c8 */ + printf("0x%02hhx\en", c8); + break; + case (size_t)-3: /* yielded a pending byte c8 */ + printf("continue 0x%02hhx\en", c8); + break; + case (size_t)-2: /* incomplete */ + printf("incomplete\en"); + goto readmore; + case (size_t)-1: /* error */ + printf("error: %d\en", errno); + goto out; + } + s += len; + n -= len; +} +.Ed +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh ERRORS +.Bl -tag -width Bq +.It Bq Er EILSEQ +The multibyte sequence cannot be decoded in the current locale as a +Unicode scalar value. +.It Bq Er EIO +An error occurred in loading the locale's character conversions. +.El +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c8rtomb 3 , +.Xr c16rtomb 3 , +.Xr c32rtomb 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 , +.Xr uchar 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.Rs +.%A F. Yergeau +.%T UTF-8, a transformation format of ISO 10646 +.%R RFC 3629 +.%D November 2003 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc3629 +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" .Sh STANDARDS +.\" The +.\" .Nm +.\" function conforms to +.\" .St -isoC-2023 . +.\" .\" XXX PR misc/58600: man pages lack C17, C23, C++98, C++03, C++11, C++17, C++20, C++23 citation syntax +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man3/mbrtowc.3 b/static/netbsd/man3/mbrtowc.3 new file mode 100644 index 00000000..80f7a597 --- /dev/null +++ b/static/netbsd/man3/mbrtowc.3 @@ -0,0 +1,196 @@ +.\" $NetBSD: mbrtowc.3,v 1.8 2006/10/16 09:10:29 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 4, 2002 +.Dt MBRTOWC 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbrtowc +.Nd converts a multibyte character to a wide character (restartable) +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" \ +"mbstate_t * restrict ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mbrtowc +usually converts the multibyte character pointed to by +.Fa s +to a wide character, and stores the wide character +to the wchar_t object pointed to by +.Fa pwc +if +.Fa pwc +is +.Pf non- Dv NULL +and +.Fa s +points to a valid character. +The conversion happens in accordance with, and changes the conversion +state described in the mbstate_t object pointed to by +.Fa ps . +This function may examine at most +.Fa n +bytes of the array beginning from +.Fa s . +.Pp +If +.Fa s +points to a valid character and the character corresponds to a nul wide +character, then the +.Fn mbrtowc +places the mbstate_t object pointed to by +.Fa ps +to an initial conversion state. +.Pp +Unlike +.Xr mbtowc 3 , +the +.Fn mbrtowc +may accept the byte sequence pointed to by +.Fa s +not forming a complete multibyte character +but which may be part of a valid character. +In this case, this function will accept all such bytes +and save them into the conversion state object pointed to by +.Fa ps . +They will be used at subsequent calls of this function to restart +the conversion suspended. +.Pp +The behaviour of +.Fn mbrtowc +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 012345678901 +.It "s == NULL" +.Fn mbrtowc +sets the conversion state object pointed to by +.Fa ps +to an initial state and always returns 0. +Unlike +.Xr mbtowc 3 , +the value returned does not indicate whether the current encoding of +the locale is state-dependent. +.Pp +In this case, +.Fn mbrtowc +ignores +.Fa pwc +and +.Fa n , +and is equivalent to the following call: +.Bd -literal -offset indent +mbrtowc(NULL, "", 1, ps); +.Ed +.It "pwc == NULL" +The conversion from a multibyte character to a wide character has +taken place and the conversion state may be affected, but the resulting +wide character is discarded. +.It "ps == NULL" +.Fn mbrtowc +uses its own internal state object to keep the conversion state, +instead of +.Fa ps +mentioned in this manual page. +.Pp +Calling any other functions in +.Lb libc +never changes the internal state of +.Fn mbrtowc , +which is initialized at startup time of the program. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +In the usual cases, +.Fn mbrtowc +returns: +.Bl -tag -width 012345678901 +.It 0 +The next bytes pointed to by +.Fa s +form a nul character. +.It positive +If +.Fa s +points to a valid character, +.Fn mbrtowc +returns the number of bytes in the character. +.It (size_t)-2 +.Fa s +points to a byte sequence which possibly contains part of a valid +multibyte character, but which is incomplete. +When +.Fa n +is at least +.Dv MB_CUR_MAX , +this case can only occur if the array pointed to by +.Fa s +contains a redundant shift sequence. +.It (size_t)-1 +.Fa s +points to an illegal byte sequence which does not form a valid multibyte +character. +In this case, +.Fn mbrtowc +sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbrtowc +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid or incomplete multibyte character. +.It Bq Er EINVAL +.Fa ps +points to an invalid or uninitialized mbstate_t object. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbrlen 3 , +.Xr mbtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbrtowc +function conforms to +.St -isoC-amd1 . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/mbsinit.3 b/static/netbsd/man3/mbsinit.3 new file mode 100644 index 00000000..63ef147b --- /dev/null +++ b/static/netbsd/man3/mbsinit.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: mbsinit.3,v 1.6 2006/10/16 08:42:16 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2002 +.Dt MBSINIT 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbsinit +.Nd determines whether the state object is in the initial state +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn mbsinit "const mbstate_t *ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mbsinit +determines whether the state object pointed to by +.Fa ps +is the initial conversion state, or not. +.Pp +.Fa ps +may be a null pointer. +In this case, +.Fn mbsinit +will always return non-zero. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn mbsinit +returns: +.Bl -tag -width 0123456789 +.It 0 +The current state is not the initial state. +.It non-zero +The current state is the initial state or +.Fa ps +is a null pointer. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbsinit +conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/mbsrtowcs.3 b/static/netbsd/man3/mbsrtowcs.3 new file mode 100644 index 00000000..2a0e576d --- /dev/null +++ b/static/netbsd/man3/mbsrtowcs.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: mbsrtowcs.3,v 1.15 2024/09/09 18:55:26 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 9, 2024 +.Dt MBSRTOWCS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbsrtowcs , +.Nm mbsrntowcs +.Nd converts a multibyte character string to a wide-character string \ +(restartable) +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +. +.In wchar.h +. +.Ft size_t +.Fo mbsrtowcs +.Fa "wchar_t * restrict pwcs" +.Fa "const char ** restrict s" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +. +.Ft size_t +.Fo mbsnrtowcs +.Fa "wchar_t * restrict pwcs" +.Fa "const char ** restrict s" +.Fa "size_t nmc" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +. +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn mbsrtowcs +function converts the multibyte character string indirectly pointed to +by +.Fa s +to the corresponding wide-character string, and stores it in the +array pointed to by +.Fa pwcs . +The conversion stops due to the following reasons: +.Bl -bullet +.It +The conversion reaches a NUL byte. +In this case, the NUL byte is also converted. +.It +The +.Fn mbsrtowcs +has already stored +.Fa n +wide characters. +.It +The conversion encounters an invalid character. +.El +.Pp +Each character will be converted as if +.Xr mbrtowc 3 +is continuously called. +.Pp +After conversion, +if +.Fa pwcs +is not a NULL pointer, +the pointer object pointed to by +.Fa s +is a NULL pointer +.Pq if the conversion is stopped due to reaching a NUL byte +or the first byte of the character just after the last character +converted. +.Pp +If +.Fa pwcs +is not a NULL pointer and the conversion is stopped due to reaching +a NUL byte, the +.Fn mbsrtowcs +places the state object pointed to by +.Fa ps +to an initial state after the conversion has taken place. +.Pp +The behaviour of +.Fn mbsrtowcs +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width Li +. +.It Li "s == NULL || *s == NULL" +Undefined (may cause the program to crash). +. +.It Li "pwcs == NULL" +The conversion has taken place, but the resulting wide-character string +was discarded. +In this case, the pointer object pointed to by +.Fa s +is not modified and +.Fa n +is ignored. +. +.It Li "ps == NULL" +The +.Fn mbsrtowcs +uses its own internal state object to keep the conversion state, +instead of +.Fa ps +mentioned in this manual page. +.Pp +Calling any other functions in +.Lb libc +never changes the internal state of +.Fn mbsrtowcs , +which is initialized at startup time of the program. +.El +.Pp +The +.Fn mbsnrtowcs +function behaves identically to +.Fn mbsrtowcs , +except that the conversion stops after reading at most +.Fa nmc +characters from the buffer pointed to by +.Fa s . +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions return: +.Bl -tag -width Li +.It Li 0 , No or positive +The value returned is the number of elements stored in the array +pointed to by +.Fa pwcs , +except for a terminating NUL wide character (if any). +If +.Fa pwcs +is not +.Dv NULL +and the value returned is equal to +.Fa n , +the wide-character string pointed to by +.Fa pwcs +is not NUL-terminated. +If +.Fa pwcs +is a NULL pointer, the value returned is the number of elements to contain +the whole string converted, except for a terminating NUL wide character. +.It Li "(size_t)-1" +The array indirectly pointed to by +.Fa s +contains a byte sequence forming invalid character. +In this case, +.Fn mbsrtowcs +sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +The +.Fn mbsrtowcs +and +.Fn mbsnrtowcs +functions may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to a string containing an invalid or incomplete multibyte +character. +.It Bq Er EINVAL +.Fa ps +points to an invalid or uninitialized mbstate_t object. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbrtowc 3 , +.Xr mbstowcs 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbsrtowcs +function conforms to +.St -isoC-amd1 . +The +.Li restrict +qualifier was added by +.St -isoC-99 . +.Pp +The +.Fn mbsnrtowcs +function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/mbstowcs.3 b/static/netbsd/man3/mbstowcs.3 new file mode 100644 index 00000000..f0435fca --- /dev/null +++ b/static/netbsd/man3/mbstowcs.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: mbstowcs.3,v 1.12 2011/03/16 09:32:12 mbalmer Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 16, 2011 +.Dt MBSTOWCS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbstowcs +.Nd converts a multibyte character string to a wide-character string +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Fn mbstowcs "wchar_t * restrict pwcs" "const char * restrict s" "size_t n" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +.Fn mbstowcs +converts a nul-terminated multibyte character string pointed to by +.Fa s +to the corresponding wide-character string and stores it in the array +pointed to by +.Fa pwcs . +This function may modify the first at most +.Fa n +elements of the array pointed to by +.Fa pwcs . +Each character will be converted as if +.Xr mbtowc 3 +is continuously called, except the internal state of +.Xr mbtowc 3 +will not be affected. +.Pp +For state-dependent encoding, +.Fn mbstowcs +implies the multibyte character string pointed to by +.Fa s +always begins with an initial state. +.Pp +These are the special cases: +.Bl -tag -width 012345678901 +.It pwcs == NULL +.Fn mbstowcs +returns the number of elements to store the whole wide-character string +corresponding to the multibyte character string pointed to by +.Fa s . +In this case, +.Fa n +is ignored. +.It s == NULL +Undefined (may cause the program to crash). +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn mbstowcs +returns: +.Bl -tag -width 012345678901 +.It 0 or positive +Number of elements stored in the array pointed to by +.Fa pwcs . +There are no cases that the value returned is greater than +.Fa n +(unless +.Fa pwcs +is a null pointer) or the value of the +.Dv MB_CUR_MAX +macro. +If the return value is equal to +.Fa n , +the string pointed to by +.Fa pwcs +will not be nul-terminated. +.It (size_t)-1 +.Fa s +points to a string containing an invalid or incomplete multibyte character. +The +.Fn mbstowcs +also sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbstowcs +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to a string containing an invalid or incomplete multibyte character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbtowc 3 , +.Xr setlocale 3 , +.Xr wcstombs 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbstowcs +function conforms to +.St -ansiC . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/mbtowc.3 b/static/netbsd/man3/mbtowc.3 new file mode 100644 index 00000000..317fb334 --- /dev/null +++ b/static/netbsd/man3/mbtowc.3 @@ -0,0 +1,182 @@ +.\" $NetBSD: mbtowc.3,v 1.8 2006/10/16 09:10:29 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2002 +.Dt MBTOWC 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbtowc +.Nd converts a multibyte character to a wide character +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" +.Sh DESCRIPTION +.Fn mbtowc +usually converts the multibyte character pointed to by +.Fa s +to a wide character, and stores it in the wchar_t object pointed to by +.Fa pwc +if +.Fa pwc +is +.Pf non- Dv NULL +and +.Fa s +points to a valid character. +This function may inspect at most n bytes of the array beginning from +.Fa s . +.Pp +In state-dependent encodings, +.Fa s +may point to the special sequence bytes to change the shift-state. +Although such sequence bytes correspond to no individual +wide-character code, +.Fn mbtowc +changes its own state by the sequence bytes and treats them +as if they are a part of the subsequence multibyte character. +.Pp +Unlike +.Xr mbrtowc 3 , +the first +.Fa n +bytes pointed to by +.Fa s +need to form an entire multibyte character. +Otherwise, this function causes an error. +.Pp +Calling any other functions in +.Lb libc +never changes the internal state of +.Fn mbtowc , +except for calling +.Xr setlocale 3 +with changing the +.Dv LC_CTYPE +category of the current locale. +Such +.Xr setlocale 3 +call causes the internal state of this function to be indeterminate. +.Pp +The behaviour of +.Fn mbtowc +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There are special cases: +.Bl -tag -width 012345678901 +.It s == NULL +.Fn mbtowc +initializes its own internal state to an initial state, and +determines whether the current encoding is state-dependent. +This function returns 0 if the encoding is state-independent, +otherwise non-zero. +In this case, +.Fa pwc +is completely ignored. +.It pwc == NULL +.Fn mbtowc +executes the conversion as if +.Fa pwc +is non-NULL, but a result of the conversion is discarded. +.It n == 0 +In this case, +the first +.Fa n +bytes of the array pointed to by +.Fa s +never form a complete character. +Thus, the +.Fn mbtowc +always fails. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +Normally, the +.Fn mbtowc +returns: +.Bl -tag -width 012345678901 +.It 0 +.Fa s +points to a nul byte +.Pq Sq \e0 . +.It positive +Number of bytes for the valid multibyte character pointed to by +.Fa s . +There are no cases that the value returned is greater than +the value of the +.Dv MB_CUR_MAX +macro. +.It -1 +.Fa s +points to an invalid or an incomplete multibyte character. +The +.Fn mbtowc +also sets +.Va errno +to indicate the error. +.El +.Pp +When +.Fa s +is equal to +.Dv NULL , +.Fn mbtowc +returns: +.Bl -tag -width 0123456789 +.It 0 +The current encoding is state-independent. +.It non-zero +The current encoding is state-dependent. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbtowc +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid or incomplete multibyte character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mblen 3 , +.Xr mbrtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbtowc +function conforms to +.St -ansiC . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/mchars_alloc.3 b/static/netbsd/man3/mchars_alloc.3 new file mode 100644 index 00000000..7d079254 --- /dev/null +++ b/static/netbsd/man3/mchars_alloc.3 @@ -0,0 +1,227 @@ +.\" Id: mchars_alloc.3,v 1.4 2016/07/07 19:19:01 schwarze Exp +.\" +.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd July 7, 2016 +.Dt MCHARS_ALLOC 3 +.Os +.Sh NAME +.Nm mchars_alloc , +.Nm mchars_free , +.Nm mchars_num2char , +.Nm mchars_num2uc , +.Nm mchars_spec2cp , +.Nm mchars_spec2str , +.Nm mchars_uc2str +.Nd character table for mandoc +.Sh SYNOPSIS +.In sys/types.h +.In mandoc.h +.Ft void +.Fn mchars_alloc void +.Ft void +.Fn mchars_free void +.Ft char +.Fo mchars_num2char +.Fa "const char *decimal" +.Fa "size_t sz" +.Fc +.Ft int +.Fo mchars_num2uc +.Fa "const char *hexadecimal" +.Fa "size_t sz" +.Fc +.Ft int +.Fo mchars_spec2cp +.Fa "const char *name" +.Fa "size_t sz" +.Fc +.Ft "const char *" +.Fo mchars_spec2str +.Fa "const char *name" +.Fa "size_t sz" +.Fa "size_t *rsz" +.Fc +.Ft "const char *" +.Fn mchars_uc2str "int codepoint" +.Sh DESCRIPTION +These functions translate Unicode character numbers and +.Xr roff 7 +character names into glyphs. +See +.Xr mandoc_char 7 +for a list of +.Xr roff 7 +special characters. +These functions are intended for external use by programs formatting +.Xr mdoc 7 +and +.Xr man 7 +pages for output, for example the +.Xr mandoc 1 +output formatter modules and +.Xr makewhatis 8 . +The +.Fa decimal , +.Fa hexadecimal , +.Fa name , +and +.Fa size +input arguments are usually obtained from the +.Xr mandoc_escape 3 +parser function. +.Pp +The function +.Fn mchars_num2char +converts a +.Fa decimal +string representation of a character number consisting of +.Fa sz +digits into a printable ASCII character. +If the input string is non-numeric or does not represent a printable +ASCII character, the NUL character +.Pq Sq \e0 +is returned. +For example, the +.Xr mandoc 1 +.Fl Tascii , +.Fl Tutf8 , +and +.Fl Thtml +output modules use this function to render +.Xr roff 7 +.Ic \eN +escape sequences. +.Pp +The function +.Fn mchars_num2uc +converts a +.Fa hexadecimal +string representation of a Unicode codepoint consisting of +.Fa sz +digits into an integer representation. +If the input string is non-numeric or represents an ASCII character, +the NUL character +.Pq Sq \e0 +is returned. +For example, the +.Xr mandoc 1 +.Fl Tutf8 +and +.Fl Thtml +output modules use this function to render +.Xr roff 7 +.Ic \e[u Ns Ar XXXX Ns Ic \&] +and +.Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq +escape sequences. +.Pp +The function +.Fn mchars_alloc +initializes a static +.Vt "struct ohash" +object for subsequent use by the following two lookup functions. +When no longer needed, this object can be destroyed with +.Fn mchars_free . +.Pp +The function +.Fn mchars_spec2cp +looks up a +.Xr roff 7 +special character +.Fa name +consisting of +.Fa sz +characters and returns the corresponding Unicode codepoint. +If the +.Ar name +is not recognized, \-1 is returned. +For example, the +.Xr mandoc 1 +.Fl Tutf8 +and +.Fl Thtml +output modules use this function to render +.Xr roff 7 +.Ic \e[ Ns Ar name Ns Ic \&] +and +.Ic \eC\(aq Ns Ar name Ns Ic \(aq +escape sequences. +.Pp +The function +.Fn mchars_spec2str +looks up a +.Xr roff 7 +special character +.Fa name +consisting of +.Fa sz +characters and returns an ASCII string representation. +The length of the representation is returned in +.Fa rsz . +In many cases, the meaning of such ASCII representations +is not quite obvious, so using +.Xr roff 7 +special characters in documents intended for ASCII rendering +is usually a bad idea. +If the +.Ar name +is not recognized, +.Dv NULL +is returned. +For example, +.Xr makewhatis 8 +and the +.Xr mandoc 1 +.Fl Tascii +output module use this function to render +.Xr roff 7 +.Ic \e[ Ns Ar name Ns Ic \&] +and +.Ic \eC\(aq Ns Ar name Ns Ic \(aq +escape sequences. +.Pp +The function +.Fn mchars_uc2str +performs a reverse lookup of the Unicode +.Fa codepoint +and returns an ASCII string representation, or the string +.Qq <?> +if none is available. +.Sh FILES +These funtions are implemented in the file +.Pa chars.c . +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr mandoc_escape 3 , +.Xr ohash_init 3 , +.Xr mandoc_char 7 , +.Xr roff 7 +.Sh HISTORY +These functions and their predecessors have been available since the +following mandoc versions: +.Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10" +.It Sy function Ta since Ta Sy predecessor Ta since +.It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3 +.It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0 +.It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10 +.It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em +.It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5 +.It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3 +.It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em +.El +.Sh AUTHORS +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +.An Ingo Schwarze Aq Mt schwarze@openbsd.org diff --git a/static/netbsd/man3/md2.3 b/static/netbsd/man3/md2.3 new file mode 100644 index 00000000..11a71f4a --- /dev/null +++ b/static/netbsd/man3/md2.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: md2.3,v 1.3 2018/12/17 08:18:06 wiz Exp $ +.\" +.\" ---------------------------------------------------------------------------- +.\" "THE BEER-WARE LICENSE" (Revision 42): +.\" <phk@login.dkuug.dk> wrote this file. As long as you retain this notice you +.\" can do whatever you want with this stuff. If we meet some day, and you think +.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +.\" ---------------------------------------------------------------------------- +.\" +.\" from FreeBSD Id: mdX.3,v 1.7 1996/10/22 16:28:56 phk Exp +.\" +.Dd September 24, 2005 +.Dt MD2 3 +.Os +.Sh NAME +.Nm MD2Init , +.Nm MD2Update , +.Nm MD2Final , +.Nm MD2End , +.Nm MD2File , +.Nm MD2Data +.Nd calculate the RSA Data Security, Inc., +.Dq MD2 +message digest +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In mdX.h +.Ft void +.Fn MD2Init "MD2_CTX *context" +.Ft void +.Fn MD2Update "MD2_CTX *context" "const unsigned char *data" "unsigned int len" +.Ft void +.Fn MD2Final "unsigned char digest[16]" "MD2_CTX *context" +.Ft "char *" +.Fn MD2End "MD2_CTX *context" "char *buf" +.Ft "char *" +.Fn MD2File "const char *filename" "char *buf" +.Ft "char *" +.Fn MD2Data "const unsigned char *data" "unsigned int len" "char *buf" +.Sh DESCRIPTION +The MD2 functions calculate a 128-bit cryptographic checksum (digest) +for any number of input bytes. +A cryptographic checksum is a one-way +hash-function, that is, you cannot find (except by exhaustive search) +the input corresponding to a particular output. +This net result is +a ``fingerprint'' of the input-data, which doesn't disclose the actual +input. +.Pp +The MD2 routines should not be used for any security-related purpose. +.Pp +The +.Fn MD2Init , +.Fn MD2Update , +and +.Fn MD2Final +functions are the core functions. +Allocate an MD2_CTX, initialize it with +.Fn MD2Init , +run over the data with +.Fn MD2Update , +and finally extract the result using +.Fn MD2Final . +.Pp +.Fn MD2End +is a wrapper for +.Fn MD2Final +which converts the return value to a 33-character +(including the terminating '\e0') ASCII +string which represents the 128 bits in hexadecimal. +.Pp +.Fn MD2File +calculates the digest of a file, and uses +.Fn MD2End +to return the result. +If the file cannot be opened, a null pointer is returned. +.Fn MD2Data +calculates the digest of a chunk of data in memory, and uses +.Fn MD2End +to return the result. +.Pp +When using +.Fn MD2End , +.Fn MD2File , +or +.Fn MD2Data , +the +.Ar buf +argument can be a null pointer, in which case the returned string +is allocated with +.Xr malloc 3 +and subsequently must be explicitly deallocated using +.Xr free 3 +after use. +If the +.Ar buf +argument is non-null it must point to at least 33 characters of buffer space. +.Sh SEE ALSO +.Xr md4 3 , +.Xr md5 3 , +.Xr openssl_MD2 3 , +.Xr openssl_MD4 3 , +.Xr openssl_MD5 3 , +.Rs +.%A B. Kaliski +.%T The MD2 Message-Digest Algorithm +.%O RFC 1319 +.Re +.Rs +.%A RSA Laboratories +.%T Frequently Asked Questions About today's Cryptography +.Re +.Sh HISTORY +These functions appeared in +.Nx 1.3 . +.Sh AUTHORS +.An -nosplit +The original MD2 routines were developed by +.An RSA Data Security, Inc. , +and published in the above references. +This code is a public domain implementation by +.An Andrew Brown . +.Sh BUGS +No method is known to exist which finds two files having the same hash value, +nor to find a file with a specific hash value. +There is on the other hand no guarantee that such a method doesn't exist. diff --git a/static/netbsd/man3/mdX.3 b/static/netbsd/man3/mdX.3 new file mode 100644 index 00000000..f10f28fc --- /dev/null +++ b/static/netbsd/man3/mdX.3 @@ -0,0 +1,146 @@ +.\" $NetBSD: mdX.3,v 1.12 2018/05/23 06:08:01 wiz Exp $ +.\" +.\" ---------------------------------------------------------------------------- +.\" "THE BEER-WARE LICENSE" (Revision 42): +.\" <phk@login.dkuug.dk> wrote this file. As long as you retain this notice you +.\" can do whatever you want with this stuff. If we meet some day, and you think +.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +.\" ---------------------------------------------------------------------------- +.\" +.\" from FreeBSD Id: mdX.3,v 1.7 1996/10/22 16:28:56 phk Exp +.\" +.Dd May 22, 2018 +.Dt MDX 3 +.Os +.Sh NAME +.Nm MDXInit , +.Nm MDXUpdate , +.Nm MDXFinal , +.Nm MDXEnd , +.Nm MDXFile , +.Nm MDXData +.Nd calculate the RSA Data Security, Inc., +.Dq MDX +message digest +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In mdX.h +.Ft void +.Fn MDXInit "MDX_CTX *context" +.Ft void +.Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len" +.Ft void +.Fn MDXFinal "unsigned char digest[16]" "MDX_CTX *context" +.Ft "char *" +.Fn MDXEnd "MDX_CTX *context" "char *buf" +.Ft "char *" +.Fn MDXFile "const char *filename" "char *buf" +.Ft "char *" +.Fn MDXData "const unsigned char *data" "unsigned int len" "char *buf" +.Sh DESCRIPTION +The MDX functions calculate a 128-bit cryptographic checksum (digest) +for any number of input bytes. +A cryptographic checksum is a one-way +hash-function, that is, you cannot find (except by exhaustive search) +the input corresponding to a particular output. +This net result is +a ``fingerprint'' of the input-data, which doesn't disclose the actual +input. +.Pp +MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle. +MD2 can only be used for Privacy-Enhanced Mail. +MD4 has been criticized for being too weak, so MD5 was developed in +response as ``MD4 with safety-belts''. +When in doubt, use MD5. +.Pp +The +.Fn MDXInit , +.Fn MDXUpdate , +and +.Fn MDXFinal +functions are the core functions. +Allocate an MDX_CTX, initialize it with +.Fn MDXInit , +run over the data with +.Fn MDXUpdate , +and finally extract the result using +.Fn MDXFinal . +.Pp +.Fn MDXEnd +is a wrapper for +.Fn MDXFinal +which converts the return value to a 33-character +(including the terminating '\e0') +.Tn ASCII +string which represents the 128 bits in hexadecimal. +.Pp +.Fn MDXFile +calculates the digest of a file, and uses +.Fn MDXEnd +to return the result. +If the file cannot be opened, a null pointer is returned. +.Fn MDXData +calculates the digest of a chunk of data in memory, and uses +.Fn MDXEnd +to return the result. +.Pp +When using +.Fn MDXEnd , +.Fn MDXFile , +or +.Fn MDXData , +the +.Ar buf +argument can be a null pointer, in which case the returned string +is allocated with +.Xr malloc 3 +and subsequently must be explicitly deallocated using +.Xr free 3 +after use. +If the +.Ar buf +argument is non-null it must point to at least 33 characters of buffer space. +.Sh SEE ALSO +.Xr md2 3 , +.Xr md4 3 , +.Xr md5 3 , +.Xr openssl_MD2 3 , +.Xr openssl_MD4 3 , +.Xr openssl_MD5 3 +.Rs +.%A B. Kaliski +.%T The MD2 Message-Digest Algorithm +.%O RFC 1319 +.Re +.Rs +.%A R. Rivest +.%T The MD4 Message-Digest Algorithm +.%O RFC 1186 +.Re +.Rs +.%A R. Rivest +.%T The MD5 Message-Digest Algorithm +.%O RFC 1321 +.Re +.Rs +.%A RSA Laboratories +.%T Frequently Asked Questions About today's Cryptography +.Re +.Sh HISTORY +These functions appeared in +.Nx 1.3 . +.Sh AUTHORS +.An -nosplit +The original MDX routines were developed by +.An RSA Data Security, Inc. , +and published in the above references. +This code is derived directly from these implementations by +.An Poul-Henning Kamp Aq Mt phk@login.dkuug.dk . +.Pp +Phk ristede runen. +.Sh BUGS +No method is known to exist which finds two files having the same hash value, +nor to find a file with a specific hash value. +There is on the other hand no guarantee that such a method doesn't exist. diff --git a/static/netbsd/man3/membar_ops.3 b/static/netbsd/man3/membar_ops.3 new file mode 100644 index 00000000..b9935c71 --- /dev/null +++ b/static/netbsd/man3/membar_ops.3 @@ -0,0 +1,393 @@ +.\" $NetBSD: membar_ops.3,v 1.10 2022/04/09 23:32:52 riastradh Exp $ +.\" +.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 30, 2022 +.Dt MEMBAR_OPS 3 +.Os +.Sh NAME +.Nm membar_ops , +.Nm membar_acquire , +.Nm membar_release , +.Nm membar_producer , +.Nm membar_consumer , +.Nm membar_datadep_consumer , +.Nm membar_sync +.Nd memory ordering barriers +.\" .Sh LIBRARY +.\" .Lb libc +.Sh SYNOPSIS +.In sys/atomic.h +.\" +.Ft void +.Fn membar_acquire "void" +.Ft void +.Fn membar_release "void" +.Ft void +.Fn membar_producer "void" +.Ft void +.Fn membar_consumer "void" +.Ft void +.Fn membar_datadep_consumer "void" +.Ft void +.Fn membar_sync "void" +.Sh DESCRIPTION +The +.Nm +family of functions prevent reordering of memory operations, as needed +for synchronization in multiprocessor execution environments that have +relaxed load and store order. +.Pp +In general, memory barriers must come in pairs \(em a barrier on one +CPU, such as +.Fn membar_release , +must pair with a barrier on another CPU, such as +.Fn membar_acquire , +in order to synchronize anything between the two CPUs. +Code using +.Nm +should generally be annotated with comments identifying how they are +paired. +.Pp +.Nm +affect only operations on regular memory, not on device +memory; see +.Xr bus_space 9 +and +.Xr bus_dma 9 +for machine-independent interfaces to handling device memory and DMA +operations for device drivers. +.Pp +Unlike C11, +.Em all +memory operations \(em that is, all loads and stores on regular +memory \(em are affected by +.Nm , +not just C11 atomic operations on +.Vt _Atomic\^ Ns -qualified +objects. +.Bl -tag -width abcd +.It Fn membar_acquire +Any load preceding +.Fn membar_acquire +will happen before all memory operations following it. +.Pp +A load followed by a +.Fn membar_acquire +implies a +.Em load-acquire +operation in the language of C11. +.Fn membar_acquire +should only be used after atomic read/modify/write, such as +.Xr atomic_cas_uint 3 . +For regular loads, instead of +.Li "x = *p; membar_acquire()" , +you should use +.Li "x = atomic_load_acquire(p)" . +.Pp +.Fn membar_acquire +is typically used in code that implements locking primitives to ensure +that a lock protects its data, and is typically paired with +.Fn membar_release ; +see below for an example. +.It Fn membar_release +All memory operations preceding +.Fn membar_release +will happen before any store that follows it. +.Pp +A +.Fn membar_release +followed by a store implies a +.Em store-release +operation in the language of C11. +.Fn membar_release +should only be used before atomic read/modify/write, such as +.Xr atomic_inc_uint 3 . +For regular stores, instead of +.Li "membar_release(); *p = x" , +you should use +.Li "atomic_store_release(p, x)" . +.Pp +.Fn membar_release +is typically paired with +.Fn membar_acquire , +and is typically used in code that implements locking or reference +counting primitives. +Releasing a lock or reference count should use +.Fn membar_release , +and acquiring a lock or handling an object after draining references +should use +.Fn membar_acquire , +so that whatever happened before releasing will also have happened +before acquiring. +For example: +.Bd -literal -offset abcdefgh +/* thread A -- release a reference */ +obj->state.mumblefrotz = 42; +KASSERT(valid(&obj->state)); +membar_release(); +atomic_dec_uint(&obj->refcnt); + +/* + * thread B -- busy-wait until last reference is released, + * then lock it by setting refcnt to UINT_MAX + */ +while (atomic_cas_uint(&obj->refcnt, 0, -1) != 0) + continue; +membar_acquire(); +KASSERT(valid(&obj->state)); +obj->state.mumblefrotz--; +.Ed +.Pp +In this example, +.Em if +the load in +.Fn atomic_cas_uint +in thread B witnesses the store in +.Fn atomic_dec_uint +in thread A setting the reference count to zero, +.Em then +everything in thread A before the +.Fn membar_release +is guaranteed to happen before everything in thread B after the +.Fn membar_acquire , +as if the machine had sequentially executed: +.Bd -literal -offset abcdefgh +obj->state.mumblefrotz = 42; /* from thread A */ +KASSERT(valid(&obj->state)); +\&... +KASSERT(valid(&obj->state)); /* from thread B */ +obj->state.mumblefrotz--; +.Ed +.Pp +.Fn membar_release +followed by a store, serving as a +.Em store-release +operation, may also be paired with a subsequent load followed by +.Fn membar_acquire , +serving as the corresponding +.Em load-acquire +operation. +However, you should use +.Xr atomic_store_release 9 +and +.Xr atomic_load_acquire 9 +instead in that situation, unless the store is an atomic +read/modify/write which requires a separate +.Fn membar_release . +.It Fn membar_producer +All stores preceding +.Fn membar_producer +will happen before any stores following it. +.Pp +.Fn membar_producer +has no analogue in C11. +.Pp +.Fn membar_producer +is typically used in code that produces data for read-only consumers +which use +.Fn membar_consumer , +such as +.Sq seqlocked +snapshots of statistics; see below for an example. +.It Fn membar_consumer +All loads preceding +.Fn membar_consumer +will complete before any loads after it. +.Pp +.Fn membar_consumer +has no analogue in C11. +.Pp +.Fn membar_consumer +is typically used in code that reads data from producers which use +.Fn membar_producer , +such as +.Sq seqlocked +snapshots of statistics. +For example: +.Bd -literal +struct { + /* version number and in-progress bit */ + unsigned seq; + + /* read-only statistics, too large for atomic load */ + unsigned foo; + int bar; + uint64_t baz; +} stats; + + /* producer (must be serialized, e.g. with mutex(9)) */ + stats->seq |= 1; /* mark update in progress */ + membar_producer(); + stats->foo = count_foo(); + stats->bar = measure_bar(); + stats->baz = enumerate_baz(); + membar_producer(); + stats->seq++; /* bump version number */ + + /* consumer (in parallel w/ producer, other consumers) */ +restart: + while ((seq = stats->seq) & 1) /* wait for update */ + SPINLOCK_BACKOFF_HOOK; + membar_consumer(); + foo = stats->foo; /* read out a candidate snapshot */ + bar = stats->bar; + baz = stats->baz; + membar_consumer(); + if (seq != stats->seq) /* try again if version changed */ + goto restart; +.Ed +.It Fn membar_datadep_consumer +Same as +.Fn membar_consumer , +but limited to loads of addresses dependent on prior loads, or +.Sq data-dependent +loads: +.Bd -literal -offset indent +int **pp, *p, v; + +p = *pp; +membar_datadep_consumer(); +v = *p; +consume(v); +.Ed +.Pp +.Fn membar_datadep_consumer +is typically paired with +.Fn membar_release +by code that initializes an object before publishing it. +However, you should use +.Xr atomic_store_release 9 +and +.Xr atomic_load_consume 9 +instead, to avoid obscure edge cases in case the consumer is not +read-only. +.Pp +.Fn membar_datadep_consumer +does not guarantee ordering of loads in branches, or +.Sq control-dependent +loads \(em you must use +.Fn membar_consumer +instead: +.Bd -literal -offset indent +int *ok, *p, v; + +if (*ok) { + membar_consumer(); + v = *p; + consume(v); +} +.Ed +.Pp +Most CPUs do not reorder data-dependent loads (i.e., most CPUs +guarantee that cached values are not stale in that case), so +.Fn membar_datadep_consumer +is a no-op on those CPUs. +.It Fn membar_sync +All memory operations preceding +.Fn membar_sync +will happen before any memory operations following it. +.Pp +.Fn membar_sync +is a sequential consistency acquire/release barrier, analogous to +.Li "atomic_thread_fence(memory_order_seq_cst)" +in C11. +.Pp +.Fn membar_sync +is typically paired with +.Fn membar_sync . +.Pp +.Fn membar_sync +is typically not needed except in exotic synchronization schemes like +Dekker's algorithm that require store-before-load ordering. +If you are tempted to reach for it, see if there is another way to do +what you're trying to do first. +.El +.Sh DEPRECATED MEMORY BARRIERS +The following memory barriers are deprecated. +They were imported from Solaris, which describes them as providing +ordering relative to +.Sq lock acquisition , +but the documentation in +.Nx +disagreed with the implementation and use on the semantics. +.Bl -tag -width abcd +.It Fn membar_enter +Originally documented as store-before-load/store, this was instead +implemented as load-before-load/store on some platforms, which is what +essentially all uses relied on. +Now this is implemented as an alias for +.Fn membar_sync +everywhere, meaning a full load/store-before-load/store sequential +consistency barrier, in order to guarantee what the documentation +claimed +.Em and +what the implementation actually did. +.Pp +New code should use +.Fn membar_acquire +for load-before-load/store ordering, which is what most uses need, or +.Fn membar_sync +for store-before-load/store ordering, which typically only appears in +exotic synchronization schemes like Dekker's algorithm. +.It Fn membar_exit +Alias for +.Fn membar_release . +This was originally meant to be paired with +.Fn membar_enter . +.Pp +New code should use +.Fn membar_release +instead. +.El +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr atomic_loadstore 9 , +.Xr bus_dma 9 , +.Xr bus_space 9 +.Sh HISTORY +The +.Nm membar_ops +functions first appeared in +.Nx 5.0 . +.Pp +The data-dependent load barrier, +.Fn membar_datadep_consumer , +first appeared in +.Nx 7.0 . +.Pp +The +.Fn membar_acquire +and +.Fn membar_release +functions first appeared, and the +.Fn membar_enter +and +.Fn membar_exit +functions were deprecated, in +.Nx 10.0 . diff --git a/static/netbsd/man3/memccpy.3 b/static/netbsd/man3/memccpy.3 new file mode 100644 index 00000000..809200c3 --- /dev/null +++ b/static/netbsd/man3/memccpy.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memccpy.3 8.1 (Berkeley) 6/9/93 +.\" $NetBSD: memccpy.3,v 1.11 2024/07/15 19:25:30 wiz Exp $ +.\" +.Dd July 15, 2024 +.Dt MEMCCPY 3 +.Os +.Sh NAME +.Nm memccpy +.Nd copy string until character found +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memccpy "void *dst" "const void *src" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memccpy +function +copies bytes from string +.Fa src +to string +.Fa dst . +If the character +.Fa c +(as converted to an unsigned char) occurs in the string +.Fa src , +the copy stops and a pointer to the byte after the copy of +.Fa c +in the string +.Fa dst +is returned. +Otherwise, +.Fa len +bytes are copied, and a null pointer is returned. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 +.Sh STANDARDS +.Nm +conforms to +.St -p1003.1 +and +.St -svid4 . +.Sh HISTORY +The +.Fn memccpy +function first appeared in +.Bx 4.3 Tahoe . diff --git a/static/netbsd/man3/memchr.3 b/static/netbsd/man3/memchr.3 new file mode 100644 index 00000000..cb3b9680 --- /dev/null +++ b/static/netbsd/man3/memchr.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memchr.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memchr.3,v 1.11 2009/04/10 23:24:35 wiz Exp $ +.\" +.Dd April 10, 2009 +.Dt MEMCHR 3 +.Os +.Sh NAME +.Nm memchr , +.Nm memrchr +.Nd locate byte in byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memchr "const void *b" "int c" "size_t len" +.Ft void * +.Fn memrchr "const void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memchr +function +locates the first occurrence of +.Fa c +(converted to an unsigned char) +in string +.Fa b . +The +.Fn memrchr +function +locates the last occurrence of +.Fa c +(converted to an unsigned char) +in string +.Fa b . +.Sh RETURN VALUES +The +.Fn memchr +and +.Fn memrchr +functions +return a pointer to the byte located, or +.Dv NULL +if no such byte exists within +.Fa len +bytes. +.Sh SEE ALSO +.Xr index 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn memchr +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/memcmp.3 b/static/netbsd/man3/memcmp.3 new file mode 100644 index 00000000..fec697f7 --- /dev/null +++ b/static/netbsd/man3/memcmp.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memcmp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memcmp.3,v 1.11 2013/06/24 04:21:20 riastradh Exp $ +.\" +.Dd June 23, 2013 +.Dt MEMCMP 3 +.Os +.Sh NAME +.Nm memcmp +.Nd compare byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn memcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn memcmp +function +compares byte string +.Fa b1 +against byte string +.Fa b2 . +Both strings are assumed to be +.Fa len +bytes long. +.Sh RETURN VALUES +The +.Fn memcmp +function +returns zero if the two strings are identical, +otherwise returns the difference between the first two differing bytes +(treated as unsigned char values, so that +.Sq Li \e200 +is greater than +.Sq Li \&\e0 , +for example). +Zero-length strings are always identical. +.Pp +Do not use +.Fn memcmp +to compare cryptographic secrets, because the time it takes varies +depending on how many bytes are the same, and thus leaks information +about the two strings by a timing side channel. +To compare secrets, hashes, message authentication codes, etc., use +.Xr consttime_memequal 3 +instead. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr consttime_memequal 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn memcmp +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/memcpy.3 b/static/netbsd/man3/memcpy.3 new file mode 100644 index 00000000..aa078c5a --- /dev/null +++ b/static/netbsd/man3/memcpy.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memcpy.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memcpy.3,v 1.15 2023/08/13 04:20:07 wiz Exp $ +.\" +.Dd August 1, 2023 +.Dt MEMCPY 3 +.Os +.Sh NAME +.Nm memcpy +.Nd copy byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memcpy "void * restrict dst" "const void * restrict src" "size_t len" +.Ft void * +.Fn mempcpy "void * restrict dst" "const void * restrict src" "size_t len" +.Sh DESCRIPTION +The +.Fn memcpy +and +.Fn mempcpy +functions +copy +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +The arguments must not overlap -- behavior if the arguments overlap is +undefined. +To copy byte strings that overlap, use +.Xr memmove 3 . +.Sh RETURN VALUES +The +.Fn memcpy +function +returns the original value of +.Fa dst . +.Pp +The +.Fn mempcpy +function returns a pointer to the byte after the last written byte. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memmove 3 , +.Xr wmemcpy 3 , +.Xr wmempcpy 3 +.Sh STANDARDS +The +.Fn memcpy +function +conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/memmem.3 b/static/netbsd/man3/memmem.3 new file mode 100644 index 00000000..3eb3b4a1 --- /dev/null +++ b/static/netbsd/man3/memmem.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: memmem.3,v 1.4 2024/11/01 16:36:58 nia Exp $ +.\" +.\" Copyright (c) 2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Perry E. Metzger of Metzger, Dowdeswell & Co. LLC. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 1, 2024 +.Dt MEMMEM 3 +.Os +.Sh NAME +.Nm memmem +.Nd locate substring in byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memmem "const void *block" "size_t blen" "const void *pat" "size_t plen" +.Sh DESCRIPTION +The +.Fn memmem +function locates the first occurrence of the binary string +.Fa pat +of size +.Fa plen +bytes in the byte string +.Fa block +of size +.Fa blen +bytes. +.Sh RETURN VALUES +The +.Fn memmem +function returns a pointer to the substring located, or +.Dv NULL +if no such substring exists within +.Fa block . +.Pp +If +.Fa plen +is zero, +.Fa block +is returned, i.e. a zero length +.Fa pat +is deemed to match the start of the string, as with +.Xr strstr 3 . +.Sh SEE ALSO +.Xr bm 3 , +.Xr memchr 3 , +.Xr strchr 3 , +.Xr strstr 3 +.Sh STANDARDS +The +.Nm +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +.Fn memmem +first appeared in the Free Software Foundation's glibc library. diff --git a/static/netbsd/man3/memmove.3 b/static/netbsd/man3/memmove.3 new file mode 100644 index 00000000..3c609980 --- /dev/null +++ b/static/netbsd/man3/memmove.3 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memmove.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memmove.3,v 1.8 2003/08/07 16:43:48 agc Exp $ +.\" +.Dd June 4, 1993 +.Dt MEMMOVE 3 +.Os +.Sh NAME +.Nm memmove +.Nd copy byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memmove "void *dst" "const void *src" "size_t len" +.Sh DESCRIPTION +The +.Fn memmove +function +copies +.Fa len +bytes from string +.Fa src +to string +.Fa dst . +The two strings may overlap; +the copy is always done in a non-destructive manner. +.Sh RETURN VALUES +The +.Fn memmove +function returns the original value of +.Fa dst . +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr strcpy 3 +.Sh STANDARDS +The +.Fn memmove +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/memory.3 b/static/netbsd/man3/memory.3 new file mode 100644 index 00000000..6757eff8 --- /dev/null +++ b/static/netbsd/man3/memory.3 @@ -0,0 +1,68 @@ +.\" $NetBSD: memory.3,v 1.12 2017/04/26 07:40:09 abhinav Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memory.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 26, 2017 +.Dt MEMORY 3 +.Os +.Sh NAME +.Nm memory +.Nd general memory allocation operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn malloc "size_t size" +.Ft void +.Fn free "void *ptr" +.Ft void * +.Fn realloc "void *ptr" "size_t size" +.Ft void * +.Fn calloc "size_t nelem" "size_t elsize" +.Ft void * +.Fn alloca "size_t size" +.Sh DESCRIPTION +These functions allocate and free memory for the calling process. +They are described in the +individual manual pages. +The memory allocators used in the kernel are described in +.Xr memoryallocators 9 . +.Sh SEE ALSO +.Xr alloca 3 , +.Xr calloc 3 , +.Xr free 3 , +.Xr malloc 3 , +.Xr realloc 3 +.Sh STANDARDS +These functions, with the exception of +.Fn alloca +conform to +.St -ansiC . diff --git a/static/netbsd/man3/memset.3 b/static/netbsd/man3/memset.3 new file mode 100644 index 00000000..949979c7 --- /dev/null +++ b/static/netbsd/man3/memset.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)memset.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: memset.3,v 1.13 2016/08/04 16:36:45 sevan Exp $ +.\" +.Dd June 23, 2013 +.Dt MEMSET 3 +.Os +.Sh NAME +.Nm memset +.Nd write a byte to byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void * +.Fn memset "void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memset +function +writes +.Fa len +bytes of value +.Fa c +(converted to an unsigned char) to the string +.Fa b . +.Sh RETURN VALUES +The +.Fn memset +function +returns the original value of +.Fa b . +.Pp +Note that the compiler may optimize away a call to +.Fn memset +if it can prove that the string will not be used by the program again, +for example if it is allocated on the stack and about to go out of scope. +If you want to guarantee that zeros are written to memory, for example +to sanitize a buffer holding a cryptographic secret, use +.Xr explicit_memset 3 . +.Sh SEE ALSO +.Xr bzero 3 , +.Xr explicit_memset 3 , +.Xr swab 3 +.Sh STANDARDS +The +.Fn memset +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/menu_attributes.3 b/static/netbsd/man3/menu_attributes.3 new file mode 100644 index 00000000..c00cd594 --- /dev/null +++ b/static/netbsd/man3/menu_attributes.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: menu_attributes.3,v 1.11 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ATTRIBUTES 3 +.Os +.Sh NAME +.Nm menu_back , +.Nm menu_fore , +.Nm menu_grey , +.Nm menu_pad , +.Nm set_menu_back , +.Nm set_menu_fore , +.Nm set_menu_grey , +.Nm set_menu_pad +.Nd get and set menu attributes +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char +.Fn menu_back "MENU *menu" +.Ft char +.Fn menu_fore "MENU *menu" +.Ft char +.Fn menu_grey "MENU *menu" +.Ft int +.Fn menu_pad "MENU *menu" +.Ft int +.Fn set_menu_back "MENU *menu" "char attr" +.Ft int +.Fn set_menu_fore "MENU *menu" "char attr" +.Ft int +.Fn set_menu_grey "MENU *menu" "char attr" +.Ft int +.Fn set_menu_pad "MENU *menu" "int pad" +.Sh DESCRIPTION +The +.Fn menu_back +function returns the value of the background attribute for the menu +passed. +This attribute is set by the +.Fn set_menu_back +call. +The +.Fn menu_fore +function returns the value of the foreground character attribute for +the menu passed. +This attribute is set by the +.Fn set_menu_fore +function. +The +.Fn menu_grey +function returns the value of the grey or unselectable character +attribute for the menu passed. +This attribute is set by the +.Fn set_menu_grey +function. +The +.Fn menu_pad +function returns the padding character that will be used between the +item name and its description. +The value of the pad character is set by the +.Fn set_menu_pad +function. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_POSTED +The menu is not posted. +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_SELECTABLE +The item could not be selected. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_cursor.3 b/static/netbsd/man3/menu_cursor.3 new file mode 100644 index 00000000..ddc380f2 --- /dev/null +++ b/static/netbsd/man3/menu_cursor.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: menu_cursor.3,v 1.10 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_CURSOR 3 +.Os +.Sh NAME +.Nm pos_menu_cursor +.Nd position cursor in menu window +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn pos_menu_cursor "MENU *menu" +.Sh DESCRIPTION +The +.Fn pos_menu_cursor +function positions the cursor in the menu window. +This function can be called after other curses calls to restore the cursor +to its correct position in the menu. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_POSTED +The menu is not posted. +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_SELECTABLE +The item could not be selected. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_driver.3 b/static/netbsd/man3/menu_driver.3 new file mode 100644 index 00000000..ae02fcfe --- /dev/null +++ b/static/netbsd/man3/menu_driver.3 @@ -0,0 +1,136 @@ +.\" $NetBSD: menu_driver.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_DRIVER 3 +.Os +.Sh NAME +.Nm menu_driver +.Nd main menu handling function +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn menu_driver "MENU *menu" "int c" +.Sh DESCRIPTION +The +.Fn menu_driver +function is the guts of the menu system. +It takes the commands passed +by c parameter and performs the requested action on the menu given. +The following commands may be given to the menu driver: +.Pp +.Bl -tag -width REQ_CLEAR_PATTERN -compact +.It Command +Action +.It REQ_LEFT_ITEM +Sets the new current item to be the item to the left of the current +item. +.It REQ_RIGHT_ITEM +Sets the new current item to be the item to the rights of the current +item. +.It REQ_UP_ITEM +Sets the new current item to be the item above the current item. +.It REQ_DOWN_ITEM +Sets the new current item to be the item below the current item. +.It REQ_SCR_ULINE +Scroll the menu one line towards the bottom of the menu window. +The new current item becomes the item immediately above the current item. +.It REQ_SCR_DLINE +Scroll the menu one line towards the top of the menu window. +The new current item becomes the item immediately below the current item. +.It REQ_SCR_DPAGE +Scroll the menu one page towards the bottom of the menu window. +.It REQ_SCR_UPAGE +Scroll the menu one page towards the top of the menu window. +.It REQ_FIRST_ITEM +Set the current item to be the first item in the menu. +.It REQ_LAST_ITEM +Set the current item to be the last item in the menu. +.It REQ_NEXT_ITEM +Set the new current item to be the next item in the item array after +the current item. +.It REQ_PREV_ITEM +Set the new current item to be the item before the current item in the +items array. +.It REQ_TOGGLE_ITEM +If the item is selectable then toggle the item's value. +.It REQ_CLEAR_PATTERN +Clear all the characters currently in the menu's pattern buffer. +.It REQ_BACK_PATTERN +Remove the last character from the pattern buffer. +.It REQ_NEXT_MATCH +Attempt to find the next item that matches the pattern buffer. +.It REQ_PREV_MATCH +Attempt to find the previous item that matches the pattern buffer. +.El +If +.Fn menu_driver +is passed a command that is greater than MAX_COMMAND then the command +passed is assumed to be a user defined command and +.Fn menu_driver +returns E_UNKNOWN_COMMAND. +Otherwise if the command is a printable +character then the character represented by the command is placed at +the end of the pattern buffer and an attempt is made to match the +pattern buffer against the items in the menu. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_NOT_POSTED +The menu is not posted. +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_format.3 b/static/netbsd/man3/menu_format.3 new file mode 100644 index 00000000..e5556b50 --- /dev/null +++ b/static/netbsd/man3/menu_format.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: menu_format.3,v 1.10 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_FORMAT 3 +.Os +.Sh NAME +.Nm menu_format , +.Nm set_menu_format +.Nd get or set number of rows and columns of items +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft void +.Fn menu_format "MENU *menu" "int *rows" "int *cols" +.Ft int +.Fn set_menu_format "MENU *menu" "int rows" "int cols" +.Sh DESCRIPTION +The +.Fn menu_format +returns the number of rows and columns of items that can be displayed +by the menu. +The format is set by the +.Fn set_menu_format +function call. +Note that the rows and columns defined here are not the size of the +window but rather the number of rows and columns of items. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_BAD_ARGUMENT -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_hook.3 b/static/netbsd/man3/menu_hook.3 new file mode 100644 index 00000000..f979c942 --- /dev/null +++ b/static/netbsd/man3/menu_hook.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: menu_hook.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_HOOK 3 +.Os +.Sh NAME +.Nm item_init , +.Nm item_term , +.Nm menu_init , +.Nm menu_term , +.Nm set_item_init , +.Nm set_item_term , +.Nm set_menu_init , +.Nm set_menu_term +.Nd get or set handler functions for menu post/unpost or item change +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft void (*hook)() +.Fn item_init "MENU *menu" +.Ft void (*hook)() +.Fn item_term "MENU *menu" +.Ft void (*hook)() +.Fn menu_init "MENU *menu" +.Ft void (*hook)() +.Fn menu_term "MENU *menu" +.Ft int +.Fn set_item_init "MENU *menu" "void (*hook)())" +.Ft int +.Fn set_item_term "MENU *menu" "void (*hook)())" +.Ft int +.Fn set_menu_init "MENU *menu" "void (*hook)())" +.Ft int +.Fn set_menu_term "MENU *menu" "void (*hook)())" +.Sh DESCRIPTION +The +.Fn item_init +function returns a pointer to the function that will be called +whenever the menu is posted and also just after the current item +changes. +This is set by the +.Fn set_item_init +call. +The +.Fn item_term +function returns a pointer to the function that will be called before +the menu is unposted and just before the current item changes, this +pointer is set by the +.Fn set_item_term +call. +The +.Fn menu_init +functions returns a pointer to the function that will be called just +before the menu is posted to the screen. +This pointer is set by the +.Fn set_menu_init +function call. +The +.Fn menu_term +function returns a pointer to the function that will be called just +after the menu has been unposted, this pointer is set by the +.Fn set_menu_term +function. +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_current.3 b/static/netbsd/man3/menu_item_current.3 new file mode 100644 index 00000000..98a6e73f --- /dev/null +++ b/static/netbsd/man3/menu_item_current.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: menu_item_current.3,v 1.10 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_CURRENT 3 +.Os +.Sh NAME +.Nm current_item , +.Nm item_index , +.Nm set_current_item , +.Nm set_top_row +.Nm top_row +.Nd get or set item pointers or top row +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft ITEM * +.Fn current_item "MENU *menu" +.Ft int +.Fn item_index "ITEM *item" +.Ft int +.Fn set_current_item "MENU *menu" "ITEM *item" +.Ft int +.Fn set_top_row "MENU *menu" "int row" +.Ft int +.Fn top_row "MENU *menu" +.Sh DESCRIPTION +The +.Fn current_item +returns a pointer to the current menu item. +The +.Fn set_current_item +can be used to set this to the item give. +The +.Fn item_index +function returns the index number in the array of items for the item +pointed to by the +.Fa item +parameter. +The +.Fn set_top_row +function sets the top row of the menu displayed to be the row given. +The current item becomes the leftmost item of the top row. +The +.Fn top_row +call returns the row number that is currently at the top of the +displayed menu. +.Sh RETURN VALUES +.Fn current_item +returns NULL if no items are attached to the menu. +.Pp +.Bl -tag -width E_NOT_CONNECTED -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_name.3 b/static/netbsd/man3/menu_item_name.3 new file mode 100644 index 00000000..69dcf0dc --- /dev/null +++ b/static/netbsd/man3/menu_item_name.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: menu_item_name.3,v 1.10 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_NAME 3 +.Os +.Sh NAME +.Nm item_description , +.Nm item_name +.Nd get item name or description +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char * +.Fn item_description "ITEM *item" +.Ft char * +.Fn item_name "ITEM *item" +.Sh DESCRIPTION +The +.Fn item_description +.Fa menu +function returns the description string associated with the passed +item. +The +.Fn item_name +function returns the name string associated with the passed item. +.Sh RETURN VALUES +The function +.Fn item_description +and +.Fn item_name +functions return NULL if the item pointer is not valid. +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_new.3 b/static/netbsd/man3/menu_item_new.3 new file mode 100644 index 00000000..8365318f --- /dev/null +++ b/static/netbsd/man3/menu_item_new.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: menu_item_new.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_NEW 3 +.Os +.Sh NAME +.Nm free_item , +.Nm new_item +.Nd create or delete menu item +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn free_item "ITEM *item" +.Ft ITEM * +.Fn new_item "char *name" "char *description" +.Sh DESCRIPTION +The +.Fn free_item +function destroys the item and frees all allocated storage for that +item. +The +.Fn new_item +allocates storage for a new item then copies in the item name and +description for the new item. +A pointer to the newly created item is returned to the caller. +.Sh RETURN VALUES +The +.Fn new_item +function returns NULL on failure, the +.Fn free_item +returns one of the following error values: +.Pp +.Bl -tag -width E_BAD_ARGUMENT -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_opts.3 b/static/netbsd/man3/menu_item_opts.3 new file mode 100644 index 00000000..53fbe34d --- /dev/null +++ b/static/netbsd/man3/menu_item_opts.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: menu_item_opts.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_OPTS 3 +.Os +.Sh NAME +.Nm item_opts , +.Nm item_opts_off , +.Nm item_opts_on +.Nd get or modify options for an item +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft OPTIONS +.Fn item_opts "ITEM *item" +.Ft int +.Fn item_opts_off "ITEM *item" "OPTIONS opts" +.Ft int +.Fn item_opts_on "ITEM *item" "OPTIONS opts" +.Sh DESCRIPTION +The +.Fn item_opts +function returns the options currently set for the given item. +The +.Fn item_opts_off +function turns off the options passed in +.Fa opts +for the item passed. +The +.Fn item_opts_on +function turns on the options passed in +.Fa opts +for the item given. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_SYSTEM_ERROR -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_userptr.3 b/static/netbsd/man3/menu_item_userptr.3 new file mode 100644 index 00000000..82ca9fd3 --- /dev/null +++ b/static/netbsd/man3/menu_item_userptr.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: menu_item_userptr.3,v 1.8 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_USERPTR 3 +.Os +.Sh NAME +.Nm item_userptr , +.Nm set_item_userptr +.Nd get or set user pointer for an item +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char * +.Fn item_userptr "ITEM *item" +.Ft int +.Fn set_item_userptr "ITEM *item" "char *userptr" +.Sh DESCRIPTION +The +.Fn item_userptr +function returns the value of the user defined pointer for the given +item, this pointer is defined by the +.Fn set_item_userptr +function. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_SYSTEM_ERROR -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_item_value.3 b/static/netbsd/man3/menu_item_value.3 new file mode 100644 index 00000000..8f513cbf --- /dev/null +++ b/static/netbsd/man3/menu_item_value.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: menu_item_value.3,v 1.12 2017/07/03 21:32:50 wiz Exp $ .\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_VALUE 3 +.Os +.Sh NAME +.Nm item_value , +.Nm set_item_value , +.Nm item_selected +.Nd get or set value for an item +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn item_value "ITEM *item" +.Ft int +.Fn set_item_value "ITEM *item" "int flag" +.Ft int +.Fn item_selected "MENU *menu" "int **array" +.Sh DESCRIPTION +The +.Fn item_value +function returns value of the item. +If the item has been selected then this value will be TRUE. +The value can also be set by calling +.Fn set_item_value +to set the value to a defined state. +Setting the value to a value +other than TRUE or FALSE will have undefined results. +The +.Fn item_selected +function returns the number of items that are selected in the menu, that +is the number of items whose value is TRUE. +The indexes of the selected +items will be returned in +.Fa array +which will be dynamically allocated to hold the number of indexes. +It is the responsibility of the caller to release this storage by calling +.Xr free 3 +when the storage is no longer required. +If there are no elements selected in the items array then +.Fn item_selected +will return 0 and +.Fa array +will be NULL. +If an error occurs +.Fn item_selected +will return one of the below return values which are less than 0. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_REQUEST_DENIED -compact +.It Er E_OK +The function was successful. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.It Er E_SYSTEM_ERROR +A system error occurred whilst processing the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . +.Pp +The function +.Fn item_selected +is a +.Nx +extension and must not be used in portable code. diff --git a/static/netbsd/man3/menu_item_visible.3 b/static/netbsd/man3/menu_item_visible.3 new file mode 100644 index 00000000..490fe92b --- /dev/null +++ b/static/netbsd/man3/menu_item_visible.3 @@ -0,0 +1,67 @@ +.\" $NetBSD: menu_item_visible.3,v 1.8 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEM_VISIBLE 3 +.Os +.Sh NAME +.Nm item_visible +.Nd get visibility status of an item +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn item_visible "ITEM *item" +.Sh DESCRIPTION +The +.Fn item_visible +function returns TRUE if the item passed is currently visible in a +menu. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_NOT_CONNECTED -compact +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_items.3 b/static/netbsd/man3/menu_items.3 new file mode 100644 index 00000000..c567e63c --- /dev/null +++ b/static/netbsd/man3/menu_items.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: menu_items.3,v 1.11 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_ITEMS 3 +.Os +.Sh NAME +.Nm item_count , +.Nm menu_items , +.Nm set_menu_items +.Nd attach items to menus or check correspondences +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn item_count "MENU *menu" +.Ft ITEM ** +.Fn menu_items "MENU *menu" +.Ft int +.Fn set_menu_items "MENU *menu" "ITEM **items" +.Sh DESCRIPTION +The +.Fn item_count +.Fa menu +function returns the number of items currently attached to the menu +passed. +The +.Fn menu_items +function returns a pointer to an array of item pointers that represent +the menu items currently attached to the given menu. +Apart from using +.Fn new_menu +(see +.Xr menu_new 3 ) +menu items may be attached to a menu by calling +.Fn set_menu_items +any items currently attached to the menu will be detached and the NULL +terminated array of new items will be attached to the menu. +.Sh RETURN VALUES +Any function returning a string pointer will return NULL if an error +occurs. +Functions returning an integer will return one of the following: +.Pp +.Bl -tag -width E_CONNECTED -compact +.It Er E_OK +The function was successful. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_mark.3 b/static/netbsd/man3/menu_mark.3 new file mode 100644 index 00000000..6f85bf85 --- /dev/null +++ b/static/netbsd/man3/menu_mark.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: menu_mark.3,v 1.10 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_MARK 3 +.Os +.Sh NAME +.Nm menu_mark , +.Nm menu_unmark , +.Nm set_menu_mark , +.Nm set_menu_unmark +.Nd get or set strings that show mark status for a menu +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char * +.Fn menu_mark "MENU *menu" +.Ft char * +.Fn menu_unmark "MENU *menu" +.Ft int +.Fn set_menu_mark "MENU *menu" "char *mark" +.Ft int +.Fn set_menu_unmark "MENU *menu" "char *mark" +.Sh DESCRIPTION +The +.Fn menu_mark +function returns a pointer to the character string that is used to +mark selected items in the menu. +The mark string is set by the +.Fn set_menu_mark +function. +The +.Fn menu_unmark +function returns a pointer to the character string that is used to +indicate a menu items is not selected, this string is set by the +.Fn set_menu_unmark +function. +The mark and unmark strings may be of differing lengths, the room +allocated to drawing the mark will be the maximum of the lengths of +both the mark and unmark strings. +The shorter of the two strings will be left justified and space padded. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_POSTED +The menu is not posted. +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_SELECTABLE +The item could not be selected. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_new.3 b/static/netbsd/man3/menu_new.3 new file mode 100644 index 00000000..8efc0368 --- /dev/null +++ b/static/netbsd/man3/menu_new.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: menu_new.3,v 1.11 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_NEW 3 +.Os +.Sh NAME +.Nm free_menu , +.Nm new_menu +.Nd create or delete a menu +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn free_menu "MENU *menu" +.Ft MENU * +.Fn new_menu "ITEM **items" +.Sh DESCRIPTION +The +.Fn free_menu +.Fa menu +function destroys the given menu and frees all allocated storage +associated with the menu. +All items associated with the menu are +detached from the menu before it is destroyed. +The +.Fn new_menu +function allocates storage for a new menu and initializes all the +values to the defined defaults. +If the items pointer passed is not a NULL then the given NULL terminated +array of items is attached to the new menu. +.Sh RETURN VALUES +The +.Fn new_menu +function returns NULL on error, while the +.Fn free_menu +function returns one of the following error values: +.Pp +.Bl -tag -width E_BAD_ARGUMENT -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_opts.3 b/static/netbsd/man3/menu_opts.3 new file mode 100644 index 00000000..c89840e0 --- /dev/null +++ b/static/netbsd/man3/menu_opts.3 @@ -0,0 +1,97 @@ +.\" $NetBSD: menu_opts.3,v 1.12 2023/08/17 14:21:18 andvar Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 30, 2019 +.Dt MENU_OPTS 3 +.Os +.Sh NAME +.Nm menu_opts , +.Nm menu_opts_off , +.Nm menu_opts_on , +.Nm set_menu_opts +.Nd get or modify options for a menu +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft OPTIONS +.Fn menu_opts "MENU *menu" +.Ft int +.Fn menu_opts_off "MENU *menu" "OPTIONS opts" +.Ft int +.Fn menu_opts_on "MENU *menu" "OPTIONS opts" +.Ft int +.Fn set_menu_opts "MENU *menu" "OPTIONS opts" +.Sh DESCRIPTION +The +.Fn menu_opts +function returns the current options set for the menu given. +The +.Fn menu_opts_off +function turns off the menu options given by the opts parameter for +the menu. +The +.Fn menu_opts_on +function turns on the menu options given by the opts parameter for the +menu passed. +The +.Fn set_menu_opts +sets the menu options to the value given in opts. +Options may be logically ORed together. +Valid options are: +.Bl -column -offset indent ".Sy Option" ".Sy Meaning" +.It Sy Option Ta Sy Meaning +.It Dv O_ONEVALUE Ta The menu may only have one item selected at a time. +The menu mark will indicate the current item. +If this option is off then multiple menu items may be selected and +the menu mark will be displayed on each selected item. +.El +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_BAD_ARGUMENT -compact +.It Er E_OK +The function was successful. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Aq Pa menu.h +automatically includes both +.Aq Pa curses.h +and +.Aq Pa eti.h . diff --git a/static/netbsd/man3/menu_pattern.3 b/static/netbsd/man3/menu_pattern.3 new file mode 100644 index 00000000..1efaa7c5 --- /dev/null +++ b/static/netbsd/man3/menu_pattern.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: menu_pattern.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_PATTERN 3 +.Os +.Sh NAME +.Nm menu_pattern , +.Nm set_menu_pattern +.Nd get or set menu pattern +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char * +.Fn menu_pattern "MENU *menu" +.Sh DESCRIPTION +The +.Fn menu_pattern +function returns a pointer to the string that is currently in the menu +pattern buffer. +The menu pattern buffer can be set by calling +.Fn set_menu_pattern +which will set the pattern buffer to the string passed and then +attempt to match that string against the names of the items in the +attached items. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_BAD_ARGUMENT -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_NO_MATCH +The character search failed to find a match. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_post.3 b/static/netbsd/man3/menu_post.3 new file mode 100644 index 00000000..91067b53 --- /dev/null +++ b/static/netbsd/man3/menu_post.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: menu_post.3,v 1.11 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_POST 3 +.Os +.Sh NAME +.Nm post_menu , +.Nm unpost_menu +.Nd post (draw) or unpost a menu +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft int +.Fn post_menu "MENU *menu" +.Ft int +.Fn unpost_menu "MENU *menu" +.Sh DESCRIPTION +The +.Fn post_menu +function causes the menu to be drawn on the screen. +Any functions defined by either +.Fn set_menu_init +or +.Fn set_item_init +(see +.Xr menu_hook 3 ) +are called before the menu is placed on the screen. +The +.Fn unpost_menu +does the opposite, it removes a menu from the screen. +Any functions defined by both +.Fn set_menu_term +and +.Fn set_item_term +(see +.Xr menu_hook 3 ) +are called prior to the menu's removal. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_NOT_CONNECTED -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menu_hook 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_userptr.3 b/static/netbsd/man3/menu_userptr.3 new file mode 100644 index 00000000..fec4d0dc --- /dev/null +++ b/static/netbsd/man3/menu_userptr.3 @@ -0,0 +1,73 @@ +.\" $NetBSD: menu_userptr.3,v 1.9 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_USERPTR 3 +.Os +.Sh NAME +.Nm menu_userptr , +.Nm set_menu_userptr +.Nd get or set user pointer for a menu +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft char * +.Fn menu_userptr "MENU *menu" +.Ft int +.Fn set_menu_userptr "MENU *menu" "char *ptr" +.Sh DESCRIPTION +The +.Fn menu_userptr +function returns the pointer to the user defined pointer for the given +menu. +This pointer is set by the +.Fn set_menu_userptr +function. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_SYSTEM_ERROR -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menu_win.3 b/static/netbsd/man3/menu_win.3 new file mode 100644 index 00000000..21678ad5 --- /dev/null +++ b/static/netbsd/man3/menu_win.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: menu_win.3,v 1.11 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENU_WIN 3 +.Os +.Sh NAME +.Nm menu_sub , +.Nm menu_win , +.Nm scale_menu , +.Nm set_menu_sub , +.Nm set_menu_win +.Nd sub-menu handling +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Ft WINDOW * +.Fn menu_sub "MENU *menu" +.Ft WINDOW * +.Fn menu_win "MENU *menu" +.Ft int +.Fn scale_menu "MENU *menu" "int *rows" "int *cols" +.Ft int +.Fn set_menu_sub "MENU *menu" "WINDOW *sub" +.Ft int +.Fn set_menu_win "MENU *menu" "WINDOW *win" +.Sh DESCRIPTION +The +.Fn menu_sub +function returns a pointer to the window that will be used to post a +menu into, this pointer is set by the +.Fn set_menu_sub +function. +The +.Fn menu_win +function returns a pointer to the window in which the menu subwindow +will be created when the menu is posted, this pointer is set by the +.Fn set_menu_win +function. +The +.Fn scale_menu +function calculates the minimum size a window needs to be to hold the +items for a given menu, the parameters rows and cols are set to the +required number of rows and columns respectively. +.Sh RETURN VALUES +The functions return one of the following error values: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_POSTED +The menu is not posted +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_SELECTABLE +The item could not be selected. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menus 3 +.Sh NOTES +The header +.Pa <menu.h> +automatically includes both +.Pa <curses.h> +and +.Pa <eti.h> . diff --git a/static/netbsd/man3/menus.3 b/static/netbsd/man3/menus.3 new file mode 100644 index 00000000..9016fcfd --- /dev/null +++ b/static/netbsd/man3/menus.3 @@ -0,0 +1,299 @@ +.\" $NetBSD: menus.3,v 1.16 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1999 +.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au +.\" +.\" This code is donated to The NetBSD Foundation by the author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 10, 1999 +.Dt MENUS 3 +.Os +.Sh NAME +.Nm menus +.Nd menu library +.Sh LIBRARY +.Lb libmenu +.Sh SYNOPSIS +.In menu.h +.Sh DESCRIPTION +The +.Nm +library provides a terminal independent menu system using the +.Xr curses 3 +library. +Before using the +.Nm +functions the terminal must be set up by +.Xr curses 3 +using the +.Fn initscr +function or similar. +Programs using +.Nm +functions must be linked with the +.Xr curses 3 +library. +.Pp +The +.Nm +library provides facilities for defining menu items, placing a menu on the +terminal screen, assign pre- and post-change operations and setting the +attributes of both the menu and its items. +.Ss Defining default attributes for menus and items +The +.Nm +library allows any settable attribute or option of both the menu and item +objects to be defined such that any new menu or item automatically inherits +the value as default. +Setting the default value will not affect any item or +menu that has already been created but will be applied to subsequent objects. +To set the default attribute or option the set routine is passed a NULL +pointer in the item or menu parameter when calling the set routine. +The current default value can be retrieved by calling the get routine with a +NULL pointer for the item or menu parameter. +.Pp +.Bl -tag -width item_description -compact +.It function name +manual page name +.It current_item +.Xr menu_item_current 3 +.It free_item +.Xr menu_item_new 3 +.It free_menu +.Xr menu_new 3 +.It item_count +.Xr menu_items 3 +.It item_description +.Xr menu_item_name 3 +.It item_index +.Xr menu_item_current 3 +.It item_init +.Xr menu_hook 3 +.It item_name +.Xr menu_item_name 3 +.It item_opts +.Xr menu_item_opts 3 +.It item_opts_off +.Xr menu_item_opts 3 +.It item_opts_on +.Xr menu_item_opts 3 +.It item_selected +.Xr menu_item_value 3 +.It item_term +.Xr menu_hook 3 +.It item_userptr +.Xr menu_item_userptr 3 +.It item_value +.Xr menu_item_value 3 +.It item_visible +.Xr menu_item_visible 3 +.It menu_back +.Xr menu_attributes 3 +.It menu_driver +.Xr menu_driver 3 +.It menu_fore +.Xr menu_attributes 3 +.It menu_format +.Xr menu_format 3 +.It menu_grey +.Xr menu_attributes 3 +.It menu_init +.Xr menu_hook 3 +.It menu_items +.Xr menu_items 3 +.It menu_mark +.Xr menu_mark 3 +.It menu_opts +.Xr menu_opts 3 +.It menu_opts_off +.Xr menu_opts 3 +.It menu_opts_on +.Xr menu_opts 3 +.It menu_pad +.Xr menu_attributes 3 +.It menu_pattern +.Xr menu_pattern 3 +.It menu_sub +.Xr menu_win 3 +.It menu_term +.Xr menu_hook 3 +.It menu_unmark +.Xr menu_mark 3 +.It menu_userptr +.Xr menu_userptr 3 +.It men_win +.Xr menu_win 3 +.It new_item +.Xr menu_item_new 3 +.It new_menu +.Xr menu_new 3 +.It pos_menu_cursor +.Xr menu_cursor 3 +.It post_menu +.Xr menu_post 3 +.It scale_menu +.Xr menu_win 3 +.It set_current_item +.Xr menu_item_current 3 +.It set_item_init +.Xr menu_hook 3 +.It set_item_opts +.Xr menu_item_opts 3 +.It set_item_term +.Xr menu_hook 3 +.It set_item_userptr +.Xr menu_item_userptr 3 +.It set_item_value +.Xr menu_item_value 3 +.It set_menu_back +.Xr menu_attributes 3 +.It set_menu_fore +.Xr menu_attributes 3 +.It set_menu_format +.Xr menu_format 3 +.It set_menu_grey +.Xr menu_attributes 3 +.It set_menu_init +.Xr menu_hook 3 +.It set_menu_items +.Xr menu_items 3 +.It set_menu_mark +.Xr menu_mark 3 +.It set_menu_opts +.Xr menu_opts 3 +.It set_menu_pad +.Xr menu_attributes 3 +.It set_menu_pattern +.Xr menu_pattern 3 +.It set_menu_sub +.Xr menu_win 3 +.It set_menu_term +.Xr menu_hook 3 +.It set_menu_unmark +.Xr menu_mark 3 +.It set_menu_userptr +.Xr menu_userptr 3 +.It set_menu_win +.Xr menu_win 3 +.It set_top_row +.Xr menu_item_current 3 +.It top_row +.Xr menu_item_current 3 +.It unpost_menu +.Xr menu_post 3 +.El +.Sh RETURN VALUES +Any function returning a string pointer will return NULL if an error +occurs. +Functions returning an integer will return one of the following: +.Pp +.Bl -tag -width E_UNKNOWN_COMMAND -compact +.It Er E_OK +The function was successful. +.It Er E_SYSTEM_ERROR +There was a system error during the call. +.It Er E_BAD_ARGUMENT +One or more of the arguments passed to the function was incorrect. +.It Er E_POSTED +The menu is already posted. +.It Er E_CONNECTED +An item was already connected to a menu. +.It Er E_BAD_STATE +The function was called from within an initialization or termination +routine. +.It Er E_NO_ROOM +The menu does not fit within the subwindow. +.It Er E_NOT_POSTED +The menu is not posted. +.It Er E_UNKNOWN_COMMAND +The menu driver does not recognize the request passed to it. +.It Er E_NO_MATCH +The character search failed to find a match. +.It Er E_NOT_SELECTABLE +The item could not be selected. +.It Er E_NOT_CONNECTED +The item is not connected to a menu. +.It Er E_REQUEST_DENIED +The menu driver could not process the request. +.El +.Sh SEE ALSO +.Xr curses 3 , +.Xr menu_attributes 3 , +.Xr menu_cursor 3 , +.Xr menu_driver 3 , +.Xr menu_format 3 , +.Xr menu_hook 3 , +.Xr menu_item_current 3 , +.Xr menu_item_name 3 , +.Xr menu_item_new 3 , +.Xr menu_item_opts 3 , +.Xr menu_item_userptr 3 , +.Xr menu_item_value 3 , +.Xr menu_item_visible 3 , +.Xr menu_items 3 , +.Xr menu_mark 3 , +.Xr menu_new 3 , +.Xr menu_opts 3 , +.Xr menu_pattern 3 , +.Xr menu_post 3 , +.Xr menu_userptr 3 , +.Xr menu_win 3 +.Sh NOTES +This implementation of the menus library does depart in behaviour +subtly from the original AT & T implementation. +Some of the more notable departures are: +.Pp +.Bl -tag -width "item marking" -compact +.It unmark +The original implementation did not have a marker for an unmarked field +the mark was only displayed next to a field when it had been marked using +the REQ_TOGGLE_ITEM. +In this implementation a separate marker can be used +to indicate an unmarked item. +This can be set using set_menu_unmark function. +There is no requirement for the mark and unmark strings to be the same +length. +Room will be left for the longest of the two. +The unmark string +is optional, if it is not set then menus defaults to the old behaviour. +.It item marking +In the original implementation the current item was considered selected +and hence had the mark string displayed next to it. +This implementation does not do this because the Author considers the +effect too confusing. +Especially in the case of a multiple selection menu because there was no +way to tell if the current item is selected or not without shifting off +of it. +Since the current item is displayed using the foreground attribute it was +deemed unnecessary to also display the mark string against the current item. +.El +.Pp +The option O_RADIO and the function +.Fn item_selected +are +.Nx +extensions and must not be used in portable code. diff --git a/static/netbsd/man3/mi_vector_hash.3 b/static/netbsd/man3/mi_vector_hash.3 new file mode 100644 index 00000000..6827e612 --- /dev/null +++ b/static/netbsd/man3/mi_vector_hash.3 @@ -0,0 +1,65 @@ +.\" $NetBSD: mi_vector_hash.3,v 1.2 2009/07/21 12:40:52 joerg Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 13, 2009 +.Dt MI_VECTOR_HASH 3 +.Os +.Sh NAME +.Nm mi_vector_hash +.Nd fast 32bit hash functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn mi_vector_hash "const void * restrict key" "size_t len" \ + "uint32_t seed" "uint32_t hashes[3]" +.Sh DESCRIPTION +The +.Nm +function computes three 32-bit hash values of the memory area starting at +.Fa key +with length +.Fa len . +.Pp +The output is identical on all architectures and only depends on +.Fa key +and +.Fa seed . +.Sh IMPLEMENTATION NOTES +An optimised code path is used if +.Fa key +is aligned on a 32-bit boundary. +.Sh HISTORY +The +.Nm +function appeared in +.Nx 6.0 . +.Sh AUTHORS +The hash function has been created by Bob Jenkins. diff --git a/static/netbsd/man3/mktemp.3 b/static/netbsd/man3/mktemp.3 new file mode 100644 index 00000000..496ff865 --- /dev/null +++ b/static/netbsd/man3/mktemp.3 @@ -0,0 +1,390 @@ +.\" $NetBSD: mktemp.3,v 1.36 2025/08/06 23:52:06 kre Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd November 2, 2024 +.Dt MKTEMP 3 +.Os +.Sh NAME +.Nm mktemp , +.Nm mkstemp , +.Nm mkstemps , +.Nm mkostemp , +.Nm mkostemps , +.Nm mkdtemp +.Nd make unique temporary file or directory name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn mktemp "char *template" +.Ft int +.Fn mkstemp "char *template" +.Ft int +.Fn mkostemp "char *template" "int oflags" +.Ft int +.Fn mkostemps "char *template" "int suffixlen" "int oflags" +.Ft char * +.Fn mkdtemp "char *template" +.In unistd.h +.Ft int +.Fn mkstemps "char *template" "int suffixlen" +.Sh DESCRIPTION +The +.Fn mktemp +function +takes the given file name template and overwrites a portion of it +to create a file name. +This file name is unique and suitable for use +by the application. +The template may be any file name with some number of +.Sq Li X +characters appended to it, for example +.Pa /tmp/temp.XXXXXX . +The trailing +.Sq Li X +characters in the template are replaced with a unique letter and number +combination. +.Fn mktemp +can return depends on the number of +.Sq Li X +characters provided. +Although the +.Nx +implementation of the functions will accept any number of trailing +.Sq Li X +characters, for portability reasons one should use only six. +Using six +.Sq Li X +characters will result in +.Fn mktemp +testing roughly 62 ** 6 (56800235584) combinations. +.Pp +The +.Fn mkstemp +function +makes the same replacement to the template and creates the template file, +mode 0600, returning a file descriptor opened for reading and writing. +This avoids the race between testing for a file's existence and opening it +for use. +The +.Fn mkostemp +function +is like +.Fn mkstemp +but allows specifying additional +.Xr open 2 +flags (defined in +.In fcntl.h ) . +The permitted flags are +.Dv O_APPEND , +.Dv O_DIRECT , +.Dv O_SHLOCK , +.Dv O_EXLOCK , +.Dv O_SYNC , +.Dv O_CLOEXEC +and +.Dv O_CLOFORK . +.Pp +The +.Fn mkstemps +and +.Fn mkostemps +functions act the same as +.Fn mkstemp +and +.Fn mkostemp +respectively, +except they permit a suffix to exist in the template. +The template should be of the form +.Pa /tmp/tmpXXXXXXsuffix . +The +.Fn mkstemps +and +.Fn mkostemps +function +are told the length of the suffix string. +.Pp +The +.Fn mkdtemp +function +is similar to +.Fn mkstemp , +but it creates a mode 0700 directory instead and returns the path. +.Pp +Please note that the permissions of the file or directory being created are +subject to the restrictions imposed by the +.Xr umask 2 +system call. +It may thus happen that the created file is unreadable and/or unwritable. +.Sh RETURN VALUES +The +.Fn mktemp +and +.Fn mkdtemp +functions +return a pointer to the template on success and +.Dv NULL +on failure. +The +.Fn mkstemp , +.Fn mkostemp , +.Fn mkstemps +and +.Fn mkostemps +functions +returns \-1 if no suitable file could be created. +If either call fails an error code is placed in the global variable +.Va errno . +.Sh EXAMPLES +Quite often a programmer will want to replace a use of +.Fn mktemp +with +.Fn mkstemp , +usually to avoid the problems described above. +Doing this correctly requires a good understanding of the code in question. +.Pp +For instance, code of this form: +.Bd -literal -offset indent +char sfn[15] = ""; +FILE *sfp; + +strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn); +if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) { + fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); + return (NULL); +} +return (sfp); +.Ed +.Pp +should be rewritten like this: +.Bd -literal -offset indent +char sfn[15] = ""; +FILE *sfp; +int fd = -1; + +strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn); +if ((fd = mkstemp(sfn)) == -1 || + (sfp = fdopen(fd, "w+")) == NULL) { + if (fd != -1) { + unlink(sfn); + close(fd); + } + fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); + return (NULL); +} +return (sfp); +.Ed +.Pp +Often one will find code which uses +.Fn mktemp +very early on, perhaps to globally initialize the template nicely, but the +code which calls +.Xr open 2 +or +.Xr fopen 3 +on that filename will occur much later. +(In almost all cases, the use of +.Xr fopen 3 +will mean that the flags +.Dv O_CREAT +| +.Dv O_EXCL +are not given to +.Xr open 2 , +and thus a symbolic link race becomes possible, hence making +necessary the use of +.Xr fdopen 3 +as seen above). +Furthermore, one must be careful about code which opens, closes, and then +re-opens the file in question. +Finally, one must ensure that upon error the temporary file is +removed correctly. +.Pp +There are also cases where modifying the code to use +.Fn mktemp , +in concert with +.Xr open 2 +using the flags +.Dv O_CREAT +| +.Dv O_EXCL , +is better, as long as the code retries a new template if +.Xr open 2 +fails with an +.Va errno +of +.Er EEXIST . +.Sh ERRORS +The +.Fn mkstemp , +.Fn mkostemp , +.Fn mkstemps , +.Fn mkostemps +and +.Fn mkdtemp +functions +may set +.Va errno +to one of the following values: +.Bl -tag -width Er +.It Bq Er ENOTDIR +The pathname portion of the template is not an existing directory. +.El +.Pp +The +.Fn mktemp , +.Fn mkstemp +and +.Fn mkdtemp +functions +may also set +.Va errno +to any value specified by the +.Xr stat 2 +function. +.Pp +The +.Fn mkstemp +function +may also set +.Va errno +to any value specified by the +.Xr open 2 +function. +.Pp +The +.Fn mkdtemp +function +may also set +.Va errno +to any value specified by the +.Xr mkdir 2 +function. +.Sh SEE ALSO +.Xr chmod 2 , +.Xr getpid 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mktemp +conforms to +.St -p1003.1-2001 . +It was however removed from the specification in the +.St -p1003.1-2008 +revision. +The +.Fn mkstemp +function conforms to +.St -p1003.1-2004 . +The +.Fn mkdtemp +function conforms to +.St -p1003.1-2008 . +The +.Fn mkostemp +function conforms to +.St -p1003.1-2024 . +.Sh HISTORY +A +.Fn mktemp +function appeared in +.At v7 . +.Pp +The +.Fn mkstemp +function appeared in +.Bx 4.4 . +.Pp +The +.Fn mkdtemp +function appeared in +.Nx 1.4 . +The +.Fn mkstemps +function first appeared in +.Ox 2.4 , +and later in +.Fx 3.4 +and +.Nx 7.0 . +The +.Fn mkostemp +and +.Fn mkostemps +functions appeared in +.Fx 10.0 +and +.Nx 7.0 . +.Sh BUGS +For +.Fn mktemp +there is an obvious race between file name selection and file +creation and deletion: the program is typically written to call +.Xr tmpnam 3 , +.Xr tempnam 3 , +or +.Fn mktemp . +Subsequently, the program calls +.Xr open 2 +or +.Xr fopen 3 +and erroneously opens a file (or symbolic link, fifo or other +device) that the attacker has created in the expected file location. +Hence +.Fn mkstemp +is recommended, since it atomically creates the file. +An attacker can guess the filenames produced by +.Fn mktemp . +Whenever it is possible, +.Fn mkstemp +or +.Fn mkdtemp +should be used instead. +.Pp +For this reason, +.Xr ld 1 +will output a warning message whenever it links code that uses +.Fn mktemp . +.Sh SECURITY CONSIDERATIONS +The use of +.Fn mktemp +should generally be avoided, as a hostile process can exploit a race +condition in the time between the generation of a temporary filename by +.Fn mktemp +and the invoker's use of the temporary name. +A link-time warning will be issued advising the use of +.Fn mkstemp +or +.Fn mkdtemp +instead. diff --git a/static/netbsd/man3/modf.3 b/static/netbsd/man3/modf.3 new file mode 100644 index 00000000..65127188 --- /dev/null +++ b/static/netbsd/man3/modf.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: modf.3,v 1.3 2017/02/01 15:57:47 abhinav Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)modf.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd March 7, 2016 +.Dt MODF 3 +.Os +.Sh NAME +.Nm modf , +.Nm modff , +.Nm modfl +.Nd extract signed integral and fractional values from floating-point number +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn modf "double value" "double *iptr" +.Ft float +.Fn modff "float value" "float *iptr" +.Ft long double +.Fn modfl "long double value" "long double *iptr" +.Sh DESCRIPTION +The +.Fn modf +function breaks the argument +.Fa value +into integral and fractional parts, each of which has the +same sign as the argument. +It stores the integral part as a +.Em double +in the object pointed to by +.Fa iptr . +.Sh RETURN VALUES +The +.Fn modf +function returns the signed fractional part of +.Fa value . +.Sh SEE ALSO +.Xr frexp 3 , +.Xr ldexp 3 , +.Xr math 3 +.Sh STANDARDS +The +.Fn modf +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/modrdn.out.provider.3 b/static/netbsd/man3/modrdn.out.provider.3 new file mode 100644 index 00000000..67299dc5 --- /dev/null +++ b/static/netbsd/man3/modrdn.out.provider.3 @@ -0,0 +1,19 @@ +dn: cn=James A Jones 1,ou=Alumni Association,ou=People,dc=example,dc=com +objectClass: OpenLDAPperson +cn: James A Jones 1 +cn: James Jones +cn: Jim Jones +sn: Jones +uid: jaj +postalAddress: Alumni Association $ 111 Maple St $ Anytown, MI 48109 +seeAlso: cn=All Staff,ou=Groups,dc=example,dc=com +userPassword:: amFq +homePostalAddress: 3882 Beverly Rd. $ Anytown, MI 48105 +homePhone: +1 313 555 4772 +description: Outstanding +title: Mad Cow Researcher, UM Alumni Association +pager: +1 313 555 3923 +mail: jaj@mail.alumni.example.com +facsimileTelephoneNumber: +1 313 555 4332 +telephoneNumber: +1 313 555 0895 + diff --git a/static/netbsd/man3/moncontrol.3 b/static/netbsd/man3/moncontrol.3 new file mode 100644 index 00000000..bc3dc325 --- /dev/null +++ b/static/netbsd/man3/moncontrol.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: moncontrol.3,v 1.10 2009/04/11 15:33:27 joerg Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)moncontrol.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt MONCONTROL 3 +.Os +.Sh NAME +.Nm moncontrol , +.Nm monstartup +.Nd control execution profile +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fn moncontrol "int mode" +.Fn monstartup "u_long *lowpc" "u_long *highpc" +.Sh DESCRIPTION +An executable program compiled using the +.Fl pg +option to +.Xr cc 1 +automatically includes calls to collect statistics for the +.Xr gprof 1 +call-graph execution profiler. +In typical operation, profiling begins at program startup +and ends when the program calls exit. +When the program exits, the profiling data are written to the file +.Em gmon.out , +then +.Xr gprof 1 +can be used to examine the results. +.Pp +.Fn moncontrol +selectively controls profiling within a program. +When the program starts, profiling begins. +To stop the collection of histogram ticks and call counts use +.Fn moncontrol 0 ; +to resume the collection of histogram ticks and call counts use +.Fn moncontrol 1 . +This feature allows the cost of particular operations to be measured. +Note that an output file will be produced on program exit +regardless of the state of +.Fn moncontrol . +.Pp +Programs that are not loaded with +.Fl pg +may selectively collect profiling statistics by calling +.Fn monstartup +with the range of addresses to be profiled. +.Fa lowpc +and +.Fa highpc +specify the address range that is to be sampled; +the lowest address sampled is that of +.Fa lowpc +and the highest is just below +.Fa highpc . +Only functions in that range that have been compiled with the +.Fl pg +option to +.Xr cc 1 +will appear in the call graph part of the output; +however, all functions in that address range will +have their execution time measured. +Profiling begins on return from +.Fn monstartup . +.Sh ENVIRONMENT +.Bl -tag -width "PROFDIR" +.It Ev PROFDIR +Directory to place the output file(s) in. +When this is set, instead of writing the profiling output to +.Pa gmon.out , +a filename is generated from the process id and name of the program +(e.g., +.Pa 123.a.out ) . +If you are profiling a program that forks, +or otherwise creates multiple copies, +setting this is the only reasonable way to get all profiling data. +.El +.Sh FILES +.Bl -tag -width ".Pa gmon.out" -compact +.It Pa gmon.out +execution data file +.El +.Sh SEE ALSO +.Xr cc 1 , +.Xr gprof 1 , +.Xr profil 2 diff --git a/static/netbsd/man3/move_panel.3 b/static/netbsd/man3/move_panel.3 new file mode 100644 index 00000000..d4c5aead --- /dev/null +++ b/static/netbsd/man3/move_panel.3 @@ -0,0 +1,70 @@ +.\" $NetBSD: move_panel.3,v 1.4 2015/10/28 10:22:40 wiz Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt MOVE_PANEL 3 +.Os +.Sh NAME +.Nm move_panel +.Nd change panel position +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft int +.Fn move_panel "PANEL *p" "int y" "int x" +.\" +.Sh DESCRIPTION +A panel can be moved to a new position by calling the +.Fn move_panel +function. +The +.Fa y +and +.Fa x +positions are the new origin of the panel on the screen. +.Pp +This function is the panel library counterpart of the curses +.Xr mvwin 3 +function. +Curses +.Fn mvwin +must never be directly used on a window associated with a panel. +.Sh RETURN VALUES +The +.Fn move_panel +function will return one of the following +values: +.Pp +.Bl -tag -width ".Dv ERR" -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr mvwin 3 , +.Xr panel 3 diff --git a/static/netbsd/man3/mpool.3 b/static/netbsd/man3/mpool.3 new file mode 100644 index 00000000..14814b9a --- /dev/null +++ b/static/netbsd/man3/mpool.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: mpool.3,v 1.11 2019/03/08 08:35:58 msaitoh Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd December 16, 2010 +.Dt MPOOL 3 +.Os +.Sh NAME +.Nm mpool , +.Nm mpool_open , +.Nm mpool_filter , +.Nm mpool_new , +.Nm mpool_get , +.Nm mpool_put , +.Nm mpool_sync , +.Nm mpool_close +.Nd shared memory buffer pool +.Sh SYNOPSIS +.In db.h +.In mpool.h +.Ft MPOOL * +.Fn mpool_open "DBT *key" "int fd" "pgno_t pagesize" "pgno_t maxcache" +.Ft void +.Fn mpool_filter "MPOOL *mp" "void (*pgin)(void *, pgno_t, void *)" \ +"void (*pgout)(void *, pgno_t, void *)" "void *pgcookie" +.Ft void * +.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" +.Ft void * +.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags" +.Ft int +.Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags" +.Ft int +.Fn mpool_sync "MPOOL *mp" +.Ft int +.Fn mpool_close "MPOOL *mp" +.Sh DESCRIPTION +.Nm +is the library interface intended to provide page oriented buffer +management of files. +The buffers may be shared between processes. +.Pp +The function +.Fn mpool_open +initializes a memory pool. +The +.Fa key +argument is the byte string used to negotiate between multiple +processes wishing to share buffers. +If the file buffers are mapped in shared memory, all processes using +the same key will share the buffers. +If +.Fa key +is +.Dv NULL , +the buffers are mapped into private memory. +The +.Fa fd +argument is a file descriptor for the underlying file, which must be +seekable. +If +.Fa key +is +.No non- Ns Dv NULL +and matches a file already being mapped, the +.Fa fd +argument is ignored. +.Pp +The +.Fa pagesize +argument is the size, in bytes, of the pages into which the file is +broken up. +The +.Fa maxcache +argument is the maximum number of pages from the underlying file to +cache at any one time. +This value is not relative to the number of processes which share a +file's buffers, but will be the largest value specified by any of the +processes sharing the file. +.Pp +The +.Fn mpool_filter +function is intended to make transparent input and output processing +of the pages possible. +If the +.Fa pgin +function is specified, it is called each time a buffer is read into +the memory pool from the backing file. +If the +.Fa pgout +function is specified, it is called each time a buffer is written into +the backing file. +Both functions are called with the +.Fa pgcookie +pointer, the page number and a pointer to the page to being read or +written. +.Pp +The function +.Fn mpool_new +takes an MPOOL pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.Fa pgnoaddr +address. +Otherwise, +.Dv NULL +is returned and errno is set. +.Pp +The function +.Fn mpool_get +takes a MPOOL pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, +.Dv NULL +is returned and errno is set. +The flags parameter is not currently used. +.Pp +The function +.Fn mpool_put +unpins the page referenced by +.Fa pgaddr . +.Fa pgaddr +must be an address previously returned by +.Fn mpool_get +or +.Fn mpool_new . +The flag value is specified by or'ing any of the following values: +.Bl -tag -width MPOOL_DIRTYX -offset indent +.It Dv MPOOL_DIRTY +The page has been modified and needs to be written to the backing +file. +.El +.Pp +.Fn mpool_put +returns 0 on success and \-1 if an error occurs. +.Pp +The function +.Fn mpool_sync +writes all modified pages associated with the MPOOL pointer to the +backing file. +.Fn mpool_sync +returns 0 on success and \-1 if an error occurs. +.Pp +The +.Fn mpool_close +function frees up any allocated memory associated with the memory pool +cookie. +Modified pages are +.Em not +written to the backing file. +.Fn mpool_close +returns 0 on success and \-1 if an error occurs. +.Sh ERRORS +The +.Fn mpool_open +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 . +.Pp +The +.Fn mpool_get +function may fail and set +.Va errno +for the following: +.Bl -tag -width Er -offset indent +.It Er EINVAL +The requested record doesn't exist. +.El +.Pp +The +.Fn mpool_new +and +.Fn mpool_get +functions may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr read 2 , +.Xr write 2 , +and +.Xr malloc 3 . +.Pp +The +.Fn mpool_sync +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr write 2 . +.Pp +The +.Fn mpool_close +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr free 3 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr hash 3 , +.Xr recno 3 diff --git a/static/netbsd/man3/mq.3 b/static/netbsd/man3/mq.3 new file mode 100644 index 00000000..a7c739ae --- /dev/null +++ b/static/netbsd/man3/mq.3 @@ -0,0 +1,354 @@ +.\" $NetBSD: mq.3,v 1.5 2011/02/26 12:56:35 wiz Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 28, 2010 +.Dt MQ 3 +.Os +.Sh NAME +.Nm mq , +.Nm mqueue +.Nd POSIX message queues (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Sh DESCRIPTION +The +.St -p1003.1-2001 +standard defines and +.Nx +implements an interprocess communication +.Pq Tn IPC +interface known as +.Tn POSIX +message queues. +Although the basic functionality is similar, +.Nm +is distinct from the older +.At V +message queues (see for example +.Xr ipcs 1 +or +.Xr msgget 2 ) . +.Ss Rationale +The rationale behind +.Nm +is to provide an efficient, priority-driven asynchronous +.Tn IPC +mechanism. +When the +.At V +message queues were first implemented, the reasoning was similar: +the only form of +.Tn IPC +was half-duplex pipes and message queues were +seen to overcome the performance limitations with these. +.Pp +But arguably in modern systems there is little difference between +the efficiency of the System V message queues, pipes, and +.Tn UNIX +domain sockets (if anything, the +.At V +message queues tend to be slower than the rest). +The fundamental performance bottleneck is however still there with +.Nm +as well: data must be first copied from the sender to the kernel +and then from the kernel to the receiver. +The bigger the message, the higher the overhead. +.Pp +For realtime applications, +.Nm +offers some advantages: +.Pp +.Bl -enum -offset 2n +.It +Unlike the predecessors, +.Nm +provides an asynchronous notification mechanism. +.It +Messages are prioritized. +The queue always remains sorted such that the +oldest message of the highest priority is always received first, +regardless of the number of messages in the queue. +.It +By default, the functions to send and receive messages are blocking calls. +It is however possible to use non-blocking variants with +.Nm . +Furthermore, it is possible to specify timeouts to avoid +non-deterministic blocking. +.It +Resource limits can be enforced \&-- or perhaps more importantly, +the availability of resources can be ensured as the internal +data structures are preallocated. +.El +.Ss Descriptors and Naming +Comparable to pipes and +.Tn FIFOs +.Pq a.k.a. named pipes , +all +.Tn POSIX +message queue operations are performed by using a descriptor. +The used type is +.Vt mqd_t , +an abbreviation from a +.Dq message queue descriptor . +In the +.Nx +implementation this is actually an ordinary file descriptor. +This means that it is possible, but not portable, to +monitor a message queue descriptor by using +.Xr poll 2 +or +.Xr select 2 . +.Pp +Message queues are named by character +strings that represent (absolute) pathnames. +The used interface is analogous to the conventional file concepts. +But unlike +.Tn FIFOs +and pipes, neither +.Tn POSIX +nor System V message queues are accessed by using +.Xr open 2 , +.Xr read 2 , +or +.Xr write 2 . +Instead, equivalents such as +.Fn mq_open , +.Fn mq_close , +and +.Fn mq_unlink +are used. +.Pp +The standard does not specify whether +.Tn POSIX +message queues are exposed at the file system level. +It can be argued that +.Nm +inherited an old problem with the System V message queues. +Even if an implementation would have support for it, +it is not portable to view message queues by +.Xr ls 1 , +remove these with +.Xr rm 1 , +or adjust the permissions with +.Xr chmod 1 . +.Ss Processes +When a new process is created or the program is terminated, +message queues behave like files. +More specifically, when +.Xr fork 2 +is called, files and message queues are inherited, and when the +program terminates by calling +.Xr exit 3 +or +.Xr _exit 2 , +both file descriptors and message queues are closed. +However, the +.Xr exec 3 +family of functions behave somewhat differently for +message queues and files: all message queues are +closed when a process calls one of the +.Fn exec +functions. +In this respect +.Tn POSIX +message queues are closer to +.Tn FIFOs +than normal pipes. +.Ss Attributes +All message queues have an attribute associated with them. +This is represented by the +.Va mq_attr +structure: +.Bd -literal -offset indent +struct mq_attr { + long mq_flags; + long mq_maxmsg; + long mq_msgsize; + long mq_curmsgs; +}; +.Ed +.Pp +The members in the structure are: +flags set for the message queue +.Pq Va mq_flags , +the maximum number of messages in the queue +.Pq Va mq_maxmsg , +the maximum size of each message +.Pq Va mq_msgsize , +and the number of queued messages +.Pq Va mq_curmsgs . +.Pp +The overall resource requirements for a particular message queue are given by +.Va mq_maxmsg +and +.Va mq_msgsize . +These two can be specified when the queue is created by a call to +.Fn mq_open . +The constraints are enforced through the lifetime of the queue: +an error is returned if a message larger than +.Va mq_msgsize +is sent, and if the message queue is already full, as determined by +.Va mq_maxmsg , +the call to queue a message will either block or error out. +.Pp +Although there are two functions, +.Fn mq_getattr +and +.Fn mq_setattr , +to retrieve and set attributes, +resource limits cannot be changed once the queue has been created. +In +.Nx +the super user may however control the global resource limits by using few +.Xr sysctl 7 +variables. +.Ss Asynchronous Notification +Instead of blocking in the functions that receive messages, +.Nm +offers an asynchronous mechanism for a process to receive +notifications that messages are available in the message queue. +The function +.Fn mq_notify +is used to register for notification. +Either a signal or a thread can be used as the type of notification; see +.Xr sigevent 3 +for details. +.Pp +Bear in mind that no notification is sent for an arrival +of a message to a non-empty message queue. +In other words, +.Fn mq_notify +does not by itself ensure that a process +will be notified every time a message arrives. +Thus, after having called +.Fn mq_notify , +an application may need to repeatedly call +.Fn mq_receive +until the queue is empty. +This requires that the message queue was created with the +.Dv O_NONBLOCK +flag; otherwise +.Fn mq_receive +blocks until a message is again queued +or the call is interrupted by a signal. +This may be a limitation for some realtime applications. +.Ss Priorities +Each message has a priority, ranging from 0 to the implementation-defined +.Dv MQ_PRIO_MAX . +The +.Tn POSIX +standard enforces the minimum value of the maximum priority to be 32. +All messages are inserted into a message +queue according to the specified priority. +High priority messages are sent before low priority messages. +If the used priority is constant, +.Nm +follows the +.Tn FIFO +.Pq First In, First Out +principle. +.Pp +The basic rule of thumb with realtime prioritization is that low priority +tasks should never unnecessarily delay high priority tasks. +Priority inheritance is not however part of the provided +.Tn API ; +the receiver process may run at low priority even +when receiving high priority messages. +To address this limitation and other potential realtime problems, +the user may consider other functions from the +.Lb librt . +The process scheduling interface described in +.Xr sched 3 +can be mentioned as an example. +.Sh FUNCTIONS +The following functions are available in the +.Tn API . +.Bl -column -offset indent "mq_timedreceive " "XXX" +.It Sy Function Ta Sy Description +.It Xr mq_open 3 Ta open a message queue +.It Xr mq_close 3 Ta close a message queue +.It Xr mq_unlink 3 Ta remove a message queue +.It Xr mq_send 3 Ta send a message +.It Xr mq_receive 3 Ta receive a message +.It Xr mq_timedsend 3 Ta send a message with a timeout +.It Xr mq_timedreceive 3 Ta receive a message with a timeout +.It Xr mq_getattr 3 Ta get message queue attributes +.It Xr mq_setattr 3 Ta set message queue attributes +.It Xr mq_notify 3 Ta register asynchronous notify +.El +.Sh COMPATIBILITY +Despite of some early fears, the +.Tn POSIX +message queue implementations are fairly compatible with each other. +Nevertheless, few points can be noted for portable applications. +.Bl -bullet +.It +It is not portable to use functions external to the +.Tn API +with message queue descriptors. +.It +The standard leaves the rules loose with +respect to the message queue names. +Only the interpretation of the first slash character is consistent; +the following slash characters may or may not follow the conventional +construction rules for a pathname. +.It +The length limits for a message queue name are implementation-defined. +These may or may not follow the conventional pathname limits +.Dv PATH_MAX +and +.Dv NAME_MAX . +.El +.Sh SEE ALSO +.Rs +.%A Bill O. Gallmeister +.%T POSIX.4: Programming for the Real World +.%I O'Reilly and Associates +.%D 1995 +.Re +.Rs +.%A Richard W. Stevens +.%T UNIX Network Programming, Volume 2: Interprocess Communications +.%V Second Edition +.%I Prentice Hall +.%D 1998 +.Re +.Sh STANDARDS +The +.Tn POSIX +message queue implementation is expected to conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Tn POSIX +message queue +.Tn API +first appeared in +.Nx 5.0 . +.Sh CAVEATS +User should be careful to unlink message queues at the program termination. +Otherwise it is possible to leave them lying around. diff --git a/static/netbsd/man3/mq_close.3 b/static/netbsd/man3/mq_close.3 new file mode 100644 index 00000000..f3c94af3 --- /dev/null +++ b/static/netbsd/man3/mq_close.3 @@ -0,0 +1,65 @@ +.\" $NetBSD: mq_close.3,v 1.3 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_CLOSE 3 +.Os +.Sh NAME +.Nm mq_close +.Nd close a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_close "mqd_t mqdes" +.Sh DESCRIPTION +The +.Fn mq_close +function will remove the association between the message queue descriptor, +.Fa mqdes , +and its message queue. +.Pp +If the process has successfully attached a notification request to +the message queue via this +.Fa mqdes , +this attachment will be removed, and the message queue is available +for another process to attach for notification. +.Sh RETURN VALUES +.Rv -std mq_close +.Sh ERRORS +The +.Fn mq_close +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_open 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_close +function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_getattr.3 b/static/netbsd/man3/mq_getattr.3 new file mode 100644 index 00000000..30c712b5 --- /dev/null +++ b/static/netbsd/man3/mq_getattr.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: mq_getattr.3,v 1.3 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_GETATTR 3 +.Os +.Sh NAME +.Nm mq_getattr +.Nd get message queue attributes (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat" +.Sh DESCRIPTION +The +.Fn mq_getattr +function will obtain status information and attributes of the +message queue and the open message queue description associated +with the message queue descriptor. +.Pp +The +.Fa mqdes +argument specifies a message queue descriptor. +.Pp +The results are returned in the +.Vt mq_attr +structure referenced by the +.Va mqstat +argument. +.Pp +Upon return, the following members have the values associated with +the open message queue description as set when the message queue was +opened and as modified by subsequent +.Xr mq_setattr 3 +calls: +.Va mq_flags . +.Pp +The following attributes of the message queue will be returned as set +at message queue creation: +.Va mq_maxmsg , +.Va mq_msgsize . +.Pp +Upon return, the following members within the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument will be set to the current state of the message queue: +.Bl -tag -width mq_curmsgs +.It Va mq_curmsgs +The number of messages currently on the queue. +.El +.Sh RETURN VALUES +.Rv -std mq_getattr +.Sh ERRORS +The +.Fn mq_getattr +function may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The mqdes argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_setattr 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_notify.3 b/static/netbsd/man3/mq_notify.3 new file mode 100644 index 00000000..5a07ea9f --- /dev/null +++ b/static/netbsd/man3/mq_notify.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: mq_notify.3,v 1.3 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_NOTIFY 3 +.Os +.Sh NAME +.Nm mq_notify +.Nd notify process that a message is available (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" +.Sh DESCRIPTION +If the argument +.Fa notification +is not +.Dv NULL , +this function will register the calling process to be notified of +message arrival at an empty message queue associated with the +specified message queue descriptor, +.Fa mqdes . +The notification specified by the +.Fa notification +argument will be sent to the process when the message queue +transitions from empty to non-empty. +At any time, only one process may be registered for notification +by a message queue. +If the calling process or any other process has already registered +for notification of message arrival at the specified message queue, +subsequent attempts to register for that message queue fails. +.Pp +If +.Fa notification +is +.Dv NULL +and the process is currently registered for notification by the +specified message queue, the existing registration will be removed. +.Pp +When the notification is sent to the registered process, +its registration will be removed. +The message queue will then be available for registration. +.Pp +If a process has registered for notification of message arrival +at a message queue and some thread is blocked in +.Fn mq_receive +waiting to receive a message when a message arrives at the queue, +the arriving message will satisfy the appropriate +.Fn mq_receive . +The resulting behavior is as if the message queue remains empty, +and no notification will be sent. +.Sh RETURN VALUES +.Rv -std mq_notify +.Sh ERRORS +The +.Fn mq_notify +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.It Bq Er EBUSY +A process is already registered for notification by the message queue. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr sigevent 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_open.3 b/static/netbsd/man3/mq_open.3 new file mode 100644 index 00000000..fe23dbc8 --- /dev/null +++ b/static/netbsd/man3/mq_open.3 @@ -0,0 +1,273 @@ +.\" $NetBSD: mq_open.3,v 1.6 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_OPEN 3 +.Os +.Sh NAME +.Nm mq_open +.Nd open a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" "mode_t mode" "struct mq_attr *attr" +.Sh DESCRIPTION +The +.Fn mq_open +function establishes the connection between a process and a message queue +with a message queue descriptor. +It creates an open message queue description that refers to the message +queue, and a message queue descriptor that refers to that open message +queue description. +The message queue descriptor is used by other functions to refer to that +message queue. +The +.Fa name +argument points to a string naming a message queue, +which should conform to the construction rules for a pathname. +The +.Fa name +should begin with a slash character. +The processes calling +.Fn mq_open +with the same value of +.Fa name +will refer to the same message queue object, +as long as that name has not been removed. +If the +.Fa name +argument is not +the name of an existing message queue and creation is not requested, +.Fn mq_open +fails and returns an error. +.Pp +The +.Fa oflag +argument requests the desired receive and/or send access to the message queue. +The requested access permission to receive messages or send messages are +granted if the calling process would be granted read or write access, +respectively, to an equivalently protected file. +.Pp +The value of +.Fa oflag +is the bitwise-inclusive OR of values from the following list. +Applications must specify exactly one of the first three values +(access modes) below in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_RDONLY" +.It Dv O_RDONLY +Open the message queue for receiving messages. +The process can use the returned message queue descriptor with +.Xr mq_receive 3 , +but not +.Xr mq_send 3 . +.It Dv O_WRONLY +Open the queue for sending messages. +The process can use the returned message queue descriptor with +.Xr mq_send 3 +but not +.Xr mq_receive 3 . +.It Dv O_RDWR +Open the queue for both receiving and sending messages. +The process can use any of the functions allowed for +.Dv O_RDONLY +and +.Dv O_WRONLY . +.El +.Pp +In all cases, a message queue may be open multiple times in the same +or different processes for sending/receiving messages. +.Pp +Any combination of the remaining flags may be specified in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_CREAT +Create a message queue. +It requires two additional arguments: +.Fa mode +and +.Fa attr . +If the pathname +.Fa name +has already been used to create a message queue that still exists, +then this flag will have no effect, except as noted under +.Dv O_EXCL . +Otherwise, a message queue will be created without any messages in it. +The user ID of the message queue will be set to the effective user ID +of the process, and the group ID of the message queue will be set to +the effective group ID of the process. +The permission bits of the message queue will be set to the value of the +.Fa mode +argument, except those set in the file mode creation mask of +the process. +When bits in +.Fa mode +other than the file permission bits are specified, the effect +is unspecified. +If +.Fa attr +is +.Dv NULL , +the message queue will be created with implementation-defined default +message queue attributes. +If +.Fa attr +is +.No non- Ns Dv NULL +and the calling process has the appropriate privilege on +.Fa name , +the message queue +.Va mq_maxmsg +and +.Va mq_msgsize +attributes will be set to the values of the corresponding members in the +.Vt mq_attr +structure referred to by +.Fa attr . +If +.Fa attr +is +.No non- Ns Dv NULL , +but the calling process does not have the +appropriate privilege on +.Fa name , +the +.Fn mq_open +function will fail and return an error without creating the message queue. +.It Dv O_EXCL +If +.Dv O_EXCL +and +.Dv O_CREAT +are set, +.Fn mq_open +fails if the message queue +.Fa name +exists. +The check for the existence of the message queue and the creation of the +message queue if it does not exist will be atomic with respect to other +threads executing +.Fn mq_open +naming the same +.Fa name +with +.Dv O_EXCL +and +.Dv O_CREAT +set. +If +.Dv O_EXCL +is set and +.Dv O_CREAT +is not set, the result is undefined. +.It Dv O_NONBLOCK +Determines whether an +.Xr mq_send 3 +or +.Xr mq_receive 3 +waits for resources or messages that are not currently available, +or fails with errno set to +.Er EAGAIN . +.El +.Pp +The +.Fn mq_open +function does not add or remove messages from the queue. +.Sh IMPLEMENTATION NOTES +The +.Xr select 2 +and +.Xr poll 2 +system calls to the message queue descriptor are supported by +.Nx , +however, it is not portable. +.Sh RETURN VALUES +Upon successful completion, +.Fn mq_open +returns a message queue descriptor. +Otherwise, the function returns +.Pq Dv mqd_t +\-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_open +function fails if: +.Bl -tag -width Er +.It Bq Er EACCES +The message queue exists and the permissions specified by +.Fa oflag +are denied, or the message queue does not exist and permission +to create the message queue is denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are set and the named message queue already exists. +.It Bq Er EINTR +The +.Fn mq_open +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fn mq_open +function is not supported for the given name, or +.Dv O_CREAT +was specified in +.Fa oflag , +the value of +.Fa attr +is not +.Dv NULL , +and either +.Va mq_maxmsg +or +.Va mq_msgsize +was less than or equal to zero. +.It Bq Er EMFILE +Too many message queue descriptors or file descriptors are currently +in use by this process. +.It Bq Er ENAMETOOLONG +The length of the +.Fa name +argument exceeds +.Brq Dv PATH_MAX +or a pathname component is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENFILE +Too many message queues are currently open in the system. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named message queue does not exist. +.It Bq Er ENOSPC +There is insufficient space for the creation of the new message queue. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_close 3 , +.Xr mq_unlink 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_receive.3 b/static/netbsd/man3/mq_receive.3 new file mode 100644 index 00000000..7e799f89 --- /dev/null +++ b/static/netbsd/man3/mq_receive.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: mq_receive.3,v 1.6 2015/11/19 07:03:13 wiz Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd November 18, 2015 +.Dt MQ_RECEIVE 3 +.Os +.Sh NAME +.Nm mq_receive, mq_timedreceive +.Nd receive a message from a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft ssize_t +.Fo mq_receive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fc +.In mqueue.h +.In time.h +.Ft ssize_t +.Fo mq_timedreceive +.Fa "mqd_t mqdes" +.Fa "char *restrict msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *restrict msg_prio" +.Fa "const struct timespec *restrict abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_receive +function receives the oldest of the highest priority message(s) +from the message queue specified by +.Fa mqdes . +If the size of the buffer in bytes, specified by the +.Fa msg_len +argument, is less than the +.Va mq_msgsize +attribute of the message queue, the function fails and returns an error. +Otherwise, the selected message will be removed from the queue and copied +to the buffer pointed to by the +.Fa msg_ptr +argument. +.Pp +If the argument +.Fa msg_prio +is not +.Dv NULL , +the priority of the selected message will be stored in the location +referenced by +.Fa msg_prio . +.Pp +If the specified message queue is empty and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_receive +blocks until a message is enqueued on the message queue or until +.Fn mq_receive +is interrupted by a signal. +If more than one thread is waiting to receive a message when a +message arrives at an empty queue, then the thread of highest +priority that has been waiting the longest will be selected to +receive the message. +If the specified message queue is empty and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +no message will be removed from the queue, and +.Fn mq_receive +returns an error. +.Pp +The timeout expires when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The resolution of the timeout is based on the CLOCK_REALTIME clock. +The +.Fa timespec +argument is defined in the +.In time.h +header. +.Pp +Under no circumstance will the operation fail with a timeout if a +message can be removed from the message queue immediately. +The validity of the +.Fa abs_timeout +parameter will not be checked if a message can be removed from the +message queue immediately. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_receive +and +.Fn mq_timedreceive +functions return the length of the selected message in bytes, and the +message is removed from the queue. +Otherwise, no message will be removed from the queue, +the functions return a value of +\-1, and set the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_receive +and +.Fn mq_timedreceive +functions fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +.Dv O_NONBLOCK +was set in the message description associated with +.Fa mqdes , +and the specified message queue is empty. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for reading. +.It Bq Er EINTR +The +.Fn mq_receive +or +.Fn mq_timedreceive +operation was interrupted by a signal. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message buffer size, +.Fa msg_len , +is less than the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, +but no message arrived on the queue before the specified timeout expired. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_send 3 +.Sh STANDARDS +These functions are expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_receive +and +.Fn mq_timedreceive +functions first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_send.3 b/static/netbsd/man3/mq_send.3 new file mode 100644 index 00000000..c9c026c6 --- /dev/null +++ b/static/netbsd/man3/mq_send.3 @@ -0,0 +1,202 @@ +.\" $NetBSD: mq_send.3,v 1.4 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_SEND 3 +.Os +.Sh NAME +.Nm mq_send , mq_timedsend +.Nd send a message to a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_send +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fc +.In mqueue.h +.In time.h +.Ft int +.Fo mq_timedsend +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_send +function will add the message pointed to by the argument +.Fa msg_ptr +to the message queue specified by +.Fa mqdes . +The +.Fa msg_len +argument specifies the length of the message, in bytes, pointed to by +.Fa msg_ptr . +The value of +.Fa msg_len +will be less than or equal to the +.Fa mq_msgsize +attribute of the message queue, or +.Fn mq_send +will fail. +.Pp +If the specified message queue is not full, +.Fn mq_send +behaves as if the message is inserted into the message queue at the +position indicated by the +.Fa msg_prio +argument. +A message with a larger numeric value of +.Fa msg_prio +will be inserted before messages with lower values of +.Fa msg_prio . +A message will be inserted after other messages in the queue, +if any, with equal +.Fa msg_prio . +The value of +.Fa msg_prio +will be less than +.Brq Dv MQ_PRIO_MAX . +.Pp +If the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_send +blocks until space becomes available to enqueue the message, or until +.Fn mq_send +is interrupted by a signal. +If more than one thread is waiting to send when space becomes available +in the message queue, then the thread of the highest priority that has +been waiting the longest will be unblocked to send its message. +If the specified message queue is full and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +the message will not be queued and +.Fn mq_send +will return an error. +.Pp +The +.Fn mq_timedsend +function will add a message to the message queue specified by +.Fa mqdes +in the manner defined for the +.Fn mq_send +function. +However, if the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +the wait for sufficient room in the queue will be terminated +when the specified timeout expires. +If +.Dv O_NONBLOCK +is set in the message queue description, this function will be equivalent to +.Fn mq_send . +.Pp +The timeout will expire when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The resolution of the timeout is based on the CLOCK_REALTIME clock. +The +.Fa timespec +argument is defined in the +.In time.h +header. +.Pp +Under no circumstance will the operation fail with a timeout if there is +sufficient room in the queue to add the message immediately. +The validity of the +.Fa abs_timeout +parameter need not be checked when there is sufficient room in the queue. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_send +and +.Fn mq_timedsend +functions return a value of zero. +Otherwise, no message will be enqueued, +the functions will return \-1, and the global variable +.Va errno +will be set to indicate the error. +.Sh ERRORS +The +.Fn mq_send +and +.Fn mq_timedsend +functions fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is full. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for writing. +.It Bq Er EINTR +A signal interrupted the call to +.Fn mq_send +or +.Fn mq_timedsend . +.It Bq Er EINVAL +The value of +.Fa msg_prio +was outside the valid range, or +the process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message length, +.Fa msg_len , +exceeds the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, +but the timeout expired before the message could be added to the queue. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_receive 3 +.Sh STANDARDS +These functions are expected to conform to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_send +and +.Fn mq_timedsend +functions first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_setattr.3 b/static/netbsd/man3/mq_setattr.3 new file mode 100644 index 00000000..ab877870 --- /dev/null +++ b/static/netbsd/man3/mq_setattr.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: mq_setattr.3,v 1.3 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2010 +.Dt MQ_SETATTR 3 +.Os +.Sh NAME +.Nm mq_setattr +.Nd set message queue attributes (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_setattr +.Fa "mqd_t mqdes" +.Fa "const struct mq_attr *restrict mqstat" +.Fa "struct mq_attr *restrict omqstat" +.Fc +.Sh DESCRIPTION +The +.Fn mq_setattr +function sets attributes associated with the open message queue +description referenced by the message queue descriptor specified by +.Fa mqdes . +.Pp +The message queue attributes corresponding to the following members +defined in the +.Vt mq_attr +structure will be set to the specified values upon successful completion of +.Fn mq_setattr : +.Bl -tag -width mq_flags +.It Va mq_flags +The value of this member is the bitwise-logical OR of zero or more of +.Dv O_NONBLOCK +and any implementation-defined flags. +.El +.Pp +The values of the +.Va mq_maxmsg , +.Va mq_msgsize , +and +.Va mq_curmsgs +members of the +.Vt mq_attr +structure will be ignored by +.Fn mq_setattr . +.Pp +If +.Fa omqstat +is +.No non- Ns Dv NULL , +the +.Fn mq_setattr +function will store, in the location referenced by +.Fa omqstat +the previous message queue attributes and the current queue status. +These values are the same as would be returned by a call to +.Xr mq_getattr 3 +at that point. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_setattr +function returns zero and the attributes of the message queue will +have been changed as specified. +Otherwise, the message queue attributes are unchanged, +and the function returns a value of +\-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_setattr +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_getattr 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +This function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mq_unlink.3 b/static/netbsd/man3/mq_unlink.3 new file mode 100644 index 00000000..8615e366 --- /dev/null +++ b/static/netbsd/man3/mq_unlink.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: mq_unlink.3,v 1.4 2012/03/15 19:04:47 njoly Exp $ +.\" +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.\" +.Dd June 7, 2009 +.Dt MQ_UNLINK 3 +.Os +.Sh NAME +.Nm mq_unlink +.Nd remove a message queue (REALTIME) +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn mq_unlink +function removes the message queue named by the pathname +.Fa name . +After a successful call to +.Fn mq_unlink +with +.Fa name , +a call to +.Xr mq_open 3 +with +.Fa name +fails if the flag +.Dv O_CREAT +is not set in +.Fa flags . +If one or more processes have the message queue open when +.Fn mq_unlink +is called, destruction of the message queue will be postponed until +all references to the message queue have been closed. +.Pp +Calls to +.Xr mq_open 3 +to recreate the message queue may fail until the message queue is +actually removed. +However, the +.Fn mq_unlink +call need not block until all references have been closed; +it may return immediately. +.Sh RETURN VALUES +Upon successful completion, the function returns a value of zero. +Otherwise, the named message queue will be unchanged by this function call, +and the function returns a value of \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_unlink +function fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission is denied to unlink the named message queue. +.It Bq Er ENAMETOOLONG +The length of the name argument exceeds +.Brq Dv PATH_MAX +or a pathname +component is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENOENT +The named message queue does not exist. +.El +.Sh SEE ALSO +.Xr mq 3 , +.Xr mq_open 3 +.Sh STANDARDS +This function conforms to the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The +.Fn mq_unlink +function first appeared in +.Nx 5.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. +The original Standard can be obtained online at +.Lk http://www.opengroup.org/unix/online.html . diff --git a/static/netbsd/man3/mtx.3 b/static/netbsd/man3/mtx.3 new file mode 100644 index 00000000..907c526c --- /dev/null +++ b/static/netbsd/man3/mtx.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: mtx.3,v 1.3 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt MTX 3 +.Os +.Sh NAME +.Nm mtx +.Nd mutex functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Ft void +.Fn mtx_destroy "mtx_t *mtx" +.Ft int +.Fn mtx_init "mtx_t *mtx" "int type" +.Ft int +.Fn mtx_lock "mtx_t *mtx" +.Ft int +.Fn mtx_timedlock "mtx_t * restrict mtx" "const struct timespec * restrict ts" +.Ft int +.Fn mtx_trylock "mtx_t *mtx" +.Ft int +.Fn mtx_unlock "mtx_t *mtx" +.Sh DESCRIPTION +The +.Fn mtx_destroy +function releases the resources of +.Fa mtx . +It is not allowed to block the same +.Fa mtx +during the +.Fn mtx_destroy +call. +.Pp +The +.Fn mtx_init +function initialized the +.Fa mtx +object uniquely identificable with the +.Fa type +properties. +The allowed values of +.Fa type +are as follows: +.Bl -column "mtx_plain | mtx_recursive" +.It Sy "Type" Ta Sy "Description" +.It Dv mtx_plain Ta basic mutex +.It Dv mtx_timed Ta mutex with timeout support +.It Dv mtx_plain | Dv mtx_recursive Ta basic recursive mutex +.It Dv mtx_timed | Dv mtx_recursive Ta recursive mutex with timeout support +.El +.Pp +The underlying +.Nx +implementation of mutex types does not distinguish between +.Dv mtx_plain +and +.Dv mtx_timed , +however portable code must keep the distinction. +.Pp +The +.Fn mtx_lock +function locks the +.Fa mtx +object. +It is required to never lock the same +.Fa mtx +object without the +.Dv mtx_recursive +property multiple times. +If the +.Fa mtx +object is already locked by another thread, +the caller of +.Fa mtx_lock +blocks until the lock becomes available. +.Pp +The +.Fn mtx_timedlock +function tries to lock the +.Fa mtx +object. +In case of blocked resource by another thread, +this call blocks for the specified timeout in the +.Fa ts +argument. +The timeout argument is +.Dv TIME_UTC +based time of +.Dv timespec +type. +It is required to never lock the same +.Fa mtx +object without the +.Dv mtx_recursive +property multiple times. +In portable code, a +.Fa mtx +object with the +.Dv mtx_recursive +property must be used in such a case. +.Pp +The +.Fn mtx_trylock +function call attempts to lock the +.Fa mtx +object. +This function does not block if another thread already locked the +.Fa mtx +object, but immediately returns indicating proper status. +.Pp +The +.Fn mtx_unlock +function unlocks the +.Fa mtx +object. +This call must be preceded with a matching +.Fn mtx_lock +call in the same thread. +.Sh RETURN VALUES +The +.Fn mtx_destroy +function returns no value. +.Pp +The +.Fn mtx_init +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn mtx_lock +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn mtx_lock +function returns +.Dv thrd_success +on success, +otherwise +.Dv thrd_timedout +to indicate that system time has reached or exceeded the time specified in +.Dv ts , +or +.Dv thrd_error +on failure. +.Pp +The +.Fn mtx_trylock +function returns +.Dv thrd_success +on success, +otherwise +.Dv thrd_timedout +to indicate that +.Fa mtx +object is already locked, or +.Dv thrd_error +on failure. +.Pp +The +.Fn mtx_unlock +function returns +.Dv thrd_success +on success, +otherwise +.Dv thrd_timedout +to indicate that +.Fa mtx +object is already locked, or +.Dv thrd_error +on failure. +.Sh SEE ALSO +.Xr pthread_mutex 3 , +.Xr threads 3 +.Sh STANDARDS +The +.Nm +interface conforms to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/nan.3 b/static/netbsd/man3/nan.3 new file mode 100644 index 00000000..1fdb9c54 --- /dev/null +++ b/static/netbsd/man3/nan.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: nan.3,v 1.5 2016/08/27 02:56:26 dholland Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 15, 2006 +.Dt NAN 3 +.Os +.Sh NAME +.Nm nan , +.Nm nanf , +.Nm nanl +.Nd return quiet NaN +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn nan "const char *tagp" +.Ft float +.Fn nanf "const char *tagp" +.Ft long double +.Fn nanl "const char *tagp" +.Sh DESCRIPTION +The call +.Fn nan "\*qn-char-sequence\*q" +is equivalent to the call +.Fn strtod "\*qNAN(n-char-sequence)\*q" "NULL" . +The call +.Fn nan "\*q\*q" +is equivalent to the call +.Fn strtod "\*qNAN()\*q" "NULL" . +.Pp +The +.Fn nanf +and +.Fn nanl +functions are equivalent to +.Fn nan +but substituting +.Fn strtof +and +.Fn strtold , +respectively. +.Sh RETURN VALUES +.Ss IEEE 754 +The +.Fn nan , +.Fn nanf , +and +.Fn nanl +functions return a quiet NaN as specified by +.Fa tagp . +.Ss VAX +The +.Fn nan , +.Fn nanf , +and +.Fn nanl +functions return zero. +.Sh SEE ALSO +.Xr math 3 , +.Xr strtod 3 +.Sh STANDARDS +The +.Fn nan , +.Fn nanf , +and +.Fn nanl +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/new_panel.3 b/static/netbsd/man3/new_panel.3 new file mode 100644 index 00000000..8c6934c9 --- /dev/null +++ b/static/netbsd/man3/new_panel.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: new_panel.3,v 1.4 2015/10/29 02:33:46 uwe Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt NEW_PANEL 3 +.Os +.Sh NAME +.Nm new_panel , +.Nm panel_window , +.Nm replace_panel , +.Nm del_panel +.Nd panel routines +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft PANEL * +.Fn new_panel "WINDOW *win" +.\" +.Ft WINDOW * +.Fn panel_window "PANEL *p" +.\" +.Ft int +.Fn replace_panel "PANEL *p" "WINDOW *win" +.\" +.Ft int +.Fn del_panel "PANEL *p" +.\" +.Sh DESCRIPTION +The function +.Fn new_panel +creates a new panel associated with the curses window +.Fa win . +The new panel is visible and is placed at the top of the deck. +.Pp +The curses window associated with a panel may be obtained with +.Fn panel_window +and changed with +.Fn replace_panel . +.Pp +The function +.Fn del_panel +hides the panel and deletes it. +Note that the curses window associated with the panel is not deleted. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ".Dv ERR" -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr panel 3 diff --git a/static/netbsd/man3/newlocale.3 b/static/netbsd/man3/newlocale.3 new file mode 100644 index 00000000..394b3e9d --- /dev/null +++ b/static/netbsd/man3/newlocale.3 @@ -0,0 +1,126 @@ +.\" $NetBSD: newlocale.3,v 1.3 2021/02/15 15:38:43 wiz Exp $ +.\" Copyright (c) 2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by David Chisnall under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/locale/newlocale.3 366375 2020-10-02 18:35:55Z markj $ +.Dd February 15, 2021 +.Dt NEWLOCALE 3 +.Os +.Sh NAME +.Nm newlocale +.Nd Creates a new locale +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In locale.h +.Ft locale_t +.Fn newlocale "int mask" "const char * locale" "locale_t base" +.Sh DESCRIPTION +Creates a new locale, inheriting some properties from an existing locale. +The +.Fa mask +defines the components that the new locale will have set to the locale with the +name specified in the +.Fa locale +parameter. +Any components not specified in +.Fa mask +will be inherited from the locale referenced by +.Fa base , +if +.Fa base +is not +.Dv NULL . +If the call is successful, the state of the locale referenced by +.Fa base +is unspecified, and it must not be accessed. +The special locale +.Dv LC_GLOBAL_LOCALE +may not be specified for +.Fa base . +The +.Fa mask +is either +.Fa LC_ALL_MASK , +indicating all possible locale components, +or the logical OR of some combination of the following: +.Bl -tag -width "LC_MESSAGES_MASK" -offset indent +.It LC_COLLATE_MASK +The locale for string collation routines. +This controls alphabetic ordering in +.Xr strcoll 3 +and +.Xr strxfrm 3 . +.It LC_CTYPE_MASK +The locale for the +.Xr ctype 3 +.\" and +.\" .Xr multibyte 3 +functions. +This controls recognition of upper and lower case, alphabetic or +non-alphabetic characters, and so on. +.It LC_MESSAGES_MASK +Set a locale for message catalogs, see +.Xr catopen 3 +function. +.It LC_MONETARY_MASK +Set a locale for formatting monetary values; this affects +the +.Xr localeconv 3 +function. +.It LC_NUMERIC_MASK +Set a locale for formatting numbers. +This controls the formatting of decimal points in input and output of floating +point numbers in functions such as +.Xr printf 3 +and +.Xr scanf 3 , +as well as values returned by +.Xr localeconv 3 . +.It LC_TIME_MASK +Set a locale for formatting dates and times using the +.Xr strftime 3 +function. +.El +This function uses the same rules for loading locale components as +.Xr setlocale 3 . +.Sh RETURN VALUES +Returns a new, valid, +.Fa locale_t +or NULL if an error occurs. +You must free the returned locale with +.Xr freelocale 3 . +.Sh SEE ALSO +.Xr duplocale 3 , +.Xr freelocale 3 , +.Xr localeconv 3 +.\" .Xr querylocale 3 , +.\" .Xr uselocale 3 , +.\" .Xr xlocale 3 +.Sh STANDARDS +This function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/nextafter.3 b/static/netbsd/man3/nextafter.3 new file mode 100644 index 00000000..f377ebbe --- /dev/null +++ b/static/netbsd/man3/nextafter.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: nextafter.3,v 1.8 2019/05/02 15:08:35 mgorny Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 13, 2015 +.Dt NEXTAFTER 3 +.Os +.Sh NAME +.Nm nextafter , +.Nm nextafterf , +.Nm nextafterl , +.Nm nexttoward , +.Nm nexttowardf , +.Nm nexttowardl +.Nd next representable floating-point number +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn nextafter "double x" "double y" +.Ft float +.Fn nextafterf "float x" "float y" +.Ft long double +.Fn nextafterl "long double x" "long double y" +.Ft double +.Fn nexttoward "double x" "long double y" +.Ft float +.Fn nexttowardf "float x" "long double y" +.Ft long double +.Fn nexttowardl "long double x" "long double y" +.Sh DESCRIPTION +The +.Fn nextafter , +.Fn nextafterf , +and +.Fn nextafterl +functions return the next machine representable number from +.Fa x +in direction of +.Fa y . +In other words, if +.Fa y +is less than +.Fa x , +the functions return the largest representable floating-point number less than +.Fa x . +When +.Fa x +equals +.Fa y , +the value of +.Fa y +is returned. +The three functions differ only in the type of the return value and +.Fa x . +.Pp +The +.Fn nexttoward +and +.Fn nexttowardf +functions are equivalent to the +.Fn nextafter +family of functions with two exceptions: +.Bl -enum -offset indent +.It +The second parameter has a type +.Vt long double . +.It +The return value is +.Fa y +converted to the type of the function, provided that +.Fa x +equals +.Fa y . +.El +.Pp +.Fn nexttowardl +is equivalent to +.Fn nextafterl . +.Sh RETURN VALUES +Upon successful completion, the described functions return +the next representable floating-point value as described above. +If +.Fa x +is finite but an overflow would occur, +a range error follows and the functions return +.Dv \*(PmHUGE_VAL , +.Dv \*(PmHUGE_VALF , +or +.Dv \*(PmHUGE_VALL +with the same sign as +.Fa x . +When either +.Fa x +or +.Fa y +is \*(Na, a \*(Na is returned. +When +.Fa x +is not +.Fa y +but the function value is subnormal, zero, or underflows, +a range error occurs, and either 0.0 or the correct function +value (if representable) is returned. +.Sh SEE ALSO +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/ngettext.3 b/static/netbsd/man3/ngettext.3 new file mode 100644 index 00000000..5e74e5dd --- /dev/null +++ b/static/netbsd/man3/ngettext.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" This is free documentation; 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 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" GNU gettext source code and manual +.\" LI18NUX 2000 Globalization Specification +.\" +.TH NGETTEXT 3 "May 2001" "GNU gettext 0.16.1" +.SH NAME +ngettext, dngettext, dcngettext \- translate message and choose plural form +.SH SYNOPSIS +.nf +.B #include <libintl.h> +.sp +.BI "char * ngettext (const char * " msgid ", const char * " msgid_plural , +.BI " unsigned long int " n ); +.BI "char * dngettext (const char * " domainname , +.BI " const char * " msgid ", const char * " msgid_plural , +.BI " unsigned long int " n ); +.BI "char * dcngettext (const char * " domainname , +.BI " const char * " msgid ", const char * " msgid_plural , +.BI " unsigned long int " n ", int " category ); +.fi +.SH DESCRIPTION +The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions attempt to +translate a text string into the user's native language, by looking up the +appropriate plural form of the translation in a message catalog. +.PP +Plural forms are grammatical variants depending on the a number. Some languages +have two forms, called singular and plural. Other languages have three forms, +called singular, dual and plural. There are also languages with four forms. +.PP +The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions work like +the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions, respectively. +Additionally, they choose the appropriate plural form, which depends on the +number \fIn\fP and the language of the message catalog where the translation +was found. +.PP +In the "C" locale, or if none of the used catalogs contain a translation for +\fImsgid\fP, the \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions +return \fImsgid\fP if \fIn\fP == 1, or \fImsgid_plural\fP if \fIn\fP != 1. +.SH "RETURN VALUE" +If a translation was found in one of the specified catalogs, the appropriate +plural form is converted to the locale's codeset and returned. The resulting +string is statically allocated and must not be modified or freed. Otherwise +\fImsgid\fP or \fImsgid_plural\fP is returned, as described above. +.SH ERRORS +\fBerrno\fP is not modified. +.SH BUGS +The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid +warnings in C code predating ANSI C. +.SH "SEE ALSO" +.BR gettext (3), +.BR dgettext (3), +.BR dcgettext (3) diff --git a/static/netbsd/man3/nice.3 b/static/netbsd/man3/nice.3 new file mode 100644 index 00000000..3aa293f4 --- /dev/null +++ b/static/netbsd/man3/nice.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: nice.3,v 1.14 2011/05/01 02:54:22 christos Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)nice.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 30, 2011 +.Dt NICE 3 +.Os +.Sh NAME +.Nm nice +.Nd set program scheduling priority +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn nice "int incr" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr setpriority 2 . +.Ef +.Pp +The +.Fn nice +function obtains the scheduling priority of the process +from the system and sets it to the priority value specified in +.Fa incr . +The priority is a value in the range -20 to 20. +The default priority is 0; lower priorities cause more favorable scheduling. +Only a process with appropriate privileges may lower priorities. +.Pp +Children inherit the priority of their parent processes via +.Xr fork 2 . +.Sh RETURN VALUES +Upon successful completion, +.Fn nice +returns the new nice value minus +.Dv NZERO . +Otherwise, \-1 is returned, the process' nice value is not changed, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn nice +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The +.Fa incr +argument is negative and the caller does not have appropriate privileges. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr fork 2 , +.Xr setpriority 2 , +.Xr renice 8 +.Sh STANDARDS +The +.Fn nice +function conforms to +.St -xpg4.2 . +.Sh HISTORY +A +.Fn nice +syscall appeared in +.At v6 . diff --git a/static/netbsd/man3/nl_langinfo.3 b/static/netbsd/man3/nl_langinfo.3 new file mode 100644 index 00000000..41326afc --- /dev/null +++ b/static/netbsd/man3/nl_langinfo.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: nl_langinfo.3,v 1.21 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Written by J.T. Conklin <jtc@NetBSD.org>. +.\" Public domain. +.\" +.Dd April 14, 2011 +.Dt NL_LANGINFO 3 +.Os +.Sh NAME +.Nm nl_langinfo +.Nd get locale information +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In langinfo.h +.Ft char * +.Fn nl_langinfo "nl_item item" +.Sh DESCRIPTION +The +.Fn nl_langinfo +function returns a pointer to a string containing information +set by the program's locale. +.Pp +The names and values of +.Fa item +are defined in +.In langinfo.h . +The entries under Category indicate in which +.Xr setlocale 3 +category each item is defined. +.Bl -column ERA_D_T_FMT LC_MESSAGES +.It Sy Constant Ta Sy Category Ta Sy Meaning +.It CODESET LC_CTYPE Codeset name +.It D_T_FMT LC_TIME String for formatting date and time +.It D_FMT LC_TIME Date format string +.It T_FMT LC_TIME Time format string +.It T_FMT_AMPM LC_TIME A.M. or P.M. time format string +.It AM_STR LC_TIME Ante-meridiem affix +.It PM_STR LC_TIME Post-meridiem affix +.It DAY_1 LC_TIME Name of the first day of the week (e.g.: Sunday) +.It DAY_2 LC_TIME Name of the second day of the week (e.g.: Monday) +.It DAY_3 LC_TIME Name of the third day of the week (e.g.: Tuesday) +.It DAY_4 LC_TIME Name of the fourth day of the week (e.g.: Wednesday) +.It DAY_5 LC_TIME Name of the fifth day of the week (e.g.: Thursday) +.It DAY_6 LC_TIME Name of the sixth day of the week (e.g.: Friday) +.It DAY_7 LC_TIME Name of the seventh day of the week (e.g.: Saturday) +.It ABDAY_1 LC_TIME Abbreviated name of the first day of the week +.It ABDAY_2 LC_TIME Abbreviated name of the second day of the week +.It ABDAY_3 LC_TIME Abbreviated name of the third day of the week +.It ABDAY_4 LC_TIME Abbreviated name of the fourth day of the week +.It ABDAY_5 LC_TIME Abbreviated name of the fifth day of the week +.It ABDAY_6 LC_TIME Abbreviated name of the sixth day of the week +.It ABDAY_7 LC_TIME Abbreviated name of the seventh day of the week +.It MON_1 LC_TIME Name of the first month of the year +.It MON_2 LC_TIME Name of the second month +.It MON_3 LC_TIME Name of the third month +.It MON_4 LC_TIME Name of the fourth month +.It MON_5 LC_TIME Name of the fifth month +.It MON_6 LC_TIME Name of the sixth month +.It MON_7 LC_TIME Name of the seventh month +.It MON_8 LC_TIME Name of the eighth month +.It MON_9 LC_TIME Name of the ninth month +.It MON_10 LC_TIME Name of the tenth month +.It MON_11 LC_TIME Name of the eleventh month +.It MON_12 LC_TIME Name of the twelfth month +.It ABMON_1 LC_TIME Abbreviated name of the first month +.It ABMON_2 LC_TIME Abbreviated name of the second month +.It ABMON_3 LC_TIME Abbreviated name of the third month +.It ABMON_4 LC_TIME Abbreviated name of the fourth month +.It ABMON_5 LC_TIME Abbreviated name of the fifth month +.It ABMON_6 LC_TIME Abbreviated name of the sixth month +.It ABMON_7 LC_TIME Abbreviated name of the seventh month +.It ABMON_8 LC_TIME Abbreviated name of the eighth month +.It ABMON_9 LC_TIME Abbreviated name of the ninth month +.It ABMON_10 LC_TIME Abbreviated name of the tenth month +.It ABMON_11 LC_TIME Abbreviated name of the eleventh month +.It ABMON_12 LC_TIME Abbreviated name of the twelfth month +.It ERA LC_TIME Era description segments +.It ERA_D_FMT LC_TIME Era date format string +.It ERA_D_T_FMT LC_TIME Era date and time format string +.It ERA_T_FMT LC_TIME Era time format string +.It ALT_DIGITS LC_TIME Alternative symbols for digits +.It RADIXCHAR LC_NUMERIC Radix character +.It THOUSEP LC_NUMERIC Separator for thousands +.It YESEXPR LC_MESSAGES Affirmative response expression +.It NOEXPR LC_MESSAGES Negative response expression +.\".It CRNCYSTR LC_MONETARY Local currency symbol +.El +.Sh RETURN VALUES +.Fn nl_langinfo +returns a pointer to an empty string if +.Fa item +is invalid. +.Sh EXAMPLES +The following example uses +.Fn nl_langinfo +to obtain the date and time format for the current locale: +.Pp +.Bd -literal -offset indent +#include <time.h> +#include <langinfo.h> +#include <locale.h> + +int main(void) +{ + char datestring[100]; + struct tm *tm; + time_t t; + char *ptr; + + t = time(NULL); + tm = localtime(&t); + (void)setlocale(LC_ALL, ""); + ptr = nl_langinfo(D_T_FMT); + strftime(datestring, sizeof(datestring), ptr, tm); + printf("%s\en", datestring); + return (0); +} +.Ed +.\" .Pp +.\" The following example uses +.\" .Fn nl_langinfo +.\" to obtain the setting of the currency symbol for the current locale: +.\" .Pp +.\" .Bd +.\" #include <langinfo.h> +.\" #include <locale.h> +.\" int main(void) +.\" { +.\" char *ptr; +.\" (void)setlocale(LC_ALL, ""); +.\" ptr = nl_langinfo(CRNCYSTR); +.\" printf("%s", ptr); +.\" } +.\" .Ed +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr tm 3 , +.Xr nls 7 +.Sh STANDARDS +The +.Fn nl_langinfo +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn nl_langinfo +function appeared in +.Nx 1.0 . diff --git a/static/netbsd/man3/nlist.3 b/static/netbsd/man3/nlist.3 new file mode 100644 index 00000000..f9ac7684 --- /dev/null +++ b/static/netbsd/man3/nlist.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: nlist.3,v 1.14 2020/03/30 22:14:48 wiz Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)nlist.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd March 30, 2020 +.Dt NLIST 3 +.Os +.Sh NAME +.Nm nlist +.Nd retrieve symbol table name list from an executable file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In nlist.h +.Ft int +.Fn nlist "const char *filename" "struct nlist *nl" +.Sh DESCRIPTION +The +.Fn nlist +function +retrieves name list entries from the symbol table of an +executable file. +(See +.Xr elf 5 . ) +The argument +.Fa \&nl +is set to reference the +beginning of the list. +The list is preened of binary and invalid data; +if an entry in the +name list is valid, the +.Fa n_type +and +.Fa n_value +for the entry are copied into the list +referenced by +.Fa \&nl . +No other data is copied. +The last entry in the list is always +.Dv NULL . +.Sh RETURN VALUES +The number of invalid entries is returned if successful; otherwise, +if the file +.Fa filename +does not exist or is not executable, the returned value is \-1. +.Sh SEE ALSO +.Xr a.out 5 , +.Xr elf 5 +.Sh HISTORY +A +.Fn nlist +function appeared in +.At v6 . diff --git a/static/netbsd/man3/nsdispatch.3 b/static/netbsd/man3/nsdispatch.3 new file mode 100644 index 00000000..8b61ec0b --- /dev/null +++ b/static/netbsd/man3/nsdispatch.3 @@ -0,0 +1,959 @@ +.\" $NetBSD: nsdispatch.3,v 1.34 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 1997, 1998, 1999, 2004, 2005, 2008 +.\" The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn; and by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 4, 2015 +.Dt NSDISPATCH 3 +.Os +.Sh NAME +.Nm nsdispatch +.Nd name-service switch dispatcher routine +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In nsswitch.h +.Ft int +.Fo nsdispatch +.Fa "void *nsdrv" +.Fa "const ns_dtab dtab[]" +.Fa "const char *database" +.Fa "const char *name" +.Fa "const ns_src defaults[]" +.Fa "..." +.Fc +.Sh DESCRIPTION +The +.Fn nsdispatch +function invokes the callback functions specified in +.Fa dtab +in the order given in +.Pa /etc/nsswitch.conf +for the database +.Fa database +until the action criteria for a source of that database is fulfilled. +.Pp +.Fa nsdrv +is passed to each callback function to use as necessary +(to pass back to the caller of +.Fn nsdispatch ) . +.Pp +.Fa dtab +is an array of +.Fa ns_dtab +structures, which have the following format: +.Bl -item -offset indent +.It +.Bd -literal +typedef struct { + const char *src; + nss_method cb; + void *cb_data; +} ns_dtab; +.Ed +.It +The +.Fa dtab +array should consist of one entry for each source type that has a +static implementation, +with +.Fa src +as the name of the source, +.Fa cb +as a callback function which handles that source, and +.Fa cb_data +as a pointer to arbitrary data to be passed to the callback function. +The last entry in +.Fa dtab +should contain +.Dv NULL +values for +.Fa src , +.Fa cb , +and +.Fa cb_data . +.It +The callback function signature is described by the typedef: +.Bd -ragged -offset indent +.Ft typedef int +.Fo \*(lp*nss_method\*(rp +.Fa "void *cbrv" +.Fa "void *cbdata" +.Fa "va_list ap" +.Fc ; +.Bl -tag -width cbdata +.It Fa cbrv +The +.Fa nsdrv +that +.Fn nsdispatch +was invoked with. +.It Fa cbdata +The +.Fa cb_data +member of the array entry for the source that this +callback function implements in the +.Fa dtab +argument of +.Fn nsdispatch . +.It Fa ap +The +.Fa ... +arguments to +.Fn nsdispatch , +converted to a +.Ft va_list . +.El +.Ed +.El +.Pp +.Fa database +and +.Fa name +are used to select methods from optional per-source +dynamically-loaded modules. +.Fa name +is usually the name of the function calling +.Fn nsdispatch . +Note that the callback functions provided by +.Fa dtab +take priority over those implemented in dynamically-loaded modules in the +event of a conflict. +.Pp +.Fa defaults +contains a list of default sources to try in the case of +a missing or corrupt +.Xr nsswitch.conf 5 , +or if there isn't a relevant entry for +.Fa database . +It is an array of +.Fa ns_src +structures, which have the following format: +.Bl -item -offset indent +.It +.Bd -literal +typedef struct { + const char *src; + uint32_t flags; +} ns_src; +.Ed +.It +The +.Fa defaults +array should consist of one entry for each source to consult by default +indicated by +.Fa src , +and +.Fa flags +set to the desired behavior +(usually +.Dv NS_SUCCESS ; +refer to +.Sx Callback function return values +for more information). +The last entry in +.Fa defaults +should have +.Fa src +set to +.Dv NULL +and +.Fa flags +set to 0. +.It +Some invokers of +.Fn nsdispatch +(such as +.Xr setgrent 3 ) +need to force all callback functions to be invoked, +irrespective of the action criteria listed in +.Xr nsswitch.conf 5 . +This can be achieved by adding +.Dv NS_FORCEALL +to +.Fa defaults[0].flags +before invoking +.Fn nsdispatch . +The return value of +.Fn nsdispatch +will be the result of the final callback function invoked. +.It +For convenience, a global variable defined as: +.Dl extern const ns_src __nsdefaultsrc[]; +exists which contains a single default entry for +.Sq files +for use by callers which don't require complicated default rules. +.El +.Pp +.Fa ... +are optional extra arguments, which +are passed to the appropriate callback function as a +.Xr stdarg 3 +variable argument +list of the type +.Fa va_list . +.Pp +.Nm +returns the value of the callback function that caused the dispatcher +to finish, or +.Dv NS_NOTFOUND +otherwise. +.\" +.Ss Dynamically-loaded module interface +The +.Fn nsdispatch +function loads callback functions from the run-time link-editor's search +path using the following naming convention: +.Bl -item -offset indent +.It +.Bd -literal +nss_<source>.so.<version> +.Ed +.Bl -tag -width XversionX +.It Aq source +The source that the module implements. +.It Aq version +The +.Nm nsdispatch +module interface version, which is defined by the integer +.Dv NSS_MODULE_INTERFACE_VERSION , +which has the value 0. +.El +.El +.Pp +When a module is loaded, +.Fn nsdispatch +looks for and calls the following function in the module: +.Pp +.Bd -ragged -offset indent +.Ft ns_mtab * +.Fo nss_module_register +.Fa "const char *source" +.Fa "u_int *nelems" +.Fa "nss_module_unregister_fn *unreg" +.Fc ; +.Pp +.Bl -tag -width source +.It Fa source +The name of the source that the module implements, as used by +.Fn nsdispatch +to construct the module's name. +.It Fa nelems +A pointer to an unsigned integer that +.Fn nss_module_register +should set to the number of elements in the +.Ft ns_mtab +array returned by +.Fn nss_module_register , +or +.Dv 0 +if there was a failure. +.It Fa unreg +A pointer to a function pointer that +.Fn nss_module_register +can optionally set to an unregister function to be invoked when the module is +unloaded, or +.Dv NULL +if there isn't one. +.El +.Ed +.Pp +The unregister function signature is described by the typedef: +.Pp +.Bd -ragged -offset indent +.Ft typedef void +.Fo \*(lp*nss_module_unregister_fn\*(rp +.Fa "ns_mtab *mtab" +.Fa "u_int nelems" +.Fc ; +.Pp +.Bl -tag -width nelems +.It Fa mtab +The array of +.Ft ns_mtab +structures returned by +.Fn nss_module_register . +.It Fa nelems +The +.Fa *nelems +value set by +.Fn nss_module_register . +.El +.Ed +.Pp +.Fn nss_module_register +returns an array of +.Ft ns_mtab +structures +(with +.Fa *nelems +entries), or +.Dv NULL +if there was a failure. +The +.Ft ns_mtab +structures have the following format: +.Bl -item -offset indent +.It +.Bd -literal +typedef struct { + const char *database; + const char *name; + nss_method method; + void *mdata; +} ns_mtab; +.Ed +.It +The +.Fa mtab +array should consist of one entry for each callback function (method) +that is implemented, +with +.Fa database +as the name of the database, +.Fa name +as the name of the callback function, +.Fa method +as the +.Ft nss_method +callback function that implements the method, and +.Fa mdata +as a pointer to arbitrary data to be passed to the callback function as its +.Fa cbdata +argument. +.El +.\" +.Ss Valid source types +While there is support for arbitrary sources, the following +#defines for commonly implemented sources are provided: +.Bl -column NSSRC_COMPAT COMPAT -offset indent +.It Sy #define Value +.It NSSRC_FILES "files" +.It NSSRC_DNS "dns" +.It NSSRC_NIS "nis" +.It NSSRC_COMPAT "compat" +.El +.Pp +Refer to +.Xr nsswitch.conf 5 +for a complete description of what each source type is. +.\" +.Ss Valid database types +While there is support for arbitrary databases, the following +#defines for currently implemented system databases are provided: +.Bl -column NSDB_PASSWD_COMPAT PASSWD_COMPAT -offset indent +.It Sy #define Value +.It NSDB_HOSTS "hosts" +.It NSDB_GROUP "group" +.It NSDB_GROUP_COMPAT "group_compat" +.It NSDB_NETGROUP "netgroup" +.It NSDB_NETWORKS "networks" +.It NSDB_PASSWD "passwd" +.It NSDB_PASSWD_COMPAT "passwd_compat" +.It NSDB_SHELLS "shells" +.El +.Pp +Refer to +.Xr nsswitch.conf 5 +for a complete description of what each database is. +.\" +.Ss Callback function return values +The callback functions should return one of the following values +depending upon status of the lookup: +.Bl -column NS_NOTFOUND -offset indent +.It Sy "Return value" Status code +.It NS_SUCCESS The requested entry was found. +.It NS_NOTFOUND The entry is not present at this source. +.It NS_TRYAGAIN The source is busy, and may respond to retries. +.It NS_UNAVAIL The source is not responding, or entry is corrupt. +.El +.\" +.Sh CALLBACK FUNCTION API FOR STANDARD DATABASES +The organization of the +.Fa ap +argument for an +.Fn nss_method +callback function for a standard method in a standard database is: +.Bl -enum -offset indent -compact +.It +Pointer to return value of the standard function. +.It +First argument of the standard function. +.It +(etc.) +.El +.Pp +For example, given the standard function +.Xr getgrnam 3 : +.Bd -ragged -offset indent -compact +.Ft struct group * +.Fn getgrnam "const char *name" +.Ed +the +.Fa ap +organization used by the callback functions is: +.Bl -enum -offset indent -compact +.It +.Ft "struct group **" +.It +.Ft "const char *" +.El +.Pp +.Sy NOTE: +Not all standard databases are using this calling convention yet; +those that aren't are noted below. +These will be changed in the future. +.Pp +The callback function names and +.Ft va_list +organization for various standard database callback functions are: +.\" +.Ss Methods for hosts database +.Bl -tag -width 3n +.It Sy getaddrinfo +.Ft "char *name" , +.Ft "const struct addrinfo *pai" +.Pp +Returns +.Ft "struct addrinfo *" +via +.Ft "void *cbrv" . +.It Sy gethostbyaddr +.Ft "unsigned char *addr" , +.Ft "int addrlen" , +.Ft "int af" +.Pp +Returns +.Ft "struct getnamaddr *" +via +.Ft "void *cbrv" . +.It Sy gethostbyname +.Ft "char *name" , +.Ft "int namelen" , +.Ft "int af" +.Pp +Returns +.Ft "struct getnamaddr *" +via +.Ft "void *cbrv" . +.El +.Pp +The +.Ft "struct getnamaddr" +is defined internally in libc as: +.Bd -literal +struct getnamaddr { + struct hostent *hp; + char *buf; + size_t buflen; + int *he; +}; +.Ed +.\" +.Ss Methods for group and group_compat databases +.Bl -tag -width 3n +.It Sy endgrent +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.It Sy getgrent +.Ft "struct group **retval" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct group" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getgrent 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getgrent_r +.Ft "int *retval" , +.Ft "struct group *grp" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct group **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getgrent_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy getgrgid +.Ft "struct group **retval" , +.Ft "gid_t gid" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct group" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getgrgid 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getgrgid_r +.Ft "int *retval" , +.Ft "gid_t gid" , +.Ft "struct group *grp" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct group **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getgrgid_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy getgrnam +.Ft "struct group **retval" , +.Ft "const char *name" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct group" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getgrnam 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getgrnam_r +.Ft "int *retval" , +.Ft "const char *name" , +.Ft "struct group *grp" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct group **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getgrnam_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy getgroupmembership +.Ft "int *retval" , +.Ft "const char *name" , +.Ft "gid_t basegid" , +.Ft "gid_t *groups" , +.Ft "int maxgrp" , +.Ft "int *groupc" +.Pp +.Fa retval +is unused. +.Pp +Lookups for +.Sy group_compat +are also stopped if +.Dv NS_SUCCESS +was returned to prevent multiple +.Dq "+:" +compat entries from being expanded. +.Pp +.Xr getgroupmembership 3 +returns +is -1 if +.Fa *groupc +is greater than to +.Fa maxgrp , +and 0 otherwise. +.It Sy setgroupent +.Ft "int *retval" , +.Ft "int stayopen" +.Pp +.Fa retval +should be set to 0 on failure and 1 on success. +.Pp +All methods for all sources are invoked for this method name. +.It Sy setgrent +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.El +.\" +.Ss Methods for netgroup database +.Sy NOTE: +The method APIs for this database will be changing in the near future. +.Bl -tag -width 3n +.It Sy endnetgrent +Empty +.Fa ap . +.It Sy lookup +.Ft "char *name" , +.Ft "char **line" , +.Ft "int bywhat" +.Pp +Find the given +.Fa name +and return its value in +.Fa line . +.Fa bywhat +is one of +.Dv _NG_KEYBYNAME , +.Dv _NG_KEYBYUSER , +or +.Dv _NG_KEYBYHOST . +.It Sy getnetgrent +.Ft "int *retval" , +.Ft "const char **host" , +.Ft "const char **user" , +.Ft "const char **domain" +.Pp +.Fa *retval +should be set to 0 for no more netgroup members and 1 otherwise. +.Pp +.Xr getnetgrent 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +0 otherwise. +.It Sy innetgr +.Ft "int *retval" , +.Ft "const char *grp" , +.Ft "const char *host" , +.Ft "const char *user" , +.Ft "const char *domain" +.Pp +.Fa *retval +should be set to 1 for a successful match and 0 otherwise. +.It Sy setnetgrent +.Ft "const char *netgroup" +.El +.\" +.Ss Methods for networks database +.Bl -tag -width 3n +.It Sy getnetbyaddr +.Ft "struct netent **retval" , +.Ft "uint32_t net" , +.Ft "int type" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct netent" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getnetbyaddr 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getnetbyname +.Ft "struct netent **retval" , +.Ft "const char *name" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct netent" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getnetbyname 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.El +.\" +.Ss Methods for passwd and passwd_compat databases +.Bl -tag -width 3n +.It Sy endpwent +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.It Sy getpwent +.Ft "struct passwd **retval" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct passwd" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getpwent 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getpwent_r +.Ft "int *retval" , +.Ft "struct passwd *pw" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct passwd **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getpwent_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy getpwnam +.Ft "struct passwd **retval" , +.Ft "const char *name" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct passwd" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getpwnam 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getpwnam_r +.Ft "int *retval" , +.Ft "const char *name" , +.Ft "struct passwd *pw" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct passwd **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getpwnam_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy getpwuid +.Ft "struct passwd **retval" , +.Ft "uid_t uid" +.Pp +.Fa *retval +should be set to a pointer to an internal static +.Ft "struct passwd" +on success, +.Dv NULL +otherwise. +.Pp +.Xr getpwuid 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +.Dv NULL +otherwise. +.It Sy getpwuid_r +.Ft "int *retval" , +.Ft "uid_t uid" , +.Ft "struct passwd *pw" , +.Ft "char *buffer" , +.Ft "size_t buflen" , +.Ft "struct passwd **result" +.Pp +.Fa *retval +should be set to an appropriate +.Xr errno 2 +on failure. +.Pp +.Xr getpwuid_r 3 +returns 0 +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS +or +.Dv NS_NOTFOUND , +and +.Fa *retval +otherwise. +.It Sy setpassent +.Ft "int *retval" , +.Ft "int stayopen" +.Pp +.Fa retval +should be set to 0 on failure and 1 on success. +.Pp +All methods for all sources are invoked for this method name. +.It Sy setpwent +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.El +.\" +.Ss Methods for shells database +.Bl -tag -width 3n +.It Sy endusershell +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.It Sy getusershell +.Ft "char **retval" +.Pp +.Xr getusershell 3 +returns +.Fa *retval +if +.Fn nsdispatch +returns +.Dv NS_SUCCESS , +and 0 otherwise. +.It Sy setusershell +Empty +.Fa ap . +.Pp +All methods for all sources are invoked for this method name. +.El +.\" +.Sh SEE ALSO +.Xr ld.elf_so 1 , +.Xr hesiod 3 , +.Xr stdarg 3 , +.Xr ypclnt 3 , +.Xr nsswitch.conf 5 +.Sh HISTORY +The +.Nm +routines first appeared in +.Nx 1.4 . +Support for dynamically-loaded modules first appeared in +.Nx 3.0 . +.Sh AUTHORS +.An Luke Mewburn +.Aq Mt lukem@NetBSD.org +wrote this freely distributable name-service switch implementation, +using ideas from the +.Tn ULTRIX +.Xr svc.conf 5 +and +.Tn Solaris +.Xr nsswitch.conf 4 +manual pages. +Support for dynamically-loaded modules was added by +.An Jason Thorpe +.Aq Mt thorpej@NetBSD.org , +based on code developed by the +.Fx +Project. diff --git a/static/netbsd/man3/ntlm_buf.3 b/static/netbsd/man3/ntlm_buf.3 new file mode 100644 index 00000000..da092026 --- /dev/null +++ b/static/netbsd/man3/ntlm_buf.3 @@ -0,0 +1,47 @@ +.\" $NetBSD: ntlm_buf.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "ntlm_buf" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal ntlm library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +ntlm_buf +.SH SYNOPSIS +.br +.PP +.PP +\fC#include <heimntlm\&.h>\fP +.SS "Data Fields" + +.in +1c +.ti -1c +.RI "size_t \fBlength\fP" +.br +.ti -1c +.RI "void * \fBdata\fP" +.br +.in -1c +.SH "Detailed Description" +.PP +Buffer for storing data in the NTLM library\&. When filled in by the library it should be freed with \fBheim_ntlm_free_buf()\fP\&. +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SH "Field Documentation" +.PP +.SS "void* ntlm_buf::data" +pointer to the data itself +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "size_t ntlm_buf::length" +length buffer data +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal ntlm library from the source code\&. diff --git a/static/netbsd/man3/ntlm_core.3 b/static/netbsd/man3/ntlm_core.3 new file mode 100644 index 00000000..c0a4b97e --- /dev/null +++ b/static/netbsd/man3/ntlm_core.3 @@ -0,0 +1,474 @@ +.\" $NetBSD: ntlm_core.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "ntlm_core" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal ntlm library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +ntlm_core \- Heimdal NTLM library +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "void \fBheim_ntlm_free_buf\fP (struct \fBntlm_buf\fP *p)" +.br +.ti -1c +.RI "void \fBheim_ntlm_free_targetinfo\fP (struct ntlm_targetinfo *ti)" +.br +.ti -1c +.RI "int \fBheim_ntlm_encode_targetinfo\fP (const struct ntlm_targetinfo *ti, int ucs2, struct \fBntlm_buf\fP *data)" +.br +.ti -1c +.RI "int \fBheim_ntlm_decode_targetinfo\fP (const struct \fBntlm_buf\fP *data, int ucs2, struct ntlm_targetinfo *ti)" +.br +.ti -1c +.RI "void \fBheim_ntlm_free_type1\fP (struct \fBntlm_type1\fP *data)" +.br +.ti -1c +.RI "int \fBheim_ntlm_encode_type1\fP (const struct \fBntlm_type1\fP *type1, struct \fBntlm_buf\fP *data)" +.br +.ti -1c +.RI "void \fBheim_ntlm_free_type2\fP (struct \fBntlm_type2\fP *data)" +.br +.ti -1c +.RI "int \fBheim_ntlm_encode_type2\fP (const struct \fBntlm_type2\fP *type2, struct \fBntlm_buf\fP *data)" +.br +.ti -1c +.RI "void \fBheim_ntlm_free_type3\fP (struct \fBntlm_type3\fP *data)" +.br +.ti -1c +.RI "int \fBheim_ntlm_encode_type3\fP (const struct \fBntlm_type3\fP *type3, struct \fBntlm_buf\fP *data, size_t *mic_offset)" +.br +.ti -1c +.RI "int \fBheim_ntlm_nt_key\fP (const char *password, struct \fBntlm_buf\fP *key)" +.br +.ti -1c +.RI "int \fBheim_ntlm_calculate_ntlm1\fP (void *key, size_t len, unsigned char challenge[8], struct \fBntlm_buf\fP *answer)" +.br +.ti -1c +.RI "int \fBheim_ntlm_build_ntlm1_master\fP (void *key, size_t len, struct \fBntlm_buf\fP *session, struct \fBntlm_buf\fP *master)" +.br +.ti -1c +.RI "int \fBheim_ntlm_build_ntlm2_master\fP (void *key, size_t len, struct \fBntlm_buf\fP *blob, struct \fBntlm_buf\fP *session, struct \fBntlm_buf\fP *master)" +.br +.ti -1c +.RI "int \fBheim_ntlm_keyex_unwrap\fP (struct \fBntlm_buf\fP *baseKey, struct \fBntlm_buf\fP *encryptedSession, struct \fBntlm_buf\fP *session)" +.br +.ti -1c +.RI "int \fBheim_ntlm_ntlmv2_key\fP (const void *key, size_t len, const char *username, const char *target, int upper_case_target, unsigned char ntlmv2[16])" +.br +.ti -1c +.RI "int \fBheim_ntlm_calculate_lm2\fP (const void *key, size_t len, const char *username, const char *target, const unsigned char serverchallenge[8], unsigned char ntlmv2[16], struct \fBntlm_buf\fP *answer)" +.br +.ti -1c +.RI "int \fBheim_ntlm_calculate_ntlm2\fP (const void *key, size_t len, const char *username, const char *target, const unsigned char serverchallenge[8], const struct \fBntlm_buf\fP *infotarget, unsigned char ntlmv2[16], struct \fBntlm_buf\fP *answer)" +.br +.ti -1c +.RI "int \fBheim_ntlm_verify_ntlm2\fP (const void *key, size_t len, const char *username, const char *target, time_t now, const unsigned char serverchallenge[8], const struct \fBntlm_buf\fP *answer, struct \fBntlm_buf\fP *infotarget, unsigned char ntlmv2[16])" +.br +.in -1c +.SH "Detailed Description" +.PP +The NTLM core functions implement the string2key generation function, message encode and decode function, and the hash function functions\&. +.SH "Function Documentation" +.PP +.SS "int heim_ntlm_build_ntlm1_master (void * key, size_t len, struct \fBntlm_buf\fP * session, struct \fBntlm_buf\fP * master)" +Generates an NTLMv1 session random with assosited session master key\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm v1 key +.br +\fIlen\fP length of key +.br +\fIsession\fP generated session nonce, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.br +\fImaster\fP calculated session master key, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.SS "int heim_ntlm_build_ntlm2_master (void * key, size_t len, struct \fBntlm_buf\fP * blob, struct \fBntlm_buf\fP * session, struct \fBntlm_buf\fP * master)" +Generates an NTLMv2 session random with associated session master key\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the NTLMv2 key +.br +\fIlen\fP length of key +.br +\fIblob\fP the NTLMv2 'blob' +.br +\fIsession\fP generated session nonce, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.br +\fImaster\fP calculated session master key, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.SS "int heim_ntlm_calculate_lm2 (const void * key, size_t len, const char * username, const char * target, const unsigned char serverchallenge[8], unsigned char ntlmv2[16], struct \fBntlm_buf\fP * answer)" +Calculate LMv2 response +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm key +.br +\fIlen\fP length of key +.br +\fIusername\fP name of the user, as sent in the message, assumed to be in UTF8\&. +.br +\fItarget\fP the name of the target, assumed to be in UTF8\&. +.br +\fIserverchallenge\fP challenge as sent by the server in the type2 message\&. +.br +\fIntlmv2\fP calculated session key +.br +\fIanswer\fP ntlm response answer, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.SS "int heim_ntlm_calculate_ntlm1 (void * key, size_t len, unsigned char challenge[8], struct \fBntlm_buf\fP * answer)" +Calculate NTLMv1 response hash +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm v1 key +.br +\fIlen\fP length of key +.br +\fIchallenge\fP sent by the server +.br +\fIanswer\fP calculated answer, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_calculate_ntlm2 (const void * key, size_t len, const char * username, const char * target, const unsigned char serverchallenge[8], const struct \fBntlm_buf\fP * infotarget, unsigned char ntlmv2[16], struct \fBntlm_buf\fP * answer)" +Calculate NTLMv2 response +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm key +.br +\fIlen\fP length of key +.br +\fIusername\fP name of the user, as sent in the message, assumed to be in UTF8\&. +.br +\fItarget\fP the name of the target, assumed to be in UTF8\&. +.br +\fIserverchallenge\fP challenge as sent by the server in the type2 message\&. +.br +\fIinfotarget\fP infotarget as sent by the server in the type2 message\&. +.br +\fIntlmv2\fP calculated session key +.br +\fIanswer\fP ntlm response answer, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_decode_targetinfo (const struct \fBntlm_buf\fP * data, int ucs2, struct ntlm_targetinfo * ti)" +Decodes an NTLM targetinfo message +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP input data buffer with the encode NTLM targetinfo message +.br +\fIucs2\fP if the strings should be encoded with ucs2 (selected by flag in message)\&. +.br +\fIti\fP the decoded target info, should be freed with \fBheim_ntlm_free_targetinfo()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_encode_targetinfo (const struct ntlm_targetinfo * ti, int ucs2, struct \fBntlm_buf\fP * data)" +Encodes a ntlm_targetinfo message\&. +.PP +\fBParameters\fP +.RS 4 +\fIti\fP the ntlm_targetinfo message to encode\&. +.br +\fIucs2\fP ignored +.br +\fIdata\fP is the return buffer with the encoded message, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_encode_type1 (const struct \fBntlm_type1\fP * type1, struct \fBntlm_buf\fP * data)" +Encodes an \fBntlm_type1\fP message\&. +.PP +\fBParameters\fP +.RS 4 +\fItype1\fP the \fBntlm_type1\fP message to encode\&. +.br +\fIdata\fP is the return buffer with the encoded message, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_encode_type2 (const struct \fBntlm_type2\fP * type2, struct \fBntlm_buf\fP * data)" +Encodes an \fBntlm_type2\fP message\&. +.PP +\fBParameters\fP +.RS 4 +\fItype2\fP the \fBntlm_type2\fP message to encode\&. +.br +\fIdata\fP is the return buffer with the encoded message, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_encode_type3 (const struct \fBntlm_type3\fP * type3, struct \fBntlm_buf\fP * data, size_t * mic_offset)" +Encodes an \fBntlm_type3\fP message\&. +.PP +\fBParameters\fP +.RS 4 +\fItype3\fP the \fBntlm_type3\fP message to encode\&. +.br +\fIdata\fP is the return buffer with the encoded message, should be +.br +\fImic_offset\fP offset of message integrity code freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "void heim_ntlm_free_buf (struct \fBntlm_buf\fP * p)" +heim_ntlm_free_buf frees the ntlm buffer +.PP +\fBParameters\fP +.RS 4 +\fIp\fP buffer to be freed +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "void heim_ntlm_free_targetinfo (struct ntlm_targetinfo * ti)" +Frees the ntlm_targetinfo message +.PP +\fBParameters\fP +.RS 4 +\fIti\fP targetinfo to be freed +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "void heim_ntlm_free_type1 (struct \fBntlm_type1\fP * data)" +Frees the \fBntlm_type1\fP message +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP message to be freed +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "void heim_ntlm_free_type2 (struct \fBntlm_type2\fP * data)" +Frees the \fBntlm_type2\fP message +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP message to be freed +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "void heim_ntlm_free_type3 (struct \fBntlm_type3\fP * data)" +Frees the \fBntlm_type3\fP message +.PP +\fBParameters\fP +.RS 4 +\fIdata\fP message to be freed +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_keyex_unwrap (struct \fBntlm_buf\fP * baseKey, struct \fBntlm_buf\fP * encryptedSession, struct \fBntlm_buf\fP * session)" +Given a key and encrypted session, unwrap the session key +.PP +\fBParameters\fP +.RS 4 +\fIbaseKey\fP the sessionBaseKey +.br +\fIencryptedSession\fP encrypted session, type3\&.session field\&. +.br +\fIsession\fP generated session nonce, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.SS "int heim_ntlm_nt_key (const char * password, struct \fBntlm_buf\fP * key)" +Calculate the NTLM key, the password is assumed to be in UTF8\&. +.PP +\fBParameters\fP +.RS 4 +\fIpassword\fP password to calcute the key for\&. +.br +\fIkey\fP calcuted key, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP + +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SS "int heim_ntlm_ntlmv2_key (const void * key, size_t len, const char * username, const char * target, int upper_case_target, unsigned char ntlmv2[16])" +Generates an NTLMv2 session key\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm key +.br +\fIlen\fP length of key +.br +\fIusername\fP name of the user, as sent in the message, assumed to be in UTF8\&. +.br +\fItarget\fP the name of the target, assumed to be in UTF8\&. +.br +\fIupper_case_target\fP upper case the target, should not be used only for legacy systems +.br +\fIntlmv2\fP the ntlmv2 session key +.RE +.PP +\fBReturns\fP +.RS 4 +0 on success, or an error code on failure\&. +.RE +.PP + +.SS "int heim_ntlm_verify_ntlm2 (const void * key, size_t len, const char * username, const char * target, time_t now, const unsigned char serverchallenge[8], const struct \fBntlm_buf\fP * answer, struct \fBntlm_buf\fP * infotarget, unsigned char ntlmv2[16])" +Verify NTLMv2 response\&. +.PP +\fBParameters\fP +.RS 4 +\fIkey\fP the ntlm key +.br +\fIlen\fP length of key +.br +\fIusername\fP name of the user, as sent in the message, assumed to be in UTF8\&. +.br +\fItarget\fP the name of the target, assumed to be in UTF8\&. +.br +\fInow\fP the time now (0 if the library should pick it up itself) +.br +\fIserverchallenge\fP challenge as sent by the server in the type2 message\&. +.br +\fIanswer\fP ntlm response answer, should be freed with \fBheim_ntlm_free_buf()\fP\&. +.br +\fIinfotarget\fP infotarget as sent by the server in the type2 message\&. +.br +\fIntlmv2\fP calculated session key +.RE +.PP +\fBReturns\fP +.RS 4 +In case of success 0 is return, an errors, a errno in what went wrong\&. +.RE +.PP +First check with the domain as the client passed it to the function\&. +.PP +Second check with domain uppercased\&. +.PP +Third check with empty domain\&. +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal ntlm library from the source code\&. diff --git a/static/netbsd/man3/ntlm_type1.3 b/static/netbsd/man3/ntlm_type1.3 new file mode 100644 index 00000000..23abb8c9 --- /dev/null +++ b/static/netbsd/man3/ntlm_type1.3 @@ -0,0 +1,23 @@ +.\" $NetBSD: ntlm_type1.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "ntlm_type1" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal ntlm library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +ntlm_type1 +.SH SYNOPSIS +.br +.PP +.PP +\fC#include <heimntlm\&.h>\fP +.SH "Detailed Description" +.PP +Struct for the NTLM type1 message info, the strings is assumed to be in UTF8\&. When filled in by the library it should be freed with \fBheim_ntlm_free_type1()\fP\&. +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal ntlm library from the source code\&. diff --git a/static/netbsd/man3/ntlm_type2.3 b/static/netbsd/man3/ntlm_type2.3 new file mode 100644 index 00000000..814b5804 --- /dev/null +++ b/static/netbsd/man3/ntlm_type2.3 @@ -0,0 +1,23 @@ +.\" $NetBSD: ntlm_type2.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "ntlm_type2" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal ntlm library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +ntlm_type2 +.SH SYNOPSIS +.br +.PP +.PP +\fC#include <heimntlm\&.h>\fP +.SH "Detailed Description" +.PP +Struct for the NTLM type2 message info, the strings is assumed to be in UTF8\&. When filled in by the library it should be freed with \fBheim_ntlm_free_type2()\fP\&. +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal ntlm library from the source code\&. diff --git a/static/netbsd/man3/ntlm_type3.3 b/static/netbsd/man3/ntlm_type3.3 new file mode 100644 index 00000000..a9ff3d4e --- /dev/null +++ b/static/netbsd/man3/ntlm_type3.3 @@ -0,0 +1,23 @@ +.\" $NetBSD: ntlm_type3.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "ntlm_type3" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal ntlm library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +ntlm_type3 +.SH SYNOPSIS +.br +.PP +.PP +\fC#include <heimntlm\&.h>\fP +.SH "Detailed Description" +.PP +Struct for the NTLM type3 message info, the strings is assumed to be in UTF8\&. When filled in by the library it should be freed with \fBheim_ntlm_free_type3()\fP\&. +.PP +\fBExamples\fP +.in +1c +\fBtest_ntlm\&.c\fP\&. + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal ntlm library from the source code\&. diff --git a/static/netbsd/man3/o2i_SCT_LIST.3 b/static/netbsd/man3/o2i_SCT_LIST.3 new file mode 100644 index 00000000..30b36b0f --- /dev/null +++ b/static/netbsd/man3/o2i_SCT_LIST.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: o2i_SCT_LIST.3,v 1.5 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "o2i_SCT_LIST 3" +.TH o2i_SCT_LIST 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +o2i_SCT_LIST, i2o_SCT_LIST, o2i_SCT, i2o_SCT \- +decode and encode Signed Certificate Timestamp lists in TLS wire format +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ct.h> +\& +\& STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, +\& size_t len); +\& int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp); +\& SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len); +\& int i2o_SCT(const SCT *sct, unsigned char **out); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The SCT_LIST and SCT functions are very similar to the i2d and d2i family of +functions, except that they convert to and from TLS wire format, as described in +RFC 6962. See \fBd2i_SCT_LIST\fR\|(3) for more information about how the parameters are +treated and the return values. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +All of the functions have return values consistent with those stated for +\&\fBd2i_SCT_LIST\fR\|(3) and \fBi2d_SCT_LIST\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBct\fR\|(7), +\&\fBd2i_SCT_LIST\fR\|(3), +\&\fBi2d_SCT_LIST\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 1.1.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/offtime.3 b/static/netbsd/man3/offtime.3 new file mode 100644 index 00000000..7f933112 --- /dev/null +++ b/static/netbsd/man3/offtime.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: offtime.3,v 1.5 2025/04/21 06:38:10 nia Exp $ +.\" Written by Klaus Klein, May 10, 2004. +.\" Public domain. +.Dd April 20, 2025 +.Dt OFFTIME 3 +.Os +.Sh NAME +.Nm offtime , +.Nm offtime_r , +.Nm timeoff , +.Nm timegm , +.Nm timelocal +.Nd convert date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft struct tm * +.Fn offtime "const time_t * clock" "long int offset" +.Ft struct tm * +.Fn offtime_r "const time_t * clock" "long int offset" "struct tm *ret" +.Ft time_t +.Fn timeoff "struct tm * tm" "long int offset" +.Ft time_t +.Fn timegm "struct tm * tm" +.Ft time_t +.Fn timelocal "struct tm * tm" +.Sh DESCRIPTION +These functions are inspired by C standard interfaces named similarly. +.Pp +.Fn offtime +converts the calendar time +.Fa clock , +offset by +.Fa offset +seconds, +into broken-down time, expressed as Coordinated Universal Time (UTC). +.Pp +.Fn offtime_r +is similar to +.Fn offtime +but it places the returned +.Ft "struct tm *" +in the user supplied +.Fa ret +argument. +.Pp +.Fn timeoff +converts the broken-down time +.Fa tm , +expressed as UTC, +offset by +.Fa offset +seconds, +into a calendar time value. +.Pp +.Fn timegm +converts the broken-down time +.Fa tm +into a calendar time value, effectively being the inverse of +.Xr gmtime 3 . +It is equivalent to the C standard function +.Xr mktime 3 +operating in UTC. +.Pp +.Fn timelocal +converts the broken down time +.Fa tm , +expressed as local time, into a calendar time value. +It is equivalent to the C standard function +.Xr mktime 3 , +and is provided for symmetry only. +.Sh SEE ALSO +.Xr ctime 3 , +.Xr tm 3 , +.Xr tzset 3 +.Sh STANDARDS +The +.Fn timegm +function conforms to +.St -isoC-2023 . diff --git a/static/netbsd/man3/ohash_init.3 b/static/netbsd/man3/ohash_init.3 new file mode 100644 index 00000000..a0939a8e --- /dev/null +++ b/static/netbsd/man3/ohash_init.3 @@ -0,0 +1,229 @@ +.\" $OpenBSD: ohash_init.3,v 1.14 2007/05/31 19:19:30 jmc Exp $ +.\" Copyright (c) 1999 Marc Espie <espie@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: May 31 2007 $ +.Dt OPEN_HASH 3 +.Os +.Sh NAME +.Nm ohash_init , +.Nm ohash_delete , +.Nm ohash_lookup_interval , +.Nm ohash_lookup_memory , +.Nm ohash_find , +.Nm ohash_remove , +.Nm ohash_insert , +.Nm ohash_first , +.Nm ohash_next , +.Nm ohash_entries +.Nd light-weight open hashing +.Sh SYNOPSIS +.Fd #include <stdint.h> +.Fd #include <stddef.h> +.Fd #include <ohash.h> +.Ft void +.Fn ohash_init "struct ohash *h" "unsigned int size" "struct ohash_info *info" +.Ft void +.Fn ohash_delete "struct ohash *h" +.Ft "unsigned int" +.Fn ohash_lookup_interval "struct ohash *h" "const char *start" "const char *end" "uint32_t hv" +.Ft "unsigned int" +.Fn ohash_lookup_memory "struct ohash *h" "const char *k" "size_t s" "uint32_t hv" +.Ft void * +.Fn ohash_find "struct ohash *h" "unsigned int i" +.Ft void * +.Fn ohash_remove "struct ohash *h" "unsigned int i" +.Ft void * +.Fn ohash_insert "struct ohash *h" "unsigned int i" "void *p" +.Ft void * +.Fn ohash_first "struct ohash *h" "unsigned int *i" +.Ft void * +.Fn ohash_next "struct ohash *h" "unsigned int *i" +.Ft "unsigned int" +.Fn ohash_entries "struct ohash *h" +.Sh DESCRIPTION +These functions have been designed as a fast, extensible alternative to +the usual hash table functions. +They provide storage and retrieval of records indexed by keys, +where a key is a contiguous sequence of bytes at a fixed position in +each record. +Keys can either be NUL-terminated strings or fixed-size memory areas. +All functions take a pointer to an ohash structure as the +.Fa h +function argument. +Storage for this structure should be provided by user code. +.Pp +.Fn ohash_init +initializes the table to store roughly 2 to the power +.Fa size +elements. +.Fa info +holds the position of the key in each record, and two pointers to +.Xr calloc 3 +and +.Xr free 3 Ns -like +functions, to use for managing the table internal storage. +.Pp +.Fn ohash_delete +frees storage internal to +.Fa h . +Elements themselves should be freed by the user first, using for instance +.Fn ohash_first +and +.Fn ohash_next . +.Pp +.Fn ohash_lookup_interval +and +.Fn ohash_lookup_memory +are the basic look-up element functions. +The hashing function result is provided by the user as +.Fa hv . +These return a +.Qq slot +in the ohash table +.Fa h , +to be used with +.Fn ohash_find , +.Fn ohash_insert , +or +.Fn ohash_remove . +This slot is only valid up to the next call to +.Fn ohash_insert +or +.Fn ohash_remove . +.Pp +.Fn ohash_lookup_interval +handles string-like keys. +.Fn ohash_lookup_interval +assumes the key is the interval between +.Fa start +and +.Fa end , +exclusive, +though the actual elements stored in the table should only contain +NUL-terminated keys. +.Pp +.Fn ohash_lookup_memory +assumes the key is the memory area starting at +.Fa k +of size +.Fa s . +All bytes are significant in key comparison. +.Pp +.Fn ohash_find +retrieves an element from a slot +.Fa i +returned by the +.Fn ohash_lookup* +functions. +It returns +.Dv NULL +if the slot is empty. +.Pp +.Fn ohash_insert +inserts a new element +.Fa p +at slot +.Fa i . +Slot +.Fa i +must be empty and element +.Fa p +must have a key corresponding to the +.Fn ohash_lookup* +call. +.Pp +.Fn ohash_remove +removes the element at slot +.Fa i . +It returns the removed element, for user code to dispose of, or +.Dv NULL +if the slot was empty. +.Pp +.Fn ohash_first +and +.Fn ohash_next +can be used to access all elements in an ohash table, like this: +.Bd -literal -offset indent +for (n = ohash_first(h, &i); n != NULL; n = ohash_next(h, &i)) + do_something_with(n); +.Ed +.Pp +.Fa i +points to an auxiliary unsigned integer used to record the current position +in the ohash table. +Those functions are safe to use even while entries are added to/removed +from the table, but in such a case they don't guarantee that new entries +will be returned. +As a special case, they can safely be used to free elements in the table. +.Pp +.Fn ohash_entries +returns the number of elements in the hash table. +.Sh STORAGE HANDLING +Only +.Fn ohash_init , +.Fn ohash_insert , +.Fn ohash_remove +and +.Fn ohash_delete +may call the user-supplied memory functions. +It is the responsibility of the user memory allocation code to verify +that those calls did not fail. +.Pp +If memory allocation fails, +.Fn ohash_init +returns a useless hash table. +.Fn ohash_insert +and +.Fn ohash_remove +still perform the requested operation, but the returned table should be +considered read-only. +It can still be accessed by +.Fn ohash_lookup* , +.Fn ohash_find , +.Fn ohash_first +and +.Fn ohash_next +to dump relevant information to disk before aborting. +.Sh THREAD SAFETY +The open hashing functions are not thread-safe by design. +In particular, in a threaded environment, there is no guarantee that a +.Qq slot +will not move between a +.Fn ohash_lookup* +and a +.Fn ohash_find , +.Fn ohash_insert +or +.Fn ohash_remove +call. +.Pp +Multi-threaded applications should explicitly protect ohash table access. +.Sh SEE ALSO +.Xr ohash_interval 3 +.Rs +.%A Donald E. Knuth +.%B The Art of Computer Programming +.%V Vol. 3 +.%P pp 506-550 +.%D 1973 +.Re +.Sh STANDARDS +Those functions are completely non-standard and should be avoided in +portable programs. +.Sh HISTORY +Those functions were designed and written for +.Ox +.Xr make 1 +by Marc Espie in 1999. diff --git a/static/netbsd/man3/ohash_interval.3 b/static/netbsd/man3/ohash_interval.3 new file mode 100644 index 00000000..2e56ca5b --- /dev/null +++ b/static/netbsd/man3/ohash_interval.3 @@ -0,0 +1,90 @@ +.\" $OpenBSD: ohash_interval.3,v 1.11 2007/05/31 19:19:30 jmc Exp $ +.\" Copyright (c) 2001 Marc Espie <espie@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: May 31 2007 $ +.Dt OPEN_HASH_HELPER 3 +.Os +.Sh NAME +.Nm ohash_interval , +.Nm ohash_create_entry , +.Nm ohash_qlookup , +.Nm ohash_qlookupi +.Nd helper functions for open hashing +.Sh SYNOPSIS +.Fd #include <stdint.h> +.Fd #include <stddef.h> +.Fd #include <ohash.h> +.Ft u_int32_t +.Fn ohash_interval "const char *start" "const char **pend" +.Ft "void *" +.Fn ohash_create_entry "struct ohash_info *info" "const char *start" "const char **pend" +.Ft "unsigned int" +.Fn ohash_qlookupi "struct ohash *h" "const char *start" "const char **pend" +.Ft "unsigned int" +.Fn ohash_qlookup "struct ohash *h" "const char *start" +.Sh DESCRIPTION +These functions are commonly used to simplify open hashing usage, and use +similar conventions. +They operate indifferently on NUL-terminated strings +.Po +by setting +.Fa *pend += +.Dv NULL +.Pc +or memory ranges +.Po +delimited by +.Fa start +and +.Fa *pend +.Pc . +For NUL-terminated strings, as a side effect, those functions +set +.Fa *pend +to the terminating NUL byte. +.Pp +.Fn ohash_interval +is a simple hashing function that yields good results on common data sets. +.Pp +.Fn ohash_create_entry +can be used to create a new record with a given key. +In that case, +the alloc field of +.Fa info +should point to a +.Xr malloc 3 Ns -like +function to allocate the storage. +.Pp +.Fn ohash_qlookupi +is a wrapper function that simply calls +.Fn ohash_interval +and +.Fn ohash_lookup_interval . +.Pp +.Fn ohash_qlookup +is a variation on +.Fn ohash_qlookupi +designed for NUL-terminated strings. +.Sh SEE ALSO +.Xr ohash_init 3 +.Sh STANDARDS +Those functions are completely non-standard and should be avoided in +portable programs. +.Sh HISTORY +Those functions were designed and written for +.Ox +.Xr make 1 +by Marc Espie in 1999. diff --git a/static/netbsd/man3/omapi.3 b/static/netbsd/man3/omapi.3 new file mode 100644 index 00000000..0433953d --- /dev/null +++ b/static/netbsd/man3/omapi.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: omapi.3,v 1.3 2022/04/03 01:10:59 christos Exp $ +.\" +.\" omapi.3 +.\" +.\" Copyright (C) 2004-2022 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 2000-2003 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" PO Box 360 +.\" Newmarket, NH 03857 USA +.\" <info@isc.org> +.\" https://www.isc.org/ +.\" +.\" This software has been written for Internet Systems Consortium +.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. +.\" +.\" Support and other services are available for ISC products - see +.\" https://www.isc.org for more information or to learn more about ISC. +.\" +.TH omapi 3 +.SH NAME +OMAPI - Object Management Application Programming Interface +.SH DESCRIPTION +.PP +OMAPI is an programming layer designed for controlling remote +applications, and for querying them for their state. It is currently +used by the ISC DHCP server and this outline addresses the parts of +OMAPI appropriate to the clients of DHCP server. It does this by also +describing the use of a thin API layered on top of OMAPI called +\'dhcpctl\' +.PP +OMAPI uses TCP/IP as the transport for server communication, and +security can be imposed by having the client and server +cryptographically sign messages using a shared secret. +.PP +dhcpctl works by presenting the client with handles to objects that +act as surrogates for the real objects in the server. For example a +client will create a handle for a lease object, and will request the +server to fill the lease handle's state. The client application can +then pull details such as the lease expiration time from the lease +handle. +.PP +Modifications can be made to the server state by creating handles to +new objects, or by modifying attributes of handles to existing +objects, and then instructing the server to update itself according to +the changes made. +.SH USAGE +.PP +The client application must always call dhcpctl_initialize() before +making calls to any other dhcpctl functions. This initializes +various internal data structures. +.PP +To create the connection to the server the client must use +dhcpctl_connect() function. As well as making the physical connection +it will also set up the connection data structures to do +authentication on each message, if that is required. +.PP +All the dhcpctl functions return an integer value of type +isc_result_t. A successful call will yield a result of +ISC_R_SUCCESS. If the call fails for a reason local to the client +(e.g. insufficient local memory, or invalid arguments to the call) +then the return value of the dhcpctl function will show that. If the +call succeeds but the server couldn't process the request the error +value from the server is returned through another way, shown below. +.PP +The easiest way to understand dhcpctl is to see it in action. The +following program is fully functional, but almost all error checking +has been removed to make is shorter and easier to understand. This +program will query the server running on the localhost for the details +of the lease for IP address 10.0.0.101. It will then print out the time +the lease ends. +.PP +.nf + #include <stdarg.h> + #include <sys/time.h> + #include <sys/socket.h> + #include <stdio.h> + #include <netinet/in.h> + + #include <isc/result.h> + #include <dhcpctl/dhcpctl.h> + + int main (int argc, char **argv) { + dhcpctl_data_string ipaddrstring = NULL; + dhcpctl_data_string value = NULL; +.fi +.PP +All modifications of handles and all accesses of handle data happen +via dhcpctl_data_string objects. +.PP +.nf + dhcpctl_handle connection = NULL; + dhcpctl_handle lease = NULL; + isc_result_t waitstatus; + struct in_addr convaddr; + time_t thetime; + + dhcpctl_initialize (); +.fi +.PP +Required first step. +.PP +.nf + dhcpctl_connect (&connection, "127.0.0.1", + 7911, 0); +.fi +.PP +Sets up the connection to the server. The server normally listens on +port 7911 unless configured to do otherwise. +.PP +.nf + dhcpctl_new_object (&lease, connection, + "lease"); +.fi +.PP +Here we create a handle to a lease. This call just sets up local data +structure. The server hasn't yet made any association between the +client's data structure and any lease it has. +.PP +.nf + memset (&ipaddrstring, 0, sizeof + ipaddrstring); + + inet_pton(AF_INET, "10.0.0.101", + &convaddr); + + omapi_data_string_new (&ipaddrstring, + 4, MDL); +.fi +.PP +Create a new data string to storing in the handle. +.PP +.nf + memcpy(ipaddrstring->value, &convaddr.s_addr, 4); + + dhcpctl_set_value (lease, ipaddrstring, + "ip-address"); +.fi +.PP +We're setting the ip-address attribute of the lease handle to the +given address. We've not set any other attributes so when the server +makes the association the ip address will be all it uses to look up +the lease in its tables. +.PP +.nf + dhcpctl_open_object (lease, connection, 0); +.fi +.PP +Here we prime the connection with the request to look up the lease in +the server and fill up the local handle with the attributes the server +will send over in its answer. +.PP +.nf + dhcpctl_wait_for_completion (lease, + &waitstatus); +.fi +.PP +This call causes the message to get sent to the server (the message to +look up the lease and send back the attribute values in the +answer). The value in the variable waitstatus when the function +returns will be the result from the server. If the message could +not be processed properly by the server then the error will be +reflected here. +.PP +.nf + if (waitstatus != ISC_R_SUCCESS) { + /* server not authoritative */ + exit (0); + } + + dhcpctl_data_string_dereference(&ipaddrstring, + MDL); +.fi +.PP +Clean-up memory we no longer need. +.PP +.nf + dhcpctl_get_value (&value, lease, "ends"); +.fi +.PP +Get the attribute named ``ends'' from the lease handle. This is a +4-byte integer of the time (in unix epoch seconds) that the lease +will expire. +.PP +.nf + + memcpy(&thetime, value->value, value->len); + dhcpctl_data_string_dereference(&value, MDL); + + fprintf (stdout, "ending time is %s", + ctime(&thetime)); + } + +.fi +.SH AUTHENTICATION +If the server demands authenticated connections then before opening +the connection the user must call dhcpctl_new_authenticator. +.PP +.nf + dhcpctl_handle authenticator = NULL; + const char *keyname = "a-key-name"; + const char *algorithm = "hmac-md5"; + const char *secret = "a-shared-secret"; + + dhcpctl_new_authenticator (&authenticator, + keyname, + algorithm, + secret, + strlen(secret) + 1); +.fi +.PP +The keyname, algorithm and must all match what is specified in the server's +dhcpd.conf file, excepting that the secret should appear in \'raw\' form, not +in base64 as it would in dhcpd.conf: +.PP +.nf + key "a-key-name" { + algorithm hmac-md5; + secret "a-shared-secret"; + }; + + # Set the omapi-key value to use + # authenticated connections + omapi-key a-key-name; +.fi +.PP +The authenticator handle that is created by the call to +dhcpctl_new_authenticator must be given as the last (the 4th) argument +to the call to dhcpctl_connect(). All messages will then be signed +with the given secret string using the specified algorithm. +.SH SEE ALSO +dhcpctl(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5). +.SH AUTHOR +.B omapi +is maintained by ISC. To learn more about Internet Systems Consortium, +see +.B https://www.isc.org diff --git a/static/netbsd/man3/open_memstream.3 b/static/netbsd/man3/open_memstream.3 new file mode 100644 index 00000000..b6c0fdc2 --- /dev/null +++ b/static/netbsd/man3/open_memstream.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: open_memstream.3,v 1.4 2021/12/12 08:49:57 andvar Exp $ +.\" Copyright (c) 2013 Advanced Computing Technologies LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/stdio/open_memstream.3 247415 2013-02-27 20:09:25Z joel $ +.\" +.Dd October 12, 2014 +.Dt OPEN_MEMSTREAM 3 +.Os +.Sh NAME +.Nm open_memstream , +.Nm open_wmemstream +.Nd dynamic memory buffer stream open functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn open_memstream "char **bufp" "size_t *sizep" +.In wchar.h +.Ft FILE * +.Fn open_wmemstream "wchar_t **bufp" "size_t *sizep" +.Sh DESCRIPTION +The +.Fn open_memstream +and +.Fn open_wmemstream +functions create a write-only, seekable stream backed by a dynamically +allocated memory buffer. +The +.Fn open_memstream +function creates a byte-oriented stream, +while the +.Fn open_wmemstream +function creates a wide-oriented stream. +.Pp +Each stream maintains a current position and size. +Initially, +the position and size are set to zero. +Each write begins at the current position and advances it the number of +successfully written bytes for +.Fn open_memstream +or wide characters for +.Fn open_wmemstream . +If a write moves the current position beyond the length of the buffer, +the length of the buffer is extended and a null character is appended to the +buffer. +.Pp +A stream's buffer always contains a null character at the end of the buffer +that is not included in the current length. +.Pp +If a stream's current position is moved beyond the current length via a +seek operation and a write is performed, +the characters between the current length and the current position are filled +with null characters before the write is performed. +.Pp +After a successful call to +.Xr fclose 3 +or +.Xr fflush 3 , +the pointer referenced by +.Fa bufp +will contain the start of the memory buffer and the variable referenced by +.Fa sizep +will contain the smaller of the current position and the current buffer length. +.Pp +After a successful call to +.Xr fflush 3 , +the pointer referenced by +.Fa bufp +and the variable referenced by +.Fa sizep +are only valid until the next write operation or a call to +.Xr fclose 3 . +.Pp +Once a stream is closed, +the allocated buffer referenced by +.Fa bufp +should be released via a call to +.Xr free 3 +when it is no longer needed. +.Sh IMPLEMENTATION NOTES +Internally all I/O streams are effectively byte-oriented, +so using wide-oriented operations to write to a stream opened via +.Fn open_wmemstream +results in wide characters being expanded to a stream of multibyte characters +in stdio's internal buffers. +These multibyte characters are then converted back to wide characters when +written into the stream. +As a result, +the wide-oriented streams maintain an internal multibyte character conversion +state that is cleared on any seek operation that changes the current position. +This should have no effect as long as wide-oriented output operations are used +on a wide-oriented stream. +.Sh RETURN VALUES +Upon successful completion, +.Fn open_memstream +and +.Fn open_wmemstream +return a +.Tn FILE +pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa bufp +or +.Fa sizep +argument was +.Dv NULL . +.It Bq Er ENOMEM +Memory for the stream or buffer could not be allocated. +.El +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr free 3 , +.Xr fseek 3 , +.Xr stdio 3 +.Sh STANDARDS +The +.Fn open_memstream +and +.Fn open_wmemstream +functions conform to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/opendisk.3 b/static/netbsd/man3/opendisk.3 new file mode 100644 index 00000000..c36bc9af --- /dev/null +++ b/static/netbsd/man3/opendisk.3 @@ -0,0 +1,233 @@ +.\" $NetBSD: opendisk.3,v 1.17 2024/10/13 14:56:31 rillig Exp $ +.\" +.\" Copyright (c) 1997, 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 13, 2024 +.Dt OPENDISK 3 +.Os +.Sh NAME +.Nm opendisk , +.Nm opendisk1 +.Nd open a disk partition +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fo opendisk +.Fa "const char *path" +.Fa "int flags" +.Fa "char *buf" +.Fa "size_t buflen" +.Fa "int iscooked" +.Fc +.Ft int +.Fo opendisk1 +.Fa "const char *path" +.Fa "int flags" +.Fa "char *buf" +.Fa "size_t buflen" +.Fa "int iscooked" +.Fa "int (*ofn)(const char *, int, ...)" +.Fc +.Sh DESCRIPTION +.Fn opendisk +opens +.Fa path , +for reading and/or writing as specified by the argument +.Fa flags +using +.Xr open 2 , +and the file descriptor is returned to the caller. +.Fa buf +is used to store the resultant filename. +.Fa buflen +is the size, in bytes, of the array referenced by +.Fa buf +(usually +.Dv MAXPATHLEN +bytes). +.Fa iscooked +controls which paths in +.Pa /dev +are tried. +.Pp +.Fn opendisk +attempts to open the following variations of +.Fa path , +in order: +.Pp +If +.Fa path +does not contain a +slash +.Pq Dq / , +the following variations are attempted: +.Pp +.Bl -dash -compact +.It +If +.Fa iscooked +is zero: +.Bl -tag -compact -width "/dev/rpathX" +.It Pa /dev/rpath +.Fa path +with a prefix of +.Dq Pa /dev/r . +.It Pa /dev/rpath Ns Em X +.Fa path +with a prefix of +.Dq Pa /dev/r +and a suffix of +.Sq Em X +(q.v.). +.El +.It +If +.Fa iscooked +is non-zero: +.Bl -tag -compact -width "/dev/rpathX" +.It Pa /dev/path +.Fa path +with a prefix of +.Dq Pa /dev/ . +.It Pa /dev/path Ns Em X +.Fa path +with a prefix of +.Dq Pa /dev/ +and a suffix of +.Sq Em X +(q.v.). +.El +.El +.Pp +If the above fails, then the original +.Fa path +is tried using the following two variations: +.Pp +.Bl -dash -compact +.It +The +.Fa iscooked +value is ignored: +.Bl -tag -compact -width "/dev/rpathX" +.It Pa path +The pathname as given. +.It Pa path Ns Em X +.Fa path +with a suffix of +.Sq Em X , +where +.Sq Em X +represents the raw partition of the device, as determined by +.Xr getrawpartition 3 , +usually +.Dq c +or +.Dq d . +.El +.El +.Pp +.Fn opendisk1 +is identical to +.Fn opendisk +except uses the supplied +.Fa ofn +function instead of +.Xr open 2 . +This function must be compatible +with +.Xr open 2 +in the parameters it takes, +the value it returns, +and way that errors are indicated. +.Sh RETURN VALUES +An open file descriptor, or -1 if the +.Xr open 2 +failed. +.Sh ERRORS +.Fn opendisk +and +.Fn opendisk1 +may set +.Va errno +to one of the following values: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa buf +was the +.Dv NULL +pointer. +.It Bq Er EINVAL +.Dv O_CREAT +was set in +.Fa flags , +or +.Xr getrawpartition 3 +didn't return a valid partition. +.El +.Pp +The +.Fn opendisk +function +may also set +.Va errno +to any value specified by the +.Xr open 2 +function. +.Pp +The +.Fn opendisk1 +function may also set +.Va errno +to any value set by the +.Fa ofn +function. +.Sh SEE ALSO +.Xr open 2 , +.Xr getrawpartition 3 +.Sh HISTORY +The +.Fn opendisk +function first appeared in +.Nx 1.3 . +.Pp +The +.Fn opendisk1 +function first appeared in +.Nx 6.0 , +and was documented in +.Nx 8.0 . +.Pp +The lookup order of +.Fn opendisk +was changed in +.Nx 7.1 +to first look in +.Pa /dev +in order to avoid opening random files in the current working directory. diff --git a/static/netbsd/man3/openpam.3 b/static/netbsd/man3/openpam.3 new file mode 100644 index 00000000..2a9dd0bb --- /dev/null +++ b/static/netbsd/man3/openpam.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: openpam.3,v 1.13 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM 3 +.Os +.Sh NAME +.Nm openpam_borrow_cred , +.Nm openpam_free_data , +.Nm openpam_free_envlist , +.Nm openpam_get_feature , +.Nm openpam_get_option , +.Nm openpam_log , +.Nm openpam_nullconv , +.Nm openpam_readline , +.Nm openpam_readlinev , +.Nm openpam_readword , +.Nm openpam_restore_cred , +.Nm openpam_set_feature , +.Nm openpam_set_option , +.Nm openpam_straddch , +.Nm openpam_subst , +.Nm openpam_ttyconv , +.Nm pam_error , +.Nm pam_get_authtok , +.Nm pam_info , +.Nm pam_prompt , +.Nm pam_setenv , +.Nm pam_verror , +.Nm pam_vinfo , +.Nm pam_vprompt +.Nd Pluggable Authentication Modules Library +.Sh LIBRARY +.Lb libpam +.Sh SYNOPSIS +.In security/openpam.h +.Ft "int" +.Fn openpam_borrow_cred "pam_handle_t *pamh" "const struct passwd *pwd" +.Ft "void" +.Fn openpam_free_data "pam_handle_t *pamh" "void *data" "int status" +.Ft "void" +.Fn openpam_free_envlist "char **envlist" +.Ft "int" +.Fn openpam_get_feature "int feature" "int *onoff" +.Ft "const char *" +.Fn openpam_get_option "pam_handle_t *pamh" "const char *option" +.Ft "void" +.Fn openpam_log "int level" "const char *fmt" "..." +.Ft "int" +.Fn openpam_nullconv "int n" "const struct pam_message **msg" "struct pam_response **resp" "void *data" +.Ft "char *" +.Fn openpam_readline "FILE *f" "int *lineno" "size_t *lenp" +.Ft "char **" +.Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp" +.Ft "char *" +.Fn openpam_readword "FILE *f" "int *lineno" "size_t *lenp" +.Ft "int" +.Fn openpam_restore_cred "pam_handle_t *pamh" +.Ft "int" +.Fn openpam_set_feature "int feature" "int onoff" +.Ft "int" +.Fn openpam_set_option "pam_handle_t *pamh" "const char *option" "const char *value" +.Ft "int" +.Fn openpam_straddch "char **str" "size_t *size" "size_t *len" "int ch" +.Ft "int" +.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template" +.Ft "int" +.Fn openpam_ttyconv "int n" "const struct pam_message **msg" "struct pam_response **resp" "void *data" +.Ft "int" +.Fn pam_error "const pam_handle_t *pamh" "const char *fmt" "..." +.Ft "int" +.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt" +.Ft "int" +.Fn pam_info "const pam_handle_t *pamh" "const char *fmt" "..." +.Ft "int" +.Fn pam_prompt "const pam_handle_t *pamh" "int style" "char **resp" "const char *fmt" "..." +.Ft "int" +.Fn pam_setenv "pam_handle_t *pamh" "const char *name" "const char *value" "int overwrite" +.Ft "int" +.Fn pam_verror "const pam_handle_t *pamh" "const char *fmt" "va_list ap" +.Ft "int" +.Fn pam_vinfo "const pam_handle_t *pamh" "const char *fmt" "va_list ap" +.Ft "int" +.Fn pam_vprompt "const pam_handle_t *pamh" "int style" "char **resp" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +These functions are OpenPAM extensions to the PAM API. +Those named +.Fn pam_* +are, in the author's opinion, logical and necessary extensions to the +standard API, while those named +.Fn openpam_* +are either simple convenience functions, or functions intimately tied +to OpenPAM implementation details, and therefore not well suited to +standardization. +.Sh SEE ALSO +.Xr openpam_borrow_cred 3 , +.Xr openpam_free_data 3 , +.Xr openpam_free_envlist 3 , +.Xr openpam_get_feature 3 , +.Xr openpam_get_option 3 , +.Xr openpam_log 3 , +.Xr openpam_nullconv 3 , +.Xr openpam_readline 3 , +.Xr openpam_readlinev 3 , +.Xr openpam_readword 3 , +.Xr openpam_restore_cred 3 , +.Xr openpam_set_feature 3 , +.Xr openpam_set_option 3 , +.Xr openpam_straddch 3 , +.Xr openpam_subst 3 , +.Xr openpam_ttyconv 3 , +.Xr pam_error 3 , +.Xr pam_get_authtok 3 , +.Xr pam_info 3 , +.Xr pam_prompt 3 , +.Xr pam_setenv 3 , +.Xr pam_verror 3 , +.Xr pam_vinfo 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The OpenPAM library and this manual page were developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_borrow_cred.3 b/static/netbsd/man3/openpam_borrow_cred.3 new file mode 100644 index 00000000..6ca784db --- /dev/null +++ b/static/netbsd/man3/openpam_borrow_cred.3 @@ -0,0 +1,65 @@ +.\" $NetBSD: openpam_borrow_cred.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_borrow_cred.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_BORROW_CRED 3 +.Os +.Sh NAME +.Nm openpam_borrow_cred +.Nd temporarily borrow user credentials +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_borrow_cred "pam_handle_t *pamh" "const struct passwd *pwd" +.Sh DESCRIPTION +The +.Fn openpam_borrow_cred +function saves the current credentials and +switches to those of the user specified by its +.Fa pwd +argument. +The affected credentials are the effective UID, the effective GID, and +the group access list. +The original credentials can be restored using +.Xr openpam_restore_cred 3 . +.Sh RETURN VALUES +The +.Fn openpam_borrow_cred +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr setegid 2 , +.Xr seteuid 2 , +.Xr setgroups 2 , +.Xr openpam_restore_cred 3 , +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_borrow_cred +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_borrow_cred +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_free_data.3 b/static/netbsd/man3/openpam_free_data.3 new file mode 100644 index 00000000..f9ee09af --- /dev/null +++ b/static/netbsd/man3/openpam_free_data.3 @@ -0,0 +1,47 @@ +.\" $NetBSD: openpam_free_data.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_free_data.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_FREE_DATA 3 +.Os +.Sh NAME +.Nm openpam_free_data +.Nd generic cleanup function +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "void" +.Fn openpam_free_data "pam_handle_t *pamh" "void *data" "int status" +.Sh DESCRIPTION +The +.Fn openpam_free_data +function is a cleanup function suitable for +passing to +.Xr pam_set_data 3 . +It simply releases the data by passing its +.Fa data +argument to +.Xr free 3 . +.Sh SEE ALSO +.Xr free 3 , +.Xr pam 3 , +.Xr pam_set_data 3 +.Sh STANDARDS +The +.Fn openpam_free_data +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_free_data +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_free_envlist.3 b/static/netbsd/man3/openpam_free_envlist.3 new file mode 100644 index 00000000..b60258fc --- /dev/null +++ b/static/netbsd/man3/openpam_free_envlist.3 @@ -0,0 +1,37 @@ +.\" $NetBSD: openpam_free_envlist.3,v 1.11 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_free_envlist.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_FREE_ENVLIST 3 +.Os +.Sh NAME +.Nm openpam_free_envlist +.Nd free an environment list +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "void" +.Fn openpam_free_envlist "char **envlist" +.Sh DESCRIPTION +The +.Fn openpam_free_envlist +function is a convenience function which +frees all the environment variables in an environment list, and the +list itself. +It is suitable for freeing the return value from +.Xr pam_getenvlist 3 . +.Pp +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_getenvlist 3 +.Sh STANDARDS +The +.Fn openpam_free_envlist +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_free_envlist +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_get_feature.3 b/static/netbsd/man3/openpam_get_feature.3 new file mode 100644 index 00000000..25e8d584 --- /dev/null +++ b/static/netbsd/man3/openpam_get_feature.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: openpam_get_feature.3,v 1.9 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_get_feature.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_GET_FEATURE 3 +.Os +.Sh NAME +.Nm openpam_get_feature +.Nd query the state of an optional feature +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_get_feature "int feature" "int *onoff" +.Sh DESCRIPTION +.Bf Sy +This function is experimental and may be modified or removed in a future release without prior warning. +.Ef +.Pp +The +.Fn openpam_get_feature +function stores the current state of the +specified feature in the variable pointed to by its +.Fa onoff +argument. +.Pp +The following features are recognized: +.Bl -tag -width 18n +.It Dv OPENPAM_RESTRICT_SERVICE_NAME +Disallow path separators in service names. +This feature is enabled by default. +Disabling it allows the application to specify the path to +the desired policy file directly. +.It Dv OPENPAM_VERIFY_POLICY_FILE +Verify the ownership and permissions of the policy file +and the path leading up to it. +This feature is enabled by default. +.It Dv OPENPAM_RESTRICT_MODULE_NAME +Disallow path separators in module names. +This feature is disabled by default. +Enabling it prevents the use of modules in non-standard +locations. +.It Dv OPENPAM_VERIFY_MODULE_FILE +Verify the ownership and permissions of each loadable +module and the path leading up to it. +This feature is enabled by default. +.El +.Sh RETURN VALUES +The +.Fn openpam_get_feature +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_FEATURE +Unrecognized or restricted feature. +.El +.Sh SEE ALSO +.Xr openpam_set_feature 3 , +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_get_feature +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_get_feature +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_get_option.3 b/static/netbsd/man3/openpam_get_option.3 new file mode 100644 index 00000000..7518a7f2 --- /dev/null +++ b/static/netbsd/man3/openpam_get_option.3 @@ -0,0 +1,49 @@ +.\" $NetBSD: openpam_get_option.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_get_option.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_GET_OPTION 3 +.Os +.Sh NAME +.Nm openpam_get_option +.Nd returns the value of a module option +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "const char *" +.Fn openpam_get_option "pam_handle_t *pamh" "const char *option" +.Sh DESCRIPTION +The +.Fn openpam_get_option +function returns the value of the specified +option in the context of the currently executing service module, or +.Dv NULL +if the option is not set or no module is currently executing. +.Sh RETURN VALUES +The +.Fn openpam_get_option +function returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr openpam_set_option 3 , +.Xr pam 3 +.Sh STANDARDS +The +.Fn openpam_get_option +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_get_option +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_log.3 b/static/netbsd/man3/openpam_log.3 new file mode 100644 index 00000000..ba64dceb --- /dev/null +++ b/static/netbsd/man3/openpam_log.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: openpam_log.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_log.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_LOG 3 +.Os +.Sh NAME +.Nm openpam_log +.Nd log a message through syslog +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "void" +.Fn openpam_log "int level" "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn openpam_log +function logs messages using +.Xr syslog 3 . +It is primarily intended for internal use by the library and modules. +.Pp +The +.Fa level +argument indicates the importance of the message. +The following levels are defined: +.Bl -tag -width 18n +.It Dv PAM_LOG_LIBDEBUG +Debugging messages. +For internal use only. +.It Dv PAM_LOG_DEBUG +Debugging messages. +These messages are normally not logged unless the global +integer variable +.Va openpam_debug +is set to a non-zero +value, in which case they are logged with a +.Xr syslog 3 +priority of +.Dv LOG_DEBUG . +.It Dv PAM_LOG_VERBOSE +Information about the progress of the authentication +process, or other non-essential messages. +These messages are logged with a +.Xr syslog 3 +priority of +.Dv LOG_INFO . +.It Dv PAM_LOG_NOTICE +Messages relating to non-fatal errors. +These messages are logged with a +.Xr syslog 3 +priority of +.Dv LOG_NOTICE . +.It Dv PAM_LOG_ERROR +Messages relating to serious errors. +These messages are logged with a +.Xr syslog 3 +priority of +.Dv LOG_ERR . +.El +.Pp +The remaining arguments are a +.Xr printf 3 +format string and the +corresponding arguments. +.Pp +The +.Fn openpam_log +function does not modify the value of +.Va errno . +.Sh SEE ALSO +.Xr pam 3 , +.Xr printf 3 , +.Xr syslog 3 +.Sh STANDARDS +The +.Fn openpam_log +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_log +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_nullconv.3 b/static/netbsd/man3/openpam_nullconv.3 new file mode 100644 index 00000000..71ff6f67 --- /dev/null +++ b/static/netbsd/man3/openpam_nullconv.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: openpam_nullconv.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_nullconv.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_NULLCONV 3 +.Os +.Sh NAME +.Nm openpam_nullconv +.Nd null conversation function +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_nullconv "int n" "const struct pam_message **msg" "struct pam_response **resp" "void *data" +.Sh DESCRIPTION +The +.Fn openpam_nullconv +function is a null conversation function suitable +for applications that want to use PAM but don't support interactive +dialog with the user. +Such applications should set +.Dv PAM_AUTHTOK +to whatever authentication +token they've obtained on their own before calling +.Xr pam_authenticate 3 +and / or +.Xr pam_chauthtok 3 , +and their PAM configuration should specify the +.Dv use_first_pass +option for all modules that require access to the +authentication token, to make sure they use +.Dv PAM_AUTHTOK +rather than try to query the user. +.Sh RETURN VALUES +The +.Fn openpam_nullconv +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.El +.Sh SEE ALSO +.Xr openpam_ttyconv 3 , +.Xr pam 3 , +.Xr pam_authenticate 3 , +.Xr pam_chauthtok 3 , +.Xr pam_prompt 3 , +.Xr pam_set_item 3 , +.Xr pam_strerror 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +The +.Fn openpam_nullconv +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_nullconv +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_readline.3 b/static/netbsd/man3/openpam_readline.3 new file mode 100644 index 00000000..6393f646 --- /dev/null +++ b/static/netbsd/man3/openpam_readline.3 @@ -0,0 +1,90 @@ +.\" $NetBSD: openpam_readline.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_readline.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_READLINE 3 +.Os +.Sh NAME +.Nm openpam_readline +.Nd read a line from a file +.Sh SYNOPSIS +.In sys/types.h +.In stdio.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "char *" +.Fn openpam_readline "FILE *f" "int *lineno" "size_t *lenp" +.Sh DESCRIPTION +.Bf Sy +This function is deprecated and may be removed in a future release without further warning. +The +.Fn openpam_readlinev +function may be used to achieve similar results. +.Ef +.Pp +The +.Fn openpam_readline +function reads a line from a file, and returns it +in a NUL-terminated buffer allocated with +.Xr malloc 3 . +.Pp +The +.Fn openpam_readline +function performs a certain amount of processing +on the data it reads: +.Bl -bullet +.It +Comments (introduced by a hash sign) are stripped. +.It +Blank lines are ignored. +.It +If a line ends in a backslash, the backslash is stripped and the +next line is appended. +.El +.Pp +If +.Fa lineno +is not +.Dv NULL , +the integer variable it points to is +incremented every time a newline character is read. +.Pp +If +.Fa lenp +is not +.Dv NULL , +the length of the line (not including the +terminating NUL character) is stored in the variable it points to. +.Pp +The caller is responsible for releasing the returned buffer by passing +it to +.Xr free 3 . +.Pp +.Sh RETURN VALUES +The +.Fn openpam_readline +function returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr openpam_readlinev 3 , +.Xr openpam_readword 3 , +.Xr pam 3 +.Sh STANDARDS +The +.Fn openpam_readline +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_readline +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_readlinev.3 b/static/netbsd/man3/openpam_readlinev.3 new file mode 100644 index 00000000..e72a0477 --- /dev/null +++ b/static/netbsd/man3/openpam_readlinev.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: openpam_readlinev.3,v 1.9 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_readlinev.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_READLINEV 3 +.Os +.Sh NAME +.Nm openpam_readlinev +.Nd read a line from a file and split it into words +.Sh SYNOPSIS +.In sys/types.h +.In stdio.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "char **" +.Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp" +.Sh DESCRIPTION +The +.Fn openpam_readlinev +function reads a line from a file, splits it +into words according to the rules described in the +.Xr openpam_readword 3 +manual page, and returns a list of those words. +.Pp +If +.Fa lineno +is not +.Dv NULL , +the integer variable it points to is +incremented every time a newline character is read. +This includes quoted or escaped newline characters and the newline +character at the end of the line. +.Pp +If +.Fa lenp +is not +.Dv NULL , +the number of words on the line is stored in the +variable to which it points. +.Sh RETURN VALUES +If successful, the +.Fn openpam_readlinev +function returns a pointer to a +dynamically allocated array of pointers to individual dynamically +allocated NUL-terminated strings, each containing a single word, in the +order in which they were encountered on the line. +The array is terminated by a +.Dv NULL +pointer. +.Pp +The caller is responsible for freeing both the array and the individual +strings by passing each of them to +.Xr free 3 . +.Pp +If the end of the line was reached before any words were read, +.Fn openpam_readlinev +returns a pointer to a dynamically allocated array +containing a single +.Dv NULL +pointer. +.Pp +The +.Fn openpam_readlinev +function can fail and return +.Dv NULL +for one of +four reasons: +.Bl -bullet +.It +The end of the file was reached before any words were read; +.Va errno +is +zero, +.Xr ferror 3 +returns zero, and +.Xr feof 3 +returns a non-zero value. +.It +The end of the file was reached while a quote or backslash escape +was in effect; +.Va errno +is set to +.Dv EINVAL , +.Xr ferror 3 +returns zero, and +.Xr feof 3 +returns a non-zero value. +.It +An error occurred while reading from the file; +.Va errno +is non-zero, +.Xr ferror 3 +returns a non-zero value and +.Xr feof 3 +returns zero. +.It +A +.Xr malloc 3 +or +.Xr realloc 3 +call failed; +.Va errno +is set to +.Dv ENOMEM , +.Xr ferror 3 +returns a non-zero value, and +.Xr feof 3 +may or may not return +a non-zero value. +.El +.Sh SEE ALSO +.Xr openpam_readline 3 , +.Xr openpam_readword 3 , +.Xr pam 3 +.Sh STANDARDS +The +.Fn openpam_readlinev +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_readlinev +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_readword.3 b/static/netbsd/man3/openpam_readword.3 new file mode 100644 index 00000000..20f46203 --- /dev/null +++ b/static/netbsd/man3/openpam_readword.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: openpam_readword.3,v 1.9 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_readword.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_READWORD 3 +.Os +.Sh NAME +.Nm openpam_readword +.Nd read a word from a file, respecting shell quoting rules +.Sh SYNOPSIS +.In sys/types.h +.In stdio.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "char *" +.Fn openpam_readword "FILE *f" "int *lineno" "size_t *lenp" +.Sh DESCRIPTION +The +.Fn openpam_readword +function reads the next word from a file, and +returns it in a NUL-terminated buffer allocated with +.Xr malloc 3 . +.Pp +A word is a sequence of non-whitespace characters. +However, whitespace characters can be included in a word if quoted or +escaped according to the following rules: +.Bl -bullet +.It +An unescaped single or double quote introduces a quoted string, +which ends when the same quote character is encountered a second +time. +The quotes themselves are stripped. +.It +Within a single- or double-quoted string, all whitespace characters, +including the newline character, are preserved as-is. +.It +Outside a quoted string, a backslash escapes the next character, +which is preserved as-is, unless that character is a newline, in +which case it is discarded and reading continues at the beginning of +the next line as if the backslash and newline had not been there. +In all cases, the backslash itself is discarded. +.It +Within a single-quoted string, double quotes and backslashes are +preserved as-is. +.It +Within a double-quoted string, a single quote is preserved as-is, +and a backslash is preserved as-is unless used to escape a double +quote. +.El +.Pp +In addition, if the first non-whitespace character on the line is a +hash character (#), the rest of the line is discarded. +If a hash character occurs within a word, however, it is preserved +as-is. +A backslash at the end of a comment does cause line continuation. +.Pp +If +.Fa lineno +is not +.Dv NULL , +the integer variable it points to is +incremented every time a quoted or escaped newline character is read. +.Pp +If +.Fa lenp +is not +.Dv NULL , +the length of the word (after quotes and +backslashes have been removed) is stored in the variable it points to. +.Sh RETURN VALUES +If successful, the +.Fn openpam_readword +function returns a pointer to a +dynamically allocated NUL-terminated string containing the first word +encountered on the line. +.Pp +The caller is responsible for releasing the returned buffer by passing +it to +.Xr free 3 . +.Pp +If +.Fn openpam_readword +reaches the end of the line or file before any +characters are copied to the word, it returns +.Dv NULL . +In the former +case, the newline is pushed back to the file. +.Pp +If +.Fn openpam_readword +reaches the end of the file while a quote or +backslash escape is in effect, it sets +.Va errno +to +.Dv EINVAL +and returns +.Dv NULL . +.Sh IMPLEMENTATION NOTES +The parsing rules are intended to be equivalent to the normal POSIX +shell quoting rules. +Any discrepancy is a bug and should be reported to the author along +with sample input that can be used to reproduce the error. +.Pp +.Sh SEE ALSO +.Xr openpam_readline 3 , +.Xr openpam_readlinev 3 , +.Xr pam 3 +.Sh STANDARDS +The +.Fn openpam_readword +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_readword +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_restore_cred.3 b/static/netbsd/man3/openpam_restore_cred.3 new file mode 100644 index 00000000..d8d60bc0 --- /dev/null +++ b/static/netbsd/man3/openpam_restore_cred.3 @@ -0,0 +1,57 @@ +.\" $NetBSD: openpam_restore_cred.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_restore_cred.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_RESTORE_CRED 3 +.Os +.Sh NAME +.Nm openpam_restore_cred +.Nd restore credentials +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_restore_cred "pam_handle_t *pamh" +.Sh DESCRIPTION +The +.Fn openpam_restore_cred +function restores the credentials saved by +.Xr openpam_borrow_cred 3 . +.Sh RETURN VALUES +The +.Fn openpam_restore_cred +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_NO_MODULE_DATA +Module data not found. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr setegid 2 , +.Xr seteuid 2 , +.Xr setgroups 2 , +.Xr openpam_borrow_cred 3 , +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_restore_cred +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_restore_cred +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_set_feature.3 b/static/netbsd/man3/openpam_set_feature.3 new file mode 100644 index 00000000..29c7e23d --- /dev/null +++ b/static/netbsd/man3/openpam_set_feature.3 @@ -0,0 +1,54 @@ +.\" $NetBSD: openpam_set_feature.3,v 1.9 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_set_feature.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_SET_FEATURE 3 +.Os +.Sh NAME +.Nm openpam_set_feature +.Nd enable or disable an optional feature +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_set_feature "int feature" "int onoff" +.Sh DESCRIPTION +.Bf Sy +This function is experimental and may be modified or removed in a future release without prior warning. +.Ef +.Pp +The +.Fn openpam_set_feature +function sets the state of the specified +feature to the value specified by the +.Fa onoff +argument. +See +.Xr openpam_get_feature 3 +for a list of recognized features. +.Pp +.Sh RETURN VALUES +The +.Fn openpam_set_feature +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_FEATURE +Unrecognized or restricted feature. +.El +.Sh SEE ALSO +.Xr openpam_get_feature 3 , +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_set_feature +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_set_feature +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_set_option.3 b/static/netbsd/man3/openpam_set_option.3 new file mode 100644 index 00000000..cad372a5 --- /dev/null +++ b/static/netbsd/man3/openpam_set_option.3 @@ -0,0 +1,54 @@ +.\" $NetBSD: openpam_set_option.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_set_option.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_SET_OPTION 3 +.Os +.Sh NAME +.Nm openpam_set_option +.Nd sets the value of a module option +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_set_option "pam_handle_t *pamh" "const char *option" "const char *value" +.Sh DESCRIPTION +The +.Fn openpam_set_option +function sets the specified option in the +context of the currently executing service module. +.Sh RETURN VALUES +The +.Fn openpam_set_option +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr openpam_get_option 3 , +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_set_option +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_set_option +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_straddch.3 b/static/netbsd/man3/openpam_straddch.3 new file mode 100644 index 00000000..6d79cbc0 --- /dev/null +++ b/static/netbsd/man3/openpam_straddch.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: openpam_straddch.3,v 1.9 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_straddch.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_STRADDCH 3 +.Os +.Sh NAME +.Nm openpam_straddch +.Nd add a character to a string, expanding the buffer if needed +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_straddch "char **str" "size_t *size" "size_t *len" "int ch" +.Sh DESCRIPTION +The +.Fn openpam_straddch +function appends a character to a dynamically +allocated NUL-terminated buffer, reallocating the buffer as needed. +.Pp +The +.Fa str +argument points to a variable containing either a pointer to +an existing buffer or +.Dv NULL . +If the value of the variable pointed to by +.Fa str +is +.Dv NULL , +a new buffer +is allocated. +.Pp +The +.Fa size +and +.Fa len +argument point to variables used to hold the size +of the buffer and the length of the string it contains, respectively. +.Pp +The final argument, +.Fa ch , +is the character that should be appended to +the string. If +.Fa ch +is 0, nothing is appended, but a new buffer is +still allocated if +.Fa str +is NULL. This can be used to +.Do +bootstrap +.Dc +the +string. +.Pp +If a new buffer is allocated or an existing buffer is reallocated to +make room for the additional character, +.Fa str +and +.Fa size +are updated +accordingly. +.Pp +The +.Fn openpam_straddch +function ensures that the buffer is always +NUL-terminated. +.Pp +If the +.Fn openpam_straddch +function is successful, it increments the +integer variable pointed to by +.Fa len +(unless +.Fa ch +was 0) and returns 0. +Otherwise, it leaves the variables pointed to by +.Fa str , +.Fa size +and +.Fa len +unmodified, sets +.Va errno +to +.Dv ENOMEM +and returns -1. +.Pp +.Sh RETURN VALUES +The +.Fn openpam_straddch +function returns 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_straddch +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_straddch +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_subst.3 b/static/netbsd/man3/openpam_subst.3 new file mode 100644 index 00000000..815f755a --- /dev/null +++ b/static/netbsd/man3/openpam_subst.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: openpam_subst.3,v 1.11 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_subst.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_SUBST 3 +.Os +.Sh NAME +.Nm openpam_subst +.Nd substitute PAM item values in a string +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template" +.Sh DESCRIPTION +The +.Fn openpam_subst +function expands a string, substituting PAM item +values for all occurrences of specific substitution codes. +The +.Fa template +argument points to the initial string. +The result is stored in the buffer pointed to by the +.Fa buf +argument; the +.Fa bufsize +argument specifies the size of that buffer. +The actual size of the resulting string, including the terminating NUL +character, is stored in the location pointed to by the +.Fa bufsize +argument. +.Pp +If +.Fa buf +is NULL, or if the buffer is too small to hold the expanded +string, +.Fa bufsize +is updated to reflect the amount of space required to +hold the entire string, and +.Fn openpam_subst +returns +.Dv PAM_TRY_AGAIN . +.Pp +If +.Fn openpam_subst +fails for any other reason, the +.Fa bufsize +argument is +untouched, but part of the buffer may still have been overwritten. +.Pp +Substitution codes are introduced by a percent character and correspond +to PAM items: +.Bl -tag -width 18n +.It \&%H +Replaced by the current value of the +.Dv PAM_RHOST +item. +.It \&%h +Replaced by the current value of the +.Dv PAM_HOST +item. +.It \&%s +Replaced by the current value of the +.Dv PAM_SERVICE +item. +.It \&%t +Replaced by the current value of the +.Dv PAM_TTY +item. +.It \&%U +Replaced by the current value of the +.Dv PAM_RUSER +item. +.It \&%u +Replaced by the current value of the +.Dv PAM_USER +item. +.El +.Sh RETURN VALUES +The +.Fn openpam_subst +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_TRY_AGAIN +Try again. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_get_authtok 3 , +.Xr pam_get_item 3 , +.Xr pam_get_user 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn openpam_subst +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_subst +function and this manual page were +developed by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpam_ttyconv.3 b/static/netbsd/man3/openpam_ttyconv.3 new file mode 100644 index 00000000..e10c79fd --- /dev/null +++ b/static/netbsd/man3/openpam_ttyconv.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: openpam_ttyconv.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from openpam_ttyconv.c by gendoc.pl +.Dd May 31, 2025 +.Dt OPENPAM_TTYCONV 3 +.Os +.Sh NAME +.Nm openpam_ttyconv +.Nd simple tty-based conversation function +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/openpam.h +.Ft "int" +.Fn openpam_ttyconv "int n" "const struct pam_message **msg" "struct pam_response **resp" "void *data" +.Sh DESCRIPTION +The +.Fn openpam_ttyconv +function is a standard conversation function +suitable for use on TTY devices. +It should be adequate for the needs of most text-based interactive +programs. +.Pp +The +.Fn openpam_ttyconv +function allows the application to specify a +timeout for user input by setting the global integer variable +.Va openpam_ttyconv_timeout +to the length of the timeout in seconds. +.Pp +.Sh RETURN VALUES +The +.Fn openpam_ttyconv +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr getpass 3 , +.Xr openpam_nullconv 3 , +.Xr pam 3 , +.Xr pam_prompt 3 , +.Xr pam_strerror 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +The +.Fn openpam_ttyconv +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn openpam_ttyconv +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/openpty.3 b/static/netbsd/man3/openpty.3 new file mode 100644 index 00000000..f0c54051 --- /dev/null +++ b/static/netbsd/man3/openpty.3 @@ -0,0 +1,178 @@ +.\" $NetBSD: openpty.3,v 1.17 2012/07/27 21:33:46 christos Exp $ +.\" +.\" Copyright (c) 1995 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 27, 2012 +.Dt OPENPTY 3 +.Os +.Sh NAME +.Nm openpty , +.Nm login_tty , +.Nm forkpty +.Nd tty utility functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp" +.Ft int +.Fn login_tty "int fd" +.Ft pid_t +.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp" +.Sh DESCRIPTION +The +.Fn openpty , +.Fn login_tty , +and +.Fn forkpty +functions perform manipulations on ttys and pseudo-ttys. +.Pp +The +.Fn openpty +function finds an available pseudo-tty and returns file descriptors +for the master and slave in +.Fa amaster +and +.Fa aslave . +If +.Fa name +is non-null, the filename of the slave is returned in +.Fa name . +The length of +.Fa name +is limited to +.Dv PATH_MAX +as any other regular path name, so a buffer of this size should be used. +.\" .Dv 16 +.\" characters in the current +.\" .Xr ptm 4 +.\" device driver (including the terminating +.\" .Dv NUL ) +.\" which limits the maximum to +.\" .Dv 100,000 +.\" ptys. +If +.Fa termp +is non-null, the terminal parameters of the slave will be set to the +values in +.Fa termp . +If +.Fa winp +is non-null, the window size of the slave will be set to the values in +.Fa winp . +.Pp +The +.Fn login_tty +function prepares for a login on the tty +.Fa fd +(which may be a real tty device, or the slave of a pseudo-tty as +returned by +.Fn openpty ) +by creating a new session, making +.Fa fd +the controlling terminal for the current process, setting +.Fa fd +to be the standard input, output, and error streams of the current +process, and closing +.Fa fd . +.Pp +The +.Fn forkpty +function combines +.Fn openpty , +.Fn fork , +and +.Fn login_tty +to create a new process operating in a pseudo-tty. +The file descriptor of the master side of the pseudo-tty is returned +(to the parent process only) in +.Fa amaster . +The filename of the slave is returned (to both the parent and child +processes) in +.Fa name +if +.Fa name +is non-null. +The +.Fa termp +and +.Fa winp +parameters, if non-null, will determine the terminal attributes and +window size of the slave side of the pseudo-tty. +.Sh RETURN VALUES +If a call to +.Fn openpty , +.Fn login_tty , +or +.Fn forkpty +is not successful, -1 is returned and +.Va errno +is set to indicate the error. +Otherwise, +.Fn openpty , +.Fn login_tty , +and the child process of +.Fn forkpty +return 0, and the parent process of +.Fn forkpty +returns the process ID of the child process. +.Sh FILES +.Bl -tag -width /dev/[pt]ty[p-zP-T][0-9a-zA-Z] -compact +.It Pa /dev/[pt]ty[p-zP-T][0-9a-zA-Z] +.El +.Sh ERRORS +.Fn openpty +will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +There are no available ttys. +.It Bq Er EPERM +The caller was not the superuser and the +.Xr ptm 4 +device is missing or not configured. +.El +.Pp +.Fn login_tty +will fail if +.Fn ioctl +fails to set +.Fa fd +to the controlling terminal of the current process. +.Fn forkpty +will fail if either +.Fn openpty +or +.Fn fork +fails. +.Sh SEE ALSO +.Xr fork 2 diff --git a/static/netbsd/man3/openssl-DES_random_key.3 b/static/netbsd/man3/openssl-DES_random_key.3 new file mode 100644 index 00000000..0289e6e1 --- /dev/null +++ b/static/netbsd/man3/openssl-DES_random_key.3 @@ -0,0 +1,391 @@ +.\" $NetBSD: openssl-DES_random_key.3,v 1.2 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "DES_random_key 3" +.TH DES_random_key 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, +DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, +DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, +DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, +DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, +DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, +DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, +DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, +DES_fcrypt, DES_crypt \- DES encryption +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/des.h> +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& void DES_random_key(DES_cblock *ret); +\& +\& int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_set_key_checked(const_DES_cblock *key, DES_key_schedule *schedule); +\& void DES_set_key_unchecked(const_DES_cblock *key, DES_key_schedule *schedule); +\& +\& void DES_set_odd_parity(DES_cblock *key); +\& int DES_is_weak_key(const_DES_cblock *key); +\& +\& void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks, int enc); +\& void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); +\& void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, +\& DES_key_schedule *ks3, int enc); +\& +\& void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec, int enc); +\& void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec); +\& void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num, int enc); +\& void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num); +\& +\& void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& const_DES_cblock *inw, const_DES_cblock *outw, int enc); +\& +\& void DES_ede2_cbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int enc); +\& void DES_ede2_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, +\& int *num, int enc); +\& void DES_ede2_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int *num); +\& +\& void DES_ede3_cbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int enc); +\& void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int *num, int enc); +\& void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int *num); +\& +\& DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, +\& long length, DES_key_schedule *schedule, +\& const_DES_cblock *ivec); +\& DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], +\& long length, int out_count, DES_cblock *seed); +\& void DES_string_to_key(const char *str, DES_cblock *key); +\& void DES_string_to_2keys(const char *str, DES_cblock *key1, DES_cblock *key2); +\& +\& char *DES_fcrypt(const char *buf, const char *salt, char *ret); +\& char *DES_crypt(const char *buf, const char *salt); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. Applications should +instead use \fBEVP_EncryptInit_ex\fR\|(3), \fBEVP_EncryptUpdate\fR\|(3) and +\&\fBEVP_EncryptFinal_ex\fR\|(3) or the equivalently named decrypt functions. +.PP +This library contains a fast implementation of the DES encryption +algorithm. +.PP +There are two phases to the use of DES encryption. The first is the +generation of a \fIDES_key_schedule\fR from a key, the second is the +actual encryption. A DES key is of type \fIDES_cblock\fR. This type +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. +.PP +\&\fBDES_random_key()\fR generates a random key. The random generator must be +seeded when calling this function. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see \fBRAND\fR\|(7)), the operation will fail. +If the function fails, 0 is returned. +.PP +Before a DES key can be used, it must be converted into the +architecture dependent \fIDES_key_schedule\fR via the +\&\fBDES_set_key_checked()\fR or \fBDES_set_key_unchecked()\fR function. +.PP +\&\fBDES_set_key_checked()\fR will check that the key passed is of odd parity +and is not a weak or semi\-weak key. If the parity is wrong, then \-1 +is returned. If the key is a weak key, then \-2 is returned. If an +error is returned, the key schedule is not generated. +.PP +\&\fBDES_set_key()\fR works like \fBDES_set_key_checked()\fR and remains for +backward compatibility. +.PP +\&\fBDES_set_odd_parity()\fR sets the parity of the passed \fIkey\fR to odd. +.PP +\&\fBDES_is_weak_key()\fR returns 1 if the passed key is a weak key, 0 if it +is ok. +.PP +The following routines mostly operate on an input and output stream of +\&\fIDES_cblock\fRs. +.PP +\&\fBDES_ecb_encrypt()\fR is the basic DES encryption routine that encrypts or +decrypts a single 8\-byte \fIDES_cblock\fR in \fIelectronic code book\fR +(ECB) mode. It always transforms the input data, pointed to by +\&\fIinput\fR, into the output data, pointed to by the \fIoutput\fR argument. +If the \fIencrypt\fR argument is nonzero (DES_ENCRYPT), the \fIinput\fR +(cleartext) is encrypted in to the \fIoutput\fR (ciphertext) using the +key_schedule specified by the \fIschedule\fR argument, previously set via +\&\fIDES_set_key\fR. If \fIencrypt\fR is zero (DES_DECRYPT), the \fIinput\fR (now +ciphertext) is decrypted into the \fIoutput\fR (now cleartext). Input +and output may overlap. \fBDES_ecb_encrypt()\fR does not return a value. +.PP +\&\fBDES_ecb3_encrypt()\fR encrypts/decrypts the \fIinput\fR block by using +three\-key Triple\-DES encryption in ECB mode. This involves encrypting +the input with \fIks1\fR, decrypting with the key schedule \fIks2\fR, and +then encrypting with \fIks3\fR. This routine greatly reduces the chances +of brute force breaking of DES and has the advantage of if \fIks1\fR, +\&\fIks2\fR and \fIks3\fR are the same, it is equivalent to just encryption +using ECB mode and \fIks1\fR as the key. +.PP +The macro \fBDES_ecb2_encrypt()\fR is provided to perform two\-key Triple\-DES +encryption by using \fIks1\fR for the final encryption. +.PP +\&\fBDES_ncbc_encrypt()\fR encrypts/decrypts using the \fIcipher\-block\-chaining\fR +(CBC) mode of DES. If the \fIencrypt\fR argument is nonzero, the +routine cipher\-block\-chain encrypts the cleartext data pointed to by +the \fIinput\fR argument into the ciphertext pointed to by the \fIoutput\fR +argument, using the key schedule provided by the \fIschedule\fR argument, +and initialization vector provided by the \fIivec\fR argument. If the +\&\fIlength\fR argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. +.PP +\&\fBDES_xcbc_encrypt()\fR is RSA\*(Aqs DESX mode of DES. It uses \fIinw\fR and +\&\fIoutw\fR to \*(Aqwhiten\*(Aq the encryption. \fIinw\fR and \fIoutw\fR are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than CBC DES. +.PP +\&\fBDES_ede3_cbc_encrypt()\fR implements outer triple CBC DES encryption with +three keys. This means that each DES operation inside the CBC mode is +\&\f(CW\*(C`C=E(ks3,D(ks2,E(ks1,M)))\*(C'\fR. This mode is used by SSL. +.PP +The \fBDES_ede2_cbc_encrypt()\fR macro implements two\-key Triple\-DES by +reusing \fIks1\fR for the final encryption. \f(CW\*(C`C=E(ks1,D(ks2,E(ks1,M)))\*(C'\fR. +This form of Triple\-DES is used by the RSAREF library. +.PP +\&\fBDES_pcbc_encrypt()\fR encrypts/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +\&\fBDES_ncbc_encrypt()\fR. +.PP +\&\fBDES_cfb_encrypt()\fR encrypts/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs an array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per \fInumbits\fR, this function is only +suggested for use when sending a small number of characters. +.PP +\&\fBDES_cfb64_encrypt()\fR +implements CFB mode of DES with 64\-bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, without 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains \*(Aqhow far\*(Aq we are though ivec. If this does +not make much sense, read more about CFB mode of DES. +.PP +\&\fBDES_ede3_cfb64_encrypt()\fR and \fBDES_ede2_cfb64_encrypt()\fR is the same as +\&\fBDES_cfb64_encrypt()\fR except that Triple\-DES is used. +.PP +\&\fBDES_ofb_encrypt()\fR encrypts using output feedback mode. This method +takes an array of characters as input and outputs an array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per \fInumbits\fR, this function is only +suggested for use when sending a small number of characters. +.PP +\&\fBDES_ofb64_encrypt()\fR is the same as \fBDES_cfb64_encrypt()\fR using Output +Feed Back mode. +.PP +\&\fBDES_ede3_ofb64_encrypt()\fR and \fBDES_ede2_ofb64_encrypt()\fR is the same as +\&\fBDES_ofb64_encrypt()\fR, using Triple\-DES. +.PP +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. +.PP +\&\fBDES_cbc_cksum()\fR produces an 8 byte checksum based on the input stream +(via CBC encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in \fIoutput\fR. This function is +used by Kerberos v4. Other applications should use +\&\fBEVP_DigestInit\fR\|(3) etc. instead. +.PP +\&\fBDES_quad_cksum()\fR is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on \fIout_count\fR, 1, 2, 3 or 4 times. If \fIoutput\fR is +non\-NULL, the 8 bytes generated by each pass are written into +\&\fIoutput\fR. +.PP +The following are DES\-based transformations: +.PP +\&\fBDES_fcrypt()\fR is a fast version of the Unix \fBcrypt\fR\|(3) function. This +version takes only a small amount of space relative to other fast +\&\fBcrypt()\fR implementations. This is different to the normal \fBcrypt()\fR in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal \fBcrypt()\fR. +.PP +\&\fBDES_crypt()\fR is a faster replacement for the normal system \fBcrypt()\fR. +This function calls \fBDES_fcrypt()\fR with a static array passed as the +third parameter. This mostly emulates the normal non\-thread\-safe semantics +of \fBcrypt\fR\|(3). +The \fBsalt\fR must be two ASCII characters. +.PP +The values returned by \fBDES_fcrypt()\fR and \fBDES_crypt()\fR are terminated by NUL +character. +.PP +\&\fBDES_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from +buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default) +using \fIsched\fR for the key and \fIiv\fR as a starting vector. The actual +data send down \fIfd\fR consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. +.SH BUGS +.IX Header "BUGS" +\&\fBDES_cbc_encrypt()\fR does not modify \fBivec\fR; use \fBDES_ncbc_encrypt()\fR +instead. +.PP +\&\fBDES_cfb_encrypt()\fR and \fBDES_ofb_encrypt()\fR operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! +.PP +\&\fBDES_string_to_key()\fR is available for backward compatibility with the +MIT library. New applications should use a cryptographic hash function. +The same applies for \fBDES_string_to_2key()\fR. +.SH NOTES +.IX Header "NOTES" +The \fBdes\fR library was written to be source code compatible with +the MIT Kerberos library. +.PP +Applications should use the higher level functions +\&\fBEVP_EncryptInit\fR\|(3) etc. instead of calling these +functions directly. +.PP +Single\-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see \fBdes_modes\fR\|(7). +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBDES_set_key()\fR, \fBDES_key_sched()\fR, and \fBDES_set_key_checked()\fR +return 0 on success or negative values on error. +.PP +\&\fBDES_is_weak_key()\fR returns 1 if the passed key is a weak key, 0 if it +is ok. +.PP +\&\fBDES_cbc_cksum()\fR and \fBDES_quad_cksum()\fR return 4\-byte integer representing the +last 4 bytes of the checksum of the input. +.PP +\&\fBDES_fcrypt()\fR returns a pointer to the caller\-provided buffer and \fBDES_crypt()\fR \- +to a static buffer on success; otherwise they return NULL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBdes_modes\fR\|(7), +\&\fBEVP_EncryptInit\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.PP +The requirement that the \fBsalt\fR parameter to \fBDES_crypt()\fR and \fBDES_fcrypt()\fR +be two ASCII characters was first enforced in +OpenSSL 1.1.0. Previous versions tried to use the letter uppercase \fBA\fR +if both character were not present, and could crash when given non\-ASCII +on some platforms. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl-HMAC.3 b/static/netbsd/man3/openssl-HMAC.3 new file mode 100644 index 00000000..e01043bd --- /dev/null +++ b/static/netbsd/man3/openssl-HMAC.3 @@ -0,0 +1,234 @@ +.\" $NetBSD: openssl-HMAC.3,v 1.2 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "HMAC 3" +.TH HMAC 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +HMAC, +HMAC_CTX_new, +HMAC_CTX_reset, +HMAC_CTX_free, +HMAC_Init, +HMAC_Init_ex, +HMAC_Update, +HMAC_Final, +HMAC_CTX_copy, +HMAC_CTX_set_flags, +HMAC_CTX_get_md, +HMAC_size +\&\- HMAC message authentication code +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/hmac.h> +\& +\& unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len, +\& const unsigned char *data, size_t data_len, +\& unsigned char *md, unsigned int *md_len); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& HMAC_CTX *HMAC_CTX_new(void); +\& int HMAC_CTX_reset(HMAC_CTX *ctx); +\& +\& int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, +\& const EVP_MD *md, ENGINE *impl); +\& int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len); +\& int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); +\& +\& void HMAC_CTX_free(HMAC_CTX *ctx); +\& +\& int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); +\& void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); +\& const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); +\& +\& size_t HMAC_size(const HMAC_CTX *e); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, +\& const EVP_MD *md); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. +.PP +\&\fBHMAC()\fR computes the message authentication code of the \fIdata_len\fR bytes at +\&\fIdata\fR using the hash function \fIevp_md\fR and the key \fIkey\fR which is +\&\fIkey_len\fR bytes long. The \fIkey\fR may also be NULL with \fIkey_len\fR being 0. +.PP +It places the result in \fImd\fR (which must have space for the output of +the hash function, which is no more than \fBEVP_MAX_MD_SIZE\fR bytes). +If \fImd\fR is NULL, the digest is placed in a static array. The size of +the output is placed in \fImd_len\fR, unless it is NULL. Note: passing a NULL +value for \fImd\fR to use the static array is not thread safe. +.PP +\&\fIevp_md\fR is a message digest such as \fBEVP_sha1()\fR, \fBEVP_ripemd160()\fR etc. +HMAC does not support variable output length digests such as \fBEVP_shake128()\fR and +\&\fBEVP_shake256()\fR. +.PP +\&\fBHMAC()\fR uses the default \fBOSSL_LIB_CTX\fR. +Use \fBEVP_Q_mac\fR\|(3) instead if a library context is required. +.PP +All of the functions described below are deprecated. +Applications should instead use \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), +\&\fBEVP_MAC_init\fR\|(3), \fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) +or the \*(Aqquick\*(Aq single\-shot MAC function \fBEVP_Q_mac\fR\|(3). +.PP +\&\fBHMAC_CTX_new()\fR creates a new HMAC_CTX in heap memory. +.PP +\&\fBHMAC_CTX_reset()\fR clears an existing \fBHMAC_CTX\fR and associated +resources, making it suitable for new computations as if it was newly +created with \fBHMAC_CTX_new()\fR. +.PP +\&\fBHMAC_CTX_free()\fR erases the key and other data from the \fBHMAC_CTX\fR, +releases any associated resources and finally frees the \fBHMAC_CTX\fR +itself. If the argument is NULL, nothing is done. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBHMAC_Init_ex()\fR initializes or reuses a \fBHMAC_CTX\fR structure to use the hash +function \fIevp_md\fR and key \fIkey\fR. If both are NULL, or if \fIkey\fR is NULL +and \fIevp_md\fR is the same as the previous call, then the +existing key is +reused. \fIctx\fR must have been created with \fBHMAC_CTX_new()\fR before the first use +of an \fBHMAC_CTX\fR in this function. +.PP +If \fBHMAC_Init_ex()\fR is called with \fIkey\fR NULL and \fIevp_md\fR is not the +same as the previous digest used by \fIctx\fR then an error is returned +because reuse of an existing key with a different digest is not supported. +.PP +\&\fBHMAC_Init()\fR initializes a \fBHMAC_CTX\fR structure to use the hash +function \fIevp_md\fR and the key \fIkey\fR which is \fIkey_len\fR bytes +long. +.PP +\&\fBHMAC_Update()\fR can be called repeatedly with chunks of the message to +be authenticated (\fIlen\fR bytes at \fIdata\fR). +.PP +\&\fBHMAC_Final()\fR places the message authentication code in \fImd\fR, which +must have space for the hash function output. +.PP +\&\fBHMAC_CTX_copy()\fR copies all of the internal state from \fIsctx\fR into \fIdctx\fR. +.PP +\&\fBHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs. +These flags have the same meaning as for \fBEVP_MD_CTX_set_flags\fR\|(3). +.PP +\&\fBHMAC_CTX_get_md()\fR returns the EVP_MD that has previously been set for the +supplied HMAC_CTX. +.PP +\&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBHMAC()\fR returns a pointer to the message authentication code or NULL if +an error occurred. +.PP +\&\fBHMAC_CTX_new()\fR returns a pointer to a new \fBHMAC_CTX\fR on success or +NULL if an error occurred. +.PP +\&\fBHMAC_CTX_reset()\fR, \fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR and +\&\fBHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred. +.PP +\&\fBHMAC_CTX_get_md()\fR return the EVP_MD previously set for the supplied HMAC_CTX or +NULL if no EVP_MD has been set. +.PP +\&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output +or zero on error. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 2104 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSHA1\fR\|(3), \fBEVP_Q_mac\fR\|(3), \fBevp\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All functions except for \fBHMAC()\fR were deprecated in OpenSSL 3.0. +.PP +\&\fBHMAC_CTX_init()\fR was replaced with \fBHMAC_CTX_reset()\fR in OpenSSL 1.1.0. +.PP +\&\fBHMAC_CTX_cleanup()\fR existed in OpenSSL before version 1.1.0. +.PP +\&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR and \fBHMAC_CTX_get_md()\fR are new in OpenSSL 1.1.0. +.PP +\&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR and \fBHMAC_Final()\fR did not return values in +OpenSSL before version 1.0.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl-MD5.3 b/static/netbsd/man3/openssl-MD5.3 new file mode 100644 index 00000000..5986da0b --- /dev/null +++ b/static/netbsd/man3/openssl-MD5.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: openssl-MD5.3,v 1.2 2026/04/08 17:06:50 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "MD5 3" +.TH MD5 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final \- MD2, MD4, and MD5 hash functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include <openssl/md2.h> +\& +\& unsigned char *MD2(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD2_Init(MD2_CTX *c); +\& int MD2_Update(MD2_CTX *c, const unsigned char *data, unsigned long len); +\& int MD2_Final(unsigned char *md, MD2_CTX *c); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include <openssl/md4.h> +\& +\& unsigned char *MD4(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD4_Init(MD4_CTX *c); +\& int MD4_Update(MD4_CTX *c, const void *data, unsigned long len); +\& int MD4_Final(unsigned char *md, MD4_CTX *c); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& #include <openssl/md5.h> +\& +\& unsigned char *MD5(const unsigned char *d, unsigned long n, unsigned char *md); +\& +\& int MD5_Init(MD5_CTX *c); +\& int MD5_Update(MD5_CTX *c, const void *data, unsigned long len); +\& int MD5_Final(unsigned char *md, MD5_CTX *c); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +All of the functions described on this page are deprecated. +Applications should instead use \fBEVP_DigestInit_ex\fR\|(3), \fBEVP_DigestUpdate\fR\|(3) +and \fBEVP_DigestFinal_ex\fR\|(3). +.PP +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. +.PP +\&\fBMD2()\fR, \fBMD4()\fR, and \fBMD5()\fR compute the MD2, MD4, and MD5 message digest +of the \fBn\fR bytes at \fBd\fR and place it in \fBmd\fR (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If \fBmd\fR is NULL, the digest is placed in a static +array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fBMD2_Init()\fR initializes a \fBMD2_CTX\fR structure. +.PP +\&\fBMD2_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fBMD2_Final()\fR places the message digest in \fBmd\fR, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the \fBMD2_CTX\fR. +.PP +\&\fBMD4_Init()\fR, \fBMD4_Update()\fR, \fBMD4_Final()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, and +\&\fBMD5_Final()\fR are analogous using an \fBMD4_CTX\fR and \fBMD5_CTX\fR structure. The parameter \fBMUST NOT\fR be NULL. +.PP +Applications should use the higher level functions +\&\fBEVP_DigestInit\fR\|(3) +etc. instead of calling the hash functions directly. +.SH NOTE +.IX Header "NOTE" +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, hashes from the SHA\-2 or SHA\-3 family +should be preferred. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBMD2()\fR, \fBMD4()\fR, and \fBMD5()\fR return pointers to the hash value. +.PP +\&\fBMD2_Init()\fR, \fBMD2_Update()\fR, \fBMD2_Final()\fR, \fBMD4_Init()\fR, \fBMD4_Update()\fR, +\&\fBMD4_Final()\fR, \fBMD5_Init()\fR, \fBMD5_Update()\fR, and \fBMD5_Final()\fR return 1 for +success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 1319, RFC 1320, RFC 1321 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_DigestInit\fR\|(3), \fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +All of these functions were deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl_HMAC.3 b/static/netbsd/man3/openssl_HMAC.3 new file mode 100644 index 00000000..75f50ac7 --- /dev/null +++ b/static/netbsd/man3/openssl_HMAC.3 @@ -0,0 +1,284 @@ +.\" $NetBSD: openssl_HMAC.3,v 1.1 2018/05/23 01:58:40 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "HMAC 3" +.TH HMAC 3 "2018-01-15" "1.1.0g" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +HMAC, +HMAC_CTX_new, +HMAC_CTX_reset, +HMAC_CTX_free, +HMAC_Init, +HMAC_Init_ex, +HMAC_Update, +HMAC_Final, +HMAC_CTX_copy, +HMAC_CTX_set_flags, +HMAC_CTX_get_md +\&\- HMAC message authentication code +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/hmac.h> +\& +\& unsigned char *HMAC(const EVP_MD *evp_md, const void *key, +\& int key_len, const unsigned char *d, int n, +\& unsigned char *md, unsigned int *md_len); +\& +\& HMAC_CTX *HMAC_CTX_new(void); +\& int HMAC_CTX_reset(HMAC_CTX *ctx); +\& +\& int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, +\& const EVP_MD *md, ENGINE *impl); +\& int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); +\& int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); +\& +\& void HMAC_CTX_free(HMAC_CTX *ctx); +\& +\& int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); +\& void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); +\& const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); +.Ve +.PP +Deprecated: +.PP +.Vb 4 +\& #if OPENSSL_API_COMPAT < 0x10100000L +\& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, +\& const EVP_MD *md); +\& #endif +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1HMAC\s0 is a \s-1MAC \s0(message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. +.PP +\&\s-1\fIHMAC\s0()\fR computes the message authentication code of the \fBn\fR bytes at +\&\fBd\fR using the hash function \fBevp_md\fR and the key \fBkey\fR which is +\&\fBkey_len\fR bytes long. +.PP +It places the result in \fBmd\fR (which must have space for the output of +the hash function, which is no more than \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes). +If \fBmd\fR is \s-1NULL,\s0 the digest is placed in a static array. The size of +the output is placed in \fBmd_len\fR, unless it is \fB\s-1NULL\s0\fR. Note: passing a \s-1NULL\s0 +value for \fBmd\fR to use the static array is not thread safe. +.PP +\&\fBevp_md\fR can be \fIEVP_sha1()\fR, \fIEVP_ripemd160()\fR etc. +.PP +\&\fIHMAC_CTX_new()\fR creates a new \s-1HMAC_CTX\s0 in heap memory. +.PP +\&\fIHMAC_CTX_reset()\fR zeroes an existing \fB\s-1HMAC_CTX\s0\fR and associated +resources, making it suitable for new computations as if it was newly +created with \fIHMAC_CTX_new()\fR. +.PP +\&\fIHMAC_CTX_free()\fR erases the key and other data from the \fB\s-1HMAC_CTX\s0\fR, +releases any associated resources and finally frees the \fB\s-1HMAC_CTX\s0\fR +itself. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fIHMAC_Init()\fR initializes a \fB\s-1HMAC_CTX\s0\fR structure to use the hash +function \fBevp_md\fR and the key \fBkey\fR which is \fBkey_len\fR bytes +long. It is deprecated and only included for backward compatibility +with OpenSSL 0.9.6b. +.PP +\&\fIHMAC_Init_ex()\fR initializes or reuses a \fB\s-1HMAC_CTX\s0\fR structure to use the hash +function \fBevp_md\fR and key \fBkey\fR. If both are \s-1NULL \s0(or \fBevp_md\fR is the same +as the previous digest used by \fBctx\fR and \fBkey\fR is \s-1NULL\s0) the existing key is +reused. \fBctx\fR must have been created with \fIHMAC_CTX_new()\fR before the first use +of an \fB\s-1HMAC_CTX\s0\fR in this function. \fBN.B. \f(BIHMAC_Init()\fB had this undocumented +behaviour in previous versions of OpenSSL \- failure to switch to \f(BIHMAC_Init_ex()\fB +in programs that expect it will cause them to stop working\fR. +.PP +\&\fB\s-1NOTE:\s0\fR If \fIHMAC_Init_ex()\fR is called with \fBkey\fR \s-1NULL\s0 and \fBevp_md\fR is not the +same as the previous digest used by \fBctx\fR then an error is returned +because reuse of an existing key with a different digest is not supported. +.PP +\&\fIHMAC_Update()\fR can be called repeatedly with chunks of the message to +be authenticated (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fIHMAC_Final()\fR places the message authentication code in \fBmd\fR, which +must have space for the hash function output. +.PP +\&\fIHMAC_CTX_copy()\fR copies all of the internal state from \fBsctx\fR into \fBdctx\fR. +.PP +\&\fIHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs. +These flags have the same meaning as for \fIEVP_MD_CTX_set_flags\fR\|(3). +.PP +\&\fIHMAC_CTX_get_md()\fR returns the \s-1EVP_MD\s0 that has previously been set for the +supplied \s-1HMAC_CTX.\s0 +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\s-1\fIHMAC\s0()\fR returns a pointer to the message authentication code or \s-1NULL\s0 if +an error occurred. +.PP +\&\fIHMAC_CTX_new()\fR returns a pointer to a new \fB\s-1HMAC_CTX\s0\fR on success or +\&\fB\s-1NULL\s0\fR if an error occurred. +.PP +\&\fIHMAC_CTX_reset()\fR, \fIHMAC_Init_ex()\fR, \fIHMAC_Update()\fR, \fIHMAC_Final()\fR and +\&\fIHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred. +.PP +\&\fIHMAC_CTX_get_md()\fR return the \s-1EVP_MD\s0 previously set for the supplied \s-1HMAC_CTX\s0 or +\&\s-1NULL\s0 if no \s-1EVP_MD\s0 has been set. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 2104\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_sha\fR\|(3), \fIopenssl_evp\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIHMAC_CTX_init()\fR was replaced with \fIHMAC_CTX_reset()\fR in OpenSSL versions 1.1.0. +.PP +\&\fIHMAC_CTX_cleanup()\fR existed in OpenSSL versions before 1.1.0. +.PP +\&\fIHMAC_CTX_new()\fR, \fIHMAC_CTX_free()\fR and \fIHMAC_CTX_get_md()\fR are new in OpenSSL version +1.1.0. +.PP +\&\fIHMAC_Init_ex()\fR, \fIHMAC_Update()\fR and \fIHMAC_Final()\fR did not return values in +versions of OpenSSL before 1.0.0. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl_MD5.3 b/static/netbsd/man3/openssl_MD5.3 new file mode 100644 index 00000000..e20be6a1 --- /dev/null +++ b/static/netbsd/man3/openssl_MD5.3 @@ -0,0 +1,231 @@ +.\" $NetBSD: openssl_MD5.3,v 1.1 2018/05/23 01:58:40 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "MD5 3" +.TH MD5 3 "2018-01-15" "1.1.0g" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final \- MD2, MD4, and MD5 hash functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/md2.h> +\& +\& unsigned char *MD2(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int MD2_Init(MD2_CTX *c); +\& int MD2_Update(MD2_CTX *c, const unsigned char *data, +\& unsigned long len); +\& int MD2_Final(unsigned char *md, MD2_CTX *c); +\& +\& +\& #include <openssl/md4.h> +\& +\& unsigned char *MD4(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int MD4_Init(MD4_CTX *c); +\& int MD4_Update(MD4_CTX *c, const void *data, +\& unsigned long len); +\& int MD4_Final(unsigned char *md, MD4_CTX *c); +\& +\& +\& #include <openssl/md5.h> +\& +\& unsigned char *MD5(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int MD5_Init(MD5_CTX *c); +\& int MD5_Update(MD5_CTX *c, const void *data, +\& unsigned long len); +\& int MD5_Final(unsigned char *md, MD5_CTX *c); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1MD2, MD4,\s0 and \s-1MD5\s0 are cryptographic hash functions with a 128 bit output. +.PP +\&\s-1\fIMD2\s0()\fR, \s-1\fIMD4\s0()\fR, and \s-1\fIMD5\s0()\fR compute the \s-1MD2, MD4,\s0 and \s-1MD5\s0 message digest +of the \fBn\fR bytes at \fBd\fR and place it in \fBmd\fR (which must have space +for \s-1MD2_DIGEST_LENGTH\s0 == \s-1MD4_DIGEST_LENGTH\s0 == \s-1MD5_DIGEST_LENGTH\s0 == 16 +bytes of output). If \fBmd\fR is \s-1NULL,\s0 the digest is placed in a static +array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fIMD2_Init()\fR initializes a \fB\s-1MD2_CTX\s0\fR structure. +.PP +\&\fIMD2_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fIMD2_Final()\fR places the message digest in \fBmd\fR, which must have space +for \s-1MD2_DIGEST_LENGTH\s0 == 16 bytes of output, and erases the \fB\s-1MD2_CTX\s0\fR. +.PP +\&\fIMD4_Init()\fR, \fIMD4_Update()\fR, \fIMD4_Final()\fR, \fIMD5_Init()\fR, \fIMD5_Update()\fR, and +\&\fIMD5_Final()\fR are analogous using an \fB\s-1MD4_CTX\s0\fR and \fB\s-1MD5_CTX\s0\fR structure. +.PP +Applications should use the higher level functions +\&\fIEVP_DigestInit\fR\|(3) +etc. instead of calling the hash functions directly. +.SH "NOTE" +.IX Header "NOTE" +\&\s-1MD2, MD4,\s0 and \s-1MD5\s0 are recommended only for compatibility with existing +applications. In new applications, \s-1SHA\-1\s0 or \s-1RIPEMD\-160\s0 should be +preferred. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\s-1\fIMD2\s0()\fR, \s-1\fIMD4\s0()\fR, and \s-1\fIMD5\s0()\fR return pointers to the hash value. +.PP +\&\fIMD2_Init()\fR, \fIMD2_Update()\fR, \fIMD2_Final()\fR, \fIMD4_Init()\fR, \fIMD4_Update()\fR, +\&\fIMD4_Final()\fR, \fIMD5_Init()\fR, \fIMD5_Update()\fR, and \fIMD5_Final()\fR return 1 for +success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1RFC 1319, RFC 1320, RFC 1321\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIEVP_DigestInit\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl_bio.3 b/static/netbsd/man3/openssl_bio.3 new file mode 100644 index 00000000..78edfb14 --- /dev/null +++ b/static/netbsd/man3/openssl_bio.3 @@ -0,0 +1,218 @@ +.\" $NetBSD: openssl_bio.3,v 1.1.1.2 2023/04/18 14:19:15 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "bio 3" +.TH bio 3 "2018-01-15" "1.1.0g" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +bio \- Basic I/O abstraction +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/bio.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +A \s-1BIO\s0 is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a \s-1BIO\s0 for its +I/O it can transparently handle \s-1SSL\s0 connections, unencrypted network +connections and file I/O. +.PP +There are two type of \s-1BIO,\s0 a source/sink \s-1BIO\s0 and a filter \s-1BIO.\s0 +.PP +As its name implies a source/sink \s-1BIO\s0 is a source and/or sink of data, +examples include a socket \s-1BIO\s0 and a file \s-1BIO.\s0 +.PP +A filter \s-1BIO\s0 takes data from one \s-1BIO\s0 and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest \s-1BIO\s0) or translated (for example an +encryption \s-1BIO\s0). The effect of a filter \s-1BIO\s0 may change according +to the I/O operation it is performing: for example an encryption +\&\s-1BIO\s0 will encrypt data if it is being written to and decrypt data +if it is being read from. +.PP +BIOs can be joined together to form a chain (a single \s-1BIO\s0 is a chain +with one component). A chain normally consist of one source/sink +\&\s-1BIO\s0 and one or more filter BIOs. Data read from or written to the +first \s-1BIO\s0 then traverses the chain to the end (normally a source/sink +\&\s-1BIO\s0). +.PP +Some BIOs (such as memory BIOs) can be used immediately after calling +\&\fIBIO_new()\fR. Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. +.PP +If \fIBIO_free()\fR is called on a \s-1BIO\s0 chain it will only free one \s-1BIO\s0 resulting +in a memory leak. +.PP +Calling \fIBIO_free_all()\fR a single \s-1BIO\s0 has the same effect as calling \fIBIO_free()\fR +on it other than the discarded return value. +.PP +Normally the \fBtype\fR argument is supplied by a function which returns a +pointer to a \s-1BIO_METHOD.\s0 There is a naming convention for such functions: +a source/sink \s-1BIO\s0 is normally called BIO_s_*() and a filter \s-1BIO\s0 +BIO_f_*(); +.SH "EXAMPLE" +.IX Header "EXAMPLE" +Create a memory \s-1BIO:\s0 +.PP +.Vb 1 +\& BIO *mem = BIO_new(BIO_s_mem()); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIBIO_ctrl\fR\|(3), +\&\fIBIO_f_base64\fR\|(3), \fIBIO_f_buffer\fR\|(3), +\&\fIBIO_f_cipher\fR\|(3), \fIBIO_f_md\fR\|(3), +\&\fIBIO_f_null\fR\|(3), \fIBIO_f_ssl\fR\|(3), +\&\fIBIO_find_type\fR\|(3), \fIBIO_new\fR\|(3), +\&\fIBIO_new_bio_pair\fR\|(3), +\&\fIBIO_push\fR\|(3), \fIBIO_read\fR\|(3), +\&\fIBIO_s_accept\fR\|(3), \fIBIO_s_bio\fR\|(3), +\&\fIBIO_s_connect\fR\|(3), \fIBIO_s_fd\fR\|(3), +\&\fIBIO_s_file\fR\|(3), \fIBIO_s_mem\fR\|(3), +\&\fIBIO_s_mem\fR\|(3), +\&\fIBIO_s_null\fR\|(3), \fIBIO_s_socket\fR\|(3), +\&\fIBIO_set_callback\fR\|(3), +\&\fIBIO_should_retry\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl_blowfish.3 b/static/netbsd/man3/openssl_blowfish.3 new file mode 100644 index 00000000..12f7d4c1 --- /dev/null +++ b/static/netbsd/man3/openssl_blowfish.3 @@ -0,0 +1,242 @@ +.\" $NetBSD: openssl_blowfish.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "blowfish 3" +.TH blowfish 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options \- Blowfish encryption +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/blowfish.h> +\& +\& void BF_set_key(BF_KEY *key, int len, const unsigned char *data); +\& +\& void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, +\& BF_KEY *key, int enc); +\& void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, unsigned char *ivec, int enc); +\& void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, unsigned char *ivec, int *num, +\& int enc); +\& void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, BF_KEY *schedule, unsigned char *ivec, int *num); +\& const char *BF_options(void); +\& +\& void BF_encrypt(BF_LONG *data,const BF_KEY *key); +\& void BF_decrypt(BF_LONG *data,const BF_KEY *key); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library implements the Blowfish cipher, which was invented and described +by Counterpane (see http://www.counterpane.com/blowfish.html ). +.PP +Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. +It uses a variable size key, but typically, 128 bit (16 byte) keys are +considered good for strong encryption. Blowfish can be used in the same +modes as \s-1DES \s0(see \fIdes_modes\fR\|(7)). Blowfish is currently one +of the faster block ciphers. It is quite a bit faster than \s-1DES,\s0 and much +faster than \s-1IDEA\s0 or \s-1RC2.\s0 +.PP +Blowfish consists of a key setup phase and the actual encryption or decryption +phase. +.PP +\&\fIBF_set_key()\fR sets up the \fB\s-1BF_KEY\s0\fR \fBkey\fR using the \fBlen\fR bytes long key +at \fBdata\fR. +.PP +\&\fIBF_ecb_encrypt()\fR is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of \fBin\fR using the key \fBkey\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fB\s-1BF_ENCRYPT\s0\fR) +or decryption (\fB\s-1BF_DECRYPT\s0\fR) shall be performed. The vector pointed at by +\&\fBin\fR and \fBout\fR must be 64 bits in length, no less. If they are larger, +everything after the first 64 bits is ignored. +.PP +The mode functions \fIBF_cbc_encrypt()\fR, \fIBF_cfb64_encrypt()\fR and \fIBF_ofb64_encrypt()\fR +all operate on variable length data. They all take an initialization vector +\&\fBivec\fR which needs to be passed along into the next call of the same function +for the same message. \fBivec\fR may be initialized with anything, but the +recipient needs to know what it was initialized with, or it won't be able +to decrypt. Some programs and protocols simplify this, like \s-1SSH,\s0 where +\&\fBivec\fR is simply initialized to zero. +\&\fIBF_cbc_encrypt()\fR operates on data that is a multiple of 8 bytes long, while +\&\fIBF_cfb64_encrypt()\fR and \fIBF_ofb64_encrypt()\fR are used to encrypt an variable +number of bytes (the amount does not have to be an exact multiple of 8). The +purpose of the latter two is to simulate stream ciphers, and therefore, they +need the parameter \fBnum\fR, which is a pointer to an integer where the current +offset in \fBivec\fR is stored between calls. This integer must be initialized +to zero when \fBivec\fR is initialized. +.PP +\&\fIBF_cbc_encrypt()\fR is the Cipher Block Chaining function for Blowfish. It +encrypts or decrypts the 64 bits chunks of \fBin\fR using the key \fBschedule\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (\s-1BF_ENCRYPT\s0) or +decryption (\s-1BF_DECRYPT\s0) shall be performed. \fBivec\fR must point at an 8 byte +long initialization vector. +.PP +\&\fIBF_cfb64_encrypt()\fR is the \s-1CFB\s0 mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in \fBin\fR using the key \fBschedule\fR, +putting the result in \fBout\fR. \fBenc\fR decides if encryption (\fB\s-1BF_ENCRYPT\s0\fR) +or decryption (\fB\s-1BF_DECRYPT\s0\fR) shall be performed. \fBivec\fR must point at an +8 byte long initialization vector. \fBnum\fR must point at an integer which must +be initially zero. +.PP +\&\fIBF_ofb64_encrypt()\fR is the \s-1OFB\s0 mode for Blowfish with 64 bit feedback. +It uses the same parameters as \fIBF_cfb64_encrypt()\fR, which must be initialized +the same way. +.PP +\&\fIBF_encrypt()\fR and \fIBF_decrypt()\fR are the lowest level functions for Blowfish +encryption. They encrypt/decrypt the first 64 bits of the vector pointed by +\&\fBdata\fR, using the key \fBkey\fR. These functions should not be used unless you +implement 'modes' of Blowfish. The alternative is to use \fIBF_ecb_encrypt()\fR. +If you still want to use these functions, you should be aware that they take +each 32\-bit chunk in host-byte order, which is little-endian on little-endian +platforms and big-endian on big-endian ones. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +None of the functions presented here return any value. +.SH "NOTE" +.IX Header "NOTE" +Applications should use the higher level functions +\&\fIEVP_EncryptInit\fR\|(3) etc. instead of calling the +blowfish functions directly. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIdes_modes\fR\|(7) +.SH "HISTORY" +.IX Header "HISTORY" +The Blowfish functions are available in all versions of SSLeay and OpenSSL. diff --git a/static/netbsd/man3/openssl_bn.3 b/static/netbsd/man3/openssl_bn.3 new file mode 100644 index 00000000..1a364c18 --- /dev/null +++ b/static/netbsd/man3/openssl_bn.3 @@ -0,0 +1,315 @@ +.\" $NetBSD: openssl_bn.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "bn 3" +.TH bn 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +bn \- multiprecision integer arithmetics +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/bn.h> +\& +\& BIGNUM *BN_new(void); +\& void BN_free(BIGNUM *a); +\& void BN_init(BIGNUM *); +\& void BN_clear(BIGNUM *a); +\& void BN_clear_free(BIGNUM *a); +\& +\& BN_CTX *BN_CTX_new(void); +\& void BN_CTX_init(BN_CTX *c); +\& void BN_CTX_free(BN_CTX *c); +\& +\& BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); +\& BIGNUM *BN_dup(const BIGNUM *a); +\& +\& BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); +\& +\& int BN_num_bytes(const BIGNUM *a); +\& int BN_num_bits(const BIGNUM *a); +\& int BN_num_bits_word(BN_ULONG w); +\& +\& void BN_set_negative(BIGNUM *a, int n); +\& int BN_is_negative(const BIGNUM *a); +\& +\& int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); +\& int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); +\& int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +\& int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); +\& int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, +\& BN_CTX *ctx); +\& int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, +\& BN_CTX *ctx); +\& int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); +\& int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); +\& int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx); +\& int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); +\& +\& int BN_add_word(BIGNUM *a, BN_ULONG w); +\& int BN_sub_word(BIGNUM *a, BN_ULONG w); +\& int BN_mul_word(BIGNUM *a, BN_ULONG w); +\& BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); +\& BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); +\& +\& int BN_cmp(BIGNUM *a, BIGNUM *b); +\& int BN_ucmp(BIGNUM *a, BIGNUM *b); +\& int BN_is_zero(BIGNUM *a); +\& int BN_is_one(BIGNUM *a); +\& int BN_is_word(BIGNUM *a, BN_ULONG w); +\& int BN_is_odd(BIGNUM *a); +\& +\& int BN_zero(BIGNUM *a); +\& int BN_one(BIGNUM *a); +\& const BIGNUM *BN_value_one(void); +\& int BN_set_word(BIGNUM *a, unsigned long w); +\& unsigned long BN_get_word(BIGNUM *a); +\& +\& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& int BN_rand_range(BIGNUM *rnd, BIGNUM *range); +\& int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); +\& +\& BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, +\& BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); +\& int BN_is_prime(const BIGNUM *p, int nchecks, +\& void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); +\& +\& int BN_set_bit(BIGNUM *a, int n); +\& int BN_clear_bit(BIGNUM *a, int n); +\& int BN_is_bit_set(const BIGNUM *a, int n); +\& int BN_mask_bits(BIGNUM *a, int n); +\& int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); +\& int BN_lshift1(BIGNUM *r, BIGNUM *a); +\& int BN_rshift(BIGNUM *r, BIGNUM *a, int n); +\& int BN_rshift1(BIGNUM *r, BIGNUM *a); +\& +\& int BN_bn2bin(const BIGNUM *a, unsigned char *to); +\& BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); +\& char *BN_bn2hex(const BIGNUM *a); +\& char *BN_bn2dec(const BIGNUM *a); +\& int BN_hex2bn(BIGNUM **a, const char *str); +\& int BN_dec2bn(BIGNUM **a, const char *str); +\& int BN_print(BIO *fp, const BIGNUM *a); +\& int BN_print_fp(FILE *fp, const BIGNUM *a); +\& int BN_bn2mpi(const BIGNUM *a, unsigned char *to); +\& BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); +\& +\& BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, +\& BN_CTX *ctx); +\& +\& BN_RECP_CTX *BN_RECP_CTX_new(void); +\& void BN_RECP_CTX_init(BN_RECP_CTX *recp); +\& void BN_RECP_CTX_free(BN_RECP_CTX *recp); +\& int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); +\& int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, +\& BN_RECP_CTX *recp, BN_CTX *ctx); +\& +\& BN_MONT_CTX *BN_MONT_CTX_new(void); +\& void BN_MONT_CTX_init(BN_MONT_CTX *ctx); +\& void BN_MONT_CTX_free(BN_MONT_CTX *mont); +\& int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); +\& BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); +\& int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, +\& BN_MONT_CTX *mont, BN_CTX *ctx); +\& int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, +\& BN_CTX *ctx); +\& int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, +\& BN_CTX *ctx); +\& +\& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, +\& BIGNUM *mod); +\& void BN_BLINDING_free(BN_BLINDING *b); +\& int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); +\& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); +\& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); +\& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, +\& BN_CTX *ctx); +\& int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, +\& BN_CTX *ctx); +\& unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); +\& void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); +\& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); +\& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); +\& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, +\& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, +\& int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, +\& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), +\& BN_MONT_CTX *m_ctx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library performs arithmetic operations on integers of arbitrary +size. It was written for use in public key cryptography, such as \s-1RSA\s0 +and Diffie-Hellman. +.PP +It uses dynamic memory allocation for storing its data structures. +That means that there is no limit on the size of the numbers +manipulated by these functions, but return values must always be +checked in case a memory allocation error has occurred. +.PP +The basic object in this library is a \fB\s-1BIGNUM\s0\fR. It is used to hold a +single large integer. This type should be considered opaque and fields +should not be modified or accessed directly. +.PP +The creation of \fB\s-1BIGNUM\s0\fR objects is described in \fIBN_new\fR\|(3); +\&\fIBN_add\fR\|(3) describes most of the arithmetic operations. +Comparison is described in \fIBN_cmp\fR\|(3); \fIBN_zero\fR\|(3) +describes certain assignments, \fIBN_rand\fR\|(3) the generation of +random numbers, \fIBN_generate_prime\fR\|(3) deals with prime +numbers and \fIBN_set_bit\fR\|(3) with bit operations. The conversion +of \fB\s-1BIGNUM\s0\fRs to external formats is described in \fIBN_bn2bin\fR\|(3). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_bn_internal\fR\|(3), +\&\fIopenssl_dh\fR\|(3), \fIopenssl_err\fR\|(3), \fIopenssl_rand\fR\|(3), \fIopenssl_rsa\fR\|(3), +\&\fIBN_new\fR\|(3), \fIBN_CTX_new\fR\|(3), +\&\fIBN_copy\fR\|(3), \fIBN_swap\fR\|(3), \fIBN_num_bytes\fR\|(3), +\&\fIBN_add\fR\|(3), \fIBN_add_word\fR\|(3), +\&\fIBN_cmp\fR\|(3), \fIBN_zero\fR\|(3), \fIBN_rand\fR\|(3), +\&\fIBN_generate_prime\fR\|(3), \fIBN_set_bit\fR\|(3), +\&\fIBN_bn2bin\fR\|(3), \fIBN_mod_inverse\fR\|(3), +\&\fIBN_mod_mul_reciprocal\fR\|(3), +\&\fIBN_mod_mul_montgomery\fR\|(3), +\&\fIBN_BLINDING_new\fR\|(3) diff --git a/static/netbsd/man3/openssl_bn_internal.3 b/static/netbsd/man3/openssl_bn_internal.3 new file mode 100644 index 00000000..a2f7ff73 --- /dev/null +++ b/static/netbsd/man3/openssl_bn_internal.3 @@ -0,0 +1,369 @@ +.\" $NetBSD: openssl_bn_internal.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "bn_internal 3" +.TH bn_internal 3 "2009-12-26" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, +bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, +bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, +bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, +bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, +bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, +bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low \- BIGNUM +library internal functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/bn.h> +\& +\& BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); +\& BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, +\& BN_ULONG w); +\& void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); +\& BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); +\& BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, +\& int num); +\& BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, +\& int num); +\& +\& void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); +\& void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); +\& void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); +\& void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); +\& +\& int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); +\& +\& void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, +\& int nb); +\& void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); +\& void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, +\& int dna,int dnb,BN_ULONG *tmp); +\& void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, +\& int n, int tna,int tnb, BN_ULONG *tmp); +\& void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, +\& int n2, BN_ULONG *tmp); +\& void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, +\& int n2, BN_ULONG *tmp); +\& +\& void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); +\& void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); +\& +\& void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); +\& void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); +\& void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); +\& +\& BIGNUM *bn_expand(BIGNUM *a, int bits); +\& BIGNUM *bn_wexpand(BIGNUM *a, int n); +\& BIGNUM *bn_expand2(BIGNUM *a, int n); +\& void bn_fix_top(BIGNUM *a); +\& +\& void bn_check_top(BIGNUM *a); +\& void bn_print(BIGNUM *a); +\& void bn_dump(BN_ULONG *d, int n); +\& void bn_set_max(BIGNUM *a); +\& void bn_set_high(BIGNUM *r, BIGNUM *a, int n); +\& void bn_set_low(BIGNUM *r, BIGNUM *a, int n); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This page documents the internal functions used by the OpenSSL +\&\fB\s-1BIGNUM\s0\fR implementation. They are described here to facilitate +debugging and extending the library. They are \fInot\fR to be used by +applications. +.SS "The \s-1BIGNUM\s0 structure" +.IX Subsection "The BIGNUM structure" +.Vb 1 +\& typedef struct bignum_st BIGNUM; +\& +\& struct bignum_st +\& { +\& BN_ULONG *d; /* Pointer to an array of \*(AqBN_BITS2\*(Aq bit chunks. */ +\& int top; /* Index of last used d +1. */ +\& /* The next are internal book keeping for bn_expand. */ +\& int dmax; /* Size of the d array. */ +\& int neg; /* one if the number is negative */ +\& int flags; +\& }; +.Ve +.PP +The integer value is stored in \fBd\fR, a \fImalloc()\fRed array of words (\fB\s-1BN_ULONG\s0\fR), +least significant word first. A \fB\s-1BN_ULONG\s0\fR can be either 16, 32 or 64 bits +in size, depending on the 'number of bits' (\fB\s-1BITS2\s0\fR) specified in +\&\f(CW\*(C`openssl/bn.h\*(C'\fR. +.PP +\&\fBdmax\fR is the size of the \fBd\fR array that has been allocated. \fBtop\fR +is the number of words being used, so for a value of 4, bn.d[0]=4 and +bn.top=1. \fBneg\fR is 1 if the number is negative. When a \fB\s-1BIGNUM\s0\fR is +\&\fB0\fR, the \fBd\fR field can be \fB\s-1NULL\s0\fR and \fBtop\fR == \fB0\fR. +.PP +\&\fBflags\fR is a bit field of flags which are defined in \f(CW\*(C`openssl/bn.h\*(C'\fR. The +flags begin with \fB\s-1BN_FLG_\s0\fR. The macros BN_set_flags(b,n) and +BN_get_flags(b,n) exist to enable or fetch flag(s) \fBn\fR from \fB\s-1BIGNUM\s0\fR +structure \fBb\fR. +.PP +Various routines in this library require the use of temporary +\&\fB\s-1BIGNUM\s0\fR variables during their execution. Since dynamic memory +allocation to create \fB\s-1BIGNUM\s0\fRs is rather expensive when used in +conjunction with repeated subroutine calls, the \fB\s-1BN_CTX\s0\fR structure is +used. This structure contains \fB\s-1BN_CTX_NUM\s0\fR \fB\s-1BIGNUM\s0\fRs, see +\&\fIBN_CTX_start\fR\|(3). +.SS "Low-level arithmetic operations" +.IX Subsection "Low-level arithmetic operations" +These functions are implemented in C and for several platforms in +assembly language: +.PP +bn_mul_words(\fBrp\fR, \fBap\fR, \fBnum\fR, \fBw\fR) operates on the \fBnum\fR word +arrays \fBrp\fR and \fBap\fR. It computes \fBap\fR * \fBw\fR, places the result +in \fBrp\fR, and returns the high word (carry). +.PP +bn_mul_add_words(\fBrp\fR, \fBap\fR, \fBnum\fR, \fBw\fR) operates on the \fBnum\fR +word arrays \fBrp\fR and \fBap\fR. It computes \fBap\fR * \fBw\fR + \fBrp\fR, places +the result in \fBrp\fR, and returns the high word (carry). +.PP +bn_sqr_words(\fBrp\fR, \fBap\fR, \fBn\fR) operates on the \fBnum\fR word array +\&\fBap\fR and the 2*\fBnum\fR word array \fBap\fR. It computes \fBap\fR * \fBap\fR +word-wise, and places the low and high bytes of the result in \fBrp\fR. +.PP +bn_div_words(\fBh\fR, \fBl\fR, \fBd\fR) divides the two word number (\fBh\fR,\fBl\fR) +by \fBd\fR and returns the result. +.PP +bn_add_words(\fBrp\fR, \fBap\fR, \fBbp\fR, \fBnum\fR) operates on the \fBnum\fR word +arrays \fBap\fR, \fBbp\fR and \fBrp\fR. It computes \fBap\fR + \fBbp\fR, places the +result in \fBrp\fR, and returns the high word (carry). +.PP +bn_sub_words(\fBrp\fR, \fBap\fR, \fBbp\fR, \fBnum\fR) operates on the \fBnum\fR word +arrays \fBap\fR, \fBbp\fR and \fBrp\fR. It computes \fBap\fR \- \fBbp\fR, places the +result in \fBrp\fR, and returns the carry (1 if \fBbp\fR > \fBap\fR, 0 +otherwise). +.PP +bn_mul_comba4(\fBr\fR, \fBa\fR, \fBb\fR) operates on the 4 word arrays \fBa\fR and +\&\fBb\fR and the 8 word array \fBr\fR. It computes \fBa\fR*\fBb\fR and places the +result in \fBr\fR. +.PP +bn_mul_comba8(\fBr\fR, \fBa\fR, \fBb\fR) operates on the 8 word arrays \fBa\fR and +\&\fBb\fR and the 16 word array \fBr\fR. It computes \fBa\fR*\fBb\fR and places the +result in \fBr\fR. +.PP +bn_sqr_comba4(\fBr\fR, \fBa\fR, \fBb\fR) operates on the 4 word arrays \fBa\fR and +\&\fBb\fR and the 8 word array \fBr\fR. +.PP +bn_sqr_comba8(\fBr\fR, \fBa\fR, \fBb\fR) operates on the 8 word arrays \fBa\fR and +\&\fBb\fR and the 16 word array \fBr\fR. +.PP +The following functions are implemented in C: +.PP +bn_cmp_words(\fBa\fR, \fBb\fR, \fBn\fR) operates on the \fBn\fR word arrays \fBa\fR +and \fBb\fR. It returns 1, 0 and \-1 if \fBa\fR is greater than, equal and +less than \fBb\fR. +.PP +bn_mul_normal(\fBr\fR, \fBa\fR, \fBna\fR, \fBb\fR, \fBnb\fR) operates on the \fBna\fR +word array \fBa\fR, the \fBnb\fR word array \fBb\fR and the \fBna\fR+\fBnb\fR word +array \fBr\fR. It computes \fBa\fR*\fBb\fR and places the result in \fBr\fR. +.PP +bn_mul_low_normal(\fBr\fR, \fBa\fR, \fBb\fR, \fBn\fR) operates on the \fBn\fR word +arrays \fBr\fR, \fBa\fR and \fBb\fR. It computes the \fBn\fR low words of +\&\fBa\fR*\fBb\fR and places the result in \fBr\fR. +.PP +bn_mul_recursive(\fBr\fR, \fBa\fR, \fBb\fR, \fBn2\fR, \fBdna\fR, \fBdnb\fR, \fBt\fR) operates +on the word arrays \fBa\fR and \fBb\fR of length \fBn2\fR+\fBdna\fR and \fBn2\fR+\fBdnb\fR +(\fBdna\fR and \fBdnb\fR are currently allowed to be 0 or negative) and the 2*\fBn2\fR +word arrays \fBr\fR and \fBt\fR. \fBn2\fR must be a power of 2. It computes +\&\fBa\fR*\fBb\fR and places the result in \fBr\fR. +.PP +bn_mul_part_recursive(\fBr\fR, \fBa\fR, \fBb\fR, \fBn\fR, \fBtna\fR, \fBtnb\fR, \fBtmp\fR) +operates on the word arrays \fBa\fR and \fBb\fR of length \fBn\fR+\fBtna\fR and +\&\fBn\fR+\fBtnb\fR and the 4*\fBn\fR word arrays \fBr\fR and \fBtmp\fR. +.PP +bn_mul_low_recursive(\fBr\fR, \fBa\fR, \fBb\fR, \fBn2\fR, \fBtmp\fR) operates on the +\&\fBn2\fR word arrays \fBr\fR and \fBtmp\fR and the \fBn2\fR/2 word arrays \fBa\fR +and \fBb\fR. +.PP +bn_mul_high(\fBr\fR, \fBa\fR, \fBb\fR, \fBl\fR, \fBn2\fR, \fBtmp\fR) operates on the +\&\fBn2\fR word arrays \fBr\fR, \fBa\fR, \fBb\fR and \fBl\fR (?) and the 3*\fBn2\fR word +array \fBtmp\fR. +.PP +\&\fIBN_mul()\fR calls \fIbn_mul_normal()\fR, or an optimized implementation if the +factors have the same size: \fIbn_mul_comba8()\fR is used if they are 8 +words long, \fIbn_mul_recursive()\fR if they are larger than +\&\fB\s-1BN_MULL_SIZE_NORMAL\s0\fR and the size is an exact multiple of the word +size, and \fIbn_mul_part_recursive()\fR for others that are larger than +\&\fB\s-1BN_MULL_SIZE_NORMAL\s0\fR. +.PP +bn_sqr_normal(\fBr\fR, \fBa\fR, \fBn\fR, \fBtmp\fR) operates on the \fBn\fR word array +\&\fBa\fR and the 2*\fBn\fR word arrays \fBtmp\fR and \fBr\fR. +.PP +The implementations use the following macros which, depending on the +architecture, may use \*(L"long long\*(R" C operations or inline assembler. +They are defined in \f(CW\*(C`bn_lcl.h\*(C'\fR. +.PP +mul(\fBr\fR, \fBa\fR, \fBw\fR, \fBc\fR) computes \fBw\fR*\fBa\fR+\fBc\fR and places the +low word of the result in \fBr\fR and the high word in \fBc\fR. +.PP +mul_add(\fBr\fR, \fBa\fR, \fBw\fR, \fBc\fR) computes \fBw\fR*\fBa\fR+\fBr\fR+\fBc\fR and +places the low word of the result in \fBr\fR and the high word in \fBc\fR. +.PP +sqr(\fBr0\fR, \fBr1\fR, \fBa\fR) computes \fBa\fR*\fBa\fR and places the low word +of the result in \fBr0\fR and the high word in \fBr1\fR. +.SS "Size changes" +.IX Subsection "Size changes" +\&\fIbn_expand()\fR ensures that \fBb\fR has enough space for a \fBbits\fR bit +number. \fIbn_wexpand()\fR ensures that \fBb\fR has enough space for an +\&\fBn\fR word number. If the number has to be expanded, both macros +call \fIbn_expand2()\fR, which allocates a new \fBd\fR array and copies the +data. They return \fB\s-1NULL\s0\fR on error, \fBb\fR otherwise. +.PP +The \fIbn_fix_top()\fR macro reduces \fBa\->top\fR to point to the most +significant non-zero word plus one when \fBa\fR has shrunk. +.SS "Debugging" +.IX Subsection "Debugging" +\&\fIbn_check_top()\fR verifies that \f(CW\*(C`((a)\->top >= 0 && (a)\->top +<= (a)\->dmax)\*(C'\fR. A violation will cause the program to abort. +.PP +\&\fIbn_print()\fR prints \fBa\fR to stderr. \fIbn_dump()\fR prints \fBn\fR words at \fBd\fR +(in reverse order, i.e. most significant word first) to stderr. +.PP +\&\fIbn_set_max()\fR makes \fBa\fR a static number with a \fBdmax\fR of its current size. +This is used by \fIbn_set_low()\fR and \fIbn_set_high()\fR to make \fBr\fR a read-only +\&\fB\s-1BIGNUM\s0\fR that contains the \fBn\fR low or high words of \fBa\fR. +.PP +If \fB\s-1BN_DEBUG\s0\fR is not defined, \fIbn_check_top()\fR, \fIbn_print()\fR, \fIbn_dump()\fR +and \fIbn_set_max()\fR are defined as empty macros. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_bn\fR\|(3) diff --git a/static/netbsd/man3/openssl_buffer.3 b/static/netbsd/man3/openssl_buffer.3 new file mode 100644 index 00000000..157c846b --- /dev/null +++ b/static/netbsd/man3/openssl_buffer.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: openssl_buffer.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "buffer 3" +.TH buffer 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow \- simple +character array structure +.PP +BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat \- +standard C library equivalents +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/buffer.h> +\& +\& BUF_MEM *BUF_MEM_new(void); +\& +\& void BUF_MEM_free(BUF_MEM *a); +\& +\& int BUF_MEM_grow(BUF_MEM *str, int len); +\& +\& char *BUF_strdup(const char *str); +\& +\& char *BUF_strndup(const char *str, size_t siz); +\& +\& void *BUF_memdup(const void *data, size_t siz); +\& +\& size_t BUF_strlcpy(char *dst, const char *src, size_t size); +\& +\& size_t BUF_strlcat(char *dst, const char *src, size_t size); +\& +\& size_t BUF_strnlen(const char *str, size_t maxlen); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. +.PP +\&\fIBUF_MEM_new()\fR allocates a new buffer of zero size. +.PP +\&\fIBUF_MEM_free()\fR frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. +.PP +\&\fIBUF_MEM_grow()\fR changes the size of an already existing buffer to +\&\fBlen\fR. Any data already in the buffer is preserved if it increases in +size. +.PP +\&\fIBUF_strdup()\fR, \fIBUF_strndup()\fR, \fIBUF_memdup()\fR, \fIBUF_strlcpy()\fR, +\&\fIBUF_strlcat()\fR and BUF_strnlen are equivalents of the standard C +library functions. The \fIdup()\fR functions use \fIOPENSSL_malloc()\fR underneath +and so should be used in preference to the standard library for memory +leak checking or replacing the \fImalloc()\fR function. +.PP +Memory allocated from these functions should be freed up using the +\&\fIOPENSSL_free()\fR function. +.PP +BUF_strndup makes the explicit guarantee that it will never read past +the first \fBsiz\fR bytes of \fBstr\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fIBUF_MEM_new()\fR returns the buffer or \s-1NULL\s0 on error. +.PP +\&\fIBUF_MEM_free()\fR has no return value. +.PP +\&\fIBUF_MEM_grow()\fR returns zero on error or the new size (i.e. \fBlen\fR). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_bio\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIBUF_MEM_new()\fR, \fIBUF_MEM_free()\fR and \fIBUF_MEM_grow()\fR are available in all +versions of SSLeay and OpenSSL. \fIBUF_strdup()\fR was added in SSLeay 0.8. diff --git a/static/netbsd/man3/openssl_des.3 b/static/netbsd/man3/openssl_des.3 new file mode 100644 index 00000000..8dec19d0 --- /dev/null +++ b/static/netbsd/man3/openssl_des.3 @@ -0,0 +1,486 @@ +.\" $NetBSD: openssl_des.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "des 3" +.TH des 3 "2014-08-10" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, +DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, +DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, +DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, +DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, +DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, +DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, +DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, +DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write \- DES encryption +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/des.h> +\& +\& void DES_random_key(DES_cblock *ret); +\& +\& int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); +\& int DES_set_key_checked(const_DES_cblock *key, +\& DES_key_schedule *schedule); +\& void DES_set_key_unchecked(const_DES_cblock *key, +\& DES_key_schedule *schedule); +\& +\& void DES_set_odd_parity(DES_cblock *key); +\& int DES_is_weak_key(const_DES_cblock *key); +\& +\& void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks, int enc); +\& void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); +\& void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, +\& DES_key_schedule *ks1, DES_key_schedule *ks2, +\& DES_key_schedule *ks3, int enc); +\& +\& void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec, int enc); +\& void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, +\& int numbits, long length, DES_key_schedule *schedule, +\& DES_cblock *ivec); +\& void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int enc); +\& void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num, int enc); +\& void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& int *num); +\& +\& void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, +\& long length, DES_key_schedule *schedule, DES_cblock *ivec, +\& const_DES_cblock *inw, const_DES_cblock *outw, int enc); +\& +\& void DES_ede2_cbc_encrypt(const unsigned char *input, +\& unsigned char *output, long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int enc); +\& void DES_ede2_cfb64_encrypt(const unsigned char *in, +\& unsigned char *out, long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc); +\& void DES_ede2_ofb64_encrypt(const unsigned char *in, +\& unsigned char *out, long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_cblock *ivec, int *num); +\& +\& void DES_ede3_cbc_encrypt(const unsigned char *input, +\& unsigned char *output, long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, +\& int enc); +\& void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, DES_key_schedule *ks2, +\& DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, +\& int enc); +\& void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, DES_key_schedule *ks2, +\& DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc); +\& void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, +\& long length, DES_key_schedule *ks1, +\& DES_key_schedule *ks2, DES_key_schedule *ks3, +\& DES_cblock *ivec, int *num); +\& +\& DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, +\& long length, DES_key_schedule *schedule, +\& const_DES_cblock *ivec); +\& DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], +\& long length, int out_count, DES_cblock *seed); +\& void DES_string_to_key(const char *str, DES_cblock *key); +\& void DES_string_to_2keys(const char *str, DES_cblock *key1, +\& DES_cblock *key2); +\& +\& char *DES_fcrypt(const char *buf, const char *salt, char *ret); +\& char *DES_crypt(const char *buf, const char *salt); +\& +\& int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, +\& DES_cblock *iv); +\& int DES_enc_write(int fd, const void *buf, int len, +\& DES_key_schedule *sched, DES_cblock *iv); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library contains a fast implementation of the \s-1DES\s0 encryption +algorithm. +.PP +There are two phases to the use of \s-1DES\s0 encryption. The first is the +generation of a \fIDES_key_schedule\fR from a key, the second is the +actual encryption. A \s-1DES\s0 key is of type \fIDES_cblock\fR. This type is +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. +.PP +\&\fIDES_random_key()\fR generates a random key. The \s-1PRNG\s0 must be seeded +prior to using this function (see \fIopenssl_rand\fR\|(3)). If the \s-1PRNG\s0 +could not generate a secure key, 0 is returned. +.PP +Before a \s-1DES\s0 key can be used, it must be converted into the +architecture dependent \fIDES_key_schedule\fR via the +\&\fIDES_set_key_checked()\fR or \fIDES_set_key_unchecked()\fR function. +.PP +\&\fIDES_set_key_checked()\fR will check that the key passed is of odd parity +and is not a week or semi-weak key. If the parity is wrong, then \-1 +is returned. If the key is a weak key, then \-2 is returned. If an +error is returned, the key schedule is not generated. +.PP +\&\fIDES_set_key()\fR works like +\&\fIDES_set_key_checked()\fR if the \fIDES_check_key\fR flag is non-zero, +otherwise like \fIDES_set_key_unchecked()\fR. These functions are available +for compatibility; it is recommended to use a function that does not +depend on a global variable. +.PP +\&\fIDES_set_odd_parity()\fR sets the parity of the passed \fIkey\fR to odd. +.PP +\&\fIDES_is_weak_key()\fR returns 1 if the passed key is a weak key, 0 if it +is ok. +.PP +The following routines mostly operate on an input and output stream of +\&\fIDES_cblock\fRs. +.PP +\&\fIDES_ecb_encrypt()\fR is the basic \s-1DES\s0 encryption routine that encrypts or +decrypts a single 8\-byte \fIDES_cblock\fR in \fIelectronic code book\fR +(\s-1ECB\s0) mode. It always transforms the input data, pointed to by +\&\fIinput\fR, into the output data, pointed to by the \fIoutput\fR argument. +If the \fIencrypt\fR argument is non-zero (\s-1DES_ENCRYPT\s0), the \fIinput\fR +(cleartext) is encrypted in to the \fIoutput\fR (ciphertext) using the +key_schedule specified by the \fIschedule\fR argument, previously set via +\&\fIDES_set_key\fR. If \fIencrypt\fR is zero (\s-1DES_DECRYPT\s0), the \fIinput\fR (now +ciphertext) is decrypted into the \fIoutput\fR (now cleartext). Input +and output may overlap. \fIDES_ecb_encrypt()\fR does not return a value. +.PP +\&\fIDES_ecb3_encrypt()\fR encrypts/decrypts the \fIinput\fR block by using +three-key Triple-DES encryption in \s-1ECB\s0 mode. This involves encrypting +the input with \fIks1\fR, decrypting with the key schedule \fIks2\fR, and +then encrypting with \fIks3\fR. This routine greatly reduces the chances +of brute force breaking of \s-1DES\s0 and has the advantage of if \fIks1\fR, +\&\fIks2\fR and \fIks3\fR are the same, it is equivalent to just encryption +using \s-1ECB\s0 mode and \fIks1\fR as the key. +.PP +The macro \fIDES_ecb2_encrypt()\fR is provided to perform two-key Triple-DES +encryption by using \fIks1\fR for the final encryption. +.PP +\&\fIDES_ncbc_encrypt()\fR encrypts/decrypts using the \fIcipher-block-chaining\fR +(\s-1CBC\s0) mode of \s-1DES. \s0 If the \fIencrypt\fR argument is non-zero, the +routine cipher-block-chain encrypts the cleartext data pointed to by +the \fIinput\fR argument into the ciphertext pointed to by the \fIoutput\fR +argument, using the key schedule provided by the \fIschedule\fR argument, +and initialization vector provided by the \fIivec\fR argument. If the +\&\fIlength\fR argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. +.PP +\&\fIDES_xcbc_encrypt()\fR is \s-1RSA\s0's \s-1DESX\s0 mode of \s-1DES. \s0 It uses \fIinw\fR and +\&\fIoutw\fR to 'whiten' the encryption. \fIinw\fR and \fIoutw\fR are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than \s-1CBC DES.\s0 +.PP +\&\fIDES_ede3_cbc_encrypt()\fR implements outer triple \s-1CBC DES\s0 encryption with +three keys. This means that each \s-1DES\s0 operation inside the \s-1CBC\s0 mode is +an \f(CW\*(C`C=E(ks3,D(ks2,E(ks1,M)))\*(C'\fR. This mode is used by \s-1SSL.\s0 +.PP +The \fIDES_ede2_cbc_encrypt()\fR macro implements two-key Triple-DES by +reusing \fIks1\fR for the final encryption. \f(CW\*(C`C=E(ks1,D(ks2,E(ks1,M)))\*(C'\fR. +This form of Triple-DES is used by the \s-1RSAREF\s0 library. +.PP +\&\fIDES_pcbc_encrypt()\fR encrypt/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +\&\fIDES_ncbc_encrypt()\fR. +.PP +\&\fIDES_cfb_encrypt()\fR encrypt/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete \s-1DES ECB\s0 encryption per \fInumbits\fR, this function is only +suggested for use when sending small numbers of characters. +.PP +\&\fIDES_cfb64_encrypt()\fR +implements \s-1CFB\s0 mode of \s-1DES\s0 with 64bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, no 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains 'how far' we are though ivec. If this does +not make much sense, read more about cfb mode of \s-1DES :\-\s0). +.PP +\&\fIDES_ede3_cfb64_encrypt()\fR and \fIDES_ede2_cfb64_encrypt()\fR is the same as +\&\fIDES_cfb64_encrypt()\fR except that Triple-DES is used. +.PP +\&\fIDES_ofb_encrypt()\fR encrypts using output feedback mode. This method +takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the \fIivec\fR variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete \s-1DES ECB\s0 encryption per numbits, this function is only +suggested for use when sending small numbers of characters. +.PP +\&\fIDES_ofb64_encrypt()\fR is the same as \fIDES_cfb64_encrypt()\fR using Output +Feed Back mode. +.PP +\&\fIDES_ede3_ofb64_encrypt()\fR and \fIDES_ede2_ofb64_encrypt()\fR is the same as +\&\fIDES_ofb64_encrypt()\fR, using Triple-DES. +.PP +The following functions are included in the \s-1DES\s0 library for +compatibility with the \s-1MIT\s0 Kerberos library. +.PP +\&\fIDES_cbc_cksum()\fR produces an 8 byte checksum based on the input stream +(via \s-1CBC\s0 encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in \fIoutput\fR. This function is +used by Kerberos v4. Other applications should use +\&\fIEVP_DigestInit\fR\|(3) etc. instead. +.PP +\&\fIDES_quad_cksum()\fR is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on \fIout_count\fR, 1, 2, 3 or 4 times. If \fIoutput\fR is +non-NULL, the 8 bytes generated by each pass are written into +\&\fIoutput\fR. +.PP +The following are DES-based transformations: +.PP +\&\fIDES_fcrypt()\fR is a fast version of the Unix \fIcrypt\fR\|(3) function. This +version takes only a small amount of space relative to other fast +\&\fIcrypt()\fR implementations. This is different to the normal crypt in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal crypt. +.PP +\&\fIDES_crypt()\fR is a faster replacement for the normal system \fIcrypt()\fR. +This function calls \fIDES_fcrypt()\fR with a static array passed as the +third parameter. This emulates the normal non-thread safe semantics +of \fIcrypt\fR\|(3). +.PP +\&\fIDES_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from +buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default) +using \fIsched\fR for the key and \fIiv\fR as a starting vector. The actual +data send down \fIfd\fR consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. +.PP +\&\fIDES_enc_read()\fR is used to read \fIlen\fR bytes from file descriptor +\&\fIfd\fR into buffer \fIbuf\fR. The data being read from \fIfd\fR is assumed to +have come from \fIDES_enc_write()\fR and is decrypted using \fIsched\fR for +the key schedule and \fIiv\fR for the initial vector. +.PP +\&\fBWarning:\fR The data format used by \fIDES_enc_write()\fR and \fIDES_enc_read()\fR +has a cryptographic weakness: When asked to write more than \s-1MAXWRITE\s0 +bytes, \fIDES_enc_write()\fR will split the data into several chunks that +are all encrypted using the same \s-1IV. \s0 So don't use these functions +unless you are sure you know what you do (in which case you might not +want to use them anyway). They cannot handle non-blocking sockets. +\&\fIDES_enc_read()\fR uses an internal state and thus cannot be used on +multiple files. +.PP +\&\fIDES_rw_mode\fR is used to specify the encryption mode to use with +\&\fIDES_enc_read()\fR and \fIDES_end_write()\fR. If set to \fI\s-1DES_PCBC_MODE\s0\fR (the +default), DES_pcbc_encrypt is used. If set to \fI\s-1DES_CBC_MODE\s0\fR +DES_cbc_encrypt is used. +.SH "NOTES" +.IX Header "NOTES" +Single-key \s-1DES\s0 is insecure due to its short key size. \s-1ECB\s0 mode is +not suitable for most applications; see \fIdes_modes\fR\|(7). +.PP +The \fIopenssl_evp\fR\|(3) library provides higher-level encryption functions. +.SH "BUGS" +.IX Header "BUGS" +\&\fIDES_3cbc_encrypt()\fR is flawed and must not be used in applications. +.PP +\&\fIDES_cbc_encrypt()\fR does not modify \fBivec\fR; use \fIDES_ncbc_encrypt()\fR +instead. +.PP +\&\fIDES_cfb_encrypt()\fR and \fIDES_ofb_encrypt()\fR operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! +.PP +\&\fIDES_string_to_key()\fR is available for backward compatibility with the +\&\s-1MIT\s0 library. New applications should use a cryptographic hash function. +The same applies for \fIDES_string_to_2key()\fR. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ANSI X3.106\s0 +.PP +The \fBdes\fR library was written to be source code compatible with +the \s-1MIT\s0 Kerberos library. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypt\fR\|(3), \fIdes_modes\fR\|(7), \fIopenssl_evp\fR\|(3), \fIopenssl_rand\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +In OpenSSL 0.9.7, all des_ functions were renamed to \s-1DES_\s0 to avoid +clashes with older versions of libdes. Compatibility des_ functions +are provided for a short while, as well as \fIcrypt()\fR. +Declarations for these are in <openssl/des_old.h>. There is no \s-1DES_\s0 +variant for \fIdes_random_seed()\fR. +This will happen to other functions +as well if they are deemed redundant (\fIdes_random_seed()\fR just calls +\&\fIRAND_seed()\fR and is present for backward compatibility only), buggy or +already scheduled for removal. +.PP +\&\fIdes_cbc_cksum()\fR, \fIdes_cbc_encrypt()\fR, \fIdes_ecb_encrypt()\fR, +\&\fIdes_is_weak_key()\fR, \fIdes_key_sched()\fR, \fIdes_pcbc_encrypt()\fR, +\&\fIdes_quad_cksum()\fR, \fIdes_random_key()\fR and \fIdes_string_to_key()\fR +are available in the \s-1MIT\s0 Kerberos library; +\&\fIdes_check_key_parity()\fR, \fIdes_fixup_key_parity()\fR and \fIdes_is_weak_key()\fR +are available in newer versions of that library. +.PP +\&\fIdes_set_key_checked()\fR and \fIdes_set_key_unchecked()\fR were added in +OpenSSL 0.9.5. +.PP +\&\fIdes_generate_random_block()\fR, \fIdes_init_random_number_generator()\fR, +\&\fIdes_new_random_key()\fR, \fIdes_set_random_generator_seed()\fR and +\&\fIdes_set_sequence_number()\fR and \fIdes_rand_data()\fR are used in newer +versions of Kerberos but are not implemented here. +.PP +\&\fIdes_random_key()\fR generated cryptographically weak random data in +SSLeay and in OpenSSL prior version 0.9.5, as well as in the original +\&\s-1MIT\s0 library. +.SH "AUTHOR" +.IX Header "AUTHOR" +Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project +(http://www.openssl.org). diff --git a/static/netbsd/man3/openssl_dh.3 b/static/netbsd/man3/openssl_dh.3 new file mode 100644 index 00000000..3a473824 --- /dev/null +++ b/static/netbsd/man3/openssl_dh.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: openssl_dh.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "dh 3" +.TH dh 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +dh \- Diffie\-Hellman key agreement +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/dh.h> +\& #include <openssl/engine.h> +\& +\& DH * DH_new(void); +\& void DH_free(DH *dh); +\& +\& int DH_size(const DH *dh); +\& +\& DH * DH_generate_parameters(int prime_len, int generator, +\& void (*callback)(int, int, void *), void *cb_arg); +\& int DH_check(const DH *dh, int *codes); +\& +\& int DH_generate_key(DH *dh); +\& int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); +\& +\& void DH_set_default_method(const DH_METHOD *meth); +\& const DH_METHOD *DH_get_default_method(void); +\& int DH_set_method(DH *dh, const DH_METHOD *meth); +\& DH *DH_new_method(ENGINE *engine); +\& const DH_METHOD *DH_OpenSSL(void); +\& +\& int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), +\& int (*dup_func)(), void (*free_func)()); +\& int DH_set_ex_data(DH *d, int idx, char *arg); +\& char *DH_get_ex_data(DH *d, int idx); +\& +\& DH * d2i_DHparams(DH **a, unsigned char **pp, long length); +\& int i2d_DHparams(const DH *a, unsigned char **pp); +\& +\& int DHparams_print_fp(FILE *fp, const DH *x); +\& int DHparams_print(BIO *bp, const DH *x); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions implement the Diffie-Hellman key agreement protocol. +The generation of shared \s-1DH\s0 parameters is described in +\&\fIDH_generate_parameters\fR\|(3); \fIDH_generate_key\fR\|(3) describes how +to perform a key agreement. +.PP +The \fB\s-1DH\s0\fR structure consists of several \s-1BIGNUM\s0 components. +.PP +.Vb 9 +\& struct +\& { +\& BIGNUM *p; // prime number (shared) +\& BIGNUM *g; // generator of Z_p (shared) +\& BIGNUM *priv_key; // private DH value x +\& BIGNUM *pub_key; // public DH value g^x +\& // ... +\& }; +\& DH +.Ve +.PP +Note that \s-1DH\s0 keys may use non-standard \fB\s-1DH_METHOD\s0\fR implementations, +either directly or by the use of \fB\s-1ENGINE\s0\fR modules. In some cases (eg. an +\&\s-1ENGINE\s0 providing support for hardware-embedded keys), these \s-1BIGNUM\s0 values +will not be used by the implementation or may be used for alternative data +storage. For this reason, applications should generally avoid using \s-1DH\s0 +structure elements directly and instead use \s-1API\s0 functions to query or +modify keys. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_dhparam\fR\|(1), \fIopenssl_bn\fR\|(3), \fIopenssl_dsa\fR\|(3), \fIopenssl_err\fR\|(3), +\&\fIopenssl_rand\fR\|(3), \fIopenssl_rsa\fR\|(3), \fIengine\fR\|(3), +\&\fIDH_set_method\fR\|(3), \fIDH_new\fR\|(3), +\&\fIDH_get_ex_new_index\fR\|(3), +\&\fIDH_generate_parameters\fR\|(3), +\&\fIDH_compute_key\fR\|(3), \fId2i_DHparams\fR\|(3), +\&\fIRSA_print\fR\|(3) diff --git a/static/netbsd/man3/openssl_dsa.3 b/static/netbsd/man3/openssl_dsa.3 new file mode 100644 index 00000000..84110a91 --- /dev/null +++ b/static/netbsd/man3/openssl_dsa.3 @@ -0,0 +1,249 @@ +.\" $NetBSD: openssl_dsa.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "dsa 3" +.TH dsa 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +dsa \- Digital Signature Algorithm +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/dsa.h> +\& #include <openssl/engine.h> +\& +\& DSA * DSA_new(void); +\& void DSA_free(DSA *dsa); +\& +\& int DSA_size(const DSA *dsa); +\& +\& DSA * DSA_generate_parameters(int bits, unsigned char *seed, +\& int seed_len, int *counter_ret, unsigned long *h_ret, +\& void (*callback)(int, int, void *), void *cb_arg); +\& +\& DH * DSA_dup_DH(const DSA *r); +\& +\& int DSA_generate_key(DSA *dsa); +\& +\& int DSA_sign(int dummy, const unsigned char *dgst, int len, +\& unsigned char *sigret, unsigned int *siglen, DSA *dsa); +\& int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, +\& BIGNUM **rp); +\& int DSA_verify(int dummy, const unsigned char *dgst, int len, +\& const unsigned char *sigbuf, int siglen, DSA *dsa); +\& +\& void DSA_set_default_method(const DSA_METHOD *meth); +\& const DSA_METHOD *DSA_get_default_method(void); +\& int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); +\& DSA *DSA_new_method(ENGINE *engine); +\& const DSA_METHOD *DSA_OpenSSL(void); +\& +\& int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), +\& int (*dup_func)(), void (*free_func)()); +\& int DSA_set_ex_data(DSA *d, int idx, char *arg); +\& char *DSA_get_ex_data(DSA *d, int idx); +\& +\& DSA_SIG *DSA_SIG_new(void); +\& void DSA_SIG_free(DSA_SIG *a); +\& int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); +\& DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); +\& +\& DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); +\& int DSA_do_verify(const unsigned char *dgst, int dgst_len, +\& DSA_SIG *sig, DSA *dsa); +\& +\& DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); +\& DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); +\& DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); +\& int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); +\& int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); +\& int i2d_DSAparams(const DSA *a,unsigned char **pp); +\& +\& int DSAparams_print(BIO *bp, const DSA *x); +\& int DSAparams_print_fp(FILE *fp, const DSA *x); +\& int DSA_print(BIO *bp, const DSA *x, int off); +\& int DSA_print_fp(FILE *bp, const DSA *x, int off); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions implement the Digital Signature Algorithm (\s-1DSA\s0). The +generation of shared \s-1DSA\s0 parameters is described in +\&\fIDSA_generate_parameters\fR\|(3); +\&\fIDSA_generate_key\fR\|(3) describes how to +generate a signature key. Signature generation and verification are +described in \fIDSA_sign\fR\|(3). +.PP +The \fB\s-1DSA\s0\fR structure consists of several \s-1BIGNUM\s0 components. +.PP +.Vb 10 +\& struct +\& { +\& BIGNUM *p; // prime number (public) +\& BIGNUM *q; // 160\-bit subprime, q | p\-1 (public) +\& BIGNUM *g; // generator of subgroup (public) +\& BIGNUM *priv_key; // private key x +\& BIGNUM *pub_key; // public key y = g^x +\& // ... +\& } +\& DSA; +.Ve +.PP +In public keys, \fBpriv_key\fR is \s-1NULL.\s0 +.PP +Note that \s-1DSA\s0 keys may use non-standard \fB\s-1DSA_METHOD\s0\fR implementations, +either directly or by the use of \fB\s-1ENGINE\s0\fR modules. In some cases (eg. an +\&\s-1ENGINE\s0 providing support for hardware-embedded keys), these \s-1BIGNUM\s0 values +will not be used by the implementation or may be used for alternative data +storage. For this reason, applications should generally avoid using \s-1DSA\s0 +structure elements directly and instead use \s-1API\s0 functions to query or +modify keys. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1US\s0 Federal Information Processing Standard \s-1FIPS 186 \s0(Digital Signature +Standard, \s-1DSS\s0), \s-1ANSI X9.30\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_bn\fR\|(3), \fIopenssl_dh\fR\|(3), \fIopenssl_err\fR\|(3), \fIopenssl_rand\fR\|(3), +\&\fIopenssl_rsa\fR\|(3), \fIopenssl_sha\fR\|(3), \fIengine\fR\|(3), +\&\fIDSA_new\fR\|(3), +\&\fIDSA_size\fR\|(3), +\&\fIDSA_generate_parameters\fR\|(3), +\&\fIDSA_dup_DH\fR\|(3), +\&\fIDSA_generate_key\fR\|(3), +\&\fIDSA_sign\fR\|(3), \fIDSA_set_method\fR\|(3), +\&\fIDSA_get_ex_new_index\fR\|(3), +\&\fIRSA_print\fR\|(3) diff --git a/static/netbsd/man3/openssl_ecdsa.3 b/static/netbsd/man3/openssl_ecdsa.3 new file mode 100644 index 00000000..9800cae0 --- /dev/null +++ b/static/netbsd/man3/openssl_ecdsa.3 @@ -0,0 +1,349 @@ +.\" $NetBSD: openssl_ecdsa.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ecdsa 3" +.TH ecdsa 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify \- Elliptic Curve Digital Signature Algorithm +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ecdsa.h> +\& +\& ECDSA_SIG* ECDSA_SIG_new(void); +\& void ECDSA_SIG_free(ECDSA_SIG *sig); +\& int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); +\& ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, +\& long len); +\& +\& ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, +\& EC_KEY *eckey); +\& ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, +\& const BIGNUM *kinv, const BIGNUM *rp, +\& EC_KEY *eckey); +\& int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, +\& const ECDSA_SIG *sig, EC_KEY* eckey); +\& int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, +\& BIGNUM **kinv, BIGNUM **rp); +\& int ECDSA_sign(int type, const unsigned char *dgst, +\& int dgstlen, unsigned char *sig, +\& unsigned int *siglen, EC_KEY *eckey); +\& int ECDSA_sign_ex(int type, const unsigned char *dgst, +\& int dgstlen, unsigned char *sig, +\& unsigned int *siglen, const BIGNUM *kinv, +\& const BIGNUM *rp, EC_KEY *eckey); +\& int ECDSA_verify(int type, const unsigned char *dgst, +\& int dgstlen, const unsigned char *sig, +\& int siglen, EC_KEY *eckey); +\& int ECDSA_size(const EC_KEY *eckey); +\& +\& const ECDSA_METHOD* ECDSA_OpenSSL(void); +\& void ECDSA_set_default_method(const ECDSA_METHOD *meth); +\& const ECDSA_METHOD* ECDSA_get_default_method(void); +\& int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); +\& +\& int ECDSA_get_ex_new_index(long argl, void *argp, +\& CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, +\& CRYPTO_EX_free *free_func); +\& int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); +\& void* ECDSA_get_ex_data(EC_KEY *d, int idx); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fB\s-1ECDSA_SIG\s0\fR structure consists of two BIGNUMs for the +r and s value of a \s-1ECDSA\s0 signature (see X9.62 or \s-1FIPS 186\-2\s0). +.PP +.Vb 5 +\& struct +\& { +\& BIGNUM *r; +\& BIGNUM *s; +\& } ECDSA_SIG; +.Ve +.PP +\&\fIECDSA_SIG_new()\fR allocates a new \fB\s-1ECDSA_SIG\s0\fR structure (note: this +function also allocates the BIGNUMs) and initialize it. +.PP +\&\fIECDSA_SIG_free()\fR frees the \fB\s-1ECDSA_SIG\s0\fR structure \fBsig\fR. +.PP +\&\fIi2d_ECDSA_SIG()\fR creates the \s-1DER\s0 encoding of the \s-1ECDSA\s0 signature +\&\fBsig\fR and writes the encoded signature to \fB*pp\fR (note: if \fBpp\fR +is \s-1NULL \s0\fBi2d_ECDSA_SIG\fR returns the expected length in bytes of +the \s-1DER\s0 encoded signature). \fBi2d_ECDSA_SIG\fR returns the length +of the \s-1DER\s0 encoded signature (or 0 on error). +.PP +\&\fId2i_ECDSA_SIG()\fR decodes a \s-1DER\s0 encoded \s-1ECDSA\s0 signature and returns +the decoded signature in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure. +\&\fB*sig\fR points to the buffer containing the \s-1DER\s0 encoded signature +of size \fBlen\fR. +.PP +\&\fIECDSA_size()\fR returns the maximum length of a \s-1DER\s0 encoded +\&\s-1ECDSA\s0 signature created with the private \s-1EC\s0 key \fBeckey\fR. +.PP +\&\fIECDSA_sign_setup()\fR may be used to precompute parts of the +signing operation. \fBeckey\fR is the private \s-1EC\s0 key and \fBctx\fR +is a pointer to \fB\s-1BN_CTX\s0\fR structure (or \s-1NULL\s0). The precomputed +values or returned in \fBkinv\fR and \fBrp\fR and can be used in a +later call to \fBECDSA_sign_ex\fR or \fBECDSA_do_sign_ex\fR. +.PP +\&\fIECDSA_sign()\fR is wrapper function for ECDSA_sign_ex with \fBkinv\fR +and \fBrp\fR set to \s-1NULL.\s0 +.PP +\&\fIECDSA_sign_ex()\fR computes a digital signature of the \fBdgstlen\fR bytes +hash value \fBdgst\fR using the private \s-1EC\s0 key \fBeckey\fR and the optional +pre-computed values \fBkinv\fR and \fBrp\fR. The \s-1DER\s0 encoded signatures is +stored in \fBsig\fR and it's length is returned in \fBsig_len\fR. Note: \fBsig\fR +must point to \fBECDSA_size\fR bytes of memory. The parameter \fBtype\fR +is ignored. +.PP +\&\fIECDSA_verify()\fR verifies that the signature in \fBsig\fR of size +\&\fBsiglen\fR is a valid \s-1ECDSA\s0 signature of the hash value +\&\fBdgst\fR of size \fBdgstlen\fR using the public key \fBeckey\fR. +The parameter \fBtype\fR is ignored. +.PP +\&\fIECDSA_do_sign()\fR is wrapper function for ECDSA_do_sign_ex with \fBkinv\fR +and \fBrp\fR set to \s-1NULL.\s0 +.PP +\&\fIECDSA_do_sign_ex()\fR computes a digital signature of the \fBdgst_len\fR +bytes hash value \fBdgst\fR using the private key \fBeckey\fR and the +optional pre-computed values \fBkinv\fR and \fBrp\fR. The signature is +returned in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure (or \s-1NULL\s0 on error). +.PP +\&\fIECDSA_do_verify()\fR verifies that the signature \fBsig\fR is a valid +\&\s-1ECDSA\s0 signature of the hash value \fBdgst\fR of size \fBdgst_len\fR +using the public key \fBeckey\fR. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fIECDSA_size()\fR returns the maximum length signature or 0 on error. +.PP +\&\fIECDSA_sign_setup()\fR and \fIECDSA_sign()\fR return 1 if successful or 0 +on error. +.PP +\&\fIECDSA_verify()\fR and \fIECDSA_do_verify()\fR return 1 for a valid +signature, 0 for an invalid signature and \-1 on error. +The error codes can be obtained by \fIERR_get_error\fR\|(3). +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Creating a \s-1ECDSA\s0 signature of given \s-1SHA\-1\s0 hash value using the +named curve secp192k1. +.PP +First step: create a \s-1EC_KEY\s0 object (note: this part is \fBnot\fR \s-1ECDSA\s0 +specific) +.PP +.Vb 12 +\& int ret; +\& ECDSA_SIG *sig; +\& EC_KEY *eckey; +\& eckey = EC_KEY_new_by_curve_name(NID_secp192k1); +\& if (eckey == NULL) +\& { +\& /* error */ +\& } +\& if (!EC_KEY_generate_key(eckey)) +\& { +\& /* error */ +\& } +.Ve +.PP +Second step: compute the \s-1ECDSA\s0 signature of a \s-1SHA\-1\s0 hash value +using \fBECDSA_do_sign\fR +.PP +.Vb 5 +\& sig = ECDSA_do_sign(digest, 20, eckey); +\& if (sig == NULL) +\& { +\& /* error */ +\& } +.Ve +.PP +or using \fBECDSA_sign\fR +.PP +.Vb 9 +\& unsigned char *buffer, *pp; +\& int buf_len; +\& buf_len = ECDSA_size(eckey); +\& buffer = OPENSSL_malloc(buf_len); +\& pp = buffer; +\& if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey); +\& { +\& /* error */ +\& } +.Ve +.PP +Third step: verify the created \s-1ECDSA\s0 signature using \fBECDSA_do_verify\fR +.PP +.Vb 1 +\& ret = ECDSA_do_verify(digest, 20, sig, eckey); +.Ve +.PP +or using \fBECDSA_verify\fR +.PP +.Vb 1 +\& ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); +.Ve +.PP +and finally evaluate the return value: +.PP +.Vb 12 +\& if (ret == \-1) +\& { +\& /* error */ +\& } +\& else if (ret == 0) +\& { +\& /* incorrect signature */ +\& } +\& else /* ret == 1 */ +\& { +\& /* signature ok */ +\& } +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ANSI X9.62, US\s0 Federal Information Processing Standard \s-1FIPS 186\-2 +\&\s0(Digital Signature Standard, \s-1DSS\s0) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_dsa\fR\|(3), \fIopenssl_rsa\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The ecdsa implementation was first introduced in OpenSSL 0.9.8 +.SH "AUTHOR" +.IX Header "AUTHOR" +Nils Larsch for the OpenSSL project (http://www.openssl.org). diff --git a/static/netbsd/man3/openssl_engine.3 b/static/netbsd/man3/openssl_engine.3 new file mode 100644 index 00000000..495c0099 --- /dev/null +++ b/static/netbsd/man3/openssl_engine.3 @@ -0,0 +1,746 @@ +.\" $NetBSD: openssl_engine.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "engine 3" +.TH engine 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +engine \- ENGINE cryptographic module support +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/engine.h> +\& +\& ENGINE *ENGINE_get_first(void); +\& ENGINE *ENGINE_get_last(void); +\& ENGINE *ENGINE_get_next(ENGINE *e); +\& ENGINE *ENGINE_get_prev(ENGINE *e); +\& +\& int ENGINE_add(ENGINE *e); +\& int ENGINE_remove(ENGINE *e); +\& +\& ENGINE *ENGINE_by_id(const char *id); +\& +\& int ENGINE_init(ENGINE *e); +\& int ENGINE_finish(ENGINE *e); +\& +\& void ENGINE_load_openssl(void); +\& void ENGINE_load_dynamic(void); +\& #ifndef OPENSSL_NO_STATIC_ENGINE +\& void ENGINE_load_4758cca(void); +\& void ENGINE_load_aep(void); +\& void ENGINE_load_atalla(void); +\& void ENGINE_load_chil(void); +\& void ENGINE_load_cswift(void); +\& void ENGINE_load_gmp(void); +\& void ENGINE_load_nuron(void); +\& void ENGINE_load_sureware(void); +\& void ENGINE_load_ubsec(void); +\& #endif +\& void ENGINE_load_cryptodev(void); +\& void ENGINE_load_builtin_engines(void); +\& +\& void ENGINE_cleanup(void); +\& +\& ENGINE *ENGINE_get_default_RSA(void); +\& ENGINE *ENGINE_get_default_DSA(void); +\& ENGINE *ENGINE_get_default_ECDH(void); +\& ENGINE *ENGINE_get_default_ECDSA(void); +\& ENGINE *ENGINE_get_default_DH(void); +\& ENGINE *ENGINE_get_default_RAND(void); +\& ENGINE *ENGINE_get_cipher_engine(int nid); +\& ENGINE *ENGINE_get_digest_engine(int nid); +\& +\& int ENGINE_set_default_RSA(ENGINE *e); +\& int ENGINE_set_default_DSA(ENGINE *e); +\& int ENGINE_set_default_ECDH(ENGINE *e); +\& int ENGINE_set_default_ECDSA(ENGINE *e); +\& int ENGINE_set_default_DH(ENGINE *e); +\& int ENGINE_set_default_RAND(ENGINE *e); +\& int ENGINE_set_default_ciphers(ENGINE *e); +\& int ENGINE_set_default_digests(ENGINE *e); +\& int ENGINE_set_default_string(ENGINE *e, const char *list); +\& +\& int ENGINE_set_default(ENGINE *e, unsigned int flags); +\& +\& unsigned int ENGINE_get_table_flags(void); +\& void ENGINE_set_table_flags(unsigned int flags); +\& +\& int ENGINE_register_RSA(ENGINE *e); +\& void ENGINE_unregister_RSA(ENGINE *e); +\& void ENGINE_register_all_RSA(void); +\& int ENGINE_register_DSA(ENGINE *e); +\& void ENGINE_unregister_DSA(ENGINE *e); +\& void ENGINE_register_all_DSA(void); +\& int ENGINE_register_ECDH(ENGINE *e); +\& void ENGINE_unregister_ECDH(ENGINE *e); +\& void ENGINE_register_all_ECDH(void); +\& int ENGINE_register_ECDSA(ENGINE *e); +\& void ENGINE_unregister_ECDSA(ENGINE *e); +\& void ENGINE_register_all_ECDSA(void); +\& int ENGINE_register_DH(ENGINE *e); +\& void ENGINE_unregister_DH(ENGINE *e); +\& void ENGINE_register_all_DH(void); +\& int ENGINE_register_RAND(ENGINE *e); +\& void ENGINE_unregister_RAND(ENGINE *e); +\& void ENGINE_register_all_RAND(void); +\& int ENGINE_register_STORE(ENGINE *e); +\& void ENGINE_unregister_STORE(ENGINE *e); +\& void ENGINE_register_all_STORE(void); +\& int ENGINE_register_ciphers(ENGINE *e); +\& void ENGINE_unregister_ciphers(ENGINE *e); +\& void ENGINE_register_all_ciphers(void); +\& int ENGINE_register_digests(ENGINE *e); +\& void ENGINE_unregister_digests(ENGINE *e); +\& void ENGINE_register_all_digests(void); +\& int ENGINE_register_complete(ENGINE *e); +\& int ENGINE_register_all_complete(void); +\& +\& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); +\& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); +\& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, +\& long i, void *p, void (*f)(void), int cmd_optional); +\& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, +\& int cmd_optional); +\& +\& int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); +\& void *ENGINE_get_ex_data(const ENGINE *e, int idx); +\& +\& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, +\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); +\& +\& ENGINE *ENGINE_new(void); +\& int ENGINE_free(ENGINE *e); +\& int ENGINE_up_ref(ENGINE *e); +\& +\& int ENGINE_set_id(ENGINE *e, const char *id); +\& int ENGINE_set_name(ENGINE *e, const char *name); +\& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); +\& int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); +\& int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); +\& int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); +\& int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); +\& int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); +\& int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); +\& int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); +\& int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); +\& int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); +\& int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); +\& int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); +\& int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); +\& int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); +\& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); +\& int ENGINE_set_flags(ENGINE *e, int flags); +\& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); +\& +\& const char *ENGINE_get_id(const ENGINE *e); +\& const char *ENGINE_get_name(const ENGINE *e); +\& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); +\& const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); +\& const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); +\& const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); +\& const DH_METHOD *ENGINE_get_DH(const ENGINE *e); +\& const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); +\& const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); +\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); +\& ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); +\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); +\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); +\& ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); +\& ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); +\& const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); +\& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); +\& int ENGINE_get_flags(const ENGINE *e); +\& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); +\& +\& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, +\& UI_METHOD *ui_method, void *callback_data); +\& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, +\& UI_METHOD *ui_method, void *callback_data); +\& +\& void ENGINE_add_conf_module(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions create, manipulate, and use cryptographic modules in the +form of \fB\s-1ENGINE\s0\fR objects. These objects act as containers for +implementations of cryptographic algorithms, and support a +reference-counted mechanism to allow them to be dynamically loaded in and +out of the running application. +.PP +The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR +implementation includes the following abstractions; +.PP +.Vb 6 +\& RSA_METHOD \- for providing alternative RSA implementations +\& DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, +\& STORE_METHOD \- similarly for other OpenSSL APIs +\& EVP_CIPHER \- potentially multiple cipher algorithms (indexed by \*(Aqnid\*(Aq) +\& EVP_DIGEST \- potentially multiple hash algorithms (indexed by \*(Aqnid\*(Aq) +\& key\-loading \- loading public and/or private EVP_PKEY keys +.Ve +.SS "Reference counting and handles" +.IX Subsection "Reference counting and handles" +Due to the modular nature of the \s-1ENGINE API,\s0 pointers to ENGINEs need to be +treated as handles \- ie. not only as pointers, but also as references to +the underlying \s-1ENGINE\s0 object. Ie. one should obtain a new reference when +making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and +released) independently. +.PP +\&\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in +which the objects are used. At the most basic level, each \s-1ENGINE\s0 pointer is +inherently a \fBstructural\fR reference \- a structural reference is required +to use the pointer value at all, as this kind of reference is a guarantee +that the structure can not be deallocated until the reference is released. +.PP +However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is +initialised and able to use any of its cryptographic +implementations. Indeed it's quite possible that most ENGINEs will not +initialise at all in typical environments, as ENGINEs are typically used to +support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a +\&\fBfunctional\fR reference. This kind of reference can be considered a +specialised form of structural reference, because each functional reference +implicitly contains a structural reference as well \- however to avoid +difficult-to-find programming bugs, it is recommended to treat the two +kinds of reference independently. If you have a functional reference to an +\&\s-1ENGINE,\s0 you have a guarantee that the \s-1ENGINE\s0 has been initialised and +is ready to perform cryptographic operations, and will remain initialised +until after you have released your reference. +.PP +\&\fIStructural references\fR +.PP +This basic type of reference is used for instantiating new ENGINEs, +iterating across OpenSSL's internal linked-list of loaded +ENGINEs, reading information about an \s-1ENGINE,\s0 etc. Essentially a structural +reference is sufficient if you only need to query or manipulate the data of +an \s-1ENGINE\s0 implementation rather than use its functionality. +.PP +The \fIENGINE_new()\fR function returns a structural reference to a new (empty) +\&\s-1ENGINE\s0 object. There are other \s-1ENGINE API\s0 functions that return structural +references such as; \fIENGINE_by_id()\fR, \fIENGINE_get_first()\fR, \fIENGINE_get_last()\fR, +\&\fIENGINE_get_next()\fR, \fIENGINE_get_prev()\fR. All structural references should be +released by a corresponding to call to the \fIENGINE_free()\fR function \- the +\&\s-1ENGINE\s0 object itself will only actually be cleaned up and deallocated when +the last structural reference is released. +.PP +It should also be noted that many \s-1ENGINE API\s0 function calls that accept a +structural reference will internally obtain another reference \- typically +this happens whenever the supplied \s-1ENGINE\s0 will be needed by OpenSSL after +the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to +OpenSSL's internal list is \fIENGINE_add()\fR \- if this function returns success, +then OpenSSL will have stored a new structural reference internally so the +caller is still responsible for freeing their own reference with +\&\fIENGINE_free()\fR when they are finished with it. In a similar way, some +functions will automatically release the structural reference passed to it +if part of the function's job is to do so. Eg. the \fIENGINE_get_next()\fR and +\&\fIENGINE_get_prev()\fR functions are used for iterating across the internal +\&\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or +previous) \s-1ENGINE\s0 in the list or \s-1NULL\s0 if at the end (or beginning) of the +list, but in either case the structural reference passed to the function is +released on behalf of the caller. +.PP +To clarify a particular function's handling of references, one should +always consult that function's documentation \*(L"man\*(R" page, or failing that +the openssl/engine.h header file includes some hints. +.PP +\&\fIFunctional references\fR +.PP +As mentioned, functional references exist when the cryptographic +functionality of an \s-1ENGINE\s0 is required to be available. A functional +reference can be obtained in one of two ways; from an existing structural +reference to the required \s-1ENGINE,\s0 or by asking OpenSSL for the default +operational \s-1ENGINE\s0 for a given cryptographic purpose. +.PP +To obtain a functional reference from an existing structural reference, +call the \fIENGINE_init()\fR function. This returns zero if the \s-1ENGINE\s0 was not +already operational and couldn't be successfully initialised (eg. lack of +system drivers, no special hardware attached, etc), otherwise it will +return non-zero to indicate that the \s-1ENGINE\s0 is now operational and will +have allocated a new \fBfunctional\fR reference to the \s-1ENGINE.\s0 All functional +references are released by calling \fIENGINE_finish()\fR (which removes the +implicit structural reference as well). +.PP +The second way to get a functional reference is by asking OpenSSL for a +default implementation for a given task, eg. by \fIENGINE_get_default_RSA()\fR, +\&\fIENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next +section, though they are not usually required by application programmers as +they are used automatically when creating and using the relevant +algorithm-specific types in OpenSSL, such as \s-1RSA, DSA, EVP_CIPHER_CTX,\s0 etc. +.SS "Default implementations" +.IX Subsection "Default implementations" +For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table +of state to control which implementations are available for a given +abstraction and which should be used by default. These implementations are +registered in the tables and indexed by an 'nid' value, because +abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct +algorithms and modes, and ENGINEs can support arbitrarily many of them. +In the case of other abstractions like \s-1RSA, DSA,\s0 etc, there is only one +\&\*(L"algorithm\*(R" so all implementations implicitly register using the same 'nid' +index. +.PP +When a default \s-1ENGINE\s0 is requested for a given abstraction/algorithm/mode, (eg. +when calling RSA_new_method(\s-1NULL\s0)), a \*(L"get_default\*(R" call will be made to the +\&\s-1ENGINE\s0 subsystem to process the corresponding state table and return a +functional reference to an initialised \s-1ENGINE\s0 whose implementation should be +used. If no \s-1ENGINE\s0 should (or can) be used, it will return \s-1NULL\s0 and the caller +will operate with a \s-1NULL ENGINE\s0 handle \- this usually equates to using the +conventional software implementation. In the latter case, OpenSSL will from +then on behave the way it used to before the \s-1ENGINE API\s0 existed. +.PP +Each state table has a flag to note whether it has processed this +\&\*(L"get_default\*(R" query since the table was last modified, because to process +this question it must iterate across all the registered ENGINEs in the +table trying to initialise each of them in turn, in case one of them is +operational. If it returns a functional reference to an \s-1ENGINE,\s0 it will +also cache another reference to speed up processing future queries (without +needing to iterate across the table). Likewise, it will cache a \s-1NULL\s0 +response if no \s-1ENGINE\s0 was available so that future queries won't repeat the +same iteration unless the state table changes. This behaviour can also be +changed; if the \s-1ENGINE_TABLE_FLAG_NOINIT\s0 flag is set (using +\&\fIENGINE_set_table_flags()\fR), no attempted initialisations will take place, +instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to the +\&\*(L"get_default\*(R" query will be if one is expressly set in the table. Eg. +\&\fIENGINE_set_default_RSA()\fR does the same job as \fIENGINE_register_RSA()\fR except +that it also sets the state table's cached response for the \*(L"get_default\*(R" +query. In the case of abstractions like \s-1EVP_CIPHER,\s0 where implementations are +indexed by 'nid', these flags and cached-responses are distinct for each 'nid' +value. +.SS "Application requirements" +.IX Subsection "Application requirements" +This section will explain the basic things an application programmer should +support to make the most useful elements of the \s-1ENGINE\s0 functionality +available to the user. The first thing to consider is whether the +programmer wishes to make alternative \s-1ENGINE\s0 modules available to the +application and user. OpenSSL maintains an internal linked list of +\&\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is +empty and in fact if an application does not call any \s-1ENGINE API\s0 calls and +it uses static linking against openssl, then the resulting application +binary will not contain any alternative \s-1ENGINE\s0 code at all. So the first +consideration is whether any/all available \s-1ENGINE\s0 implementations should be +made visible to OpenSSL \- this is controlled by calling the various \*(L"load\*(R" +functions, eg. +.PP +.Vb 9 +\& /* Make the "dynamic" ENGINE available */ +\& void ENGINE_load_dynamic(void); +\& /* Make the CryptoSwift hardware acceleration support available */ +\& void ENGINE_load_cswift(void); +\& /* Make support for nCipher\*(Aqs "CHIL" hardware available */ +\& void ENGINE_load_chil(void); +\& ... +\& /* Make ALL ENGINE implementations bundled with OpenSSL available */ +\& void ENGINE_load_builtin_engines(void); +.Ve +.PP +Having called any of these functions, \s-1ENGINE\s0 objects would have been +dynamically allocated and populated with these implementations and linked +into OpenSSL's internal linked list. At this point it is important to +mention an important \s-1API\s0 function; +.PP +.Vb 1 +\& void ENGINE_cleanup(void); +.Ve +.PP +If no \s-1ENGINE API\s0 functions are called at all in an application, then there +are no inherent memory leaks to worry about from the \s-1ENGINE\s0 functionality, +however if any ENGINEs are loaded, even if they are never registered or +used, it is necessary to use the \fIENGINE_cleanup()\fR function to +correspondingly cleanup before program exit, if the caller wishes to avoid +memory leaks. This mechanism uses an internal callback registration table +so that any \s-1ENGINE API\s0 functionality that knows it requires cleanup can +register its cleanup details to be called during \fIENGINE_cleanup()\fR. This +approach allows \fIENGINE_cleanup()\fR to clean up after any \s-1ENGINE\s0 functionality +at all that your program uses, yet doesn't automatically create linker +dependencies to all possible \s-1ENGINE\s0 functionality \- only the cleanup +callbacks required by the functionality you do use will be required by the +linker. +.PP +The fact that ENGINEs are made visible to OpenSSL (and thus are linked into +the program and loaded into memory at run-time) does not mean they are +\&\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour +is something for the application to control. Some applications +will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used +if any is to be used at all. Others may prefer to load all support and have +OpenSSL automatically use at run-time any \s-1ENGINE\s0 that is able to +successfully initialise \- ie. to assume that this corresponds to +acceleration hardware attached to the machine or some such thing. There are +probably numerous other ways in which applications may prefer to handle +things, so we will simply illustrate the consequences as they apply to a +couple of simple cases and leave developers to consider these and the +source code to openssl's builtin utilities as guides. +.PP +\&\fIUsing a specific \s-1ENGINE\s0 implementation\fR +.PP +Here we'll assume an application has been configured by its user or admin +to want to use the \*(L"\s-1ACME\*(R" ENGINE\s0 if it is available in the version of +OpenSSL the application was compiled with. If it is available, it should be +used by default for all \s-1RSA, DSA,\s0 and symmetric cipher operations, otherwise +OpenSSL should use its builtin software as per usual. The following code +illustrates how to approach this; +.PP +.Vb 10 +\& ENGINE *e; +\& const char *engine_id = "ACME"; +\& ENGINE_load_builtin_engines(); +\& e = ENGINE_by_id(engine_id); +\& if(!e) +\& /* the engine isn\*(Aqt available */ +\& return; +\& if(!ENGINE_init(e)) { +\& /* the engine couldn\*(Aqt initialise, release \*(Aqe\*(Aq */ +\& ENGINE_free(e); +\& return; +\& } +\& if(!ENGINE_set_default_RSA(e)) +\& /* This should only happen when \*(Aqe\*(Aq can\*(Aqt initialise, but the previous +\& * statement suggests it did. */ +\& abort(); +\& ENGINE_set_default_DSA(e); +\& ENGINE_set_default_ciphers(e); +\& /* Release the functional reference from ENGINE_init() */ +\& ENGINE_finish(e); +\& /* Release the structural reference from ENGINE_by_id() */ +\& ENGINE_free(e); +.Ve +.PP +\&\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR +.PP +Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations +bundled with OpenSSL, such that for any cryptographic algorithm required by +OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialised, +it should be used. The following code illustrates how this can work; +.PP +.Vb 4 +\& /* Load all bundled ENGINEs into memory and make them visible */ +\& ENGINE_load_builtin_engines(); +\& /* Register all of them for every algorithm they collectively implement */ +\& ENGINE_register_all_complete(); +.Ve +.PP +That's all that's required. Eg. the next time OpenSSL tries to set up an +\&\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to +\&\fIENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the +default for \s-1RSA\s0 use from then on. +.SS "Advanced configuration support" +.IX Subsection "Advanced configuration support" +There is a mechanism supported by the \s-1ENGINE\s0 framework that allows each +\&\s-1ENGINE\s0 implementation to define an arbitrary set of configuration +\&\*(L"commands\*(R" and expose them to OpenSSL and any applications based on +OpenSSL. This mechanism is entirely based on the use of name-value pairs +and assumes \s-1ASCII\s0 input (no unicode or \s-1UTF\s0 for now!), so it is ideal if +applications want to provide a transparent way for users to provide +arbitrary configuration \*(L"directives\*(R" directly to such ENGINEs. It is also +possible for the application to dynamically interrogate the loaded \s-1ENGINE\s0 +implementations for the names, descriptions, and input flags of their +available \*(L"control commands\*(R", providing a more flexible configuration +scheme. However, if the user is expected to know which \s-1ENGINE\s0 device he/she +is using (in the case of specialised hardware, this goes without saying) +then applications may not need to concern themselves with discovering the +supported control commands and simply prefer to pass settings into ENGINEs +exactly as they are provided by the user. +.PP +Before illustrating how control commands work, it is worth mentioning what +they are typically used for. Broadly speaking there are two uses for +control commands; the first is to provide the necessary details to the +implementation (which may know nothing at all specific to the host system) +so that it can be initialised for use. This could include the path to any +driver or config files it needs to load, required network addresses, +smart-card identifiers, passwords to initialise protected devices, +logging information, etc etc. This class of commands typically needs to be +passed to an \s-1ENGINE \s0\fBbefore\fR attempting to initialise it, ie. before +calling \fIENGINE_init()\fR. The other class of commands consist of settings or +operations that tweak certain behaviour or cause certain operations to take +place, and these commands may work either before or after \fIENGINE_init()\fR, or +in some cases both. \s-1ENGINE\s0 implementations should provide indications of +this in the descriptions attached to builtin control commands and/or in +external product documentation. +.PP +\&\fIIssuing control commands to an \s-1ENGINE\s0\fR +.PP +Let's illustrate by example; a function for which the caller supplies the +name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use before +initialisation, and another table for use after initialisation. Note that +the string-pairs used for control commands consist of a command \*(L"name\*(R" +followed by the command \*(L"parameter\*(R" \- the parameter could be \s-1NULL\s0 in some +cases but the name can not. This function should initialise the \s-1ENGINE +\&\s0(issuing the \*(L"pre\*(R" commands beforehand and the \*(L"post\*(R" commands afterwards) +and set it as the default for everything except \s-1RAND\s0 and then return a +boolean success or failure. +.PP +.Vb 10 +\& int generic_load_engine_fn(const char *engine_id, +\& const char **pre_cmds, int pre_num, +\& const char **post_cmds, int post_num) +\& { +\& ENGINE *e = ENGINE_by_id(engine_id); +\& if(!e) return 0; +\& while(pre_num\-\-) { +\& if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, +\& pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); +\& ENGINE_free(e); +\& return 0; +\& } +\& pre_cmds += 2; +\& } +\& if(!ENGINE_init(e)) { +\& fprintf(stderr, "Failed initialisation\en"); +\& ENGINE_free(e); +\& return 0; +\& } +\& /* ENGINE_init() returned a functional reference, so free the structural +\& * reference from ENGINE_by_id(). */ +\& ENGINE_free(e); +\& while(post_num\-\-) { +\& if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, +\& post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); +\& ENGINE_finish(e); +\& return 0; +\& } +\& post_cmds += 2; +\& } +\& ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); +\& /* Success */ +\& return 1; +\& } +.Ve +.PP +Note that \fIENGINE_ctrl_cmd_string()\fR accepts a boolean argument that can +relax the semantics of the function \- if set non-zero it will only return +failure if the \s-1ENGINE\s0 supported the given command name but failed while +executing it, if the \s-1ENGINE\s0 doesn't support the command name it will simply +return success without doing anything. In this case we assume the user is +only supplying commands specific to the given \s-1ENGINE\s0 so we set this to +\&\s-1FALSE.\s0 +.PP +\&\fIDiscovering supported control commands\fR +.PP +It is possible to discover at run-time the names, numerical-ids, descriptions +and input parameters of the control commands supported by an \s-1ENGINE\s0 using a +structural reference. Note that some control commands are defined by OpenSSL +itself and it will intercept and handle these control commands on behalf of the +\&\s-1ENGINE,\s0 ie. the \s-1ENGINE\s0's \fIctrl()\fR handler is not used for the control command. +openssl/engine.h defines an index, \s-1ENGINE_CMD_BASE,\s0 that all control commands +implemented by ENGINEs should be numbered from. Any command value lower than +this symbol is considered a \*(L"generic\*(R" command is handled directly by the +OpenSSL core routines. +.PP +It is using these \*(L"core\*(R" control commands that one can discover the the control +commands implemented by a given \s-1ENGINE,\s0 specifically the commands; +.PP +.Vb 9 +\& #define ENGINE_HAS_CTRL_FUNCTION 10 +\& #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 +\& #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 +\& #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 +\& #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 +\& #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 +\& #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 +\& #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 +\& #define ENGINE_CTRL_GET_CMD_FLAGS 18 +.Ve +.PP +Whilst these commands are automatically processed by the OpenSSL framework code, +they use various properties exposed by each \s-1ENGINE\s0 to process these +queries. An \s-1ENGINE\s0 has 3 properties it exposes that can affect how this behaves; +it can supply a \fIctrl()\fR handler, it can specify \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 in +the \s-1ENGINE\s0's flags, and it can expose an array of control command descriptions. +If an \s-1ENGINE\s0 specifies the \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 flag, then it will +simply pass all these \*(L"core\*(R" control commands directly to the \s-1ENGINE\s0's \fIctrl()\fR +handler (and thus, it must have supplied one), so it is up to the \s-1ENGINE\s0 to +reply to these \*(L"discovery\*(R" commands itself. If that flag is not set, then the +OpenSSL framework code will work with the following rules; +.PP +.Vb 9 +\& if no ctrl() handler supplied; +\& ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), +\& all other commands fail. +\& if a ctrl() handler was supplied but no array of control commands; +\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, +\& all other commands fail. +\& if a ctrl() handler and array of control commands was supplied; +\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, +\& all other commands proceed processing ... +.Ve +.PP +If the \s-1ENGINE\s0's array of control commands is empty then all other commands will +fail, otherwise; \s-1ENGINE_CTRL_GET_FIRST_CMD_TYPE\s0 returns the identifier of +the first command supported by the \s-1ENGINE, ENGINE_GET_NEXT_CMD_TYPE\s0 takes the +identifier of a command supported by the \s-1ENGINE\s0 and returns the next command +identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a string +name for a command and returns the corresponding identifier or fails if no such +command name exists, and the remaining commands take a command identifier and +return properties of the corresponding commands. All except +\&\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description, +or populate a supplied character buffer with a copy of the command name or +description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-OR'd mask of the following +possible values; +.PP +.Vb 4 +\& #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 +\& #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 +\& #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 +\& #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 +.Ve +.PP +If the \s-1ENGINE_CMD_FLAG_INTERNAL\s0 flag is set, then any other flags are purely +informational to the caller \- this flag will prevent the command being usable +for any higher-level \s-1ENGINE\s0 functions such as \fIENGINE_ctrl_cmd_string()\fR. +\&\*(L"\s-1INTERNAL\*(R"\s0 commands are not intended to be exposed to text-based configuration +by applications, administrations, users, etc. These can support arbitrary +operations via \fIENGINE_ctrl()\fR, including passing to and/or from the control +commands data of any arbitrary type. These commands are supported in the +discovery mechanisms simply to allow applications determinie if an \s-1ENGINE\s0 +supports certain specific commands it might want to use (eg. application \*(L"foo\*(R" +might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\*(R" \-\s0 +and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific +extension). +.SS "Future developments" +.IX Subsection "Future developments" +The \s-1ENGINE API\s0 and internal architecture is currently being reviewed. Slated for +possible release in 0.9.8 is support for transparent loading of \*(L"dynamic\*(R" +ENGINEs (built as self-contained shared-libraries). This would allow \s-1ENGINE\s0 +implementations to be provided independently of OpenSSL libraries and/or +OpenSSL-based applications, and would also remove any requirement for +applications to explicitly use the \*(L"dynamic\*(R" \s-1ENGINE\s0 to bind to shared-library +implementations. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_rsa\fR\|(3), \fIopenssl_dsa\fR\|(3), \fIopenssl_dh\fR\|(3), \fIopenssl_rand\fR\|(3) diff --git a/static/netbsd/man3/openssl_err.3 b/static/netbsd/man3/openssl_err.3 new file mode 100644 index 00000000..aa98fb81 --- /dev/null +++ b/static/netbsd/man3/openssl_err.3 @@ -0,0 +1,321 @@ +.\" $NetBSD: openssl_err.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "err 3" +.TH err 3 "2014-08-10" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +err \- error codes +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/err.h> +\& +\& unsigned long ERR_get_error(void); +\& unsigned long ERR_peek_error(void); +\& unsigned long ERR_get_error_line(const char **file, int *line); +\& unsigned long ERR_peek_error_line(const char **file, int *line); +\& unsigned long ERR_get_error_line_data(const char **file, int *line, +\& const char **data, int *flags); +\& unsigned long ERR_peek_error_line_data(const char **file, int *line, +\& const char **data, int *flags); +\& +\& int ERR_GET_LIB(unsigned long e); +\& int ERR_GET_FUNC(unsigned long e); +\& int ERR_GET_REASON(unsigned long e); +\& +\& void ERR_clear_error(void); +\& +\& char *ERR_error_string(unsigned long e, char *buf); +\& const char *ERR_lib_error_string(unsigned long e); +\& const char *ERR_func_error_string(unsigned long e); +\& const char *ERR_reason_error_string(unsigned long e); +\& +\& void ERR_print_errors(BIO *bp); +\& void ERR_print_errors_fp(FILE *fp); +\& +\& void ERR_load_crypto_strings(void); +\& void ERR_free_strings(void); +\& +\& void ERR_remove_state(unsigned long pid); +\& +\& void ERR_put_error(int lib, int func, int reason, const char *file, +\& int line); +\& void ERR_add_error_data(int num, ...); +\& +\& void ERR_load_strings(int lib,ERR_STRING_DATA str[]); +\& unsigned long ERR_PACK(int lib, int func, int reason); +\& int ERR_get_next_error_library(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When a call to the OpenSSL library fails, this is usually signalled +by the return value, and an error code is stored in an error queue +associated with the current thread. The \fBerr\fR library provides +functions to obtain these error codes and textual error messages. +.PP +The \fIERR_get_error\fR\|(3) manpage describes how to +access error codes. +.PP +Error codes contain information about where the error occurred, and +what went wrong. \s-1\fIERR_GET_LIB\s0\fR\|(3) describes how to +extract this information. A method to obtain human-readable error +messages is described in \fIERR_error_string\fR\|(3). +.PP +\&\fIERR_clear_error\fR\|(3) can be used to clear the +error queue. +.PP +Note that \fIERR_remove_state\fR\|(3) should be used to +avoid memory leaks when threads are terminated. +.SH "ADDING NEW ERROR CODES TO OPENSSL" +.IX Header "ADDING NEW ERROR CODES TO OPENSSL" +See \fIERR_put_error\fR\|(3) if you want to record error codes in the +OpenSSL error system from within your application. +.PP +The remainder of this section is of interest only if you want to add +new error codes to OpenSSL or add error codes from external libraries. +.SS "Reporting errors" +.IX Subsection "Reporting errors" +Each sub-library has a specific macro \fIXXXerr()\fR that is used to report +errors. Its first argument is a function code \fB\s-1XXX_F_...\s0\fR, the second +argument is a reason code \fB\s-1XXX_R_...\s0\fR. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function \fIssl23_read()\fR reports a +\&\*(L"handshake failure\*(R" as follows: +.PP +.Vb 1 +\& SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); +.Ve +.PP +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as \*(L"\s-1SSL23_READ\*(R"\s0 in the above example. +.PP +The trailing section of a reason code (after the \*(L"_R_\*(R") is translated +into lower case and underscores changed to spaces. +.PP +When you are using new function or reason codes, run \fBmake errors\fR. +The necessary \fB#define\fRs will then automatically be added to the +sub-library's header file. +.PP +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include \s-1ASN1\s0 code which must use +the \fIASN1err()\fR macro. +.SS "Adding new libraries" +.IX Subsection "Adding new libraries" +When adding a new sub-library to OpenSSL, assign it a library number +\&\fB\s-1ERR_LIB_XXX\s0\fR, define a macro \fIXXXerr()\fR (both in \fBerr.h\fR), add its +name to \fBERR_str_libraries[]\fR (in \fBcrypto/err/err.c\fR), and add +\&\f(CW\*(C`ERR_load_XXX_strings()\*(C'\fR to the \fIERR_load_crypto_strings()\fR function +(in \fBcrypto/err/err_all.c\fR). Finally, add an entry +.PP +.Vb 1 +\& L XXX xxx.h xxx_err.c +.Ve +.PP +to \fBcrypto/err/openssl.ec\fR, and add \fBxxx_err.c\fR to the Makefile. +Running \fBmake errors\fR will then generate a file \fBxxx_err.c\fR, and +add all error codes used in the library to \fBxxx.h\fR. +.PP +Additionally the library include file must have a certain form. +Typically it will initially look like this: +.PP +.Vb 2 +\& #ifndef HEADER_XXX_H +\& #define HEADER_XXX_H +\& +\& #ifdef _\|_cplusplus +\& extern "C" { +\& #endif +\& +\& /* Include files */ +\& +\& #include <openssl/bio.h> +\& #include <openssl/x509.h> +\& +\& /* Macros, structures and function prototypes */ +\& +\& +\& /* BEGIN ERROR CODES */ +.Ve +.PP +The \fB\s-1BEGIN ERROR CODES\s0\fR sequence is used by the error code +generation script as the point to place new error codes, any text +after this point will be overwritten when \fBmake errors\fR is run. +The closing #endif etc will be automatically added by the script. +.PP +The generated C error code file \fBxxx_err.c\fR will load the header +files \fBstdio.h\fR, \fBopenssl/err.h\fR and \fBopenssl/xxx.h\fR so the +header file must load any additional header files containing any +definitions it uses. +.SH "USING ERROR CODES IN EXTERNAL LIBRARIES" +.IX Header "USING ERROR CODES IN EXTERNAL LIBRARIES" +It is also possible to use OpenSSL's error code scheme in external +libraries. The library needs to load its own codes and call the OpenSSL +error code insertion script \fBmkerr.pl\fR explicitly to add codes to +the header file and generate the C error code file. This will normally +be done if the external library needs to generate new \s-1ASN1\s0 structures +but it can also be used to add more general purpose error code handling. +.PP +\&\s-1TBA\s0 more details +.SH "INTERNALS" +.IX Header "INTERNALS" +The error queues are stored in a hash table with one \fB\s-1ERR_STATE\s0\fR +entry for each pid. \fIERR_get_state()\fR returns the current thread's +\&\fB\s-1ERR_STATE\s0\fR. An \fB\s-1ERR_STATE\s0\fR can hold up to \fB\s-1ERR_NUM_ERRORS\s0\fR error +codes. When more error codes are added, the old ones are overwritten, +on the assumption that the most recent errors are most important. +.PP +Error strings are also stored in hash table. The hash tables can +be obtained by calling ERR_get_err_state_table(void) and +ERR_get_string_table(void) respectively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fICRYPTO_set_locking_callback\fR\|(3), +\&\fIERR_get_error\fR\|(3), +\&\s-1\fIERR_GET_LIB\s0\fR\|(3), +\&\fIERR_clear_error\fR\|(3), +\&\fIERR_error_string\fR\|(3), +\&\fIERR_print_errors\fR\|(3), +\&\fIERR_load_crypto_strings\fR\|(3), +\&\fIERR_remove_state\fR\|(3), +\&\fIERR_put_error\fR\|(3), +\&\fIERR_load_strings\fR\|(3), +\&\fISSL_get_error\fR\|(3) diff --git a/static/netbsd/man3/openssl_evp.3 b/static/netbsd/man3/openssl_evp.3 new file mode 100644 index 00000000..ab4e1d57 --- /dev/null +++ b/static/netbsd/man3/openssl_evp.3 @@ -0,0 +1,236 @@ +.\" $NetBSD: openssl_evp.3,v 1.1.1.2 2023/04/18 14:19:15 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "evp 3" +.TH evp 3 "2018-01-15" "1.1.0g" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +evp \- high\-level cryptographic functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/evp.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1EVP\s0 library provides a high-level interface to cryptographic +functions. +.PP +\&\fBEVP_Seal\fR\fI...\fR and \fBEVP_Open\fR\fI...\fR +provide public key encryption and decryption to implement digital \*(L"envelopes\*(R". +.PP +The \fBEVP_DigestSign\fR\fI...\fR and +\&\fBEVP_DigestVerify\fR\fI...\fR functions implement +digital signatures and Message Authentication Codes (MACs). Also see the older +\&\fBEVP_Sign\fR\fI...\fR and \fBEVP_Verify\fR\fI...\fR +functions. +.PP +Symmetric encryption is available with the \fBEVP_Encrypt\fR\fI...\fR +functions. The \fBEVP_Digest\fR\fI...\fR functions provide message digests. +.PP +The \fB\s-1EVP_PKEY\s0\fR\fI...\fR functions provide a high level interface to +asymmetric algorithms. To create a new \s-1EVP_PKEY\s0 see +\&\fIEVP_PKEY_new\fR\|(3). EVP_PKEYs can be associated +with a private key of a particular algorithm by using the functions +described on the \fIEVP_PKEY_set1_RSA\fR\|(3) page, or +new keys can be generated using \fIEVP_PKEY_keygen\fR\|(3). +EVP_PKEYs can be compared using \fIEVP_PKEY_cmp\fR\|(3), or printed using +\&\fIEVP_PKEY_print_private\fR\|(3). +.PP +The \s-1EVP_PKEY\s0 functions support the full range of asymmetric algorithm operations: +.IP "For key agreement see \fIEVP_PKEY_derive\fR\|(3)" 4 +.IX Item "For key agreement see EVP_PKEY_derive" +.PD 0 +.IP "For signing and verifying see \fIEVP_PKEY_sign\fR\|(3), \fIEVP_PKEY_verify\fR\|(3) and \fIEVP_PKEY_verify_recover\fR\|(3). However, note that these functions do not perform a digest of the data to be signed. Therefore normally you would use the \fIEVP_DigestSignInit\fR\|(3) functions for this purpose." 4 +.IX Item "For signing and verifying see EVP_PKEY_sign, EVP_PKEY_verify and EVP_PKEY_verify_recover. However, note that these functions do not perform a digest of the data to be signed. Therefore normally you would use the EVP_DigestSignInit functions for this purpose." +.ie n .IP "For encryption and decryption see \fIEVP_PKEY_encrypt\fR\|(3) and \fIEVP_PKEY_decrypt\fR\|(3) respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a ""digital envelope"" using the \fIEVP_SealInit\fR\|(3) and \fIEVP_OpenInit\fR\|(3) functions." 4 +.el .IP "For encryption and decryption see \fIEVP_PKEY_encrypt\fR\|(3) and \fIEVP_PKEY_decrypt\fR\|(3) respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a ``digital envelope'' using the \fIEVP_SealInit\fR\|(3) and \fIEVP_OpenInit\fR\|(3) functions." 4 +.IX Item "For encryption and decryption see EVP_PKEY_encrypt and EVP_PKEY_decrypt respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a digital envelope using the EVP_SealInit and EVP_OpenInit functions." +.PD +.PP +The \fIEVP_BytesToKey\fR\|(3) function provides some limited support for password +based encryption. Careful selection of the parameters will provide a PKCS#5 \s-1PBKDF1\s0 compatible +implementation. However, new applications should not typically use this (preferring, for example, +\&\s-1PBKDF2\s0 from PCKS#5). +.PP +The \fBEVP_Encode\fR\fI...\fR and +\&\fBEVP_Decode\fR\fI...\fR functions implement base 64 encoding +and decoding. +.PP +All the symmetric algorithms (ciphers), digests and asymmetric algorithms +(public key algorithms) can be replaced by \fIengine\fR\|(3) modules providing alternative +implementations. If \s-1ENGINE\s0 implementations of ciphers or digests are registered +as defaults, then the various \s-1EVP\s0 functions will automatically use those +implementations automatically in preference to built in software +implementations. For more information, consult the \fIengine\fR\|(3) man page. +.PP +Although low level algorithm specific functions exist for many algorithms +their use is discouraged. They cannot be used with an \s-1ENGINE\s0 and \s-1ENGINE\s0 +versions of new algorithms cannot be accessed using the low level functions. +Also makes code harder to adapt to new algorithms and some options are not +cleanly supported at the low level and some operations are more efficient +using the high level interface. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIEVP_DigestInit\fR\|(3), +\&\fIEVP_EncryptInit\fR\|(3), +\&\fIEVP_OpenInit\fR\|(3), +\&\fIEVP_SealInit\fR\|(3), +\&\fIEVP_DigestSignInit\fR\|(3), +\&\fIEVP_SignInit\fR\|(3), +\&\fIEVP_VerifyInit\fR\|(3), +\&\fIEVP_EncodeInit\fR\|(3), +\&\fIEVP_PKEY_new\fR\|(3), +\&\fIEVP_PKEY_set1_RSA\fR\|(3), +\&\fIEVP_PKEY_keygen\fR\|(3), +\&\fIEVP_PKEY_print_private\fR\|(3), +\&\fIEVP_PKEY_decrypt\fR\|(3), +\&\fIEVP_PKEY_encrypt\fR\|(3), +\&\fIEVP_PKEY_sign\fR\|(3), +\&\fIEVP_PKEY_verify\fR\|(3), +\&\fIEVP_PKEY_verify_recover\fR\|(3), +\&\fIEVP_PKEY_derive\fR\|(3), +\&\fIEVP_BytesToKey\fR\|(3), +\&\fIengine\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/openssl_lhash.3 b/static/netbsd/man3/openssl_lhash.3 new file mode 100644 index 00000000..ba70ce2c --- /dev/null +++ b/static/netbsd/man3/openssl_lhash.3 @@ -0,0 +1,439 @@ +.\" $NetBSD: openssl_lhash.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "lhash 3" +.TH lhash 3 "2009-12-26" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error \- dynamic hash table +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/lhash.h> +\& +\& DECLARE_LHASH_OF(<type>); +\& +\& LHASH *lh_<type>_new(); +\& void lh_<type>_free(LHASH_OF(<type> *table); +\& +\& <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data); +\& <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data); +\& <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data); +\& +\& void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); +\& void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, +\& <type2>, <type2> *arg); +\& +\& int lh_<type>_error(LHASH_OF(<type> *table); +\& +\& typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); +\& typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); +\& typedef void (*LHASH_DOALL_FN_TYPE)(const void *); +\& typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library implements type-checked dynamic hash tables. The hash +table entries can be arbitrary structures. Usually they consist of key +and value fields. +.PP +lh_<type>\fI_new()\fR creates a new \fB\s-1LHASH_OF\s0(<type\fR> structure to store +arbitrary data entries, and provides the 'hash' and 'compare' +callbacks to be used in organising the table's entries. The \fBhash\fR +callback takes a pointer to a table entry as its argument and returns +an unsigned long hash value for its key field. The hash value is +normally truncated to a power of 2, so make sure that your hash +function returns well mixed low order bits. The \fBcompare\fR callback +takes two arguments (pointers to two hash table entries), and returns +0 if their keys are equal, non-zero otherwise. If your hash table +will contain items of some particular type and the \fBhash\fR and +\&\fBcompare\fR callbacks hash/compare these types, then the +\&\fB\s-1DECLARE_LHASH_HASH_FN\s0\fR and \fB\s-1IMPLEMENT_LHASH_COMP_FN\s0\fR macros can be +used to create callback wrappers of the prototypes required by +lh_<type>\fI_new()\fR. These provide per-variable casts before calling the +type-specific callbacks written by the application author. These +macros, as well as those used for the \*(L"doall\*(R" callbacks, are defined +as; +.PP +.Vb 7 +\& #define DECLARE_LHASH_HASH_FN(name, o_type) \e +\& unsigned long name##_LHASH_HASH(const void *); +\& #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \e +\& unsigned long name##_LHASH_HASH(const void *arg) { \e +\& const o_type *a = arg; \e +\& return name##_hash(a); } +\& #define LHASH_HASH_FN(name) name##_LHASH_HASH +\& +\& #define DECLARE_LHASH_COMP_FN(name, o_type) \e +\& int name##_LHASH_COMP(const void *, const void *); +\& #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \e +\& int name##_LHASH_COMP(const void *arg1, const void *arg2) { \e +\& const o_type *a = arg1; \e +\& const o_type *b = arg2; \e +\& return name##_cmp(a,b); } +\& #define LHASH_COMP_FN(name) name##_LHASH_COMP +\& +\& #define DECLARE_LHASH_DOALL_FN(name, o_type) \e +\& void name##_LHASH_DOALL(void *); +\& #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \e +\& void name##_LHASH_DOALL(void *arg) { \e +\& o_type *a = arg; \e +\& name##_doall(a); } +\& #define LHASH_DOALL_FN(name) name##_LHASH_DOALL +\& +\& #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e +\& void name##_LHASH_DOALL_ARG(void *, void *); +\& #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \e +\& void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \e +\& o_type *a = arg1; \e +\& a_type *b = arg2; \e +\& name##_doall_arg(a, b); } +\& #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG +\& +\& An example of a hash table storing (pointers to) structures of type \*(AqSTUFF\*(Aq +\& could be defined as follows; +\& +\& /* Calculates the hash value of \*(Aqtohash\*(Aq (implemented elsewhere) */ +\& unsigned long STUFF_hash(const STUFF *tohash); +\& /* Orders \*(Aqarg1\*(Aq and \*(Aqarg2\*(Aq (implemented elsewhere) */ +\& int stuff_cmp(const STUFF *arg1, const STUFF *arg2); +\& /* Create the type\-safe wrapper functions for use in the LHASH internals */ +\& static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); +\& static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); +\& /* ... */ +\& int main(int argc, char *argv[]) { +\& /* Create the new hash table using the hash/compare wrappers */ +\& LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), +\& LHASH_COMP_FN(STUFF_cmp)); +\& /* ... */ +\& } +.Ve +.PP +lh_<type>\fI_free()\fR frees the \fB\s-1LHASH_OF\s0(<type\fR> structure +\&\fBtable\fR. Allocated hash table entries will not be freed; consider +using lh_<type>\fI_doall()\fR to deallocate any remaining entries in the +hash table (see below). +.PP +lh_<type>\fI_insert()\fR inserts the structure pointed to by \fBdata\fR into +\&\fBtable\fR. If there already is an entry with the same key, the old +value is replaced. Note that lh_<type>\fI_insert()\fR stores pointers, the +data are not copied. +.PP +lh_<type>\fI_delete()\fR deletes an entry from \fBtable\fR. +.PP +lh_<type>\fI_retrieve()\fR looks up an entry in \fBtable\fR. Normally, \fBdata\fR +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. +.PP +lh_<type>\fI_doall()\fR will, for every entry in the hash table, call +\&\fBfunc\fR with the data item as its parameter. For lh_<type>\fI_doall()\fR +and lh_<type>\fI_doall_arg()\fR, function pointer casting should be avoided +in the callbacks (see \fB\s-1NOTE\s0\fR) \- instead use the declare/implement +macros to create type-checked wrappers that cast variables prior to +calling your type-specific callbacks. An example of this is +illustrated here where the callback is used to cleanup resources for +items in the hash table prior to the hashtable itself being +deallocated: +.PP +.Vb 9 +\& /* Cleans up resources belonging to \*(Aqa\*(Aq (this is implemented elsewhere) */ +\& void STUFF_cleanup_doall(STUFF *a); +\& /* Implement a prototype\-compatible wrapper for "STUFF_cleanup" */ +\& IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) +\& /* ... then later in the code ... */ +\& /* So to run "STUFF_cleanup" against all items in a hash table ... */ +\& lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); +\& /* Then the hash table itself can be deallocated */ +\& lh_STUFF_free(hashtable); +.Ve +.PP +When doing this, be careful if you delete entries from the hash table +in your callbacks: the table may decrease in size, moving the item +that you are currently on down lower in the hash table \- this could +cause some entries to be skipped during the iteration. The second +best solution to this problem is to set hash\->down_load=0 before +you start (which will stop the hash table ever decreasing in size). +The best solution is probably to avoid deleting items from the hash +table inside a \*(L"doall\*(R" callback! +.PP +lh_<type>\fI_doall_arg()\fR is the same as lh_<type>\fI_doall()\fR except that +\&\fBfunc\fR will be called with \fBarg\fR as the second argument and \fBfunc\fR +should be of type \fB\s-1LHASH_DOALL_ARG_FN_TYPE\s0\fR (a callback prototype +that is passed both the table entry and an extra argument). As with +\&\fIlh_doall()\fR, you can instead choose to declare your callback with a +prototype matching the types you are dealing with and use the +declare/implement macros to create compatible wrappers that cast +variables before calling your type-specific callbacks. An example of +this is demonstrated here (printing all hash table entries to a \s-1BIO\s0 +that is provided by the caller): +.PP +.Vb 8 +\& /* Prints item \*(Aqa\*(Aq to \*(Aqoutput_bio\*(Aq (this is implemented elsewhere) */ +\& void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); +\& /* Implement a prototype\-compatible wrapper for "STUFF_print" */ +\& static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) +\& /* ... then later in the code ... */ +\& /* Print out the entire hashtable to a particular BIO */ +\& lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, +\& logging_bio); +.Ve +.PP +lh_<type>\fI_error()\fR can be used to determine if an error occurred in the last +operation. lh_<type>\fI_error()\fR is a macro. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +lh_<type>\fI_new()\fR returns \fB\s-1NULL\s0\fR on error, otherwise a pointer to the new +\&\fB\s-1LHASH\s0\fR structure. +.PP +When a hash table entry is replaced, lh_<type>\fI_insert()\fR returns the value +being replaced. \fB\s-1NULL\s0\fR is returned on normal operation and on error. +.PP +lh_<type>\fI_delete()\fR returns the entry being deleted. \fB\s-1NULL\s0\fR is returned if +there is no such value in the hash table. +.PP +lh_<type>\fI_retrieve()\fR returns the hash table entry if it has been found, +\&\fB\s-1NULL\s0\fR otherwise. +.PP +lh_<type>\fI_error()\fR returns 1 if an error occurred in the last operation, 0 +otherwise. +.PP +lh_<type>\fI_free()\fR, lh_<type>\fI_doall()\fR and lh_<type>\fI_doall_arg()\fR return no values. +.SH "NOTE" +.IX Header "NOTE" +The various \s-1LHASH\s0 macros and callback types exist to make it possible +to write type-checked code without resorting to function-prototype +casting \- an evil that makes application code much harder to +audit/verify and also opens the window of opportunity for stack +corruption and other hard-to-find bugs. It also, apparently, violates +ANSI-C. +.PP +The \s-1LHASH\s0 code regards table entries as constant data. As such, it +internally represents \fIlh_insert()\fR'd items with a \*(L"const void *\*(R" +pointer type. This is why callbacks such as those used by \fIlh_doall()\fR +and \fIlh_doall_arg()\fR declare their prototypes with \*(L"const\*(R", even for the +parameters that pass back the table items' data pointers \- for +consistency, user-provided data is \*(L"const\*(R" at all times as far as the +\&\s-1LHASH\s0 code is concerned. However, as callers are themselves providing +these pointers, they can choose whether they too should be treating +all such parameters as constant. +.PP +As an example, a hash table may be maintained by code that, for +reasons of encapsulation, has only \*(L"const\*(R" access to the data being +indexed in the hash table (ie. it is returned as \*(L"const\*(R" from +elsewhere in their code) \- in this case the \s-1LHASH\s0 prototypes are +appropriate as-is. Conversely, if the caller is responsible for the +life-time of the data in question, then they may well wish to make +modifications to table item passed back in the \fIlh_doall()\fR or +\&\fIlh_doall_arg()\fR callbacks (see the \*(L"STUFF_cleanup\*(R" example above). If +so, the caller can either cast the \*(L"const\*(R" away (if they're providing +the raw callbacks themselves) or use the macros to declare/implement +the wrapper functions without \*(L"const\*(R" types. +.PP +Callers that only have \*(L"const\*(R" access to data they're indexing in a +table, yet declare callbacks without constant types (or cast the +\&\*(L"const\*(R" away themselves), are therefore creating their own risks/bugs +without being encouraged to do so by the \s-1API. \s0 On a related note, +those auditing code should pay special attention to any instances of +DECLARE/IMPLEMENT_LHASH_DOALL_[\s-1ARG_\s0]_FN macros that provide types +without any \*(L"const\*(R" qualifiers. +.SH "BUGS" +.IX Header "BUGS" +lh_<type>\fI_insert()\fR returns \fB\s-1NULL\s0\fR both for success and error. +.SH "INTERNALS" +.IX Header "INTERNALS" +The following description is based on the SSLeay documentation: +.PP +The \fBlhash\fR library implements a hash table described in the +\&\fICommunications of the \s-1ACM\s0\fR in 1991. What makes this hash table +different is that as the table fills, the hash table is increased (or +decreased) in size via \fIOPENSSL_realloc()\fR. When a 'resize' is done, instead of +all hashes being redistributed over twice as many 'buckets', one +bucket is split. So when an 'expand' is done, there is only a minimal +cost to redistribute some values. Subsequent inserts will cause more +single 'bucket' redistributions but there will never be a sudden large +cost due to redistributing all the 'buckets'. +.PP +The state for a particular hash table is kept in the \fB\s-1LHASH\s0\fR structure. +The decision to increase or decrease the hash table size is made +depending on the 'load' of the hash table. The load is the number of +items in the hash table divided by the size of the hash table. The +default values are as follows. If (hash\->up_load < load) => +expand. if (hash\->down_load > load) => contract. The +\&\fBup_load\fR has a default value of 1 and \fBdown_load\fR has a default value +of 2. These numbers can be modified by the application by just +playing with the \fBup_load\fR and \fBdown_load\fR variables. The 'load' is +kept in a form which is multiplied by 256. So +hash\->up_load=8*256; will cause a load of 8 to be set. +.PP +If you are interested in performance the field to watch is +num_comp_calls. The hash library keeps track of the 'hash' value for +each item so when a lookup is done, the 'hashes' are compared, if +there is a match, then a full compare is done, and +hash\->num_comp_calls is incremented. If num_comp_calls is not equal +to num_delete plus num_retrieve it means that your hash function is +generating hashes that are the same for different values. It is +probably worth changing your hash function if this is the case because +even if your hash table has 10 items in a 'bucket', it can be searched +with 10 \fBunsigned long\fR compares and 10 linked list traverses. This +will be much less expensive that 10 calls to your compare function. +.PP +\&\fIlh_strhash()\fR is a demo string hashing function: +.PP +.Vb 1 +\& unsigned long lh_strhash(const char *c); +.Ve +.PP +Since the \fB\s-1LHASH\s0\fR routines would normally be passed structures, this +routine would not normally be passed to lh_<type>\fI_new()\fR, rather it would be +used in the function passed to lh_<type>\fI_new()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIlh_stats\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The \fBlhash\fR library is available in all versions of SSLeay and OpenSSL. +\&\fIlh_error()\fR was added in SSLeay 0.9.1b. +.PP +This manpage is derived from the SSLeay documentation. +.PP +In OpenSSL 0.9.7, all lhash functions that were passed function pointers +were changed for better type safety, and the function types \s-1LHASH_COMP_FN_TYPE, +LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE\s0 and \s-1LHASH_DOALL_ARG_FN_TYPE \s0 +became available. +.PP +In OpenSSL 1.0.0, the lhash interface was revamped for even better +type checking. diff --git a/static/netbsd/man3/openssl_mdc2.3 b/static/netbsd/man3/openssl_mdc2.3 new file mode 100644 index 00000000..56d70cf3 --- /dev/null +++ b/static/netbsd/man3/openssl_mdc2.3 @@ -0,0 +1,195 @@ +.\" $NetBSD: openssl_mdc2.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "mdc2 3" +.TH mdc2 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +MDC2, MDC2_Init, MDC2_Update, MDC2_Final \- MDC2 hash function +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/mdc2.h> +\& +\& unsigned char *MDC2(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int MDC2_Init(MDC2_CTX *c); +\& int MDC2_Update(MDC2_CTX *c, const unsigned char *data, +\& unsigned long len); +\& int MDC2_Final(unsigned char *md, MDC2_CTX *c); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1MDC2\s0 is a method to construct hash functions with 128 bit output from +block ciphers. These functions are an implementation of \s-1MDC2\s0 with +\&\s-1DES.\s0 +.PP +\&\s-1\fIMDC2\s0()\fR computes the \s-1MDC2\s0 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +\&\s-1MDC2_DIGEST_LENGTH\s0 == 16 bytes of output). If \fBmd\fR is \s-1NULL,\s0 the digest +is placed in a static array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fIMDC2_Init()\fR initializes a \fB\s-1MDC2_CTX\s0\fR structure. +.PP +\&\fIMDC2_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fIMDC2_Final()\fR places the message digest in \fBmd\fR, which must have space +for \s-1MDC2_DIGEST_LENGTH\s0 == 16 bytes of output, and erases the \fB\s-1MDC2_CTX\s0\fR. +.PP +Applications should use the higher level functions +\&\fIEVP_DigestInit\fR\|(3) etc. instead of calling the +hash functions directly. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\s-1\fIMDC2\s0()\fR returns a pointer to the hash value. +.PP +\&\fIMDC2_Init()\fR, \fIMDC2_Update()\fR and \fIMDC2_Final()\fR return 1 for success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ISO/IEC 10118\-2,\s0 with \s-1DES\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_sha\fR\|(3), \fIEVP_DigestInit\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1\fIMDC2\s0()\fR, \fIMDC2_Init()\fR, \fIMDC2_Update()\fR and \fIMDC2_Final()\fR are available since +SSLeay 0.8. diff --git a/static/netbsd/man3/openssl_pem.3 b/static/netbsd/man3/openssl_pem.3 new file mode 100644 index 00000000..0c62732e --- /dev/null +++ b/static/netbsd/man3/openssl_pem.3 @@ -0,0 +1,661 @@ +.\" $NetBSD: openssl_pem.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "pem 3" +.TH pem 3 "2015-06-12" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, +PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, +PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, +PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, +PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, +PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, +PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, +PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, +PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, +PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, +PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, +PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, +PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, +PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, +PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, +PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, +PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, +PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, +PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, +PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, +PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, +PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, +PEM_write_NETSCAPE_CERT_SEQUENCE \- PEM routines +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/pem.h> +\& +\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& +\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, +\& char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& +\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); +\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); +\& +\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); +\& +\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x); +\& +\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); +\& +\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); +\& +\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, +\& pem_password_cb *cb, void *u); +\& +\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, +\& unsigned char *kstr, int klen, +\& pem_password_cb *cb, void *u); +\& +\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, +\& pem_password_cb *cb, void *u); +\& +\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); +\& +\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); +\& +\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); +\& +\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x); +\& +\& int PEM_write_DSAparams(FILE *fp, DSA *x); +\& +\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); +\& +\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_DHparams(BIO *bp, DH *x); +\& +\& int PEM_write_DHparams(FILE *fp, DH *x); +\& +\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); +\& +\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_X509(BIO *bp, X509 *x); +\& +\& int PEM_write_X509(FILE *fp, X509 *x); +\& +\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); +\& +\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); +\& +\& int PEM_write_X509_AUX(FILE *fp, X509 *x); +\& +\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, +\& pem_password_cb *cb, void *u); +\& +\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); +\& +\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); +\& +\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); +\& +\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); +\& +\& X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, +\& pem_password_cb *cb, void *u); +\& X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, +\& pem_password_cb *cb, void *u); +\& int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); +\& int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); +\& +\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); +\& +\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); +\& +\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x); +\& +\& NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, +\& NETSCAPE_CERT_SEQUENCE **x, +\& pem_password_cb *cb, void *u); +\& +\& NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, +\& NETSCAPE_CERT_SEQUENCE **x, +\& pem_password_cb *cb, void *u); +\& +\& int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); +\& +\& int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1PEM\s0 functions read or write structures in \s-1PEM\s0 format. In +this sense \s-1PEM\s0 format is simply base64 encoded data surrounded +by header lines. +.PP +For more details about the meaning of arguments see the +\&\fB\s-1PEM FUNCTION ARGUMENTS\s0\fR section. +.PP +Each operation has four functions associated with it. For +clarity the term "\fBfoobar\fR functions" will be used to collectively +refer to the \fIPEM_read_bio_foobar()\fR, \fIPEM_read_foobar()\fR, +\&\fIPEM_write_bio_foobar()\fR and \fIPEM_write_foobar()\fR functions. +.PP +The \fBPrivateKey\fR functions read or write a private key in +\&\s-1PEM\s0 format using an \s-1EVP_PKEY\s0 structure. The write routines use +\&\*(L"traditional\*(R" private key format and can handle both \s-1RSA\s0 and \s-1DSA\s0 +private keys. The read functions can additionally transparently +handle PKCS#8 format encrypted and unencrypted keys too. +.PP +\&\fIPEM_write_bio_PKCS8PrivateKey()\fR and \fIPEM_write_PKCS8PrivateKey()\fR +write a private key in an \s-1EVP_PKEY\s0 structure in PKCS#8 +EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption +algorithms. The \fBcipher\fR argument specifies the encryption algorithm to +use: unlike all other \s-1PEM\s0 routines the encryption is applied at the +PKCS#8 level and not in the \s-1PEM\s0 headers. If \fBcipher\fR is \s-1NULL\s0 then no +encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. +.PP +\&\fIPEM_write_bio_PKCS8PrivateKey_nid()\fR and \fIPEM_write_PKCS8PrivateKey_nid()\fR +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however +it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm +to use is specified in the \fBnid\fR parameter and should be the \s-1NID\s0 of the +corresponding \s-1OBJECT IDENTIFIER \s0(see \s-1NOTES\s0 section). +.PP +The \fB\s-1PUBKEY\s0\fR functions process a public key using an \s-1EVP_PKEY\s0 +structure. The public key is encoded as a SubjectPublicKeyInfo +structure. +.PP +The \fBRSAPrivateKey\fR functions process an \s-1RSA\s0 private key using an +\&\s-1RSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR +functions but an error occurs if the private key is not \s-1RSA.\s0 +.PP +The \fBRSAPublicKey\fR functions process an \s-1RSA\s0 public key using an +\&\s-1RSA\s0 structure. The public key is encoded using a PKCS#1 RSAPublicKey +structure. +.PP +The \fB\s-1RSA_PUBKEY\s0\fR functions also process an \s-1RSA\s0 public key using +an \s-1RSA\s0 structure. However the public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not \s-1RSA.\s0 +.PP +The \fBDSAPrivateKey\fR functions process a \s-1DSA\s0 private key using a +\&\s-1DSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR +functions but an error occurs if the private key is not \s-1DSA.\s0 +.PP +The \fB\s-1DSA_PUBKEY\s0\fR functions process a \s-1DSA\s0 public key using +a \s-1DSA\s0 structure. The public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not \s-1DSA.\s0 +.PP +The \fBDSAparams\fR functions process \s-1DSA\s0 parameters using a \s-1DSA\s0 +structure. The parameters are encoded using a Dss-Parms structure +as defined in \s-1RFC2459.\s0 +.PP +The \fBDHparams\fR functions process \s-1DH\s0 parameters using a \s-1DH\s0 +structure. The parameters are encoded using a PKCS#3 DHparameter +structure. +.PP +The \fBX509\fR functions process an X509 certificate using an X509 +structure. They will also process a trusted X509 certificate but +any trust settings are discarded. +.PP +The \fBX509_AUX\fR functions process a trusted X509 certificate using +an X509 structure. +.PP +The \fBX509_REQ\fR and \fBX509_REQ_NEW\fR functions process a PKCS#10 +certificate request using an X509_REQ structure. The \fBX509_REQ\fR +write functions use \fB\s-1CERTIFICATE REQUEST\s0\fR in the header whereas +the \fBX509_REQ_NEW\fR functions use \fB\s-1NEW CERTIFICATE REQUEST\s0\fR +(as required by some CAs). The \fBX509_REQ\fR read functions will +handle either form so there are no \fBX509_REQ_NEW\fR read functions. +.PP +The \fBX509_CRL\fR functions process an X509 \s-1CRL\s0 using an X509_CRL +structure. +.PP +The \fB\s-1PKCS7\s0\fR functions process a PKCS#7 ContentInfo using a \s-1PKCS7\s0 +structure. +.PP +The \fB\s-1NETSCAPE_CERT_SEQUENCE\s0\fR functions process a Netscape Certificate +Sequence using a \s-1NETSCAPE_CERT_SEQUENCE\s0 structure. +.SH "PEM FUNCTION ARGUMENTS" +.IX Header "PEM FUNCTION ARGUMENTS" +The \s-1PEM\s0 functions have many common arguments. +.PP +The \fBbp\fR \s-1BIO\s0 parameter (if present) specifies the \s-1BIO\s0 to read from +or write to. +.PP +The \fBfp\fR \s-1FILE\s0 parameter (if present) specifies the \s-1FILE\s0 pointer to +read from or write to. +.PP +The \s-1PEM\s0 read functions all take an argument \fB\s-1TYPE\s0 **x\fR and return +a \fB\s-1TYPE\s0 *\fR pointer. Where \fB\s-1TYPE\s0\fR is whatever structure the function +uses. If \fBx\fR is \s-1NULL\s0 then the parameter is ignored. If \fBx\fR is not +\&\s-1NULL\s0 but \fB*x\fR is \s-1NULL\s0 then the structure returned will be written +to \fB*x\fR. If neither \fBx\fR nor \fB*x\fR is \s-1NULL\s0 then an attempt is made +to reuse the structure at \fB*x\fR (but see \s-1BUGS\s0 and \s-1EXAMPLES\s0 sections). +Irrespective of the value of \fBx\fR a pointer to the structure is always +returned (or \s-1NULL\s0 if an error occurred). +.PP +The \s-1PEM\s0 functions which write private keys take an \fBenc\fR parameter +which specifies the encryption algorithm to use, encryption is done +at the \s-1PEM\s0 level. If this parameter is set to \s-1NULL\s0 then the private +key is written in unencrypted form. +.PP +The \fBcb\fR argument is the callback to use when querying for the pass +phrase used for encrypted \s-1PEM\s0 structures (normally only private keys). +.PP +For the \s-1PEM\s0 write routines if the \fBkstr\fR parameter is not \s-1NULL\s0 then +\&\fBklen\fR bytes at \fBkstr\fR are used as the passphrase and \fBcb\fR is +ignored. +.PP +If the \fBcb\fR parameters is set to \s-1NULL\s0 and the \fBu\fR parameter is not +\&\s-1NULL\s0 then the \fBu\fR parameter is interpreted as a null terminated string +to use as the passphrase. If both \fBcb\fR and \fBu\fR are \s-1NULL\s0 then the +default callback routine is used which will typically prompt for the +passphrase on the current terminal with echoing turned off. +.PP +The default passphrase callback is sometimes inappropriate (for example +in a \s-1GUI\s0 application) so an alternative can be supplied. The callback +routine has the following form: +.PP +.Vb 1 +\& int cb(char *buf, int size, int rwflag, void *u); +.Ve +.PP +\&\fBbuf\fR is the buffer to write the passphrase to. \fBsize\fR is the maximum +length of the passphrase (i.e. the size of buf). \fBrwflag\fR is a flag +which is set to 0 when reading and 1 when writing. A typical routine +will ask the user to verify the passphrase (for example by prompting +for it twice) if \fBrwflag\fR is 1. The \fBu\fR parameter has the same +value as the \fBu\fR parameter passed to the \s-1PEM\s0 routine. It allows +arbitrary data to be passed to the callback by the application +(for example a window handle in a \s-1GUI\s0 application). The callback +\&\fBmust\fR return the number of characters in the passphrase or 0 if +an error occurred. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Although the \s-1PEM\s0 routines take several arguments in almost all applications +most of them are set to 0 or \s-1NULL.\s0 +.PP +Read a certificate in \s-1PEM\s0 format from a \s-1BIO:\s0 +.PP +.Vb 6 +\& X509 *x; +\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); +\& if (x == NULL) +\& { +\& /* Error */ +\& } +.Ve +.PP +Alternative method: +.PP +.Vb 5 +\& X509 *x = NULL; +\& if (!PEM_read_bio_X509(bp, &x, 0, NULL)) +\& { +\& /* Error */ +\& } +.Ve +.PP +Write a certificate to a \s-1BIO:\s0 +.PP +.Vb 4 +\& if (!PEM_write_bio_X509(bp, x)) +\& { +\& /* Error */ +\& } +.Ve +.PP +Write an unencrypted private key to a \s-1FILE\s0 pointer: +.PP +.Vb 4 +\& if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) +\& { +\& /* Error */ +\& } +.Ve +.PP +Write a private key (using traditional format) to a \s-1BIO\s0 using +triple \s-1DES\s0 encryption, the pass phrase is prompted for: +.PP +.Vb 4 +\& if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) +\& { +\& /* Error */ +\& } +.Ve +.PP +Write a private key (using PKCS#8 format) to a \s-1BIO\s0 using triple +\&\s-1DES\s0 encryption, using the pass phrase \*(L"hello\*(R": +.PP +.Vb 4 +\& if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) +\& { +\& /* Error */ +\& } +.Ve +.PP +Read a private key from a \s-1BIO\s0 using the pass phrase \*(L"hello\*(R": +.PP +.Vb 5 +\& key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); +\& if (key == NULL) +\& { +\& /* Error */ +\& } +.Ve +.PP +Read a private key from a \s-1BIO\s0 using a pass phrase callback: +.PP +.Vb 5 +\& key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); +\& if (key == NULL) +\& { +\& /* Error */ +\& } +.Ve +.PP +Skeleton pass phrase callback: +.PP +.Vb 6 +\& int pass_cb(char *buf, int size, int rwflag, void *u); +\& { +\& int len; +\& char *tmp; +\& /* We\*(Aqd probably do something else if \*(Aqrwflag\*(Aq is 1 */ +\& printf("Enter pass phrase for \e"%s\e"\en", u); +\& +\& /* get pass phrase, length \*(Aqlen\*(Aq into \*(Aqtmp\*(Aq */ +\& tmp = "hello"; +\& len = strlen(tmp); +\& +\& if (len <= 0) return 0; +\& /* if too long, truncate */ +\& if (len > size) len = size; +\& memcpy(buf, tmp, len); +\& return len; +\& } +.Ve +.SH "NOTES" +.IX Header "NOTES" +The old \fBPrivateKey\fR write routines are retained for compatibility. +New applications should write private keys using the +\&\fIPEM_write_bio_PKCS8PrivateKey()\fR or \fIPEM_write_PKCS8PrivateKey()\fR routines +because they are more secure (they use an iteration count of 2048 whereas +the traditional routines use a count of 1) unless compatibility with older +versions of OpenSSL is important. +.PP +The \fBPrivateKey\fR read routines can be used in all applications because +they handle all formats transparently. +.PP +A frequent cause of problems is attempting to use the \s-1PEM\s0 routines like +this: +.PP +.Vb 2 +\& X509 *x; +\& PEM_read_bio_X509(bp, &x, 0, NULL); +.Ve +.PP +this is a bug because an attempt will be made to reuse the data at \fBx\fR +which is an uninitialised pointer. +.SH "PEM ENCRYPTION FORMAT" +.IX Header "PEM ENCRYPTION FORMAT" +This old \fBPrivateKey\fR routines use a non standard technique for encryption. +.PP +The private key (or other data) takes the following form: +.PP +.Vb 3 +\& \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\- +\& Proc\-Type: 4,ENCRYPTED +\& DEK\-Info: DES\-EDE3\-CBC,3F17F5316E2BAC89 +\& +\& ...base64 encoded data... +\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\- +.Ve +.PP +The line beginning DEK-Info contains two comma separated pieces of information: +the encryption algorithm name as used by \fIEVP_get_cipherbyname()\fR and an 8 +byte \fBsalt\fR encoded as a set of hexadecimal digits. +.PP +After this is the base64 encoded encrypted data. +.PP +The encryption key is determined using \fIEVP_BytesToKey()\fR, using \fBsalt\fR and an +iteration count of 1. The \s-1IV\s0 used is the value of \fBsalt\fR and *not* the \s-1IV\s0 +returned by \fIEVP_BytesToKey()\fR. +.SH "BUGS" +.IX Header "BUGS" +The \s-1PEM\s0 read routines in some versions of OpenSSL will not correctly reuse +an existing structure. Therefore the following: +.PP +.Vb 1 +\& PEM_read_bio_X509(bp, &x, 0, NULL); +.Ve +.PP +where \fBx\fR already contains a valid certificate, may not work, whereas: +.PP +.Vb 2 +\& X509_free(x); +\& x = PEM_read_bio_X509(bp, NULL, 0, NULL); +.Ve +.PP +is guaranteed to work. +.SH "RETURN CODES" +.IX Header "RETURN CODES" +The read routines return either a pointer to the structure read or \s-1NULL\s0 +if an error occurred. +.PP +The write routines return 1 for success or 0 for failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIEVP_get_cipherbyname\fR\|(3), \fIEVP_BytesToKey\fR\|(3) diff --git a/static/netbsd/man3/openssl_rand.3 b/static/netbsd/man3/openssl_rand.3 new file mode 100644 index 00000000..ee2fdbe7 --- /dev/null +++ b/static/netbsd/man3/openssl_rand.3 @@ -0,0 +1,290 @@ +.\" $NetBSD: openssl_rand.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "rand 3" +.TH rand 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +rand \- pseudo\-random number generator +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/rand.h> +\& +\& int RAND_set_rand_engine(ENGINE *engine); +\& +\& int RAND_bytes(unsigned char *buf, int num); +\& int RAND_pseudo_bytes(unsigned char *buf, int num); +\& +\& void RAND_seed(const void *buf, int num); +\& void RAND_add(const void *buf, int num, double entropy); +\& int RAND_status(void); +\& +\& int RAND_load_file(const char *file, long max_bytes); +\& int RAND_write_file(const char *file); +\& const char *RAND_file_name(char *file, size_t num); +\& +\& int RAND_egd(const char *path); +\& +\& void RAND_set_rand_method(const RAND_METHOD *meth); +\& const RAND_METHOD *RAND_get_rand_method(void); +\& RAND_METHOD *RAND_SSLeay(void); +\& +\& void RAND_cleanup(void); +\& +\& /* For Win32 only */ +\& void RAND_screen(void); +\& int RAND_event(UINT, WPARAM, LPARAM); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Since the introduction of the \s-1ENGINE API,\s0 the recommended way of controlling +default implementations is by using the \s-1ENGINE API\s0 functions. The default +\&\fB\s-1RAND_METHOD\s0\fR, as set by \fIRAND_set_rand_method()\fR and returned by +\&\fIRAND_get_rand_method()\fR, is only used if no \s-1ENGINE\s0 has been set as the default +\&\*(L"rand\*(R" implementation. Hence, these two functions are no longer the recommended +way to control defaults. +.PP +If an alternative \fB\s-1RAND_METHOD\s0\fR implementation is being used (either set +directly or as provided by an \s-1ENGINE\s0 module), then it is entirely responsible +for the generation and management of a cryptographically secure \s-1PRNG\s0 stream. The +mechanisms described below relate solely to the software \s-1PRNG\s0 implementation +built in to OpenSSL and used by default. +.PP +These functions implement a cryptographically secure pseudo-random +number generator (\s-1PRNG\s0). It is used by other library functions for +example to generate random keys, and applications can use it when they +need randomness. +.PP +A cryptographic \s-1PRNG\s0 must be seeded with unpredictable data such as +mouse movements or keys pressed at random by the user. This is +described in \fIRAND_add\fR\|(3). Its state can be saved in a seed file +(see \fIRAND_load_file\fR\|(3)) to avoid having to go through the +seeding process whenever the application is started. +.PP +\&\fIRAND_bytes\fR\|(3) describes how to obtain random data from the +\&\s-1PRNG. \s0 +.SH "INTERNALS" +.IX Header "INTERNALS" +The \fIRAND_SSLeay()\fR method implements a \s-1PRNG\s0 based on a cryptographic +hash function. +.PP +The following description of its design is based on the SSLeay +documentation: +.PP +First up I will state the things I believe I need for a good \s-1RNG.\s0 +.IP "1." 4 +A good hashing algorithm to mix things up and to convert the \s-1RNG \s0'state' +to random numbers. +.IP "2." 4 +An initial source of random 'state'. +.IP "3." 4 +The state should be very large. If the \s-1RNG\s0 is being used to generate +4096 bit \s-1RSA\s0 keys, 2 2048 bit random strings are required (at a minimum). +If your \s-1RNG\s0 state only has 128 bits, you are obviously limiting the +search space to 128 bits, not 2048. I'm probably getting a little +carried away on this last point but it does indicate that it may not be +a bad idea to keep quite a lot of \s-1RNG\s0 state. It should be easier to +break a cipher than guess the \s-1RNG\s0 seed data. +.IP "4." 4 +Any \s-1RNG\s0 seed data should influence all subsequent random numbers +generated. This implies that any random seed data entered will have +an influence on all subsequent random numbers generated. +.IP "5." 4 +When using data to seed the \s-1RNG\s0 state, the data used should not be +extractable from the \s-1RNG\s0 state. I believe this should be a +requirement because one possible source of 'secret' semi random +data would be a private key or a password. This data must +not be disclosed by either subsequent random numbers or a +\&'core' dump left by a program crash. +.IP "6." 4 +Given the same initial 'state', 2 systems should deviate in their \s-1RNG\s0 state +(and hence the random numbers generated) over time if at all possible. +.IP "7." 4 +Given the random number output stream, it should not be possible to determine +the \s-1RNG\s0 state or the next random number. +.PP +The algorithm is as follows. +.PP +There is global state made up of a 1023 byte buffer (the 'state'), a +working hash value ('md'), and a counter ('count'). +.PP +Whenever seed data is added, it is inserted into the 'state' as +follows. +.PP +The input is chopped up into units of 20 bytes (or less for +the last block). Each of these blocks is run through the hash +function as follows: The data passed to the hash function +is the current 'md', the same number of bytes from the 'state' +(the location determined by in incremented looping index) as +the current 'block', the new key data 'block', and 'count' +(which is incremented after each use). +The result of this is kept in 'md' and also xored into the +\&'state' at the same locations that were used as input into the +hash function. I +believe this system addresses points 1 (hash function; currently +\&\s-1SHA\-1\s0), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash +function and xor). +.PP +When bytes are extracted from the \s-1RNG,\s0 the following process is used. +For each group of 10 bytes (or less), we do the following: +.PP +Input into the hash function the local 'md' (which is initialized from +the global 'md' before any bytes are generated), the bytes that are to +be overwritten by the random bytes, and bytes from the 'state' +(incrementing looping index). From this digest output (which is kept +in 'md'), the top (up to) 10 bytes are returned to the caller and the +bottom 10 bytes are xored into the 'state'. +.PP +Finally, after we have finished 'num' random bytes for the caller, +\&'count' (which is incremented) and the local and global 'md' are fed +into the hash function and the results are kept in the global 'md'. +.PP +I believe the above addressed points 1 (use of \s-1SHA\-1\s0), 6 (by hashing +into the 'state' the 'old' data from the caller that is about to be +overwritten) and 7 (by not using the 10 bytes given to the caller to +update the 'state', but they are used to update 'md'). +.PP +So of the points raised, only 2 is not addressed (but see +\&\fIRAND_add\fR\|(3)). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIBN_rand\fR\|(3), \fIRAND_add\fR\|(3), +\&\fIRAND_load_file\fR\|(3), \fIRAND_egd\fR\|(3), +\&\fIRAND_bytes\fR\|(3), +\&\fIRAND_set_rand_method\fR\|(3), +\&\fIRAND_cleanup\fR\|(3) diff --git a/static/netbsd/man3/openssl_rc4.3 b/static/netbsd/man3/openssl_rc4.3 new file mode 100644 index 00000000..eb2d26b2 --- /dev/null +++ b/static/netbsd/man3/openssl_rc4.3 @@ -0,0 +1,193 @@ +.\" $NetBSD: openssl_rc4.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "rc4 3" +.TH rc4 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RC4_set_key, RC4 \- RC4 encryption +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/rc4.h> +\& +\& void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); +\& +\& void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, +\& unsigned char *outdata); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +This library implements the Alleged \s-1RC4\s0 cipher, which is described for +example in \fIApplied Cryptography\fR. It is believed to be compatible +with RC4[\s-1TM\s0], a proprietary cipher of \s-1RSA\s0 Security Inc. +.PP +\&\s-1RC4\s0 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. +.PP +\&\s-1RC4\s0 consists of a key setup phase and the actual encryption or +decryption phase. +.PP +\&\fIRC4_set_key()\fR sets up the \fB\s-1RC4_KEY\s0\fR \fBkey\fR using the \fBlen\fR bytes long +key at \fBdata\fR. +.PP +\&\s-1\fIRC4\s0()\fR encrypts or decrypts the \fBlen\fR bytes of data at \fBindata\fR using +\&\fBkey\fR and places the result at \fBoutdata\fR. Repeated \s-1\fIRC4\s0()\fR calls with +the same \fBkey\fR yield a continuous key stream. +.PP +Since \s-1RC4\s0 is a stream cipher (the input is XORed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. +.PP +Applications should use the higher level functions +\&\fIEVP_EncryptInit\fR\|(3) +etc. instead of calling the \s-1RC4\s0 functions directly. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fIRC4_set_key()\fR and \s-1\fIRC4\s0()\fR do not return values. +.SH "NOTE" +.IX Header "NOTE" +Certain conditions have to be observed to securely use stream ciphers. +It is not permissible to perform multiple encryptions using the same +key stream. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_blowfish\fR\|(3), \fIopenssl_des\fR\|(3), \fIrc2\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fIRC4_set_key()\fR and \s-1\fIRC4\s0()\fR are available in all versions of SSLeay and OpenSSL. diff --git a/static/netbsd/man3/openssl_ripemd.3 b/static/netbsd/man3/openssl_ripemd.3 new file mode 100644 index 00000000..e796fbd1 --- /dev/null +++ b/static/netbsd/man3/openssl_ripemd.3 @@ -0,0 +1,197 @@ +.\" $NetBSD: openssl_ripemd.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ripemd 3" +.TH ripemd 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final \- +RIPEMD\-160 hash function +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ripemd.h> +\& +\& unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, +\& unsigned char *md); +\& +\& int RIPEMD160_Init(RIPEMD160_CTX *c); +\& int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, +\& unsigned long len); +\& int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1RIPEMD\-160\s0 is a cryptographic hash function with a +160 bit output. +.PP +\&\s-1\fIRIPEMD160\s0()\fR computes the \s-1RIPEMD\-160\s0 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +\&\s-1RIPEMD160_DIGEST_LENGTH\s0 == 20 bytes of output). If \fBmd\fR is \s-1NULL,\s0 the digest +is placed in a static array. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fIRIPEMD160_Init()\fR initializes a \fB\s-1RIPEMD160_CTX\s0\fR structure. +.PP +\&\fIRIPEMD160_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fIRIPEMD160_Final()\fR places the message digest in \fBmd\fR, which must have +space for \s-1RIPEMD160_DIGEST_LENGTH\s0 == 20 bytes of output, and erases +the \fB\s-1RIPEMD160_CTX\s0\fR. +.PP +Applications should use the higher level functions +\&\fIEVP_DigestInit\fR\|(3) etc. instead of calling the +hash functions directly. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\s-1\fIRIPEMD160\s0()\fR returns a pointer to the hash value. +.PP +\&\fIRIPEMD160_Init()\fR, \fIRIPEMD160_Update()\fR and \fIRIPEMD160_Final()\fR return 1 for +success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1ISO/IEC 10118\-3 \s0(draft) (??) +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_sha\fR\|(3), \fIopenssl_hmac\fR\|(3), \fIEVP_DigestInit\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1\fIRIPEMD160\s0()\fR, \fIRIPEMD160_Init()\fR, \fIRIPEMD160_Update()\fR and +\&\fIRIPEMD160_Final()\fR are available since SSLeay 0.9.0. diff --git a/static/netbsd/man3/openssl_rsa.3 b/static/netbsd/man3/openssl_rsa.3 new file mode 100644 index 00000000..2d04387d --- /dev/null +++ b/static/netbsd/man3/openssl_rsa.3 @@ -0,0 +1,257 @@ +.\" $NetBSD: openssl_rsa.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "rsa 3" +.TH rsa 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +rsa \- RSA public key cryptosystem +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 2 +\& #include <openssl/rsa.h> +\& #include <openssl/engine.h> +\& +\& RSA * RSA_new(void); +\& void RSA_free(RSA *rsa); +\& +\& int RSA_public_encrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& int RSA_private_decrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa, int padding); +\& int RSA_private_encrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa,int padding); +\& int RSA_public_decrypt(int flen, unsigned char *from, +\& unsigned char *to, RSA *rsa,int padding); +\& +\& int RSA_sign(int type, unsigned char *m, unsigned int m_len, +\& unsigned char *sigret, unsigned int *siglen, RSA *rsa); +\& int RSA_verify(int type, unsigned char *m, unsigned int m_len, +\& unsigned char *sigbuf, unsigned int siglen, RSA *rsa); +\& +\& int RSA_size(const RSA *rsa); +\& +\& RSA *RSA_generate_key(int num, unsigned long e, +\& void (*callback)(int,int,void *), void *cb_arg); +\& +\& int RSA_check_key(RSA *rsa); +\& +\& int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); +\& void RSA_blinding_off(RSA *rsa); +\& +\& void RSA_set_default_method(const RSA_METHOD *meth); +\& const RSA_METHOD *RSA_get_default_method(void); +\& int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); +\& const RSA_METHOD *RSA_get_method(const RSA *rsa); +\& RSA_METHOD *RSA_PKCS1_SSLeay(void); +\& RSA_METHOD *RSA_null_method(void); +\& int RSA_flags(const RSA *rsa); +\& RSA *RSA_new_method(ENGINE *engine); +\& +\& int RSA_print(BIO *bp, RSA *x, int offset); +\& int RSA_print_fp(FILE *fp, RSA *x, int offset); +\& +\& int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), +\& int (*dup_func)(), void (*free_func)()); +\& int RSA_set_ex_data(RSA *r,int idx,char *arg); +\& char *RSA_get_ex_data(RSA *r, int idx); +\& +\& int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, +\& unsigned int m_len, unsigned char *sigret, unsigned int *siglen, +\& RSA *rsa); +\& int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, +\& unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, +\& RSA *rsa); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These functions implement \s-1RSA\s0 public key encryption and signatures +as defined in \s-1PKCS\s0 #1 v2.0 [\s-1RFC 2437\s0]. +.PP +The \fB\s-1RSA\s0\fR structure consists of several \s-1BIGNUM\s0 components. It can +contain public as well as private \s-1RSA\s0 keys: +.PP +.Vb 10 +\& struct +\& { +\& BIGNUM *n; // public modulus +\& BIGNUM *e; // public exponent +\& BIGNUM *d; // private exponent +\& BIGNUM *p; // secret prime factor +\& BIGNUM *q; // secret prime factor +\& BIGNUM *dmp1; // d mod (p\-1) +\& BIGNUM *dmq1; // d mod (q\-1) +\& BIGNUM *iqmp; // q^\-1 mod p +\& // ... +\& }; +\& RSA +.Ve +.PP +In public keys, the private exponent and the related secret values are +\&\fB\s-1NULL\s0\fR. +.PP +\&\fBp\fR, \fBq\fR, \fBdmp1\fR, \fBdmq1\fR and \fBiqmp\fR may be \fB\s-1NULL\s0\fR in private +keys, but the \s-1RSA\s0 operations are much faster when these values are +available. +.PP +Note that \s-1RSA\s0 keys may use non-standard \fB\s-1RSA_METHOD\s0\fR implementations, +either directly or by the use of \fB\s-1ENGINE\s0\fR modules. In some cases (eg. an +\&\s-1ENGINE\s0 providing support for hardware-embedded keys), these \s-1BIGNUM\s0 values +will not be used by the implementation or may be used for alternative data +storage. For this reason, applications should generally avoid using \s-1RSA\s0 +structure elements directly and instead use \s-1API\s0 functions to query or +modify keys. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1SSL, PKCS\s0 #1 v2.0 +.SH "PATENTS" +.IX Header "PATENTS" +\&\s-1RSA\s0 was covered by a \s-1US\s0 patent which expired in September 2000. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_rsa\fR\|(1), \fIopenssl_bn\fR\|(3), \fIopenssl_dsa\fR\|(3), \fIopenssl_dh\fR\|(3), +\&\fIopenssl_rand\fR\|(3), \fIengine\fR\|(3), \fIRSA_new\fR\|(3), +\&\fIRSA_public_encrypt\fR\|(3), +\&\fIRSA_sign\fR\|(3), \fIRSA_size\fR\|(3), +\&\fIRSA_generate_key\fR\|(3), +\&\fIRSA_check_key\fR\|(3), +\&\fIRSA_blinding_on\fR\|(3), +\&\fIRSA_set_method\fR\|(3), \fIRSA_print\fR\|(3), +\&\fIRSA_get_ex_new_index\fR\|(3), +\&\fIRSA_private_encrypt\fR\|(3), +\&\fIRSA_sign_ASN1_OCTET_STRING\fR\|(3), +\&\fIRSA_padding_add_PKCS1_type_1\fR\|(3) diff --git a/static/netbsd/man3/openssl_sha.3 b/static/netbsd/man3/openssl_sha.3 new file mode 100644 index 00000000..029247b4 --- /dev/null +++ b/static/netbsd/man3/openssl_sha.3 @@ -0,0 +1,235 @@ +.\" $NetBSD: openssl_sha.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "sha 3" +.TH sha 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, +SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, +SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, +SHA512_Final \- Secure Hash Algorithm +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/sha.h> +\& +\& int SHA1_Init(SHA_CTX *c); +\& int SHA1_Update(SHA_CTX *c, const void *data, size_t len); +\& int SHA1_Final(unsigned char *md, SHA_CTX *c); +\& unsigned char *SHA1(const unsigned char *d, size_t n, +\& unsigned char *md); +\& +\& int SHA224_Init(SHA256_CTX *c); +\& int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); +\& int SHA224_Final(unsigned char *md, SHA256_CTX *c); +\& unsigned char *SHA224(const unsigned char *d, size_t n, +\& unsigned char *md); +\& +\& int SHA256_Init(SHA256_CTX *c); +\& int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); +\& int SHA256_Final(unsigned char *md, SHA256_CTX *c); +\& unsigned char *SHA256(const unsigned char *d, size_t n, +\& unsigned char *md); +\& +\& int SHA384_Init(SHA512_CTX *c); +\& int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); +\& int SHA384_Final(unsigned char *md, SHA512_CTX *c); +\& unsigned char *SHA384(const unsigned char *d, size_t n, +\& unsigned char *md); +\& +\& int SHA512_Init(SHA512_CTX *c); +\& int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); +\& int SHA512_Final(unsigned char *md, SHA512_CTX *c); +\& unsigned char *SHA512(const unsigned char *d, size_t n, +\& unsigned char *md); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Applications should use the higher level functions +\&\fIEVP_DigestInit\fR\|(3) etc. instead of calling the hash +functions directly. +.PP +\&\s-1SHA\-1 \s0(Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. +.PP +\&\s-1\fISHA1\s0()\fR computes the \s-1SHA\-1\s0 message digest of the \fBn\fR +bytes at \fBd\fR and places it in \fBmd\fR (which must have space for +\&\s-1SHA_DIGEST_LENGTH\s0 == 20 bytes of output). If \fBmd\fR is \s-1NULL,\s0 the digest +is placed in a static array. Note: setting \fBmd\fR to \s-1NULL\s0 is \fBnot thread safe\fR. +.PP +The following functions may be used if the message is not completely +stored in memory: +.PP +\&\fISHA1_Init()\fR initializes a \fB\s-1SHA_CTX\s0\fR structure. +.PP +\&\fISHA1_Update()\fR can be called repeatedly with chunks of the message to +be hashed (\fBlen\fR bytes at \fBdata\fR). +.PP +\&\fISHA1_Final()\fR places the message digest in \fBmd\fR, which must have space +for \s-1SHA_DIGEST_LENGTH\s0 == 20 bytes of output, and erases the \fB\s-1SHA_CTX\s0\fR. +.PP +The \s-1SHA224, SHA256, SHA384\s0 and \s-1SHA512\s0 families of functions operate in the +same way as for the \s-1SHA1\s0 functions. Note that \s-1SHA224\s0 and \s-1SHA256\s0 use a +\&\fB\s-1SHA256_CTX\s0\fR object instead of \fB\s-1SHA_CTX\s0\fR. \s-1SHA384\s0 and \s-1SHA512\s0 use \fB\s-1SHA512_CTX\s0\fR. +The buffer \fBmd\fR must have space for the output from the \s-1SHA\s0 variant being used +(defined by \s-1SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH\s0 and +\&\s-1SHA512_DIGEST_LENGTH\s0). Also note that, as for the \s-1\fISHA1\s0()\fR function above, the +\&\s-1\fISHA224\s0()\fR, \s-1\fISHA256\s0()\fR, \s-1\fISHA384\s0()\fR and \s-1\fISHA512\s0()\fR functions are not thread safe if +\&\fBmd\fR is \s-1NULL.\s0 +.PP +The predecessor of \s-1SHA\-1, SHA,\s0 is also implemented, but it should be +used only when backward compatibility is required. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\s-1\fISHA1\s0()\fR, \s-1\fISHA224\s0()\fR, \s-1\fISHA256\s0()\fR, \s-1\fISHA384\s0()\fR and \s-1\fISHA512\s0()\fR return a pointer to the hash +value. +.PP +\&\fISHA1_Init()\fR, \fISHA1_Update()\fR and \fISHA1_Final()\fR and equivalent \s-1SHA224, SHA256, +SHA384\s0 and \s-1SHA512\s0 functions return 1 for success, 0 otherwise. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +\&\s-1US\s0 Federal Information Processing Standard \s-1FIPS PUB 180\-4 \s0(Secure Hash +Standard), +\&\s-1ANSI X9.30\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl_ripemd\fR\|(3), \fIopenssl_hmac\fR\|(3), \fIEVP_DigestInit\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\s-1\fISHA1\s0()\fR, \fISHA1_Init()\fR, \fISHA1_Update()\fR and \fISHA1_Final()\fR are available in all +versions of SSLeay and OpenSSL. diff --git a/static/netbsd/man3/openssl_threads.3 b/static/netbsd/man3/openssl_threads.3 new file mode 100644 index 00000000..3479ceb8 --- /dev/null +++ b/static/netbsd/man3/openssl_threads.3 @@ -0,0 +1,330 @@ +.\" $NetBSD: openssl_threads.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "threads 3" +.TH threads 3 "2009-12-26" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, +CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, +CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, +CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, +CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, +CRYPTO_destroy_dynlockid, CRYPTO_lock \- OpenSSL thread support +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/crypto.h> +\& +\& /* Don\*(Aqt use this structure directly. */ +\& typedef struct crypto_threadid_st +\& { +\& void *ptr; +\& unsigned long val; +\& } CRYPTO_THREADID; +\& /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ +\& void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); +\& void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); +\& int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); +\& void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); +\& void CRYPTO_THREADID_current(CRYPTO_THREADID *id); +\& int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, +\& const CRYPTO_THREADID *b); +\& void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, +\& const CRYPTO_THREADID *src); +\& unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); +\& +\& int CRYPTO_num_locks(void); +\& +\& /* struct CRYPTO_dynlock_value needs to be defined by the user */ +\& struct CRYPTO_dynlock_value; +\& +\& void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * +\& (*dyn_create_function)(char *file, int line)); +\& void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) +\& (int mode, struct CRYPTO_dynlock_value *l, +\& const char *file, int line)); +\& void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) +\& (struct CRYPTO_dynlock_value *l, const char *file, int line)); +\& +\& int CRYPTO_get_new_dynlockid(void); +\& +\& void CRYPTO_destroy_dynlockid(int i); +\& +\& void CRYPTO_lock(int mode, int n, const char *file, int line); +\& +\& #define CRYPTO_w_lock(type) \e +\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,_\|_FILE_\|_,_\|_LINE_\|_) +\& #define CRYPTO_w_unlock(type) \e +\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,_\|_FILE_\|_,_\|_LINE_\|_) +\& #define CRYPTO_r_lock(type) \e +\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,_\|_FILE_\|_,_\|_LINE_\|_) +\& #define CRYPTO_r_unlock(type) \e +\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,_\|_FILE_\|_,_\|_LINE_\|_) +\& #define CRYPTO_add(addr,amount,type) \e +\& CRYPTO_add_lock(addr,amount,type,_\|_FILE_\|_,_\|_LINE_\|_) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +OpenSSL can safely be used in multi-threaded applications provided +that at least two callback functions are set, locking_function and +threadid_func. +.PP +locking_function(int mode, int n, const char *file, int line) is +needed to perform locking on shared data structures. +(Note that OpenSSL uses a number of global data structures that +will be implicitly shared whenever multiple threads use OpenSSL.) +Multi-threaded applications will crash at random if it is not set. +.PP +\&\fIlocking_function()\fR must be able to handle up to \fICRYPTO_num_locks()\fR +different mutex locks. It sets the \fBn\fR\-th lock if \fBmode\fR & +\&\fB\s-1CRYPTO_LOCK\s0\fR, and releases it otherwise. +.PP +\&\fBfile\fR and \fBline\fR are the file number of the function setting the +lock. They can be useful for debugging. +.PP +threadid_func(\s-1CRYPTO_THREADID\s0 *id) is needed to record the currently-executing +thread's identifier into \fBid\fR. The implementation of this callback should not +fill in \fBid\fR directly, but should use \fICRYPTO_THREADID_set_numeric()\fR if thread +IDs are numeric, or \fICRYPTO_THREADID_set_pointer()\fR if they are pointer-based. +If the application does not register such a callback using +\&\fICRYPTO_THREADID_set_callback()\fR, then a default implementation is used \- on +Windows and BeOS this uses the system's default thread identifying APIs, and on +all other platforms it uses the address of \fBerrno\fR. The latter is satisfactory +for thread-safety if and only if the platform has a thread-local error number +facility. +.PP +Once \fIthreadid_func()\fR is registered, or if the built-in default implementation is +to be used; +.IP "\(bu" 4 +\&\fICRYPTO_THREADID_current()\fR records the currently-executing thread \s-1ID\s0 into the +given \fBid\fR object. +.IP "\(bu" 4 +\&\fICRYPTO_THREADID_cmp()\fR compares two thread IDs (returning zero for equality, ie. +the same semantics as \fImemcmp()\fR). +.IP "\(bu" 4 +\&\fICRYPTO_THREADID_cpy()\fR duplicates a thread \s-1ID\s0 value, +.IP "\(bu" 4 +\&\fICRYPTO_THREADID_hash()\fR returns a numeric value usable as a hash-table key. This +is usually the exact numeric or pointer-based thread \s-1ID\s0 used internally, however +this also handles the unusual case where pointers are larger than 'long' +variables and the platform's thread IDs are pointer-based \- in this case, mixing +is done to attempt to produce a unique numeric value even though it is not as +wide as the platform's true thread IDs. +.PP +Additionally, OpenSSL supports dynamic locks, and sometimes, some parts +of OpenSSL need it for better performance. To enable this, the following +is required: +.IP "\(bu" 4 +Three additional callback function, dyn_create_function, dyn_lock_function +and dyn_destroy_function. +.IP "\(bu" 4 +A structure defined with the data that each lock needs to handle. +.PP +struct CRYPTO_dynlock_value has to be defined to contain whatever structure +is needed to handle locks. +.PP +dyn_create_function(const char *file, int line) is needed to create a +lock. Multi-threaded applications might crash at random if it is not set. +.PP +dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) +is needed to perform locking off dynamic lock numbered n. Multi-threaded +applications might crash at random if it is not set. +.PP +dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is +needed to destroy the lock l. Multi-threaded applications might crash at +random if it is not set. +.PP +\&\fICRYPTO_get_new_dynlockid()\fR is used to create locks. It will call +dyn_create_function for the actual creation. +.PP +\&\fICRYPTO_destroy_dynlockid()\fR is used to destroy locks. It will call +dyn_destroy_function for the actual destruction. +.PP +\&\fICRYPTO_lock()\fR is used to lock and unlock the locks. mode is a bitfield +describing what should be done with the lock. n is the number of the +lock as returned from \fICRYPTO_get_new_dynlockid()\fR. mode can be combined +from the following values. These values are pairwise exclusive, with +undefined behaviour if misused (for example, \s-1CRYPTO_READ\s0 and \s-1CRYPTO_WRITE\s0 +should not be used together): +.PP +.Vb 4 +\& CRYPTO_LOCK 0x01 +\& CRYPTO_UNLOCK 0x02 +\& CRYPTO_READ 0x04 +\& CRYPTO_WRITE 0x08 +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fICRYPTO_num_locks()\fR returns the required number of locks. +.PP +\&\fICRYPTO_get_new_dynlockid()\fR returns the index to the newly created lock. +.PP +The other functions return no values. +.SH "NOTES" +.IX Header "NOTES" +You can find out if OpenSSL was configured with thread support: +.PP +.Vb 7 +\& #define OPENSSL_THREAD_DEFINES +\& #include <openssl/opensslconf.h> +\& #if defined(OPENSSL_THREADS) +\& // thread support enabled +\& #else +\& // no thread support +\& #endif +.Ve +.PP +Also, dynamic locks are currently not used internally by OpenSSL, but +may do so in the future. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +\&\fBcrypto/threads/mttest.c\fR shows examples of the callback functions on +Solaris, Irix and Win32. +.SH "HISTORY" +.IX Header "HISTORY" +\&\fICRYPTO_set_locking_callback()\fR is +available in all versions of SSLeay and OpenSSL. +\&\fICRYPTO_num_locks()\fR was added in OpenSSL 0.9.4. +All functions dealing with dynamic locks were added in OpenSSL 0.9.5b\-dev. +\&\fB\s-1CRYPTO_THREADID\s0\fR and associated functions were introduced in OpenSSL 1.0.0 +to replace (actually, deprecate) the previous \fICRYPTO_set_id_callback()\fR, +\&\fICRYPTO_get_id_callback()\fR, and \fICRYPTO_thread_id()\fR functions which assumed +thread IDs to always be represented by 'unsigned long'. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIcrypto\fR\|(3) diff --git a/static/netbsd/man3/openssl_ui.3 b/static/netbsd/man3/openssl_ui.3 new file mode 100644 index 00000000..ca919904 --- /dev/null +++ b/static/netbsd/man3/openssl_ui.3 @@ -0,0 +1,326 @@ +.\" $NetBSD: openssl_ui.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ui 3" +.TH ui 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, +UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, +UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, +UI_add_error_string, UI_dup_error_string, UI_construct_prompt, +UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, +UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, +UI_set_method, UI_OpenSSL, ERR_load_UI_strings \- New User Interface +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ui.h> +\& +\& typedef struct ui_st UI; +\& typedef struct ui_method_st UI_METHOD; +\& +\& UI *UI_new(void); +\& UI *UI_new_method(const UI_METHOD *method); +\& void UI_free(UI *ui); +\& +\& int UI_add_input_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize); +\& int UI_dup_input_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize); +\& int UI_add_verify_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize, const char *test_buf); +\& int UI_dup_verify_string(UI *ui, const char *prompt, int flags, +\& char *result_buf, int minsize, int maxsize, const char *test_buf); +\& int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, +\& const char *ok_chars, const char *cancel_chars, +\& int flags, char *result_buf); +\& int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, +\& const char *ok_chars, const char *cancel_chars, +\& int flags, char *result_buf); +\& int UI_add_info_string(UI *ui, const char *text); +\& int UI_dup_info_string(UI *ui, const char *text); +\& int UI_add_error_string(UI *ui, const char *text); +\& int UI_dup_error_string(UI *ui, const char *text); +\& +\& /* These are the possible flags. They can be or\*(Aqed together. */ +\& #define UI_INPUT_FLAG_ECHO 0x01 +\& #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 +\& +\& char *UI_construct_prompt(UI *ui_method, +\& const char *object_desc, const char *object_name); +\& +\& void *UI_add_user_data(UI *ui, void *user_data); +\& void *UI_get0_user_data(UI *ui); +\& +\& const char *UI_get0_result(UI *ui, int i); +\& +\& int UI_process(UI *ui); +\& +\& int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); +\& #define UI_CTRL_PRINT_ERRORS 1 +\& #define UI_CTRL_IS_REDOABLE 2 +\& +\& void UI_set_default_method(const UI_METHOD *meth); +\& const UI_METHOD *UI_get_default_method(void); +\& const UI_METHOD *UI_get_method(UI *ui); +\& const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); +\& +\& UI_METHOD *UI_OpenSSL(void); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1UI\s0 stands for User Interface, and is general purpose set of routines to +prompt the user for text-based information. Through user-written methods +(see \fIui_create\fR\|(3)), prompting can be done in any way +imaginable, be it plain text prompting, through dialog boxes or from a +cell phone. +.PP +All the functions work through a context of the type \s-1UI. \s0 This context +contains all the information needed to prompt correctly as well as a +reference to a \s-1UI_METHOD,\s0 which is an ordered vector of functions that +carry out the actual prompting. +.PP +The first thing to do is to create a \s-1UI\s0 with \fIUI_new()\fR or \fIUI_new_method()\fR, +then add information to it with the UI_add or UI_dup functions. Also, +user-defined random data can be passed down to the underlying method +through calls to UI_add_user_data. The default \s-1UI\s0 method doesn't care +about these data, but other methods might. Finally, use \fIUI_process()\fR +to actually perform the prompting and \fIUI_get0_result()\fR to find the result +to the prompt. +.PP +A \s-1UI\s0 can contain more than one prompt, which are performed in the given +sequence. Each prompt gets an index number which is returned by the +UI_add and UI_dup functions, and has to be used to get the corresponding +result with \fIUI_get0_result()\fR. +.PP +The functions are as follows: +.PP +\&\fIUI_new()\fR creates a new \s-1UI\s0 using the default \s-1UI\s0 method. When done with +this \s-1UI,\s0 it should be freed using \fIUI_free()\fR. +.PP +\&\fIUI_new_method()\fR creates a new \s-1UI\s0 using the given \s-1UI\s0 method. When done with +this \s-1UI,\s0 it should be freed using \fIUI_free()\fR. +.PP +\&\fIUI_OpenSSL()\fR returns the built-in \s-1UI\s0 method (note: not the default one, +since the default can be changed. See further on). This method is the +most machine/OS dependent part of OpenSSL and normally generates the +most problems when porting. +.PP +\&\fIUI_free()\fR removes a \s-1UI\s0 from memory, along with all other pieces of memory +that's connected to it, like duplicated input strings, results and others. +.PP +\&\fIUI_add_input_string()\fR and \fIUI_add_verify_string()\fR add a prompt to the \s-1UI,\s0 +as well as flags and a result buffer and the desired minimum and maximum +sizes of the result, not counting the final \s-1NUL\s0 character. The given +information is used to prompt for information, for example a password, +and to verify a password (i.e. having the user enter it twice and check +that the same string was entered twice). \fIUI_add_verify_string()\fR takes +and extra argument that should be a pointer to the result buffer of the +input string that it's supposed to verify, or verification will fail. +.PP +\&\fIUI_add_input_boolean()\fR adds a prompt to the \s-1UI\s0 that's supposed to be answered +in a boolean way, with a single character for yes and a different character +for no. A set of characters that can be used to cancel the prompt is given +as well. The prompt itself is divided in two, one part being the +descriptive text (given through the \fIprompt\fR argument) and one describing +the possible answers (given through the \fIaction_desc\fR argument). +.PP +\&\fIUI_add_info_string()\fR and \fIUI_add_error_string()\fR add strings that are shown at +the same time as the prompt for extra information or to show an error string. +The difference between the two is only conceptual. With the builtin method, +there's no technical difference between them. Other methods may make a +difference between them, however. +.PP +The flags currently supported are \s-1UI_INPUT_FLAG_ECHO,\s0 which is relevant for +\&\fIUI_add_input_string()\fR and will have the users response be echoed (when +prompting for a password, this flag should obviously not be used, and +\&\s-1UI_INPUT_FLAG_DEFAULT_PWD,\s0 which means that a default password of some +sort will be used (completely depending on the application and the \s-1UI\s0 +method). +.PP +\&\fIUI_dup_input_string()\fR, \fIUI_dup_verify_string()\fR, \fIUI_dup_input_boolean()\fR, +\&\fIUI_dup_info_string()\fR and \fIUI_dup_error_string()\fR are basically the same +as their UI_add counterparts, except that they make their own copies +of all strings. +.PP +\&\fIUI_construct_prompt()\fR is a helper function that can be used to create +a prompt from two pieces of information: an description and a name. +The default constructor (if there is none provided by the method used) +creates a string "Enter \fIdescription\fR for \fIname\fR:\*(L". With the +description \*(R"pass phrase\*(L" and the file name \*(R"foo.key\*(L", that becomes +\&\*(R"Enter pass phrase for foo.key:". Other methods may create whatever +string and may include encodings that will be processed by the other +method functions. +.PP +\&\fIUI_add_user_data()\fR adds a piece of memory for the method to use at any +time. The builtin \s-1UI\s0 method doesn't care about this info. Note that several +calls to this function doesn't add data, it replaces the previous blob +with the one given as argument. +.PP +\&\fIUI_get0_user_data()\fR retrieves the data that has last been given to the +\&\s-1UI\s0 with \fIUI_add_user_data()\fR. +.PP +\&\fIUI_get0_result()\fR returns a pointer to the result buffer associated with +the information indexed by \fIi\fR. +.PP +\&\fIUI_process()\fR goes through the information given so far, does all the printing +and prompting and returns. +.PP +\&\fIUI_ctrl()\fR adds extra control for the application author. For now, it +understands two commands: \s-1UI_CTRL_PRINT_ERRORS,\s0 which makes \fIUI_process()\fR +print the OpenSSL error stack as part of processing the \s-1UI,\s0 and +\&\s-1UI_CTRL_IS_REDOABLE,\s0 which returns a flag saying if the used \s-1UI\s0 can +be used again or not. +.PP +\&\fIUI_set_default_method()\fR changes the default \s-1UI\s0 method to the one given. +.PP +\&\fIUI_get_default_method()\fR returns a pointer to the current default \s-1UI\s0 method. +.PP +\&\fIUI_get_method()\fR returns the \s-1UI\s0 method associated with a given \s-1UI.\s0 +.PP +\&\fIUI_set_method()\fR changes the \s-1UI\s0 method associated with a given \s-1UI.\s0 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIui_create\fR\|(3), \fIui_compat\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The \s-1UI\s0 section was first introduced in OpenSSL 0.9.7. +.SH "AUTHOR" +.IX Header "AUTHOR" +Richard Levitte (richard@levitte.org) for the OpenSSL project +(http://www.openssl.org). diff --git a/static/netbsd/man3/openssl_ui_compat.3 b/static/netbsd/man3/openssl_ui_compat.3 new file mode 100644 index 00000000..aca77ddd --- /dev/null +++ b/static/netbsd/man3/openssl_ui_compat.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: openssl_ui_compat.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ui_compat 3" +.TH ui_compat 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw \- +Compatibility user interface functions +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/des_old.h> +\& +\& int des_read_password(DES_cblock *key,const char *prompt,int verify); +\& int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, +\& const char *prompt,int verify); +\& +\& int des_read_pw_string(char *buf,int length,const char *prompt,int verify); +\& int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1DES\s0 library contained a few routines to prompt for passwords. These +aren't necessarely dependent on \s-1DES,\s0 and have therefore become part of the +\&\s-1UI\s0 compatibility library. +.PP +\&\fIdes_read_pw()\fR writes the string specified by \fIprompt\fR to standard output +turns echo off and reads an input string from the terminal. The string is +returned in \fIbuf\fR, which must have spac for at least \fIsize\fR bytes. +If \fIverify\fR is set, the user is asked for the password twice and unless +the two copies match, an error is returned. The second password is stored +in \fIbuff\fR, which must therefore also be at least \fIsize\fR bytes. A return +code of \-1 indicates a system error, 1 failure due to use interaction, and +0 is success. All other functions described here use \fIdes_read_pw()\fR to do +the work. +.PP +\&\fIdes_read_pw_string()\fR is a variant of \fIdes_read_pw()\fR that provides a buffer +for you if \fIverify\fR is set. +.PP +\&\fIdes_read_password()\fR calls \fIdes_read_pw()\fR and converts the password to a +\&\s-1DES\s0 key by calling \fIDES_string_to_key()\fR; \fIdes_read_2password()\fR operates in +the same way as \fIdes_read_password()\fR except that it generates two keys +by using the \fIDES_string_to_2key()\fR function. +.SH "NOTES" +.IX Header "NOTES" +\&\fIdes_read_pw_string()\fR is available in the \s-1MIT\s0 Kerberos library as well, and +is also available under the name \fIEVP_read_pw_string()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIui\fR\|(3), \fIui_create\fR\|(3) +.SH "AUTHOR" +.IX Header "AUTHOR" +Richard Levitte (richard@levitte.org) for the OpenSSL project +(http://www.openssl.org). diff --git a/static/netbsd/man3/openssl_x509.3 b/static/netbsd/man3/openssl_x509.3 new file mode 100644 index 00000000..3d241878 --- /dev/null +++ b/static/netbsd/man3/openssl_x509.3 @@ -0,0 +1,198 @@ +.\" $NetBSD: openssl_x509.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "x509 3" +.TH x509 3 "2009-07-19" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +x509 \- X.509 certificate handling +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/x509.h> +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +A X.509 certificate is a structured grouping of information about +an individual, a device, or anything one can imagine. A X.509 \s-1CRL +\&\s0(certificate revocation list) is a tool to help determine if a +certificate is still valid. The exact definition of those can be +found in the X.509 document from ITU-T, or in \s-1RFC3280\s0 from \s-1PKIX.\s0 +In OpenSSL, the type X509 is used to express such a certificate, and +the type X509_CRL is used to express a \s-1CRL.\s0 +.PP +A related structure is a certificate request, defined in PKCS#10 from +\&\s-1RSA\s0 Security, Inc, also reflected in \s-1RFC2896. \s0 In OpenSSL, the type +X509_REQ is used to express such a certificate request. +.PP +To handle some complex parts of a certificate, there are the types +X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express +a certificate attributes), X509_EXTENSION (to express a certificate +extension) and a few more. +.PP +Finally, there's the supertype X509_INFO, which can contain a \s-1CRL,\s0 a +certificate and a corresponding private key. +.PP +\&\fBX509_\fR\fI...\fR, \fBd2i_X509_\fR\fI...\fR and \fBi2d_X509_\fR\fI...\fR handle X.509 +certificates, with some exceptions, shown below. +.PP +\&\fBX509_CRL_\fR\fI...\fR, \fBd2i_X509_CRL_\fR\fI...\fR and \fBi2d_X509_CRL_\fR\fI...\fR +handle X.509 CRLs. +.PP +\&\fBX509_REQ_\fR\fI...\fR, \fBd2i_X509_REQ_\fR\fI...\fR and \fBi2d_X509_REQ_\fR\fI...\fR +handle PKCS#10 certificate requests. +.PP +\&\fBX509_NAME_\fR\fI...\fR handle certificate names. +.PP +\&\fBX509_ATTRIBUTE_\fR\fI...\fR handle certificate attributes. +.PP +\&\fBX509_EXTENSION_\fR\fI...\fR handle certificate extensions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIX509_NAME_ENTRY_get_object\fR\|(3), +\&\fIX509_NAME_add_entry_by_txt\fR\|(3), +\&\fIX509_NAME_add_entry_by_NID\fR\|(3), +\&\fIX509_NAME_print_ex\fR\|(3), +\&\fIX509_NAME_new\fR\|(3), +\&\fId2i_X509\fR\|(3), +\&\fId2i_X509_ALGOR\fR\|(3), +\&\fId2i_X509_CRL\fR\|(3), +\&\fId2i_X509_NAME\fR\|(3), +\&\fId2i_X509_REQ\fR\|(3), +\&\fId2i_X509_SIG\fR\|(3), +\&\fIcrypto\fR\|(3), +\&\fIx509v3\fR\|(3) diff --git a/static/netbsd/man3/ossaudio.3 b/static/netbsd/man3/ossaudio.3 new file mode 100644 index 00000000..19b6bf88 --- /dev/null +++ b/static/netbsd/man3/ossaudio.3 @@ -0,0 +1,147 @@ +.\" $NetBSD: ossaudio.3,v 1.28 2022/12/04 11:25:09 uwe Exp $ +.\" +.\" Copyright (c) 1997, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson and Nia Alarie. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 20, 2020 +.Dt OSSAUDIO 3 +.Os +.Sh NAME +.Nm ossaudio +.Nd Open Sound System emulation +.Sh LIBRARY +.Lb libossaudio +.Sh SYNOPSIS +.In soundcard.h +.Sh DESCRIPTION +The +.Nm +library provides an emulation of the Open Sound System audio interface. +.Pp +Use the native +.Xr audio 4 +and +.Xr mixer 4 +interfaces for new programs, and this emulation library only for +building code written for other operating systems. +.Ss Mixer Control Map +The following table summarizes the mappings from native interface +device names to OSSv3 mixer controls. +.Bl -column ".Sy Native Device Name" "SOUND_MIXER_SPEAKER" +.It Sy "Native Device Name" Ta Sy "OSS Mixer Control" +.It *.mic Ta SOUND_MIXER_MIC +.It *.line Ta SOUND_MIXER_LINE +.It *.cd Ta SOUND_MIXER_CD +.It *.dac Ta SOUND_MIXER_PCM +.It *.aux Ta SOUND_MIXER_LINE1 +.It *.record Ta SOUND_MIXER_IMIX +.It *.master Ta SOUND_MIXER_VOLUME +.It *.treble Ta SOUND_MIXER_TREBLE +.It *.bass Ta SOUND_MIXER_BASS +.It *.speaker Ta SOUND_MIXER_SPEAKER +.It *.output Ta SOUND_MIXER_OGAIN +.It *.input Ta SOUND_MIXER_IGAIN +.It *.fmsynth Ta SOUND_MIXER_SYNTH +.It *.midi Ta SOUND_MIXER_SYNTH +.El +.Sh COMPATIBILITY +The +.Nm +interface aims to be compatible with the Open Sound System version 4, as +described in: +.Pp +.Rs +.%A 4Front Technologies +.%T OSS 4.x Programmer's Guide +.%U http://manuals.opensound.com/developer/ +.%D 2007 +.Re +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr audio 4 , +.Xr midi 4 , +.Xr mixer 4 +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 1.3 . +.Pp +The Open Sound System up to version 3 was originally the preferred +API for writing audio code under Linux until ALSA became the new default +in Linux 2.6. +It remains the preferred API in +.Fx +and Solaris, and a large body of code exists supporting it. +.Sh BUGS +.Bl -bullet +.It +The emulation is incomplete. +Some less popular features are not emulated (e.g. sync groups), but the +essential ioctls used by the majority of software are covered. +.It +.Nx +.Dv AUDIO_MIXER_SET +control types cannot be accurately represented in the OSSv4 mixer API, +so are treated as enums. +.It +Per-stream volume (i.e. +.Dv SNDCTL_DSP_SETPLAYVOL ) +is not currently implemented as in OSSv4, and will instead modify the +global volume. +Applications need to provide samples with the appropriate gain. +.It +Linux, +.Fx , +and Solaris provide +.Pa /dev/dsp +and +.Pa /dev/mixer +devices in place of the +.Pa /dev/audio +and +.Pa /dev/mixer +devices this compatibility layer must be accessed through on +.Nx . +However, changing this is typically trivial when porting programs. +.It +The emulation only covers +.Fn ioctl , +there are other differences as well. +E.g., on a write +that would block in non-blocking mode Linux returns +.Er EINTR +whereas +.Nx 1.3 +returns +.Er EAGAIN . +.It +The emulation uses a #define for +.Fn ioctl +so some obscure programs +can fail to compile. +.El diff --git a/static/netbsd/man3/p.3 b/static/netbsd/man3/p.3 new file mode 100644 index 00000000..e2eb0d28 --- /dev/null +++ b/static/netbsd/man3/p.3 @@ -0,0 +1 @@ +{ printf "[%10s] [%-16d]\n", $1, $3 } diff --git a/static/netbsd/man3/p2k.3 b/static/netbsd/man3/p2k.3 new file mode 100644 index 00000000..7aadb370 --- /dev/null +++ b/static/netbsd/man3/p2k.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: p2k.3,v 1.13 2024/10/13 14:56:30 rillig Exp $ +.\" +.\" Copyright (c) 2008 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 13, 2024 +.Dt P2K 3 +.Os +.Sh NAME +.Nm p2k +.Nd puffs to kernel vfs translation library +.Sh LIBRARY +p2k Library (libp2k, \-lp2k) +.Sh SYNOPSIS +.In rump/p2k.h +.Ft struct p2k_mount * +.Fn p2k_init "uint32_t puffs_flags" +.Ft void +.Fn p2k_cancel "struct p2k_mount *p2m" "int error" +.Ft int +.Fo p2k_setup_fs +.Fa "struct p2k_mount *p2m" "const char *vfsname" "const char *devpath" +.Fa "const char *mountpath" "int mntflags" "void *arg" "size_t alen" +.Fc +.Ft int +.Fo p2k_setup_diskfs +.Fa "struct p2k_mount *p2m" "const char *vfsname" "const char *devpath" +.Fa "struct ukfs_part *part" "const char *mountpath" "int mntflags" +.Fa "void *arg" "size_t alen" +.Fc +.Ft int +.Fn p2k_mainloop "struct p2k_mount *p2m" +.Ft int +.Fo p2k_run_fs +.Fa "const char *vfsname" "const char *devpath" "const char *mountpath" +.Fa "int mntflags" "void *arg" "size_t alen" "uint32_t puffs_flags" +.Fc +.Ft int +.Fo p2k_run_diskfs +.Fa "const char *vfsname" "const char *devpath" "struct ukfs_part *part" +.Fa "const char *mountpath" "int mntflags" "void *arg" "size_t alen" +.Fa "uint32_t puffs_flags" +.Fc +.Sh DESCRIPTION +The +.Nm +library translates the puffs protocol to the kernel +.Xr vfs 9 +protocol and back again. +It can therefore be used to mount and run kernel file system code as +a userspace daemon. +.Pp +Calling the library interface function mounts the file system and, +if successful, starts handling requests. +The parameters are handled by +.Fn ukfs_mount +(see +.Xr ukfs 3 ) , +with the exception that +.Fa mountpath +and +.Fa puffs_flags +are handled by +.Xr puffs 3 . +The "run_fs" variants of the interfaces are provided as a convenience +for the common case. +They execute all of init, setup and mainloop in one call. +.Sh ENVIRONMENT +The following environment variables affect the behaviour of +.Nm . +They are useful mostly for debugging purposes. +The flags are environment variables because typically the command line +arguments to +.Nm +utilities are parsed using versions not aware of +.Nm +options; for example, the +.Xr rump_cd9660 8 +arguments are really parsed by +.Xr mount_cd9660 8 . +.Bl -tag -width "XP2K_NOCACHE_PAGE" -offset 2n +.It Dv P2K_DEBUG +Do not detach from tty and print information about each puffs operation. +In case the daemon receives +.Dv SIGINFO +(typically from ctrl-T), it dumps out the status of the mount point. +Sending +.Dv SIGUSR1 +causes a dump of all the vnodes (verbose). +.It Dv P2K_NODETACH +Do not detach from tty. +.It Dv P2K_NOCACHE_PAGE +Do not use the puffs page cache. +.It Dv P2K_NOCACHE_NAME +Do not use the puffs name cache. +.It Dv P2K_NOCACHE +Do not use the puffs page or name cache. +.It Dv P2K_WIZARDUID +If set, use the value of the variable to determine the UID of the +caller of each operation instead of the actual caller supplied by +.Xr puffs 3 . +This can be used for example to simplify modifying an OS installation's +root image as a non-root user. +.El +.Sh SEE ALSO +.Xr puffs 3 , +.Xr rump 3 , +.Xr ukfs 3 , +.Xr rump_cd9660 8 , +.Xr rump_efs 8 , +.Xr rump_ext2fs 8 , +.Xr rump_ffs 8 , +.Xr rump_hfs 8 , +.Xr rump_lfs 8 , +.Xr rump_msdos 8 , +.Xr rump_nfs 8 , +.Xr rump_ntfs 8 , +.Xr rump_syspuffs 8 , +.Xr rump_sysvbfs 8 , +.Xr rump_tmpfs 8 , +.Xr rump_udf 8 diff --git a/static/netbsd/man3/page_ca.3 b/static/netbsd/man3/page_ca.3 new file mode 100644 index 00000000..77e2ceb5 --- /dev/null +++ b/static/netbsd/man3/page_ca.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_ca.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_ca" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_ca \- Hx509 CA functions +See the library functions here: \fBhx509 CA functions\fP diff --git a/static/netbsd/man3/page_cert.3 b/static/netbsd/man3/page_cert.3 new file mode 100644 index 00000000..cde19fe8 --- /dev/null +++ b/static/netbsd/man3/page_cert.3 @@ -0,0 +1,12 @@ +.\" $NetBSD: page_cert.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_cert" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_cert \- The basic certificate +The basic hx509 cerificate object in hx509 is hx509_cert\&. The hx509_cert object is representing one X509/PKIX certificate and associated attributes; like private key, friendly name, etc\&. +.PP +A hx509_cert object is usully found via the keyset interfaces (\fBCertificate store operations\fP), but its also possible to create a certificate directly from a parsed object with \fBhx509_cert_init()\fP and \fBhx509_cert_init_data()\fP\&. +.PP +See the library functions here: \fBhx509 certificate functions\fP diff --git a/static/netbsd/man3/page_cms.3 b/static/netbsd/man3/page_cms.3 new file mode 100644 index 00000000..14528408 --- /dev/null +++ b/static/netbsd/man3/page_cms.3 @@ -0,0 +1,20 @@ +.\" $NetBSD: page_cms.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_cms" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_cms \- CMS/PKCS7 message functions\&. +CMS is defined in RFC 3369 and is an continuation of the RSA Labs standard PKCS7\&. The basic messages in CMS is +.PP +.IP "\(bu" 2 +SignedData Data signed with private key (RSA, DSA, ECDSA) or secret (symmetric) key +.IP "\(bu" 2 +EnvelopedData Data encrypted with private key (RSA) +.IP "\(bu" 2 +EncryptedData Data encrypted with secret (symmetric) key\&. +.IP "\(bu" 2 +ContentInfo Wrapper structure including type and data\&. +.PP +.PP +See the library functions here: \fBhx509 CMS/pkcs7 functions\fP diff --git a/static/netbsd/man3/page_des.3 b/static/netbsd/man3/page_des.3 new file mode 100644 index 00000000..c66ed5e5 --- /dev/null +++ b/static/netbsd/man3/page_des.3 @@ -0,0 +1,38 @@ +.\" $NetBSD: page_des.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "page_des" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_des \- DES - Data Encryption Standard crypto interface +See the library functions here: \fBDES crypto functions\fP +.PP +DES was created by IBM, modififed by NSA and then adopted by NBS (now NIST) and published ad FIPS PUB 46 (updated by FIPS 46-1)\&. +.PP +Since the 19th May 2005 DES was withdrawn by NIST and should no longer be used\&. See \fBEVP - generic crypto interface\fP for replacement encryption algorithms and interfaces\&. +.PP +Read more the iteresting history of DES on Wikipedia http://www.wikipedia.org/wiki/Data_Encryption_Standard \&. +.SH "DES key generation" +.PP +To generate a DES key safely you have to use the code-snippet below\&. This is because the \fBDES_random_key()\fP can fail with an abort() in case of and failure to start the random generator\&. +.PP +There is a replacement function \fBDES_new_random_key()\fP, however that function does not exists in OpenSSL\&. +.PP +.PP +.nf +DES_cblock key; +do { + if (RAND_rand(&key, sizeof(key)) != 1) + goto failure; + DES_set_odd_parity(key); +} while (DES_is_weak_key(&key)); +.fi +.PP +.SH "DES implementation history" +.PP +There was no complete BSD licensed, fast, GPL compatible implementation of DES, so Love wrote the part that was missing, fast key schedule setup and adapted the interface to the orignal libdes\&. +.PP +The document that got me started for real was 'Efficient +Implementation of the Data Encryption Standard' by Dag Arne Osvik\&. I never got to the PC1 transformation was working, instead I used table-lookup was used for all key schedule setup\&. The document was very useful since it de-mystified other implementations for me\&. +.PP +The core DES function (SBOX + P transformation) is from Richard Outerbridge public domain DES implementation\&. My sanity is saved thanks to his work\&. Thank you Richard\&. diff --git a/static/netbsd/man3/page_dh.3 b/static/netbsd/man3/page_dh.3 new file mode 100644 index 00000000..b6babfdb --- /dev/null +++ b/static/netbsd/man3/page_dh.3 @@ -0,0 +1,12 @@ +.\" $NetBSD: page_dh.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "page_dh" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_dh \- DH - Diffie-Hellman key exchange +Diffie-Hellman key exchange is a protocol that allows two parties to establish a shared secret key\&. +.PP +Include and example how to use \fBDH_new()\fP and friends here\&. +.PP +See the library functions here: \fBDiffie-Hellman functions\fP diff --git a/static/netbsd/man3/page_env.3 b/static/netbsd/man3/page_env.3 new file mode 100644 index 00000000..a42bd569 --- /dev/null +++ b/static/netbsd/man3/page_env.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_env.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_env" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_env \- Hx509 environment functions +See the library functions here: \fBhx509 environment functions\fP diff --git a/static/netbsd/man3/page_error.3 b/static/netbsd/man3/page_error.3 new file mode 100644 index 00000000..225994fc --- /dev/null +++ b/static/netbsd/man3/page_error.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_error.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_error" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_error \- Hx509 error reporting functions +See the library functions here: \fBhx509 error functions\fP diff --git a/static/netbsd/man3/page_evp.3 b/static/netbsd/man3/page_evp.3 new file mode 100644 index 00000000..1279a2ef --- /dev/null +++ b/static/netbsd/man3/page_evp.3 @@ -0,0 +1,11 @@ +.\" $NetBSD: page_evp.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "page_evp" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_evp \- EVP - generic crypto interface +See the library functions here: \fBEVP generic crypto functions\fP +.SH "EVP Cipher" +.PP +The use of \fBEVP_CipherInit_ex()\fP and EVP_Cipher() is pretty easy to understand forward, then \fBEVP_CipherUpdate()\fP and \fBEVP_CipherFinal_ex()\fP really needs an example to explain \fBexample_evp_cipher\&.c\fP \&. diff --git a/static/netbsd/man3/page_keyset.3 b/static/netbsd/man3/page_keyset.3 new file mode 100644 index 00000000..86a2a3a2 --- /dev/null +++ b/static/netbsd/man3/page_keyset.3 @@ -0,0 +1,27 @@ +.\" $NetBSD: page_keyset.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_keyset" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_keyset \- Certificate store operations +Type of certificates store: +.IP "\(bu" 2 +MEMORY In memory based format\&. Doesnt support storing\&. +.IP "\(bu" 2 +FILE FILE supports raw DER certicates and PEM certicates\&. When PEM is used the file can contain may certificates and match private keys\&. Support storing the certificates\&. DER format only supports on certificate and no private key\&. +.IP "\(bu" 2 +PEM-FILE Same as FILE, defaulting to PEM encoded certificates\&. +.IP "\(bu" 2 +PEM-FILE Same as FILE, defaulting to DER encoded certificates\&. +.IP "\(bu" 2 +PKCS11 +.IP "\(bu" 2 +PKCS12 +.IP "\(bu" 2 +DIR +.IP "\(bu" 2 +KEYCHAIN Apple Mac OS X KeyChain backed keychain object\&. +.PP +.PP +See the library functions here: \fBhx509 certificate store functions\fP diff --git a/static/netbsd/man3/page_lock.3 b/static/netbsd/man3/page_lock.3 new file mode 100644 index 00000000..14415370 --- /dev/null +++ b/static/netbsd/man3/page_lock.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_lock.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_lock" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_lock \- Locking and unlocking certificates and encrypted data\&. +See the library functions here: \fBhx509 lock functions\fP diff --git a/static/netbsd/man3/page_name.3 b/static/netbsd/man3/page_name.3 new file mode 100644 index 00000000..fad69e91 --- /dev/null +++ b/static/netbsd/man3/page_name.3 @@ -0,0 +1,20 @@ +.\" $NetBSD: page_name.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_name" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_name \- PKIX/X\&.509 Names +There are several names in PKIX/X\&.509, GeneralName and Name\&. +.PP +A Name consists of an ordered list of Relative Distinguished Names (RDN)\&. Each RDN consists of an unordered list of typed strings\&. The types are defined by OID and have long and short description\&. For example id-at-commonName (2\&.5\&.4\&.3) have the long name CommonName and short name CN\&. The string itself can be of several encoding, UTF8, UTF16, Teltex string, etc\&. The type limit what encoding should be used\&. +.PP +GeneralName is a broader nametype that can contains al kind of stuff like Name, IP addresses, partial Name, etc\&. +.PP +Name is mapped into a hx509_name object\&. +.PP +Parse and string name into a hx509_name object with \fBhx509_parse_name()\fP, make it back into string representation with \fBhx509_name_to_string()\fP\&. +.PP +Name string are defined rfc2253, rfc1779 and X\&.501\&. +.PP +See the library functions here: \fBhx509 name functions\fP diff --git a/static/netbsd/man3/page_peer.3 b/static/netbsd/man3/page_peer.3 new file mode 100644 index 00000000..53b884b8 --- /dev/null +++ b/static/netbsd/man3/page_peer.3 @@ -0,0 +1,10 @@ +.\" $NetBSD: page_peer.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_peer" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_peer \- Hx509 crypto selecting functions +Peer info structures are used togeter with hx509_crypto_select() to select the best avaible crypto algorithm to use\&. +.PP +See the library functions here: \fBhx509 certificate selecting functions\fP diff --git a/static/netbsd/man3/page_print.3 b/static/netbsd/man3/page_print.3 new file mode 100644 index 00000000..f0e9ae0f --- /dev/null +++ b/static/netbsd/man3/page_print.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_print.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_print" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_print \- Hx509 printing functions +See the library functions here: \fBhx509 printing functions\fP diff --git a/static/netbsd/man3/page_rand.3 b/static/netbsd/man3/page_rand.3 new file mode 100644 index 00000000..7a671506 --- /dev/null +++ b/static/netbsd/man3/page_rand.3 @@ -0,0 +1,8 @@ +.\" $NetBSD: page_rand.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "page_rand" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_rand \- RAND - random number +See the library functions here: \fBRAND crypto functions\fP diff --git a/static/netbsd/man3/page_revoke.3 b/static/netbsd/man3/page_revoke.3 new file mode 100644 index 00000000..bb8089d8 --- /dev/null +++ b/static/netbsd/man3/page_revoke.3 @@ -0,0 +1,12 @@ +.\" $NetBSD: page_revoke.3,v 1.3 2023/06/19 21:41:40 christos Exp $ +.\" +.TH "page_revoke" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal x509 library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_revoke \- Revocation methods +There are two revocation method for PKIX/X\&.509: CRL and OCSP\&. Revocation is needed if the private key is lost and stolen\&. Depending on how picky you are, you might want to make revocation for destroyed private keys too (smartcard broken), but that should not be a problem\&. +.PP +CRL is a list of certifiates that have expired\&. +.PP +OCSP is an online checking method where the requestor sends a list of certificates to the OCSP server to return a signed reply if they are valid or not\&. Some services sends a OCSP reply as part of the hand-shake to make the revoktion decision simpler/faster for the client\&. diff --git a/static/netbsd/man3/page_rsa.3 b/static/netbsd/man3/page_rsa.3 new file mode 100644 index 00000000..68f89ab5 --- /dev/null +++ b/static/netbsd/man3/page_rsa.3 @@ -0,0 +1,15 @@ +.\" $NetBSD: page_rsa.3,v 1.3 2023/06/19 21:41:39 christos Exp $ +.\" +.TH "page_rsa" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal crypto library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +page_rsa \- RSA - public-key cryptography +RSA is named by its inventors (Ron Rivest, Adi Shamir, and Leonard Adleman) (published in 1977), patented expired in 21 September 2000\&. +.PP +Speed for RSA in seconds no key blinding 1000 iteration, same rsa keys (1024 and 2048) operation performed each eteration sign, verify, encrypt, decrypt on a random bit pattern +.SH "name 1024 2048 4098" +.PP +gmp: 0\&.73 6\&.60 44\&.80 tfm: 2\&.45 -- -- ltm: 3\&.79 20\&.74 105\&.41 (default in hcrypto) openssl: 4\&.04 11\&.90 82\&.59 cdsa: 15\&.89 102\&.89 721\&.40 imath: 40\&.62 -- -- +.PP +See the library functions here: \fBRSA functions\fP diff --git a/static/netbsd/man3/pam.3 b/static/netbsd/man3/pam.3 new file mode 100644 index 00000000..683ad311 --- /dev/null +++ b/static/netbsd/man3/pam.3 @@ -0,0 +1,268 @@ +.\" $NetBSD: pam.3,v 1.13 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated by gendoc.pl +.Dd May 31, 2025 +.Dt PAM 3 +.Os +.Sh NAME +.Nm pam_acct_mgmt , +.Nm pam_authenticate , +.Nm pam_chauthtok , +.Nm pam_close_session , +.Nm pam_end , +.Nm pam_get_data , +.Nm pam_get_item , +.Nm pam_get_user , +.Nm pam_getenv , +.Nm pam_getenvlist , +.Nm pam_open_session , +.Nm pam_putenv , +.Nm pam_set_data , +.Nm pam_set_item , +.Nm pam_setcred , +.Nm pam_start , +.Nm pam_strerror +.Nd Pluggable Authentication Modules Library +.Sh LIBRARY +.Lb libpam +.Sh SYNOPSIS +.In security/pam_appl.h +.Ft "int" +.Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_authenticate "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_chauthtok "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_close_session "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_end "pam_handle_t *pamh" "int status" +.Ft "int" +.Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data" +.Ft "int" +.Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item" +.Ft "int" +.Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt" +.Ft "const char *" +.Fn pam_getenv "pam_handle_t *pamh" "const char *name" +.Ft "char **" +.Fn pam_getenvlist "pam_handle_t *pamh" +.Ft "int" +.Fn pam_open_session "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue" +.Ft "int" +.Fn pam_set_data "pam_handle_t *pamh" "const char *module_data_name" "void *data" "void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)" +.Ft "int" +.Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item" +.Ft "int" +.Fn pam_setcred "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh" +.Ft "const char *" +.Fn pam_strerror "const pam_handle_t *pamh" "int error_number" +.Sh DESCRIPTION +The Pluggable Authentication Modules (PAM) library abstracts a number +of common authentication-related operations and provides a framework +for dynamically loaded modules that implement these operations in +various ways. +.Ss Terminology +In PAM parlance, the application that uses PAM to authenticate a user +is the server, and is identified for configuration purposes by a +service name, which is often (but not necessarily) the program name. +.Pp +The user requesting authentication is called the applicant, while the +user (usually, root) charged with verifying his identity and granting +him the requested credentials is called the arbitrator. +.Pp +The sequence of operations the server goes through to authenticate a +user and perform whatever task he requested is a PAM transaction; the +context within which the server performs the requested task is called +a session. +.Pp +The functionality embodied by PAM is divided into six primitives +grouped into four facilities: authentication, account management, +session management and password management. +.Ss Conversation +The PAM library expects the application to provide a conversation +callback which it can use to communicate with the user. +Some modules may use specialized conversation functions to communicate +with special hardware such as cryptographic dongles or biometric +devices. +See +.Xr pam_conv 3 +for details. +.Ss Initialization and Cleanup +The +.Fn pam_start +function initializes the PAM library and returns a handle which must +be provided in all subsequent function calls. +The transaction state is contained entirely within the structure +identified by this handle, so it is possible to conduct multiple +transactions in parallel. +.Pp +The +.Fn pam_end +function releases all resources associated with the specified context, +and can be called at any time to terminate a PAM transaction. +.Ss Storage +The +.Fn pam_set_item +and +.Fn pam_get_item +functions set and retrieve a number of predefined items, including the +service name, the names of the requesting and target users, the +conversation function, and prompts. +.Pp +The +.Fn pam_set_data +and +.Fn pam_get_data +functions manage named chunks of free-form data, generally used by +modules to store state from one invocation to another. +.Ss Authentication +There are two authentication primitives: +.Fn pam_authenticate +and +.Fn pam_setcred . +The former authenticates the user, while the latter manages his +credentials. +.Ss Account Management +The +.Fn pam_acct_mgmt +function enforces policies such as password expiry, account expiry, +time-of-day restrictions, and so forth. +.Ss Session Management +The +.Fn pam_open_session +and +.Fn pam_close_session +functions handle session setup and teardown. +.Ss Password Management +The +.Fn pam_chauthtok +function allows the server to change the user's password, either at +the user's request or because the password has expired. +.Ss Miscellaneous +The +.Fn pam_putenv , +.Fn pam_getenv +and +.Fn pam_getenvlist +functions manage a private environment list in which modules can set +environment variables they want the server to export during the +session. +.Pp +The +.Fn pam_strerror +function returns a pointer to a string describing the specified PAM +error code. +.Sh RETURN VALUES +The following return codes are defined by +.In security/pam_constants.h : +.Bl -tag -width 18n +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_ACCT_EXPIRED +User account has expired. +.It Bq Er PAM_AUTHINFO_UNAVAIL +Authentication information is unavailable. +.It Bq Er PAM_AUTHTOK_DISABLE_AGING +Authentication token aging disabled. +.It Bq Er PAM_AUTHTOK_ERR +Authentication token failure. +.It Bq Er PAM_AUTHTOK_EXPIRED +Password has expired. +.It Bq Er PAM_AUTHTOK_LOCK_BUSY +Authentication token lock busy. +.It Bq Er PAM_AUTHTOK_RECOVERY_ERR +Failed to recover old authentication token. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BAD_FEATURE +Unrecognized or restricted feature. +.It Bq Er PAM_BAD_HANDLE +Invalid PAM handle. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_ERR +Failed to set user credentials. +.It Bq Er PAM_CRED_EXPIRED +User credentials have expired. +.It Bq Er PAM_CRED_INSUFFICIENT +Insufficient credentials. +.It Bq Er PAM_CRED_UNAVAIL +Failed to retrieve user credentials. +.It Bq Er PAM_DOMAIN_UNKNOWN +Unknown authentication domain. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_MAXTRIES +Maximum number of tries exceeded. +.It Bq Er PAM_MODULE_UNKNOWN +Unknown module type. +.It Bq Er PAM_NEW_AUTHTOK_REQD +New authentication token required. +.It Bq Er PAM_NO_MODULE_DATA +Module data not found. +.It Bq Er PAM_OPEN_ERR +Failed to load module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_SYMBOL_ERR +Invalid symbol. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_TRY_AGAIN +Try again. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr openpam 3 , +.Xr pam_acct_mgmt 3 , +.Xr pam_authenticate 3 , +.Xr pam_chauthtok 3 , +.Xr pam_close_session 3 , +.Xr pam_conv 3 , +.Xr pam_end 3 , +.Xr pam_get_data 3 , +.Xr pam_getenv 3 , +.Xr pam_getenvlist 3 , +.Xr pam_get_item 3 , +.Xr pam_get_user 3 , +.Xr pam_open_session 3 , +.Xr pam_putenv 3 , +.Xr pam_setcred 3 , +.Xr pam_set_data 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The OpenPAM library and this manual page were developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_acct_mgmt.3 b/static/netbsd/man3/pam_acct_mgmt.3 new file mode 100644 index 00000000..ea5d5e92 --- /dev/null +++ b/static/netbsd/man3/pam_acct_mgmt.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: pam_acct_mgmt.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_acct_mgmt.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_ACCT_MGMT 3 +.Os +.Sh NAME +.Nm pam_acct_mgmt +.Nd perform PAM account validation procedures +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_acct_mgmt +function verifies and enforces account restrictions +after the user has been authenticated. +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.It Dv PAM_DISALLOW_NULL_AUTHTOK +Fail if the user's authentication token is null. +.El +.Pp +If any other bits are set, +.Fn pam_acct_mgmt +will return +.Dv PAM_SYMBOL_ERR . +.Sh RETURN VALUES +The +.Fn pam_acct_mgmt +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_ACCT_EXPIRED +User account has expired. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_NEW_AUTHTOK_REQD +New authentication token required. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_acct_mgmt +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_authenticate.3 b/static/netbsd/man3/pam_authenticate.3 new file mode 100644 index 00000000..0a3d7307 --- /dev/null +++ b/static/netbsd/man3/pam_authenticate.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: pam_authenticate.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_authenticate.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_AUTHENTICATE 3 +.Os +.Sh NAME +.Nm pam_authenticate +.Nd perform authentication within the PAM framework +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_authenticate "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_authenticate +function attempts to authenticate the user +associated with the pam context specified by the +.Fa pamh +argument. +.Pp +The application is free to call +.Fn pam_authenticate +as many times as it +wishes, but some modules may maintain an internal retry counter and +return +.Dv PAM_MAXTRIES +when it exceeds some preset or hardcoded limit. +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.It Dv PAM_DISALLOW_NULL_AUTHTOK +Fail if the user's authentication token is null. +.El +.Pp +If any other bits are set, +.Fn pam_authenticate +will return +.Dv PAM_BAD_CONSTANT . +.Sh RETURN VALUES +The +.Fn pam_authenticate +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_AUTHINFO_UNAVAIL +Authentication information is unavailable. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_INSUFFICIENT +Insufficient credentials. +.It Bq Er PAM_MAXTRIES +Maximum number of tries exceeded. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_authenticate +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_chauthtok.3 b/static/netbsd/man3/pam_chauthtok.3 new file mode 100644 index 00000000..054b2bcd --- /dev/null +++ b/static/netbsd/man3/pam_chauthtok.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: pam_chauthtok.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_chauthtok.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_CHAUTHTOK 3 +.Os +.Sh NAME +.Nm pam_chauthtok +.Nd perform password related functions within the PAM framework +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_chauthtok "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_chauthtok +function attempts to change the authentication token +for the user associated with the pam context specified by the +.Fa pamh +argument. +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.It Dv PAM_CHANGE_EXPIRED_AUTHTOK +Change only those authentication tokens that have expired. +.El +.Pp +If any other bits are set, +.Fn pam_chauthtok +will return +.Dv PAM_BAD_CONSTANT . +.Sh RETURN VALUES +The +.Fn pam_chauthtok +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_AUTHTOK_DISABLE_AGING +Authentication token aging disabled. +.It Bq Er PAM_AUTHTOK_ERR +Authentication token failure. +.It Bq Er PAM_AUTHTOK_LOCK_BUSY +Authentication token lock busy. +.It Bq Er PAM_AUTHTOK_RECOVERY_ERR +Failed to recover old authentication token. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_TRY_AGAIN +Try again. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_chauthtok +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_close_session.3 b/static/netbsd/man3/pam_close_session.3 new file mode 100644 index 00000000..2a52fa99 --- /dev/null +++ b/static/netbsd/man3/pam_close_session.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: pam_close_session.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_close_session.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_CLOSE_SESSION 3 +.Os +.Sh NAME +.Nm pam_close_session +.Nd close an existing user session +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_close_session "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_close_session +function tears down the user session previously +set up by +.Xr pam_open_session 3 . +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.El +.Pp +If any other bits are set, +.Fn pam_close_session +will return +.Dv PAM_BAD_CONSTANT . +.Sh RETURN VALUES +The +.Fn pam_close_session +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_open_session 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_close_session +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_conv.3 b/static/netbsd/man3/pam_conv.3 new file mode 100644 index 00000000..42c43182 --- /dev/null +++ b/static/netbsd/man3/pam_conv.3 @@ -0,0 +1,187 @@ +.\" $NetBSD: pam_conv.3,v 1.11 2025/09/03 16:06:25 christos Exp $ +.\" +.\"- +.\" Copyright (c) 2002-2003 Networks Associates Technology, Inc. +.\" Copyright (c) 2004-2017 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by ThinkSec AS and +.\" Network Associates Laboratories, the Security Research Division of +.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +.\" ("CBOSS"), as part of the DARPA CHATS research program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 31, 2025 +.Dt PAM_CONV 3 +.Os +.Sh NAME +.Nm pam_conv +.Nd PAM conversation system +.Sh LIBRARY +.Lb libpam +.Sh SYNOPSIS +.In security/pam_appl.h +.Bd -literal +struct pam_message { + int msg_style; + char *msg; +}; + +struct pam_response { + char *resp; + int resp_retcode; +}; + +struct pam_conv { + int (*conv)(int, const struct pam_message **, + struct pam_response **, void *); + void *appdata_ptr; +}; +.Ed +.Sh DESCRIPTION +The PAM library uses an application-defined callback to communicate +with the user. +This callback is specified by the +.Vt struct pam_conv +passed to +.Fn pam_start +at the start of the transaction. +It is also possible to set or change the conversation function at any +point during a PAM transaction by changing the value of the +.Dv PAM_CONV +item. +.Pp +The conversation function's first argument specifies the number of +messages (up to +.Dv PAM_MAX_NUM_MSG ) +to process. +The second argument is a pointer to an array of pointers to +.Vt pam_message +structures containing the actual messages. +.Pp +Each message can have one of four types, specified by the +.Va msg_style +member of +.Vt struct pam_message : +.Bl -tag -width 18n +.It Dv PAM_PROMPT_ECHO_OFF +Display a prompt and accept the user's response without echoing it to +the terminal. +This is commonly used for passwords. +.It Dv PAM_PROMPT_ECHO_ON +Display a prompt and accept the user's response, echoing it to the +terminal. +This is commonly used for login names and one-time passphrases. +.It Dv PAM_ERROR_MSG +Display an error message. +.It Dv PAM_TEXT_INFO +Display an informational message. +.El +.Pp +In each case, the prompt or message to display is pointed to by the +.Va msg +member of +.Vt struct pam_message . +It can be up to +.Dv PAM_MAX_MSG_SIZE +characters long, including the terminating NUL. +.Pp +On success, the conversation function should allocate and fill a +contiguous array of +.Vt struct pam_response , +one for each message that was passed in. +A pointer to the user's response to each message (or +.Dv NULL +in the case of informational or error messages) should be stored in +the +.Va resp +member of the corresponding +.Vt struct pam_response . +Each response can be up to +.Dv PAM_MAX_RESP_SIZE +characters long, including the terminating NUL. +.Pp +The +.Va resp_retcode +member of +.Vt struct pam_response +is unused and should be set to zero. +.Pp +The conversation function should store a pointer to this array in the +location pointed to by its third argument. +It is the caller's responsibility to release both this array and the +responses themselves, using +.Xr free 3 . +It is the conversation function's responsibility to ensure that it is +legal to do so. +.Pp +The +.Va appdata_ptr +member of +.Vt struct pam_conv +is passed unmodified to the conversation function as its fourth and +final argument. +.Pp +On failure, the conversation function should release any resources it +has allocated, and return one of the predefined PAM error codes. +.Sh RETURN VALUES +The conversation function should return one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr openpam_nullconv 3 , +.Xr openpam_ttyconv 3 , +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_get_item 3 , +.Xr pam_info 3 , +.Xr pam_prompt 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The OpenPAM library and this manual page were developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, +the Security Research Division of Network Associates, Inc. under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_end.3 b/static/netbsd/man3/pam_end.3 new file mode 100644 index 00000000..b2fa2290 --- /dev/null +++ b/static/netbsd/man3/pam_end.3 @@ -0,0 +1,57 @@ +.\" $NetBSD: pam_end.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_end.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_END 3 +.Os +.Sh NAME +.Nm pam_end +.Nd terminate the PAM transaction +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_end "pam_handle_t *pamh" "int status" +.Sh DESCRIPTION +The +.Fn pam_end +function terminates a PAM transaction and destroys the +corresponding PAM context, releasing all resources allocated to it. +.Pp +The +.Fa status +argument should be set to the error code returned by the +last API call before the call to +.Fn pam_end . +.Sh RETURN VALUES +The +.Fn pam_end +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_HANDLE +Invalid PAM handle. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_end +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_error.3 b/static/netbsd/man3/pam_error.3 new file mode 100644 index 00000000..f60433a2 --- /dev/null +++ b/static/netbsd/man3/pam_error.3 @@ -0,0 +1,57 @@ +.\" $NetBSD: pam_error.3,v 1.10 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_error.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_ERROR 3 +.Os +.Sh NAME +.Nm pam_error +.Nd display an error message +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_error "const pam_handle_t *pamh" "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn pam_error +function displays an error message through the +intermediary of the given PAM context's conversation function. +.Sh RETURN VALUES +The +.Fn pam_error +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_info 3 , +.Xr pam_prompt 3 , +.Xr pam_strerror 3 , +.Xr pam_verror 3 +.Sh STANDARDS +The +.Fn pam_error +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_error +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_get_authtok.3 b/static/netbsd/man3/pam_get_authtok.3 new file mode 100644 index 00000000..d508f3fb --- /dev/null +++ b/static/netbsd/man3/pam_get_authtok.3 @@ -0,0 +1,165 @@ +.\" $NetBSD: pam_get_authtok.3,v 1.11 2025/09/03 16:06:25 christos Exp $ +.\" +.\" Generated from pam_get_authtok.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GET_AUTHTOK 3 +.Os +.Sh NAME +.Nm pam_get_authtok +.Nd retrieve authentication token +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt" +.Sh DESCRIPTION +The +.Fn pam_get_authtok +function either prompts the user for an +authentication token or retrieves a cached authentication token, +depending on circumstances. +Either way, a pointer to the authentication token is stored in the +location pointed to by the +.Fa authtok +argument, and the corresponding PAM +item is updated. +.Pp +The +.Fa item +argument must have one of the following values: +.Bl -tag -width 18n +.It Dv PAM_AUTHTOK +Returns the current authentication token, or the new token +when changing authentication tokens. +.It Dv PAM_OLDAUTHTOK +Returns the previous authentication token when changing +authentication tokens. +.El +.Pp +The +.Fa prompt +argument specifies a prompt to use if no token is cached. +If it is +.Dv NULL , +the +.Dv PAM_AUTHTOK_PROMPT +or +.Dv PAM_OLDAUTHTOK_PROMPT +item, +as appropriate, will be used. +If that item is also +.Dv NULL , +a hardcoded default prompt will be used. +Additionally, when +.Fn pam_get_authtok +is called from a service module, +the prompt may be affected by module options as described below. +The prompt is then expanded using +.Xr openpam_subst 3 +before it is passed to +the conversation function. +.Pp +If +.Fa item +is set to +.Dv PAM_AUTHTOK +and there is a non-null +.Dv PAM_OLDAUTHTOK +item, +.Fn pam_get_authtok +will ask the user to confirm the new token by +retyping it. +If there is a mismatch, +.Fn pam_get_authtok +will return +.Dv PAM_TRY_AGAIN . +.Sh MODULE OPTIONS +When called by a service module, +.Fn pam_get_authtok +will recognize the +following module options: +.Bl -tag -width 18n +.It Dv authtok_prompt +Prompt to use when +.Fa item +is set to +.Dv PAM_AUTHTOK . +This option overrides both the +.Fa prompt +argument and the +.Dv PAM_AUTHTOK_PROMPT +item. +.It Dv echo_pass +If the application's conversation function allows it, this +lets the user see what they are typing. +This should only be used for non-reusable authentication +tokens. +.It Dv oldauthtok_prompt +Prompt to use when +.Fa item +is set to +.Dv PAM_OLDAUTHTOK . +This option overrides both the +.Fa prompt +argument and the +.Dv PAM_OLDAUTHTOK_PROMPT +item. +.It Dv try_first_pass +If the requested item is non-null, return it without +prompting the user. +Typically, the service module will verify the token, and +if it does not match, clear the item before calling +.Fn pam_get_authtok +a second time. +.It Dv use_first_pass +Do not prompt the user at all; just return the cached +value, or +.Dv PAM_AUTH_ERR +if there is none. +.El +.Sh RETURN VALUES +The +.Fn pam_get_authtok +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_TRY_AGAIN +Try again. +.El +.Sh SEE ALSO +.Xr openpam_get_option 3 , +.Xr openpam_subst 3 , +.Xr pam 3 , +.Xr pam_conv 3 , +.Xr pam_get_item 3 , +.Xr pam_get_user 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +The +.Fn pam_get_authtok +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_get_authtok +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_get_data.3 b/static/netbsd/man3/pam_get_data.3 new file mode 100644 index 00000000..af96b745 --- /dev/null +++ b/static/netbsd/man3/pam_get_data.3 @@ -0,0 +1,70 @@ +.\" $NetBSD: pam_get_data.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_get_data.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GET_DATA 3 +.Os +.Sh NAME +.Nm pam_get_data +.Nd get module information +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data" +.Sh DESCRIPTION +The +.Fn pam_get_data +function looks up the opaque object associated with +the string specified by the +.Fa module_data_name +argument, in the PAM +context specified by the +.Fa pamh +argument. +A pointer to the object is stored in the location pointed to by the +.Fa data +argument. +If +.Fn pam_get_data +fails, the +.Fa data +argument is untouched. +.Pp +This function and its counterpart +.Xr pam_set_data 3 +are useful for managing +data that are meaningful only to a particular service module. +.Sh RETURN VALUES +The +.Fn pam_get_data +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_NO_MODULE_DATA +Module data not found. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_set_data 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_get_data +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_get_item.3 b/static/netbsd/man3/pam_get_item.3 new file mode 100644 index 00000000..67633ac2 --- /dev/null +++ b/static/netbsd/man3/pam_get_item.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: pam_get_item.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_get_item.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GET_ITEM 3 +.Os +.Sh NAME +.Nm pam_get_item +.Nd get PAM information +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item" +.Sh DESCRIPTION +The +.Fn pam_get_item +function stores a pointer to the item specified by +the +.Fa item_type +argument in the location pointed to by the +.Fa item +argument. +The item is retrieved from the PAM context specified by the +.Fa pamh +argument. +If +.Fn pam_get_item +fails, the +.Fa item +argument is untouched. +.Pp +The following item types are recognized: +.Bl -tag -width 18n +.It Dv PAM_SERVICE +The name of the requesting service. +.It Dv PAM_USER +The name of the user the application is trying to +authenticate. +.It Dv PAM_TTY +The name of the current terminal. +.It Dv PAM_RHOST +The name of the applicant's host. +.It Dv PAM_CONV +A +.Vt struct pam_conv +describing the current conversation +function. +.It Dv PAM_AUTHTOK +The current authentication token. +.It Dv PAM_OLDAUTHTOK +The expired authentication token. +.It Dv PAM_RUSER +The name of the applicant. +.It Dv PAM_USER_PROMPT +The prompt to use when asking the applicant for a user +name to authenticate as. +.It Dv PAM_AUTHTOK_PROMPT +The prompt to use when asking the applicant for an +authentication token. +.It Dv PAM_OLDAUTHTOK_PROMPT +The prompt to use when asking the applicant for an +expired authentication token prior to changing it. +.It Dv PAM_HOST +The name of the host the application runs on. +.It Dv PAM_SOCKADDR +The sockaddr_storage of the applicants's host. +.It Dv PAM_NUSER +The +.Do +nested +.Dc +user if this is a login on top of a previous one. +.El +.Pp +See +.Xr pam_start 3 +for a description of +.Vt struct pam_conv . +.Sh RETURN VALUES +The +.Fn pam_get_item +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_get_item +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_get_user.3 b/static/netbsd/man3/pam_get_user.3 new file mode 100644 index 00000000..19a79a61 --- /dev/null +++ b/static/netbsd/man3/pam_get_user.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: pam_get_user.3,v 1.11 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_get_user.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GET_USER 3 +.Os +.Sh NAME +.Nm pam_get_user +.Nd retrieve user name +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt" +.Sh DESCRIPTION +The +.Fn pam_get_user +function returns the name of the target user, as +specified to +.Xr pam_start 3 . +If no user was specified, nor set using +.Xr pam_set_item 3 , +.Fn pam_get_user +will prompt for a user name. +Either way, a pointer to the user name is stored in the location +pointed to by the +.Fa user +argument, and the corresponding PAM item is +updated. +.Pp +The +.Fa prompt +argument specifies a prompt to use if no user name is +cached. +If it is +.Dv NULL , +the +.Dv PAM_USER_PROMPT +item will be used. +If that item is also +.Dv NULL , +a hardcoded default prompt will be used. +Additionally, when +.Fn pam_get_user +is called from a service module, the +prompt may be affected by module options as described below. +The prompt is then expanded using +.Xr openpam_subst 3 +before it is passed to +the conversation function. +.Sh MODULE OPTIONS +When called by a service module, +.Fn pam_get_user +will recognize the +following module options: +.Bl -tag -width 18n +.It Dv user_prompt +Prompt to use when asking for the user name. +This option overrides both the +.Fa prompt +argument and the +.Dv PAM_USER_PROMPT +item. +.El +.Sh RETURN VALUES +The +.Fn pam_get_user +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr openpam_get_option 3 , +.Xr openpam_subst 3 , +.Xr pam 3 , +.Xr pam_conv 3 , +.Xr pam_get_authtok 3 , +.Xr pam_get_item 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_get_user +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_getenv.3 b/static/netbsd/man3/pam_getenv.3 new file mode 100644 index 00000000..4cdf8923 --- /dev/null +++ b/static/netbsd/man3/pam_getenv.3 @@ -0,0 +1,53 @@ +.\" $NetBSD: pam_getenv.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_getenv.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GETENV 3 +.Os +.Sh NAME +.Nm pam_getenv +.Nd retrieve the value of a PAM environment variable +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "const char *" +.Fn pam_getenv "pam_handle_t *pamh" "const char *name" +.Sh DESCRIPTION +The +.Fn pam_getenv +function returns the value of an environment variable. +Its semantics are similar to those of +.Xr getenv 3 , +but it accesses the PAM +context's environment list instead of the application's. +.Sh RETURN VALUES +The +.Fn pam_getenv +function returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr getenv 3 , +.Xr pam 3 , +.Xr pam_getenvlist 3 , +.Xr pam_putenv 3 , +.Xr pam_setenv 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_getenv +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_getenvlist.3 b/static/netbsd/man3/pam_getenvlist.3 new file mode 100644 index 00000000..7b077024 --- /dev/null +++ b/static/netbsd/man3/pam_getenvlist.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: pam_getenvlist.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_getenvlist.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_GETENVLIST 3 +.Os +.Sh NAME +.Nm pam_getenvlist +.Nd returns a list of all the PAM environment variables +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "char **" +.Fn pam_getenvlist "pam_handle_t *pamh" +.Sh DESCRIPTION +The +.Fn pam_getenvlist +function returns a copy of the given PAM context's +environment list as a pointer to an array of strings. +The last element in the array is +.Dv NULL . +The pointer is suitable for assignment to +.Va environ . +.Pp +The array and the strings it lists are allocated using +.Xr malloc 3 , +and +should be released using +.Xr free 3 +after use: +.Pp +.Bd -literal + char **envlist, **env; + + envlist = environ; + environ = pam_getenvlist(pamh); + /* do something nifty */ + for (env = environ; *env != NULL; env++) + free(*env); + free(environ); + environ = envlist; +.Ed +.Sh RETURN VALUES +The +.Fn pam_getenvlist +function returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 , +.Xr pam 3 , +.Xr pam_getenv 3 , +.Xr pam_putenv 3 , +.Xr pam_setenv 3 , +.Xr environ 7 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_getenvlist +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_info.3 b/static/netbsd/man3/pam_info.3 new file mode 100644 index 00000000..e9086f68 --- /dev/null +++ b/static/netbsd/man3/pam_info.3 @@ -0,0 +1,57 @@ +.\" $NetBSD: pam_info.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_info.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_INFO 3 +.Os +.Sh NAME +.Nm pam_info +.Nd display an information message +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_info "const pam_handle_t *pamh" "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn pam_info +function displays an informational message through the +intermediary of the given PAM context's conversation function. +.Sh RETURN VALUES +The +.Fn pam_info +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_prompt 3 , +.Xr pam_strerror 3 , +.Xr pam_vinfo 3 +.Sh STANDARDS +The +.Fn pam_info +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_info +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_open_session.3 b/static/netbsd/man3/pam_open_session.3 new file mode 100644 index 00000000..44661c45 --- /dev/null +++ b/static/netbsd/man3/pam_open_session.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: pam_open_session.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_open_session.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_OPEN_SESSION 3 +.Os +.Sh NAME +.Nm pam_open_session +.Nd open a user session +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_open_session "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_open_session +sets up a user session for a previously +authenticated user. +The session should later be torn down by a call to +.Xr pam_close_session 3 . +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.El +.Pp +If any other bits are set, +.Fn pam_open_session +will return +.Dv PAM_BAD_CONSTANT . +.Sh RETURN VALUES +The +.Fn pam_open_session +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_close_session 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_open_session +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_prompt.3 b/static/netbsd/man3/pam_prompt.3 new file mode 100644 index 00000000..d496b5cd --- /dev/null +++ b/static/netbsd/man3/pam_prompt.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: pam_prompt.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_prompt.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_PROMPT 3 +.Os +.Sh NAME +.Nm pam_prompt +.Nd call the conversation function +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_prompt "const pam_handle_t *pamh" "int style" "char **resp" "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn pam_prompt +function constructs a message from the specified format +string and arguments and passes it to the given PAM context's +conversation function. +.Pp +A pointer to the response, or +.Dv NULL +if the conversation function did +not return one, is stored in the location pointed to by the +.Fa resp +argument. +.Pp +See +.Xr pam_vprompt 3 +for further details. +.Sh RETURN VALUES +The +.Fn pam_prompt +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_info 3 , +.Xr pam_strerror 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +The +.Fn pam_prompt +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_prompt +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_putenv.3 b/static/netbsd/man3/pam_putenv.3 new file mode 100644 index 00000000..d19aff6f --- /dev/null +++ b/static/netbsd/man3/pam_putenv.3 @@ -0,0 +1,60 @@ +.\" $NetBSD: pam_putenv.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_putenv.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_PUTENV 3 +.Os +.Sh NAME +.Nm pam_putenv +.Nd set the value of an environment variable +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue" +.Sh DESCRIPTION +The +.Fn pam_putenv +function sets an environment variable. +Its semantics are similar to those of +.Xr putenv 3 , +but it modifies the PAM +context's environment list instead of the application's. +.Sh RETURN VALUES +The +.Fn pam_putenv +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_getenv 3 , +.Xr pam_getenvlist 3 , +.Xr pam_setenv 3 , +.Xr pam_strerror 3 , +.Xr putenv 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_putenv +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_set_data.3 b/static/netbsd/man3/pam_set_data.3 new file mode 100644 index 00000000..05064a26 --- /dev/null +++ b/static/netbsd/man3/pam_set_data.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: pam_set_data.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_set_data.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SET_DATA 3 +.Os +.Sh NAME +.Nm pam_set_data +.Nd set module information +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_set_data "pam_handle_t *pamh" "const char *module_data_name" "void *data" "void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)" +.Sh DESCRIPTION +The +.Fn pam_set_data +function associates a pointer to an opaque object +with an arbitrary string specified by the +.Fa module_data_name +argument, +in the PAM context specified by the +.Fa pamh +argument. +.Pp +If not +.Dv NULL , +the +.Fa cleanup +argument should point to a function +responsible for releasing the resources associated with the object. +.Pp +This function and its counterpart +.Xr pam_get_data 3 +are useful for managing +data that are meaningful only to a particular service module. +.Sh RETURN VALUES +The +.Fn pam_set_data +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr openpam_free_data 3 , +.Xr pam 3 , +.Xr pam_get_data 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_set_data +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_set_item.3 b/static/netbsd/man3/pam_set_item.3 new file mode 100644 index 00000000..35aa15ab --- /dev/null +++ b/static/netbsd/man3/pam_set_item.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: pam_set_item.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_set_item.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SET_ITEM 3 +.Os +.Sh NAME +.Nm pam_set_item +.Nd set authentication information +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item" +.Sh DESCRIPTION +The +.Fn pam_set_item +function sets the item specified by the +.Fa item_type +argument to a copy of the object pointed to by the +.Fa item +argument. +The item is stored in the PAM context specified by the +.Fa pamh +argument. +See +.Xr pam_get_item 3 +for a list of recognized item types. +.Sh RETURN VALUES +The +.Fn pam_set_item +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_get_item 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_set_item +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_setcred.3 b/static/netbsd/man3/pam_setcred.3 new file mode 100644 index 00000000..f29a8331 --- /dev/null +++ b/static/netbsd/man3/pam_setcred.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: pam_setcred.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_setcred.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SETCRED 3 +.Os +.Sh NAME +.Nm pam_setcred +.Nd modify / delete user credentials for an authentication service +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_setcred "pam_handle_t *pamh" "int flags" +.Sh DESCRIPTION +The +.Fn pam_setcred +function manages the application's credentials. +.Pp +The +.Fa flags +argument is the binary or of zero or more of the following +values: +.Bl -tag -width 18n +.It Dv PAM_SILENT +Do not emit any messages. +.It Dv PAM_ESTABLISH_CRED +Establish the credentials of the target user. +.It Dv PAM_DELETE_CRED +Revoke all established credentials. +.It Dv PAM_REINITIALIZE_CRED +Fully reinitialise credentials. +.It Dv PAM_REFRESH_CRED +Refresh credentials. +.El +.Pp +The latter four are mutually exclusive. +.Pp +If any other bits are set, +.Fn pam_setcred +will return +.Dv PAM_BAD_CONSTANT . +.Sh RETURN VALUES +The +.Fn pam_setcred +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BAD_CONSTANT +Bad constant. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_ERR +Failed to set user credentials. +.It Bq Er PAM_CRED_EXPIRED +User credentials have expired. +.It Bq Er PAM_CRED_UNAVAIL +Failed to retrieve user credentials. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_setcred +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_setenv.3 b/static/netbsd/man3/pam_setenv.3 new file mode 100644 index 00000000..8eacbb32 --- /dev/null +++ b/static/netbsd/man3/pam_setenv.3 @@ -0,0 +1,59 @@ +.\" $NetBSD: pam_setenv.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_setenv.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SETENV 3 +.Os +.Sh NAME +.Nm pam_setenv +.Nd mirrors setenv(3) +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_setenv "pam_handle_t *pamh" "const char *name" "const char *value" "int overwrite" +.Sh DESCRIPTION +The +.Fn pam_setenv +function sets an environment variable. +Its semantics are similar to those of +.Xr setenv 3 , +but it modifies the PAM +context's environment list instead of the application's. +.Sh RETURN VALUES +The +.Fn pam_setenv +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_getenv 3 , +.Xr pam_getenvlist 3 , +.Xr pam_putenv 3 , +.Xr pam_strerror 3 , +.Xr setenv 3 +.Sh STANDARDS +The +.Fn pam_setenv +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_setenv +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_acct_mgmt.3 b/static/netbsd/man3/pam_sm_acct_mgmt.3 new file mode 100644 index 00000000..a1215e37 --- /dev/null +++ b/static/netbsd/man3/pam_sm_acct_mgmt.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: pam_sm_acct_mgmt.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_acct_mgmt.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_ACCT_MGMT 3 +.Os +.Sh NAME +.Nm pam_sm_acct_mgmt +.Nd service module implementation for pam_acct_mgmt +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_acct_mgmt "pam_handle_t *pamh" "int flags" "int argc" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_acct_mgmt +function is the service module's implementation +of the +.Xr pam_acct_mgmt 3 +API function. +.Sh RETURN VALUES +The +.Fn pam_sm_acct_mgmt +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_ACCT_EXPIRED +User account has expired. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_NEW_AUTHTOK_REQD +New authentication token required. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_acct_mgmt 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_acct_mgmt +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_authenticate.3 b/static/netbsd/man3/pam_sm_authenticate.3 new file mode 100644 index 00000000..2e573375 --- /dev/null +++ b/static/netbsd/man3/pam_sm_authenticate.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: pam_sm_authenticate.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_authenticate.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_AUTHENTICATE 3 +.Os +.Sh NAME +.Nm pam_sm_authenticate +.Nd service module implementation for pam_authenticate +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_authenticate "pam_handle_t *pamh" "int flags" "int argc" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_authenticate +function is the service module's +implementation of the +.Xr pam_authenticate 3 +API function. +.Sh RETURN VALUES +The +.Fn pam_sm_authenticate +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_AUTHINFO_UNAVAIL +Authentication information is unavailable. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_INSUFFICIENT +Insufficient credentials. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_MAXTRIES +Maximum number of tries exceeded. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_authenticate 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_authenticate +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_chauthtok.3 b/static/netbsd/man3/pam_sm_chauthtok.3 new file mode 100644 index 00000000..814ff474 --- /dev/null +++ b/static/netbsd/man3/pam_sm_chauthtok.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: pam_sm_chauthtok.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_chauthtok.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_CHAUTHTOK 3 +.Os +.Sh NAME +.Nm pam_sm_chauthtok +.Nd service module implementation for pam_chauthtok +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_chauthtok "pam_handle_t *pamh" "int flags" "int argc" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_chauthtok +function is the service module's implementation +of the +.Xr pam_chauthtok 3 +API function. +.Pp +When the application calls +.Xr pam_chauthtok 3 , +the service function is +called twice, first with the +.Dv PAM_PRELIM_CHECK +flag set and then again +with the +.Dv PAM_UPDATE_AUTHTOK +flag set. +.Sh RETURN VALUES +The +.Fn pam_sm_chauthtok +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_AUTHTOK_DISABLE_AGING +Authentication token aging disabled. +.It Bq Er PAM_AUTHTOK_ERR +Authentication token failure. +.It Bq Er PAM_AUTHTOK_LOCK_BUSY +Authentication token lock busy. +.It Bq Er PAM_AUTHTOK_RECOVERY_ERR +Failed to recover old authentication token. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_TRY_AGAIN +Try again. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_chauthtok 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_chauthtok +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_close_session.3 b/static/netbsd/man3/pam_sm_close_session.3 new file mode 100644 index 00000000..f5a4fcbf --- /dev/null +++ b/static/netbsd/man3/pam_sm_close_session.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: pam_sm_close_session.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_close_session.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_CLOSE_SESSION 3 +.Os +.Sh NAME +.Nm pam_sm_close_session +.Nd service module implementation for pam_close_session +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_close_session "pam_handle_t *pamh" "int flags" "int args" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_close_session +function is the service module's +implementation of the +.Xr pam_close_session 3 +API function. +.Sh RETURN VALUES +The +.Fn pam_sm_close_session +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_close_session 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_close_session +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_open_session.3 b/static/netbsd/man3/pam_sm_open_session.3 new file mode 100644 index 00000000..7567d1fc --- /dev/null +++ b/static/netbsd/man3/pam_sm_open_session.3 @@ -0,0 +1,69 @@ +.\" $NetBSD: pam_sm_open_session.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_open_session.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_OPEN_SESSION 3 +.Os +.Sh NAME +.Nm pam_sm_open_session +.Nd service module implementation for pam_open_session +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_open_session "pam_handle_t *pamh" "int flags" "int argc" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_open_session +function is the service module's +implementation of the +.Xr pam_open_session 3 +API function. +.Sh RETURN VALUES +The +.Fn pam_sm_open_session +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_open_session 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_open_session +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_sm_setcred.3 b/static/netbsd/man3/pam_sm_setcred.3 new file mode 100644 index 00000000..d3f979e9 --- /dev/null +++ b/static/netbsd/man3/pam_sm_setcred.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: pam_sm_setcred.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_sm_setcred.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_SM_SETCRED 3 +.Os +.Sh NAME +.Nm pam_sm_setcred +.Nd service module implementation for pam_setcred +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.In security/pam_modules.h +.Ft "int" +.Fn pam_sm_setcred "pam_handle_t *pamh" "int flags" "int argc" "const char **argv" +.Sh DESCRIPTION +The +.Fn pam_sm_setcred +function is the service module's implementation of +the +.Xr pam_setcred 3 +API function. +.Sh RETURN VALUES +The +.Fn pam_sm_setcred +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_ERR +Failed to set user credentials. +.It Bq Er PAM_CRED_EXPIRED +User credentials have expired. +.It Bq Er PAM_CRED_UNAVAIL +Failed to retrieve user credentials. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_setcred 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_sm_setcred +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_start.3 b/static/netbsd/man3/pam_start.3 new file mode 100644 index 00000000..02c4c70b --- /dev/null +++ b/static/netbsd/man3/pam_start.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: pam_start.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_start.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_START 3 +.Os +.Sh NAME +.Nm pam_start +.Nd initiate a PAM transaction +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh" +.Sh DESCRIPTION +The +.Fn pam_start +function creates and initializes a PAM context. +.Pp +The +.Fa service +argument specifies the name of the policy to apply, and is +stored in the +.Dv PAM_SERVICE +item in the created context. +.Pp +The +.Fa user +argument specifies the name of the target user - the user the +created context will serve to authenticate. +It is stored in the +.Dv PAM_USER +item in the created context. +.Pp +The +.Fa pam_conv +argument points to a +.Vt struct pam_conv +describing the +conversation function to use; see +.Fa pam_conv +for details. +.Sh RETURN VALUES +The +.Fn pam_start +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BAD_ITEM +Unrecognized or restricted item. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_end 3 , +.Xr pam_get_item 3 , +.Xr pam_set_item 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_start +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_strerror.3 b/static/netbsd/man3/pam_strerror.3 new file mode 100644 index 00000000..ef9cdd70 --- /dev/null +++ b/static/netbsd/man3/pam_strerror.3 @@ -0,0 +1,58 @@ +.\" $NetBSD: pam_strerror.3,v 1.11 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_strerror.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_STRERROR 3 +.Os +.Sh NAME +.Nm pam_strerror +.Nd get PAM standard error message string +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "const char *" +.Fn pam_strerror "const pam_handle_t *pamh" "int error_number" +.Sh DESCRIPTION +The +.Fn pam_strerror +function returns a pointer to a string containing a +textual description of the error indicated by the +.Fa error_number +argument in the context of the PAM transaction described by the +.Fa pamh . +The +.Fa pamh +argument is ignored. +For compatibility with other implementations, it should be either a +valid PAM handle returned by a previous call to +.Xr pam_start 3 , +or +.Dv NULL . +.Sh RETURN VALUES +The +.Fn pam_strerror +function returns +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_start 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The +.Fn pam_strerror +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_verror.3 b/static/netbsd/man3/pam_verror.3 new file mode 100644 index 00000000..b9619ac2 --- /dev/null +++ b/static/netbsd/man3/pam_verror.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: pam_verror.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_verror.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_VERROR 3 +.Os +.Sh NAME +.Nm pam_verror +.Nd display an error message +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_verror "const pam_handle_t *pamh" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Fn pam_verror +function passes its arguments to +.Xr pam_vprompt 3 +with a +style argument of +.Dv PAM_ERROR_MSG , +and discards the response. +.Sh RETURN VALUES +The +.Fn pam_verror +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_strerror 3 , +.Xr pam_vinfo 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +The +.Fn pam_verror +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_verror +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_vinfo.3 b/static/netbsd/man3/pam_vinfo.3 new file mode 100644 index 00000000..168bf21b --- /dev/null +++ b/static/netbsd/man3/pam_vinfo.3 @@ -0,0 +1,61 @@ +.\" $NetBSD: pam_vinfo.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_vinfo.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_VINFO 3 +.Os +.Sh NAME +.Nm pam_vinfo +.Nd display an information message +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_vinfo "const pam_handle_t *pamh" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Fn pam_vinfo +function passes its arguments to +.Xr pam_vprompt 3 +with a +style argument of +.Dv PAM_TEXT_INFO , +and discards the response. +.Sh RETURN VALUES +The +.Fn pam_vinfo +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_info 3 , +.Xr pam_strerror 3 , +.Xr pam_verror 3 , +.Xr pam_vprompt 3 +.Sh STANDARDS +The +.Fn pam_vinfo +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_vinfo +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/pam_vprompt.3 b/static/netbsd/man3/pam_vprompt.3 new file mode 100644 index 00000000..61a1c0da --- /dev/null +++ b/static/netbsd/man3/pam_vprompt.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: pam_vprompt.3,v 1.10 2025/09/03 16:06:26 christos Exp $ +.\" +.\" Generated from pam_vprompt.c by gendoc.pl +.Dd May 31, 2025 +.Dt PAM_VPROMPT 3 +.Os +.Sh NAME +.Nm pam_vprompt +.Nd call the conversation function +.Sh SYNOPSIS +.In sys/types.h +.In security/pam_appl.h +.Ft "int" +.Fn pam_vprompt "const pam_handle_t *pamh" "int style" "char **resp" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Fn pam_vprompt +function constructs a string from the +.Fa fmt +and +.Fa ap +arguments using +.Xr vsnprintf 3 , +and passes it to the given PAM context's +conversation function. +.Pp +The +.Fa style +argument specifies the type of interaction requested, and +must be one of the following: +.Bl -tag -width 18n +.It Dv PAM_PROMPT_ECHO_OFF +Display the message and obtain the user's response without +displaying it. +.It Dv PAM_PROMPT_ECHO_ON +Display the message and obtain the user's response. +.It Dv PAM_ERROR_MSG +Display the message as an error message, and do not wait +for a response. +.It Dv PAM_TEXT_INFO +Display the message as an informational message, and do +not wait for a response. +.El +.Pp +A pointer to the response, or +.Dv NULL +if the conversation function did +not return one, is stored in the location pointed to by the +.Fa resp +argument. +.Pp +The message and response should not exceed +.Dv PAM_MAX_MSG_SIZE +or +.Dv PAM_MAX_RESP_SIZE , +respectively. +If they do, they may be truncated. +.Sh RETURN VALUES +The +.Fn pam_vprompt +function returns one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_info 3 , +.Xr pam_prompt 3 , +.Xr pam_strerror 3 , +.Xr pam_verror 3 , +.Xr pam_vinfo 3 , +.Xr vsnprintf 3 +.Sh STANDARDS +The +.Fn pam_vprompt +function is an OpenPAM extension. +.Sh AUTHORS +The +.Fn pam_vprompt +function and this manual page were +developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +The OpenPAM library is maintained by +.An Dag-Erling Sm\(/orgrav Aq Mt des@des.dev . diff --git a/static/netbsd/man3/panel.3 b/static/netbsd/man3/panel.3 new file mode 100644 index 00000000..b2b611d2 --- /dev/null +++ b/static/netbsd/man3/panel.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: panel.3,v 1.3 2015/10/28 10:22:40 wiz Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt PANEL 3 +.Os +.Sh NAME +.Nm panel +.Nd z-order for curses windows +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.Sh DESCRIPTION +Overlapping curses windows have no notion of z-order, +what you see on the screen depends on the order of updates. +The +.Nm +library is an extension built on top of +.Xr curses 3 +that adds z-order to curses windows. +.Pp +Each panel has an associated curses window. +All currently visible panels form a +.Dq deck . +Panels have z-order only relative to other panels in the deck and to +.\".Xr stdscr 3 . +stdscr. +The latter doesn't have a panel of its own but implicitly lies below +all other panels in the deck. +If you mix plain curses windows and panels, the visual results are +undefined since the panel library is not aware of windows that are not +associated with panels. +.Bl -column ".Xr set_panel_userptr 3" +.It Sy "Function" Ta Sy "Summary" +.It Xr bottom_panel 3 Ta move the panel to the bottom of the deck +.It Xr del_panel 3 Ta delete the panel +.It Xr hide_panel 3 Ta hide the panel, removing it from deck +.It Xr move_panel 3 Ta move the panel to a new position on screen +.It Xr new_panel 3 Ta create new panel +.It Xr panel_above 3 Ta a panel above the given panel +.It Xr panel_below 3 Ta a panel below the given panel +.It Xr panel_hidden 3 Ta check if the panel is hidden +.It Xr panel_userptr 3 Ta user data associated with the panel +.It Xr panel_window 3 Ta curses window associated with the panel +.It Xr replace_panel 3 Ta associate a different window with the panel +.It Xr set_panel_userptr 3 Ta associate arbitrary user data with the panel +.It Xr show_panel 3 Ta show hidden panel at the top of the deck +.It Xr top_panel 3 Ta move the panel to the top of the deck +.It Xr update_panels 3 Ta update terminal display +.El +.Sh SEE ALSO +.Xr curses 3 diff --git a/static/netbsd/man3/panel_above.3 b/static/netbsd/man3/panel_above.3 new file mode 100644 index 00000000..883dee2a --- /dev/null +++ b/static/netbsd/man3/panel_above.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: panel_above.3,v 1.8 2015/11/01 14:47:54 wiz Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt PANEL_ABOVE 3 +.Os +.Sh NAME +.Nm top_panel , +.Nm bottom_panel , +.Nm panel_above , +.Nm panel_below +.Nd z-order of panels +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft int +.Fn top_panel "PANEL *p" +.\" +.Ft int +.Fn bottom_panel "PANEL *p" +.\" +.Ft PANEL * +.Fn panel_above "PANEL *p" +.\" +.Ft PANEL * +.Fn panel_below "PANEL *p" +.\" +.Sh DESCRIPTION +Newly created panels are placed at the top of the deck. +The z-order of a visible panel can be changed with the functions +.Fn top_panel +and +.Fn bottom_panel +that move it to the top and bottom of the deck respectively. +.Pp +For a visible panel its neighbors in the deck can be obtained with +.Fn panel_above +and +.Fn panel_below . +The bottom and top panels can be obtained by passing a +.Dv NULL +argument to +.Fn panel_above +and +.Fn panel_below , +respectively. +.Sh IMPLEMENTATION NOTES +The +.Fn top_panel +function will return an error if the panel is currently hidden. +Use +.Xr show_panel 3 +to make a hidden panel visible again and put it at the top of the deck. +This is the behaviour specified by the original +.At V +panel library. +.Pp +In the ncurses implementation of the panel library +.Fn show_panel +and +.Fn top_panel +are identical and handle both visible and hidden panels. +This may be a source of bugs in programs tested only against ncurses. +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ".Dv ERR" -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr panel 3 diff --git a/static/netbsd/man3/panel_hidden.3 b/static/netbsd/man3/panel_hidden.3 new file mode 100644 index 00000000..8d4aef6b --- /dev/null +++ b/static/netbsd/man3/panel_hidden.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: panel_hidden.3,v 1.3 2015/10/28 10:22:40 wiz Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt PANEL_HIDDEN 3 +.Os +.Sh NAME +.Nm hide_panel , +.Nm show_panel , +.Nm panel_hidden +.Nd visibility of panels +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft int +.Fn hide_panel "PANEL *p" +.\" +.Ft int +.Fn show_panel "PANEL *p" +.\" +.Ft int +.Fn panel_hidden "PANEL *p" +.\" +.Sh DESCRIPTION +Panels are initially created visible. +The function +.Fn hide_panel +can be used to hide a panel. +The panel is removed from the deck. +.Pp +A panel can be made visible again with a call to +.Fn show_panel . +The panel is returned to the top of the deck. +.Pp +The current visibility status of a panel can be queried with +.Fn panel_hidden . +.Sh IMPLEMENTATION NOTES +The +.Fn show_panel +function will return an error if the panel is already visible. +Use +.Xr top_panel 3 +to change z-order of an already visible panel. +This is the behaviour specified by the original +.At V +panel library. +.Pp +In the ncurses implementation of the panel library +.Fn show_panel +and +.Fn top_panel +are identical and handle both visible and hidden panels. +This may be a source of bugs in programs tested only against ncurses. +.Sh RETURN VALUES +The +.Fn panel_hidden +function returns +.Dv TRUE +or +.Dv FALSE . +It will return +.Dv ERR +if passed a null pointer. +.Pp +Other functions will return one of the following values: +.Pp +.Bl -tag -width ".Dv ERR" -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr panel 3 diff --git a/static/netbsd/man3/panel_userptr.3 b/static/netbsd/man3/panel_userptr.3 new file mode 100644 index 00000000..7af42e89 --- /dev/null +++ b/static/netbsd/man3/panel_userptr.3 @@ -0,0 +1,65 @@ +.\" $NetBSD: panel_userptr.3,v 1.2 2015/10/28 02:23:50 uwe Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt PANEL_USERPTR 3 +.Os +.Sh NAME +.Nm set_panel_userptr , +.Nm panel_userptr +.Nd user data associated with panels +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft int +.Fn set_panel_userptr "PANEL *p" "char *data" +.\" +.Ft char * +.Fn panel_userptr "PANEL *p" +.\" +.Sh DESCRIPTION +The function +.Fn set_panel_userptr +can be used to associate arbitrary user data with a panel. +.Pp +The data associated with a panel can be obtained with +.Fn panel_userptr . +.Sh RETURN VALUES +Functions returning pointers will return +.Dv NULL +if an error is detected. +The functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ".Dv ERR" -compact +.It Dv OK +The function completed successfully. +.It Dv ERR +An error occurred in the function. +.El +.Sh SEE ALSO +.Xr panel 3 diff --git a/static/netbsd/man3/parse_time.3 b/static/netbsd/man3/parse_time.3 new file mode 100644 index 00000000..70ae0012 --- /dev/null +++ b/static/netbsd/man3/parse_time.3 @@ -0,0 +1,175 @@ +.\" $NetBSD: parse_time.3,v 1.2 2017/01/28 21:31:50 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" Id: parse_time.3,v 1.3 2013/06/17 18:57:45 robert Exp +.\" +.Dd November 17, 2013 +.Dt PARSE_TIME 3 +.Os +.Sh NAME +.Nm parse_time , +.Nm print_time_table , +.Nm unparse_time , +.Nm unparse_time_approx , +.Nd parse and unparse time intervals +.Sh LIBRARY +The roken library (libroken, -lroken) +.Sh SYNOPSIS +.Fd #include <parse_time.h> +.Ft int +.Fn parse_time "const char *timespec" "const char *def_unit" +.Ft void +.Fn print_time_table "FILE *f" +.Ft size_t +.Fn unparse_time "int seconds" "char *buf" "size_t len" +.Ft size_t +.Fn unparse_time_approx "int seconds" "char *buf" "size_t len" +.Sh DESCRIPTION +The +.Fn parse_time +function converts the period of time specified +into a number of seconds. +The +.Fa timespec +can be any number of +.Aq number unit +pairs separated by comma and whitespace. The number can be +negative. Numbers without explicit units are taken as being +.Fa def_unit . +.Pp +The +.Fn unparse_time +and +.Fn unparse_time_approx +do the opposite of +.Fn parse_time , +that is they take a number of seconds and express that as human +readable strings. +.Fa unparse_time +produces an exact time, while +.Fa unparse_time_approx +restricts the result to include only one unit. +.Pp +.Fn print_time_table +prints a descriptive list of available units on the passed file +descriptor. +.Pp +The possible units include: +.Bl -tag -width "month" -compact -offset indent +.It Li second , s +.It Li minute , m +.It Li hour , h +.It day +.It week +seven days +.It month +30 days +.It year +365 days +.El +.Pp +Units names can be arbitrarily abbreviated (as long as they are +unique). +.Sh RETURN VALUES +.Fn parse_time +returns the number of seconds that represents the expression in +.Fa timespec +or -1 on error. +.Fn unparse_time +and +.Fn unparse_time_approx +return the number of characters written to +.Fa buf . +if the return value is greater than or equal to the +.Fa len +argument, the string was too short and some of the printed characters +were discarded. +.Sh EXAMPLES +.Bd -literal +#include <stdio.h> +#include <parse_time.h> + +int +main(int argc, char **argv) +{ + int i; + int result; + char buf[128]; + print_time_table(stdout); + for (i = 1; i < argc; i++) { + result = parse_time(argv[i], "second"); + if(result == -1) { + fprintf(stderr, "%s: parse error\\n", argv[i]); + continue; + } + printf("--\\n"); + printf("parse_time = %d\\n", result); + unparse_time(result, buf, sizeof(buf)); + printf("unparse_time = %s\\n", buf); + unparse_time_approx(result, buf, sizeof(buf)); + printf("unparse_time_approx = %s\\n", buf); + } + return 0; +} +.Ed +.Bd -literal +$ ./a.out "1 minute 30 seconds" "90 s" "1 y -1 s" +1 year = 365 days +1 month = 30 days +1 week = 7 days +1 day = 24 hours +1 hour = 60 minutes +1 minute = 60 seconds +1 second +-- +parse_time = 90 +unparse_time = 1 minute 30 seconds +unparse_time_approx = 1 minute +-- +parse_time = 90 +unparse_time = 1 minute 30 seconds +unparse_time_approx = 1 minute +-- +parse_time = 31535999 +unparse_time = 12 months 4 days 23 hours 59 minutes 59 seconds +unparse_time_approx = 12 months +.Ed +.Sh BUGS +Since +.Fn parse_time +returns -1 on error there is no way to parse "minus one second". +Currently "s" at the end of units is ignored. This is a hack for +English plural forms. If these functions are ever localised, this +scheme will have to change. +.\".Sh SEE ALSO +.\".Xr parse_bytes 3 +.\".Xr parse_units 3 diff --git a/static/netbsd/man3/parsedate.3 b/static/netbsd/man3/parsedate.3 new file mode 100644 index 00000000..da3817ef --- /dev/null +++ b/static/netbsd/man3/parsedate.3 @@ -0,0 +1,513 @@ +.\" $NetBSD: parsedate.3,v 1.27 2024/05/02 18:34:01 rillig Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 16, 2021 +.Dt PARSEDATE 3 +.Os +.Sh NAME +.Nm parsedate +.Nd date parsing function +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft time_t +.Fn parsedate "const char *datestr" "const time_t *time" "const int *tzoff" +.Sh DESCRIPTION +The +.Fn parsedate +function parses a date and time from +.Ar datestr +described in English relative to an optional +.Ar time +point, +and an optional timezone offset (in minutes behind/west of UTC) +specified in +.Ar tzoff . +If +.Ar time +is +.Dv NULL +then the current time is used. +If +.Ar tzoff +is +.Dv NULL , +then the current time zone is used. +.Pp +The +.Ar datestr +is a sequence of white-space separated items. +The white-space is optional if the concatenated items are not ambiguous. +The string contains data which can specify a base time (used in +conjunction with the +.Ar time +parameter, totally replacing that parameter's value if sufficient data +appears in +.Ar datestr +to do so), and data specifying an offset from the base time. +Both of those are optional. +If no data specifies the base time, then +.Nm +simply uses the value given by +.Ar \&*time +.Pq "or now" . +If there is no offset data then no offset is applied. +An empty +.Ar datestr , +or a +.Ar datestr +containing nothing but whitespace, +is equivalent to midnight at the start of the day specified by +.Ar \&*time +.Pq "or today" . +.Pp +The following words have the indicated numeric meanings: +.Dv last = +\-1, +.Dv this = +0, +.Dv first , next , +or +.Dv one = +1 +.Pq but see the BUGS section below , +.Dv second +is unused so that it is not confused with +.Dq seconds , +.Dv two = +2, +.Dv third +or +.Dv three = +3, +.Dv fourth +or +.Dv four = +4, +.Dv fifth +or +.Dv five = +5, +.Dv sixth +or +.Dv six = +6, +.Dv seventh +or +.Dv seven = +7, +.Dv eighth +or +.Dv eight = +8, +.Dv ninth +or +.Dv nine = +9, +.Dv tenth +or +.Dv ten = +10, +.Dv eleventh +or +.Dv eleven = +11, +.Dv twelfth +or +.Dv twelve = +12. +.Pp +The following words are recognized in English only: +.Dv AM , +.Dv PM , +.Dv a.m. , +.Dv p.m. , +.Dv midnight , +.Dv mn , +.Dv noon . +.Pp +The months: +.Dv january , +.Dv february , +.Dv march , +.Dv april , +.Dv may , +.Dv june , +.Dv july , +.Dv august , +.Dv september , +.Dv october , +.Dv november , +.Dv december , +and common abbreviations for them. +When a month name (or its ordinal number) is given, +the number of some particular day of that month is required to accompany it. +This is generally true of any data that specifies a period +with a duration longer than a day, so simply specifying a year, +or a month, is invalid, as also is specifying a year and a month. +.Pp +The days of the week: +.Dv sunday , +.Dv monday , +.Dv tuesday , +.Dv wednesday , +.Dv thursday , +.Dv friday , +.Dv saturday , +and common abbreviations for them. +Weekday names are typically ignored if any other data +is given to specify the date, even if the name given +is not the day on which the specified date occurred. +.Pp +Time units: +.Dv year , +.Dv month , +.Dv fortnight , +.Dv week , +.Dv day , +.Dv hour , +.Dv minute , +.Dv min , +.Dv second , +.Dv sec , +.Dv tomorrow , +.Dv yesterday . +.Pp +Timezone names: +.Dv gmt (+0000) , +.Dv ut (+0000) , +.Dv utc (+0000) , +.Dv wet (+0000) , +.Dv bst (+0100) , +.Dv wat (-0100) , +.Dv at (-0200) , +.Dv nft (-0330) , +.Dv nst (-0330) , +.Dv ndt (-0230) , +.Dv ast (-0400) , +.Dv adt (-0300) , +.Dv est (-0500) , +.Dv edt (-0400) , +.Dv cst (-0600) , +.Dv cdt (-0500) , +.Dv mst (-0700) , +.Dv mdt (-0600) , +.Dv pst (-0800) , +.Dv pdt (-0700) , +.Dv yst (-0900) , +.Dv ydt (-0800) , +.Dv hst (-1000) , +.Dv hdt (-0900) , +.Dv cat (-1000) , +.Dv ahst (-1000) , +.Dv nt (-1100) , +.Dv idlw (-1200) , +.Dv cet (+0100) , +.Dv met (+0100) , +.Dv mewt (+0100) , +.Dv mest (+0200) , +.Dv swt (+0100) , +.Dv sst (+0200) , +.Dv fwt (+0100) , +.Dv fst (+0200) , +.Dv eet (+0200) , +.Dv bt (+0300) , +.Dv it (+0330) , +.\".Dv zp4 (+0400) , +.\".Dv zp5 (+0500) , +.Dv ist (+0530) , +.\".Dv zp6 (+0600) , +.Dv ict (+0700) , +.Dv wast (+0800) , +.Dv wadt (+0900) , +.Dv awst (+0800) , +.Dv awdt (+0900) , +.Dv cct (+0800) , +.Dv sgt (+0800) , +.Dv hkt (+0800) , +.Dv jst (+0900) , +.Dv cast (+0930) , +.Dv cadt (+1030) , +.Dv acst (+0930) , +.Dv acdt (+1030) , +.Dv east (+1000) , +.Dv eadt (+1100) , +.Dv aest (+1000) , +.Dv aedt (+1100) , +.Dv gst (+1000) , +.Dv nzt (+1200) , +.Dv nzst (+1200) , +.Dv nzdt (+1300) , +.Dv idle (+1200) . +.Pp +The timezone names simply specify an offset from +Coordinated Universal Time (UTC) +and do not imply validating the time/date to be reasonable in any zone +that happens to use the abbreviation specified. +.Pp +A variety of unambiguous dates are recognized: +.Bl -tag -compact -width "20 Jun 1994" +.It 9/10/69 +For years between 69-99 we assume 1900+ and for years between 0-68 +we assume 2000+. +.It 2006-11-17 +An ISO-8601 date. +Note that when using the ISO-8601 format date and time with the +.Sq T +designator to separate date and time-of-day, +this must appear at the start of the input string, +with no preceding whitespace. +Other modifiers may optionally follow. +.It 67-09-10 +The year in an ISO-8601 date is always taken literally, +so this is the year 67, not 2067. +.It 10/1/2000 +October 1, 2000; the common, but bizarre, US format. +.It 20 Jun 1994 +.It 23jun2001 +.It 1-sep-06 +Other common abbreviations. +.It 1/11 +The year can be omitted. +A missing year is taken from the +.Ar \&*time +value, or +.Dq now +if +.Ar time +is NULL. +Again, this is the US month/day format (the 11th of January). +.El +.Pp +Standard e-mail (RFC822, RFC2822, etc) +formats and the output from +.Xr date 1 , +and +.Xr asctime 3 +are all supported as input, +as is cvs date format (where years < 100 are treated as +20th century). +.Pp +Times can also be specified in common forms: +.Bl -tag -compact -width 12:11:01.000012 +.It 10:01 +.It 10:12pm +.It 12:11:01.000012 +.It 12:21-0500 +.El +Fractions of seconds (after a decimal point, or comma) are parsed, but ignored. +If no time is given, midnight on the specified date is assumed. +If a time is given without a date, that time on the day +specified by +.Ar \&*time +.Pq or now +is used. +Missing minutes, or seconds, are taken to be zero. +.Pp +A variety of forms for relative items to specify +an offset from the base time are also supported: +.Bl -tag -compact -width "this thursday" +.It -1 month +.It last friday +.It one week ago +.It this thursday +.It next sunday +.It +2 years +.El +.Pp +Note that, as a special case for +.Dv midnight +with the name of a day only, +.Dq "midnight tuesday" +implies 00:00 at the beginning of Tuesday, +.Pq "the midnight before Tuesday" +whereas +.Dq "Sat mn" +implies 00:00 at the end of Saturday +.Pq "midnight after Saturday" +.Pq "i.e. early Sunday morning" . +.Pp +Seconds since epoch, UTC, (also known as UNIX time) are also supported +to specify the base time: +.Bl -tag -compact -width "E.g.:\ @735275209\ \ \ \ " +.It "E.g.: @735275209" +to specify: Tue Apr 20 03:06:49 UTC 1993 +.El +provided that the value given is within the range +that can be represented as a +.Va "struct tm" . +Negative values +(times before the epoch) +are permitted, but no other significant data as part of +the base time \(en the value given specifies year, month, +day, hour, minute, and second, there is no more. +An offset from this base time may still be included. +Thus +.Dq "@735275209 +2 months 5 hours 15 minutes" +produces a time_t which represents +.Dq "Sun Jun 20 08:21:49 UTC 1993" . +.Pp +Text in +.Ar datestr +enclosed in parentheses +.Ql \&( +and +.Ql \&) +is treated as a comment, and ignored. +Parentheses nest (the comment ends when there have +been the same number of closing parentheses as there +were opening parentheses.) +There is no escape character in comments, +.Ql \&) +always ends +(or decreases the nesting level of) +the comment. +.Sh RETURN VALUES +.Fn parsedate +returns the number of seconds passed since, +or before (if negative,) +the Epoch, or +.Dv \-1 +if the date could not be parsed properly. +A non-error result of +.Dv \-1 +can be distinguished from an error by setting +.Va errno +to +.Dv 0 +before calling +.Fn parsedate , +and checking the value of +.Va errno +afterwards. +.Sh ENVIRONMENT +If the +.Ar tzoff +parameter is given as +.Dv NULL , +then: +.Bl -tag -width iTZ +.It Ev TZ +The timezone to which the input is relative, +when no zone information is otherwise specified in the +.Ar datestr +input. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr touch 1 , +.Xr errno 2 , +.Xr ctime 3 , +.\" WTF ???? eeprom(8)!! Why? Just because it calls this function? Weird! +.Xr eeprom 8 +.Sh HISTORY +The parser used in +.Fn parsedate +was originally written by Steven M. Bellovin while at the University +of North Carolina at Chapel Hill. +It was later tweaked by a couple of people on Usenet. +Completely overhauled by Rich $alz and Jim Berets in August, 1990. +Further mangled during its residence with +.Nx . +.Pp +The +.Fn parsedate +function first appeared in +.Nx 4.0 . +.Sh BUGS +.Bl -tag -compact -width 1 +.It 1 +The +.Fn parsedate +function is not re-entrant or thread-safe. +.It 2 +The +.Fn parsedate +function assumes years less than 0 mean \(mi +.Fa year , +and in non ISO formats, +that years less than 69 mean 2000 + +.Fa year , +otherwise +years less than 100 mean 1900 + +.Fa year . +That is except in the CVS format, where years less than 100 +mean 1900 + +.Fa year . +.It 3 +The +.Fn parsedate +function accepts +.Dq "12 am" +where +.Dq "12 midnight" +is correct, and similarly +.Dq "12 pm" +for +.Dq "12 noon" . +The correct forms are also accepted. +.It 4 +There are various weird cases that are hard to explain, +but are nevertheless considered correct. +.It 5 +It is very hard to specify years BC, +and in any case, +conversions of times before the +commencement of the modern Gregorian calendar +(when that occurred depends upon location, +but late 16th century is a rough guide) +are suspicious at best, +and depending upon context, +often just plain wrong. +.It 6 +Despite what is stated above, +.Dq next +is actually 2. +The input +.Dq "next January" , +instead of producing a timestamp for January of the +following year, produces one for January 2nd, of the +current year. +Use caution with +.Dq next +it rarely does what humans expect. +For example, on a Sunday +.Dq "next sunday" +means the following Sunday (7 days hence) +whereas +.Dq "next monday" +means the monday that follows that (8 days hence) +rather than +.Dq tomorrow +or just +.Dq Mon +.Pq without the Dq next +which is the nearest subsequent Monday. +.El diff --git a/static/netbsd/man3/pause.3 b/static/netbsd/man3/pause.3 new file mode 100644 index 00000000..413ffbb9 --- /dev/null +++ b/static/netbsd/man3/pause.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: pause.3,v 1.15 2003/08/07 16:42:55 agc Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)pause.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt PAUSE 3 +.Os +.Sh NAME +.Nm pause +.Nd stop until signal +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn pause void +.Sh DESCRIPTION +.Bf -symbolic +Pause is made obsolete by +.Xr sigsuspend 2 . +.Ef +.Pp +The +.Fn pause +function +forces a process to pause until +a signal is received from either the +.Xr kill 2 +function +or an interval timer. +(See +.Xr setitimer 2 . ) +Upon termination of a signal handler started during a +.Fn pause , +the +.Fn pause +call will return. +.Sh RETURN VALUES +Always returns \-1. +.Sh ERRORS +The +.Fn pause +function +always returns: +.Bl -tag -width Er +.It Bq Er EINTR +The call was interrupted. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr setitimer 2 , +.Xr sigsuspend 2 +.Sh STANDARDS +The +.Fn pause +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +A +.Fn pause +syscall +appeared in +.At v6 . diff --git a/static/netbsd/man3/pci.3 b/static/netbsd/man3/pci.3 new file mode 100644 index 00000000..571a8541 --- /dev/null +++ b/static/netbsd/man3/pci.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: pci.3,v 1.14 2017/10/22 15:28:48 abhinav Exp $ +.\" +.\" Copyright 2001 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 23, 2016 +.Dt PCI 3 +.Os +.Sh NAME +.Nm pci , +.Nm pcibus_conf_read , +.Nm pcibus_conf_write , +.Nm pcidev_conf_read , +.Nm pcidev_conf_write , +.Nm pci_findvendor , +.Nm pci_devinfo , +.Nm pci_conf_print , +.Nm pci_drvname , +.Nm pci_drvnameonbus +.Nd library interface for PCI bus access +.Sh LIBRARY +.Lb libpci +.Sh SYNOPSIS +.In pci.h +.Ft int +.Fn pcibus_conf_read "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" \ +"unsigned int reg" "pcireg_t *valp" +.Ft int +.Fn pcibus_conf_write "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" \ +"unsigned int reg" "pcireg_t val" +.Ft int +.Fn pcidev_conf_read "int devfd" "unsigned int reg" "pcireg_t *valp" +.Ft int +.Fn pcidev_conf_write "int devfd" "unsigned int reg" "pcireg_t val" +.Ft char * +.Fn pci_findvendor "pcireg_t id_reg" +.Ft void +.Fn pci_devinfo "pcireg_t id_reg" "pcireg_t class_reg" "int showclass" "char *devinfo" "size_t len" +.Ft void +.Fn pci_conf_print "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" +.Ft int +.Fn pci_drvname "int pcifd" "unsigned int dev" "unsigned int func" "char *drvname" "size_t len" +.Ft int +.Fn pci_drvnameonbus "int pcifd" "u_int bus" "u_int dev" "u_int func" "char *drvname" "size_t len" +.Sh DESCRIPTION +The +.Nm +library provides support for accessing the PCI bus by user programs. +.Pp +These functions are available in the +.Nm libpci +library. +Programs should be linked with +.Fl lpci . +.Sh CONFIGURATION SPACE FUNCTIONS +The following functions are used to access PCI configuration space: +.Bl -tag -width 4n +.It Fn pcibus_conf_read +Access the PCI configuration register +.Fa reg +on the device located at +.Fa bus , +.Fa dev , +.Fa func , +and place the result in +.Fa *valp . +.Fa pcifd +must be an open file descriptor to a PCI bus within the target PCI domain. +.It Fn pcibus_conf_write +Write the value specified by +.Fa val +into the PCI configuration register +.Fa reg +on the device located at +.Fa bus , +.Fa dev , +.Fa func . +.Fa pcifd +must be an open file descriptor to a PCI bus within the target PCI domain. +.It Fn pcidev_conf_read +Access the PCI configuration register +.Fa reg +on the device associated with the open file descriptor +.Fa devfd +and place the result in +.Fa *valp . +.It Fn pcidev_conf_write +Write the value specified by +.Fa val +into the PCI configuration register +.Fa reg +on the device associated with the open file descriptor +.Fa devfd . +.El +.Sh MISCELLANEOUS FUNCTIONS +The following miscellaneous functions are available: +.Bl -tag -width 4n +.It Fn pci_findvendor +Return an ASCII description of the PCI vendor in the +PCI ID register +.Fa id_reg . +.It Fn pci_devinfo +Return an ASCII description of the PCI vendor, PCI product, +and PCI class specified by the PCI ID register +.Fa id_reg +and PCI class ID register +.Fa class_reg . +The description is placed into the buffer pointed to by +.Fa devinfo ; +the size of that buffer is specified in +.Fa len . +If +.Fa showclass +is not 0, the class, subclass and interface are added into the buffer. +.It Fn pci_conf_print +Print the PCI configuration information for the device located +at +.Fa bus , +.Fa dev , +.Fa func . +.Fa pcifd +must be an open file descriptor to a PCI bus within the target PCI domain. +.It Fn pci_drvname +For the PCI bus opened on +.Fa pcifd , +return the driver name for +.Fa dev +and +.Fa func +into +.Fa drvname +using +.Fa len +as the buffer length. +.It Fn pci_drvnameonbus +Just like +.Fn pci_drvname +but also allows looking up via PCI bus number. +.El +.Sh RETURN VALUES +The +.Fn pcibus_conf_read , +.Fn pcibus_conf_write , +.Fn pcidev_conf_read , +.Fn pcidev_conf_write , +.Fn pci_devinfo , +and +.Fn pci_drvname +functions return 0 on success and \-1 on failure. +.Pp +The +.Fn pci_findvendor +function returns +.Dv NULL +if the PCI vendor description cannot be found. +.Sh SEE ALSO +.Xr pci 4 +.Sh HISTORY +The +.Fn pcibus_conf_read , +.Fn pcibus_conf_write , +.Fn pcidev_conf_read , +.Fn pcidev_conf_write , +.Fn pci_findvendor , +.Fn pci_devinfo , +and +.Fn pci_conf_print +functions first appeared in +.Nx 1.6 . +The +.Fn pci_drvname +function first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/pidfile.3 b/static/netbsd/man3/pidfile.3 new file mode 100644 index 00000000..d2dfd442 --- /dev/null +++ b/static/netbsd/man3/pidfile.3 @@ -0,0 +1,173 @@ +.\" $NetBSD: pidfile.3,v 1.16 2017/10/22 16:55:32 abhinav Exp $ +.\" +.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe and Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 10, 2016 +.Dt PIDFILE 3 +.Os +.Sh NAME +.Nm pidfile , +.Nm pidfile_lock , +.Nm pidfile_read , +.Nm pidfile_clean +.Nd write a daemon pid file +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn pidfile "const char *path" +.Ft pid_t +.Fn pidfile_lock "const char *path" +.Ft pid_t +.Fn pidfile_read "const char *path" +.Ft int +.Fn pidfile_clean "void" +.Sh DESCRIPTION +.Fn pidfile +and +.Fn pidfile_lock +create and lock a file containing the process ID of the calling program. +The pid file can be used as a quick reference if +the process needs to be sent a signal. +The pid file is truncated and removed automatically when the program exits, +unless the program receives a fatal signal. +.Pp +If +.Ar path +is +.Dv NULL +or a plain basename (a name containing no directory components), the pid file +is created in the +.Pa /var/run +directory. +The file name has the form +.Pa /var/run/basename.pid . +The basename part is either the value of +.Ar path +if it was not +.Dv NULL , +or the program name as returned by +.Xr getprogname 3 +otherwise. +.Pp +If +.Ar path +is an absolute or relative path (i.e. it contains the +.Sq / +character), +the pid file is created in the provided location. +.Pp +If called with a new +.Ar path , +.Fn pidfile +and +.Fn pidfile_lock +will remove the old pid file. +.Pp +The pid file is truncated, so these functions can be called multiple times and +allow a child process to take over the lock. +.Pp +.Fn pidfile_read +will read the last pid file created, or specified by +.Ar path , +and return the process ID it contains. +.Pp +.Fn pidfile_clean +will +.Xr ftruncate 2 , +.Xr close 2 , +and +.Xr unlink 2 +the last opening pid file if, and only if, the current process wrote it. +This function should be called if the program needs to call +.Xr _exit 2 +(such as from a signal handler) and needs to clean up the pid file. +.Sh RETURN VALUES +.Fn pidfile +and +.Fn pidfile_clean +returns 0 on success and \-1 on failure. +.Pp +.Fn pidfile_lock +returns 0 on success. +Otherwise, the process ID who owns the lock is returned and if that +cannot be derived then \-1 is returned. +.Pp +.Fn pidfile_read +returns the process ID if known, otherwise \-1. +.Sh ERRORS +The +.Fn pidfile +and +.Fn pidfile_lock +functions will fail if: +.Bl -tag -width Er +.It Bq Er EEXIST +Some process already holds the lock on the given pid file, meaning that a +daemon is already running. +.It Bq Er ENAMETOOLONG +Specified pidfile's name is too long. +.El +.Sh SEE ALSO +.Xr flock 2 , +.Xr atexit 3 +.Sh HISTORY +The +.Fn pidfile +function call appeared in +.Nx 1.5 . +Support for creating pid files in any arbitrary path was added in +.Nx 6.0 . +.Pp +The +.Fn pidfile_lock , +.Fn pidfile_read , +and +.Fn pidfile_clean +function calls appeared in +.Nx 8 . +.Sh CAVEATS +.Fn pidfile +and +.Fn pidfile_lock +use +.Xr atexit 3 +to ensure the pid file is cleaned at program exit. +However, programs that use the +.Xr _exit 2 +function (for example, in signal handlers) +will not trigger this behaviour and should call +.Fn pidfile_clean . +Like-wise, if the program creates a pid file before +.Xr fork 2 Ns ing +a child to take over, it should use the +.Xr _exit 2 +function instead of returning or using the +.Xr exit 3 +function to ensure the pid file is not cleaned. diff --git a/static/netbsd/man3/pidlock.3 b/static/netbsd/man3/pidlock.3 new file mode 100644 index 00000000..90be7795 --- /dev/null +++ b/static/netbsd/man3/pidlock.3 @@ -0,0 +1,184 @@ +.\" $NetBSD: pidlock.3,v 1.13 2017/10/23 01:05:10 wiz Exp $ +.\" +.\" Copyright 1996, 1997 by Curt Sampson <cjs@NetBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 19, 2006 +.Dt PIDLOCK 3 +.Os +.Sh NAME +.Nm pidlock , +.Nm ttylock , +.Nm ttyunlock +.Nd locks based on files containing PIDs +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn pidlock "const char *lockfile" "int flags" "pid_t *locker" "const char *info" +.Ft int +.Fn ttylock "const char *tty" "int flags" "pid_t *locker" +.Ft int +.Fn ttyunlock "const char *tty" +.Sh DESCRIPTION +The +.Fn pidlock +.Fn ttylock , +and +.Fn ttyunlock +functions attempt to create a lockfile for an arbitrary resource that +only one program may hold at a time. +(In the case of +.Fn ttylock , +this is access to a tty device.) +If the +function succeeds in creating the lockfile, it will succeed for +no other program calling it with the same lockfile until the original +calling program has removed the lockfile or exited. +The +.Fn ttyunlock +function will remove the lockfile created by +.Fn ttylock . +.Pp +These functions use the method of creating a lockfile traditionally +used by UUCP software. +This is described as follows in the documentation for Taylor UUCP: +.Bd -filled -offset indent +The lock file normally contains the process ID of the locking process. +This makes it easy to determine whether a lock is still valid. +The algorithm is to create a temporary file and then link +it to the name that must be locked. +If the link fails because a file with that name already exists, +the existing file is read to get the process ID. +If the process still exists, the lock attempt fails. +Otherwise the lock file is deleted and the locking algorithm +is retried. +.Ed +.Pp +The PID is stored in ASCII format, with leading spaces to pad it +out to ten characters, and a terminating newline. +This implementation has been extended to put the hostname +on the second line of the file, terminated with a newline, and +optionally an arbitrary comment on the third line of the file, also +terminated with a newline. +If a comment is given, but +.Dv PIDLOCK_NONBLOCK +is not, a blank line will be written as the second line of the file. +.Pp +The +.Fn pidlock +function will attempt to create the file +.Fa lockfile +and put the current process's pid in it. +The +.Fn ttylock +function will do the same, but should be passed only the base name +(with no leading directory prefix) of the +.Fa tty +to be locked; it will test that the tty exists in +.Pa /dev +and is a character device, and then create +the file in the +.Pa /var/spool/lock +directory and prefix the filename with +.Pa LCK.. . +Use the +.Fn ttyunlock +function to remove this lock. +.Pp +The following flags may be passed in +.Pa flags : +.Bl -tag -width Dv -offset indent +.It Dv PIDLOCK_NONBLOCK +The function should return immediately when a lock is held by another +active process. +Otherwise the function will wait (forever, if necessary) +for the lock to be freed. +.It Dv PIDLOCK_USEHOSTNAME +The hostname should be compared against the hostname in the second +line of the file (if present), and if they differ, no attempt at +checking for a living process holding the lock will be made, and +the lockfile will never be deleted. +(The process is assumed to be alive.) +This is used for locking on NFS or other remote filesystems. +(The function will never create a lock if +.Dv PIDLOCK_USEHOSTNAME +is specified and no hostname is present.) +.El +.Pp +If +.Pa locker +is non-null, it will contain the PID of the locking process, if there +is one, on return. +.Pp +If +.Pa info +is non-null and the lock succeeds, the string it points to will be +written as the third line of the lock file. +.Sh RETURN VALUES +Zero is returned if the operation was successful; on an error a -1 +is returned and a standard error code is left in the global location +.Va errno . +.Sh ERRORS +In addition to the errors that are returned from +.Xr stat 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +and +.Xr link 2 , +.Fn pidlock +or +.Fn ttylock +can set +.Va errno +to the following values on failure: +.Bl -tag -width Er +.It Bq Er EFTYPE +The +.Fa tty +specified in +.Fn ttylock +is not a character special device. +.It Bq Er EWOULDBLOCK +Another running process has a lock and the +.Dv PIDLOCK_NONBLOCK +flag was specified. +.El +.\" .Sh SEE ALSO +.Sh HISTORY +The +.Fn pidlock +and +.Fn ttylock +functions appeared in +.Nx 1.3 . +.Sh AUTHORS +.An Curt Sampson +.Aq cjs@NetBSD.org . +.Sh BUGS +The lockfile format breaks if a pid is longer than ten digits when +printed in decimal form. +.Pp +The PID returned will be the pid of the locker on the remote machine if +.Dv PIDLOCK_USEHOSTNAME +is specified, but there is no indication that this is not on the local +machine. diff --git a/static/netbsd/man3/popcount.3 b/static/netbsd/man3/popcount.3 new file mode 100644 index 00000000..bf036264 --- /dev/null +++ b/static/netbsd/man3/popcount.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: popcount.3,v 1.6 2016/07/14 18:21:31 abhinav Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 22, 2011 +.Dt POPCOUNT 3 +.Os +.Sh NAME +.Nm popcount , +.Nm popcountl , +.Nm popcountll , +.Nm popcount32 , +.Nm popcount64 +.Nd count number of bits set in a bit string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft unsigned int +.Fn popcount "unsigned int value" +.Ft unsigned int +.Fn popcountl "unsigned long value" +.Ft unsigned int +.Fn popcountll "unsigned long long value" +.In stdint.h +.Ft unsigned int +.Fn popcount32 "uint32_t value" +.Ft unsigned int +.Fn popcount64 "uint64_t value" +.Sh DESCRIPTION +The +.Nm +functions return the number of bits set in +.Fa value . +.Sh SEE ALSO +.Xr ffs 3 +.Sh HISTORY +The +.Fn popcount , +.Fn popcountl , +.Fn popcountll , +.Fn popcount32 , +and +.Fn popcount64 +functions appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/popen.3 b/static/netbsd/man3/popen.3 new file mode 100644 index 00000000..a50e32bb --- /dev/null +++ b/static/netbsd/man3/popen.3 @@ -0,0 +1,228 @@ +.\" $NetBSD: popen.3,v 1.25 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)popen.3 8.2 (Berkeley) 5/3/95 +.\" +.Dd September 11, 2021 +.Dt POPEN 3 +.Os +.Sh NAME +.Nm popen , +.Nm popenve , +.Nm pclose +.Nd process +.Tn I/O +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn popen "const char *command" "const char *type" +.Ft FILE * +.Fn popenve "const char *path" "char * const *argv" "char * const *envp" "const char *type" +.Ft int +.Fn pclose "FILE *stream" +.Sh DESCRIPTION +The +.Fn popen +function +.Dq opens +a process by creating an IPC connection, +forking, +and invoking the shell. +Historically, +.Fn popen +was implemented with a unidirectional pipe; +hence many implementations of +.Fn popen +only allow the +.Fa type +argument to specify reading or writing, not both. +Since +.Fn popen +is now implemented using sockets, the +.Fa type +may request a bidirectional data flow. +The +.Fa type +argument is a pointer to a null-terminated string +which must be +.Ql r +for reading, +.Ql w +for writing, or +.Ql r+ +for reading and writing. +In addition if the character +.Ql e +is present in the +.Fa type +string, the file descriptor used internally is set to be closed on +.Xr exec 3 . +.Pp +The +.Fa command +argument is a pointer to a null-terminated string +containing a shell command line. +This command is passed to +.Pa /bin/sh +using the +.Fl c +flag; interpretation, if any, is performed by the shell. +.Pp +The +.Fn popenve +function is similar to +.Fn popen +but the first three arguments are passed +to +.Xr execve 2 +and there is no shell involved in the command invocation. +.Pp +The return value from +.Fn popen +and +.Fn popenve +is a normal standard +.Tn I/O +stream in all respects +save that it must be closed with +.Fn pclose +rather than +.Fn fclose . +Writing to such a stream +writes to the standard input of the command; +the command's standard output is the same as that of the process that called +.Fn popen , +unless this is altered by the command itself. +Conversely, reading from a +.Dq popened +stream reads the command's standard output, and +the command's standard input is the same as that of the process that called +.Fn popen . +.Pp +Note that output +.Fn popen +streams are fully buffered by default. +.Pp +The +.Fn pclose +function waits for the associated process to terminate +and returns the exit status of the command +as returned by +.Xr wait4 2 . +.Sh RETURN VALUES +The +.Fn popen +function returns +.Dv NULL +if the +.Xr vfork 2 , +.Xr pipe 2 , +or +.Xr socketpair 2 +calls fail, +or if it cannot allocate memory, preserving +the errno from those functions. +.Pp +The +.Fn pclose +function +returns \-1 if +.Fa stream +is not associated with a +.Dq popened +command, if +.Fa stream +has already been +.Dq pclosed , +setting errno to +.Er ESRCH , +or if +.Xr wait4 2 +returns an error, preserving the errno returned by +.Xr wait4 2 . +.Sh SEE ALSO +.Xr sh 1 , +.Xr execve 2 , +.Xr fork 2 , +.Xr pipe 2 , +.Xr socketpair 2 , +.Xr vfork 2 , +.Xr wait4 2 , +.Xr fclose 3 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr shquote 3 , +.Xr stdio 3 , +.Xr system 3 +.Sh STANDARDS +The +.Fn popen +and +.Fn pclose +functions conform to +.St -p1003.2-92 . +.Sh HISTORY +A +.Fn popen +and a +.Fn pclose +function appeared in +.At v7 . +.Pp +The +.Fn popenve +function first appeared in +.Nx 8 . +.Sh BUGS +Since the standard input of a command opened for reading +shares its seek offset with the process that called +.Fn popen , +if the original process has done a buffered read, +the command's input position may not be as expected. +Similarly, the output from a command opened for writing +may become intermingled with that of the original process. +The latter can be avoided by calling +.Xr fflush 3 +before +.Fn popen . +.Pp +Failure to execute the shell +is indistinguishable from the shell's failure to execute the command, +or an immediate exit of the command. +The only hint is an exit status of 127. +.Pp +The +.Fn popen +argument +always calls +.Xr sh 1 , +never calls +.Xr csh 1 . diff --git a/static/netbsd/man3/posix1e.3 b/static/netbsd/man3/posix1e.3 new file mode 100644 index 00000000..67f681f7 --- /dev/null +++ b/static/netbsd/man3/posix1e.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: posix1e.3,v 1.4 2020/06/28 21:37:05 wiz Exp $ +.\"- +.\" Copyright (c) 2000, 2009 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/posix1e/posix1e.3 318704 2017-05-23 07:05:34Z ngie $ +.\" +.Dd February 25, 2016 +.Dt POSIX1E 3 +.Os +.Sh NAME +.Nm posix1e +.Nd introduction to the POSIX.1e security API +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/acl.h +.\" .In sys/mac.h +.Sh DESCRIPTION +POSIX.1e describes five security extensions to the POSIX.1 API: Access +Control Lists (ACLs), Auditing, Capabilities, Mandatory Access Control, and +Information Flow Labels. +While IEEE POSIX.1e D17 specification has not been standardized, several of +its interfaces are widely used. +.Pp +.Nx +implements POSIX.1e interface for access control lists, described in +.Xr acl 3 , +and supports ACLs on the +.Xr ffs 7 +file system; ACLs must be administratively enabled using +.Xr tunefs 8 +or via +.Xr mount 8 +options. +.Pp +.Nx +does not implement the POSIX.1e mac, audit, privilege (capability), +or information flow label APIs. +.Sh ENVIRONMENT +POSIX.1e assigns security attributes to all objects, extending the security +functionality described in POSIX.1. +These additional attributes store fine-grained discretionary access control +information; for files, they are stored +in extended attributes, described in +.Xr extattr 3 . +.Pp +POSIX.2c describes +a set of userland utilities for manipulating these attributes, including +.Xr getfacl 1 +and +.Xr setfacl 1 . +.Sh SEE ALSO +.Xr getfacl 1 , +.Xr setfacl 1 , +.Xr acl 3 , +.Xr extattr 3 , +.Xr ffs 7 , +.Xr tunefs 8 , +.Xr acl 9 , +.Xr extattr 9 +.Sh STANDARDS +POSIX.1e is described in IEEE POSIX.1e draft 17. +.Sh HISTORY +POSIX.1e support was introduced in +.Nx 10.0 . +.Sh AUTHORS +.An Robert N M Watson +.An Chris D. Faulhaber +.An Thomas Moestl +.An Ilmar S Habibulin diff --git a/static/netbsd/man3/posix_memalign.3 b/static/netbsd/man3/posix_memalign.3 new file mode 100644 index 00000000..c7e69d9b --- /dev/null +++ b/static/netbsd/man3/posix_memalign.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: posix_memalign.3,v 1.8 2025/01/11 11:41:08 wiz Exp $ +.\" +.\" Copyright (C) 2006 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" FreeBSD: src/lib/libc/stdlib/posix_memalign.3,v 1.3 2007/03/28 04:32:51 jasone Exp +.\" +.Dd July 27, 2018 +.Dt POSIX_MEMALIGN 3 +.Os +.Sh NAME +.Nm posix_memalign , aligned_alloc +.Nd aligned memory allocation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn posix_memalign "void **ptr" "size_t alignment" "size_t size" +.Ft void * +.Fn aligned_alloc "size_t alignment" "size_t size" +.Sh DESCRIPTION +The +.Fn posix_memalign +function allocates +.Fa size +bytes of memory such that the allocation's base address is an even multiple of +.Fa alignment , +and returns the allocation in the value pointed to by +.Fa ptr . +The requested +.Fa alignment +must be a power of 2 at least as large as +.Fn sizeof "void *" . +.Pp +The +.Fn aligned_alloc +function allocates +.Fa size +bytes of memory such that the allocation's base address is an even multiple of +.Fa alignment . +The requested +.Fa alignment +must be a power of 2. +.Pp +Memory that is allocated via +.Fn posix_memalign +or +.Fn aligned_alloc +can be used as an argument in subsequent calls to +.Xr realloc 3 +and +.Xr free 3 . +.Sh RETURN VALUES +The +.Fn posix_memalign +function returns the value 0 if successful; otherwise it returns an error value. +.Pp +The +.Fn aligned_alloc +function returns a pointer to the allocated memory if successful; on failure it +returns +.Dv NULL +and sets +.Fa errno +to indicate the error. +.Sh ERRORS +The +.Fn posix_memalign +and +.Fn aligned_alloc +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa alignment +parameter is not a power of 2. +.It Bq Er ENOMEM +Memory allocation error. +.El +.Pp +The +.Fn posix_memalign +function will also fail if +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa alignment +parameter is not at least as large as +.Fn sizeof "void *" . +.El +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 , +.Xr realloc 3 , +.Xr valloc 3 +.Sh STANDARDS +The +.Fn posix_memalign +function conforms to +.St -p1003.1-2001 . +The +.Fn aligned_alloc +function conforms to +.St -isoC-2011 . +.Sh HISTORY +.St -isoC-2011 +required size to be an integer multiple of alignment. +This requirement was removed in later standards. diff --git a/static/netbsd/man3/posix_openpt.3 b/static/netbsd/man3/posix_openpt.3 new file mode 100644 index 00000000..70e03b65 --- /dev/null +++ b/static/netbsd/man3/posix_openpt.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: posix_openpt.3,v 1.11 2025/08/06 00:07:16 gutteridge Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 6, 2025 +.Dt POSIX_OPENPT 3 +.Os +.Sh NAME +.Nm posix_openpt +.Nd open a pseudo-terminal device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.In fcntl.h +.Ft int +.Fn posix_openpt "int oflag" +.Sh DESCRIPTION +The +.Fn posix_openpt +function searches for an unused master pseudo-terminal device, +opens it, and returns a file descriptor associated with the now +used pseudo-terminal device. +The +.Fa oflag +argument has the same meaning as in the +.Xr open 2 +call. +.Sh RETURN VALUES +If successful, +.Fn posix_openpt +returns a non-negative integer, which corresponds to a file descriptor +pointing to the master pseudo-terminal device. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +Note that unlike implementations on some other operating systems, +.Fn posix_openpt +does not return +.Er EINVAL +if a flag supplied in +.Fa oflag +would be deemed invalid, instead it is simply ignored. +This means it is not possible to dynamically test which +.Xr open 2 +flags are possible to set, and apply a fallback if +.Er EINVAL +is received. +However, this is unlikely to be a concern in practice, as flags such as +.Dv O_NONBLOCK , +.Dv O_CLOEXEC , +and +.Dv O_CLOFORK +are supported. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr open 2 , +.Xr grantpt 3 , +.Xr ptsname 3 , +.Xr unlockpt 3 +.Sh RATIONALE +The standards committee did not want to directly expose the cloning device, +thus decided to wrap the functionality in this function. +The equivalent code would be: +.Bd -literal + int + posix_openpt(int oflag) { + return open("/dev/ptmx", oflag); + } +.Ed +.Sh STANDARDS +The +.Fn posix_openpt +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +This function first appeared in +.Nx 3 . +Support for non-standard flags appeared in +.Nx 10 . diff --git a/static/netbsd/man3/posix_spawn.3 b/static/netbsd/man3/posix_spawn.3 new file mode 100644 index 00000000..6ca4a59a --- /dev/null +++ b/static/netbsd/man3/posix_spawn.3 @@ -0,0 +1,488 @@ +.\" $NetBSD: posix_spawn.3,v 1.13 2021/11/15 14:06:50 wiz Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawn.3,v 1.2.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd June 11, 2019 +.Dt POSIX_SPAWN 3 +.Os +.Sh NAME +.Nm posix_spawn , +.Nm posix_spawnp +.Nd "spawn a process" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" +.Ft int +.Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" +.Sh DESCRIPTION +The +.Fn posix_spawn +and +.Fn posix_spawnp +functions create a new process (child process) from the specified +process image. +The new process image is constructed from a regular executable +file called the new process image file. +.Pp +When a C program is executed as the result of this call, it is +entered as a C-language function call as follows: +.Bd -literal -offset indent +int main(int argc, char *argv[]); +.Ed +.Pp +where +.Fa argc +is the argument count and +.Fa argv +is an array of character pointers to the arguments themselves. +In addition, the variable: +.Bd -literal -offset indent +extern char **environ; +.Ed +.Pp +points to an array of character pointers to +the environment strings. +.Pp +The argument +.Fa argv +is an array of character pointers to null-terminated +strings. +The last member of this array is a null pointer and is not counted +in +.Fa argc . +These strings constitute the argument list available to the new process +image. +The value in +.Fa argv Ns [0] +should point to +a filename that is associated with the process image being started by +the +.Fn posix_spawn +or +.Fn posix_spawnp +function. +.Pp +The argument +.Fa envp +is an array of character pointers to null-terminated strings. +These strings constitute the environment for the new process image. +The environment array is terminated by a null pointer. +.Pp +The +.Fa path +argument to +.Fn posix_spawn +is a pathname that identifies the new process image file to execute. +.Pp +The +.Fa file +parameter to +.Fn posix_spawnp +is used to construct a pathname that identifies the new process +image file. +If the file parameter contains a slash character, the file parameter +is used as the pathname for the new process image file. +Otherwise, the path prefix for this file is obtained by a search +of the directories passed as the environment variable +.Dq Ev PATH . +If this variable is not specified, +the default path is set according to the +.Dv _PATH_DEFPATH +definition in +.In paths.h , +which is set to +.Dq Ev /usr/bin:/bin . +.Pp +If +.Fa file_actions +is a null pointer, then file descriptors open in the +calling process remain open in the child process, except for those +whose close-on-exec flag +.Dv FD_CLOEXEC +is set (see +.Fn fcntl ) . +For those +file descriptors that remain open, all attributes of the corresponding +open file descriptions, including file locks (see +.Fn fcntl ) , +remain unchanged. +.Pp +If +.Fa file_actions +is not +.Dv NULL , +then the file descriptors open in the child process are +those open in the calling process as modified by the spawn file +actions object pointed to by +.Fa file_actions +and the +.Dv FD_CLOEXEC +flag of each remaining open file descriptor after the spawn file actions +have been processed. +The effective order of processing the spawn file actions are: +.Bl -enum +.It +The set of open file descriptors for the child process initially +are the same set as is open for the calling process. +All attributes of the corresponding open file descriptions, including +file locks (see +.Fn fcntl ) , +remain unchanged. +.It +The signal mask, signal default actions, and the effective user and +group IDs for the child process are changed as specified in the +attributes object referenced by +.Fa attrp . +.It +The file actions specified by the spawn file actions object are +performed in the order in which they were added to the spawn file +actions object. +.It +Any file descriptor that has its +.Dv FD_CLOEXEC +flag set (see +.Fn fcntl ) +is closed. +.El +.Pp +The maximum number of +.Fa file_actions +objects is limited to the +.Dv RLIMIT_NOFILE +rlimit times 2. +.Pp +The +.Vt posix_spawnattr_t +spawn attributes object type is defined in +.In spawn.h . +It contains the attributes defined below. +.Pp +If the +.Dv POSIX_SPAWN_SETPGROUP +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp , +and the spawn-pgroup attribute of the same object is non-zero, then the +child's process group is as specified in the spawn-pgroup +attribute of the object referenced by +.Fa attrp . +.Pp +As a special case, if the +.Dv POSIX_SPAWN_SETPGROUP +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp , +and the spawn-pgroup attribute of the same object is set to zero, then +the child is in a new process group with a process group ID equal +to its process ID. +.Pp +If the +.Dv POSIX_SPAWN_SETPGROUP +flag is not set in the spawn-flags attribute of the object referenced by +.Fa attrp , +the new child process inherits the parent's process group. +.Pp +If the +.Dv POSIX_SPAWN_SETSCHEDPARAM +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp , +but +.Dv POSIX_SPAWN_SETSCHEDULER +is not set, the new process image initially has the scheduling +policy of the calling process with the scheduling parameters specified +in the spawn-schedparam attribute of the object referenced by +.Fa attrp . +.Pp +If the +.Dv POSIX_SPAWN_SETSCHEDULER +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp +(regardless of the setting of the +.Dv POSIX_SPAWN_SETSCHEDPARAM +flag), the new process image initially has the scheduling policy +specified in the spawn-schedpolicy attribute of the object referenced by +.Fa attrp +and the scheduling parameters specified in the spawn-schedparam +attribute of the same object. +.Pp +The +.Dv POSIX_SPAWN_RESETIDS +flag in the spawn-flags attribute of the object referenced by +.Fa attrp +governs the effective user ID of the child process. +If this flag is not set, the child process inherits the parent +process' effective user ID. +If this flag is set, the child process' effective user ID is reset +to the parent's real user ID. +In either case, if the set-user-ID mode bit of the new process image +file is set, the effective user ID of the child process becomes +that file's owner ID before the new process image begins execution. +.Pp +The +.Dv POSIX_SPAWN_RESETIDS +flag in the spawn-flags attribute of the object referenced by +.Fa attrp +also governs the effective group ID of the child process. +If this flag is not set, the child process inherits the parent +process' effective group ID. +If this flag is set, the child process' effective group ID is +reset to the parent's real group ID. +In either case, if the set-group-ID mode bit of the new process image +file is set, the effective group ID of the child process becomes +that file's group ID before the new process image begins execution. +.Pp +If the +.Dv POSIX_SPAWN_SETSIGMASK +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp , +the child process initially has the signal mask specified in the +spawn-sigmask attribute of the object referenced by +.Fa attrp . +.Pp +If the +.Dv POSIX_SPAWN_SETSIGDEF +flag is set in the spawn-flags attribute of the object referenced by +.Fa attrp , +the signals specified in the spawn-sigdefault attribute of the same +object is set to their default actions in the child process. +Signals set to the default action in the parent process is set to +the default action in the child process. +.Pp +Signals set to be caught by the calling process is set to the +default action in the child process. +.Pp +Signals set to be ignored by the calling process image is set to +be ignored by the child process, unless otherwise specified by the +.Dv POSIX_SPAWN_SETSIGDEF +flag being set in the spawn-flags attribute of the object referenced by +.Fa attrp +and the signals being indicated in the spawn-sigdefault attribute +of the object referenced by +.Fa attrp . +.Pp +If the value of the +.Fa attrp +pointer is +.Dv NULL , +then the default values are used. +.Pp +All process attributes, other than those influenced by the attributes +set in the object referenced by +.Fa attrp +as specified above or by the file descriptor manipulations specified in +.Fa file_actions , +appear in the new process image as though +.Fn vfork +had been called to create a child process and then +.Fn execve +had been called by the child process to execute the new process image. +.Pp +This implementation does not run +.Xr pthread_atfork 3 +callbacks. +.Fn posix_spawn +on +.Nx +directly creates the child process without intermediate fork. +.Sh RETURN VALUES +Upon successful completion, +.Fn posix_spawn +and +.Fn posix_spawnp +return the process ID of the child process to the parent process, +in the variable pointed to by a +.Pf non- Dv NULL +.Fa pid +argument, and return zero as the function return value. +Otherwise, no child process is created, no value is stored into +the variable pointed to by +.Fa pid , +and an error number is returned as the function return value to +indicate the error. +If the +.Fa pid +argument is a null pointer, the process ID of the child is not returned +to the caller. +.Sh ERRORS +.Bl -enum +.It +If +.Fn posix_spawn +and +.Fn posix_spawnp +fail for any of the reasons that would cause +.Fn vfork +or one of the +.Nm exec +to fail, an error value is returned as described by +.Fn vfork +and +.Nm exec , +respectively (or, if the error occurs after the calling process successfully +returns, the child process exits with exit status 127). +.It +If +.Nm POSIX_SPAWN_SETPGROUP +is set in the spawn-flags attribute of the object referenced by attrp, and +.Fn posix_spawn +or +.Fn posix_spawnp +fails while changing the child's process group, an error value is returned as +described by +.Fn setpgid +(or, if the error occurs after the calling process successfully returns, +the child process exits with exit status 127). +.It +If +.Nm POSIX_SPAWN_SETSCHEDPARAM +is set and +.Nm POSIX_SPAWN_SETSCHEDULER +is not set in the spawn-flags attribute of the object referenced by attrp, then +if +.Fn posix_spawn +or +.Fn posix_spawnp +fails for any of the reasons that would cause +.Fn sched_setparam +to fail, an error value is returned as described by +.Fn sched_setparam +(or, if the error occurs after the calling process successfully returns, the +child process exits with exit status 127). +.It +If +.Nm POSIX_SPAWN_SETSCHEDULER +is set in the spawn-flags attribute of the object referenced by attrp, and if +.Fn posix_spawn +or +.Fn posix_spawnp +fails for any of the reasons that would cause +.Fn sched_setscheduler +to fail, an error value is returned as described by +.Fn sched_setscheduler +(or, if the error occurs after the calling process successfully returns, +the child process exits with exit status 127). +.It +If the +.Fa file_actions +argument is not +.Dv NULL , +and specifies any +.Fn close , +.Fn dup2 , +or +.Fn open +actions to be performed, and if +.Fn posix_spawn +or +.Fn posix_spawnp +fails for any of the reasons that would cause +.Fn close , +.Fn dup2 , +or +.Fn open +to fail, an error value is returned as described by +.Fn close , +.Fn dup2 , +and +.Fn open , +respectively (or, if the error occurs after the calling process successfully +returns, the child process exits with exit status 127). An open file action +may, by itself, result in any of the errors described by +.Fn close +or +.Fn dup2 , +in addition to those described by +.Fn open . +Finally, if the number of +.Fa file_actions +objects exceeds the allowed limit, +.Er EINVAL +is returned. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr dup2 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr open 2 , +.Xr setpgid 2 , +.Xr vfork 2 , +.Xr posix_spawn_file_actions_addchdir 3 , +.Xr posix_spawn_file_actions_addclose 3 , +.Xr posix_spawn_file_actions_adddup2 3 , +.Xr posix_spawn_file_actions_addfchdir 3 , +.Xr posix_spawn_file_actions_addopen 3 , +.Xr posix_spawn_file_actions_destroy 3 , +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_getflags 3 , +.Xr posix_spawnattr_getpgroup 3 , +.Xr posix_spawnattr_getschedparam 3 , +.Xr posix_spawnattr_getschedpolicy 3 , +.Xr posix_spawnattr_getsigdefault 3 , +.Xr posix_spawnattr_getsigmask 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setflags 3 , +.Xr posix_spawnattr_setpgroup 3 , +.Xr posix_spawnattr_setschedparam 3 , +.Xr posix_spawnattr_setschedpolicy 3 , +.Xr posix_spawnattr_setsigdefault 3 , +.Xr posix_spawnattr_setsigmask 3 , +.Xr sched_setparam 3 , +.Xr sched_setscheduler 3 +.Sh STANDARDS +The +.Fn posix_spawn +and +.Fn posix_spawnp +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawn +and +.Fn posix_spawnp +functions first appeared in +.Fx 8.0 . +The library parts were ported and a kernel implementation of +.Fn posix_spawn +added for +.Nx 6.0 +during Google Summer of Code by Charles Zhang and Martin Husemann. +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawn_file_actions_addchdir.3 b/static/netbsd/man3/posix_spawn_file_actions_addchdir.3 new file mode 100644 index 00000000..34ac8f6e --- /dev/null +++ b/static/netbsd/man3/posix_spawn_file_actions_addchdir.3 @@ -0,0 +1,162 @@ +.\" $NetBSD: posix_spawn_file_actions_addchdir.3,v 1.3 2021/11/15 16:00:25 kre Exp $ +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd July 8, 2020 +.Dt POSIX_SPAWN_FILE_ACTIONS_ADDCHDIR 3 +.Os +.Sh NAME +.Nm posix_spawn_file_actions_addchdir , +.Nm posix_spawn_file_actions_addfchdir +.Nd add chdir or fchdir action to spawn file actions object +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn_file_actions_addchdir "posix_spawn_file_actions_t *restrict file_actions" "const char *restrict path" +.Ft int +.Fn posix_spawn_file_actions_addfchdir "posix_spawn_file_actions_t * file_actions" "int fildes" +.Sh DESCRIPTION +The +.Fn posix_spawn_file_actions_addchdir +function adds a chdir action to the object referenced by +.Fa file_actions +that causes the working directory to be set to +.Fa path +(as if +.Bd -literal -offset indent +chdir(path) +.Ed +.Pp +had been called) for a new process spawned using this file actions +object. +A relative +.Fa path +is interpreted relative to the working directory determined by any +prior actions. +The string pointed to by +.Fa path +is copied by the +.Fn posix_spawn_file_actions_addchdir +function. +.Pp +The +.Fn posix_spawn_file_actions_addfchdir +function adds a fchdir action to the object referenced by +.Fa file_actions +that causes the working directory to be set to the directory referenced by +.Fa fildes +(as if +.Bd -literal -offset indent +fchdir(fildes) +.Ed +.Pp +had been called) for a new process spawned using this file actions object. +.\" The last paragraph of APPLICATION USAGE +.Pp +File actions are performed in the new process created by +.Fn posix_spawn +or +.Fn posix_spawnp +in the same order that they were added to the file actions object. +Thus the execution of an +.Dq open +action that was created by a call to +.Fn posix_spawn_file_actions_addopen +that specifies a relative path will be affected by the execution of a +chdir or fchdir action that was created by a previous call to +.Fn posix_spawn_file_actions_addchdir +or +.Fn posix_spawn_file_actions_addfchdir . +Likewise, a relative path passed to +.Fn posix_spawn +will be affected by the last chdir or fchdir action in the file action list. +.Sh RETURN VALUES +Upon successful completion, these function return zero; +otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn posix_spawn_file_actions_addfchdir +function fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The value specified by +.Fa fildes +is negative. +.El +.Pp +Both functions may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa file_actions +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to add the spawn file actions object. +.El +.Pp +It is not an error for the +.Fa path +or +.Fa fildes +argument passed to these functions to specify a pathname or file descriptor +for which the specified operation could not be performed at the time of the call. +Any such error will be detected when the associated file actions object is +later used during a +.Fn posix_spawn +or +.Fn posix_spawnp +operation. +.Sh SEE ALSO +.Xr chdir 2 , +.Xr fchdir 2 , +.Xr posix_spawn 3 , +.Xr posix_spawn_file_actions_destroy 3 , +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawn_file_actions_addchdir +and +.Fn posix_spawn_file_actions_addfchdir +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The POSIX implementation of +.Fn posix_spawn_file_actions_addchdir +and +.Fn posix_spawn_file_actions_addfchdir +is derived from SOLARIS kernel's +.Fn posix_spawn_file_actions_addchdir_np . +.Sh AUTHORS +.An Piyush Sachdeva diff --git a/static/netbsd/man3/posix_spawn_file_actions_addopen.3 b/static/netbsd/man3/posix_spawn_file_actions_addopen.3 new file mode 100644 index 00000000..9a23d6f9 --- /dev/null +++ b/static/netbsd/man3/posix_spawn_file_actions_addopen.3 @@ -0,0 +1,190 @@ +.\" $NetBSD: posix_spawn_file_actions_addopen.3,v 1.5 2014/02/02 16:59:13 wiz Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawn_file_actions_addopen.3,v 1.2.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd February 2, 2014 +.Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3 +.Os +.Sh NAME +.Nm posix_spawn_file_actions_addopen , +.Nm posix_spawn_file_actions_adddup2 , +.Nm posix_spawn_file_actions_addclose +.Nd "add open, dup2 or close action to spawn file actions object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn_file_actions_addopen "posix_spawn_file_actions_t * file_actions" "int fildes" "const char *restrict path" "int oflag" "mode_t mode" +.Ft int +.Fn posix_spawn_file_actions_adddup2 "posix_spawn_file_actions_t * file_actions" "int fildes" "int newfildes" +.Ft int +.Fn posix_spawn_file_actions_addclose "posix_spawn_file_actions_t * file_actions" "int fildes" +.Sh DESCRIPTION +These functions add an open, dup2 or close action to a spawn +file actions object. +.Pp +A spawn file actions object is of type +.Vt posix_spawn_file_actions_t +(defined in +.In spawn.h ) +and is used to specify a series of actions to be performed by a +.Fn posix_spawn +or +.Fn posix_spawnp +operation in order to arrive at the set of open file descriptors for the +child process given the set of open file descriptors of the parent. +.Pp +A spawn file actions object, when passed to +.Fn posix_spawn +or +.Fn posix_spawnp , +specify how the set of open file descriptors in the calling +process is transformed into a set of potentially open file descriptors +for the spawned process. +This transformation is as if the specified sequence of actions was +performed exactly once, in the context of the spawned process (prior to +execution of the new process image), in the order in which the actions +were added to the object; additionally, when the new process image is +executed, any file descriptor (from this new set) which has its +.Dv FD_CLOEXEC +flag set is closed (see +.Fn posix_spawn ) . +.Pp +The +.Fn posix_spawn_file_actions_addopen +function adds an open action to the object referenced by +.Fa file_actions +that causes the file named by +.Fa path +to be opened (as if +.Bd -literal -offset indent +open(path, oflag, mode) +.Ed +.Pp +had been called, and the returned file descriptor, if not +.Fa fildes , +had been changed to +.Fa fildes ) +when a new process is spawned using this file actions object. +If +.Fa fildes +was already an open file descriptor, it is closed before the new +file is opened. +.Pp +The string described by +.Fa path +is copied by the +.Fn posix_spawn_file_actions_addopen +function. +.Pp +The +.Fn posix_spawn_file_actions_adddup2 +function adds a dup2 action to the object referenced by +.Fa file_actions +that causes the file descriptor +.Fa fildes +to be duplicated as +.Fa newfildes +(as if +.Bd -literal -offset indent +dup2(fildes, newfildes) +.Ed +.Pp +had been called) when a new process is spawned using this file actions object. +.Pp +The +.Fn posix_spawn_file_actions_addclose +function adds a close action to the object referenced by +.Fa file_actions +that causes the file descriptor +.Fa fildes +to be closed (as if +.Bd -literal -offset indent +close(fildes) +.Ed +.Pp +had been called) when a new process is spawned using this file actions +object. +.Sh RETURN VALUES +Upon successful completion, these functions return zero; +otherwise, an error number is returned to indicate the error. +.Sh ERRORS +These +functions fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The value specified by +.Fa fildes +or +.Fa newfildes +is negative. +.It Bq Er EINVAL +The value specified by +.Fa file_actions +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr dup2 2 , +.Xr open 2 , +.Xr posix_spawn 3 , +.Xr posix_spawn_file_actions_destroy 3 , +.Xr posix_spawn_file_actions_init 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawn_file_actions_addopen , +.Fn posix_spawn_file_actions_adddup2 +and +.Fn posix_spawn_file_actions_addclose +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawn_file_actions_addopen , +.Fn posix_spawn_file_actions_adddup2 +and +.Fn posix_spawn_file_actions_addclose +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawn_file_actions_init.3 b/static/netbsd/man3/posix_spawn_file_actions_init.3 new file mode 100644 index 00000000..d33a09c2 --- /dev/null +++ b/static/netbsd/man3/posix_spawn_file_actions_init.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: posix_spawn_file_actions_init.3,v 1.5 2014/02/02 16:59:13 wiz Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawn_file_actions_init.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd February 2, 2014 +.Dt POSIX_SPAWN_FILE_ACTIONS_INIT 3 +.Os +.Sh NAME +.Nm posix_spawn_file_actions_init , +.Nm posix_spawn_file_actions_destroy +.Nd "initialize and destroy spawn file actions object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawn_file_actions_init "posix_spawn_file_actions_t * file_actions" +.Ft int +.Fn posix_spawn_file_actions_destroy "posix_spawn_file_actions_t * file_actions" +.Sh DESCRIPTION +The +.Fn posix_spawn_file_actions_init +function initialize the object referenced by +.Fn file_actions +to contain no file actions for +.Fn posix_spawn +or +.Fn posix_spawnp . +Initializing an already initialized spawn file actions object may cause +memory to be leaked. +.Pp +The +.Fn posix_spawn_file_actions_destroy +function destroy the object referenced by +.Fa file_actions ; +the object becomes, in effect, uninitialized. +A destroyed spawn file actions object can be reinitialized using +.Fn posix_spawn_file_actions_init . +The object should not be used after it has been destroyed. +.Sh RETURN VALUES +Upon successful completion, these functions return zero; +otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn posix_spawn_file_actions_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa file_actions +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the spawn file actions object. +.El +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawn_file_actions_addclose 3 , +.Xr posix_spawn_file_actions_adddup2 3 , +.Xr posix_spawn_file_actions_addopen 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawn_file_actions_init +and +.Fn posix_spawn_file_actions_destroy +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawn_file_actions_init +and +.Fn posix_spawn_file_actions_destroy +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getflags.3 b/static/netbsd/man3/posix_spawnattr_getflags.3 new file mode 100644 index 00000000..bb29c53b --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getflags.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: posix_spawnattr_getflags.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getflags.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETFLAGS 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getflags , +.Nm posix_spawnattr_setflags +.Nd "get and set the spawn-flags attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getflags "const posix_spawnattr_t *restrict attr" "short *restrict flags" +.Ft int +.Fn posix_spawnattr_setflags "posix_spawnattr_t *attr" "short flags" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getflags +function obtains the value of the spawn-flags attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setflags +function sets the spawn-flags attribute in an initialized +attributes object referenced by +.Fa attr . +.Pp +The spawn-flags attribute is used to indicate which process attributes +are to be changed in the new process image when invoking +.Fn posix_spawn +or +.Fn posix_spawnp . +It is the bitwise-inclusive OR of zero or more of the following flags +(see +.Fn posix_spawn ) : +.Bl -tag -offset indent +.It Dv POSIX_SPAWN_RESETIDS +.It Dv POSIX_SPAWN_SETPGROUP +.It Dv POSIX_SPAWN_SETSIGDEF +.It Dv POSIX_SPAWN_SETSIGMASK +.It Dv POSIX_SPAWN_SETSCHEDPARAM +.It Dv POSIX_SPAWN_SETSCHEDULER +.El +.Pp +These flags are defined in +.In spawn.h . +The default value of this attribute is as if no flags were set. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getflags +and +.Fn posix_spawnattr_setflags +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getflags +and +.Fn posix_spawnattr_setflags +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getflags +and +.Fn posix_spawnattr_setflags +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getpgroup.3 b/static/netbsd/man3/posix_spawnattr_getpgroup.3 new file mode 100644 index 00000000..7f6c6fb3 --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getpgroup.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: posix_spawnattr_getpgroup.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getpgroup.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETPGROUP 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getpgroup , +.Nm posix_spawnattr_setpgroup +.Nd "get and set the spawn-pgroup attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getpgroup "const posix_spawnattr_t *restrict attr" "pid_t *restrict pgroup" +.Ft int +.Fn posix_spawnattr_setpgroup "posix_spawnattr_t *attr" "pid_t pgroup" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getpgroup +function obtains the value of the spawn-pgroup attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setpgroup +function sets the spawn-pgroup attribute in an initialized +attributes object referenced by +.Fa attr . +.Pp +The spawn-pgroup attribute represents the process group to be joined by +the new process image in a spawn operation (if +.Dv POSIX_SPAWN_SETPGROUP +is set in the spawn-flags attribute). +The default value of this attribute is zero. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getpgroup +and +.Fn posix_spawnattr_setpgroup +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getpgroup +and +.Fn posix_spawnattr_setpgroup +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getpgroup +and +.Fn posix_spawnattr_setpgroup +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getschedparam.3 b/static/netbsd/man3/posix_spawnattr_getschedparam.3 new file mode 100644 index 00000000..c5936bbe --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getschedparam.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: posix_spawnattr_getschedparam.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getschedparam.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETSCHEDPARAM 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getschedparam , +.Nm posix_spawnattr_setschedparam +.Nd "get and set the spawn-schedparam attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getschedparam "const posix_spawnattr_t *restrict attr" "struct sched_param *restrict schedparam" +.Ft int +.Fn posix_spawnattr_setschedparam "posix_spawnattr_t *attr" "const struct sched_param *restrict schedparam" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getschedparam +function obtains the value of the spawn-schedparam attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setschedparam +function sets the spawn-schedparam attribute in an initialized attributes +object referenced by +.Fa attr . +.Pp +The spawn-schedparam attribute represents the scheduling parameters to +be assigned to the new process image in a spawn operation (if +.Dv POSIX_SPAWN_SETSCHEDULER +or +.Dv POSIX_SPAWN_SETSCHEDPARAM +is set in the spawn-flags attribute). +The default value of this attribute is unspecified. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getschedparam +and +.Fn posix_spawnattr_setschedparam +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_getschedpolicy 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setschedpolicy 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getschedparam +and +.Fn posix_spawnattr_setschedparam +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getschedparam +and +.Fn posix_spawnattr_setschedparam +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getschedpolicy.3 b/static/netbsd/man3/posix_spawnattr_getschedpolicy.3 new file mode 100644 index 00000000..19e3a152 --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getschedpolicy.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: posix_spawnattr_getschedpolicy.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getschedpolicy.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETSCHEDPOLICY 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getschedpolicy , +.Nm posix_spawnattr_setschedpolicy +.Nd "get and set the spawn-schedpolicy attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getschedpolicy "const posix_spawnattr_t *restrict attr" "int *restrict schedpolicy" +.Ft int +.Fn posix_spawnattr_setschedpolicy "posix_spawnattr_t *attr" "int schedpolicy" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getschedpolicy +function obtains the value of the spawn-schedpolicy attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setschedpolicy +function sets the spawn-schedpolicy attribute in an initialized attributes +object referenced by +.Fa attr . +.Pp +The spawn-schedpolicy attribute represents the scheduling policy to +be assigned to the new process image in a spawn operation (if +.Dv POSIX_SPAWN_SETSCHEDULER +is set in the spawn-flags attribute). +The default value of this attribute is unspecified. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getschedpolicy +and +.Fn posix_spawnattr_setschedpolicy +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_getschedparam 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setschedparam 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getschedpolicy +and +.Fn posix_spawnattr_setschedpolicy +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getschedpolicy +and +.Fn posix_spawnattr_setschedpolicy +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getsigdefault.3 b/static/netbsd/man3/posix_spawnattr_getsigdefault.3 new file mode 100644 index 00000000..a3a321e2 --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getsigdefault.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: posix_spawnattr_getsigdefault.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getsigdefault.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETSIGDEFAULT 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getsigdefault , +.Nm posix_spawnattr_setsigdefault +.Nd "get and set the spawn-sigdefault attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getsigdefault "const posix_spawnattr_t *restrict attr" "sigset_t *restrict sigdefault" +.Ft int +.Fn posix_spawnattr_setsigdefault "posix_spawnattr_t *attr" "const sigset_t *restrict sigdefault" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getsigdefault +function obtains the value of the spawn-sigdefault attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setsigdefault +function sets the spawn-sigdefault attribute in an initialized attributes +object referenced by +.Fa attr . +.Pp +The spawn-sigdefault attribute represents the set of signals to be forced to +default signal handling in the new process image (if +.Dv POSIX_SPAWN_SETSIGDEF +is set in the spawn-flags attribute) by a spawn operation. +The default value of this attribute is an empty signal set. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getsigdefault +and +.Fn posix_spawnattr_setsigdefault +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_getsigmask 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setsigmask 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getsigdefault +and +.Fn posix_spawnattr_setsigdefault +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getsigdefault +and +.Fn posix_spawnattr_setsigdefault +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_getsigmask.3 b/static/netbsd/man3/posix_spawnattr_getsigmask.3 new file mode 100644 index 00000000..0b0ad4c5 --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_getsigmask.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: posix_spawnattr_getsigmask.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_getsigmask.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_GETSIGMASK 3 +.Os +.Sh NAME +.Nm posix_spawnattr_getsigmask , +.Nm posix_spawnattr_setsigmask +.Nd "get and set the spawn-sigmask attribute of a spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_getsigmask "const posix_spawnattr_t *restrict attr" "sigset_t *restrict sigmask" +.Ft int +.Fn posix_spawnattr_setsigmask "posix_spawnattr_t *attr" "const sigset_t *restrict sigmask" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_getsigmask +function obtains the value of the spawn-sigmask attribute from the +attributes object referenced by +.Fa attr . +.Pp +The +.Fn posix_spawnattr_setsigmask +function sets the spawn-sigmask attribute in an initialized attributes +object referenced by +.Fa attr . +.Pp +The spawn-sigmask attribute represents the signal mask in effect in the +new process image of a spawn operation (if +.Dv POSIX_SPAWN_SETSIGMASK +is set in the spawn-flags attribute). +The default value of this attribute is unspecified. +.Sh RETURN VALUES +The +.Fn posix_spawnattr_getsigmask +and +.Fn posix_spawnattr_setsigmask +functions return zero. +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnattr_destroy 3 , +.Xr posix_spawnattr_init 3 , +.Xr posix_spawnattr_setsigmask 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_getsigmask +and +.Fn posix_spawnattr_setsigmask +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_getsigmask +and +.Fn posix_spawnattr_setsigmask +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/posix_spawnattr_init.3 b/static/netbsd/man3/posix_spawnattr_init.3 new file mode 100644 index 00000000..2358bc0a --- /dev/null +++ b/static/netbsd/man3/posix_spawnattr_init.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: posix_spawnattr_init.3,v 1.4 2014/03/18 18:20:37 riastradh Exp $ +.\" +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD: src/lib/libc/gen/posix_spawnattr_init.3,v 1.1.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ +.\" +.Dd December 20, 2011 +.Dt POSIX_SPAWNATTR_INIT 3 +.Os +.Sh NAME +.Nm posix_spawnattr_init , +.Nm posix_spawnattr_destroy +.Nd "initialize and destroy spawn attributes object" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In spawn.h +.Ft int +.Fn posix_spawnattr_init "posix_spawnattr_t * attr" +.Ft int +.Fn posix_spawnattr_destroy "posix_spawnattr_t * attr" +.Sh DESCRIPTION +The +.Fn posix_spawnattr_init +function initializes a spawn attributes object +.Fa attr +with the default value for all of the individual attributes used by the +implementation. +Initializing an already initialized spawn attributes object may cause +memory to be leaked. +.Pp +The +.Fn posix_spawnattr_destroy +function destroys a spawn attributes object. +A destroyed +.Fa attr +attributes object can be reinitialized using +.Fn posix_spawnattr_init . +The object should not be used after it has been destroyed. +.Pp +A spawn attributes object is of type +.Vt posix_spawnattr_t +(defined in +.In spawn.h ) +and is used to specify the inheritance of process attributes across a +spawn operation. +.Pp +The resulting spawn attributes object (possibly modified by setting +individual attribute values), is used to modify the behavior of +.Fn posix_spawn +or +.Fn posix_spawnp . +After a spawn attributes object has been used to spawn a process by a +call to a +.Fn posix_spawn +or +.Fn posix_spawnp , +any function affecting the attributes object (including destruction) +will not affect any process that has been spawned in this way. +.Sh RETURN VALUES +Upon successful completion, +.Fn posix_spawnattr_init +and +.Fn posix_spawnattr_destroy +return zero; +otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn posix_spawnattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the spawn file actions object. +.El +.Sh SEE ALSO +.Xr posix_spawn 3 , +.Xr posix_spawnp 3 +.Sh STANDARDS +The +.Fn posix_spawnattr_init +and +.Fn posix_spawnattr_destroy +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_spawnattr_init +and +.Fn posix_spawnattr_destroy +functions first appeared in +.Fx 8.0 +and imported for +.Nx 6.0 . +.Sh AUTHORS +.An Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/static/netbsd/man3/pow.3 b/static/netbsd/man3/pow.3 new file mode 100644 index 00000000..26550491 --- /dev/null +++ b/static/netbsd/man3/pow.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: pow.3,v 1.4 2024/01/26 23:41:55 wiz Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 24, 2024 +.Dt POW 3 +.Os +.Sh NAME +.Nm pow , +.Nm powf , +.Nm powl +.Nd power functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn pow "double x" "double y" +.Ft float +.Fn powf "float x" "float y" +.Ft long double +.Fn powl "long double x" "long double y" +.Sh DESCRIPTION +The +.Fn pow +family of functions returns +.Fa x +raised to the power of +.Fa y . +.Pp +If +.Fa x +is negative and +.Fa y +is not an integer, the global variable +.Va errno +is set to +.Er EDOM , +and on +.Tn VAX +a reserved operand fault is generated. +A portable application should nevertheless ensure that +.Fa y +is an integer value whenever +.Fa x +is negative. +.Sh RETURN VALUES +.\" +.\" XXX: List also the special return values? +.\" +Upon successful completion, the described functions return +.Fa x^y . +.Sh SEE ALSO +.Xr exp 3 , +.Xr log 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . +.Sh HISTORY +The history of the power functions dates back to +.At v6 . diff --git a/static/netbsd/man3/ppath.3 b/static/netbsd/man3/ppath.3 new file mode 100644 index 00000000..c7b60083 --- /dev/null +++ b/static/netbsd/man3/ppath.3 @@ -0,0 +1,440 @@ +.\" $NetBSD: ppath.3,v 1.5 2017/10/23 00:59:44 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young <dyoung@NetBSD.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 24, 2011 +.Dt PPATH 3 +.Os +.Sh NAME +.Nm ppath , +.Nm ppath_idx , +.Nm ppath_key , +.\" , +.Nm ppath_component_retain , +.Nm ppath_component_release , +.\" , +.Nm ppath_create , +.Nm ppath_length , +.Nm ppath_component_idx , +.Nm ppath_component_key , +.Nm ppath_pop , +.Nm ppath_push , +.Nm ppath_component_at , +.Nm ppath_subpath , +.Nm ppath_push_idx , +.Nm ppath_push_key , +.Nm ppath_replace_idx , +.Nm ppath_replace_key , +.\" , +.Nm ppath_copy , +.Nm ppath_retain , +.Nm ppath_release , +.\" , +.Nm ppath_lookup +.\" , +.Nd property container path library +.Sh LIBRARY +.Lb libppath +.Sh SYNOPSIS +.In ppath/ppath.h +.\" +.Ft "ppath_component_t *" +.Fn ppath_idx "unsigned int index" +.Ft "ppath_component_t *" +.Fn ppath_key "const char *key" +.\" +.Ft "ppath_component_t *" +.Fn ppath_component_retain "ppath_component_t *pc" +.Ft void +.Fn ppath_component_release "ppath_component_t *pc" +.\" +.Ft "ppath_t *" +.Fn ppath_create "void" +.Ft "unsigned int" +.Fn ppath_length "const ppath_t *p" +.Ft int +.Fn ppath_component_idx "const ppath_component_t *" +.Ft const char * +.Fn ppath_component_key "const ppath_component_t *" +.Ft "ppath_t *" +.Fn ppath_pop "ppath_t *" "ppath_component_t **" +.Ft ppath_t * +.Fn ppath_push "ppath_t *" "ppath_component_t *" +.Ft ppath_component_t * +.Fn ppath_component_at "const ppath_t *" "unsigned int" +.Ft ppath_t * +.Fn ppath_subpath "const ppath_t *" "unsigned int" "unsigned int" +.Ft ppath_t * +.Fn ppath_push_idx "ppath_t *" "unsigned int" +.Ft ppath_t * +.Fn ppath_push_key "ppath_t *" "const char *" +.Ft ppath_t * +.Fn ppath_replace_idx "ppath_t *" "unsigned int" +.Ft ppath_t * +.Fn ppath_replace_key "ppath_t *" "const char *" +.\" +.Ft ppath_t * +.Fn ppath_copy "const ppath_t *" +.Ft ppath_t * +.Fn ppath_retain "ppath_t *" +.Ft void +.Fn ppath_release "ppath_t *" +.\" +.Ft prop_object_t +.Fn ppath_lookup "prop_object_t" "const ppath_t *" +.\" +.Sh DESCRIPTION +The +.Nm +library provides functions to read, write, or delete objects in a +property list. +A property-list +.Dq path +names the object in a property list to read, write, or delete. +.Pp +A property-list path is an ordered array of zero or more array +indices and dictionary keys that names at most one +.Vt prop_object_t +in a property list. +The abstract function +.Fn E +evaluates +a property-list path against a +.Vt prop_object_t , +.Va o , +to yield a +.Vt prop_object_t +result according to the following recursive definition, where +.Fa empty +indicates the empty +.Pq zero-length +path and the operator +.Dq | +indicates the concatenation of the path on the left-hand side with +the key or index on the right-hand side: +.Bl -tag -width "E(o, p | index)" +.It Fn E "o" "empty" +Evaluates to +.Fa o . +.It Fn E "o" "p | index" +If +.Fn E "o" "p" +evaluates to a +.Vt prop_array_t , +then +.Fn E "o" "p | index" +evaluates to the +.Fa index 'th +element of that array. +Otherwise, an error occurs. +.It Fn E "o" "p | key" +If +.Fn E "o" "p" +evaluates to a +.Vt prop_dictionary_t , +then +.Fn E "o" "p | key" +evaluates to the dictionary value stored under +.Fa key . +Otherwise, an error occurs. +.El +.Pp +The programmer may think of property-list paths as working similarly +to paths in a file system, where property arrays and dictionaries +correspond to directories, and all other property types correspond +to files. +.Sh DATA TYPES +.Nm +provides two opaque types: +.Bl -tag -width ppath_component +.It Vt ppath_component_t +A property-list path component: a single key or index. +.Nm +counts references to a +.Vt ppath_component_t +and reclaims its storage when there are no more references. +.It Vt ppath_t +An array of zero or more property-list path components. +.Nm +counts references to a +.Vt ppath_t +and reclaims its storage when there are no more references. +.El +.Sh FUNCTIONS +.Nm +provides these functions for manipulating property-list paths +and their components: +.Bl -tag -width ppath +.It Fn ppath_idx "unsigned int index" +Allocate a new +.Vt ppath_component_t +for the given array index and return it. +Its reference count is initially one. +.Pp +If there is not sufficient memory to complete the request, return +.Dv NULL . +.It Fn ppath_key "const char *key" +Allocate a new +.Vt ppath_component_t +for the given dictionary key and return it. +Its reference count is initially one. +.Pp +If there is not sufficient memory to complete the request, return +.Dv NULL . +.\" +.It Fn ppath_component_retain "ppath_component_t *pc" +Increase the reference count on +.Fa pc +by one. +.It Fn ppath_component_release "ppath_component_t *pc" +Decrease the reference count on +.Fa pc +by one. +If the reference count reaches zero, reclaim the storage +for +.Fa pc . +.\" +.It Fn ppath_create "void" +Create a new property-list path and return it. +Its reference count is initially one. +The path's length is initially zero. +.Pp +If there is not sufficient memory to complete the request, return +.Dv NULL . +.It Fn ppath_length "const ppath_t *p" +Return the number of components in path +.Fa p . +.It Fn ppath_component_idx "const ppath_component_t *pc" +Return the array index represented by the component +.Fa pc , +or \-1 if +.Fa pc +does not represent an array index. +.It Fn ppath_component_key "const ppath_component_t *pc" +Return the dictionary key represented by the component +.Fa pc , +or +.Dv NULL +if +.Fa pc +does not represent a dictionary key. +.It Fn ppath_pop "ppath_t *p" "ppath_component_t **pcp" +If +.Fa p +is the empty path or +.Dv NULL , +return +.Dv NULL . +Otherwise, remove the last component from +.Fa p +and return +.Fa p , +and if +.Fa pcp +is not +.Dv NULL , +write the removed component to +.Fa "*pcp" . +.It Fn ppath_push "ppath_t *p" "ppath_component_t *pc" +If +either +.Fa p +is +.Dv NULL +or no more components can be added to +.Fa p , +return +.Dv NULL . +Otherwise, append +.Fa pc +to the end of the component array +.Fa p +and return +.Fa p . +.It Fn ppath_component_at "const ppath_t *p" "unsigned int i" +If +either +.Fa p +is +.Dv NULL +or there is no +.Fa ith +component to +.Fa p , +return +.Dv NULL . +Otherwise, return the +.Fa ith +component of +.Fa p . +Before returning a component, +.Fn ppath_component_at +increases its reference count. +(The first component is 0.) +.It Fn ppath_subpath "const ppath_t *p" "unsigned int first" "unsigned int exclast" +Create a new +.Vt ppath_t +and fill it with components +.Fa first +to +.Fa exclast +.Pq exclusive +of +.Fa p . +If there are no such components as those in +.Fa p , +.Fn ppath_subpath +returns an empty +.Vt ppath_t . +If there is insufficient memory to create the new path, or if +.Fa p +is +.Dv NULL , +return +.Dv NULL . +Otherwise, return the new path. +.It Fn ppath_push_idx "ppath_t *p" "unsigned int idx" +Append an array index, +.Fa idx , +to the end of path +.Fa p . +If +.Fa p +is +.Dv NULL , +or if there is insufficient memory to complete the operation, +return +.Dv NULL . +Otherwise, return +.Fa p . +.It Fn ppath_push_key "ppath_t *" "const char *key" +Append a dictionary key, +.Fa key , +to the end of path +.Fa p . +If +.Fa p +is +.Dv NULL , +or if there is insufficient memory to complete the operation, +return +.Dv NULL . +Otherwise, return +.Fa p . +.It Fn ppath_replace_idx "ppath_t *p" "unsigned int idx" +Replace the array index at the end of path +.Fa p +with the array index +.Fa idx . +If +.Fa p +is +.Dv NULL , +if the last component of +.Fa p +is not an array index, +or if there is insufficient memory to complete the operation, +return +.Dv NULL . +Otherwise, return +.Fa p . +.It Fn ppath_replace_key "ppath_t *p" "const char *key" +Replace the dictionary key at the end of path +.Fa p +with the dictionary key +.Fa idx . +If +.Fa p +is +.Dv NULL , +if the last component of +.Fa p +is not a dictionary key, +or if there is insufficient memory to complete the operation, +return +.Dv NULL . +Otherwise, return +.Fa p . +.\" +.It Fn ppath_copy "const ppath_t *p" +Create a copy of path +.Fa p . +If +.Fa p +is +.Dv NULL , +or if there is insufficient memory to complete the operation, +return +.Dv NULL . +Otherwise, return the copy, whose reference count will be one. +.It Fn ppath_retain "ppath_t *p" +Increase the reference count on +.Fa p +and return +.Fa p . +.It Fn ppath_release "ppath_t *p" +Decrease the reference count on +.Fa p . +Reclaim the storage for +.Fa p +if the reference count reaches zero. +.\" +.It Fn ppath_lookup "prop_object_t o" "const ppath_t *p" +Return the +.Vt prop_object_t +under +.Fa o +named by +.Fa p , +or return +.Dv NULL +if no such +.Vt prop_object_t +is under +.Fa o . +.El +.Sh SEE ALSO +.\" Cross-references should be ordered by section (low to high), then in +.\" alphabetical order. +.Xr ppath_bool 3 , +.\" .Xr ppath_data 3 , +.Xr ppath_number 3 , +.Xr ppath_object 3 , +.\" .Xr ppath_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Nm +property container path library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An David Young +.Aq dyoung@pobox.com +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man3/ppath_bool.3 b/static/netbsd/man3/ppath_bool.3 new file mode 100644 index 00000000..7e026125 --- /dev/null +++ b/static/netbsd/man3/ppath_bool.3 @@ -0,0 +1,235 @@ +.\" $NetBSD: ppath_bool.3,v 1.7 2017/10/23 00:59:44 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young <dyoung@NetBSD.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 13, 2011 +.Dt PPATH_BOOL 3 +.Os +.Sh NAME +.Nm ppath_bool , +.\" , +.Nm ppath_copydel_bool , +.Nm ppath_copyset_bool , +.Nm ppath_set_bool , +.Nm ppath_get_bool , +.Nm ppath_delete_bool +.Nd boolean property path operations +.Sh LIBRARY +.Lb libppath +.Sh SYNOPSIS +.In ppath/ppath.h +.\" +.Ft int +.Fn ppath_copydel_bool "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_bool "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "bool" +.Ft int +.Fn ppath_set_bool "prop_object_t" "const ppath_t *" "bool" +.Ft int +.Fn ppath_get_bool "prop_object_t" "const ppath_t *" "bool *" +.Ft int +.Fn ppath_delete_bool "prop_object_t" "const ppath_t *" +.Sh DESCRIPTION +The +.Nm +routines read, write, or +delete boolean values in a property list by path. +.Sh FUNCTIONS +.Nm +provides these functions for manipulating boolean values in a property list +by the values' paths: +.Bl -tag -width ppath +.It Fn ppath_copydel_bool "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" +Create a copy of the property list +.Fa o +at +.Fa *op . +Delete from the copy the +.Vt prop_bool_t +named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copydel_bool +creates a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copydel_bool +expects for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copydel_bool , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_bool +modifies a property shared by +.Fa *op +and +.Fa o , +it creates a private copy of the property for +.Fa *op . +.It Fn ppath_copyset_bool "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" "bool v" +Create a copy of the property list +.Fa o +at +.Fa *op . +In the copy, replace with +.Fa v +the +.Vt prop_bool_t +named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copyset_bool +creates a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copyset_bool +expects for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copyset_bool , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_bool +modifies a property shared by +.Fa *op +and +.Fa o , +it creates a private copy of the property for +.Fa *op . +.It Fn ppath_set_bool "prop_object_t o" "const ppath_t *p" "bool v" +Replace with +.Fa v +the +.Vt prop_bool_t +in +.Fa o +named by +.Fa p . +.It Fn ppath_get_bool "prop_object_t o" "const ppath_t *p" "bool *vp" +Retrieve the +.Vt prop_bool_t +named by +.Fa p +from +.Fa o , +and write it to +.Fa *vp . +.It Fn ppath_delete_bool "prop_object_t o" "const ppath_t *p" +Delete the +.Vt prop_bool_t +named by +.Fa p +from +.Fa o . +.Fn ppath_delete_bool +decreases by one the deleted boolean value's reference count. +.El +.\" +.\" This next request is for sections 2 and 3 function return values only. +.Sh RETURN VALUES +.Nm +routines return 0 on success, and non-zero on error. +.\" The next request is for sections 2 and 3 error and signal handling only. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFTYPE +A +.Nm +operation returns +.Er EFTYPE +when the object named by the path is not a +.Vt prop_bool_t . +.It Bq Er ENOENT +.Nm +routines return +.Er ENOENT +if the path +.Fa p +does not exist in +.Fa o . +.It Bq Er ENOMEM +.Fn ppath_set_bool , +and +.Fn ppath_copyset_bool +return +.Er ENOMEM +if there was insufficient memory to complete the operation. +.El +.Sh SEE ALSO +.\" Cross-references should be ordered by section (low to high), then in +.\" alphabetical order. +.Xr ppath 3 , +.\" .Xr ppath_data 3 , +.Xr ppath_object 3 , +.\" .Xr ppath_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Nm +property container path library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An David Young +.Aq dyoung@pobox.com +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man3/ppath_number.3 b/static/netbsd/man3/ppath_number.3 new file mode 100644 index 00000000..8850171b --- /dev/null +++ b/static/netbsd/man3/ppath_number.3 @@ -0,0 +1,280 @@ +.\" $NetBSD: ppath_number.3,v 1.5 2017/10/23 00:59:44 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young <dyoung@NetBSD.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 13, 2011 +.Dt PPATH_NUMBER 3 +.Os +.Sh NAME +.Nm ppath_number , +.\" , +.Nm ppath_copydel_int64 , +.Nm ppath_copyset_int64 , +.Nm ppath_set_int64 , +.Nm ppath_get_int64 , +.Nm ppath_delete_int64 , +.\" , +.Nm ppath_copydel_uint64 , +.Nm ppath_copyset_uint64 , +.Nm ppath_set_uint64 , +.Nm ppath_get_uint64 , +.Nm ppath_delete_uint64 +.Nd integer property path operations +.Sh LIBRARY +.Lb libppath +.Sh SYNOPSIS +.In ppath/ppath.h +.\" +.Ft int +.Fn ppath_copydel_int64 "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_int64 "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "int64_t" +.Ft int +.Fn ppath_set_int64 "prop_object_t" "const ppath_t *" "int64_t" +.Ft int +.Fn ppath_get_int64 "prop_object_t" "const ppath_t *" "int64_t *" +.Ft int +.Fn ppath_delete_int64 "prop_object_t" "const ppath_t *" +.\" +.Ft int +.Fn ppath_copydel_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_uint64 "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "uint64_t" +.Ft int +.Fn ppath_set_uint64 "prop_object_t" "const ppath_t *" "uint64_t" +.Ft int +.Fn ppath_get_uint64 "prop_object_t" "const ppath_t *" "uint64_t *" +.Ft int +.Fn ppath_delete_uint64 "prop_object_t" "const ppath_t *" +.Sh DESCRIPTION +The +.Nm +routines read, write, or +delete integers in a property list by path. +.Sh FUNCTIONS +.Nm +provides these functions for manipulating integers in a property list +by the integers' paths: +.Bl -tag -width ppath +.It Fn ppath_copydel_int64 "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" +.It Fn ppath_copydel_uint64 "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" +Create a copy of the property list +.Fa o +at +.Fa *op . +Delete from the copy the +.Vt prop_number_t +named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copydel_int64 +and +.Fn ppath_copydel_uint64 +create a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copydel_int64 +and +.Fn ppath_copydel_uint64 +expect for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copydel_int64 +and +.Fn ppath_copydel_uint64 , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_int64 +and +.Fn ppath_copydel_uint64 +modify a property shared by +.Fa *op +and +.Fa o , +they create a private copy of the property for +.Fa *op . +.It Fn ppath_copyset_int64 "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" "int64_t v" +.It Fn ppath_copyset_uint64 "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" "uint64_t v" +Create a copy of the property list +.Fa o +at +.Fa *op . +In the copy, replace with +.Fa v +the +.Vt prop_number_t +named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copyset_int64 +and +.Fn ppath_copyset_uint64 +create a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copyset_int64 +and +.Fn ppath_copyset_uint64 +expect for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copyset_int64 +and +.Fn ppath_copyset_uint64 , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_int64 +and +.Fn ppath_copydel_uint64 +modify a property shared by +.Fa *op +and +.Fa o , +they create a private copy of the property for +.Fa *op . +.It Fn ppath_set_int64 "prop_object_t o" "const ppath_t *p" "int64_t v" +.It Fn ppath_set_uint64 "prop_object_t o" "const ppath_t *" "uint64_t v" +Replace with +.Fa v +the +.Vt prop_number_t +in +.Fa o +named by +.Fa p . +.It Fn ppath_get_int64 "prop_object_t o" "const ppath_t *p" "int64_t *vp" +.It Fn ppath_get_uint64 "prop_object_t o" "const ppath_t *p" "uint64_t *vp" +Retrieve the +.Vt prop_number_t +named by +.Fa p +from +.Fa o , +and write it to +.Fa *vp . +.It Fn ppath_delete_int64 "prop_object_t o" "const ppath_t *p" +.It Fn ppath_delete_uint64 "prop_object_t o" "const ppath_t *p" +Delete the +.Vt prop_number_t +named by +.Fa p +from +.Fa o . +.Fn ppath_delete_int64 +and +.Fn ppath_delete_uint64 +decrease by one the deleted number's reference count. +.El +.\" +.\" This next request is for sections 2 and 3 function return values only. +.Sh RETURN VALUES +.Nm +routines return 0 on success, and non-zero on error. +.\" The next request is for sections 2 and 3 error and signal handling only. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFTYPE +A +.Nm +operation returns +.Er EFTYPE +when the object named by the path is not a +.Vt prop_number_t . +.It Bq Er ENOENT +.Nm +routines return +.Er ENOENT +if the path +.Fa p +does not exist in +.Fa o . +.It Bq Er ENOMEM +.Fn ppath_set_int64 , +.Fn ppath_set_uint64 , +.Fn ppath_copyset_int64 , +and +.Fn ppath_copyset_uint64 +return +.Er ENOMEM +if there was insufficient memory to complete the operation. +.El +.Sh SEE ALSO +.\" Cross-references should be ordered by section (low to high), then in +.\" alphabetical order. +.Xr ppath 3 , +.\" .Xr ppath_data 3 , +.Xr ppath_object 3 , +.\" .Xr ppath_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Nm +property container path library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An David Young +.Aq dyoung@pobox.com +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man3/ppath_object.3 b/static/netbsd/man3/ppath_object.3 new file mode 100644 index 00000000..d612bb16 --- /dev/null +++ b/static/netbsd/man3/ppath_object.3 @@ -0,0 +1,278 @@ +.\" $NetBSD: ppath_object.3,v 1.4 2017/10/23 00:59:44 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young <dyoung@NetBSD.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 24, 2011 +.Dt PPATH_OBJECT 3 +.Os +.Sh NAME +.Nm ppath_object , +.\" , +.Nm ppath_copydel_object , +.Nm ppath_copyset_object , +.Nm ppath_set_object , +.Nm ppath_get_object , +.Nm ppath_delete_object , +.\" , +.Nm ppath_copydel_data , +.Nm ppath_copyset_data , +.Nm ppath_set_data , +.Nm ppath_get_data , +.Nm ppath_dup_data , +.Nm ppath_delete_data , +.\" , +.Nm ppath_copydel_string , +.Nm ppath_copyset_string , +.Nm ppath_set_string , +.Nm ppath_get_string , +.Nm ppath_dup_string , +.Nm ppath_delete_string +.Nd property object path operations +.Sh LIBRARY +.Lb libppath +.Sh SYNOPSIS +.In ppath/ppath.h +.\" +.Ft int +.Fn ppath_copydel_object "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_object "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "prop_object_t" +.Ft int +.Fn ppath_set_object "prop_object_t" "const ppath_t *" "prop_object_t" +.Ft int +.Fn ppath_get_object "prop_object_t" "const ppath_t *" "prop_object_t *" +.Ft int +.Fn ppath_delete_object "prop_object_t" "const ppath_t *" +.\" +.Ft int +.Fn ppath_copydel_data "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_data "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "const void *" "size_t" +.Ft int +.Fn ppath_set_data "prop_object_t" "const ppath_t *" "const void *" "size_t" +.Ft int +.Fn ppath_get_data "prop_object_t" "const ppath_t *" "const void **" "size_t *" +.Ft int +.Fn ppath_dup_data "prop_object_t" "const ppath_t *" "void **" "size_t *" +.Ft int +.Fn ppath_delete_data "prop_object_t" "const ppath_t *" +.\" +.Ft int +.Fn ppath_copydel_string "prop_object_t" "prop_object_t *" "const ppath_t *" +.Ft int +.Fn ppath_copyset_string "prop_object_t" "prop_object_t *" "const ppath_t *" \ + "const char *" +.Ft int +.Fn ppath_set_string "prop_object_t" "const ppath_t *" "const char *" +.Ft int +.Fn ppath_get_string "prop_object_t" "const ppath_t *" "const char **" +.Ft int +.Fn ppath_dup_string "prop_object_t" "const ppath_t *" "char **" +.Ft int +.Fn ppath_delete_string "prop_object_t" "const ppath_t *" +.Sh DESCRIPTION +The +.Nm +routines read, write, or +delete objects in a property list by path. +.Sh FUNCTIONS +.Nm +provides these functions for manipulating objects in a property list +by the objects' paths: +.Bl -tag -width ppath +.It Fn ppath_copydel_object "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" +Create a copy of the property list +.Fa o +at +.Fa *op . +Delete from the copy the property named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copydel_object +creates a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copydel_object +expects for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copydel_object , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_object +modifies a property shared by +.Fa *op +and +.Fa o , +it creates a private copy of the property for +.Fa *op . +.It Fn ppath_copyset_object "prop_object_t o" "prop_object_t *op" \ + "const ppath_t *p" "prop_object_t v" +Create a copy of the property list +.Fa o +at +.Fa *op . +In the copy, replace with +.Fa v +the property named by +.Fa p . +.Pp +If +.Fa *op +is +.Dv NULL , +.Fn ppath_copyset_object +creates a shallow copy of +.Fa o +at +.Fa *op . +If +.Fa *op +is not +.Dv NULL , +.Fn ppath_copyset_object +expects for +.Fa *op +to be an existing shallow copy of +.Fa o . +.Pp +For the purposes of +.Fn ppath_copyset_object , +.Fa *op +is a shallow copy of property list +.Fa o +if equal properties at equal paths are shared between the two. +Before +.Fn ppath_copydel_object +modifies a property shared by +.Fa *op +and +.Fa o , +it creates a private copy of the property for +.Fa *op . +.It Fn ppath_set_object "prop_object_t o" "const ppath_t *p" "prop_object_t v" +Replace with +.Fa v +the +.Vt prop_object_t +in +.Fa o +named by +.Fa p . +.It Fn ppath_get_object "prop_object_t o" "const ppath_t *p" "prop_object_t *vp" +Retrieve the +.Vt prop_object_t +named by +.Fa p +from +.Fa o , +and write it to +.Fa *vp . +.Fn ppath_get_object +does +.Em not +increase the reference count of the retrieved object. +.It Fn ppath_delete_object "prop_object_t o" "const ppath_t *p" +Delete the +.Vt prop_object_t +named by +.Fa p +from +.Fa o . +.Fn ppath_delete_object +decreases by one the deleted object's reference count. +.El +.\" +.\" This next request is for sections 2 and 3 function return values only. +.Sh RETURN VALUES +.Nm +routines return 0 on success, and non-zero on error. +.\" The next request is for sections 2 and 3 error and signal handling only. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFTYPE +The +.Nm +call requested a +.It Bq Er ENOENT +.Fn ppath_copyset_object , +.Fn ppath_delete_object , +.Fn ppath_get_object , +and +.Fn ppath_set_object +return +.Er ENOENT +if the path +.Fa p +does not exist in +.Fa o . +.It Bq Er ENOMEM +.Fn ppath_set_object +and +.Fn ppath_copyset_object +will return +.Er ENOMEM +if there was insufficient memory to complete the operation. +.El +.Sh SEE ALSO +.\" Cross-references should be ordered by section (low to high), then in +.\" alphabetical order. +.Xr ppath 3 , +.\" .Xr ppath_data 3 , +.Xr ppath_number 3 , +.\" .Xr ppath_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Nm +property container path library first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An David Young +.Aq dyoung@pobox.com +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man3/printf.3 b/static/netbsd/man3/printf.3 new file mode 100644 index 00000000..400456a5 --- /dev/null +++ b/static/netbsd/man3/printf.3 @@ -0,0 +1,1015 @@ +.\" $NetBSD: printf.3,v 1.71 2022/04/03 14:17:53 christos Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 3, 2022 +.Dt PRINTF 3 +.Os +.Sh NAME +.Nm printf , +.Nm fprintf , +.Nm dprintf , +.Nm sprintf , +.Nm snprintf , +.Nm snprintf_ss , +.Nm asprintf , +.Nm vprintf , +.Nm vfprintf , +.Nm vsprintf , +.Nm vdprintf , +.Nm vsnprintf , +.Nm vsnprintf_ss , +.Nm vasprintf +.Nd formatted output conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn printf "const char * restrict format" ... +.Ft int +.Fn fprintf "FILE * restrict stream" "const char * restrict format" ... +.Ft int +.Fn dprintf "int fd" "const char * restrict format" ... +.Ft int +.Fn sprintf "char * restrict str" "const char * restrict format" ... +.Ft int +.Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ... +.Ft int +.Fn snprintf_ss "char * restrict str" "size_t size" "const char * restrict format" ... +.Ft int +.Fn asprintf "char ** restrict ret" "const char * restrict format" ... +.In stdarg.h +.Ft int +.Fn vprintf "const char * restrict format" "va_list ap" +.Ft int +.Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap" +.Ft int +.Fn vdprintf "int fd" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsnprintf_ss "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" +.Ft int +.Fn vasprintf "char ** restrict ret" "const char * restrict format" "va_list ap" +.Sh DESCRIPTION +The +.Fn printf +family of functions produces output according to a +.Fa format +as described below. +The +.Fn printf +and +.Fn vprintf +functions +write output to +.Em stdout , +the standard output stream; +.Fn fprintf +and +.Fn vfprintf +write output to the given output +.Fa stream ; +.Fn dprintf +and +.Fn vdprintf +write output to the given file descriptor +.Fa fd ; +.Fn sprintf , +.Fn snprintf , +.Fn snprintf_ss , +.Fn vsprintf , +.Fn vsnprintf , +and +.Fn vsnprintf_ss +write to the character string +.Fa str ; +and +.Fn asprintf +and +.Fn vasprintf +write to a dynamically allocated string that is stored in +.Fa ret . +.Pp +These functions write the output under the control of a +.Fa format +string that specifies how subsequent arguments +(or arguments accessed via the variable-length argument facilities of +.Xr stdarg 3 ) +are converted for output. +.Pp +.Fn snprintf_ss +and +.Fn vsnprintf_ss +are signal-safe standalone versions that do not handle +floating point formats, positional arguments, and wide characters. +.Pp +.Fn asprintf +and +.Fn vasprintf +set the +.Fa ret +argument to a pointer containing the formatted string. +This pointer +points to a newly allocated buffer and should be passed to +.Xr free 3 +to release the allocated storage when it is no longer needed. +If sufficient space cannot be allocated, these functions +will return \-1 and set +.Fa ret +to be a +.Dv NULL +pointer. +Please note that these functions are not standardized, and not all +implementations can be assumed to set the +.Fa ret +argument to +.Dv NULL +on error. +It is more portable to check for a return value of \-1 instead. +.Pp +.Fn snprintf , +.Fn vsnprintf , +and +.Fn vsnprintf_ss +will write at most +.Fa size Ns \-1 +of the characters printed into the output string +(the +.Fa size Ns 'th +character then gets the terminating +.Ql \e0 ) ; +if the return value is greater than or equal to the +.Fa size +argument, the string was too short +and some of the printed characters were discarded. +If +.Fa size +is zero, nothing is written and +.Fa str +may be a +.Dv NULL +pointer. +.Pp +.Fn sprintf +and +.Fn vsprintf +effectively assume an infinite +.Fa size . +.Pp +The format string is composed of zero or more directives: +ordinary +.\" multibyte +characters (not +.Cm % ) , +which are copied unchanged to the output stream; +and conversion specifications, each of which results +in fetching zero or more subsequent arguments. +Each conversion specification is introduced by +the character +.Cm % . +The arguments must correspond properly (after type promotion) +with the conversion specifier. +After the +.Cm % , +the following appear in sequence: +.Bl -bullet +.It +An optional field, consisting of a decimal digit string followed by a +.Cm $ , +specifying the next argument to access. +If this field is not provided, the argument following the last +argument accessed will be used. +Arguments are numbered starting at +.Cm 1 . +If unaccessed arguments in the format string are interspersed with ones that +are accessed the results will be indeterminate. +.It +Zero or more of the following flags: +.Bl -tag -width ".So \ Sc (space)" +.It Sq Cm # +The value should be converted to an +.Dq alternate form . +For +.Cm c , +.Cm d , +.Cm i , +.Cm n , +.Cm p , +.Cm s , +and +.Cm u +conversions, this option has no effect. +For +.Cm o +conversions, the precision of the number is increased to force the first +character of the output string to a zero (except if a zero value is printed +with an explicit precision of zero). +For +.Cm x +and +.Cm X +conversions, a non-zero result has the string +.Ql 0x +(or +.Ql 0X +for +.Cm X +conversions) prepended to it. +For +.Cm a , +.Cm A , +.Cm e , +.Cm E , +.Cm f , +.Cm F , +.Cm g , +and +.Cm G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of +those conversions only if a digit follows). +For +.Cm g +and +.Cm G +conversions, trailing zeros are not removed from the result as they +would otherwise be. +.It So Cm 0 Sc (zero) +Zero padding. +For all conversions except +.Cm n , +the converted value is padded on the left with zeros rather than blanks. +If a precision is given with a numeric conversion +.Pf ( Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +and +.Cm X ) , +the +.Cm 0 +flag is ignored. +.It Sq Cm \- +A negative field width flag; +the converted value is to be left adjusted on the field boundary. +Except for +.Cm n +conversions, the converted value is padded on the right with blanks, +rather than on the left with blanks or zeros. +A +.Sq Cm \- +overrides a +.Sq Cm \&0 +if both are given. +.It So "\ " Sc (space) +A blank should be left before a positive number +produced by a signed conversion +.Pf ( Cm a , +.Cm A +.Cm d , +.Cm e , +.Cm E , +.Cm f , +.Cm F , +.Cm g , +.Cm G , +or +.Cm i ) . +.It Sq Cm + +A sign must always be placed before a +number produced by a signed conversion. +A +.Sq Cm + +overrides a space if both are used. +.It Sq Cm ' +Decimal conversions +.Cm ( d , u , +or +.Cm i ) +or the integral portion of a floating point conversion +.Cm ( f +or +.Cm F ) +should be grouped and separated by thousands using +the non-monetary separator returned by +.Xr localeconv 3 . +.El +.It +An optional decimal digit string specifying a minimum field width. +If the converted value has fewer characters than the field width, it will +be padded with spaces on the left (or right, if the left-adjustment +flag has been given) to fill out the field width. +.It +An optional precision, in the form of a period +.Sq Cm \&. +followed by an optional digit string. +If the digit string is omitted, the precision is taken as zero. +This gives the minimum number of digits to appear for +.Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +and +.Cm X +conversions, the number of digits to appear after the decimal-point for +.Cm a , +.Cm A , +.Cm e , +.Cm E , +.Cm f , +and +.Cm F +conversions, the maximum number of significant digits for +.Cm g +and +.Cm G +conversions, or the maximum number of characters to be printed from a +string for +.Cm s +conversions. +.It +An optional length modifier, that specifies the size of the argument. +The following length modifiers are valid for the +.Cm d , i , n , o , u , x , +or +.Cm X +conversions: +.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" +.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n +.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" +.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" +.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" +.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" +.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" +.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" +.It Cm z Ta (see note) Ta Vt size_t Ta (see note) +.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" +.El +.Pp +Note: +the +.Cm t +modifier, when applied to a +.Cm o , u , x , +or +.Cm X +conversion, indicates that the argument is of an unsigned type +equivalent in size to a +.Vt ptrdiff_t . +The +.Cm z +modifier, when applied to a +.Cm d +or +.Cm i +conversion, indicates that the argument is of a signed type equivalent in +size to a +.Vt size_t . +Similarly, when applied to an +.Cm n +conversion, it indicates that the argument is a pointer to a signed type +equivalent in size to a +.Vt size_t . +.Pp +Note: +if the standard integer types described in +.Xr stdint 3 +are used, it is recommended that the predefined format string specifier +macros are used when possible. +These are further described in +.Xr inttypes 3 . +.Pp +The following length modifiers are valid for the +.Cm a , +.Cm A , +.Cm e , +.Cm E , +.Cm f , +.Cm F , +.Cm g , +or +.Cm G +conversions: +.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" +.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G +.It Cm l No (ell) Ta Vt double +(ignored, same behavior as without it) +.It Cm L Ta Vt "long double" +.El +.Pp +The following length modifier is valid for the +.Cm c +or +.Cm s +conversions: +.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" +.It Sy Modifier Ta Cm c Ta Cm s +.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" +.El +.It +A character that specifies the type of conversion to be applied. +.El +.Pp +A field width or precision, or both, may be indicated by +an asterisk +.Ql * +or an asterisk followed by one or more decimal digits and a +.Ql $ +instead of a +digit string. +In this case, an +.Vt int +argument supplies the field width or precision. +A negative field width is treated as a left adjustment flag followed by a +positive field width; a negative precision is treated as though it were +missing. +If a single format directive mixes positional +.Pq Li nn$ +and non-positional arguments, the results are undefined. +.Pp +The conversion specifiers and their meanings are: +.Bl -tag -width ".Cm diouxX" +.It Cm diouxX +The +.Vt int +(or appropriate variant) argument is converted to signed decimal +.Pf ( Cm d +and +.Cm i ) , +unsigned octal +.Pq Cm o , +unsigned decimal +.Pq Cm u , +or unsigned hexadecimal +.Pf ( Cm x +and +.Cm X ) +notation. +The letters +.Dq Li abcdef +are used for +.Cm x +conversions; the letters +.Dq Li ABCDEF +are used for +.Cm X +conversions. +The precision, if any, gives the minimum number of digits that must +appear; if the converted value requires fewer digits, it is padded on +the left with zeros. +.It Cm DOU +The +.Vt long int +argument is converted to signed decimal, unsigned octal, or unsigned +decimal, as if the format had been +.Cm ld , +.Cm lo , +or +.Cm lu +respectively. +These conversion characters are deprecated, and will eventually disappear. +.It Cm eE +The +.Vt double +argument is rounded and converted in the style +.Sm off +.Oo \- Oc Ar d Li \&. Ar ddd Li e \*[Pm] Ar dd +.Sm on +where there is one digit before the +decimal-point character +and the number of digits after it is equal to the precision; +if the precision is missing, +it is taken as 6; if the precision is +zero, no decimal-point character appears. +An +.Cm E +conversion uses the letter +.Ql E +(rather than +.Ql e ) +to introduce the exponent. +The exponent always contains at least two digits; if the value is zero, +the exponent is 00. +.Pp +For +.Cm a , +.Cm A , +.Cm e , +.Cm E , +.Cm f , +.Cm F , +.Cm g , +and +.Cm G +conversions, positive and negative infinity are represented as +.Li inf +and +.Li -inf +respectively when using the lowercase conversion character, and +.Li INF +and +.Li -INF +respectively when using the uppercase conversion character. +Similarly, NaN is represented as +.Li nan +when using the lowercase conversion, and +.Li NAN +when using the uppercase conversion. +.It Cm fF +The +.Vt double +argument is rounded and converted to decimal notation in the style +.Sm off +.Oo \- Oc Ar ddd Li \&. Ar ddd , +.Sm on +where the number of digits after the decimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as 6; if the precision is +explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.It Cm gG +The +.Vt double +argument is converted in style +.Cm f +or +.Cm e +(or in style +.Cm F +or +.Cm E +for +.Cm G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.Cm e +is used if the exponent from its conversion is less than \-4 or greater than +or equal to the precision. +Trailing zeros are removed from the fractional part of the result; a +decimal point appears only if it is followed by at least one digit. +.It Cm aA +The +.Vt double +argument is rounded and converted to hexadecimal notation in the style +.Sm off +.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \*[Pm] Oc Ar d , +.Sm on +where the number of digits after the hexadecimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as enough to represent +the floating-point number exactly, and no rounding occurs. +If the precision is zero, no hexadecimal-point character appears. +The +.Cm p +is a literal character +.Ql p , +and the exponent consists of a positive or negative sign +followed by a decimal number representing an exponent of 2. +The +.Cm A +conversion uses the prefix +.Dq Li 0X +(rather than +.Dq Li 0x ) , +the letters +.Dq Li ABCDEF +(rather than +.Dq Li abcdef ) +to represent the hex digits, and the letter +.Ql P +(rather than +.Ql p ) +to separate the significand and exponent. +.Pp +Note that there may be multiple valid ways to represent floating-point +numbers in this hexadecimal format. +For example, +.Li 0x3.24p+0 , 0x6.48p-1 +and +.Li 0xc.9p-2 +are all equivalent. +The format chosen depends on the internal representation of the +number, but the implementation guarantees that the length of the +significand will be minimized. +Zeroes are always represented with a significand of 0 (preceded by a +.Ql - +if appropriate) and an exponent of +.Li +0 . +.It Cm C +Treated as +.Cm c +with the +.Cm l +(ell) modifier. +.It Cm c +The +.Vt int +argument is converted to an +.Vt "unsigned char" , +and the resulting character is written. +.Pp +If the +.Cm l +(ell) modifier is used, the +.Vt wint_t +argument shall be converted to a +.Vt wchar_t , +and the (potentially multi-byte) sequence representing the +single wide character is written, including any shift sequences. +If a shift sequence is used, the shift state is also restored +to the original state after the character. +.It Cm S +Treated as +.Cm s +with the +.Cm l +(ell) modifier. +.It Cm s +The +.Vt "char *" +argument is expected to be a pointer to an array of character type (pointer +to a string). +Characters from the array are written up to (but not including) +a terminating +.Dv NUL +character; +if a precision is specified, no more than the number specified are +written. +If a precision is given, no null character +need be present; if the precision is not specified, or is greater than +the size of the array, the array must contain a terminating +.Dv NUL +character. +.Pp +If the +.Cm l +(ell) modifier is used, the +.Vt "wchar_t *" +argument is expected to be a pointer to an array of wide characters +(pointer to a wide string). +For each wide character in the string, the (potentially multi-byte) +sequence representing the +wide character is written, including any shift sequences. +If any shift sequence is used, the shift state is also restored +to the original state after the string. +Wide characters from the array are written up to (but not including) +a terminating wide +.Dv NUL +character; +if a precision is specified, no more than the number of bytes specified are +written (including shift sequences). +Partial characters are never written. +If a precision is given, no null character +need be present; if the precision is not specified, or is greater than +the number of bytes required to render the multibyte representation of +the string, the array must contain a terminating wide +.Dv NUL +character. +.It Cm p +The +.Vt "void *" +pointer argument is printed in hexadecimal (as if by +.Ql %#x +or +.Ql %#lx ) . +.It Cm n +The number of characters written so far is stored into the +integer indicated by the +.Vt "int *" +(or variant) pointer argument. +No argument is converted. +.It Cm % +A +.Ql % +is written. +No argument is converted. +The complete conversion specification is +.Ql %% . +.El +.Pp +The decimal point +character is defined in the program's locale (category +.Dv LC_NUMERIC ) . +.Pp +In no case does a non-existent or small field width cause truncation of +a numeric field; if the result of a conversion is wider than the field +width, the +field is expanded to contain the conversion result. +.Sh RETURN VALUES +These functions return +the number of characters printed, or that would be printed if there +was adequate space in case of +.Fn snprintf , +.Fn vsnprintf , +and +.Fn vsnprintf_ss +(not including the trailing +.Ql \e0 +used to end output to strings). +If an output error was encountered, these functions shall return a +negative value. +.Sh EXAMPLES +To print a date and time in the form +.Dq Li "Sunday, July 3, 10:02" , +where +.Fa weekday +and +.Fa month +are pointers to strings: +.Bd -literal -offset indent +#include <stdio.h> +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.Ed +.Pp +To print \*(Pi +to five decimal places: +.Bd -literal -offset indent +#include <math.h> +#include <stdio.h> +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.Ed +.Pp +To allocate a 128 byte string and print into it: +.Bd -literal -offset indent +#include <stdio.h> +#include <stdlib.h> +#include <stdarg.h> +char *newfmt(const char *fmt, ...) +{ + char *p; + va_list ap; + if ((p = malloc(128)) == NULL) + return (NULL); + va_start(ap, fmt); + (void) vsnprintf(p, 128, fmt, ap); + va_end(ap); + return (p); +} +.Ed +.Sh ERRORS +In addition to the errors documented for the +.Xr write 2 +system call, the +.Fn printf +family of functions may fail if: +.Bl -tag -width Er +.It Bq Er EILSEQ +An invalid wide-character code was encountered. +.It Bq Er ENOMEM +Insufficient storage space is available. +.It Bq Er EOVERFLOW +The +.Fa size +argument exceeds +.Dv INT_MAX , +or the return value would be too large to be represented by an +.Vt int . +.El +.Sh SEE ALSO +.Xr printf 1 , +.Xr fmtcheck 3 , +.Xr scanf 3 , +.Xr setlocale 3 , +.Xr snprintb 3 , +.Xr wprintf 3 , +.Xr printf 9 +.Sh STANDARDS +Subject to the caveats noted in the +.Sx BUGS +section below, the +.Fn fprintf , +.Fn printf , +.Fn sprintf , +.Fn vprintf , +.Fn vfprintf , +and +.Fn vsprintf +functions +conform to +.St -ansiC +and +.St -isoC-99 . +With the same reservation, the +.Fn snprintf +and +.Fn vsnprintf +functions conform to +.St -isoC-99 . +.Sh HISTORY +The functions +.Fn snprintf +and +.Fn vsnprintf +first appeared in +.Bx 4.4 . +The functions +.Fn asprintf +and +.Fn vasprintf +are modeled on the ones that first appeared in the GNU C library. +The function +.Fn vsnprintf_ss +is non-standard and appeared in +.Nx 4.0 . +The functions +.Fn dprintf +and +.Fn vdprintf +are parts of +.St -p1003.1-2008 +and appeared in +.Nx 6.0 . +.Sh CAVEATS +Because +.Fn sprintf +and +.Fn vsprintf +assume an infinitely long string, callers must be careful not to +overflow the actual space; this is often impossible to assure. +For safety, programmers should use the +.Fn snprintf +and +.Fn asprintf +family of interfaces instead. +Unfortunately, the +.Fn snprintf +interfaces are not available on older +systems and the +.Fn asprintf +interfaces are not yet portable. +.Pp +It is important never to pass a string with user-supplied data as a +format without using +.Ql %s . +An attacker can put format specifiers in the string to mangle your stack, +leading to a possible security hole. +This holds true even if you have built the string +.Dq by hand +using a function like +.Fn snprintf , +as the resulting string may still contain user-supplied conversion specifiers +for later interpolation by +.Fn printf . +.Pp +Be sure to use the proper secure idiom: +.Bd -literal -offset indent +snprintf(buffer, sizeof(buffer), "%s", string); +.Ed +.Pp +There is no way for +.Fn printf +to know the size of each argument passed. +If you use positional arguments you must ensure that all parameters, up to the +last positionally specified parameter, are used in the format string. +This allows for the format string to be parsed for this information. +Failure to do this will mean your code is non-portable and liable to fail. +.Pp +In this implementation, passing a +.Dv NULL +.Vt char * +argument to the +.Cm %s +format specifier will output +.Em "(null)" +instead of crashing. +Programs that depend on this behavior are non-portable and may crash +on other systems or in the future. +.Sh BUGS +The conversion formats +.Cm \&%D , +.Cm \&%O , +and +.Cm \&%U +are not standard and are provided only for backward compatibility. +The effect of padding the +.Cm %p +format with zeros (either by the +.Sq Cm 0 +flag or by specifying a precision), and the benign effect (i.e. none) +of the +.Sq Cm # +flag on +.Cm %n +and +.Cm %p +conversions, as well as other nonsensical combinations such as +.Cm %Ld , +are not standard; such combinations should be avoided. +.Pp +The +.Fn printf +family of functions do not correctly handle multibyte characters in the +.Fa format +argument. +.Sh SECURITY CONSIDERATIONS +The +.Fn sprintf +and +.Fn vsprintf +functions are easily misused in a manner which enables malicious users +to arbitrarily change a running program's functionality through +a buffer overflow attack. +Because +.Fn sprintf +and +.Fn vsprintf +assume an infinitely long string, +callers must be careful not to overflow the actual space; +this is often hard to assure. +For safety, programmers should use the +.Fn snprintf +interface instead. +For example: +.Bd -literal +void +foo(const char *arbitrary_string, const char *and_another) +{ + char onstack[8]; + +#ifdef BAD + /* + * This first sprintf is bad behavior. Do not use sprintf! + */ + sprintf(onstack, "%s, %s", arbitrary_string, and_another); +#else + /* + * The following two lines demonstrate better use of + * snprintf(). + */ + snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string, + and_another); +#endif +} +.Ed +.Pp +The +.Fn printf +and +.Fn sprintf +family of functions are also easily misused in a manner +allowing malicious users to arbitrarily change a running program's +functionality by either causing the program +to print potentially sensitive data +.Dq "left on the stack" , +or causing it to generate a memory fault or bus error +by dereferencing an invalid pointer. +.Pp +.Cm %n +can be used to write arbitrary data to potentially carefully-selected +addresses. +Programmers are therefore strongly advised to never pass untrusted strings +as the +.Fa format +argument, as an attacker can put format specifiers in the string +to mangle your stack, +leading to a possible security hole. +This holds true even if the string was built using a function like +.Fn snprintf , +as the resulting string may still contain user-supplied conversion specifiers +for later interpolation by +.Fn printf . +.Pp +Always use the proper secure idiom: +.Pp +.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);" diff --git a/static/netbsd/man3/printf_l.3 b/static/netbsd/man3/printf_l.3 new file mode 100644 index 00000000..7e12fd5e --- /dev/null +++ b/static/netbsd/man3/printf_l.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: printf_l.3,v 1.2 2016/12/29 20:29:30 wiz Exp $ +.\" Copyright (c) 2012 Isabell Long <issyl0@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/stdio/printf_l.3 258245 2013-11-17 02:03:45Z eadler $ +.\" +.Dd December 29, 2016 +.Dt PRINTF_L 3 +.Os +.Sh NAME +.Nm printf_l , +.Nm asprintf_l , +.Nm fprintf_l , +.Nm snprintf_l , +.Nm sprintf_l , +.Nm vasprintf_l , +.Nm vfprintf_l , +.Nm vprintf_l , +.Nm vsnprintf_l , +.Nm vsprintf_l +.Nd formatted output conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In locale.h +.Ft int +.Fn printf_l "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn asprintf_l "char **ret" "locale_t loc" "const char * format" "..." +.Ft int +.Fn fprintf_l "FILE * restrict stream" "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn snprintf_l "char * restrict str" "size_t size" "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn sprintf_l "char * restrict str" "locale_t loc" "const char * restrict format" "..." +.In stdarg.h +.Ft int +.Fn vasprintf_l "char **ret" "locale_t loc" "const char *format" "va_list ap" +.Ft int +.Fn vfprintf_l "FILE * restrict stream" "locale_t loc" "const char * restrict format" "va_list ap" +.Ft int +.Fn vprintf_l "locale_t loc" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsnprintf_l "char * restrict str" "size_t size" "locale_t loc" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsprintf_l "char * restrict str" "locale_t loc" "const char * restrict format" "va_list ap" +.Sh DESCRIPTION +The above functions are used to convert formatted output in the locale +.Fa loc . +They behave in the same way as the versions without the _l suffix, but use +the specified locale rather than the global or per-thread locale. +See the specific manual pages for more information. +.Sh SEE ALSO +.Xr printf 3 , +.Xr xlocale 3 +.Sh STANDARDS +These functions do not conform to any specific standard so they should be +considered as non-portable local extensions. +.Sh HISTORY +These functions first appeared in Darwin and were first implemented in +.Fx 9.1 +and +.Nx 7 . diff --git a/static/netbsd/man3/proc_compare.3 b/static/netbsd/man3/proc_compare.3 new file mode 100644 index 00000000..c845502d --- /dev/null +++ b/static/netbsd/man3/proc_compare.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: proc_compare.3,v 1.2 2011/10/21 12:58:53 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd October 20, 2011 +.Dt PROC_COMPARE 3 +.Os +.Sh NAME +.Nm proc_compare +.Nd compare two processes' interactivity +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In sys/sysctl.h +.Ft int +.Fn "proc_compare" "const struct kinfo_proc2 *p1" "const struct kinfo_lwp *l1" \ +"const struct kinfo_proc2 *p2" "const struct kinfo_lwp *l2" +.Sh DESCRIPTION +The +.Fn proc_compare +function compares two processes that are on the same terminal for their +interactivity. +This means that the process returned is the one that has a better chance +being the active foreground process on that tty. +This algorithm is used in the kernel for +.Dv SIGINFO +reporting and in userland by +.Xr w 1 . +.Pp +The algorithm used is as follows: +.Bl -bullet -compact -offset indent +.It +If one of them is runnable, it is preferred. +.It +If both are runnable, the one with the largest CPU percent is preferred. +.It +In a CPU percent tie, the one started more recently wins. +.It +If none are runnable, and one of them is a zombie, the non-zombie is preferred +.It +If both are zombies, the one started more recently wins. +.It +If neither is a zombie, the one with the smaller sleep time wins. +.It +In a tie, and one is sleeping in non-interruptible sleep, prefer that one. +.It +If both are in the same state, the one started more recently is preferred. +.El +In all cases where the most recently started wins, if there was no winner, +the one with the largest PID wins. +.Sh RETURN VALUES +The +.Fn proc_compare +function returns +.Dv 0 +if +.Fa p1 +is to be preferred +and +.Dv 1 +if +.Fa p2 +is to be preferred. +.Sh SEE ALSO +.Xr w 1 +.Sh HISTORY +The +.Fn proc_compare +was extracted from +.Pa src/sys/kern/tty.c +and +.Pa src/usr.bin/w/proc_compare.c +and merged in +.Nx 6.0 . diff --git a/static/netbsd/man3/prop_array.3 b/static/netbsd/man3/prop_array.3 new file mode 100644 index 00000000..0a65cfe6 --- /dev/null +++ b/static/netbsd/man3/prop_array.3 @@ -0,0 +1,265 @@ +.\" $NetBSD: prop_array.3,v 1.16 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 20, 2025 +.Dt PROP_ARRAY 3 +.Os +.Sh NAME +.Nm prop_array , +.Nm prop_array_create , +.Nm prop_array_create_with_capacity , +.Nm prop_array_copy , +.Nm prop_array_copy_mutable , +.Nm prop_array_capacity , +.Nm prop_array_count , +.Nm prop_array_ensure_capacity , +.Nm prop_array_iterator , +.Nm prop_array_make_immutable , +.Nm prop_array_mutable , +.Nm prop_array_get , +.Nm prop_array_set , +.Nm prop_array_add , +.Nm prop_array_remove , +.Nm prop_array_externalize , +.Nm prop_array_internalize , +.Nm prop_array_externalize_to_file , +.Nm prop_array_internalize_from_file , +.Nm prop_array_equals +.Nd array property collection object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_array_t +.Fn prop_array_create "void" +.Ft prop_array_t +.Fn prop_array_create_with_capacity "unsigned int capacity" +.\" +.Ft prop_array_t +.Fn prop_array_copy "prop_array_t array" +.Ft prop_array_t +.Fn prop_array_copy_mutable "prop_array_t array" +.\" +.Ft unsigned int +.Fn prop_array_capacity "prop_array_t array" +.Ft unsigned int +.Fn prop_array_count "prop_array_t array" +.Ft bool +.Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" +.\" +.Ft prop_object_iterator_t +.Fn prop_array_iterator "prop_array_t array" +.\" +.Ft void +.Fn prop_array_make_immutable "prop_array_t array" +.Ft bool +.Fn prop_array_mutable "prop_array_t array" +.\" +.Ft prop_object_t +.Fn prop_array_get "prop_array_t array" "unsigned int index" +.Ft bool +.Fn prop_array_set "prop_array_t array" "unsigned int index" "prop_object_t obj" +.Ft bool +.Fn prop_array_add "prop_array_t array" "prop_object_t obj" +.Ft void +.Fn prop_array_remove "prop_array_t array" "unsigned int index" +.\" +.Ft char * +.Fn prop_array_externalize "prop_array_t array" +.Ft prop_array_t +.Fn prop_array_internalize "const char *data" +.\" +.Ft bool +.Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" +.Ft prop_array_t +.Fn prop_array_internalize_from_file "const char *path" +.\" +.Ft bool +.Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" +.Sh DESCRIPTION +The +.Nm +family of functions operate on the array property collection object type. +An array is an ordered set; an iterated array will return objects in the +same order with which they were stored. +.Bl -tag -width "xxxxx" +.It Fn prop_array_create "void" +Create an empty array. +The array initially has no capacity. +Returns +.Dv NULL +on failure. +.It Fn prop_array_create_with_capacity "unsigned int capacity" +Create an array with the capacity to store +.Fa capacity +objects. +Returns +.Dv NULL +on failure. +.It Fn prop_array_copy "prop_array_t array" +Copy an array. +The new array has an initial capacity equal to the number of objects stored +in the array being copied. +The new array contains references to the original array's objects, not +copies of those objects +.Pq i.e. a shallow copy is made . +If the original array is immutable, the resulting array is also immutable. +Returns +.Dv NULL +on failure. +.It Fn prop_array_copy_mutable "prop_array_t array" +Like +.Fn prop_array_copy , +except the resulting array is always mutable. +.It Fn prop_array_capacity "prop_array_t array" +Returns the total capacity of the array, including objects already stored +in the array. +If the supplied object isn't an array, zero is returned. +.It Fn prop_array_count "prop_array_t array" +Returns the number of objects stored in the array. +If the supplied object isn't an array, zero is returned. +.It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity" +Ensure that the array has a total capacity of +.Fa capacity , +including objects already stored in the array. +Returns +.Dv true +if the capacity of the array is greater or equal to +.Fa capacity +or if expansion of the array's capacity was successful +and +.Dv false +otherwise. +.It Fn prop_array_iterator "prop_array_t array" +Create an iterator for the array. +The array is retained by the iterator. +An array iterator returns the object references stored in the array. +Storing to or removing from the array invalidates any active iterators for +the array. +Returns +.Dv NULL +on failure. +.It Fn prop_array_make_immutable "prop_array_t array" +Make +.Fa array +immutable. +.It Fn prop_array_mutable "prop_array_t array" +Returns +.Dv true +if the array is mutable. +.It Fn prop_array_get "prop_array_t array" "unsigned int index" +Return the object stored at the array index +.Fa index . +Returns +.Dv NULL +on failure. +.It Fn prop_array_set "prop_array_t array" "unsigned int index" \ + "prop_object_t obj" +Store a reference to the object +.Fa obj +at the array index +.Fa index . +This function is not allowed to create holes in the array; +the caller must either be setting the object just beyond the existing +count or replacing an already existing object reference. +The object will be retained by the array. +If an existing object reference is being replaced, that object will be +released. +Returns +.Dv true +if storing the object was successful and +.Dv false +otherwise. +.It Fn prop_array_add "prop_array_t array" "prop_object_t obj" +Add a reference to the object +.Fa obj +to the array, appending to the end and growing the array's capacity if +necessary. +The object will be retained by the array. +Returns +.Dv true +if storing the object was successful and +.Dv false +otherwise. +.Pp +During expansion, array's capacity is augmented by the +.Dv EXPAND_STEP +constant, as defined in +.Pa libprop/prop_array.c +file, e.g. +.Pp +.Dl #define EXPAND_STEP 16 +.It Fn prop_array_remove "prop_array_t array" "unsigned int index" +Remove the reference to the object stored at array index +.Fa index . +The object will be released and the array compacted following +the removal. +.It Fn prop_array_externalize "prop_array_t array" +This is an alias of +.Fn prop_object_externalize +provided for backwards compatibility. +.It Fn prop_array_internalize "const char *data" +This is a wrapper around +.Fn prop_object_internalize +provided for backwards compatbility. +In order to preserve previous behavior, +.Fn prop_array_internalize +will fail if the resulting object is not an array. +.It Fn prop_array_externalize_to_file "prop_array_t array" "const char *path" +This is an alias of +.Fn prop_object_externalize_to_file +provided for backwards compatibility. +.It Fn prop_array_internalize_from_file "const char *path" +This is a wrapper around +.Fn prop_object_internalize_from_file +provided for backwards compatibility. +.It Fn prop_array_equals "prop_array_t array1" "prop_array_t array2" +Returns +.Dv true +if the two arrays are equivalent. +If at least one of the supplied objects isn't an array, +.Dv false +is returned. +Note: Objects contained in the array are compared by value, not by reference. +.El +.Sh SEE ALSO +.Xr prop_array_util 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_array_util.3 b/static/netbsd/man3/prop_array_util.3 new file mode 100644 index 00000000..56c292e6 --- /dev/null +++ b/static/netbsd/man3/prop_array_util.3 @@ -0,0 +1,404 @@ +.\" $NetBSD: prop_array_util.3,v 1.13 2024/02/10 18:43:51 andvar Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_ARRAY_UTIL 3 +.Os +.Sh NAME +.Nm prop_array_util , +.Nm prop_array_get_bool , +.Nm prop_array_set_bool , +.Nm prop_array_get_schar , +.Nm prop_array_get_uchar , +.Nm prop_array_set_schar , +.Nm prop_array_set_uchar , +.Nm prop_array_get_short , +.Nm prop_array_get_ushort , +.Nm prop_array_set_short , +.Nm prop_array_set_ushort , +.Nm prop_array_get_int , +.Nm prop_array_get_uint , +.Nm prop_array_set_int , +.Nm prop_array_set_uint , +.Nm prop_array_get_long , +.Nm prop_array_get_ulong , +.Nm prop_array_set_long , +.Nm prop_array_set_ulong , +.Nm prop_array_get_longlong , +.Nm prop_array_get_ulonglong , +.Nm prop_array_set_longlong , +.Nm prop_array_set_ulonglong , +.Nm prop_array_get_intptr , +.Nm prop_array_get_uintptr , +.Nm prop_array_set_intptr , +.Nm prop_array_set_uintptr , +.Nm prop_array_get_int8 , +.Nm prop_array_get_uint8 , +.Nm prop_array_set_int8 , +.Nm prop_array_set_uint8 , +.Nm prop_array_get_int16 , +.Nm prop_array_get_uint16 , +.Nm prop_array_set_int16 , +.Nm prop_array_set_uint16 , +.Nm prop_array_get_int32 , +.Nm prop_array_get_uint32 , +.Nm prop_array_set_int32 , +.Nm prop_array_set_uint32 , +.Nm prop_array_get_int64 , +.Nm prop_array_get_uint64 , +.Nm prop_array_set_int64 , +.Nm prop_array_set_uint64 , +.Nm prop_array_get_data , +.Nm prop_array_set_data , +.Nm prop_array_set_data_nocopy , +.Nm prop_array_get_string , +.Nm prop_array_set_string , +.Nm prop_array_set_string_nocopy , +.Nm prop_array_add_schar , +.Nm prop_array_add_uchar , +.Nm prop_array_add_short , +.Nm prop_array_add_ushort , +.Nm prop_array_add_int , +.Nm prop_array_add_uint , +.Nm prop_array_add_long , +.Nm prop_array_add_ulong , +.Nm prop_array_add_longlong , +.Nm prop_array_add_ulonglong , +.Nm prop_array_add_intptr , +.Nm prop_array_add_uintptr , +.Nm prop_array_add_int8 , +.Nm prop_array_add_uint8 , +.Nm prop_array_add_int16 , +.Nm prop_array_add_uint16 , +.Nm prop_array_add_int32 , +.Nm prop_array_add_uint32 , +.Nm prop_array_add_int64 , +.Nm prop_array_add_uint64 , +.Nm prop_array_add_data , +.Nm prop_array_add_data_nocopy , +.Nm prop_array_add_string , +.Nm prop_array_add_string_nocopy , +.Nm prop_array_add_and_rel +.Nd array property collection object utility functions +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft bool +.Fn prop_array_get_bool "prop_array_t array" "unsigned int indx" \ + "bool *valp" +.Ft bool +.Fn prop_array_set_bool "prop_array_t array" "unsigned int indx" \ + "bool val" +.\" +.Ft bool +.Fn prop_array_get_schar "prop_array_t array" "unsigned int indx" \ + "signed char *valp" +.Ft bool +.Fn prop_array_get_uchar "prop_array_t array" "unsigned int indx" \ + "unsigned char *valp" +.Ft bool +.Fn prop_array_set_schar "prop_array_t array" "unsigned int indx" \ + "signed char val" +.Ft bool +.Fn prop_array_set_uchar "prop_array_t array" "unsigned int indx" \ + "unsigned char val" +.\" +.Ft bool +.Fn prop_array_get_short "prop_array_t array" "unsigned int indx" \ + "short *valp" +.Ft bool +.Fn prop_array_get_ushort "prop_array_t array" "unsigned int indx" \ + "unsigned short *valp" +.Ft bool +.Fn prop_array_set_short "prop_array_t array" "unsigned int indx" \ + "short val" +.Ft bool +.Fn prop_array_set_ushort "prop_array_t array" "unsigned int indx" \ + "unsigned short val" +.\" +.Ft bool +.Fn prop_array_get_int "prop_array_t array" "unsigned int indx" \ + "int *valp" +.Ft bool +.Fn prop_array_get_uint "prop_array_t array" "unsigned int indx" \ + "unsigned int *valp" +.Ft bool +.Fn prop_array_set_int "prop_array_t array" "unsigned int indx" \ + "int val" +.Ft bool +.Fn prop_array_set_uint "prop_array_t array" "unsigned int indx" \ + "unsigned int val" +.\" +.Ft bool +.Fn prop_array_get_long "prop_array_t array" "unsigned int indx" \ + "long *valp" +.Ft bool +.Fn prop_array_get_ulong "prop_array_t array" "unsigned int indx" \ + "unsigned long *valp" +.Ft bool +.Fn prop_array_set_long "prop_array_t array" "unsigned int indx" \ + "long val" +.Ft bool +.Fn prop_array_set_ulong "prop_array_t array" "unsigned int indx" \ + "unsigned long val" +.\" +.Ft bool +.Fn prop_array_get_longlong "prop_array_t array" "unsigned int indx" \ + "long long *valp" +.Ft bool +.Fn prop_array_get_ulonglong "prop_array_t array" "unsigned int indx" \ + "unsigned long long *valp" +.Ft bool +.Fn prop_array_set_longlong "prop_array_t array" "unsigned int indx" \ + "long long val" +.Ft bool +.Fn prop_array_set_ulonglong "prop_array_t array" "unsigned int indx" \ + "unsigned long long val" +.\" +.Ft bool +.Fn prop_array_get_intptr "prop_array_t array" "unsigned int indx" \ + "intptr_t *valp" +.Ft bool +.Fn prop_array_get_uintptr "prop_array_t array" "unsigned int indx" \ + "uintptr_t *valp" +.Ft bool +.Fn prop_array_set_intptr "prop_array_t array" "unsigned int indx" \ + "intptr_t val" +.Ft bool +.Fn prop_array_set_uintptr "prop_array_t array" "unsigned int indx" \ + "uintptr_t val" +.\" +.Ft bool +.Fn prop_array_get_int8 "prop_array_t array" "unsigned int indx" \ + "int8_t *valp" +.Ft bool +.Fn prop_array_get_uint8 "prop_array_t array" "unsigned int indx" \ + "uint8_t *valp" +.Ft bool +.Fn prop_array_set_int8 "prop_array_t array" "unsigned int indx" \ + "int8_t val" +.Ft bool +.Fn prop_array_set_uint8 "prop_array_t array" "unsigned int indx" \ + "uint8_t val" +.\" +.Ft bool +.Fn prop_array_get_int16 "prop_array_t array" "unsigned int indx" \ + "int16_t *valp" +.Ft bool +.Fn prop_array_get_uint16 "prop_array_t array" "unsigned int indx" \ + "uint16_t *valp" +.Ft bool +.Fn prop_array_set_int16 "prop_array_t array" "unsigned int indx" \ + "int16_t val" +.Ft bool +.Fn prop_array_set_uint16 "prop_array_t array" "unsigned int indx" \ + "uint16_t val" +.\" +.Ft bool +.Fn prop_array_get_int32 "prop_array_t array" "unsigned int indx" \ + "int32_t *valp" +.Ft bool +.Fn prop_array_get_uint32 "prop_array_t array" "unsigned int indx" \ + "uint32_t *valp" +.Ft bool +.Fn prop_array_set_int32 "prop_array_t array" "unsigned int indx" \ + "int32_t val" +.Ft bool +.Fn prop_array_set_uint32 "prop_array_t array" "unsigned int indx" \ + "uint32_t val" +.\" +.Ft bool +.Fn prop_array_get_int64 "prop_array_t array" "unsigned int indx" \ + "int64_t *valp" +.Ft bool +.Fn prop_array_get_uint64 "prop_array_t array" "unsigned int indx" \ + "uint64_t *valp" +.Ft bool +.Fn prop_array_set_int64 "prop_array_t array" "unsigned int indx" \ + "int64_t val" +.Ft bool +.Fn prop_array_set_uint64 "prop_array_t array" "unsigned int indx" \ + "uint64_t val" +.\" +.Ft bool +.Fn prop_array_get_data "prop_array_t array" "unsigned int indx" \ + "const void **datap" "size_t *sizep" +.Ft bool +.Fn prop_array_set_data "prop_array_t array" "unsigned int indx" \ + "const void *data" "size_t len" +.Ft bool +.Fn prop_array_set_data_nocopy "prop_array_t array" "unsigned int indx" \ + "const void *data" "size_t len" +.\" +.Ft bool +.Fn prop_array_get_string "prop_array_t array" "unsigned int indx" \ + "const char **strp" +.Ft bool +.Fn prop_array_set_string "prop_array_t array" "unsigned int indx" \ + "const char *str" +.Ft bool +.Fn prop_array_set_string_nocopy "prop_array_t array" "unsigned int indx" \ + "const char *str" +.\" +.Ft bool +.Fn prop_array_set_and_rel "prop_array_t array" "unsigned int indx" \ + "prop_object_t obj" +.\" +.Ft bool +.Fn prop_array_add_bool "prop_array_t array" "bool val" +.Ft bool +.Fn prop_array_add_schar "prop_array_t array" "signed char val" +.Ft bool +.Fn prop_array_add_uchar "prop_array_t array" "unsigned char val" +.Ft bool +.Fn prop_array_add_short "prop_array_t array" "short val" +.Ft bool +.Fn prop_array_add_ushort "prop_array_t array" "unsigned short val" +.Ft bool +.Fn prop_array_add_int "prop_array_t array" "int val" +.Ft bool +.Fn prop_array_add_uint "prop_array_t array" "unsigned int val" +.Ft bool +.Fn prop_array_add_long "prop_array_t array" "long val" +.Ft bool +.Fn prop_array_add_ulong "prop_array_t array" "unsigned long val" +.Ft bool +.Fn prop_array_add_longlong "prop_array_t array" "long long val" +.Ft bool +.Fn prop_array_add_ulonglong "prop_array_t array" "unsigned long long val" +.Ft bool +.Fn prop_array_add_intptr "prop_array_t array" "intptr_t val" +.Ft bool +.Fn prop_array_add_uintptr "prop_array_t array" "uintptr_t val" +.Ft bool +.Fn prop_array_add_int8 "prop_array_t array" "int8_t val" +.Ft bool +.Fn prop_array_add_uint8 "prop_array_t array" "uint8_t val" +.Ft bool +.Fn prop_array_add_int16 "prop_array_t array" "int16_t val" +.Ft bool +.Fn prop_array_add_uint16 "prop_array_t array" "uint16_t val" +.Ft bool +.Fn prop_array_add_int32 "prop_array_t array" "int32_t val" +.Ft bool +.Fn prop_array_add_uint32 "prop_array_t array" "uint32_t val" +.Ft bool +.Fn prop_array_add_int64 "prop_array_t array" "int64_t val" +.Ft bool +.Fn prop_array_add_uint64 "prop_array_t array" "uint64_t val" +.\" +.Ft bool +.Fn prop_array_add_data "prop_array_t array" "const void *data" \ + "size_t len" +.Ft bool +.Fn prop_array_add_data_nocopy "prop_array_t array" "const char *data" \ + "size_t len" +.\" +.Ft bool +.Fn prop_array_add_string "prop_array_t array" "const char *str" +.Ft bool +.Fn prop_array_add_string_nocopy "prop_array_t array" "const char *str" +.\" +.Ft bool +.Fn prop_array_add_and_rel "prop_array_t array" "prop_object_t obj" +.Sh DESCRIPTION +The +.Nm +family of functions are provided to make getting and setting values in +arrays more convenient in some applications. +.Pp +The getters check the type of the returned object and, in some cases, also +ensure that the returned value is within the range implied by the getter's +value type. +.Pp +The setters and adders handle object creation and release for the caller. +.Pp +If the +.Fa sizep +argument to +.Fn prop_array_get_data +is not +.Dv NULL , +then it will be set to the size of the returned data. +.Pp +The +.Fn prop_array_get_data , +.Fn prop_array_set_data_nocopy , +and +.Fn prop_array_add_data_nocopy +do not copy the data that is set or returned. +See +.Xr prop_data 3 +for more information. +.Pp +The +.Fn prop_array_get_string , +.Fn prop_array_set_string_nocopy , +and +.Fn prop_array_add_string_nocopy +do not copy the string that is set or returned. +See +.Xr prop_string 3 +for more information. +The +.Fn prop_array_set_and_rel +and +.Fn prop_array_add_and_rel +functions add the object to the array and release it. +The object is always released, even if adding it to the array fails. +.Sh RETURN VALUES +The +.Nm +getter functions return +.Dv true +if the object exists in the array and the value is in-range, or +.Dv false +otherwise. +.Pp +The +.Nm +setter and adder functions return +.Dv true +if creating the object and storing it in the array is successful, or +.Dv false +otherwise. +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_number 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_bool.3 b/static/netbsd/man3/prop_bool.3 new file mode 100644 index 00000000..afc16705 --- /dev/null +++ b/static/netbsd/man3/prop_bool.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: prop_bool.3,v 1.8 2020/06/06 21:25:59 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_BOOL 3 +.Os +.Sh NAME +.Nm prop_bool , +.Nm prop_bool_create , +.Nm prop_bool_copy , +.Nm prop_bool_true , +.Nm prop_bool_value +.Nd boolean value property object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_bool_t +.Fn prop_bool_create "bool val" +.Ft prop_bool_t +.Fn prop_bool_copy "prop_bool_t bool" +.\" +.Ft bool +.Fn prop_bool_true "prop_bool_t bool" +.Ft bool +.Fn prop_bool_value "prop_bool_t bool" +.Sh DESCRIPTION +The +.Nm +family of functions operate on a boolean value property object type. +.Bl -tag -width "xxxxx" +.It Fn prop_bool_create "bool val" +Create a boolean value object with the value +.Fa val . +.It Fn prop_bool_copy "prop_bool_t bool" +Copy a boolean value object. +If the supplied object isn't a boolean, +.Dv NULL +is returned. +.It Fn prop_bool_true "prop_bool_t bool" +.It Fn prop_bool_value "prop_bool_t bool" +Returns the value of the boolean value object. +Both functions are equivalent. +If the supplied object isn't a boolean, +.Dv false +is returned. +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_data.3 b/static/netbsd/man3/prop_data.3 new file mode 100644 index 00000000..99a7be8c --- /dev/null +++ b/static/netbsd/man3/prop_data.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: prop_data.3,v 1.10 2025/09/23 21:32:38 rillig Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_DATA 3 +.Os +.Sh NAME +.Nm prop_data , +.Nm prop_data_create_copy , +.Nm prop_data_create_nocopy , +.Nm prop_data_copy , +.Nm prop_data_size , +.Nm prop_data_value , +.Nm prop_data_copy_value , +.Nm prop_data_equals , +.Nm prop_data_equals_data +.Nd opaque data value property object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_data_t +.Fn prop_data_create_copy "const void *blob" "size_t len" +.Ft prop_data_t +.Fn prop_data_create_nocopy "const void *blob" "size_t len" +.\" +.Ft prop_data_t +.Fn prop_data_copy "prop_data_t data" +.\" +.Ft const void * +.Fn prop_data_value "prop_data_t data" +.Ft bool +.Fn prop_data_copy_value "prop_data_t data" "void *buf" "size_t buflen" +.\" +.Ft size_t +.Fn prop_data_size "prop_data_t data" +.\" +.Ft bool +.Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2" +.Ft bool +.Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len" +.Sh DESCRIPTION +The +.Nm +family of functions operate on an opaque data value property object type. +.Bl -tag -width "xxxxx" +.It Fn prop_data_create_copy "const void *blob" "size_t len" +Create a data object that contains a copy of +.Fa blob +with size +.Fa len . +Returns +.Dv NULL +on failure. +.It Fn prop_data_create_nocopy "const void *blob" "size_t len" +Similar to +.Fn prop_data_create_copy , +but is allowed to not create an internal copy of the opaque data, instead +referencing the buffer passed by the caller. +Caution must be exercised because data objects can have an indefinite +lifespan. +The caller must therefore ensure that the provided buffer reference will +also be valid indefinitely. +This is provided as a memory optimization; it is not guaranteed that +the returned data object will reference the provided buffer, and thus +callers should not rely on this behavior. +Returns +.Dv NULL +on failure. +.It Fn prop_data_copy "prop_data_t data" +Copy a data object. +If the data object being copied is an external data reference, +then the copy also references the same external data. +Returns +.Dv NULL +on failure. +.It Fn prop_data_size "prop_data_t data" +Returns the size of the data object. +If the supplied object isn't a data object, zero is returned. +.It Fn prop_data_value "prop_data_t data" +Returns a reference to the data object's buffer. +If the supplied object isn't a data object or +if the data container is empty, +.Dv NULL +is returned. +.It Fn prop_data_copy_value "prop_data_t data" "void *buf" "size_t buflen" +Copies the contents of the data object into the supplied buffer of the +specified size. +Returns +.Dv true +if the copy succeeds and +.Dv false +iff the supplied buffer is not large enough or if the object is not a +data object. +.It Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2" +Returns +.Dv true +if the two data objects are equivalent. +If at least one of the supplied objects isn't a data object, +.Dv false +is returned. +.It Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len" +Returns +.Dv true +if the data object's value is equivalent to +.Fa blob +with size +.Fa len . +If the supplied object isn't a data object, +.Dv false +is returned. +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . +Support for mutable data objects was deprecated in +.Nx 10.0 . diff --git a/static/netbsd/man3/prop_dictionary.3 b/static/netbsd/man3/prop_dictionary.3 new file mode 100644 index 00000000..764392f0 --- /dev/null +++ b/static/netbsd/man3/prop_dictionary.3 @@ -0,0 +1,308 @@ +.\" $NetBSD: prop_dictionary.3,v 1.22 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 20, 2025 +.Dt PROP_DICTIONARY 3 +.Os +.Sh NAME +.Nm prop_dictionary , +.Nm prop_dictionary_create , +.Nm prop_dictionary_create_with_capacity , +.Nm prop_dictionary_copy , +.Nm prop_dictionary_copy_mutable , +.Nm prop_dictionary_count , +.Nm prop_dictionary_ensure_capacity , +.Nm prop_dictionary_iterator , +.Nm prop_dictionary_all_keys , +.Nm prop_dictionary_make_immutable , +.Nm prop_dictionary_mutable , +.Nm prop_dictionary_get , +.Nm prop_dictionary_set , +.Nm prop_dictionary_remove , +.Nm prop_dictionary_get_keysym , +.Nm prop_dictionary_set_keysym , +.Nm prop_dictionary_remove_keysym , +.Nm prop_dictionary_externalize , +.Nm prop_dictionary_internalize , +.Nm prop_dictionary_externalize_to_file , +.Nm prop_dictionary_internalize_from_file , +.Nm prop_dictionary_equals , +.Nm prop_dictionary_keysym_value , +.Nm prop_dictionary_keysym_equals +.Nd dictionary property collection object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_dictionary_t +.Fn prop_dictionary_create "void" +.Ft prop_dictionary_t +.Fn prop_dictionary_create_with_capacity "unsigned int capacity" +.\" +.Ft prop_dictionary_t +.Fn prop_dictionary_copy "prop_dictionary_t dict" +.Ft prop_dictionary_t +.Fn prop_dictionary_copy_mutable "prop_dictionary_t dict" +.\" +.Ft unsigned int +.Fn prop_dictionary_count "prop_dictionary_t dict" +.Ft bool +.Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \ + "unsigned int capacity" +.\" +.Ft prop_object_iterator_t +.Fn prop_dictionary_iterator "prop_dictionary_t dict" +.Ft prop_array_t +.Fn prop_dictionary_all_keys "prop_dictionary_t dict" +.\" +.Ft void +.Fn prop_dictionary_make_immutable "prop_dictionary_t dict" +.Ft bool +.Fn prop_dictionary_mutable "prop_dictionary_t dict" +.\" +.Ft prop_object_t +.Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key" +.Ft bool +.Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \ + "prop_object_t obj" +.Ft void +.Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key" +.\" +.Ft prop_object_t +.Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t keysym" +.Ft bool +.Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t keysym" "prop_object_t obj" +.Ft void +.Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t keysym" +.\" +.Ft bool +.Fn prop_dictionary_equals "prop_dictionary_t dict1" "prop_dictionary_t dict2" +.\" +.Ft const char * +.Fn prop_dictionary_keysym_value "prop_dictionary_keysym_t sym" +.\" +.Ft bool +.Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \ + "prop_dictionary_keysym_t keysym2" +.\" +.Ft char * +.Fn prop_dictionary_externalize "prop_dictionary_t dict" +.Ft prop_dictionary_t +.Fn prop_dictionary_internalize "const char *data" +.\" +.Ft bool +.Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \ + "const char *path" +.Ft prop_dictionary_t +.Fn prop_dictionary_internalize_from_file "const char *path" +.\" +.Sh DESCRIPTION +The +.Nm +family of functions operate on the dictionary property collection object type. +A dictionary is an unordered set of objects stored as key-value pairs. +.Bl -tag -width "xxxxx" +.It Fn prop_dictionary_create "void" +Create an empty dictionary. +The dictionary initially has no capacity. +Returns +.Dv NULL +on failure. +.It Fn prop_dictionary_create_with_capacity "unsigned int capacity" +Create a dictionary with the capacity to store +.Fa capacity +objects. +Returns +.Dv NULL +on failure. +.It Fn prop_dictionary_copy "prop_dictionary_t dict" +Copy a dictionary. +The new dictionary has an initial capacity equal to the number of objects +stored in the dictionary being copied. +The new dictionary contains references to the original dictionary's objects, +not copies of those objects +.Pq i.e. a shallow copy is made . +If the original dictionary is immutable, the resulting dictionary is also +immutable. +.It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict" +Like +.Fn prop_dictionary_copy , +except the resulting dictionary is always mutable. +.It Fn prop_dictionary_count "prop_dictionary_t dict" +Returns the number of objects stored in the dictionary. +.It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict" \ + "unsigned int capacity" +Ensure that the dictionary has a total capacity of +.Fa capacity , +including objects already stored in the dictionary. +Returns +.Dv true +if the capacity of the dictionary is greater or equal to +.Fa capacity +or if the expansion of the dictionary's capacity was successful +and +.Dv false +otherwise. +If the supplied object isn't a dictionary, +.Dv false +is returned. +.It Fn prop_dictionary_iterator "prop_dictionary_t dict" +Create an iterator for the dictionary. +The dictionary is retained by the iterator. +A dictionary iterator returns the key symbols used to look up objects stored +in the dictionary; to get the object itself, a dictionary lookup using this +key symbol must be performed. +Storing to or removing from the dictionary invalidates any active iterators for +the dictionary. +Returns +.Dv NULL +on failure. +.It Fn prop_dictionary_all_keys "prop_dictionary_t dict" +Return an array of all of the dictionary key symbols +.Pq prop_dictionary_keysym_t +in the dictionary. +This provides a way to iterate over the items in the dictionary while +retaining the ability to mutate the dictionary; instead of iterating +over the dictionary itself, iterate over the array of keys. +The caller is responsible for releasing the array. +Returns +.Dv NULL +on failure. +.It Fn prop_dictionary_make_immutable "prop_dictionary_t dict" +Make +.Fa dict +immutable. +.It Fn prop_dictionary_mutable "prop_dictionary_t dict" +Returns +.Dv true +if the dictionary is mutable. +.It Fn prop_dictionary_get "prop_dictionary_t dict" "const char *key" +Return the object stored in the dictionary with the key +.Fa key . +If no object is stored with the specified key, +.Dv NULL +is returned. +.It Fn prop_dictionary_set "prop_dictionary_t dict" "const char *key" \ + "prop_object_t obj" +Store a reference to the object +.Fa obj +with the key +.Fa key . +The object will be retained by the dictionary. +If the key already exists in the dictionary, the object associated with +that key will be released and replaced with the new object. +Returns +.Dv true +if storing the object was successful and +.Dv false +otherwise. +.It Fn prop_dictionary_remove "prop_dictionary_t dict" "const char *key" +Remove the reference to the object stored in the dictionary with the key +.Fa key . +The object will be released. +.It Fn prop_dictionary_get_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t sym" +Like +.Fn prop_dictionary_get , +but the lookup is performed using a key symbol returned by a dictionary +iterator. +The results are undefined if the iterator used to obtain the key symbol +is not associated with +.Fa dict . +.It Fn prop_dictionary_set_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t sym" "prop_object_t obj" +Like +.Fn prop_dictionary_set , +but the lookup of the object to replace is performed using a key symbol +returned by a dictionary iterator. +The results are undefined if the iterator used to obtain the key symbol +is not associated with +.Fa dict . +.It Fn prop_dictionary_remove_keysym "prop_dictionary_t dict" \ + "prop_dictionary_keysym_t sym" +Like +.Fn prop_dictionary_remove , +but the lookup of the object to remove is performed using a key symbol +returned by a dictionary iterator. +The results are undefined if the iterator used to obtain the key symbol +is not associated with +.Fa dict . +.It Fn prop_dictionary_equals "prop_dictionary_t dict1" \ + "prop_dictionary_t dict2" +Returns +.Dv true +if the two dictionaries are equivalent. +Note: Objects contained in the dictionary are compared by value, not by +reference. +.It Fn prop_dictionary_keysym_value "prop_dictionary_keysym_t keysym" +Returns a reference to the dictionary key symbol's string value. +.It Fn prop_dictionary_keysym_equals "prop_dictionary_keysym_t keysym1" \ + "prop_dictionary_keysym_t keysym2" +Returns +.Dv true +if the two dictionary key symbols are equivalent. +.It Fn prop_dictionary_externalize "prop_dictionary_t dict" +This is an alias of +.Fn prop_object_externalize +provided for backwards compatibility. +.It Fn prop_dictionary_internalize "const char *data" +This is a wrapper around +.Fn prop_object_internalize +provided for backwards compatbility. +In order to preserve previous behavior, +.Fn prop_dictionary_internalize +will fail if the resulting object is not a dictionary. +.It Fn prop_dictionary_externalize_to_file "prop_dictionary_t dict" \ + "const char *path" +This is an alias of +.Fn prop_object_externalize_to_file +provided for backwards compatibility. +.It Fn prop_dictionary_internalize_from_file "const char *path" +This is a wrapper around +.Fn prop_object_internalize_from_file +provided for backwards compatibility. +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary_util 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_dictionary_util.3 b/static/netbsd/man3/prop_dictionary_util.3 new file mode 100644 index 00000000..56f4bd67 --- /dev/null +++ b/static/netbsd/man3/prop_dictionary_util.3 @@ -0,0 +1,330 @@ +.\" $NetBSD: prop_dictionary_util.3,v 1.10 2020/06/06 21:25:59 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_DICTIONARY_UTIL 3 +.Os +.Sh NAME +.Nm prop_dictionary_util , +.Nm prop_dictionary_get_dict , +.Nm prop_dictionary_get_bool , +.Nm prop_dictionary_set_bool , +.Nm prop_dictionary_get_schar , +.Nm prop_dictionary_get_uchar , +.Nm prop_dictionary_set_schar , +.Nm prop_dictionary_set_uchar , +.Nm prop_dictionary_get_short , +.Nm prop_dictionary_get_ushort , +.Nm prop_dictionary_set_short , +.Nm prop_dictionary_set_ushort , +.Nm prop_dictionary_get_int , +.Nm prop_dictionary_get_uint , +.Nm prop_dictionary_set_int , +.Nm prop_dictionary_set_uint , +.Nm prop_dictionary_get_long , +.Nm prop_dictionary_get_ulong , +.Nm prop_dictionary_set_long , +.Nm prop_dictionary_set_ulong , +.Nm prop_dictionary_get_longlong , +.Nm prop_dictionary_get_ulonglong , +.Nm prop_dictionary_set_longlong , +.Nm prop_dictionary_set_ulonglong , +.Nm prop_dictionary_get_intptr , +.Nm prop_dictionary_get_uintptr , +.Nm prop_dictionary_set_intptr , +.Nm prop_dictionary_set_uintptr , +.Nm prop_dictionary_get_int8 , +.Nm prop_dictionary_get_uint8 , +.Nm prop_dictionary_set_int8 , +.Nm prop_dictionary_set_uint8 , +.Nm prop_dictionary_get_int16 , +.Nm prop_dictionary_get_uint16 , +.Nm prop_dictionary_set_int16 , +.Nm prop_dictionary_set_uint16 , +.Nm prop_dictionary_get_int32 , +.Nm prop_dictionary_get_uint32 , +.Nm prop_dictionary_set_int32 , +.Nm prop_dictionary_set_uint32 , +.Nm prop_dictionary_get_int64 , +.Nm prop_dictionary_get_uint64 , +.Nm prop_dictionary_set_int64 , +.Nm prop_dictionary_set_uint64 , +.Nm prop_dictionary_get_data , +.Nm prop_dictionary_set_data , +.Nm prop_dictionary_set_data_nocopy , +.Nm prop_dictionary_get_string , +.Nm prop_dictionary_set_string , +.Nm prop_dictionary_set_string_nocopy , +.Nm prop_dictionary_set_and_rel +.Nd dictionary property collection object utility functions +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft bool +.Fn prop_dictionary_get_dict "prop_dictionary_t dict" "const char *key" \ + "prop_dictionary_t *dictp" +.Ft bool +.Fn prop_dictionary_get_bool "prop_dictionary_t dict" "const char *key" \ + "bool *valp" +.Ft bool +.Fn prop_dictionary_set_bool "prop_dictionary_t dict" "const char *key" \ + "bool val" +.\" +.Ft bool +.Fn prop_dictionary_get_schar "prop_dictionary_t dict" "const char *key" \ + "signed char *valp" +.Ft bool +.Fn prop_dictionary_get_uchar "prop_dictionary_t dict" "const char *key" \ + "unsigned char *valp" +.Ft bool +.Fn prop_dictionary_set_schar "prop_dictionary_t dict" "const char *key" \ + "signed char val" +.Ft bool +.Fn prop_dictionary_set_uchar "prop_dictionary_t dict" "const char *key" \ + "unsigned char val" +.\" +.Ft bool +.Fn prop_dictionary_get_short "prop_dictionary_t dict" "const char *key" \ + "short *valp" +.Ft bool +.Fn prop_dictionary_get_ushort "prop_dictionary_t dict" "const char *key" \ + "unsigned short *valp" +.Ft bool +.Fn prop_dictionary_set_short "prop_dictionary_t dict" "const char *key" \ + "short val" +.Ft bool +.Fn prop_dictionary_set_ushort "prop_dictionary_t dict" "const char *key" \ + "unsigned short val" +.\" +.Ft bool +.Fn prop_dictionary_get_int "prop_dictionary_t dict" "const char *key" \ + "int *valp" +.Ft bool +.Fn prop_dictionary_get_uint "prop_dictionary_t dict" "const char *key" \ + "unsigned int *valp" +.Ft bool +.Fn prop_dictionary_set_int "prop_dictionary_t dict" "const char *key" \ + "int val" +.Ft bool +.Fn prop_dictionary_set_uint "prop_dictionary_t dict" "const char *key" \ + "unsigned int val" +.\" +.Ft bool +.Fn prop_dictionary_get_long "prop_dictionary_t dict" "const char *key" \ + "long *valp" +.Ft bool +.Fn prop_dictionary_get_ulong "prop_dictionary_t dict" "const char *key" \ + "unsigned long *valp" +.Ft bool +.Fn prop_dictionary_set_long "prop_dictionary_t dict" "const char *key" \ + "long val" +.Ft bool +.Fn prop_dictionary_set_ulong "prop_dictionary_t dict" "const char *key" \ + "unsigned long val" +.\" +.Ft bool +.Fn prop_dictionary_get_longlong "prop_dictionary_t dict" "const char *key" \ + "long long *valp" +.Ft bool +.Fn prop_dictionary_get_ulonglong "prop_dictionary_t dict" "const char *key" \ + "unsigned long long *valp" +.Ft bool +.Fn prop_dictionary_set_longlong "prop_dictionary_t dict" "const char *key" \ + "long long val" +.Ft bool +.Fn prop_dictionary_set_ulonglong "prop_dictionary_t dict" "const char *key" \ + "unsigned long long val" +.\" +.Ft bool +.Fn prop_dictionary_get_intptr "prop_dictionary_t dict" "const char *key" \ + "intptr_t *valp" +.Ft bool +.Fn prop_dictionary_get_uintptr "prop_dictionary_t dict" "const char *key" \ + "uintptr_t *valp" +.Ft bool +.Fn prop_dictionary_set_intptr "prop_dictionary_t dict" "const char *key" \ + "intptr_t val" +.Ft bool +.Fn prop_dictionary_set_uintptr "prop_dictionary_t dict" "const char *key" \ + "uintptr_t val" +.\" +.Ft bool +.Fn prop_dictionary_get_int8 "prop_dictionary_t dict" "const char *key" \ + "int8_t *valp" +.Ft bool +.Fn prop_dictionary_get_uint8 "prop_dictionary_t dict" "const char *key" \ + "uint8_t *valp" +.Ft bool +.Fn prop_dictionary_set_int8 "prop_dictionary_t dict" "const char *key" \ + "int8_t val" +.Ft bool +.Fn prop_dictionary_set_uint8 "prop_dictionary_t dict" "const char *key" \ + "uint8_t val" +.\" +.Ft bool +.Fn prop_dictionary_get_int16 "prop_dictionary_t dict" "const char *key" \ + "int16_t *valp" +.Ft bool +.Fn prop_dictionary_get_uint16 "prop_dictionary_t dict" "const char *key" \ + "uint16_t *valp" +.Ft bool +.Fn prop_dictionary_set_int16 "prop_dictionary_t dict" "const char *key" \ + "int16_t val" +.Ft bool +.Fn prop_dictionary_set_uint16 "prop_dictionary_t dict" "const char *key" \ + "uint16_t val" +.\" +.Ft bool +.Fn prop_dictionary_get_int32 "prop_dictionary_t dict" "const char *key" \ + "int32_t *valp" +.Ft bool +.Fn prop_dictionary_get_uint32 "prop_dictionary_t dict" "const char *key" \ + "uint32_t *valp" +.Ft bool +.Fn prop_dictionary_set_int32 "prop_dictionary_t dict" "const char *key" \ + "int32_t val" +.Ft bool +.Fn prop_dictionary_set_uint32 "prop_dictionary_t dict" "const char *key" \ + "uint32_t val" +.\" +.Ft bool +.Fn prop_dictionary_get_int64 "prop_dictionary_t dict" "const char *key" \ + "int64_t *valp" +.Ft bool +.Fn prop_dictionary_get_uint64 "prop_dictionary_t dict" "const char *key" \ + "uint64_t *valp" +.Ft bool +.Fn prop_dictionary_set_int64 "prop_dictionary_t dict" "const char *key" \ + "int64_t val" +.Ft bool +.Fn prop_dictionary_set_uint64 "prop_dictionary_t dict" "const char *key" \ + "uint64_t val" +.\" +.Ft bool +.Fn prop_dictionary_get_cstring "prop_dictionary_t dict" "const char *key" \ + "char **strp" +.Ft bool +.Fn prop_dictionary_set_cstring "prop_dictionary_t dict" "const char *key" \ + "const char *str" +.\" +.Ft bool +.Fn prop_dictionary_get_data "prop_dictionary_t dict" \ + "const char *key" "const void **datap" "size_t *sizep" +.Ft bool +.Fn prop_dictionary_set_data "prop_dictionary_t dict" \ + "const char *key" "const void *data" "size_t len" +.Ft bool +.Fn prop_dictionary_set_data_nocopy "prop_dictionary_t dict" \ + "const char *key" "const void *data" "size_t len" +.\" +.Ft bool +.Fn prop_dictionary_get_string "prop_dictionary_t dict" \ + "const char *key" "const char **strp" +.Ft bool +.Fn prop_dictionary_set_string "prop_dictionary_t dict" \ + "const char *key" "const char *strp" +.Ft bool +.Fn prop_dictionary_set_string_nocopy "prop_dictionary_t dict" \ + "const char *key" "const char *strp" +.\" +.Ft bool +.Fn prop_dictionary_set_and_rel "prop_dictionary_t dict" \ + "const char *key" "prop_object_t obj" +.Sh DESCRIPTION +The +.Nm +family of functions are provided to make getting and setting values in +dictionaries more convenient in some applications. +.Pp +The getters check the type of the returned object and, in some cases, also +ensure that the returned value is within the range implied by the getter's +value type. +.Pp +The setters handle object creation and release for the caller. +.Pp +If the +.Fa sizep +argument to +.Fn prop_dictionary_get_data +is not +.Dv NULL , +then it will be set to the size of the returned data. +.Pp +The +.Fn prop_dictionary_get_data +and +.Fn prop_dictionary_set_data_nocopy +functions do not copy the data that is set or returned. +See +.Xr prop_data 3 +for more information. +.Pp +The +.Fn prop_dictionary_get_string +and +.Fn prop_dictionary_set_string_nocopy +functions do not copy the string that is set or returned. +See +.Xr prop_string 3 +for more information. +.Pp +The +.Fn prop_dictionary_set_and_rel +function adds the object to the dictionary and releases it. +The object is always released, even if adding it to the dictionary fails. +.Sh RETURN VALUES +The +.Nm +getter functions return +.Dv true +if the object exists in the dictionary and the value is in-range, or +.Dv false +otherwise. +.Pp +The +.Nm +setter functions return +.Dv true +if creating the object and storing it in the dictionary is successful, or +.Dv false +otherwise. +.Sh SEE ALSO +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_ingest.3 b/static/netbsd/man3/prop_ingest.3 new file mode 100644 index 00000000..c3277fc5 --- /dev/null +++ b/static/netbsd/man3/prop_ingest.3 @@ -0,0 +1,181 @@ +.\" $NetBSD: prop_ingest.3,v 1.8 2017/02/12 16:18:48 abhinav Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 21, 2008 +.Dt PROP_INGEST 3 +.Os +.Sh NAME +.Nm prop_ingest , +.Nm prop_ingest_context_alloc , +.Nm prop_ingest_context_free , +.Nm prop_ingest_context_error , +.Nm prop_ingest_context_type , +.Nm prop_ingest_context_key , +.Nm prop_ingest_context_private , +.Nm prop_dictionary_ingest +.Nd Ingest a dictionary into an arbitrary binary format +.Sh SYNOPSIS +.In prop/proplib.h +.Ft prop_ingest_context_t +.Fn prop_ingest_context_alloc "void *private" +.Ft void +.Fn prop_ingest_context_free "prop_ingest_context_t ctx" +.Ft prop_ingest_error_t +.Fn prop_ingest_context_error "prop_ingest_context_t ctx" +.Ft prop_type_t +.Fn prop_ingest_context_type "prop_ingest_context_t ctx" +.Ft const char * +.Fn prop_ingest_context_key "prop_ingest_context_t ctx" +.Ft void * +.Fn prop_ingest_context_private "prop_ingest_context_t ctx" +.Ft bool +.Fn prop_dictionary_ingest "prop_dictionary_t dict" \ + "const prop_ingest_table_entry rules[]" \ + "prop_ingest_context_t ctx" +.Pp +.Ft typedef bool +.Fn (*prop_ingest_handler_t) "prop_ingest_context_t" "prop_object_t" +.Sh DESCRIPTION +The +.Fn prop_dictionary_ingest +function provides a convenient way to convert a property list into +an arbitrary binary format or to extract values from dictionaries in a +way that is convenient to an application +.Pq for configuration files, for example . +.Pp +.Fn prop_dictionary_ingest +is driven by a table of rules provided by the application. +Each rule consists of three items: +.Bl -bullet +.It +A C string containing a key to be looked up in the dictionary. +.It +The expected property type of the object associated with the key +(or +.Dv PROP_TYPE_UNKNOWN +to specify that any type is allowed). +.It +A callback function of type +.Dv prop_ingest_handler_t +that will perform the translation for the application. +.El +.Pp +The table is constructed using a series of macros as follows: +.Bd -literal +static const prop_ingest_table_entry ingest_rules[] = { + PROP_INGEST("file-name", PROP_TYPE_STRING, ingest_filename), + PROP_INGEST("count", PROP_TYPE_NUMBER, ingest_count), + PROP_INGEST_OPTIONAL("required", PROP_TYPE_BOOL, ingest_required), + PROP_INGEST_OPTIONAL("extra", PROP_TYPE_UNKNOWN, ingest_extra), + PROP_INGEST_END +}; +.Ed +.Pp +The +.Dv PROP_INGEST +macro specifies that the key is required to be present in the dictionary. +The +.Dv PROP_INGEST_OPTIONAL +macro specifies that the presence of the key in the dictionary is optional. +The +.Dv PROP_INGEST_END +macro marks the end of the rules table. +.Pp +In each case, +.Fn prop_dictionary_ingest +looks up the rule's key in the dictionary. +If an object is present in the dictionary at that key, its type is checked +against the type specified in the rule. +A type specification of +.Dv PROP_TYPE_UNKNOWN +allows the object to be of any type. +If the object does not exist and the rule is not marked as optional, then +an error is returned. +Otherwise, the handler specified in the rule is invoked with the ingest +context and the object +(or +.Dv NULL +if the key does not exist in the dictionary). +The handler should return +.Dv false +if the value of the object is invalid to indicate failure and +.Dv true +otherwise. +.Pp +The ingest context contains several pieces of information that are +useful during the ingest process. +The context also provides specific error information should the ingest +fail. +.Bl -tag -width "xxxxx" +.It Fn prop_ingest_context_alloc "void *private" +Allocate an ingest context. +The argument +.Fa private +may be used to pass application-specific context to the ingest handlers. +Note that an ingest context can be re-used to perform multiple ingests. +Returns +.Dv NULL +on failure. +.It Fn prop_ingest_context_free "prop_ingest_context_t ctx" +Free an ingest context. +.It Fn prop_ingest_context_error "prop_ingest_context_t ctx" +Returns the code indicating the error encountered during ingest. +The following error codes are defined: +.Pp +.Bl -tag -width "PROP_INGEST_ERROR_HANDLER_FAILED" -compact +.It Dv PROP_INGEST_ERROR_NO_ERROR +No error was encountered during ingest. +.It Dv PROP_INGEST_ERROR_NO_KEY +A non-optional key was not found in the dictionary. +.It Dv PROP_INGEST_ERROR_WRONG_TYPE +An object in the dictionary was not the same type specified in the rules. +.It Dv PROP_INGEST_ERROR_HANDLER_FAILED +An object's handler returned +.Dv false . +.El +.It Fn prop_ingest_context_type "prop_ingest_context_t ctx" +Returns the type of the last object visited during an ingest. +When called by an ingest handler, it returns the type of the object +currently being processed. +.It Fn prop_ingest_context_key "prop_ingest_context_t ctx" +Returns the last dictionary key looked up during an ingest. +When called by an ingest handler, it returns the dictionary key corresponding +to the object currently being processed. +.It Fn prop_ingest_context_private "prop_ingest_context_t ctx" +Returns the private data set when the context was allocated with +.Fn prop_ingest_context_alloc . +.El +.Sh SEE ALSO +.Xr prop_dictionary 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_number.3 b/static/netbsd/man3/prop_number.3 new file mode 100644 index 00000000..83d2afd4 --- /dev/null +++ b/static/netbsd/man3/prop_number.3 @@ -0,0 +1,297 @@ +.\" $NetBSD: prop_number.3,v 1.12 2020/06/06 21:25:59 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_NUMBER 3 +.Os +.Sh NAME +.Nm prop_number , +.Nm prop_number_create_signed , +.Nm prop_number_create_unsigned , +.Nm prop_number_copy , +.Nm prop_number_size , +.Nm prop_number_unsigned , +.Nm prop_number_signed_value , +.Nm prop_number_unsigned_value , +.Nm prop_number_schar_value , +.Nm prop_number_short_value , +.Nm prop_number_int_value , +.Nm prop_number_long_value , +.Nm prop_number_longlong_value , +.Nm prop_number_intptr_value , +.Nm prop_number_int8_value , +.Nm prop_number_int16_value , +.Nm prop_number_int32_value , +.Nm prop_number_int64_value , +.Nm prop_number_uchar_value , +.Nm prop_number_ushort_value , +.Nm prop_number_uint_value , +.Nm prop_number_ulong_value , +.Nm prop_number_ulonglong_value , +.Nm prop_number_uintptr_value , +.Nm prop_number_uint8_value , +.Nm prop_number_uint16_value , +.Nm prop_number_uint32_value , +.Nm prop_number_uint64_value , +.Nm prop_number_equals , +.Nm prop_number_equals_signed , +.Nm prop_number_equals_unsigned +.Nd numeric value property object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_number_t +.Fn prop_number_create_signed "intmax_t val" +.Ft prop_number_t +.Fn prop_number_create_unsigned "uintmax_t val" +.Ft prop_number_t +.Fn prop_number_copy "prop_number_t number" +.\" +.Ft int +.Fn prop_number_size "prop_number_t number" +.Ft bool +.Fn prop_number_unsigned "prop_number_t number" +.Ft intmax_t +.Fn prop_number_signed_value "prop_number_t number" +.Ft uintmax_t +.Fn prop_number_usigned_value "prop_number_t number" +.\" +.Ft bool +.Fn prop_number_schar_value "prop_number_t number" "signed char *valp" +.Ft bool +.Fn prop_number_short_value "prop_number_t number" "short *valp" +.Ft bool +.Fn prop_number_int_value "prop_number_t number" "int *valp" +.Ft bool +.Fn prop_number_long_value "prop_number_t number" "long *valp" +.Ft bool +.Fn prop_number_longlong_value "prop_number_t number" "long long *valp" +.Ft bool +.Fn prop_number_intptr_value "prop_number_t number" "intptr_t *valp" +.Ft bool +.Fn prop_number_int8_value "prop_number_t number" "int8_t *valp" +.Ft bool +.Fn prop_number_int16_value "prop_number_t number" "int16_t *valp" +.Ft bool +.Fn prop_number_int32_value "prop_number_t number" "int32_t *valp" +.Ft bool +.Fn prop_number_int64_value "prop_number_t number" "int64_t *valp" +.\" +.Ft bool +.Fn prop_number_uchar_value "prop_number_t number" "unsigned char *valp" +.Ft bool +.Fn prop_number_ushort_value "prop_number_t number" "unsigned short *valp" +.Ft bool +.Fn prop_number_uint_value "prop_number_t number" "unsigned int *valp" +.Ft bool +.Fn prop_number_ulong_value "prop_number_t number" "unsigned long *valp" +.Ft bool +.Fn prop_number_ulonglong_value "prop_number_t number" "unsigned long long *valp" +.Ft bool +.Fn prop_number_uintptr_value "prop_number_t number" "uintptr_t *valp" +.Ft bool +.Fn prop_number_uint8_value "prop_number_t number" "uint8_t *valp" +.Ft bool +.Fn prop_number_uint16_value "prop_number_t number" "uint16_t *valp" +.Ft bool +.Fn prop_number_uint32_value "prop_number_t number" "uint32_t *valp" +.Ft bool +.Fn prop_number_uint64_value "prop_number_t number" "uint64_t *valp" +.\" +.Ft bool +.Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" +.Ft bool +.Fn prop_number_equals_signed "prop_number_t number" "intmax_t val" +.Ft bool +.Fn prop_number_equals_unsigned "prop_number_t number" "uintmax_t val" +.Sh DESCRIPTION +The +.Nm +family of functions operate on a numeric value property object type. +Values are either signed or unsigned, and promoted to the maximum size +integer type +.Pq intmax_t or uintmax_t , respectively . +.Pp +It is possible to compare number objects that differ in sign. +Such comparisons first test to see if each object is within the valid +number range of the other: +.Bl -bullet +.It +Signed numbers that are greater than or equal to 0 can be compared to +unsigned numbers. +.It +Unsigned numbers that are less than or equal to the largest signed +integer value +.Pq Dv INTMAX_MAX +can be compared to signed numbers. +.El +.Pp +Number objects have a different externalized representation depending +on their sign: +.Bl -bullet +.It +Signed numbers are externalized in base-10 +.Pq decimal . +.It +Unsigned numbers are externalized in base-16 +.Pq hexadecimal . +.El +.Pp +When numbers are internalized, the sign of the resulting number object +.Pq and thus its valid range +is determined by a set of rules evaluated in the following order: +.Bl -bullet +.It +If the first character of the number is a +.Sq - +then the number is signed. +.It +If the first two characters of the number are +.Sq 0x +then the number is unsigned. +.It +If the number value fits into the range of a signed number then the +number is signed. +.It +In all other cases, the number is unsigned. +.El +.Bl -tag -width "xxxxx" +.It Fn prop_number_create_signed "intmax_t val" +Create a numeric value object with the signed value +.Fa val . +Returns +.Dv NULL +on failure. +.It Fn prop_number_create_unsigned "uintmax_t val" +Create a numeric value object with the unsigned value +.Fa val . +Returns +.Dv NULL +on failure. +.It Fn prop_number_copy "prop_number_t number" +Copy a numeric value object. +If the supplied object isn't a numeric value, +.Dv NULL +is returned. +.It Fn prop_number_size "prop_number_t number" +Returns 8, 16, 32, or 64, representing the number of bits required to +hold the value of the object. +If the supplied object isn't a numeric value, 0 is returned. +.It Fn prop_number_unsigned "prop_number_t number" +Returns +.Dv true +if the numeric value object has an unsigned value. +.It Fn prop_number_signed_value "prop_number_t number" +Returns the signed value of the numeric value object. +If the supplied object isn't a numeric value, zero is returned. +Thus, +it is not possible to distinguish between +.Dq not a prop_number_t +and +.Dq prop_number_t has a value of 0 . +.It Fn prop_number_unsigned_value "prop_number_t number" +Returns the unsigned value of the numeric value object. +If the supplied object isn't a numeric value, zero is returned. +Thus, +it is not possible to distinguish between +.Dq not a prop_number_t +and +.Dq prop_number_t has a value of 0 . +.\" +.It Fn prop_number_schar_value "prop_number_t number" "signed char *valp" +.It Fn prop_number_short_value "prop_number_t number" "short *valp" +.It Fn prop_number_int_value "prop_number_t number" "int *valp" +.It Fn prop_number_long_value "prop_number_t number" "long *valp" +.It Fn prop_number_longlong_value "prop_number_t number" "long long *valp" +.It Fn prop_number_intptr_value "prop_number_t number" "intptr_t *valp" +.It Fn prop_number_int8_value "prop_number_t number" "int8_t *valp" +.It Fn prop_number_int16_value "prop_number_t number" "int16_t *valp" +.It Fn prop_number_int32_value "prop_number_t number" "int32_t *valp" +.It Fn prop_number_int64_value "prop_number_t number" "int64_t *valp" +.It Fn prop_number_uchar_value "prop_number_t number" "unsigned char *valp" +.It Fn prop_number_ushort_value "prop_number_t number" "unsigned short *valp" +.It Fn prop_number_uint_value "prop_number_t number" "unsigned int *valp" +.It Fn prop_number_ulong_value "prop_number_t number" "unsigned long *valp" +.It Fn prop_number_ulonglong_value "prop_number_t number" "unsigned long long *valp" +.It Fn prop_number_uintptr_value "prop_number_t number" "uintptr_t *valp" +.It Fn prop_number_uint8_value "prop_number_t number" "uint8_t *valp" +.It Fn prop_number_uint16_value "prop_number_t number" "uint16_t *valp" +.It Fn prop_number_uint32_value "prop_number_t number" "uint32_t *valp" +.It Fn prop_number_uint64_value "prop_number_t number" "uint64_t *valp" +These functions extract the numeric value as the specified type and +store it in +.Fa valp . +The value is bounds-checked against the minimum and maximum values of +the type. +If the value can be represented in the specified type, these functions +return +.Dv true . +Otherwise, they return +.Dv false . +.\" +.It Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" +Returns +.Dv true +if the two numeric value objects are equivalent. +If at least one of the supplied objects isn't a numeric value, +.Dv false +is returned. +.It Fn prop_number_equals_signed "prop_number_t number" "intmax_t val" +Returns +.Dv true +if the object's value is equivalent to the signed value +.Fa val . +If the supplied object isn't a numerical value, +.Dv false +is returned. +.It Fn prop_number_equals_unsigned "prop_number_t number" \ + "uintmax_t val" +Returns +.Dv true +if the object's value is equivalent to the unsigned value +.Fa val . +If the supplied object isn't a numerical value, +.Dv false +is returned. +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_object 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_object.3 b/static/netbsd/man3/prop_object.3 new file mode 100644 index 00000000..ee4b9482 --- /dev/null +++ b/static/netbsd/man3/prop_object.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: prop_object.3,v 1.11 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2025 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 20, 2025 +.Dt PROP_OBJECT 3 +.Os +.Sh NAME +.Nm prop_object , +.Nm prop_object_retain , +.Nm prop_object_release , +.Nm prop_object_type , +.Nm prop_object_equals , +.Nm prop_object_iterator_next , +.Nm prop_object_iterator_reset , +.Nm prop_object_iterator_release , +.Nm prop_object_externalize , +.Nm prop_object_externalize_with_format , +.Nm prop_object_externalize_to_file , +.Nm prop_object_externalize_to_file_with_format , +.Nm prop_object_internalize , +.Nm prop_object_internalize_from_file +.Nd general property container object functions +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft void +.Fn prop_object_retain "prop_object_t obj" +.Ft void +.Fn prop_object_release "prop_object_t obj" +.\" +.Ft prop_type_t +.Fn prop_object_type "prop_object_t obj" +.Ft bool +.Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2" +.\" +.Ft prop_object_t +.Fn prop_object_iterator_next "prop_object_iterator_t iter" +.Ft void +.Fn prop_object_iterator_reset "prop_object_iterator_t iter" +.Ft void +.Fn prop_object_iterator_release "prop_object_iterator_t iter" +.\" +.Ft char * +.Fn prop_object_externalize "prop_object_t obj" +.Ft char * +.Fn prop_object_externalize_with_format "prop_object_t obj" \ + "prop_format_t format" +.Ft bool +.Fn prop_object_externalize_to_file "prop_object_t obj" "const char *path" +.Ft bool +.Fn prop_object_externalize_to_file_with_format "prop_object_t obj" \ + "const char *path" "prop_format_t format" +.\" +.Ft prop_object_t +.Fn prop_object_internalize "const char *data" +.Ft prop_object_t +.Fn prop_object_internalize_from_file "const char *path" +.Sh DESCRIPTION +The +.Nm +family of functions operate on all property container object types. +.Bl -tag -width "" +.It Fn prop_object_retain "prop_object_t obj" +Increment the reference count on an object. +.It Fn prop_object_release "prop_object_t obj" +Decrement the reference count on an object. +If the last reference is dropped, the object is freed. +.It Fn prop_object_type "prop_object_t obj" +Determine the type of the object. +Objects are one of the following types: +.Pp +.Bl -tag -width "PROP_TYPE_DICT_KEYSYM" -compact +.It Dv PROP_TYPE_BOOL +Boolean value +.Pq prop_bool_t +.It Dv PROP_TYPE_NUMBER +Number +.Pq prop_number_t +.It Dv PROP_TYPE_STRING +String +.Pq prop_string_t +.It Dv PROP_TYPE_DATA +Opaque data +.Pq prop_data_t +.It Dv PROP_TYPE_ARRAY +Array +.Pq prop_array_t +.It Dv PROP_TYPE_DICTIONARY +Dictionary +.Pq prop_dictionary_t +.It Dv PROP_TYPE_DICT_KEYSYM +Dictionary key symbol +.Pq prop_dictionary_keysym_t +.El +.Pp +If +.Fa obj +is +.Dv NULL , +then +.Dv PROP_TYPE_UNKNOWN +is returned. +.It Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2" +Returns +.Dv true +if the two objects are of the same type and are equivalent. +.It Fn prop_object_iterator_next "prop_object_iterator_t iter" +Return the next object in the collection +.Pq array or dictionary +being iterated by the iterator +.Fa iter . +If there are no more objects in the collection, +.Dv NULL +is returned. +.It Fn prop_object_iterator_reset "prop_object_iterator_t iter" +Reset the iterator to the first object in the collection being iterated +by the iterator +.Fa iter . +.It Fn prop_object_iterator_release "prop_object_iterator_t iter" +Release the iterator +.Fa iter . +.It Fn prop_object_externalize "prop_object_t obj" +Externalizes an object, returning a NUL-terminated buffer containing +a representation of the object in the default format +.Pq XML property list . +The caller is responsible for freeing the returned buffer. +If converting to the external representation fails for any reason, +.Dv NULL +is returned. +.Pp +In user space, the buffer is allocated using +.Xr malloc 3 . +In the kernel, the buffer is allocated using +.Xr malloc 9 +using the malloc type +.Dv M_TEMP . +.It Fn prop_object_externalize_with_format "prop_object_t obj" \ + "prop_format_t format" +Like +.Fn prop_object_externalize , +except the output format is specified explicitly. +The following formats are supported: +.Pp +.Bl -tag -width "PROP_FORMAT_JSON" -compact +.It Dv PROP_FORMAT_JSON +RFC 8259 JSON format +.It Dv PROP_FORMAT_XML +XML property list format +.El +.It Fn prop_object_externalize_to_file "prop_object_t" \ + "const char *path" +.It Fn prop_object_externalize_to_file_with_format "prop_object_t" \ + "const char *path" "prop_format_t format" +Like +.Fn prop_object_externalize +and +.Fn prop_object_externalize_with_format , +except the external representation is written to the file specified by +.Fa path . +The file is saved with the mode +.Dv 0666 +as modified by the process's file creation mask +.Pq see Xr umask 2 +and is written atomically. +Returns +.Dv false +if externalizing the object or writing the file fails for any reason. +.It Fn prop_object_internalize "const char *data" +Parses the external representation of an object in the NUL-terminated +buffer +.Fa data +and returns the corresponding object. +The format of the external representation is detected automatically. +Returns +.Dv NULL +if parsing fails for any reason. +.It Fn prop_object_internalize_from_file "const char *path" +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_string 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_send_ioctl.3 b/static/netbsd/man3/prop_send_ioctl.3 new file mode 100644 index 00000000..fe79db98 --- /dev/null +++ b/static/netbsd/man3/prop_send_ioctl.3 @@ -0,0 +1,143 @@ +.\" $NetBSD: prop_send_ioctl.3,v 1.11 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 20, 2025 +.Dt PROP_SEND_IOCTL 3 +.Os +.Sh NAME +.Nm prop_object_send_ioctl , +.Nm prop_object_recv_ioctl , +.Nm prop_object_sendrecv_ioctl +.Nd Send and receive property lists to and from the kernel using ioctl +.Sh SYNOPSIS +.In prop/proplib.h +.Ft int +.Fn prop_object_send_ioctl "prop_object_t obj" "int fd" "unsigned long cmd" +.Ft int +.Fn prop_object_recv_ioctl "int fd" "unsigned long cmd" "prop_object_t *objp" +.Ft int +.Fn prop_object_sendrecv_ioctl "prop_object_t dict" "int fd" \ + "unsigned long cmd" "prop_object_t *objp" +.Sh DESCRIPTION +The +.Fn prop_object_send_ioctl , +.Fn prop_object_recv_ioctl , +and +.Fn prop_object_sendrecv_ioctl +functions implement the user space side of a protocol for sending property +lists to and from the kernel using +.Xr ioctl 2 . +.Pp +The functions +.Fn prop_array_send_ioctl , +.Fn prop_array_recv_ioctl , +.Fn prop_dictionary_send_ioctl , +.Fn prop_dictionary_recv_ioctl , +and +.Fn prop_dictionary_sendrecv_ioctl +are provided as wrappers around the corresponding generic object +functions for backwards compatibility. +.Sh RETURN VALUES +If successful, functions return zero. +Otherwise, an error number is returned to indicate the error. +.Sh EXAMPLES +The following +.Pq simplified +example demonstrates using +.Fn prop_object_send_ioctl +and +.Fn prop_object_recv_ioctl +in an application: +.Bd -literal +void +foo_setprops(prop_dictionary_t dict) +{ + int fd; + + fd = open("/dev/foo", O_RDWR, 0640); + if (fd == -1) + return; + + (void) prop_object_send_ioctl(dict, fd, FOOSETPROPS); + + (void) close(fd); +} + +prop_dictionary_t +foo_getprops(void) +{ + prop_object_t obj; + int fd; + + fd = open("/dev/foo", O_RDONLY, 0640); + if (fd == -1) + return (NULL); + + if (prop_object_recv_ioctl(fd, FOOGETPROPS, \*[Am]obj) != 0) + return (NULL); + + (void) close(fd); + + return (obj); +} +.Ed +.Pp +The +.Fn prop_object_sendrecv_ioctl +function combines the send and receive functionality, allowing for +ioctls that require two-way communication +.Pq for example to specify arguments for the ioctl operation . +.Sh ERRORS +.Fn prop_object_send_ioctl +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Cannot allocate memory +.El +.Pp +.Fn prop_object_recv_ioctl +will fail if: +.Bl -tag -width Er +.It Bq Er EIO +Input/output error +.El +.Pp +In addition to these, +.Xr ioctl 2 +errors may be returned. +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_dictionary 3 , +.Xr proplib 3 , +.Xr prop_copyin_ioctl 9 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_send_syscall.3 b/static/netbsd/man3/prop_send_syscall.3 new file mode 100644 index 00000000..5194699f --- /dev/null +++ b/static/netbsd/man3/prop_send_syscall.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: prop_send_syscall.3,v 1.6 2017/02/12 16:00:53 abhinav Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 17, 2011 +.Dt PROP_SEND_SYCALL 3 +.Os +.Sh NAME +.Nm prop_array_send_syscall , +.Nm prop_array_recv_syscall , +.Nm prop_dictionary_send_syscall , +.Nm prop_dictionary_recv_syscall +.Nd send and receive property lists to and from the kernel using syscalls +.Sh SYNOPSIS +.In prop/proplib.h +.Ft int +.Fn prop_array_send_syscall "prop_array_t array" "struct plistref *prefp" +.Ft int +.Fn prop_array_recv_syscall "const struct plistref *prefp" \ + "prop_array_t *arrayp" +.Ft int +.Fn prop_dictionary_send_syscall "prop_dictionary_t dict" \ + "struct plistref *prefp" +.Ft int +.Fn prop_dictionary_recv_syscall "const struct plistref *prefp" \ + "prop_dictionary_t *dictp" +.Sh DESCRIPTION +The +.Fn prop_array_send_syscall , +.Fn prop_array_recv_syscall , +.Fn prop_dictionary_send_syscall , +and +.Fn prop_dictionary_recv_syscall +functions implement the user space side of a protocol for sending property +lists to and from the kernel using +.Xr syscall 2 . +.Sh RETURN VALUES +If successful, functions return zero. +Otherwise, an error number is returned to indicate the error. +.Sh EXAMPLES +The following +.Pq simplified +example demonstrates using +.Fn prop_dictionary_send_syscall +and +.Fn prop_dictionary_recv_syscall +in an application: +.Bd -literal +void +foo_setprops(prop_dictionary_t dict) +{ + struct pref pref; + + (void) prop_dictionary_send_syscall(dict, \*[Am]pref); + (void) my_syscall_set(\*[Am]pref); + +} + +prop_dictionary_t +foo_getprops(void) +{ + prop_dictionary_t dict; + struct pref pref; + + (void) my_syscall_get(\*[Am]pref); + if (prop_dictionary_recv_syscall(\*[Am]pref, \*[Am]dict) != 0) + return (NULL); + + return (dict); +} +.Ed +.Sh ERRORS +.Fn prop_array_send_syscall +and +.Fn prop_dictionary_send_syscall +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Cannot allocate memory +.It Bq Er ENOTSUP +Not supported +.El +.Pp +.Fn prop_array_recv_syscall +and +.Fn prop_dictionary_recv_syscall +will fail if: +.Bl -tag -width Er +.It Bq Er EIO +Input/output error +.It Bq Er ENOTSUP +Not supported +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_dictionary 3 , +.Xr proplib 3 , +.Xr prop_copyin_ioctl 9 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/prop_string.3 b/static/netbsd/man3/prop_string.3 new file mode 100644 index 00000000..964faa0b --- /dev/null +++ b/static/netbsd/man3/prop_string.3 @@ -0,0 +1,174 @@ +.\" $NetBSD: prop_string.3,v 1.11 2025/04/02 00:51:15 gutteridge Exp $ +.\" +.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 2, 2020 +.Dt PROP_STRING 3 +.Os +.Sh NAME +.Nm prop_string , +.Nm prop_string_create_copy , +.Nm prop_string_create_format , +.Nm prop_string_create_nocopy , +.Nm prop_string_value , +.Nm prop_string_copy_value , +.Nm prop_string_copy , +.Nm prop_string_size , +.Nm prop_string_equals , +.Nm prop_string_equals_string , +.Nm prop_string_compare , +.Nm prop_string_compare_string +.Nd string value property object +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.\" +.Ft prop_string_t +.Fn prop_string_create_copy "const char *cstring" +.Ft prop_string_t +.Fn prop_string_create_format "const char *fmt" "..." +.Ft prop_string_t +.Fn prop_string_create_nocopy "const char *cstring" +.\" +.Ft prop_string_t +.Fn prop_string_copy "prop_string_t string" +.Ft bool +.Fn prop_string_copy_value "prop_string_t string" "char *buf" "size_t buflen" +.\" +.Ft size_t +.Fn prop_string_size "prop_string_t string" +.\" +.Ft const char * +.Fn prop_string_value "prop_string_t string" +.\" +.Ft bool +.Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" +.Ft bool +.Fn prop_string_equals_string "prop_string_t string" "const char *cstring" +.\" +.Ft int +.Fn prop_string_compare "prop_string_t str1" "prop_string_t str2" +.Ft int +.Fn prop_string_compare_string "prop_string_t string" "const char *cstring" +.Sh DESCRIPTION +The +.Nm +family of functions operate on a string value property object type. +.Bl -tag -width "xxxxx" +.It Fn prop_string_create_copy "const char *cstring" +Create a string object that contains a copy of +.Fa cstring . +Returns +.Dv NULL +on failure. +.It Fn prop_string_create_format "const char *fmt" "..." +Similar to +.Fn prop_string_create_copy , +but creates the string using the specified +.Xr printf 3 +format. +.It Fn prop_string_create_nocopy "const char *cstring" +Similar to +.Fn prop_string_create_copy , +but is allowed to not create an internal copy of the string data, instead +referencing the string data passed by the caller. +Caution must be exercised because string objects can have an indefinite +lifespan. +The caller must therefore ensure that the provided string data +reference will also be valid indefinitely. +This is provided only as a memory optimization; it is not guaranteed that +the returned string object will reference the provided string data, and +thus callers should not rely on this behavior. +Returns +.Dv NULL +on failure. +.It Fn prop_string_copy "prop_string_t string" +Copy a string object. +If the string object being copied has an external string buffer reference, +then the copy also references the same external string buffer. +Returns +.Dv NULL +on failure. +.It Fn prop_string_size "prop_string_t string" +Returns the size of the string, not including the terminating NUL; +equivalent semantics to +.Xr strlen 3 . +If the supplied object isn't a string, zero is returned. +.It Fn prop_string_value "prop_string_t string" +Returns a reference to the contents of the string as a C string. +If the supplied object isn't a string, +.Dv NULL +is returned. +.It Fn prop_string_copy_value "prop_string_t string" "void *buf" "size_t buflen" +Copies the contents of the string object including the terminating NUL +into the supplied buffer of the specified size. +Returns +.Dv true +if the copy succeeds +and +.Dv false +if the supplied buffer is not large enough or if the object is not a +string object. +.It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" +Returns +.Dv true +if the two string objects are equivalent. +.It Fn prop_string_equals_string "prop_string_t string" "const char *cstring" +Returns +.Dv true +if the string's value is equivalent to +.Fa cstring . +.It Fn prop_string_compare "prop_string_t str1" "prop_string_t str2" +Compares two strings using +.Xr strcmp 3 +semantics. +If either of the two objects are not string objects, an arbitrary +non-matching value will be returned. +.It Fn prop_string_compare_string "prop_string_t string" "const char *cstring" +Compares the a string object to the specified C string using +.Xr strcmp 3 +semantics. +If either the object is not a string object, an arbitrary +non-matching value will be returned. +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Xr proplib 3 +property container object library first appeared in +.Nx 4.0 . +Support for mutable string objects was deprecated in +.Nx 10.0 . diff --git a/static/netbsd/man3/proplib.3 b/static/netbsd/man3/proplib.3 new file mode 100644 index 00000000..b07b1341 --- /dev/null +++ b/static/netbsd/man3/proplib.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: proplib.3,v 1.10 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2025 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 20, 2025 +.Dt PROPLIB 3 +.Os +.Sh NAME +.Nm proplib +.Nd property container object library +.Sh LIBRARY +.Lb libprop +.Sh SYNOPSIS +.In prop/proplib.h +.Sh DESCRIPTION +The +.Nm +library provides an abstract interface for creating and manipulating +property lists. +Property lists have object types for boolean values, opaque data, numbers, +and strings. +Structure is provided by the array and dictionary collection types. +.Pp +Property lists can be passed across protection boundaries by translating +them to an external representation. +There are two formats availavble for external representation: +.Bl -bullet +.It +An XML document whose format is described by the following DTD: +.Bd -literal -offset indent +.Lk http://www.apple.com/DTDs/PropertyList-1.0.dtd +.Ed +.It +A JSON document whose format is described by RFC 8259. +.El +.Pp +Property container objects are reference counted. +When an object is created, its reference count is set to 1. +Any code that keeps a reference to an object, including the collection +types +.Pq arrays and dictionaries , +must +.Dq retain +the object +.Pq increment its reference count . +When that reference is dropped, the object must be +.Dq released +.Pq reference count decremented . +When an object's reference count drops to 0, it is automatically freed. +.Pp +The rules for managing reference counts are very simple: +.Bl -bullet +.It +If you create an object and do not explicitly maintain a reference to it, +you must release it. +.It +If you get a reference to an object from other code and wish to maintain +a reference to it, you must retain the object. +You are responsible for +releasing the object once you drop that reference. +.It +You must never release an object unless you create it or retain it. +.El +.Pp +Object collections may be iterated by creating a special iterator object. +Iterator objects are special; they may not be retained, and they are +released using an iterator-specific release function. +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_array_util 3 , +.Xr prop_bool 3 , +.Xr prop_data 3 , +.Xr prop_dictionary 3 , +.Xr prop_dictionary_util 3 , +.Xr prop_number 3 , +.Xr prop_object 3 , +.Xr prop_send_ioctl 3 , +.Xr prop_send_syscall 3 , +.Xr prop_string 3 +.Sh HISTORY +The +.Nm +property container object library first appeared in +.Nx 4.0 . +Support for the JSON serialization format was added in +.Nx 11.0 . +.Sh CAVEATS +.Nm +does not have a +.Sq date +object type, and thus will not parse +.Sq date +elements from an Apple XML property list. +.Pp +.Nm +does not have a +.Sq null +object type, and thus will not parse +.Sq null +elements from a JSON document. +.Pp +The +.Nm +.Sq number +object type differs from the Apple XML property list format in the following +ways: +.Bl -bullet +.It +The external representation for unsigned numbers is in base 16, not base 10. +.Nm +is able to parse base 8, base 10, and base 16 +.Sq integer +elements. +Signed numbers are represented in base 10. +.It +.Nm +does not support floating point numbers, so +.Sq real +elements from an Apple XML property list will not be parsed. +.El +.Pp +Similarly, +.Nm +does not parse floating point numbers +.Pq as described in RFC 8259 +in JSON documents. +For JSON documents, all numbers are represented in base 10. +.Pp +JSON does not have an opaque data element that is functionally equivalent +to the +.Sq data +elements in XML property lists. +As such, a property list containing +.Sq data +objects cannot be externalized into a JSON document. +.Pp +In order to facilitate use of +.Nm +in kernel, standalone, and user space environments, the +.Nm +parser is not a real XML parser. +It is hard-coded to parse only the property list external representation. diff --git a/static/netbsd/man3/pset.3 b/static/netbsd/man3/pset.3 new file mode 100644 index 00000000..2f0b876c --- /dev/null +++ b/static/netbsd/man3/pset.3 @@ -0,0 +1,277 @@ +.\" $NetBSD: pset.3,v 1.15 2025/02/21 15:33:58 wiz Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 21, 2025 +.Dt PSET 3 +.Os +.Sh NAME +.Nm pset_create , +.Nm pset_assign , +.Nm pset_bind , +.Nm pset_destroy +.Nd processor sets +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In sys/pset.h +.Ft int +.Fn pset_create "psetid_t *psid" +.Ft int +.Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid" +.Ft int +.Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid" +.Ft int +.Fn pset_destroy "psetid_t psid" +.Sh DESCRIPTION +The processor sets API provides the possibility to exclusively +dedicate specific processors or groups of processors to processes +or threads. +After processes or threads are bound to a group of processors by +the API, the group henceforth runs only those processes or threads. +This section describes the functions used to control processor sets. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pset_create psid +Creates a processor set, and returns its ID into +.Fa psid . +.It Fn pset_assign psid cpu opsid +Assigns the processor specified by +.Fa cpuid +to the processor set specified by +.Fa psid . +Stores the current processor set ID of the processor or +.Dv PS_NONE +into +.Fa opsid , +if the pointer is not +.Dv NULL . +.Pp +The following actions can be specified: +.Bl -enum -offset 2n +.It +If +.Fa psid +is set to +.Dv PS_QUERY , +then the current processor set ID will be returned into +.Fa psid , +and no assignment will be performed. +.It +If +.Fa psid +is set to +.Dv PS_MYID , +then the processor set ID of the calling process will be used, and +.Fa psid +will be ignored. +.It +If +.Fa psid +is set to +.Dv PS_NONE , +any assignment to the processor will be cleared. +.El +.It Fn pset_bind psid type id opsid +Dedicates the processor set specified by +.Fa psid +to the target specified by +.Fa id . +The current processor set ID to which the target is bound or +.Dv PS_NONE +will be returned in +.Fa opsid , +if the pointer is not +.Dv NULL . +.Nx +supports the following types of targets specified by +.Fa type : +.Bl -tag -width P_LWPID -offset 2n +.It Dv P_PID +Process identified by the PID. +.It Dv P_LWPID +Thread of the calling process identified by the LID. +.El +.Pp +The following actions can be specified: +.Bl -enum -offset 2n +.It +If +.Fa psid +is set to +.Dv PS_QUERY , +then the current processor set ID to which the target is bound or +.Dv PS_NONE +will be returned in +.Fa opsid , +and no binding will be performed. +.It +If +.Fa psid +is set to +.Dv PS_MYID , +then the processor set ID of the calling process will be used. +.It +If +.Fa psid +is set to +.Dv PS_NONE , +the specified target will be unbound from the processor set. +.El +.It Fn pset_destroy psid +Destroys the processor set specified by +.Fa psid . +Before destroying the processor set, all related assignments of the +processors will be cleared, and all bound threads will be unbound. +.Pp +If +.Fa psid +is +.Dv PS_MYID , +the processor set ID of the caller thread will be used. +.El +.Sh IMPLEMENTATION NOTES +Except for +.Dv PS_QUERY +operations, these interfaces require super-user privileges. +.Pp +The +.Fn pset_bind +function can return the current processor set ID to which the +target is bound, or +.Dv PS_NONE . +However, for example, the process may have many threads, which could be +bound to different processor sets. +In such a case it is unspecified which thread will be used to return +the information. +.Pp +There is an alternative thread affinity interface, see +.Xr affinity 3 . +However, processor sets and thread affinity are mutually exclusive, +hence mixing of these interfaces is prohibited. +.Sh RETURN VALUES +Upon successful completion these functions return 0. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Sh EXAMPLES +An example of code fragment, which assigns the CPU whose ID is 0, +for current process: +.Bd -literal + psetid_t psid; + cpuid_t ci = 0; + + if (pset_create(&psid) < 0) + err(EXIT_FAILURE, "pset_create"); + + /* Assign CPU 0 to the processor-set */ + if (pset_assign(psid, ci, NULL) < 0) + err(EXIT_FAILURE, "pset_assign"); + + /* Bind the current process to the processor-set */ + if (pset_bind(psid, P_PID, P_MYID, NULL) < 0) + err(EXIT_FAILURE, "pset_bind"); + + /* + * At this point, CPU 0 runs only the current process. + */ + perform_work(); + + if (pset_destroy(psid) < 0) + err(EXIT_FAILURE, "pset_destroy"); +.Ed +.Sh ERRORS +The +.Fn pset_create +function fails if: +.Bl -tag -width Er +.It Bq Er ENOMEM +No memory is available for creation of the processor set, or limit +of the allowed count of the processor sets was reached. +.It Bq Er EPERM +The calling process is not the super-user. +.El +.Pp +The +.Fn pset_assign +function fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +Another operation is performing on the processor set. +.It Bq Er EINVAL +.Fa psid +or +.Fa cpuid +are invalid. +.It Bq Er EPERM +The calling process is not the super-user, and +.Fa psid +is not +.Dv PS_QUERY . +.El +.Pp +The +.Fn pset_bind +function fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +Another operation is performing on the processor set. +.It Bq Er EINVAL +.Fa psid +or +.Fa type +are invalid. +.It Bq Er EPERM +The calling process is not the super-user, and +.Fa psid +is not +.Dv PS_QUERY . +.It Bq Er ESRCH +The specified target was not found. +.El +.Pp +The +.Fn pset_destroy +function fails if: +.Bl -tag -width Er +.It Bq Er EBUSY +Another operation is performing on the processor set. +.It Bq Er EPERM +The calling process is not the super-user. +.El +.Sh SEE ALSO +.Xr affinity 3 , +.Xr cpuset 3 , +.Xr sched 3 , +.Xr schedctl 8 +.Sh STANDARDS +This API is expected to be compatible with the APIs found in Solaris and +HP-UX operating systems. +.Sh HISTORY +The processor sets appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/psignal.3 b/static/netbsd/man3/psignal.3 new file mode 100644 index 00000000..05e5922f --- /dev/null +++ b/static/netbsd/man3/psignal.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: psignal.3,v 1.17 2010/08/27 08:38:41 christos Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)psignal.3 8.2 (Berkeley) 2/27/95 +.\" +.Dd August 27, 2010 +.Dt PSIGNAL 3 +.Os +.Sh NAME +.Nm psignal , +.Nm psiginfo , +.Nm sys_siglist , +.Nm sys_signame +.Nd system signal messages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft void +.Fn psignal "int sig" "const char *s" +.Fn psiginfo "const siginfo_t *si" "const char *s" +.Vt extern const char * const sys_siglist[]; +.Vt extern const char * const sys_signame[]; +.Sh DESCRIPTION +The +.Fn psignal +function locates the descriptive message +string for the given signal number +.Fa sig +and writes it to the standard error. +.Pp +If the argument +.Fa s +is +.Pf non- Dv NULL +it is written to the standard error file descriptor +prior to the message string, +immediately followed by a colon and a space. +If the signal number is not recognized +.Pq Xr sigaction 2 , +the string +.Dq "Unknown signal" +is produced. +.Pp +The +.Fn psiginfo +function produces the same output as the +.Fn psignal +function, only it uses the signal number information from the +.Fa si +argument. +.Pp +The message strings can be accessed directly using the external array +.Va sys_siglist , +indexed by recognized signal numbers. +The external array +.Va sys_signame +is used similarly and contains short, upper-case abbreviations for signals +which are useful for recognizing signal names in user input. +The defined variable +.Dv NSIG +contains a count of the strings in +.Va sys_siglist +and +.Va sys_signame . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr perror 3 , +.Xr setlocale 3 , +.Xr strsignal 3 +.Sh HISTORY +The +.Fn psignal +function appeared in +.Bx 4.2 . +The +.Fn psiginfo +function appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/pthread.3 b/static/netbsd/man3/pthread.3 new file mode 100644 index 00000000..096b864d --- /dev/null +++ b/static/netbsd/man3/pthread.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: pthread.3,v 1.18 2017/10/23 01:03:23 wiz Exp $ +.\" +.\" Copyright (c) 2003, 2007, 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Hubert Feyrer <hubertf@NetBSD.org> and Thomas Klausner <wiz@NetBSD.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 22, 2016 +.Dt PTHREAD 3 +.Os +.Sh NAME +.Nm pthread +.Nd POSIX Threads Library +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Pp +.Nm cc +.Op Ar flags +.Ar files +.Fl lpthread +.Op Ar libraries +.Sh DESCRIPTION +The +.Nm +library provides an implementation of the standard POSIX threads +library. +.Pp +The +.Nx +implementation is based on 1:1 thread model, therefore each +.Nm +has a kernel thread, called a light-weight process (LWP). +.Pp +Note that the system private thread interfaces upon which the +.Nm +library is built are subject to change without notice. +In order to remain compatible with future +.Nx +releases, programs must be linked against the dynamic version of the +thread library. +Statically linked programs using the POSIX +threads framework may not work when run on a future version of the system. +.Sh FUNCTIONS +The following functions comprise the core of the +.Nm +library: +.Bl -column -offset indent "pthread_barrier_destroy(3)" "XXX" +.It Sy Function Ta Sy Description +.It Xr pthread_attr 3 Ta thread attribute operations +.It Xr pthread_barrier_destroy 3 Ta destroy a barrier +.It Xr pthread_barrier_init 3 Ta create a barrier +.It Xr pthread_barrier_wait 3 Ta wait for a barrier +.It Xr pthread_barrierattr 3 Ta barrier attribute operations +.It Xr pthread_cancel 3 Ta cancel the execution of a thread +.It Xr pthread_cleanup_push 3 Ta add or remove cleanup functions +.It Xr pthread_cond_broadcast 3 Ta unblock one or more threads +.It Xr pthread_cond_destroy 3 Ta destroy a condition variable +.It Xr pthread_cond_init 3 Ta create a condition variable +.It Xr pthread_cond_wait 3 Ta wait for a condition variable +.It Xr pthread_condattr 3 Ta condition attribute operations +.It Xr pthread_create 3 Ta create a new thread +.It Xr pthread_detach 3 Ta detach a thread +.It Xr pthread_equal 3 Ta compare thread identifiers +.It Xr pthread_exit 3 Ta terminate the calling thread +.It Xr pthread_getspecific 3 Ta get a thread-specific data value +.It Xr pthread_join 3 Ta wait for thread termination +.It Xr pthread_key_create 3 Ta thread-specific data key creation +.It Xr pthread_key_delete 3 Ta delete a thread-specific data key +.It Xr pthread_kill 3 Ta send a signal to a specific thread +.It Xr pthread_mutex_destroy 3 Ta free a mutex +.It Xr pthread_mutex_init 3 Ta create a mutex +.It Xr pthread_mutex_lock 3 Ta acquire a lock on a mutex +.It Xr pthread_mutex_unlock 3 Ta unlock a mutex +.It Xr pthread_mutexattr 3 Ta mutex attribute operations +.It Xr pthread_once 3 Ta dynamic package initialization +.It Xr pthread_rwlock_destroy 3 Ta destroy a read/write lock +.It Xr pthread_rwlock_init 3 Ta initialize a read/write lock +.It Xr pthread_rwlock_rdlock 3 Ta acquire a read/write lock for reading +.It Xr pthread_rwlock_unlock 3 Ta release a read/write lock +.It Xr pthread_rwlock_wrlock 3 Ta acquire a read/write lock for writing +.It Xr pthread_rwlockattr 3 Ta read/write lock attribute operations +.It Xr pthread_schedparam 3 Ta thread scheduling manipulation +.It Xr pthread_self 3 Ta get the ID of the calling thread +.It Xr pthread_setspecific 3 Ta get a thread-specific data value +.It Xr pthread_sigmask 3 Ta manipulate a thread's signal mask +.It Xr pthread_spin_destroy 3 Ta destroy a spin lock +.It Xr pthread_spin_init 3 Ta initialize a spin lock +.It Xr pthread_spin_lock 3 Ta acquire a spin lock +.It Xr pthread_spin_unlock 3 Ta release a spin lock +.It Xr pthread_testcancel 3 Ta set cancelability state +.El +.Sh ENVIRONMENT +The following environment variables affect the behavior of the library: +.Bl -tag -width "XXX" +.It Ev PTHREAD_DIAGASSERT +Possible values are any combinations of: +.Pp +.Bl -tag -width "X " -offset 1n -compact +.It Em A +Report errors to application by error return, but do not abort. +.It Em a +Abort on errors, creating a core dump for further debugging. +.It Em E +Do not log errors to stdout. +.It Em e +Log errors to stdout. +.It Em L +Do not log errors via +.Xr syslogd 8 . +.It Em l +Log errors via +.Xr syslogd 8 . +.El +.Pp +If not set in the environment, the +.Nm +library behaves as if +.Em AEL +has been specified. +.It Ev PTHREAD_STACKSIZE +Integer value giving the stack size in kilobytes. +This allows to set a smaller stack size than the default stack size. +The default stack size is the current limit on the stack size as +set with the shell's command to change limits +.Ic ( limit +for +.Xr csh 1 , +or +.Ic ulimit +for +.Xr sh 1 ) . +.El +.Sh SEE ALSO +.Rs +.%A David R. Butenhof +.%T Programming with POSIX(R) Threads +.%D 1997 +.%I Addison-Wesley +.Re +.Sh STANDARDS +The +.Nm +library conforms to +.St -p1003.1-2001 . +.Sh CAVEATS +Due to limitations in the current pthread implementation, +.Xr makecontext 3 +and +.Xr sigaltstack 2 +should not be used in programs which link against the +.Nm +library (whether threads are used or not). diff --git a/static/netbsd/man3/pthread_atfork.3 b/static/netbsd/man3/pthread_atfork.3 new file mode 100644 index 00000000..b29f414d --- /dev/null +++ b/static/netbsd/man3/pthread_atfork.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: pthread_atfork.3,v 1.7 2014/07/19 14:58:50 wiz Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Nathan J. Williams. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 18, 2014 +.Dt PTHREAD_ATFORK 3 +.Os +.Sh NAME +.Nm pthread_atfork +.Nd register handlers to be called when process forks +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_atfork "void (*prepare)(void)" "void (*parent)(void)" "void (*child)(void)" +.Sh DESCRIPTION +The +.Fn pthread_atfork +function registers the provided handler functions to be called when the +.Xr fork 2 +function is called. +Each of the three handlers is called at a different place in the +.Xr fork 2 +sequence. +The +.Ar prepare +handler is called in the parent process before the fork happens, the +.Ar parent +handler is called in the parent process after the fork has happened, and the +.Ar child +handler is called in the child process after the fork has happened. +The +.Ar parent +and +.Ar child +handlers are called in the order in which they were registered, while the +.Ar prepare +handlers are called in reverse of the order in which they were registered. +.Pp +Any of the handlers given may be +.Dv NULL . +.Pp +The intended use of +.Fn pthread_atfork +is to provide a consistent state to a child process from a multithreaded parent +process where locks may be acquired and released asynchronously with respect to the +.Xr fork 2 +call. +Each subsystem with locks that are used in a child process should register +handlers with +.Fn pthread_atfork +that acquires those locks in the +.Ar prepare +handler and releases them in the +.Ar parent +handler. +.Sh RETURN VALUES +The +.Fn pthread_atfork +function returns 0 on success and an error number on failure. +.Sh ERRORS +The following error code may be returned: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to register the fork handlers. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr pthread_mutex 3 , +.Xr signal 7 +.Sh STANDARDS +The +.Fn pthread_atfork +function conforms to +.St -p1003.1c-95 . +.Sh HISTORY +The +.Fn pthread_atfork +function first appeared in +.Nx 2.0 . +.Sh CAVEATS +After calling +.Xr fork 2 +from a multithreaded process, it is only safe to call +async-signal-safe functions until calling one of the +.Xr exec 3 +functions. +The +.Fn pthread_* +functions are not async-signal-safe, so it is not safe to use such functions +in the +.Ar child +handler. +POSIX does not mandate that +.Fn pthread_mutex_unlock +be async-signal-safe, but it is in +.Nx +and thus safe to use within the +.Ar child +handler. +.Sh BUGS +There is no way to unregister a handler registered with +.Fn pthread_atfork . diff --git a/static/netbsd/man3/pthread_attr.3 b/static/netbsd/man3/pthread_attr.3 new file mode 100644 index 00000000..50fc82da --- /dev/null +++ b/static/netbsd/man3/pthread_attr.3 @@ -0,0 +1,156 @@ +.\" $NetBSD: pthread_attr.3,v 1.23 2026/04/23 08:24:54 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_attr.3,v 1.11 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_ATTR 3 +.Os +.Sh NAME +.Nm pthread_attr_init , +.Nm pthread_attr_destroy +.Nd thread attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_init "pthread_attr_t *attr" +.Ft int +.Fn pthread_attr_destroy "pthread_attr_t *attr" +.Sh DESCRIPTION +Thread attributes are used to specify parameters to +.Fn pthread_create . +One attribute object can be used in multiple calls to +.Fn pthread_create , +with or without modifications between the calls. +The +.Vt pthread_attr_t +type is an opaque representation of the thread attributes; +any access to the object other than via the described +.Fn pthread_attr_* +functions may result in undefined behavior. +.Pp +The +.Fn pthread_attr_init +function initializes +.Fa attr +with the default thread attributes used in the implementation. +Depending on the implementation, undefined behavior may follow +if an uninitialized thread attribute object is used with some of +the thread attribute functions. +It is therefore a good practice to always use +.Fn pthread_attr_init , +even if this might be unnecessary. +Undefined behavior may also follow if an already initialized +.Fa attr +is used with +.Fn pthread_attr_init . +.Pp +When the attribute object is no longer needed, +it should be destroyed by using +.Fn pthread_attr_destroy . +The function has no effect on threads that +were created by using a given attribute object. +A destroyed +.Fa attr +can be reinitialized using +.Fn pthread_attr_init , +but all other actions with the destroyed object are unspecified. +.Pp +The following standard thread attribute functions are available: +.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX" +.It Sy Function Ta Sy Description +.It Xr pthread_attr_getdetachstate 3 Ta thread detach state +.It Xr pthread_attr_getguardsize 3 Ta thread guard size +.It Xr pthread_attr_getinheritsched 3 Ta inherit scheduler attribute +.It Xr pthread_attr_getschedparam 3 Ta thread scheduling parameter +.It Xr pthread_attr_getschedpolicy 3 Ta thread scheduling policy +.It Xr pthread_attr_getscope 3 Ta thread contention scope +.It Xr pthread_attr_getstack 3 Ta thread stack +.It Xr pthread_attr_getstacksize 3 Ta thread stack size +.It Xr pthread_attr_getstackaddr 3 Ta thread stack address +.El +.Pp +Each listed +.Fn pthread_attr_get* +function has a +.Fn pthread_attr_set* +counterpart. +In addition, the following +.Nx +specific extensions are available: +.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX" +.It Sy Function Ta Sy Description +.It Xr pthread_attr_get_np 3 Ta attributes of a running thread +.It Xr pthread_attr_getname_np 3 Ta descriptive name of an attribute +.El +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_init +and +.Fn pthread_attr_destroy . +.Sh SEE ALSO +.Xr pthread_attr_get_np 3 , +.Xr pthread_create 3 , +.Xr pthread_join 3 +.Sh STANDARDS +Both +.Fn pthread_attr_init +and +.Fn pthread_attr_destroy +conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_attr_get_np.3 b/static/netbsd/man3/pthread_attr_get_np.3 new file mode 100644 index 00000000..cbd0bc29 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_get_np.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: pthread_attr_get_np.3,v 1.5 2017/10/22 15:44:21 abhinav Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 6, 2010 +.Dt PTHREAD_ATTR_GET_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_get_np , +.Nm pthread_getattr_np +.Nd get attributes of existing thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_get_np "pthread_t thread" "pthread_attr_t *attr" +.Ft int +.Fn pthread_getattr_np "pthread_t thread" "pthread_attr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_attr_get_np +and +.Fn pthread_getattr_np +functions can be used to retrieve attributes of a running +.Fa thread . +The result is stored to +.Fa attr . +.Pp +For +.Fn pthread_attr_get_np +.Fa attr +should be initialized prior to the call by using +.Xr pthread_attr_init 3 . +.Fn pthread_getattr_np +does this automatically. +.Pp +For both functions +.Fa attr +should be freed when it is not in use anymore with +.Xr pthread_attr_destroy 3 . +.Pp +Most fields of +.Fa attr +are the same ones provided during thread creation time as a parameter to +.Xr pthread_create 3 . +The exceptions include: +.Bl -bullet -offset indent +.It +The detach state -- a joinable thread +may have detached itself after the creation. +.It +The guard size, which may vary if the application +has allocated its own thread stack. +.It +The stack address and size; +.Fn pthread_attr_get_np +will always return the thread's real stack address and size, +regardless of the values in the original attributes structure. +.El +.Pp +The returned +.Vt pthread_attr_t +structure is supposed to be used in conjunction with the +.Fn pthread_attr_get* +functions to retrieve individual values from the structure. +When the returned +.Fa attr +is no longer needed, it should be destroyed by using +.Xr pthread_attr_destroy 3 . +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_attr_get_np +and +.Fn pthread_getattr_np +return 0. +Otherwise an error number is returned to indicate the error. +.Sh COMPATIBILITY +The +.Fn pthread_attr_get_np +and +.Fn pthread_getattr_np +functions are non-standard extensions. +.Sh ERRORS +The +.Fn pthread_attr_get_np +and +.Fn pthread_getattr_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory. +.It Bq Er ESRCH +Non-existent +.Fa thread . +.El +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_attr 3 diff --git a/static/netbsd/man3/pthread_attr_getdetachstate.3 b/static/netbsd/man3/pthread_attr_getdetachstate.3 new file mode 100644 index 00000000..b47fb597 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getdetachstate.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: pthread_attr_getdetachstate.3,v 1.4 2017/10/23 01:03:23 wiz Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_attr.3,v 1.11 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_ATTR_GETDETACHSTATE 3 +.Os +.Sh NAME +.Nm pthread_attr_getdetachstate , +.Nm pthread_attr_setdetachstate +.Nd get and set the +.Dq detach state +attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Sh DESCRIPTION +The attribute parameters for the +.Fn pthread_attr_getdetachstate +and +.Fn pthread_attr_setdetachstate +functions are mutually exclusive and must be one of: +.Bl -tag -width PTHREAD_CREATE_DETACHED -offset 2n +.It Dv PTHREAD_CREATE_JOINABLE +The threads must explicitly be waited for using the +.Xr pthread_join 3 +function once they exit for their status to be received and their resources +to be freed. +This is the default. +.It Dv PTHREAD_CREATE_DETACHED +The thread's resources will automatically be freed once the thread exits, +and the thread will not be joined. +.El +.Pp +If the thread is created as detached, +it is an error to use the thread ID with +.Xr pthread_detach 3 +or +.Xr pthread_join 3 . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_getdetachstate . +.Pp +The +.Fn pthread_attr_setdetachstate +function should fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa detachstate +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_detach 3 , +.Xr pthread_join 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_attr_getguardsize.3 b/static/netbsd/man3/pthread_attr_getguardsize.3 new file mode 100644 index 00000000..58972222 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getguardsize.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: pthread_attr_getguardsize.3,v 1.6 2023/12/07 16:55:01 riastradh Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 2, 2017 +.Dt PTHREAD_ATTR_GETGUARDSIZE 3 +.Os +.Sh NAME +.Nm pthread_attr_getguardsize , +.Nm pthread_attr_setguardsize +.Nd get and set thread guard size +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getguardsize \ +"const pthread_attr_t * restrict attr" "size_t * restrict guardsize" +.Ft int +.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" +.Sh DESCRIPTION +The +.Fn pthread_attr_getguardsize +and +.Fn pthread_attr_setguardsize +functions get and set +.Fa guardsize +in the +.Fa attr +object. +If +.Fa guardsize +is larger than 0, the system reserves +an additional region of guarded memory of at least +.Fa guardsize +bytes at the end of the thread's stack for each new thread created by using +.Fa attr . +.Pp +The guarded area is understood to be pages of memory +that are protected from read and write access. +While the guarded area should be rounded by the system page size, +the actual default size is implementation-defined. +In +.Nx +the default +.Fa guardsize +is given by the +.Pa vm.thread_guard_size +.Xr sysctl 7 . +.Pp +The rationale behind +.Fa guardsize +is two-fold: +.Bl -enum -offset 2n +.It +On the one hand, it provides protection against overflow of the stack pointer. +If there is a guard area and a thread overflows its +stack pointer into this extra memory area, it should receive a +.Dv SIGSEGV +signal or experience other comparable fatal error condition. +Note that if a thread allocates large data structures on stack, +it may be necessary to raise the default +.Fa guardsize +in order to detect stack overflows. +.It +On the other hand, the overflow protection may waste system resources +if an application that creates a large number of threads knows that it +will never overflow the stack. +In this case it is possible to set +.Fa guardsize +to 0. +.El +.Pp +If +.Xr pthread_attr_setstack 3 +or +.Xr pthread_attr_setstackaddr 3 +is used to set the stack address attribute in +.Fa attr , +the guard size attribute is ignored and no guard area will be allocated; +it is the responsibility of the application to handle the overflow conditions. +.Sh RETURN VALUES +If successful, both functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_getguardsize . +.Pp +The +.Fn pthread_attr_setguardsize +may fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_attr_setstack 3 , +.Xr sysconf 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2008 . +.Sh BUGS +Older versions of +.Nx , +prior to 10.0, 9.4, and 8.3, incorrectly adjust the stack address by +the guard size in threads configured with +.Xr pthread_attr_setstack 3 , +instead of ignoring the guard size in that case as +.Tn POSIX +prescribes +.Po +see +.Lk https://gnats.NetBSD.org/57721 "PR lib/57721" +.Pc . +.Pp +Even if you didn't set a nonzero guard size with +.Fn pthread_attr_setguardsize , +the system will choose a nonzero default guard size. +.Pp +To work around this in applications that run on older and newer +versions of +.Nx , +as well as on other operating systems, you can safely set the guard +size to zero: +.Dl "pthread_attr_setguardsize(&attr, 0);" diff --git a/static/netbsd/man3/pthread_attr_getinheritsched.3 b/static/netbsd/man3/pthread_attr_getinheritsched.3 new file mode 100644 index 00000000..bf7fa593 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getinheritsched.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: pthread_attr_getinheritsched.3,v 1.5 2025/02/27 06:27:35 andvar Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 10, 2013 +.Dt PTHREAD_ATTR_GETINHERITSCHED 3 +.Os +.Sh NAME +.Nm pthread_attr_getinheritsched , +.Nm pthread_attr_setinheritsched +.Nd get and set +.Dq inheritsched +attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getinheritsched \ +"const pthread_attr_t * restrict attr" "int * restrict inheritsched" +.Ft int +.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" +.Sh DESCRIPTION +The +.Fn pthread_attr_getinheritsched +and +.Fn pthread_attr_setinheritsched +functions get and set, respectively, the inherit scheduler attribute, +.Fa inheritsched , +in the +.Fa attr +object. +The +.Fa inheritsched +parameter specifies whether a thread created by using +.Fa attr +will obtain its scheduling attributes directly from +.Fa attr +or whether it will inherit these from the calling thread. +.Pp +Two values are possible for +.Fa inheritsched : +.Bl -tag -width PTHREAD_EXPLICIT_SCHED -offset indent +.It Dv PTHREAD_INHERIT_SCHED +The thread scheduling attributes will be +inherited from the creating thread and the ones in +.Fa attr +are ignored. +.It Dv PTHREAD_EXPLICIT_SCHED +The thread scheduling attributes will be set to the corresponding values in +.Fa attr . +.El +.Pp +The following thread scheduling attributes are affected by +.Fa inheritsched : +.Bl -bullet -offset indent +.It +Scheduling policy; see +.Xr pthread_attr_setschedpolicy 3 . +.It +Scheduling parameter; see +.Xr pthread_attr_getschedparam 3 . +.It +Scheduling contention scope; see +.Xr pthread_attr_getscope 3 . +.El +.Sh RETURN VALUES +If successful, both functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh COMPATIBILITY +The standard leaves it unspecified which (if any) is the default +inherit scheduler attribute in a newly initialized attribute object. +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_getinheritsched . +.Pp +The +.Fn pthread_attr_setinheritsched +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa inheritsched +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/pthread_attr_getname_np.3 b/static/netbsd/man3/pthread_attr_getname_np.3 new file mode 100644 index 00000000..b9b79a79 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getname_np.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: pthread_attr_getname_np.3,v 1.7 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c)2007 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd July 7, 2010 +.Dt PTHREAD_ATTR_GETNAME_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_getname_np , +.Nm pthread_attr_setname_np +.Nd get and set descriptive name of an attribute +.\" ------------------------------------------------------------ +.Sh LIBRARY +.Lb libpthread +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getname_np \ +"const pthread_attr_t attr" "char *name" "size_t len" +.Ft int +.Fn pthread_attr_setname_np \ +"pthread_attr_t attr" "const char *name" "void *arg" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn pthread_attr_getname_np +function gets the descriptive name of a thread attribute. +It takes the following arguments: +.Bl -tag -width target -offset indent +.It Fa attr +The attribute whose descriptive name will be obtained. +.It Fa name +The buffer to be filled with the descriptive name of the attribute. +.It Fa len +The size of the buffer +.Fa name +in bytes. +.El +.Pp +The +.Fn pthread_attr_setname_np +function sets the descriptive name of a thread attribute. +It takes the following arguments: +.Bl -tag -width attr -offset indent +.It Fa attr +The attribute whose descriptive name will be set. +.It Fa name +The +.Xr printf 3 +format string to be used to construct the descriptive name of the attribute. +The resulted descriptive name should be shorter than +.Dv PTHREAD_MAX_NAMELEN_NP . +.It Fa arg +The +.Xr printf 3 +argument used with +.Fa name . +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +Both functions return 0 on success. +Otherwise, an error number is returned. +.\" ------------------------------------------------------------ +.Sh COMPATIBILITY +Both functions are non-standard extensions. +.\" ------------------------------------------------------------ +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_getname_np . +.Pp +The +.Fn pthread_attr_setname_np +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The supplied descriptive +.Fa name +was longer than +.Dv PTHREAD_MAX_NAMELEN_NP . +.It Bq Er ENOMEM +There was insufficient memory for the operation. +.El +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_getname_np 3 diff --git a/static/netbsd/man3/pthread_attr_getschedparam.3 b/static/netbsd/man3/pthread_attr_getschedparam.3 new file mode 100644 index 00000000..23021278 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getschedparam.3 @@ -0,0 +1,127 @@ +.\" $NetBSD: pthread_attr_getschedparam.3,v 1.3 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2010 +.Dt PTHREAD_ATTR_GETSCHEDPARAM 3 +.Os +.Sh NAME +.Nm pthread_attr_getschedparam , +.Nm pthread_attr_setschedparam , +.Nm pthread_attr_getschedpolicy , +.Nm pthread_attr_setschedpolicy +.Nd get and set scheduling attributes +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getschedparam \ +"const pthread_attr_t * restrict attr" "struct sched_param * restrict param" +.Ft int +.Fn pthread_attr_setschedparam \ +"pthread_attr_t *attr" "const struct sched_param *param" +.Ft int +.Fn pthread_attr_getschedpolicy \ +"const pthread_attr_t * restrict attr" "int * restrict policy" +.Ft int +.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" +.Sh DESCRIPTION +The +.Fn pthread_attr_getschedparam +and +.Fn pthread_attr_setschedparam +functions obtain and set the scheduling parameter attribute in the +.Fa attr +object. +The +.Vt sched_param +structure is defined in +.In sched.h . +At minimum this structure contains only a single member, +.Vt sched_priority . +Refer to +.Xr pthread_schedparam 3 +and +.Xr sched 3 +for additional details. +.Pp +The +.Fn pthread_attr_getschedpolicy +and +.Fn pthread_attr_setschedpolicy +functions get and set the scheduling policy attribute, +.Fa policy , +in the +.Fa attr +object. +The supported values of +.Fa policy +are the same ones listed in +.Xr pthread_schedparam 3 . +.Sh RETURN VALUES +If successful, all described functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_getschedparam +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid parameter was specified. +.El +.Pp +The +.Fn pthread_attr_setschedparam +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid parameter was specified. +.It Bq Er ENOMEM +There was insufficient memory. +.El +.Pp +The +.Fn pthread_attr_setschedpolicy +function may fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory. +.It Bq Er ENOTSUP +An unsupported +.Fa policy +was specified. +.El +.Pp +No errors are defined for +.Fn pthread_attr_getschedpolicy . +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_schedparam 3 , +.Xr sched 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/pthread_attr_getscope.3 b/static/netbsd/man3/pthread_attr_getscope.3 new file mode 100644 index 00000000..d41761a6 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getscope.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: pthread_attr_getscope.3,v 1.4 2017/10/23 01:03:23 wiz Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2010 +.Dt PTHREAD_ATTR_GETSCOPE 3 +.Os +.Sh NAME +.Nm pthread_attr_getscope , +.Nm pthread_attr_setscope +.Nd get and set the contention scope attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getscope \ +"const pthread_attr_t * restrict attr" "int * restrict contentionscope" +.Ft int +.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" +.Sh DESCRIPTION +The +.Fn pthread_attr_getscope +and +.Fn pthread_attr_setscope +functions get and set, respectively, the contention scope attribute in the +.Fa attr +object. +.Pp +The +.Fa contentionscope +parameter specifies the scheduling contention scope of a thread. +It is only possible to set the scope of a thread before the thread is created. +There are two possible contention scopes: +.Bl -tag -width PTHREAD_SCOPE_PROCESS -offset 2n +.It Dv PTHREAD_SCOPE_SYSTEM +The thread will contend for CPU +resources with all other processes and threads in the system. +Generally this means that the user thread is bound directly to the +kernel scheduling for its entire lifetime. +.It Dv PTHREAD_SCOPE_PROCESS +The thread will contend with other threads with the same scope attribute. +In general, this means that all +.Dv PTHREAD_SCOPE_PROCESS +threads are grouped together and this group of threads contends for +CPU resources. +This is commonly seen to require a hybrid +.Pq Dq M:N +threading model in order to multiplex the user and kernel space scheduling. +.El +.Pp +Only +.Dv PTHREAD_SCOPE_SYSTEM +is supported in +.Nx . +.Sh RETURN VALUES +Upon successful completion, both functions return 0. +Otherwise an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for +.Fn pthread_attr_getscope . +.Pp +The +.Fn pthread_attr_setscope +function shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid parameter. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr csf 9 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-96 . diff --git a/static/netbsd/man3/pthread_attr_getstack.3 b/static/netbsd/man3/pthread_attr_getstack.3 new file mode 100644 index 00000000..ba003d72 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getstack.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: pthread_attr_getstack.3,v 1.9 2023/12/07 16:55:01 riastradh Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 9, 2010 +.Dt PTHREAD_ATTR_GETSTACK 3 +.Os +.Sh NAME +.Nm pthread_attr_getstack , +.Nm pthread_attr_setstack , +.Nm pthread_attr_getstacksize , +.Nm pthread_attr_setstacksize , +.Nm pthread_attr_getstackaddr , +.Nm pthread_attr_setstackaddr +.Nd get and set thread stack attributes +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_getstack \ +"const pthread_attr_t * restrict attr" \ +"void ** restrict stackaddr" "size_t * restrict stacksize" +.Ft int +.Fn pthread_attr_setstack \ +"pthread_attr_t * restrict attr" "void *stackaddr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstacksize \ +"const pthread_attr_t * restrict attr" "size_t * restrict stacksize" +.Ft int +.Fn pthread_attr_setstacksize \ +"pthread_attr_t *attr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstackaddr \ +"const pthread_attr_t * restrict attr" "void ** restrict stackaddr" +.Ft int +.Fn pthread_attr_setstackaddr \ +"pthread_attr_t *attr" "void *stackaddr" +.Sh DESCRIPTION +The +.Fn pthread_attr_getstack +and +.Fn pthread_attr_setstack +functions get and set, respectively, the thread stack attributes +.Fa stackaddr +and +.Fa stacksize +in the +.Fa attr +object. +The remaining four functions behave similarly, +but instead of getting or setting both +.Fa stackaddr +and +.Fa stacksize , +these get and set the values individually. +.Pp +The +.Fa stacksize +parameter is defined to be the minimum stack size (in bytes) +allocated for the thread's stack during the creation of the thread. +The +.Fa stackaddr +attribute specifies the location of storage to be used for the thread's stack. +All pages within the stack described by +.Fa stackaddr +and +.Fa stacksize +should be both readable and writable by the thread. +.Pp +The behavior is undefined in all functions if the +.Fa attr +parameter does not refer to an attribute object initialized by using +.Xr pthread_attr_init 3 +prior to the call. +In addition, undefined behavior may follow if the +.Fn pthread_attr_getstack +function is called before the +.Fa stackaddr +attribute has been set. +.Ss Rationale +The rationale behind these functions is to address cases where an application +may be used in an environment where the stack of a thread must be placed to +some particular region of memory. +For the majority of applications, this is seldom necessary, +and the use of these functions should be generally avoided. +At least few potential caveats can be mentioned. +.Bl -bullet -offset 2n +.It +There is a certain degree of ambiguity in the POSIX +standard with respect to thread stack. +.It +The exact behavior of the functions may vary +both across machines and operating systems. +In particular, the address specified by +.Fa stackaddr +should be suitably aligned. +The system page size, as specified by +.Xr sysconf 3 , +and the use of +.Xr posix_memalign 3 +may guarantee some degree of portability. +Also +.Xr mmap 2 +provides means for alignment. +.It +If the application modifies the stack address, it claims also +the responsibility of allocating the stack area and guarding it against +possible stack overflow. +No default guard area will be allocated (see +.Xr pthread_attr_getguardsize 3 ) . +It may be necessary to manually use +.Xr mprotect 2 +in order to define a guard area at the end of the allocated stack. +.It +Moreover, if +.Fa attr +is used to create multiple threads, the stack address must be changed +by the application between successive calls to +.Xr pthread_create 3 . +.El +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for the three functions that obtain the stack values. +The three functions that set the stack values may fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory to complete the operation. +.El +.Pp +The +.Fn pthread_attr_setstacksize +function may additionally fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified +.Fa stacksize +is less than +.Dv PTHREAD_STACK_MIN +or exceeds some system-imposed limit. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_attr_setguardsize 3 +.Sh STANDARDS +All described functions conform to +.St -p1003.1-2001 . +Note that +.Fn pthread_attr_getstackaddr +and +.Fn pthread_attr_setstackaddr +were however removed from the specification in the +.St -p1003.1-2008 +revision. +.Sh BUGS +Older versions of +.Nx , +prior to 10.0, 9.4, and 8.3, incorrectly adjust the stack address by +the guard size in threads configured with +.Fn pthread_attr_setstack , +instead of ignoring the guard size in that case as +.Tn POSIX +prescribes +.Po +see +.Lk https://gnats.NetBSD.org/57721 "PR lib/57721" +.Pc . +.Pp +Even if you didn't set a nonzero guard size with +.Xr pthread_attr_setguardsize 3 , +the system will choose a nonzero default guard size. +.Pp +To work around this in applications that run on older and newer +versions of +.Nx , +as well as on other operating systems, you can safely set the guard +size to zero: +.Dl "pthread_attr_setguardsize(&attr, 0);" diff --git a/static/netbsd/man3/pthread_attr_setcreatesuspend_np.3 b/static/netbsd/man3/pthread_attr_setcreatesuspend_np.3 new file mode 100644 index 00000000..a285bedb --- /dev/null +++ b/static/netbsd/man3/pthread_attr_setcreatesuspend_np.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: pthread_attr_setcreatesuspend_np.3,v 1.4 2010/07/09 09:10:34 jruoho Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 9, 2010 +.Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_setcreatesuspend_np +.Nd set attribute to create a thread suspended +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t attr" +.Sh DESCRIPTION +The +.Fn pthread_attr_setcreatesuspend_np +function sets the +.Ar attr +argument, so that if this +.Ar attr +is used in a +.Xr pthread_create 3 +call, then the thread created will not run, but it will remain blocked +in the suspended queue, until +.Xr pthread_resume_np 3 +is called on it. +.Sh RETURN VALUES +The +.Fn pthread_attr_setcreatesuspend_np +function always returns 0. +.Sh COMPATIBILITY +The function is a non-standard extension. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 diff --git a/static/netbsd/man3/pthread_barrier.3 b/static/netbsd/man3/pthread_barrier.3 new file mode 100644 index 00000000..7c8264fd --- /dev/null +++ b/static/netbsd/man3/pthread_barrier.3 @@ -0,0 +1,166 @@ +.\" $NetBSD: pthread_barrier.3,v 1.8 2017/10/22 16:15:02 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd October 22, 2017 +.Dt PTHREAD_BARRIER 3 +.Os +.Sh NAME +.Nm pthread_barrier , +.Nm pthread_barrier_init , +.Nm pthread_barrier_destroy , +.Nm pthread_barrier_wait +.Nd barrier interface +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrier_init "pthread_barrier_t * restrict barrier" \ +"const pthread_barrierattr_t * restrict attr" "unsigned int count" +.Ft int +.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" +.Ft int +.Fn pthread_barrier_wait "pthread_barrier_t *barrier" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_barrier_init +function creates a new barrier with attributes +.Fa attr +and +.Fa count . +The +.Fa count +parameter indicates the number of threads +which will participate in the barrier. +The +.Xr pthread_barrierattr_init 3 +function may be used to specify the attributes supplied in +.Fa attr . +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +Barriers are most commonly used in the decomposition of parallel loops. +.Pp +.\" ----- +The +.Fn pthread_barrier_destroy +function causes the resources allocated to +.Fa barrier +to be released. +No threads should be blocked on +.Fa barrier . +.Pp +.\" ----- +The +.Fn pthread_barrier_wait +function causes the current thread to wait on the barrier specified. +Once as many threads as specified by the +.Fa count +parameter to the corresponding +.Fn pthread_barrier_init +call have called +.Fn pthread_barrier_wait , +all threads will wake up, return from their respective +.Fn pthread_barrier_wait +calls and continue execution. +.\" ----- +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, +.Fn pthread_barrier_init +will return zero and put the new barrier id into +.Fa barrier , +otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, +.Fn pthread_barrier_destroy +will return zero. +Otherwise an error value will be returned. +.Pp +.\" ----- +If successful, +.Fn pthread_barrier_wait +will return zero for all waiting threads except for one. +One thread will receive status +.Dv PTHREAD_BARRIER_SERIAL_THREAD , +which is intended to indicate that this thread may be used to update +shared data. +It is the responsibility of this thread to insure the visibility +and atomicity of any updates to shared data with respect to the +other threads participating in the barrier. +In the case of failure, an error value will be returned. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +The +.Fn pthread_barrier_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa count +is zero or +.Fa attr +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_barrier_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The +.Fa barrier +still has active threads associated with it. +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_barrier_wait +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.\" --------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread_barrierattr 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutex 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_barrierattr.3 b/static/netbsd/man3/pthread_barrierattr.3 new file mode 100644 index 00000000..b697e118 --- /dev/null +++ b/static/netbsd/man3/pthread_barrierattr.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: pthread_barrierattr.3,v 1.14 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 12, 2016 +.Dt PTHREAD_BARRIERATTR 3 +.Os +.Sh NAME +.Nm pthread_barrierattr_init , +.Nm pthread_barrierattr_destroy , +.Nm pthread_barrierattr_getpshared , +.Nm pthread_barrierattr_setpshared +.Nd barrier attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr" +.Ft int +.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr" +.Ft int +.Fn pthread_barrierattr_getpshared "const pthread_barrierattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_barrierattr_setpshared "pthread_barrierattr_t * attr" "int pshared" +.Sh DESCRIPTION +Barrier attributes are used to specify parameters to be used with +.Xr pthread_barrier_init 3 . +One attribute object can be used in multiple calls to +.Fn pthread_barrier_init , +with or without modifications between calls. +.Pp +The +.Fn pthread_barrierattr_init +function initializes +.Fa attr +with the default barrier attributes. +.Pp +The +.Fn pthread_barrierattr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_barrierattr_getpshared +function shall obtain the value of the process-shared attribute +from the attributes object referenced by +.Fa attr . +.Pp +The +.Fn pthread_barrierattr_setpshared +function shall set the process-shared attribute in an initialized +attributes object referenced by +.Fa attr . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No error codes are defined for +.Fn pthread_barrierattr_init . +.Pp +The +.Fn pthread_barrierattr_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_barrier_init 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh BUGS +The +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +functions are hidden by default since only thread shared attributes +are supported. diff --git a/static/netbsd/man3/pthread_cancel.3 b/static/netbsd/man3/pthread_cancel.3 new file mode 100644 index 00000000..b7de992c --- /dev/null +++ b/static/netbsd/man3/pthread_cancel.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: pthread_cancel.3,v 1.6 2014/03/12 07:32:46 dholland Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_cancel.3,v 1.7 2002/09/16 19:29:28 mini Exp $ +.Dd July 9, 2010 +.Dt PTHREAD_CANCEL 3 +.Os +.Sh NAME +.Nm pthread_cancel +.Nd cancel execution of a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_cancel +function requests that +.Fa thread +be canceled. +The target thread's cancelability state and type determines +whether and when the target thread reacts to the cancellation request. +.Bl -enum -offset 2n +.It +The cancelability +.Em state +of a thread is determined by the +.Xr pthread_setcancelstate 3 +function. +The state can be either: +.Bl -bullet -offset 2n +.It +.Dv PTHREAD_CANCEL_ENABLE : +the cancelability type determines when the actual cancellation occurs. +This is the default. +.It +.Dv PTHREAD_CANCEL_DISABLE : +the request from +.Fn pthread_cancel +remains queued until the cancellation is enabled by the thread. +.El +.It +The cancellation +.Em type +of a thread is determined by the +.Xr pthread_setcanceltype 3 +function. +The type can be either: +.Bl -bullet -offset 2n +.It +.Dv PTHREAD_CANCEL_DEFERRED : +the cancellation will be delayed until the thread calls +a function that is a cancellation point. +This is the default. +The available cancellation points are listed in +.Xr pthread_setcanceltype 3 . +.It +.Dv PTHREAD_CANCEL_ASYNCHRONOUS : +the thread can be canceled at any time. +.El +.El +.Pp +When the thread reacts to the cancellation request, the following occur: +.Bl -enum -offset 2n +.It +The cancellation cleanup handlers for the thread are called; see +.Xr pthread_cleanup_push 3 . +.It +When the last cancellation cleanup handler returns, +the thread-specific data destructor functions will be called for the thread. +.It +When the last destructor function returns, the thread will be terminated; see +.Xr pthread_exit 3 . +.El +.Pp +The cancellation processing in the target thread runs asynchronously with +respect to the calling thread returning from +.Fn pthread_cancel . +.Pp +A status of +.Dv PTHREAD_CANCELED +is made available to any threads joining with the target. +The symbolic +constant +.Dv PTHREAD_CANCELED +expands to a constant expression of type +.Ft (void *) , +whose value matches no pointer to an object in memory nor the value +.Dv NULL . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cancel +functions will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cancel +function may fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.El +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_join 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_cleanup_push.3 b/static/netbsd/man3/pthread_cleanup_push.3 new file mode 100644 index 00000000..d38f841f --- /dev/null +++ b/static/netbsd/man3/pthread_cleanup_push.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: pthread_cleanup_push.3,v 1.6 2010/07/09 08:51:28 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_cleanup_push.3,v 1.11 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_CLEANUP 3 +.Os +.Sh NAME +.Nm pthread_cleanup_push , +.Nm pthread_cleanup_pop +.Nd add and remove cleanup functions for thread exit +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_cleanup_push "void \*[lp]*cleanup_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_push +function adds +.Fa cleanup_routine +to the top of the stack of cleanup handlers that +get called when the current thread exits. +.Pp +The +.Fn pthread_cleanup_pop +function pops the top cleanup routine off of the current threads cleanup +routine stack, and, if +.Fa execute +is non-zero, it will execute the function. +.Pp +When +.Fa cleanup_routine +is called, it is passed +.Fa arg +as its only argument. +.Pp +These functions may be implemented as macros which contain scope delimiters; +therefore, there must be a matching +.Fn pthread_cleanup_pop +for every +.Fn pthread_cleanup_push +at the same level of lexical scoping. +.Pp +The effect of calling +.Fn longjmp +or +.Fn siglongjmp +is undefined after a call to +.Fn pthread_cleanup_push +but before the matching call to +.Fn pthread_cleanup_pop +after the jump buffer was filled. +.Sh RETURN VALUES +Neither +.Fn pthread_cleanup_push +nor +.Fn pthread_cleanup_pop +returns a value. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_exit 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_cond.3 b/static/netbsd/man3/pthread_cond.3 new file mode 100644 index 00000000..0091ab95 --- /dev/null +++ b/static/netbsd/man3/pthread_cond.3 @@ -0,0 +1,281 @@ +.\" $NetBSD: pthread_cond.3,v 1.9 2018/07/28 14:00:19 kre Exp $ +.\" +.\" Copyright (c) 2002, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_COND 3 +.Os +.Sh NAME +.Nm pthread_cond , +.Nm pthread_cond_init , +.Nm pthread_cond_destroy , +.Nm pthread_cond_broadcast , +.Nm pthread_cond_signal , +.Nm pthread_cond_wait , +.Nm pthread_cond_timedwait +.Nd condition variable interface +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_init "pthread_cond_t * restrict cond" \ +"const pthread_condattr_t * restrict attr" +.Vt pthread_cond_t cond No = Dv PTHREAD_COND_INITIALIZER ; +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_wait "pthread_cond_t * restrict cond" \ +"pthread_mutex_t * restrict mutex" +.Ft int +.Fn pthread_cond_timedwait "pthread_cond_t * restrict cond" \ +"pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +Condition variables are intended to be used to communicate changes in +the state of data shared between threads. +Condition variables are always associated with a mutex to provide +synchronized access to the shared data. +A single predicate should always be associated with a +condition variable. +The predicate should identify a state of the +shared data that must be true before the thread proceeds. +.Pp +The +.Fn pthread_cond_init +function creates a new condition variable, with attributes specified with +.Fa attr . +If +.Fa attr +is +.Dv NULL +the default attributes are used. +The +.Fn pthread_cond_destroy +function frees the resources allocated by the condition variable +.Fa cond . +.Pp +The macro +.Dv PTHREAD_COND_INITIALIZER +can be used to initialize a condition variable when it can be statically +allocated and the default attributes are appropriate. +The effect is similar to calling +.Fn pthread_cond_init +with +.Fa attr +specified as +.Dv NULL , +except that no error checking is done. +.Pp +.\" ----- +The difference between +.Fn pthread_cond_broadcast +and +.Fn pthread_cond_signal +is that the former unblocks all threads waiting for the condition variable, +whereas the latter unblocks only one waiting thread. +If no threads are waiting on +.Fa cond , +neither function has any effect. +If more than one thread is blocked on a condition variable, +the used scheduling policy determines the order in which threads are unblocked. +The same mutex used for waiting must be held while calling either function. +Although neither function strictly enforces this requirement, +undefined behavior may follow if the mutex is not held. +.Pp +.\" ----- +The +.Fn pthread_cond_wait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and unlocks the mutex specified by +.Fa mutex . +The +.Fn pthread_cond_timedwait +function behaves similarly, but unblocks also +if the system time reaches the time specified in +.Fa abstime , +represented as +.Em struct timespec +(see +.Xr timespec 3 ) . +With both functions the waiting thread unblocks after another thread calls +.Fn pthread_cond_signal +or +.Fn pthread_cond_broadcast +with the same condition variable and by holding the same +.Fa mutex +that was associated with +.Fa cond +by either one of the blocking functions. +The current thread holds the lock on +.Fa mutex +upon return from either function. +.\" ----- +.Pp +Note that a call to +.Fn pthread_cond_wait +or +.Fn pthread_cond_timedwait +may wake up spontaneously, without a call to +.Fn pthread_cond_signal +or +.Fn pthread_cond_broadcast . +The caller should prepare for this by invoking either function +within a predicate loop that tests whether the thread should proceed. +.Pp +.\" ----- +As noted, when calling either function that waits on a condition variable, +a temporary binding is established between the condition variable +.Fa cond +and the mutex +.Fa mutex . +During this time, the effect of an attempt by any thread to wait on +that condition variable using a different mutex is undefined. +The same mutex must be held while broadcasting or signaling on +.Fa cond . +Additionally, the same mutex must be used for concurrent calls to +.Fn pthread_cond_wait +and +.Fn pthread_cond_timedwait . +Only when a condition variable is known to be quiescent may an application +change the mutex associated with it. +In this implementation, none of the functions enforce this requirement, but +if the mutex is not held or independent mutexes are used the resulting +behaviour is undefined. +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, all functions return zero. +Otherwise, an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_cond_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The variable +.Fa cond +is locked by another thread. +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Pp +.\" ----- +Both +.Fn pthread_cond_broadcast +and +.Fn pthread_cond_signal +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Pp +.\" ----- +Both +.Fn pthread_cond_wait +and +.Fn pthread_cond_timedwait +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +or the value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The value specified by +.Fa mutex +was not locked in the condition wait. +.El +.Pp +The +.Fn pthread_cond_timedwait +function may additionally fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The system time has reached or exceeded the time specified in +.Fa abstime . +.El +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_condattr 3 , +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_condattr.3 b/static/netbsd/man3/pthread_condattr.3 new file mode 100644 index 00000000..a1c04bb4 --- /dev/null +++ b/static/netbsd/man3/pthread_condattr.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: pthread_condattr.3,v 1.13 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_condattr.3,v 1.10 2002/09/16 19:29:28 mini Exp $ +.Dd March 28, 2017 +.Dt PTHREAD_CONDATTR 3 +.Os +.Sh NAME +.Nm pthread_condattr_init , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock +.Nd condition attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_getclock "const pthread_condattr_t * restrict attr" \ +"clockid_t * restrict clock_id" +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock" +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_getpshared "const pthread_condattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pshared_condattr_setpshared "pthread_condattr_t *attr" "int pshared" +.Sh DESCRIPTION +Condition attribute objects are used to specify parameters to the +.Xr pthread_cond_init 3 +function. +The +.Fn pthread_condattr_init +function initializes a condition attribute object with the default attributes +and the +.Fn pthread_condattr_destroy +function destroys a condition attribute object. +The +.Fn pthread_condattr_getclock +function shall obtain the value of the +.Fa clock +attributes object referenced by +.Fa attr . +The +.Fn pthread_condattr_setclock +function sets the system clock to be used for time comparisons to +the one specified in +.Fa clock . +Valid clock values are +.Dv CLOCK_MONOTONIC +and +.Dv CLOCK_REALTIME +(the default). +The +.Fn pthread_condattr_getpshared +function shall obtain the value of the process-shared attribute from the +attributes object referenced by +.Fa attr . +The +.Fn pthread_condattr_setpshared +function shall set the process-shared attribute in an initialized attributes +object referenced by +.Fa attr . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +No errors are defined for +.Fn pthread_condattr_init . +.Pp +The +.Fn pthread_condattr_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The +.Fn pthread_condattr_getclock +and +.Fn pthread_condattr_setclock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The +.Fn pthread_condattr_getpshared +and +.Fn pthread_condattr_setpshared +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_cond_init 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Sh BUGS +The +.Fn pthread_condattr_getpshared +and +.Fn pthread_condattr_setpshared +functions are hidden by default since only thread shared attributes +are supported. diff --git a/static/netbsd/man3/pthread_create.3 b/static/netbsd/man3/pthread_create.3 new file mode 100644 index 00000000..24aa5726 --- /dev/null +++ b/static/netbsd/man3/pthread_create.3 @@ -0,0 +1,164 @@ +.\" $NetBSD: pthread_create.3,v 1.9 2023/04/29 21:37:07 uwe Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_create.3,v 1.16 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_CREATE 3 +.Os +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +. +.Ft int +.Fo pthread_create +.Fa "pthread_t * restrict thread" +.Fa "const pthread_attr_t * restrict attr" +.Fa "void *(*start_routine)(void *)" +.Fa "void * restrict arg" +.Fc +. +.Sh DESCRIPTION +The +.Fn pthread_create +function is used to create a new thread, with attributes specified by +.Fa attr , +within a process. +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +.Pp +The attributes specified via +.Fa attr +are copied into the new thread. +Any subsequent modifications to the attributes object +.Fa attr +points to will have no effect upon already-created threads. +It is thus also safe to pass the same +.Fa attr +to multiple calls to +.Fn pthread_create . +.Pp +Upon +successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. +.Pp +If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Xr pthread_exit 3 +using the return value of +.Fa start_routine +as the exit status. +Note that the thread in which +.Fn main +was originally invoked differs from this. +When it returns from +.Fn main , +the effect is as if there was an implicit call to +.Xr exit 3 +using the return value of +.Fn main +as the exit status. +.Pp +The signal state of the new thread is initialized as: +.Bl -bullet -offset indent +.It +The signal mask is inherited from the creating thread. +.It +The set of signals pending for the new thread is empty. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_create +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_create +shall fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +.Dv PTHREAD_THREADS_MAX +would be exceeded. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr pthread_attr 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_curcpu_np.3 b/static/netbsd/man3/pthread_curcpu_np.3 new file mode 100644 index 00000000..6bf0ba40 --- /dev/null +++ b/static/netbsd/man3/pthread_curcpu_np.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: pthread_curcpu_np.3,v 1.2 2011/11/10 16:44:47 wiz Exp $ +.\" +.\" Copyright (c)2011 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd November 10, 2011 +.Dt PTHREAD_CURCPU_NP 3 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm pthread_curcpu_np +.Nd get current CPU identifier +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In pthread.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft unsigned int +.Fn pthread_curcpu_np \ +"void" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn pthread_curcpu_np +function provides a way for a thread to know which CPU it's currently running +on. +.Pp +Note that, unless the thread is bound to a specific CPU, the result might be +already stale when the function returns. +However, it still can be useful as a hint to achieve better CPU locality. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +The +.Fn pthread_curcpu_np +function returns the integer identifier of the CPU which is currently +running the calling thread. +.\" ------------------------------------------------------------ +.Sh COMPATIBILITY +The +.Fn pthread_curcpu_np +function is a non-standard extension. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr affinity 3 , +.Xr pthread 3 diff --git a/static/netbsd/man3/pthread_detach.3 b/static/netbsd/man3/pthread_detach.3 new file mode 100644 index 00000000..ea6172e0 --- /dev/null +++ b/static/netbsd/man3/pthread_detach.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: pthread_detach.3,v 1.4 2010/07/09 08:51:28 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_detach.3,v 1.13 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_DETACH 3 +.Os +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_detach "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_detach +function is used to indicate to the implementation that storage for the +thread +.Fa thread +can be reclaimed when the thread terminates. +If +.Fa thread +has not terminated, +.Fn pthread_detach +will not cause it to terminate. +The effect of multiple +.Fn pthread_detach +calls on the same target thread is unspecified. +.Sh RETURN VALUES +If successful, the +.Fn pthread_detach +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_detach +shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Sh SEE ALSO +.Xr pthread_join 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_equal.3 b/static/netbsd/man3/pthread_equal.3 new file mode 100644 index 00000000..33e17663 --- /dev/null +++ b/static/netbsd/man3/pthread_equal.3 @@ -0,0 +1,92 @@ +.\" $NetBSD: pthread_equal.3,v 1.4 2010/07/09 08:51:28 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_equal.3,v 1.11 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_EQUAL 3 +.Os +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Sh DESCRIPTION +The +.Fn pthread_equal +function compares the thread IDs +.Fa t1 +and +.Fa t2 . +.Sh RETURN VALUES +The +.Fn pthread_equal +function will return non-zero if the thread IDs +.Fa t1 +and +.Fa t2 +correspond to the same thread, otherwise it will return zero. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_exit.3 b/static/netbsd/man3/pthread_exit.3 new file mode 100644 index 00000000..d82d6b34 --- /dev/null +++ b/static/netbsd/man3/pthread_exit.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: pthread_exit.3,v 1.5 2010/07/09 08:51:28 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_exit.3,v 1.16 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_EXIT 3 +.Os +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_exit "void *value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_exit +function terminates the calling thread and makes the value +.Fa value_ptr +available to any successful join with the terminating thread. +Any +cancellation cleanup handlers that have been pushed and are not yet popped +are popped in the reverse order that they were pushed and then executed. +After all cancellation handlers have been executed, if the thread has any +thread-specific data, appropriate destructor functions are called in an +unspecified order. +Thread termination does not release any application +visible process resources, including, but not limited to, mutexes and +file descriptors, nor does it perform any process level cleanup +actions, including, but not limited to, calling +.Fn atexit +routines that may exist. +.Pp +An implicit call to +.Fn pthread_exit +is made when a thread other than the thread in which +.Fn main +was first invoked returns from the start routine that was used to create +it. +The function's return value serves as the thread's exit status. +.Pp +The behavior of +.Fn pthread_exit +is undefined if called from a cancellation handler or destructor function +that was invoked as the result of an implicit or explicit call to +.Fn pthread_exit . +.Pp +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. +Thus, references to local variables +of the exiting thread should not be used for the +.Fn pthread_exit +.Fa value_ptr +parameter value. +.Pp +The process will exit with an exit status of 0 after the last thread has +been terminated. +The behavior is as if the implementation called +.Fn exit +with a zero argument at thread termination time. +.Sh RETURN VALUES +The +.Fn pthread_exit +function cannot return to its caller. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr exit 3 , +.Xr pthread_create 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_getcpuclockid.3 b/static/netbsd/man3/pthread_getcpuclockid.3 new file mode 100644 index 00000000..b0b6f92c --- /dev/null +++ b/static/netbsd/man3/pthread_getcpuclockid.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: pthread_getcpuclockid.3,v 1.5 2017/03/05 18:42:51 njoly Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 5, 2017 +.Dt PTHREAD_GETCPUCLOCKID 3 +.Os +.Sh NAME +.Nm pthread_getcpuclockid +.Nd retrieve the clockid of the given thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_getcpuclockid "pthread_t thread" "clockid_t *clock_id" +.Sh DESCRIPTION +The +.Fn pthread_getcpuclockid +function retrieves the +.Fa clock_id +for the specified +.Fa thread . +.Pp +The +.Xr clock_gettime 2 +function can be used with the returned +.Fa clock_id +to retrieve LWP times. +.Sh RETURN VALUES +On success the +.Fn pthread_getcpuclockid +function returns 0, placing the requested +.Fa clock_id +in the argument. +Otherwise an error number will be returned. +.Sh ERRORS +These functions fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa clock_id +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr clock_getcpuclockid2 2 , +.Xr clock_gettime 2 +.Sh STANDARDS +The +.Fn pthread_getcpuclockid +function conforms to +.St -p1003.1-2001 . +extension. +.Sh HISTORY +The +.Fn pthread_getcpuclockid +function appeared in +.Nx 8 . diff --git a/static/netbsd/man3/pthread_getname_np.3 b/static/netbsd/man3/pthread_getname_np.3 new file mode 100644 index 00000000..30f177cd --- /dev/null +++ b/static/netbsd/man3/pthread_getname_np.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: pthread_getname_np.3,v 1.7 2025/10/27 16:29:15 christos Exp $ +.\" +.\" Copyright (c)2007 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd July 9, 2010 +.Dt PTHREAD_GETNAME_NP 3 +.Os +.Sh NAME +.Nm pthread_getname_np , +.Nm pthread_setname_np +.Nd get and set descriptive name of a thread +.\" ------------------------------------------------------------ +.Sh LIBRARY +.Lb libpthread +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" +.Ft int +.Fn pthread_setname_np "pthread_t thread" "const char *name" "void *arg" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Fn pthread_getname_np +function obtains the descriptive name of a thread. +It takes the following arguments: +.Bl -tag -width target -offset indent +.It Fa thread +The thread whose descriptive name will be obtained. +.It Fa name +The buffer to be filled with the descriptive name of the thread. +.It Fa len +The size of the buffer +.Fa name +in bytes. +.El +.Pp +The +.Fn pthread_setname_np +function sets the descriptive name of a thread. +It takes the following arguments: +.Bl -tag -width target -offset indent +.It Fa thread +The thread whose descriptive name will be set. +.It Fa name +The +.Xr printf 3 +format string to be used to construct the descriptive name of the thread. +The resulted descriptive name should be shorter than +.Dv PTHREAD_MAX_NAMELEN_NP . +.It Fa arg +The +.Xr printf 3 +argument used with +.Fa name . +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +Both functions return 0 on success. +Otherwise, an error number is returned to indicate the error. +.\" ------------------------------------------------------------ +.Sh COMPATIBILITY +Both functions are non-standard extensions. +.\" ------------------------------------------------------------ +.Sh ERRORS +Both functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid parameter. +.It Bq Er ESRCH +Non-existent +.Fa thread . +.El +.Pp +The +.Fn pthread_setname_np +function may also fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory for the operation. +.El +.Sh SEE ALSO +.Xr pthread_attr_get_np 3 , +.Xr pthread_attr_getname_np 3 diff --git a/static/netbsd/man3/pthread_getspecific.3 b/static/netbsd/man3/pthread_getspecific.3 new file mode 100644 index 00000000..ad04bf0b --- /dev/null +++ b/static/netbsd/man3/pthread_getspecific.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: pthread_getspecific.3,v 1.6 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_getspecific.3,v 1.11 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_GETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_getspecific , +.Nm pthread_setspecific +.Nd thread-specific data value +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +Conversely, the +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Xr pthread_key_create 3 . +Different threads have different values bound to each key. +These values are typically pointers to blocks of dynamically +allocated memory that have been reserved for use by the calling thread. +.Pp +Undefined behavior may follow if either function is called with a +.Fa key +value not obtained from +.Xr pthread_key_create 3 , +or if the call is made after +.Fa key +has been deleted with +.Xr pthread_key_delete 3 . +It is possible to call either function from +a thread-specific data destructor function. +Note however that this is not well defined for the +.Fn pthread_setspecific +function; +lost storage or infinite loops may occur. +.Sh RETURN VALUES +The +.Fn pthread_getspecific +function will return the thread-specific data value associated with the given +.Fa key . +If no thread-specific data value is associated with +.Fa key , +then the value +.Dv NULL +is returned. +If successful, the +.Fn pthread_setspecific +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +No errors are defined for either function. +.Sh SEE ALSO +.Xr pthread_key_create 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_join.3 b/static/netbsd/man3/pthread_join.3 new file mode 100644 index 00000000..41609f65 --- /dev/null +++ b/static/netbsd/man3/pthread_join.3 @@ -0,0 +1,134 @@ +.\" $NetBSD: pthread_join.3,v 1.6 2010/07/09 10:55:11 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_join.3,v 1.13 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_JOIN 3 +.Os +.Sh NAME +.Nm pthread_join +.Nd wait for thread termination +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_join +function suspends execution of the calling thread until the target +.Fa thread +terminates unless the target +.Fa thread +has already terminated. +.Pp +On return from a successful +.Fn pthread_join +call with a +.Pf non- Dv NULL +.Fa value_ptr +argument, the value passed to +.Fn pthread_exit +by the terminating thread is stored in the location referenced by +.Fa value_ptr . +When a +.Fn pthread_join +returns successfully, the target thread has been terminated. +The results +of multiple simultaneous calls to +.Fn pthread_join +specifying the same target thread are undefined. +If the thread calling +.Fn pthread_join +is cancelled, then the target thread is not detached. +.Pp +A thread that has exited but remains unjoined counts against +.Dv _POSIX_THREAD_THREADS_MAX . +.Sh RETURN VALUES +If successful, the +.Fn pthread_join +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_join +shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Pp +.Fn pthread_join +may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +A deadlock was detected or the value of +.Fa thread +specifies the calling thread. +.El +.Sh SEE ALSO +.Xr wait 2 , +.Xr pthread_create 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_key_create.3 b/static/netbsd/man3/pthread_key_create.3 new file mode 100644 index 00000000..5694a50c --- /dev/null +++ b/static/netbsd/man3/pthread_key_create.3 @@ -0,0 +1,195 @@ +.\" $NetBSD: pthread_key_create.3,v 1.9 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_key_create.3,v 1.12 2002/09/16 19:29:28 mini Exp $ +.\" +.Dd May 29, 2015 +.Dt PTHREAD_KEY_CREATE 3 +.Os +.Sh NAME +.Nm pthread_key_create , +.Nm pthread_key_delete +.Nd thread-specific data +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. +Key values are opaque objects used to locate thread-specific data. +The same key value may be used by different threads, +but the values bound to the key by +.Fn pthread_setspecific +are maintained on a per-thread basis and +persist for the life of the calling thread. +.Pp +Upon key creation, the value +.Dv NULL +is associated with the new key in all active threads. +Upon thread creation, the value +.Dv NULL +is associated with all +defined keys in the new thread. +.Pp +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a +.Pf non- Dv NULL +destructor pointer, and the thread has a +.Pf non- Dv NULL +value associated with the key, the function pointed +to is called with the current associated value as its sole argument. +The order of destructor calls is unspecified if more +than one destructor exists for a thread when it exits. +.Pp +If, after all the destructors have been called for all +.Pf non- Dv NULL +values with associated destructors, there are still some +.Pf non- Dv NULL +values with associated destructors, then the process is repeated. +If, after at least +.Dv PTHREAD_DESTRUCTOR_ITERATIONS +iterations of destructor calls for outstanding +.Pf non- Dv NULL +values, there are still some +.Pf non- Dv NULL +values with +associated destructors, the implementation stops calling destructors. +.Pp +The +.Fn pthread_key_delete +function deletes a thread-specific data key previously returned by +.Fn pthread_key_create . +The thread-specific data values associated with +.Fa key +need not be +.Dv NULL +at the time of the call. +It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any threads; +this cleanup can be done either before or after +.Fn pthread_key_delete +is called. +Any attempt to use +.Fa key +following the call to +.Fn pthread_key_delete +results in undefined behavior. +.Pp +The +.Fn pthread_key_delete +function itself is callable from within destructor functions, +but destructor functions are not invoked by the function. +Any destructor function that may have been associated with +.Fa key +will no longer be called upon thread exit. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_create +function will store the newly created key value at the location specified by +.Fa key +and returns zero. +Also +.Fn pthread_key_delete +will return zero upon success. +Upon failure both functions return an error number to indicate the cause. +.Sh ENVIRONMENT +.Bl -tag -width PTHREAD_KEYS_MAX +.It Ev PTHREAD_KEYS_MAX +Maximum per-process thread-specific data keys. +This cannot be set below +.Dv _POSIX_THREAD_KEYS_MAX . +.El +.Sh ERRORS +The +.Fn pthread_key_create +may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total number of keys per-process +.Dv PTHREAD_KEYS_MAX +would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Pp +The +.Fn pthread_key_delete +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh BUGS +The current specifications are flawed and +do not permit a clean implementation without potential problems. +The current implementation in +.Nx +addresses these problems by not supporting key reuse. diff --git a/static/netbsd/man3/pthread_kill.3 b/static/netbsd/man3/pthread_kill.3 new file mode 100644 index 00000000..90513e94 --- /dev/null +++ b/static/netbsd/man3/pthread_kill.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: pthread_kill.3,v 1.9 2010/07/09 08:51:28 jruoho Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_kill.3,v 1.9 2002/09/16 19:29:28 mini Exp $ +.Dd July 9, 2010 +.Dt PTHREAD_KILL 3 +.Os +.Sh NAME +.Nm pthread_kill +.Nd send a signal to a specified thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_kill "pthread_t thread" "int sig" +.Sh DESCRIPTION +The +.Fn pthread_kill +function sends a signal, specified by +.Fa sig , +to a thread, specified by +.Fa thread . +The signal will be handled in the context of +.Fa thread , +but the signal action may alter the process as a whole. +If +.Fa sig +is 0, error checking is performed, but no signal is actually sent. +.Sh RETURN VALUES +If successful, +.Fn pthread_kill +returns 0. +Otherwise, an error number is returned. +.Sh ERRORS +.Fn pthread_kill +shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sig +is an invalid or unsupported signal number. +.It Bq Er ESRCH +.Fa thread +is an invalid thread ID. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigwait 2 , +.Xr pthread_self 3 , +.Xr raise 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_mutex.3 b/static/netbsd/man3/pthread_mutex.3 new file mode 100644 index 00000000..9f0c5034 --- /dev/null +++ b/static/netbsd/man3/pthread_mutex.3 @@ -0,0 +1,304 @@ +.\" $NetBSD: pthread_mutex.3,v 1.12 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd June 12, 2016 +.Dt PTHREAD_MUTEX 3 +.Os +.Sh NAME +.Nm pthread_mutex , +.Nm pthread_mutex_init , +.Nm pthread_mutex_destroy , +.Nm pthread_mutex_lock , +.Nm pthread_mutex_trylock , +.Nm pthread_mutex_unlock , +.Nm pthread_mutex_timedlock , +.Nm pthread_mutex_getprioceiling , +.Nm pthread_mutex_setprioceiling +.Nd mutual exclusion primitives +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_init "pthread_mutex_t * restrict mutex" \ +"const pthread_mutexattr_t * restrict attr" +.Vt pthread_mutex_t mutex No = Dv PTHREAD_MUTEX_INITIALIZER ; +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_timedlock "pthread_mutex_t * restrict mutex" "const struct timespec * restrict timeout" +.Ft int +.Fn pthread_mutex_getprioceiling "const pthread_mutex_t * restrict mutex" "int * restrict prioceiling" +.Ft int +.Fn pthread_mutex_setprioceiling "pthread_mutex_t * restrict mutex" \ +"int prioceiling" "int * restrict old_ceiling" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_mutex_init +function creates a new mutex, with attributes specified with +.Fa attr . +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +.Pp +The macro +.Dv PTHREAD_MUTEX_INITIALIZER +can be used to initialize a mutex when the default attributes are +appropriate and the mutex can be statically allocated. +The behavior is similar to +.Fn pthread_mutex_init +with +.Fa attr +specified as +.Dv NULL , +except that no error checking is done. +.Pp +.\" ----- +The +.Fn pthread_mutex_destroy +function frees the resources allocated for +.Fa mutex . +It is possible to reinitialize a destroyed mutex, but undefined +behavior may follow if the destroyed object is otherwise referenced. +.Pp +.\" ----- +The +.Fn pthread_mutex_lock +function locks +.Fa mutex . +If the mutex is already locked, the calling thread will block until the +mutex becomes available. +The error conditions may vary depending on the type of the mutex; see +.Xr pthread_mutexattr 3 +for additional details. +.Pp +The +.Fn pthread_mutex_trylock +function locks +.Fa mutex . +If the mutex is already locked, +.Fn pthread_mutex_trylock +will not block waiting for the mutex, but will return an error condition. +.Pp +.\" ----- +The +.Fn pthread_mutex_unlock +function unlocks an acquired +.Fa mutex . +When operating with the default mutex type, +undefined behavior follows if a thread tries to unlock a mutex +that has not been locked by it, or if a thread tries to release +a mutex that is already unlocked. +.Pp +.\" ----- +The +.Fn pthread_mutex_timedlock +function shall lock the mutex object referenced by +.Fa mutex . +If the mutex is already locked, the calling thread shall block until +the mutex becomes available in the +.Fn pthread_mutex_lock +function. +If the mutex cannot be locked without waiting for another thread to +unlock the mutex, this wait shall be terminated when the specified timeout +expires. +The timeout shall expire when the absolute time specified by +.Fa timeout +passes, as measured by the clock on which timeouts are based. +.Pp +.\" ----- +The +.Fn pthread_mutex_getprioceiling +function shall return the current priority ceiling of the mutex. +.Pp +.\" ----- +The +.Fn pthread_mutex_setprioceiling +function shall either lock the mutex if it is unlocked, or block until +it can successfully lock the mutex, then it shall change the mutex's priority +ceiling and release the mutex. +When the change is successful, the previous value of the priority ceiling +shall be returned +in +.Fa old_ceiling . +The process of locking the mutex need not adhere to the priority +protect protocol. +If +.Fn pthread_mutex_setprioceiling +function fails, the mutex priority ceiling shall not be changed. +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +Upon success all described functions return zero. +Otherwise, an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_mutex_init +may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another mutex. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to initialize another mutex. +.El +.Pp +.\" ----- +.Fn pthread_mutex_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is locked by another thread. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_lock +may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +A deadlock would occur if the thread blocked waiting for +.Fa mutex . +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.Fn pthread_mutex_trylock +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is already locked. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_unlock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.Pp +.\" ----- +.Fn pthread_mutex_timedlock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The mutex was created with the protocol attribute having the value +.Dv PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher than +the mutex current priority ceiling; or +the process or thread would have blocked, and the +.Fa timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.El +.Pp +.\" ----- +The +.Fn pthread_mutex_getprioceiling +and +.Fn pthread_mutex_setprioceiling +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The priority requested by +.Fa prioceiling +is out of range; or +the value specified by +.Fa mutex +does not refer to a currently existing mutex. +.It Bq Er EPERM +The caller does not have the privilege to perform the operation. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutexattr 3 , +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.\" ---------------------------------------------------------------------------- +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_mutexattr.3 b/static/netbsd/man3/pthread_mutexattr.3 new file mode 100644 index 00000000..b61ce9dc --- /dev/null +++ b/static/netbsd/man3/pthread_mutexattr.3 @@ -0,0 +1,302 @@ +.\" $NetBSD: pthread_mutexattr.3,v 1.15 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $ +.Dd June 12, 2016 +.Dt PTHREAD_MUTEXATTR 3 +.Os +.Sh NAME +.Nm pthread_mutexattr_init , +.Nm pthread_mutexattr_destroy , +.Nm pthread_mutexattr_setprioceiling , +.Nm pthread_mutexattr_getprioceiling , +.Nm pthread_mutexattr_setprotocol , +.Nm pthread_mutexattr_getprotocol , +.Nm pthread_mutexattr_settype , +.Nm pthread_mutexattr_gettype , +.Nm pthread_mutexattr_getpshared , +.Nm pthread_mutexattr_setpshared +.Nd mutex attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" +.Ft int +.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" +.Ft int +.Fn pthread_mutexattr_setprioceiling \ +"pthread_mutexattr_t *attr" "int prioceiling" +.Ft int +.Fn pthread_mutexattr_getprioceiling \ +"pthread_mutexattr_t *attr" "int *prioceiling" +.Ft int +.Fn pthread_mutexattr_setprotocol \ +"pthread_mutexattr_t *attr" "int protocol" +.Ft int +.Fn pthread_mutexattr_getprotocol \ +"pthread_mutexattr_t *attr" "int *protocol" +.Ft int +.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" +.Ft int +.Fn pthread_mutexattr_gettype \ +"pthread_mutexattr_t * restrict attr" "int * restrict type" +.Ft int +.Fn pthread_mutexattr_getpshared \ +"const pthread_mutexattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_mutexattr_setpshared \ +"pthread_mutexattr_t * attr" "int pshared" +.Sh DESCRIPTION +Mutex attributes are used to specify parameters to +.Fn pthread_mutex_init . +Like with thread attributes, +one attribute object can be used in multiple calls to +.Xr pthread_mutex_init 3 , +with or without modifications between calls. +.Pp +The +.Fn pthread_mutexattr_init +function initializes +.Fa attr +with all the default mutex attributes. +.Pp +The +.Fn pthread_mutexattr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_mutexattr_settype +functions set the mutex +.Fa type +value of the attribute. +Valid mutex types are: +.Bl -tag -width "XXX" -offset 2n +.It Dv PTHREAD_MUTEX_NORMAL +This type of mutex does not check for usage errors. +It will deadlock if reentered, and result in undefined behavior if a +locked mutex is unlocked by another thread. +Attempts to unlock an already unlocked +.Dv PTHREAD_MUTEX_NORMAL +mutex will result in undefined behavior. +.It Dv PTHREAD_MUTEX_ERRORCHECK +These mutexes do check for usage errors. +If an attempt is made to relock a +.Dv PTHREAD_MUTEX_ERRORCHECK +mutex without first dropping the lock, an error will be returned. +If a thread attempts to unlock a +.Dv PTHREAD_MUTEX_ERRORCHECK +mutex that is locked by another thread, an error will be returned. +If a thread attempts to unlock a +.Dv PTHREAD_MUTEX_ERRORCHECK +thread that is unlocked, an error will be returned. +.It Dv PTHREAD_MUTEX_RECURSIVE +These mutexes allow recursive locking. +An attempt to relock a +.Dv PTHREAD_MUTEX_RECURSIVE +mutex that is already locked by the same thread succeeds. +An equivalent number of +.Xr pthread_mutex_unlock 3 +calls are needed before the mutex will wake another thread waiting +on this lock. +If a thread attempts to unlock a +.Dv PTHREAD_MUTEX_RECURSIVE +mutex that is locked by another thread, an error will be returned. +If a thread attempts to unlock a +.Dv PTHREAD_MUTEX_RECURSIVE +thread that is unlocked, an error will be returned. +.Pp +It is advised that +.Dv PTHREAD_MUTEX_RECURSIVE +mutexes are not used with condition variables. +This is because of the implicit unlocking done by +.Xr pthread_cond_wait 3 +and +.Xr pthread_cond_timedwait 3 . +.It Dv PTHREAD_MUTEX_DEFAULT +Also this type of mutex will cause undefined behavior if reentered. +Unlocking a +.Dv PTHREAD_MUTEX_DEFAULT +mutex locked by another thread will result in undefined behavior. +Attempts to unlock an already unlocked +.Dv PTHREAD_MUTEX_DEFAULT +mutex will result in undefined behavior. +.Pp +This is the default mutex type for +.Fn pthread_mutexattr_init . +.El +.Pp +The +.Fn pthread_mutexattr_gettype +functions copy the type value of the attribute to the location +pointed to by the second parameter. +.Pp +The +.Fn pthread_mutexattr_getpshared +function obtains the value of the process-shared attribute from +the attributes object referenced by +.Fa attr . +.Pp +The +.Fn pthread_mutexattr_setpshared +function is used to set the process-shared attribute in an initialised +attributes object referenced by +.Fa attr . +.Pp +The +.Fn pthread_mutexattr_getprotocol +and +.Fn pthread_mutexattr_setprotocol +functions shall get and set the protocol attribute of a mutex attributes +object pointed to by +.Fa attr +which was previously created by the function +.Fn pthread_mutexattr_init . +.Pp +The +.Fn pthread_mutexattr_getprioceiling +and +.Fn pthread_mutexattr_setprioceiling +functions, shall get and set the priority ceiling attribute of a mutex attributes +object pointed to by +.Fa attr +which was previously created by the function +.Fn pthread_mutexattr_init . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutexattr_init +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the mutex attributes object. +.El +.Pp +The +.Fn pthread_mutexattr_settype +function shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified either by +.Fa type +or +.Fa attr +is invalid. +.El +.Pp +No error numbers are defined for the +.Fn pthread_mutexattr_destroy +and +.Fn pthread_mutexattr_gettype +functions. +.Pp +.Fn pthread_mutexattr_setprioceiling +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa prioceiling . +.El +.Pp +.Fn pthread_mutexattr_getprioceiling +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +.Fn pthread_mutexattr_setprotocol +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa protocol . +.El +.Pp +.Fn pthread_mutexattr_getprotocol +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +.Fn pthread_mutexattr_getpshared +and +.Fn pthread_mutexattr_setpshared +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +the value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh BUGS +The +.Fn pthread_mutexattr_getpshared +and +.Fn pthread_mutexattr_setpshared +functions are hidden by default since only thread shared attributes +are supported. diff --git a/static/netbsd/man3/pthread_once.3 b/static/netbsd/man3/pthread_once.3 new file mode 100644 index 00000000..51f6aea1 --- /dev/null +++ b/static/netbsd/man3/pthread_once.3 @@ -0,0 +1,128 @@ +.\" $NetBSD: pthread_once.3,v 1.10 2016/07/05 10:04:17 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_once.3,v 1.14 2002/09/16 19:29:29 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_ONCE 3 +.Os +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" +.Vt pthread_once_t once_control No = Dv PTHREAD_ONCE_INIT ; +.Sh DESCRIPTION +The first call to +.Fn pthread_once +by any thread in a process, with a given +.Fa once_control , +will call the +.Fn init_routine +with no arguments. +Subsequent calls to +.Fn pthread_once +with the same +.Fa once_control +will not call the +.Fn init_routine +On return from +.Fn pthread_once , +it is guaranteed that +.Fn init_routine +has completed. +The +.Fa once_control +parameter is used to determine whether the associated initialization +routine has been called. +.Pp +The function +.Fn pthread_once +is not a cancellation point. +However, if +.Fn init_routine +is a cancellation point and is cancelled, the effect on +.Fa once_control +is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Dv PTHREAD_ONCE_INIT +initializes the static once synchronization control structure +.Fa once_control +to be used with +.Fn pthread_once . +The behavior of +.Fn pthread_once +is undefined if +.Fa once_control +has automatic storage duration or is not initialized by +.Dv PTHREAD_ONCE_INIT . +.Sh RETURN VALUES +If successful, the +.Fn pthread_once +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +None. +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_rwlock.3 b/static/netbsd/man3/pthread_rwlock.3 new file mode 100644 index 00000000..35a6e64e --- /dev/null +++ b/static/netbsd/man3/pthread_rwlock.3 @@ -0,0 +1,355 @@ +.\" $NetBSD: pthread_rwlock.3,v 1.7 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_RWLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock , +.Nm pthread_rwlock_init , +.Nm pthread_rwlock_destroy , +.Nm pthread_rwlock_rdlock , +.Nm pthread_rwlock_timedrdlock , +.Nm pthread_rwlock_tryrdlock , +.Nm pthread_rwlock_wrlock , +.Nm pthread_rwlock_timedwrlock , +.Nm pthread_rwlock_trywrlock , +.Nm pthread_rwlock_unlock +.Nd read/write lock interface +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_init "pthread_rwlock_t * restrict lock" \ +"const pthread_rwlockattr_t * restrict attr" +.Vt pthread_rwlock_t lock No = Dv PTHREAD_RWLOCK_INITIALIZER ; +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_timedrdlock "pthread_rwlock_t * restrict lock" \ +"const struct timespec * restrict abstime" +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t * restrict lock" \ +"const struct timespec * restrict abstime" +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_rwlock_init +function is used to initialize a read/write lock, with attributes +specified by +.Fa attr . +If +.Fa attr +is +.Dv NULL , +the default read/write lock attributes are used. +.Pp +The results of calling +.Fn pthread_rwlock_init +with an already initialized lock are undefined. +.Pp +The macro +.Dv PTHREAD_RWLOCK_INITIALIZER +can be used to initialize a read/write lock when the allocation can be done +statically, no error checking is required, and the default attributes are +appropriate. +The behavior is similar to calling +.Fn pthread_rwlock_init +with +.Fa attr +specified as +.Dv NULL . +.Pp +.\" ----- +The +.Fn pthread_rwlock_destroy +function is used to destroy a read/write lock previously created with +.Fn pthread_rwlock_init . +.Pp +.\" ----- +The +.Fn pthread_rwlock_rdlock +function acquires a read lock on +.Fa lock +provided that +.Fa lock +is not presently held for writing and no writer threads are +presently blocked on the lock. +If the read lock cannot be immediately acquired, the calling thread +blocks until it can acquire the lock. +.Pp +The +.Fn pthread_rwlock_timedrdlock +performs the same action, but will not wait beyond +.Fa abstime +to obtain the lock before returning. +.Pp +The +.Fn pthread_rwlock_tryrdlock +function performs the same action as +.Fn pthread_rwlock_rdlock , +but does not block if the lock cannot be immediately obtained (i.e., +the lock is held for writing or there are waiting writers). +.Pp +A thread may hold multiple concurrent read locks. +If so, +.Fn pthread_rwlock_unlock +must be called once for each lock obtained. +.Pp +The results of acquiring a read lock while the calling thread holds +a write lock are undefined. +.Pp +.\" ----- +The +.Fn pthread_rwlock_wrlock +function blocks until a write lock can be acquired against +.Fa lock . +.Pp +The +.Fn pthread_rwlock_timedwrlock +performs the same action, but will not wait beyond +.Fa abstime +to obtain the lock before returning. +.Pp +The +.Fn pthread_rwlock_trywrlock +function performs the same action as +.Fn pthread_rwlock_wrlock , +but does not block if the lock cannot be immediately obtained. +.Pp +The results are undefined if the calling thread already holds the +lock at the time the call is made. +.Pp +.\" ----- +The +.Fn pthread_rwlock_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_tryrdlock , +or +.Fn pthread_rwlock_trywrlock . +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_init +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +If successful, the +.Fn pthread_rwlock_destroy , +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_timedrdlock , +.Fn pthread_rwlock_tryrdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_timedwrlock , +.Fn pthread_rwlock_trywrlock , +and +.Fn pthread_rwlock_unlock +will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +The results are undefined if +.Fa lock +is not held by the calling thread. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +The +.Fn pthread_rwlock_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another read-write lock. +.It Bq Er EBUSY +The system has detected an attempt to re-initialize the object +referenced by +.Fa lock , +a previously initialized but not yet destroyed read/write lock. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the read-write lock. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_tryrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The time specified by +.Fa abstime +was reached before the lock could be obtained. +.El +.Pp +The +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_timedrdlock , +and +.Fn pthread_rwlock_tryrdlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The lock could not be acquired because the maximum number of read locks +against +.Fa lock +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_trywrlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The calling thread is not able to acquire the lock without blocking. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The time specified by +.Fa abstime +was reached before the lock could be obtained. +.El +.Pp +The +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_timedwrlock , +and +.Fn pthread_rwlock_trywrlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the read/write lock (for reading +or writing). +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EPERM +The current thread does not own the read/write lock. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutex 3 , +.Xr pthread_rwlockattr 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.\" ---------------------------------------------------------------------------- +.Sh BUGS +The +.Dv PTHREAD_PROCESS_SHARED +attribute is not supported. diff --git a/static/netbsd/man3/pthread_rwlockattr.3 b/static/netbsd/man3/pthread_rwlockattr.3 new file mode 100644 index 00000000..b6610478 --- /dev/null +++ b/static/netbsd/man3/pthread_rwlockattr.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: pthread_rwlockattr.3,v 1.11 2025/02/10 20:40:55 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_rwlockattr_init.3,v 1.7 2002/09/16 19:29:29 mini Exp $ +.\" +.Dd June 12, 2016 +.Dt PTHREAD_RWLOCKATTR 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_init , +.Nm pthread_rwlockattr_destroy , +.Nm pthread_rwlockattr_getpshared , +.Nm pthread_rwlockattr_setpshared +.Nd initialize, destroy or query read/write lock attributes +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Ft int +.Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_init +function is used to initialize a read/write lock attributes object. +.Pp +The +.Fn pthread_rwlockattr_destroy +function is used to destroy a read/write lock attribute object +previously created with +.Fn pthread_rwlockattr_init . +.Pp +The +.Fn pthread_rwlockattr_getpshared +function shall obtain the value of process-shared attribute from +the initialized attributes object referenced by +.Fa attr . +.Pp +The +.Fn pthread_rwlockattr_setpshared +function shall set the process-shared attribute in an initialized +attributes object referenced by +.Fa attr . +.Sh RETURN VALUES +If successful, +all these functions return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn pthread_rwlockattr_init +shall fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the read/write lock attributes object. +.El +.Pp +.Fn pthread_rwlockattr_init +and +.Fn pthread_rwlockattr_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.Fn pthread_rwlockattr_getpshared +and +.Fn pthread_rwlockattr_setpshared +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . +.Sh BUGS +The +.Fn pthread_rwlockattr_getpshared +and +.Fn pthread_rwlockattr_setpshared +functions are hidden by default since only thread shared attributes +are supported. diff --git a/static/netbsd/man3/pthread_schedparam.3 b/static/netbsd/man3/pthread_schedparam.3 new file mode 100644 index 00000000..cdb632d6 --- /dev/null +++ b/static/netbsd/man3/pthread_schedparam.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: pthread_schedparam.3,v 1.8 2017/07/03 21:32:51 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_schedparam.3,v 1.7 2002/09/16 19:29:29 mini Exp $ +.Dd July 9, 2010 +.Dt PTHREAD_SCHEDPARAM 3 +.Os +.Sh NAME +.Nm pthread_setschedparam , +.Nm pthread_getschedparam +.Nd thread scheduling parameter manipulation +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setschedparam "pthread_t thread" "int policy" "const struct sched_param *param" +.Ft int +.Fn pthread_getschedparam "pthread_t thread" "int * restrict policy" "struct sched_param * restrict param" +.Sh DESCRIPTION +The +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +functions set and get the scheduling parameters of individual threads. +The scheduling policy for a thread can be: +.Bl -tag -width SCHED_OTHER -offset indent +.It Dv SCHED_FIFO +First in, first out. +.It Dv SCHED_RR +Round-robin. +.It Dv SCHED_OTHER +The system default. +.El +.Pp +The thread priority (accessed via +.Va param->sched_priority ) +must be at least +.Dv PTHREAD_MIN_PRIORITY +and no more than +.Dv PTHREAD_MAX_PRIORITY . +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +.Fn pthread_setschedparam +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Va policy +is invalid. +.It Bq Er ENOTSUP +Invalid value for scheduling parameters. +.It Bq Er ESRCH +Non-existent thread +.Va thread . +.El +.Pp +.Fn pthread_getschedparam +may fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +Non-existent thread +.Va thread . +.El +.Sh SEE ALSO +.Xr pthread_attr_getschedparam 3 , +.Xr sched 3 +.Sh STANDARDS +Both functions conform to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_self.3 b/static/netbsd/man3/pthread_self.3 new file mode 100644 index 00000000..c3edf395 --- /dev/null +++ b/static/netbsd/man3/pthread_self.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: pthread_self.3,v 1.5 2017/10/23 01:03:23 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_self.3,v 1.10 2002/09/16 19:29:29 mini Exp $ +.\" +.Dd July 9, 2010 +.Dt PTHREAD_SELF 3 +.Os +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft pthread_t +.Fn pthread_self "void" +.Sh DESCRIPTION +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh RETURN VALUES +The return value is the thread ID. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_sigmask.3 b/static/netbsd/man3/pthread_sigmask.3 new file mode 100644 index 00000000..3286e11c --- /dev/null +++ b/static/netbsd/man3/pthread_sigmask.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: pthread_sigmask.3,v 1.9 2010/07/09 10:55:11 wiz Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_sigmask.3,v 1.10 2002/09/16 19:29:29 mini Exp $ +.Dd July 9, 2010 +.Dt PTHREAD_SIGMASK 3 +.Os +.Sh NAME +.Nm pthread_sigmask +.Nd examine and/or change a thread's signal mask +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.\" .In pthread.h +.In signal.h +.Ft int +.Fn pthread_sigmask "int how" "const sigset_t * restrict set" "sigset_t * restrict oset" +.Sh DESCRIPTION +The +.Fn pthread_sigmask +function examines and/or changes the calling thread's signal mask. +.Pp +If +.Fa set +is not +.Dv NULL , +it specifies a set of signals to be modified, and +.Fa how +specifies what to set the signal mask to: +.Bl -tag -width SIG_UNBLOCK +.It Dv SIG_BLOCK +Union of the current mask and +.Fa set . +.It Dv SIG_UNBLOCK +Intersection of the current mask and the complement of +.Fa set . +.It Dv SIG_SETMASK +.Fa set . +.El +.Pp +If +.Fa oset +is not +.Dv NULL , +the previous signal mask is stored in the location pointed to by +.Fa oset . +.Pp +.Dv SIGKILL +and +.Dv SIGSTOP +cannot be blocked, and will be silently ignored if included in the signal mask. +.Sh RETURN VALUES +If successful, +.Fn pthread_sigmask +returns 0. +Otherwise, an error is returned. +.Sh ERRORS +.Fn pthread_sigmask +shall fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa how +is not one of the defined values. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigwait 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/pthread_spin.3 b/static/netbsd/man3/pthread_spin.3 new file mode 100644 index 00000000..b5b11bfa --- /dev/null +++ b/static/netbsd/man3/pthread_spin.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: pthread_spin.3,v 1.6 2017/10/22 16:37:24 abhinav Exp $ +.\" +.\" Copyright (c) 2002, 2008, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_SPIN 3 +.Os +.Sh NAME +.Nm pthread_spin , +.Nm pthread_spin_init , +.Nm pthread_spin_destroy , +.Nm pthread_spin_lock , +.Nm pthread_spin_trylock , +.Nm pthread_spin_unlock +.Nd spin lock interface +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" +.Ft int +.Fn pthread_spin_destroy "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function is used to initialize a spin lock. +In the +.Nx +implementation the +.Fa pshared +parameter is currently unused and all spin locks exhibit the +.Dv PTHREAD_PROCESS_SHARED +property, implying that all spin locks may be +accessed by threads of multiple processes. +The results of calling +.Fn pthread_spin_init +with an already initialized lock are undefined. +.Pp +.\" ----- +The +.Fn pthread_spin_destroy +function is used to destroy a spin lock previously created with +.Fn pthread_spin_init . +It is undefined what happens if the function is called +when a thread holds the lock, or if the function is called +with an uninitialized spin lock. +.Pp +.\" ----- +The +.Fn pthread_spin_lock +function acquires a spin lock on +.Fa lock , +provided that +.Fa lock +is not presently held. +If the lock cannot be +immediately acquired, the calling thread repeatedly retries until it can +acquire the lock. +Undefined behavior may follow if the calling thread holds +the lock at the time the call is made. +.Pp +The +.Fn pthread_spin_trylock +function performs the same locking action, but does not block if the lock +cannot be immediately obtained; if the lock is held, the call fails. +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_spin_lock +or +.Fn pthread_spin_trylock . +The results are undefined if the lock is not held by the calling thread. +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, all described functions return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_spin_init +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.El +.Pp +The +.Fn pthread_spin_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa lock +parameter was +.Dv NULL +or the +.Fa pshared +parameter was neither +.Dv PTHREAD_PROCESS_SHARED +nor +.Dv PTHREAD_PROCESS_PRIVATE . +.El +.Pp +.\" ----- +The +.Fn pthread_spin_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_trylock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_spin_lock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.El +.Pp +The +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.\" ---------------------------------------------------------------------------- +.Sh CAVEATS +Applications using spin locks are vulnerable to the effects of priority +inversion. +Applications using real-time threads +.Pq Dv SCHED_FIFO , +.Pq Dv SCHED_RR +should not use these interfaces. +Outside carefully controlled environments, priority inversion with spin locks +can lead to system deadlock. +Mutexes are preferable in nearly every possible use case. diff --git a/static/netbsd/man3/pthread_suspend_np.3 b/static/netbsd/man3/pthread_suspend_np.3 new file mode 100644 index 00000000..453ea06a --- /dev/null +++ b/static/netbsd/man3/pthread_suspend_np.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: pthread_suspend_np.3,v 1.5 2010/07/09 09:18:45 jruoho Exp $ +.\" +.\" Copyright (c) 2003, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 9, 2010 +.Dt PTHREAD_SUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_suspend_np , +.Nm pthread_resume_np +.Nd suspend/resume the given thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_suspend_np "pthread_t thread" +.Ft int +.Fn pthread_resume_np "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_suspend_np +function suspends the +.Fa thread +given as argument. +If +.Fa thread +is the currently running thread as returned by +.Xr pthread_self 3 , +the function fails and returns +.Er EDEADLK . +Otherwise, it removes the named thread from the running queue, and +adds it to the suspended queue. +The +.Fa thread +will remain blocked until +.Fn pthread_resume_np +is called on it. +In other words, +.Fn pthread_resume_np +resumes the +.Fa thread +given as argument, if it was suspended. +.Sh RETURN VALUES +Both functions return 0 on success and an error number indicating the +reason for the failure. +.Sh COMPATIBILITY +These functions are non-standard extensions. +.Sh ERRORS +The +.Fn pthread_suspend_np +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The thread requested to suspend was the currently running thread. +.It Bq Er ESRCH +The supplied +.Fa thread +was invalid. +.El +.Pp +The +.Fn pthread_resume_np +function may fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The supplied +.Fa thread +was invalid. +.El +.Sh NOTES +Some +.Fn pthread_suspend_np +implementations may allow suspending the current thread. +This is dangerous, because the semantics of the function would then +require the scheduler to schedule another thread, causing a thread +context switch. +Since that context switch can happen in a signal handler by someone +calling +.Fn pthread_suspend_np +in a signal handler, this is currently not allowed. +.Pp +In +.Fn pthread_resume_np +the +.Nx +implementation does not check if the +.Fa thread +argument is not already suspended. +Some implementations might return an error condition if +.Fn pthread_resume_np +is called on a non-suspended thread. +.Sh SEE ALSO +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_self 3 diff --git a/static/netbsd/man3/pthread_testcancel.3 b/static/netbsd/man3/pthread_testcancel.3 new file mode 100644 index 00000000..5de4ee97 --- /dev/null +++ b/static/netbsd/man3/pthread_testcancel.3 @@ -0,0 +1,271 @@ +.\" $NetBSD: pthread_testcancel.3,v 1.10 2025/03/05 16:38:50 riastradh Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libpthread/man/pthread_testcancel.3,v 1.9 2002/09/16 19:29:29 mini Exp $ +.Dd August 6, 2010 +.Dt PTHREAD_TESTCANCEL 3 +.Os +.Sh NAME +.Nm pthread_setcancelstate , +.Nm pthread_setcanceltype , +.Nm pthread_testcancel +.Nd set cancelability state +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setcancelstate "int state" "int *oldstate" +.Ft int +.Fn pthread_setcanceltype "int type" "int *oldtype" +.Ft void +.Fn pthread_testcancel "void" +.Sh DESCRIPTION +The +.Fn pthread_setcancelstate +function atomically both sets the calling thread's cancelability state +to the indicated +.Fa state +and, if +.Fa oldstate +is not +.Dv NULL , +returns the previous cancelability state at the location referenced by +.Fa oldstate . +Legal values for +.Fa state +are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DISABLE . +.Pp +The +.Fn pthread_setcanceltype +function atomically both sets the calling thread's cancelability type +to the indicated +.Fa type +and, if +.Fa oldtype +is not +.Dv NULL , +returns the previous cancelability type at the location referenced by +.Fa oldtype . +Legal values for +.Fa type +are +.Dv PTHREAD_CANCEL_DEFERRED +and +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.Pp +The cancelability state and type of any newly created threads, including the +thread in which +.Fn main +was first invoked, are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DEFERRED +respectively. +.Pp +The +.Fn pthread_testcancel +function creates a cancellation point in the calling thread. +The +.Fn pthread_testcancel +function has no effect if cancelability is disabled. +.Ss Cancelability States +The cancelability state of a thread determines the action taken upon +receipt of a cancellation request. +The thread may control cancellation in +a number of ways. +.Pp +Each thread maintains its own +.Dq cancelability state +which may be encoded in two bits: +.Bl -hang +.It Em Cancelability Enable : +When cancelability is +.Dv PTHREAD_CANCEL_DISABLE , +cancellation requests against the target thread are held pending. +.It Em Cancelability Type : +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_ASYNCHRONOUS , +new or pending cancellation requests may be acted upon at any time. +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_DEFERRED , +cancellation requests are held pending until a cancellation point (see +below) is reached. +If cancelability is disabled, the setting of the +cancelability type has no immediate effect as all cancellation requests +are held pending; however, once cancelability is enabled again the new +type will be in effect. +.El +.Ss Cancellation Points +Cancellation points will occur when a thread is executing the following +functions: +.Fn accept , +.Fn aio_suspend , +.Fn clock_nanosleep , +.Fn close , +.Fn connect , +.Fn creat , +.Fn fcntl , +.Fn fdatasync , +.Fn fsync , +.Fn fsync_range , +.\".Fn getmsg , +.\".Fn getpmsg , +.Fn kevent , +.\".Fn lockf , +.Fn mq_receive , +.Fn mq_send , +.Fn mq_timedreceive , +.Fn mq_timedsend , +.Fn msgrcv , +.Fn msgsnd , +.Fn msync , +.Fn nanosleep , +.Fn open , +.Fn pause , +.Fn poll , +.Fn pollts , +.Fn pread , +.Fn pselect , +.Fn pthread_cond_timedwait , +.Fn pthread_cond_wait , +.Fn pthread_join , +.Fn pthread_testcancel , +.\".Fn putmsg , +.\".Fn putpmsg , +.Fn pwrite , +.Fn read , +.Fn readv , +.Fn recv , +.Fn recvfrom , +.Fn recvmsg , +.Fn select , +.Fn sem_timedwait , +.Fn sem_wait , +.Fn send , +.Fn sendmsg , +.Fn sendto , +.Fn sigpause , +.Fn sigsuspend , +.Fn sigtimedwait , +.Fn sigwait , +.Fn sigwaitinfo , +.Fn sleep , +.Fn system , +.Fn tcdrain , +.Fn usleep , +.Fn wait , +.Fn wait4 , +.Fn waitid , +.Fn waitpid , +.Fn write , +and +.Fn writev . +.Sh RETURN VALUES +If successful, the +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions will return zero. +Otherwise, an error number shall be returned to +indicate the error. +.Pp +The +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions are used to control the points at which a thread may be +asynchronously canceled. +For cancellation control to be usable in modular +fashion, some rules must be followed. +.Pp +For purposes of this discussion, consider an object to be a generalization +of a procedure. +It is a set of procedures and global variables written as +a unit and called by clients not known by the object. +Objects may depend +on other objects. +.Pp +First, cancelability should only be disabled on entry to an object, never +explicitly enabled. +On exit from an object, the cancelability state should +always be restored to its value on entry to the object. +.Pp +This follows from a modularity argument: if the client of an object (or the +client of an object that uses that object) has disabled cancelability, it is +because the client doesn't want to have to worry about how to clean up if the +thread is canceled while executing some sequence of actions. +If an object +is called in such a state and it enables cancelability and a cancellation +request is pending for that thread, then the thread will be canceled, +contrary to the wish of the client that disabled. +.Pp +Second, the cancelability type may be explicitly set to either +.Em deferred +or +.Em asynchronous +upon entry to an object. +But as with the cancelability state, on exit from +an object that cancelability type should always be restored to its value on +entry to the object. +.Pp +Finally, only functions that are cancel-safe may be called from a thread that +is asynchronously cancelable. +.Sh ERRORS +The function +.Fn pthread_setcancelstate +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_ENABLE +or +.Dv PTHREAD_CANCEL_DISABLE . +.El +.Pp +The function +.Fn pthread_setcanceltype +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_DEFERRED +or +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.El +.Sh SEE ALSO +.Xr pthread_cancel 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh AUTHORS +This man page was written by +.An David Leonard Aq Mt d@openbsd.org +for the +.Ox +implementation of +.Xr pthread_cancel 3 . diff --git a/static/netbsd/man3/ptsname.3 b/static/netbsd/man3/ptsname.3 new file mode 100644 index 00000000..0a86aaee --- /dev/null +++ b/static/netbsd/man3/ptsname.3 @@ -0,0 +1,168 @@ +.\" $NetBSD: ptsname.3,v 1.13 2022/01/02 03:46:40 uwe Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 2, 2022 +.Dt PTSNAME 3 +.Os +.Sh NAME +.Nm ptsname , +.Nm ptsname_r +.Nd get the pathname of the slave pseudo-terminal device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft char * +.Fn ptsname "int masterfd" +.Ft int +.Fn ptsname_r "int masterfd" "char *buf" "size_t buflen" +.Sh DESCRIPTION +The +.Fn ptsname +function returns the pathname of the slave pseudo-terminal device +that corresponds to the master pseudo-terminal device associated with +.Fa masterfd . +The +.Fn ptsname +function is not reentrant or thread-safe. +.Pp +The +.Fn ptsname_r +function +places the pathname of the slave pseudo-terminal device that corresponds +to the master pseudo-terminal device associated with +.Fa masterfd +int the +.Fa buf +argument copying up to +.Fa buflen +characters. +The +.Fa buf +is always +.Dv NUL +terminated. +.Sh RETURN VALUES +If successful, +.Fn ptsname +returns a pointer to a nul-terminated string containing the pathname +of the slave pseudo-terminal device. +If an error occurs +.Fn ptsname +will return +.Dv NULL +and +.Va errno +is set to indicate the error. +.Pp +If successful, +.Fn ptsname_r +places a nul-terminated string containing the pathname +of the slave pseudo-terminal device +in +.Fa buf +and returns +.Dv 0 . +If an error occurs +.Fn ptsname_r +will return +an error number indicating what went wrong. +.Sh ERRORS +The +.Fn ptsname +and +.Fn ptsname_r +functions will fail if: +.Bl -tag -width Er +.It Bq Er EACCESS +the corresponding pseudo-terminal device could not be accessed. +.It Bq Er EBADF +.Fa masterfd +is not a valid descriptor. +.It Bq Er EINVAL +.Fa masterfd +is not associated with a master pseudo-terminal device. +.El +.Pp +In addition the +.Fn ptsname_r +function +will return: +.Bl -tag -width Er +.It Bq Er EINVAL +the +.Fa buf +argument is +.Dv NULL . +.It Bq Er ERANGE +the name of the pseudo-terminal is longer than +.Fa bufsiz +characters plus the terminating +.Dv NUL . +.El +.Sh NOTES +The error returns of +.Fn ptsname +are a +.Nx +extension. +The +.Fn ptsname +function is equivalent to: +.Bd -literal + static struct ptmget pm; + return ioctl(masterfd, TIOCPTSNAME, &pm) == -1 ? NULL : pm.sn; +.Ed +.Pp +Both the +.Fn ptsname +and +.Fn ptsname_r +functions will also return the name of the slave pseudo-terminal if a file +descriptor to the slave pseudo-terminal is passed to +.Fa masterfd . +.Pp +This is a convenient extension because it allows one to use the file descriptor +obtained by +.Xr open 2 +.Pa /dev/tty +to obtain the name of the pseudo-terminal for the current process. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr open 2 , +.Xr grantpt 3 , +.Xr posix_openpt 3 , +.Xr unlockpt 3 +.Sh STANDARDS +The +.Fn ptsname +function conforms to +.St -p1003.1-2001 . +Its first release was in +.St -xpg4.2 . diff --git a/static/netbsd/man3/puffs.3 b/static/netbsd/man3/puffs.3 new file mode 100644 index 00000000..bcd0ef13 --- /dev/null +++ b/static/netbsd/man3/puffs.3 @@ -0,0 +1,595 @@ +.\" $NetBSD: puffs.3,v 1.67 2022/01/22 07:35:26 pho Exp $ +.\" +.\" Copyright (c) 2006, 2007, 2008 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 10, 2016 +.Dt PUFFS 3 +.Os +.Sh NAME +.Nm puffs +.Nd Pass-to-Userspace Framework File System development interface +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft struct puffs_usermount * +.Fo puffs_init +.Fa "struct puffs_ops *pops" "const char *mntfromname" "const char *puffsname" +.Fa "void *private" "uint32_t flags" +.Fc +.Ft int +.Fo puffs_mount +.Fa "struct puffs_usermount *pu" "const char *dir" "int mntflags" +.Fa "puffs_cookie_t root_cookie" +.Fc +.Ft int +.Fn puffs_getselectable "struct puffs_usermount *pu" +.Ft int +.Fn puffs_setblockingmode "struct puffs_usermount *pu" "int mode" +.Ft int +.Fn puffs_getstate "struct puffs_usermount *pu" +.Ft int +.Fn puffs_setstacksize "struct puffs_usermount *pu" "size_t stacksize" +.Ft void +.Fn puffs_setroot "struct puffs_usermount *pu" "struct puffs_node *node" +.Ft void +.Fo puffs_setrootinfo +.Fa "struct puffs_usermount *pu" "enum vtype vt" "size_t vsize" "dev_t rdev" +.Fc +.Ft struct puffs_node * +.Fn puffs_getroot "struct puffs_usermount *pu" +.Ft void * +.Fn puffs_getspecific "struct puffs_usermount *pu" +.Ft void +.Fn puffs_setspecific "struct puffs_usermount *pu" "void *private" +.Ft void +.Fn puffs_setmaxreqlen "struct puffs_usermount *pu" "size_t maxreqlen" +.Ft size_t +.Fn puffs_getmaxreqlen "struct puffs_usermount *pu" +.Ft void +.Fn puffs_setfhsize "struct puffs_usermount *pu" "size_t fhsize" "int flags" +.Ft void +.Fn puffs_setncookiehash "struct puffs_usermount *pu" "int nhashes" +.Ft void +.Fn puffs_ml_loop_fn "struct puffs_usermount *pu" +.Ft void +.Fn puffs_ml_setloopfn "struct puffs_usermount *pu" "puffs_ml_loop_fn lfn" +.Ft void +.Fn puffs_ml_settimeout "struct puffs_usermount *pu" "struct timespec *ts" +.Ft int +.Fn puffs_daemon "struct puffs_usermount *pu" "int nochdir" "int noclose" +.Ft int +.Fn puffs_mainloop "struct puffs_usermount *pu" +.Ft int +.Fn puffs_unmountonsignal "int sig" "bool ignoresig" +.Ft int +.Fo puffs_dispatch_create +.Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pb" +.Fa "struct puffs_cc **pccp" +.Fc +.Ft int +.Fn puffs_dispatch_exec "struct puffs_cc *pcc" "struct puffs_framebuf **pbp" +.Sh DESCRIPTION +.Nm +provides a framework for creating file systems as userspace servers. +Operations are transported from the kernel virtual file system layer +to the concrete implementation behind +.Nm , +where they are processed and results are sent back to the kernel. +.Pp +It is possible to use +.Nm +in two different ways. +Calling +.Fn puffs_mainloop +takes execution context away from the caller and automatically handles +all requests by using the callbacks. +By using +.Xr puffs_framebuf 3 +in conjunction with +.Fn puffs_mainloop , +it is possible to handle I/O to and from file descriptors. +This is suited e.g. for distributed file servers. +.Ss Library operation +Operations on the library always require a pointer to the opaque context +identifier, +.Va struct puffs_usermount . +It is obtained by calling +.Fn puffs_init . +.Pp +.Nm +operates using operation callbacks. +They can be initialized using the macro +.Fn PUFFSOP_SET pops fsname type opname , +which will initialize the operation +.Fn puffs_type_opname +in +.Fa pops +to +.Fn fsname_type_opname . +All operations are initialized to a default state with the call +.Fn PUFFSOP_INIT pops . +All of the VFS routines are mandatory, but all of the node operations +with the exception of +.Fn puffs_node_lookup +are optional. +However, leaving operations blank will naturally have an effect on the +features available from the file system implementation. +.Bl -tag -width xxxx +.It Fn puffs_init pops mntfromname puffsname private flags +Initializes the library context. +.Ar pops +specifies the callback operations vector. +.Ar mntfromname +is device the file system is mounted from. +This can be for example a block device such as +.Pa /dev/wd0a +or, if the file system is pseudo file system, the +.Nm +device name can be given by +.Dv _PATH_PUFFS . +This value is used for example in the first column of the output of +.Xr mount 8 +and +.Xr df 1 . +.Ar puffsname +is the file system type. +It will always be prepended with the string "puffs|". +If possible, file server binaries should be named using the format +"mount_myfsnamehere" and this value should equal "myfsnamehere". +A file system specific context pointer can optionally be given in +.Ar private . +This can be retrieved by +.Fn puffs_getspecific . +Flags for +.Nm +can be given via +.Fa flags . +Currently the following flags are supported: +.Bl -tag -width "XPUFFS_KFLAG_LOOKUP_FULLPNBUF" +.It Dv PUFFS_KFLAG_NOCACHE_NAME +Do not enter pathname components into the name cache. +This means that every time the kernel does a lookup for a +componentname, the file server will be consulted. +.It Dv PUFFS_KFLAG_NOCACHE_PAGE +Do not use the page cache. +This means that all reads and writes to regular file are +propagated to the file server for handling. +This option makes a difference only for regular files. +.It Dv PUFFS_KFLAG_NOCACHE +An alias for both +.Dv PUFFS_KFLAG_NOCACHE_NAME +and +.Dv PUFFS_KFLAG_NOCACHE_PAGE . +.It Dv PUFFS_KFLAG_ALLOPS +This flag requests that all operations are sent to userspace. +Normally the kernel shortcircuits unimplemented operations. +This flag is mostly useful for debugging purposes. +.It Dv PUFFS_KFLAG_WTCACHE +Set the file system cache behavior as write-through. +This means that all writes are immediately issued to the file server +instead of being flushed in file system sync. +This is useful especially for distributed file systems. +.It Dv PUFFS_KFLAG_IAONDEMAND +Issue inactive only on demand. +If a file server defines the inactive method, call it only if the file +server has explicitly requested that inactive be called for the +node in question. +Once inactive has been called for a node, it will not be called +again unless the request to call inactive is reissued by the file server. +See +.Fn puffs_setback +in +.Xr puffs_ops 3 +for more information. +.It Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF +This flag affects only the parameter +.Ar pcn to +.Fn puffs_node_lookup . +If this flag is not given, only the next pathname component under +lookup is found from +.Ar pcn->pcn_name . +If this flag is given, the full path the kernel was +asked to resolve can be found from there. +.It Dv PUFFS_FLAG_BUILDPATH +The framework will build a complete path name, which is supplied +with each operation and can be found from the +.Va pcn_po_full.po_path +field in a +.Vt struct puffs_cn . +The option assumes that the framework can map a cookie to a +.Vt struct puffs_node . +See +.Sx Cookies +for more information on cookie mapping. +See +.Xr puffs_path 3 +for more information on library calls involving paths. +.It Dv PUFFS_FLAG_HASHPATH +Calculate a hash of the path into the path object field +.Va po_hash . +This hash value is used by +.Fn puffs_path_walkcmp +to avoid doing a full comparison for every path equal in length to +the one searched for. +Especially if the file system uses the abovementioned function, it +is a good idea to define this flag. +.It Dv PUFFS_FLAG_PNCOOKIE +Tell puffs that cookies map to +.Vt struct pnode . +This is automagically set if +.Fn puffs_pn_new +is called. +.It Dv PUFFS_KFLAG_CACHE_FS_TTL +Enforce name and attribute caches based on file system-supplied TTL. +In lookup, create, mknod, mkdir, and symlink, the file system must +update the node attributes, their TTL, and the node name TTL through +.Fn puffs_newinfo_setva , +.Fn puffs_newinfo_setvattl , +and +.Fn puffs_newinfo_setcnttl . +.Pp +Additionally, +.Fn puffs_node_getattr_ttl +and +.Fn puffs_node_setattr_ttl +will be called instead of +.Fn puffs_node_getattr +and +.Fn puffs_node_setattr . +.It Dv PUFFS_KFLAG_CACHE_DOTDOT +Never send lookups for +.Dq .. +to the file system. +Parent vnodes are all kept active until their children are reclaimed. +.It Dv PUFFS_KFLAG_NOFLUSH_META +Do not send metadata cache flushes for time and size to the file system, +which should take care of updating the values on its own. +.It Dv PUFFS_FLAG_OPDUMP +This option makes the framework dump a textual representation of +each operation before executing it. +It is useful for debugging purposes. +.El +.El +.Pp +The following functions can be used to query or modify the global +state of the file system. +Note, that all calls are not available at all times. +.Bl -tag -width xxxx +.It Fn puffs_getselectable "pu" +Returns a handle to do I/O multiplexing with: +.Xr select 2 , +.Xr poll 2 , +and +.Xr kqueue 2 +are all examples of acceptable operations. +.It Fn puffs_setblockingmode "pu" "mode" +Sets the file system upstream access to blocking or non-blocking mode. +Acceptable values for the argument are +.Dv PUFFSDEV_BLOCK +and +.Dv PUFFSDEV_NONBLOCK . +.Pp +This routine can be called only after calling +.Fn puffs_mount . +.It Fn puffs_getstate "pu" +Returns the state of the file system. +It is maintained by the framework and is mostly useful for the framework +itself. +Possible values are +.Dv PUFFS_STATE_BEFOREMOUNT , +.Dv PUFFS_STATE_RUNNING , +.Dv PUFFS_STATE_UNMOUNTING +and +.Dv PUFFS_STATE_UNMOUNTED . +.It Fn puffs_setstacksize "pu" "stacksize" +Sets the stack size used when running callbacks. +The default is +.Dv PUFFS_STACKSIZE_DEFAULT +bytes of stack space per request. +The minimum stacksize is architecture-dependent and can be specified +by using the opaque constant +.Dv PUFFS_STACKSIZE_MIN . +.It Fn puffs_setroot "pu" "node" +Sets the root node of mount +.Fa pu +to +.Fa "node" . +Setting the root node is currently required only if the path +framework is used, see +.Xr puffs_path 3 . +.It Fn puffs_setrootinfo pu vt vsize rdev +The default root node is a directory. +In case the file system wants something different, it can call this +function and set the type, size and possible device type to whatever +it wants. +This routine is independent of +.Fn puffs_setroot . +.It Fn puffs_getroot "pu" +Returns the root node set earlier. +.It Fn puffs_getspecific "pu" +Returns the +.Fa private +argument of +.Fn puffs_init . +.It Fn puffs_setspecific "pu" "private" +Can be used to set the specific data after the call to +.Fn puffs_init . +.It Fn puffs_setmaxreqlen "pu" "maxreqlen" +In case the file system desires a maximum buffer length different from +the default, the amount +.Fa maxreqlen +will be requested from the kernel when the file system is mounted. +.Pp +It is legal to call this function only between +.Fn puffs_init +and +.Fn puffs_mount . +.Pp +.Em NOTE +This does not currently work. +.It Fn puffs_getmaxreqlen "pu" +Returns the maximum request length the kernel will need for a single +request. +.Pp +.Em NOTE +This does not currently work. +.It Fn puffs_setfhsize "pu" "fhsize" "flags" +Sets the desired file handle size. +This must be called if the file system wishes to support NFS exporting +file systems of the +.Fn fh* +family of function calls. +.Pp +In case all nodes in the file system produce the same length file handle, +it must be supplied as +.Fa fhsize . +In this case, the file system may ignore the length parameters in the +file handle callback routines, as the kernel will always pass the +correct length buffer. +However, if the file handle size varies according to file, the argument +.Fa fhsize +defines the maximum size of a file handle for the file system. +In this case the file system must take care of the handle lengths by +itself in the file handle callbacks, see +.Xr puffs_ops 3 +for more information. +Also, the flag +.Dv PUFFS_FHFLAG_DYNAMIC +must be provided in the argument +.Fa flags . +.Pp +In case the file system wants to sanity check its file handle lengths +for the limits of NFS, it can supply +.Dv PUFFS_FHFLAG_NFSV2 +and +.Dv PUFFS_FHFLAG_NFSV3 +in the +.Fa flags +parameter. +It is especially important to note that these are not directly the +limits specified by the protocols, as the kernel uses some bytes from +the buffer space. +In case the file handles are too large, mount will return an error. +.Pp +It is legal to call this function only between +.Fn puffs_init +and +.Fn puffs_mount . +.It Fn puffs_setncookiehash "pu" "ncookiehash" +The parameter +.Fa ncookiehash +controls the amount of hash buckets the kernel has for reverse lookups +from cookie to vnode. +Technically the default is enough, but a memory/time tradeoff can be +made by increasing this for file systems which know they will have +very many active files. +.Pp +It is legal to call this function only between +.Fn puffs_init +and +.Fn puffs_mount . +.El +.Pp +After the correct setup for the library has been established and the +backend has been initialized the file system is made operational by calling +.Fn puffs_mount . +After this function returns the file system should start processing requests. +.Bl -tag -width xxxx +.It Fn puffs_mount pu dir mntflags root_cookie +.Ar pu +is the library context pointer from +.Fn puffs_init . +The argument +.Fa dir +signifies the mount point and +.Fa mntflags +is the flagset given to +.Xr mount 2 . +The value +.Ar root_cookie +will be used as the cookie for the file system root node. +.El +.Ss Using the built-in eventloop +.Bl -tag -width xxxx +.It Fn puffs_ml_loop_fn pu +Loop function signature. +.It Fn puffs_ml_setloopfn pu lfn +Set loop function to +.Ar lfn . +This function is called once each time the event loop loops. +It is not a well-defined interval, but it can be made fairly regular +by setting the loop timeout by +.Fn puffs_ml_settimeout . +.It Fn puffs_ml_settimeout pu ts +Sets the loop timeout to +.Ar ts +or disables it if +.Ar ts +is +.Dv NULL . +This can be used to roughly control how often the loop callback +.Fn lfn +is called +.It Fn puffs_daemon pu nochdir noclose +Detach from the console like +.Fn daemon 3 . +If it is called before +.Fn puffs_mount , +this call synchronizes with +.Fn puffs_mount +and the foreground process does not exit before the file system mount +call has returned from the kernel. +Since this routine internally calls fork, it is highly recommended to call it +.Em before +.Fn puffs_mount . +.It Fn puffs_mainloop pu flags +Handle all requests automatically until the file system is unmounted. +It returns 0 if the file system was successfully unmounted or \-1 if it +was killed in action. +.Pp +In case +.Xr puffs_framebuf 3 +has been initialized, I/O from the relevant descriptors is processed +automatically by the eventloop. +.It Fn puffs_unmountonsignal signum ignoresig +Cause all file servers within the process to initiate unmount upon +receipt of signal +.Ar signum . +This works only for servers which call +.Fn puffs_mainloop +and must be called before any server within the process enters the mainloop. +The process signal handler is still called before starting the unmount +procedure. +The parameter +.Ar ignoresig +is provided as a convenience and tells if to install a signal handler +to ignore +.Ar sig +so that the process will not e.g. terminate based on the default action +before the file system unmount can be initiated. +.It Fn puffs_dispatch_create pu pb pccp +.It Fn puffs_dispatch_exec pcc pbp +In case the use of +.Fn puffs_mainloop +is not possible, requests may be dispatched manually. +However, as this is less efficient than using the mainloop, +it should never be the first preference. +.Pp +Calling +.Fn puffs_dispatch_create +creates a dispatch request. +The argument +.Ar pb +should contains a valid request and upon success +.Ar pccp +will contain a valid request context. +This context is passed to +.Fn puffs_dispatch_exec +to execute the request. +If the request yielded before completing, the routine returns 0, +otherwise 1. +When the routine completes, +.Ar pcc +is made invalid and a pointer to the processed buffer is placed in +.Ar pbp . +It is the responsibility of the caller to send the response (if +necessary) and destroy the buffer. +.Pp +See +.Xr puffs_cc 3 +and +.Xr puffs_framebuf 3 +for further information. +.El +.Ss Cookies +Every file (regular file, directory, device node, ...) instance is +attached to the kernel using a cookie. +A cookie should uniquely map to a file during its lifetime. +If file instances are kept in memory, a simple strategy is to use +the virtual address of the structure describing the file. +The cookie can be recycled when +.Fn puffs_node_reclaim +is called for a node. +.Pp +For some operations (such as building paths) the framework needs to map +the cookie to the framework-level structure describing a file, +.Vt struct puffs_node . +It is advisable to simply use the +.Vt struct puffs_node +address as a cookie and store file system specific data in the private +portion of +.Vt struct puffs_node . +The library assumes this by default. +If it is not desirable, the file system implementation can call +.Fn puffs_set_cookiemap +to provide an alternative cookie-to-node mapping function. +.Sh SEE ALSO +.Xr mount 2 , +.Xr puffs_cc 3 , +.Xr puffs_cred 3 , +.Xr puffs_flush 3 , +.Xr puffs_framebuf 3 , +.Xr puffs_node 3 , +.Xr puffs_ops 3 , +.Xr puffs_path 3 , +.Xr refuse 3 , +.Xr puffs 4 +.Rs +.%A Antti Kantee +.%D March 2007 +.%J Proceedings of AsiaBSDCon 2007 +.%P pp. 29-42 +.%T puffs - Pass-to-Userspace Framework File System +.Re +.Rs +.%A Antti Kantee +.%D September 2007 +.%I Helsinki University of Technology +.%R Tech Report TKK-TKO-B157 +.%T Using puffs for Implementing Client-Server Distributed File Systems +.Re +.Rs +.%A Antti Kantee +.%A Alistair Crooks +.%D September 2007 +.%J EuroBSDCon 2007 +.%T ReFUSE: Userspace FUSE Reimplementation Using puffs +.Re +.Rs +.%A Antti Kantee +.%D March 2008 +.%J Proceedings of AsiaBSDCon 2008 +.%P pp. 55-70 +.%T Send and Receive of File System Protocols: Userspace Approach With puffs +.Re +.Sh HISTORY +An unsupported experimental version of +.Nm +first appeared in +.Nx 4.0 . +A stable version appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Antti Kantee Aq Mt pooka@iki.fi diff --git a/static/netbsd/man3/puffs_cc.3 b/static/netbsd/man3/puffs_cc.3 new file mode 100644 index 00000000..bee49908 --- /dev/null +++ b/static/netbsd/man3/puffs_cc.3 @@ -0,0 +1,94 @@ +.\" $NetBSD: puffs_cc.3,v 1.14 2009/04/11 16:48:53 wiz Exp $ +.\" +.\" Copyright (c) 2007, 2008 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 28, 2008 +.Dt PUFFS_CC 3 +.Os +.Sh NAME +.Nm puffs_cc +.Nd puffs continuation routines +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft void +.Fn puffs_cc_yield "struct puffs_cc *pcc" +.Ft void +.Fn puffs_cc_continue "struct puffs_cc *pcc" +.Ft void +.Fn puffs_cc_schedule "struct puffs_cc *pcc" +.Ft struct puffs_cc * +.Fn puffs_cc_getcc "struct puffs_usermount *pu" +.Sh DESCRIPTION +These routines are used for the cooperative multitasking suite present +in puffs. +.Pp +.Bl -tag -width xxxx +.It Fn puffs_cc_yield "pcc" +Suspend and save the current execution context and return control +to the previous point. +In practice, from the file system author perspective, control returns +back to where either the mainloop or where +.Fn puffs_dispatch_exec +was called from. +.It Fn puffs_cc_continue pcc +Will suspend current execution and return control to where it was +before before calling +.Fn puffs_cc_yield . +This is rarely called directly but rather through +.Fn puffs_dispatch_exec . +.It Fn puffs_cc_schedule "pcc" +Schedule a continuation. +As opposed to +.Fn puffs_cc_continue +this call returns immediately. +.Fa pcc +will be scheduled sometime in the future. +.It Fn puffs_cc_getcc "pu" +Returns the current pcc or +.Dv NULL +if this is the main thread. +.Em NOTE : +The argument +.Ar pu +will most likely disappear at some point. +.El +.Pp +Before calling +.Fn puffs_cc_yield +a file system will typically want to record some cookie value into its +own internal bookkeeping. +This cookie should be hooked to the +.Va pcc +so that the correct continuation can be continued when the event it +was waiting for triggers. +Alternatively, the +.Xr puffs_framebuf 3 +framework and +.Fn puffs_mainloop +can be used for handling this automatically. +.Sh SEE ALSO +.Xr puffs 3 , +.Xr puffs_framebuf 3 diff --git a/static/netbsd/man3/puffs_cred.3 b/static/netbsd/man3/puffs_cred.3 new file mode 100644 index 00000000..cd1e6913 --- /dev/null +++ b/static/netbsd/man3/puffs_cred.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: puffs_cred.3,v 1.5 2009/04/11 15:36:22 joerg Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 18, 2007 +.Dt PUFFS_CRED 3 +.Os +.Sh NAME +.Nm puffs_cred +.Nd puffs credential and access control routines +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft int +.Fn puffs_cred_getuid "const struct puffs_cred *pcr" "uid_t *uid" +.Ft int +.Fn puffs_cred_getgid "const struct puffs_cred *pcr" "gid_t *gid" +.Ft int +.Fo puffs_cred_getgroups +.Fa "const struct puffs_cred *pcr" "gid_t *gids" "short *ngids" +.Fc +.Pp +.Ft bool +.Fn puffs_cred_isuid "const struct puffs_cred *pcr" "uid_t uid" +.Ft bool +.Fn puffs_cred_hasgroup "const struct puffs_cred *pcr" "gid_t gid" +.Ft bool +.Fn puffs_cred_iskernel "const struct puffs_cred *pcr" +.Ft bool +.Fn puffs_cred_isfs "const struct puffs_cred *pcr" +.Ft bool +.Fn puffs_cred_isjuggernaut "const struct puffs_cred *pcr" +.Pp +.Ft int +.Fo puffs_access +.Fa "enum vtype type" "mode_t file_mode" "uid_t owner" "gid_t group" +.Fa "mode_t access_mode" "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_access_chown +.Fa "uid_t owner" "gid_t group" "uid_t newowner" "gid_t newgroup" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_access_chmod +.Fa "uid_t owner" "gid_t group" "enum vtype type" "mode_t newmode" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_access_times +.Fa "uid_t owner" "gid_t group" "mode_t file_mode" "int va_utimes_null" +.Fa "const struct puffs_cred *pcr" +.Fc +.Sh DESCRIPTION +These functions can be used to check operation credentials and perform +access control. +The structure +.Vt struct puffs_cred +can contain two types of credentials: ones belonging to users and +ones belonging to the kernel. +The latter is further divided into generic kernel credentials and +file system credentials. +The general rule is that these should be treated as more powerful +than superuser credentials, but the file system is free to treat +them as it sees fit. +.Ss Credentials +The +.Fn puffs_cred_get +family of functions fetch the uid or gid(s) from the given credential +cookie. +They return 0 for success or \-1 for an error and set +.Va errno . +An error happens when the credentials represent kernel or file system +credentials and do not contain an uid or gid(s). +.Pp +For +.Fn puffs_cred_getgroups , +the argument +.Fa gids +should point to an array with room for +.Fa *ngids +elements. +.Pp +The +.Fn puffs_cred_is +family of functions return 1 if the truth value of the function for +.Fa pcr +is true and 0 if it is false. +The function +.Fn puffs_cred_isjuggernaut +is true if +.Fa pcr +describes superuser, kernel or file system credentials. +.Ss Access Control +To help the programmers task of emulating normal kernel file system +access control semantics, several helper functions are provided to +check if access is allowed. +They return 0 if access should be permitted or an errno value to +indicate that access should be denied with the returned value. +.Pp +.Fn puffs_access +is equivalent to the kernel +.Fn vaccess +function. +The arguments specify current information of the file to be +tested with the exception of +.Fa access_mode , +which is a combination of +.Dv PUFFS_VREAD , +.Dv PUFFS_VWRITE +and +.Dv PUFFS_VEXEC +indicating the desired file access mode. +.Pp +The rest of the functions provide UFS semantics for operations. +.Fn puffs_access_chown +checks if it is permissible to chown a file with the current uid +and gid to the new uid and gid with the credentials of +.Fa pcr . +.Pp +.Fn puffs_access_chmod +checks against permission to chmod a file of type +.Fa type +to the mode +.Fa newmode . +.Pp +Finally, +.Fn puffs_access_times +checks if it is allowable to update the timestamps of a file. +The argument +.Fa va_utimes_null +signals if the flags +.Dv VA_UTIMES_NULL +was set in +.Fa va_vaflags +of +.Va struct vattr . +If coming from a path where this information is unavailable, passing +0 as this argument restricts the permission of modification to the +owner and superuser. +Otherwise the function checks for write permissions to the node and +returns success if the caller has write permissions. +.Sh SEE ALSO +.Xr puffs 3 , +.Xr vnode 9 diff --git a/static/netbsd/man3/puffs_flush.3 b/static/netbsd/man3/puffs_flush.3 new file mode 100644 index 00000000..a139ac7d --- /dev/null +++ b/static/netbsd/man3/puffs_flush.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: puffs_flush.3,v 1.8 2009/02/20 14:26:56 pooka Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 7, 2007 +.Dt PUFFS_FLUSH 3 +.Os +.Sh NAME +.Nm puffs_flush +.Nd puffs kernel cache flushing and invalidation routines +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft int +.Fo puffs_inval_namecache_dir +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" +.Fc +.Ft int +.Fn puffs_inval_namecache_all "struct puffs_usermount *pu" +.Ft int +.Fo puffs_inval_pagecache_node +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" +.Fc +.Ft int +.Fo puffs_inval_pagecache_node_range +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "off_t start" +.Fa "off_t end" +.Fc +.Ft int +.Fo puffs_flush_pagecache_node +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" +.Fc +.Ft int +.Fo puffs_flush_pagecache_node_range +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "off_t start" +.Fa "off_t end" +.Fc +.Sh DESCRIPTION +These routines are used inform the kernel that any information it might +have cached is no longer valid. +.Fn puffs_inval_namecache_dir +invalidates the name cache for a given directory. +The argument +.Va cookie +should describe an existing and valid directory cookie for the file +system. +Similarly, +.Fn puffs_inval_namecache_all +invalidates the name cache for the entire file system +(this routine might go away). +.Pp +The cached pages (file contents) for a regular file described by +.Va cookie +are invalidated using +.Fn puffs_inval_pagecache_node . +A specific range can be invalidated using +.Fn puffs_inval_pagecache_node_range +for a platform specific page level granularity. +The offset +.Va start +will be +.Em truncated +to a page boundary while +.Va end +will be +.Em "rounded up" +to the next page boundary. +As a special case, specifying 0 as +.Va end +will invalidate all contents from +.Va start +to the end of the file. +.Pp +It is especially important to note that these routines will not only +invalidate data in the "read cache", but also data in the "write back" +cache (conceptually speaking; in reality they are the same cache), which +has not yet been flushed to the file server. +Therefore any unflushed data will be lost. +.Pp +The counterparts of the invalidation routines are the flushing routines +.Fn puffs_flush_pagecache_node +and +.Fn puffs_flush_pagecache_node_range , +which force unwritten data from the kernel page cache to be written. +For the flush range version, the same range rules as with the +invalidation routine apply. +The data is flushed asynchronously, i.e. if the routine returns +successfully, all the caller knows is that the data has been queued +for writing. +.Sh SEE ALSO +.Xr puffs 3 diff --git a/static/netbsd/man3/puffs_framebuf.3 b/static/netbsd/man3/puffs_framebuf.3 new file mode 100644 index 00000000..d698d831 --- /dev/null +++ b/static/netbsd/man3/puffs_framebuf.3 @@ -0,0 +1,620 @@ +.\" $NetBSD: puffs_framebuf.3,v 1.30 2015/02/16 10:48:50 wiz Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 6, 2008 +.Dt PUFFS_FRAMEBUF 3 +.Os +.Sh NAME +.Nm puffs_framebuf +.Nd buffering and event handling for networked file systems +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft struct puffs_framebuf * +.Fn puffs_framebuf_make +.Ft void +.Fn puffs_framebuf_destroy "struct puffs_framebuf *pufbuf" +.Ft void +.Fn puffs_framebuf_recycle "struct puffs_framebuf *pufbuf" +.Ft int +.Fn puffs_framebuf_reserve_space "struct puffs_framebuf *pufbuf" "size_t space" +.Ft int +.Fo puffs_framebuf_putdata +.Fa "struct puffs_framebuf *pufbuf" "const void *data" "size_t dlen" +.Fc +.Ft int +.Fo puffs_framebuf_putdata_atoff +.Fa "struct puffs_framebuf *pufbuf" "size_t offset" "const void *data" +.Fa "size_t dlen" +.Fc +.Ft int +.Fo puffs_framebuf_getdata +.Fa "struct puffs_framebuf *pufbuf" "void *data" "size_t dlen" +.Fc +.Ft int +.Fo puffs_framebuf_getdata_atoff +.Fa "struct puffs_framebuf *pufbuf" "size_t offset" +.Fa "void *data" "size_t dlen" +.Fc +.Ft size_t +.Fn puffs_framebuf_telloff "struct puffs_framebuf *pufbuf" +.Ft size_t +.Fn puffs_framebuf_tellsize "struct puffs_framebuf *pufbuf" +.Ft size_t +.Fn puffs_framebuf_remaining "struct puffs_framebuf *pufbuf" +.Ft int +.Fn puffs_framebuf_seekset "struct puffs_framebuf *pufbuf" "size_t offset" +.Ft int +.Fo puffs_framebuf_getwindow +.Fa "struct puffs_framebuf *pufbuf" "size_t offset" +.Fa "void **winp" "size_t *winlen" +.Fc +.Ft int +.Fo puffs_framev_enqueue_cc +.Fa "struct puffs_cc *pcc" "int fd" "struct puffs_framebuf *pufbuf" "int flags" +.Fc +.Ft void +.Fo puffs_framev_cb +.Fa "struct puffs_usermount *pu" "int fd" "struct puffs_framebuf *pufbuf" +.Fa "void *arg" "int flags" +.Fa "int error" +.Fc +.Ft void +.Fo puffs_framev_enqueue_cb +.Fa "struct puffs_usermount *pu" "int fd" "struct puffs_framebuf *pufbuf" +.Fa "puffs_framebuf_cb fcb" "void *fcb_arg" "int flags" +.Fc +.Ft void +.Fo puffs_framev_enqueue_justsend +.Fa "struct puffs_usermount *pu" "int fd" "struct puffs_framebuf *pufbuf" +.Fa "int waitreply" "int flags" +.Fc +.Ft void +.Fo puffs_framev_enqueue_directsend +.Fa "struct puffs_usermount *pu" "int fd" "struct puffs_framebuf *pufbuf" +.Fa "int flags" +.Fc +.Ft void +.Fo puffs_framev_enqueue_directreceive +.Fa "struct puffs_usermount *pu" "int fd" "struct puffs_framebuf *pufbuf" +.Fa "int flags" +.Fc +.Ft int +.Fo puffs_framev_framebuf_ccpromote +.Fa "struct puffs_framebuf *pufbuf" "struct puffs_cc *pcc" +.Fc +.Ft int +.Fn puffs_framev_enqueue_waitevent "struct puffs_cc *pcc" "int fd" "int *what" +.Ft int +.Fo puffs_framev_readframe_fn +.Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pufbuf" +.Fa "int fd" "int *done" +.Fc +.Ft int +.Fo puffs_framev_writeframe_fn +.Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pufbuf" +.Fa "int fd" "int *done" +.Fc +.Ft int +.Fo puffs_framev_cmpframe_fn +.Fa "struct puffs_usermount *pu" +.Fa "struct puffs_framebuf *cmp1" "struct puffs_framebuf *cmp2" "int *notresp" +.Fc +.Ft void +.Fo puffs_framev_gotframe_fn +.Fa "struct puffs_usermount *pu" "struct puffs_framebuf *pufbuf" +.Fc +.Ft void +.Fo puffs_framev_fdnotify_fn +.Fa "struct puffs_usermount *pu" "int fd" "int what" +.Fc +.Ft void +.Fo puffs_framev_init +.Fa "struct puffs_usermount *pu" +.Fa "puffs_framev_readframe_fn rfb" "puffs_framev_writeframe_fn wfb" +.Fa "puffs_framev_cmpframe_fn cmpfb" "puffs_framev_gotframe_fn gotfb" +.Fa "puffs_framev_fdnotify_fn fdnotfn" +.Fc +.Ft int +.Fn puffs_framev_addfd "struct puffs_usermount *pu" "int fd" "int what" +.Ft int +.Fn puffs_framev_enablefd "struct puffs_usermount *pu" "int fd" "int what" +.Ft int +.Fn puffs_framev_disablefd "struct puffs_usermount *pu" "int fd" "int what" +.Ft int +.Fn puffs_framev_removefd "struct puffs_usermount *pu" "int fd" "int error" +.Ft void +.Fo puffs_framev_unmountonclose +.Fa "struct puffs_usermount *pu" "int fd" "int what" +.Fc +.Sh DESCRIPTION +The +.Nm +routines provide buffering and an event loop structured around the +buffers. +It operates on top of the puffs continuation framework, +.Xr puffs_cc 3 , +and multiplexes execution automatically to an instance whenever +one is runnable. +.Pp +The file system is entered in three different ways: +.Bl -bullet -offset indent +.It +An event arrives from the kernel and the +.Xr puffs_ops 3 +callbacks are called to start processing the event. +.It +A file system which has sent out a request receives a response. +Execution is resumed from the place where the file system yielded. +.It +A request from a peer arrives. +A request is an incoming PDU which is not a response to any outstanding +request. +.El +.Pp +.Nm +is used by defining various callbacks and providing I/O descriptors, +which are then monitored for activity by the library. +A descriptor, when present, can be either enabled or disabled for +input and output. +If a descriptor is not enabled for a certain direction, the callbacks +will not be called even if there were activity on the descriptor. +For example, even if a network socket has been added and there is +input data in the socket buffer, the read callback will be called +only if the socket has been enabled for reading. +.Pp +File descriptors are treated like sockets: they have two sides, a read +side and a write side. +The framework determines that one side of the descriptor has been +closed if the supplied I/O callbacks return an error or if the I/O +multiplexing call says a side has been closed. +It is still possible, from the framework perspective, to write to a +file descriptor whose read side is closed. +However, it is not possible to wait for a response on such a file +descriptor. +Conversely, it is possible to read responses from a descriptor whose +write side is closed. +It should be stressed that the implementation underlying the file +descriptor might not support this. +.Pp +The following callbacks can be defined, cf. +.Fn puffs_framev_init , +and all are optional. +None of them should block, because this would cause the entire file server +to block. +One option is to make the descriptors non-blocking before adding them. +.Bl -tag -width "xfdnotfnx" +.It rfb +Read a frame from the file descriptor onto the specified buffer. +.It wfb +Write a frame from the specified buffer into the file descriptor. +.It cmpfb +Identify if a buffer is the response to the specified buffer. +.It gotfb +Called iff no outstanding request matches the incoming frame. +In other words, this is called when we receive a request from a peer. +.It fdnotfn +Receive notifications about a change-of-state in a file descriptor's +status. +.El +.Pp +Better descriptions for each callback are given below. +.Pp +The buffers of +.Nm +provide automatic memory management of buffers for the file servers. +They provide a cursor to the current buffer offset. +Reading or writing data through the normal routines will advance that cursor. +Additionally, the buffer size is provided to the user. +It represents the maximum offset where data was written. +.Pp +Generally the write functions will fail if the cannot allocate enough +memory to satisfy the buffer length requirements. +Read functions will fail if the amount of data written to the buffer +is not large enough to satisfy the read. +.Bl -tag -width xxxx +.It Fn puffs_framebuf_make +Create a buffer. +Return the address of the buffer or +.Dv NULL +in case no memory was available. +.It Fn puffs_framebuf_destroy pufbuf +Free memory used by buffer. +.It Fn puffs_framebuf_recycle pufbuf +Reset offsets so that buffer can be reused. +Does not free memory or reallocate memory. +.It Fn puffs_framebuf_reserve_space pufbuf space +Make sure that the buffer has +.Ar space +bytes of available memory starting from the current offset. +This is not strictly necessary, but can be used for optimizations +where it is known in advance how much memory will be required. +.It Fn puffs_framebuf_putdata pufbuf data dlen +Write +.Ar dlen +amount of data from the address +.Ar data +into the buffer. +Moves the offset cursor forward +.Ar dlen +bytes. +.It Fn puffs_framebuf_putdata_atoff pufbuf offset data dlen +Like +.Fn puffs_framebuf_putdata , +except writes data at buffer offset +.Ar offset . +It is legal to write past the current end of the buffer. +Does NOT modify the current offset cursor. +.It Fn puffs_framebuf_getdata pufbuf data dlen +Read +.Ar dlen +bytes of data from the buffer into +.Ar data . +Advances the offset cursor. +.It Fn puffs_framebuf_getdata_atoff pufbuf offset data dlen +Read data from buffer position +.Ar offset . +Does NOT modify the offset cursor. +.It Fn puffs_framebuf_telloff pufbuf +Return the offset into the buffer. +.It Fn puffs_framebuf_tellsize pufbuf +Return the maximum offset where data has been written, i.e. buffer size. +.It Fn puffs_framebuf_remaining pufbuf +Distance from current offset to the end of the buffer, i.e. size-offset. +.It Fn puffs_framebuf_seekset pufbuf offset +Set the offset cursor to the position +.Ar offset . +This does NOT modify the buffer size, but reserves at least +enough memory memory for a write to +.Ar offset +and will fail if memory cannot be allocated. +.It Fn puffs_framebuf_getwindow pufbuf offset winp winlen +Get a direct memory window into the buffer starting from +.Ar offset . +The maximum mapped window size will be +.Ar winlen +bytes, but this routine might return a smaller window and the caller +should always check the actual mapped size after the call. +The window is returned in +.Ar winp . +This function not modify the buffer offset, but it DOES set the buffer +size to +.Ar offset + +.Ar winlen +in case that value is greater than the current size. +The window is valid until the next until the next +.Fn puffs_framebuf +call operating on the buffer in question. +.It Fn puffs_framev_enqueue_cc pcc fd pufbuf flags +Add the buffer +.Ar pufbuf +to outgoing queue of descriptor +.Ar fd +and yield with the continuation +.Ar pcc . +Execution is resumed once a response is received. +Returns 0 if the buffer was successfully enqueued (not necessarily +delivered) and non-zero to signal a non-recoverable error. +.Pp +Usually the buffer is placed at the end of the output queue. +However, if +.Ar flags +contains +.Dv PUFFS_FBQUEUE_URGENT , +.Ar pufbuf +is placed in the front of the queue to be sent immediately after +the current PDU (if any) has been sent. +.It Fn puffs_framev_enqueue_cb pu fd pufbuf fcb fcb_arg flags +Enqueue the buffer +.Ar pufbuf +for outgoing data and immediately return. +Once a response arrives, the callback +.Fn fcb +will be called with the argument +.Ar fcb_arg . +The callback function +.Fn fcb +is responsible for freeing the buffer. +Returns 0 if the buffer was successfully enqueued (not necessarily +delivered) and non-zero to signal a non-recoverable error. +.Pp +See +.Fn puffs_framev_enqueue_cc +for +.Ar flags . +.It Fn puffs_framev_cb pu pufbuf arg error +Callback function. +Called when a response to a specific request arrives from the server. +If +.Ar error +is non-zero, the framework was unable to obtain a response and the +function should not examine the contents of +.Ar pufbuf , +only do resource cleanup. +May not block. +.It Fn puffs_framev_enqueue_justsend pu fd pufbuf waitreply flags +Enqueue the buffer +.Ar pufbuf +for outgoing traffic and immediately return. +The parameter +.Ar waitreply +can be used to control if the buffer is to be freed immediately after +sending of if a response is expected and the buffer should be freed +only after the response arrives (receiving an unexpected message from +the server is treated as an error). +Returns 0 if the buffer was successfully enqueued (not necessarily +delivered) and non-zero to signal a non-recoverable error. +.Pp +See +.Fn puffs_framev_enqueue_cc +for +.Ar flags . +.It Fn puffs_framev_enqueue_directsend pcc fd pufbuf flags +Acts like +.Fn puffs_framev_enqueue_justsend +with the exception that the call yields until the frame has been sent. +As opposed to +.Fn puffs_framev_enqueue_cc , +the routine does not wait for input, but returns immediately after +sending the frame. +.Pp +See +.Fn puffs_framev_enqueue_cc +for +.Ar flags . +.It Fn puffs_framev_enqueue_directreceive pcc fd pufbuf flags +Receive data into +.Ar pufbuf . +This routine yields until a complete frame has been read into +the buffer by the readframe routine. +.Pp +See +.Fn puffs_framev_enqueue_cc +for +.Ar flags . +.It Fn puffs_framev_framebuf_ccpromote pufbuf pcc +Promote the framebuffer +.Ar pufbuf +sent with +.Fn puffs_framev_enqueue_cb +or +.Fn puffs_framev_enqueue_justsend +to a wait using +.Ar pcc +and yield until the result arrives. +The response from the file server for +.Ar pufbuf +must not yet have arrived. +If sent with +.Fn puffs_framev_enqueue_justsend , +the call must be expecting a response. +.It Fn puffs_framev_enqueue_waitevent pcc fd what +Waits for an event in +.Ar what +to happen on file descriptor +.Ar fd . +The events which happened are returned back in +.Ar what . +The possible events are +.Dv PUFFS_FBIO_READ , +.Dv PUFFS_FBIO_WRITE , +and +.Dv PUFFS_FBIO_ERROR , +specifying read, write and error conditions, respectively. +Error is always checked. +.Pp +This call does not depend on if the events were previously enabled on +the file descriptor - the specified events are always checked +regardless. +.Pp +There is currently no other way to cancel or timeout a call except by +removing the file descriptor in question. +This may change in the future. +.It Fn puffs_framev_readframe_fn pu pufbuf fd done +Callback function. +Read at most one frame from file descriptor +.Ar fd +into the buffer +.Ar pufbuf . +If a complete frame is read, the value pointed to by +.Ar done +must be set to 1. +This function should return 0 on success (even if a complete frame was not +yet read) and a non-zero +.Er errno +to signal a fatal error. +In case a fatal error is returned, the read side of the file descriptor +is marked closed. +This routine will be called with the same buffer argument until a +complete frame has been read. +May not block. +.It Fn puffs_framev_writeframe_fn pu pufbuf fd done +Write the frame contained in +.Ar pufbuf +to the file descriptor +.Ar fd . +In case the entire frame is successfully written, +.Ar *done +should be set to 1. +This function should return 0 on success (even if a complete frame was not +yet written) and a non-zero +.Er errno +to signal a fatal error. +In case a fatal error is returned, the write side of the file descriptor +is marked closed. +This routine will be called with the same buffer argument until the +complete frame has been written. +May not block. +.Pp +It is a good idea to make sure that this function can handle a possible +.Dv SIGPIPE +caused by a closed connection. +For example, the file server can opt to trap +.Dv SIGPIPE +or, if writing to a socket, call +.Fn send +with the flag +.Dv MSG_NOSIGNAL +instead of using +.Fn write . +.It Fn puffs_framev_cmpframe_fn pu pufbuf_cmp1 pufbuf_cmp2 notresp +Compare the file system internal request tags in +.Ar pufbuf_cmp1 +and +.Ar pufbuf_cmp2 . +Should return 0 if the tags are equal, 1 if first buffer's tag is +greater than the second and \-1 if it is smaller. +The definitions "greater" and "smaller" are used transparently by +the library, e.g. like +.Xr qsort 3 . +If it can be determined from +.Ar pufbuf_cmp1 +that it is not a response to any outstanding request, +.Ar notresp +should be set to non-zero. +This will cause +.Nm +to skip the test of the buffer against the rest of the outstanding +request. +May not block. +.It Fn puffs_framev_gotframe_fn pu pufbuf +Called when no outstanding request matches an incoming frame. +The ownership of +.Ar pufbuf +is transferred to the called function and must be destroyed once +processing is over. +May not block. +.It Fn puffs_framev_fdnotify_fn pu fd what +Is called when the read or write side of the file descriptor +.Ar fd +is closed. +It is called once for each side, the bitmask parameter +.Ar what +specified what is currently closed: +.Dv PUFFS_FBIO_READ +and +.Dv PUFFS_FBIO_WRITE +for read and write, respectively. +.It Fn puffs_framev_init pu rfb wfb cmpfb gotfb fdnotfn +Initializes the given callbacks to the system. +They will be used when +.Fn puffs_mainloop +is called. +The framework provides the routines +.Fn puffs_framev_removeonclose +and +.Fn puffs_framev_unmountonclose , +which can be given as +.Ar fdnotfn . +The first one removes the file descriptor once both sides are closed +while the second one unmounts the file system and exits the mainloop. +.It Fn puffs_framev_addfd pu fd what +Add file descriptor +.Ar fd +to be handled by the framework. +It is legal to add a file descriptor either before calling +.Fn puffs_mainloop +or at time when running. +The parameter +.Ar what +controls enabling of input and output events and can be a bitwise +combination of +.Dv PUFFS_FBIO_READ +and +.Dv PUFFS_FBIO_WRITE . +If not specified, the descriptor will be in a disabled state. +.It Fn puffs_framev_enablefd pu fd what +Enable events of type +.Ar what +for file descriptor +.Ar fd . +.It Fn puffs_framev_disablefd pu fd what +Disable events of type +.Ar what +for file descriptor +.Ar fd . +.It Fn puffs_framev_removefd pu fd error +Remove file descriptor +.Ar fd +from the list of descriptors handled by the framework. +Removing a file descriptor causes all operations blocked either on +output or input to be released with the error value +.Ar error . +In case 0 is supplied as this parameter, +.Er ECONNRESET +is used. +.Pp +The file system +.Em must +explicitly remove each fd it has added. +A good place to do this is +.Fn puffs_framev_fdnotify_fn +or +.Fn puffs_node_reclaim , +depending a little on the structure of the file system. +.It Fn puffs_framev_unmountonclose pu fd what +This is library provided convenience routine for +.Fn puffs_framev_fdnotify_fn . +It unmounts the file system when both the read and write side are +closed. +It is useful for file systems such as +.Xr mount_psshfs 8 +which depend on a single connection. +.El +.Sh RETURN VALUES +These functions generally return \-1 to signal error and set +.Er errno +to indicate the type of error. +.Sh CODE REFERENCES +The current users of +.Nm +in the tree are +.Xr mount_psshfs 8 +and +.Xr mount_9p 8 . +See +.Pa src/usr.sbin/puffs/mount_psshfs +and +.Pa src/usr.sbin/puffs/mount_9p +for the respective usage examples. +.Sh SEE ALSO +.Xr puffs 3 , +.Xr puffs_cc 3 , +.Xr puffs_ops 3 +.Rs +.%A Antti Kantee +.%D September 2007 +.%I Helsinki University of Technology +.%R Tech Report TKK-TKO-B157 +.%T Using puffs for Implementing Client-Server Distributed File Systems +.Re +.Rs +.%A Antti Kantee +.%D March 2008 +.%J Proceedings of AsiaBSDCon 2008 +.%P pp. 55-70 +.%T Send and Receive of File System Protocols: Userspace Approach With puffs +.Re diff --git a/static/netbsd/man3/puffs_node.3 b/static/netbsd/man3/puffs_node.3 new file mode 100644 index 00000000..4989003d --- /dev/null +++ b/static/netbsd/man3/puffs_node.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: puffs_node.3,v 1.6 2021/08/04 09:31:25 andvar Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd June 24, 2007 +.Dt PUFFS_NODE 3 +.Os +.Sh NAME +.Nm puffs_node +.Nd puffs node routines +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft struct puffs_node * +.Fn puffs_pn_new "struct puffs_usermount *pu" "void *priv" +.Ft void * +.Fo puffs_nodewalk_fn +.Fa "struct puffs_usermount *pu" "struct puffs_node *pn" "void *arg" +.Fc +.Ft void * +.Fo puffs_pn_nodewalk +.Fa "struct puffs_usermount *pu" "puffs_nodewalk_fn nwfn" "void *arg" +.Fc +.Ft void +.Fn puffs_pn_remove "struct puffs_node *pn" +.Ft void +.Fn puffs_pn_put "struct puffs_node *pn" +.Sh DESCRIPTION +.Bl -tag -width xxxx +.It Fn puffs_pn_new pu priv +Create a new node and attach it to the mountpoint +.Ar pu . +The argument +.Ar priv +can be used for associating file system specific data with the new +node and will not be accessed by puffs. +.It Fn puffs_nodewalk_fn pu pn arg +A callback for +.Fn puffs_nodewalk . +The list of nodes is iterated in the argument +.Ar pn +and the argument +.Ar arg +is the argument given to +.Fn puffs_nodewalk . +.It Fn puffs_nodewalk pu nwfn arg +Walk all nodes associated with the mountpoint +.Ar pu +and call +.Fn nwfn +for them. +The walk is aborted if +.Fn puffs_nodewalk_fn +returns a value which is not +.Dv NULL . +This value is also returned this function. +In case the whole set of nodes is traversed, +.Dv NULL +is returned. +This function is useful for example in handling the +.Fn puffs_fs_sync +callback, when cached data for every node should be flushed to stable +storage. +.It Fn puffs_pn_remove pn +Signal that a node has been removed from the file system, but do not +yet release resources associated with the node. +This will prevent the nodewalk functions from accessing the node. +If necessary, this is usually called from +.Fn puffs_node_remove +and +.Fn puffs_node_rmdir . +.It Fn puffs_pn_put pn +Free all resources associated with node +.Ar pn . +This is typically called from +.Fn puffs_node_reclaim . +.El +.Sh SEE ALSO +.Xr puffs 3 diff --git a/static/netbsd/man3/puffs_ops.3 b/static/netbsd/man3/puffs_ops.3 new file mode 100644 index 00000000..595b5302 --- /dev/null +++ b/static/netbsd/man3/puffs_ops.3 @@ -0,0 +1,989 @@ +.\" $NetBSD: puffs_ops.3,v 1.48 2021/12/03 14:00:59 pho Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 29, 2016 +.Dt PUFFS_OPS 3 +.Os +.Sh NAME +.Nm puffs_ops +.Nd puffs callback operations +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft int +.Fo puffs_fs_statvfs +.Fa "struct puffs_usermount *pu" "struct statvfs *sbp" +.Fc +.Ft int +.Fo puffs_fs_sync +.Fa "struct puffs_usermount *pu" "int waitfor" "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_fs_fhtonode +.Fa "struct puffs_usermount *pu" "void *fid" "size_t fidsize" +.Fa "struct puffs_newinfo *pni" +.Fc +.Ft int +.Fo puffs_fs_nodetofh +.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "void *fid" +.Fa "size_t *fidsize" +.Fc +.Ft int +.Fo puffs_fs_extattrctl +.Fa "struct puffs_usermount *pu" "int cmd" "puffs_cookie_t cookie" "int flags" +.Fa "int attrnamespace" "const char *attrname" +.Fc +.Ft int +.Fo puffs_fs_unmount +.Fa "struct puffs_usermount *pu" "int flags" +.Fc +.Ft int +.Fo puffs_node_lookup +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" +.Fc +.Ft int +.Fo puffs_node_create +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" +.Fa "const struct vattr *vap" +.Fc +.Ft int +.Fo puffs_node_mknod +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" +.Fa "const struct vattr *vap" +.Fc +.Ft int +.Fo puffs_node_open +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int mode" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_open2 +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int modep" +.Fa "const struct puffs_cred *pcr" "int *oflags" +.Fc +.Ft int +.Fo puffs_node_close +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_access +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int mode" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_getattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_setattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "const struct vattr *vap" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_getattr_ttl +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap" +.Fa "const struct puffs_cred *pcr" "struct timespec *va_ttl" +.Fc +.Ft int +.Fo puffs_node_setattr_ttl +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap" +.Fa "const struct puffs_cred *pcr" "struct timespec *va_ttl" "int xflag" +.Fc +.Ft int +.Fo puffs_node_pathconf +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int name" +.Fa "__register_t *retval" +.Fc +.Ft int +.Fo puffs_node_advlock +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "void *id" "int op" +.Fa "struct flock *fl" "int flags" +.Fc +.Ft int +.Fo puffs_node_poll +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int *events" +.Fc +.Ft int +.Fo puffs_node_mmap +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_fsync +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "const struct puffs_cred *pcr" "int flags" "off_t offlo" "off_t offhi" +.Fc +.Ft int +.Fo puffs_node_seek +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t oldoff" +.Fa "off_t newoff" "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_remove +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" +.Fa "const struct puffs_cn *pcn" +.Fc +.Ft int +.Fo puffs_node_link +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" +.Fa "const struct puffs_cn *pcn" +.Fc +.Ft int +.Fo puffs_node_rename +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t src" +.Fa "const struct puffs_cn *pcn_src" "puffs_cookie_t targ_dir" +.Fa "puffs_cookie_t targ" "const struct puffs_cn *pcn_targ" +.Fc +.Ft int +.Fo puffs_node_mkdir +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" +.Fa "const struct vattr *vap" +.Fc +.Ft int +.Fo puffs_node_rmdir +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" +.Fa "const struct puffs_cn *pcn" +.Fc +.Ft int +.Fo puffs_node_readdir +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct dirent *dent" +.Fa "off_t *readoff" "size_t *reslen" "const struct puffs_cred *pcr" +.Fa "int *eofflag" "off_t *cookies" "size_t *ncookies" +.Fc +.Ft int +.Fo puffs_node_symlink +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "struct puffs_newinfo *pni" +.Fa "const struct puffs_cn *pcn_src" "const struct vattr *vap" +.Fa "const char *link_target" +.Fc +.Ft int +.Fo puffs_node_readlink +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "const struct puffs_cred *pcr" "char *link" "size_t *linklen" +.Fc +.Ft int +.Fo puffs_node_read +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" +.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" +.Fc +.Ft int +.Fo puffs_node_write +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" +.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" +.Fc +.Ft int +.Fo puffs_node_write2 +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" +.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" +.Fa "int xflag" +.Fc +.Ft int +.Fo puffs_node_abortop +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fa "const struct puffs_cn *pcn" +.Fc +.Ft int +.Fo puffs_node_getextattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" +.Fa "const char *attrname" "size_t *attrsize" "uint8_t *attr" "size_t *resid" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_setextattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" +.Fa "const char *attrname" "uint8_t *attr" "size_t *resid" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_listextattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" +.Fa "size_t *attrssize" "uint8_t *attrs" "size_t *resid" "int flag" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_deleteextattr +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" +.Fa "const char *attrname" +.Fa "const struct puffs_cred *pcr" +.Fc +.Ft int +.Fo puffs_node_fallocate +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t pos" "off_t len" +.Fc +.Ft int +.Fo puffs_node_fdiscard +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t pos" "off_t len" +.Fc +.Ft int +.Fo puffs_node_print +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fc +.Ft int +.Fo puffs_node_reclaim +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fc +.Ft int +.Fo puffs_node_reclaim2 +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int nlookup" +.Fc +.Ft int +.Fo puffs_node_inactive +.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" +.Fc +.Ft void +.Fn puffs_setback "struct puffs_cc *pcc" "int op" +.Ft void +.Fn puffs_newinfo_setcookie "struct puffs_newinfo *pni" "puffs_cookie_t cookie" +.Ft void +.Fn puffs_newinfo_setvtype "struct puffs_newinfo *pni" "enum vtype vtype" +.Ft void +.Fn puffs_newinfo_setsize "struct puffs_newinfo *pni" "voff_t size" +.Ft void +.Fn puffs_newinfo_setrdev "struct puffs_newinfo *pni" "dev_t rdev" +.Ft void +.Fn puffs_newinfo_setva "struct puffs_newinfo *pni" "struct vattr *vap" +.Ft void +.Fn puffs_newinfo_setvattl "struct puffs_newinfo *pni" "struct timespec *va_ttl" +.Ft void +.Fn puffs_newinfo_setcnttl "struct puffs_newinfo *pni" "struct timespec *cn_ttl" +.Sh DESCRIPTION +The operations +.Nm puffs +requires to function can be divided into two categories: file system +callbacks and node callbacks. +The former affect the entire file system while the latter are targeted +at a file or a directory and a file. +They are roughly equivalent to the vfs and vnode operations in the +kernel. +.Pp +All callbacks can be prototyped with the file system name and operation +name using the macro +.Fn PUFFSOP_PROTOS fsname . +.Ss File system callbacks (puffs_fs) +.Bl -tag -width xxxx +.It Fn puffs_fs_statvfs "pu" "sbp" +The following fields of the argument +.Fa sbp +need to be filled: +.Bd -literal + * unsigned long f_bsize; file system block size + * unsigned long f_frsize; fundamental file system block size + * fsblkcnt_t f_blocks; number of blocks in file system, + * (in units of f_frsize) + * + * fsblkcnt_t f_bfree; free blocks avail in file system + * fsblkcnt_t f_bavail; free blocks avail to non-root + * fsblkcnt_t f_bresvd; blocks reserved for root + + * fsfilcnt_t f_files; total file nodes in file system + * fsfilcnt_t f_ffree; free file nodes in file system + * fsfilcnt_t f_favail; free file nodes avail to non-root + * fsfilcnt_t f_fresvd; file nodes reserved for root + +.Ed +.It Fn puffs_fs_sync "pu" "waitfor" "pcr" +All the dirty buffers that have been cached at the file server +level including metadata should be committed to stable storage. +The +.Fa waitfor +parameter affects the operation. +Possible values are: +.Bl -tag -width XMNT_NOWAITX +.It Dv MNT_WAIT +Wait for all I/O for complete until returning. +.It Dv MNT_NOWAIT +Initiate I/O, but do not wait for completion. +.It Dv MNT_LAZY +Synchronize data not synchronized by the file system syncer, +i.e., data not written when +.Fn node_fsync +is called with +.Dv FSYNC_LAZY . +.El +.Pp +The credentials for the initiator of the sync operation are present in +.Fa pcr +and will usually be either file system or kernel credentials, but might +also be user credentials. +However, most of the time it is advisable to sync regardless of the +credentials of the caller. +.It Fn puffs_fs_fhtonode "pu" "fid" "fidsize" "pni" +Translates a file handle +.Fa fid +to a node. +The parameter +.Fa fidsize +indicates how large the file handle is. +In case the file system's handles are static length, this parameter can +be ignored as the kernel guarantees all file handles passed to the file +server are of correct length. +For dynamic length handles the field should be examined and +.Er EINVAL +returned in case the file handle length is not correct. +.Pp +This function provides essentially the same information to the kernel as +.Fn puffs_node_lookup . +The information is necessary for creating a new vnode corresponding to +the file handle. +.It Fn puffs_fs_nodetofh "pu" "cookie" "fid" "fidsize" +Create a file handle from the node described by +.Fa cookie . +The file handle should contain enough information to reliably identify +the node even after reboots and the pathname/inode being replaced by +another file. +If this is not possible, it is up to the author of the file system to +act responsibly and decide if the file system can support file handles +at all. +.Pp +For file systems which want dynamic length file handles, this function +must check if the file handle space indicated by +.Fa fidsize +is large enough to accommodate the file handle for the node. +If not, it must fill in the correct size and return +.Er E2BIG . +In either case, the handle length should be supplied to the kernel in +.Fa fidsize . +File systems with static length handles can ignore the size parameter as +the kernel always supplies the correct size buffer. +.It Fn puffs_fs_unmount "pu" "flags" +Unmount the file system. +The kernel has assumedly flushed all cached data when this callback +is executed. +If the file system cannot currently be safely be unmounted, for whatever +reason, the kernel will honor an error value and not forcibly unmount. +However, if the flag +.Dv MNT_FORCE +is not honored by the file server, the kernel will forcibly unmount +the file system. +.El +.Ss Node callbacks +These operations operate in the level of individual files. +The file cookie is always provided as the second argument +.Fa opc . +If the operation is for a file, it will be the cookie of the file. +The case the operation involves a directory (such as +.Dq create file in directory ) , +the cookie will be for the directory. +Some operations take additional cookies to describe the rest of +the operands. +The return value 0 signals success, else an appropriate errno value +should be returned. +Please note that neither this list nor the descriptions are complete. +.Bl -tag -width xxxx +.It Fn puffs_node_lookup "pu" "opc" "pni" "pcn" +This function is used to locate nodes, or in other words translate +pathname components to file system data structures. +The implementation should match the name in +.Fa pcn +against the existing entries in the directory provided by the cookie +.Fa opc . +If found, the cookie for the located node should be set in +.Fa pni +using +.Fn puffs_newinfo_setcookie . +Additionally, the vnode type and size (latter applicable to regular files only) +should be set using +.Fn puffs_newinfo_setvtype +and +.Fn puffs_newinfo_setsize , +respectively. +If the located entry is a block device or character device file, +the dev_t for the entry should be set using +.Fn puffs_newinfo_setrdev . +.Pp +If +.Fn puffs_init +was called with +.Dv PUFFS_KFLAG_CACHE_FS_TTL +then +.Fn puffs_newinfo_setva , +.Fn puffs_newinfo_setvattl , +and +.Fn puffs_newinfo_setcnttl +can be called to specify the new node attributes, cached attributes +time to live, and cached name time to live. +.Pp +The type of operation is found from +.Va pcn->pcn_nameiop : +.Bl -tag -width XNAMEI_LOOKUPX +.It Dv NAMEI_LOOKUP +Normal lookup operation. +.It Dv NAMEI_CREATE +Lookup to create a node. +.It Dv NAMEI_DELETE +Lookup for node deletion. +.It Dv NAMEI_RENAME +Lookup for the target of a rename operation (source will be looked +up using +.Dv NAMEI_DELETE ) . +.El +.Pp +The final component from a pathname lookup usually requires special +treatment. +It can be identified by looking at the +.Va pcn->pcn_flags +fields for the flag +.Dv PUFFSLOOKUP_ISLASTCN . +For example, in most cases the lookup operation will want to check if +a delete, rename or create operation has enough credentials to perform +the operation. +.Pp +The return value 0 signals a found node and a nonzero value signals +an errno. +As a special case, +.Er ENOENT +signals "success" for cases where the lookup operation is +.Dv NAMEI_CREATE +or +.Dv NAMEI_RENAME . +Failure in these cases can be signalled by returning another appropriate +error code, for example +.Er EACCESS . +.Pp +Usually a null-terminated string for the next pathname component is +provided in +.Ar pcn->pcn_name . +In case the file system is using the option +.Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF , +the remainder of the complete pathname under lookup is found in +the same location. +.Ar pcn->pcn_namelen +always specifies the length of the next component. +If operating with a full path, the file system is allowed to consume +more than the next component's length in node lookup. +This is done by setting +.Ar pcn->pcn_consume +to indicate the amount of +.Em extra +characters in addition to +.Ar pcn->pcn_namelen +processed. +.It Fn puffs_node_create "pu" "opc" "pni" "pcn" "va" +.It Fn puffs_node_mkdir "pu" "opc" "pni" "pcn" "va" +.It Fn puffs_node_mknod "pu" "opc" "pni" "pcn" "va" +A file node is created in the directory denoted by the cookie +.Fa opc +by any of the above callbacks. +The name of the new file can be found from +.Fa pcn +and the attributes are specified by +.Fa va +and the cookie for the newly created node should be set in +.Fa pni . +The only difference between these three is that they create a regular +file, directory and device special file, respectively. +.Pp +In case of mknod, the device identifier can be found in +.Fa va->va_rdev . +.It Fn puffs_node_open "pu" "opc" "mode" "pcr" +.It Fn puffs_node_open2 "pu" "opc" "mode" "pcr" "oflags" +Open the node denoted by the cookie +.Fa opc . +The parameter +.Fa mode +specifies the flags that +.Xr open 2 +was called with, e.g. +.Dv O_APPEND +and +.Dv O_NONBLOCK . +.Fn puffs_node_open2 +allows the file system to pass back information for the file in +.Fa oflags . +The only implemented flag for now is +.Dv PUFFS_OPEN_IO_DIRECT +that cause file read/write to bypass the page cache. +.It Fn puffs_node_close "pu" "opc" "flags" "pcr" +Close a node. +The parameter +.Fa flags +parameter describes the flags that the file was opened with. +.It Fn puffs_node_access "pu" "opc" "mode" "pcr" +Check if the credentials of +.Fa pcr +have the right to perform the operation specified by +.Fa mode +onto the node +.Fa opc . +The argument +.Fa mode +can specify read, write or execute by +.Dv PUFFS_VREAD , +.Dv PUFFS_VWRITE , +and +.Dv PUFFS_VEXEC , +respectively. +.It Fn puffs_node_getattr "pu" "opc" "va" "pcr" +The attributes of the node specified by +.Fa opc +must be copied to the space pointed by +.Fa va . +.It Fn puffs_node_getattr_ttl "pu" "opc" "va" "pcr" "va_ttl" +Same as +.Fn puffs_node_getattr +with cached attribute time to live specified in +.Fa va_ttl +.It Fn puffs_node_setattr "pu" "opc" "va" "pcr" +The attributes for the node specified by +.Fa opc +must be set to those contained in +.Fa va . +Only fields of +.Fa va +which contain a value different from +.Dv PUFFS_VNOVAL +(typecast to the field's type!) contain a valid value. +.It Fn puffs_node_setattr_ttl "pu" "opc" "va" "pcr" "va_ttl" "xflag" +Same as +.Fn puffs_node_setattr +with cached attribute time to live specified in +.Fa va_ttl . +.Dv PUFFS_SETATTR_FAF +will be set in +.Fa xflag +for Fire-And-Forget operations. +.It Fn puffs_node_pathconf "pu" "opc" "name" "retval" +The value of the +.Xr pathconf 2 +filesystem limit specified in +.Ar name +for the node +.Ar opc +should be copied to the space pointed to by +.Ar retval . +.It Fn puffs_node_advlock "po" "opc" "id" "op" "fl" "flags" +Manipulate advisory record locks on the node +.Ar opc . +The argument +.Ar id +is the id token which is changing the lock, +.Ar op +is the +.Xr fcntl 2 +operation to perform, +.Ar fl +is the lock descriptor structure and +.Ar flags +are the flags as defined in +.Xr VOP_ADVLOCK 9 . +.It Fn puffs_node_poll "pu" "opc" "events" +Poll for events on node +.Ar opc . +If +.Xr poll 2 +events specified in +.Ar events +are available, the function should set the bitmask to match available +events and return immediately. +Otherwise, the function should block (yield) until some events in +.Ar events +become available and only then set the +.Ar events +bitmask and return. +.Pp +In case this function returns an error, +.Dv POLLERR +(or its +.Xr select 2 +equivalent) will be delivered to the calling process. +.Pp +.Em NOTE! +The system call interface for +.Fn poll +contains a timeout parameter. +At this level, however, the timeout is not supplied. +In case input does not arrive, the file system should periodically +unblock and return 0 new events to avoid hanging forever. +This will hopefully be better supported by libpuffs in the future. +.It Fn puffs_node_mmap "pu" "opc" "flags" "pcr" +Called when a regular file is being memory mapped by +.Xr mmap 2 . +.Fa flags +is currently always 0. +.It Fn puffs_node_fsync "pu" "opc" "pcr" "flags" "offlo" "offhi" +Synchronize a node's contents onto stable storage. +This is necessary only if the file server caches some information +before committing it. +The parameter +.Fa flags +specifies the minimum level of synchronization required (XXX: they are +not yet available). +The parameters +.Fa offlo +and +.Fa offhi +specify the data offsets requiring to be synced. +A high offset of 0 means sync from +.Fa offlo +to the end of the file. +.It Fn puffs_node_seek "pu" "opc" "oldoff" "newoff" "pcr" +Test if the node +.Ar opc +is seekable to the location +.Ar newoff . +The argument +.Ar oldoff +specifies the offset we are starting the seek from. +Most file systems dealing only with regular will choose to not +implement this. +However, it is useful for example in cases where files are +unseekable streams. +.It Fn puffs_node_remove "pu" "opc" "targ" "pcn" +.It Fn puffs_node_rmdir "pu" "opc" "targ" "pcn" +Remove the node +.Fa targ +from the directory indicated by +.Fa opc . +The directory entry name to be removed is provided by +.Fa pcn . +The rmdir operation removes only directories, while the remove +operation removes all other types except directories. +.Pp +It is paramount to note that the file system may not remove the +node data structures at this point, only the directory entry and prevent +lookups from finding the node again. +This is to retain the +.Ux +open file semantics. +The data may be removed only when +.Fn puffs_node_reclaim +or +.Fn puffs_node_reclaim2 +is called for the node, as this assures there are no further users. +.It Fn puffs_node_link "pu" "opc" "targ" "pcn" +Create a hard link for the node +.Fa targ +into the directory +.Fa opc . +The argument +.Fa pcn +provides the directory entry name for the new link. +.It Fn puffs_node_rename "pu" "src_dir" "src" "pcn_src" "targ_dir" "targ" "pcn_targ" +Rename the node +.Fa src +with the name specified by +.Fa pcn_src +from the directory +.Fa src_dir . +The target directory and target name are given by +.Fa targ_dir +and +.Fa pcn_targ , +respectively. +.Em If +the target node already exists, it is specified by +.Fa targ +and must be replaced atomically. +Otherwise +.Fa targ +is gives as +.Dv NULL . +.Pp +It is legal to replace a directory node by another directory node with +the means of rename if the target directory is empty, otherwise +.Er ENOTEMPTY +should be returned. +All other types can replace all other types. +In case a rename between incompatible types is attempted, the errors +.Er ENOTDIR +or +.Er EISDIR +should be returned, depending on the target type. +.It Fn puffs_node_readdir "pu" "opc" "dent" "readoff" "reslen" "pcr" "eofflag" "cookies" "ncookies" +To read directory entries, +.Fn puffs_node_readdir +is called. +It should store directories as +.Va struct dirent +in the space pointed to by +.Fa dent . +The amount of space available is given by +.Fa reslen +and before returning it should be set to the amount of space +.Em remaining +in the buffer. +The argument +.Fa offset +is used to specify the offset to the directory. +Its interpretation is up to the file system and it should be set to +signal the continuation point when there is no more room for the next +entry in +.Fa dent . +It is most performant to return the maximal amount of directory +entries each call. +It is easiest to generate directory entries by using +.Fn puffs_nextdent , +which also automatically advances the necessary pointers. +.Pp +In case end-of-directory is reached, +.Fa eofflag +should be set to one. +Note that even a new call to readdir may start where +.Fa readoff +points to end-of-directory. +.Pp +If the file system supports file handles, the arguments +.Fa cookies +and +.Fa ncookies +must be filled out. +.Fa cookies +is a vector for offsets corresponding to read offsets. +One cookie should be filled out for each directory entry. +The value of the cookie should equal the offset of the +.Em next +directory entry, i.e., which offset should be passed to readdir for +the first entry read to be the entry following the current one. +.Fa ncookies +is the number of slots for cookies in the cookie vector upon entry to +the function and must be set to the amount of cookies stored in the +vector (i.e., amount of directory entries read) upon exit. +There is always enough space in the cookie vector for the maximal number +of entries that will fit into the directory entry buffer. +For filling out the vector, the helper function +.Fn PUFFS_STORE_DCOOKIE cookies ncookies offset +can be used. +This properly checks against +.Fa cookies +being +.Dv NULL . +Note that +.Fa ncookies +must be initialized to zero before the first call to +.Fn PUFFS_STORE_DCOOKIE . +.It Fn puffs_node_symlink "pu" "opc" "pni" "pcn_src" "va" "link_target" +Create a symbolic link into the directory +.Fa opc +with the name in +.Fa pcn_src +and the initial attributes in +.Fa va . +The argument +.Ar link_target +contains a null-terminated string for the link target. +The created node cookie should be set in +.Fa pni . +.It Fn puffs_node_readlink "pu" "opc" "pcr" "link" "linklen" +Read the target of a symbolic link +.Fa opc . +The result is placed in the buffer pointed to by +.Fa link . +This buffer's length is given in +.Fa linklen +and it must be updated to reflect the real link length. +A terminating nul character should not be put into the buffer and +.Em "must not" +be included in the link length. +.It Fn puffs_node_read "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" +Read the contents of a file +.Fa opc . +It will gather the data from +.Fa offset +in the file and read the number +.Fa resid +octets. +The buffer is guaranteed to have this much space. +The amount of data requested by +.Fa resid +should be read, except in the case of eof-of-file or an error. +The parameter +.Fa resid +should be set to indicate the amount of request NOT completed. +In the normal case this should be 0. +.It Fn puffs_node_write "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" +.It Fn puffs_node_write2 "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" \ +"xflag" +.Fn puffs_node_write +writes data to a file +.Fa opc +at +.Fa offset +and extend the file if necessary. +The number of octets written is indicated by +.Fa resid ; +everything must be written or an error will be generated. +The parameter must be set to indicate the amount of data NOT written. +In case the ioflag +.Dv PUFFS_IO_APPEND +is specified, the data should be appended to the end of the file. +.Fn puffs_node_write2 +serves the same purpose as +.Fn puffs_node_write +with an additional +.Fa xflag +in which +.Dv PUFFS_WRITE_FAF +is set for Fire-And-Forget operations. +.It Fn puffs_node_fallocate "pu" "opc" "pos" "len" +Allocate +.Fa len +bytes of backing store at offset +.Fa pos +for the node referenced by the cookie +.Fa opc . +.It Fn puffs_node_fdiscard "pu" "opc" "pos" "len" +Free +.Fa len +bytes of backing store (creating a hole) at offset +.Fa pos +for the node referenced by the cookie +.Fa opc . +.It Fn puffs_node_print "pu" "opc" +Print information about node. +This is used only for kernel-initiated diagnostic purposes. +.It Fn puffs_node_reclaim "pu" "opc" +The kernel will no longer reference the cookie and resources associated +with it may be freed. +In case the file +.Fa opc +has a link count of zero, it may be safely removed now. +.It Fn puffs_node_reclaim2 "pu" "opc" "nlookup" +Same as +.Fn puffs_node_reclaim +with an additional argument for the number of lookups that have been done +on the node (Node creation is counted as a lookup). This can be used by the +file system to avoid a race condition, where the kernel sends a reclaim +while it does not have received the reply for a lookup. +If the file system tracks lookup count, and compares to +.Fa nlookup +it can detect this situation and ignore the reclaim. +.Pp +If the file system maps cookies to +.Vt struct puffs_node +then the framework will do that work, and +.Fn puffs_node_reclaim +can be reliably used without the race condition. +.It Fn puffs_node_abortop "pu" "opc" "pcn" +In case the operation following lookup (e.g., mkdir or remove) is not +executed for some reason, abortop will be issued. +This is useful only for servers which cache state between lookup +and a directory operation and is generally left unimplemented. +.It Fn puffs_node_inactive "pu" "opc" +The node +.Fa opc +has lost its last reference in the kernel. +However, the cookie must still remain valid until +.Fn puffs_node_reclaim +or +.Fn puffs_node_reclaim2 +is called. +.It Fn puffs_setback "pcc" "op" +Issue a "setback" operation which will be handled when the request response +is returned to the kernel. +Currently this can be only called from mmap, open, remove and rmdir. +The valid parameters for +.Ar op +are +.Dv PUFFS_SETBACK_INACT_N1 +and +.Dv PUFFS_SETBACK_INACT_N2 . +These signal that a file system mounted with +.Dv PUFFS_KFLAG_IAONDEMAND +should call the file system inactive method for the specified node. +The node number 1 always means the operation cookie +.Ar opc , +while the node number 2 can be used to specify the second node argument +present in some methods, e.g., remove. +.It Fn puffs_newinfo_setcookie pni cookie +Set cookie for node provided by this method to +.Ar cookie . +.It Fn puffs_newinfo_setvtype pni vtype +Set the type of the newly located node to +.Ar vtype . +This call is valid only for +.Fn lookup +and +.Fn fhtonode . +.It Fn puffs_newinfo_setsize pni size +Set the size of the newly located node to +.Ar size . +If left unset, the value defaults to 0. +This call is valid only for +.Fn lookup +and +.Fn fhtovp . +.It Fn puffs_newinfo_setrdev pni rdev +Set the type of the newly located node to +.Ar vtype . +This call is valid only for +.Fn lookup +and +.Fn fhtovp +producing device type nodes. +.It Fn puffs_newinfo_setva pni vap +Set the attributes for newly created vnode. +This call is valid for +.Fn lookup , +.Fn create , +.Fn mkdir , +.Fn mknod , +and +.Fn symlink , +if +.Fn puffs_init +was called with +.Dv PUFFS_KFLAG_CACHE_FS_TTL +flag set. +.It Fn puffs_newinfo_setvattl pni va_ttl +Set cached attribute time to live for newly created vnode. +This call is valid for +.Fn lookup , +.Fn create , +.Fn mkdir , +.Fn mknod , +and +.Fn symlink , +if +.Fn puffs_init +was called with +.Dv PUFFS_KFLAG_CACHE_FS_TTL +flag set. +.It Fn puffs_newinfo_setcnttl pni cn_ttl +Set cached name time to live for newly created vnode. +This call is valid for +.Fn lookup , +.Fn create , +.Fn mkdir , +.Fn mknod , +and +.Fn symlink , +if +.Fn puffs_init +was called with +.Dv PUFFS_KFLAG_CACHE_FS_TTL +flag set. +.El +.Sh SEE ALSO +.Xr puffs 3 , +.Xr vfsops 9 , +.Xr vnodeops 9 diff --git a/static/netbsd/man3/puffs_path.3 b/static/netbsd/man3/puffs_path.3 new file mode 100644 index 00000000..ea02bdd7 --- /dev/null +++ b/static/netbsd/man3/puffs_path.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: puffs_path.3,v 1.4 2009/02/20 14:26:56 pooka Exp $ +.\" +.\" Copyright (c) 2007 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 27, 2007 +.Dt PUFFS_PATH 3 +.Os +.Sh NAME +.Nm puffs_path +.Nd puffs pathbuilding routines +.Sh LIBRARY +.Lb libpuffs +.Sh SYNOPSIS +.In puffs.h +.Ft int +.Fo pu_pathbuild_fn +.Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_dir" +.Fa "const struct puffs_pathobj *po_comp" "size_t offset" +.Fa "struct puffs_pathobj *po_new" +.Fc +.Ft int +.Fo pu_pathtransform_fn +.Fa "struct puffs_usermount *pu" "const struct puffs_pathobj *po_base" +.Fa "const struct puffs_cn *pcn" "struct puffs_pathobj *po_new" +.Fc +.Ft int +.Fo pu_pathcmp_fn +.Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po1" +.Fa "struct puffs_pathobj *po2" "size_t checklen" "int checkprefix" +.Fc +.Ft void +.Fn pu_pathfree_fn "struct puffs_usermount *pu" "struct puffs_pathobj *po" +.Ft int +.Fo pu_namemod_fn +.Fa "struct puffs_usermount *pu" "struct puffs_pathobj *po_dir" +.Fa "struct puffs_cn *pcn" +.Fc +.Ft struct puffs_pathobj * +.Fn puffs_getrootpathobj "struct puffs_usermount *pu" +.Sh DESCRIPTION +The puffs library has the ability to provide full pathnames for backends +which require them. +Normal file systems should be constructed without the file system +node tied to a file name and should not used routines described herein. +An example of a file system where the backend requires filenames is +.Xr mount_psshfs 8 . +.Pp +The features described here are enabled by passing +.Dv PUFFS_FLAG_BUILDPATH +to +.Fn puffs_init . +This facility requires to use puffs nodes to store the contents of the +pathname. +Either the address of the operation cookie must directly be that of the +puffs node, or +.Fn puffs_set_cmap +must be used to set a mapping function from the cookie to the puffs +node associated with the cookie. +Finally, the root node for the file system must be set using +.Fn puffs_setroot +and the root path object retrieved using +.Fn puffs_getrootpathobj +and initialized. +.Pp +There are two different places a filename can be retrieved from. +It is available for each puffs node after the node has been registered +with the framework, i.e. +.Em after +the routine creating the node returns. +In other words, there is a window between the node is created and +when the pathname is available and multithreaded file systems must +take this into account. +The second place where a pathname is available is from the componentname +.Vt struct puffs_pcn +in operations which are passed one. +These can be retrieved using the convenience macros +.Fn PNPATH +and +.Fn PCNPATH +for node and componentname, respectively. +The type of object they return is +.Vt void * . +.Pp +By default the framework manages "regular" filenames, which consist +of directory names separated by "/" and a final component. +If the file system wishes to use pathnames of this format, all it +has to do it enable the feature. +Everything else, including bookkeeping for node and directory renames, +is done by the library. +The callback routines described next provide the ability to build +non-standard pathnames. +A +.Fn pu_foo_fn +callback is set using the +.Fn puffs_set_foo +routine. +.Pp +This manual page is still unfinished. +Please take a number and wait in line. +.Sh SEE ALSO +.Xr puffs 3 , +.Xr puffs_node 3 , +.Xr mount_psshfs 8 , +.Xr mount_sysctlfs 8 diff --git a/static/netbsd/man3/putc.3 b/static/netbsd/man3/putc.3 new file mode 100644 index 00000000..3392883c --- /dev/null +++ b/static/netbsd/man3/putc.3 @@ -0,0 +1,176 @@ +.\" $NetBSD: putc.3,v 1.15 2024/12/12 06:18:24 rillig Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)putc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd September 2, 2019 +.Dt PUTC 3 +.Os +.Sh NAME +.Nm fputc , +.Nm putc , +.Nm putchar , +.Nm putc_unlocked , +.Nm putchar_unlocked , +.Nm putw +.Nd output a character or word to a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn fputc "int c" "FILE *stream" +.Ft int +.Fn putc "int c" "FILE *stream" +.Ft int +.Fn putchar "int c" +.Ft int +.Fn putc_unlocked "int c" "FILE *stream" +.Ft int +.Fn putchar_unlocked "int c" +.Ft int +.Fn putw "int w" "FILE *stream" +.Sh DESCRIPTION +The +.Fn fputc +function +writes the character +.Fa c +(converted to an +.Dq unsigned char ) +to the output stream pointed to by +.Fa stream . +.Pp +.Fn putc +acts essentially identically to +.Fn fputc , +but is a macro that expands in-line. +It may evaluate +.Fa stream +more than once, so arguments given to +.Fn putc +should not be expressions with potential side effects. +.Pp +.Fn putchar +is identical to +.Fn putc +with an output stream of +.Em stdout . +.Pp +The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions provide functionality identical to that of +.Fn putc +and +.Fn putchar , +respectively, but do not perform implicit locking of the streams they +operate on. +In multi-threaded programs they may be used +.Em only +within a scope in which the stream +has been successfully locked by the calling thread using either +.Xr flockfile 3 +or +.Xr ftrylockfile 3 , +and may later be released using +.Xr funlockfile 3 . +.Pp +The +.Fn putw +function +writes the specified +.Em int +to the named output +.Fa stream , +in a binary format. +.Sh RETURN VALUES +The functions +.Fn fputc , +.Fn putc +and +.Fn putchar +return the character written. +If an error occurs, the value +.Dv EOF +is returned. +The +.Fn putw +function +returns 0 on success; +.Dv EOF +is returned if +a write error occurs, +or if an attempt is made to write a read-only stream. +.Sh SEE ALSO +.Xr ferror 3 , +.Xr flockfile 3 , +.Xr fopen 3 , +.Xr getc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputc , +.Fn putc , +and +.Fn putchar , +conform to +.St -ansiC . +The functions +.Fn putc_unlocked +and +.Fn putchar_unlocked +conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn putc +and +.Fn putw +functions first appeared in +.At v1 . +The +.Fn putchar +function first appeared in +.At v4 . +The function +.Fn fputc +appeared in +.At v7 . +.Sh BUGS +The size and byte order of an +.Em int +varies from one machine to another, and +.Fn putw +is not recommended for portable applications. diff --git a/static/netbsd/man3/putwc.3 b/static/netbsd/man3/putwc.3 new file mode 100644 index 00000000..7cde4130 --- /dev/null +++ b/static/netbsd/man3/putwc.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: putwc.3,v 1.9 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)putc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd October 20, 2001 +.Dt PUTWC 3 +.Os +.Sh NAME +.Nm fputwc , +.Nm putwc , +.Nm putwchar , +.Nd output a wide character to a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft wint_t +.Fn fputwc "wchar_t wc" "FILE *stream" +.Ft wint_t +.Fn putwc "wchar_t wc" "FILE *stream" +.Ft wint_t +.Fn putwchar "wchar_t wc" +.Sh DESCRIPTION +The +.Fn fputwc +function +writes the wide character +.Fa wc +to the output stream pointed to by +.Fa stream . +.Pp +.Fn putwc +acts essentially identically to +.Fn fputwc , +but is a macro that expands in-line. +It may evaluate +.Fa stream +more than once, so arguments given to +.Fn putwc +should not be expressions with potential side effects. +.Pp +.Fn putwchar +is identical to +.Fn putwc +with an output stream of +.Em stdout . +.Sh RETURN VALUES +The functions +.Fn fputwc , +.Fn putwc , +and +.Fn putwchar +return the wide character written. +If an error occurs, the value +.Dv WEOF +is returned. +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fopen 3 , +.Xr getwc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputwc , +.Fn putwc , +and +.Fn putwchar , +conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/pw_gensalt.3 b/static/netbsd/man3/pw_gensalt.3 new file mode 100644 index 00000000..2b018c41 --- /dev/null +++ b/static/netbsd/man3/pw_gensalt.3 @@ -0,0 +1,184 @@ +.\" $NetBSD: pw_gensalt.3,v 1.8 2021/10/12 12:03:47 nia Exp $ +.\" +.\" Copyright (c) 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd October 12, 2021 +.Dt PW_GENSALT 3 +.Os +.Sh NAME +.Nm pw_gensalt +.Nd passwd salt generation function +.Sh LIBRARY +.Lb libcrypt +.Sh SYNOPSIS +.In pwd.h +.Ft int +.Fn pw_gensalt "char *salt" "size_t saltlen" "const char *type" "const char *option" +.Sh DESCRIPTION +The +.Fn pw_gensalt +function generates a +.Dq salt +to be added to a password hashing function to guarantee uniqueness and +slow down dictionary and brute force attacks. +The function places a random array of +.Ar saltlen +bytes in +.Ar salt +using the hash function specified in +.Ar type +with the function-specific +.Ar option . +.Pp +The new salt types follow the +.Dq Modular Crypt Format +(MCF) standard and are of the form: +.Bd -literal -offset indent +.Li $<id>[$<param>=<value>(,<param>=<value>)*][$<salt>[$<hash>]] +.Ed +.Pp +The characters allowed in the password salt are alphanumeric and +include a forward slash and a period (are in the regular expression +format +.Li [A-Za-z0-9/.] ) . +.Pp +The following types are available: +.Bl -tag -width blowfish -offset indent +.It old +The original Unix implementation. +This is of the form +.Li _Gl/.???? , +where +.Li \&? +denotes a random alphanumeric character. +The minimum salt size is +.Dv 3 . +.It new +The Seventh Edition Unix 12 bit salt. +This has the same form as the +.Sq old . +The minimum salt size is +.Dv 10 . +The number of rounds can be specified in +.Ar option +and is enforced to be between +.Dv 7250 +and +.Dv 16777215 . +.It newsalt +An alias for +.Sq new . +.It md5 +A salt generated using the +.Xr md5 1 +algorithm. +This is of the form +.Li $1$????????$ . +The minimum salt size is +.Dv 13 . +.It sha1 +A salt generated using the +.Xr sha1 1 +algorithm. +This is of the form +.Li $sha1$nrounds$????????$ , +where +.Ar nrounds +is the number of rounds to be used. +The number of rounds can be specified in +.Ar option , +and defaults to random if +.Dv NULL . +The minimum salt size is +.Dv 8 +and the maximum is +.Dv 64 . +.It blowfish +A salt generated using the +.Sq blowfish +algorithm. +The minimum salt size is +.Dv 30 +and the number of rounds needs to be specified in +.Ar option . +This is of the form: +.Li $2a$nrounds$?????????????????????? . +The +.Li 2 +in the salt string indicates the current blowfish version. +.It argon2d +This is of the form: +.Li $argon2d$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ +.It argon2i +This is of the form: +.Li $argon2i$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ +.It argon2id +This is of the form: +.Li $argon2id$v=19$m=MEMORY,t=TIME,p=THREADS$????????????????$ +.It argon2 +An alias for +.Dq argon2id . +.Pp +See +.Xr crypt 3 +for details on the Argon2 parameters. +.El +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn pw_gensalt +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +If the +.Ar option +is not specified or has an illegal value. +.It Bq Er ENOSPC +The +.Ar saltlen +was not large enough to fit the salt for the specified +.Ar type . +.El +.Sh SEE ALSO +.Xr passwd 1 , +.Xr pwhash 1 +.Sh HISTORY +The +.Fn pw_gensalt +function was written in 1997 by +.An Niels Provos Aq Mt provos@physnet.uni-hamburg.de . +.Pp +The +.Lk https://passlib.readthedocs.io/en/stable/modular_crypt_format.html "Modular Crypt Format (MCF)" . +.Pp +The +.Lk https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md "Password Hashing Competition (PHC) format" . diff --git a/static/netbsd/man3/pw_getconf.3 b/static/netbsd/man3/pw_getconf.3 new file mode 100644 index 00000000..5b707c9a --- /dev/null +++ b/static/netbsd/man3/pw_getconf.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: pw_getconf.3,v 1.13 2025/12/31 13:02:21 nia Exp $ +.\" +.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" from OpenBSD: pw_getconf.3,v 1.5 1999/09/21 04:52:46 csapuntz Exp +.\" +.Dd May 4, 2010 +.Dt PW_GETCONF 3 +.Os +.Sh NAME +.Nm pw_getconf , +.Nm pw_getpwconf +.Nd password encryption configuration access function +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft void +.Fn pw_getconf "char *data" "size_t len" "const char *key" "const char *option" +.Ft void +.Fn pw_getpwconf "char *data" "size_t len" "const struct passwd *pwd" "const char *option" +.Sh DESCRIPTION +The +.Fn pw_getconf +function reads +.Pa /etc/passwd.conf +and retrieves the value of the option specified +by +.Pa option +from the section given by +.Pa key . +If no suitable entry is found +for the +.Pa key +an empty string will be returned in data. +.Pp +To retrieve default values the key +.Pa default +can be used. +In this case, if +.Pa /etc/passwd.conf +does not exist or does not contain a +.Pa default +section, the built-in defaults will be returned. +They are as follows: +.Bl -column localcipher data -offset indent +.It Sy option data +.It ypcipher old +.It localcipher old +.El +.Pp +An empty string is returned for all errors. +.Pp +.Fn pw_getpwconf +returns the value for the option specified for the particular user +specified in +.Ar pwd . +If that option is not found, then it tries to find the option in +the primary group of that user, and if that fails, then it returns +the default entry. +.Sh FILES +.Bl -tag -width /etc/passwd.conf -compact +.It Pa /etc/passwd.conf +.El +.Sh ERRORS +.Fn pw_getconf +and +.Fn pw_getpwconf +will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +There is no option named +.Pa option +in the specified key. +.It Bq Er ENOTDIR +There is no key in +.Pa /etc/passwd.conf +named +.Pa key . +.El +.Sh SEE ALSO +.Xr passwd 5 , +.Xr passwd.conf 5 +.Sh HISTORY +The +.Fn pw_getconf +function first appeared in +.Nx 1.6 . diff --git a/static/netbsd/man3/pw_init.3 b/static/netbsd/man3/pw_init.3 new file mode 100644 index 00000000..49beb0d0 --- /dev/null +++ b/static/netbsd/man3/pw_init.3 @@ -0,0 +1,233 @@ +.\" $NetBSD: pw_init.3,v 1.17 2022/12/04 11:16:39 uwe Exp $ +.\" +.\" Copyright (c) 1995 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2004 +.Dt PW_INIT 3 +.Os +.Sh NAME +.Nm pw_init , +.Nm pw_edit , +.Nm pw_prompt , +.Nm pw_copy , +.Nm pw_copyx , +.Nm pw_scan , +.Nm pw_error +.Nd utility functions for interactive passwd file updates +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In pwd.h +.In util.h +.Ft void +.Fn pw_init "void" +.Ft void +.Fn pw_edit "int notsetuid" "const char *filename" +.Ft void +.Fn pw_prompt "void" +.Ft void +.Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" +.Ft int +.Fn pw_copyx "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" \ + "char *errbuf" "size_t errbufsz" +.Ft int +.Fn pw_scan "char *bp" "struct passwd *pw" "int *flags" +.Ft void +.Fn pw_error "const char *name" "int err" "int eval" +.Sh DESCRIPTION +These functions are designed as conveniences for interactive programs +which update the passwd file and do nothing else. +They generally handle errors by printing out a message to the standard error +stream and possibly aborting the process. +.Pp +The +.Fn pw_init +function prepares for a passwd update by unlimiting all resource +constraints, disabling core dumps (thus preventing dumping the +contents of the passwd database into a world-readable file), and +disabling most signals. +.Pp +The +.Fn pw_edit +function runs an editor (named by the environment variable +.Ev EDITOR , +or +.Pa /usr/bin/vi +if +.Ev EDITOR +is not set) on the file +.Fa filename +(or +.Pa /etc/ptmp +if +.Fa filename +is +.Dv NULL ) . +If +.Fa notsetuid +is nonzero, +.Fn pw_edit +will set the effective user and group ID to the real user and group ID +before running the editor. +.Pp +The +.Fn pw_prompt +function asks the user whether he or she wants to re-edit the password +file; if the answer is no, +.Fn pw_prompt +deletes the lock file and exits the process. +.Pp +The +.Fn pw_copy +function reads a passwd file from +.Fa ffd +and writes it to +.Fa tfd , +updating the entry corresponding to pw->pw_name with the information +in +.Fa pw . +If +.Fa old_pw +is not +.Dv NULL , +it checks to make sure the old entry is the same as +the one described in +.Fa old_pw +or the process is aborted. +If an entry is not found to match +.Fa pw , +a new entry is appended to the passwd file only if the real user +ID is 0. +If an error occurs, +.Fn pw_copy +will display a message on +.Dv stderr +and call +.Fn pw_error . +.Pp +The +.Fn pw_copyx +function performs the same operation as +.Fn pw_copy +with the exception of error handling. +Upon an error, +.Fn pw_copyx +will write an error message into the buffer pointed to by +.Fa errbuf +which has the size +.Fa errbufsz . +.Pp +The +.Fn pw_scan +function accepts in +.Fa bp +a passwd entry as it would be represented in +.Pa /etc/master.passwd +and fills in +.Fa pw +with corresponding values; string fields in +.Fa pw +will be pointers into +.Fa bp . +Some characters in +.Fa bp +will be overwritten with 0s in order to terminate the strings pointed +to by +.Fa pw . +If +.Fa flags +is non-null, it should be cleared and the following options +enabled if required: +.Bl -tag -offset indent -width _PASSWORD_OLDFMT +.It Dv _PASSWORD_NOWARN +Don't print warnings. +.It Dv _PASSWORD_OLDFMT +Parse +.Fa bp +as an old format entry as found in +.Pa /etc/passwd . +.El +.Pp +Upon return it is cleared, and filled in with the following flags: +.Bl -tag -offset indent -width _PASSWORD_NOGID +.It Dv _PASSWORD_NOUID +The uid field of +.Fa bp +is empty. +.It Dv _PASSWORD_NOGID +The gid field of +.Fa bp +is empty. +.It Dv _PASSWORD_NOCHG +The change field of +.Fa bp +is empty. +.It Dv _PASSWORD_NOEXP +The expire field of +.Fa bp +is empty. +.El +.Pp +The +.Fn pw_error +function displays an error message, aborts the current passwd update, +and exits the current process. +If +.Fa err +is non-zero, a warning message beginning with +.Fa name +is printed for the current value of +.Va errno . +The process exits with status +.Fa eval . +.Sh RETURN VALUES +The +.Fn pw_copyx +function returns 1 if the new password entry was successfully written +to the destination file, and 0 otherwise. +.Pp +The +.Fn pw_scan +function prints a warning message and returns 0 if the string in the +.Fa bp +argument is not a valid passwd string. +Otherwise, +.Fn pw_scan +returns 1. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/master.passwd +.It Pa /etc/ptmp +.El +.Sh SEE ALSO +.Xr pw_lock 3 , +.Xr passwd 5 diff --git a/static/netbsd/man3/pw_lock.3 b/static/netbsd/man3/pw_lock.3 new file mode 100644 index 00000000..e57d37db --- /dev/null +++ b/static/netbsd/man3/pw_lock.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: pw_lock.3,v 1.14 2010/05/05 22:05:31 wiz Exp $ +.\" +.\" Copyright (c) 1995 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software developed by the Computer Systems +.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract +.\" BG 91-66 and contributed to Berkeley. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 17, 2007 +.Dt PW_LOCK 3 +.Os +.Sh NAME +.Nm pw_lock , +.Nm pw_mkdb , +.Nm pw_abort , +.Nm pw_setprefix , +.Nm pw_getprefix +.Nd passwd file update functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn pw_lock "int retries" +.Ft int +.Fn pw_mkdb "const char *username" "int secureonly" +.Ft void +.Fn pw_abort "void" +.Ft int +.Fn pw_setprefix "const char *new_prefix" +.Ft "const char *" +.Fn pw_getprefix "void" +.Sh DESCRIPTION +The +.Fn pw_lock , +.Fn pw_mkdb , +and +.Fn pw_abort +functions allow a program to update the system passwd database. +.Pp +The +.Fn pw_lock +function attempts to lock the passwd database by creating the file +.Pa /etc/ptmp , +and returns the file descriptor of that file. +If +.Fa retries +is greater than zero, +.Fn pw_lock +will try multiple times to open +.Pa /etc/ptmp , +waiting one second between tries. +In addition to being a lock file, +.Pa /etc/ptmp +will also hold the contents of the new passwd file. +.Pp +The +.Fn pw_mkdb +function updates the passwd file from the contents of +.Pa /etc/ptmp . +You should finish writing to and close the file descriptor returned by +.Fn pw_lock +before calling +.Fn pw_mkdb . +If +.Fn pw_mkdb +fails and you do not wish to retry, you should make sure to call +.Fn pw_abort +to clean up the lock file. +If the +.Ar username +argument is not +.Dv NULL , +only database entries pertaining to the specified user +will be modified. +If the +.Ar secureonly +argument is non-zero, only the secure database will be updated. +.Pp +The +.Fn pw_abort +function aborts a passwd file update by deleting +.Pa /etc/ptmp . +The passwd database remains unchanged. +.Pp +The +.Fn pw_setprefix +function defines the root directory used for passwd file updates. +If the prefix is set to +.Pa /newroot +.Fn pw_lock +will operate on +.Pa /newroot/etc/ptmp +afterwards. +The default prefix is an empty string. +.Pp +The +.Fn pw_getprefix +function returns the root directory which is currently used for passwd file +updates. +.Sh RETURN VALUES +The +.Fn pw_lock +and +.Fn pw_mkdb +functions return -1 if they are unable to complete properly. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/master.passwd +.It Pa /etc/ptmp +.El +.Sh SEE ALSO +.Xr pw_init 3 , +.Xr pwd_mkdb 8 diff --git a/static/netbsd/man3/pwcache.3 b/static/netbsd/man3/pwcache.3 new file mode 100644 index 00000000..d7632bbd --- /dev/null +++ b/static/netbsd/man3/pwcache.3 @@ -0,0 +1,224 @@ +.\" $NetBSD: pwcache.3,v 1.18 2017/10/24 19:04:58 abhinav Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.\" @(#)pwcache.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd January 24, 2002 +.Dt PWCACHE 3 +.Os +.Sh NAME +.Nm pwcache , +.Nm user_from_uid , +.Nm uid_from_user , +.Nm pwcache_userdb , +.Nm group_from_gid , +.Nm gid_from_group , +.Nm pwcache_groupdb +.Nd cache password and group entries +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In pwd.h +.Ft const char * +.Fn user_from_uid "uid_t uid" "int nouser" +.Ft int +.Fn uid_from_user "const char *name" "uid_t *uid" +.Ft int +.Fn pwcache_userdb "int (*setpassent)(int)" "void (*endpwent)(void)" "struct passwd * (*getpwnam)(const char *)" "struct passwd * (*getpwuid)(uid_t)" +.In grp.h +.Ft const char * +.Fn group_from_gid "gid_t gid" "int nogroup" +.Ft int +.Fn gid_from_group "const char *name" "gid_t *gid" +.Ft int +.Fn pwcache_groupdb "int (*setgroupent)(int)" "void (*endgrent)(void)" "struct group * (*getgrnam)(const char *)" "struct group * (*getgrgid)(gid_t)" +.Sh DESCRIPTION +The +.Fn user_from_uid +function returns the user name associated with the argument +.Fa uid . +The user name is cached so that multiple calls with the same +.Fa uid +do not require additional calls to +.Xr getpwuid 3 . +If there is no user associated with the +.Fa uid , +a pointer is returned +to a string representation of the +.Fa uid , +unless the argument +.Fa nouser +is non-zero, in which case a +.Dv NULL +pointer is returned. +.Pp +The +.Fn group_from_gid +function returns the group name associated with the argument +.Fa gid . +The group name is cached so that multiple calls with the same +.Fa gid +do not require additional calls to +.Xr getgrgid 3 . +If there is no group associated with the +.Fa gid , +a pointer is returned +to a string representation of the +.Fa gid , +unless the argument +.Fa nogroup +is non-zero, in which case a +.Dv NULL +pointer is returned. +.Pp +The +.Fn uid_from_user +function returns the uid associated with the argument +.Fa name . +The uid is cached so that multiple calls with the same +.Fa name +do not require additional calls to +.Xr getpwnam 3 . +If there is no uid associated with the +.Fa name , +the +.Fn uid_from_user +function returns \-1; otherwise it stores the uid at the location pointed to by +.Fa uid +and returns 0. +.Pp +The +.Fn gid_from_group +function returns the gid associated with the argument +.Fa name . +The gid is cached so that multiple calls with the same +.Fa name +do not require additional calls to +.Xr getgrnam 3 . +If there is no gid associated with the +.Fa name , +the +.Fn gid_from_group +function returns \-1; otherwise it stores the gid at the location pointed to by +.Fa gid +and returns 0. +.Pp +The +.Fn pwcache_userdb +function changes the user database access routines which +.Fn user_from_uid +and +.Fn uid_from_user +call to search for users. +The caches are flushed and the existing +.Fn endpwent +method is called before switching to the new routines. +.Fa getpwnam +and +.Fa getpwuid +must be provided, and +.Fa setpassent +and +.Fa endpwent +may be +.Dv NULL +pointers. +.Pp +The +.Fn pwcache_groupdb +function changes the group database access routines which +.Fn group_from_gid +and +.Fn gid_from_group +call to search for groups. +The caches are flushed and the existing +.Fn endgrent +method is called before switching to the new routines. +.Fa getgrnam +and +.Fa getgrgid +must be provided, and +.Fa setgroupent +and +.Fa endgrent +may be +.Dv NULL +pointers. +.Sh SEE ALSO +.Xr getgrgid 3 , +.Xr getgrnam 3 , +.Xr getpwnam 3 , +.Xr getpwuid 3 +.Sh HISTORY +The +.Fn user_from_uid +and +.Fn group_from_gid +functions first appeared in +.Bx 4.4 . +.Pp +The +.Fn uid_from_user +and +.Fn gid_from_group +functions first appeared in +.Nx 1.4 . +.Pp +The +.Fn pwcache_userdb +and +.Fn pwcache_groupdb +functions first appeared in +.Nx 1.6 . diff --git a/static/netbsd/man3/qabs.3 b/static/netbsd/man3/qabs.3 new file mode 100644 index 00000000..95306af2 --- /dev/null +++ b/static/netbsd/man3/qabs.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: qabs.3,v 1.9 2008/08/04 21:29:27 matt Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)labs.3 5.3 (Berkeley) 6/29/91 +.\" +.Dd June 29, 1991 +.Dt QABS 3 +.Os +.Sh NAME +.Nm qabs +.Nd return the absolute value of a quad integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft quad_t +.Fn qabs "quad_t j" +.Sh DESCRIPTION +The +.Fn qabs +function +returns the absolute value of the quad integer +.Ar j . +.Sh SEE ALSO +.Xr abs 3 , +.Xr cabs 3 , +.Xr floor 3 , +.Xr imaxabs 3 , +.Xr labs 3 , +.Xr llabs 3 , +.Xr math 3 +.Sh BUGS +The absolute value of the most negative integer remains negative. diff --git a/static/netbsd/man3/qdiv.3 b/static/netbsd/man3/qdiv.3 new file mode 100644 index 00000000..0d308372 --- /dev/null +++ b/static/netbsd/man3/qdiv.3 @@ -0,0 +1,67 @@ +.\" $NetBSD: qdiv.3,v 1.9 2008/08/04 21:29:27 matt Exp $ +.\" +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)qdiv.3 5.3 (Berkeley) 6/29/91 +.\" +.Dd June 29, 1991 +.Dt QDIV 3 +.Os +.Sh NAME +.Nm qdiv +.Nd return quotient and remainder from division +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft qdiv_t +.Fn qdiv "quad_t num" "quad_t denom" +.Sh DESCRIPTION +The +.Fn qdiv +function +computes the value +.Ar num/denom +and returns the quotient and remainder in a structure named +.Ar qdiv_t +that contains two +.Em quad integer +members named +.Ar quot +and +.Ar rem . +.Sh SEE ALSO +.Xr div 3 , +.Xr imaxdiv 3 , +.Xr ldiv 3 , +.Xr lldiv 3 , +.Xr math 3 diff --git a/static/netbsd/man3/qsort.3 b/static/netbsd/man3/qsort.3 new file mode 100644 index 00000000..ebe8c482 --- /dev/null +++ b/static/netbsd/man3/qsort.3 @@ -0,0 +1,279 @@ +.\" $NetBSD: qsort.3,v 1.16 2025/07/20 23:52:00 dholland Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)qsort.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 20, 2025 +.Dt QSORT 3 +.Os +.Sh NAME +.Nm qsort , +.Nm heapsort , +.Nm mergesort , +.Nm qsort_r , +.Nm heapsort_r , +.Nm mergesort_r +.Nd sort functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn qsort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.Ft void +.Fn qsort_r "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *, void *)" "void *cookie" +.Ft int +.Fn heapsort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.Ft int +.Fn heapsort_r "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *, void *)" "void *cookie" +.Ft int +.Fn mergesort "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *)" +.Ft int +.Fn mergesort_r "void *base" "size_t nmemb" "size_t size" "int (*compar)(const void *, const void *, void *)" "void *cookie" +.Sh DESCRIPTION +The +.Fn qsort +function is a modified partition-exchange sort, or quicksort. +The +.Fn heapsort +function is a modified selection sort. +The +.Fn mergesort +function is a modified merge sort with exponential search +intended for sorting data with pre-existing order. +.Pp +The +.Fn qsort +and +.Fn heapsort +functions sort an array of +.Fa nmemb +objects, the initial member of which is pointed to by +.Fa base . +The size of each object is specified by +.Fa size . +.Fn mergesort +behaves similarly, but +.Em requires +that +.Fa size +be greater than +.Dq "sizeof(void *) / 2" . +.Pp +The contents of the array +.Fa base +are sorted in ascending order according to +a comparison function pointed to by +.Fa compar , +which requires two arguments pointing to the objects being +compared. +.Pp +The comparison function must return an integer less than, equal to, or +greater than zero if the first argument is considered to be respectively +less than, equal to, or greater than the second. +.Pp +The functions +.Fn qsort +and +.Fn heapsort +are +.Em not +stable, that is, if two members compare as equal, their order in +the sorted array is undefined. +The function +.Fn mergesort +is stable. +.Pp +The +.Fn qsort_r , +.Fn heapsort_r , +and +.Fn mergesort_r +functions pass an additional cookie argument through to the comparison +function. +.Pp +The +.Fn qsort +function is an implementation of C.A.R. Hoare's ``quicksort'' algorithm, +a variant of partition-exchange sorting; in particular, see D.E. Knuth's +Algorithm Q. +.Fn qsort +takes O N lg N average time. +This implementation uses median selection to avoid its +O N**2 worst-case behavior. +.Pp +The +.Fn heapsort +function is an implementation of J.W.J. William's ``heapsort'' algorithm, +a variant of selection sorting; in particular, see D.E. Knuth's Algorithm H. +.Fn heapsort +takes O N lg N worst-case time. +Its +.Em only +advantage over +.Fn qsort +is that it uses almost no additional memory; while +.Fn qsort +does not allocate memory, it is implemented using recursion. +.Pp +The function +.Fn mergesort +requires additional memory of size +.Fa nmemb * +.Fa size +bytes; it should be used only when space is not at a premium. +.Fn mergesort +is optimized for data with pre-existing order; its worst case +time is O N lg N; its best case is O N. +.Pp +Normally, +.Fn qsort +is faster than +.Fn mergesort +is faster than +.Fn heapsort . +Memory availability and pre-existing order in the data can make this +untrue. +.Sh RETURN VALUES +The +.Fn qsort +and +.Fn qsort_r +functions +return no value. +.Pp +Upon successful completion, +.Fn heapsort , +.Fn mergesort +.Fn heapsort_r , +and +.Fn mergesort_r +return 0. +Otherwise, they return \-1 and the global variable +.Va errno +is set to indicate the error. +.Sh COMPATIBILITY +Previous versions of +.Fn qsort +did not permit the comparison routine itself to call +.Fn qsort . +This is no longer true. +.Sh ERRORS +The +.Fn heapsort , +.Fn mergesort +.Fn heapsort_r , +and +.Fn heapsort_r +functions succeed unless: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa size +argument is zero, or, +the +.Fa size +argument to +.Fn mergesort +or +.Fn mergesort_r +is less than +.Dq "sizeof(void *) / 2" . +.It Bq Er ENOMEM +.Fn heapsort , +.Fn heapsort_r , +.Fn mergesort , +or +.Fn mergesort_r +were unable to allocate memory. +.El +.Sh SEE ALSO +.Xr sort 1 , +.Xr radixsort 3 +.Rs +.%A Hoare, C.A.R. +.%D 1962 +.%T "Quicksort" +.%J "The Computer Journal" +.%V 5:1 +.%P pp. 10-15 +.Re +.Rs +.%A Williams, J.W.J +.%D 1964 +.%T "Heapsort" +.%J "Communications of the ACM" +.%V 7:1 +.%P pp. 347-348 +.Re +.Rs +.%A Knuth, D.E. +.%D 1968 +.%B "The Art of Computer Programming" +.%V Vol. 3 +.%T "Sorting and Searching" +.%P pp. 114-123, 145-149 +.Re +.Rs +.%A McIlroy, P.M. +.%D 1993 +.%T "Optimistic Sorting and Information Theoretic Complexity" +.%J "Proceedings of the Fourth Annual ACM-SIAM Symposium on Discrete Algorithms" +.%P pp. 467-474 +.Re +.Rs +.%A Bentley, J.L. and McIlroy, M.D. +.%D 1993 +.%T "Engineering a Sort Function" +.%J "Software-Practice and Experience" +.%V Vol. 23 +.%P pp. 1249-1265 +.Re +.Sh STANDARDS +The +.Fn qsort +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn qsort_r , +.Fn heapsort_r , +and +.Fn mergesort_r +functions were added in +.Nx 11.0 . +.Pp +The +.Fn qsort_r +function conforms to +.St -p1003.1-2024 . diff --git a/static/netbsd/man3/quick_exit.3 b/static/netbsd/man3/quick_exit.3 new file mode 100644 index 00000000..4e6e7975 --- /dev/null +++ b/static/netbsd/man3/quick_exit.3 @@ -0,0 +1,68 @@ +.\" $NetBSD: quick_exit.3,v 1.3 2015/07/26 17:03:06 christos Exp $ +.\" Copyright (c) 2011 David Chisnall +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libc/stdlib/quick_exit.3,v 1.4 2012/11/17 01:49:41 svnexp Exp $ +.\" +.Dd July 26, 2015 +.Dt QUICK_EXIT 3 +.Os +.Sh NAME +.Nm quick_exit +.Nd exits a program quickly, running minimal cleanup +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft _Noreturn void +.Fn quick_exit "int status" +.Sh DESCRIPTION +The +.Fn quick_exit +function exits the program quickly calling any cleanup functions registered +with +.Xr at_quick_exit 3 +but not any C++ destructors or cleanup code registered with +.Xr atexit 3 . +.Pp +The +.Fa status +values +.Dv EXIT_SUCCESS +and +.Dv EXIT_FAILURE +can be used to indicate successful and unsuccessful +termination, respectively. +.Sh RETURN VALUES +The +.Fn quick_exit +function does not return. +.Sh SEE ALSO +.Xr at_quick_exit 3 , +.Xr exit 3 +.Sh STANDARDS +The +.Fn quick_exit +function conforms to +.St -isoC-2011 . diff --git a/static/netbsd/man3/radixsort.3 b/static/netbsd/man3/radixsort.3 new file mode 100644 index 00000000..109466ab --- /dev/null +++ b/static/netbsd/man3/radixsort.3 @@ -0,0 +1,167 @@ +.\" $NetBSD: radixsort.3,v 1.13 2003/08/07 16:43:43 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)radixsort.3 8.2 (Berkeley) 1/27/94 +.\" +.Dd January 27, 1994 +.Dt RADIXSORT 3 +.Os +.Sh NAME +.Nm radixsort , +.Nm sradixsort +.Nd radix sort +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In limits.h +.In stdlib.h +.Ft int +.Fn radixsort "const u_char **base" "int nmemb" "u_char *table" "u_int endbyte" +.Ft int +.Fn sradixsort "const u_char **base" "int nmemb" "u_char *table" "u_int endbyte" +.Sh DESCRIPTION +The +.Fn radixsort +and +.Fn sradixsort +functions +are implementations of radix sort. +.Pp +These functions sort an +.Fa nmemb +element array of pointers to byte strings, with +the initial member of which is referenced by +.Fa base . +The byte strings may contain any values. +End of strings is denoted +by character which has same weight as user specified value +.Fa endbyte . +.Fa endbyte +has to be between 0 and 255. +.Pp +Applications may specify a sort order by providing the +.Fa table +argument. +If +.Pf non- Dv NULL , +.Fa table +must reference an array of +.Dv UCHAR_MAX ++ 1 bytes which contains the sort +weight of each possible byte value. +The end-of-string byte must have a sort weight of 0 or 255 +(for sorting in reverse order). +More than one byte may have the same sort weight. +The +.Fa table +argument +is useful for applications which wish to sort different characters +equally, for example, providing a table with the same weights +for A-Z as for a-z will result in a case-insensitive sort. +If +.Fa table +is NULL, the contents of the array are sorted in ascending order +according to the +.Tn ASCII +order of the byte strings they reference and +.Fa endbyte +has a sorting weight of 0. +.Pp +The +.Fn sradixsort +function is stable, that is, if two elements compare as equal, their +order in the sorted array is unchanged. +The +.Fn sradixsort +function uses additional memory sufficient to hold +.Fa nmemb +pointers. +.Pp +The +.Fn radixsort +function is not stable, but uses no additional memory. +.Pp +These functions are variants of most-significant-byte radix sorting; in +particular, see D.E. Knuth's Algorithm R and section 5.2.5, exercise 10. +They take linear time relative to the number of bytes in the strings. +.Sh RETURN VALUES +Upon successful completion 0 is returned. +Otherwise, \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa endbyte +element of +.Fa table +is not 0 or 255. +.El +.Pp +Additionally, the +.Fn sradixsort +function +may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 . +.Sh SEE ALSO +.Xr sort 1 , +.Xr qsort 3 +.Pp +.Rs +.%A Knuth, D.E. +.%D 1968 +.%B "The Art of Computer Programming" +.%T "Sorting and Searching" +.%V Vol. 3 +.%P pp. 170-178 +.Re +.Rs +.%A Paige, R. +.%D 1987 +.%T "Three Partition Refinement Algorithms" +.%J "SIAM J. Comput." +.%V Vol. 16 +.%N No. 6 +.Re +.Rs +.%A McIlroy, P. +.%D 1993 +.%B "Engineering Radix Sort" +.%T "Computing Systems" +.%V Vol. 6:1 +.%P pp. 5-27 +.Re +.Sh HISTORY +The +.Fn radixsort +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/raise.3 b/static/netbsd/man3/raise.3 new file mode 100644 index 00000000..bbef7745 --- /dev/null +++ b/static/netbsd/man3/raise.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: raise.3,v 1.10 2011/05/09 09:06:21 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)raise.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 9, 2011 +.Dt RAISE 3 +.Os +.Sh NAME +.Nm raise +.Nd send a signal to the current thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn raise "int sig" +.Sh DESCRIPTION +The +.Fn raise +function sends the signal +.Fa sig +to the current thread. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn raise +function +may fail and set +.Va errno +for any of the errors specified for the +library functions +.Xr _lwp_self 2 +and +.Xr _lwp_kill 2 . +.Sh SEE ALSO +.Xr kill 2 , +.Xr raise_default_signal 3 +.Sh STANDARDS +The +.Fn raise +function +conforms to +.St -ansiC +and +.St -susv2 . diff --git a/static/netbsd/man3/raise_default_signal.3 b/static/netbsd/man3/raise_default_signal.3 new file mode 100644 index 00000000..9b2c0a88 --- /dev/null +++ b/static/netbsd/man3/raise_default_signal.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: raise_default_signal.3,v 1.3 2011/03/27 12:53:16 njoly Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 25, 2007 +.Dt RAISE_DEFAULT_SIGNAL 3 +.Os +.Sh NAME +.Nm raise_default_signal +.Nd raise the default signal handler +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fo raise_default_signal +.Fa "int sig" +.Fc +.Sh DESCRIPTION +The +.Fn raise_default_signal +function raises the default signal handler for the signal +.Fa sig . +This function may be used by a user-defined signal handler router +to ensure that a parent process receives the correct notification +of a process termination by a signal. +This can be used to avoid a common programming mistake +when terminating a process from a custom +.Dv SIGINT +or +.Dv SIGQUIT +signal handler. +.Pp +The operations performed are: +.Bl -enum -offset indent +.It +Block all signals, using +.Xr sigprocmask 2 . +.It +Set the signal handler for signal +.Fa sig +to the default signal handler +.Dv ( SIG_DFL ) . +.It +.Xr raise 3 +signal +.Fa sig . +.It +Unblock signal +.Fa sig +to deliver it. +.It +Restore the original signal mask and handler, +even if there was a failure. +.El +.Pp +See +.Xr signal 7 +for a table of signals and default actions. +.Pp +The +.Fn raise_default_signal +function should be async-signal-safe. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn raise_default_signal +function may fail and set +.Va errno +for any of the errors specified for the functions +.Xr sigemptyset 3 , +.Xr sigfillset 3 , +.Xr sigaddset 3 , +.Xr sigprocmask 2 , +.Xr sigaction 2 , +or +.Xr raise 3 . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr raise 3 , +.Xr signal 7 +.Sh HISTORY +The +.Fn raise_default_signal +function first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/rand.3 b/static/netbsd/man3/rand.3 new file mode 100644 index 00000000..85f04236 --- /dev/null +++ b/static/netbsd/man3/rand.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: rand.3,v 1.12 2010/03/22 19:30:54 joerg Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)rand.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt RAND 3 +.Os +.Sh NAME +.Nm rand , +.Nm srand , +.Nm rand_r +.Nd bad random number generator +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn srand "unsigned int seed" +.Ft int +.Fn rand void +.Ft int +.Fn rand_r "unsigned int *seed" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are obsoleted by +.Xr random 3 . +.Ef +.Pp +The +.Fn rand +function computes a sequence of pseudo-random integers in the range +of 0 to +.Dv RAND_MAX +(as defined by the header file +.In stdlib.h ) . +.Pp +The +.Fn srand +function sets its argument as the seed for a new sequence of +pseudo-random numbers to be returned by +.Fn rand . +These sequences are repeatable by calling +.Fn srand +with the same seed value. +.Pp +If no seed value is provided, the +.Fn rand +function is automatically seeded with a value of 1. +.Pp +The +.Fn rand_r +function is a reentrant interface to +.Fn rand ; +the seed has to be supplied and is maintained by the caller. +.Sh SEE ALSO +.Xr random 3 , +.Xr rnd 4 +.Sh STANDARDS +The +.Fn rand +and +.Fn srand +functions +conform to +.St -ansiC . +The +.Fn rand_r +function conforms to +.St -p1003.1c-95 . diff --git a/static/netbsd/man3/rand48.3 b/static/netbsd/man3/rand48.3 new file mode 100644 index 00000000..2deb8c70 --- /dev/null +++ b/static/netbsd/man3/rand48.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: rand48.3,v 1.14 2021/02/16 14:44:25 riastradh Exp $ +.\" +.\" Copyright (c) 1993 Martin Birgmeier +.\" All rights reserved. +.\" +.\" You may redistribute unmodified or modified versions of this source +.\" code provided that the above copyright notice and this and the +.\" following conditions are retained. +.\" +.\" This software is provided ``as is'', and comes with no warranties +.\" of any kind. I shall in no event be liable for anything that happens +.\" to anyone/anything when using this software. +.\" +.Dd February 22, 2020 +.Dt RAND48 3 +.Os +.Sh NAME +.Nm drand48 , +.Nm erand48 , +.Nm lrand48 , +.Nm nrand48 , +.Nm mrand48 , +.Nm jrand48 , +.Nm srand48 , +.Nm seed48 , +.Nm lcong48 +.Nd pseudo-random number generators and initialization routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft double +.Fn drand48 void +.Ft double +.Fn erand48 "unsigned short xseed[3]" +.Ft long +.Fn lrand48 void +.Ft long +.Fn nrand48 "unsigned short xseed[3]" +.Ft long +.Fn mrand48 void +.Ft long +.Fn jrand48 "unsigned short xseed[3]" +.Ft void +.Fn srand48 "long seed" +.Ft "unsigned short *" +.Fn seed48 "unsigned short xseed[3]" +.Ft void +.Fn lcong48 "unsigned short p[7]" +.Sh DESCRIPTION +The +.Fn rand48 +family of functions generates pseudo-random numbers using a linear +congruential algorithm working on integers 48 bits in size. +The particular formula employed is +r(n+1) = (a * r(n) + c) mod m +where the default values are +for the multiplicand a = 0x5deece66d = 25214903917 and +the addend c = 0xb = 11. +The modulus is always fixed at m = 2 ** 48. +r(n) is called the seed of the random number generator. +.Pp +For all the six generator routines described next, the first +computational step is to perform a single iteration of the algorithm. +.Pp +.Fn drand48 +and +.Fn erand48 +return values of type double. +The full 48 bits of r(n+1) are loaded into the significand of the +returned value, with the exponent set such that the values produced +lie in the interval [0.0, 1.0). +.Pp +.Fn lrand48 +and +.Fn nrand48 +return values of type long in the range [0, 2**31-1]. +The high-order (31) bits of r(n+1) are loaded into the lower bits +of the returned value, with the topmost (sign) bit set to zero. +.Pp +.Fn mrand48 +and +.Fn jrand48 +return values of type long in the range [-2**31, 2**31-1]. +The high-order (32) bits of r(n+1) are loaded into the returned value. +.Pp +.Fn drand48 , +.Fn lrand48 , +and +.Fn mrand48 +use an internal buffer to store r(n). +For these functions +the initial value of r(0) = 0x1234abcd330e = 20017429951246. +.Pp +On the other hand, +.Fn erand48 , +.Fn nrand48 , +and +.Fn jrand48 +use a user-supplied buffer to store the seed r(n), which consists +of an array of 3 unsigned shorts, where the zeroth member holds the least +significant bits. +.Pp +All functions share the same multiplicand and addend. +.Pp +.Fn srand48 +is used to initialize the internal buffer r(n) of +.Fn drand48 , +.Fn lrand48 , +and +.Fn mrand48 +such that the 32 bits of the seed value are copied into the upper 32 bits +of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e. +Additionally, the constant multiplicand and addend of the algorithm are +reset to the default values given above. +.Pp +.Fn seed48 +also initializes the internal buffer r(n) of +.Fn drand48 , +.Fn lrand48 , +and +.Fn mrand48 , +but here all 48 bits of the seed can be specified in an array of 3 unsigned shorts, +where the zeroth member specifies the lowest bits. +Again, the constant multiplicand and addend of the algorithm are +reset to the default values given above. +.Fn seed48 +returns a pointer to an array of 3 unsigned shorts which contains the old seed. +This array is statically allocated, thus its contents are lost after +each new call to +.Fn seed48 . +.Pp +Finally, +.Fn lcong48 +allows full control over the multiplicand and addend used in +.Fn drand48 , +.Fn erand48 , +.Fn lrand48 , +.Fn nrand48 , +.Fn mrand48 , +and +.Fn jrand48 , +and the seed used in +.Fn drand48 , +.Fn lrand48 , +and +.Fn mrand48 . +An array of 7 unsigned shorts is passed as parameter; the first three shorts are +used to initialize the seed; the second three are used to initialize the +multiplicand; and the last short is used to initialize the addend. +It is thus not possible to use values greater than 0xffff as the addend. +.Pp +Note that all three methods of seeding the random number generator +always also set the multiplicand and addend for any of the six +generator calls. +.Pp +For a more powerful random number generator, see +.Xr random 3 . +.Sh SEE ALSO +.Xr rand 3 , +.Xr random 3 +.Sh AUTHORS +Martin Birgmeier diff --git a/static/netbsd/man3/random.3 b/static/netbsd/man3/random.3 new file mode 100644 index 00000000..92572e0b --- /dev/null +++ b/static/netbsd/man3/random.3 @@ -0,0 +1,191 @@ +.\" $NetBSD: random.3,v 1.24 2025/11/25 16:16:26 jschauma Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)random.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 12, 2014 +.Dt RANDOM 3 +.Os +.Sh NAME +.Nm random , +.Nm srandom , +.Nm initstate , +.Nm setstate +.Nd better random number generator; routines for changing generators +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft long +.Fn random void +.Ft void +.Fn srandom "unsigned int seed" +.Ft char * +.Fn initstate "unsigned int seed" "char *state" "size_t n" +.Ft char * +.Fn setstate "char *state" +.Sh DESCRIPTION +The +.Fn random +function +uses a non-linear additive feedback random number generator employing a +default table of size 31 long integers to return successive pseudo-random +numbers in the range from 0 to +.if t 2\u\s731\s10\d\(mi1. +.if n (2**31)\(mi1. +The period of this random number generator is very large, approximately +.if t 16\(mu(2\u\s731\s10\d\(mi1). +.if n 16*((2**31)\(mi1). +The maximum value +.Dv RANDOM_MAX +is defined in +.In stdlib.h . +.Pp +The +.Fn random +and +.Fn srandom +have (almost) the same calling sequence and initialization properties as +.Xr rand 3 +and +.Xr srand 3 . +The difference is that +.Xr rand 3 +produces a much less random sequence \(em in fact, the low dozen bits +generated by +.Xr rand 3 +go through a cyclic pattern. +All the bits generated by +.Fn random +are usable. +For example, +.Sq Li random()&01 +will produce a random binary value. +.Pp +Like +.Xr rand 3 , +.Fn random +will by default produce a sequence of numbers that can be duplicated +by calling +.Fn srandom +with +.Ql 1 +as the seed. +.Pp +The +.Fn initstate +routine allows a state array, passed in as an argument, to be initialized +for future use. +The size of the state array (in bytes) is used by +.Fn initstate +to decide how sophisticated a random number generator it should use \(em the +more state, the better the random numbers will be. +(Current "optimal" values for the amount of state information are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. +Using fewer than 8 bytes will cause an error). +The seed for the initialization (which specifies a starting point for +the random number sequence, and provides for restarting at the same +point) is also an argument. +The state array passed to +.Fn initstate +must be aligned to a 32-bit boundary. +This can be achieved by using +a suitably-sized array of ints, and casting the array to char * when +passing it to +.Fn initstate . +The +.Fn initstate +function +returns a pointer to the previous state information array. +.Pp +Once a state has been initialized, the +.Fn setstate +routine provides for rapid switching between states. +The +.Fn setstate +function +returns a pointer to the previous state array; its +argument state array is used for further random number generation +until the next call to +.Fn initstate +or +.Fn setstate . +.Pp +Once a state array has been initialized, it may be restarted at a +different point either by calling +.Fn initstate +(with the desired seed, the state array, and its size) or by calling +both +.Fn setstate +(with the state array) and +.Fn srandom +(with the desired seed). +The advantage of calling both +.Fn setstate +and +.Fn srandom +is that the size of the state array does not have to be remembered after +it is initialized. +.Pp +With 256 bytes of state information, the period of the random number +generator is greater than +.if t 2\u\s769\s10\d, +.if n 2**69 +which should be sufficient for most purposes. +.Sh RETURN VALUES +If +.Fn initstate +is called with fewer than 8 bytes of state information, or if +.Fn setstate +detects that the state information has been garbled, error +messages are printed on the standard error output. +.Sh SEE ALSO +.Xr rand 3 , +.Xr srand 3 , +.Xr rnd 4 , +.Xr rnd 9 +.Sh STANDARDS +The +.Fn random , +.Fn srandom , +.Fn initstate +and +.Fn setstate +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +These +functions appeared in +.Bx 4.2 . +.Sh AUTHORS +.An Earl T. Cohen +.Sh BUGS +About 2/3 the speed of +.Xr rand 3 . diff --git a/static/netbsd/man3/randomid.3 b/static/netbsd/man3/randomid.3 new file mode 100644 index 00000000..8c885b5e --- /dev/null +++ b/static/netbsd/man3/randomid.3 @@ -0,0 +1,148 @@ +.\" $NetBSD: randomid.3,v 1.9 2017/10/24 19:07:12 abhinav Exp $ +.\" +.\" Copyright (C) 2006 The NetBSD Foundation +.\" All rights reserved. +.\" +.\" Copyright (C) 2003 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 5, 2006 +.Dt RANDOMID 3 +.Os +.Sh NAME +.Nm randomid , +.Nm randomid_new , +.Nm randomid_delete +.Nd provide pseudo-random data stream without repetitions +.Sh SYNOPSIS +.In sys/types.h +.In randomid.h +.Ft uint32_t +.Fn randomid "randomid_t ctx" +.Ft randomid_t +.Fn randomid_new "int bits" "long timeo" +.Ft void +.Fn randomid_delete "randomid_t ctx" +.Sh DESCRIPTION +The +.Fn randomid +function provides pseudo-random data stream, +which is guaranteed not to generate the same number twice during +a certain duration. +.Fa ctx +is the context which holds internal state for the random number generator. +.Pp +To initialize a context, +.Fa randomid_new +is used. +.Fa bits +specifies the bitwidth of the value generated by +.Fn randomid . +Currently 32, 20, and 16 are supported. +.Fa timeo +specifies the reinitialization interval in seconds. +.Fa timeo +has to be bigger than +.Dv RANDOMID_TIMEO_MIN . +.Fa randomid_new +returns a dynamically-allocated memory region allocated by +.Xr malloc 3 . +.Pp +.Fn randomid_delete +will +.Xr free 3 +the internal state +.Fa ctx . +.Pp +The same number may appear after two reinitialization events of the internal state, +.Fa ctx . +Reinitialization happens when the random number generator cycle is exhausted, +or +.Fa timeo +seconds have passed since the last reinitialization. +For instance, +.Fa ctx +configured to generate 16 bit data stream will reinitialize its internal state +every 30000 calls to +.Fn randomid +.Po +or after +.Fa timeo +seconds +.Pc , +therefore the same data will not appear until after 30000 calls to +.Fn randomid +.Po +or after +.Fa timeo +seconds +.Pc . +.Pp +The internal state, +.Fa ctx , +determines the data stream generated by +.Fn randomid . +.Fa ctx +must be allocated per data stream +.Pq such as a specific data field . +It must not be shared among multiple data streams with different usage. +.\" +.Sh EXAMPLES +.Bd -literal -offset indent +#include <stdio.h> +#include <sys/types.h> +#include <randomid.h> + +uint32_t +genid(void) +{ + static randomid_t ctx = NULL; + + if (!ctx) + ctx = randomid_new(16, (long)3600); + return randomid(ctx); +} +.Ed +.\" +.Sh ERRORS +.Fn randomid_new +returns +.Dv NULL +on error and sets the external variable +.Va errno . +.\" +.Sh SEE ALSO +.Xr arc4random 3 +.\" +.Sh HISTORY +The pseudo-random data stream generator was designed by Niels Provos for +.Ox +IPv4 fragment ID generation. +.Fn randomid +is a generalized version of the generator, reworked by Jun-ichiro itojun Hagino, +and was introduced in +.Nx 2.0 . diff --git a/static/netbsd/man3/rcmd.3 b/static/netbsd/man3/rcmd.3 new file mode 100644 index 00000000..70ad7d9d --- /dev/null +++ b/static/netbsd/man3/rcmd.3 @@ -0,0 +1,311 @@ +.\" $NetBSD: rcmd.3,v 1.30 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd March 30, 2005 +.Dt RCMD 3 +.Os +.Sh NAME +.Nm rcmd , +.Nm orcmd , +.Nm rcmd_af , +.Nm orcmd_af , +.Nm rresvport , +.Nm rresvport_af , +.Nm iruserok , +.Nm ruserok , +.Nm iruserok_sa +.Nd routines for returning a stream to a remote command +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" +.Ft int +.Fn orcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" +.Ft int +.Fn rcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" +.Ft int +.Fn orcmd_af "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" "int af" +.Ft int +.Fn rresvport "int *port" +.Ft int +.Fn rresvport_af "int *port" "int family" +.Ft int +.Fn iruserok "uint32_t raddr" "int superuser" "const char *ruser" "const char *luser" +.Ft int +.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" +.Ft int +.Fn iruserok_sa "const void *raddr" "int rlen" "int superuser" "const char *ruser" "const char *luser" +.Sh DESCRIPTION +The +.Fn rcmd +function is available for use by anyone to run commands on a +remote system. It acts like the +.Fn orcmd +command, with the exception that it makes a call out to the +.Xr rcmd 1 +command, or any other user-specified command, to perform the +actual connection (thus not requiring +that the caller be running as the super-user), and is only +available for the +.Dq shell/tcp +port. +The +.Fn orcmd +function +is used by the super-user to execute a command on +a remote machine using an authentication scheme based +on reserved port numbers. +While +.Fn rcmd +and +.Fn orcmd +can only handle IPv4 address in the first argument, +.Fn rcmd_af +and +.Fn orcmd_af +can handle other cases as well. +The +.Fn rresvport +function +returns a descriptor to a socket +with an address in the privileged port space. +The +.Fn rresvport_af +function is similar to +.Fn rresvport , +but you can explicitly specify the address family to use. +Calling +.Fn rresvport_af +with +.Dv AF_INET +has the same effect as +.Fn rresvport . +The +.Fn iruserok +and +.Fn ruserok +functions are used by servers +to authenticate clients requesting service with +.Fn rcmd . +All six functions are present in the same file and are used +by the +.Xr rshd 8 +server (among others). +.Fn iruserok_sa +is an address family independent variant of +.Fn iruserok . +.Pp +The +.Fn rcmd +function +looks up the host +.Fa *ahost +using +.Xr gethostbyname 3 , +returning \-1 if the host does not exist. +Otherwise +.Fa *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.Fa inport . +.Pp +If the connection succeeds, +a socket in the Internet domain of type +.Dv SOCK_STREAM +is returned to the caller, and given to the remote +command as +.Em stdin +and +.Em stdout . +If +.Fa fd2p +is non-zero, then an auxiliary channel to a control +process will be set up, and a descriptor for it will be placed +in +.Fa *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being +.Ux +signal numbers, to be +forwarded to the process group of the command. +If +.Fa fd2p +is 0, then the +.Em stderr +(unit 2 of the remote +command) will be made the same as the +.Em stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.Pp +.Fn rcmd_af +and +.Fn orcmd_af +take address family in the last argument. +If the last argument is +.Dv PF_UNSPEC , +interpretation of +.Fa *ahost +will obey the underlying address resolution like DNS. +.Pp +The protocol is described in detail in +.Xr rshd 8 . +.Pp +The +.Fn rresvport +and +.Fn rresvport_af +functions are used to obtain a socket with a privileged +address bound to it. This socket is suitable for use +by +.Fn rcmd +and several other functions. Privileged Internet ports are those +in the range 0 to 1023. Only the super-user +is allowed to bind an address of this sort to a socket. +.Pp +The +.Fn iruserok +and +.Fn ruserok +functions take a remote host's IP address or name, respectively, +two user names and a flag indicating whether the local user's +name is that of the super-user. +Then, if the user is +.Em NOT +the super-user, it checks the +.Pa /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.Pa .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.Pp +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the super-user, or is writable by anyone other +than the owner, the check automatically fails. +Zero is returned if the machine name is listed in the +.Dq Pa hosts.equiv +file, or the host and remote user name are found in the +.Dq Pa .rhosts +file; otherwise +.Fn iruserok +and +.Fn ruserok +return \-1. +If the local domain (as obtained from +.Xr gethostname 3 ) +is the same as the remote domain, only the machine name need be specified. +.Pp +If the IP address of the remote host is known, +.Fn iruserok +should be used in preference to +.Fn ruserok , +as it does not require trusting the DNS server for the remote host's domain. +.Pp +While +.Fn iruserok +can handle IPv4 addresses only, +.Fn iruserok_sa +and +.Fn ruserok +can handle other address families as well, like IPv6. +The first argument of +.Fn iruserok_sa +is typed as +.Fa "void *" +to avoid dependency between +.In unistd.h +and +.In sys/socket.h . +.Sh ENVIRONMENT +.Bl -tag -width RCMD_CMDxx -compact +.It Ev RCMD_CMD +When using the +.Fn rcmd +function, this variable is used as the program to run instead of +.Xr rcmd 1 . +.El +.Sh RETURN VALUES +The +.Fn rcmd +function +returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.Pp +The +.Fn rresvport +and +.Fn rresvport_af +function +return a valid, bound socket descriptor on success. +They return \-1 on error with the global value +.Va errno +set according to the reason for failure. +The error code +.Er EAGAIN +is overloaded to mean ``All network ports in use.'' +.Sh SEE ALSO +.Xr rcmd 1 , +.Xr rlogin 1 , +.Xr rsh 1 , +.Xr intro 2 , +.Xr rexec 3 , +.Xr hosts.equiv 5 , +.Xr rhosts 5 , +.Xr rexecd 8 , +.Xr rlogind 8 , +.Xr rshd 8 +.Sh HISTORY +The +.Fn orcmd , +.Fn rresvport , +.Fn iruserok +and +.Fn ruserok +functions appeared in +.Bx 4.2 , +where the +.Fn orcmd +function was called +.Fn rcmd . +The (newer) +.Fn rcmd +function appeared in +.Nx 1.3 . +.Fn rcmd_af +and +.Fn rresvport_af +were defined in RFC2292. diff --git a/static/netbsd/man3/re_comp.3 b/static/netbsd/man3/re_comp.3 new file mode 100644 index 00000000..e895bdce --- /dev/null +++ b/static/netbsd/man3/re_comp.3 @@ -0,0 +1,127 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)re_comp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: re_comp.3,v 1.13 2022/12/04 01:29:32 uwe Exp $ +.\" +.Dd June 4, 1993 +.Dt RE_COMP 3 +.Os +.Sh NAME +.Nm re_comp , +.Nm re_exec +.Nd regular expression handler +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.In re_comp.h +.Ft char * +.Fn re_comp "const char *s" +.Ft int +.Fn re_exec "const char *s" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr regex 3 . +It is available from the compatibility library, libcompat. +.Ef +.Pp +The +.Fn re_comp +function +compiles a string into an internal form suitable for pattern matching. +The +.Fn re_exec +function +checks the argument string against the last string passed to +.Fn re_comp . +.Pp +The +.Fn re_comp +function +returns 0 if the string +.Fa s +was compiled successfully; otherwise a string containing an +error message is returned. +If +.Fn re_comp +is passed 0 or a null string, it returns without changing the currently +compiled regular expression. +.Pp +The +.Fn re_exec +function +returns 1 if the string +.Fa s +matches the last compiled regular expression, 0 if the string +.Fa s +failed to match the last compiled regular expression, and \-1 if the compiled +regular expression was invalid (indicating an internal error). +.Pp +The strings passed to both +.Fn re_comp +and +.Fn re_exec +may have trailing or embedded newline characters; +they are terminated by +.Dv NUL Ns s . +The regular expressions recognized are described in the manual entry for +.Xr ed 1 , +given the above difference. +.Sh RETURN VALUES +The +.Fn re_exec +function +returns \-1 for an internal error. +.Pp +The +.Fn re_comp +function +returns one of the following strings if an error occurs: +.Bd -unfilled -offset indent +No previous regular expression, +Regular expression too long, +unmatched \e(, +missing ], +too many \e(\e) pairs, +unmatched \e). +.Ed +.Sh SEE ALSO +.Xr ed 1 , +.Xr egrep 1 , +.Xr ex 1 , +.Xr fgrep 1 , +.Xr grep 1 , +.Xr regex 3 , +.Xr re_format 7 +.Sh HISTORY +The +.Fn re_comp +and +.Fn re_exec +functions appeared in +.Bx 4.0 . diff --git a/static/netbsd/man3/readline.3 b/static/netbsd/man3/readline.3 new file mode 100644 index 00000000..77ef02a6 --- /dev/null +++ b/static/netbsd/man3/readline.3 @@ -0,0 +1,1597 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Information Network Services +.\" Case Western Reserve University +.\" chet.ramey@case.edu +.\" +.\" Last Change: Mon Sep 19 11:11:22 EDT 2022 +.\" +.TH READLINE 3 "2022 September 19" "GNU Readline 8.2" +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.SH NAME +readline \- get a line from a user with editing +.SH SYNOPSIS +.LP +.nf +.ft B +#include <stdio.h> +#include <readline/readline.h> +#include <readline/history.h> +.ft +.fi +.LP +.nf +\fIchar *\fP +.br +\fBreadline\fP (\fIconst char *prompt\fP); +.fi +.SH COPYRIGHT +.if n Readline is Copyright (C) 1989\-2020 Free Software Foundation, Inc. +.if t Readline is Copyright \(co 1989\-2020 Free Software Foundation, Inc. +.SH DESCRIPTION +.LP +.B readline +will read a line from the terminal +and return it, using +.B prompt +as a prompt. If +.B prompt +is \fBNULL\fP or the empty string, no prompt is issued. +The line returned is allocated with +.IR malloc (3); +the caller must free it when finished. The line returned +has the final newline removed, so only the text of the line +remains. +.LP +.B readline +offers editing capabilities while the user is entering the +line. +By default, the line editing commands +are similar to those of emacs. +A vi\-style line editing interface is also available. +.LP +This manual page describes only the most basic use of \fBreadline\fP. +Much more functionality is available; see +\fIThe GNU Readline Library\fP and \fIThe GNU History Library\fP +for additional information. +.SH RETURN VALUE +.LP +.B readline +returns the text of the line read. A blank line +returns the empty string. If +.B EOF +is encountered while reading a line, and the line is empty, +.B NULL +is returned. If an +.B EOF +is read with a non\-empty line, it is +treated as a newline. +.SH NOTATION +.LP +An Emacs-style notation is used to denote +keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n +means Control\-N. Similarly, +.I meta +keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards +without a +.I meta +key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key +then the +.I x +key. This makes ESC the \fImeta prefix\fP. +The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, +or press the Escape key +then hold the Control key while pressing the +.I x +key.) +.PP +Readline commands may be given numeric +.IR arguments , +which normally act as a repeat count. Sometimes, however, it is the +sign of the argument that is significant. Passing a negative argument +to a command that acts in the forward direction (e.g., \fBkill\-line\fP) +causes that command to act in a backward direction. +Commands whose behavior with arguments deviates from this are noted +below. +.PP +When a command is described as \fIkilling\fP text, the text +deleted is saved for possible future retrieval +(\fIyanking\fP). The killed text is saved in a +\fIkill ring\fP. Consecutive kills cause the text to be +accumulated into one unit, which can be yanked all at once. +Commands which do not kill text separate the chunks of text +on the kill ring. +.SH INITIALIZATION FILE +.LP +Readline is customized by putting commands in an initialization +file (the \fIinputrc\fP file). +The name of this file is taken from the value of the +.B INPUTRC +environment variable. If that variable is unset, the default is +.IR ~/.inputrc . +If that file does not exist or cannot be read, the ultimate default is +.IR /etc/inputrc . +When a program which uses the readline library starts up, the +init file is read, and the key bindings and variables are set. +There are only a few basic constructs allowed in the +readline init file. Blank lines are ignored. +Lines beginning with a \fB#\fP are comments. +Lines beginning with a \fB$\fP indicate conditional constructs. +Other lines denote key bindings and variable settings. +Each program using this library may add its own commands +and bindings. +.PP +For example, placing +.RS +.PP +M\-Control\-u: universal\-argument +.RE +or +.RS +C\-Meta\-u: universal\-argument +.RE +.sp +into the +.I inputrc +would make M\-C\-u execute the readline command +.IR universal\-argument . +.PP +The following symbolic character names are recognized while +processing key bindings: +.IR DEL , +.IR ESC , +.IR ESCAPE , +.IR LFD , +.IR NEWLINE , +.IR RET , +.IR RETURN , +.IR RUBOUT , +.IR SPACE , +.IR SPC , +and +.IR TAB . +.PP +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a \fImacro\fP). +.PP +.SS Key Bindings +The syntax for controlling key bindings in the +.I inputrc +file is simple. All that is required is the name of the +command or the text of a macro and a key sequence to which +it should be bound. The name may be specified in one of two ways: +as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP +prefixes, or as a key sequence. +The name and key sequence are separated by a colon. There can be no +whitespace between the name and the colon. +.PP +When using the form \fBkeyname\fP:\^\fIfunction-name\fP or \fImacro\fP, +.I keyname +is the name of a key spelled out in English. For example: +.sp +.RS +Control\-u: universal\-argument +.br +Meta\-Rubout: backward\-kill\-word +.br +Control\-o: "> output" +.RE +.LP +In the above example, +.I C\-u +is bound to the function +.BR universal\-argument , +.I M-DEL +is bound to the function +.BR backward\-kill\-word , +and +.I C\-o +is bound to run the macro +expressed on the right hand side (that is, to insert the text +.if t \f(CW> output\fP +.if n ``> output'' +into the line). +.PP +In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP, +.B keyseq +differs from +.B keyname +above in that strings denoting +an entire key sequence may be specified by placing the sequence +within double quotes. Some GNU Emacs style key escapes can be +used, as in the following example, but the symbolic character names +are not recognized. +.sp +.RS +"\eC\-u": universal\-argument +.br +"\eC\-x\eC\-r": re\-read\-init\-file +.br +"\ee[11~": "Function Key 1" +.RE +.PP +In this example, +.I C-u +is again bound to the function +.BR universal\-argument . +.I "C-x C-r" +is bound to the function +.BR re\-read\-init\-file , +and +.I "ESC [ 1 1 ~" +is bound to insert the text +.if t \f(CWFunction Key 1\fP. +.if n ``Function Key 1''. +.PP +The full set of GNU Emacs style escape sequences available when specifying +key sequences is +.RS +.PD 0 +.TP +.B \eC\- +control prefix +.TP +.B \eM\- +meta prefix +.TP +.B \ee +an escape character +.TP +.B \e\e +backslash +.TP +.B \e" +literal ", a double quote +.TP +.B \e' +literal ', a single quote +.RE +.PD +.PP +In addition to the GNU Emacs style escape sequences, a second +set of backslash escapes is available: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ed +delete +.TP +.B \ef +form feed +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.RE +.PD +.PP +When entering the text of a macro, single or double quotes should +be used to indicate a macro definition. Unquoted text +is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including " and '. +.PP +.B Bash +allows the current readline key bindings to be displayed or modified +with the +.B bind +builtin command. The editing mode may be switched during interactive +use by using the +.B \-o +option to the +.B set +builtin command. Other programs using this library provide +similar mechanisms. The +.I inputrc +file may be edited and re-read if a program does not provide +any other means to incorporate new bindings. +.SS Variables +Readline has variables that can be used to further customize its +behavior. A variable may be set in the +.I inputrc +file with a statement of the form +.RS +.PP +\fBset\fP \fIvariable\-name\fP \fIvalue\fP +.RE +.PP +Except where noted, readline variables can take the values +.B On +or +.B Off +(without regard to case). +Unrecognized variable names are ignored. +When a variable value is read, empty or null values, "on" (case-insensitive), +and "1" are equivalent to \fBOn\fP. All other values are equivalent to +\fBOff\fP. +The variables and their default values are: +.PP +.PD 0 +.TP +.B active\-region\-start\-color +A string variable that controls the text color and background when displaying +the text in the active region (see the description of +\fBenable\-active\-region\fP below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[01;33m"\fP. +.TP +.B active\-region\-end\-color +A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[0m\fP". +.TP +.B bell\-style (audible) +Controls what happens when readline wants to ring the terminal bell. +If set to \fBnone\fP, readline never rings the bell. If set to +\fBvisible\fP, readline uses a visible bell if one is available. +If set to \fBaudible\fP, readline attempts to ring the terminal's bell. +.TP +.B bind\-tty\-special\-chars (On) +If set to \fBOn\fP (the default), readline attempts to bind the control +characters treated specially by the kernel's terminal driver to their +readline equivalents. +.TP +.B blink\-matching\-paren (Off) +If set to \fBOn\fP, readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. +.TP +.B colored\-completion\-prefix (Off) +If set to \fBOn\fP, when listing completions, readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +If there is a color definition in \fB$LS_COLORS\fP for the custom suffix +"readline-colored-completion-prefix", readline uses this color for +the common prefix instead of its default. +.TP +.B colored\-stats (Off) +If set to \fBOn\fP, readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +.TP +.B comment\-begin (``#'') +The string that is inserted in \fBvi\fP mode when the +.B insert\-comment +command is executed. +This command is bound to +.B M\-# +in emacs mode and to +.B # +in vi command mode. +.TP +.B completion\-display\-width (\-1) +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is \-1. +.TP +.B completion\-ignore\-case (Off) +If set to \fBOn\fP, readline performs filename matching and completion +in a case\-insensitive fashion. +.TP +.B completion\-map\-case (Off) +If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline +treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when +performing case\-insensitive filename matching and completion. +.TP +.B completion\-prefix\-display\-length (0) +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. +.TP +.B completion\-query\-items (100) +This determines when the user is queried about viewing +the number of possible completions +generated by the \fBpossible\-completions\fP command. +It may be set to any integer value greater than or equal to zero. +If the number of possible completions is greater than +or equal to the value of this variable, +readline will ask whether or not the user wishes to view them; +otherwise they are simply listed +on the terminal. +A negative value causes readline to never ask. +.TP +.B convert\-meta (On) +If set to \fBOn\fP, readline will convert characters with the +eighth bit set to an ASCII key sequence +by stripping the eighth bit and prefixing it with an +escape character (in effect, using escape as the \fImeta prefix\fP). +The default is \fIOn\fP, but readline will set it to \fIOff\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B disable\-completion (Off) +If set to \fBOn\fP, readline will inhibit word completion. Completion +characters will be inserted into the line as if they had been +mapped to \fBself-insert\fP. +.TP +.B echo\-control\-characters (On) +When set to \fBOn\fP, on operating systems that indicate they support it, +readline echoes a character corresponding to a signal generated from the +keyboard. +.TP +.B editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to \fIEmacs\fP or \fIvi\fP. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.TP +.B emacs\-mode\-string (@) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B enable\-active\-region (On) +The \fIpoint\fP is the current cursor position, and \fImark\fP refers +to a saved cursor position. +The text between the point and mark is referred to as the \fIregion\fP. +When this variable is set to \fIOn\fP, readline allows certain commands +to designate the region as \fIactive\fP. +When the region is active, readline highlights the text in the region using +the value of the \fBactive\-region\-start\-color\fP, which defaults to the +string that enables +the terminal's standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +.TP +.B enable\-bracketed\-paste (On) +When set to \fBOn\fP, readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This prevents readline from executing any editing commands bound to key +sequences appearing in the pasted text. +.TP +.B enable\-keypad (Off) +When set to \fBOn\fP, readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. +.TP +.B enable\-meta\-key (On) +When set to \fBOn\fP, readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +.TP +.B expand\-tilde (Off) +If set to \fBOn\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B history\-preserve\-point (Off) +If set to \fBOn\fP, the history code attempts to place point at the +same location on each history line retrieved with \fBprevious-history\fP +or \fBnext-history\fP. +.TP +.B history\-size (unset) +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is not limited. +If an attempt is made to set \fIhistory\-size\fP to a non-numeric value, +the maximum number of history entries will be set to 500. +.TP +.B horizontal\-scroll\-mode (Off) +When set to \fBOn\fP, makes readline use a single line for display, +scrolling the input horizontally on a single screen line when it +becomes longer than the screen width rather than wrapping to a new line. +This setting is automatically enabled for terminals of height 1. +.TP +.B input\-meta (Off) +If set to \fBOn\fP, readline will enable eight-bit input (that is, +it will not clear the eighth bit in the characters it reads), +regardless of what the terminal claims it can support. The name +.B meta\-flag +is a synonym for this variable. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B isearch\-terminators (``C\-[ C\-J'') +The string of characters that should terminate an incremental +search without subsequently executing the character as a command. +If this variable has not been given a value, the characters +\fIESC\fP and \fIC\-J\fP will terminate an incremental search. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of legal keymap names is +\fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, +vi-command\fP, and +.IR vi-insert . +\fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is +equivalent to \fIemacs-standard\fP. The default value is +.IR emacs . +The value of +.B editing\-mode +also affects the default keymap. +.TP +.B keyseq\-timeout (500) +Specifies the duration \fIreadline\fP will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, \fIreadline\fP will use the shorter +but complete key sequence. +The value is specified in milliseconds, so a value of 1000 means that +\fIreadline\fP will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, \fIreadline\fP will wait until another key is pressed to +decide which key sequence to complete. +.TP +.B mark\-directories (On) +If set to \fBOn\fP, completed directory names have a slash +appended. +.TP +.B mark\-modified\-lines (Off) +If set to \fBOn\fP, history lines that have been modified are displayed +with a preceding asterisk (\fB*\fP). +.TP +.B mark\-symlinked\-directories (Off) +If set to \fBOn\fP, completed names which are symbolic links to directories +have a slash appended (subject to the value of +\fBmark\-directories\fP). +.TP +.B match\-hidden\-files (On) +This variable, when set to \fBOn\fP, causes readline to match files whose +names begin with a `.' (hidden files) when performing filename +completion. +If set to \fBOff\fP, the leading `.' must be +supplied by the user in the filename to be completed. +.TP +.B menu\-complete\-display\-prefix (Off) +If set to \fBOn\fP, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. +.TP +.B output\-meta (Off) +If set to \fBOn\fP, readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B page\-completions (On) +If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager +to display a screenful of possible completions at a time. +.TP +.B print\-completions\-horizontally (Off) +If set to \fBOn\fP, readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +.TP +.B revert\-all\-at\-newline (Off) +If set to \fBOn\fP, readline will undo all changes to history lines +before returning when \fBaccept\-line\fP is executed. By default, +history lines may be modified and retain individual undo lists across +calls to \fBreadline\fP. +.TP +.B show\-all\-if\-ambiguous (Off) +This alters the default behavior of the completion functions. If +set to +.BR On , +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +.TP +.B show\-all\-if\-unmodified (Off) +This alters the default behavior of the completion functions in +a fashion similar to \fBshow\-all\-if\-ambiguous\fP. +If set to +.BR On , +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +.TP +.B show\-mode\-in\-prompt (Off) +If set to \fBOn\fP, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP). +.TP +.B skip\-completed\-text (Off) +If set to \fBOn\fP, this alters the default completion behavior when +inserting a single match into the line. It's only active when +performing completion in the middle of a word. If enabled, readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +.TP +.B vi\-cmd\-mode\-string ((cmd)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B vi\-ins\-mode\-string ((ins)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B visible\-stats (Off) +If set to \fBOn\fP, a character denoting a file's type as reported +by \fIstat\fP(2) is appended to the filename when listing possible +completions. +.PD +.SS Conditional Constructs +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. +.IP \fB$if\fP +The +.B $if +construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. +.RS +.IP \fBmode\fP +The \fBmode=\fP form of the \fB$if\fP directive is used to test +whether readline is in emacs or vi mode. +This may be used in conjunction +with the \fBset keymap\fP command, for instance, to set bindings in +the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if +readline is starting out in emacs mode. +.IP \fBterm\fP +The \fBterm=\fP form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +.B = +is tested against the full name of the terminal and the portion +of the terminal name before the first \fB\-\fP. This allows +.I sun +to match both +.I sun +and +.IR sun\-cmd , +for instance. +.IP \fBversion\fP +The \fBversion\fP test may be used to perform comparisons against +specific readline versions. +The \fBversion\fP expands to the current readline version. +The set of comparison operators includes +.BR = , +(and +.BR == ), +.BR != , +.BR <= , +.BR >= , +.BR < , +and +.BR > . +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., \fB7.1\fP). If the minor version is omitted, it +is assumed to be \fB0\fP. +The operator may be separated from the string \fBversion\fP +and from the version number argument by whitespace. +.IP \fBapplication\fP +The \fBapplication\fP construct is used to include +application-specific settings. Each program using the readline +library sets the \fIapplication name\fP, and an initialization +file can test for a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in \fBbash\fP: +.sp 1 +.RS +.nf +\fB$if\fP Bash +# Quote the current or previous word +"\eC-xq": "\eeb\e"\eef\e"" +\fB$endif\fP +.fi +.RE +.IP \fIvariable\fP +The \fIvariable\fP construct provides simple equality tests for readline +variables and values. +The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values \fIon\fP and \fIoff\fP. +.RE +.IP \fB$endif\fP +This command, as seen in the previous example, terminates an +\fB$if\fP command. +.IP \fB$else\fP +Commands in this branch of the \fB$if\fP directive are executed if +the test fails. +.IP \fB$include\fP +This directive takes a single filename as an argument and reads commands +and bindings from that file. For example, the following directive +would read \fI/etc/inputrc\fP: +.sp 1 +.RS +.nf +\fB$include\fP \^ \fI/etc/inputrc\fP +.fi +.RE +.SH SEARCHING +Readline provides commands for searching through the command history +for lines containing a specified string. +There are two search modes: +.I incremental +and +.IR non-incremental . +.PP +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +To search backward in the history for a particular string, type +\fBC\-r\fP. Typing \fBC\-s\fP searches forward through the history. +The characters present in the value of the \fBisearch-terminators\fP +variable are used to terminate an incremental search. +If that variable has not been assigned a value the \fIEscape\fP and +\fBC\-J\fP characters will terminate an incremental search. +\fBC\-G\fP will abort an incremental search and restore the original +line. +When the search is terminated, the history entry containing the +search string becomes the current line. +.PP +To find other matching entries in the history list, type \fBC\-s\fP or +\fBC\-r\fP as appropriate. +This will search backward or forward in the history for the next +line matching the search string typed so far. +Any other key sequence bound to a readline command will terminate +the search and execute that command. +For instance, a newline will terminate the search and accept +the line, thereby executing the command from the history list. +A movement command will terminate the search, make the last line found +the current line, and begin editing. +.PP +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. +.SH EDITING COMMANDS +The following is a list of the names of the commands and the default +key sequences to which they are bound. +Command names without an accompanying key sequence are unbound by default. +.PP +In the following descriptions, \fIpoint\fP refers to the current cursor +position, and \fImark\fP refers to a cursor position saved by the +\fBset\-mark\fP command. +The text between the point and mark is referred to as the \fIregion\fP. +.SS Commands for Moving +.PD 0 +.TP +.B beginning\-of\-line (C\-a) +Move to the start of the current line. +.TP +.B end\-of\-line (C\-e) +Move to the end of the line. +.TP +.B forward\-char (C\-f) +Move forward a character. +.TP +.B backward\-char (C\-b) +Move back a character. +.TP +.B forward\-word (M\-f) +Move forward to the end of the next word. Words are composed of +alphanumeric characters (letters and digits). +.TP +.B backward\-word (M\-b) +Move back to the start of the current or previous word. Words are +composed of alphanumeric characters (letters and digits). +.TP +.B previous\-screen\-line +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. +.TP +.B next\-screen\-line +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if the length +of the current readline line is not greater than the length of the prompt +plus the screen width. +.TP +.B clear\-display (M\-C\-l) +Clear the screen and, if possible, the terminal's scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. +.TP +.B clear\-screen (C\-l) +Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. +With an argument, refresh the current line without clearing the +screen. +.TP +.B redraw\-current\-line +Refresh the current line. +.PD +.SS Commands for Manipulating the History +.PD 0 +.TP +.B accept\-line (Newline, Return) +Accept the line regardless of where the cursor is. +If this line is +non-empty, it may be added to the history list for future recall with +\fBadd_history()\fP. +If the line is a modified history line, the history line is restored to its original state. +.TP +.B previous\-history (C\-p) +Fetch the previous command from the history list, moving back in +the list. +.TP +.B next\-history (C\-n) +Fetch the next command from the history list, moving forward in the +list. +.TP +.B beginning\-of\-history (M\-<) +Move to the first line in the history. +.TP +.B end\-of\-history (M\->) +Move to the end of the input history, i.e., the line currently being +entered. +.TP +.B +operate\-and\-get\-next (C\-o) +Accept the current line for return to the calling application as if a +newline had been entered, +and fetch the next line relative to the current line from the history +for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. +.TP +.B +fetch\-history +With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. +.TP +.B reverse\-search\-history (C\-r) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. +.TP +.B forward\-search\-history (C\-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +.TP +.B non\-incremental\-reverse\-search\-history (M\-p) +Search backward through the history starting at the current line +using a non-incremental search for a string supplied by the user. +.TP +.B non\-incremental\-forward\-search\-history (M\-n) +Search forward through the history using a non-incremental search +for a string supplied by the user. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +The search string must match at the beginning of a history line. +This is a non-incremental search. +.TP +.B history\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +.TP +.B history\-substring\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B history\-substring\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B yank\-nth\-arg (M\-C\-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument +.IR n , +insert the \fIn\fPth word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the \fIn\fPth word from the end of the previous command. +Once the argument \fIn\fP is computed, the argument is extracted +as if the "!\fIn\fP" history expansion had been specified. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). +With a numeric argument, behave exactly like \fByank\-nth\-arg\fP. +Successive calls to \fByank\-last\-arg\fP move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last argument, +as if the "!$" history expansion had been specified. +.PD +.SS Commands for Changing Text +.PD 0 +.TP +.B \fIend\-of\-file\fP (usually C\-d) +The character indicating end-of-file as set, for example, by +.if t \f(CWstty\fP. +.if n ``stty''. +If this character is read when there are no characters +on the line, and point is at the beginning of the line, readline +interprets it as the end of input and returns +.SM +.BR EOF . +.TP +.B delete\-char (C\-d) +Delete the character at point. +If this function is bound to the +same character as the tty \fBEOF\fP character, as \fBC\-d\fP +commonly is, see above for the effects. +.TP +.B backward\-delete\-char (Rubout) +Delete the character behind the cursor. When given a numeric argument, +save the deleted text on the kill ring. +.TP +.B forward\-backward\-delete\-char +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character that you type to the line verbatim. This is +how to insert characters like \fBC\-q\fP, for example. +.TP +.B tab\-insert (M-TAB) +Insert a tab character. +.TP +.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) +Insert the character typed. +.TP +.B transpose\-chars (C\-t) +Drag the character before point forward over the character at point, +moving point forward as well. +If point is at the end of the line, then this transposes +the two characters before point. +Negative arguments have no effect. +.TP +.B transpose\-words (M\-t) +Drag the word before point past the word after point, +moving point over that word as well. +If point is at the end of the line, this transposes +the last two words on the line. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move point. +.TP +.B overwrite\-mode +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +\fBemacs\fP mode; \fBvi\fP mode does overwrite differently. +Each call to \fIreadline()\fP starts in insert mode. +In overwrite mode, characters bound to \fBself\-insert\fP replace +the text at point rather than pushing the text to the right. +Characters bound to \fBbackward\-delete\-char\fP replace the character +before point with a space. By default, this command is unbound. +.PD +.SS Killing and Yanking +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from point to the end of the line. +.TP +.B backward\-kill\-line (C\-x Rubout) +Kill backward to the beginning of the line. +.TP +.B unix\-line\-discard (C\-u) +Kill backward from point to the beginning of the line. +The killed text is saved on the kill-ring. +.\" There is no real difference between this and backward-kill-line +.TP +.B kill\-whole\-line +Kill all characters on the current line, no matter where point is. +.TP +.B kill\-word (M\-d) +Kill from point the end of the current word, or if between +words, to the end of the next word. Word boundaries are the same as +those used by \fBforward\-word\fP. +.TP +.B backward\-kill\-word (M\-Rubout) +Kill the word behind point. +Word boundaries are the same as those used by \fBbackward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. +.TP +.B unix\-filename\-rubout +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text between the point and \fImark\fP (saved cursor position). +This text is referred to as the \fIregion\fP. +.TP +.B copy\-region\-as\-kill +Copy the text in the region to the kill buffer. +.TP +.B copy\-backward\-word +Copy the word before point to the kill buffer. +The word boundaries are the same as \fBbackward\-word\fP. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +The word boundaries are the same as \fBforward\-word\fP. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at point. +.TP +.B yank\-pop (M\-y) +Rotate the kill ring, and yank the new top. Only works following +.B yank +or +.BR yank\-pop . +.PD +.SS Numeric Arguments +.PD 0 +.TP +.B digit\-argument (M\-0, M\-1, ..., M\-\-) +Add this digit to the argument already accumulating, or start a new +argument. M\-\- starts a negative argument. +.TP +.B universal\-argument +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing +.B universal\-argument +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit or minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +.PD +.SS Completing +.PD 0 +.TP +.B complete (TAB) +Attempt to perform completion on the text before point. +The actual completion performed is application-specific. +.BR Bash , +for instance, attempts completion treating the text as a variable +(if the text begins with \fB$\fP), username (if the text begins with +\fB~\fP), hostname (if the text begins with \fB@\fP), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +.BR Gdb , +on the other hand, +allows completion of program functions and variables, and +only attempts filename completion under certain circumstances. +.TP +.B possible\-completions (M\-?) +List the possible completions of the text before point. +When displaying completions, readline sets the number of columns used +for display to the value of \fBcompletion-display-width\fP, the value of +the environment variable +.SM +.BR COLUMNS , +or the screen width, in that order. +.TP +.B insert\-completions (M\-*) +Insert all completions of the text before point +that would have been generated by +\fBpossible\-completions\fP. +.TP +.B menu\-complete +Similar to \fBcomplete\fP, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of \fBmenu\-complete\fP steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of \fBbell\-style\fP) +and the original text is restored. +An argument of \fIn\fP moves \fIn\fP positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to \fBTAB\fP, but is unbound +by default. +.TP +.B menu\-complete\-backward +Identical to \fBmenu\-complete\fP, but moves backward through the list +of possible completions, as if \fBmenu\-complete\fP had been given a +negative argument. This command is unbound by default. +.TP +.B delete\-char\-or\-list +Deletes the character under the cursor if not at the beginning or +end of the line (like \fBdelete-char\fP). +If at the end of the line, behaves identically to +\fBpossible-completions\fP. +.PD +.SS Keyboard Macros +.PD 0 +.TP +.B start\-kbd\-macro (C\-x (\^) +Begin saving the characters typed into the current keyboard macro. +.TP +.B end\-kbd\-macro (C\-x )\^) +Stop saving the characters typed into the current keyboard macro +and store the definition. +.TP +.B call\-last\-kbd\-macro (C\-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +.TP +.B print\-last\-kbd\-macro () +Print the last keyboard macro defined in a format suitable for the +\fIinputrc\fP file. +.PD +.SS Miscellaneous +.PD 0 +.TP +.B re\-read\-init\-file (C\-x C\-r) +Read in the contents of the \fIinputrc\fP file, and incorporate +any bindings or variable assignments found there. +.TP +.B abort (C\-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +.BR bell\-style ). +.TP +.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is uppercase, run the command +that is bound to the corresponding metafied lowercase character. +The behavior is undefined if \fIx\fP is already lowercase. +.TP +.B prefix\-meta (ESC) +Metafy the next character typed. +.SM +.B ESC +.B f +is equivalent to +.BR Meta\-f . +.TP +.B undo (C\-_, C\-x C\-u) +Incremental undo, separately remembered for each line. +.TP +.B revert\-line (M\-r) +Undo all changes made to this line. This is like executing the +.B undo +command enough times to return the line to its initial state. +.TP +.B tilde\-expand (M\-&) +Perform tilde expansion on the current word. +.TP +.B set\-mark (C\-@, M\-<space>) +Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. +.TP +.B exchange\-point\-and\-mark (C\-x C\-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +.TP +.B character\-search (C\-]) +A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. +.TP +.B character\-search\-backward (M\-C\-]) +A character is read and point is moved to the previous occurrence of that +character. A negative argument searches for subsequent occurrences. +.TP +.B skip\-csi\-sequence +Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC\-[. +.TP +.B insert\-comment (M\-#) +Without a numeric argument, the value of the readline +.B comment\-begin +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of \fBcomment\-begin\fP, the value is inserted, otherwise +the characters in \fBcomment-begin\fP are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +The default value of +.B comment\-begin +makes the current line a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +.TP +.B dump\-functions +Print all of the functions and their key bindings to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-variables +Print all of the settable variables and their values to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-macros +Print all of the readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B emacs\-editing\-mode (C\-e) +When in +.B vi +command mode, this causes a switch to +.B emacs +editing mode. +.TP +.B vi\-editing\-mode (M\-C\-j) +When in +.B emacs +editing mode, this causes a switch to +.B vi +editing mode. +.PD +.SH DEFAULT KEY BINDINGS +.LP +The following is a list of the default emacs and vi bindings. +Characters with the eighth bit set are written as M\-<character>, and +are referred to as +.I metafied +characters. +The printable ASCII characters not mentioned in the list of emacs +standard bindings are bound to the +.B self\-insert +function, which just inserts the given character into the input line. +In vi insertion mode, all characters not specifically mentioned are +bound to +.BR self\-insert . +Characters assigned to signal generation by +.IR stty (1) +or the terminal driver, such as C-Z or C-C, +retain that function. +Upper and lower case metafied characters are bound to the same function in +the emacs mode meta keymap. +The remaining characters are unbound, which causes readline +to ring the bell (subject to the setting of the +.B bell\-style +variable). +.SS Emacs Mode +.RS +.6i +.nf +.ta 2.5i +.sp +Emacs Standard bindings +.sp +"C-@" set-mark +"C-A" beginning-of-line +"C-B" backward-char +"C-D" delete-char +"C-E" end-of-line +"C-F" forward-char +"C-G" abort +"C-H" backward-delete-char +"C-I" complete +"C-J" accept-line +"C-K" kill-line +"C-L" clear-screen +"C-M" accept-line +"C-N" next-history +"C-P" previous-history +"C-Q" quoted-insert +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"C-]" character-search +"C-_" undo +"\^ " to "/" self-insert +"0" to "9" self-insert +":" to "~" self-insert +"C-?" backward-delete-char +.PP +Emacs Meta bindings +.sp +"M-C-G" abort +"M-C-H" backward-kill-word +"M-C-I" tab-insert +"M-C-J" vi-editing-mode +"M-C-L" clear-display +"M-C-M" vi-editing-mode +"M-C-R" revert-line +"M-C-Y" yank-nth-arg +"M-C-[" complete +"M-C-]" character-search-backward +"M-space" set-mark +"M-#" insert-comment +"M-&" tilde-expand +"M-*" insert-completions +"M--" digit-argument +"M-." yank-last-arg +"M-0" digit-argument +"M-1" digit-argument +"M-2" digit-argument +"M-3" digit-argument +"M-4" digit-argument +"M-5" digit-argument +"M-6" digit-argument +"M-7" digit-argument +"M-8" digit-argument +"M-9" digit-argument +"M-<" beginning-of-history +"M-=" possible-completions +"M->" end-of-history +"M-?" possible-completions +"M-B" backward-word +"M-C" capitalize-word +"M-D" kill-word +"M-F" forward-word +"M-L" downcase-word +"M-N" non-incremental-forward-search-history +"M-P" non-incremental-reverse-search-history +"M-R" revert-line +"M-T" transpose-words +"M-U" upcase-word +"M-Y" yank-pop +"M-\e" delete-horizontal-space +"M-~" tilde-expand +"M-C-?" backward-kill-word +"M-_" yank-last-arg +.PP +Emacs Control-X bindings +.sp +"C-XC-G" abort +"C-XC-R" re-read-init-file +"C-XC-U" undo +"C-XC-X" exchange-point-and-mark +"C-X(" start-kbd-macro +"C-X)" end-kbd-macro +"C-XE" call-last-kbd-macro +"C-XC-?" backward-kill-line +.sp +.RE +.SS VI Mode bindings +.RS +.6i +.nf +.ta 2.5i +.sp +.PP +VI Insert Mode functions +.sp +"C-D" vi-eof-maybe +"C-H" backward-delete-char +"C-I" complete +"C-J" accept-line +"C-M" accept-line +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"C-[" vi-movement-mode +"C-_" undo +"\^ " to "~" self-insert +"C-?" backward-delete-char +.PP +VI Command Mode functions +.sp +"C-D" vi-eof-maybe +"C-E" emacs-editing-mode +"C-G" abort +"C-H" backward-char +"C-J" accept-line +"C-K" kill-line +"C-L" clear-screen +"C-M" accept-line +"C-N" next-history +"C-P" previous-history +"C-Q" quoted-insert +"C-R" reverse-search-history +"C-S" forward-search-history +"C-T" transpose-chars +"C-U" unix-line-discard +"C-V" quoted-insert +"C-W" unix-word-rubout +"C-Y" yank +"C-_" vi-undo +"\^ " forward-char +"#" insert-comment +"$" end-of-line +"%" vi-match +"&" vi-tilde-expand +"*" vi-complete +"+" next-history +"," vi-char-search +"-" previous-history +"." vi-redo +"/" vi-search +"0" beginning-of-line +"1" to "9" vi-arg-digit +";" vi-char-search +"=" vi-complete +"?" vi-search +"A" vi-append-eol +"B" vi-prev-word +"C" vi-change-to +"D" vi-delete-to +"E" vi-end-word +"F" vi-char-search +"G" vi-fetch-history +"I" vi-insert-beg +"N" vi-search-again +"P" vi-put +"R" vi-replace +"S" vi-subst +"T" vi-char-search +"U" revert-line +"W" vi-next-word +"X" backward-delete-char +"Y" vi-yank-to +"\e" vi-complete +"^" vi-first-print +"_" vi-yank-arg +"`" vi-goto-mark +"a" vi-append-mode +"b" vi-prev-word +"c" vi-change-to +"d" vi-delete-to +"e" vi-end-word +"f" vi-char-search +"h" backward-char +"i" vi-insertion-mode +"j" next-history +"k" prev-history +"l" forward-char +"m" vi-set-mark +"n" vi-search-again +"p" vi-put +"r" vi-change-char +"s" vi-subst +"t" vi-char-search +"u" vi-undo +"w" vi-next-word +"x" vi-delete +"y" vi-yank-to +"|" vi-column +"~" vi-change-case +.RE +.SH "SEE ALSO" +.PD 0 +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIbash\fP(1) +.PD +.SH FILES +.PD 0 +.TP +.FN ~/.inputrc +Individual \fBreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet.ramey@case.edu +.SH BUG REPORTS +If you find a bug in +.B readline, +you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of the +.B readline +library that you have. +.PP +Once you have determined that a bug actually exists, mail a +bug report to \fIbug\-readline\fP@\fIgnu.org\fP. +If you have a fix, you are welcome to mail that +as well! Suggestions and `philosophical' bug reports may be mailed +to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet.ramey@case.edu . +.SH BUGS +It's too big and too slow. diff --git a/static/netbsd/man3/readpassphrase.3 b/static/netbsd/man3/readpassphrase.3 new file mode 100644 index 00000000..b3821925 --- /dev/null +++ b/static/netbsd/man3/readpassphrase.3 @@ -0,0 +1,118 @@ +.\" $NetBSD: readpassphrase.3,v 1.5 2017/04/18 18:41:46 christos Exp $ +.\" $OpenBSD: readpassphrase.3,v 1.3 2001/08/06 10:42:25 mpech Exp $ +.\" +.\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 20, 2000 +.Dt READPASSPHRASE 3 +.Os +.Sh NAME +.Nm readpassphrase +.Nd get a passphrase from the user +.Sh SYNOPSIS +.In readpassphrase.h +.Ft char * +.Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags" +.Sh DESCRIPTION +The +.Fn readpassphrase +function displays a prompt to, and reads in a passphrase from, +.Pa /dev/tty . +If this file is inaccessible +and the +.Dv RPP_REQUIRE_TTY +flag is not set, +.Fn readpassphrase +displays the prompt on the standard error output and reads from the standard +input. +In this case it is generally not possible to turn off echo. +.Pp +Up to +.Fa bufsiz +- 1 characters (one is for the NUL) are read into the provided buffer +.Fa buf . +Any additional +characters and the terminating newline (or return) character are discarded. +.Pp +.Fn readpassphrase +takes the following optional +.Fa flags : +.Pp +.Bd -literal -offset indent -compact +RPP_ECHO_OFF turn off echo (default behavior) +RPP_ECHO_ON leave echo on +RPP_REQUIRE_TTY fail if there is no tty +RPP_FORCELOWER force input to lower case +RPP_FORCEUPPER force input to upper case +RPP_SEVENBIT strip the high bit from input +.Ed +.Pp +The calling process should zero the passphrase as soon as possible to +avoid leaving the cleartext passphrase visible in the process's address +space. +.Sh RETURN VALUES +On success, +.Fn readpassphrase +returns a pointer to the null-terminated passphrase. +If the +.Dv RPP_REQUIRE_TTY +flag is set and +.Pa /dev/tty +is inaccessible, +.Fn readpassphrase +returns a null pointer. +.Sh FILES +.Bl -tag -width /dev/tty -compact +.It Pa /dev/tty +.El +.Sh EXAMPLES +The following code fragment will read a passphrase from +.Pa /dev/tty +into the buffer +.Fa passbuf . +.Bd -literal -offset indent +char passbuf[1024]; + +\&... + +if (readpassphrase("Response: ", passbuf, sizeof(passbuf), + RPP_REQUIRE_TTY) == NULL) + errx(1, "unable to read passphrase"); + +if (compare(transform(passbuf), epass) != 0) + errx(1, "bad passphrase"); + +\&... + +memset(passbuf, 0, sizeof(passbuf)); +.Ed +.Sh SEE ALSO +.Xr getpass 3 +.Sh HISTORY +The +.Fn readpassphrase +function first appeared in +.Ox 2.9 . diff --git a/static/netbsd/man3/reallocarr.3 b/static/netbsd/man3/reallocarr.3 new file mode 100644 index 00000000..446f281a --- /dev/null +++ b/static/netbsd/man3/reallocarr.3 @@ -0,0 +1,177 @@ +.\" $NetBSD: reallocarr.3,v 1.7 2022/08/31 12:18:41 riastradh Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd August 31, 2022 +.Dt REALLOCARR 3 +.Os +.Sh NAME +.Nm reallocarr +.Nd reallocate array +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fo reallocarr +.Fa "void *ptrp" +.Fa "size_t number" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +The +.Nm +function safely allocates, resizes, or frees arrays in memory. +.Pp +If +.Fa ptr +is a null pointer, or a pointer to memory previously allocated with +.Nm , +then +.Fo reallocarr +.Li & Ns Fa ptr , +.Fa number , +.Fa size +.Fc +allocates or reallocates the memory that +.Fa ptr +points to, possibly moving it to a different location in memory, so +that it has space for an array of +.Fa number +elements of +.Fa size +bytes apiece. +.Nm +updates +.Fa ptr +in case it was moved on success, and leaves it unchanged on failure. +.Pp +If +.Fa ptr +was previously allocated, the objects stored at +.Fa ptr Ns Li "[0]" , +.Fa ptr Ns Li "[1]" , +\&..., +up to the shorter of its old +.Fa number +and its new +.Fa number , +are copied into the new memory, like +.Xr realloc 3 . +.Pp +.Fa ptr +may be null and +.Fa number +may be zero. +.Fa size +must be nonzero. +.Pp +The memory allocated by +.Nm +may be freed with +.Fo reallocarr +.Li & Ns Fa ptr , +.Li 0 , +.Fa size +.Fc , +which will always succeed and unconditionally set +.Fa ptr +to null. +.Pp +Like +.Xr calloc 3 , +.Nm +fails gracefully if the product of +.Fa number +and +.Fa size +would overflow the representable size of memory. +Unlike +.Xr calloc 3 , +new memory allocated by +.Nm +is not zero-initialized. +.Pp +The +.Nm +function may alter +.Va errno +as a side effect. +.Pp +Note that the argument +.Fa ptrp +is a pointer to a pointer to allocated memory, unlike +.Xr realloc 3 +which takes a pointer to allocated memory. +.Sh RETURN VALUES +On successful completion, +.Nm +returns 0 and updates +.Fa ptr . +Otherwise, an +.Xr errno 2 +is returned, and +.Fa ptr +and the memory it points to are unmodified. +.Sh EXAMPLES +The following uses +.Fn reallocarr +to initialize an array of +.Dv INITSIZE +integers, then +resizes it to +.Dv NEWSIZE +elements, and finally frees it: +.Bd -literal -offset indent +int *data = NULL; +int error = 0; + +/* allocate */ +error = reallocarr(&data, INITSIZE, sizeof(*data)); +if (error) + errc(1, error, "reallocarr failed"); +\&... +/* resize */ +error = reallocarr(&data, NEWSIZE, sizeof(*data)); +if (error) + errc(1, error, "reallocarr failed on resize"); +\&... +/* free */ +(void)reallocarr(&data, 0, sizeof(*data)); +assert(data == NULL); +.Ed +.Sh SEE ALSO +.Xr calloc 3 , +.Xr realloc 3 , +.Xr reallocarray 3 +.Sh HISTORY +.Nm +first appeared in +.Nx 7.0 . +.Ox +introduced the +.Xr reallocarray 3 +function for the same purpose, but the interface makes it difficult +to correctly handle zero-sized allocations. diff --git a/static/netbsd/man3/reallocarray.3 b/static/netbsd/man3/reallocarray.3 new file mode 100644 index 00000000..7ad7f344 --- /dev/null +++ b/static/netbsd/man3/reallocarray.3 @@ -0,0 +1,123 @@ +.\" $NetBSD: reallocarray.3,v 1.7 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 2015 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 9, 2022 +.Dt REALLOCARRAY 3 +.Os +.Sh NAME +.Nm reallocarray +.Nd reallocate memory for an array of elements checking for overflow +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fo reallocarray +.Fa "void *ptr" +.Fa "size_t nmemb" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +The +.Fn reallocarray +function reallocates the pointer +.Fa ptr +to a size appropriate to handle an allocation of +.Fa nmemb +elements in an array where each of the array elements is +.Fa size +bytes using +.Xr realloc 3 +and making sure that overflow does not happen in the multiplication of +.Dq "nmemb * size" . +Otherwise it behaves like +.Xr realloc 3 . +.Sh RETURN VALUES +The +.Fn reallocarray +function will return +.Dv NULL +if there was overflow or if +.Xr realloc 3 +failed setting +.Va errno +to +.Er ENOMEM +or preserving the value from +.Xr realloc 3 . +.Sh SEE ALSO +.Xr malloc 3 , +.Xr realloc 3 , +.Xr reallocarr 3 +.\" .Sh STANDARDS +.\" Will be part of POSIX, but isn't yet. +.Sh HISTORY +The +.Fn reallocarray +function first appeared in +.Ox 5.6 . +.Fn reallocarray +was redesigned in +.Nx 8 +as +.Fn reallocarr 3 . +Until +.Nx 10 , +.Nm +was available in the +.Vt _OPENBSD_SOURCE +namespace. +.Sh CAVEATS +The +.Fn reallocarray +function was designed to facilitate safe, +robust programming and overcome the shortcomings of the +.Xr malloc 3 +and +.Xr realloc 3 +functions by centralizing the overflow check in the multiplication of +.Fa nmemb +and +.Fa size . +.Pp +There are still portability issues. +(It does not solve the +.Dv 0 +sized allocation return ambiguity in the C standard: does +.Fn reallocarray +return +.Dv NULL +or a unique pointer to memory that cannot be accessed? +Does a +.Dv NULL +mean that an error occurred, and can someone check +.Dv errno +in that case to find out what happened?) +For this reason +.Nx +decided to go with an alternative implementation, and created +.Xr reallocarr 3 . diff --git a/static/netbsd/man3/realpath.3 b/static/netbsd/man3/realpath.3 new file mode 100644 index 00000000..10547e8a --- /dev/null +++ b/static/netbsd/man3/realpath.3 @@ -0,0 +1,163 @@ +.\" $NetBSD: realpath.3,v 1.19 2017/03/06 09:24:09 pgoyette Exp $ +.\" +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Jan-Simon Pendry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)realpath.3 8.2 (Berkeley) 2/16/94 +.\" +.Dd May 24, 2013 +.Dt REALPATH 3 +.Os +.Sh NAME +.Nm realpath +.Nd returns the canonicalized absolute pathname +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In stdlib.h +.Ft "char *" +.Fn realpath "const char * restrict pathname" "char * restrict resolvedname" +.Sh DESCRIPTION +The +.Fn realpath +function resolves all symbolic links, extra +.Dq / +characters and references to +.Pa /./ +and +.Pa /../ +in +.Fa pathname , +and copies the resulting absolute pathname into +the memory referenced by +.Fa resolvedname . +The +.Fa resolvedname +argument +.Em must +refer to a buffer capable of storing at least +.Dv MAXPATHLEN +characters, or be +.Dv NULL . +.Pp +The +.Fn realpath +function will resolve both absolute and relative paths +and return the absolute pathname corresponding to +.Fa pathname . +.Sh RETURN VALUES +If +.Fa resolvedname +is +.Dv NULL , +it will be allocated and the returned pointer can be deallocated using +.Xr free 3 . +The +.Fn realpath +function returns +.Fa resolvedname +on success. +If an error occurs, +.Fn realpath +returns +.Dv NULL , +and if +.Fa resolvedname +was not allocated by +.Fn realpath , +it will contain the pathname which caused the problem. +.Sh ERRORS +The function +.Fn realpath +may fail and set the external variable +.Va errno +for any of the errors specified for the library functions +.\" First sorted by section, then by name. +.Xr lstat 2 , +.Xr readlink 2 , +.Xr getcwd 3 +and +.Xr malloc 3 . +.Pp +In addition, the following errors may be reported: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa pathname +argument is +.Dv NULL . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the +.Fa pathname . +.It Bq Er ENAMETOOLONG +The resulting absolute pathname exceeds +.Dv MAXPATHLEN +characters. +.It Bq Er ENOENT +The value of the +.Fa pathname +argument is an empty string; +or a symbolic link to an empty string is encountered. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.El +.Sh SEE ALSO +.Xr getcwd 3 +.Sh STANDARDS +.Fn realpath +first appeared in +.St -xpg4.2 +and is part of +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn realpath +function call first appeared in +.Bx 4.4 . +In +.Nx 7.0 +the function was updated to accept a +.Dv NULL +pointer for the +.Fa resolvedname +argument. +.Sh BUGS +This implementation of +.Fn realpath +differs slightly from the Solaris implementation. +The +.Bx 4.4 +version always returns absolute pathnames, +whereas the Solaris implementation will, +under certain circumstances, return a relative +.Fa resolvedname +when given a relative +.Fa pathname . diff --git a/static/netbsd/man3/recno.3 b/static/netbsd/man3/recno.3 new file mode 100644 index 00000000..a38871fe --- /dev/null +++ b/static/netbsd/man3/recno.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: recno.3,v 1.11 2010/03/22 19:30:53 joerg Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" +.Dd April 17, 2003 +.Dt RECNO 3 +.Os +.Sh NAME +.Nm recno +.Nd record number database access method +.Sh SYNOPSIS +.In sys/types.h +.In db.h +.Sh DESCRIPTION +The routine +.Fn dbopen +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.Xr dbopen 3 , +this manual page describes only the recno specific information. +.Pp +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.Pp +The recno access method specific data structure provided to +.Fn dbopen +is defined in the +.In db.h +include file as follows: +.Bd -literal +typedef struct { + u_long flags; + u_int cachesize; + u_int psize; + int lorder; + size_t reclen; + uint8_t bval; + char *bfname; +} RECNOINFO; +.Ed +.Pp +The elements of this structure are defined as follows: +.Bl -tag -width cachesizex +.It Fa flags +The flag value is specified by or'ing any of the following values: +.Bl -tag -width R_FIXEDLENX -offset indent +.It Dv R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.Fa reclen +specifies the length of the record, and the structure element +.Fa bval +is used as the pad character. +Any records, inserted into the database, that are less than +.Fa reclen +bytes long are automatically padded. +.It Dv R_NOKEY +In the interface specified by +.Fn dbopen , +the sequential record retrieval fills in both the caller's key and +data structures. +If the +.Dv R_NOKEY +flag is specified, the cursor routines are not required to fill in the +key structure. +This permits applications to retrieve records at the end of files +without reading all of the intervening records. +.It Dv R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.Fn dbopen +is called, instead of permitting any unmodified records to be read +from the original file. +.El +.It Fa cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.Em only +advisory, and the access method will allocate more memory rather than +fail. +If +.Fa cachesize +is 0 (no size is specified) a default cache is used. +.It Fa psize +The recno access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that +tree. +If +.Fa psize +is 0 (no page size is specified) a page size is chosen based on the +underlying file system I/O block size. +See +.Xr btree 3 +for more information. +.It Fa lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.Fa lorder +is 0 (no order is specified) the current host order is used. +.It Fa reclen +The length of a fixed-length record. +.It Fa bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines +.Pq Dq \en +are used to mark the end of variable-length records and fixed-length +records are padded with spaces. +.It Fa bfname +The recno access method stores the in-memory copies of its records +in a btree. +If bfname is +.No non- Ns Dv NULL , +it specifies the name of the btree file, as if specified as the file +name for a +.Fn dbopen +of a btree file. +.El +.Pp +The data part of the key/data pair used by the recno access method +is the same as other access methods. +The key is different. +The +.Fa data +field of the key should be a pointer to a memory location of type +recno_t, as defined in the +.In db.h +include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.Fa size +field of the key should be the size of that type. +.Pp +Because there can be no meta-data associated with the underlying +recno access method files, any changes made to the default values +(e.g., fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.Pp +In the interface specified by +.Fn dbopen , +using the +.Fa put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.Sh ERRORS +The +.Nm +access method routines may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr dbopen 3 +or the following: +.Bl -tag -width Er +.It Er EINVAL +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.El +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr hash 3 , +.Xr mpool 3 +.Pp +.Rs +.%T "Document Processing in a Relational Database System" +.%A Michael Stonebraker +.%A Heidi Stettner +.%A Joseph Kalash +.%A Antonin Guttman +.%A Nadene Lynn +.%J Memorandum No. UCB/ERL M82/32 +.%D May 1982 +.Re +.Sh BUGS +Only big and little endian byte order is supported. diff --git a/static/netbsd/man3/refuse.3 b/static/netbsd/man3/refuse.3 new file mode 100644 index 00000000..fbc188f0 --- /dev/null +++ b/static/netbsd/man3/refuse.3 @@ -0,0 +1,288 @@ +.\" $NetBSD: refuse.3,v 1.15 2019/04/11 06:18:43 wiz Exp $ +.\" +.\" Copyright © 2007 Alistair Crooks. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 11, 2019 +.Dt REFUSE 3 +.Os +.Sh NAME +.Nm refuse +.Nd Re-implementation of a file system in userspace system +.Sh LIBRARY +.Lb librefuse +.Sh SYNOPSIS +.In fuse.h +.Ft int +.Fo fuse_main +.Fa "int argc" "char **argv" "const struct fuse_operations *" +.Fc +.Ft struct fuse_args +.Fo FUSE_ARGS_INIT +.Fa "int argc" "char **argv" +.Fc +.Ft struct fuse_opt +.Fo FUSE_OPT_KEY +.Fa "const char* templ" "int32_t key" +.Fc +.Vt struct fuse_opt Dv FUSE_OPT_END ; +.Vt int32_t Dv FUSE_OPT_KEY_OPT ; +.Vt int32_t Dv FUSE_OPT_KEY_NONOPT ; +.Vt int32_t Dv FUSE_OPT_KEY_KEEP ; +.Vt int32_t Dv FUSE_OPT_KEY_DISCARD ; +.Ft int +.Fo fuse_opt_add_arg +.Fa "struct fuse_args *args" "const char *arg" +.Fc +.Ft int +.Fo fuse_opt_add_opt +.Fa "char **opts" "const char *opt" +.Fc +.Ft int +.Fo fuse_opt_add_opt_escaped +.Fa "char **opts" "const char *opt" +.Fc +.Ft void +.Fo fuse_opt_free_args +.Fa "struct fuse_args *args" +.Fc +.Ft int +.Fo fuse_opt_insert_arg +.Fa "struct fuse_args *args" "int pos" "const char *arg" +.Fc +.Ft int +.Fo fuse_opt_match +.Fa "const struct fuse_opt *opts" "const char *opt" +.Fc +.Ft int +.Fo fuse_opt_parse +.Fa "struct fuse_args *args" "void *userdata" +.Fa "const struct fuse_opt *descriptions" "fuse_opt_proc_t processingfunc" +.Fc +.Ft int +.Fo fuse_new +.Fa "struct fuse_args *args" "const struct fuse_operations *ops" +.Fa "size_t opssize" "void *userdata" +.Fc +.Ft int +.Fo fuse_mount +.Fa "struct fuse *fuse" "const char *mountpoint" +.Fc +.Ft int +.Fo fuse_unmount +.Fa "struct fuse* fuse" +.Fc +.Ft int +.Fo fuse_daemonize +.Fa "struct fuse *fuse" +.Fc +.Ft int +.Fo fuse_version +.Fa "struct fuse *fuse" +.Fc +.Ft int +.Fo puffs_fuse_node_getattr +.Fa "const char *path" "struct stat *attrs" +.Fc +.Ft int +.Fo puffs_fuse_node_readlink +.Fa "const char *path" "char *output" "size_t outlen" +.Fc +.Ft int +.Fo puffs_fuse_node_mknod +.Fa "const char *path" "mode_t permissions" "dev_t devicenumber" +.Fc +.Ft int +.Fo puffs_fuse_node_mkdir +.Fa "const char *path" "mode_t permissions" +.Fc +.Ft int +.Fo puffs_fuse_unlink +.Fa "const char *path" +.Fc +.Ft int +.Fo puffs_fuse_node_rmdir +.Fa "const char *path" +.Fc +.Ft int +.Fo puffs_fuse_node_symlink +.Fa "const char *path" "const char *target" +.Fc +.Ft int +.Fo puffs_fuse_node_rename +.Fa "const char *from" "const char *to" +.Fc +.Ft int +.Fo puffs_fuse_node_link +.Fa "const char *from" "const char *to" +.Fc +.Ft int +.Fo puffs_fuse_node_chmod +.Fa "const char *path" "mode_t permissions" +.Fc +.Ft int +.Fo puffs_fuse_node_own +.Fa "const char *path" "uid_t owner" "gid_t group" +.Fc +.Ft int +.Fo puffs_fuse_node_truncate +.Fa "const char *path" "off_t newsize" +.Fc +.Ft int +.Fo puffs_fuse_node_utime +.Fa "const char *path" "struct utimbuf *newtimes" +.Fc +.Ft int +.Fo puffs_fuse_node_open +.Fa "const char *path" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_read +.Fa "const char *path" "char *buffer" "size_t bufferlen" "off_t startoffset" +.Fa "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_write +.Fa "const char *path" "char *buffer" "size_t bufferlen" "off_t startoffset" +.Fa "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_fs_statfs +.Fa "const char *path" "struct statvfs *vfsinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_flush +.Fa "const char *path" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_fsync +.Fa "const char *path" "int flags" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_setxattr +.Fa "const char *path" "const char *attrname" "const char *attrvalue" +.Fa "size_t attrsize" "int flags" +.Fc +.Ft int +.Fo puffs_fuse_node_getxattr +.Fa "const char *path" "const char *attrname" "const char *attrvalue" +.Fa "size_t attrvaluesize" +.Fc +.Ft int +.Fo puffs_fuse_node_listxattr +.Fa "const char *path" "const char *attrname" +.Fa "size_t attrvaluesize" +.Fc +.Ft int +.Fo puffs_fuse_node_removexattr +.Fa "const char *path" "const char *attrname" +.Fc +.Ft int +.Fo puffs_fuse_node_opendir +.Fa "const char *path" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_readdir +.Fa "const char *path" "void *data" "fuse_fill_dir_t fillinfo" +.Fa "off_t offset" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_releasedir +.Fa "const char *path" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_fsyncdir +.Fa "const char *path" "int flags" "struct fuse_file_info *fileinfo" +.Fc +.Ft void * +.Fo puffs_fuse_fs_init +.Fa "struct fuse_conn_info *connectioninfo" +.Fc +.Ft void +.Fo puffs_fuse_node_destroy +.Fa "void *connection" +.Fc +.Ft int +.Fo puffs_fuse_node_access +.Fa "const char *path" "int accesstype" +.Fc +.Ft int +.Fo puffs_fuse_node_create +.Fa "const char *path" "mode_t permissions" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_ftruncate +.Fa "const char *path" "off_t offset" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_fgetattr +.Fa "const char *path" "struct stat *attrs" "struct fuse_file_info *fileinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_lock +.Fa "const char *path" "struct fuse_file_info *fileinfo" +.Fa "int locktype" "struct flock *lockinfo" +.Fc +.Ft int +.Fo puffs_fuse_node_utimens +.Fa "const char *path" "const struct timespec *newtimes" +.Fc +.Ft int +.Fo puffs_fuse_node_bmap +.Fa "const char *path" "size_t mapsize" "uint64_t offset" +.Fc +.Sh DESCRIPTION +.Nm +is a reimplementation of the file system in user space subsystem. +Operations are transported from the kernel virtual file system layer +to the concrete implementation behind +.Nm , +where they are processed and results are sent back to the kernel. +.Pp +It uses the framework provided by the +.Xr puffs 3 +subsystem, and, through that, the kernel interface provided by +.Xr puffs 4 . +.Sh SEE ALSO +.Xr puffs 3 , +.Xr puffs 4 +.Rs +.%A Antti Kantee +.%A Alistair Crooks +.%D September 2007 +.%J EuroBSDCon 2007 +.%T ReFUSE: Userspace FUSE Reimplementation Using puffs +.Re +.Sh HISTORY +An unsupported experimental version of +.Nm +first appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org , +.An Antti Kantee Aq Mt pooka@NetBSD.org +.Sh BUGS +Many, legion, but well-loved. diff --git a/static/netbsd/man3/regex.3 b/static/netbsd/man3/regex.3 new file mode 100644 index 00000000..f4e71563 --- /dev/null +++ b/static/netbsd/man3/regex.3 @@ -0,0 +1,538 @@ +.\" Copyright (c) 1992, 1993, 1994 Henry Spencer. +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Henry Spencer of the University of Toronto. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)regex.3 8.2 (Berkeley) 3/16/94 +.\" +.TH REGEX 3 "March 16, 1994" +.de ZR +.\" one other place knows this name: the SEE ALSO section +.IR re_format (7) \\$1 +.. +.SH NAME +regcomp, regexec, regerror, regfree \- regular-expression library +.SH SYNOPSIS +.ft B +.\".na +#include <sys/types.h> +.br +#include <regex.h> +.HP 10 +int regcomp(regex_t\ *preg, const\ char\ *pattern, int\ cflags); +.HP +int\ regexec(const\ regex_t\ *preg, const\ char\ *string, +size_t\ nmatch, regmatch_t\ pmatch[], int\ eflags); +.HP +size_t\ regerror(int\ errcode, const\ regex_t\ *preg, +char\ *errbuf, size_t\ errbuf_size); +.HP +void\ regfree(regex_t\ *preg); +.\".ad +.ft +.SH DESCRIPTION +These routines implement POSIX 1003.2 regular expressions (``RE''s); +see +.ZR . +.I Regcomp +compiles an RE written as a string into an internal form, +.I regexec +matches that internal form against a string and reports results, +.I regerror +transforms error codes from either into human-readable messages, +and +.I regfree +frees any dynamically-allocated storage used by the internal form +of an RE. +.PP +The header +.I <regex.h> +declares two structure types, +.I regex_t +and +.IR regmatch_t , +the former for compiled internal forms and the latter for match reporting. +It also declares the four functions, +a type +.IR regoff_t , +and a number of constants with names starting with ``REG_''. +.PP +.I Regcomp +compiles the regular expression contained in the +.I pattern +string, +subject to the flags in +.IR cflags , +and places the results in the +.I regex_t +structure pointed to by +.IR preg . +.I Cflags +is the bitwise OR of zero or more of the following flags: +.IP REG_EXTENDED \w'REG_EXTENDED'u+2n +Compile modern (``extended'') REs, +rather than the obsolete (``basic'') REs that +are the default. +.IP REG_BASIC +This is a synonym for 0, +provided as a counterpart to REG_EXTENDED to improve readability. +.IP REG_NOSPEC +Compile with recognition of all special characters turned off. +All characters are thus considered ordinary, +so the ``RE'' is a literal string. +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +REG_EXTENDED and REG_NOSPEC may not be used +in the same call to +.IR regcomp . +.IP REG_ICASE +Compile for matching that ignores upper/lower case distinctions. +See +.ZR . +.IP REG_NOSUB +Compile for matching that need only report success or failure, +not what was matched. +.IP REG_NEWLINE +Compile for newline-sensitive matching. +By default, newline is a completely ordinary character with no special +meaning in either REs or strings. +With this flag, +`[^' bracket expressions and `.' never match newline, +a `^' anchor matches the null string after any newline in the string +in addition to its normal function, +and the `$' anchor matches the null string before any newline in the +string in addition to its normal function. +.IP REG_PEND +The regular expression ends, +not at the first NUL, +but just before the character pointed to by the +.I re_endp +member of the structure pointed to by +.IR preg . +The +.I re_endp +member is of type +.IR const\ char\ * . +This flag permits inclusion of NULs in the RE; +they are considered ordinary characters. +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +.PP +When successful, +.I regcomp +returns 0 and fills in the structure pointed to by +.IR preg . +One member of that structure +(other than +.IR re_endp ) +is publicized: +.IR re_nsub , +of type +.IR size_t , +contains the number of parenthesized subexpressions within the RE +(except that the value of this member is undefined if the +REG_NOSUB flag was used). +If +.I regcomp +fails, it returns a non-zero error code; +see DIAGNOSTICS. +.PP +.I Regexec +matches the compiled RE pointed to by +.I preg +against the +.IR string , +subject to the flags in +.IR eflags , +and reports results using +.IR nmatch , +.IR pmatch , +and the returned value. +The RE must have been compiled by a previous invocation of +.IR regcomp . +The compiled form is not altered during execution of +.IR regexec , +so a single compiled RE can be used simultaneously by multiple threads. +.PP +By default, +the NUL-terminated string pointed to by +.I string +is considered to be the text of an entire line, minus any terminating +newline. +The +.I eflags +argument is the bitwise OR of zero or more of the following flags: +.IP REG_NOTBOL \w'REG_STARTEND'u+2n +The first character of +the string +is not the beginning of a line, so the `^' anchor should not match before it. +This does not affect the behavior of newlines under REG_NEWLINE. +.IP REG_NOTEOL +The NUL terminating +the string +does not end a line, so the `$' anchor should not match before it. +This does not affect the behavior of newlines under REG_NEWLINE. +.IP REG_STARTEND +The string is considered to start at +\fIstring\fR\ + \fIpmatch\fR[0].\fIrm_so\fR +and to have a terminating NUL located at +\fIstring\fR\ + \fIpmatch\fR[0].\fIrm_eo\fR +(there need not actually be a NUL at that location), +regardless of the value of +.IR nmatch . +See below for the definition of +.IR pmatch +and +.IR nmatch . +This is an extension, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +Note that a non-zero \fIrm_so\fR does not imply REG_NOTBOL; +REG_STARTEND affects only the location of the string, +not how it is matched. +.PP +See +.ZR +for a discussion of what is matched in situations where an RE or a +portion thereof could match any of several substrings of +.IR string . +.PP +Normally, +.I regexec +returns 0 for success and the non-zero code REG_NOMATCH for failure. +Other non-zero error codes may be returned in exceptional situations; +see DIAGNOSTICS. +.PP +If REG_NOSUB was specified in the compilation of the RE, +or if +.I nmatch +is 0, +.I regexec +ignores the +.I pmatch +argument (but see below for the case where REG_STARTEND is specified). +Otherwise, +.I pmatch +points to an array of +.I nmatch +structures of type +.IR regmatch_t . +Such a structure has at least the members +.I rm_so +and +.IR rm_eo , +both of type +.I regoff_t +(a signed arithmetic type at least as large as an +.I off_t +and a +.IR ssize_t ), +containing respectively the offset of the first character of a substring +and the offset of the first character after the end of the substring. +Offsets are measured from the beginning of the +.I string +argument given to +.IR regexec . +An empty substring is denoted by equal offsets, +both indicating the character following the empty substring. +.PP +The 0th member of the +.I pmatch +array is filled in to indicate what substring of +.I string +was matched by the entire RE. +Remaining members report what substring was matched by parenthesized +subexpressions within the RE; +member +.I i +reports subexpression +.IR i , +with subexpressions counted (starting at 1) by the order of their opening +parentheses in the RE, left to right. +Unused entries in the array\(emcorresponding either to subexpressions that +did not participate in the match at all, or to subexpressions that do not +exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fIre_nsub\fR)\(emhave both +.I rm_so +and +.I rm_eo +set to \-1. +If a subexpression participated in the match several times, +the reported substring is the last one it matched. +(Note, as an example in particular, that when the RE `(b*)+' matches `bbb', +the parenthesized subexpression matches each of the three `b's and then +an infinite number of empty strings following the last `b', +so the reported substring is one of the empties.) +.PP +If REG_STARTEND is specified, +.I pmatch +must point to at least one +.I regmatch_t +(even if +.I nmatch +is 0 or REG_NOSUB was specified), +to hold the input offsets for REG_STARTEND. +Use for output is still entirely controlled by +.IR nmatch ; +if +.I nmatch +is 0 or REG_NOSUB was specified, +the value of +.IR pmatch [0] +will not be changed by a successful +.IR regexec . +.PP +.I Regerror +maps a non-zero +.I errcode +from either +.I regcomp +or +.I regexec +to a human-readable, printable message. +If +.I preg +is non-NULL, +the error code should have arisen from use of +the +.I regex_t +pointed to by +.IR preg , +and if the error code came from +.IR regcomp , +it should have been the result from the most recent +.I regcomp +using that +.IR regex_t . +.RI ( Regerror +may be able to supply a more detailed message using information +from the +.IR regex_t .) +.I Regerror +places the NUL-terminated message into the buffer pointed to by +.IR errbuf , +limiting the length (including the NUL) to at most +.I errbuf_size +bytes. +If the whole message won't fit, +as much of it as will fit before the terminating NUL is supplied. +In any case, +the returned value is the size of buffer needed to hold the whole +message (including terminating NUL). +If +.I errbuf_size +is 0, +.I errbuf +is ignored but the return value is still correct. +.PP +If the +.I errcode +given to +.I regerror +is first ORed with REG_ITOA, +the ``message'' that results is the printable name of the error code, +e.g. ``REG_NOMATCH'', +rather than an explanation thereof. +If +.I errcode +is REG_ATOI, +then +.I preg +shall be non-NULL and the +.I re_endp +member of the structure it points to +must point to the printable name of an error code; +in this case, the result in +.I errbuf +is the decimal digits of +the numeric value of the error code +(0 if the name is not recognized). +REG_ITOA and REG_ATOI are intended primarily as debugging facilities; +they are extensions, +compatible with but not specified by POSIX 1003.2, +and should be used with +caution in software intended to be portable to other systems. +Be warned also that they are considered experimental and changes are possible. +.PP +.I Regfree +frees any dynamically-allocated storage associated with the compiled RE +pointed to by +.IR preg . +The remaining +.I regex_t +is no longer a valid compiled RE +and the effect of supplying it to +.I regexec +or +.I regerror +is undefined. +.PP +None of these functions references global variables except for tables +of constants; +all are safe for use from multiple threads if the arguments are safe. +.SH IMPLEMENTATION CHOICES +There are a number of decisions that 1003.2 leaves up to the implementor, +either by explicitly saying ``undefined'' or by virtue of them being +forbidden by the RE grammar. +This implementation treats them as follows. +.PP +See +.ZR +for a discussion of the definition of case-independent matching. +.PP +There is no particular limit on the length of REs, +except insofar as memory is limited. +Memory usage is approximately linear in RE size, and largely insensitive +to RE complexity, except for bounded repetitions. +See BUGS for one short RE using them +that will run almost any system out of memory. +.PP +A backslashed character other than one specifically given a magic meaning +by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs) +is taken as an ordinary character. +.PP +Any unmatched [ is a REG_EBRACK error. +.PP +Equivalence classes cannot begin or end bracket-expression ranges. +The endpoint of one range cannot begin another. +.PP +RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255. +.PP +A repetition operator (?, *, +, or bounds) cannot follow another +repetition operator. +A repetition operator cannot begin an expression or subexpression +or follow `^' or `|'. +.PP +`|' cannot appear first or last in a (sub)expression or after another `|', +i.e. an operand of `|' cannot be an empty subexpression. +An empty parenthesized subexpression, `()', is legal and matches an +empty (sub)string. +An empty string is not a legal RE. +.PP +A `{' followed by a digit is considered the beginning of bounds for a +bounded repetition, which must then follow the syntax for bounds. +A `{' \fInot\fR followed by a digit is considered an ordinary character. +.PP +`^' and `$' beginning and ending subexpressions in obsolete (``basic'') +REs are anchors, not ordinary characters. +.SH SEE ALSO +grep(1), re_format(7) +.PP +POSIX 1003.2, sections 2.8 (Regular Expression Notation) +and +B.5 (C Binding for Regular Expression Matching). +.SH DIAGNOSTICS +Non-zero error codes from +.I regcomp +and +.I regexec +include the following: +.PP +.nf +.ta \w'REG_ECOLLATE'u+3n +REG_NOMATCH regexec() failed to match +REG_BADPAT invalid regular expression +REG_ECOLLATE invalid collating element +REG_ECTYPE invalid character class +REG_EESCAPE \e applied to unescapable character +REG_ESUBREG invalid backreference number +REG_EBRACK brackets [ ] not balanced +REG_EPAREN parentheses ( ) not balanced +REG_EBRACE braces { } not balanced +REG_BADBR invalid repetition count(s) in { } +REG_ERANGE invalid character range in [ ] +REG_ESPACE ran out of memory +REG_BADRPT ?, *, or + operand invalid +REG_EMPTY empty (sub)expression +REG_ASSERT ``can't happen''\(emyou found a bug +REG_INVARG invalid argument, e.g. negative-length string +.fi +.SH HISTORY +Originally written by Henry Spencer at University of Toronto. +Altered for inclusion in the 4.4BSD distribution. +.SH BUGS +This is an alpha release with known defects. +Please report problems. +.PP +There is one known functionality bug. +The implementation of internationalization is incomplete: +the locale is always assumed to be the default one of 1003.2, +and only the collating elements etc. of that locale are available. +.PP +The back-reference code is subtle and doubts linger about its correctness +in complex cases. +.PP +.I Regexec +performance is poor. +This will improve with later releases. +.I Nmatch +exceeding 0 is expensive; +.I nmatch +exceeding 1 is worse. +.I Regexec +is largely insensitive to RE complexity \fIexcept\fR that back +references are massively expensive. +RE length does matter; in particular, there is a strong speed bonus +for keeping RE length under about 30 characters, +with most special characters counting roughly double. +.PP +.I Regcomp +implements bounded repetitions by macro expansion, +which is costly in time and space if counts are large +or bounded repetitions are nested. +An RE like, say, +`((((a{1,100}){1,100}){1,100}){1,100}){1,100}' +will (eventually) run almost any existing machine out of swap space. +.PP +There are suspected problems with response to obscure error conditions. +Notably, +certain kinds of internal overflow, +produced only by truly enormous REs or by multiply nested bounded repetitions, +are probably not handled well. +.PP +Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is +a special character only in the presence of a previous unmatched `('. +This can't be fixed until the spec is fixed. +.PP +The standard's definition of back references is vague. +For example, does +`a\e(\e(b\e)*\e2\e)*d' match `abbbd'? +Until the standard is clarified, +behavior in such cases should not be relied on. +.PP +The implementation of word-boundary matching is a bit of a kludge, +and bugs may lurk in combinations of word-boundary matching and anchoring. diff --git a/static/netbsd/man3/regexp.3 b/static/netbsd/man3/regexp.3 new file mode 100644 index 00000000..46af0863 --- /dev/null +++ b/static/netbsd/man3/regexp.3 @@ -0,0 +1,322 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)regexp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: regexp.3,v 1.18 2017/07/03 21:32:50 wiz Exp $ +.\" +.Dd June 4, 1993 +.Dt REGEXP 3 +.Os +.Sh NAME +.Nm regcomp , +.Nm regexec , +.Nm regsub , +.Nm regerror +.Nd obsolete "'regexp'" regular expression handlers +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.In regexp.h +.Ft regexp * +.Fn regcomp "const char *exp" +.Ft int +.Fn regexec "const regexp *prog" "const char *string" +.Ft void +.Fn regsub "const regexp *prog" "const char *source" "char *dest" +.Ft void +.Fn regerror "const char *msg" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr regex 3 . +It is available from the compatibility library, libcompat. +.Ef +.Pp +The +.Fn regcomp , +.Fn regexec , +.Fn regsub , +and +.Fn regerror +functions implement +.Xr egrep 1 Ns -style +regular expressions and supporting facilities. +.Pp +The +.Fn regcomp +function +compiles a regular expression into a structure of type +.Em regexp , +and returns a pointer to it. +The space has been allocated using +.Xr malloc 3 +and may be released by +.Xr free 3 . +.Pp +The +.Fn regexec +function +matches a +.Dv NUL Ns -terminated +.Fa string +against the compiled regular expression +in +.Fa prog . +It returns 1 for success and 0 for failure, and adjusts the contents of +.Fa prog Ns 's +.Em startp +and +.Em endp +(see below) accordingly. +.Pp +The members of a +.Em regexp +structure include at least the following (not necessarily in order): +.Bd -literal -offset indent +char *startp[NSUBEXP]; +char *endp[NSUBEXP]; +.Ed +.Pp +where +.Dv NSUBEXP +is defined (as 10) in the header file. +Once a successful +.Fn regexec +has been done using the +.Fn regexp , +each +.Em startp Ns - Em endp +pair describes one substring +within the +.Fa string , +with the +.Em startp +pointing to the first character of the substring and +the +.Em endp +pointing to the first character following the substring. +The 0th substring is the substring of +.Fa string +that matched the whole +regular expression. +The others are those substrings that matched parenthesized expressions +within the regular expression, with parenthesized expressions numbered +in left-to-right order of their opening parentheses. +.Pp +The +.Fn regsub +function +copies +.Fa source +to +.Fa dest , +making substitutions according to the +most recent +.Fn regexec +performed using +.Fa prog . +Each instance of `&' in +.Fa source +is replaced by the substring +indicated by +.Em startp Ns Bq +and +.Em endp Ns Bq . +Each instance of +.Sq \e Ns Em n , +where +.Em n +is a digit, is replaced by +the substring indicated by +.Em startp Ns Bq Em n +and +.Em endp Ns Bq Em n . +To get a literal `&' or +.Sq \e Ns Em n +into +.Fa dest , +prefix it with `\e'; +to get a literal `\e' preceding `&' or +.Sq \e Ns Em n , +prefix it with +another `\e'. +.Pp +The +.Fn regerror +function +is called whenever an error is detected in +.Fn regcomp , +.Fn regexec , +or +.Fn regsub . +The default +.Fn regerror +writes the string +.Fa msg , +with a suitable indicator of origin, +on the standard +error output +and invokes +.Xr exit 3 . +The +.Fn regerror +function +can be replaced by the user if other actions are desirable. +.Sh REGULAR EXPRESSION SYNTAX +A regular expression is zero or more +.Em branches , +separated by `|'. +It matches anything that matches one of the branches. +.Pp +A branch is zero or more +.Em pieces , +concatenated. +It matches a match for the first, followed by a match for the second, etc. +.Pp +A piece is an +.Em atom +possibly followed by `*', `+', or `?'. +An atom followed by `*' matches a sequence of 0 or more matches of the atom. +An atom followed by `+' matches a sequence of 1 or more matches of the atom. +An atom followed by `?' matches a match of the atom, or the null string. +.Pp +An atom is a regular expression in parentheses (matching a match for the +regular expression), a +.Em range +(see below), `.' +(matching any single character), `^' (matching the null string at the +beginning of the input string), `$' (matching the null string at the +end of the input string), a `\e' followed by a single character (matching +that character), or a single character with no other significance +(matching that character). +.Pp +A +.Em range +is a sequence of characters enclosed in `[]'. +It normally matches any single character from the sequence. +If the sequence begins with `^', +it matches any single character +.Em not +from the rest of the sequence. +If two characters in the sequence are separated by `\-', this is shorthand +for the full list of +.Tn ASCII +characters between them +(e.g. `[0-9]' matches any decimal digit). +To include a literal `]' in the sequence, make it the first character +(following a possible `^'). +To include a literal `\-', make it the first or last character. +.Sh AMBIGUITY +If a regular expression could match two different parts of the input string, +it will match the one which begins earliest. +If both begin in the same place but match different lengths, or match +the same length in different ways, life gets messier, as follows. +.Pp +In general, the possibilities in a list of branches are considered in +left-to-right order, the possibilities for `*', `+', and `?' are +considered longest-first, nested constructs are considered from the +outermost in, and concatenated constructs are considered leftmost-first. +The match that will be chosen is the one that uses the earliest +possibility in the first choice that has to be made. +If there is more than one choice, the next will be made in the same manner +(earliest possibility) subject to the decision on the first choice. +And so forth. +.Pp +For example, +.Sq Li (ab|a)b*c +could match +`abc' in one of two ways. +The first choice is between `ab' and `a'; since `ab' is earlier, and does +lead to a successful overall match, it is chosen. +Since the `b' is already spoken for, +the `b*' must match its last possibility\(emthe empty string\(emsince +it must respect the earlier choice. +.Pp +In the particular case where no `|'s are present and there is only one +`*', `+', or `?', the net effect is that the longest possible +match will be chosen. +So +.Sq Li ab* , +presented with `xabbbby', will match `abbbb'. +Note that if +.Sq Li ab* , +is tried against `xabyabbbz', it +will match `ab' just after `x', due to the begins-earliest rule. +(In effect, the decision on where to start the match is the first choice +to be made, hence subsequent choices must respect it even if this leads them +to less-preferred alternatives.) +.Sh RETURN VALUES +The +.Fn regcomp +function +returns +.Dv NULL +for a failure +.Pf ( Fn regerror +permitting), +where failures are syntax errors, exceeding implementation limits, +or applying `+' or `*' to a possibly-null operand. +.Sh SEE ALSO +.Xr ed 1 , +.Xr egrep 1 , +.Xr ex 1 , +.Xr expr 1 , +.Xr fgrep 1 , +.Xr grep 1 , +.Xr regex 3 , +.Xr re_format 7 +.Sh HISTORY +Both code and manual page for +.Fn regcomp , +.Fn regexec , +.Fn regsub , +and +.Fn regerror +were written at the University of Toronto +and appeared in +.Bx 4.3 tahoe . +They are intended to be compatible with the Bell V8 +.Xr regexp 3 , +but are not derived from Bell code. +.Sh BUGS +Empty branches and empty regular expressions are not portable to V8. +.Pp +The restriction against +applying `*' or `+' to a possibly-null operand is an artifact of the +simplistic implementation. +.Pp +Does not support +.Xr egrep 1 Ns 's +newline-separated branches; +neither does the V8 +.Xr regexp 3 , +though. +.Pp +Due to emphasis on +compactness and simplicity, +it's not strikingly fast. +It does give special attention to handling simple cases quickly. diff --git a/static/netbsd/man3/remainder.3 b/static/netbsd/man3/remainder.3 new file mode 100644 index 00000000..a510a832 --- /dev/null +++ b/static/netbsd/man3/remainder.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: remainder.3,v 1.3 2024/01/26 19:27:30 nros Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 24, 2024 +.Dt REMAINDER 3 +.Os +.Sh NAME +.Nm remainder , +.Nm remainderf , +.Nm remainderl , +.Nm remquo , +.Nm remquof , +.Nm remquol +.Nd remainder functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn remainder "double x" "double y" +.Ft float +.Fn remainderf "float x" "float y" +.Ft long double +.Fn remainderl "long double x" "long double y" +.Ft double +.Fn remquo "double x" "double y" "int *quo" +.Ft float +.Fn remquof "float x" "float y" "int *quo" +.Ft long double +.Fn remquol "long double x" "long double y" "int *quo" +.Sh DESCRIPTION +Provided that +.Fa y +\*(Ne 0 , +the +.Fn remainder +.Fn remainderf +and +.Fn remainderl +functions calculate the floating-point remainder +.Fa r +of +.Bd -ragged -offset indent +.Va r += +.Va x - ny , +.Ed +.Pp +where +.Fa n +is the integral value nearest to the exact value of +.Fa x +/ +.Fa y . +If +.Bd -ragged -offset indent +.Va | n +- +.Va x / y | += 1/2 , +.Ed +.Pp +the value +.Fa n +is chosen to be even. +Consequently, the remainder is computed exactly and +.Va | r | +\*(Le +.Fa | y | +/ 2 . +.Pp +Also the +.Fn remquo +.Fn remquof +and +.Fn remquol +functions calculate the remainder as described above. +But these additionally use +.Fa quo +to store a value whose sign is the sign of +.Va x / y +and whose magnitude is congruent modulo +.Va 2^k +to the magnitude of the integral quotient of +.Va x / y , +where +.Fa k +is an implementation-defined integer greater than or equal to 3. +.Pp +The rationale of the +.Fn remquo +family of functions relates to situations where +only few bits of the quotient are required. +The exact representation of the quotient may not be meaningful when +.Fa x +is large in magnitude compared to +.Fa y . +.Sh RETURN VALUES +The functions return the remainder independent of the rounding mode. +If +.Fa y +is zero , +\*(Na +is returned and a domain error occurs. +A domain error occurs and a +\*(Na +is returned also when +.Fa x +is infinite but +.Fa y +is not a +\*(Na. +If either +.Fa x +or +.Fa y +is +\*(Na, +a +\*(Na +is always returned. +.Sh SEE ALSO +.Xr div 3 , +.Xr fast_remainder32 3 , +.Xr fmod 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/remove.3 b/static/netbsd/man3/remove.3 new file mode 100644 index 00000000..17895c34 --- /dev/null +++ b/static/netbsd/man3/remove.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: remove.3,v 1.12 2003/08/07 16:43:30 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)remove.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt REMOVE 3 +.Os +.Sh NAME +.Nm remove +.Nd remove directory entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn remove "const char *path" +.Sh DESCRIPTION +The +.Fn remove +function removes the file or directory specified by +.Fa path . +.Pp +If +.Fa path +specifies a directory, +.Fn remove "path" +is the equivalent of +.Fn rmdir "path" . +Otherwise, it is the equivalent of +.Fn unlink "path" . +.Sh RETURN VALUES +Upon successful completion, +.Fn remove +returns 0. +Otherwise, \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn remove +function +may fail and set +.Va errno +for any of the errors specified for the routines +.Xr rmdir 2 +or +.Xr unlink 2 . +.Sh SEE ALSO +.Xr rmdir 2 , +.Xr unlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn remove +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/resolver.3 b/static/netbsd/man3/resolver.3 new file mode 100644 index 00000000..abf118ac --- /dev/null +++ b/static/netbsd/man3/resolver.3 @@ -0,0 +1,669 @@ +.\" $NetBSD: resolver.3,v 1.1.1.2 2012/09/09 16:07:43 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: resolver.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd July 4, 2000 +.Dt RESOLVER @LIB_NETWORK_EXT_U@ +.Os BSD 4 +.Sh NAME +.Nm res_ninit , +.Nm res_ourserver_p , +.Nm fp_resstat , +.Nm res_hostalias , +.Nm res_pquery , +.Nm res_nquery , +.Nm res_nsearch , +.Nm res_nquerydomain , +.Nm res_nmkquery , +.Nm res_nsend , +.Nm res_nupdate , +.Nm res_nmkupdate , +.Nm res_nclose , +.Nm res_nsendsigned , +.Nm res_findzonecut , +.Nm res_getservers , +.Nm res_setservers , +.Nm res_ndestroy , +.Nm dn_comp , +.Nm dn_expand , +.Nm hstrerror , +.Nm res_init , +.Nm res_isourserver , +.Nm fp_nquery , +.Nm p_query , +.Nm hostalias , +.Nm res_query , +.Nm res_search , +.Nm res_querydomain , +.Nm res_mkquery , +.Nm res_send , +.Nm res_update , +.Nm res_close , +.Nm herror +.Nd resolver routines +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <netinet/in.h> +.Fd #include <arpa/nameser.h> +.Fd #include <resolv.h> +.Fd #include <res_update.h> +.Vt typedef struct __res_state *res_state ; +.Pp +.Ft int +.Fn res_ninit "res_state statp" +.Ft int +.Fn res_ourserver_p "const res_state statp" "const struct sockaddr_in *addr" +.Ft void +.Fn fp_resstat "const res_state statp" "FILE *fp" +.Ft "const char *" +.Fn res_hostalias "const res_state statp" "const char *name" "char *buf" "size_t buflen" +.Ft int +.Fn res_pquery "const res_state statp" "const u_char *msg" "int msglen" "FILE *fp" +.Ft int +.Fn res_nquery "res_state statp" "const char *dname" "int class" "int type" "u_char *answer" "int anslen" +.Ft int +.Fn res_nsearch "res_state statp" "const char *dname" "int class" "int type" "u_char * answer" "int anslen" +.Ft int +.Fn res_nquerydomain "res_state statp" "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" +.Ft int +.Fo res_nmkquery +.Fa "res_state statp" +.Fa "int op" +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "const u_char *data" +.Fa "int datalen" +.Fa "const u_char *newrr" +.Fa "u_char *buf" +.Fa "int buflen" +.Fc +.Ft int +.Fn res_nsend "res_state statp" "const u_char *msg" "int msglen" "u_char *answer" "int anslen" +.Ft int +.Fn res_nupdate "res_state statp" "ns_updrec *rrecp_in" +.Ft int +.Fn res_nmkupdate "res_state statp" "ns_updrec *rrecp_in" "u_char *buf" "int buflen" +.Ft void +.Fn res_nclose "res_state statp" +.Ft int +.Fn res_nsendsigned "res_state statp" "const u_char *msg" "int msglen" "ns_tsig_key *key" "u_char *answer" "int anslen" +.Ft int +.Fn res_findzonecut "res_state statp" "const char *dname" "ns_class class" "int options" "char *zname" "size_t zsize" "struct in_addr *addrs" "int naddrs" +.Ft int +.Fn res_getservers "res_state statp" "union res_sockaddr_union *set" "int cnt" +.Ft void +.Fn res_setservers "res_state statp" "const union res_sockaddr_union *set" "int cnt" +.Ft void +.Fn res_ndestroy "res_state statp" +.Ft int +.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs" "u_char **lastdnptr" +.Ft int +.Fn dn_expand "const u_char *msg" "const u_char *eomorig" "const u_char *comp_dn" "char *exp_dn" "int length" +.Ft "const char *" +.Fn hstrerror "int err" +.Ss DEPRECATED +.Fd #include <sys/types.h> +.Fd #include <netinet/in.h> +.Fd #include <arpa/nameser.h> +.Fd #include <resolv.h> +.Fd #include <res_update.h> +.Ft int +.Fn res_init "void" +.Ft int +.Fn res_isourserver "const struct sockaddr_in *addr" +.Ft int +.Fn fp_nquery "const u_char *msg" "int msglen" "FILE *fp" +.Ft void +.Fn p_query "const u_char *msg" "FILE *fp" +.Ft "const char *" +.Fn hostalias "const char *name" +.Ft int +.Fn res_query "const char *dname" "int class" "int type" "u_char *answer" "int anslen" +.Ft int +.Fn res_search "const char *dname" "int class" "int type" "u_char *answer" "int anslen" +.Ft int +.Fn res_querydomain "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen" +.Ft int +.Fo res_mkquery +.Fa "int op" +.Fa "const char *dname" +.Fa "int class" +.Fa "int type" +.Fa "const char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "u_char *buf" +.Fa "int buflen" +.Fc +.Ft int +.Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen" +.Ft int +.Fn res_update "ns_updrec *rrecp_in" +.Ft void +.Fn res_close "void" +.Ft void +.Fn herror "const char *s" +.Sh DESCRIPTION +These routines are used for making, sending and interpreting +query and reply messages with Internet domain name servers. +.Pp +State information is kept in +.Fa statp +and is used to control the behavior of these functions. +.Fa statp +should be set to all zeros prior to the first call to any of these functions. +.Pp +The functions +.Fn res_init , +.Fn res_isourserver , +.Fn fp_nquery , +.Fn p_query , +.Fn hostalias , +.Fn res_query , +.Fn res_search , +.Fn res_querydomain , +.Fn res_mkquery , +.Fn res_send , +.Fn res_update , +.Fn res_close +and +.Fn herror +are deprecated and are supplied for compatability with old source +code. +They use global configuration and state information that is +kept in the structure +.Ft _res +rather than that referenced through +.Ft statp . +.Pp +Most of the values in +.Ft statp +and +.Ft _res +are initialized on the first call to +.Fn res_ninit +/ +.Fn res_init +to reasonable defaults and can be ignored. +Options +stored in +.Ft statp->options +/ +.Ft _res.options +are defined in +.Pa resolv.h +and are as follows. +Options are stored as a simple bit mask containing the bitwise +.Dq OR +of the options enabled. +.Bl -tag -width "RES_DEB" +.It Dv RES_INIT +True if the initial name server address and default domain name are +initialized (i.e., +.Fn res_ninit +/ +.Fn res_init +has been called). +.It Dv RES_DEBUG +Print debugging messages. +.It Dv RES_AAONLY +Accept authoritative answers only. +Should continue until it finds an authoritative answer or finds an error. +Currently this is not implemented. +.It Dv RES_USEVC +Use TCP connections for queries instead of UDP datagrams. +.It Dv RES_STAYOPEN +Used with +.Dv RES_USEVC +to keep the TCP connection open between queries. +This is useful only in programs that regularly do many queries. +UDP should be the normal mode used. +.It Dv RES_IGNTC +Ignore truncation errors, i.e., don't retry with TCP. +.It Dv RES_RECURSE +Set the recursion-desired bit in queries. +This is the default. +(\c +.Fn res_nsend +/ +.Fn res_send +does not do iterative queries and expects the name server +to handle recursion.) +.It Dv RES_DEFNAMES +If set, +.Fn res_nsearch +/ +.Fn res_search +will append the default domain name to single-component names +(those that do not contain a dot). +This option is enabled by default. +.It Dv RES_DNSRCH +If this option is set, +.Fn res_nsearch +/ +.Fn res_search +will search for host names in the current domain and in parent domains; see +.Xr hostname @DESC_EXT@ . +This is used by the standard host lookup routine +.Xr gethostbyname @LIB_NETWORK_EXT@ . +This option is enabled by default. +.It Dv RES_NOALIASES +This option turns off the user level aliasing feature controlled by +the +.Ev HOSTALIASES +environment variable. +Network daemons should set this option. +.It Dv RES_USE_INET6 +This option causes +.Xr gethostbyname @LIB_NETWORK_EXT@ +to look for AAAA records before looking for A records if none are found. +.It Dv RES_ROTATE +This options causes the +.Fn res_nsend +/ +.Fn res_send +to rotate the list of nameservers in +.Fa statp->nsaddr_list +/ +.Fa _res.nsaddr_list . +.It Dv RES_KEEPTSIG +This option causes +.Fn res_nsendsigned +to leave the message unchanged after TSIG verification; otherwise the TSIG +record would be removed and the header updated. +.It Dv RES_NOTLDQUERY +This option causes +.Fn res_nsearch +to not attempt to resolve a unqualified name as if it were a top level +domain (TLD). +This option can cause problems if the site has "localhost" as a TLD rather +than having localhost on one or more elements of the search list. +This option has no effect if neither +.Dv RES_DEFNAMES +or +.Dv RES_DNSRCH +is set. +.El +.Pp +The +.Fn res_ninit +/ +.Fn res_init +routine +reads the configuration file (if any; see +.Xr resolver @FORMAT_EXT@ ) +to get the default domain name, search list and +the Internet address of the local name server(s). +If no server is configured, the host running the resolver is tried. +The current domain name is defined by the hostname +if not specified in the configuration file; +it can be overridden by the environment variable +.Ev LOCALDOMAIN . +This environment variable may contain several blank-separated +tokens if you wish to override the +.Dq search list +on a per-process basis. This is similar to the +.Ic search +command in the configuration file. +Another environment variable +.Pq Dq Ev RES_OPTIONS +can be set to override certain internal resolver options which are otherwise +set by changing fields in the +.Ft statp +/ +.Ft _res +structure or are inherited from the configuration file's +.Ic options +command. The syntax of the +.Dq Ev RES_OPTIONS +environment variable is explained in +.Xr resolver @FORMAT_EXT@ . +Initialization normally occurs on the first call +to one of the other resolver routines. +.Pp +The memory referred to by +.Ft statp +must be set to all zeros prior to the first call to +.Fn res_ninit . +.Fn res_ndestroy +should be call to free memory allocated by +.Fn res_ninit +after last use. +.Pp +The +.Fn res_nquery +/ +.Fn res_query +functions provides interfaces to the server query mechanism. +They constructs a query, sends it to the local server, +awaits a response, and makes preliminary checks on the reply. +The query requests information of the specified +.Fa type +and +.Fa class +for the specified fully-qualified domain name +.Fa dname . +The reply message is left in the +.Fa answer +buffer with length +.Fa anslen +supplied by the caller. +.Fn res_nquery +/ +.Fn res_query +return -1 on error or the length of the answer. +.Pp +The +.Fn res_nsearch +/ +.Fn res_search +routines make a query and awaits a response like +.Fn res_nquery +/ +.Fn res_query , +but in addition, it implements the default and search rules +controlled by the +.Dv RES_DEFNAMES +and +.Dv RES_DNSRCH +options. +It returns the length of the first successful reply which is stored in +.Ft answer +or -1 on error. +.Pp +The remaining routines are lower-level routines used by +.Fn res_nquery +/ +.Fn res_query . +The +.Fn res_nmkquery +/ +.Fn res_mkquery +functions +constructs a standard query message and places it in +.Fa buf . +It returns the size of the query, or \-1 if the query is +larger than +.Fa buflen . +The query type +.Fa op +is usually +.Dv QUERY , +but can be any of the query types defined in +.Pa <arpa/nameser.h> . +The domain name for the query is given by +.Fa dname . +.Fa Newrr +is currently unused but is intended for making update messages. +.Pp +The +.Fn res_nsend +/ +.Fn res_send +/ +.Fn res_nsendsigned +routines +sends a pre-formatted query and returns an answer. +It will call +.Fn res_ninit +/ +.Fn res_init +if +.Dv RES_INIT +is not set, send the query to the local name server, and +handle timeouts and retries. Additionally, +.Fn res_nsendsigned +will use TSIG signatures to add authentication to the query and verify the +response. In this case, only one nameserver will be contacted. +The length of the reply message is returned, or \-1 if there were errors. +.Pp +.Fn res_nquery +/ +.Fn res_query , +.Fn res_nsearch +/ +.Fn res_search +and +.Fn res_nsend +/ +.Fn res_send +return a length that may be bigger than +.Fa anslen . +In that case the query should be retried with a bigger buffer. +NOTE the answer to the second query may be larger still so supplying +a buffer that bigger that the answer returned by the previous +query is recommended. +.Pp +.Fa answer +MUST be big enough to receive a maximum UDP response from the server or +parts of the answer will be silently discarded. +The default maximum UDP response size is 512 bytes. +.Pp +The function +.Fn res_ourserver_p +returns true when +.Fa inp +is one of the servers in +.Fa statp->nsaddr_list +/ +.Fa _res.nsaddr_list . +.Pp +The functions +.Fn fp_nquery +/ +.Fn p_query +print out the query and any answer in +.Fa msg +on +.Fa fp . +.Fn p_query +is equivalent to +.Fn fp_nquery +with +.Fa msglen +set to 512. +.Pp +The function +.Fn fp_resstat +prints out the active flag bits in +.Fa statp->options +preceeded by the text ";; res options:" on +.Fa file . +.Pp +The functions +.Fn res_hostalias +/ +.Fn hostalias +lookup up name in the file referred to by the +.Ev HOSTALIASES +files return a fully qualified hostname if found or NULL if +not found or an error occurred. +.Fn res_hostalias +uses +.Fa buf +to store the result in, +.Fn hostalias +uses a static buffer. +.Pp +The functions +.Fn res_getservers +and +.Fn res_setservers +are used to get and set the list of server to be queried. +.Pp +The functions +.Fn res_nupdate +/ +.Fn res_update +take a list of ns_updrec +.Fa rrecp_in . +Identifies the containing zone for each record and groups the records +according to containing zone maintaining in zone order then sends and update +request to the servers for these zones. The number of zones updated is +returned or -1 on error. Note that +.Fn res_nupdate +will perform TSIG authenticated dynamic update operations if the key is not +NULL. +.Pp +The function +.Fn res_findzonecut +discovers the closest enclosing zone cut for a specified domain name, +and finds the IP addresses of the zone's master servers. +.Pp +The functions +.Fn res_nmkupdate +/ +.Fn res_mkupdate +take a linked list of ns_updrec +.Fa rrecp_in +and construct a UPDATE message in +.Fa buf . +.Fn res_nmkupdate +/ +.Fn res_mkupdate +return the length of the constructed message on no error or one of the +following error values. +.Bl -inset -width "-5" +.It -1 +An error occurred parsing +.Fa rrecp_in . +.It -2 +The buffer +.Fa buf +was too small. +.It -3 +The first record was not a zone section or there was a section order problem. +The section order is S_ZONE, S_PREREQ and S_UPDATE. +.It -4 +A number overflow occurred. +.It -5 +Unknown operation or no records. +.El +.Pp +The functions +.Fn res_nclose +/ +.Fn res_close +close any open files referenced through +.Fa statp +/ +.Fa _res . +.Pp +The function +.Fn res_ndestroy +calls +.Fn res_nclose +then frees any memory allocated by +.Fn res_ninit . +.Pp +The +.Fn dn_comp +function +compresses the domain name +.Fa exp_dn +and stores it in +.Fa comp_dn . +The size of the compressed name is returned or \-1 if there were errors. +The size of the array pointed to by +.Fa comp_dn +is given by +.Fa length . +The compression uses +an array of pointers +.Fa dnptrs +to previously-compressed names in the current message. +The first pointer points to +to the beginning of the message and the list ends with +.Dv NULL . +The limit to the array is specified by +.Fa lastdnptr . +A side effect of +.Fn dn_comp +is to update the list of pointers for labels inserted into the message +as the name is compressed. If +.Fa dnptr +is +.Dv NULL , +names are not compressed. If +.Fa lastdnptr +is +.Dv NULL , +the list of labels is not updated. +.Pp +The +.Fn dn_expand +entry +expands the compressed domain name +.Fa comp_dn +to a full domain name. +The compressed name is contained in a query or reply message; +.Fa msg +is a pointer to the beginning of the message. +.Fa eomorig +is a pointer to the first location after the message. +The uncompressed name is placed in the buffer indicated by +.Fa exp_dn +which is of size +.Fa length . +The size of compressed name is returned or \-1 if there was an error. +.Pp +The variables +.Ft statp->res_h_errno +/ +.Ft _res.res_h_errno +and external variable +.Ft h_errno +is set whenever an error occurs during resolver operation. The following +definitions are given in +.Pa <netdb.h> : +.Bd -literal +#define NETDB_INTERNAL -1 /* see errno */ +#define NETDB_SUCCESS 0 /* no problem */ +#define HOST_NOT_FOUND 1 /* Authoritative Answer Host not found */ +#define TRY_AGAIN 2 /* Non-Authoritative not found, or SERVFAIL */ +#define NO_RECOVERY 3 /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */ +#define NO_DATA 4 /* Valid name, no data for requested type */ +.Ed +.Pp +The +.Fn herror +function writes a message to the diagnostic output consisting of the string +parameter +.Fa s , +the constant string ": ", and a message corresponding to the value of +.Ft h_errno . +.Pp +The +.Fn hstrerror +function returns a string which is the message text corresponding to the +value of the +.Fa err +parameter. +.Sh FILES +.Bl -tag -width "/etc/resolv.conf " +.It Pa /etc/resolv.conf +See +.Xr resolver @FORMAT_EXT@ . +.El +.Sh SEE ALSO +.Xr gethostbyname @LIB_NETWORK_EXT@ , +.Xr hostname @DESC_EXT@ , +.Xr resolver @FORMAT_EXT@ ; +RFC1032, RFC1033, RFC1034, RFC1035, RFC974; +SMM:11, +.Dq Name Server Operations Guide for BIND diff --git a/static/netbsd/man3/rexec.3 b/static/netbsd/man3/rexec.3 new file mode 100644 index 00000000..01ba864f --- /dev/null +++ b/static/netbsd/man3/rexec.3 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)rexec.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: rexec.3,v 1.13 2003/08/07 16:44:16 agc Exp $ +.\" +.Dd June 4, 1993 +.Dt REXEC 3 +.Os +.Sh NAME +.Nm rexec +.Nd return stream to a remote command +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.Ft int +.Fn rexec "char **ahost" "int inport" "char *user" "char *passwd" "char *cmd" "int *fd2p" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr rcmd 3 . +It is available from the compatibility library, libcompat. +.Ef +.Pp +The +.Fn rexec +function looks up the host +.Fa *ahost +using +.Xr gethostbyname 3 , +returning \-1 if the host does not exist. +Otherwise +.Fa *ahost +is set to the standard name of the host. +If a username and password are both specified, then these +are used to authenticate to the foreign host; otherwise +the environment and then the user's +.Pa .netrc +file in his home directory are searched for appropriate information. +If all this fails, the user is prompted for the information. +.Pp +The port +.Fa inport +specifies which well-known +.Tn DARPA +Internet port to use for the connection; the call +.Ql getservbyname(\\*qexec\\*q, \\*qtcp\\*q) +(see +.Xr getservent 3 ) +will return a pointer to a structure, which contains the +necessary port. +The protocol for connection is described in detail in +.Xr rexecd 8 . +.Pp +If the connection succeeds, a socket in the Internet domain of type +.Dv SOCK_STREAM +is returned to the caller, and given to the remote command as +.Em stdin +and +.Em stdout . +If +.Fa fd2p +is non-zero, then an auxiliary channel to a control +process will be set up, and a descriptor for it will be placed +in +.Fa *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being +.Ux +signal numbers, to be forwarded to the process group of the command. +The diagnostic information returned does not include remote authorization +failure, as the secondary connection is set up after authorization has been +verified. +If +.Fa fd2p +is 0, then the +.Em stderr +(unit 2 of the remote command) will be made the same as the +.Em stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.Sh SEE ALSO +.Xr rcmd 3 , +.Xr rexecd 8 +.Sh HISTORY +The +.Fn rexec +function appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/rindex.3 b/static/netbsd/man3/rindex.3 new file mode 100644 index 00000000..0b9b33f6 --- /dev/null +++ b/static/netbsd/man3/rindex.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)rindex.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: rindex.3,v 1.14 2012/05/05 21:18:43 dholland Exp $ +.\" +.Dd May 5, 2012 +.Dt RINDEX 3 +.Os +.Sh NAME +.Nm rindex +.Nd locate character in string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft char * +.Fn rindex "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn rindex +function +locates the last character +matching +.Fa c +(converted to a +.Em char ) +in the nul-terminated string +.Fa s . +.Pp +This function is obsolete. +The equivalent function +.Xr strrchr 3 +should be used instead. +.Sh RETURN VALUES +A pointer to the character is returned if it is found; otherwise +.Dv NULL +is returned. +If +.Fa c +is +.Ql \e0 , +.Fn rindex +locates the terminating +.Ql \e0 . +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn rindex +function conforms to +.St -p1003.1-2001 . +The +.St -p1003.1-2004 +revision marked it as legacy and recommended the use of +.Xr strrchr 3 +instead. +The +.St -p1003.1-2008 +revision removed +.Fn rindex +from the specification. +.Sh HISTORY +A +.Fn rindex +function appeared in +.At v6 . diff --git a/static/netbsd/man3/rint.3 b/static/netbsd/man3/rint.3 new file mode 100644 index 00000000..e63a1c5c --- /dev/null +++ b/static/netbsd/man3/rint.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)rint.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: rint.3,v 1.16 2025/04/18 13:56:05 christos Exp $ +.\" +.Dd April 18, 2025 +.Dt RINT 3 +.Os +.Sh NAME +.Nm nearbyint , +.Nm nearbyintf , +.Nm nearbyintl , +.Nm rint , +.Nm rintf , +.Nm rintl +.Nd round to integral value in floating-point format +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn nearbyint "double x" +.Ft float +.Fn nearbyintf "float x" +.Ft long double +.Fn nearbyintl "long double x" +.Ft double +.Fn rint "double x" +.Ft float +.Fn rintf "float x" +.Ft long double +.Fn rintl "long double x" +.Sh DESCRIPTION +The +.Fn rint , +.Fn rintf , +and +.Fn rintl +functions return the integral value nearest to +.Fa x +according to the prevailing rounding mode. +The prevailing rounding mode can be retrieved using +.Xr fegetround 3 , +and set using +.Xr fesetround 3 . +These functions raise an inexact exception when the original argument +is not an exact integer. +.Pp +The +.Fn nearbyint , +.Fn nearbyintf , +and +.Fn nearbyintl +functions perform the same operation, except that they do not raise +an inexact exception. +.Sh SEE ALSO +.Xr abs 3 , +.Xr ceil 3 , +.Xr fabs 3 , +.Xr fegetround 3 , +.Xr fenv 3 , +.Xr fesetround 3 , +.Xr floor 3 , +.Xr lrint 3 , +.Xr math 3 , +.Xr round 3 +.Sh HISTORY +A +.Fn rint +function appeared in +.At v6 . diff --git a/static/netbsd/man3/rmd160.3 b/static/netbsd/man3/rmd160.3 new file mode 100644 index 00000000..716ec852 --- /dev/null +++ b/static/netbsd/man3/rmd160.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: rmd160.3,v 1.4 2017/07/03 21:32:49 wiz Exp $ +.\" $OpenBSD: rmd160.3,v 1.12 2000/04/18 03:01:29 aaron Exp $ +.\" +.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" See http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html +.\" for detailed information about RIPEMD-160. +.\" +.Dd July 16, 1997 +.Dt RMD160 3 +.Os +.Sh NAME +.Nm RMD160Init , +.Nm RMD160Update , +.Nm RMD160Final , +.Nm RMD160Transform , +.Nm RMD160End , +.Nm RMD160File , +.Nm RMD160Data +.Nd calculate the ``RIPEMD-160'' message digest +.Sh SYNOPSIS +.In sys/types.h +.In rmd160.h +.Ft void +.Fn RMD160Init "RMD160_CTX *context" +.Ft void +.Fn RMD160Update "RMD160_CTX *context" "const u_char *data" "u_int nbytes" +.Ft void +.Fn RMD160Final "u_char digest[20]" "RMD160_CTX *context" +.Ft void +.Fn RMD160Transform "uint32_t state[5]" "const uint32_t block[16]" +.Ft "char *" +.Fn RMD160End "RMD160_CTX *context" "char *buf" +.Ft "char *" +.Fn RMD160File "char *filename" "char *buf" +.Ft "char *" +.Fn RMD160Data "u_char *data" "size_t len" "char *buf" +.Sh DESCRIPTION +The RMD160 functions implement the 160-bit RIPE message digest hash algorithm +(RMD-160). +RMD-160 is used to generate a condensed representation +of a message called a message digest. +The algorithm takes a +message less than 2^64 bits as input and produces a 160-bit digest +suitable for use as a digital signature. +.Pp +The RMD160 functions are considered to be more secure than the +.Xr md4 3 +and +.Xr md5 3 +functions and at least as secure as the +.Xr sha1 3 +function. +All share a similar interface. +.Pp +The +.Fn RMD160Init +function initializes a RMD160_CTX +.Ar context +for use with +.Fn RMD160Update , +and +.Fn RMD160Final . +The +.Fn RMD160Update +function adds +.Ar data +of length +.Ar nbytes +to the RMD160_CTX specified by +.Ar context . +.Fn RMD160Final +is called when all data has been added via +.Fn RMD160Update +and stores a message digest in the +.Ar digest +parameter. +When a null pointer is passed to +.Fn RMD160Final +as first argument only the final padding will be applied and the +current context can still be used with +.Fn RMD160Update . +.Pp +The +.Fn RMD160Transform +function is used by +.Fn RMD160Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn RMD160Init , +.Fn RMD160Update +and +.Fn RMD160Final +instead of calling +.Fn RMD160Transform +directly. +.Pp +The +.Fn RMD160End +function is a front end for +.Fn RMD160Final +which converts the digest into an +.Tn ASCII +representation of the 160 bit digest in hexadecimal. +.Pp +The +.Fn RMD160File +function calculates the digest for a file and returns the result via +.Fn RMD160End . +If +.Fn RMD160File +is unable to open the file a NULL pointer is returned. +.Pp +The +.Fn RMD160Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn RMD160End . +.Pp +For each of the +.Fn RMD160End , +.Fn RMD160File , +and +.Fn RMD160Data +functions the +.Ar buf +parameter should either be a string of at least 41 characters in +size or a NULL pointer. +In the latter case, space will be dynamically allocated via +.Xr malloc 3 +and should be freed using +.Xr free 3 +when it is no longer needed. +.Sh EXAMPLES +The follow code fragment will calculate the digest for +the string "abc" which is ``0x8eb208f7e05d987a9b044a8e98c6b087f15a0bfc''. +.Bd -literal -offset indent +RMD160_CTX rmd; +u_char results[20]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +RMD160Init(&rmd); +RMD160Update(&rmd, (u_char *)buf, n); +RMD160Final(results, &rmd); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n < 20; n++) + printf("%02x", results[n]); +putchar('\en'); +.Ed +.Pp +Alternately, the helper functions could be used in the following way: +.Bd -literal -offset indent +RMD160_CTX rmd; +u_char output[41]; +char *buf = "abc"; + +printf("0x%s\en", RMD160Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr rmd160 1 , +.Xr md4 3 , +.Xr md5 3 , +.Xr sha1 3 +.Pp +.Rs +.%A H. Dobbertin, A. Bosselaers, B. Preneel +.%T RIPEMD-160, a strengthened version of RIPEMD +.Re +.Rs +.%T Information technology - Security techniques - Hash-functions - Part 3: Dedicated hash-functions +.%O ISO/IEC 10118-3 +.Re +.Rs +.%A H. Dobbertin, A. Bosselaers, B. Preneel +.%T The RIPEMD-160 cryptographic hash function +.%J Dr. Dobb's Journal +.%V Vol. 22, No. 1 +.%D January 1997 +.%P pp. 24-28 +.Re +.Sh HISTORY +The RMD-160 functions appeared in +.Ox 2.1 . +.Sh AUTHORS +This implementation of RMD-160 was written by Antoon Bosselaers. +.Pp +The +.Fn RMD160End , +.Fn RMD160File , +and +.Fn RMD160Data +helper functions are derived from code written by Poul-Henning Kamp. +.Sh BUGS +If a message digest is to be copied to a multi-byte type (ie: +an array of five 32-bit integers) it will be necessary to +perform byte swapping on little endian machines such as the i386, alpha, +and VAX. diff --git a/static/netbsd/man3/rmtops.3 b/static/netbsd/man3/rmtops.3 new file mode 100644 index 00000000..b1b77042 --- /dev/null +++ b/static/netbsd/man3/rmtops.3 @@ -0,0 +1,184 @@ +.\" $NetBSD: rmtops.3,v 1.17 2022/12/04 11:25:09 uwe Exp $ +.\" +.Dd October 16, 2001 +.Dt RMTOPS 3 +.Os +.Sh NAME +.Nm rmtops +.Nd access tape drives on remote machines +.Sh LIBRARY +Remote Magnetic Tape Library (librmt, -lrmt) +.Sh SYNOPSIS +.In rmt.h +.In sys/stat.h +.Ft int +.Fn isrmt "int fd" +.Ft int +.Fn rmtaccess "char *file" "int mode" +.Ft int +.Fn rmtclose "int fd" +.Ft int +.Fn rmtcreat "char *file" "int mode" +.Ft int +.Fn rmtdup "int fd" +.Ft int +.Fn rmtfcntl "int fd" "int cmd" "int arg" +.Ft int +.Fn rmtfstat "int fd" "struct stat *buf" +.Ft int +.Fn rmtioctl "int fd" "int request" "char *argp" +.Ft int +.Fn rmtisatty "int fd" +.Ft long +.Fn rmtlseek "int fd" "long offset" "int whence" +.Ft int +.Fn rmtlstat "char *file" "struct stat *buf" +.Ft int +.Fn rmtopen "char *file" "int flags" "int mode" +.Ft int +.Fn rmtread "int fd" "char *buf" "int nbytes" +.Ft int +.Fn rmtstat "char *file" "struct stat *buf" +.Ft int +.Fn rmtwrite "int fd" "char *buf" "int nbytes" +.Sh DESCRIPTION +The +.Nm +library provides a simple means of transparently accessing tape drives +on remote machines via +.Xr rsh 1 +and +.Xr rmt 8 . +These routines are used like their corresponding system calls, but +allow the user to open up a tape drive on a remote system on which he +or she has an account and the appropriate remote permissions. +.Pp +A remote tape drive file name has the form +.Dl [user@]hostname:/dev/??? +where +.Em system +is the remote system, +.Em /dev/??? +is the particular drive on the remote system (raw, blocked, rewinding, +non-rewinding, etc.), and the optional +.Em user +is the login name to be used on the remote system, if different from +the current user's login name. +.\" .Pp +.\" The library source code may be optionally compiled to recognize the +.\" old +.\" .Bx 4.2 , +.\" remote syntax +.\" .sp +.\" hostname[.user]:/dev/??? +.\" .sp +.\" By default, only the first form (introduced in +.\" .Bx 4.3 ) +.\" is recognized. +.Pp +For transparency, the user should include the file +.In rmt.h , +which has the following defines in it: +.Bd -literal +#define access rmtaccess +#define close rmtclose +#define creat rmtcreat +#define dup rmtdup +#define fcntl rmtfcntl +#define fstat rmtfstat +#define ioctl rmtioctl +#define isatty rmtisatty +#define lseek rmtlseek +#define lstat rmtlstat +#define open rmtopen +#define read rmtread +#define stat rmtstat +#define write rmtwrite +.Ed +.Pp +This allows the programmer to use +.Xr open 2 , +.Xr close 2 , +.Xr read 2 , +.Xr write 2 , +etc. in their normal fashion, with the +.Nm +routines taking care of differentiating between local and remote files. +This file should be included +.Em before +including the file +.Pa <sys/stat.h> , +since it redefines the identifier ``stat'' which is used to declare +objects of type +.Em "struct stat" . +.Pp +The routines differentiate between local and remote file descriptors +by adding a bias (currently 128) to the file descriptor of the pipe. +The programmer, if he or she must know if a file is remote, should use +.Fn isrmt . +.Sh ENVIRONMENT +The RCMD_CMD environment variable can be set to the name or pathname +of a program to use, instead of +.Pa /usr/bin/rsh , +and must have the same calling conventions as +.Xr rsh 1 . +.Sh FILES +.Bl -tag -width /usr/lib/librmt.a -compact +.It Pa /usr/lib/librmt.a +remote tape library +.El +.Sh RETURN VALUES +Several of these routines will return \-1 and set +.Va errno +to +.Er EOPNOTSUPP , +if they are given a remote file name or a file descriptor +on an open remote file (e.g., +.Fn rmtdup ) . +.Sh SEE ALSO +.Xr rcp 1 , +.Xr rsh 1 , +.Xr rmt 8 +.Pp +And the appropriate system calls in section 2. +.\" .Sh CONFIGURATION OPTIONS +.\" The library may be compiled to allow the use of +.\" .Bx 4.2 -style +.\" remote file names. This is not recommended. +.\" .Pp +.\" By default, the library opens two pipes to +.\" .Xr rsh 1 . +.\" It may optionally be compiled to use +.\" .Xr rexec 3 , +.\" instead. Doing so requires the use of a +.\" .Em .netrc +.\" file in the user's home directory, or that the application designer be +.\" willing to have +.\" .Xr rexec 3 +.\" prompt the user for a login name and password on the remote host. +.Sh AUTHORS +Jeff Lee wrote the original routines for accessing tape drives via +.Xr rmt 8 . +.Pp +Fred Fish redid them into a general purpose library. +.Pp +Arnold Robbins added the ability to specify a user name on the remote +system, the +.Pa <rmt.h> +include file, this man page, cleaned up the library a little, and made +the appropriate changes for +.Bx 4.3 . +.Pp +Dan Kegel contributed the code to use the +.Xr rexec 3 +library routine. +.Sh BUGS +There is no way to use remote tape drives with +.Xr stdio 3 , +short of recompiling it entirely to use these routines. +.Pp +The +.Xr rmt 8 +protocol is not very capable. +In particular, it relies on TCP/IP sockets for error +free transmission, and does no data validation of its own. diff --git a/static/netbsd/man3/round.3 b/static/netbsd/man3/round.3 new file mode 100644 index 00000000..a3c07fc1 --- /dev/null +++ b/static/netbsd/man3/round.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: round.3,v 1.7 2013/11/12 00:10:29 joerg Exp $ +.\" +.\" Copyright (c) 2003, Steven G. Kargl +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/msun/man/round.3,v 1.2 2004/06/20 09:27:17 das Exp $ +.\" +.Dd November 12, 2013 +.Dt ROUND 3 +.Os +.Sh NAME +.Nm round , +.Nm roundf , +.Nm roundl +.Nd round to nearest integral value +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn round "double x" +.Ft float +.Fn roundf "float x" +.Ft long double +.Fn roundl "long double x" +.Sh DESCRIPTION +The +.Fn round , +.Fn roundf , +and +.Fn roundl +functions return the nearest integral value to +.Fa x ; +if +.Fa x +lies halfway between two integral values, then these +functions return the integral value with the larger +absolute value (i.e., they round away from zero). +.Sh SEE ALSO +.Xr ceil 3 , +.Xr floor 3 , +.Xr math 3 , +.Xr rint 3 , +.Xr trunc 3 +.Sh STANDARDS +The +.Fn round +and +.Fn roundf +functions conform to +.St -isoC-99 . +.Sh HISTORY +The +.Fn round +and +.Fn roundf +functions appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/rpc.3 b/static/netbsd/man3/rpc.3 new file mode 100644 index 00000000..b5027ec3 --- /dev/null +++ b/static/netbsd/man3/rpc.3 @@ -0,0 +1,416 @@ +.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" $NetBSD: rpc.3,v 1.25 2017/07/03 21:32:49 wiz Exp $ +.Dd May 7, 1993 +.Dt RPC 3 +.Os +.Sh NAME +.Nm rpc +.Nd library routines for remote procedure calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.In netconfig.h +.Sh DESCRIPTION +These +routines allow C language programs to make procedure +calls on other machines across a network. +First, the client sends a request to the server. +On receipt of the request, the server calls a dispatch routine +to perform the requested service, and then sends back a reply. +.Pp +All +RPC routines require the header +.In rpc/rpc.h . +Routines that take a +.Fa netconfig +structure also require that +.In netconfig.h +be included. +.Ss Nettype +Some of the high-level +RPC interface routines take a +.Fa nettype +string as one of the parameters +(for example, +.Fn clnt_create , +.Fn svc_create , +.Fn rpc_reg , +.Fn rpc_call . +This string defines a class of transports which can be used +for a particular application. +.Pp +.Fa nettype +can be one of the following: +.Bl -tag -width datagram_v +.It netpath +Choose from the transports which have been +indicated by their token names in the +.Ev NETPATH +environment variable. +If +.Ev NETPATH +is unset or +.Dv NULL +, it defaults to +.Fa visible . +.Fa netpath +is the default +.Fa nettype . +.It visible +Choose the transports which have the visible flag (v) +set in the +.Pa /etc/netconfig +file. +.It circuit_v +This is same as +.Fa visible +except that it chooses only the connection oriented transports +(semantics +.Fa tpi_cots +or +.Fa tpi_cots_ord ) +from the entries in the +.Pa /etc/netconfig +file. +.It datagram_v +This is same as +.Fa visible +except that it chooses only the connectionless datagram transports +(semantics +.Fa tpi_clts ) +from the entries in the +.Pa /etc/netconfig +file. +.It circuit_n +This is same as +.Fa netpath +except that it chooses only the connection oriented datagram transports +(semantics +.Fa tpi_cots +or +.Fa tpi_cots_ord ) . +.It datagram_n +This is same as +.Fa netpath +except that it chooses only the connectionless datagram transports +(semantics +.Fa tpi_clts ) . +.It udp +This refers to Internet UDP, both version 4 and 6. +.It tcp +This refers to Internet TCP, both version 4 and 6. +.El +.Pp +If +.Fa nettype +is +.Dv NULL , +it defaults to +.Fa netpath . +The transports are tried in left to right order in the +.Ev NETPATH +variable or in top to down order in the +.Pa /etc/netconfig +file. +.Ss Derived Types +The derived types used in the RPC interfaces are defined as follows: +.Bd -literal + typedef uint32_t rpcprog_t; + typedef uint32_t rpcvers_t; + typedef uint32_t rpcproc_t; + typedef uint32_t rpcprot_t; + typedef uint32_t rpcport_t; + typedef int32_t rpc_inline_t; +.Ed +.Ss Data Structures +Some of the data structures used by the +RPC package are shown below. +.Ss The AUTH Structure +.Bd -literal +/* + * Authentication info. Opaque to client. + */ +struct opaque_auth { + enum_t oa_flavor; /* flavor of auth */ + caddr_t oa_base; /* address of more auth stuff */ + u_int oa_length; /* not to exceed MAX_AUTH_BYTES */ +}; + +/* + * Auth handle, interface to client side authenticators. + */ +typedef struct { + struct opaque_auth ah_cred; + struct opaque_auth ah_verf; + struct auth_ops { + void (*ah_nextverf)(\|); + int (*ah_marshal)(\|); /* nextverf & serialize */ + int (*ah_validate)(\|); /* validate verifier */ + int (*ah_refresh)(\|); /* refresh credentials */ + void (*ah_destroy)(\|); /* destroy this structure */ + } *ah_ops; + caddr_t ah_private; +} AUTH; +.Ed +.Ss The CLIENT Structure +.Bd -literal +/* + * Client rpc handle. + * Created by individual implementations. + * Client is responsible for initializing auth. + */ + +typedef struct { + AUTH *cl_auth; /* authenticator */ + struct clnt_ops { + enum clnt_stat (*cl_call)(); /* call remote procedure */ + void (*cl_abort)(); /* abort a call */ + void (*cl_geterr)(); /* get specific error code */ + bool_t (*cl_freeres)(); /* frees results */ + void (*cl_destroy)(); /* destroy this structure */ + bool_t (*cl_control)(); /* the ioctl() of rpc */ + } *cl_ops; + caddr_t cl_private; /* private stuff */ + char *cl_netid; /* network identifier */ + char *cl_tp; /* device name */ +} CLIENT; +.Ed +.Ss The SVCXPRT structure +.Bd -literal +enum xprt_stat { + XPRT_DIED, + XPRT_MOREREQS, + XPRT_IDLE +}; + +/* + * Server side transport handle + */ +typedef struct { + int xp_fd; /* file descriptor for the server handle */ + u_short xp_port; /* obsolete */ + const struct xp_ops { + bool_t (*xp_recv)(); /* receive incoming requests */ + enum xprt_stat (*xp_stat)(); /* get transport status */ + bool_t (*xp_getargs)(); /* get arguments */ + bool_t (*xp_reply)(); /* send reply */ + bool_t (*xp_freeargs)(); /* free mem allocated for args */ + void (*xp_destroy)(); /* destroy this struct */ + } *xp_ops; + int xp_addrlen; /* length of remote addr. Obsolete */ + struct sockaddr_in xp_raddr; /* Obsolete */ + const struct xp_ops2 { + bool_t (*xp_control)(); /* catch-all function */ + } *xp_ops2; + char *xp_tp; /* transport provider device name */ + char *xp_netid; /* network identifier */ + struct netbuf xp_ltaddr; /* local transport address */ + struct netbuf xp_rtaddr; /* remote transport address */ + struct opaque_auth xp_verf; /* raw response verifier */ + caddr_t xp_p1; /* private: for use by svc ops */ + caddr_t xp_p2; /* private: for use by svc ops */ + caddr_t xp_p3; /* private: for use by svc lib */ + int xp_type /* transport type */ +} SVCXPRT; +.Ed +.Ss The svc_req structure +.Bd -literal +struct svc_req { + rpcprog_t rq_prog; /* service program number */ + rpcvers_t rq_vers; /* service protocol version */ + rpcproc_t rq_proc; /* the desired procedure */ + struct opaque_auth rq_cred; /* raw creds from the wire */ + caddr_t rq_clntcred; /* read only cooked cred */ + SVCXPRT *rq_xprt; /* associated transport */ +}; +.Ed +.Ss The XDR structure +.Bd -literal +/* + * XDR operations. + * XDR_ENCODE causes the type to be encoded into the stream. + * XDR_DECODE causes the type to be extracted from the stream. + * XDR_FREE can be used to release the space allocated by an XDR_DECODE + * request. + */ +enum xdr_op { + XDR_ENCODE=0, + XDR_DECODE=1, + XDR_FREE=2 +}; +/* + * This is the number of bytes per unit of external data. + */ +#define BYTES_PER_XDR_UNIT (4) +#define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) / + BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT) + +/* + * A xdrproc_t exists for each data type which is to be encoded or + * decoded. The second argument to the xdrproc_t is a pointer to + * an opaque pointer. The opaque pointer generally points to a + * structure of the data type to be decoded. If this points to 0, + * then the type routines should allocate dynamic storage of the + * appropriate size and return it. + */ +typedef bool_t (*xdrproc_t)(XDR *, const void *); + +/* + * The XDR handle. + * Contains operation which is being applied to the stream, + * an operations vector for the particular implementation + */ +typedef struct { + enum xdr_op x_op; /* operation; fast additional param */ + struct xdr_ops { + bool_t (*x_getlong)(); /* get a long from underlying stream */ + bool_t (*x_putlong)(); /* put a long to underlying stream */ + bool_t (*x_getbytes)(); /* get bytes from underlying stream */ + bool_t (*x_putbytes)(); /* put bytes to underlying stream */ + u_int (*x_getpostn)(); /* returns bytes off from beginning */ + bool_t (*x_setpostn)(); /* lets you reposition the stream */ + long * (*x_inline)(); /* buf quick ptr to buffered data */ + void (*x_destroy)(); /* free privates of this xdr_stream */ + } *x_ops; + caddr_t x_public; /* users' data */ + caddr_t x_private; /* pointer to private data */ + caddr_t x_base; /* private used for position info */ + int x_handy; /* extra private word */ +} XDR; + +/* + * The netbuf structure. This structure is defined in <xti.h> on SysV + * systems, but NetBSD does not use XTI. + * + * Usually, buf will point to a struct sockaddr, and len and maxlen + * will contain the length and maximum length of that socket address, + * respectively. + */ +struct netbuf { + unsigned int maxlen; + unsigned int len; + void *buf; +}; + +/* + * The format of the address and options arguments of the XTI t_bind call. + * Only provided for compatibility, it should not be used other than + * as an argument to svc_tli_create(). + */ + +struct t_bind { + struct netbuf addr; + unsigned int qlen; +}; +.Ed +.Ss Index to Routines +The following table lists RPC routines and the manual reference +pages on which they are described: +.Bl -column "authunix_create_default()" "rpc_clnt_create(3)" +.It Em "RPC Routine" Ta Em "Manual Reference Page" +.Pp +.It Fn auth_destroy Ta Xr rpc_clnt_auth 3 +.It Fn authdes_create Ta Xr rpc_soc 3 +.It Fn authnone_create Ta Xr rpc_clnt_auth 3 +.It Fn authsys_create Ta Xr rpc_clnt_auth 3 +.It Fn authsys_create_default Ta Xr rpc_clnt_auth 3 +.It Fn authunix_create Ta Xr rpc_soc 3 +.It Fn authunix_create_default Ta Xr rpc_soc 3 +.It Fn callrpc Ta Xr rpc_soc 3 +.It Fn clnt_broadcast Ta Xr rpc_soc 3 +.It Fn clnt_call Ta Xr rpc_clnt_calls 3 +.It Fn clnt_control Ta Xr rpc_clnt_create 3 +.It Fn clnt_create Ta Xr rpc_clnt_create 3 +.It Fn clnt_destroy Ta Xr rpc_clnt_create 3 +.It Fn clnt_dg_create Ta Xr rpc_clnt_create 3 +.It Fn clnt_freeres Ta Xr rpc_clnt_calls 3 +.It Fn clnt_geterr Ta Xr rpc_clnt_calls 3 +.It Fn clnt_pcreateerror Ta Xr rpc_clnt_create 3 +.It Fn clnt_perrno Ta Xr rpc_clnt_calls 3 +.It Fn clnt_perror Ta Xr rpc_clnt_calls 3 +.It Fn clnt_raw_create Ta Xr rpc_clnt_create 3 +.It Fn clnt_spcreateerror Ta Xr rpc_clnt_create 3 +.It Fn clnt_sperrno Ta Xr rpc_clnt_calls 3 +.It Fn clnt_sperror Ta Xr rpc_clnt_calls 3 +.It Fn clnt_tli_create Ta Xr rpc_clnt_create 3 +.It Fn clnt_tp_create Ta Xr rpc_clnt_create 3 +.It Fn clnt_udpcreate Ta Xr rpc_soc 3 +.It Fn clnt_vc_create Ta Xr rpc_clnt_create 3 +.It Fn clntraw_create Ta Xr rpc_soc 3 +.It Fn clnttcp_create Ta Xr rpc_soc 3 +.It Fn clntudp_bufcreate Ta Xr rpc_soc 3 +.It Fn get_myaddress Ta Xr rpc_soc 3 +.It Fn pmap_getmaps Ta Xr rpc_soc 3 +.It Fn pmap_getport Ta Xr rpc_soc 3 +.It Fn pmap_rmtcall Ta Xr rpc_soc 3 +.It Fn pmap_set Ta Xr rpc_soc 3 +.It Fn pmap_unset Ta Xr rpc_soc 3 +.It Fn registerrpc Ta Xr rpc_soc 3 +.It Fn rpc_broadcast Ta Xr rpc_clnt_calls 3 +.It Fn rpc_broadcast_exp Ta Xr rpc_clnt_calls 3 +.It Fn rpc_call Ta Xr rpc_clnt_calls 3 +.It Fn rpc_reg Ta Xr rpc_svc_calls 3 +.It Fn svc_create Ta Xr rpc_svc_create 3 +.It Fn svc_destroy Ta Xr rpc_svc_create 3 +.It Fn svc_dg_create Ta Xr rpc_svc_create 3 +.It Fn svc_dg_enablecache Ta Xr rpc_svc_calls 3 +.It Fn svc_fd_create Ta Xr rpc_svc_create 3 +.It Fn svc_fds Ta Xr rpc_soc 3 +.It Fn svc_freeargs Ta Xr rpc_svc_reg 3 +.It Fn svc_getargs Ta Xr rpc_svc_reg 3 +.It Fn svc_getcaller Ta Xr rpc_soc 3 +.It Fn svc_getreq Ta Xr rpc_soc 3 +.It Fn svc_getreqset Ta Xr rpc_svc_calls 3 +.It Fn svc_getrpccaller Ta Xr rpc_svc_calls 3 +.It Fn svc_kerb_reg Ta Xr kerberos_rpc 3 +.It Fn svc_raw_create Ta Xr rpc_svc_create 3 +.It Fn svc_reg Ta Xr rpc_svc_calls 3 +.It Fn svc_register Ta Xr rpc_soc 3 +.It Fn svc_run Ta Xr rpc_svc_reg 3 +.It Fn svc_sendreply Ta Xr rpc_svc_reg 3 +.It Fn svc_tli_create Ta Xr rpc_svc_create 3 +.It Fn svc_tp_create Ta Xr rpc_svc_create 3 +.It Fn svc_unreg Ta Xr rpc_svc_calls 3 +.It Fn svc_unregister Ta Xr rpc_soc 3 +.It Fn svc_vc_create Ta Xr rpc_svc_create 3 +.It Fn svcerr_auth Ta Xr rpc_svc_err 3 +.It Fn svcerr_decode Ta Xr rpc_svc_err 3 +.It Fn svcerr_noproc Ta Xr rpc_svc_err 3 +.It Fn svcerr_noprog Ta Xr rpc_svc_err 3 +.It Fn svcerr_progvers Ta Xr rpc_svc_err 3 +.It Fn svcerr_systemerr Ta Xr rpc_svc_err 3 +.It Fn svcerr_weakauth Ta Xr rpc_svc_err 3 +.It Fn svcfd_create Ta Xr rpc_soc 3 +.It Fn svcraw_create Ta Xr rpc_soc 3 +.It Fn svctcp_create Ta Xr rpc_soc 3 +.It Fn svcudp_bufcreate Ta Xr rpc_soc 3 +.It Fn svcudp_create Ta Xr rpc_soc 3 +.It Fn xdr_accepted_reply Ta Xr rpc_xdr 3 +.It Fn xdr_authsys_parms Ta Xr rpc_xdr 3 +.It Fn xdr_authunix_parms Ta Xr rpc_soc 3 +.It Fn xdr_callhdr Ta Xr rpc_xdr 3 +.It Fn xdr_callmsg Ta Xr rpc_xdr 3 +.It Fn xdr_opaque_auth Ta Xr rpc_xdr 3 +.It Fn xdr_rejected_reply Ta Xr rpc_xdr 3 +.It Fn xdr_replymsg Ta Xr rpc_xdr 3 +.It Fn xprt_register Ta Xr rpc_svc_calls 3 +.It Fn xprt_unregister Ta Xr rpc_svc_calls 3 +.El +.Sh FILES +.Pa /etc/netconfig +.Sh SEE ALSO +.Xr getnetconfig 3 , +.Xr getnetpath 3 , +.Xr rpc_clnt_auth 3 , +.Xr rpc_clnt_calls 3 , +.Xr rpc_clnt_create 3 , +.Xr rpc_svc_calls 3 , +.Xr rpc_svc_create 3 , +.Xr rpc_svc_err 3 , +.Xr rpc_svc_reg 3 , +.Xr rpc_xdr 3 , +.Xr rpcbind 3 , +.Xr xdr 3 , +.Xr netconfig 5 diff --git a/static/netbsd/man3/rpc.h.3 b/static/netbsd/man3/rpc.h.3 new file mode 100644 index 00000000..42d8ffb0 --- /dev/null +++ b/static/netbsd/man3/rpc.h.3 @@ -0,0 +1,893 @@ +.TH "event2/rpc.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/rpc.h \- This header files provides basic support for an RPC server and client\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVRPC_GENERATE\fP(rpcname, reqstruct, rplystruct)" +.br +.RI "\fIGenerates the code for receiving and sending an RPC message\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_HEADER\fP(rpcname, reqstruct, rplystruct)" +.br +.RI "\fICreates the definitions and prototypes for an RPC\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_MAKE_CTX\fP(rpcname, reqstruct, rplystruct, pool, request, reply, cb, cbarg)" +.br +.RI "\fICreates a context structure that contains rpc specific information\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_MAKE_REQUEST\fP(name, pool, request, reply, cb, cbarg) evrpc_send_request_##name((pool), (request), (reply), (cb), (cbarg))" +.br +.RI "\fIlaunches an RPC and sends it to the server \fP" +.ti -1c +.RI "#define \fBEVRPC_REGISTER\fP(base, name, request, reply, callback, cbarg)" +.br +.RI "\fIregister RPCs with the HTTP Server \fP" +.ti -1c +.RI "#define \fBEVRPC_REQUEST_DONE\fP(rpc_req)" +.br +.RI "\fICreates the reply to an RPC request\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_REQUEST_HTTP\fP(rpc_req) (rpc_req)\->http_req" +.br +.RI "\fIProvides access to the HTTP request object underlying an RPC\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_STRUCT\fP(rpcname) struct evrpc_req__##rpcname" +.br +.RI "\fIThe type of a specific RPC Message\&. \fP" +.ti -1c +.RI "#define \fBEVRPC_UNREGISTER\fP(base, name) evrpc_unregister_rpc((base), #name)" +.br +.RI "\fIUnregisters an already registered RPC\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ARRAY_ADD\fP(msg, member) (*(msg)\->base\->member##_add)(msg)" +.br +.RI "\fIAllocates a new entry in the array and returns it\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ARRAY_ADD_VALUE\fP(msg, member, value) (*(msg)\->base\->member##_add)((msg), (value))" +.br +.RI "\fIAdds a value to an array\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ARRAY_GET\fP(msg, member, offset, pvalue) (*(msg)\->base\->member##_get)((msg), (offset), (pvalue))" +.br +.RI "\fIGets a variable at the specified offset from the array\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ARRAY_LEN\fP(msg, member) ((msg)\->member##_length)" +.br +.RI "\fIReturns the number of entries in the array\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ASSIGN\fP(msg, member, value) (*(msg)\->base\->member##_assign)((msg), (value))" +.br +.RI "\fIAssigns a value to the member in the message\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_ASSIGN_WITH_LEN\fP(msg, member, value, len) (*(msg)\->base\->member##_assign)((msg), (value), (len))" +.br +.RI "\fIAssigns a value to the member in the message\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_GET\fP(msg, member, pvalue) (*(msg)\->base\->member##_get)((msg), (pvalue))" +.br +.RI "\fIReturns the value for a member\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_GET_WITH_LEN\fP(msg, member, pvalue, plen) (*(msg)\->base\->member##_get)((msg), (pvalue), (plen))" +.br +.RI "\fIReturns the value for a member\&. \fP" +.ti -1c +.RI "#define \fBEVTAG_HAS\fP(msg, member) ((msg)\->member##_set == 1)" +.br +.RI "\fIDetermines if the member has been set in the message\&. \fP" +.ti -1c +.RI "#define \fBINPUT\fP \fBEVRPC_INPUT\fP" +.br +.RI "\fIDeprecated alias for EVRPC_INPUT\&. \fP" +.ti -1c +.RI "#define \fBOUTPUT\fP \fBEVRPC_OUTPUT\fP" +.br +.RI "\fIDeprecated alias for EVRPC_OUTPUT\&. \fP" +.in -1c +.SS "Enumerations" + +.in +1c +.ti -1c +.RI "enum \fBEVRPC_HOOK_RESULT\fP { \fBEVRPC_TERMINATE\fP = -1, \fBEVRPC_CONTINUE\fP = 0, \fBEVRPC_PAUSE\fP = 1 } +.RI "\fIReturn value from hook processing functions\&. \fP"" +.br +.ti -1c +.RI "enum \fBEVRPC_HOOK_TYPE\fP { \fBEVRPC_INPUT\fP, \fBEVRPC_OUTPUT\fP } +.RI "\fIHooks for changing the input and output of RPCs; this can be used to implement compression, authentication, encryption, \&.\&.\&. \fP"" +.br +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "void * \fBevrpc_add_hook\fP (void *vbase, enum \fBEVRPC_HOOK_TYPE\fP hook_type, int(*cb)(void *, struct evhttp_request *, struct \fBevbuffer\fP *, void *), void *cb_arg)" +.br +.RI "\fIadds a processing hook to either an rpc base or rpc pool \fP" +.ti -1c +.RI "void \fBevrpc_free\fP (struct evrpc_base *base)" +.br +.RI "\fIFrees the evrpc base\&. \fP" +.ti -1c +.RI "void * \fBevrpc_get_reply\fP (struct evrpc_req_generic *req)" +.br +.ti -1c +.RI "void * \fBevrpc_get_request\fP (struct evrpc_req_generic *req)" +.br +.RI "\fIaccessors for request and reply \fP" +.ti -1c +.RI "void \fBevrpc_hook_add_meta\fP (void *ctx, const char *key, const void *data, size_t data_size)" +.br +.RI "\fIadds meta data to request \fP" +.ti -1c +.RI "int \fBevrpc_hook_find_meta\fP (void *ctx, const char *key, void **data, size_t *data_size)" +.br +.RI "\fIretrieves meta data previously associated \fP" +.ti -1c +.RI "struct evhttp_connection * \fBevrpc_hook_get_connection\fP (void *ctx)" +.br +.RI "\fIreturns the connection object associated with the request \fP" +.ti -1c +.RI "struct evrpc_base * \fBevrpc_init\fP (struct evhttp *server)" +.br +.RI "\fICreates a new rpc base from which RPC requests can be received\&. \fP" +.ti -1c +.RI "int \fBevrpc_make_request\fP (struct evrpc_request_wrapper *ctx)" +.br +.RI "\fIMakes an RPC request based on the provided context\&. \fP" +.ti -1c +.RI "struct evrpc_request_wrapper * \fBevrpc_make_request_ctx\fP (struct evrpc_pool *pool, void *request, void *reply, const char *rpcname, void(*req_marshal)(struct \fBevbuffer\fP *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct \fBevbuffer\fP *), void(*cb)(struct evrpc_status *, void *, void *, void *), void *cbarg)" +.br +.RI "\fIuse EVRPC_GENERATE instead \fP" +.ti -1c +.RI "void \fBevrpc_pool_add_connection\fP (struct evrpc_pool *pool, struct evhttp_connection *evcon)" +.br +.RI "\fIAdds a connection over which rpc can be dispatched to the pool\&. \fP" +.ti -1c +.RI "void \fBevrpc_pool_free\fP (struct evrpc_pool *pool)" +.br +.RI "\fIfrees an rpc connection pool \fP" +.ti -1c +.RI "struct evrpc_pool * \fBevrpc_pool_new\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fIcreates an rpc connection pool \fP" +.ti -1c +.RI "void \fBevrpc_pool_remove_connection\fP (struct evrpc_pool *pool, struct evhttp_connection *evcon)" +.br +.RI "\fIRemoves a connection from the pool\&. \fP" +.ti -1c +.RI "void \fBevrpc_pool_set_timeout\fP (struct evrpc_pool *pool, int timeout_in_secs)" +.br +.RI "\fISets the timeout in secs after which a request has to complete\&. \fP" +.ti -1c +.RI "int \fBevrpc_register_generic\fP (struct evrpc_base *base, const char *name, void(*callback)(struct evrpc_req_generic *, void *), void *cbarg, void *(*req_new)(void *), void *req_new_arg, void(*req_free)(void *), int(*req_unmarshal)(void *, struct \fBevbuffer\fP *), void *(*rpl_new)(void *), void *rpl_new_arg, void(*rpl_free)(void *), int(*rpl_complete)(void *), void(*rpl_marshal)(struct \fBevbuffer\fP *, void *))" +.br +.RI "\fIFunction for registering a generic RPC with the RPC base\&. \fP" +.ti -1c +.RI "int \fBevrpc_register_rpc\fP (struct evrpc_base *, struct evrpc *, void(*)(struct evrpc_req_generic *, void *), void *)" +.br +.RI "\fILow level function for registering an RPC with a server\&. \fP" +.ti -1c +.RI "int \fBevrpc_remove_hook\fP (void *vbase, enum \fBEVRPC_HOOK_TYPE\fP hook_type, void *handle)" +.br +.RI "\fIremoves a previously added hook \fP" +.ti -1c +.RI "void \fBevrpc_request_done\fP (struct evrpc_req_generic *req)" +.br +.RI "\fIcompletes the server response to an rpc request \fP" +.ti -1c +.RI "struct evrpc_pool * \fBevrpc_request_get_pool\fP (struct evrpc_request_wrapper *ctx)" +.br +.RI "\fIaccessors for obscure and undocumented functionality \fP" +.ti -1c +.RI "void \fBevrpc_request_set_cb\fP (struct evrpc_request_wrapper *ctx, void(*cb)(struct evrpc_status *, void *request, void *reply, void *arg), void *cb_arg)" +.br +.ti -1c +.RI "void \fBevrpc_request_set_pool\fP (struct evrpc_request_wrapper *ctx, struct evrpc_pool *pool)" +.br +.ti -1c +.RI "int \fBevrpc_resume_request\fP (void *vbase, void *ctx, enum \fBEVRPC_HOOK_RESULT\fP res)" +.br +.RI "\fIresume a paused request \fP" +.ti -1c +.RI "int \fBevrpc_send_request_generic\fP (struct evrpc_pool *pool, void *request, void *reply, void(*cb)(struct evrpc_status *, void *, void *, void *), void *cb_arg, const char *rpcname, void(*req_marshal)(struct \fBevbuffer\fP *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct \fBevbuffer\fP *))" +.br +.RI "\fIFunction for sending a generic RPC request\&. \fP" +.ti -1c +.RI "int \fBevrpc_unregister_rpc\fP (struct evrpc_base *base, const char *name)" +.br +.in -1c +.SH "Detailed Description" +.PP +This header files provides basic support for an RPC server and client\&. + +To support RPCs in a server, every supported RPC command needs to be defined and registered\&. +.PP +\fBEVRPC_HEADER(SendCommand, Request, Reply)\fP; +.PP +SendCommand is the name of the RPC command\&. Request is the name of a structure generated by event_rpcgen\&.py\&. It contains all parameters relating to the SendCommand RPC\&. The server needs to fill in the Reply structure\&. Reply is the name of a structure generated by event_rpcgen\&.py\&. It contains the answer to the RPC\&. +.PP +To register an RPC with an HTTP server, you need to first create an RPC base with: +.PP +struct evrpc_base *base = evrpc_init(http); +.PP +A specific RPC can then be registered with +.PP +\fBEVRPC_REGISTER(base, SendCommand, Request, Reply, FunctionCB, arg)\fP; +.PP +when the server receives an appropriately formatted RPC, the user callback is invoked\&. The callback needs to fill in the reply structure\&. +.PP +void FunctionCB(EVRPC_STRUCT(SendCommand)* rpc, void *arg); +.PP +To send the reply, call \fBEVRPC_REQUEST_DONE(rpc)\fP; +.PP +See the regression test for an example\&. +.SH "Macro Definition Documentation" +.PP +.SS "#define EVRPC_GENERATE(rpcname, reqstruct, rplystruct)" +\fBValue:\fP +.PP +.nf +int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \ + struct reqstruct *request, struct rplystruct *reply, \ + void (*cb)(struct evrpc_status *, \ + struct reqstruct *, struct rplystruct *, void *cbarg), \ + void *cbarg) { \ + return evrpc_send_request_generic(pool, request, reply, \ + (void (*)(struct evrpc_status *, void *, void *, void *))cb, \ + cbarg, \ + #rpcname, \ + (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \ + (void (*)(void *))rplystruct##_clear, \ + (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal); \ +} +.fi +.PP +Generates the code for receiving and sending an RPC message\&. EVRPC_GENERATE is used to create the code corresponding to sending and receiving a particular RPC message +.PP +\fBParameters:\fP +.RS 4 +\fIrpcname\fP the name of the RPC +.br +\fIreqstruct\fP the name of the RPC request structure +.br +\fIreplystruct\fP the name of the RPC reply structure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_HEADER()\fP +.RE +.PP + +.SS "#define EVRPC_HEADER(rpcname, reqstruct, rplystruct)" +\fBValue:\fP +.PP +.nf +EVRPC_STRUCT(rpcname) { \ + struct evrpc_hook_meta *hook_meta; \ + struct reqstruct* request; \ + struct rplystruct* reply; \ + struct evrpc* rpc; \ + struct evhttp_request* http_req; \ + struct evbuffer* rpc_data; \ +}; \ +int evrpc_send_request_##rpcname(struct evrpc_pool *, \ + struct reqstruct *, struct rplystruct *, \ + void (*)(struct evrpc_status *, \ + struct reqstruct *, struct rplystruct *, void *cbarg), \ + void *); +.fi +.PP +Creates the definitions and prototypes for an RPC\&. You need to use EVRPC_HEADER to create structures and function prototypes needed by the server and client implementation\&. The structures have to be defined in an \&.rpc file and converted to source code via event_rpcgen\&.py +.PP +\fBParameters:\fP +.RS 4 +\fIrpcname\fP the name of the RPC +.br +\fIreqstruct\fP the name of the RPC request structure +.br +\fIreplystruct\fP the name of the RPC reply structure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_GENERATE()\fP +.RE +.PP + +.SS "#define EVRPC_MAKE_CTX(rpcname, reqstruct, rplystruct, pool, request, reply, cb, cbarg)" +\fBValue:\fP +.PP +.nf +evrpc_make_request_ctx(pool, request, reply, \ + #rpcname, \ + (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \ + (void (*)(void *))rplystruct##_clear, \ + (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal, \ + (void (*)(struct evrpc_status *, void *, void *, void *))cb, \ + cbarg) +.fi +.PP +Creates a context structure that contains rpc specific information\&. EVRPC_MAKE_CTX is used to populate a RPC specific context that contains information about marshaling the RPC data types\&. +.PP +\fBParameters:\fP +.RS 4 +\fIrpcname\fP the name of the RPC +.br +\fIreqstruct\fP the name of the RPC request structure +.br +\fIreplystruct\fP the name of the RPC reply structure +.br +\fIpool\fP the evrpc_pool over which to make the request +.br +\fIrequest\fP a pointer to the RPC request structure object +.br +\fIreply\fP a pointer to the RPC reply structure object +.br +\fIcb\fP the callback function to call when the RPC has completed +.br +\fIcbarg\fP the argument to supply to the callback +.RE +.PP + +.SS "#define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) evrpc_send_request_##name((pool), (request), (reply), (cb), (cbarg))" + +.PP +launches an RPC and sends it to the server \fBEVRPC_MAKE_REQUEST()\fP is used by the client to send an RPC to the server\&. +.PP +\fBParameters:\fP +.RS 4 +\fIname\fP the name of the RPC +.br +\fIpool\fP the evrpc_pool that contains the connection objects over which the request should be sent\&. +.br +\fIrequest\fP a pointer to the RPC request structure - it contains the data to be sent to the server\&. +.br +\fIreply\fP a pointer to the RPC reply structure\&. It is going to be filled if the request was answered successfully +.br +\fIcb\fP the callback to invoke when the RPC request has been answered +.br +\fIcbarg\fP an additional argument to be passed to the client +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "#define EVRPC_REGISTER(base, name, request, reply, callback, cbarg)" +\fBValue:\fP +.PP +.nf +evrpc_register_generic(base, #name, \ + (void (*)(struct evrpc_req_generic *, void *))callback, cbarg, \ + (void *(*)(void *))request##_new, NULL, \ + (void (*)(void *))request##_free, \ + (int (*)(void *, struct evbuffer *))request##_unmarshal, \ + (void *(*)(void *))reply##_new, NULL, \ + (void (*)(void *))reply##_free, \ + (int (*)(void *))reply##_complete, \ + (void (*)(struct evbuffer *, void *))reply##_marshal) +.fi +.PP +register RPCs with the HTTP Server registers a new RPC with the HTTP server, each RPC needs to have a unique name under which it can be identified\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evrpc_base structure in which the RPC should be registered\&. +.br +\fIname\fP the name of the RPC +.br +\fIrequest\fP the name of the RPC request structure +.br +\fIreply\fP the name of the RPC reply structure +.br +\fIcallback\fP the callback that should be invoked when the RPC is received\&. The callback has the following prototype void (\fIcallback)(\fBEVRPC_STRUCT(Message)\fP\fP rpc, void *arg) +.br +\fIcbarg\fP an additional parameter that can be passed to the callback\&. The parameter can be used to carry around state\&. +.RE +.PP + +.SS "#define EVRPC_REQUEST_DONE(rpc_req)" +\fBValue:\fP +.PP +.nf +do { \ + struct evrpc_req_generic *req_ = (struct evrpc_req_generic *)(rpc_req); \\ + evrpc_request_done(req_); \ +} while (0) +.fi +.PP +Creates the reply to an RPC request\&. EVRPC_REQUEST_DONE is used to answer a request; the reply is expected to have been filled in\&. The request and reply pointers become invalid after this call has finished\&. +.PP +\fBParameters:\fP +.RS 4 +\fIrpc_req\fP the rpc request structure provided to the server callback +.RE +.PP + +.SS "#define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)\->http_req" + +.PP +Provides access to the HTTP request object underlying an RPC\&. Access to the underlying http object; can be used to look at headers or for getting the remote ip address +.PP +\fBParameters:\fP +.RS 4 +\fIrpc_req\fP the rpc request structure provided to the server callback +.RE +.PP +\fBReturns:\fP +.RS 4 +an struct evhttp_request object that can be inspected for HTTP headers or sender information\&. +.RE +.PP + +.SS "#define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname" + +.PP +The type of a specific RPC Message\&. +.PP +\fBParameters:\fP +.RS 4 +\fIrpcname\fP the name of the RPC message +.RE +.PP + +.SS "#define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc((base), #name)" + +.PP +Unregisters an already registered RPC\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evrpc_base object from which to unregister an RPC +.br +\fIname\fP the name of the rpc to unregister +.RE +.PP +\fBReturns:\fP +.RS 4 +-1 on error or 0 when successful\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_REGISTER()\fP +.RE +.PP + +.SS "#define EVTAG_ASSIGN(msg, member, value) (*(msg)\->base\->member##_assign)((msg), (value))" + +.PP +Assigns a value to the member in the message\&. +.PP +\fBParameters:\fP +.RS 4 +\fImsg\fP the message to which to assign a value +.br +\fImember\fP the name of the member variable +.br +\fIvalue\fP the value to assign +.RE +.PP + +.SS "#define EVTAG_ASSIGN_WITH_LEN(msg, member, value, len) (*(msg)\->base\->member##_assign)((msg), (value), (len))" + +.PP +Assigns a value to the member in the message\&. +.PP +\fBParameters:\fP +.RS 4 +\fImsg\fP the message to which to assign a value +.br +\fImember\fP the name of the member variable +.br +\fIvalue\fP the value to assign +.br +\fIlen\fP the length of the value +.RE +.PP + +.SS "#define EVTAG_GET(msg, member, pvalue) (*(msg)\->base\->member##_get)((msg), (pvalue))" + +.PP +Returns the value for a member\&. +.PP +\fBParameters:\fP +.RS 4 +\fImsg\fP the message from which to get the value +.br +\fImember\fP the name of the member variable +.br +\fIpvalue\fP a pointer to the variable to hold the value +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 otherwise\&. +.RE +.PP + +.SS "#define EVTAG_GET_WITH_LEN(msg, member, pvalue, plen) (*(msg)\->base\->member##_get)((msg), (pvalue), (plen))" + +.PP +Returns the value for a member\&. +.PP +\fBParameters:\fP +.RS 4 +\fImsg\fP the message from which to get the value +.br +\fImember\fP the name of the member variable +.br +\fIpvalue\fP a pointer to the variable to hold the value +.br +\fIplen\fP a pointer to the length of the value +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 otherwise\&. +.RE +.PP + +.SS "#define EVTAG_HAS(msg, member) ((msg)\->member##_set == 1)" + +.PP +Determines if the member has been set in the message\&. +.PP +\fBParameters:\fP +.RS 4 +\fImsg\fP the message to inspect +.br +\fImember\fP the member variable to test for presences +.RE +.PP +\fBReturns:\fP +.RS 4 +1 if it's present or 0 otherwise\&. +.RE +.PP + +.SS "#define INPUT \fBEVRPC_INPUT\fP" + +.PP +Deprecated alias for EVRPC_INPUT\&. Not available on windows, where it conflicts with platform headers\&. +.SS "#define OUTPUT \fBEVRPC_OUTPUT\fP" + +.PP +Deprecated alias for EVRPC_OUTPUT\&. Not available on windows, where it conflicts with platform headers\&. +.SH "Enumeration Type Documentation" +.PP +.SS "enum \fBEVRPC_HOOK_RESULT\fP" + +.PP +Return value from hook processing functions\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVRPC_TERMINATE \fP\fP +indicates the rpc should be terminated +.TP +\fB\fIEVRPC_CONTINUE \fP\fP +continue processing the rpc +.TP +\fB\fIEVRPC_PAUSE \fP\fP +pause processing request until resumed +.SS "enum \fBEVRPC_HOOK_TYPE\fP" + +.PP +Hooks for changing the input and output of RPCs; this can be used to implement compression, authentication, encryption, \&.\&.\&. +.PP +\fBEnumerator\fP +.in +1c +.TP +\fB\fIEVRPC_INPUT \fP\fP +apply the function to an input hook +.TP +\fB\fIEVRPC_OUTPUT \fP\fP +apply the function to an output hook +.SH "Function Documentation" +.PP +.SS "void* evrpc_add_hook (void * vbase, enum \fBEVRPC_HOOK_TYPE\fP hook_type, int(*)(void *, struct evhttp_request *, struct \fBevbuffer\fP *, void *) cb, void * cb_arg)" + +.PP +adds a processing hook to either an rpc base or rpc pool If a hook returns TERMINATE, the processing is aborted\&. On CONTINUE, the request is immediately processed after the hook returns\&. If the hook returns PAUSE, request processing stops until \fBevrpc_resume_request()\fP has been called\&. +.PP +The add functions return handles that can be used for removing hooks\&. +.PP +\fBParameters:\fP +.RS 4 +\fIvbase\fP a pointer to either struct evrpc_base or struct evrpc_pool +.br +\fIhook_type\fP either INPUT or OUTPUT +.br +\fIcb\fP the callback to call when the hook is activated +.br +\fIcb_arg\fP an additional argument for the callback +.RE +.PP +\fBReturns:\fP +.RS 4 +a handle to the hook so it can be removed later +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_remove_hook()\fP +.RE +.PP + +.SS "void evrpc_free (struct evrpc_base * base)" + +.PP +Frees the evrpc base\&. For now, you are responsible for making sure that no rpcs are ongoing\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the evrpc_base object to be freed +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_init\fP +.RE +.PP + +.SS "void evrpc_hook_add_meta (void * ctx, const char * key, const void * data, size_t data_size)" + +.PP +adds meta data to request \fBevrpc_hook_add_meta()\fP allows hooks to add meta data to a request\&. for a client request, the meta data can be inserted by an outgoing request hook and retrieved by the incoming request hook\&. +.PP +\fBParameters:\fP +.RS 4 +\fIctx\fP the context provided to the hook call +.br +\fIkey\fP a NUL-terminated c-string +.br +\fIdata\fP the data to be associated with the key +.br +\fIdata_size\fP the size of the data +.RE +.PP + +.SS "int evrpc_hook_find_meta (void * ctx, const char * key, void ** data, size_t * data_size)" + +.PP +retrieves meta data previously associated \fBevrpc_hook_find_meta()\fP can be used to retrieve meta data associated to a request by a previous hook\&. +.PP +\fBParameters:\fP +.RS 4 +\fIctx\fP the context provided to the hook call +.br +\fIkey\fP a NUL-terminated c-string +.br +\fIdata\fP pointer to a data pointer that will contain the retrieved data +.br +\fIdata_size\fP pointer to the size of the data +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success or -1 on failure +.RE +.PP + +.SS "struct evhttp_connection* evrpc_hook_get_connection (void * ctx)" + +.PP +returns the connection object associated with the request +.PP +\fBParameters:\fP +.RS 4 +\fIctx\fP the context provided to the hook call +.RE +.PP +\fBReturns:\fP +.RS 4 +a pointer to the evhttp_connection object +.RE +.PP + +.SS "struct evrpc_base* evrpc_init (struct evhttp * server)" + +.PP +Creates a new rpc base from which RPC requests can be received\&. +.PP +\fBParameters:\fP +.RS 4 +\fIserver\fP a pointer to an existing HTTP server +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated evrpc_base struct +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_free()\fP +.RE +.PP + +.SS "int evrpc_make_request (struct evrpc_request_wrapper * ctx)" + +.PP +Makes an RPC request based on the provided context\&. This is a low-level function and should not be used directly unless a custom context object is provided\&. Use \fBEVRPC_MAKE_REQUEST()\fP instead\&. +.PP +\fBParameters:\fP +.RS 4 +\fIctx\fP a context from \fBEVRPC_MAKE_CTX()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 otherwise\&. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_MAKE_REQUEST()\fP, \fBEVRPC_MAKE_CTX()\fP +.RE +.PP + +.SS "void evrpc_pool_add_connection (struct evrpc_pool * pool, struct evhttp_connection * evcon)" + +.PP +Adds a connection over which rpc can be dispatched to the pool\&. The connection object must have been newly created\&. +.PP +\fBParameters:\fP +.RS 4 +\fIpool\fP the pool to which to add the connection +.br +\fIevcon\fP the connection to add to the pool\&. +.RE +.PP + +.SS "void evrpc_pool_free (struct evrpc_pool * pool)" + +.PP +frees an rpc connection pool +.PP +\fBParameters:\fP +.RS 4 +\fIpool\fP a pointer to an evrpc_pool allocated via \fBevrpc_pool_new()\fP +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_pool_new()\fP +.RE +.PP + +.SS "struct evrpc_pool* evrpc_pool_new (struct \fBevent_base\fP * base)" + +.PP +creates an rpc connection pool a pool has a number of connections associated with it\&. rpc requests are always made via a pool\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP a pointer to an struct event_based object; can be left NULL in singled-threaded applications +.RE +.PP +\fBReturns:\fP +.RS 4 +a newly allocated struct evrpc_pool object +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_pool_free()\fP +.RE +.PP + +.SS "void evrpc_pool_remove_connection (struct evrpc_pool * pool, struct evhttp_connection * evcon)" + +.PP +Removes a connection from the pool\&. The connection object must have been newly created\&. +.PP +\fBParameters:\fP +.RS 4 +\fIpool\fP the pool from which to remove the connection +.br +\fIevcon\fP the connection to remove from the pool\&. +.RE +.PP + +.SS "void evrpc_pool_set_timeout (struct evrpc_pool * pool, int timeout_in_secs)" + +.PP +Sets the timeout in secs after which a request has to complete\&. The RPC is completely aborted if it does not complete by then\&. Setting the timeout to 0 means that it never timeouts and can be used to implement callback type RPCs\&. +.PP +Any connection already in the pool will be updated with the new timeout\&. Connections added to the pool after set_timeout has be called receive the pool timeout only if no timeout has been set for the connection itself\&. +.PP +\fBParameters:\fP +.RS 4 +\fIpool\fP a pointer to a struct evrpc_pool object +.br +\fItimeout_in_secs\fP the number of seconds after which a request should timeout and a failure be returned to the callback\&. +.RE +.PP + +.SS "int evrpc_register_generic (struct evrpc_base * base, const char * name, void(*)(struct evrpc_req_generic *, void *) callback, void * cbarg, void *(*)(void *) req_new, void * req_new_arg, void(*)(void *) req_free, int(*)(void *, struct \fBevbuffer\fP *) req_unmarshal, void *(*)(void *) rpl_new, void * rpl_new_arg, void(*)(void *) rpl_free, int(*)(void *) rpl_complete, void(*)(struct \fBevbuffer\fP *, void *) rpl_marshal)" + +.PP +Function for registering a generic RPC with the RPC base\&. Do not call this function directly, use \fBEVRPC_REGISTER()\fP instead\&. +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_REGISTER()\fP +.RE +.PP + +.SS "int evrpc_register_rpc (struct evrpc_base *, struct evrpc *, void(*)(struct evrpc_req_generic *, void *), void *)" + +.PP +Low level function for registering an RPC with a server\&. Use \fBEVRPC_REGISTER()\fP instead\&. +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_REGISTER()\fP +.RE +.PP + +.SS "int evrpc_remove_hook (void * vbase, enum \fBEVRPC_HOOK_TYPE\fP hook_type, void * handle)" + +.PP +removes a previously added hook +.PP +\fBParameters:\fP +.RS 4 +\fIvbase\fP a pointer to either struct evrpc_base or struct evrpc_pool +.br +\fIhook_type\fP either INPUT or OUTPUT +.br +\fIhandle\fP a handle returned by \fBevrpc_add_hook()\fP +.RE +.PP +\fBReturns:\fP +.RS 4 +1 on success or 0 on failure +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBevrpc_add_hook()\fP +.RE +.PP + +.SS "int evrpc_resume_request (void * vbase, void * ctx, enum \fBEVRPC_HOOK_RESULT\fP res)" + +.PP +resume a paused request +.PP +\fBParameters:\fP +.RS 4 +\fIvbase\fP a pointer to either struct evrpc_base or struct evrpc_pool +.br +\fIctx\fP the context pointer provided to the original hook call +.RE +.PP + +.SS "int evrpc_send_request_generic (struct evrpc_pool * pool, void * request, void * reply, void(*)(struct evrpc_status *, void *, void *, void *) cb, void * cb_arg, const char * rpcname, void(*)(struct \fBevbuffer\fP *, void *) req_marshal, void(*)(void *) rpl_clear, int(*)(void *, struct \fBevbuffer\fP *) rpl_unmarshal)" + +.PP +Function for sending a generic RPC request\&. Do not call this function directly, use \fBEVRPC_MAKE_REQUEST()\fP instead\&. +.PP +\fBSee also:\fP +.RS 4 +\fBEVRPC_MAKE_REQUEST()\fP +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/rpc_clnt_auth.3 b/static/netbsd/man3/rpc_clnt_auth.3 new file mode 100644 index 00000000..0d43cd14 --- /dev/null +++ b/static/netbsd/man3/rpc_clnt_auth.3 @@ -0,0 +1,108 @@ +.\" @(#)rpc_clnt_auth.3n 1.21 93/05/07 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_clnt_auth 1.4 89/07/20 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_clnt_auth.3,v 1.7 2020/10/03 18:31:29 christos Exp $ +.Dd October 3, 2020 +.Dt RPC_CLNT_AUTH 3 +.Os +.Sh NAME +.Nm auth_destroy , +.Nm authnone_create , +.Nm authsys_create , +.Nm authsys_create_default , +.Nm set_rpc_maxgrouplist +.Nd library routines for client side remote procedure call authentication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft "void" +.Fn auth_destroy "AUTH *auth" +.Ft "AUTH *" +.Fn authnone_create "void" +.Ft "AUTH *" +.Fn authsys_create "const char *host" "const uid_t uid" "const gid_t gid" "const int len" "const gid_t *aup_gids" +.Ft "AUTH *" +.Fn authsys_create_default "void" +.Ft "void" +.Fn set_rpc_maxgrouplist "int num" +.Sh DESCRIPTION +These routines are part of the +RPC library that allows C language programs to make procedure +calls on other machines across the network, +with desired authentication. +.Pp +These routines are normally called after creating the +.Dv CLIENT +handle. +The +.Fa cl_auth +field of the +.Dv CLIENT +structure should be initialized by the +.Dv AUTH +structure returned by some of the following routines. +The client's authentication information +is passed to the server when the +RPC +call is made. +.Pp +Only the +.Dv NULL +and the +.Dv SYS +style of authentication is discussed here. +.Sh ROUTINES +.Bl -tag -width authsys_create_default() +.It Fn auth_destroy +A function macro that destroys the authentication +information associated with +.Fa auth . +Destruction usually involves deallocation +of private data structures. +The use of +.Fn auth +is undefined after calling +.Fn auth_destroy . +.Pp +.It Fn authnone_create +Create and return an RPC +authentication handle that passes nonusable +authentication information with each remote procedure call. +This is the default authentication used by RPC. +.Pp +.It Fn authsys_create +Create and return an RPC authentication handle that contains +.Dv AUTH_SYS +authentication information. +The parameter +.Fa host +is the name of the machine on which the information was +created; +.Fa uid +is the user's user ID; +.Fa gid +is the user's current group ID; +.Fa len +and +.Fa aup_gids +refer to a counted array of groups to which the user belongs. +.Pp +.It Fn authsys_create_default +Call +.Fn authsys_create +with the appropriate parameters. +.Pp +.It Fn set_rpc_maxgrouplist +Allow the application to set the maximum size of the group list +that will be used in +.Fn authunix_create_default to +.Fa num . +Some servers will refuse mounts if the group list is larger than it expects +(like 8). +.El +.Sh SEE ALSO +.Xr rpc 3 , +.Xr rpc_clnt_calls 3 , +.Xr rpc_clnt_create 3 diff --git a/static/netbsd/man3/rpc_clnt_calls.3 b/static/netbsd/man3/rpc_clnt_calls.3 new file mode 100644 index 00000000..2f464a1e --- /dev/null +++ b/static/netbsd/man3/rpc_clnt_calls.3 @@ -0,0 +1,296 @@ +.\" @(#)rpc_clnt_calls.3n 1.30 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_clnt_calls 1.4 89/07/20 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_clnt_calls.3,v 1.7 2005/12/03 15:16:19 yamt Exp $ +.Dd December 4, 2005 +.Dt RPC_CLNT_CALLS 3 +.Os +.Sh NAME +.Nm rpc_clnt_calls , +.Nm clnt_call , +.Nm clnt_freeres , +.Nm clnt_geterr , +.Nm clnt_perrno , +.Nm clnt_perror , +.Nm clnt_sperrno , +.Nm clnt_sperror , +.Nm rpc_broadcast , +.Nm rpc_broadcast_exp , +.Nm rpc_call +.Nd library routines for client side calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft "enum clnt_stat" +.Fn clnt_call "CLIENT *clnt" "const rpcproc_t procnum" "const xdrproc_t inproc" "const char *in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout" +.Ft bool_t +.Fn clnt_freeres "CLIENT *clnt" "const xdrproc_t outproc" "caddr_t out" +.Ft void +.Fn clnt_geterr "const CLIENT * clnt" "struct rpc_err * errp" +.Ft void +.Fn clnt_perrno "const enum clnt_stat stat" +.Ft void +.Fn clnt_perror "const CLIENT * clnt" "const char *s" +.Ft "char *" +.Fn clnt_sperrno "const enum clnt_stat stat" +.Ft "char *" +.Fn clnt_sperror "const CLIENT *clnt" "const char * s" +.\" Note the clustered Fn arguments. It can't take more than 9. XXX +.Ft "enum clnt_stat" +.Fn rpc_broadcast "const rpcprog_t prognum, const rpcvers_t versnum" "const rpcproc_t procnum" "const xdrproc_t inproc" "const char *in" "const xdrproc_t outproc" "caddr_t out" "const resultproc_t eachresult" "const char *nettype" +.Ft "enum clnt_stat" +.Fn rpc_broadcast_exp "rpcprog_t prognum, const rpcvers_t versnum" "const rpcproc_t procnum, const xdrproc_t xargs" "caddr_t argsp, const xdrproc_t xresults" "caddr_t resultsp" "const int inittime" "const int waittime" "const resultproc_t eachresult" "const char * nettype" +.Ft "enum clnt_stat" +.Fn rpc_call "const char *host, const rpcprog_t prognum" "const rpcvers_t versnum" "const rpcproc_t procnum, const xdrproc_t inproc" "const char *in" "const xdrproc_t outproc" "char *out" "const char *nettype" +.Sh DESCRIPTION +RPC library routines allow C language programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a request to the server. +Upon receipt of the request, the server calls a dispatch routine +to perform the requested service, and then sends back a reply. +.Pp +The +.Fn clnt_call , +.Fn rpc_call , +and +.Fn rpc_broadcast +routines handle the client side of the procedure call. +The remaining routines deal with error handling in the case of errors. +.Pp +Some of the routines take a +.Dv CLIENT +handle as one of the parameters. +A +.Dv CLIENT +handle can be created by an RPC creation routine such as +.Fn clnt_create +(see +.Xr rpc_clnt_create 3 ) . +.Pp +These routines are safe for use in multithreaded applications. +.Dv CLIENT +handles can be shared between threads, however in this implementation +requests by different threads are serialized (that is, the first request will +receive its results before the second request is sent). +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Dv CLIENT +data structure. +.Pp +.Bl -tag -width XXXXX +.It Fn clnt_call +A function macro that calls the remote procedure +.Fa procnum +associated with the client handle, +.Fa clnt , +which is obtained with an RPC +client creation routine such as +.Fn clnt_create +(see +.Xr rpc_clnt_create 3 ) . +The parameter +.Fn inproc +is the XDR function used to encode the procedure's parameters, and +.Fn outproc +is the XDR function used to decode the procedure's results; +.Fn in +is the address of the procedure's argument(s), and +.Fn out +is the address of where to place the result(s). +.Fn tout +is the time allowed for results to be returned, which is overridden by +a time-out set explicitly through +.Fn clnt_control , +see +.Xr rpc_clnt_create 3 . +If the remote call succeeds, the status returned is +.Dv RPC_SUCCESS , +otherwise an appropriate status is returned. +.Pp +.It Fn clnt_freeres +A function macro that frees any data allocated by the +RPC/XDR system when it decoded the results of an RPC call. +The parameter +.Fa out +is the address of the results, and +.Fa outproc +is the XDR routine describing the results. +This routine returns 1 if the results were successfully freed, +and 0 otherwise. +.Pp +.It Fn clnt_geterr +A function macro that copies the error structure out of the client +handle to the structure at address +.Fa errp . +.Pp +.It Fn clnt_perrno +Print a message to standard error corresponding +to the condition indicated by +.Fa stat . +A newline is appended. +Normally used after a procedure call fails for a routine +for which a client handle is not needed, for instance +.Fn rpc_call . +.Pp +.It Fn clnt_perror +Print a message to the standard error indicating why an +RPC call failed; +.Fa clnt +is the handle used to do the call. +The message is prepended with string +.Fa s +and a colon. +A newline is appended. +Normally used after a remote procedure call fails +for a routine which requires a client handle, +for instance +.Fn clnt_call . +.Pp +.It Fn clnt_sperrno +Take the same arguments as +.Fn clnt_perrno , +but instead of sending a message to the standard error +indicating why an RPC +call failed, return a pointer to a string which contains the message. +.Fn clnt_sperrno +is normally used instead of +.Fn clnt_perrno +when the program does not have a standard error (as a program +running as a server quite likely does not), or if the programmer +does not want the message to be output with +.Fn printf +(see +.Xr printf 3 ) , +or if a message format different than that supported by +.Fn clnt_perrno +is to be used. +Note: +unlike +.Fn clnt_sperror +and +.Fn clnt_spcreaterror +(see +.Xr rpc_clnt_create 3 ) , +.Fn clnt_sperrno +does not return pointer to static data so the +result will not get overwritten on each call. +.Pp +.It Fn clnt_sperror +Like +.Fn clnt_perror , +except that (like +.Fn clnt_sperrno ) +it returns a string instead of printing to standard error. +However, +.Fn clnt_sperror +does not append a newline at the end of the message. +Warning: +returns pointer to a buffer that is overwritten +on each call. +.Pp +.It Fn rpc_broadcast +Like +.Fn rpc_call , +except the call message is broadcast to +all the connectionless transports specified by +.Fa nettype . +If +.Fa nettype +is +.Dv NULL , +it defaults to +.Dq netpath . +Each time it receives a response, +this routine calls +.Fn eachresult , +whose form is: +.Ft bool_t +.Fn eachresult "caddr_t out" "const struct netbuf * addr" "const struct netconfig * netconf" +where +.Fa out +is the same as +.Fa out +passed to +.Fn rpc_broadcast , +except that the remote procedure's output is decoded there; +.Fa addr +points to the address of the machine that sent the results, and +.Fa netconf +is the netconfig structure of the transport on which the remote +server responded. +If +.Fn eachresult +returns 0, +.Fn rpc_broadcast +waits for more replies; +otherwise it returns with appropriate status. +Warning: +broadcast file descriptors are limited in size to the +maximum transfer size of that transport. +For Ethernet, this value is 1500 bytes. +.Fn rpc_broadcast +uses +.Dv AUTH_SYS +credentials by default (see +.Xr rpc_clnt_auth 3 ) . +.Pp +.It Fn rpc_broadcast_exp +Like +.Fn rpc_broadcast , +except that the initial timeout, +.Fa inittime +and the maximum timeout, +.Fa waittime +are specified in milliseconds. +.Fa inittime +is the initial time that +.Fn rpc_broadcast_exp +waits before resending the request. +After the first resend, the re-transmission interval +increases exponentially until it exceeds +.Fa waittime . +.Pp +.It Fn rpc_call +Call the remote procedure associated with +.Fa prognum , +.Fa versnum , +and +.Fa procnum +on the machine, +.Fa host . +The parameter +.Fa inproc +is used to encode the procedure's parameters, and +.Fa outproc +is used to decode the procedure's results; +.Fa in +is the address of the procedure's argument(s), and +.Fa out +is the address of where to place the result(s). +.Fa nettype +can be any of the values listed on +.Xr rpc 3 . +This routine returns +.Dv RPC_SUCCESS +if it succeeds, or an appropriate status is returned. +Use the +.Fn clnt_perrno +routine to translate failure status into error messages. +Warning: +.Fn rpc_call +uses the first available transport belonging +to the class +.Fa nettype , +on which it can create a connection. +You do not have control of timeouts or authentication +using this routine. +.El +.Sh SEE ALSO +.Xr printf 3 , +.Xr rpc 3 , +.Xr rpc_clnt_auth 3 , +.Xr rpc_clnt_create 3 diff --git a/static/netbsd/man3/rpc_clnt_create.3 b/static/netbsd/man3/rpc_clnt_create.3 new file mode 100644 index 00000000..1b11a2c3 --- /dev/null +++ b/static/netbsd/man3/rpc_clnt_create.3 @@ -0,0 +1,443 @@ +.\" @(#)rpc_clnt_create.3n 1.36 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_clnt_create 1.5 89/07/24 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_clnt_create.3,v 1.13 2017/07/03 21:32:49 wiz Exp $ +.Dd May 23, 2009 +.Dt RPC_CLNT_CREATE 3 +.Os +.Sh NAME +.Nm rpc_clnt_create , +.Nm clnt_control , +.Nm clnt_create , +.Nm clnt_create_vers , +.Nm clnt_destroy , +.Nm clnt_dg_create , +.Nm clnt_pcreateerror , +.Nm clnt_raw_create , +.Nm clnt_spcreateerror , +.Nm clnt_tli_create , +.Nm clnt_tp_create , +.Nm clnt_vc_create , +.Nm rpc_createerr +.Nd "library routines for dealing with creation and manipulation of CLIENT handles" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft bool_t +.Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info" +.Ft "CLIENT *" +.Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" +.Ft "CLIENT *" +.Fn clnt_create_vers "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "char *nettype" +.Ft void +.Fn clnt_destroy "CLIENT * clnt" +.Ft "CLIENT *" +.Fn clnt_dg_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz" +.Ft void +.Fn clnt_pcreateerror "const char *s" +.Ft "char *" +.Fn clnt_spcreateerror "const char *s" +.Ft "CLIENT *" +.Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum" +.Ft "CLIENT *" +.Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz" +.Ft "CLIENT *" +.Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" +.Ft "CLIENT *" +.Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz" +.Sh DESCRIPTION +RPC library routines allow C language programs to make procedure +calls on other machines across the network. +First a +.Dv CLIENT +handle is created and then the client calls a procedure to send a +request to the server. +On receipt of the request, the server calls a dispatch routine +to perform the requested service, and then sends a reply. +.Sh ROUTINES +.Bl -tag -width YYYYYYY +.It Fn clnt_control +A function macro to change or retrieve various information +about a client object. +.Fa req +indicates the type of operation, and +.Fa info +is a pointer to the information. +For both connectionless and connection-oriented transports, +the supported values of +.Fa req +and their argument types and what they do are: +.Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout" +.It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout" +.It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout" +.El +.Pp +Note: +if you set the timeout using +.Fn clnt_control , +the timeout argument passed by +.Fn clnt_call +is ignored in all subsequent calls. +.Pp +Note: +If you set the timeout value to 0 +.Fn clnt_control +immediately returns an error +.Pq Dv RPC_TIMEDOUT . +Set the timeout parameter to 0 for batching calls. +.Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy" +.It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address" +.It Dv CLGET_FD Ta "int *" Ta "get fd from handle" +.It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy" +.It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy" +.It Dv CLGET_VERS Ta "unsigned long *" Ta "get RPC program version" +.It Dv CLSET_VERS Ta "unsigned long *" Ta "set RPC program version" +.It Dv CLGET_XID Ta "unsigned long *" Ta "get XID of previous call" +.It Dv CLSET_XID Ta "unsigned long *" Ta "set XID of next call" +.El +.Pp +The following operations are valid for connectionless transports only: +.Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout" +.It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout" +.It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout" +.El +.Pp +The retry timeout is the time that RPC +waits for the server to reply before retransmitting the request. +.Fn clnt_control +returns +.Dv TRUE +on success and +.Dv FALSE +on failure. +.Pp +.It Fn clnt_create +Generic client creation routine for program +.Fa prognum +and version +.Fa versnum . +.Fa host +identifies the name of the remote host where the server +is located. +.Fa nettype +indicates the class of transport protocol to use. +The transports are tried in left to right order in +.Ev NETPATH +environment variable or in top to bottom order in +the netconfig database. +.Fn clnt_create +tries all the transports of the +.Fa nettype +class available from the +.Ev NETPATH +environment variable and the netconfig database, +and chooses the first successful one. +A default timeout is set and can be modified using +.Fn clnt_control . +This routine returns +.Dv NULL +if it fails. +The +.Fn clnt_pcreateerror +routine can be used to print the reason for failure. +.Pp +Note: +.Fn clnt_create +returns a valid client handle even +if the particular version number supplied to +.Fn clnt_create +is not registered with the +.Xr rpcbind 8 +service. +This mismatch will be discovered by a +.Fn clnt_call +later (see +.Xr rpc_clnt_calls 3 ) . +.Pp +.It Fn clnt_create_vers +Generic client creation routine which is similar to +.Fn clnt_create +but which also checks for the +version availability. +.Fa host +identifies the name of the remote host where the server +is located. +.Fa nettype +indicates the class transport protocols to be used. +If the routine is successful it returns a client handle created for +the highest version between +.Fa vers_low +and +.Fa vers_high +that is supported by the server. +.Fa vers_outp +is set to this value. +That is, after a successful return +.Fa vers_low +\*[Le] +.Fa *vers_outp +\*[Le] +.Fa vers_high . +If no version between +.Fa vers_low +and +.Fa vers_high +is supported by the server then the routine fails and returns +.Dv NULL . +A default timeout is set and can be modified using +.Fn clnt_control . +This routine returns +.Dv NULL +if it fails. +The +.Fn clnt_pcreateerror +routine can be used to print the reason for failure. +Note: +.Fn clnt_create +returns a valid client handle even +if the particular version number supplied to +.Fn clnt_create +is not registered with the +.Xr rpcbind 8 +service. +This mismatch will be discovered by a +.Fn clnt_call +later (see +.Xr rpc_clnt_calls 3 ) . +However, +.Fn clnt_create_vers +does this for you and returns a valid handle +only if a version within +the range supplied is supported by the server. +.Pp +.It Fn clnt_destroy +A function macro that destroys the client's RPC handle. +Destruction usually involves deallocation +of private data structures, including +.Fa clnt +itself. +Use of +.Fa clnt +is undefined after calling +.Fn clnt_destroy . +If the RPC library opened the associated file descriptor, or +.Dv CLSET_FD_CLOSE +was set using +.Fn clnt_control , +the file descriptor will be closed. +The caller should call +.Fn auth_destroy "clnt->cl_auth" +(before calling +.Fn clnt_destroy ) +to destroy the associated +.Dv AUTH +structure (see +.Xr rpc_clnt_auth 3 ) . +.Pp +.It Fn clnt_dg_create +This routine creates an RPC client for the remote program +.Fa prognum +and version +.Fa versnum ; +the client uses a connectionless transport. +The remote program is located at address +.Fa svcaddr . +The parameter +.Fa fildes +is an open and bound file descriptor. +This routine will resend the call message in intervals of +15 seconds until a response is received or until the +call times out. +The total time for the call to time out is specified by +.Fn clnt_call +(see +.Fn clnt_call +in +.Xr rpc_clnt_calls 3 ) . +The retry time out and the total time out periods can +be changed using +.Fn clnt_control . +The user may set the size of the send and receive +buffers with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of 0 choose suitable defaults. +This routine returns +.Dv NULL +if it fails. +.Pp +.It Fn clnt_pcreateerror +Print a message to standard error indicating +why a client RPC handle could not be created. +The message is prepended with the string +.Fa s +and a colon, and appended with a newline. +.Pp +.It Fn clnt_spcreateerror +Like +.Fn clnt_pcreateerror , +except that it returns a string +instead of printing to the standard error. +A newline is not appended to the message in this case. +Warning: +returns a pointer to a buffer that is overwritten +on each call. +.Pp +.It Fn clnt_raw_create +This routine creates an RPC +client handle for the remote program +.Fa prognum +and version +.Fa versnum . +The transport used to pass messages to the service is +a buffer within the process's address space, +so the corresponding RPC +server should live in the same address space; +(see +.Fn svc_raw_create +in +.Xr rpc_svc_create 3 ) . +This allows simulation of RPC and measurement of +RPC overheads, such as round trip times, +without any kernel or networking interference. +This routine returns +.Dv NULL +if it fails. +.Fn clnt_raw_create +should be called after +.Fn svc_raw_create . +.Pp +.It Fn clnt_tli_create +This routine creates an RPC +client handle for the remote program +.Fa prognum +and version +.Fa versnum . +The remote program is located at address +.Fa svcaddr . +If +.Fa svcaddr +is +.Dv NULL +and it is connection-oriented, it is assumed that the file descriptor +is connected. +For connectionless transports, if +.Fa svcaddr +is +.Dv NULL , +.Dv RPC_UNKNOWNADDR +error is set. +.Fa fildes +is a file descriptor which may be open, bound and connected. +If it is +.Dv RPC_ANYFD , +it opens a file descriptor on the transport specified by +.Fa netconf . +If +.Fa fildes +is +.Dv RPC_ANYFD +and +.Fa netconf +is +.Dv NULL , +a +.Dv RPC_UNKNOWNPROTO +error is set. +If +.Fa fildes +is unbound, then it will attempt to bind the descriptor. +The user may specify the size of the buffers with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of 0 choose suitable defaults. +Depending upon the type of the transport (connection-oriented +or connectionless), +.Fn clnt_tli_create +calls appropriate client creation routines. +This routine returns +.Dv NULL +if it fails. +The +.Fn clnt_pcreateerror +routine can be used to print the reason for failure. +The remote rpcbind +service (see +.Xr rpcbind 8 ) +is not consulted for the address of the remote +service. +.Pp +.It Fn clnt_tp_create +Like +.Fn clnt_create +except +.Fn clnt_tp_create +tries only one transport specified through +.Fa netconf . +.Fn clnt_tp_create +creates a client handle for the program +.Fa prognum , +the version +.Fa versnum , +and for the transport specified by +.Fa netconf . +Default options are set, +which can be changed using +.Fn clnt_control +calls. +The remote rpcbind service on the host +.Fa host +is consulted for the address of the remote service. +This routine returns +.Dv NULL +if it fails. +The +.Fn clnt_pcreateerror +routine can be used to print the reason for failure. +.Pp +.It Fn clnt_vc_create +This routine creates an RPC +client for the remote program +.Fa prognum +and version +.Fa versnum ; +the client uses a connection-oriented transport. +The remote program is located at address +.Fa svcaddr . +The parameter +.Fa fildes +is an open and bound file descriptor. +The user may specify the size of the send and receive buffers +with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of 0 choose suitable defaults. +This routine returns +.Dv NULL +if it fails. +The address +.Fa svcaddr +should not be +.Dv NULL +and should point to the actual address of the remote program. +.Fn clnt_vc_create +does not consult the remote rpcbind service for this information. +.Pp +.It struct rpc_createerr rpc_createerr; +A global variable whose value is set by any RPC +client handle creation routine +that fails. +It is used by the routine +.Fn clnt_pcreateerror +to print the reason for the failure. +.El +.Sh SEE ALSO +.Xr rpc 3 , +.Xr rpc_clnt_auth 3 , +.Xr rpc_clnt_calls 3 , +.Xr rpcbind 8 diff --git a/static/netbsd/man3/rpc_compat.h.3 b/static/netbsd/man3/rpc_compat.h.3 new file mode 100644 index 00000000..52a50a91 --- /dev/null +++ b/static/netbsd/man3/rpc_compat.h.3 @@ -0,0 +1,25 @@ +.TH "event2/rpc_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/rpc_compat.h \- Deprecated versions of the functions in \fBrpc\&.h\fP: provided only for backwards compatibility\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVTAG_LEN\fP(msg, member) ((msg)\->member##_length)" +.br +.RI "\fIbackwards compatible accessors that work only with gcc \fP" +.in -1c +.SH "Detailed Description" +.PP +Deprecated versions of the functions in \fBrpc\&.h\fP: provided only for backwards compatibility\&. + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/rpc_soc.3 b/static/netbsd/man3/rpc_soc.3 new file mode 100644 index 00000000..95285be3 --- /dev/null +++ b/static/netbsd/man3/rpc_soc.3 @@ -0,0 +1,1067 @@ +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" $NetBSD: rpc_soc.3,v 1.17 2017/07/03 21:32:49 wiz Exp $ +.\" Converted to mdoc by Thomas Klausner <wiz@NetBSD.org> +.\" +.Dd December 29, 2016 +.Dt RPC_SOC 3 +.Os +.Sh NAME +.Nm rpc_soc , +.Nm auth_destroy , +.Nm authnone_create , +.Nm authunix_create , +.Nm authunix_create_default , +.Nm callrpc , +.Nm clnt_broadcast , +.Nm clnt_call , +.Nm clnt_control , +.Nm clnt_create , +.Nm clnt_destroy , +.Nm clnt_freeres , +.Nm clnt_geterr , +.Nm clnt_pcreateerror , +.Nm clnt_perrno , +.Nm clnt_perror , +.Nm clnt_spcreateerror , +.Nm clnt_sperrno , +.Nm clnt_sperror , +.Nm clntraw_create , +.Nm clnttcp_create , +.Nm clntudp_bufcreate , +.Nm clntudp_create , +.Nm get_myaddress , +.Nm pmap_getmaps , +.Nm pmap_getport , +.Nm pmap_rmtcall , +.Nm pmap_set , +.Nm pmap_unset , +.Nm registerrpc , +.Nm rpc_createerr , +.Nm svc_destroy , +.Nm svc_fds , +.Nm svc_fdset , +.Nm svc_getargs , +.Nm svc_getcaller , +.Nm svc_getreg , +.Nm svc_getregset , +.Nm svc_getrpccaller , +.Nm svc_register , +.Nm svc_run , +.Nm svc_sendreply , +.Nm svc_unregister , +.Nm svcerr_auth , +.Nm svcerr_decode , +.Nm svcerr_noproc , +.Nm svcerr_noprog , +.Nm svcerr_progvers , +.Nm svcerr_systemerr , +.Nm svcerr_weakauth , +.Nm svcfd_create , +.Nm svcraw_create , +.Nm xdr_accepted_reply , +.Nm xdr_authunix_parms , +.Nm xdr_callhdr , +.Nm xdr_callmsg , +.Nm xdr_opaque_auth , +.Nm xdr_pmap , +.Nm xdr_pmaplist , +.Nm xdr_rejected_reply , +.Nm xdr_replymsg , +.Nm xprt_register , +.Nm xprt_unregister +.Nd library routines for remote procedure calls +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft void +.Fn auth_destroy "AUTH *auth" +.Ft AUTH * +.Fn authnone_create "void" +.Ft AUTH * +.Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids" +.Ft AUTH * +.Fn authunix_create_default "void" +.Ft int +.Fn callrpc "char *host" "int prognum" "int versnum" \ +"int procnum" "xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" +.Ft enum clnt_stat +.Fn clnt_broadcast "u_long prognum" "u_long versnum" "u_long procnum" \ +"xdrproc_t inproc" "char *in" "xdrproc_t outproc" "char *out" \ +"resultproc_t eachresult" +.Ft enum clnt_stat +.Fn clnt_call "CLIENT *clnt" "u_long procnum" "xdrproc_t inproc" \ +"char *in" "xdrproc_t outproc" "char *out" "struct timeval tout" +.Ft int +.Fn clnt_destroy "CLIENT *clnt" +.Ft CLIENT * +.Fn clnt_create "const char *host" "rpcprog_t prog" "rpcvers_t vers" "const char *proto" +.Ft bool_t +.Fn clnt_control "CLIENT *cl" "u_int req" "char *info" +.Ft int +.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out" +.Ft void +.Fn clnt_geterr "CLIENT *clnt" "struct rpc_err errp" +.Ft void +.Fn clnt_pcreateerror "const char *s" +.Ft void +.Fn clnt_perrno "enum clnt_stat stat" +.Ft void +.Fn clnt_perror "CLIENT *clnt" "const char *s" +.Ft char * +.Fn clnt_spcreateerror "const char *s" +.Ft char * +.Fn clnt_sperrno "enum clnt_stat stat" +.Ft char * +.Fn clnt_sperror "CLIENT *rpch" "const char *s" +.Ft CLIENT * +.Fn clntraw_create "u_long prognum" "u_long versnum" +.Ft CLIENT * +.Fn clnttcp_create "struct sockaddr_in *addr" "u_long prognum" \ +"u_long versnum" "int *sockp" "u_int sendsz" "u_int recvsz" +.Ft CLIENT * +.Fn clntudp_create "struct sockaddr_in *addr" "u_long prognum" \ +"u_long versnum" "struct timeval wait" "int *sockp" +.Ft CLIENT * +.Fn clntudp_bufcreate "struct sockaddr_in *addr" "u_long prognum" \ +"u_long versnum" "struct timeval wait" "int *sockp" \ +"unsigned int sendsize" "unsigned int recosize" +.Ft int +.Fn get_myaddress "struct sockaddr_in *addr" +.Ft struct pmaplist * +.Fn pmap_getmaps "struct sockaddr_in *addr" +.Ft u_short +.Fn pmap_getport "struct sockaddr_in *addr" "u_long prognum" \ +"u_long versnum" "u_int protocol" +.Ft enum clnt_stat +.Fo pmap_rmtcall +.Fa "struct sockaddr_in *addr" +.Fa "u_long prognum" +.Fa "u_long versnum" +.Fa "u_long procnum" +.Fa "xdrproc_t inproc" +.Fa "char *in" +.Fa "xdrproc_t outproc" +.Fa "char *out" +.Fa "struct timeval tout" +.Fa "u_long *portp" +.Fc +.Ft int +.Fn pmap_set "u_long prognum" "u_long versnum" "int protocol" \ +"int port" +.Ft int +.Fn pmap_unset "u_long prognum" "u_long versnum" +.Ft int +.Fn registerrpc "int prognum" "int versnum" "int procnum" \ +"char *(*procname)()" "xdrproc_t inproc" "xdrproc_t outproc" +.Fd struct rpc_createerr rpc_createerr; +.Ft int +.Fn svc_destroy "SVCXPRT *xprt" +.Fd fd_set svc_fdset; +.Fd int svc_fds; +.Ft int +.Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" +.Ft int +.Fn svc_getargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" +.Ft struct sockaddr_in * +.Fn svc_getcaller "SVCXPRT *xprt" +.Ft void +.Fn svc_getreqset "fd_set *rdfds" +.Ft void +.Fn svc_getreq "int rdfds" +.Ft struct netbuf * +.Fn svc_getrpccaller "SVCXPRT *xprt" +.Ft bool_t +.Fn svc_register "SVCXPRT *xprt" "u_long prognum" "u_long versnum" \ +"void (*dispatch)()" "int protocol" +.Ft void +.Fn svc_run "void" +.Ft bool_t +.Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t xdr_results" "const char *location" +.Ft void +.Fn svc_unregister "u_long prognum" "u_long versnum" +.Ft void +.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why" +.Ft void +.Fn svcerr_decode "SVCXPRT *xprt" +.Ft void +.Fn svcerr_noproc "SVCXPRT *xprt" +.Ft void +.Fn svcerr_noprog "SVCXPRT *xprt" +.Ft void +.Fn svcerr_progvers "SVCXPRT *xprt" "rpcvers_t low_vers" "rpcvers_t high_vers" +.Ft void +.Fn svcerr_systemerr "SVCXPRT *xprt" +.Ft void +.Fn svcerr_weakauth "SVCXPRT *xprt" +.Ft SVCXPRT * +.Fn svcraw_create "void" +.Ft SVCXPRT * +.Fn svctcp_create "int sock" "u_int send_buf_size" \ +"u_int recv_buf_size" +.Ft SVCXPRT * +.Fn svcfd_create "int fd" "u_int sendsize" "u_int recvsize" +.Ft SVCXPRT * +.Fn svcudp_bufcreate "int sock" "u_int sendsize" "u_int recosize" +.Ft SVCXPRT * +.Fn svcudp_create "int sock" +.Ft int +.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar" +.Ft int +.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp" +.Ft bool_t +.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr" +.Ft int +.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg" +.Ft int +.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap" +.Ft int +.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs" +.Ft int +.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp" +.Ft int +.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr" +.Ft int +.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg" +.Ft bool_t +.Fn xprt_register "SVCXPRT *xprt" +.Ft void +.Fn xprt_unregister "SVCXPRT *xprt" +.Sh DESCRIPTION +.Em "The svc and clnt functions described in this page are the old, TS-RPC" +.Em "interface to the XDR and RPC library, and exist for backward compatibility." +.Em "The new interface is described in the pages referenced from" +.Xr rpc 3 . +.Pp +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a +data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a +reply. +Finally, the procedure call returns to the client. +.\" XXX: NOTYET +.\".Pp +.\"Routines that are used for Secure RPC (DES authentication) are described in +.\".Xr rpc_secure 3 . +.\"Secure RPC can be used only if DES encryption is available. +.Pp +.Bl -tag -width xxx +.It Fn auth_destroy +A macro that destroys the authentication information associated with +.Fa auth . +Destruction usually involves deallocation of private data structures. +The use of +.Fa auth +is undefined after calling +.Fn auth_destroy . +.It Fn authnone_create +Create and returns an RPC authentication handle that passes nonusable +authentication information with each remote procedure call. +This is the default authentication used by RPC. +.It Fn authunix_create +Create and return an RPC authentication handle that contains +.\" XXX: .UX ? +authentication information. +The parameter +.Fa host +is the name of the machine on which the information was +created; +.Fa uid +is the user's user ID; +.Fa gid +is the user's current group id; +.Fa len +and +.Fa aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.It Fn authunix_create_default +Calls +.Fn authunix_create +with the appropriate parameters. +.It Fn callrpc +Call the remote procedure associated with +.Fa prognum , +.Fa versnum , +and +.Fa procnum +on the machine, +.Fa host . +The parameter +.Fa in +is the address of the procedure's argument(s), and +.Fa out +is the address of where to place the result(s); +.Fa inproc +is used to encode the procedure's parameters, and +.Fa outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.Va "enum clnt_stat" +cast to an integer if it fails. +The routine +.Fn clnt_perrno +is handy for translating failure statuses into messages. +.Pp +Warning: calling remote procedures with this routine +uses UDP/IP as a transport; see +.Fn clntudp_create +for restrictions. +You do not have control of timeouts or authentication using +this routine. +.It Fn clnt_broadcast +Like +.Fn callrpc , +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a response, this routine calls +.Fn eachresult , +whose form is +.Ft int +.Fn eachresult "char *out" "struct sockaddr_in *addr" +where +.Fa out +is the same as +.Fa out +passed to +.Fn clnt_broadcast , +except that the remote procedure's output is decoded there; +.Fa addr +points to the address of the machine that sent the results. +If +.Fn eachresult +returns zero, +.Fn clnt_broadcast +waits for more replies; otherwise it returns with appropriate +status. +.Pp +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. +.It Fn clnt_call +A macro that calls the remote procedure +.Fa procnum +associated with the client handle, +.Fa clnt , +which is obtained with an RPC client creation routine such as +.Fn clnt_create . +The parameter +.Fa in +is the address of the procedure's argument(s), and +.Fa out +is the address of where to place the result(s); +.Fa inproc +is used to encode the procedure's parameters, and +.Fa outproc +is used to decode the procedure's results; +.Fa tout +is the time allowed for results to come back. +.It Fn clnt_destroy +A macro that destroys the client's RPC handle. +Destruction usually involves deallocation +of private data structures, including +.Fa clnt +itself. +Use of +.Fa clnt +is undefined after calling +.Fn clnt_destroy . +If the RPC library opened the associated socket, it will close it +also. +Otherwise, the socket remains open. +.It Fn clnt_create +Generic client creation routine. +.Fa host +identifies the name of the remote host where the server +is located. +.Fa proto +indicates which kind of transport protocol to use. +The currently supported values for this field are +.Dq udp +and +.Dq tcp . +Default timeouts are set, but can be modified using +.Fn clnt_control . +.Pp +.Em Warning : +Using UDP has its shortcomings. +Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded +data, this transport cannot be used for procedures that take +large arguments or return huge results. +.It Fn clnt_control +A macro used to change or retrieve various information +about a client object. +.Fa req +indicates the type of operation, and +.Fa info +is a pointer to the information. +For both UDP and TCP the supported values of +.Fa req +and their argument types and what they do are: +.Bl -tag -width CLSET_RETRY_TIMEOUTX +.It CLSET_TIMEOUT +.Vt struct timeval ; +set total timeout. +.It CLGET_TIMEOUT +.Vt struct timeval ; +get total timeout. +.Pp +Note: if you set the timeout using +.Fn clnt_control , +the timeout parameter passed to +.Fn clnt_call +will be ignored in all future calls. +.It CLGET_SERVER_ADDR +.Vt struct sockaddr_in ; +get server's address. +.El +.Pp +The following operations are valid for UDP only: +.Bl -tag -width CLSET_RETRY_TIMEOUT +.It CLSET_RETRY_TIMEOUT +.Vt struct timeval ; +set the retry timeout. +.It CLGET_RETRY_TIMEOUT +.Vt struct timeval ; +get the retry timeout. +.Pp +The retry timeout is the time that UDP RPC waits for the server to +reply before retransmitting the request. +.El +.It Fn clnt_freeres +A macro that frees any data allocated by the RPC/XDR system when it +decoded the results of an RPC call. +The parameter +.Fa out +is the address of the results, and +.Fa outproc +is the XDR routine describing the results. +This routine returns one if the results were successfully freed, +and zero otherwise. +.It Fn clnt_geterr +A macro that copies the error structure out of the client +handle to the structure at address +.Fa errp . +.It Fn clnt_pcreateerror +Print a message to standard error indicating why a client RPC handle +could not be created. +The message is prepended with string +.Fa s +and a colon. +A newline character is appended at the end of the message. +Used when a +.Fn clnt_create , +.Fn clntraw_create , +.Fn clnttcp_create , +or +.Fn clntudp_create +call fails. +.It Fn clnt_perrno +Print a message to standard error corresponding +to the condition indicated by +.Fa stat . +A newline character is appended at the end of the message. +Used after +.Fn callrpc . +.It Fn clnt_perror +Print a message to standard error indicating why an RPC call failed; +.Fa clnt +is the handle used to do the call. +The message is prepended with string +.Fa s +and a colon. +A newline character is appended at the end of the message. +Used after +.Fn clnt_call . +.It Fn clnt_spcreateerror +Like +.Fn clnt_pcreateerror , +except that it returns a string +instead of printing to the standard error. +.Pp +Bugs: returns pointer to static data that is overwritten +on each call. +.It Fn clnt_sperrno +Take the same arguments as +.Fn clnt_perrno , +but instead of sending a message to the standard error +indicating why an RPC call failed, return a pointer to a string which +contains the message. +.Pp +.Fn clnt_sperrno +is used instead of +.Fn clnt_perrno +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the +programmer does not want the message to be output with +.Xr printf 3 , +or if a message format different than that supported by +.Fn clnt_perrno +is to be used. +Note: unlike +.Fn clnt_sperror +and +.Fn clnt_spcreateerror , +.Fn clnt_sperrno +returns a pointer to static data, but the +result will not get overwritten on each call. +.It Fn clnt_sperror +Like +.Fn clnt_perror , +except that (like +.Fn clnt_sperrno ) +it returns a string instead of printing to standard error. +.Pp +Bugs: returns pointer to static data that is overwritten +on each call. +.It Fn clntraw_create +This routine creates a toy RPC client for the remote program +.Fa prognum , +version +.Fa versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding RPC server should live in the same address space; see +.Fn svcraw_create . +This allows simulation of RPC and acquisition of RPC overheads, such +as round trip times, without any kernel interference. +This routine returns +.Dv NULL +if it fails. +.It Fn clnttcp_create +This routine creates an RPC client for the remote program +.Fa prognum , +version +.Fa versnum ; +the client uses TCP/IP as a transport. +The remote program is located at Internet address +.Fa *addr . +If +.Fa addr->sin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +or +.Cm portmap +service is consulted for this information). +The parameter +.Fa sockp +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +Since TCP-based RPC uses buffered I/O , +the user may specify the size of the send and receive buffers +with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of zero choose suitable defaults. +This routine returns +.Dv NULL +if it fails. +.It Fn clntudp_create +This routine creates an RPC client for the remote program +.Fa prognum , +version +.Fa versnum ; +the client uses UDP/IP as a transport. +The remote program is located at Internet address +.Fa addr . +If +.Fa addr->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +or +.Cm portmap +service is consulted for this information). +The parameter +.Fa sockp +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +The UDP transport resends the call message in intervals of +.Fa wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.Fa clnt_call . +.Pp +Warning: since UDP-based RPC messages can only hold up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.It Fn clntudp_bufcreate +This routine creates an RPC client for the remote program +.Fa prognum , +on +.Fa versnum ; +the client uses UDP/IP as a transport. +The remote program is located at Internet address +.Fa addr . +If +.Fa addr->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.Xr rpcbind 8 +or +.Cm portmap +service is consulted for this information). +The parameter +.Fa sockp +is a socket; if it is +.Dv RPC_ANYSOCK , +then this routine opens a new one and sets +.Fa sockp . +The UDP transport resends the call message in intervals of +.Fa wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.Fa clnt_call . +.Pp +This allows the user to specify the maximum packet size for sending and +receiving UDP-based RPC messages. +.It Fn get_myaddress +Stuff the machine's IP address into +.Fa *addr , +without consulting the library routines that deal with +.Pa /etc/hosts . +The port number is always set to +.Fn htons "PMAPPORT" . +Returns zero on success, non-zero on failure. +.It Fn pmap_getmaps +A user interface to the +.Xr rpcbind 8 +service, which returns a list of the current RPC program-to-port +mappings on the host located at IP address +.Fa *addr . +This routine can return +.Dv NULL . +The command +.Dl Cm rpcinfo Fl p +uses this routine. +.It Fn pmap_getport +A user interface to the +.Xr rpcbind 8 +service, which returns the port number +on which waits a service that supports program number +.Fa prognum , +version +.Fa versnum , +and speaks the transport protocol associated with +.Fa protocol . +The value of +.Fa protocol +is most likely +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +A return value of zero means that the mapping does not exist +or that the RPC system failured to contact the remote +.Xr rpcbind 8 +service. +In the latter case, the global variable +.Fn rpc_createerr +contains the RPC status. +.It Fn pmap_rmtcall +A user interface to the +.Xr rpcbind 8 +service, which instructs +.Xr rpcbind 8 +on the host at IP address +.Fa *addr +to make an RPC call on your behalf to a procedure on that host. +The parameter +.Fa *portp +will be modified to the program's port number if the +procedure succeeds. +The definitions of other parameters are discussed in +.Fn callrpc +and +.Fn clnt_call . +This procedure should be used for a +.Dq ping +and nothing else. +See also +.Fn clnt_broadcast . +.It Fn pmap_set +A user interface to the +.Xr rpcbind 8 +service, which establishes a mapping between the triple +.Fa [ prognum , +.Fa versnum , +.Fa protocol ] +and +.Fa port +on the machine's +.Xr rpcbind 8 +service. +The value of +.Fa protocol +is most likely +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.Fn svc_register . +.It Fn pmap_unset +A user interface to the +.Xr rpcbind 8 +service, which destroys all mapping between the triple +.Fa [ prognum , +.Fa versnum , +.Fa * ] +and +.Fa ports +on the machine's +.Xr rpcbind 8 +service. +This routine returns one if it succeeds, zero otherwise. +.It Fn registerrpc +Register procedure +.Fa procname +with the RPC service package. +If a request arrives for program +.Fa prognum , +version +.Fa versnum , +and procedure +.Fa procnum , +.Fa procname +is called with a pointer to its parameter(s); +.Fa progname +should return a pointer to its static result(s); +.Fa inproc +is used to decode the parameters while +.Fa outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 +otherwise. +.Pp +Warning: remote procedures registered in this form +are accessed using the UDP/IP transport; see +.Fn svcudp_bufcreate +for restrictions. +.It struct rpc_createerr rpc_createerr ; +A global variable whose value is set by any RPC +client creation routine that does not succeed. +Use the routine +.Fn clnt_pcreateerror +to print the reason why. +.It Fn svc_destroy +A macro that destroys the RPC service transport handle, +.Fa xprt . +Destruction usually involves deallocation +of private data structures, including +.Fa xprt +itself. +Use of +.Fa xprt +is undefined after calling this routine. +.It fd_set svc_fdset ; +A global variable reflecting the RPC service side's read file +descriptor bit mask; it is suitable as a parameter to the +.Xr select 2 +system call. +This is only of interest if a service implementor does not call +.Fn svc_run , +but rather does his own asynchronous event processing. +This variable is read-only (do not pass its address to +.Xr select 2 ! ) , +yet it may change after calls to +.Fn svc_getreqset +or any creation routines. +.It int svc_fds; +Similar to +.Fn svc_fedset , +but limited to 32 descriptors. +This interface is obsoleted by +.Fn svc_fdset . +.It Fn svc_freeargs +A macro that frees any data allocated by the RPC/XDR +system when it decoded the arguments to a service procedure using +.Fn svc_getargs . +This routine returns 1 if the results were successfully freed, +and zero otherwise. +.It Fn svc_getargs +A macro that decodes the arguments of an RPC request associated with +the RPC service transport handle, +.Fa xprt . +The parameter +.Fa in +is the address where the arguments will be placed; +.Fa inproc +is the XDR routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero otherwise. +.It Fn svc_getcaller +The obsolete way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.Fa xprt , +use +.Fn svc_getrpccaller . +.It Fn svc_getreqset +This routine is only of interest if a service implementor +does not call +.Fn svc_run , +but instead implements custom asynchronous event processing. +It is called when the +.Xr select 2 +system call has determined that an RPC request has arrived on some +RPC socket(s) ; +.Fa rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the +value of +.Fa rdfds +have been serviced. +.It Fn svc_getreq +Similar to +.Fn svc_getreqset , +but limited to 32 descriptors. +This interface is obsoleted by +.Fn svc_getreqset . +.It Fn svc_getrpccaller +The approved way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.Fa xprt . +.It Fn svc_register +Associates +.Fa prognum +and +.Fa versnum +with the service dispatch procedure, +.Fa dispatch . +If +.Fa protocol +is zero, the service is not registered with the +.Xr rpcbind 8 +service. +If +.Fa protocol +is non-zero, then a mapping of the triple +.Fa [ prognum , +.Fa versnum , +.Fa protocol ] +to +.Fa xprt->xp_port +is established with the local +.Xr rpcbind 8 +service (generally +.Fa protocol +is zero, +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP ) . +The procedure +.Fa dispatch +has the following form: +.Ft int +.Fn dispatch "struct svc_req *request" "SVCXPRT *xprt" . +.Pp +The +.Fn svc_register +routine returns one if it succeeds, and zero otherwise. +.It Fn svc_run +This routine never returns. +It waits for RPC requests to arrive, and calls the appropriate service +procedure using +.Fn svc_getreq +when one arrives. +This procedure is usually waiting for a +.Xr select 2 +system call to return. +.It Fn svc_sendreply +Called by an RPC service's dispatch routine to send the results of a +remote procedure call. +The parameter +.Fa xprt +is the request's associated transport handle; +.Fa xdr_results +is the XDR routine which is used to encode the results; and +.Fa xdr_location +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.It Fn svc_unregister +Remove all mapping of the double +.Fa [ prognum , +.Fa versnum ] +to dispatch routines, and of the triple +.Fa [ prognum , +.Fa versnum , +.Fa * ] +to port number. +.It Fn svcerr_auth +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.It Fn svcerr_decode +Called by a service dispatch routine that cannot successfully +decode its parameters. +See also +.Fn svc_getargs . +.It Fn svcerr_noproc +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.It Fn svcerr_noprog +Called when the desired program is not registered with the RPC +package. +Service implementors usually do not need this routine. +.It Fn svcerr_progvers +Called when the desired version of a program is not registered +with the RPC package. +Service implementors usually do not need this routine. +.\" TODO: document low_vers and high_vers +.It Fn svcerr_systemerr +Called by a service dispatch routine when it detects a system error +not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.It Fn svcerr_weakauth +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient +authentication parameters. +The routine calls +.Fn svcerr_auth "xprt" "AUTH_TOOWEAK" . +.It Fn svcraw_create +This routine creates a toy RPC service transport, to which it returns +a pointer. +The transport is really a buffer within the process's address space, +so the corresponding RPC client should live in the same address space; +see +.Fn clntraw_create . +This routine allows simulation of RPC and acquisition of RPC overheads +(such as round trip times), without any kernel interference. +This routine returns +.Dv NULL +if it fails. +.It Fn svctcp_create +This routine creates a TCP/IP-based RPC service transport, to which it +returns a pointer. +The transport is associated with the socket +.Fa sock , +which may be +.Dv RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local TCP +port, then this routine binds it to an arbitrary port. +Upon completion, +.Fa xprt->xp_sock +is the transport's socket descriptor, and +.Fa xprt->xp_port +is the transport's port number. +This routine returns +.Dv NULL +if it fails. +Since TCP-based RPC uses buffered I/O , +users may specify the size of buffers; values of zero +choose suitable defaults. +.It Fn svcfd_create +Create a service on top of any open descriptor. +Typically, this descriptor is a connected socket +for a stream protocol such as TCP. +.Fa sendsize +and +.Fa recvsize +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. +.It Fn svcudp_bufcreate +This routine creates a UDP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.Fa sock , +which may be +.Dv RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local UDP +port, then this routine binds it to an arbitrary port. +Upon completion, +.Fa xprt->xp_sock +is the transport's socket descriptor, and +.Fa xprt->xp_port +is the transport's port number. +This routine returns +.Dv NULL +if it fails. +.Pp +This allows the user to specify the maximum packet size for sending and +receiving UDP-based RPC messages. +.It Fn svcudp_create +This acts as +.Fn svcudp_bufcreate +with predefined sizes for the maximum packet sizes. +.It Fn xdr_accepted_reply +Used for encoding RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xdr_authunix_parms +Used for describing UNIX credentials. +This routine is useful for users who wish to generate these +credentials without using the RPC authentication package. +.It Fn xdr_callhdr +Used for describing RPC call header messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xdr_callmsg +Used for describing RPC call messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xdr_opaque_auth +Used for describing RPC authentication information messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xdr_pmap +Used for describing parameters to various +.Xr rpcbind 8 +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the +.Em pmap +interface. +.It Fn xdr_pmaplist +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the +.Em pmap +interface. +.It Fn xdr_rejected_reply +Used for describing RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xdr_replymsg +Used for describing RPC reply messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.It Fn xprt_register +After RPC service transport handles are created, +they should register themselves with the RPC service package. +This routine modifies the global variable +.Va svc_fds . +Service implementors usually do not need this routine. +.It Fn xprt_unregister +Before an RPC service transport handle is destroyed, +it should unregister itself with the RPC service package. +This routine modifies the global variable +.Va svc_fds . +Service implementors usually do not need this routine. +.El +.Sh SEE ALSO +.\".Xr rpc_secure 3 , +.Xr xdr 3 +.Pp +The following manuals: +.Rs +.%B Remote Procedure Calls: Protocol Specification +.Re +.Rs +.%B Remote Procedure Call Programming Guide +.Re +.Rs +.%B rpcgen Programming Guide +.Re +.Pp +.Rs +.%A Sun Microsystems, Inc., USC-ISI +.%T "RPC: Remote Procedure Call Protocol Specification" +.%J RFC +.%V 1050 +.Re diff --git a/static/netbsd/man3/rpc_svc_calls.3 b/static/netbsd/man3/rpc_svc_calls.3 new file mode 100644 index 00000000..f9060d1d --- /dev/null +++ b/static/netbsd/man3/rpc_svc_calls.3 @@ -0,0 +1,253 @@ +.\" @(#)rpc_svc_calls.3n 1.28 93/05/10 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_svc_calls 1.5 89/07/25 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_svc_calls.3,v 1.13 2017/10/25 16:49:24 abhinav Exp $ +.Dd May 3, 1993 +.Dt RPC_SVC_CALLS 3 +.Os +.Sh NAME +.Nm svc_dg_enablecache , +.Nm svc_exit , +.Nm svc_fdset , +.Nm svc_freeargs , +.Nm svc_getargs , +.Nm svc_getreq_common , +.Nm svc_getreq_poll , +.Nm svc_getreqset , +.Nm svc_getrpccaller , +.Nm __svc_getcallercreds , +.Nm svc_pollset , +.Nm svc_run , +.Nm svc_sendreply +.Nd library routines for RPC servers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft int +.Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size" +.Ft void +.Fn svc_exit "void" +.Ft bool_t +.Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in" +.Ft bool_t +.Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in" +.Ft void +.Fn svc_getreq_common "const int fd" +.Ft void +.Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval" +.Ft void +.Fn svc_getreqset "fd_set * rdfds" +.Ft "struct netbuf *" +.Fn svc_getrpccaller "const SVCXPRT *xprt" +.Ft "struct sockcred *" +.Fn __svc_getcallercreds "const SVCXPRT *xprt" +.Vt struct pollfd svc_pollset[FD_SETSIZE]; +.Ft void +.Fn svc_run "void" +.Ft bool_t +.Fn svc_sendreply "const SVCXPRT *xprt" "const xdrproc_t outproc" "const caddr_t *out" +.Sh DESCRIPTION +These routines are part of the +RPC +library which allows C language programs to make procedure +calls on other machines across the network. +.Pp +These routines are associated with the server side of the +RPC mechanism. +Some of them are called by the server side dispatch function, +while others +(such as +.Fn svc_run ) +are called when the server is initiated. +.\" .Pp +.\" In the current implementation, the service transport handle, +.\" .Dv SVCXPRT , +.\" contains a single data area for decoding arguments and encoding results. +.\" Therefore, this structure cannot be freely shared between threads that call +.\" functions that do this. Routines on this page that are affected by this +.\" restriction are marked as unsafe for MT applications. +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Dv SVCXPRT +data structure. +.Bl -tag -width __svc_getcallercreds() +.It Fn svc_dg_enablecache +This function allocates a duplicate request cache for the +service endpoint +.Fa xprt , +large enough to hold +.Fa cache_size +entries. +Once enabled, there is no way to disable caching. +This routine returns 0 if space necessary for a cache of the given size +was successfully allocated, and 1 otherwise. +.It Fn svc_exit +This function when called by any of the RPC server procedure or +otherwise, causes +.Fn svc_run +to return. +.Pp +As currently implemented, +.Fn svc_exit +zeroes the +.Dv svc_fdset +global variable. +If RPC server activity is to be resumed, +services must be reregistered with the RPC library +either through one of the +.Fn rpc_svc_create +functions, or using +.Fn xprt_register . +.Fn svc_exit +has global scope and ends all RPC server activity. +.Ft "fd_set svc_fdset" +A global variable reflecting the +RPC server's read file descriptor bit mask; it is suitable as a parameter +to the +.Xr select 2 +system call. +This is only of interest +if service implementors do not call +.Fn svc_run , +but rather do their own asynchronous event processing. +This variable is read-only (do not pass its address to +.Xr select 2 ! ) , +yet it may change after calls to +.Fn svc_getreqset +or any creation routines. +.It Fn svc_freeargs +A function macro that frees any data allocated by the +RPC/XDR system when it decoded the arguments to a service procedure +using +.Fn svc_getargs . +This routine returns +.Dv TRUE +if the results were successfully +freed, and +.Dv FALSE +otherwise. +.It Fn svc_getargs +A function macro that decodes the arguments of an +RPC request associated with the RPC +service transport handle +.Fa xprt . +The parameter +.Fa in +is the address where the arguments will be placed; +.Fa inproc +is the XDR +routine used to decode the arguments. +This routine returns +.Dv TRUE +if decoding succeeds, and +.Dv FALSE +otherwise. +.It Fn svc_getreq_common +This routine is called to handle a request on the given +file descriptor. +.It Fn svc_getreq_poll +This routine is only of interest if a service implementor +does not call +.Fn svc_run , +but instead implements custom asynchronous event processing. +It is called when +.Xr poll 2 +has determined that an RPC request has arrived on some RPC +file descriptors; +.Fn pollretval +is the return value from +.Xr poll 2 +and +.Fa pfdp +is the array of +.Fa pollfd +structures on which the +.Xr poll 2 +was done. +It is assumed to be an array large enough to +contain the maximal number of descriptors allowed. +.It Fn svc_getreqset +This routine is only of interest if a service implementor +does not call +.Fn svc_run , +but instead implements custom asynchronous event processing. +It is called when +.Xr poll 2 +has determined that an RPC +request has arrived on some RPC file descriptors; +.Fa rdfds +is the resultant read file descriptor bit mask. +The routine returns when all file descriptors +associated with the value of +.Fa rdfds +have been serviced. +.It Fn svc_getrpccaller +The approved way of getting the network address of the caller +of a procedure associated with the +RPC service transport handle +.Fa xprt . +.It Fn __svc_getcallercreds +.Em Warning: this macro is specific to +.Nx +.Em and thus not portable. +This macro returns a pointer to a sockcred structure, defined in +.In sys/socket.h , +identifying the calling client. +This only works if the client is calling the server over an +.Dv AF_LOCAL +socket. +.It Fa struct pollfd svc_pollset[FD_SETSIZE]; +.Va svc_pollset +is an array of +.Vt pollfd +structures derived from +.Va svc_fdset[] . +It is suitable as a parameter to the +.Xr poll 2 +system call. +The derivation of +.Va svc_pollset +from +.Va svc_fdset +is made in the current implementation in +.Fn svc_run . +Service implementors who do not call +.Fn svc_run +and who wish to use this array must perform this derivation themselves. +.It Fn svc_run +This routine never returns. +It waits for RPC +requests to arrive, and calls the appropriate service +procedure using +.Fn svc_getreq_poll +when one arrives. +This procedure is usually waiting for the +.Xr poll 2 +system call to return. +.It Fn svc_sendreply +Called by an RPC service's dispatch routine to send the results of a +remote procedure call. +The parameter +.Fa xprt +is the request's associated transport handle; +.Fa outproc +is the XDR +routine which is used to encode the results; and +.Fa out +is the address of the results. +This routine returns +.Dv TRUE +if it succeeds, +.Dv FALSE +otherwise. +.El +.Sh SEE ALSO +.Xr poll 2 , +.Xr rpc 3 , +.Xr rpc_svc_create 3 , +.Xr rpc_svc_err 3 , +.Xr rpc_svc_reg 3 diff --git a/static/netbsd/man3/rpc_svc_create.3 b/static/netbsd/man3/rpc_svc_create.3 new file mode 100644 index 00000000..ff07a526 --- /dev/null +++ b/static/netbsd/man3/rpc_svc_create.3 @@ -0,0 +1,315 @@ +.\" @(#)rpc_svc_create.3n 1.26 93/08/26 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_svc_create 1.3 89/06/28 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_svc_create.3,v 1.11 2010/03/22 19:30:54 joerg Exp $ +.Dd May 3, 1993 +.Dt RPC_SVC_CREATE 3 +.Os +.Sh NAME +.Nm rpc_svc_create , +.Nm svc_control , +.Nm svc_create , +.Nm svc_destroy , +.Nm svc_dg_create , +.Nm svc_fd_create , +.Nm svc_raw_create , +.Nm svc_tli_create , +.Nm svc_tp_create , +.Nm svc_vc_create +.Nd library routines for the creation of server handles +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft bool_t +.Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info" +.Ft int +.Fn svc_create "const void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" +.Ft SVCXPRT *" +.Fn svc_dg_create "const int fildes" "const u_int sendsz" "const u_int recvsz" +.Ft void +.Fn svc_destroy "SVCXPRT *xprt" +.Ft "SVCXPRT *" +.Fn svc_fd_create "const int fildes" "const u_int sendsz" "const u_int recvsz" +.Ft "SVCXPRT *" +.Fn svc_raw_create "void" +.Ft "SVCXPRT *" +.Fn svc_tli_create "const int fildes" "const struct netconfig *netconf" "const struct t_bind *bindaddr" "const u_int sendsz" "const u_int recvsz" +.Ft "SVCXPRT *" +.Fn svc_tp_create "const void (*dispatch)(const struct svc_reg *, const SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" +.Ft "SVCXPRT *" +.Fn svc_vc_create "const int fildes" "const u_int sendsz" "const u_int recvsz" +.Sh DESCRIPTION +These routines are part of the RPC +library which allows C language programs to make procedure +calls on servers across the network. +These routines deal with the creation of service handles. +Once the handle is created, the server can be invoked by calling +.Fn svc_run . +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Dv SVCXPRT +data structure. +.Pp +.Bl -tag -width XXXXX +.It Fn svc_control +A function to change or retrieve various information +about a service object. +.Fa req +indicates the type of operation and +.Fa info +is a pointer to the information. +The supported values of +.Fa req , +their argument types, and what they do are: +.Bl -tag -width SVCGET_XID +.It Dv SVCGET_VERSQUIET +If a request is received for a program number +served by this server but the version number +is outside the range registered with the server, +an +.Dv RPC_PROGVERSMISMATCH +error will normally +be returned. +.Fa info +should be a pointer to an integer. +Upon successful completion of the +.Dv SVCGET_VERSQUIET +request, +.Fa *info +contains an +integer which describes the server's current +behavior: 0 indicates normal server behavior +(that is, an +.Dv RPC_PROGVERSMISMATCH +error +will be returned); 1 indicates that the out of +range request will be silently ignored. +.Pp +.It Dv SVCSET_VERSQUIET +If a request is received for a program number +served by this server but the version number +is outside the range registered with the server, +an +.Dv RPC_PROGVERSMISMATCH +error will normally be returned. +It is sometimes desirable to change this behavior. +.Fa info +should be a +pointer to an integer which is either 0 +(indicating normal server behavior - an +.Dv RPC_PROGVERSMISMATCH +error will be returned), +or 1 (indicating that the out of range request +should be silently ignored). +.El +.Pp +.It Fn svc_create +.Fn svc_create +creates server handles for all the transports +belonging to the class +.Fa nettype . +.Fa nettype +defines a class of transports which can be used +for a particular application. +The transports are tried in left to right order in +.Ev NETPATH +variable or in top to bottom order in the netconfig database. +If +.Fa nettype +is +.Dv NULL , +it defaults to +.Dv netpath . +.Pp +.Fn svc_create +registers itself with the rpcbind +service (see +.Xr rpcbind 8 ) . +.Fa dispatch +is called when there is a remote procedure call for the given +.Fa prognum +and +.Fa versnum ; +this requires calling +.Fn svc_run +(see +.Fn svc_run +in +.Xr rpc_svc_reg 3 ) . +If +.Fn svc_create +succeeds, it returns the number of server +handles it created, +otherwise it returns 0 and an error message is logged. +.Pp +.It Fn svc_destroy +A function macro that destroys the RPC +service handle +.Fa xprt . +Destruction usually involves deallocation +of private data structures, +including +.Fa xprt +itself. +Use of +.Fa xprt +is undefined after calling this routine. +.Pp +.It Fn svc_dg_create +This routine creates a connectionless RPC +service handle, and returns a pointer to it. +This routine returns +.Dv NULL +if it fails, and an error message is logged. +.Fa sendsz +and +.Fa recvsz +are parameters used to specify the size of the buffers. +If they are 0, suitable defaults are chosen. +The file descriptor +.Fa fildes +should be open and bound. +The server is not registered with +.Xr rpcbind 8 . +.Em Warning : +since connectionless-based RPC +messages can only hold limited amount of encoded data, +this transport cannot be used for procedures +that take large arguments or return huge results. +.Pp +.It Fn svc_fd_create +This routine creates a service on top of an open and bound file descriptor, +and returns the handle to it. +Typically, this descriptor is a connected file descriptor for a +connection-oriented transport. +.Fa sendsz +and +.Fa recvsz +indicate sizes for the send and receive buffers. +If they are 0, reasonable defaults are chosen. +This routine returns +.Dv NULL +if it fails, and an error message is logged. +.Pp +.It Fn svc_raw_create +This routine creates an RPC +service handle and returns a pointer to it. +The transport is really a buffer within the process's +address space, so the corresponding RPC +client should live in the same address space; +(see +.Fn clnt_raw_create +in +.Xr rpc_clnt_create 3 ) . +This routine allows simulation of RPC and acquisition of +RPC overheads (such as round trip times), +without any kernel and networking interference. +This routine returns +.Dv NULL +if it fails, and an error message is logged. +.Em Note : +.Fn svc_run +should not be called when the raw interface is being used. +.Pp +.It Fn svc_tli_create +This routine creates an RPC +server handle, and returns a pointer to it. +.Fa fildes +is the file descriptor on which the service is listening. +If +.Fa fildes +is +.Dv RPC_ANYFD , +it opens a file descriptor on the transport specified by +.Fa netconf . +If the file descriptor is unbound and +.Fa bindaddr +is non-null +.Fa fildes +is bound to the address specified by +.Fa bindaddr , +otherwise +.Fa fildes +is bound to a default address chosen by the transport. +.Pp +Note: the +.Vt t_bind +structure comes from the TLI/XTI SysV interface, which +.Nx +does not use. +The structure is defined in +.In rpc/types.h +for compatibility as: +.Bd -literal +struct t_bind { + struct netbuf addr; /* network address, see rpc(3) */ + unsigned int qlen; /* queue length (for listen(2)) */ +}; +.Ed +.Pp +In the case where the default address is chosen, +the number of outstanding connect requests is set to 8 +for connection-oriented transports. +The user may specify the size of the send and receive buffers +with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of 0 choose suitable defaults. +This routine returns +.Dv NULL +if it fails, +and an error message is logged. +The server is not registered with the +.Xr rpcbind 8 +service. +.Pp +.It Fn svc_tp_create +.Fn svc_tp_create +creates a server handle for the network +specified by +.Fa netconf , +and registers itself with the rpcbind service. +.Fa dispatch +is called when there is a remote procedure call +for the given +.Fa prognum +and +.Fa versnum ; +this requires calling +.Fn svc_run . +.Fn svc_tp_create +returns the service handle if it succeeds, +otherwise a +.Dv NULL +is returned and an error message is logged. +.Pp +.It Fn svc_vc_create +This routine creates a connection-oriented RPC +service and returns a pointer to it. +This routine returns +.Dv NULL +if it fails, and an error message is logged. +The users may specify the size of the send and receive buffers +with the parameters +.Fa sendsz +and +.Fa recvsz ; +values of 0 choose suitable defaults. +The file descriptor +.Fa fildes +should be open and bound. +The server is not registered with the +.Xr rpcbind 8 +service. +.El +.Sh SEE ALSO +.Xr rpc 3 , +.Xr rpc_svc_calls 3 , +.Xr rpc_svc_err 3 , +.Xr rpc_svc_reg 3 , +.Xr rpcbind 8 diff --git a/static/netbsd/man3/rpc_svc_err.3 b/static/netbsd/man3/rpc_svc_err.3 new file mode 100644 index 00000000..0eb0ebc3 --- /dev/null +++ b/static/netbsd/man3/rpc_svc_err.3 @@ -0,0 +1,101 @@ +.\" @(#)rpc_svc_err.3n 1.23 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_svc_err 1.4 89/06/28 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_svc_err.3,v 1.6 2003/04/16 13:34:43 wiz Exp $ +.Dd May 3, 1993 +.Dt RPC_SVC_ERR 3 +.Os +.Sh NAME +.Nm rpc_svc_err , +.Nm svcerr_auth , +.Nm svcerr_decode , +.Nm svcerr_noproc , +.Nm svcerr_noprog , +.Nm svcerr_progvers , +.Nm svcerr_systemerr , +.Nm svcerr_weakauth +.Nd library routines for server side remote procedure call errors +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft void +.Fn svcerr_auth "const SVCXPRT1 *xprt" "const enum auth_stat why" +.Ft void +.Fn svcerr_decode "const SVCXPRT *xprt" +.Ft void +.Fn svcerr_noproc "const SVCXPRT *xprt" +.Ft void +.Fn svcerr_noprog "const SVCXPRT *xprt" +.Ft void +.Fn svcerr_progvers "const SVCXPRT *xprt" "rpcvers_t low_vers" "rpcvers_t high_vers" +.Ft void +.Fn svcerr_systemerr "const SVCXPRT *xprt" +.Ft void +.Fn svcerr_weakauth "const SVCXPRT *xprt" +.Sh DESCRIPTION +These routines are part of the RPC +library which allows C language programs to make procedure +calls on other machines across the network. +.Pp +These routines can be called by the server side +dispatch function if there is any error in the +transaction with the client. +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Vt SVCXPRT +data structure. +.Pp +.Bl -tag -width XXXXX +.It Fn svcerr_auth +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.Pp +.Fn svcerr_decode +Called by a service dispatch routine that cannot successfully +decode the remote parameters +(see +.Fn svc_getargs +in +.Xr rpc_svc_reg 3 ) . +.Pp +.It Fn svcerr_noproc +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.Pp +.It Fn svcerr_noprog +Called when the desired program is not registered with the +RPC package. +Service implementors usually do not need this routine. +.Pp +.It Fn svcerr_progvers +Called when the desired version of a program is not registered with the +RPC package. +.Fa low_vers +is the lowest version number, +and +.Fa high_vers +is the highest version number. +Service implementors usually do not need this routine. +.Pp +.It Fn svcerr_systemerr +Called by a service dispatch routine when it detects a system +error not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.Pp +.It Fn svcerr_weakauth +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient (but correct) +authentication parameters. +The routine calls +.Fn svcerr_auth "xprt" "AUTH_TOOWEAK" . +.El +.Sh SEE ALSO +.Xr rpc 3 , +.Xr rpc_svc_calls 3 , +.Xr rpc_svc_create 3 , +.Xr rpc_svc_reg 3 diff --git a/static/netbsd/man3/rpc_svc_reg.3 b/static/netbsd/man3/rpc_svc_reg.3 new file mode 100644 index 00000000..d5f90978 --- /dev/null +++ b/static/netbsd/man3/rpc_svc_reg.3 @@ -0,0 +1,196 @@ +.\" @(#)rpc_svc_reg.3n 1.32 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_svc_call 1.6 89/07/20 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_svc_reg.3,v 1.11 2017/07/03 21:32:49 wiz Exp $ +.Dd May 3, 1993 +.Dt RPC_SVC_REG 3 +.Os +.Sh NAME +.Nm rpc_svc_reg , +.Nm rpc_reg , +.Nm svc_reg , +.Nm svc_unreg , +.Nm svc_auth_reg , +.Nm xprt_register , +.Nm xprt_unregister +.Nd library routines for registering servers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft bool_t +.Fn rpc_reg "const rpcprog_t prognum" "const rpcvers_t versnum" "const rpcproc_t procnum" "const char *(*procname)()" "const xdrproc_t inproc" "const xdrproc_t outproc" "const char *nettype" +.Ft int +.Fn svc_reg "const SVCXPRT *xprt" "const rpcprog_t prognum" "const rpcvers_t versnum" "const void (*dispatch(struct svc_req *, SVCXPRT *)" "const struct netconfig *netconf" +.Ft void +.Fn svc_unreg "const rpcprog_t prognum" "const rpcvers_t versnum" +.Ft int +.Fn svc_auth_reg "const int cred_flavor" "const enum auth_stat (*handler(struct svc_req *, struct rpc_msg *))" +.Ft bool_t +.Fn xprt_register "const SVCXPRT *xprt" +.Ft void +.Fn xprt_unregister "const SVCXPRT *xprt" +.Sh DESCRIPTION +These routines are a part of the RPC +library which allows the RPC +servers to register themselves with rpcbind +(see +.Xr rpcbind 8 ) , +and associate the given program and version +number with the dispatch function. +When the RPC server receives a RPC request, the library invokes the +dispatch routine with the appropriate arguments. +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Vt SVCXPRT +data structure. +.Pp +.Bl -tag -width XXXXX +.It Fn rpc_reg +Register program +.Fa prognum , +procedure +.Fa procname , +and version +.Fa versnum +with the RPC +service package. +If a request arrives for program +.Fa prognum , +version +.Fa versnum , +and procedure +.Fa procnum , +.Fa procname +is called with a pointer to its parameter(s); +.Fa procname +should return a pointer to its static result(s); +.Fa inproc +is the XDR function used to decode the parameters while +.Fa outproc +is the XDR function used to encode the results. +Procedures are registered on all available transports of the class +.Fa nettype . +See +.Xr rpc 3 . +This routine returns 0 if the registration succeeded, +-1 otherwise. +.Pp +.It Fn svc_reg +Associates +.Fa prognum +and +.Fa versnum +with the service dispatch procedure, +.Fa dispatch . +If +.Fa netconf +is +.Dv NULL , +the service is not registered with the +.Xr rpcbind 8 +service. +If +.Fa netconf +is non-zero, +then a mapping of the triple +[ +.Fa prognum , +.Fa versnum , +.Fa netconf->nc_netid ] +to +.Fa xprt->xp_ltaddr +is established with the local rpcbind +service. +.Pp +The +.Fn svc_reg +routine returns 1 if it succeeds, +and 0 otherwise. +.Pp +.It Fn svc_unreg +Remove from the rpcbind +service, all mappings of the triple +[ +.Fa prognum , +.Fa versnum , +all-transports ] +to network address +and all mappings within the RPC service package +of the double +[ +.Fa prognum , +.Fa versnum ] +to dispatch routines. +.Pp +.It Fn svc_auth_reg +Registers the service authentication routine +.Fa handler +with the dispatch mechanism so that it can be +invoked to authenticate RPC requests received +with authentication type +.Fa cred_flavor . +This interface allows developers to add new authentication +types to their RPC applications without needing to modify +the libraries. +Service implementors usually do not need this routine. +.Pp +Typical service application would call +.Fn svc_auth_reg +after registering the service and prior to calling +.Fn svc_run . +When needed to process an RPC credential of type +.Fa cred_flavor , +the +.Fa handler +procedure will be called with two parameters +.Fa "struct svc_req *rqst" , +and +.Fa "struct rpc_msg * msg" , +and is expected to return a valid +.Vt "enum auth_stat" +value. +There is no provision to change or delete an authentication handler +once registered. +.Pp +The +.Fn svc_auth_reg +routine returns 0 if the registration is successful, +1 if +.Fa cred_flavor +already has an authentication handler registered for it, +and -1 otherwise. +.Pp +.It Fn xprt_register +After RPC service transport handle +.Fa xprt +is created, it is registered with the RPC +service package. +This routine modifies the global variable +.Va svc_fdset +(see +.Xr rpc_svc_calls 3 ) . +Service implementors usually do not need this routine. +.Pp +.It Fn xprt_unregister +Before an RPC service transport handle +.Fa xprt +is destroyed, it unregisters itself with the +RPC service package. +This routine modifies the global variable +.Va svc_fdset +(see +.Xr rpc_svc_calls 3 ) . +Service implementors usually do not need this routine. +.El +.Sh SEE ALSO +.Xr select 2 , +.Xr rpc 3 , +.Xr rpc_svc_calls 3 , +.Xr rpc_svc_create 3 , +.Xr rpc_svc_err 3 , +.Xr rpcbind 3 , +.Xr rpcbind 8 diff --git a/static/netbsd/man3/rpc_xdr.3 b/static/netbsd/man3/rpc_xdr.3 new file mode 100644 index 00000000..62e7c85f --- /dev/null +++ b/static/netbsd/man3/rpc_xdr.3 @@ -0,0 +1,100 @@ +.\" @(#)rpc_xdr.3n 1.24 93/08/31 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" @(#)rpc_xdr.new 1.1 89/04/06 SMI; +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpc_xdr.3,v 1.8 2009/04/11 16:03:29 joerg Exp $ +.Dd May 3, 1993 +.Dt RPC_XDR 3 +.Os +.Sh NAME +.Nm xdr_accepted_reply , +.Nm xdr_authsys_parms , +.Nm xdr_callhdr , +.Nm xdr_callmsg , +.Nm xdr_opaque_auth , +.Nm xdr_rejected_reply , +.Nm xdr_replymsg +.Nd XDR library routines for remote procedure calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft bool_t +.Fn xdr_accepted_reply "XDR *xdrs" "const struct accepted_reply *ar" +.Ft bool_t +.Fn xdr_authsys_parms "XDR *xdrs" "struct authsys_parms *aupp" +.Ft void +.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr" +.Ft bool_t +.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg" +.Ft bool_t +.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap" +.Ft bool_t +.Fn xdr_rejected_reply "XDR *xdrs" "const struct rejected_reply *rr" +.Ft bool_t +.Fn xdr_replymsg "XDR *xdrs" "const struct rpc_msg *rmsg" +.Sh DESCRIPTION +These routines are used for describing the +RPC messages in XDR language. +They should normally be used by those who do not +want to use the RPC +package directly. +These routines return TRUE if they succeed, FALSE otherwise. +.Sh ROUTINES +See +.Xr rpc 3 +for the definition of the +.Vt XDR +data structure. +.Pp +.Bl -tag -width XXXXX +.It Fn xdr_accepted_reply +Used to translate between RPC +reply messages and their external representation. +It includes the status of the RPC +call in the XDR language format. +In the case of success, it also includes the call results. +.Pp +.It Fn xdr_authsys_parms +Used for describing UNIX operating system credentials. +It includes machine-name, uid, gid list, etc. +.Pp +.It Fn xdr_callhdr +Used for describing RPC call header messages. +It encodes the static part of the call message header in the +XDR language format. +It includes information such as transaction +ID, RPC version number, program and version number. +.Pp +.It Fn xdr_callmsg +Used for describing +RPC call messages. +This includes all the RPC +call information such as transaction +ID, RPC version number, program number, version number, +authentication information, etc. +This is normally used by servers to determine information about the client +RPC call. +.Pp +.It Fn xdr_opaque_auth +Used for describing RPC +opaque authentication information messages. +.Pp +.It Fn xdr_rejected_reply +Used for describing RPC reply messages. +It encodes the rejected RPC message in the XDR language format. +The message could be rejected either because of version +number mis-match or because of authentication errors. +.Pp +.It Fn xdr_replymsg +Used for describing RPC +reply messages. +It translates between the +RPC reply message and its external representation. +This reply could be either an acceptance, +rejection or +.Dv NULL . +.El +.Sh SEE ALSO +.Xr rpc 3 , +.Xr xdr 3 diff --git a/static/netbsd/man3/rpcbind.3 b/static/netbsd/man3/rpcbind.3 new file mode 100644 index 00000000..e02bd641 --- /dev/null +++ b/static/netbsd/man3/rpcbind.3 @@ -0,0 +1,201 @@ +.\" @(#)rpcbind.3n 1.25 93/05/07 SMI; from SVr4 +.\" Copyright 1989 AT&T +.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" $NetBSD: rpcbind.3,v 1.12 2017/07/03 21:32:49 wiz Exp $ +.Dd December 4, 2005 +.Dt RPCBIND 3 +.Os +.Sh NAME +.Nm rpcb_getmaps , +.Nm rpcb_getaddr , +.Nm rpcb_gettime , +.Nm rpcb_rmtcall , +.Nm rpcb_set , +.Nm rpcb_unset +.Nd library routines for RPC bind service +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft "struct rpcblist *" +.Fn rpcb_getmaps "const struct netconfig *netconf" "const char *host" +.Ft bool_t +.Fn rpcb_getaddr "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const char *host" +.Ft bool_t +.Fn rpcb_gettime "const char *host" "time_t * timep" +.Ft "enum clnt_stat" +.Fn rpcb_rmtcall "const struct netconfig *netconf" "const char *host" "const rpcprog_t prognum, const rpcvers_t versnum" "const rpcproc_t procnum, const xdrproc_t inproc" "const char *in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout, struct netbuf *svcaddr" +.Ft bool_t +.Fn rpcb_set "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct netbuf *svcaddr" +.Ft bool_t +.Fn rpcb_unset "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" +.Sh DESCRIPTION +These routines allow client C programs to make procedure +calls to the RPC binder service. +(see +.Xr rpcbind 8 ) +maintains a list of mappings between programs +and their universal addresses. +.Sh ROUTINES +.Bl -tag -width XXXXX +.It Fn rpcb_getmaps +An interface to the rpcbind service, +which returns a list of the current +RPC program-to-address mappings on +.Fa host . +It uses the transport specified through +.Fa netconf +to contact the remote rpcbind +service on +.Fa host . +This routine will return +.Dv NULL , +if the remote rpcbind could not be contacted. +.Pp +.It Fn rpcb_getaddr +An interface to the rpcbind +service, which finds the address of the service on +.Fa host +that is registered with program number +.Fa prognum , +version +.Fa versnum , +and speaks the transport protocol associated with +.Fa netconf . +The address found is returned in +.Fa svcaddr . +.Fa svcaddr +should be preallocated. +This routine returns +.Dv TRUE +if it succeeds. +A return value of +.Dv FALSE +means that the mapping does not exist +or that the RPC +system failed to contact the remote +rpcbind service. +In the latter case, the global variable +.Va rpc_createerr +(see +.Xr rpc_clnt_create 3 +contains the +RPC status. +.Pp +.It Fn rpcb_gettime +This routine returns the time on +.Fa host +in +.Fa timep . +If +.Fa host +is +.Dv NULL , +.Fn rpcb_gettime +returns the time on its own machine. +This routine returns +.Dv TRUE +if it succeeds, +.Dv FALSE +if it fails. +.Fn rpcb_gettime +can be used to synchronize the time between the +client and the remote server. +.Pp +.It Fn rpcb_rmtcall +An interface to the rpcbind service, which instructs +rpcbind on +.Fa host +to make an RPC +call on your behalf to a procedure on that host. +The +.Fn netconfig +structure should correspond to a connectionless transport. +The parameter +.Fa svcaddr +will be modified to the server's address if the procedure succeeds +(see +.Fn rpc_call +and +.Fn clnt_call +in +.Xr rpc_clnt_calls 3 +for the definitions of other parameters). +.Pp +This procedure should normally be used for a +``ping'' and nothing else. +This routine allows programs to do lookup and call, all in one step. +.Pp +Note: Even if the server is not running +.Fn rpcb_rmtcall +does not return any error messages to the caller. +In such a case, the caller times out. +.Pp +Note: +.Fn rpcb_rmtcall +is only available for connectionless transports. +.Pp +.It Fn rpcb_set +An interface to the rpcbind +service, which establishes a mapping between the triple +[ +.Fa prognum , +.Fa versnum , +.Fa netconf->nc_netid ] +and +.Fa svcaddr +on the machine's rpcbind +service. +The value of +.Fa nc_netid +must correspond to a network identifier that is defined by the +netconfig database. +This routine returns +.Dv TRUE +if it succeeds, +.Dv FALSE +otherwise. +(See also +.Fn svc_reg +in +.Xr rpc_svc_calls 3 . +If there already exists such an entry with rpcbind, +.Fn rpcb_set +will fail. +.Pp +.It Fn rpcb_unset +An interface to the rpcbind +service, which destroys the mapping between the triple +[ +.Fa prognum , +.Fa versnum , +.Fa netconf->nc_netid ] +and the address on the machine's rpcbind +service. +If +.Fa netconf +is +.Dv NULL , +.Fn rpcb_unset +destroys all mapping between the triple +[ +.Fa prognum , +.Fa versnum , +.Fa all-transports ] +and the addresses on the machine's rpcbind service. +This routine returns +.Dv TRUE +if it succeeds, +.Dv FALSE +otherwise. +Only the owner of the service or the super-user can destroy the mapping. +(See also +.Fn svc_unreg +in +.Xr rpc_svc_calls 3 . +.El +.Sh SEE ALSO +.Xr rpc_clnt_calls 3 , +.Xr rpc_svc_calls 3 , +.Xr rpcbind 8 , +.Xr rpcinfo 8 diff --git a/static/netbsd/man3/rs256_pk_new.3 b/static/netbsd/man3/rs256_pk_new.3 new file mode 100644 index 00000000..0c0ab78b --- /dev/null +++ b/static/netbsd/man3/rs256_pk_new.3 @@ -0,0 +1,160 @@ +.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd $Mdocdate: July 15 2022 $ +.Dt RS256_PK_NEW 3 +.Os +.Sh NAME +.Nm rs256_pk_new , +.Nm rs256_pk_free , +.Nm rs256_pk_from_RSA , +.Nm rs256_pk_from_EVP_PKEY , +.Nm rs256_pk_from_ptr , +.Nm rs256_pk_to_EVP_PKEY +.Nd FIDO2 COSE RS256 API +.Sh SYNOPSIS +.In openssl/rsa.h +.In fido/rs256.h +.Ft rs256_pk_t * +.Fn rs256_pk_new "void" +.Ft void +.Fn rs256_pk_free "rs256_pk_t **pkp" +.Ft int +.Fn rs256_pk_from_EVP_PKEY "rs256_pk_t *pk" "const EVP_PKEY *pkey" +.Ft int +.Fn rs256_pk_from_RSA "rs256_pk_t *pk" "const RSA *rsa" +.Ft int +.Fn rs256_pk_from_ptr "rs256_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn rs256_pk_to_EVP_PKEY "const rs256_pk_t *pk" +.Sh DESCRIPTION +RS256 is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256. +The COSE RS256 API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +RSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +RS256 public keys are abstracted by the +.Vt rs256_pk_t +type. +.Pp +The +.Fn rs256_pk_new +function returns a pointer to a newly allocated, empty +.Vt rs256_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn rs256_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn rs256_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn rs256_pk_free +is a NOP. +.Pp +The +.Fn rs256_pk_from_EVP_PKEY +function fills +.Fa pk +with the contents of +.Fa pkey . +No references to +.Fa pkey +are kept. +.Pp +The +.Fn rs256_pk_from_RSA +function fills +.Fa pk +with the contents of +.Fa rsa . +No references to +.Fa rsa +are kept. +.Pp +The +.Fn rs256_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn rs256_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn rs256_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn rs256_pk_from_EVP_PKEY , +.Fn rs256_pk_from_RSA , +and +.Fn rs256_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr eddsa_pk_new 3 , +.Xr es256_pk_new 3 , +.Xr es384_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 diff --git a/static/netbsd/man3/rtbl.3 b/static/netbsd/man3/rtbl.3 new file mode 100644 index 00000000..27acb112 --- /dev/null +++ b/static/netbsd/man3/rtbl.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: rtbl.3,v 1.5 2023/06/19 21:41:45 christos Exp $ +.\" +.\" Copyright (c) 2004 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" Id +.\" +.Dd June 26, 2004 +.Dt RTBL 3 +.Os +.Sh NAME +.Nm rtbl_create , +.Nm rtbl_destroy , +.Nm rtbl_set_flags , +.Nm rtbl_get_flags , +.Nm rtbl_set_prefix , +.Nm rtbl_set_separator , +.Nm rtbl_set_column_prefix , +.Nm rtbl_set_column_affix_by_id , +.Nm rtbl_add_column , +.Nm rtbl_add_column_by_id , +.Nm rtbl_add_column_entry , +.Nm rtbl_add_column_entry_by_id , +.Nm rtbl_new_row , +.Nm rtbl_format +.Nd format data in simple tables +.Sh LIBRARY +The roken library (libroken, -lroken) +.Sh SYNOPSIS +.In rtbl.h +.Ft int +.Fn rtbl_add_column "rtbl_t table" "const char *column_name" "unsigned int flags" +.Ft int +.Fn rtbl_add_column_by_id "rtbl_t table" "unsigned int column_id" "const char *column_header" "unsigned int flags" +.Ft int +.Fn rtbl_add_column_entry "rtbl_t table" "const char *column_name" "const char *cell_entry" +.Ft int +.Fn rtbl_add_column_entry_by_id "rtbl_t table" "unsigned int column_id" "const char *cell_entry" +.Ft rtbl_t +.Fn rtbl_create "void" +.Ft void +.Fn rtbl_destroy "rtbl_t table" +.Ft int +.Fn rtbl_new_row "rtbl_t table" +.Ft int +.Fn rtbl_set_column_affix_by_id "rtbl_t table" "unsigned int column_id "const char *prefix" "const char *suffix" +.Ft int +.Fn rtbl_set_column_prefix "rtbl_t table" "const char *column_name" "const char *prefix" +.Ft "unsigned int" +.Fn rtbl_get_flags "rtbl_t table" +.Ft void +.Fn rtbl_set_flags "rtbl_t table" "unsigned int flags" +.Ft int +.Fn rtbl_set_prefix "rtbl_t table" "const char *prefix" +.Ft int +.Fn rtbl_set_separator "rtbl_t table" "const char *separator" +.Ft int +.Fn rtbl_format "rtbl_t table "FILE *file" +.Sh DESCRIPTION +This set of functions assemble a simple table consisting of rows and +columns, allowing it to be printed with certain options. Typical use +would be output from tools such as +.Xr ls 1 +or +.Xr netstat 1 , +where you have a fixed number of columns, but don't know the column +widths before hand. +.Pp +A table is created with +.Fn rtbl_create +and destroyed with +.Fn rtbl_destroy . +.Pp +Global flags on the table are set with +.Fa rtbl_set_flags +and retrieved with +.Fa rtbl_get_flags . +At present the only defined flag is +.Dv RTBL_HEADER_STYLE_NONE +which suppresses printing the header. +.Pp +Before adding data to the table, one or more columns need to be +created. This would normally be done with +.Fn rtbl_add_column_by_id , +.Fa column_id +is any number of your choice (it's used only to identify columns), +.Fa column_header +is the header to print at the top of the column, and +.Fa flags +are flags specific to this column. Currently the only defined flag is +.Dv RTBL_ALIGN_RIGHT , +aligning column entries to the right. Columns are printed in the order +they are added. +.Pp +There's also a way to add columns by column name with +.Fn rtbl_add_column , +but this is less flexible (you need unique header names), and is +considered deprecated. +.Pp +To add data to a column you use +.Fn rtbl_add_column_entry_by_id , +where the +.Fa column_id +is the same as when the column was added (adding data to a +non-existent column is undefined), and +.Fa cell_entry +is whatever string you wish to include in that cell. It should not +include newlines. +For columns added with +.Fn rtbl_add_column +you must use +.Fn rtbl_add_column_entry +instead. +.Pp +.Fn rtbl_new_row +fills all columns with blank entries until they all have the same +number of rows. +.Pp +Each column can have a separate prefix and suffix, set with +.Fa rtbl_set_column_affix_by_id ; +.Fa rtbl_set_column_prefix +allows setting the prefix only by column name. In addition to this, +columns may be separated by a string set with +.Fa rtbl_set_separator ( Ns +by default columns are not seprated by anything). +.Pp +The finished table is printed to +.Fa file +with +.Fa rtbl_format . +.Sh EXAMPLES +This program: +.Bd -literal -offset xxxx +#include <stdio.h> +#include <rtbl.h> +int +main(int argc, char **argv) +{ + rtbl_t table; + table = rtbl_create(); + rtbl_set_separator(table, " "); + rtbl_add_column_by_id(table, 0, "Column A", 0); + rtbl_add_column_by_id(table, 1, "Column B", RTBL_ALIGN_RIGHT); + rtbl_add_column_by_id(table, 2, "Column C", 0); + rtbl_add_column_entry_by_id(table, 0, "A-1"); + rtbl_add_column_entry_by_id(table, 0, "A-2"); + rtbl_add_column_entry_by_id(table, 0, "A-3"); + rtbl_add_column_entry_by_id(table, 1, "B-1"); + rtbl_add_column_entry_by_id(table, 2, "C-1"); + rtbl_add_column_entry_by_id(table, 2, "C-2"); + rtbl_add_column_entry_by_id(table, 1, "B-2"); + rtbl_add_column_entry_by_id(table, 1, "B-3"); + rtbl_add_column_entry_by_id(table, 2, "C-3"); + rtbl_add_column_entry_by_id(table, 0, "A-4"); + rtbl_new_row(table); + rtbl_add_column_entry_by_id(table, 1, "B-4"); + rtbl_new_row(table); + rtbl_add_column_entry_by_id(table, 2, "C-4"); + rtbl_new_row(table); + rtbl_format(table, stdout); + rtbl_destroy(table); + return 0; +} +.Ed +.Pp +will output the following: +.Bd -literal -offset xxxx +Column A Column B Column C +A-1 B-1 C-1 +A-2 B-2 C-2 +A-3 B-3 C-3 +A-4 + B-4 + C-4 +.Ed +.\" .Sh SEE ALSO diff --git a/static/netbsd/man3/rump.3 b/static/netbsd/man3/rump.3 new file mode 100644 index 00000000..d217713d --- /dev/null +++ b/static/netbsd/man3/rump.3 @@ -0,0 +1,55 @@ +.\" $NetBSD: rump.3,v 1.12 2014/12/02 01:52:13 pooka Exp $ +.\" +.\" Copyright (c) 2008-2011 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 1, 2014 +.Dt RUMP 3 +.Os +.Sh NAME +.Nm librump +.Nd Rump kernel base +.Sh LIBRARY +rump kernel base (librump, \-lrump) +.Sh SYNOPSIS +.In rump/rump.h +.In rump/rump_syscalls.h +.Sh DESCRIPTION +The base of a +.Xr rumpkernel 7 +is provided by the +.Nm +library. +In addition to fundamental routines such as kernel memory allocators +and locking, +.Nm +provides system call wrappers. +.Pp +Like the +.Xr rumpuser 3 +library, +.Nm +is a mandatory component and is present in every rump kernel. +.Sh SEE ALSO +.Xr rumpuser 3 , +.Xr rumpkernel 7 diff --git a/static/netbsd/man3/rump_etfs.3 b/static/netbsd/man3/rump_etfs.3 new file mode 100644 index 00000000..719d6673 --- /dev/null +++ b/static/netbsd/man3/rump_etfs.3 @@ -0,0 +1,213 @@ +.\" $NetBSD: rump_etfs.3,v 1.4 2015/06/12 17:50:01 dholland Exp $ +.\" +.\" Copyright (c) 2010 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 27, 2014 +.Dt RUMP_ETFS 3 +.Os +.Sh NAME +.Nm rump_etfs +.Nd rump kernel host file system interface +.Sh LIBRARY +rump kernel (librump, \-lrump) +.Sh SYNOPSIS +.In rump/rump.h +.Ft int +.Fo rump_pub_etfs_register +.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype" +.Fc +.Ft int +.Fo rump_pub_etfs_register_withsize +.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype" +.Fa "uint64_t begin" "uint64_t size" +.Fc +.Ft void +.Fn rump_boot_etfs_register "struct rump_boot_etfs *eb" +.Ft int +.Fn rump_pub_etfs_remove "const char *key" +.Sh DESCRIPTION +The rump ExtraTerrestrial File System +.Nm ( ) +is used to provide access to the host file system namespace +within a rump kernel. +.Pp +The operation is based on registered +.Fa key +values which each map to a +.Fa hostpath . +A key must be an absolute path (i.e. begin with +.Dq / ) . +Multiple leading slashes are collapsed to one (i.e. +.Dq /key +is the same as +.Dq //key ) . +The rest of the path, including slashes, is compared verbatim (i.e. +.Dq /key/path +does not match +.Dq /key//path ) . +.Pp +The +.Fa hostpath +is interpreted in host system context for the current working directory +and can be either absolute or relative. +.Pp +The +.Fa key +is accessible from all rump kernel clients, both local and remote. +Note: the keys are not visible via readdir, so you will not see +them in directory listings. +.Pp +The +.Fa ftype +parameter specifies how the etfs file will be presented and does not +have to match the host type, although some limitations apply. +Possible values are: +.Bl -tag -width RUMP_ETFS_DIR_SUBDIRSXXX +.It Dv RUMP_ETFS_REG +regular file. +.It Dv RUMP_ETFS_BLK +block device. +This is often used when mapping file system images. +.It Dv RUMP_ETFS_CHR +character device. +.It Dv RUMP_ETFS_DIR +directory. +This option is valid only when +.Fa hostpath +is a directory. +The immediate children of the host directory will be accessible +inside a rump kernel. +.It Dv RUMP_ETFS_DIR_SUBDIRS +directory. +This option is valid only when +.Fa hostpath +is a directory. +This option recursively applies to all subdirectories, and allows +a rump kernel to access an entire directory tree. +.El +.Pp +The interfaces are: +.Bl -tag -width xxxx +.It Fn rump_pub_etfs_register "key" "hostpath" "ftype" +Map +.Fa key +to a file of type +.Fa ftype +with the contents of +.Fa hostpath . +.It Fn rump_pub_etfs_register_withsize "key" "hostpath" "ftype" "begin" "size" +Like the above, but map only +.Fa [ begin , begin+size ] +from +.Fa hostpath . +This is useful when mapping disk images where only one partition is +relevant to the application. +If +.Ar size +is given the special value +.Dv RUMP_ETFS_SIZE_ENDOFF , +the underlying file is mapped from +.Ar begin +to the end of the file. +.It Fn rump_boot_etfs_register "eb" +Unlike the above interfaces, +.Fn rump_boot_etfs_register +can and must be called before +.Fn rump_init . +It causes an etfs key to be available immediately when the root file +system is mounted as part of +.Fn rump_init . +The intended use is for example for firmware images to be available +immediately when device driver autoconfiguration is run as part of +.Fn rump_init . +.Pp +To use +.Fn rump_boot_etfs_register , +the client fills out +.Fa eb . +The layout of +.Fa eb +is as follows: +.Bd -literal +struct rump_boot_etfs { + /* client initializes */ + const char *eb_key; + const char *eb_hostpath; + enum rump_etfs_type eb_type; + uint64_t eb_begin; + uint64_t eb_size; + + /* rump kernel initializes */ + struct rump_boot_etfs *_eb_next; + int eb_status; +}; +.Ed +.Pp +All of the client fields must be initialized before the call. +See +.Fn rump_pub_etfs_register_withsize +for descriptions of the fields. +After the function has been called, the client may not touch the +structure memory or the pathname pointers. +After +.Fn rump_init +returns, the client may check the status of the registration from +.Fa eb_status +and free the structure. +A value of \-1 designates that the etfs registration was not +performed, 0 designates success and a value larger than 0 designates +an errno. +The client must serialize calls to +.Fn rump_boot_etfs_register . +.It Fn rump_pub_etfs_remove "key" +Remove etfs mapping for +.Fa key . +This routine may be called only if the file related to the mapping +is not in use. +.El +.Sh RETURN VALUES +.Nm +routines return 0 on success or an errno indicating the reason for failure. +.Sh EXAMPLES +Map a host image file to a mountable +.Pa /dev/harddisk +path using window offsets from the disklabel. +.Bd -literal -offset indent +rump_pub_etfs_register_withsize("/dev/harddisk", "disk.img", + RUMP_ETFS_BLK, + pp->p_offset << DEV_BSHIFT, pp->p_size << DEV_BSHIFT); +.Ed +.Pp +Make the host kernel module directory hierarchy available within the +rump kernel. +.Bd -literal -offset indent +rump_pub_etfs_register("/stand/i386/5.99.41", + "/stand/i386/5.99.41", RUMP_ETFS_DIR_SUBDIRS); +.Ed +.Sh SEE ALSO +.Xr rump 3 +.Sh HISTORY +.Nm +first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/rump_lwproc.3 b/static/netbsd/man3/rump_lwproc.3 new file mode 100644 index 00000000..8b0afb6d --- /dev/null +++ b/static/netbsd/man3/rump_lwproc.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: rump_lwproc.3,v 1.2 2015/03/23 15:42:29 pooka Exp $ +.\" +.\" Copyright (c) 2010 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 27, 2014 +.Dt RUMP_LWPROC 3 +.Os +.Sh NAME +.Nm rump_lwproc +.Nd rump kernel process/lwp management +.Sh LIBRARY +rump kernel (librump, \-lrump) +.Sh SYNOPSIS +.In rump/rump.h +.Ft int +.Fn rump_pub_lwproc_rfork "int flags" +.Ft int +.Fn rump_pub_lwproc_newlwp "pid_t pid" +.Ft void +.Fn rump_pub_lwproc_switch "struct lwp *l" +.Ft void +.Fn rump_pub_lwproc_releaselwp +.Ft struct lwp * +.Fn rump_pub_lwproc_curlwp +.Sh DESCRIPTION +In a normal operating system model a process is a resource +container and a thread (lwp) is the execution context. +Every lwp is associated with exactly one process, and a process is +associated with one or more lwps. +The current lwp (curlwp) indicates the current process and determines +which resources, such as UID/GID, current working directory, and +file descriptor table, are currently used. +These basic principles apply to rump kernels as well, but since +a rump kernel uses the host's thread and process context directly, the rules +for how thread context is determined are different. +.Pp +In the rump kernel model, each host thread (implemented for example +with pthreads or green threads) is either bound to +a rump kernel lwp or accesses the rump kernel with an implicit thread +context associated with pid 1. +An implicit thread context is created every time the rump kernel +is entered and disbanded upon exit. +While convenient for occasional calls, creating an implicit thread +uses a shared resource which can become highly contended in a +multithreaded situation. +It is therefore recommended that dedicated threads are created. +.Pp +The association between host threads and the rump kernel curlwp is +left to the caller. +It is possible to create a dedicated host thread for every +rump kernel lwp or multiplex them on top of a single host thread. +After rump kernel lwps have been created, switching curlwp is very cheap. +In case multiple lwps/processes are created, it is the caller's +responsibility to keep track of them and release them when they +are no longer necessary. +A rump kernel lwp will persist until it is explicitly released. +A rump kernel process will persist until all of its lwps have been +released, at which point the process is automatically released. +.Bl -tag -width xxxx +.It Fn rump_pub_lwproc_rfork +Create a process, one lwp inside it and set curlwp to the new lwp. +The +.Ar flags +parameter controls how file descriptors are inherited from the +parent. +By default (flags=0) file descriptors are shared. +Other options are: +.Bl -tag -width RUMP_RFCFDGXX +.It Dv RUMP_RFFDG +Copy file descriptors from parent. +This is what +.Xr fork 2 +does. +.It Dv RUMP_RFCFDG +File descriptors neither copied nor shared, i.e. new process does not +have access to the parent's file descriptors. +.El +.Pp +This routine returns 0 for success or an errno indicating the reason +for failure. +The new process id can be retrieved in the normal fashion by calling +.Fn rump_sys_getpid . +.It Fn rump_pub_lwproc_newlwp "pid" +Create a new lwp attached to the process specified by +.Fa pid . +Sets curlwp to the new lwp. +This routine returns 0 for success or an errno indicating the reason +for failure. +.It Fn rump_pub_lwproc_switch "l" +Sets curlwp to +.Fa l . +In case the new thread is associated with a different process than the +current one, the process context is also switched. +The special value +.Dv NULL +sets curlwp to implicit context. +Switching to an already running lwp, i.e. attempting to use the +same curlwp in two host threads simultaneously causes a fatal error. +.It Fn rump_pub_lwproc_releaselwp +Release curlwp and set curlwp to implicit context. +In case curlwp was the last thread inside the current process, the +process container is also released. +Calling this routine without a dedicated curlwp is a fatal error. +.It Fn rump_pub_lwproc_curlwp +Returns curlwp or +.Dv NULL +if the current context is an implicit context. +.El +.Sh RETURN VALUES +.Fn rump_pub_lwproc_rfork +and +.Fn rump_pub_lwproc_newlwp +return 0 on success or an errno indicating the reason for failure. +.Fn rump_pub_lwproc_curlwp +returns curlwp or +.Dv NULL +if the current context is an implicit context. +.Sh SEE ALSO +.Xr getpid 2 , +.Xr rump 3 +.Sh HISTORY +.Nm +first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/rumpclient.3 b/static/netbsd/man3/rumpclient.3 new file mode 100644 index 00000000..48f0d14b --- /dev/null +++ b/static/netbsd/man3/rumpclient.3 @@ -0,0 +1,204 @@ +.\" $NetBSD: rumpclient.3,v 1.3 2013/03/08 08:30:44 wiz Exp $ +.\" +.\" Copyright (c) 2011 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 16, 2011 +.Dt RUMPCLIENT 3 +.Os +.Sh NAME +.Nm rumpclient +.Nd rump client library +.Sh LIBRARY +.Lb rumpclient +.Sh SYNOPSIS +.In rump/rumpclient.h +.In rump/rump_syscalls.h +.Ft int +.Fn rumpclient_init +.Ft pid_t +.Fn rumpclient_fork +.Ft pid_t +.Fn rumpclient_vfork +.Ft struct rumpclient_fork * +.Fn rumpclient_prefork +.Ft int +.Fn rumpclient_fork_init "struct rumpclient_fork *rfp" +.Ft void +.Fn rumpclient_fork_cancel "struct rumpclient_fork *rfp" +.Ft int +.Fn rumpclient_exec "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn rumpclient_daemon "int nochdir" "int noclose" +.Ft void +.Fn rumpclient_setconnretry "time_t retrytime" +.Ft int +.Fo rumpclient_syscall +.Fa "int num" "const void *sysarg" "size_t argsize" "register_t *retval" +.Fc +.Sh DESCRIPTION +.Nm +is the clientside implementation of the +.Xr rump_sp 7 +facility. +It can be used to connect to a rump kernel server and make system call +style requests. +.Pp +Every connection to a rump kernel server creates a new process +context in the rump kernel. +By default a process is inherited from init, but through existing +connections and the forking facility offered by +.Nm +it is possible to form process trees. +.Bl -tag -width xxxx +.It Fn rumpclient_init +Initialize +.Nm . +The server address is determined from the environment variable +.Ev RUMP_SERVER +according to syntax described in +.Xr rump_sp 7 . +The new process is registered to the rump kernel with the command +name from +.Xr getprogname 3 . +.It Fn rumpclient_fork +Fork a rump client process. +This also causes a host process fork via +.Xr fork 2 . +The child will have a copy of the parent's rump kernel file descriptors. +.It Fn rumpclient_vfork +Like above, but the host uses +.Xr vfork 2 . +.It Fn rumpclient_prefork +Low-level routine which instructs the rump kernel that the current +process is planning to fork. +The routine returns a +.Pf non- Dv NULL +cookie if successful. +.It Fn rumpclient_fork_init rfp +Low-level routine which works like +.Fn rumpclient_init , +with the exception that it uses the +.Ar rfp +context created by a call to +.Fn rumpclient_prefork . +This is typically called from the child of a +.Xr fork 2 +call. +.It Fn rumpclient_fork_cancel rfp +Cancel previously initiated prefork context. +This is useful for error handling in case a full fork could not +be carried through. +.It Fn rumpclient_exec path argv envp +This call is a +.Nm +wrapper around +.Xr execve 2 . +The wrapper makes sure that the rump kernel process context stays +the same in the newly executed program. +This means that the rump kernel PID remains the same and the same +rump file descriptors are available (apart from ones which +were marked with +.Dv FD_CLOEXEC ) . +.Pp +It should be noted that the newly executed program must call +.Fn rumpclient_init +before any other rump kernel communication can take place. +The wrapper cannot do it because it no longer has program control. +However, since all rump clients call the init routine, +this should not be a problem. +.It Fn rumpclient_daemon noclose nochdir +This function performs the equivalent of +.Xr daemon 3 , +but also ensures that the internal call to +.Xr fork 2 +is handled properly. +This routine is provided for convenience. +.It Fn rumpclient_setconnretry retrytime +Set the timeout for how long the client attempts to reconnect to +the server in case of a broken connection. +After the timeout expires the client will return a failure +for that particular request. +It is critical to note that after a restablished connection the +rump kernel context will be that of a newly connected client. +This means all previous kernel state such as file descriptors +will be lost. +It is largely up to a particular application if this has impact +or not. +For example, web browsers tend to recover fairly smoothly from a +kernel server reconnect, while +.Xr sshd 8 +gets confused if its sockets go missing. +.Pp +If +.Ar retrytime +is a positive integer, it means the number of seconds for which +reconnection will be attempted. +The value 0 means that reconnection will not be attempted, and all +subsequent operations will return the errno +.Er ENOTCONN . +.Pp +Additionally, the following special values are accepted: +.Bl -tag -width xxxx +.It Dv RUMPCLIENT_RETRYCONN_INFTIME +Attempt reconnection indefinitely. +.It Dv RUMPCLIENT_RETRYCONN_ONCE +Attempt reconnect exactly once. +What this precisely means depends on the situation: e.g. getting +.Er EHOSTUNREACH +immediately or the TCP connection request timeouting are considered +to be one retry. +.It Dv RUMPCLIENT_RETRYCONN_DIE +In case of a broken connection is detected at runtime, call +.Xr exit 3 . +This is useful for example in testing. +It ensures that clients are killed immediately when they attempt +to communicate with a halted server. +.El +.It Fn rumpclient_syscall num sysarg argsize retval +Execute an "indirect" system call. +In the normal case system calls are executed through the interfaces in +.In rump/rump_syscalls.h +(for example +.Fn rump_sys_read fd buf nbytes ) . +This interface allows calling the server with pre-marshalled arguments. +.El +.Pp +Additionally, all of the supported rump system calls are available +through this library. +See +.In rump/rump_syscalls.h +for a list. +.Sh RETURN VALUES +.Nm +routines return \-1 in case of error and set errno. +In case of success a non-negative integer is returned, where applicable. +.Sh SEE ALSO +.Xr rump_server 1 , +.Xr rump 3 , +.Xr rump_sp 7 +.Sh CAVEATS +Interfaces for a cryptographically authenticated client-server +handshake do not currently exist. +This can be worked around with e.g. host access control and an ssh +tunnel. diff --git a/static/netbsd/man3/rumphijack.3 b/static/netbsd/man3/rumphijack.3 new file mode 100644 index 00000000..fed7dc22 --- /dev/null +++ b/static/netbsd/man3/rumphijack.3 @@ -0,0 +1,243 @@ +.\" $NetBSD: rumphijack.3,v 1.13 2018/12/16 14:03:37 hannken Exp $ +.\" +.\" Copyright (c) 2011 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 16, 2018 +.Dt RUMPHIJACK 3 +.Os +.Sh NAME +.Nm rumphijack +.Nd System call hijack library +.Sh LIBRARY +used by +.Xr ld.so 1 +.Sh DESCRIPTION +The +.Xr ld.so 1 +runtime linker can be instructed to load +.Nm +between the main object and other libraries. +This enables +.Nm +to capture and redirect system call requests to a rump kernel instead +of the host kernel. +.Pp +The behaviour of hijacked applications is affected by the following +environment variables: +.Bl -tag -width 12345 +.It Ev RUMPHIJACK +If present, this variable specifies which system calls should be +hijacked. +The string is parsed as a comma-separated list of +.Dq name=value +tuples. +The possible lefthandside names are: +.Bl -tag -width xxblanketxx +.It Dq path +Pathname-based system calls are hijacked if the path the system +call is directed to resides under +.Ar value . +In case of an absolute pathname argument, a literal prefix comparison is made. +In case of a relative pathname, the current working direct is +examined. +This also implies that neither +.Dq .. +nor symbolic links will cause the namespace to be switched. +.It Dq blanket +A colon-separated list of rump path prefixes. +This acts almost like +.Dq path +with the difference that the prefix does not get removed when +passing the path to the rump kernel. +For example, if +.Dq path +is +.Pa /rump , +accessing +.Pa /rump/dev/bpf +will cause +.Pa /dev/bpf +to be accessed in the rump kernel. +In contrast, if +.Dq blanket +contains +.Pa /dev/bpf , +accessing +.Pa /dev/bpf +will cause an access to +.Pa /dev/bpf +in the rump kernel. +.Pp +In case the current working directory is changed to a blanketed +directory, the current working directory will still be reported +with the rump prefix, if available. +Note, though, that some shells cache the directory and may report +something else. +In case no rump path prefix has been configured, the raw rump +directory is reported. +.Pp +It is recommended to supply blanketed pathnames as specific as +possible, i.e. use +.Pa /dev/bpf +instead of +.Pa /dev +unless necessary to do otherwise. +Also, note that the blanket prefix does not follow directory borders. +In other words, setting the blanket for +.Pa /dev/bpf +means it is set for +.Em all +pathnames with the given prefix, not just ones in +.Pa /dev . +.It Dq socket +The specifier +.Ar value +contains a colon-separated list of which protocol families should +be hijacked. +The special value +.Dq all +can be specified as the first element. +It indicates that all protocol families should be hijacked. +Some can then be disabled by prepending +.Dq no +to the name of the protocol family. +.Pp +For example, +.Dq inet:inet6 +specifies that only +.Dv PF_INET +and +.Dv PF_INET6 +sockets should be hijacked, +while +.Dq all:noinet +specifies that all protocol families except +.Dv PF_INET +should be hijacked. +.It Dq vfs +The specifier +.Ar value +contains a colon-separated list of which vfs-related system calls +should be hijacked. +These differ from the pathname-based file system syscalls in that +there is no pathname to make the selection based on. +Current possible values are +.Dq nfssvc , +.Dq getvfsstat , +and +.Dq fhcalls . +They indicate hijacking +.Fn nfssvc , +.Fn getvfsstat , +and all file handle calls, respectively. +The file handle calls include +.Fn fhopen , +.Fn fhstat , +and +.Fn fhstatvfs1 . +.Pp +It is also possible to use +.Dq all +and +.Dq no +in the same fashion as with the socket hijack specifier. +.It Dq sysctl +Direct the +.Fn __sysctl +backend of the +.Xr sysctl 3 +facility to the rump kernel. +Acceptable values are +.Dq yes +and +.Dq no , +meaning to call the rump or the host kernel, respectively. +.It Dq modctl +Direct the +.Fn modctl +call to the rump kernel. +Acceptable values are +.Dq yes +and +.Dq no , +meaning to call the rump or the host kernel, respectively. +.It Dq fdoff +Adjust the library's fd offset to the specified value. +All rump kernel descriptors have the offset added to them +before they are returned to the application. +This should be changed only if the application defines a low non-default +.Dv FD_SETSIZE +for +.Fn select +or if it opens a very large number of file descriptors. +The default value is 128. +.El +.Pp +If the environment variable is unset, the default value +.Qq path=/rump,socket=all:nolocal +is used. +The rationale for this is to have networked X clients work +out-of-the-box: X clients use local sockets to communicate with +the server, so local sockets must be used as a host service. +.Pp +An empty string as a value means no calls are hijacked. +.It Ev RUMPHIJACK_RETRYCONNECT +Change how +.Xr rumpclient 3 +attempts to reconnect to the server in case the connection is lost. +Acceptable values are: +.Bl -tag -width xxinftimexx +.It Dq inftime +retry indefinitely +.It Dq once +retry once, when that connection fails, give up +.It Dq die +call +.Xr exit 3 +if connection failure is detected +.It n +Attempt reconnect for n seconds. +The value 0 means reconnection is not attempted. +The value n must be a positive integer. +.El +.Pp +See +.Xr rumpclient 3 +for more discussion. +.El +.Sh EXAMPLES +Use an alternate TCP/IP stack for firefox with a persistent server +connection: +.Bd -literal -offset indent +$ setenv RUMP_SERVER unix:///tmp/tcpip +$ setenv LD_PRELOAD /usr/lib/librumphijack.so +$ setenv RUMPHIJACK_RETRYCONNECT inftime +$ firefox +.Ed +.Sh SEE ALSO +.Xr ld.so 1 , +.Xr rump_server 1 , +.Xr rump 3 , +.Xr rumpclient 3 , +.Xr rump_sp 7 diff --git a/static/netbsd/man3/rumpuser.3 b/static/netbsd/man3/rumpuser.3 new file mode 100644 index 00000000..5b7540e9 --- /dev/null +++ b/static/netbsd/man3/rumpuser.3 @@ -0,0 +1,777 @@ +.\" $NetBSD: rumpuser.3,v 1.4 2023/07/14 23:21:53 lukem Exp $ +.\" +.\" Copyright (c) 2013 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 15, 2023 +.Dt RUMPUSER 3 +.Os +.Sh NAME +.Nm rumpuser +.Nd rump kernel hypercall interface +.Sh LIBRARY +rump User Library (librumpuser, \-lrumpuser) +.Sh SYNOPSIS +.In rump/rumpuser.h +.Sh DESCRIPTION +The +.Nm +hypercall interfaces allow a rump kernel to access host resources. +A hypervisor implementation must implement the routines described in +this document to allow a rump kernel to run on the host. +The implementation included in +.Nx +is for POSIX-like hosts (*BSD, Linux, etc.). +This document is divided into sections based on the functionality +group of each hypercall. +.Pp +Since the hypercall interface is a C function interface, both the +rump kernel and the hypervisor must conform to the same ABI. +The interface itself attempts to assume as little as possible from +the type systems, and for example +.Vt off_t +is passed as +.Vt int64_t +and enums are passed as ints. +It is recommended that the hypervisor converts these to the native +types before starting to process the hypercall, for example by +assigning the ints back to enums. +.Sh UPCALLS AND RUMP KERNEL CONTEXT +A hypercall is always entered with the calling thread scheduled in +the rump kernel. +In case the hypercall intends to block while waiting for an event, +the hypervisor must first release the rump kernel scheduling context. +In other words, the rump kernel context is a resource and holding +on to it while waiting for a rump kernel event/resource may lead +to a deadlock. +Even when there is no possibility of deadlock in the strict sense +of the term, holding on to the rump kernel context while performing +a slow hypercall such as reading a device will prevent other threads +(including the clock interrupt) from using that rump kernel context. +.Pp +Releasing the context is done by calling the +.Fn hyp_backend_unschedule +upcall which the hypervisor received from rump kernel as a parameter +for +.Fn rumpuser_init . +Before a hypercall returns back to the rump kernel, the returning thread +must carry a rump kernel context. +In case the hypercall unscheduled itself, it must reschedule itself +by calling +.Fn hyp_backend_schedule . +.Sh HYPERCALL INTERFACES +.Ss Initialization +.Ft int +.Fn rumpuser_init "int version" "struct rump_hyperup *hyp" +.Pp +Initialize the hypervisor. +.Bl -tag -width "xenum_rumpclock" +.It Fa version +hypercall interface version number that the kernel expects to be used. +In case the hypervisor cannot provide an exact match, this routine must +return a non-zero value. +.It Fa hyp +pointer to a set of upcalls the hypervisor can make into the rump kernel +.El +.Ss Memory allocation +.Ft int +.Fn rumpuser_malloc "size_t len" "int alignment" "void **memp" +.Bl -tag -width "xenum_rumpclock" +.It Fa len +amount of memory to allocate +.It Fa alignment +size the returned memory must be aligned to. +For example, if the value passed is 4096, the returned memory +must be aligned to a 4k boundary. +.It Fa memp +return pointer for allocated memory +.El +.Pp +.Ft void +.Fn rumpuser_free "void *mem" "size_t len" +.Bl -tag -width "xenum_rumpclock" +.It Fa mem +memory to free +.It Fa len +length of allocation. +This is always equal to the amount the caller requested from the +.Fn rumpuser_malloc +which returned +.Fa mem . +.El +.Ss Files and I/O +.Ft int +.Fn rumpuser_open "const char *name" "int mode" "int *fdp" +.Pp +Open +.Fa name +for I/O and associate a file descriptor with it. +Notably, there needs to be no mapping between +.Fa name +and the host's file system namespace. +For example, it is possible to associate the file descriptor with +device I/O registers for special values of +.Fa name . +.Bl -tag -width "xenum_rumpclock" +.It Fa name +the identifier of the file to open for I/O +.It Fa mode +combination of the following: +.Bl -tag -width "XRUMPUSER_OPEN_CREATE" +.It Dv RUMPUSER_OPEN_RDONLY +open only for reading +.It Dv RUMPUSER_OPEN_WRONLY +open only for writing +.It Dv RUMPUSER_OPEN_RDWR +open for reading and writing +.It Dv RUMPUSER_OPEN_CREATE +do not treat missing +.Fa name +as an error +.It Dv RUMPUSER_OPEN_EXCL +combined with +.Dv RUMPUSER_OPEN_CREATE , +flag an error if +.Fa name +already exists +.It Dv RUMPUSER_OPEN_BIO +the caller will use this file for block I/O, usually used in +conjunction with accessing file system media. +The hypervisor should treat this flag as advisory and possibly +enable some optimizations for +.Fa *fdp +based on it. +.El +Notably, the permissions of the created file are left up to the +hypervisor implementation. +.It Fa fdp +An integer value denoting the open file is returned here. +.El +.Pp +.Ft int +.Fn rumpuser_close "int fd" +.Pp +Close a previously opened file descriptor. +.Pp +.Ft int +.Fn rumpuser_getfileinfo "const char *name" "uint64_t *size" "int *type" +.Bl -tag -width "xenum_rumpclock" +.It Fa name +file for which information is returned. +The namespace is equal to that of +.Fn rumpuser_open . +.It Fa size +If +.Pf non- Dv NULL , +size of the file is returned here. +.It Fa type +If +.Pf non- Dv NULL , +type of the file is returned here. +The options are +.Dv RUMPUSER_FT_DIR , +.Dv RUMPUSER_FT_REG , +.Dv RUMPUSER_FT_BLK , +.Dv RUMPUSER_FT_CHR , +or +.Dv RUMPUSER_FT_OTHER +for directory, regular file, block device, character device or unknown, +respectively. +.El +.Pp +.Ft void +.Fo rumpuser_bio +.Fa "int fd" "int op" "void *data" "size_t dlen" "int64_t off" +.Fa "rump_biodone_fn biodone" "void *donearg" +.Fc +.Pp +Initiate block I/O and return immediately. +.Bl -tag -width "xenum_rumpclock" +.It Fa fd +perform I/O on this file descriptor. +The file descriptor must have been opened with +.Dv RUMPUSER_OPEN_BIO . +.It Fa op +Transfer data from the file descriptor with +.Dv RUMPUSER_BIO_READ +and transfer data to the file descriptor with +.Dv RUMPUSER_BIO_WRITE . +Unless +.Dv RUMPUSER_BIO_SYNC +is specified, the hypervisor may cache a write instead of +committing it to permanent storage. +.It Fa data +memory address to transfer data to/from +.It Fa dlen +length of I/O. +The length is guaranteed to be a multiple of 512. +.It Fa off +offset into +.Fa fd +where I/O is performed +.It Fa biodone +To be called when the I/O is complete. +Accessing +.Fa data +is not legal after the call is made. +.It Fa donearg +opaque arg that must be passed to +.Fa biodone . +.El +.Pp +.Ft int +.Fo rumpuser_iovread +.Fa "int fd" "struct rumpuser_iovec *ruiov" "size_t iovlen" +.Fa "int64_t off" "size_t *retv" +.Fc +.Pp +.Ft int +.Fo rumpuser_iovwrite +.Fa "int fd" "struct rumpuser_iovec *ruiov" "size_t iovlen" +.Fa "int64_t off" "size_t *retv" +.Fc +.Pp +These routines perform scatter-gather I/O which is not +block I/O by nature and therefore cannot be handled by +.Fn rumpuser_bio . +.Bl -tag -width "xenum_rumpclock" +.It Fa fd +file descriptor to perform I/O on +.It Fa ruiov +an array of I/O descriptors. +It is defined as follows: +.Bd -literal -offset indent -compact +struct rumpuser_iovec { + void *iov_base; + size_t iov_len; +}; +.Ed +.It Fa iovlen +number of elements in +.Fa ruiov +.It Fa off +offset of +.Fa fd +to perform I/O on. +This can either be a non-negative value or +.Dv RUMPUSER_IOV_NOSEEK . +The latter denotes that no attempt to change the underlying objects +offset should be made. +Using both types of offsets on a single instance of +.Fa fd +results in undefined behavior. +.It Fa retv +number of bytes successfully transferred is returned here +.El +.Pp +.Ft int +.Fo rumpuser_syncfd +.Fa "int fd" "int flags" "uint64_t start" "uint64_t len" +.Fc +.Pp +Synchronizes +.Fa fd +with respect to backing storage. +The other arguments are: +.Bl -tag -width "xenum_rumpclock" +.It Fa flags +controls how synchronization happens. +It must contain one of the following: +.Bl -tag -width "XRUMPUSER_SYNCFD_BARRIER" +.It Dv RUMPUSER_SYNCFD_READ +Make sure that the next read sees writes from all other parties. +This is useful for example in the case that +.Fa fd +represents memory to write a DMA read is being performed. +.It Dv RUMPUSER_SYNCFD_WRITE +Flush cached writes. +.El +.Pp +The following additional parameters may be passed in +.Fa flags : +.Bl -tag -width "XRUMPUSER_SYNCFD_BARRIER" +.It Dv RUMPUSER_SYNCFD_BARRIER +Issue a barrier. +Outstanding I/O operations which were started before the barrier +complete before any operations after the barrier are performed. +.It Dv RUMPUSER_SYNCFD_SYNC +Wait for the synchronization operation to fully complete before +returning. +For example, this could mean that the data to be written to a disk +has hit either the disk or non-volatile memory. +.El +.It Fa start +offset into the object. +.It Fa len +the number of bytes to synchronize. +The value 0 denotes until the end of the object. +.El +.Ss Clocks +The hypervisor should support two clocks, one for wall time and one +for monotonically increasing time, the latter of which may be based +on some arbitrary time (e.g. system boot time). +If this is not possible, the hypervisor must make a reasonable effort to +retain semantics. +.Pp +.Ft int +.Fn rumpuser_clock_gettime "int enum_rumpclock" "int64_t *sec" "long *nsec" +.Bl -tag -width "xenum_rumpclock" +.It Fa enum_rumpclock +specifies the clock type. +In case of +.Dv RUMPUSER_CLOCK_RELWALL +the wall time should be returned. +In case of +.Dv RUMPUSER_CLOCK_ABSMONO +the time of a monotonic clock should be returned. +.It Fa sec +return value for seconds +.It Fa nsec +return value for nanoseconds +.El +.Pp +.Ft int +.Fn rumpuser_clock_sleep "int enum_rumpclock" "int64_t sec" "long nsec" +.Bl -tag -width "xenum_rumpclock" +.It Fa enum_rumpclock +In case of +.Dv RUMPUSER_CLOCK_RELWALL , +the sleep should last at least as long as specified. +In case of +.Dv RUMPUSER_CLOCK_ABSMONO , +the sleep should last until the hypervisor monotonic clock hits +the specified absolute time. +.It Fa sec +sleep duration, seconds. +exact semantics depend on +.Fa clk . +.It Fa nsec +sleep duration, nanoseconds. +exact semantics depend on +.Fa clk . +.El +.Ss Parameter retrieval +.Ft int +.Fn rumpuser_getparam "const char *name" "void *buf" "size_t buflen" +.Pp +Retrieve a configuration parameter from the hypervisor. +It is up to the hypervisor to decide how the parameters can be set. +.Bl -tag -width "xenum_rumpclock" +.It Fa name +name of the parameter. +If the name starts with an underscore, it means a mandatory parameter. +The mandatory parameters are +.Dv RUMPUSER_PARAM_NCPU +which specifies the amount of virtual CPUs bootstrapped by the +rump kernel and +.Dv RUMPUSER_PARAM_HOSTNAME +which returns a preferably unique instance name for the rump kernel. +.It Fa buf +buffer to return the data in as a string +.It Fa buflen +length of buffer +.El +.Ss Termination +.Ft void +.Fn rumpuser_exit "int value" +.Pp +Terminate the rump kernel with exit value +.Fa value . +If +.Fa value +is +.Dv RUMPUSER_PANIC +the hypervisor should attempt to provide something akin to a core dump. +.Ss Console output +Console output is divided into two routines: a per-character +one and printf-like one. +The former is used e.g. by the rump kernel's internal printf +routine. +The latter can be used for direct debug prints e.g. very early +on in the rump kernel's bootstrap or when using the in-kernel +routine causes too much skew in the debug print results +(the hypercall runs outside of the rump kernel and therefore does not +cause any locking or scheduling events inside the rump kernel). +.Pp +.Ft void +.Fn rumpuser_putchar "int ch" +.Pp +Output +.Fa ch +on the console. +.Pp +.Ft void +.Fn rumpuser_dprintf "const char *fmt" "..." +.Pp +Do output based on printf-like parameters. +.Ss Signals +A rump kernel should be able to send signals to client programs +due to some standard interfaces including signal delivery in their +specifications. +Examples of these interfaces include +.Xr setitimer 2 +and +.Xr write 2 . +The +.Fn rumpuser_kill +function advises the hypercall implementation to raise a signal for the +process containing the rump kernel. +.Pp +.Ft int +.Fn rumpuser_kill "int64_t pid" "int sig" +.Bl -tag -width "xenum_rumpclock" +.It Fa pid +The pid of the rump kernel process that the signal is directed to. +This value may be used as the hypervisor as a hint on how to deliver +the signal. +The value +.Dv RUMPUSER_PID_SELF +may also be specified to indicate no hint. +This value will be removed in a future version of the hypercall interface. +.It Fa sig +Number of signal to raise. +The value is in +.Nx +signal number namespace. +In case the host has a native representation for signals, the +value should be translated before the signal is raised. +In case there is no mapping between +.Fa sig +and native signals (if any), the behavior is implementation-defined. +.El +.Pp +A rump kernel will ignore the return value of this hypercall. +The only implication of not implementing +.Fn rumpuser_kill +is that some application programs may not experience expected behavior +for standard interfaces. +.Pp +As an aside,the +.Xr rump_sp 7 +protocol provides equivalent functionality for remote clients. +.Ss Random pool +.Ft int +.Fn rumpuser_getrandom "void *buf" "size_t buflen" "int flags" "size_t *retp" +.Bl -tag -width "xenum_rumpclock" +.It Fa buf +buffer that the randomness is written to +.It Fa buflen +number of bytes of randomness requested +.It Fa flags +The value 0 or a combination of +.Dv RUMPUSER_RANDOM_HARD +(return true randomness instead of something from a PRNG) +and +.Dv RUMPUSER_RANDOM_NOWAIT +(do not block in case the requested amount of bytes is not available). +.It Fa retp +The number of random bytes written into +.Fa buf . +.El +.Ss Threads +.Ft int +.Fo rumpuser_thread_create +.Fa "void *(*fun)(void *)" "void *arg" "const char *thrname" "int mustjoin" +.Fa "int priority" "int cpuidx" "void **cookie" +.Fc +.Pp +Create a schedulable host thread context. +The rump kernel will call this interface when it creates a kernel thread. +The scheduling policy for the new thread is defined by the hypervisor. +In case the hypervisor wants to optimize the scheduling of the +threads, it can perform heuristics on the +.Fa thrname , +.Fa priority +and +.Fa cpuidx +parameters. +.Bl -tag -width "xenum_rumpclock" +.It Fa fun +function that the new thread must call. +This call will never return. +.It Fa arg +argument to be passed to +.Fa fun +.It Fa thrname +Name of the new thread. +.It Fa mustjoin +If 1, the thread will be waited for by +.Fn rumpuser_thread_join +when the thread exits. +.It Fa priority +The priority that the kernel requested the thread to be created at. +Higher values mean higher priority. +The exact kernel semantics for each value are not available through +this interface. +.It Fa cpuidx +The index of the virtual CPU that the thread is bound to, or \-1 +if the thread is not bound. +The mapping between the virtual CPUs and physical CPUs, if any, +is hypervisor implementation specific. +.It Fa cookie +In case +.Fa mustjoin +is set, the value returned in +.Fa cookie +will be passed to +.Fn rumpuser_thread_join . +.El +.Pp +.Ft void +.Fn rumpuser_thread_exit "void" +.Pp +Called when a thread created with +.Fn rumpuser_thread_create +exits. +.Pp +.Ft int +.Fn rumpuser_thread_join "void *cookie" +.Pp +Wait for a joinable thread to exit. +The cookie matches the value from +.Fn rumpuser_thread_create . +.Pp +.Ft void +.Fn rumpuser_curlwpop "int enum_rumplwpop" "struct lwp *l" +.Pp +Manipulate the hypervisor's thread context database. +The possible operations are create, destroy, and set as specified by +.Fa enum_rumplwpop : +.Bl -tag -width "XRUMPUSER_LWP_DESTROY" +.It Dv RUMPUSER_LWP_CREATE +Inform the hypervisor that +.Fa l +is now a valid thread context which may be set. +A currently valid value of +.Fa l +may not be specified. +This operation is informational and does not mandate any action +from the hypervisor. +.It Dv RUMPUSER_LWP_DESTROY +Inform the hypervisor that +.Fa l +is no longer a valid thread context. +This means that it may no longer be set as the current context. +A currently set context or an invalid one may not be destroyed. +This operation is informational and does not mandate any action +from the hypervisor. +.It Dv RUMPUSER_LWP_SET +Set +.Fa l +as the current host thread's rump kernel context. +A previous context must not exist. +.It Dv RUMPUSER_LWP_CLEAR +Clear the context previous set by +.Dv RUMPUSER_LWP_SET . +The value passed in +.Fa l +is the current thread and is never +.Dv NULL . +.El +.Pp +.Ft struct lwp * +.Fn rumpuser_curlwp "void" +.Pp +Retrieve the rump kernel thread context associated with the current host +thread, as set by +.Fn rumpuser_curlwpop . +This routine may be called when a context is not set and +the routine must return +.Dv NULL +in that case. +This interface is expected to be called very often. +Any optimizations pertaining to the execution speed of this routine +should be done in +.Fn rumpuser_curlwpop . +.Pp +.Ft void +.Fn rumpuser_seterrno "int errno" +.Pp +Set an errno value in the calling thread's TLS. +Note: this is used only if rump kernel clients make rump system calls. +.Ss Mutexes, rwlocks and condition variables +The locking interfaces have standard semantics, so we will not +discuss each one in detail. +The data types +.Vt struct rumpuser_mtx , +.Vt struct rumpuser_rw +and +.Vt struct rumpuser_cv +used by these interfaces are opaque to the rump kernel, i.e. the +hypervisor has complete freedom over them. +.Pp +Most of these interfaces will (and must) relinquish the rump kernel +CPU context in case they block (or intend to block). +The exceptions are the "nowrap" variants of the interfaces which +may not relinquish rump kernel context. +.Pp +.Ft void +.Fn rumpuser_mutex_init "struct rumpuser_mtx **mtxp" "int flags" +.Pp +.Ft void +.Fn rumpuser_mutex_enter "struct rumpuser_mtx *mtx" +.Pp +.Ft void +.Fn rumpuser_mutex_enter_nowrap "struct rumpuser_mtx *mtx" +.Pp +.Ft int +.Fn rumpuser_mutex_tryenter "struct rumpuser_mtx *mtx" +.Pp +.Ft void +.Fn rumpuser_mutex_exit "struct rumpuser_mtx *mtx" +.Pp +.Ft void +.Fn rumpuser_mutex_destroy "struct rumpuser_mtx *mtx" +.Pp +.Ft void +.Fn rumpuser_mutex_owner "struct rumpuser_mtx *mtx" "struct lwp **lp" +.Pp +Mutexes provide mutually exclusive locking. +The flags, of which at least one must be given, are as follows: +.Bl -tag -width "XRUMPUSER_MTX_KMUTEX" +.It Dv RUMPUSER_MTX_SPIN +Create a spin mutex. +Locking this type of mutex must not relinquish rump kernel context +even when +.Fn rumpuser_mutex_enter +is used. +.It Dv RUMPUSER_MTX_KMUTEX +The mutex must track and be able to return the rump kernel thread +that owns the mutex (if any). +If this flag is not specified, +.Fn rumpuser_mutex_owner +will never be called for that particular mutex. +.El +.Pp +.Ft void +.Fn rumpuser_rw_init "struct rumpuser_rw **rwp" +.Pp +.Ft void +.Fn rumpuser_rw_enter "int enum_rumprwlock" "struct rumpuser_rw *rw" +.Pp +.Ft int +.Fn rumpuser_rw_tryenter "int enum_rumprwlock" "struct rumpuser_rw *rw" +.Pp +.Ft int +.Fn rumpuser_rw_tryupgrade "struct rumpuser_rw *rw" +.Pp +.Ft void +.Fn rumpuser_rw_downgrade "struct rumpuser_rw *rw" +.Pp +.Ft void +.Fn rumpuser_rw_exit "struct rumpuser_rw *rw" +.Pp +.Ft void +.Fn rumpuser_rw_destroy "struct rumpuser_rw *rw" +.Pp +.Ft void +.Fo rumpuser_rw_held +.Fa "int enum_rumprwlock" "struct rumpuser_rw *rw" "int *heldp" +.Fc +.Pp +Read/write locks provide either shared or exclusive locking. +The possible values for +.Fa lk +are +.Dv RUMPUSER_RW_READER +and +.Dv RUMPUSER_RW_WRITER . +Upgrading means trying to migrate from an already owned shared +lock to an exclusive lock and downgrading means migrating from +an already owned exclusive lock to a shared lock. +.Pp +.Ft void +.Fn rumpuser_cv_init "struct rumpuser_cv **cvp" +.Pp +.Ft void +.Fn rumpuser_cv_destroy "struct rumpuser_cv *cv" +.Pp +.Ft void +.Fn rumpuser_cv_wait "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx" +.Pp +.Ft void +.Fn rumpuser_cv_wait_nowrap "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx" +.Pp +.Ft int +.Fo rumpuser_cv_timedwait +.Fa "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx" +.Fa "int64_t sec" "int64_t nsec" +.Fc +.Pp +.Ft void +.Fn rumpuser_cv_signal "struct rumpuser_cv *cv" +.Pp +.Ft void +.Fn rumpuser_cv_broadcast "struct rumpuser_cv *cv" +.Pp +.Ft void +.Fn rumpuser_cv_has_waiters "struct rumpuser_cv *cv" "int *waitersp" +.Pp +Condition variables wait for an event. +The +.Fa mtx +interlock eliminates a race between checking the predicate and +sleeping on the condition variable; the mutex should be released +for the duration of the sleep in the normal atomic manner. +The timedwait variant takes a specifier indicating a relative +sleep duration after which the routine will return with +.Er ETIMEDOUT . +If a timedwait is signaled before the timeout expires, the +routine will return 0. +.Pp +The order in which the hypervisor +reacquires the rump kernel context and interlock mutex before +returning into the rump kernel is as follows. +In case the interlock mutex was initialized with both +.Dv RUMPUSER_MTX_SPIN +and +.Dv RUMPUSER_MTX_KMUTEX , +the rump kernel context is scheduled before the mutex is reacquired. +In case of a purely +.Dv RUMPUSER_MTX_SPIN +mutex, the mutex is acquired first. +In the final case the order is implementation-defined. +.Sh RETURN VALUES +All routines which return an integer return an errno value. +The hypervisor must translate the value to the native errno +namespace used by the rump kernel. +Routines which do not return an integer may never fail. +.Sh SEE ALSO +.Xr rump 3 +.Rs +.%A Antti Kantee +.%D 2012 +.%J Aalto University Doctoral Dissertations +.%T Flexible Operating System Internals: The Design and Implementation of the Anykernel and Rump Kernels +.%O Section 2.3.2: The Hypercall Interface +.Re +.Pp +For a list of all known implementations of the +.Nm +interface, see +.Lk https://github.com/rumpkernel/wiki/wiki/Platforms . +.Sh HISTORY +The rump kernel hypercall API was first introduced in +.Nx 5.0 . +The API described above first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/run_query.3 b/static/netbsd/man3/run_query.3 new file mode 100644 index 00000000..8e63ece9 --- /dev/null +++ b/static/netbsd/man3/run_query.3 @@ -0,0 +1,208 @@ +.\" $NetBSD: run_query.3,v 1.6 2023/06/24 05:15:42 msaitoh Exp $ +.\" +.\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com> +.\" All rights reserved. +.\" +.\" This code was developed as part of Google's Summer of Code 2011 program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 23, 2016 +.Dt RUN_QUERY 3 +.Os +.Sh NAME +.Nm run_query +.Nd run a query against +.Pa /var/db/man.db +and process the results in a callback function. +.Sh SYNOPSIS +.In apropos-utils.h +.Ft int +.Fn run_query "sqlite3 *db" "query_format fmt" "query_args *args" +.Sh DESCRIPTION +The +.Fn run_query +function prepares the user supplied query in a form suitable to be run +against +.Pa /var/db/man.db +and executes the query. +For each row obtained in the result set, +.Fn run_query +will call the user supplied callback function, which should contain the +logic for processing the data thus obtained. +.Pp +The +.Fn run_query +function takes following arguments: +.Bl -tag -width 8n +.It Fa sqlite3 *db +Handle to the database connection which can be obtained by calling +.Fn init_db . +.It Fa query_format fmt +An enum value +indicating the output format. +Currently you can specify following values: +.Bl -hang -width compact +.It Dv APROPOS_PAGER +.It Dv APROPOS_TERM +.It Dv APROPOS_HTML +.It Dv APROPOS_NONE +.El +.It Fa query_args *args +.Ft query_args +is a struct which is defined in +.Pa apropos-utils.h . +It has the following fields: +.Bl -tag -width 8n -offset indent +.It Li const char *search_str +This is the query as entered by the user. +You may want to pre-process it to do sanitization etc. +.It Li int *sec_nums +This is an array of +.Ft int +wherein each index element represents the +section number in which search should be performed. +The sections whose corresponding index element in this array is set to +.Dv NULL +are not searched. +If all the elements in the array are +.Dv 0 +then all the sections are searched. +Alternatively pass +.Dv NULL +as to search in all the sections. +.It Li int nrec +This specifies the number of matching rows to fetch from the database. +Specify a negative value to fetch all the matching rows. +.It Li int offset +This specifies the offset within the result-set. +Use it to specify the position +from where to start processing the result-set. +For example if the value of nrec is m and value of offset is n, then the first +n records from the result-set will be omitted and rest m-n (or less) records will +be available for processing inside the callback. +Use a negative value if you don't wish to offset any records. +.It Li int legacy +If the output should be in legacy format (similary to classic apropos). +.It Li const char *machine +The machine architecture to which the searches should be restricted. +Specify NULL if the search should not be restricted a particular machine architecture. +.It Li int (*callback) (void *, const char *, const char *, const char *,\ +const char *, size_t) +This is the callback function which will +be called for each row retrieved from the database. +The function should return a value of 0 on successful execution. +A non-zero return value will indicate a failure and +.Fn run_query +will return. +The interface of the callback function is described later in this section. +.It Li void *callback_data +Use this argument to pass any data to the callback function. +It can be retrieved inside the callback function from its first argument. +.It Li char **errmsg +If an error occurs while fetching the data from the database, +a human readable error message will be stored in +.Fa errmsg . +If no error occurs then +.Fa errmsg +will be set to +.Dv NULL . +In case +.Fa errmsg +is not +.Dv NULL , +then the caller should make sure to free it. +.El +.El +.Pp +The interface of the callback function is +.Ft int +.Fn (*callback) "void *callback_data" "const char *section" "const char *name"\ +"const char *name_desc" "const char *snippet" "size_t snippet_length" +.Pp +Its arguments are: +.Bl -column -offset indent "Function" "Argument Description" +.It Li void *callback_data Ta This is the caller supplied data. +.It Li const char *section Ta Ta \&It is the section number to which this man +page belongs. +.It Li const char *name Ta This is the name of the man page +.It Li const char *name_desc Ta This is the one line description of this man +page obtained from its NAME section. +.It Li const char *snippet Ta This is a snippet of the matching text from this +man page. +.It Li size_t snippet_length Ta This is the length of the snippet. +.El +.Sh RETURN VALUES +On successful execution the +.Fn run_query +function will return 0 and in case of an error \-1 will be returned. +.Sh FILES +.Bl -hang -width /var/db/man.db -compact +.It Pa /var/db/man.db +The SQLite FTS database which contains an index of the manual pages. +.El +.Sh EXAMPLES +Following is a code excerpt of how +.Pa apropos.c +uses +.Fn run_query . +.Bd -literal -offset indent +#include <apropos-utils.h> +query_args args; +char *errmsg = NULL; +int *sec_nums = {0, 1, 1, 0, 0, 0, 0, 0, 0}; +args.search_str = argv[1]; +args.sec_nums = sec_nums; +args.nrec = 10; +args.offset = -1; +args.machine = NULL; +args.callback = &query_callback; +args.callback_data = NULL; +args.errmsg = &errmsg; +if (run_query(db, APROPOS_PAGER, &args) < 0) + errx(EXIT_FAILURE, "%s", errmsg); +} + +free(query); +free(errmsg); + +static int +query_callback(void *data, const char *section, const char *name, + const char *name_desc, const char *snippet, size_t snippet_length ) +{ + /* The user supplied data could be obtained as follows */ + // my_data *buf = (my_data *) data; + + fprintf(stdout, "%s(%s)\t%s\en%s\en\en", name, section, name_desc, + snippet); + return 0; +} +.Ed +.Sh SEE ALSO +.Xr apropos-utils 3 , +.Xr close_db 3 , +.Xr init_db 3 +.Sh AUTHORS +.An Abhinav Upadhyay diff --git a/static/netbsd/man3/s2i_ASN1_IA5STRING.3 b/static/netbsd/man3/s2i_ASN1_IA5STRING.3 new file mode 100644 index 00000000..58baeac3 --- /dev/null +++ b/static/netbsd/man3/s2i_ASN1_IA5STRING.3 @@ -0,0 +1,157 @@ +.\" $NetBSD: s2i_ASN1_IA5STRING.3,v 1.5 2026/04/08 17:06:51 christos Exp $ +.\" +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "s2i_ASN1_IA5STRING 3" +.TH s2i_ASN1_IA5STRING 3 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +i2s_ASN1_IA5STRING, +s2i_ASN1_IA5STRING, +i2s_ASN1_INTEGER, +s2i_ASN1_INTEGER, +i2s_ASN1_OCTET_STRING, +s2i_ASN1_OCTET_STRING, +i2s_ASN1_ENUMERATED, +i2s_ASN1_ENUMERATED_TABLE, +i2s_ASN1_UTF8STRING, +s2i_ASN1_UTF8STRING +\&\- convert objects from/to ASN.1/string representation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/x509v3.h> +\& +\& char *i2s_ASN1_IA5STRING(X509V3_EXT_METHOD *method, ASN1_IA5STRING *ia5); +\& ASN1_IA5STRING *s2i_ASN1_IA5STRING(X509V3_EXT_METHOD *method, +\& X509V3_CTX *ctx, const char *str); +\& char *i2s_ASN1_INTEGER(X509V3_EXT_METHOD *method, const ASN1_INTEGER *a); +\& ASN1_INTEGER *s2i_ASN1_INTEGER(X509V3_EXT_METHOD *method, const char *value); +\& char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, +\& const ASN1_OCTET_STRING *oct); +\& ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, +\& X509V3_CTX *ctx, const char *str); +\& char *i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *method, const ASN1_ENUMERATED *a); +\& char *i2s_ASN1_ENUMERATED_TABLE(X509V3_EXT_METHOD *method, +\& const ASN1_ENUMERATED *e); +\& +\& char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method, +\& ASN1_UTF8STRING *utf8); +\& ASN1_UTF8STRING *s2i_ASN1_UTF8STRING(X509V3_EXT_METHOD *method, +\& X509V3_CTX *ctx, const char *str); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +These functions convert OpenSSL objects to and from their ASN.1/string +representation. This function is used for \fBX509v3\fR extensions. +.SH NOTES +.IX Header "NOTES" +The letters \fBi\fR and \fBs\fR in \fBi2s\fR and \fBs2i\fR stand for +"internal" (that is, an internal C structure) and string respectively. +So \fBi2s_ASN1_IA5STRING\fR() converts from internal to string. +.PP +It is the caller\*(Aqs responsibility to free the returned string. +In the \fBi2s_ASN1_IA5STRING\fR() function the string is copied and +the ownership of the original string remains with the caller. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBi2s_ASN1_IA5STRING\fR() returns the pointer to a IA5 string +or NULL if an error occurs. +.PP +\&\fBs2i_ASN1_IA5STRING\fR() return a valid +\&\fBASN1_IA5STRING\fR structure or NULL if an error occurs. +.PP +\&\fBi2s_ASN1_INTEGER\fR() return a valid +string or NULL if an error occurs. +.PP +\&\fBs2i_ASN1_INTEGER\fR() returns the pointer to a \fBASN1_INTEGER\fR +structure or NULL if an error occurs. +.PP +\&\fBi2s_ASN1_OCTET_STRING\fR() returns the pointer to a OCTET_STRING string +or NULL if an error occurs. +.PP +\&\fBs2i_ASN1_OCTET_STRING\fR() return a valid +\&\fBASN1_OCTET_STRING\fR structure or NULL if an error occurs. +.PP +\&\fBi2s_ASN1_ENUMERATED\fR() return a valid +string or NULL if an error occurs. +.PP +\&\fBs2i_ASN1_ENUMERATED\fR() returns the pointer to a \fBASN1_ENUMERATED\fR +structure or NULL if an error occurs. +.PP +\&\fBs2i_ASN1_UTF8STRING\fR() return a valid +\&\fBASN1_UTF8STRING\fR structure or NULL if an error occurs. +.PP +\&\fBi2s_ASN1_UTF8STRING\fR() returns the pointer to a UTF\-8 string +or NULL if an error occurs. +.SH HISTORY +.IX Header "HISTORY" +\&\fBi2s_ASN1_UTF8STRING()\fR and \fBs2i_ASN1_UTF8STRING()\fR were made public in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/static/netbsd/man3/scalbn.3 b/static/netbsd/man3/scalbn.3 new file mode 100644 index 00000000..fcf0a078 --- /dev/null +++ b/static/netbsd/man3/scalbn.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: scalbn.3,v 1.2 2011/09/18 05:33:14 jruoho Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 18, 2011 +.Dt SCALBN 3 +.Os +.Sh NAME +.Nm scalbn , +.Nm scalbnf , +.Nm scalbnl +.Nd exponent using FLT_RADIX +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn scalbn "double x" "int n" +.Ft float +.Fn scalbnf "float x" "int n" +.Ft long double +.Fn scalbnl "long double x" "int n" +.Sh DESCRIPTION +The +.Fn scalbn , +.Fn scalbnf , +and +.Fn scalbnl +functions compute +.Fa x +* +.Fa r^n , +where +.Fa r +is the radix of the machine's floating point arithmetic, defined by the +.Dv FLT_RADIX +constant in +.In float.h . +The rationale is efficiency; +.Fa r^n +is not computed explicitly. +.Sh RETURN VALUES +As described above, upon successful completion, the described functions return +the exponent computed using +.Dv FLT_RADIX . +Otherwise the following may occur: +.Pp +.Bl -enum -offset indent +.It +When the result would cause an overflow, a range error occurs and +.Dv \*(Pm\*HHUGE_VAL , +.Dv \*(Pm\*HHUGE_VALF , +or +.Dv \*(Pm\*HHUGE_VALL +is returned according to the sign of +.Fa x +and the return type of the corresponding function. +.It +When the correct value would cause an underflow +and it is not representable, a range error occurs and +either 0.0 or an implementation-defined value is returned. +When an underflow occurs but the correct value is representable, +a range error occurs but the correct value is returned. +.It +If +.Fa x +is \*(Pm0 or \*(Pm\Inf, +.Fa x +is returned. +Likewise, if +.Fa n +is zero, +.Fa x +is returned. +If +.Fa x +is \*(Na, \*(Na is returned. +.El +.Sh SEE ALSO +.Xr exp 3 , +.Xr frexp 3 , +.Xr ldexp 3 , +.Xr math 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/scandir.3 b/static/netbsd/man3/scandir.3 new file mode 100644 index 00000000..64655157 --- /dev/null +++ b/static/netbsd/man3/scandir.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: scandir.3,v 1.17 2022/12/04 01:29:32 uwe Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd December 15, 2016 +.Dt SCANDIR 3 +.Os +.Sh NAME +.Nm scandir , +.Nm alphasort +.Nd scan a directory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In dirent.h +.Ft int +.Fn scandir "const char *dirname" "struct dirent ***namelist" "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" +.Ft int +.Fn alphasort "const struct dirent **d1" "const struct dirent **d2" +.Sh DESCRIPTION +The +.Fn scandir +function +reads the directory +.Fa dirname +and builds an array of pointers to directory +entries using +.Xr malloc 3 . +It returns the number of entries in the array. +A pointer to the array of directory entries is stored in the location +referenced by +.Fa namelist . +.Pp +The +.Fa select +parameter is a pointer to a user supplied subroutine which is called by +.Fn scandir +to select which entries are to be included in the array. +The select routine is passed a +pointer to a directory entry and should return a non-zero +value if the directory entry is to be included in the array. +If +.Fa select +is null, then all the directory entries will be included. +.Pp +The +.Fa compar +parameter is a pointer to a user supplied subroutine which is passed to +.Xr qsort 3 +to sort the completed array. +If this pointer is null, the array is not sorted. +.Pp +The +.Fn alphasort +function +is a routine which can be used for the +.Fa compar +parameter to sort the array alphabetically. +.Pp +The memory allocated for the array can be deallocated with +.Xr free 3 , +by freeing each pointer in the array and then the array itself. +.Sh RETURN VALUES +Returns \-1 if the directory cannot be opened for reading or if +.Xr malloc 3 +cannot allocate enough memory to hold all the data structures. +.Sh SEE ALSO +.Xr directory 3 , +.Xr dirent 3 , +.Xr malloc 3 , +.Xr qsort 3 +.Sh STANDARDS +The +.Fn scandir +and +.Fn alphasort +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn scandir +and +.Fn alphasort +functions appeared in +.Bx 4.2 . +.Pp +They were changed in +.Nx 8.0 +to use +.Dq struct dirent ** +instead of +.Dq void * +for the comparison function, including +.Fn alphasort . diff --git a/static/netbsd/man3/scanf.3 b/static/netbsd/man3/scanf.3 new file mode 100644 index 00000000..2da89991 --- /dev/null +++ b/static/netbsd/man3/scanf.3 @@ -0,0 +1,478 @@ +.\" $NetBSD: scanf.3,v 1.27 2010/05/14 03:04:32 joerg Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd March 21, 2010 +.Dt SCANF 3 +.Os +.Sh NAME +.Nm scanf , +.Nm fscanf , +.Nm sscanf , +.Nm vscanf , +.Nm vsscanf , +.Nm vfscanf +.Nd input format conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn scanf "const char * restrict format" ... +.Ft int +.Fn fscanf "FILE * restrict stream" "const char * restrict format" ... +.Ft int +.Fn sscanf "const char * restrict str" "const char * restrict format" ... +.In stdarg.h +.Ft int +.Fn vscanf "const char * restrict format" "va_list ap" +.Ft int +.Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap" +.Ft int +.Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap" +.Sh DESCRIPTION +The +.Fn scanf +family of functions scans input according to a +.Fa format +as described below. +This format may contain +.Em conversion specifiers ; +the results from such conversions, if any, +are stored through the +.Em pointer +arguments. +.Pp +The +.Fn scanf +function +reads input from the standard input stream +.Em stdin , +.Fn fscanf +reads input from the stream pointer +.Fa stream , +and +.Fn sscanf +reads its input from the character string pointed to by +.Fa str . +The +.Fn vfscanf +function +is analogous to +.Xr vfprintf 3 +and reads input from the stream pointer +.Fa stream +using a variable argument list of pointers (see +.Xr stdarg 3 ) . +The +.Fn vscanf +function scans a variable argument list from the standard input and +the +.Fn vsscanf +function scans it from a string; +these are analogous to +the +.Fn vprintf +and +.Fn vsprintf +functions respectively. +.Pp +Each successive +.Em pointer +argument must correspond properly with +each successive conversion specifier +(but see `suppression' below). +All conversions are introduced by the +.Cm % +(percent sign) character. +The +.Fa format +string +may also contain other characters. +White space (such as blanks, tabs, or newlines) in the +.Fa format +string match any amount of white space, including none, in the input. +Everything else +matches only itself. +Scanning stops +when an input character does not match such a format character. +Scanning also stops +when an input conversion cannot be made (see below). +.Sh CONVERSIONS +Following the +.Cm % +character introducing a conversion +there may be a number of +.Em flag +characters, as follows: +.Bl -tag -width indent +.It Cm * +Suppresses assignment. +The conversion that follows occurs as usual, but no pointer is used; +the result of the conversion is simply discarded. +.It Cm h +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em short int +(rather than +.Em int ) . +.It Cm hh +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em char +(rather than +.Em int ) . +.It Cm j +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to an +.Em intmax_t +(rather than +.Em int ) . +.It Cm l +Indicates either that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em long int +(rather than +.Em int ) , +or that the conversion will be one of +.Cm efg +and the next pointer is a pointer to +.Em double +(rather than +.Em float ) . +.It Cm ll +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em long long int +(rather than +.Em int ) . +.It Cm q +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em quad_t +(rather than +.Em int ) . +.It Cm t +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em ptrdiff_t +(rather than +.Em int ) . +.It Cm z +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Em size_t +(rather than +.Em int ) . +.It Cm L +Indicates that the conversion will be +.Cm efg +and the next pointer is a pointer to +.Em long double . +.El +.Pp +In addition to these flags, +there may be an optional maximum field width, +expressed as a decimal integer, +between the +.Cm % +and the conversion. +If no width is given, +a default of `infinity' is used (with one exception, below); +otherwise at most this many characters are scanned +in processing the conversion. +Before conversion begins, +most conversions skip white space; +this white space is not counted against the field width. +.Pp +The following conversions are available: +.Bl -tag -width XXXX +.It Cm % +Matches a literal `%'. +That is, `%\&%' in the format string +matches a single input `%' character. +No conversion is done, and assignment does not occur. +.It Cm d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.Em int . +.It Cm D +Equivalent to +.Cm ld ; +this exists only for backwards compatibility. +.It Cm i +Matches an optionally signed integer; +the next pointer must be a pointer to +.Em int . +The integer is read in base 16 if it begins +with +.Ql 0x +or +.Ql 0X , +in base 8 if it begins with +.Ql 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.It Cm o +Matches an octal integer; +the next pointer must be a pointer to +.Em unsigned int . +.It Cm O +Equivalent to +.Cm lo ; +this exists for backwards compatibility. +.It Cm u +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.Em unsigned int . +.It Cm x +Matches an optionally signed hexadecimal integer; +the next pointer must be a pointer to +.Em unsigned int . +.It Cm X +Equivalent to +.Cm x . +.It Cm f +Matches an optionally signed floating-point number; +the next pointer must be a pointer to +.Em float . +.It Cm e +Equivalent to +.Cm f . +.It Cm g +Equivalent to +.Cm f . +.It Cm E +Equivalent to +.Cm f . +.It Cm G +Equivalent to +.Cm f . +.It Cm s +Matches a sequence of non-white-space characters; +the next pointer must be a pointer to +.Em char , +and the array must be large enough to accept all the sequence and the +terminating +.Dv NUL +character. +The input string stops at white space +or at the maximum field width, whichever occurs first. +.It Cm c +Matches a sequence of +.Em width +count +characters (default 1); +the next pointer must be a pointer to +.Em char , +and there must be enough room for all the characters +(no terminating +.Dv NUL +is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.It Cm \&[ +Matches a nonempty sequence of characters from the specified set +of accepted characters; +the next pointer must be a pointer to +.Em char , +and there must be enough room for all the characters in the string, +plus a terminating +.Dv NUL +character. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in +(or not in) +a particular set; +the set is defined by the characters between the open bracket +.Cm \&[ +character +and a close bracket +.Cm \&] +character. +The set +.Em excludes +those characters +if the first character after the open bracket is a circumflex +.Cm ^ . +To include a close bracket in the set, +make it the first character after the open bracket +or the circumflex; +any other position will end the set. +The hyphen character +.Cm - +is also special; +when placed between two other characters, +it adds all intervening characters to the set. +To include a hyphen, +make it the last character before the final close bracket. +For instance, +.Ql [^]0-9-] +means the set `everything except close bracket, zero through nine, +and hyphen'. +The string ends with the appearance of a character not in the +(or, with a circumflex, in) set +or when the field width runs out. +.It Cm p +Matches a pointer value (as printed by +.Ql %p +in +.Xr printf 3 ) ; +the next pointer must be a pointer to +.Em void . +.It Cm n +Nothing is expected; +instead, the number of characters consumed thus far from the input +is stored through the next pointer, +which must be a pointer to +.Em int . +This is +.Em not +a conversion, although it can be suppressed with the +.Cm * +flag. +.El +.Pp +For backwards compatibility, +other conversion characters (except +.Ql \e0 ) +are taken as if they were +.Ql %d +or, if uppercase, +.Ql %ld , +and a `conversion' of +.Ql %\e0 +causes an immediate return of +.Dv EOF . +.Pp +The format string specifier macros described in +.Xr inttypes 3 +should be used for the standard +.Dq C99 +fixed-size integers documented in +.Xr stdint 3 . +.Sh RETURN VALUES +These +functions +return +the number of input items assigned, which can be fewer than provided +for, or even zero, in the event of a matching failure. +Zero +indicates that, while there was input available, +no conversions were assigned; +typically this is due to an invalid input character, +such as an alphabetic character for a +.Ql %d +conversion. +The value +.Dv EOF +is returned if an input failure occurs before any conversion such as an +end-of-file occurs. +If an error or end-of-file occurs after conversion has begun, +the number of conversions which were successfully completed is returned. +.Sh SEE ALSO +.Xr getc 3 , +.Xr inttypes 3 , +.Xr printf 3 , +.Xr strtod 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The functions +.Fn fscanf , +.Fn scanf , +and +.Fn sscanf +conform to +.St -isoC-90 . +The +.Cm %j , +.Cm %t +and +.Cm %z +conversion format modifiers +conform to +.St -isoC-99 . +The +.Fn vfscanf , +.Fn vscanf +and +.Fn vsscanf +functions conform to +.St -isoC-99 . +.Sh HISTORY +The functions +.Fn vscanf , +.Fn vsscanf +and +.Fn vfscanf +appeared in +.Bx 4.4 +or even +.Bx 4.3 . +.Sh NOTES +All of the backwards compatibility formats will be removed in the future. +.Sh BUGS +Numerical strings are truncated to 512 characters; for example, +.Cm %f +and +.Cm %d +are implicitly +.Cm %512f +and +.Cm %512d . diff --git a/static/netbsd/man3/scanf_l.3 b/static/netbsd/man3/scanf_l.3 new file mode 100644 index 00000000..0c925c4e --- /dev/null +++ b/static/netbsd/man3/scanf_l.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: scanf_l.3,v 1.1 2015/12/29 17:55:23 christos Exp $ +.\" Copyright (c) 2012 Isabell Long <issyl0@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/stdio/scanf_l.3 258245 2013-11-17 02:03:45Z eadler $ +.\" +.Dd December 29, 2015 +.Dt SCANF_L 3 +.Os +.Sh NAME +.Nm scanf_l , +.Nm fscanf_l , +.Nm sscanf_l , +.Nm vfscanf_l , +.Nm vscanf_l , +.Nm vsscanf_l +.Nd input format conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In locale.h +.Ft int +.Fn scanf_l "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn fscanf_l "FILE * restrict stream" "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn sscanf_l "const char * restrict str" "locale_t loc" "const char * restrict format" "..." +.Ft int +.Fn vfscanf_l "FILE * restrict stream" "locale_t loc" "const char * restrict format" "va_list ap" +.Ft int +.Fn vscanf_l "locale_t loc" "const char * restrict format" "va_list ap" +.Ft int +.Fn vsscanf_l "const char * restrict str" "locale_t loc" "const char * restrict format" "va_list ap" +.Sh DESCRIPTION +The above functions scan input according to a specified +.Fa format +in the locale +.Fa loc . +They behave in the same way as the versions without the _l suffix, but use +the specific locale rather than the global or per-thread locale. +See the specific manual pages for more information. +.Sh SEE ALSO +.Xr scanf 3 , +.Xr xlocale 3 +.Sh STANDARDS +These functions do not conform to any specific standard so they should be +considered as non-portable local extensions. +.Sh HISTORY +These functions first appeared in Darwin and were first implemented in +.Fx 9.1 +and +.Nx 7 . diff --git a/static/netbsd/man3/sched.3 b/static/netbsd/man3/sched.3 new file mode 100644 index 00000000..5c16fde7 --- /dev/null +++ b/static/netbsd/man3/sched.3 @@ -0,0 +1,335 @@ +.\" $NetBSD: sched.3,v 1.18 2016/09/15 07:53:59 njoly Exp $ +.\" +.\" Copyright (c) 2008, 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 5, 2016 +.Dt SCHED 3 +.Os +.Sh NAME +.Nm sched_setparam , +.Nm sched_getparam , +.Nm sched_setscheduler , +.Nm sched_getscheduler , +.Nm sched_get_priority_max , +.Nm sched_get_priority_min , +.Nm sched_rr_get_interval , +.Nm sched_yield , +.Nm sched_protect , +.Nm sched_setaffinity_np , +.Nm sched_getaffinity_np +.Nd process scheduling +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_setparam "pid_t pid" "const struct sched_param *param" +.Ft int +.Fn sched_getparam "pid_t pid" "struct sched_param *param" +.Ft int +.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" +.Ft int +.Fn sched_getscheduler "pid_t pid" +.Ft int +.Fn sched_get_priority_max "int policy" +.Ft int +.Fn sched_get_priority_min "int policy" +.Ft int +.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval" +.Ft int +.Fn sched_yield "void" +.Ft int +.Fn sched_setaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset" +.Ft int +.Fn sched_getaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset" +.Ft int +.Fn sched_protect "int priority" +.Sh DESCRIPTION +This section describes the functions used to get scheduling information +about processes, and control the scheduling of processes. +.Pp +Available scheduling policies (classes) are: +.Bl -tag -width SCHED_OTHER +.It Dv SCHED_OTHER +Time-sharing (TS) scheduling policy. +The default policy in +.Nx . +.It Dv SCHED_FIFO +First in, first out (FIFO) scheduling policy. +.It Dv SCHED_RR +Round robin scheduling policy. +.El +.Pp +The +.Fa struct sched_param +contains at least one member: +.Bl -tag -width flags +.It Fa sched_priority +Specifies the priority of the process. +For +.Dv SCHED_OTHER , +must be +.Dv PRI_NONE ; +the kernel will dynamically assign priorities to the thread based on +CPU load. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn sched_setparam pid param +Sets the scheduling parameters for the process specified by +.Fa pid +to +.Fa param . +If the value of +.Fa pid +is equal to zero, then the calling process is used. +.It Fn sched_getparam pid param +Gets the scheduling parameters of the process specified by +.Fa pid +into the structure +.Fa param . +If the value of +.Fa pid +is equal to zero, then the calling process is used. +.It Fn sched_setscheduler pid policy param +Set the scheduling policy and parameters for the process specified by +.Fa pid . +If the value of +.Fa pid +is equal to zero, then the calling process is used. +.It Fn sched_getscheduler pid +Returns the scheduling policy of the process specified by +.Fa pid . +If the value of +.Fa pid +is equal to zero, then the calling process is used. +.It Fn sched_get_priority_max policy +Returns the maximal priority which may be used for the scheduling policy +specified by +.Fa policy . +.It Fn sched_get_priority_min policy +Returns the minimal priority which may be used for the scheduling policy +specified by +.Fa policy . +.It Fn sched_rr_get_interval pid interval +Returns the time quantum into the structure +.Fa interval +of the process specified by +.Fa pid . +If the value of +.Fa pid +is equal to zero, then the calling process is used. +The process must be running at +.Fa SCHED_RR +scheduling policy. +.It Fn sched_yield +Yields a processor voluntarily and gives other threads a chance to run +without waiting for an involuntary preemptive switch. +.It Fn sched_setaffinity_np pid size cpuset +Set the affinity mask specified by +.Fa cpuset +for the process specified by +.Fa pid . +At least one valid CPU must be set in the mask. +.It Fn sched_getaffinity_np pid size cpuset +Get the affinity mask of the process specified by +.Fa pid +into the +.Fa cpuset . +.It Fn sched_protect priority +Performs priority protection using the +.Dv PTHREAD_PRIO_PROTECT +protocol. +This function will increase the protected priority of the caller thread to +.Fa priority +if the current thread's protected priority is smaller than +.Fa priority . +Multiple calls to +.Fn sched_protect +with a positive priority will +.Dq push +a priority level to the current thread, whereas calling +.Fn sched_protect +with a +.Fa priority +level of +.Dv \-1 +will +.Dq pop +a priority level. +When the level reaches +.Dv 0 +(the same number of +.Dq pushes +and +.Dq pops +have been issued) the original thread priority will be restored. +.El +.Sh IMPLEMENTATION NOTES +Setting CPU +.Xr affinity 3 +requires super-user privileges. +Ordinary users can be allowed to control CPU affinity +of their threads via the +.Pa security.models.extensions.user_set_cpu_affinity +.Xr sysctl 7 . +See +.Xr secmodel_extensions 9 . +.Pp +Portable applications should not use the +.Fn sched_setaffinity_np +and +.Fn sched_getaffinity_np +functions. +.Sh RETURN VALUES +.Fn sched_protect , +.Fn sched_setparam , +.Fn sched_getparam , +.Fn sched_rr_get_interval , +and +.Fn sched_yield +return 0 on success. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +.Fn sched_setscheduler +returns the previously used scheduling policy on success. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +.Fn sched_getscheduler +returns the scheduling policy on success. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +return the maximal/minimal priority value on success. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Pp +.Fn sched_setaffinity_np +and +.Fn sched_getaffinity_np +return 0 on success. +Otherwise, \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sched_setparam +and +.Fn sched_setscheduler +functions fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +At least one of the specified scheduling parameters was invalid. +.It Bq Er EPERM +The calling process has no appropriate privileges to perform the operation. +.It Bq Er ESRCH +No process can be found corresponding to the PID specified by +.Fa pid , +and the value of +.Fa pid +is not zero. +.El +.Pp +The +.Fn sched_getparam +and +.Fn sched_getscheduler +functions fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The calling process is not a super-user and its effective user id does not +match the effective user-id of the specified process. +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid , +and the value of +.Fa pid +is not zero. +.El +.Pp +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +functions fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified scheduling policy is invalid. +.El +.Pp +The +.Fn sched_rr_get_interval +function fails if: +.Bl -tag -width Er +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid , +and the value of +.Fa pid +is not zero. +.El +.Pp +The +.Fn sched_protect +function fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The thread was not priority protected. +.It Bq Er EPERM +The +.Fa priority +parameter was out of range (not in the range between +.Dv SCHED_PRIO_MIN +and +.Dv SCHED_PRIO_MAX ) . +.El +.Sh SEE ALSO +.Xr affinity 3 , +.Xr cpuset 3 , +.Xr pset 3 , +.Xr schedctl 8 +.Sh STANDARDS +These functions, except +.Fn sched_setaffinity_np +and +.Fn sched_getaffinity_np , +are expected to conform the +.St -p1003.1-2001 +standard. +.Sh HISTORY +The scheduling functions appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/sctp_bindx.3 b/static/netbsd/man3/sctp_bindx.3 new file mode 100644 index 00000000..0d9490e0 --- /dev/null +++ b/static/netbsd/man3/sctp_bindx.3 @@ -0,0 +1,120 @@ +.\" $NetBSD: sctp_bindx.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_BINDX 3 +.Os +.Sh NAME +.Nm sctp_bindx +.Nd bind or unbind an SCTP socket to a list of addresses +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_bindx "int s" "struct sockaddr *addrs" "int num" "int type" +.Sh DESCRIPTION +The +.Fn sctp_bindx +call binds or unbinds a address or a list of addresses to an +SCTP endpoint. +This allows a user to bind a subset of +addresses. +The +.Fn sctp_bindx +call operates similarly to +.Fn bind +but allows a list of addresses and also allows a bind or an +unbind. +The argument +.Fa s +must be a valid SCTP socket descriptor. +The argument +.Fa addrs +is a list of addresses (where the list may be only 1 in +length) that the user wishes to bind or unbind to the +socket. +The argument +.Fa type +must be one of the following values. +.Pp +.Dv SCTP_BINDX_ADD_ADDR +This value indicates that the listed address(es) need to +be added to the endpoint. +.Pp +.Dv SCTP_BINDX_DEL_ADDR +This value indicates that the listed address(es) need to +be removed from the endpoint. +.Pp +Note that when a user adds or deletes an address to an +association if the dynamic address flag +.Va net.inet.sctp.auto_asconf +is enabled any associations in the endpoint will attempt to +have the address(es) added dynamically to the existing +association. +.Sh RETURN VALUES +The call returns 0 on success and \-1 upon failure. +.Sh ERRORS +The +.Fn sctp_bindx +function can return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EINVAL +This value is returned if the +.Fa type +field is not one of the allowed values (see above). +.It Bq Er ENOMEM +This value is returned if the number of addresses +being added causes a memory allocation failure in +the call. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_connectx.3 b/static/netbsd/man3/sctp_connectx.3 new file mode 100644 index 00000000..35a337e0 --- /dev/null +++ b/static/netbsd/man3/sctp_connectx.3 @@ -0,0 +1,111 @@ +.\" $NetBSD: sctp_connectx.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2018 +.Dt SCTP_CONNECTX 3 +.Os +.Sh NAME +.Nm sctp_connectx +.Nd connect an SCTP socket with multiple destination addresses +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_connectx "int sd" "struct sockaddr *addrs" "int addrcnt" "sctp_assoc_t *id" +.Sh DESCRIPTION +The +.Fn sctp_connectx +call attempts to initiate an association to a peer SCTP +endpoint. +The call operates similarly to +.Fn connect +but it also provides the ability to specify multiple destination +addresses for the peer. +This allows a fault tolerant method +of initiating an association. +When one of the peers addresses +is unreachable, the subsequent listed addresses will also be used +to set up the association with the peer. +.Pp +The user also needs to consider that any address listed in an +.Fn sctp_connectx +call is also considered "confirmed". +A confirmed address is one in +which the SCTP transport will trust is a part of the association +and it will not send a confirmation heartbeat to it with +a random nonce. +.Pp +If the peer SCTP stack does not list one or more of +the provided addresses in its response message then +the extra addresses sent in the +.Fn sctp_connectx +call will be silently discarded from the association. +On +successful completion the provided +.Fa id +will be +filled in with the association identification of the newly +forming association. +.Sh RETURN VALUES +The call returns 0 on success and \-1 upon failure. +.Sh ERRORS +The +.Fn sctp_connectx +function can return the following errors: +.Bl -tag -width Er +.It Bq Er E2BIG +The size of the address list exceeds the amount of +data provided. +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EINVAL +An address listed has an invalid family or no +addresses were provided. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_freepaddrs.3 b/static/netbsd/man3/sctp_freepaddrs.3 new file mode 100644 index 00000000..43ed4ce7 --- /dev/null +++ b/static/netbsd/man3/sctp_freepaddrs.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: sctp_freepaddrs.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_FREEPADDRS 3 +.Os +.Sh NAME +.Nm sctp_freepaddrs , +.Nm sctp_freeladdrs +.Nd release the memory returned from a previous call +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft void +.Fn sctp_freepaddrs "struct sockaddr *" +.Ft void +.Fn sctp_freeladdrs "struct sockaddr *" +.Sh DESCRIPTION +The +.Fn sctp_freepaddrs +and +.Fn sctp_freeladdrs +functions are used to release the memory allocated by previous +calls to +.Xr sctp_getpaddrs 3 +or +.Xr sctp_getladdrs 3 +respectively. +.Sh RETURN VALUES +none. +.Sh SEE ALSO +.Xr sctp_getladdrs 3 , +.Xr sctp_getpaddrs 3 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +These functions first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_getaddrlen.3 b/static/netbsd/man3/sctp_getaddrlen.3 new file mode 100644 index 00000000..e76e8f79 --- /dev/null +++ b/static/netbsd/man3/sctp_getaddrlen.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: sctp_getaddrlen.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_GETADDRLEN 3 +.Os +.Sh NAME +.Nm sctp_getaddrlen +.Nd return the address length of an address family +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_getaddrlen "sa_family_t family" +.Sh DESCRIPTION +The +.Fn sctp_getaddrlen +function returns the size of a specific address family. +This function +is provided for application binary compatibility since it +provides the application with the size the operating system +thinks the specific address family is. +Note that the function +will actually create an SCTP socket and then gather the +information via a +.Fn getsockopt +system calls. +If for some reason a SCTP socket cannot +be created or the +.Fn getsockopt +call fails, an error will be returned +with +.Va errno +set as specified in the +.Fn socket +or +.Fn getsockopt +system call. +.Sh RETURN VALUES +The call returns the number of bytes that the operating +system expects for the specific address family or \-1. +.Sh ERRORS +The +.Fn sctp_getaddrlen +function can return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The address family specified does NOT exist. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr socket 2 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_getassocid.3 b/static/netbsd/man3/sctp_getassocid.3 new file mode 100644 index 00000000..00458573 --- /dev/null +++ b/static/netbsd/man3/sctp_getassocid.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: sctp_getassocid.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2018 +.Dt SCTP_GETASSOCID 3 +.Os +.Sh NAME +.Nm sctp_getassocid +.Nd return an association id for a specified socket address +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft sctp_assoc_t +.Fn sctp_getassocid "int s" "struct sockaddr *addr" +.Sh DESCRIPTION +The +.Fn sctp_getassocid +call attempts to look up the specified socket address +.Fa addr +and find the respective association identification. +.Sh RETURN VALUES +The call returns the association id upon success and +0 is returned upon failure. +.Sh ERRORS +The +.Fn sctp_getassocid +function can return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOENT +The address does not have an association setup to it. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_getpaddrs.3 b/static/netbsd/man3/sctp_getpaddrs.3 new file mode 100644 index 00000000..fd51b919 --- /dev/null +++ b/static/netbsd/man3/sctp_getpaddrs.3 @@ -0,0 +1,106 @@ +.\" $NetBSD: sctp_getpaddrs.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_GETPADDRS 3 +.Os +.Sh NAME +.Nm sctp_getpaddrs , +.Nm sctp_getladdrs +.Nd return a list of addresses to the caller +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_getpaddrs "int s" "sctp_assoc_t asocid" "struct sockaddr **addrs" +.Ft int +.Fn sctp_getladdrs "int s" "sctp_assoc_t asocid" "struct sockaddr **addrs" +.Sh DESCRIPTION +The +.Fn sctp_getpaddrs +function is used to get the list of the peers addresses. +The +.Fn sctp_getladdrs +function is used to get the list of the local addresses. +The association of interest is identified by the +.Fa asocid +argument. +The addresses are returned in a newly allocated +array of socket addresses returned in the argument +.Fa addrs +upon success. +.Pp +After the caller is finished, the function +.Xr sctp_freepaddrs 3 +or +.Xr sctp_freeladdrs 3 +should be used to release the memory allocated by these +calls. +.Sh RETURN VALUES +The call returns \-1 upon failure and a count of +the number of addresses returned in +.Fa addrs +upon success. +.Sh ERRORS +The functions can return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EINVAL +An address listed has an invalid family or no +addresses were provided. +.It Bq Er ENOMEM +The call cannot allocate memory to hold the +socket addresses. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr sctp_freeladdrs 3 , +.Xr sctp_freepaddrs 3 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +These functions first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_opt_info.3 b/static/netbsd/man3/sctp_opt_info.3 new file mode 100644 index 00000000..eca25ebd --- /dev/null +++ b/static/netbsd/man3/sctp_opt_info.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: sctp_opt_info.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_OPT_INFO 3 +.Os +.Sh NAME +.Nm sctp_opt_info +.Nd get SCTP socket information +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_opt_info "int sd" "sctp_assoc_t id" "int opt" "void *arg" "socklen_t *size" +.Sh DESCRIPTION +The +.Fn sctp_opt_info +call provides a multi-os compatible method for getting +specific +.Fn getsockopt +data where an association identification needs to be passed +into the operating system. +For those +who wish to write portable code amongst multiple operating systems +this call should be used for the following SCTP +socket options. +.Pp +.Dv SCTP_RTOINFO +.Pp +.Dv SCTP_ASSOCINFO +.Pp +.Dv SCTP_PRIMARY_ADDR +.Pp +.Dv SCTP_PEER_ADDR_PARAMS +.Pp +.Dv SCTP_DEFAULT_SEND_PARAM +.Pp +.Dv SCTP_MAX_SEG +.Pp +.Dv SCTP_AUTH_ACTIVE_KEY +.Pp +.Dv SCTP_DELAYED_SACK +.Pp +.Dv SCTP_MAX_BURST +.Pp +.Dv SCTP_CONTEXT +.Pp +.Dv SCTP_EVENT +.Pp +.Dv SCTP_DEFAULT_SNDINFO +.Pp +.Dv SCTP_DEFAULT_PRINFO +.Pp +.Dv SCTP_STATUS +.Pp +.Dv SCTP_GET_PEER_ADDR_INFO +.Pp +.Dv SCTP_PEER_AUTH_CHUNKS +.Pp +.Dv SCTP_LOCAL_AUTH_CHUNKS +.Sh RETURN VALUES +The call returns 0 on success and \-1 upon error. +.Sh ERRORS +The +.Fn sctp_opt_info +function can return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EINVAL +The argument +.Fa arg +value was invalid. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EOPNOTSUPP +The argument +.Fa opt +was not one of the above listed SCTP socket +options. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr getsockopt2 2 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_peeloff.3 b/static/netbsd/man3/sctp_peeloff.3 new file mode 100644 index 00000000..71808e27 --- /dev/null +++ b/static/netbsd/man3/sctp_peeloff.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: sctp_peeloff.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2018 +.Dt SCTP_PEELOFF 3 +.Os +.Sh NAME +.Nm sctp_peeloff +.Nd detach an association from a one-to-many socket to its own fd +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_peeloff "int s" "sctp_assoc_t id" +.Sh DESCRIPTION +The +.Fn sctp_peeloff +function attempts detach the association specified by +.Fa id +into its own separate socket. +.Sh RETURN VALUES +The call returns \-1 on failure and the new socket descriptor +upon success. +.Sh ERRORS +The +.Fn sctp_peeloff +function can return the following errors: +.Bl -tag -width Er +.It Bq Er E2BIG +The size of the address list exceeds the amount of +data provided. +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTCONN +The +.Fa id +given to the call does not map to a valid +association. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_recvmsg.3 b/static/netbsd/man3/sctp_recvmsg.3 new file mode 100644 index 00000000..53d4b7bd --- /dev/null +++ b/static/netbsd/man3/sctp_recvmsg.3 @@ -0,0 +1,308 @@ +.\" $NetBSD: sctp_recvmsg.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2018 +.Dt SCTP_RECVMSG 3 +.Os +.Sh NAME +.Nm sctp_recvmsg +.Nd receive a message from an SCTP socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft ssize_t +.Fo sctp_recvmsg +.Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" +.Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" +.Fc +.Sh DESCRIPTION +The +.Fn sctp_recvmsg +system call +is used to receive a message from another SCTP endpoint. +The +.Fn sctp_recvmsg +call is used by one-to-one +.Dv ( SOCK_STREAM ) +type sockets after a successful +.Fn connect +call or after the application has performed a +.Fn listen +followed by a successful +.Fn accept . +For a one-to-many +.Dv ( SOCK_SEQPACKET ) +type socket, an endpoint may call +.Fn sctp_recvmsg +after having implicitly started an association via one +of the send calls including +.Fn sctp_sendmsg , +.Fn sendto , +and +.Fn sendmsg . +Or, an application may also receive a message after having +called +.Fn listen +with a positive backlog to enable the reception of new associations. +.Pp +The address of the sender is held in the +.Fa from +argument with +.Fa fromlen +specifying its size. +At the completion of a successful +.Fn sctp_recvmsg +call +.Fa from +will hold the address of the peer and +.Fa fromlen +will hold the length of that address. +Note that +the address is bounded by the initial value of +.Fa fromlen +which is used as an in/out variable. +.Pp +The length of the message +.Fa msg +to be received is bounded by +.Fa len . +If the message is too long to fit in the users +receive buffer, then the +.Fa flags +argument will +.Em not +have the +.Dv MSG_EOF +flag applied. +If the message is a complete message then +the +.Fa flags +argument will have +.Dv MSG_EOF +set. +Locally detected errors are +indicated by a return value of \-1 with +.Va errno +set accordingly. +The +.Fa flags +argument may also hold the value +.Dv MSG_NOTIFICATION . +When this +occurs it indicates that the message received is +.Em not +from +the peer endpoint, but instead is a notification from the +SCTP stack (see +.Xr sctp 4 +for more details). +Note that no notifications are ever +given unless the user subscribes to such notifications using +the +.Dv SCTP_EVENTS +socket option. +.Pp +If no messages are available at the socket then +.Fn sctp_recvmsg +normally blocks on the reception of a message or NOTIFICATION, unless the +socket has been placed in non-blocking I/O mode. +The +.Xr select 2 +system call may be used to determine when it is possible to +receive a message. +.Pp +The +.Fa sinfo +argument is defined as follows. +.Bd -literal +struct sctp_sndrcvinfo { + uint16_t sinfo_stream; /* Stream arriving on */ + uint16_t sinfo_ssn; /* Stream Sequence Number */ + uint16_t sinfo_flags; /* Flags on the incoming message */ + uint32_t sinfo_ppid; /* The ppid field */ + uint32_t sinfo_context; /* context field */ + uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ + uint32_t sinfo_tsn; /* The transport sequence number */ + uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ + sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ +}; +.Ed +.Pp +The +.Fa sinfo->sinfo_ppid +field is an opaque 32 bit value that is passed transparently +through the stack from the peer endpoint. +Note that the stack passes this value without regard to byte +order. +.Pp +The +.Fa sinfo->sinfo_flags +field may include the following: +.Bd -literal +#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ +.Ed +.Pp +The +.Dv SCTP_UNORDERED +flag is used to specify that the message arrived with no +specific order and was delivered to the peer application +as soon as possible. +When this flag is absent the message +was delivered in order within the stream it was received. +.Pp +The +.Fa sinfo->sinfo_stream +field is the SCTP stream that the message was received on. +Streams in SCTP are reliable (or partially reliable) flows of ordered +messages. +.Pp +The +.Fa sinfo->sinfo_context +field is used only if the local application set an association level +context with the +.Dv SCTP_CONTEXT +socket option. +Optionally a user process can use this value to index some application +specific data structure for all data coming from a specific +association. +.Pp +The +.Fa sinfo->sinfo_ssn +field will hold the stream sequence number assigned +by the peer endpoint if the message is +.Em not +unordered. +For unordered messages this field holds an undefined value. +.Pp +The +.Fa sinfo->sinfo_tsn +field holds a transport sequence number (TSN) that was assigned +to this message by the peer endpoint. +For messages that fit in or less +than the path MTU this will be the only TSN assigned. +Note that for messages that span multiple TSNs this +value will be one of the TSNs that was used on the +message. +.Pp +The +.Fa sinfo->sinfo_cumtsn +field holds the current cumulative acknowledgment point of +the transport association. +Note that this may be larger +or smaller than the TSN assigned to the message itself. +.Pp +The +.Fa sinfo->sinfo_assoc_id +is the unique association identification that was assigned +to the association. +For one-to-many +.Dv ( SOCK_SEQPACKET ) +type sockets this value can be used to send data to the peer without +the use of an address field. +It is also quite useful in +setting various socket options on the specific association +(see +.Xr sctp 4 ) . +.Pp +The +.Fa sinfo->info_timetolive +field is not used by +.Fn sctp_recvmsg . +.Sh RETURN VALUES +The call returns the number of bytes received, or \-1 +if an error occurred. +.Sh ERRORS +The +.Fn sctp_recvmsg +system call +fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The socket is marked non-blocking and the requested operation +would block. +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er ECONNRESET +An abort was received by the stack while the user was +attempting to send data to the peer. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +This error is also returned when +the output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +.It Bq Er ENOENT +On a one to many style socket no address is specified +so that the association cannot be located or the +.Dv SCTP_ABORT +flag was specified on a non-existing association. +.It Bq Er ENOTCONN +On a one-to-one style socket no association exists. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EPIPE +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket +is not connected and is a one-to-one style socket. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr sendmsg 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr sctp_send 3 , +.Xr sctp_sendmsg 3 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +This function first appeared in +.Nx 9.0 . diff --git a/static/netbsd/man3/sctp_send.3 b/static/netbsd/man3/sctp_send.3 new file mode 100644 index 00000000..c28b755a --- /dev/null +++ b/static/netbsd/man3/sctp_send.3 @@ -0,0 +1,368 @@ +.\" $NetBSD: sctp_send.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 1, 2018 +.Dt SCTP_SEND 3 +.Os +.Sh NAME +.Nm sctp_send , +.Nm sctp_sendx +.Nd send a message from an SCTP socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft ssize_t +.Fo sctp_send +.Fa "int sd" "const void *msg" "size_t len" +.Fa "const struct sctp_sndrcvinfo *sinfo" "int flags" +.Fc +.Ft ssize_t +.Fo sctp_sendx +.Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs" +.Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn sctp_send +system call +is used to transmit a message to another SCTP endpoint. +.Fn sctp_send +may be used to send data to an existing association for both +one-to-many +.Dv ( SOCK_SEQPACKET ) +and one-to-one +.Dv ( SOCK_STREAM ) +socket types. +The length of the message +.Fa msg +is given by +.Fa len . +If the message is too long to pass atomically through the +underlying protocol, +.Va errno +is set to +.Er EMSGSIZE , +\-1 is returned, and +the message is not transmitted. +.Pp +No indication of failure to deliver is implicit in a +.Fn sctp_send . +Locally detected errors are indicated by a return value of \-1. +.Pp +If no space is available at the socket to hold +the message to be transmitted, then +.Fn sctp_send +normally blocks, unless the socket has been placed in +non-blocking I/O mode. +The +.Xr select 2 +system call may be used to determine when it is possible to +send more data on one-to-one type +.Dv ( SOCK_STREAM ) +sockets. +.Pp +The +.Fa sinfo +structure is used to control various SCTP features +and has the following format: +.Bd -literal +struct sctp_sndrcvinfo { + uint16_t sinfo_stream; /* Stream sending to */ + uint16_t sinfo_ssn; /* valid for recv only */ + uint16_t sinfo_flags; /* flags to control sending */ + uint32_t sinfo_ppid; /* ppid field */ + uint32_t sinfo_context; /* context field */ + uint32_t sinfo_timetolive; /* timetolive for PR-SCTP */ + uint32_t sinfo_tsn; /* valid for recv only */ + uint32_t sinfo_cumtsn; /* valid for recv only */ + sctp_assoc_t sinfo_assoc_id; /* The association id */ +}; +.Ed +.Pp +The +.Fa sinfo->sinfo_ppid +argument is an opaque 32 bit value that is passed transparently +through the stack to the peer endpoint. +It will be available on reception of a message (see +.Xr sctp_recvmsg 3 ) . +Note that the stack passes this value without regard to byte +order. +.Pp +The +.Fa sinfo->sinfo_flags +argument may include one or more of the following: +.Bd -literal +#define SCTP_EOF 0x0100 /* Start a shutdown procedures */ +#define SCTP_ABORT 0x0200 /* Send an ABORT to peer */ +#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ +#define SCTP_ADDR_OVER 0x0800 /* Override the primary-address */ +#define SCTP_SENDALL 0x1000 /* Send this on all associations */ + /* for the endpoint */ +/* The lower byte is an enumeration of PR-SCTP policies */ +#define SCTP_PR_SCTP_TTL 0x0001 /* Time based PR-SCTP */ +#define SCTP_PR_SCTP_BUF 0x0002 /* Buffer based PR-SCTP */ +#define SCTP_PR_SCTP_RTX 0x0003 /* Number of retransmissions based PR-SCTP */ +.Ed +.Pp +The flag +.Dv SCTP_EOF +is used to instruct the SCTP stack to queue this message +and then start a graceful shutdown of the association. +All +remaining data in queue will be sent after which the association +will be shut down. +.Pp +.Dv SCTP_ABORT +is used to immediately terminate an association. +An abort +is sent to the peer and the local TCB is destroyed. +.Pp +.Dv SCTP_UNORDERED +is used to specify that the message being sent has no +specific order and should be delivered to the peer application +as soon as possible. +When this flag is absent messages +are delivered in order within the stream they are sent, but without +respect to order to peer streams. +.Pp +The flag +.Dv SCTP_ADDR_OVER +is used to specify that a specific address should be used. +Normally +SCTP will use only one of a multi-homed peers addresses as the primary +address to send to. +By default, no matter what the +.Fa to +argument is, this primary address is used to send data. +By specifying +this flag, the user is asking the stack to ignore the primary address +and instead use the specified address not only as a lookup mechanism +to find the association but also as the actual address to send to. +.Pp +For a one-to-many type +.Dv ( SOCK_SEQPACKET ) +socket the flag +.Dv SCTP_SENDALL +can be used as a convenient way to make one send call and have +all associations that are under the socket get a copy of the message. +Note that this mechanism is quite efficient and makes only one actual +copy of the data which is shared by all the associations for sending. +.Pp +The remaining flags are used for the partial reliability extension (RFC3758) +and will only be effective if the peer endpoint supports this extension. +This option specifies what local policy the local endpoint should use +in skipping data. +If none of these options are set, then data is +never skipped over. +.Pp +.Dv SCTP_PR_SCTP_TTL +is used to indicate that a time based lifetime is being applied +to the data. +The +.Fa sinfo->sinfo_timetolive +argument is then a number of milliseconds for which the data is +attempted to be transmitted. +If that many milliseconds elapse +and the peer has not acknowledged the data, the data will be +skipped and no longer transmitted. +Note that this policy does +not even assure that the data will ever be sent. +In times of a congestion +with large amounts of data being queued, the +.Fa sinfo->sinfo_timetolive +may expire before the first transmission is ever made. +.Pp +The +.Dv SCTP_PR_SCTP_BUF +based policy transforms the +.Fa sinfo->sinfo_timetolive +field into a total number of bytes allowed on the outbound +send queue. +If that number or more bytes are in queue, then +other buffer-based sends are looked to be removed and +skipped. +Note that this policy may also result in the data +never being sent if no buffer based sends are in queue and +the maximum specified by +.Fa timetolive +bytes is in queue. +.Pp +The +.Dv SCTP_PR_SCTP_RTX +policy transforms the +.Fa sinfo->sinfo_timetolive +into a number of retransmissions to allow. +This policy +always assures that at a minimum one send attempt is +made of the data. +After which no more than +.Fa sinfo->sinfo_timetolive +retransmissions will be made before the data is skipped. +.Pp +.Fa sinfo->sinfo_stream +is the SCTP stream that you wish to send the +message on. +Streams in SCTP are reliable (or partially reliable) flows of ordered +messages. +.Pp +The +.Fa sinfo->sinfo_assoc_id +field is used to +select the association to send to on a one-to-many socket. +For a one-to-one socket, this field is ignored. +.Pp +The +.Fa sinfo->sinfo_context +field is used only in the event the message cannot be sent. +This is an opaque +value that the stack retains and will give to the user when a failed send +is given if that notification is enabled (see +.Xr sctp 4 ) . +Normally a user process can use this value to index some application +specific data structure when a send cannot be fulfilled. +.Pp +The +.Fa flags +argument holds the same meaning and values as those found in +.Xr sendmsg 2 +but is generally ignored by SCTP. +.Pp +The fields +.Fa sinfo->sinfo_ssn , +.Fa sinfo->sinfo_tsn , +and +.Fa sinfo->sinfo_cumtsn +are used only when receiving messages and are thus ignored by +.Fn sctp_send . +The function +.Fn sctp_sendx +has the same properties as +.Fn sctp_send +with the additional arguments of an array of sockaddr structures +passed in. +With the +.Fa addrs +argument being given as an array of addresses to be sent to and +the +.Fa addrcnt +argument indicating how many socket addresses are in the passed +in array. +Note that all of the addresses will only be used +when an implicit association is being set up. +This allows the +user the equivalent behavior as doing a +.Fn sctp_connectx +followed by a +.Fn sctp_send +to the association. +Note that if the +.Fa sinfo->sinfo_assoc_id +field is 0, then the first address will be used to look up +the association in place of the association id. +If both +an address and an association id are specified, the association +id has priority. +.Sh RETURN VALUES +The call returns the number of characters sent, or \-1 +if an error occurred. +.Sh ERRORS +The +.Fn sctp_send +system call +fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The socket is marked non-blocking and the requested operation +would block. +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er ECONNRESET +An abort was received by the stack while the user was +attempting to send data to the peer. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +This error is also returned when +the output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +.It Bq Er ENOENT +On a one-to-many style socket no address is specified +so that the association cannot be located or the +.Dv SCTP_ABORT +flag was specified on a non-existing association. +.It Bq Er ENOTCONN +On a one-to-one style socket no association exists. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EPIPE +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket +is not connected and is a one-to-one style socket. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr sendmsg 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr sctp_connectx 3 , +.Xr sctp_recvmsg 3 , +.Xr sctp_sendmsg 3 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +These functions first appeared in +.Nx 9.0 . +.Sh BUGS +Because +.Fn sctp_send +may have multiple associations under one endpoint, a +select on write will only work for a one-to-one style +socket. diff --git a/static/netbsd/man3/sctp_sendmsg.3 b/static/netbsd/man3/sctp_sendmsg.3 new file mode 100644 index 00000000..73c458a3 --- /dev/null +++ b/static/netbsd/man3/sctp_sendmsg.3 @@ -0,0 +1,346 @@ +.\" $NetBSD: sctp_sendmsg.3,v 1.2 2018/08/13 06:00:21 wiz Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" +.Dd August 1, 2018 +.Dt SCTP_SENDMSG 3 +.Os +.Sh NAME +.Nm sctp_sendmsg , +.Nm sctp_sendmsgx +.Nd send a message from an SCTP socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft ssize_t +.Fo sctp_sendmsg +.Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to" +.Fa "socklen_t tolen" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" +.Fa "uint32_t timetolive" "uint32_t context" +.Fc +.Ft ssize_t +.Fo sctp_sendmsgx +.Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to" +.Fa "int addrcnt" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" +.Fa "uint32_t timetolive" "uint32_t context" +.Fc +.Sh DESCRIPTION +The +.Fn sctp_sendmsg +system call +is used to transmit a message to another SCTP endpoint. +The +.Fn sctp_sendmsg +may be used at any time. +If the socket is a one-to-many type +.Dv ( SOCK_SEQPACKET ) +socket then an attempt to send to an address that no association exists to will +implicitly create a new association. +Data sent in such an instance will result in +the data being sent on the third leg of the SCTP four-way handshake. +Note that if +the socket is a one-to-one type +.Dv ( SOCK_STREAM ) +socket then an association must +be in existence (by use of the +.Xr connect 2 +system call). +Calling +.Fn sctp_sendmsg +or +.Fn sctp_sendmsgx +on a non-connected one-to-one socket will result in +.Va errno +being set to +.Er ENOTCONN , +\-1 being returned, and the message not being transmitted. +.Pp +The address of the target is given by +.Fa to +with +.Fa tolen +specifying its size. +The length of the message +.Fa msg +is given by +.Fa len . +If the message is too long to pass atomically through the +underlying protocol, +.Va errno +is set to +.Er EMSGSIZE , +\-1 is returned, and +the message is not transmitted. +.Pp +No indication of failure to deliver is implicit in a +.Fn sctp_sendmsg +call. +Locally detected errors are indicated by a return value of -1. +.Pp +If no space is available at the socket to hold +the message to be transmitted, then +.Fn sctp_sendmsg +normally blocks, unless the socket has been placed in +non-blocking I/O mode. +The +.Xr select 2 +system call may be used to determine when it is possible to +send more data on one-to-one type +.Dv ( SOCK_STREAM ) +sockets. +.Pp +The +.Fa ppid +argument is an opaque 32 bit value that is passed transparently +through the stack to the peer endpoint. +It will be available on +reception of a message (see +.Xr sctp_recvmsg 3 ) . +Note that the stack passes this value without regard to byte +order. +.Pp +The +.Fa flags +argument may include one or more of the following: +.Bd -literal +#define SCTP_EOF 0x0100 /* Start a shutdown procedures */ +#define SCTP_ABORT 0x0200 /* Send an ABORT to peer */ +#define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ +#define SCTP_ADDR_OVER 0x0800 /* Override the primary-address */ +#define SCTP_SENDALL 0x1000 /* Send this on all associations */ + /* for the endpoint */ +/* The lower byte is an enumeration of PR-SCTP policies */ +#define SCTP_PR_SCTP_TTL 0x0001 /* Time based PR-SCTP */ +#define SCTP_PR_SCTP_BUF 0x0002 /* Buffer based PR-SCTP */ +#define SCTP_PR_SCTP_RTX 0x0003 /* Number of retransmissions based PR-SCTP */ +.Ed +.Pp +The flag +.Dv SCTP_EOF +is used to instruct the SCTP stack to queue this message +and then start a graceful shutdown of the association. +All +remaining data in queue will be sent after which the association +will be shut down. +.Pp +.Dv SCTP_ABORT +is used to immediately terminate an association. +An abort +is sent to the peer and the local TCB is destroyed. +.Pp +.Dv SCTP_UNORDERED +is used to specify that the message being sent has no +specific order and should be delivered to the peer application +as soon as possible. +When this flag is absent messages +are delivered in order within the stream they are sent, but without +respect to order to peer streams. +.Pp +The flag +.Dv SCTP_ADDR_OVER +is used to specify that an specific address should be used. +Normally +SCTP will use only one of a multi-homed peers addresses as the primary +address to send to. +By default, no matter what the +.Fa to +argument is, this primary address is used to send data. +By specifying +this flag, the user is asking the stack to ignore the primary address +and instead use the specified address not only as a lookup mechanism +to find the association but also as the actual address to send to. +.Pp +For a one-to-many type +.Dv ( SOCK_SEQPACKET ) +socket the flag +.Dv SCTP_SENDALL +can be used as a convenient way to make one send call and have +all associations that are under the socket get a copy of the message. +Note that this mechanism is quite efficient and makes only one actual +copy of the data which is shared by all the associations for sending. +.Pp +The remaining flags are used for the partial reliability extension (RFC3758) +and will only be effective if the peer endpoint supports this extension. +This option specifies what local policy the local endpoint should use +in skipping data. +If none of these options are set, then data is +never skipped over. +.Pp +.Dv SCTP_PR_SCTP_TTL +is used to indicate that a time based lifetime is being applied +to the data. +The +.Fa timetolive +argument is then a number of milliseconds for which the data is +attempted to be transmitted. +If that many milliseconds elapse +and the peer has not acknowledged the data, the data will be +skipped and no longer transmitted. +Note that this policy does +not even assure that the data will ever be sent. +In times of a congestion +with large amounts of data being queued, the +.Fa timetolive +may expire before the first transmission is ever made. +.Pp +The +.Dv SCTP_PR_SCTP_BUF +based policy transforms the +.Fa timetolive +field into a total number of bytes allowed on the outbound +send queue. +If that number or more bytes are in queue, then +other buffer based sends are looked to be removed and +skipped. +Note that this policy may also result in the data +never being sent if no buffer based sends are in queue and +the maximum specified by +.Fa timetolive +bytes is in queue. +.Pp +The +.Dv SCTP_PR_SCTP_RTX +policy transforms the +.Fa timetolive +into a number of retransmissions to allow. +This policy +always assures that at a minimum one send attempt is +made of the data. +After which no more than +.Fa timetolive +retransmissions will be made before the data is skipped. +.Pp +.Fa stream_no +is the SCTP stream that you wish to send the +message on. +Streams in SCTP are reliable (or partially reliable) flows of ordered +messages. +The +.Fa context +field is used only in the event the message cannot be sent. +This is an opaque +value that the stack retains and will give to the user when a failed send +is given if that notification is enabled (see +.Xr sctp 4 ) . +Normally a user process can use this value to index some application +specific data structure when a send cannot be fulfilled. +.Fn sctp_sendmsgx +is identical to +.Fn sctp_sendmsg +with the exception that it takes an array of sockaddr structures in the +argument +.Fa to +and adds the additional argument +.Fa addrcnt +which specifies how many addresses are in the array. +This allows a +caller to implicitly set up an association passing multiple addresses +as if +.Fn sctp_connectx +had been called to set up the association. +.Sh RETURN VALUES +The call returns the number of characters sent, or \-1 +if an error occurred. +.Sh ERRORS +The +.Fn sctp_sendmsg +system call +fails if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The socket is marked non-blocking and the requested operation +would block. +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er ECONNRESET +An abort was received by the stack while the user was +attempting to send data to the peer. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +This error is also returned when +the output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +.It Bq Er ENOENT +On a one-to-many style socket no address is specified +so that the association cannot be located or the +.Dv SCTP_ABORT +flag was specified on a non-existing association. +.It Bq Er ENOTCONN +On a one-to-one style socket no association exists. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EPIPE +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket +is not connected and is a one-to-one style socket. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr sendmsg 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr sctp_connectx 3 , +.Xr sctp 4 +.Rs +.%R RFC +.%N 6458 +.%T "Sockets API Extensions for the Stream Control Transmission Protocol (SCTP)" +.%D December 2011 +.Re +.Sh HISTORY +These functions first appeared in +.Nx 9.0 . +.Sh BUGS +Because in the one-to-many style socket +.Fn sctp_sendmsg +or +.Fn sctp_sendmsgx +may have multiple associations under one endpoint, a +select on write will only work for a one-to-one style +socket. diff --git a/static/netbsd/man3/sdp.3 b/static/netbsd/man3/sdp.3 new file mode 100644 index 00000000..4fe0cab1 --- /dev/null +++ b/static/netbsd/man3/sdp.3 @@ -0,0 +1,260 @@ +.\" $NetBSD: sdp.3,v 1.5 2024/10/13 14:56:30 rillig Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Iain Hibbert. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 13, 2024 +.Dt SDP 3 +.Os +.Sh NAME +.Nm sdp_open , +.Nm sdp_open_local , +.Nm sdp_close , +.Nm sdp_service_search , +.Nm sdp_service_attribute , +.Nm sdp_service_search_attribute , +.Nm sdp_record_insert , +.Nm sdp_record_update , +.Nm sdp_record_remove +.Nd Service Discovery Protocol session routines +.Sh LIBRARY +.Lb libbluetooth +.Sh SYNOPSIS +.In sdp.h +.Ft sdp_session_t +.Fn sdp_open "const bdaddr_t *laddr" "const bdaddr_t *raddr" +.Ft sdp_session_t +.Fn sdp_open_local "const char *control" +.Ft void +.Fn sdp_close "sdp_session_t ss" +.Ft bool +.Fo sdp_service_search +.Fa "sdp_session_t ss" "const sdp_data_t *ssp" "uint32_t *handlep" "int *num" +.Fc +.Ft bool +.Fo sdp_service_attribute +.Fa "sdp_session_t ss" "uint32_t handle" "const sdp_data_t *ail" "sdp_data_t *response" +.Fc +.Ft bool +.Fo sdp_service_search_attribute +.Fa "sdp_session_t ss" "const sdp_data_t *ssp" "const sdp_data_t *ail" "sdp_data_t *response" +.Fc +.Ft bool +.Fo sdp_record_insert +.Fa "sdp_session_t ss" "bdaddr_t *bdaddr" "uint32_t *handlep" "const sdp_data_t *record" +.Fc +.Ft bool +.Fn sdp_record_update "sdp_session_t ss" "uint32_t handle" "sdp_data_t *record" +.Ft bool +.Fn sdp_record_remove "sdp_session_t ss" "uint32_t handle" +.Sh DESCRIPTION +The SDP library provides means for client programs to perform Bluetooth +Service Discovery, and to advertise Service Records on the local host. +.Pp +The Service Discovery API reflects the Bluetooth SDP specification, providing +access to complete ServiceSearch, ServiceAttribute or ServiceSearchAttribute +transactions and using SDP data element lists directly which can be +constructed and parsed with the +.Xr sdp_data 3 +library functions. +.Pp +The ServiceSearchPattern is a list of UUID data elements. +The list must +contain at least one UUID and the maximum number of UUIDs is 12. +A service record will be matched when all the UUIDs from the +ServiceSearchPattern are contained in the record. +.Pp +The AttributeIDList is a list of data elements where each is either an +attribute ID encoded as an unsigned 16-bit integer, or a range of attribute +IDs encoded as an unsigned 32-bit integer where the high order 16-bits are +the start of the range and the low order 16-bits are the end of the range +.Pq inclusive . +The AttributeIDList should be arranged in ascending order and there should +be no duplicate attribute ID values. +If +.Dv NULL +is passed, all attributes +.Pq 0x0000-0xffff +will be requested. +.Pp +ServiceRecords to be registered with the local +.Xr sdpd 8 +server should consist of a list of attribute ID/value pairs, where the +attribute ID is a 16-bit unsigned integer element, and the attribute value +is any data element. +The attribute IDs should be in ascending order, and the first one must be +.Dv SDP_ATTR_SERVICE_RECORD_HANDLE +.Pq 0x0000 , +otherwise the server will reject the record. +For consistency, records should also contain a BrowseGroupList with the +PublicBrowseGroup UUID, plus at least a ServiceName string in the native +language with an associated LanguageBaseAttributeIDList although this is +not currently enforced. +.Sh FUNCTIONS +.Bl -tag -width xxxx +.It Fn sdp_open "laddr" "raddr" +Open a SDP session to a remote Bluetooth device. +.Fa laddr +refers to the local bluetooth device address and may be +.Dv NULL +in which case it will default to +.Dv BDADDR_ANY . +.It Fn sdp_open_local "control" +Open a SDP session to a server using a local socket. +The +.Fa control +socket path may be given as +.Dv NULL +in which case the default control path +.Pa /var/run/sdp +will be used. +.It Fn sdp_close ss +Close SDP session and release all resources. +.It Fn sdp_service_search "ss" "ssp" "handlep" "num" +Perform a complete ServiceSearch transaction on the SDP session. +At most +.Fa num +service record handles matching the ServiceSearchPattern +.Fa ssp +will be returned in the array pointed to by +.Fa handlep . +.It Fn sdp_service_attribute "ss" "handle" "ail" "response" +Perform a complete ServiceAttribute transaction on the SDP session. +The ServiceRecord with ServiceRecordHandle +.Fa handle +will be parsed using the AttributeIDList +.Fa ail . +If the transaction succeeds, the +.Fa response +data buffer will contain a validated data element list of attribute +ID/value pairs from the selected record. +.It Fn sdp_service_search_attribute "ss" "ssp" "ail" "response" +Perform a complete ServiceSearchAttribute transaction on the SDP session. +All ServiceRecords matching the ServiceSearchPattern +.Fa ssp +will be parsed using the AttributeIDList +.Fa ail . +If the transaction succeeds, the +.Fa response +data buffer will contain a valid data element list of sequences, where +each sequence is the attribute ID/value list from a matched record. +.It Fn sdp_record_insert "ss" "bdaddr" "handlep" "record" +Insert a ServiceRecord +.Fa record . +If +.Fa bdaddr +is given, the service record will be restricted to clients connecting +through the Bluetooth controller with that BD_ADDR. +When the +.Fa handlep +pointer is non NULL, the resulting ServiceRecordHandle will be written +to the address given. +The record will be valid while the session is active and will be +purged when the session is closed. +.It Fn sdp_record_update "ss" "handle" "record" +Update a ServiceRecord that is owned by this session. +.Fa handle +is the identifier returned by the +.Fn sdp_record_insert +call, and +.Fa record +is the updated ServiceRecord as described above. +.It Fn sdp_record_remove "ss" "handle" +Remove a ServiceRecord owned by this session. +.Fa handle +is the identifier returned by the +.Fn sdp_record_insert +call. +.El +.Pp +A single response buffer is maintained for each session, so the results +of a ServiceAttribute or ServiceSearchAttribute request will only be valid +until another request is made or the session is closed. +The SDP specifications do not mandate a limit on the size of the response +buffer but this implementation has a default limit of UINT16_MAX bytes. +This limit can be increased at runtime by setting the environment variable +.Ev SDP_RESPONSE_MAX +to a numeric value. +.Pp +Records are only allowed to be removed or updated by the session that inserted +them, and records will be removed automatically when the session is closed. +Further, manipulating service records will normally only be possible for +privileged users on a SDP session connected with a local socket. +See +.Xr sdpd 8 +and your local system administrator for details. +.Sh RETURN VALUES +Session open routines will return a session handle on success and +.Dv NULL +on failure. +For service lookup and record manipulation routines, a boolean value is +returned indicating success or failure. +On failure, +.Va errno +will be set to indicate the error. +.Sh FILES +.Pa /var/run/sdp +.Sh ERRORS +In addition to errors returned by the standard C library IO functions, +the following errors may be detected by +.Nm libbluetooth : +.Bl -tag -offset indent -width ".Bq Er ENOATTR" +.It Bq Er EINVAL +A provided function argument was not valid. +.It Bq Er EIO +A response from the remote server was not understood. +.It Bq Er ENOATTR +The record +.Fa handle +did not exist on the server. +.El +.Sh SEE ALSO +.Xr sdpquery 1 , +.Xr bluetooth 3 , +.Xr sdp_data 3 , +.Xr sdpd 8 +.Pp +The +.Qq Service Discovery Protocol +section of the Bluetooth Core specifications, available at +.Lk http://www.bluetooth.com/ +.Sh HISTORY +The first Service Discovery implementation was written for +.Fx +and was ported to +.Nx 4.0 . +This, the second version API, was designed by +.An Iain Hibbert +for +.Nx 6.0 +in order to simplify the +.Xr sdpd 8 +daemon and allow client code greater control over all aspects of the +service records. +The original API is still available when +.Dv SDP_COMPAT +is defined but will eventually be removed. diff --git a/static/netbsd/man3/sdp_data.3 b/static/netbsd/man3/sdp_data.3 new file mode 100644 index 00000000..383a307c --- /dev/null +++ b/static/netbsd/man3/sdp_data.3 @@ -0,0 +1,393 @@ +.\" $NetBSD: sdp_data.3,v 1.10 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Iain Hibbert. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 15, 2011 +.Dt SDP_DATA 3 +.Os +.Sh NAME +.Nm sdp_match_uuid16 +.Nm sdp_get_data +.Nm sdp_get_attr +.Nm sdp_get_uuid +.Nm sdp_get_bool +.Nm sdp_get_seq +.Nm sdp_get_alt +.Nm sdp_get_uint +.Nm sdp_get_int +.Nm sdp_get_str +.Nm sdp_get_url +.Nm sdp_put_data +.Nm sdp_put_attr +.Nm sdp_put_uuid +.Nm sdp_put_uuid16 +.Nm sdp_put_uuid32 +.Nm sdp_put_uuid128 +.Nm sdp_put_bool +.Nm sdp_put_uint +.Nm sdp_put_uint8 +.Nm sdp_put_uint16 +.Nm sdp_put_uint32 +.Nm sdp_put_uint64 +.Nm sdp_put_int +.Nm sdp_put_int8 +.Nm sdp_put_int16 +.Nm sdp_put_int32 +.Nm sdp_put_int64 +.Nm sdp_put_seq +.Nm sdp_put_alt +.Nm sdp_put_str +.Nm sdp_put_url +.Nm sdp_set_bool +.Nm sdp_set_uint +.Nm sdp_set_int +.Nm sdp_set_seq +.Nm sdp_set_alt +.Nm sdp_data_size +.Nm sdp_data_type +.Nm sdp_data_valid +.Nm sdp_data_print +.Nd Service Discovery Protocol data manipulation routines +.Sh LIBRARY +.Lb libbluetooth +.Sh SYNOPSIS +.In sdp.h +.Vt extern const uuid_t BLUETOOTH_BASE_UUID ; +.Ft bool +.Fn sdp_match_uuid16 "sdp_data_t *data" "uint16_t uuid" +.Ft bool +.Fn sdp_get_data "sdp_data_t *data" "sdp_data_t *value" +.Ft bool +.Fn sdp_get_attr "sdp_data_t *data" "uint16_t *attr" "sdp_data_t *value" +.Ft bool +.Fn sdp_get_uuid "sdp_data_t *data" "uuid_t *uuid" +.Ft bool +.Fn sdp_get_bool "sdp_data_t *data" "bool *value" +.Ft bool +.Fn sdp_get_seq "sdp_data_t *data" "sdp_data_t *seq" +.Ft bool +.Fn sdp_get_alt "sdp_data_t *data" "sdp_data_t *alt" +.Ft bool +.Fn sdp_get_uint "sdp_data_t *data" "uintmax_t *value" +.Ft bool +.Fn sdp_get_int "sdp_data_t *data" "intmax_t *value" +.Ft bool +.Fn sdp_get_str "sdp_data_t *data" "char **str" "size_t *length" +.Ft bool +.Fn sdp_get_url "sdp_data_t *data" "char **url" "size_t *length" +.Ft bool +.Fn sdp_put_data "sdp_data_t *data" "sdp_data_t *value" +.Ft bool +.Fn sdp_put_attr "sdp_data_t *data" "uint16_t attr" "sdp_data_t *value" +.Ft bool +.Fn sdp_put_uuid "sdp_data_t *data" "const uuid_t *value" +.Ft bool +.Fn sdp_put_uuid16 "sdp_data_t *data" "uint16_t value" +.Ft bool +.Fn sdp_put_uuid32 "sdp_data_t *data" "uint32_t value" +.Ft bool +.Fn sdp_put_uuid128 "sdp_data_t *data" "const uuid_t *value" +.Ft bool +.Fn sdp_put_bool "sdp_data_t *data" "bool value" +.Ft bool +.Fn sdp_put_uint "sdp_data_t *data" "uintmax_t value" +.Ft bool +.Fn sdp_put_uint8 "sdp_data_t *data" "uint8_t value" +.Ft bool +.Fn sdp_put_uint16 "sdp_data_t *data" "uint16_t value" +.Ft bool +.Fn sdp_put_uint32 "sdp_data_t *data" "uint32_t value" +.Ft bool +.Fn sdp_put_uint64 "sdp_data_t *data" "uint64_t value" +.Ft bool +.Fn sdp_put_int "sdp_data_t *data" "intmax_t value" +.Ft bool +.Fn sdp_put_int8 "sdp_data_t *data" "int8_t value" +.Ft bool +.Fn sdp_put_int16 "sdp_data_t *data" "int16_t value" +.Ft bool +.Fn sdp_put_int32 "sdp_data_t *data" "int32_t value" +.Ft bool +.Fn sdp_put_int64 "sdp_data_t *data" "int64_t value" +.Ft bool +.Fn sdp_put_seq "sdp_data_t *data" "ssize_t length" +.Ft bool +.Fn sdp_put_alt "sdp_data_t *data" "ssize_t length" +.Ft bool +.Fn sdp_put_str "sdp_data_t *data" "const char *str" "ssize_t length" +.Ft bool +.Fn sdp_put_url "sdp_data_t *data" "const char *url" "ssize_t length" +.Ft bool +.Fn sdp_set_bool "const sdp_data_t *data" "bool value" +.Ft bool +.Fn sdp_set_uint "const sdp_data_t *data" "uintmax_t value" +.Ft bool +.Fn sdp_set_int "const sdp_data_t *data" "intmax_t value" +.Ft bool +.Fn sdp_set_seq "const sdp_data_t *data" "ssize_t length" +.Ft ssize_t +.Fn sdp_data_size "const sdp_data_t *data" +.Ft int +.Fn sdp_data_type "const sdp_data_t *data" +.Ft bool +.Fn sdp_data_valid "const sdp_data_t *data" +.Ft void +.Fn sdp_data_print "const sdp_data_t *data" "int indent" +.Sh DESCRIPTION +These routines provide for the manipulation of Service Discovery +Protocol data buffers. +An SDP data buffer type is defined as: +.Bd -literal -offset indent +typedef struct { + uint8_t *next; + uint8_t *end; +} sdp_data_t; +.Ed +.Pp +Where +.Fa next +points to the next available byte, and +.Fa end +points to the first address past end of the data area, such that +.Qq end = next + length . +.Pp +The SDP data consists of byte streams describing data elements, where +a data element is a typed data representation consisting of a header +field and a data field. +The header field consists of type and size descriptors, and the data +field is a sequence of bytes whose length is specified in the size +descriptor and whose content is specified by the type descriptor. +For instance, the byte sequence +.Qq 0x09, 0x01, 0x00 +describes an 16-bit unsigned integer element (type 0x09) with +value of 0x0100. +.Pp +Data element types including signed and unsigned integers, boolean, +string, sequence and alternative lists are defined in the +.In sdp.h +include file. +See the +.Qq Service Discovery Protocol +chapters of the +.Qq Bluetooth Core Specifications +for more information. +.Pp +To reduce the burden of storing and transferring 128-bit UUID values, a +range of UUID values has been pre-allocated for assignment to often-used, +registered purposes. +The first UUID in this pre-allocated range is known as the +.Qq Bluetooth Base UUID , +defined in the +.Qq Bluetooth Assigned Numbers +document and declared in +.In sdp.h +as +.Vt const uuid_t BLUETOOTH_BASE_UUID ; +.Pp +The data manipulation routines are arranged into major groups +by function: +.Bl -hang +.It The Fn sdp_match_uuid16 +routine examines the next data element in the data buffer for +an element of type UUID that matches the Bluetooth short alias +UUID with 16-bit value given. +If the UUID matches, the function will return +.Dv true +and the +.Fa next +field of the SDP data buffer will be advanced to the next element. +Otherwise +.Dv false +will be returned. +.It The Fn sdp_get_xxxx +routines examine the next data element in the data buffer for an +element of the given type. +If the type matches, the function will extract the typed value to +the address given and advance the +.Fa next +field of the SDP data buffer to the next element then return +.Dv true . +Otherwise +.Dv false +will be returned. +Note, these functions will not modify the +.Fa data +argument unless the correct type was found, and will update the +.Fa data +argument first to allow discarding in the case where a +.Dv sdp_data_t +was being returned. +.It The Fn sdp_put_xxxx +routines will attempt to write a data element of the given type +and value to the data buffer. +If the data buffer is too small to contain the encoded data element, +the function will return +.Dv false , +otherwise +.Dv true +will be returned and the +.Fa next +field of the SDP data pointer will be advanced. +In the case of +.Fn sdp_put_seq +and +.Fn sdp_put_alt , +the +.Fa length +argument may be -1, in which case the generated sequence header will +describe all the remaining buffer space. +For +.Fn sdp_put_str +and +.Fn sdp_put_url +the +.Fa length +argument may be -1 in which case the string pointer is treated as +nul terminated. +.It The Fn sdp_set_xxxx +routines examine the SDP data buffer for a data element of the given +type, and replace the content with the passed value. +If the next data element in the buffer is not of the appropriate +type, the function will return +.Dv false , +otherwise +.Dv true +will be returned and the value updated. +In the case of +.Fn sdp_set_seq +and +.Fn sdp_set_alt , +the +.Fa length +argument may be -1, in which case the sequence header will be +adjusted to describe the entire data space where possible. +.It The Fn sdp_data_xxxx +routines include various functions to provide information about +the data stream such as +.Fn sdp_data_size +to return the size of the next data element, and +.Fn sdp_data_type +to return the type of the next data element. +.Fn sdp_data_valid +can be used to ensure that the entire data buffer contains +valid SDP data elements and that all of the elements are contained +exactly within the data buffer. +Finally, +.Fn sdp_data_print +will print the data buffer in human readable format. +.El +.Sh EXAMPLES +To parse a ServiceAttribute response obtained from a remote server +using +.Xr sdp_service_attribute 3 , +examining various attribute values: +.Bd -literal + sdp_data_t rsp, val; + uint16_t attr; + uintmax_t handle; + + /* rsp contains remote response */ + + while (sdp_get_attr(&rsp, &attr, &val)) { + switch(attr) { + case SDP_ATTR_SERVICE_RECORD_HANDLE: + sdp_get_uint(&val, &handle); + printf("ServiceRecordHandle: 0x%08x\\n", handle); + break; + + case SDP_ATTR_PROFILE_DESCRIPTOR_LIST: + printf("ProfileDescriptorList:\\n"); + sdp_data_print(&val, 0); + break; + + default: + printf("uninteresting attribute 0x%04x\\n", attr); + break; + } + } +.Ed +.Pp +The following code creates a ProtocolDataList attribute value for a service +using the L2CAP and RFCOMM protocols and illustrates how to construct sequences +of known and unknown length. +.Bd -literal + uint8_t buf[SIZE]; + sdp_data_t seq; + uint16_t psm; + uint8_t channel; + + seq.next = buf; + seq.end = buf + sizeof(buf); + sdp_put_seq(&seq, -1); + + sdp_put_seq(&seq, 6); + sdp_put_uuid16(&seq, SDP_UUID_PROTOCOL_L2CAP); + sdp_put_uint16(&seq, psm); + + sdp_put_seq(&seq, 5); + sdp_put_uuid16(&seq, SDP_UUID_PROTOCOL_RFCOMM); + sdp_put_uint8(&seq, channel); + + seq.end = seq.next; + seq.next = buf; + sdp_set_seq(&seq, -1); +.Ed +.Pp +Note that although +.Dv SIZE +is assumed to be large enough to contain the entire sequence +in this case, the +.Fn sdp_put_xxxx +routines will not overflow the buffer area or write partial data. +.Pp +The encoded data stream will be stored in a space efficient +manner where possible. +In the above example, it is known that the data element sequence +containing the L2CAP UUID will be 8 bytes long overall since the +container length of 6 can be stored in a single byte. +But, because the value of +.Dv SIZE +is unknown, the overall length of the ProtocolDataList may vary +depending if 8, 16 or 32 bits were needed to represent the original +buffer size. +.Fn sdp_set_seq +will only modify the content, not the size of the header. +.Sh SEE ALSO +.Xr sdpquery 1 , +.Xr bluetooth 3 , +.Xr sdp 3 , +.Xr uuid 3 , +.Xr sdpd 8 +.Pp +The +.Qq Service Discovery Protocol +section of the Bluetooth Core specifications, available at +.Lk http://www.bluetooth.com/ +.Sh HISTORY +These SDP data parsing and manipulation functions first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/secure_path.3 b/static/netbsd/man3/secure_path.3 new file mode 100644 index 00000000..1506c3b1 --- /dev/null +++ b/static/netbsd/man3/secure_path.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: secure_path.3,v 1.10 2010/05/04 06:41:27 jruoho Exp $ +.\" +.\" Copyright (c) 1996,1997 Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Berkeley Software Design, +.\" Inc. +.\" 4. The name of Berkeley Software Design, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from BSDI: login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp +.\" +.Dd May 4, 2010 +.Dt SECURE_PATH 3 +.Os +.Sh NAME +.Nm secure_path +.Nd determine if a file appears to be ``secure'' +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn secure_path "const char *path" +.Sh DESCRIPTION +The +.Fn secure_path +function takes a path name and returns zero if the referenced file is +.Dq secure , +non-zero if not. +Any +.Dq insecurity , +other than failure to access +the referenced file, will be logged to the system log. +.Pp +To be +.Dq secure , +the referenced file must exist, be a regular file (and not a +directory), owned by the super-user, and writable only by the super-user. +.Sh SEE ALSO +.Xr openlog 3 +.Sh HISTORY +The +.Fn secure_path +function is based on the +.Bsx +implementation of same, and appeared in +.Nx 1.5 +by kind permission. diff --git a/static/netbsd/man3/sem_destroy.3 b/static/netbsd/man3/sem_destroy.3 new file mode 100644 index 00000000..1fd18311 --- /dev/null +++ b/static/netbsd/man3/sem_destroy.3 @@ -0,0 +1,82 @@ +.\" $NetBSD: sem_destroy.3,v 1.2 2007/08/07 20:45:05 wiz Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 22, 2003 +.Dt SEM_DESTROY 3 +.Os +.Sh NAME +.Nm sem_destroy +.Nd destroy an unnamed semaphore +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_destroy "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_destroy +function destroys the unnamed semaphore pointed to by +.Fa sem . +After a successful call to +.Fn sem_destroy , +.Fa sem +is unusable until re-initialized by another call to +.Fn sem_init . +.Sh RETURN VALUES +.Rv -std sem_destroy +.Sh ERRORS +.Fn sem_destroy +will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +There are currently threads blocked on the semaphore that +.Fa sem +points to. +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_init 3 +.Sh STANDARDS +.Fn sem_destroy +conforms to +.St -p1003.1-96 . +.Pp +POSIX does not define the behavior of +.Fn sem_destroy +if called while there are threads blocked on +.Fa sem , +but this implementation is guaranteed to return \-1 and set +.Va errno +to +.Er EBUSY +if there are threads blocked on +.Fa sem . diff --git a/static/netbsd/man3/sem_getvalue.3 b/static/netbsd/man3/sem_getvalue.3 new file mode 100644 index 00000000..4dda2f6a --- /dev/null +++ b/static/netbsd/man3/sem_getvalue.3 @@ -0,0 +1,76 @@ +.\" $NetBSD: sem_getvalue.3,v 1.4 2012/03/08 22:12:37 wiz Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 29, 2012 +.Dt SEM_GETVALUE 3 +.Os +.Sh NAME +.Nm sem_getvalue +.Nd get the value of a semaphore +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_getvalue "sem_t * restrict sem" "int * restrict sval" +.Sh DESCRIPTION +The +.Fn sem_getvalue +function sets the variable pointed to by +.Fa sval +to the current value of the semaphore pointed to by +.Fa sem , +as of the time that the call to +.Fn sem_getvalue +is actually run. +.Sh RETURN VALUES +.Rv -std sem_getvalue +.Sh ERRORS +.Fn sem_getvalue +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_post 3 , +.Xr sem_timedwait 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_getvalue +conforms to +.St -p1003.1-96 . +.Pp +The value of the semaphore is never negative, even if there are threads blocked +on the semaphore. +POSIX is somewhat ambiguous in its wording with regard to +what the value of the semaphore should be if there are blocked waiting threads, +but this behavior is conformant, given the wording of the specification. diff --git a/static/netbsd/man3/sem_init.3 b/static/netbsd/man3/sem_init.3 new file mode 100644 index 00000000..2373d18c --- /dev/null +++ b/static/netbsd/man3/sem_init.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: sem_init.3,v 1.5 2019/02/21 21:54:09 christos Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 21, 2019 +.Dt SEM_INIT 3 +.Os +.Sh NAME +.Nm sem_init +.Nd initialize an unnamed semaphore +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_init "sem_t *sem" "int pshared" "unsigned int value" +.Sh DESCRIPTION +The +.Fn sem_init +function initializes the unnamed semaphore pointed to by +.Fa sem +to have the value +.Fa value . +A non-zero value for +.Fa pshared +specifies a shared semaphore that can be used by multiple processes. +.Pp +Following a successful call to +.Fn sem_init , +.Fa sem +can be used as an argument in subsequent calls to +.Fn sem_wait , +.Fn sem_timedwait , +.Fn sem_trywait , +.Fn sem_post , +and +.Fn sem_destroy . +.Fa sem +is no longer valid after a successful call to +.Fa sem_destroy . +.Sh RETURN VALUES +.Rv -std sem_init +.Sh ERRORS +.Fn sem_init +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa value +exceeds SEM_VALUE_MAX. +.It Bq Er ENOSPC +There was memory allocation error, or the limit on available semaphores +.Dv ( SEM_NSEMS_MAX ) +has been exceeded. +.It Bq Er EPERM +Unable to initialize a shared semaphore. +.El +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_post 3 , +.Xr sem_timedwait 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_init +conforms to +.St -p1003.1-96 . diff --git a/static/netbsd/man3/sem_open.3 b/static/netbsd/man3/sem_open.3 new file mode 100644 index 00000000..cbf67e9e --- /dev/null +++ b/static/netbsd/man3/sem_open.3 @@ -0,0 +1,227 @@ +.\" $NetBSD: sem_open.3,v 1.8 2018/05/05 06:39:10 wiz Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" From: FreeBSD: src/lib/libc/gen/sem_open.3,v 1.12 2004/07/02 16:45:56 ru +.\" +.Dd May 4, 2018 +.Dt SEM_OPEN 3 +.Os +.Sh NAME +.Nm sem_open , +.Nm sem_close , +.Nm sem_unlink +.Nd named semaphore operations +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft "sem_t *" +.Fn sem_open "const char *name" "int oflag" ... +.Ft int +.Fn sem_close "sem_t *sem" +.Ft int +.Fn sem_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn sem_open +function creates or opens the named semaphore specified by +.Fa name . +The returned semaphore may be used in subsequent calls to +.Xr sem_getvalue 3 , +.Xr sem_timedwait 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 , +.Xr sem_post 3 , +and +.Fn sem_close . +.Pp +The following bits may be set in the +.Fa oflag +argument: +.Bl -tag -width ".Dv O_CREAT" +.It Dv O_CREAT +Create the semaphore if it does not already exist. +.Pp +The third argument to the call to +.Fn sem_open +must be of type +.Vt mode_t +and specifies the mode for the semaphore. +Only the +.Dv S_IWUSR , S_IWGRP , +and +.Dv S_IWOTH +bits are examined; +it is not possible to grant only +.Dq read +permission on a semaphore. +The mode is modified according to the process's file creation +mask; see +.Xr umask 2 . +.Pp +The fourth argument must be an +.Vt "unsigned int" +and specifies the initial value for the semaphore, +and must be no greater than +.Dv SEM_VALUE_MAX . +.It Dv O_EXCL +Create the semaphore if it does not exist. +If the semaphore already exists, +.Fn sem_open +will fail. +This flag is ignored unless +.Dv O_CREAT +is also specified. +.El +.Pp +The +.Fn sem_close +function closes a named semaphore that was opened by a call to +.Fn sem_open . +.Pp +The +.Fn sem_unlink +function removes the semaphore named +.Fa name . +Resources allocated to the semaphore are only deallocated when all +processes that have the semaphore open close it. +.Sh RETURN VALUES +If successful, +the +.Fn sem_open +function returns the address of the opened semaphore. +If the same +.Fa name +argument is given to multiple calls to +.Fn sem_open +by the same process without an intervening call to +.Fn sem_close , +the same address is returned each time. +If the semaphore cannot be opened, +.Fn sem_open +returns +.Dv SEM_FAILED +and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std sem_close sem_unlink +.Sh ERRORS +The +.Fn sem_open +function will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The semaphore exists and the permissions specified by +.Fa oflag +at the time it was created deny access to this process; +or the semaphore does not exist, but permission to create it is denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are set but the semaphore already exists. +.It Bq Er EINTR +The call was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa name +argument does not begin with a +.Sq / +or contains more slashes. +This is implementation-specific behavior and allowed by +.St -p1003.1-96 . +Or, the +.Fa value +argument is greater than +.Dv SEM_VALUE_MAX . +.\"FreeBSD never returns EMFILE +.\".It Bq Er EMFILE +.\"Too many semaphores are in use by this process. +.It Bq Er ENAMETOOLONG +The specified +.Fa name +is longer than +.Dv NAME_MAX , +or longer than the implementing file system will allow. +.It Bq Er ENFILE +The system limit on semaphores has been reached. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named semaphore does not exist. +.It Bq Er ENOSPC +There is not enough space to create the semaphore. +.El +.Pp +The +.Fn sem_close +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sem +argument is not a valid semaphore. +.El +.Pp +The +.Fn sem_unlink +function will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission is denied to unlink the semaphore. +.It Bq Er ENAMETOOLONG +The specified +.Fa name +is longer than +.Dv NAME_MAX , +or longer than the implementing file system will allow. +.It Bq Er ENOENT +The named semaphore does not exist. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr umask 2 , +.Xr unlink 2 , +.Xr sem_getvalue 3 , +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 , +.Xr sem 4 +.Sh STANDARDS +The +.Fn sem_open , +.Fn sem_close , +and +.Fn sem_unlink +functions conform to +.St -p1003.1-96 . +.Sh HISTORY +Support for named semaphores first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/sem_post.3 b/static/netbsd/man3/sem_post.3 new file mode 100644 index 00000000..059113d4 --- /dev/null +++ b/static/netbsd/man3/sem_post.3 @@ -0,0 +1,74 @@ +.\" $NetBSD: sem_post.3,v 1.3 2012/03/08 22:13:05 wiz Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 29, 2012 +.Dt SEM_POST 3 +.Os +.Sh NAME +.Nm sem_post +.Nd increment (unlock) a semaphore +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_post "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_post +function increments (unlocks) the semaphore pointed to by +.Fa sem . +If there are threads blocked on the semaphore when +.Fn sem_post +is called, then the highest priority thread that has been blocked the longest on +the semaphore will be allowed to return from +.Fn sem_wait +or +.Fn sem_timedwait . +.Pp +.Fn sem_post +is signal-reentrant and may be called within signal handlers. +.Sh RETURN VALUES +.Rv -std sem_post +.Sh ERRORS +.Fn sem_post +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Sh SEE ALSO +.Xr sem_timedwait 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 +.Sh STANDARDS +.Fn sem_post +conforms to +.St -p1003.1-96 . diff --git a/static/netbsd/man3/sem_wait.3 b/static/netbsd/man3/sem_wait.3 new file mode 100644 index 00000000..1eb062a8 --- /dev/null +++ b/static/netbsd/man3/sem_wait.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: sem_wait.3,v 1.3 2012/03/08 22:13:32 wiz Exp $ +.\" +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 29, 2012 +.Dt SEM_WAIT 3 +.Os +.Sh NAME +.Nm sem_wait , +.Nm sem_timedwait , +.Nm sem_trywait +.Nd decrement (lock) a semaphore +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In semaphore.h +.Ft int +.Fn sem_wait "sem_t *sem" +.Ft int +.Fn sem_timedwait "sem_t *sem" "const struct timespec * restrict abstime" +.Ft int +.Fn sem_trywait "sem_t *sem" +.Sh DESCRIPTION +The +.Fn sem_wait +function decrements (locks) the semaphore pointed to by +.Fa sem , +but blocks if the value of +.Fa sem +is zero, until the value is non-zero and the value can be decremented. +.Pp +The +.Fn sem_timedwait +function performs the same action, but will not wait beyond +.Fa abstime +for the value of +.Fa sem +to be non-zero. +.Pp +The +.Fn sem_trywait +function decrements (locks) the semaphore pointed to by +.Fa sem +only if the value is non-zero. +Otherwise, the semaphore is not decremented and an error is returned. +.Sh RETURN VALUES +.Rv -std sem_wait +.Sh ERRORS +.Fn sem_wait , +.Fn sem_timedwait , +and +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa sem +points to an invalid semaphore. +.El +.Pp +Additionally, +.Fn sem_trywait +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The semaphore value was zero, and thus could not be decremented. +.El +.Pp +.Fn sem_timedwait +will also fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The semaphore value was zero and +.Fa abstime +was reached. +.El +.Sh SEE ALSO +.Xr sem_post 3 +.Sh STANDARDS +.Fn sem_wait +and +.Fn sem_trywait +conform to +.St -p1003.1-96 . diff --git a/static/netbsd/man3/setbuf.3 b/static/netbsd/man3/setbuf.3 new file mode 100644 index 00000000..dc548d8b --- /dev/null +++ b/static/netbsd/man3/setbuf.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: setbuf.3,v 1.20 2018/12/14 03:43:22 uwe Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setbuf.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt SETBUF 3 +.Os +.Sh NAME +.Nm setbuf , +.Nm setbuffer , +.Nm setlinebuf , +.Nm setvbuf +.Nd stream buffering operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn setbuf "FILE * restrict stream" "char * restrict buf" +.Ft void +.Fn setbuffer "FILE *stream" "char *buf" "size_t size" +.Ft int +.Fn setlinebuf "FILE *stream" +.Ft int +.Fn setvbuf "FILE * restrict stream" "char * restrict buf" "int mode" "size_t size" +.Sh DESCRIPTION +The three types of buffering available are unbuffered, block buffered, +and line buffered. +When an output stream is unbuffered, information appears on the +destination file or terminal as soon as written; +when it is block buffered many characters are saved up and written as a block; +when it is line buffered characters are saved up until a newline is +output or input is read from any stream attached to a terminal device +(typically +.Va stdin ) . +.Pp +The default buffer settings can be overwritten per descriptor +.Ev ( STDBUF Ns Ar n , +where +.Ar n +is the numeric value of the file descriptor represented by the stream), or +for all descriptors +.Ev ( STDBUF ) . +The environment variable value is a letter followed by an optional numeric +value indicating the size of the buffer. +Valid sizes range from 0B to 1MB. +Valid letters are: +.Bl -tag -offset indent -width X +.It Li U +unbuffered +.It Li L +line buffered +.It Li F +fully buffered +.El +.Pp +The function +.Xr fflush 3 +may be used to force the block out early. +(See +.Xr fclose 3 . ) +.Pp +Normally all files are block buffered. +When the first I/O operation occurs on a file, +.Xr malloc 3 +is called, +and an optimally-sized buffer is obtained. +If a stream refers to a terminal +(as +.Va stdout +normally does) it is line buffered. +The standard error stream +.Va stderr +is initially unbuffered. +.Pp +The +.Fn setvbuf +function +may be used to alter the buffering behavior of a stream. +The +.Fa mode +parameter must be one of the following three macros: +.Bl -tag -width _IOFBF -offset indent +.It Dv _IONBF +unbuffered +.It Dv _IOLBF +line buffered +.It Dv _IOFBF +fully buffered +.El +.Pp +The +.Fa size +parameter may be given as zero +to obtain deferred optimal-size buffer allocation as usual. +If it is not zero, +then except for unbuffered files, the +.Fa buf +argument should point to a buffer at least +.Fa size +bytes long; +this buffer will be used instead of the current buffer. +(If the +.Fa size +argument +is not zero but +.Fa buf +is +.Dv NULL , +a buffer of the given size will be allocated immediately, +and released on close. +This is an extension to ANSI C; +portable code should use a size of 0 with any +.Dv NULL +buffer.) +.Pp +The +.Fn setvbuf +function may be used at any time, +but may have peculiar side effects +(such as discarding input or flushing output) +if the stream is ``active''. +Portable applications should call it only once on any given stream, +and before any I/O is performed. +.Pp +The other three calls are, in effect, simply aliases for calls to +.Fn setvbuf . +Except for the lack of a return value, the +.Fn setbuf +function is exactly equivalent to the call +.Pp +.Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" +.Pp +The +.Fn setbuffer +function +is the same, except that the size of the buffer is up to the caller, +rather than being determined by the default +.Dv BUFSIZ . +The +.Fn setlinebuf +function +is exactly equivalent to the call: +.Pp +.Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" +.Sh RETURN VALUES +The +.Fn setvbuf +function returns 0 on success, or +.Dv EOF +if the request cannot be honored +(note that the stream is still functional in this case). +.Pp +The +.Fn setlinebuf +function returns what the equivalent +.Fn setvbuf +would have returned. +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr malloc 3 , +.Xr printf 3 , +.Xr puts 3 +.Sh STANDARDS +The +.Fn setbuf +and +.Fn setvbuf +functions +conform to +.St -ansiC . +.Sh HISTORY +The +.Fn setbuf +function first appeared in +.At v7 . +The +.Fn setbuffer +function first appeared in +.Bx 4.1c . +The +.Fn setlinebuf +function first appeared in +.Bx 4.2 . +The +.Fn setvbuf +function first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn setbuf +function usually uses a suboptimal buffer size and should be avoided. diff --git a/static/netbsd/man3/setjmp.3 b/static/netbsd/man3/setjmp.3 new file mode 100644 index 00000000..8594d8db --- /dev/null +++ b/static/netbsd/man3/setjmp.3 @@ -0,0 +1,238 @@ +.\" $NetBSD: setjmp.3,v 1.18 2021/05/24 23:59:59 riastradh Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setjmp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 1, 2008 +.Dt SETJMP 3 +.Os +.Sh NAME +.Nm sigsetjmp , +.Nm siglongjmp , +.Nm setjmp , +.Nm longjmp , +.Nm _setjmp , +.Nm _longjmp , +.Nm longjmperror +.Nd non-local jumps +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In setjmp.h +.Ft int +.Fn sigsetjmp "sigjmp_buf env" "int savemask" +.Ft void +.Fn siglongjmp "sigjmp_buf env" "int val" +.Ft int +.Fn setjmp "jmp_buf env" +.Ft void +.Fn longjmp "jmp_buf env" "int val" +.Ft int +.Fn _setjmp "jmp_buf env" +.Ft void +.Fn _longjmp "jmp_buf env" "int val" +.Ft void +.Fn longjmperror void +.Sh DESCRIPTION +The +.Fn sigsetjmp , +.Fn setjmp , +and +.Fn _setjmp +functions save their calling environment in +.Fa env . +Each of these functions returns 0. +.Pp +The corresponding +.Fn longjmp +functions restore the environment saved by the most recent +invocation of the respective +.Fn setjmp +function. +They then return so that program execution continues as if the corresponding +invocation of the +.Fn setjmp +call had just returned the value specified by +.Fa val , +instead of 0. +The +.Fn longjmp +functions cannot cause +.Fn setjmp +to return 0; if +.Fa val +is 0, +.Fn setjmp +returns 1 instead. +.Pp +Pairs of calls may be intermixed, i.e., both +.Fn sigsetjmp +and +.Fn siglongjmp +as well as +.Fn setjmp +and +.Fn longjmp +combinations may be used in the same program. +However, individual calls may not, e.g., the +.Fa env +argument to +.Fn setjmp +may not be passed to +.Fn siglongjmp . +.Pp +The +.Fn longjmp +routines may not be called after the routine which called the +.Fn setjmp +routines returns. +.Pp +All accessible objects have values as of the time +.Fn longjmp +routine was called, except that the values of objects of automatic storage +invocation duration that do not have the +.Li volatile +type and have been changed between the +.Fn setjmp +invocation and +.Fn longjmp +call are indeterminate. +.Pp +The +.Fn setjmp Ns / Ns Fn longjmp +function pairs save and restore the signal mask while +.Fn _setjmp Ns / Ns Fn _longjmp +function pairs save and restore only the register set and the stack. +(See +.Fn sigprocmask 2 . ) +.Pp +The +.Fn sigsetjmp Ns / Ns Fn siglongjmp +function pairs save and restore the signal mask if the argument +.Fa savemask +is non-zero. +Otherwise, only the register set and the stack are saved. +.Pp +In other words, +.Fn setjmp Ns / Ns Fn longjmp +are functionally equivalent to +.Fn sigsetjmp Ns / Ns Fn siglongjmp +when +.Fn sigsetjmp +is called with a non-zero +.Fa savemask +argument. +Conversely, +.Fn _setjmp Ns / Ns Fn _longjmp +are functionally equivalent to +.Fn sigsetjmp Ns / Ns Fn siglongjmp +when +.Fn sigsetjmp +is called with a zero-value +.Fa savemask . +.Pp +The +.Fn sigsetjmp Ns / Ns Fn siglongjmp +interfaces are preferred for maximum portability. +.Sh ERRORS +If the contents of the +.Fa env +are corrupted or correspond to an environment that has already returned, +the +.Fn longjmp +routine calls the routine +.Xr longjmperror 3 . +If +.Fn longjmperror +returns, the program is aborted (see +.Xr abort 3 ) . +The default version of +.Fn longjmperror +prints the message +.Dq Li longjmp botch +to standard error and returns. +User programs wishing to exit more gracefully should write their own +versions of +.Fn longjmperror . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr sigprocmask 2 , +.Xr pthread_sigmask 3 , +.Xr signal 3 +.Sh STANDARDS +The +.Fn setjmp +and +.Fn longjmp +functions conform to +.St -ansiC . +The +.Fn sigsetjmp +and +.Fn siglongjmp +functions conform to +.St -p1003.1-90 . +.Sh CAVEATS +Historically, on +.At V , +the +.Fn setjmp Ns / Ns Fn longjmp +functions have been equivalent to the +.Bx +.Fn _setjmp Ns / Ns Fn _longjmp +functions and do not restore the signal mask. +Because of this discrepancy, the +.Fn sigsetjmp Ns / Ns Fn siglongjmp +interfaces should be used if portability is desired. +.Pp +Use of +.Fn longjmp +or +.Fn siglongjmp +from inside a signal handler is not as easy as it might seem. +Generally speaking, all possible code paths between the +.Fn setjmp +and +.Fn longjmp +must be signal race safe. +Furthermore, the code paths must not do resource management +(such as +.Xr open 2 +or +.Xr close 2 ) +without blocking the signal in question, or resources might +be mismanaged. +Obviously this makes +.Fn longjmp +much less useful than previously thought. diff --git a/static/netbsd/man3/setlocale.3 b/static/netbsd/man3/setlocale.3 new file mode 100644 index 00000000..bc5cec89 --- /dev/null +++ b/static/netbsd/man3/setlocale.3 @@ -0,0 +1,406 @@ +.\" $NetBSD: setlocale.3,v 1.23 2022/12/31 14:35:56 nia Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley at BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd December 31, 2022 +.Dt SETLOCALE 3 +.Os +.Sh NAME +.Nm setlocale , +.Nm localeconv +.Nd natural language formatting for C +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In locale.h +.Ft char * +.Fn setlocale "int category" "const char *locale" +.Ft struct lconv * +.Fn localeconv "void" +.Sh DESCRIPTION +The +.Fn setlocale +function sets the C library's notion +of natural language formatting style +for particular sets of routines. +Each such style is called a +.Sq locale +and is invoked using an appropriate name passed as a C string. +The +.Fn localeconv +routine returns the current locale's parameters +for formatting numbers. +.Pp +The +.Fn setlocale +function recognizes several categories of routines. +These are the categories and the sets of routines they select: +.Bl -tag -width LC_MONETARY +.It Dv LC_ALL +Set the entire locale generically. +.It Dv LC_COLLATE +Set a locale for string collation routines. +This controls alphabetic ordering in +.Fn strcoll +and +.Fn strxfrm . +.It Dv LC_CTYPE +Set a locale for the +.Xr ctype 3 +functions. +This controls recognition of upper and lower case, +alphabetic or non-alphabetic characters, +and so on. +.It Dv LC_MESSAGES +Set a locale for message catalogs. +This controls the selection of message catalogs by the +.Xr catgets 3 +and +.Xr gettext 3 +families of functions. +.It Dv LC_MONETARY +Set a locale for formatting monetary values; +this affects the +.Fn localeconv +function. +.It Dv LC_NUMERIC +Set a locale for formatting numbers. +This controls the formatting of decimal points +in input and output of floating point numbers +in functions such as +.Fn printf +and +.Fn scanf , +as well as values returned by +.Fn localeconv . +.It Dv LC_TIME +Set a locale for formatting dates and times using the +.Fn strftime +function. +.El +.Pp +Only three locales are defined by default, +the empty string +.Li "\&""\|"" +which denotes the native environment, and the +.Li "\&""C"" +and +.Li "\&""POSIX"" +locales, which denote the C language environment. +A +.Fa locale +argument of +.Dv NULL +causes +.Fn setlocale +to return the current locale. +By default, C programs start in the +.Li "\&""C"" +locale. +The format of the locale string is described in +.Xr nls 7 . +.Pp +The only function in the library that sets the locale is +.Fn setlocale ; +the locale is never changed as a side effect of some other routine. +.Pp +Changing the setting of +.Dv LC_MESSAGES +has no effect on catalogs that have already been opened by +.Xr catopen 3 . +.Pp +The +.Fn localeconv +function returns a pointer to a structure +which provides parameters for formatting numbers, +especially currency values: +.Bd -literal -offset indent +struct lconv { + char *decimal_point; + char *thousands_sep; + char *grouping; + char *int_curr_symbol; + char *currency_symbol; + char *mon_decimal_point; + char *mon_thousands_sep; + char *mon_grouping; + char *positive_sign; + char *negative_sign; + char int_frac_digits; + char frac_digits; + char p_cs_precedes; + char p_sep_by_space; + char n_cs_precedes; + char n_sep_by_space; + char p_sign_posn; + char n_sign_posn; + char int_p_cs_precedes; + char int_n_cs_precedes; + char int_p_sep_by_space; + char int_n_sep_by_space; + char int_p_sign_posn; + char int_n_sign_posn; +}; +.Ed +.Pp +The individual fields have the following meanings: +.Bl -tag -width int_p_sep_by_space +.It Fa decimal_point +The decimal point character, except for monetary values. +.It Fa thousands_sep +The separator between groups of digits +before the decimal point, except for monetary values. +.It Fa grouping +The sizes of the groups of digits, except for monetary values. +This is a pointer to a vector of integers, each of size +.Va char , +representing group size from low order digit groups +to high order (right to left). +The list may be terminated with 0 or +.Dv CHAR_MAX . +If the list is terminated with 0, +the last group size before the 0 is repeated to account for all the digits. +If the list is terminated with +.Dv CHAR_MAX , +no more grouping is performed. +.It Fa int_curr_symbol +The standardized (ISO 4217:1995) international currency symbol. +.It Fa currency_symbol +The local currency symbol. +.It Fa mon_decimal_point +The decimal point character for monetary values. +.It Fa mon_thousands_sep +The separator for digit groups in monetary values. +.It Fa mon_grouping +Like +.Fa grouping +but for monetary values. +.It Fa positive_sign +The character used to denote nonnegative monetary values, +usually the empty string. +.It Fa negative_sign +The character used to denote negative monetary values, +usually a minus sign. +.It Fa int_frac_digits +The number of digits after the decimal point +in an internationally formatted monetary value. +.It Fa frac_digits +The number of digits after the decimal point +in an locally formatted monetary value. +.It Fa p_cs_precedes +1 if the currency symbol precedes the monetary value +for nonnegative values, 0 if it follows. +.It Fa p_sep_by_space +1 if a space is inserted between the currency symbol +and the monetary value for nonnegative values, 0 otherwise. +.It Fa n_cs_precedes +Like +.Fa p_cs_precedes +but for negative values. +.It Fa n_sep_by_space +Like +.Fa p_sep_by_space +but for negative values. +.It Fa p_sign_posn +The location of the +.Fa positive_sign +with respect to a nonnegative quantity and the +.Fa currency_symbol . +.It Fa n_sign_posn +Like +.Fa p_sign_posn +but for negative currency values. +.It Fa int_p_cs_precedes +1 if the currency symbol precedes the internationally +formatted monetary value for nonnegative values, 0 if it follows. +.It Fa int_n_cs_precedes +Like +.Fa int_p_cs_precedes +but for negative values. +.It Fa int_p_sep_by_space +1 if a space is inserted between the currency symbol +and the internationally formatted monetary value for +nonnegative values, 0 otherwise. +.It Fa int_n_sep_by_space +Like +.Fa int_p_sep_by_space +but for negative values. +.It Fa int_p_sign_posn +The location of the +.Fa positive_sign +with respect to a nonnegative quantity and the +.Fa currency_symbol , +for internationally formatted nonnegative monetary values. +.It Fa int_n_sign_posn +Like +.Fa int_p_sign_posn +but for negative values. +.El +.Pp +The positional parameters in +.Fa p_sign_posn , +.Fa n_sign_posn , +.Fa int_p_sign_posn +and +.Fa int_n_sign_posn +are encoded as follows: +.Bl -tag -width 3n -compact +.It Li 0 +Parentheses around the entire string. +.It Li 1 +Before the string. +.It Li 2 +After the string. +.It Li 3 +Just before +.Fa currency_symbol . +.It Li 4 +Just after +.Fa currency_symbol . +.El +.Pp +Unless mentioned above, +an empty string as a value for a field +indicates a zero length result or +a value that is not in the current locale. +A +.Dv CHAR_MAX +result similarly denotes an unavailable value. +.Sh RETURN VALUES +The +.Fn setlocale +function returns +.Dv NULL +and fails to change the locale +if the given combination of +.Fa category +and +.Fa locale +makes no sense. +The +.Fn localeconv +function returns a pointer to a static object +which may be altered by later calls to +.Fn setlocale +or +.Fn localeconv . +.Pp +Currently, +.Fn setlocale +returns +.Dv NULL +and fails to change the locale when +.Dv LC_COLLATE +is modified independently of other values. +.Sh EXAMPLES +The following code illustrates how a program can initialize the +international environment for one language, while selectively +modifying the program's locale such that regular expressions and +string operations can be applied to text recorded in a different +language: +.Bd -literal + setlocale(LC_ALL, "de"); + setlocale(LC_NUMERIC, "C"); +.Ed +.Pp +When a process is started, its current locale is set to the C or POSIX +locale. +An internationalized program that depends on locale data not defined in +the C or POSIX locale must invoke the setlocale subroutine in the +following manner before using any of the locale-specific information: +.Bd -literal + setlocale(LC_ALL, ""); +.Ed +.Sh FILES +The use of multibyte locales requires shared libraries located in +.Pa /usr/lib/i18n . +.\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX +.\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX +.\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX +.\" locale file for the locale \fIlocale\fP XXX +.\" and the category \fIcategory\fP. XXX +.\" .El +.Sh SEE ALSO +.Xr catopen 3 , +.Xr gettext 3 , +.Xr nl_langinfo 3 , +.Xr nls 7 +.\" .Xr strcoll 3 , XXX +.\" .Xr strxfrm 3 XXX +.Sh STANDARDS +The +.Fn setlocale +and +.Fn localeconv +functions conform to +.St -ansiC +and +.St -isoC-90 . +.Pp +The +.Fa int_p_cs_precedes , +.Fa int_n_cs_precedes , +.Fa int_p_sep_by_space , +.Fa int_n_sep_by_space , +.Fa int_p_sign_posn +and +.Fa int_n_sign_posn +members of +.Ft struct lconv +were introduced in +.St -isoC-99 . +.Sh HISTORY +The +.Fn setlocale +and +.Fn localeconv +functions first appeared in +.Bx 4.4 . +.Sh BUGS +In spite of the gnarly currency support in +.Fn localeconv , +the standards don't include any functions +for generalized currency formatting. +.Pp +.Dv LC_COLLATE +is unimplemented (but does not make sense for many languages). +Use of +.Dv LC_MONETARY +could lead to misleading results until we have a real time currency +conversion function. +.Dv LC_NUMERIC +and +.Dv LC_TIME +are personal choices and should not be wrapped up with the other categories. +.Pp +Multibyte locales aren't supported for static binaries. diff --git a/static/netbsd/man3/setmode.3 b/static/netbsd/man3/setmode.3 new file mode 100644 index 00000000..76bc6155 --- /dev/null +++ b/static/netbsd/man3/setmode.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: setmode.3,v 1.24 2024/04/28 22:43:30 rillig Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setmode.3 8.2 (Berkeley) 4/28/95 +.\" +.Dd March 12, 2022 +.Dt SETMODE 3 +.Os +.Sh NAME +.Nm getmode , +.Nm setmode +.Nd modify mode bits +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void * +.Fn setmode "const char *mode_str" +.Ft mode_t +.Fn getmode "const void *set" "mode_t mode" +.Sh DESCRIPTION +The +.Fn setmode +function accepts a string representation of a file mode change, +compiles it to binary form, and returns an abstract representation +that may be passed to +.Fn getmode . +The string may be a numeric (octal) or symbolic string of the form +accepted by +.Xr chmod 1 , +and may represent either an exact mode to set or a change to make to +an existing mode. +.Pp +The +.Fn getmode +function adjusts the file permission bits given by +.Fa mode +according to the compiled change representation +.Fa set , +and returns the adjusted mode. +While only the permission bits are altered, other parts of the file +mode, particularly the type, may be examined. +.Pp +Because some of the possible symbolic values are defined relative to +the file creation mask, +.Fn setmode +may call +.Xr umask 2 , +temporarily changing the mask. +If this occurs, the file creation mask will be restored before +.Fn setmode +returns. +If the calling program changes the value of its file creation mask +after calling +.Fn setmode , +.Fn setmode +must be called again to recompile the mode string if +.Fn getmode +is to modify future file modes correctly. +.Pp +If the mode passed to +.Fn setmode +is invalid, +.Fn setmode +returns +.Dv NULL . +.Sh EXAMPLES +The effects of the shell command +.Ql "chmod a+x myscript.sh" +can be duplicated as follows: +.Bd -literal -offset indent +const char *file = "myscript.sh"; +struct stat st; +mode_t newmode; + +stat(file, &st); +newmode = getmode(setmode("a+x"), st.st_mode); +chmod(file, newmode); +.Ed +.Sh ERRORS +The +.Fn setmode +function +may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr reallocarr 3 +or +.Xr strtol 3 . +In addition, +.Fn setmode +may fail and set +.Va errno +to: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa mode +argument does not represent a valid mode. +.El +.Sh SEE ALSO +.Xr chmod 1 , +.Xr stat 2 , +.Xr umask 2 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn getmode +and +.Fn setmode +functions first appeared in +.Bx 4.4 . +.Sh BUGS +Each call to +.Nm setmode +allocates a small amount of memory that there is no correct way to +free. +.Pp +The type of +.Fa set +should really be some opaque struct type used only by these functions +rather than +.Ft void * . diff --git a/static/netbsd/man3/setproctitle.3 b/static/netbsd/man3/setproctitle.3 new file mode 100644 index 00000000..8d32011f --- /dev/null +++ b/static/netbsd/man3/setproctitle.3 @@ -0,0 +1,99 @@ +.\" $NetBSD: setproctitle.3,v 1.18 2003/07/26 19:24:44 salo Exp $ +.\" +.\" Copyright (c) 1994, 1995 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See http://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd April 13, 1994 +.Dt SETPROCTITLE 3 +.Os +.Sh NAME +.Nm setproctitle +.Nd set process title +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn setproctitle "const char *fmt" "..." +.Sh DESCRIPTION +The +.Fn setproctitle +function sets the invoking process's title. +The process title is set to the last component of the program +name, followed by a colon and the formatted string specified +by +.Va fmt . +If +.Va fmt +is +.Dv NULL , +the colon and formatted string are omitted. +The length of a process title is limited to 2048 bytes. +.Sh EXAMPLES +Set the process title to the program name, with no further information: +.Bd -literal -offset indent +setproctitle(NULL); +.Ed +.Pp +Set the process title to the program name, an informational string, +and the process id: +.Bd -literal -offset indent +setproctitle("foo! (%d)", getpid()); +.Ed +.Sh SEE ALSO +.Xr ps 1 , +.Xr w 1 , +.Xr getprogname 3 , +.Xr printf 3 +.Sh HISTORY +The +.Fn setproctitle +function first appeared in +.Nx 1.0 . +.Sh CAVEATS +It is important never to pass a string with user-supplied data as a +format without using +.Ql %s . +An attacker can put format specifiers in the string to mangle your stack, +leading to a possible security hole. +This holds true even if you have built the string +.Dq by hand +using a function like +.Fn snprintf , +as the resulting string may still contain user-supplied conversion specifiers +for later interpolation by +.Fn setproctitle . +.Pp +Always be sure to use the proper secure idiom: +.Bd -literal -offset indent +setproctitle("%s", string); +.Ed diff --git a/static/netbsd/man3/setruid.3 b/static/netbsd/man3/setruid.3 new file mode 100644 index 00000000..8a557b1d --- /dev/null +++ b/static/netbsd/man3/setruid.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)setruid.3 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: setruid.3,v 1.10 2003/08/07 16:42:40 agc Exp $ +.\" +.Dd June 2, 1993 +.Dt SETRUID 3 +.Os +.Sh NAME +.Nm setruid , +.Nm setrgid +.Nd set user and group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.Ft int +.Fn setruid "uid_t ruid" +.Ft int +.Fn setrgid "gid_t rgid" +.Sh DESCRIPTION +The +.Fn setruid +function +.Pq Fn setrgid +sets the real user ID (group ID) of the +current process. +.Sh RETURN VALUES +Upon success, these functions return 0; +otherwise \-1 is returned. +.Pp +If the user is not the super user, or the uid +specified is not the real or effective ID, these +functions return \-1. +.Pp +The use of these calls is not portable. +Their use is discouraged; they will be removed in the future. +.Sh SEE ALSO +.Xr getgid 2 , +.Xr getuid 2 , +.Xr setegid 2 , +.Xr seteuid 2 , +.Xr setgid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn setruid +and +.Fn setrgid +syscalls appeared in +.Bx 4.2 +and were dropped in +.Bx 4.4 . diff --git a/static/netbsd/man3/sha1.3 b/static/netbsd/man3/sha1.3 new file mode 100644 index 00000000..2e288cd6 --- /dev/null +++ b/static/netbsd/man3/sha1.3 @@ -0,0 +1,225 @@ +.\" $NetBSD: sha1.3,v 1.9 2018/11/27 10:38:14 wiz Exp $ +.\" $OpenBSD: sha1.3,v 1.9 1998/03/07 22:18:12 millert Exp $ +.\" +.\" Copyright (c) 1997, 2004 Todd C. Miller <Todd.Miller@courtesan.com> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" See http://csrc.nist.gov/fips/fip180-1.txt for the detailed standard +.\" +.Dd November 27, 2018 +.Dt SHA1 3 +.Os +.Sh NAME +.Nm SHA1Init , +.Nm SHA1Update , +.Nm SHA1Final , +.Nm SHA1Transform , +.Nm SHA1End , +.Nm SHA1File , +.Nm SHA1FileChunk , +.Nm SHA1Data +.Nd calculate the NIST Secure Hash Algorithm +.Sh SYNOPSIS +.In sys/types.h +.In sha1.h +.Ft void +.Fn SHA1Init "SHA1_CTX *context" +.Ft void +.Fn SHA1Update "SHA1_CTX *context" "const uint8_t *data" "u_int len" +.Ft void +.Fn SHA1Final "uint8_t digest[20]" "SHA1_CTX *context" +.Ft void +.Fn SHA1Transform "uint32_t state[5]" "uint8_t buffer[64]" +.Ft "char *" +.Fn SHA1End "SHA1_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA1File "char *filename" "char *buf" +.Ft "char *" +.Fn SHA1FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA1Data "uint8_t *data" "size_t len" "char *buf" +.Sh DESCRIPTION +The SHA1 functions implement the NIST Secure Hash Algorithm (SHA-1), +FIPS PUB 180-1. +SHA-1 is used to generate a condensed representation +of a message called a message digest. +The algorithm takes a +message less than 2^64 bits as input and produces a 160-bit digest +suitable for use as a digital signature. +.Pp +The SHA1 functions are considered to be more secure than the +.Xr md4 3 +and +.Xr md5 3 +functions with which they share a similar interface. +.Pp +The +.Fn SHA1Init +function initializes a SHA1_CTX +.Ar context +for use with +.Fn SHA1Update , +and +.Fn SHA1Final . +The +.Fn SHA1Update +function adds +.Ar data +of length +.Ar len +to the SHA1_CTX specified by +.Ar context . +.Fn SHA1Final +is called when all data has been added via +.Fn SHA1Update +and stores a message digest in the +.Ar digest +parameter. +When a null pointer is passed to +.Fn SHA1Final +as first argument only the final padding will be applied and the +current context can still be used with +.Fn SHA1Update . +.Pp +The +.Fn SHA1Transform +function is used by +.Fn SHA1Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn SHA1Init , +.Fn SHA1Update +and +.Fn SHA1Final +instead of calling +.Fn SHA1Transform +directly. +.Pp +The +.Fn SHA1End +function is a front end for +.Fn SHA1Final +which converts the digest into an +.Tn ASCII +representation of the 160 bit digest in hexadecimal. +.Pp +The +.Fn SHA1File +function calculates the digest for a file and returns the result via +.Fn SHA1End . +If +.Fn SHA1File +is unable to open the file a NULL pointer is returned. +.Pp +.Fn SHA1FileChunk +behaves like +.Fn SHA1File +but calculates the digest only for that portion of the file starting at +.Fa offset +and continuing for +.Fa length +bytes or until end of file is reached, whichever comes first. +A zero +.Fa length +can be specified to read until end of file. +A negative +.Fa length +or +.Fa offset +will be ignored. +.Pp +The +.Fn SHA1Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn SHA1End . +.Pp +For each of the +.Fn SHA1End , +.Fn SHA1File , +and +.Fn SHA1Data +functions the +.Ar buf +parameter should either be a string of at least 41 characters in +size or a NULL pointer. +In the latter case, space will be dynamically +allocated via +.Xr malloc 3 +and should be freed using +.Xr free 3 +when it is no longer needed. +.Sh EXAMPLES +The follow code fragment will calculate the digest for +the string "abc" which is ``0xa9993e36476816aba3e25717850c26c9cd0d89d''. +.Bd -literal -offset indent +SHA1_CTX sha; +uint8_t results[20]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +SHA1Init(&sha); +SHA1Update(&sha, (uint8_t *)buf, n); +SHA1Final(results, &sha); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n < 20; n++) + printf("%02x", results[n]); +putchar('\en'); +.Ed +.Pp +Alternately, the helper functions could be used in the following way: +.Bd -literal -offset indent +SHA1_CTX sha; +uint8_t output[41]; +char *buf = "abc"; + +printf("0x%s", SHA1Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.\" .Xr sha1 1 , +.Xr md5 1 , +.Xr md4 3 , +.Xr md5 3 +.Pp +.Rs +.%A J. Burrows +.%T The Secure Hash Standard +.%O FIPS PUB 180-1 +.Re +.Sh HISTORY +The SHA-1 functions appeared in +.Nx 1.4 . +.Sh AUTHORS +This implementation of SHA-1 was written by +.An Steve Reid . +.Pp +The +.Fn SHA1End , +.Fn SHA1File , +.Fn SHA1FileChunk , +and +.Fn SHA1Data +helper functions are derived from code written by Poul-Henning Kamp. +.Sh BUGS +This implementation of SHA-1 has not been validated by NIST +and as such is not in official compliance with the standard. +.Pp +If a message digest is to be copied to a multi-byte type (ie: +an array of five 32-bit integers) it will be necessary to +perform byte swapping on little endian machines such as the i386, alpha, +and VAX. diff --git a/static/netbsd/man3/sha2.3 b/static/netbsd/man3/sha2.3 new file mode 100644 index 00000000..3d6f41df --- /dev/null +++ b/static/netbsd/man3/sha2.3 @@ -0,0 +1,314 @@ +.\" $NetBSD: sha2.3,v 1.9 2018/10/09 11:36:35 kamil Exp $ +.\" $OpenBSD: sha2.3,v 1.11 2004/06/22 01:57:29 jfb Exp $ +.\" +.\" Copyright (c) 2003, 2004 Todd C. Miller <Todd.Miller@courtesan.com> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.\" See http://www.nist.gov/sha/ for the detailed standard +.\" +.Dd October 9, 2018 +.Dt SHA2 3 +.Os +.Sh NAME +.Nm SHA224_Init , +.Nm SHA224_Update , +.Nm SHA224_Final , +.Nm SHA224_Transform , +.Nm SHA224_End , +.Nm SHA224_File , +.Nm SHA224_FileChunk , +.Nm SHA224_Data , +.Nm SHA256_Init , +.Nm SHA256_Update , +.Nm SHA256_Final , +.Nm SHA256_Transform , +.Nm SHA256_End , +.Nm SHA256_File , +.Nm SHA256_FileChunk , +.Nm SHA256_Data , +.Nm SHA384_Init , +.Nm SHA384_Update , +.Nm SHA384_Final , +.Nm SHA384_Transform , +.Nm SHA384_End , +.Nm SHA384_File , +.Nm SHA384_FileChunk , +.Nm SHA384_Data , +.Nm SHA512_Init , +.Nm SHA512_Update , +.Nm SHA512_Final , +.Nm SHA512_Transform , +.Nm SHA512_End , +.Nm SHA512_File , +.Nm SHA512_FileChunk , +.Nm SHA512_Data +.Nd calculate the NIST Secure Hash Standard (version 2) +.Sh SYNOPSIS +.In sys/types.h +.In sha2.h +.Ft void +.Fn SHA224_Init "SHA224_CTX *context" +.Ft void +.Fn SHA224_Update "SHA224_CTX *context" "const uint8_t *data" "size_t len" +.Ft void +.Fn SHA224_Final "uint8_t digest[SHA224_DIGEST_LENGTH]" "SHA224_CTX *context" +.Ft void +.Fn SHA224_Transform "uint32_t state[8]" "const uint8_t buffer[SHA224_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA224_End "SHA224_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA224_File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA224_Data "uint8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA256_Init "SHA256_CTX *context" +.Ft void +.Fn SHA256_Update "SHA256_CTX *context" "const uint8_t *data" "size_t len" +.Ft void +.Fn SHA256_Final "uint8_t digest[SHA256_DIGEST_LENGTH]" "SHA256_CTX *context" +.Ft void +.Fn SHA256_Transform "uint32_t state[8]" "const uint8_t buffer[SHA256_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA256_End "SHA256_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA256_File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA256_Data "uint8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA384_Init "SHA384_CTX *context" +.Ft void +.Fn SHA384_Update "SHA384_CTX *context" "const uint8_t *data" "size_t len" +.Ft void +.Fn SHA384_Final "uint8_t digest[SHA384_DIGEST_LENGTH]" "SHA384_CTX *context" +.Ft void +.Fn SHA384_Transform "uint64_t state[8]" "const uint8_t buffer[SHA384_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA384_End "SHA384_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA384_File "char *filename" "char *buf" +.Ft "char *" +.Fn SHA384_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA384_Data "uint8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA512_Init "SHA512_CTX *context" +.Ft void +.Fn SHA512_Update "SHA512_CTX *context" "const uint8_t *data" "size_t len" +.Ft void +.Fn SHA512_Final "uint8_t digest[SHA512_DIGEST_LENGTH]" "SHA512_CTX *context" +.Ft void +.Fn SHA512_Transform "uint64_t state[8]" "const uint8_t buffer[SHA512_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA512_End "SHA512_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA512_File "char *filename" "char *buf" +.Ft "char *" +.Fn SHA512_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA512_Data "uint8_t *data" "size_t len" "char *buf" +.Sh DESCRIPTION +The SHA2 functions implement the NIST Secure Hash Standard, +FIPS PUB 180-2. +The SHA2 functions are used to generate a condensed representation of a +message called a message digest, suitable for use as a digital signature. +There are four families of functions, with names corresponding to +the number of bits in the resulting message digest. +The SHA-224 and SHA-256 functions are limited to processing a message of less +than 2^64 bits as input. +The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1 +bits as input. +.Pp +The SHA2 functions are considered to be more secure than the +.Xr sha1 3 +functions with which they share a similar interface. +The 224, 256, 384, and 512-bit versions of SHA2 share the same interface. +For brevity, only the 256-bit variants are described below. +.Pp +The +.Fn SHA256_Init +function initializes a SHA256_CTX +.Ar context +for use with +.Fn SHA256_Update , +and +.Fn SHA256_Final . +The +.Fn SHA256_Update +function adds +.Ar data +of length +.Ar len +to the SHA256_CTX specified by +.Ar context . +.Fn SHA256_Final +is called when all data has been added via +.Fn SHA256_Update +and stores a message digest in the +.Ar digest +parameter. +.Pp +The +.Fn SHA256_Transform +function is used by +.Fn SHA256_Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn SHA256_Init , +.Fn SHA256_Update , +and +.Fn SHA256_Final +instead of calling +.Fn SHA256_Transform +directly. +.Pp +The +.Fn SHA256_End +function is a front end for +.Fn SHA256_Final +which converts the digest into an ASCII representation of the digest +in hexadecimal. +.Pp +The +.Fn SHA256_File +function calculates the digest for a file and returns the result via +.Fn SHA256_End . +If +.Fn SHA256_File +is unable to open the file, a +.Dv NULL +pointer is returned. +.Pp +.Fn SHA256_FileChunk +behaves like +.Fn SHA256_File +but calculates the digest only for that portion of the file starting at +.Fa offset +and continuing for +.Fa length +bytes or until end of file is reached, whichever comes first. +A zero +.Fa length +can be specified to read until end of file. +A negative +.Fa length +or +.Fa offset +will be ignored. +.Pp +The +.Fn SHA256_Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn SHA256_End . +.Pp +For each of the +.Fn SHA256_End , +.Fn SHA256_File , +.Fn SHA256_FileChunk , +and +.Fn SHA256_Data +functions the +.Ar buf +parameter should either be a string large enough to hold the resulting digest +(e.g., +.Ev SHA224_DIGEST_STRING_LENGTH , +.Ev SHA256_DIGEST_STRING_LENGTH , +.Ev SHA384_DIGEST_STRING_LENGTH , +or +.Ev SHA512_DIGEST_STRING_LENGTH , +depending on the function being used) +or a +.Dv NULL +pointer. +In the latter case, space will be dynamically allocated via +.Xr malloc 3 +and should be freed using +.Xr free 3 +when it is no longer needed. +.Sh EXAMPLES +The following code fragment will calculate the SHA-256 digest for the string +.Qq abc , +which is +.Dq 0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad . +.Bd -literal -offset indent +SHA256_CTX ctx; +uint8_t results[SHA256_DIGEST_LENGTH]; +char *buf; +int n; + +buf = "abc"; +n = strlen(buf); +SHA256_Init(&ctx); +SHA256_Update(&ctx, (uint8_t *)buf, n); +SHA256_Final(results, &ctx); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n < SHA256_DIGEST_LENGTH; n++) + printf("%02x", results[n]); +putchar('\en'); +.Ed +.Pp +Alternately, the helper functions could be used in the following way: +.Bd -literal -offset indent +SHA256_CTX ctx; +uint8_t output[SHA256_DIGEST_STRING_LENGTH]; +char *buf = "abc"; + +printf("0x%s\en", SHA256_Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr cksum 1 , +.Xr md4 3 , +.Xr md5 3 , +.Xr rmd160 3 , +.Xr sha1 3 +.Rs +.%T Secure Hash Standard +.%O FIPS PUB 180-2 +.Re +.Sh HISTORY +The SHA2 functions appeared in +.Ox 3.4 +and +.Nx 3.0 . +.Sh AUTHORS +.An -nosplit +This implementation of the SHA functions was written by +.An Aaron D. Gifford . +.Pp +The +.Fn SHA256_End , +.Fn SHA256_File , +.Fn SHA256_FileChunk , +and +.Fn SHA256_Data +helper functions are derived from code written by +.An Poul-Henning Kamp . +.Sh CAVEATS +This implementation of the Secure Hash Standard has not been validated by +NIST and as such is not in official compliance with the standard. +.Pp +If a message digest is to be copied to a multi-byte type (i.e.: +an array of five 32-bit integers) it will be necessary to +perform byte swapping on little endian machines such as the i386, alpha, +and vax. diff --git a/static/netbsd/man3/sha3.3 b/static/netbsd/man3/sha3.3 new file mode 100644 index 00000000..27dc55a7 --- /dev/null +++ b/static/netbsd/man3/sha3.3 @@ -0,0 +1,129 @@ +.\" $NetBSD: sha3.3,v 1.1 2017/11/30 16:00:48 wiz Exp $ +.\" +.\" Copyright (c) 2015 Taylor R. Campbell +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 14, 2015 +.Dt SHA3 3 +.Os +.Sh NAME +.Nm SHA3 +.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.Sh SYNOPSIS +.In sha3.h +.Ft void +.Fn SHA3_224_Init "SHA3_224_CTX *ctx" +.Ft void +.Fn SHA3_224_Update "SHA3_224_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHA3_224_Final "uint8_t digest[SHA3_224_DIGEST_LENGTH]" "SHA3_224_CTX *ctx" +.Ft void +.Fn SHA3_256_Init "SHA3_256_CTX *ctx" +.Ft void +.Fn SHA3_256_Update "SHA3_256_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHA3_256_Final "uint8_t digest[SHA3_256_DIGEST_LENGTH]" "SHA3_256_CTX *ctx" +.Ft void +.Fn SHA3_384_Init "SHA3_384_CTX *ctx" +.Ft void +.Fn SHA3_384_Update "SHA3_384_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHA3_384_Final "uint8_t digest[SHA3_384_DIGEST_LENGTH]" "SHA3_384_CTX *ctx" +.Ft void +.Fn SHA3_512_Init "SHA3_512_CTX *ctx" +.Ft void +.Fn SHA3_512_Update "SHA3_512_CTX *ctx" "const uint8_t *buf" "size_t len" +.Ft void +.Fn SHA3_512_Final "uint8_t digest[SHA3_512_DIGEST_LENGTH]" "SHA3_512_CTX *ctx" +.Sh DESCRIPTION +The +.Nm +functions implement the cryptographic hash functions of the NIST SHA-3 +standard, FIPS PUB 202. +The +.Nm +functions compress an arbitrary-length message m into short +fixed-length octet strings SHA3-224(m), SHA3-256(m), etc., called a +cryptographic digest or hash. +.Pp +Before using the +.Nm +functions, applications should first call +.Xr SHA3_Selftest 3 +and confirm that it succeeded. +.Pp +Only the +.Nm SHA3_256 +functions are specified in detail; the +.Nm SHA3_224 , +.Nm SHA3_384 , +and +.Nm SHA3_512 +functions are exactly analogous. +.Pp +The caller must allocate memory for a +.Vt SHA3_256_CTX +object to hold the state of a SHA3-256 hash computation over a +message. +.Vt SHA3_256_CTX +objects are slightly over 200 bytes, and may be copied or relocated in +memory. +.Bl -tag -width abcd +.It Fn SHA3_256_Init "ctx" +Initialize a SHA3-256 context. +Must be done before any other operations on +.Fa ctx . +.It Fn SHA3_256_Update "ctx" "data" "len" +Append +.Fa len +octets at +.Fa data +to the message. +.It Fn SHA3_256_Final "digest" "ctx" +Store at +.Fa digest +the 32-octet SHA3-256 hash of the message obtained by concatenating +all prior inputs to +.Fn SHA3_256_Update +on +.Fa ctx . +.Pp +Subsequent use of +.Fa ctx +is not allowed, unless it is reinitialized with +.Fn SHA3_256_Init . +.El +.Sh SEE ALSO +.Xr keccak 3 , +.Xr SHA3_Selftest 3 , +.Xr SHAKE 3 +.Sh STANDARDS +.Rs +.%A National Institute of Standards and Technology +.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions +.%O FIPS PUB 202 +.%D August 2015 +.Re +.Sh AUTHORS +.An Taylor R Campbell Aq campbell+sha3@mumble.net diff --git a/static/netbsd/man3/shm_open.3 b/static/netbsd/man3/shm_open.3 new file mode 100644 index 00000000..131d09c5 --- /dev/null +++ b/static/netbsd/man3/shm_open.3 @@ -0,0 +1,240 @@ +.\" $NetBSD: shm_open.3,v 1.2 2013/12/20 13:48:45 wiz Exp $ +.\" +.\" Copyright 2000 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 19, 2013 +.Dt SHM_OPEN 3 +.Os +.Sh NAME +.Nm shm_open , shm_unlink +.Nd "shared memory object operations" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In sys/types.h +.In sys/mman.h +.In fcntl.h +.Ft int +.Fn shm_open "const char *name" "int flags" "mode_t mode" +.Ft int +.Fn shm_unlink "const char *name" +.Sh DESCRIPTION +The +.Fn shm_open +function creates or opens a +.Tn POSIX +shared memory object named +.Fa name . +The +.Fa flags +argument contains a subset of the flags used by +.Xr open 2 . +An access mode of either +.Dv O_RDONLY +or +.Dv O_RDWR +must be included in +.Fa flags . +The optional flags +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +may also be specified. +.Pp +If +.Dv O_CREAT +is specified, +then a new shared memory object named +.Fa name +will be created if it does not exist. +In this case, +the shared memory object is created with mode +.Fa mode +subject to the process' umask value. +If both the +.Dv O_CREAT +and +.Dv O_EXCL +flags are specified and a shared memory object named +.Fa path +already exists, +then +.Fn shm_open +will fail with +.Er EEXIST . +.Pp +Newly created objects start off with a size of zero. +If an existing shared memory object is opened with +.Dv O_RDWR +and the +.Dv O_TRUNC +flag is specified, +then the shared memory object will be truncated to a size of zero. +The size of the object can be adjusted via +.Xr ftruncate 2 +and queried via +.Xr fstat 2 . +.Pp +The new descriptor is set to close during +.Xr execve 2 +system calls; +see +.Xr close 2 +and +.Xr fcntl 2 . +.Pp +The +.Fn shm_unlink +system call removes a shared memory object named +.Fa path . +.Sh RETURN VALUES +If successful, +.Fn shm_open +returns a non-negative integer, +and +.Fn shm_unlink +returns zero. +Both functions return -1 on failure, and set +.Va errno +to indicate the error. +.Sh COMPATIBILITY +The +.Fa path +argument does not necessarily represent a pathname (although it does in +most other implementations). +Two processes opening the same +.Fa path +are guaranteed to access the same shared memory object if and only if +.Fa path +begins with a slash +.Pq Ql \&/ +character. +.Pp +Only the +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +flags may be used in portable programs. +.Pp +The result of using +.Xr open 2 , +.Xr read 2 , +or +.Xr write 2 +on a shared memory object, or on the descriptor returned by +.Fn shm_open , +is undefined. +It is also undefined whether the shared memory object itself, or its +contents, persist across reboots. +.Sh ERRORS +The following errors are defined for +.Fn shm_open : +.Bl -tag -width Er +.It Bq Er EACCES +The required permissions (for reading or reading and writing) are denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are specified and the named shared memory object does exist. +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er EINVAL +A flag other than +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +or +.Dv O_TRUNC +was included in +.Fa flags ; +or the +.Fa path +does not begin with a slash +.Pq Ql \&/ +character. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENAMETOOLONG +The entire pathname exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOENT +.Dv O_CREAT +is specified and the named shared memory object does not exist. +.It Bq Er ENOTSUP +Not supported, most likely due to missing or incorrect +.Pa /var/shm +mount. +.El +.Pp +The following errors are defined for +.Fn shm_unlink : +.Bl -tag -width Er +.It Bq Er EACCES +The required permissions are denied. +.Fn shm_unlink +requires write permission to the shared memory object. +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named shared memory object does not exist. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr fstat 2 , +.Xr ftruncate 2 , +.Xr mmap 2 , +.Xr munmap 2 +.Sh STANDARDS +The +.Fn shm_open +and +.Fn shm_unlink +functions are expected to conform to +.St -p1003.1b-93 . +.Sh HISTORY +These functions first appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/shquote.3 b/static/netbsd/man3/shquote.3 new file mode 100644 index 00000000..fcaf4c0a --- /dev/null +++ b/static/netbsd/man3/shquote.3 @@ -0,0 +1,244 @@ +.\" $NetBSD: shquote.3,v 1.10 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 2001 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the +.\" NetBSD Project. See http://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>> +.\" +.Dd September 7, 2008 +.Dt SHQUOTE 3 +.Os +.Sh NAME +.Nm shquote , +.Nm shquotev +.Nd quote argument strings for use with the shell +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Fn shquote "const char *arg" "char *buf" "size_t bufsize" +.Ft size_t +.Fn shquotev "int argc" "char * const *argv" "char *buf" "size_t bufsize" +.Sh DESCRIPTION +The +.Fn shquote +and +.Fn shquotev +functions copy strings and transform the copies by adding shell +escape and quoting characters. +They are used to encapsulate +arguments to be included in command strings passed to the +.Fn system +and +.Fn popen +functions, so that the arguments will have the correct values +after being evaluated by the shell. +.Pp +The exact method of quoting and escaping may vary, and is intended +to match the conventions of the shell used by +.Fn system +and +.Fn popen . +It may not match the conventions used by other shells. +In this implementation, the following +transformation is applied to each input string: +.Bl -bullet -width indent +.It +it is surrounded by single quotes +.Pq ' , +.It +any single quotes in the input are escaped by replacing them with +the four-character sequence: +.Li '\e'' , +and +.It +extraneous pairs of single quotes (caused by multiple adjacent single +quotes in the input string, or by single quotes at the beginning or +end of the input string) are elided. +.El +.Pp +The +.Fn shquote +function transforms the string specified by its +.Fa arg +argument, and places the result into the memory pointed to by +.Fa buf . +.Pp +The +.Fn shquotev +function transforms each of the +.Fa argc +strings specified by the array +.Fa argv +independently. +The transformed strings are placed in the memory pointed to by +.Fa buf , +separated by spaces. +It does not modify the pointer array specified by +.Fa argv +or the strings pointed to by the pointers in the array. +.Pp +Both functions write up to +.Fa bufsize +- 1 characters of output into the buffer pointed to by +.Fa buf , +then add a +.Li NUL +character to terminate the output string. +If +.Fa bufsize +is given as zero, the +.Fa buf +parameter is ignored and no output is written. +.Sh RETURN VALUES +The +.Fn shquote +and +.Fn shquotev +functions return the number of characters necessary to hold the +result from operating on their input strings, +not including the terminating +.Li NUL . +That is, they return the length of the string that would have +been written to the output buffer, if it were large enough. +If an error occurs during processing, the value ((size_t)\-1) +is returned and +.Va errno +is set appropriately. +.Sh EXAMPLES +The following code fragment demonstrates how you might use +.Fn shquotev +to construct a command string to be used with +.Fn system . +The command uses an environment variable (which will be expanded by +the shell) to determine the actual program to run. +Note that the environment variable may be expanded by +the shell into multiple words. +The first word of the expansion will be used by the shell +as the name of the program to run, +and the rest will be passed as arguments to the program. +.Bd -literal -offset indent +char **argv, c, *cmd; +size_t cmdlen, len, qlen; +int argc; + +\&... + +/* + * Size buffer to hold the command string, and allocate it. + * Buffer of length one given to snprintf() for portability. + */ +cmdlen = snprintf(&c, 1, "${PROG-%s} ", PROG_DEFAULT); +qlen = shquotev(argc, argv, NULL, 0); +if (qlen == (size_t)-1) { + \&... +} +cmdlen += qlen + 1; +cmd = malloc(cmdlen); +if (cmd == NULL) { + \&... +} + +/* Create the command string. */ +len = snprintf(cmd, cmdlen, "${PROG-%s} ", PROG_DEFAULT); +qlen = shquotev(argc, argv, cmd + len, cmdlen - len); +if (qlen == (size_t)-1) { + /* Should not ever happen. */ + \&... +} +len += qlen; + +/* "cmd" can now be passed to system(). */ +.Ed +.Pp +The following example shows how you would implement the same +functionality using the +.Fn shquote +function directly. +.Bd -literal -offset indent +char **argv, c, *cmd; +size_t cmdlen, len, qlen; +int argc, i; + +\&... + +/* + * Size buffer to hold the command string, and allocate it. + * Buffer of length one given to snprintf() for portability. + */ +cmdlen = snprintf(&c, 1, "${PROG-%s} ", PROG_DEFAULT); +for (i = 0; i < argc; i++) { + qlen = shquote(argv[i], NULL, 0); + if (qlen == (size_t)-1) { + \&... + } + cmdlen += qlen + 1; +} +cmd = malloc(cmdlen); +if (cmd == NULL) { + \&... +} + +/* Start the command string with the env var reference. */ +len = snprintf(cmd, cmdlen, "${PROG-%s} ", PROG_DEFAULT); + +/* Quote all of the arguments when copying them. */ +for (i = 0; i < argc; i++) { + qlen = shquote(argv[i], cmd + len, cmdlen - len); + if (qlen == (size_t)-1) { + /* Should not ever happen. */ + \&... + } + len += qlen; + cmd[len++] = ' '; +} +cmd[--len] = '\e0'; + +/* "cmd" can now be passed to system(). */ +.Ed +.Sh SEE ALSO +.Xr sh 1 , +.Xr popen 3 , +.Xr system 3 +.Sh BUGS +This implementation does not currently handle strings containing multibyte +characters properly. +To address this issue, +.Pa /bin/sh +.Po +the shell used by +.Fn system +and +.Fn popen +.Pc +must first be fixed to handle multibyte characters. +When that has been done, +these functions can have multibyte character support enabled. diff --git a/static/netbsd/man3/sigblock.3 b/static/netbsd/man3/sigblock.3 new file mode 100644 index 00000000..86c8dff0 --- /dev/null +++ b/static/netbsd/man3/sigblock.3 @@ -0,0 +1,119 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sigblock.2 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: sigblock.3,v 1.17 2003/08/07 16:42:40 agc Exp $ +.\" +.Dd August 10, 2002 +.Dt SIGBLOCK 3 +.Os +.Sh NAME +.Nm sigblock +.Nd block signals +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigblock "int mask" +.Ft int +.Fn sigmask signum +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by: +.Xr sigprocmask 2 . +.Ef +.Pp +.Fn sigblock +adds the signals specified in +.Fa mask +to the set of signals currently +being blocked from delivery. +Signals are blocked if the +corresponding bit in +.Fa mask +is a 1; the macro +.Fn sigmask +is provided to construct the mask for a given +.Fa signum . +.Pp +It is not possible to block +.Dv SIGKILL +or +.Dv SIGSTOP ; +this restriction is silently +imposed by the system. +.Sh RETURN VALUES +The previous set of masked signals is returned. +.Sh EXAMPLES +The following example using +.Fn sigblock : +.Bd -literal -offset indent +int omask; + +omask = sigblock(sigmask(SIGINT) | sigmask(SIGHUP)); +.Ed +.Pp +Becomes: +.Bd -literal -offset indent +sigset_t set, oset; + +sigemptyset(&set); +sigaddset(&set, SIGINT); +sigaddset(&set, SIGHUP); +sigprocmask(SIG_BLOCK, &set, &oset); +.Ed +.Pp +Another use of +.Fn sigblock +is to get the current set of masked signals without changing what +is actually blocked. +Instead of: +.Bd -literal -offset indent +int set; + +set = sigblock(0); +.Ed +.Pp +Use the following: +.Bd -literal -offset indent +sigset_t set; + +sigprocmask(SIG_BLOCK, NULL, &set); +.Ed +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsetmask 3 , +.Xr sigsetops 3 +.Sh HISTORY +The +.Fn sigblock +function call appeared in +.Bx 4.2 +and has been deprecated. diff --git a/static/netbsd/man3/sighold.3 b/static/netbsd/man3/sighold.3 new file mode 100644 index 00000000..b29e46bf --- /dev/null +++ b/static/netbsd/man3/sighold.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: sighold.3,v 1.5 2010/04/30 04:39:16 jruoho Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2010 +.Dt SIGHOLD 3 +.Os +.Sh NAME +.Nm sighold +.Nd manipulate current signal mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sighold "int sig" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigprocmask 2 . +.Ef +.Pp +The +.Fn sighold +function adds the signal +.Fa sig +to the calling process' signal mask. +.Sh RETURN VALUES +If successful, the +.Fn sighold +function returns 0. +Otherwise \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sighold +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa sig +is not a valid signal number. +.El +.Sh SEE ALSO +.Xr sigprocmask 2 , +.Xr sigrelse 3 +.Sh STANDARDS +The +.Fn sighold +function conforms to +.St -p1003.1-2001 . +It was however marked as obsolete in the +.St -p1003.1-2008 +revision of the standard. diff --git a/static/netbsd/man3/sigignore.3 b/static/netbsd/man3/sigignore.3 new file mode 100644 index 00000000..41ed44e8 --- /dev/null +++ b/static/netbsd/man3/sigignore.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: sigignore.3,v 1.6 2010/04/30 06:48:20 wiz Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2010 +.Dt SIGIGNORE 3 +.Os +.Sh NAME +.Nm sigignore +.Nd manipulate signal dispositions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigignore "int sig" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigaction 2 . +.Ef +.Pp +The +.Fn sigignore +function sets the disposition of the signal +.Fa sig +to +.Dv SIG_IGN . +.Sh RETURN VALUES +If successful, the +.Fn sigignore +function returns 0. +Otherwise \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sigignore +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa sig +is not a valid signal number; +or an attempt is made to ignore a signal that cannot be ignored, +such as +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr sigaction 2 +.Sh STANDARDS +The +.Fn sigignore +function conforms to +.St -p1003.1-2001 . +It was however marked as obsolete in the +.St -p1003.1-2008 +revision of the standard. diff --git a/static/netbsd/man3/siginterrupt.3 b/static/netbsd/man3/siginterrupt.3 new file mode 100644 index 00000000..ce7ce627 --- /dev/null +++ b/static/netbsd/man3/siginterrupt.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: siginterrupt.3,v 1.12 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)siginterrupt.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt SIGINTERRUPT 3 +.Os +.Sh NAME +.Nm siginterrupt +.Nd allow signals to interrupt system calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn siginterrupt "int sig" "int flag" +.Sh DESCRIPTION +The +.Fn siginterrupt +function +is used to change the system call restart +behavior when a system call is interrupted by the specified signal. +If the flag is false (0), then system calls will be restarted if +they are interrupted by the specified signal +and no data has been transferred yet. +System call restart is the default behavior on +.Bx 4.2 . +.Pp +If the flag is true (1), +then restarting of system calls is disabled. +If a system call is interrupted by the specified signal +and no data has been transferred, +the system call will return \-1 with the global variable +.Va errno +set to +.Er EINTR . +Interrupted system calls that have started transferring +data will return the amount of data actually transferred. +System call interrupt is the signal behavior found on +.Bx 4.1 +and +.At V +systems. +.Pp +Note that the new +.Bx 4.2 +signal handling semantics are not +altered in any other way. +Most notably, signal handlers always remain installed until +explicitly changed by a subsequent +.Xr sigaction 2 +call, and the signal mask operates as documented in +.Xr sigaction 2 . +Programs may switch between restartable and interruptible +system call operation as often as desired in the execution of a program. +.Pp +Issuing a +.Fn siginterrupt 3 +call during the execution of a signal handler will cause +the new action to take place on the next signal to be caught. +.Sh NOTES +This library routine uses an extension of the +.Xr sigaction 2 +system call that is not available in +.Bx 4.2 , +hence it should not be used if backward compatibility is needed. +.Sh RETURN VALUES +A 0 value indicates that the call succeeded. +A \-1 value indicates that an invalid signal number has been supplied. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 +.Sh HISTORY +The +.Fn siginterrupt +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/signal.3 b/static/netbsd/man3/signal.3 new file mode 100644 index 00000000..ea3b6c4f --- /dev/null +++ b/static/netbsd/man3/signal.3 @@ -0,0 +1,204 @@ +.\" $NetBSD: signal.3,v 1.31 2025/07/25 23:08:20 uwe Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)signal.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd June 5, 2016 +.Dt SIGNAL 3 +.Os +.Sh NAME +.Nm signal +.Nd simplified software signal facilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.\" The following is Quite Ugly, but syntactically correct. Don't try to +.\" fix it. +.Ft void \*(lp* +.Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint" +.Sh DESCRIPTION +This +.Fn signal +facility +is a simplified interface to the more general +.Xr sigaction 2 +facility. +.Pp +Signals allow the manipulation of a process from outside its +domain as well as allowing the process to manipulate itself or +copies of itself (children). +There are two general types of signals: +those that cause termination of a process and those that do not. +Signals which cause termination of a program might result from +an irrecoverable error or might be the result of a user at a terminal +typing the `interrupt' character. +Signals are used when a process is stopped because it wishes to access +its control terminal while in the background (see +.Xr tty 4 ) . +Signals are optionally generated +when a process resumes after being stopped, +when the status of child processes changes, +or when input is ready at the control terminal. +Most signals result in the termination of the process receiving them +if no action +is taken; some signals instead cause the process receiving them +to be stopped, or are simply discarded if the process has not +requested otherwise. +Except for the +.Dv SIGKILL +and +.Dv SIGSTOP +signals, the +.Fn signal +function allows for a signal to be caught, to be ignored, or to generate +an interrupt. +See +.Xr signal 7 +for comprehensive list of supported signals. +.Pp +The +.Fa func +procedure allows a user to choose the action upon receipt of a signal. +To set the default action of the signal to occur as listed above, +.Fa func +should be +.Dv SIG_DFL . +A +.Dv SIG_DFL +resets the default action. +To ignore the signal +.Fa func +should be +.Dv SIG_IGN . +This will cause subsequent instances of the signal to be ignored +and pending instances to be discarded. +If +.Dv SIG_IGN +is not used, +further occurrences of the signal are +automatically blocked and +.Fa func +is called. +.Pp +The handled signal is unblocked when the +function returns and +the process continues from where it left off when the signal occurred. +The handler +.Fa func +remains installed after a signal has been delivered. +.Pp +For some system calls, if a signal is caught while the call is +executing and the call is prematurely terminated, +the call is automatically restarted. +(The handler is installed using the +.Dv SA_RESTART +flag with +.Xr sigaction 2 ) . +The affected system calls include +.Xr read 2 , +.Xr write 2 , +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr sendmsg 2 +and +.Xr recvmsg 2 +on a communications channel or a low speed device +and during a +.Xr ioctl 2 +or +.Xr wait 2 . +However, calls that have already committed are not restarted, +but instead return a partial success (for example, a short read count). +.Pp +When a process which has installed signal handlers forks, +the child process inherits the signals. +All caught signals may be reset to their default action by a call +to the +.Xr execve 2 +function; +ignored signals remain ignored. +.Pp +Only functions that are async-signal-safe can safely be used in signal +handlers; see +.Xr sigaction 2 +for a complete list. +.Sh RETURN VALUES +The previous action is returned on a successful call. +Otherwise, +.Dv SIG_ERR +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn signal +will fail and no action will take place if one of the following occur: +.Bl -tag -width Er +.It Bq Er EINVAL +Specified +.Em sig +is not a valid signal number; +or an attempt is made to ignore or supply a handler for +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr kill 2 , +.Xr ptrace 2 , +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr bsd_signal 3 , +.Xr psignal 3 , +.Xr setjmp 3 , +.Xr strsignal 3 , +.Xr tty 4 , +.Xr signal 7 +.Sh HISTORY +The +.Fn signal +facility first appeared in +.At v4 . +It used to be a system call that implemented a different semantics, +.Dq old signals , +in which a signal was reset to +.Dv SIG_DFL +after being caught. +.Pp +This +.Dq new signals +facility appeared in +.Bx 4.0 +as jobs library and became the default +.Xr signal 3 +in +.Bx 4.2 . diff --git a/static/netbsd/man3/signalname.3 b/static/netbsd/man3/signalname.3 new file mode 100644 index 00000000..96996c05 --- /dev/null +++ b/static/netbsd/man3/signalname.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: signalname.3,v 1.3 2020/08/20 22:56:56 kre Exp $ +.\" +.\" Available to all and sundry, without restriction on use, or other +.\" limitations, and without fee. Also without any warranty of fitness +.\" for any purpose whatever. +.\" +.\" Licensed for any use, including redistribution in source +.\" and binary forms, with or without modifications, subject +.\" the following agreement: +.\" +.\" Licensee agrees to indemnify licensor, and distributor, for +.\" the full amount of any any claim made by the licensee against +.\" the licensor or distributor, for any action that results from +.\" any use or redistribution of this software, plus any costs +.\" incurred by licensor or distributor resulting from that claim. +.\" +.\" This licence must be retained with the software. +.\" +.Dd April 28, 2017 +.Dt SIGNALNAME 3 +.Os +.Sh NAME +.Nm signalname , +.Nm signalnumber , +.Nm signalnext +.Nd convert between signal numbers and names +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft const char * +.Fn signalname "int sig" +.Ft int +.Fn signalnumber "const char *name" +.Ft int +.Fn signalnext "int sig" +.Sh DESCRIPTION +The +.Fn signalname +function takes a signal number +.Fa sig , +and returns the name of that signal. +The name returned is locale independent, +and can be the string representation of one of the +signal names from +.In signal.h +such as +.Dv SIGHUP , +.Dv SIGSTOP , +.Dv SIGKILL , +or some similar name, +but does not contain the leading +.Dq Dv SIG +prefix. +.Pp +The return value of +.Fn signalname +is +.Dv NULL +if +.Fa sig +does not represent a valid signal number, +or if the signal number given has no name. +.Pp +The +.Fn signalnumber +function converts the signal name +.Fa name +to the number corresponding to that signal. +The +.Fa name +is handled in a case-insensitive manner. +Any leading +.Dq Dv SIG +prefix in +.Fa name +is ignored. +.Pp +This implementation also accepts +.Dv rtmax Ns \&[\-n] +and +.Dv rtmin Ns \&[+n] +.Po +where the optional +.Ar n +is a decimal integer between 0 and SIGRTMAX\-SIGRTMIN +.Pc +to refer to the real time signals. +.Pp +The +.Fn signalnumber +function returns the signal number, +or zero (0) if the name given does not represent a valid signal. +.Pp +The +.Fn signalnext +function takes a signal number, and returns the number of the +next available bigger signal number. +When no higher signal numbers remain, it returns zero (0). +The parameter +.Fa sig +can be given as zero (0), to obtain the smallest implemented +signal number. +.Pp +The +.Fn signalnext +function returns minus one (\-1) on error, +that is, if the given signal +.Fa sig +is neither a valid signal number nor zero. +It returns zero when the input signal number, +.Fa sig , +is the biggest available signal number. +Otherwise it returns the signal number of an implemented +signal that is larger than +.Fa sig +and such that there are no implemented signals with values +between +.Fa sig +and the value returned. +.Pp +The +.Fn signalnext +function can also be used to determine if a non-zero signal +number is valid or not (0 is always invalid, but cannot be +detected as such this way.) +Given the non-zero signal number to check as +.Fa sig , +if +.Fn signalnext +returns anything other than minus one (\-1) +then +.Fa sig +represents a valid signal number. +If the return value is \-1 then +.Fa sig +is invalid. +.Sh SEE ALSO +.Xr kill 1 , +.Xr intro 2 , +.Xr psignal 3 , +.Xr strsignal 3 +.Sh HISTORY +The +.Fn signalname , +.Fn signalnext , +and +.Fn signalnumber +functions first appeared in +.Nx 8.0 . diff --git a/static/netbsd/man3/signbit.3 b/static/netbsd/man3/signbit.3 new file mode 100644 index 00000000..71e3eb59 --- /dev/null +++ b/static/netbsd/man3/signbit.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: signbit.3,v 1.3 2008/04/30 13:10:50 martin Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 29, 2003 +.Dt SIGNBIT 3 +.Os +.Sh NAME +.Nm signbit +.Nd test sign +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In math.h +.Ft int +.Fn signbit "real-floating x" +.Sh DESCRIPTION +The +.Fn signbit +macro determines whether the sign of its argument value +.Fa x +is negative. +An argument represented in a format wider than its semantic type is +converted to its semantic type first. +The determination is then based on the type of the argument. +.Ss IEEE754 +The sign is determined for all values, including infinities, zeroes, +and NaNs +.Ss VAX +The sign is determined for finites, true zeros, and dirty zeroes; +for ROPs the sign is reported negative. +.Sh RETURN VALUES +The +.Fn signbit +macro returns a non-zero value if the sign of its value +.Fa x +is negative. +Otherwise 0 is returned. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr fpclassify 3 , +.Xr isfinite 3 , +.Xr isnormal 3 , +.Xr math 3 +.Sh STANDARDS +The +.Fn signbit +macro conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/sigpause.3 b/static/netbsd/man3/sigpause.3 new file mode 100644 index 00000000..26e9275b --- /dev/null +++ b/static/netbsd/man3/sigpause.3 @@ -0,0 +1,75 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sigpause.2 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: sigpause.3,v 1.16 2022/12/04 11:25:08 uwe Exp $ +.\" +.Dd June 2, 1993 +.Dt SIGPAUSE 3 +.Os +.Sh NAME +.Nm sigpause +.Nd atomically release blocked signals and wait for interrupt +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigpause "int sigmask" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigsuspend 2 . +.Ef +.Pp +.Fn sigpause +assigns +.Fa sigmask +to the set of masked signals +and then waits for a signal to arrive; +on return the set of masked signals is restored. +.Fa sigmask +is usually 0 to indicate that no +signals are to be blocked. +.Fn sigpause +always terminates by being interrupted, returning -1 with +.Va errno +set to +.Er EINTR . +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigblock 3 , +.Xr sigvec 3 +.Sh HISTORY +The +.Fn sigpause +function call appeared in +.Bx 4.2 +and has been deprecated. diff --git a/static/netbsd/man3/sigrelse.3 b/static/netbsd/man3/sigrelse.3 new file mode 100644 index 00000000..f70cc49e --- /dev/null +++ b/static/netbsd/man3/sigrelse.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: sigrelse.3,v 1.4 2010/04/30 04:39:16 jruoho Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2010 +.Dt SIGRELSE 3 +.Os +.Sh NAME +.Nm sigrelse +.Nd manipulate current signal mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigrelse "int sig" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigprocmask 2 . +.Ef +.Pp +The +.Fn sigrelse +function removes the signal +.Fa sig +from the calling process' signal mask. +.Sh RETURN VALUES +If successful, the +.Fn sigrelse +function returns 0. +Otherwise \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sigrelse +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa sig +is not a valid signal number. +.El +.Sh SEE ALSO +.Xr sigprocmask 2 , +.Xr sighold 3 +.Sh STANDARDS +The +.Fn sigrelse +function conforms to +.St -p1003.1-2001 . +It was however marked as obsolete in the +.St -p1003.1-2008 +revision of the standard. diff --git a/static/netbsd/man3/sigset.3 b/static/netbsd/man3/sigset.3 new file mode 100644 index 00000000..c5da2818 --- /dev/null +++ b/static/netbsd/man3/sigset.3 @@ -0,0 +1,125 @@ +.\" $NetBSD: sigset.3,v 1.8 2010/04/30 06:48:20 wiz Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2010 +.Dt SIGSET 3 +.Os +.Sh NAME +.Nm sigset +.Nd manipulate signal dispositions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.\" The following is Quite Ugly, but syntactically correct. Don't try to +.\" fix it. +.Ft void \*(lp* +.Fn sigset "int sig" "void \*(lp*disp\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigaction 2 +and +.Xr sigprocmask 2 . +.Ef +.Pp +The +.Fn sigset +function manipulates the disposition of the signal +.Fa sig . +The new disposition is given in +.Fa disp . +.Pp +If +.Fa disp +is one of +.Dv SIG_DFL , +.Dv SIG_IGN , +or the address of a handler function, +the disposition of +.Fa sig +is changed accordingly, and +.Fa sig +is removed from the process' signal mask. +Also, if +.Fa disp +is the address of a handler function, +.Fa sig +will be added to the process' signal mask during execution of the handler. +.Pp +If +.Fa disp +is equal to +.Dv SIG_HOLD , +.Fa sig +is added to the calling process' signal mask and the disposition of +.Fa sig +remains unchanged. +.Sh RETURN VALUES +If successful, the +.Fn sigset +function returns +.Dv SIG_HOLD +if +.Fa sig +had been blocked, +and the previous disposition of +.Fa sig +if it had not been blocked. +Otherwise +.Dv SIG_ERR +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sigset +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa sig +is not a valid signal number; +or an attempt is made to ignore a signal that cannot be ignored, +such as +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 +.Sh STANDARDS +The +.Fn sigset +function conforms to +.St -p1003.1-2001 . +It was however marked as obsolete in the +.St -p1003.1-2008 +revision of the standard. diff --git a/static/netbsd/man3/sigsetmask.3 b/static/netbsd/man3/sigsetmask.3 new file mode 100644 index 00000000..77959281 --- /dev/null +++ b/static/netbsd/man3/sigsetmask.3 @@ -0,0 +1,140 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sigsetmask.2 8.1 (Berkeley) 6/2/93 +.\" $NetBSD: sigsetmask.3,v 1.19 2013/05/06 13:29:12 wiz Exp $ +.\" +.Dd August 10, 2002 +.Dt SIGSETMASK 3 +.Os +.Sh NAME +.Nm sigsetmask +.Nd set current signal mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigsetmask "int mask" +.Fn sigmask signum +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by: +.Ef +.Xr sigprocmask 2 . +.Pp +.Fn sigsetmask +sets the current signal mask. +Signals are blocked from delivery if the +corresponding bit in +.Fa mask +is a 1; the macro +.Fn sigmask +is provided to construct the mask for a given +.Fa signum . +.Pp +The system +quietly disallows +.Dv SIGKILL +or +.Dv SIGSTOP +to be blocked. +.Sh RETURN VALUES +The previous set of masked signals is returned. +.Sh EXAMPLES +The following example using +.Fn sigsetmask : +.Bd -literal -offset indent +int omask; + +omask = sigblock(sigmask(SIGINT) | sigmask(SIGHUP)); + +\&... + +sigsetmask(omask & ~(sigmask(SIGINT) | sigmask(SIGHUP))); +.Ed +.Pp +Could be converted literally to: +.Bd -literal -offset indent +sigset_t set, oset; + +sigemptyset(&set); +sigaddset(&set, SIGINT); +sigaddset(&set, SIGHUP); +sigprocmask(SIG_BLOCK, &set, &oset); + +\&... + +sigdelset(&oset, SIGINT); +sigdelset(&oset, SIGHUP); +sigprocmask(SIG_SETMASK, &oset, NULL); +.Ed +.Pp +Another, clearer, alternative is: +.Bd -literal -offset indent +sigset_t set; + +sigemptyset(&set); +sigaddset(&set, SIGINT); +sigaddset(&set, SIGHUP); +sigprocmask(SIG_BLOCK, &set, NULL); + +\&... + +sigprocmask(SIG_UNBLOCK, &set, NULL); +.Ed +.Pp +To completely clear the signal mask using +.Fn sigsetmask +one can do: +.Bd -literal -offset indent +(void) sigsetmask(0); +.Ed +.Pp +Which can be expressed via +.Xr sigprocmask 2 +as: +.Bd -literal -offset indent +sigset_t eset; + +sigemptyset(&eset); +(void) sigprocmask(SIG_SETMASK, &eset, NULL); +.Ed +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigblock 3 , +.Xr sigsetops 3 , +.Xr sigvec 3 +.Sh HISTORY +The +.Fn sigsetmask +function call appeared in +.Bx 4.2 +and has been deprecated. diff --git a/static/netbsd/man3/sigsetops.3 b/static/netbsd/man3/sigsetops.3 new file mode 100644 index 00000000..e97e130d --- /dev/null +++ b/static/netbsd/man3/sigsetops.3 @@ -0,0 +1,124 @@ +.\" $NetBSD: sigsetops.3,v 1.14 2003/08/07 16:42:57 agc Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigsetops.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt SIGSETOPS 3 +.Os +.Sh NAME +.Nm sigemptyset , +.Nm sigfillset , +.Nm sigaddset , +.Nm sigdelset , +.Nm sigismember +.Nd manipulate signal sets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigemptyset "sigset_t *set" +.Ft int +.Fn sigfillset "sigset_t *set" +.Ft int +.Fn sigaddset "sigset_t *set" "int signo" +.Ft int +.Fn sigdelset "sigset_t *set" "int signo" +.Ft int +.Fn sigismember "sigset_t *set" "int signo" +.Sh DESCRIPTION +These functions manipulate signal sets stored in a +.Fa sigset_t . +Either +.Fn sigemptyset +or +.Fn sigfillset +must be called for every object of type +.Fa sigset_t +before any other use of the object. +.Pp +The +.Fn sigemptyset +function initializes a signal set to be empty. +.Pp +The +.Fn sigfillset +function initializes a signal set to contain all signals. +.Pp +The +.Fn sigaddset +function adds the specified signal +.Fa signo +to the signal set. +.Pp +The +.Fn sigdelset +function deletes the specified signal +.Fa signo +from the signal set. +.Pp +The +.Fn sigismember +function returns whether a specified signal +.Fa signo +is contained in the signal set. +.Pp +.Fn sigemptyset +and +.Fn sigfillset +are provided as macros, but actual functions are available +if their names are undefined (with #undef +.Em name ) . +.Sh RETURN VALUES +The +.Fn sigismember +function returns 1 +if the signal is a member of the set, +a 0 otherwise. +The other functions return 0 upon success. +A \-1 return value +indicates an error occurred and the global variable +.Va errno +is set to indicate the reason. +.Sh ERRORS +These functions could fail if one of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa signo +has an invalid value. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigsuspend 2 , +.Xr signal 7 +.Sh STANDARDS +These functions conform to +.St -p1003.1-90 . diff --git a/static/netbsd/man3/sigvec.3 b/static/netbsd/man3/sigvec.3 new file mode 100644 index 00000000..3c9cda2c --- /dev/null +++ b/static/netbsd/man3/sigvec.3 @@ -0,0 +1,313 @@ +.\" $NetBSD: sigvec.3,v 1.27 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sigvec.2 8.2 (Berkeley) 4/19/94 +.\" +.Dd December 3, 2005 +.Dt SIGVEC 3 +.Os +.Sh NAME +.Nm sigvec +.Nd software signal facilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +struct sigvec { + void (*sv_handler)(); + int sv_mask; + int sv_flags; +}; +.Ed +.Ft int +.Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec" +.Sh DESCRIPTION +.Bf -symbolic +This interface is made obsolete by +.Xr sigaction 2 . +The structure, flags, and function declaration have been removed from +the header files but the function is kept in the c library for binary +compatibility. +.Ef +.Pp +The system defines a set of signals that may be delivered to a process. +Signal delivery resembles the occurrence of a hardware interrupt: +the signal is blocked from further occurrence, the current process +context is saved, and a new one is built. +A process may specify a +.Em handler +to which a signal is delivered, or specify that a signal is to be +.Em ignored . +A process may also specify that a default action is to be taken +by the system when a signal occurs. +A signal may also be +.Em blocked , +in which case its delivery is postponed until it is +.Em unblocked . +The action to be taken on delivery is determined at the time +of delivery. +Normally, signal handlers execute on the current stack +of the process. +This may be changed, on a per-handler basis, so that signals are +taken on a special +.Em "signal stack" . +.Pp +Signal routines execute with the signal that caused their +invocation +.Em blocked , +but other signals may yet occur. +A global +.Em "signal mask" +defines the set of signals currently blocked from delivery +to a process. +The signal mask for a process is initialized from that of its parent +(normally 0). +It may be changed with a +.Xr sigblock 3 +or +.Xr sigsetmask 3 +call, or when a signal is delivered to the process. +.Pp +When a signal +condition arises for a process, the signal is added to a set of +signals pending for the process. +If the signal is not currently +.Em blocked +by the process then it is delivered to the process. +When a caught signal +is delivered, the current state of the process is saved, +a new signal mask is calculated (as described below), +and the signal handler is invoked. +The call to the handler is arranged so that if the signal handling +routine returns normally the process will resume execution in the +context from before the signal's delivery. +If the process wishes to resume in a different context, then it +must arrange to restore the previous context itself. +.Pp +When a signal is delivered to a process a new signal mask is +installed for the duration of the process' signal handler +(or until a +.Xr sigblock 3 +or +.Xr sigsetmask 3 +call is made). +This mask is formed by taking the union of the current signal mask, +the signal to be delivered, and +the signal mask associated with the handler to be invoked. +.Pp +.Fn sigvec +assigns a handler for a specific signal. +If +.Fa vec +is non-zero, it +specifies an action +.Pf ( Dv SIG_DFL , +.Dv SIG_IGN , +or a handler routine) and mask +to be used when delivering the specified signal. +Further, if the +.Dv SV_ONSTACK +bit is set in +.Fa sv_flags , +the system will deliver the signal to the process on a +.Em "signal stack" , +specified with +.Xr sigaltstack 2 . +If +.Fa ovec +is non-zero, the previous handling information for the signal +is returned to the user. +.Pp +Once a signal handler is installed, it remains installed +until another +.Fn sigvec +call is made, or an +.Xr execve 2 +is performed. +A signal-specific default action may be reset by +setting +.Fa sv_handler +to +.Dv SIG_DFL . +The defaults are process termination, possibly with core dump; +no action; stopping the process; or continuing the process. +See the signal list below for each signal's default action. +If +.Fa sv_handler +is set to +.Dv SIG_DFL , +the default action for the signal is to discard the signal, +and if a signal is pending, +the pending signal is discarded even if the signal is masked. +If +.Fa sv_handler +is set to +.Dv SIG_IGN , +current and pending instances +of the signal are ignored and discarded. +.Pp +Options may be specified by setting +.Em sv_flags . +If the +.Dv SV_ONSTACK +bit is set in +.Fa sv_flags , +the system will deliver the signal to the process on a +.Em "signal stack" , +specified with +.Xr sigstack 2 . +.Pp +If a signal is caught during the system calls listed below, +the call may be restarted, +the call may return with a data transfer shorter than requested, +or the call may be forced to terminate +with the error +.Er EINTR . +Interrupting of pending calls is requested +by setting the +.Dv SV_INTERRUPT +bit in +.Ar sv_flags . +The affected system calls include +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr sendmsg 2 +and +.Xr recvmsg 2 +on a communications channel or a slow device (such as a terminal, +but not a regular file) +and during a +.Xr wait 2 +or +.Xr ioctl 2 . +However, calls that have already committed are not restarted, +but instead return a partial success (for example, a short read count). +.Pp +After a +.Xr fork 2 +or +.Xr vfork 2 +all signals, the signal mask, the signal stack, +and the interrupt/restart flags are inherited by the child. +.Pp +The +.Xr execve 2 +system call reinstates the default action for all signals which +were caught and resets all signals to be caught on the user stack. +Ignored signals remain ignored; +the signal mask remains the same; +signals that interrupt pending system calls continue to do so. +.Pp +See +.Xr signal 7 +for comprehensive list of supported signals. +.Sh NOTES +The mask specified in +.Fa vec +is not allowed to block +.Dv SIGKILL +or +.Dv SIGSTOP . +This is enforced silently by the system. +.Pp +The +.Dv SV_INTERRUPT +flag is not available in +.Bx 4.2 , +hence it should not be used if backward compatibility is needed. +.Sh RETURN VALUES +A 0 value indicated that the call succeeded. +A \-1 return value indicates an error occurred and +.Va errno +is set to indicated the reason. +.Sh EXAMPLES +The handler routine can be declared: +.Bd -literal -offset indent +void +handler(sig, code, scp) + int sig, code; + struct sigcontext *scp; +.Ed +.Pp +Here +.Fa sig +is the signal number, into which the hardware faults and traps are +mapped as defined below. +.Fa code +is a parameter that is either a constant +or the code provided by the hardware. +.Fa scp +is a pointer to the +.Fa sigcontext +structure (defined in +.In signal.h ) , +used to restore the context from before the signal. +.Sh ERRORS +.Fn sigvec +will fail and no new signal handler will be installed if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa vec +or +.Fa ovec +points to memory that is not a valid part of the process +address space. +.It Bq Er EINVAL +.Fa sig +is not a valid signal number. +.It Bq Er EINVAL +An attempt is made to ignore or supply a handler for +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr kill 2 , +.Xr ptrace 2 , +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr sigprocmask 2 , +.Xr sigstack 2 , +.Xr sigsuspend 2 , +.Xr setjmp 3 , +.Xr sigblock 3 , +.Xr siginterrupt 3 , +.Xr signal 3 , +.Xr sigpause 3 , +.Xr sigsetmask 3 , +.Xr sigsetops 3 , +.Xr tty 4 , +.Xr signal 7 diff --git a/static/netbsd/man3/sin.3 b/static/netbsd/man3/sin.3 new file mode 100644 index 00000000..d71e3014 --- /dev/null +++ b/static/netbsd/man3/sin.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sin.3 6.7 (Berkeley) 4/19/91 +.\" $NetBSD: sin.3,v 1.16 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd January 24, 2024 +.Dt SIN 3 +.Os +.Sh NAME +.Nm sin , +.Nm sinf , +.Nm sinl +.Nd sine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn sin "double x" +.Ft float +.Fn sinf "float x" +.Ft long double +.Fn sinl "long double x" +.Sh DESCRIPTION +The +.Fn sin +function computes the sine of +.Fa x +(measured in radians). +A large magnitude argument may yield a result with little +or no significance. +.Sh RETURN VALUES +The +.Fn sin +function returns the sine value. +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sinh 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn sin +function conforms to +.St -ansiC . +.Sh HISTORY +A +.Fn sin +function appeared in +.At v1 . diff --git a/static/netbsd/man3/sincos.3 b/static/netbsd/man3/sincos.3 new file mode 100644 index 00000000..7771fbc4 --- /dev/null +++ b/static/netbsd/man3/sincos.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 2011 Steven G. Kargl. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/msun/man/sincos.3 366583 2020-10-09 19:12:44Z gbe $ +.\" $NetBSD: sincos.3,v 1.2 2023/06/11 15:28:21 christos Exp $ +.\" +.Dd June 11, 2023 +.Dt SINCOS 3 +.Os +.Sh NAME +.Nm sincos , +.Nm sincosf , +.Nm sincosl +.Nd sine and cosine functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft void +.Fn sincos "double x" "double *s" "double *c" +.Ft void +.Fn sincosf "float x" "float *s" "float *c" +.Ft void +.Fn sincosl "long double x" "long double *s" "long double *c" +.Sh DESCRIPTION +The +.Fn sincos , +.Fn sincosf , +and +.Fn sincosl +functions compute the sine and cosine of +.Fa x . +Using these functions allows argument reduction to occur only +once instead of twice with individual invocations of +.Fn sin +and +.Fn cos . +Like +.Fn sin +and +.Fn cos , +a large magnitude argument may yield a result with little +or no significance. +.Sh RETURN VALUES +Upon returning from +.Fn sincos , +.Fn sincosf , +and +.Fn sincosl , +the memory pointed to by +.Ar "*s" +and +.Ar "*c" +are assigned the values of sine and cosine, respectively. +.Sh SEE ALSO +.Xr cos 3 , +.Xr sin 3 , +.Sh HISTORY +These functions were added to +.Fx 11.2 +and +.Nx 10.0 +to aid in writing various complex function contained in +.St -isoC-99 . + diff --git a/static/netbsd/man3/sinh.3 b/static/netbsd/man3/sinh.3 new file mode 100644 index 00000000..a6dc470e --- /dev/null +++ b/static/netbsd/man3/sinh.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sinh.3 6.6 (Berkeley) 4/19/91 +.\" $NetBSD: sinh.3,v 1.15 2024/01/26 19:27:30 nros Exp $ +.Dd April 19, 1991 +.Dt SINH 3 +.Os +.Sh NAME +.Nm sinh , +.Nm sinhf , +.Nm sinhl +.Nd hyperbolic sine function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn sinh "double x" +.Ft float +.Fn sinhf "float x" +.Ft long double +.Fn sinh "long double x" +.Sh DESCRIPTION +The +.Fn sinh +function computes the hyperbolic sine of +.Fa x . +.Sh RETURN VALUES +The +.Fn sinh +function returns the hyperbolic sine value unless +the magnitude of +.Fa x +is too large; in this event, the global variable +.Va errno +is set to +.Er ERANGE . +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr tan 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn sinh +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/skey.3 b/static/netbsd/man3/skey.3 new file mode 100644 index 00000000..0e68776b --- /dev/null +++ b/static/netbsd/man3/skey.3 @@ -0,0 +1,257 @@ +.\" $NetBSD: skey.3,v 1.11 2017/07/03 21:32:51 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 10, 2001 +.Dt SKEY 3 +.Os +.Sh NAME +.Nm skey , +.Nm skeychallenge , +.Nm skeylookup , +.Nm skeygetnext , +.Nm skeyverify , +.Nm skeyzero , +.Nm getskeyprompt , +.Nm skey_set_algorithm , +.Nm skey_get_algorithm , +.Nm skey_haskey , +.Nm skey_keyinfo , +.Nm skey_passcheck , +.Nm skey_authenticate +.Nd one-time password (OTP) library +.Sh LIBRARY +S/key One-Time Password Library (libskey, -lskey) +.Sh SYNOPSIS +.In skey.h +.Ft int +.Fn skeychallenge "struct skey *mp" "const char *name" "char *ss" \ +"size_t sslen" +.Ft int +.Fn skeylookup "struct skey *mp" "const char *name" +.Ft int +.Fn skeygetnext "struct skey *mp" +.Ft int +.Fn skeyverify "struct skey *mp" "char *response" +.Ft int +.Fn skeyzero "struct skey *mp" "char *response" +.Ft int +.Fn getskeyprompt "struct skey *mp" "char *name" "char *prompt" +.Ft const char * +.Fn skey_set_algorithm "const char *new" +.Ft const char * +.Fn skey_get_algorithm "void" +.Ft int +.Fn skey_haskey "const char *username" +.Ft const char * +.Fn skey_keyinfo "const char *username" +.Ft int +.Fn skey_passcheck "const char *username" "char *passwd" +.Ft int +.Fn skey_authenticate "const char *username" +.Ft void +.Fn f "char *x" +.Ft int +.Fn keycrunch "char *result" "const char *seed" "const char *passwd" +.Ft void +.Fn rip "char *buf" +.Ft char * +.Fn readpass "char *buf" "int n" +.Ft char * +.Fn readskey "char *buf" "int n" +.Ft int +.Fn atob8 "char *out" "const char *in" +.Ft int +.Fn btoa8 "char *out" "const char *in" +.Ft int +.Fn htoi "int c" +.Ft const char * +.Fn skipspace "const char *cp" +.Ft void +.Fn backspace "char *buf" +.Ft void +.Fn sevenbit "char *buf" +.Ft char * +.Fn btoe "char *engout" "const char *c" +.Ft int +.Fn etob "char *out" "const char *e" +.Ft char * +.Fn put8 "char *out" "const char *s" +.Sh DESCRIPTION +The +.Nm +library provides routines for accessing +.Nx Ns 's +one-time password (OTP) authentication system. +.Pp +Most S/Key operations take a pointer to a +.Em struct skey , +which should be considered as an opaque identifier. +.Sh FUNCTIONS +The following high-level functions are available: +.Bl -tag -width compact +.It Fn skeychallenge "mp" "name" "ss" "sslen" +Return a S/Key challenge for user +.Fa name . +If successful, the caller's skey structure +.Fa mp +is filled and 0 is returned. +If unsuccessful (e.g. if name is unknown), +\-1 is returned. +.It Fn skeylookup "mp" "name" +Find an entry for user +.Fa name +in the one-time password database. +Returns 0 if the entry is found and 1 if the entry is not found. +If an error occurs accessing the database, \-1 is returned. +.It Fn skeygetnext "mp" +Get the next entry in the one-time password database. +Returns 0 on success and the entry is stored in +.Ar mp +and 1 if no more entries are available. +If an error occurs accessing the database, \-1 is returned. +.It Fn skeyverify "mp" "response" +Verify response +.Fa response +to a S/Key challenge. +Returns 0 if the verification is successful and 1 if the verification failed. +If an error occurs accessing the database, \-1 is returned. +.It Fn skeyzero "mp" "response" +Comment out user's entry in the S/Key database. +Returns 0 on success and the database is updated, +otherwise \-1 is returned and the database remains unchanged. +.It Fn getskeyprompt "mp" "name" "prompt" +Issue a S/Key challenge for user +.Ar name . +If successful, fill in the caller's skey structure +.Fa mp +and return 0. +If unsuccessful (e.g. if name is unknown) \-1 is returned. +.El +.Pp +The following lower-level functions are available: +.Bl -tag -width compact +.It Fn skey_set_algorithm "new" +Set hash algorithm type. +Valid values for +.Fa new +are "md4", "md5" and "sha1". +.It Fn skey_get_algorithm "void" +Get current hash type. +.It Fn skey_haskey "username" +Returns 0 if the user +.Fa username +exists and 1 if the user doesn't exist. +Returns \-1 on file error. +.It Fn skey_keyinfo "username" +Returns the current sequence number and seed for user +.Ar username . +.It Fn skey_passcheck "username" "passwd" +Checks to see if answer is the correct one to the current challenge. +.It Fn skey_authenticate "username" +Used when calling program will allow input of the user's response to +the challenge. +Returns zero on success or \-1 on failure. +.El +.Pp +The following miscellaneous functions are available: +.Bl -tag -width compact +.It Fn f "x" +One-way function to take 8 bytes pointed to by +.Fa x +and return 8 bytes in place. +.It Fn keycrunch "char *result" "const char *seed" "const char *passwd" +Crunch a key. +.It Fn rip "buf" +Strip trailing CR/LF characters from a line of text +.Fa buf . +.It Fn readpass "buf" "n" +Read in secret passwd (turns off echo). +.It Fn readskey "buf" "n" +Read in an s/key OTP (does not turn off echo). +.It Fn atob8 "out" "in" +Convert 8-byte hex-ascii string +.Fa in +to binary array +.Fa out . +Returns 0 on success, \-1 on error. +.It Fn btoa8 "out" "in" +Convert 8-byte binary array +.Fa in +to hex-ascii string +.Fa out . +Returns 0 on success, \-1 on error. +.It Fn htoi "int c" +Convert hex digit to binary integer. +.It Fn skipspace "cp" +Skip leading spaces from the string +.Fa cp . +.It Fn backspace "buf" +Remove backspaced over characters from the string +.Fa buf . +.It Fn sevenbit "buf" +Ensure line +.Fa buf +is all seven bits. +.It Fn btoe "engout" "c" +Encode 8 bytes in +.Ar c +as a string of English words. +Returns a pointer to a static buffer in +.Fa engout . +.It Fn etob "out" "e" +Convert English to binary. +Returns 0 if the word is not in the database, 1 if all good words and +parity is valid, \-1 if badly formed input (i.e. > 4 char word) +and -2 if words are valid but parity is wrong. +.It Fn put8 "out" "s" +Display 8 bytes +.Fa s +as a series of 16-bit hex digits. +.El +.Sh FILES +.Bl -tag -width /usr/lib/libskey_p.a -compact +.It Pa /usr/lib/libskey.a +static skey library +.It Pa /usr/lib/libskey.so +dynamic skey library +.It Pa /usr/lib/libskey_p.a +static skey library compiled for profiling +.El +.Sh SEE ALSO +.Xr skey 1 , +.Xr skeyaudit 1 , +.Xr skeyinfo 1 +.Sh BUGS +The +.Nm +library functions are not re-entrant or thread-safe. +.Pp +The +.Nm +library defines many poorly named functions which pollute the name space. diff --git a/static/netbsd/man3/sleep.3 b/static/netbsd/man3/sleep.3 new file mode 100644 index 00000000..9cf8e19a --- /dev/null +++ b/static/netbsd/man3/sleep.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: sleep.3,v 1.15 2003/08/07 16:42:57 agc Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt SLEEP 3 +.Os +.Sh NAME +.Nm sleep +.Nd suspend process execution for interval of seconds +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft unsigned int +.Fn sleep "unsigned int seconds" +.Sh DESCRIPTION +The +.Fn sleep +function suspends execution of the calling process until either the +number of seconds specified by +.Fa seconds +have elapsed or a signal is delivered to the calling process and its +action is to invoke a signal-catching function or to terminate the +process. +The suspension time may be longer than requested due to the +scheduling of other activity by the system. +.Sh RETURN VALUES +If the +.Fn sleep +function returns because the requested time has elapsed, the value +returned will be zero. +If the +.Fn sleep +function returns due to the delivery of a signal, the value returned +will be the unslept amount (the request time minus the time actually +slept) in seconds. +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr usleep 3 +.Sh STANDARDS +The +.Fn sleep +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +A +.Fn sleep +function appeared in +.At v7 . diff --git a/static/netbsd/man3/smp.3 b/static/netbsd/man3/smp.3 new file mode 100644 index 00000000..58feef94 --- /dev/null +++ b/static/netbsd/man3/smp.3 @@ -0,0 +1,23 @@ + * * * * + * * * * * * + * * * * * * * * + * * * * * * * * +* * * * * * * * +* * * * * * * * +* * * * * * * * +* * * * * * * * + * * * * * * * * + * * * * * * * * + * * * * * * + * * * * + + + + + + + + + + + diff --git a/static/netbsd/man3/snprintb.3 b/static/netbsd/man3/snprintb.3 new file mode 100644 index 00000000..4ec52615 --- /dev/null +++ b/static/netbsd/man3/snprintb.3 @@ -0,0 +1,488 @@ +.\" $NetBSD: snprintb.3,v 1.41 2026/03/14 14:25:46 rillig Exp $ +.\" +.\" Copyright (c) 1998, 2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 14, 2026 +.Dt SNPRINTB 3 +.Os +.Sh NAME +.Nm snprintb , +.Nm snprintb_m +.Nd bitmask output conversion +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn "snprintb" "char *buf" "size_t bufsize" "const char *fmt" "uint64_t val" +.Ft int +.Fn "snprintb_m" "char *buf" "size_t bufsize" "const char *fmt" "uint64_t val" \ +"size_t max" +.Sh DESCRIPTION +The +.Fn snprintb +function formats a bitmask into a mnemonic form suitable for printing. +.Pp +It formats the integer +.Fa val +into the buffer +.Fa buf , +of size +.Fa bufsize , +interpreting the bits within that integer as flags or groups of bits. +The buffer is always +.Tn NUL Ns -terminated. +If the buffer +.Fa buf +is too small to hold the formatted output, +.Fn snprintb +will fill as much as it can, and return the number of bytes +that it would have written if the buffer were long enough excluding the +terminating +.Tn NUL . +If +.Fa bufsize +is zero, nothing is written and +.Fa buf +may be a null pointer. +.Pp +The +.Fn snprintb_m +function accepts an additional +.Fa max +argument. +If this argument is zero, the +.Fn snprintb_m +function behaves exactly like the +.Fn snprintb +function. +If the +.Fa max +argument has a non-zero value, it represents the maximum length of a +formatted string. +If the formatted string would require more than +.Fa max +characters, the +.Fn snprintb_m +function returns multiple formatted strings in the output buffer +.Fa buf . +Each string is +.Tn NUL Ns -terminated , +and the last string is followed by an +additional +.Tn NUL +character +.Pq or, if you prefer, a zero-length string . +.Pp +The decoding directive in +.Fa fmt +describes how the bitfield is to be interpreted and displayed. +It follows two possible formats, referred to as +.Dq old +and +.Dq new . +The +.Dq old +format is limited to describing single bits in a 32-bit value, +the bit positions are 1-based. +The +.Dq new +format supports multi-bit fields and 64-bit values, +the bit positions are 0-based. +.Pp +If the first character of +.Fa fmt +is +.Pq in C escape-character format +.Ql \e177 +or +.Ql \ex7f , +the remainder of the +.Fa fmt +argument follows the +.Dq new +format. +.Pp +The next character +.Po the first for the +.Dq old +format +.Pc +specifies the numeral base in which to print the numbers in the output. +The possible values are +.Ql \e010 +or +.Ql \ex08 +for octal, +.Ql \e012 +or +.Ql \ex0a +for decimal, and +.Ql \e020 +or +.Ql \ex10 +for hexadecimal. +.Pp +The remaining characters in the +.Fa fmt +argument represent the formatting conversions, +according to the +.Dq old +or +.Dq new +format. +. +.Ss Old Format +.Pp +In the +.Dq old +format, each conversion specifies a bit position +and a description that is printed if the corresponding bit is set. +.Pp +The bit position is a 1-based single-byte binary value, +ranging from +.Ql \e001 +or +.Ql \ex01 +(1) for the least significant bit up to +.Ql \e040 +or +.Ql \ex20 +(32) for the most significant bit. +.Pp +The description is delimited by the next character whose value is 32 or less +.Po see +.Xr ascii 7 +.Pc , +or by the end of the format string itself. +. +.Ss New Format +.Pp +In the +.Dq new +format, +each conversion begins with a conversion type, +followed by type-specific parameters, each encoded as a single byte, +followed by a +.Tn NUL Ns -terminated description. +The bit positions are 0-based, +ranging from +.Ql \e000 +or +.Ql \ex00 +(0) for the least significant bit to +.Ql \e077 +or +.Ql \ex3f +(63) for the most significant bit. +. +.Bl -tag -width Cm +. +.It Cm b Ar bit Ar descr +Prints the description from +.Ar descr +if the bit at the position +.Ar bit +is set. +. +.It Cm f Ar lsb Ar width Ar descr +Prints the description from +.Ar descr , +a delimiting +.Sq \&= +and the numerical value of the multi-bit field +whose least significant bit is at +.Ar lsb +and that spans +.Ar width +bits. +To print individual values of the field, see the +.Sq Cm \&= , +.Sq Cm \&: +and +.Sq Cm \&* +conversions below. +. +.It Cm \&= Ar cmp Ar descr +Compares the field value from the previous +.Sq Cm f +.Pq or, in rare cases, Sq Cm F +conversion to the single-byte value +.Ar cmp , +ranging from +.Ql \e000 +or +.Ql \ex00 +(0) to +.Ql \e377 +or +.Ql \exff +(255). +If they are equal, prints +.Ql \&= +followed by the description from +.Ar descr . +This conversion may be repeated. +. +.It Cm F Ar lsb Ar width Op Ar descr +Describes a multi-bit field like +.Sq Cm f , +but just extracts the value for use with the +.Sq Cm \&: +.Pq or, in rare cases, Sq Cm \&= +and +.Sq Cm \&* +conversions below. +The description from +.Ar descr +is ignored, +it is only present for uniformity with the other conversions. +. +.It Cm \&: Ar cmp Ar descr +Compares the field value from the previous +.Sq Cm F +.Pq or, in rare cases, Sq Cm f +conversion to the single-byte value +.Ar cmp , +ranging from +.Ql \e000 +or +.Ql \ex00 +(0) to +.Ql \e377 +or +.Ql \exff +(255). +If they are equal, prints the description from +.Ar descr . +This conversion may be repeated. +. +.It Cm * Ar fmt +If none of the previous +.Sq Cm \&= +or +.Sq Cm \&: +conversions matched, prints the format string +.Ar fmt +via +.Xr snprintf 3 . +The format string +.Ar fmt +may contain a single +.Vt uintmax_t +conversion specification to print the field value that did not match. +.El +.Pp +The new format is terminated by an additional +.Tn NUL +character at the end, following that delimiting the last conversion. +This +.Tn NUL +is supplied by the compiler to terminate the string literal and +doesn't need to be written explicitly. +.Sh RETURN VALUES +The +.Fn snprintb +and +.Fn snprintb_m +functions return the number of bytes that they would have written to the buffer +if there was adequate space, excluding the final terminating NUL, or \-1 in +case an error occurred. +For +.Fn snprintb_m , +the NUL characters terminating each individual string are included in the +total number of bytes. +.Sh EXAMPLES +Two examples of the old formatting style: +.Bd -literal -offset indent +snprintb(buf, bufsize, "\e010\e002BITTWO\e001BITONE", 3) +\(rA "03<BITTWO,BITONE>" + +snprintb(buf, bufsize, + "\ex10" + "\ex10" "NOTBOOT" + "\ex0f" "FPP" + "\ex0e" "SDVMA" + "\ex0c" "VIDEO" + "\ex0b" "LORES" + "\ex0a" "FPA" + "\ex09" "DIAG" + "\ex07" "CACHE" + "\ex06" "IOCACHE" + "\ex05" "LOOPBACK" + "\ex04" "DBGCACHE", + 0xe860) +\(rA "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" +.Ed +.Pp +An example of the new formatting style: +.Bd -literal -offset indent +snprintb(buf, bufsize, + "\e177\e020" + "b\e000" "LSB\e0" + "b\e001" "BITONE\e0" + "f\e004\e004" "NIBBLE2\e0" + "f\e020\e004" "BURST\e0" + "=\ex04" "FOUR\e0" + "=\ex0f" "FIFTEEN\e0" + "b\e037" "MSB\e0", + 0x800f0701) +\(rA "0x800f0701<LSB,NIBBLE2=0,BURST=0xf=FIFTEEN,MSB>" +.Ed +.Pp +The same example using snprintb_m: +.Bd -literal -offset indent +snprintb_m(buf, bufsize, + "\e177\e020" + "b\e000" "LSB\e0" + "b\e001" "BITONE\e0" + "f\e004\e004" "NIBBLE2\e0" + "f\e020\e004" "BURST\e0" + "=\ex04" "FOUR\e0" + "=\ex0f" "FIFTEEN\e0" + "b\e037" "MSB\e0", + 0x800f0701, 34) +\(rA "0x800f0701<LSB,NIBBLE2=0>\e0" + "0x800f0701<BURST=0xf=FIFTEEN,MSB>\e0" + "" +.Ed +.Pp +A more complex example from +.In sys/mman.h +that uses both the single-bit +.Sq Cm b +formatting as well as the multi-bit field +.Sq Cm F +formatting with a default +.Sq Cm \&* : +.Bd -literal -offset indent +#define MAP_FMT "\e177\e020" \e + "b\e0" "SHARED\e0" \e + "b\e1" "PRIVATE\e0" \e + "b\e2" "COPY\e0" \e + "b\e4" "FIXED\e0" \e + "b\e5" "RENAME\e0" \e + "b\e6" "NORESERVE\e0" \e + "b\e7" "INHERIT\e0" \e + "b\e11" "HASSEMAPHORE\e0" \e + "b\e12" "TRYFIXED\e0" \e + "b\e13" "WIRED\e0" \e + "F\e14\e1\e0" \e + ":\e0" "FILE\e0" \e + ":\e1" "ANONYMOUS\e0" \e + "b\e15" "STACK\e0" \e + "F\e30\e010\e0" \e + ":\e000" "ALIGN=NONE\e0" \e + ":\e012" "ALIGN=1KB\e0" \e + ":\e013" "ALIGN=2KB\e0" \e + ":\e014" "ALIGN=4KB\e0" \e + ":\e015" "ALIGN=8KB\e0" \e + ":\e016" "ALIGN=16KB\e0" \e + ":\e017" "ALIGN=32KB\e0" \e + ":\e020" "ALIGN=64KB\e0" \e + ":\e021" "ALIGN=128KB\e0" \e + ":\e022" "ALIGN=256KB\e0" \e + ":\e023" "ALIGN=512KB\e0" \e + ":\e024" "ALIGN=1MB\e0" \e + ":\e025" "ALIGN=2MB\e0" \e + ":\e026" "ALIGN=4MB\e0" \e + ":\e027" "ALIGN=8MB\e0" \e + ":\e030" "ALIGN=16MB\e0" \e + ":\e034" "ALIGN=256MB\e0" \e + ":\e040" "ALIGN=4GB\e0" \e + ":\e044" "ALIGN=64GB\e0" \e + ":\e050" "ALIGN=1TB\e0" \e + ":\e054" "ALIGN=16TB\e0" \e + ":\e060" "ALIGN=256TB\e0" \e + ":\e064" "ALIGN=4PB\e0" \e + ":\e070" "ALIGN=64PB\e0" \e + ":\e074" "ALIGN=1EB\e0" \e + "*" "ALIGN=2^%ju\e0" + +snprintb(buf, bufsize, MAP_FMT, 0x0d001234) +\(rA "0xd001234<COPY,FIXED,RENAME,HASSEMAPHORE,ANONYMOUS,ALIGN=8KB>" + +snprintb(buf, bufsize, MAP_FMT, 0x2e000000) +\(rA "0x2e000000<FILE,ALIGN=2^46>" +.Ed +.Sh ERRORS +.Fn snprintb +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Pq Only in user mode. +The leading character +.Po for the +.Dq old +format +.Pc +or the second character +.Po for the +.Dq new +format +.Pc +does not describe a supported numeral base, +or a bit number in the +.Ar fmt +argument is out of bounds, +or the sequence of conversions in the +.Ar fmt +argument is invalid, +or +.Fn snprintf +failed. +.El +.Sh SEE ALSO +.Xr snprintf 3 +.Sh HISTORY +The +.Fn snprintb +function was originally implemented as a non-standard +.Li %b +format string for the kernel +.Fn printf +function in +.Nx 1.5 +and earlier releases. +It was called +.Fn bitmask_snprintf +in +.Nx 5.0 +and earlier releases. +.Sh AUTHORS +The +.Dq new +format was the invention of +.An Chris Torek . +.Sh CAVEATS +When using hexadecimal character escapes for bit positions or field widths, +if a following description starts with one of the letters A to F, +that letter is considered part of the character escape. +In such a situation, the character escape and the description must be +put into separate string literals, as in +.Li \[dq]\ex0f\[dq] \[dq]FIFTEEN\[dq] . diff --git a/static/netbsd/man3/sockaddr_snprintf.3 b/static/netbsd/man3/sockaddr_snprintf.3 new file mode 100644 index 00000000..8608dea8 --- /dev/null +++ b/static/netbsd/man3/sockaddr_snprintf.3 @@ -0,0 +1,257 @@ +.\" $NetBSD: sockaddr_snprintf.3,v 1.12 2025/09/15 12:56:32 christos Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 15, 2025 +.Dt SOCKADDR_SNPRINTF 3 +.Os +.Sh NAME +.Nm sockaddr_snprintf +.Nd formatting function for socket address structures +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn sockaddr_snprintf "char *buf" "size_t buflen" "const char *fmt" "const struct sockaddr *sa" +.Sh DESCRIPTION +The +.Fn sockaddr_snprintf +function formats a socket address into a form suitable for printing. +.Pp +This function is convenient because it is protocol independent, i.e. one does +not need to know the address family of the sockaddr in order to print it. +The +.Xr printf 3 +like format string specifies how the address is going to be printed. +Some formatting characters are only supported by some address families. +If a certain formatting character is not supported, then the string +.Dq N/A +is printed. +.Pp +The resulting formatted string is placed into +.Fa buf . +Up to +.Fa buflen +characters are placed in +.Fa buf . +.Pp +The following formatting characters are supported (immediately +after a percent +.Pq Sq % +sign): +.Bl -tag -width %a +.It a +The node address portion of the socket address is printed numerically. +For +.Dv AF_INET +the address is printed as: +.Dq A.B.C.D +and +for AF_INET6 +the address is printed as: +.Dq A:B...[%if] +using +.Xr getnameinfo 3 +internally with +.Dv NI_NUMERICHOST . +For +.Dv AF_APPLETALK +the address is printed as: +.Dq A.B +For +.Dv AF_LOCAL +.Pq Dv AF_UNIX +the address is printed as: +.Dq socket-path +For +.Dv AF_LINK +the address is printed as: +.Dq a.b.c.d.e.f +using +.Xr link_ntoa 3 , +but the interface portion is skipped (see below). +For +.Dv AF_UNSPEC +nothing is printed. +.It A +The symbolic name of the address is printed. +For +.Dv AF_INET +and +.Dv AF_INET6 +this is the hostname associated with the address. +For all other address families, it is the same as the +.Dq a +format. +.It D +Debugging output: +For all addresses, print all their fields as +.Dq field_name=value . +.It f +The numeric value of the family of the address is printed. +.It l +The length of the socket address is printed. +.It m +The symbolic name of the address family is printed +.Sq appletalk , +.Sq inet , +.Sq inet6 , +.Sq link , +or +.Sq unix . +.It n +The address is printed numerically. If the address supports a port, +then %a:%p is printed except for inet6 where [%a]:%p is printed. +Otherwise %a is printed. +.It N +The address is printed symbolically. If the address supports a port, +then %A:%P is printed except for inet6 where [%A]:%P is printed (because +name resolution can fail, and also to differentiate from ipv4). +Otherwise %A is printed. +.It p +For +.Dv AF_INET , +.Dv AF_INET6 , +and +.Dv AF_APPLETALK +the numeric value of the port portion of the address is printed. +.It P +For +.Dv AF_INET +and +.Dv AF_INET6 +this is the name of the service associated with the port number, if +available. +For all other address families, it is the same as the +.Dq p +format. +.It I +For +.Dv AF_LINK +addresses, the interface name portion is printed. +.It F +For +.Dv AF_INET6 +addresses, the flowinfo portion of the address is printed numerically. +.It R +For +.Dv AF_APPLETALK +addresses, the netrange portion of the address is printed as: +.Dq phase:[firstnet,lastnet] +.It S +For +.Dv AF_INET6 +addresses, the scope portion of the address is printed numerically. +.It ? +If present between +.Dq % +and the format character, and the selected format does not apply to +the given address family, the +.Dq N/A +string is elided and no output results. +.El +.Sh RETURN VALUES +The +.Fn sockaddr_snprintf +function returns the number of characters that are required to format the +value +.Fa val +given the format string +.Fa fmt +excluding the terminating NUL. +The returned string in +.Fa buf +is always NUL-terminated. +If the address family is not supported, +.Fn sockaddr_snprintf +returns \-1 and sets +.Va errno +to +.Er EAFNOSUPPORT . +For +.Dv AF_INET +and +.Dv AF_INET6 +addresses +.Fn sockaddr_snprintf +returns \-1 if the +.Xr getnameinfo 3 +conversion failed, and +.Fa errno +is set to the error value from +.Xr getnameinfo 3 . +.Sh ERRORS +If the buffer +.Fa buf +is too small to hold the formatted output, +.Fn sockaddr_snprintf +will still return the buffer, containing a truncated string. +.Sh SEE ALSO +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 , +.Xr link_ntoa 3 , +.Xr snprintf 3 +.Sh HISTORY +The +.Fn sockaddr_snprintf +first appeared in +.Nx 3.0 . +.Sh BUGS +The +.Fn sockaddr_snprintf +interface is experimental and might change in the future. +.Pp +There is no way to specify different formatting styles for particular +addresses. +For example it would be useful to print +.Dv AF_LINK +addresses as +.Dq %.2x:%.2x... +instead of +.Dq %x.%x... +.Pp +This function is supposed to be quick, but +.Xr getnameinfo 3 +might use system calls to convert the scope number to an interface +name and the +.Dq A +and +.Dq P +format characters call +.Xr getaddrinfo 3 +which may block for a noticeable period of time. +.Pp +Not all formatting characters are supported by all address families and +printing +.Dq N/A +is not very convenient. +The +.Dq \&? +character can suppress this, but other formatting (e.g., spacing or +punctuation) will remain. diff --git a/static/netbsd/man3/sockatmark.3 b/static/netbsd/man3/sockatmark.3 new file mode 100644 index 00000000..77717339 --- /dev/null +++ b/static/netbsd/man3/sockatmark.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: sockatmark.3,v 1.10 2022/06/28 20:12:52 rillig Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 28, 2022 +.Dt SOCKATMARK 3 +.Os +.Sh NAME +.Nm sockatmark +.Nd determine whether a socket is at the out-of-band mark +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn sockatmark "int s" +.Sh DESCRIPTION +The +.Nm sockatmark +function determines whether the socket referenced by the file descriptor +.Fa s +is at the out-of-band mark. +.Sh RETURN VALUES +If successful, the +.Nm sockatmark +function returns 1 to indicate that the socket is at an out-of-band mark; +0 is returned if there is no out-of-band mark or the mark is preceded +by in-band data. +Otherwise, -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Nm sockatmark +function will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid file descriptor. +.It Bq Er ENOTTY +The file descriptor +.Fa s +does not refer to a socket. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr recv 2 , +.Xr socket 2 +.Rs +.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" +.%A Stuart Sechrest +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets +.Rs +.%T "Advanced 4.4BSD IPC Tutorial" +.%A Samuel J. Leffler +.%A Robert S. Fabry +.%A William N. Joy +.%A Phil Lapsley +.%A Steve Miller +.%A Chris Torek +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets-advanced +.Sh STANDARDS +The +.Nm sockatmark +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Nm sockatmark +function appeared in +.St -p1003.1g-2000 +as a replacement for the +.Dv SIOCATMARK +.Xr ioctl 2 +interface. diff --git a/static/netbsd/man3/sqlite3.3 b/static/netbsd/man3/sqlite3.3 new file mode 100644 index 00000000..557ead8f --- /dev/null +++ b/static/netbsd/man3/sqlite3.3 @@ -0,0 +1,41 @@ +.Dd January 24, 2024 +.Dt SQLITE3 3 +.Os +.Sh NAME +.Nm sqlite3 +.Nd database connection handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3 sqlite3; +.Sh DESCRIPTION +Each open SQLite database is represented by a pointer to an instance +of the opaque structure named "sqlite3". +It is useful to think of an sqlite3 pointer as an object. +The +.Fn sqlite3_open , +.Fn sqlite3_open16 , +and +.Fn sqlite3_open_v2 +interfaces are its constructors, and +.Fn sqlite3_close +and +.Fn sqlite3_close_v2 +are its destructors. +There are many other interfaces (such as +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_create_function , +and +.Fn sqlite3_busy_timeout +to name but three) that are methods on an sqlite3 object. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 259. +.Bd -literal +typedef struct sqlite3 sqlite3; +.Ed +.Sh SEE ALSO +.Xr sqlite3_busy_timeout 3 , +.Xr sqlite3_close 3 , +.Xr sqlite3_create_function 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_prepare 3 diff --git a/static/netbsd/man3/sqlite3_aggregate_context.3 b/static/netbsd/man3/sqlite3_aggregate_context.3 new file mode 100644 index 00000000..436ed5f0 --- /dev/null +++ b/static/netbsd/man3/sqlite3_aggregate_context.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_AGGREGATE_CONTEXT 3 +.Os +.Sh NAME +.Nm sqlite3_aggregate_context +.Nd obtain aggregate function context +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_aggregate_context +.Fa "sqlite3_context*" +.Fa "int nBytes" +.Fc +.Sh DESCRIPTION +Implementations of aggregate SQL functions use this routine to allocate +memory for storing their state. +.Pp +The first time the sqlite3_aggregate_context(C,N) routine is called +for a particular aggregate function, SQLite allocates N bytes of memory, +zeroes out that memory, and returns a pointer to the new memory. +On second and subsequent calls to sqlite3_aggregate_context() for the +same aggregate function instance, the same buffer is returned. +Sqlite3_aggregate_context() is normally called once for each invocation +of the xStep callback and then one last time when the xFinal callback +is invoked. +When no rows match an aggregate query, the xStep() callback of the +aggregate function implementation is never called and xFinal() is called +exactly once. +In those cases, sqlite3_aggregate_context() might be called for the +first time from within xFinal(). +.Pp +The sqlite3_aggregate_context(C,N) routine returns a NULL pointer when +first called if N is less than or equal to zero or if a memory allocation +error occurs. +.Pp +The amount of space allocated by sqlite3_aggregate_context(C,N) is +determined by the N parameter on first successful call. +Changing the value of N in any subsequent call to sqlite3_aggregate_context() +within the same aggregate function instance will not resize the memory +allocation. +Within the xFinal callback, it is customary to set N=0 in calls to +sqlite3_aggregate_context(C,N) so that no pointless memory allocations +occur. +.Pp +SQLite automatically frees the memory allocated by sqlite3_aggregate_context() +when the aggregate query concludes. +.Pp +The first parameter must be a copy of the SQL function context +that is the first parameter to the xStep or xFinal callback routine +that implements the aggregate function. +.Pp +This routine must be called from the same thread in which the aggregate +SQL function is running. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5831. +.Bd -literal +SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); +.Ed +.Sh SEE ALSO +.Xr sqlite3_context 3 diff --git a/static/netbsd/man3/sqlite3_aggregate_count.3 b/static/netbsd/man3/sqlite3_aggregate_count.3 new file mode 100644 index 00000000..87575206 --- /dev/null +++ b/static/netbsd/man3/sqlite3_aggregate_count.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_AGGREGATE_COUNT 3 +.Os +.Sh NAME +.Nm sqlite3_aggregate_count , +.Nm sqlite3_expired , +.Nm sqlite3_transfer_bindings , +.Nm sqlite3_global_recover , +.Nm sqlite3_thread_cleanup , +.Nm sqlite3_memory_alarm +.Nd deprecated functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_aggregate_count +.Fa "sqlite3_context*" +.Fc +.Ft int +.Fo sqlite3_expired +.Fa "sqlite3_stmt*" +.Fc +.Ft int +.Fo sqlite3_transfer_bindings +.Fa "sqlite3_stmt*" +.Fa "sqlite3_stmt*" +.Fc +.Ft int +.Fo sqlite3_global_recover +.Fa "void" +.Fc +.Ft void +.Fo sqlite3_thread_cleanup +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_memory_alarm +.Fa "void(*)(void*,sqlite3_int64,int)" +.Fa "void*" +.Fa "sqlite3_int64" +.Fc +.Sh DESCRIPTION +These functions are deprecated. +In order to maintain backwards compatibility with older code, these +functions continue to be supported. +However, new applications should avoid the use of these functions. +To encourage programmers to avoid these functions, we will not explain +what they do. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5609. +.Bd -literal +#ifndef SQLITE_OMIT_DEPRECATED +SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); +SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); +SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); +SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); +SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); +SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int), + void*,sqlite3_int64); +#endif +.Ed diff --git a/static/netbsd/man3/sqlite3_api_routines.3 b/static/netbsd/man3/sqlite3_api_routines.3 new file mode 100644 index 00000000..d45ed329 --- /dev/null +++ b/static/netbsd/man3/sqlite3_api_routines.3 @@ -0,0 +1,20 @@ +.Dd January 24, 2024 +.Dt SQLITE3_API_ROUTINES 3 +.Os +.Sh NAME +.Nm sqlite3_api_routines +.Nd loadable extension thunk +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_api_routines sqlite3_api_routines; +.Sh DESCRIPTION +A pointer to the opaque sqlite3_api_routines structure is passed as +the third parameter to entry points of loadable extensions. +This structure must be typedefed in order to work around compiler warnings +on some platforms. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1265. +.Bd -literal +typedef struct sqlite3_api_routines sqlite3_api_routines; +.Ed diff --git a/static/netbsd/man3/sqlite3_auto_extension.3 b/static/netbsd/man3/sqlite3_auto_extension.3 new file mode 100644 index 00000000..5168b69f --- /dev/null +++ b/static/netbsd/man3/sqlite3_auto_extension.3 @@ -0,0 +1,64 @@ +.Dd January 24, 2024 +.Dt SQLITE3_AUTO_EXTENSION 3 +.Os +.Sh NAME +.Nm sqlite3_auto_extension +.Nd automatically load statically linked extensions +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_auto_extension +.Fa "void(*xEntryPoint)(void)" +.Fc +.Sh DESCRIPTION +This interface causes the xEntryPoint() function to be invoked for +each new database connection that is created. +The idea here is that xEntryPoint() is the entry point for a statically +linked SQLite extension that is to be automatically +loaded into all new database connections. +.Pp +Even though the function prototype shows that xEntryPoint() takes no +arguments and returns void, SQLite invokes xEntryPoint() with three +arguments and expects an integer result as if the signature of the +entry point where as follows: +.Bd -ragged +.Bd -literal + int xEntryPoint( sqlite3 *db, const char **pzErrMsg, +const struct sqlite3_api_routines *pThunk ); +.Ed +.Pp +.Ed +.Pp +If the xEntryPoint routine encounters an error, it should make *pzErrMsg +point to an appropriate error message (obtained from +.Fn sqlite3_mprintf ) +and return an appropriate error code. +SQLite ensures that *pzErrMsg is NULL before calling the xEntryPoint(). +SQLite will invoke +.Fn sqlite3_free +on *pzErrMsg after xEntryPoint() returns. +If any xEntryPoint() returns an error, the +.Fn sqlite3_open , +.Fn sqlite3_open16 , +or +.Fn sqlite3_open_v2 +call that provoked the xEntryPoint() will fail. +.Pp +Calling sqlite3_auto_extension(X) with an entry point X that is already +on the list of automatic extensions is a harmless no-op. +No entry point will be called more than once for each database connection +that is opened. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7207. +.Bd -literal +SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void)); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_cancel_auto_extension 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mprintf 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_reset_auto_extension 3 diff --git a/static/netbsd/man3/sqlite3_autovacuum_pages.3 b/static/netbsd/man3/sqlite3_autovacuum_pages.3 new file mode 100644 index 00000000..670da1be --- /dev/null +++ b/static/netbsd/man3/sqlite3_autovacuum_pages.3 @@ -0,0 +1,82 @@ +.Dd January 24, 2024 +.Dt SQLITE3_AUTOVACUUM_PAGES 3 +.Os +.Sh NAME +.Nm sqlite3_autovacuum_pages +.Nd autovacuum compaction amount callback +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_autovacuum_pages +.Fa "sqlite3 *db" +.Fa "unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int)" +.Fa "void*" +.Fa "void(*)(void*)" +.Fc +.Sh DESCRIPTION +The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback +function C that is invoked prior to each autovacuum of the database +file. +The callback is passed a copy of the generic data pointer (P), the +schema-name of the attached database that is being autovacuumed, the +size of the database file in pages, the number of free pages, and the +number of bytes per page, respectively. +The callback should return the number of free pages that should be +removed by the autovacuum. +If the callback returns zero, then no autovacuum happens. +If the value returned is greater than or equal to the number of free +pages, then a complete autovacuum happens. +.Pp +If there are multiple ATTACH-ed database files that are being modified +as part of a transaction commit, then the autovacuum pages callback +is invoked separately for each file. +.Pp +\fBThe callback is not reentrant.\fP The callback function should not attempt +to invoke any other SQLite interface. +If it does, bad things may happen, including segmentation faults and +corrupt database files. +The callback function should be a simple function that does some arithmetic +on its input parameters and returns a result. +.Pp +The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional +destructor for the P parameter. +If X is not NULL, then X(P) is invoked whenever the database connection +closes or when the callback is overwritten by another invocation of +sqlite3_autovacuum_pages(). +.Pp +There is only one autovacuum pages callback per database connection. +Each call to the sqlite3_autovacuum_pages() interface overrides all +previous invocations for that database connection. +If the callback argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is +a NULL pointer, then the autovacuum steps callback is canceled. +The return value from sqlite3_autovacuum_pages() is normally SQLITE_OK, +but might be some other error code if something goes wrong. +The current implementation will only return SQLITE_OK or SQLITE_MISUSE, +but other return codes might be added in future releases. +.Pp +If no autovacuum pages callback is specified (the usual case) or a +NULL pointer is provided for the callback, then the default behavior +is to vacuum all free pages. +So, in other words, the default behavior is the same as if the callback +function were something like this: +.Bd -ragged +.Bd -literal + unsigned int demonstration_autovac_pages_callback( void *pClientData, + const char *zSchema, unsigned int nDbPage, unsigned +int nFreePage, unsigned int nBytePerPage ){ return +nFreePage; } +.Ed +.Pp +.Ed +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6772. +.Bd -literal +SQLITE_API int sqlite3_autovacuum_pages( + sqlite3 *db, + unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int), + void*, + void(*)(void*) +); +.Ed diff --git a/static/netbsd/man3/sqlite3_backup.3 b/static/netbsd/man3/sqlite3_backup.3 new file mode 100644 index 00000000..6c411495 --- /dev/null +++ b/static/netbsd/man3/sqlite3_backup.3 @@ -0,0 +1,24 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BACKUP 3 +.Os +.Sh NAME +.Nm sqlite3_backup +.Nd online backup object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_backup sqlite3_backup; +.Sh DESCRIPTION +The sqlite3_backup object records state information about an ongoing +online backup operation. +The sqlite3_backup object is created by a call to +.Fn sqlite3_backup_init +and is destroyed by a call to +.Fn sqlite3_backup_finish . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9107. +.Bd -literal +typedef struct sqlite3_backup sqlite3_backup; +.Ed +.Sh SEE ALSO +.Xr sqlite3_backup_init 3 diff --git a/static/netbsd/man3/sqlite3_backup_init.3 b/static/netbsd/man3/sqlite3_backup_init.3 new file mode 100644 index 00000000..bf951b84 --- /dev/null +++ b/static/netbsd/man3/sqlite3_backup_init.3 @@ -0,0 +1,253 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BACKUP_INIT 3 +.Os +.Sh NAME +.Nm sqlite3_backup_init , +.Nm sqlite3_backup_step , +.Nm sqlite3_backup_finish , +.Nm sqlite3_backup_remaining , +.Nm sqlite3_backup_pagecount +.Nd online backup API +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_backup * +.Fo sqlite3_backup_init +.Fa "sqlite3 *pDest" +.Fa "const char *zDestName" +.Fa "sqlite3 *pSource" +.Fa "const char *zSourceName" +.Fc +.Ft int +.Fo sqlite3_backup_step +.Fa "sqlite3_backup *p" +.Fa "int nPage" +.Fc +.Ft int +.Fo sqlite3_backup_finish +.Fa "sqlite3_backup *p" +.Fc +.Ft int +.Fo sqlite3_backup_remaining +.Fa "sqlite3_backup *p" +.Fc +.Ft int +.Fo sqlite3_backup_pagecount +.Fa "sqlite3_backup *p" +.Fc +.Sh DESCRIPTION +The backup API copies the content of one database into another. +It is useful either for creating backups of databases or for copying +in-memory databases to or from persistent files. +.Pp +SQLite holds a write transaction open on the destination database file +for the duration of the backup operation. +The source database is read-locked only while it is being read; it +is not locked continuously for the entire backup operation. +Thus, the backup may be performed on a live source database without +preventing other database connections from reading or writing to the +source database while the backup is underway. +.Pp +To perform a backup operation: +.Bl -enum +.It +\fBsqlite3_backup_init()\fP is called once to initialize the backup, +.It +\fBsqlite3_backup_step()\fP is called one or more times to transfer the data +between the two databases, and finally +.It +\fBsqlite3_backup_finish()\fP is called to release all resources associated +with the backup operation. +.El +.Pp +There should be exactly one call to sqlite3_backup_finish() for each +successful call to sqlite3_backup_init(). +.Pp +\fBsqlite3_backup_init()\fP +.Pp +The D and N arguments to sqlite3_backup_init(D,N,S,M) are the database connection +associated with the destination database and the database name, respectively. +The database name is "main" for the main database, "temp" for the temporary +database, or the name specified after the AS keyword in an ATTACH +statement for an attached database. +The S and M arguments passed to sqlite3_backup_init(D,N,S,M) identify +the database connection and database name of the +source database, respectively. +The source and destination database connections +(parameters S and D) must be different or else sqlite3_backup_init(D,N,S,M) +will fail with an error. +.Pp +A call to sqlite3_backup_init() will fail, returning NULL, if there +is already a read or read-write transaction open on the destination +database. +.Pp +If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is +returned and an error code and error message are stored in the destination +database connection D. +The error code and message for the failed call to sqlite3_backup_init() +can be retrieved using the +.Fn sqlite3_errcode , +.Fn sqlite3_errmsg , +and/or +.Fn sqlite3_errmsg16 +functions. +A successful call to sqlite3_backup_init() returns a pointer to an +sqlite3_backup object. +The sqlite3_backup object may be used with the sqlite3_backup_step() +and sqlite3_backup_finish() functions to perform the specified backup +operation. +.Pp +\fBsqlite3_backup_step()\fP +.Pp +Function sqlite3_backup_step(B,N) will copy up to N pages between the +source and destination databases specified by sqlite3_backup +object B. +If N is negative, all remaining source pages are copied. +If sqlite3_backup_step(B,N) successfully copies N pages and there are +still more pages to be copied, then the function returns SQLITE_OK. +If sqlite3_backup_step(B,N) successfully finishes copying all pages +from source to destination, then it returns SQLITE_DONE. +If an error occurs while running sqlite3_backup_step(B,N), then an +error code is returned. +As well as SQLITE_OK and SQLITE_DONE, a call to +sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, +SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX +extended error code. +.Pp +The sqlite3_backup_step() might return SQLITE_READONLY +if +.Bl -enum +.It +the destination database was opened read-only, or +.It +the destination database is using write-ahead-log journaling and the +destination and source page sizes differ, or +.It +the destination database is an in-memory database and the destination +and source page sizes differ. +.El +.Pp +If sqlite3_backup_step() cannot obtain a required file-system lock, +then the busy-handler function is invoked (if +one is specified). +If the busy-handler returns non-zero before the lock is available, +then SQLITE_BUSY is returned to the caller. +In this case the call to sqlite3_backup_step() can be retried later. +If the source database connection is being used +to write to the source database when sqlite3_backup_step() is called, +then SQLITE_LOCKED is returned immediately. +Again, in this case the call to sqlite3_backup_step() can be retried +later on. +If SQLITE_IOERR_XXX, SQLITE_NOMEM, or SQLITE_READONLY +is returned, then there is no point in retrying the call to sqlite3_backup_step(). +These errors are considered fatal. +The application must accept that the backup operation has failed and +pass the backup operation handle to the sqlite3_backup_finish() to +release associated resources. +.Pp +The first call to sqlite3_backup_step() obtains an exclusive lock on +the destination file. +The exclusive lock is not released until either sqlite3_backup_finish() +is called or the backup operation is complete and sqlite3_backup_step() +returns SQLITE_DONE. +Every call to sqlite3_backup_step() obtains a shared lock +on the source database that lasts for the duration of the sqlite3_backup_step() +call. +Because the source database is not locked between calls to sqlite3_backup_step(), +the source database may be modified mid-way through the backup process. +If the source database is modified by an external process or via a +database connection other than the one being used by the backup operation, +then the backup will be automatically restarted by the next call to +sqlite3_backup_step(). +If the source database is modified by the using the same database connection +as is used by the backup operation, then the backup database is automatically +updated at the same time. +.Pp +\fBsqlite3_backup_finish()\fP +.Pp +When sqlite3_backup_step() has returned SQLITE_DONE, or +when the application wishes to abandon the backup operation, the application +should destroy the sqlite3_backup by passing it to sqlite3_backup_finish(). +The sqlite3_backup_finish() interfaces releases all resources associated +with the sqlite3_backup object. +If sqlite3_backup_step() has not yet returned SQLITE_DONE, +then any active write-transaction on the destination database is rolled +back. +The sqlite3_backup object is invalid and may not be used +following a call to sqlite3_backup_finish(). +.Pp +The value returned by sqlite3_backup_finish is SQLITE_OK if +no sqlite3_backup_step() errors occurred, regardless or whether or +not sqlite3_backup_step() completed. +If an out-of-memory condition or IO error occurred during any prior +sqlite3_backup_step() call on the same sqlite3_backup +object, then sqlite3_backup_finish() returns the corresponding error code. +.Pp +A return of SQLITE_BUSY or SQLITE_LOCKED from +sqlite3_backup_step() is not a permanent error and does not affect +the return value of sqlite3_backup_finish(). +.Pp +\fBsqlite3_backup_remaining() and sqlite3_backup_pagecount()\fP +.Pp +The sqlite3_backup_remaining() routine returns the number of pages +still to be backed up at the conclusion of the most recent sqlite3_backup_step(). +The sqlite3_backup_pagecount() routine returns the total number of +pages in the source database at the conclusion of the most recent sqlite3_backup_step(). +The values returned by these functions are only updated by sqlite3_backup_step(). +If the source database is modified in a way that changes the size of +the source database or the number of pages remaining, those changes +are not reflected in the output of sqlite3_backup_pagecount() and sqlite3_backup_remaining() +until after the next sqlite3_backup_step(). +.Pp +\fBConcurrent Usage of Database Handles\fP +.Pp +The source database connection may be used by the +application for other purposes while a backup operation is underway +or being initialized. +If SQLite is compiled and configured to support threadsafe database +connections, then the source database connection may be used concurrently +from within other threads. +.Pp +However, the application must guarantee that the destination database connection +is not passed to any other API (by any thread) after sqlite3_backup_init() +is called and before the corresponding call to sqlite3_backup_finish(). +SQLite does not currently check to see if the application incorrectly +accesses the destination database connection and +so no error code is reported, but the operations may malfunction nevertheless. +Use of the destination database connection while a backup is in progress +might also cause a mutex deadlock. +.Pp +If running in shared cache mode, the application must +guarantee that the shared cache used by the destination database is +not accessed while the backup is running. +In practice this means that the application must guarantee that the +disk file being backed up to is not accessed by any connection within +the process, not just the specific connection that was passed to sqlite3_backup_init(). +.Pp +The sqlite3_backup object itself is partially threadsafe. +Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). +However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() +APIs are not strictly speaking threadsafe. +If they are invoked at the same time as another thread is invoking +sqlite3_backup_step() it is possible that they return invalid values. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9119. +.Bd -literal +SQLITE_API sqlite3_backup *sqlite3_backup_init( + sqlite3 *pDest, /* Destination database handle */ + const char *zDestName, /* Destination database name */ + sqlite3 *pSource, /* Source database handle */ + const char *zSourceName /* Source database name */ +); +SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage); +SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p); +SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p); +SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_backup 3 , +.Xr sqlite3_busy_handler 3 , +.Xr sqlite3_errcode 3 , +.Xr SQLITE_ERROR_MISSING_COLLSEQ 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_bind_blob.3 b/static/netbsd/man3/sqlite3_bind_blob.3 new file mode 100644 index 00000000..1f319956 --- /dev/null +++ b/static/netbsd/man3/sqlite3_bind_blob.3 @@ -0,0 +1,293 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BIND_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_bind_blob , +.Nm sqlite3_bind_blob64 , +.Nm sqlite3_bind_double , +.Nm sqlite3_bind_int , +.Nm sqlite3_bind_int64 , +.Nm sqlite3_bind_null , +.Nm sqlite3_bind_text , +.Nm sqlite3_bind_text16 , +.Nm sqlite3_bind_text64 , +.Nm sqlite3_bind_value , +.Nm sqlite3_bind_pointer , +.Nm sqlite3_bind_zeroblob , +.Nm sqlite3_bind_zeroblob64 +.Nd binding values to prepared statements +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_bind_blob +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "int n" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_blob64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_double +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "double" +.Fc +.Ft int +.Fo sqlite3_bind_int +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_bind_int64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "sqlite3_int64" +.Fc +.Ft int +.Fo sqlite3_bind_null +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_bind_text +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const char*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_text16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_text64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const char*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fa "unsigned char encoding" +.Fc +.Ft int +.Fo sqlite3_bind_value +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_bind_pointer +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "void*" +.Fa "const char*" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_zeroblob +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "int n" +.Fc +.Ft int +.Fo sqlite3_bind_zeroblob64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "sqlite3_uint64" +.Fc +.Sh DESCRIPTION +In the SQL statement text input to +.Fn sqlite3_prepare_v2 +and its variants, literals may be replaced by a parameter +that matches one of following templates: +.Bl -bullet +.It +? +.It +?NNN +.It +:VVV +.It +@VVV +.It +$VVV +.El +.Pp +In the templates above, NNN represents an integer literal, and VVV +represents an alphanumeric identifier. +The values of these parameters (also called "host parameter names" +or "SQL parameters") can be set using the sqlite3_bind_*() routines +defined here. +.Pp +The first argument to the sqlite3_bind_*() routines is always a pointer +to the sqlite3_stmt object returned from +.Fn sqlite3_prepare_v2 +or its variants. +.Pp +The second argument is the index of the SQL parameter to be set. +The leftmost SQL parameter has an index of 1. +When the same named SQL parameter is used more than once, second and +subsequent occurrences have the same index as the first occurrence. +The index for named parameters can be looked up using the +.Fn sqlite3_bind_parameter_index +API if desired. +The index for "?NNN" parameters is the value of NNN. +The NNN value must be between 1 and the +.Fn sqlite3_limit +parameter SQLITE_LIMIT_VARIABLE_NUMBER +(default value: 32766). +.Pp +The third argument is the value to bind to the parameter. +If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() +or sqlite3_bind_blob() is a NULL pointer then the fourth parameter +is ignored and the end result is the same as sqlite3_bind_null(). +If the third parameter to sqlite3_bind_text() is not NULL, then it +should be a pointer to well-formed UTF8 text. +If the third parameter to sqlite3_bind_text16() is not NULL, then it +should be a pointer to well-formed UTF16 text. +If the third parameter to sqlite3_bind_text64() is not NULL, then it +should be a pointer to a well-formed unicode string that is either +UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 otherwise. +.Pp +The byte-order of UTF16 input text is determined by the byte-order +mark (BOM, U+FEFF) found in first character, which is removed, or in +the absence of a BOM the byte order is the native byte order of the +host machine for sqlite3_bind_text16() or the byte order specified +in the 6th parameter for sqlite3_bind_text64(). +If UTF16 input text contains invalid unicode characters, then SQLite +might change those invalid characters into the unicode replacement +character: U+FFFD. +.Pp +In those routines that have a fourth argument, its value is the number +of bytes in the parameter. +To be clear: the value is the number of \fIbytes\fP in the value, not the +number of characters. +If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() +is negative, then the length of the string is the number of bytes up +to the first zero terminator. +If the fourth parameter to sqlite3_bind_blob() is negative, then the +behavior is undefined. +If a non-negative fourth parameter is provided to sqlite3_bind_text() +or sqlite3_bind_text16() or sqlite3_bind_text64() then that parameter +must be the byte offset where the NUL terminator would occur assuming +the string were NUL terminated. +If any NUL characters occurs at byte offsets less than the value of +the fourth parameter then the resulting string value will contain embedded +NULs. +The result of expressions involving strings with embedded NULs is undefined. +.Pp +The fifth argument to the BLOB and string binding interfaces controls +or indicates the lifetime of the object referenced by the third parameter. +These three options exist: (1) A destructor to dispose of the BLOB +or string after SQLite has finished with it may be passed. +It is called to dispose of the BLOB or string even if the call to the +bind API fails, except the destructor is not called if the third parameter +is a NULL pointer or the fourth parameter is negative. +(2) The special constant, SQLITE_STATIC, may be passed +to indicate that the application remains responsible for disposing +of the object. +In this case, the object and the provided pointer to it must remain +valid until either the prepared statement is finalized or the same +SQL parameter is bound to something else, whichever occurs sooner. +(3) The constant, SQLITE_TRANSIENT, may be passed to +indicate that the object is to be copied prior to the return from sqlite3_bind_*(). +The object and pointer to it must remain valid until then. +SQLite will then manage the lifetime of its private copy. +.Pp +The sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8, +SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE +to specify the encoding of the text in the third parameter. +If the sixth argument to sqlite3_bind_text64() is not one of the allowed +values shown above, or if the text encoding is different from the encoding +specified by the sixth parameter, then the behavior is undefined. +.Pp +The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is +filled with zeroes. +A zeroblob uses a fixed amount of memory (just an integer to hold its +size) while it is being processed. +Zeroblobs are intended to serve as placeholders for BLOBs whose content +is later written using incremental BLOB I/O routines. +A negative value for the zeroblob results in a zero-length BLOB. +.Pp +The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter +in prepared statement S to have an SQL value of NULL, +but to also be associated with the pointer P of type T. +D is either a NULL pointer or a pointer to a destructor function for +P. +SQLite will invoke the destructor D with a single argument of P when +it is finished using P. +The T parameter should be a static string, preferably a string literal. +The sqlite3_bind_pointer() routine is part of the pointer passing interface +added for SQLite 3.20.0. +.Pp +If any of the sqlite3_bind_*() routines are called with a NULL pointer +for the prepared statement or with a prepared statement +for which +.Fn sqlite3_step +has been called more recently than +.Fn sqlite3_reset , +then the call will return SQLITE_MISUSE. +If any sqlite3_bind_() routine is passed a prepared statement +that has been finalized, the result is undefined and probably harmful. +.Pp +Bindings are not cleared by the +.Fn sqlite3_reset +routine. +Unbound parameters are interpreted as NULL. +.Pp +The sqlite3_bind_* routines return SQLITE_OK on success or +an error code if anything goes wrong. +SQLITE_TOOBIG might be returned if the size of a string +or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) +or SQLITE_MAX_LENGTH. +SQLITE_RANGE is returned if the parameter index is out +of range. +SQLITE_NOMEM is returned if malloc() fails. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4543. +.Bd -literal +SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); +SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, + void(*)(void*)); +SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); +SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); +SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); +SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); +SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); +SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); +SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, + void(*)(void*), unsigned char encoding); +SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); +SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); +SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); +SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_parameter_count 3 , +.Xr sqlite3_bind_parameter_index 3 , +.Xr sqlite3_bind_parameter_name 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_destructor_type 3 , +.Xr sqlite3_limit 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_LIMIT_LENGTH 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_bind_parameter_count.3 b/static/netbsd/man3/sqlite3_bind_parameter_count.3 new file mode 100644 index 00000000..f3d06d92 --- /dev/null +++ b/static/netbsd/man3/sqlite3_bind_parameter_count.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BIND_PARAMETER_COUNT 3 +.Os +.Sh NAME +.Nm sqlite3_bind_parameter_count +.Nd number of SQL parameters +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_bind_parameter_count +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +This routine can be used to find the number of SQL parameters +in a prepared statement. +SQL parameters are tokens of the form "?", "?NNN", ":AAA", "$AAA", +or "@AAA" that serve as placeholders for values that are bound +to the parameters at a later time. +.Pp +This routine actually returns the index of the largest (rightmost) +parameter. +For all forms except ?NNN, this will correspond to the number of unique +parameters. +If parameters of the ?NNN form are used, there may be gaps in the list. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4699. +.Bd -literal +SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_bind_parameter_index 3 , +.Xr sqlite3_bind_parameter_name 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_bind_parameter_index.3 b/static/netbsd/man3/sqlite3_bind_parameter_index.3 new file mode 100644 index 00000000..5ad59b11 --- /dev/null +++ b/static/netbsd/man3/sqlite3_bind_parameter_index.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BIND_PARAMETER_INDEX 3 +.Os +.Sh NAME +.Nm sqlite3_bind_parameter_index +.Nd index of a parameter with a given name +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_bind_parameter_index +.Fa "sqlite3_stmt*" +.Fa "const char *zName" +.Fc +.Sh DESCRIPTION +Return the index of an SQL parameter given its name. +The index value returned is suitable for use as the second parameter +to sqlite3_bind(). +A zero is returned if no matching parameter is found. +The parameter name must be given in UTF-8 even if the original statement +was prepared from UTF-16 text using +.Fn sqlite3_prepare16_v2 +or +.Fn sqlite3_prepare16_v3 . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4748. +.Bd -literal +SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_bind_parameter_count 3 , +.Xr sqlite3_bind_parameter_name 3 , +.Xr sqlite3_prepare 3 diff --git a/static/netbsd/man3/sqlite3_bind_parameter_name.3 b/static/netbsd/man3/sqlite3_bind_parameter_name.3 new file mode 100644 index 00000000..daab06b4 --- /dev/null +++ b/static/netbsd/man3/sqlite3_bind_parameter_name.3 @@ -0,0 +1,46 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BIND_PARAMETER_NAME 3 +.Os +.Sh NAME +.Nm sqlite3_bind_parameter_name +.Nd name of a host parameter +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_bind_parameter_name +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Sh DESCRIPTION +The sqlite3_bind_parameter_name(P,N) interface returns the name of +the N-th SQL parameter in the prepared statement +P. +SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" have +a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" respectively. +In other words, the initial ":" or "$" or "@" or "?" is included as +part of the name. +Parameters of the form "?" without a following integer have no name +and are referred to as "nameless" or "anonymous parameters". +.Pp +The first host parameter has an index of 1, not 0. +.Pp +If the value N is out of range or if the N-th parameter is nameless, +then NULL is returned. +The returned string is always in UTF-8 encoding even if the named parameter +was originally specified as UTF-16 in +.Fn sqlite3_prepare16 , +.Fn sqlite3_prepare16_v2 , +or +.Fn sqlite3_prepare16_v3 . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4720. +.Bd -literal +SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_bind_parameter_count 3 , +.Xr sqlite3_bind_parameter_index 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_blob.3 b/static/netbsd/man3/sqlite3_blob.3 new file mode 100644 index 00000000..b7a0b5f8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_blob +.Nd a handle to an open BLOB +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_blob sqlite3_blob; +.Sh DESCRIPTION +An instance of this object represents an open BLOB on which incremental BLOB I/O +can be performed. +Objects of this type are created by +.Fn sqlite3_blob_open +and destroyed by +.Fn sqlite3_blob_close . +The +.Fn sqlite3_blob_read +and +.Fn sqlite3_blob_write +interfaces can be used to read or write small subsections of the BLOB. +The +.Fn sqlite3_blob_bytes +interface returns the size of the BLOB in bytes. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7669. +.Bd -literal +typedef struct sqlite3_blob sqlite3_blob; +.Ed +.Sh SEE ALSO +.Xr sqlite3_blob_bytes 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_blob_read 3 , +.Xr sqlite3_blob_write 3 diff --git a/static/netbsd/man3/sqlite3_blob_bytes.3 b/static/netbsd/man3/sqlite3_blob_bytes.3 new file mode 100644 index 00000000..710e196f --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_bytes.3 @@ -0,0 +1,35 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_BYTES 3 +.Os +.Sh NAME +.Nm sqlite3_blob_bytes +.Nd return the size of an open BLOB +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_bytes +.Fa "sqlite3_blob *" +.Fc +.Sh DESCRIPTION +Returns the size in bytes of the BLOB accessible via the successfully +opened BLOB handle in its only argument. +The incremental blob I/O routines can only read or overwriting existing +blob content; they cannot change the size of a blob. +.Pp +This routine only works on a BLOB handle which has been +created by a prior successful call to +.Fn sqlite3_blob_open +and which has not been closed by +.Fn sqlite3_blob_close . +Passing any other pointer in to this routine results in undefined and +probably undesirable behavior. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7824. +.Bd -literal +SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); +.Ed +.Sh SEE ALSO +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_blob_open 3 diff --git a/static/netbsd/man3/sqlite3_blob_close.3 b/static/netbsd/man3/sqlite3_blob_close.3 new file mode 100644 index 00000000..c77a6f2e --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_close.3 @@ -0,0 +1,42 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_CLOSE 3 +.Os +.Sh NAME +.Nm sqlite3_blob_close +.Nd close a BLOB handle +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_close +.Fa "sqlite3_blob *" +.Fc +.Sh DESCRIPTION +This function closes an open BLOB handle. +The BLOB handle is closed unconditionally. +Even if this routine returns an error code, the handle is still closed. +.Pp +If the blob handle being closed was opened for read-write access, and +if the database is in auto-commit mode and there are no other open +read-write blob handles or active write statements, the current transaction +is committed. +If an error occurs while committing the transaction, an error code +is returned and the transaction rolled back. +.Pp +Calling this function with an argument that is not a NULL pointer or +an open blob handle results in undefined behavior. +Calling this routine with a null pointer (such as would be returned +by a failed call to +.Fn sqlite3_blob_open ) +is a harmless no-op. +Otherwise, if this function is passed a valid open blob handle, the +values returned by the sqlite3_errcode() and sqlite3_errmsg() functions +are set before returning. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7801. +.Bd -literal +SQLITE_API int sqlite3_blob_close(sqlite3_blob *); +.Ed +.Sh SEE ALSO +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_open 3 diff --git a/static/netbsd/man3/sqlite3_blob_open.3 b/static/netbsd/man3/sqlite3_blob_open.3 new file mode 100644 index 00000000..5feb3a18 --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_open.3 @@ -0,0 +1,146 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_OPEN 3 +.Os +.Sh NAME +.Nm sqlite3_blob_open +.Nd open a BLOB for incremental I/O +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_open +.Fa "sqlite3*" +.Fa "const char *zDb" +.Fa "const char *zTable" +.Fa "const char *zColumn" +.Fa "sqlite3_int64 iRow" +.Fa "int flags" +.Fa "sqlite3_blob **ppBlob" +.Fc +.Sh DESCRIPTION +This interfaces opens a handle to the BLOB located in row iRow, +column zColumn, table zTable in database zDb; in other words, the same +BLOB that would be selected by: +.Bd -literal +SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; +.Ed +.Pp +Parameter zDb is not the filename that contains the database, but rather +the symbolic name of the database. +For attached databases, this is the name that appears after the AS +keyword in the ATTACH statement. +For the main database file, the database name is "main". +For TEMP tables, the database name is "temp". +.Pp +If the flags parameter is non-zero, then the BLOB is opened for read +and write access. +If the flags parameter is zero, the BLOB is opened for read-only access. +.Pp +On success, SQLITE_OK is returned and the new BLOB handle +is stored in *ppBlob. +Otherwise an error code is returned and, unless the error +code is SQLITE_MISUSE, *ppBlob is set to NULL. +This means that, provided the API is not misused, it is always safe +to call +.Fn sqlite3_blob_close +on *ppBlob after this function it returns. +.Pp +This function fails with SQLITE_ERROR if any of the following are true: +.Bl -bullet +.It +Database zDb does not exist, +.It +Table zTable does not exist within database zDb, +.It +Table zTable is a WITHOUT ROWID table, +.It +Column zColumn does not exist, +.It +Row iRow is not present in the table, +.It +The specified column of row iRow contains a value that is not a TEXT +or BLOB value, +.It +Column zColumn is part of an index, PRIMARY KEY or UNIQUE constraint +and the blob is being opened for read/write access, +.It +Foreign key constraints are enabled, column +zColumn is part of a child key definition and the blob is +being opened for read/write access. +.El +.Pp +Unless it returns SQLITE_MISUSE, this function sets the database connection +error code and message accessible via +.Fn sqlite3_errcode +and +.Fn sqlite3_errmsg +and related functions. +.Pp +A BLOB referenced by sqlite3_blob_open() may be read using the +.Fn sqlite3_blob_read +interface and modified by using +.Fn sqlite3_blob_write . +The BLOB handle can be moved to a different row of the same +table using the +.Fn sqlite3_blob_reopen +interface. +However, the column, table, or database of a BLOB handle +cannot be changed after the BLOB handle is opened. +.Pp +If the row that a BLOB handle points to is modified by an UPDATE, +DELETE, or by ON CONFLICT side-effects then the BLOB +handle is marked as "expired". +This is true if any column of the row is changed, even a column other +than the one the BLOB handle is open on. +Calls to +.Fn sqlite3_blob_read +and +.Fn sqlite3_blob_write +for an expired BLOB handle fail with a return code of SQLITE_ABORT. +Changes written into a BLOB prior to the BLOB expiring are not rolled +back by the expiration of the BLOB. +Such changes will eventually commit if the transaction continues to +completion. +.Pp +Use the +.Fn sqlite3_blob_bytes +interface to determine the size of the opened blob. +The size of a blob may not be changed by this interface. +Use the UPDATE SQL command to change the size of a blob. +.Pp +The +.Fn sqlite3_bind_zeroblob +and +.Fn sqlite3_result_zeroblob +interfaces and the built-in zeroblob SQL function may be used +to create a zero-filled blob to read or write using the incremental-blob +interface. +.Pp +To avoid a resource leak, every open BLOB handle should +eventually be released by a call to +.Fn sqlite3_blob_close . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7683. +.Bd -literal +SQLITE_API int sqlite3_blob_open( + sqlite3*, + const char *zDb, + const char *zTable, + const char *zColumn, + sqlite3_int64 iRow, + int flags, + sqlite3_blob **ppBlob +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_bytes 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_blob_read 3 , +.Xr sqlite3_blob_reopen 3 , +.Xr sqlite3_blob_write 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_result_blob 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_blob_read.3 b/static/netbsd/man3/sqlite3_blob_read.3 new file mode 100644 index 00000000..c5927e03 --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_read.3 @@ -0,0 +1,58 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_READ 3 +.Os +.Sh NAME +.Nm sqlite3_blob_read +.Nd read data from a BLOB incrementally +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_read +.Fa "sqlite3_blob *" +.Fa "void *Z" +.Fa "int N" +.Fa "int iOffset" +.Fc +.Sh DESCRIPTION +This function is used to read data from an open BLOB handle +into a caller-supplied buffer. +N bytes of data are copied into buffer Z from the open BLOB, starting +at offset iOffset. +.Pp +If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR +is returned and no data is read. +If N or iOffset is less than zero, SQLITE_ERROR is returned +and no data is read. +The size of the blob (and hence the maximum value of N+iOffset) can +be determined using the +.Fn sqlite3_blob_bytes +interface. +.Pp +An attempt to read from an expired BLOB handle fails with +an error code of SQLITE_ABORT. +.Pp +On success, sqlite3_blob_read() returns SQLITE_OK. +Otherwise, an error code or an extended error code +is returned. +.Pp +This routine only works on a BLOB handle which has been +created by a prior successful call to +.Fn sqlite3_blob_open +and which has not been closed by +.Fn sqlite3_blob_close . +Passing any other pointer in to this routine results in undefined and +probably undesirable behavior. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7840. +.Bd -literal +SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); +.Ed +.Sh SEE ALSO +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_bytes 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_blob_write 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_blob_reopen.3 b/static/netbsd/man3/sqlite3_blob_reopen.3 new file mode 100644 index 00000000..0aa2ddf3 --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_reopen.3 @@ -0,0 +1,53 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_REOPEN 3 +.Os +.Sh NAME +.Nm sqlite3_blob_reopen +.Nd move a BLOB handle to a new row +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_reopen +.Fa "sqlite3_blob *" +.Fa "sqlite3_int64" +.Fc +.Sh DESCRIPTION +This function is used to move an existing BLOB handle so +that it points to a different row of the same database table. +The new row is identified by the rowid value passed as the second argument. +Only the row can be changed. +The database, table and column on which the blob handle is open remain +the same. +Moving an existing BLOB handle to a new row is faster than +closing the existing handle and opening a new one. +.Pp +The new row must meet the same criteria as for +.Fn sqlite3_blob_open +- it must exist and there must be either a blob or text value stored +in the nominated column. +If the new row is not present in the table, or if it does not contain +a blob or text value, or if another error occurs, an SQLite error code +is returned and the blob handle is considered aborted. +All subsequent calls to +.Fn sqlite3_blob_read , +.Fn sqlite3_blob_write +or +.Fn sqlite3_blob_reopen +on an aborted blob handle immediately return SQLITE_ABORT. +Calling +.Fn sqlite3_blob_bytes +on an aborted blob handle always returns zero. +.Pp +This function sets the database handle error code and message. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7776. +.Bd -literal +SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); +.Ed +.Sh SEE ALSO +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_bytes 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_blob_read 3 , +.Xr sqlite3_blob_write 3 diff --git a/static/netbsd/man3/sqlite3_blob_write.3 b/static/netbsd/man3/sqlite3_blob_write.3 new file mode 100644 index 00000000..5242ab67 --- /dev/null +++ b/static/netbsd/man3/sqlite3_blob_write.3 @@ -0,0 +1,77 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BLOB_WRITE 3 +.Os +.Sh NAME +.Nm sqlite3_blob_write +.Nd write data into a BLOB incrementally +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_blob_write +.Fa "sqlite3_blob *" +.Fa "const void *z" +.Fa "int n" +.Fa "int iOffset" +.Fc +.Sh DESCRIPTION +This function is used to write data into an open BLOB handle +from a caller-supplied buffer. +N bytes of data are copied from the buffer Z into the open BLOB, starting +at offset iOffset. +.Pp +On success, sqlite3_blob_write() returns SQLITE_OK. +Otherwise, an error code or an extended error code +is returned. +Unless SQLITE_MISUSE is returned, this function sets the database connection +error code and message accessible via +.Fn sqlite3_errcode +and +.Fn sqlite3_errmsg +and related functions. +.Pp +If the BLOB handle passed as the first argument was not +opened for writing (the flags parameter to +.Fn sqlite3_blob_open +was zero), this function returns SQLITE_READONLY. +.Pp +This function may only modify the contents of the BLOB; it is not possible +to increase the size of a BLOB using this API. +If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR +is returned and no data is written. +The size of the BLOB (and hence the maximum value of N+iOffset) can +be determined using the +.Fn sqlite3_blob_bytes +interface. +If N or iOffset are less than zero SQLITE_ERROR is returned +and no data is written. +.Pp +An attempt to write to an expired BLOB handle fails with +an error code of SQLITE_ABORT. +Writes to the BLOB that occurred before the BLOB handle +expired are not rolled back by the expiration of the handle, though +of course those changes might have been overwritten by the statement +that expired the BLOB handle or by other independent statements. +.Pp +This routine only works on a BLOB handle which has been +created by a prior successful call to +.Fn sqlite3_blob_open +and which has not been closed by +.Fn sqlite3_blob_close . +Passing any other pointer in to this routine results in undefined and +probably undesirable behavior. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7869. +.Bd -literal +SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_bytes 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_blob_read 3 , +.Xr sqlite3_errcode 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_busy_handler.3 b/static/netbsd/man3/sqlite3_busy_handler.3 new file mode 100644 index 00000000..3ce2ae41 --- /dev/null +++ b/static/netbsd/man3/sqlite3_busy_handler.3 @@ -0,0 +1,82 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BUSY_HANDLER 3 +.Os +.Sh NAME +.Nm sqlite3_busy_handler +.Nd register a callback to handle SQLITE_BUSY errors +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_busy_handler +.Fa "sqlite3*" +.Fa "int(*)(void*,int)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_busy_handler(D,X,P) routine sets a callback function X +that might be invoked with argument P whenever an attempt is made to +access a database table associated with database connection +D when another thread or process has the table locked. +The sqlite3_busy_handler() interface is used to implement +.Fn sqlite3_busy_timeout +and PRAGMA busy_timeout. +.Pp +If the busy callback is NULL, then SQLITE_BUSY is returned +immediately upon encountering the lock. +If the busy callback is not NULL, then the callback might be invoked +with two arguments. +.Pp +The first argument to the busy handler is a copy of the void* pointer +which is the third argument to sqlite3_busy_handler(). +The second argument to the busy handler callback is the number of times +that the busy handler has been invoked previously for the same locking +event. +If the busy callback returns 0, then no additional attempts are made +to access the database and SQLITE_BUSY is returned to the +application. +If the callback returns non-zero, then another attempt is made to access +the database and the cycle repeats. +.Pp +The presence of a busy handler does not guarantee that it will be invoked +when there is lock contention. +If SQLite determines that invoking the busy handler could result in +a deadlock, it will go ahead and return SQLITE_BUSY to the +application instead of invoking the busy handler. +Consider a scenario where one process is holding a read lock that it +is trying to promote to a reserved lock and a second process is holding +a reserved lock that it is trying to promote to an exclusive lock. +The first process cannot proceed because it is blocked by the second +and the second process cannot proceed because it is blocked by the +first. +If both processes invoke the busy handlers, neither will make any progress. +Therefore, SQLite returns SQLITE_BUSY for the first process, +hoping that this will induce the first process to release its read +lock and allow the second process to proceed. +.Pp +The default busy callback is NULL. +.Pp +There can only be a single busy handler defined for each database connection. +Setting a new busy handler clears any previously set handler. +Note that calling +.Fn sqlite3_busy_timeout +or evaluating PRAGMA busy_timeout=N will change +the busy handler and thus clear any previously set busy handler. +.Pp +The busy callback should not take any actions which modify the database +connection that invoked the busy handler. +In other words, the busy handler is not reentrant. +Any such actions result in undefined behavior. +.Pp +A busy handler must not close the database connection or prepared statement +that invoked the busy handler. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2781. +.Bd -literal +SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_busy_timeout 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_busy_timeout.3 b/static/netbsd/man3/sqlite3_busy_timeout.3 new file mode 100644 index 00000000..8db08339 --- /dev/null +++ b/static/netbsd/man3/sqlite3_busy_timeout.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BUSY_TIMEOUT 3 +.Os +.Sh NAME +.Nm sqlite3_busy_timeout +.Nd set a busy timeout +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_busy_timeout +.Fa "sqlite3*" +.Fa "int ms" +.Fc +.Sh DESCRIPTION +This routine sets a busy handler that sleeps for a specified +amount of time when a table is locked. +The handler will sleep multiple times until at least "ms" milliseconds +of sleeping have accumulated. +After at least "ms" milliseconds of sleeping, the handler returns 0 +which causes +.Fn sqlite3_step +to return SQLITE_BUSY. +.Pp +Calling this routine with an argument less than or equal to zero turns +off all busy handlers. +.Pp +There can only be a single busy handler for a particular database connection +at any given moment. +If another busy handler was defined (using +.Fn sqlite3_busy_handler ) +prior to calling this routine, that other busy handler is cleared. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2842. +.Bd -literal +SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_busy_handler 3 , +.Xr sqlite3_step 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_cancel_auto_extension.3 b/static/netbsd/man3/sqlite3_cancel_auto_extension.3 new file mode 100644 index 00000000..bd4bb1f6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_cancel_auto_extension.3 @@ -0,0 +1,25 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CANCEL_AUTO_EXTENSION 3 +.Os +.Sh NAME +.Nm sqlite3_cancel_auto_extension +.Nd cancel automatic extension loading +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_cancel_auto_extension +.Fa "void(*xEntryPoint)(void)" +.Fc +.Sh DESCRIPTION +The sqlite3_cancel_auto_extension(X) +interface unregisters the initialization routine X that was registered +using a prior call to sqlite3_auto_extension(X). +The sqlite3_cancel_auto_extension(X) +routine returns 1 if initialization routine X was successfully unregistered +and it returns 0 if X was not on the list of initialization routines. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7245. +.Bd -literal +SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); +.Ed diff --git a/static/netbsd/man3/sqlite3_changegroup.3 b/static/netbsd/man3/sqlite3_changegroup.3 new file mode 100644 index 00000000..fca88deb --- /dev/null +++ b/static/netbsd/man3/sqlite3_changegroup.3 @@ -0,0 +1,18 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CHANGEGROUP 3 +.Os +.Sh NAME +.Nm sqlite3_changegroup +.Nd changegroup handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_changegroup sqlite3_changegroup; +.Sh DESCRIPTION +A changegroup is an object used to combine two or more changesets +or patchsets +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11822. +.Bd -literal +typedef struct sqlite3_changegroup sqlite3_changegroup; +.Ed diff --git a/static/netbsd/man3/sqlite3_changes.3 b/static/netbsd/man3/sqlite3_changes.3 new file mode 100644 index 00000000..47762169 --- /dev/null +++ b/static/netbsd/man3/sqlite3_changes.3 @@ -0,0 +1,77 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CHANGES 3 +.Os +.Sh NAME +.Nm sqlite3_changes , +.Nm sqlite3_changes64 +.Nd count the number of rows modified +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_changes +.Fa "sqlite3*" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_changes64 +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +These functions return the number of rows modified, inserted or deleted +by the most recently completed INSERT, UPDATE or DELETE statement on +the database connection specified by the only parameter. +The two functions are identical except for the type of the return value +and that if the number of rows modified by the most recent INSERT, +UPDATE or DELETE is greater than the maximum value supported by type +"int", then the return value of sqlite3_changes() is undefined. +Executing any other type of SQL statement does not modify the value +returned by these functions. +.Pp +Only changes made directly by the INSERT, UPDATE or DELETE statement +are considered - auxiliary changes caused by triggers, foreign key actions +or REPLACE constraint resolution are not counted. +.Pp +Changes to a view that are intercepted by INSTEAD OF triggers +are not counted. +The value returned by sqlite3_changes() immediately after an INSERT, +UPDATE or DELETE statement run on a view is always zero. +Only changes made to real tables are counted. +.Pp +Things are more complicated if the sqlite3_changes() function is executed +while a trigger program is running. +This may happen if the program uses the changes() SQL function, +or if some other callback function invokes sqlite3_changes() directly. +Essentially: +.Bl -bullet +.It +Before entering a trigger program the value returned by sqlite3_changes() +function is saved. +After the trigger program has finished, the original value is restored. +.It +Within a trigger program each INSERT, UPDATE and DELETE statement sets +the value returned by sqlite3_changes() upon completion as normal. +Of course, this value will not include any changes performed by sub-triggers, +as the sqlite3_changes() value will be saved and restored after each +sub-trigger has run. +.El +.Pp +This means that if the changes() SQL function (or similar) is used +by the first INSERT, UPDATE or DELETE statement within a trigger, it +returns the value as set when the calling statement began executing. +If it is used by the second or subsequent such statement within a trigger +program, the value returned reflects the number of rows modified by +the previous INSERT, UPDATE or DELETE statement within the same trigger. +.Pp +If a separate thread makes changes on the same database connection +while +.Fn sqlite3_changes +is running then the value returned is unpredictable and not meaningful. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2599. +.Bd -literal +SQLITE_API int sqlite3_changes(sqlite3*); +SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_total_changes 3 diff --git a/static/netbsd/man3/sqlite3_changeset_iter.3 b/static/netbsd/man3/sqlite3_changeset_iter.3 new file mode 100644 index 00000000..64cd5ae2 --- /dev/null +++ b/static/netbsd/man3/sqlite3_changeset_iter.3 @@ -0,0 +1,18 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CHANGESET_ITER 3 +.Os +.Sh NAME +.Nm sqlite3_changeset_iter +.Nd changeset iterator handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_changeset_iter sqlite3_changeset_iter; +.Sh DESCRIPTION +An instance of this object acts as a cursor for iterating over the +elements of a changeset or patchset. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10945. +.Bd -literal +typedef struct sqlite3_changeset_iter sqlite3_changeset_iter; +.Ed diff --git a/static/netbsd/man3/sqlite3_clear_bindings.3 b/static/netbsd/man3/sqlite3_clear_bindings.3 new file mode 100644 index 00000000..8314c8fc --- /dev/null +++ b/static/netbsd/man3/sqlite3_clear_bindings.3 @@ -0,0 +1,27 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CLEAR_BINDINGS 3 +.Os +.Sh NAME +.Nm sqlite3_clear_bindings +.Nd reset all bindings on a prepared statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_clear_bindings +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +Contrary to the intuition of many, +.Fn sqlite3_reset +does not reset the bindings on a prepared statement. +Use this routine to reset all host parameters to NULL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4766. +.Bd -literal +SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_close.3 b/static/netbsd/man3/sqlite3_close.3 new file mode 100644 index 00000000..c273145a --- /dev/null +++ b/static/netbsd/man3/sqlite3_close.3 @@ -0,0 +1,73 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CLOSE 3 +.Os +.Sh NAME +.Nm sqlite3_close , +.Nm sqlite3_close_v2 +.Nd closing a database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_close +.Fa "sqlite3*" +.Fc +.Ft int +.Fo sqlite3_close_v2 +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +The sqlite3_close() and sqlite3_close_v2() routines are destructors +for the sqlite3 object. +Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK +if the sqlite3 object is successfully destroyed and all associated +resources are deallocated. +.Pp +Ideally, applications should finalize all prepared statements, +close all BLOB handles, and finish all sqlite3_backup +objects associated with the sqlite3 object prior to attempting +to close the object. +If the database connection is associated with unfinalized prepared +statements, BLOB handlers, and/or unfinished sqlite3_backup objects +then sqlite3_close() will leave the database connection open and return +SQLITE_BUSY. +If sqlite3_close_v2() is called with unfinalized prepared statements, +unclosed BLOB handlers, and/or unfinished sqlite3_backups, it returns +SQLITE_OK regardless, but instead of deallocating the database +connection immediately, it marks the database connection as an unusable +"zombie" and makes arrangements to automatically deallocate the database +connection after all prepared statements are finalized, all BLOB handles +are closed, and all backups have finished. +The sqlite3_close_v2() interface is intended for use with host languages +that are garbage collected, and where the order in which destructors +are called is arbitrary. +.Pp +If an sqlite3 object is destroyed while a transaction is open, +the transaction is automatically rolled back. +.Pp +The C parameter to sqlite3_close(C) and sqlite3_close_v2(C) +must be either a NULL pointer or an sqlite3 object pointer obtained +from +.Fn sqlite3_open , +.Fn sqlite3_open16 , +or +.Fn sqlite3_open_v2 , +and not previously closed. +Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer argument +is a harmless no-op. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 316. +.Bd -literal +SQLITE_API int sqlite3_close(sqlite3*); +SQLITE_API int sqlite3_close_v2(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_backup 3 , +.Xr sqlite3_backup_init 3 , +.Xr sqlite3_blob 3 , +.Xr sqlite3_blob_close 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_collation_needed.3 b/static/netbsd/man3/sqlite3_collation_needed.3 new file mode 100644 index 00000000..1eb17e8f --- /dev/null +++ b/static/netbsd/man3/sqlite3_collation_needed.3 @@ -0,0 +1,66 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLLATION_NEEDED 3 +.Os +.Sh NAME +.Nm sqlite3_collation_needed , +.Nm sqlite3_collation_needed16 +.Nd collation needed callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_collation_needed +.Fa "sqlite3*" +.Fa "void*" +.Fa "void(*)(void*,sqlite3*,int eTextRep,const char*)" +.Fc +.Ft int +.Fo sqlite3_collation_needed16 +.Fa "sqlite3*" +.Fa "void*" +.Fa "void(*)(void*,sqlite3*,int eTextRep,const void*)" +.Fc +.Sh DESCRIPTION +To avoid having to register all collation sequences before a database +can be used, a single callback function may be registered with the +database connection to be invoked whenever an undefined +collation sequence is required. +.Pp +If the function is registered using the sqlite3_collation_needed() +API, then it is passed the names of undefined collation sequences as +strings encoded in UTF-8. +If sqlite3_collation_needed16() is used, the names are passed as UTF-16 +in machine native byte order. +A call to either function replaces the existing collation-needed callback. +.Pp +When the callback is invoked, the first argument passed is a copy of +the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). +The second argument is the database connection. +The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, +or SQLITE_UTF16LE, indicating the most desirable form +of the collation sequence function required. +The fourth parameter is the name of the required collation sequence. +.Pp +The callback function should register the desired collation using +.Fn sqlite3_create_collation , +.Fn sqlite3_create_collation16 , +or +.Fn sqlite3_create_collation_v2 . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6350. +.Bd -literal +SQLITE_API int sqlite3_collation_needed( + sqlite3*, + void*, + void(*)(void*,sqlite3*,int eTextRep,const char*) +); +SQLITE_API int sqlite3_collation_needed16( + sqlite3*, + void*, + void(*)(void*,sqlite3*,int eTextRep,const void*) +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_create_collation 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_column_blob.3 b/static/netbsd/man3/sqlite3_column_blob.3 new file mode 100644 index 00000000..38c2cf92 --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_blob.3 @@ -0,0 +1,356 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLUMN_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_column_blob , +.Nm sqlite3_column_double , +.Nm sqlite3_column_int , +.Nm sqlite3_column_int64 , +.Nm sqlite3_column_text , +.Nm sqlite3_column_text16 , +.Nm sqlite3_column_value , +.Nm sqlite3_column_bytes , +.Nm sqlite3_column_bytes16 , +.Nm sqlite3_column_type +.Nd result values from a query +.Sh SYNOPSIS +.In sqlite3.h +.Ft const void * +.Fo sqlite3_column_blob +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft double +.Fo sqlite3_column_double +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft int +.Fo sqlite3_column_int +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_column_int64 +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft const unsigned char * +.Fo sqlite3_column_text +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft const void * +.Fo sqlite3_column_text16 +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft sqlite3_value * +.Fo sqlite3_column_value +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft int +.Fo sqlite3_column_bytes +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft int +.Fo sqlite3_column_bytes16 +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Ft int +.Fo sqlite3_column_type +.Fa "sqlite3_stmt*" +.Fa "int iCol" +.Fc +.Sh DESCRIPTION +\fBSummary:\fP +.Bd -ragged +.Pp + \fBsqlite3_column_blob\fP \(-> BLOB result + \fBsqlite3_column_double\fP \(-> REAL result + \fBsqlite3_column_int\fP \(-> 32-bit INTEGER result + \fBsqlite3_column_int64\fP \(-> 64-bit INTEGER result + \fBsqlite3_column_text\fP \(-> UTF-8 TEXT result + \fBsqlite3_column_text16\fP \(-> UTF-16 TEXT result + \fBsqlite3_column_value\fP \(-> The result as an unprotected sqlite3_value +object. + + \fBsqlite3_column_bytes\fP \(-> Size of a BLOB or a UTF-8 TEXT result in bytes + \fBsqlite3_column_bytes16 \fP \(-> Size of UTF-16 TEXT in bytes + \fBsqlite3_column_type\fP \(-> Default datatype of the result +.Pp +.Ed +.Pp +\fBDetails:\fP +.Pp +These routines return information about a single column of the current +result row of a query. +In every case the first argument is a pointer to the prepared statement +that is being evaluated (the sqlite3_stmt* that was returned +from +.Fn sqlite3_prepare_v2 +or one of its variants) and the second argument is the index of the +column for which information should be returned. +The leftmost column of the result set has the index 0. +The number of columns in the result can be determined using +.Fn sqlite3_column_count . +If the SQL statement does not currently point to a valid row, or if +the column index is out of range, the result is undefined. +These routines may only be called when the most recent call to +.Fn sqlite3_step +has returned SQLITE_ROW and neither +.Fn sqlite3_reset +nor +.Fn sqlite3_finalize +have been called subsequently. +If any of these routines are called after +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +or after +.Fn sqlite3_step +has returned something other than SQLITE_ROW, the results +are undefined. +If +.Fn sqlite3_step +or +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +are called from a different thread while any of these routines are +pending, then the results are undefined. +.Pp +The first six interfaces (_blob, _double, _int, _int64, _text, and +_text16) each return the value of a result column in a specific data +format. +If the result column is not initially in the requested format (for +example, if the query returns an integer but the sqlite3_column_text() +interface is used to extract the value) then an automatic type conversion +is performed. +.Pp +The sqlite3_column_type() routine returns the datatype code +for the initial data type of the result column. +The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, +SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. +The return value of sqlite3_column_type() can be used to decide which +of the first six interface should be used to extract the column value. +The value returned by sqlite3_column_type() is only meaningful if no +automatic type conversions have occurred for the value in question. +After a type conversion, the result of calling sqlite3_column_type() +is undefined, though harmless. +Future versions of SQLite may change the behavior of sqlite3_column_type() +following a type conversion. +.Pp +If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes() +or sqlite3_column_bytes16() interfaces can be used to determine the +size of that BLOB or string. +.Pp +If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() +routine returns the number of bytes in that BLOB or string. +If the result is a UTF-16 string, then sqlite3_column_bytes() converts +the string to UTF-8 and then returns the number of bytes. +If the result is a numeric value then sqlite3_column_bytes() uses +.Fn sqlite3_snprintf +to convert that value to a UTF-8 string and returns the number of bytes +in that string. +If the result is NULL, then sqlite3_column_bytes() returns zero. +.Pp +If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() +routine returns the number of bytes in that BLOB or string. +If the result is a UTF-8 string, then sqlite3_column_bytes16() converts +the string to UTF-16 and then returns the number of bytes. +If the result is a numeric value then sqlite3_column_bytes16() uses +.Fn sqlite3_snprintf +to convert that value to a UTF-16 string and returns the number of +bytes in that string. +If the result is NULL, then sqlite3_column_bytes16() returns zero. +.Pp +The values returned by +.Fn sqlite3_column_bytes +and +.Fn sqlite3_column_bytes16 +do not include the zero terminators at the end of the string. +For clarity: the values returned by +.Fn sqlite3_column_bytes +and +.Fn sqlite3_column_bytes16 +are the number of bytes in the string, not the number of characters. +.Pp +Strings returned by sqlite3_column_text() and sqlite3_column_text16(), +even empty strings, are always zero-terminated. +The return value from sqlite3_column_blob() for a zero-length BLOB +is a NULL pointer. +.Pp +Strings returned by sqlite3_column_text16() always have the endianness +which is native to the platform, regardless of the text encoding set +for the database. +.Pp +\fBWarning:\fP The object returned by +.Fn sqlite3_column_value +is an unprotected sqlite3_value object. +In a multithreaded environment, an unprotected sqlite3_value object +may only be used safely with +.Fn sqlite3_bind_value +and +.Fn sqlite3_result_value . +If the unprotected sqlite3_value object returned +by +.Fn sqlite3_column_value +is used in any other way, including calls to routines like +.Fn sqlite3_value_int , +.Fn sqlite3_value_text , +or +.Fn sqlite3_value_bytes , +the behavior is not threadsafe. +Hence, the sqlite3_column_value() interface is normally only useful +within the implementation of application-defined SQL functions +or virtual tables, not within top-level application code. +.Pp +These routines may attempt to convert the datatype of the result. +For example, if the internal representation is FLOAT and a text result +is requested, +.Fn sqlite3_snprintf +is used internally to perform the conversion automatically. +The following table details the conversions that are applied: +.Bd -ragged +.Pp + Internal Type Requested Type Conversion + NULL INTEGER Result is 0 + NULL FLOAT Result is 0.0 + NULL TEXT Result is a NULL pointer + NULL BLOB Result is a NULL pointer + INTEGER FLOAT Convert from integer to float + INTEGER TEXT ASCII rendering of the integer + INTEGER BLOB Same as INTEGER->TEXT + FLOAT INTEGER CAST to INTEGER + FLOAT TEXT ASCII rendering of the float + FLOAT BLOB CAST to BLOB + TEXT INTEGER CAST to INTEGER + TEXT FLOAT CAST to REAL + TEXT BLOB No change + BLOB INTEGER CAST to INTEGER + BLOB FLOAT CAST to REAL + BLOB TEXT CAST to TEXT, ensure zero terminator +.Pp +.Ed +.Pp +Note that when type conversions occur, pointers returned by prior calls +to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() +may be invalidated. +Type conversions and pointer invalidations might occur in the following +cases: +.Bl -bullet +.It +The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() +is called. +A zero-terminator might need to be added to the string. +.It +The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() +is called. +The content must be converted to UTF-16. +.It +The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() +is called. +The content must be converted to UTF-8. +.El +.Pp +Conversions between UTF-16be and UTF-16le are always done in place +and do not invalidate a prior pointer, though of course the content +of the buffer that the prior pointer references will have been modified. +Other kinds of conversion are done in place when it is possible, but +sometimes they are not possible and in those cases prior pointers are +invalidated. +.Pp +The safest policy is to invoke these routines in one of the following +ways: +.Bl -bullet +.It +sqlite3_column_text() followed by sqlite3_column_bytes() +.It +sqlite3_column_blob() followed by sqlite3_column_bytes() +.It +sqlite3_column_text16() followed by sqlite3_column_bytes16() +.El +.Pp +In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), +or sqlite3_column_text16() first to force the result into the desired +format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() +to find the size of the result. +Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() +with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() +with calls to sqlite3_column_bytes(). +.Pp +The pointers returned are valid until a type conversion occurs as described +above, or until +.Fn sqlite3_step +or +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +is called. +The memory space used to hold strings and BLOBs is freed automatically. +Do not pass the pointers returned from +.Fn sqlite3_column_blob , +.Fn sqlite3_column_text , +etc. +into +.Fn sqlite3_free . +As long as the input parameters are correct, these routines will only +fail if an out-of-memory error occurs during a format conversion. +Only the following subset of interfaces are subject to out-of-memory +errors: +.Bl -bullet +.It +sqlite3_column_blob() +.It +sqlite3_column_text() +.It +sqlite3_column_text16() +.It +sqlite3_column_bytes() +.It +sqlite3_column_bytes16() +.El +.Pp +If an out-of-memory error occurs, then the return value from these +routines is the same as if the column had contained an SQL NULL value. +Valid SQL NULL returns can be distinguished from out-of-memory errors +by invoking the +.Fn sqlite3_errcode +immediately after the suspect return value is obtained and before any +other SQLite interface is called on the same database connection. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5041. +.Bd -literal +SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); +SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); +SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); +SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); +SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); +SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_column_count 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mprintf 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_result_blob 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_value_blob 3 , +.Xr SQLITE_INTEGER 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_column_count.3 b/static/netbsd/man3/sqlite3_column_count.3 new file mode 100644 index 00000000..8f44d66a --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_count.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLUMN_COUNT 3 +.Os +.Sh NAME +.Nm sqlite3_column_count +.Nd number of columns in a result set +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_column_count +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +Return the number of columns in the result set returned by the prepared statement. +If this routine returns 0, that means the prepared statement +returns no data (for example an UPDATE). +However, just because this routine returns a positive number does not +mean that one or more rows of data will be returned. +A SELECT statement will always have a positive sqlite3_column_count() +but depending on the WHERE clause constraints and the table content, +it might return no rows. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4776. +.Bd -literal +SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3_data_count 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_column_database_name.3 b/static/netbsd/man3/sqlite3_column_database_name.3 new file mode 100644 index 00000000..56c54e6d --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_database_name.3 @@ -0,0 +1,100 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLUMN_DATABASE_NAME 3 +.Os +.Sh NAME +.Nm sqlite3_column_database_name , +.Nm sqlite3_column_database_name16 , +.Nm sqlite3_column_table_name , +.Nm sqlite3_column_table_name16 , +.Nm sqlite3_column_origin_name , +.Nm sqlite3_column_origin_name16 +.Nd source of data in a query result +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_column_database_name +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const void * +.Fo sqlite3_column_database_name16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const char * +.Fo sqlite3_column_table_name +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const void * +.Fo sqlite3_column_table_name16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const char * +.Fo sqlite3_column_origin_name +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const void * +.Fo sqlite3_column_origin_name16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Sh DESCRIPTION +These routines provide a means to determine the database, table, and +table column that is the origin of a particular result column in SELECT +statement. +The name of the database or table or column can be returned as either +a UTF-8 or UTF-16 string. +The _database_ routines return the database name, the _table_ routines +return the table name, and the origin_ routines return the column name. +The returned string is valid until the prepared statement +is destroyed using +.Fn sqlite3_finalize +or until the statement is automatically reprepared by the first call +to +.Fn sqlite3_step +for a particular run or until the same information is requested again +in a different encoding. +.Pp +The names returned are the original un-aliased names of the database, +table, and column. +.Pp +The first argument to these interfaces is a prepared statement. +These functions return information about the Nth result column returned +by the statement, where N is the second function argument. +The left-most column is column 0 for these routines. +.Pp +If the Nth column returned by the statement is an expression or subquery +and is not a column value, then all of these functions return NULL. +These routines might also return NULL if a memory allocation error +occurs. +Otherwise, they return the name of the attached database, table, or +column that query result column was extracted from. +.Pp +As with all other SQLite APIs, those whose names end with "16" return +UTF-16 encoded strings and the other functions return UTF-8. +.Pp +These APIs are only available if the library was compiled with the +SQLITE_ENABLE_COLUMN_METADATA C-preprocessor +symbol. +.Pp +If two or more threads call one or more column metadata interfaces +for the same prepared statement and result column +at the same time then the results are undefined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4822. +.Bd -literal +SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); +SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int); +SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int); +SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int); +SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); +SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_column_decltype.3 b/static/netbsd/man3/sqlite3_column_decltype.3 new file mode 100644 index 00000000..4ef3eaa6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_decltype.3 @@ -0,0 +1,55 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLUMN_DECLTYPE 3 +.Os +.Sh NAME +.Nm sqlite3_column_decltype , +.Nm sqlite3_column_decltype16 +.Nd declared datatype of a query result +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_column_decltype +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft const void * +.Fo sqlite3_column_decltype16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Sh DESCRIPTION +The first parameter is a prepared statement. +If this statement is a SELECT statement and the Nth column of +the returned result set of that SELECT is a table column (not +an expression or subquery) then the declared type of the table column +is returned. +If the Nth column of the result set is an expression or subquery, then +a NULL pointer is returned. +The returned string is always UTF-8 encoded. +.Pp +For example, given the database schema: +.Pp +CREATE TABLE t1(c1 VARIANT); +.Pp +and the following statement to be compiled: +.Pp +SELECT c1 + 1, c1 FROM t1; +.Pp +this routine would return the string "VARIANT" for the second result +column (i==1), and a NULL pointer for the first result column (i==0). +.Pp +SQLite uses dynamic run-time typing. +So just because a column is declared to contain a particular type does +not mean that the data stored in that column is of the declared type. +SQLite is strongly typed, but the typing is dynamic not static. +Type is associated with individual values, not with the containers +used to hold those values. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4871. +.Bd -literal +SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); +SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_column_name.3 b/static/netbsd/man3/sqlite3_column_name.3 new file mode 100644 index 00000000..be28cd87 --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_name.3 @@ -0,0 +1,58 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COLUMN_NAME 3 +.Os +.Sh NAME +.Nm sqlite3_column_name , +.Nm sqlite3_column_name16 +.Nd column names in a result set +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_column_name +.Fa "sqlite3_stmt*" +.Fa "int N" +.Fc +.Ft const void * +.Fo sqlite3_column_name16 +.Fa "sqlite3_stmt*" +.Fa "int N" +.Fc +.Sh DESCRIPTION +These routines return the name assigned to a particular column in the +result set of a SELECT statement. +The sqlite3_column_name() interface returns a pointer to a zero-terminated +UTF-8 string and sqlite3_column_name16() returns a pointer to a zero-terminated +UTF-16 string. +The first parameter is the prepared statement that +implements the SELECT statement. +The second parameter is the column number. +The leftmost column is number 0. +.Pp +The returned string pointer is valid until either the prepared statement +is destroyed by +.Fn sqlite3_finalize +or until the statement is automatically reprepared by the first call +to +.Fn sqlite3_step +for a particular run or until the next call to sqlite3_column_name() +or sqlite3_column_name16() on the same column. +.Pp +If sqlite3_malloc() fails during the processing of either routine (for +example during a conversion from UTF-8 to UTF-16) then a NULL pointer +is returned. +.Pp +The name of a result column is the value of the "AS" clause for that +column, if there is an AS clause. +If there is no AS clause then the name of the column is unspecified +and may change from one release of SQLite to the next. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4792. +.Bd -literal +SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); +SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_commit_hook.3 b/static/netbsd/man3/sqlite3_commit_hook.3 new file mode 100644 index 00000000..53c26578 --- /dev/null +++ b/static/netbsd/man3/sqlite3_commit_hook.3 @@ -0,0 +1,84 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COMMIT_HOOK 3 +.Os +.Sh NAME +.Nm sqlite3_commit_hook , +.Nm sqlite3_rollback_hook +.Nd commit and rollback notification callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_commit_hook +.Fa "sqlite3*" +.Fa "int(*)(void*)" +.Fa "void*" +.Fc +.Ft void * +.Fo sqlite3_rollback_hook +.Fa "sqlite3*" +.Fa "void(*)(void *)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_commit_hook() interface registers a callback function to +be invoked whenever a transaction is committed. +Any callback set by a previous call to sqlite3_commit_hook() for the +same database connection is overridden. +The sqlite3_rollback_hook() interface registers a callback function +to be invoked whenever a transaction is rolled back. +Any callback set by a previous call to sqlite3_rollback_hook() for +the same database connection is overridden. +The pArg argument is passed through to the callback. +If the callback on a commit hook function returns non-zero, then the +commit is converted into a rollback. +.Pp +The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions +return the P argument from the previous call of the same function on +the same database connection D, or NULL for the +first call for each function on D. +.Pp +The commit and rollback hook callbacks are not reentrant. +The callback implementation must not do anything that will modify the +database connection that invoked the callback. +Any actions to modify the database connection must be deferred until +after the completion of the +.Fn sqlite3_step +call that triggered the commit or rollback hook in the first place. +Note that running any other SQL statements, including SELECT statements, +or merely calling +.Fn sqlite3_prepare_v2 +and +.Fn sqlite3_step +will modify the database connections for the meaning of "modify" in +this paragraph. +.Pp +Registering a NULL function disables the callback. +.Pp +When the commit hook callback routine returns zero, the COMMIT +operation is allowed to continue normally. +If the commit hook returns non-zero, then the COMMIT is converted +into a ROLLBACK. +The rollback hook is invoked on a rollback that results from a commit +hook returning non-zero, just as it would be with any other rollback. +.Pp +For the purposes of this API, a transaction is said to have been rolled +back if an explicit "ROLLBACK" statement is executed, or an error or +constraint causes an implicit rollback to occur. +The rollback callback is not invoked if a transaction is automatically +rolled back because the database connection is closed. +.Pp +See also the +.Fn sqlite3_update_hook +interface. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6722. +.Bd -literal +SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); +SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_update_hook 3 diff --git a/static/netbsd/man3/sqlite3_compileoption_used.3 b/static/netbsd/man3/sqlite3_compileoption_used.3 new file mode 100644 index 00000000..b4e90ba9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_compileoption_used.3 @@ -0,0 +1,48 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COMPILEOPTION_USED 3 +.Os +.Sh NAME +.Nm sqlite3_compileoption_used , +.Nm sqlite3_compileoption_get , +.Nm sqlite3_compileoption_used(X) , +.Nm sqlite3_compileoption_get(X) +.Nd run-Time library compilation options diagnostics +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_compileoption_used +.Fa "const char *zOptName" +.Fc +.Ft const char * +.Fo sqlite3_compileoption_get +.Fa "int N" +.Fc +.Fd #define sqlite3_compileoption_used(X) +.Fd #define sqlite3_compileoption_get(X) +.Sh DESCRIPTION +The sqlite3_compileoption_used() function returns 0 or 1 indicating +whether the specified option was defined at compile time. +The SQLITE_ prefix may be omitted from the option name passed to sqlite3_compileoption_used(). +.Pp +The sqlite3_compileoption_get() function allows iterating over the +list of options that were defined at compile time by returning the +N-th compile time option string. +If N is out of range, sqlite3_compileoption_get() returns a NULL pointer. +The SQLITE_ prefix is omitted from any strings returned by sqlite3_compileoption_get(). +.Pp +Support for the diagnostic functions sqlite3_compileoption_used() and +sqlite3_compileoption_get() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS +option at compile time. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 191. +.Bd -literal +#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS +SQLITE_API int sqlite3_compileoption_used(const char *zOptName); +SQLITE_API const char *sqlite3_compileoption_get(int N); +#else +# define sqlite3_compileoption_used(X) 0 +# define sqlite3_compileoption_get(X) ((void*)0) +#endif +.Ed diff --git a/static/netbsd/man3/sqlite3_complete.3 b/static/netbsd/man3/sqlite3_complete.3 new file mode 100644 index 00000000..57a53bef --- /dev/null +++ b/static/netbsd/man3/sqlite3_complete.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_COMPLETE 3 +.Os +.Sh NAME +.Nm sqlite3_complete , +.Nm sqlite3_complete16 +.Nd determine if an SQL statement is complete +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_complete +.Fa "const char *sql" +.Fc +.Ft int +.Fo sqlite3_complete16 +.Fa "const void *sql" +.Fc +.Sh DESCRIPTION +These routines are useful during command-line input to determine if +the currently entered text seems to form a complete SQL statement or +if additional input is needed before sending the text into SQLite for +parsing. +These routines return 1 if the input string appears to be a complete +SQL statement. +A statement is judged to be complete if it ends with a semicolon token +and is not a prefix of a well-formed CREATE TRIGGER statement. +Semicolons that are embedded within string literals or quoted identifier +names or comments are not independent tokens (they are part of the +token in which they are embedded) and thus do not count as a statement +terminator. +Whitespace and comments that follow the final semicolon are ignored. +.Pp +These routines return 0 if the statement is incomplete. +If a memory allocation fails, then SQLITE_NOMEM is returned. +.Pp +These routines do not parse the SQL statements thus will not detect +syntactically incorrect SQL. +.Pp +If SQLite has not been initialized using +.Fn sqlite3_initialize +prior to invoking sqlite3_complete16() then sqlite3_initialize() is +invoked automatically by sqlite3_complete16(). +If that initialization fails, then the return value from sqlite3_complete16() +will be non-zero regardless of whether or not the input SQL is complete. +.Pp +The input to +.Fn sqlite3_complete +must be a zero-terminated UTF-8 string. +.Pp +The input to +.Fn sqlite3_complete16 +must be a zero-terminated UTF-16 string in native byte order. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2745. +.Bd -literal +SQLITE_API int sqlite3_complete(const char *sql); +SQLITE_API int sqlite3_complete16(const void *sql); +.Ed +.Sh SEE ALSO +.Xr sqlite3_initialize 3 diff --git a/static/netbsd/man3/sqlite3_config.3 b/static/netbsd/man3/sqlite3_config.3 new file mode 100644 index 00000000..f0082fb1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_config.3 @@ -0,0 +1,59 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CONFIG 3 +.Os +.Sh NAME +.Nm sqlite3_config +.Nd configuring the SQLite library +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_config +.Fa "int" +.Fa "..." +.Fc +.Sh DESCRIPTION +The sqlite3_config() interface is used to make global configuration +changes to SQLite in order to tune SQLite to the specific needs of +the application. +The default configuration is recommended for most applications and +so this routine is usually not necessary. +It is provided to support rare applications with unusual needs. +.Pp +\fBThe sqlite3_config() interface is not threadsafe. +The application must ensure that no other SQLite interfaces are invoked +by other threads while sqlite3_config() is running.\fP +.Pp +The first argument to sqlite3_config() is an integer configuration option +that determines what property of SQLite is to be configured. +Subsequent arguments vary depending on the configuration option +in the first argument. +.Pp +For most configuration options, the sqlite3_config() interface may +only be invoked prior to library initialization using +.Fn sqlite3_initialize +or after shutdown by +.Fn sqlite3_shutdown . +The exceptional configuration options that may be invoked at any time +are called "anytime configuration options". +If sqlite3_config() is called after +.Fn sqlite3_initialize +and before +.Fn sqlite3_shutdown +with a first argument that is not an anytime configuration option, +then the sqlite3_config() call will return SQLITE_MISUSE. +Note, however, that sqlite3_config() can be called as part of the implementation +of an application-defined +.Fn sqlite3_os_init . +When a configuration option is set, sqlite3_config() returns SQLITE_OK. +If the option is unknown or SQLite is unable to set the option then +this routine returns a non-zero error code. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1647. +.Bd -literal +SQLITE_API int sqlite3_config(int, ...); +.Ed +.Sh SEE ALSO +.Xr sqlite3_initialize 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_context.3 b/static/netbsd/man3/sqlite3_context.3 new file mode 100644 index 00000000..c09b6d19 --- /dev/null +++ b/static/netbsd/man3/sqlite3_context.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CONTEXT 3 +.Os +.Sh NAME +.Nm sqlite3_context +.Nd SQL function context object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_context sqlite3_context; +.Sh DESCRIPTION +The context in which an SQL function executes is stored in an sqlite3_context +object. +A pointer to an sqlite3_context object is always first parameter to +application-defined SQL functions. +The application-defined SQL function implementation will pass this +pointer through into calls to sqlite3_result(), +.Fn sqlite3_aggregate_context , +.Fn sqlite3_user_data , +.Fn sqlite3_context_db_handle , +.Fn sqlite3_get_auxdata , +and/or +.Fn sqlite3_set_auxdata . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4529. +.Bd -literal +typedef struct sqlite3_context sqlite3_context; +.Ed +.Sh SEE ALSO +.Xr sqlite3_aggregate_context 3 , +.Xr sqlite3_context_db_handle 3 , +.Xr sqlite3_get_auxdata 3 , +.Xr sqlite3_result_blob 3 , +.Xr sqlite3_user_data 3 diff --git a/static/netbsd/man3/sqlite3_context_db_handle.3 b/static/netbsd/man3/sqlite3_context_db_handle.3 new file mode 100644 index 00000000..5198b8d9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_context_db_handle.3 @@ -0,0 +1,29 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CONTEXT_DB_HANDLE 3 +.Os +.Sh NAME +.Nm sqlite3_context_db_handle +.Nd database connection for functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3 * +.Fo sqlite3_context_db_handle +.Fa "sqlite3_context*" +.Fc +.Sh DESCRIPTION +The sqlite3_context_db_handle() interface returns a copy of the pointer +to the database connection (the 1st parameter) of +the +.Fn sqlite3_create_function +and +.Fn sqlite3_create_function16 +routines that originally registered the application defined function. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5891. +.Bd -literal +SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_create_function 3 diff --git a/static/netbsd/man3/sqlite3_create_collation.3 b/static/netbsd/man3/sqlite3_create_collation.3 new file mode 100644 index 00000000..4d59ecb8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_create_collation.3 @@ -0,0 +1,159 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CREATE_COLLATION 3 +.Os +.Sh NAME +.Nm sqlite3_create_collation , +.Nm sqlite3_create_collation_v2 , +.Nm sqlite3_create_collation16 +.Nd define new collating sequences +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_create_collation +.Fa "sqlite3*" +.Fa "const char *zName" +.Fa "int eTextRep" +.Fa "void *pArg" +.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" +.Fc +.Ft int +.Fo sqlite3_create_collation_v2 +.Fa "sqlite3*" +.Fa "const char *zName" +.Fa "int eTextRep" +.Fa "void *pArg" +.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" +.Fa "void(*xDestroy)(void*)" +.Fc +.Ft int +.Fo sqlite3_create_collation16 +.Fa "sqlite3*" +.Fa "const void *zName" +.Fa "int eTextRep" +.Fa "void *pArg" +.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" +.Fc +.Sh DESCRIPTION +These functions add, remove, or modify a collation associated +with the database connection specified as the first +argument. +.Pp +The name of the collation is a UTF-8 string for sqlite3_create_collation() +and sqlite3_create_collation_v2() and a UTF-16 string in native byte +order for sqlite3_create_collation16(). +Collation names that compare equal according to +.Fn sqlite3_strnicmp +are considered to be the same name. +.Pp +The third argument (eTextRep) must be one of the constants: +.Bl -bullet +.It +SQLITE_UTF8, +.It +SQLITE_UTF16LE, +.It +SQLITE_UTF16BE, +.It +SQLITE_UTF16, or +.It +SQLITE_UTF16_ALIGNED. +.El +.Pp +The eTextRep argument determines the encoding of strings passed to +the collating function callback, xCompare. +The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED +values for eTextRep force strings to be UTF16 with native byte order. +The SQLITE_UTF16_ALIGNED value for eTextRep forces +strings to begin on an even byte address. +.Pp +The fourth argument, pArg, is an application data pointer that is passed +through as the first argument to the collating function callback. +.Pp +The fifth argument, xCompare, is a pointer to the collating function. +Multiple collating functions can be registered using the same name +but with different eTextRep parameters and SQLite will use whichever +function requires the least amount of data transformation. +If the xCompare argument is NULL then the collating function is deleted. +When all collating functions having the same name are deleted, that +collation is no longer usable. +.Pp +The collating function callback is invoked with a copy of the pArg +application data pointer and with two strings in the encoding specified +by the eTextRep argument. +The two integer parameters to the collating function callback are the +length of the two strings, in bytes. +The collating function must return an integer that is negative, zero, +or positive if the first string is less than, equal to, or greater +than the second, respectively. +A collating function must always return the same answer given the same +inputs. +If two or more collating functions are registered to the same collation +name (using different eTextRep values) then all must give an equivalent +answer when invoked with equivalent strings. +The collating function must obey the following properties for all strings +A, B, and C: +.Bl -enum +.It +If A==B then B==A. +.It +If A==B and B==C then A==C. +.It +If A<B THEN B>A. +.It +If A<B and B<C then A<C. +.El +.Pp +If a collating function fails any of the above constraints and that +collating function is registered and used, then the behavior of SQLite +is undefined. +.Pp +The sqlite3_create_collation_v2() works like sqlite3_create_collation() +with the addition that the xDestroy callback is invoked on pArg when +the collating function is deleted. +Collating functions are deleted when they are overridden by later calls +to the collation creation functions or when the database connection +is closed using +.Fn sqlite3_close . +The xDestroy callback is \fInot\fP called if the sqlite3_create_collation_v2() +function fails. +Applications that invoke sqlite3_create_collation_v2() with a non-NULL +xDestroy argument should check the return code and dispose of the application +data pointer themselves rather than expecting SQLite to deal with it +for them. +This is different from every other SQLite interface. +The inconsistency is unfortunate but cannot be changed without breaking +backwards compatibility. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6246. +.Bd -literal +SQLITE_API int sqlite3_create_collation( + sqlite3*, + const char *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*) +); +SQLITE_API int sqlite3_create_collation_v2( + sqlite3*, + const char *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*), + void(*xDestroy)(void*) +); +SQLITE_API int sqlite3_create_collation16( + sqlite3*, + const void *zName, + int eTextRep, + void *pArg, + int(*xCompare)(void*,int,const void*,int,const void*) +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_close 3 , +.Xr sqlite3_collation_needed 3 , +.Xr sqlite3_stricmp 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_create_filename.3 b/static/netbsd/man3/sqlite3_create_filename.3 new file mode 100644 index 00000000..dd29f198 --- /dev/null +++ b/static/netbsd/man3/sqlite3_create_filename.3 @@ -0,0 +1,93 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CREATE_FILENAME 3 +.Os +.Sh NAME +.Nm sqlite3_create_filename , +.Nm sqlite3_free_filename +.Nd create and destroy VFS filenames +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_filename +.Fo sqlite3_create_filename +.Fa "const char *zDatabase" +.Fa "const char *zJournal" +.Fa "const char *zWal" +.Fa "int nParam" +.Fa "const char **azParam" +.Fc +.Ft void +.Fo sqlite3_free_filename +.Fa "sqlite3_filename" +.Fc +.Sh DESCRIPTION +These interfaces are provided for use by VFS shim implementations +and are not useful outside of that context. +.Pp +The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version +of database filename D with corresponding journal file J and WAL file +W and with N URI parameters key/values pairs in the array P. +The result from sqlite3_create_filename(D,J,W,N,P) is a pointer to +a database filename that is safe to pass to routines like: +.Bl -bullet +.It +.Fn sqlite3_uri_parameter , +.It +.Fn sqlite3_uri_boolean , +.It +.Fn sqlite3_uri_int64 , +.It +.Fn sqlite3_uri_key , +.It +.Fn sqlite3_filename_database , +.It +.Fn sqlite3_filename_journal , +or +.It +.Fn sqlite3_filename_wal . +.El +.Pp +If a memory allocation error occurs, sqlite3_create_filename() might +return a NULL pointer. +The memory obtained from sqlite3_create_filename(X) must be released +by a corresponding call to sqlite3_free_filename(Y). +.Pp +The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an +array of 2*N pointers to strings. +Each pair of pointers in this array corresponds to a key and value +for a query parameter. +The P parameter may be a NULL pointer if N is zero. +None of the 2*N pointers in the P array may be NULL pointers and key +pointers should not be empty strings. +None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) +may be NULL pointers, though they can be empty strings. +.Pp +The sqlite3_free_filename(Y) routine releases a memory allocation previously +obtained from sqlite3_create_filename(). +Invoking sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless +no-op. +.Pp +If the Y parameter to sqlite3_free_filename(Y) is anything other than +a NULL pointer or a pointer previously acquired from sqlite3_create_filename(), +then bad things such as heap corruption or segfaults may occur. +The value Y should not be used again after sqlite3_free_filename(Y) +has been called. +This means that if the +.Fn sqlite3_vfs.xOpen +method of a VFS has been called using Y, then the correspondingsqlite3_module.xClose() +method should also be invoked prior to calling sqlite3_free_filename(Y). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3876. +.Bd -literal +SQLITE_API sqlite3_filename sqlite3_create_filename( + const char *zDatabase, + const char *zJournal, + const char *zWal, + int nParam, + const char **azParam +); +SQLITE_API void sqlite3_free_filename(sqlite3_filename); +.Ed +.Sh SEE ALSO +.Xr sqlite3_filename_database 3 , +.Xr sqlite3_uri_parameter 3 diff --git a/static/netbsd/man3/sqlite3_create_function.3 b/static/netbsd/man3/sqlite3_create_function.3 new file mode 100644 index 00000000..811aa524 --- /dev/null +++ b/static/netbsd/man3/sqlite3_create_function.3 @@ -0,0 +1,243 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CREATE_FUNCTION 3 +.Os +.Sh NAME +.Nm sqlite3_create_function , +.Nm sqlite3_create_function16 , +.Nm sqlite3_create_function_v2 , +.Nm sqlite3_create_window_function +.Nd create or redefine SQL functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_create_function +.Fa "sqlite3 *db" +.Fa "const char *zFunctionName" +.Fa "int nArg" +.Fa "int eTextRep" +.Fa "void *pApp" +.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xFinal)(sqlite3_context*)" +.Fc +.Ft int +.Fo sqlite3_create_function16 +.Fa "sqlite3 *db" +.Fa "const void *zFunctionName" +.Fa "int nArg" +.Fa "int eTextRep" +.Fa "void *pApp" +.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xFinal)(sqlite3_context*)" +.Fc +.Ft int +.Fo sqlite3_create_function_v2 +.Fa "sqlite3 *db" +.Fa "const char *zFunctionName" +.Fa "int nArg" +.Fa "int eTextRep" +.Fa "void *pApp" +.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xFinal)(sqlite3_context*)" +.Fa "void(*xDestroy)(void*)" +.Fc +.Ft int +.Fo sqlite3_create_window_function +.Fa "sqlite3 *db" +.Fa "const char *zFunctionName" +.Fa "int nArg" +.Fa "int eTextRep" +.Fa "void *pApp" +.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void (*xFinal)(sqlite3_context*)" +.Fa "void (*xValue)(sqlite3_context*)" +.Fa "void (*xInverse)(sqlite3_context*,int,sqlite3_value**)" +.Fa "void(*xDestroy)(void*)" +.Fc +.Sh DESCRIPTION +These functions (collectively known as "function creation routines") +are used to add SQL functions or aggregates or to redefine the behavior +of existing SQL functions or aggregates. +The only differences between the three "sqlite3_create_function*" routines +are the text encoding expected for the second parameter (the name of +the function being created) and the presence or absence of a destructor +callback for the application data pointer. +Function sqlite3_create_window_function() is similar, but allows the +user to supply the extra callback functions needed by aggregate window functions. +.Pp +The first parameter is the database connection to +which the SQL function is to be added. +If an application uses more than one database connection then application-defined +SQL functions must be added to each database connection separately. +.Pp +The second parameter is the name of the SQL function to be created +or redefined. +The length of the name is limited to 255 bytes in a UTF-8 representation, +exclusive of the zero-terminator. +Note that the name length limit is in UTF-8 bytes, not characters nor +UTF-16 bytes. +Any attempt to create a function with a longer name will result in +SQLITE_MISUSE being returned. +.Pp +The third parameter (nArg) is the number of arguments that the SQL +function or aggregate takes. +If this parameter is -1, then the SQL function or aggregate may take +any number of arguments between 0 and the limit set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG). +If the third parameter is less than -1 or greater than 127 then the +behavior is undefined. +.Pp +The fourth parameter, eTextRep, specifies what text encoding +this SQL function prefers for its parameters. +The application should set this parameter to SQLITE_UTF16LE +if the function implementation invokes +.Fn sqlite3_value_text16le +on an input, or SQLITE_UTF16BE if the implementation +invokes +.Fn sqlite3_value_text16be +on an input, or SQLITE_UTF16 if +.Fn sqlite3_value_text16 +is used, or SQLITE_UTF8 otherwise. +The same SQL function may be registered multiple times using different +preferred text encodings, with different implementations for each encoding. +When multiple implementations of the same function are available, SQLite +will pick the one that involves the least amount of data conversion. +.Pp +The fourth parameter may optionally be ORed with SQLITE_DETERMINISTIC +to signal that the function will always return the same result given +the same inputs within a single SQL statement. +Most SQL functions are deterministic. +The built-in +.Fn random +SQL function is an example of a function that is not deterministic. +The SQLite query planner is able to perform additional optimizations +on deterministic functions, so use of the SQLITE_DETERMINISTIC +flag is recommended where possible. +.Pp +The fourth parameter may also optionally include the SQLITE_DIRECTONLY +flag, which if present prevents the function from being invoked from +within VIEWs, TRIGGERs, CHECK constraints, generated column expressions, +index expressions, or the WHERE clause of partial indexes. +.Pp +For best security, the SQLITE_DIRECTONLY flag is recommended +for all application-defined SQL functions that do not need to be used +inside of triggers, view, CHECK constraints, or other elements of the +database schema. +This flags is especially recommended for SQL functions that have side +effects or reveal internal application state. +Without this flag, an attacker might be able to modify the schema of +a database file to include invocations of the function with parameters +chosen by the attacker, which the application will then execute when +the database file is opened and read. +.Pp +The fifth parameter is an arbitrary pointer. +The implementation of the function can gain access to this pointer +using +.Fn sqlite3_user_data . +The sixth, seventh and eighth parameters passed to the three "sqlite3_create_function*" +functions, xFunc, xStep and xFinal, are pointers to C-language functions +that implement the SQL function or aggregate. +A scalar SQL function requires an implementation of the xFunc callback +only; NULL pointers must be passed as the xStep and xFinal parameters. +An aggregate SQL function requires an implementation of xStep and xFinal +and NULL pointer must be passed for xFunc. +To delete an existing SQL function or aggregate, pass NULL pointers +for all three function callbacks. +.Pp +The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue +and xInverse) passed to sqlite3_create_window_function are pointers +to C-language callbacks that implement the new function. +xStep and xFinal must both be non-NULL. +xValue and xInverse may either both be NULL, in which case a regular +aggregate function is created, or must both be non-NULL, in which case +the new function may be used as either an aggregate or aggregate window +function. +More details regarding the implementation of aggregate window functions +are available here. +.Pp +If the final parameter to sqlite3_create_function_v2() or sqlite3_create_window_function() +is not NULL, then it is destructor for the application data pointer. +The destructor is invoked when the function is deleted, either by being +overloaded or when the database connection closes. +The destructor is also invoked if the call to sqlite3_create_function_v2() +fails. +When the destructor callback is invoked, it is passed a single argument +which is a copy of the application data pointer which was the fifth +parameter to sqlite3_create_function_v2(). +.Pp +It is permitted to register multiple implementations of the same functions +with the same name but with either differing numbers of arguments or +differing preferred text encodings. +SQLite will use the implementation that most closely matches the way +in which the SQL function is used. +A function implementation with a non-negative nArg parameter is a better +match than a function implementation with a negative nArg. +A function where the preferred text encoding matches the database encoding +is a better match than a function where the encoding is different. +A function where the encoding difference is between UTF16le and UTF16be +is a closer match than a function where the encoding difference is +between UTF8 and UTF16. +.Pp +Built-in functions may be overloaded by new application-defined functions. +.Pp +An application-defined function is permitted to call other SQLite interfaces. +However, such calls must not close the database connection nor finalize +or reset the prepared statement in which the function is running. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5333. +.Bd -literal +SQLITE_API int sqlite3_create_function( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +SQLITE_API int sqlite3_create_function16( + sqlite3 *db, + const void *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*) +); +SQLITE_API int sqlite3_create_function_v2( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xFunc)(sqlite3_context*,int,sqlite3_value**), + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*), + void(*xDestroy)(void*) +); +SQLITE_API int sqlite3_create_window_function( + sqlite3 *db, + const char *zFunctionName, + int nArg, + int eTextRep, + void *pApp, + void (*xStep)(sqlite3_context*,int,sqlite3_value**), + void (*xFinal)(sqlite3_context*), + void (*xValue)(sqlite3_context*), + void (*xInverse)(sqlite3_context*,int,sqlite3_value**), + void(*xDestroy)(void*) +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_limit 3 , +.Xr sqlite3_user_data 3 , +.Xr sqlite3_value_blob 3 , +.Xr SQLITE_DETERMINISTIC 3 , +.Xr SQLITE_LIMIT_LENGTH 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_create_module.3 b/static/netbsd/man3/sqlite3_create_module.3 new file mode 100644 index 00000000..dddefecd --- /dev/null +++ b/static/netbsd/man3/sqlite3_create_module.3 @@ -0,0 +1,75 @@ +.Dd January 24, 2024 +.Dt SQLITE3_CREATE_MODULE 3 +.Os +.Sh NAME +.Nm sqlite3_create_module , +.Nm sqlite3_create_module_v2 +.Nd register a virtual table implementation +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_create_module +.Fa "sqlite3 *db" +.Fa "const char *zName" +.Fa "const sqlite3_module *p" +.Fa "void *pClientData" +.Fc +.Ft int +.Fo sqlite3_create_module_v2 +.Fa "sqlite3 *db" +.Fa "const char *zName" +.Fa "const sqlite3_module *p" +.Fa "void *pClientData" +.Fa "void(*xDestroy)(void*)" +.Fc +.Sh DESCRIPTION +These routines are used to register a new virtual table module +name. +Module names must be registered before creating a new virtual table +using the module and before using a preexisting virtual table +for the module. +.Pp +The module name is registered on the database connection +specified by the first parameter. +The name of the module is given by the second parameter. +The third parameter is a pointer to the implementation of the virtual table module. +The fourth parameter is an arbitrary client data pointer that is passed +through into the xCreate and xConnect methods of the +virtual table module when a new virtual table is be being created or +reinitialized. +.Pp +The sqlite3_create_module_v2() interface has a fifth parameter which +is a pointer to a destructor for the pClientData. +SQLite will invoke the destructor function (if it is not NULL) when +SQLite no longer needs the pClientData pointer. +The destructor will also be invoked if the call to sqlite3_create_module_v2() +fails. +The sqlite3_create_module() interface is equivalent to sqlite3_create_module_v2() +with a NULL destructor. +.Pp +If the third parameter (the pointer to the sqlite3_module object) is +NULL then no new module is created and any existing modules with the +same name are dropped. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7530. +.Bd -literal +SQLITE_API int sqlite3_create_module( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData /* Client data for xCreate/xConnect */ +); +SQLITE_API int sqlite3_create_module_v2( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData, /* Client data for xCreate/xConnect */ + void(*xDestroy)(void*) /* Module destructor function */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_drop_modules 3 , +.Xr sqlite3_module 3 diff --git a/static/netbsd/man3/sqlite3_data_count.3 b/static/netbsd/man3/sqlite3_data_count.3 new file mode 100644 index 00000000..3f708936 --- /dev/null +++ b/static/netbsd/man3/sqlite3_data_count.3 @@ -0,0 +1,40 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DATA_COUNT 3 +.Os +.Sh NAME +.Nm sqlite3_data_count +.Nd number of columns in a result set +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_data_count +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_data_count(P) interface returns the number of columns in +the current row of the result set of prepared statement +P. +If prepared statement P does not have results ready to return (via +calls to the sqlite3_column() family of interfaces) +then sqlite3_data_count(P) returns 0. +The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. +The sqlite3_data_count(P) routine returns 0 if the previous call to +sqlite3_step(P) returned SQLITE_DONE. +The sqlite3_data_count(P) will return non-zero if previous call to +sqlite3_step(P) returned SQLITE_ROW, except in +the case of the PRAGMA incremental_vacuum +where it always returns zero since each step of that multi-step pragma +returns 0 columns of data. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4988. +.Bd -literal +SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_column_count 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_data_directory.3 b/static/netbsd/man3/sqlite3_data_directory.3 new file mode 100644 index 00000000..c33ec2b3 --- /dev/null +++ b/static/netbsd/man3/sqlite3_data_directory.3 @@ -0,0 +1,52 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DATA_DIRECTORY 3 +.Os +.Sh NAME +.Nm sqlite3_data_directory +.Nd name of the folder holding database files +.Sh SYNOPSIS +.In sqlite3.h +.Vt char *sqlite3_data_directory; +.Sh DESCRIPTION +If this global variable is made to point to a string which is the name +of a folder (a.k.a. +directory), then all database files specified with a relative pathname +and created or accessed by SQLite when using a built-in windows VFS +will be assumed to be relative to that directory. +If this variable is a NULL pointer, then SQLite assumes that all database +files specified with a relative pathname are relative to the current +directory for the process. +Only the windows VFS makes use of this global variable; it is ignored +by the unix VFS. +.Pp +Changing the value of this variable while a database connection is +open can result in a corrupt database. +.Pp +It is not safe to read or modify this variable in more than one thread +at a time. +It is not safe to read or modify this variable if a database connection +is being used at the same time in a separate thread. +It is intended that this variable be set once as part of process initialization +and before any SQLite interface routines have been called and that +this variable remain unchanged thereafter. +.Pp +The data_store_directory pragma may modify +this variable and cause it to point to memory obtained from sqlite3_malloc. +Furthermore, the data_store_directory pragma +always assumes that any string that this variable points to is held +in memory obtained from sqlite3_malloc and the pragma +may attempt to free that memory using sqlite3_free. +Hence, if this variable is modified directly, either it should be made +NULL or made to point to memory obtained from sqlite3_malloc +or else the use of the data_store_directory pragma +should be avoided. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6482. +.Bd -literal +SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory; +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_database_file_object.3 b/static/netbsd/man3/sqlite3_database_file_object.3 new file mode 100644 index 00000000..c71fee50 --- /dev/null +++ b/static/netbsd/man3/sqlite3_database_file_object.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DATABASE_FILE_OBJECT 3 +.Os +.Sh NAME +.Nm sqlite3_database_file_object +.Nd database file corresponding to a journal +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_file * +.Fo sqlite3_database_file_object +.Fa "const char*" +.Fc +.Sh DESCRIPTION +If X is the name of a rollback or WAL-mode journal file that is passed +into the xOpen method of sqlite3_vfs, then sqlite3_database_file_object(X) +returns a pointer to the sqlite3_file object that represents +the main database file. +.Pp +This routine is intended for use in custom VFS implementations only. +It is not a general-purpose interface. +The argument sqlite3_file_object(X) must be a filename pointer that +has been passed into sqlite3_vfs.xOpen method where the +flags parameter to xOpen contains one of the bits SQLITE_OPEN_MAIN_JOURNAL +or SQLITE_OPEN_WAL. +Any other use of this routine results in undefined and probably undesirable +behavior. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3857. +.Bd -literal +SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_file 3 , +.Xr sqlite3_vfs 3 , +.Xr SQLITE_OPEN_READONLY 3 diff --git a/static/netbsd/man3/sqlite3_db_cacheflush.3 b/static/netbsd/man3/sqlite3_db_cacheflush.3 new file mode 100644 index 00000000..8f1cecdf --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_cacheflush.3 @@ -0,0 +1,56 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_CACHEFLUSH 3 +.Os +.Sh NAME +.Nm sqlite3_db_cacheflush +.Nd flush caches to disk mid-transaction +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_db_cacheflush +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +If a write-transaction is open on database connection +D when the sqlite3_db_cacheflush(D) interface +invoked, any dirty pages in the pager-cache that are not currently +in use are written out to disk. +A dirty page may be in use if a database cursor created by an active +SQL statement is reading from it, or if it is page 1 of a database +file (page 1 is always "in use"). +The sqlite3_db_cacheflush(D) interface flushes +caches for all schemas - "main", "temp", and any attached databases. +.Pp +If this function needs to obtain extra database locks before dirty +pages can be flushed to disk, it does so. +If those locks cannot be obtained immediately and there is a busy-handler +callback configured, it is invoked in the usual manner. +If the required lock still cannot be obtained, then the database is +skipped and an attempt made to flush any dirty pages belonging to the +next (if any) database. +If any databases are skipped because locks cannot be obtained, but +no other error occurs, this function returns SQLITE_BUSY. +.Pp +If any other error occurs while flushing dirty pages to disk (for example +an IO error or out-of-memory condition), then processing is abandoned +and an SQLite error code is returned to the caller immediately. +.Pp +Otherwise, if no error occurs, +.Fn sqlite3_db_cacheflush +returns SQLITE_OK. +.Pp +This function does not set the database handle error code or message +returned by the +.Fn sqlite3_errcode +and +.Fn sqlite3_errmsg +functions. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10283. +.Bd -literal +SQLITE_API int sqlite3_db_cacheflush(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_errcode 3 diff --git a/static/netbsd/man3/sqlite3_db_config.3 b/static/netbsd/man3/sqlite3_db_config.3 new file mode 100644 index 00000000..2383c145 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_config.3 @@ -0,0 +1,39 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_CONFIG 3 +.Os +.Sh NAME +.Nm sqlite3_db_config +.Nd configure database connections +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_db_config +.Fa "sqlite3*" +.Fa "int op" +.Fa "..." +.Fc +.Sh DESCRIPTION +The sqlite3_db_config() interface is used to make configuration changes +to a database connection. +The interface is similar to +.Fn sqlite3_config +except that the changes apply to a single database connection +(specified in the first argument). +.Pp +The second argument to sqlite3_db_config(D,V,...) is the configuration verb +- an integer code that indicates what aspect of the database connection +is being configured. +Subsequent arguments vary depending on the configuration verb. +.Pp +Calls to sqlite3_db_config() return SQLITE_OK if and only if the call +is considered successful. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1683. +.Bd -literal +SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_config 3 , +.Xr SQLITE_DBCONFIG_MAINDBNAME 3 diff --git a/static/netbsd/man3/sqlite3_db_filename.3 b/static/netbsd/man3/sqlite3_db_filename.3 new file mode 100644 index 00000000..66c5c1c2 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_filename.3 @@ -0,0 +1,57 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_FILENAME 3 +.Os +.Sh NAME +.Nm sqlite3_db_filename +.Nd return the filename for a database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_filename +.Fo sqlite3_db_filename +.Fa "sqlite3 *db" +.Fa "const char *zDbName" +.Fc +.Sh DESCRIPTION +The sqlite3_db_filename(D,N) interface returns a pointer to the filename +associated with database N of connection D. +If there is no attached database N on the database connection D, or +if database N is a temporary or in-memory database, then this function +will return either a NULL pointer or an empty string. +.Pp +The string value returned by this routine is owned and managed by the +database connection. +The value will be valid until the database N is DETACH-ed or +until the database connection closes. +.Pp +The filename returned by this function is the output of the xFullPathname +method of the VFS. +In other words, the filename will be an absolute pathname, even if +the filename used to open the database originally was a URI or relative +pathname. +.Pp +If the filename pointer returned by this routine is not NULL, then +it can be used as the filename input parameter to these routines: +.Bl -bullet +.It +.Fn sqlite3_uri_parameter +.It +.Fn sqlite3_uri_boolean +.It +.Fn sqlite3_uri_int64 +.It +.Fn sqlite3_filename_database +.It +.Fn sqlite3_filename_journal +.It +.Fn sqlite3_filename_wal +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6613. +.Bd -literal +SQLITE_API sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName); +.Ed +.Sh SEE ALSO +.Xr sqlite3_filename_database 3 , +.Xr sqlite3_uri_parameter 3 diff --git a/static/netbsd/man3/sqlite3_db_handle.3 b/static/netbsd/man3/sqlite3_db_handle.3 new file mode 100644 index 00000000..efc11870 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_handle.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_HANDLE 3 +.Os +.Sh NAME +.Nm sqlite3_db_handle +.Nd find the database handle of a prepared statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3 * +.Fo sqlite3_db_handle +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +The sqlite3_db_handle interface returns the database connection +handle to which a prepared statement belongs. +The database connection returned by sqlite3_db_handle +is the same database connection that was the first +argument to the +.Fn sqlite3_prepare_v2 +call (or its variants) that was used to create the statement in the +first place. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6578. +.Bd -literal +SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_db_mutex.3 b/static/netbsd/man3/sqlite3_db_mutex.3 new file mode 100644 index 00000000..e28939c2 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_mutex.3 @@ -0,0 +1,27 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_MUTEX 3 +.Os +.Sh NAME +.Nm sqlite3_db_mutex +.Nd retrieve the mutex for a database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_mutex * +.Fo sqlite3_db_mutex +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +This interface returns a pointer the sqlite3_mutex object +that serializes access to the database connection +given in the argument when the threading mode is Serialized. +If the threading mode is Single-thread or Multi-thread +then this routine returns a NULL pointer. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8209. +.Bd -literal +SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_mutex 3 diff --git a/static/netbsd/man3/sqlite3_db_name.3 b/static/netbsd/man3/sqlite3_db_name.3 new file mode 100644 index 00000000..fb028bb8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_name.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_NAME 3 +.Os +.Sh NAME +.Nm sqlite3_db_name +.Nd return the schema name for a database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_db_name +.Fa "sqlite3 *db" +.Fa "int N" +.Fc +.Sh DESCRIPTION +The sqlite3_db_name(D,N) interface returns a pointer to the schema +name for the N-th database on database connection D, or a NULL pointer +of N is out of range. +An N value of 0 means the main database file. +An N of 1 is the "temp" schema. +Larger values of N correspond to various ATTACH-ed databases. +.Pp +Space to hold the string that is returned by sqlite3_db_name() is managed +by SQLite itself. +The string might be deallocated by any operation that changes the schema, +including ATTACH or DETACH or calls to +.Fn sqlite3_serialize +or +.Fn sqlite3_deserialize , +even operations that occur on a different thread. +Applications that need to remember the string long-term should make +their own copy. +Applications that are accessing the same database connection simultaneously +on multiple threads should mutex-protect calls to this API and should +make their own private copy of the result prior to releasing the mutex. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6591. +.Bd -literal +SQLITE_API const char *sqlite3_db_name(sqlite3 *db, int N); +.Ed +.Sh SEE ALSO +.Xr sqlite3_deserialize 3 , +.Xr sqlite3_serialize 3 diff --git a/static/netbsd/man3/sqlite3_db_readonly.3 b/static/netbsd/man3/sqlite3_db_readonly.3 new file mode 100644 index 00000000..129f12c1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_readonly.3 @@ -0,0 +1,23 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_READONLY 3 +.Os +.Sh NAME +.Nm sqlite3_db_readonly +.Nd determine if a database is read-only +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_db_readonly +.Fa "sqlite3 *db" +.Fa "const char *zDbName" +.Fc +.Sh DESCRIPTION +The sqlite3_db_readonly(D,N) interface returns 1 if the database N +of connection D is read-only, 0 if it is read/write, or -1 if N is +not the name of a database on connection D. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6645. +.Bd -literal +SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName); +.Ed diff --git a/static/netbsd/man3/sqlite3_db_release_memory.3 b/static/netbsd/man3/sqlite3_db_release_memory.3 new file mode 100644 index 00000000..a666d817 --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_release_memory.3 @@ -0,0 +1,28 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_RELEASE_MEMORY 3 +.Os +.Sh NAME +.Nm sqlite3_db_release_memory +.Nd free memory used by a database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_db_release_memory +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +The sqlite3_db_release_memory(D) interface attempts to free as much +heap memory as possible from database connection D. +Unlike the +.Fn sqlite3_release_memory +interface, this interface is in effect even when the SQLITE_ENABLE_MEMORY_MANAGEMENT +compile-time option is omitted. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6955. +.Bd -literal +SQLITE_API int sqlite3_db_release_memory(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_release_memory 3 diff --git a/static/netbsd/man3/sqlite3_db_status.3 b/static/netbsd/man3/sqlite3_db_status.3 new file mode 100644 index 00000000..88a004ee --- /dev/null +++ b/static/netbsd/man3/sqlite3_db_status.3 @@ -0,0 +1,44 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DB_STATUS 3 +.Os +.Sh NAME +.Nm sqlite3_db_status +.Nd database connection status +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_db_status +.Fa "sqlite3*" +.Fa "int op" +.Fa "int *pCur" +.Fa "int *pHiwtr" +.Fa "int resetFlg" +.Fc +.Sh DESCRIPTION +This interface is used to retrieve runtime status information about +a single database connection. +The first argument is the database connection object to be interrogated. +The second argument is an integer constant, taken from the set of SQLITE_DBSTATUS options, +that determines the parameter to interrogate. +The set of SQLITE_DBSTATUS options is likely +to grow in future releases of SQLite. +.Pp +The current value of the requested parameter is written into *pCur +and the highest instantaneous value is written into *pHiwtr. +If the resetFlg is true, then the highest instantaneous value is reset +back down to the current value. +.Pp +The sqlite3_db_status() routine returns SQLITE_OK on success and a +non-zero error code on failure. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8627. +.Bd -literal +SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_status 3 , +.Xr sqlite3_stmt_status 3 , +.Xr SQLITE_DBSTATUS_LOOKASIDE_USED 3 diff --git a/static/netbsd/man3/sqlite3_declare_vtab.3 b/static/netbsd/man3/sqlite3_declare_vtab.3 new file mode 100644 index 00000000..98e1f89d --- /dev/null +++ b/static/netbsd/man3/sqlite3_declare_vtab.3 @@ -0,0 +1,25 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DECLARE_VTAB 3 +.Os +.Sh NAME +.Nm sqlite3_declare_vtab +.Nd declare the schema of a virtual table +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_declare_vtab +.Fa "sqlite3*" +.Fa "const char *zSQL" +.Fc +.Sh DESCRIPTION +The xCreate and xConnect methods of a virtual table module +call this interface to declare the format (the names and datatypes +of the columns) of the virtual tables they implement. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7640. +.Bd -literal +SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); +.Ed +.Sh SEE ALSO +.Xr sqlite3_module 3 diff --git a/static/netbsd/man3/sqlite3_deserialize.3 b/static/netbsd/man3/sqlite3_deserialize.3 new file mode 100644 index 00000000..134328e8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_deserialize.3 @@ -0,0 +1,77 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DESERIALIZE 3 +.Os +.Sh NAME +.Nm sqlite3_deserialize +.Nd deserialize a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_deserialize +.Fa "sqlite3 *db" +.Fa "const char *zSchema" +.Fa "unsigned char *pData" +.Fa "sqlite3_int64 szDb" +.Fa "sqlite3_int64 szBuf" +.Fa "unsigned mFlags" +.Fc +.Sh DESCRIPTION +The sqlite3_deserialize(D,S,P,N,M,F) interface causes the database connection +D to disconnect from database S and then reopen S as an in-memory database +based on the serialization contained in P. +The serialized database P is N bytes in size. +M is the size of the buffer P, which might be larger than N. +If M is larger than N, and the SQLITE_DESERIALIZE_READONLY bit is not +set in F, then SQLite is permitted to add content to the in-memory +database as long as the total size does not exceed M bytes. +.Pp +If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite +will invoke sqlite3_free() on the serialization buffer when the database +connection closes. +If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then SQLite will try +to increase the buffer size using sqlite3_realloc64() if writes on +the database cause it to grow larger than M bytes. +.Pp +Applications must not modify the buffer P or invalidate it before the +database connection D is closed. +.Pp +The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the +database is currently in a read transaction or is involved in a backup +operation. +.Pp +It is not possible to deserialized into the TEMP database. +If the S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then +the function returns SQLITE_ERROR. +.Pp +The deserialized database should not be in WAL mode. +If the database is in WAL mode, then any attempt to use the database +file will result in an SQLITE_CANTOPEN error. +The application can set the file format version numbers +(bytes 18 and 19) of the input database P to 0x01 prior to invoking +sqlite3_deserialize(D,S,P,N,M,F) to force the database file into rollback +mode and work around this limitation. +.Pp +If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the +SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then +.Fn sqlite3_free +is invoked on argument P prior to returning. +.Pp +This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE +option. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10702. +.Bd -literal +SQLITE_API int sqlite3_deserialize( + sqlite3 *db, /* The database connection */ + const char *zSchema, /* Which DB to reopen with the deserialization */ + unsigned char *pData, /* The serialized database content */ + sqlite3_int64 szDb, /* Number bytes in the deserialization */ + sqlite3_int64 szBuf, /* Total size of buffer pData[] */ + unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_destructor_type.3 b/static/netbsd/man3/sqlite3_destructor_type.3 new file mode 100644 index 00000000..ee449d89 --- /dev/null +++ b/static/netbsd/man3/sqlite3_destructor_type.3 @@ -0,0 +1,35 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DESTRUCTOR_TYPE 3 +.Os +.Sh NAME +.Nm sqlite3_destructor_type , +.Nm SQLITE_STATIC , +.Nm SQLITE_TRANSIENT +.Nd constants defining special destructor behavior +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef void (*sqlite3_destructor_type)(void*); +.Fd #define SQLITE_STATIC +.Fd #define SQLITE_TRANSIENT +.Sh DESCRIPTION +These are special values for the destructor that is passed in as the +final argument to routines like +.Fn sqlite3_result_blob . +If the destructor argument is SQLITE_STATIC, it means that the content +pointer is constant and will never change. +It does not need to be destroyed. +The SQLITE_TRANSIENT value means that the content will likely change +in the near future and that SQLite should make its own private copy +of the content before returning. +.Pp +The typedef is necessary to work around problems in certain C++ compilers. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6029. +.Bd -literal +typedef void (*sqlite3_destructor_type)(void*); +#define SQLITE_STATIC ((sqlite3_destructor_type)0) +#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) +.Ed +.Sh SEE ALSO +.Xr sqlite3_result_blob 3 diff --git a/static/netbsd/man3/sqlite3_drop_modules.3 b/static/netbsd/man3/sqlite3_drop_modules.3 new file mode 100644 index 00000000..0709213d --- /dev/null +++ b/static/netbsd/man3/sqlite3_drop_modules.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3_DROP_MODULES 3 +.Os +.Sh NAME +.Nm sqlite3_drop_modules +.Nd remove unnecessary virtual table implementations +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_drop_modules +.Fa "sqlite3 *db" +.Fa "const char **azKeep" +.Fc +.Sh DESCRIPTION +The sqlite3_drop_modules(D,L) interface removes all virtual table modules +from database connection D except those named on list L. +The L parameter must be either NULL or a pointer to an array of pointers +to strings where the array is terminated by a single NULL pointer. +If the L parameter is NULL, then all virtual table modules are removed. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7576. +.Bd -literal +SQLITE_API int sqlite3_drop_modules( + sqlite3 *db, /* Remove modules from this connection */ + const char **azKeep /* Except, do not remove the ones named here */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_create_module 3 diff --git a/static/netbsd/man3/sqlite3_enable_load_extension.3 b/static/netbsd/man3/sqlite3_enable_load_extension.3 new file mode 100644 index 00000000..1ad739f6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_enable_load_extension.3 @@ -0,0 +1,50 @@ +.Dd January 24, 2024 +.Dt SQLITE3_ENABLE_LOAD_EXTENSION 3 +.Os +.Sh NAME +.Nm sqlite3_enable_load_extension +.Nd enable or disable extension loading +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_enable_load_extension +.Fa "sqlite3 *db" +.Fa "int onoff" +.Fc +.Sh DESCRIPTION +So as not to open security holes in older applications that are unprepared +to deal with extension loading, and as a means of +disabling extension loading while evaluating user-entered +SQL, the following API is provided to turn the +.Fn sqlite3_load_extension +mechanism on and off. +.Pp +Extension loading is off by default. +Call the sqlite3_enable_load_extension() routine with onoff==1 to turn +extension loading on and call it with onoff==0 to turn it back off +again. +.Pp +This interface enables or disables both the C-API +.Fn sqlite3_load_extension +and the SQL function +.Fn load_extension . +Use sqlite3_db_config(db,SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,..) +to enable or disable only the C-API. +.Pp +\fBSecurity warning:\fP It is recommended that extension loading be enabled +using the SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +method rather than this interface, so the +.Fn load_extension +SQL function remains disabled. +This will prevent SQL injections from giving attackers access to extension +loading capabilities. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7180. +.Bd -literal +SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_config 3 , +.Xr sqlite3_load_extension 3 , +.Xr SQLITE_DBCONFIG_MAINDBNAME 3 diff --git a/static/netbsd/man3/sqlite3_enable_shared_cache.3 b/static/netbsd/man3/sqlite3_enable_shared_cache.3 new file mode 100644 index 00000000..8f78fd11 --- /dev/null +++ b/static/netbsd/man3/sqlite3_enable_shared_cache.3 @@ -0,0 +1,73 @@ +.Dd January 24, 2024 +.Dt SQLITE3_ENABLE_SHARED_CACHE 3 +.Os +.Sh NAME +.Nm sqlite3_enable_shared_cache +.Nd enable or disable shared pager cache +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_enable_shared_cache +.Fa "int" +.Fc +.Sh DESCRIPTION +This routine enables or disables the sharing of the database cache +and schema data structures between connections to the same +database. +Sharing is enabled if the argument is true and disabled if the argument +is false. +.Pp +This interface is omitted if SQLite is compiled with -DSQLITE_OMIT_SHARED_CACHE. +The -DSQLITE_OMIT_SHARED_CACHE compile-time +option is recommended because the use of shared cache mode is discouraged. +.Pp +Cache sharing is enabled and disabled for an entire process. +This is a change as of SQLite version 3.5.0 (dateof:3.5.0). +In prior versions of SQLite, sharing was enabled or disabled for each +thread separately. +.Pp +The cache sharing mode set by this interface effects all subsequent +calls to +.Fn sqlite3_open , +.Fn sqlite3_open_v2 , +and +.Fn sqlite3_open16 . +Existing database connections continue to use the sharing mode that +was in effect at the time they were opened. +.Pp +This routine returns SQLITE_OK if shared cache was enabled +or disabled successfully. +An error code is returned otherwise. +.Pp +Shared cache is disabled by default. +It is recommended that it stay that way. +In other words, do not use this routine. +This interface continues to be provided for historical compatibility, +but its use is discouraged. +Any use of shared cache is discouraged. +If shared cache must be used, it is recommended that shared cache only +be enabled for individual database connections using the +.Fn sqlite3_open_v2 +interface with the SQLITE_OPEN_SHAREDCACHE flag. +.Pp +Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 and +will always return SQLITE_MISUSE. +On those systems, shared cache mode should be enabled per-database +connection via +.Fn sqlite3_open_v2 +with SQLITE_OPEN_SHAREDCACHE. +.Pp +This interface is threadsafe on processors where writing a 32-bit integer +is atomic. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6893. +.Bd -literal +SQLITE_API int sqlite3_enable_shared_cache(int); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_open 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_OPEN_READONLY 3 diff --git a/static/netbsd/man3/sqlite3_errcode.3 b/static/netbsd/man3/sqlite3_errcode.3 new file mode 100644 index 00000000..8afc1d90 --- /dev/null +++ b/static/netbsd/man3/sqlite3_errcode.3 @@ -0,0 +1,115 @@ +.Dd January 24, 2024 +.Dt SQLITE3_ERRCODE 3 +.Os +.Sh NAME +.Nm sqlite3_errcode , +.Nm sqlite3_extended_errcode , +.Nm sqlite3_errmsg , +.Nm sqlite3_errmsg16 , +.Nm sqlite3_errstr , +.Nm sqlite3_error_offset +.Nd error codes and messages +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_errcode +.Fa "sqlite3 *db" +.Fc +.Ft int +.Fo sqlite3_extended_errcode +.Fa "sqlite3 *db" +.Fc +.Ft const char * +.Fo sqlite3_errmsg +.Fa "sqlite3*" +.Fc +.Ft const void * +.Fo sqlite3_errmsg16 +.Fa "sqlite3*" +.Fc +.Ft const char * +.Fo sqlite3_errstr +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_error_offset +.Fa "sqlite3 *db" +.Fc +.Sh DESCRIPTION +If the most recent sqlite3_* API call associated with database connection +D failed, then the sqlite3_errcode(D) interface returns the numeric +result code or extended result code +for that API call. +The sqlite3_extended_errcode() interface is the same except that it +always returns the extended result code even when +extended result codes are disabled. +.Pp +The values returned by sqlite3_errcode() and/or sqlite3_extended_errcode() +might change with each API call. +Except, there are some interfaces that are guaranteed to never change +the value of the error code. +The error-code preserving interfaces include the following: +.Bl -bullet +.It +sqlite3_errcode() +.It +sqlite3_extended_errcode() +.It +sqlite3_errmsg() +.It +sqlite3_errmsg16() +.It +sqlite3_error_offset() +.El +.Pp +The sqlite3_errmsg() and sqlite3_errmsg16() return English-language +text that describes the error, as either UTF-8 or UTF-16 respectively, +or NULL if no error message is available. +(See how SQLite handles invalid UTF for exceptions to this +rule.) Memory to hold the error message string is managed internally. +The application does not need to worry about freeing the result. +However, the error string might be overwritten or deallocated by subsequent +calls to other SQLite interface functions. +.Pp +The sqlite3_errstr(E) interface returns the English-language text that +describes the result code E, as UTF-8, or NULL if E is not +an result code for which a text error message is available. +Memory to hold the error message string is managed internally and must +not be freed by the application. +.Pp +If the most recent error references a specific token in the input SQL, +the sqlite3_error_offset() interface returns the byte offset of the +start of that token. +The byte offset returned by sqlite3_error_offset() assumes that the +input SQL is UTF8. +If the most recent error does not reference a specific token in the +input SQL, then the sqlite3_error_offset() function returns -1. +.Pp +When the serialized threading mode is in use, it might +be the case that a second error occurs on a separate thread in between +the time of the first error and the call to these interfaces. +When that happens, the second error will be reported since these interfaces +always report the most recent result. +To avoid this, each thread can obtain exclusive use of the database connection +D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) +before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) +after all calls to the interfaces listed here are completed. +.Pp +If an interface fails with SQLITE_MISUSE, that means the interface +was invoked incorrectly by the application. +In that case, the error code and message may or may not be set. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3930. +.Bd -literal +SQLITE_API int sqlite3_errcode(sqlite3 *db); +SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); +SQLITE_API const char *sqlite3_errmsg(sqlite3*); +SQLITE_API const void *sqlite3_errmsg16(sqlite3*); +SQLITE_API const char *sqlite3_errstr(int); +SQLITE_API int sqlite3_error_offset(sqlite3 *db); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_db_mutex 3 , +.Xr sqlite3_mutex_alloc 3 diff --git a/static/netbsd/man3/sqlite3_exec.3 b/static/netbsd/man3/sqlite3_exec.3 new file mode 100644 index 00000000..15930f07 --- /dev/null +++ b/static/netbsd/man3/sqlite3_exec.3 @@ -0,0 +1,106 @@ +.Dd January 24, 2024 +.Dt SQLITE3_EXEC 3 +.Os +.Sh NAME +.Nm sqlite3_exec +.Nd one-Step query execution interface +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_exec +.Fa "sqlite3*" +.Fa "const char *sql" +.Fa "int (*callback)(void*,int,char**,char**)" +.Fa "void *" +.Fa "char **errmsg" +.Fc +.Sh DESCRIPTION +The sqlite3_exec() interface is a convenience wrapper around +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_step , +and +.Fn sqlite3_finalize , +that allows an application to run multiple statements of SQL without +having to use a lot of C code. +.Pp +The sqlite3_exec() interface runs zero or more UTF-8 encoded, semicolon-separate +SQL statements passed into its 2nd argument, in the context of the +database connection passed in as its 1st argument. +If the callback function of the 3rd argument to sqlite3_exec() is not +NULL, then it is invoked for each result row coming out of the evaluated +SQL statements. +The 4th argument to sqlite3_exec() is relayed through to the 1st argument +of each callback invocation. +If the callback pointer to sqlite3_exec() is NULL, then no callback +is ever invoked and result rows are ignored. +.Pp +If an error occurs while evaluating the SQL statements passed into +sqlite3_exec(), then execution of the current statement stops and subsequent +statements are skipped. +If the 5th parameter to sqlite3_exec() is not NULL then any error message +is written into memory obtained from +.Fn sqlite3_malloc +and passed back through the 5th parameter. +To avoid memory leaks, the application should invoke +.Fn sqlite3_free +on error message strings returned through the 5th parameter of sqlite3_exec() +after the error message string is no longer needed. +If the 5th parameter to sqlite3_exec() is not NULL and no errors occur, +then sqlite3_exec() sets the pointer in its 5th parameter to NULL before +returning. +.Pp +If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() +routine returns SQLITE_ABORT without invoking the callback again and +without running any subsequent SQL statements. +.Pp +The 2nd argument to the sqlite3_exec() callback function is the number +of columns in the result. +The 3rd argument to the sqlite3_exec() callback is an array of pointers +to strings obtained as if from +.Fn sqlite3_column_text , +one for each column. +If an element of a result row is NULL then the corresponding string +pointer for the sqlite3_exec() callback is a NULL pointer. +The 4th argument to the sqlite3_exec() callback is an array of pointers +to strings where each entry represents the name of corresponding result +column as obtained from +.Fn sqlite3_column_name . +If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer +to an empty string, or a pointer that contains only whitespace and/or +SQL comments, then no SQL statements are evaluated and the database +is not changed. +.Pp +Restrictions: +.Bl -bullet +.It +The application must ensure that the 1st parameter to sqlite3_exec() +is a valid and open database connection. +.It +The application must not close the database connection +specified by the 1st parameter to sqlite3_exec() while sqlite3_exec() +is running. +.It +The application must not modify the SQL statement text passed into +the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 364. +.Bd -literal +SQLITE_API int sqlite3_exec( + sqlite3*, /* An open database */ + const char *sql, /* SQL to be evaluated */ + int (*callback)(void*,int,char**,char**), /* Callback function */ + void *, /* 1st argument to callback */ + char **errmsg /* Error msg written here */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_column_name 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_step 3 diff --git a/static/netbsd/man3/sqlite3_extended_result_codes.3 b/static/netbsd/man3/sqlite3_extended_result_codes.3 new file mode 100644 index 00000000..1fc2854f --- /dev/null +++ b/static/netbsd/man3/sqlite3_extended_result_codes.3 @@ -0,0 +1,23 @@ +.Dd January 24, 2024 +.Dt SQLITE3_EXTENDED_RESULT_CODES 3 +.Os +.Sh NAME +.Nm sqlite3_extended_result_codes +.Nd enable or disable extended result codes +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_extended_result_codes +.Fa "sqlite3*" +.Fa "int onoff" +.Fc +.Sh DESCRIPTION +The sqlite3_extended_result_codes() routine enables or disables the +extended result codes feature of SQLite. +The extended result codes are disabled by default for historical compatibility. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2517. +.Bd -literal +SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); +.Ed diff --git a/static/netbsd/man3/sqlite3_file.3 b/static/netbsd/man3/sqlite3_file.3 new file mode 100644 index 00000000..ba022d47 --- /dev/null +++ b/static/netbsd/man3/sqlite3_file.3 @@ -0,0 +1,30 @@ +.Dd January 24, 2024 +.Dt SQLITE3_FILE 3 +.Os +.Sh NAME +.Nm sqlite3_file , +.Nm sqlite3_file +.Nd OS interface open file handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_file sqlite3_file; +.Vt struct sqlite3_file ; +.Sh DESCRIPTION +An sqlite3_file object represents an open file in the OS interface layer. +Individual OS interface implementations will want to subclass this +object by appending additional fields for their own use. +The pMethods entry is a pointer to an sqlite3_io_methods +object that defines methods for performing I/O operations on the open +file. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 718. +.Bd -literal +typedef struct sqlite3_file sqlite3_file; +struct sqlite3_file { + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_io_methods 3 , +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_file_control.3 b/static/netbsd/man3/sqlite3_file_control.3 new file mode 100644 index 00000000..028f5c76 --- /dev/null +++ b/static/netbsd/man3/sqlite3_file_control.3 @@ -0,0 +1,68 @@ +.Dd January 24, 2024 +.Dt SQLITE3_FILE_CONTROL 3 +.Os +.Sh NAME +.Nm sqlite3_file_control +.Nd low-Level control of database files +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_file_control +.Fa "sqlite3*" +.Fa "const char *zDbName" +.Fa "int op" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The +.Fn sqlite3_file_control +interface makes a direct call to the xFileControl method for the sqlite3_io_methods +object associated with a particular database identified by the second +argument. +The name of the database is "main" for the main database or "temp" +for the TEMP database, or the name that appears after the AS keyword +for databases that are added using the ATTACH SQL command. +A NULL pointer can be used in place of "main" to refer to the main +database file. +The third and fourth parameters to this routine are passed directly +through to the second and third parameters of the xFileControl method. +The return value of the xFileControl method becomes the return value +of this routine. +.Pp +A few opcodes for +.Fn sqlite3_file_control +are handled directly by the SQLite core and never invoke the sqlite3_io_methods.xFileControl +method. +The SQLITE_FCNTL_FILE_POINTER value for the +op parameter causes a pointer to the underlying sqlite3_file +object to be written into the space pointed to by the 4th parameter. +The SQLITE_FCNTL_JOURNAL_POINTER works +similarly except that it returns the sqlite3_file object +associated with the journal file instead of the main database. +The SQLITE_FCNTL_VFS_POINTER opcode returns +a pointer to the underlying sqlite3_vfs object for the file. +The SQLITE_FCNTL_DATA_VERSION returns the +data version counter from the pager. +.Pp +If the second parameter (zDbName) does not match the name of any open +database file, then SQLITE_ERROR is returned. +This error code is not remembered and will not be recalled by +.Fn sqlite3_errcode +or +.Fn sqlite3_errmsg . +The underlying xFileControl method might also return SQLITE_ERROR. +There is no way to distinguish between an incorrect zDbName and an +SQLITE_ERROR return from the underlying xFileControl method. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8221. +.Bd -literal +SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_errcode 3 , +.Xr sqlite3_file 3 , +.Xr sqlite3_io_methods 3 , +.Xr sqlite3_vfs 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 diff --git a/static/netbsd/man3/sqlite3_filename.3 b/static/netbsd/man3/sqlite3_filename.3 new file mode 100644 index 00000000..f55296b9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_filename.3 @@ -0,0 +1,38 @@ +.Dd January 24, 2024 +.Dt SQLITE3_FILENAME 3 +.Os +.Sh NAME +.Nm sqlite3_filename +.Nd file name +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef const char *sqlite3_filename; +.Sh DESCRIPTION +Type sqlite3_filename is used by SQLite to pass filenames +to the xOpen method of a VFS. +It may be cast to (const char*) and treated as a normal, nul-terminated, +UTF-8 buffer containing the filename, but may also be passed to special +APIs such as: +.Bl -bullet +.It +sqlite3_filename_database() +.It +sqlite3_filename_journal() +.It +sqlite3_filename_wal() +.It +sqlite3_uri_parameter() +.It +sqlite3_uri_boolean() +.It +sqlite3_uri_int64() +.It +sqlite3_uri_key() +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1275. +.Bd -literal +typedef const char *sqlite3_filename; +.Ed diff --git a/static/netbsd/man3/sqlite3_filename_database.3 b/static/netbsd/man3/sqlite3_filename_database.3 new file mode 100644 index 00000000..7dfdfbdd --- /dev/null +++ b/static/netbsd/man3/sqlite3_filename_database.3 @@ -0,0 +1,60 @@ +.Dd January 24, 2024 +.Dt SQLITE3_FILENAME_DATABASE 3 +.Os +.Sh NAME +.Nm sqlite3_filename_database , +.Nm sqlite3_filename_journal , +.Nm sqlite3_filename_wal +.Nd translate filenames +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_filename_database +.Fa "sqlite3_filename" +.Fc +.Ft const char * +.Fo sqlite3_filename_journal +.Fa "sqlite3_filename" +.Fc +.Ft const char * +.Fo sqlite3_filename_wal +.Fa "sqlite3_filename" +.Fc +.Sh DESCRIPTION +These routines are available to custom VFS implementations +for translating filenames between the main database file, the journal +file, and the WAL file. +.Pp +If F is the name of an sqlite database file, journal file, or WAL file +passed by the SQLite core into the VFS, then sqlite3_filename_database(F) +returns the name of the corresponding database file. +.Pp +If F is the name of an sqlite database file, journal file, or WAL file +passed by the SQLite core into the VFS, or if F is a database filename +obtained from +.Fn sqlite3_db_filename , +then sqlite3_filename_journal(F) returns the name of the corresponding +rollback journal file. +.Pp +If F is the name of an sqlite database file, journal file, or WAL file +that was passed by the SQLite core into the VFS, or if F is a database +filename obtained from +.Fn sqlite3_db_filename , +then sqlite3_filename_wal(F) returns the name of the corresponding +WAL file. +.Pp +In all of the above, if F is not the name of a database, journal or +WAL filename passed into the VFS from the SQLite core and F is not +the return value from +.Fn sqlite3_db_filename , +then the result is undefined and is likely a memory access violation. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3826. +.Bd -literal +SQLITE_API const char *sqlite3_filename_database(sqlite3_filename); +SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename); +SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_filename 3 diff --git a/static/netbsd/man3/sqlite3_finalize.3 b/static/netbsd/man3/sqlite3_finalize.3 new file mode 100644 index 00000000..ead471e1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_finalize.3 @@ -0,0 +1,46 @@ +.Dd January 24, 2024 +.Dt SQLITE3_FINALIZE 3 +.Os +.Sh NAME +.Nm sqlite3_finalize +.Nd destroy a prepared statement object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_finalize +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_finalize() function is called to delete a prepared statement. +If the most recent evaluation of the statement encountered no errors +or if the statement is never been evaluated, then sqlite3_finalize() +returns SQLITE_OK. +If the most recent evaluation of statement S failed, then sqlite3_finalize(S) +returns the appropriate error code or extended error code. +.Pp +The sqlite3_finalize(S) routine can be called at any point during the +life cycle of prepared statement S: before statement +S is ever evaluated, after one or more calls to +.Fn sqlite3_reset , +or after any call to +.Fn sqlite3_step +regardless of whether or not the statement has completed execution. +.Pp +Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. +.Pp +The application must finalize every prepared statement +in order to avoid resource leaks. +It is a grievous error for the application to try to use a prepared +statement after it has been finalized. +Any use of a prepared statement after it has been finalized can result +in undefined and undesirable behavior such as segfaults and heap corruption. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5265. +.Bd -literal +SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_get_autocommit.3 b/static/netbsd/man3/sqlite3_get_autocommit.3 new file mode 100644 index 00000000..ab69e743 --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_autocommit.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_GET_AUTOCOMMIT 3 +.Os +.Sh NAME +.Nm sqlite3_get_autocommit +.Nd test for auto-Commit mode +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_get_autocommit +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +The sqlite3_get_autocommit() interface returns non-zero or zero if +the given database connection is or is not in autocommit mode, respectively. +Autocommit mode is on by default. +Autocommit mode is disabled by a BEGIN statement. +Autocommit mode is re-enabled by a COMMIT or ROLLBACK. +.Pp +If certain kinds of errors occur on a statement within a multi-statement +transaction (errors including SQLITE_FULL, SQLITE_IOERR, +SQLITE_NOMEM, SQLITE_BUSY, and SQLITE_INTERRUPT) +then the transaction might be rolled back automatically. +The only way to find out whether SQLite automatically rolled back the +transaction after an error is to use this function. +.Pp +If another thread changes the autocommit status of the database connection +while this routine is running, then the return value is undefined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6554. +.Bd -literal +SQLITE_API int sqlite3_get_autocommit(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_get_auxdata.3 b/static/netbsd/man3/sqlite3_get_auxdata.3 new file mode 100644 index 00000000..3220c724 --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_auxdata.3 @@ -0,0 +1,105 @@ +.Dd January 24, 2024 +.Dt SQLITE3_GET_AUXDATA 3 +.Os +.Sh NAME +.Nm sqlite3_get_auxdata , +.Nm sqlite3_set_auxdata +.Nd function auxiliary data +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_get_auxdata +.Fa "sqlite3_context*" +.Fa "int N" +.Fc +.Ft void +.Fo sqlite3_set_auxdata +.Fa "sqlite3_context*" +.Fa "int N" +.Fa "void*" +.Fa "void (*)(void*)" +.Fc +.Sh DESCRIPTION +These functions may be used by (non-aggregate) SQL functions to associate +auxiliary data with argument values. +If the same argument value is passed to multiple invocations of the +same SQL function during query execution, under some circumstances +the associated auxiliary data might be preserved. +An example of where this might be useful is in a regular-expression +matching function. +The compiled version of the regular expression can be stored as auxiliary +data associated with the pattern string. +Then as long as the pattern string remains the same, the compiled regular +expression can be reused on multiple invocations of the same function. +.Pp +The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary +data associated by the sqlite3_set_auxdata(C,N,P,X) function with the +Nth argument value to the application-defined function. +N is zero for the left-most function argument. +If there is no auxiliary data associated with the function argument, +the sqlite3_get_auxdata(C,N) interface returns a NULL pointer. +.Pp +The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data +for the N-th argument of the application-defined function. +Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most +recent sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still +valid or NULL if the auxiliary data has been discarded. +After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, +SQLite will invoke the destructor function X with parameter P exactly +once, when the auxiliary data is discarded. +SQLite is free to discard the auxiliary data at any time, including: +.Bl -bullet +.It +when the corresponding function parameter changes, or +.It +when +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +is called for the SQL statement, or +.It +when sqlite3_set_auxdata() is invoked again on the same parameter, +or +.It +during the original sqlite3_set_auxdata() call when a memory allocation +error occurs. +.It +during the original sqlite3_set_auxdata() call if the function is evaluated +during query planning instead of during query execution, as sometimes +happens with SQLITE_ENABLE_STAT4. +.El +.Pp +Note the last two bullets in particular. +The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, +before the sqlite3_set_auxdata() interface even returns. +Hence sqlite3_set_auxdata() should be called near the end of the function +implementation and the function implementation should not make any +use of P after sqlite3_set_auxdata() has been called. +Furthermore, a call to sqlite3_get_auxdata() that occurs immediately +after a corresponding call to sqlite3_set_auxdata() might still return +NULL if an out-of-memory condition occurred during the sqlite3_set_auxdata() +call or if the function is being evaluated during query planning rather +than during query execution. +.Pp +In practice, auxiliary data is preserved between function calls for +function parameters that are compile-time constants, including literal +values and parameters and expressions composed from the same. +.Pp +The value of the N parameter to these interfaces should be non-negative. +Future enhancements may make use of negative N values to define new +kinds of function caching behavior. +.Pp +These routines must be called from the same thread in which the SQL +function is running. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5903. +.Bd -literal +SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); +SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_get_clientdata 3 , +.Xr sqlite3_reset 3 diff --git a/static/netbsd/man3/sqlite3_get_clientdata.3 b/static/netbsd/man3/sqlite3_get_clientdata.3 new file mode 100644 index 00000000..45777fed --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_clientdata.3 @@ -0,0 +1,85 @@ +.Dd January 24, 2024 +.Dt SQLITE3_GET_CLIENTDATA 3 +.Os +.Sh NAME +.Nm sqlite3_get_clientdata , +.Nm sqlite3_set_clientdata +.Nd database connection client data +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_get_clientdata +.Fa "sqlite3*" +.Fa "const char*" +.Fc +.Ft int +.Fo sqlite3_set_clientdata +.Fa "sqlite3*" +.Fa "const char*" +.Fa "void*" +.Fa "void(*)(void*)" +.Fc +.Sh DESCRIPTION +These functions are used to associate one or more named pointers with +a database connection. +A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P to be +attached to database connection D using name N. +Subsequent calls to sqlite3_get_clientdata(D,N) will return a copy +of pointer P or a NULL pointer if there were no prior calls to sqlite3_set_clientdata() +with the same values of D and N. +Names are compared using strcmp() and are thus case sensitive. +.Pp +If P and X are both non-NULL, then the destructor X is invoked with +argument P on the first of the following occurrences: +.Bl -bullet +.It +An out-of-memory error occurs during the call to sqlite3_set_clientdata() +which attempts to register pointer P. +.It +A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made with the +same D and N parameters. +.It +The database connection closes. +SQLite does not make any guarantees about the order in which destructors +are called, only that all destructors will be called exactly once at +some point during the database connection closing process. +.El +.Pp +SQLite does not do anything with client data other than invoke destructors +on the client data at the appropriate time. +The intended use for client data is to provide a mechanism for wrapper +libraries to store additional information about an SQLite database +connection. +.Pp +There is no limit (other than available memory) on the number of different +client data pointers (with different names) that can be attached to +a single database connection. +However, the implementation is optimized for the case of having only +one or two different client data names. +Applications and wrapper libraries are discouraged from using more +than one client data name each. +.Pp +There is no way to enumerate the client data pointers associated with +a database connection. +The N parameter can be thought of as a secret key such that only code +that knows the secret key is able to access the associated data. +.Pp +Security Warning: These interfaces should not be exposed in scripting +languages or in other circumstances where it might be possible for +an an attacker to invoke them. +Any agent that can invoke these interfaces can probably also take control +of the process. +.Pp +Database connection client data is only available for SQLite version +3.44.0 (dateof:3.44.0) and later. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5973. +.Bd -literal +SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*); +SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*)); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_get_auxdata 3 diff --git a/static/netbsd/man3/sqlite3_get_table.3 b/static/netbsd/man3/sqlite3_get_table.3 new file mode 100644 index 00000000..6e3a30f9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_table.3 @@ -0,0 +1,122 @@ +.Dd January 24, 2024 +.Dt SQLITE3_GET_TABLE 3 +.Os +.Sh NAME +.Nm sqlite3_get_table , +.Nm sqlite3_free_table +.Nd convenience routines for running queries +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_get_table +.Fa "sqlite3 *db" +.Fa "const char *zSql" +.Fa "char ***pazResult" +.Fa "int *pnRow" +.Fa "int *pnColumn" +.Fa "char **pzErrmsg" +.Fc +.Ft void +.Fo sqlite3_free_table +.Fa "char **result" +.Fc +.Sh DESCRIPTION +This is a legacy interface that is preserved for backwards compatibility. +Use of this interface is not recommended. +.Pp +Definition: A \fBresult table\fP is memory data structure created by the +.Fn sqlite3_get_table +interface. +A result table records the complete query results from one or more +queries. +.Pp +The table conceptually has a number of rows and columns. +But these numbers are not part of the result table itself. +These numbers are obtained separately. +Let N be the number of rows and M be the number of columns. +.Pp +A result table is an array of pointers to zero-terminated UTF-8 strings. +There are (N+1)*M elements in the array. +The first M pointers point to zero-terminated strings that contain +the names of the columns. +The remaining entries all point to query results. +NULL values result in NULL pointers. +All other values are in their UTF-8 zero-terminated string representation +as returned by +.Fn sqlite3_column_text . +A result table might consist of one or more memory allocations. +It is not safe to pass a result table directly to +.Fn sqlite3_free . +A result table should be deallocated using +.Fn sqlite3_free_table . +As an example of the result table format, suppose a query result is +as follows: +.Bd -ragged +.Bd -literal +Name | Age ----------------------- Alice | 43 Bob +| 28 Cindy | 21 +.Ed +.Pp +.Ed +.Pp +There are two columns (M==2) and three rows (N==3). +Thus the result table has 8 entries. +Suppose the result table is stored in an array named azResult. +Then azResult holds this content: +.Bd -ragged +.Bd -literal +azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3] += "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy"; +azResult[7] = "21"; +.Ed +.Pp +.Ed +.Pp +The sqlite3_get_table() function evaluates one or more semicolon-separated +SQL statements in the zero-terminated UTF-8 string of its 2nd parameter +and returns a result table to the pointer given in its 3rd parameter. +.Pp +After the application has finished with the result from sqlite3_get_table(), +it must pass the result table pointer to sqlite3_free_table() in order +to release the memory that was malloced. +Because of the way the +.Fn sqlite3_malloc +happens within sqlite3_get_table(), the calling function must not try +to call +.Fn sqlite3_free +directly. +Only +.Fn sqlite3_free_table +is able to release the memory properly and safely. +.Pp +The sqlite3_get_table() interface is implemented as a wrapper around +.Fn sqlite3_exec . +The sqlite3_get_table() routine does not have access to any internal +data structures of SQLite. +It uses only the public interface defined here. +As a consequence, errors that occur in the wrapper layer outside of +the internal +.Fn sqlite3_exec +call are not reflected in subsequent calls to +.Fn sqlite3_errcode +or +.Fn sqlite3_errmsg . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2865. +.Bd -literal +SQLITE_API int sqlite3_get_table( + sqlite3 *db, /* An open database */ + const char *zSql, /* SQL to be evaluated */ + char ***pazResult, /* Results of the query */ + int *pnRow, /* Number of result rows written here */ + int *pnColumn, /* Number of result columns written here */ + char **pzErrmsg /* Error msg written here */ +); +SQLITE_API void sqlite3_free_table(char **result); +.Ed +.Sh SEE ALSO +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_exec 3 , +.Xr sqlite3_malloc 3 diff --git a/static/netbsd/man3/sqlite3_index_info.3 b/static/netbsd/man3/sqlite3_index_info.3 new file mode 100644 index 00000000..bc238a7f --- /dev/null +++ b/static/netbsd/man3/sqlite3_index_info.3 @@ -0,0 +1,153 @@ +.Dd January 24, 2024 +.Dt SQLITE3_INDEX_INFO 3 +.Os +.Sh NAME +.Nm sqlite3_index_info +.Nd virtual table indexing information +.Sh SYNOPSIS +.In sqlite3.h +.Vt struct sqlite3_index_info ; +.Sh DESCRIPTION +The sqlite3_index_info structure and its substructures is used as part +of the virtual table interface to pass information into +and receive the reply from the xBestIndex method of a virtual table module. +The fields under **Inputs** are the inputs to xBestIndex and are read-only. +xBestIndex inserts its results into the **Outputs** fields. +.Pp +The aConstraint[] array records WHERE clause constraints of the form: +.Bd -ragged +column OP expr +.Ed +.Pp +where OP is =, <, <=, >, or >=. +The particular operator is stored in aConstraint[].op using one of +the SQLITE_INDEX_CONSTRAINT_ values. +The index of the column is stored in aConstraint[].iColumn. +aConstraint[].usable is TRUE if the expr on the right-hand side can +be evaluated (and thus the constraint is usable) and false if it cannot. +.Pp +The optimizer automatically inverts terms of the form "expr OP column" +and makes other simplifications to the WHERE clause in an attempt to +get as many WHERE clause terms into the form shown above as possible. +The aConstraint[] array only reports WHERE clause terms that are relevant +to the particular virtual table being queried. +.Pp +Information about the ORDER BY clause is stored in aOrderBy[]. +Each term of aOrderBy records a column of the ORDER BY clause. +.Pp +The colUsed field indicates which columns of the virtual table may +be required by the current scan. +Virtual table columns are numbered from zero in the order in which +they appear within the CREATE TABLE statement passed to sqlite3_declare_vtab(). +For the first 63 columns (columns 0-62), the corresponding bit is set +within the colUsed mask if the column may be required by SQLite. +If the table has at least 64 columns and any column to the right of +the first 63 is required, then bit 63 of colUsed is also set. +In other words, column iCol may be required if the expression (colUsed +& ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to non-zero. +.Pp +The xBestIndex method must fill aConstraintUsage[] with information +about what parameters to pass to xFilter. +If argvIndex>0 then the right-hand side of the corresponding aConstraint[] +is evaluated and becomes the argvIndex-th entry in argv. +If aConstraintUsage[].omit is true, then the constraint is assumed +to be fully handled by the virtual table and might not be checked again +by the byte code. +The aConstraintUsage[].omit flag is an optimization hint. +When the omit flag is left in its default setting of false, the constraint +will always be checked separately in byte code. +If the omit flag is change to true, then the constraint may or may +not be checked in byte code. +In other words, when the omit flag is true there is no guarantee that +the constraint will not be checked again using byte code. +.Pp +The idxNum and idxStr values are recorded and passed into the xFilter +method. +.Fn sqlite3_free +is used to free idxStr if and only if needToFreeIdxStr is true. +.Pp +The orderByConsumed means that output from xFilter/xNext +will occur in the correct order to satisfy the ORDER BY clause so that +no separate sorting step is required. +.Pp +The estimatedCost value is an estimate of the cost of a particular +strategy. +A cost of N indicates that the cost of the strategy is similar to a +linear scan of an SQLite table with N rows. +A cost of log(N) indicates that the expense of the operation is similar +to that of a binary search on a unique indexed field of an SQLite table +with N rows. +.Pp +The estimatedRows value is an estimate of the number of rows that will +be returned by the strategy. +.Pp +The xBestIndex method may optionally populate the idxFlags field with +a mask of SQLITE_INDEX_SCAN_* flags. +Currently there is only one such flag - SQLITE_INDEX_SCAN_UNIQUE. +If the xBestIndex method sets this flag, SQLite assumes that the strategy +may visit at most one row. +.Pp +Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, +then SQLite also assumes that if a call to the xUpdate() method is +made as part of the same statement to delete or update a virtual table +row and the implementation returns SQLITE_CONSTRAINT, then there is +no need to rollback any database changes. +In other words, if the xUpdate() returns SQLITE_CONSTRAINT, the database +contents must be exactly as they were before xUpdate was called. +By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not set and xUpdate returns +SQLITE_CONSTRAINT, any database changes made by the xUpdate method +are automatically rolled back by SQLite. +.Pp +IMPORTANT: The estimatedRows field was added to the sqlite3_index_info +structure for SQLite version 3.8.2 (dateof:3.8.2). +If a virtual table extension is used with an SQLite version earlier +than 3.8.2, the results of attempting to read or write the estimatedRows +field are undefined (but are likely to include crashing the application). +The estimatedRows field should therefore only be used if +.Fn sqlite3_libversion_number +returns a value greater than or equal to 3008002. +Similarly, the idxFlags field was added for version 3.9.0 +(dateof:3.9.0). +It may therefore only be used if sqlite3_libversion_number() returns +a value greater than or equal to 3009000. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7331. +.Bd -literal +struct sqlite3_index_info { + /* Inputs */ + int nConstraint; /* Number of entries in aConstraint */ + struct sqlite3_index_constraint { + int iColumn; /* Column constrained. -1 for ROWID */ + unsigned char op; /* Constraint operator */ + unsigned char usable; /* True if this constraint is usable */ + int iTermOffset; /* Used internally - xBestIndex should ignore */ + } *aConstraint; /* Table of WHERE clause constraints */ + int nOrderBy; /* Number of terms in the ORDER BY clause */ + struct sqlite3_index_orderby { + int iColumn; /* Column number */ + unsigned char desc; /* True for DESC. False for ASC. */ + } *aOrderBy; /* The ORDER BY clause */ + /* Outputs */ + struct sqlite3_index_constraint_usage { + int argvIndex; /* if >0, constraint is part of argv to xFilter */ + unsigned char omit; /* Do not code a test for this constraint */ + } *aConstraintUsage; + int idxNum; /* Number used to identify the index */ + char *idxStr; /* String, possibly obtained from sqlite3_malloc */ + int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ + int orderByConsumed; /* True if output is already ordered */ + double estimatedCost; /* Estimated cost of using this index */ + /* Fields below are only available in SQLite 3.8.2 and later */ + sqlite3_int64 estimatedRows; /* Estimated number of rows returned */ + /* Fields below are only available in SQLite 3.9.0 and later */ + int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */ + /* Fields below are only available in SQLite 3.10.0 and later */ + sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3_module 3 , +.Xr sqlite3_version 3 , +.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 diff --git a/static/netbsd/man3/sqlite3_initialize.3 b/static/netbsd/man3/sqlite3_initialize.3 new file mode 100644 index 00000000..8e3dd9b7 --- /dev/null +++ b/static/netbsd/man3/sqlite3_initialize.3 @@ -0,0 +1,120 @@ +.Dd January 24, 2024 +.Dt SQLITE3_INITIALIZE 3 +.Os +.Sh NAME +.Nm sqlite3_initialize , +.Nm sqlite3_shutdown , +.Nm sqlite3_os_init , +.Nm sqlite3_os_end +.Nd initialize the SQLite library +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_initialize +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_shutdown +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_os_init +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_os_end +.Fa "void" +.Fc +.Sh DESCRIPTION +The sqlite3_initialize() routine initializes the SQLite library. +The sqlite3_shutdown() routine deallocates any resources that were +allocated by sqlite3_initialize(). +These routines are designed to aid in process initialization and shutdown +on embedded systems. +Workstation applications using SQLite normally do not need to invoke +either of these routines. +.Pp +A call to sqlite3_initialize() is an "effective" call if it is the +first time sqlite3_initialize() is invoked during the lifetime of the +process, or if it is the first time sqlite3_initialize() is invoked +following a call to sqlite3_shutdown(). +Only an effective call of sqlite3_initialize() does any initialization. +All other calls are harmless no-ops. +.Pp +A call to sqlite3_shutdown() is an "effective" call if it is the first +call to sqlite3_shutdown() since the last sqlite3_initialize(). +Only an effective call to sqlite3_shutdown() does any deinitialization. +All other valid calls to sqlite3_shutdown() are harmless no-ops. +.Pp +The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() +is not. +The sqlite3_shutdown() interface must only be called from a single +thread. +All open database connections must be closed and +all other SQLite resources must be deallocated prior to invoking sqlite3_shutdown(). +.Pp +Among other things, sqlite3_initialize() will invoke sqlite3_os_init(). +Similarly, sqlite3_shutdown() will invoke sqlite3_os_end(). +.Pp +The sqlite3_initialize() routine returns SQLITE_OK on success. +If for some reason, sqlite3_initialize() is unable to initialize the +library (perhaps it is unable to allocate a needed resource such as +a mutex) it returns an error code other than SQLITE_OK. +.Pp +The sqlite3_initialize() routine is called internally by many other +SQLite interfaces so that an application usually does not need to invoke +sqlite3_initialize() directly. +For example, +.Fn sqlite3_open +calls sqlite3_initialize() so the SQLite library will be automatically +initialized when +.Fn sqlite3_open +is called if it has not be initialized already. +However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT +compile-time option, then the automatic calls to sqlite3_initialize() +are omitted and the application must call sqlite3_initialize() directly +prior to using any other SQLite interface. +For maximum portability, it is recommended that applications always +invoke sqlite3_initialize() directly prior to using any other SQLite +interface. +Future releases of SQLite may require this. +In other words, the behavior exhibited when SQLite is compiled with +SQLITE_OMIT_AUTOINIT might become the default behavior +in some future release of SQLite. +.Pp +The sqlite3_os_init() routine does operating-system specific initialization +of the SQLite library. +The sqlite3_os_end() routine undoes the effect of sqlite3_os_init(). +Typical tasks performed by these routines include allocation or deallocation +of static resources, initialization of global variables, setting up +a default sqlite3_vfs module, or setting up a default configuration +using +.Fn sqlite3_config . +The application should never invoke either sqlite3_os_init() or sqlite3_os_end() +directly. +The application should only invoke sqlite3_initialize() and sqlite3_shutdown(). +The sqlite3_os_init() interface is called automatically by sqlite3_initialize() +and sqlite3_os_end() is called by sqlite3_shutdown(). +Appropriate implementations for sqlite3_os_init() and sqlite3_os_end() +are built into SQLite when it is compiled for Unix, Windows, or OS/2. +When built for other platforms (using the +SQLITE_OS_OTHER=1 compile-time option) the application +must supply a suitable implementation for sqlite3_os_init() and sqlite3_os_end(). +An application-supplied implementation of sqlite3_os_init() or sqlite3_os_end() +must return SQLITE_OK on success and some other error code +upon failure. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1567. +.Bd -literal +SQLITE_API int sqlite3_initialize(void); +SQLITE_API int sqlite3_shutdown(void); +SQLITE_API int sqlite3_os_init(void); +SQLITE_API int sqlite3_os_end(void); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_config 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_vfs 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_interrupt.3 b/static/netbsd/man3/sqlite3_interrupt.3 new file mode 100644 index 00000000..91c65a45 --- /dev/null +++ b/static/netbsd/man3/sqlite3_interrupt.3 @@ -0,0 +1,63 @@ +.Dd January 24, 2024 +.Dt SQLITE3_INTERRUPT 3 +.Os +.Sh NAME +.Nm sqlite3_interrupt , +.Nm sqlite3_is_interrupted +.Nd interrupt a long-Running query +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_interrupt +.Fa "sqlite3*" +.Fc +.Ft int +.Fo sqlite3_is_interrupted +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +This function causes any pending database operation to abort and return +at its earliest opportunity. +This routine is typically called in response to a user action such +as pressing "Cancel" or Ctrl-C where the user wants a long query operation +to halt immediately. +.Pp +It is safe to call this routine from a thread different from the thread +that is currently running the database operation. +But it is not safe to call this routine with a database connection +that is closed or might close before sqlite3_interrupt() returns. +.Pp +If an SQL operation is very nearly finished at the time when sqlite3_interrupt() +is called, then it might not have an opportunity to be interrupted +and might continue to completion. +.Pp +An SQL operation that is interrupted will return SQLITE_INTERRUPT. +If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that +is inside an explicit transaction, then the entire transaction will +be rolled back automatically. +.Pp +The sqlite3_interrupt(D) call is in effect until all currently running +SQL statements on database connection D complete. +Any new SQL statements that are started after the sqlite3_interrupt() +call and before the running statement count reaches zero are interrupted +as if they had been running prior to the sqlite3_interrupt() call. +New SQL statements that are started after the running statement count +reaches zero are not effected by the sqlite3_interrupt(). +A call to sqlite3_interrupt(D) that occurs when there are no running +SQL statements is a no-op and has no effect on SQL statements that +are started after the sqlite3_interrupt() call returns. +.Pp +The sqlite3_is_interrupted(D) interface can +be used to determine whether or not an interrupt is currently in effect +for database connection D. +It returns 1 if an interrupt is currently in effect, or 0 otherwise. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2703. +.Bd -literal +SQLITE_API void sqlite3_interrupt(sqlite3*); +SQLITE_API int sqlite3_is_interrupted(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_io_methods.3 b/static/netbsd/man3/sqlite3_io_methods.3 new file mode 100644 index 00000000..20c8e232 --- /dev/null +++ b/static/netbsd/man3/sqlite3_io_methods.3 @@ -0,0 +1,176 @@ +.Dd January 24, 2024 +.Dt SQLITE3_IO_METHODS 3 +.Os +.Sh NAME +.Nm sqlite3_io_methods , +.Nm sqlite3_io_methods +.Nd OS interface file virtual methods object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_io_methods sqlite3_io_methods; +.Vt struct sqlite3_io_methods ; +.Sh DESCRIPTION +Every file opened by the sqlite3_vfs.xOpen method +populates an sqlite3_file object (or, more commonly, a +subclass of the sqlite3_file object) with a pointer to +an instance of this object. +This object defines the methods used to perform various operations +against the open file represented by the sqlite3_file object. +.Pp +If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods +element to a non-NULL pointer, then the sqlite3_io_methods.xClose method +may be invoked even if the sqlite3_vfs.xOpen reported +that it failed. +The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen +is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods +element to NULL. +.Pp +The flags argument to xSync may be one of SQLITE_SYNC_NORMAL +or SQLITE_SYNC_FULL. +The first choice is the normal fsync(). +The second choice is a Mac OS X style fullsync. +The SQLITE_SYNC_DATAONLY flag may be ORed in to +indicate that only the data of the file and not its inode needs to +be synced. +.Pp +The integer values to xLock() and xUnlock() are one of +.Bl -bullet +.It +SQLITE_LOCK_NONE, +.It +SQLITE_LOCK_SHARED, +.It +SQLITE_LOCK_RESERVED, +.It +SQLITE_LOCK_PENDING, or +.It +SQLITE_LOCK_EXCLUSIVE. +.El +.Pp +xLock() upgrades the database file lock. +In other words, xLock() moves the database file lock in the direction +NONE toward EXCLUSIVE. +The argument to xLock() is always on of SHARED, RESERVED, PENDING, +or EXCLUSIVE, never SQLITE_LOCK_NONE. +If the database file lock is already at or above the requested lock, +then the call to xLock() is a no-op. +xUnlock() downgrades the database file lock to either SHARED or NONE. +If the lock is already at or below the requested lock state, then the +call to xUnlock() is a no-op. +The xCheckReservedLock() method checks whether any database connection, +either in this process or in some other process, is holding a RESERVED, +PENDING, or EXCLUSIVE lock on the file. +It returns true if such a lock exists and false otherwise. +.Pp +The xFileControl() method is a generic interface that allows custom +VFS implementations to directly control an open file using the +.Fn sqlite3_file_control +interface. +The second "op" argument is an integer opcode. +The third argument is a generic pointer intended to point to a structure +that may contain arguments or space in which to write return values. +Potential uses for xFileControl() might be functions to enable blocking +locks with timeouts, to change the locking strategy (for example to +use dot-file locks), to inquire about the status of a lock, or to break +stale locks. +The SQLite core reserves all opcodes less than 100 for its own use. +A list of opcodes less than 100 is available. +Applications that define a custom xFileControl method should use opcodes +greater than 100 to avoid conflicts. +VFS implementations should return SQLITE_NOTFOUND for +file control opcodes that they do not recognize. +.Pp +The xSectorSize() method returns the sector size of the device that +underlies the file. +The sector size is the minimum write that can be performed without +disturbing other bytes in the file. +The xDeviceCharacteristics() method returns a bit vector describing +behaviors of the underlying device: +.Bl -bullet +.It +SQLITE_IOCAP_ATOMIC +.It +SQLITE_IOCAP_ATOMIC512 +.It +SQLITE_IOCAP_ATOMIC1K +.It +SQLITE_IOCAP_ATOMIC2K +.It +SQLITE_IOCAP_ATOMIC4K +.It +SQLITE_IOCAP_ATOMIC8K +.It +SQLITE_IOCAP_ATOMIC16K +.It +SQLITE_IOCAP_ATOMIC32K +.It +SQLITE_IOCAP_ATOMIC64K +.It +SQLITE_IOCAP_SAFE_APPEND +.It +SQLITE_IOCAP_SEQUENTIAL +.It +SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN +.It +SQLITE_IOCAP_POWERSAFE_OVERWRITE +.It +SQLITE_IOCAP_IMMUTABLE +.It +SQLITE_IOCAP_BATCH_ATOMIC +.El +.Pp +The SQLITE_IOCAP_ATOMIC property means that all writes of any size +are atomic. +The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are +nnn bytes in size and are aligned to an address which is an integer +multiple of nnn are atomic. +The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended +to a file, the data is appended first then the size of the file is +extended, never the other way around. +The SQLITE_IOCAP_SEQUENTIAL property means that information is written +to disk in the same order as calls to xWrite(). +.Pp +If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the +unread portions of the buffer with zeros. +A VFS that fails to zero-fill short reads might seem to work. +However, failure to zero-fill short reads will eventually lead to database +corruption. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 734. +.Bd -literal +typedef struct sqlite3_io_methods sqlite3_io_methods; +struct sqlite3_io_methods { + int iVersion; + int (*xClose)(sqlite3_file*); + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); + int (*xSync)(sqlite3_file*, int flags); + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); + int (*xLock)(sqlite3_file*, int); + int (*xUnlock)(sqlite3_file*, int); + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); + int (*xFileControl)(sqlite3_file*, int op, void *pArg); + int (*xSectorSize)(sqlite3_file*); + int (*xDeviceCharacteristics)(sqlite3_file*); + /* Methods above are valid for version 1 */ + int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); + int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); + void (*xShmBarrier)(sqlite3_file*); + int (*xShmUnmap)(sqlite3_file*, int deleteFlag); + /* Methods above are valid for version 2 */ + int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp); + int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p); + /* Methods above are valid for version 3 */ + /* Additional methods may be added in future releases */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_file 3 , +.Xr sqlite3_file_control 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 , +.Xr SQLITE_IOCAP_ATOMIC 3 , +.Xr SQLITE_LOCK_NONE 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_SYNC_NORMAL 3 diff --git a/static/netbsd/man3/sqlite3_keyword_count.3 b/static/netbsd/man3/sqlite3_keyword_count.3 new file mode 100644 index 00000000..0f6e8fb9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_keyword_count.3 @@ -0,0 +1,84 @@ +.Dd January 24, 2024 +.Dt SQLITE3_KEYWORD_COUNT 3 +.Os +.Sh NAME +.Nm sqlite3_keyword_count , +.Nm sqlite3_keyword_name , +.Nm sqlite3_keyword_check +.Nd SQL keyword checking +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_keyword_count +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_keyword_name +.Fa "int" +.Fa "const char**" +.Fa "int*" +.Fc +.Ft int +.Fo sqlite3_keyword_check +.Fa "const char*" +.Fa "int" +.Fc +.Sh DESCRIPTION +These routines provide access to the set of SQL language keywords recognized +by SQLite. +Applications can uses these routines to determine whether or not a +specific identifier needs to be escaped (for example, by enclosing +in double-quotes) so as not to confuse the parser. +.Pp +The sqlite3_keyword_count() interface returns the number of distinct +keywords understood by SQLite. +.Pp +The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and +makes *Z point to that keyword expressed as UTF8 and writes the number +of bytes in the keyword into *L. +The string that *Z points to is not zero-terminated. +The sqlite3_keyword_name(N,Z,L) routine returns SQLITE_OK if N is within +bounds and SQLITE_ERROR if not. +If either Z or L are NULL or invalid pointers then calls to sqlite3_keyword_name(N,Z,L) +result in undefined behavior. +.Pp +The sqlite3_keyword_check(Z,L) interface checks to see whether or not +the L-byte UTF8 identifier that Z points to is a keyword, returning +non-zero if it is and zero if not. +.Pp +The parser used by SQLite is forgiving. +It is often possible to use a keyword as an identifier as long as such +use does not result in a parsing ambiguity. +For example, the statement "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" +is accepted by SQLite, and creates a new table named "BEGIN" with three +columns named "REPLACE", "PRAGMA", and "END". +Nevertheless, best practice is to avoid using keywords as identifiers. +Common techniques used to avoid keyword name collisions include: +.Bl -bullet +.It +Put all identifier names inside double-quotes. +This is the official SQL way to escape identifier names. +.It +Put identifier names inside [...]. +This is not standard SQL, but it is what SQL Server does and so lots +of programmers use this technique. +.It +Begin every identifier with the letter "Z" as no SQL keywords start +with "Z". +.It +Include a digit somewhere in every identifier name. +.El +.Pp +Note that the number of keywords understood by SQLite can depend on +compile-time options. +For example, "VACUUM" is not a keyword if SQLite is compiled with the +-DSQLITE_OMIT_VACUUM option. +Also, new keywords may be added to future releases of SQLite. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8331. +.Bd -literal +SQLITE_API int sqlite3_keyword_count(void); +SQLITE_API int sqlite3_keyword_name(int,const char**,int*); +SQLITE_API int sqlite3_keyword_check(const char*,int); +.Ed diff --git a/static/netbsd/man3/sqlite3_last_insert_rowid.3 b/static/netbsd/man3/sqlite3_last_insert_rowid.3 new file mode 100644 index 00000000..8cf84230 --- /dev/null +++ b/static/netbsd/man3/sqlite3_last_insert_rowid.3 @@ -0,0 +1,79 @@ +.Dd January 24, 2024 +.Dt SQLITE3_LAST_INSERT_ROWID 3 +.Os +.Sh NAME +.Nm sqlite3_last_insert_rowid +.Nd last insert rowid +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_int64 +.Fo sqlite3_last_insert_rowid +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +Each entry in most SQLite tables (except for WITHOUT ROWID +tables) has a unique 64-bit signed integer key called the "rowid". +The rowid is always available as an undeclared column named ROWID, +OID, or _ROWID_ as long as those names are not also used by explicitly +declared columns. +If the table has a column of type INTEGER PRIMARY KEY +then that column is another alias for the rowid. +.Pp +The sqlite3_last_insert_rowid(D) interface usually returns the rowid +of the most recent successful INSERT into a rowid table or virtual table +on database connection D. +Inserts into WITHOUT ROWID tables are not recorded. +If no successful INSERTs into rowid tables have ever occurred +on the database connection D, then sqlite3_last_insert_rowid(D) returns +zero. +.Pp +As well as being set automatically as rows are inserted into database +tables, the value returned by this function may be set explicitly by +.Fn sqlite3_set_last_insert_rowid +Some virtual table implementations may INSERT rows into rowid tables +as part of committing a transaction (e.g. to flush data accumulated +in memory to disk). +In this case subsequent calls to this function return the rowid associated +with these internal INSERT operations, which leads to unintuitive results. +Virtual table implementations that do write to rowid tables in this +way can avoid this problem by restoring the original rowid value using +.Fn sqlite3_set_last_insert_rowid +before returning control to the user. +.Pp +If an INSERT occurs within a trigger then this routine will return +the rowid of the inserted row as long as the trigger is running. +Once the trigger program ends, the value returned by this routine reverts +to what it was before the trigger was fired. +.Pp +An INSERT that fails due to a constraint violation is not a successful +INSERT and does not change the value returned by this routine. +Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT +OR ABORT make no changes to the return value of this routine when their +insertion fails. +When INSERT OR REPLACE encounters a constraint violation, it does not +fail. +The INSERT continues to completion after deleting rows that caused +the constraint problem so INSERT OR REPLACE will always change the +return value of this interface. +.Pp +For the purposes of this routine, an INSERT is considered to +be successful even if it is subsequently rolled back. +.Pp +This function is accessible to SQL statements via the last_insert_rowid() SQL function. +.Pp +If a separate thread performs a new INSERT on the same database +connection while the +.Fn sqlite3_last_insert_rowid +function is running and thus changes the last insert rowid, then +the value returned by +.Fn sqlite3_last_insert_rowid +is unpredictable and might not equal either the old or the new last +insert rowid. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2527. +.Bd -literal +SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_set_last_insert_rowid 3 diff --git a/static/netbsd/man3/sqlite3_limit.3 b/static/netbsd/man3/sqlite3_limit.3 new file mode 100644 index 00000000..5e4774f6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_limit.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_LIMIT 3 +.Os +.Sh NAME +.Nm sqlite3_limit +.Nd run-time limits +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_limit +.Fa "sqlite3*" +.Fa "int id" +.Fa "int newVal" +.Fc +.Sh DESCRIPTION +This interface allows the size of various constructs to be limited +on a connection by connection basis. +The first parameter is the database connection whose +limit is to be set or queried. +The second parameter is one of the limit categories +that define a class of constructs to be size limited. +The third parameter is the new limit for that construct. +.Pp +If the new limit is a negative number, the limit is unchanged. +For each limit category SQLITE_LIMIT_\fINAME\fP there is a hard upper bound +set at compile-time by a C preprocessor macro called SQLITE_MAX_<i>NAME</i>. +(The "_LIMIT_" in the name is changed to "_MAX_".) Attempts to increase +a limit above its hard upper bound are silently truncated to the hard +upper bound. +.Pp +Regardless of whether or not the limit was changed, the +.Fn sqlite3_limit +interface returns the prior value of the limit. +Hence, to find the current value of a limit without changing it, simply +invoke this interface with the third parameter set to -1. +.Pp +Run-time limits are intended for use in applications that manage both +their own internal database and also databases that are controlled +by untrusted external sources. +An example application might be a web browser that has its own databases +for storing history and separate databases controlled by JavaScript +applications downloaded off the Internet. +The internal databases can be given the large, default limits. +Databases managed by external sources can be given much smaller limits +designed to prevent a denial of service attack. +Developers might also want to use the +.Fn sqlite3_set_authorizer +interface to further control untrusted SQL. +The size of the database created by an untrusted script can be contained +using the max_page_count PRAGMA. +.Pp +New run-time limit categories may be added in future releases. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4026. +.Bd -literal +SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_set_authorizer 3 diff --git a/static/netbsd/man3/sqlite3_load_extension.3 b/static/netbsd/man3/sqlite3_load_extension.3 new file mode 100644 index 00000000..c8bf84a1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_load_extension.3 @@ -0,0 +1,75 @@ +.Dd January 24, 2024 +.Dt SQLITE3_LOAD_EXTENSION 3 +.Os +.Sh NAME +.Nm sqlite3_load_extension +.Nd load an extension +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_load_extension +.Fa "sqlite3 *db" +.Fa "const char *zFile" +.Fa "const char *zProc" +.Fa "char **pzErrMsg" +.Fc +.Sh DESCRIPTION +This interface loads an SQLite extension library from the named file. +.Pp +The sqlite3_load_extension() interface attempts to load an SQLite extension +library contained in the file zFile. +If the file cannot be loaded directly, attempts are made to load with +various operating-system specific extensions added. +So for example, if "samplelib" cannot be loaded, then names like "samplelib.so" +or "samplelib.dylib" or "samplelib.dll" might be tried also. +.Pp +The entry point is zProc. +zProc may be 0, in which case SQLite will try to come up with an entry +point name on its own. +It first tries "sqlite3_extension_init". +If that does not work, it constructs a name "sqlite3_X_init" where +the X is consists of the lower-case equivalent of all ASCII alphabetic +characters in the filename from the last "/" to the first following +"." and omitting any initial "lib". +The sqlite3_load_extension() interface returns SQLITE_OK on +success and SQLITE_ERROR if something goes wrong. +If an error occurs and pzErrMsg is not 0, then the +.Fn sqlite3_load_extension +interface shall attempt to fill *pzErrMsg with error message text stored +in memory obtained from +.Fn sqlite3_malloc . +The calling function should free this memory by calling +.Fn sqlite3_free . +Extension loading must be enabled using +.Fn sqlite3_enable_load_extension +or sqlite3_db_config(db,SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL) +prior to calling this API, otherwise an error will be returned. +.Pp +\fBSecurity warning:\fP It is recommended that the SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION +method be used to enable only this interface. +The use of the +.Fn sqlite3_enable_load_extension +interface should be avoided. +This will keep the SQL function +.Fn load_extension +disabled and prevent SQL injections from giving attackers access to +extension loading capabilities. +.Pp +See also the load_extension() SQL function. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7129. +.Bd -literal +SQLITE_API int sqlite3_load_extension( + sqlite3 *db, /* Load the extension into this database connection */ + const char *zFile, /* Name of the shared library containing extension */ + const char *zProc, /* Entry point. Derived from zFile if 0 */ + char **pzErrMsg /* Put error message here if not 0 */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_config 3 , +.Xr sqlite3_enable_load_extension 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_DBCONFIG_MAINDBNAME 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_log.3 b/static/netbsd/man3/sqlite3_log.3 new file mode 100644 index 00000000..f642542e --- /dev/null +++ b/static/netbsd/man3/sqlite3_log.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE3_LOG 3 +.Os +.Sh NAME +.Nm sqlite3_log +.Nd error logging interface +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_log +.Fa "int iErrCode" +.Fa "const char *zFormat" +.Fa "..." +.Fc +.Sh DESCRIPTION +The +.Fn sqlite3_log +interface writes a message into the error log established +by the SQLITE_CONFIG_LOG option to +.Fn sqlite3_config . +If logging is enabled, the zFormat string and subsequent arguments +are used with +.Fn sqlite3_snprintf +to generate the final output string. +.Pp +The sqlite3_log() interface is intended for use by extensions such +as virtual tables, collating functions, and SQL functions. +While there is nothing to prevent an application from calling sqlite3_log(), +doing so is considered bad form. +.Pp +The zFormat string must not be NULL. +.Pp +To avoid deadlocks and other threading problems, the sqlite3_log() +routine will not use dynamically allocated memory. +The log message is stored in a fixed-length buffer on the stack. +If the log message is longer than a few hundred characters, it will +be truncated to the length of the buffer. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9489. +.Bd -literal +SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...); +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr sqlite3_mprintf 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/sqlite3_malloc.3 b/static/netbsd/man3/sqlite3_malloc.3 new file mode 100644 index 00000000..0a5fd072 --- /dev/null +++ b/static/netbsd/man3/sqlite3_malloc.3 @@ -0,0 +1,128 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MALLOC 3 +.Os +.Sh NAME +.Nm sqlite3_malloc , +.Nm sqlite3_malloc64 , +.Nm sqlite3_realloc , +.Nm sqlite3_realloc64 , +.Nm sqlite3_free , +.Nm sqlite3_msize +.Nd memory allocation subsystem +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_malloc +.Fa "int" +.Fc +.Ft void * +.Fo sqlite3_malloc64 +.Fa "sqlite3_uint64" +.Fc +.Ft void * +.Fo sqlite3_realloc +.Fa "void*" +.Fa "int" +.Fc +.Ft void * +.Fo sqlite3_realloc64 +.Fa "void*" +.Fa "sqlite3_uint64" +.Fc +.Ft void +.Fo sqlite3_free +.Fa "void*" +.Fc +.Ft sqlite3_uint64 +.Fo sqlite3_msize +.Fa "void*" +.Fc +.Sh DESCRIPTION +The SQLite core uses these three routines for all of its own internal +memory allocation needs. +"Core" in the previous sentence does not include operating-system specific +VFS implementation. +The Windows VFS uses native malloc() and free() for some operations. +.Pp +The sqlite3_malloc() routine returns a pointer to a block of memory +at least N bytes in length, where N is the parameter. +If sqlite3_malloc() is unable to obtain sufficient free memory, it +returns a NULL pointer. +If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() +returns a NULL pointer. +.Pp +The sqlite3_malloc64(N) routine works just like sqlite3_malloc(N) except +that N is an unsigned 64-bit integer instead of a signed 32-bit integer. +.Pp +Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() +or sqlite3_realloc() releases that memory so that it might be reused. +The sqlite3_free() routine is a no-op if is called with a NULL pointer. +Passing a NULL pointer to sqlite3_free() is harmless. +After being freed, memory should neither be read nor written. +Even reading previously freed memory might result in a segmentation +fault or other severe error. +Memory corruption, a segmentation fault, or other severe error might +result if sqlite3_free() is called with a non-NULL pointer that was +not obtained from sqlite3_malloc() or sqlite3_realloc(). +.Pp +The sqlite3_realloc(X,N) interface attempts to resize a prior memory +allocation X to be at least N bytes. +If the X parameter to sqlite3_realloc(X,N) is a NULL pointer then its +behavior is identical to calling sqlite3_malloc(N). +If the N parameter to sqlite3_realloc(X,N) is zero or negative then +the behavior is exactly the same as calling sqlite3_free(X). +sqlite3_realloc(X,N) returns a pointer to a memory allocation of at +least N bytes in size or NULL if insufficient memory is available. +If M is the size of the prior allocation, then min(N,M) bytes of the +prior allocation are copied into the beginning of buffer returned by +sqlite3_realloc(X,N) and the prior allocation is freed. +If sqlite3_realloc(X,N) returns NULL and N is positive, then the prior +allocation is not freed. +.Pp +The sqlite3_realloc64(X,N) interfaces works the same as sqlite3_realloc(X,N) +except that N is a 64-bit unsigned integer instead of a 32-bit signed +integer. +.Pp +If X is a memory allocation previously obtained from sqlite3_malloc(), +sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then +sqlite3_msize(X) returns the size of that memory allocation in bytes. +The value returned by sqlite3_msize(X) might be larger than the number +of bytes requested when X was allocated. +If X is a NULL pointer then sqlite3_msize(X) returns zero. +If X points to something that is not the beginning of memory allocation, +or if it points to a formerly valid memory allocation that has now +been freed, then the behavior of sqlite3_msize(X) is undefined and +possibly harmful. +.Pp +The memory returned by sqlite3_malloc(), sqlite3_realloc(), sqlite3_malloc64(), +and sqlite3_realloc64() is always aligned to at least an 8 byte boundary, +or to a 4 byte boundary if the SQLITE_4_BYTE_ALIGNED_MALLOC +compile-time option is used. +.Pp +The pointer arguments to +.Fn sqlite3_free +and +.Fn sqlite3_realloc +must be either NULL or else pointers obtained from a prior invocation +of +.Fn sqlite3_malloc +or +.Fn sqlite3_realloc +that have not yet been released. +.Pp +The application must not read or write any part of a block of memory +after it has been released using +.Fn sqlite3_free +or +.Fn sqlite3_realloc . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2993. +.Bd -literal +SQLITE_API void *sqlite3_malloc(int); +SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); +SQLITE_API void *sqlite3_realloc(void*, int); +SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); +SQLITE_API void sqlite3_free(void*); +SQLITE_API sqlite3_uint64 sqlite3_msize(void*); +.Ed diff --git a/static/netbsd/man3/sqlite3_mem_methods.3 b/static/netbsd/man3/sqlite3_mem_methods.3 new file mode 100644 index 00000000..a18d4b46 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mem_methods.3 @@ -0,0 +1,102 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MEM_METHODS 3 +.Os +.Sh NAME +.Nm sqlite3_mem_methods , +.Nm sqlite3_mem_methods +.Nd memory allocation routines +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_mem_methods sqlite3_mem_methods; +.Vt struct sqlite3_mem_methods ; +.Sh DESCRIPTION +An instance of this object defines the interface between SQLite and +low-level memory allocation routines. +.Pp +This object is used in only one place in the SQLite interface. +A pointer to an instance of this object is the argument to +.Fn sqlite3_config +when the configuration option is SQLITE_CONFIG_MALLOC +or SQLITE_CONFIG_GETMALLOC. +By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC) +during configuration, an application can specify an alternative memory +allocation subsystem for SQLite to use for all of its dynamic memory +needs. +.Pp +Note that SQLite comes with several built-in memory allocators +that are perfectly adequate for the overwhelming majority of applications +and that this object is only useful to a tiny minority of applications +with specialized memory allocation requirements. +This object is also used during testing of SQLite in order to specify +an alternative memory allocator that simulates memory out-of-memory +conditions in order to verify that SQLite recovers gracefully from +such conditions. +.Pp +The xMalloc, xRealloc, and xFree methods must work like the malloc(), +realloc() and free() functions from the standard C library. +SQLite guarantees that the second argument to xRealloc is always a +value returned by a prior call to xRoundup. +.Pp +xSize should return the allocated size of a memory allocation previously +obtained from xMalloc or xRealloc. +The allocated size is always at least as big as the requested size +but may be larger. +.Pp +The xRoundup method returns what would be the allocated size of a memory +allocation given a particular requested size. +Most memory allocators round up memory allocations at least to the +next multiple of 8. +Some allocators round up to a larger multiple or to a power of 2. +Every memory allocation request coming in through +.Fn sqlite3_malloc +or +.Fn sqlite3_realloc +first calls xRoundup. +If xRoundup returns 0, that causes the corresponding memory allocation +to fail. +.Pp +The xInit method initializes the memory allocator. +For example, it might allocate any required mutexes or initialize internal +data structures. +The xShutdown method is invoked (indirectly) by +.Fn sqlite3_shutdown +and should deallocate any resources acquired by xInit. +The pAppData pointer is used as the only parameter to xInit and xShutdown. +.Pp +SQLite holds the SQLITE_MUTEX_STATIC_MAIN mutex +when it invokes the xInit method, so the xInit method need not be threadsafe. +The xShutdown method is only called from +.Fn sqlite3_shutdown +so it does not need to be threadsafe either. +For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM +mutex as long as the SQLITE_CONFIG_MEMSTATUS +configuration option is turned on (which it is by default) and so the +methods are automatically serialized. +However, if SQLITE_CONFIG_MEMSTATUS is disabled, +then the other methods must be threadsafe or else make their own arrangements +for serialization. +.Pp +SQLite will never invoke xInit() more than once without an intervening +call to xShutdown(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1702. +.Bd -literal +typedef struct sqlite3_mem_methods sqlite3_mem_methods; +struct sqlite3_mem_methods { + void *(*xMalloc)(int); /* Memory allocation function */ + void (*xFree)(void*); /* Free a prior allocation */ + void *(*xRealloc)(void*,int); /* Resize an allocation */ + int (*xSize)(void*); /* Return the size of an allocation */ + int (*xRoundup)(int); /* Round up request size to allocation size */ + int (*xInit)(void*); /* Initialize the memory allocator */ + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ + void *pAppData; /* Argument to xInit() and xShutdown() */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr sqlite3_initialize 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_MUTEX_FAST 3 diff --git a/static/netbsd/man3/sqlite3_memory_used.3 b/static/netbsd/man3/sqlite3_memory_used.3 new file mode 100644 index 00000000..dca1ebd4 --- /dev/null +++ b/static/netbsd/man3/sqlite3_memory_used.3 @@ -0,0 +1,62 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MEMORY_USED 3 +.Os +.Sh NAME +.Nm sqlite3_memory_used , +.Nm sqlite3_memory_highwater +.Nd memory allocator statistics +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_int64 +.Fo sqlite3_memory_used +.Fa "void" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_memory_highwater +.Fa "int resetFlag" +.Fc +.Sh DESCRIPTION +SQLite provides these two interfaces for reporting on the status of +the +.Fn sqlite3_malloc , +.Fn sqlite3_free , +and +.Fn sqlite3_realloc +routines, which form the built-in memory allocation subsystem. +.Pp +The +.Fn sqlite3_memory_used +routine returns the number of bytes of memory currently outstanding +(malloced but not freed). +The +.Fn sqlite3_memory_highwater +routine returns the maximum value of +.Fn sqlite3_memory_used +since the high-water mark was last reset. +The values returned by +.Fn sqlite3_memory_used +and +.Fn sqlite3_memory_highwater +include any overhead added by SQLite in its implementation of +.Fn sqlite3_malloc , +but not overhead added by the any underlying system library routines +that +.Fn sqlite3_malloc +may call. +.Pp +The memory high-water mark is reset to the current value of +.Fn sqlite3_memory_used +if and only if the parameter to +.Fn sqlite3_memory_highwater +is true. +The value returned by sqlite3_memory_highwater(1) +is the high-water mark prior to the reset. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3075. +.Bd -literal +SQLITE_API sqlite3_int64 sqlite3_memory_used(void); +SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 diff --git a/static/netbsd/man3/sqlite3_module.3 b/static/netbsd/man3/sqlite3_module.3 new file mode 100644 index 00000000..380fc844 --- /dev/null +++ b/static/netbsd/man3/sqlite3_module.3 @@ -0,0 +1,72 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MODULE 3 +.Os +.Sh NAME +.Nm sqlite3_module +.Nd virtual table object +.Sh SYNOPSIS +.In sqlite3.h +.Vt struct sqlite3_module ; +.Sh DESCRIPTION +This structure, sometimes called a "virtual table module", defines +the implementation of a virtual table. +This structure consists mostly of methods for the module. +.Pp +A virtual table module is created by filling in a persistent instance +of this structure and passing a pointer to that instance to +.Fn sqlite3_create_module +or +.Fn sqlite3_create_module_v2 . +The registration remains valid until it is replaced by a different +module or until the database connection closes. +The content of this structure must not change while it is registered +with any database connection. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7273. +.Bd -literal +struct sqlite3_module { + int iVersion; + int (*xCreate)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xConnect)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); + int (*xDisconnect)(sqlite3_vtab *pVTab); + int (*xDestroy)(sqlite3_vtab *pVTab); + int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); + int (*xClose)(sqlite3_vtab_cursor*); + int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, + int argc, sqlite3_value **argv); + int (*xNext)(sqlite3_vtab_cursor*); + int (*xEof)(sqlite3_vtab_cursor*); + int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); + int (*xBegin)(sqlite3_vtab *pVTab); + int (*xSync)(sqlite3_vtab *pVTab); + int (*xCommit)(sqlite3_vtab *pVTab); + int (*xRollback)(sqlite3_vtab *pVTab); + int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, + void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), + void **ppArg); + int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); + /* The methods above are in version 1 of the sqlite_module object. Those + ** below are for version 2 and greater. */ + int (*xSavepoint)(sqlite3_vtab *pVTab, int); + int (*xRelease)(sqlite3_vtab *pVTab, int); + int (*xRollbackTo)(sqlite3_vtab *pVTab, int); + /* The methods above are in versions 1 and 2 of the sqlite_module object. + ** Those below are for version 3 and greater. */ + int (*xShadowName)(const char*); + /* The methods above are in versions 1 through 3 of the sqlite_module object. + ** Those below are for version 4 and greater. */ + int (*xIntegrity)(sqlite3_vtab *pVTab, const char *zSchema, + const char *zTabName, int mFlags, char **pzErr); +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_create_module 3 diff --git a/static/netbsd/man3/sqlite3_mprintf.3 b/static/netbsd/man3/sqlite3_mprintf.3 new file mode 100644 index 00000000..48ff3a70 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mprintf.3 @@ -0,0 +1,86 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MPRINTF 3 +.Os +.Sh NAME +.Nm sqlite3_mprintf , +.Nm sqlite3_vmprintf , +.Nm sqlite3_snprintf , +.Nm sqlite3_vsnprintf +.Nd formatted string printing functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft char * +.Fo sqlite3_mprintf +.Fa "const char*" +.Fa "..." +.Fc +.Ft char * +.Fo sqlite3_vmprintf +.Fa "const char*" +.Fa "va_list" +.Fc +.Ft char * +.Fo sqlite3_snprintf +.Fa "int" +.Fa "char*" +.Fa "const char*" +.Fa "..." +.Fc +.Ft char * +.Fo sqlite3_vsnprintf +.Fa "int" +.Fa "char*" +.Fa "const char*" +.Fa "va_list" +.Fc +.Sh DESCRIPTION +These routines are work-alikes of the "printf()" family of functions +from the standard C library. +These routines understand most of the common formatting options from +the standard library printf() plus some additional non-standard formats +(%q, %Q, %w, and %z). +See the +.Fn built-in printf +documentation for details. +.Pp +The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results +into memory obtained from +.Fn sqlite3_malloc64 . +The strings returned by these two routines should be released by +.Fn sqlite3_free . +Both routines return a NULL pointer if +.Fn sqlite3_malloc64 +is unable to allocate enough memory to hold the resulting string. +.Pp +The sqlite3_snprintf() routine is similar to "snprintf()" from the +standard C library. +The result is written into the buffer supplied as the second parameter +whose size is given by the first parameter. +Note that the order of the first two parameters is reversed from snprintf(). +This is an historical accident that cannot be fixed without breaking +backwards compatibility. +Note also that sqlite3_snprintf() returns a pointer to its buffer instead +of the number of characters actually written into the buffer. +We admit that the number of characters written would be a more useful +return value but we cannot change the implementation of sqlite3_snprintf() +now without breaking compatibility. +.Pp +As long as the buffer size is greater than zero, sqlite3_snprintf() +guarantees that the buffer is always zero-terminated. +The first parameter "n" is the total size of the buffer, including +space for the zero terminator. +So the longest string that can be completely written will be n-1 characters. +.Pp +The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2948. +.Bd -literal +SQLITE_API char *sqlite3_mprintf(const char*,...); +SQLITE_API char *sqlite3_vmprintf(const char*, va_list); +SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); +SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 diff --git a/static/netbsd/man3/sqlite3_mutex.3 b/static/netbsd/man3/sqlite3_mutex.3 new file mode 100644 index 00000000..309b7c36 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mutex.3 @@ -0,0 +1,25 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MUTEX 3 +.Os +.Sh NAME +.Nm sqlite3_mutex +.Nd mutex handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_mutex sqlite3_mutex; +.Sh DESCRIPTION +The mutex module within SQLite defines sqlite3_mutex to +be an abstract type for a mutex object. +The SQLite core never looks at the internal representation of an sqlite3_mutex. +It only deals with pointers to the sqlite3_mutex object. +.Pp +Mutexes are created using +.Fn sqlite3_mutex_alloc . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1253. +.Bd -literal +typedef struct sqlite3_mutex sqlite3_mutex; +.Ed +.Sh SEE ALSO +.Xr sqlite3_mutex_alloc 3 diff --git a/static/netbsd/man3/sqlite3_mutex_alloc.3 b/static/netbsd/man3/sqlite3_mutex_alloc.3 new file mode 100644 index 00000000..3d000fd6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mutex_alloc.3 @@ -0,0 +1,175 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MUTEX_ALLOC 3 +.Os +.Sh NAME +.Nm sqlite3_mutex_alloc , +.Nm sqlite3_mutex_free , +.Nm sqlite3_mutex_enter , +.Nm sqlite3_mutex_try , +.Nm sqlite3_mutex_leave +.Nd mutexes +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_mutex * +.Fo sqlite3_mutex_alloc +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_mutex_free +.Fa "sqlite3_mutex*" +.Fc +.Ft void +.Fo sqlite3_mutex_enter +.Fa "sqlite3_mutex*" +.Fc +.Ft int +.Fo sqlite3_mutex_try +.Fa "sqlite3_mutex*" +.Fc +.Ft void +.Fo sqlite3_mutex_leave +.Fa "sqlite3_mutex*" +.Fc +.Sh DESCRIPTION +The SQLite core uses these routines for thread synchronization. +Though they are intended for internal use by SQLite, code that links +against SQLite is permitted to use any of these routines. +.Pp +The SQLite source code contains multiple implementations of these mutex +routines. +An appropriate implementation is selected automatically at compile-time. +The following implementations are available in the SQLite core: +.Bl -bullet +.It +SQLITE_MUTEX_PTHREADS +.It +SQLITE_MUTEX_W32 +.It +SQLITE_MUTEX_NOOP +.El +.Pp +The SQLITE_MUTEX_NOOP implementation is a set of routines that does +no real locking and is appropriate for use in a single-threaded application. +The SQLITE_MUTEX_PTHREADS and SQLITE_MUTEX_W32 implementations are +appropriate for use on Unix and Windows. +.Pp +If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor macro +defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex implementation +is included with the library. +In this case the application must supply a custom mutex implementation +using the SQLITE_CONFIG_MUTEX option of the sqlite3_config() +function before calling sqlite3_initialize() or any other public sqlite3_ +function that calls sqlite3_initialize(). +.Pp +The sqlite3_mutex_alloc() routine allocates a new mutex and returns +a pointer to it. +The sqlite3_mutex_alloc() routine returns NULL if it is unable to allocate +the requested mutex. +The argument to sqlite3_mutex_alloc() must one of these integer constants: +.Bl -bullet +.It +SQLITE_MUTEX_FAST +.It +SQLITE_MUTEX_RECURSIVE +.It +SQLITE_MUTEX_STATIC_MAIN +.It +SQLITE_MUTEX_STATIC_MEM +.It +SQLITE_MUTEX_STATIC_OPEN +.It +SQLITE_MUTEX_STATIC_PRNG +.It +SQLITE_MUTEX_STATIC_LRU +.It +SQLITE_MUTEX_STATIC_PMEM +.It +SQLITE_MUTEX_STATIC_APP1 +.It +SQLITE_MUTEX_STATIC_APP2 +.It +SQLITE_MUTEX_STATIC_APP3 +.It +SQLITE_MUTEX_STATIC_VFS1 +.It +SQLITE_MUTEX_STATIC_VFS2 +.It +SQLITE_MUTEX_STATIC_VFS3 +.El +.Pp +The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) +cause sqlite3_mutex_alloc() to create a new mutex. +The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but +not necessarily so when SQLITE_MUTEX_FAST is used. +The mutex implementation does not need to make a distinction between +SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. +SQLite will only request a recursive mutex in cases where it really +needs one. +If a faster non-recursive mutex implementation is available on the +host platform, the mutex subsystem might return such a mutex in response +to SQLITE_MUTEX_FAST. +.Pp +The other allowed parameters to sqlite3_mutex_alloc() (anything other +than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer +to a static preexisting mutex. +Nine static mutexes are used by the current version of SQLite. +Future versions of SQLite may add additional static mutexes. +Static mutexes are for internal use by SQLite only. +Applications that use SQLite mutexes should use only the dynamic mutexes +returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE. +.Pp +Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST +or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns +a different mutex on every call. +For the static mutex types, the same mutex is returned on every call +that has the same type number. +.Pp +The sqlite3_mutex_free() routine deallocates a previously allocated +dynamic mutex. +Attempting to deallocate a static mutex results in undefined behavior. +.Pp +The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt +to enter a mutex. +If another thread is already within the mutex, sqlite3_mutex_enter() +will block and sqlite3_mutex_try() will return SQLITE_BUSY. +The sqlite3_mutex_try() interface returns SQLITE_OK upon successful +entry. +Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple +times by the same thread. +In such cases, the mutex must be exited an equal number of times before +another thread can enter. +If the same thread tries to enter any mutex other than an SQLITE_MUTEX_RECURSIVE +more than once, the behavior is undefined. +.Pp +Some systems (for example, Windows 95) do not support the operation +implemented by sqlite3_mutex_try(). +On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. +In most cases the SQLite core only uses sqlite3_mutex_try() as an optimization, +so this is acceptable behavior. +The exceptions are unix builds that set the SQLITE_ENABLE_SETLK_TIMEOUT +build option. +In that case a working sqlite3_mutex_try() is required. +.Pp +The sqlite3_mutex_leave() routine exits a mutex that was previously +entered by the same thread. +The behavior is undefined if the mutex is not currently entered by +the calling thread or is not currently allocated. +.Pp +If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave(), +or sqlite3_mutex_free() is a NULL pointer, then any of the four routines +behaves as a no-op. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7944. +.Bd -literal +SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); +SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); +SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); +SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); +SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_mutex_held 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_mutex_held.3 b/static/netbsd/man3/sqlite3_mutex_held.3 new file mode 100644 index 00000000..9555de7a --- /dev/null +++ b/static/netbsd/man3/sqlite3_mutex_held.3 @@ -0,0 +1,55 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MUTEX_HELD 3 +.Os +.Sh NAME +.Nm sqlite3_mutex_held , +.Nm sqlite3_mutex_notheld +.Nd mutex verification routines +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_mutex_held +.Fa "sqlite3_mutex*" +.Fc +.Ft int +.Fo sqlite3_mutex_notheld +.Fa "sqlite3_mutex*" +.Fc +.Sh DESCRIPTION +The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended +for use inside assert() statements. +The SQLite core never uses these routines except inside an assert() +and applications are advised to follow the lead of the core. +The SQLite core only provides implementations for these routines when +it is compiled with the SQLITE_DEBUG flag. +External mutex implementations are only required to provide these routines +if SQLITE_DEBUG is defined and if NDEBUG is not defined. +.Pp +These routines should return true if the mutex in their argument is +held or not held, respectively, by the calling thread. +.Pp +The implementation is not required to provide versions of these routines +that actually work. +If the implementation does not provide working versions of these routines, +it should at least provide stubs that always return true so that one +does not get spurious assertion failures. +.Pp +If the argument to sqlite3_mutex_held() is a NULL pointer then the +routine should return 1. +This seems counter-intuitive since clearly the mutex cannot be held +if it does not exist. +But the reason the mutex does not exist is because the build is not +using mutexes. +And we do not want the assert() containing the call to sqlite3_mutex_held() +to fail, so a non-zero return is the appropriate thing to do. +The sqlite3_mutex_notheld() interface should also return 1 when given +a NULL pointer. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8144. +.Bd -literal +#ifndef NDEBUG +SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); +SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); +#endif +.Ed diff --git a/static/netbsd/man3/sqlite3_mutex_methods.3 b/static/netbsd/man3/sqlite3_mutex_methods.3 new file mode 100644 index 00000000..bbd22124 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mutex_methods.3 @@ -0,0 +1,108 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MUTEX_METHODS 3 +.Os +.Sh NAME +.Nm sqlite3_mutex_methods , +.Nm sqlite3_mutex_methods +.Nd mutex methods object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; +.Vt struct sqlite3_mutex_methods ; +.Sh DESCRIPTION +An instance of this structure defines the low-level routines used to +allocate and use mutexes. +.Pp +Usually, the default mutex implementations provided by SQLite are sufficient, +however the application has the option of substituting a custom implementation +for specialized deployments or systems for which SQLite does not provide +a suitable implementation. +In this case, the application creates and populates an instance of +this structure to pass to sqlite3_config() along with the SQLITE_CONFIG_MUTEX +option. +Additionally, an instance of this structure can be used as an output +variable when querying the system for the current mutex implementation, +using the SQLITE_CONFIG_GETMUTEX option. +.Pp +The xMutexInit method defined by this structure is invoked as part +of system initialization by the sqlite3_initialize() function. +The xMutexInit routine is called by SQLite exactly once for each effective +call to +.Fn sqlite3_initialize . +The xMutexEnd method defined by this structure is invoked as part of +system shutdown by the sqlite3_shutdown() function. +The implementation of this method is expected to release all outstanding +resources obtained by the mutex methods implementation, especially +those obtained by the xMutexInit method. +The xMutexEnd() interface is invoked exactly once for each call to +.Fn sqlite3_shutdown . +The remaining seven methods defined by this structure (xMutexAlloc, +xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and xMutexNotheld) +implement the following interfaces (respectively): +.Bl -bullet +.It +.Fn sqlite3_mutex_alloc +.It +.Fn sqlite3_mutex_free +.It +.Fn sqlite3_mutex_enter +.It +.Fn sqlite3_mutex_try +.It +.Fn sqlite3_mutex_leave +.It +.Fn sqlite3_mutex_held +.It +.Fn sqlite3_mutex_notheld +.El +.Pp +The only difference is that the public sqlite3_XXX functions enumerated +above silently ignore any invocations that pass a NULL pointer instead +of a valid mutex handle. +The implementations of the methods defined by this structure are not +required to handle this case. +The results of passing a NULL pointer instead of a valid mutex handle +are undefined (i.e. it is acceptable to provide an implementation that +segfaults if it is passed a NULL pointer). +.Pp +The xMutexInit() method must be threadsafe. +It must be harmless to invoke xMutexInit() multiple times within the +same process and without intervening calls to xMutexEnd(). +Second and subsequent calls to xMutexInit() must be no-ops. +.Pp +xMutexInit() must not use SQLite memory allocation ( +.Fn sqlite3_malloc +and its associates). +Similarly, xMutexAlloc() must not use SQLite memory allocation for +a static mutex. +However xMutexAlloc() may use SQLite memory allocation for a fast or +recursive mutex. +.Pp +SQLite will invoke the xMutexEnd() method when +.Fn sqlite3_shutdown +is called, but only if the prior call to xMutexInit returned SQLITE_OK. +If xMutexInit fails in any way, it is expected to clean up after itself +prior to returning. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8066. +.Bd -literal +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; +struct sqlite3_mutex_methods { + int (*xMutexInit)(void); + int (*xMutexEnd)(void); + sqlite3_mutex *(*xMutexAlloc)(int); + void (*xMutexFree)(sqlite3_mutex *); + void (*xMutexEnter)(sqlite3_mutex *); + int (*xMutexTry)(sqlite3_mutex *); + void (*xMutexLeave)(sqlite3_mutex *); + int (*xMutexHeld)(sqlite3_mutex *); + int (*xMutexNotheld)(sqlite3_mutex *); +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_initialize 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mutex_alloc 3 , +.Xr sqlite3_mutex_held 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/sqlite3_next_stmt.3 b/static/netbsd/man3/sqlite3_next_stmt.3 new file mode 100644 index 00000000..6840f985 --- /dev/null +++ b/static/netbsd/man3/sqlite3_next_stmt.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3_NEXT_STMT 3 +.Os +.Sh NAME +.Nm sqlite3_next_stmt +.Nd find the next prepared statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_stmt * +.Fo sqlite3_next_stmt +.Fa "sqlite3 *pDb" +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +This interface returns a pointer to the next prepared statement +after pStmt associated with the database connection +pDb. +If pStmt is NULL then this interface returns a pointer to the first +prepared statement associated with the database connection pDb. +If no prepared statement satisfies the conditions of this routine, +it returns NULL. +.Pp +The database connection pointer D in a call to sqlite3_next_stmt(D,S) +must refer to an open database connection and in particular must not +be a NULL pointer. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6706. +.Bd -literal +SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_open.3 b/static/netbsd/man3/sqlite3_open.3 new file mode 100644 index 00000000..63581d34 --- /dev/null +++ b/static/netbsd/man3/sqlite3_open.3 @@ -0,0 +1,335 @@ +.Dd January 24, 2024 +.Dt SQLITE3_OPEN 3 +.Os +.Sh NAME +.Nm sqlite3_open , +.Nm sqlite3_open16 , +.Nm sqlite3_open_v2 +.Nd opening a new database connection +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_open +.Fa "const char *filename" +.Fa "sqlite3 **ppDb" +.Fc +.Ft int +.Fo sqlite3_open16 +.Fa "const void *filename" +.Fa "sqlite3 **ppDb" +.Fc +.Ft int +.Fo sqlite3_open_v2 +.Fa "const char *filename" +.Fa "sqlite3 **ppDb" +.Fa "int flags" +.Fa "const char *zVfs" +.Fc +.Sh DESCRIPTION +These routines open an SQLite database file as specified by the filename +argument. +The filename argument is interpreted as UTF-8 for sqlite3_open() and +sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). +A database connection handle is usually returned +in *ppDb, even if an error occurs. +The only exception is that if SQLite is unable to allocate memory to +hold the sqlite3 object, a NULL will be written into *ppDb instead +of a pointer to the sqlite3 object. +If the database is opened (and/or created) successfully, then SQLITE_OK +is returned. +Otherwise an error code is returned. +The +.Fn sqlite3_errmsg +or +.Fn sqlite3_errmsg16 +routines can be used to obtain an English language description of the +error following a failure of any of the sqlite3_open() routines. +.Pp +The default encoding will be UTF-8 for databases created using sqlite3_open() +or sqlite3_open_v2(). +The default encoding for databases created using sqlite3_open16() will +be UTF-16 in the native byte order. +.Pp +Whether or not an error occurs when it is opened, resources associated +with the database connection handle should be released +by passing it to +.Fn sqlite3_close +when it is no longer required. +.Pp +The sqlite3_open_v2() interface works like sqlite3_open() except that +it accepts two additional parameters for additional control over the +new database connection. +The flags parameter to sqlite3_open_v2() must include, at a minimum, +one of the following three flag combinations: +.Bl -tag -width Ds +.It SQLITE_OPEN_READONLY +The database is opened in read-only mode. +If the database does not already exist, an error is returned. +.It SQLITE_OPEN_READWRITE +The database is opened for reading and writing if possible, or reading +only if the file is write protected by the operating system. +In either case the database must already exist, otherwise an error +is returned. +For historical reasons, if opening in read-write mode fails due to +OS-level permissions, an attempt is made to open it in read-only mode. +.Fn sqlite3_db_readonly +can be used to determine whether the database is actually read-write. +.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE +The database is opened for reading and writing, and is created if it +does not already exist. +This is the behavior that is always used for sqlite3_open() and sqlite3_open16(). +.El +.Pp +In addition to the required flags, the following optional flags are +also supported: +.Bl -tag -width Ds +.It SQLITE_OPEN_URI +The filename can be interpreted as a URI if this flag is set. +.It SQLITE_OPEN_MEMORY +The database will be opened as an in-memory database. +The database is named by the "filename" argument for the purposes of +cache-sharing, if shared cache mode is enabled, but the "filename" +is otherwise ignored. +.It SQLITE_OPEN_NOMUTEX +The new database connection will use the "multi-thread" threading mode. +This means that separate threads are allowed to use SQLite at the same +time, as long as each thread is using a different database connection. +.It SQLITE_OPEN_FULLMUTEX +The new database connection will use the "serialized" threading mode. +This means the multiple threads can safely attempt to use the same +database connection at the same time. +(Mutexes will block any actual concurrency, but in this mode there +is no harm in trying.) +.It SQLITE_OPEN_SHAREDCACHE +The database is opened shared cache enabled, overriding +the default shared cache setting provided by +.Fn sqlite3_enable_shared_cache . +The use of shared cache mode is discouraged +and hence shared cache capabilities may be omitted from many builds +of SQLite. +In such cases, this option is a no-op. +.It SQLITE_OPEN_PRIVATECACHE +The database is opened shared cache disabled, overriding +the default shared cache setting provided by +.Fn sqlite3_enable_shared_cache . +.It SQLITE_OPEN_EXRESCODE +The database connection comes up in "extended result code mode". +In other words, the database behaves has if sqlite3_extended_result_codes(db,1) +where called on the database connection as soon as the connection is +created. +In addition to setting the extended result code mode, this flag also +causes +.Fn sqlite3_open_v2 +to return an extended result code. +.It SQLITE_OPEN_NOFOLLOW +The database filename is not allowed to contain a symbolic link +.El +.Pp +If the 3rd parameter to sqlite3_open_v2() is not one of the required +combinations shown above optionally combined with other SQLITE_OPEN_* bits +then the behavior is undefined. +Historic versions of SQLite have silently ignored surplus bits in the +flags parameter to sqlite3_open_v2(), however that behavior might not +be carried through into future versions of SQLite and so applications +should not rely upon it. +Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op for +sqlite3_open_v2(). +The SQLITE_OPEN_EXCLUSIVE does *not* cause the open to fail if the +database already exists. +The SQLITE_OPEN_EXCLUSIVE flag is intended for use by the VFS interface +only, and not by sqlite3_open_v2(). +.Pp +The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs +object that defines the operating system interface that the new database +connection should use. +If the fourth parameter is a NULL pointer then the default sqlite3_vfs +object is used. +.Pp +If the filename is ":memory:", then a private, temporary in-memory +database is created for the connection. +This in-memory database will vanish when the database connection is +closed. +Future versions of SQLite might make use of additional special filenames +that begin with the ":" character. +It is recommended that when a database filename actually does begin +with a ":" character you should prefix the filename with a pathname +such as "./" to avoid ambiguity. +.Pp +If the filename is an empty string, then a private, temporary on-disk +database will be created. +This private database will be automatically deleted as soon as the +database connection is closed. +.Ss URI Filenames +If URI filename interpretation is enabled, and the filename +argument begins with "file:", then the filename is interpreted as a +URI. +URI filename interpretation is enabled if the SQLITE_OPEN_URI +flag is set in the third argument to sqlite3_open_v2(), or if it has +been enabled globally using the SQLITE_CONFIG_URI +option with the +.Fn sqlite3_config +method or by the SQLITE_USE_URI compile-time option. +URI filename interpretation is turned off by default, but future releases +of SQLite might enable URI filename interpretation by default. +See "URI filenames" for additional information. +.Pp +URI filenames are parsed according to RFC 3986. +If the URI contains an authority, then it must be either an empty string +or the string "localhost". +If the authority is not an empty string or "localhost", an error is +returned to the caller. +The fragment component of a URI, if present, is ignored. +.Pp +SQLite uses the path component of the URI as the name of the disk file +which contains the database. +If the path begins with a '/' character, then it is interpreted as +an absolute path. +If the path does not begin with a '/' (meaning that the authority section +is omitted from the URI) then the path is interpreted as a relative +path. +On windows, the first component of an absolute path is a drive specification +(e.g. "C:"). +.Pp +The query component of a URI may contain parameters that are interpreted +either by SQLite itself, or by a custom VFS implementation. +SQLite and its built-in VFSes interpret the following query parameters: +.Bl -bullet +.It +\fBvfs\fP: The "vfs" parameter may be used to specify the name of a VFS object +that provides the operating system interface that should be used to +access the database file on disk. +If this option is set to an empty string the default VFS object is +used. +Specifying an unknown VFS is an error. +If sqlite3_open_v2() is used and the vfs option is present, then the +VFS specified by the option takes precedence over the value passed +as the fourth parameter to sqlite3_open_v2(). +.It +\fBmode\fP: The mode parameter may be set to either "ro", "rw", "rwc", or +"memory". +Attempting to set it to any other value is an error. +If "ro" is specified, then the database is opened for read-only access, +just as if the SQLITE_OPEN_READONLY flag had been +set in the third argument to sqlite3_open_v2(). +If the mode option is set to "rw", then the database is opened for +read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but +not SQLITE_OPEN_CREATE) had been set. +Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and +SQLITE_OPEN_CREATE. +If the mode option is set to "memory" then a pure in-memory database +that never reads or writes from disk is used. +It is an error to specify a value for the mode parameter that is less +restrictive than that specified by the flags passed in the third parameter +to sqlite3_open_v2(). +.It +\fBcache\fP: The cache parameter may be set to either "shared" or "private". +Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE +bit in the flags argument passed to sqlite3_open_v2(). +Setting the cache parameter to "private" is equivalent to setting the +SQLITE_OPEN_PRIVATECACHE bit. +If sqlite3_open_v2() is used and the "cache" parameter is present in +a URI filename, its value overrides any behavior requested by setting +SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. +.It +\fBpsow\fP: The psow parameter indicates whether or not the powersafe overwrite +property does or does not apply to the storage media on which the database +file resides. +.It +\fBnolock\fP: The nolock parameter is a boolean query parameter which if +set disables file locking in rollback journal modes. +This is useful for accessing a database on a filesystem that does not +support locking. +Caution: Database corruption might result if two or more processes +write to the same database and any one of those processes uses nolock=1. +.It +\fBimmutable\fP: The immutable parameter is a boolean query parameter that +indicates that the database file is stored on read-only media. +When immutable is set, SQLite assumes that the database file cannot +be changed, even by a process with higher privilege, and so the database +is opened read-only and all locking and change detection is disabled. +Caution: Setting the immutable property on a database file that does +in fact change can result in incorrect query results and/or SQLITE_CORRUPT +errors. +.El +.Pp +Specifying an unknown parameter in the query component of a URI is +not an error. +Future versions of SQLite might understand additional query parameters. +See "query parameters with special meaning to SQLite" +for additional information. +.Ss URI filename examples +.Pp + URI filenames Results + file:data.db Open the file "data.db" in the current directory. + file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db + Open the database file "/home/fred/data.db". + file://darkstar/home/fred/data.db An error. +"darkstar" is not a recognized authority. + file:///C:/Documents%20and%20Settings/fred/Desktop/data.db Windows +only: Open the file "data.db" on fred's desktop on drive C:. +Note that the %20 escaping in this example is not strictly necessary +- space characters can be used literally in URI filenames. + file:data.db?mode=ro&cache=private Open file "data.db" in the current +directory for read-only access. +Regardless of whether or not shared-cache mode is enabled by default, +use a private cache. + file:/home/fred/data.db?vfs=unix-dotfile Open file "/home/fred/data.db". +Use the special VFS "unix-dotfile" that uses dot-files in place of +posix advisory locking. + file:data.db?mode=readonly An error. +"readonly" is not a valid option for the "mode" parameter. +Use "ro" instead: "file:data.db?mode=ro". +.Pp +URI hexadecimal escape sequences (%HH) are supported within the path +and query components of a URI. +A hexadecimal escape sequence consists of a percent sign - "%" - followed +by exactly two hexadecimal digits specifying an octet value. +Before the path or query components of a URI filename are interpreted, +they are encoded using UTF-8 and all hexadecimal escape sequences replaced +by a single byte containing the corresponding octet. +If this process generates an invalid UTF-8 encoding, the results are +undefined. +.Pp +\fBNote to Windows users:\fP The encoding used for the filename argument +of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever +codepage is currently defined. +Filenames containing international characters must be converted to +UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2(). +.Pp +\fBNote to Windows Runtime users:\fP The temporary directory must be set +prior to calling sqlite3_open() or sqlite3_open_v2(). +Otherwise, various features that require the use of temporary files +may fail. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3462. +.Bd -literal +SQLITE_API int sqlite3_open( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +SQLITE_API int sqlite3_open16( + const void *filename, /* Database filename (UTF-16) */ + sqlite3 **ppDb /* OUT: SQLite db handle */ +); +SQLITE_API int sqlite3_open_v2( + const char *filename, /* Database filename (UTF-8) */ + sqlite3 **ppDb, /* OUT: SQLite db handle */ + int flags, /* Flags */ + const char *zVfs /* Name of VFS module to use */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_close 3 , +.Xr sqlite3_config 3 , +.Xr sqlite3_db_readonly 3 , +.Xr sqlite3_enable_shared_cache 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_temp_directory 3 , +.Xr sqlite3_vfs 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_IOCAP_ATOMIC 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_OPEN_READONLY 3 diff --git a/static/netbsd/man3/sqlite3_overload_function.3 b/static/netbsd/man3/sqlite3_overload_function.3 new file mode 100644 index 00000000..6b4c0454 --- /dev/null +++ b/static/netbsd/man3/sqlite3_overload_function.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_OVERLOAD_FUNCTION 3 +.Os +.Sh NAME +.Nm sqlite3_overload_function +.Nd overload a function for a virtual table +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_overload_function +.Fa "sqlite3*" +.Fa "const char *zFuncName" +.Fa "int nArg" +.Fc +.Sh DESCRIPTION +Virtual tables can provide alternative implementations of functions +using the xFindFunction method of the virtual table module. +But global versions of those functions must exist in order to be overloaded. +.Pp +This API makes sure a global version of a function with a particular +name and number of parameters exists. +If no such function exists before this API is called, a new function +is created. +The implementation of the new function always causes an exception to +be thrown. +So the new function is not good for anything by itself. +Its only purpose is to be a placeholder function that can be overloaded +by a virtual table. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7650. +.Bd -literal +SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); +.Ed +.Sh SEE ALSO +.Xr sqlite3_module 3 diff --git a/static/netbsd/man3/sqlite3_pcache.3 b/static/netbsd/man3/sqlite3_pcache.3 new file mode 100644 index 00000000..c07f09cb --- /dev/null +++ b/static/netbsd/man3/sqlite3_pcache.3 @@ -0,0 +1,25 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PCACHE 3 +.Os +.Sh NAME +.Nm sqlite3_pcache +.Nd custom page cache object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_pcache sqlite3_pcache; +.Sh DESCRIPTION +The sqlite3_pcache type is opaque. +It is implemented by the pluggable module. +The SQLite core has no knowledge of its size or internal structure +and never deals with the sqlite3_pcache object except by holding and +passing pointers to the object. +.Pp +See sqlite3_pcache_methods2 for additional information. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8880. +.Bd -literal +typedef struct sqlite3_pcache sqlite3_pcache; +.Ed +.Sh SEE ALSO +.Xr sqlite3_pcache_methods2 3 diff --git a/static/netbsd/man3/sqlite3_pcache_methods2.3 b/static/netbsd/man3/sqlite3_pcache_methods2.3 new file mode 100644 index 00000000..00a09331 --- /dev/null +++ b/static/netbsd/man3/sqlite3_pcache_methods2.3 @@ -0,0 +1,194 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PCACHE_METHODS2 3 +.Os +.Sh NAME +.Nm sqlite3_pcache_methods2 , +.Nm sqlite3_pcache_methods2 +.Nd application defined page cache +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; +.Vt struct sqlite3_pcache_methods2 ; +.Sh DESCRIPTION +The sqlite3_config(SQLITE_CONFIG_PCACHE2, +\&...) interface can register an alternative page cache implementation +by passing in an instance of the sqlite3_pcache_methods2 structure. +In many applications, most of the heap memory allocated by SQLite is +used for the page cache. +By implementing a custom page cache using this API, an application +can better control the amount of memory consumed by SQLite, the way +in which that memory is allocated and released, and the policies used +to determine exactly which parts of a database file are cached and +for how long. +.Pp +The alternative page cache mechanism is an extreme measure that is +only needed by the most demanding applications. +The built-in page cache is recommended for most uses. +.Pp +The contents of the sqlite3_pcache_methods2 structure are copied to +an internal buffer by SQLite within the call to sqlite3_config. +Hence the application may discard the parameter after the call to +.Fn sqlite3_config +returns. +.Pp +The xInit() method is called once for each effective call to +.Fn sqlite3_initialize +(usually only once during the lifetime of the process). +The xInit() method is passed a copy of the sqlite3_pcache_methods2.pArg +value. +The intent of the xInit() method is to set up global data structures +required by the custom page cache implementation. +If the xInit() method is NULL, then the built-in default page cache +is used instead of the application defined page cache. +.Pp +The xShutdown() method is called by +.Fn sqlite3_shutdown . +It can be used to clean up any outstanding resources before process +shutdown, if required. +The xShutdown() method may be NULL. +.Pp +SQLite automatically serializes calls to the xInit method, so the xInit +method need not be threadsafe. +The xShutdown method is only called from +.Fn sqlite3_shutdown +so it does not need to be threadsafe either. +All other methods must be threadsafe in multithreaded applications. +.Pp +SQLite will never invoke xInit() more than once without an intervening +call to xShutdown(). +.Pp +SQLite invokes the xCreate() method to construct a new cache instance. +SQLite will typically create one cache instance for each open database +file, though this is not guaranteed. +The first parameter, szPage, is the size in bytes of the pages that +must be allocated by the cache. +szPage will always a power of two. +The second parameter szExtra is a number of bytes of extra storage +associated with each page cache entry. +The szExtra parameter will a number less than 250. +SQLite will use the extra szExtra bytes on each page to store metadata +about the underlying database page on disk. +The value passed into szExtra depends on the SQLite version, the target +platform, and how SQLite was compiled. +The third argument to xCreate(), bPurgeable, is true if the cache being +created will be used to cache database pages of a file stored on disk, +or false if it is used for an in-memory database. +The cache implementation does not have to do anything special based +with the value of bPurgeable; it is purely advisory. +On a cache where bPurgeable is false, SQLite will never invoke xUnpin() +except to deliberately delete a page. +In other words, calls to xUnpin() on a cache with bPurgeable set to +false will always have the "discard" flag set to true. +Hence, a cache created with bPurgeable false will never contain any +unpinned pages. +.Pp +The xCachesize() method may be called at any time by SQLite to set +the suggested maximum cache-size (number of pages stored by) the cache +instance passed as the first argument. +This is the value configured using the SQLite "PRAGMA cache_size" +command. +As with the bPurgeable parameter, the implementation is not required +to do anything with this value; it is advisory only. +.Pp +The xPagecount() method must return the number of pages currently stored +in the cache, both pinned and unpinned. +.Pp +The xFetch() method locates a page in the cache and returns a pointer +to an sqlite3_pcache_page object associated with that page, or a NULL +pointer. +The pBuf element of the returned sqlite3_pcache_page object will be +a pointer to a buffer of szPage bytes used to store the content of +a single database page. +The pExtra element of sqlite3_pcache_page will be a pointer to the +szExtra bytes of extra storage that SQLite has requested for each entry +in the page cache. +.Pp +The page to be fetched is determined by the key. +The minimum key value is 1. +After it has been retrieved using xFetch, the page is considered to +be "pinned". +.Pp +If the requested page is already in the page cache, then the page cache +implementation must return a pointer to the page buffer with its content +intact. +If the requested page is not already in the cache, then the cache implementation +should use the value of the createFlag parameter to help it determined +what action to take: +.Pp + createFlag Behavior when page is not already in cache + 0 Do not allocate a new page. +Return NULL. + 1 Allocate a new page if it easy and convenient to do so. +Otherwise return NULL. + 2 Make every effort to allocate a new page. +Only return NULL if allocating a new page is effectively impossible. +.Pp +SQLite will normally invoke xFetch() with a createFlag of 0 or 1. +SQLite will only use a createFlag of 2 after a prior call with a createFlag +of 1 failed. +In between the xFetch() calls, SQLite may attempt to unpin one or more +cache pages by spilling the content of pinned pages to disk and synching +the operating system disk cache. +.Pp +xUnpin() is called by SQLite with a pointer to a currently pinned page +as its second argument. +If the third parameter, discard, is non-zero, then the page must be +evicted from the cache. +If the discard parameter is zero, then the page may be discarded or +retained at the discretion of page cache implementation. +The page cache implementation may choose to evict unpinned pages at +any time. +.Pp +The cache must not perform any reference counting. +A single call to xUnpin() unpins the page regardless of the number +of prior calls to xFetch(). +.Pp +The xRekey() method is used to change the key value associated with +the page passed as the second argument. +If the cache previously contains an entry associated with newKey, it +must be discarded. +Any prior cache entry associated with newKey is guaranteed not to be +pinned. +.Pp +When SQLite calls the xTruncate() method, the cache must discard all +existing cache entries with page numbers (keys) greater than or equal +to the value of the iLimit parameter passed to xTruncate(). +If any of these pages are pinned, they are implicitly unpinned, meaning +that they can be safely discarded. +.Pp +The xDestroy() method is used to delete a cache allocated by xCreate(). +All resources associated with the specified cache should be freed. +After calling the xDestroy() method, SQLite considers the sqlite3_pcache* +handle invalid, and will not use it with any other sqlite3_pcache_methods2 +functions. +.Pp +SQLite invokes the xShrink() method when it wants the page cache to +free up as much of heap memory as possible. +The page cache implementation is not obligated to free any memory, +but well-behaved implementations should do their best. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8909. +.Bd -literal +typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; +struct sqlite3_pcache_methods2 { + int iVersion; + void *pArg; + int (*xInit)(void*); + void (*xShutdown)(void*); + sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable); + void (*xCachesize)(sqlite3_pcache*, int nCachesize); + int (*xPagecount)(sqlite3_pcache*); + sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); + void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard); + void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, + unsigned oldKey, unsigned newKey); + void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); + void (*xDestroy)(sqlite3_pcache*); + void (*xShrink)(sqlite3_pcache*); +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr sqlite3_initialize 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/sqlite3_pcache_page.3 b/static/netbsd/man3/sqlite3_pcache_page.3 new file mode 100644 index 00000000..b88bfb88 --- /dev/null +++ b/static/netbsd/man3/sqlite3_pcache_page.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PCACHE_PAGE 3 +.Os +.Sh NAME +.Nm sqlite3_pcache_page , +.Nm sqlite3_pcache_page +.Nd custom page cache object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_pcache_page sqlite3_pcache_page; +.Vt struct sqlite3_pcache_page ; +.Sh DESCRIPTION +The sqlite3_pcache_page object represents a single page in the page +cache. +The page cache will allocate instances of this object. +Various methods of the page cache use pointers to instances of this +object as parameters or as their return value. +.Pp +See sqlite3_pcache_methods2 for additional information. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8893. +.Bd -literal +typedef struct sqlite3_pcache_page sqlite3_pcache_page; +struct sqlite3_pcache_page { + void *pBuf; /* The content of the page */ + void *pExtra; /* Extra information associated with the page */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_pcache_methods2 3 diff --git a/static/netbsd/man3/sqlite3_prepare.3 b/static/netbsd/man3/sqlite3_prepare.3 new file mode 100644 index 00000000..d1697c44 --- /dev/null +++ b/static/netbsd/man3/sqlite3_prepare.3 @@ -0,0 +1,234 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PREPARE 3 +.Os +.Sh NAME +.Nm sqlite3_prepare , +.Nm sqlite3_prepare_v2 , +.Nm sqlite3_prepare_v3 , +.Nm sqlite3_prepare16 , +.Nm sqlite3_prepare16_v2 , +.Nm sqlite3_prepare16_v3 +.Nd compiling an SQL statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_prepare +.Fa "sqlite3 *db" +.Fa "const char *zSql" +.Fa "int nByte" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const char **pzTail" +.Fc +.Ft int +.Fo sqlite3_prepare_v2 +.Fa "sqlite3 *db" +.Fa "const char *zSql" +.Fa "int nByte" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const char **pzTail" +.Fc +.Ft int +.Fo sqlite3_prepare_v3 +.Fa "sqlite3 *db" +.Fa "const char *zSql" +.Fa "int nByte" +.Fa "unsigned int prepFlags" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const char **pzTail" +.Fc +.Ft int +.Fo sqlite3_prepare16 +.Fa "sqlite3 *db" +.Fa "const void *zSql" +.Fa "int nByte" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const void **pzTail" +.Fc +.Ft int +.Fo sqlite3_prepare16_v2 +.Fa "sqlite3 *db" +.Fa "const void *zSql" +.Fa "int nByte" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const void **pzTail" +.Fc +.Ft int +.Fo sqlite3_prepare16_v3 +.Fa "sqlite3 *db" +.Fa "const void *zSql" +.Fa "int nByte" +.Fa "unsigned int prepFlags" +.Fa "sqlite3_stmt **ppStmt" +.Fa "const void **pzTail" +.Fc +.Sh DESCRIPTION +To execute an SQL statement, it must first be compiled into a byte-code +program using one of these routines. +Or, in other words, these routines are constructors for the prepared statement +object. +.Pp +The preferred routine to use is +.Fn sqlite3_prepare_v2 . +The +.Fn sqlite3_prepare +interface is legacy and should be avoided. +.Fn sqlite3_prepare_v3 +has an extra "prepFlags" option that is used for special purposes. +.Pp +The use of the UTF-8 interfaces is preferred, as SQLite currently does +all parsing using UTF-8. +The UTF-16 interfaces are provided as a convenience. +The UTF-16 interfaces work by converting the input text into UTF-8, +then invoking the corresponding UTF-8 interface. +.Pp +The first argument, "db", is a database connection +obtained from a prior successful call to +.Fn sqlite3_open , +.Fn sqlite3_open_v2 +or +.Fn sqlite3_open16 . +The database connection must not have been closed. +.Pp +The second argument, "zSql", is the statement to be compiled, encoded +as either UTF-8 or UTF-16. +The sqlite3_prepare(), sqlite3_prepare_v2(), and sqlite3_prepare_v3() +interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), +and sqlite3_prepare16_v3() use UTF-16. +.Pp +If the nByte argument is negative, then zSql is read up to the first +zero terminator. +If nByte is positive, then it is the number of bytes read from zSql. +If nByte is zero, then no prepared statement is generated. +If the caller knows that the supplied string is nul-terminated, then +there is a small performance advantage to passing an nByte parameter +that is the number of bytes in the input string \fIincluding\fP the nul-terminator. +.Pp +If pzTail is not NULL then *pzTail is made to point to the first byte +past the end of the first SQL statement in zSql. +These routines only compile the first statement in zSql, so *pzTail +is left pointing to what remains uncompiled. +.Pp +*ppStmt is left pointing to a compiled prepared statement +that can be executed using +.Fn sqlite3_step . +If there is an error, *ppStmt is set to NULL. +If the input text contains no SQL (if the input is an empty string +or a comment) then *ppStmt is set to NULL. +The calling procedure is responsible for deleting the compiled SQL +statement using +.Fn sqlite3_finalize +after it has finished with it. +ppStmt may not be NULL. +.Pp +On success, the sqlite3_prepare() family of routines return SQLITE_OK; +otherwise an error code is returned. +.Pp +The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(), +and sqlite3_prepare16_v3() interfaces are recommended for all new programs. +The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) are +retained for backwards compatibility, but their use is discouraged. +In the "vX" interfaces, the prepared statement that is returned (the +sqlite3_stmt object) contains a copy of the original SQL +text. +This causes the +.Fn sqlite3_step +interface to behave differently in three ways: +.Bl -enum +.It +If the database schema changes, instead of returning SQLITE_SCHEMA +as it always used to do, +.Fn sqlite3_step +will automatically recompile the SQL statement and try to run it again. +As many as SQLITE_MAX_SCHEMA_RETRY retries will +occur before sqlite3_step() gives up and returns an error. +.It +When an error occurs, +.Fn sqlite3_step +will return one of the detailed error codes or extended error codes. +The legacy behavior was that +.Fn sqlite3_step +would only return a generic SQLITE_ERROR result code and +the application would have to make a second call to +.Fn sqlite3_reset +in order to find the underlying cause of the problem. +With the "v2" prepare interfaces, the underlying reason for the error +is returned immediately. +.It +If the specific value bound to a host parameter in the +WHERE clause might influence the choice of query plan for a statement, +then the statement will be automatically recompiled, as if there had +been a schema change, on the first +.Fn sqlite3_step +call following any change to the bindings of that parameter. +The specific value of a WHERE-clause parameter might influence +the choice of query plan if the parameter is the left-hand side of +a LIKE or GLOB operator or if the parameter is compared to +an indexed column and the SQLITE_ENABLE_STAT4 compile-time +option is enabled. +.El +.Pp +.Pp +sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having +the extra prepFlags parameter, which is a bit array consisting of zero +or more of the SQLITE_PREPARE_* flags. +The sqlite3_prepare_v2() interface works exactly the same as sqlite3_prepare_v3() +with a zero prepFlags parameter. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4176. +.Bd -literal +SQLITE_API int sqlite3_prepare( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlite3_prepare_v2( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlite3_prepare_v3( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlite3_prepare16( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlite3_prepare16_v2( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlite3_prepare16_v3( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_PREPARE_PERSISTENT 3 diff --git a/static/netbsd/man3/sqlite3_preupdate_hook.3 b/static/netbsd/man3/sqlite3_preupdate_hook.3 new file mode 100644 index 00000000..9283e8b9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_preupdate_hook.3 @@ -0,0 +1,188 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PREUPDATE_HOOK 3 +.Os +.Sh NAME +.Nm sqlite3_preupdate_hook , +.Nm sqlite3_preupdate_old , +.Nm sqlite3_preupdate_count , +.Nm sqlite3_preupdate_depth , +.Nm sqlite3_preupdate_new , +.Nm sqlite3_preupdate_blobwrite +.Nd the pre-update hook +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_preupdate_hook +.Fa "sqlite3 *db" +.Fa "void(*xPreUpdate)( void *pCtx,sqlite3 *db,int op,char const *zDb,char const *zName,sqlite3_int64 iKey1,sqlite3_int64 iKey2)" +.Fa "void*" +.Fc +.Ft int +.Fo sqlite3_preupdate_old +.Fa "sqlite3 *" +.Fa "int" +.Fa "sqlite3_value **" +.Fc +.Ft int +.Fo sqlite3_preupdate_count +.Fa "sqlite3 *" +.Fc +.Ft int +.Fo sqlite3_preupdate_depth +.Fa "sqlite3 *" +.Fc +.Ft int +.Fo sqlite3_preupdate_new +.Fa "sqlite3 *" +.Fa "int" +.Fa "sqlite3_value **" +.Fc +.Ft int +.Fo sqlite3_preupdate_blobwrite +.Fa "sqlite3 *" +.Fc +.Sh DESCRIPTION +These interfaces are only available if SQLite is compiled using the +SQLITE_ENABLE_PREUPDATE_HOOK compile-time +option. +.Pp +The +.Fn sqlite3_preupdate_hook +interface registers a callback function that is invoked prior to each +INSERT, UPDATE, and DELETE operation on a database +table. +At most one preupdate hook may be registered at a time on a single +database connection; each call to +.Fn sqlite3_preupdate_hook +overrides the previous setting. +The preupdate hook is disabled by invoking +.Fn sqlite3_preupdate_hook +with a NULL pointer as the second parameter. +The third parameter to +.Fn sqlite3_preupdate_hook +is passed through as the first parameter to callbacks. +.Pp +The preupdate hook only fires for changes to real database tables; +the preupdate hook is not invoked for changes to virtual tables +or to system tables like sqlite_sequence or sqlite_stat1. +.Pp +The second parameter to the preupdate callback is a pointer to the +database connection that registered the preupdate +hook. +The third parameter to the preupdate callback is one of the constants +SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE +to identify the kind of update operation that is about to occur. +The fourth parameter to the preupdate callback is the name of the database +within the database connection that is being modified. +This will be "main" for the main database or "temp" for TEMP tables +or the name given after the AS keyword in the ATTACH statement +for attached databases. +The fifth parameter to the preupdate callback is the name of the table +that is being modified. +.Pp +For an UPDATE or DELETE operation on a rowid table, the +sixth parameter passed to the preupdate callback is the initial rowid +of the row being modified or deleted. +For an INSERT operation on a rowid table, or any operation on a WITHOUT +ROWID table, the value of the sixth parameter is undefined. +For an INSERT or UPDATE on a rowid table the seventh parameter is the +final rowid value of the row being inserted or updated. +The value of the seventh parameter passed to the callback function +is not defined for operations on WITHOUT ROWID tables, or for DELETE +operations on rowid tables. +.Pp +The sqlite3_preupdate_hook(D,C,P) function returns the P argument from +the previous call on the same database connection +D, or NULL for the first call on D. +.Pp +The +.Fn sqlite3_preupdate_old , +.Fn sqlite3_preupdate_new , +.Fn sqlite3_preupdate_count , +and +.Fn sqlite3_preupdate_depth +interfaces provide additional information about a preupdate event. +These routines may only be called from within a preupdate callback. +Invoking any of these routines from outside of a preupdate callback +or with a database connection pointer that is different +from the one supplied to the preupdate callback results in undefined +and probably undesirable behavior. +.Pp +The sqlite3_preupdate_count(D) interface +returns the number of columns in the row that is being inserted, updated, +or deleted. +.Pp +The sqlite3_preupdate_old(D,N,P) interface +writes into P a pointer to a protected sqlite3_value +that contains the value of the Nth column of the table row before it +is updated. +The N parameter must be between 0 and one less than the number of columns +or the behavior will be undefined. +This must only be used within SQLITE_UPDATE and SQLITE_DELETE preupdate +callbacks; if it is used by an SQLITE_INSERT callback then the behavior +is undefined. +The sqlite3_value that P points to will be destroyed when +the preupdate callback returns. +.Pp +The sqlite3_preupdate_new(D,N,P) interface +writes into P a pointer to a protected sqlite3_value +that contains the value of the Nth column of the table row after it +is updated. +The N parameter must be between 0 and one less than the number of columns +or the behavior will be undefined. +This must only be used within SQLITE_INSERT and SQLITE_UPDATE preupdate +callbacks; if it is used by an SQLITE_DELETE callback then the behavior +is undefined. +The sqlite3_value that P points to will be destroyed when +the preupdate callback returns. +.Pp +The sqlite3_preupdate_depth(D) interface +returns 0 if the preupdate callback was invoked as a result of a direct +insert, update, or delete operation; or 1 for inserts, updates, or +deletes invoked by top-level triggers; or 2 for changes resulting from +triggers called by top-level triggers; and so forth. +.Pp +When the +.Fn sqlite3_blob_write +API is used to update a blob column, the pre-update hook is invoked +with SQLITE_DELETE. +This is because the in this case the new values are not available. +In this case, when a callback made with op==SQLITE_DELETE is actually +a write using the sqlite3_blob_write() API, the +.Fn sqlite3_preupdate_blobwrite +returns the index of the column being written. +In other cases, where the pre-update hook is being invoked for some +other reason, including a regular DELETE, sqlite3_preupdate_blobwrite() +returns -1. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10316. +.Bd -literal +#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) +SQLITE_API void *sqlite3_preupdate_hook( + sqlite3 *db, + void(*xPreUpdate)( + void *pCtx, /* Copy of third arg to preupdate_hook() */ + sqlite3 *db, /* Database handle */ + int op, /* SQLITE_UPDATE, DELETE or INSERT */ + char const *zDb, /* Database name */ + char const *zName, /* Table name */ + sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ + sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ + ), + void* +); +SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); +SQLITE_API int sqlite3_preupdate_count(sqlite3 *); +SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); +SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); +SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *); +#endif +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_blob_write 3 , +.Xr sqlite3_update_hook 3 , +.Xr sqlite3_value 3 , +.Xr SQLITE_CREATE_INDEX 3 diff --git a/static/netbsd/man3/sqlite3_progress_handler.3 b/static/netbsd/man3/sqlite3_progress_handler.3 new file mode 100644 index 00000000..20af7b30 --- /dev/null +++ b/static/netbsd/man3/sqlite3_progress_handler.3 @@ -0,0 +1,70 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PROGRESS_HANDLER 3 +.Os +.Sh NAME +.Nm sqlite3_progress_handler +.Nd query progress callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_progress_handler +.Fa "sqlite3*" +.Fa "int" +.Fa "int(*)(void*)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_progress_handler(D,N,X,P) interface causes the callback +function X to be invoked periodically during long running calls to +.Fn sqlite3_step +and +.Fn sqlite3_prepare +and similar for database connection D. +An example use for this interface is to keep a GUI updated during a +large query. +.Pp +The parameter P is passed through as the only parameter to the callback +function X. +The parameter N is the approximate number of virtual machine instructions +that are evaluated between successive invocations of the callback X. +If N is less than one then the progress handler is disabled. +.Pp +Only a single progress handler may be defined at one time per database connection; +setting a new progress handler cancels the old one. +Setting parameter X to NULL disables the progress handler. +The progress handler is also disabled by setting N to a value less +than 1. +.Pp +If the progress callback returns non-zero, the operation is interrupted. +This feature can be used to implement a "Cancel" button on a GUI progress +dialog box. +.Pp +The progress handler callback must not do anything that will modify +the database connection that invoked the progress handler. +Note that +.Fn sqlite3_prepare_v2 +and +.Fn sqlite3_step +both modify their database connections for the meaning of "modify" +in this paragraph. +.Pp +The progress handler callback would originally only be invoked from +the bytecode engine. +It still might be invoked during +.Fn sqlite3_prepare +and similar because those routines might force a reparse of the schema +which involves running the bytecode engine. +However, beginning with SQLite version 3.41.0, the progress handler +callback might also be invoked directly from +.Fn sqlite3_prepare +while analyzing and generating code for complex queries. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3421. +.Bd -literal +SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_step 3 diff --git a/static/netbsd/man3/sqlite3_randomness.3 b/static/netbsd/man3/sqlite3_randomness.3 new file mode 100644 index 00000000..31d2e4fa --- /dev/null +++ b/static/netbsd/man3/sqlite3_randomness.3 @@ -0,0 +1,40 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RANDOMNESS 3 +.Os +.Sh NAME +.Nm sqlite3_randomness +.Nd pseudo-Random number generator +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_randomness +.Fa "int N" +.Fa "void *P" +.Fc +.Sh DESCRIPTION +SQLite contains a high-quality pseudo-random number generator (PRNG) +used to select random ROWIDs when inserting new records into +a table that already uses the largest possible ROWID. +The PRNG is also used for the built-in random() and randomblob() SQL +functions. +This interface allows applications to access the same PRNG for other +purposes. +.Pp +A call to this routine stores N bytes of randomness into buffer P. +The P parameter can be a NULL pointer. +.Pp +If this routine has not been previously called or if the previous call +had N less than one or a NULL pointer for P, then the PRNG is seeded +using randomness obtained from the xRandomness method of the default +sqlite3_vfs object. +If the previous call to this routine had an N of 1 or more and a non-NULL +P then the pseudo-randomness is generated internally and without recourse +to the sqlite3_vfs xRandomness method. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3101. +.Bd -literal +SQLITE_API void sqlite3_randomness(int N, void *P); +.Ed +.Sh SEE ALSO +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_rebaser.3 b/static/netbsd/man3/sqlite3_rebaser.3 new file mode 100644 index 00000000..0ef05e2b --- /dev/null +++ b/static/netbsd/man3/sqlite3_rebaser.3 @@ -0,0 +1,111 @@ +.Dd January 24, 2024 +.Dt SQLITE3_REBASER 3 +.Os +.Sh NAME +.Nm sqlite3_rebaser +.Nd rebasing changesets +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_rebaser sqlite3_rebaser; +.Sh DESCRIPTION +Suppose there is a site hosting a database in state S0. +And that modifications are made that move that database to state S1 +and a changeset recorded (the "local" changeset). +Then, a changeset based on S0 is received from another site (the "remote" +changeset) and applied to the database. +The database is then in state (S1+"remote"), where the exact state +depends on any conflict resolution decisions (OMIT or REPLACE) made +while applying "remote". +Rebasing a changeset is to update it to take those conflict resolution +decisions into account, so that the same conflicts do not have to be +resolved elsewhere in the network. +.Pp +For example, if both the local and remote changesets contain an INSERT +of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)": +.Pp +local: INSERT INTO t1 VALUES(1, 'v1'); remote: INSERT INTO t1 VALUES(1, +\&'v2'); +.Pp +and the conflict resolution is REPLACE, then the INSERT change is removed +from the local changeset (it was overridden). +Or, if the conflict resolution was "OMIT", then the local changeset +is modified to instead contain: +.Pp +UPDATE t1 SET b = 'v2' WHERE a=1; +.Pp +Changes within the local changeset are rebased as follows: +.Bl -tag -width Ds +.It Local INSERT +This may only conflict with a remote INSERT. +If the conflict resolution was OMIT, then add an UPDATE change to the +rebased changeset. +Or, if the conflict resolution was REPLACE, add nothing to the rebased +changeset. +.It Local DELETE +This may conflict with a remote UPDATE or DELETE. +In both cases the only possible resolution is OMIT. +If the remote operation was a DELETE, then add no change to the rebased +changeset. +If the remote operation was an UPDATE, then the old.* fields of change +are updated to reflect the new.* values in the UPDATE. +.It Local UPDATE +This may conflict with a remote UPDATE or DELETE. +If it conflicts with a DELETE, and the conflict resolution was OMIT, +then the update is changed into an INSERT. +Any undefined values in the new.* record from the update change are +filled in using the old.* values from the conflicting DELETE. +Or, if the conflict resolution was REPLACE, the UPDATE change is simply +omitted from the rebased changeset. +.Pp +If conflict is with a remote UPDATE and the resolution is OMIT, then +the old.* values are rebased using the new.* values in the remote change. +Or, if the resolution is REPLACE, then the change is copied into the +rebased changeset with updates to columns also updated by the conflicting +remote UPDATE removed. +If this means no columns would be updated, the change is omitted. +.El +.Pp +A local change may be rebased against multiple remote changes simultaneously. +If a single key is modified by multiple remote changesets, they are +combined as follows before the local changeset is rebased: +.Bl -bullet +.It +If there has been one or more REPLACE resolutions on a key, it is rebased +according to a REPLACE. +.It +If there have been no REPLACE resolutions on a key, then the local +changeset is rebased according to the most recent of the OMIT resolutions. +.El +.Pp +Note that conflict resolutions from multiple remote changesets are +combined on a per-field basis, not per-row. +This means that in the case of multiple remote UPDATE operations, some +fields of a single local change may be rebased for REPLACE while others +are rebased for OMIT. +.Pp +In order to rebase a local changeset, the remote changeset must first +be applied to the local database using sqlite3changeset_apply_v2() +and the buffer of rebase information captured. +Then: +.Bl -enum +.It +An sqlite3_rebaser object is created by calling sqlite3rebaser_create(). +.It +The new object is configured with the rebase buffer obtained from sqlite3changeset_apply_v2() +by calling sqlite3rebaser_configure(). +If the local changeset is to be rebased against multiple remote changesets, +then sqlite3rebaser_configure() should be called multiple times, in +the same order that the multiple sqlite3changeset_apply_v2() calls +were made. +.It +Each local changeset is rebased by calling sqlite3rebaser_rebase(). +.It +The sqlite3_rebaser object is deleted by calling sqlite3rebaser_delete(). +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12352. +.Bd -literal +typedef struct sqlite3_rebaser sqlite3_rebaser; +.Ed diff --git a/static/netbsd/man3/sqlite3_release_memory.3 b/static/netbsd/man3/sqlite3_release_memory.3 new file mode 100644 index 00000000..76301bf6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_release_memory.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RELEASE_MEMORY 3 +.Os +.Sh NAME +.Nm sqlite3_release_memory +.Nd attempt to free heap memory +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_release_memory +.Fa "int" +.Fc +.Sh DESCRIPTION +The sqlite3_release_memory() interface attempts to free N bytes of +heap memory by deallocating non-essential memory allocations held by +the database library. +Memory used to cache database pages to improve performance is an example +of non-essential memory. +sqlite3_release_memory() returns the number of bytes actually freed, +which might be more or less than the amount requested. +The sqlite3_release_memory() routine is a no-op returning zero if SQLite +is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6939. +.Bd -literal +SQLITE_API int sqlite3_release_memory(int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_release_memory 3 diff --git a/static/netbsd/man3/sqlite3_reset.3 b/static/netbsd/man3/sqlite3_reset.3 new file mode 100644 index 00000000..006346e8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_reset.3 @@ -0,0 +1,60 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RESET 3 +.Os +.Sh NAME +.Nm sqlite3_reset +.Nd reset a prepared statement object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_reset +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_reset() function is called to reset a prepared statement +object back to its initial state, ready to be re-executed. +Any SQL statement variables that had values bound to them using the +sqlite3_bind_*() API retain their values. +Use +.Fn sqlite3_clear_bindings +to reset the bindings. +.Pp +The sqlite3_reset(S) interface resets the prepared statement +S back to the beginning of its program. +.Pp +The return code from sqlite3_reset(S) indicates whether +or not the previous evaluation of prepared statement S completed successfully. +If sqlite3_step(S) has never before been called on S +or if sqlite3_step(S) has not been called since the +previous call to sqlite3_reset(S), then sqlite3_reset(S) +will return SQLITE_OK. +.Pp +If the most recent call to sqlite3_step(S) for the prepared statement +S indicated an error, then sqlite3_reset(S) returns +an appropriate error code. +The sqlite3_reset(S) interface might also return an +error code if there were no prior errors but the process +of resetting the prepared statement caused a new error. +For example, if an INSERT statement with a RETURNING +clause is only stepped one time, that one call to sqlite3_step(S) +might return SQLITE_ROW but the overall statement might still fail +and the sqlite3_reset(S) call might return SQLITE_BUSY +if locking constraints prevent the database change from committing. +Therefore, it is important that applications check the return code +from sqlite3_reset(S) even if no prior call to sqlite3_step(S) +indicated a problem. +.Pp +The sqlite3_reset(S) interface does not change the +values of any bindings on the prepared statement +S. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5293. +.Bd -literal +SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_clear_bindings 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_reset_auto_extension.3 b/static/netbsd/man3/sqlite3_reset_auto_extension.3 new file mode 100644 index 00000000..995b261e --- /dev/null +++ b/static/netbsd/man3/sqlite3_reset_auto_extension.3 @@ -0,0 +1,24 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RESET_AUTO_EXTENSION 3 +.Os +.Sh NAME +.Nm sqlite3_reset_auto_extension +.Nd reset automatic extension loading +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_reset_auto_extension +.Fa "void" +.Fc +.Sh DESCRIPTION +This interface disables all automatic extensions previously registered +using +.Fn sqlite3_auto_extension . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7257. +.Bd -literal +SQLITE_API void sqlite3_reset_auto_extension(void); +.Ed +.Sh SEE ALSO +.Xr sqlite3_auto_extension 3 diff --git a/static/netbsd/man3/sqlite3_result_blob.3 b/static/netbsd/man3/sqlite3_result_blob.3 new file mode 100644 index 00000000..e0b6604b --- /dev/null +++ b/static/netbsd/man3/sqlite3_result_blob.3 @@ -0,0 +1,330 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RESULT_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_result_blob , +.Nm sqlite3_result_blob64 , +.Nm sqlite3_result_double , +.Nm sqlite3_result_error , +.Nm sqlite3_result_error16 , +.Nm sqlite3_result_error_toobig , +.Nm sqlite3_result_error_nomem , +.Nm sqlite3_result_error_code , +.Nm sqlite3_result_int , +.Nm sqlite3_result_int64 , +.Nm sqlite3_result_null , +.Nm sqlite3_result_text , +.Nm sqlite3_result_text64 , +.Nm sqlite3_result_text16 , +.Nm sqlite3_result_text16le , +.Nm sqlite3_result_text16be , +.Nm sqlite3_result_value , +.Nm sqlite3_result_pointer , +.Nm sqlite3_result_zeroblob , +.Nm sqlite3_result_zeroblob64 +.Nd setting the result of an SQL function +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_result_blob +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_blob64 +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_double +.Fa "sqlite3_context*" +.Fa "double" +.Fc +.Ft void +.Fo sqlite3_result_error +.Fa "sqlite3_context*" +.Fa "const char*" +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_result_error16 +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_result_error_toobig +.Fa "sqlite3_context*" +.Fc +.Ft void +.Fo sqlite3_result_error_nomem +.Fa "sqlite3_context*" +.Fc +.Ft void +.Fo sqlite3_result_error_code +.Fa "sqlite3_context*" +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_result_int +.Fa "sqlite3_context*" +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_result_int64 +.Fa "sqlite3_context*" +.Fa "sqlite3_int64" +.Fc +.Ft void +.Fo sqlite3_result_null +.Fa "sqlite3_context*" +.Fc +.Ft void +.Fo sqlite3_result_text +.Fa "sqlite3_context*" +.Fa "const char*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_text64 +.Fa "sqlite3_context*" +.Fa "const char*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fa "unsigned char encoding" +.Fc +.Ft void +.Fo sqlite3_result_text16 +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_text16le +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_text16be +.Fa "sqlite3_context*" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_value +.Fa "sqlite3_context*" +.Fa "sqlite3_value*" +.Fc +.Ft void +.Fo sqlite3_result_pointer +.Fa "sqlite3_context*" +.Fa "void*" +.Fa "const char*" +.Fa "void(*)(void*)" +.Fc +.Ft void +.Fo sqlite3_result_zeroblob +.Fa "sqlite3_context*" +.Fa "int n" +.Fc +.Ft int +.Fo sqlite3_result_zeroblob64 +.Fa "sqlite3_context*" +.Fa "sqlite3_uint64 n" +.Fc +.Sh DESCRIPTION +These routines are used by the xFunc or xFinal callbacks that implement +SQL functions and aggregates. +See +.Fn sqlite3_create_function +and +.Fn sqlite3_create_function16 +for additional information. +.Pp +These functions work very much like the parameter binding +family of functions used to bind values to host parameters in prepared +statements. +Refer to the SQL parameter documentation for additional +information. +.Pp +The sqlite3_result_blob() interface sets the result from an application-defined +function to be the BLOB whose content is pointed to by the second parameter +and which is N bytes long where N is the third parameter. +.Pp +The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N) +interfaces set the result of the application-defined function to be +a BLOB containing all zero bytes and N bytes in size. +.Pp +The sqlite3_result_double() interface sets the result from an application-defined +function to be a floating point value specified by its 2nd argument. +.Pp +The sqlite3_result_error() and sqlite3_result_error16() functions cause +the implemented SQL function to throw an exception. +SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() +or sqlite3_result_error16() as the text of an error message. +SQLite interprets the error message string from sqlite3_result_error() +as UTF-8. +SQLite interprets the string from sqlite3_result_error16() as UTF-16 +using the same byte-order determination rules +as +.Fn sqlite3_bind_text16 . +If the third parameter to sqlite3_result_error() or sqlite3_result_error16() +is negative then SQLite takes as the error message all text up through +the first zero character. +If the third parameter to sqlite3_result_error() or sqlite3_result_error16() +is non-negative then SQLite takes that many bytes (not characters) +from the 2nd parameter as the error message. +The sqlite3_result_error() and sqlite3_result_error16() routines make +a private copy of the error message text before they return. +Hence, the calling function can deallocate or modify the text after +they return without harm. +The sqlite3_result_error_code() function changes the error code returned +by SQLite as a result of an error in a function. +By default, the error code is SQLITE_ERROR. +A subsequent call to sqlite3_result_error() or sqlite3_result_error16() +resets the error code to SQLITE_ERROR. +.Pp +The sqlite3_result_error_toobig() interface causes SQLite to throw +an error indicating that a string or BLOB is too long to represent. +.Pp +The sqlite3_result_error_nomem() interface causes SQLite to throw an +error indicating that a memory allocation failed. +.Pp +The sqlite3_result_int() interface sets the return value of the application-defined +function to be the 32-bit signed integer value given in the 2nd argument. +The sqlite3_result_int64() interface sets the return value of the application-defined +function to be the 64-bit signed integer value given in the 2nd argument. +.Pp +The sqlite3_result_null() interface sets the return value of the application-defined +function to be NULL. +.Pp +The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), +and sqlite3_result_text16be() interfaces set the return value of the +application-defined function to be a text string which is represented +as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 +big endian, respectively. +The sqlite3_result_text64() interface sets the return value of an application-defined +function to be a text string in an encoding specified by the fifth +(and last) parameter, which must be one of SQLITE_UTF8, +SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE. +SQLite takes the text result from the application from the 2nd parameter +of the sqlite3_result_text* interfaces. +If the 3rd parameter to any of the sqlite3_result_text* interfaces +other than sqlite3_result_text64() is negative, then SQLite computes +the string length itself by searching the 2nd parameter for the first +zero character. +If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, +then as many bytes (not characters) of the text pointed to by the 2nd +parameter are taken as the application-defined function result. +If the 3rd parameter is non-negative, then it must be the byte offset +into the string where the NUL terminator would appear if the string +where NUL terminated. +If any NUL characters occur in the string at a byte offset that is +less than the value of the 3rd parameter, then the resulting string +will contain embedded NULs and the result of expressions operating +on strings with embedded NULs is undefined. +If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob +is a non-NULL pointer, then SQLite calls that function as the destructor +on the text or BLOB result when it has finished using that result. +If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob +is the special constant SQLITE_STATIC, then SQLite assumes that the +text or BLOB result is in constant space and does not copy the content +of the parameter nor call a destructor on the content when it has finished +using that result. +If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob +is the special constant SQLITE_TRANSIENT then SQLite makes a copy of +the result into space obtained from +.Fn sqlite3_malloc +before it returns. +.Pp +For the sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() +routines, and for sqlite3_result_text64() when the encoding is not +UTF8, if the input UTF16 begins with a byte-order mark (BOM, U+FEFF) +then the BOM is removed from the string and the rest of the string +is interpreted according to the byte-order specified by the BOM. +The byte-order specified by the BOM at the beginning of the text overrides +the byte-order specified by the interface procedure. +So, for example, if sqlite3_result_text16le() is invoked with text +that begins with bytes 0xfe, 0xff (a big-endian byte-order mark) then +the first two bytes of input are skipped and the remaining input is +interpreted as UTF16BE text. +.Pp +For UTF16 input text to the sqlite3_result_text16(), sqlite3_result_text16be(), +sqlite3_result_text16le(), and sqlite3_result_text64() routines, if +the text contains invalid UTF16 characters, the invalid characters +might be converted into the unicode replacement character, U+FFFD. +.Pp +The sqlite3_result_value() interface sets the result of the application-defined +function to be a copy of the unprotected sqlite3_value +object specified by the 2nd parameter. +The sqlite3_result_value() interface makes a copy of the sqlite3_value +so that the sqlite3_value specified in the parameter may +change or be deallocated after sqlite3_result_value() returns without +harm. +A protected sqlite3_value object may always +be used where an unprotected sqlite3_value +object is required, so either kind of sqlite3_value object +can be used with this interface. +.Pp +The sqlite3_result_pointer(C,P,T,D) interface sets the result to an +SQL NULL value, just like sqlite3_result_null(C), +except that it also associates the host-language pointer P or type +T with that NULL value such that the pointer can be retrieved within +an application-defined SQL function +using +.Fn sqlite3_value_pointer . +If the D parameter is not NULL, then it is a pointer to a destructor +for the P parameter. +SQLite invokes D with P as its only argument when SQLite is finished +with P. +The T parameter should be a static string and preferably a string literal. +The sqlite3_result_pointer() routine is part of the pointer passing interface +added for SQLite 3.20.0. +.Pp +If these routines are called from within the different thread than +the one containing the application-defined function that received the +sqlite3_context pointer, the results are undefined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6047. +.Bd -literal +SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); +SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*, + sqlite3_uint64,void(*)(void*)); +SQLITE_API void sqlite3_result_double(sqlite3_context*, double); +SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); +SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); +SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); +SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); +SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); +SQLITE_API void sqlite3_result_int(sqlite3_context*, int); +SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); +SQLITE_API void sqlite3_result_null(sqlite3_context*); +SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); +SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, + void(*)(void*), unsigned char encoding); +SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); +SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); +SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); +SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); +SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*)); +SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); +SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_context 3 , +.Xr sqlite3_create_function 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_value_blob 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_result_subtype.3 b/static/netbsd/man3/sqlite3_result_subtype.3 new file mode 100644 index 00000000..840d5aff --- /dev/null +++ b/static/netbsd/man3/sqlite3_result_subtype.3 @@ -0,0 +1,44 @@ +.Dd January 24, 2024 +.Dt SQLITE3_RESULT_SUBTYPE 3 +.Os +.Sh NAME +.Nm sqlite3_result_subtype +.Nd setting the subtype of an SQL function +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_result_subtype +.Fa "sqlite3_context*" +.Fa "unsigned int" +.Fc +.Sh DESCRIPTION +The sqlite3_result_subtype(C,T) function causes the subtype of the +result from the application-defined SQL function +with sqlite3_context C to be the value T. +Only the lower 8 bits of the subtype T are preserved in current versions +of SQLite; higher order bits are discarded. +The number of subtype bytes preserved by SQLite might increase in future +releases of SQLite. +.Pp +Every application-defined SQL function +that invokes this interface should include the SQLITE_RESULT_SUBTYPE +property in its text encoding argument when the SQL function is registered. +If the SQLITE_RESULT_SUBTYPE property is omitted +from the function that invokes sqlite3_result_subtype(), then in some +cases the sqlite3_result_subtype() might fail to set the result subtype. +.Pp +If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any SQL +function that invokes the sqlite3_result_subtype() interface and that +does not have the SQLITE_RESULT_SUBTYPE property will raise an error. +Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1 by +default. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6218. +.Bd -literal +SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_context 3 , +.Xr sqlite3_create_function 3 , +.Xr SQLITE_DETERMINISTIC 3 diff --git a/static/netbsd/man3/sqlite3_serialize.3 b/static/netbsd/man3/sqlite3_serialize.3 new file mode 100644 index 00000000..676f1000 --- /dev/null +++ b/static/netbsd/man3/sqlite3_serialize.3 @@ -0,0 +1,72 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SERIALIZE 3 +.Os +.Sh NAME +.Nm sqlite3_serialize +.Nd serialize a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft unsigned char * +.Fo sqlite3_serialize +.Fa "sqlite3 *db" +.Fa "const char *zSchema" +.Fa "sqlite3_int64 *piSize" +.Fa "unsigned int mFlags" +.Fc +.Sh DESCRIPTION +The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory +that is a serialization of the S database on database connection +D. +If P is not a NULL pointer, then the size of the database in bytes +is written into *P. +.Pp +For an ordinary on-disk database file, the serialization is just a +copy of the disk file. +For an in-memory database or a "TEMP" database, the serialization is +the same sequence of bytes which would be written to disk if that database +where backed up to disk. +.Pp +The usual case is that sqlite3_serialize() copies the serialization +of the database into memory obtained from +.Fn sqlite3_malloc64 +and returns a pointer to that memory. +The caller is responsible for freeing the returned value to avoid a +memory leak. +However, if the F argument contains the SQLITE_SERIALIZE_NOCOPY bit, +then no memory allocations are made, and the sqlite3_serialize() function +will return a pointer to the contiguous memory representation of the +database that SQLite is currently using for that database, or NULL +if the no such contiguous memory representation of the database exists. +A contiguous memory representation of the database will usually only +exist if there has been a prior call to sqlite3_deserialize(D,S,...) +with the same values of D and S. +The size of the database is written into *P even if the SQLITE_SERIALIZE_NOCOPY +bit is set but no contiguous copy of the database exists. +.Pp +After the call, if the SQLITE_SERIALIZE_NOCOPY bit had been set, the +returned buffer content will remain accessible and unchanged until +either the next write operation on the connection or when the connection +is closed, and applications must not modify the buffer. +If the bit had been clear, the returned buffer will not be accessed +by SQLite after the call. +.Pp +A call to sqlite3_serialize(D,S,P,F) might return NULL even if the +SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory +allocation error occurs. +.Pp +This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE +option. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10636. +.Bd -literal +SQLITE_API unsigned char *sqlite3_serialize( + sqlite3 *db, /* The database connection */ + const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */ + sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */ + unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_malloc 3 diff --git a/static/netbsd/man3/sqlite3_session.3 b/static/netbsd/man3/sqlite3_session.3 new file mode 100644 index 00000000..42768095 --- /dev/null +++ b/static/netbsd/man3/sqlite3_session.3 @@ -0,0 +1,18 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SESSION 3 +.Os +.Sh NAME +.Nm sqlite3_session +.Nd session object handle +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_session sqlite3_session; +.Sh DESCRIPTION +An instance of this object is a session that can be used to +record changes to a database. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10937. +.Bd -literal +typedef struct sqlite3_session sqlite3_session; +.Ed diff --git a/static/netbsd/man3/sqlite3_set_authorizer.3 b/static/netbsd/man3/sqlite3_set_authorizer.3 new file mode 100644 index 00000000..6ea3e3c1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_set_authorizer.3 @@ -0,0 +1,142 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SET_AUTHORIZER 3 +.Os +.Sh NAME +.Nm sqlite3_set_authorizer +.Nd compile-Time authorization callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_set_authorizer +.Fa "sqlite3*" +.Fa "int (*xAuth)(void*,int,const char*,const char*,const char*,const char*)" +.Fa "void *pUserData" +.Fc +.Sh DESCRIPTION +This routine registers an authorizer callback with a particular database connection, +supplied in the first argument. +The authorizer callback is invoked as SQL statements are being compiled +by +.Fn sqlite3_prepare +or its variants +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare16 , +.Fn sqlite3_prepare16_v2 , +and +.Fn sqlite3_prepare16_v3 . +At various points during the compilation process, as logic is being +created to perform various actions, the authorizer callback is invoked +to see if those actions are allowed. +The authorizer callback should return SQLITE_OK to allow the +action, SQLITE_IGNORE to disallow the specific action +but allow the SQL statement to continue to be compiled, or SQLITE_DENY +to cause the entire SQL statement to be rejected with an error. +If the authorizer callback returns any value other than SQLITE_IGNORE, +SQLITE_OK, or SQLITE_DENY then the +.Fn sqlite3_prepare_v2 +or equivalent call that triggered the authorizer will fail with an +error message. +.Pp +When the callback returns SQLITE_OK, that means the operation +requested is ok. +When the callback returns SQLITE_DENY, the +.Fn sqlite3_prepare_v2 +or equivalent call that triggered the authorizer will fail with an +error message explaining that access is denied. +.Pp +The first parameter to the authorizer callback is a copy of the third +parameter to the sqlite3_set_authorizer() interface. +The second parameter to the callback is an integer action code +that specifies the particular action to be authorized. +The third through sixth parameters to the callback are either NULL +pointers or zero-terminated strings that contain additional details +about the action to be authorized. +Applications must always be prepared to encounter a NULL pointer in +any of the third through the sixth parameters of the authorization +callback. +.Pp +If the action code is SQLITE_READ and the callback returns +SQLITE_IGNORE then the prepared statement +statement is constructed to substitute a NULL value in place of the +table column that would have been read if SQLITE_OK had been +returned. +The SQLITE_IGNORE return can be used to deny an untrusted +user access to individual columns of a table. +When a table is referenced by a SELECT but no column values are +extracted from that table (for example in a query like "SELECT count(*) +FROM tab") then the SQLITE_READ authorizer callback is invoked +once for that table with a column name that is an empty string. +If the action code is SQLITE_DELETE and the callback returns +SQLITE_IGNORE then the DELETE operation proceeds +but the truncate optimization is disabled and +all rows are deleted individually. +.Pp +An authorizer is used when preparing SQL statements from an +untrusted source, to ensure that the SQL statements do not try to access +data they are not allowed to see, or that they do not try to execute +malicious statements that damage the database. +For example, an application may allow a user to enter arbitrary SQL +queries for evaluation by a database. +But the application does not want the user to be able to make arbitrary +changes to the database. +An authorizer could then be put in place while the user-entered SQL +is being prepared that disallows everything except SELECT +statements. +.Pp +Applications that need to process SQL from untrusted sources might +also consider lowering resource limits using +.Fn sqlite3_limit +and limiting database size using the max_page_count PRAGMA +in addition to using an authorizer. +.Pp +Only a single authorizer can be in place on a database connection at +a time. +Each call to sqlite3_set_authorizer overrides the previous call. +Disable the authorizer by installing a NULL callback. +The authorizer is disabled by default. +.Pp +The authorizer callback must not do anything that will modify the database +connection that invoked the authorizer callback. +Note that +.Fn sqlite3_prepare_v2 +and +.Fn sqlite3_step +both modify their database connections for the meaning of "modify" +in this paragraph. +.Pp +When +.Fn sqlite3_prepare_v2 +is used to prepare a statement, the statement might be re-prepared +during +.Fn sqlite3_step +due to a schema change. +Hence, the application should ensure that the correct authorizer callback +remains in place during the +.Fn sqlite3_step . +Note that the authorizer callback is invoked only during +.Fn sqlite3_prepare +or its variants. +Authorization is not performed during statement evaluation in +.Fn sqlite3_step , +unless as stated in the previous paragraph, sqlite3_step() invokes +sqlite3_prepare_v2() to reprepare a statement after a schema change. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3124. +.Bd -literal +SQLITE_API int sqlite3_set_authorizer( + sqlite3*, + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), + void *pUserData +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_limit 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_CREATE_INDEX 3 , +.Xr SQLITE_DENY 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_set_last_insert_rowid.3 b/static/netbsd/man3/sqlite3_set_last_insert_rowid.3 new file mode 100644 index 00000000..dea0d1a3 --- /dev/null +++ b/static/netbsd/man3/sqlite3_set_last_insert_rowid.3 @@ -0,0 +1,23 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SET_LAST_INSERT_ROWID 3 +.Os +.Sh NAME +.Nm sqlite3_set_last_insert_rowid +.Nd set the last insert rowid value +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_set_last_insert_rowid +.Fa "sqlite3*" +.Fa "sqlite3_int64" +.Fc +.Sh DESCRIPTION +The sqlite3_set_last_insert_rowid(D, R) method allows the application +to set the value returned by calling sqlite3_last_insert_rowid(D) to +R without inserting a row into the database. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2589. +.Bd -literal +SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64); +.Ed diff --git a/static/netbsd/man3/sqlite3_sleep.3 b/static/netbsd/man3/sqlite3_sleep.3 new file mode 100644 index 00000000..750652e8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_sleep.3 @@ -0,0 +1,42 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SLEEP 3 +.Os +.Sh NAME +.Nm sqlite3_sleep +.Nd suspend execution for a short time +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_sleep +.Fa "int" +.Fc +.Sh DESCRIPTION +The sqlite3_sleep() function causes the current thread to suspend execution +for at least a number of milliseconds specified in its parameter. +.Pp +If the operating system does not support sleep requests with millisecond +time resolution, then the time will be rounded up to the nearest second. +The number of milliseconds of sleep actually requested from the operating +system is returned. +.Pp +SQLite implements this interface by calling the xSleep() method of +the default sqlite3_vfs object. +If the xSleep() method of the default VFS is not implemented correctly, +or not implemented at all, then the behavior of sqlite3_sleep() may +deviate from the description in the previous paragraphs. +.Pp +If a negative argument is passed to sqlite3_sleep() the results vary +by VFS and operating system. +Some system treat a negative argument as an instruction to sleep forever. +Others understand it to mean do not sleep at all. +In SQLite version 3.42.0 and later, a negative argument passed into +sqlite3_sleep() is changed to zero before it is relayed down into the +xSleep method of the VFS. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6398. +.Bd -literal +SQLITE_API int sqlite3_sleep(int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_snapshot.3 b/static/netbsd/man3/sqlite3_snapshot.3 new file mode 100644 index 00000000..367e56a9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot +.Nd database snapshot +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_snapshot { unsigned char hidden[48]; } sqlite3_snapshot; +.Sh DESCRIPTION +An instance of the snapshot object records the state of a WAL mode +database for some specific point in history. +.Pp +In WAL mode, multiple database connections +that are open on the same database file can each be reading a different +historical version of the database file. +When a database connection begins a read transaction, +that connection sees an unchanging copy of the database as it existed +for the point in time when the transaction first started. +Subsequent changes to the database from other connections are not seen +by the reader until a new read transaction is started. +.Pp +The sqlite3_snapshot object records state information about an historical +version of the database file so that it is possible to later open a +new read transaction that sees that historical version of the database +rather than the most recent version. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10446. +.Bd -literal +typedef struct sqlite3_snapshot { + unsigned char hidden[48]; +} sqlite3_snapshot; +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 diff --git a/static/netbsd/man3/sqlite3_snapshot_cmp.3 b/static/netbsd/man3/sqlite3_snapshot_cmp.3 new file mode 100644 index 00000000..13918507 --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot_cmp.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT_CMP 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot_cmp +.Nd compare the ages of two snapshot handles +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_snapshot_cmp +.Fa "sqlite3_snapshot *p1" +.Fa "sqlite3_snapshot *p2" +.Fc +.Sh DESCRIPTION +The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages +of two valid snapshot handles. +.Pp +If the two snapshot handles are not associated with the same database +file, the result of the comparison is undefined. +.Pp +Additionally, the result of the comparison is only valid if both of +the snapshot handles were obtained by calling sqlite3_snapshot_get() +since the last time the wal file was deleted. +The wal file is deleted when the database is changed back to rollback +mode or when the number of database clients drops to zero. +If either snapshot handle was obtained before the wal file was last +deleted, the value returned by this function is undefined. +.Pp +Otherwise, this API returns a negative value if P1 refers to an older +snapshot than P2, zero if the two handles refer to the same database +snapshot, and a positive value if P1 is a newer snapshot than P2. +.Pp +This interface is only available if SQLite is compiled with the SQLITE_ENABLE_SNAPSHOT +option. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10581. +.Bd -literal +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp( + sqlite3_snapshot *p1, + sqlite3_snapshot *p2 +); +.Ed diff --git a/static/netbsd/man3/sqlite3_snapshot_free.3 b/static/netbsd/man3/sqlite3_snapshot_free.3 new file mode 100644 index 00000000..d78a6505 --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot_free.3 @@ -0,0 +1,30 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT_FREE 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot_free +.Nd destroy a snapshot +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_snapshot_free +.Fa "sqlite3_snapshot*" +.Fc +.Sh DESCRIPTION +The sqlite3_snapshot_free(P) interface destroys +sqlite3_snapshot P. +The application must eventually free every sqlite3_snapshot +object using this routine to avoid a memory leak. +.Pp +The +.Fn sqlite3_snapshot_free +interface is only available when the SQLITE_ENABLE_SNAPSHOT +compile-time option is used. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10568. +.Bd -literal +SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_snapshot 3 diff --git a/static/netbsd/man3/sqlite3_snapshot_get.3 b/static/netbsd/man3/sqlite3_snapshot_get.3 new file mode 100644 index 00000000..b7c2cd2e --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot_get.3 @@ -0,0 +1,76 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT_GET 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot_get +.Nd record a database snapshot +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_snapshot_get +.Fa "sqlite3 *db" +.Fa "const char *zSchema" +.Fa "sqlite3_snapshot **ppSnapshot" +.Fc +.Sh DESCRIPTION +The sqlite3_snapshot_get(D,S,P) interface +attempts to make a new sqlite3_snapshot object that +records the current state of schema S in database connection D. +On success, the sqlite3_snapshot_get(D,S,P) +interface writes a pointer to the newly created sqlite3_snapshot +object into *P and returns SQLITE_OK. +If there is not already a read-transaction open on schema S when this +function is called, one is opened automatically. +.Pp +The following must be true for this function to succeed. +If any of the following statements are false when sqlite3_snapshot_get() +is called, SQLITE_ERROR is returned. +The final value of *P is undefined in this case. +.Bl -bullet +.It +The database handle must not be in autocommit mode. +.It +Schema S of database connection D must be a WAL mode +database. +.It +There must not be a write transaction open on schema S of database +connection D. +.It +One or more transactions must have been written to the current wal +file since it was created on disk (by any connection). +This means that a snapshot cannot be taken on a wal mode database with +no wal file immediately after it is first opened. +At least one transaction must be written to it first. +.El +.Pp +This function may also return SQLITE_NOMEM. +If it is called with the database handle in autocommit mode but fails +for some other reason, whether or not a read transaction is opened +on schema S is undefined. +.Pp +The sqlite3_snapshot object returned from a successful +call to +.Fn sqlite3_snapshot_get +must be freed using +.Fn sqlite3_snapshot_free +to avoid a memory leak. +.Pp +The +.Fn sqlite3_snapshot_get +interface is only available when the SQLITE_ENABLE_SNAPSHOT +compile-time option is used. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10470. +.Bd -literal +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( + sqlite3 *db, + const char *zSchema, + sqlite3_snapshot **ppSnapshot +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_get_autocommit 3 , +.Xr sqlite3_snapshot 3 , +.Xr sqlite3_snapshot_free 3 diff --git a/static/netbsd/man3/sqlite3_snapshot_open.3 b/static/netbsd/man3/sqlite3_snapshot_open.3 new file mode 100644 index 00000000..35c51a91 --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot_open.3 @@ -0,0 +1,74 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT_OPEN 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot_open +.Nd start a read transaction on an historical snapshot +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_snapshot_open +.Fa "sqlite3 *db" +.Fa "const char *zSchema" +.Fa "sqlite3_snapshot *pSnapshot" +.Fc +.Sh DESCRIPTION +The sqlite3_snapshot_open(D,S,P) interface +either starts a new read transaction or upgrades an existing one for +schema S of database connection D such that the +read transaction refers to historical snapshot P, rather than +the most recent change to the database. +The +.Fn sqlite3_snapshot_open +interface returns SQLITE_OK on success or an appropriate error code +if it fails. +.Pp +In order to succeed, the database connection must not be in autocommit mode +when sqlite3_snapshot_open(D,S,P) is called. +If there is already a read transaction open on schema S, then the database +handle must have no active statements (SELECT statements that have +been passed to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()). +SQLITE_ERROR is returned if either of these conditions is violated, +or if schema S does not exist, or if the snapshot object is invalid. +.Pp +A call to sqlite3_snapshot_open() will fail to open if the specified +snapshot has been overwritten by a checkpoint. +In this case SQLITE_ERROR_SNAPSHOT is returned. +.Pp +If there is already a read transaction open when this function is invoked, +then the same read transaction remains open (on the same database snapshot) +if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT is returned. +If another error code - for example SQLITE_PROTOCOL or an SQLITE_IOERR +error code - is returned, then the final state of the read transaction +is undefined. +If SQLITE_OK is returned, then the read transaction is now open on +database snapshot P. +.Pp +A call to sqlite3_snapshot_open(D,S,P) +will fail if the database connection D does not know that the database +file for schema S is in WAL mode. +A database connection might not know that the database file is in WAL mode +if there has been no prior I/O on that database connection, or if the +database entered WAL mode after the most recent I/O on the +database connection. +(Hint: Run "PRAGMA application_id" against a newly +opened database connection in order to make it ready to use snapshots.) +.Pp +The +.Fn sqlite3_snapshot_open +interface is only available when the SQLITE_ENABLE_SNAPSHOT +compile-time option is used. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10519. +.Bd -literal +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( + sqlite3 *db, + const char *zSchema, + sqlite3_snapshot *pSnapshot +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_get_autocommit 3 , +.Xr sqlite3_snapshot 3 diff --git a/static/netbsd/man3/sqlite3_snapshot_recover.3 b/static/netbsd/man3/sqlite3_snapshot_recover.3 new file mode 100644 index 00000000..36916ce3 --- /dev/null +++ b/static/netbsd/man3/sqlite3_snapshot_recover.3 @@ -0,0 +1,46 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SNAPSHOT_RECOVER 3 +.Os +.Sh NAME +.Nm sqlite3_snapshot_recover +.Nd recover snapshots from a wal file +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_snapshot_recover +.Fa "sqlite3 *db" +.Fa "const char *zDb" +.Fc +.Sh DESCRIPTION +If a WAL file remains on disk after all database connections +close (either through the use of the SQLITE_FCNTL_PERSIST_WAL +file control or because the last process to have the database +opened exited without calling +.Fn sqlite3_close ) +and a new connection is subsequently opened on that database and WAL file, +the +.Fn sqlite3_snapshot_open +interface will only be able to open the last transaction added to the +WAL file even though the WAL file contains other valid transactions. +.Pp +This function attempts to scan the WAL file associated with database +zDb of database handle db and make all valid snapshots available to +sqlite3_snapshot_open(). +It is an error if there is already a read transaction open on the database, +or if the database is not a WAL mode database. +.Pp +SQLITE_OK is returned if successful, or an SQLite error code otherwise. +.Pp +This interface is only available if SQLite is compiled with the SQLITE_ENABLE_SNAPSHOT +option. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10611. +.Bd -literal +SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb); +.Ed +.Sh SEE ALSO +.Xr sqlite3_close 3 , +.Xr sqlite3_file_control 3 , +.Xr sqlite3_snapshot_open 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 diff --git a/static/netbsd/man3/sqlite3_soft_heap_limit.3 b/static/netbsd/man3/sqlite3_soft_heap_limit.3 new file mode 100644 index 00000000..03293cda --- /dev/null +++ b/static/netbsd/man3/sqlite3_soft_heap_limit.3 @@ -0,0 +1,28 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SOFT_HEAP_LIMIT 3 +.Os +.Sh NAME +.Nm sqlite3_soft_heap_limit +.Nd deprecated soft heap limit interface +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_soft_heap_limit +.Fa "int N" +.Fc +.Sh DESCRIPTION +This is a deprecated version of the +.Fn sqlite3_soft_heap_limit64 +interface. +This routine is provided for historical compatibility only. +All new applications should use the +.Fn sqlite3_soft_heap_limit64 +interface rather than this one. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7036. +.Bd -literal +SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); +.Ed +.Sh SEE ALSO +.Xr sqlite3_soft_heap_limit64 3 diff --git a/static/netbsd/man3/sqlite3_soft_heap_limit64.3 b/static/netbsd/man3/sqlite3_soft_heap_limit64.3 new file mode 100644 index 00000000..5bab4431 --- /dev/null +++ b/static/netbsd/man3/sqlite3_soft_heap_limit64.3 @@ -0,0 +1,89 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SOFT_HEAP_LIMIT64 3 +.Os +.Sh NAME +.Nm sqlite3_soft_heap_limit64 , +.Nm sqlite3_hard_heap_limit64 +.Nd impose a limit on heap size +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_int64 +.Fo sqlite3_soft_heap_limit64 +.Fa "sqlite3_int64 N" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_hard_heap_limit64 +.Fa "sqlite3_int64 N" +.Fc +.Sh DESCRIPTION +These interfaces impose limits on the amount of heap memory that will +be by all database connections within a single process. +.Pp +The sqlite3_soft_heap_limit64() interface sets and/or queries the soft +limit on the amount of heap memory that may be allocated by SQLite. +SQLite strives to keep heap memory utilization below the soft heap +limit by reducing the number of pages held in the page cache as heap +memory usages approaches the limit. +The soft heap limit is "soft" because even though SQLite strives to +stay below the limit, it will exceed the limit rather than generate +an SQLITE_NOMEM error. +In other words, the soft heap limit is advisory only. +.Pp +The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound +of N bytes on the amount of memory that will be allocated. +The sqlite3_hard_heap_limit64(N) interface is similar to sqlite3_soft_heap_limit64(N) +except that memory allocations will fail when the hard heap limit is +reached. +.Pp +The return value from both sqlite3_soft_heap_limit64() and sqlite3_hard_heap_limit64() +is the size of the heap limit prior to the call, or negative in the +case of an error. +If the argument N is negative then no change is made to the heap limit. +Hence, the current size of heap limits can be determined by invoking +sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1). +.Pp +Setting the heap limits to zero disables the heap limiter mechanism. +.Pp +The soft heap limit may not be greater than the hard heap limit. +If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) +is invoked with a value of N that is greater than the hard heap limit, +the soft heap limit is set to the value of the hard heap limit. +The soft heap limit is automatically enabled whenever the hard heap +limit is enabled. +When sqlite3_hard_heap_limit64(N) is invoked and the soft heap limit +is outside the range of 1..N, then the soft heap limit is set to N. +Invoking sqlite3_soft_heap_limit64(0) when the hard heap limit is enabled +makes the soft heap limit equal to the hard heap limit. +.Pp +The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit +and PRAGMA hard_heap_limit. +.Pp +The heap limits are not enforced in the current implementation if one +or more of following conditions are true: +.Bl -bullet +.It +The limit value is set to zero. +.It +Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) +start-time option and the SQLITE_DEFAULT_MEMSTATUS +compile-time option. +.It +An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE2,...). +.It +The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) +rather than from the heap. +.El +.Pp +The circumstances under which SQLite will enforce the heap limits may +changes in future releases of SQLite. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6969. +.Bd -literal +SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); +SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N); +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_sql.3 b/static/netbsd/man3/sqlite3_sql.3 new file mode 100644 index 00000000..a6d46f6f --- /dev/null +++ b/static/netbsd/man3/sqlite3_sql.3 @@ -0,0 +1,80 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SQL 3 +.Os +.Sh NAME +.Nm sqlite3_sql , +.Nm sqlite3_expanded_sql , +.Nm sqlite3_normalized_sql +.Nd retrieving statement SQL +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_sql +.Fa "sqlite3_stmt *pStmt" +.Fc +.Ft char * +.Fo sqlite3_expanded_sql +.Fa "sqlite3_stmt *pStmt" +.Fc +.Ft const char * +.Fo sqlite3_normalized_sql +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 +SQL text used to create prepared statement P if P +was created by +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare16_v2 , +or +.Fn sqlite3_prepare16_v3 . +The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 +string containing the SQL text of prepared statement P with bound parameters +expanded. +The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8 +string containing the normalized SQL text of prepared statement P. +The semantics used to normalize a SQL statement are unspecified and +subject to change. +At a minimum, literal values will be replaced with suitable placeholders. +.Pp +For example, if a prepared statement is created using the SQL text +"SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 and +parameter :xyz is unbound, then sqlite3_sql() will return the original +string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() will return "SELECT +2345,NULL". +.Pp +The sqlite3_expanded_sql() interface returns NULL if insufficient memory +is available to hold the result, or if the result would exceed the +the maximum string length determined by the SQLITE_LIMIT_LENGTH. +.Pp +The SQLITE_TRACE_SIZE_LIMIT compile-time option +limits the size of bound parameter expansions. +The SQLITE_OMIT_TRACE compile-time option causes sqlite3_expanded_sql() +to always return NULL. +.Pp +The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P) +are managed by SQLite and are automatically freed when the prepared +statement is finalized. +The string returned by sqlite3_expanded_sql(P), on the other hand, +is obtained from +.Fn sqlite3_malloc +and must be freed by the application by passing it to +.Fn sqlite3_free . +The sqlite3_normalized_sql() interface is only available if the SQLITE_ENABLE_NORMALIZE +compile-time option is defined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4321. +.Bd -literal +SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); +SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); +#ifdef SQLITE_ENABLE_NORMALIZE +SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt); +#endif +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_LIMIT_LENGTH 3 diff --git a/static/netbsd/man3/sqlite3_status.3 b/static/netbsd/man3/sqlite3_status.3 new file mode 100644 index 00000000..ef6ab345 --- /dev/null +++ b/static/netbsd/man3/sqlite3_status.3 @@ -0,0 +1,63 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STATUS 3 +.Os +.Sh NAME +.Nm sqlite3_status , +.Nm sqlite3_status64 +.Nd SQLite runtime status +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_status +.Fa "int op" +.Fa "int *pCurrent" +.Fa "int *pHighwater" +.Fa "int resetFlag" +.Fc +.Ft int +.Fo sqlite3_status64 +.Fa "int op" +.Fa "sqlite3_int64 *pCurrent" +.Fa "sqlite3_int64 *pHighwater" +.Fa "int resetFlag" +.Fc +.Sh DESCRIPTION +These interfaces are used to retrieve runtime status information about +the performance of SQLite, and optionally to reset various highwater +marks. +The first argument is an integer code for the specific parameter to +measure. +Recognized integer codes are of the form SQLITE_STATUS_.... +The current value of the parameter is returned into *pCurrent. +The highest recorded value is returned in *pHighwater. +If the resetFlag is true, then the highest record value is reset after +*pHighwater is written. +Some parameters do not record the highest value. +For those parameters nothing is written into *pHighwater and the resetFlag +is ignored. +Other parameters record only the highwater mark and not the current +value. +For these latter parameters nothing is written into *pCurrent. +.Pp +The sqlite3_status() and sqlite3_status64() routines return SQLITE_OK +on success and a non-zero error code on failure. +.Pp +If either the current value or the highwater mark is too large to be +represented by a 32-bit integer, then the values returned by sqlite3_status() +are undefined. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8514. +.Bd -literal +SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); +SQLITE_API int sqlite3_status64( + int op, + sqlite3_int64 *pCurrent, + sqlite3_int64 *pHighwater, + int resetFlag +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_status 3 , +.Xr SQLITE_STATUS_MEMORY_USED 3 diff --git a/static/netbsd/man3/sqlite3_step.3 b/static/netbsd/man3/sqlite3_step.3 new file mode 100644 index 00000000..73b2e35c --- /dev/null +++ b/static/netbsd/man3/sqlite3_step.3 @@ -0,0 +1,142 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STEP 3 +.Os +.Sh NAME +.Nm sqlite3_step +.Nd evaluate an SQL statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_step +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +After a prepared statement has been prepared using +any of +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare16_v2 , +or +.Fn sqlite3_prepare16_v3 +or one of the legacy interfaces +.Fn sqlite3_prepare +or +.Fn sqlite3_prepare16 , +this function must be called one or more times to evaluate the statement. +.Pp +The details of the behavior of the sqlite3_step() interface depend +on whether the statement was prepared using the newer "vX" interfaces +.Fn sqlite3_prepare_v3 , +.Fn sqlite3_prepare_v2 , +.Fn sqlite3_prepare16_v3 , +.Fn sqlite3_prepare16_v2 +or the older legacy interfaces +.Fn sqlite3_prepare +and +.Fn sqlite3_prepare16 . +The use of the new "vX" interface is recommended for new applications +but the legacy interface will continue to be supported. +.Pp +In the legacy interface, the return value will be either SQLITE_BUSY, +SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, +or SQLITE_MISUSE. +With the "v2" interface, any of the other result codes +or extended result codes might be returned as +well. +.Pp +SQLITE_BUSY means that the database engine was unable to +acquire the database locks it needs to do its job. +If the statement is a COMMIT or occurs outside of an explicit +transaction, then you can retry the statement. +If the statement is not a COMMIT and occurs within an explicit +transaction then you should rollback the transaction before continuing. +.Pp +SQLITE_DONE means that the statement has finished executing +successfully. +sqlite3_step() should not be called again on this virtual machine without +first calling +.Fn sqlite3_reset +to reset the virtual machine back to its initial state. +.Pp +If the SQL statement being executed returns any data, then SQLITE_ROW +is returned each time a new row of data is ready for processing by +the caller. +The values may be accessed using the column access functions. +sqlite3_step() is called again to retrieve the next row of data. +.Pp +SQLITE_ERROR means that a run-time error (such as a constraint +violation) has occurred. +sqlite3_step() should not be called again on the VM. +More information may be found by calling +.Fn sqlite3_errmsg . +With the legacy interface, a more specific error code (for example, +SQLITE_INTERRUPT, SQLITE_SCHEMA, SQLITE_CORRUPT, +and so forth) can be obtained by calling +.Fn sqlite3_reset +on the prepared statement. +In the "v2" interface, the more specific error code is returned directly +by sqlite3_step(). +.Pp +SQLITE_MISUSE means that the this routine was called inappropriately. +Perhaps it was called on a prepared statement that +has already been finalized or on one that had previously returned +SQLITE_ERROR or SQLITE_DONE. +Or it could be the case that the same database connection is being +used by two or more threads at the same moment in time. +.Pp +For all versions of SQLite up to and including 3.6.23.1, a call to +.Fn sqlite3_reset +was required after sqlite3_step() returned anything other than SQLITE_ROW +before any subsequent invocation of sqlite3_step(). +Failure to reset the prepared statement using +.Fn sqlite3_reset +would result in an SQLITE_MISUSE return from sqlite3_step(). +But after version 3.6.23.1 (dateof:3.6.23.1, +sqlite3_step() began calling +.Fn sqlite3_reset +automatically in this circumstance rather than returning SQLITE_MISUSE. +This is not considered a compatibility break because any application +that ever receives an SQLITE_MISUSE error is broken by definition. +The SQLITE_OMIT_AUTORESET compile-time option +can be used to restore the legacy behavior. +.Pp +\fBGoofy Interface Alert:\fP In the legacy interface, the sqlite3_step() +API always returns a generic error code, SQLITE_ERROR, +following any error other than SQLITE_BUSY and SQLITE_MISUSE. +You must call +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +in order to find one of the specific error codes that better +describes the error. +We admit that this is a goofy design. +The problem has been fixed with the "v2" interface. +If you prepare all of your SQL statements using +.Fn sqlite3_prepare_v3 +or +.Fn sqlite3_prepare_v2 +or +.Fn sqlite3_prepare16_v2 +or +.Fn sqlite3_prepare16_v3 +instead of the legacy +.Fn sqlite3_prepare +and +.Fn sqlite3_prepare16 +interfaces, then the more specific error codes are returned +directly by sqlite3_step(). +The use of the "vX" interfaces is recommended. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4904. +.Bd -literal +SQLITE_API int sqlite3_step(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_stmt.3 b/static/netbsd/man3/sqlite3_stmt.3 new file mode 100644 index 00000000..0465eecf --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt.3 @@ -0,0 +1,51 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT 3 +.Os +.Sh NAME +.Nm sqlite3_stmt +.Nd prepared statement object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_stmt sqlite3_stmt; +.Sh DESCRIPTION +An instance of this object represents a single SQL statement that has +been compiled into binary form and is ready to be evaluated. +.Pp +Think of each SQL statement as a separate computer program. +The original SQL text is source code. +A prepared statement object is the compiled object code. +All SQL must be converted into a prepared statement before it can be +run. +.Pp +The life-cycle of a prepared statement object usually goes like this: +.Bl -enum +.It +Create the prepared statement object using +.Fn sqlite3_prepare_v2 . +.It +Bind values to parameters using the sqlite3_bind_*() interfaces. +.It +Run the SQL by calling +.Fn sqlite3_step +one or more times. +.It +Reset the prepared statement using +.Fn sqlite3_reset +then go back to step 2. +Do this zero or more times. +.It +Destroy the object using +.Fn sqlite3_finalize . +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4000. +.Bd -literal +typedef struct sqlite3_stmt sqlite3_stmt; +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 diff --git a/static/netbsd/man3/sqlite3_stmt_busy.3 b/static/netbsd/man3/sqlite3_stmt_busy.3 new file mode 100644 index 00000000..4c40a4a0 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_busy.3 @@ -0,0 +1,37 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_BUSY 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_busy +.Nd determine if a prepared statement has been reset +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_busy +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +The sqlite3_stmt_busy(S) interface returns true (non-zero) if the prepared statement +S has been stepped at least once using sqlite3_step(S) +but has neither run to completion (returned SQLITE_DONE +from sqlite3_step(S)) nor been reset using sqlite3_reset(S). +The sqlite3_stmt_busy(S) interface returns false if S is a NULL pointer. +If S is not a NULL pointer and is not a pointer to a valid prepared statement +object, then the behavior is undefined and probably undesirable. +.Pp +This interface can be used in combination +.Fn sqlite3_next_stmt +to locate all prepared statements associated with a database connection +that are in need of being reset. +This can be used, for example, in diagnostic routines to search for +prepared statements that are holding a transaction open. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4464. +.Bd -literal +SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_next_stmt 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_stmt_explain.3 b/static/netbsd/man3/sqlite3_stmt_explain.3 new file mode 100644 index 00000000..5b07249b --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_explain.3 @@ -0,0 +1,56 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_EXPLAIN 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_explain +.Nd change the EXPLAIN setting for a prepared statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_explain +.Fa "sqlite3_stmt *pStmt" +.Fa "int eMode" +.Fc +.Sh DESCRIPTION +The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN setting +for prepared statement S. +If E is zero, then S becomes a normal prepared statement. +If E is 1, then S behaves as if its SQL text began with "EXPLAIN". +If E is 2, then S behaves as if its SQL text began with "EXPLAIN QUERY PLAN". +.Pp +Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared. +SQLite tries to avoid a reprepare, but a reprepare might be necessary +on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode. +.Pp +Because of the potential need to reprepare, a call to sqlite3_stmt_explain(S,E) +will fail with SQLITE_ERROR if S cannot be reprepared because it was +created using +.Fn sqlite3_prepare +instead of the newer +.Fn sqlite3_prepare_v2 +or +.Fn sqlite3_prepare_v3 +interfaces and hence has no saved SQL text with which to reprepare. +.Pp +Changing the explain setting for a prepared statement does not change +the original SQL text for the statement. +Hence, if the SQL text originally began with EXPLAIN or EXPLAIN QUERY +PLAN, but sqlite3_stmt_explain(S,0) is called to convert the statement +into an ordinary statement, the EXPLAIN or EXPLAIN QUERY PLAN keywords +will still appear in the sqlite3_sql(S) output, even though the statement +now acts like a normal SQL statement. +.Pp +This routine returns SQLITE_OK if the explain mode is successfully +changed, or an error code if the explain mode could not be changed. +The explain mode cannot be changed while a statement is active. +Hence, it is good practice to call sqlite3_reset(S) +immediately prior to calling sqlite3_stmt_explain(S,E). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4429. +.Bd -literal +SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode); +.Ed +.Sh SEE ALSO +.Xr sqlite3_prepare 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_stmt_isexplain.3 b/static/netbsd/man3/sqlite3_stmt_isexplain.3 new file mode 100644 index 00000000..403fc9d0 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_isexplain.3 @@ -0,0 +1,24 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_ISEXPLAIN 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_isexplain +.Nd query the EXPLAIN setting for a prepared statement +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_isexplain +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_stmt_isexplain(S) interface returns 1 if the prepared statement +S is an EXPLAIN statement, or 2 if the statement S is an EXPLAIN QUERY +PLAN. +The sqlite3_stmt_isexplain(S) interface returns 0 if S is an ordinary +statement or a NULL pointer. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4417. +.Bd -literal +SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt); +.Ed diff --git a/static/netbsd/man3/sqlite3_stmt_readonly.3 b/static/netbsd/man3/sqlite3_stmt_readonly.3 new file mode 100644 index 00000000..565d2d87 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_readonly.3 @@ -0,0 +1,70 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_READONLY 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_readonly +.Nd determine if an SQL statement writes the database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_readonly +.Fa "sqlite3_stmt *pStmt" +.Fc +.Sh DESCRIPTION +The sqlite3_stmt_readonly(X) interface returns true (non-zero) if and +only if the prepared statement X makes no direct +changes to the content of the database file. +.Pp +Note that application-defined SQL functions +or virtual tables might change the database indirectly +as a side effect. +For example, if an application defines a function "eval()" that calls +.Fn sqlite3_exec , +then the following SQL statement would change the database file through +side-effects: +.Bd -ragged +.Bd -literal +SELECT eval('DELETE FROM t1') FROM t2; +.Ed +.Pp +.Ed +.Pp +But because the SELECT statement does not change the database +file directly, sqlite3_stmt_readonly() would still return true. +.Pp +Transaction control statements such as BEGIN, COMMIT, ROLLBACK, +SAVEPOINT, and RELEASE cause sqlite3_stmt_readonly() +to return true, since the statements themselves do not actually modify +the database but rather they control the timing of when other statements +modify the database. +The ATTACH and DETACH statements also cause sqlite3_stmt_readonly() +to return true since, while those statements change the configuration +of a database connection, they do not make changes to the content of +the database files on disk. +The sqlite3_stmt_readonly() interface returns true for BEGIN since +BEGIN merely sets internal flags, but the BEGIN IMMEDIATE +and BEGIN EXCLUSIVE commands do touch the database and +so sqlite3_stmt_readonly() returns false for those commands. +.Pp +This routine returns false if there is any possibility that the statement +might change the database file. +A false return does not guarantee that the statement will change the +database file. +For example, an UPDATE statement might have a WHERE clause that makes +it a no-op, but the sqlite3_stmt_readonly() result would still be false. +Similarly, a CREATE TABLE IF NOT EXISTS statement is a read-only no-op +if the table already exists, but sqlite3_stmt_readonly() still returns +false for such a statement. +.Pp +If prepared statement X is an EXPLAIN or EXPLAIN QUERY PLAN +statement, then sqlite3_stmt_readonly(X) returns the same value as +if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4368. +.Bd -literal +SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); +.Ed +.Sh SEE ALSO +.Xr sqlite3_exec 3 , +.Xr sqlite3_stmt 3 diff --git a/static/netbsd/man3/sqlite3_stmt_scanstatus.3 b/static/netbsd/man3/sqlite3_stmt_scanstatus.3 new file mode 100644 index 00000000..f6f949d1 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_scanstatus.3 @@ -0,0 +1,83 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_SCANSTATUS 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_scanstatus , +.Nm sqlite3_stmt_scanstatus_v2 +.Nd prepared statement scan status +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_scanstatus +.Fa "sqlite3_stmt *pStmt" +.Fa "int idx" +.Fa "int iScanStatusOp" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3_stmt_scanstatus_v2 +.Fa "sqlite3_stmt *pStmt" +.Fa "int idx" +.Fa "int iScanStatusOp" +.Fa "int flags" +.Fa "void *pOut" +.Fc +.Sh DESCRIPTION +These interfaces return information about the predicted and measured +performance for pStmt. +Advanced applications can use this interface to compare the predicted +and the measured performance and issue warnings and/or rerun ANALYZE +if discrepancies are found. +.Pp +Since this interface is expected to be rarely used, it is only available +if SQLite is compiled using the SQLITE_ENABLE_STMT_SCANSTATUS +compile-time option. +.Pp +The "iScanStatusOp" parameter determines which status information to +return. +The "iScanStatusOp" must be one of the scanstatus options +or the behavior of this interface is undefined. +The requested measurement is written into a variable pointed to by +the "pOut" parameter. +.Pp +The "flags" parameter must be passed a mask of flags. +At present only one flag is defined - SQLITE_SCANSTAT_COMPLEX. +If SQLITE_SCANSTAT_COMPLEX is specified, then status information is +available for all elements of a query plan that are reported by "EXPLAIN +QUERY PLAN" output. +If SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements +that correspond to query loops (the "SCAN..." and "SEARCH..." elements +of the EXPLAIN QUERY PLAN output) are available. +Invoking API sqlite3_stmt_scanstatus() is equivalent to calling sqlite3_stmt_scanstatus_v2() +with a zeroed flags parameter. +.Pp +Parameter "idx" identifies the specific query element to retrieve statistics +for. +Query elements are numbered starting from zero. +A value of -1 may be to query for statistics regarding the entire query. +If idx is out of range - less than -1 or greater than or equal to the +total number of query elements used to implement the statement - a +non-zero value is returned and the variable that pOut points to is +unchanged. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10215. +.Bd -literal +SQLITE_API int sqlite3_stmt_scanstatus( + sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ + int idx, /* Index of loop to report on */ + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ + void *pOut /* Result written here */ +); +SQLITE_API int sqlite3_stmt_scanstatus_v2( + sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ + int idx, /* Index of loop to report on */ + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ + int flags, /* Mask of flags defined below */ + void *pOut /* Result written here */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_stmt_scanstatus_reset 3 , +.Xr SQLITE_SCANSTAT_NLOOP 3 diff --git a/static/netbsd/man3/sqlite3_stmt_scanstatus_reset.3 b/static/netbsd/man3/sqlite3_stmt_scanstatus_reset.3 new file mode 100644 index 00000000..5c567b75 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_scanstatus_reset.3 @@ -0,0 +1,27 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_SCANSTATUS_RESET 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_scanstatus_reset +.Nd zero scan-Status counters +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_stmt_scanstatus_reset +.Fa "sqlite3_stmt*" +.Fc +.Sh DESCRIPTION +Zero all +.Fn sqlite3_stmt_scanstatus +related event counters. +.Pp +This API is only available if the library is built with pre-processor +symbol SQLITE_ENABLE_STMT_SCANSTATUS defined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10272. +.Bd -literal +SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_stmt_scanstatus 3 diff --git a/static/netbsd/man3/sqlite3_stmt_status.3 b/static/netbsd/man3/sqlite3_stmt_status.3 new file mode 100644 index 00000000..42455ce3 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stmt_status.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STMT_STATUS 3 +.Os +.Sh NAME +.Nm sqlite3_stmt_status +.Nd prepared statement status +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stmt_status +.Fa "sqlite3_stmt*" +.Fa "int op" +.Fa "int resetFlg" +.Fc +.Sh DESCRIPTION +Each prepared statement maintains various SQLITE_STMTSTATUS counters +that measure the number of times it has performed specific operations. +These counters can be used to monitor the performance characteristics +of the prepared statements. +For example, if the number of table steps greatly exceeds the number +of table searches or result rows, that would tend to indicate that +the prepared statement is using a full table scan rather than an index. +.Pp +This interface is used to retrieve and reset counter values from a +prepared statement. +The first argument is the prepared statement object to be interrogated. +The second argument is an integer code for a specific SQLITE_STMTSTATUS counter +to be interrogated. +The current value of the requested counter is returned. +If the resetFlg is true, then the counter is reset to zero after this +interface call returns. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8779. +.Bd -literal +SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); +.Ed +.Sh SEE ALSO +.Xr sqlite3_db_status 3 , +.Xr sqlite3_status 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_STMTSTATUS_FULLSCAN_STEP 3 diff --git a/static/netbsd/man3/sqlite3_str.3 b/static/netbsd/man3/sqlite3_str.3 new file mode 100644 index 00000000..b6997705 --- /dev/null +++ b/static/netbsd/man3/sqlite3_str.3 @@ -0,0 +1,39 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STR 3 +.Os +.Sh NAME +.Nm sqlite3_str +.Nd dynamic string object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_str sqlite3_str; +.Sh DESCRIPTION +An instance of the sqlite3_str object contains a dynamically-sized +string under construction. +.Pp +The lifecycle of an sqlite3_str object is as follows: +.Bl -enum +.It +The sqlite3_str object is created using +.Fn sqlite3_str_new . +.It +Text is appended to the sqlite3_str object using various methods, such +as +.Fn sqlite3_str_appendf . +.It +The sqlite3_str object is destroyed and the string it created is returned +using the +.Fn sqlite3_str_finish +interface. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8382. +.Bd -literal +typedef struct sqlite3_str sqlite3_str; +.Ed +.Sh SEE ALSO +.Xr sqlite3_str_appendf 3 , +.Xr sqlite3_str_finish 3 , +.Xr sqlite3_str_new 3 diff --git a/static/netbsd/man3/sqlite3_str_appendf.3 b/static/netbsd/man3/sqlite3_str_appendf.3 new file mode 100644 index 00000000..09021482 --- /dev/null +++ b/static/netbsd/man3/sqlite3_str_appendf.3 @@ -0,0 +1,94 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STR_APPENDF 3 +.Os +.Sh NAME +.Nm sqlite3_str_appendf , +.Nm sqlite3_str_vappendf , +.Nm sqlite3_str_append , +.Nm sqlite3_str_appendall , +.Nm sqlite3_str_appendchar , +.Nm sqlite3_str_reset +.Nd add content to a dynamic string +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_str_appendf +.Fa "sqlite3_str*" +.Fa "const char *zFormat" +.Fa "..." +.Fc +.Ft void +.Fo sqlite3_str_vappendf +.Fa "sqlite3_str*" +.Fa "const char *zFormat" +.Fa "va_list" +.Fc +.Ft void +.Fo sqlite3_str_append +.Fa "sqlite3_str*" +.Fa "const char *zIn" +.Fa "int N" +.Fc +.Ft void +.Fo sqlite3_str_appendall +.Fa "sqlite3_str*" +.Fa "const char *zIn" +.Fc +.Ft void +.Fo sqlite3_str_appendchar +.Fa "sqlite3_str*" +.Fa "int N" +.Fa "char C" +.Fc +.Ft void +.Fo sqlite3_str_reset +.Fa "sqlite3_str*" +.Fc +.Sh DESCRIPTION +These interfaces add content to an sqlite3_str object previously obtained +from +.Fn sqlite3_str_new . +The sqlite3_str_appendf(X,F,...) and sqlite3_str_vappendf(X,F,V) +interfaces uses the built-in printf functionality of +SQLite to append formatted text onto the end of sqlite3_str +object X. +.Pp +The sqlite3_str_append(X,S,N) method appends +exactly N bytes from string S onto the end of the sqlite3_str +object X. +N must be non-negative. +S must contain at least N non-zero bytes of content. +To append a zero-terminated string in its entirety, use the +.Fn sqlite3_str_appendall +method instead. +.Pp +The sqlite3_str_appendall(X,S) method appends +the complete content of zero-terminated string S onto the end of sqlite3_str +object X. +.Pp +The sqlite3_str_appendchar(X,N,C) method +appends N copies of the single-byte character C onto the end of sqlite3_str +object X. +This method can be used, for example, to add whitespace indentation. +.Pp +The sqlite3_str_reset(X) method resets the string +under construction inside sqlite3_str object X back to zero +bytes in length. +.Pp +These methods do not return a result code. +If an error occurs, that fact is recorded in the sqlite3_str +object and can be recovered by a subsequent call to sqlite3_str_errcode(X). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8442. +.Bd -literal +SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...); +SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list); +SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N); +SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn); +SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C); +SQLITE_API void sqlite3_str_reset(sqlite3_str*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_str 3 , +.Xr sqlite3_str_new 3 diff --git a/static/netbsd/man3/sqlite3_str_errcode.3 b/static/netbsd/man3/sqlite3_str_errcode.3 new file mode 100644 index 00000000..60c09ead --- /dev/null +++ b/static/netbsd/man3/sqlite3_str_errcode.3 @@ -0,0 +1,63 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STR_ERRCODE 3 +.Os +.Sh NAME +.Nm sqlite3_str_errcode , +.Nm sqlite3_str_length , +.Nm sqlite3_str_value +.Nd status of a dynamic string +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_str_errcode +.Fa "sqlite3_str*" +.Fc +.Ft int +.Fo sqlite3_str_length +.Fa "sqlite3_str*" +.Fc +.Ft char * +.Fo sqlite3_str_value +.Fa "sqlite3_str*" +.Fc +.Sh DESCRIPTION +These interfaces return the current status of an sqlite3_str +object. +.Pp +If any prior errors have occurred while constructing the dynamic string +in sqlite3_str X, then the sqlite3_str_errcode(X) +method will return an appropriate error code. +The sqlite3_str_errcode(X) method returns SQLITE_NOMEM +following any out-of-memory error, or SQLITE_TOOBIG if +the size of the dynamic string exceeds SQLITE_MAX_LENGTH, +or SQLITE_OK if there have been no errors. +.Pp +The sqlite3_str_length(X) method returns the current +length, in bytes, of the dynamic string under construction in sqlite3_str +object X. +The length returned by sqlite3_str_length(X) does +not include the zero-termination byte. +.Pp +The sqlite3_str_value(X) method returns a pointer +to the current content of the dynamic string under construction in +X. +The value returned by sqlite3_str_value(X) is managed +by the sqlite3_str object X and might be freed or altered by any subsequent +method on the same sqlite3_str object. +Applications must not used the pointer returned sqlite3_str_value(X) +after any subsequent method call on the same object. +Applications may change the content of the string returned by sqlite3_str_value(X) +as long as they do not write into any bytes outside the range of 0 +to sqlite3_str_length(X) and do not read or write +any byte after any subsequent sqlite3_str method call. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8481. +.Bd -literal +SQLITE_API int sqlite3_str_errcode(sqlite3_str*); +SQLITE_API int sqlite3_str_length(sqlite3_str*); +SQLITE_API char *sqlite3_str_value(sqlite3_str*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_str 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_str_finish.3 b/static/netbsd/man3/sqlite3_str_finish.3 new file mode 100644 index 00000000..69f12a62 --- /dev/null +++ b/static/netbsd/man3/sqlite3_str_finish.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STR_FINISH 3 +.Os +.Sh NAME +.Nm sqlite3_str_finish +.Nd finalize a dynamic string +.Sh SYNOPSIS +.In sqlite3.h +.Ft char * +.Fo sqlite3_str_finish +.Fa "sqlite3_str*" +.Fc +.Sh DESCRIPTION +The sqlite3_str_finish(X) interface destroys the +sqlite3_str object X and returns a pointer to a memory buffer obtained +from +.Fn sqlite3_malloc64 +that contains the constructed string. +The calling application should pass the returned value to +.Fn sqlite3_free +to avoid a memory leak. +The sqlite3_str_finish(X) interface may return +a NULL pointer if any errors were encountered during construction of +the string. +The sqlite3_str_finish(X) interface will also +return a NULL pointer if the string in sqlite3_str object +X is zero bytes long. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8427. +.Bd -literal +SQLITE_API char *sqlite3_str_finish(sqlite3_str*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3_str 3 diff --git a/static/netbsd/man3/sqlite3_str_new.3 b/static/netbsd/man3/sqlite3_str_new.3 new file mode 100644 index 00000000..16f3aa04 --- /dev/null +++ b/static/netbsd/man3/sqlite3_str_new.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STR_NEW 3 +.Os +.Sh NAME +.Nm sqlite3_str_new +.Nd create a new dynamic string object +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_str * +.Fo sqlite3_str_new +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +The sqlite3_str_new(D) interface allocates and initializes +a new sqlite3_str object. +To avoid memory leaks, the object returned by +.Fn sqlite3_str_new +must be freed by a subsequent call to sqlite3_str_finish(X). +.Pp +The sqlite3_str_new(D) interface always returns a +pointer to a valid sqlite3_str object, though in the event +of an out-of-memory error the returned object might be a special singleton +that will silently reject new text, always return SQLITE_NOMEM from +.Fn sqlite3_str_errcode , +always return 0 for +.Fn sqlite3_str_length , +and always return NULL from sqlite3_str_finish(X). +It is always safe to use the value returned by sqlite3_str_new(D) +as the sqlite3_str parameter to any of the other sqlite3_str +methods. +.Pp +The D parameter to sqlite3_str_new(D) may be NULL. +If the D parameter in sqlite3_str_new(D) is not NULL, +then the maximum length of the string contained in the sqlite3_str +object will be the value set for sqlite3_limit(D,SQLITE_LIMIT_LENGTH) +instead of SQLITE_MAX_LENGTH. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8400. +.Bd -literal +SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_limit 3 , +.Xr sqlite3_str 3 , +.Xr sqlite3_str_errcode 3 , +.Xr SQLITE_LIMIT_LENGTH 3 diff --git a/static/netbsd/man3/sqlite3_strglob.3 b/static/netbsd/man3/sqlite3_strglob.3 new file mode 100644 index 00000000..a1bb67d2 --- /dev/null +++ b/static/netbsd/man3/sqlite3_strglob.3 @@ -0,0 +1,28 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STRGLOB 3 +.Os +.Sh NAME +.Nm sqlite3_strglob +.Nd string globbing +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_strglob +.Fa "const char *zGlob" +.Fa "const char *zStr" +.Fc +.Sh DESCRIPTION +Note that this routine returns zero on a match and non-zero if the +strings do not match, the same as +.Fn sqlite3_stricmp +and +.Fn sqlite3_strnicmp . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9449. +.Bd -literal +SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr); +.Ed +.Sh SEE ALSO +.Xr sqlite3_stricmp 3 , +.Xr sqlite3_strlike 3 diff --git a/static/netbsd/man3/sqlite3_stricmp.3 b/static/netbsd/man3/sqlite3_stricmp.3 new file mode 100644 index 00000000..85582352 --- /dev/null +++ b/static/netbsd/man3/sqlite3_stricmp.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STRICMP 3 +.Os +.Sh NAME +.Nm sqlite3_stricmp , +.Nm sqlite3_strnicmp +.Nd string comparison +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_stricmp +.Fa "const char *" +.Fa "const char *" +.Fc +.Ft int +.Fo sqlite3_strnicmp +.Fa "const char *" +.Fa "const char *" +.Fa "int" +.Fc +.Sh DESCRIPTION +The +.Fn sqlite3_stricmp +and +.Fn sqlite3_strnicmp +APIs allow applications and extensions to compare the contents of two +buffers containing UTF-8 strings in a case-independent fashion, using +the same definition of "case independence" that SQLite uses internally +when comparing identifiers. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9438. +.Bd -literal +SQLITE_API int sqlite3_stricmp(const char *, const char *); +SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); +.Ed diff --git a/static/netbsd/man3/sqlite3_strlike.3 b/static/netbsd/man3/sqlite3_strlike.3 new file mode 100644 index 00000000..614a4b86 --- /dev/null +++ b/static/netbsd/man3/sqlite3_strlike.3 @@ -0,0 +1,32 @@ +.Dd January 24, 2024 +.Dt SQLITE3_STRLIKE 3 +.Os +.Sh NAME +.Nm sqlite3_strlike +.Nd string LIKE matching +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_strlike +.Fa "const char *zGlob" +.Fa "const char *zStr" +.Fa "unsigned int cEsc" +.Fc +.Sh DESCRIPTION +The sqlite3_strlike(P,X,E) function matches Unicode +characters, though only ASCII characters are case folded. +.Pp +Note that this routine returns zero on a match and non-zero if the +strings do not match, the same as +.Fn sqlite3_stricmp +and +.Fn sqlite3_strnicmp . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9466. +.Bd -literal +SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); +.Ed +.Sh SEE ALSO +.Xr sqlite3_strglob 3 , +.Xr sqlite3_stricmp 3 diff --git a/static/netbsd/man3/sqlite3_system_errno.3 b/static/netbsd/man3/sqlite3_system_errno.3 new file mode 100644 index 00000000..40b89c3f --- /dev/null +++ b/static/netbsd/man3/sqlite3_system_errno.3 @@ -0,0 +1,30 @@ +.Dd January 24, 2024 +.Dt SQLITE3_SYSTEM_ERRNO 3 +.Os +.Sh NAME +.Nm sqlite3_system_errno +.Nd low-level system error code +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_system_errno +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +Attempt to return the underlying operating system error code or error +number that caused the most recent I/O error or failure to open a file. +The return value is OS-dependent. +For example, on unix systems, after +.Fn sqlite3_open_v2 +returns SQLITE_CANTOPEN, this interface could be called +to get back the underlying "errno" that caused the problem, such as +ENOSPC, EAUTH, EISDIR, and so forth. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10433. +.Bd -literal +SQLITE_API int sqlite3_system_errno(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_open 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_table_column_metadata.3 b/static/netbsd/man3/sqlite3_table_column_metadata.3 new file mode 100644 index 00000000..4a304d21 --- /dev/null +++ b/static/netbsd/man3/sqlite3_table_column_metadata.3 @@ -0,0 +1,102 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TABLE_COLUMN_METADATA 3 +.Os +.Sh NAME +.Nm sqlite3_table_column_metadata +.Nd extract metadata about a column of a table +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_table_column_metadata +.Fa "sqlite3 *db" +.Fa "const char *zDbName" +.Fa "const char *zTableName" +.Fa "const char *zColumnName" +.Fa "char const **pzDataType" +.Fa "char const **pzCollSeq" +.Fa "int *pNotNull" +.Fa "int *pPrimaryKey" +.Fa "int *pAutoinc" +.Fc +.Sh DESCRIPTION +The sqlite3_table_column_metadata(X,D,T,C,....) routine returns information +about column C of table T in database D on database connection +X. +The sqlite3_table_column_metadata() interface returns SQLITE_OK and +fills in the non-NULL pointers in the final five arguments with appropriate +values if the specified column exists. +The sqlite3_table_column_metadata() interface returns SQLITE_ERROR +if the specified column does not exist. +If the column-name parameter to sqlite3_table_column_metadata() is +a NULL pointer, then this routine simply checks for the existence of +the table and returns SQLITE_OK if the table exists and SQLITE_ERROR +if it does not. +If the table name parameter T in a call to sqlite3_table_column_metadata(X,D,T,C,...) +is NULL then the result is undefined behavior. +.Pp +The column is identified by the second, third and fourth parameters +to this function. +The second parameter is either the name of the database (i.e. "main", +"temp", or an attached database) containing the specified table or +NULL. +If it is NULL, then all attached databases are searched for the table +using the same algorithm used by the database engine to resolve unqualified +table references. +.Pp +The third and fourth parameters to this function are the table and +column name of the desired column, respectively. +.Pp +Metadata is returned by writing to the memory locations passed as the +5th and subsequent parameters to this function. +Any of these arguments may be NULL, in which case the corresponding +element of metadata is omitted. +.Bd -ragged +.Pp + Parameter Output Type Description + 5th const char* Data type + 6th const char* Name of default collation sequence + 7th int True if column has a NOT NULL constraint + 8th int True if column is part of the PRIMARY KEY + 9th int True if column is AUTOINCREMENT +.Pp +.Ed +.Pp +The memory pointed to by the character pointers returned for the declaration +type and collation sequence is valid until the next call to any SQLite +API function. +.Pp +If the specified table is actually a view, an error code +is returned. +.Pp +If the specified column is "rowid", "oid" or "_rowid_" and the table +is not a WITHOUT ROWID table and an INTEGER PRIMARY KEY +column has been explicitly declared, then the output parameters are +set for the explicitly declared column. +If there is no INTEGER PRIMARY KEY column, then +the outputs for the rowid are set as follows: +.Bd -literal +data type: "INTEGER" collation sequence: "BINARY" not null: 0 primary +key: 1 auto increment: 0 +.Ed +.Pp +This function causes all database schemas to be read from disk and +parsed, if that has not already been done, and returns an error if +any errors are encountered while loading the schema. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7048. +.Bd -literal +SQLITE_API int sqlite3_table_column_metadata( + sqlite3 *db, /* Connection handle */ + const char *zDbName, /* Database name or NULL */ + const char *zTableName, /* Table name */ + const char *zColumnName, /* Column name */ + char const **pzDataType, /* OUTPUT: Declared data type */ + char const **pzCollSeq, /* OUTPUT: Collation sequence name */ + int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ + int *pPrimaryKey, /* OUTPUT: True if column part of PK */ + int *pAutoinc /* OUTPUT: True if column is auto-increment */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 diff --git a/static/netbsd/man3/sqlite3_temp_directory.3 b/static/netbsd/man3/sqlite3_temp_directory.3 new file mode 100644 index 00000000..0ac5193a --- /dev/null +++ b/static/netbsd/man3/sqlite3_temp_directory.3 @@ -0,0 +1,76 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TEMP_DIRECTORY 3 +.Os +.Sh NAME +.Nm sqlite3_temp_directory +.Nd name of the folder holding temporary files +.Sh SYNOPSIS +.In sqlite3.h +.Vt char *sqlite3_temp_directory; +.Sh DESCRIPTION +If this global variable is made to point to a string which is the name +of a folder (a.k.a. +directory), then all temporary files created by SQLite when using a +built-in VFS will be placed in that directory. +If this variable is a NULL pointer, then SQLite performs a search for +an appropriate temporary file directory. +.Pp +Applications are strongly discouraged from using this global variable. +It is required to set a temporary folder on Windows Runtime (WinRT). +But for all other platforms, it is highly recommended that applications +neither read nor write this variable. +This global variable is a relic that exists for backwards compatibility +of legacy applications and should be avoided in new projects. +.Pp +It is not safe to read or modify this variable in more than one thread +at a time. +It is not safe to read or modify this variable if a database connection +is being used at the same time in a separate thread. +It is intended that this variable be set once as part of process initialization +and before any SQLite interface routines have been called and that +this variable remain unchanged thereafter. +.Pp +The temp_store_directory pragma may modify +this variable and cause it to point to memory obtained from sqlite3_malloc. +Furthermore, the temp_store_directory pragma +always assumes that any string that this variable points to is held +in memory obtained from sqlite3_malloc and the pragma +may attempt to free that memory using sqlite3_free. +Hence, if this variable is modified directly, either it should be made +NULL or made to point to memory obtained from sqlite3_malloc +or else the use of the temp_store_directory pragma +should be avoided. +Except when requested by the temp_store_directory pragma, +SQLite does not free the memory that sqlite3_temp_directory points +to. +If the application wants that memory to be freed, it must do so itself, +taking care to only do so after all database connection +objects have been destroyed. +.Pp +\fBNote to Windows Runtime users:\fP The temporary directory must be set +prior to calling sqlite3_open or sqlite3_open_v2. +Otherwise, various features that require the use of temporary files +may fail. +Here is an example of how to do this using C++ with the Windows Runtime: +.Bd -ragged +.Bd -literal +LPCWSTR zPath = Windows::Storage::ApplicationData::Current-> +TemporaryFolder->Path->Data(); char zPathBuf[MAX_PATH + 1]; memset(zPathBuf, +0, sizeof(zPathBuf)); WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, +sizeof(zPathBuf), NULL, NULL); sqlite3_temp_directory = sqlite3_mprintf("%s", +zPathBuf); +.Ed +.Pp +.Ed +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6424. +.Bd -literal +SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory; +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_test_control.3 b/static/netbsd/man3/sqlite3_test_control.3 new file mode 100644 index 00000000..3721e3cb --- /dev/null +++ b/static/netbsd/man3/sqlite3_test_control.3 @@ -0,0 +1,35 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TEST_CONTROL 3 +.Os +.Sh NAME +.Nm sqlite3_test_control +.Nd testing interface +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_test_control +.Fa "int op" +.Fa "..." +.Fc +.Sh DESCRIPTION +The sqlite3_test_control() interface is used to read out internal state +of SQLite and to inject faults into SQLite for testing purposes. +The first parameter is an operation code that determines the number, +meaning, and operation of all subsequent parameters. +.Pp +This interface is not for use by applications. +It exists solely for verifying the correct operation of the SQLite +library. +Depending on how the SQLite library is compiled, this interface might +not exist. +.Pp +The details of the operation codes, their meanings, the parameters +they take, and what they do are all subject to change without notice. +Unlike most of the SQLite API, this function is not guaranteed to operate +consistently from one release to the next. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8264. +.Bd -literal +SQLITE_API int sqlite3_test_control(int op, ...); +.Ed diff --git a/static/netbsd/man3/sqlite3_threadsafe.3 b/static/netbsd/man3/sqlite3_threadsafe.3 new file mode 100644 index 00000000..64e1ac03 --- /dev/null +++ b/static/netbsd/man3/sqlite3_threadsafe.3 @@ -0,0 +1,59 @@ +.Dd January 24, 2024 +.Dt SQLITE3_THREADSAFE 3 +.Os +.Sh NAME +.Nm sqlite3_threadsafe +.Nd test to see if the library is threadsafe +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_threadsafe +.Fa "void" +.Fc +.Sh DESCRIPTION +The sqlite3_threadsafe() function returns zero if and only if SQLite +was compiled with mutexing code omitted due to the SQLITE_THREADSAFE +compile-time option being set to 0. +.Pp +SQLite can be compiled with or without mutexes. +When the SQLITE_THREADSAFE C preprocessor macro is +1 or 2, mutexes are enabled and SQLite is threadsafe. +When the SQLITE_THREADSAFE macro is 0, the mutexes +are omitted. +Without the mutexes, it is not safe to use SQLite concurrently from +more than one thread. +.Pp +Enabling mutexes incurs a measurable performance penalty. +So if speed is of utmost importance, it makes sense to disable the +mutexes. +But for maximum safety, mutexes should be enabled. +The default behavior is for mutexes to be enabled. +.Pp +This interface can be used by an application to make sure that the +version of SQLite that it is linking against was compiled with the +desired setting of the SQLITE_THREADSAFE macro. +.Pp +This interface only reports on the compile-time mutex setting of the +SQLITE_THREADSAFE flag. +If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are +enabled by default but can be fully or partially disabled using a call +to +.Fn sqlite3_config +with the verbs SQLITE_CONFIG_SINGLETHREAD, +SQLITE_CONFIG_MULTITHREAD, or SQLITE_CONFIG_SERIALIZED. +The return value of the sqlite3_threadsafe() function shows only the +compile-time setting of thread safety, not any run-time changes to +that setting made by sqlite3_config(). +In other words, the return value from sqlite3_threadsafe() is unchanged +by calls to sqlite3_config(). +.Pp +See the threading mode documentation for additional information. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 221. +.Bd -literal +SQLITE_API int sqlite3_threadsafe(void); +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/sqlite3_total_changes.3 b/static/netbsd/man3/sqlite3_total_changes.3 new file mode 100644 index 00000000..f4ec74d2 --- /dev/null +++ b/static/netbsd/man3/sqlite3_total_changes.3 @@ -0,0 +1,59 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TOTAL_CHANGES 3 +.Os +.Sh NAME +.Nm sqlite3_total_changes , +.Nm sqlite3_total_changes64 +.Nd total number of rows modified +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_total_changes +.Fa "sqlite3*" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_total_changes64 +.Fa "sqlite3*" +.Fc +.Sh DESCRIPTION +These functions return the total number of rows inserted, modified +or deleted by all INSERT, UPDATE or DELETE statements +completed since the database connection was opened, including those +executed as part of trigger programs. +The two functions are identical except for the type of the return value +and that if the number of rows modified by the connection exceeds the +maximum value supported by type "int", then the return value of sqlite3_total_changes() +is undefined. +Executing any other type of SQL statement does not affect the value +returned by sqlite3_total_changes(). +.Pp +Changes made as part of foreign key actions are +included in the count, but those made as part of REPLACE constraint +resolution are not. +Changes to a view that are intercepted by INSTEAD OF triggers are not +counted. +.Pp +The sqlite3_total_changes(D) interface only +reports the number of rows that changed due to SQL statement run against +database connection D. +Any changes by other database connections are ignored. +To detect changes against a database file from other database connections +use the PRAGMA data_version command or the SQLITE_FCNTL_DATA_VERSION +file control. +.Pp +If a separate thread makes changes on the same database connection +while +.Fn sqlite3_total_changes +is running then the value returned is unpredictable and not meaningful. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2661. +.Bd -literal +SQLITE_API int sqlite3_total_changes(sqlite3*); +SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_changes 3 , +.Xr sqlite3_file_control 3 , +.Xr SQLITE_FCNTL_LOCKSTATE 3 diff --git a/static/netbsd/man3/sqlite3_trace.3 b/static/netbsd/man3/sqlite3_trace.3 new file mode 100644 index 00000000..8209da7c --- /dev/null +++ b/static/netbsd/man3/sqlite3_trace.3 @@ -0,0 +1,70 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TRACE 3 +.Os +.Sh NAME +.Nm sqlite3_trace , +.Nm sqlite3_profile +.Nd tracing and profiling functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_trace +.Fa "sqlite3*" +.Fa "void(*xTrace)(void*,const char*)" +.Fa "void*" +.Fc +.Ft void * +.Fo sqlite3_profile +.Fa "sqlite3*" +.Fa "void(*xProfile)(void*,const char*,sqlite3_uint64)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +These routines are deprecated. +Use the +.Fn sqlite3_trace_v2 +interface instead of the routines described here. +.Pp +These routines register callback functions that can be used for tracing +and profiling the execution of SQL statements. +.Pp +The callback function registered by sqlite3_trace() is invoked at various +times when an SQL statement is being run by +.Fn sqlite3_step . +The sqlite3_trace() callback is invoked with a UTF-8 rendering of the +SQL statement text as the statement first begins executing. +Additional sqlite3_trace() callbacks might occur as each triggered +subprogram is entered. +The callbacks for triggers contain a UTF-8 SQL comment that identifies +the trigger. +.Pp +The SQLITE_TRACE_SIZE_LIMIT compile-time option +can be used to limit the length of bound parameter expansion +in the output of sqlite3_trace(). +.Pp +The callback function registered by sqlite3_profile() is invoked as +each SQL statement finishes. +The profile callback contains the original statement text and an estimate +of wall-clock time of how long that statement took to run. +The profile callback time is in units of nanoseconds, however the current +implementation is only capable of millisecond resolution so the six +least significant digits in the time are meaningless. +Future versions of SQLite might provide greater resolution on the profiler +callback. +Invoking either +.Fn sqlite3_trace +or +.Fn sqlite3_trace_v2 +will cancel the profile callback. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3289. +.Bd -literal +SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, + void(*xTrace)(void*,const char*), void*); +SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, + void(*xProfile)(void*,const char*,sqlite3_uint64), void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_step 3 , +.Xr sqlite3_trace_v2 3 diff --git a/static/netbsd/man3/sqlite3_trace_v2.3 b/static/netbsd/man3/sqlite3_trace_v2.3 new file mode 100644 index 00000000..4c5d5940 --- /dev/null +++ b/static/netbsd/man3/sqlite3_trace_v2.3 @@ -0,0 +1,62 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TRACE_V2 3 +.Os +.Sh NAME +.Nm sqlite3_trace_v2 +.Nd SQL trace hook +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_trace_v2 +.Fa "sqlite3*" +.Fa "unsigned uMask" +.Fa "int(*xCallback)(unsigned,void*,void*,void*)" +.Fa "void *pCtx" +.Fc +.Sh DESCRIPTION +The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback +function X against database connection D, using +property mask M and context pointer P. +If the X callback is NULL or if the M mask is zero, then tracing is +disabled. +The M argument should be the bitwise OR-ed combination of zero or more +SQLITE_TRACE constants. +.Pp +Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P) +overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P) +for the database connection D. +Each database connection may have at most one trace callback. +.Pp +The X callback is invoked whenever any of the events identified by +mask M occur. +The integer return value from the callback is currently ignored, though +this may change in future releases. +Callback implementations should return zero to ensure future compatibility. +.Pp +A trace callback is invoked with four arguments: callback(T,C,P,X). +The T argument is one of the SQLITE_TRACE constants to +indicate why the callback was invoked. +The C argument is a copy of the context pointer. +The P and X arguments are pointers whose meanings depend on T. +.Pp +The sqlite3_trace_v2() interface is intended to replace the legacy +interfaces +.Fn sqlite3_trace +and +.Fn sqlite3_profile , +both of which are deprecated. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3383. +.Bd -literal +SQLITE_API int sqlite3_trace_v2( + sqlite3*, + unsigned uMask, + int(*xCallback)(unsigned,void*,void*,void*), + void *pCtx +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_trace 3 , +.Xr SQLITE_TRACE_STMT 3 diff --git a/static/netbsd/man3/sqlite3_txn_state.3 b/static/netbsd/man3/sqlite3_txn_state.3 new file mode 100644 index 00000000..850eb55c --- /dev/null +++ b/static/netbsd/man3/sqlite3_txn_state.3 @@ -0,0 +1,38 @@ +.Dd January 24, 2024 +.Dt SQLITE3_TXN_STATE 3 +.Os +.Sh NAME +.Nm sqlite3_txn_state +.Nd determine the transaction state of a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_txn_state +.Fa "sqlite3*" +.Fa "const char *zSchema" +.Fc +.Sh DESCRIPTION +The sqlite3_txn_state(D,S) interface returns the current transaction state +of schema S in database connection D. +If S is NULL, then the highest transaction state of any schema on database +connection D is returned. +Transaction states are (in order of lowest to highest): +.Bl -enum +.It +SQLITE_TXN_NONE +.It +SQLITE_TXN_READ +.It +SQLITE_TXN_WRITE +.El +.Pp +If the S argument to sqlite3_txn_state(D,S) is not the name of a valid +schema, then -1 is returned. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6655. +.Bd -literal +SQLITE_API int sqlite3_txn_state(sqlite3*,const char *zSchema); +.Ed +.Sh SEE ALSO +.Xr SQLITE_TXN_NONE 3 diff --git a/static/netbsd/man3/sqlite3_unlock_notify.3 b/static/netbsd/man3/sqlite3_unlock_notify.3 new file mode 100644 index 00000000..ce43a6ef --- /dev/null +++ b/static/netbsd/man3/sqlite3_unlock_notify.3 @@ -0,0 +1,150 @@ +.Dd January 24, 2024 +.Dt SQLITE3_UNLOCK_NOTIFY 3 +.Os +.Sh NAME +.Nm sqlite3_unlock_notify +.Nd unlock notification +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_unlock_notify +.Fa "sqlite3 *pBlocked" +.Fa "void (*xNotify)(void **apArg, int nArg)" +.Fa "void *pNotifyArg" +.Fc +.Sh DESCRIPTION +When running in shared-cache mode, a database operation may fail with +an SQLITE_LOCKED error if the required locks on the shared-cache +or individual tables within the shared-cache cannot be obtained. +See SQLite Shared-Cache Mode for a description +of shared-cache locking. +This API may be used to register a callback that SQLite will invoke +when the connection currently holding the required lock relinquishes +it. +This API is only available if the library was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY +C-preprocessor symbol defined. +.Pp +Shared-cache locks are released when a database connection concludes +its current transaction, either by committing it or rolling it back. +.Pp +When a connection (known as the blocked connection) fails to obtain +a shared-cache lock and SQLITE_LOCKED is returned to the caller, the +identity of the database connection (the blocking connection) that +has locked the required resource is stored internally. +After an application receives an SQLITE_LOCKED error, it may call the +sqlite3_unlock_notify() method with the blocked connection handle as +the first argument to register for a callback that will be invoked +when the blocking connections current transaction is concluded. +The callback is invoked from within the sqlite3_step or +sqlite3_close call that concludes the blocking connection's +transaction. +.Pp +If sqlite3_unlock_notify() is called in a multi-threaded application, +there is a chance that the blocking connection will have already concluded +its transaction by the time sqlite3_unlock_notify() is invoked. +If this happens, then the specified callback is invoked immediately, +from within the call to sqlite3_unlock_notify(). +.Pp +If the blocked connection is attempting to obtain a write-lock on a +shared-cache table, and more than one other connection currently holds +a read-lock on the same table, then SQLite arbitrarily selects one +of the other connections to use as the blocking connection. +.Pp +There may be at most one unlock-notify callback registered by a blocked +connection. +If sqlite3_unlock_notify() is called when the blocked connection already +has a registered unlock-notify callback, then the new callback replaces +the old. +If sqlite3_unlock_notify() is called with a NULL pointer as its second +argument, then any existing unlock-notify callback is canceled. +The blocked connections unlock-notify callback may also be canceled +by closing the blocked connection using +.Fn sqlite3_close . +The unlock-notify callback is not reentrant. +If an application invokes any sqlite3_xxx API functions from within +an unlock-notify callback, a crash or deadlock may be the result. +.Pp +Unless deadlock is detected (see below), sqlite3_unlock_notify() always +returns SQLITE_OK. +.Pp +\fBCallback Invocation Details\fP +.Pp +When an unlock-notify callback is registered, the application provides +a single void* pointer that is passed to the callback when it is invoked. +However, the signature of the callback function allows SQLite to pass +it an array of void* context pointers. +The first argument passed to an unlock-notify callback is a pointer +to an array of void* pointers, and the second is the number of entries +in the array. +.Pp +When a blocking connection's transaction is concluded, there may be +more than one blocked connection that has registered for an unlock-notify +callback. +If two or more such blocked connections have specified the same callback +function, then instead of invoking the callback function multiple times, +it is invoked once with the set of void* context pointers specified +by the blocked connections bundled together into an array. +This gives the application an opportunity to prioritize any actions +related to the set of unblocked database connections. +.Pp +\fBDeadlock Detection\fP +.Pp +Assuming that after registering for an unlock-notify callback a database +waits for the callback to be issued before taking any further action +(a reasonable assumption), then using this API may cause the application +to deadlock. +For example, if connection X is waiting for connection Y's transaction +to be concluded, and similarly connection Y is waiting on connection +X's transaction, then neither connection will proceed and the system +may remain deadlocked indefinitely. +.Pp +To avoid this scenario, the sqlite3_unlock_notify() performs deadlock +detection. +If a given call to sqlite3_unlock_notify() would put the system in +a deadlocked state, then SQLITE_LOCKED is returned and no unlock-notify +callback is registered. +The system is said to be in a deadlocked state if connection A has +registered for an unlock-notify callback on the conclusion of connection +B's transaction, and connection B has itself registered for an unlock-notify +callback when connection A's transaction is concluded. +Indirect deadlock is also detected, so the system is also considered +to be deadlocked if connection B has registered for an unlock-notify +callback on the conclusion of connection C's transaction, where connection +C is waiting on connection A. +Any number of levels of indirection are allowed. +.Pp +\fBThe "DROP TABLE" Exception\fP +.Pp +When a call to +.Fn sqlite3_step +returns SQLITE_LOCKED, it is almost always appropriate to call sqlite3_unlock_notify(). +There is however, one exception. +When executing a "DROP TABLE" or "DROP INDEX" statement, SQLite checks +if there are any currently executing SELECT statements that belong +to the same connection. +If there are, SQLITE_LOCKED is returned. +In this case there is no "blocking connection", so invoking sqlite3_unlock_notify() +results in the unlock-notify callback being invoked immediately. +If the application then re-attempts the "DROP TABLE" or "DROP INDEX" +query, an infinite loop might be the result. +.Pp +One way around this problem is to check the extended error code returned +by an sqlite3_step() call. +If there is a blocking connection, then the extended error code is +set to SQLITE_LOCKED_SHAREDCACHE. +Otherwise, in the special "DROP TABLE/INDEX" case, the extended error +code is just SQLITE_LOCKED. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9316. +.Bd -literal +SQLITE_API int sqlite3_unlock_notify( + sqlite3 *pBlocked, /* Waiting connection */ + void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ + void *pNotifyArg /* Argument to pass to xNotify */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_close 3 , +.Xr sqlite3_step 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_update_hook.3 b/static/netbsd/man3/sqlite3_update_hook.3 new file mode 100644 index 00000000..e330a853 --- /dev/null +++ b/static/netbsd/man3/sqlite3_update_hook.3 @@ -0,0 +1,87 @@ +.Dd January 24, 2024 +.Dt SQLITE3_UPDATE_HOOK 3 +.Os +.Sh NAME +.Nm sqlite3_update_hook +.Nd data change notification callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_update_hook +.Fa "sqlite3*" +.Fa "void(*)(void *,int ,char const *,char const *,sqlite3_int64)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_update_hook() interface registers a callback function with +the database connection identified by the first +argument to be invoked whenever a row is updated, inserted or deleted +in a rowid table. +Any callback set by a previous call to this function for the same database +connection is overridden. +.Pp +The second argument is a pointer to the function to invoke when a row +is updated, inserted or deleted in a rowid table. +The first argument to the callback is a copy of the third argument +to sqlite3_update_hook(). +The second callback argument is one of SQLITE_INSERT, +SQLITE_DELETE, or SQLITE_UPDATE, depending +on the operation that caused the callback to be invoked. +The third and fourth arguments to the callback contain pointers to +the database and table name containing the affected row. +The final callback parameter is the rowid of the row. +In the case of an update, this is the rowid after the update takes +place. +.Pp +The update hook is not invoked when internal system tables are modified +(i.e. sqlite_sequence). +The update hook is not invoked when WITHOUT ROWID tables +are modified. +.Pp +In the current implementation, the update hook is not invoked when +conflicting rows are deleted because of an ON CONFLICT REPLACE +clause. +Nor is the update hook invoked when rows are deleted using the truncate optimization. +The exceptions defined in this paragraph might change in a future release +of SQLite. +.Pp +The update hook implementation must not do anything that will modify +the database connection that invoked the update hook. +Any actions to modify the database connection must be deferred until +after the completion of the +.Fn sqlite3_step +call that triggered the update hook. +Note that +.Fn sqlite3_prepare_v2 +and +.Fn sqlite3_step +both modify their database connections for the meaning of "modify" +in this paragraph. +.Pp +The sqlite3_update_hook(D,C,P) function returns the P argument from +the previous call on the same database connection +D, or NULL for the first call on D. +.Pp +See also the +.Fn sqlite3_commit_hook , +.Fn sqlite3_rollback_hook , +and +.Fn sqlite3_preupdate_hook +interfaces. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6838. +.Bd -literal +SQLITE_API void *sqlite3_update_hook( + sqlite3*, + void(*)(void *,int ,char const *,char const *,sqlite3_int64), + void* +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_commit_hook 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_preupdate_hook 3 , +.Xr sqlite3_step 3 , +.Xr SQLITE_CREATE_INDEX 3 diff --git a/static/netbsd/man3/sqlite3_uri_parameter.3 b/static/netbsd/man3/sqlite3_uri_parameter.3 new file mode 100644 index 00000000..91078bbd --- /dev/null +++ b/static/netbsd/man3/sqlite3_uri_parameter.3 @@ -0,0 +1,118 @@ +.Dd January 24, 2024 +.Dt SQLITE3_URI_PARAMETER 3 +.Os +.Sh NAME +.Nm sqlite3_uri_parameter , +.Nm sqlite3_uri_boolean , +.Nm sqlite3_uri_int64 , +.Nm sqlite3_uri_key +.Nd obtain values for URI parameters +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_uri_parameter +.Fa "sqlite3_filename z" +.Fa "const char *zParam" +.Fc +.Ft int +.Fo sqlite3_uri_boolean +.Fa "sqlite3_filename z" +.Fa "const char *zParam" +.Fa "int bDefault" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_uri_int64 +.Fa "sqlite3_filename" +.Fa "const char*" +.Fa "sqlite3_int64" +.Fc +.Ft const char * +.Fo sqlite3_uri_key +.Fa "sqlite3_filename z" +.Fa "int N" +.Fc +.Sh DESCRIPTION +These are utility routines, useful to custom VFS implementations, +that check if a database file was a URI that contained a specific query +parameter, and if so obtains the value of that query parameter. +.Pp +The first parameter to these interfaces (hereafter referred to as F) +must be one of: +.Bl -bullet +.It +A database filename pointer created by the SQLite core and passed into +the xOpen() method of a VFS implementation, or +.It +A filename obtained from +.Fn sqlite3_db_filename , +or +.It +A new filename constructed using +.Fn sqlite3_create_filename . +.El +.Pp +If the F parameter is not one of the above, then the behavior is undefined +and probably undesirable. +Older versions of SQLite were more tolerant of invalid F parameters +than newer versions. +.Pp +If F is a suitable filename (as described in the previous paragraph) +and if P is the name of the query parameter, then sqlite3_uri_parameter(F,P) +returns the value of the P parameter if it exists or a NULL pointer +if P does not appear as a query parameter on F. +If P is a query parameter of F and it has no explicit value, then sqlite3_uri_parameter(F,P) +returns a pointer to an empty string. +.Pp +The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean +parameter and returns true (1) or false (0) according to the value +of P. +The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the value +of query parameter P is one of "yes", "true", or "on" in any case or +if the value begins with a non-zero number. +The sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value +of query parameter P is one of "no", "false", or "off" in any case +or if the value begins with a numeric zero. +If P is not a query parameter on F or if the value of P does not match +any of the above, then sqlite3_uri_boolean(F,P,B) returns (B!=0). +.Pp +The sqlite3_uri_int64(F,P,D) routine converts the value of P into a +64-bit signed integer and returns that integer, or D if P does not +exist. +If the value of P is something other than an integer, then zero is +returned. +.Pp +The sqlite3_uri_key(F,N) returns a pointer to the name (not the value) +of the N-th query parameter for filename F, or a NULL pointer if N +is less than zero or greater than the number of query parameters minus +1. +The N value is zero-based so N should be 0 to obtain the name of the +first query parameter, 1 for the second parameter, and so forth. +.Pp +If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL +and sqlite3_uri_boolean(F,P,B) returns B. +If F is not a NULL pointer and is not a database file pathname pointer +that the SQLite core passed into the xOpen VFS method, then the behavior +of this routine is undefined and probably undesirable. +.Pp +Beginning with SQLite version 3.31.0 (dateof:3.31.0) +the input F parameter can also be the name of a rollback journal file +or WAL file in addition to the main database file. +Prior to version 3.31.0, these routines would only work if F was the +name of the main database file. +When the F parameter is the name of the rollback journal or WAL file, +it has access to all the same query parameters as were found on the +main database file. +.Pp +See the URI filename documentation for additional information. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3755. +.Bd -literal +SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam); +SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault); +SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64); +SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N); +.Ed +.Sh SEE ALSO +.Xr sqlite3_create_filename 3 , +.Xr sqlite3_db_filename 3 diff --git a/static/netbsd/man3/sqlite3_user_data.3 b/static/netbsd/man3/sqlite3_user_data.3 new file mode 100644 index 00000000..800adbe7 --- /dev/null +++ b/static/netbsd/man3/sqlite3_user_data.3 @@ -0,0 +1,30 @@ +.Dd January 24, 2024 +.Dt SQLITE3_USER_DATA 3 +.Os +.Sh NAME +.Nm sqlite3_user_data +.Nd user data for functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_user_data +.Fa "sqlite3_context*" +.Fc +.Sh DESCRIPTION +The sqlite3_user_data() interface returns a copy of the pointer that +was the pUserData parameter (the 5th parameter) of the +.Fn sqlite3_create_function +and +.Fn sqlite3_create_function16 +routines that originally registered the application defined function. +.Pp +This routine must be called from the same thread in which the application-defined +function is running. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5876. +.Bd -literal +SQLITE_API void *sqlite3_user_data(sqlite3_context*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_create_function 3 diff --git a/static/netbsd/man3/sqlite3_value.3 b/static/netbsd/man3/sqlite3_value.3 new file mode 100644 index 00000000..e05cb6f5 --- /dev/null +++ b/static/netbsd/man3/sqlite3_value.3 @@ -0,0 +1,72 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE 3 +.Os +.Sh NAME +.Nm sqlite3_value +.Nd dynamically typed value object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_value sqlite3_value; +.Sh DESCRIPTION +SQLite uses the sqlite3_value object to represent all values that can +be stored in a database table. +SQLite uses dynamic typing for the values it stores. +Values stored in sqlite3_value objects can be integers, floating point +values, strings, BLOBs, or NULL. +.Pp +An sqlite3_value object may be either "protected" or "unprotected". +Some interfaces require a protected sqlite3_value. +Other interfaces will accept either a protected or an unprotected sqlite3_value. +Every interface that accepts sqlite3_value arguments specifies whether +or not it requires a protected sqlite3_value. +The +.Fn sqlite3_value_dup +interface can be used to construct a new protected sqlite3_value from +an unprotected sqlite3_value. +.Pp +The terms "protected" and "unprotected" refer to whether or not a mutex +is held. +An internal mutex is held for a protected sqlite3_value object but +no mutex is held for an unprotected sqlite3_value object. +If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0 +and with +.Fn sqlite3_threadsafe +returning 0) or if SQLite is run in one of reduced mutex modes SQLITE_CONFIG_SINGLETHREAD +or SQLITE_CONFIG_MULTITHREAD then there is +no distinction between protected and unprotected sqlite3_value objects +and they can be used interchangeably. +However, for maximum code portability it is recommended that applications +still make the distinction between protected and unprotected sqlite3_value +objects even when not strictly required. +.Pp +The sqlite3_value objects that are passed as parameters into the implementation +of application-defined SQL functions +are protected. +The sqlite3_value objects returned by +.Fn sqlite3_vtab_rhs_value +are protected. +The sqlite3_value object returned by +.Fn sqlite3_column_value +is unprotected. +Unprotected sqlite3_value objects may only be used as arguments to +.Fn sqlite3_result_value , +.Fn sqlite3_bind_value , +and +.Fn sqlite3_value_dup . +The sqlite3_value_type() family of interfaces require +protected sqlite3_value objects. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4485. +.Bd -literal +typedef struct sqlite3_value sqlite3_value; +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_result_blob 3 , +.Xr sqlite3_threadsafe 3 , +.Xr sqlite3_value_blob 3 , +.Xr sqlite3_value_dup 3 , +.Xr sqlite3_vtab_rhs_value 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 diff --git a/static/netbsd/man3/sqlite3_value_blob.3 b/static/netbsd/man3/sqlite3_value_blob.3 new file mode 100644 index 00000000..df74210d --- /dev/null +++ b/static/netbsd/man3/sqlite3_value_blob.3 @@ -0,0 +1,250 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_value_blob , +.Nm sqlite3_value_double , +.Nm sqlite3_value_int , +.Nm sqlite3_value_int64 , +.Nm sqlite3_value_pointer , +.Nm sqlite3_value_text , +.Nm sqlite3_value_text16 , +.Nm sqlite3_value_text16le , +.Nm sqlite3_value_text16be , +.Nm sqlite3_value_bytes , +.Nm sqlite3_value_bytes16 , +.Nm sqlite3_value_type , +.Nm sqlite3_value_numeric_type , +.Nm sqlite3_value_nochange , +.Nm sqlite3_value_frombind +.Nd obtaining SQL values +.Sh SYNOPSIS +.In sqlite3.h +.Ft const void * +.Fo sqlite3_value_blob +.Fa "sqlite3_value*" +.Fc +.Ft double +.Fo sqlite3_value_double +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_int +.Fa "sqlite3_value*" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_value_int64 +.Fa "sqlite3_value*" +.Fc +.Ft void * +.Fo sqlite3_value_pointer +.Fa "sqlite3_value*" +.Fa "const char*" +.Fc +.Ft const unsigned char * +.Fo sqlite3_value_text +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16 +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16le +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16be +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_bytes +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_bytes16 +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_type +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_numeric_type +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_nochange +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_frombind +.Fa "sqlite3_value*" +.Fc +.Sh DESCRIPTION +\fBSummary:\fP +.Bd -ragged +.Pp + \fBsqlite3_value_blob\fP \(-> BLOB value + \fBsqlite3_value_double\fP \(-> REAL value + \fBsqlite3_value_int\fP \(-> 32-bit INTEGER value + \fBsqlite3_value_int64\fP \(-> 64-bit INTEGER value + \fBsqlite3_value_pointer\fP \(-> Pointer value + \fBsqlite3_value_text\fP \(-> UTF-8 TEXT value + \fBsqlite3_value_text16\fP \(-> UTF-16 TEXT value in the native byteorder + \fBsqlite3_value_text16be\fP \(-> UTF-16be TEXT value + \fBsqlite3_value_text16le\fP \(-> UTF-16le TEXT value + + \fBsqlite3_value_bytes\fP \(-> Size of a BLOB or a UTF-8 TEXT in bytes + \fBsqlite3_value_bytes16 \fP \(-> Size of UTF-16 TEXT in bytes + \fBsqlite3_value_type\fP \(-> Default datatype of the value + \fBsqlite3_value_numeric_type \fP \(-> Best numeric datatype of the value + \fBsqlite3_value_nochange \fP \(-> True if the column is unchanged in an +UPDATE against a virtual table. + \fBsqlite3_value_frombind \fP \(-> True if value originated from a bound parameter +.Pp +.Ed +.Pp +\fBDetails:\fP +.Pp +These routines extract type, size, and content information from protected sqlite3_value +objects. +Protected sqlite3_value objects are used to pass parameter information +into the functions that implement application-defined SQL functions +and virtual tables. +.Pp +These routines work only with protected sqlite3_value +objects. +Any attempt to use these routines on an unprotected sqlite3_value +is not threadsafe. +.Pp +These routines work just like the corresponding column access functions +except that these routines take a single protected sqlite3_value +object pointer instead of a sqlite3_stmt* pointer and +an integer column number. +.Pp +The sqlite3_value_text16() interface extracts a UTF-16 string in the +native byte-order of the host machine. +The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces +extract UTF-16 strings as big-endian and little-endian respectively. +.Pp +If sqlite3_value object V was initialized using sqlite3_bind_pointer(S,I,P,X,D) +or sqlite3_result_pointer(C,P,X,D) and +if X and Y are strings that compare equal according to strcmp(X,Y), +then sqlite3_value_pointer(V,Y) will return the pointer P. +Otherwise, sqlite3_value_pointer(V,Y) returns a NULL. +The sqlite3_bind_pointer() routine is part of the pointer passing interface +added for SQLite 3.20.0. +.Pp +The sqlite3_value_type(V) interface returns the datatype code +for the initial datatype of the sqlite3_value object V. +The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, +SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. +Other interfaces might change the datatype for an sqlite3_value object. +For example, if the datatype is initially SQLITE_INTEGER and sqlite3_value_text(V) +is called to extract a text value for that integer, then subsequent +calls to sqlite3_value_type(V) might return SQLITE_TEXT. +Whether or not a persistent internal datatype conversion occurs is +undefined and may change from one release of SQLite to the next. +.Pp +The sqlite3_value_numeric_type() interface attempts to apply numeric +affinity to the value. +This means that an attempt is made to convert the value to an integer +or floating point. +If such a conversion is possible without loss of information (in other +words, if the value is a string that looks like a number) then the +conversion is performed. +Otherwise no conversion occurs. +The datatype after conversion is returned. +.Pp +Within the xUpdate method of a virtual table, the +sqlite3_value_nochange(X) interface returns true if and only if the +column corresponding to X is unchanged by the UPDATE operation that +the xUpdate method call was invoked to implement and if and the prior +xColumn method call that was invoked to extracted the value +for that column returned without setting a result (probably because +it queried +.Fn sqlite3_vtab_nochange +and found that the column was unchanging). +Within an xUpdate method, any value for which sqlite3_value_nochange(X) +is true will in all other respects appear to be a NULL value. +If sqlite3_value_nochange(X) is invoked anywhere other than within +an xUpdate method call for an UPDATE statement, then the return +value is arbitrary and meaningless. +.Pp +The sqlite3_value_frombind(X) interface returns non-zero if the value +X originated from one of the sqlite3_bind() interfaces. +If X comes from an SQL literal value, or a table column, or an expression, +then sqlite3_value_frombind(X) returns zero. +.Pp +Please pay particular attention to the fact that the pointer returned +from +.Fn sqlite3_value_blob , +.Fn sqlite3_value_text , +or +.Fn sqlite3_value_text16 +can be invalidated by a subsequent call to +.Fn sqlite3_value_bytes , +.Fn sqlite3_value_bytes16 , +.Fn sqlite3_value_text , +or +.Fn sqlite3_value_text16 . +These routines must be called from the same thread as the SQL function +that supplied the sqlite3_value* parameters. +.Pp +As long as the input parameter is correct, these routines can only +fail if an out-of-memory error occurs during a format conversion. +Only the following subset of interfaces are subject to out-of-memory +errors: +.Bl -bullet +.It +sqlite3_value_blob() +.It +sqlite3_value_text() +.It +sqlite3_value_text16() +.It +sqlite3_value_text16le() +.It +sqlite3_value_text16be() +.It +sqlite3_value_bytes() +.It +sqlite3_value_bytes16() +.El +.Pp +If an out-of-memory error occurs, then the return value from these +routines is the same as if the column had contained an SQL NULL value. +Valid SQL NULL returns can be distinguished from out-of-memory errors +by invoking the +.Fn sqlite3_errcode +immediately after the suspect return value is obtained and before any +other SQLite interface is called on the same database connection. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5629. +.Bd -literal +SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); +SQLITE_API double sqlite3_value_double(sqlite3_value*); +SQLITE_API int sqlite3_value_int(sqlite3_value*); +SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); +SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*); +SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); +SQLITE_API int sqlite3_value_bytes(sqlite3_value*); +SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); +SQLITE_API int sqlite3_value_type(sqlite3_value*); +SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); +SQLITE_API int sqlite3_value_nochange(sqlite3_value*); +SQLITE_API int sqlite3_value_frombind(sqlite3_value*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_vtab_nochange 3 , +.Xr SQLITE_INTEGER 3 diff --git a/static/netbsd/man3/sqlite3_value_dup.3 b/static/netbsd/man3/sqlite3_value_dup.3 new file mode 100644 index 00000000..6b4d56d8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_value_dup.3 @@ -0,0 +1,40 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE_DUP 3 +.Os +.Sh NAME +.Nm sqlite3_value_dup , +.Nm sqlite3_value_free +.Nd copy and free SQL values +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_value * +.Fo sqlite3_value_dup +.Fa "const sqlite3_value*" +.Fc +.Ft void +.Fo sqlite3_value_free +.Fa "sqlite3_value*" +.Fc +.Sh DESCRIPTION +The sqlite3_value_dup(V) interface makes a copy of the sqlite3_value +object D and returns a pointer to that copy. +The sqlite3_value returned is a protected sqlite3_value +object even if the input is not. +The sqlite3_value_dup(V) interface returns NULL if V is NULL or if +a memory allocation fails. +If V is a pointer value, then the result of sqlite3_value_dup(V) +is a NULL value. +.Pp +The sqlite3_value_free(V) interface frees an sqlite3_value +object previously obtained from +.Fn sqlite3_value_dup . +If V is a NULL pointer then sqlite3_value_free(V) is a harmless no-op. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5813. +.Bd -literal +SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*); +SQLITE_API void sqlite3_value_free(sqlite3_value*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_value 3 diff --git a/static/netbsd/man3/sqlite3_value_encoding.3 b/static/netbsd/man3/sqlite3_value_encoding.3 new file mode 100644 index 00000000..2b2b5db7 --- /dev/null +++ b/static/netbsd/man3/sqlite3_value_encoding.3 @@ -0,0 +1,41 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE_ENCODING 3 +.Os +.Sh NAME +.Nm sqlite3_value_encoding +.Nd report the internal text encoding state of an sqlite3_value object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_value_encoding +.Fa "sqlite3_value*" +.Fc +.Sh DESCRIPTION +The sqlite3_value_encoding(X) interface returns one of SQLITE_UTF8, +SQLITE_UTF16BE, or SQLITE_UTF16LE according +to the current text encoding of the value X, assuming that X has type +TEXT. +If sqlite3_value_type(X) returns something other than SQLITE_TEXT, +then the return value from sqlite3_value_encoding(X) is meaningless. +Calls to sqlite3_value_text(X), sqlite3_value_text16(X), +sqlite3_value_text16be(X), sqlite3_value_text16le(X), +sqlite3_value_bytes(X), or sqlite3_value_bytes16(X) +might change the encoding of the value X and thus change the return +from subsequent calls to sqlite3_value_encoding(X). +.Pp +This routine is intended for used by applications that test and validate +the SQLite implementation. +This routine is inquiring about the opaque internal state of an sqlite3_value +object. +Ordinary applications should not need to know what the internal state +of an sqlite3_value object is and hence should not need to use this +interface. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5773. +.Bd -literal +SQLITE_API int sqlite3_value_encoding(sqlite3_value*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_value 3 , +.Xr SQLITE_UTF8 3 diff --git a/static/netbsd/man3/sqlite3_value_subtype.3 b/static/netbsd/man3/sqlite3_value_subtype.3 new file mode 100644 index 00000000..82ce12ee --- /dev/null +++ b/static/netbsd/man3/sqlite3_value_subtype.3 @@ -0,0 +1,36 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE_SUBTYPE 3 +.Os +.Sh NAME +.Nm sqlite3_value_subtype +.Nd finding the subtype of SQL values +.Sh SYNOPSIS +.In sqlite3.h +.Ft unsigned int +.Fo sqlite3_value_subtype +.Fa "sqlite3_value*" +.Fc +.Sh DESCRIPTION +The sqlite3_value_subtype(V) function returns the subtype for an application-defined SQL function +argument V. +The subtype information can be used to pass a limited amount of context +from one SQL function to another. +Use the +.Fn sqlite3_result_subtype +routine to set the subtype for the return value of an SQL function. +.Pp +Every application-defined SQL function +that invoke this interface should include the SQLITE_SUBTYPE +property in the text encoding argument when the function is registered. +If the SQLITE_SUBTYPE property is omitted, then sqlite3_value_subtype() +might return zero instead of the upstream subtype in some corner cases. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5795. +.Bd -literal +SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_create_function 3 , +.Xr sqlite3_result_subtype 3 , +.Xr SQLITE_DETERMINISTIC 3 diff --git a/static/netbsd/man3/sqlite3_version.3 b/static/netbsd/man3/sqlite3_version.3 new file mode 100644 index 00000000..55e6bee9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_version.3 @@ -0,0 +1,68 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VERSION 3 +.Os +.Sh NAME +.Nm sqlite3_version , +.Nm sqlite3_libversion , +.Nm sqlite3_sourceid , +.Nm sqlite3_libversion_number +.Nd run-Time library version numbers +.Sh SYNOPSIS +.In sqlite3.h +.Vt const char sqlite3_version[]; +.Ft const char * +.Fo sqlite3_libversion +.Fa "void" +.Fc +.Ft const char * +.Fo sqlite3_sourceid +.Fa "void" +.Fc +.Ft int +.Fo sqlite3_libversion_number +.Fa "void" +.Fc +.Sh DESCRIPTION +These interfaces provide the same information as the SQLITE_VERSION, +SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID +C preprocessor macros but are associated with the library instead of +the header file. +Cautious programmers might include assert() statements in their application +to verify that values returned by these interfaces match the macros +in the header, and thus ensure that the application is compiled with +matching library and header files. +.Bd -ragged +.Bd -literal +assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); assert( +strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 ); assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 +); +.Ed +.Pp +.Ed +.Pp +The sqlite3_version[] string constant contains the text of SQLITE_VERSION +macro. +The sqlite3_libversion() function returns a pointer to the to the sqlite3_version[] +string constant. +The sqlite3_libversion() function is provided for use in DLLs since +DLL users usually do not have direct access to string constants within +the DLL. +The sqlite3_libversion_number() function returns an integer equal to +SQLITE_VERSION_NUMBER. +The sqlite3_sourceid() function returns a pointer to a string constant +whose value is the same as the SQLITE_SOURCE_ID C preprocessor +macro. +Except if SQLite is built using an edited copy of the amalgamation, +then the last four characters of the hash might be different from SQLITE_SOURCE_ID. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 154. +.Bd -literal +SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; +SQLITE_API const char *sqlite3_libversion(void); +SQLITE_API const char *sqlite3_sourceid(void); +SQLITE_API int sqlite3_libversion_number(void); +.Ed +.Sh SEE ALSO +.Xr SQLITE_VERSION 3 diff --git a/static/netbsd/man3/sqlite3_vfs.3 b/static/netbsd/man3/sqlite3_vfs.3 new file mode 100644 index 00000000..0032750b --- /dev/null +++ b/static/netbsd/man3/sqlite3_vfs.3 @@ -0,0 +1,263 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VFS 3 +.Os +.Sh NAME +.Nm sqlite3_vfs , +.Nm sqlite3_syscall_ptr , +.Nm sqlite3_vfs +.Nd OS interface object +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_vfs sqlite3_vfs; +.Vt typedef void (*sqlite3_syscall_ptr)(void); +.Vt struct sqlite3_vfs ; +.Sh DESCRIPTION +An instance of the sqlite3_vfs object defines the interface between +the SQLite core and the underlying operating system. +The "vfs" in the name of the object stands for "virtual file system". +See the VFS documentation for further information. +.Pp +The VFS interface is sometimes extended by adding new methods onto +the end. +Each time such an extension occurs, the iVersion field is incremented. +The iVersion value started out as 1 in SQLite version 3.5.0 +on dateof:3.5.0, then increased to 2 with SQLite version 3.7.0 +on dateof:3.7.0, and then increased to 3 with SQLite version 3.7.6 +on dateof:3.7.6. +Additional fields may be appended to the sqlite3_vfs object and the +iVersion value may increase again in future versions of SQLite. +Note that due to an oversight, the structure of the sqlite3_vfs object +changed in the transition from SQLite version 3.5.9 to +version 3.6.0 on dateof:3.6.0 and yet the +iVersion field was not increased. +.Pp +The szOsFile field is the size of the subclassed sqlite3_file +structure used by this VFS. +mxPathname is the maximum length of a pathname in this VFS. +.Pp +Registered sqlite3_vfs objects are kept on a linked list formed by +the pNext pointer. +The +.Fn sqlite3_vfs_register +and +.Fn sqlite3_vfs_unregister +interfaces manage this list in a thread-safe way. +The +.Fn sqlite3_vfs_find +interface searches the list. +Neither the application code nor the VFS implementation should use +the pNext pointer. +.Pp +The pNext field is the only field in the sqlite3_vfs structure that +SQLite will ever modify. +SQLite will only access or modify this field while holding a particular +static mutex. +The application should never modify anything within the sqlite3_vfs +object once the object has been registered. +.Pp +The zName field holds the name of the VFS module. +The name must be unique across all VFS modules. +.Pp +SQLite guarantees that the zFilename parameter to xOpen is either a +NULL pointer or string obtained from xFullPathname() with an optional +suffix added. +If a suffix is added to the zFilename parameter, it will consist of +a single "-" character followed by no more than 11 alphanumeric and/or +"-" characters. +SQLite further guarantees that the string will be valid and unchanged +until xClose() is called. +Because of the previous sentence, the sqlite3_file can +safely store a pointer to the filename if it needs to remember the +filename for some reason. +If the zFilename parameter to xOpen is a NULL pointer then xOpen must +invent its own temporary name for the file. +Whenever the xFilename parameter is NULL it will also be the case that +the flags parameter will include SQLITE_OPEN_DELETEONCLOSE. +.Pp +The flags argument to xOpen() includes all bits set in the flags argument +to +.Fn sqlite3_open_v2 . +Or if +.Fn sqlite3_open +or +.Fn sqlite3_open16 +is used, then flags includes at least SQLITE_OPEN_READWRITE +| SQLITE_OPEN_CREATE. +If xOpen() opens a file read-only then it sets *pOutFlags to include +SQLITE_OPEN_READONLY. +Other bits in *pOutFlags may be set. +.Pp +SQLite will also add one of the following flags to the xOpen() call, +depending on the object being opened: +.Bl -bullet +.It +SQLITE_OPEN_MAIN_DB +.It +SQLITE_OPEN_MAIN_JOURNAL +.It +SQLITE_OPEN_TEMP_DB +.It +SQLITE_OPEN_TEMP_JOURNAL +.It +SQLITE_OPEN_TRANSIENT_DB +.It +SQLITE_OPEN_SUBJOURNAL +.It +SQLITE_OPEN_SUPER_JOURNAL +.It +SQLITE_OPEN_WAL +.El +.Pp +The file I/O implementation can use the object type flags to change +the way it deals with files. +For example, an application that does not care about crash recovery +or rollback might make the open of a journal file a no-op. +Writes to this journal would also be no-ops, and any attempt to read +the journal would return SQLITE_IOERR. +Or the implementation might recognize that a database file will be +doing page-aligned sector reads and writes in a random order and set +up its I/O subsystem accordingly. +.Pp +SQLite might also add one of the following flags to the xOpen method: +.Bl -bullet +.It +SQLITE_OPEN_DELETEONCLOSE +.It +SQLITE_OPEN_EXCLUSIVE +.El +.Pp +The SQLITE_OPEN_DELETEONCLOSE flag means the +file should be deleted when it is closed. +The SQLITE_OPEN_DELETEONCLOSE will be set +for TEMP databases and their journals, transient databases, and subjournals. +.Pp +The SQLITE_OPEN_EXCLUSIVE flag is always used +in conjunction with the SQLITE_OPEN_CREATE flag, +which are both directly analogous to the O_EXCL and O_CREAT flags of +the POSIX open() API. +The SQLITE_OPEN_EXCLUSIVE flag, when paired with the SQLITE_OPEN_CREATE, +is used to indicate that file should always be created, and that it +is an error if it already exists. +It is \fInot\fP used to indicate the file should be opened for exclusive +access. +.Pp +At least szOsFile bytes of memory are allocated by SQLite to hold the +sqlite3_file structure passed as the third argument to +xOpen. +The xOpen method does not have to allocate the structure; it should +just fill it in. +Note that the xOpen method must set the sqlite3_file.pMethods to either +a valid sqlite3_io_methods object or to NULL. +xOpen must do this even if the open fails. +SQLite expects that the sqlite3_file.pMethods element will be valid +after xOpen returns regardless of the success or failure of the xOpen +call. +.Pp +The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS +to test for the existence of a file, or SQLITE_ACCESS_READWRITE +to test whether a file is readable and writable, or SQLITE_ACCESS_READ +to test whether a file is at least readable. +The SQLITE_ACCESS_READ flag is never actually used and is not implemented +in the built-in VFSes of SQLite. +The file is named by the second argument and can be a directory. +The xAccess method returns SQLITE_OK on success or some non-zero +error code if there is an I/O error or if the name of the file given +in the second argument is illegal. +If SQLITE_OK is returned, then non-zero or zero is written into *pResOut +to indicate whether or not the file is accessible. +.Pp +SQLite will always allocate at least mxPathname+1 bytes for the output +buffer xFullPathname. +The exact size of the output buffer is also passed as a parameter to +both methods. +If the output buffer is not large enough, SQLITE_CANTOPEN +should be returned. +Since this is handled as a fatal error by SQLite, vfs implementations +should endeavor to prevent this by setting mxPathname to a sufficiently +large value. +.Pp +The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() +interfaces are not strictly a part of the filesystem, but they are +included in the VFS structure for completeness. +The xRandomness() function attempts to return nBytes bytes of good-quality +randomness into zOut. +The return value is the actual number of bytes of randomness obtained. +The xSleep() method causes the calling thread to sleep for at least +the number of microseconds given. +The xCurrentTime() method returns a Julian Day Number for the current +date and time as a floating point value. +The xCurrentTimeInt64() method returns, as an integer, the Julian Day +Number multiplied by 86400000 (the number of milliseconds in a 24-hour +day). +SQLite will use the xCurrentTimeInt64() method to get the current date +and time if that method is available (if iVersion is 2 or greater and +the function pointer is not NULL) and will fall back to xCurrentTime() +if xCurrentTimeInt64() is unavailable. +.Pp +The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces +are not used by the SQLite core. +These optional interfaces are provided by some VFSes to facilitate +testing of the VFS code. +By overriding system calls with functions under its control, a test +program can simulate faults and error conditions that would otherwise +be difficult or impossible to induce. +The set of system calls that can be overridden varies from one VFS +to another, and from one version of the same VFS to the next. +Applications that use these interfaces must be prepared for any or +all of these interfaces to be NULL or for their behavior to change +from one release to the next. +Applications must not attempt to access any of these methods if the +iVersion of the VFS is less than 3. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1295. +.Bd -literal +typedef struct sqlite3_vfs sqlite3_vfs; +typedef void (*sqlite3_syscall_ptr)(void); +struct sqlite3_vfs { + int iVersion; /* Structure version number (currently 3) */ + int szOsFile; /* Size of subclassed sqlite3_file */ + int mxPathname; /* Maximum file pathname length */ + sqlite3_vfs *pNext; /* Next registered VFS */ + const char *zName; /* Name of this virtual file system */ + void *pAppData; /* Pointer to application-specific data */ + int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*, + int flags, int *pOutFlags); + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); + void (*xDlClose)(sqlite3_vfs*, void*); + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); + int (*xSleep)(sqlite3_vfs*, int microseconds); + int (*xCurrentTime)(sqlite3_vfs*, double*); + int (*xGetLastError)(sqlite3_vfs*, int, char *); + /* + ** The methods above are in version 1 of the sqlite_vfs object + ** definition. Those that follow are added in version 2 or later + */ + int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); + /* + ** The methods above are in versions 1 and 2 of the sqlite_vfs object. + ** Those below are for version 3 and greater. + */ + int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); + sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); + const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); + /* + ** The methods above are in versions 1 through 3 of the sqlite_vfs object. + ** New fields may be appended in future versions. The iVersion + ** value will increment whenever this happens. + */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_file 3 , +.Xr sqlite3_io_methods 3 , +.Xr sqlite3_open 3 , +.Xr sqlite3_vfs_find 3 , +.Xr SQLITE_ACCESS_EXISTS 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_OPEN_READONLY 3 diff --git a/static/netbsd/man3/sqlite3_vfs_find.3 b/static/netbsd/man3/sqlite3_vfs_find.3 new file mode 100644 index 00000000..cd71e33a --- /dev/null +++ b/static/netbsd/man3/sqlite3_vfs_find.3 @@ -0,0 +1,61 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VFS_FIND 3 +.Os +.Sh NAME +.Nm sqlite3_vfs_find , +.Nm sqlite3_vfs_register , +.Nm sqlite3_vfs_unregister +.Nd virtual file system objects +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_vfs * +.Fo sqlite3_vfs_find +.Fa "const char *zVfsName" +.Fc +.Ft int +.Fo sqlite3_vfs_register +.Fa "sqlite3_vfs*" +.Fa "int makeDflt" +.Fc +.Ft int +.Fo sqlite3_vfs_unregister +.Fa "sqlite3_vfs*" +.Fc +.Sh DESCRIPTION +A virtual filesystem (VFS) is an sqlite3_vfs object that +SQLite uses to interact with the underlying operating system. +Most SQLite builds come with a single default VFS that is appropriate +for the host computer. +New VFSes can be registered and existing VFSes can be unregistered. +The following interfaces are provided. +.Pp +The sqlite3_vfs_find() interface returns a pointer to a VFS given its +name. +Names are case sensitive. +Names are zero-terminated UTF-8 strings. +If there is no match, a NULL pointer is returned. +If zVfsName is NULL then the default VFS is returned. +.Pp +New VFSes are registered with sqlite3_vfs_register(). +Each new VFS becomes the default VFS if the makeDflt flag is set. +The same VFS can be registered multiple times without injury. +To make an existing VFS into the default VFS, register it again with +the makeDflt flag set. +If two different VFSes with the same name are registered, the behavior +is undefined. +If a VFS is registered with a name that is NULL or an empty string, +then the behavior is undefined. +.Pp +Unregister a VFS with the sqlite3_vfs_unregister() interface. +If the default VFS is unregistered, another VFS is chosen as the default. +The choice for the new VFS is arbitrary. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7911. +.Bd -literal +SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); +SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); +SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_vfs 3 diff --git a/static/netbsd/man3/sqlite3_vtab.3 b/static/netbsd/man3/sqlite3_vtab.3 new file mode 100644 index 00000000..9101ab19 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab.3 @@ -0,0 +1,44 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB 3 +.Os +.Sh NAME +.Nm sqlite3_vtab +.Nd virtual table instance object +.Sh SYNOPSIS +.In sqlite3.h +.Vt struct sqlite3_vtab ; +.Sh DESCRIPTION +Every virtual table module implementation uses +a subclass of this object to describe a particular instance of the +virtual table. +Each subclass will be tailored to the specific needs of the module +implementation. +The purpose of this superclass is to define certain fields that are +common to all module implementations. +.Pp +Virtual tables methods can set an error message by assigning a string +obtained from +.Fn sqlite3_mprintf +to zErrMsg. +The method should take care that any prior string is freed by a call +to +.Fn sqlite3_free +prior to assigning a new string to zErrMsg. +After the error message is delivered up to the client application, +the string will be automatically freed by sqlite3_free() and the zErrMsg +field will be zeroed. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7593. +.Bd -literal +struct sqlite3_vtab { + const sqlite3_module *pModule; /* The module for this virtual table */ + int nRef; /* Number of open cursors */ + char *zErrMsg; /* Error message from sqlite3_mprintf() */ + /* Virtual table implementations will typically add additional fields */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3_module 3 , +.Xr sqlite3_mprintf 3 diff --git a/static/netbsd/man3/sqlite3_vtab_collation.3 b/static/netbsd/man3/sqlite3_vtab_collation.3 new file mode 100644 index 00000000..aa505b95 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_collation.3 @@ -0,0 +1,59 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_COLLATION 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_collation +.Nd determine the collation for a virtual table constraint +.Sh SYNOPSIS +.In sqlite3.h +.Ft const char * +.Fo sqlite3_vtab_collation +.Fa "sqlite3_index_info*" +.Fa "int" +.Fc +.Sh DESCRIPTION +This function may only be called from within a call to the xBestIndex +method of a virtual table. +This function returns a pointer to a string that is the name of the +appropriate collation sequence to use for text comparisons on the constraint +identified by its arguments. +.Pp +The first argument must be the pointer to the sqlite3_index_info +object that is the first parameter to the xBestIndex() method. +The second argument must be an index into the aConstraint[] array belonging +to the sqlite3_index_info structure passed to xBestIndex. +.Pp +Important: The first parameter must be the same pointer that is passed +into the xBestMethod() method. +The first parameter may not be a pointer to a different sqlite3_index_info +object, even an exact copy. +.Pp +The return value is computed as follows: +.Bl -enum +.It +.Pp +If the constraint comes from a WHERE clause expression that contains +a COLLATE operator, then the name of the collation +specified by that COLLATE operator is returned. +.It +.Pp +If there is no COLLATE operator, but the column that is the subject +of the constraint specifies an alternative collating sequence via a +COLLATE clause on the column definition within the CREATE +TABLE statement that was passed into +.Fn sqlite3_declare_vtab , +then the name of that alternative collating sequence is returned. +.It +.Pp +Otherwise, "BINARY" is returned. +.El +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9854. +.Bd -literal +SQLITE_API const char *sqlite3_vtab_collation(sqlite3_index_info*,int); +.Ed +.Sh SEE ALSO +.Xr sqlite3_declare_vtab 3 , +.Xr sqlite3_index_info 3 diff --git a/static/netbsd/man3/sqlite3_vtab_config.3 b/static/netbsd/man3/sqlite3_vtab_config.3 new file mode 100644 index 00000000..223a4f12 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_config.3 @@ -0,0 +1,38 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_CONFIG 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_config +.Nd virtual table interface configuration +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_config +.Fa "sqlite3*" +.Fa "int op" +.Fa "..." +.Fc +.Sh DESCRIPTION +This function may be called by either the xConnect or xCreate +method of a virtual table implementation to configure +various facets of the virtual table interface. +.Pp +If this interface is invoked outside the context of an xConnect or +xCreate virtual table method then the behavior is undefined. +.Pp +In the call sqlite3_vtab_config(D,C,...) the D parameter is the database connection +in which the virtual table is being created and which is passed in +as the first argument to the xConnect or xCreate method +that is invoking sqlite3_vtab_config(). +The C parameter is one of the virtual table configuration options. +The presence and meaning of parameters after C depend on which virtual table configuration option +is used. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9720. +.Bd -literal +SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr SQLITE_VTAB_CONSTRAINT_SUPPORT 3 diff --git a/static/netbsd/man3/sqlite3_vtab_cursor.3 b/static/netbsd/man3/sqlite3_vtab_cursor.3 new file mode 100644 index 00000000..cfd35ecf --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_cursor.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_CURSOR 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_cursor +.Nd virtual table cursor object +.Sh SYNOPSIS +.In sqlite3.h +.Vt struct sqlite3_vtab_cursor ; +.Sh DESCRIPTION +Every virtual table module implementation uses +a subclass of the following structure to describe cursors that point +into the virtual table and are used to loop through the +virtual table. +Cursors are created using the xOpen method of the module and are +destroyed by the xClose method. +Cursors are used by the xFilter, xNext, xEof, xColumn, +and xRowid methods of the module. +Each module implementation will define the content of a cursor structure +to suit its own needs. +.Pp +This superclass exists in order to define fields of the cursor that +are common to all implementations. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7618. +.Bd -literal +struct sqlite3_vtab_cursor { + sqlite3_vtab *pVtab; /* Virtual table of this cursor */ + /* Virtual table implementations will typically add additional fields */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_module 3 diff --git a/static/netbsd/man3/sqlite3_vtab_distinct.3 b/static/netbsd/man3/sqlite3_vtab_distinct.3 new file mode 100644 index 00000000..ead97119 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_distinct.3 @@ -0,0 +1,100 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_DISTINCT 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_distinct +.Nd determine if a virtual table query is DISTINCT +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_distinct +.Fa "sqlite3_index_info*" +.Fc +.Sh DESCRIPTION +This API may only be used from within an xBestIndex method +of a virtual table implementation. +The result of calling this interface from outside of xBestIndex() is +undefined and probably harmful. +.Pp +The sqlite3_vtab_distinct() interface returns an integer between 0 +and 3. +The integer returned by sqlite3_vtab_distinct() gives the virtual table +additional information about how the query planner wants the output +to be ordered. +As long as the virtual table can meet the ordering requirements of +the query planner, it may set the "orderByConsumed" flag. +.Bl -enum +.It +.Pp +If the sqlite3_vtab_distinct() interface returns 0, that means that +the query planner needs the virtual table to return all rows in the +sort order defined by the "nOrderBy" and "aOrderBy" fields of the sqlite3_index_info +object. +This is the default expectation. +If the virtual table outputs all rows in sorted order, then it is always +safe for the xBestIndex method to set the "orderByConsumed" flag, regardless +of the return value from sqlite3_vtab_distinct(). +.It +.Pp +If the sqlite3_vtab_distinct() interface returns 1, that means that +the query planner does not need the rows to be returned in sorted order +as long as all rows with the same values in all columns identified +by the "aOrderBy" field are adjacent. +This mode is used when the query planner is doing a GROUP BY. +.It +.Pp +If the sqlite3_vtab_distinct() interface returns 2, that means that +the query planner does not need the rows returned in any particular +order, as long as rows with the same values in all "aOrderBy" columns +are adjacent. +Furthermore, only a single row for each particular combination of values +in the columns identified by the "aOrderBy" field needs to be returned. +It is always ok for two or more rows with the same values in all "aOrderBy" +columns to be returned, as long as all such rows are adjacent. +The virtual table may, if it chooses, omit extra rows that have the +same value for all columns identified by "aOrderBy". +However omitting the extra rows is optional. +This mode is used for a DISTINCT query. +.It +.Pp +If the sqlite3_vtab_distinct() interface returns 3, that means that +the query planner needs only distinct rows but it does need the rows +to be sorted. +The virtual table implementation is free to omit rows that are identical +in all aOrderBy columns, if it wants to, but it is not required to +omit any rows. +This mode is used for queries that have both DISTINCT and ORDER BY +clauses. +.El +.Pp +For the purposes of comparing virtual table output values to see if +the values are same value for sorting purposes, two NULL values are +considered to be the same. +In other words, the comparison operator is "IS" (or "IS NOT DISTINCT +FROM") and not "==". +.Pp +If a virtual table implementation is unable to meet the requirements +specified above, then it must not set the "orderByConsumed" flag in +the sqlite3_index_info object or an incorrect answer +may result. +.Pp +A virtual table implementation is always free to return rows in any +order it wants, as long as the "orderByConsumed" flag is not set. +When the the "orderByConsumed" flag is unset, the query planner will +add extra bytecode to ensure that the final results returned +by the SQL query are ordered correctly. +The use of the "orderByConsumed" flag and the sqlite3_vtab_distinct() +interface is merely an optimization. +Careful use of the sqlite3_vtab_distinct() interface and the "orderByConsumed" +flag might help queries against a virtual table to run faster. +Being overly aggressive and setting the "orderByConsumed" flag when +it is not valid to do so, on the other hand, might cause SQLite to +return incorrect results. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9889. +.Bd -literal +SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_index_info 3 diff --git a/static/netbsd/man3/sqlite3_vtab_in.3 b/static/netbsd/man3/sqlite3_vtab_in.3 new file mode 100644 index 00000000..28cd5cb8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_in.3 @@ -0,0 +1,96 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_IN 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_in +.Nd identify and handle IN constraints in xBestIndex +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_in +.Fa "sqlite3_index_info*" +.Fa "int iCons" +.Fa "int bHandle" +.Fc +.Sh DESCRIPTION +This interface may only be used from within an xBestIndex() method +of a virtual table implementation. +The result of invoking this interface from any other context is undefined +and probably harmful. +.Pp +A constraint on a virtual table of the form "column IN (...)" +is communicated to the xBestIndex method as a SQLITE_INDEX_CONSTRAINT_EQ +constraint. +If xBestIndex wants to use this constraint, it must set the corresponding +aConstraintUsage[].argvIndex to a positive integer. +Then, under the usual mode of handling IN operators, SQLite generates +bytecode that invokes the xFilter() method +once for each value on the right-hand side of the IN operator. +Thus the virtual table only sees a single value from the right-hand +side of the IN operator at a time. +.Pp +In some cases, however, it would be advantageous for the virtual table +to see all values on the right-hand of the IN operator all at once. +The sqlite3_vtab_in() interfaces facilitates this in two ways: +.Bl -enum +.It +.Pp +A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) if and +only if the P->aConstraintN constraint is an IN operator +that can be processed all at once. +In other words, sqlite3_vtab_in() with -1 in the third argument is +a mechanism by which the virtual table can ask SQLite if all-at-once +processing of the IN operator is even possible. +.It +.Pp +A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates to SQLite +that the virtual table does or does not want to process the IN operator +all-at-once, respectively. +Thus when the third parameter (F) is non-negative, this interface is +the mechanism by which the virtual table tells SQLite how it wants +to process the IN operator. +.El +.Pp +The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times +within the same xBestIndex method call. +For any given P,N pair, the return value from sqlite3_vtab_in(P,N,F) +will always be the same within the same xBestIndex call. +If the interface returns true (non-zero), that means that the constraint +is an IN operator that can be processed all-at-once. +If the constraint is not an IN operator or cannot be processed all-at-once, +then the interface returns false. +.Pp +All-at-once processing of the IN operator is selected if both of the +following conditions are met: +.Bl -enum +.It +.Pp +The P->aConstraintUsageN.argvIndex value is set to a positive integer. +This is how the virtual table tells SQLite that it wants to use the +N-th constraint. +.It +.Pp +The last call to sqlite3_vtab_in(P,N,F) for which F was non-negative +had F>=1. +.El +.Pp +If either or both of the conditions above are false, then SQLite uses +the traditional one-at-a-time processing strategy for the IN constraint. +If both conditions are true, then the argvIndex-th parameter to the +xFilter method will be an sqlite3_value that appears to +be NULL, but which can be passed to +.Fn sqlite3_vtab_in_first +and +.Fn sqlite3_vtab_in_next +to find all values on the right-hand side of the IN constraint. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9962. +.Bd -literal +SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle); +.Ed +.Sh SEE ALSO +.Xr sqlite3_index_info 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_vtab_in_first 3 , +.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 diff --git a/static/netbsd/man3/sqlite3_vtab_in_first.3 b/static/netbsd/man3/sqlite3_vtab_in_first.3 new file mode 100644 index 00000000..7d24bfb8 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_in_first.3 @@ -0,0 +1,71 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_IN_FIRST 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_in_first , +.Nm sqlite3_vtab_in_next +.Nd find all elements on the right-hand side of an IN constraint +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_in_first +.Fa "sqlite3_value *pVal" +.Fa "sqlite3_value **ppOut" +.Fc +.Ft int +.Fo sqlite3_vtab_in_next +.Fa "sqlite3_value *pVal" +.Fa "sqlite3_value **ppOut" +.Fc +.Sh DESCRIPTION +These interfaces are only useful from within the xFilter() method +of a virtual table implementation. +The result of invoking these interfaces from any other context is undefined +and probably harmful. +.Pp +The X parameter in a call to sqlite3_vtab_in_first(X,P) or sqlite3_vtab_in_next(X,P) +should be one of the parameters to the xFilter method which invokes +these routines, and specifically a parameter that was previously selected +for all-at-once IN constraint processing use the +.Fn sqlite3_vtab_in +interface in the xBestIndex method. +If the X parameter is not an xFilter argument that was selected for +all-at-once IN constraint processing, then these routines return SQLITE_ERROR. +.Pp +Use these routines to access all values on the right-hand side of the +IN constraint using code like the following: +.Bd -ragged +.Bd -literal + for(rc=sqlite3_vtab_in_first(pList, &pVal); rc==SQLITE_OK +&& pVal; rc=sqlite3_vtab_in_next(pList, &pVal) ){ // +do something with pVal } if( rc!=SQLITE_OK ){ // an error +has occurred } +.Ed +.Pp +.Ed +.Pp +On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) +routines return SQLITE_OK and set *P to point to the first or next +value on the RHS of the IN constraint. +If there are no more values on the right hand side of the IN constraint, +then *P is set to NULL and these routines return SQLITE_DONE. +The return value might be some other value, such as SQLITE_NOMEM, in +the event of a malfunction. +.Pp +The *ppOut values returned by these routines are only valid until the +next call to either of these routines or until the end of the xFilter +method from which these routines were called. +If the virtual table implementation needs to retain the *ppOut values +for longer, it must make copies. +The *ppOut values are protected. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10035. +.Bd -literal +SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut); +SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut); +.Ed +.Sh SEE ALSO +.Xr sqlite3_value 3 , +.Xr sqlite3_vtab_in 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_vtab_nochange.3 b/static/netbsd/man3/sqlite3_vtab_nochange.3 new file mode 100644 index 00000000..843a1706 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_nochange.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_NOCHANGE 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_nochange +.Nd determine if virtual table column access is for UPDATE +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_nochange +.Fa "sqlite3_context*" +.Fc +.Sh DESCRIPTION +If the sqlite3_vtab_nochange(X) routine is called within the xColumn +method of a virtual table, then it might return true if +the column is being fetched as part of an UPDATE operation during which +the column value will not change. +The virtual table implementation can use this hint as permission to +substitute a return value that is less expensive to compute and that +the corresponding xUpdate method understands as a "no-change" +value. +.Pp +If the xColumn method calls sqlite3_vtab_nochange() and finds +that the column is not changed by the UPDATE statement, then the xColumn +method can optionally return without setting a result, without calling +any of the sqlite3_result_xxxxx() interfaces. +In that case, sqlite3_value_nochange(X) will +return true for the same column in the xUpdate method. +.Pp +The sqlite3_vtab_nochange() routine is an optimization. +Virtual table implementations should continue to give a correct answer +even if the sqlite3_vtab_nochange() interface were to always return +false. +In the current implementation, the sqlite3_vtab_nochange() interface +does always returns false for the enhanced UPDATE FROM statement. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9828. +.Bd -literal +SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_result_blob 3 diff --git a/static/netbsd/man3/sqlite3_vtab_on_conflict.3 b/static/netbsd/man3/sqlite3_vtab_on_conflict.3 new file mode 100644 index 00000000..195f08b4 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_on_conflict.3 @@ -0,0 +1,30 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_ON_CONFLICT 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_on_conflict +.Nd determine the virtual table conflict policy +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_on_conflict +.Fa "sqlite3 *" +.Fc +.Sh DESCRIPTION +This function may only be called from within a call to the xUpdate +method of a virtual table implementation for an INSERT +or UPDATE operation. +The value returned is one of SQLITE_ROLLBACK, SQLITE_IGNORE, +SQLITE_FAIL, SQLITE_ABORT, or SQLITE_REPLACE, +according to the ON CONFLICT mode of the SQL statement that +triggered the call to the xUpdate method of the virtual table. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9816. +.Bd -literal +SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); +.Ed +.Sh SEE ALSO +.Xr SQLITE_DENY 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_ROLLBACK 3 diff --git a/static/netbsd/man3/sqlite3_vtab_rhs_value.3 b/static/netbsd/man3/sqlite3_vtab_rhs_value.3 new file mode 100644 index 00000000..719979b4 --- /dev/null +++ b/static/netbsd/man3/sqlite3_vtab_rhs_value.3 @@ -0,0 +1,66 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VTAB_RHS_VALUE 3 +.Os +.Sh NAME +.Nm sqlite3_vtab_rhs_value +.Nd constraint values in xBestIndex() +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_vtab_rhs_value +.Fa "sqlite3_index_info*" +.Fa "int" +.Fa "sqlite3_value **ppVal" +.Fc +.Sh DESCRIPTION +This API may only be used from within the xBestIndex method +of a virtual table implementation. +The result of calling this interface from outside of an xBestIndex +method are undefined and probably harmful. +.Pp +When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within +the xBestIndex method of a virtual table implementation, +with P being a copy of the sqlite3_index_info object +pointer passed into xBestIndex and J being a 0-based index into P->aConstraint[], +then this routine attempts to set *V to the value of the right-hand +operand of that constraint if the right-hand operand is known. +If the right-hand operand is not known, then *V is set to a NULL pointer. +The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if and +only if *V is set to a value. +The sqlite3_vtab_rhs_value(P,J,V) inteface returns SQLITE_NOTFOUND +if the right-hand side of the J-th constraint is not available. +The sqlite3_vtab_rhs_value() interface can return an result code other +than SQLITE_OK or SQLITE_NOTFOUND if something goes wrong. +.Pp +The sqlite3_vtab_rhs_value() interface is usually only successful if +the right-hand operand of a constraint is a literal value in the original +SQL statement. +If the right-hand operand is an expression or a reference to some other +column or a host parameter, then sqlite3_vtab_rhs_value() +will probably return SQLITE_NOTFOUND. +.Pp +Some constraints, such as SQLITE_INDEX_CONSTRAINT_ISNULL +and SQLITE_INDEX_CONSTRAINT_ISNOTNULL, +have no right-hand operand. +For such constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND. +.Pp +The sqlite3_value object returned in *V is a protected +sqlite3_value and remains valid for the duration of the xBestIndex +method call. +When xBestIndex returns, the sqlite3_value object returned by sqlite3_vtab_rhs_value() +is automatically deallocated. +.Pp +The "_rhs_" in the name of this routine is an abbreviation for "Right-Hand +Side". +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10083. +.Bd -literal +SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_index_info 3 , +.Xr sqlite3_value 3 , +.Xr SQLITE_INDEX_CONSTRAINT_EQ 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_wal_autocheckpoint.3 b/static/netbsd/man3/sqlite3_wal_autocheckpoint.3 new file mode 100644 index 00000000..059cdd18 --- /dev/null +++ b/static/netbsd/man3/sqlite3_wal_autocheckpoint.3 @@ -0,0 +1,51 @@ +.Dd January 24, 2024 +.Dt SQLITE3_WAL_AUTOCHECKPOINT 3 +.Os +.Sh NAME +.Nm sqlite3_wal_autocheckpoint +.Nd configure an auto-checkpoint +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_wal_autocheckpoint +.Fa "sqlite3 *db" +.Fa "int N" +.Fc +.Sh DESCRIPTION +The sqlite3_wal_autocheckpoint(D,N) +is a wrapper around +.Fn sqlite3_wal_hook +that causes any database on database connection +D to automatically checkpoint after committing a transaction +if there are N or more frames in the write-ahead log +file. +Passing zero or a negative value as the nFrame parameter disables automatic +checkpoints entirely. +.Pp +The callback registered by this function replaces any existing callback +registered using +.Fn sqlite3_wal_hook . +Likewise, registering a callback using +.Fn sqlite3_wal_hook +disables the automatic checkpoint mechanism configured by this function. +.Pp +The wal_autocheckpoint pragma can be used +to invoke this interface from SQL. +.Pp +Checkpoints initiated by this mechanism are PASSIVE. +.Pp +Every new database connection defaults to having +the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT +pages. +The use of this interface is only necessary if the default setting +is found to be suboptimal for a particular application. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9553. +.Bd -literal +SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_wal_checkpoint_v2 3 , +.Xr sqlite3_wal_hook 3 diff --git a/static/netbsd/man3/sqlite3_wal_checkpoint.3 b/static/netbsd/man3/sqlite3_wal_checkpoint.3 new file mode 100644 index 00000000..904a085d --- /dev/null +++ b/static/netbsd/man3/sqlite3_wal_checkpoint.3 @@ -0,0 +1,39 @@ +.Dd January 24, 2024 +.Dt SQLITE3_WAL_CHECKPOINT 3 +.Os +.Sh NAME +.Nm sqlite3_wal_checkpoint +.Nd checkpoint a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_wal_checkpoint +.Fa "sqlite3 *db" +.Fa "const char *zDb" +.Fc +.Sh DESCRIPTION +The sqlite3_wal_checkpoint(D,X) is equivalent to sqlite3_wal_checkpoint_v2(D,X,SQLITE_CHECKPOINT_PASSIVE,0,0). +.Pp +In brief, sqlite3_wal_checkpoint(D,X) causes the content in the write-ahead log +for database X on database connection D to be transferred +into the database file and for the write-ahead log to be reset. +See the checkpointing documentation for addition information. +.Pp +This interface used to be the only way to cause a checkpoint to occur. +But then the newer and more powerful +.Fn sqlite3_wal_checkpoint_v2 +interface was added. +This interface is retained for backwards compatibility and as a convenience +for applications that need to manually start a callback but which do +not need the full power (and corresponding complication) of +.Fn sqlite3_wal_checkpoint_v2 . +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9584. +.Bd -literal +SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_wal_checkpoint_v2 3 , +.Xr SQLITE_CHECKPOINT_PASSIVE 3 diff --git a/static/netbsd/man3/sqlite3_wal_checkpoint_v2.3 b/static/netbsd/man3/sqlite3_wal_checkpoint_v2.3 new file mode 100644 index 00000000..e0b6fcea --- /dev/null +++ b/static/netbsd/man3/sqlite3_wal_checkpoint_v2.3 @@ -0,0 +1,128 @@ +.Dd January 24, 2024 +.Dt SQLITE3_WAL_CHECKPOINT_V2 3 +.Os +.Sh NAME +.Nm sqlite3_wal_checkpoint_v2 +.Nd checkpoint a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_wal_checkpoint_v2 +.Fa "sqlite3 *db" +.Fa "const char *zDb" +.Fa "int eMode" +.Fa "int *pnLog" +.Fa "int *pnCkpt" +.Fc +.Sh DESCRIPTION +The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint +operation on database X of database connection D +in mode M. +Status information is written back into integers pointed to by L and +C. +The M parameter must be a valid checkpoint mode: +.Bl -tag -width Ds +.It SQLITE_CHECKPOINT_PASSIVE +Checkpoint as many frames as possible without waiting for any database +readers or writers to finish, then sync the database file if all frames +in the log were checkpointed. +The busy-handler callback is never invoked in +the SQLITE_CHECKPOINT_PASSIVE mode. +On the other hand, passive mode might leave the checkpoint unfinished +if there are concurrent readers or writers. +.It SQLITE_CHECKPOINT_FULL +This mode blocks (it invokes the busy-handler callback) +until there is no database writer and all readers are reading from +the most recent database snapshot. +It then checkpoints all frames in the log file and syncs the database +file. +This mode blocks new database writers while it is pending, but new +database readers are allowed to continue unimpeded. +.It SQLITE_CHECKPOINT_RESTART +This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition +that after checkpointing the log file it blocks (calls the busy-handler callback) +until all readers are reading from the database file only. +This ensures that the next writer will restart the log file from the +beginning. +Like SQLITE_CHECKPOINT_FULL, this mode blocks new database writer attempts +while it is pending, but does not impede readers. +.It SQLITE_CHECKPOINT_TRUNCATE +This mode works the same way as SQLITE_CHECKPOINT_RESTART with the +addition that it also truncates the log file to zero bytes just prior +to a successful return. +.El +.Pp +If pnLog is not NULL, then *pnLog is set to the total number of frames +in the log file or to -1 if the checkpoint could not run because of +an error or because the database is not in WAL mode. +If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed +frames in the log file (including any that were already checkpointed +before the function was called) or to -1 if the checkpoint could not +run due to an error or because the database is not in WAL mode. +Note that upon successful completion of an SQLITE_CHECKPOINT_TRUNCATE, +the log file will have been truncated to zero bytes and so both *pnLog +and *pnCkpt will be set to zero. +.Pp +All calls obtain an exclusive "checkpoint" lock on the database file. +If any other process is running a checkpoint operation at the same +time, the lock cannot be obtained and SQLITE_BUSY is returned. +Even if there is a busy-handler configured, it will not be invoked +in this case. +.Pp +The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain +the exclusive "writer" lock on the database file. +If the writer lock cannot be obtained immediately, and a busy-handler +is configured, it is invoked and the writer lock retried until either +the busy-handler returns 0 or the lock is successfully obtained. +The busy-handler is also invoked while waiting for database readers +as described above. +If the busy-handler returns 0 before the writer lock is obtained or +while waiting for database readers, the checkpoint operation proceeds +from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing +as many frames as possible without blocking any further. +SQLITE_BUSY is returned in this case. +.Pp +If parameter zDb is NULL or points to a zero length string, then the +specified operation is attempted on all WAL databases attached +to database connection db. +In this case the values written to output parameters *pnLog and *pnCkpt +are undefined. +If an SQLITE_BUSY error is encountered when processing one or more +of the attached WAL databases, the operation is still attempted on +any remaining attached databases and SQLITE_BUSY is returned at the +end. +If any other error occurs while processing an attached database, processing +is abandoned and the error code is returned to the caller immediately. +If no error (SQLITE_BUSY or otherwise) is encountered while processing +the attached databases, SQLITE_OK is returned. +.Pp +If database zDb is the name of an attached database that is not in +WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to +-1. +If zDb is not NULL (or a zero length string) and is not the name of +any attached database, SQLITE_ERROR is returned to the caller. +.Pp +Unless it returns SQLITE_MISUSE, the sqlite3_wal_checkpoint_v2() interface +sets the error information that is queried by +.Fn sqlite3_errcode +and +.Fn sqlite3_errmsg . +The PRAGMA wal_checkpoint command can be used +to invoke this interface from SQL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9606. +.Bd -literal +SQLITE_API int sqlite3_wal_checkpoint_v2( + sqlite3 *db, /* Database handle */ + const char *zDb, /* Name of attached database (or NULL) */ + int eMode, /* SQLITE_CHECKPOINT_* value */ + int *pnLog, /* OUT: Size of WAL log in frames */ + int *pnCkpt /* OUT: Total number of frames checkpointed */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_busy_handler 3 , +.Xr sqlite3_errcode 3 , +.Xr SQLITE_CHECKPOINT_PASSIVE 3 diff --git a/static/netbsd/man3/sqlite3_wal_hook.3 b/static/netbsd/man3/sqlite3_wal_hook.3 new file mode 100644 index 00000000..5b3a4e50 --- /dev/null +++ b/static/netbsd/man3/sqlite3_wal_hook.3 @@ -0,0 +1,69 @@ +.Dd January 24, 2024 +.Dt SQLITE3_WAL_HOOK 3 +.Os +.Sh NAME +.Nm sqlite3_wal_hook +.Nd write-Ahead log commit hook +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_wal_hook +.Fa "sqlite3*" +.Fa "int(*)(void *,sqlite3*,const char*,int)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The +.Fn sqlite3_wal_hook +function is used to register a callback that is invoked each time data +is committed to a database in wal mode. +.Pp +The callback is invoked by SQLite after the commit has taken place +and the associated write-lock on the database released, so the implementation +may read, write or checkpoint the database as required. +.Pp +The first parameter passed to the callback function when it is invoked +is a copy of the third parameter passed to sqlite3_wal_hook() when +registering the callback. +The second is a copy of the database handle. +The third parameter is the name of the database that was written to +- either "main" or the name of an ATTACH-ed database. +The fourth parameter is the number of pages currently in the write-ahead +log file, including those that were just committed. +.Pp +The callback function should normally return SQLITE_OK. +If an error code is returned, that error will propagate back up through +the SQLite code base to cause the statement that provoked the callback +to report an error, though the commit will have still occurred. +If the callback returns SQLITE_ROW or SQLITE_DONE, +or if it returns a value that does not correspond to any valid SQLite +error code, the results are undefined. +.Pp +A single database handle may have at most a single write-ahead log +callback registered at one time. +Calling +.Fn sqlite3_wal_hook +replaces any previously registered write-ahead log callback. +The return value is a copy of the third parameter from the previous +call, if any, or 0. +Note that the +.Fn sqlite3_wal_autocheckpoint +interface and the wal_autocheckpoint pragma +both invoke +.Fn sqlite3_wal_hook +and will overwrite any prior +.Fn sqlite3_wal_hook +settings. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 9512. +.Bd -literal +SQLITE_API void *sqlite3_wal_hook( + sqlite3*, + int(*)(void *,sqlite3*,const char*,int), + void* +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_wal_autocheckpoint 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3_win32_set_directory.3 b/static/netbsd/man3/sqlite3_win32_set_directory.3 new file mode 100644 index 00000000..fece2169 --- /dev/null +++ b/static/netbsd/man3/sqlite3_win32_set_directory.3 @@ -0,0 +1,62 @@ +.Dd January 24, 2024 +.Dt SQLITE3_WIN32_SET_DIRECTORY 3 +.Os +.Sh NAME +.Nm sqlite3_win32_set_directory , +.Nm sqlite3_win32_set_directory8 , +.Nm sqlite3_win32_set_directory16 +.Nd win32 specific interface +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_win32_set_directory +.Fa "unsigned long type" +.Fa "void *zValue" +.Fc +.Ft int +.Fo sqlite3_win32_set_directory8 +.Fa "unsigned long type" +.Fa "const char *zValue" +.Fc +.Ft int +.Fo sqlite3_win32_set_directory16 +.Fa "unsigned long type" +.Fa "const void *zValue" +.Fc +.Sh DESCRIPTION +These interfaces are available only on Windows. +The sqlite3_win32_set_directory interface +is used to set the value associated with the sqlite3_temp_directory +or sqlite3_data_directory variable, to zValue, +depending on the value of the type parameter. +The zValue parameter should be NULL to cause the previous value to +be freed via sqlite3_free; a non-NULL value will be copied +into memory obtained from sqlite3_malloc prior to being +used. +The sqlite3_win32_set_directory interface +returns SQLITE_OK to indicate success, SQLITE_ERROR +if the type is unsupported, or SQLITE_NOMEM if memory could +not be allocated. +The value of the sqlite3_data_directory variable +is intended to act as a replacement for the current directory on the +sub-platforms of Win32 where that concept is not present, e.g. WinRT +and UWP. +The sqlite3_win32_set_directory8 and sqlite3_win32_set_directory16 +interfaces behave exactly the same as the sqlite3_win32_set_directory +interface except the string parameter must be UTF-8 or UTF-16, respectively. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 6519. +.Bd -literal +SQLITE_API int sqlite3_win32_set_directory( + unsigned long type, /* Identifier for directory being set or reset */ + void *zValue /* New value for directory being set or reset */ +); +SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue); +SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue); +.Ed +.Sh SEE ALSO +.Xr sqlite3_data_directory 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_temp_directory 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changegroup_add.3 b/static/netbsd/man3/sqlite3changegroup_add.3 new file mode 100644 index 00000000..d93d6563 --- /dev/null +++ b/static/netbsd/man3/sqlite3changegroup_add.3 @@ -0,0 +1,89 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGEGROUP_ADD 3 +.Os +.Sh NAME +.Nm sqlite3changegroup_add +.Nd add a changeset to a changegroup +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changegroup_add +.Fa "sqlite3_changegroup*" +.Fa "int nData" +.Fa "void *pData" +.Fc +.Sh DESCRIPTION +Add all changes within the changeset (or patchset) in buffer pData +(size nData bytes) to the changegroup. +.Pp +If the buffer contains a patchset, then all prior calls to this function +on the same changegroup object must also have specified patchsets. +Or, if the buffer contains a changeset, so must have the earlier calls +to this function. +Otherwise, SQLITE_ERROR is returned and no changes are added to the +changegroup. +.Pp +Rows within the changeset and changegroup are identified by the values +in their PRIMARY KEY columns. +A change in the changeset is considered to apply to the same row as +a change already present in the changegroup if the two rows have the +same primary key. +.Pp +Changes to rows that do not already appear in the changegroup are simply +copied into it. +Or, if both the new changeset and the changegroup contain changes that +apply to a single row, the final contents of the changegroup depends +on the type of each change, as follows: +.Pp + Existing Change New Change Output Change + INSERT INSERT The new change is ignored. +This case does not occur if the new changeset was recorded immediately +after the changesets already added to the changegroup. + INSERT UPDATE The INSERT change remains in the changegroup. +The values in the INSERT change are modified as if the row was inserted +by the existing change and then updated according to the new change. + INSERT DELETE The existing INSERT is removed from the changegroup. +The DELETE is not added. + UPDATE INSERT The new change is ignored. +This case does not occur if the new changeset was recorded immediately +after the changesets already added to the changegroup. + UPDATE UPDATE The existing UPDATE remains within the changegroup. +It is amended so that the accompanying values are as if the row was +updated once by the existing change and then again by the new change. + UPDATE DELETE The existing UPDATE is replaced by the new DELETE within +the changegroup. + DELETE INSERT If one or more of the column values in the row inserted +by the new change differ from those in the row deleted by the existing +change, the existing DELETE is replaced by an UPDATE within the changegroup. +Otherwise, if the inserted row is exactly the same as the deleted row, +the existing DELETE is simply discarded. + DELETE UPDATE The new change is ignored. +This case does not occur if the new changeset was recorded immediately +after the changesets already added to the changegroup. + DELETE DELETE The new change is ignored. +This case does not occur if the new changeset was recorded immediately +after the changesets already added to the changegroup. +.Pp +If the new changeset contains changes to a table that is already present +in the changegroup, then the number of columns and the position of +the primary key columns for the table must be consistent. +If this is not the case, this function fails with SQLITE_SCHEMA. +Except, if the changegroup object has been configured with a database +schema using the sqlite3changegroup_schema() API, then it is possible +to combine changesets with different numbers of columns for a single +table, provided that they are otherwise compatible. +.Pp +If the input changeset appears to be corrupt and the corruption is +detected, SQLITE_CORRUPT is returned. +Or, if an out-of-memory condition occurs during processing, this function +returns SQLITE_NOMEM. +.Pp +In all cases, if an error occurs the state of the final contents of +the changegroup is undefined. +If no error occurs, SQLITE_OK is returned. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11900. +.Bd -literal +SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData); +.Ed diff --git a/static/netbsd/man3/sqlite3changegroup_delete.3 b/static/netbsd/man3/sqlite3changegroup_delete.3 new file mode 100644 index 00000000..6473730a --- /dev/null +++ b/static/netbsd/man3/sqlite3changegroup_delete.3 @@ -0,0 +1,19 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGEGROUP_DELETE 3 +.Os +.Sh NAME +.Nm sqlite3changegroup_delete +.Nd delete a changegroup object +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3changegroup_delete +.Fa "sqlite3_changegroup*" +.Fc +.Sh DESCRIPTION +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12014. +.Bd -literal +SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*); +.Ed diff --git a/static/netbsd/man3/sqlite3changegroup_new.3 b/static/netbsd/man3/sqlite3changegroup_new.3 new file mode 100644 index 00000000..94754246 --- /dev/null +++ b/static/netbsd/man3/sqlite3changegroup_new.3 @@ -0,0 +1,52 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGEGROUP_NEW 3 +.Os +.Sh NAME +.Nm sqlite3changegroup_new +.Nd create a new changegroup object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changegroup_new +.Fa "sqlite3_changegroup **pp" +.Fc +.Sh DESCRIPTION +An sqlite3_changegroup object is used to combine two or more changesets +(or patchsets) into a single changeset (or patchset). +A single changegroup object may combine changesets or patchsets, but +not both. +The output is always in the same format as the input. +.Pp +If successful, this function returns SQLITE_OK and populates (*pp) +with a pointer to a new sqlite3_changegroup object before returning. +The caller should eventually free the returned object using a call +to sqlite3changegroup_delete(). +If an error occurs, an SQLite error code (i.e. SQLITE_NOMEM) is returned +and *pp is set to NULL. +.Pp +The usual usage pattern for an sqlite3_changegroup object is as follows: +.Bl -bullet +.It +It is created using a call to sqlite3changegroup_new(). +.It +Zero or more changesets (or patchsets) are added to the object by calling +sqlite3changegroup_add(). +.It +The result of combining all input changesets together is obtained by +the application via a call to sqlite3changegroup_output(). +.It +The object is deleted using a call to sqlite3changegroup_delete(). +.El +.Pp +Any number of calls to add() and output() may be made between the calls +to new() and delete(), and in any order. +.Pp +As well as the regular sqlite3changegroup_add() and sqlite3changegroup_output() +functions, also available are the streaming versions sqlite3changegroup_add_strm() +and sqlite3changegroup_output_strm(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11830. +.Bd -literal +SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp); +.Ed diff --git a/static/netbsd/man3/sqlite3changegroup_output.3 b/static/netbsd/man3/sqlite3changegroup_output.3 new file mode 100644 index 00000000..98f0627c --- /dev/null +++ b/static/netbsd/man3/sqlite3changegroup_output.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGEGROUP_OUTPUT 3 +.Os +.Sh NAME +.Nm sqlite3changegroup_output +.Nd obtain a composite changeset from a changegroup +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changegroup_output +.Fa "sqlite3_changegroup*" +.Fa "int *pnData" +.Fa "void **ppData" +.Fc +.Sh DESCRIPTION +Obtain a buffer containing a changeset (or patchset) representing the +current contents of the changegroup. +If the inputs to the changegroup were themselves changesets, the output +is a changeset. +Or, if the inputs were patchsets, the output is also a patchset. +.Pp +As with the output of the sqlite3session_changeset() and sqlite3session_patchset() +functions, all changes related to a single table are grouped together +in the output of this function. +Tables appear in the same order as for the very first changeset added +to the changegroup. +If the second or subsequent changesets added to the changegroup contain +changes for tables that do not appear in the first changeset, they +are appended onto the end of the output changeset, again in the order +in which they are first encountered. +.Pp +If an error occurs, an SQLite error code is returned and the output +variables (*pnData) and (*ppData) are set to 0. +Otherwise, SQLITE_OK is returned and the output variables are set to +the size of and a pointer to the output buffer, respectively. +In this case it is the responsibility of the caller to eventually free +the buffer using a call to sqlite3_free(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11983. +.Bd -literal +SQLITE_API int sqlite3changegroup_output( + sqlite3_changegroup*, + int *pnData, /* OUT: Size of output buffer in bytes */ + void **ppData /* OUT: Pointer to output buffer */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3changegroup_schema.3 b/static/netbsd/man3/sqlite3changegroup_schema.3 new file mode 100644 index 00000000..9753db0a --- /dev/null +++ b/static/netbsd/man3/sqlite3changegroup_schema.3 @@ -0,0 +1,49 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGEGROUP_SCHEMA 3 +.Os +.Sh NAME +.Nm sqlite3changegroup_schema +.Nd add a schema to a changegroup +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changegroup_schema +.Fa "sqlite3_changegroup*" +.Fa "sqlite3*" +.Fa "const char *zDb" +.Fc +.Sh DESCRIPTION +This method may be used to optionally enforce the rule that the changesets +added to the changegroup handle must match the schema of database zDb +("main", "temp", or the name of an attached database). +If sqlite3changegroup_add() is called to add a changeset that is not +compatible with the configured schema, SQLITE_SCHEMA is returned and +the changegroup object is left in an undefined state. +.Pp +A changeset schema is considered compatible with the database schema +in the same way as for sqlite3changeset_apply(). +Specifically, for each table in the changeset, there exists a database +table with: +.Bl -bullet +.It +The name identified by the changeset, and +.It +at least as many columns as recorded in the changeset, and +.It +the primary key columns in the same position as recorded in the changeset. +.El +.Pp +The output of the changegroup object always has the same schema as +the database nominated using this function. +In cases where changesets passed to sqlite3changegroup_add() have fewer +columns than the corresponding table in the database schema, these +are filled in using the default column values from the database schema. +This makes it possible to combined changesets that have different numbers +of columns for a single table within a changegroup, provided that they +are otherwise compatible. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11868. +.Bd -literal +SQLITE_API int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb); +.Ed diff --git a/static/netbsd/man3/sqlite3changeset_apply.3 b/static/netbsd/man3/sqlite3changeset_apply.3 new file mode 100644 index 00000000..623ffa16 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_apply.3 @@ -0,0 +1,233 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_APPLY 3 +.Os +.Sh NAME +.Nm sqlite3changeset_apply , +.Nm sqlite3changeset_apply_v2 +.Nd apply a changeset to a database +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_apply +.Fa "sqlite3 *db" +.Fa "int nChangeset" +.Fa "void *pChangeset" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fc +.Ft int +.Fo sqlite3changeset_apply_v2 +.Fa "sqlite3 *db" +.Fa "int nChangeset" +.Fa "void *pChangeset" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fa "void **ppRebase" +.Fa "int *pnRebase" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +Apply a changeset or patchset to a database. +These functions attempt to update the "main" database attached to handle +db with the changes found in the changeset passed via the second and +third arguments. +.Pp +The fourth argument (xFilter) passed to these functions is the "filter +callback". +If it is not NULL, then for each table affected by at least one change +in the changeset, the filter callback is invoked with the table name +as the second argument, and a copy of the context pointer passed as +the sixth argument as the first. +If the "filter callback" returns zero, then no attempt is made to apply +any changes to the table. +Otherwise, if the return value is non-zero or the xFilter argument +to is NULL, all changes related to the table are attempted. +.Pp +For each table that is not excluded by the filter callback, this function +tests that the target database contains a compatible table. +A table is considered compatible if all of the following are true: +.Bl -bullet +.It +The table has the same name as the name recorded in the changeset, +and +.It +The table has at least as many columns as recorded in the changeset, +and +.It +The table has primary key columns in the same position as recorded +in the changeset. +.El +.Pp +If there is no compatible table, it is not an error, but none of the +changes associated with the table are applied. +A warning message is issued via the sqlite3_log() mechanism with the +error code SQLITE_SCHEMA. +At most one such warning is issued for each table in the changeset. +.Pp +For each change for which there is a compatible table, an attempt is +made to modify the table contents according to the UPDATE, INSERT or +DELETE change. +If a change cannot be applied cleanly, the conflict handler function +passed as the fifth argument to sqlite3changeset_apply() may be invoked. +A description of exactly when the conflict handler is invoked for each +type of change is below. +.Pp +Unlike the xFilter argument, xConflict may not be passed NULL. +The results of passing anything other than a valid function pointer +as the xConflict argument are undefined. +.Pp +Each time the conflict handler function is invoked, it must return +one of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_ABORT +or SQLITE_CHANGESET_REPLACE. +SQLITE_CHANGESET_REPLACE may only be returned if the second argument +passed to the conflict handler is either SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. +If the conflict-handler returns an illegal value, any changes already +made are rolled back and the call to sqlite3changeset_apply() returns +SQLITE_MISUSE. +Different actions are taken by sqlite3changeset_apply() depending on +the value returned by each invocation of the conflict-handler function. +Refer to the documentation for the three available return values +for details. +.Bl -tag -width Ds +.It DELETE Changes +For each DELETE change, the function checks if the target database +contains a row with the same primary key value (or values) as the original +row values stored in the changeset. +If it does, and the values stored in all non-primary key columns also +match the values stored in the changeset the row is deleted from the +target database. +.Pp +If a row with matching primary key values is found, but one or more +of the non-primary key fields contains a value different from the original +row value stored in the changeset, the conflict-handler function is +invoked with SQLITE_CHANGESET_DATA as the second +argument. +If the database table has more columns than are recorded in the changeset, +only the values of those non-primary key fields are compared against +the current database contents - any trailing database table columns +are ignored. +.Pp +If no row with matching primary key values is found in the database, +the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND +passed as the second argument. +.Pp +If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT +(which can only happen if a foreign key constraint is violated), the +conflict-handler function is invoked with SQLITE_CHANGESET_CONSTRAINT +passed as the second argument. +This includes the case where the DELETE operation is attempted because +an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. +.It INSERT Changes +For each INSERT change, an attempt is made to insert the new row into +the database. +If the changeset row contains fewer fields than the database table, +the trailing fields are populated with their default values. +.Pp +If the attempt to insert the row fails because the database already +contains a row with the same primary key values, the conflict handler +function is invoked with the second argument set to SQLITE_CHANGESET_CONFLICT. +.Pp +If the attempt to insert the row fails because of some other constraint +violation (e.g. NOT NULL or UNIQUE), the conflict handler function +is invoked with the second argument set to SQLITE_CHANGESET_CONSTRAINT. +This includes the case where the INSERT operation is re-attempted because +an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. +.It UPDATE Changes +For each UPDATE change, the function checks if the target database +contains a row with the same primary key value (or values) as the original +row values stored in the changeset. +If it does, and the values stored in all modified non-primary key columns +also match the values stored in the changeset the row is updated within +the target database. +.Pp +If a row with matching primary key values is found, but one or more +of the modified non-primary key fields contains a value different from +an original row value stored in the changeset, the conflict-handler +function is invoked with SQLITE_CHANGESET_DATA +as the second argument. +Since UPDATE changes only contain values for non-primary key fields +that are to be modified, only those fields need to match the original +values to avoid the SQLITE_CHANGESET_DATA conflict-handler callback. +.Pp +If no row with matching primary key values is found in the database, +the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND +passed as the second argument. +.Pp +If the UPDATE operation is attempted, but SQLite returns SQLITE_CONSTRAINT, +the conflict-handler function is invoked with SQLITE_CHANGESET_CONSTRAINT +passed as the second argument. +This includes the case where the UPDATE operation is attempted after +an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. +.El +.Pp +It is safe to execute SQL statements, including those that write to +the table that the callback related to, from within the xConflict callback. +This can be used to further customize the application's conflict resolution +strategy. +.Pp +All changes made by these functions are enclosed in a savepoint transaction. +If any other error (aside from a constraint failure when attempting +to write to the target database) occurs, then the savepoint transaction +is rolled back, restoring the target database to its original state, +and an SQLite error code returned. +.Pp +If the output parameters (ppRebase) and (pnRebase) are non-NULL and +the input is a changeset (not a patchset), then sqlite3changeset_apply_v2() +may set (*ppRebase) to point to a "rebase" that may be used with the +sqlite3_rebaser APIs buffer before returning. +In this case (*pnRebase) is set to the size of the buffer in bytes. +It is the responsibility of the caller to eventually free any such +buffer using sqlite3_free(). +The buffer is only allocated and populated if one or more conflicts +were encountered while applying the patchset. +See comments surrounding the sqlite3_rebaser APIs for further details. +.Pp +The behavior of sqlite3changeset_apply_v2() and its streaming equivalent +may be modified by passing a combination of supported flags +as the 9th parameter. +.Pp +Note that the sqlite3changeset_apply_v2() API is still \fBexperimental\fP +and therefore subject to change. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12020. +.Bd -literal +SQLITE_API int sqlite3changeset_apply( + sqlite3 *db, /* Apply change to "main" db of this handle */ + int nChangeset, /* Size of changeset in bytes */ + void *pChangeset, /* Changeset blob */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx /* First argument passed to xConflict */ +); +SQLITE_API int sqlite3changeset_apply_v2( + sqlite3 *db, /* Apply change to "main" db of this handle */ + int nChangeset, /* Size of changeset in bytes */ + void *pChangeset, /* Changeset blob */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx, /* First argument passed to xConflict */ + void **ppRebase, int *pnRebase, /* OUT: Rebase data */ + int flags /* SESSION_CHANGESETAPPLY_* flags */ +); +.Ed +.Sh SEE ALSO +.Xr SQLITE_CHANGESET_DATA 3 , +.Xr SQLITE_CHANGESET_OMIT 3 , +.Xr SQLITE_CHANGESETAPPLY_NOSAVEPOINT 3 diff --git a/static/netbsd/man3/sqlite3changeset_apply_strm.3 b/static/netbsd/man3/sqlite3changeset_apply_strm.3 new file mode 100644 index 00000000..919858c9 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_apply_strm.3 @@ -0,0 +1,281 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_APPLY_STRM 3 +.Os +.Sh NAME +.Nm sqlite3changeset_apply_strm , +.Nm sqlite3changeset_apply_v2_strm , +.Nm sqlite3changeset_concat_strm , +.Nm sqlite3changeset_invert_strm , +.Nm sqlite3changeset_start_strm , +.Nm sqlite3changeset_start_v2_strm , +.Nm sqlite3session_changeset_strm , +.Nm sqlite3session_patchset_strm , +.Nm sqlite3changegroup_add_strm , +.Nm sqlite3changegroup_output_strm , +.Nm sqlite3rebaser_rebase_strm +.Nd streaming versions of API functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_apply_strm +.Fa "sqlite3 *db" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fc +.Ft int +.Fo sqlite3changeset_apply_v2_strm +.Fa "sqlite3 *db" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fa "void **ppRebase" +.Fa "int *pnRebase" +.Fa "int flags" +.Fc +.Ft int +.Fo sqlite3changeset_concat_strm +.Fa "int (*xInputA)(void *pIn, void *pData, int *pnData)" +.Fa "void *pInA" +.Fa "int (*xInputB)(void *pIn, void *pData, int *pnData)" +.Fa "void *pInB" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changeset_invert_strm +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changeset_start_strm +.Fa "sqlite3_changeset_iter **pp" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fc +.Ft int +.Fo sqlite3changeset_start_v2_strm +.Fa "sqlite3_changeset_iter **pp" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int flags" +.Fc +.Ft int +.Fo sqlite3session_changeset_strm +.Fa "sqlite3_session *pSession" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3session_patchset_strm +.Fa "sqlite3_session *pSession" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changegroup_add_strm +.Fa "sqlite3_changegroup*" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fc +.Ft int +.Fo sqlite3changegroup_output_strm +.Fa "sqlite3_changegroup*" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3rebaser_rebase_strm +.Fa "sqlite3_rebaser *pRebaser" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Sh DESCRIPTION +The six streaming API xxx_strm() functions serve similar purposes to +the corresponding non-streaming API functions: +.Pp + Streaming function Non-streaming equivalent + sqlite3changeset_apply_strm sqlite3changeset_apply + sqlite3changeset_apply_strm_v2 sqlite3changeset_apply_v2 + sqlite3changeset_concat_strm sqlite3changeset_concat + sqlite3changeset_invert_strm sqlite3changeset_invert + sqlite3changeset_start_strm sqlite3changeset_start + sqlite3session_changeset_strm sqlite3session_changeset + sqlite3session_patchset_strm sqlite3session_patchset +.Pp +Non-streaming functions that accept changesets (or patchsets) as input +require that the entire changeset be stored in a single buffer in memory. +Similarly, those that return a changeset or patchset do so by returning +a pointer to a single large buffer allocated using sqlite3_malloc(). +Normally this is convenient. +However, if an application running in a low-memory environment is required +to handle very large changesets, the large contiguous memory allocations +required can become onerous. +.Pp +In order to avoid this problem, instead of a single large buffer, input +is passed to a streaming API functions by way of a callback function +that the sessions module invokes to incrementally request input data +as it is required. +In all cases, a pair of API function parameters such as +.Bd -literal + int nChangeset, void *pChangeset, +.Ed +.Pp +Is replaced by: +.Bd -literal + int (*xInput)(void *pIn, void *pData, int *pnData), void +*pIn, +.Ed +.Pp +Each time the xInput callback is invoked by the sessions module, the +first argument passed is a copy of the supplied pIn context pointer. +The second argument, pData, points to a buffer (*pnData) bytes in size. +Assuming no error occurs the xInput method should copy up to (*pnData) +bytes of data into the buffer and set (*pnData) to the actual number +of bytes copied before returning SQLITE_OK. +If the input is completely exhausted, (*pnData) should be set to zero +to indicate this. +Or, if an error occurs, an SQLite error code should be returned. +In all cases, if an xInput callback returns an error, all processing +is abandoned and the streaming API function returns a copy of the error +code to the caller. +.Pp +In the case of sqlite3changeset_start_strm(), the xInput callback may +be invoked by the sessions module at any point during the lifetime +of the iterator. +If such an xInput callback returns an error, the iterator enters an +error state, whereby all subsequent calls to iterator functions immediately +fail with the same error code as returned by xInput. +.Pp +Similarly, streaming API functions that return changesets (or patchsets) +return them in chunks by way of a callback function instead of via +a pointer to a single large buffer. +In this case, a pair of parameters such as: +.Bd -literal + int *pnChangeset, void **ppChangeset, +.Ed +.Pp +Is replaced by: +.Bd -literal + int (*xOutput)(void *pOut, const void *pData, int nData), +void *pOut +.Ed +.Pp +The xOutput callback is invoked zero or more times to return data to +the application. +The first parameter passed to each call is a copy of the pOut pointer +supplied by the application. +The second parameter, pData, points to a buffer nData bytes in size +containing the chunk of output data being returned. +If the xOutput callback successfully processes the supplied data, it +should return SQLITE_OK to indicate success. +Otherwise, it should return some other SQLite error code. +In this case processing is immediately abandoned and the streaming +API function returns a copy of the xOutput error code to the application. +.Pp +The sessions module never invokes an xOutput callback with the third +parameter set to a value less than or equal to zero. +Other than this, no guarantees are made as to the size of the chunks +of data returned. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12507. +.Bd -literal +SQLITE_API int sqlite3changeset_apply_strm( + sqlite3 *db, /* Apply change to "main" db of this handle */ + int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ + void *pIn, /* First arg for xInput */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx /* First argument passed to xConflict */ +); +SQLITE_API int sqlite3changeset_apply_v2_strm( + sqlite3 *db, /* Apply change to "main" db of this handle */ + int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ + void *pIn, /* First arg for xInput */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx, /* First argument passed to xConflict */ + void **ppRebase, int *pnRebase, + int flags +); +SQLITE_API int sqlite3changeset_concat_strm( + int (*xInputA)(void *pIn, void *pData, int *pnData), + void *pInA, + int (*xInputB)(void *pIn, void *pData, int *pnData), + void *pInB, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3changeset_invert_strm( + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3changeset_start_strm( + sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlite3changeset_start_v2_strm( + sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int flags +); +SQLITE_API int sqlite3session_changeset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3session_patchset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3rebaser_rebase_strm( + sqlite3_rebaser *pRebaser, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_concat 3 , +.Xr sqlite3changeset_invert 3 , +.Xr sqlite3changeset_start 3 , +.Xr sqlite3session_changeset 3 , +.Xr sqlite3session_patchset 3 diff --git a/static/netbsd/man3/sqlite3changeset_concat.3 b/static/netbsd/man3/sqlite3changeset_concat.3 new file mode 100644 index 00000000..34aeab07 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_concat.3 @@ -0,0 +1,48 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_CONCAT 3 +.Os +.Sh NAME +.Nm sqlite3changeset_concat +.Nd concatenate two changeset objects +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_concat +.Fa "int nA" +.Fa "void *pA" +.Fa "int nB" +.Fa "void *pB" +.Fa "int *pnOut" +.Fa "void **ppOut" +.Fc +.Sh DESCRIPTION +This function is used to concatenate two changesets, A and B, into +a single changeset. +The result is a changeset equivalent to applying changeset A followed +by changeset B. +.Pp +This function combines the two input changesets using an sqlite3_changegroup +object. +Calling it produces similar results as the following code fragment: +.Bd -literal +sqlite3_changegroup *pGrp; rc = sqlite3_changegroup_new(&pGrp); if( +rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA); if( rc==SQLITE_OK +) rc = sqlite3changegroup_add(pGrp, nB, pB); if( rc==SQLITE_OK ){ rc += sqlite3changegroup_output(pGrp, pnOut, ppOut); }else{ *ppOut = 0; +*pnOut = 0; } +.Ed +.Pp +Refer to the sqlite3_changegroup documentation below for details. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11774. +.Bd -literal +SQLITE_API int sqlite3changeset_concat( + int nA, /* Number of bytes in buffer pA */ + void *pA, /* Pointer to buffer containing changeset A */ + int nB, /* Number of bytes in buffer pB */ + void *pB, /* Pointer to buffer containing changeset B */ + int *pnOut, /* OUT: Number of bytes in output changeset */ + void **ppOut /* OUT: Buffer containing output changeset */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3changeset_conflict.3 b/static/netbsd/man3/sqlite3changeset_conflict.3 new file mode 100644 index 00000000..897c5e80 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_conflict.3 @@ -0,0 +1,48 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_CONFLICT 3 +.Os +.Sh NAME +.Nm sqlite3changeset_conflict +.Nd obtain conflicting row values from a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_conflict +.Fa "sqlite3_changeset_iter *pIter" +.Fa "int iVal" +.Fa "sqlite3_value **ppValue" +.Fc +.Sh DESCRIPTION +This function should only be used with iterator objects passed to a +conflict-handler callback by +.Fn sqlite3changeset_apply +with either SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. +If this function is called on any other iterator, SQLITE_MISUSE +is returned and *ppValue is set to NULL. +.Pp +Argument iVal must be greater than or equal to 0, and less than the +number of columns in the table affected by the current change. +Otherwise, SQLITE_RANGE is returned and *ppValue is set +to NULL. +.Pp +If successful, this function sets *ppValue to point to a protected +sqlite3_value object containing the iVal'th value from the "conflicting +row" associated with the current conflict-handler callback and returns +SQLITE_OK. +.Pp +If some other error occurs (e.g. an OOM condition), an SQLite error +code is returned and *ppValue is set to NULL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11664. +.Bd -literal +SQLITE_API int sqlite3changeset_conflict( + sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlite3_value **ppValue /* OUT: Value from conflicting row */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr SQLITE_CHANGESET_DATA 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changeset_finalize.3 b/static/netbsd/man3/sqlite3changeset_finalize.3 new file mode 100644 index 00000000..b11d45c5 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_finalize.3 @@ -0,0 +1,52 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_FINALIZE 3 +.Os +.Sh NAME +.Nm sqlite3changeset_finalize +.Nd finalize a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_finalize +.Fa "sqlite3_changeset_iter *pIter" +.Fc +.Sh DESCRIPTION +This function is used to finalize an iterator allocated with +.Fn sqlite3changeset_start . +This function should only be called on iterators created using the +.Fn sqlite3changeset_start +function. +If an application calls this function with an iterator passed to a +conflict-handler by +.Fn sqlite3changeset_apply , +SQLITE_MISUSE is immediately returned and the call has +no effect. +.Pp +If an error was encountered within a call to an sqlite3changeset_xxx() +function (for example an SQLITE_CORRUPT in +.Fn sqlite3changeset_next +or an SQLITE_NOMEM in +.Fn sqlite3changeset_new ) +then an error code corresponding to that error is returned by this +function. +Otherwise, SQLITE_OK is returned. +This is to allow the following pattern (pseudo-code): +.Bd -literal +sqlite3changeset_start(); while( SQLITE_ROW==sqlite3changeset_next() +){ // Do something with change. +} rc = sqlite3changeset_finalize(); if( rc!=SQLITE_OK ){ // An error +has occurred } +.Ed +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11709. +.Bd -literal +SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_new 3 , +.Xr sqlite3changeset_next 3 , +.Xr sqlite3changeset_start 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changeset_fk_conflicts.3 b/static/netbsd/man3/sqlite3changeset_fk_conflicts.3 new file mode 100644 index 00000000..5fc50cda --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_fk_conflicts.3 @@ -0,0 +1,29 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_FK_CONFLICTS 3 +.Os +.Sh NAME +.Nm sqlite3changeset_fk_conflicts +.Nd determine the number of foreign key constraint violations +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_fk_conflicts +.Fa "sqlite3_changeset_iter *pIter" +.Fa "int *pnOut" +.Fc +.Sh DESCRIPTION +This function may only be called with an iterator passed to an SQLITE_CHANGESET_FOREIGN_KEY +conflict handler callback. +In this case it sets the output variable to the total number of known +foreign key violations in the destination database and returns SQLITE_OK. +.Pp +In all other cases this function returns SQLITE_MISUSE. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11692. +.Bd -literal +SQLITE_API int sqlite3changeset_fk_conflicts( + sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int *pnOut /* OUT: Number of FK violations */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3changeset_invert.3 b/static/netbsd/man3/sqlite3changeset_invert.3 new file mode 100644 index 00000000..98ff8327 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_invert.3 @@ -0,0 +1,55 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_INVERT 3 +.Os +.Sh NAME +.Nm sqlite3changeset_invert +.Nd invert a changeset +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_invert +.Fa "int nIn" +.Fa "const void *pIn" +.Fa "int *pnOut" +.Fa "void **ppOut" +.Fc +.Sh DESCRIPTION +This function is used to "invert" a changeset object. +Applying an inverted changeset to a database reverses the effects of +applying the uninverted changeset. +Specifically: +.Bl -bullet +.It +Each DELETE change is changed to an INSERT, and +.It +Each INSERT change is changed to a DELETE, and +.It +For each UPDATE change, the old.* and new.* values are exchanged. +.El +.Pp +This function does not change the order in which changes appear within +the changeset. +It merely reverses the sense of each individual change. +.Pp +If successful, a pointer to a buffer containing the inverted changeset +is stored in *ppOut, the size of the same buffer is stored in *pnOut, +and SQLITE_OK is returned. +If an error occurs, both *pnOut and *ppOut are zeroed and an SQLite +error code returned. +.Pp +It is the responsibility of the caller to eventually call sqlite3_free() +on the *ppOut pointer to free the buffer allocation following a successful +call to this function. +.Pp +WARNING/TODO: This function currently assumes that the input is a valid +changeset. +If it is not, the results are undefined. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11741. +.Bd -literal +SQLITE_API int sqlite3changeset_invert( + int nIn, const void *pIn, /* Input changeset */ + int *pnOut, void **ppOut /* OUT: Inverse of input */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3changeset_new.3 b/static/netbsd/man3/sqlite3changeset_new.3 new file mode 100644 index 00000000..c2aa4524 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_new.3 @@ -0,0 +1,60 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_NEW 3 +.Os +.Sh NAME +.Nm sqlite3changeset_new +.Nd obtain new.* values from a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_new +.Fa "sqlite3_changeset_iter *pIter" +.Fa "int iVal" +.Fa "sqlite3_value **ppValue" +.Fc +.Sh DESCRIPTION +The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by +.Fn sqlite3changeset_apply , +or an iterator created by +.Fn sqlite3changeset_start . +In the latter case, the most recent call to +.Fn sqlite3changeset_next +must have returned SQLITE_ROW. +Furthermore, it may only be called if the type of change that the iterator +currently points to is either SQLITE_UPDATE or SQLITE_INSERT. +Otherwise, this function returns SQLITE_MISUSE and sets +*ppValue to NULL. +.Pp +Argument iVal must be greater than or equal to 0, and less than the +number of columns in the table affected by the current change. +Otherwise, SQLITE_RANGE is returned and *ppValue is set +to NULL. +.Pp +If successful, this function sets *ppValue to point to a protected +sqlite3_value object containing the iVal'th value from the vector of +new row values stored as part of the UPDATE or INSERT change and returns +SQLITE_OK. +If the change is an UPDATE and does not include a new value for the +requested column, *ppValue is set to NULL and SQLITE_OK returned. +The name of the function comes from the fact that this is similar to +the "new.*" columns available to update or delete triggers. +.Pp +If some other error occurs (e.g. an OOM condition), an SQLite error +code is returned and *ppValue is set to NULL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11630. +.Bd -literal +SQLITE_API int sqlite3changeset_new( + sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_next 3 , +.Xr sqlite3changeset_start 3 , +.Xr SQLITE_CREATE_INDEX 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changeset_next.3 b/static/netbsd/man3/sqlite3changeset_next.3 new file mode 100644 index 00000000..6ccec571 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_next.3 @@ -0,0 +1,43 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_NEXT 3 +.Os +.Sh NAME +.Nm sqlite3changeset_next +.Nd advance a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_next +.Fa "sqlite3_changeset_iter *pIter" +.Fc +.Sh DESCRIPTION +This function may only be used with iterators created by the function +.Fn sqlite3changeset_start . +If it is called on an iterator passed to a conflict-handler callback +by +.Fn sqlite3changeset_apply , +SQLITE_MISUSE is returned and the call has no effect. +.Pp +Immediately after an iterator is created by sqlite3changeset_start(), +it does not point to any change in the changeset. +Assuming the changeset is not empty, the first call to this function +advances the iterator to point to the first change in the changeset. +Each subsequent call advances the iterator to point to the next change +in the changeset (if any). +If no error occurs and the iterator points to a valid change after +a call to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned. +Otherwise, if all changes in the changeset have already been visited, +SQLITE_DONE is returned. +.Pp +If an error occurs, an SQLite error code is returned. +Possible error codes include SQLITE_CORRUPT (if the changeset buffer +is corrupt) or SQLITE_NOMEM. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11502. +.Bd -literal +SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_start 3 diff --git a/static/netbsd/man3/sqlite3changeset_old.3 b/static/netbsd/man3/sqlite3changeset_old.3 new file mode 100644 index 00000000..d02231ff --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_old.3 @@ -0,0 +1,58 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_OLD 3 +.Os +.Sh NAME +.Nm sqlite3changeset_old +.Nd obtain old.* values from a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_old +.Fa "sqlite3_changeset_iter *pIter" +.Fa "int iVal" +.Fa "sqlite3_value **ppValue" +.Fc +.Sh DESCRIPTION +The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by +.Fn sqlite3changeset_apply , +or an iterator created by +.Fn sqlite3changeset_start . +In the latter case, the most recent call to +.Fn sqlite3changeset_next +must have returned SQLITE_ROW. +Furthermore, it may only be called if the type of change that the iterator +currently points to is either SQLITE_DELETE or SQLITE_UPDATE. +Otherwise, this function returns SQLITE_MISUSE and sets +*ppValue to NULL. +.Pp +Argument iVal must be greater than or equal to 0, and less than the +number of columns in the table affected by the current change. +Otherwise, SQLITE_RANGE is returned and *ppValue is set +to NULL. +.Pp +If successful, this function sets *ppValue to point to a protected +sqlite3_value object containing the iVal'th value from the vector of +original row values stored as part of the UPDATE or DELETE change and +returns SQLITE_OK. +The name of the function comes from the fact that this is similar to +the "old.*" columns available to update or delete triggers. +.Pp +If some other error occurs (e.g. an OOM condition), an SQLite error +code is returned and *ppValue is set to NULL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11599. +.Bd -literal +SQLITE_API int sqlite3changeset_old( + sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_next 3 , +.Xr sqlite3changeset_start 3 , +.Xr SQLITE_CREATE_INDEX 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changeset_op.3 b/static/netbsd/man3/sqlite3changeset_op.3 new file mode 100644 index 00000000..3a6a2cb9 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_op.3 @@ -0,0 +1,70 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_OP 3 +.Os +.Sh NAME +.Nm sqlite3changeset_op +.Nd obtain the current operation from a changeset iterator +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_op +.Fa "sqlite3_changeset_iter *pIter" +.Fa "const char **pzTab" +.Fa "int *pnCol" +.Fa "int *pOp" +.Fa "int *pbIndirect" +.Fc +.Sh DESCRIPTION +The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by +.Fn sqlite3changeset_apply , +or an iterator created by +.Fn sqlite3changeset_start . +In the latter case, the most recent call to +.Fn sqlite3changeset_next +must have returned SQLITE_ROW. +If this is not the case, this function returns SQLITE_MISUSE. +.Pp +Arguments pOp, pnCol and pzTab may not be NULL. +Upon return, three outputs are set through these pointers: +.Pp +*pOp is set to one of SQLITE_INSERT, SQLITE_DELETE +or SQLITE_UPDATE, depending on the type of change that +the iterator currently points to; +.Pp +*pnCol is set to the number of columns in the table affected by the +change; and +.Pp +*pzTab is set to point to a nul-terminated utf-8 encoded string containing +the name of the table affected by the current change. +The buffer remains valid until either sqlite3changeset_next() is called +on the iterator or until the conflict-handler function returns. +.Pp +If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the +change is an indirect change, or false (0) otherwise. +See the documentation for +.Fn sqlite3session_indirect +for a description of direct and indirect changes. +.Pp +If no error occurs, SQLITE_OK is returned. +If an error does occur, an SQLite error code is returned. +The values of the output variables may not be trusted in this case. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11527. +.Bd -literal +SQLITE_API int sqlite3changeset_op( + sqlite3_changeset_iter *pIter, /* Iterator object */ + const char **pzTab, /* OUT: Pointer to table name */ + int *pnCol, /* OUT: Number of columns in table */ + int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */ + int *pbIndirect /* OUT: True for an 'indirect' change */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_next 3 , +.Xr sqlite3changeset_start 3 , +.Xr sqlite3session_indirect 3 , +.Xr SQLITE_CREATE_INDEX 3 , +.Xr SQLITE_OK 3 diff --git a/static/netbsd/man3/sqlite3changeset_pk.3 b/static/netbsd/man3/sqlite3changeset_pk.3 new file mode 100644 index 00000000..6d1c3849 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_pk.3 @@ -0,0 +1,48 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_PK 3 +.Os +.Sh NAME +.Nm sqlite3changeset_pk +.Nd obtain the primary key definition of a table +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_pk +.Fa "sqlite3_changeset_iter *pIter" +.Fa "unsigned char **pabPK" +.Fa "int *pnCol" +.Fc +.Sh DESCRIPTION +For each modified table, a changeset includes the following: +.Bl -bullet +.It +The number of columns in the table, and +.It +Which of those columns make up the tables PRIMARY KEY. +.El +.Pp +This function is used to find which columns comprise the PRIMARY KEY +of the table modified by the change that iterator pIter currently points +to. +If successful, *pabPK is set to point to an array of nCol entries, +where nCol is the number of columns in the table. +Elements of *pabPK are set to 0x01 if the corresponding column is part +of the tables primary key, or 0x00 if it is not. +.Pp +If argument pnCol is not NULL, then *pnCol is set to the number of +columns in the table. +.Pp +If this function is called when the iterator does not point to a valid +entry, SQLITE_MISUSE is returned and the output variables zeroed. +Otherwise, SQLITE_OK is returned and the output variables populated +as described above. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11567. +.Bd -literal +SQLITE_API int sqlite3changeset_pk( + sqlite3_changeset_iter *pIter, /* Iterator object */ + unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */ + int *pnCol /* OUT: Number of entries in output array */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3changeset_start.3 b/static/netbsd/man3/sqlite3changeset_start.3 new file mode 100644 index 00000000..f738b1bc --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_start.3 @@ -0,0 +1,94 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_START 3 +.Os +.Sh NAME +.Nm sqlite3changeset_start , +.Nm sqlite3changeset_start_v2 +.Nd create an iterator to traverse a changeset +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_start +.Fa "sqlite3_changeset_iter **pp" +.Fa "int nChangeset" +.Fa "void *pChangeset" +.Fc +.Ft int +.Fo sqlite3changeset_start_v2 +.Fa "sqlite3_changeset_iter **pp" +.Fa "int nChangeset" +.Fa "void *pChangeset" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +Create an iterator used to iterate through the contents of a changeset. +If successful, *pp is set to point to the iterator handle and SQLITE_OK +is returned. +Otherwise, if an error occurs, *pp is set to zero and an SQLite error +code is returned. +.Pp +The following functions can be used to advance and query a changeset +iterator created by this function: +.Bl -bullet +.It +.Fn sqlite3changeset_next +.It +.Fn sqlite3changeset_op +.It +.Fn sqlite3changeset_new +.It +.Fn sqlite3changeset_old +.El +.Pp +It is the responsibility of the caller to eventually destroy the iterator +by passing it to +.Fn sqlite3changeset_finalize . +The buffer containing the changeset (pChangeset) must remain valid +until after the iterator is destroyed. +.Pp +Assuming the changeset blob was created by one of the +.Fn sqlite3session_changeset , +.Fn sqlite3changeset_concat +or +.Fn sqlite3changeset_invert +functions, all changes within the changeset that apply to a single +table are grouped together. +This means that when an application iterates through a changeset using +an iterator created by this function, all changes that relate to a +single table are visited consecutively. +There is no chance that the iterator will visit a change the applies +to table X, then one for table Y, and then later on visit another change +for table X. +.Pp +The behavior of sqlite3changeset_start_v2() and its streaming equivalent +may be modified by passing a combination of supported flags +as the 4th parameter. +.Pp +Note that the sqlite3changeset_start_v2() API is still \fBexperimental\fP +and therefore subject to change. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11435. +.Bd -literal +SQLITE_API int sqlite3changeset_start( + sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ + int nChangeset, /* Size of changeset blob in bytes */ + void *pChangeset /* Pointer to blob containing changeset */ +); +SQLITE_API int sqlite3changeset_start_v2( + sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ + int nChangeset, /* Size of changeset blob in bytes */ + void *pChangeset, /* Pointer to blob containing changeset */ + int flags /* SESSION_CHANGESETSTART_* flags */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_concat 3 , +.Xr sqlite3changeset_finalize 3 , +.Xr sqlite3changeset_invert 3 , +.Xr sqlite3changeset_new 3 , +.Xr sqlite3changeset_next 3 , +.Xr sqlite3changeset_old 3 , +.Xr sqlite3changeset_op 3 , +.Xr sqlite3session_changeset 3 , +.Xr SQLITE_CHANGESETSTART_INVERT 3 diff --git a/static/netbsd/man3/sqlite3changeset_upgrade.3 b/static/netbsd/man3/sqlite3changeset_upgrade.3 new file mode 100644 index 00000000..3d0eb725 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_upgrade.3 @@ -0,0 +1,29 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_UPGRADE 3 +.Os +.Sh NAME +.Nm sqlite3changeset_upgrade +.Nd upgrade the schema of a changeset/Patchset +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_upgrade +.Fa "sqlite3 *db" +.Fa "const char *zDb" +.Fa "int nIn" +.Fa "const void *pIn" +.Fa "int *pnOut" +.Fa "void **ppOut" +.Fc +.Sh DESCRIPTION +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11810. +.Bd -literal +SQLITE_API int sqlite3changeset_upgrade( + sqlite3 *db, + const char *zDb, + int nIn, const void *pIn, /* Input changeset */ + int *pnOut, void **ppOut /* OUT: Inverse of input */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3rebaser_configure.3 b/static/netbsd/man3/sqlite3rebaser_configure.3 new file mode 100644 index 00000000..b7a62195 --- /dev/null +++ b/static/netbsd/man3/sqlite3rebaser_configure.3 @@ -0,0 +1,27 @@ +.Dd January 24, 2024 +.Dt SQLITE3REBASER_CONFIGURE 3 +.Os +.Sh NAME +.Nm sqlite3rebaser_configure +.Nd configure a changeset rebaser object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3rebaser_configure +.Fa "sqlite3_rebaser*" +.Fa "int nRebase" +.Fa "const void *pRebase" +.Fc +.Sh DESCRIPTION +Configure the changeset rebaser object to rebase changesets according +to the conflict resolutions described by buffer pRebase (size nRebase +bytes), which must have been obtained from a previous call to sqlite3changeset_apply_v2(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12463. +.Bd -literal +SQLITE_API int sqlite3rebaser_configure( + sqlite3_rebaser*, + int nRebase, const void *pRebase +); +.Ed diff --git a/static/netbsd/man3/sqlite3rebaser_create.3 b/static/netbsd/man3/sqlite3rebaser_create.3 new file mode 100644 index 00000000..6bcd6ca9 --- /dev/null +++ b/static/netbsd/man3/sqlite3rebaser_create.3 @@ -0,0 +1,23 @@ +.Dd January 24, 2024 +.Dt SQLITE3REBASER_CREATE 3 +.Os +.Sh NAME +.Nm sqlite3rebaser_create +.Nd create a changeset rebaser object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3rebaser_create +.Fa "sqlite3_rebaser **ppNew" +.Fc +.Sh DESCRIPTION +Allocate a new changeset rebaser object. +If successful, set (*ppNew) to point to the new object and return SQLITE_OK. +Otherwise, if an error occurs, return an SQLite error code (e.g. SQLITE_NOMEM) +and set (*ppNew) to NULL. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12452. +.Bd -literal +SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew); +.Ed diff --git a/static/netbsd/man3/sqlite3rebaser_delete.3 b/static/netbsd/man3/sqlite3rebaser_delete.3 new file mode 100644 index 00000000..2a112624 --- /dev/null +++ b/static/netbsd/man3/sqlite3rebaser_delete.3 @@ -0,0 +1,22 @@ +.Dd January 24, 2024 +.Dt SQLITE3REBASER_DELETE 3 +.Os +.Sh NAME +.Nm sqlite3rebaser_delete +.Nd delete a changeset rebaser object +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3rebaser_delete +.Fa "sqlite3_rebaser *p" +.Fc +.Sh DESCRIPTION +Delete the changeset rebaser object and all associated resources. +There should be one call to this function for each successful invocation +of sqlite3rebaser_create(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12497. +.Bd -literal +SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p); +.Ed diff --git a/static/netbsd/man3/sqlite3rebaser_rebase.3 b/static/netbsd/man3/sqlite3rebaser_rebase.3 new file mode 100644 index 00000000..0eca152f --- /dev/null +++ b/static/netbsd/man3/sqlite3rebaser_rebase.3 @@ -0,0 +1,39 @@ +.Dd January 24, 2024 +.Dt SQLITE3REBASER_REBASE 3 +.Os +.Sh NAME +.Nm sqlite3rebaser_rebase +.Nd rebase a changeset +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3rebaser_rebase +.Fa "sqlite3_rebaser*" +.Fa "int nIn" +.Fa "const void *pIn" +.Fa "int *pnOut" +.Fa "void **ppOut" +.Fc +.Sh DESCRIPTION +Argument pIn must point to a buffer containing a changeset nIn bytes +in size. +This function allocates and populates a buffer with a copy of the changeset +rebased according to the configuration of the rebaser object passed +as the first argument. +If successful, (*ppOut) is set to point to the new buffer containing +the rebased changeset and (*pnOut) to its size in bytes and SQLITE_OK +returned. +It is the responsibility of the caller to eventually free the new buffer +using sqlite3_free(). +Otherwise, if an error occurs, (*ppOut) and (*pnOut) are set to zero +and an SQLite error code returned. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12477. +.Bd -literal +SQLITE_API int sqlite3rebaser_rebase( + sqlite3_rebaser*, + int nIn, const void *pIn, + int *pnOut, void **ppOut +); +.Ed diff --git a/static/netbsd/man3/sqlite3session_attach.3 b/static/netbsd/man3/sqlite3session_attach.3 new file mode 100644 index 00000000..99b73e7e --- /dev/null +++ b/static/netbsd/man3/sqlite3session_attach.3 @@ -0,0 +1,86 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_ATTACH 3 +.Os +.Sh NAME +.Nm sqlite3session_attach +.Nd attach a table to a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_attach +.Fa "sqlite3_session *pSession" +.Fa "const char *zTab" +.Fc +.Sh DESCRIPTION +If argument zTab is not NULL, then it is the name of a table to attach +to the session object passed as the first argument. +All subsequent changes made to the table while the session object is +enabled will be recorded. +See documentation for +.Fn sqlite3session_changeset +for further details. +.Pp +Or, if argument zTab is NULL, then changes are recorded for all tables +in the database. +If additional tables are added to the database (by executing "CREATE +TABLE" statements) after this call is made, changes for the new tables +are also recorded. +.Pp +Changes can only be recorded for tables that have a PRIMARY KEY explicitly +defined as part of their CREATE TABLE statement. +It does not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid +alias) or not. +The PRIMARY KEY may consist of a single column, or may be a composite +key. +.Pp +It is not an error if the named table does not exist in the database. +Nor is it an error if the named table does not have a PRIMARY KEY. +However, no changes will be recorded in either of these scenarios. +.Pp +Changes are not recorded for individual rows that have NULL values +stored in one or more of their PRIMARY KEY columns. +.Pp +SQLITE_OK is returned if the call completes without error. +Or, if an error occurs, an SQLite error code (e.g. SQLITE_NOMEM) is +returned. +.Ss Special sqlite_stat1 Handling +As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception +to some of the rules above. +In SQLite, the schema of sqlite_stat1 is: +.Bd -literal + CREATE TABLE sqlite_stat1(tbl,idx,stat) +.Ed +.Pp +Even though sqlite_stat1 does not have a PRIMARY KEY, changes are recorded +for it as if the PRIMARY KEY is (tbl,idx). +Additionally, changes are recorded for rows for which (idx IS NULL) +is true. +However, for such rows a zero-length blob (SQL value X'') is stored +in the changeset or patchset instead of a NULL value. +This allows such changesets to be manipulated by legacy implementations +of sqlite3changeset_invert(), concat() and similar. +.Pp +The sqlite3changeset_apply() function automatically converts the zero-length +blob back to a NULL value when updating the sqlite_stat1 table. +However, if the application calls sqlite3changeset_new(), sqlite3changeset_old() +or sqlite3changeset_conflict on a changeset iterator directly (including +on a changeset iterator passed to a conflict-handler callback) then +the X'' value is returned. +The application must translate X'' to NULL itself if required. +.Pp +Legacy (older than 3.22.0) versions of the sessions module cannot capture +changes made to the sqlite_stat1 table. +Legacy versions of the sqlite3changeset_apply() function silently ignore +any modifications to the sqlite_stat1 table that are part of a changeset +or patchset. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11101. +.Bd -literal +SQLITE_API int sqlite3session_attach( + sqlite3_session *pSession, /* Session object */ + const char *zTab /* Table name */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_changeset 3 diff --git a/static/netbsd/man3/sqlite3session_changeset.3 b/static/netbsd/man3/sqlite3session_changeset.3 new file mode 100644 index 00000000..bc2138d7 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_changeset.3 @@ -0,0 +1,149 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_CHANGESET 3 +.Os +.Sh NAME +.Nm sqlite3session_changeset +.Nd generate a changeset from a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_changeset +.Fa "sqlite3_session *pSession" +.Fa "int *pnChangeset" +.Fa "void **ppChangeset" +.Fc +.Sh DESCRIPTION +Obtain a changeset containing changes to the tables attached to the +session object passed as the first argument. +If successful, set *ppChangeset to point to a buffer containing the +changeset and *pnChangeset to the size of the changeset in bytes before +returning SQLITE_OK. +If an error occurs, set both *ppChangeset and *pnChangeset to zero +and return an SQLite error code. +.Pp +A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes, +each representing a change to a single row of an attached table. +An INSERT change contains the values of each field of a new database +row. +A DELETE contains the original values of each field of a deleted database +row. +An UPDATE change contains the original values of each field of an updated +database row along with the updated values for each updated non-primary-key +column. +It is not possible for an UPDATE change to represent a change that +modifies the values of primary key columns. +If such a change is made, it is represented in a changeset as a DELETE +followed by an INSERT. +.Pp +Changes are not recorded for rows that have NULL values stored in one +or more of their PRIMARY KEY columns. +If such a row is inserted or deleted, no corresponding change is present +in the changesets returned by this function. +If an existing row with one or more NULL values stored in PRIMARY KEY +columns is updated so that all PRIMARY KEY columns are non-NULL, only +an INSERT is appears in the changeset. +Similarly, if an existing row with non-NULL PRIMARY KEY values is updated +so that one or more of its PRIMARY KEY columns are set to NULL, the +resulting changeset contains a DELETE change only. +.Pp +The contents of a changeset may be traversed using an iterator created +using the +.Fn sqlite3changeset_start +API. +A changeset may be applied to a database with a compatible schema using +the +.Fn sqlite3changeset_apply +API. +.Pp +Within a changeset generated by this function, all changes related +to a single table are grouped together. +In other words, when iterating through a changeset or when applying +a changeset to a database, all changes related to a single table are +processed before moving on to the next table. +Tables are sorted in the same order in which they were attached (or +auto-attached) to the sqlite3_session object. +The order in which the changes related to a single table are stored +is undefined. +.Pp +Following a successful call to this function, it is the responsibility +of the caller to eventually free the buffer that *ppChangeset points +to using +.Fn sqlite3_free . +.Ss Changeset Generation +Once a table has been attached to a session object, the session object +records the primary key values of all new rows inserted into the table. +It also records the original primary key and other column values of +any deleted or updated rows. +For each unique primary key value, data is only recorded once - the +first time a row with said primary key is inserted, updated or deleted +in the lifetime of the session. +.Pp +There is one exception to the previous paragraph: when a row is inserted, +updated or deleted, if one or more of its primary key columns contain +a NULL value, no record of the change is made. +.Pp +The session object therefore accumulates two types of records - those +that consist of primary key values only (created when the user inserts +a new record) and those that consist of the primary key values and +the original values of other table columns (created when the users +deletes or updates a record). +.Pp +When this function is called, the requested changeset is created using +both the accumulated records and the current contents of the database +file. +Specifically: +.Bl -bullet +.It +For each record generated by an insert, the database is queried for +a row with a matching primary key. +If one is found, an INSERT change is added to the changeset. +If no such row is found, no change is added to the changeset. +.It +For each record generated by an update or delete, the database is queried +for a row with a matching primary key. +If such a row is found and one or more of the non-primary key fields +have been modified from their original values, an UPDATE change is +added to the changeset. +Or, if no such row is found in the table, a DELETE change is added +to the changeset. +If there is a row with a matching primary key in the database, but +all fields contain their original values, no change is added to the +changeset. +.El +.Pp +This means, amongst other things, that if a row is inserted and then +later deleted while a session object is active, neither the insert +nor the delete will be present in the changeset. +Or if a row is deleted and then later a row with the same primary key +values inserted while a session object is active, the resulting changeset +will contain an UPDATE change instead of a DELETE and an INSERT. +.Pp +When a session object is disabled (see the +.Fn sqlite3session_enable +API), it does not accumulate records when rows are inserted, updated +or deleted. +This may appear to have some counter-intuitive effects if a single +row is written to more than once during a session. +For example, if a row is inserted while a session object is enabled, +then later deleted while the same session object is disabled, no INSERT +record will appear in the changeset, even though the delete took place +while the session was disabled. +Or, if one field of a row is updated while a session is disabled, and +another field of the same row is updated while the session is enabled, +the resulting changeset will contain an UPDATE change that updates +both fields. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11183. +.Bd -literal +SQLITE_API int sqlite3session_changeset( + sqlite3_session *pSession, /* Session object */ + int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ + void **ppChangeset /* OUT: Buffer containing changeset */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_malloc 3 , +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_start 3 , +.Xr sqlite3session_enable 3 diff --git a/static/netbsd/man3/sqlite3session_changeset_size.3 b/static/netbsd/man3/sqlite3session_changeset_size.3 new file mode 100644 index 00000000..9a36ed68 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_changeset_size.3 @@ -0,0 +1,29 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_CHANGESET_SIZE 3 +.Os +.Sh NAME +.Nm sqlite3session_changeset_size +.Nd return an upper-limit for the size of the changeset +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_int64 +.Fo sqlite3session_changeset_size +.Fa "sqlite3_session *pSession" +.Fc +.Sh DESCRIPTION +By default, this function always returns 0. +For it to return a useful result, the sqlite3_session object must have +been configured to enable this API using sqlite3session_object_config() +with the SQLITE_SESSION_OBJCONFIG_SIZE verb. +.Pp +When enabled, this function returns an upper limit, in bytes, for the +size of the changeset that might be produced if sqlite3session_changeset() +were called. +The final changeset size might be equal to or smaller than the size +in bytes returned by this function. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11294. +.Bd -literal +SQLITE_API sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession); +.Ed diff --git a/static/netbsd/man3/sqlite3session_config.3 b/static/netbsd/man3/sqlite3session_config.3 new file mode 100644 index 00000000..848be5f2 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_config.3 @@ -0,0 +1,51 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_CONFIG 3 +.Os +.Sh NAME +.Nm sqlite3session_config +.Nd configure global parameters +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_config +.Fa "int op" +.Fa "void *pArg" +.Fc +.Sh DESCRIPTION +The sqlite3session_config() interface is used to make global configuration +changes to the sessions module in order to tune it to the specific +needs of the application. +.Pp +The sqlite3session_config() interface is not threadsafe. +If it is invoked while any other thread is inside any other sessions +method then the results are undefined. +Furthermore, if it is invoked after any sessions related objects have +been created, the results are also undefined. +.Pp +The first argument to the sqlite3session_config() function must be +one of the SQLITE_SESSION_CONFIG_XXX constants defined below. +The interpretation of the (void*) value passed as the second parameter +and the effect of calling this function depends on the value of the +first parameter. +.Bl -tag -width Ds +.It SQLITE_SESSION_CONFIG_STRMSIZE +By default, the sessions module streaming interfaces attempt to input +and output data in approximately 1 KiB chunks. +This operand may be used to set and query the value of this configuration +setting. +The pointer passed as the second argument must point to a value of +type (int). +If this value is greater than 0, it is used as the new streaming data +chunk size for both input and output. +Before returning, the (int) value pointed to by pArg is set to the +final value of the streaming interface chunk size. +.El +.Pp +This function returns SQLITE_OK if successful, or an SQLite error code +otherwise. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12680. +.Bd -literal +SQLITE_API int sqlite3session_config(int op, void *pArg); +.Ed diff --git a/static/netbsd/man3/sqlite3session_create.3 b/static/netbsd/man3/sqlite3session_create.3 new file mode 100644 index 00000000..b310c67b --- /dev/null +++ b/static/netbsd/man3/sqlite3session_create.3 @@ -0,0 +1,60 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_CREATE 3 +.Os +.Sh NAME +.Nm sqlite3session_create +.Nd create a new session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_create +.Fa "sqlite3 *db" +.Fa "const char *zDb" +.Fa "sqlite3_session **ppSession" +.Fc +.Sh DESCRIPTION +Create a new session object attached to database handle db. +If successful, a pointer to the new object is written to *ppSession +and SQLITE_OK is returned. +If an error occurs, *ppSession is set to NULL and an SQLite error code +(e.g. SQLITE_NOMEM) is returned. +.Pp +It is possible to create multiple session objects attached to a single +database handle. +.Pp +Session objects created using this function should be deleted using +the +.Fn sqlite3session_delete +function before the database handle that they are attached to is itself +closed. +If the database handle is closed before the session object is deleted, +then the results of calling any session module function, including +.Fn sqlite3session_delete +on the session object are undefined. +.Pp +Because the session module uses the +.Fn sqlite3_preupdate_hook +API, it is not possible for an application to register a pre-update +hook on a database handle that has one or more session objects attached. +Nor is it possible to create a session object attached to a database +handle for which a pre-update hook is already defined. +The results of attempting either of these things are undefined. +.Pp +The session object will be used to create changesets for tables in +database zDb, where zDb is either "main", or "temp", or the name of +an attached database. +It is not an error if database zDb is not attached to the database +when the session object is created. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10953. +.Bd -literal +SQLITE_API int sqlite3session_create( + sqlite3 *db, /* Database handle */ + const char *zDb, /* Name of db (e.g. "main") */ + sqlite3_session **ppSession /* OUT: New session object */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3_preupdate_hook 3 , +.Xr sqlite3session_delete 3 diff --git a/static/netbsd/man3/sqlite3session_delete.3 b/static/netbsd/man3/sqlite3session_delete.3 new file mode 100644 index 00000000..4e760e32 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_delete.3 @@ -0,0 +1,31 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_DELETE 3 +.Os +.Sh NAME +.Nm sqlite3session_delete +.Nd delete a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3session_delete +.Fa "sqlite3_session *pSession" +.Fc +.Sh DESCRIPTION +Delete a session object previously allocated using +.Fn sqlite3session_create . +Once a session object has been deleted, the results of attempting to +use pSession with any other session module function are undefined. +.Pp +Session objects must be deleted before the database handle to which +they are attached is closed. +Refer to the documentation for +.Fn sqlite3session_create +for details. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10990. +.Bd -literal +SQLITE_API void sqlite3session_delete(sqlite3_session *pSession); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_create 3 diff --git a/static/netbsd/man3/sqlite3session_diff.3 b/static/netbsd/man3/sqlite3session_diff.3 new file mode 100644 index 00000000..0ff831d3 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_diff.3 @@ -0,0 +1,87 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_DIFF 3 +.Os +.Sh NAME +.Nm sqlite3session_diff +.Nd load the difference between tables into a session +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_diff +.Fa "sqlite3_session *pSession" +.Fa "const char *zFromDb" +.Fa "const char *zTbl" +.Fa "char **pzErrMsg" +.Fc +.Sh DESCRIPTION +If it is not already attached to the session object passed as the first +argument, this function attaches table zTbl in the same manner as the +.Fn sqlite3session_attach +function. +If zTbl does not exist, or if it does not have a primary key, this +function is a no-op (but does not return an error). +.Pp +Argument zFromDb must be the name of a database ("main", "temp" etc.) +attached to the same database handle as the session object that contains +a table compatible with the table attached to the session by this function. +A table is considered compatible if it: +.Bl -bullet +.It +Has the same name, +.It +Has the same set of columns declared in the same order, and +.It +Has the same PRIMARY KEY definition. +.El +.Pp +If the tables are not compatible, SQLITE_SCHEMA is returned. +If the tables are compatible but do not have any PRIMARY KEY columns, +it is not an error but no changes are added to the session object. +As with other session APIs, tables without PRIMARY KEYs are simply +ignored. +.Pp +This function adds a set of changes to the session object that could +be used to update the table in database zFrom (call this the "from-table") +so that its content is the same as the table attached to the session +object (call this the "to-table"). +Specifically: +.Bl -bullet +.It +For each row (primary key) that exists in the to-table but not in the +from-table, an INSERT record is added to the session object. +.It +For each row (primary key) that exists in the to-table but not in the +from-table, a DELETE record is added to the session object. +.It +For each row (primary key) that exists in both tables, but features +different non-PK values in each, an UPDATE record is added to the session. +.El +.Pp +To clarify, if this function is called and then a changeset constructed +using +.Fn sqlite3session_changeset , +then after applying that changeset to database zFrom the contents of +the two compatible tables would be identical. +.Pp +It an error if database zFrom does not exist or does not contain the +required compatible table. +.Pp +If the operation is successful, SQLITE_OK is returned. +Otherwise, an SQLite error code. +In this case, if argument pzErrMsg is not NULL, *pzErrMsg may be set +to point to a buffer containing an English language error message. +It is the responsibility of the caller to free this buffer using sqlite3_free(). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11310. +.Bd -literal +SQLITE_API int sqlite3session_diff( + sqlite3_session *pSession, + const char *zFromDb, + const char *zTbl, + char **pzErrMsg +); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_attach 3 , +.Xr sqlite3session_changeset 3 diff --git a/static/netbsd/man3/sqlite3session_enable.3 b/static/netbsd/man3/sqlite3session_enable.3 new file mode 100644 index 00000000..16d61f17 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_enable.3 @@ -0,0 +1,38 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_ENABLE 3 +.Os +.Sh NAME +.Nm sqlite3session_enable +.Nd enable or disable a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_enable +.Fa "sqlite3_session *pSession" +.Fa "int bEnable" +.Fc +.Sh DESCRIPTION +Enable or disable the recording of changes by a session object. +When enabled, a session object records changes made to the database. +When disabled - it does not. +A newly created session object is enabled. +Refer to the documentation for +.Fn sqlite3session_changeset +for further details regarding how enabling and disabling a session +object affects the eventual changesets. +.Pp +Passing zero to this function disables the session. +Passing a value greater than zero enables it. +Passing a value less than zero is a no-op, and may be used to query +the current state of the session. +.Pp +The return value indicates the final state of the session object: 0 +if the session is disabled, or 1 if it is enabled. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11051. +.Bd -literal +SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_changeset 3 diff --git a/static/netbsd/man3/sqlite3session_indirect.3 b/static/netbsd/man3/sqlite3session_indirect.3 new file mode 100644 index 00000000..88c3045f --- /dev/null +++ b/static/netbsd/man3/sqlite3session_indirect.3 @@ -0,0 +1,47 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_INDIRECT 3 +.Os +.Sh NAME +.Nm sqlite3session_indirect +.Nd set or clear the indirect change flag +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_indirect +.Fa "sqlite3_session *pSession" +.Fa "int bIndirect" +.Fc +.Sh DESCRIPTION +Each change recorded by a session object is marked as either direct +or indirect. +A change is marked as indirect if either: +.Bl -bullet +.It +The session object "indirect" flag is set when the change is made, +or +.It +The change is made by an SQL trigger or foreign key action instead +of directly as a result of a users SQL statement. +.El +.Pp +If a single row is affected by more than one operation within a session, +then the change is considered indirect if all operations meet the criteria +for an indirect change above, or direct otherwise. +.Pp +This function is used to set, clear or query the session object indirect +flag. +If the second argument passed to this function is zero, then the indirect +flag is cleared. +If it is greater than zero, the indirect flag is set. +Passing a value less than zero does not modify the current value of +the indirect flag, and may be used to query the current state of the +indirect flag for the specified session object. +.Pp +The return value indicates the final state of the indirect flag: 0 +if it is clear, or 1 if it is set. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11071. +.Bd -literal +SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect); +.Ed diff --git a/static/netbsd/man3/sqlite3session_isempty.3 b/static/netbsd/man3/sqlite3session_isempty.3 new file mode 100644 index 00000000..ccd21882 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_isempty.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_ISEMPTY 3 +.Os +.Sh NAME +.Nm sqlite3session_isempty +.Nd test if a changeset has recorded any changes +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_isempty +.Fa "sqlite3_session *pSession" +.Fc +.Sh DESCRIPTION +Return non-zero if no changes to attached tables have been recorded +by the session object passed as the first argument. +Otherwise, if one or more changes have been recorded, return zero. +.Pp +Even if this function returns zero, it is possible that calling +.Fn sqlite3session_changeset +on the session handle may still return a changeset that contains no +changes. +This can happen when a row in an attached table is modified and then +later on the original values are restored. +However, if this function returns non-zero, then it is guaranteed that +a call to sqlite3session_changeset() will return a changeset containing +zero changes. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11410. +.Bd -literal +SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_changeset 3 diff --git a/static/netbsd/man3/sqlite3session_memory_used.3 b/static/netbsd/man3/sqlite3session_memory_used.3 new file mode 100644 index 00000000..d9de94dc --- /dev/null +++ b/static/netbsd/man3/sqlite3session_memory_used.3 @@ -0,0 +1,21 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_MEMORY_USED 3 +.Os +.Sh NAME +.Nm sqlite3session_memory_used +.Nd query for the amount of heap memory used by a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_int64 +.Fo sqlite3session_memory_used +.Fa "sqlite3_session *pSession" +.Fc +.Sh DESCRIPTION +This API returns the total amount of heap memory in bytes currently +used by the session object passed as the only argument. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11427. +.Bd -literal +SQLITE_API sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession); +.Ed diff --git a/static/netbsd/man3/sqlite3session_object_config.3 b/static/netbsd/man3/sqlite3session_object_config.3 new file mode 100644 index 00000000..d555b353 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_object_config.3 @@ -0,0 +1,28 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_OBJECT_CONFIG 3 +.Os +.Sh NAME +.Nm sqlite3session_object_config +.Nd configure a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_object_config +.Fa "sqlite3_session*" +.Fa "int op" +.Fa "void *pArg" +.Fc +.Sh DESCRIPTION +This method is used to configure a session object after it has been +created. +At present the only valid values for the second parameter are SQLITE_SESSION_OBJCONFIG_SIZE +and SQLITE_SESSION_OBJCONFIG_ROWID. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11005. +.Bd -literal +SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg); +.Ed +.Sh SEE ALSO +.Xr SQLITE_SESSION_OBJCONFIG_SIZE 3 diff --git a/static/netbsd/man3/sqlite3session_patchset.3 b/static/netbsd/man3/sqlite3session_patchset.3 new file mode 100644 index 00000000..73cf37da --- /dev/null +++ b/static/netbsd/man3/sqlite3session_patchset.3 @@ -0,0 +1,50 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_PATCHSET 3 +.Os +.Sh NAME +.Nm sqlite3session_patchset +.Nd generate a patchset from a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_patchset +.Fa "sqlite3_session *pSession" +.Fa "int *pnPatchset" +.Fa "void **ppPatchset" +.Fc +.Sh DESCRIPTION +The differences between a patchset and a changeset are that: +.Bl -bullet +.It +DELETE records consist of the primary key fields only. +The original values of other fields are omitted. +.It +The original values of any modified fields are omitted from UPDATE +records. +.El +.Pp +A patchset blob may be used with up to date versions of all sqlite3changeset_xxx +API functions except for sqlite3changeset_invert(), which returns SQLITE_CORRUPT +if it is passed a patchset. +Similarly, attempting to use a patchset blob with old versions of the +sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. +.Pp +Because the non-primary key "old.*" fields are omitted, no SQLITE_CHANGESET_DATA +conflicts can be detected or reported if a patchset is passed to the +sqlite3changeset_apply() API. +Other conflict types work in the same way as for changesets. +.Pp +Changes within a patchset are ordered in the same way as for changesets +generated by the sqlite3session_changeset() function (i.e. all changes +for a single table are grouped together, tables appear in the order +in which they were attached to the session object). +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11375. +.Bd -literal +SQLITE_API int sqlite3session_patchset( + sqlite3_session *pSession, /* Session object */ + int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */ + void **ppPatchset /* OUT: Buffer containing patchset */ +); +.Ed diff --git a/static/netbsd/man3/sqlite3session_table_filter.3 b/static/netbsd/man3/sqlite3session_table_filter.3 new file mode 100644 index 00000000..83495064 --- /dev/null +++ b/static/netbsd/man3/sqlite3session_table_filter.3 @@ -0,0 +1,34 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_TABLE_FILTER 3 +.Os +.Sh NAME +.Nm sqlite3session_table_filter +.Nd set a table filter on a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3session_table_filter +.Fa "sqlite3_session *pSession" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "void *pCtx" +.Fc +.Sh DESCRIPTION +The second argument (xFilter) is the "filter callback". +For changes to rows in tables that are not attached to the Session +object, the filter is called to determine whether changes to the table's +rows should be tracked or not. +If xFilter returns 0, changes are not tracked. +Note that once a table is attached, xFilter will not be called again. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11164. +.Bd -literal +SQLITE_API void sqlite3session_table_filter( + sqlite3_session *pSession, /* Session object */ + int(*xFilter)( + void *pCtx, /* Copy of third arg to _filter_table() */ + const char *zTab /* Table name */ + ), + void *pCtx /* First argument passed to xFilter */ +); +.Ed diff --git a/static/netbsd/man3/sqlite_int64.3 b/static/netbsd/man3/sqlite_int64.3 new file mode 100644 index 00000000..fe1cb119 --- /dev/null +++ b/static/netbsd/man3/sqlite_int64.3 @@ -0,0 +1,58 @@ +.Dd January 24, 2024 +.Dt SQLITE_INT64 3 +.Os +.Sh NAME +.Nm sqlite_int64 , +.Nm sqlite_uint64 , +.Nm sqlite_uint64 , +.Nm sqlite_int64 , +.Nm sqlite_uint64 , +.Nm sqlite_int64 , +.Nm sqlite_uint64 , +.Nm sqlite3_int64 , +.Nm sqlite3_uint64 +.Nd 64-Bit integer types +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef SQLITE_INT64_TYPE sqlite_int64; +.Vt typedef SQLITE_UINT64_TYPE sqlite_uint64; +.Vt typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; +.Vt typedef __int64 sqlite_int64; +.Vt typedef unsigned __int64 sqlite_uint64; +.Vt typedef long long int sqlite_int64; +.Vt typedef unsigned long long int sqlite_uint64; +.Vt typedef sqlite_int64 sqlite3_int64; +.Vt typedef sqlite_uint64 sqlite3_uint64; +.Sh DESCRIPTION +Because there is no cross-platform way to specify 64-bit integer types +SQLite includes typedefs for 64-bit signed and unsigned integers. +.Pp +The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. +The sqlite_int64 and sqlite_uint64 types are supported for backwards +compatibility only. +.Pp +The sqlite3_int64 and sqlite_int64 types can store integer values between +-9223372036854775808 and +9223372036854775807 inclusive. +The sqlite3_uint64 and sqlite_uint64 types can store integer values +between 0 and +18446744073709551615 inclusive. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 275. +.Bd -literal +#ifdef SQLITE_INT64_TYPE + typedef SQLITE_INT64_TYPE sqlite_int64; +# ifdef SQLITE_UINT64_TYPE + typedef SQLITE_UINT64_TYPE sqlite_uint64; +# else + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; +# endif +#elif defined(_MSC_VER) || defined(__BORLANDC__) + typedef __int64 sqlite_int64; + typedef unsigned __int64 sqlite_uint64; +#else + typedef long long int sqlite_int64; + typedef unsigned long long int sqlite_uint64; +#endif +typedef sqlite_int64 sqlite3_int64; +typedef sqlite_uint64 sqlite3_uint64; +.Ed diff --git a/static/netbsd/man3/sqrt.3 b/static/netbsd/man3/sqrt.3 new file mode 100644 index 00000000..50cb194c --- /dev/null +++ b/static/netbsd/man3/sqrt.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)sqrt.3 6.4 (Berkeley) 5/6/91 +.\" $NetBSD: sqrt.3,v 1.15 2022/12/04 11:25:09 uwe Exp $ +.\" +.Dd November 19, 2013 +.Dt SQRT 3 +.Os +.Sh NAME +.Nm cbrt , +.Nm cbrtf , +.Nm cbrtl , +.Nm sqrt , +.Nm sqrtf , +.Nm sqrtl +.Nd cube root and square root functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn cbrt "double x" +.Ft float +.Fn cbrtf "float x" +.Ft long double +.Fn cbrtl "long double x" +.Ft double +.Fn sqrt "double x" +.Ft float +.Fn sqrtf "float x" +.Ft long double +.Fn sqrtl "long double x" +.Sh DESCRIPTION +The +.Fn cbrt , +.Fn cbrtf +and +.Fn cbrtl +functions compute +the cube root of +.Ar x . +.Pp +The +.Fn sqrt , +.Fn sqrtf +and +.Fn sqrtl +functions compute +the non-negative square root of x. +.Sh RETURN VALUES +If x is negative, +.Fn sqrt "x" , +.Fn sqrtf "x" +and +.Fn sqrtl "x" +.\" POSIX_MODE +set the global variable +.Va errno +to +.Er EDOM . +.\" SYSV_MODE +.\" call +.\" .Xr matherr 3 . +.Sh SEE ALSO +.Xr math 3 +.\" .Xr matherr 3 +.Sh STANDARDS +The +.Fn sqrt +function conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn cbrt +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/ssl.3 b/static/netbsd/man3/ssl.3 new file mode 100644 index 00000000..034c587d --- /dev/null +++ b/static/netbsd/man3/ssl.3 @@ -0,0 +1,878 @@ +.\" $NetBSD: ssl.3,v 1.1.1.1 2018/02/03 22:43:39 christos Exp $ +.\" +.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ssl 3" +.TH ssl 3 "2016-10-14" "1.0.2k" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +SSL \- OpenSSL SSL/TLS library +.SH "LIBRARY" +libcrypto, -lcrypto +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The OpenSSL \fBssl\fR library implements the Secure Sockets Layer (\s-1SSL\s0 v2/v3) and +Transport Layer Security (\s-1TLS\s0 v1) protocols. It provides a rich \s-1API\s0 which is +documented here. +.PP +At first the library must be initialized; see +\&\fISSL_library_init\fR\|(3). +.PP +Then an \fB\s-1SSL_CTX\s0\fR object is created as a framework to establish +\&\s-1TLS/SSL\s0 enabled connections (see \fISSL_CTX_new\fR\|(3)). +Various options regarding certificates, algorithms etc. can be set +in this object. +.PP +When a network connection has been created, it can be assigned to an +\&\fB\s-1SSL\s0\fR object. After the \fB\s-1SSL\s0\fR object has been created using +\&\fISSL_new\fR\|(3), \fISSL_set_fd\fR\|(3) or +\&\fISSL_set_bio\fR\|(3) can be used to associate the network +connection with the object. +.PP +Then the \s-1TLS/SSL\s0 handshake is performed using +\&\fISSL_accept\fR\|(3) or \fISSL_connect\fR\|(3) +respectively. +\&\fISSL_read\fR\|(3) and \fISSL_write\fR\|(3) are used +to read and write data on the \s-1TLS/SSL\s0 connection. +\&\fISSL_shutdown\fR\|(3) can be used to shut down the +\&\s-1TLS/SSL\s0 connection. +.SH "DATA STRUCTURES" +.IX Header "DATA STRUCTURES" +Currently the OpenSSL \fBssl\fR library functions deals with the following data +structures: +.IP "\fB\s-1SSL_METHOD\s0\fR (\s-1SSL\s0 Method)" 4 +.IX Item "SSL_METHOD (SSL Method)" +That's a dispatch structure describing the internal \fBssl\fR library +methods/functions which implement the various protocol versions (SSLv1, SSLv2 +and TLSv1). It's needed to create an \fB\s-1SSL_CTX\s0\fR. +.IP "\fB\s-1SSL_CIPHER\s0\fR (\s-1SSL\s0 Cipher)" 4 +.IX Item "SSL_CIPHER (SSL Cipher)" +This structure holds the algorithm information for a particular cipher which +are a core part of the \s-1SSL/TLS\s0 protocol. The available ciphers are configured +on a \fB\s-1SSL_CTX\s0\fR basis and the actually used ones are then part of the +\&\fB\s-1SSL_SESSION\s0\fR. +.IP "\fB\s-1SSL_CTX\s0\fR (\s-1SSL\s0 Context)" 4 +.IX Item "SSL_CTX (SSL Context)" +That's the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +\&\fB\s-1SSL\s0\fR structures which are later created for the connections. +.IP "\fB\s-1SSL_SESSION\s0\fR (\s-1SSL\s0 Session)" 4 +.IX Item "SSL_SESSION (SSL Session)" +This is a structure containing the current \s-1TLS/SSL\s0 session details for a +connection: \fB\s-1SSL_CIPHER\s0\fRs, client and server certificates, keys, etc. +.IP "\fB\s-1SSL\s0\fR (\s-1SSL\s0 Connection)" 4 +.IX Item "SSL (SSL Connection)" +That's the main \s-1SSL/TLS\s0 structure which is created by a server or client per +established connection. This actually is the core structure in the \s-1SSL API.\s0 +Under run-time the application usually deals with this structure which has +links to mostly all other structures. +.SH "HEADER FILES" +.IX Header "HEADER FILES" +Currently the OpenSSL \fBssl\fR library provides the following C header files +containing the prototypes for the data structures and and functions: +.IP "\fBssl.h\fR" 4 +.IX Item "ssl.h" +That's the common header file for the \s-1SSL/TLS API. \s0 Include it into your +program to make the \s-1API\s0 of the \fBssl\fR library available. It internally +includes both more private \s-1SSL\s0 headers and headers from the \fBcrypto\fR library. +Whenever you need hard-core details on the internals of the \s-1SSL API,\s0 look +inside this header file. +.IP "\fBssl2.h\fR" 4 +.IX Item "ssl2.h" +That's the sub header file dealing with the SSLv2 protocol only. +\&\fIUsually you don't have to include it explicitly because +it's already included by ssl.h\fR. +.IP "\fBssl3.h\fR" 4 +.IX Item "ssl3.h" +That's the sub header file dealing with the SSLv3 protocol only. +\&\fIUsually you don't have to include it explicitly because +it's already included by ssl.h\fR. +.IP "\fBssl23.h\fR" 4 +.IX Item "ssl23.h" +That's the sub header file dealing with the combined use of the SSLv2 and +SSLv3 protocols. +\&\fIUsually you don't have to include it explicitly because +it's already included by ssl.h\fR. +.IP "\fBtls1.h\fR" 4 +.IX Item "tls1.h" +That's the sub header file dealing with the TLSv1 protocol only. +\&\fIUsually you don't have to include it explicitly because +it's already included by ssl.h\fR. +.SH "API FUNCTIONS" +.IX Header "API FUNCTIONS" +Currently the OpenSSL \fBssl\fR library exports 214 \s-1API\s0 functions. +They are documented in the following: +.SS "\s-1DEALING WITH PROTOCOL METHODS\s0" +.IX Subsection "DEALING WITH PROTOCOL METHODS" +Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 +protocol methods defined in \fB\s-1SSL_METHOD\s0\fR structures. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv23_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv23_method(void);" +Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for +clients, servers or both. +See \fISSL_CTX_new\fR\|(3) for details. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv23_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv23_client_method(void);" +Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for +clients. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv23_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv23_client_method(void);" +Constructor for the \fIversion-flexible\fR \s-1SSL_METHOD\s0 structure for +servers. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_2_method(void);" +Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for clients, servers +or both. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_2_client_method(void);" +Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for clients. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_2_server_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_2_server_method(void);" +Constructor for the TLSv1.2 \s-1SSL_METHOD\s0 structure for servers. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_1_method(void);" +Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for clients, servers +or both. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_1_client_method(void);" +Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for clients. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_1_server_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_1_server_method(void);" +Constructor for the TLSv1.1 \s-1SSL_METHOD\s0 structure for servers. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_method(void);" +Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for clients, servers +or both. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_client_method(void);" +Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for clients. +.IP "const \s-1SSL_METHOD\s0 *\fBTLSv1_server_method\fR(void);" 4 +.IX Item "const SSL_METHOD *TLSv1_server_method(void);" +Constructor for the TLSv1 \s-1SSL_METHOD\s0 structure for servers. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv3_method(void);" +Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for clients, servers +or both. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv3_client_method(void);" +Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for clients. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv3_server_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv3_server_method(void);" +Constructor for the SSLv3 \s-1SSL_METHOD\s0 structure for servers. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv2_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv2_method(void);" +Constructor for the SSLv2 \s-1SSL_METHOD\s0 structure for clients, servers +or both. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv2_client_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv2_client_method(void);" +Constructor for the SSLv2 \s-1SSL_METHOD\s0 structure for clients. +.IP "const \s-1SSL_METHOD\s0 *\fBSSLv2_server_method\fR(void);" 4 +.IX Item "const SSL_METHOD *SSLv2_server_method(void);" +Constructor for the SSLv2 \s-1SSL_METHOD\s0 structure for servers. +.SS "\s-1DEALING WITH CIPHERS\s0" +.IX Subsection "DEALING WITH CIPHERS" +Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 +ciphers defined in \fB\s-1SSL_CIPHER\s0\fR structures. +.IP "char *\fBSSL_CIPHER_description\fR(\s-1SSL_CIPHER\s0 *cipher, char *buf, int len);" 4 +.IX Item "char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int len);" +Write a string to \fIbuf\fR (with a maximum size of \fIlen\fR) containing a human +readable description of \fIcipher\fR. Returns \fIbuf\fR. +.IP "int \fBSSL_CIPHER_get_bits\fR(\s-1SSL_CIPHER\s0 *cipher, int *alg_bits);" 4 +.IX Item "int SSL_CIPHER_get_bits(SSL_CIPHER *cipher, int *alg_bits);" +Determine the number of bits in \fIcipher\fR. Because of export crippled ciphers +there are two bits: The bits the algorithm supports in general (stored to +\&\fIalg_bits\fR) and the bits which are actually used (the return value). +.IP "const char *\fBSSL_CIPHER_get_name\fR(\s-1SSL_CIPHER\s0 *cipher);" 4 +.IX Item "const char *SSL_CIPHER_get_name(SSL_CIPHER *cipher);" +Return the internal name of \fIcipher\fR as a string. These are the various +strings defined by the \fISSL2_TXT_xxx\fR, \fISSL3_TXT_xxx\fR and \fITLS1_TXT_xxx\fR +definitions in the header files. +.IP "char *\fBSSL_CIPHER_get_version\fR(\s-1SSL_CIPHER\s0 *cipher);" 4 +.IX Item "char *SSL_CIPHER_get_version(SSL_CIPHER *cipher);" +Returns a string like "\f(CW\*(C`TLSv1/SSLv3\*(C'\fR\*(L" or \*(R"\f(CW\*(C`SSLv2\*(C'\fR" which indicates the +\&\s-1SSL/TLS\s0 protocol version to which \fIcipher\fR belongs (i.e. where it was defined +in the specification the first time). +.SS "\s-1DEALING WITH PROTOCOL CONTEXTS\s0" +.IX Subsection "DEALING WITH PROTOCOL CONTEXTS" +Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 +protocol context defined in the \fB\s-1SSL_CTX\s0\fR structure. +.IP "int \fBSSL_CTX_add_client_CA\fR(\s-1SSL_CTX\s0 *ctx, X509 *x);" 4 +.IX Item "int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x);" +.PD 0 +.IP "long \fBSSL_CTX_add_extra_chain_cert\fR(\s-1SSL_CTX\s0 *ctx, X509 *x509);" 4 +.IX Item "long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);" +.IP "int \fBSSL_CTX_add_session\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *c);" 4 +.IX Item "int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);" +.IP "int \fBSSL_CTX_check_private_key\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_check_private_key(const SSL_CTX *ctx);" +.IP "long \fBSSL_CTX_ctrl\fR(\s-1SSL_CTX\s0 *ctx, int cmd, long larg, char *parg);" 4 +.IX Item "long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, char *parg);" +.IP "void \fBSSL_CTX_flush_sessions\fR(\s-1SSL_CTX\s0 *s, long t);" 4 +.IX Item "void SSL_CTX_flush_sessions(SSL_CTX *s, long t);" +.IP "void \fBSSL_CTX_free\fR(\s-1SSL_CTX\s0 *a);" 4 +.IX Item "void SSL_CTX_free(SSL_CTX *a);" +.IP "char *\fBSSL_CTX_get_app_data\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "char *SSL_CTX_get_app_data(SSL_CTX *ctx);" +.IP "X509_STORE *\fBSSL_CTX_get_cert_store\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx);" +.IP "\s-1STACK\s0 *\fBSSL_CTX_get_client_CA_list\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "STACK *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);" +.IP "int (*\fBSSL_CTX_get_client_cert_cb\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, X509 **x509, \s-1EVP_PKEY\s0 **pkey);" 4 +.IX Item "int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);" +.IP "void \fBSSL_CTX_get_default_read_ahead\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "void SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);" +.IP "char *\fBSSL_CTX_get_ex_data\fR(const \s-1SSL_CTX\s0 *s, int idx);" 4 +.IX Item "char *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx);" +.IP "int \fBSSL_CTX_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 +.IX Item "int SSL_CTX_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" +.IP "void (*\fBSSL_CTX_get_info_callback\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, int cb, int ret);" 4 +.IX Item "void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);" +.IP "int \fBSSL_CTX_get_quiet_shutdown\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);" +.IP "void \fBSSL_CTX_get_read_ahead\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "void SSL_CTX_get_read_ahead(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_get_session_cache_mode\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);" +.IP "long \fBSSL_CTX_get_timeout\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "long SSL_CTX_get_timeout(const SSL_CTX *ctx);" +.IP "int (*\fBSSL_CTX_get_verify_callback\fR(const \s-1SSL_CTX\s0 *ctx))(int ok, X509_STORE_CTX *ctx);" 4 +.IX Item "int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);" +.IP "int \fBSSL_CTX_get_verify_mode\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_get_verify_mode(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_load_verify_locations\fR(\s-1SSL_CTX\s0 *ctx, char *CAfile, char *CApath);" 4 +.IX Item "int SSL_CTX_load_verify_locations(SSL_CTX *ctx, char *CAfile, char *CApath);" +.IP "long \fBSSL_CTX_need_tmp_RSA\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "long SSL_CTX_need_tmp_RSA(SSL_CTX *ctx);" +.IP "\s-1SSL_CTX\s0 *\fBSSL_CTX_new\fR(const \s-1SSL_METHOD\s0 *meth);" 4 +.IX Item "SSL_CTX *SSL_CTX_new(const SSL_METHOD *meth);" +.IP "int \fBSSL_CTX_remove_session\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *c);" 4 +.IX Item "int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);" +.IP "int \fBSSL_CTX_sess_accept\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_accept(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_accept_good\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_accept_good(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_accept_renegotiate\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_cache_full\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_cache_full(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_cb_hits\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_cb_hits(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_connect\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_connect(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_connect_good\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_connect_good(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_connect_renegotiate\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_get_cache_size\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);" +.IP "\s-1SSL_SESSION\s0 *(*\fBSSL_CTX_sess_get_get_cb\fR(\s-1SSL_CTX\s0 *ctx))(\s-1SSL\s0 *ssl, unsigned char *data, int len, int *copy);" 4 +.IX Item "SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);" +.IP "int (*\fBSSL_CTX_sess_get_new_cb\fR(\s-1SSL_CTX\s0 *ctx)(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *sess);" 4 +.IX Item "int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);" +.IP "void (*\fBSSL_CTX_sess_get_remove_cb\fR(\s-1SSL_CTX\s0 *ctx)(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *sess);" 4 +.IX Item "void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);" +.IP "int \fBSSL_CTX_sess_hits\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_hits(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_misses\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_misses(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_sess_number\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_number(SSL_CTX *ctx);" +.IP "void \fBSSL_CTX_sess_set_cache_size\fR(\s-1SSL_CTX\s0 *ctx,t);" 4 +.IX Item "void SSL_CTX_sess_set_cache_size(SSL_CTX *ctx,t);" +.IP "void \fBSSL_CTX_sess_set_get_cb\fR(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *(*cb)(\s-1SSL\s0 *ssl, unsigned char *data, int len, int *copy));" 4 +.IX Item "void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));" +.IP "void \fBSSL_CTX_sess_set_new_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *sess));" 4 +.IX Item "void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));" +.IP "void \fBSSL_CTX_sess_set_remove_cb\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(\s-1SSL_CTX\s0 *ctx, \s-1SSL_SESSION\s0 *sess));" 4 +.IX Item "void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));" +.IP "int \fBSSL_CTX_sess_timeouts\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_sess_timeouts(SSL_CTX *ctx);" +.IP "\s-1LHASH\s0 *\fBSSL_CTX_sessions\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "LHASH *SSL_CTX_sessions(SSL_CTX *ctx);" +.IP "void \fBSSL_CTX_set_app_data\fR(\s-1SSL_CTX\s0 *ctx, void *arg);" 4 +.IX Item "void SSL_CTX_set_app_data(SSL_CTX *ctx, void *arg);" +.IP "void \fBSSL_CTX_set_cert_store\fR(\s-1SSL_CTX\s0 *ctx, X509_STORE *cs);" 4 +.IX Item "void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *cs);" +.IP "void \fBSSL_CTX_set_cert_verify_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(), char *arg)" 4 +.IX Item "void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(), char *arg)" +.IP "int \fBSSL_CTX_set_cipher_list\fR(\s-1SSL_CTX\s0 *ctx, char *str);" 4 +.IX Item "int SSL_CTX_set_cipher_list(SSL_CTX *ctx, char *str);" +.IP "void \fBSSL_CTX_set_client_CA_list\fR(\s-1SSL_CTX\s0 *ctx, \s-1STACK\s0 *list);" 4 +.IX Item "void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK *list);" +.IP "void \fBSSL_CTX_set_client_cert_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb)(\s-1SSL\s0 *ssl, X509 **x509, \s-1EVP_PKEY\s0 **pkey));" 4 +.IX Item "void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));" +.IP "void \fBSSL_CTX_set_default_passwd_cb\fR(\s-1SSL_CTX\s0 *ctx, int (*cb);(void))" 4 +.IX Item "void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, int (*cb);(void))" +.IP "void \fBSSL_CTX_set_default_read_ahead\fR(\s-1SSL_CTX\s0 *ctx, int m);" 4 +.IX Item "void SSL_CTX_set_default_read_ahead(SSL_CTX *ctx, int m);" +.IP "int \fBSSL_CTX_set_default_verify_paths\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);" +.IP "int \fBSSL_CTX_set_ex_data\fR(\s-1SSL_CTX\s0 *s, int idx, char *arg);" 4 +.IX Item "int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, char *arg);" +.IP "void \fBSSL_CTX_set_info_callback\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(\s-1SSL\s0 *ssl, int cb, int ret));" 4 +.IX Item "void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));" +.IP "void \fBSSL_CTX_set_msg_callback\fR(\s-1SSL_CTX\s0 *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, \s-1SSL\s0 *ssl, void *arg));" 4 +.IX Item "void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));" +.IP "void \fBSSL_CTX_set_msg_callback_arg\fR(\s-1SSL_CTX\s0 *ctx, void *arg);" 4 +.IX Item "void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);" +.IP "void \fBSSL_CTX_set_options\fR(\s-1SSL_CTX\s0 *ctx, unsigned long op);" 4 +.IX Item "void SSL_CTX_set_options(SSL_CTX *ctx, unsigned long op);" +.IP "void \fBSSL_CTX_set_quiet_shutdown\fR(\s-1SSL_CTX\s0 *ctx, int mode);" 4 +.IX Item "void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);" +.IP "void \fBSSL_CTX_set_read_ahead\fR(\s-1SSL_CTX\s0 *ctx, int m);" 4 +.IX Item "void SSL_CTX_set_read_ahead(SSL_CTX *ctx, int m);" +.IP "void \fBSSL_CTX_set_session_cache_mode\fR(\s-1SSL_CTX\s0 *ctx, int mode);" 4 +.IX Item "void SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, int mode);" +.IP "int \fBSSL_CTX_set_ssl_version\fR(\s-1SSL_CTX\s0 *ctx, const \s-1SSL_METHOD\s0 *meth);" 4 +.IX Item "int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *meth);" +.IP "void \fBSSL_CTX_set_timeout\fR(\s-1SSL_CTX\s0 *ctx, long t);" 4 +.IX Item "void SSL_CTX_set_timeout(SSL_CTX *ctx, long t);" +.IP "long \fBSSL_CTX_set_tmp_dh\fR(SSL_CTX* ctx, \s-1DH\s0 *dh);" 4 +.IX Item "long SSL_CTX_set_tmp_dh(SSL_CTX* ctx, DH *dh);" +.IP "long \fBSSL_CTX_set_tmp_dh_callback\fR(\s-1SSL_CTX\s0 *ctx, \s-1DH\s0 *(*cb)(void));" 4 +.IX Item "long SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, DH *(*cb)(void));" +.IP "long \fBSSL_CTX_set_tmp_rsa\fR(\s-1SSL_CTX\s0 *ctx, \s-1RSA\s0 *rsa);" 4 +.IX Item "long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);" +.IP "SSL_CTX_set_tmp_rsa_callback" 4 +.IX Item "SSL_CTX_set_tmp_rsa_callback" +.PD +\&\f(CW\*(C`long \f(CBSSL_CTX_set_tmp_rsa_callback\f(CW(SSL_CTX *\f(CBctx\f(CW, RSA *(*\f(CBcb\f(CW)(SSL *\f(CBssl\f(CW, int \f(CBexport\f(CW, int \f(CBkeylength\f(CW));\*(C'\fR +.Sp +Sets the callback which will be called when a temporary private key is +required. The \fB\f(CB\*(C`export\*(C'\fB\fR flag will be set if the reason for needing +a temp key is that an export ciphersuite is in use, in which case, +\&\fB\f(CB\*(C`keylength\*(C'\fB\fR will contain the required keylength in bits. Generate a key of +appropriate size (using ???) and return it. +.IP "SSL_set_tmp_rsa_callback" 4 +.IX Item "SSL_set_tmp_rsa_callback" +long \fBSSL_set_tmp_rsa_callback\fR(\s-1SSL\s0 *ssl, \s-1RSA\s0 *(*cb)(\s-1SSL\s0 *ssl, int export, int keylength)); +.Sp +The same as \fBSSL_CTX_set_tmp_rsa_callback\fR, except it operates on an \s-1SSL\s0 +session instead of a context. +.IP "void \fBSSL_CTX_set_verify\fR(\s-1SSL_CTX\s0 *ctx, int mode, int (*cb);(void))" 4 +.IX Item "void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, int (*cb);(void))" +.PD 0 +.IP "int \fBSSL_CTX_use_PrivateKey\fR(\s-1SSL_CTX\s0 *ctx, \s-1EVP_PKEY\s0 *pkey);" 4 +.IX Item "int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);" +.IP "int \fBSSL_CTX_use_PrivateKey_ASN1\fR(int type, \s-1SSL_CTX\s0 *ctx, unsigned char *d, long len);" 4 +.IX Item "int SSL_CTX_use_PrivateKey_ASN1(int type, SSL_CTX *ctx, unsigned char *d, long len);" +.IP "int \fBSSL_CTX_use_PrivateKey_file\fR(\s-1SSL_CTX\s0 *ctx, char *file, int type);" 4 +.IX Item "int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, char *file, int type);" +.IP "int \fBSSL_CTX_use_RSAPrivateKey\fR(\s-1SSL_CTX\s0 *ctx, \s-1RSA\s0 *rsa);" 4 +.IX Item "int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);" +.IP "int \fBSSL_CTX_use_RSAPrivateKey_ASN1\fR(\s-1SSL_CTX\s0 *ctx, unsigned char *d, long len);" 4 +.IX Item "int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);" +.IP "int \fBSSL_CTX_use_RSAPrivateKey_file\fR(\s-1SSL_CTX\s0 *ctx, char *file, int type);" 4 +.IX Item "int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, char *file, int type);" +.IP "int \fBSSL_CTX_use_certificate\fR(\s-1SSL_CTX\s0 *ctx, X509 *x);" 4 +.IX Item "int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);" +.IP "int \fBSSL_CTX_use_certificate_ASN1\fR(\s-1SSL_CTX\s0 *ctx, int len, unsigned char *d);" 4 +.IX Item "int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);" +.IP "int \fBSSL_CTX_use_certificate_file\fR(\s-1SSL_CTX\s0 *ctx, char *file, int type);" 4 +.IX Item "int SSL_CTX_use_certificate_file(SSL_CTX *ctx, char *file, int type);" +.IP "X509 *\fBSSL_CTX_get0_certificate\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "X509 *SSL_CTX_get0_certificate(const SSL_CTX *ctx);" +.IP "\s-1EVP_PKEY\s0 *\fBSSL_CTX_get0_privatekey\fR(const \s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "EVP_PKEY *SSL_CTX_get0_privatekey(const SSL_CTX *ctx);" +.IP "void \fBSSL_CTX_set_psk_client_callback\fR(\s-1SSL_CTX\s0 *ctx, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" 4 +.IX Item "void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" +.IP "int \fBSSL_CTX_use_psk_identity_hint\fR(\s-1SSL_CTX\s0 *ctx, const char *hint);" 4 +.IX Item "int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);" +.IP "void \fBSSL_CTX_set_psk_server_callback\fR(\s-1SSL_CTX\s0 *ctx, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *identity, unsigned char *psk, int max_psk_len));" 4 +.IX Item "void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));" +.PD +.SS "\s-1DEALING WITH SESSIONS\s0" +.IX Subsection "DEALING WITH SESSIONS" +Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 +sessions defined in the \fB\s-1SSL_SESSION\s0\fR structures. +.IP "int \fBSSL_SESSION_cmp\fR(const \s-1SSL_SESSION\s0 *a, const \s-1SSL_SESSION\s0 *b);" 4 +.IX Item "int SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b);" +.PD 0 +.IP "void \fBSSL_SESSION_free\fR(\s-1SSL_SESSION\s0 *ss);" 4 +.IX Item "void SSL_SESSION_free(SSL_SESSION *ss);" +.IP "char *\fBSSL_SESSION_get_app_data\fR(\s-1SSL_SESSION\s0 *s);" 4 +.IX Item "char *SSL_SESSION_get_app_data(SSL_SESSION *s);" +.IP "char *\fBSSL_SESSION_get_ex_data\fR(const \s-1SSL_SESSION\s0 *s, int idx);" 4 +.IX Item "char *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx);" +.IP "int \fBSSL_SESSION_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 +.IX Item "int SSL_SESSION_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" +.IP "long \fBSSL_SESSION_get_time\fR(const \s-1SSL_SESSION\s0 *s);" 4 +.IX Item "long SSL_SESSION_get_time(const SSL_SESSION *s);" +.IP "long \fBSSL_SESSION_get_timeout\fR(const \s-1SSL_SESSION\s0 *s);" 4 +.IX Item "long SSL_SESSION_get_timeout(const SSL_SESSION *s);" +.IP "unsigned long \fBSSL_SESSION_hash\fR(const \s-1SSL_SESSION\s0 *a);" 4 +.IX Item "unsigned long SSL_SESSION_hash(const SSL_SESSION *a);" +.IP "\s-1SSL_SESSION\s0 *\fBSSL_SESSION_new\fR(void);" 4 +.IX Item "SSL_SESSION *SSL_SESSION_new(void);" +.IP "int \fBSSL_SESSION_print\fR(\s-1BIO\s0 *bp, const \s-1SSL_SESSION\s0 *x);" 4 +.IX Item "int SSL_SESSION_print(BIO *bp, const SSL_SESSION *x);" +.IP "int \fBSSL_SESSION_print_fp\fR(\s-1FILE\s0 *fp, const \s-1SSL_SESSION\s0 *x);" 4 +.IX Item "int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *x);" +.IP "void \fBSSL_SESSION_set_app_data\fR(\s-1SSL_SESSION\s0 *s, char *a);" 4 +.IX Item "void SSL_SESSION_set_app_data(SSL_SESSION *s, char *a);" +.IP "int \fBSSL_SESSION_set_ex_data\fR(\s-1SSL_SESSION\s0 *s, int idx, char *arg);" 4 +.IX Item "int SSL_SESSION_set_ex_data(SSL_SESSION *s, int idx, char *arg);" +.IP "long \fBSSL_SESSION_set_time\fR(\s-1SSL_SESSION\s0 *s, long t);" 4 +.IX Item "long SSL_SESSION_set_time(SSL_SESSION *s, long t);" +.IP "long \fBSSL_SESSION_set_timeout\fR(\s-1SSL_SESSION\s0 *s, long t);" 4 +.IX Item "long SSL_SESSION_set_timeout(SSL_SESSION *s, long t);" +.PD +.SS "\s-1DEALING WITH CONNECTIONS\s0" +.IX Subsection "DEALING WITH CONNECTIONS" +Here we document the various \s-1API\s0 functions which deal with the \s-1SSL/TLS\s0 +connection defined in the \fB\s-1SSL\s0\fR structure. +.IP "int \fBSSL_accept\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_accept(SSL *ssl);" +.PD 0 +.IP "int \fBSSL_add_dir_cert_subjects_to_stack\fR(\s-1STACK\s0 *stack, const char *dir);" 4 +.IX Item "int SSL_add_dir_cert_subjects_to_stack(STACK *stack, const char *dir);" +.IP "int \fBSSL_add_file_cert_subjects_to_stack\fR(\s-1STACK\s0 *stack, const char *file);" 4 +.IX Item "int SSL_add_file_cert_subjects_to_stack(STACK *stack, const char *file);" +.IP "int \fBSSL_add_client_CA\fR(\s-1SSL\s0 *ssl, X509 *x);" 4 +.IX Item "int SSL_add_client_CA(SSL *ssl, X509 *x);" +.IP "char *\fBSSL_alert_desc_string\fR(int value);" 4 +.IX Item "char *SSL_alert_desc_string(int value);" +.IP "char *\fBSSL_alert_desc_string_long\fR(int value);" 4 +.IX Item "char *SSL_alert_desc_string_long(int value);" +.IP "char *\fBSSL_alert_type_string\fR(int value);" 4 +.IX Item "char *SSL_alert_type_string(int value);" +.IP "char *\fBSSL_alert_type_string_long\fR(int value);" 4 +.IX Item "char *SSL_alert_type_string_long(int value);" +.IP "int \fBSSL_check_private_key\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_check_private_key(const SSL *ssl);" +.IP "void \fBSSL_clear\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "void SSL_clear(SSL *ssl);" +.IP "long \fBSSL_clear_num_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_clear_num_renegotiations(SSL *ssl);" +.IP "int \fBSSL_connect\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_connect(SSL *ssl);" +.IP "void \fBSSL_copy_session_id\fR(\s-1SSL\s0 *t, const \s-1SSL\s0 *f);" 4 +.IX Item "void SSL_copy_session_id(SSL *t, const SSL *f);" +.IP "long \fBSSL_ctrl\fR(\s-1SSL\s0 *ssl, int cmd, long larg, char *parg);" 4 +.IX Item "long SSL_ctrl(SSL *ssl, int cmd, long larg, char *parg);" +.IP "int \fBSSL_do_handshake\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_do_handshake(SSL *ssl);" +.IP "\s-1SSL\s0 *\fBSSL_dup\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "SSL *SSL_dup(SSL *ssl);" +.IP "\s-1STACK\s0 *\fBSSL_dup_CA_list\fR(\s-1STACK\s0 *sk);" 4 +.IX Item "STACK *SSL_dup_CA_list(STACK *sk);" +.IP "void \fBSSL_free\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "void SSL_free(SSL *ssl);" +.IP "\s-1SSL_CTX\s0 *\fBSSL_get_SSL_CTX\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);" +.IP "char *\fBSSL_get_app_data\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_get_app_data(SSL *ssl);" +.IP "X509 *\fBSSL_get_certificate\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "X509 *SSL_get_certificate(const SSL *ssl);" +.IP "const char *\fBSSL_get_cipher\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "const char *SSL_get_cipher(const SSL *ssl);" +.IP "int \fBSSL_get_cipher_bits\fR(const \s-1SSL\s0 *ssl, int *alg_bits);" 4 +.IX Item "int SSL_get_cipher_bits(const SSL *ssl, int *alg_bits);" +.IP "char *\fBSSL_get_cipher_list\fR(const \s-1SSL\s0 *ssl, int n);" 4 +.IX Item "char *SSL_get_cipher_list(const SSL *ssl, int n);" +.IP "char *\fBSSL_get_cipher_name\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_get_cipher_name(const SSL *ssl);" +.IP "char *\fBSSL_get_cipher_version\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_get_cipher_version(const SSL *ssl);" +.IP "\s-1STACK\s0 *\fBSSL_get_ciphers\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "STACK *SSL_get_ciphers(const SSL *ssl);" +.IP "\s-1STACK\s0 *\fBSSL_get_client_CA_list\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "STACK *SSL_get_client_CA_list(const SSL *ssl);" +.IP "\s-1SSL_CIPHER\s0 *\fBSSL_get_current_cipher\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "SSL_CIPHER *SSL_get_current_cipher(SSL *ssl);" +.IP "long \fBSSL_get_default_timeout\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_get_default_timeout(const SSL *ssl);" +.IP "int \fBSSL_get_error\fR(const \s-1SSL\s0 *ssl, int i);" 4 +.IX Item "int SSL_get_error(const SSL *ssl, int i);" +.IP "char *\fBSSL_get_ex_data\fR(const \s-1SSL\s0 *ssl, int idx);" 4 +.IX Item "char *SSL_get_ex_data(const SSL *ssl, int idx);" +.IP "int \fBSSL_get_ex_data_X509_STORE_CTX_idx\fR(void);" 4 +.IX Item "int SSL_get_ex_data_X509_STORE_CTX_idx(void);" +.IP "int \fBSSL_get_ex_new_index\fR(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" 4 +.IX Item "int SSL_get_ex_new_index(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))" +.IP "int \fBSSL_get_fd\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_fd(const SSL *ssl);" +.IP "void (*\fBSSL_get_info_callback\fR(const \s-1SSL\s0 *ssl);)()" 4 +.IX Item "void (*SSL_get_info_callback(const SSL *ssl);)()" +.IP "\s-1STACK\s0 *\fBSSL_get_peer_cert_chain\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "STACK *SSL_get_peer_cert_chain(const SSL *ssl);" +.IP "X509 *\fBSSL_get_peer_certificate\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "X509 *SSL_get_peer_certificate(const SSL *ssl);" +.IP "\s-1EVP_PKEY\s0 *\fBSSL_get_privatekey\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "EVP_PKEY *SSL_get_privatekey(const SSL *ssl);" +.IP "int \fBSSL_get_quiet_shutdown\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_quiet_shutdown(const SSL *ssl);" +.IP "\s-1BIO\s0 *\fBSSL_get_rbio\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "BIO *SSL_get_rbio(const SSL *ssl);" +.IP "int \fBSSL_get_read_ahead\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_read_ahead(const SSL *ssl);" +.IP "\s-1SSL_SESSION\s0 *\fBSSL_get_session\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "SSL_SESSION *SSL_get_session(const SSL *ssl);" +.IP "char *\fBSSL_get_shared_ciphers\fR(const \s-1SSL\s0 *ssl, char *buf, int len);" 4 +.IX Item "char *SSL_get_shared_ciphers(const SSL *ssl, char *buf, int len);" +.IP "int \fBSSL_get_shutdown\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_shutdown(const SSL *ssl);" +.IP "const \s-1SSL_METHOD\s0 *\fBSSL_get_ssl_method\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);" +.IP "int \fBSSL_get_state\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_state(const SSL *ssl);" +.IP "long \fBSSL_get_time\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_get_time(const SSL *ssl);" +.IP "long \fBSSL_get_timeout\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_get_timeout(const SSL *ssl);" +.IP "int (*\fBSSL_get_verify_callback\fR(const \s-1SSL\s0 *ssl))(int,X509_STORE_CTX *)" 4 +.IX Item "int (*SSL_get_verify_callback(const SSL *ssl))(int,X509_STORE_CTX *)" +.IP "int \fBSSL_get_verify_mode\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_get_verify_mode(const SSL *ssl);" +.IP "long \fBSSL_get_verify_result\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_get_verify_result(const SSL *ssl);" +.IP "char *\fBSSL_get_version\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_get_version(const SSL *ssl);" +.IP "\s-1BIO\s0 *\fBSSL_get_wbio\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "BIO *SSL_get_wbio(const SSL *ssl);" +.IP "int \fBSSL_in_accept_init\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_in_accept_init(SSL *ssl);" +.IP "int \fBSSL_in_before\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_in_before(SSL *ssl);" +.IP "int \fBSSL_in_connect_init\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_in_connect_init(SSL *ssl);" +.IP "int \fBSSL_in_init\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_in_init(SSL *ssl);" +.IP "int \fBSSL_is_init_finished\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_is_init_finished(SSL *ssl);" +.IP "\s-1STACK\s0 *\fBSSL_load_client_CA_file\fR(char *file);" 4 +.IX Item "STACK *SSL_load_client_CA_file(char *file);" +.IP "void \fBSSL_load_error_strings\fR(void);" 4 +.IX Item "void SSL_load_error_strings(void);" +.IP "\s-1SSL\s0 *\fBSSL_new\fR(\s-1SSL_CTX\s0 *ctx);" 4 +.IX Item "SSL *SSL_new(SSL_CTX *ctx);" +.IP "long \fBSSL_num_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_num_renegotiations(SSL *ssl);" +.IP "int \fBSSL_peek\fR(\s-1SSL\s0 *ssl, void *buf, int num);" 4 +.IX Item "int SSL_peek(SSL *ssl, void *buf, int num);" +.IP "int \fBSSL_pending\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_pending(const SSL *ssl);" +.IP "int \fBSSL_read\fR(\s-1SSL\s0 *ssl, void *buf, int num);" 4 +.IX Item "int SSL_read(SSL *ssl, void *buf, int num);" +.IP "int \fBSSL_renegotiate\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_renegotiate(SSL *ssl);" +.IP "char *\fBSSL_rstate_string\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_rstate_string(SSL *ssl);" +.IP "char *\fBSSL_rstate_string_long\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_rstate_string_long(SSL *ssl);" +.IP "long \fBSSL_session_reused\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_session_reused(SSL *ssl);" +.IP "void \fBSSL_set_accept_state\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "void SSL_set_accept_state(SSL *ssl);" +.IP "void \fBSSL_set_app_data\fR(\s-1SSL\s0 *ssl, char *arg);" 4 +.IX Item "void SSL_set_app_data(SSL *ssl, char *arg);" +.IP "void \fBSSL_set_bio\fR(\s-1SSL\s0 *ssl, \s-1BIO\s0 *rbio, \s-1BIO\s0 *wbio);" 4 +.IX Item "void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);" +.IP "int \fBSSL_set_cipher_list\fR(\s-1SSL\s0 *ssl, char *str);" 4 +.IX Item "int SSL_set_cipher_list(SSL *ssl, char *str);" +.IP "void \fBSSL_set_client_CA_list\fR(\s-1SSL\s0 *ssl, \s-1STACK\s0 *list);" 4 +.IX Item "void SSL_set_client_CA_list(SSL *ssl, STACK *list);" +.IP "void \fBSSL_set_connect_state\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "void SSL_set_connect_state(SSL *ssl);" +.IP "int \fBSSL_set_ex_data\fR(\s-1SSL\s0 *ssl, int idx, char *arg);" 4 +.IX Item "int SSL_set_ex_data(SSL *ssl, int idx, char *arg);" +.IP "int \fBSSL_set_fd\fR(\s-1SSL\s0 *ssl, int fd);" 4 +.IX Item "int SSL_set_fd(SSL *ssl, int fd);" +.IP "void \fBSSL_set_info_callback\fR(\s-1SSL\s0 *ssl, void (*cb);(void))" 4 +.IX Item "void SSL_set_info_callback(SSL *ssl, void (*cb);(void))" +.IP "void \fBSSL_set_msg_callback\fR(\s-1SSL\s0 *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, \s-1SSL\s0 *ssl, void *arg));" 4 +.IX Item "void SSL_set_msg_callback(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));" +.IP "void \fBSSL_set_msg_callback_arg\fR(\s-1SSL\s0 *ctx, void *arg);" 4 +.IX Item "void SSL_set_msg_callback_arg(SSL *ctx, void *arg);" +.IP "void \fBSSL_set_options\fR(\s-1SSL\s0 *ssl, unsigned long op);" 4 +.IX Item "void SSL_set_options(SSL *ssl, unsigned long op);" +.IP "void \fBSSL_set_quiet_shutdown\fR(\s-1SSL\s0 *ssl, int mode);" 4 +.IX Item "void SSL_set_quiet_shutdown(SSL *ssl, int mode);" +.IP "void \fBSSL_set_read_ahead\fR(\s-1SSL\s0 *ssl, int yes);" 4 +.IX Item "void SSL_set_read_ahead(SSL *ssl, int yes);" +.IP "int \fBSSL_set_rfd\fR(\s-1SSL\s0 *ssl, int fd);" 4 +.IX Item "int SSL_set_rfd(SSL *ssl, int fd);" +.IP "int \fBSSL_set_session\fR(\s-1SSL\s0 *ssl, \s-1SSL_SESSION\s0 *session);" 4 +.IX Item "int SSL_set_session(SSL *ssl, SSL_SESSION *session);" +.IP "void \fBSSL_set_shutdown\fR(\s-1SSL\s0 *ssl, int mode);" 4 +.IX Item "void SSL_set_shutdown(SSL *ssl, int mode);" +.IP "int \fBSSL_set_ssl_method\fR(\s-1SSL\s0 *ssl, const \s-1SSL_METHOD\s0 *meth);" 4 +.IX Item "int SSL_set_ssl_method(SSL *ssl, const SSL_METHOD *meth);" +.IP "void \fBSSL_set_time\fR(\s-1SSL\s0 *ssl, long t);" 4 +.IX Item "void SSL_set_time(SSL *ssl, long t);" +.IP "void \fBSSL_set_timeout\fR(\s-1SSL\s0 *ssl, long t);" 4 +.IX Item "void SSL_set_timeout(SSL *ssl, long t);" +.IP "void \fBSSL_set_verify\fR(\s-1SSL\s0 *ssl, int mode, int (*callback);(void))" 4 +.IX Item "void SSL_set_verify(SSL *ssl, int mode, int (*callback);(void))" +.IP "void \fBSSL_set_verify_result\fR(\s-1SSL\s0 *ssl, long arg);" 4 +.IX Item "void SSL_set_verify_result(SSL *ssl, long arg);" +.IP "int \fBSSL_set_wfd\fR(\s-1SSL\s0 *ssl, int fd);" 4 +.IX Item "int SSL_set_wfd(SSL *ssl, int fd);" +.IP "int \fBSSL_shutdown\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_shutdown(SSL *ssl);" +.IP "int \fBSSL_state\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_state(const SSL *ssl);" +.IP "char *\fBSSL_state_string\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_state_string(const SSL *ssl);" +.IP "char *\fBSSL_state_string_long\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "char *SSL_state_string_long(const SSL *ssl);" +.IP "long \fBSSL_total_renegotiations\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "long SSL_total_renegotiations(SSL *ssl);" +.IP "int \fBSSL_use_PrivateKey\fR(\s-1SSL\s0 *ssl, \s-1EVP_PKEY\s0 *pkey);" 4 +.IX Item "int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);" +.IP "int \fBSSL_use_PrivateKey_ASN1\fR(int type, \s-1SSL\s0 *ssl, unsigned char *d, long len);" 4 +.IX Item "int SSL_use_PrivateKey_ASN1(int type, SSL *ssl, unsigned char *d, long len);" +.IP "int \fBSSL_use_PrivateKey_file\fR(\s-1SSL\s0 *ssl, char *file, int type);" 4 +.IX Item "int SSL_use_PrivateKey_file(SSL *ssl, char *file, int type);" +.IP "int \fBSSL_use_RSAPrivateKey\fR(\s-1SSL\s0 *ssl, \s-1RSA\s0 *rsa);" 4 +.IX Item "int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);" +.IP "int \fBSSL_use_RSAPrivateKey_ASN1\fR(\s-1SSL\s0 *ssl, unsigned char *d, long len);" 4 +.IX Item "int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);" +.IP "int \fBSSL_use_RSAPrivateKey_file\fR(\s-1SSL\s0 *ssl, char *file, int type);" 4 +.IX Item "int SSL_use_RSAPrivateKey_file(SSL *ssl, char *file, int type);" +.IP "int \fBSSL_use_certificate\fR(\s-1SSL\s0 *ssl, X509 *x);" 4 +.IX Item "int SSL_use_certificate(SSL *ssl, X509 *x);" +.IP "int \fBSSL_use_certificate_ASN1\fR(\s-1SSL\s0 *ssl, int len, unsigned char *d);" 4 +.IX Item "int SSL_use_certificate_ASN1(SSL *ssl, int len, unsigned char *d);" +.IP "int \fBSSL_use_certificate_file\fR(\s-1SSL\s0 *ssl, char *file, int type);" 4 +.IX Item "int SSL_use_certificate_file(SSL *ssl, char *file, int type);" +.IP "int \fBSSL_version\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_version(const SSL *ssl);" +.IP "int \fBSSL_want\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_want(const SSL *ssl);" +.IP "int \fBSSL_want_nothing\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_want_nothing(const SSL *ssl);" +.IP "int \fBSSL_want_read\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_want_read(const SSL *ssl);" +.IP "int \fBSSL_want_write\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_want_write(const SSL *ssl);" +.IP "int \fBSSL_want_x509_lookup\fR(const \s-1SSL\s0 *ssl);" 4 +.IX Item "int SSL_want_x509_lookup(const SSL *ssl);" +.IP "int \fBSSL_write\fR(\s-1SSL\s0 *ssl, const void *buf, int num);" 4 +.IX Item "int SSL_write(SSL *ssl, const void *buf, int num);" +.IP "void \fBSSL_set_psk_client_callback\fR(\s-1SSL\s0 *ssl, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" 4 +.IX Item "void SSL_set_psk_client_callback(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));" +.IP "int \fBSSL_use_psk_identity_hint\fR(\s-1SSL\s0 *ssl, const char *hint);" 4 +.IX Item "int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);" +.IP "void \fBSSL_set_psk_server_callback\fR(\s-1SSL\s0 *ssl, unsigned int (*callback)(\s-1SSL\s0 *ssl, const char *identity, unsigned char *psk, int max_psk_len));" 4 +.IX Item "void SSL_set_psk_server_callback(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));" +.IP "const char *\fBSSL_get_psk_identity_hint\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "const char *SSL_get_psk_identity_hint(SSL *ssl);" +.IP "const char *\fBSSL_get_psk_identity\fR(\s-1SSL\s0 *ssl);" 4 +.IX Item "const char *SSL_get_psk_identity(SSL *ssl);" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIopenssl\fR\|(1), \fIcrypto\fR\|(3), +\&\fISSL_accept\fR\|(3), \fISSL_clear\fR\|(3), +\&\fISSL_connect\fR\|(3), +\&\fISSL_CIPHER_get_name\fR\|(3), +\&\fISSL_COMP_add_compression_method\fR\|(3), +\&\fISSL_CTX_add_extra_chain_cert\fR\|(3), +\&\fISSL_CTX_add_session\fR\|(3), +\&\fISSL_CTX_ctrl\fR\|(3), +\&\fISSL_CTX_flush_sessions\fR\|(3), +\&\fISSL_CTX_get_ex_new_index\fR\|(3), +\&\fISSL_CTX_get_verify_mode\fR\|(3), +\&\fISSL_CTX_load_verify_locations\fR\|(3) +\&\fISSL_CTX_new\fR\|(3), +\&\fISSL_CTX_sess_number\fR\|(3), +\&\fISSL_CTX_sess_set_cache_size\fR\|(3), +\&\fISSL_CTX_sess_set_get_cb\fR\|(3), +\&\fISSL_CTX_sessions\fR\|(3), +\&\fISSL_CTX_set_cert_store\fR\|(3), +\&\fISSL_CTX_set_cert_verify_callback\fR\|(3), +\&\fISSL_CTX_set_cipher_list\fR\|(3), +\&\fISSL_CTX_set_client_CA_list\fR\|(3), +\&\fISSL_CTX_set_client_cert_cb\fR\|(3), +\&\fISSL_CTX_set_default_passwd_cb\fR\|(3), +\&\fISSL_CTX_set_generate_session_id\fR\|(3), +\&\fISSL_CTX_set_info_callback\fR\|(3), +\&\fISSL_CTX_set_max_cert_list\fR\|(3), +\&\fISSL_CTX_set_mode\fR\|(3), +\&\fISSL_CTX_set_msg_callback\fR\|(3), +\&\fISSL_CTX_set_options\fR\|(3), +\&\fISSL_CTX_set_quiet_shutdown\fR\|(3), +\&\fISSL_CTX_set_read_ahead\fR\|(3), +\&\fISSL_CTX_set_session_cache_mode\fR\|(3), +\&\fISSL_CTX_set_session_id_context\fR\|(3), +\&\fISSL_CTX_set_ssl_version\fR\|(3), +\&\fISSL_CTX_set_timeout\fR\|(3), +\&\fISSL_CTX_set_tmp_rsa_callback\fR\|(3), +\&\fISSL_CTX_set_tmp_dh_callback\fR\|(3), +\&\fISSL_CTX_set_verify\fR\|(3), +\&\fISSL_CTX_use_certificate\fR\|(3), +\&\fISSL_alert_type_string\fR\|(3), +\&\fISSL_do_handshake\fR\|(3), +\&\fISSL_get_SSL_CTX\fR\|(3), +\&\fISSL_get_ciphers\fR\|(3), +\&\fISSL_get_client_CA_list\fR\|(3), +\&\fISSL_get_default_timeout\fR\|(3), +\&\fISSL_get_error\fR\|(3), +\&\fISSL_get_ex_data_X509_STORE_CTX_idx\fR\|(3), +\&\fISSL_get_ex_new_index\fR\|(3), +\&\fISSL_get_fd\fR\|(3), +\&\fISSL_get_peer_cert_chain\fR\|(3), +\&\fISSL_get_rbio\fR\|(3), +\&\fISSL_get_session\fR\|(3), +\&\fISSL_get_verify_result\fR\|(3), +\&\fISSL_get_version\fR\|(3), +\&\fISSL_library_init\fR\|(3), +\&\fISSL_load_client_CA_file\fR\|(3), +\&\fISSL_new\fR\|(3), +\&\fISSL_pending\fR\|(3), +\&\fISSL_read\fR\|(3), +\&\fISSL_rstate_string\fR\|(3), +\&\fISSL_session_reused\fR\|(3), +\&\fISSL_set_bio\fR\|(3), +\&\fISSL_set_connect_state\fR\|(3), +\&\fISSL_set_fd\fR\|(3), +\&\fISSL_set_session\fR\|(3), +\&\fISSL_set_shutdown\fR\|(3), +\&\fISSL_shutdown\fR\|(3), +\&\fISSL_state_string\fR\|(3), +\&\fISSL_want\fR\|(3), +\&\fISSL_write\fR\|(3), +\&\fISSL_SESSION_free\fR\|(3), +\&\fISSL_SESSION_get_ex_new_index\fR\|(3), +\&\fISSL_SESSION_get_time\fR\|(3), +\&\fId2i_SSL_SESSION\fR\|(3), +\&\fISSL_CTX_set_psk_client_callback\fR\|(3), +\&\fISSL_CTX_use_psk_identity_hint\fR\|(3), +\&\fISSL_get_psk_identity\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +The \fIssl\fR\|(3) document appeared in OpenSSL 0.9.2 diff --git a/static/netbsd/man3/ssp.3 b/static/netbsd/man3/ssp.3 new file mode 100644 index 00000000..b7ffbaf9 --- /dev/null +++ b/static/netbsd/man3/ssp.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: ssp.3,v 1.9 2015/12/03 13:11:45 christos Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd December 3, 2015 +.Dt SSP 3 +.Os +.Sh NAME +.Nm ssp +.Nd bounds checked libc functions +.Sh LIBRARY +.Lb libssp +.Sh SYNOPSIS +.In ssp/stdio.h +.Ft int +.Fn sprintf "char *str" "const char *fmt" "..." +.Ft int +.Fn vsprintf "char *str" "const char *fmt" "va_list ap" +.Ft int +.Fn snprintf "char *str" "size_t len" "const char *fmt" "..." +.Ft int +.Fn vsnprintf "char *str" "size_t len" "const char *fmt" "va_list ap" +.Ft char * +.Fn gets "char *str" +.Ft char * +.Fn fgets "char *str" "int len" "FILE *fp" +.In ssp/string.h +.Ft void * +.Fn memcpy "void *str" "const void *ptr" "size_t len" +.Ft void * +.Fn memmove "void *str" "const void *ptr" "size_t len" +.Ft void * +.Fn memset "void *str" "int val" "size_t len" +.Ft char * +.Fn stpcpy "char *str" "const char *ptr" +.Ft char * +.Fn strcpy "char *str" "const char *ptr" +.Ft char * +.Fn strcat "char *str" "const char *ptr" +.Ft char * +.Fn strncpy "char *str" "const char *ptr" "size_t len" +.Ft char * +.Fn strncat "char *str" "const char *ptr" "size_t len" +.In ssp/strings.h +.Ft void * +.Fn bcopy "const void *ptr" "void *str" "size_t len" +.Ft void * +.Fn bzero "void *str" "size_t len" +.In ssp/unistd.h +.Ft ssize_t +.Fn read "int fd" "void *str" "size_t len" +.Ft int +.Fn readlink "const char * restrict path" "char * restrict str" "size_t len" +.Ft int +.Fn getcwd "char *str" "size_t len" +.Sh DESCRIPTION +When +.Dv _FORTIFY_SOURCE +bounds checking is enabled as described below, the above functions get +overwritten to use the +.Xr __builtin_object_size 3 +function to compute the size of +.Fa str , +if known at compile time, +and perform bounds check on it in order +to avoid data buffer or stack buffer overflows. +If an overflow is detected, the routines will call +.Xr abort 3 . +.Pp +To enable these function overrides the following should be added to the +.Xr gcc 1 +command line: +.Dq \-D_FORTIFY_SOURCE=1 +or +.Dq \-D_FORTIFY_SOURCE=2 . +.Pp +If +.Dv _FORTIFY_SOURCE is set to +.Dv 1 +the code will compute the maximum possible buffer size for +.Fa str , +and if set to +.Dv 2 +it will compute the minimum buffer size. +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __builtin_object_size 3 , +.Xr stdio 3 , +.Xr string 3 , +.Xr security 7 +.Sh HISTORY +The +.Nm ssp +library appeared +.Nx 4.0 . diff --git a/static/netbsd/man3/stat_flags.3 b/static/netbsd/man3/stat_flags.3 new file mode 100644 index 00000000..5286bafd --- /dev/null +++ b/static/netbsd/man3/stat_flags.3 @@ -0,0 +1,172 @@ +.\" $NetBSD: stat_flags.3,v 1.9 2023/05/31 21:49:39 uwe Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 31, 2023 +.Dt STAT_FLAGS 3 +.Os +.Sh NAME +.Nm string_to_flags , +.Nm flags_to_string +.Nd Stat flags parsing and printing functions +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft char * +.Fn flags_to_string "u_long flags" "const char *def" +.Ft int +.Fn string_to_flags "char **stringp" "u_long *setp" "u_long *clrp" +.Sh DESCRIPTION +The +.Fn flags_to_string +and +.Fn string_to_flags +functions are used by +programs such as +.Xr chflags 1 , +.Xr ls 1 , +.Xr makefs 8 , +.Xr mtree 8 , +etc., to parse and/or print the +.Fa st_flags +field in the +.Xr stat 2 +structure. +. +.Pp +They recognize the following flags: +. +.Bl -tag -width Cm -offset indent +. +.It Cm arch , Cm archived Pq Dv SF_ARCHIVED +file is archived +.Po legacy/compat flag for +.Xr mount_msdos 8 +filesystems +.Pc +. +.It Cm nodump Pq Dv UF_NODUMP +do not +.Xr dump 8 +file +. +.It Cm opaque Pq Dv UF_OPAQUE +directory is opaque in +.Xr mount_union 8 +filesystems +. +.It Cm sappnd , Cm sappend Pq Dv SF_APPEND +writes to the file may only append +.Pq flag can be changed by the superuser only +. +.It Cm schg , Cm schange , Cm simmutable Pq Dv SF_IMMUTABLE +file cannot be changed; it is immutable +.Pq flag can be changed by the superuser only +. +.It Cm snap Pq Dv SF_SNAPSHOT +file is an +.Xr fss 4 +snapshot inode +. +.It Cm uappnd , Cm uappend Pq Dv UF_APPEND +writes to the file may only append +. +.It Cm uchg , Cm uchange , Cm uimmutable Pq Dv UF_IMMUTABLE +file cannot be changed; it is immutable +. +.El +. +.Pp +The +.Fn flags_to_string +function converts the bits set in the +.Fa flags +argument to a comma-separated string and returns it. +If no flags are set, then the +.Fa def +string is returned. +The returned string is allocated via +.Xr malloc 3 +and it is the responsibility of the caller to +.Xr free 3 +it. +.Pp +Where the above list has several flag names for a flag, +the first of the listed names is returned. +. +.Pp +The +.Fn string_to_flags +function takes a +.Fa stringp +of space, comma, or tab separated flag names +and places their bit value on the +.Fa setp +argument. +.Pp +If the flag name is prefixed by +.Ql no , +then the bit value is placed on the +.Fa clrp +argument. +Both +.Cm nonodump +and +.Cm dump +are recognized as negative forms of the +.Cm nodump +flag name. +.Pp +Where the above list has several flag names for a flag, +all of them are recognized. +The +.Cm snap +flag name is +.Em not +recognized +.Pq as its flag cannot be changed anyway . +. +.Sh RETURN VALUES +.Fn flags_to_string +returns the symbolic representation of flags, the default string, or +.Dv NULL +if allocation failed. +. +.Pp +.Fn string_to_flags +returns +.Dv 0 +on success and +.Dv 1 +if it fails to parse the string, setting +.Fa stringp +to point to the first name that it failed to parse. +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 diff --git a/static/netbsd/man3/stdio.3 b/static/netbsd/man3/stdio.3 new file mode 100644 index 00000000..7c206bc7 --- /dev/null +++ b/static/netbsd/man3/stdio.3 @@ -0,0 +1,347 @@ +.\" $NetBSD: stdio.3,v 1.28 2020/08/29 15:25:57 rillig Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 +.\" +.Dd August 29, 2020 +.Dt STDIO 3 +.Os +.Sh NAME +.Nm stdio +.Nd standard input/output library functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Vt FILE *stdin; +.Vt FILE *stdout; +.Vt FILE *stderr; +.Sh DESCRIPTION +The standard +.Tn I/O +library provides a simple and efficient buffered stream +.Tn I/O +interface. +Input and output is mapped into logical data streams +and the physical +.Tn I/O +characteristics are concealed. +.Pp +A stream is associated with an external file (which may be a physical +device) by +.Em opening +a file, which may involve creating a new file. +Creating an existing file causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, as opposed +to a terminal) then a +.Em file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. +If append mode is used, the position indicator is placed at the end-of-file. +The position indicator is maintained by subsequent reads, writes +and positioning requests. +All input occurs as if the characters were read by successive calls to the +.Xr fgetc 3 +function; all output takes place as if all characters were +written by successive calls to the +.Xr fputc 3 +function. +.Pp +A file is disassociated from a stream by +.Em closing +the file. +Output streams are flushed (any unwritten buffer contents are transferred +to the host environment) before the stream is disassociated from the file. +The value of a pointer to a +.Dv FILE +object is indeterminate after a file is closed (garbage). +.Pp +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be repositioned +at the start). +If the main function returns to its original caller, or the +.Xr exit 3 +function is called, all open files are closed (hence all output +streams are flushed) before program termination. +Other methods of program termination, such as +.Xr abort 3 +do not bother about closing files properly. +.Pp +This implementation needs and makes +no distinction between +.Dq text +and +.Dq binary +streams. +In effect, all streams are binary. +No translation is performed and no extra padding appears on any stream. +.Pp +At program startup, three streams are predefined and need not be +opened explicitly: +.Bl -enum -offset indent +.It +.Em standard input +for reading conventional input, +.It +.Em standard output +for writing conventional output, and +.It +.Em standard error +for writing diagnostic output. +.El +.Pp +These streams are abbreviated +.Em stdin , +.Em stdout , +and +.Em stderr . +.Pp +Initially, the standard error stream +is unbuffered; the standard input and output streams are +fully buffered if and only if the streams do not refer to +an interactive or +.Dq terminal +device, as determined by the +.Xr isatty 3 +function. +In fact, +.Em all +freshly-opened streams that refer to terminal devices +default to line buffering, and +pending output to such streams is written automatically +whenever such an input stream is read. +Note that this applies only to +.Dq "true reads" ; +if the read request can be satisfied by existing buffered data, +no automatic flush will occur. +In these cases, +or when a large amount of computation is done after printing +part of a line on an output terminal, it is necessary to +.Xr fflush 3 +the standard output before going off and computing so that the output +will appear. +Alternatively, these defaults may be modified via the +.Xr setvbuf 3 +function. +.Sh IMPLEMENTATION NOTES +In multi-threaded applications, operations on streams perform implicit +locking, except for the +.Fn getc_unlocked , +.Fn getchar_unlocked , +.Fn putc_unlocked , +and +.Fn putchar_unlocked +functions. +Explicit control of stream locking is available through the +.Fn flockfile , +.Fn ftrylockfile , +and +.Fn funlockfile +functions . +.Pp +The following are defined as macros; these names may not be re-used +without first removing their current definitions with +.Dv #undef : +.Dv BUFSIZ , +.Dv EOF , +.Dv FILENAME_MAX , +.Dv FOPEN_MAX , +.Dv L_cuserid , +.Dv L_ctermid , +.Dv L_tmpnam , +.Dv NULL , +.Dv SEEK_END , +.Dv SEEK_SET , +.Dv SEE_CUR , +.Dv TMP_MAX , +.Fn clearerr , +.Fn feof , +.Fn ferror , +.Fn fileno , +.Fn freopen , +.Fn fwopen , +.Fn getc , +.Fn getc_unlocked , +.Fn getchar , +.Fn getchar_unlocked , +.Fn putc , +.Fn putc_unlocked , +.Fn putchar , +.Fn putchar_unlocked , +.Dv stderr , +.Dv stdin , +.Dv stdout . +.Pp +Function versions of the macro functions +.Fn feof , +.Fn ferror , +.Fn clearerr , +.Fn fileno , +.Fn getc , +.Fn getc_unlocked , +.Fn getchar , +.Fn getchar_unlocked , +.Fn putc , +.Fn putc_unlocked , +.Fn putchar , +and +.Fn putchar_unlocked +exist and will be used if the macros definitions are explicitly removed. +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 +.Sh STANDARDS +The +.Nm +library conforms to +.St -ansiC . +.Sh LIST OF FUNCTIONS +.Bl -column "putchar_unlocked" "Description" +.It Sy Function Description +.It asprintf formatted output conversion with allocation +.It asprintf_l formatted output conversion with allocation +.It clearerr check and reset stream status +.It dprintf formatted output conversion +.It dprintf_l formatted output conversion +.It fclose close a stream +.It fdopen stream open functions +.It feof check and reset stream status +.It ferror check and reset stream status +.It fflush flush a stream +.It fgetc get next character or word from input stream +.It fgetln get a line from a stream +.It fgetpos reposition a stream +.It fgets get a line from a stream +.It fgetwc get next wide character from input stream +.It fileno check and reset stream status +.It flockfile lock a stream +.It fmemopen open a stream that points to a memory buffer +.It fopen stream open functions +.It fprintf formatted output conversion +.It fprintf_l formatted output conversion +.It fpurge flush a stream +.It fputc output a character or word to a stream +.It fputs output a line to a stream +.It fputwc output a wide character to a stream +.It fread binary stream input/output +.It freopen stream open functions +.It fropen open a stream +.It fscanf input format conversion +.It fscanf_l input format conversion +.It fseek reposition a stream +.It fseeko reposition a stream +.It fsetpos reposition a stream +.It ftell reposition a stream +.It ftello reposition a stream +.It ftrylockfile lock a stream (non-blocking) +.It funlockfile unlock a stream +.It funopen open a stream +.It funopen2 open a stream, with flush support +.It fwide set/get orientation of a stream +.It fwopen open a stream +.It fwrite binary stream input/output +.It getc get next character or word from input stream +.It getc_unlocked get next character or word from input stream +.It Ta (no implicit locking) +.It getchar get next character or word from input stream +.It getchar_unlocked get next character or word from input stream +.It Ta (no implicit locking) +.It getdelim get a delimited record from a stream +.It getline get a line from a stream +.It gets get a line from a stream +.It getw get next character or word from input stream +.It getwc get next wide character from input stream +.It getwchar get next wide character from input stream +.It mkstemp create unique temporary file +.It mktemp create unique temporary file +.It open_memstream open memory as a stream +.It popen open a program as a stream +.It popenve open a program as a stream +.It pclose close an opened program stream +.It perror system error messages +.It printf formatted output conversion +.It printf_l formatted output conversion +.It putc output a character or word to a stream +.It putc_unlocked output a character or word to a stream +.It Ta (no implicit locking) +.It putchar output a character or word to a stream +.It putchar_unlocked output a character or word to a stream +.It Ta (no implicit locking) +.It puts output a line to a stream +.It putw output a character or word to a stream +.It putwc output a wide character to a stream +.It putwchar output a wide character to a stream +.It remove remove directory entry +.It rewind reposition a stream +.It scanf input format conversion +.It scanf_l input format conversion +.It setbuf stream buffering operations +.It setbuffer stream buffering operations +.It setlinebuf stream buffering operations +.It setvbuf stream buffering operations +.It snprintf formatted output conversion +.It snprintf_l formatted output conversion +.It sprintf formatted output conversion +.It sscanf input format conversion +.It sscanf_l input format conversion +.It strerror system error messages +.It sys_errlist system error messages +.It sys_nerr system error messages +.It tempnam temporary file routines +.It tmpfile temporary file routines +.It tmpnam temporary file routines +.It ungetc un-get character from input stream +.It ungetwc un-get wide character from input stream +.It vasprintf formatted output conversion with allocation +.It vasprintf_l formatted output conversion with allocation +.It vdprintf formatted output conversion +.It vdprintf_l formatted output conversion +.It vfprintf formatted output conversion +.It vfprintf_l formatted output conversion +.It vfscanf input format conversion +.It vfscanf_l input format conversion +.It vprintf formatted output conversion +.It vprintf_l formatted output conversion +.It vscanf input format conversion +.It vscanf_l input format conversion +.It vsnprintf formatted output conversion +.It vsnprintf_l formatted output conversion +.It vsprintf formatted output conversion +.It vsprintf_l formatted output conversion +.It vsscanf input format conversion +.It vsscanf_l input format conversion +.El +.Sh BUGS +The standard buffered functions do not interact well with certain other +library and system functions, especially +.Xr vfork 2 +and +.Xr abort 3 . diff --git a/static/netbsd/man3/strcasecmp.3 b/static/netbsd/man3/strcasecmp.3 new file mode 100644 index 00000000..0aa713ab --- /dev/null +++ b/static/netbsd/man3/strcasecmp.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcasecmp.3 8.1 (Berkeley) 6/9/93 +.\" $NetBSD: strcasecmp.3,v 1.21 2016/07/13 09:05:16 abhinav Exp $ +.\" +.Dd July 11, 2016 +.Dt STRCASECMP 3 +.Os +.Sh NAME +.Nm strcasecmp , +.Nm strncasecmp +.Nd compare strings, ignoring case +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fn strcasecmp "const char *s1" "const char *s2" +.Ft int +.Fn strncasecmp "const char *s1" "const char *s2" "size_t len" +.Sh DESCRIPTION +The +.Fn strcasecmp +and +.Fn strncasecmp +functions +compare the nul-terminated strings +.Fa s1 +and +.Fa s2 +and return an integer greater than, equal to, or less than 0, +according to whether +.Fa s1 +is lexicographically greater than, equal to, or less than +.Fa s2 +after translation of each corresponding character to lower-case. +The strings themselves are not modified. +The comparison is done using unsigned characters, so that +.Sq Li \e200 +is greater than +.Ql \e0 . +.Pp +The +.Fn strncasecmp +function +compares at most +.Fa len +characters. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn strcasecmp +and +.Fn strncasecmp +functions conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn strcasecmp +and +.Fn strncasecmp +functions first appeared in +.Bx 4.4 . +.Sh NOTES +If +.Fa len +is 0 +.Fn strncasecmp +always returns 0. diff --git a/static/netbsd/man3/strcat.3 b/static/netbsd/man3/strcat.3 new file mode 100644 index 00000000..046b2ee7 --- /dev/null +++ b/static/netbsd/man3/strcat.3 @@ -0,0 +1,138 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcat.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strcat.3,v 1.16 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd August 11, 2002 +.Dt STRCAT 3 +.Os +.Sh NAME +.Nm strcat , +.Nm strncat +.Nd concatenate strings +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strcat "char * restrict s" "const char * restrict append" +.Ft char * +.Fn strncat "char * restrict s" "const char * restrict append" "size_t count" +.Sh DESCRIPTION +The +.Fn strcat +and +.Fn strncat +functions +append a copy of the nul-terminated string +.Fa append +to the end of the nul-terminated string +.Fa s , +then add a terminating +.Ql \e0 . +The string +.Fa s +must have sufficient space to hold the result. +.Pp +The +.Fn strncat +function +appends not more than +.Fa count +characters where space for the terminating +.Ql \e0 +should not be included in +.Fa count . +.Sh RETURN VALUES +The +.Fn strcat +and +.Fn strncat +functions +return the pointer +.Fa s . +.Sh EXAMPLES +The following appends +.Dq Li abc +to +.Dq Li chararray : +.Bd -literal -offset indent +char *letters = "abcdefghi"; + +(void)strncat(chararray, letters, 3); +.Ed +.Pp +The following example shows how to use +.Fn strncat +safely in conjunction with +.Xr strncpy 3 . +.Bd -literal -offset indent +char buf[BUFSIZ]; +char *input, *suffix; + +(void)strncpy(buf, input, sizeof(buf) - 1); +buf[sizeof(buf) - 1] = '\e0'; +(void)strncat(buf, suffix, sizeof(buf) - 1 - strlen(buf)); +.Ed +.Pp +The above will copy as many characters from +.Dq Li input +to +.Dq Li buf +as will fit. +It then appends as many characters from suffix as will fit (or none +if there is no space). +For operations like this, the +.Xr strlcpy 3 +and +.Xr strlcat 3 +functions are a better choice, as shown below. +.Bd -literal -offset indent +(void)strlcpy(buf, input, sizeof(buf)); +(void)strlcat(buf, suffix, sizeof(buf)); +.Ed +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strlcat 3 , +.Xr strlcpy 3 +.Sh STANDARDS +The +.Fn strcat +and +.Fn strncat +functions +conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/strchr.3 b/static/netbsd/man3/strchr.3 new file mode 100644 index 00000000..9bd71451 --- /dev/null +++ b/static/netbsd/man3/strchr.3 @@ -0,0 +1,118 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strchr.3 8.2 (Berkeley) 4/19/94 +.\" $NetBSD: strchr.3,v 1.15 2023/01/31 01:42:32 simonb Exp $ +.\" +.Dd November 27, 2020 +.Dt STRCHR 3 +.Os +.Sh NAME +.Nm strchr, strchrnul +.Nd locate character in string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strchr "const char *s" "int c" +.Ft char * +.Fn strchrnul "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn strchr +and +.Fn strchrnul +functions locate the first occurrence of +.Ar c +in the string pointed to by +.Ar s . +The terminating +.Dv NUL +character is considered part of the string. +If +.Fa c +is +.Ql \e0 , +.Fn strchr +and +.Fn strchrnul +locate the terminating +.Ql \e0 . +.Sh RETURN VALUES +The function +.Fn strchr +returns a pointer to the located character, or +.Dv NULL +if the character does not appear in the string. +The function +.Fn strchrnul +returns a pointer to the located character, or +a pointer to the +.Dv NUL +terminating character of the string if the character does not appear +in the string. +.Sh EXAMPLES +After the following call to +.Fn strchr , +.Va p +will point to the string +.Qq oobar : +.Bd -literal -offset indent +char *p; +char *s = "foobar"; + +p = strchr(s, 'o'); +.Ed +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strchr +function +conforms to +.St -ansiC . +.Sh HISTORY +The +.Fn strchrnul +first appeared in glibc 2.1.1 and was added to +.Fx 10 +and +.Nx 8 . diff --git a/static/netbsd/man3/strcmp.3 b/static/netbsd/man3/strcmp.3 new file mode 100644 index 00000000..9afa0a47 --- /dev/null +++ b/static/netbsd/man3/strcmp.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcmp.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strcmp.3,v 1.14 2016/07/14 17:09:03 abhinav Exp $ +.\" +.Dd June 4, 1993 +.Dt STRCMP 3 +.Os +.Sh NAME +.Nm strcmp , +.Nm strncmp +.Nd compare strings +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn strcmp "const char *s1" "const char *s2" +.Ft int +.Fn strncmp "const char *s1" "const char *s2" "size_t len" +.Sh DESCRIPTION +The +.Fn strcmp +and +.Fn strncmp +functions +lexicographically compare the nul-terminated strings +.Fa s1 +and +.Fa s2 . +.Sh RETURN VALUES +The +.Fn strcmp +and +.Fn strncmp +functions return an integer greater than, equal to, or less than 0, according +to whether the string +.Fa s1 +is greater than, equal to, or less than the string +.Fa s2 . +The comparison is done using unsigned characters, so that +.Ql \e200 +is greater than +.Ql \e0 . +.Pp +The +.Fn strncmp +function compares not more than +.Fa len +characters. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 , +.Xr strcasecmp 3 , +.Xr strcoll 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn strcmp +and +.Fn strncmp +functions +conform to +.St -ansiC . +.Sh NOTES +If +.Fa len +is 0, +.Fn strncmp +always returns 0. diff --git a/static/netbsd/man3/strcoll.3 b/static/netbsd/man3/strcoll.3 new file mode 100644 index 00000000..79cfb138 --- /dev/null +++ b/static/netbsd/man3/strcoll.3 @@ -0,0 +1,73 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcoll.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strcoll.3,v 1.10 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd June 4, 1993 +.Dt STRCOLL 3 +.Os +.Sh NAME +.Nm strcoll +.Nd compare strings according to current collation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn strcoll "const char *s1" "const char *s2" +.Sh DESCRIPTION +The +.Fn strcoll +function +lexicographically compares the nul-terminated strings +.Fa s1 +and +.Fa s2 +according to the current locale collation +and returns an integer greater than, equal to, or less than 0, +according to whether +.Fa s1 +is greater than, equal to, or less than +.Fa s2 . +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 , +.Xr setlocale 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn strcoll +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/strcpy.3 b/static/netbsd/man3/strcpy.3 new file mode 100644 index 00000000..b6a54ee4 --- /dev/null +++ b/static/netbsd/man3/strcpy.3 @@ -0,0 +1,152 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcpy.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strcpy.3,v 1.27 2023/08/11 21:17:16 riastradh Exp $ +.\" +.Dd August 11, 2023 +.Dt STRCPY 3 +.Os +.Sh NAME +.Nm stpcpy , +.Nm strcpy +.Nd copy strings +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn stpcpy "char * restrict dst" "const char * restrict src" +.Ft char * +.Fn strcpy "char * restrict dst" "const char * restrict src" +.Sh DESCRIPTION +The +.Fn stpcpy +and +.Fn strcpy +functions +copy the string +.Fa src +to +.Fa dst , +including the terminating +.Tn NUL +byte. +.Pp +The strings +.Fa src +and +.Fa dst +may not overlap. +The string +.Fa src +must be terminated by a +.Tn NUL +byte. +The memory for +.Fa dst +must have space for +.Fn strlen src Li "+ 1" +bytes. +.Sh RETURN VALUES +The +.Fn strcpy +function returns +.Fa dst . +.Pp +The +.Fn stpcpy +function returns a pointer to the terminating +.Tn NUL +byte of +.Fa dst . +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strlcpy 3 , +.Xr strncpy 3 , +.Xr wcscpy 3 +.Sh STANDARDS +The +.Fn strcpy +function conforms to +.St -isoC-99 . +.Pp +The +.Fn stpcpy +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn stpcpy +function first appeared in +.Nx 6.0 . +.Sh SECURITY CONSIDERATIONS +The +.Fn strcpy +and +.Fn stpcpy +functions copy until a +.Tn NUL +terminator without any bounds checks on the size of the input or output +buffers. +If the input buffer is missing a +.Tn NUL +terminator, or the input string is longer than the output buffer, this +can lead to crashes or security vulnerabilities from buffer overruns, +including disclosure of secrets in memory and arbitrary code +execution. +.Pp +The +.Xr strlcpy 3 +function is a safer replacement for +.Fn strcpy +which allows the caller to specify the space allocated for +.Fa dst . +.Xr strlcpy 3 , +or +.Xr snprintf 3 +with a format string of +.Li \*q%s\*q , +should be used instead of +.Fn strcpy +and +.Fn stpcpy +wherever possible to avoid buffer overruns in +.Fa dst . +.Po +However, they still require +.Fa src +to be +.Tn NUL Ns -terminated . +.Pc diff --git a/static/netbsd/man3/strcspn.3 b/static/netbsd/man3/strcspn.3 new file mode 100644 index 00000000..3f530150 --- /dev/null +++ b/static/netbsd/man3/strcspn.3 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcspn.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strcspn.3,v 1.10 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd August 11, 2002 +.Dt STRCSPN 3 +.Os +.Sh NAME +.Nm strcspn +.Nd span the complement of a string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strcspn "const char *s" "const char *charset" +.Sh DESCRIPTION +The +.Fn strcspn +function +spans the initial part of the nul-terminated string +.Fa s +as long as the characters from +.Fa s +do not occur in string +.Fa charset +(it +spans the +.Em complement +of +.Fa charset ) . +.Sh RETURN VALUES +The +.Fn strcspn +function +returns the number of characters spanned. +.Sh EXAMPLES +The following call to +.Fn strcspn +will return 3, since the first three characters of string +.Fa s +do not occur in string +.Fa charset : +.Bd -literal -offset indent +char *s = "foobar"; +char *charset = "bar"; +size_t span; + +span = strcspn(s, charset); +.Ed +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strcspn +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/strdup.3 b/static/netbsd/man3/strdup.3 new file mode 100644 index 00000000..f32da5f6 --- /dev/null +++ b/static/netbsd/man3/strdup.3 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strdup.3 8.1 (Berkeley) 6/9/93 +.\" $NetBSD: strdup.3,v 1.19 2024/12/09 12:09:02 nros Exp $ +.\" +.Dd December 9, 2024 +.Dt STRDUP 3 +.Os +.Sh NAME +.Nm strdup , +.Nm strndup +.Nd save a copy of a string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strdup "const char *str" +.Ft char * +.Fn strndup "const char *str" "size_t len" +.Sh DESCRIPTION +The +.Fn strdup +function +allocates sufficient memory for a copy +of the string +.Fa str , +does the copy, and returns a pointer to it. +The pointer may subsequently be used as an +argument to the function +.Xr free 3 . +.Pp +If insufficient memory is available, +.Dv NULL +is returned. +.Pp +The +.Fn strndup +function copies at most +.Fa len +characters from the string +.Fa str +always +.Dv NUL +terminating the copied string. +.Sh EXAMPLES +The following will point +.Va p +to an allocated area of memory containing the nul-terminated string +.Qq foobar : +.Bd -literal -offset indent +char *p; + +if ((p = strdup("foobar")) == NULL) { + fprintf(stderr, "Out of memory.\en"); + exit(1); +} +.Ed +.Sh ERRORS +The +.Fn strdup +function may fail and set the external variable +.Va errno +for any of the errors specified for the library function +.Xr malloc 3 . +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 , +.Xr strcpy 3 , +.Xr strlen 3 +.Sh STANDARDS +The +.Fn strdup +function conforms to +.St -p1003.1-2001 . +The +.Fn strdup +and +.Fn strndup +functions conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Fn strdup +function first appeared in +.Bx 4.4 . +The +.Fn strndup +function was added in +.Nx 4.0 . diff --git a/static/netbsd/man3/strerror.3 b/static/netbsd/man3/strerror.3 new file mode 100644 index 00000000..5fbf3069 --- /dev/null +++ b/static/netbsd/man3/strerror.3 @@ -0,0 +1,289 @@ +.\" $NetBSD: strerror.3,v 1.24 2020/04/04 21:29:54 dholland Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)strerror.3 8.1 (Berkeley) 6/9/93 +.Dd April 4, 2020 +.Dt STRERROR 3 +.Os +.Sh NAME +.Nm perror , +.Nm strerror , +.Nm strerror_l , +.\" .Nm strerror_lr , +.Nm strerror_r , +.Nm sys_errlist , +.Nm sys_nerr +.Nd system error messages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn perror "const char *string" +.In errno.h +.Vt extern const char * const sys_errlist[] ; +.Vt extern const int sys_nerr ; +.In string.h +.Ft "char *" +.Fn strerror "int errnum" +.Ft int +.Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen" +.Ft "char *" +.Fn strerror_l "int errnum" "locale_t loc" +.\".Ft int +.\".Fn strerror_lr "int errnum" "char *strerrbuf" "size_t buflen" "locale_t loc" +.Sh DESCRIPTION +The +.Fn strerror , +.Fn strerror_l , +.\".Fn strerror_lr , +.Fn strerror_r , +and +.Fn perror +functions look up the language-dependent error message +string corresponding to an error number. +.Pp +The +.Fn strerror +function accepts an error number argument +.Fa errnum +and returns a pointer to the corresponding +message string. +The application should not attempt to modify the +returned string, it may be shared, or read only. +.Pp +The +.Fn strerror_r +function renders the same result into +.Fa strerrbuf +for a maximum of +.Fa buflen +characters (including terminator) and returns 0 upon success. +.Pp +The +.Fn strerror_l +function is like +.Fn strerror +but provides in +.Fa loc +the locale to be used to obtain the language for the message, +rather than using the application's current locale. +.\".Pp +.\"The +.\".Fn strerror_lr +.\"function is to +.\".Fn strerror_l +.\"as +.\".Fn strerror_r +.\"is to +.\".Fn strerror . +.Pp +The +.Fn perror +function finds the error message corresponding to the current +value of the global variable +.Va errno +.Pq Xr intro 2 +and writes it, followed by a newline, to the +standard error file descriptor. +If the argument +.Fa string +is +.Pf non- Dv NULL +and does not point to the nul character, +this string is prepended to the message +string and separated from it by +a colon and space +.Pq Dq Li ":\ " ; +otherwise, only the error message string is printed. +Note that in most cases the +.Xr err 3 +and +.Xr warn 3 +family of functions is preferable to +.Fn perror ; +they are more flexible and also print the program name. +.Pp +If the error number is not recognized, these functions return an error message +string containing +.\" , in the appropriate language, +.Dq Li "Unknown error:\ " +followed by the error number in decimal. +To warn about this, +.Fn strerror +and +.Fn strerror_l +set +.Dv errno +to +.Er EINVAL , +and +.Fn strerror_r +.\"and +.\".Fn strerror_lr +returns +.Er EINVAL . +In other cases, except where noted below, +.Dv errno +is not altered, so applications should set it to a known value +(usually zero) before calling either +.Fn strerror +or +.Fn strerror_l +if the resulting value in +.Dv errno +is to be tested for this condition. +Error numbers recognized by this implementation fall in +the range 0 < +.Fa errnum +< +.Fa sys_nerr . +.Pp +If insufficient storage is provided in +.Fa strerrbuf +(as specified in +.Fa buflen ) +to contain the error string, +.Fn strerror_r +.\" and +.\" .Fn strerror_lr +returns +.Er ERANGE +and +.Fa strerrbuf +will contain an error message that has been truncated and +.Dv NUL +terminated to fit the length specified by +.Fa buflen . +In extraordinary cases, it is possible that the internal +buffer used by +.Fn strerror +and +.Fn strerror_l +may be too small for a translated message, +in which case it will be truncated as indicated for +.Fn strerror_r +and +.Dv errno +will be set to +.Er ERANGE . +.Pp +The POSIX locale message strings can be accessed directly using the external +array +.Va sys_errlist . +The external value +.Va sys_nerr +contains a count of the messages in +.Va sys_errlist . +The use of these variables is deprecated; +one of the +.Fn strerror +family of functions should be used instead. +.Sh COMPATIBILITY +Programs that attempt to use the deprecated +.Va sys_errlist +variable often fail to compile because they provide their own, +inconsistent, declaration of it. +Such programs should be updated to use +.Fn strerror . +.Sh ERRORS +These functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The error number was out of range. +.It Bq Er ERANGE +The string buffer supplied was not large enough to hold the complete +error message. +.El +.Sh SEE ALSO +.Xr intro 2 , +.Xr err 3 , +.Xr psignal 3 , +.Xr warn 3 +.Sh STANDARDS +The +.Fn perror +and +.Fn strerror +functions conform to +.St -isoC-99 . +The +.Fn strerror_r +function conforms to +.St -p1003.1-2001 . +The +.Fn strerror_l +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn perror +function first appeared in +.At v4 . +The +.Fn strerror +function first appeared in +.Bx 4.3 Reno . +The +.Fn strerror_r +function first appeared in +.Nx 4.0 . +The +.Fn strerror_l +function was first released in +.Nx 7.0 . +.\"The +.\".Fn strerror_lr +.\"function first appeared in +.\".Nx 10.0 . +.Sh BUGS +The +.Fn strerror +function may return its result in a static buffer which +will be overwritten by subsequent calls. +For portable use, this must be assumed to be a subsequent +call from the current, or any other, thread in the process. +This implementation limits the issue to calls from the +current thread. +The +.Fn strerror_l +function has a similar restriction, but even in other +implementations, is required to use thread local storage, +so only other calls from the calling thread can overwrite +the result. +Both +.Fn strerror +and +.Fn strerror_l +use the same thread local storage; a call to either will destroy +the result from an earlier call by the same thread of either of them. diff --git a/static/netbsd/man3/strfmon.3 b/static/netbsd/man3/strfmon.3 new file mode 100644 index 00000000..a93af668 --- /dev/null +++ b/static/netbsd/man3/strfmon.3 @@ -0,0 +1,185 @@ +.\" $NetBSD: strfmon.3,v 1.8 2017/12/07 22:19:17 kre Exp $ +.\" +.\" Copyright (c) 2001 Jeroen Ruigrok van der Werven <asmodai@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: FreeBSD: Id: strfmon.3,v 1.7 2003/01/06 06:21:25 tjr Exp +.\" +.Dd December 7, 2017 +.Dt STRFMON 3 +.Os +.Sh NAME +.Nm strfmon +.Nd convert monetary value to string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In monetary.h +.Ft ssize_t +.Fn strfmon "char * restrict s" "size_t maxsize" "const char * restrict format" "..." +.Ft ssize_t +.Fn strfmon_l "char * restrict s" "size_t maxsize" "locale_t loc" "const char * restrict format" "..." +.Sh DESCRIPTION +The +.Fn strfmon +function places characters into the array pointed to by +.Fa s +as controlled by the string pointed to by +.Fa format . +No more than +.Fa maxsize +bytes are placed into the array. +.Pp +The +.Fn strfmon_l +function behaves the same as +.Fn strfmon , +but uses the locale +.Fa loc +instead of the process global locale. +.Pp +The format string is composed of zero or more directives: +ordinary characters (not +.Cm % ) , +which are copied unchanged to the output stream; and conversion +specifications, each of which results in fetching zero or more subsequent +arguments. +Each conversion specification is introduced by the +.Cm % +character. +After the +.Cm % , +the following appear in sequence: +.Bl -bullet +.It +Zero or more of the following flags: +.Bl -tag -width "XXX" +.It Cm = Ns Ar f +A +.Sq Cm = +character followed by another character +.Ar f +which is used as the numeric fill character. +.It Cm ^ +Do not use grouping characters, regardless of the current locale default. +.It Cm + +Represent positive values by prefixing them with a positive sign, +and negative values by prefixing them with a negative sign. +This is the default. +.It Cm \&( +Enclose negative values in parentheses. +.It Cm \&! +Do not include a currency symbol in the output. +.It Cm \- +Left justify the result. +Only valid when a field width is specified. +.El +.It +An optional minimum field width as a decimal number. +By default, there is no minimum width. +.It +A +.Sq Cm # +sign followed by a decimal number specifying the maximum +expected number of digits before the radix character. +When this option is used, values that do not exceed the +specified number of digits are formatted so they will be +correctly aligned with other values printed using the same +format. +This includes always leaving space for a possible sign +indicator, even if none is needed for a particular value. +.It +A +.Sq Cm \&. +character followed by a decimal number specifying the number +of digits after the radix character. +.It +One of the following conversion specifiers: +.Bl -tag -width "XXX" +.It Cm i +The +.Vt double +argument is formatted as an international monetary amount. +.It Cm n +The +.Vt double +argument is formatted as a national monetary amount. +.It Cm % +A +.Sq Li % +character is written. +.El +.El +.Sh RETURN VALUES +If the total number of resulting bytes including the terminating +.Dv NULL +byte is not more than +.Fa maxsize , +.Fn strfmon +returns the number of bytes placed into the array pointed to by +.Fa s , +not including the terminating +.Dv NULL +byte. +Otherwise, \-1 is returned, +the contents of the array are indeterminate, +and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn strfmon +function will fail if: +.Bl -tag -width Er +.It Bq Er E2BIG +Conversion stopped due to lack of space in the buffer. +.It Bq Er EINVAL +The format string is invalid. +.It Bq Er ENOMEM +Not enough memory for temporary buffers. +.El +.Sh SEE ALSO +.Xr localeconv 3 +.Sh STANDARDS +The +.Fn strfmon +function +conforms to +.St -p1003.1-2001 . +.Sh AUTHORS +.An -nosplit +The +.Fn strfmon +function was implemented by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . +.Pp +This manual page was written by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org +based on the standard's text. +.Sh BUGS +The +.Fn strfmon +function does not correctly handle multibyte characters in the +.Fa format +argument. diff --git a/static/netbsd/man3/strftime.3 b/static/netbsd/man3/strftime.3 new file mode 100644 index 00000000..b800a7fd --- /dev/null +++ b/static/netbsd/man3/strftime.3 @@ -0,0 +1,545 @@ +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 +.\" $NetBSD: strftime.3,v 1.41 2025/04/08 21:28:48 riastradh Exp $ +.\" +.Dd April 6, 2025 +.Dt STRFTIME 3 +.Os +.Sh NAME +.Nm strftime +.Nd format date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft size_t +.Fo strftime +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fc +.Ft size_t +.Fo strftime_l +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fa "locale_t loc" +.Fc +.Ft size_t +.Fo strftime_z +.Fa "const timezone_t tz" +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fc +.Ft size_t +.Fo strftime_lz +.Fa "const timezone_t tz" +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fa "locale_t loc" +.Fc +.Sh DESCRIPTION +The +.Fn strftime +function formats the information from +.Fa timeptr +into the array pointed to by +.Fa buf +according to the string pointed to by +.Fa format . +.Pp +The function +.Fn strftime_l +does the same as +.Fn strftime +but takes an explicit locale specified in the +.Ft "locale_t" +.Fa loc +argument, rather than using the current locale. +.Pp +The function +.Fn strftime_z +is similar to +.Fn strftime , +but uses an explicit timezone specified in the +.Ft "const timezone_t" +.Fa tz +argument, instead of using the default from the environment. +.Pp +The function +.Fn strftime_lz +does the same as +.Fn strftime +but takes both an explicit timezone and locale arguments. +.Pp +The +.Fa format +string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are copied directly into the array. +A conversion specification consists of a percent sign +.Ql % +and one other character. +.Pp +No more than +.Fa maxsize +characters will be placed into the array. +If the total number of resulting characters, including the terminating +NUL character, is not more than +.Fa maxsize , +.Fn strftime +returns the number of characters in the array, not counting the +terminating NUL. +Otherwise, zero is returned and the buffer contents are indeterminate. +.Pp +Each conversion specification is replaced by the characters as +follows which are then copied into the array. +The characters depend on the values of zero or more members of +.Fa timeptr +as specified by brackets in the description. +If a bracketed member name is followed by +.Dq + , +.Nm strftime +can use the named member even though POSIX.1-2024 does not list it; +if the name is followed by +.Dq \&- , +.Nm strftime +ignores the member even though POSIX.1-2024 lists it +which means portable code should set it. +For portability, +.Fa timeptr +should be initialized as if by a successful call to +.Xr gmtime 3 , +.Xr localtime 3 , +.Xr mktime 3 , +.Xr timegm 3 , +or similar functions. +.Bl -tag -width "xxxx" +.It Cm \&%A +is replaced by the locale's full weekday name. +.Dv [ tm_wday ] +.It Cm %a +is replaced by the locale's abbreviated weekday name. +.Dv [ tm_wday ] +.It Cm \&%B +is replaced by the locale's full month name. +.Dv [ tm_mon ] +.It Cm \&%b No or Cm \&%h +is replaced by the locale's abbreviated month name. +.RI [ tm_mon ] +.It Cm \&%C +is replaced by the century (a year divided by 100 and truncated to an integer) +as a decimal number, with at least two digits by default. +.RI [ tm_year ] +.It Cm \&%c +is replaced by the locale's appropriate date and time representation. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone , +.Dv tm_isdst \&-]. +.It Cm \&%D +is replaced by the date in the format +.Dq Li %m/%d/%y . +Although used in the United States for current dates, +this format is ambiguous elsewhere +and for dates that might involve other centuries. +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday ] +.It Cm \&%d +is replaced by the day of the month as a decimal number [01,31]. +.Dv [ tm_mday ] +.It Cm %d +is replaced by the day of the month as a decimal number (01-31). +.It Cm %E* %O* +POSIX locale extensions. +The sequences +%Ec %EC %Ex %EX %Ey %EY +%Od %Oe %OH %OI %Om %OM +%OS %Ou %OU %OV %Ow %OW %Oy +are supposed to provide alternate +representations. +.Pp +Additionally %OB implemented +to represent alternative months names +(used standalone, without day mentioned). +.It Cm \&%e +is replaced by the day of month as a decimal number [1,31]; +single digits are preceded by a blank. +.Dv [ tm_mday ] +.It Cm \&%F +is equivalent to +.Dq Li %Y-%m-%d +(the ISO 8601 date format). +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday ] +.It Cm \&%G +is replaced by the ISO 8601 year with century as a decimal number. +See also the +.Cm \&%V +conversion specification +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%g +is replaced by the ISO 8601 year without century as a decimal number. +This is the year that includes the greater part of the week. +(Monday as the first day of a week). +See also the +.Ql \&%V +conversion specification. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%H +is replaced by the hour (24-hour clock) as a decimal number [00,23]. +.Dv [ tm_hour ] +.It Cm \&%I +is replaced by the hour (12-hour clock) as a decimal number [01,12]. +.Dv [ tm_hour ] +.It Cm \&%j +is replaced by the day of the year as a decimal number [001,366]. +.Dv [ tm_yday ] +.It Cm \&%k +is replaced by the hour (24-hour clock) as a decimal number [0,23]; +single digits are preceded by a blank. +.Dv [ tm_hour ] +.It Cm \&%l +is replaced by the hour (12-hour clock) as a decimal number [1,12]; +single digits are preceded by a blank. +.Dv [ tm_hour ] +.It Cm \&%M +is replaced by the minute as a decimal number [00,59]. +.Dv [ tm_min ] +.It Cm %m +is replaced by the month as a decimal number [01,12]. +.Dv [ tm_mon ] +.It Cm %n +is replaced by a newline. +.It Cm %p +is replaced by the locale's equivalent of either +.Dq Tn AM +or +.Dq Tn PM . +.Dv [ tm_hour ] +.It Cm \&%R +is replaced by the time in the format +.Dq Li %H:%M . +.Dv [ tm_hour , +.Dv tm_min ] +.It Cm \&%r +is replaced by the locale's representation of 12-hour clock time +using AM/PM notation. +.It Cm \&%S +is replaced by the second as a decimal number [00,60]. +The range of +seconds is [00-60] instead of [00-59] to allow for the periodic occurrence +of leap seconds. +.Dv [ tm_sec ] +.It Cm \&%s +is replaced by the number of seconds since the Epoch (see +.Xr ctime 3 ) . +Although %s is reliable in this implementation, +it can have glitches on other platforms +(notably obsolescent platforms lacking +.Fa tm_gmtoff +or where +.Tp time_t +is no wider than int), and POSIX allows +.Nm strftime +to set +.Dv errno +to +.Dv EINVAL +or +.Dv EOVERFLOW +and return 0 if the number of seconds would be negative or out of range for +.Tp time_t . +Portable code should therefore format a +.Tp time_t +value directly via something like +.Xr snprintf 3 +instead of via +.Xr localtime 3 +followed by +.Nm strftime +with "%s". +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff +, +.Dv tm_isdst \&-]. +.It Cm \&%T +is replaced by the time in the format +.Dq Li %H:%M:%S . +.Dv [ tm_hour , +.Dv tm_min , +.Dv tm_sec ] +.It Cm \&%t +is replaced by a tab. +.It Cm \&%U +is replaced by the week number of the year (Sunday as the first day of +the week) as a decimal number [00,53]. +.Dv [ tm_wday , +.Dv tm_yday , +.Dv tm_year \&-] +.It Cm \&%u +is replaced by the weekday (Monday as the first day of the week) +as a decimal number [1,7]. +.Dv [ tm_wday ] +.It Cm \&%V +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number [01,53]. According to ISO 8601 the week +containing January 1 is week 1 if it has four or more days in the new year, +otherwise it is week 53 of the previous year, and the next week is week 1. +The year is given by the +.Ql \&%G +conversion specification. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%v +is replaced by the date in the format +.Dq Li %e-%b-%Y . +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%W +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number [00,53]. +.Dv [ tm_yday , +.Dv tm_wday ] +.It Cm \&%w +is replaced by the weekday (Sunday as the first day of the week) +as a decimal number [0,6]. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%X +is replaced by the locale's appropriate time representation. +.Dv [ tm_year \&-, +.Dv tm_yday \&-, +.Dv tm_mon \&-, +.Dv tm_mday \&-, +.Dv tm_wday \&-, +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone , +.Dv tm_isdst \&-]. +.It Cm \&%x +is replaced by the locale's appropriate date representation. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour \&-, +.Dv tm_min \&-, +.Dv tm_sec \&-, +.Dv tm_gmtoff \&-, +.Dv tm_zone \&-, +.Dv tm_isdst \&-]. +.It Cm \&%Y +is replaced by the year with century as a decimal number. +.Dv [ tm_year ] +.It Cm \&%y +is replaced by the year without century as a decimal number [00,99]. +.Dv [ tm_year ] +.It Cm \&%Z +is replaced by the time zone abbreviation, +or the empty string if this is not determinable. +.Dv [ tm_zone , +.Dv tm_isdst \&-] +.It Cm \&%z +is replaced by the offset from the Prime Meridian in the format ++HHMM or -HHMM (ISO 8601) as appropriate, with positive values representing +locations east of Greenwich, or by the empty string if this is +not determinable. +The numeric time zone abbreviation \&-0000 is used when the time is +Universal Time +but local time is indeterminate; by convention this is used for +locations while uninhabited, and corresponds to a zero offset when the +time zone abbreviation begins with +.Dq Li [-] . +.It Cm %+ +is replaced by locale's date and time in +.Xr date 1 +format. +On +.Nx +currently this only works for the C locale. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone ] +.It Cm %-* +GNU libc extension. +Do not do any padding when performing numerical outputs. +.It Cm %_* +GNU libc extension. +Explicitly specify space for padding. +.It Cm %0* +GNU libc extension. +Explicitly specify zero for padding. +.It Cm %% +is replaced by as single +.Ql % . +.El +.Pp +As a side effect, +.Nm strftime +also behaves as if +.Xr tzset 3 +were called. +This is for compatibility with older platforms, as required by POSIX; +it is not needed for +.Nm strftime +'s +own use. +.Sh RETURN VALUES +If the conversion is successful, +.Nm +returns the number of bytes placed into the array, not counting the +terminating +.Dv NUL ; +.Va errno +is unchanged if the returned value is zero. +Otherwise, +.Va errno +is set to indicate the error, zero is returned, +and the array contents are unspecified. +.Sh ERRORS +This function fails if: +.Bl -tag -width Er +.It Bq Er ERANGE +The specified file offset is invalid. +The total number of resulting bytes, including the terminating +.Dv NUL +character, is more than +.Fa maxsize . +.It Bq Er EOVERFLOW +The format includes an +.Cm \&%s +conversion and the number of seconds since the Epoch cannot be represented +in a +.Ft time_t . +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr printf 1 , +.Xr ctime 3 , +.Xr printf 3 , +.Xr strptime 3 , +.Xr tm 3 +.Sh STANDARDS +The +.Fn strftime +function +conforms to +.St -isoC-99 . +The +.Ql \&%C , +.Ql \&%D , +.Ql \&%e , +.Ql \&%g , +.Ql \&%G , +.Ql \&%h , +.Ql \&%k , +.Ql \&%l , +.Ql \&%n , +.Ql \&%r , +.Ql \&%R , +.Ql \&%s , +.Ql \&%t , +.Ql \&%T , +.Ql \&%u , +.Ql \&%V , +and +.Ql \&%v +conversion specifications are extensions. +.Pp +Use of the ISO 8601 conversions may produce non-intuitive results. +Week 01 of a year is per definition the first week which has the Thursday +in this year, which is equivalent to the week which contains the fourth +day of January. +In other words, the first week of a new year is the week which has the +majority of its days in the new year. +Week 01 might also contain days from the previous year and the week +before week 01 of a year is the last week (52 or 53) of the previous +year even if it contains days from the new year. +A week starts with Monday (day 1) and ends with Sunday (day 7). +For example, the first week of the year 1997 lasts from +1996-12-30 to 1997-01-05. +.Sh BUGS +There is no conversion specification for the phase of the moon. +.Pp +The +.Fn strftime +function does not correctly handle multibyte characters in the +.Fa format +argument. +.Pp +A return value of zero does not necessarily indicate an error. +If the resulting string is an empty string, the result value is +zero and it is not possible to distinguish between success and error. +For example, in many locales +.Cm \&%p +yields an empty string. +This problem can be avoided by inserting an extra space at the +beginning of the format string and then skipping over it or removing +it from the result. diff --git a/static/netbsd/man3/string.3 b/static/netbsd/man3/string.3 new file mode 100644 index 00000000..c4cb4b36 --- /dev/null +++ b/static/netbsd/man3/string.3 @@ -0,0 +1,170 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)string.3 8.2 (Berkeley) 12/11/93 +.\" $NetBSD: string.3,v 1.18 2017/04/26 07:40:09 abhinav Exp $ +.\" +.Dd April 26, 2017 +.Dt STRING 3 +.Os +.Sh NAME +.Nm string +.Nd string specific functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn stpcpy "char *dst" "const char *src" +.Ft char * +.Fn stpncpy "char *dst" "const char *src" "size_t count" +.Ft char * +.Fn strcat "char *s" "const char * append" +.Ft size_t +.Fn strlcat "char *dst" "const char *src" "size_t size" +.Ft char * +.Fn strncat "char *s" "const char *append" "size_t count" +.Ft char * +.Fn strchr "const char *s" "int c" +.Ft char * +.Fn strrchr "const char *s" "int c" +.Ft int +.Fn strcmp "const char *s1" "const char *s2" +.Ft int +.Fn strncmp "const char *s1" "const char *s2" "size_t count" +.Ft int +.Fn strcasecmp "const char *s1" "const char *s2" +.Ft int +.Fn strncasecmp "const char *s1" "const char *s2" "size_t count" +.Ft int +.Fn strcoll "const char *s1" "const char *s2" +.Ft char * +.Fn strcpy "char *dst" "const char *src" +.Ft size_t +.Fn strlcpy "char *dst" "const char *src" "size_t size" +.Ft char * +.Fn strncpy "char *dst" "const char *src" "size_t count" +.Ft char * +.Fn strerror "int errno" +.Ft int +.Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen" +.Ft size_t +.Fn strlen "const char *s" +.Ft size_t +.Fn strnlen "const char *s" "size_t count" +.Ft char * +.Fn strpbrk "const char *s" "const char *charset" +.Ft char * +.Fn strsep "char **stringp" "const char *delim" +.Ft char * +.Fn stresep "char **stringp" "const char *delim" "int escape" +.Ft size_t +.Fn strspn "const char *s" "const char *charset" +.Ft size_t +.Fn strcspn "const char *s" "const char *charset" +.Ft char * +.Fn strdup "const char *str" +.Ft char * +.Fn strndup "const char *str" "size_t len" +.Ft char * +.Fn strstr "const char *big" "const char *little" +.Ft char * +.Fn strcasestr "const char *big" "const char *little" +.Ft char * +.Fn strtok "char *s" "const char *delim" +.Ft char * +.Fn strtok_r "char *s" "const char *delim" "char **lasts" +.Ft size_t +.Fn strxfrm "char *dst" "const char *src" "size_t n" +.Sh DESCRIPTION +The string +functions manipulate strings terminated by a +nul byte. +.Pp +See the specific manual pages for more information. +For manipulating variable length generic objects as byte +strings (without the nul byte check), see +.Xr bstring 3 . +.Pp +Except as noted in their specific manual pages, +the string functions do not test the destination +for size limitations. +.Sh SEE ALSO +.Xr bstring 3 , +.Xr strcat 3 , +.Xr strchr 3 , +.Xr strcmp 3 , +.Xr strcoll 3 , +.Xr strcpy 3 , +.Xr strcspn 3 , +.Xr strdup 3 , +.Xr strerror 3 , +.Xr strings 3 , +.Xr strlcat 3 , +.Xr strlen 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 , +.Xr strxfrm 3 +.Sh STANDARDS +The +.Fn strcat , +.Fn strncat , +.Fn strchr , +.Fn strrchr , +.Fn strcmp , +.Fn strncmp , +.Fn strcpy , +.Fn strncpy , +.Fn strcoll , +.Fn strerror , +.Fn strlen , +.Fn strpbrk , +.Fn strsep , +.Fn strspn , +.Fn strcspn , +.Fn strstr , +.Fn strtok , +and +.Fn strxfrm +functions conform to +.St -ansiC . +.Pp +The +.Fn strtok_r +function conforms to +.St -p1003.1c-95 . +.Pp +The +.Fn strerror_r +function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/stringlist.3 b/static/netbsd/man3/stringlist.3 new file mode 100644 index 00000000..1caffe55 --- /dev/null +++ b/static/netbsd/man3/stringlist.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: stringlist.3,v 1.16 2017/07/03 21:32:49 wiz Exp $ +.\" +.\" Copyright (c) 1997, 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 6, 2010 +.Dt STRINGLIST 3 +.Os +.Sh NAME +.Nm stringlist , +.Nm sl_init , +.Nm sl_add , +.Nm sl_free , +.Nm sl_find , +.Nm sl_delete +.Nd stringlist manipulation functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stringlist.h +.Ft StringList * +.Fn sl_init +.Ft int +.Fn sl_add "StringList *sl" "char *item" +.Ft void +.Fn sl_free "StringList *sl" "int freeall" +.Ft char * +.Fn sl_find "StringList *sl" "const char *item" +.Ft int +.Fn sl_delete "StringList *sl" "const char *item" "int freeit" +.Sh DESCRIPTION +The +.Nm +functions manipulate stringlists, which are lists of +strings that extend automatically if necessary. +.Pp +The +.Ar StringList +structure has the following definition: +.Bd -literal -offset indent +typedef struct _stringlist { + char **sl_str; + size_t sl_max; + size_t sl_cur; +} StringList; +.Ed +.Pp +where: +.Bl -tag -width "sl_str" -offset indent +.It Ar sl_str +is a pointer to the base of the array containing the list, +.It Ar sl_max +is the size of +.Ar sl_str , +and +.It Ar sl_cur +is the offset in +.Ar sl_str +of the current element. +.El +.Pp +The following stringlist manipulation functions are available: +.Bl -tag -width "sl_delete()" -offset 2n +.It Fn sl_init +Create a stringlist. +Returns a pointer to a +.Ar StringList , +or +.Dv NULL +in case of failure. +.It Fn sl_free +Releases memory occupied by +.Ar sl +and the +.Ar sl->sl_str +array. +If +.Ar freeall +is non-zero, then each of the items within +.Ar sl->sl_str +is released as well. +.It Fn sl_add +Add +.Ar item +to +.Ar sl->sl_str +at +.Ar sl->sl_cur , +extending the size of +.Ar sl->sl_str . +Returns zero upon success, \-1 upon failure. +.It Fn sl_find +Find +.Ar item +in +.Ar sl , +returning +.Dv NULL +if it's not found. +.It Fn sl_delete +Remove +.Ar item +from the list. +If +.Ar freeit +is non-zero, the string is freed. +Returns +.Dv 0 +if the name is found +and +.Dv \-1 +if the name is not found. +.El +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 +.Sh HISTORY +The +.Nm +functions appeared in +.Nx 1.3 . diff --git a/static/netbsd/man3/strings.3 b/static/netbsd/man3/strings.3 new file mode 100644 index 00000000..ea63e723 --- /dev/null +++ b/static/netbsd/man3/strings.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: strings.3,v 1.3 2017/06/17 10:48:09 abhinav Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 17, 2017 +.Dt STRINGS 3 +.Os +.Sh NAME +.Nm strings +.Nd string operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In strings.h +.Ft int +.Fn bcmp "const void *b1" "const void *b2" "size_t len" +.Ft void +.Fn bcopy "const void *src" "void *dst" "size_t len" +.Ft void +.Fn bzero "void *b" "size_t len" +.Ft int +.Fn ffs "int value" +.Ft char * +.Fn index "const char *s" "int c" +.Ft char * +.Fn rindex "const char *s" "int c" +.Ft int +.Fn strcasecmp "const char *s1" "const char *s2" +.Ft int +.Fn strncasecmp "const char *s1" "const char *s2" "size_t len" +.Sh DESCRIPTION +These functions all live in the +.In strings.h +header file. +Except for +.Fn ffs , +they operate on strings. +.Fn index , +.Fn rindex , +and +.Fn strcasecmp +need nul-terminated strings. +.Pp +See the specific manual pages for more information. +.Pp +See +.Xr string 3 +for string functions that follow +.St -ansiC +or +.St -isoC-99 , +.Xr bstring 3 +for functions that operate on strings that are not nul-terminated, and +.Xr bitstring 3 +for bit-string manipulation macros. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr bcopy 3 , +.Xr bitstring 3 , +.Xr bstring 3 , +.Xr bzero 3 , +.Xr ffs 3 , +.Xr index 3 , +.Xr rindex 3 , +.Xr strcasecmp 3 , +.Xr string 3 diff --git a/static/netbsd/man3/strlcpy.3 b/static/netbsd/man3/strlcpy.3 new file mode 100644 index 00000000..32f5f631 --- /dev/null +++ b/static/netbsd/man3/strlcpy.3 @@ -0,0 +1,359 @@ +.\" $NetBSD: strlcpy.3,v 1.30 2026/01/04 23:58:42 uwe Exp $ +.\" from OpenBSD: strlcpy.3,v 1.11 2000/11/16 23:27:41 angelos Exp +.\" +.\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 4, 2026 +.Dt STRLCPY 3 +.Os +.Sh NAME +.Nm strlcpy , +.Nm strlcat +.Nd size-bounded string copying and concatenation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strlcpy "char *dst" "const char *src" "size_t size" +.Ft size_t +.Fn strlcat "char *dst" "const char *src" "size_t size" +.Sh DESCRIPTION +The +.Fn strlcpy +and +.Fn strlcat +functions copy and concatenate +.Tn NUL Ns -terminated +strings respectively. +.Pp +The +.Fn strlcpy +function computes the length +.Pq like Xr strlen 3 +of +.Fa src , +which +.Em MUST +be +.Tn NUL Ns -terminated , +and copies up to +.Fa size Li "- 1" +bytes from +.Fa src +to +.Fa dst , +.Tn NUL Ns -terminating +the result. +.Pp +If the bytes +.Fa dst Ns Li "[0]" , +.Fa dst Ns Li "[1]" , +\&...\^, +.Fa dst Ns Li "[" Ns Fa size Li - 1 Ns Li "]" +are all +.No non- Ns Tn NUL , +then the +.Fn strlcat +function returns +.Sm off +.Fa size Li \~+\~ strlen( Fa src ) +.Sm on +without writing anything to +.Fa dst . +.Pp +Otherwise, the +.Fn strlcat +function computes the sum of the lengths of +.Fa dst +and +.Fa src , +which +.Em MUST +be +.Tn NUL Ns -terminated , +and copies the content of +.Fa src +to the position of the first +.Tn NUL +byte in +.Fa dst , +.Tn NUL Ns -terminating +the result. +.Fn strlcat +will append at most +.Sm off +.Fa size Li \~-\~ strlen( Fa dst ) Li \~-\~ 1 +.Sm on +.No non- Ns Tn NUL +bytes from +.Fa src , +followed by one +.Tn NUL +byte. +.Ss Relation to Xr strncpy 3 and Xr strncat 3 +Unlike +.Xr strncpy 3 , +.Fn strlcpy +is guaranteed to +.Tn NUL Ns -terminate +the result +.Po +as long as +.Fa size +is larger than 0 +.Pc . +Note that you should include a byte for the +.Tn NUL +in +.Fa size . +.Pp +Unlike +.Xr strncat 3 , +.Fn strlcat +is guaranteed to +.Tn NUL Ns -terminate +the result if +.Fa dst +is +.Tn NUL Ns -terminated +to begin with. +. +.Bl -hang -width 0n \" indent by just the extra spacing (digit-width) +. +.It Sy WARNING : +.Fn strlcpy +and +.Fn strlcat +are not guaranteed to initialize all +.Fa size +bytes of +.Fa dst . +.Fn strlcpy +leaves bytes past +.Sm off +.Fa dst Li "[" strlen( Fa src ) Li "]" +.Sm on +uninitialized, and +.Fn strlcat +leaves bytes past +.Sm off +.Fa dst Li "[" strlen( Fa dst ) Li \~+\~ strlen( Fa src ) Li "]" +.Sm on +uninitialized. +This can lead to security vulnerabilities such as leaking secrets from +uninitialized stack or heap buffers. +You +.Em MUST NOT +simply replace +.Xr strncpy 3 +and +.Xr strncat 3 +by +.Fn strlcpy +and +.Fn strlcat +without proving it is safe to leave some of the output uninitialized. +. +.It Sy WARNING : +.Fn strlcat +does not guarantee to +.Tn NUL Ns -terminate +.Fa dst +even if there is space for it. +In particular, if +.Fa dst +is not +.Tn NUL Ns -terminated +on entry, then +.Fn strlcat +will leave it without a +.Tn NUL Ns -terminator +on return. +. +.It Sy WARNING : +The +.Fa src +argument +.Em MUST +be +.Tn NUL Ns -terminated . +Both +.Fn strlcpy +and +.Fn strlcat +will read through +.Fa src +until they find a +.Tn NUL +terminator, reading +.Fa src Ns Li "[" Ns Fa size Ns Li "]" Ns , +.Fa src Ns Li "[" Ns Fa size Li + 1 Ns Li "]" Ns , +.Fa src Ns Li "[" Ns Fa size Li + 2 Ns Li "]" Ns , +and beyond if there was no earlier +.Tn NUL +terminator. +Applications handling fixed-width fields with +.Pq possibly empty +.Tn NUL +padding, instead of +.Tn NUL Ns -terminated +C strings, +.Em MUST +use +.Xr strncpy 3 +and +.Xr strncat 3 +instead. +Attempting to use +.Fn strlcpy +or +.Fn strlcat +for these cases can lead to crashes or security vulnerabilities from +buffer overruns. +. +.El +. +.Sh RETURN VALUES +The +.Fn strlcpy +and +.Fn strlcat +functions return the total length of the string they tried to create. +For +.Fn strlcpy +that means the length of +.Fa src . +For +.Fn strlcat +that means the initial length of +.Fa dst +plus +the length of +.Fa src . +While this may seem somewhat confusing it was done to make +truncation detection simple. +.Pp +Note however, that if +.Fn strlcat +traverses +.Fa size +bytes without finding a +.Tn NUL , +the length of the string is considered to be +.Fa size +and the destination string will not be +.Tn NUL Ns -terminated +.Pq since there was no space for the Tn NUL . +This keeps +.Fn strlcat +from running off the end of a string. +In practice this should not happen +.Po +as it means that either +.Fa size +is incorrect or that +.Fa dst +is not a proper +.Dq C +string +.Pc . +The check exists to prevent potential security problems in incorrect code. +.Sh EXAMPLES +The following code fragment illustrates the simple case: +.Bd -literal -offset indent +char *s, *p, buf[BUFSIZ]; + +\&... + +strlcpy(buf, s, sizeof(buf)); +strlcat(buf, p, sizeof(buf)); +.Ed +.Pp +To detect truncation, perhaps while building a pathname, something +like the following might be used: +.Bd -literal -offset indent +char *dir, *file, pname[MAXPATHLEN]; + +\&... + +if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) + goto toolong; +if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) + goto toolong; +.Ed +.Pp +Since we know how many bytes we copied the first time, we can +speed things up a bit by using a copy instead of an append: +.Bd -literal -offset indent +char *dir, *file, pname[MAXPATHLEN]; +size_t n; + +\&... + +n = strlcpy(pname, dir, sizeof(pname)); +if (n >= sizeof(pname)) + goto toolong; +if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) + goto toolong; +.Ed +.Pp +However, one may question the validity of such optimizations, as they +defeat the whole purpose of +.Fn strlcpy +and +.Fn strlcat . +.Sh SEE ALSO +.Xr snprintf 3 , +.Xr strncat 3 , +.Xr strncpy 3 +.Rs +.%A Todd C. Miller +.%A Theo de Raadt +.%T strlcpy and strlcat \(em Consistent, Safe, String Copy and Concatenation +.%I USENIX Association +.%B Proceedings of the FREENIX Track: 1999 USENIX Annual Technical Conference +.%D June 6\|\(en11, 1999 +.%U http://www.usenix.org/publications/library/proceedings/usenix99/full_papers/millert/millert.pdf +.Re +.Sh STANDARDS +The +.Fn strlcpy +and +.Fn strlcat +functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +The +.Fn strlcpy +and +.Fn strlcat +functions first appeared in +.Ox 2.4 , +then in +.Nx 1.4.3 +and +.Fx 3.3 . diff --git a/static/netbsd/man3/strlen.3 b/static/netbsd/man3/strlen.3 new file mode 100644 index 00000000..d460f9d3 --- /dev/null +++ b/static/netbsd/man3/strlen.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strlen.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strlen.3,v 1.9 2009/05/01 17:27:01 perry Exp $ +.\" +.Dd May 1, 2009 +.Dt STRLEN 3 +.Os +.Sh NAME +.Nm strlen , +.Nm strnlen +.Nd find length of string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strlen "const char *s" +.Ft size_t +.Fn strnlen "const char *s" "size_t maxlen" +.Sh DESCRIPTION +The +.Fn strlen +function +computes the length of the string +.Fa s . +.Pp +The +.Fn strnlen +function attempts to compute the length of +.Fa s , +but never scans beyond the first +.Fa maxlen +bytes of +.Fa s . +.Sh RETURN VALUES +The +.Fn strlen +function +returns +the number of characters that precede the +terminating +.Dv NUL +character. +.Pp +The +.Fn strnlen +function returns either the same result as +.Fn strlen +or +.Fa maxlen , +whichever is smaller. +.Sh SEE ALSO +.Xr string 3 , +.Xr wcslen 3 , +.Xr wcswidth 3 +.Sh STANDARDS +The +.Fn strlen +function +conforms to +.St -isoC . +The +.Fn strnlen +function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/strmode.3 b/static/netbsd/man3/strmode.3 new file mode 100644 index 00000000..89980092 --- /dev/null +++ b/static/netbsd/man3/strmode.3 @@ -0,0 +1,156 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strmode.3 8.3 (Berkeley) 7/28/94 +.\" $NetBSD: strmode.3,v 1.17 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd July 28, 1994 +.Dt STRMODE 3 +.Os +.Sh NAME +.Nm strmode +.Nd convert inode status information into a symbolic string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn strmode "mode_t mode" "char *bp" +.Sh DESCRIPTION +The +.Fn strmode +function +converts a file +.Fa mode +(the type and permission information associated with an inode, see +.Xr stat 2 ) +into a symbolic string which is stored in the location referenced by +.Fa bp . +This stored string is eleven characters in length plus a trailing nul byte. +.Pp +The first character is the inode type, and will be one of the following: +.Pp +.Bl -tag -width flag -offset indent -compact +.It \- +regular file +.It a +regular file in archive state 1 +.It A +regular file in archive state 2 +.It b +block special +.It c +character special +.It d +directory +.It l +symbolic link +.It p +fifo +.It s +socket +.It w +whiteout +.It ? +unknown inode type +.El +.Pp +The next nine characters encode three sets of permissions, in three +characters each. +The first three characters are the permissions for the owner of the +file, the second three for the group the file belongs to, and the +third for the ``other'', or default, set of users. +.Pp +Permission checking is done as specifically as possible. +If read permission is denied to the owner of a file in the first set +of permissions, the owner of the file will not be able to read the file. +This is true even if the owner is in the file's group and the group +permissions allow reading or the ``other'' permissions allow reading. +.Pp +If the first character of the three character set is an ``r'', the file is +readable for that set of users; if a dash ``\-'', it is not readable. +.Pp +If the second character of the three character set is a ``w'', the file is +writable for that set of users; if a dash ``\-'', it is not writable. +.Pp +The third character is the first of the following characters that apply: +.Bl -tag -width xxxx +.It S +If the character is part of the owner permissions and the file is not +executable or the directory is not searchable by the owner, and the +set-user-id bit is set. +.It S +If the character is part of the group permissions and the file is not +executable or the directory is not searchable by the group, and the +set-group-id bit is set. +.It T +If the character is part of the other permissions and the file is not +executable or the directory is not searchable by others, and the ``sticky'' +.Pq Dv S_ISVTX +bit is set. +.It s +If the character is part of the owner permissions and the file is +executable or the directory searchable by the owner, and the set-user-id +bit is set. +.It s +If the character is part of the group permissions and the file is +executable or the directory searchable by the group, and the set-group-id +bit is set. +.It t +If the character is part of the other permissions and the file is +executable or the directory searchable by others, and the ``sticky'' +.Pq Dv S_ISVTX +bit is set. +.It x +The file is executable or the directory is searchable. +.It \- +None of the above apply. +.El +.Pp +The last character is a plus sign ``+'' if there are any alternative +or additional access control methods associated with the inode, otherwise +it will be a space. +.Pp +Archive state 1 and archive state 2 represent file system dependent +archive state for a file. +Most file systems do not retain file archive +state, and so will not report files in either archive state. +msdosfs will report a file in archive state 1 if it has been +archived more recently than modified. +Hierarchical storage systems may have multiple archive states for a +file and may define archive states 1 and 2 as appropriate. +.Sh SEE ALSO +.Xr chmod 1 , +.Xr find 1 , +.Xr stat 2 , +.Xr getmode 3 , +.Xr setmode 3 +.Sh HISTORY +The +.Fn strmode +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/strncpy.3 b/static/netbsd/man3/strncpy.3 new file mode 100644 index 00000000..27887b21 --- /dev/null +++ b/static/netbsd/man3/strncpy.3 @@ -0,0 +1,302 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcpy.3 8.1 (Berkeley) 6/4/93 +.\" from: NetBSD: strcpy.3,v 1.23 2015/04/01 20:18:17 riastradh Exp +.\" $NetBSD: strncpy.3,v 1.16 2023/08/13 11:27:22 riastradh Exp $ +.\" +.Dd August 11, 2023 +.Dt STRNCPY 3 +.Os +.Sh NAME +.Nm stpncpy , +.Nm strncpy +.Nd copy fixed-width buffers with NUL padding +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len" +.Ft char * +.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len" +.Sh DESCRIPTION +The +.Fn stpncpy +and +.Fn strncpy +functions fill a +.Fa len Ns -byte +buffer at +.Fa dst +by copying up to +.Fa len +.No non- Ns Tn NUL +bytes from +.Fa src +followed by enough +.Tn NUL +bytes \(em possibly zero of them \(em to pad the remainder. +.Pp +The buffers +.Fa src +and +.Fa dst +may not overlap. +.Pp +The buffer +.Fa src +is not required to hold a +.Tn NUL Ns -terminated +string on input; it is only required +.Em either +to have at least +.Fa len +bytes allocated and initialized, +.Em or +to have a +.Tn NUL +byte if it is shorter than +.Fa len +bytes. +.Pp +The buffer +.Fa dst +is not guaranteed to hold a +.Tn NUL Ns -terminated +string on output; +.Fn stpncpy +and +.Fn strncpy +write exactly +.Fa len +bytes to it, which includes nonempty +.Tn NUL +padding only if a +.Tn NUL +byte appears in the first +.Fa len +bytes at +.Fa src . +.Sh RETURN VALUES +The +.Fn strncpy +function returns +.Fa dst . +.Pp +The +.Fn stpncpy +function returns a pointer to the byte after the last +.No non- Ns Tn NUL +byte of +.Fa dst . +This does not necessarily point to a +.Tn NUL +byte; +.Fn stpncpy +may return +.Li \*(Am Ns Fa dst Ns Li "[" Fa len Ns Li "]" Ns , +if all +.Fa len +bytes starting at +.Fa src +are +.No non- Tn NUL . +.Sh EXAMPLES +The following logic fills a fixed-width field in a record that might +appear on disk with the content of a caller-provided string +.Dv str , +padded to the end of the field with +.Tn NUL +bytes: +.Bd -literal -offset indent +struct record { + uint16_t id; + char name[6]; + uint8_t tag; + ... +}; + +struct record *rec = ...; +strncpy(rec->name, str, sizeof(rec->name)); +.Ed +.Pp +The following values for +.Dv str +result in the following corresponding contents of +.Dv rec Ns Li "->name" : +.Bl -column -offset indent ".Li \*qabcdefghi\e0\*q" ".Li \*qabc\e0\e0\e0\*q" +.It Dv str Ta Dv rec Ns Li "->name" +.It Li \*qabc\e0\*q Ta Li \*qabc\e0\e0\e0\*q +.It Li \*qabc\e0\e0\e0\*q Ta Li \*qabc\e0\e0\e0\*q +.It Li \*qabcde\e0\*q Ta Li \*qabcde\e0\*q +.It Li \*qabcdef\e0\*q Ta Li \*qabcdef\*q +.It Li \*qabcdef\*q Ta Li \*qabcdef\*q +.It Li \*qabcdefghi\e0\*q Ta Li \*qabcdef\*q +.It Li \*qabcdefghi\*q Ta Li \*qabcdef\*q +.El +.Pp +Note that when +.Dv str +has at least six +.No non- Ns Tn NUL +bytes, +.Dv rec Ns Li "->name" +is +.Em not +.Tn NUL Ns -terminated +\(em it is only +.Em padded +with (possibly zero) +.Tn NUL +bytes to fill the fixed-width buffer. +When +.Dv str +has +.Em more +than six +.No non- Ns Tn NUL +bytes, the additional ones are truncated. +If +.Dv str +has space for +.Em fewer +than six bytes, and the last one is not +.Tn NUL , +using +.Fn strncpy +is undefined. +.Pp +Because +.Fn strncpy +does +.Em not +guarantee to +.Tn NUL Ns -terminate +the result, if +.Tn NUL Ns -termination +is required it must be done explicitly: +.Bd -literal -offset indent +char buf[1024]; + +strncpy(buf, input, sizeof(buf) - 1); +buf[sizeof(buf) - 1] = '\e0'; +.Ed +.Pp +If +.Va input +is guaranteed to be +.Tn NUL Ns -terminated , +and if +.Va buf +need only be +.Tn NUL Ns -terminated , +not fully initialized with +.Tn NUL +padding, +this could be achieved using +.Xr strlcpy 3 +as follows: +.Bd -literal -offset indent +strlcpy(buf, input, sizeof(buf)); +.Ed +.Pp +It is not enough for +.Va input +to have +.Li sizeof(buf) +bytes allocated; it MUST be +.Tn NUL Ns -terminated +for +.Xr strlcpy 3 +to be used. +.Pp +Note that because +.Xr strlcpy 3 +is not defined in any standards, it should +only be used when portability is not a concern. +.Pp +.Sy WARNING : +Because +.Xr strlcpy 3 +does not fully initialize +.Fa dst , +but does read all the way to a +.Tn NUL +terminator in +.Fa src +even past +.Fa len +bytes, +.Xr strlcpy 3 +is +.Em not +a safe +.Tn NUL Ns -terminating +replacement for +.Fn strncpy . +Naively replacing +.Fn strncpy +by +.Xr strlcpy 3 +can lead to crashes, undefined behaviour, and disclosure of secrets +from uninitialized memory. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr memccpy 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr strcpy 3 , +.Xr strlcpy 3 , +.Xr wcscpy 3 +.Sh STANDARDS +The +.Fn strncpy +function conforms to +.St -isoC-99 . +.Pp +The +.Fn stpncpy +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn stpncpy +function first appeared in +.Nx 6.0 . +.Sh SECURITY CONSIDERATIONS +The +.Fn stpncpy +and +.Fn strncpy +functions are not guaranteed to +.Tn NUL Ns -terminate +the result. diff --git a/static/netbsd/man3/strpbrk.3 b/static/netbsd/man3/strpbrk.3 new file mode 100644 index 00000000..f0886706 --- /dev/null +++ b/static/netbsd/man3/strpbrk.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strpbrk.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strpbrk.3,v 1.9 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd June 4, 1993 +.Dt STRPBRK 3 +.Os +.Sh NAME +.Nm strpbrk +.Nd locate multiple characters in string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strpbrk "const char *s" "const char *charset" +.Sh DESCRIPTION +The +.Fn strpbrk +function +locates in the nul-terminated string +.Fa s +the first occurrence of any character in the string +.Fa charset +and returns a pointer to this character. +If no characters from +.Fa charset +occur anywhere in +.Fa s +.Fn strpbrk +returns +.Dv NULL . +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strpbrk +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/strpct.3 b/static/netbsd/man3/strpct.3 new file mode 100644 index 00000000..c3ac408b --- /dev/null +++ b/static/netbsd/man3/strpct.3 @@ -0,0 +1,237 @@ +.\" $NetBSD: strpct.3,v 1.8 2025/12/14 16:28:05 kre Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This file was contributed to The NetBSD Foundation by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 14, 2025 +.Dt STRPCT 3 +.Os +.Sh NAME +.Nm strpct , +.Nm strspct , +.Nm strpct_r , +.Nm strsptc_r , +.Nm strpct_round +.Nd decimal percent formatters +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft char * +.Fn strpct "char *buf" "size_t bufsiz" "uintmax_t numerator" "uintmax_t denominator" "size_t precision" +.Ft char * +.Fn strpct_r "char *buf" "size_t bufsiz" "uintmax_t numerator" "uintmax_t denominator" "size_t precision" "uint32_t rounding_mode" +.Ft char * +.Fn strspct "char *buf" "size_t bufsiz" "intmax_t numerator" "intmax_t denominator" "size_t precision" +.Ft char * +.Fn strspct_r "char *buf" "size_t bufsiz" "intmax_t numerator" "intmax_t denominator" "size_t precision" "uint32_t rounding_mode" +.Ft uint32_t +.Fn strpct_round "uint32_t mode" +.Sh DESCRIPTION +The +.Fn strpct_r +function formats the fraction represented by +.Fa numerator +and +.Fa denominator +into a percentage representation with the number of fractional digits +specified by +.Fa precision , +without using floating point arithmetic. +.Pp +The result is stored in the +.Fa buf +in which a maximum of +.Fa bufsiz +\(mi 1 meaningful bytes can be stored +and is rounded according to the +.Fa rounding_mode . +The current locale's radix character, +typically period +.Pq Sq \&. +or comma +.Pq Sq \&, , +is inserted before the fractional digits if the +.Fa precision +is greater than 0. +.Pp +The parameter +.Fa rounding_mode +should be one of the following: +.Pp +.Bl -tag -width 12n -compact +.It Dv STRPCT_RTN +The result returned will be rounded to the nearest correct value. +Actual values exactly mid way between one representable value +and the next round away from zero. +.It Dv STRPCT_RTZ +Rounding towards 0 (truncating rather than rounding) is used. +.It Dv STRPCT_RAZ +Rounding away from 0 (toward the next bigger magnitude) is used. +.It Dv STRPCT_RTI +Rounding towards infinity, to a mathematically greater or equal value. +.It Dv STRPCT_RAI +Rounding away from infinity, towards negative innfinity, +to a mathematically smaller or equal value. +.El +.Pp +Any other value causes unspecified rounding behaviour. +.Pp +The +.Fn strspct_r +function is identical to +.Fn strpct_r +except uses signed values for the +.Fa numerator +and +.Fa denominator , +and so can return a result with a leading minus sign. +.Pp +The +.Fn strpct +and +.Fn strspct +functions are identical to +.Fn strpct_r +and +.Fn strspct_r +respectively, with the +.Fa rounding_mode +specified as +.Dv STRPCT_RTZ , +unless modified by an earlier call to +.Fn strpct_round . +.Pp +The +.Fn strpct_round +function sets the rounding mode used by subsequent calls of +.Fn strpct +and +.Fn strspct +to the +.Fa mode +specified, which must be one of those listed as a possible +value for the +.Fa rounding_mode +parameter of +.Fn strpct_r . +Alternatively, the +.Fa mode +may be +.Dv STRPCT_RQRY , +in which case the current rounding mode will not be altered. +In any case, the previous rounding mode is returned. +.Sh RETURN VALUES +.Fn strpct_r , +.Fn strspct_r , +.Fn strpct +and +.Fn strspct +always return a pointer to a NUL-terminated (unless +.Fa bufsiz +is +.Dv 0 ) +formatted string which +is placed in +.Fa buf . +.Pp +.Fn strpct_round +returns the rounding mode that was in use for +.Fn strpct +and +.Fn strspct +before the call. +.Sh EXAMPLES +.Bd -literal -offset indent +strpct(buf, sizeof(buf), 1, 16, 3); +\(rA "6.250" +strpct(buf, sizeof(buf), 1, 2, 0); +\(rA "50" +strpct_r(buf, sizeof(buf), 2, 3, 2, STRPCT_RTN) +\(rA "66.67" +strpct_r(buf, sizeof(buf), 2, 3, 2, STRPCT_RTZ) +\(rA "66.66" +.Ed +.Sh HISTORY +.Fn strpct +was originally implemented in +.Xr csh 1 +for +.Nx 1.3 . +It printed into a static buffer, was not locale aware, handled +.Ft unsigned long +numbers, and printed a +.Dq % +at the end of the number. +Other programs such as +.Xr df 1 +and +.Xr time 1 +started using it. +.Fn strpct +and +.Fn strspct +appeared separately in libutil for +.Nx 6.0 . +.Pp +.Fn strpct_r , +.Fn strspct_r +and +.Fn strpct_round +appeared in +.Nx 11.0 . +.Sh AUTHORS +.An Erik E. Fair Aq Mt fair@NetBSD.org +.An Roland Illig Aq Mt rillig@NetBSD.org +.Sh BUGS +If the supplied buffer size is insufficient for the +result (including a terminating nul +.Pq Sq \e0 +character), +the result will be silently truncated with only the most +significant digits included, the last of which will be +rounded using the requested method. +This is not useful. +If the buffer space is exhausted part way through a locale's (multi-byte) +radix character, even more bizarre behaviour is to be expected. +Always provide a buffer bigger than can possibly be needed. +.Pp +Rather than causing an abnormal process termination, +as it arguably should, a +.Fa denominator +specified as zero will be treated as if it were one. +.Pp +Using +.Dv STRPCT_RTZ +rather than +.Dv STRPCT_RTN +as the default rounding mode for +.Fn strpct +and +.Fn strspct +is for compatibility with historic practice, +not because it is the most useful mode. +That might be changed at some future time. diff --git a/static/netbsd/man3/strptime.3 b/static/netbsd/man3/strptime.3 new file mode 100644 index 00000000..9f94fad2 --- /dev/null +++ b/static/netbsd/man3/strptime.3 @@ -0,0 +1,443 @@ +.\" $NetBSD: strptime.3,v 1.40 2025/04/06 16:17:30 christos Exp $ +.\" +.\" Copyright (c) 1997, 1998, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This file was contributed to The NetBSD Foundation by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 6, 2025 +.Dt STRPTIME 3 +.Os +.Sh NAME +.Nm strptime +.Nd converts a character string to a time value +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft char * +.Fo strptime +.Fa "const char * restrict buf" +.Fa "const char * restrict format" +.Fa "struct tm * restrict timeptr" +.Fc +.Ft char * +.Fo strptime_l +.Fa "const char * restrict buf" +.Fa "const char * restrict format" +.Fa "struct tm * restrict timeptr" +.Fa "locale_t loc" +.Fc +.Sh DESCRIPTION +The +.Fn strptime +function converts the character string pointed to by +.Fa buf +according to the string pointed to by +.Fa format , +and fills in the elements of the structure pointed to by +.Fa timeptr . +The resulting values will be relative to the local time zone. +Thus, it can be considered the reverse operation of +.Xr strftime 3 . +The +.Fn strptime_l +function does the same as +.Fn strptime , +but takes an explicit locale in the +.Ft locale_t +.Fa loc +argument rather than using the current locale. +.Pp +The +.Fa format +string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters in +are compared directly against the corresponding characters in +.Fa buf ; +comparisons which fail will cause +.Fn strptime +to fail. +Whitespace characters in +.Fa format +match any number of whitespace characters in +.Fa buf , +including none. +All conversion specifications are identical to those described in +.Xr strftime 3 . +.Pp +Two-digit year values, including formats +.Fa %y +and +.Fa \&%D , +are now interpreted as beginning at 1969 per POSIX requirements. +Years 69-00 are interpreted in the 20th century (1969-2000), years +01-68 in the 21st century (2001-2068). +The +.Fa \&%U +and +.Fa %W +format specifiers accept any value within the range 00 to 53. +.Pp +If the +.Fa format +string does not contain enough conversion specifications to completely +specify the resulting +.Vt struct tm , +the unspecified members of +.Va timeptr +are left untouched. +For example, if +.Fa format +is +.Dq Li "%H:%M:%S" , +only +.Va tm_hour , +.Va tm_sec +.Va tm_min +will be modified. +If time relative to today is desired, initialize the +.Fa timeptr +structure with today's date before passing it to +.Fn strptime . +All ordinary characters in +are compared directly against the corresponding characters in +.Fa buf ; +comparisons which fail will cause +.Fn strptime +to fail. +Whitespace characters in +.Fa format +match any number of whitespace characters in +.Fa buf , +including none. +.Pp +A conversion specification consists of a percent sign +.Ql % +followed by one +or two conversion characters which specify the replacement required. +There must be white-space or other non-alphanumeric characters between any +two conversion specifications. +.Pp +Conversion of alphanumeric strings (such as month and weekday names) is +done without regard to case. +Conversion specifications which cannot be matched will cause +.Fn strptime +to fail. +.Pp +The LC_TIME category defines the locale values for the conversion +specifications. +The following conversion specifications are supported: +.Bl -tag -width "xxxx" +.It Cm \&%a +the day of week, using the locale's weekday names; +either the abbreviated or full name may be specified. +.It Cm \&%A +the same as +.Cm \&%a . +.It Cm \&%b +the month, using the locale's month names; +either the abbreviated or full name may be specified. +.It Cm \&%B +the same as +.Cm \&%b . +.It Cm \&%c +the date and time, using the locale's date and time format. +.It Cm \&%C +the century number [0,99]; +leading zeros are permitted but not required. +This conversion should be used in conjunction with the \&%y conversion. +.It Cm \&%d +the day of month [1,31]; +leading zeros are permitted but not required. +.It Cm \&%D +the date as %m/%d/%y. +.It Cm \&%e +the same as +.Cm \&%d . +.It Cm \&%F +the date as %Y-%m-%d +(the ISO 8601 date format). +.It Cm \&%g +the year corresponding to the ISO week number, without the century. +.Po +A +.Nx +extension. +.Pc +.It Cm \&%G +the year corresponding to the ISO week number, with the century. +.Po +A +.Nx +extension. +.Pc +.It Cm \&%h +the same as +.Cm \&%b . +.It Cm \&%H +the hour (24-hour clock) [0,23]; +leading zeros are permitted but not required. +.It Cm \&%I +the hour (12-hour clock) [1,12]; +leading zeros are permitted but not required. +.It Cm \&%j +the day number of the year [1,366]; +leading zeros are permitted but not required. +.It Cm \&%k +the same as +.Cm \&%H . +.It Cm \&%l +the same as +.Cm \&%I . +.It Cm \&%m +the month number [1,12]; +leading zeros are permitted but not required. +.It Cm \&%M +the minute [0,59]; +leading zeros are permitted but not required. +.It Cm \&%n +any white-space, including none. +.It Cm \&%p +the locale's equivalent of a.m. or p.m. +.It Cm \&%r +the time (12-hour clock) with %p, using the locale's time format. +.It Cm \&%R +the time as %H:%M. +.It Cm \&%S +the seconds [0,60]; +leading zeros are permitted but not required. +.It Cm \&%s +the number of seconds since the Epoch, UTC (see +.Xr mktime 3 ) . +.Po +A +.Nx +extension. +.Pc +.It Cm \&%t +any white-space, including none. +.It Cm \&%T +the time as %H:%M:%S. +.It Cm \&%u +the day of the week as a decimal number, where Monday = 1. +.Po +A +.Nx +extension. +.Pc +.It Cm \&%U +the week number of the year (Sunday as the first day of the week) +as a decimal number [0,53]; +leading zeros are permitted but not required. +All days in a year preceding the first Sunday are considered to be in week 0. +.It Cm \&%V +the ISO 8601:1988 week number as a decimal number. +If the week (starting on Monday) that contains January 1 has more than +three days in the new year, then it is considered the first week of the +year. +If it has fewer than four days in the new year, then it is considered +the last week of the previous year. +Weeks are numbered from 1 to 53. +.Po +A +.Nx +extension. +.Pc +.It Cm \&%w +the weekday as a decimal number [0,6], with 0 representing Sunday; +leading zeros are permitted but not required. +.It Cm \&%W +the week number of the year (Monday as the first day of the week) +as a decimal number [0,53]; +leading zeros are permitted but not required. +All days in a year preceding the first Monday are considered to be in week 0. +.It Cm \&%x +the date, using the locale's date format. +.It Cm \&%X +the time, using the locale's time format. +.It Cm \&%y +the year within the 20th century [69,99] or the 21st century [0,68]; +leading zeros are permitted but not required. +If specified in conjunction +with \&%C, specifies the year [0,99] within that century. +.It Cm \&%Y +the year, including the century (i.e., 1996). +.It Cm \&%z +an ISO 8601, RFC-2822, or RFC-3339 time zone specification. +.Po +A +.Nx +extension. +.Pc +This is one of the following: +.Bl -dash -offset indent -compact +.It +The offset from Coordinated Universal Time +.Pq Ql UTC +specified as: +.Bl -bullet -offset indent -compact +.It +[+-]hhmm +.It +[+-]hh:mm +.It +[+-]hh +.El +.It +.Ql UTC +specified as: +.Bl -bullet -offset indent -compact +.It +UTC +.Pq Ql Coordinated Universal Time +.It +GMT +.Pq Ql Greenwich Mean Time +.It +UT +.Pq Ql Universal Time +.It +Z +.Pq Ql Zulu Time +.El +.It +A three character US time zone specified as: +.Bl -bullet -offset indent -compact +.It +EDT +.It +EST +.It +CDT +.It +CST +.It +MDT +.It +MST +.It +PDT +.It +PST +.El +with the first letter standing for +.Ql Eastern +.Pq Dq E , +.Ql Central +.Pq Dq C , +.Ql Mountain +.Pq Dq M +or +.Ql Pacific +.Pq Dq P , +and the second letter standing for +.Ql Daylight +.Po +.Dq D +or summer +.Pc +time +or +.Ql Standard +.Pq Dq S +time +.It +a single letter military or nautical time zone specified as: +.Bl -bullet -offset indent -compact +.It +.Dq A +through +.Dq I +.It +.Dq K +through +.Dq Y +.It +.Dq J +.Pq non-nautical local time zone +.El +.It +An arbitrary timezone name that can be loaded from the database. +.El +.It Cm \&%Z +time zone name or no characters when time zone information is unavailable. +.Po +A +.Nx +extension. +.Pc +.It Cm \&%% +matches a literal `%'. +No argument is converted. +.El +.Ss Modified conversion specifications +For compatibility, certain conversion specifications can be modified +by the +.Cm E +and +.Cm O +modifier characters to indicate that an alternative format or specification +should be used rather than the one normally used by the unmodified +conversion specification. +As there are currently neither alternative formats +nor specifications supported by the system, the behavior will be as if the +unmodified conversion specification were used. +.Pp +Case is ignored when matching string items in +.Fa buf , +such as month and weekday names. +.Sh RETURN VALUES +If successful, the +.Fn strptime +function returns a pointer to the character following the last character +parsed. +Otherwise, a +.Dv NULL +pointer is returned. +.Sh SEE ALSO +.Xr ctime 3 , +.Xr isspace 3 , +.Xr localtime 3 , +.Xr strftime 3 , +.Xr tm 3 +.Sh STANDARDS +The +.Fn strptime +function conforms to +.St -xpg4 . +.Sh BUGS +The +.Cm \&%Z +format specifier only accepts time zone +abbreviations of the local time zone, +or the values +.Dq GMT +or +.Dq UTC . +This limitation is caused by the ambiguity +of overloaded time zone abbreviations, +for example EST is both Eastern Standard +Time and Eastern Australia Summer Time. diff --git a/static/netbsd/man3/strrchr.3 b/static/netbsd/man3/strrchr.3 new file mode 100644 index 00000000..9e46f9e8 --- /dev/null +++ b/static/netbsd/man3/strrchr.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strrchr.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strrchr.3,v 1.10 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd August 11, 2002 +.Dt STRRCHR 3 +.Os +.Sh NAME +.Nm strrchr +.Nd locate character in string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strrchr "const char *s" "int c" +.Sh DESCRIPTION +The +.Fn strrchr +function +locates the last occurrence of +.Fa c +(converted to a char) +in the string +.Fa s . +If +.Fa c +is +.Ql \e0 , +.Fn strrchr +locates the terminating +.Ql \e0 . +.Sh RETURN VALUES +The +.Fn strrchr +function +returns a pointer to the character, +or a null pointer if +.Fa c +does not occur anywhere in +.Fa s . +.Sh EXAMPLES +After the following call to +.Fn strrchr , +.Va p +will point to the string +.Qq obar : +.Bd -literal -offset indent +char *p; +char *s = "foobar"; + +p = strrchr(s, 'o'); +.Ed +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strrchr +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/strsep.3 b/static/netbsd/man3/strsep.3 new file mode 100644 index 00000000..e508c78d --- /dev/null +++ b/static/netbsd/man3/strsep.3 @@ -0,0 +1,120 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strsep.3 8.1 (Berkeley) 6/9/93 +.\" $NetBSD: strsep.3,v 1.20 2017/07/03 21:32:50 wiz Exp $ +.\" +.Dd August 12, 2006 +.Dt STRSEP 3 +.Os +.Sh NAME +.Nm strsep , +.Nm stresep +.Nd separate strings +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strsep "char **stringp" "const char *delim" +.Ft char * +.Fn stresep "char **stringp" "const char *delim" "int escape" +.Sh DESCRIPTION +The +.Fn strsep +function locates, in the nul-terminated string referenced by +.Fa *stringp , +the first occurrence of any character in the string +.Fa delim +(or the terminating +.Ql \e0 +character) and replaces it with a +.Ql \e0 . +The location of the next character after the delimiter character +(or +.Dv NULL , +if the end of the string was reached) is stored in +.Fa *stringp . +The original value of +.Fa *stringp +is returned. +.Pp +An +.Dq empty +field, i.e., one caused by two adjacent delimiter characters, +can be detected by comparing the location referenced by the pointer returned +by +.Fn strsep +to +.Ql \e0 . +.Pp +If +.Fa *stringp +is initially +.Dv NULL , +.Fn strsep +returns +.Dv NULL . +The +.Fn stresep +function also takes an escape character that allows quoting the delimiter +character so that it can be part of the source string. +.Sh EXAMPLES +The following uses +.Fn strsep +to parse a string, containing tokens delimited by white space, into an +argument vector: +.Bd -literal -offset indent +char **ap, *argv[10], *inputstring; + +for (ap = argv; ap < &argv[9] && + (*ap = strsep(&inputstring, " \et")) != NULL;) { + if (**ap != '\e0') + ap++; +} +.Ed +.Sh HISTORY +The +.Fn strsep +function +is intended as a replacement for the +.Fn strtok +function. +While the +.Fn strtok +function should be preferred for portability reasons (it conforms to +.St -ansiC ) +it is unable to handle empty fields, i.e., detect fields delimited by +two adjacent delimiter characters, or to be used for more than a single +string at a time. +The +.Fn strsep +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/strsignal.3 b/static/netbsd/man3/strsignal.3 new file mode 100644 index 00000000..9d5daa4a --- /dev/null +++ b/static/netbsd/man3/strsignal.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strerror.3 6.9 (Berkeley) 6/29/91 +.\" $NetBSD: strsignal.3,v 1.10 2009/07/22 19:48:27 kleink Exp $ +.\" +.Dd July 22, 2009 +.Dt STRSIGNAL 3 +.Os +.Sh NAME +.Nm strsignal +.Nd get signal description string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strsignal "int sig" +.Sh DESCRIPTION +The +.Fn strsignal +function returns a pointer to the language-dependent string describing +a signal. +.Pp +The array pointed to is not to be modified by the program, but may be +overwritten by subsequent calls to +.Fn strsignal . +.Sh SEE ALSO +.Xr intro 2 , +.Xr psignal 3 , +.Xr setlocale 3 +.\" .Sh STANDARDS +.\" The +.\" .Fn strsignal +.\" function conforms to +.\" .St -p1003.1-2008 . diff --git a/static/netbsd/man3/strspn.3 b/static/netbsd/man3/strspn.3 new file mode 100644 index 00000000..09382393 --- /dev/null +++ b/static/netbsd/man3/strspn.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strspn.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strspn.3,v 1.11 2006/10/16 08:48:45 wiz Exp $ +.\" +.Dd August 11, 2002 +.Dt STRSPN 3 +.Os +.Sh NAME +.Nm strspn +.Nd span a string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strspn "const char *s" "const char *charset" +.Sh DESCRIPTION +The +.Fn strspn +function +spans the initial part of the nul-terminated string +.Fa s +as long as the characters from +.Fa s +occur in string +.Fa charset . +.Sh RETURN VALUES +The +.Fn strspn +function +returns the number of characters spanned. +.Sh EXAMPLES +The following call to +.Fn strspn +will return 3, since the first three characters of string +.Fa s +are part of string +.Fa charset : +.Bd -literal -offset indent +char *s = "foobar"; +char *charset = "of"; +size_t span; + +span = strspn(s, charset); +.Ed +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strstr 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strspn +function +conforms to +.St -ansiC . diff --git a/static/netbsd/man3/strstr.3 b/static/netbsd/man3/strstr.3 new file mode 100644 index 00000000..85e0369a --- /dev/null +++ b/static/netbsd/man3/strstr.3 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2001 Mike Barcroft <mike@FreeBSD.org> +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strstr.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strstr.3,v 1.12 2014/09/24 18:43:21 wiz Exp $ +.\" +.Dd September 24, 2014 +.Dt STRSTR 3 +.Os +.Sh NAME +.Nm strstr , strcasestr , strnstr +.Nd locate a substring in a string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strstr "const char *big" "const char *little" +.Ft char * +.Fn strcasestr "const char *big" "const char *little" +.Ft char * +.Fn strnstr "const char *big" "const char *little" "size_t len" +.Sh DESCRIPTION +The +.Fn strstr +function +locates the first occurrence of the nul-terminated string +.Fa little +in the nul-terminated string +.Fa big . +.Pp +The +.Fn strcasestr +function is similar to +.Fn strstr , +but ignores the case of both strings. +The +.Fn strnstr +function +locates the first occurrence of the NUL-terminated string +.Fa little +in the string +.Fa big , +where not more than +.Fa len +characters are searched. +Characters that appear after a +.Ql \e0 +character are not searched. +Since the +.Fn strnstr +function is a +.Nx +specific API, it should only be used when portability is not a concern. +.Sh RETURN VALUES +If +.Fa little +is an empty string, +.Fa big +is returned; +if +.Fa little +occurs nowhere in +.Fa big , +.Dv NULL +is returned; +otherwise a pointer to the first character of the first occurrence of +.Fa little +is returned. +.Sh EXAMPLES +The following sets the pointer +.Va ptr +to the +.Qq Li Bar Baz +portion of +.Va largestring : +.Bd -literal -offset indent +const char *largestring = "Foo Bar Baz"; +const char *smallstring = "Bar"; +char *ptr; + +ptr = strstr(largestring, smallstring); +.Ed +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strtok 3 +.Sh STANDARDS +The +.Fn strstr +function +conforms to +.St -isoC . +.Sh HISTORY +The +.Fn strnstr +function originated in +.Fx . diff --git a/static/netbsd/man3/strsuftoll.3 b/static/netbsd/man3/strsuftoll.3 new file mode 100644 index 00000000..ffaca3e8 --- /dev/null +++ b/static/netbsd/man3/strsuftoll.3 @@ -0,0 +1,150 @@ +.\" $NetBSD: strsuftoll.3,v 1.11 2010/12/14 13:00:34 jruoho Exp $ +.\" +.\" Copyright (c) 2002,2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 14, 2010 +.Dt STRSUFTOLL 3 +.Os +.Sh NAME +.Nm strsuftoll , +.Nm strsuftollx +.Nd "convert a string to a long long, with suffix parsing" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft long long +.Fn strsuftoll "const char *desc" "const char *val" "long long min" "long long max" +.Ft long long +.Fn strsuftollx "const char *desc" "const char *val" "long long min" "long long max" "char *errbuf" "size_t errbuflen" +.Sh DESCRIPTION +The functions +.Fn strsuftoll +and +.Fn strsuftollx +convert +.Fa val +into a number of type +.Vt long long , +checking that the result is not smaller than +.Fa min +or larger than +.Fa max . +Two or more decimal numbers may be separated by an +.Dq x +to indicate a product. +.Pp +Each decimal number may have one of the following optional suffixes: +.Pp +.Bl -tag -width 3n -offset indent -compact +.It Em b +Block; multiply by 512 +.It Em k +Kibi; multiply by 1024 (1 KiB) +.It Em m +Mebi; multiply by 1048576 (1 MiB) +.It Em g +Gibi; multiply by 1073741824 (1 GiB) +.It Em t +Tebi; multiply by 1099511627776 (1 TiB) +.It Em w +Word; multiply by the number of bytes in an integer +.El +.Pp +In the case of an error (range overflow or an invalid number), +.Fn strsuftollx +places an error message into +.Fa errbuf +(which is +.Fa errbuflen +bytes long) and returns 0, +and +.Fn strsuftoll +displays that error and terminates the process. +The parameter +.Fa desc +is used to construct +.Fa errbuf . +.Pp +Neither +.Fa desc +nor +.Fa val +may be +.Dv NULL . +.Sh RETURN VALUES +The functions +.Fn strsuftoll +and +.Fn strsuftollx +return either the result of the conversion, +unless the value overflows or is not a number; +in the latter case, +.Fn strsuftoll +displays an error message and terminates the process with exit code +.Dv EXIT_FAILURE , +and +.Fn strsuftollx +returns with 0 and +.Fa errbuf +contains a non-empty error message. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ERANGE +The given string was out of range; the value converted has been clamped. +.El +.Sh SEE ALSO +.Xr errx 3 , +.Xr strtoll 3 , +.Xr orders 7 +.Sh BUGS +At least few limitations should be mentioned: +.Bl -bullet +.It +Both functions ignore the current locale. +.It +Neither +.Fn strsuftoll +nor +.Fn strsuftollx +fail gracefully in case of invalid, +.Dv NULL , +pointers. +.It +Arguably the return type should be +.Vt intmax_t +instead of +.Vt long long . +.It +The +.Fn strsuftollx +function is prone to buffer overflows if used incorrectly. +Arguably only +.Fn strsuftoll +should be exposed to a caller. +.El diff --git a/static/netbsd/man3/strtod.3 b/static/netbsd/man3/strtod.3 new file mode 100644 index 00000000..f8be2a6a --- /dev/null +++ b/static/netbsd/man3/strtod.3 @@ -0,0 +1,243 @@ +.\" $NetBSD: strtod.3,v 1.30 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strtod.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd November 4, 2016 +.Dt STRTOD 3 +.Os +.Sh NAME +.Nm strtod , +.Nm strtof , +.Nm strtold +.Nd convert +.Tn ASCII +string to double, float, or long double +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft double +.Fn strtod "const char * restrict nptr" "char ** restrict endptr" +.Ft float +.Fn strtof "const char * restrict nptr" "char ** restrict endptr" +.Ft long double +.Fn strtold "const char * restrict nptr" "char ** restrict endptr" +.Sh DESCRIPTION +The +.Fn strtod +function converts the initial portion of the string +pointed to by +.Fa nptr +to +.Em double +representation. +.Pp +The +.Fn strtof +function converts the initial portion of the string +pointed to by +.Fa nptr +to +.Em float +representation. +.Pp +The +.Fn strtold +function converts the initial portion of the string +pointed to by +.Fa nptr +to +.Em long double +representation. +.Pp +The expected form of the string is an optional plus +.Pq Sq + +or minus sign +.Pq Sq \- +followed by one of the following: +.Bl -dash +.It +a sequence of digits optionally containing +a decimal-point character, optionally followed by an exponent. +An exponent consists of an +.Sq E +or +.Sq e , +followed by an optional plus +or minus sign, followed by a sequence of digits. +.It +one of +.Li INF +or +.Li INFINITY , +ignoring case. +.It +one of +.Li NAN +or +.Li NAN(n-char-sequence-opt) , +ignoring case. +This implementation currently does not interpret such a sequence. +.El +.Pp +Leading white-space characters in the string (as defined by the +.Xr isspace 3 +function) are skipped. +.Sh RETURN VALUES +The +.Fn strtod , +.Fn strtof , +and +.Fn strtold +functions return the converted value, if any. +.Pp +A character sequence +.Li INF +or +.Li INFINITY +is converted to \*(If, +if supported, else to the largest finite floating-point number representable +on the machine (i.e., +.Tn VAX ) . +.Pp +A character sequence +.Li NAN +or +.Li NAN(n-char-sequence-opt) +is converted to a quiet \*(Na, if supported, else remains unrecognized (i.e., +.Tn VAX ) . +.Pp +If +.Fa endptr +is not +.Dv NULL , +a pointer to the character after the last character used +in the conversion is stored in the location referenced by +.Fa endptr . +.Pp +If no conversion is performed, zero is returned and the value of +.Fa nptr +is stored in the location referenced by +.Fa endptr . +.Pp +If the correct value is too large in magnitude to be represented +.Pq Sq overflow , +plus or minus +.Dv HUGE_VAL , +.Dv HUGE_VALF , +or +.Dv HUGE_VALL +is returned (according to the return type and sign of the value), and +.Er ERANGE +is stored in +.Va errno . +.Pp +If the correct value is too small in magnitude to be represented +normally with full precision +.Pq Sq underflow , +the closest subnormal value, or zero, is returned, and +.Er ERANGE +is stored in +.Va errno . +.Sh EXAMPLES +Since there is no out-of-band channel or sentinel value to indicate an +error, callers who wish to know whether there was overflow or underflow +must set +.Va errno +to zero before calling +.Fn strtod , +.Fn strtof , +or +.Fn strtold ; +in the case of no underflow or overflow, these functions preserve +.Va errno . +.Pp +To check for syntax errors, callers must +.Em also +check whether +.Fa endptr +was updated to reflect the true end of the string in order to determine +whether the full string was consumed or whether there were additional +erroneous characters in it. +.Bd -literal -offset abcd +char *end; +double d; + +\&... + +errno = 0; +d = strtod(s, &end); +if (end == s) + errx(EXIT_FAILURE, "invalid syntax"); +if (end[0] != '\e0') + errx(EXIT_FAILURE, "trailing garbage"); +if (errno) { + assert(errno == ERANGE); + assert(isinf(d) || d == 0 || + fpclassify(d) == FP_SUBNORMAL); + warnx("%s", isinf(d) ? "overflow" : "underflow"); +} +/* d is the best floating-point approximation to the number in s */ +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ERANGE +The conversion resulted in floating-point underflow or overflow. +.El +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr math 3 , +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn strtod +function +conforms to +.St -ansiC . +The +.Fn strtof +and +.Fn strtold +functions conform to +.St -isoC-99 . +.Sh HISTORY +The +.Fn strtof +and +.Fn strtold +functions appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/strtoi.3 b/static/netbsd/man3/strtoi.3 new file mode 100644 index 00000000..871649db --- /dev/null +++ b/static/netbsd/man3/strtoi.3 @@ -0,0 +1,301 @@ +.\" $NetBSD: strtoi.3,v 1.11 2024/07/24 08:55:08 kre Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strtol.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Created by Kamil Rytarowski, based on ID: +.\" NetBSD: strtol.3,v 1.31 2015/03/11 09:57:35 wiz Exp +.\" +.Dd July 24, 2024 +.Dt STRTOI 3 +.Os +.Sh NAME +.Nm strtoi , +.Nm strtoi_l +.Nd convert a string value to an intmax_t integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In inttypes.h +.Ft intmax_t +.Fo strtoi +.Fa "const char * restrict nptr" +.Fa "char ** restrict endptr" +.Fa "int base" +.Fa "intmax_t lo" +.Fa "intmax_t hi" +.Fa "int *rstatus" +.Fc +.In locale.h +.Ft intmax_t +.Fo strtoi_l +.Fa "const char * restrict nptr" +.Fa "char ** restrict endptr" +.Fa "int base" +.Fa "intmax_t lo" +.Fa "intmax_t hi" +.Fa "int *rstatus" +.Fa "locale_t loc" +.Fc +.Sh DESCRIPTION +The +.Fn strtoi +generates the +.Ft intmax_t +result value equivalent to the numeric string in +.Fa nptr . +The +.Fn strtoi +function internally uses +.Xr strtoimax 3 +and then ensures that the result is in the range +.Bq Fa lo No .. Fa hi . +In addition it places +a conversion status indicator, +.Dv 0 +if fully successful, +in the integer addressed by the +.Fa rstatus +argument, if that is not NULL, allowing the +.Dv errno +gymnastics that other similar functions require to be avoided. +The +.Fa rstatus +argument can be +.Dv NULL +if the conversion status is to be ignored. +.Pp +The operation of +.Fn strtoi +is unspecified if +.Fa lo +is greater than +.Fa hi . +.Pp +The string may begin with an arbitrary amount of white space +(as determined by +.Xr isspace 3 ) +followed by a single optional +.Ql + +or +.Ql - +sign. +If +.Fa base +is zero or 16, +the string may then include a +.Ql 0x +or +.Ql 0X +prefix, +after which there must immediately follow at least one hexadecimal digit, +and the number will be read in base 16; otherwise, +.\" if the +.\" .Fa base +.\" is zero or 2, +.\" the string may then include a +.\" .Ql 0b +.\" or +.\" .Ql 0B +.\" prefix, +.\" and the number will be read in base 2; otherwise, +a zero +.Fa base +is taken as 10 (decimal) unless the next character is +.Ql 0 , +in which case it is taken as 8 (octal). +.Pp +The remainder of the string is converted to the +.Em intmax_t +result in the obvious manner, +stopping at the end of the string +or at the first character which is not a valid digit +in the given base. +(In bases above 10, the letter +.Ql A +in either upper or lower case +represents 10, +.Ql B +represents 11, and so forth, with +.Ql Z +representing 35.) +.Pp +If +.Fa endptr +is not NULL, +.Fn strtoi +stores the address of the first character after those +which were converted in +.Fa *endptr . +If there were no digits at all, however, +or if the +.Fa base +is invalid, +.Fn strtoi +stores the original value of +.Fa nptr +in +.Fa *endptr . +(Thus, if +.Fa *nptr +is not +.Ql \e0 +but +.Fa **endptr +is +.Ql \e0 +on return, the entire string was valid.) +Note that converting an out of range value has no +impact upon the value placed into +.Fa *endptr . +.Pp +The +.Fn strtoi_l +function is identical, except uses the locale given by +.Fa loc +rather than the current locale, when determining what is white space to +be skipped before the conversion begins. +.Sh RETURN VALUES +The +.Fn strtoi +function, +returns the converted value, +or the closest value in the range specified by the +.Fa lo +and +.Fa hi +arguments, if the value converted was outside that range. +If +.Fa lo +is equal to +.Fa hi +and no overriding error occurs, +that value will always be returned. +.Pp +The +.Va errno +value from +.In errno.h , +is guaranteed to be left unchanged. +.Pp +Errors are stored as the conversion status error indicator, +taken from a subset of the values from +.In errno.h +in the +.Fa rstatus +argument, if that was not given as a NULL pointer. +See the ERRORS section below for the possible values. +.Sh EXAMPLES +The following example will always return a number in +.Dv [1..99] +range no matter what the input is, and warn if the conversion failed. +.Bd -literal -offset indent +int e; +intmax_t lval = strtoi(buf, NULL, 0, 1, 99, &e); +if (e) + warnc(e, "conversion of `%s' to a number failed, using %jd", + buf, lval); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ECANCELED +The string did not contain any characters that were converted. +If given +.Fa endptr +will be set to +.Fa nptr . +.It Bq Er EINVAL +The +.Ar base +is not between 2 and 36 and nor is it the special value 0. +If given +.Fa endptr +will be set to +.Fa nptr . +.It Bq Er ENOTSUP +The string contained non-numeric characters that did not get converted. +In this case, +.Fa endptr +points to the first unconverted character. +.It Bq Er ERANGE +The given string was out of range; the value converted has been clamped. +In this case, +.Fa endptr +points to the terminating +.Sq \e0 +if the +.Fa nptr +string was fully converted, or to the first unconverted character otherwise. +.El +.Pp +The validity of the provided base is checked first, and if that +fails, no further processing is attempted. +The range check is more important than the unconverted characters check, +and is given priority. +If a program needs to know if there were unconverted characters when an +out of range number has been provided, it needs to supply and test +.Fa endptr. +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr atoll 3 , +.Xr strtod 3 , +.Xr strtou 3 , +.Xr strtoimax 3 , +.Xr strtol 3 , +.Xr strtoll 3 , +.Xr strtoul 3 , +.Xr strtoull 3 , +.Xr warnc 3 +.Sh STANDARDS +The +.Fn strtoi +and +.Fn strtoi_l +functions are a +.Nx +extension. +.Sh HISTORY +The +.Fn strtoi +function first appeared in +.Nx 7 . +.Ox +introduced the +.Fn strtonum 3 +function for the same purpose, but its interface makes it impossible to +properly differentiate error conditions. +.Sh BUGS +Ignores the current locale while doing the numeric conversion, only +ASCII letters and digits are allowed, and no grouping characters. diff --git a/static/netbsd/man3/strtok.3 b/static/netbsd/man3/strtok.3 new file mode 100644 index 00000000..4d9c243f --- /dev/null +++ b/static/netbsd/man3/strtok.3 @@ -0,0 +1,177 @@ +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strtok.3 8.2 (Berkeley) 2/3/94 +.\" $NetBSD: strtok.3,v 1.24 2026/02/19 13:24:32 kre Exp $ +.\" +.Dd February 19, 2026 +.Dt STRTOK 3 +.Os +.Sh NAME +.Nm strtok, strtok_r +.Nd string tokens +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft char * +.Fn strtok "char * restrict str" "const char * restrict sep" +.Ft char * +.Fn strtok_r "char * restrict str" "const char * restrict sep" "char ** restrict lasts" +.Sh DESCRIPTION +The +.Fn strtok +function +is used to isolate sequential tokens in a nul-terminated string, +.Fa str . +These tokens are separated in the string by at least one of the +characters in +.Fa sep . +The first time that +.Fn strtok +is called, +.Fa str +should be specified; subsequent calls, wishing to obtain further tokens +from the same string, should pass a null pointer instead. +The separator string, +.Fa sep , +must be supplied each time, and may change between calls. +.Pp +The +.Fn strtok +function +returns a pointer to the beginning of each subsequent token in the string, +after replacing the separator character itself with a +.Dv NUL +character. +Separator characters at the beginning of the string or at the +continuation point are skipped so that zero length tokens +are not returned. +When no more tokens remain, a null pointer is returned. +.Pp +The +.Fn strtok_r +function implements the functionality of +.Fn strtok +but is passed an additional argument, +.Fa lasts , +which points to a user-provided pointer which is used by +.Fn strtok_r +to store state which needs to be kept between calls to scan the same string; +unlike +.Fn strtok , +it is not necessary to limit tokenizing to a single string at a time +when using +.Fn strtok_r . +.Sh EXAMPLES +The following will construct an array of pointers to each individual word in +the string +.Va s : +.Bd -literal -offset indent +#define MAXTOKENS 128 + +char s[512], *p, *tokens[MAXTOKENS+1]; +char *last; +int i = 0; + +snprintf(s, sizeof(s), "cat dog horse cow"); + +for ((p = strtok_r(s, " ", &last)); + (p != NULL && i < MAXTOKENS); + (p = strtok_r(NULL, " ", &last)), i++) { + tokens[i] = p; +} +tokens[i] = NULL; +.Ed +.Pp +That is, +.Li tokens[0] +will point to +.Qq cat , +.Li tokens[1] +will point to +.Qq dog , +.Li tokens[2] +will point to +.Qq horse , +and +.Li tokens[3] +will point to +.Qq cow . +.Pp +If the pointer variable +.Li p +is not +.Dv NULL +when the loop terminates, +there were more than +.Li MAXTOKENS +words in the input string. +.Sh SEE ALSO +.Xr index 3 , +.Xr memchr 3 , +.Xr rindex 3 , +.Xr strchr 3 , +.Xr strcspn 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strsep 3 , +.Xr strspn 3 , +.Xr strstr 3 +.Sh STANDARDS +The +.Fn strtok +function +conforms to +.St -ansiC . +The +.Fn strtok_r +function conforms to +.St -p1003.1c-95 . +The +.Pa restrict +keyword was added in +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh BUGS +The System V +.Fn strtok , +if handed a string containing only delimiter characters, +will not alter the next starting point, so that a call to +.Fn strtok +with a different (or empty) delimiter string +may return a +.Pf non- Dv NULL +value. +Since this implementation always alters the next starting point, +such a sequence of calls would always return +.Dv NULL . diff --git a/static/netbsd/man3/strtol.3 b/static/netbsd/man3/strtol.3 new file mode 100644 index 00000000..94555396 --- /dev/null +++ b/static/netbsd/man3/strtol.3 @@ -0,0 +1,320 @@ +.\" $NetBSD: strtol.3,v 1.40 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strtol.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd November 4, 2016 +.Dt STRTOL 3 +.Os +.Sh NAME +.Nm strtol , +.Nm strtoll , +.Nm strtoimax , +.Nm strtoq +.Nd convert string value to a long, long long, intmax_t or quad_t integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.In limits.h +.Ft long int +.Fn strtol "const char * restrict nptr" "char ** restrict endptr" "int base" +.Ft long long int +.Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base" +.Pp +.In inttypes.h +.Ft intmax_t +.Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base" +.Pp +.In sys/types.h +.In stdlib.h +.In limits.h +.Ft quad_t +.Fn strtoq "const char * restrict nptr" "char ** restrict endptr" "int base" +.Sh DESCRIPTION +The +.Fn strtol +function +converts the string in +.Fa nptr +to a +.Ft long int +value. +The +.Fn strtoll +function +converts the string in +.Fa nptr +to a +.Ft long long int +value. +The +.Fn strtoimax +function +converts the string in +.Fa nptr +to an +.Ft intmax_t +value. +The +.Fn strtoq +function +converts the string in +.Fa nptr +to a +.Ft quad_t +value. +.Pp +The conversion is done according to the given +.Fa base , +which must be between 2 and 36 inclusive, +or be the special value 0. +.Pp +The string may begin with an arbitrary amount of white space +(as determined by +.Xr isspace 3 ) +followed by a single optional +.Ql + +or +.Ql - +sign. +If +.Fa base +is zero or 16, +the string may then include a +.Ql 0x +or +.Ql 0X +prefix, +and the number will be read in base 16; otherwise, +.\" if the +.\" .Fa base +.\" is zero or 2, +.\" the string may then include a +.\" .Ql 0b +.\" or +.\" .Ql 0B +.\" prefix, +.\" and the number will be read in base 2; otherwise, +a zero +.Fa base +is taken as 10 (decimal) unless the next character is +.Ql 0 , +in which case it is taken as 8 (octal). +.Pp +The remainder of the string is converted to an appropriate value +in the obvious manner, +stopping at the first character which is not a valid digit in the given base. +(In bases above 10, the letter +.Ql A +in either upper or lower case +represents 10, +.Ql B +represents 11, and so forth, with +.Ql Z +representing 35.) +.Pp +If +.Fa endptr +is non-nil, the functions store the address of the first invalid character in +.Fa *endptr . +If there were no digits at all, however, +the functions store the original value of +.Fa nptr +in +.Fa *endptr . +(Thus, if +.Fa *nptr +is not +.Ql \e0 +but +.Fa **endptr +is +.Ql \e0 +on return, the entire string was valid.) +.Sh RETURN VALUES +The +.Fn strtol +function +returns the result of the conversion, +unless the value would underflow or overflow. +If an underflow occurs, +.Fn strtol +returns +.Dv LONG_MIN , +.Fn strtoll +returns +.Dv LLONG_MIN , +and +.Fn strtoimax +returns +.Dv INTMAX_MIN . +If an overflow occurs, +.Fn strtol +returns +.Dv LONG_MAX , +.Fn strtoll +returns +.Dv LLONG_MAX , +and +.Fn strtoimax +returns +.Dv INTMAX_MAX . +In these cases, +.Va errno +is set to +.Er ERANGE . +If the +.Fa base +argument is not supported then +.Va errno +is set to +.Er EINVAL +and the functions return 0. +.Pp +If no error occurs, +.Va errno +is left unchanged. +This behavior (which is unlike most library functions) is guaranteed +by the pertinent standards. +.Sh EXAMPLES +Because the return value of +.Fn strtol +cannot be used unambiguously to detect an error, +.Va errno +is left unchanged after a successful call. +To ensure that a string is a valid number (i.e., in range and containing no +trailing characters), clear +.Va errno +beforehand explicitly, then check it afterwards: +.Bd -literal -offset indent +char *ep; +long lval; + +\&... + +errno = 0; +lval = strtol(buf, &ep, 10); +if (ep == buf) + goto not_a_number; +if (*ep != '\e0') + goto trailing_garbage; +if (errno) { + assert(errno == ERANGE); + assert(lval == LONG_MAX || lval == LONG_MIN); + goto out_of_range; +} +.Ed +.Pp +This example will accept +.Dq 12 +but not +.Dq 12foo +or +.Dq 12\en . +If trailing whitespace is acceptable, further checks must be done on +.Va *ep ; +alternately, use +.Xr sscanf 3 . +.Pp +If +.Fn strtol +is being used instead of +.Xr atoi 3 , +error checking is further complicated because the desired return value is an +.Li int +rather than a +.Li long ; +however, on some architectures integers and long integers are the same size. +Thus the following is necessary: +.Bd -literal -offset indent +char *ep; +int ival; +long lval; + +\&... + +errno = 0; +lval = strtol(buf, &ep, 10); +if (ep == buf) + goto not_a_number; +if (*ep != '\e0') + goto trailing_garbage; +if (errno == ERANGE || lval < INT_MIN || INT_MAX < lval) + goto out_of_range; +assert(errno == 0); +assert(INT_MIN <= lval); +assert(lval <= INT_MAX); +ival = lval; +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Ar base +is not between 2 and 36 and does not contain the special value 0. +.It Bq Er ERANGE +The given string was out of range; the value converted has been clamped. +.El +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr atoll 3 , +.Xr strtod 3 , +.Xr strtou 3 , +.Xr strtoul 3 , +.Xr strtoull 3 , +.Xr strtoumax 3 +.Sh STANDARDS +The +.Fn strtol +function +conforms to +.St -ansiC . +The +.Fn strtoll +and +.Fn strtoimax +functions conform to +.St -isoC-99 . +.Pp +The +.Fn strtoq +function is a +.Bx +legacy function equivalent to +.Fn strtoll +and should not be used in a new code. +.Sh BUGS +Ignores the current locale. diff --git a/static/netbsd/man3/strtonum.3 b/static/netbsd/man3/strtonum.3 new file mode 100644 index 00000000..e109cd21 --- /dev/null +++ b/static/netbsd/man3/strtonum.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: strtonum.3,v 1.2 2015/01/19 11:47:41 wiz Exp $ +.\" $OpenBSD: strtonum.3,v 1.17 2013/08/14 06:32:28 jmc Exp $ +.\" +.\" Copyright (c) 2004 Ted Unangst +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 18, 2015 +.Dt STRTONUM 3 +.Os +.Sh NAME +.Nm strtonum +.Nd reliably convert string value to an integer +.Sh SYNOPSIS +.Vt #define _OPENBSD_SOURCE +.In stdlib.h +.Ft long long +.Fo strtonum +.Fa "const char *nptr" +.Fa "long long minval" +.Fa "long long maxval" +.Fa "const char **errstr" +.Fc +.Sh DESCRIPTION +The +.Fn strtonum +function converts the string in +.Fa nptr +to a +.Li long long +value. +.Pp +The string may begin with an arbitrary amount of whitespace +(as determined by +.Xr isspace 3 ) +followed by a single optional +.Ql + +or +.Ql - +sign. +.Pp +The remainder of the string is converted to a +.Li long long +value according to base 10. +.Pp +The value obtained is then checked against the provided +.Fa minval +and +.Fa maxval +bounds. +If +.Fa errstr +is non-null, +.Fn strtonum +stores an error string in +.Fa *errstr +indicating the failure. +.Sh RETURN VALUES +The +.Fn strtonum +function returns the result of the conversion, +unless the value would exceed the provided bounds or is invalid. +On error, 0 is returned, +.Va errno +is set, and +.Fa errstr +will point to an error message. +.Fa *errstr +will be set to +.Dv NULL +on success; +this fact can be used to differentiate +a successful return of 0 from an error. +.Sh EXAMPLES +Using +.Fn strtonum +correctly is meant to be simpler than the alternative functions. +.Bd -literal -offset indent +int iterations; +const char *errstr; + +iterations = strtonum(optarg, 1, 64, &errstr); +if (errstr) + errx(1, "number of iterations is %s: %s", errstr, optarg); +.Ed +.Pp +The above example will guarantee that the value of iterations is between +1 and 64 (inclusive). +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The given string did not consist solely of digit characters; or +.Ar minval +was larger than +.Ar maxval . +.It Bq Er ERANGE +The given string was out of range. +.El +.Pp +If an error occurs, +.Fa errstr +will be set to one of the following strings: +.Pp +.Bl -tag -width "too largeXX" -compact +.It Qq too large +The result was larger than the provided maximum value. +.It Qq too small +The result was smaller than the provided minimum value. +.It Qq invalid +The string did not consist solely of digit characters. +.El +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr atoll 3 , +.Xr sscanf 3 , +.Xr strtod 3 , +.Xr strtoi 3 , +.Xr strtol 3 , +.Xr strtoll 3 , +.Xr strtou 3 , +.Xr strtoul 3 , +.Xr strtoull 3 +.Sh STANDARDS +.Fn strtonum +is an +.Ox +extension. +.Sh HISTORY +The +.Fn strtonum +function first appeared in +.Ox 3.6 . +.Fn strtonum +was redesigned in +.Nx 8 +as +.Fn strtoi 3 +and +.Fn strtou 3 . +For compatibility reasons it's available since +.Nx 8 +in the +.Vt _OPENBSD_SOURCE +namespace. +.Sh CAVEATS +The +.Fn strtonum +function was designed to facilitate safe, +robust programming and overcome the shortcomings of the +.Xr atoi 3 +and +.Xr strtol 3 +family of interfaces, however there are problems with the +.Fn strtonum +API: +.Bl -dash +.It +will return 0 on failure; 0 might not be in range, so that necessitates +an error check even if you want to avoid it +.It +does not differentiate 'illegal' returns, so we can't tell the +difference between partial and no conversions +.It +returns english strings +.It +can't set the base, or find where the conversion ended +.It +hardcodes long long integer type +.El +To overcome the shortcomings of +.Fn strtonum +.Nx +provides +.Fn strtou 3 +and +.Fn strtoi 3 . diff --git a/static/netbsd/man3/strtoul.3 b/static/netbsd/man3/strtoul.3 new file mode 100644 index 00000000..c667bdb9 --- /dev/null +++ b/static/netbsd/man3/strtoul.3 @@ -0,0 +1,292 @@ +.\" $NetBSD: strtoul.3,v 1.37 2017/07/03 21:32:50 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strtoul.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd November 13, 2015 +.Dt STRTOUL 3 +.Os +.Sh NAME +.Nm strtoul , +.Nm strtoull , +.Nm strtoumax , +.Nm strtouq +.Nd convert a string to an unsigned long, unsigned long long, uintmax_t or u_quad_t integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.In limits.h +.Ft unsigned long int +.Fn strtoul "const char * restrict nptr" "char ** restrict endptr" "int base" +.Ft unsigned long long int +.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base" +.Pp +.In inttypes.h +.Ft uintmax_t +.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base" +.Pp +.In sys/types.h +.In stdlib.h +.In limits.h +.Ft u_quad_t +.Fn strtouq "const char * restrict nptr" "char ** restrict endptr" "int base" +.Sh DESCRIPTION +The +.Fn strtoul +function +converts the string in +.Fa nptr +to an +.Ft unsigned long int +value. +The +.Fn strtoull +function +converts the string in +.Fa nptr +to an +.Ft unsigned long long int +value. +The +.Fn strtoumax +function +converts the string in +.Fa nptr +to an +.Ft uintmax_t +value. +The +.Fn strtouq +function +converts the string in +.Fa nptr +to a +.Ft u_quad_t +value. +.Pp +The conversion is done according to the given +.Fa base , +which must be between 2 and 36 inclusive, +or be the special value 0. +.Pp +The string may begin with an arbitrary amount of white space +(as determined by +.Xr isspace 3 ) +followed by a single optional +.Ql + +or +.Ql - +sign. +If +.Fa base +is zero or 16, +the string may then include a +.Ql 0x +or +.Ql 0X +prefix, +and the number will be read in base 16; otherwise, +.\" if the +.\" .Fa base +.\" is zero or 2, +.\" the string may then include a +.\" .Ql 0b +.\" or +.\" .Ql 0B +.\" prefix, +.\" and the number will be read in base 2; otherwise, +a zero +.Fa base +is taken as 10 (decimal) unless the next character is +.Ql 0 , +in which case it is taken as 8 (octal). +.Pp +The remainder of the string is converted to an appropriate +value in the obvious manner, +stopping at the end of the string +or at the first character that does not produce a valid digit +in the given base. +(In bases above 10, the letter +.Ql A +in either upper or lower case +represents 10, +.Ql B +represents 11, and so forth, with +.Ql Z +representing 35.) +.Pp +If +.Fa endptr +is non-nil, the functions store the address of the first invalid character in +.Fa *endptr . +If there were no digits at all, however, +the functions store the original value of +.Fa nptr +in +.Fa *endptr . +(Thus, if +.Fa *nptr +is not +.Ql \e0 +but +.Fa **endptr +is +.Ql \e0 +on return, the entire string was valid.) +.Sh RETURN VALUES +The +.Fn strtoul +function +returns either the result of the conversion +or, if there was a leading minus sign, +the negation of the result of the conversion, +unless the original (non-negated) value would overflow; +in the latter case, +.Fn strtoul +returns +.Dv ULONG_MAX , +.Fn strtoull +returns +.Dv ULLONG_MAX , +.Fn strtoumax +returns +.Dv UINTMAX_MAX , +.Fn strtouq +returns +.Dv UQUAD_MAX , +and the global variable +.Va errno +is set to +.Er ERANGE . +.Pp +There is no way to determine if +.Fn strtoul +has processed a negative number (and returned an unsigned value) short of +examining the string in +.Fa nptr +directly. +If the +.Fa base +argument is not supported then +.Va errno +is set to +.Er EINVAL +and the functions return 0. +.Pp +If no error occurs, +.Va errno +is left unchanged. +This behavior (which is unlike most library functions) is guaranteed +by the pertinent standards. +.Sh EXAMPLES +Because the return value of +.Fn strtoul +cannot be used unambiguously to detect an error, +.Va errno +is left unchanged after a successful call. +To ensure that a string is a valid number (i.e., in range and containing no +trailing characters), clear +.Va errno +beforehand explicitly, then check it afterwards: +.Bd -literal -offset indent +char *ep; +unsigned long ulval; + +\&... + +errno = 0; +ulval = strtoul(buf, &ep, 10); +if (ep == buf) + goto not_a_number; +if (*ep != '\e0') + goto trailing_garbage; +if (errno) { + assert(errno == ERANGE); + assert(ulval == ULONG_MAX); + goto out_of_range; +} +.Ed +.Pp +This example will accept +.Dq 12 +but not +.Dq 12foo +or +.Dq 12\en . +If trailing whitespace is acceptable, further checks must be done on +.Va *ep ; +alternately, use +.Xr sscanf 3 . +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Ar base +is not between 2 and 36 and does not contain the special value 0. +.It Bq Er ERANGE +The given string was out of range; the value converted has been clamped. +.El +.Sh SEE ALSO +.Xr atof 3 , +.Xr atoi 3 , +.Xr atol 3 , +.Xr atoll 3 , +.Xr strtod 3 , +.Xr strtoi 3 , +.Xr strtoimax 3 , +.Xr strtol 3 , +.Xr strtoll 3 , +.Xr strtou 3 +.Sh STANDARDS +The +.Fn strtoul +function +conforms to +.St -ansiC . +The +.Fn strtoull +and +.Fn strtoumax +functions conform to +.St -isoC-99 . +.Pp +The +.Fn strtouq +function is a +.Bx +legacy function equivalent to +.Fn strtoull +and should not be used in a new code. +.Sh BUGS +Ignores the current locale. diff --git a/static/netbsd/man3/strxfrm.3 b/static/netbsd/man3/strxfrm.3 new file mode 100644 index 00000000..6bb66e88 --- /dev/null +++ b/static/netbsd/man3/strxfrm.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strxfrm.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: strxfrm.3,v 1.12 2019/03/18 02:15:21 mrg Exp $ +.\" +.Dd March 6, 2019 +.Dt STRXFRM 3 +.Os +.Sh NAME +.Nm strxfrm +.Nd transform a string under locale +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft size_t +.Fn strxfrm "char * restrict dst" "const char * restrict src" "size_t n" +.Sh DESCRIPTION +The +.Fn strxfrm +function does something horrible. +The idea is to +.Dq un-localize +a string: the function transforms +.Ar src , +storing the result in +.Ar dst , +such that +.Xr strcmp 3 +on transformed strings returns what +.Xr strcoll 3 +on the original untransformed strings would return. +.Sh SEE ALSO +.Xr bcmp 3 , +.Xr memcmp 3 , +.\" .Xr setlocale 3 , +.Xr strcasecmp 3 , +.Xr strcmp 3 , +.Xr strcoll 3 +.Sh STANDARDS +The +.Fn strxfrm +function +conforms to +.St -ansiC . +.Sh BUGS +Since locales are not fully implemented on +.Nx , +.Fn strxfrm +just returns a copy of the original string. diff --git a/static/netbsd/man3/stty.3 b/static/netbsd/man3/stty.3 new file mode 100644 index 00000000..d9f83a86 --- /dev/null +++ b/static/netbsd/man3/stty.3 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)stty.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: stty.3,v 1.11 2022/12/04 01:29:32 uwe Exp $ +.\" +.Dd September 2, 2019 +.Dt STTY 3 +.Os +.Sh NAME +.Nm stty , +.Nm gtty +.Nd set and get terminal state (defunct) +.Sh LIBRARY +.Lb libcompat +.Sh SYNOPSIS +.In sgtty.h +.Fn stty "int fd" "struct sgttyb *buf" +.Fn gtty "int fd" "struct sgttyb *buf" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are obsoleted by +.Xr ioctl 2 . +They are available from the compatibility library, libcompat. +.Ef +.Pp +The +.Fn stty +function +sets the state of the terminal associated with +.Fa fd . +The +.Fn gtty +function +retrieves the state of the terminal associated +with +.Fa fd . +To set the state of a terminal the call must have +write permission. +.Pp +The +.Fn stty +call is actually +.Ql ioctl(fd, TIOCSETP, buf) , +while +the +.Fn gtty +call is +.Ql ioctl(fd, TIOCGETP, buf) . +See +.Xr ioctl 2 +and +.Xr tty 4 +for an explanation. +.Sh RETURN VALUES +.Rv -std gtty stty +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr tty 4 +.Sh HISTORY +The +.Fn stty +and +.Fn gtty +functions appeared in +.At v1 . +Obsoleted by +.Xr ioctl 2 , +these functions were moved to libcompat in +.Bx 4.2 . diff --git a/static/netbsd/man3/swab.3 b/static/netbsd/man3/swab.3 new file mode 100644 index 00000000..7c91e6b8 --- /dev/null +++ b/static/netbsd/man3/swab.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)swab.3 8.1 (Berkeley) 6/4/93 +.\" $NetBSD: swab.3,v 1.15 2010/04/30 03:52:13 jruoho Exp $ +.\" +.Dd April 30, 2010 +.Dt SWAB 3 +.Os +.Sh NAME +.Nm swab +.Nd swap adjacent bytes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn swab "const void * restrict src" "void * restrict dst" "ssize_t len" +.Sh DESCRIPTION +The function +.Fn swab +copies +.Fa len +bytes from the location referenced by +.Fa src +to the location referenced by +.Fa dst , +swapping adjacent bytes. +.Pp +If +.Fa len +is negative or zero, +.Fn swab +does nothing. +If +.Fa len +is odd, +.Fn swab +copies +.Fa len - 1 +bytes and the disposition of the last byte is unspecified. +.Sh SEE ALSO +.Xr bzero 3 , +.Xr memset 3 +.Sh STANDARDS +The +.Fn swab +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +A +.Fn swab +function appeared in +.At v7 . +It was originally documented to be +.Dq useful for carrying binary data between PDP11's and other machines . +.Pp +In +.Nx 6.0 +the type of +.Fa len +was changed from +.Vt size_t +to +.Vt ssize_t +for +.Tn POSIX +compliance. diff --git a/static/netbsd/man3/swapon.3 b/static/netbsd/man3/swapon.3 new file mode 100644 index 00000000..38ac7ed2 --- /dev/null +++ b/static/netbsd/man3/swapon.3 @@ -0,0 +1,121 @@ +.\" $NetBSD: swapon.3,v 1.16 2010/05/31 12:16:20 njoly Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)swapon.2 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt SWAPON 3 +.Os +.Sh NAME +.Nm swapon +.Nd add a swap device for interleaved paging/swapping +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn swapon "const char *special" +.Sh DESCRIPTION +.Bf -symbolic +.\" This interface is available from the compatibility library, libcompat and +This interface is provided for compatibility only and +has been obsoleted by +.Xr swapctl 2 . +.Ef +.Pp +.Fn swapon +makes the block device +.Fa special +available to the system for +allocation for paging and swapping. +The names of potentially available devices are known to the system +and defined at system configuration time. +The size of the swap area on +.Fa special +is calculated at the time the device is first made available +for swapping. +.Sh RETURN VALUES +If an error has occurred, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn swapon +succeeds unless: +.Bl -tag -width ENAMETOOLONG +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters, or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named device does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er ENOTBLK +.Fa special +is not a block device. +.It Bq Er EBUSY +The device specified by +.Fa special +has already +been made available for swapping +.It Bq Er EINVAL +The device configured by +.Fa special +was not +configured into the system as a swap device. +.It Bq Er ENXIO +The major device number of +.Fa special +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EIO +An I/O error occurred while opening the swap device. +.It Bq Er EFAULT +.Fa special +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr swapctl 2 , +.Xr swapctl 8 , +.Xr swapon 8 +.Sh HISTORY +The +.Fn swapon +function call appeared in +.Bx 4.0 +and was removed +.Nx 1.3 +.Sh BUGS +This call will be upgraded in future versions of the system. diff --git a/static/netbsd/man3/sysconf.3 b/static/netbsd/man3/sysconf.3 new file mode 100644 index 00000000..9e4180b1 --- /dev/null +++ b/static/netbsd/man3/sysconf.3 @@ -0,0 +1,362 @@ +.\" $NetBSD: sysconf.3,v 1.57 2024/03/21 22:27:55 uwe Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sysconf.3 8.3 (Berkeley) 4/19/94 +.\" +.Dd October 25, 2023 +.Dt SYSCONF 3 +.Os +.Sh NAME +.Nm sysconf +.Nd get configurable system variables +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn sysconf "int name" +.Sh DESCRIPTION +This interface is defined by +.St -p1003.1-88 . +A far more complete interface is available using +.Xr sysctl 3 . +.Pp +The +.Fn sysconf +function provides a method for applications to determine the current +value of a configurable system limit or option variable. +The +.Fa name +argument specifies the system variable to be queried. +Symbolic constants for each name value are found in the include file +.In unistd.h . +.Pp +The available values are as follows: +.Bl -tag -width Dv +.It Dv _SC_ARG_MAX +The maximum bytes of argument to +.Xr execve 2 . +.It Dv _SC_ATEXIT_MAX +The maximum number of functions that may be registered with +.Xr atexit 3 . +.It Dv _SC_BARRIERS +The version of +.St -p1003.1 +and its +Barriers +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_CLOCK_SELECTION +Return the +.Tn POSIX +version the implementation of the Clock Selection option +on this system conforms to, +or \-1 if unavailable. +.It Dv _SC_CHILD_MAX +The maximum number of simultaneous processes per user id. +.It Dv _SC_CLK_TCK +The number of clock ticks per second. +.It Dv _SC_FSYNC +Return 1 if the File Synchronization option is available on this system, +otherwise \-1. +.It Dv _SC_HOST_NAME_MAX +The maximum size of a hostname, including the terminating +.Tn NUL . +.It Dv _SC_IOV_MAX +The maximum number of +.Vt iovec +structures that a process has available for use with +.Xr preadv 2 , +.Xr pwritev 2 , +.Xr readv 2 , +.Xr recvmsg 2 , +.Xr sendmsg 2 +or +.Xr writev 2 . +.It Dv _SC_JOB_CONTROL +Return 1 if job control is available on this system, otherwise \-1. +.It Dv _SC_LOGIN_NAME_MAX +Returns the size of the storage required for a login name, in bytes, +including the terminating +.Tn NUL . +.It Dv _SC_MAPPED_FILES +Return 1 if the Memory Mapped Files option is available on this system, +otherwise \-1. +.It Dv _SC_MEMLOCK +Return 1 if the Process Memory Locking option is available on this system, +otherwise \-1. +.It Dv _SC_MEMLOCK_RANGE +Return 1 if the Range Memory Locking option is available on this system, +otherwise \-1. +.It Dv _SC_MEMORY_PROTECTION +Return 1 if the Memory Protection option is available on this system, +otherwise \-1. +.It Dv _SC_MONOTONIC_CLOCK +Return the +.Tn POSIX +version the implementation of the Monotonic Clock option +on this system conforms to, +or \-1 if unavailable. +.It Dv _SC_NGROUPS_MAX +The maximum number of supplemental groups. +.It Dv _SC_OPEN_MAX +The maximum number of open files per process. +.It Dv _SC_PAGESIZE +The size of a system page in bytes. +.It Dv _SC_PASS_MAX +The maximum length of the password, not counting the terminating +.Tn NUL . +.It Dv _SC_READER_WRITER_LOCKS +The version of +.St -p1003.1 +and its +Read-Write Locks +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_REGEXP +Return 1 if +.Tn POSIX +regular expressions are available on this system, otherwise \-1. +.It Dv _SC_SEMAPHORES +The version of +.St -p1003.1 +and its +Semaphores +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_SEM_NSEMS_MAX +The maximum number of semaphores that one process can have open at a time, +otherwise \-1. +.It Dv _SC_SHELL +Return 1 if +.Tn POSIX +shell is available on this system, otherwise \-1. +.It Dv _SC_SPIN_LOCKS +The version of +.St -p1003.1 +and its +Spin Locks +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_STREAM_MAX +The minimum maximum number of streams that a process may have open +at any one time. +.It Dv _SC_SYMLOOP_MAX +The maximum number of symbolic links that may be expanded in a path name. +.It Dv _SC_SYNCHRONIZED_IO +Return 1 if the Synchronized I/O option is available on this system, +otherwise \-1. +.It Dv _SC_THREADS +The version of +.St -p1003.1 +and its +Threads +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_THREAD_PRIO_PROTECT +System supports the priority ceiling protocol for POSIX threads. +.It Dv _SC_TIMERS +The version of +.St -p1003.1 +and its +Timers +option to which the system attempts to conform, +otherwise \-1. +.It Dv _SC_CPUTIME +The clockID +.Dv CLOCK_PROCESS_CPUTIME_ID +is supported, otherwise \-1. +.It Dv _SC_THREAD_CPUTIME +The clockID +.Dv CLOCK_THREAD_CPUTIME_ID +is supported, otherwise \-1. +.It Dv _SC_DELAYTIMER_MAX +The maximum number of overrun for a specific timer, +otherwise \-1. +.It Dv _SC_TZNAME_MAX +The minimum maximum number of types supported for the name of a +timezone. +.It Dv _SC_SAVED_IDS +Returns 1 if saved set-group and saved set-user ID is available, +otherwise \-1. +.It Dv _SC_VERSION +The version of ISO/IEC 9945 (POSIX 1003.1) with which the system +attempts to comply. +.It Dv _SC_XOPEN_SHM +Return 1 if the +.St -xpg4.2 +Shared Memory +option is available on this system, +otherwise \-1. +.Pp +Availability of the +Shared Memory +option depends on the +.Dv SYSVSHM +kernel option. +.It Dv _SC_BC_BASE_MAX +The maximum ibase/obase values in the +.Xr bc 1 +utility. +.It Dv _SC_BC_DIM_MAX +The maximum array size in the +.Xr bc 1 +utility. +.It Dv _SC_BC_SCALE_MAX +The maximum scale value in the +.Xr bc 1 +utility. +.It Dv _SC_BC_STRING_MAX +The maximum string length in the +.Xr bc 1 +utility. +.It Dv _SC_COLL_WEIGHTS_MAX +The maximum number of weights that can be assigned to any entry of +the LC_COLLATE order keyword in the locale definition file. +.It Dv _SC_EXPR_NEST_MAX +The maximum number of expressions that can be nested within +parenthesis by the +.Xr expr 1 +utility. +.It Dv _SC_LINE_MAX +The maximum length in bytes of a text-processing utility's input +line. +.It Dv _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression +permitted when using interval notation. +.It Dv _SC_2_VERSION +The version of POSIX 1003.2 with which the system attempts to comply. +.It Dv _SC_2_C_BIND +Return 1 if the system's C-language development facilities support the +C-Language Bindings option, otherwise \-1. +.It Dv _SC_2_C_DEV +Return 1 if the system supports the C-Language Development Utilities option, +otherwise \-1. +.It Dv _SC_2_CHAR_TERM +Return 1 if the system supports at least one terminal type capable of +all operations described in POSIX 1003.2, otherwise \-1. +.It Dv _SC_2_FORT_DEV +Return 1 if the system supports the FORTRAN Development Utilities option, +otherwise \-1. +.It Dv _SC_2_FORT_RUN +Return 1 if the system supports the FORTRAN Runtime Utilities option, +otherwise \-1. +.It Dv _SC_2_LOCALEDEF +Return 1 if the system supports the creation of locales, otherwise \-1. +.It Dv _SC_2_SW_DEV +Return 1 if the system supports the Software Development Utilities option, +otherwise \-1. +.It Dv _SC_2_UPE +Return 1 if the system supports the User Portability Utilities option, +otherwise \-1. +.It Dv _SC_GETGR_R_SIZE_MAX +The minimum size of the +.Fa buffer +passed to +.Xr getgrgid_r 3 +and +.Xr getgrnam_r 3 . +.It Dv _SC_GETPW_R_SIZE_MAX +The minimum size of the +.Fa buffer +passed to +.Xr getpwnam_r 3 +and +.Xr getpwuid_r 3 . +.It Dv _SC_NPROCESSORS_CONF +The number of processors configured. +.It Dv _SC_NPROCESSORS_ONLN +The number of processors online (capable of running processes). +.It Dv _SC_PHYS_PAGES +The total number of pages of physical memory. +See +.Dv _SC_PAGESIZE +for the system page size. +.It Dv _SC_AVPHYS_PAGES +The number of available pages of physical memory. +See +.Dv _SC_PAGESIZE +for the system page size. +.It Dv _SC_TIMER_MAX +The number of timers available for +.Xr timer_create 2 . +This is also known as +.Dv _POSIX_TIMER_MAX . +.El +.Sh RETURN VALUES +If the call to +.Nm sysconf +is not successful, \-1 is returned and +.Va errno +is set appropriately. +Otherwise, if the variable is associated with functionality that is not +supported, \-1 is returned and +.Va errno +is not modified. +Otherwise, the current variable value is returned. +.Sh ERRORS +The +.Fn sysconf +function may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr sysctl 3 . +In addition, the following error may be reported: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa name +argument is invalid. +.El +.Sh SEE ALSO +.Xr getconf 1 , +.Xr limits 3 , +.Xr sysctl 3 +.Sh STANDARDS +The +.Fn sysconf +function conforms to +.St -p1003.1-90 . +The constants +.Dv _SC_NPROCESSORS_CONF +and +.Dv _SC_NPROCESSORS_ONLN +are not part of the standard, but are provided by many systems. +.Sh HISTORY +The +.Nm sysconf +function first appeared in +.Bx 4.4 . +.Sh BUGS +The value for +.Dv _SC_STREAM_MAX +is a minimum maximum, and required to be the same as +.Tn ANSI C Ap s +.Dv FOPEN_MAX , +so the returned value is a ridiculously small and misleading number. diff --git a/static/netbsd/man3/sysctl.3 b/static/netbsd/man3/sysctl.3 new file mode 100644 index 00000000..d3c4e00a --- /dev/null +++ b/static/netbsd/man3/sysctl.3 @@ -0,0 +1,753 @@ +.\" $NetBSD: sysctl.3,v 1.207 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sysctl.3 8.4 (Berkeley) 5/9/95 +.\" +.Dd September 14, 2019 +.Dt SYSCTL 3 +.Os +.Sh NAME +.Nm sysctl , +.Nm sysctlbyname , +.Nm sysctlgetmibinfo , +.Nm sysctlnametomib , +.Nm asysctl , +.Nm asysctlbyname +.Nd get or set system information +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/sysctl.h +.Ft int +.Fn sysctl "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" \ +"const void *newp" "size_t newlen" +.Ft int +.Fn sysctlbyname "const char *sname" "void *oldp" "size_t *oldlenp" \ +"const void *newp" "size_t newlen" +.Ft int +.Fn sysctlgetmibinfo "const char *sname" "int *name" "u_int *namelenp" \ +"char *cname" "size_t *csz" "struct sysctlnode **rnode" "int v" +.Ft int +.Fn sysctlnametomib "const char *sname" "int *name" "size_t *namelenp" +.Ft void * +.Fn asysctl "const int *name" "size_t namelen" "size_t *len" +.Ft void * +.Fn asysctlbyname "const char *sname" "size_t *len" +.Sh DESCRIPTION +The +.Nm +function retrieves system information and allows processes with +appropriate privileges to set system information. +The information available from +.Nm +consists of integers, strings, and tables. +Information may be retrieved and set from the command interface +using the +.Xr sysctl 8 +utility. +.Pp +Unless explicitly noted below, +.Nm +returns a consistent snapshot of the data requested. +Consistency is obtained by locking the destination +buffer into memory so that the data may be copied out without blocking. +Calls to +.Nm +are serialized to avoid deadlock. +.Pp +The state is described using a ``Management Information Base'' (MIB) +style name, listed in +.Fa name , +which is a +.Fa namelen +length array of integers. +.Pp +The +.Fn sysctlbyname +function accepts a string representation of a MIB entry and internally +maps it to the appropriate numeric MIB representation. +Its semantics are otherwise no different from +.Fn sysctl . +.Pp +The information is copied into the buffer specified by +.Fa oldp . +The size of the buffer is given by the location specified by +.Fa oldlenp +before the call, +and that location gives the amount of data copied after a successful call. +If the amount of data available is greater +than the size of the buffer supplied, +the call supplies as much data as fits in the buffer provided +and returns with the error code +.Er ENOMEM . +If the old value is not desired, +.Fa oldp +and +.Fa oldlenp +should be set to +.Dv NULL . +.Pp +The size of the available data can be determined by calling +.Nm +with a +.Dv NULL +parameter for +.Fa oldp . +The size of the available data will be returned in the location pointed to by +.Fa oldlenp . +For some operations, the amount of space may change often. +For these operations, +the system attempts to round up so that the returned size is +large enough for a call to return the data shortly thereafter. +.Pp +To set a new value, +.Fa newp +is set to point to a buffer of length +.Fa newlen +from which the requested value is to be taken. +If a new value is not to be set, +.Fa newp +should be set to +.Dv NULL +and +.Fa newlen +set to 0. +.Pp +The +.Fn sysctlnametomib +function can be used to map the string representation of a MIB entry +to the numeric version. +The +.Fa name +argument should point to an array of integers large enough to hold the +MIB, and +.Fa namelenp +should indicate the number of integer slots available. +Following a successful translation, the size_t indicated by +.Fa namelenp +will be changed to show the number of slots consumed. +.Pp +The +.Fn sysctlgetmibinfo +function performs name translation similar to +.Fn sysctlnametomib , +but also canonicalizes the name (or returns the first erroneous token +from the string being parsed) into the space indicated by +.Fa cname +and +.Fa csz . +.Fa csz +should indicate the size of the buffer pointed to by +.Fa cname +and on return, will indicate the size of the returned string including +the trailing +.Sq nul +character. +.Pp +The +.Fa rnode +and +.Fa v +arguments to +.Fn sysctlgetmibinfo +are used to provide a tree for it to parse into, and to get back +either a pointer to, or a copy of, the terminal node. +If +.Fa rnode +is +.Dv NULL , +.Fn sysctlgetmibinfo +uses its own internal tree for parsing, and checks it against the +kernel at each call, to make sure that the name-to-number mapping is +kept up to date. +The +.Fa v +argument is ignored in this case. +If +.Fa rnode +is not +.Dv NULL +but the pointer it references is, on a successful return, +.Fa rnode +will be adjusted to point to a copy of the terminal node. +The +.Fa v +argument indicates which version of the +.Nm +node structure the caller wants. +The application must later +.Fn free +this copy. +If neither +.Fa rnode +nor the pointer it references are +.Dv NULL , +the pointer is used as the address of a tree over which the parsing is +done. +In this last case, the tree is not checked against the kernel, no +refreshing of the mappings is performed, and the value given by +.Fa v +must agree with the version indicated by the tree. +It is recommended that applications always use +.Dv SYSCTL_VERSION +as the value for +.Fa v , +as defined in the include file +.Pa sys/sysctl.h . +.Pp +The numeric and text names of sysctl variables are described in +.Xr sysctl 7 . +The numeric names are defined as preprocessor macros. +The top level names are defined with a CTL_ prefix in +.In sys/sysctl.h . +The next and subsequent levels down have different prefixes for each +subtree. +.Pp +For example, the following retrieves the maximum number of processes allowed +in the system - the +.Li kern.maxproc +variable: +.Bd -literal -offset indent -compact +int mib[2], maxproc; +size_t len; +.sp +mib[0] = CTL_KERN; +mib[1] = KERN_MAXPROC; +len = sizeof(maxproc); +sysctl(mib, 2, &maxproc, &len, NULL, 0); +.Ed +.sp +To retrieve the standard search path for the system utilities - +.Li user.cs_path : +.Bd -literal -offset indent -compact +int mib[2]; +size_t len; +char *p; +.sp +mib[0] = CTL_USER; +mib[1] = USER_CS_PATH; +sysctl(mib, 2, NULL, &len, NULL, 0); +p = malloc(len); +sysctl(mib, 2, p, &len, NULL, 0); +.Ed +.Pp +The +.Fn asysctl +and +.Fn asysctlbyname +functions are wrappers for +.Fn sysctl +and +.Fn sysctlbyname . +They return memory allocated with +.Xr malloc 3 +and resize the buffer in a loop until all data fits. +.Sh DYNAMIC OPERATIONS +Several meta-identifiers are provided to perform operations on the +.Nm +tree itself, or support alternate means of accessing the data +instrumented by the +.Nm +tree. +.Bl -column CTLXCREATESYMXXX +.It Sy Name Description +.It CTL\_QUERY Retrieve a mapping of names to numbers below a given node +.It CTL\_CREATE Create a new node +.It CTL\_CREATESYM Create a new node by its kernel symbol +.It CTL\_DESTROY Destroy a node +.It CTL\_DESCRIBE Retrieve node descriptions +.El +.Pp +The core interface to all of these meta-functions is the structure +that the kernel uses to describe the tree internally, as defined in +.In sys/sysctl.h +as: +.Bd -literal +struct sysctlnode { + uint32_t sysctl_flags; /* flags and type */ + int32_t sysctl_num; /* mib number */ + char sysctl_name[SYSCTL_NAMELEN]; /* node name */ + uint32_t sysctl_ver; /* node's version vs. rest of tree */ + uint32_t __rsvd; + union { + struct { + uint32_t suc_csize; /* size of child node array */ + uint32_t suc_clen; /* number of valid children */ + struct sysctlnode* suc_child; /* array of child nodes */ + } scu_child; + struct { + void *sud_data; /* pointer to external data */ + size_t sud_offset; /* offset to data */ + } scu_data; + int32_t scu_alias; /* node this node refers to */ + int32_t scu_idata; /* immediate "int" data */ + u_quad_t scu_qdata; /* immediate "u_quad_t" data */ + } sysctl_un; + size_t _sysctl_size; /* size of instrumented data */ + sysctlfn _sysctl_func; /* access helper function */ + struct sysctlnode *sysctl_parent; /* parent of this node */ + const char *sysctl_desc; /* description of node */ +}; + +#define sysctl_csize sysctl_un.scu_child.suc_csize +#define sysctl_clen sysctl_un.scu_child.suc_clen +#define sysctl_child sysctl_un.scu_child.suc_child +#define sysctl_data sysctl_un.scu_data.sud_data +#define sysctl_offset sysctl_un.scu_data.sud_offset +#define sysctl_alias sysctl_un.scu_alias +#define sysctl_idata sysctl_un.scu_idata +#define sysctl_qdata sysctl_un.scu_qdata +.Ed +.Pp +Querying the tree to discover the name to number mapping permits +dynamic discovery of all the data that the tree currently has +instrumented. +For example, to discover all the nodes below the +.Dv CTL_VFS +node: +.Pp +.Bd -literal -offset indent -compact +struct sysctlnode query, vfs[128]; +int mib[2]; +size_t len; +.sp +mib[0] = CTL_VFS; +mib[1] = CTL_QUERY; +memset(&query, 0, sizeof(query)); +query.sysctl_flags = SYSCTL_VERSION; +len = sizeof(vfs); +sysctl(mib, 2, &vfs[0], &len, &query, sizeof(query)); +.Ed +.Pp +Note that a reference to an empty node with +.Fa sysctl_flags +set to +.Dv SYSCTL_VERSION +is passed to sysctl in order to indicate the version that the program +is using. +All dynamic operations passing nodes into sysctl require that the +version be explicitly specified. +.Pp +Creation and destruction of nodes works by constructing part of a new +node description (or a description of the existing node) and invoking +.Dv CTL_CREATE +(or +.Dv CTL_CREATESYM ) +or +.Dv CTL_DESTROY +at the parent of the new +node, with a pointer to the new node passed via the +.Fa new +and +.Fa newlen +arguments. +If valid values for +.Fa old +and +.Fa oldlenp +are passed, a copy of the new node once in the tree will be returned. +If the create operation fails because a node with the same name or MIB +number exists, a copy of the conflicting node will be returned. +.Pp +The minimum requirements for creating a node are setting the +.Fa sysctl_flags +to indicate the new node's type, +.Fa sysctl_num +to either the new node's number (or +.Dv CTL_CREATE +or +.Dv CTL_CREATESYM +if a +dynamically allocated MIB number is acceptable), +.Fa sysctl_size +to the size of the data to be instrumented (which must agree with the +given type), and +.Fa sysctl_name +must be set to the new node's name. +Nodes that are not of type +.Dq node +must also have some description of the data to be instrumented, which +will vary depending on what is to be instrumented. +.Pp +If existing kernel data is to be covered by this new node, its address +should be given in +.Fa sysctl_data +or, if +.Dv CTL_CREATESYM +is used, +.Fa sysctl_data +should be set to a string containing its name from the kernel's symbol +table. +If new data is to be instrumented and an initial value is available, +the new integer or quad type data should be placed into either +.Fa sysctl_idata +or +.Fa sysctl_qdata , +respectively, along with the +.Dv CTLFLAG_IMMEDIATE +flag being set, or +.Fa sysctl_data +should be set to point to a copy of the new data, and the +.Dv CTLFLAG_OWNDATA +flag must be set. +This latter method is the only way that new string and struct type +nodes can be initialized. +Invalid kernel addresses are accepted, but any attempt to access those +nodes will return an error. +.Pp +The +.Fa sysctl_csize , +.Fa sysctl_clen , +.Fa sysctl_child , +.Fa sysctl_parent , +and +.Fa sysctl_alias +members are used by the kernel to link the tree together and must be +.Dv NULL +or 0. +Nodes created in this manner cannot have helper functions, so +.Fa sysctl_func +must also be +.Dv NULL . +If the +.Fa sysctl_ver +member is non-zero, it must match either the version of the parent or +the version at the root of the MIB or an error is returned. +This can be used to ensure that nodes are only added or removed from a +known state of the tree. +Note: It may not be possible to determine the version at the root +of the tree. +.Pp +This example creates a new subtree and adds a node to it that controls the +.Fa audiodebug +kernel variable, thereby making it tunable at at any time, without +needing to use +.Xr ddb 4 +or +.Xr kvm 3 +to alter the kernel's memory directly. +.Pp +.Bd -literal -offset indent -compact +struct sysctlnode node; +int mib[2]; +size_t len; +.sp +mib[0] = CTL_CREATE; /* create at top-level */ +len = sizeof(node); +memset(&node, 0, len); +node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_NODE; +snprintf(node.sysctl_name, sizeof(node.sysctl_name), "local"); +node.sysctl_num = CTL_CREATE; /* request dynamic MIB number */ +sysctl(&mib[0], 1, &node, &len, &node, len); +.sp +mib[0] = node.sysctl_num; /* use new MIB number */ +mib[1] = CTL_CREATESYM; /* create at second level */ +len = sizeof(node); +memset(&node, 0, len); +node.sysctl_flags = SYSCTL_VERSION|CTLFLAG_READWRITE|CTLTYPE_INT; +snprintf(node.sysctl_name, sizeof(node.sysctl_name), "audiodebug"); +node.sysctl_num = CTL_CREATE; +node.sysctl_data = "audiodebug"; /* kernel symbol to be used */ +sysctl(&mib[0], 2, NULL, NULL, &node, len); +.Ed +.Pp +The process for deleting nodes is similar, but less data needs to +be supplied. +Only the +.Fa sysctl_num +field +needs to be filled in; almost all other fields must be left blank. +The +.Fa sysctl_name +and/or +.Fa sysctl_ver +fields can be filled in with the name and version of the existing node +as additional checks on what will be deleted. +If all the given data fail to match any node, nothing will be deleted. +If valid values for +.Fa old +and +.Fa oldlenp +are supplied and a node is deleted, a copy of what was in the MIB tree +will be returned. +.Pp +This sample code shows the deletion of the two nodes created in the +above example: +.Pp +.Bd -literal -offset indent -compact +int mib[2]; +.sp +len = sizeof(node); +memset(&node, 0, len); +node.sysctl_flags = SYSCTL_VERSION; +.sp +mib[0] = 3214; /* assumed number for "local" */ +mib[1] = CTL_DESTROY; +node.sysctl_num = 3215; /* assumed number for "audiodebug" */ +sysctl(&mib[0], 2, NULL, NULL, &node, len); +.sp +mib[0] = CTL_DESTROY; +node.sysctl_num = 3214; /* now deleting "local" */ +sysctl(&mib[0], 1, NULL, NULL, &node, len); +.Ed +.Pp +Descriptions of each of the nodes can also be retrieved, if they are +available. +Descriptions can be retrieved in bulk at each level or on a per-node +basis. +The layout of the buffer into which the descriptions are returned is a +series of variable length structures, each of which describes its own +size. +The length indicated includes the terminating +.Sq nul +character. +Nodes that have no description or where the description is not +available are indicated by an empty string. +The +.Fa descr_ver +will match the +.Fa sysctl_ver +value for a given node, so that descriptions for nodes whose number +have been recycled can be detected and ignored or discarded. +.Bd -literal +struct sysctldesc { + int32_t descr_num; /* mib number of node */ + uint32_t descr_ver; /* version of node */ + uint32_t descr_len; /* length of description string */ + char descr_str[1]; /* not really 1...see above */ +}; +.Ed +.Pp +The +.Fn NEXT_DESCR +macro can be used to skip to the next description in the retrieved +list. +.Pp +.Bd -literal -offset indent -compact +struct sysctlnode desc; +struct sysctldesc *d; +char buf[1024]; +int mib[2]; +size_t len; +.sp +/* retrieve kern-level descriptions */ +mib[0] = CTL_KERN; +mib[1] = CTL_DESCRIBE; +d = (struct sysctldesc *)&buf[0]; +len = sizeof(buf); +sysctl(mib, 2, d, &len, NULL, 0); +while ((caddr_t)d < (caddr_t)&buf[len]) { + printf("node %d: %.*s\\n", d->descr_num, d->descr_len, + d->descr_str); + d = NEXT_DESCR(d); +} +.sp +/* retrieve description for kern.securelevel */ +memset(&desc, 0, sizeof(desc)); +desc.sysctl_flags = SYSCTL_VERSION; +desc.sysctl_num = KERN_SECURELEVEL; +d = (struct sysctldesc *)&buf[0]; +len = sizeof(buf); +sysctl(mib, 2, d, &len, &desc, sizeof(desc)); +printf("kern.securelevel: %.*s\\n", d->descr_len, d->descr_str); +.Ed +.Pp +Descriptions can also be set as follows, subject to the following rules: +.Pp +.Bl -bullet -compact +.It +The kernel securelevel is at zero or lower +.It +The caller has super-user privileges +.It +The node does not currently have a description +.It +The node is not marked as +.Dq permanent +.El +.Pp +.Bd -literal -offset indent -compact +struct sysctlnode desc; +int mib[2]; +.sp +/* presuming the given top-level node was just added... */ +mib[0] = 3214; /* mib numbers taken from previous examples */ +mib[1] = CTL_DESCRIBE; +memset(&desc, 0, sizeof(desc)); +desc.sysctl_flags = SYSCTL_VERSION; +desc.sysctl_num = 3215; +desc.sysctl_desc = "audio debug control knob"; +sysctl(mib, 2, NULL, NULL, &desc, sizeof(desc)); +.Ed +.Pp +Upon successfully setting a description, the new description will be +returned in the space indicated by the +.Fa oldp +and +.Fa oldlenp +arguments. +.Pp +The +.Fa sysctl_flags +field in the struct sysctlnode contains the sysctl version, node type +information, and a number of flags. +The macros +.Fn SYSCTL_VERS , +.Fn SYSCTL_TYPE , +and +.Fn SYSCTL_FLAGS +can be used to access the different fields. +Valid flags are: +.Bl -column CTLFLAGXPERMANENTXXX +.It Sy Name Description +.It CTLFLAG\_READONLY Node is read-only +.It CTLFLAG\_READWRITE Node is writable by the superuser +.It CTLFLAG\_ANYWRITE Node is writable by anyone +.It CTLFLAG\_PRIVATE Node is readable only by the superuser +.It CTLFLAG\_PERMANENT Node cannot be removed (cannot be set by +processes) +.It CTLFLAG\_OWNDATA Node owns data and does not instrument +existing data +.It CTLFLAG\_IMMEDIATE Node contains instrumented data and does not +instrument existing data +.It CTLFLAG\_HEX Node's contents should be displayed in a hexadecimal +form +.It CTLFLAG\_ROOT Node is the root of a tree (cannot be set at +any time) +.It CTLFLAG\_ANYNUMBER Node matches any MIB number (cannot be set by +processes) +.It CTLFLAG\_HIDDEN Node not displayed by default +.It CTLFLAG\_ALIAS Node refers to a sibling node (cannot be set +by processes) +.It CTLFLAG\_OWNDESC Node owns its own description string space +.El +.Sh RETURN VALUES +If the call to +.Nm +is successful, 0 is returned. +Otherwise \-1 is returned and +.Va errno +is set appropriately. +.Sh FILES +.Bl -tag -width <netinet6/udp6Xvar.h> -compact +.It Aq Pa sys/sysctl.h +definitions for top level identifiers, second level kernel and hardware +identifiers, and user level identifiers +.It Aq Pa sys/socket.h +definitions for second level network identifiers +.It Aq Pa sys/gmon.h +definitions for third level profiling identifiers +.It Aq Pa uvm/uvm_param.h +definitions for second level virtual memory identifiers +.It Aq Pa netinet/in.h +definitions for third level IPv4/v6 identifiers and +fourth level IPv4/v6 identifiers +.It Aq Pa netinet/icmp_var.h +definitions for fourth level ICMP identifiers +.It Aq Pa netinet/icmp6.h +definitions for fourth level ICMPv6 identifiers +.It Aq Pa netinet/tcp_var.h +definitions for fourth level TCP identifiers +.It Aq Pa netinet/udp_var.h +definitions for fourth level UDP identifiers +.It Aq Pa netinet6/udp6_var.h +definitions for fourth level IPv6 UDP identifiers +.It Aq Pa netipsec/ipsec.h +definitions for fourth level IPsec identifiers +.It Aq Pa netipsec/key_var.h +definitions for third level PF_KEY identifiers +.It Aq Pa machine/cpu.h +definitions for second level machdep identifiers +.El +.Sh ERRORS +The following errors may be reported: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer +.Fa name , +.Fa oldp , +.Fa newp , +or length pointer +.Fa oldlenp +contains an invalid address, or the requested value is temporarily +unavailable. +.It Bq Er EINVAL +The +.Fa name +array is zero or greater than +.Dv CTL_MAXNAME ; +or a non-null +.Fa newp +is given and its specified length in +.Fa newlen +is too large or too small, or the given value is not acceptable for +the given node. +.It Bq Er EISDIR +The +.Fa name +array specifies an intermediate rather than terminal name. +.It Bq Er ENOENT +The +.Fa name +array specifies a node that does not exist in the tree; +or an attempt was made to destroy a node that does not exist, or to +create or destroy a node below a node that does not exist. +.It Bq Er ENOMEM +The length pointed to by +.Fa oldlenp +is too short to hold the requested value. +.It Bq Er ENOTDIR +The +.Fa name +array specifies a node below a node that addresses data. +.It Bq Er ENOTEMPTY +An attempt was made to destroy a node that still has children. +.It Bq Er EOPNOTSUPP +The +.Fa name +array specifies a value that is unknown or a meta-operation was +attempted that the requested node does not support. +.It Bq Er EPERM +An attempt is made to set a read-only value; or +a process without appropriate privilege attempts to set a value or to +create or destroy a node; or +an attempt to change a value protected by the current kernel security +level is made. +.El +.Sh SEE ALSO +.Xr sysctl 7 , +.Xr sysctl 8 , +.Xr secmodel_securelevel 9 +.\" .Xr sysctl 9 +.Sh HISTORY +The +.Nm +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/syslog.3 b/static/netbsd/man3/syslog.3 new file mode 100644 index 00000000..24dd0100 --- /dev/null +++ b/static/netbsd/man3/syslog.3 @@ -0,0 +1,549 @@ +.\" $NetBSD: syslog.3,v 1.35 2024/07/11 06:04:13 riastradh Exp $ +.\" $OpenBSD: syslog.3,v 1.25 2005/07/22 03:16:58 jaredy Exp $ +.\" +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)syslog.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 2, 2024 +.Dt SYSLOG 3 +.Os +.Sh NAME +.Nm syslog , +.Nm syslog_r , +.Nm vsyslog , +.Nm vsyslog_r , +.Nm syslogp , +.Nm syslogp_r , +.Nm syslog_ss , +.Nm syslogp_ss , +.Nm vsyslogp , +.Nm vsyslogp_r , +.Nm vsyslog_ss , +.Nm vsyslogp_ss , +.Nm openlog , +.Nm openlog_r , +.Nm closelog , +.Nm closelog_r , +.Nm setlogmask , +.Nm setlogmask_r +.Nd control system log +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In syslog.h +.Ft void +.Fn syslog "int priority" "const char *message" "..." +.Ft void +.Fn syslog_r "int priority" "struct syslog_data *data" "const char *message" "..." +.Ft void +.Fn syslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "..." +.Ft void +.Fn syslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "..." +.Ft void +.Fn syslog_ss "int priority" "struct syslog_data *data" "const char *message" "..." +.Ft void +.Fn syslogp_ss "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "..." +.Ft void +.Fn openlog "const char *ident" "int logopt" "int facility" +.Ft void +.Fn openlog_r "const char *ident" "int logopt" "int facility" "struct syslog_data *data" +.Ft void +.Fn closelog void +.Ft void +.Fn closelog_r "struct syslog_data *data" +.Ft int +.Fn setlogmask "int maskpri" +.Ft int +.Fn setlogmask_r "int maskpri" "struct syslog_data *data" +.In stdarg.h +.Ft void +.Fn vsyslog "int priority" "const char *message" "va_list args" +.Ft void +.Fn vsyslog_r "int priority" "struct syslog_data *data" "const char *message" "va_list args" +.Ft void +.Fn vsyslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args" +.Ft void +.Fn vsyslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args" +.Ft void +.Fn vsyslog_ss "int priority" "struct syslog_data *data" "const char *message" "va_list args" +.Ft void +.Fn vsyslogp_ss "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args" +.Sh DESCRIPTION +The +.Fn syslog +function +writes +.Fa message +to the system message logger. +The message is then written to the system console, log files, +logged-in users, or forwarded to other machines as appropriate (see +.Xr syslogd 8 ) . +.Pp +The message is identical to a +.Xr printf 3 +format string, except that +.Ql %m +is replaced by the current error +message. +(As denoted by the global variable +.Va errno ; +see +.Xr strerror 3 . ) +A trailing newline is added if none is present. +.\" shouldn't the newline statement be removed? +.\" when logging through a socket a newline is +.\" not added nor is it required. -- ms +.Pp +The +.Fn syslog_r +function is a multithread-safe version of the +.Fn syslog +function. +It takes a pointer to a +.Fa syslog_data +structure which is used to store +information. +This parameter must be initialized before +.Fn syslog_r +is called. +The +.Dv SYSLOG_DATA_INIT +constant is used for this purpose. +The +.Fa syslog_data +structure and the +.Dv SYSLOG_DATA_INIT +constant are defined as: +.Bd -literal -offset indent +struct syslog_data { + int log_file; + int connected; + int opened; + int log_stat; + const char *log_tag; + int log_fac; + int log_mask; +}; + +#define SYSLOG_DATA_INIT { \e + .log_file = -1, \e + .log_fac = LOG_USER, \e + .log_mask = 0xff, \e +} +.Ed +.Pp +The structure is composed of the following elements: +.Bl -tag -width connected -offset indent +.It Va log_file +contains the file descriptor of the file where the message is logged +.It Va connected +indicates if connect has been done +.It Va opened +indicates if +.Fn openlog_r +has been called +.It Va log_stat +status bits, set by +.Fn openlog_r +.It Va log_tag +string to tag the entry with +.It Va log_fac +facility code +.It Va log_mask +mask of priorities to be logged +.El +.Pp +The +.Fn syslog_ss +is the async-signal-safe version of +.Fn syslog_r +and is also multithread-safe. +It has the following limitations: +.Bl -enum -offset indent +.It +The format string cannot contain multi-byte character sequences. +.It +Positional +.Xr printf 3 +arguments are not supported. +.It +Floating point formats are not supported and print +.Dq UNK . +.It +The time of the event is not sent to +.Xr syslogd 8 . +.It +The error string in the %m format is not printed symbolically but as +.Dq Error %d . +.El +.Pp +For more information about async-signal-safe functions and signal handlers, see +.Xr signal 7 . +.Pp +Similarly +.Fn vsyslog_ss +is the async-signal-safe version of +.Fn vsyslog_r . +Same for +.Fn syslogp_ss +and +.Fn syslogp_r , +and finally +.Fn vsyslogp_ss +and +.Fn vsyslogp_r . +.Pp +The +.Fn vsyslog +function +is an alternative form in which the arguments have already been captured +using the variable-length argument facilities of +.Xr stdarg 3 . +.Pp +The +.Fn syslogp +variants take additional arguments which correspond to new fields in the +syslog-protocol message format. +All three arguments are evaluated as +.Xr printf 3 +format strings and any of them can be +.Dv NULL . +This enables applications to use message IDs, structured data, and UTF-8 encoded +content in messages. +.Pp +The message is tagged with +.Fa priority . +Priorities are encoded as a +.Fa facility +and a +.Em level . +The facility describes the part of the system +generating the message. +The level is selected from the following +.Em ordered +(high to low) list: +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_EMERG +A panic condition. +This is normally broadcast to all users. +.It Dv LOG_ALERT +A condition that should be corrected immediately, such as a corrupted +system database. +.It Dv LOG_CRIT +Critical conditions, e.g., hard device errors. +.It Dv LOG_ERR +Errors. +.It Dv LOG_WARNING +Warning messages. +.It Dv LOG_NOTICE +Conditions that are not error conditions, +but should possibly be handled specially. +.It Dv LOG_INFO +Informational messages. +.It Dv LOG_DEBUG +Messages that contain information +normally of use only when debugging a program. +.El +.Pp +The +.Fn vsyslog_r +is used the same way as +.Fn vsyslog +except that it takes an additional pointer to a +.Fa syslog_data +structure. +It is a multithread-safe version of the +.Fn vsyslog +function described above. +.\" The +.\" .Fn vsyslog_ss +.\" is the async-signal-safe version of +.\" .Fn vsyslog_r , +.\" is also multithread-safe, and has the same limitations as +.\" .Fn syslog_ss . +.Pp +The +.Fn openlog +function +provides for more specialized processing of the messages sent +by +.Fn syslog +and +.Fn vsyslog . +The parameter +.Fa ident +is a string that will be prepended to every message. +The +.Fa logopt +argument +is a bit field specifying logging options, which is formed by +.Tn OR Ns 'ing +one or more of the following values: +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_CONS +If +.Fn syslog +cannot pass the message to +.Xr syslogd 8 +it will attempt to write the message to the console +.Pq Dq Pa /dev/console . +.It Dv LOG_NDELAY +Open the connection to +.Xr syslogd 8 +immediately. +Normally the open is delayed until the first message is logged. +Useful for programs that need to manage the order in which file +descriptors are allocated. +.It Dv LOG_NLOG +Stops syslog from writing to the system log. +Only useful with +.Dv LOG_PERROR . +.It Dv LOG_PERROR +Write the message to standard error output as well to the system log. +.It Dv LOG_PID +Log the process id with each message: useful for identifying +instantiations of daemons. +(This PID is placed within brackets +between the ident and the message.) +.It Dv LOG_PTRIM +Trim anything syslog added to the message before writing to +standard error output. +.El +.Pp +The +.Fa facility +parameter encodes a default facility to be assigned to all messages +that do not have an explicit facility encoded: +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_AUTH +The authorization system: +.Xr login 1 , +.Xr su 1 , +.Xr getty 8 , +etc. +.It Dv LOG_AUTHPRIV +The same as +.Dv LOG_AUTH , +but logged to a file readable only by +selected individuals. +.It Dv LOG_CRON +The cron daemon: +.Xr cron 8 . +.It Dv LOG_DAEMON +System daemons, such as +.Xr routed 8 , +that are not provided for explicitly by other facilities. +.It Dv LOG_FTP +The file transfer protocol daemon: +.Xr ftpd 8 . +.It Dv LOG_KERN +Messages generated by the kernel. +These cannot be generated by any user processes. +.It Dv LOG_LPR +The line printer spooling system: +.Xr lpr 1 , +.Xr lpc 8 , +.Xr lpd 8 , +etc. +.It Dv LOG_MAIL +The mail system. +.It Dv LOG_NEWS +The network news system. +.It Dv LOG_SYSLOG +Messages generated internally by +.Xr syslogd 8 . +.It Dv LOG_USER +Messages generated by random user processes. +This is the default facility identifier if none is specified. +.It Dv LOG_UUCP +The uucp system. +.It Dv LOG_LOCAL0 +Reserved for local use. +Similarly for +.Dv LOG_LOCAL1 +through +.Dv LOG_LOCAL7 . +.El +.Pp +The +.Fn openlog_r +function is the multithread-safe version of the +.Fn openlog +function. +It takes an additional pointer to a +.Fa syslog_data +structure. +This function must be used in conjunction with the other +multithread-safe functions. +.Pp +The +.Fn closelog +function +can be used to close the log file. +.Pp +The +.Fn closelog_r +does the same thing as +.Xr closelog 3 +but in a multithread-safe way and takes an additional +pointer to a +.Fa syslog_data +structure. +.Pp +The +.Fn setlogmask +function +sets the log priority mask to +.Fa maskpri +and returns the previous mask. +Calls to +.Fn syslog +with a priority not set in +.Fa maskpri +are rejected. +The mask for an individual priority +.Fa pri +is calculated by the macro +.Fn LOG_MASK pri ; +the mask for all priorities up to and including +.Fa toppri +is given by the macro +.Fn LOG_UPTO toppri . +The default allows all priorities to be logged. +.Pp +The +.Fn setlogmask_r +function is the multithread-safe version of +.Fn setlogmask . +It takes an additional pointer to a +.Fa syslog_data +structure. +.Sh RETURN VALUES +The routines +.Fn closelog , +.Fn closelog_r , +.Fn openlog , +.Fn openlog_r , +.Fn syslog , +.Fn syslog_r , +.Fn vsyslog , +.Fn vsyslog_r , +.Fn syslogp , +.Fn syslogp_r , +.Fn vsyslogp , +and +.Fn vsyslogp_r +return no value. +.Pp +The routines +.Fn setlogmask +and +.Fn setlogmask_r +always return the previous log mask level. +.Sh EXAMPLES +.Bd -literal -offset indent -compact +syslog(LOG_ALERT, "who: internal error 23"); + +openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); + +setlogmask(LOG_UPTO(LOG_ERR)); + +syslog(LOG_INFO, "Connection from host %d", CallingHost); + +syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); + +syslogp(LOG_INFO|LOG_LOCAL2, NULL, NULL, "foobar error: %m"); + +syslogp(LOG_INFO, "ID%d", "[meta language=\e"en-US\e"]", + "event: %s", 42, EventDescription); +.Ed +.Pp +For the multithread-safe functions: +.Bd -literal -offset indent +struct syslog_data sdata = SYSLOG_DATA_INIT; + +syslog_r(LOG_INFO|LOG_LOCAL2, &sdata, "foobar error: %m"); +.Ed +.Sh SEE ALSO +.Xr logger 1 , +.Xr syslogd 8 +.Rs +.%R RFC +.%N 3164 +.%D August 2001 +.%T The BSD syslog Protocol +.Re +.Rs +.%R Internet-Draft +.%N draft-ietf-syslog-protocol-23 +.%D September 2007 +.%T The syslog Protocol +.Re +.Sh HISTORY +These non-multithread-safe functions appeared in +.Bx 4.2 . +The multithread-safe functions appeared in +.Ox 3.1 +and then in +.Nx 4.0 . +The async-signal-safe functions appeared in +.Nx 4.0 . +The syslog-protocol functions appeared in +.Nx 5.0 . +.Sh CAVEATS +It is important never to pass a string with user-supplied data as a +format without using +.Ql %s . +An attacker can put format specifiers in the string to mangle your stack, +leading to a possible security hole. +This holds true even if you have built the string +.Dq by hand +using a function like +.Fn snprintf , +as the resulting string may still contain user-supplied conversion specifiers +for later interpolation by +.Fn syslog . +.Pp +Always be sure to use the proper secure idiom: +.Bd -literal -offset indent +syslog(priority, "%s", string); +.Ed +.Pp +With +.Fn syslogp +the caller is responsible to use the right formatting for the message fields. +A +.Fa msgid +must only contain up to 32 ASCII characters. +A +.Fa sdfmt +has strict rules for parenthesis and character quoting. +If the +.Fa msgfmt +contains UTF-8 characters, then it has to start with a Byte Order Mark. diff --git a/static/netbsd/man3/system.3 b/static/netbsd/man3/system.3 new file mode 100644 index 00000000..8721e085 --- /dev/null +++ b/static/netbsd/man3/system.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: system.3,v 1.17 2008/08/27 06:45:02 christos Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)system.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd August 2, 2007 +.Dt SYSTEM 3 +.Os +.Sh NAME +.Nm system +.Nd pass a command to the shell +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn system "const char *string" +.Sh DESCRIPTION +The +.Fn system +function +hands the argument +.Fa string +to the command interpreter +.Xr sh 1 . +The calling process waits for the shell to finish executing the command, +ignoring +.Dv SIGINT +and +.Dv SIGQUIT , +and blocking +.Dv SIGCHLD . +.Pp +If +.Fa string +is a +.Dv NULL +pointer, +.Fn system +will return non-zero, if the command interpreter is available, or zero if none +is available. +Otherwise, +.Fn system +returns the termination status of the shell in the format specified by +.Xr waitpid 2 . +.Sh RETURN VALUES +If a child process cannot be created, or the termination status of +the shell cannot be obtained, +.Fn system +returns -1 and sets +.Va errno +to indicate the error. +If execution of the shell fails, +.Fn system +returns the termination status for a program that terminates with a call of +.Fn exit 127 . +.Sh SEE ALSO +.Xr sh 1 , +.Xr execve 2 , +.Xr waitpid 2 , +.Xr popen 3 , +.Xr shquote 3 +.Sh STANDARDS +The +.Fn system +function +conforms to +.St -ansiC +and +.St -p1003.2-92 . +.Sh CAVEATS +Never supply the +.Fn system +function with a command containing any part of an unsanitized user-supplied +string. +Shell meta-characters present will be honored by the +.Xr sh 1 +command interpreter. diff --git a/static/netbsd/man3/t.3 b/static/netbsd/man3/t.3 new file mode 100644 index 00000000..8abbecc7 --- /dev/null +++ b/static/netbsd/man3/t.3 @@ -0,0 +1 @@ +$1 == "5" || $1 == "4" diff --git a/static/netbsd/man3/tag.h.3 b/static/netbsd/man3/tag.h.3 new file mode 100644 index 00000000..d197cb29 --- /dev/null +++ b/static/netbsd/man3/tag.h.3 @@ -0,0 +1,123 @@ +.TH "event2/tag.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/tag.h \- Helper functions for reading and writing tagged data onto buffers\&. + +.SH SYNOPSIS +.br +.PP +\fC#include <event2/visibility\&.h>\fP +.br +\fC#include <event2/event\-config\&.h>\fP +.br +\fC#include <event2/util\&.h>\fP +.br + +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_consume\fP (struct \fBevbuffer\fP *evbuf)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_encode_int\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t number)" +.br +.RI "\fIEncode an integer and store it in an evbuffer\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_encode_int64\fP (struct \fBevbuffer\fP *evbuf, ev_uint64_t number)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_init\fP (void)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t tag, const void *data, ev_uint32_t len)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal_buffer\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t tag, struct \fBevbuffer\fP *data)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal_int\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t tag, ev_uint32_t integer)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal_int64\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t tag, ev_uint64_t integer)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal_string\fP (struct \fBevbuffer\fP *buf, ev_uint32_t tag, const char *string)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevtag_marshal_timeval\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t tag, struct timeval *tv)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_payload_length\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t *plength)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_peek\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t *ptag)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_peek_length\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t *plength)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal\fP (struct \fBevbuffer\fP *src, ev_uint32_t *ptag, struct \fBevbuffer\fP *dst)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_fixed\fP (struct \fBevbuffer\fP *src, ev_uint32_t need_tag, void *data, size_t len)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_header\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t *ptag)" +.br +.RI "\fIUnmarshals the header and returns the length of the payload\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_int\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t need_tag, ev_uint32_t *pinteger)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_int64\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t need_tag, ev_uint64_t *pinteger)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_string\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t need_tag, char **pstring)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevtag_unmarshal_timeval\fP (struct \fBevbuffer\fP *evbuf, ev_uint32_t need_tag, struct timeval *ptv)" +.br +.in -1c +.SH "Detailed Description" +.PP +Helper functions for reading and writing tagged data onto buffers\&. + + +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL void evtag_encode_int (struct \fBevbuffer\fP * evbuf, ev_uint32_t number)" + +.PP +Encode an integer and store it in an evbuffer\&. We encode integers by nybbles; the first nibble contains the number of significant nibbles - 1; this allows us to encode up to 64-bit integers\&. This function is byte-order independent\&. +.PP +\fBParameters:\fP +.RS 4 +\fIevbuf\fP evbuffer to store the encoded number +.br +\fInumber\fP a 32-bit integer +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evtag_unmarshal_header (struct \fBevbuffer\fP * evbuf, ev_uint32_t * ptag)" + +.PP +Unmarshals the header and returns the length of the payload\&. +.PP +\fBParameters:\fP +.RS 4 +\fIevbuf\fP the buffer from which to unmarshal data +.br +\fIptag\fP a pointer in which the tag id is being stored +.RE +.PP +\fBReturns:\fP +.RS 4 +-1 on failure or the number of bytes in the remaining payload\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/tag_compat.h.3 b/static/netbsd/man3/tag_compat.h.3 new file mode 100644 index 00000000..7d7beaec --- /dev/null +++ b/static/netbsd/man3/tag_compat.h.3 @@ -0,0 +1,41 @@ +.TH "event2/tag_compat.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/tag_compat.h \- Obsolete/deprecated functions from \fBtag\&.h\fP; provided only for backwards compatibility\&. + +.SH SYNOPSIS +.br +.PP +.SS "Macros" + +.PP +.RI "\fBMisnamed functions\fP" +.br + +.PP +\fBDeprecated\fP +.RS 4 +These macros are deprecated because their names don't follow Libevent's naming conventions\&. +.RE +.PP +Use evtag_encode_int and evtag_encode_int64 instead\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBencode_int\fP(evbuf, number) \fBevtag_encode_int\fP((evbuf), (number))" +.br +.ti -1c +.RI "#define \fBencode_int64\fP(evbuf, number) evtag_encode_int64((evbuf), (number))" +.br +.in -1c +.in -1c +.SH "Detailed Description" +.PP +Obsolete/deprecated functions from \fBtag\&.h\fP; provided only for backwards compatibility\&. + + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/tan.3 b/static/netbsd/man3/tan.3 new file mode 100644 index 00000000..989aed7c --- /dev/null +++ b/static/netbsd/man3/tan.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)tan.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: tan.3,v 1.14 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd May 2, 1991 +.Dt TAN 3 +.Os +.Sh NAME +.Nm tan , +.Nm tanf , +.Nm tanl +.Nd tangent functions +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn tan "double x" +.Ft float +.Fn tanf "float x" +.Ft long double +.Fn tanl "long double x" +.Sh DESCRIPTION +The +.Fn tan +.Fn tanf +and +.Fn tanl +functions compute the tangent of +.Fa x +(measured in radians). +A large magnitude argument may yield a result +with little or no significance. +For a discussion of error due to roundoff, see +.Xr math 3 . +.Sh RETURN VALUES +The +.Fn tan +function returns the tangent value. +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tanh 3 +.Sh STANDARDS +The +.Fn tan +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/tanh.3 b/static/netbsd/man3/tanh.3 new file mode 100644 index 00000000..5b0c6f31 --- /dev/null +++ b/static/netbsd/man3/tanh.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)tanh.3 5.1 (Berkeley) 5/2/91 +.\" $NetBSD: tanh.3,v 1.16 2024/01/26 19:27:30 nros Exp $ +.\" +.Dd September 18, 2011 +.Dt TANH 3 +.Os +.Sh NAME +.Nm tanh , +.Nm tanhf , +.Nm tanhl +.Nd hyperbolic tangent function +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn tanh "double x" +.Ft float +.Fn tanhf "float x" +.Ft long double +.Fn tanhl "long double x" +.Sh DESCRIPTION +The +.Fn tanh +.Fn tanhf +and +.Fn tanhl +functions compute the hyperbolic tangent of +.Fa x . +For a discussion of error due to roundoff, see +.Xr math 3 . +.Sh RETURN VALUES +Upon successful completion, +these functions return the hyperbolic tangent value. +The following may also occur: +.Bl -enum -offset indent +.It +If +.Fa x +is \*(Pm 0, +.Fa x +is returned. +.It +If +.Fa x +is \*(Na, a \*(Na is returned. +.It +If +.Fa x +is positive infinity, a value 1 is returned; +if +.Fa x +is negative infinity, -1 is returned. +.It +If +.Fa x +is subnormal, a range error can occur and +.Fa x +is returned. +.El +.Sh SEE ALSO +.Xr acos 3 , +.Xr asin 3 , +.Xr atan 3 , +.Xr atan2 3 , +.Xr cos 3 , +.Xr cosh 3 , +.Xr math 3 , +.Xr sin 3 , +.Xr sinh 3 , +.Xr tan 3 +.Sh STANDARDS +The described functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/tbl.3 b/static/netbsd/man3/tbl.3 new file mode 100644 index 00000000..fb517c43 --- /dev/null +++ b/static/netbsd/man3/tbl.3 @@ -0,0 +1,349 @@ +.\" Id: tbl.3,v 1.6 2018/12/14 06:33:14 schwarze Exp +.\" +.\" Copyright (c) 2013, 2015, 2018 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 14, 2018 +.Dt TBL 3 +.Os +.Sh NAME +.Nm tbl_alloc , +.Nm tbl_read , +.Nm tbl_restart , +.Nm tbl_span , +.Nm tbl_end , +.Nm tbl_free +.Nd roff table parser library for mandoc +.Sh SYNOPSIS +.In sys/types.h +.In tbl.h +.In tbl_parse.h +.Ft struct tbl_node * +.Fo tbl_alloc +.Fa "int pos" +.Fa "int line" +.Fc +.Ft void +.Fo tbl_read +.Fa "struct tbl_node *tbl" +.Fa "int ln" +.Fa "const char *p" +.Fa "int offs" +.Fc +.Ft void +.Fo tbl_restart +.Fa "int line" +.Fa "int pos" +.Fa "struct tbl_node *tbl" +.Fc +.Ft const struct tbl_span * +.Fo tbl_span +.Fa "struct tbl_node *tbl" +.Fc +.Ft void +.Fo tbl_end +.Fa "struct tbl_node **tblp" +.Fc +.Ft void +.Fo tbl_free +.Fa "struct tbl_node *tbl" +.Fc +.Sh DESCRIPTION +This library is tightly integrated into the +.Xr mandoc 1 +utility and not designed for stand-alone use. +The present manual is intended as a reference for developers working on +.Xr mandoc 1 . +.Ss Data structures +Unless otherwise noted, all of the following data structures are declared in +.In tbl.h +and are deleted in +.Fn tbl_free . +.Bl -tag -width Ds +.It Vt struct tbl_node +This structure describes a complete table. +It is declared in +.In tbl_int.h , +created in +.Fn tbl_alloc , +and stored in the members +.Fa first_tbl , +.Fa last_tbl , +and +.Fa tbl +of +.Vt struct roff Bq Pa roff.c . +.Pp +The +.Fa first_span , +.Fa current_span , +.Fa last_span , +and +.Fa next +members may be +.Dv NULL . +The +.Fa first_row +and +.Fa last_row +members may be +.Dv NULL , +but if there is a span, the function +.Fn tbl_layout +guarantees that these pointers are not +.Dv NULL . +.It Vt struct tbl_opts +This structure describes the options of one table. +It is used as a substructure of +.Vt struct tbl_node +and thus created and deleted together with it. +It is filled in +.Fn tbl_options . +.It Vt struct tbl_row +This structure describes one layout line in a table +by maintaining a list of all the cells in that line. +It is allocated and filled in +.Fn row Bq Pa tbl_layout.c +and referenced from the +.Fa layout +member of +.Vt struct tbl_node . +.Pp +The +.Fa next +member may be +.Dv NULL . +The function +.Fn tbl_layout +guarantees that the +.Fa first +and +.Fa last +members are not NULL. +.It Vt struct tbl_cell +This structure describes one layout cell in a table, +in particular its alignment, membership in spans, and +usage for lines. +It is allocated and filled in +.Fn cell_alloc Bq Pa tbl_layout.c +and referenced from the +.Fa first +and +.Fa last +members of +.Vt struct tbl_row . +.Pp +The +.Fa next +member may be +.Dv NULL . +.It Vt struct tbl_span +This structure describes one data line in a table +by maintaining a list of all data cells in that line +or by specifying that it is a horizontal line. +It is allocated and filled in +.Fn newspan Bq Pa tbl_data.c +which is called from +.Fn tbl_data +and referenced from the +.Fa first_span , +.Fa current_span , +and +.Fa last_span +members of +.Vt struct tbl_node , +and from the +.Fa span +members of +.Vt struct man_node +and +.Vt struct mdoc_node +from +.In man.h +and +.In mdoc.h . +.Pp +The +.Fa first , +.Fa last , +.Fa prev , +and +.Fa next +members may be +.Dv NULL . +The function +.Fn newspan Bq Pa tbl_data.c +guarantees that the +.Fa opts +and +.Fa layout +members are not +.Dv NULL . +.It Vt struct tbl_dat +This structure describes one data cell in a table by specifying +whether it contains a line or data, whether it spans additional +layout cells, and by storing the data. +It is allocated and filled in +.Fn tbl_data +and referenced from the +.Fa first +and +.Fa last +members of +.Vt struct tbl_span . +.Pp +The +.Fa string +and +.Fa next +members may be +.Dv NULL . +The function +.Fn getdata +guarantees that the +.Fa layout +member is not +.Dv NULL . +.El +.Ss Interface functions +The following functions are implemented in +.Pa tbl.c , +and all callers are in +.Pa roff.c . +.Bl -tag -width Ds +.It Fn tbl_alloc +Allocates, initializes, and returns a new +.Vt struct tbl_node . +Called from +.Fn roff_TS . +.It Fn tbl_read +Dispatches to +.Fn tbl_option , +.Fn tbl_layout , +.Fn tbl_cdata , +and +.Fn tbl_data , +see below. +Called from +.Fn roff_parseln . +.It Fn tbl_restart +Resets the +.Fa part +member of +.Vt struct tbl_node +to +.Dv TBL_PART_LAYOUT . +Called from +.Fn roff_T_ . +.It Fn tbl_span +On the first call, return the first +.Vt struct tbl_span ; +for later calls, return the next one or +.Dv NULL . +Called from +.Fn roff_span . +.It Fn tbl_end +Flags the last span as +.Dv TBL_SPAN_LAST +and clears the pointer passed as an argment. +Called from +.Fn roff_TE +and +.Fn roff_endparse . +.It Fn tbl_free +Frees the specified +.Vt struct tbl_node +and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures +referenced from it. +Called from +.Fn roff_free +and +.Fn roff_reset . +.El +.Ss Private functions +The following functions are declared in +.In tbl_int.h . +.Bl -tag -width Ds +.It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p" +Parses the options line into +.Vt struct tbl_opts . +Implemented in +.Pa tbl_opts.c , +called from +.Fn tbl_read . +.It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p" +Allocates and fills one +.Vt struct tbl_row +for each layout line and one +.Vt struct tbl_cell +for each layout cell. +Implemented in +.Pa tbl_layout.c , +called from +.Fn tbl_read . +.It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p" +Allocates one +.Vt struct tbl_span +for each data line and calls +.Fn getdata +for each data cell. +Implemented in +.Pa tbl_data.c , +called from +.Fn tbl_read . +.It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p" +Continues parsing a data line: +When finding +.Sq T} , +switches back to +.Dv TBL_PART_DATA +mode and calls +.Fn getdata +if there are more data cells on the line. +Otherwise, appends the data to the current data cell. +Implemented in +.Pa tbl_data.c , +called from +.Fn tbl_read . +.It Xo +.Ft int +.Fo getdata +.Fa "struct tbl_node *tbl" +.Fa "struct tbl_span *dp" +.Fa "int ln" +.Fa "const char *p" +.Fa "int *pos" +.Fc +.Xc +Parses one data cell into one +.Vt struct tbl_dat . +Implemented in +.Pa tbl_data.c , +called from +.Fn tbl_data +and +.Fn tbl_cdata . +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr mandoc 3 , +.Xr tbl 7 +.Sh AUTHORS +.An -nosplit +The +.Nm tbl +library was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +with contributions from +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/static/netbsd/man3/tcgetpgrp.3 b/static/netbsd/man3/tcgetpgrp.3 new file mode 100644 index 00000000..c3f44f83 --- /dev/null +++ b/static/netbsd/man3/tcgetpgrp.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: tcgetpgrp.3,v 1.11 2003/08/07 16:44:13 agc Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tcgetpgrp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt TCGETPGRP 3 +.Os +.Sh NAME +.Nm tcgetpgrp +.Nd get foreground process group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn tcgetpgrp "int fd" +.Sh DESCRIPTION +The +.Nm tcgetpgrp +function returns the value of the process group ID of the foreground +process group associated with the terminal device. +If there is no foreground process group, +.Nm tcgetpgrp +returns an invalid process ID. +.Sh ERRORS +If an error occurs, +.Nm tcgetpgrp +returns -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er ENOTTY +The calling process does not have a controlling terminal or the +underlying terminal device represented by +.Fa fd +is not the controlling terminal. +.El +.Sh SEE ALSO +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Nm tcgetpgrp +function conforms to +.St -p1003.1-90 . diff --git a/static/netbsd/man3/tcgetsid.3 b/static/netbsd/man3/tcgetsid.3 new file mode 100644 index 00000000..996992ed --- /dev/null +++ b/static/netbsd/man3/tcgetsid.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: tcgetsid.3,v 1.6 2019/12/19 16:12:21 leot Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tcgetpgrp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd December 19, 2019 +.Dt TCGETSID 3 +.Os +.Sh NAME +.Nm tcgetsid +.Nd get session ID associated with a controlling terminal +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In termios.h +.Ft pid_t +.Fn tcgetsid "int fd" +.Sh DESCRIPTION +The +.Nm tcgetsid +function returns the value of the session ID associated with the specified +controlling terminal device. +The session ID is defined as the process group ID of the session leader. +.Sh ERRORS +If an error occurs, +.Nm tcgetsid +returns -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er ENOTTY +The calling process does not have a controlling terminal or the +underlying terminal device represented by +.Fa fd +is not the controlling terminal. +.El +.Sh SEE ALSO +.Xr getsid 2 , +.Xr setsid 2 , +.Xr tcgetpgrp 3 +.Sh STANDARDS +The +.Nm tcgetsid +function conforms to +.St -xpg4.2 . diff --git a/static/netbsd/man3/tcgetwinsize.3 b/static/netbsd/man3/tcgetwinsize.3 new file mode 100644 index 00000000..fce65a3b --- /dev/null +++ b/static/netbsd/man3/tcgetwinsize.3 @@ -0,0 +1,216 @@ +.\" $NetBSD: tcgetwinsize.3,v 1.2 2017/10/30 15:43:21 wiz Exp $ +.\" +.\" Copyright (c) 2017 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 25, 2017 +.Dt TCGETWINSIZE 3 +.Os +.Sh NAME +.Nm tcgetwinsize , +.Nm tcsetwinsize +.Nd manipulate terminal window size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In termios.h +.Ft int +.Fn tcgetwinsize "int fd" "struct winsize *gws" +.Ft int +.Fn tcsetwinsize "int fd" "const struct winsize *sws" +.Sh DESCRIPTION +The +.Nm tcgetwinsize +function fills in the +.Ic winsize +structure pointed to by +.Fa gws +with values that represent the size of the +terminal window for which +.Fa fd +provides an open file descriptor. +If no error occurs +.Fn tcgetwinsize +returns zero (0). +.Pp +The +.Nm tcsetwinsize +function sets the terminal window size, +for the terminal referenced by +.Fa fd , +to the sizes from the +.Ic winsize +structure pointed to by +.Fa sws . +If no error occurs +.Fn tcsetwinsize +returns zero (0). +.Pp +The +.Ic winsize +structure, defined in +.In termios.h , +contains (at least) the following four fields +.Bd -literal + unsigned short ws_row; /* Number of rows, in characters */ + unsigned short ws_col; /* Number of columns, in characters */ + unsigned short ws_xpixel; /* Width, in pixels */ + unsigned short ws_ypixel; /* Height, in pixels */ +.Ed +.Pp +If the actual window size of the controlling terminal +of a process changes, the process is sent a +.Dv SIGWINCH +signal. +See +.Xr signal 7 . +Note simply changing the sizes using +.Fn tcsetwinsize +does not necessarily change the actual window size, +and if not, will not generate a +.Dv SIGWINCH . +.Sh ERRORS +If an error occurs, +.Fn tcgetwinsize +and +.Fn tcsetwinsize +return \-1 and cause the global variable +.Va errno +to be set to indicate the error. +Common errors are as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument to +.Fn tcgetwinsize +or +.Fn tcsetwinsize +is not a valid file descriptor. +.It Bq Er EFAULT +The +.Fa gws +argument to +.Fn tcgetwinsize +does not point to a suitable location +into which to store the resulting +.Ic winsize +structure, +or the +.Fa sws +argument to +.Fn tcsetwinsize +does not refer to a suitable location +from which the +.Ic winsize +structure can be obtained. +.It Bq Er EINVAL +The values passed in the +.Ar sws +.Ic winsize +structure to +.Fn tcsetwinsize +represent an attempt to set the window size to an invalid state. +.It Bq Er ENOTTY +The +.Fa fd +argument to +.Fn tcgetwinsize +or +.Fn tcsetwinsize +does not represent a terminal device capable +of remembering a window size. +.El +.Sh SEE ALSO +.Xr stty 1 , +.Xr pty 4 , +.Xr termios 4 , +.Xr tty 4 , +.Xr signal 7 +.Sh STANDARDS +The +.Nm tcgetwinsize +and +.Nm tcsetwinsize +functions will conform to +.St -p1003.1 +issue 8, when it is published. +.Pp +The +.Ic ws_xpixel +and +.Ic ws_ypixel +fields are extensions to the standard. +.Pp +The standard only requires pseudo-terminals +.Pq Xr pty 4 +to support these operations. +In +.Nx +all terminal devices can set and recall a window size, +regardless of whether any actual window exists. +.Sh HISTORY +The +.Fn tcgetwinsize +and +.Fn tcsetwinsize +functions were added in +.Nx 8.0 +after specification by POSIX +as more portable alternatives to ancient +.Ic ioctl +operations from +.Bx 4.3 . +.Sh CAVEATS +It is unspecified whether calling the +.Nm tcsetwinsize +function causes the underlying terminal window to be resized. +Nor is it specified whether altering the relationship between +the character fields (ws_row and ws_col) and the pixel fields +(ws_xpixel and ws_ypixel) causes the font size to change, or +whether the application is required to maintain any specific +relationship between these fields. +In general, the +.Nm tcsetwinsize +function is best avoided except by applications responsible +for actually implementing terminal windows. +.Pp +As the +.Ic winsize +structure may have more fields than documented, applications +planning to call +.Fn tcsetwinsize +should call +.Fn tcgetwinsize +first with the same +.Ar fd +parameter, and use the result obtained in +.Ar *gws +to initialize the +.Ic winsize +structure to be used (after altering fields that are to be changed) +as the +.Ar sws +operand of +.Nm tcsetwinsize . diff --git a/static/netbsd/man3/tcsendbreak.3 b/static/netbsd/man3/tcsendbreak.3 new file mode 100644 index 00000000..27e76583 --- /dev/null +++ b/static/netbsd/man3/tcsendbreak.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: tcsendbreak.3,v 1.9 2003/08/07 16:44:13 agc Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tcsendbreak.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt TCSENDBREAK 3 +.Os +.Sh NAME +.Nm tcsendbreak , +.Nm tcdrain , +.Nm tcflush , +.Nm tcflow +.Nd line control functions +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In termios.h +.Ft int +.Fn tcdrain "int fd" +.Ft int +.Fn tcflow "int fd" "int action" +.Ft int +.Fn tcflush "int fd" "int action" +.Ft int +.Fn tcsendbreak "int fd" "int len" +.Sh DESCRIPTION +The +.Nm tcdrain +function waits until all output written to the terminal referenced by +.Fa fd +has been transmitted to the terminal. +.Pp +The +.Nm tcflow +function suspends transmission of data to or the reception of data from +the terminal referenced by +.Fa fd +depending on the value of +.Fa action . +The value of +.Fa action +must be one of the following: +.Bl -tag -width "TCIOFF" +.It Fa TCOOFF +Suspend output. +.It Fa TCOON +Restart suspended output. +.It Fa TCIOFF +Transmit a STOP character, which is intended to cause the terminal to stop +transmitting data to the system. +(See the description of IXOFF in the +.Ql Input Modes +section of +.Xr termios 4 ) . +.It Fa TCION +Transmit a START character, which is intended to cause the terminal to start +transmitting data to the system. +(See the description of IXOFF in the +.Ql Input Modes +section of +.Xr termios 4 ) . +.El +.Pp +The +.Nm tcflush +function discards any data written to the terminal referenced by +.Fa fd +which has not been transmitted to the terminal, or any data received +from the terminal but not yet read, depending on the value of +.Fa action . +The value of +.Fa action +must be one of the following: +.Bl -tag -width "TCIOFLUSH" +.It Fa TCIFLUSH +Flush data received but not read. +.It Fa TCOFLUSH +Flush data written but not transmitted. +.It Fa TCIOFLUSH +Flush both data received but not read and data written but not transmitted. +.El +.Pp +The +.Nm tcsendbreak +function transmits a continuous stream of zero-valued bits for four-tenths +of a second to the terminal referenced by +.Fa fd . +The +.Fa len +parameter is ignored in this implementation. +.Sh RETURN VALUES +Upon successful completion, all of these functions return a value of zero. +.Sh ERRORS +If any error occurs, a value of -1 is returned and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa action +argument is not a proper value. +.It Bq Er ENOTTY +The file associated with +.Fa fd +is not a terminal. +.It Bq Er EINTR +A signal interrupted the +.Nm tcdrain +function. +.El +.Sh SEE ALSO +.Xr tcsetattr 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Nm tcsendbreak , +.Nm tcdrain , +.Nm tcflush +and +.Nm tcflow +functions are expected to be compliant with the +.St -p1003.1-88 +specification. diff --git a/static/netbsd/man3/tcsetattr.3 b/static/netbsd/man3/tcsetattr.3 new file mode 100644 index 00000000..b5a31231 --- /dev/null +++ b/static/netbsd/man3/tcsetattr.3 @@ -0,0 +1,331 @@ +.\" $NetBSD: tcsetattr.3,v 1.13 2010/03/22 19:30:55 joerg Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tcsetattr.3 8.3 (Berkeley) 1/2/94 +.\" +.Dd May 1, 2004 +.Dt TCSETATTR 3 +.Os +.Sh NAME +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed , +.Nm cfsetspeed , +.Nm cfmakeraw , +.Nm tcgetattr , +.Nm tcsetattr +.Nd manipulating the termios structure +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In termios.h +.Ft speed_t +.Fn cfgetispeed "const struct termios *t" +.Ft int +.Fn cfsetispeed "struct termios *t" "speed_t speed" +.Ft speed_t +.Fn cfgetospeed "const struct termios *t" +.Ft int +.Fn cfsetospeed "struct termios *t" "speed_t speed" +.Ft int +.Fn cfsetspeed "struct termios *t" "speed_t speed" +.Ft void +.Fn cfmakeraw "struct termios *t" +.Ft int +.Fn tcgetattr "int fd" "struct termios *t" +.Ft int +.Fn tcsetattr "int fd" "int action" "const struct termios *t" +.Sh DESCRIPTION +The +.Nm cfmakeraw , +.Nm tcgetattr +and +.Nm tcsetattr +functions are provided for getting and setting the termios structure. +.Pp +The +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed +and +.Nm cfsetspeed +functions are provided for getting and setting the baud rate values in +the termios structure. +The effects of the functions on the terminal as described below +do not become effective, nor are all errors detected, until the +.Nm tcsetattr +function is called. +Certain values for baud rates set in the termios structure and passed to +.Nm tcsetattr +have special meanings. +These are discussed in the portion of the manual page that describes the +.Nm tcsetattr +function. +.Sh GETTING AND SETTING THE BAUD RATE +The input and output baud rates are found in the termios structure. +The unsigned integer +.Li speed_t +is typdef'd in the include file +.In termios.h . +The value of the integer corresponds directly to the baud rate being +represented, however, the following symbolic values are defined. +.Bd -literal +#define B0 0 +#define B50 50 +#define B75 75 +#define B110 110 +#define B134 134 +#define B150 150 +#define B200 200 +#define B300 300 +#define B600 600 +#define B1200 1200 +#define B1800 1800 +#define B2400 2400 +#define B4800 4800 +#define B9600 9600 +#define B19200 19200 +#define B38400 38400 +#ifndef _POSIX_SOURCE +#define EXTA 19200 +#define EXTB 38400 +#endif /*_POSIX_SOURCE */ +.Ed +.Pp +The +.Nm cfgetispeed +function returns the input baud rate in the termios structure referenced by +.Fa tp . +.Pp +The +.Nm cfsetispeed +function sets the input baud rate in the termios structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Nm cfgetospeed +function returns the output baud rate in the termios structure referenced by +.Fa tp . +.Pp +The +.Nm cfsetospeed +function sets the output baud rate in the termios structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Nm cfsetspeed +function sets both the input and output baud rate in the termios structure +referenced by +.Fa tp +to +.Fa speed . +.Pp +Upon successful completion, the functions +.Nm cfsetispeed , +.Nm cfsetospeed , +and +.Nm cfsetspeed +return a value of 0. +Otherwise, a value of -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh GETTING AND SETTING THE TERMIOS STATE +This section describes the functions that are used to control the general +terminal interface. +Unless otherwise noted for a specific command, these functions are restricted +from use by background processes. +Attempts to perform these operations shall cause the process group to be sent +a SIGTTOU signal. +If the calling process is blocking or ignoring SIGTTOU signals, the process +is allowed to perform the operation and the SIGTTOU signal is not sent. +.Pp +In all the functions, although +.Fa fd +is an open file descriptor, the functions affect the underlying terminal +file, not just the open file description associated with the particular +file descriptor. +.Pp +The +.Nm cfmakeraw +function sets the flags stored in the termios structure (initialized by +.Nm tcgetattr ) +to a state disabling all input and output processing, giving a +.Dq raw I/O path . +It should be noted that there is no function to reverse this effect. +This is because there are a variety of processing options that could be +re-enabled and the correct method is for an application to snapshot the +current terminal state using the function +.Nm tcgetattr , +setting raw mode with +.Nm cfmakeraw +and the subsequent +.Nm tcsetattr , +and then using another +.Nm tcsetattr +with the saved state to revert to the previous terminal state. +.Pp +The +.Nm tcgetattr +function copies the parameters associated with the terminal referenced +by +.Fa fd +to the termios structure referenced by +.Fa tp . +This function is allowed from a background process, however, the terminal +attributes may be subsequently changed by a foreground process. +.Pp +The +.Nm tcsetattr +function sets the parameters associated with the terminal from the +termios structure referenced by +.Fa tp . +The +.Fa action +field is created by +.Em or Ns 'ing +the following values, as specified in the include file +.In termios.h . +.Bl -tag -width "TCSADRAIN" +.It Fa TCSANOW +The change occurs immediately. +.It Fa TCSADRAIN +The change occurs after all output written to +.Fa fd +has been transmitted to the terminal. +This value of +.Fa action +should be used when changing parameters that affect output. +.It Fa TCSAFLUSH +The change occurs after all output written to +.Fa fd +has been transmitted to the terminal. +Additionally, any input that has been received but not read is discarded. +.It Fa TCSASOFT +If this value is +.Em or Ns 'ed +into the +.Fa action +value, the values of the +.Em c_cflag , +.Em c_ispeed , +and +.Em c_ospeed +fields are ignored. +.El +.Pp +The 0 baud rate is used to terminate the connection. +If 0 is specified as the output speed to the function +.Nm tcsetattr , +modem control will no longer be asserted on the terminal, disconnecting +the terminal. +.Pp +If zero is specified as the input speed to the function +.Nm tcsetattr , +the input baud rate will be set to the same value as that specified by +the output baud rate. +.Sh RETURN VALUES +If +.Nm tcsetattr +is unable to make any of the requested changes, it returns -1 and +sets errno. +Otherwise, it makes all of the requested changes it can. +If the specified input and output baud rates differ and are a combination +that is not supported, neither baud rate is changed. +.Pp +Upon successful completion, the functions +.Nm tcgetattr +and +.Nm tcsetattr +return a value of 0. +Otherwise, they +return -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument to +.Nm tcgetattr +or +.Nm tcsetattr +was not a valid file descriptor. +.It Bq Er EINTR +The +.Nm tcsetattr +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa action +argument to the +.Nm tcsetattr +function was not valid, or an attempt was made to change an attribute +represented in the termios structure to an unsupported value. +.It Bq Er ENOTTY +The file associated with the +.Fa fd +argument to +.Nm tcgetattr +or +.Nm tcsetattr +is not a terminal. +.El +.Sh SEE ALSO +.Xr tcsendbreak 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed , +.Nm tcgetattr +and +.Nm tcsetattr +functions are expected to be compliant with the +.St -p1003.1-88 +specification. +The +.Nm cfmakeraw +and +.Nm cfsetspeed +functions, +as well as the +.Li TCSASOFT +option to the +.Nm tcsetattr +function are extensions to the +.St -p1003.1-88 +specification. diff --git a/static/netbsd/man3/tcsetpgrp.3 b/static/netbsd/man3/tcsetpgrp.3 new file mode 100644 index 00000000..b0db4e0c --- /dev/null +++ b/static/netbsd/man3/tcsetpgrp.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: tcsetpgrp.3,v 1.10 2003/08/07 16:44:14 agc Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tcsetpgrp.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt TCSETPGRP 3 +.Os +.Sh NAME +.Nm tcsetpgrp +.Nd set foreground process group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn tcsetpgrp "int fd" "pid_t pgrp_id" +.Sh DESCRIPTION +If the process has a controlling terminal, the +.Nm tcsetpgrp +function sets the foreground process group ID associated with the +terminal device to +.Fa pgrp_id . +The terminal device associated with +.Fa fd +must be the controlling terminal of the calling process and the +controlling terminal must be currently associated with the session +of the calling process. +The value of +.Fa pgrp_id +must be the same as the process group ID of a process in the same +session as the calling process. +.Pp +Upon successful completion, +.Nm tcsetpgrp +returns a value of zero. +.Sh ERRORS +If an error occurs, +.Nm tcgetpgrp +returns -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +An invalid value of +.Fa pgrp_id +was specified. +.It Bq Er ENOTTY +The calling process does not have a controlling terminal, or the file +represented by +.Fa fd +is not the controlling terminal, or the controlling terminal is no +longer associated with the session of the calling process. +.It Bq Er EPERM +The +.Fa pgrp_id +argument does not match the process group ID of a process in the same +session as the calling process. +.El +.Sh SEE ALSO +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr tcgetpgrp 3 +.Sh STANDARDS +The +.Nm tcsetpgprp +function conforms to +.St -p1003.1-90 . diff --git a/static/netbsd/man3/termcap.3 b/static/netbsd/man3/termcap.3 new file mode 100644 index 00000000..8803c128 --- /dev/null +++ b/static/netbsd/man3/termcap.3 @@ -0,0 +1,155 @@ +.\" $NetBSD: termcap.3,v 1.9 2017/10/22 16:44:51 abhinav Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 14, 2011 +.Dt TERMCAP 3 +.Os +.Sh NAME +.Nm tgetent , +.Nm tgetnum , +.Nm tgetflag , +.Nm tgetstr , +.Nm tgoto +.Nd terminal independent operation routines +.Sh LIBRARY +.Lb libtermcap +.Sh SYNOPSIS +.In termcap.h +.Vt char PC ; +.Vt char *BC ; +.Vt char *UP ; +.Ft int +.Fn tgetent "char *bp" "const char *name" +.Ft int +.Fn tgetnum "const char *id" +.Ft int +.Fn tgetflag "const char *id" +.Ft char * +.Fn tgetstr "const char *id" "char **area" +.Ft char * +.Fn tgoto "const char *cm" "int destcol" "int destline" +.Sh DESCRIPTION +These functions extract and use capabilities from a terminal capability +database. +They exist as wrappers around equivalent +.Xr terminfo 3 +functions, which new code should use. +These are low level routines; see +.Xr curses 3 +for a higher level package. +.Pp +The +.Fn tgetent +function calls +.Fn setupterm +and configures +.Va PC , +.Va UP +and +.Va BC . +Only +.Va PC +is actually used internally. +The +.Fn tgetent +function returns \-1 if none of the +.Nm terminfo +data base files could be opened, +0 if the terminal name given does not match an entry, +and 1 if all goes well. +The +.Fa bp +argument is not used. +.Pp +The +.Fn tgetnum +function gets the numeric value of the capability +.Fa id , +returning \-1 if it is not given for the terminal. +The +.Fn tgetflag +function returns 1 if the specified capability is present in the terminal's +entry, 0 if it is not. +The +.Fn tgetstr +function returns the string value of the capability +.Fa id . +This is a +.Xr terminfo 5 +string and not a +.Nm termcap +string; +as such it should only be processed by +.Fn tgoto . +The +.Fn tgetstr +function returns +.Dv NULL +if the capability was not found. +The +.Fa area +argument is unused. +.Pp +The +.Fn tgoto +function returns a cursor addressing string decoded from +.Fa cm +to go to column +.Fa destcol +in line +.Fa destline , +or +.Dv NULL +on error conditions such as out of memory. +Please note that +.Fn tgoto +can return an incomplete value on a malformed input sequence. +Historically +.Fn tgoto +used to return +.Dq OOPS +on those conditions, so newer programs should now be checking the return +value. +.Sh SEE ALSO +.Xr terminfo 3 , +.Xr terminfo 5 +.Sh HISTORY +.Nm termcap +first appeared in 4.0BSD. +.Nx 1.5 +introduced some +.Nm termcap +.Fn t_* +extensions which were removed in +.Nx 6.0 +when +.Xr terminfo 3 +was introduced. +.Sh AUTHORS +.An Roy Marples Aq Mt roy@NetBSD.org diff --git a/static/netbsd/man3/terminfo.3 b/static/netbsd/man3/terminfo.3 new file mode 100644 index 00000000..3363d4d0 --- /dev/null +++ b/static/netbsd/man3/terminfo.3 @@ -0,0 +1,256 @@ +.\" $NetBSD: terminfo.3,v 1.14 2017/10/22 16:42:34 abhinav Exp $ +.\" +.\" Copyright (c) 2009, 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Roy Marples. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 23, 2015 +.Dt TERMINFO 3 +.Os +.Sh NAME +.Nm setupterm , +.Nm set_curterm , +.Nm del_curterm , +.Nm termname , +.Nm longname , +.Nm tigetflag , +.Nm tigetnum , +.Nm tigetstr , +.Nm tparm , +.Nm tputs , +.Nm putp , +.Nm ti_setupterm , +.Nm ti_getflag , +.Nm ti_getnum , +.Nm ti_getstr , +.Nm tiparm , +.Nm ti_tiparm , +.Nm ti_puts , +.Nm ti_putp +.Nd terminal independent operation routines +.Sh LIBRARY +.Lb libterminfo +.Sh SYNOPSIS +.In term.h +.Vt char PC ; +.Vt short ospeed ; +.Vt TERMINAL *cur_term ; +.Ft int +.Fn setupterm "const char *name" "int fildes" "int *errret" +.Ft TERMINAL * +.Fn set_curterm "TERMINAL *nterm" +.Ft int +.Fn del_curterm "TERMINAL *oterm" +.Ft char * +.Fn termname "void" +.Ft char * +.Fn longname "void" +.Ft int +.Fn tigetnum "const char *id" +.Ft int +.Fn tigetflag "const char *id" +.Ft char * +.Fn tigetstr "const char *id" +.Ft char * +.Fn tparm "const char *cm" "long p1" "long p2" "long p3" "long p4" "long p5" "long p6" "long p7" "long p8" "long p9" +.Ft int +.Fn tputs "const char *cp" "int affcnt" "int (*outc)(int)" +.Ft int +.Fn putp "const char *cp" +.Ft int +.Fn ti_setupterm "TERMINAL **" "const char *name" "int fildes" "int *error" +.Ft int +.Fn ti_getflag "const TERMINAL *" "const char *id" +.Ft int +.Fn ti_getnum "const TERMINAL *" "const char *id" +.Ft const char * +.Fn ti_getstr "const TERMINAL *" "const char *id" +.Ft char * +.Fn tiparm "const char *cm" "..." +.Ft char * +.Fn ti_tiparm "TERMINAL *" "const char *cm" "..." +.Ft int +.Fn ti_puts "const TERMINAL *term" "const char *str" "int affcnt" "int (*outc)(int ch, void *arg)" "void *arg" +.Ft int +.Fn ti_putp "const TERMINAL *term" "const char *str" +.Sh DESCRIPTION +These functions extract and use capabilities from a terminal capability +database, usually +.Pa /usr/share/misc/terminfo , +the format of which is described in +.Xr terminfo 5 . +These are low level routines; +see +.Xr curses 3 +for a higher level package. +.Pp +The +.Fn setupterm +function extracts the entry for terminal +.Fa name +and then calls +.Fn set_curterm +to set +.Va cur_term +to it. +If +.Fa name +is +.Dv NULL +then it is replaced by the environment variable +.Ev TERM . +The +.Fn setupterm +function returns 0 on success and \-1 on error. +.Va errret +is set to \-1 if the +.Nm terminfo +database could not be opened, +0 if the terminal could not be found in the database, and +1 if all went well. +.Pp +The +.Fn set_curterm +function sets the variable +.Va cur_term +to +.Va nterm +and makes all of the +.Nm terminfo +boolean, numeric and string variables use the values from +.Va nterm . +The global variables +.Va PC +and +.Va ospeed +are then set. +The old value of +.Va cur_term +is returned. +The +.Fn del_curterm +function frees space pointed to by +.Va oterm . +.Pp +The +.Fn termname +function returns the name of +.Va cur_term . +The +.Fn longname +function returns the description of +.Va cur_term . +.Pp +The +.Fn tigetflag +function gets the boolean value of capability +.Va id , +returning \-1 if it is not a valid capability. +The +.Fn tigetnum +function gets the numeric value of the capability +.Va id , +returning \-2 if it is not a valid capability. +The +.Fn tigetstr +function returns the string value of the capability +.Va id , +returning (char *)-1 if it is not a valid capability. +.Pp +The +.Fn tparm +function returns a string decoded from +.Va cm +with the parameters +.Va p1 +\&... +.Va p9 +applied. +Some capabilities require string parameters and only platforms that can fit +a +.Vt char * +pointer inside a +.Vt long +can use them. +For platforms which don't support this, +.Dv NULL +is returned and +.Va errno +is set to +.Er ENOTSUPP . +The string encoding and parameter application is described in +.Xr terminfo 5 . +.Pp +The +.Fn tputs +function applies padding information to the string +.Va cp ; +.Va affcnt +gives the number of lines affected by the operation, +or 1 if this is not applicable; +.Va outc +is a function which is called by each character in turn. +The external variable +.Va ospeed +controls how many padding characters are sent in relation to the terminal +speed. +The +.Fn putp +function calls tputs(str, 1, putchar). +The output from +.Fn putp +always goes to stdout. +.Ss NetBSD Extensions To Terminfo +The +.Fn tiparm +function allows variadic parameters instead of 9 fixed longs. +Numeric parameters must be passed as +.Vt int . +String parameters must be passed as +.Vt char * +and works on all platforms, unlike +.Fn tparm . +.Pp +The +.Fn ti_* +functions correspond to the standard +.Fn t* +functions but take an additional +.Ft TERMINAL * +parameter so that the terminal can be specified instead of assuming +.Va cur_term . +These functions use private variables to the +.Ft TERMINAL +instead of the global variables, such as +.Va PC +and +.Va ospeed . +.Sh SEE ALSO +.Xr ex 1 , +.Xr curses 3 , +.Xr terminfo 5 +.Sh AUTHORS +.An Roy Marples Aq Mt roy@NetBSD.org diff --git a/static/netbsd/man3/test_ldnsrr.3 b/static/netbsd/man3/test_ldnsrr.3 new file mode 100644 index 00000000..70ca222f --- /dev/null +++ b/static/netbsd/man3/test_ldnsrr.3 @@ -0,0 +1,574 @@ +types-signed.wb.sidnlabs.nl. 86400 IN SOA nsd.sidnlabs.nl. hostmaster.sidnlabs.nl. 2013090401 3600 600 1814400 3600 +types-signed.wb.sidnlabs.nl. 86400 IN RRSIG SOA 8 4 86400 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. FS5/2Besj3v0zLSGbsSztLL48+efFgpVADvLURzd5DC1Mz3W9x5yIDvDmmJs8o/9E8f0CKFfCAsP7dByfjSTsNXp83HSC4gB3OJgBGKFcvCdBjqG4lNeZlvX2510z5Wt4I9Ap+4xrpdb7Gx+nLfysZUozoPXZTtnXRQr/fUIlSM= +types-signed.wb.sidnlabs.nl. 60 IN NS nsd.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN NS knot.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN NS nsd4.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN NS bind9.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN NS bind10.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN NS powerdns.sidnlabs.nl. +types-signed.wb.sidnlabs.nl. 60 IN RRSIG NS 8 4 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. uj2mFDdXuXJI+ahHJWdFqpDenLh3P2skezM933C+FpaLLc14JhHITjL5CoAhnaJGIuDJAc/PocCLgl+fFsEgRFSvK/svqzLCkzTA+1w04D7JdoKj4NFkkUe5ryWdDnaUPvp4b2yk5Ian6JMXkYNjZ1PwIEWpE1P3qc8PMOFqXDo= +types-signed.wb.sidnlabs.nl. 86400 IN DNSKEY 256 3 8 AwEAAde1PJyYjnR2R0RmzDuiYKRh/ldkv0znVOYwfjsHZNLg0ahLI+UsvghBmimoUSGa9d6Ckd3dodbHYxUpjFYsJfdeq+qimYFjrG8bUA2BD2uJMag1/QG7DTUp3jHaV0Q13r/829QEl0sjrLIBxC7wSlqu0ydfYz5VX7X0A8i1vDm9 ;{id = 62298 (zsk), size = 1024b} +types-signed.wb.sidnlabs.nl. 86400 IN RRSIG DNSKEY 8 4 86400 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. KBS/LNj/KwAK/7Qozeyq/dM9rnRZBfAeJECC7tdYvKG793yLeWah1uS3yYulHTXN+jyPZ7agfbir7vRxnXc5o9NiJKumT5/Ke0ZBRDGlSWyA/AqMfkbiwkLWnUA448wNHbD+3acxd+ahs7XTz1qnEvYLhA8gkbW7PfVCmaN6qqQ= +types-signed.wb.sidnlabs.nl. 3600 IN NSEC a.types-signed.wb.sidnlabs.nl. NS SOA RRSIG NSEC DNSKEY +types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 4 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. tV3HzeRPSp1JvGuWkzW5WiRQlH1MVcIddFPT6P1FXHfzKHvA6/kEBxH0qRraxqx++Sj7PX7SmR7qHoa2IUVAYwVXiwMf7Vm1iR9ReqylMDOSYnCCIrTj/H1rkM2ohSabn4ONmmuxmeHgm4IjKHbIuKPyOY12HcNPV0j7dwM6Xo0= +a.types-signed.wb.sidnlabs.nl. 60 IN A 213.136.31.221 +a.types-signed.wb.sidnlabs.nl. 60 IN RRSIG A 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. xVnnWCWW7jRgCpshnZWWxTa7so+1sSlTvYSCdTIWbXp8+FdF88NND23Evevwf0cBjiKvk5hzowCIHo4d201EtQcAUGsBue1SMg6Dg6vXrsB9XOt+eAwXUsF3diIptDB0A+jJ6bzxs+DOZGI7eFpAw/eCnIvOMOunQrTs8qNUt08= +a.types-signed.wb.sidnlabs.nl. 3600 IN NSEC a01.types-signed.wb.sidnlabs.nl. A RRSIG NSEC +a.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. yMJ9D23OqKPeGLqE2GQ2Heu5K9le1ToIfO7fQ1Zwla6rwIvXixvBm/s220nrIGDE0ULRC9FL6Esh/YGee10eEOebCpaDmSyCR9+Ea3j1CZpJIZLYFDEu98rlavFSx3g9FPpFnQiVDI+e6Fm4bU9g7GyivVh7wyeu9pAB1SsxyDw= +a01.types-signed.wb.sidnlabs.nl. 60 IN A 0.0.0.0 +a01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG A 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. xvYiYdW0OQt6XXt7vgGZztSW0hFXBp7GxQzOeF9mozvNbFefTu2XVZMJYYxOhNo6HvYbdPilVs7ZCv7wlzT6x2SOP+eHt+bZBIoYG2nc8se/uh9K0jwgPp6U4pgIFC/Eawp7mMzZR7bcJ0vlZSe3vjkxCdhoC3a0peHmiOLFpF0= +a01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC a02.types-signed.wb.sidnlabs.nl. A RRSIG NSEC +a01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. c9gz6OkVfusvO1G9Hfb75OrFaqz6QzRUhD+PyqYYl3KRv4eAv9q7310svKXKHVlB+FLNCGMsMjBlBueCF0mY/np92c8uvxbqOErGkf1vU1SAD/PA79Gdemc/9+q9bmfHSaW0/4eHOGhnUy2R4akcxC7t8Um5+z6WYIoJkWjQBLY= +a02.types-signed.wb.sidnlabs.nl. 60 IN A 255.255.255.255 +a02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG A 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. eqp/zC5jc9ypeNCsmct7DNXIyKPEDQWxBt0G42OWUOmmBh3lVRngG71RL83VHFboMlxsAUBjKRbw9kDKM1vwoxcDtOOF0ZbYTnj+C6TAPDIeiAVCfA7k1kvFtwlhBDVVWMKOeVlMd+rr8tQsGKtNE9IJHmS4VNz+GH79W1zHikk= +a02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC aaaa.types-signed.wb.sidnlabs.nl. A RRSIG NSEC +a02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. w+df+olnBx6YLSnE+sawqz98esH8PTS6reePfg6tU9qUt+L+9GlZ8AnmOJlxb/issPcaD4VvBprCQxLSGH0jJ77IsHh85KZNeY3LFcl7OWks5wEPNi5JaCqDjmMosE5Lrb//QS2cR0gYWlhBtcbhvQIkRzOPI17sDlT+flFULoo= +aaaa.types-signed.wb.sidnlabs.nl. 60 IN AAAA 2001:7b8:c05::80:4 +aaaa.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AAAA 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. NCF4gq2gb82K5xxmGqSE4jeo3tCyhPkEK3hQmIZpuGHLaRkV5XWKENKl6ExhNUy2WUAYMqa6FtL5f2tEymKeYmHLwBAPSJpDlcXiHmeMyY9tQZiFhpg48wtUbgyvbAgqvbNU6kf8YU/YaQSoMu/HDPjtMIbIY9L+CpphD49BgyU= +aaaa.types-signed.wb.sidnlabs.nl. 3600 IN NSEC afsdb.types-signed.wb.sidnlabs.nl. AAAA RRSIG NSEC +aaaa.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. gRNkK0ecH2/TbQryyKOvsu1QnKT4cHgRcUfZYa0U+V5532ggDwl9QxtyPKK7BbuAPSucLncSKv/h+Wy+wGHVTZkXdgSEe1QeEAbFTo+HBuWTvvKIkd8KTnwFRT2efuTtC+r6V/Njwb54ZzVkRxxvo6SCsnKKgMvHzjOsGzwDbt4= +afsdb.types-signed.wb.sidnlabs.nl. 60 IN AFSDB 12345 afsnode.types-signed.wb.sidnlabs.nl. +afsdb.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AFSDB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0zcmBgLAXX2OaJ+38g4JN5oDwsXloVQcP3MHsSXAi8mWUc2pYYxl58IFPaNhqm9Q6rSnng27VwFxBw2lP1SyGmsgiMtgbXV6z0uMP9TS43CMiQHFt27cMnL9nkM8BJBTorKHiSHD4CjsAH81i0VpcxMtSjO1/rohzCyp5ATqxFI= +afsdb.types-signed.wb.sidnlabs.nl. 3600 IN NSEC afsdb01.types-signed.wb.sidnlabs.nl. AFSDB RRSIG NSEC +afsdb.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OfBOAZzfR6bpQ10LUN/tK8xlGnQvs7sCPlE4nXaLzel8EdOLyDYj6oaez+c8TxIlL/3XRsM9wmkUuUJ0nwu5mluPwx+W0wR5r8BF4px22k5YEP+FYbtz/HXkrCUCVFG3Rn4hsLX0SJ4FqRvsszxanzWLDGE4Hhma4QpNgVhlz0k= +afsdb01.types-signed.wb.sidnlabs.nl. 60 IN AFSDB 0 hostname.types-signed.wb.sidnlabs.nl. +afsdb01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AFSDB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. QzI29ze2x0L5UTSkMKB9i1HxKGz2SxHMR/Llf9VBu5PcfdPw6/7b43zSLrp9DZCL2WBTS/9aPWX9P/Q17JmDU811G+Mdy1okjVyoT04FFKRVFEemU6T5CEycaIKTzVqQBdM+v87bknyB+eugm3oH0A8rWOWtZ/mg5MvvBQwlnCg= +afsdb01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC afsdb02.types-signed.wb.sidnlabs.nl. AFSDB RRSIG NSEC +afsdb01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HO9r5sk1ZCMZ3vuZA++PD+H5ZHJjGE8YoAPmRZ7wyN7ODcCecx/MU1HxDLKLDJhpk9YgQDSm3yxcggDSz/13objsyIZlnzCBQrMDSvU0ykqz21msfJkYe/kA5vds+fMHSPlB9MGYEaJ01f5EzkSmF+9D81e4uVLlNTU3hfYma/Q= +afsdb02.types-signed.wb.sidnlabs.nl. 60 IN AFSDB 65535 . +afsdb02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AFSDB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. WRwlGYPHleWaFOrFiXHNNtllsBrUav1Nh84KD7dBxpFQgswCqfq1I9MwLEJjM6O5x4kJgTJs8Aool0sFbOY7IhiLwcrAKGQTPaKWnj9uAGuypyHDiAzKmbmwYZEgr/BCgQWorHCVynwbmctR4LnYuBb/mpKtlRfkQi02bTMPZhM= +afsdb02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC cds.types-signed.wb.sidnlabs.nl. AFSDB RRSIG NSEC +afsdb02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. eGFG3E2Smm216j3GQcObHdgM2vwysnHdDSlckN5JxKMQ9Pnmhl3AWN3LRwpgVpdObGYLinJaRkb/feWUlgaemJIeFTaZzd3ZX5QG/egeaOoi4Q0pD7uwdeeWpcbepltGr3aD4qg7WkBUAxBseKnAS9jrvbC3iF7z0XzfN2rCSGU= +cds.types-signed.wb.sidnlabs.nl. 60 IN TYPE59 \# 36 fc b2 08 02 86 63 2f 83 49 4b 1d 70 37 e7 29 49 fd 6c d8 68 9c 5d aa f4 df 1e 5d 7e 6e f3 ba 28 ec e1 e3 c8 +; RRSIG: +cds.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 3b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 7b ac 8d 49 e1 6c 37 44 de 3c 9e f1 98 c0 54 80 f5 23 8c 49 62 01 2d 61 91 2c e5 32 c4 15 09 c7 70 a8 9f 55 62 43 52 bd 7f 31 d7 72 d4 cf 76 d4 e0 20 41 d6 58 90 4e d3 f4 f3 a8 5b a3 4f 37 24 44 d3 36 bc 8c d7 fb ee 80 8b 5d 37 15 71 b4 b4 c1 41 9e 47 23 09 19 39 d3 47 52 79 c0 31 c5 ba db 9d d2 24 92 77 55 30 9a e0 5a 18 93 65 3a 63 a9 f2 1c e5 24 9a 72 1a c6 41 5b ee 68 30 99 a8 +; NSEC: +cds.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 44 04 63 65 72 74 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 10 +cds.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OXca6RcZ3vAaA9Z7UI+E0cUdmKmcrdpNChJaVPUZWqKs/cN1hvCB4P0MfsMWsO5q4VlIOgyHfSUsIz1HGFeNDeK9jndjYxUtE7HvRHPrl+PggrVjkILQHfAs0n18707bKXptKhtCFIRlzenERdP+z83Sk15AoNBejKUgvlFiOiE= +cert.types-signed.wb.sidnlabs.nl. 60 IN CERT 65534 65535 254 MxFcby9k/yvedMfQgKzhH5er0Mu/vILz45IkskceFGgiWCn/GxHhai6VAuHAoNUz4YoU1tVfSCSqQYn6//11U6Nld80jEeC8aTrO+KKmCaY= +cert.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CERT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. J0QSoNK/D7jFxrpEpIXtbBX8GvdvWPBUH20H12om4Kai5NUeJCv8MN8ehHsy9UCZjg0+S+BynRBsvwajJiOTMr1C7pKs077Ju/XjMa0umoYltDbBx26Q36rwnNN5O9zb/dyXDxBksK/twZViNZrRCq90L+cEkwXDMtjiqXA8Zag= +cert.types-signed.wb.sidnlabs.nl. 3600 IN NSEC cert01.types-signed.wb.sidnlabs.nl. CERT RRSIG NSEC +cert.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Y+0rG4IrW5psyw9O0B2PFZ/CFGpnr+M19dUP9+el6BbjjYpkgyF/n4t5SNYBYRy7Uqgw/qEIIGOImwlJyxPX19Dvl5Ci4T8RjbFkcYQWb7DGPLfSaDerpsd4LzDMAc1aqheHFXSnRYFY3xeTkLGrZnOq/wE/89oV/ZvnYSGiE4M= +cert01.types-signed.wb.sidnlabs.nl. 60 IN CERT 65534 65535 254 MxFcby9k/yvedMfQgKzhH5er0Mu/vILz45IkskceFGgiWCn/GxHhai6VAuHAoNUz4YoU1tVfSCSqQYn6//11U6Nld80jEeC8aTrO+KKmCaY= +cert01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CERT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. mpC3G7ND9TK2gCNHTrde4bNNzP/jRi+USwQzEMUOKo+rAiOAAJXz/3OxGFBjLEIPwg5d8DzZhf1EcV66HqNHxaW1gk6NQwCbdTgvgAeUMJ3GzNyDnrmpaS3CIqURPOo/1T2MoC+DvoQuxO5M5EuQDsh4Uz617HzUE5M476TaqRc= +cert01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC cname.types-signed.wb.sidnlabs.nl. CERT RRSIG NSEC +cert01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. nTaATn7wtzeCtOVpPMH50gE+C32M7YPLbXIZPd9TaFVWN21k/yE1f///BmdGh34hwteLuXTgg47Z0rxHotvYvOy7IkyqPQ13/RYDkf1W//aTRaCUbVpfyNIZ7Zjq5DYxC4iKyMzYJ0aRMn+KMjMHGZuvdZsHCp19QdMvhV/RsHo= +cname.types-signed.wb.sidnlabs.nl. 60 IN CNAME www.types-signed.wb.sidnlabs.nl. +cname.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. iulgjDFHWOpB2RnVMFAu3Nx0AQQ0bq0AXnUOQFma3xQt2ZZXUoXjLebDZQSE6a6afCG9IXgg5Oka6Qzp1N/idRnsKINjpJi6IqdAOIqVxhG0Y9X+DS0HbR8wiikWrBVuBbk6AZsH98SePYh0u6IhoHb3KZqFcsgb37PkpvFYg2s= +cname.types-signed.wb.sidnlabs.nl. 3600 IN NSEC cname01.types-signed.wb.sidnlabs.nl. CNAME RRSIG NSEC +cname.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Vljy+6YhzNQBz+Hp8v+B3+G1Q3kc/asrxgncrWYJ031ix7d5n5yzjib5FMDCRCGxOw39PRcBsumSSzgmr9EpQewfPHQD0ZI48GTqhcxu2Nu6WqFN3OLjhGleECn56WwK9pU0sgRA+CpoGuPlczhNvcAURBlyjzdS089sNANQVoo= +cname01.types-signed.wb.sidnlabs.nl. 60 IN CNAME cname-target. +cname01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BHDEK8+lOpSCfSTSOlOa+c/6UfsI91fTvPGjmgTVixHRJCwBRn9n4hwRscc9OFbOaa/DSN5pRJ9TggNssP2O1Yz6T8PckZnvkAExT10uexIuhY5lIx/+JRAIwkR0r/cObb9bh6QdQfh4+/9ijntpUM7b259L4z0nkc2WQw/mxTw= +cname01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC cname02.types-signed.wb.sidnlabs.nl. CNAME RRSIG NSEC +cname01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. uvbfLhiUEvNUY+3HoaQNOeOB3dCP57THn7HuU9fr6fVGOWkf01AgTigzpk6X/RyB0LKti8hiV3Vn4JimcxljZEOOxUOKwOX1qxIkbrbE4DEviWm2aO6jmskUD9JnAfIJzUDxeFmvZmDJvrcupVMBusRRx+bD12qXuNv77eENlGQ= +cname02.types-signed.wb.sidnlabs.nl. 60 IN CNAME cname-target.types-signed.wb.sidnlabs.nl. +cname02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fI3V1bTtCRmVTGOjuEbF4ue4vsxJzTpLvoNDdaPtrsquSR6pEUAQaUllBnctAD9QNqaiocBkbvI+YqmWe+ALkWjjB2RDDmacHn907sNHUwpDi64akqHSPYpPX7KBLmFXis8SlVgMtrsfqTAPEVhwbm3HmJbIUUhd8xgrYlTQV/Q= +cname02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC dhcid.types-signed.wb.sidnlabs.nl. CNAME RRSIG NSEC +cname02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. MHiiGZ7/3x080HQiQrVwWvU8Zx3OyNLtxYJgr10QZeQ8PDAq7uiTNuP8d3xZ+Sw3vG/RKWzKB1Mdf/cyCuoRS97xtppRynG3KOSk3HTY/FPn5qSe9NNbU4yZvDX7yr+tdHOxEBe5su1hKq+t37GIf2AzBugF2ErRl6UxBrXqUEs= +dhcid.types-signed.wb.sidnlabs.nl. 60 IN DHCID AAIBY2/AuCccgoJbsaxcQc9TUapptP69lOjxfNuVAA2kjEA= +dhcid.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DHCID 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. r5KE7Pt7WWGRgDOh88tQUp5OezvqrIH1Ut4L8zcyL8n+XifOy9tpntknKjTtZsZMnzhnCjwYwAfpOjE0WD1zJ+fLTNu+y324u1ugsZSVpl/Xb1BgbUe6M1/22612EqGcGTweut98HlJHz6liAlWmo1yAYke0ujL1c6TBnXQ0nbU= +dhcid.types-signed.wb.sidnlabs.nl. 3600 IN NSEC dname.types-signed.wb.sidnlabs.nl. RRSIG NSEC DHCID +dhcid.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. R2POgfAcSLuNo8BFu0tVIhki2RDzQu+5bfwbvcVLplsKRffr+By24zm6JYMxBzO22s19NpJvWTi6eO/grI2viXpGvGJJT+cb1g0WDAFmQpjh03iNVhnOsp/Dim2dgxKPmS4bf4TvMAnZXEPg4pfzuTNsWfrfb3preoz7gAgz7cY= +dname.types-signed.wb.sidnlabs.nl. 60 IN DNAME dname-target. +dname.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OPF3jGt9zmdf7SKcW2yJD+lT8T0JVZBl29tQyvJBwbi44ExZY/QBh1YbOfJmPJbq/G5vE6SKBM07kl8OungKC7pU5JsI4osx5DbadBink0hDFdiEqsR9k4BndcbgMVjG3DI3lpR5dtdwR/x7GTe7Jc5GE12mP9baA1QC7uBAHW4= +dname.types-signed.wb.sidnlabs.nl. 3600 IN NSEC dname01.types-signed.wb.sidnlabs.nl. DNAME RRSIG NSEC +dname.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. R+Cv9M1IaW6O2XD7hYgJ45HGGPooNcwE+K1Da7VuvwAwyWyK0Ip3B4nfzdrO2F9PF51uPebKrzPA41X62AxjC1Zj3c/PzSQqOwLONmkdLBzKacT0glV6yzuJcB5XR6XIATl+A3vgGJzj1mhcF6wjV5F1bE8v4b4ysq9lDCy/cC8= +dname01.types-signed.wb.sidnlabs.nl. 60 IN DNAME dname-target. +dname01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HhXaLVh2lDAPxE6XJ/uqUGvpK3vyoPoY2bspICKjlJNosepMbBs95GPmnoXY387L/o20gRF7lrs945enAAuD9HVyBTjUnuIgBT2UIKpOq8p79mLjYYEglSmDRM5h4896PTtRBK3aGKci/GPyD4tDiTzuBMXBhYBI7jPk09v4+u0= +dname01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC dname02.types-signed.wb.sidnlabs.nl. DNAME RRSIG NSEC +dname01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0Rgi/IRR2bIasPGK/cM3rxzf9FixNdv5c7AztYAkWZusIPjnM18wke3FwIfpMCvmHumXiv6TqvbViUMJMnh7maA/mzbROKXHU41brPZ2y+ypM46ChGE5H7I7mldiJg+UdbnIvMjwCmZ5hwr38ylrdygk+BvICSZOKfJutmJm8/c= +dname02.types-signed.wb.sidnlabs.nl. 60 IN DNAME dname-target.types-signed.wb.sidnlabs.nl. +dname02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. h7CPniH+xF30ZlWqmtN+LfUcqMma5vp363VtAiIBV4qLhsKm8SjicBGMzvHNTSqXuefDzZbKt8QJr4ChNuIlAkVqzLSq6F2fLq/142nS8Zz2m5uzYy7j7qm39laZ55iIkYM87NO2t8MyUWNukzfDD5vJpPP8YkIZi28aZZo4iF8= +dname02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC dname03.types-signed.wb.sidnlabs.nl. DNAME RRSIG NSEC +dname02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. W0X6NkFSq040mfnwqoIvMP/hGgd5zXlVJYhAM33glde5IT2XXuJYJ7qW127XrVM1jhBMWsTEk3pdJejq1O2FzvMVVIhRPIOoholiVvNq4GXBxLpJlN+aQohqfTi8hA718pqOJFdf8fAsfTW7TCThc5TwyCB2SHf0/7gA/bM9JBU= +dname03.types-signed.wb.sidnlabs.nl. 60 IN DNAME . +dname03.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. q06U1uZ3VYwAj60QGUJRAzLB2yFEqZwDUqPUZnHysbszl7S5GDkt4aAjsL1fWpvXpwpGPqkEv0yxX/wue2AxfRVRE3yO+Thsn7TIinAoUrPmnFgoMxZcKow2m3WDoptAL3YU+OSADE2pCuYlWeE+EoksB193c4NNMP6GEsnWH44= +dname03.types-signed.wb.sidnlabs.nl. 3600 IN NSEC gpos.types-signed.wb.sidnlabs.nl. DNAME RRSIG NSEC +dname03.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. z85oCM5AXMcwFvloXnXBYb6qWGnSpsm1hPTCK9DP4ZnETy+MaLx87vZNrqREp4ybt4JxxIfNOnaIX3V+XZjOwLNdFz/iEEBFOqWcNKYVUZmp4dj6zGejZkYCEpjS+cruMeLgIqsVK/MpgXldeW/FUy8Begkf15KJlroeXvLmZdw= +gpos.types-signed.wb.sidnlabs.nl. 60 IN TYPE27 \# 18 05 32 33 2e 36 37 05 32 33 2e 36 37 05 32 33 2e 36 37 +; RRSIG: +gpos.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 1b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 49 cb ab ee d1 b9 08 96 95 c5 52 48 92 94 37 86 69 ae 1b 93 4a 81 07 6f 36 4e 3d 3e 68 f2 39 e3 4a c1 06 d4 55 4f 00 9a 39 a7 81 3b 1c 8e 02 07 6b 0a 07 37 da ce 4c cc 7b f3 cd 20 f4 df f9 c1 99 34 da ad 81 f2 3f b7 43 c8 9c a9 41 38 7c fc 6b 15 06 52 56 34 20 6d 49 18 fa 9c be 97 07 a8 8b 25 b0 f6 ff 10 e2 95 55 1e 46 43 48 8e a8 7f e7 e0 51 bd 9e 6d 8a ef 42 f0 15 74 bb 56 be e4 +; NSEC: +gpos.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 43 05 68 69 6e 66 6f 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 06 00 00 00 10 00 03 +gpos.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. N7ZrGEGx8VWu4rwUQl/MFmpb2CKCWSdyYJblfqycr0EDZrf8O3Pxa1LQ6kAsgErtevsA+Jv5iqpWdYyVq0vGYKt1mXPVUD/cSNy718ACNd+828zPoj0JQlFCt+MUMChQD+pIX5aUAei4X0Topcbc6yNoaF8fSgtpnoknO5RQOc0= +hinfo.types-signed.wb.sidnlabs.nl. 60 IN HINFO "Generic PC clone" "MyOS" +hinfo.types-signed.wb.sidnlabs.nl. 60 IN RRSIG HINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. s4fnRSRBplDkwpDLvSy5BcsqyI34GPAyzc5oF8ImJEK9NFnCXUvXoDOuBw2Ku7LThIlK+qdhjKm8ytRNbE4iU9ycns4toTNYkHkig4k9/k3ZODgRfZBoXbtYrBS0IddPpzrCSWdpGWSkNWSRlhu5BPQ8OpE0pfu52APdYHCByt8= +hinfo.types-signed.wb.sidnlabs.nl. 3600 IN NSEC hinfo01.types-signed.wb.sidnlabs.nl. HINFO RRSIG NSEC +hinfo.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. vHgEKVeYRKSlwRn+ThJJTS/37QxlGVbPul2q2tRuCrZwC8CRr7UmRZw4zPXjfrshp/CH+p9nTXWkmn04v0ur70e6eZuHd+iojLmYoPJKnhFA/Rzo2MPu/p29uYI6M35stWTePAZUaoZIvD/7o+y36gSspYRARXO4vZdQx+zdffU= +hinfo01.types-signed.wb.sidnlabs.nl. 60 IN HINFO "Generic PC clone" "NetBSD-1.4" +hinfo01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG HINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. LRlHYaYxa+jtlO4TqP85UeB3qLLHWl+TIJr4EYFQJEBhK/Rsgh6z+0W6QOL8MwVqVgJrr6bcOI1/yZYHMoWUS1bjzCGa1kDP529TAfJb3kBQoBxUHS+Lguw7VLV5GWWHo/0SPOFjaRXdKN+E7u0KYWXByGq6LJ0Le02nlyuq6Xo= +hinfo01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC hinfo02.types-signed.wb.sidnlabs.nl. HINFO RRSIG NSEC +hinfo01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. xSacPtyhS47YjOtWm1JldmlF4Y/rFbJBwGlDmajlSHSzymSBcr2yMr3YiiFDItd4BM/ANjiYKx0nkATbFvN/V9toSOEuuwwyvBQN4hQZk2UGQ3GOWdhIq7oEPIKvNxxNbNT0thIUnGt9rN6u8KRB+2kWJHWf0soS8zd4oqHyRjQ= +hinfo02.types-signed.wb.sidnlabs.nl. 60 IN HINFO "PC" "NetBSD" +hinfo02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG HINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. UPJ8+rMZzLWgdtwklca9G4kG5mY/d70CRtXIKZxwgd4IuxcSRPf+K0d7/SEkPj9qT1NKtFKMUhvLAeBCck0Z67HIJ49Ke1a0Zl5ONJTSb+deCVjSaI2c45/p3D1yLt2zwqf7G16GlpKd4sqGkZtP5Jrh3z98Ei/hwiAqqqufgYM= +hinfo02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC isdn.types-signed.wb.sidnlabs.nl. HINFO RRSIG NSEC +hinfo02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Qv+RbcYA/0GeSwan8b4npM1t8Mh+pkkhzzYftAwIpECDNeUZIrfli4QCiqnK0EDzXpTGZ8kSyvVTOpC0P69MM1gs0KoxX78iMD1nDb/wnEMF6ij8Y/wsPaVJR1x5uUp7Tt9gfTAcIqkUQusUMiizM9+YCkp12oFyU5rxavZvCzE= +isdn.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" "subaddress" +isdn.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Ya2+U1GFFqTjqc4Mk/VaPV9P/3DXmBlX/08C7HwUoXE854OHi5zpqTom64PYRdW8AyvJDUVDE+Jng0V6aEQzLTMq6gnijXYNGFjIUHv0TrowD6NS/gOjrNNK7UdxBVfgqQQu6jzPU0V+4djHGrjk8vTjXnhqTYnMCDEO0I8Sgec= +isdn.types-signed.wb.sidnlabs.nl. 3600 IN NSEC isdn01.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +isdn.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. M/nT2HKbweJ/u2P3JyZTAWa7mEzjl4TyGI6JsBiksdj3BJtwp61eu2QbvDxlfPuP8Y3eHVwGjlrEimfajq4PZI2zTD91GeAmCAK/Wvc9g2L19pZgyw8Eg5v1u2jvmSkydEfdCOOazit05QX/RAa9EeBxIuqgYpkMpcPVjVcGR5I= +isdn01.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" +isdn01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. JWYfAKWrIqN0vKHoFIjdHEdJc7zJoyE1shbyGmNxzYYIgWECshehRnslifsTW/bjhshy24Y+ANEpLWuu1lMYTZ9iLqoZaj3vOFrUxAf0JHasrDNxr111eVUK3CHYKccTs1tU7q4ev0Twm7BOTvIN92TiiOBqveGdmYhJHNUk9/E= +isdn01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC isdn02.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +isdn01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. YgHAIvmlEr4HNgiyKNUQ90UAQu2ckPWMziTwPcBKalAXPaDRXBvu1nNgXsiRhRzRU5zQaArOM4/aGiZNAX+5flzpAaPYTRrUhLY3GLiqm/a8b1DVqztVr7M896ZEPYBNaoCvOJmfuw1NaRIjEDs8x9INLqnsKNrcRaINAYb6euk= +isdn02.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" "subaddress" +isdn02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. vn/vUij8ORct9C7+pc912ZuASlySgSYLs2OQ0MyewuFmt2fa6FRr4bP780ukPPy7iMGYNkH0hqabm0rBPm27CYVOMwoOU75EsnPVY/tGqn1dyTkNJ28iEUKevU1cgRogm+hPB2slKNXOzYAIUYU5ioXEFKVKgvSmmNDuKKoBAgI= +isdn02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC isdn03.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +isdn02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. W3DS27jdcoFpLGrPIrcowj5zGnWZwLJDql9ida90maIs1c2XwJjXur+msUf6ciD3T7vcExCENyjcuRIfXrvK/qCuWDpPK0pHw2SGQ8oX4Cw/ghgRj/IeK+MDjmM2ZoJ1Q2yWNKFntgPzEBws7cqjpBLOAz45e7WavsY2Nd0QmwY= +isdn03.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" +isdn03.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. uRRicG1FyQSOXmWEO+3hITRQyn8uOdPISJrDhPRWAJQaFD9lvnG4zuu0lOPQsHQ/S1YLsacOQ/vfbOMlNe3ConSvpKw4tE2tDcBxWvkjt46KZ/krin725vuTI2T6kGy2H/JS719XQ6pY7WgcHHrgUIXL93tcqKqBEkIQpp+5w70= +isdn03.types-signed.wb.sidnlabs.nl. 3600 IN NSEC isdn04.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +isdn03.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ooa/OYBcsOClpGsBMkwvXx9NASD3sS0wMWcHUZPq/ciGxHiDGwVrxKUSyqDgFhflqwJs7MFzyuiTAp68f2G3llor3hkk7ihidpmgAWu5oWuaveaL/jd2Jc841jCVoOv2dlFnzZwsdovgQE93lmkyTWwLR8QIsexrWXBEGFA9wh8= +isdn04.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" "subaddress" +isdn04.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. veWeKnFf5xQodnjyRVtwExhXcf3XL6oyf6QE9l8UYIfZcsrrdy5FMaq74lPArdw4aq+I+wt9LKvboWBlC/QreT8yAEBG+OHiYLr3qn2D9KUIFnUrvhU28lnITRaKlknoky1RFZBLQCey+BjN+Av3Q2i7RrP5R+puOqSf7FE4qwM= +isdn04.types-signed.wb.sidnlabs.nl. 3600 IN NSEC kx.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +isdn04.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. P1bsQZuUm42v2ZnxLoowWRLofzBSKOE4+fjHmwB/lvj0VQcDaMKQdZfTZhVN4sEF9SDX8gMx0r2y6ERGQKbP+6u78Uin24Ncal6AUdWXCIb1oXP2+rfjkrpSO3ArdD/P3IcgDpfHAErg7aq+jlbTYuW/b2Aw7OnpnWk/E7rLLdU= +kx.types-signed.wb.sidnlabs.nl. 60 IN KX 10 kx.types-signed.wb.sidnlabs.nl. +kx.types-signed.wb.sidnlabs.nl. 60 IN RRSIG KX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HTnnoQj+kXnXGAhrMevDjMltI7QOmsK7DRrtwfJShuiZFf/fQ5wdDKe2vaYHQ7AsTN5GvPVtIvi/anHGn4ktt5ONnkSOHSBIjRu0IIDYIaF5v7kKpnzc9Jim3933ZEyNa3TEXkWUc0AUw9bYPytPZqjgF61g8CGls0Q8x5rH5B4= +kx.types-signed.wb.sidnlabs.nl. 3600 IN NSEC kx01.types-signed.wb.sidnlabs.nl. KX RRSIG NSEC +kx.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. STlc0nU1R32UIhYyrWQPo08rZ9ZIiRrKKzBbxvZo9bTz2uVWNPwEJnpzmmK2vqyXfbk5HaT3tG+enEkO3yAct4yOBDaW6EncRmdCFqbK2fmx9hO+P+pw9ToqYk/68YPKLiNrGMXqxl8RfmpX+QVJdAwuI7LG1NPT24eTffH34d4= +kx01.types-signed.wb.sidnlabs.nl. 60 IN KX 10 kdc.types-signed.wb.sidnlabs.nl. +kx01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG KX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. lJvhWraGMDMIOkYtcTpS5Degg1H2H4qRBS8qERQp0pBEldKalxUBMqV/Z6ePQM552KUXRlF+pRtzGcLvXs1eX/kv4sz5+2gEpO42u8g+DU4X/VK9cbESVc/RWQsGCnhyT4qzizzIIkCFa5WA/xhoBPmK2wmYwzJPoDvNZgSQD88= +kx01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC kx02.types-signed.wb.sidnlabs.nl. KX RRSIG NSEC +kx01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. cErg21bBzRZBpzfoJN6hODhwokb54ZFleUvOAq1EoifmHVci+vAu5L0lPU2BAbMPjsQ9/QQmOyJI8TZfbxWvHtHiRcZI0wm5QoKxMXgRq1AggrlTnKgBtfkAhPiuJFNyhvsDzYV8fV8eIf0Uaxuk85GhciuE/MqpJJPTzUqXP/8= +kx02.types-signed.wb.sidnlabs.nl. 60 IN KX 10 . +kx02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG KX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. m8pFgj3dgvmkH/AhwBI+w1y8w67Fp0NVwAkCXaOyTSh8HZbLPmapky7TCzWBsc6rIeu/yNEqChhEqH3FTdhXtGiC8cuKy7Ta7yIP0IjqARXXDdSvKZqHboFv91wOjRH6zvkGwQGzoJukimqELUIuZVLpbWMoDPGhy3sT4Hi3AeA= +kx02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC l32.types-signed.wb.sidnlabs.nl. KX RRSIG NSEC +kx02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ZnxdA0mzm7eb40IM8R4zZAZtGiaPK/leV2y+F8sSIlVpLizLW6VZHH3EaizKnQXUgqUbxWa+SqOgIvVGOlez3ygByKHJTiBAKy4NanSecWmm0vQ1N35GvqcbGuzNECtktD8LB9L5C7Ao40PmDP1lQvgxeAqD74aZ1nNZmvIkdMI= +l32.types-signed.wb.sidnlabs.nl. 60 IN TYPE105 \# 6 00 0a c0 00 02 01 +; RRSIG: +l32.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 69 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 c3 2b 9c 1f f9 dc ba 10 0f a5 f9 33 65 8b 71 c8 ba 93 52 c4 33 f9 59 f1 f9 d1 35 91 77 9e f5 c6 1d 0d 46 b1 7d c5 45 67 2e 8b 71 16 66 76 04 44 8e f6 d7 8b 28 46 b1 51 40 45 3b 47 af f4 40 55 81 7c 91 c8 ec cb cf b8 2e c8 e7 84 45 27 56 4d d6 47 df d3 0a 81 7d 2b 15 c7 b2 d3 cd 40 52 5a d3 49 f4 2a 0d 9d 5a f7 ea 3f 72 14 cc 8a 54 de be 70 dd fa 2a 45 87 c0 60 b5 0f 8d 5a 1d 64 fc +; NSEC: +l32.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 49 03 6c 36 34 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 40 +l32.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Nhgme9mLX+ff1Etmoxr7EAawHXMCpGCtb7RMwi/2d8J/YKo1BXK75teXCjJeSIlG/5JXqk1M1qw8QSkx+aWoKCUSBr8bmQt1qYKs6RUK0LoT1fXfBWblAQY7p7t2rEt8VJvhd7blpB3/ZCkuzg7TZn96zMwH6mXBYRKCMv4JKyU= +l64.types-signed.wb.sidnlabs.nl. 60 IN TYPE106 \# 10 00 0a 2a 00 0d 78 00 04 05 03 +; RRSIG: +l64.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 6a 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 14 be 0d f8 8d 72 5b 50 49 36 1f 50 8d 8a f7 42 0d 22 6d 96 c9 f5 20 cc 62 af 7d ba 10 bc ee 7b 5d cf 85 fa 31 72 e5 1d bc 25 bf 58 4d 62 3c d3 15 b1 4e 92 cb a3 0a bc f3 03 d9 ea 20 a7 cf d5 5f e3 ac 76 b0 31 bb ce 45 22 3d 82 a4 2c 06 f7 fc 3c c9 d2 ba 11 e3 06 08 57 32 aa aa 84 80 34 0c fa 8f ae 1c 75 b2 0d 92 32 f7 81 46 86 0b c6 e3 5c 96 80 71 24 8f c8 bf e3 de 9a e3 b2 e1 27 +; NSEC: +l64.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 49 03 6c 6f 63 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 20 +l64.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. MCOIhgOHf97DPKlkrsmKSRxlxXBXC8iDaWxh55LCSfKU4gZ5kXjzCYSiclN21xOHVsfTzNfrQoM+couCSMdaC8W2LAl7+SMyqYisbbyR130rIx/QVnokhPP4XIyaSqDVWWzpSlRX14LjWFubF14Z+NU9uXlnF/iAMTT83ftHC9E= +loc.types-signed.wb.sidnlabs.nl. 60 IN LOC 60 09 0.000 N 24 39 0.000 E 10m 20m 2000m 20m +loc.types-signed.wb.sidnlabs.nl. 60 IN RRSIG LOC 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. gXMPjxoDL7d3ClMJFvXf8eVrU+cry/+vPE3SxC5Ko/K9mYNH7m1ccJWqt9U/0/L8gJS88TLfrBTXOfyouhwpe5Qc7WQuY/tnG+YWjPmvAOfQoPfn4jv8ywy/KbUsAb1QBs9thQh6y72KGXqJuq17Yuw4jyzwEMhKMf390JsnYKU= +loc.types-signed.wb.sidnlabs.nl. 3600 IN NSEC loc01.types-signed.wb.sidnlabs.nl. LOC RRSIG NSEC +loc.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Lah8vFamyU/NJNRBjF1lsdkgiDYY0x5T6RNGsXbDMHGRIOxyHu1f6DDKUE692xMTF/BB0tLG0jwO4FV9UAttUhcY8EOwFeGZrIXrPYw4bCSmn55Rn1D2IESSZ+82oI0bA+FUtRuNCyJM/Nhzgdv8osx7l3OLFr6yH9cEvvYrv9k= +loc01.types-signed.wb.sidnlabs.nl. 60 IN LOC 60 09 0.000 N 24 39 0.000 E 10m 20m 2000m 20m +loc01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG LOC 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Eo1Rb4zpQlQO56DbVX3HsETJqQw2em+Hx4JqK6sLlVzhP/7bg2lpUyrKFJJlHmHt576b+ey+l9NjGBF90zf7gvJJjXJQgFUYMe2dFen5+npCHhaEguZIPzkSS/L4xkJ/s0f7vxxlH14FNT9bX43JnCcmim7SfRx9zjFKkc2JgNg= +loc01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC loc02.types-signed.wb.sidnlabs.nl. LOC RRSIG NSEC +loc01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. DpDdQRa41+5XRGMShk9LVCVO/2x0xU/KciUQVwD9CSyOv6+ghnoSav9uJwSCigJgpMK8CnFfi15Pff4l2OqJl6fYWmQXmDrkUmO/m0QCC1o/320FTKd6xw4ZTJVCOC5cuX605AGvEIWQUroOO5jO0v0jDG7m3s72K2oSiV2WbDM= +loc02.types-signed.wb.sidnlabs.nl. 60 IN LOC 60 09 0.000 N 24 39 0.000 E 10m 20m 0.00m 10m +loc02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG LOC 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. U9UFLxo290G76h9YkwWT+A9lcPGsmWP2uWC+gJEupYZcI3LezmxSh3hFHI2HG6AbICHaept69insEIc4QQroMN8t72IrNaHrNo55aJf1KF5ksQ9/dHeW0AnL7oLh2KjaCXBklEPjtTY1eaycTmqv18dzKHVbi4oBqc9z2+SxYGg= +loc02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC lp.types-signed.wb.sidnlabs.nl. LOC RRSIG NSEC +loc02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. snf3YYNIR7zeeOrtHFwGPg+0sLS7qlRLpUQK0oZLlssr1xzqhOd09V3ux9YMYwzKQhWlRDrVMvrc60ZGPvTWAOlvZUFhCC0hksKsa1grZfcHtJt2d2ya5WrYxxy0RDP9IBeOowrzGBwx3UsExU08XpZKOeE8DAeYSwTWGj61QiE= +lp.types-signed.wb.sidnlabs.nl. 60 IN TYPE107 \# 27 00 0a 0b 6c 36 34 2d 73 75 62 6e 65 74 31 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 +; RRSIG: +lp.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 6b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 8f db 63 e2 b7 06 29 ad 5a f5 de 90 7d d3 30 c7 03 f4 a3 59 98 d4 4f b7 31 74 0a 16 3a d0 91 86 59 35 3f bb 0d 6d cf bb 1a 6b 02 53 15 99 2d d9 a4 57 21 50 7d 4f 83 53 6f da 02 03 94 72 02 10 b0 3e 35 89 4c 9d 87 66 ce de 5e 49 fc 5d 52 f4 60 68 4d 43 30 13 44 be a0 c6 2e f3 c6 e6 39 2a 41 2a 3d e5 79 5a a6 54 3d 1d 41 0d 40 f8 01 76 60 fa 47 a0 ae 7e 89 fb 23 f7 c8 3a 9d d3 cf e2 +; NSEC: +lp.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 48 02 6d 62 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 10 +lp.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Bzmbk9uCG7BpMNPbWBIjnrLjcJ3EJvxPW+/o+TqWlN8daV6+N7+oWc1K8DupoGB1TCQXykXLR8LBRTcl0DW4DitEIZk+pQxl++L1LN8JJiGFvvtTo93FVxbHuomjR1fnLg36scdo3GlIAG9da/NV5AA7a8r1uhDZ9CirDvvdTfo= +mb.types-signed.wb.sidnlabs.nl. 60 IN MB mailbox.types-signed.wb.sidnlabs.nl. +mb.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HMNktjuSFKEOSRKJQOU5nMsnvadPX6j+MeJKh9WbSvg9Z7SHpakBeqDTSMKRvtKJPT3fH32NgMjlFOV8TSas59bJBpzHbfnfBMWBjVb4jZzswytfKmdhXLoeSRrVjUweQLRE3OIG0qvKE/wSeF0c0fMJVH6eEce+axqV0JANENY= +mb.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mb01.types-signed.wb.sidnlabs.nl. MB RRSIG NSEC +mb.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. m8JzyH2RCi/mAQ9L8nnuIsDjr4X/SEZzGZ/LK7lbRQ305I0oOTCxgmAJnCLi4n29oqCcP1gaymKJoa0CSpXa2lie2pjNuWA1vTtcQiM3Qm4pycwFlNUnZjpxABmUtiyszehtb3iaJtpfuXAKFUsK2TL5yJZoQvt4w5Cg9HS+JNk= +mb01.types-signed.wb.sidnlabs.nl. 60 IN MG madname.types-signed.wb.sidnlabs.nl. +mb01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. TP64cHsuwgGaD2Xxsr94jPnnF2ml6r/sfh6NX10EQ9f4f0wzdRreBJ3rv+76EJX+vZmiT70vZFq9jnYPxF6nN7zYSPuXLJqoXG9qdQGA10yis1mWt5ILB0fDUtzSnt1BR+RapBfHjExe/4W/6XYBu3gZwyQSRXCOFxRy04VOGP8= +mb01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mb02.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +mb01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. lAka0baev8L6taxaF/+uz1mSZ1+gHmf8ggsfahOfSz0mGA0OMfx3P30JWpgaqeEjVnzmxaTcp9Slqse6/SCL0XHh9sxceTKp8BmvGgWd+HljVZRgU1ddas1ffGDS0icrLch2oncH0EEQIJozcE/utB5XjgY8lKAEvP8K+DQd0QA= +mb02.types-signed.wb.sidnlabs.nl. 60 IN MG . +mb02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. R9PVgTAt/htcXxCpJ+k7RKpNFXAsiLq6OYFLZa2/6E5o//vd81zZfethLtmChMDLgBEtfaDAPOOr8L0NWJZGvAKcTR7fQ109hqdqo97ViznGjlv3eBk6C61lmI7W8D7RbaMlYtFFtOjHmreipCd+9z1Gj+f/HdPKM2uwVqhAMjE= +mb02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC md.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +mb02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. giBNbaCTfWM8dHdPxJLRe1fURwlBwdZvZNAyHcX0Qt9tutJPX3CBbtnQHa6UwpiNvnH73V/C78TvLBcG6/IsUaceHlD4uKMRCopi84OWoERtpDoNxg/x38pk4RYC1btf7zyLCq8O+eyfdWrErJtCnWL9TsWXjkqiB0NyzD0WS0o= +md.types-signed.wb.sidnlabs.nl. 60 IN MD maildestination.types-signed.wb.sidnlabs.nl. +md.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MD 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. V8sbjl3GHJcTlnPMrFyJSsgWiQ1nU3zdxySSogbZCGRJoUXTGN3S8CQg4UnYxI0eFRLYd31ijDR1CEIf0ib4ciLQxx8fhjsyB2HUARtaq8GFAzbRGFAk+XjKX3x/d6GUfrRdq605cSy6bgffQtjok1i+NH2LwC8tSYD8cg7VyS0= +md.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mf.types-signed.wb.sidnlabs.nl. MD RRSIG NSEC +md.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Vw8utApHpFTuE2q7GYnmFh5IYkjs21xuE54ctThXxsNQBwaxArIbQkWWH4ViYjTI3C3mXzLgdHYAm9JsP7bRzorZ6ZEfvP/Jb4lzUvxsHBlCa0DKZOcCXKROO8Nq6su9wsd1zJ8v4OyhTNBmfbthspz+Qlr0lsGyrAWqdayOeRE= +mf.types-signed.wb.sidnlabs.nl. 60 IN MF mailforwarder.types-signed.wb.sidnlabs.nl. +mf.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MF 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Gmj86rMvB8g89wprKF9CBeG69kuu217awp1pCzvRDuDl5ApRYM7q9l6oyHfbsC+SXnee0yAC/I4j5xms2IRRtD7kudm0Ds7offyQS4ZciUYKoPemsZWcBa5iPP+NQuO/jPN4QUYmQubz3Y5BhPCROCysd3qgNCSk/ZhmViDWTjc= +mf.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mg.types-signed.wb.sidnlabs.nl. MF RRSIG NSEC +mf.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. aJHxeM2RQnWe6xLfH75EYGvEpuo4tQe6cLhhKApigSGv8ss8ppbPe17qSvFxPJFIpp+vyjrAtu89Avc7cP4UPuXbRKeE3XV+qoH73UTJ6Fs+i1p3dCuXeWnpXNm/r1nGok7tq+BCistIOFvsEiRTN0hsUPH71eBdU7Ic4lV6Bno= +mg.types-signed.wb.sidnlabs.nl. 60 IN MG mailgroupmember.types-signed.wb.sidnlabs.nl. +mg.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. G8YqwCpeBiejn3ifwnGfhIazjZJgzDUY/p9tqd0rPG4uwBvMpCJrx6mkb8TWPAXmTf+NWHly5ti5eOgVFblsfV2sHl7scK5zANsICFmL05gfLToWPCdbpFJ3curv5PHWKvlAYOZt82s0HWc3FLMoHo5OaNN0hGrvgK3QeXXHECs= +mg.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mg01.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +mg.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Zm3LeNdwOVNR+rQs8IIYqTSxGDFBfrRsqBormYF/rxVXcIyS+tA8r7VI4BmBthwfMobYs3FoA6abH78BK1RMsfCR62kH9ETnDM9sTv3tbtFQodyAbiKhVfV0LJZ3LxMqniTHlBH808bOS8sJJtouhpnjwY+lTrMZwJkxVzEIJnY= +mg01.types-signed.wb.sidnlabs.nl. 60 IN MG mgmname.types-signed.wb.sidnlabs.nl. +mg01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. V1hOjXAhf3r1pmyle+XrUWjYc1yPCcvOw25XDbypI1l5SDZ8E+MbjMtTHkwpUhsyHyJwveHnhA7zVbo06eTFWrA4ZPYOyTWCryNAiEUCcJkg6tM+OjQQ42bVsEHR3dzS+6kz/I0r9NIaNpp4ZxTFlFEUKCREMvpzkvI0AStFfEg= +mg01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mg02.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +mg01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ll6lWw1vorF2zwzcHIdjvXZmjO6ftjkXLIq+sRxhvHQs+MnORWX9mnCOUbwhTYEszYN3QGiMo0QZFPUTRwtz4487oARZA3b8f4XX7DM4cPHKcQtQdN6kfAccHMe+Z+QWCTw+i8JEFE5r/cIlRbMNXVrBteCuHTxXTUnA1EEsut8= +mg02.types-signed.wb.sidnlabs.nl. 60 IN MG . +mg02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. gUpI7J4FYHcTdWDRrM8GAdFjII8EeMuJVO2dKszrEv8q7b9Dps9KnE0gZ1jWOpd76dVy0Vwdk+JZe/72QWXbH3m/LtkxhjAK20LaXyxs6i8Qo++1Eut90dHQK55SUHL6VLlmaH8y7Boq2/8NQ7dfGucz3uNsY1VWjWumLcrT2YA= +mg02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC minfo.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +mg02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OTrr31G9kOqBYaKiDcjumg7n838pOBdV/LF7w6mavw2FUJ8y4C0GOvGQSGj12Oh4Ic1fBzfs4Ep0C6b5Vj58dWesLJJBi3GqOHxyv9bPaLtpjDvICN2Bq0T02QZiZum7XMdHQh9P5rIpFek6ATigRAPD+kLXekYGE8qL0fQ+8xQ= +minfo.types-signed.wb.sidnlabs.nl. 60 IN MINFO boxmaster.foo.bar. mailbox.there. +minfo.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ZA/nHCIx0GbCokFbPHO2hMvaPJesIv3gCOgVmjluzGrO5gJMyyerNLYmwVswiTdIf4sl+wi9421yPJhM5whVZI+Nw3ixBjvwg39X5qYG4SP62UIB2QuUGBJcN+XVrjhoGmljgdNcbK3u4HbqVsZGl4TrhF3O52Pu3L9tRC99jgc= +minfo.types-signed.wb.sidnlabs.nl. 3600 IN NSEC minfo01.types-signed.wb.sidnlabs.nl. MINFO RRSIG NSEC +minfo.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. cVs2MX9wIlFDmc+00+hEaatpp0kjCtkUzqJAjGAQKRDvh9oQOWFBOm9vEzsxrULBOzgLNEpkWLvzcc+ikw5pm93066Wt8k5waLmbDqILAy1kwpuR8IFVTqjFrG3q0TVyDrqAj7aJBz2s06w99kbE2vSilgrDZQtg3PjBvN+NJbc= +minfo01.types-signed.wb.sidnlabs.nl. 60 IN MINFO . . +minfo01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. PLMeHJChWBNO2LWbWxsuIoHbovpS3BJgEIqrPg0uhO38VMzQjnlXR2Jx2VByBBtB1pev4LhurUsSzdYxl5dctcWV/45Q/MnJSohOw9CExJhklwf/R9VU0lFFYLl13vHW8TblRo6hO/tGe9IxVs7fvQ0cWz20EknFUSv0wOSilHg= +minfo01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mr.types-signed.wb.sidnlabs.nl. MINFO RRSIG NSEC +minfo01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ugyG4yrAPppd13/GFyutEBSK897eRAkO1ywUWghr450UJLlbETLYLIWA6sR4B+qS3HIuPmr+5XCGrSpqDA2AFwzbJt2QUfySDyycMLpTVk4PVSUlbQYzWTEUXlQa1rqLY6ZTNo1SqXLH6gotUQPLGkF6bupYESgzNe+g5UbsKJ0= +mr.types-signed.wb.sidnlabs.nl. 60 IN MR mailrename.types-signed.wb.sidnlabs.nl. +mr.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. bBDlF97SWIz/mwfbaD7r0LykjewEai/QJTrFSkY1lU8kiBGS49VvnQFtd5r0Vtd6lJPMesFmoS+CRffdueZtRhcMqw+hMaijQlQnIcS6Ffnru/rWCvKKafPUX/R41RHY0OziHOKxkEJ+f4PRzbaHgMzssd44NMV4nKciOJhXl8k= +mr.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mr01.types-signed.wb.sidnlabs.nl. MR RRSIG NSEC +mr.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. d2WMzaFC5ZvUfGM8hXpjr8ycMv/1yzfBxWvy+W8tCi6hmUt9bKzzsDxO029nioa8oQZnJVt7g+fnlaDPFHKEbNYr3hSl0mA9jtkUZEeHwEUd4ya0/Kz38ydEfS+iH90WDZXdmrdJCXgTaLeSJfomFYX18d1t6jYBEOhvg4C4seI= +mr01.types-signed.wb.sidnlabs.nl. 60 IN MR mrname.types-signed.wb.sidnlabs.nl. +mr01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Nhm0i9TBN9GN99QLaPO0NWj0YkkgKpjwrrvhJOB5k8pPM8wX0E+/x0tZTyA9jOK2cQpW0WAhxDpvMvTADQoGAqPyYxkX7txXKxHhrb05dePKfJdROIGcLO1ebQo4HPagzzNF6pp0RNccLaayGEkeCvCvCjYCfTZwQlbjPJnORSE= +mr01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mr02.types-signed.wb.sidnlabs.nl. MR RRSIG NSEC +mr01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. R4Y31APDI987gB48QLvaGNngKr+T6FDsfukNB2khuDjgC6ZoyCn/zH03/cuOJzf7Ovgkm5Bmp6XR89tiKjB5F6X5+SgyHyGlflvSU03ffP9azBXuJA3DtDxnBMra40OcmNF6cIvjFtG/s48u1iyGceDYsJUtgWvSJ30zxfdZLiY= +mr02.types-signed.wb.sidnlabs.nl. 60 IN MR . +mr02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HItNXDRa7Jp8Q91E9m4r7WxCrJhXiR4Hvi1knnVLO98rTuLukNtgCSeHs2cN1iuIpaXLadd8haAZBeK+O5Zo9M7baF+QH0OkcFw0waaKixYnsEAD/AZgfoK30qaOlliZYj9tU+UdiIUMxIxbyNrUDff6S9YrKYY4azVnbwhRl+E= +mr02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mx.types-signed.wb.sidnlabs.nl. MR RRSIG NSEC +mr02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. LHduN8uh/6N8VCorW8d/xQN5xZzXpOm316N4odBrstJZ7Q9OD0ZIvGc6+EVUNdLnnoM7h83vZMW7C0KDms4cZWXio/WC8zoBRE1nzmRyAgc3DIeyaaHpOwvf5Jlcs657GD5Uw39zF+JJtnJbJ1ZK+Qvj1VXkn+J0Fi/4xGIeLNc= +mx.types-signed.wb.sidnlabs.nl. 60 IN MX 10 maildoesntwork.types-signed.wb.sidnlabs.nl. +mx.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. DoOq5zYUjD5cCADGc/YXurDLGiXIQ7saqju7LSU18cn2/TXqFLBEokqA7vJxYNvvzU8vUsaUOfW0prN+JHKKHWTVncgoiCkZlK5DAtWN3OTtr5naHB/XGHQkPA5iTorbgvyUFchufHk2rvJ+Z6wmKGn+9ZmJQU60+0M33LER2/g= +mx.types-signed.wb.sidnlabs.nl. 3600 IN NSEC mx01.types-signed.wb.sidnlabs.nl. MX RRSIG NSEC +mx.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. nRD8njAlg2bdarp0pVpcjfIEtCmmGRsZG9BY5S6L7pIIGwkZMzuS+9J98XdqhE+Q4sN52zkVoCU5ILbV5RsOS7uFj63+l4Kk6UrF+/3CAYgYvex58QniUj+iR8NYmDwPMBIm21jK0pyO5inhNq7abik+b0V5PZuQWcPfnSxjVR8= +mx01.types-signed.wb.sidnlabs.nl. 60 IN MX 10 mail.types-signed.wb.sidnlabs.nl. +mx01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. qGwRMqUKhMORO3WZb8jEzRQvfiuRbZGAttDIEAHGxbSwIf8/ag8gY3zfFQnag0e/XcqhbijZuAgGu8qPszetgZNdwaEQ/MzDQtb7YquvmJpX2LAE0Q20Jfulqg6n1ubIOqNDsL9f+nidQj4dAeffmicW5oC+g+/ATGSusNcZinc= +mx01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC naptr.types-signed.wb.sidnlabs.nl. MX RRSIG NSEC +mx01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. PDzM7fk7l1BqmEfvTHf6Q0PuIVNAklnvGYQPWw92ZYleqyauoh3phEfYCklheuGZVftInrAWlTYAESkXRuGPfloRMUDgELuJo//0MIw1mJBR89xNxBIss10ZWwtpjSKtixmb5TXVjrJlNtFjPI/iXrkNQsaYAT8xnHY96UlAqS4= +naptr.types-signed.wb.sidnlabs.nl. 60 IN NAPTR 100 100 "s" "http+l@r" "" naptr.replacement.types-signed.wb.sidnlabs.nl. +naptr.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NAPTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fXCfkYMFOGwVmZmVt9nIUJGHeGQhUqGuzbDtJuYhHTKmwWDpQEt0PB9yIOyvJcjCGtaTcrEc2z6xH4n+gRb57aN8xByFNqk1QisrGChOalhubXbV77RwRm01IaPT6BJXgSVONBNvNBn3Hq2ASPx2EPltE9EVviOmT8EESIYC8+M= +naptr.types-signed.wb.sidnlabs.nl. 3600 IN NSEC naptr01.types-signed.wb.sidnlabs.nl. NAPTR RRSIG NSEC +naptr.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. j3Lr01oO7jbo30NLkn/l9wGOVTSk2+nfxWUNw7csd8RcUoR9lrkLYahP7kVDMwIL8sGsTxsU/dVrAE+Eu7NXwml06uXo+rhs+f9khhRWbb6Gv4E9clJTJbjlaKiwuKulGAiax/Yt49apI2rFnyfROcQjWePT4PhhmYWSA7c59J0= +naptr01.types-signed.wb.sidnlabs.nl. 60 IN NAPTR 0 0 "" "" "" . +naptr01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NAPTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. pgFTFWJdxj2oZanic0sG4CFRdiPKY12gJbpnivQoAclhulCFY2eaTH3C4RvVA7riJ5M899cCCEZkrAD0hnfFqQBkYSqdzTgXHp6Qc4me6T6VWJ+4dXZwD6KR5t+KsjTBGZFLswukfvSicyENwwUp9wWnrxiZIqOVbX9P1/xa55g= +naptr01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC naptr02.types-signed.wb.sidnlabs.nl. NAPTR RRSIG NSEC +naptr01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ueV806APghV9pDNzvFrL8z6JobK0zxFL4z8Qg6oOcNQEusBiQ4V+BxkedUYQhSn8iPZmX7MZHMRFCCHT2aj/WMSwnb9jLZSi0bGC6lK72vF2NJpKgsRZejcBHvE0biVv1sKtqRnRyO9ro/aPVnDvrSf9lJFIiZ+w/1eo3bvjuFs= +naptr02.types-signed.wb.sidnlabs.nl. 60 IN NAPTR 65535 65535 "blurgh" "blorf" "blllbb" foo. +naptr02.types-signed.wb.sidnlabs.nl. 60 IN NAPTR 65535 65535 "blurgh" "blorf" "blllbb" foo. +naptr02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NAPTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OoAzH1lHAzjHTHvDyH7y+oZR4cs1cZkV9rF/MBsAF9m2oDjSsAgxxVpOxFxK93Frs6rcZ5GpKN7Wo8Lo8q3YVRb1hXSRz8FfUYxuL9ODXJZOcMBil68opwCt/Oc6ukGFHdQ1brlEyZOQhL6oytdsa5wzp56XrCpRdqtuXzR0OzM= +naptr02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC nid.types-signed.wb.sidnlabs.nl. NAPTR RRSIG NSEC +naptr02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. dxIxqn17d/wwt/I4Yht+cHZ9t7Iz9hqmKNWDsALvIEuMPe3CmdQ6X/ngC4LCRn86f9skAHHrKc6VzIk+YOHGZI96xCyrlhWG8NWt01bRLdw1l+y/teFYeGDwVWDBDA1UDmdM3rnlLBpZVCEy3h5SvXOc17ncjI42CvnflhLJsm8= +nid.types-signed.wb.sidnlabs.nl. 60 IN TYPE104 \# 10 00 0a 00 94 01 98 01 52 01 69 +; RRSIG: +nid.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 68 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 25 62 7d 85 8d 06 c3 bd 42 ee 06 2f 18 a5 1a 03 b1 8e 71 47 0c df bc 08 0f a8 55 76 fd ea c4 67 91 d4 f2 aa 6c fa 3c 8b 6a db 1b 42 f4 49 d7 a0 85 c4 71 1c 99 0a 00 1c 7d a3 b5 c4 15 ee b5 d5 e7 b9 1c 4f 00 12 ef f7 bb 96 39 c1 d4 9c d5 f7 46 11 98 5b 6a 11 ee d2 f1 f9 ad c8 73 21 98 4a 78 48 fc cc 0a 9e 0e 84 69 eb a6 e1 68 47 3a 54 e0 7c 64 44 da 39 b1 60 fd 6c 32 39 87 66 b0 81 +; NSEC: +nid.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 51 05 6e 69 6e 66 6f 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 80 +nid.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. I1WXGFms2rtmsAvfOgSMGZonUhWbDOhIO7m0h+oakKqNTbs0JluvzF+sJrzlJGnmYdxZ3D7qP5GDaMDjy0cHMg96BBKwmRcMFJfGDfaJNvEzi/yNYZdbwSlY00+XiLWfSa3/OkBIyxx6tvwGwjkCMTmHJXAdhRSHX6Nt7dGj6F0= +ninfo.types-signed.wb.sidnlabs.nl. 60 IN TYPE56 \# 27 1a 54 68 69 73 20 7a 6f 6e 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e +; RRSIG: +ninfo.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 38 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 10 dd a8 f8 bd b9 54 1f 90 5c 47 fa b7 58 66 7c 4c 95 2b c6 68 71 91 fb 39 ec 8b 85 cd 76 aa 77 29 8a 46 a6 df d3 aa df 05 f4 56 8c 14 20 54 a2 11 a3 18 86 10 b9 a7 56 bb de 9d a4 e3 0e e1 ab b6 15 bc 7d 10 ff b8 2d f5 00 3e e3 71 0e 66 a3 65 5e 2b 44 73 0f 02 4d b4 16 ab a1 db eb a2 c3 f4 14 49 b3 82 22 44 a9 f5 f0 73 43 5b 3a 75 d2 48 e4 14 a3 b2 f6 1b 2d bc 56 03 dc 7c 19 45 d2 +; NSEC: +ninfo.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 44 04 6e 73 61 70 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 80 +ninfo.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. tmkTQZgqatcb4Xf3mmDhFkwTU1W5g4rm9jwADG9C2BIM2XnsWrbdth6bTyh6tx8nROmg/htYr+9JBu4kCB0CA5BkTkW2M2yaJBsgRR1G04OcSHjmuhoiuCiwSo3EztvaRa211cBokesCR0fWS/Hzw1WMaxnd+Bde5ZjtWW7l1Lg= +nsap.types-signed.wb.sidnlabs.nl. 60 IN NSAP 0x012345 +nsap.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NSAP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. T32X7IOd23hPga4aptqtSSaOInhPUtPrQuZ0K70XhLeRHALQG65cFA9BseiHrm2f0joGK1Op5+041rKUBEFIVyCjwzz3GBHoHSDiROnNulbUpQGnknBb1zx3Qz37VGzI2NJc1jqRdh3pqZU6wBvzZ6HfDEyvSkyh4hAFJx9a5ZY= +nsap.types-signed.wb.sidnlabs.nl. 3600 IN NSEC nsap01.types-signed.wb.sidnlabs.nl. NSAP RRSIG NSEC +nsap.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. tXFIUj2W+5T9R9QgGdbjMN+PrucIkBDA+YFbIq+IGSmh1aDH5fuzxb+a4YT2eckP+mHtqsdux6XYzIbApQGLbCbAA8I1jgkKerLR5dW4qjgCkHyiooscVVeugh7DUDbLgxYWRUSldIxQN8w0fTjfT92GwQdJjp+CePXgveu43d4= +nsap01.types-signed.wb.sidnlabs.nl. 60 IN NSAP 0x47000580005a0000000001e133ffffff00016100 +nsap01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NSAP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. EVzsHVnSnBAv2QHT7htoYvH27Jxt2NYNfAjNdcEfnIxnx4qWlSM91aTpUGqBz86y7y87a5CnH+Lq7m5f7vU3c24LrTGMzsu0csMsvgFMzh6IcJz2Py2a22VvhtFwwC2pjKwjtdwYUXFbQu4FAELf6o5NYaBisHb5Ki+jlGmdqq4= +nsap01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC ptr01.types-signed.wb.sidnlabs.nl. NSAP RRSIG NSEC +nsap01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. mHWHng+TuTMf9gyA5t8dXrG5ryKOiul3e4woEf5PiT4xR7YIlXoV5pdTcCVdIOIKJ6OPZW+e1Bfep7PMFP6WtQjWfdJIq5PazLdjmekpYsTUOnlnc28i9QFluwaezeoL1OxfF1EWyRr/GotqJWqa3zAtlX8fThZZECUtFH7ul+4= +ptr01.types-signed.wb.sidnlabs.nl. 60 IN PTR types-signed.wb.sidnlabs.nl. +ptr01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG PTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. IhLfaiETx5XMz8fbnbb2/RH8X93K2Z/jv48uZf44+maB8vXXLxTU7Sddnc7tzqsCEu4mA/vbh/XYsHZVCRS2oEYK04HRXTb/fdHTy60WBOFNxx0Qx2AkUsQGwAGDOe5XAQ6kssnTvqmv/tMj6+AmUD0jcg1mc+noOIbRc4T0zDk= +ptr01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC px.types-signed.wb.sidnlabs.nl. PTR RRSIG NSEC +ptr01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. dz8beP7pH6wwG+M0VXOrZM0PQ/61rQ8qKUlHYUMHEPy0HIpxPlQhcVnlgdAwrBg2tE/2/vpEZPEXFPW9+wo+IQfL48sAPeh7Y0XFo/20ieaowlGScJae6bj8bd6k7yXBLzXPJviy79BK5KuSQaz/nWotk6dQj+kI3hwL8cWM8mw= +px.types-signed.wb.sidnlabs.nl. 60 IN PX 10 map822.types-signed.wb.sidnlabs.nl. mapx400.types-signed.wb.sidnlabs.nl. +px.types-signed.wb.sidnlabs.nl. 60 IN RRSIG PX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. rZr/yjK6TJojDsIJ81JI48nVYGIBTEL+CrxFc+ViSeld4abjS7JXPbBy+qWnb9LKqQtUTUnes9NOsJV1seKuj3fy5dkYGbEva/m1IZxHBaM9dCvvzCO3SvzI+yO4GzsbVoQYBtx9lYevWGFnSurwq+1fe7w56nergvNMlAIHfaI= +px.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rkey.types-signed.wb.sidnlabs.nl. PX RRSIG NSEC +px.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. l19VV3z5EoSCo1QSStGBqxjEqHljzUyYRut9SIyfzQZ2N1e/ww+D79aQp1QZL0eM3ArmjxKxCH6eK70y9jRd3sZ8yl9PyDQhcqjdgtGdPJy9uOxm9FRcBJHTtbRgm/hsWQjuIbtNuaIXFfMrnsKZ7Smz7NCVLXGtDEaTxu/H+qo= +rkey.types-signed.wb.sidnlabs.nl. 60 IN TYPE57 \# 136 00 00 01 08 03 01 00 01 d7 b5 3c 9c 98 8e 74 76 47 44 66 cc 3b a2 60 a4 61 fe 57 64 bf 4c e7 54 e6 30 7e 3b 07 64 d2 e0 d1 a8 4b 23 e5 2c be 08 41 9a 29 a8 51 21 9a f5 de 82 91 dd dd a1 d6 c7 63 15 29 8c 56 2c 25 f7 5e ab ea a2 99 81 63 ac 6f 1b 50 0d 81 0f 6b 89 31 a8 35 fd 01 bb 0d 35 29 de 31 da 57 44 35 de bf fc db d4 04 97 4b 23 ac b2 01 c4 2e f0 4a 5a ae d3 27 5f 63 3e 55 5f b5 f4 03 c8 b5 bc 39 bd +; RRSIG: +rkey.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 39 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 72 c9 b6 3b 54 b7 e5 9c 17 5d 2b 9c d6 6d 9f 24 2b c6 b5 01 f6 02 ef 4a 07 03 5c ec 49 22 27 f3 6c 67 58 48 60 52 00 d5 ce bc 94 0c e9 c3 33 ba 2d 5e ca 10 ad 9a 92 d3 d0 a4 e7 61 05 85 e0 93 d4 07 20 08 73 11 d3 b9 e5 04 0f 89 0e 6e 1d 34 c4 22 58 30 86 e6 89 3a 82 fb 9a c2 67 0a d4 96 26 21 51 55 80 45 91 8e be 8d bd b7 bd 0d 03 65 ea bc 99 dc 89 e6 5f 36 65 2f 14 3e 0c bd 89 81 +; NSEC: +rkey.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 42 02 72 70 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 40 +rkey.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. w5CH8sOk1Y2//7DcyCTM7af9NvhRJuQOTfgmv9Xu0phZAgdIFcYlT90h+AebA7DARpT85DluiHKin1C8lkS0aTzn3GHUXpX0CvdxlVGxzIeNymWrKHIje+eZWf1Wuy9IrsBlMSAG2/IhNoPWs5mUiZNGF2HXJ9wLyOqFOJyuyD4= +rp.types-signed.wb.sidnlabs.nl. 60 IN RP . txt.types-signed.wb.sidnlabs.nl. +rp.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0mAUUhQsCbCuApI0N900sR93wBOmONzG/mU+9ORtMfrDdgQRFU3x0SWH6/3asX/Rh60vWgXJquOD8HDXyQhtwymf/xD8+jsRcLPkpU4Zn+FX7CxtirpchFrPBb57wgk3oXeA1eDkdXylfx4rfG+DCF4PtLrgqlnZjWo91FaIFYY= +rp.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rp01.types-signed.wb.sidnlabs.nl. RP RRSIG NSEC +rp.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. MWydUezsqOyG61ddYPbIHKq7nHuEyGE/KAfCHhbExHcObv4x1JJLeXhsPeZV9phuvcA/RDFeQkeqNcqbw/tt0kfNNJCMjwFwcDAQOQnbZp7lyCBV/5rgBAENxK4Obx8ANz9X8amTmyy7FmTxYi0Wk59zS/TTzpFC8jnMWxVbY2Y= +rp01.types-signed.wb.sidnlabs.nl. 60 IN RP mbox-dname.types-signed.wb.sidnlabs.nl. txt-dname.types-signed.wb.sidnlabs.nl. +rp01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Df0cttpbhUbrQiU6xPlEd7W8ofQIbfKJPMbq457vQdmBSsiioajhYaMcX3xtm8+9GvugqwMe4iDpKbDsN5Tagt+tquy9yxyhHjTlrS8dg8rPLuxvJMC8GV9pYJEedKmRoLoiqRQFb1290Slg/e9cugVK76b6L36Hcr0zS86arV8= +rp01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rp02.types-signed.wb.sidnlabs.nl. RP RRSIG NSEC +rp01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. O7SzsWJOuqxFLSGcQb0nXKP85ibz8bGgWGZE9k0n419JaHxVFQfcRqczErU0MiSHfqKnA5iEWRAfj0MDmg1vAxJdKWe/ColElgq146Ux4LXQZIdDYGwFFJSloE4BtWIZBNKB5jwk2P01ULbfYLVECC9c+nhkUxbkgszSIMJn/8k= +rp02.types-signed.wb.sidnlabs.nl. 60 IN RP . . +rp02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. zLfI6S2WjQN53zKfNZhzzVRd5UQtOTbPNXukI8XC6XiOHiXdmYzFmy5f3/IrANjxX89a3ocgDCLwqJwe+oGzDjxEMtwxEnAFYxS6kfxADe5r0vX9OzbHSVYLrl0V0K7gttG4fziWzj2ol36HQXwfr9xx0+bfx5GMNYPYWQWhfrc= +rp02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rt.types-signed.wb.sidnlabs.nl. RP RRSIG NSEC +rp02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Z9ZWhfDbLJWMkbgRfpzPARYrWQqk7NDBMNiFZsvoJftbxI6hs9+ex36L1Mr0kSfpnxpZsq9dfwcyQqnKvx6NYpeqr8uLM5NoyQZRcl12w9UQpKyJLK+EVIP4dlvcjypuDqtrld553BPdJHevb6kok2M/RKdZOzTojPi0T88s9bM= +rt.types-signed.wb.sidnlabs.nl. 60 IN RT 10 rthost.types-signed.wb.sidnlabs.nl. +rt.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. m0arLlFFWg3EuJ8MLcFNCFnT9SZTfxze9mI/5eC6KFIs4o1rQqXTvnR1P669fCbVi3dIcxUUlD2Wmhu76iz52LeQrN/Bz/LoQDFXeHXkdOpk/kgnQ5W+90SEP1le7WbqDOnnQsNi+k0s63HD94QmjzV4UXyxfM/+y/Un/IT4Jhw= +rt.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rt01.types-signed.wb.sidnlabs.nl. RT RRSIG NSEC +rt.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 072w+49hnO2m1T2CppTxSv77oqqljSRBfx17Zqv9hl+466twAvPq5F/kUGGNiQW3Bj//J4WkHimaKInaPDMLF0v8Ex/0RojyT6IGLB/lbSYLeXTFaIL+Bh6+K4C9lhDQpOLPjXlAbffrCgOzPkhtQheZieXPByUfdXwHlzO5Pn8= +rt01.types-signed.wb.sidnlabs.nl. 60 IN RT 0 intermediate-host.types-signed.wb.sidnlabs.nl. +rt01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. OdPeXvgrmEcF0NT4cUxOu/IQRsRNx2gb6rrRCl9hvH9JwpjazNGL2IIKB+XvBLfTtiL4JUiAXfYj1p2z1IaTr3yVbRZwwr167v/D1tBnZFmBh8N3pxbSOidEo2CDGXPuJtYjXAT8KJpaQraTjwXyYqXLWkHrey0ITeGuK6CswAk= +rt01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC rt02.types-signed.wb.sidnlabs.nl. RT RRSIG NSEC +rt01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. x92ge9/GRfWjAuSJx6BuhZsuROWwJnzZ8CtRSSJYAfz9TUXMpRxI4WMgC/6bzR4i1Tyu9/o9rv6hxr5Etv/Opd5zW8cX+/9RCwP99VwQo8HgXwbfvLOY6eKjBaabzwt9rxbJSL3anliHCs9fuBh7BtxEG7d+9/i7QhzkhtuZ1Y8= +rt02.types-signed.wb.sidnlabs.nl. 60 IN RT 65535 . +rt02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. zzjiOmoQFT1gGKcMXm77E+Cn2aGPdoYBjkq2MI2DmV2YHAiqRrEgBjxNvvVzRf3CaKj3d2D/hOkF/pdN/SZ1WBqk59JJfBkKE/wjr5NgGkUK2gebMMSJbCMRfPmJZ0vCTErtvQ9p9wNnXWr5rdfncuv4yqTGEmN4XnEv7EWuQRs= +rt02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC spf.types-signed.wb.sidnlabs.nl. RT RRSIG NSEC +rt02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0HXIKijySXvj7ahspOm5Nq+BjvnVyi/TG/N4RsRSMQlOVHdtlgBb3lwKA10lWcHDEE10VujUR+jD4w8Tg63MV2HqL5wioBPmW1reExqe9cTmOrHV0KhvyhmOAAcAdeoFLGdImJQfM53EvJyOR43KYUt8Lgxvbgv6yWwk8aINHcU= +spf.types-signed.wb.sidnlabs.nl. 60 IN SPF "v=spf1 +mx a:colo.example.com/28 -all" +spf.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SPF 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. RWEBwX+MfCQuAZ57zvRjBPEOErW9vTzIqeopOnkxT5T7pLWjrWUAtzptTHxmZ48BTwIThJiTKftnGs6xqhFqw1AoBO+yCpxPSFvgGx1WL6nDmoF/2Udtq8cKaEkhyRQb3lbEo/auRPLLdwPLh2yX0hoG/MDtDOBeyqe2uErDM7g= +spf.types-signed.wb.sidnlabs.nl. 3600 IN NSEC srv.types-signed.wb.sidnlabs.nl. RRSIG NSEC SPF +spf.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. K45ej1Ej54yZckICAMiufO0kM2VWOH7Em+jhICVjiLRZlQGcRTOJ7EGBGK9L6Y5nWwzleo8QpujBD10ejx1coMX+zC2fHN9WJUeV1VDeCXthOl+AOVpdwOGwYJuBsVJItVWA3okHdjL5jfX1a+oZlKyRqSxoIyBQJwlkL/yEc+Y= +srv.types-signed.wb.sidnlabs.nl. 60 IN SRV 65535 65535 65535 old-slow-box.types-signed.wb.sidnlabs.nl. +srv.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SRV 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. CFCGzq2DZSkrscbgtEs4TY1F+RsF8FOKGjC1TDY9zH7JUnxCJyl7OB6k9dt3H4Mj9rki8W4eY//ezo/uOnqHc51WIPBiW7ruPAkJTnSPQ68PtgHO4Yo0ydV+8CqKZdDwSNo4UP4079qUpqsY5Xdla/6yf0AdGYiLMuKbFPyzlAE= +srv.types-signed.wb.sidnlabs.nl. 3600 IN NSEC srv01.types-signed.wb.sidnlabs.nl. SRV RRSIG NSEC +srv.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. iVY5lYVVBExo9mSF6auHJUA2Cle788n4wrk2kuKhivPsxg9S2b6O4BnRdVyAfsve9wKE6ZsixzuevjMm8b08pNRN8P36Nt1mM6vifgX2J7Iz09koXiFW8QChGaK9KrvcoXiZ5J9qrYNQzO3uHZHqFrYhpfQx9PU2EqDgh8XtLiM= +srv01.types-signed.wb.sidnlabs.nl. 60 IN SRV 0 0 0 foo. +srv01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SRV 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. LNTVSV8wXJzhwqf6LQ18ft1znTi7vhc20ltDpSfqrDBZC231CSKdfDS9NxkLhycaU7NzAD2RCbwE/cYD5F3cn1XIW21IpAVkzSBvUXOceaWmSMqcfnvgtMuj7+gafSYrKRp047vTzzPl0btHqdYJN158ZdJp+I8TvectIUEzsp0= +srv01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC srv02.types-signed.wb.sidnlabs.nl. SRV RRSIG NSEC +srv01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. rj9iFGq3JE4Z2sIHLoD54uuvXEz7z2wNJceJT7RdKQpVyn3FiUth+aaB/wZUu6rwQUXWoUEWCJjVrr0y3A+ISxwuKMX8aoMJfMwZe8qpw1vhfGP/kBce6q1tt52gTyGP5aP3qyvFXgDO6y6FFWDxySjGoJVboBxYQ9hDsIJAHsY= +srv02.types-signed.wb.sidnlabs.nl. 60 IN SRV 65535 65535 65535 old-slow-box.types-signed.wb.sidnlabs.nl. +srv02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SRV 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. LqyxdT6Swu9dZOROcRbapALe6Hj2kFSfi04jMMOlgP2uSUlY9vsfh/rmeHqoX/bqiStjJGzFvTcn/MMQK+ybuYRD+XDpJJ8oLErbj1SO5S6KKdAB6WsMyZ+v5zCQFrxh/ugUAL2ba8xGEuE2AGUgoaPvJRQa7hXue4d2bMLDr3g= +srv02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC talink.types-signed.wb.sidnlabs.nl. SRV RRSIG NSEC +srv02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. eN+805hRa+K97AhX6qzIcAaaocIasWR/WZA84wNEAXY0Sei88uN5kt2QhCZvRsXhofiK7wpKkY38EfA/3z9HJNBsOsDmbo5qYlJEax17tAtDDkG37E80CBauCBHGuRARe1k6w66W3w0MI7qgdlYFzguB69zvIbbYUEFSKVtdSFI= +talink.types-signed.wb.sidnlabs.nl. 60 IN TYPE58 \# 32 02 68 30 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 02 68 31 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 +; RRSIG: +talink.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 3a 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 04 60 66 44 13 f0 5e c3 a1 bb d5 70 bf 9b 17 97 5f d4 4c e4 cd c4 ad dc a5 66 02 f1 6a 1e 4d 65 3a b5 5b b0 2f 0c 2b c9 e5 75 fa 28 4a e1 f6 58 4a 46 cc 20 c5 41 76 4b 2a 96 13 38 5b b0 e2 6a 9a ed d2 3b ff 21 99 af 78 59 ff 45 bb ab 1c c6 9a c7 9a 06 99 01 f5 1c 3b fb a0 8f 94 d6 15 6a b3 ac 11 11 e0 ce 2c ad 3e f6 9e 3a 01 4a d1 c1 b3 cc 75 2c 2d 3c eb 64 ad 2e 9a d2 ff df 9f a4 +; NSEC: +talink.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 44 04 74 6c 73 61 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 20 +talink.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. YOHwBGJM07n8PtGr3e6gMwHz+OxWU3nzGlq9nuERIKuLiJH+iQ+5RSqSLqWHoWT0TAZUK4cfVlACqmLjfmTBu8YKjbWPkhh5kS/ktDnVlYxBQDdsamReGntKQ7zZujFKvl1AJcBFG7nyL2+uuDXVaSdcongJeIskJoo9/qAAp34= +tlsa.types-signed.wb.sidnlabs.nl. 60 IN TYPE52 \# 67 01 01 02 92 00 3b a3 49 42 dc 74 15 2e 2f 2c 40 8d 29 ec a5 a5 20 e7 f2 e0 6b b9 44 f4 dc a3 46 ba f6 3c 1b 17 76 15 d4 66 f6 c4 b7 1c 21 6a 50 29 2b d5 8c 9e bd d2 f7 4e 38 fe 51 ff d4 8c 43 32 6c bc +; RRSIG: +tlsa.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 34 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 cd f2 d6 6c 5a 72 33 72 75 09 dc f1 53 3b d3 b8 81 20 1a 38 b5 56 98 c0 61 d3 cb 19 8f 0f d1 9c d1 5d 61 8e 1f c1 a7 1f e2 22 9c f6 71 15 b8 65 85 f5 e2 9b 77 fa 5d 51 e6 34 da d1 2a a8 da 48 18 63 39 56 af ef 28 05 55 5c fe f4 c5 c9 7e 8e 9e c5 c2 37 04 bc 6f 6c 67 07 7d 72 bc 7f 53 d4 2e cf 5e e5 0c 89 62 bb e3 64 c1 d4 d7 b0 b7 7c bc 89 86 6d 1a 05 82 f1 2e 7e 6f 06 ce 06 c9 d2 +; NSEC: +tlsa.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 42 03 74 78 74 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 07 00 00 00 00 00 03 08 +tlsa.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. l/UvixSoKpysCjWjBsqemPNauLqY2CS+FKgjXLvpPMo6V2wOg9NquVHwjrKYy1L9MD5NjWeQdiAzzEoDbLi7sImP5TAwU9Xk3f+9cZ/B1d0oCgjpMVwwTaiIP38+EOnmkQGF9GaHjsV8YOxQNeK44HRINBTlAHm0WPm6NuTFeJ8= +txt.types-signed.wb.sidnlabs.nl. 60 IN TXT "\"Just" "some\"" "\"" "text\"" +txt.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. i9VqoaVA7boMToyJIF/Md9FCVRIQYghp2ojDPGU3hQW5BVRkCW+vyo9mAnL++YmOyf/mkHipMo+JWMigtD/mkErRJOHAz9Al5UOdDFbp3ouspxA5SE/NmcH6wcnwiCRiJ64FpEqJiQHxRgBrZuqLZJ8JZfyuacEgQRqNLvQG4kE= +txt.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt01.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. eJVOacx52Mjuu/NL8+/2Vl1muVh0N/WyFdkUgvxNsDEXaVBCEc+VKMCqqBwY/hsLW93fNb4x5ZWZ5bRQx5hYqyMpWVPBBE1fC7K59f6AhI8i4qni5/uCpwF7X5qbpu367pNAB7GXhW1EEQLPuT6SGML0cjD+iDGDgp3JlkZSmDA= +txt01.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo" +txt01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. uvSFJBtawDQH0yhEyp+9aTcuHPyncUcj/EzdwZfwDb6G4086kc1WGNcuNTKzHratimCj12m6qnH8owLxnIN6MDnLaGpa01RNLAfOyBrlq9hQz2rXk6ZSWVioE3VPAUxzaRZSUwZpVG16dGqYnEZho1ZFH10tbiFHmkwpr78NmAA= +txt01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt02.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. PPMkIjsjEqTQaNdED1qmhWxHR1rGrXZXn38dwzwQVOaV+wfjYhDSUGxO2nfefPO2EGfyzp2wgJrTJ/PpbaeDlGmShPd7IVCymYnFq2QYJtbRPUJmo4Aqj6z7qIOenRHSudrnVtyBE4J+9UZLTjJiupgmqbA8+pp/zrcEqcgN0JE= +txt02.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo" "bar" +txt02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. thiAv/6Y+2zhNwoCP061OFBgAm0OGIqirjeZ1sE0o8MGR+6atBBFoe0AOJDiGYOkNU7/3etXJgjOex+NVNTxcYtVqNEoKKSbhw9iDNogu4dcjAH5aomevmCw9cxI8EcJuVbf+/d5JnrUGWJhGX/nuFj8sZ4CdnlXmsIRsVlpBww= +txt02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt03.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. aRkAdrtlshrkfwlLCPvo0emZVjDBz5PnEC7N5R0LmCx3WWnve3VFeB1E9rwr3u/FxottCZ7Ww56dYo8ZG5jS/gcnj6f4sO4pFv7ZyI9RLwaCe26E/phLscllycey3rEGvfKp6F6rkZTos2W+Asn+5j6aG8ChVgqYwbM8DKoxoEk= +txt03.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo" +txt03.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. WkuggOSq7v26ktw+27typCnQ2PLZ0USkQyoqnbTHTKr4vF1bDZa+CMX4GCansn8WgqL0rxRIXrKSWCMLreuorg8RrTk4gCbQynSAbWfqyd7DpUW7fXc1uQlRhFln3kcUCL98Avjx+v16qkKKGZZp9GwaapYG+yD1zDTO/WZFhRM= +txt03.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt04.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt03.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ndaw/rVPl1RzebFE9fMvaoJT/EVNDbybcMCJlUMMGKaWQN2hAv5MBvF5w5UpdscVv+pLpienQUxbBkiglbj+A/S/J5plovs0I48DFaxw1jam66Ezrj9mCDJLq9FxIRmk7G+A9EgDeWuqSlpo7Nq6ASKEpcYBcHSxQbYZXWYeH8Q= +txt04.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo" "bar" +txt04.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. DIbsDF3lLrnDI16sX0Pd2vXFS6IpQqr7MEqSalHnC0Ohe9ZmSOh9b1LfU2zZSMjGvQ5QGzvbqsAphEYf/HM08MN1X2FjCdXxzMhi5LzUsysnRV+7D1CcJmoNIng94LYFOshuLDnp028TDE7eLmAjpjGpQA3fkK1NsWnGgY1KeGk= +txt04.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt05.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt04.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. tek1XWbn4R4RDIH0wnPfyAUmE0HF5TkUyA/W2d7/tj/PSyHSVOM1gEc1mFo4re9yzAKUWoacReHVsoJJMSfLRCmEFexBQBXmMZg8Uywo8HzP7YlwjR34Wk3PlCAm6FbvnzVEkCSWa+6DG99zsx+GzqRusLa+nsRO3uGJamMxzEQ= +txt05.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo bar" +txt05.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. LD7LbI+S4o+MOhiTS0uo5NWFzlIMuJfp3S8wInTKSKhZLOaRG+S+XvyC1rMCO8WgwVxtGHjkinlKWFMpEIX13u1nvNxVtLnkVX6xI42y80q4Ws8Zl/WovwyKJ7LdnkzrM/udpXQcAk0XMik1zBdkJE6LbKHoIc7eg1TF8l9UWQg= +txt05.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt06.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt05.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BJA1+XqJ52wCdVBMMUOowPRoxJeF/TmU0uMMQILMhV5X7ENdRDU5gUhELJq94HzFTdZsQzqehH0R0nlFeOQ7eL+hu7ey1OlyNkNxW5pQfcAqvEiWXrQu41scyRqCs1PcDM8QxfXQ79F8sa9+JHgkOWkLiGeCgk2JuVtiHPu5AWc= +txt06.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo bar" +txt06.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. FpPj4l3OBTcHrHjbGD/cfZfO/L69Pbua8+sXPRUMtCGrP3JCOGmR+iwJBVPlcqozLzO4jaPgK4Hgn0WjAKDpeNoAsp13ALjQ7kdHVYlz+9rMYOfxdm581mpZ1NRjtxVRulWyNpL0NOnQe/TEHDEgAiZ3uGvHE0JvmVywHga3Fmg= +txt06.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt07.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt06.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. hc0I0kjwttcA79ptubiaJZEhXcHg/B3FOocEMBEeQiaB+vZIXNj2XmfhMHmpprEpzF63QgWmcCsVvQgWe+ZY5SG0C2PZXWhx9K0rQUTCaXcD9ThwvoBdbUvSTWNDbfoCdtTGn2rINYLn8BO0DPb4FTjGYuWhTv/RIv6jkIv2Ses= +txt07.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo bar" +txt07.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Wx8QVHIDnslD7UaSyGYed9vITLPmndgYbBFjVMuP4ktADSozN7ST/aRdQ6H8t61EFfAvKlWLDX79+OpIWQ8RuEOA5rUQNVrTQiYNLCNvGudIJ6LFAa5bTpV9nl6B/tCLKGIET0BwDNpq6s8sgpgIh655E4Mq7UvKv5VotqAQrGQ= +txt07.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt08.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt07.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. o1Cy5dPDOjK8Cdk8F6FKHNiPIj8t19/0HNqsC4v4sxhExyOeuhWjIFepYqqYkPldgw4fXFsOKJE9yUZlF9xtKYIjy9uqJrn+qvsS5oDy6v4NQv1XKgC9MV4+lJEV1xJuKvrh+pxup/heLAW+8/8xlmU3pLwslg3IJBGCrkCOrws= +txt08.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo\010bar" +txt08.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fq9Q1ePTr8Nny1Hx9PAj+EYQswqtSc1lgpOCItd6Nvt8oQt452FYQF6u0VCeZuH+TWHIuYd0Vdx65zlCZ85xCJKPhbhfqzMkDkXBwjY/i+5y+OpLdTbrFa3Vfw92nfjBvTkWT9LHUnjzLo7XoaiIHAeZKZi9gqvqrXOUJs1n7Yw= +txt08.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt09.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt08.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BFqeBpF0NWxjnz5Jb4LqRknBrH03jB9W48Ei5YESINDc4ca7ITfevsq2HGgkKqbN7HfRbge+nwkZp+Bh29SCXK7+lkaiVeoVuQK1Tr5twrm2R554eCqV7EksDjA4oQqTnfXbogLWIh8QzP4rB1ccLUF4TLaabXJyEe/lM8+fIGA= +txt09.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo\010bar" +txt09.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BJMfjXpaxfOFph2Au7RYCpBuz19dvJp4C21Fu03bEN60/p6Sc59Wz1EMdgKlwiZWMj9okhXa0awoCTv/2PGkWIiQvVCK2kJwXR9kYc6FN5xPSI02hOhcJK2Yl0qAgo5nkauIfjL3QTIYHBDASil6v+UhRK/p4TzNF+tLY5GF0J4= +txt09.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt10.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt09.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. guQatBfPYqEIh5w5NQi6oF0RBFluak0XyztRAzsprkFHjKpOj/uINudJ5fWez11qvaD+ygkVrrkIwfWVFbTTv9M6B1RCCMpYrpfsLNhtcmsLlXQDX2Ff4YmGMfeDtfyiSbcnUlbAhpbkcHPt3NITQc3Z44My97IOwzObJSkMzS4= +txt10.types-signed.wb.sidnlabs.nl. 60 IN TXT "foo bar" +txt10.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. B5q/ZfSwr1MtQ9j3yH21jqlee8O9jsH234nbHl1d2P8re1ZIF6OvpSHnypj2hZm3zEd9fnZpV9LAx2lzE9pgMuSfppDpJj2HF17up/yGMQaHRQ0FI2TSaOxdKuKmmTYq+3WBdlSbmHadY6fWH3ZJczeXtVxDd1VnFJnVtCkDuEI= +txt10.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt11.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt10.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. CbuQ55lP5fTw8z7XiMMWFQkrWUNZumRc5MdbCU/qR6PqPt4vlj7RdYJqbCGTyAF64sYzEacJnASMubX6rBsfJkDwFK/0XrKBoX/x4WsgCGF4/xJSURcZHvOW9cJo/4L2v1iFww56r9TgMkkMZ2QxD962nP7zQNOuTwfqyZdROOU= +txt11.types-signed.wb.sidnlabs.nl. 60 IN TXT "\"foo\"" +txt11.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. kgGMZgnzc6lesGru1wWGULgOofEejJFdEqXoR4drNG1xEx7MIANz55fgonpZ5KxyU6pbSb+y3iVjCH8vS47gJl6w/irQmUxEBFqUMStMkTPeeA0cqGE67RHsauD72nEQT99yHLnoG7SveAYa3lk0s9FdHGnjxEEJOfwEywe5npk= +txt11.types-signed.wb.sidnlabs.nl. 3600 IN NSEC txt12.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt11.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BaNYZYbxreo9do4V4sojKRYCScOA+ARpDoHV6lU8jSi2uNezzLfsIsxtzdJ4a0AKQVqPYnq3XkghZmH9GUk0fGdKSQ0Q7ZjHjsx3mGNlNKmGR1mIsLusieVBXAkfP3M6XYJAn9RvE2uEzMh0INouBOPIdUyJMydh5PvCcXPA670= +txt12.types-signed.wb.sidnlabs.nl. 60 IN TXT "\"foo\"" +txt12.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. VBrMLwVo/AFQBbpATVMC5FmI1up/mKY8IDFWmWbyNPiyolMFhEmPnTWd3qn9+WgEE8GBjRuj8S9YerzuHO5xgZeYqxk6Cxqrhxa209Jo59KQESjT0ZepE+E/KssrkBUD7iiknfx4GDe8RxQQSMZk+QfO5RLK3MNFSHRxUfOp+DM= +txt12.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type1.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +txt12.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. sBorSaUpB6wdVK3UL9kRGxzwh+RpDl4KzGrLUlPrUAjAMIi/FuMvRpGxMvkIv0oo2YWu/kt8ydGYkGmI7wEr/sqc8VNKoCnXdmrS6Y3micp71o/MUjbgQSaIqp1EVN4rtHboAoWNpF9WREkwCNlE+U60JXxX3fT9HT8MB4y+is4= +type1.types-signed.wb.sidnlabs.nl. 60 IN A 213.136.31.221 +type1.types-signed.wb.sidnlabs.nl. 60 IN RRSIG A 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HnLYtItbkUrCWYQi0/5M+59DlrFei9s8YQJdZr7zvf/P4y/b9z8738G+Whgmr/+RiQDkQTz53yANcPquSTqPX/KXoZyUCylNVfq5N0/58hzU2glmzkWhl/woXCSX6wDjlz7s06ITXV2r3XNngUJdM9e+Fc4xLes9yWtmm4V7mUA= +type1.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type104.types-signed.wb.sidnlabs.nl. A RRSIG NSEC +type1.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. S+A9rV801zsly7G6nQTdRUTbyIcAA6hpD3tidPJPc1JaWnFcvlS3/gWxhp59AUA9462r5qRPd8mqe1w+qp16Dliqpd28Kc1hmFxDFyBhvj3CxVHdU9TXJwwzhMJunJjYNaFrioHHwwz4NWQ27iZWJCHXnRfq78HqnHG+UY7L02Y= +type104.types-signed.wb.sidnlabs.nl. 60 IN TYPE104 \# 10 00 0a 00 94 01 98 01 52 01 69 +; RRSIG: +type104.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 68 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 d5 66 53 2a f6 41 9b 03 8f d5 c8 65 2b de 32 7c 00 08 88 9d b8 4c 48 0b ca 50 8f 22 a9 a5 1a d2 14 5d e2 1c 0a d1 d4 4f 1a b4 0c 74 43 3e 78 07 e1 b4 d5 fd 23 74 8b 11 f3 99 fb a1 56 cf 50 67 75 95 3a e4 bf cd 76 c8 8f 14 d5 db 62 93 6a 29 1c 08 2a ba 77 a0 b3 ab 77 bf 30 eb 85 a3 99 67 d9 53 72 c2 11 7d f5 1e 9f ff cf 8f 5c 2b 22 81 65 6e b7 7a 04 d7 bc 88 30 d3 cb a8 ab 66 67 c3 +; NSEC: +type104.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 53 07 74 79 70 65 31 30 35 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 80 +type104.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. syWqtiuLSBEf52SoqxXblLLG5IB67kPDYm4xiuuM8WhNZOTZf0lRsJSaJt8nrv9oTbHi+LePa8wHHt4EHeXiEQO/gF4gTcIRMT5UmCHTngkYzWZ5iWGcRwXiW5HnlipDLMCbqv3R05xKNoRugBfPtYGbgDbe05U+d71OUNMS0AY= +type105.types-signed.wb.sidnlabs.nl. 60 IN TYPE105 \# 6 00 0a c0 00 02 01 +; RRSIG: +type105.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 69 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 18 53 9c 6e 19 dd da 7e 8a 3f 64 c2 09 f0 27 a5 69 94 90 ac 0a 4a 94 e8 e9 1a fa 63 81 64 92 48 e3 5a dc 21 14 d8 6f 1c a0 4b 87 30 52 15 de 26 49 32 72 48 25 37 59 94 00 68 00 5a 7c ae d1 eb a6 21 7e 7a 49 3b c1 84 98 ae 90 99 5a 9e 85 50 e9 3c 08 f9 06 d2 0f 99 40 8c a8 d1 8b 1a a2 06 27 de 51 39 b1 6a 82 66 41 6b 9f e9 e1 d2 f1 0b a9 7a f0 b2 18 18 56 a8 0d 33 8a ed 8a 32 3d 38 +; NSEC: +type105.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 53 07 74 79 70 65 31 30 36 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 40 +type105.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. FhaSb/03UXeId1hF7a0xOstlhuNGDWwKPGedQfVEm41fDyzb0/O2ahhQF8vOEHBrCoIwbbE6rZzwXXhamHudSirW1r0JzsFr+hzP4/rzMYFGaxnx5J1g7QSfRkzgTk/yqypMUNCwfMHcyLTDrKQqH0+MPqgsQo1wXB7xzmaC7eo= +type106.types-signed.wb.sidnlabs.nl. 60 IN TYPE106 \# 10 00 0a 2a 00 0d 78 00 04 05 03 +; RRSIG: +type106.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 6a 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 ae f7 6e b3 b8 86 e8 c7 28 75 8a fb 25 8a 15 f1 22 a3 d6 23 9c bb 85 9a 2b a3 3d 19 e8 39 a5 b7 8d bc a9 95 3e 52 ba 34 2b 00 e8 38 7d fa ee 76 34 25 af 6e 28 53 89 9e 90 57 81 93 ba d0 80 a1 7c d6 eb f6 cf ab 03 be 1e 4b 67 7b cd b2 6b 5f b7 bd 15 ae 8f b7 a3 8b be 26 a0 bc 03 f1 cf 1c 1a 6f 04 4c ed c7 d8 c1 2f d6 2e 31 46 7c 3d 3e 60 76 31 a8 87 6c f2 89 e7 a4 b6 7e 8b a8 bb 93 +; NSEC: +type106.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 53 07 74 79 70 65 31 30 37 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 20 +type106.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. hQdrfnE0mB+zBqnnridrtRm/hhIYAAvCtdXeq/un3loZhUkGTnOgwTl3aWFP03j+3aSihFfQ1sa5Cj4J1sGLPFT5p1+eoGYzWx3MPOt9vWj3qqDhwXt36dAQg8gPunxMpTUmbkS9VcYPsD+7sdRnKjbgF2UuUjTiYmFuYx1eHSE= +type107.types-signed.wb.sidnlabs.nl. 60 IN TYPE107 \# 27 00 0a 0b 6c 36 34 2d 73 75 62 6e 65 74 31 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 +; RRSIG: +type107.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 6b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 6a 9b cd 96 15 96 9b c5 45 13 73 a1 a8 06 86 ba f4 99 4d 7f 73 e9 d0 4f 97 7e 56 83 db df 93 5f 6c 69 e3 c1 9e 44 7b 27 17 b7 0e 9c f4 f0 01 6f ad 4f dd 71 b9 bd c0 d7 0e 77 a8 e5 2a e7 48 57 39 83 fc 9d 3a 57 90 48 f2 5a d9 bc 41 f5 ed d0 ea e8 86 13 b6 6f 28 64 28 76 e1 8c 2b d4 44 ae af cd 4c 3e 42 df a8 c1 32 8b 02 c0 7a b8 99 cb bf 60 aa 67 6e ae 2c 77 99 11 06 6b b3 fe 77 f9 +; NSEC: +type107.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 52 06 74 79 70 65 31 31 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 0e 00 00 00 00 00 03 00 00 00 00 00 00 00 10 +type107.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Wmyz4qv6QnUgca3D1z2D3xwsnjyXgHc1eX+srLi4bP7wraGU5eBDO5miUB3ankeMauH9sYD8Y5Vu2UXq0H2BolzdkM+OVIatsAEErQoYFTUHhv30WvlxgyndCRcTLuIPIstYeprBP8QNWCvZ7r6K7qZ5Zlg0HCTQLohrRGLuRdE= +type11.types-signed.wb.sidnlabs.nl. 60 IN WKS 10.0.0.1 tcp 0 1 2 21 23 24 26 33 34 +type11.types-signed.wb.sidnlabs.nl. 60 IN RRSIG WKS 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. bNn/EeYJu7Vr1g0K69DiC3kK250ZJrXaLgdwtxclCzGl0cj6lieBJcPRJOMDnt3wTQZftdEB27P6e5tDN9OOVHdzcZrVMZz9hlpqkweyfSUS8DJXKcdc8i1Z2WgtUR2FZbpxVxIKXj41k07y+ifvMzFChUtbnuR/yskGJTWgwTc= +type11.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type12.types-signed.wb.sidnlabs.nl. WKS RRSIG NSEC +type11.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. uM88+sv5qkrcMjbHKBj0GTgKeDODbb1wsrsBYrIE523uIWf6uunseDDzuhaas2aY8kB0Et1GARV2ee+Lmswkbdhb10qhjRDlOba9g8u3ng7D/XDCIVfrKag3lptGpqJay0ATB7pQsz3nXHJJAxUoWVAwkHxtacW7EoAKLEno5XA= +type12.types-signed.wb.sidnlabs.nl. 60 IN PTR types-signed.wb.sidnlabs.nl. +type12.types-signed.wb.sidnlabs.nl. 60 IN RRSIG PTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. x512lckf+y/0s5hqvjhPTblRMN0Z4E6hjKwAJL5Pytvgu6Q15DYKxiXlUPmNiTq99xXcRPMB35kF6yo0DohVmkImfI51N2pbCyyWCX4Kg6maDHK92dKThWRKdqv1l4JE1Wdk3J8l2yaBMzBeXDwNihpGW240yESfkY7Yg5keSXc= +type12.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type13.types-signed.wb.sidnlabs.nl. PTR RRSIG NSEC +type12.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0xoOvyZ4vFyZXZo/zwZENvU2XJd4yLQ3cVgrn/M4DOTA/wxbLI7xnAXpTxUii7w5diVmfkDzS7rGURDoLgmOGM/QiuQr1/majMILkUCNhy0WFElFvp0JHxHZbZO5wzudXemr5/N4jzcoeq4cLNDraq6rWx3uQw5ViwD+A6KetlY= +type13.types-signed.wb.sidnlabs.nl. 60 IN HINFO "Generic PC clone" "MyOS" +type13.types-signed.wb.sidnlabs.nl. 60 IN RRSIG HINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. BNGqwyT2klcwR8U1/TCJuoMnKoSe04O36mgJB5nYqlzDSvhFI6fXhwAJJnfv3pQIbuKmZUvIE1DXlYKK25rtii1Kh7iRQ+n0WGfwOmIcVJFzijD33HxajRp+WPxinzlaZ9zJKwM+dWAVaLe9nhgFCZvw4dCngFTuYX1jn76rchI= +type13.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type14.types-signed.wb.sidnlabs.nl. HINFO RRSIG NSEC +type13.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. wecVOxVaP2xCtBYDRDDSuOmM/mGlloko4w9PqpLKxbwfm1jAe8ypmRFTCf6Nn0mXHkEpDksHYod7HPNY3G+Kt63MumELy5nQbkzOQG4v+/OvGMICOVgnO9nuQ926a4WwNpAguBOwcOVhbmdYmsnh4tKt6N2pT3vt8hV7O33zCfY= +type14.types-signed.wb.sidnlabs.nl. 60 IN MINFO boxmaster.foo.bar. mailbox.there. +type14.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MINFO 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. hFwPVnIWC6+qKWSIfsK/pw1SXwQdGZ6E50Xa7MtUGxMSuqzJRoW4gk/RCVaPDMHDA8UWJe5vuM2/QFj9T4NZq2vEY4Cge5gs7yfzaxl0Pfytts6OuVABlNNwHZyXwIWxzuIu3jONLIo3Rc13b6Yvb0B0HziX6L2KWEF/d+fhHcI= +type14.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type15.types-signed.wb.sidnlabs.nl. MINFO RRSIG NSEC +type14.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. MX/rO3D90ad3K9e4eJu2kWj7f086sVmwVp8KGp2ODtBp3nzf2OaZz4BNBM7BJOoBXJtz5d8gfWY5q9EUXZkhB4b0UAwpMKzVrXonEe9mPPjr37yn/yX0as+H/OEYX7tpVhef2Ga/eco9XgTU1QkhJo/0EhXXQLDSToeImSV1v6E= +type15.types-signed.wb.sidnlabs.nl. 60 IN MX 10 maildoesntwork.types-signed.wb.sidnlabs.nl. +type15.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. alCyc8uO3iqxURffoFxYCKeH9+nIbEt5u+ONQpRU5x8jch7wOe1F706vJi7rvWFlatp7VMzVdWbL+cfF54WxBYzxke02UZKJbVSNbZ9fjz+yu7KlAZjNCRG7+G2oOOs4CUtf9Xs7EBaN3/BTkSezzoU0fUQOpCEuGhPz4E5T0SI= +type15.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type16.types-signed.wb.sidnlabs.nl. MX RRSIG NSEC +type15.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. VdqDe4+ggzVpK4w6QoMNt6yqkylqO/4HXgr6FrhYwdnPsBmGbvWuuFigIopaLAabesYBgmNxOinjxK3GRyHZOCHVD+69gQJ7CpKJ0VI7bRXb/EoIF+hb3ojnwYFT4lK/qQDGwAMNmXww4D4W2LvszolgOLtDuvgx/O4+HfL5p10= +type16.types-signed.wb.sidnlabs.nl. 60 IN TXT "\"Just" "some\"" "\"" "text\"" +type16.types-signed.wb.sidnlabs.nl. 60 IN RRSIG TXT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. e2NElZfsIoa8NxaMCcBQXWMzooDXo8TbX9e23bVIuaEOe5YytzLgoxeKoJ5BxXzd+cSVtoM+gkC29f2GhT8tWrd/CVZOVbsxA/qoHt96qx+LuHKuiNpBErJLVGm4ZJ4FaPAcSHZ1kXek7poDJbTiezew6omr+ZET9H8sa7sVMyc= +type16.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type17.types-signed.wb.sidnlabs.nl. TXT RRSIG NSEC +type16.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Iq9UgeppXP5xa4NYfqEHa/oyMZVyHcWhoW5lxGjDYhytOVylDyUN24E2CxfIQZxc3fVPU848oMNMl6hDYV01wbvBpPHsKq10zpHyEJUrGdwDFLIHI+hSWwFXmHnh83b3yzcq40hL6ZW8dAkelUTgpBkSWzLEf7IhHS6u9+/HK1k= +type17.types-signed.wb.sidnlabs.nl. 60 IN RP . txt.types-signed.wb.sidnlabs.nl. +type17.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. NqlDVM5HHDHsOsN4O6QYfW3MYUoNx4VE0zxvtBlwt+ydhnxlbiv7G8pAciUVrtK6fsxma6tnHnq0RXUBuU0DU0go9j9Abjd9btjQmGNtRn3xzJKp0x5ZAUdmCYFl1Dmz25siGiQHgzDX3tbmbScRg73p/kxt7/B7/JrzTeIDD+0= +type17.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type18.types-signed.wb.sidnlabs.nl. RP RRSIG NSEC +type17.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. VZNsecxi0bBubeRPVsrtTJXR8bOIFC7TZfUpUmiuaJIzgi7miXPxcNqQAluXDgsSz/URQlgsYss50wemo1DEJiFSLLz9/dnMVeu9rj8J1183F1fxuPQQT1S1ZLkrl+0S+4cBacROq0wbJv7w2DMmMOB94Dh3PHKOWOBzzDlv7/s= +type18.types-signed.wb.sidnlabs.nl. 60 IN AFSDB 12345 afsnode.types-signed.wb.sidnlabs.nl. +type18.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AFSDB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. YQz6/e0GojsmeDD07Im2bQe24QL+VbPjgh5SCrbnLVFLHAYPxNtaJ/ErHDT0Di2ZpXq451R2gq8cVi0Oa2on59gzgNdp5tEJ+9fzmOjda7atu0V7kG1DnuMoqbiJ3hRD20kF8qp8Bqsm27QsMAeiKiqBje9k9AEjIt8JkxvjFWw= +type18.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type19.types-signed.wb.sidnlabs.nl. AFSDB RRSIG NSEC +type18.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. naKTTAV7517qYBYZLPiDdAIaRXVjOmmuh796SV3LO+xtI8F2lj63a+31kH4sJ/MXpm5gObeJpv6Mzjqg68njy4BSBytUmfn3WSOhyKQ1SOws6g3F2sJ7jr1HinXt2WBaLyub6scAuOTDQpXLPXvN1JzuNGUEgS8fl6yVfnST+Ak= +type19.types-signed.wb.sidnlabs.nl. 60 IN X25 "3033033033" +type19.types-signed.wb.sidnlabs.nl. 60 IN RRSIG X25 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. yxQ18T2jmpGM3u4bqcW9FeukAkNN8KE2Og3cbPb8DgRqXlDOM0yNygmaGHKpMt3PHlX/br8zNixrZfahHXPDB+IK3+PwWgMkeJdtkUbPAbHinCiwnOuOhTxunSmVwuGAKN+YJ14yfcmYRxYNe8gZteP/PqclTIrDM6r2niA5mcU= +type19.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type20.types-signed.wb.sidnlabs.nl. X25 RRSIG NSEC +type19.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. MNMK6p/DURHn0TT7DbSOw+ba7vIBmwN0IBGt4QxZLCy5jOHuhpIfcYtXeD+s+yeRdgpkqp4QLaI/eqXwlaMTxS8yc/QYmoV9lKGArnI1u2/954YxmcKfZkrRtaBDWh1mfBFO/hmNzXNdUyKpYnAhltd2bvKf/fs5TEpaarSM3ZE= +type20.types-signed.wb.sidnlabs.nl. 60 IN ISDN "isdn-address" "subaddress" +type20.types-signed.wb.sidnlabs.nl. 60 IN RRSIG ISDN 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Pof2TR2skrnegyKNzd4f/gqJx0a7OQbbF2ihvcvGym8pAQ04S/0u1+TNnkcMS7/lO7XcYsSEtWTMYB94fcqQ7LaiKU9xKOk2iZxtMGj4N46eBTC2EBs4lkfO1FC1Zj3LXMLSwoxeyJkOWJXzIgqlDHlpoiO3FvS/DVs/rmmu95I= +type20.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type21.types-signed.wb.sidnlabs.nl. ISDN RRSIG NSEC +type20.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. KVwZsEsv7GT5dA0MjaSMrgCnr2FQJIb+wDhPH4LGJlqa2gwUYvdCl2Q/EFZCtxV3Q6mTCGsAX46Gk2ydV9cG4rpS2vD8alxC/xm0W2C6zj+eECP4CXOHKGAM1C90ZN0p9fHzzPCKD8cHWLKPi47CXOJ/hkQNQwZEzUQiG59mJrA= +type21.types-signed.wb.sidnlabs.nl. 60 IN RT 10 rthost.types-signed.wb.sidnlabs.nl. +type21.types-signed.wb.sidnlabs.nl. 60 IN RRSIG RT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Um5c+Zahp1yifMbo42CMTs6vlhVAEiV/4vjd41SVJSg9wdafLFxZPFxNROc2qmqGPR1DU+RNcf7u47AG1jld6PKBNPVSEr/RDrb5GCToMdPPPMgwp5eZ9tU9WtuIf6L+kiEdzSf7I917GySLYPnvCyHIqfFIl3nwnSSkvuLDuGU= +type21.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type22.types-signed.wb.sidnlabs.nl. RT RRSIG NSEC +type21.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fZlgo/6e2JBkB7LwXDAMgFzkyDoudOhjriNOShROayENOyK7lJSE1z3I0KTHlZVSaRzzQVKTOamVqXTDHzfKiFfxLjhNH99Pz1XRMLhPA6b01Xy7MRJrDCLi6KoCsiE1rOaKSc5YfWQRQ4pBABeuyTRrLnyzzWw8niByFiDniyM= +type22.types-signed.wb.sidnlabs.nl. 60 IN NSAP 0x47000580005a0000000001e133ffffff00016100 +type22.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NSAP 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. XvZudSKX39GYPjVDYy7DR+mDuGyz/HWwQ2w8uwndB+RiObS8ktH6dDeYTTvKcwAKEct/0ttEfJgGBCeiejIG1PKuq5LWE2k06D0whNkVe38eGBj6dqmzoiAFVKwDhBBvPKDzWAxcWnPauc7S9DNk7Vjx8lWAUQ7r90QzY1EJG4Y= +type22.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type26.types-signed.wb.sidnlabs.nl. NSAP RRSIG NSEC +type22.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Pvy2G9XMdRiiEclL+ZMPZlzY5Su3ba1VHNnYSpgVmJlT8GD5GSBSCWUy214i4Cpj8vgjOrQj2OpdU4RF4IWS0N+I9qBFLYQNORTupPIXgafhPN/GIutMXPA3vlfwLWuFjmYGyfej6RYpCr0kmJgzfFln2g7zZJhDaacd/5yF444= +type26.types-signed.wb.sidnlabs.nl. 60 IN PX 10 map822.types-signed.wb.sidnlabs.nl. mapx400.types-signed.wb.sidnlabs.nl. +type26.types-signed.wb.sidnlabs.nl. 60 IN RRSIG PX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. B7x+bFjM5eFr9M+ib0d810gERF+EiDvhBVQjW6a5SQChSVfEO/j7MD7XETF0vGnLYHC6UBixVnpwfvPp1c4FYOm91tiGL6sHBxfG+fYPiwQ//cIoaABh28FppfSHFlV41+sXjcoKw2dcIzcCGSYJl4mhvXLfb++sqB59lznHmr8= +type26.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type27.types-signed.wb.sidnlabs.nl. PX RRSIG NSEC +type26.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. s38cK3O7HWpe5KU+Lp6PiT8KTiD9Yrx8HFbSpA1ZrHzSUVdVX8Z3u53Kp2w/B3ELOB27Ye7yqIlqZ/GvQBB9/FvXS2JZOs/75AfeoBXhLXIpRyW9x7ghj9xemRpWdsybrFm4otdD86OkeSJhZ9VJc8fa4yJn0q1t6HPMir3PoH4= +type27.types-signed.wb.sidnlabs.nl. 60 IN TYPE27 \# 18 05 32 33 2e 36 37 05 32 33 2e 36 37 05 32 33 2e 36 37 +; RRSIG: +type27.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 1b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 13 bf 8c a0 c4 6c ab e2 34 d3 a0 d5 5a 9d 4d 2a 30 44 9e 21 a2 5e 88 9d ba e3 49 9a 2c 56 7b 8f 65 2c 2c b2 f6 7a 83 76 7d 6b 59 63 20 5f 7f bf 83 a7 93 18 e7 02 c5 58 e3 06 88 50 7e 06 20 29 fc f4 eb d2 ec 5d ee 7d fe b6 c3 c2 f3 26 13 19 20 40 1a 05 44 4a aa 32 6c c9 d1 18 13 9c 43 a4 a0 dc 83 4e ce 3e cf 88 3d ac 78 b0 30 31 f1 54 32 a5 ac d4 33 15 87 f4 3b 22 17 6c ba 0a 6e 14 +; NSEC: +type27.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 44 06 74 79 70 65 32 38 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 06 00 00 00 10 00 03 +type27.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. X6h589HJ0wrKtIeFOr0yaULPb6woH2Ka5bZdr1CVgk4cOu5tNo/80KuRJUDgegjA8ALJFnHJENJbB+robgW+MMjHdrdxYj36kmI6VNrUIV5f7MaqVAnEPFwanmH1I8IsMrYCtoWyHSrRwNsb2gQ3+sliqM9uTXs4rsxLcJJVkkw= +type28.types-signed.wb.sidnlabs.nl. 60 IN AAAA 2001:7b8:c05::80:4 +type28.types-signed.wb.sidnlabs.nl. 60 IN RRSIG AAAA 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. qi/CKoXG8391j+KLMEFTKPIsI5KGyXdm7iTlbzZaVFP+8HDAZrpjn9E+a9ZfrodExC2sD7szNEkaOkbhTAEGLVmUEW2OajQcZLehWsWUiLexvhpDgKfWfdh5AJUKtQd+fF9kk+NYfqgc2p0QVT7tGBhmSxM6CnvuUKYH/EaZA1o= +type28.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type29.types-signed.wb.sidnlabs.nl. AAAA RRSIG NSEC +type28.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. RLaxe7Vcggc9xU0pFjIIG2SGxadDEY0IfcAS6WIDP/VJKkExBrRS6x8Gh6F0+pXiUfiNbPF3/MxLa5nKc2RpeLUm3hLK/6FLgHj881TACaheathNx8W71PC6vUO0h/KCy57E0VfEdzw3c4i+hAwMDZMzCODjCqc3e7etSI0iv6k= +type29.types-signed.wb.sidnlabs.nl. 60 IN LOC 60 09 0.000 N 24 39 0.000 E 10m 20m 2000m 20m +type29.types-signed.wb.sidnlabs.nl. 60 IN RRSIG LOC 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. dzeX7l5t/spRtZ4pd4wqKYhS0MQ+z0iB9mnD1omRZ9y8qWWyze6CfIo/1WuLFaGLZn/e6fJndvH/oyWHwHB3B/2PJ/A11PlBFOrYAqNWVOfi8wD3+h2eybdpPP32ZVvLPHDW+ywZzE1Pp9wq2XUxygMPjxjxOTJoog51gUYbh/4= +type29.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type3.types-signed.wb.sidnlabs.nl. LOC RRSIG NSEC +type29.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. vbV8xEkjhjT1eYZ8vRmpPuX1pUcEUpZD2euFX45xN3Vieo5krZFn0OTa0WmtVyYpbBwWJwBDEL0fbf1XHBnBeCwrFDRK7wdAfKyFBJR4u/dV5i/ARO1/gXToyplTS3JIdpXRmb+J7UZzHVCvF+sVorqJ8ZNe2Br/b0qD5vEi/lE= +type3.types-signed.wb.sidnlabs.nl. 60 IN MD maildestination.types-signed.wb.sidnlabs.nl. +type3.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MD 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. dMBfaQ9FCoBRcGbPixCycIAcRsbhaY3Mdzd7u8LeQZcyVgjZLwoet7lHwXZmMwbxmf2kXYANptuBcATuK1z4UcjfdD8f9woALqVzZlfqqbuW/3UAr6m2/3LdEfoQ7zgp8NMWd6ndz3eeds0Ez5UJpLtyUyxVLhAy+1ukhxzZB1Q= +type3.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type33.types-signed.wb.sidnlabs.nl. MD RRSIG NSEC +type3.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. vVpRL+15MWzDMlidMWoehtIPf78zkXCSlkdE58Md/fWrhIv0P90uKnecN9Vc8gt+G/0zYZq0J2lq43eRXxK9F3icnNPnKq5cH79xwUjUYA44RJyp+JoA6n2aSRUtmVDaoqgEpeVKyHaaduo0Ewx2zdnKRQizHa5hGNLQwx6I1Lo= +type33.types-signed.wb.sidnlabs.nl. 60 IN SRV 65535 65535 65535 old-slow-box.types-signed.wb.sidnlabs.nl. +type33.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SRV 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. VL8gJoEx/2MR+T7aS1L65WRCgGWenOF69A6TwP2nacr7DueyuiQOKY+3xM9fu+B42NDbszHQwicl3G+NwES0izpp54y6HR8vw/fgEDW00QJjCMMox5u/B5GKfiCg7/CRqQIJCeSj75dimmmTg/brKZtvjIpczbSLd8iJwXbyTFM= +type33.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type35.types-signed.wb.sidnlabs.nl. SRV RRSIG NSEC +type33.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. M6OFYbCiqZSBBagSGx7tEaeWot+ILnQwNKUSH8morMAsZ9yckpOyq7oY2X7T02JDSS/0ZHyQR0UukH7BD72Z4dgMIzJ8nm0hoau/sSAjRpWRZ5Vokf9YEzXEKvRdwqc6q+LjT8KuWVeKMK9w+uBP6wgYS5Ao+HqV0hgtbNnjYRo= +type35.types-signed.wb.sidnlabs.nl. 60 IN NAPTR 100 100 "s" "http+l@r" "" naptr.replacement.types-signed.wb.sidnlabs.nl. +type35.types-signed.wb.sidnlabs.nl. 60 IN RRSIG NAPTR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. nBnu2lhatErGRmjTeV/igqR5Rlf5uuoHExMMdKAWJONBBihQHm+JamS+hhZDYKULsehqz2RhXHAJk3n5PgNECDDfw8huDOHPzNWYQU0Y3Y3/orBj5zUWMPkrs3FR8xKPoi0QNUeISTtPBtnZJjUdWUxgL4kG0sXQZCHSwZvRyQ4= +type35.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type36.types-signed.wb.sidnlabs.nl. NAPTR RRSIG NSEC +type35.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ppd/JXq9CShfmZsDvKW2/Ys5UkrF44UYZyWKo0jxGlYJDRMOHWmJPKYj/UXoMbek4f/fp6iz9ovpeqo63bN9KKPNc4GGdxqoFI6uxlWJ9m2L6VcRXOnhKeKLTRFpAMn7mBdHBVgYZYkX8u0VZnyxL2zfDqaFiC4VaF0yycdnezQ= +type36.types-signed.wb.sidnlabs.nl. 60 IN KX 10 kx.types-signed.wb.sidnlabs.nl. +type36.types-signed.wb.sidnlabs.nl. 60 IN RRSIG KX 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. L5jL15c2aSkZK2BWyi2767MbGKp0RQja/EoKIEcwC9Sk3oEvIXSfh7wFsTnumjy4wtrTRN84MpOZgPaHH7niRyTzwXvsF52w4E7CVGVi3XoOrvdqxnpLJB52Doha3REfUXvU2feFxnh0RTNA99QM8G7TtG5fTht5kMx3/GAs2rc= +type36.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type37.types-signed.wb.sidnlabs.nl. KX RRSIG NSEC +type36.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. d6YAVe/r2WfbPRXOl6up1VWp0XUDRH+Trti6ioBX0y+csWPw4jDlIFcGrOoECoYPpf9gUybcSQtkbN9o1afWPExDkOMJJ7d/JVxoAXECIyqhgNv5W0bnPJCnBKSw2H+xYfrIHAqR5LNzcX3b2P3lINDy5JmXr+TDyVfokHCkCx8= +type37.types-signed.wb.sidnlabs.nl. 60 IN CERT 65534 65535 254 MxFcby9k/yvedMfQgKzhH5er0Mu/vILz45IkskceFGgiWCn/GxHhai6VAuHAoNUz4YoU1tVfSCSqQYn6//11U6Nld80jEeC8aTrO+KKmCaY= +type37.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CERT 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. SlCOl2LPMWklV5mmMC4Z9LzEy9GIhZPm+dVXhp7LFc0CmxR94zAp6NrNQmo/5LAMCcqWaXZtBhsyDgQhcZFg919JVkmK7yiJ9bzqIg8RQUNOtMh4pI9TtYgg7FRXM3MkPu+yTy7HYv/rFhuAM3X9IgITodeeVeSArSYx9hiOAhA= +type37.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type39.types-signed.wb.sidnlabs.nl. CERT RRSIG NSEC +type37.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. o/U1lTNjKe/yQjunuVgr7PAH9su7HATW80F+/H2H+R+Apa6ktdP4mZFVTdUaxSnD3KzV6H2Y4l8SZJ2YoqmukADyngrfwcqz0Xy0HTl/Eo9BrnZGqUZ4zyDBsZK3uvkM3sLODGRQNYhBSmEUn0MUOARXecJH6BufBP3csvUIHZ4= +type39.types-signed.wb.sidnlabs.nl. 60 IN DNAME dname-target. +type39.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ZmECqkLy7Qw4nGo8F4DcKps5SeAjFa7p/nCxpF8zGZH9LQCwzxOmwlNCld6omDnYscx3OgFHG+GJ+3rMRjW+ZyAc9U1Y92bDpEjDz7UKdWmUpTUT7rJ0Cur08GV4dWPhCPjOHqNnicmZnG5lXZCzSssFE9tjuLsvzZrIR8rUxG8= +type39.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type4.types-signed.wb.sidnlabs.nl. DNAME RRSIG NSEC +type39.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. KbbOeByeCe2YefjKI5U1SPUYiwOCk1twYKb6h5mm+NL0xEDiYiT+qdSp8sR0ste1VWh6grikJwZ8E/aaFZlEsbfKREMdT0Nx2aWJOEcE41P7y6z5vijvIl8MsB80LzcCwC0PyOg/2EYHZOTtzigiTaAz9gp63ITDrCXrycoobwU= +type4.types-signed.wb.sidnlabs.nl. 60 IN MF mailforwarder.types-signed.wb.sidnlabs.nl. +type4.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MF 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. eV+t41KAgyw/SNfAFRdDxX0rRahvBbVJIGT6q9gZfX25CEK1R29pDwX7rG17bVK6MdsKVFOZZewKGvjoHUQ+mxHO52F1/I7RTLyVye0z+oqiwTHK6TIdR4nrtEGJewwNc/P3xsRl8Y/hXpbCYXBBSeDsrIxmBlHWbKIkxQctHtQ= +type4.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type49.types-signed.wb.sidnlabs.nl. MF RRSIG NSEC +type4.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ArjC3guyoU/kicVZN6aQHPIX60JmGFW3TlwapId7wpWRy7etmciUKPR3+9qx0/xbZ8wuPto8KsE+083P2Fnd2gwk56devOIKlfxJh5LD/vDhOCdKv9fZ38skLxzXtRX2Yzr1h8PhO0MzldjB2HNLornyph+PXGb3oAUhajg3b7c= +type49.types-signed.wb.sidnlabs.nl. 60 IN DHCID AAIBY2/AuCccgoJbsaxcQc9TUapptP69lOjxfNuVAA2kjEA= +type49.types-signed.wb.sidnlabs.nl. 60 IN RRSIG DHCID 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. TyUCNkjU1cH1SL7CdZklnUrng5jhWYOQkXV+lRbr/g2lJ3hbInyZ0jGp4hqye9jN7drTD5XaBtzesxzkyEE6KoACEgWpvCYi0yb67URORLbSnfk9V65UWjTQTWh9UQkr8Dt1PVKQ18w0ukiXCHsP0sbAKyk4mSyFNpsFCLK46Ls= +type49.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type5.types-signed.wb.sidnlabs.nl. RRSIG NSEC DHCID +type49.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. rU4xWncTlzMdgTLJVz3Wb05ZpWgMRSuAyuiJNm+n0+tDn4S5q5oRwk2W8MZzMyuKx9iLJhE0xU5H4DxeIBzyetWKVjaHaXt6+hb0IttrBeW/PHVE/hPbS6r5Ozon5ZTU6DzgxYSnMhWuilWLHrUhs1zaR6Bf6RDJwyGc9WK76eU= +type5.types-signed.wb.sidnlabs.nl. 60 IN CNAME www.types-signed.wb.sidnlabs.nl. +type5.types-signed.wb.sidnlabs.nl. 60 IN RRSIG CNAME 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0ntnbJbTyh00XP95sXfExiYrWqN4V668japhRVXKuzMyViuYQv5XqXvOc37BNe/A1w7vBBeIbdLtjNAnFaER5WPzFdlK4nrTLLgEakzZ5Owt3KudHkf1aMpRWHBMXuk7JfekCkWw/MMh5Wprb4Im3u2A80xHVU69RyhSn2t68l4= +type5.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type52.types-signed.wb.sidnlabs.nl. CNAME RRSIG NSEC +type5.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. lWtXPElNPR2D7+zmAPI0ktLKRM+OipgRWrTjQPFY16pyfSa3nXwu4OT43fWl2fBD5hfN3UZzZIzeN1Mwtr85aDiiA7Trqba4idNp7robO41j1jUWO1cKqaOcp/LBv8qKnjiCbk522BeeZ7nJe1ABzzL86mOdvL4QEPJvjLjVWTU= +type52.types-signed.wb.sidnlabs.nl. 60 IN TYPE52 \# 67 01 01 02 92 00 3b a3 49 42 dc 74 15 2e 2f 2c 40 8d 29 ec a5 a5 20 e7 f2 e0 6b b9 44 f4 dc a3 46 ba f6 3c 1b 17 76 15 d4 66 f6 c4 b7 1c 21 6a 50 29 2b d5 8c 9e bd d2 f7 4e 38 fe 51 ff d4 8c 43 32 6c bc +; RRSIG: +type52.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 34 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 7c 3a 75 6d 26 5a 46 89 8d c4 95 a9 4d 7e 93 3f 19 72 dd 81 24 33 54 4b b1 39 90 08 c5 9e b6 b9 16 93 14 84 33 8f d3 ea 05 21 9f 5a a8 36 52 65 e7 ac fa 2b 99 5c 19 17 c4 b8 53 81 cf 5d 6d 1c ee ac e9 73 54 a1 02 17 72 a5 81 13 c6 b9 c5 38 d2 ed 51 1f 9c 58 1d f0 a0 2e 75 42 f1 21 3e 16 85 27 f9 e7 22 01 96 36 28 a9 c4 be 5b d1 90 8c 49 3b 7e ce 94 91 8b 74 0e e0 d2 ff 4a 41 98 ba +; NSEC: +type52.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 45 06 74 79 70 65 35 36 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 07 00 00 00 00 00 03 08 +type52.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ax+MxUC07rKTnOwSrlHJpF59yAHhhT9o0zg6a9kYrLZVaHb7svDMN9qqFa4LeF9rE3uD/LtBqYJzLJPhVqcI9aua+vH/uBEbM5fg8FHql/jTE9DtkGPbzlV6TGtNv9MTOjObXNkhuwDR7xREOm65nZ1VTgaW5bYx1X9yeZiWWgA= +type56.types-signed.wb.sidnlabs.nl. 60 IN TYPE56 \# 27 1a 54 68 69 73 20 7a 6f 6e 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e +; RRSIG: +type56.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 38 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 b1 2e 7f ab a9 1d 6b 5d e3 55 1b 72 01 51 5c 94 c6 1d cf b9 36 dc 67 94 66 ed 2b bf ab 1a 29 5b 19 91 f4 fd eb 59 38 88 ee 8a c2 f8 f9 e2 d2 7c cf c5 08 0e 72 d4 c0 ff 8e 40 c0 20 e3 41 d0 d1 44 4e fc dc 7c b1 a6 f6 ea c0 64 2e be f6 6a 26 16 13 f2 ee 4f d0 a9 45 ac 8c f2 22 d6 1c 63 20 12 2c 48 98 99 a2 a2 2a 47 a1 e2 cd db c3 5c b8 cd 6c be 6b cb 50 e7 03 52 57 87 1d ca 71 3e 6b +; NSEC: +type56.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 46 06 74 79 70 65 35 37 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 80 +type56.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. oEgJi1LXQnhjuvcrWU+CYQ4DgVdasmV7JXVPQyzdV4ORRNoDMDMpBA2ei6vF6NpGm5dcLrSKFLFpfqJBO4+quuCbmM2RAXEFZ8cZpZLNkA11rMxJfwXG4IEDywh1TslthcYL1ukoy1sG6wEQPgadcetfEP5Fk7sMH4P32bwJY0s= +type57.types-signed.wb.sidnlabs.nl. 60 IN TYPE57 \# 136 00 00 01 08 03 01 00 01 d7 b5 3c 9c 98 8e 74 76 47 44 66 cc 3b a2 60 a4 61 fe 57 64 bf 4c e7 54 e6 30 7e 3b 07 64 d2 e0 d1 a8 4b 23 e5 2c be 08 41 9a 29 a8 51 21 9a f5 de 82 91 dd dd a1 d6 c7 63 15 29 8c 56 2c 25 f7 5e ab ea a2 99 81 63 ac 6f 1b 50 0d 81 0f 6b 89 31 a8 35 fd 01 bb 0d 35 29 de 31 da 57 44 35 de bf fc db d4 04 97 4b 23 ac b2 01 c4 2e f0 4a 5a ae d3 27 5f 63 3e 55 5f b5 f4 03 c8 b5 bc 39 bd +; RRSIG: +type57.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 39 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 b8 86 c4 44 a3 b0 56 0a 1f cb 3c d1 24 56 7d 86 b6 df 79 4f d3 1e 0f 16 de c9 f8 f0 c6 d7 53 91 31 9e bd 94 e2 ff 46 38 cf 5c 49 be 69 f2 4b 50 f0 1c 77 de e2 98 3f e5 3f 29 48 88 bf 0a 3a c4 bf a8 d2 f6 bc 38 e0 a4 02 1d b7 6f ef c7 b5 fb 17 bc 65 ce 8c b5 09 ac 14 c3 a5 98 e5 f8 32 7b 27 8e 07 33 d1 b0 9d 1e 03 86 0b 06 2e c9 40 bf c6 b8 dc 08 b2 e9 28 51 44 f9 91 e7 69 22 2d 4f +; NSEC: +type57.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 46 06 74 79 70 65 35 38 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 40 +type57.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. EK1Nf9XdaS55J7SIWhfi7Fs0yO6FSiza+84oSDeDr+eoHT6gzrhOI/7QgvmB1fbze9Ju9u/C9Mgh0G5RFqqSep0JGl/XtEEThIuPMi9uXfkuz+Pxl2kOVG9kWbo4n6vI08Enfgey+t9oHN4QfAc2UIH1mgHrYSZfJk0eLcVQNIc= +type58.types-signed.wb.sidnlabs.nl. 60 IN TYPE58 \# 32 02 68 30 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 02 68 31 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 +; RRSIG: +type58.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 3a 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 c9 c4 1f b3 9c 61 74 77 b0 86 4a 42 8b 90 b6 7d 37 dd 40 11 da 80 bb a5 dd 17 e9 d9 55 3c 40 8b 9a db 2b c5 20 c3 8e 31 17 ae a7 52 36 20 84 fe 89 ba 88 3d fb 59 ea 6f fa 9b eb 63 56 bb 99 3d 26 8a a0 97 01 3d 48 7b a0 41 ab 63 6d cc b2 35 11 d9 bc 45 12 26 df df 7e ed 64 2c ef d1 ef 26 bc 69 eb ee 09 7a f5 89 df c9 c9 63 bf 69 62 81 6c 7c 0c df 43 12 a3 8d 88 4e 66 98 fb 6a 90 fd +; NSEC: +type58.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 46 06 74 79 70 65 35 39 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 20 +type58.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. DtEdLwbHmM4IEJVYDlPbQNMAM6z2ksWMtbYX5InIuJ28sRKaAo7hyNdCMayBI4UgPAYmKd/nESh0qX6i3SADERNnPVreufJkP1GdP3au59qV+C6IDG8CkM5/N1nFRRid4T+gzpoqWxolKu3VflghEUeTkPem5e10KVBFPt1qang= +type59.types-signed.wb.sidnlabs.nl. 60 IN TYPE59 \# 36 fc b2 08 02 86 63 2f 83 49 4b 1d 70 37 e7 29 49 fd 6c d8 68 9c 5d aa f4 df 1e 5d 7e 6e f3 ba 28 ec e1 e3 c8 +; RRSIG: +type59.types-signed.wb.sidnlabs.nl. 60 IN TYPE46 \# 175 00 3b 08 05 00 00 00 3c 52 ec 39 00 52 49 63 dc f3 5a 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 73 99 7b f3 3e 9e ec bc aa a6 d0 7c 08 02 4a d8 35 8c c2 69 74 16 7b cd 43 28 02 fb 68 e6 cd 1c 36 15 39 d0 98 fc c5 7d 43 b8 d1 04 d2 7a ad 32 07 0b eb fc 60 f0 02 e5 d9 98 b6 15 e7 65 80 ee fb 74 f2 e8 b0 e1 55 c0 d5 78 2c 9e 15 d8 9d a0 36 b7 70 c2 ac ba d2 1e e3 45 3d 00 70 c3 86 bd 2a 15 4e c7 f6 48 1c f6 9b 22 6e 2e 12 87 3d e0 f7 53 b1 6f 7b 52 20 cd dd 13 a9 3c 92 40 f8 e2 +; NSEC: +type59.types-signed.wb.sidnlabs.nl. 3600 IN TYPE47 \# 45 05 74 79 70 65 37 0c 74 79 70 65 73 2d 73 69 67 6e 65 64 02 77 62 08 73 69 64 6e 6c 61 62 73 02 6e 6c 00 00 08 00 00 00 00 00 03 00 10 +type59.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. B2a5QOr/ETGnhpsHVOxzTw3RXUhRCf54WL8q1iR7kTU2/Vv/cu1HaeopC/BH7RQ7D7Z1H+ULW/pBaPPv2MeowijBevwxxAT8bWtWl8p4U/mwB6kQm6uJGt0ydek8t2KQl85LBOsqyvfvnDK9ckg1vPjLNPY6RL7Ex0c0e2lMFTc= +type7.types-signed.wb.sidnlabs.nl. 60 IN MB mailbox.types-signed.wb.sidnlabs.nl. +type7.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MB 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. bW4lc0urxx/J19/33qgQJD1Ex9+nIWOMFIwQNJ7nbzmLAwROa7qXFxH6MpJwU9Lspj3pXSOLaam9HRG1iAguE4MtF7C8x9762EQYRTBfW/nPWQGibMTxq7nJ3Ap6+ONomla7JeItoILQWxezHL+LzdDMQa9kGZcPZgacJdpeiSA= +type7.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type8.types-signed.wb.sidnlabs.nl. MB RRSIG NSEC +type7.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. ZkTkPjgl2AlrOgIgMVHJ7evwrGXWchFnSnCQqy6feX7bHVeQBScUoK/wORgmU2YaLD7MHmlvcgFqxngYtkeH03T4PpJfL9jsht9lZGuDaw8AhOKVp1XnF5Z69RoQ1el7JYWifzn8Q7C3CgKH+L7oEPFcDct7g3ArAJQaIsZuShE= +type8.types-signed.wb.sidnlabs.nl. 60 IN MG mailgroupmember.types-signed.wb.sidnlabs.nl. +type8.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MG 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. iczcF6KmRy86DDbYTXrKs6xV1LAHwmeojk8L++Rkn9IwkDlTES6/xakvg3d+WZAPp4r4Rt3jV9YW7MgXTjuu3zeWKHIlf0kxrYYkXGh1KEzfg2/ABMtXamYTzBLwUToQxmTQJA/l9Mk/UoT34RQZbh4q7sslelk4dcHfcFZloRw= +type8.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type9.types-signed.wb.sidnlabs.nl. MG RRSIG NSEC +type8.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. HKuc8BPEYgyG0t82ynr1XmvoGpNVPdqNahD+pjOlIVIv40vBnufGZ8lm65R1JlKrfPEh72myT2DNmOFi9BekvHJD5+BP8cFLHQdmonyqoBr0PberXzYt5fvB/gVEk2u2rtj/ZR9+x6ccWdudhIXqjl3ELDcjwHpow1cwbo6Nj6A= +type9.types-signed.wb.sidnlabs.nl. 60 IN MR mailrename.types-signed.wb.sidnlabs.nl. +type9.types-signed.wb.sidnlabs.nl. 60 IN RRSIG MR 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fpzO5uIZkfjwUdJ/IFBiYGVBStXUYsjZkOcBanSSbOJNSuFWm/5vddo95RdQIOOg3++cdYhH9B15vbqetC4kdvn0qkHxE/U0vHCgmJUWwlq1Af38Ts9/WsJ+OtQeUS6i5gtIQ8sMtSedd4T3d/OsZNgWdWjgL+5JdXQyV02jsjU= +type9.types-signed.wb.sidnlabs.nl. 3600 IN NSEC type99.types-signed.wb.sidnlabs.nl. MR RRSIG NSEC +type9.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. rK80Qfay6gazrF6/2T+DjyfK3ec84MAr8W1Kyst0fNbW2eF9XBXQREYJyYNDVZ1mhE9lEdC977ety4bzC8LF41ttm0Dyj4lkcW3y68aBn5zFi388vm8oSX8KHVXQMLmGyED1+bqSyJz4dsjYcyjW0nvXN2/L87aPg0AndiueqUk= +type99.types-signed.wb.sidnlabs.nl. 60 IN SPF "v=spf1 +mx a:colo.example.com/28 -all" +type99.types-signed.wb.sidnlabs.nl. 60 IN RRSIG SPF 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. e+gPKZzvKt4QLeeZUnezhyUrEkw8KwYoZOQnp0OErRYrWQfSG0+pIWPqmQmjctv2KuruWoH8RDLYm94yMDzA+wuPxCCjmPsto63NXCzXHGuJUIQhq1DYbWhXQwa313Ms2Oquj84APx+fiB3hAulPJltF68b3XFspMUGIFRMABWY= +type99.types-signed.wb.sidnlabs.nl. 3600 IN NSEC wks.types-signed.wb.sidnlabs.nl. RRSIG NSEC SPF +type99.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. C/Fzy7gdFS2UMjugX5zQx/INNv2lnBIqQqe3LCTUyiRQuzB3B0QSM71OR/uo+jIi9SSXjgbc0spxniS2x3a2jTRUJPu+MrP9NCpMwCMzgc8lRXaYIKFzKTBU0gej5BC6p7HQb6ng6Fs0sfypD1LxstExN9pR1Li4aPh5Hr9U1Qc= +wks.types-signed.wb.sidnlabs.nl. 60 IN WKS 10.0.0.1 tcp 0 1 2 21 23 24 26 33 34 +wks.types-signed.wb.sidnlabs.nl. 60 IN RRSIG WKS 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. n3AdmQ1HEwQOmmhSfXZwY2jqwJea25psB/CJQOf+srO2vJd64mgEpA0IekSx8ajKktilHqOVM7E/HqqNZDVyMKCOVrVhjSZuI7e2uNj3mCWmtUMsmEsEV3BLLkw0Nvz4MXOl+gdPECSDqLdcc56pthoiRS35wvG2lHXUxjUiGQY= +wks.types-signed.wb.sidnlabs.nl. 3600 IN NSEC wks01.types-signed.wb.sidnlabs.nl. WKS RRSIG NSEC +wks.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. Rka/Lc6o1z/mCLl7/Rmkugv9oGhqyQcht/sMI4IB02XpTVYyRppTntWESusKXQ2cRqN06Iqxn9Rhk0DVYKgRJqNjewEWZG7tA/u36SuyXCeStHmgbkoW962ZWM1QDc8j+BYHS1pTKkx6x+5Ehb0y+SyMZyy6229WJfSZLU54CL4= +wks01.types-signed.wb.sidnlabs.nl. 60 IN WKS 10.0.0.1 tcp 0 1 2 21 23 24 26 33 34 +wks01.types-signed.wb.sidnlabs.nl. 60 IN RRSIG WKS 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. l7HYfzjcIhIQDZ2zIJl0gD5jsYdzh/1qQRQLFXGbjQlXerEaw/YBJPXzRPFm1caU8xz2rbkqMXVyoIZnDt6pH+y/MfFNlQhjswWG0q3WGUfpUlyfJCpSE0Fddfoh7362m42mLTgbfornJguxbgdYLQ/NfLinrFeBfNEk4ZFCU20= +wks01.types-signed.wb.sidnlabs.nl. 3600 IN NSEC wks02.types-signed.wb.sidnlabs.nl. WKS RRSIG NSEC +wks01.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. 0BABoZLuZnFIltEVzP5AImbPmT9xHUVrcbG6sNCX8wI+P2gv4tRNsKfneQaIyKePMn9103C1l+7OF7SfVRbUOMYZ52pBti0yBl0ECCrf4jXWBZZ3e0vcXNA0Bpn9fLxeYyHLawhHllPCy29v1ns4zpWjvIphxG3X9fnEBVZzRI4= +wks02.types-signed.wb.sidnlabs.nl. 60 IN WKS 10.0.0.1 udp 0 1 2 domain +wks02.types-signed.wb.sidnlabs.nl. 60 IN RRSIG WKS 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. P+p1gcQbO4I/sBQUZktrz4Q1osWIFIFGlK8o+SzIXMjxmdNy36vjwW6Sfy97CycbLRFIQ2grPv/cPaXtoMb+usHCoDtl5sSvLTJFmg9hpQ+xm12GvunZvAYAGx9fZic+QvLahSg+cjqX1M0oR9B68gcx+duMdLzawlUcIqX8gmA= +wks02.types-signed.wb.sidnlabs.nl. 3600 IN NSEC www.types-signed.wb.sidnlabs.nl. WKS RRSIG NSEC +wks02.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. E0NeTdwBvfouI0vv1fom9Ivvio9nvAZMCosKLnSL8tV6nV4HIOBx8GmeXsctyLSm/AdABtKe5Ll2emblpjLHuAItO2VCINXfGebodDzf5xY2UbAThpfwGx5pXBr9d+DXWxHJej5Ub9eOWztgxB1k2G1u+AxpQEBY8ywiDop7z4k= +www.types-signed.wb.sidnlabs.nl. 60 IN A 213.136.31.221 +www.types-signed.wb.sidnlabs.nl. 60 IN RRSIG A 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. sP6X9RSL6zDJ762WZLgs2wG3fDkmPacs0eT5qgjHZBBxTZkvop5fAPtaKq14tP+pfN1+pa1mjrWPpOwuvcpC25Sa8x64ISfm+pg8RRDmElM2NgOu7a4jxtOOzjAcQS5Fpf4zPHbo2jETocTcv7XOGinqe33SxAlzit2yfkZNkJk= +www.types-signed.wb.sidnlabs.nl. 3600 IN NSEC x25.types-signed.wb.sidnlabs.nl. A RRSIG NSEC +www.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. j2lNsX7mxldTSmwnTQoT6aKzY2QpzRqjR9aRBSpjVU/FnT8zc1/nz9y3+h6trvb4BmbsSftnEMJKQwtciNGO5KNcDayZJNQ74fiEYwd9CEvwEYQYnURDUTHOsZ/s27t2fb5y4+bI+9hUTMidWsz3sYH/3h43qyP8rd6dv3v/EcI= +x25.types-signed.wb.sidnlabs.nl. 60 IN X25 "3033033033" +x25.types-signed.wb.sidnlabs.nl. 60 IN RRSIG X25 8 5 60 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. fYqiHPDKREmQ28cv2kmFS6kP4nZYN7+hZsjkoQ983VSGbP8zmPAfPnfVsuwZz+LHnUfLQcCZrLzK2K4rCBHsuKbSLkZwYQa9VLd5U3PY9Krj9Sj+2ACtxG2KX285RLnR6ZVyyAHK92udqUfJUU5LoROuuz37TeRMY/DvSpz/uik= +x25.types-signed.wb.sidnlabs.nl. 3600 IN NSEC types-signed.wb.sidnlabs.nl. X25 RRSIG NSEC +x25.types-signed.wb.sidnlabs.nl. 3600 IN RRSIG NSEC 8 5 3600 20140201000000 20130930114324 62298 types-signed.wb.sidnlabs.nl. AqLeezQyBdjXXEe5vNtSzOrOPQLKvl3jAF6V3hIFtZdsbAExrjLXXrxeoR37tPxtOqF95/HtXYFaDmuVQtlEdiDozIHNCtBS3KtVrIVld00VLd3xQLNak7X9WhMYNIl5cJ5gdLFVc/tVKcL2craDyXMsjXDA0o2NxnpVZatkP7c= diff --git a/static/netbsd/man3/test_packets.3 b/static/netbsd/man3/test_packets.3 new file mode 100644 index 00000000..bcdb5446 --- /dev/null +++ b/static/netbsd/man3/test_packets.3 @@ -0,0 +1,496 @@ +1576 +1ca000000001000000000000036e73310762617365776562026e6c0000010001 +1ca080000001000000020002036e73310762617365776562026e6c0000010001c01000020001000151800002c00cc01000020001000151800006036e7332c010c00c00010001000151800004d535d035c03a00010001000151800004d535d034 + +1577 +221c0000000100000000000009652d6c756e61746963026e6c0000010001 +221c8000000100000002000009652d6c756e61746963026e6c0000010001c00c0002000100015180000e036e73330767617574656e67c016c00c00020001000151800006036e7334c02e + +1578 +b9ab000000010000000000000962626469676974616c026e6c0000010001 +b9ab800000010000000200000962626469676974616c026e6c0000010001c00c0002000100015180001105646e732d33056c61646f7403636f6d00c00c0002000100015180000805646e732d34c030 + +1579 +b2c21baf5011fae2e9c00000000000000000 +b2c29ba40000000000000000 + +1580 +e1be0000000100000000000008686f75736561647303696467026e6c0000010001 +e1be8000000100000003000308686f75736561647303696467026e6c0000010001c01500020001000151800006036e7331c015c01500020001000151800006036e7332c015c01500020001000151800006036e7333c015c02d0001000100015180000451af4646c03f0001000100015180000451af4647c05100010001000151800004d5a0fde6 + +1581 +000000007002faf00a970000020405b401010402 +000080010000000000000000 + +1582 +02ac00000001000000000000036e73310563736e6574026e6c0000010001 +02ac80000001000000020002036e73310563736e6574026e6c0000010001c01000020001000151800002c00cc01000020001000151800006036e7332c010c00c00010001000151800004c2451012c03800010001000151800004c2451212 + +1583 +153e00000001000000000000095f6b65726265726f73045f746370026463065f6d736463730644494b534954024e4c0000210001 +153e84030001000000010000095f6b65726265726f73045f746370026463065f6d736463730644494b534954024e4c0000210001c02c00060001000038400036026e730f646f6d61696e2d7265676973747279c02c0a686f73746d6173746572c0430bf1e540000070800000384000278d0000003840 + +1584 +b2c21bb05010fae2e9bf0000000000000000 +b2c29bb40000000000000000 + +1585 +b2c2d04f5010faf0b4380000000000000000 + + +1586 +b2c2d04f5018faf0747c0000008f552d000000010001000000000f313133333837313336363136322d320000f900010f313133333837313336363136322d320000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 + + +1587 +bf28000000010000000000000962696a656e6b6f7266026e6c0000010001 +bf28800000010000000300030962696a656e6b6f7266026e6c0000010001c00c00020001000151800010036e7331096d61726b6772616166c016c00c00020001000151800006036e7332c02ec00c00020001000151800006036e7333c02ec02a00010001000151800004c3f13ceec04600010001000151800004c372eb43c058000100010001518000043e320e8f + +1588 +f95900000001000000000000037777770766636f72696f6e026e6c0000010001 +f95984030001000000010000037777770766636f72696f6e026e6c0000010001c01800060001000038400036026e730f646f6d61696e2d7265676973747279c0180a686f73746d6173746572c02f0bf1e540000070800000384000278d0000003840 + +1589 +b2c2d05d5011fae2b3a60000000000000000 + + +1590 +000000007002faf0d9770000020405b401010402 +000080010000000000000000 + +1591 +b2c2d05e5010fae2b3a50000000000000000 + + +1592 +a18b00000001000000000000036e733107626265796f6e64026e6c0000010001 +a18b80000001000000020002036e733107626265796f6e64026e6c0000010001c01000020001000151800002c00cc01000020001000151800006036e7332c010c00c000100010001518000043eb1900bc03a000100010001518000043eb19002 + +1593 +b2c379ae5010faf0d9b90000000000000000 +b2c3f9a40000000000000000 + +1594 +410400000001000000000000036e733107626265796f6e64026e6c0000260001 +410480000001000000020002036e733107626265796f6e64026e6c0000260001c01000020001000151800002c00cc01000020001000151800006036e7332c010c00c000100010001518000043eb1900bc03a000100010001518000043eb19002 + +1595 +852300000001000000000000037777770f64616d696174652d636f6c6c656765026e6c0000010001 +852380000001000000020002037777770f64616d696174652d636f6c6c656765026e6c0000010001c0100002000100015180000d036e7331066e6c74726565c020c01000020001000151800006036e7332c038c03400010001000151800004d4b20403c04d00010001000151800004d5881e45 + +1596 +208200000001000000000000036e733207626265796f6e64026e6c0000010001 +208280000001000000020002036e733207626265796f6e64026e6c0000010001c01000020001000151800006036e7331c010c01000020001000151800002c00cc02c000100010001518000043eb1900bc00c000100010001518000043eb19002 + +1597 +883a00000001000000000000036e733207626265796f6e64026e6c0000260001 +883a80000001000000020002036e733207626265796f6e64026e6c0000260001c01000020001000151800006036e7331c010c01000020001000151800002c00cc02c000100010001518000043eb1900bc00c000100010001518000043eb19002 + +1598 +b2c379ae5018faf0d58e0000008f199c000000010001000000000f313133333837313336363136322d320000f900010f313133333837313336363136322d320000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 +b2c3f9a40000000000000000 + +1599 +2a640000000100000000000009652d6c756e61746963026e6c0000010001 +2a648000000100000002000009652d6c756e61746963026e6c0000010001c00c0002000100015180000e036e73330767617574656e67c016c00c00020001000151800006036e7334c02e + +1600 +99a400000001000000000000037777770e7765736c6579736e65696a646572026e6c0000010001 +99a480000001000000020000037777770e7765736c6579736e65696a646572026e6c0000010001c01000020001000151800014046e733031096772616669782d697303636f6d00c01000020001000151800007046e733033c038 + +1601 +7ab500000001000000000000096d61696c686f7374320b66726565686f7374696e67026e6c0000010001 +7ab580000001000000020000096d61696c686f7374320b66726565686f7374696e67026e6c0000010001c0160002000100015180001105646e732d33056c61646f7403636f6d00c0160002000100015180000805646e732d34c03c + +1602 +c3e800000001000000000000037777770f64616d696174652d636f6c6c656765026e6c0000010001 +c3e880000001000000020002037777770f64616d696174652d636f6c6c656765026e6c0000010001c0100002000100015180000d036e7331066e6c74726565c020c01000020001000151800006036e7332c038c03400010001000151800004d4b20403c04d00010001000151800004d5881e45 + +1603 +95af00100001000000000001046d61696c03777873026e6c00000100010000290800000080000000 +95af80000001000000030004046d61696c03777873026e6c0000010001c01100020001000151800007046e733038c011c01100020001000151800007046e733039c011c01100020001000151800006036e7334c011c02900010001000151800004c3790128c03c00010001000151800004c3790143c04f00010001000151800004d5ef9a650000291000000000000000 + +1604 +b2c379bc5011fae2d9270000000000000000 +b2c3f9b40000000000000000 + +1605 +61be00000001000000000000037777771a676f6c666261616e68657472696a6b76616e6e696a6d6567656e026e6c0000010001 +61be80000001000000020000037777771a676f6c666261616e68657472696a6b76616e6e696a6d6567656e026e6c0000010001c0100002000100015180000b026e73026e6c036e657400c0100002000100015180001206617574683630026e73026e6c027575c045 + +1606 +f99c00000001000000000000095f6b65726265726f73045f746370026463065f6d736463730b746563686e6f70616e656c026e6c0000060001 +f99c84030001000000010000095f6b65726265726f73045f746370026463065f6d736463730b746563686e6f70616e656c026e6c0000060001c03100060001000038400036026e730f646f6d61696e2d7265676973747279c0310a686f73746d6173746572c0480bf1e540000070800000384000278d0000003840 + +1607 +d8bd00000001000000000000037777770c636170636974796368657679026e6c0000010001 +d8bd84030001000000010000037777770c636170636974796368657679026e6c0000010001c01d00060001000038400036026e730f646f6d61696e2d7265676973747279c01d0a686f73746d6173746572c0340bf1e540000070800000384000278d0000003840 + +1608 +f05f00000001000000000000087261626f62616e6b026e6c0000010001 +f05f80000001000000020001087261626f62616e6b026e6c0000010001c00c00020001000151800005026e73c00cc00c0002000100015180000b026e73026e6c036e657400c0290001000100015180000491484fde + +1609 +b2c379bd5010fae2d9260000000000000000 +b2c3f9b40000000000000000 + +1610 +175928000001000000010000026e6c0000060001095f6b65726265726f73045f746370026463065f6d736463730b746563686e6f70616e656c026e6c000021000100000258001c000000640058056e746673310b746563686e6f70616e656c026e6c00 +1759a8040000000000000000 + +1611 +4d9a0000000100000000000005646e732d31056c61646f74026e6c0000010001 +4d9a8000000100000002000005646e732d31056c61646f74026e6c0000010001c0120002000100015180001105646e732d33056c61646f7403636f6d00c0120002000100015180000805646e732d34c032 + +1612 +adb60000000100000000000005646e732d32056c61646f74026e6c0000010001 +adb68000000100000002000005646e732d32056c61646f74026e6c0000010001c0120002000100015180001105646e732d33056c61646f7403636f6d00c0120002000100015180000805646e732d34c032 + +1613 +b22d00000001000000000000037777771777696a6b766572656e6967696e672d68616e65766f6574026e6c0000010001 +b22d84030001000000010000037777771777696a6b766572656e6967696e672d68616e65766f6574026e6c0000010001c02800060001000038400036026e730f646f6d61696e2d7265676973747279c0280a686f73746d6173746572c03f0bf1e540000070800000384000278d0000003840 + +1614 +ba9a00000001000000000000037777771076616b616e746965776f6e696e67656e0f76616b616e7469652d61616e626f64026e6c0000010001 +ba9a80000001000000020000037777771076616b616e746965776f6e696e67656e0f76616b616e7469652d61616e626f64026e6c0000010001c02100020001000151800011036e733005736572766502636f02756b00c02100020001000151800010036e7330057365727665036e6574c052 + +1615 +000000007002faf0ec1e0000020405b401010402 +000080010000000000000000 + +1616 +8f9e00000001000000000000097463676e777331313608686e65746f6e7477026e6c0000010001 +8f9e84030001000000010000097463676e777331313608686e65746f6e7477026e6c0000010001c01f00060001000038400036026e730f646f6d61696e2d7265676973747279c01f0a686f73746d6173746572c0360bf1e540000070800000384000278d0000003840 + +1617 +230b0000000100000000000004646e73310471776562026e6c0000260001 +230b8000000100000002000204646e73310471776562026e6c0000260001c01100020001000151800002c00cc0110002000100015180000704646e7332c011c00c00010001000151800004d994ac0cc03800010001000151800004d5c42f6c + +1618 +f8200000000100000000000004646e73320471776562026e6c0000260001 +f8208000000100000002000204646e73320471776562026e6c0000260001c0110002000100015180000704646e7331c011c01100020001000151800002c00cc02a00010001000151800004d994ac0cc00c00010001000151800004d5c42f6c + +1619 +825800000001000000000000046d61696c0761627374726163026e6c0000010001 +825880000001000000020002046d61696c0761627374726163026e6c0000010001c01100020001000151800013036e73310c706f77657273657276657233c019c01100020001000151800006036e7332c031c02d000100010001518000045104741ec04c000100010001518000045104741f + +1620 +f8f000000001000000000000037777770d6165726f736f6c64657369676e026e6c0000010001 +f8f080000001000000020002037777770d6165726f736f6c64657369676e026e6c0000010001c01000020001000151800006036e7331c010c01000020001000151800006036e7332c010c0320001000100015180000451044432c0440001000100015180000451044433 + +1621 +cd46000000010000000000000c626c65696a656e6265726768026e6c0000ff0001 +cd46800000010000000200020c626c65696a656e6265726768026e6c0000ff0001c00c00020001000151800010036e7331096e657467726f756e64c019c00c00020001000151800006036e7332c031c02d000100010001518000045054e415c0490001000100015180000451046014 + +1622 +b2c4383f5010faf02dcf0000000000000000 +b2c4b8340000000000000000 + +1623 +5e1200000001000000000000037777770864616e69656c6c61026e6c0000010001 +5e1280000001000000020002037777770864616e69656c6c61026e6c0000010001c01000020001000151800012026e730c6d65676170726f7669646572c019c01000020001000151800006036e7332c030c02d0001000100015180000450474002c04b0001000100015180000450474102 + +1624 +b2c4383f5018faf0d3750000008f6ec9000000010001000000000f313133333837313336363136322d330000f900010f313133333837313336363136322d330000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 +b2c4b8340000000000000000 + +1625 +e81f000000010000000000000d7469636b6574736576656e7473026e6c00000f0001 +e81f800000010000000200020d7469636b6574736576656e7473026e6c00000f0001c00c0002000100015180000c026e7306787334616c6cc01ac00c00020001000151800006036e7332c031c02e00010001000151800004c26d0642c04600010001000151800004c26d0963 + +1626 +6bf800100001000000000001034e53320743495354524f4e024e4c00000100010000290800000080000000 +6bf880000001000000020003034e53320743495354524f4e024e4c0000010001c01000020001000151800005026e73c010c01000020001000151800002c00cc02c000100010001518000043ed81f37c00c000100010001518000043ed81f380000291000000000000000 + +1627 +b2c4384d5011fae22d3d0000000000000000 +b2c4b8440000000000000000 + +1628 +000000007002faf042610000020405b401010402 +000080010000000000000000 + +1629 +39f400000001000000000000036e73320a6461632d706c616e6574026e6c0000010001 +39f480000001000000030003036e73320a6461632d706c616e6574026e6c0000010001c0100002000100015180000c036e7331056264726567c01bc01000020001000151800006036e7332c033c01000020001000151800006036e7333c033c02f00010001000151800004d44ff4dac04700010001000151800004d44ff642c05900010001000151800004c3f5c70a + +1630 +b2c4384e5010fae22d3c0000000000000000 +b2c4b8440000000000000000 + +1631 +6adb00000001000000000000037777770773657870657274026e6c0000010001 +6adb80000001000000030003037777770773657870657274026e6c0000010001c0100002000100015180000e04646e733106626c6978656dc018c0100002000100015180000704646e7332c031c0100002000100015180000704646e7333c031c02c00010001000151800004d44fe803c04600010001000151800004c3f5c782c05900010001000151800004d44ff303 + +1632 +b2c4e8a95010faf0d3a60000000000000000 + + +1633 +3a440000000100000000000006504152495445024e4c00000f0001 +3a448000000100000002000206504152495445024e4c00000f0001c00c0002000100015180000c036e7331056f72696f6ec013c00c00020001000151800006036e7332c02bc02700010001000151800004c2862282c03f00010001000151800004c2862b02 + +1634 +e9e400000001000000000000037777770b617564696f636f76657273026e6c0000010001 +e9e480000001000000020000037777770b617564696f636f76657273026e6c0000010001c0100002000100015180001105646e732d33056c61646f7403636f6d00c0100002000100015180000805646e732d34c036 + +1635 +b2c4e8a95018faf0b5df0000008f3338000000010001000000000f313133333837313336363136322d320000f900010f313133333837313336363136322d320000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 + + +1636 +02eb00000001000000000000046d61696c03777873026e6c0000010001 +02eb80000001000000030003046d61696c03777873026e6c0000010001c01100020001000151800007046e733038c011c01100020001000151800007046e733039c011c01100020001000151800006036e7334c011c02900010001000151800004c3790128c03c00010001000151800004c3790143c04f00010001000151800004d5ef9a65 + +1637 +e16d00000001000000000000086a756c69657474650762657374776562026e6c0000010001 +e16d80000001000000020002086a756c69657474650762657374776562026e6c0000010001c0150002000100015180000e08706f7765722d6133026133c01dc0150002000100015180000c09706f7765722d697078c03ac0310001000100015180000451113b42c04b00010001000151800004d5ab40e6 + +1638 +04920000000100000000000003323034033139320236310232340770726f786965730a626c61636b686f6c657307656173796e6574026e6c00001c0001 +04928000000100000002000203323034033139320236310232340770726f786965730a626c61636b686f6c657307656173796e6574026e6c00001c0001c02d00020001000151800006036e7330c02dc02d00020001000151800006036e7331c02dc04900010001000151800004c2a55e01c05b00010001000151800004c2a55e05 + +1639 +b2c4e8b75011fae2d3140000000000000000 + + +1640 +000000007002faf00f9e0000020405b401010402 +000080010000000000000000 + +1641 +613000000001000000000000046d61696c086e65646c696e7578026e6c0000010001 +613080000001000000030003046d61696c086e65646c696e7578026e6c0000010001c01100020001000151800006036e7331c011c01100020001000151800006036e7332c011c01100020001000151800006036e7333c011c02e00010001000151800004d5ef87d2c04000010001000151800004d5ef87d3c05200010001000151800004d5ef8005 + +1642 +b2c4e8b85010fae2d3130000000000000000 + + +1643 +e6930000000100000000000006636861726973026e6c00000f0001 +e6938000000100000002000006636861726973026e6c00000f0001c00c0002000100015180000c026e7306766576696461c013c00c00020001000151800006036e7332c02a + +1644 +b2c581cb5010faf007c10000000000000000 + + +1645 +b2c581cb5018faf0258a0000008ff7a7000000010001000000000f313133333837313336363136322d320000f900010f313133333837313336363136322d320000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 + + +1646 +e97b00000001000000000000036e73310b7669727475616c686f7374026e6c0000010001 +e97b80000001000000020000036e73310b7669727475616c686f7374026e6c0000010001c01000020001000151800013036e733109676c6f62616c6e656403636f6d00c01000020001000151800006036e7332c034 + +1647 +e97c00000001000000000000036e73320b7669727475616c686f7374026e6c0000010001 +e97c80000001000000020000036e73320b7669727475616c686f7374026e6c0000010001c01000020001000151800013036e733109676c6f62616c6e656403636f6d00c01000020001000151800006036e7332c034 + +1648 +bffb0000000100000000000003626c3102626c06787334616c6c026e6c0000010001 +bffb8000000100000003000203626c3102626c06787334616c6c026e6c0000010001c01300020001000151800005026e73c013c01300020001000151800006036e7332c013c0130002000100015180000d026e730472697065036e657400c02e00010001000151800004c26d0642c03f00010001000151800004c26d0963 + +1649 +37fd00000001000000000000036e73340767617574656e67026e6c0000010001 +37fd80000001000000020000036e73340767617574656e67026e6c0000010001c0100002000100015180000d036e7331066c696e6b7570c018c01000020001000151800006036e7332c030 + +1650 +73360000000100000000000004646e7331057368656c6c026e6c0000010001 +73368000000100000003000004646e7331057368656c6c026e6c0000010001c0110002000100015180001004646e7331057368656c6c03636f6d00c0110002000100015180000704646e7332c030c0110002000100015180000704646e7333c030 + +1651 +8bea00000001000000000000037777770764736c6465736b026e6c0000010001 +8bea80000001000000020000037777770764736c6465736b026e6c0000010001c01000020001000151800014036e73310a676f6c64766973696f6e03636f6d00c01000020001000151800006036e7332c030 + +1652 +35fc00000001000000000000034e53320743495354524f4e024e4c0000010001 +35fc80000001000000020002034e53320743495354524f4e024e4c0000010001c01000020001000151800005026e73c010c01000020001000151800002c00cc02c000100010001518000043ed81f37c00c000100010001518000043ed81f38 + +1653 +b2c581d95011fae2072f0000000000000000 + + +1654 +e94000000001000000000000037777770a6c696e6b746970706572026e6c0000010001 +e94080000001000000030003037777770a6c696e6b746970706572026e6c0000010001c0100002000100015180000c036e7331056d61786573c01bc01000020001000151800006036e7332c033c01000020001000151800006036e7333c033c02f000100010001518000045045402ec047000100010001518000045045402fc059000100010001518000045045440a + +1655 +77be0000000100000000000003777777086879706f686f6d65026e6c0000010001 +77be8000000100000002000003777777086879706f686f6d65026e6c0000010001c01000020001000151800013036e733109696d6167653264617903636f6d00c01000020001000151800006036e7332c031 + +1656 +4fb500000001000000000000036e733208696e74726f776562026e6c0000010001 +4fb580000001000000020002036e733208696e74726f776562026e6c0000010001c01000020001000151800006036e7331c010c01000020001000151800002c00cc02d0001000100015180000450416028c00c00010001000151800004c356780c + +1657 +b2c581da5010fae2072e0000000000000000 + + +1658 +5c6a0010000100000000000007636172746d616e076e6574666c6f77026e6c0000010001 +5c6a8000000100000002000207636172746d616e076e6574666c6f77026e6c0000010001c01400020001000151800006036e7331c014c01400020001000151800006036e7332c014c030000100010001518000043eb1ef24c042000100010001518000043eb1ef25 + +1659 +92d100000001000000000000036e7332076e656473746174026e6c0000010001 +92d180000001000000020002036e7332076e656473746174026e6c0000010001c01000020001000151800005026e73c010c01000020001000151800006036e7333c010c02c00010001000151800004d4482615c03d00010001000151800004d5c4021d + +1660 +921500000001000000000000036e7334076e656473746174026e6c0000010001 +921580000001000000020002036e7334076e656473746174026e6c0000010001c01000020001000151800005026e73c010c01000020001000151800006036e7333c010c02c00010001000151800004d4482615c03d00010001000151800004d5c4021d + +1661 +ba9500000001000000000000036e7332076e656473746174026e6c0000260001 +ba9580000001000000020002036e7332076e656473746174026e6c0000260001c01000020001000151800005026e73c010c01000020001000151800006036e7333c010c02c00010001000151800004d4482615c03d00010001000151800004d5c4021d + +1662 +3a9f00000001000000000000036e7334076e656473746174026e6c0000260001 +3a9f80000001000000020002036e7334076e656473746174026e6c0000260001c01000020001000151800005026e73c010c01000020001000151800006036e7333c010c02c00010001000151800004d4482615c03d00010001000151800004d5c4021d + +1663 +175c28000001000000010000026e6c0000060001095f6b65726265726f73045f746370155374616e64616172642d6565727374652d73697465065f7369746573026463065f6d736463730b746563686e6f70616e656c026e6c000021000100000258001c000000640058056e746673310b746563686e6f70616e656c026e6c00 +175ca8040000000000000000 + +1664 +3cfa00000001000000000000036e733108696e74726f776562026e6c0000010001 +3cfa80000001000000020002036e733108696e74726f776562026e6c0000010001c01000020001000151800002c00cc01000020001000151800006036e7332c010c00c0001000100015180000450416028c03b00010001000151800004c356780c + +1665 +e0ea0000000100000000000006636f6f6b696504696c7365026e6c0000010001 +e0ea8000000100000003000306636f6f6b696504696c7365026e6c0000010001c01300020001000151800006036e7331c013c01300020001000151800006036e7332c013c01300020001000151800006036e7333c013c02c000100010001518000043e45a282c03e000100010001518000043e45a283c050000100010001518000043e45a284 + +1666 +000000007002faf01bd90000020405b401010402 +000080010000000000000000 + +1667 +ddaf000000010000000000000377777709766572626f7577656e026e6c0000010001 +ddaf800000010000000200020377777709766572626f7577656e026e6c0000010001c0100002000100015180000f036e7331086765656e70756e74c01ac01000020001000151800006036e7332c032c02e00010001000151800004d4ccd865c049000100010001518000045054ec34 + +1668 +b2c62b8d5010faf06a390000000000000000 +b2c6ab840000000000000000 + +1669 +b2c62b8d5018faf031d50000008f4cd4000000010001000000000f313133333837313336363136322d330000f900010f313133333837313336363136322d330000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 +b2c6ab840000000000000000 + +1670 +897c0000000100000000000004686f6d650774697363616c69026e6c0000010001 +897c8000000100000003000204686f6d650774697363616c69026e6c0000010001c0110002000100015180000704616e7331c011c0110002000100015180000704616e7332c011c0110002000100015180001404616e73330a74697363616c696e657402626500c02d00010001000151800004c3f14d38c04000010001000151800004c3f13325 + +1671 +4caa00000001000000000000086f76657268656964047a6f656b026e6c0000010001 +4caa80000001000000020002086f76657268656964047a6f656b026e6c0000010001c0150002000100015180000d026e73076e65746c616e64c01ac01500020001000151800006036e7332c031c02e00010001000151800004d9aa2042c04700010001000151800004d9aa2c06 + +1672 +5eb200000001000000000000086f76657268656964047a6f656b026e6c0000010001 +5eb280000001000000020002086f76657268656964047a6f656b026e6c0000010001c0150002000100015180000d026e73076e65746c616e64c01ac01500020001000151800006036e7332c031c02e00010001000151800004d9aa2042c04700010001000151800004d9aa2c06 + +1673 +b2c62b9b5011fae269a70000000000000000 +b2c6ab940000000000000000 + +1674 +000000007002faf04d060000020405b401010402 +000080010000000000000000 + +1675 +e97f00000001000000000000036e73320b7669727475616c686f7374026e6c0000010001 +e97f80000001000000020000036e73320b7669727475616c686f7374026e6c0000010001c01000020001000151800013036e733109676c6f62616c6e656403636f6d00c01000020001000151800006036e7332c034 + +1676 +e97e00000001000000000000036e73310b7669727475616c686f7374026e6c0000010001 +e97e80000001000000020000036e73310b7669727475616c686f7374026e6c0000010001c01000020001000151800013036e733109676c6f62616c6e656403636f6d00c01000020001000151800006036e7332c034 + +1677 +c36200000001000000000000046d61696c06737469626265026e6c0000010001 +c36280000001000000020002046d61696c06737469626265026e6c0000010001c01100020001000151800011026e730b666163696e676661637473c018c01100020001000151800006036e7332c02fc02c00010001000151800004d513b013c04900010001000151800004d513b012 + +1678 +7637000000010000000000000777656276696577026e6c00000f0001 +7637800000010000000200000777656276696577026e6c00000f0001c00c00020001000151800012036e73310b6d6565737465726c696a6bc014c00c00020001000151800006036e7332c02c + +1679 +e7000000000100000000000005627261616d026e6c00000f0001 +e7008000000100000002000205627261616d026e6c00000f0001c00c0002000100015180000b036e73310461786974c012c00c00020001000151800006036e7332c02ac026000100010001518000043e3a440bc03d000100010001518000043e3a440c + +1680 +b2c62b9c5010fae269a60000000000000000 +b2c6ab940000000000000000 + +1681 +e5cc000000010000000000000f6d656c6b7765672d686f6c6c616e64026e6c00000f0001 +e5cc800000010000000300030f6d656c6b7765672d686f6c6c616e64026e6c00000f0001c00c0002000100015180000e076e73617574683103626974c01cc00c0002000100015180000a076e736175746832c038c00c0002000100015180000a076e736175746833c038c03000010001000151800004d5880c33c04a00010001000151800004d5880c3bc06000010001000151800004d4ccc00b + +1682 +3a0f000000010000000000000964656e68656c646572026e6c00000f0001 +3a0f800000010000000200020964656e68656c646572026e6c00000f0001c00c00020001000151800011036e73310a7765626275726f646e73c016c00c00020001000151800006036e7332c02ec02a00010001000151800004d51380cec04700010001000151800004d513806a + +1683 +b2c6b1045010faf015ef0000000000000000 + + +1684 +b2c6b1045018faf01a1d0000008f1143000000010001000000000f313133333837313336363136322d320000f900010f313133333837313336363136322d320000f900ff00000000005303677373096d6963726f736f667403636f6d00403afc84403c4e040003000000304e544c4d535350000100000097b208e00b000b002500000005000500200000004e54465331544543484e4f50414e454c0000 + + +1685 +c22900000001000000000000036e733103727567026e6c0000010001 +c22980000001000000030003036e733103727567026e6c0000010001c01000020001000151800002c00cc01000020001000151800006036e7332c010c0100002000100015180000e036e733107737572666e6574c014c00c00010001000151800004817d0406c03600010001000151800004817d040dc04800010001000151800004c0576a65 + +1686 +ab8400000001000000000000036e733203727567026e6c0000010001 +ab8480000001000000030003036e733203727567026e6c0000010001c01000020001000151800006036e7331c010c01000020001000151800002c00cc0100002000100015180000e036e733107737572666e6574c014c02800010001000151800004817d0406c00c00010001000151800004817d040dc04800010001000151800004c0576a65 + +1687 +0359000000010000000000000f50432d30392054454120262052494108627275696e686f66026e6c0000010001 +0359800000010000000300020f50432d30392054454120262052494108627275696e686f66026e6c0000010001c01c0002000100015180000d036e733106776964657873c025c01c00020001000151800010036e733206776964657873036e657400c01c00020001000151800006036e7333c03dc03900010001000151800004d4ccc0fcc06e000100010001518000043efa0703 + +1688 +38fd0000000100000000000006636861726973026e6c0000ff0001 +38fd8000000100000002000006636861726973026e6c0000ff0001c00c0002000100015180000c026e7306766576696461c013c00c00020001000151800006036e7332c02a + +1689 +4e9100000001000000000000076e6372766e6574026e6c00000f0001 +4e9180000001000000030003076e6372766e6574026e6c00000f0001c00c0002000100015180001208736f6c7574696f6e06736f6c636f6ec014c00c00020001000151800006036e7331c031c00c00020001000151800006036e7332c031c02800010001000151800004d42d2005c04600010001000151800004d42d2003c05800010001000151800004d42d2103 + +1690 +964b00000001000000000000066b7669616e61036b7669026e6c0000010001 +964b80000001000000030003066b7669616e61036b7669026e6c0000010001c01300020001000151800009066b7669657870c013c01300020001000151800002c00cc0130002000100015180000e04616a6178066e696b686566c017c02b00010001000151800004817d0f01c00c00010001000151800004817d0f02c04e00010001000151800004c010c701 + +1691 +0ba600000001000000000000066b7669617376036b7669026e6c0000010001 +0ba680000001000000030003066b7669617376036b7669026e6c0000010001c01300020001000151800009066b7669657870c013c01300020001000151800009066b7669616e61c013c0130002000100015180000e04616a6178066e696b686566c017c02b00010001000151800004817d0f01c04000010001000151800004817d0f02c05500010001000151800004c010c701 + +1692 +85d300000001000000000000066b7669657870036b7669026e6c0000010001 +85d380000001000000030003066b7669657870036b7669026e6c0000010001c01300020001000151800002c00cc01300020001000151800009066b7669616e61c013c0130002000100015180000e04616a6178066e696b686566c017c00c00010001000151800004817d0f01c03900010001000151800004817d0f02c04e00010001000151800004c010c701 + +1693 +11fc000000010000000000000234330332313503313733033134320770726f786965730a626c61636b686f6c657307656173796e6574026e6c00001c0001 +11fc800000010000000200020234330332313503313733033134320770726f786965730a626c61636b686f6c657307656173796e6574026e6c00001c0001c02e00020001000151800006036e7330c02ec02e00020001000151800006036e7331c02ec04a00010001000151800004c2a55e01c05c00010001000151800004c2a55e05 + +1694 +769c000000010000000000000a6d61726b656e6865656d026e6c00000f0001 +769c800000010000000200020a6d61726b656e6865656d026e6c00000f0001c00c0002000100015180000c026e7306787334616c6cc017c00c00020001000151800006036e7332c02ec02b00010001000151800004c26d0642c04300010001000151800004c26d0963 + +1695 +9355000000010000000000000d3231312d3233322d34372d343708696e746572746e7303636f6d06787369746573026e6c0000010001 +9355800000010000000200020d3231312d3233322d34372d343708696e746572746e7303636f6d06787369746573026e6c0000010001c02700020001000151800006036e7331c027c02700020001000151800006036e7332c027c042000100010001518000045054f526c054000100010001518000045054f527 + +1696 +51c600000001000000000000056761726f74026e6c00000f0001 +51c680000001000000020002056761726f74026e6c00000f0001c00c0002000100015180000f026e7309656174736572766572c012c00c00020001000151800006036e7332c029c02600010001000151800004d4cb0e42c04100010001000151800004d4cb1221 + +1697 +b2c6b1125011fae2155d0000000000000000 + + +1698 +000000007002faf041280000020405b401010402 +000080010000000000000000 + +1699 +c1f700000001000000000000096e696a656e6b616d70026e6c00000f0001 +c1f780000001000000020002096e696a656e6b616d70026e6c00000f0001c00c0002000100015180000f036e733108696e74726f776562c016c00c00020001000151800006036e7332c02ec02a0001000100015180000450416028c04500010001000151800004c356780c + diff --git a/static/netbsd/man3/test_signatures.3 b/static/netbsd/man3/test_signatures.3 new file mode 100644 index 00000000..fddc462c --- /dev/null +++ b/static/netbsd/man3/test_signatures.3 @@ -0,0 +1,48 @@ +; Signature test file + +; first entry is a DNSKEY answer, with the DNSKEY rrset used for verification. +; later entries are verified with it. + +; created test keys with bind tools: +; dnssec-keygen 9.4.2: /usr/sbin/dnssec-keygen -a DSA -b 512 -n ZONE nlnetlabs.nl +; Knlnetlabs.nl.+003+03510 + +; private key file: +; Private-key-format: v1.2 +; Algorithm: 3 (DSA) +; Prime(p): 4nziv5P4tsXwaf71EoyKFoLzFq0/wN5fb6yb8IY5uwmVh5hvO0M4lR8LAjwimCIo3SYEdCnUPkl8WbJYHkRm9w== +; Subprime(q): 3ueDKL3Jc2Ue1G/ZCfhwMEyR4v0= +; Base(g): Ji9iYukmprX5qXO7V0MALKCTsfvz3kef2TsZdpM/VdetDK53OwKE1NRTMU6PSPGyumedOrkSD2BLa7CT1dJRJQ== +; Private_value(x): wlEfaVwW10q6Re/ZOBL9PLJJb20= +; Public_value(y): cHuTGyrkbj5QVkgmFm3KEpLnb5c7jH6tapeU5ugEIJiacbroPhfz/9vPw8tkZedBGImuYPSohRPfHIQPMxfxAg== + + +; DSA key from bind tool 9.4.2 +ENTRY_BEGIN +SECTION QUESTION +nlnetlabs.nl. IN DNSKEY +SECTION ANSWER +nlnetlabs.nl. IN DNSKEY 256 3 3 AN7ngyi9yXNlHtRv2Qn4cDBMkeL94nziv5P4tsXwaf71EoyKFoLzFq0/ wN5fb6yb8IY5uwmVh5hvO0M4lR8LAjwimCIo3SYEdCnUPkl8WbJYHkRm 9yYvYmLpJqa1+alzu1dDACygk7H7895Hn9k7GXaTP1XXrQyudzsChNTU UzFOj0jxsrpnnTq5Eg9gS2uwk9XSUSVwe5MbKuRuPlBWSCYWbcoSkudv lzuMfq1ql5Tm6AQgmJpxuug+F/P/28/Dy2Rl50EYia5g9KiFE98chA8z F/EC +ENTRY_END + +; entry to test +; from +; /usr/sbin/dnssec-signzone nlnetlabs.nl +ENTRY_BEGIN +SECTION QUESTION +nlnetlabs.nl. IN SOA +SECTION ANSWER +nlnetlabs.nl. 10200 IN SOA open.nlnetlabs.nl. hostmaster.nlnetlabs.nl. ( 2008040100 28800 7200 604800 3600 ) +nlnetlabs.nl. 10200 RRSIG SOA 3 2 10200 20080515132632 ( 20080415132632 3510 nlnetlabs.nl. ACYwIl9GQofKJ2xdgx1YelKbtmLrWRl8f+eC ToRnfyQ+gvdUIX3mTTw= ) +ENTRY_END + +ENTRY_BEGIN +SECTION QUESTION +nlnetlabs.nl. IN NS +SECTION ANSWER +nlnetlabs.nl. 10200 NS omval.tednet.nl. +nlnetlabs.nl. 10200 NS ns7.domain-registry.nl. +nlnetlabs.nl. 10200 NS open.nlnetlabs.nl. +nlnetlabs.nl. 10200 RRSIG NS 3 2 10200 20080515132632 ( 20080415132632 3510 nlnetlabs.nl. AEYy9ZN3KEDHybhZbL3PoR71jMQuufKM1lej +obA6uL6CjYQAPrL9tk= ) +ENTRY_END + diff --git a/static/netbsd/man3/textdomain.3 b/static/netbsd/man3/textdomain.3 new file mode 100644 index 00000000..29b30e98 --- /dev/null +++ b/static/netbsd/man3/textdomain.3 @@ -0,0 +1,57 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" This is free documentation; 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 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" GNU gettext source code and manual +.\" LI18NUX 2000 Globalization Specification +.\" +.TH TEXTDOMAIN 3 "May 2001" "GNU gettext 0.16.1" +.SH NAME +textdomain \- set domain for future gettext() calls +.SH SYNOPSIS +.nf +.B #include <libintl.h> +.sp +.BI "char * textdomain (const char * " domainname ); +.fi +.SH DESCRIPTION +The \fBtextdomain\fP function sets or retrieves the current message domain. +.PP +A message domain is a set of translatable \fImsgid\fP messages. Usually, +every software package has its own message domain. The domain name is used +to determine the message catalog where a translation is looked up; it must +be a non-empty string. +.PP +The current message domain is used by the \fBgettext\fP, \fBngettext\fP +functions, and by the \fBdgettext\fP, \fBdcgettext\fP, \fBdngettext\fP and +\fBdcngettext\fP functions when called with a NULL domainname argument. +.PP +If \fIdomainname\fP is not NULL, the current message domain is set to +\fIdomainname\fP. The string the function stores internally is a copy of the +\fIdomainname\fP argument. +.PP +If \fIdomainname\fP is NULL, the function returns the current message domain. +.SH "RETURN VALUE" +If successful, the \fBtextdomain\fP function returns the current message +domain, after possibly changing it. The resulting string is valid until the +next \fBtextdomain\fP call and must not be modified or freed. If a memory +allocation failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns +NULL. +.SH ERRORS +The following error can occur, among others: +.TP +.B ENOMEM +Not enough memory available. +.SH BUGS +The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid +warnings in C code predating ANSI C. +.SH "SEE ALSO" +.BR gettext (3), +.BR ngettext (3), +.BR bindtextdomain (3), +.BR bind_textdomain_codeset (3) diff --git a/static/netbsd/man3/thrd.3 b/static/netbsd/man3/thrd.3 new file mode 100644 index 00000000..76d08413 --- /dev/null +++ b/static/netbsd/man3/thrd.3 @@ -0,0 +1,234 @@ +.\" $NetBSD: thrd.3,v 1.3 2019/04/27 10:57:11 wiz Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt THRD 3 +.Os +.Sh NAME +.Nm thrd +.Nd thread functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Vt typedef "int" "(*thrd_start_t)" "(void *)" +.Ft int +.Fn thrd_create "thrd_t *thr" "thrd_start_t func" "void *arg" +.Ft thrd_t +.Fn thrd_current "void" +.Ft int +.Fn thrd_detach "thrd_t thr" +.Ft int +.Fn thrd_equal "thrd_t t1" "thrd_t t2" +.Ft _Noreturn void +.Fn thrd_exit "int res" +.Ft int +.Fn thrd_join "thrd_t thr" "int *res" +.Ft int +.Fn thrd_sleep "const struct timespec *duration" "struct timespec *remaining" +.Ft void +.Fn thrd_yield "void" +.Sh DESCRIPTION +The +.Nm +interface operates over opaque objects of the +.Dv thrd_t +type. +.Pp +The +.Fn thrd_create +function is used to create a new thread, calling +.Fa func +with the +.Fa arg +parameter. +This function initializes the +.Fa thr +object with the identifier of the newly created thread. +The completion of +.Fn thrd_create +is synchronized with the start of the newly produced thread. +It is possible to reuse the +.Fa thr +object once the thread has terminated either by joining another thread +operation or been detached. +.Pp +The +.Fn thrd_current +function returns the thread identifier of the current thread. +.Pp +The +.Fn thrd_detach +function is used to indicate that storage for the +.Fa thr +object can be reclaimed on the thread's termination. +The +.Fa thr +object cannot be already detached or joined. +.Pp +The +.Fn thrd_equal +function is used to check whether two +.Fa t1 +and +.Fa t2 +objects refer to the same thread. +.Pp +The +.Fn thrd_exit +function terminates the calling thread and passes the +.Fa res +value that might be read by the +.Fn thrd_join +function. +The program terminates once all threads have been terminated with +an exit code equivalent to calling the +.Xr exit 3 +function with the +.Dv EXIT_SUCCESS +status. +The +.Fn thrd_join +function joins the +.Fa thr +thread, waiting and blocking until it has terminated. +The +.Fa res +parameter points to a variable that will store the status passed from the +joined function. +If +.Fa res +is +.Dv NULL +then the status from the +.Fn thrd_exit +function is ignored. +.Pp +The +.Fn thrd_sleep +function suspends execution of the calling thread until either +a signal is received or the interval specified in the +.Fa duration +argument has been passed. +The +.Fa remaining +parameter stores requested timeout reduced with the time actually suspended. +This argument is used when +.Fn thrd_sleep +has been interrupted. +It is valid code to point both arguments +.Fa duration +and +.Fa remaining +to the same object. +It is not guaranteed that sleep will not take longer than specified in +.Fa duration , +however unless interrupted with a signal it will not take shorter +than the specified interval. +.Pp +The +.Fn thrd_yield +function yields a process voluntarily and gives other threads a chance to run +without waiting for any involuntary preemptive switch. +.Sh RETURN VALUES +The +.Fn thrd_create +function returns +.Dv thrd_success +on success, otherwise +.Dv thrd_nomem +if not sufficient memory could be allocated, or +.Dv thrd_error +on other errors. +.Pp +The +.Fn thrd_current +function returns the identifier of the calling thread. +.Pp +The +.Fn thrd_detach +function returns +.Dv thrd_current +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn thrd_equal +function returns zero if +.Fa t0 +and +.Fa t1 +refer to the different threads, +otherwise it will return non-zero. +.Pp +The +.Fn thrd_exit +function does not return. +.Pp +The +.Fn thrd_join +function returns +.Dv thrd_success +on success or +.Dv thrd_error +on failure. +.Pp +The +.Fn thrd_sleep +function returns 0 on success (as the requested time has elapsed), +\-1 once the function was interrupted by a signal, +or a negative value to indicate error. +The +.Nx +implementation returns \-2 on error. +.Pp +The +.Fn thrd_yield +function returns no value. +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr pthread_create 3 , +.Xr pthread_detach 3 , +.Xr pthread_equal 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr pthread_self 3 , +.Xr sched 3 , +.Xr threads 3 +.Sh STANDARDS +The +.Nm +interface conforms to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/thread.h.3 b/static/netbsd/man3/thread.h.3 new file mode 100644 index 00000000..e2aa7bd4 --- /dev/null +++ b/static/netbsd/man3/thread.h.3 @@ -0,0 +1,210 @@ +.TH "event2/thread.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/thread.h \- Functions for multi-threaded applications using Libevent\&. + +.SH SYNOPSIS +.br +.PP +\fC#include <event2/visibility\&.h>\fP +.br +\fC#include <event2/event\-config\&.h>\fP +.br + +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBevthread_condition_callbacks\fP" +.br +.RI "\fIThis structure describes the interface a threading library uses for condition variables\&. \fP" +.ti -1c +.RI "struct \fBevthread_lock_callbacks\fP" +.br +.RI "\fIThis structure describes the interface a threading library uses for locking\&. \fP" +.in -1c +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEVTHREAD_CONDITION_API_VERSION\fP 1" +.br +.ti -1c +.RI "#define \fBEVTHREAD_LOCK_API_VERSION\fP 1" +.br +.ti -1c +.RI "#define \fBEVTHREAD_USE_PTHREADS_IMPLEMENTED\fP 1" +.br +.RI "\fIDefined if Libevent was built with support for \fBevthread_use_pthreads()\fP \fP" +.ti -1c +.RI "#define \fBEVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED\fP 1" +.br +.RI "\fIDefined if Libevent was built with support for \fBevthread_use_windows_threads()\fP \fP" +.in -1c +.PP +.RI "\fBFlags passed to lock functions\fP" +.br + +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVTHREAD_WRITE\fP 0x04" +.br +.RI "\fIA flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for writing\&. \fP" +.ti -1c +.RI "#define \fBEVTHREAD_READ\fP 0x08" +.br +.RI "\fIA flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for reading\&. \fP" +.ti -1c +.RI "#define \fBEVTHREAD_TRY\fP 0x10" +.br +.RI "\fIA flag passed to a locking callback when we don't want to block waiting for the lock; if we can't get the lock immediately, we will instead return nonzero from the locking callback\&. \fP" +.in -1c +.in -1c +.PP +.RI "\fBTypes of locks\fP" +.br + +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVTHREAD_LOCKTYPE_RECURSIVE\fP 1" +.br +.RI "\fIA recursive lock is one that can be acquired multiple times at once by the same thread\&. \fP" +.ti -1c +.RI "#define \fBEVTHREAD_LOCKTYPE_READWRITE\fP 2" +.br +.in -1c +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevthread_enable_lock_debugging\fP (void)" +.br +.RI "\fIEnable debugging wrappers around the current lock callbacks\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevthread_enable_lock_debuging\fP (void)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_make_base_notifiable\fP (struct \fBevent_base\fP *base)" +.br +.RI "\fIMake sure it's safe to tell an event base to wake up from another thread or a signal handler\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_condition_callbacks\fP (const struct \fBevthread_condition_callbacks\fP *)" +.br +.RI "\fISets a group of functions that Libevent should use for condition variables\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevthread_set_id_callback\fP (unsigned long(*id_fn)(void))" +.br +.RI "\fISets the function for determining the thread id\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_lock_callbacks\fP (const struct \fBevthread_lock_callbacks\fP *)" +.br +.RI "\fISets a group of functions that Libevent should use for locking\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_pthreads\fP (void)" +.br +.RI "\fISets up Libevent for use with Pthreads locking and thread ID functions\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_windows_threads\fP (void)" +.br +.RI "\fISets up Libevent for use with Windows builtin locking and thread ID functions\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Functions for multi-threaded applications using Libevent\&. + +When using a multi-threaded application in which multiple threads add and delete events from a single event base, Libevent needs to lock its data structures\&. +.PP +Like the memory-management function hooks, all of the threading functions \fImust\fP be set up before an \fBevent_base\fP is created if you want the base to use them\&. +.PP +Most programs will either be using Windows threads or Posix threads\&. You can configure Libevent to use one of these event_use_windows_threads() or event_use_pthreads() respectively\&. If you're using another threading library, you'll need to configure threading functions manually using \fBevthread_set_lock_callbacks()\fP and \fBevthread_set_condition_callbacks()\fP\&. +.SH "Macro Definition Documentation" +.PP +.SS "#define EVTHREAD_LOCKTYPE_RECURSIVE 1" + +.PP +A recursive lock is one that can be acquired multiple times at once by the same thread\&. No other process can allocate the lock until the thread that has been holding it has unlocked it as many times as it locked it\&. +.SS "#define EVTHREAD_READ 0x08" + +.PP +A flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for reading\&. +.SS "#define EVTHREAD_TRY 0x10" + +.PP +A flag passed to a locking callback when we don't want to block waiting for the lock; if we can't get the lock immediately, we will instead return nonzero from the locking callback\&. +.SS "#define EVTHREAD_WRITE 0x04" + +.PP +A flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for writing\&. +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL void evthread_enable_lock_debugging (void)" + +.PP +Enable debugging wrappers around the current lock callbacks\&. If Libevent makes one of several common locking errors, exit with an assertion failure\&. +.PP +If you're going to call this function, you must do so before any locks are allocated\&. +.SS "EVENT2_EXPORT_SYMBOL int evthread_make_base_notifiable (struct \fBevent_base\fP * base)" + +.PP +Make sure it's safe to tell an event base to wake up from another thread or a signal handler\&. You shouldn't need to call this by hand; configuring the base with thread support should be necessary and sufficient\&. +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evthread_set_condition_callbacks (const struct \fBevthread_condition_callbacks\fP *)" + +.PP +Sets a group of functions that Libevent should use for condition variables\&. For full information on the required callback API, see the documentation for the individual members of \fBevthread_condition_callbacks\fP\&. +.PP +Note that if you're using Windows or the Pthreads threading library, you probably shouldn't call this function; instead, use \fBevthread_use_windows_threads()\fP or \fBevthread_use_pthreads()\fP if you can\&. +.SS "EVENT2_EXPORT_SYMBOL void evthread_set_id_callback (unsigned long(*)(void) id_fn)" + +.PP +Sets the function for determining the thread id\&. +.PP +\fBParameters:\fP +.RS 4 +\fIbase\fP the event base for which to set the id function +.br +\fIid_fn\fP the identify function Libevent should invoke to determine the identity of a thread\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evthread_set_lock_callbacks (const struct \fBevthread_lock_callbacks\fP *)" + +.PP +Sets a group of functions that Libevent should use for locking\&. For full information on the required callback API, see the documentation for the individual members of \fBevthread_lock_callbacks\fP\&. +.PP +Note that if you're using Windows or the Pthreads threading library, you probably shouldn't call this function; instead, use \fBevthread_use_windows_threads()\fP or evthread_use_posix_threads() if you can\&. +.SS "EVENT2_EXPORT_SYMBOL int evthread_use_pthreads (void)" + +.PP +Sets up Libevent for use with Pthreads locking and thread ID functions\&. Unavailable if Libevent is not build for use with pthreads\&. Requires libraries to link against Libevent_pthreads as well as Libevent\&. +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evthread_use_windows_threads (void)" + +.PP +Sets up Libevent for use with Windows builtin locking and thread ID functions\&. Unavailable if Libevent is not built for Windows\&. +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure\&. +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/threads.3 b/static/netbsd/man3/threads.3 new file mode 100644 index 00000000..1aa4c9a9 --- /dev/null +++ b/static/netbsd/man3/threads.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: threads.3,v 1.3 2025/12/10 21:21:12 andvar Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt THREADS 3 +.Os +.Sh NAME +.Nm threads +.Nd C11 thread support library +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Sh DESCRIPTION +The C11 thread support library provides an implementation of a portable threading +interface, built on top of the +.Xr pthread 3 +native interfaces. +This library is composed of: +.Bl -dash +.It +Initialization functions. +.It +Condition variable functions. +.It +Mutex functions. +.It +Thread functions. +.It +Thread-specific storage functions. +.El +.Bl -column "mtx_timedwait" +.It Sy "Function" Ta Sy "Summary" +.It Xr call_once 3 Ta calls function exactly once +.It Xr cnd_broadcast 3 Ta unblocks all threads blocked on a condition +.It Xr cnd_destroy 3 Ta releases all resources used by a condition +.It Xr cnd_init 3 Ta creates a condition variable +.It Xr cnd_signal 3 Ta unblocks one of threads blocked on a condition +.It Xr cnd_timedwait 3 Ta unlocks a mutex and blocks until a signal or timeout +.It Xr cnd_wait 3 Ta unlocks a mutex and blocks until a signal +.It Xr mtx_destroy 3 Ta releases resources used by a mutex +.It Xr mtx_init 3 Ta creates a mutex object with requested properties +.It Xr mtx_lock 3 Ta blocks on a mutex optionally with a recursive type +.It Xr mtx_timedwait 3 Ta tries to block until it locks a mutex or timeout +.It Xr mtx_trylock 3 Ta tries to lock a mutex +.It Xr mtx_unlock 3 Ta unlocks a mutex +.It Xr thrd_create 3 Ta creates a thread executing a function with a parameter +.It Xr thrd_current 3 Ta identifies the thread that called this function +.It Xr thrd_detach 3 Ta dispose of resources allocated to a thread on exit +.It Xr thrd_equal 3 Ta determines whether two threads refer the same thread +.It Xr thrd_exit 3 Ta terminates a calling thread and sets its result code +.It Xr thrd_join 3 Ta joins a thread with the current one and blocks +.It Xr thrd_sleep 3 Ta suspends a calling thread until a signal or timeout +.It Xr tss_create 3 Ta creates a thread-specific storage pointer with a destructor +.It Xr tss_delete 3 Ta releases resources used by a thread-specific storage +.It Xr tss_get 3 Ta gets a value of thread-specific storage from a key +.It Xr tss_set 3 Ta sets a value of thread-specific storage to a key +.El +.Sh SEE ALSO +.Xr c11 1 , +.Xr pthread 3 , +.Xr c 7 +.Sh STANDARDS +The +.Nm +library interfaces conform to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/tiger.3 b/static/netbsd/man3/tiger.3 new file mode 100644 index 00000000..ea1e432b --- /dev/null +++ b/static/netbsd/man3/tiger.3 @@ -0,0 +1,218 @@ +.\" $NetBSD: tiger.3,v 1.4 2014/02/17 07:23:18 agc Exp $ +.\" +.\" Copyright (c) 2011 Alistair Crooks <agc@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 30, 2011 +.Dt TIGER 3 +.Os +.Sh NAME +.Nm TIGER_Init , +.Nm TIGER_Update , +.Nm TIGER_Final , +.Nm TIGER_End , +.Nm TIGER_File , +.Nm TIGER_Data +.Nd calculate TIGER message digests +.Sh SYNOPSIS +.In tiger.h +.Ft void +.Fo TIGER_Init +.Fa "TIGER_CTX *context" +.Fc +.Ft void +.Fo TIGER_Update +.Fa "TIGER_CTX *context" "const uint8_t *data" "u_int len" +.Fc +.Ft void +.Fo TIGER_Final +.Fa "uint8_t digest[20]" "TIGER_CTX *context" +.Fc +.Ft "char *" +.Fo TIGER_End +.Fa "TIGER_CTX *context" "char *buf" +.Fc +.Ft "char *" +.Fo TIGER_File +.Fa "char *filename" "char *buf" +.Fc +.Ft "char *" +.Fo TIGER_Data +.Fa "uint8_t *data" "size_t len" "char *buf" +.Fc +.Sh DESCRIPTION +The TIGER functions calculate TIGER message digest functions, +as defined by Ross Anderson and Eli Biham. +The algorithm takes a +message less than 2^64 bits as input and produces a 192-bit digest +suitable for use as a digital signature. +.Pp +At the time of writing, +May 2011, +no attacks or pre-imaging have been discovered against the +.Nm +message digests, whilst the same cannot be said of +.Xr md5 3 +or +.Xr sha1 3 . +.Pp +The +.Fn TIGER_Init +function initializes a TIGER_CTX +.Ar context +for use with +.Fn TIGER_Update , +and +.Fn TIGER_Final . +The +.Fn TIGER_Update +function adds +.Ar data +of length +.Ar len +to the TIGER_CTX specified by +.Ar context . +.Fn TIGER_Final +is called when all data has been added via +.Fn TIGER_Update +and stores a message digest in the +.Ar digest +parameter. +When a +.Dv NULL +pointer is passed to +.Fn TIGER_Final +as first argument only the final padding will be applied and the +current context can still be used with +.Fn TIGER_Update . +.Pp +The core of the TIGER message digest is performed by +.Fn TIGER_Update . +Most programs should use the interface provided by +.Fn TIGER_Init , +.Fn TIGER_Update , +and +.Fn TIGER_Final . +.Pp +The +.Fn TIGER_End +function is a frontend for +.Fn TIGER_Final +which converts the digest into an +.Tn ASCII +representation of the 160 bit digest in hexadecimal. +.Pp +The +.Fn TIGER_File +function calculates the digest for a file and returns the result via +.Fn TIGER_End . +If +.Fn TIGER_File +is unable to open the file a +.Dv NULL +pointer is returned. +.Pp +The +.Fn TIGER_Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn TIGER_End . +.Pp +For each of the +.Fn TIGER_End , +.Fn TIGER_File , +and +.Fn TIGER_Data +functions the +.Ar buf +parameter should either be a string of at least 41 characters in +size or a +.Dv NULL +pointer. +In the latter case, space will be dynamically allocated via +.Xr malloc 3 +and should be freed using +.Xr free 3 +when it is no longer needed. +.Sh EXAMPLES +The follow code fragment will calculate the digest for the string +.Dq The quick brown fox jumps over the lazy dog , +which is +.Dq 6d12a41e72e644f017b6f0e2f7b44c6285f06dd5d2c5b075 . +.Bd -literal -offset indent +TIGER_CTX tiger; +uint8_t results[24]; +char *buf; +int n; + +buf = "The quick brown fox jumps over the lazy dog"; +n = strlen(buf); +TIGER_Init(\*[Am]tiger); +TIGER_Update(\*[Am]tiger, (uint8_t *)buf, n); +TIGER_Final(results, \*[Am]tiger); + +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n \*[Lt] 24; n++) + printf("%02x", results[n]); +putchar('\en'); +.Ed +.Pp +Alternately, the helper functions could be used in the following way: +.Bd -literal -offset indent +TIGER_CTX tiger; +uint8_t output[49]; +char *buf = "The quick brown fox jumps over the lazy dog"; + +printf("0x%s", TIGER_Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr md5 3 , +.Xr sha1 3 +.Rs +.%A Ross Anderson +.%A Eli Biham +.%T "Tiger \- A Fast New Hash Function" +.%B Proceedings of Fast Software Encryption 3, Cambridge +.%D 1996 +.Re +.Sh HISTORY +The TIGER functions appeared in +.Nx 6.0 . +.Sh AUTHORS +.An -nosplit +This implementation of TIGER was adapted by +.An Alistair Crooks Aq Mt agc@NetBSD.org +from the original reference code. +.Pp +The +.Fn TIGER_End , +.Fn TIGER_File , +and +.Fn TIGER_Data +helper functions are derived from code written by Poul-Henning Kamp. +.Sh BUGS +All attempts have been made to optimise for the underlying hardware, +as well as to format the digest properly in an endian-neutral manner. +The author has no VAX hardware on which to test, and so it is not known +whether that platform is supported. diff --git a/static/netbsd/man3/time.3 b/static/netbsd/man3/time.3 new file mode 100644 index 00000000..624ad075 --- /dev/null +++ b/static/netbsd/man3/time.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: time.3,v 1.17 2024/04/28 22:57:16 rillig Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)time.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 29, 2024 +.Dt TIME 3 +.Os +.Sh NAME +.Nm time +.Nd get time of day +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft time_t +.Fn time "time_t *tloc" +.Sh DESCRIPTION +The +.Fn time +function +returns the value of time in seconds since 0 hours, 0 minutes, +0 seconds, January 1, 1970, Coordinated Universal Time. +.Pp +If +.Fa tloc +is not a null pointer, a copy of the time value is saved in +.Fa *tloc . +.Pp +Upon successful completion, +.Fn time +returns the value of time. +Otherwise a value of +.Po +.Po Fa time_t Pc Ns \-1 +.Pc +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr ctime 3 +.Sh STANDARDS +The +.Fn time +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +A +.Fn time +function appeared in +.At v2 . +It returned a 32-bit value measuring sixtieths of a second, leading to +rollover every 2.26 years. +In +.At v6 , +the precision of +.Fn time +was changed to seconds, allowing 135.6 years between rollovers. +.Pp +In +.Nx 6.0 +the +.Vt time_t +type was changed to be 64 bits wide, including on 32-bit machines, +making rollover a concern for the far distant future only. +Note however that any code making the incorrect assumption that +.Vt time_t +is the same as +.Vt long +will fail on 32-bit machines in 2038. diff --git a/static/netbsd/man3/time2posix.3 b/static/netbsd/man3/time2posix.3 new file mode 100644 index 00000000..a4c60152 --- /dev/null +++ b/static/netbsd/man3/time2posix.3 @@ -0,0 +1,183 @@ +.\" $NetBSD: time2posix.3,v 1.24 2026/03/08 21:04:54 christos Exp $ +.\" @(#)time2posix.3 7.7 +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. +.Dd March 8, 2026 +.Dt TIME2POSIX 3 +.Os +.Sh NAME +.Nm time2posix , +.Nm time2posix_z , +.Nm posix2time , +.Nm posix2time_z +.Nd convert seconds since the Epoch +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft time_t +.Fn time2posix "time_t t" +.Ft time_t +.Fn time2posix_z "const timezone_t tz" "time_t t" +.Ft time_t +.Fn posix2time "time_t t" +.Ft time_t +.Fn posix2time_z "const timezone_t tz" "time_t t" +.Sh DESCRIPTION +.St -p1003.1 +says that +.Va time_t +values cannot count leap +seconds and, +therefore, +that the system time must be adjusted as each leap occurs. +.Pp +If the time package is configured with leap-second support +enabled, however, no such adjustment is needed and +.Va time_t +values continue to increase over leap events +(as a true +.Dq "seconds since..." +value). +This means that these values will differ from those required by POSIX +by the net number of leap seconds inserted since the Epoch. +.Pp +For many C programs this is not a problem as the C standard says that +.Va time_t +is +(mostly) +opaque \(em +.Va time_t +values should be obtainedfrom and +passedto functions such as +.Xr time 3 , +.Xr localtime 3 , +.Xr localtime_r 3 , +.Xr localtime_rz 3 , +.Xr mktime 3 , +.Xr mktime_z 3 , +and +.Xr difftime 3 . +However, POSIX gives an arithmetic expression for computing a +.Va time_t +value directly given Universal date and time, +and the same relationship is assumed by +some applications. +Any programs creating/dissecting +.Va time_t +values using such a relationship will typically not handle intervals over +leap seconds correctly. +.Pp +The +.Fn time2posix , +.Fn time2posix_z , +.Fn posix2time , +and +.Fn posix2time_z ++functions address this mismatch by converting +between local +.Va time_t +values and their POSIX equivalents. +This is done by accounting for the number of time-base changes that would +have taken place on a POSIX system as leap seconds were inserted or deleted. +These converted values can then be used +when communicating with POSIX-compliant systems. +.Pp +The +.Fn time2posix +and +.Fn time2posix_z +functions convert a +.Va time_t . +value to its POSIX counterpart, if one exists. +The +.Fn posix2time +and +.Fn posix2time +does the reverse but +are less well-behaved: +for a positive leap second hit the result is not unique, +and for a negative leap second hit the corresponding +POSIX +.Va time_t +doesn't exist so an adjacent value is returned. +Both these indicate problems with the +POSIX representation. +.Pp +The +.Dq z +variants of the two functions behave exactly like their counterparts, +but they operate in the given +.Fa tz +argument which was previously allocated using +.Xr tzalloc 3 +and are re-entrant. +.Pp +The following table summarizes the relationship between a +.Va time_t +and its conversion to, and back from, the POSIX representation over +the leap second inserted at the end of June, 1993. +In this table, X=time2posix(T), Y=posix2time(X), A=741484816, and B=A\-17 +because 17 positive leap seconds preceded this leap second. +.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent +.It Sy DATE TIME T X=time2posix(T) posix2time(X) +.It 1993-06-30 23:59:59 A+0 B+0 A+0 +.It 1993-06-30 23:59:60 A+1 B+1 A+1 or A+2 +.It 1993-07-01 00:00:00 A+2 B+1 A+1 or A+2 +.It 1993-07-01 00:00:01 A+3 B+2 A+3 +.El +.Pp +A leap second deletion would look like... +.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent +.It Sy DATE TIME T X=time2posix(T) posix2time(X) +.It ????-06-30 23:59:58 A+0 B+0 A+0 +.It ????-07-01 00:00:00 A+1 B+2 A+1 +.It ????-07-01 00:00:01 A+2 B+3 A+2 +.El +[Note: posix2time(B+1) => A+0 or A+1] +.Pp +If leap-second support is not enabled, local +.Va time_t +and +POSIX +.Va time_t +values are equivalent, +and both +.Fn time2posix +and +.Fn posix2time +degenerate to the identity function. ++.Sh "RETURN VALUE" +If successful, these functions return the resulting timestamp without modifying +.Va errno . +Otherwise, they set +.Va errno +and return +.Va "((time_t) -1)" . +.Sh ERRORS +These functions fail if: +.Bl -tag -width Er +.It Bq Er EOVERFLOW +The resulting value cannot be represented. +This can happen for +.Fn posix2time +if its argument is close to the maximum +.Va time_t +value. +In environments where the +.Ev TZ +environment variable names a TZif file, +overflow can happen for either function for an argument sufficiently +close to an extreme +.Va time_t +value if the TZif file specifies unrealistic leap second corrections. +.El +.Sh SEE ALSO +.Xr difftime 3 , +.Xr localtime 3 , +.Xr localtime_r 3 , +.Xr localtime_rz 3 , +.Xr mktime 3 , +.Xr mktime_z 3 , +.Xr time 3 , +.Xr tzalloc 3 diff --git a/static/netbsd/man3/times.3 b/static/netbsd/man3/times.3 new file mode 100644 index 00000000..f14d9eb2 --- /dev/null +++ b/static/netbsd/man3/times.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: times.3,v 1.15 2003/08/07 16:42:58 agc Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)times.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt TIMES 3 +.Os +.Sh NAME +.Nm times +.Nd process times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/times.h +.Ft clock_t +.Fn times "struct tms *tp" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr getrusage 2 +and +.Xr gettimeofday 2 . +.Ef +.Pp +The +.Fn times +function returns the value of time in clock ticks since 0 hours, 0 +minutes, 0 seconds, January 1, 1970, Coordinated Universal Time (UTC). +.Pp +The number of clock ticks per second may be determined by calling +.Xr sysconf 3 +with the +.Dv _SC_CLK_TCK +request. +It is generally (but not always) between 60 and 1024. +.Pp +Note that at the common rate of 100 ticks per second on many +.Nx +ports, and with a 32-bit unsigned clock_t, this value first wrapped in 1971. +.Pp +The +.Fn times +call also fills in the structure pointed to by +.Fa tp +with time-accounting information. +.Pp +The +.Fa tms +structure is defined as follows: +.Bd -literal -offset indent +typedef struct { + clock_t tms_utime; + clock_t tms_stime; + clock_t tms_cutime; + clock_t tms_cstime; +} +.Ed +.Pp +The elements of this structure are defined as follows: +.Bl -tag -width tms_cutime +.It Fa tms_utime +The +.Tn CPU +time charged for the execution of user instructions. +.It Fa tms_stime +The +.Tn CPU +time charged for execution by the system on behalf of +the process. +.It Fa tms_cutime +The sum of the +.Fa tms_utime s +and +.Fa tms_cutime s +of the child processes. +.It Fa tms_cstime +The sum of the +.Fa tms_stime Ns s +and +.Fa tms_cstime Ns s +of the child processes. +.El +.Pp +All times are measured in clock ticks, as defined above. +Note that at 100 ticks per second, +and with a 32-bit unsigned clock_t, +the values wrap after 497 days. +.Pp +The times of a terminated child process are included in the +.Fa tms_cutime +and +.Fa tms_cstime +elements of the parent when one of the +.Xr wait 2 +functions returns the process ID of the terminated child to the parent. +If an error occurs, +.Fn times +returns the value +.Pq (clock_t)\-1 , +and sets +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn times +function +may fail and set the global variable +.Va errno +for any of the errors specified for the library +routines +.Xr getrusage 2 +and +.Xr gettimeofday 2 . +.Sh SEE ALSO +.Xr time 1 , +.Xr getrusage 2 , +.Xr gettimeofday 2 , +.Xr wait 2 , +.Xr sysconf 3 +.Sh STANDARDS +The +.Fn times +function conforms to +.St -p1003.1-90 . diff --git a/static/netbsd/man3/timespec_get.3 b/static/netbsd/man3/timespec_get.3 new file mode 100644 index 00000000..8015bc0d --- /dev/null +++ b/static/netbsd/man3/timespec_get.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: timespec_get.3,v 1.9 2025/04/22 14:25:50 uwe Exp $ +.\" +.\" Copyright (c) 2016, 2025 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 22, 2025 +.Dt TIMESPEC_GET 3 +.Os +. +.Sh NAME +.Nm timespec_get , +.Nm timespec_getres +.Nd get current calendar time +. +.Sh LIBRARY +.Lb libc +. +.Sh SYNOPSIS +. +.In time.h +. +.Ft int +.Fn timespec_get "struct timespec *ts" "int base" +. +.Ft int +.Fn timespec_getres "struct timespec *ts" "int base" +. +.Sh DESCRIPTION +The +.Fn timespec_get +function sets the interval pointed to by +.Fa ts +to hold the current calendar time based on the specified time base in +.Fa base . +It is the +.Tn ISO C +equivalent to the +.Tn POSIX +function +.Xr clock_gettime 2 . +.Pp +The base +.Dv TIME_UTC +returns the time since the epoch. +This time is expressed in seconds and nanoseconds since midnight (0 hour), January 1, 1970. +In +.Nx , +this corresponds to +.Dv CLOCK_REALTIME . +.Pp +The base +.Dv TIME_MONOTONIC +returns the seconds and nanoseconds since an implementation-defined reference +point in such a way that a second call will never return a value less than the +first. +In +.Nx , +this corresponds to +.Dv CLOCK_MONOTONIC . +.Pp +The resolution of each timer can be queried using +.Fn timespec_getres . +Each successive call to this function will return the same value for a +specific clock. +It is the +.Tn ISO C +equivalent to the +.Tn POSIX +function +.Xr clock_getres 2 . +.Sh RETURN VALUES +These functions return the passed non-zero value of +.Fa base +if successful, otherwise 0 on failure. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr gettimeofday 2 , +.Xr time 3 +.Sh STANDARDS +The +.Fn timespec_get +function with a +.Fa base +of +.Dv TIME_UTC +conforms to +.St -isoC-2011 . +The +.Fa base +of +.Dv TIME_MONOTONIC +is specified in +.St -isoC-2023 . +.Pp +The +.Fn timespec_getres +function conforms to +.St -isoC-2023 . +.Sh HISTORY +The +.Fn timespec_get +function first appeared in +.Nx 8.0 . +.Pp +The +.Fn timespec_getres +function first appeared in +.Nx 11.0 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org +.An Nia Alarie Aq Mt nia@NetBSD.org diff --git a/static/netbsd/man3/timezone.3 b/static/netbsd/man3/timezone.3 new file mode 100644 index 00000000..6a202dad --- /dev/null +++ b/static/netbsd/man3/timezone.3 @@ -0,0 +1,75 @@ +.\" $NetBSD: timezone.3,v 1.12 2003/08/07 16:42:58 agc Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)timezone.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd April 19, 1994 +.Dt TIMEZONE 3 +.Os +.Sh NAME +.Nm timezone +.Nd return the timezone abbreviation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Ft char * +.Fn timezone "int zone" "int dst" +.Sh DESCRIPTION +.Bf -symbolic +.\" This interface is available from the compatibility library, libcompat; +This interface is available for compatibility only and will disappear in a +future software release; +it is impossible to reliably map timezone's arguments to a time zone +abbreviation. +See +.Xr ctime 3 ; +see +.Xr tzset 3 +for the new definition of this interface. +.Ef +.Pp +The +.Fn timezone +function returns a pointer to a time zone abbreviation for the specified +.Ar zone +and +.Ar dst +values. +.Ar Zone +is the number of minutes west of GMT and +.Ar dst +is non-zero if daylight savings time is in effect. +.Sh SEE ALSO +.Xr ctime 3 , +.Xr tzset 3 +.Sh HISTORY +A +.Fn timezone +function appeared in +.At v7 . diff --git a/static/netbsd/man3/tmpnam.3 b/static/netbsd/man3/tmpnam.3 new file mode 100644 index 00000000..090632d2 --- /dev/null +++ b/static/netbsd/man3/tmpnam.3 @@ -0,0 +1,261 @@ +.\" $NetBSD: tmpnam.3,v 1.18 2019/09/01 01:23:14 uwe Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93 +.\" +.Dd April 30, 2010 +.Dt TMPFILE 3 +.Os +.Sh NAME +.Nm tempnam , +.Nm tmpfile , +.Nm tmpnam +.Nd temporary file routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn tmpfile void +.Ft char * +.Fn tmpnam "char *str" +.Ft char * +.Fn tempnam "const char *tmpdir" "const char *prefix" +.Sh DESCRIPTION +The +.Fn tmpfile +function +returns a pointer to a stream associated with a file descriptor returned +by the routine +.Xr mkstemp 3 . +The created file is unlinked before +.Fn tmpfile +returns, causing the file to be automatically deleted when the last +reference to it is closed. +The file is opened with the access mode +.Ql w+ . +.Pp +The +.Fn tmpnam +function +returns a pointer to a file name, in the +.Dv P_tmpdir +directory, which +did not reference an existing file at some indeterminate point in the +past. +.Dv P_tmpdir +is defined in the include file +.In stdio.h . +If the argument +.Fa s +is +.Pf non- Dv NULL , +the file name is copied to the buffer it references. +Otherwise, the file name is copied to a static buffer. +In either case, +.Fn tmpnam +returns a pointer to the file name. +.Pp +The buffer referenced by +.Fa s +is expected to be at least +.Dv L_tmpnam +bytes in length. +.Dv L_tmpnam +is defined in the include file +.In stdio.h . +.Pp +The +.Fn tempnam +function +is similar to +.Fn tmpnam , +but provides the ability to specify the directory which will +contain the temporary file and the file name prefix. +.Pp +The environment variable +.Ev TMPDIR +(if set), the argument +.Fa tmpdir +(if +.Pf non- Dv NULL ) , +the directory +.Dv P_tmpdir , +and the directory +.Pa /tmp +are tried, in the listed order, as directories in which to store the +temporary file. +.Pp +The argument +.Fa prefix , +if +.Pf non- Dv NULL , +is used to specify a file name prefix, which will be the +first part of the created file name. +.Fn tempnam +allocates memory in which to store the file name; the returned pointer +may be used as a subsequent argument to +.Xr free 3 . +.Sh RETURN VALUES +The +.Fn tmpfile +function +returns a pointer to an open file stream on success, and a +.Dv NULL +pointer +on error. +.Pp +The +.Fn tmpnam +and +.Fn tempnam +functions +return a pointer to a file name on success, and a +.Dv NULL +pointer +on error. +.Sh ERRORS +The +.Fn tmpfile +function +may fail and set the global variable +.Va errno +for any of the errors specified for the library functions +.Xr fdopen 3 +or +.Xr mkstemp 3 . +.Pp +The +.Fn tmpnam +function +may fail and set +.Va errno +for any of the errors specified for the library function +.Xr mktemp 3 . +.Pp +The +.Fn tempnam +function +may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr malloc 3 +or +.Xr mktemp 3 . +.Sh SEE ALSO +.Xr mkstemp 3 , +.Xr mktemp 3 +.Sh STANDARDS +The +.Fn tmpfile +and +.Fn tmpnam +functions +conform to +.St -ansiC . +All described functions also conform to +.St -p1003.1-2001 , +albeit the +.Fn tempnam +and +.Fn tmpnam +functions have been marked as obsolete in the +.St -p1003.1-2008 +revision. +.Sh BUGS +These interfaces are provided for +.At V +and +.Tn ANSI +compatibility only. +The +.Xr mkstemp 3 +interface is strongly preferred. +.Sh SECURITY CONSIDERATIONS +There are four important problems with these interfaces (as well as +with the historic +.Xr mktemp 3 +interface). +First, there is an obvious race between file name selection and file +creation and deletion: the program is typically written to call +.Fn tmpnam , +.Fn tempnam , +or +.Xr mktemp 3 . +Subsequently, the program calls +.Xr open 2 +or +.Xr fopen 3 +and erroneously opens a file (or symbolic link, or fifo or other +device) that the attacker has placed in the expected file location. +Hence +.Xr mkstemp 3 +is recommended, since it atomically creates the file. +.Pp +Second, most historic implementations provide only a limited number +of possible temporary file names (usually 26) before file names will +start being recycled. +Third, the +.At V +implementations of these functions (and of +.Xr mktemp 3 ) +use the +.Xr access 2 +system call to determine whether or not the temporary file may be created. +This has obvious ramifications for setuid or setgid programs, complicating +the portable use of these interfaces in such programs. +Finally, there is no specification of the permissions with which the +temporary files are created. +.Pp +This implementation of +.Fn tmpfile +does not have these flaws, +and that of +.Fn tmpnam +and +.Fn tempnam +only have the first limitation, but portable software +cannot depend on that. +In particular, the +.Fn tmpfile +interface should not be used in software expected to be used on other systems +if there is any possibility that the user does not wish the temporary file to +be publicly readable and writable. +.Pp +A link-time warning will be issued if +.Fn tmpnam +or +.Fn tempnam +is used, and advises the use of +.Fn mkstemp +instead. diff --git a/static/netbsd/man3/toascii.3 b/static/netbsd/man3/toascii.3 new file mode 100644 index 00000000..e2c0e0f6 --- /dev/null +++ b/static/netbsd/man3/toascii.3 @@ -0,0 +1,83 @@ +.\" $NetBSD: toascii.3,v 1.13 2010/04/30 04:46:18 jruoho Exp $ +.\" +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)toascii.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 30, 2010 +.Dt TOASCII 3 +.Os +.Sh NAME +.Nm toascii +.Nd convert a byte to 7-bit ASCII +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn toascii "int c" +.Sh DESCRIPTION +The +.Fn toascii +function returns the argument with all but the lower 7 bits cleared. +.Sh RETURN VALUES +The +.Fn toascii +function always returns a valid ASCII character. +The result is a non-negative integer in the +range from 0 to 127, inclusive. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr tolower 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn toascii +function conforms to +.St -xpg4 +and +.St -p1003.1-2001 . +The +.St -p1003.1-2008 +revision however marked it as obsolete, noting that +.Fn toascii +cannot be used portably in a localized application. diff --git a/static/netbsd/man3/tolower.3 b/static/netbsd/man3/tolower.3 new file mode 100644 index 00000000..253a55e2 --- /dev/null +++ b/static/netbsd/man3/tolower.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: tolower.3,v 1.14 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tolower.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt TOLOWER 3 +.Os +.Sh NAME +.Nm tolower +.Nd upper case to lower case letter conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn tolower "int c" +.Sh DESCRIPTION +The +.Fn tolower +function converts an upper-case letter to the corresponding lower-case +letter. +.Sh RETURN VALUES +If the argument is an upper-case letter, the +.Fn tolower +function returns the corresponding lower-case letter if there is +one; otherwise the argument is returned unchanged. +.\" In the +.\" .Em ``C'' +.\" locale, +.\" .Fn tolower +.\" maps only the characters for which +.\" .Xr isupper +.\" is true to the corresponding characters for which +.\" .Xr islower +.\" is true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr toupper 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn tolower +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn tolower +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/toupper.3 b/static/netbsd/man3/toupper.3 new file mode 100644 index 00000000..b927a546 --- /dev/null +++ b/static/netbsd/man3/toupper.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: toupper.3,v 1.17 2008/04/17 16:25:36 apb Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)toupper.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd April 17, 2008 +.Dt TOUPPER 3 +.Os +.Sh NAME +.Nm toupper +.Nd lower case to upper case letter conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ctype.h +.Ft int +.Fn toupper "int c" +.Sh DESCRIPTION +The +.Fn toupper +function converts a lower-case letter to the corresponding +upper-case letter. +.Sh RETURN VALUES +If the argument is a lower-case letter, the +.Fn toupper +function returns the corresponding upper-case letter if there is +one; otherwise the argument is returned unchanged. +.\" In the +.\" .Em ``C'' +.\" locale, +.\" .Fn toupper +.\" maps only the characters for which +.\" .Xr islower +.\" is true to the corresponding characters for which +.\" .Xr isupper +.\" is true. +.Sh SEE ALSO +.Xr ctype 3 , +.Xr isalnum 3 , +.Xr isalpha 3 , +.Xr isascii 3 , +.Xr iscntrl 3 , +.Xr isdigit 3 , +.Xr isgraph 3 , +.Xr islower 3 , +.Xr isprint 3 , +.Xr ispunct 3 , +.Xr isspace 3 , +.Xr isupper 3 , +.Xr isxdigit 3 , +.Xr stdio 3 , +.Xr toascii 3 , +.Xr ascii 7 +.Sh STANDARDS +The +.Fn toupper +function conforms to +.St -ansiC . +.Sh CAVEATS +The argument to +.Fn toupper +must be +.Dv EOF +or representable as an +.Vt unsigned char ; +otherwise, the behavior is undefined. +See the +.Sx CAVEATS +section of +.Xr ctype 3 +for more details. diff --git a/static/netbsd/man3/towctrans.3 b/static/netbsd/man3/towctrans.3 new file mode 100644 index 00000000..7772755a --- /dev/null +++ b/static/netbsd/man3/towctrans.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: towctrans.3,v 1.6 2005/06/27 14:18:36 wiz Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 4, 2003 +.Dt TOWCTRANS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm towctrans +.Nd convert a wide character with a specified map +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wctype.h +.Ft wint_t +.Fn towctrans "wint_t wc" "wctrans_t charmap" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn towctrans +function converts a wide character +.Fa wc +with a character mapping +.Fa charmap . +.Pp +The behaviour of +.Fn towctrans +is undefined if the +.Fn towctrans +function is called with an invalid +.Fa charmap +(changes of +.Dv LC_CTYPE +category invalidate +.Fa charmap ) +or invalid wide character +.Fa wc . +.Pp +The behaviour of +.Fn towctrans +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn towctrans +returns the resulting character of the conversion. +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr iswctype 3 , +.Xr setlocale 3 , +.Xr wctrans 3 , +.Xr wctype 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn towctrans +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/towlower.3 b/static/netbsd/man3/towlower.3 new file mode 100644 index 00000000..a9b739ab --- /dev/null +++ b/static/netbsd/man3/towlower.3 @@ -0,0 +1,70 @@ +.\" $NetBSD: towlower.3,v 1.8 2017/10/25 16:07:34 abhinav Exp $ +.\" +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)tolower.3 5.2 (Berkeley) 6/29/91 +.\" +.Dd December 22, 2000 +.Dt TOWLOWER 3 +.Os +.Sh NAME +.Nm towlower , +.Nm towupper +.Nd wide character case letter conversion utilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wctype.h +.Ft wint_t +.Fn towlower "wint_t wc" +.Ft wint_t +.Fn towupper "wint_t wc" +.Sh DESCRIPTION +The +.Fn towlower +function converts an upper-case wide character to the corresponding lower-case +letter. +The +.Fn towupper +function converts an lower-case wide character to the corresponding upper-case +letter. +.Sh RETURN VALUES +If the argument is an upper/lower-case letter, the +.Fn tolower +function returns the corresponding counterpart if there is +one; otherwise the argument is returned unchanged. +.Sh SEE ALSO +.Xr tolower 3 , +.Xr toupper 3 +.Sh STANDARDS +The functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/tpmUnsealFile.3 b/static/netbsd/man3/tpmUnsealFile.3 new file mode 100644 index 00000000..1fda48fc --- /dev/null +++ b/static/netbsd/man3/tpmUnsealFile.3 @@ -0,0 +1,57 @@ +.\" Copyright (C) 2005, 2006 International Business Machines Corporation +.\" +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "tpm_sealdata" 3 "2005-08-10" "TPM Management" +.ce 1 +TPM Management - tpmUnsealFile, tpmUnsealShred, tpmUnsealStrerror +.SH NAME +tpmUnsealFile, tpmUnsealShred, tpmUnsealStrerror - unseal routines +.SH "SYNOPSIS" +.ad l +.hy 0 +.B #include <tpm_unseal/tpm_unseal.h> +.sp +.B int tpmUnsealFile(char* file, char** data, int* size); +.br +.B void tpmUnsealShred(char* data, int size); +.br +.B char* tpmUnsealStrerror(int rc); +.br + +.SH "DESCRIPTION" +.PP +The functions in the tpmUnseal family allow access to a piece of sensitive data that has been sealed to the TPM configuration of a given system if the conditions are right, that is the SRK has not changed and the PCRS (if any) specified at seal time are of the appropriate value. + +The tpmUnsealFile function returns the contents of the file unsealed in the data buffer. The memory at *data must be freed by the caller. + +The tpmUnsealShred function will zero and free the memory. + +The tpmUnsealStrerror function will convert the return code from tpmUnsealFile into a human comprehensible string using and internal errno variable. + +.SH "Return Value" +The tpmUnsealFile function returns 0 on success and a negative number on error. +The tpmUnsealStrerror function returns the error string on success and the empty string on an error. + +.SH "SEE ALSO" +.PP +\fBtpm_sealdata\fR(1) + +.SH "REPORTING BUGS" +Report bugs to <trousers-users@lists.sourceforge.net> diff --git a/static/netbsd/man3/tpmUnsealShred.3 b/static/netbsd/man3/tpmUnsealShred.3 new file mode 100644 index 00000000..ffa50c3e --- /dev/null +++ b/static/netbsd/man3/tpmUnsealShred.3 @@ -0,0 +1 @@ +.so man3/tpmUnsealFile.3 diff --git a/static/netbsd/man3/tpmUnsealStrerror.3 b/static/netbsd/man3/tpmUnsealStrerror.3 new file mode 100644 index 00000000..ffa50c3e --- /dev/null +++ b/static/netbsd/man3/tpmUnsealStrerror.3 @@ -0,0 +1 @@ +.so man3/tpmUnsealFile.3 diff --git a/static/netbsd/man3/trunc.3 b/static/netbsd/man3/trunc.3 new file mode 100644 index 00000000..9d28520e --- /dev/null +++ b/static/netbsd/man3/trunc.3 @@ -0,0 +1,79 @@ +.\" $NetBSD: trunc.3,v 1.7 2013/11/13 22:11:52 wiz Exp $ +.\" +.\" Copyright (c) 2004, 2005 David Schultz <das@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/msun/man/trunc.3,v 1.3 2005/06/15 19:04:04 ru Exp $ +.\" +.Dd November 13, 2013 +.Dt TRUNC 3 +.Os +.Sh NAME +.Nm trunc , +.Nm truncf , +.Nm truncl +.Nd "nearest integral value with magnitude less than or equal to |x|" +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In math.h +.Ft double +.Fn trunc "double x" +.Ft float +.Fn truncf "float x" +.Ft "long double" +.Fn truncl "long double x" +.Sh DESCRIPTION +The +.Fn trunc , +.Fn truncf , +and +.Fn truncl +functions return the nearest integral value with magnitude less than +or equal to +.Pf | Fa x Ns | . +They are equivalent to +.Fn rint , +.Fn rintf , +and +.Fn rintl +respectively, in the +.Dv FP_RZ +rounding mode. +.Sh SEE ALSO +.Xr ceil 3 , +.Xr floor 3 , +.Xr fpsetround 3 , +.Xr math 3 , +.Xr nextafter 3 , +.Xr rint 3 , +.Xr round 3 +.Sh STANDARDS +The +.Fn trunc , +.Fn truncf , +and +.Fn truncl +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/tsearch.3 b/static/netbsd/man3/tsearch.3 new file mode 100644 index 00000000..5567f4b0 --- /dev/null +++ b/static/netbsd/man3/tsearch.3 @@ -0,0 +1,141 @@ +.\" $NetBSD: tsearch.3,v 1.12 2010/04/30 10:09:23 jruoho Exp $ +.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" OpenBSD: tsearch.3,v 1.2 1998/06/21 22:13:49 millert Exp +.\" +.Dd April 30, 2010 +.Dt TSEARCH 3 +.Os +.Sh NAME +.Nm tsearch, tfind, tdelete, twalk +.Nd manipulate binary search trees +.Sh SYNOPSIS +.In search.h +.Ft void * +.Fn tdelete "const void * restrict key" "void ** restrict rootp" "int (*compar) (const void *, const void *)" +.Ft void * +.Fn tfind "const void *key" "const void * const *rootp" "int (*compar) (const void *, const void *)" +.Ft void * +.Fn tsearch "const void *key" "void **rootp" "int (*compar) (const void *, const void *)" +.Ft void +.Fn twalk "const void *root" "void (*action) (const void *, VISIT, int)" +.Sh DESCRIPTION +The +.Fn tdelete , +.Fn tfind , +.Fn tsearch , +and +.Fn twalk +functions manage binary search trees based on algorithms T and D +from Knuth (6.2.2). +The comparison function passed in by +the user has the same style of return values as +.Xr strcmp 3 . +.Pp +.Fn tfind +searches for the datum matched by the argument +.Fa key +in the binary tree rooted at +.Fa rootp , +returning a pointer to the datum if it is found and NULL +if it is not. +.Pp +.Fn tsearch +is identical to +.Fn tfind +except that if no match is found, +.Fa key +is inserted into the tree and a pointer to it is returned. +If +.Fa rootp +points to a NULL value a new binary search tree is created. +.Pp +.Fn tdelete +deletes a node from the specified binary search tree and returns +a pointer to the parent of the node to be deleted. +It takes the same arguments as +.Fn tfind +and +.Fn tsearch . +If the node to be deleted is the root of the binary search tree, +.Fa rootp +will be adjusted. +.Pp +.Fn twalk +walks the binary search tree rooted in +.Va root +and calls the function +.Fa action +on each node. +.Fa Action +is called with three arguments: a pointer to the current node, +a value from the enum +.Sy "typedef enum { preorder, postorder, endorder, leaf } VISIT;" +specifying the traversal type, and a node level (where level +zero is the root of the tree). +.Sh RETURN VALUES +The +.Fn tsearch +function returns NULL if allocation of a new node fails (usually +due to a lack of free memory). +.Pp +.Fn tfind , +.Fn tsearch , +and +.Fn tdelete +return NULL if +.Fa rootp +is NULL or the datum cannot be found. +.Pp +The +.Fn twalk +function returns no value. +.Sh SEE ALSO +.Xr bsearch 3 , +.Xr hsearch 3 , +.Xr lsearch 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.Sh CAVEATS +The +.St -p1003.1-2001 +standard does not specify what value should be returned when deleting +the root node. +Since implementations vary, user of +.Fn tdelete +should not rely on any specific behaviour. +The +.St -p1003.1-2008 +revision tried to clarify the issue with the following wording: +.Do +the +.Fn tdelete +function shall return a pointer to the parent of the deleted node, +or an unspecified non-NULL pointer if the deleted node was the root node, or a +.Dv NULL +pointer if the node is not found +.Dc . diff --git a/static/netbsd/man3/tsig.3 b/static/netbsd/man3/tsig.3 new file mode 100644 index 00000000..b9f9c831 --- /dev/null +++ b/static/netbsd/man3/tsig.3 @@ -0,0 +1,241 @@ +.\" $NetBSD: tsig.3,v 1.1.1.2 2012/09/09 16:07:44 christos Exp $ +.\" +.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Id: tsig.3,v 1.3 2009/01/22 23:49:23 tbox Exp +.\" +.Dd January 1, 1996 +.Os BSD 4 +.Dt TSIG @SYSCALL_EXT@ +.Sh NAME +.Nm ns_sign , +.Nm ns_sign_tcp , +.Nm ns_sign_tcp_init , +.Nm ns_verify , +.Nm ns_verify_tcp , +.Nm ns_verify_tcp_init , +.Nm ns_find_tsig +.Nd TSIG system +.Sh SYNOPSIS +.Ft int +.Fo ns_sign +.Fa "u_char *msg" +.Fa "int *msglen" +.Fa "int msgsize" +.Fa "int error" +.Fa "void *k" +.Fa "const u_char *querysig" +.Fa "int querysiglen" +.Fa "u_char *sig" +.Fa "int *siglen" +.Fa "time_t in_timesigned" +.Fc +.Ft int +.Fn ns_sign_tcp "u_char *msg" "int *msglen" "int msgsize" "int error" \ + "ns_tcp_tsig_state *state" "int done" +.Ft int +.Fn ns_sign_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \ + "ns_tcp_tsig_state *state" +.Ft int +.Fo ns_verify +.Fa "u_char *msg" +.Fa "int *msglen" +.Fa "void *k" +.Fa "const u_char *querysig" +.Fa "int querysiglen" +.Fa "u_char *sig" +.Fa "int *siglen" +.Fa "time_t in_timesigned" +.Fa "int nostrip" +.Fc +.Ft int +.Fn ns_verify_tcp "u_char *msg" "int *msglen" "ns_tcp_tsig_state *state" \ + "int required" +.Ft int +.Fn ns_verify_tcp_init "void *k" "const u_char *querysig" "int querysiglen" \ + "ns_tcp_tsig_state *state" +.Ft u_char * +.Fn ns_find_tsig "u_char *msg" "u_char *eom" +.Sh DESCRIPTION +The TSIG routines are used to implement transaction/request security of +DNS messages. +.Pp +.Fn ns_sign +and +.Fn ns_verify +are the basic routines. +.Fn ns_sign_tcp +and +.Fn ns_verify_tcp +are used to sign/verify TCP messages that may be split into multiple packets, +such as zone transfers, and +.Fn ns_sign_tcp_init , +.Fn ns_verify_tcp_init +initialize the state structure necessary for TCP operations. +.Fn ns_find_tsig +locates the TSIG record in a message, if one is present. +.Pp +.Fn ns_sign +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv msgsize +the size of the buffer containing the DNS message on input +.It Dv error +the value to be placed in the TSIG error field +.It Dv key +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv sig +a buffer to be filled with the generated signature +.It Dv siglen +the length of the signature buffer on input, the signature length on output +.El +.Pp +.Fn ns_sign_tcp +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv msgsize +the size of the buffer containing the DNS message on input +.It Dv error +the value to be placed in the TSIG error field +.It Dv state +the state of the operation +.It Dv done +non-zero value signifies that this is the last packet +.El +.Pp +.Fn ns_sign_tcp_init +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv k +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv state +the state of the operation, which this initializes +.El +.Pp +.Fn ns_verify +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv key +the (DST_KEY *) to sign the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv sig +a buffer to be filled with the signature contained +.It Dv siglen +the length of the signature buffer on input, the signature length on output +.It Dv nostrip +non-zero value means that the TSIG is left intact +.El +.Pp +.Fn ns_verify_tcp +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message, which will be modified +.It Dv msglen +the length of the DNS message, on input and output +.It Dv state +the state of the operation +.It Dv required +non-zero value signifies that a TSIG record must be present at this step +.El +.Pp +.Fn ns_verify_tcp_init +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv k +the (DST_KEY *) to verify the data +.It Dv querysig +for a response, the signature contained in the query +.It Dv querysiglen +the length of the query signature +.It Dv state +the state of the operation, which this initializes +.El +.Pp +.Fn ns_find_tsig +.Bl -tag -width "in_timesigned" -compact -offset indent +.It Dv msg +the incoming DNS message +.It Dv msglen +the length of the DNS message +.El +.Sh RETURN VALUES +.Fn ns_find_tsig +returns a pointer to the TSIG record if one is found, and NULL otherwise. +.Pp +All other routines return 0 on success, modifying arguments when necessary. +.Pp +.Fn ns_sign +and +.Fn ns_sign_tcp +return the following errors: +.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent +.It Dv (-1) +bad input data +.It Dv (-ns_r_badkey) +The key was invalid, or the signing failed +.It Dv NS_TSIG_ERROR_NO_SPACE +the message buffer is too small. +.El +.Pp +.Fn ns_verify +and +.Fn ns_verify_tcp +return the following errors: +.Bl -tag -width "NS_TSIG_ERROR_NO_SPACE" -compact -offset indent +.It Dv (-1) +bad input data +.It Dv NS_TSIG_ERROR_FORMERR +The message is malformed +.It Dv NS_TSIG_ERROR_NO_TSIG +The message does not contain a TSIG record +.It Dv NS_TSIG_ERROR_ID_MISMATCH +The TSIG original ID field does not match the message ID +.It Dv (-ns_r_badkey) +Verification failed due to an invalid key +.It Dv (-ns_r_badsig) +Verification failed due to an invalid signature +.It Dv (-ns_r_badtime) +Verification failed due to an invalid timestamp +.It Dv ns_r_badkey +Verification succeeded but the message had an error of BADKEY +.It Dv ns_r_badsig +Verification succeeded but the message had an error of BADSIG +.It Dv ns_r_badtime +Verification succeeded but the message had an error of BADTIME +.El +.Pp +.Sh SEE ALSO +.Xr resolver 3 . +.Sh AUTHORS +Brian Wellington, TISLabs at Network Associates +.\" .Sh BUGS diff --git a/static/netbsd/man3/tss.3 b/static/netbsd/man3/tss.3 new file mode 100644 index 00000000..7c924de3 --- /dev/null +++ b/static/netbsd/man3/tss.3 @@ -0,0 +1,157 @@ +.\" $NetBSD: tss.3,v 1.2 2019/04/27 10:57:11 wiz Exp $ +.\" +.\" Copyright (c) 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Kamil Rytarowski. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 16, 2016 +.Dt TSS 3 +.Os +.Sh NAME +.Nm tss +.Nd thread-specific storage functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In threads.h +.Vt "typedef" "void" "(*tss_dtor_t)" "(void *)" +.Ft int +.Fn tss_create "tss_t *key" "tss_dtor_t dtor" +.Ft void +.Fn tss_delete "tss_t key" +.Ft void * +.Fn tss_get "tss_t key" +.Ft int +.Fn tss_set "tss_t key" "void *val" +.Vt #define TSS_DTOR_ITERATIONS /* implementation specified */ +.Sh DESCRIPTION +There are two groups of storage in C programs: +.Bl -dash +.It +local storage, +.It +global storage. +.El +.Pp +Multithreaded programs in C add the third group +.Sy thread-specific storage . +This data is private to thread and every entry of this type has an associated +.Dv tss_t +opaque key that is global to all threads in the process. +A thread using the +.Dv tss_t * +pointer accesses private data. +.Pp +The +.Fn tss_create +function creates a thread-specific storage with the +.Fa key +handler with optional destructor +.Fa dtor . +If the +.Fa dtor +parameter is not +.Dv NULL , +then specified appropriate destructor will be called on thread termination. +The destructor is not called if a thread called the +.Fn tss_delete +function for the specified +.Fa key . +If, after all the destructors have been called for all +.Pf non- Dv NULL +values with associated destructors, +there are still some +.Pf non- Dv NULL +values with associated destructors, +then the process is repeated. +If, after at least +.Dv TSS_DTOR_ITERATIONS +iterations of destructor calls for outstanding +.Pf non- Dv NULL +values, there are still some +.Pf non- Dv NULL +values with associated destructors, the +.Nx +implementation stops calling further destructors. +The +.Xr thrd_exit 3 +function must not be called from a destructor. +.Pp +The +.Fn tss_delete +function frees resources used by the thread-specific storage identified by the +.Fa key +object. +This function can be called inside the +.Fa dtor +destructor, however the destructor is not called by +.Fn tss_delete . +.Pp +The +.Fn tss_get +and +.Fn tss_set +functions are used to get and set thread-specific storage. +.Sh RETURN VALUES +The +.Fn tss_create +function returns +.Dv thrd_success +on success, otherwise +.Dv thrd_error +on failure. +.Pp +The +.Fn tss_delete +function returns no value. +.Pp +The +.Fn tss_get +returns pointer to thread-specific storage on success or +.Dv NULL +on failure. +.Pp +The +.Fn tss_set +function returns +.Dv thrd_success +on success, otherwise +.Dv thrd_error +on failure. +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr threads 3 +.Sh STANDARDS +The +.Nm +interface conforms to +.St -isoC-2011 . +.Sh HISTORY +This interface first appeared in +.Nx 9 . +.Sh AUTHORS +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org diff --git a/static/netbsd/man3/ttyaction.3 b/static/netbsd/man3/ttyaction.3 new file mode 100644 index 00000000..6549d549 --- /dev/null +++ b/static/netbsd/man3/ttyaction.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: ttyaction.3,v 1.16 2021/03/21 23:29:36 mrg Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gordon W. Ross. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 4, 2010 +.Dt TTYACTION 3 +.Os +.Sh NAME +.Nm ttyaction +.Nd ttyaction utility function +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn ttyaction "char *ttyname" "char *action" "char *username" +.Sh DESCRIPTION +The +.Fn ttyaction +function is used by +.Xr login 1 , +.Xr getty 8 , +.Xr telnetd 8 +and +.Xr rlogind 8 +to execute site-specific commands +when a login session begins and ends. +.Pp +The +.Fn ttyaction +function scans the +.Pa /etc/ttyaction +file for any records that match the current +.Fa ttyname +and +.Fa action +parameters, and for each matching record, +runs the shell command shown in that record. +The record format is described in +.Xr ttyaction 5 . +The parameter +.Fa username +is the name of the new owner of the +.Fa ttyname +device. +Note that the +.Fa ttyname +parameter may be passed as a fully qualified pathname, and the +.Fn ttyaction +function will skip the leading "/dev/" part of the string. +(This is a convenience for login and getty.) +.Sh RETURN VALUES +.Fn ttyaction +returns the status of the last command it executed, +or zero if no matching commands were found. +.Sh FILES +.Bl -tag -width /etc/ttyaction -compact +.It Pa /dev/\(** +.It Pa /etc/ttyaction +.El +.Sh SEE ALSO +.Xr ttyaction 5 +.Sh HISTORY +The +.Fn ttyaction +function appeared in +.Nx 1.3 . +.Sh AUTHORS +.An Gordon W. Ross +.Aq gwr@NetBSD.org , +.An Chris G. Demetriou +.Aq cgd@NetBSD.org , +.An Ty Sarna +.Aq tsarna@NetBSD.org . +.Sh BUGS +There should be some +.Em other +mechanism to allow selection of different access control policies +on a per-line basis. +It has been suggested that the same +.Fn ttyaction +mechanism should also be used for determining access control, but +it was decided (after much discussion) that +.Fn ttyaction +should only describe actions to be performed +.Em after +the system has decided to change the ownership of some tty. +Access control policies will be handled by a separate mechanism. diff --git a/static/netbsd/man3/ttymsg.3 b/static/netbsd/man3/ttymsg.3 new file mode 100644 index 00000000..8fd2e06b --- /dev/null +++ b/static/netbsd/man3/ttymsg.3 @@ -0,0 +1,68 @@ +.\" $NetBSD: ttymsg.3,v 1.13 2013/01/16 06:44:27 wiz Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 15, 2013 +.Dt TTYMSG 3 +.Os +.Sh NAME +.Nm ttymsg +.Nd ttymsg utility function +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In util.h +.Ft char * +.Fn ttymsg "struct iovec *iov" "int iovlen" "const char *tty" "int tmout" +.Sh DESCRIPTION +The +.Fn ttymsg +function is used by +programs such as +.Xr talkd 8 , +.Xr syslogd 8 , +.Xr wall 1 , +etc., to display the contents of a uio structure on a terminal. +.Fn ttymsg +forks and finishes in the child if the write would block after +waiting up to +.Fa tmout +seconds. +.Sh RETURN VALUES +.Fn ttymsg +returns a pointer to an error string on unexpected +error; the string is not newline-terminated. +Various "normal" errors are +ignored (exclusive-use, lack of permission, etc.). +.Sh SEE ALSO +.Xr writev 2 +.Sh BUGS +.Nm +could grow some flags and a username/uid who is the expected owner +of the tty. +If the flags say so then the owner should be checked against the tty +owner, and the message should not be sent if there is a mismatch. +Also another flag could say check against group writable, and don't +send a message. diff --git a/static/netbsd/man3/ttyname.3 b/static/netbsd/man3/ttyname.3 new file mode 100644 index 00000000..eddfa017 --- /dev/null +++ b/static/netbsd/man3/ttyname.3 @@ -0,0 +1,204 @@ +.\" $NetBSD: ttyname.3,v 1.24 2012/06/03 21:42:46 joerg Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 1, 2012 +.Dt TTYNAME 3 +.Os +.Sh NAME +.Nm ttyname , +.Nm ttyname_r , +.Nm isatty , +.Nm ttyslot +.Nd get name of associated terminal (tty) from file descriptor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn ttyname "int fd" +.Ft int +.Fn ttyname_r "int fd" "char *buf" "size_t len" +.Ft int +.Fn isatty "int fd" +.In stdlib.h +.Ft int +.Fn ttyslot "void" +.Sh DESCRIPTION +These functions operate on the system file descriptors for terminal +type devices. +These descriptors are not related to the standard +.Tn I/O +.Dv FILE +typedef, but refer to the special device files found in +.Pa /dev +and named +.Pa /dev/tty Ns Em xx +and for which an entry exists in the initialization file +.Pa /etc/ttys +(see +.Xr ttys 5 ) , +or for pseudo-terminal devices created in ptyfs and named +.Pa /dev/pts/ Ns Em n . +.Pp +The +.Fn isatty +function +determines if the file descriptor +.Fa fd +refers to a valid terminal type device. +.Pp +The +.Fn ttyname +function gets the related device name of a file descriptor for +which +.Fn isatty +is true. +The +.Fn ttyname_r +is the reentrant version of the above, and it places the results in +.Fa buf . +If there is not enough space to place the results (indicated by +.Fa len ) , +then it returns an error. +.Pp +The +.Fn ttyslot +function +fetches the current process' control terminal number from the +.Xr ttys 5 +file entry. +If the terminal is a pseudo-terminal, and there is no special entry +in the +.Xr ttys 5 +file for it, the slot number returned is 1 + (last slot number) + +minor(tty). +This will return a consistent and unique number for each pseudo-terminal +device without requiring one to enumerate all of them in +.Xr ttys 5 . +.Sh IMPLEMENTATION NOTES +As an optimisation, these functions attempt to obtain information about +all devices from the +.Pa /var/run/dev.cdb +database, if it exists. +If the database exists but is out of date, then these functions +may produce incorrect results. +The database should be updated using the +.Xr dev_mkdb 8 +command. +.Sh RETURN VALUES +The +.Fn ttyname +function returns the NUL-terminated name if the device is found and +.Fn isatty +is true; otherwise +a +.Dv NULL +pointer is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn ttyname_r +functions returns 0 on success and an error code on failure. +.Pp +The +.Fn isatty +function returns 1 if +.Fa fd +is associated with a terminal device; otherwise it returns 0 and +.Va errno +is set to indicate the error. +.Pp +The +.Fn ttyslot +function +returns the unit number of the device file if found; otherwise +the value zero is returned. +.Sh FILES +.Bl -tag -width /etc/ttys -compact +.It Pa /dev/\(** +.It Pa /etc/ttys +.El +.Sh ERRORS +The +.Fn ttyname , +.Fn ttyname_r , +and +.Fn isatty +functions will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er ENOTTY +The +.Fa fd +argument does not refer to a terminal device. +.El +.Pp +The +.Fn ttyname_r +function will also fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The terminal device is not found. +This can happen if the device node has been removed after it was opened. +.It Bq Er ERANGE +The buffer provided is not large enough to fit the result. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ttys 5 , +.Xr dev_mkdb 8 +.Sh STANDARDS +The +.Fn ttyname +and +.Fn isatty +functions conform to +.St -p1003.1-90 . +.Sh HISTORY +.Fn isatty , +.Fn ttyname , +and +.Fn ttyslot +functions appeared in +.At v7 . +.\" Use of the .Pa /var/run/dev.cdb file was added in netBSD 6.0. +.Sh BUGS +The +.Fn ttyname +function leaves its result in an internal static object and returns +a pointer to that object. +Subsequent calls to +.Fn ttyname +will modify the same object. diff --git a/static/netbsd/man3/tzset.3 b/static/netbsd/man3/tzset.3 new file mode 100644 index 00000000..18853341 --- /dev/null +++ b/static/netbsd/man3/tzset.3 @@ -0,0 +1,438 @@ +.\" $NetBSD: tzset.3,v 1.47 2026/03/08 21:04:54 christos Exp $ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.Dd March 8, 2026 +.Dt TZSET 3 +.Os +.Sh NAME +.Nm tzset , +.Nm tzalloc , +.Nm tzgetname , +.Nm tzgetgmtoff , +.Nm tzfree +.Nd initialize time conversion information +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft timezone_t +.Fn tzalloc "const char *zone" +.Ft void +.Fn tzfree "timezone_t restrict tz" +.Ft const char * +.Fn tzgetname "timezone_t restrict tz" "int isdst" +.Ft long +.Fn tzgetgmtoff "timezone_t restrict tz" "int isdst" +.Ft void +.Fn tzset "void" +.Sh DESCRIPTION +The +.Fn tzalloc +function takes as an argument a timezone name and returns a +.Ft timezone_t +object suitable to be used in the +.Fn ctime_rz , +.Fn localtime_rz , +and +.Fn mktime_z +functions. +.Pp +If +.Ar zone +is not a valid timezone description, or if the object cannot be allocated, +.Fn tzalloc +returns a +.Dv NULL +pointer and sets +.Va errno . +.Pp +A +.Dv NULL +pointer may be passed to +.Fn tzalloc +instead of a timezone name, to refer to the current system timezone. +An empty timezone string indicates Coordinated Universal Time +.Pq Tn UTC . +.Pp +Note that instead of setting the environment variable +.Va TZ , +and globally changing the behavior of the calling program, one can use +multiple timezones at the same time by using separate +.Ft timezone_t +objects allocated by +.Fn tzalloc +and calling the +.Dq z +variants of the functions. +The +.Fn tzfree +function deallocates +.Fa tz , +which was previously allocated by +.Fn tzalloc . +This invalidates any +.Ft tm_zone +pointers that +.Fa tz +was used to set. +The function +.Fn tzgetname +returns the name for the given +.Fa tz . +If +.Fa isdst +is +.Va 0 , +the call is equivalent to +.Va tzname[0] . +If +.Fa isdst +is set to +.Va 1 +the call is equivalent to +.Va tzname[1] . +The return values for both +.Fn tzgetname +and +.Fn tzgmtoff +correspond to the latest time for which data is available, even if that +refers to a future time. +Finally, the +.Fn tzgetgmtoff +function acts like +.Fn tzgetname +only it returns the offset in seconds from GMT for the timezone. +If there is no match, then +.Dv \-1 +is returned and +.Va errno +is set to +.Er ESRCH . +The +.Fn tzset +function acts like +.Dv tzalloc(getenv("TZ")) , +except it saves any resulting timezone object into internal +storage that is accessed by +.Fn localtime , +.Fn localtime_r , +and +.Fn mktime . +The anonymous shared timezone object is freed by the next call to +.Fn tzset . +If the implied call to +.Fn tzalloc +fails, +.Fn tzset +falls back on Universal Time (UT). +If +.Ev TZ +is +.Dv NULL , +the best available approximation to local (wall clock) time, as +specified by the +.Xr tzfile 5 +format file +.Pa /etc/localtime +is used by +.Xr localtime 3 . +If +.Ev TZ +appears in the environment but its value is the empty string, +UT is used, with the abbreviation +.Dq UTC +and without leap second correction; please see +.Xr ctime 3 . +If +.Ev TZ +is nonnull and nonempty: +.Bl -dash +.It +if the value begins with a colon, it is used as a pathname of a file +from which to read the time conversion information; +.It +if the value does not begin with a colon, it is first used as the +pathname of a file from which to read the time conversion information, +and, if that file cannot be read, is used directly as a specification +of the time conversion information. +.El +.Pp +When +.Ev TZ +is used as a pathname, if it begins with a slash, it is used as an +absolute pathname; otherwise, it is used as a pathname relative to +.Pa /usr/share/zoneinfo . +The file must be in the format specified in +.Xr tzfile 5 . +.Pp +When +.Ev TZ +is used directly as a specification of the time conversion information, +it must have the following syntax (spaces inserted for clarity): +.Sm off +.Bd -literal -offset indent +.Cm std Cm offset Oo Cm dst Oo Cm offset Oc Oo , Cm rule Oc Oc +.Ed +.Sm on +.Pp +where: +.Bl -tag -width "std and dst" -compact +.It Cm std No and Cm dst +Three or more bytes that are the designation for the standard +.Cm ( std ) +or the alternative +.Cm ( dst +such as daylight saving time) +timezone. +Only +.Cm std +is required; if +.Cm dst +is missing, then daylight saving time does not apply in this locale. +Upper- and lowercase letters are explicitly allowed. +Any characters except a leading colon (:), digits, comma (,), minus (-), +plus (+), and NUL bytes are allowed. +Alternatively, a designation can be surrounded by angle brackets +.Dv < +and +.Dv > ; +in this case, the designation can contain any characters other than +.Dv > +and +.Dv NUL . +.It Cm offset +Indicates the value one must add to the local time to arrive at +Coordinated Universal Time. +The +.Cm offset +has the form: +.Sm off +.Bd -literal -offset indent +.Cm hh Oo +.Cm :mm Oo +.Cm :ss Oc Oc +.Ed +.Sm on +.Pp +The minutes +.Cm ( mm ) +and seconds +.Cm ( ss ) +are optional. +The hour +.Cm ( hh ) +is required and may be a single digit. +The +.Cm offset +following +.Cm std +is required. +If no +.Cm offset +follows +.Cm dst , +daylight saving time is assumed to be one hour ahead of standard time. +One or more digits may be used; the value is always interpreted as a +decimal number. +The hour must be between zero and 24, and the minutes (and +seconds) \(en if present \(en between zero and 59. +If preceded by a +.Dq - +the timezone shall be east of the Prime Meridian; otherwise it shall be +west (which may be indicated by an optional preceding +.Dq + ) . +.It Cm rule +Indicates when to change to and back from daylight saving time. +The +.Cm rule +has the form: +.Sm off +.Bd -literal -offset indent +.Xo +.Cm date No / +.Cm time , +.Cm date No / +.Cm time +.Xc +.Ed +.Sm on +.Pp +where the first +.Cm date +describes when the change from standard to daylight saving time occurs and the +second +.Cm date +describes when the change back happens. +Each +.Cm time +field describes when, in current local time, the change to the other +time is made. +As an extension to POSIX, daylight saving is assumed to be in effect +all year if it begins January 1 at 00:00 and ends December 31 at +24:00 plus the difference between daylight saving and standard time, +leaving no room for standard time in the calendar. +The format of +.Fa date +is one of the following: +.Bl -tag -width "The Julian day" -compact +.It Cm J Ns Ar n +The Julian day +.Ar n +(1 \*[Le] +.Ar n +\*[Le] 365). +Leap days are not counted; that is, in all years \(en including leap +years \(en February 28 is day 59 and March 1 is day 60. +It is impossible to explicitly refer to the occasional February 29. +.It Ar n +The zero-based Julian day (0\ \*[Le] +.Ar n +\*[Le]\ 365). +Leap days are counted, and it is possible to refer to +February 29. +.Sm off +.It Cm M Ns Ar m . Ar n . Ar d +.Sm on +The +.Ar d Ns 'th +day +(0 \*[Le] +.Ar d +\*[Le]\ 6) of week +.Ar n +of month +.Ar m +of the year +(1 \*[Le] +.Ar n +\*[Le]\ 5, 1 \*[Le] +.Ar m +\*[Le]\ 12, where week 5 means +.Dq the\ last Ar d No day\ in\ month Ar m +which may occur in either the fourth or the fifth week). +Week 1 is the first week in which the +.Ar d Ns 'th +day occurs. +Day zero is Sunday. +.El +The +.Cm time +has the same format as +.Cm offset +except that POSIX does not allow a leading sign +.Dq - +or +.Dq + +is allowed. +As an extension to POSIX, the hours part of +.Cm time +can range from \-167 through 167; this allows for unusual rules such as +.Dq the Saturday before the first Sunday of March . +The default, if +.Cm time +is not given, is +.Cm 02:00:00 . +.El +.Pp +Here are some examples of +.Va TZ +values that directly specify the timezone rules; they use some of the +extensions to POSIX. +.Bl -tag -width 6n +.It EST5 +stands for US Eastern Standard +Time (EST), 5 hours behind UT, without daylight saving. +.It FJT\-12FJST,M11.1.0,M1.3.4/75 +.It <+12>\-12<+13>,M11.1.0,M1.2.1/147 +stands for Fiji time, 12 hours ahead +of UT, springing forward on November's first Sunday at 02:00, and +falling back on January's second Monday at 147:00 (i.e., 03:00 on the +first Sunday on or after January 14). +The abbreviations for standard and daylight saving time are +.Qq +12 +and +.Qq +13 . +.It IST\-2IDT,M3.4.4/26,M10.5.0 +stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), +2 hours ahead of UT, springing forward on March's fourth +Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March +23), and falling back on October's last Sunday at 02:00. +.It <\-04>4<\-03>,J1/0,J365/25 +stands for permanent daylight saving time, 3 hours behind UT with +abbreviation +.Qq \-03 . +There is a dummy fall-back transition on December 31 at 25:00 daylight +saving time (i.e., 24:00 standard time, equivalent to January 1 at +00:00 standard time), and a simultaneous spring-forward transition on +January 1 at 00:00 standard time, so daylight saving time is in effect +all year and the initial +.Em <\-04> +is a placeholder. +.It <\-03>3<\-02>,M3.5.0/\-2,M10.5.0/\-1 +stands for time in western Greenland, 3 hours behind UT, where clocks +follow the EU rule of +springing forward on March's last Sunday at 01:00 UT (\-02:00 local +time, i.e., 22:00 the previous day) and falling back on October's last +Sunday at 01:00 UT (\-01:00 local time, i.e., 23:00 the previous day). +The abbreviations for standard and daylight saving time are +.Qq \-03 +and +.Qq \-02 . +.El +.Pp +If no +.Cm rule +is present in +.Ev TZ , +the rules specified by the +.Xr tzfile 5 +format file +the rule typically defaults to the current US daylight-saving rule, +although such a default is not guaranteed and +is incorrect for many locations outside the US. +Therefore, if a +.Ev TZ +string directly specifies a timezone with daylight saving time, +it should specify the daylight saving rule explicitly. +.Pp +For compatibility with System V Release 3.1, a semicolon (;) may be +used to separate the +.Cm rule +from the rest of the specification. +.Sh FILES +.Bl -tag -width /usr/share/zoneinfo/GMT -compact +.It Pa /etc/localtime +local timezone file +.It Pa /usr/share/zoneinfo +local timezone information directory +.\" .It Pa /usr/share/zoneinfo/localtime +.\" local timezone file +.It Pa /usr/share/zoneinfo/GMT +for UTC leap seconds +.El +.Pp +If +.Pa /usr/share/zoneinfo/GMT +is absent, UTC leap seconds are loaded from +.Pa /usr/share/zoneinfo/posixrules . +.Sh SEE ALSO +.Xr ctime 3 , +.Xr getenv 3 , +.Xr strftime 3 , +.Xr time 3 , +.Xr tzfile 5 +.Sh STANDARDS +The +.Fn tzset +function conforms to +.St -p1003.1-88 . +.Sh BUGS +Neither the +.Fn tzgetname +nor +.Fn tzgmtoff +functions have the ability to specify the point in time for which the +requested data should be returned. +.\" @(#)newtzset.3 8.2 +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. diff --git a/static/netbsd/man3/ualarm.3 b/static/netbsd/man3/ualarm.3 new file mode 100644 index 00000000..39b91ae0 --- /dev/null +++ b/static/netbsd/man3/ualarm.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: ualarm.3,v 1.19 2011/05/02 17:34:05 jruoho Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ualarm.3 8.2 (Berkeley) 4/19/94 +.\" +.Dd May 2, 2011 +.Dt UALARM 3 +.Os +.Sh NAME +.Nm ualarm +.Nd schedule signal after specified time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft useconds_t +.Fn ualarm "useconds_t microseconds" "useconds_t interval" +.Sh DESCRIPTION +.Bf -symbolic +This is a simplified interface to +.Xr setitimer 2 . +.Ef +.Pp +The +.Fn ualarm +function +waits a count of +.Ar microseconds +before asserting the terminating signal +.Dv SIGALRM . +System activity or time used in processing the call may cause a slight +delay. +.Pp +If the +.Fa interval +argument is non-zero, the +.Dv SIGALRM +signal will be sent +to the process every +.Fa interval +microseconds after the timer expires (e.g. after +.Fa microseconds +microseconds have passed). +.Sh RETURN VALUES +When the signal has successfully been caught, +.Fn ualarm +returns the amount of time left on the clock. +The maximum number of +.Ar microseconds +allowed +is 2147483647. +If there is an error setting the timer, +.Fn ualarm +returns ((useconds_t) -1). +.Sh SEE ALSO +.Xr getitimer 2 , +.Xr setitimer 2 , +.Xr sigaction 2 , +.Xr sigsuspend 2 , +.Xr alarm 3 , +.Xr signal 3 , +.Xr sigvec 3 , +.Xr sleep 3 , +.Xr usleep 3 +.Sh STANDARDS +The +.Fn ualarm +function conforms to +.St -p1003.1-2001 . +However, the later +.St -p1003.1-2008 +revision removed the function from the specification. +.Sh HISTORY +The +.Fn ualarm +function appeared in +.Bx 4.3 . diff --git a/static/netbsd/man3/ukfs.3 b/static/netbsd/man3/ukfs.3 new file mode 100644 index 00000000..e4c678ea --- /dev/null +++ b/static/netbsd/man3/ukfs.3 @@ -0,0 +1,321 @@ +.\" $NetBSD: ukfs.3,v 1.19 2025/05/09 06:07:56 andvar Exp $ +.\" +.\" Copyright (c) 2008 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 12, 2018 +.Dt UKFS 3 +.Os +.Sh NAME +.Nm ukfs +.Nd user kernel file system library interface +.Sh LIBRARY +ukfs Library (libukfs, \-lukfs) +.Sh SYNOPSIS +.In rump/ukfs.h +.Sh DESCRIPTION +The +.Nm +library provides direct access to file systems without having to +specially mount a file system. +Therefore, accessing a file system through +.Nm +requires no special kernel support apart from standard POSIX functionality. +As +.Nm +is built upon +.Xr rump 3 +kernels, all kernel file systems which are supported by rump kernels +are available. +It allows to write utilities for accessing file systems +without having to duplicate file system internals knowledge already +present in kernel file system drivers. +.Pp +.Nm +provides a high-level pathname based interface for accessing file systems. +If a lower level interface is desired, +.Xr rump 3 +kernels should be used directly. +However, much like system calls, the interfaces of +.Nm +are self-contained and require no tracking and release of resources. +The only exception is the file system handle +.Ft struct ukfs +which should be released after use. +.Sh INITIALIZATION +.Bl -ohang +.It Ft int +.Fn ukfs_init +.It Ft int +.Fn ukfs_modload "const char *fname" +.It Ft int +.Fn ukfs_modload_dir "const char *dirname" +.It Ft ssize_t +.Fn ukfs_vfstypes "char *buf" "size_t buflen" +.It Ft struct ukfs * +.Fn ukfs_mount "const char *vfsname" "const char *devpath" \ +"const char *mountpath" "int mntflags" "void *arg" "size_t alen" +.It Ft struct ukfs * +.Fn ukfs_mount_disk "const char *vfsname" "const char *devpath" \ +"int partition" "const char *mountpath" "int mntflags" \ +"void *arg" "size_t alen" +.It Ft int +.Fn ukfs_release "struct ukfs *ukfs" "int flags" +.El +.Pp +.Fn ukfs_init +initializes the library and must be called once per process using +.Nm . +.Pp +.Fn ukfs_modload +is used at runtime to dynamically load a library which contains a +file system module. +For this to succeed, the +.Xr rump 3 +kernel and the module targeted must be compiled with compatible kernel +versions and the application must be dynamically linked. +Additionally, since this routine does not handle dependencies, all the +dependencies of the library must be loaded beforehand. +The routine returns \-1 for fatal error, 0 for dependency failure and 1 +for success. +.Pp +.Fn ukfs_modload_dir +loads all +.Xr rump 3 +kernel file system components in directory +.Fa dirname . +It looks for libraries which begin with +.Pa librumpfs_ +and end in +.Pa .so . +The routine tries to handle dependencies by retrying to load libraries +which failed due to dependencies. +.Fn ukfs_modload_dir +returns the number of vfs modules loaded or sets errno and +returns \-1 in case of a fatal error in directory searching. +In case a fatal error occurs after some modules have already been +loaded, the number of loaded module is returned. +Fatal errors in loading the modules themselves are ignored and +.Fn ukfs_modload +should be used directly if finegrained error reporting is desired. +.Pp +It should be noted that the above routines affect the whole process, +not just a specific instance of +.Nm . +It is preferable to call them from only one thread, as the underlying +dynamic library interfaces may not be threadsafe. +.Pp +.Fn ukfs_vfstypes +queries the available file system types and returns a nul-terminated +list of types separated by spaces in +.Fa buf . +The format of the list is equivalent to the one returned by +.Xr sysctl 3 +on the name +.Pa vfs.generic.fstypes . +The function returns the length of the string without the trailing nul +or \-1 for error. +Notably, the return value 0 means there are no file systems available. +If there is not enough room in the caller's buffer for all file system +types, as many as fit will be returned. +.Pp +.Fn ukfs_mount +initializes a file system image. +The handle resulting from the operation is passed to all other routines +and identifies the instance of the mount analogous to what a pathname +specifies in a normally mounted file system. +The parameters are the following: +.Bl -tag -width XXX -offset indent +.It vfsname +Name of the file system to be used, e.g. +.Dv MOUNT_FFS . +.It devpath +Path of file system image. +It can be either a regular file, device or, if the file system does +not support the concept of a device, an arbitrary string, e.g. network +address. +.It mountpath +Path where the file system is mounted to. +This parameter is used only by the file system being mounted. +Most of the time +.Dv UKFS_DEFAULTMP +is the correct path. +.It mntflags +Flags as passed to the +.Xr mount 2 +system call, for example +.Dv MNT_RDONLY . +In addition to generic parameters, file system specific parameters such as +.Dv MNT_LOG +(ffs) may be passed here. +.It arg +File system private argument structure. +This is passed directly to the file system. +It must match what +.Fa vfsname +expects. +.It alen +Size of said structure. +.El +.Pp +The +.Fn ukfs_mount_disk +function must be used to mount disk-based file systems. +It takes the same arguments as +.Fn ukfs_mount , +except for an additional argument signifying the +.Fa partition +number. +If the image +.Fa devpath +contains a disklabel, this value specifies the number of the partition +within the image used as the file system backend. +If +.Fa devpath +does not contain a disklabel, the value +.Dv UKFS_PARTITION_NONE +must be used to signal that the file system backend is the entire +image. +.Pp +.Fn ukfs_release +unmounts the file system and releases the resources associated with +.Fa ukfs . +The return value signals the return value of the unmount operation. +If non-zero, +.Fa ukfs +will continue to remain valid. +The possible values for flags are: +.Bl -tag -width XUKFS_RELFLAG_NOUNMOUT -offset indent +.It Dv UKFS_RELFLAG_NOUNMOUNT +Do not unmount file system, just release ukfs handle. +Release always succeeds. +.It Dv UKFS_RELFLAG_FORCE +Forcefully unmount the file system. +This means that any busy nodes (due to e.g. +.Fn ukfs_chdir ) +will be ignored. +Release always succeeds. +.El +.Sh OPERATION +.Bl -ohang +.It Ft int +.Fn ukfs_chdir "struct ukfs *ukfs" "const char *path" +.It Ft int +.Fn ukfs_getdents "struct ukfs *ukfs" "const char *dirname" "off_t *off" \ +"uint8_t *buf" "size_t bufsize" +.It Ft ssize_t +.Fn ukfs_read "struct ukfs *ukfs" "const char *filename" "off_t off" \ +"uint8_t *buf" "size_t bufsize" +.It Ft ssize_t +.Fn ukfs_write "struct ukfs *ukfs" "const char *filename" "off_t off" \ +"uint8_t *buf" "size_t bufsize" +.It Ft int +.Fn ukfs_create "struct ukfs *ukfs" "const char *filename" "mode_t mode" +.It Ft int +.Fn ukfs_mknod "struct ukfs *ukfs" "const char *path" "mode_t mode" "dev_t dev" +.It Ft int +.Fn ukfs_mkfifo "struct ukfs *ukfs" "const char *path" "mode_t mode" +.It Ft int +.Fn ukfs_mkdir "struct ukfs *ukfs" "const char *filename" "mode_t mode" +.It Ft int +.Fn ukfs_remove "struct ukfs *ukfs" "const char *filename" +.It Ft int +.Fn ukfs_rmdir "struct ukfs *ukfs" "const char *filename" +.It Ft int +.Fn ukfs_link "struct ukfs *ukfs" "const char *filename" "const char *f_create" +.It Ft int +.Fn ukfs_symlink "struct ukfs *ukfs" "const char *filename" \ +"const char *linkname" +.It Ft ssize_t +.Fn ukfs_readlink "struct ukfs *ukfs" "const char *filename" \ +"char *linkbuf" "size_t buflen" +.It Ft int +.Fn ukfs_rename "struct ukfs *ukfs" "const char *from" "const char *to" +.It Ft int +.Fn ukfs_stat "struct ukfs *ukfs" "const char *filename" \ +"struct stat *file_stat" +.It Ft int +.Fn ukfs_lstat "struct ukfs *ukfs" "const char *filename" \ +"struct stat *file_stat" +.It Ft int +.Fn ukfs_chmod "struct ukfs *ukfs" "const char *filename" "mode_t mode" +.It Ft int +.Fn ukfs_lchmod "struct ukfs *ukfs" "const char *filename" "mode_t mode" +.It Ft int +.Fn ukfs_chown "struct ukfs *ukfs" "const char *filename" "uid_t uid" \ +"gid_t gid" +.It Ft int +.Fn ukfs_lchown "struct ukfs *ukfs" "const char *filename" "uid_t uid" \ +"gid_t gid" +.It Ft int +.Fn ukfs_chflags "struct ukfs *ukfs" "const char *filename" "u_long flags" +.It Ft int +.Fn ukfs_lchflags "struct ukfs *ukfs" "const char *filename" "u_long flags" +.It Ft int +.Fn ukfs_utimes "struct ukfs *ukfs" "const char *filename" \ +"const struct timeval *tptr" +.It Ft int +.Fn ukfs_lutimes "struct ukfs *ukfs" "const char *filename" \ +"const struct timeval *tptr" +.El +.Pp +The above routines operate like their system call counterparts and the +system call manual pages without the ukfs_ prefix should be referred to +for further information on the parameters. +.Pp +The only call which modifies +.Fa ukfs +state is +.Fn ukfs_chdir . +It works like +.Xr chdir 2 +in the sense that it affects the interpretation of relative paths. +If successful, all relative pathnames will be resolved starting from the +current directory. +Currently the call affects all accesses to that particular +.Fa ukfs , +but it might be later changed to be thread private. +.Sh UTILITIES +.Bl -ohang +.It Ft int +.Fn ukfs_util_builddirs "struct ukfs *ukfs" "const char *pathname" "mode_t mode" +.El +.Pp +Builds a directory hierarchy. +Unlike mkdir, the +.Fa pathname +argument may contain multiple levels of hierarchy. +It is not considered an error if any of the directories specified exist +already. +.Sh SEE ALSO +.Xr rump 3 +.Sh HISTORY +.Nm +first appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Antti Kantee Aq Mt pooka@cs.hut.fi +.Sh NOTES +.Nm +was an early attempt at an interface for kernel file systems +running in userspace. diff --git a/static/netbsd/man3/ulimit.3 b/static/netbsd/man3/ulimit.3 new file mode 100644 index 00000000..5312050c --- /dev/null +++ b/static/netbsd/man3/ulimit.3 @@ -0,0 +1,119 @@ +.\" $NetBSD: ulimit.3,v 1.9 2010/04/30 05:09:23 jruoho Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 30, 2010 +.Dt ULIMIT 3 +.Os +.Sh NAME +.Nm ulimit +.Nd get and set process limits +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In ulimit.h +.Ft long int +.Fn ulimit "int cmd" ... +.Sh DESCRIPTION +The +.Fn ulimit +function provides a method to query or alter resource limits of the calling +process. +The method to be performed is specified by the +.Fa cmd +argument; possible values are: +.Bl -tag -width UL_GETFSIZEXX +.It Li UL_GETFSIZE +Return the soft file size limit of the process. +The value returned is in units of 512-byte blocks. +If the result cannot be represented in an object of type +.Fa long int , +the result is unspecified. +.It Li UL_SETFSIZE +Set the hard and soft file size limits of the process to the value of the +second argument passed, which is in units of 512-byte blocks, and which is +expected to be of type +.Fa long int . +The new file size limit of the process is returned. +Any process may decrease the limit, but raising it is only permitted if +the caller is the super-user. +.El +.Pp +If successful, the +.Fn ulimit +function will not change the setting of +.Va errno . +.Sh RETURN VALUES +If successful, the +.Fn ulimit +function returns the value of the requested limit. +Otherwise, it returns \-1, sets +.Va errno +to indicate an error, and the limit is not changed. +Therefore, to detect an error condition applications should set +.Va errno +to 0, call +.Fn ulimit , +and check if \-1 is returned and +.Va errno +is non-zero. +.Sh ERRORS +The +.Fn ulimit +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cmd +argument is not valid. +.It Bq Er EPERM +It was attempted to increase a limit, and the caller is not the super-user. +.El +.Sh SEE ALSO +.Xr getrlimit 2 , +.Xr setrlimit 2 +.Sh STANDARDS +The +.Fn ulimit +function conforms to +.St -xsh5 +and +.St -p1003.1-2001 . +It was marked as obsolete in the +.St -p1003.1-2008 +revision, which recommended the use of +.Xr getrlimit 2 +and +.Xr setrlimit 2 +instead, noting that because +.Fn ulimit +uses the type +.Vt long +rather than +.Vt rlim_t , +it may not be sufficient for file sizes on many current systems. diff --git a/static/netbsd/man3/uname.3 b/static/netbsd/man3/uname.3 new file mode 100644 index 00000000..8de5a4d0 --- /dev/null +++ b/static/netbsd/man3/uname.3 @@ -0,0 +1,114 @@ +.\" $NetBSD: uname.3,v 1.13 2014/06/14 14:32:43 apb Exp $ +.\" +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)uname.3 8.1 (Berkeley) 1/4/94 +.\" +.Dd June 14, 2014 +.Dt UNAME 3 +.Os +.Sh NAME +.Nm uname +.Nd get system identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/utsname.h +.Ft int +.Fn uname "struct utsname *name" +.Sh DESCRIPTION +The +.Fn uname +function stores nul-terminated strings of information identifying +the current system into the structure referenced by +.Fa name . +.Pp +The +.Em utsname +structure is defined in the +.In sys/utsname.h +header file, and contains the following members: +.Bl -tag -width nodenameXXXX -offset indent +.It Va sysname +Name of the operating system implementation. +Equivalent to the +.Xr sysctl 7 +.Va kern.ostype +variable. +.It Va nodename +Network name of this machine. +Equivalent to the +.Xr sysctl 7 +.Va kern.hostname +variable. +.It Va release +Release level of the operating system. +Equivalent to the +.Xr sysctl 7 +.Va kern.osrelease +variable. +.It Va version +Version level of the operating system. +Equivalent to the +.Xr sysctl 7 +.Va kern.version +variable, except that very long values are truncated, +and newlines are converted to spaces. +.It Va machine +Machine hardware platform. +Equivalent to the +.Xr sysctl 7 +.Va hw.machine +variable. +.El +.Sh RETURN VALUES +If +.Nm uname +is successful, 0 is returned, otherwise, \-1 is returned and +.Va errno +is set appropriately. +.Sh ERRORS +The +.Fn uname +function may fail and set +.Va errno +for any of the errors specified for the library functions +.Xr sysctl 3 . +.Sh SEE ALSO +.Xr uname 1 , +.Xr sysctl 3 +.Sh STANDARDS +The +.Fn uname +function conforms to +.St -p1003.1-90 . +.Sh HISTORY +The +.Nm uname +function first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/ungetc.3 b/static/netbsd/man3/ungetc.3 new file mode 100644 index 00000000..a9fe94cf --- /dev/null +++ b/static/netbsd/man3/ungetc.3 @@ -0,0 +1,102 @@ +.\" $NetBSD: ungetc.3,v 1.10 2010/04/30 05:56:14 jruoho Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 30, 2010 +.Dt UNGETC 3 +.Os +.Sh NAME +.Nm ungetc +.Nd un-get character from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn ungetc "int c" "FILE *stream" +.Sh DESCRIPTION +The +.Fn ungetc +function pushes the character +.Fa c +(converted to an unsigned char) +back onto the input stream pointed to by +.Fa stream . +The pushed-backed characters will be returned by subsequent reads on the +stream (in reverse order). +A successful intervening call, using the same stream, to one of the file +positioning functions +.Po +.Xr fseek 3 , +.Xr fsetpos 3 , +or +.Xr rewind 3 +.Pc +will discard the pushed back characters. +.Pp +One character of push-back is guaranteed, +but as long as there is +sufficient memory, an effectively infinite amount of pushback is allowed. +.Pp +If a character is successfully pushed-back, +the end-of-file indicator for the stream is cleared. +.Sh RETURN VALUES +The +.Fn ungetc +function +returns +the character pushed-back after the conversion, or +.Dv EOF +if the operation fails. +If the value of the argument +.Fa c +character equals +.Dv EOF , +the operation will fail and the stream will remain unchanged. +.Sh SEE ALSO +.Xr fseek 3 , +.Xr getc 3 , +.Xr setvbuf 3 +.Sh STANDARDS +The +.Fn ungetc +function conforms to +.St -ansiC +and +.St -p1003.1-2001 . +.Sh HISTORY +An +.Fn ungetc +function appeared in +.At v7 . diff --git a/static/netbsd/man3/ungetwc.3 b/static/netbsd/man3/ungetwc.3 new file mode 100644 index 00000000..d2f7722c --- /dev/null +++ b/static/netbsd/man3/ungetwc.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: ungetwc.3,v 1.9 2024/09/08 09:36:47 rillig Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd October 24, 2001 +.Dt UNGETWC 3 +.Os +.Sh NAME +.Nm ungetwc +.Nd un-get wide character from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft wint_t +.Fn ungetwc "wint_t wc" "FILE *stream" +.Sh DESCRIPTION +The +.Fn ungetwc +function pushes the wide character +.Fa wc +(converted to a wchar_t) +back onto the input stream pointed to by +.Fa stream . +The pushed-backed wide characters will be returned by subsequent reads on the +stream (in reverse order). +A successful intervening call, using the same stream, to one of the file +positioning functions +.Xr fseek 3 , +.Xr fsetpos 3 , +or +.Xr rewind 3 +will discard the pushed back wide characters. +.Pp +One wide character of push-back is guaranteed, +but as long as there is +sufficient memory, an effectively infinite amount of pushback is allowed. +.Pp +If a character is successfully pushed-back, +the end-of-file indicator for the stream is cleared. +.Sh RETURN VALUES +The +.Fn ungetwc +function +returns +the wide character pushed-back after the conversion, or +.Dv WEOF +if the operation fails. +If the value of the argument +.Fa c +character equals +.Dv WEOF , +the operation will fail and the stream will remain unchanged. +.Sh SEE ALSO +.Xr fseek 3 , +.Xr getwc 3 +.Sh STANDARDS +The +.Fn ungetwc +function conforms to +.St -isoC-99 . +.Sh BUGS +The current implementation uses a fixed sized ungetwc-buffer. diff --git a/static/netbsd/man3/unlockpt.3 b/static/netbsd/man3/unlockpt.3 new file mode 100644 index 00000000..7c8de533 --- /dev/null +++ b/static/netbsd/man3/unlockpt.3 @@ -0,0 +1,86 @@ +.\" $NetBSD: unlockpt.3,v 1.4 2008/04/30 13:10:51 martin Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 25, 2004 +.Dt UNLOCKPT 3 +.Os +.Sh NAME +.Nm unlockpt +.Nd unlock the slave pseudo-terminal device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn unlockpt "int fildes" +.Sh DESCRIPTION +The +.Fn unlockpt +unlocks access to the pseudo-terminal device corresponding to the +master pseudo-terminal device associated with +.Fa fildes . +Conforming applications must call this function before opening the +slave pseudo-terminal device. +.Sh RETURN VALUES +If successful, +.Fn unlockpt +returns 0; otherwise a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn unlockpt +function will fail if: +.Bl -tag -width Er +.It Bq Er EACCESS +the corresponding pseudo-terminal device could not be accessed. +.It Bq Er EBADF +.Fa fildes +is not a valid descriptor. +.It Bq Er EINVAL +.Fa fildes +is not associated with a master pseudo-terminal device. +.El +.Sh NOTES +In +.Nx +.Fn unlockpt +does nothing. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr grantpt 3 , +.Xr posix_openpt 3 , +.Xr ptsname 3 +.Sh STANDARDS +The +.Fn unlockpt +function conforms to +.St -p1003.1-2001 . +Its first release was in +.St -xpg4.2 . diff --git a/static/netbsd/man3/unvis.3 b/static/netbsd/man3/unvis.3 new file mode 100644 index 00000000..6efe1982 --- /dev/null +++ b/static/netbsd/man3/unvis.3 @@ -0,0 +1,268 @@ +.\" $NetBSD: unvis.3,v 1.30 2019/05/08 15:37:41 bad Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)unvis.3 8.2 (Berkeley) 12/11/93 +.\" +.Dd May 8, 2019 +.Dt UNVIS 3 +.Os +.Sh NAME +.Nm unvis , +.Nm strunvis , +.Nm strnunvis , +.Nm strunvisx , +.Nm strnunvisx +.Nd decode a visual representation of characters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In vis.h +.Ft int +.Fn unvis "char *cp" "int c" "int *astate" "int flag" +.Ft int +.Fn strunvis "char *dst" "const char *src" +.Ft int +.Fn strnunvis "char *dst" "size_t dlen" "const char *src" +.Ft int +.Fn strunvisx "char *dst" "const char *src" "int flag" +.Ft int +.Fn strnunvisx "char *dst" "size_t dlen" "const char *src" "int flag" +.Sh DESCRIPTION +The +.Fn unvis , +.Fn strunvis +and +.Fn strunvisx +functions +are used to decode a visual representation of characters, as produced +by the +.Xr vis 3 +function, back into +the original form. +.Pp +The +.Fn unvis +function is called with successive characters in +.Ar c +until a valid sequence is recognized, at which time the decoded +character is available at the character pointed to by +.Ar cp . +.Pp +The +.Fn strunvis +function decodes the characters pointed to by +.Ar src +into the buffer pointed to by +.Ar dst . +The +.Fn strunvis +function simply copies +.Ar src +to +.Ar dst , +decoding any escape sequences along the way, +and returns the number of characters placed into +.Ar dst , +or \-1 if an +invalid escape sequence was detected. +The size of +.Ar dst +should be equal to the size of +.Ar src +(that is, no expansion takes place during decoding). +.Pp +The +.Fn strunvisx +and +.Fn strnunvisx +functions do the same as the +.Fn strunvis +and +.Fn strnunvis +functions, +but take a flag that specifies the style the string +.Ar src +is encoded with. +The meaning of the flag is the same as explained below for +.Fn unvis . +.Pp +The +.Fn unvis +function implements a state machine that can be used to decode an +arbitrary stream of bytes. +All state associated with the bytes being decoded is stored outside the +.Fn unvis +function (that is, a pointer to the state is passed in), so +calls decoding different streams can be freely intermixed. +To start decoding a stream of bytes, first initialize an integer to zero. +Call +.Fn unvis +with each successive byte, along with a pointer +to this integer, and a pointer to a destination character. +The +.Fn unvis +function has several return codes that must be handled properly. +They are: +.Bl -tag -width UNVIS_VALIDPUSH +.It Li \&0 No (zero) +Another character is necessary; nothing has been recognized yet. +.It Dv UNVIS_VALID +A valid character has been recognized and is available at the location +pointed to by +.Fa cp . +.It Dv UNVIS_VALIDPUSH +A valid character has been recognized and is available at the location +pointed to by +.Fa cp ; +however, the character currently passed in should be passed in again. +.It Dv UNVIS_NOCHAR +A valid sequence was detected, but no character was produced. +This return code is necessary to indicate a logical break between characters. +.It Dv UNVIS_SYNBAD +An invalid escape sequence was detected, or the decoder is in an unknown state. +The decoder is placed into the starting state. +.El +.Pp +When all bytes in the stream have been processed, call +.Fn unvis +one more time with flag set to +.Dv UNVIS_END +to extract any remaining character (the character passed in is ignored). +.Pp +The +.Fa flag +argument is also used to specify the encoding style of the source. +If set to +.Dv VIS_NOESCAPE +.Fn unvis +will not decode backslash escapes. +If set to +.Dv VIS_HTTPSTYLE +or +.Dv VIS_HTTP1808 , +.Fn unvis +will decode URI strings as specified in RFC 1808. +If set to +.Dv VIS_HTTP1866 , +.Fn unvis +will decode entity references and numeric character references +as specified in RFC 1866. +If set to +.Dv VIS_MIMESTYLE , +.Fn unvis +will decode MIME Quoted-Printable strings as specified in RFC 2045. +If set to +.Dv VIS_NOESCAPE , +.Fn unvis +will not decode +.Ql \e +quoted characters. +.Pp +The following code fragment illustrates a proper use of +.Fn unvis . +.Bd -literal -offset indent +int state = 0; +char out; + +while ((ch = getchar()) != EOF) { +again: + switch(unvis(&out, ch, &state, 0)) { + case 0: + case UNVIS_NOCHAR: + break; + case UNVIS_VALID: + (void)putchar(out); + break; + case UNVIS_VALIDPUSH: + (void)putchar(out); + goto again; + case UNVIS_SYNBAD: + errx(EXIT_FAILURE, "Bad character sequence!"); + } +} +if (unvis(&out, '\e0', &state, UNVIS_END) == UNVIS_VALID) + (void)putchar(out); +.Ed +.Sh ERRORS +The functions +.Fn strunvis , +.Fn strnunvis , +.Fn strunvisx , +and +.Fn strnunvisx +will return \-1 on error and set +.Va errno +to: +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid escape sequence was detected, or the decoder is in an unknown state. +.El +.Pp +In addition the functions +.Fn strnunvis +and +.Fn strnunvisx +will can also set +.Va errno +on error to: +.Bl -tag -width Er +.It Bq Er ENOSPC +Not enough space to perform the conversion. +.El +.Sh SEE ALSO +.Xr unvis 1 , +.Xr vis 1 , +.Xr vis 3 +.Rs +.%A R. Fielding +.%T Relative Uniform Resource Locators +.%O RFC1808 +.Re +.Sh HISTORY +The +.Fn unvis +function +first appeared in +.Bx 4.4 . +The +.Fn strnunvis +and +.Fn strnunvisx +functions appeared in +.Nx 6.0 . +.Sh BUGS +The names +.Dv VIS_HTTP1808 +and +.Dv VIS_HTTP1866 +are wrong. +Percent-encoding was defined in RFC 1738, the original RFC for URL. +RFC 1866 defines HTML 2.0, an application of SGML, from which it +inherits concepts of numeric character references and entity +references. diff --git a/static/netbsd/man3/update_panels.3 b/static/netbsd/man3/update_panels.3 new file mode 100644 index 00000000..516e409a --- /dev/null +++ b/static/netbsd/man3/update_panels.3 @@ -0,0 +1,66 @@ +.\" $NetBSD: update_panels.3,v 1.3 2015/10/29 06:57:34 wiz Exp $ +.\" +.\" Copyright (c) 2015 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 28, 2015 +.Dt UPDATE_PANELS 3 +.Os +.Sh NAME +.Nm update_panels +.Nd update terminal display +.Sh LIBRARY +.Lb libpanel +.Sh SYNOPSIS +.In panel.h +.\" +.Ft void +.Fn update_panels "void" +.\" +.Sh DESCRIPTION +The +.Fn update_panels +function performs the internal processing required by the panel +library to determine what changes need to be made to synchronise +the curses internal screen buffer and the terminal but does not +modify the terminal display. +.Pp +This function will internally perform the required calls to +.Xr touchoverlap 3 +and +.Xr wnoutrefresh 3 +in the correct order. +You should never directly call curses functions like +.Xr wnoutrefresh 3 +on panel windows yourself. +Remember, that +.Dv stdscr +is below all panels and any changes to it also require calling +.Fn update_panels . +.Pp +Finally, call the curses function +.Xr doupdate 3 +to update the terminal display. +.Sh SEE ALSO +.Xr doupdate 3 , +.Xr panel 3 diff --git a/static/netbsd/man3/usbhid.3 b/static/netbsd/man3/usbhid.3 new file mode 100644 index 00000000..b787f3f7 --- /dev/null +++ b/static/netbsd/man3/usbhid.3 @@ -0,0 +1,223 @@ +.\" $NetBSD: usbhid.3,v 1.17 2022/05/22 05:33:46 charlotte Exp $ +.\" +.\" Copyright (c) 1999, 2001 Lennart Augustsson <augustss@NetBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 21, 2022 +.Dt USBHID 3 +.Os +.Sh NAME +.Nm usbhid , +.Nm hid_get_report_desc , +.Nm hid_use_report_desc , +.Nm hid_dispose_report_desc , +.Nm hid_start_parse , +.Nm hid_end_parse , +.Nm hid_get_item , +.Nm hid_report_size , +.Nm hid_locate , +.Nm hid_usage_page , +.Nm hid_usage_in_page , +.Nm hid_parse_usage_page , +.Nm hid_parse_usage_in_page , +.Nm hid_init , +.Nm hid_get_data , +.Nm hid_set_data +.Nd USB HID access routines +.Sh LIBRARY +.Lb libusbhid +.Sh SYNOPSIS +.In usbhid.h +.Ft report_desc_t +.Fn hid_get_report_desc "int file" +.Ft report_desc_t +.Fn hid_use_report_desc "const uint8_t *data" "unsigned int size" +.Ft void +.Fn hid_dispose_report_desc "report_desc_t d" +.Ft hid_data_t +.Fn hid_start_parse "report_desc_t d" "int kindset" "int id" +.Ft void +.Fn hid_end_parse "hid_data_t s" +.Ft int +.Fn hid_get_item "hid_data_t s" "hid_item_t *h" +.Ft int +.Fn hid_report_size "report_desc_t d" "hid_kind_t k" "int id" +.Ft int +.Fn hid_locate "report_desc_t d" "u_int usage" "hid_kind_t k" "hid_item_t *h" "int id" +.Ft char * +.Fn hid_usage_page "int i" +.Ft char * +.Fn hid_usage_in_page "u_int u" +.Ft int +.Fn hid_parse_usage_page "const char *" +.Ft int +.Fn hid_parse_usage_in_page "const char *" +.Ft void +.Fn hid_init "const char *file" +.Ft int +.Fn hid_get_data "const void *data" "const hid_item_t *h" +.Ft void +.Fn hid_set_data "void *data" "const hid_item_t *h" "u_int data" +.Sh DESCRIPTION +The +.Nm +library provides routines to extract data from USB Human Interface Devices. +.Ss INTRODUCTION +USB HID devices send and receive data laid out in a device dependent way. +The +.Nm +library contains routines to extract the +.Em report descriptor +which contains the data layout information and then use this information. +.Pp +The routines can be divided into four parts: extraction of the descriptor, +parsing of the descriptor, translating to/from symbolic names, and +data manipulation. +.Ss DESCRIPTOR FUNCTIONS +A report descriptor can be obtained by calling +.Fn hid_get_report_desc +with a file descriptor obtained by opening a +.Xr uhid 4 +device. +Alternatively a data buffer containing the report descriptor can be +passed into +.Fn hid_use_report_desc . +The data is copied into an internal structure. +When the report descriptor +is no longer needed it should be freed by calling +.Fn hid_dispose_report_desc . +The type +.Fa report_desc_t +is opaque and should be used when calling the parsing functions. +If +.Fn hid_dispose_report_desc +fails it will return +.Fa NULL . +.Ss DESCRIPTOR PARSING FUNCTIONS +To parse the report descriptor the +.Fn hid_start_parse +function should be called with a report descriptor and a set that +describes which items that are interesting. +The set is obtained by or-ing together values +.Fa "(1 << k)" +where +.Fa k +is an item of type +.Fa hid_kind_t . +The report ID (if present) is given by +.Fa id . +The function returns +.Fa NULL +if the initialization fails, otherwise an opaque value to be used +in subsequent calls. +After parsing the +.Fn hid_end_parse +function should be called to free internal data structures. +.Pp +To iterate through all the items in the report descriptor, +.Fn hid_get_item +should be called while it returns a value greater than 0. +When the report descriptor ends it will return 0; a syntax +error within the report descriptor will cause a return value less +than 0. +The struct pointed to by +.Fa h +will be filled with the relevant data for the item. +The definition of +.Fa hid_item_t +can be found in +.In usbhid.h +and the meaning of the components in the USB HID documentation. +.Pp +Data should be read/written to the device in the size of +the report. +The size of a report (of a certain kind) can be computed by the +.Fn hid_report_size +function. +If the report is prefixed by an ID byte it is given by +.Fa id . +.Pp +To locate a single item the +.Fn hid_locate +function can be used. +It should be given the usage code of +the item and its kind and it will fill the item and return +non-zero if the item was found. +.Ss NAME TRANSLATION FUNCTIONS +The function +.Fn hid_usage_page +will return the symbolic name of a usage page, and the function +.Fn hid_usage_in_page +will return the symbolic name of the usage within the page. +Both these functions may return a pointer to static data. +.Pp +The functions +.Fn hid_parse_usage_page +and +.Fn hid_parse_usage_in_page +are the inverses of +.Fn hid_usage_page +and +.Fn hid_usage_in_page . +They take a usage string and return the number of the usage, or -1 +if it cannot be found. +.Pp +Before any of these functions can be called the usage table +must be parsed, this is done by calling +.Fn hid_init +with the name of the table. +Passing +.Fa NULL +to this function will cause it to use the default table. +.Ss DATA EXTRACTION FUNCTIONS +Given the data obtained from a HID device and an item in the +report descriptor the +.Fn hid_get_data +function extracts the value of the item. +Conversely +.Fn hid_set_data +can be used to put data into a report (which must be zeroed first). +.Sh FILES +.Pa /usr/share/misc/usb_hid_usages +The default HID usage table. +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr uhid 4 , +.Xr usb 4 +.Pp +.Lk http://www.usb.org/developers/docs/ "USB Specifications" +.Sh HISTORY +The +.Nm +library first appeared in +.Nx 1.5 +as +.Nm usb +library +and was renamed to +.Nm +for +.Nx 1.6 . +.Sh BUGS +This man page is woefully incomplete. diff --git a/static/netbsd/man3/usleep.3 b/static/netbsd/man3/usleep.3 new file mode 100644 index 00000000..64794df0 --- /dev/null +++ b/static/netbsd/man3/usleep.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: usleep.3,v 1.22 2024/05/15 13:12:04 riastradh Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)usleep.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 22, 2024 +.Dt USLEEP 3 +.Os +.Sh NAME +.Nm usleep +.Nd suspend execution for interval of microseconds +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn usleep "useconds_t microseconds" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr nanosleep 2 . +.Ef +.Pp +The +.Fn usleep +function +suspends execution of the calling process +until either the number of microseconds specified by +.Fa microseconds +have elapsed or a signal is delivered to the calling process and its +action is to invoke a signal catching function or to terminate the +process. +The suspension time may be longer than requested due to the +scheduling of other activity by the system. +.Sh RETURN VALUES +On successful completion, +.Fn usleep +returns 0. +Otherwise, it returns \-1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn usleep +function may fail if: +.Bl -tag -width Er +.It Bq Er EINTR +.Nm +was interrupted by the delivery of a signal. +.El +.Sh SEE ALSO +.Xr nanosleep 2 , +.Xr sleep 3 +.Sh STANDARDS +The +.Fn usleep +function conforms to +.St -xpg4.2 . +It later appeared in the +.Tn POSIX +standard, but in +.St -p1003.1-2004 +it was marked as legacy and the use of +.Xr nanosleep 2 +was recommended instead. +The +.St -p1003.1-2008 +revision removed +.Fn usleep +from the specification. +.Sh HISTORY +The +.Fn usleep +function appeared in +.Bx 4.3 . +.Sh CAVEATS +In +.St -p1003.1-2004 , +.Nm +was limited to values of +.Fa microseconds +less than one million. +Some implementations, including +.Nx +before 10.1, fail immediately with +.Er EINVAL +\(em and don't sleep at all \(em if +.Fa microseconds +is one million or greater. diff --git a/static/netbsd/man3/util.3 b/static/netbsd/man3/util.3 new file mode 100644 index 00000000..91b7eff1 --- /dev/null +++ b/static/netbsd/man3/util.3 @@ -0,0 +1,132 @@ +.\" $NetBSD: util.3,v 1.27 2019/03/08 08:12:39 msaitoh Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 31, 2017 +.Dt UTIL 3 +.Os +.Sh NAME +.Nm util , +.Nm libutil +.Nd system utilities library +.Sh LIBRARY +.Lb libutil +.Sh DESCRIPTION +The +.Nm +library is the system utilities library and contains various +system-dependent utility routines used in a wide variety of system daemons. +The abstracted functions are mostly related to pseudo-terminals +and login accounting. +These routines are +.Nx Ns -specific +and are not portable. +Their use should be restricted. +.Pp +Declarations for these functions may be obtained from the include file +.In util.h . +The +.Nm +library and the associated functions are implemented within the +.Pa /usr/src/lib/libutil +directory. +.Sh LIST OF FUNCTIONS +.Bl -column ".Xr sockaddr_snprintf 3" -compact +.It Sy Name Ta Sy Description +.It Xr disklabel_dkcksum 3 Ta compute the checksum for a disklabel +.It Xr disklabel_scan 3 Ta scan a buffer for a valid disklabel +.It Xr efun 3 Ta error checked utility functions +.It Xr forkpty 3 Ta tty utility function +.It Xr getbootfile 3 Ta get the name of the booted kernel file +.It Xr getbyteorder 3 Ta get the current byte order +.It Xr getdiskrawname 3 Ta get the block/character device name for a disk +.It Xr getfsspecname 3 Ta get the underlying wedge name from a label +.It Xr getfstypename 3 Ta convert a partition file system type integer to a wedge +partition type name +.It Xr getlabeloffset 3 Ta get the sector number and offset of the disklabel +.It Xr getlabelsector 3 Ta get the sector number and offset of the disklabel +.It Xr getmaxpartitions 3 Ta get the maximum number of partitions allowed per disk +.It Xr getmntopts 3 Ta scan mount options +.It Xr getrawpartition 3 Ta get the system ``raw'' partition +.It Xr kinfo_getvmmap 3 Ta get per-process memory map information +.It Xr login 3 Ta login utility function +.It Xr login_cap 3 Ta query login.conf database about a user class +.It Xr login_close 3 Ta query login.conf database about a user class +.It Xr login_getcapbool 3 Ta query login.conf database about a user class +.It Xr login_getcapnum 3 Ta query login.conf database about a user class +.It Xr login_getcapsize 3 Ta query login.conf database about a user class +.It Xr login_getcapstr 3 Ta query login.conf database about a user class +.It Xr login_getcaptime 3 Ta query login.conf database about a user class +.It Xr login_getclass 3 Ta query login.conf database about a user class +.It Xr login_tty 3 Ta tty utility function +.It Xr loginx 3 Ta login utility function +.It Xr logout 3 Ta login utility function +.It Xr logoutx 3 Ta login utility function +.It Xr logwtmp 3 Ta login utility function +.It Xr logwtmpx 3 Ta login utility function +.It Xr opendisk 3 Ta open a disk partition +.It Xr openpty 3 Ta tty utility function +.It Xr pidfile 3 Ta write a daemon pid file +.It Xr pidlock 3 Ta locks based on files containing PIDs +.It Xr proc_compare 3 Ta compare two processes' interactivity +.It Xr pw_abort 3 Ta passwd file update function +.It Xr pw_copy 3 Ta utility function for interactive passwd file updates +.It Xr pw_edit 3 Ta utility function for interactive passwd file updates +.It Xr pw_error 3 Ta utility function for interactive passwd file updates +.It Xr pw_getconf 3 Ta password encryption configuration access function +.It Xr pw_getprefix 3 Ta passwd file update function +.It Xr pw_init 3 Ta utility function for interactive passwd file updates +.It Xr pw_lock 3 Ta passwd file update function +.It Xr pw_mkdb 3 Ta passwd file update function +.It Xr pw_prompt 3 Ta utility function for interactive passwd file updates +.It Xr pw_scan 3 Ta utility function for interactive passwd file updates +.It Xr pw_setprefix 3 Ta passwd file update function +.It Xr raise_default_signal 3 Ta raise the default signal handler +.It Xr secure_path 3 Ta determine if a file appears to be ``secure'' +.It Xr setclasscontext 3 Ta query login.conf database about a user class +.It Xr setusercontext 3 Ta query login.conf database about a user class +.It Xr snprintb 3 Ta bitmask output conversion +.It Xr sockaddr_snprintf 3 Ta socket address formatting function +.It Xr strpct 3 Ta decimal percent formatter +.It Xr ttyaction 3 Ta ttyaction utility function +.It Xr ttylock 3 Ta locks based on files containing PIDs +.It Xr ttymsg 3 Ta ttymsg utility function +.It Xr ttyunlock 3 Ta locks based on files containing PIDs +.El +.Sh FILES +.Bl -tag -width /usr/lib/libutil_p.a -compact +.It Pa /usr/lib/libutil.a +static util library +.It Pa /usr/lib/libutil.so +dynamic util library +.It Pa /usr/lib/libutil_p.a +static util library compiled for profiling +.El +.Sh SEE ALSO +.Xr efun 3 , +.Xr intro 3 diff --git a/static/netbsd/man3/util.h.3 b/static/netbsd/man3/util.h.3 new file mode 100644 index 00000000..dbc8e97e --- /dev/null +++ b/static/netbsd/man3/util.h.3 @@ -0,0 +1,715 @@ +.TH "event2/util.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*- +.ad l +.nh +.SH NAME +event2/util.h \- Common convenience functions for cross-platform portability and related socket manipulations\&. + +.SH SYNOPSIS +.br +.PP +\fC#include <event2/visibility\&.h>\fP +.br +\fC#include <event2/event\-config\&.h>\fP +.br +\fC#include <stdarg\&.h>\fP +.br +\fC#include <sys/socket\&.h>\fP +.br +\fC#include <time\&.h>\fP +.br + +.SS "Data Structures" + +.in +1c +.ti -1c +.RI "struct \fBevutil_addrinfo\fP" +.br +.RI "\fIA definition of struct addrinfo for systems that lack it\&. \fP" +.ti -1c +.RI "struct \fBevutil_monotonic_timer\fP" +.br +.RI "\fIStructure to hold information about a monotonic timer\&. \fP" +.in -1c +.SS "Macros" + +.in +1c +.ti -1c +.RI "#define \fBEV_MONOT_FALLBACK\fP 2" +.br +.ti -1c +.RI "#define \fBEV_MONOT_PRECISE\fP 1" +.br +.ti -1c +.RI "#define \fBev_socklen_t\fP socklen_t" +.br +.ti -1c +.RI "#define \fBEVUTIL_CLOSESOCKET\fP(s) \fBevutil_closesocket\fP(s)" +.br +.ti -1c +.RI "#define \fBevutil_offsetof\fP(type, field) ((off_t)(&((type *)0)\->field))" +.br +.RI "\fIReplacement for offsetof on platforms that don't define it\&. \fP" +.ti -1c +.RI "#define \fBevutil_socket_t\fP int" +.br +.RI "\fIA type wide enough to hold the output of 'socket()' or 'accept()'\&. \fP" +.ti -1c +.RI "#define \fBevutil_timercmp\fP(tvp, uvp, cmp)" +.br +.RI "\fIReturn true iff the tvp is related to uvp according to the relational operator cmp\&. \fP" +.ti -1c +.RI "#define \fBevutil_timerisset\fP(tvp) ((tvp)\->tv_sec || (tvp)\->tv_usec)" +.br +.in -1c +.PP +.RI "\fBStandard integer types\&.\fP" +.br +Integer type definitions for types that are supposed to be defined in the C99-specified stdint\&.h\&. +.PP +Shamefully, some platforms do not include stdint\&.h, so we need to replace it\&. (If you are on a platform like this, your C headers are now over 10 years out of date\&. You should bug them to do something about this\&.) +.PP +We define: +.PP +.IP "\fBev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t \fP" 1c +unsigned integer types of exactly 64, 32, 16, and 8 bits respectively\&. +.IP "\fBev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t \fP" 1c +signed integer types of exactly 64, 32, 16, and 8 bits respectively\&. +.IP "\fBev_uintptr_t, ev_intptr_t \fP" 1c +unsigned/signed integers large enough to hold a pointer without loss of bits\&. +.IP "\fBev_ssize_t \fP" 1c +A signed type of the same size as size_t +.IP "\fBev_off_t \fP" 1c +A signed type typically used to represent offsets within a (potentially large) file +.PP + +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBev_uint64_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_int64_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_uint32_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_int32_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_uint16_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_int16_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_uint8_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_int8_t\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBev_uintptr_t\fP ev_uint32_t" +.br +.ti -1c +.RI "#define \fBev_intptr_t\fP ev_int32_t" +.br +.ti -1c +.RI "#define \fBev_ssize_t\fP ssize_t" +.br +.ti -1c +.RI "#define \fBev_off_t\fP \&.\&.\&." +.br +.in -1c +.in -1c +.PP +.RI "\fBLimits for integer types\fP" +.br +These macros hold the largest or smallest values possible for the ev_[u]int*_t types\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEV_UINT64_MAX\fP ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)" +.br +.ti -1c +.RI "#define \fBEV_INT64_MAX\fP ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)" +.br +.ti -1c +.RI "#define \fBEV_INT64_MIN\fP ((\-EV_INT64_MAX) \- 1)" +.br +.ti -1c +.RI "#define \fBEV_UINT32_MAX\fP ((ev_uint32_t)0xffffffffUL)" +.br +.ti -1c +.RI "#define \fBEV_INT32_MAX\fP ((ev_int32_t) 0x7fffffffL)" +.br +.ti -1c +.RI "#define \fBEV_INT32_MIN\fP ((\-EV_INT32_MAX) \- 1)" +.br +.ti -1c +.RI "#define \fBEV_UINT16_MAX\fP ((ev_uint16_t)0xffffUL)" +.br +.ti -1c +.RI "#define \fBEV_INT16_MAX\fP ((ev_int16_t) 0x7fffL)" +.br +.ti -1c +.RI "#define \fBEV_INT16_MIN\fP ((\-EV_INT16_MAX) \- 1)" +.br +.ti -1c +.RI "#define \fBEV_UINT8_MAX\fP 255" +.br +.ti -1c +.RI "#define \fBEV_INT8_MAX\fP 127" +.br +.ti -1c +.RI "#define \fBEV_INT8_MIN\fP ((\-EV_INT8_MAX) \- 1)" +.br +.in -1c +.in -1c +.PP +.RI "\fBLimits for SIZE_T and SSIZE_T\fP" +.br + +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEV_SIZE_MAX\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBEV_SSIZE_MAX\fP \&.\&.\&." +.br +.ti -1c +.RI "#define \fBEV_SSIZE_MIN\fP ((\-EV_SSIZE_MAX) \- 1)" +.br +.in -1c +.in -1c +.PP +.RI "\fBSocket error functions\fP" +.br +These functions are needed for making programs compatible between Windows and Unix-like platforms\&. +.PP +You see, Winsock handles socket errors differently from the rest of the world\&. Elsewhere, a socket error is like any other error and is stored in errno\&. But winsock functions require you to retrieve the error with a special function, and don't let you use strerror for the error codes\&. And handling EWOULDBLOCK is \&.\&.\&. different\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVUTIL_SOCKET_ERROR\fP() \&.\&.\&." +.br +.RI "\fIReturn the most recent socket error\&. \fP" +.ti -1c +.RI "#define \fBEVUTIL_SET_SOCKET_ERROR\fP(errcode) \&.\&.\&." +.br +.RI "\fIReplace the most recent socket error with errcode\&. \fP" +.ti -1c +.RI "#define \fBevutil_socket_geterror\fP(sock) \&.\&.\&." +.br +.RI "\fIReturn the most recent socket error to occur on sock\&. \fP" +.ti -1c +.RI "#define \fBevutil_socket_error_to_string\fP(errcode) \&.\&.\&." +.br +.RI "\fIConvert a socket error to a string\&. \fP" +.in -1c +.in -1c +.PP +.RI "\fBManipulation macros for struct timeval\&.\fP" +.br +We define replacements for timeradd, timersub, timerclear, timercmp, and timerisset\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBevutil_timeradd\fP(tvp, uvp, vvp)" +.br +.ti -1c +.RI "#define \fBevutil_timersub\fP(tvp, uvp, vvp)" +.br +.ti -1c +.RI "#define \fBevutil_timerclear\fP(tvp) (tvp)\->tv_sec = (tvp)\->tv_usec = 0" +.br +.in -1c +.in -1c +.PP +.RI "\fBevutil_getaddrinfo() error codes\fP" +.br +These values are possible error codes for \fBevutil_getaddrinfo()\fP and related functions\&. +.PP +.in +1c +.in +1c +.ti -1c +.RI "#define \fBEVUTIL_EAI_ADDRFAMILY\fP \-901" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_AGAIN\fP \-902" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_BADFLAGS\fP \-903" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_FAIL\fP \-904" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_FAMILY\fP \-905" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_MEMORY\fP \-906" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_NODATA\fP \-907" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_NONAME\fP \-908" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_SERVICE\fP \-909" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_SOCKTYPE\fP \-910" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_SYSTEM\fP \-911" +.br +.ti -1c +.RI "#define \fBEVUTIL_EAI_CANCEL\fP \-90001" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_PASSIVE\fP 0x1000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_CANONNAME\fP 0x2000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_NUMERICHOST\fP 0x4000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_NUMERICSERV\fP 0x8000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_V4MAPPED\fP 0x10000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_ALL\fP 0x20000" +.br +.ti -1c +.RI "#define \fBEVUTIL_AI_ADDRCONFIG\fP 0x40000" +.br +.in -1c +.in -1c +.SS "Functions" + +.in +1c +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_ascii_strcasecmp\fP (const char *str1, const char *str2)" +.br +.RI "\fIAs strcasecmp, but always compares the characters in locale-independent ASCII\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_ascii_strncasecmp\fP (const char *str1, const char *str2, size_t n)" +.br +.RI "\fIAs strncasecmp, but always compares the characters in locale-independent ASCII\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_closesocket\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo the platform-specific call needed to close a socket returned from socket() or accept()\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_configure_monotonic_time\fP (struct \fBevutil_monotonic_timer\fP *timer, int flags)" +.br +.RI "\fISet up a struct \fBevutil_monotonic_timer\fP; flags can include EV_MONOT_PRECISE and EV_MONOT_FALLBACK\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_date_rfc1123\fP (char *date, const size_t datelen, const struct tm *tm)" +.br +.RI "\fIFormat a date string using RFC 1123 format (used in HTTP)\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevutil_freeaddrinfo\fP (struct \fBevutil_addrinfo\fP *ai)" +.br +.RI "\fIRelease storage allocated by evutil_getaddrinfo or evdns_getaddrinfo\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevutil_gai_strerror\fP (int err)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_getaddrinfo\fP (const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, struct \fBevutil_addrinfo\fP **res)" +.br +.RI "\fIThis function clones getaddrinfo for systems that don't have it\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_gettime_monotonic\fP (struct \fBevutil_monotonic_timer\fP *timer, struct timeval *tp)" +.br +.RI "\fIQuery the current monotonic time from a struct \fBevutil_monotonic_timer\fP previously configured with \fBevutil_configure_monotonic_time()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_gettimeofday\fP (struct timeval *tv, struct timezone *tz)" +.br +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL const char * \fBevutil_inet_ntop\fP (int af, const void *src, char *dst, size_t len)" +.br +.RI "\fIReplacement for inet_ntop for platforms which lack it\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_inet_pton\fP (int af, const char *src, void *dst)" +.br +.RI "\fIReplacement for inet_pton for platforms which lack it\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_make_listen_socket_reuseable\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo platform-specific operations to make a listener socket reusable\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_make_listen_socket_reuseable_port\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo platform-specific operations to make a listener port reusable\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_make_socket_closeonexec\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_make_socket_nonblocking\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo platform-specific operations as needed to make a socket nonblocking\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_make_tcp_listen_socket_deferred\fP (\fBevutil_socket_t\fP sock)" +.br +.RI "\fIDo platform-specific operations, if possible, to make a tcp listener socket defer accept()s until there is data to read\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevutil_monotonic_timer_free\fP (struct \fBevutil_monotonic_timer\fP *timer)" +.br +.RI "\fIFree a struct \fBevutil_monotonic_timer\fP that was allocated using \fBevutil_monotonic_timer_new()\fP\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL struct \fBevutil_monotonic_timer\fP * \fBevutil_monotonic_timer_new\fP (void)" +.br +.RI "\fIAllocate a new struct \fBevutil_monotonic_timer\fP for use with the \fBevutil_configure_monotonic_time()\fP and \fBevutil_gettime_monotonic()\fP functions\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_parse_sockaddr_port\fP (const char *str, struct sockaddr *out, int *outlen)" +.br +.RI "\fIParse an IPv4 or IPv6 address, with optional port, from a string\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevutil_secure_rng_add_bytes\fP (const char *dat, size_t datlen)" +.br +.RI "\fISeed the random number generator with extra random bytes\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL void \fBevutil_secure_rng_get_bytes\fP (void *buf, size_t n)" +.br +.RI "\fIGenerate n bytes of secure pseudorandom data, and store them in buf\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_secure_rng_init\fP (void)" +.br +.RI "\fISeed the secure random number generator if needed, and return 0 on success or -1 on failure\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_secure_rng_set_urandom_device_file\fP (char *fname)" +.br +.RI "\fISet a filename to use in place of /dev/urandom for seeding the secure PRNG\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_snprintf\fP (char *buf, size_t buflen, const char *format,\&.\&.\&.)" +.br +.RI "\fIReplacement for snprintf to get consistent behavior on platforms for which the return value of snprintf does not conform to C99\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_sockaddr_cmp\fP (const struct sockaddr *sa1, const struct sockaddr *sa2, int include_port)" +.br +.RI "\fICompare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_socketpair\fP (int d, int type, int protocol, \fBevutil_socket_t\fP sv[2])" +.br +.RI "\fICreate two new sockets that are connected to each other\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL ev_int64_t \fBevutil_strtoll\fP (const char *s, char **endptr, int base)" +.br +.RI "\fIParse a 64-bit value from a string\&. \fP" +.ti -1c +.RI "EVENT2_EXPORT_SYMBOL int \fBevutil_vsnprintf\fP (char *buf, size_t buflen, const char *format, va_list ap)" +.br +.RI "\fIReplacement for vsnprintf to get consistent behavior on platforms for which the return value of snprintf does not conform to C99\&. \fP" +.in -1c +.SH "Detailed Description" +.PP +Common convenience functions for cross-platform portability and related socket manipulations\&. + + +.SH "Macro Definition Documentation" +.PP +.SS "#define evutil_offsetof(type, field) ((off_t)(&((type *)0)\->field))" + +.PP +Replacement for offsetof on platforms that don't define it\&. +.SS "#define EVUTIL_SOCKET_ERROR() \&.\&.\&." + +.PP +Return the most recent socket error\&. Not idempotent on all platforms\&. +.SS "#define evutil_socket_error_to_string(errcode) \&.\&.\&." + +.PP +Convert a socket error to a string\&. +.SS "#define evutil_socket_geterror(sock) \&.\&.\&." + +.PP +Return the most recent socket error to occur on sock\&. +.SS "#define evutil_socket_t int" + +.PP +A type wide enough to hold the output of 'socket()' or 'accept()'\&. On Windows, this is an intptr_t; elsewhere, it is an int\&. +.SS "#define evutil_timeradd(tvp, uvp, vvp)" +\fBValue:\fP +.PP +.nf +do { \ + (vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec; \ + (vvp)->tv_usec = (tvp)->tv_usec + (uvp)->tv_usec; \ + if ((vvp)->tv_usec >= 1000000) { \ + (vvp)->tv_sec++; \ + (vvp)->tv_usec -= 1000000; \ + } \ + } while (0) +.fi +.SS "#define evutil_timercmp(tvp, uvp, cmp)" +\fBValue:\fP +.PP +.nf +(((tvp)->tv_sec == (uvp)->tv_sec) ? \ + ((tvp)->tv_usec cmp (uvp)->tv_usec) : \ + ((tvp)->tv_sec cmp (uvp)->tv_sec)) +.fi +.PP +Return true iff the tvp is related to uvp according to the relational operator cmp\&. Recognized values for cmp are ==, <=, <, >=, and >\&. +.SS "#define evutil_timersub(tvp, uvp, vvp)" +\fBValue:\fP +.PP +.nf +do { \ + (vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec; \ + (vvp)->tv_usec = (tvp)->tv_usec - (uvp)->tv_usec; \ + if ((vvp)->tv_usec < 0) { \ + (vvp)->tv_sec--; \ + (vvp)->tv_usec += 1000000; \ + } \ + } while (0) +.fi +.SH "Function Documentation" +.PP +.SS "EVENT2_EXPORT_SYMBOL int evutil_ascii_strcasecmp (const char * str1, const char * str2)" + +.PP +As strcasecmp, but always compares the characters in locale-independent ASCII\&. That's useful if you're handling data in ASCII-based protocols\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_ascii_strncasecmp (const char * str1, const char * str2, size_t n)" + +.PP +As strncasecmp, but always compares the characters in locale-independent ASCII\&. That's useful if you're handling data in ASCII-based protocols\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_closesocket (\fBevutil_socket_t\fP sock)" + +.PP +Do the platform-specific call needed to close a socket returned from socket() or accept()\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The socket to be closed +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evutil_date_rfc1123 (char * date, const size_t datelen, const struct tm * tm)" + +.PP +Format a date string using RFC 1123 format (used in HTTP)\&. If \fCtm\fP is NULL, current system's time will be used\&. The number of characters written will be returned\&. One should check if the return value is smaller than \fCdatelen\fP to check if the result is truncated or not\&. +.SS "EVENT2_EXPORT_SYMBOL void evutil_freeaddrinfo (struct \fBevutil_addrinfo\fP * ai)" + +.PP +Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_getaddrinfo (const char * nodename, const char * servname, const struct \fBevutil_addrinfo\fP * hints_in, struct \fBevutil_addrinfo\fP ** res)" + +.PP +This function clones getaddrinfo for systems that don't have it\&. For full details, see RFC 3493, section 6\&.1\&. +.PP +Limitations: +.IP "\(bu" 2 +When the system has no getaddrinfo, we fall back to gethostbyname_r or gethostbyname, with their attendant issues\&. +.IP "\(bu" 2 +The AI_V4MAPPED and AI_ALL flags are not currently implemented\&. +.PP +.PP +For a nonblocking variant, see evdns_getaddrinfo\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_gettime_monotonic (struct \fBevutil_monotonic_timer\fP * timer, struct timeval * tp)" + +.PP +Query the current monotonic time from a struct \fBevutil_monotonic_timer\fP previously configured with \fBevutil_configure_monotonic_time()\fP\&. Monotonic time is guaranteed never to run in reverse, but is not necessarily epoch- based, or relative to any other definite point\&. Use it to make reliable measurements of elapsed time between events even when the system time may be changed\&. +.PP +It is not safe to use this funtion on the same timer from multiple threads\&. +.SS "EVENT2_EXPORT_SYMBOL const char* evutil_inet_ntop (int af, const void * src, char * dst, size_t len)" + +.PP +Replacement for inet_ntop for platforms which lack it\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_inet_pton (int af, const char * src, void * dst)" + +.PP +Replacement for inet_pton for platforms which lack it\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_make_listen_socket_reuseable (\fBevutil_socket_t\fP sock)" + +.PP +Do platform-specific operations to make a listener socket reusable\&. Specifically, we want to make sure that another program will be able to bind this address right after we've closed the listener\&. +.PP +This differs from Windows's interpretation of 'reusable', which allows multiple listeners to bind the same address at the same time\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The socket to make reusable +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evutil_make_listen_socket_reuseable_port (\fBevutil_socket_t\fP sock)" + +.PP +Do platform-specific operations to make a listener port reusable\&. Specifically, we want to make sure that multiple programs which also set the same socket option will be able to bind, listen at the same time\&. +.PP +This is a feature available only to Linux 3\&.9+ +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The socket to make reusable +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evutil_make_socket_closeonexec (\fBevutil_socket_t\fP sock)" + +.PP +Do platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The socket to be closed +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evutil_make_socket_nonblocking (\fBevutil_socket_t\fP sock)" + +.PP +Do platform-specific operations as needed to make a socket nonblocking\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The socket to make nonblocking +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success, -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL int evutil_make_tcp_listen_socket_deferred (\fBevutil_socket_t\fP sock)" + +.PP +Do platform-specific operations, if possible, to make a tcp listener socket defer accept()s until there is data to read\&. Not all platforms support this\&. You don't want to do this for every listener socket: only the ones that implement a protocol where the client transmits before the server needs to respond\&. +.PP +\fBParameters:\fP +.RS 4 +\fIsock\fP The listening socket to to make deferred +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success (whether the operation is supported or not), -1 on failure +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL struct \fBevutil_monotonic_timer\fP* evutil_monotonic_timer_new (void)" + +.PP +Allocate a new struct \fBevutil_monotonic_timer\fP for use with the \fBevutil_configure_monotonic_time()\fP and \fBevutil_gettime_monotonic()\fP functions\&. You must configure the timer with \fBevutil_configure_monotonic_time()\fP before using it\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_parse_sockaddr_port (const char * str, struct sockaddr * out, int * outlen)" + +.PP +Parse an IPv4 or IPv6 address, with optional port, from a string\&. Recognized formats are: +.IP "\(bu" 2 +[IPv6Address]:port +.IP "\(bu" 2 +[IPv6Address] +.IP "\(bu" 2 +IPv6Address +.IP "\(bu" 2 +IPv4Address:port +.IP "\(bu" 2 +IPv4Address +.PP +.PP +If no port is specified, the port in the output is set to 0\&. +.PP +\fBParameters:\fP +.RS 4 +\fIstr\fP The string to parse\&. +.br +\fIout\fP A struct sockaddr to hold the result\&. This should probably be a struct sockaddr_storage\&. +.br +\fIoutlen\fP A pointer to the number of bytes that that 'out' can safely hold\&. Set to the number of bytes used in 'out' on success\&. +.RE +.PP +\fBReturns:\fP +.RS 4 +-1 if the address is not well-formed, if the port is out of range, or if out is not large enough to hold the result\&. Otherwise returns 0 on success\&. +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evutil_secure_rng_add_bytes (const char * dat, size_t datlen)" + +.PP +Seed the random number generator with extra random bytes\&. You should almost never need to call this function; it should be sufficient to invoke \fBevutil_secure_rng_init()\fP, or let Libevent take care of calling \fBevutil_secure_rng_init()\fP on its own\&. +.PP +If you call this function as a \fIreplacement\fP for the regular entropy sources, then you need to be sure that your input contains a fairly large amount of strong entropy\&. Doing so is notoriously hard: most people who try get it wrong\&. Watch out! +.PP +\fBParameters:\fP +.RS 4 +\fIdat\fP a buffer full of a strong source of random numbers +.br +\fIdatlen\fP the number of bytes to read from datlen +.RE +.PP + +.SS "EVENT2_EXPORT_SYMBOL void evutil_secure_rng_get_bytes (void * buf, size_t n)" + +.PP +Generate n bytes of secure pseudorandom data, and store them in buf\&. Current versions of Libevent use an ARC4-based random number generator, seeded using the platform's entropy source (/dev/urandom on Unix-like systems; CryptGenRandom on Windows)\&. This is not actually as secure as it should be: ARC4 is a pretty lousy cipher, and the current implementation provides only rudimentary prediction- and backtracking-resistance\&. Don't use this for serious cryptographic applications\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_secure_rng_init (void)" + +.PP +Seed the secure random number generator if needed, and return 0 on success or -1 on failure\&. It is okay to call this function more than once; it will still return 0 if the RNG has been successfully seeded and -1 if it can't be seeded\&. +.PP +Ordinarily you don't need to call this function from your own code; Libevent will seed the RNG itself the first time it needs good random numbers\&. You only need to call it if (a) you want to double-check that one of the seeding methods did succeed, or (b) you plan to drop the capability to seed (by chrooting, or dropping capabilities, or whatever), and you want to make sure that seeding happens before your program loses the ability to do it\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_secure_rng_set_urandom_device_file (char * fname)" + +.PP +Set a filename to use in place of /dev/urandom for seeding the secure PRNG\&. Return 0 on success, -1 on failure\&. +.PP +Call this function BEFORE calling any other initialization or RNG functions\&. +.PP +(This string will \fINOT\fP be copied internally\&. Do not free it while any user of the secure RNG might be running\&. Don't pass anything other than a real /dev/\&.\&.\&.random device file here, or you might lose security\&.) +.PP +This API is unstable, and might change in a future libevent version\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_sockaddr_cmp (const struct sockaddr * sa1, const struct sockaddr * sa2, int include_port)" + +.PP +Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2\&. If include_port is true, consider the port as well as the address\&. Only implemented for AF_INET and AF_INET6 addresses\&. The ordering is not guaranteed to remain the same between Libevent versions\&. +.SS "EVENT2_EXPORT_SYMBOL int evutil_socketpair (int d, int type, int protocol, \fBevutil_socket_t\fP sv[2])" + +.PP +Create two new sockets that are connected to each other\&. On Unix, this simply calls socketpair()\&. On Windows, it uses the loopback network interface on 127\&.0\&.0\&.1, and only AF_INET,SOCK_STREAM are supported\&. +.PP +(This may fail on some Windows hosts where firewall software has cleverly decided to keep 127\&.0\&.0\&.1 from talking to itself\&.) +.PP +Parameters and return values are as for socketpair() +.SS "EVENT2_EXPORT_SYMBOL ev_int64_t evutil_strtoll (const char * s, char ** endptr, int base)" + +.PP +Parse a 64-bit value from a string\&. Arguments are as for strtol\&. +.SH "Author" +.PP +Generated automatically by Doxygen for libevent from the source code\&. diff --git a/static/netbsd/man3/utime.3 b/static/netbsd/man3/utime.3 new file mode 100644 index 00000000..36508895 --- /dev/null +++ b/static/netbsd/man3/utime.3 @@ -0,0 +1,149 @@ +.\" $NetBSD: utime.3,v 1.22 2014/10/19 16:47:51 njoly Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)utime.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd April 29, 2010 +.Dt UTIME 3 +.Os +.Sh NAME +.Nm utime +.Nd set file times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In utime.h +.Ft int +.Fn utime "const char *file" "const struct utimbuf *timep" +.Sh DESCRIPTION +.Bf -symbolic +This interface is obsoleted by +.Xr utimes 2 . +.Ef +.Pp +The +.Fn utime +function sets the access and modification times of the named file. +.Pp +If +.Fa timep +is +.Dv NULL , +the access and modification times are set to the current time. +The calling process must be the owner of the file or have permission to +write the file. +.Pp +If +.Fa timep +is +.Pf non- Dv NULL , +.Fa time +is assumed to be a pointer to a utimbuf structure, as defined in +.In utime.h : +.Bd -literal -offset indent +struct utimbuf { + time_t actime; /* Access time */ + time_t modtime; /* Modification time */ +}; +.Ed +.Pp +The access time is set to the value of the actime member, and the +modification time is set to the value of the modtime member. +The times are measured in seconds since 0 hours, 0 minutes, 0 +seconds, January 1, 1970 Coordinated Universal Time (UTC). +The calling process must be the owner of the file or be the super-user. +.Pp +In either case, the inode-change-time of the file is set to the current +time. +.Sh RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn utime +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix; +or the +.Fa times +argument is +.Dv NULL +and the effective user ID of the process does not +match the owner of the file, and is not the super-user, and write +access is denied. +.It Bq Er EFAULT +.Fa file +or +.Fa times +points outside the process's allocated address space. +.It Bq Er EINVAL +The pathname contains a character with the high-order bit set. +.It Bq Er EIO +An I/O error occurred while reading or writing the affected inode. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters, +or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EPERM +The +.Fa times +argument is not +.Dv NULL +and the calling process's effective user ID +does not match the owner of the file and is not the super-user. +.It Bq Er EROFS +The file system containing the file is mounted read-only. +.El +.Sh SEE ALSO +.Xr stat 2 , +.Xr utimes 2 +.Sh STANDARDS +The +.Fn utime +function conforms to +.St -p1003.1-90 . +It was however marked as legacy in the +.St -p1003.1-2008 +revision of the standard. +.Sh HISTORY +A +.Fn utime +function appeared in +.At v7 . diff --git a/static/netbsd/man3/uuid.3 b/static/netbsd/man3/uuid.3 new file mode 100644 index 00000000..17202686 --- /dev/null +++ b/static/netbsd/man3/uuid.3 @@ -0,0 +1,211 @@ +.\" $NetBSD: uuid.3,v 1.7 2008/05/02 18:11:05 martin Exp $ +.\" +.\" Copyright (c) 2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 2002 Marcel Moolenaar +.\" Copyright (c) 2002 Hiten Mahesh Pandya +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libc/uuid/uuid.3,v 1.4 2003/08/08 19:12:28 marcel Exp $ +.\" +.Dd April 22, 2008 +.Dt UUID 3 +.Os +.Sh NAME +.Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal , +.Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string , +.Nm uuid_enc_le , uuid_dec_le , uuid_enc_be , uuid_dec_be +.Nd Universally Unique Identifier routines +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In uuid.h +.Ft int32_t +.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" +.Ft void +.Fn uuid_create "uuid_t *uuid" "uint32_t *status" +.Ft void +.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status" +.Ft int32_t +.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" +.Ft void +.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status" +.Ft uint16_t +.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status" +.Ft int32_t +.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status" +.Ft void +.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status" +.Ft void +.Fn uuid_enc_le "void *buf" "const uuid_t *uuid" +.Ft void +.Fn uuid_dec_le "const void *buf" "uuid_t *" +.Ft void +.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" +.Ft void +.Fn uuid_dec_be "const void *buf" "uuid_t *" +.Sh DESCRIPTION +These routines provide for the creation and manipulation of Universally +Unique Identifiers +.Pq UUIDs , +also referred to as Globally Unique Identifiers +.Pq GUIDs . +.Pp +The +.Fn uuid_compare +function compares two UUIDs. +It returns \-1 if +.Fa uuid1 +precedes +.Fa uuid2 , +0 if they are equal, or 1 if +.Fa uuid1 +follows +.Fa uuid2 . +.Pp +The +.Fn uuid_create +function creates a new UUID. +Storage for the new UUID must be pre-allocated by the caller. +.Pp +The +.Fn uuid_create_nil +function creates a nil-valued UUID. +Storage for the new UUID must be pre-allocated by the caller. +.Pp +The +.Fn uuid_equal +function compares two UUIDs to determine if they are equal. +It returns 1 if they are equal, and 0 if they are not equal. +.Pp +The +.Fn uuid_from_string +function parses a 36-character string representation of a UUID and +converts it to binary representation. +Storage for the UUID must be pre-allocated by the caller. +.Pp +The +.Fn uuid_hash +function generates a hash value for the specified UUID. +Note that the hash value is not a cryptographic hash, and should not be +assumed to be unique given two different UUIDs. +.Pp +The +.Fn uuid_is_nil +function returns 1 if the UUID is nil-valued and 0 if it is not. +.Pp +The +.Fn uuid_to_string +function converts a UUID from binary representation to string representation. +Storage for the string is dynamically allocated and returned via the +.Fa str +argument. +This pointer should be passed to +.Xr free 3 +to release the allocated storage when it is no longer needed. +.Pp +The +.Fn uuid_enc_le +and +.Fn uuid_enc_be +functions encode a binary representation of a UUID into an octet stream +in little-endian and big-endian byte-order, respectively. +The destination buffer must be pre-allocated by the caller, and must be +large enough to hold the 16-octet binary UUID. +.Pp +The +.Fn uuid_dec_le +and +.Fn uuid_dec_be +functions decode a UUID from an octet stream in little-endian and +big-endian byte-order, respectively. +.Sh RETURN VALUES +The +.Fn uuid_compare , +.Fn uuid_create , +.Fn uuid_create_nil , +.Fn uuid_equal , +.Fn uuid_from_string , +.Fn uuid_hash , +.Fn uuid_is_nil , +and +.Fn uuid_to_string +functions return successful or unsuccessful completion status in the +.Fa status +argument. +Possible values are: +.Pp +.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" +.It Dv uuid_s_ok +The function completed successfully. +.It Dv uuid_s_bad_version +The UUID does not have a known version. +.It Dv uuid_s_invalid_string_uuid +The string representation of a UUID is not valid. +.It Dv uuid_s_no_memory +Memory could not be allocated for the operation. +.El +.Sh SEE ALSO +.Xr uuidgen 1 , +.Xr uuidgen 2 +.Sh STANDARDS +The +.Fn uuid_compare , +.Fn uuid_create , +.Fn uuid_create_nil , +.Fn uuid_equal , +.Fn uuid_from_string , +.Fn uuid_hash , +.Fn uuid_is_nil , +and +.Fn uuid_to_string +functions are compatible with the DCE 1.1 RPC specification. +.Sh HISTORY +The UUID functions first appeared in +.Nx 3.0 . diff --git a/static/netbsd/man3/valloc.3 b/static/netbsd/man3/valloc.3 new file mode 100644 index 00000000..2c49a0de --- /dev/null +++ b/static/netbsd/man3/valloc.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: valloc.3,v 1.14 2010/05/08 11:22:58 wiz Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)valloc.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd May 6, 2010 +.Dt VALLOC 3 +.Os +.Sh NAME +.Nm valloc +.Nd aligned memory allocation function +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn valloc "size_t size" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn valloc +function is obsoleted by the current version of +.Xr malloc 3 , +which aligns page-sized and larger allocations. +.Ef +.Pp +The +.Fn valloc +function +allocates +.Fa size +bytes aligned on a page boundary. +It is implemented by calling +.Xr malloc 3 +with a slightly larger request, saving the true beginning of the block +allocated, and returning a properly aligned pointer. +.Sh RETURN VALUES +The +.Fn valloc +function returns +a pointer to the allocated space if successful; otherwise +a null pointer is returned +.Sh HISTORY +The +.Fn valloc +function appeared in +.Bx 3.0 . +.Sh BUGS +A +.Fn vfree +function has not been implemented. diff --git a/static/netbsd/man3/virtdir.3 b/static/netbsd/man3/virtdir.3 new file mode 100644 index 00000000..1eb6554a --- /dev/null +++ b/static/netbsd/man3/virtdir.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: virtdir.3,v 1.4 2014/03/18 18:20:39 riastradh Exp $ +.\" +.\" Copyright © 2007 Alistair Crooks. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS +.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 23, 2007 +.Dt VIRTDIR 3 +.Os +.Sh NAME +.Nm virtdir +.Nd Utility routines for virtual directories for refuse operations +.Sh SYNOPSIS +.In virtdir.h +.Ft int +.Fo virtdir_init +.Fa "virtdir_t *tree" "struct stat *dir" "struct stat *file" "struct stat *symlink" +.Fc +.Ft int +.Fo virtdir_add +.Fa "virtdir_t *tree" "const char *name" "size_t namesize" "uint8_t type" "char *target" +.Fc +.Ft int +.Fo virtdir_del +.Fa "virtdir_t *tree" "const char *name" "size_t namesize" +.Fc +.Ft int +.Fo virtdir_find +.Fa "virtdir_t *tree" "const char *name" "size_t namesize" +.Fc +.Ft int +.Fo virtdir_find_tgt +.Fa "virtdir_t *tree" "const char *name" "size_t namesize" +.Fc +.Ft void +.Fo virtdir_drop +.Fa "virtdir_t *tree" +.Fc +.Ft VIRTDIR * +.Fo openvirtdir +.Fa "virtdir_t *tree" "const char *directory" +.Fc +.Ft virt_dirent_t * +.Fo readvirtdir +.Fa "VIRTDIR *dirp" +.Fc +.Ft void +.Fo closevirtdir +.Fa "VIRTDIR *dirp" +.Fc +.Sh DESCRIPTION +.Nm +provides virtual directory functionality for the benefit of +.Xr refuse 3 +file systems (and also for FUSE-based file systems). +.Pp +It uses the framework provided by the +.Xr puffs 3 +subsystem, and, through that, the kernel interface provided by +.Xr puffs 4 . +.Pp +The +.Nm +routines build up and manage a list of virtual directory entries. +Each virtual directory entry is indexed by its full pathname within +the file system. +This is consistent with the way that +.Xr refuse 3 +locates directory entries - by full pathname. +.Pp +The list of paths is sorted alphabetically. +Each of these virtual directory entries has a distinct type - +file +.Pq Sq f , +directory +.Pq Sq d , +or symbolic link +.Pq Sq l . +Additionally, an entry can point to a target - this +is useful when modeling virtual directory entries which are +symbolic links. +The list contains three basic +.Xr stat 2 +structures, which contain basic information for file, directory +and symbolic link entries. +This information can be specified at +initialization time, and customized within the individual +getattr operation routines as specified by the +individual file systems. +The +.Nm +functionality can also make virtual directory entries available +on a per-directory basis +to the caller by means of routines analogous to +.Xr opendir 3 , +.Xr readdir 3 , +and +.Xr closedir 3 . +These are +.Fn openvirtdir , +.Fn readvirtdir , +and +.Fn closevirtdir , +respectively. +.Sh SEE ALSO +.Xr puffs 3 , +.Xr refuse 3 , +.Xr puffs 4 +.Sh HISTORY +An unsupported experimental version of +.Nm +first appeared in +.Nx 5.0 . +.Sh AUTHORS +.An Alistair Crooks Aq Mt agc@NetBSD.org diff --git a/static/netbsd/man3/vis.3 b/static/netbsd/man3/vis.3 new file mode 100644 index 00000000..421f7d69 --- /dev/null +++ b/static/netbsd/man3/vis.3 @@ -0,0 +1,556 @@ +.\" $NetBSD: vis.3,v 1.50 2022/12/04 11:25:08 uwe Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vis.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd April 22, 2017 +.Dt VIS 3 +.Os +.Sh NAME +.Nm vis , +.Nm nvis , +.Nm strvis , +.Nm stravis , +.Nm strnvis , +.Nm strvisx , +.Nm strnvisx , +.Nm strenvisx , +.Nm svis , +.Nm snvis , +.Nm strsvis , +.Nm strsnvis , +.Nm strsvisx , +.Nm strsnvisx , +.Nm strsenvisx +.Nd visually encode characters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In vis.h +.Ft char * +.Fn vis "char *dst" "int c" "int flag" "int nextc" +.Ft char * +.Fn nvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" +.Ft int +.Fn strvis "char *dst" "const char *src" "int flag" +.Ft int +.Fn stravis "char **dst" "const char *src" "int flag" +.Ft int +.Fn strnvis "char *dst" "size_t dlen" "const char *src" "int flag" +.Ft int +.Fn strvisx "char *dst" "const char *src" "size_t len" "int flag" +.Ft int +.Fn strnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" +.Ft int +.Fn strenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "int *cerr_ptr" +.Ft char * +.Fn svis "char *dst" "int c" "int flag" "int nextc" "const char *extra" +.Ft char * +.Fn snvis "char *dst" "size_t dlen" "int c" "int flag" "int nextc" "const char *extra" +.Ft int +.Fn strsvis "char *dst" "const char *src" "int flag" "const char *extra" +.Ft int +.Fn strsnvis "char *dst" "size_t dlen" "const char *src" "int flag" "const char *extra" +.Ft int +.Fn strsvisx "char *dst" "const char *src" "size_t len" "int flag" "const char *extra" +.Ft int +.Fn strsnvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" +.Ft int +.Fn strsenvisx "char *dst" "size_t dlen" "const char *src" "size_t len" "int flag" "const char *extra" "int *cerr_ptr" +.Sh DESCRIPTION +The +.Fn vis +function +copies into +.Fa dst +a string which represents the character +.Fa c . +If +.Fa c +needs no encoding, it is copied in unaltered. +The string is null terminated, and a pointer to the end of the string is +returned. +The maximum length of any encoding is four +bytes (not including the trailing +.Dv NUL ) ; +thus, when +encoding a set of characters into a buffer, the size of the buffer should +be four times the number of bytes encoded, plus one for the trailing +.Dv NUL . +The flag parameter is used for altering the default range of +characters considered for encoding and for altering the visual +representation. +The additional character, +.Fa nextc , +is only used when selecting the +.Dv VIS_CSTYLE +encoding format (explained below). +.Pp +The +.Fn strvis , +.Fn stravis , +.Fn strnvis , +.Fn strvisx , +and +.Fn strnvisx +functions copy into +.Fa dst +a visual representation of +the string +.Fa src . +The +.Fn strvis +and +.Fn strnvis +functions encode characters from +.Fa src +up to the +first +.Dv NUL . +The +.Fn strvisx +and +.Fn strnvisx +functions encode exactly +.Fa len +characters from +.Fa src +(this +is useful for encoding a block of data that may contain +.Dv NUL Ns 's ) . +Both forms +.Dv NUL +terminate +.Fa dst . +The size of +.Fa dst +must be four times the number +of bytes encoded from +.Fa src +(plus one for the +.Dv NUL ) . +Both +forms return the number of characters in +.Fa dst +(not including the trailing +.Dv NUL ) . +The +.Fn stravis +function allocates space dynamically to hold the string. +The +.Dq Nm n +versions of the functions also take an additional argument +.Fa dlen +that indicates the length of the +.Fa dst +buffer. +If +.Fa dlen +is not large enough to fit the converted string then the +.Fn strnvis +and +.Fn strnvisx +functions return \-1 and set +.Va errno +to +.Er ENOSPC . +The +.Fn strenvisx +function takes an additional argument, +.Fa cerr_ptr , +that is used to pass in and out a multibyte conversion error flag. +This is useful when processing single characters at a time when +it is possible that the locale may be set to something other +than the locale of the characters in the input data. +.Pp +The functions +.Fn svis , +.Fn snvis , +.Fn strsvis , +.Fn strsnvis , +.Fn strsvisx , +.Fn strsnvisx , +and +.Fn strsenvisx +correspond to +.Fn vis , +.Fn nvis , +.Fn strvis , +.Fn strnvis , +.Fn strvisx , +.Fn strnvisx , +and +.Fn strenvisx +but have an additional argument +.Fa extra , +pointing to a +.Dv NUL +terminated list of characters. +These characters will be copied encoded or backslash-escaped into +.Fa dst . +These functions are useful e.g. to remove the special meaning +of certain characters to shells. +.Pp +The encoding is a unique, invertible representation composed entirely of +graphic characters; it can be decoded back into the original form using +the +.Xr unvis 3 , +.Xr strunvis 3 +or +.Xr strnunvis 3 +functions. +.Pp +There are two parameters that can be controlled: the range of +characters that are encoded (applies only to +.Fn vis , +.Fn nvis , +.Fn strvis , +.Fn strnvis , +.Fn strvisx , +and +.Fn strnvisx ) , +and the type of representation used. +By default, all non-graphic characters, +except space, tab, and newline are encoded (see +.Xr isgraph 3 ) . +The following flags +alter this: +.Bl -tag -width VIS_WHITEX +.It Dv VIS_DQ +Also encode double quotes +.It Dv VIS_GLOB +Also encode the magic characters +.Ql ( * , +.Ql \&? , +.Ql \&[ , +and +.Ql # ) +recognized by +.Xr glob 3 . +.It Dv VIS_SHELL +Also encode the meta characters used by shells (in addition to the glob +characters): +.Ql ( ' , +.Ql ` , +.Ql \&" , +.Ql \&; , +.Ql & , +.Ql < , +.Ql > , +.Ql \&( , +.Ql \&) , +.Ql \&| , +.Ql \&] , +.Ql \e , +.Ql $ , +.Ql \&! , +.Ql \&^ , +and +.Ql ~ ) . +.It Dv VIS_SP +Also encode space. +.It Dv VIS_TAB +Also encode tab. +.It Dv VIS_NL +Also encode newline. +.It Dv VIS_WHITE +Synonym for +.Dv VIS_SP | VIS_TAB | VIS_NL . +.It Dv VIS_META +Synonym for +.Dv VIS_WHITE | VIS_GLOB | VIS_SHELL . +.It Dv VIS_SAFE +Only encode +.Dq unsafe +characters. +Unsafe means control characters which may cause common terminals to perform +unexpected functions. +Currently this form allows space, tab, newline, backspace, bell, and +return \(em in addition to all graphic characters \(em unencoded. +.El +.Pp +(The above flags have no effect for +.Fn svis , +.Fn snvis , +.Fn strsvis , +.Fn strsnvis , +.Fn strsvisx , +and +.Fn strsnvisx . +When using these functions, place all graphic characters to be +encoded in an array pointed to by +.Fa extra . +In general, the backslash character should be included in this array, see the +warning on the use of the +.Dv VIS_NOSLASH +flag below). +.Pp +There are six forms of encoding. +All forms use the backslash character +.Ql \e +to introduce a special +sequence; two backslashes are used to represent a real backslash, +except +.Dv VIS_HTTPSTYLE +that uses +.Ql % , +or +.Dv VIS_MIMESTYLE +that uses +.Ql = . +These are the visual formats: +.Bl -tag -width VIS_CSTYLE +.It (default) +Use an +.Ql M +to represent meta characters (characters with the 8th +bit set), and use caret +.Ql ^ +to represent control characters (see +.Xr iscntrl 3 ) . +The following formats are used: +.Bl -tag -width xxxxx +.It Dv \e^C +Represents the control character +.Ql C . +Spans characters +.Ql \e000 +through +.Ql \e037 , +and +.Ql \e177 +(as +.Ql \e^? ) . +.It Dv \eM-C +Represents character +.Ql C +with the 8th bit set. +Spans characters +.Ql \e241 +through +.Ql \e376 . +.It Dv \eM^C +Represents control character +.Ql C +with the 8th bit set. +Spans characters +.Ql \e200 +through +.Ql \e237 , +and +.Ql \e377 +(as +.Ql \eM^? ) . +.It Dv \e040 +Represents +.Tn ASCII +space. +.It Dv \e240 +Represents Meta-space. +.El +.It Dv VIS_CSTYLE +Use C-style backslash sequences to represent standard non-printable +characters. +The following sequences are used to represent the indicated characters: +.Bd -unfilled -offset indent +.Li \ea Tn \(em BEL No (007) +.Li \eb Tn \(em BS No (010) +.Li \ef Tn \(em NP No (014) +.Li \en Tn \(em NL No (012) +.Li \er Tn \(em CR No (015) +.Li \es Tn \(em SP No (040) +.Li \et Tn \(em HT No (011) +.Li \ev Tn \(em VT No (013) +.Li \e0 Tn \(em NUL No (000) +.Ed +.Pp +When using this format, the +.Fa nextc +parameter is looked at to determine if a +.Dv NUL +character can be encoded as +.Ql \e0 +instead of +.Ql \e000 . +If +.Fa nextc +is an octal digit, the latter representation is used to +avoid ambiguity. +.Pp +Non-printable characters without C-style +backslash sequences use the default representation. +.It Dv VIS_OCTAL +Use a three digit octal sequence. +The form is +.Ql \eddd +where +.Em d +represents an octal digit. +.It Dv VIS_CSTYLE \&| Dv VIS_OCTAL +Same as +.Dv VIS_CSTYLE +except that non-printable characters without C-style +backslash sequences use a three digit octal sequence. +.It Dv VIS_HTTPSTYLE +Use URI encoding as described in RFC 1738. +The form is +.Ql %xx +where +.Em x +represents a lower case hexadecimal digit. +.It Dv VIS_MIMESTYLE +Use MIME Quoted-Printable encoding as described in RFC 2045, only don't +break lines and don't handle CRLF. +The form is +.Ql =XX +where +.Em X +represents an upper case hexadecimal digit. +.El +.Pp +There is one additional flag, +.Dv VIS_NOSLASH , +which inhibits the +doubling of backslashes and the backslash before the default +format (that is, control characters are represented by +.Ql ^C +and +meta characters as +.Ql M-C ) . +With this flag set, the encoding is +ambiguous and non-invertible. +.Sh MULTIBYTE CHARACTER SUPPORT +These functions support multibyte character input. +The encoding conversion is influenced by the setting of the +.Ev LC_CTYPE +environment variable which defines the set of characters +that can be copied without encoding. +.Pp +If +.Dv VIS_NOLOCALE +is set, processing is done assuming the C locale and overriding +any other environment settings. +.Pp +When 8-bit data is present in the input, +.Ev LC_CTYPE +must be set to the correct locale or to the C locale. +If the locales of the data and the conversion are mismatched, +multibyte character recognition may fail and encoding will be performed +byte-by-byte instead. +.Pp +As noted above, +.Fa dst +must be four times the number of bytes processed from +.Fa src . +But note that each multibyte character can be up to +.Dv MB_LEN_MAX +bytes +.\" (see +.\" .Xr multibyte 3 ) +so in terms of multibyte characters, +.Fa dst +must be four times +.Dv MB_LEN_MAX +times the number of characters processed from +.Fa src . +.Sh ENVIRONMENT +.Bl -tag -width ".Ev LC_CTYPE" +.It Ev LC_CTYPE +Specify the locale of the input data. +Set to C if the input data locale is unknown. +.El +.Sh ERRORS +The functions +.Fn nvis +and +.Fn snvis +will return +.Dv NULL +and the functions +.Fn strnvis , +.Fn strnvisx , +.Fn strsnvis , +and +.Fn strsnvisx , +will return \-1 when the +.Fa dlen +destination buffer size is not enough to perform the conversion while +setting +.Va errno +to: +.Bl -tag -width ".Bq Er ENOSPC" +.It Bq Er ENOSPC +The destination buffer size is not large enough to perform the conversion. +.El +.Sh SEE ALSO +.Xr unvis 1 , +.Xr vis 1 , +.Xr glob 3 , +.\" .Xr multibyte 3 , +.Xr unvis 3 +.Rs +.%A T. Berners-Lee +.%T Uniform Resource Locators (URL) +.%O "RFC 1738" +.Re +.Rs +.%T "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies" +.%O "RFC 2045" +.Re +.Sh HISTORY +The +.Fn vis , +.Fn strvis , +and +.Fn strvisx +functions first appeared in +.Bx 4.4 . +The +.Fn svis , +.Fn strsvis , +and +.Fn strsvisx +functions appeared in +.Nx 1.5 . +The buffer size limited versions of the functions +.Po Fn nvis , +.Fn strnvis , +.Fn strnvisx , +.Fn snvis , +.Fn strsnvis , +and +.Fn strsnvisx Pc +appeared in +.Nx 6.0 +and +.Fx 9.2 . +Multibyte character support was added in +.Nx 7.0 +and +.Fx 9.2 . diff --git a/static/netbsd/man3/wcrtomb.3 b/static/netbsd/man3/wcrtomb.3 new file mode 100644 index 00000000..fb03f05f --- /dev/null +++ b/static/netbsd/man3/wcrtomb.3 @@ -0,0 +1,145 @@ +.\" $NetBSD: wcrtomb.3,v 1.9 2007/02/20 08:33:25 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 4, 2002 +.Dt WCRTOMB 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wcrtomb +.Nd converts a wide character to a multibyte character (restartable) +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +.Fn wcrtomb +converts the wide character given by +.Fa wc +to the corresponding multibyte character, and stores it in the array +pointed to by +.Fa s +unless +.Fa s +is a null pointer. +This function will modify the first at most +.Dv MB_CUR_MAX +bytes of the array pointed to by +.Fa s . +.Pp +The behaviour of +.Fn wcrtomb +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 012345678901 +.It "wc == 0" +For state-dependent encodings, +.Fn wcrtomb +stores a nul byte preceded by special byte sequence (if any) +to return to an initial state in the array pointed to by +.Fa s , +and the state object pointed to by +.Fa ps +also returns to an initial state. +.It "s == NULL" +.Fn wcrtomb +just places +.Fa ps +into an initial state. +It is equivalent to the following call: +.Bd -literal -offset indent +wcrtomb(buf, L'\\0', ps); +.Ed +.Pp +Here, +.Fa buf +is a dummy buffer. +In this case, +.Fa wc +is ignored. +.It "ps == NULL" +.Fn mbrtowc +uses its own internal state object to keep the conversion state, +instead of +.Fa ps +mentioned in this manual page. +.Pp +Calling any other functions in +.Lb libc +never changes the internal +state of +.Fn mbrtowc , +which is initialized at startup time of the program. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn wcrtomb +returns: +.Bl -tag -width 012345678901 +.It "positive" +The number of bytes (including any shift sequences) +which are stored in the array. +.It "(size_t)-1" +.Fa wc +is not a valid wide character. +In this case, +.Fn wcrtomb +also sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn wcrtomb +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa wc +is not a valid wide character. +.It Bq Er EINVAL +.Fa ps +points to an invalid or uninitialized mbstate_t object. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr wctomb 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wcrtomb +function conforms to +.St -isoC-amd1 . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/wcscasecmp.3 b/static/netbsd/man3/wcscasecmp.3 new file mode 100644 index 00000000..06b862f9 --- /dev/null +++ b/static/netbsd/man3/wcscasecmp.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: wcscasecmp.3,v 1.6 2016/07/14 16:09:56 abhinav Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)wcscasecmp.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd July 13, 2016 +.Dt WCSCASECMP 3 +.Os +.Sh NAME +.Nm wcscasecmp , +.Nm wcsncasecmp +.Nd compare wide-character strings, ignoring case +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcscasecmp "const wchar_t *s1" "const wchar_t *s2" +.Ft int +.Fn wcsncasecmp "const wchar_t *s1" "const wchar_t *s2" "size_t len" +.Sh DESCRIPTION +The +.Fn wcscasecmp +and +.Fn wcsncasecmp +functions +compare the nul-terminated strings +.Fa s1 +and +.Fa s2 +and return an integer greater than, equal to, or less than 0, +according to whether +.Fa s1 +is lexicographically greater than, equal to, or less than +.Fa s2 +after translation of each corresponding character to lower-case. +The strings themselves are not modified. +.Pp +The +.Fn wcsncasecmp +function compares at most +.Fa len +characters. +.Sh SEE ALSO +.Xr wcscmp 3 +.Sh STANDARDS +The +.Fn wcscasecmp +and +.Fn wcsncasecmp +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn wcscasecmp +and +.Fn wcsncasecmp +functions first appeared in +.Nx 4.0 . +.Sh NOTES +If +.Fa len +is 0, +.Fn wcsncasecmp +always returns 0. diff --git a/static/netbsd/man3/wcscoll.3 b/static/netbsd/man3/wcscoll.3 new file mode 100644 index 00000000..1e238158 --- /dev/null +++ b/static/netbsd/man3/wcscoll.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: wcscoll.3,v 1.3 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)strcoll.3 8.1 (Berkeley) 6/4/93 +.\" FreeBSD: src/lib/libc/string/strcoll.3,v 1.11 2001/10/01 16:09:00 ru Exp +.\" FreeBSD: /repoman/r/ncvs/src/lib/libc/string/wcscoll.3,v 1.2 2002/12/09 14:04:05 ru Exp +.\" +.Dd October 13, 2006 +.Dt WCSCOLL 3 +.Os +.Sh NAME +.Nm wcscoll +.Nd compare wide strings according to current collation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcscoll "const wchar_t *s1" "const wchar_t *s2" +.Sh DESCRIPTION +The +.Fn wcscoll +function compares the nul-terminated strings +.Fa s1 +and +.Fa s2 +according to the current locale collation order. +In the +.Dq Li C +locale, +.Fn wcscoll +is equivalent to +.Fn wcscmp . +.Sh RETURN VALUES +The +.Fn wcscoll +function returns an integer greater than, equal to, or less than +0, if +.Fa s1 +is greater than, equal to, or less than +.Fa s2 . +.Pp +No return value is reserved to indicate errors; +callers should set +.Va errno +to 0 before calling +.Fn wcscoll . +If it is non-zero upon return from +.Fn wcscoll , +an error has occurred. +.Sh ERRORS +The +.Fn wcscoll +function will fail if: +.Bl -tag -width Er +.It Bq Er EILSEQ +An invalid wide-character code was specified. +.It Bq Er ENOMEM +Cannot allocate enough memory for temporary buffers. +.El +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr strcoll 3 , +.Xr wcscmp 3 , +.Xr wcsxfrm 3 +.Sh STANDARDS +The +.Fn wcscoll +function conforms to +.St -isoC-99 . +.Sh BUGS +The current implementation of +.Fn wcscoll +function disregards +.Dv LC_COLLATE +locales, and falls back to using the +.Fn wcscmp +function. diff --git a/static/netbsd/man3/wcsdup.3 b/static/netbsd/man3/wcsdup.3 new file mode 100644 index 00000000..ccefae44 --- /dev/null +++ b/static/netbsd/man3/wcsdup.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: wcsdup.3,v 1.4 2012/12/28 13:53:12 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strdup.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd August 25, 2006 +.Dt WCSDUP 3 +.Os +.Sh NAME +.Nm wcsdup +.Nd save a copy of a wide string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcsdup "const wchar_t *str" +.Sh DESCRIPTION +The +.Fn wcsdup +function +allocates sufficient memory for a copy +of the wide-character string +.Fa str , +does the copy, and returns a pointer to it. +The pointer may subsequently be used as an +argument to the function +.Xr free 3 . +.Pp +If insufficient memory is available, +.Dv NULL +is returned. +.Sh EXAMPLES +The following will point +.Va p +to an allocated area of memory containing the nul-terminated string +.Qq foobar : +.Bd -literal -offset indent +wchar_t *p; + +if (p = wcsdup(L"foobar"), p == NULL) { + fprintf(stderr, "Out of memory.\en"); + exit(1); +} +.Ed +.Sh ERRORS +The +.Fn wcsdup +function may fail and set the external variable +.Va errno +for any of the errors specified for the library function +.Xr malloc 3 . +.Sh SEE ALSO +.Xr free 3 , +.Xr malloc 3 , +.Xr strdup 3 +.Sh HISTORY +The +.Fn wcsdup +function first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/wcsftime.3 b/static/netbsd/man3/wcsftime.3 new file mode 100644 index 00000000..24f1424f --- /dev/null +++ b/static/netbsd/man3/wcsftime.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: wcsftime.3,v 1.4 2024/09/10 04:43:39 rillig Exp $ +.\" +.\" Copyright (c) 2002 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/locale/wcsftime.3,v 1.2 2002/11/29 17:35:09 ru Exp $ +.\" +.Dd April 14, 2011 +.Dt WCSFTIME 3 +.Os +.Sh NAME +.Nm wcsftime +.Nd "convert date and time to a wide-character string" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fo wcsftime +.Fa "wchar_t * restrict wcs" +.Fa "size_t maxsize" +.Fa "const wchar_t * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fc +.Sh DESCRIPTION +The +.Fn wcsftime +function is equivalent to the +.Fn strftime +function except for the types of its arguments +and the return value indicating the number of wide characters. +Refer to +.Xr strftime 3 +for a detailed description. +.Sh COMPATIBILITY +Some early implementations of +.Fn wcsftime +had a +.Fa format +argument with type +.Vt "const char *" +instead of +.Vt "const wchar_t *" . +.Sh SEE ALSO +.Xr strftime 3 , +.Xr tm 3 +.Sh STANDARDS +The +.Fn wcsftime +function conforms to +.St -isoC-99 . diff --git a/static/netbsd/man3/wcsrtombs.3 b/static/netbsd/man3/wcsrtombs.3 new file mode 100644 index 00000000..9717ef9a --- /dev/null +++ b/static/netbsd/man3/wcsrtombs.3 @@ -0,0 +1,223 @@ +.\" $NetBSD: wcsrtombs.3,v 1.18 2024/10/13 14:56:30 rillig Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 13, 2024 +.Dt WCSRTOMBS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wcsrtombs , +.Nm wcsnrtombs +.Nd converts a wide-character string to a multibyte character string \ +(restartable) +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +. +.In wchar.h +. +.Ft size_t +.Fo wcsrtombs +.Fa "char * restrict s" +.Fa "const wchar_t ** restrict pwcs" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +. +.Ft size_t +.Fo wcsnrtombs +.Fa "char * restrict s" +.Fa "const wchar_t ** restrict pwcs" +.Fa "size_t nwc" +.Fa "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +. +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn wcsrtombs +function converts the NUL-terminated wide-character string indirectly +pointed to by +.Fa pwcs +to the corresponding multibyte character string, +and stores it in the array pointed to by +.Fa s . +The conversion stops due to the following reasons: +.Bl -bullet +.It +The conversion reaches a NUL wide character. +In this case, the NUL wide character is also converted. +.It +The +.Fn wcsrtombs +has already stored +.Fa n +bytes in the array pointed to by +.Fa s . +.It +The conversion encounters an invalid character. +.El +.Pp +Each character will be converted as if +.Xr wcrtomb 3 +is continuously called, except the internal state of +.Xr wcrtomb 3 +will not be affected. +.Pp +After conversion, +if +.Fa s +is not a NULL pointer, the pointer object pointed to by +.Fa pwcs +is a NULL pointer +.Pq if the conversion is stopped due to reaching a NUL wide character +or points to the first byte of the character just after the last +character converted. +.Pp +If +.Fa s +is not a NULL pointer and the conversion is stopped due to reaching +a NUL wide character, +.Fn wcsrtombs +places the state object pointed to by +.Fa ps +to an initial state after the conversion is taken place. +.Pp +The behavior of +.Fn wcsrtombs +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width Li +.It Li "s == NULL" +.Fn wcsrtombs +returns the number of bytes to store the whole multibyte character string +corresponding to the wide-character string pointed to by +.Fa pwcs , +not including the terminating NUL byte. +In this case, +.Fa n +is ignored. +.It Li "pwcs == NULL || *pwcs == NULL" +Undefined (may cause the program to crash). +.It Li "ps == NULL" +.Fn wcsrtombs +uses its own internal state object to keep the conversion state, +instead of +.Fa ps +mentioned in this manual page. +.Pp +Calling any other functions in +.Lb libc +never changes the internal +state of +.Fn wcsrtombs , +which is initialized at startup time of the program. +.El +.Pp +The +.Fn wcsnrtombs +function behaves identically to +.Fn wcsrtombs , +except that the conversion stops after reading at most +.Fa nwc +characters from the buffer pointed to by +.Fa pwcs . +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions return: +.Bl -tag -width Li +.It Li 0 , No or positive +Number of bytes stored in the array pointed to by +.Fa s , +except for a NUL byte. +There are no cases that the value returned is greater than +.Fa n +.Po +unless +.Fa s +is a NULL pointer +.Pc . +If the return value is equal to +.Fa n , +the string pointed to by +.Fa s +will not be NUL-terminated. +.It Li "(size_t)-1" +.Fa pwcs +points to a string containing an invalid wide character. +The +.Fn wcsrtombs +also sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +The +.Fn wcsrtombs +and +.Fn wcsnrtombs +functions may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa pwcs +points to a string containing an invalid wide character. +.It Bq Er EINVAL +.Fa ps +points to an invalid or uninitialized +.Vt mbstate_t +object. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr wcrtomb 3 , +.Xr wcstombs 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wcsrtombs +function conforms to +.St -ansiC . +The +.Li restrict +qualifier was added by +.St -isoC-99 . +.Pp +The +.Fn wcsnrtombs +function conforms to +.St -p1003.1-2008 . diff --git a/static/netbsd/man3/wcstod.3 b/static/netbsd/man3/wcstod.3 new file mode 100644 index 00000000..965527fa --- /dev/null +++ b/static/netbsd/man3/wcstod.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: wcstod.3,v 1.5 2007/05/21 15:29:51 tnozaki Exp $ +.\" +.\" Copyright (c) 2002, 2003 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: wcstod.3,v 1.4 2003/05/22 13:02:27 ru Exp $ +.\" +.Dd February 22, 2003 +.Dt WCSTOD 3 +.Os +.Sh NAME +.Nm wcstof , +.Nm wcstod , +.Nm wcstold +.Nd convert string to +.Vt float , double , +or +.Vt "long double" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft float +.Fn wcstof "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" +.Ft "long double" +.Fn wcstold "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" +.Ft double +.Fn wcstod "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" +.Sh DESCRIPTION +The +.Fn wcstof , +.Fn wcstod , +and +.Fn wcstold +functions are the wide-character versions of the +.Fn strtof , +.Fn strtod , +and +.Fn strtold +functions. +Refer to +.Xr strtod 3 +for details. +.Sh SEE ALSO +.Xr strtod 3 , +.Xr wcstol 3 +.Sh STANDARDS +The +.Fn wcstod +function conforms to +.St -isoC-amd1 . +The +.Fn wcstof +and +.Fn wcstold +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/wcstok.3 b/static/netbsd/man3/wcstok.3 new file mode 100644 index 00000000..a181afef --- /dev/null +++ b/static/netbsd/man3/wcstok.3 @@ -0,0 +1,135 @@ +.\" $NetBSD: wcstok.3,v 1.6 2010/12/16 17:42:28 wiz Exp $ +.\" +.\" Copyright (c) 1998 Softweyr LLC. All rights reserved. +.\" +.\" strtok_r, from Berkeley strtok +.\" Oct 13, 1998 by Wes Peters <wes@softweyr.com> +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notices, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above +.\" copyright notices, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials provided +.\" with the distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgement: +.\" +.\" This product includes software developed by Softweyr LLC, the +.\" University of California, Berkeley, and its contributors. +.\" +.\" 4. Neither the name of Softweyr LLC, the University nor the names +.\" of its contributors may be used to endorse or promote products +.\" derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY SOFTWEYR LLC, THE REGENTS AND +.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL SOFTWEYR LLC, THE REGENTS, OR +.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Original version ID: +.\" FreeBSD: src/lib/libc/string/wcstok.3,v 1.4 2002/10/15 09:49:54 tjr Exp +.\" +.Dd October 3, 2002 +.Dt WCSTOK 3 +.Os +.Sh NAME +.Nm wcstok +.Nd split wide-character string into tokens +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wcstok "wchar_t * restrict str" "const wchar_t * restrict sep" "wchar_t ** restrict last" +.Sh DESCRIPTION +The +.Fn wcstok +function +is used to isolate sequential tokens in a nul-terminated wide-character +string, +.Fa str . +These tokens are separated in the string by at least one of the +characters in +.Fa sep . +The first time that +.Fn wcstok +is called, +.Fa str +should be specified; subsequent calls, wishing to obtain further tokens +from the same string, should pass a null pointer instead. +The separator string, +.Fa sep , +must be supplied each time, and may change between calls. +The context pointer +.Fa last +must be provided on each call. +.Pp +The +.Fn wcstok +function is the wide-character counterpart of the +.Fn strtok_r +function. +.Sh RETURN VALUES +The +.Fn wcstok +function +returns a pointer to the beginning of each subsequent token in the string, +after replacing the token itself with a nul wide character (L'\e0'). +When no more tokens remain, a null pointer is returned. +.Sh EXAMPLES +The following code fragment splits a wide-character string on +.Tn ASCII +space, tab and newline characters and writes the tokens to +standard output: +.Bd -literal -offset indent +const wchar_t *seps = L" \et\en"; +wchar_t *last, *tok, text[] = L" \enone\ettwo\et\etthree \en"; + +for (tok = wcstok(text, seps, &last); tok != NULL; + tok = wcstok(NULL, seps, &last)) + wprintf(L"%ls\en", tok); +.Ed +.Sh SEE ALSO +.Xr strtok 3 , +.Xr wcschr 3 , +.Xr wcscspn 3 , +.Xr wcspbrk 3 , +.Xr wcsrchr 3 , +.Xr wcsspn 3 +.Sh STANDARDS +The +.Fn wcstok +function +conforms to +.St -isoC-99 . +.Pp +Some early implementations of +.Fn wcstok +omit the context pointer argument, +.Fa last , +and maintain state across calls in a static variable like +.Xr strtok 3 +does. diff --git a/static/netbsd/man3/wcstol.3 b/static/netbsd/man3/wcstol.3 new file mode 100644 index 00000000..54992859 --- /dev/null +++ b/static/netbsd/man3/wcstol.3 @@ -0,0 +1,96 @@ +.\" $NetBSD: wcstol.3,v 1.3 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 2002 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/libc/locale/wcstol.3,v 1.4 2002/11/29 17:35:09 ru Exp $ +.\" +.Dd September 7, 2002 +.Dt WCSTOL 3 +.Os +.Sh NAME +.Nm wcstol , wcstoul , +.Nm wcstoll , wcstoull , +.Nm wcstoimax , wcstoumax +.Nd "convert a wide-character string value to a" +.Vt long , +.Vt "unsigned long" , +.Vt "long long" , +.Vt "unsigned long long" , +.Vt intmax_t +or +.Vt uintmax_t +integer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft long +.Fn wcstol "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.Ft "unsigned long" +.Fn wcstoul "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.Ft "long long" +.Fn wcstoll "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.Ft "unsigned long long" +.Fn wcstoull "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.In inttypes.h +.Ft intmax_t +.Fn wcstoimax "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.Ft uintmax_t +.Fn wcstoumax "const wchar_t * restrict nptr" "wchar_t ** restrict endptr" "int base" +.Sh DESCRIPTION +The +.Fn wcstol , +.Fn wcstoul , +.Fn wcstoll , +.Fn wcstoull , +.Fn wcstoimax +and +.Fn wcstoumax +functions are wide-character versions of the +.Fn strtol , +.Fn strtoul , +.Fn strtoll , +.Fn strtoull , +.Fn strtoimax +and +.Fn strtoumax +functions, respectively. +Refer to their manual pages (for example +.Xr strtol 3 ) +for details. +.Sh SEE ALSO +.Xr strtol 3 , +.Xr strtoul 3 +.Sh STANDARDS +The +.Fn wcstol , +.Fn wcstoul , +.Fn wcstoll , +.Fn wcstoull , +.Fn wcstoimax +and +.Fn wcstoumax +functions conform to +.St -isoC-99 . diff --git a/static/netbsd/man3/wcstombs.3 b/static/netbsd/man3/wcstombs.3 new file mode 100644 index 00000000..0a93b835 --- /dev/null +++ b/static/netbsd/man3/wcstombs.3 @@ -0,0 +1,133 @@ +.\" $NetBSD: wcstombs.3,v 1.13 2011/03/16 09:32:12 mbalmer Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 16, 2011 +.Dt WCSTOMBS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wcstombs +.Nd converts a wide-character string to a multibyte character string +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In stdlib.h +.Ft size_t +.Fn wcstombs "char * restrict s" "const wchar_t * restrict pwcs" "size_t n" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +.Fn wcstombs +converts the nul-terminated wide-character string pointed to by +.Fa pwcs +to the corresponding multibyte character string, +and stores it in the array pointed to by +.Fa s . +This function may modify the first at most +.Fa n +bytes of the array pointed to by +.Fa s . +Each character will be converted as if +.Xr wctomb 3 +is continuously called, except the internal state of +.Xr wctomb 3 +will not be affected. +.Pp +For state-dependent encoding, the +.Fn wcstombs +implies the result multibyte character string pointed to by +.Fa s +always to begin with an initial state. +.Pp +The behaviour of +.Fn wcstombs +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 012345678901 +.It s == NULL +The +.Fn wcstombs +returns the number of bytes to store the whole multibyte character string +corresponding to the wide-character string pointed to by +.Fa pwcs . +In this case, +.Fa n +is ignored. +.It pwcs == NULL +Undefined (may cause the program to crash). +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn wcstombs +returns: +.Bl -tag -width 012345678901 +.It 0 or positive +Number of bytes stored in the array pointed to by +.Fa s . +There are no cases that the value returned is greater than +.Fa n +(unless +.Fa s +is a null pointer). +If the return value is equal to +.Fa n , +the string pointed to by +.Fa s +will not be nul-terminated. +.It (size_t)-1 +.Fa pwcs +points to a string containing an invalid wide character. +.Fn wcstombs +also sets +.Va errno +to indicate the error. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn wcstombs +may cause an error in the following case: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa pwcs +points to a string containing an invalid wide character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mbstowcs 3 , +.Xr setlocale 3 , +.Xr wctomb 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wcstombs +function conforms to +.St -ansiC . +The restrict qualifier is added at +.St -isoC-99 . diff --git a/static/netbsd/man3/wcswidth.3 b/static/netbsd/man3/wcswidth.3 new file mode 100644 index 00000000..b7a89a9f --- /dev/null +++ b/static/netbsd/man3/wcswidth.3 @@ -0,0 +1,64 @@ +.\" $NetBSD: wcswidth.3,v 1.2 2006/10/16 08:48:45 wiz Exp $ +.\" FreeBSD: src/lib/libc/string/wcswidth.3,v 1.2 2002/12/09 14:04:05 ru Exp +.\" +.\" Copyright (c) 2002 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 20, 2002 +.Dt WCSWIDTH 3 +.Os +.Sh NAME +.Nm wcswidth +.Nd "number of column positions in wide-character string" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcswidth "const wchar_t *pwcs" "size_t n" +.Sh DESCRIPTION +The +.Fn wcswidth +function determines the number of column positions required for the first +.Fa n +characters of +.Fa pwcs , +or until a nul wide character (L'\e0') is encountered. +.Sh RETURN VALUES +The +.Fn wcswidth +function returns 0 if +.Fa pwcs +is an empty string (L""), +\-1 if a non-printing wide character is encountered, +otherwise it returns the number of column positions occupied. +.Sh SEE ALSO +.Xr iswprint 3 , +.Xr wcwidth 3 +.Sh STANDARDS +The +.Fn wcswidth +function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/wcsxfrm.3 b/static/netbsd/man3/wcsxfrm.3 new file mode 100644 index 00000000..96d07cc6 --- /dev/null +++ b/static/netbsd/man3/wcsxfrm.3 @@ -0,0 +1,107 @@ +.\" $NetBSD: wcsxfrm.3,v 1.4 2010/12/16 17:42:27 wiz Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)strxfrm.3 8.1 (Berkeley) 6/4/93 +.\" FreeBSD: src/lib/libc/string/strxfrm.3,v 1.16 2002/09/06 11:24:06 tjr Exp +.\" FreeBSD: /repoman/r/ncvs/src/lib/libc/string/wcsxfrm.3,v 1.2 2002/12/09 14:04:05 ru Exp +.\" +.Dd October 13, 2006 +.Dt WCSXFRM 3 +.Os +.Sh NAME +.Nm wcsxfrm +.Nd transform a wide string under locale +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsxfrm "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t n" +.Sh DESCRIPTION +The +.Fn wcsxfrm +function transforms a nul-terminated wide-character string pointed to by +.Fa src +according to the current locale collation order then copies the +transformed string into +.Fa dst . +No more than +.Fa n +wide characters are copied into +.Fa dst , +including the terminating nul character added. +If +.Fa n +is set to 0 +(it helps to determine an actual size needed for transformation), +.Fa dst +is permitted to be a null pointer. +.Pp +Comparing two strings using +.Fn wcscmp +after +.Fn wcsxfrm +is equivalent to comparing two original strings with +.Fn wcscoll . +.Sh RETURN VALUES +Upon successful completion, +.Fn wcsxfrm +returns the length of the transformed string not including +the terminating nul character. +If this value is +.Fa n +or more, the contents of +.Fa dst +are indeterminate. +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr strxfrm 3 , +.Xr wcscmp 3 , +.Xr wcscoll 3 +.Sh STANDARDS +The +.Fn wcsxfrm +function conforms to +.St -isoC-99 . +.Sh BUGS +The current implementation of +.Fn wcsxfrm +function disregards +.Dv LC_COLLATE +locales, and falls back to using the +.Fn wcsncpy +function. diff --git a/static/netbsd/man3/wctob.3 b/static/netbsd/man3/wctob.3 new file mode 100644 index 00000000..f12de66c --- /dev/null +++ b/static/netbsd/man3/wctob.3 @@ -0,0 +1,87 @@ +.\" $NetBSD: wctob.3,v 1.4 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 3, 2003 +.Dt WCTOB 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wctob +.Nd convert a wide character to a single byte character +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wctob "wint_t wc" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn wctob +function converts a wide character +.Fa wc +to a corresponding single byte character in the initial shift state of +the current locale. +.Pp +The behaviour of +.Fn wctob +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +The +.Fn wctob +function returns: +.Bl -tag -width 012345678901 +.It Dv EOF +If +.Fa wc +is +.Dv WEOF +or if +.Fa wc +does not correspond to a valid single byte character representation. +.It (otherwise) +A single byte character corresponding to +.Fa wc . +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr btowc 3 , +.Xr setlocale 3 , +.Xr wcrtomb 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wctob +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/wctomb.3 b/static/netbsd/man3/wctomb.3 new file mode 100644 index 00000000..33dacf4a --- /dev/null +++ b/static/netbsd/man3/wctomb.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: wctomb.3,v 1.7 2025/01/26 06:17:01 riastradh Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2002 +.Dt WCTOMB 3 +.Os +.Sh NAME +.Nm wctomb +.Nd converts a wide character to a multibyte character +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft int +.Fn wctomb "char * s" "wchar_t wchar" +.Sh DESCRIPTION +The +.Fn wctomb +converts the wide character +.Fa wchar +to the corresponding multibyte character, and stores it in the array +pointed to by +.Fa s . +.Fn wctomb +may store at most +.Dv MB_CUR_MAX +bytes in the array. +.Pp +In state-dependent encoding, +.Fn wctomb +may store the special sequence to change the conversion state +before an actual multibyte character into the array pointed to by +.Fa s . +If +.Fa wchar +is a nul wide character +.Pq Sq \e0 , +this function sets its own internal state to an initial conversion state. +.Pp +Calling any other functions in +.Lb libc +never changes the internal state of +.Fn wctomb , +except changing the +.Dv LC_CTYPE +category of the current locale by calling +.Xr setlocale 3 . +Such +.Xr setlocale 3 +calls cause the internal state of this function to be indeterminate. +.Pp +The behaviour of +.Fn wctomb +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +There is one special case: +.Bl -tag -width 012345678901 +.It s == NULL +.Fn wctomb +initializes its own internal state to an initial state, and +determines whether the current encoding is state-dependent. +This function returns 0 if the encoding is state-independent, +otherwise non-zero. +In this case, +.Fa wchar +is completely ignored. +.El +.Sh RETURN VALUES +Normally, +.Fn wctomb +returns: +.Bl -tag -width 012345678901 +.It positive +Number of bytes for the valid multibyte character pointed to by +.Fa s . +There are no cases that the value returned is greater than +the value of the +.Dv MB_CUR_MAX +macro. +.It -1 +.Fa wchar +is an invalid wide character. +.El +.Pp +If +.Fa s +is equal to +.Dv NULL , +.Fn wctomb +returns: +.Bl -tag -width 0123456789 +.It 0 +The current encoding is state-independent. +.It non-zero +The current encoding is state-dependent. +.El +.Sh ERRORS +No errors are defined. +.Sh SEE ALSO +.Xr setlocale 3 +.Sh STANDARDS +The +.Fn wctomb +function conforms to +.St -ansiC . diff --git a/static/netbsd/man3/wctrans.3 b/static/netbsd/man3/wctrans.3 new file mode 100644 index 00000000..9d412aaa --- /dev/null +++ b/static/netbsd/man3/wctrans.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: wctrans.3,v 1.4 2004/01/24 16:58:54 wiz Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 4, 2003 +.Dt WCTRANS 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wctrans +.Nd get character mapping identifier by name +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wctype.h +.Ft wctrans_t +.Fn wctrans "const char *charmap" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn wctrans +function returns a character mapping identifier corresponding to the +locale-specific character mapping name +.Fa charmap . +This identifier can be used on the subsequent calls of +.Fn towctrans . +The following names are defined in all locales: +.Bd -literal -offset indent +tolower toupper +.Ed +.Pp +The behaviour of +.Fn wctrans +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn wctrans +returns: +.Bl -tag -width 012345678901 +.It 0 +If the string +.Fa charmap +does not corresponding to a valid character mapping name. +.It non-zero +A character mapping identifier corresponding to +.Fa charmap . +.El +.Pp +Note: wctype_t is a scalar type, e.g., a pointer. +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr iswctype 3 , +.Xr setlocale 3 , +.Xr wctype 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn towctrans +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/wctype.3 b/static/netbsd/man3/wctype.3 new file mode 100644 index 00000000..fd92f8f5 --- /dev/null +++ b/static/netbsd/man3/wctype.3 @@ -0,0 +1,91 @@ +.\" $NetBSD: wctype.3,v 1.6 2007/05/21 15:20:40 tnozaki Exp $ +.\" +.\" Copyright (c)2003 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 4, 2003 +.Dt WCTYPE 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm wctype +.Nd get character class identifier by name +.\" ---------------------------------------------------------------------- +.Sh LIBRARY +.Lb libc +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.In wctype.h +.Ft wctype_t +.Fn wctype "const char *charclass" +.\" ---------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn wctype +function returns a character class identifier corresponding to the +locale-specific character class name +.Fa charclass . +This identifier can be used in subsequent calls of +.Fn iswctype . +The following names are defined in all locales: +.Bd -literal -offset indent +alnum alpha blank cntrl digit graph +lower print punct space upper xdigit +.Ed +.Pp +The behaviour of +.Fn wctype +is affected by the +.Dv LC_CTYPE +category of the current locale. +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +.Fn wctype +returns: +.Bl -tag -width 012345678901 +.It 0 +If +.Fa charclass +does not correspond to a valid character class name. +.It non-zero +A character class identifier corresponding to +.Fa charclass . +.El +.Pp +Note: wctype_t is a scalar type, e.g., a pointer. +.\" ---------------------------------------------------------------------- +.Sh ERRORS +No errors are defined. +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr iswctype 3 , +.Xr setlocale 3 , +.Xr towctrans 3 , +.Xr wctrans 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn wctype +function conforms to +.St -isoC-amd1 . diff --git a/static/netbsd/man3/wcwidth.3 b/static/netbsd/man3/wcwidth.3 new file mode 100644 index 00000000..a1a35052 --- /dev/null +++ b/static/netbsd/man3/wcwidth.3 @@ -0,0 +1,89 @@ +.\" $NetBSD: wcwidth.3,v 1.4 2017/07/03 21:32:49 wiz Exp $ +.\" FreeBSD: src/lib/libc/locale/wcwidth.3,v 1.6 2004/08/17 04:56:03 trhodes Exp +.\" +.\" Copyright (c) 2002 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd August 17, 2004 +.Dt WCWIDTH 3 +.Os +.Sh NAME +.Nm wcwidth +.Nd "number of column positions of a wide-character code" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft int +.Fn wcwidth "wchar_t wc" +.Sh DESCRIPTION +The +.Fn wcwidth +function determines the number of column positions required to +display the wide character +.Fa wc . +.Sh RETURN VALUES +The +.Fn wcwidth +function returns 0 if the +.Fa wc +argument is a nul wide character (L'\e0'), +\-1 if +.Fa wc +is not printable, +otherwise it returns the number of column positions the +character occupies. +.Sh EXAMPLES +This code fragment reads text from standard input and +breaks lines that are more than 20 column positions wide, +similar to the +.Xr fold 1 +utility: +.Bd -literal -offset indent +wint_t ch; +int column, w; + +column = 0; +while ((ch = getwchar()) != WEOF) { + w = wcwidth(ch); + if (w > 0 && column + w >= 20) { + putwchar(L'\en'); + column = 0; + } + putwchar(ch); + if (ch == L'\en') + column = 0; + else if (w > 0) + column += w; +} +.Ed +.Sh SEE ALSO +.Xr iswprint 3 , +.Xr wcswidth 3 +.Sh STANDARDS +The +.Fn wcwidth +function conforms to +.St -p1003.1-2001 . diff --git a/static/netbsd/man3/wind.3 b/static/netbsd/man3/wind.3 new file mode 100644 index 00000000..ca032917 --- /dev/null +++ b/static/netbsd/man3/wind.3 @@ -0,0 +1,317 @@ +.\" $NetBSD: wind.3,v 1.3 2023/06/19 21:41:41 christos Exp $ +.\" +.TH "wind" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal wind library" \" -*- nroff -*- +.ad l +.nh +.SH NAME +wind \- Heimdal wind library +.SH SYNOPSIS +.br +.PP +.SS "Functions" + +.in +1c +.ti -1c +.RI "int \fBwind_punycode_label_toascii\fP (const uint32_t *in, size_t in_len, char *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_stringprep\fP (const uint32_t *in, size_t in_len, uint32_t *out, size_t *out_len, wind_profile_flags flags)" +.br +.ti -1c +.RI "int \fBwind_profile\fP (const char *name, wind_profile_flags *flags)" +.br +.ti -1c +.RI "int \fBwind_utf8ucs4\fP (const char *in, uint32_t *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_utf8ucs4_length\fP (const char *in, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs4utf8\fP (const uint32_t *in, size_t in_len, char *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs4utf8_length\fP (const uint32_t *in, size_t in_len, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs2read\fP (const void *ptr, size_t len, unsigned int *flags, uint16_t *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs2write\fP (const uint16_t *in, size_t in_len, unsigned int *flags, void *ptr, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_utf8ucs2\fP (const char *in, uint16_t *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_utf8ucs2_length\fP (const char *in, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs2utf8\fP (const uint16_t *in, size_t in_len, char *out, size_t *out_len)" +.br +.ti -1c +.RI "int \fBwind_ucs2utf8_length\fP (const uint16_t *in, size_t in_len, size_t *out_len)" +.br +.in -1c +.SH "Detailed Description" +.PP + +.SH "Function Documentation" +.PP +.SS "int wind_profile (const char * name, wind_profile_flags * flags)" +Try to find the profile given a name\&. +.PP +\fBParameters\fP +.RS 4 +\fIname\fP name of the profile\&. +.br +\fIflags\fP the resulting profile\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_punycode_label_toascii (const uint32_t * in, size_t in_len, char * out, size_t * out_len)" +Convert an UCS4 string to a puny-coded DNS label string suitable when combined with delimiters and other labels for DNS lookup\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UCS4 string to convert +.br +\fIin_len\fP the length of in\&. +.br +\fIout\fP the resulting puny-coded string\&. The string is not NUL terminatied\&. +.br +\fIout_len\fP before processing out_len should be the length of the out variable, after processing it will be the length of the out string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_stringprep (const uint32_t * in, size_t in_len, uint32_t * out, size_t * out_len, wind_profile_flags flags)" +Process a input UCS4 string according a string-prep profile\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP input UCS4 string to process +.br +\fIin_len\fP length of the input string +.br +\fIout\fP output UCS4 string +.br +\fIout_len\fP length of the output string\&. +.br +\fIflags\fP stringprep profile\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_ucs2read (const void * ptr, size_t len, unsigned int * flags, uint16_t * out, size_t * out_len)" +Read in an UCS2 from a buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIptr\fP The input buffer to read from\&. +.br +\fIlen\fP the length of the input buffer\&. +.br +\fIflags\fP Flags to control the behavior of the function\&. +.br +\fIout\fP the output UCS2, the array must be at least out/2 long\&. +.br +\fIout_len\fP the output length +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise\&. +.RE +.PP +if len is zero, flags are unchanged +.PP +if len is odd, WIND_ERR_LENGTH_NOT_MOD2 is returned +.PP +If the flags WIND_RW_BOM is set, check for BOM\&. If not BOM is found, check is LE/BE flag is already and use that otherwise fail with WIND_ERR_NO_BOM\&. When done, clear WIND_RW_BOM and the LE/BE flag and set the resulting LE/BE flag\&. +.SS "int wind_ucs2utf8 (const uint16_t * in, size_t in_len, char * out, size_t * out_len)" +Convert an UCS2 string to a UTF-8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UCS2 string to convert\&. +.br +\fIin_len\fP the length of the in UCS2 string\&. +.br +\fIout\fP the resulting UTF-8 strint, must be at least \fBwind_ucs2utf8_length()\fP long\&. If out is NULL, the function will calculate the needed space for the out variable (just like \fBwind_ucs2utf8_length()\fP)\&. +.br +\fIout_len\fP before processing out_len should be the length of the out variable, after processing it will be the length of the out string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_ucs2utf8_length (const uint16_t * in, size_t in_len, size_t * out_len)" +Calculate the length of from converting a UCS2 string to an UTF-8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UCS2 string to convert\&. +.br +\fIin_len\fP an UCS2 string length to convert\&. +.br +\fIout_len\fP the length of the resulting UTF-8 string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_ucs2write (const uint16_t * in, size_t in_len, unsigned int * flags, void * ptr, size_t * out_len)" +Write an UCS2 string to a buffer\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP The input UCS2 string\&. +.br +\fIin_len\fP the length of the input buffer\&. +.br +\fIflags\fP Flags to control the behavior of the function\&. +.br +\fIptr\fP The input buffer to write to, the array must be at least (in + 1) * 2 bytes long\&. +.br +\fIout_len\fP the output length +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise\&. +.RE +.PP +If in buffer is not of length be mod 2, WIND_ERR_LENGTH_NOT_MOD2 is returned +.PP +On zero input length, flags are preserved +.PP +If flags have WIND_RW_BOM set, the byte order mark is written first to the output data +.PP +If the output wont fit into out_len, WIND_ERR_OVERRUN is returned +.SS "int wind_ucs4utf8 (const uint32_t * in, size_t in_len, char * out, size_t * out_len)" +Convert an UCS4 string to a UTF-8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UCS4 string to convert\&. +.br +\fIin_len\fP the length input array\&. +.br +\fIout\fP the resulting UTF-8 strint, must be at least \fBwind_ucs4utf8_length()\fP + 1 long (the extra char for the NUL)\&. If out is NULL, the function will calculate the needed space for the out variable (just like \fBwind_ucs4utf8_length()\fP)\&. +.br +\fIout_len\fP before processing out_len should be the length of the out variable, after processing it will be the length of the out string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_ucs4utf8_length (const uint32_t * in, size_t in_len, size_t * out_len)" +Calculate the length of from converting a UCS4 string to an UTF-8 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UCS4 string to convert\&. +.br +\fIin_len\fP the length of UCS4 string to convert\&. +.br +\fIout_len\fP the length of the resulting UTF-8 string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_utf8ucs2 (const char * in, uint16_t * out, size_t * out_len)" +Convert an UTF-8 string to an UCS2 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UTF-8 string to convert\&. +.br +\fIout\fP the resulting UCS2 strint, must be at least \fBwind_utf8ucs2_length()\fP long\&. If out is NULL, the function will calculate the needed space for the out variable (just like \fBwind_utf8ucs2_length()\fP)\&. +.br +\fIout_len\fP before processing out_len should be the length of the out variable, after processing it will be the length of the out string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_utf8ucs2_length (const char * in, size_t * out_len)" +Calculate the length of from converting a UTF-8 string to a UCS2 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UTF-8 string to convert\&. +.br +\fIout_len\fP the length of the resulting UCS4 string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_utf8ucs4 (const char * in, uint32_t * out, size_t * out_len)" +Convert an UTF-8 string to an UCS4 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UTF-8 string to convert\&. +.br +\fIout\fP the resulting UCS4 strint, must be at least \fBwind_utf8ucs4_length()\fP long\&. If out is NULL, the function will calculate the needed space for the out variable (just like \fBwind_utf8ucs4_length()\fP)\&. +.br +\fIout_len\fP before processing out_len should be the length of the out variable, after processing it will be the length of the out string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SS "int wind_utf8ucs4_length (const char * in, size_t * out_len)" +Calculate the length of from converting a UTF-8 string to a UCS4 string\&. +.PP +\fBParameters\fP +.RS 4 +\fIin\fP an UTF-8 string to convert\&. +.br +\fIout_len\fP the length of the resulting UCS4 string\&. +.RE +.PP +\fBReturns\fP +.RS 4 +returns 0 on success, an wind error code otherwise +.RE +.PP + +.SH "Author" +.PP +Generated automatically by Doxygen for Heimdal wind library from the source code\&. diff --git a/static/netbsd/man3/wind_profile.3 b/static/netbsd/man3/wind_profile.3 new file mode 100644 index 00000000..38f1a91a --- /dev/null +++ b/static/netbsd/man3/wind_profile.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_profile.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_punycode_label_toascii.3 b/static/netbsd/man3/wind_punycode_label_toascii.3 new file mode 100644 index 00000000..990671a4 --- /dev/null +++ b/static/netbsd/man3/wind_punycode_label_toascii.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_punycode_label_toascii.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_stringprep.3 b/static/netbsd/man3/wind_stringprep.3 new file mode 100644 index 00000000..6cc61842 --- /dev/null +++ b/static/netbsd/man3/wind_stringprep.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_stringprep.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs2read.3 b/static/netbsd/man3/wind_ucs2read.3 new file mode 100644 index 00000000..4d6be451 --- /dev/null +++ b/static/netbsd/man3/wind_ucs2read.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs2read.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs2utf8.3 b/static/netbsd/man3/wind_ucs2utf8.3 new file mode 100644 index 00000000..f3e4b5c7 --- /dev/null +++ b/static/netbsd/man3/wind_ucs2utf8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs2utf8.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs2utf8_length.3 b/static/netbsd/man3/wind_ucs2utf8_length.3 new file mode 100644 index 00000000..287106e1 --- /dev/null +++ b/static/netbsd/man3/wind_ucs2utf8_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs2utf8_length.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs2write.3 b/static/netbsd/man3/wind_ucs2write.3 new file mode 100644 index 00000000..9a593468 --- /dev/null +++ b/static/netbsd/man3/wind_ucs2write.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs2write.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs4utf8.3 b/static/netbsd/man3/wind_ucs4utf8.3 new file mode 100644 index 00000000..3cfb408f --- /dev/null +++ b/static/netbsd/man3/wind_ucs4utf8.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs4utf8.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_ucs4utf8_length.3 b/static/netbsd/man3/wind_ucs4utf8_length.3 new file mode 100644 index 00000000..db376c44 --- /dev/null +++ b/static/netbsd/man3/wind_ucs4utf8_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_ucs4utf8_length.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_utf8ucs2.3 b/static/netbsd/man3/wind_utf8ucs2.3 new file mode 100644 index 00000000..237cf467 --- /dev/null +++ b/static/netbsd/man3/wind_utf8ucs2.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_utf8ucs2.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_utf8ucs2_length.3 b/static/netbsd/man3/wind_utf8ucs2_length.3 new file mode 100644 index 00000000..76d1dd07 --- /dev/null +++ b/static/netbsd/man3/wind_utf8ucs2_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_utf8ucs2_length.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_utf8ucs4.3 b/static/netbsd/man3/wind_utf8ucs4.3 new file mode 100644 index 00000000..d1519e29 --- /dev/null +++ b/static/netbsd/man3/wind_utf8ucs4.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_utf8ucs4.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wind_utf8ucs4_length.3 b/static/netbsd/man3/wind_utf8ucs4_length.3 new file mode 100644 index 00000000..5de0d48a --- /dev/null +++ b/static/netbsd/man3/wind_utf8ucs4_length.3 @@ -0,0 +1,3 @@ +.\" $NetBSD: wind_utf8ucs4_length.3,v 1.2 2019/12/15 22:50:46 christos Exp $ +.\" +.so man3/wind.3 diff --git a/static/netbsd/man3/wmemchr.3 b/static/netbsd/man3/wmemchr.3 new file mode 100644 index 00000000..d1bd957f --- /dev/null +++ b/static/netbsd/man3/wmemchr.3 @@ -0,0 +1,219 @@ +.\" $NetBSD: wmemchr.3,v 1.19 2024/11/01 16:36:58 nia Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strcpy.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 30, 2023 +.Dt WMEMCHR 3 +.Os +.Sh NAME +.Nm wmemchr , +.Nm wmemcmp , +.Nm wmemcpy , +.Nm wmemmove , +.Nm wmempcpy , +.Nm wmemset , +.Nm wcscat , +.Nm wcschr , +.Nm wcscmp , +.Nm wcscpy , +.Nm wcscspn , +.Nm wcslcat , +.Nm wcslcpy , +.Nm wcslen , +.Nm wcsncat , +.Nm wcsncmp , +.Nm wcsncpy , +.Nm wcsnlen , +.Nm wcspbrk , +.Nm wcsrchr , +.Nm wcsspn , +.Nm wcsstr , +.Nm wcswcs +.Nd wide-character string manipulation operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft wchar_t * +.Fn wmemchr "const wchar_t *s" "wchar_t c" "size_t n" +.Ft int +.Fn wmemcmp "const wchar_t *s1" "const wchar_t *s2" "size_t n" +.Ft wchar_t * +.Fn wmemcpy "wchar_t * restrict s1" "const wchar_t * restrict s2" "size_t n" +.Ft wchar_t * +.Fn wmemmove "wchar_t *s1" "const wchar_t *s2" "size_t n" +.Ft wchar_t * +.Fn wmempcpy "wchar_t * restrict s1" "const wchar_t * restrict s2" "size_t n" +.Ft wchar_t * +.Fn wmemset "wchar_t *s" "wchar_t c" "size_t n" +.Ft wchar_t * +.Fn wcscat "wchar_t * restrict s1" "const wchar_t * restrict s2" +.Ft wchar_t * +.Fn wcschr "const wchar_t *s" "wchar_t c" +.Ft int +.Fn wcscmp "const wchar_t *s1" "const wchar_t *s2" +.Ft wchar_t * +.Fn wcscpy "wchar_t * restrict s1" "const wchar_t * restrict s2" +.Ft size_t +.Fn wcscspn "const wchar_t *s1" "const wchar_t *s2" +.Ft size_t +.Fn wcslcat "wchar_t *s1" "const wchar_t *s2" "size_t n" +.Ft size_t +.Fn wcslcpy "wchar_t *s1" "const wchar_t *s2" "size_t n" +.Ft size_t +.Fn wcslen "const wchar_t *s" +.Ft wchar_t * +.Fn wcsncat "wchar_t * restrict s1" "const wchar_t * restrict s2" "size_t n" +.Ft int +.Fn wcsncmp "const wchar_t *s1" "const wchar_t * s2" "size_t n" +.Ft wchar_t * +.Fn wcsncpy "wchar_t * restrict s1" "const wchar_t * restrict s2" "size_t n" +.Ft size_t +.Fn wcsnlen "const wchar_t *s" "size_t maxlen" +.Ft wchar_t * +.Fn wcspbrk "const wchar_t *s1" "const wchar_t *s2" +.Ft wchar_t * +.Fn wcsrchr "const wchar_t *s" "wchar_t c" +.Ft size_t +.Fn wcsspn "const wchar_t *s1" "const wchar_t *s2" +.Ft wchar_t * +.Fn wcsstr "const wchar_t *s1" "const wchar_t *s2" +.Ft wchar_t * +.Fn wcswcs "const wchar_t *s1" "const wchar_t *s2" +.Sh DESCRIPTION +These functions implement string manipulation operations over wide-character +strings. +For a detailed description, refer to the documents for the respective +single-byte counterpart, such as +.Xr memchr 3 . +The +.Fn wcswcs +function is not a part of +.St -isoC +and +.St -isoC-amd1 , +the +.Fn wcsstr +function is strongly recommended to be used. +.Sh SEE ALSO +.Xr memchr 3 , +.Xr memcmp 3 , +.Xr memcpy 3 , +.Xr memmove 3 , +.Xr memset 3 , +.Xr stpcpy 3 , +.Xr stpncpy 3 , +.Xr strcasecmp 3 , +.Xr strcat 3 , +.Xr strchr 3 , +.Xr strcmp 3 , +.Xr strcpy 3 , +.Xr strcspn 3 , +.Xr strdup 3 , +.Xr strlcat 3 , +.Xr strlcpy 3 , +.Xr strlen 3 , +.Xr strncat 3 , +.Xr strncmp 3 , +.Xr strncpy 3 , +.Xr strnlen 3 , +.Xr strpbrk 3 , +.Xr strrchr 3 , +.Xr strspn 3 , +.Xr strstr 3 +.Sh STANDARDS +The +.Fn wmemchr , +.Fn wmemcmp , +.Fn wmemcpy , +.Fn wmemmove , +.Fn wmemset , +.Fn wcscat , +.Fn wcschr , +.Fn wcscmp , +.Fn wcscpy , +.Fn wcscspn , +.Fn wcslen , +.Fn wcsncat , +.Fn wcsncmp , +.Fn wcsncpy , +.Fn wcspbrk , +.Fn wcsrchr , +.Fn wcsspn +and +.Fn wcsstr +functions were first introduced in +.St -isoC-amd1 +and conform to +.St -isoC-99 . +Part of them: +.Fn wmemmove , +.Fn wcscat , +.Fn wcscpy , +.Fn wcsncat +and +.Fn wcsncpy +were modified in +.St -isoC-99 +and gained the +.Dv restrict +keyword in parameter list, +this new version is present in +.Nx . +.Pp +The +.Fn wcswcs +function conforms to +.St -xpg4.2 , +it is recommended to use technically equivalent +.Fn wcsstr +for maximum portability. +.Pp +The +.Fn wcsnlen +function conforms to +.St -p1003.1-2008 . +.Pp +The +.Fn wcslcat +and +.Fn wcslcpy +functions conform to +.St -p1003.1-2024 . +.Pp +The +.Fn wmempcpy +function is a +.Nx +extension. diff --git a/static/netbsd/man3/wordexp.3 b/static/netbsd/man3/wordexp.3 new file mode 100644 index 00000000..cd088dad --- /dev/null +++ b/static/netbsd/man3/wordexp.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: wordexp.3,v 1.5 2022/12/04 01:29:32 uwe Exp $ +.\" +.\" Copyright (c) 2002 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/wordexp.3,v 1.6 2003/09/08 19:57:14 ru Exp $ +.\" +.Dd July 13, 2004 +.Dt WORDEXP 3 +.Os +.Sh NAME +.Nm wordexp +.Nd "perform shell-style word expansions" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wordexp.h +.Ft int +.Fn wordexp "const char * restrict words" "wordexp_t * restrict pwordexp" "int flags" +.Ft void +.Fn wordfree "wordexp_t *pwordexp" +.Sh DESCRIPTION +The +.Fn wordexp +function performs shell-style word expansion on +.Fa words +and places the list of expanded words into the structure pointed to by +.Fa pwordexp . +.Pp +The +.Fa flags +argument is the bitwise inclusive OR of any of the following constants: +.Bl -tag -width ".Dv WRDE_SHOWERR" +.It Dv WRDE_APPEND +Append the words to those generated by a previous call to +.Fn wordexp . +.It Dv WRDE_DOOFFS +As many +.Dv NULL +pointers as are specified by the +.Va we_offs +member of +.Fa we +are added to the front of +.Va we_wordv . +.It Dv WRDE_NOCMD +Disallow command substitution in +.Fa words . +See the note in +.Sx BUGS +before using this. +.It Dv WRDE_REUSE +The +.Fa we +argument was passed to a previous successful call to +.Fn wordexp +but has not been passed to +.Fn wordfree . +The implementation may reuse the space allocated to it. +.It Dv WRDE_SHOWERR +Do not redirect shell error messages to +.Pa /dev/null . +.It Dv WRDE_UNDEF +Report error on an attempt to expand an undefined shell variable. +.El +.Pp +The structure type +.Nm wordexp_t +includes the following members: +.Bd -literal -offset indent +size_t we_wordc +char **we_wordv +size_t we_offs +.Ed +.Pp +The +.Fa we_wordc +member is the count of generated words. +.Pp +The +.Fa we_wordv +member points to a list of pointers to expanded words. +.Pp +The +.Fa we_offs +member is the number of slots to reserve at the beginning of the +.Fa we_wordv +member. +.Pp +It is the caller's responsibility to allocate the storage pointed to by +.Fa pwordexp . +The +.Fn wordexp +function allocates other space as needed, including memory +pointed to by the +.Fa we_wordv +member. +.Pp +The +.Fn wordfree +function frees the memory allocated by +.Fn wordexp . +.Sh IMPLEMENTATION NOTES +The +.Fn wordexp +function is implemented as a wrapper around the undocumented +.Ic wordexp +shell built-in command. +.Sh RETURN VALUES +The +.Fn wordexp +function returns zero if successful, otherwise it returns one of the following +error codes: +.Bl -tag -width ".Dv WRDE_NOSPACE" +.It Dv WRDE_BADCHAR +The +.Fa words +argument contains one of the following unquoted characters: +.Aq newline , +.Ql | , +.Ql & , +.Ql \&; , +.Ql < , +.Ql > , +.Ql \&( , +.Ql \&) , +.Ql { , +.Ql } . +.It Dv WRDE_BADVAL +An attempt was made to expand an undefined shell variable and +.Dv WRDE_UNDEF +is set in +.Fa flags . +.It Dv WRDE_CMDSUB +An attempt was made to use command substitution and +.Dv WRDE_NOCMD +is set in +.Fa flags . +.It Dv WRDE_NOSPACE +Not enough memory to store the result. +.It Dv WRDE_SYNTAX +Shell syntax error in +.Fa words . +.It Dv WRDE_ERRNO +An internal error occurred and +.Va errno +is set to indicate the error. +.El +.Pp +The +.Fn wordfree +function returns no value. +.Sh ENVIRONMENT +.Bl -tag -width ".Ev IFS" +.It Ev IFS +Field separator. +.El +.Sh EXAMPLES +Invoke the editor on all +.Pa .c +files in the current directory +and +.Pa /etc/motd +(error checking omitted): +.Bd -literal -offset indent +wordexp_t we; + +wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0); +execvp(we->we_wordv[0], we->we_wordv); +.Ed +.Sh DIAGNOSTICS \" sic! +Diagnostic messages from the shell are written to the standard error output +if +.Dv WRDE_SHOWERR +is set in +.Fa flags . +.Sh SEE ALSO +.Xr sh 1 , +.Xr fnmatch 3 , +.Xr glob 3 , +.Xr popen 3 , +.Xr system 3 +.Sh STANDARDS +The +.Fn wordexp +and +.Fn wordfree +functions conform to +.St -p1003.1-2001 . +Their first release was in +.St -p1003.2-92 . +The return value +.Dv WRDE_ERRNO +is an extension. +.Sh BUGS +Do not pass untrusted user data to +.Fn wordexp , +regardless of whether the +.Dv WRDE_NOCMD +flag is set. +The +.Fn wordexp +function attempts to detect input that would cause commands to be +executed before passing it to the shell +but it does not use the same parser so it may be fooled. diff --git a/static/netbsd/man3/wprintf.3 b/static/netbsd/man3/wprintf.3 new file mode 100644 index 00000000..c0edcb96 --- /dev/null +++ b/static/netbsd/man3/wprintf.3 @@ -0,0 +1,618 @@ +.\" $NetBSD: wprintf.3,v 1.9 2021/02/16 14:44:25 riastradh Exp $ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 +.\" FreeBSD: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp +.\" $FreeBSD: src/lib/libc/stdio/wprintf.3,v 1.5 2003/07/05 07:55:34 tjr Exp $ +.\" +.Dd April 30, 2010 +.Dt WPRINTF 3 +.Os +.Sh NAME +.Nm wprintf , fwprintf , swprintf , +.Nm vwprintf , vfwprintf , vswprintf +.Nd formatted wide character output conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft int +.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ... +.Ft int +.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ... +.Ft int +.Fn wprintf "const wchar_t * restrict format" ... +.In stdarg.h +.Ft int +.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap" +.Ft int +.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap" +.Ft int +.Fn vwprintf "const wchar_t * restrict format" "va_list ap" +.Sh DESCRIPTION +The +.Fn wprintf +family of functions produces output according to a +.Fa format +as described below. +The +.Fn wprintf +and +.Fn vwprintf +functions +write output to +.Dv stdout , +the standard output stream; +.Fn fwprintf +and +.Fn vfwprintf +write output to the given output +.Fa stream ; +.Fn swprintf +and +.Fn vswprintf +write to the wide-character string +.Fa ws . +.Pp +These functions write the output under the control of a +.Fa format +string that specifies how subsequent arguments +(or arguments accessed via the variable-length argument facilities of +.Xr stdarg 3 ) +are converted for output. +.Pp +The +.Fn swprintf +and +.Fn vswprintf +functions will fail if +.Fa n +or more wide characters were requested to be written, +.Pp +The format string is composed of zero or more directives: +ordinary +characters (not +.Cm % ) , +which are copied unchanged to the output stream; +and conversion specifications, each of which results +in fetching zero or more subsequent arguments. +Each conversion specification is introduced by +the +.Cm % +character. +The arguments must correspond properly (after type promotion) +with the conversion specifier. +After the +.Cm % , +the following appear in sequence: +.Bl -bullet +.It +An optional field, consisting of a decimal digit string followed by a +.Cm $ , +specifying the next argument to access. +If this field is not provided, the argument following the last +argument accessed will be used. +Arguments are numbered starting at +.Cm 1 . +If unaccessed arguments in the format string are interspersed with ones that +are accessed the results will be indeterminate. +.It +Zero or more of the following flags: +.Bl -tag -width ".So \ Sc (space)" +.It Sq Cm # +The value should be converted to an +.Dq alternate form . +For +.Cm c , d , i , n , p , s , +and +.Cm u +conversions, this option has no effect. +For +.Cm o +conversions, the precision of the number is increased to force the first +character of the output string to a zero (except if a zero value is printed +with an explicit precision of zero). +For +.Cm x +and +.Cm X +conversions, a non-zero result has the string +.Ql 0x +(or +.Ql 0X +for +.Cm X +conversions) prepended to it. +For +.Cm a , A , e , E , f , F , g , +and +.Cm G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of +those conversions only if a digit follows). +For +.Cm g +and +.Cm G +conversions, trailing zeros are not removed from the result as they +would otherwise be. +.It So Cm 0 Sc (zero) +Zero padding. +For all conversions except +.Cm n , +the converted value is padded on the left with zeros rather than blanks. +If a precision is given with a numeric conversion +.Cm ( d , i , o , u , i , x , +and +.Cm X ) , +the +.Cm 0 +flag is ignored. +.It Sq Cm \- +A negative field width flag; +the converted value is to be left adjusted on the field boundary. +Except for +.Cm n +conversions, the converted value is padded on the right with blanks, +rather than on the left with blanks or zeros. +A +.Cm \- +overrides a +.Cm 0 +if both are given. +.It So "\ " Sc (space) +A blank should be left before a positive number +produced by a signed conversion +.Cm ( a , A , d , e , E , f , F , g , G , +or +.Cm i ) . +.It Sq Cm + +A sign must always be placed before a +number produced by a signed conversion. +A +.Cm + +overrides a space if both are used. +.It Sq Cm ' +Decimal conversions +.Cm ( d , u , +or +.Cm i ) +or the integral portion of a floating point conversion +.Cm ( f +or +.Cm F ) +should be grouped and separated by thousands using +the non-monetary separator returned by +.Xr localeconv 3 . +.El +.It +An optional decimal digit string specifying a minimum field width. +If the converted value has fewer characters than the field width, it will +be padded with spaces on the left (or right, if the left-adjustment +flag has been given) to fill out +the field width. +.It +An optional precision, in the form of a period +.Cm \&. +followed by an +optional digit string. +If the digit string is omitted, the precision is taken as zero. +This gives the minimum number of digits to appear for +.Cm d , i , o , u , x , +and +.Cm X +conversions, the number of digits to appear after the decimal-point for +.Cm a , A , e , E , f , +and +.Cm F +conversions, the maximum number of significant digits for +.Cm g +and +.Cm G +conversions, or the maximum number of characters to be printed from a +string for +.Cm s +conversions. +.It +An optional length modifier, that specifies the size of the argument. +The following length modifiers are valid for the +.Cm d , i , n , o , u , x , +or +.Cm X +conversion: +.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" +.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n +.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" +.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" +.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" +.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" +.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" +.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" +.It Cm z Ta (see note) Ta Vt size_t Ta (see note) +.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" +.El +.Pp +Note: +the +.Cm t +modifier, when applied to a +.Cm o , u , x , +or +.Cm X +conversion, indicates that the argument is of an unsigned type +equivalent in size to a +.Vt ptrdiff_t . +The +.Cm z +modifier, when applied to a +.Cm d +or +.Cm i +conversion, indicates that the argument is of a signed type equivalent in +size to a +.Vt size_t . +Similarly, when applied to an +.Cm n +conversion, it indicates that the argument is a pointer to a signed type +equivalent in size to a +.Vt size_t . +.Pp +The following length modifier is valid for the +.Cm a , A , e , E , f , F , g , +or +.Cm G +conversion: +.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" +.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G +.It Cm L Ta Vt "long double" +.El +.Pp +The following length modifier is valid for the +.Cm c +or +.Cm s +conversion: +.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" +.It Sy Modifier Ta Cm c Ta Cm s +.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" +.El +.It +A character that specifies the type of conversion to be applied. +.El +.Pp +A field width or precision, or both, may be indicated by +an asterisk +.Ql * +or an asterisk followed by one or more decimal digits and a +.Ql $ +instead of a +digit string. +In this case, an +.Vt int +argument supplies the field width or precision. +A negative field width is treated as a left adjustment flag followed by a +positive field width; a negative precision is treated as though it were +missing. +If a single format directive mixes positional +.Pq Li nn$ +and non-positional arguments, the results are undefined. +.Pp +The conversion specifiers and their meanings are: +.Bl -tag -width ".Cm diouxX" +.It Cm diouxX +The +.Vt int +(or appropriate variant) argument is converted to signed decimal +.Cm ( d +and +.Cm i ) , +unsigned octal +.Pq Cm o , +unsigned decimal +.Pq Cm u , +or unsigned hexadecimal +.Cm ( x +and +.Cm X ) +notation. +The letters +.Dq Li abcdef +are used for +.Cm x +conversions; the letters +.Dq Li ABCDEF +are used for +.Cm X +conversions. +The precision, if any, gives the minimum number of digits that must +appear; if the converted value requires fewer digits, it is padded on +the left with zeros. +.It Cm DOU +The +.Vt "long int" +argument is converted to signed decimal, unsigned octal, or unsigned +decimal, as if the format had been +.Cm ld , lo , +or +.Cm lu +respectively. +These conversion characters are deprecated, and will eventually disappear. +.It Cm eE +The +.Vt double +argument is rounded and converted in the style +.Sm off +.Oo \- Oc Ar d Li \&. Ar ddd Li e \*[Pm] Ar dd +.Sm on +where there is one digit before the +decimal-point character +and the number of digits after it is equal to the precision; +if the precision is missing, +it is taken as 6; if the precision is +zero, no decimal-point character appears. +An +.Cm E +conversion uses the letter +.Ql E +(rather than +.Ql e ) +to introduce the exponent. +The exponent always contains at least two digits; if the value is zero, +the exponent is 00. +.Pp +For +.Cm a , A , e , E , f , F , g , +and +.Cm G +conversions, positive and negative infinity are represented as +.Li inf +and +.Li -inf +respectively when using the lowercase conversion character, and +.Li INF +and +.Li -INF +respectively when using the uppercase conversion character. +Similarly, NaN is represented as +.Li nan +when using the lowercase conversion, and +.Li NAN +when using the uppercase conversion. +.It Cm fF +The +.Vt double +argument is rounded and converted to decimal notation in the style +.Sm off +.Oo \- Oc Ar ddd Li \&. Ar ddd , +.Sm on +where the number of digits after the decimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as 6; if the precision is +explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.It Cm gG +The +.Vt double +argument is converted in style +.Cm f +or +.Cm e +(or +.Cm F +or +.Cm E +for +.Cm G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.Cm e +is used if the exponent from its conversion is less than \-4 or greater than +or equal to the precision. +Trailing zeros are removed from the fractional part of the result; a +decimal point appears only if it is followed by at least one digit. +.It Cm aA +The +.Vt double +argument is converted to hexadecimal notation in the style +.Sm off +.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \*[Pm] Oc Ar d , +.Sm on +where the number of digits after the hexadecimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as enough to exactly +represent the floating-point number; if the precision is +explicitly zero, no hexadecimal-point character appears. +This is an exact conversion of the significand+exponent internal +floating point representation; the +.Sm off +.Oo \- Oc Li 0x Ar h Li \&. Ar hhh +.Sm on +portion represents exactly the significand; only in subnormal numbers do +significands have a zero value to the left of the hexadecimal +point. +The +.Cm p +is a literal character +.Ql p ; +the exponent is preceded by a positive or negative sign +and is represented in decimal, using only enough characters +to represent the exponent. +The +.Cm A +conversion uses the prefix +.Dq Li 0X +(rather than +.Dq Li 0x ) , +the letters +.Dq Li ABCDEF +(rather than +.Dq Li abcdef ) +to represent the hex digits, and the letter +.Ql P +(rather than +.Ql p ) +to separate the significand and exponent. +.It Cm C +Treated as +.Cm c +with the +.Cm l +(ell) modifier. +.It Cm c +The +.Vt int +argument is converted to an +.Vt "unsigned char" , +then to a +.Vt wchar_t +as if by +.Xr btowc 3 , +and the resulting character is written. +.Pp +If the +.Cm l +(ell) modifier is used, the +.Vt wint_t +argument is converted to a +.Vt wchar_t +and written. +.It Cm S +Treated as +.Cm s +with the +.Cm l +(ell) modifier. +.It Cm s +The +.Vt "char *" +argument is expected to be a pointer to an array of character type (pointer +to a string) containing a multibyte sequence. +Characters from the array are converted to wide characters and written up to +(but not including) +a terminating +.Dv NUL +character; +if a precision is specified, no more than the number specified are +written. +If a precision is given, no null character +need be present; if the precision is not specified, or is greater than +the size of the array, the array must contain a terminating +.Dv NUL +character. +.Pp +If the +.Cm l +(ell) modifier is used, the +.Vt "wchar_t *" +argument is expected to be a pointer to an array of wide characters +(pointer to a wide string). +Each wide character in the string +is written. +Wide characters from the array are written up to (but not including) +a terminating wide +.Dv NUL +character; +if a precision is specified, no more than the number specified are +written (including shift sequences). +If a precision is given, no null character +need be present; if the precision is not specified, or is greater than +the number of characters in +the string, the array must contain a terminating wide +.Dv NUL +character. +.It Cm p +The +.Vt "void *" +pointer argument is printed in hexadecimal (as if by +.Ql %#x +or +.Ql %#lx ) . +.It Cm n +The number of characters written so far is stored into the +integer indicated by the +.Vt "int *" +(or variant) pointer argument. +No argument is converted. +.It Cm % +A +.Ql % +is written. +No argument is converted. +The complete conversion specification +is +.Ql %% . +.El +.Pp +The decimal point +character is defined in the program's locale (category +.Dv LC_NUMERIC ) . +.Pp +In no case does a non-existent or small field width cause truncation of +a numeric field; if the result of a conversion is wider than the field +width, the +field is expanded to contain the conversion result. +.Sh RETURN VALUES +These functions return the number of characters printed +(not including the trailing +.Ql \e0 +used to end output to strings). +.Sh SEE ALSO +.Xr btowc 3 , +.Xr fputws 3 , +.Xr printf 3 , +.Xr putwc 3 , +.Xr setlocale 3 , +.Xr wcsrtombs 3 , +.Xr wscanf 3 +.Sh STANDARDS +The +.Fn wprintf , +.Fn fwprintf , +.Fn swprintf , +.Fn vwprintf , +.Fn vfwprintf +and +.Fn vswprintf +functions +conform to +.St -isoC-99 . +.Sh SECURITY CONSIDERATIONS +Subject to the caveats noted in the +.Xr printf 3 . diff --git a/static/netbsd/man3/wscanf.3 b/static/netbsd/man3/wscanf.3 new file mode 100644 index 00000000..9b53ef81 --- /dev/null +++ b/static/netbsd/man3/wscanf.3 @@ -0,0 +1,484 @@ +.\" $NetBSD: wscanf.3,v 1.3 2010/12/16 17:42:27 wiz Exp $ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93 +.\" FreeBSD: src/lib/libc/stdio/scanf.3,v 1.24 2003/06/28 09:03:25 das Exp +.\" $FreeBSD: src/lib/libc/stdio/wscanf.3,v 1.6 2003/07/05 07:47:55 tjr Exp $ +.\" +.Dd July 5, 2003 +.Dt WSCANF 3 +.Os +.Sh NAME +.Nm wscanf , +.Nm fwscanf , +.Nm swscanf , +.Nm vwscanf , +.Nm vswscanf , +.Nm vfwscanf +.Nd wide character input format conversion +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.In wchar.h +.Ft int +.Fn wscanf "const wchar_t * restrict format" ... +.Ft int +.Fn fwscanf "FILE * restrict stream" "const wchar_t * restrict format" ... +.Ft int +.Fn swscanf "const wchar_t * restrict str" "const wchar_t * restrict format" ... +.In stdarg.h +.Ft int +.Fn vwscanf "const wchar_t * restrict format" "va_list ap" +.Ft int +.Fn vswscanf "const wchar_t * restrict str" "const wchar_t * restrict format" "va_list ap" +.Ft int +.Fn vfwscanf "FILE * restrict stream" "const wchar_t * restrict format" "va_list ap" +.Sh DESCRIPTION +The +.Fn wscanf +family of functions scans input according to a +.Fa format +as described below. +This format may contain +.Em conversion specifiers ; +the results from such conversions, if any, +are stored through the +.Em pointer +arguments. +The +.Fn wscanf +function +reads input from the standard input stream +.Dv stdin , +.Fn fwscanf +reads input from the stream pointer +.Fa stream , +and +.Fn swscanf +reads its input from the wide-character string pointed to by +.Fa str . +The +.Fn vfwscanf +function +is analogous to +.Xr vfwprintf 3 +and reads input from the stream pointer +.Fa stream +using a variable argument list of pointers (see +.Xr stdarg 3 ) . +The +.Fn vwscanf +function scans a variable argument list from the standard input and +the +.Fn vswscanf +function scans it from a wide-character string; +these are analogous to +the +.Fn vwprintf +and +.Fn vswprintf +functions respectively. +Each successive +.Em pointer +argument must correspond properly with +each successive conversion specifier +(but see the +.Cm * +conversion below). +All conversions are introduced by the +.Cm % +(percent sign) character. +The +.Fa format +string +may also contain other characters. +White space (such as blanks, tabs, or newlines) in the +.Fa format +string match any amount of white space, including none, in the input. +Everything else +matches only itself. +Scanning stops +when an input character does not match such a format character. +Scanning also stops +when an input conversion cannot be made (see below). +.Sh CONVERSIONS +Following the +.Cm % +character introducing a conversion +there may be a number of +.Em flag +characters, as follows: +.Bl -tag -width ".Cm l No (ell)" +.It Cm * +Suppresses assignment. +The conversion that follows occurs as usual, but no pointer is used; +the result of the conversion is simply discarded. +.It Cm hh +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt char +(rather than +.Vt int ) . +.It Cm h +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt "short int" +(rather than +.Vt int ) . +.It Cm l No (ell) +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt "long int" +(rather than +.Vt int ) , +that the conversion will be one of +.Cm a , e , f , +or +.Cm g +and the next pointer is a pointer to +.Vt double +(rather than +.Vt float ) , +or that the conversion will be one of +.Cm c +or +.Cm s +and the next pointer is a pointer to an array of +.Vt wchar_t +(rather than +.Vt char ) . +.It Cm ll No (ell ell) +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt "long long int" +(rather than +.Vt int ) . +.It Cm L +Indicates that the conversion will be one of +.Cm a , e , f , +or +.Cm g +and the next pointer is a pointer to +.Vt "long double" . +.It Cm j +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt intmax_t +(rather than +.Vt int ) . +.It Cm t +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt ptrdiff_t +(rather than +.Vt int ) . +.It Cm z +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt size_t +(rather than +.Vt int ) . +.It Cm q +(deprecated.) +Indicates that the conversion will be one of +.Cm dioux +or +.Cm n +and the next pointer is a pointer to a +.Vt "long long int" +(rather than +.Vt int ) . +.El +.Pp +In addition to these flags, +there may be an optional maximum field width, +expressed as a decimal integer, +between the +.Cm % +and the conversion. +If no width is given, +a default of +.Dq infinity +is used (with one exception, below); +otherwise at most this many characters are scanned +in processing the conversion. +Before conversion begins, +most conversions skip white space; +this white space is not counted against the field width. +.Pp +The following conversions are available: +.Bl -tag -width XXXX +.It Cm % +Matches a literal +.Ql % . +That is, +.Dq Li %% +in the format string +matches a single input +.Ql % +character. +No conversion is done, and assignment does not occur. +.It Cm d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.Vt int . +.It Cm i +Matches an optionally signed integer; +the next pointer must be a pointer to +.Vt int . +The integer is read in base 16 if it begins +with +.Ql 0x +or +.Ql 0X , +in base 8 if it begins with +.Ql 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.It Cm o +Matches an octal integer; +the next pointer must be a pointer to +.Vt "unsigned int" . +.It Cm u +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.Vt "unsigned int" . +.It Cm x , X +Matches an optionally signed hexadecimal integer; +the next pointer must be a pointer to +.Vt "unsigned int" . +.It Cm a , A , e , E , f , F , g , G +Matches a floating-point number in the style of +.Xr wcstod 3 . +The next pointer must be a pointer to +.Vt float +(unless +.Cm l +or +.Cm L +is specified.) +.It Cm s +Matches a sequence of non-white-space wide characters; +the next pointer must be a pointer to +.Vt char , +and the array must be large enough to accept the multibyte representation +of all the sequence and the +terminating +.Dv NUL +character. +The input string stops at white space +or at the maximum field width, whichever occurs first. +.Pp +If an +.Cm l +qualifier is present, the next pointer must be a pointer to +.Vt wchar_t , +into which the input will be placed. +.It Cm S +The same as +.Cm ls . +.It Cm c +Matches a sequence of +.Em width +count +wide characters (default 1); +the next pointer must be a pointer to +.Vt char , +and there must be enough room for the multibyte representation +of all the characters +(no terminating +.Dv NUL +is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.Pp +If an +.Cm l +qualifier is present, the next pointer must be a pointer to +.Vt wchar_t , +into which the input will be placed. +.It Cm C +The same as +.Cm lc . +.It Cm \&[ +Matches a nonempty sequence of characters from the specified set +of accepted characters; +the next pointer must be a pointer to +.Vt char , +and there must be enough room for the multibyte representation of +all the characters in the string, +plus a terminating +.Dv NUL +character. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in +(or not in) +a particular set; +the set is defined by the characters between the open bracket +.Cm \&[ +character +and a close bracket +.Cm \&] +character. +The set +.Em excludes +those characters +if the first character after the open bracket is a circumflex +.Cm ^ . +To include a close bracket in the set, +make it the first character after the open bracket +or the circumflex; +any other position will end the set. +To include a hyphen in the set, +make it the last character before the final close bracket; +some implementations of +.Fn wscanf +use +.Dq Li A-Z +to represent the range of characters between +.Ql A +and +.Ql Z . +The string ends with the appearance of a character not in the +(or, with a circumflex, in) set +or when the field width runs out. +.Pp +If an +.Cm l +qualifier is present, the next pointer must be a pointer to +.Vt wchar_t , +into which the input will be placed. +.It Cm p +Matches a pointer value (as printed by +.Ql %p +in +.Xr wprintf 3 ) ; +the next pointer must be a pointer to +.Vt void . +.It Cm n +Nothing is expected; +instead, the number of characters consumed thus far from the input +is stored through the next pointer, +which must be a pointer to +.Vt int . +This is +.Em not +a conversion, although it can be suppressed with the +.Cm * +flag. +.El +.Pp +The decimal point +character is defined in the program's locale (category +.Dv LC_NUMERIC ) . +.Pp +For backwards compatibility, a +.Dq conversion +of +.Ql %\e0 +causes an immediate return of +.Dv EOF . +.Sh RETURN VALUES +These +functions +return +the number of input items assigned, which can be fewer than provided +for, or even zero, in the event of a matching failure. +Zero +indicates that, while there was input available, +no conversions were assigned; +typically this is due to an invalid input character, +such as an alphabetic character for a +.Ql %d +conversion. +The value +.Dv EOF +is returned if an input failure occurs before any conversion such as an +end-of-file occurs. +If an error or end-of-file occurs after conversion +has begun, +the number of conversions which were successfully completed is returned. +.Sh SEE ALSO +.Xr fgetwc 3 , +.Xr scanf 3 , +.Xr wcrtomb 3 , +.Xr wcstod 3 , +.Xr wcstol 3 , +.Xr wcstoul 3 , +.Xr wprintf 3 +.Sh STANDARDS +The +.Fn fwscanf , +.Fn wscanf , +.Fn swscanf , +.Fn vfwscanf , +.Fn vwscanf +and +.Fn vswscanf +functions +conform to +.St -isoC-99 . +.Sh BUGS +In addition to the bugs documented in +.Xr scanf 3 , +.Fn wscanf +does not support the +.Dq Li A-Z +notation for specifying character ranges with the character +class conversion +.Pq Sq Cm %[ . diff --git a/static/netbsd/man3/xdr.3 b/static/netbsd/man3/xdr.3 new file mode 100644 index 00000000..99c822d3 --- /dev/null +++ b/static/netbsd/man3/xdr.3 @@ -0,0 +1,522 @@ +.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI +.\" $NetBSD: xdr.3,v 1.14 2011/07/08 19:28:22 wiz Exp $ +.\" +.Dd July 4, 2011 +.Dt XDR 3 +.Os +.Sh NAME +.Nm xdr , +.Nm xdr_array , +.Nm xdr_bool , +.Nm xdr_bytes , +.Nm xdr_char , +.Nm xdr_destroy , +.Nm xdr_double , +.Nm xdr_enum , +.Nm xdr_float , +.Nm xdr_free , +.Nm xdr_getpos , +.Nm xdr_hyper , +.Nm xdr_inline , +.Nm xdr_int , +.Nm xdr_long , +.Nm xdr_longlong_t , +.Nm xdrmem_create , +.Nm xdr_opaque , +.Nm xdr_pointer , +.Nm xdrrec_create , +.Nm xdrrec_endofrecord , +.Nm xdrrec_eof , +.Nm xdrrec_skiprecord , +.Nm xdr_reference , +.Nm xdr_setpos , +.Nm xdr_short , +.Nm xdr_sizeof , +.Nm xdrstdio_create , +.Nm xdr_string , +.Nm xdr_u_char , +.Nm xdr_u_hyper , +.Nm xdr_u_long , +.Nm xdr_u_longlong_t , +.Nm xdr_u_short , +.Nm xdr_union , +.Nm xdr_vector , +.Nm xdr_void , +.Nm xdr_wrapstring +.Nd library routines for external data representation +.Sh SYNOPSIS +.Ft int +.Fn xdr_array "XDR *xdrs" "char **arrp" "u_int *sizep" "u_int maxsize" \ +"u_int elsize" "xdrproc_t elproc" +.Ft int +.Fn xdr_bool "XDR *xdrs" "bool_t *bp" +.Ft int +.Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize" +.Ft int +.Fn xdr_char "XDR *xdrs" "char *cp" +.Ft void +.Fn xdr_destroy "XDR *xdrs" +.Ft int +.Fn xdr_double "XDR *xdrs" "double *dp" +.Ft int +.Fn xdr_enum "XDR *xdrs" "enum_t *ep" +.Ft int +.Fn xdr_float "XDR *xdrs" "float *fp" +.Ft void +.Fn xdr_free "xdrproc_t proc" "char *objp" +.Ft u_int +.Fn xdr_getpos "XDR *xdrs" +.Ft int +.Fn xdr_hyper "XDR *xdrs" "longlong_t *llp" +.Ft long * +.Fn xdr_inline "XDR *xdrs" "int len" +.Ft int +.Fn xdr_int "XDR *xdrs" "int *ip" +.Ft int +.Fn xdr_long "XDR *xdrs" "long *lp" +.Ft int +.Fn xdr_longlong_t "XDR *xdrs" "longlong_t *llp" +.Ft void +.Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" \ +"enum xdr_op op" +.Ft int +.Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt" +.Ft int +.Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" \ +"xdrproc_t xdrobj" +.Ft void +.Fn xdrrec_create "XDR *xdrs" "u_int sendsize" "u_int recvsize" \ +"char *handle" "int (*readit)()" "int (*writeit)()" +.Ft int +.Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow" +.Ft int +.Fn xdrrec_eof "XDR *xdrs" +.Ft int +.Fn xdrrec_skiprecord "XDR *xdrs" +.Ft int +.Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" \ +"xdrproc_t proc" +.Ft int +.Fn xdr_setpos "XDR *xdrs" "u_int pos" +.Ft int +.Fn xdr_short "XDR *xdrs" "short *sp" +.Ft nsigned long +.Fn xdr_sizeof "xdrproc_t func" "void *data" +.Ft void +.Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op" +.Ft int +.Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize" +.Ft int +.Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp" +.Ft int +.Fn xdr_u_hyper "XDR *xdrs" "u_longlong_t *ullp" +.Ft int +.Fn xdr_u_int "XDR *xdrs" "unsigned *up" +.Ft int +.Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp" +.Ft int +.Fn xdr_u_longlong_t "XDR *xdrs" "u_longlong_t *ullp" +.Ft int +.Fn xdr_u_short "XDR *xdrs" "unsigned short *usp" +.Ft int +.Fn xdr_union "XDR *xdrs" "int *dscmp" "char *unp" \ +"struct xdr_discrim *choices" "bool_t (*defaultarm)(\|)" +.Ft int +.Fn xdr_vector "XDR *xdrs" "char *arrp" "u_int size" \ +"u_int elsize" "xdrproc_t elproc" +.Ft int +.Fn xdr_void "void" +.Ft int +.Fn xdr_wrapstring "XDR *xdrs" "char **sp" +.Sh DESCRIPTION +These routines allow C programmers to describe +arbitrary data structures in a machine-independent fashion. +Data for remote procedure calls are transmitted using these +routines. +.Bl -tag -width xxx +.It Fn xdr_array +A filter primitive that translates between variable-length +arrays and their corresponding external representations. +The parameter +.Fa arrp +is the address of the pointer to the array, while +.Fa sizep +is the address of the element count of the array; +this element count cannot exceed +.Fa maxsize . +The parameter +.Fa elsize +is the +.Em sizeof +each of the array's elements, and +.Fa elproc +is an XDR filter that translates between the array elements' C form, +and their external representation. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_bool +A filter primitive that translates between booleans (C integers) +and their external representations. +When encoding data, this filter produces values of either one or +zero. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_bytes +A filter primitive that translates between counted byte +strings and their external representations. +The parameter +.Fa sp +is the address of the string pointer. +The length of the string is located at address +.Fa sizep ; +strings cannot be longer than +.Fa maxsize . +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_char +A filter primitive that translates between C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to consider +.Fn xdr_bytes , +.Fn xdr_opaque +or +.Fn xdr_string . +.It Fn xdr_destroy +A macro that invokes the destroy routine associated with the XDR +stream, +.Fa xdrs . +Destruction usually involves freeing private data structures +associated with the stream. +Using +.Fa xdrs +after invoking +.Fn xdr_destroy +is undefined. +.It Fn xdr_double +A filter primitive that translates between C double precision numbers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_enum +A filter primitive that translates between C enums (actually integers) +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_float +A filter primitive that translates between C floats +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_free +Generic freeing routine. +The first argument is the XDR routine for the object being freed. +The second argument is a pointer to the object itself. +Note: the pointer passed to this routine is +.Em not +freed, but what it points to +.Em is +freed (recursively). +.It Fn xdr_getpos +A macro that invokes the get-position routine associated with the XDR +stream, +.Fa xdrs . +The routine returns an unsigned integer, which indicates the position +of the XDR byte stream. +A desirable feature of XDR streams is that simple arithmetic works +with this number, although the XDR stream instances need not guarantee +this. +.It Fn xdr_hyper +A filter primitive that translates between ANSI C long long integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_inline +A macro that invokes the in-line routine associated with the XDR +stream, +.Fa xdrs . +The routine returns a pointer +to a contiguous piece of the stream's buffer; +.Fa len +is the byte length of the desired buffer. +Note: pointer is cast to +.Vt "long *" . +.Pp +Warning: +.Fn xdr_inline +may return +.Dv NULL +if it cannot allocate a contiguous piece of a buffer. +Therefore the behavior may vary among stream instances; +it exists for the sake of efficiency. +.It Fn xdr_int +A filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_long +A filter primitive that translates between C long integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_longlong_t +A filter primitive that translates between ANSI C long long integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdrmem_create +This routine initializes the XDR stream object pointed to by +.Fa xdrs . +The stream's data is written to, or read from, +a chunk of memory at location +.Fa addr +whose length is no more than +.Fa size +bytes long. +The +.Fa op +determines the direction of the XDR stream (either +.Dv XDR_ENCODE , +.Dv XDR_DECODE , +or +.Dv XDR_FREE ) . +.It Fn xdr_opaque +A filter primitive that translates between fixed size opaque data +and its external representation. +The parameter +.Fa cp +is the address of the opaque object, and +.Fa cnt +is its size in bytes. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_pointer +Like +.Fn xdr_reference +except that it serializes +.Dv NULL +pointers, whereas +.Fn xdr_reference +does not. +Thus, +.Fn xdr_pointer +can represent recursive data structures, such as binary trees or +linked lists. +.It Fn xdrrec_create +This routine initializes the XDR stream object pointed to by +.Fa xdrs . +The stream's data is written to a buffer of size +.Fa sendsize ; +a value of zero indicates the system should use a suitable default. +The stream's data is read from a buffer of size +.Fa recvsize ; +it too can be set to a suitable default by passing a zero value. +When a stream's output buffer is full, +.Fa writeit +is called. +Similarly, when a stream's input buffer is empty, +.Fa readit +is called. +The behavior of these two routines is similar to the system calls +.Xr read 2 +and +.Xr write 2 , +except that +.Fa handle +is passed to the former routines as the first parameter. +Note: the XDR stream's +.Fa op +field must be set by the caller. +.Pp +Warning: this XDR stream implements an intermediate record stream. +Therefore there are additional bytes in the stream +to provide record boundary information. +.It Fn xdrrec_endofrecord +This routine can be invoked only on streams created by +.Fn xdrrec_create . +The data in the output buffer is marked as a completed record, +and the output buffer is optionally written out if +.Fa sendnow +is non-zero. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdrrec_eof +This routine can be invoked only on streams created by +.Fn xdrrec_create . +After consuming the rest of the current record in the stream, +this routine returns one if the stream has no more input, +zero otherwise. +.It Fn xdrrec_skiprecord +This routine can be invoked only on streams created by +.Fn xdrrec_create . +It tells the XDR implementation that the rest of the current record +in the stream's input buffer should be discarded. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_reference +A primitive that provides pointer chasing within structures. +The parameter +.Fa pp +is the address of the pointer; +.Fa size +is the +.Em sizeof +the structure that +.Fa *pp +points to; and +.Fa proc +is an XDR procedure that filters the structure +between its C form and its external representation. +This routine returns one if it succeeds, zero otherwise. +.Pp +Warning: this routine does not understand +.Dv NULL +pointers. +Use +.Fn xdr_pointer +instead. +.It Fn xdr_setpos +A macro that invokes the set position routine associated with the XDR +stream +.Fa xdrs . +The parameter +.Fa pos +is a position value obtained from +.Fn xdr_getpos . +This routine returns one if the XDR stream could be repositioned, +and zero otherwise. +.Pp +Warning: it is difficult to reposition some types of XDR streams, so +this routine may fail with one type of stream and succeed with +another. +.It Fn xdr_short +A filter primitive that translates between C short integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_sizeof +This routine returns the amount of memory required to encode +.Fa data +using filter +.Fa func . +.It Fn xdrstdio_create +This routine initializes the XDR stream object pointed to by +.Fa xdrs . +The XDR stream data is written to, or read from, the Standard I/O +stream +.Fa file . +The parameter +.Fa op +determines the direction of the XDR stream (either +.Dv XDR_ENCODE , +.Dv XDR_DECODE , +or +.Dv XDR_FREE ) . +.Pp +Warning: the destroy routine associated with such XDR streams calls +.Xr fflush 3 +on the file stream, but never +.Xr fclose 3 . +.It Fn xdr_string +A filter primitive that translates between C strings and +their corresponding external representations. +Strings cannot be longer than +.Fa maxsize . +Note: +.Fa sp +is the address of the string's pointer. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_char +A filter primitive that translates between unsigned C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_hyper +A filter primitive that translates between unsigned ANSI C long long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_int +A filter primitive that translates between C unsigned integers + and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_long +A filter primitive that translates between C unsigned long integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_longlong_t +A filter primitive that translates between unsigned ANSI C long long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_u_short +A filter primitive that translates between C unsigned short integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_union +A filter primitive that translates between a discriminated C union +and its corresponding external representation. +It first translates the discriminant of the union located at +.Fa dscmp . +This discriminant is always an enum_t. +Next the union located at +.Fa unp +is translated. +The parameter +.Fa choices +is a pointer to an array of +.Fn xdr_discrim +structures. +Each structure contains an ordered pair of +.Fa [ value , +.Fa proc ] . +If the union's discriminant is equal to the associated +.Fa value , +then the +.Fa proc +is called to translate the union. +The end of the +.Fn xdr_discrim +structure array is denoted by a routine of value +.Dv NULL . +If the discriminant is not found in the +.Fa choices +array, then the +.Fa defaultarm +procedure is called (if it is not +.Dv NULL ) . +Returns one if it succeeds, zero otherwise. +.It Fn xdr_vector +A filter primitive that translates between fixed-length +arrays and their corresponding external representations. +The parameter +.Fa arrp +is the address of the pointer to the array, while +.Fa size +is the element count of the array. +The parameter +.Fa elsize +is the +.Em sizeof +each of the array's elements, and +.Fa elproc +is an XDR filter that translates between the array elements' C form, +and their external representation. +This routine returns one if it succeeds, zero otherwise. +.It Fn xdr_void +This routine always returns one. +It may be passed to RPC routines that require a function parameter, +where nothing is to be done. +.It Fn xdr_wrapstring +A primitive that calls +.Fn xdr_string "xdrs" "sp" "MAXUN.UNSIGNED" ; +where +.Dv MAXUN.UNSIGNED +is the maximum value of an unsigned integer. +.Fn xdr_wrapstring +is handy because the RPC package passes a maximum of two XDR +routines as parameters, and +.Fn xdr_string , +one of the most frequently used primitives, requires three. +Returns one if it succeeds, zero otherwise. +.El +.Sh SEE ALSO +.Xr rpc 3 +.Pp +The following manuals: +.Rs +.%B "eXternal Data Representation Standard: Protocol Specification" +.Re +.Rs +.%B "eXternal Data Representation: Sun Technical Notes" +.Re +.Rs +.%A Sun Microsystems, Inc., USC-ISI +.%T "XDR: External Data Representation Standard" +.%R "RFC 1014, USC-ISI" +.%V 1014 +.Re diff --git a/static/netbsd/man3/ypclnt.3 b/static/netbsd/man3/ypclnt.3 new file mode 100644 index 00000000..567d0656 --- /dev/null +++ b/static/netbsd/man3/ypclnt.3 @@ -0,0 +1,376 @@ +.\" $NetBSD: ypclnt.3,v 1.30 2018/02/11 13:30:55 wiz Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd February 7, 2018 +.Dt YPCLNT 3 +.Os +.Sh NAME +.Nm yp_all , +.Nm yp_bind , +.Nm yp_first , +.Nm yp_get_default_domain , +.Nm yp_master , +.Nm yp_match , +.Nm yp_next , +.Nm yp_order , +.Nm yp_unbind , +.Nm yperr_string , +.Nm ypprot_err , +.Nm yp_setbindtries +.Nd Interface to the YP subsystem +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In rpc/rpc.h +.In rpcsvc/ypclnt.h +.In rpcsvc/yp_prot.h +.Ft int +.Fn yp_all "const char *indomain" "const char *inmap" "struct ypall_callback *incallback" +.Ft int +.Fn yp_bind "const char *dom" +.Ft int +.Fn yp_first "const char *indomain" "const char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_get_default_domain "char **outdomain" +.Ft int +.Fn yp_master "const char *indomain" "const char *inmap" "char **outname" +.Ft int +.Fn yp_match "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_next "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen" +.Ft int +.Fn yp_order "const char *indomain" "const char *inmap" "int *outorder" +.Ft void +.Fn yp_unbind "const char *dom" +.Ft char * +.Fn yperr_string "int incode" +.Ft int +.Fn ypprot_err "unsigned int incode" +.Ft int +.Fn yp_setbindtries "int ntries" +.Sh DESCRIPTION +The +.Nm ypclnt +suite provides an interface to the YP subsystem. +For a general description of the YP subsystem, see +.Xr yp 8 . +.Pp +For all functions, input values begin with +.Pa in +and output values begin with +.Pa out . +.Pp +Any output values of type +.Em char ** +should be the addresses of uninitialized character pointers. +These values will be reset to the null pointer (unless the address +itself is the null pointer, in which case the error +.Er YPERR_BADARGS +will be returned). +If necessary, +memory will be allocated by the YP client routines using +.Fn malloc , +and the result will be stored in the appropriate output value. +If the invocation of a YP client routine doesn't return an error, +and an output value is not the null pointer, then this memory +should be freed by the user when there is no additional need for +the data stored there. +For +.Pa outkey +and +.Pa outval , +two extra bytes of memory are allocated for a +.Ql \en +and +.Ql \e0 , +which are not +reflected in the values of +.Pa outkeylen +or +.Pa outvallen . +.Pp +All occurrences of +.Pa indomain +and +.Pa inmap +must be non-null, NUL-terminated strings. +All input strings which also have +a corresponding length parameter cannot be the null pointer unless the +corresponding length value is zero. +Such strings need not be NUL-terminated. +.Pp +All YP lookup calls (the functions +.Fn yp_all , +.Fn yp_first , +.Fn yp_master , +.Fn yp_match , +.Fn yp_next , +.Fn yp_order ) +require a YP domain name and a YP map name. +The default domain name may be obtained by calling +.Fn yp_get_default_domain , +and should thus be used before all other YP calls in a client program. +The value it places +.Pa outdomain +is suitable for use as the +.Pa indomain +parameter to all subsequent YP calls. +.Pp +In order for YP lookup calls to succeed, the client process must be bound +to a YP server process. +The client process need not explicitly bind to +the server, as it happens automatically whenever a lookup occurs. +The function +.Fn yp_bind +is provided for a backup strategy, e.g. a local file, when a YP +server process is not available. +Each binding uses one socket descriptor on the client +process, which may be explicitly freed using +.Fn yp_unbind , +which frees all per-process and per-node resources to bind the domain and +marks the domain unbound. +.Pp +If, during a YP lookup, an RPC failure occurs, the domain used in the lookup +is automatically marked unbound and the +.Nm ypclnt +layer retries the lookup as long as +.Xr ypbind 8 +is running and either the client process cannot bind to a server for the domain +specified in the lookup, or RPC requests to the YP server process fail. +If an error is not RPC-related, one of the YP error codes described below +is returned and control given back to the user code. +.Pp +The +.Nm ypclnt +suite provides the following functionality: +.Bl -tag -width yp_matchxxxx +.It Fn yp_match +Provides the value associated with the given key. +.It Fn yp_first +Provides the first key-value pair from the given map in the named domain. +.It Fn yp_next +Provides the next key-value pair in the given map. +To obtain the second pair, +the +.Pa inkey +value should be the +.Pa outkey +value provided by the initial call to +.Fn yp_first . +In the general case, the next key-value pair may be obtained by using the +.Pa outkey +value from the previous call to +.Fn yp_next +as the value for +.Pa inkey . +.Pp +Of course, the notions of +.Dq first +and +.Dq next +are particular to the +type of YP map being accessed, and thus there is no guarantee of lexical order. +The only guarantees provided with +.Fn yp_first +and +.Fn yp_next , +providing that the same map on the same server is polled repeatedly until +.Fn yp_next +returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed +exactly once, and if the entire procedure is repeated, the order will be +the same. +.Pp +If the server is heavily loaded or the server fails for some reason, the +domain being used may become unbound. +If this happens, and the client process re-binds, the retrieval rules +will break: some entries may be seen twice, and others not at all. +For this reason, the function +.Fn yp_all +provides a better solution for reading all of the entries in a particular map. +.It Fn yp_all +This function provides a way to transfer an entire map from +the server to the client process with a single request. +This transfer uses TCP, unlike all other functions in the +.Nm ypclnt +suite, which use UDP. +The entire transaction occurs in a single RPC request-response. +The third argument to this function provides a way to supply +the name of a function to process each key-value pair in the map. +.Fn yp_all +returns after the entire transaction is complete, or the +.Pa foreach +function decides that it does not want any more key-value pairs. +The third argument to +.Fn yp_all +is: +.Bd -literal -offset indent +struct ypall_callback *incallback { + int (*foreach)(); + char *data; +}; +.Ed +.Pp +The +.Em char *data +argument is an opaque pointer for use by the callback function. +The +.Pa foreach +function should return non-zero when it no longer wishes to process +key-value pairs, at which time +.Fn yp_all +returns a value of 0, and is called with the following arguments: +.Bd -literal -offset indent +int foreach ( + int instatus, + char *inkey, + int inkeylen, + char *inval, + int invallen, + char *indata +); +.Ed +.Pp +Where: +.Bl -tag -width "inkey, inval" +.It Fa instatus +Holds one of the return status values described in +.In rpcsvc/yp_prot.h : +see +.Fn ypprot_err +below for a function that will translate YP protocol errors into a +.Nm ypclnt +layer error code as described in +.In rpcsvc/ypclnt.h . +.It Fa inkey , inval +The key and value arguments are somewhat different here than described +above. +In this case, the memory pointed to by +.Fa inkey +and +.Fa inval +is private to +.Fn yp_all , +and is overwritten with each subsequent key-value pair, thus the +.Pa foreach +function should do something useful with the contents of that memory during +each iteration. +If the key-value pairs are not terminated with either +.Ql \en +or +.Ql \e0 +in the map, then they will not be terminated as such when given to the +.Pa foreach +function, either. +.It Fa indata +This is the contents of the +.Pa incallback->data +element of the callback structure. +It is provided as a means to share state between the +.Pa foreach +function and the user code. +Its use is completely optional: cast it to +something useful or simply ignore it. +.El +.It Fn yp_order +Returns the order number for a map. +.It Fn yp_master +Returns the hostname for the machine on which the master YP server process for +a map is running. +.It Fn yperr_string +Returns a pointer to a NUL-terminated error string that does not contain a +.Ql \&. +or +.Ql \en . +.It Fn ypprot_err +Converts a YP protocol error code to a +.Nm ypclnt +error code suitable for +.Fn yperr_string . +.It Fn yp_setbindtries +Set the number of tries to attempt to bind to the domain before returning +an error. +The default is +.Dv 0 +which means wait forever if no ypserver is not found of if the RPC +communication with the yp server fails. +If the number passed is negative, the current number of tries is not modified. +.Pp +This function is an extension to the client library that allows an application +to catch communication problems with the ypserver without blocking forever. +.El +.Sh RETURN VALUES +All functions in the +.Nm ypclnt +suite which are of type +.Em int +return 0 upon success or one of the following error codes upon failure: +.Bl -tag -width "YPERR_BADARGS " +.It Bq Er YPERR_BADARGS +The passed arguments to the function are invalid. +.It Bq Er YPERR_BADDB +The YP map that was polled is defective. +.It Bq Er YPERR_BIND +Cannot communicate with +.Xr ypbind 8 . +.It Bq Er YPERR_DOM +The local YP domain is not set. +.It Bq Er YPERR_DOMAIN +Client process cannot bind to server on this YP domain. +.It Bq Er YPERR_KEY +The key passed does not exist. +.It Bq Er YPERR_MAP +There is no such map in the server's domain. +.It Bq Er YPERR_NOMORE +There are no more records in the queried map. +.It Bq Er YPERR_PMAP +Cannot communicate with portmapper (see +.Xr rpcbind 8 ) . +.It Bq Er YPERR_RESRC +A resource allocation failure occurred. +.It Bq Er YPERR_RPC +An RPC failure has occurred. +The domain has been marked unbound. +.It Bq Er YPERR_VERS +Client/server version mismatch. +If the server is running version 1 of the YP protocol, +.Fn yp_all +functionality does not exist. +.It Bq Er YPERR_YPERR +An internal server or client error has occurred. +.It Bq Er YPERR_YPSERV +The client cannot communicate with the YP server process. +.El +.Sh SEE ALSO +.Xr malloc 3 , +.Xr yp 8 , +.Xr ypbind 8 , +.Xr ypserv 8 +.Sh AUTHORS +.An Theo De Raadt diff --git a/static/netbsd/man3/zlib.3 b/static/netbsd/man3/zlib.3 new file mode 100644 index 00000000..c716020e --- /dev/null +++ b/static/netbsd/man3/zlib.3 @@ -0,0 +1,149 @@ +.TH ZLIB 3 "22 Jan 2024" +.SH NAME +zlib \- compression/decompression library +.SH SYNOPSIS +[see +.I zlib.h +for full description] +.SH DESCRIPTION +The +.I zlib +library is a general purpose data compression library. +The code is thread safe, assuming that the standard library functions +used are thread safe, such as memory allocation routines. +It provides in-memory compression and decompression functions, +including integrity checks of the uncompressed data. +This version of the library supports only one compression method (deflation) +but other algorithms may be added later +with the same stream interface. +.LP +Compression can be done in a single step if the buffers are large enough +or can be done by repeated calls of the compression function. +In the latter case, +the application must provide more input and/or consume the output +(providing more output space) before each call. +.LP +The library also supports reading and writing files in +.IR gzip (1) +(.gz) format +with an interface similar to that of stdio. +.LP +The library does not install any signal handler. +The decoder checks the consistency of the compressed data, +so the library should never crash even in the case of corrupted input. +.LP +All functions of the compression library are documented in the file +.IR zlib.h . +The distribution source includes examples of use of the library +in the files +.I test/example.c +and +.IR test/minigzip.c, +as well as other examples in the +.IR examples/ +directory. +.LP +Changes to this version are documented in the file +.I ChangeLog +that accompanies the source. +.LP +.I zlib +is built in to many languages and operating systems, including but not limited to +Java, Python, .NET, PHP, Perl, Ruby, Swift, and Go. +.LP +An experimental package to read and write files in the .zip format, +written on top of +.I zlib +by Gilles Vollant (info@winimage.com), +is available at: +.IP +http://www.winimage.com/zLibDll/minizip.html +and also in the +.I contrib/minizip +directory of the main +.I zlib +source distribution. +.SH "SEE ALSO" +The +.I zlib +web site can be found at: +.IP +http://zlib.net/ +.LP +The data format used by the +.I zlib +library is described by RFC +(Request for Comments) 1950 to 1952 in the files: +.IP +http://tools.ietf.org/html/rfc1950 (for the zlib header and trailer format) +.br +http://tools.ietf.org/html/rfc1951 (for the deflate compressed data format) +.br +http://tools.ietf.org/html/rfc1952 (for the gzip header and trailer format) +.LP +Mark Nelson wrote an article about +.I zlib +for the Jan. 1997 issue of Dr. Dobb's Journal; +a copy of the article is available at: +.IP +http://marknelson.us/1997/01/01/zlib-engine/ +.SH "REPORTING PROBLEMS" +Before reporting a problem, +please check the +.I zlib +web site to verify that you have the latest version of +.IR zlib ; +otherwise, +obtain the latest version and see if the problem still exists. +Please read the +.I zlib +FAQ at: +.IP +http://zlib.net/zlib_faq.html +.LP +before asking for help. +Send questions and/or comments to zlib@gzip.org, +or (for the Windows DLL version) to Gilles Vollant (info@winimage.com). +.SH AUTHORS AND LICENSE +Version 1.3.1 +.LP +Copyright (C) 1995-2024 Jean-loup Gailly and Mark Adler +.LP +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. +.LP +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: +.LP +.nr step 1 1 +.IP \n[step]. 3 +The origin of this software must not be misrepresented; you must not +claim that you wrote the original software. If you use this software +in a product, an acknowledgment in the product documentation would be +appreciated but is not required. +.IP \n+[step]. +Altered source versions must be plainly marked as such, and must not be +misrepresented as being the original software. +.IP \n+[step]. +This notice may not be removed or altered from any source distribution. +.LP +Jean-loup Gailly Mark Adler +.br +jloup@gzip.org madler@alumni.caltech.edu +.LP +The deflate format used by +.I zlib +was defined by Phil Katz. +The deflate and +.I zlib +specifications were written by L. Peter Deutsch. +Thanks to all the people who reported problems and suggested various +improvements in +.IR zlib ; +who are too numerous to cite here. +.LP +UNIX manual page by R. P. C. Rodgers, +U.S. National Library of Medicine (rodgers@nlm.nih.gov). +.\" end of man page diff --git a/static/netbsd/man3/zopen.3 b/static/netbsd/man3/zopen.3 new file mode 100644 index 00000000..32be9c4c --- /dev/null +++ b/static/netbsd/man3/zopen.3 @@ -0,0 +1,138 @@ +.\" $NetBSD: zopen.3,v 1.7 2003/08/07 11:13:29 agc Exp $ +.\" +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)zopen.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd June 9, 1993 +.Dt ZOPEN 3 +.Os +.Sh NAME +.Nm zopen +.Nd compressed stream open function +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn zopen "const char *path" "const char *mode" "int bits" +.Sh DESCRIPTION +The +.Fn zopen +function +opens the compressed file whose name is the string pointed to by +.Fa path +and associates a stream with it. +.Pp +The argument +.Fa mode +points to one of the following one-character strings: +.Bl -tag -width indent +.It Dq Li r +Open compressed file for reading. +The stream is positioned at the beginning of the file. +.It Dq Li w +Truncate file to zero length or create compressed file for writing. +The stream is positioned at the beginning of the file. +.El +.Pp +Any created files will have mode +.Pf \\*q Dv S_IRUSR +\&| +.Dv S_IWUSR +\&| +.Dv S_IRGRP +\&| +.Dv S_IWGRP +\&| +.Dv S_IROTH +\&| +.Dv S_IWOTH Ns \\*q +.Pq Li 0666 , +as modified by the process' +umask value (see +.Xr umask 2 ) . +.Pp +Files may only be read or written. +Seek operations are not allowed. +.Pp +The +.Fa bits +argument, if non-zero, is set to the bits code limit. +If zero, the default is 16. +See +.Fn compress 1 +for more information. +.Sh RETURN VALUES +Upon successful completion +.Fn zopen +returns a +.Tn FILE +pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width [EINVAL] +.It Bq Er EINVAL +The +.Fa mode +or +.Fa bits +arguments specified to +.Fn zopen +were invalid. +.It Bq Er EFTYPE +The compressed file starts with an invalid header, or the compressed +file is compressed with more bits than can be handled. +.El +.Pp +The +.Fn zopen +function may also fail and set +.Va errno +for any of the errors specified for the routines +.Xr fopen 3 +or +.Xr funopen 3 . +.Sh SEE ALSO +.Xr compress 1 , +.Xr fopen 3 , +.Xr funopen 3 +.Sh HISTORY +The +.Nm zopen +function +first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn zopen +function +may not be portable to systems other than +.Bx . -- cgit v1.2.3